@ditojs/admin 3.2.6 → 3.3.0

package/types/index.d.ts

@@ -353,6 +353,10 @@ export interface BaseSchema<$Item>
    * context's component properties, e.g. `component`
    * and `schemaComponent`, refer to the form, view or
    * dialog that holds the data, not to the field.
+   *
+   * Reading `context.options` waits while the options
+   * load, and is `undefined` when the load fails or its
+   * data resolves to nothing, so use `options?.`.
    */
   compute?: ItemAccessor<$Item>
   /**
@@ -629,6 +633,9 @@ export interface SchemaSourceMixin<$Item> {
    * the default is the 'name' property of the item,
    * followed by the label of the form (plus item id)
    * and other defaults.
+   * Labels are HTML: Callbacks return HTML, and need to
+   * escape the item values that they include with
+   * `escapeHtml()` from `@ditojs/utils`.
    */
   itemLabel?:
     | OrItemAccessor<
@@ -850,7 +857,9 @@ export type SchemaOptions<$Item, $Option = any> =
        */
       value?: keyof $Option | ItemAccessor<$Item, { option: $Option }>
       /**
-       * The key of the option property which should used to group the options.
+       * @deprecated Not supported, the options are grouped by the `groupBy`
+       * setting of the component's schema, see
+       * {@link SchemaOptionsMixin.groupBy}.
        */
       groupBy?: keyof $Option
       /**
@@ -913,7 +922,9 @@ export interface SchemaOptionsMixin<$Item, $Option = any> {
   relateBy?: string
   /**
    * The key of the option property which should be used to
-   * group the options.
+   * group the options. Selects and multiselects show the groups
+   * in their dropdowns, radio buttons and checkboxes list each
+   * group in a fieldset with the group's name as its legend.
    */
   groupBy?: OrItemAccessor<$Item, {}, string>
   /**
@@ -942,7 +953,8 @@ export interface SchemaOptionsMixin<$Item, $Option = any> {
       }
   /**
    * Whether the selected option can be edited by navigating
-   * to it.
+   * to its form in the view of `view`. Radio buttons and checkboxes
+   * show an edit button for each of their options.
    */
   editable?: OrItemAccessor<$Item, {}, boolean>
   /**
@@ -1220,7 +1232,8 @@ export interface DateSchema<$Item = any>
     }
   >
   /**
-   * @deprecated Use `formats` instead.
+   * @deprecated Use `formats.date` instead. `dateFormat` is no longer read and
+   * has no effect.
    */
   dateFormat?: OrItemAccessor<$Item, {}, DateFormat>
 }
