CRISTAL-326: Missing tooltip and hints for the create page UI (#684)

* Introduce NavigationTreeSelect as a new form component * Add help text to TextField component * Improve form styling for Vuetify * Update hierarchy API to use EntityReferences instead of PageData * Update navigation tree API to use EntityReferences instead of PageData * Update document change API to use EntityReferences instead of PageData * Improve buttons behavior on form modals * Overall style uniformization for existing forms * Add Select button to tree select
xwiki-contrib · Feb 20, 2025 · 93955fa · 93955fa
1 parent 8133dc7
commit 93955fa
Show file tree

Hide file tree

Showing 62 changed files with 698 additions and 256 deletions.
diff --git a/core/document/document-api/src/index.ts b/core/document/document-api/src/index.ts
@@ -101,21 +101,24 @@ interface DocumentService {
    * made on the whole Cristal instance.
    * @param change - the kind of change
    * @param listener - the listener to register
-   * @since 0.12
+   * @since 0.15
    */
   registerDocumentChangeListener(
     change: DocumentChange,
-    listener: (page: PageData) => Promise<void>,
+    listener: (page: DocumentReference) => Promise<void>,
   ): void;
 
   /**
    * Notify that a document change happened. This will execute all registered
    * listeners for the given kind of change.
    * @param change - the kind of change
-   * @param page - the document changed
-   * @since 0.12
+   * @param page - the reference to the changed document
+   * @since 0.15
    */
-  notifyDocumentChange(change: DocumentChange, page: PageData): Promise<void>;
+  notifyDocumentChange(
+    change: DocumentChange,
+    page: DocumentReference,
+  ): Promise<void>;
 }
 
 const name: string = "DocumentService";

diff --git a/core/document/document-default/src/defaultDocumentService.ts b/core/document/document-default/src/defaultDocumentService.ts
@@ -187,7 +187,7 @@ export class DefaultDocumentService implements DocumentService {
   private readonly store: DocumentStore;
   private readonly documentChangeListeners: Map<
     DocumentChange,
-    Array<(page: PageData) => Promise<void>>
+    Array<(page: DocumentReference) => Promise<void>>
   > = new Map();
 
   constructor(@inject("CristalApp") private cristal: CristalApp) {
@@ -242,7 +242,7 @@ export class DefaultDocumentService implements DocumentService {
 
   registerDocumentChangeListener(
     change: DocumentChange,
-    listener: (page: PageData) => Promise<void>,
+    listener: (page: DocumentReference) => Promise<void>,
   ): void {
     if (this.documentChangeListeners.has(change)) {
       this.documentChangeListeners.get(change)!.push(listener);
@@ -253,7 +253,7 @@ export class DefaultDocumentService implements DocumentService {
 
   async notifyDocumentChange(
     change: DocumentChange,
-    page: PageData,
+    page: DocumentReference,
   ): Promise<void> {
     if (this.documentChangeListeners.has(change)) {
       await Promise.all(

diff --git a/core/hierarchy/hierarchy-api/package.json b/core/hierarchy/hierarchy-api/package.json
@@ -23,7 +23,8 @@
     "test": "vitest --run"
   },
   "dependencies": {
-    "@xwiki/cristal-api": "workspace:*"
+    "@xwiki/cristal-api": "workspace:*",
+    "@xwiki/cristal-model-api": "workspace:*"
   },
   "devDependencies": {
     "@xwiki/cristal-dev-config": "workspace:*",

diff --git a/core/hierarchy/hierarchy-api/src/index.ts b/core/hierarchy/hierarchy-api/src/index.ts
@@ -18,7 +18,10 @@
  * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
  */
 
-import type { PageData } from "@xwiki/cristal-api";
+import type {
+  DocumentReference,
+  SpaceReference,
+} from "@xwiki/cristal-model-api";
 
 /**
  * Description of a hierarchy item for a given page.
@@ -39,10 +42,13 @@ interface PageHierarchyResolver {
   /**
    * Returns the page hierarchy for a given page.
    *
-   * @param pageData - the page for which to compute the hierarchy
+   * @param page - the reference to the page for which to compute the hierarchy
    * @returns the page hierarchy
+   * @since 0.15
    */
-  getPageHierarchy(pageData: PageData): Promise<Array<PageHierarchyItem>>;
+  getPageHierarchy(
+    page: DocumentReference | SpaceReference,
+  ): Promise<Array<PageHierarchyItem>>;
 }
 
 /**

diff --git a/core/hierarchy/hierarchy-default/package.json b/core/hierarchy/hierarchy-default/package.json
@@ -25,6 +25,7 @@
   "dependencies": {
     "@xwiki/cristal-api": "workspace:*",
     "@xwiki/cristal-hierarchy-api": "workspace:*",
+    "@xwiki/cristal-model-api": "workspace:*",
     "inversify": "6.2.2"
   },
   "peerDependencies": {

diff --git a/core/hierarchy/hierarchy-default/src/components/componentsInit.ts b/core/hierarchy/hierarchy-default/src/components/componentsInit.ts
@@ -19,13 +19,18 @@
  */
 
 import { name as PageHierarchyResolverName } from "@xwiki/cristal-hierarchy-api";
+import { EntityType } from "@xwiki/cristal-model-api";
 import { Container, inject, injectable } from "inversify";
-import type { CristalApp, Logger, PageData } from "@xwiki/cristal-api";
+import type { CristalApp, Logger } from "@xwiki/cristal-api";
 import type {
   PageHierarchyItem,
   PageHierarchyResolver,
   PageHierarchyResolverProvider,
 } from "@xwiki/cristal-hierarchy-api";
+import type {
+  DocumentReference,
+  SpaceReference,
+} from "@xwiki/cristal-model-api";
 
 /**
  * Default implementation for PageHierarchyResolver.
@@ -48,7 +53,7 @@ class DefaultPageHierarchyResolver implements PageHierarchyResolver {
   }
 
   async getPageHierarchy(
-    pageData: PageData,
+    page: DocumentReference | SpaceReference,
   ): Promise<Array<PageHierarchyItem>> {
     const hierarchy: Array<PageHierarchyItem> = [
       {
@@ -60,9 +65,9 @@ class DefaultPageHierarchyResolver implements PageHierarchyResolver {
         }).href,
       },
     ];
-    if (pageData != null) {
+    if (page.type == EntityType.DOCUMENT) {
       hierarchy.push({
-        label: pageData.name,
+        label: (page as DocumentReference).name,
         pageId: this.cristalApp.getCurrentPage(),
         url: window.location.href,
       });

diff --git a/core/hierarchy/hierarchy-default/src/utils.ts b/core/hierarchy/hierarchy-default/src/utils.ts
@@ -18,37 +18,46 @@
  * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
  */
 
+import { EntityType } from "@xwiki/cristal-model-api";
 import type { CristalApp, PageData } from "@xwiki/cristal-api";
 import type { PageHierarchyItem } from "@xwiki/cristal-hierarchy-api";
+import type {
+  DocumentReference,
+  SpaceReference,
+} from "@xwiki/cristal-model-api";
 
 /**
  * Returns the page hierarchy for a path-like page id.
  * This does not include a Home segment.
  *
- * @param pageData - the data of the page
+ * @param page - the reference to the page
  * @param cristalApp - the current app
  * @returns the page hierarchy
- * @since 0.10
+ * @since 0.15
  **/
 // TODO: reduce the number of statements in the following method and reactivate the disabled eslint rule.
 // eslint-disable-next-line max-statements
 export async function getPageHierarchyFromPath(
-  pageData: PageData,
+  page: DocumentReference | SpaceReference,
   cristalApp: CristalApp,
 ): Promise<Array<PageHierarchyItem>> {
   const hierarchy: Array<PageHierarchyItem> = [];
-  const fileHierarchy = pageData.id.split("/");
+  const fileHierarchy = [];
+  if (page.type == EntityType.SPACE) {
+    fileHierarchy.push(...(page as SpaceReference).names);
+  } else if (page.type == EntityType.DOCUMENT) {
+    fileHierarchy.push(
+      ...(page as DocumentReference).space!.names,
+      (page as DocumentReference).name,
+    );
+  }
   let currentFile = "";
 
   for (let i = 0; i < fileHierarchy.length; i++) {
     const file = fileHierarchy[i];
     currentFile += `${i == 0 ? "" : "/"}${file}`;
-    let currentPageData: PageData | undefined;
-    if (i == fileHierarchy.length - 1) {
-      currentPageData = pageData;
-    } else {
-      currentPageData = await cristalApp.getPage(currentFile);
-    }
+    const currentPageData: PageData | undefined =
+      await cristalApp.getPage(currentFile);
     hierarchy.push({
       label: currentPageData?.name ? currentPageData.name : file,
       pageId: currentFile,

diff --git a/core/hierarchy/hierarchy-filesystem/package.json b/core/hierarchy/hierarchy-filesystem/package.json
@@ -26,6 +26,7 @@
     "@xwiki/cristal-api": "workspace:*",
     "@xwiki/cristal-hierarchy-api": "workspace:*",
     "@xwiki/cristal-hierarchy-default": "workspace:*",
+    "@xwiki/cristal-model-api": "workspace:*",
     "inversify": "6.2.2"
   },
   "peerDependencies": {

diff --git a/core/hierarchy/hierarchy-filesystem/src/components/componentsInit.ts b/core/hierarchy/hierarchy-filesystem/src/components/componentsInit.ts
@@ -21,11 +21,15 @@
 import { name } from "@xwiki/cristal-hierarchy-api";
 import { getPageHierarchyFromPath } from "@xwiki/cristal-hierarchy-default";
 import { Container, inject, injectable } from "inversify";
-import type { CristalApp, Logger, PageData } from "@xwiki/cristal-api";
+import type { CristalApp, Logger } from "@xwiki/cristal-api";
 import type {
   PageHierarchyItem,
   PageHierarchyResolver,
 } from "@xwiki/cristal-hierarchy-api";
+import type {
+  DocumentReference,
+  SpaceReference,
+} from "@xwiki/cristal-model-api";
 
 /**
  * Implementation of PageHierarchyResolver for the FileSystem backend.
@@ -49,7 +53,7 @@ class FileSystemPageHierarchyResolver implements PageHierarchyResolver {
   }
 
   async getPageHierarchy(
-    pageData: PageData,
+    page: DocumentReference | SpaceReference,
   ): Promise<Array<PageHierarchyItem>> {
     let hierarchy: Array<PageHierarchyItem> = [
       {
@@ -61,9 +65,9 @@ class FileSystemPageHierarchyResolver implements PageHierarchyResolver {
         }).href,
       },
     ];
-    if (pageData != null) {
+    if (page != null) {
       hierarchy = hierarchy.concat(
-        await getPageHierarchyFromPath(pageData, this.cristalApp),
+        await getPageHierarchyFromPath(page, this.cristalApp),
       );
     }
     return hierarchy;

diff --git a/core/hierarchy/hierarchy-github/package.json b/core/hierarchy/hierarchy-github/package.json
@@ -25,6 +25,7 @@
   "dependencies": {
     "@xwiki/cristal-api": "workspace:*",
     "@xwiki/cristal-hierarchy-api": "workspace:*",
+    "@xwiki/cristal-model-api": "workspace:*",
     "inversify": "6.2.2"
   },
   "peerDependencies": {

diff --git a/core/hierarchy/hierarchy-github/src/components/componentsInit.ts b/core/hierarchy/hierarchy-github/src/components/componentsInit.ts
@@ -19,12 +19,17 @@
  */
 
 import { name } from "@xwiki/cristal-hierarchy-api";
+import { EntityType } from "@xwiki/cristal-model-api";
 import { Container, inject, injectable } from "inversify";
-import type { CristalApp, Logger, PageData } from "@xwiki/cristal-api";
+import type { CristalApp, Logger } from "@xwiki/cristal-api";
 import type {
   PageHierarchyItem,
   PageHierarchyResolver,
 } from "@xwiki/cristal-hierarchy-api";
+import type {
+  DocumentReference,
+  SpaceReference,
+} from "@xwiki/cristal-model-api";
 
 /**
  * Implementation of PageHierarchyResolver for the GitHub backend.
@@ -46,7 +51,7 @@ class GitHubPageHierarchyResolver implements PageHierarchyResolver {
   }
 
   async getPageHierarchy(
-    pageData: PageData,
+    page: DocumentReference | SpaceReference,
   ): Promise<Array<PageHierarchyItem>> {
     const hierarchy: Array<PageHierarchyItem> = [
       {
@@ -58,8 +63,14 @@ class GitHubPageHierarchyResolver implements PageHierarchyResolver {
         }).href,
       },
     ];
-    if (pageData != null) {
-      const fileHierarchy = pageData.id.split("/");
+    if (page != null) {
+      const fileHierarchy =
+        page.type == EntityType.SPACE
+          ? [...(page as SpaceReference).names]
+          : [
+              ...(page as DocumentReference).space!.names,
+              (page as DocumentReference).name,
+            ];
       let currentFile = "";
       for (let i = 0; i < fileHierarchy.length; i++) {
         const file = fileHierarchy[i];

diff --git a/core/hierarchy/hierarchy-nextcloud/package.json b/core/hierarchy/hierarchy-nextcloud/package.json
@@ -26,6 +26,7 @@
     "@xwiki/cristal-api": "workspace:*",
     "@xwiki/cristal-hierarchy-api": "workspace:*",
     "@xwiki/cristal-hierarchy-default": "workspace:*",
+    "@xwiki/cristal-model-api": "workspace:*",
     "inversify": "6.2.2"
   },
   "peerDependencies": {

diff --git a/core/hierarchy/hierarchy-nextcloud/src/components/componentsInit.ts b/core/hierarchy/hierarchy-nextcloud/src/components/componentsInit.ts
@@ -21,11 +21,15 @@
 import { name } from "@xwiki/cristal-hierarchy-api";
 import { getPageHierarchyFromPath } from "@xwiki/cristal-hierarchy-default";
 import { Container, inject, injectable } from "inversify";
-import type { CristalApp, Logger, PageData } from "@xwiki/cristal-api";
+import type { CristalApp, Logger } from "@xwiki/cristal-api";
 import type {
   PageHierarchyItem,
   PageHierarchyResolver,
 } from "@xwiki/cristal-hierarchy-api";
+import type {
+  DocumentReference,
+  SpaceReference,
+} from "@xwiki/cristal-model-api";
 
 /**
  * Implementation of PageHierarchyResolver for Nextcloud backend.
@@ -47,7 +51,7 @@ class NextcloudPageHierarchyResolver implements PageHierarchyResolver {
   }
 
   async getPageHierarchy(
-    pageData: PageData,
+    page: DocumentReference | SpaceReference,
   ): Promise<Array<PageHierarchyItem>> {
     let hierarchy: Array<PageHierarchyItem> = [
       {
@@ -59,9 +63,9 @@ class NextcloudPageHierarchyResolver implements PageHierarchyResolver {
         }).href,
       },
     ];
-    if (pageData != null) {
+    if (page != null) {
       hierarchy = hierarchy.concat(
-        await getPageHierarchyFromPath(pageData, this.cristalApp),
+        await getPageHierarchyFromPath(page, this.cristalApp),
       );
     }
     return hierarchy;

diff --git a/core/hierarchy/hierarchy-xwiki/src/components/componentsInit.ts b/core/hierarchy/hierarchy-xwiki/src/components/componentsInit.ts
@@ -19,16 +19,20 @@
  */
 
 import { name } from "@xwiki/cristal-hierarchy-api";
+import { EntityType } from "@xwiki/cristal-model-api";
 import { getRestSpacesApiUrl } from "@xwiki/cristal-xwiki-utils";
 import { Container, inject, injectable, named } from "inversify";
-import type { CristalApp, Logger, PageData } from "@xwiki/cristal-api";
+import type { CristalApp, Logger } from "@xwiki/cristal-api";
 import type { AuthenticationManagerProvider } from "@xwiki/cristal-authentication-api";
 import type { StorageProvider } from "@xwiki/cristal-backend-api";
 import type {
   PageHierarchyItem,
   PageHierarchyResolver,
 } from "@xwiki/cristal-hierarchy-api";
-import type { DocumentReference } from "@xwiki/cristal-model-api";
+import type {
+  DocumentReference,
+  SpaceReference,
+} from "@xwiki/cristal-model-api";
 import type { ModelReferenceSerializer } from "@xwiki/cristal-model-reference-api";
 import type { RemoteURLParser } from "@xwiki/cristal-model-remote-url-api";
 
@@ -61,14 +65,11 @@ class XWikiPageHierarchyResolver implements PageHierarchyResolver {
   // TODO: reduce the number of statements in the following method and reactivate the disabled eslint rule.
   // eslint-disable-next-line max-statements
   async getPageHierarchy(
-    pageData: PageData,
+    page: DocumentReference | SpaceReference,
   ): Promise<Array<PageHierarchyItem>> {
-    const documentId = pageData.document.getIdentifier();
-    if (documentId == null) {
-      this.logger.debug(
-        `No identifier found for page ${pageData.name}, falling back to default hierarchy resolver.`,
-      );
-      return this.defaultHierarchyResolver.getPageHierarchy(pageData);
+    let documentId = this.referenceSerializer.serialize(page)!;
+    if (page.type == EntityType.SPACE) {
+      documentId += ".WebHome";
     }
     // TODO: support subwikis.
     const restApiUrl = getRestSpacesApiUrl(
@@ -121,9 +122,9 @@ class XWikiPageHierarchyResolver implements PageHierarchyResolver {
     } catch (error) {
       this.logger.error(error);
       this.logger.debug(
-        `Could not load hierarchy for page ${pageData.name}, falling back to default hierarchy resolver.`,
+        `Could not load hierarchy for page ${documentId}, falling back to default hierarchy resolver.`,
       );
-      return this.defaultHierarchyResolver.getPageHierarchy(pageData);
+      return this.defaultHierarchyResolver.getPageHierarchy(page);
     }
   }
 }