@ditojs/admin 3.2.7 → 3.3.0

package/src/utils/schema/lookup.js

@@ -10,6 +10,7 @@ import { reactive, computed } from 'vue'
 import { getTypeOptions } from './types.js'
 import {
   findNestedSchemaComponent,
+  isMenu,
   isSchema,
   isSingleComponentView
 } from './structure.js'
@@ -72,6 +73,14 @@ export function getViewPath(schema, context) {
   return null
 }
 
+// Returns the path that links to the view or menu `schema`, displayed at
+// `path`: Menus link to their first item.
+export function getViewLinkPath(schema, path = schema.fullPath) {
+  return isMenu(schema)
+    ? Object.values(schema.items)[0].fullPath
+    : path
+}
+
 export function getViewEditPath(schema, id, context) {
   const path = getViewPath(schema, context)
   return path ? `${path}/${id}` : null
@@ -125,14 +134,19 @@ function getFormWithCreatedComponents(form, context) {
     formsByItem = new WeakMap()
     formsByComponentsCallback.set(form.components, formsByItem)
   }
-  let formWithCreatedComponents = formsByItem.get(item)
-  if (!formWithCreatedComponents) {
-    formWithCreatedComponents = computed(() =>
-      createFormWithComponents(form, context)
+  let entry = formsByItem.get(item)
+  if (!entry) {
+    entry = { context }
+    entry.formWithCreatedComponents = computed(() =>
+      createFormWithComponents(form, entry.context)
     )
-    formsByItem.set(item, formWithCreatedComponents)
+    formsByItem.set(item, entry)
   }
-  return formWithCreatedComponents.value
+  // Recreate the components with the latest context rather than the one of
+  // the first caller, whose component may have been unmounted since. Changes
+  // of the context alone don't recreate them, see above.
+  entry.context = context
+  return entry.formWithCreatedComponents.value
 }
 
 function createFormWithComponents(form, context) {
@@ -214,16 +228,27 @@ export function getButtonSchemas(buttons) {
 }
 
 // Returns the entry of the panel described by `schema`, which `DitoPanels`
-// displays at `dataPath` and `componentPath`.
-function getPanelEntry(schema, dataPath, componentPath, tabComponent) {
-  return schema ? { schema, dataPath, componentPath, tabComponent } : null
+// displays at `dataPath` and `componentPath`. Panels of components in tabs are
+// only displayed while their tab is selected: `tab` describes that tab as
+// `{ tabName, isTabSelected }`, where `isTabSelected()` tells if it currently
+// is, see `DitoPane.panelTab`.
+function getPanelEntry(schema, dataPath, componentPath, tab) {
+  return schema
+    ? {
+        schema,
+        dataPath,
+        componentPath,
+        tabName: tab?.tabName ?? null,
+        isTabSelected: tab?.isTabSelected ?? null
+      }
+    : null
 }
 
 export function getPanelEntries(
   panelSchemas,
   dataPath,
   componentPath,
-  tabComponent = null,
+  tab = null,
   panelEntries = []
 ) {
   if (panelSchemas) {
@@ -232,7 +257,7 @@ export function getPanelEntries(
         schema,
         appendDataPath(dataPath, key),
         appendDataPath(componentPath, key),
-        tabComponent
+        tab
       )
       if (entry) {
         panelEntries.push(entry)
@@ -256,7 +281,7 @@ export function getAllPanelEntries(
   dataPathComponentPath,
   schemaComponentPath,
   component = null,
-  tabComponent = null
+  tab = null
 ) {
   const panelSchema = getTypeOptions(schema)?.getPanelSchema?.(
     api,
@@ -270,7 +295,7 @@ export function getAllPanelEntries(
           panelSchema,
           appendDataPath(dataPath, panelSchema.name),
           appendDataPath(dataPathComponentPath, panelSchema.name),
-          tabComponent
+          tab
         )
       ]
     : []
@@ -280,7 +305,7 @@ export function getAllPanelEntries(
     schema?.panels,
     dataPath,
     schemaComponentPath,
-    tabComponent,
+    tab,
     panelEntries
   )
   return panelEntries

package/src/utils/schema/setup.js

@@ -97,13 +97,13 @@ export async function resolveSchemas(
 export async function resolveViews(unresolvedViews) {
   return resolveSchemas(unresolvedViews, async (schema, unwrapModule) => {
     schema = await resolveSchema(schema, unwrapModule)
-    if (!schema.name && isMenu(schema)) {
-      // Generate a name for sub-menus from their label if it's missing.
-      // NOTE: This is never actually referenced from anywhere, but they need
-      // a name by which they're stored in the parent object.
+    if (isMenu(schema)) {
       schema = {
         ...schema,
-        name: camelize(schema.label),
+        // Generate a name for sub-menus from their label if it's missing.
+        // NOTE: This is never actually referenced from anywhere, but they need
+        // a name by which they're stored in the parent object.
+        name: schema.name || camelize(schema.label),
         items: await resolveSchemas(schema.items)
       }
     }

package/src/utils/schema/validation.js

@@ -40,8 +40,7 @@ export function getValidations(schema, context) {
 export function getValueValidationErrors(value, validations) {
   const errors = []
   for (const [name, setting] of Object.entries(validations)) {
-    // eslint-disable-next-line import/namespace
-    const validator = validators[name]
+    const validator = getValidator(name)
     if (
       validator &&
       // Only apply 'required' validator to empty values.
@@ -61,6 +60,21 @@ export function getValueValidationErrors(value, validations) {
   return errors
 }
 
+// The names of unknown validators that were warned about, see `getValidator()`:
+const warnedUnknownValidatorNames = new Set()
+
+// Returns the validator of the name, or `null` with a warning, once per name,
+// e.g. for misspelled `schema.rules`.
+function getValidator(name) {
+  // eslint-disable-next-line import/namespace
+  const validator = validators[name] ?? null
+  if (!validator && !warnedUnknownValidatorNames.has(name)) {
+    warnedUnknownValidatorNames.add(name)
+    console.warn(`Unknown validator '${name}' is ignored.`)
+  }
+  return validator
+}
+
 /**
  * Validates `data` along the components of `schema`, including tabs, panels
  * and the nested forms of list and object items, skipping components whose

package/src/utils/uid.js

@@ -1,15 +1,112 @@
 import { toRaw } from 'vue'
+import { isArray, isPlainObject, isString } from '@ditojs/utils'
+import { isTemporaryId } from './data.js'
 
-const uidMap = new WeakMap()
+const uidsByItem = new WeakMap()
 
-// Generated and remembers unique ids per passed object using a weak map.
-let uid = 0
+// Generated uids have their own prefix, so that they can't be mistaken for
+// temporary ids, see `setTemporaryId()`.
+const generatedUidPrefix = 'uid-'
+let lastGeneratedUid = 0
+
+// Generates and remembers unique ids per passed object using a weak map.
 export function getUid(item, getItemId = null) {
   const raw = toRaw(item)
-  let id = uidMap.get(raw)
-  if (!id && item) {
-    id = getItemId?.(item) || `@${++uid}`
-    uidMap.set(raw, id)
+  let uid = uidsByItem.get(raw)
+  if (!uid && item) {
+    uid = getItemId?.(item) || `${generatedUidPrefix}${++lastGeneratedUid}`
+    uidsByItem.set(raw, uid)
+  }
+  return uid
+}
+
+// Transfers the uids of new objects in `source`, which are generated or
+// temporary ids, to the corresponding objects in `target` that don't have uids
+// yet, e.g. when the saved data replaces the data that was edited. This way,
+// the components and stores that are keyed by the uids of new items are kept,
+// even though the items only have their ids once they are saved.
+// Objects are matched by their keys. Array items are matched by their `id`
+// properties, see `transferArrayUids()`. The items of lists with a custom
+// `idKey` have no `id`, so they count as new items and are matched in order.
+export function transferUids(source, target) {
+  const rawSource = toRaw(source)
+  const rawTarget = toRaw(target)
+  if (
+    rawSource !== rawTarget &&
+    isTransferable(rawSource) &&
+    isTransferable(rawTarget)
+  ) {
+    const uid = uidsByItem.get(rawSource)
+    if (isNewItemUid(uid) && !uidsByItem.has(rawTarget)) {
+      uidsByItem.set(rawTarget, uid)
+    }
+    if (isArray(rawSource) && isArray(rawTarget)) {
+      transferArrayUids(rawSource, rawTarget)
+    } else {
+      for (const key of Object.keys(rawSource)) {
+        if (key in rawTarget) {
+          transferUids(rawSource[key], rawTarget[key])
+        }
+      }
+    }
+  }
+}
+
+// Matches the items of two arrays by their ids rather than their positions, as
+// the saved items may be ordered differently than the edited ones: Each saved
+// item in `source` is matched with the item in `target` that has the same id.
+// The new items in `source`, which have no id or a temporary one, can only be
+// matched with the items in `target` that have none of the saved ids, in order,
+// and only if their counts are equal. Otherwise, they are left unmatched rather
+// than risking to give an item the uid, component and store of another.
+function transferArrayUids(source, target) {
+  const sourceItems = source.filter(isTransferable)
+  const targetItems = target.filter(isTransferable)
+  const targetItemsById = new Map()
+  for (const item of targetItems) {
+    const id = getSavedItemId(item)
+    if (id !== undefined) {
+      targetItemsById.set(id, item)
+    }
+  }
+  const savedIds = new Set()
+  const newSourceItems = []
+  for (const item of sourceItems) {
+    const id = getSavedItemId(item)
+    if (id !== undefined) {
+      savedIds.add(id)
+      const targetItem = targetItemsById.get(id)
+      if (targetItem) {
+        transferUids(item, targetItem)
+      }
+    } else {
+      newSourceItems.push(item)
+    }
   }
-  return id
+  const newTargetItems = targetItems.filter(
+    item => !savedIds.has(getSavedItemId(item))
+  )
+  if (newSourceItems.length === newTargetItems.length) {
+    newSourceItems.forEach((item, index) => {
+      transferUids(item, newTargetItems[index])
+    })
+  }
+}
+
+// Returns the id of a saved item as a string, so that numeric ids match their
+// string representations, or `undefined` for new items.
+function getSavedItemId(item) {
+  const { id } = item
+  return id != null && !isTemporaryId(id) ? String(id) : undefined
+}
+
+function isTransferable(value) {
+  return isArray(value) || isPlainObject(value)
+}
+
+function isNewItemUid(uid) {
+  return (
+    isString(uid) &&
+    (uid.startsWith(generatedUidPrefix) || isTemporaryId(uid))
+  )
 }

package/src/validators/_decimals.js

@@ -1,11 +1,22 @@
+function hasUnlimitedDecimals(decimals) {
+  return decimals == null || decimals === '*'
+}
+
 export const decimals = {
   validate: (value, decimals) => {
-    const match = decimals === '*' ? '+' : `{1,${decimals}}`
-    return new RegExp(`^[-+]?\\d*(\\.\\d${match})?$`).test(value)
+    // `decimals: 0` allows no decimal point at all, only integers:
+    const fraction = hasUnlimitedDecimals(decimals)
+      ? '(\\.\\d+)?'
+      : decimals > 0
+        ? `(\\.\\d{1,${decimals}})?`
+        : ''
+    return new RegExp(`^[-+]?\\d*${fraction}$`).test(value)
   },
 
   message: (value, decimals) =>
-    `must be numeric and may contain ${
-      !decimals || decimals === '*' ? '' : decimals
-    } decimal points`
+    hasUnlimitedDecimals(decimals)
+      ? 'must be numeric and may contain decimal points'
+      : decimals > 0
+        ? `must be numeric and may contain ${decimals} decimal points`
+        : 'must be numeric and may not contain decimal points'
 }

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)
-        }
-      }
-    }
-  }
-}