@@ -1924,9 +1937,10 @@ export type DitoContext<$Item = any> = {
    */
   itemDataPath: string
   /**
-   * Data path of the parent item ancestor.
+   * Data path of the parent item ancestor, `null` for
+   * root items.
    */
-  parentItemDataPath: string
+  parentItemDataPath: string | null
   /** Index of the closest item in its list. */
   itemIndex: number | null
   /** Index of the parent item in its list. */
@@ -1959,11 +1973,11 @@ export type DitoContext<$Item = any> = {
    * copy/paste operations.
    */
   clipboardItem: any
-  /** The currently authenticated user. */
+  /** The currently authenticated user, `null` when logged out. */
   user: {
     roles?: string[]
     hasRole(...roles: string[]): boolean
-  }
+  } | null
   /** The admin API configuration. */
   api: ApiConfig
   /** The schema definition for the current component. */
@@ -1972,8 +1986,16 @@ export type DitoContext<$Item = any> = {
   views: Record<string, View>
   /** All views flattened into a single record. */
   flattenedViews: Record<string, ViewSchema>
-  /** Display label of the current item. */
+  /**
+   * Display label of the current item, as HTML with
+   * escaped item values.
+   */
   itemLabel: string | null
+  /**
+   * The text of `itemLabel`, with its item values
+   * unescaped.
+   */
+  itemLabelText: string | null
   /** Display label of the current form. */
   formLabel: string | null
   /** The current Vue component instance. */
@@ -2071,25 +2093,55 @@ export type DitoContext<$Item = any> = {
   }
   /** Returns the full URL for a given resource. */
   getResourceUrl(resource: Resource): string
-  /** Displays a notification to the user. */
-  notify(options: {
-    /** Notification style. @defaultValue `'info'` */
-    type?: LiteralUnion<'warning' | 'error' | 'info' | 'success'>
-    /** Heading text. Defaults to a label matching `type`. */
-    title?: string
-    /** Body text, rendered as HTML paragraphs. */
-    text: OrArrayOf<string>
-    /**
-     * The original error object. When `type` is `'error'`,
-     * this is logged to the console alongside the message.
-     */
-    error?: unknown
-    /**
-     * Display duration in milliseconds. When omitted, calculated
-     * automatically from content length. Use `0` for sticky.
-     */
-    duration?: number
-  }): void
+  /**
+   * Displays a notification to the user, with the
+   * paragraphs of either `text` or `html`.
+   */
+  notify(
+    options: {
+      /** Notification style. @defaultValue `'info'` */
+      type?: LiteralUnion<'warning' | 'error' | 'info' | 'success'>
+      /**
+       * Heading text, escaped like `text`. Defaults to
+       * a label matching `type`.
+       */
+      title?: string
+      /**
+       * The original error object. When `type` is
+       * `'error'`, this is logged to the console
+       * alongside the message.
+       */
+      error?: unknown
+      /**
+       * Display duration in milliseconds. When omitted,
+       * calculated automatically from content length.
+       * Use `0` for sticky.
+       */
+      duration?: number
+    } & (
+      | {
+          /**
+           * Body text, escaped as plain text. Each entry
+           * is a paragraph, newlines become `<br>`, and
+           * `false` and `null` entries are skipped.
+           */
+          text: OrArrayOf<string | false | null>
+          html?: never
+        }
+      | {
+          /**
+           * Body HTML from trusted sources, rendered as
+           * it is. Every interpolated value must be
+           * escaped with `escapeHtml()` from
+           * `@ditojs/utils`. Each entry is a paragraph,
+           * newlines become `<br>`, and `false` and
+           * `null` entries are skipped.
+           */
+          html: OrArrayOf<string | false | null>
+          text?: never
+        }
+    )
+  ): void
 }
 
 /**
@@ -2169,16 +2221,6 @@ export interface DitoComponentInstanceBase<$Item = any>
   errors: string[] | null
   /** Whether the field has validation errors. */
   hasErrors: boolean
-  /** Whether async data is currently being loaded. */
-  isLoading: boolean
-  /**
-   * Sets the loading state. Optionally propagates
-   * to the root or view component.
-   */
-  setLoading(
-    isLoading: boolean,
-    options?: { updateRoot?: boolean; updateView?: boolean }
-  ): void
   /**
    * Whether the component works with data not yet
    * persisted to the server.
@@ -2256,7 +2298,7 @@ export interface DitoComponentInstanceBase<$Item = any>
   /** The parent form component. */
   parentFormComponent: DitoComponentInstanceBase | null
   /** The root component instance. */
-  rootComponent: DitoComponentInstanceBase | null
+  rootComponent: DitoRootInstance | null
   /** The nearest ancestor tab component. */
   tabComponent: DitoComponentInstanceBase | null
   /** The parent route component. */
@@ -2485,8 +2527,63 @@ export interface EmitterMixin {
   ): this
 }
 
+/**
+ * Counts the pending operations of a scope, e.g. the
+ * requests of a resource component, of all components
+ * in a view, or of the whole admin, and forwards them
+ * to the tracker of the enclosing scope.
+ */
+export interface LoadingTracker {
+  /** The tracker of the enclosing scope, if any. */
+  readonly parent: LoadingTracker | null
+  /** The tracker of the outermost scope. */
+  readonly root: LoadingTracker
+  /** Whether any operation within the scope is pending. */
+  readonly isLoading: boolean
+  /**
+   * Begins an operation in this scope and its enclosing
+   * ones, and returns the function that ends it.
+   */
+  begin(): () => void
+  /**
+   * Tracks the operation that `callback()` performs until
+   * its returned promise settles, and returns its result.
+   */
+  track<T>(callback: () => T | Promise<T>): Promise<T>
+}
+
+/**
+ * The members of components that load and submit their
+ * data through API resources (ResourceMixin): forms and
+ * sources.
+ */
+export interface DitoResourceInstance {
+  /**
+   * Whether any request or other operation within this
+   * component's scope is pending, as tracked by its
+   * `LoadingTracker`.
+   */
+  readonly isLoading: boolean
+  /** Tracks the pending requests of the component. */
+  readonly loadingTracker: LoadingTracker
+  /**
+   * Begins or ends a loading operation of the component.
+   * The options are ignored, since the operations are
+   * always forwarded to the enclosing view and the root.
+   *
+   * @deprecated Use `loadingTracker.begin()` and call the
+   * function that it returns, or
+   * `loadingTracker.track(callback)` instead.
+   */
+  setLoading(
+    isLoading: boolean,
+    options?: { updateRoot?: boolean; updateView?: boolean }
+  ): void
+}
+
 export interface DitoFormInstance<$Item = any>
-  extends DitoComponentInstanceBase<$Item> {
+  extends DitoComponentInstanceBase<$Item>,
+    DitoResourceInstance {
   /**
    * Whether this form is creating a new item
    * (`true`) or editing an existing one (`false`).
@@ -2645,10 +2742,38 @@ export interface DitoFormInstance<$Item = any>
   getChildPath(path: string): string
 }
 
+/** The root component of the admin (DitoRoot). */
+export interface DitoRootInstance extends DitoComponentInstanceBase {
+  /**
+   * Whether any request or other operation within the
+   * admin is pending, as tracked by its `LoadingTracker`.
+   */
+  readonly isLoading: boolean
+  /** Tracks the pending requests of the whole admin. */
+  readonly loadingTracker: LoadingTracker
+}
+
 export interface DitoViewInstance<$Item = any>
   extends DitoComponentInstanceBase<$Item> {
   /** Always `true` for view components. */
   isView: true
+  /**
+   * Whether any request or other operation within the
+   * view, e.g. of its components, is pending, as
+   * tracked by its `LoadingTracker`. The view is
+   * disabled while it is loading.
+   */
+  readonly isLoading: boolean
+  /** Tracks the pending requests of the view's components. */
+  readonly loadingTracker: LoadingTracker
+  /**
+   * Begins or ends a loading operation of the view.
+   *
+   * @deprecated Use `loadingTracker.begin()` and call the
+   * function that it returns, or
+   * `loadingTracker.track(callback)` instead.
+   */
+  setLoading(isLoading: boolean): void
 
   // -- Route (RouteMixin) --
 
@@ -2767,7 +2892,8 @@ export interface DitoSchemaInstance<$Item = any>
 }
 
 export interface DitoSourceInstance<$Item = any>
-  extends DitoComponentInstanceBase<$Item> {
+  extends DitoComponentInstanceBase<$Item>,
+    DitoResourceInstance {
   // -- Data access (SourceMixin) --
 
   /** The list data array (getter/setter). */
@@ -3465,6 +3591,7 @@ export type SchemaByType<$Item = any> = {
   'url': InputSchema<$Item>
   'label': LabelSchema<$Item>
   'section': SectionSchema<$Item>
+  'panel': PanelSchema<$Item>
   'hidden': HiddenSchema<$Item>
   'unknown': never
 }

package/src/mixins/LoadingMixin.js

@@ -1,23 +0,0 @@
-// @vue/component
-export default {
-  data() {
-    return {
-      isLoading: false
-    }
-  },
-
-  methods: {
-    setLoading(isLoading, { updateRoot = false, updateView = false } = {}) {
-      if (!this.isLoading ^ !isLoading) {
-        // Boolean xor
-        this.isLoading = !!isLoading
-        if (updateRoot) {
-          this.rootComponent.registerLoading(isLoading)
-        }
-        if (updateView) {
-          this.viewComponent.setLoading(this.isLoading)
-        }
-      }
-    }
-  }
-}

package/src/mixins/PulldownMixin.js

@@ -1,72 +0,0 @@
-import DomMixin from './DomMixin.js'
-
-// @vue/component
-export default {
-  mixins: [DomMixin],
-
-  data() {
-    return {
-      pulldown: {
-        open: false,
-        startTime: 0,
-        checkTime: true,
-        events: {
-          mousedown: () => {
-            this.setPulldownOpen(false)
-            this.pulldown.handlers.remove()
-          },
-
-          mouseup: () => {
-            if (this.onPulldownMouseUp()) {
-              this.pulldown.handlers.remove()
-            }
-          }
-        },
-        handlers: null
-      }
-    }
-  },
-
-  computed: {
-    pulldownTriggerAttributes() {
-      return {
-        'aria-haspopup': 'menu',
-        'aria-expanded': this.pulldown.open
-      }
-    }
-  },
-
-  methods: {
-    onPulldownMouseDown(value = null) {
-      if (value === null) {
-        this.setPulldownOpen(true)
-        this.checkTime = true
-      } else {
-        this.checkTime = false
-      }
-    },
-
-    onPulldownMouseUp(value = null) {
-      const { startTime } = this.pulldown
-      if (!this.checkTime || startTime && (Date.now() - startTime > 250)) {
-        this.setPulldownOpen(false)
-        if (value !== null) {
-          this.onPulldownSelect(value)
-        }
-        return true
-      }
-    },
-
-    onPulldownSelect(/* value */) {
-      // NOTE: To be overridden.
-    },
-
-    setPulldownOpen(open) {
-      this.pulldown.open = open
-      this.pulldown.startTime = open ? Date.now() : 0
-      if (open) {
-        this.pulldown.handlers = this.domOn(document, this.pulldown.events)
-      }
-    }
-  }
-}

package/src/styles/_pulldown.scss

@@ -1,38 +0,0 @@
-@import '../styles/_imports';
-
-.dito-pulldown {
-  $self: &;
-
-  display: none;
-  position: absolute;
-  top: 0;
-  z-index: $z-index-popup;
-  border-radius: $pulldown-radius;
-  box-shadow: $shadow-window;
-  overflow: hidden;
-
-  &--open {
-    display: block;
-  }
-
-  li {
-    @include user-select(none);
-  }
-
-  &__item {
-    display: block;
-    padding: $pulldown-padding;
-    line-height: 1;
-    background: $button-color;
-
-    &--disabled {
-      color: $color-disabled;
-      cursor: default;
-    }
-
-    &:not(&--disabled):hover {
-      background: $color-active;
-      color: $color-white;
-    }
-  }
-}