@ditojs/admin 2.100.0 → 3.1.0

package/types/index.d.ts

@@ -52,6 +52,12 @@ export type RequestMethod = <T>(options: {
   headers?: Record<string, string> | null
   /** Abort signal to cancel the request. */
   signal?: AbortSignal | null
+  /**
+   * Milliseconds after which the request is aborted.
+   *
+   * @defaultValue {@link ApiConfig.timeout}
+   */
+  timeout?: number | null
 }) => Promise<RequestMethodResponse<T>>
 
 /**
@@ -170,6 +176,14 @@ export interface ApiConfig {
          */
         durationFactor: number
       }
+  /**
+   * Milliseconds after which requests are aborted, so that
+   * nothing waits for them forever, e.g. submitting forms for
+   * pending loads of options. Requests can set their own.
+   *
+   * @defaultValue `null`, no timeout
+   */
+  timeout?: number | null
   /**
    * CORS settings applied to API requests (where
    * {@link ApiConfig.isApiUrl} returns `true`).
@@ -326,9 +340,15 @@ export interface BaseSchema<$Item>
    */
   default?: OrItemAccessor<$Item>
   /**
-   * Computes and sets the field value reactively. If
-   * the callback returns `undefined`, the current value
-   * is preserved.
+   * Computes and sets the field value reactively, also
+   * when the field isn't rendered, unless its `if`
+   * evaluates to `false`. If the callback returns
+   * `undefined`, the current value is preserved.
+   *
+   * As it doesn't depend on the field's component, the
+   * context's component properties, e.g. `component`
+   * and `schemaComponent`, refer to the form, view or
+   * dialog that holds the data, not to the field.
    */
   compute?: ItemAccessor<$Item>
   /**
@@ -367,19 +387,26 @@ export interface SchemaDitoMixin<$Item> {
    * change before value validation occurs. Rule changes do not influence how
    * the component is rendered.
    */
-  rules?: {
-    /** Override whether the field is required. */
-    required?: boolean
-  }
+  rules?: SchemaRules
+}
+
+/**
+ * Validation rules shared by all schemas, extended by the individual types.
+ */
+export interface SchemaRules {
+  /** Override whether the field is required. */
+  required?: boolean
 }
 
 /**
  * Return false to mark event as handled and stop it from propagating to parent
  * schemas.
  */
+// Handlers can be async, as events are awaited, e.g. by buttons that show
+// their progress while their `click` handler runs.
 export type ItemEventHandler<$Item = any> = (
   itemParams: DitoContext<$Item>
-) => void | false
+) => void | false | Promise<void | false>
 
 export type OpenEventHandler<$Item = any> = (
   itemParams: DitoContext<$Item> & { open: boolean }
@@ -565,14 +592,20 @@ export interface SchemaTypeMixin<$Item> extends SchemaFields<$Item> {
    * @see {@link SchemaFields.onInitialize} and other `on`-
    * prefixed properties for per-event documentation.
    */
-  events?: SchemaEvents<$Item> & {
-    /** @see {@link BaseSchema.onFocus} */
-    focus?: ItemEventHandler<$Item>
-    /** @see {@link BaseSchema.onBlur} */
-    blur?: ItemEventHandler<$Item>
-    /** @see {@link BaseSchema.onInput} */
-    input?: ItemEventHandler<$Item>
-  }
+  events?: BaseSchemaEvents<$Item>
+}
+
+/**
+ * Grouped event handlers shared by all schemas, extended by the individual
+ * types.
+ */
+export interface BaseSchemaEvents<$Item> extends SchemaEvents<$Item> {
+  /** @see {@link BaseSchema.onFocus} */
+  focus?: ItemEventHandler<$Item>
+  /** @see {@link BaseSchema.onBlur} */
+  blur?: ItemEventHandler<$Item>
+  /** @see {@link BaseSchema.onInput} */
+  input?: ItemEventHandler<$Item>
 }
 
 export interface SchemaSourceMixin<$Item> {
@@ -643,9 +676,18 @@ export interface SchemaSourceMixin<$Item> {
   /** Buttons for the source. */
   buttons?: Buttons<$Item>
   /**
-   * Whether to wrap primitive values in objects.
+   * The key under which primitive values are wrapped in objects, so that the
+   * source's forms can edit them, e.g. `'value'` for a list of strings.
    */
-  wrapPrimitives?: boolean
+  wrapPrimitives?: string
+  /**
+   * Whether the forms of the source's items directly mutate the source's data
+   * instead of editing a copy that is applied when submitting. Forms that
+   * mutate data are never dirty.
+   *
+   * @defaultValue `false`
+   */
+  mutate?: boolean
   /**
    * URL path for the source items.
    */
@@ -722,7 +764,9 @@ export interface SchemaSourceMixin<$Item> {
   deletable?: OrItemAccessor<$Item, {}, boolean | { label: string }>
   /**
    * The column used for the order resulting from dragging around list entries
-   * when the `draggable` property of the list schema is set to `true`.
+   * when the `draggable` property of the list schema is set to `true`. Items
+   * are numbered when the data is loaded, and when they are added, removed or
+   * reordered.
    */
   orderKey?: string
   /**
@@ -772,6 +816,12 @@ export type SchemaOptions<$Item, $Option = any> =
        * receives the `DitoContext` and returns an inner
        * function that is called to fetch the actual data,
        * enabling reactive dependency tracking.
+       *
+       * The options are loaded independently of the
+       * field's component, also for computes, so the
+       * context's component properties, e.g. `component`
+       * and `schemaComponent`, refer to the form, view or
+       * dialog that holds the data, not to the field.
        */
       data?: OrItemAccessor<
         $Item,
@@ -919,14 +969,15 @@ export interface SchemaNumberMixin<$Item> {
    */
   step?: OrItemAccessor<$Item, {}, number>
   /**
-   * The amount of decimals to round to.
+   * The maximum amount of decimals allowed, validated on input.
    */
   decimals?: OrItemAccessor<$Item, {}, number>
   /** Validation rules for numeric constraints. */
-  rules?: Omit<SchemaNumberMixin<$Item>, 'rules'> & {
-    /** Restrict the value to whole numbers. */
-    integer?: boolean
-  }
+  rules?: SchemaRules &
+    Omit<SchemaNumberMixin<$Item>, 'rules'> & {
+      /** Restrict the value to whole numbers. */
+      integer?: boolean
+    }
 }
 
 export interface SchemaTextMixin<$Item> {
@@ -964,7 +1015,7 @@ export interface SchemaDataMixin<$Item> {
   /**
    * Data source for the component.
    */
-  data?: OrItemAccessor<$Item, {}, any>
+  data?: OrItemAccessor<$Item, {}, Record<string, any>>
   /**
    * Path to retrieve data from parent context.
    */
@@ -1128,7 +1179,7 @@ export interface InputSchema<$Item = any>
     | 'tel'
     | 'password'
     | 'creditcard'
-  rules?: {
+  rules?: SchemaRules & {
     text?: boolean
     email?: boolean
     url?: boolean
@@ -1180,7 +1231,7 @@ export interface ButtonSchema<$Item = any>
   onClick?: ItemEventHandler<$Item>
   onSuccess?: ItemEventHandler<$Item>
   onError?: ErrorEventHandler<$Item>
-  events?: {
+  events?: BaseSchemaEvents<$Item> & {
     click?: ItemEventHandler<$Item>
     success?: ItemEventHandler<$Item>
     error?: ErrorEventHandler<$Item>
@@ -1209,8 +1260,9 @@ export interface SwitchSchema<$Item = any> extends BaseSchema<$Item> {
 }
 
 export interface NumberSchema<$Item = any>
+  // `rules` comes from `SchemaNumberMixin`, which extends `SchemaRules`.
   extends SchemaNumberMixin<$Item>,
-    BaseSchema<$Item>,
+    Omit<BaseSchema<$Item>, 'rules'>,
     SchemaAffixMixin<$Item> {
   /**
    * The type of the component.
@@ -1219,8 +1271,9 @@ export interface NumberSchema<$Item = any>
 }
 
 export interface SliderSchema<$Item = any>
+  // `rules` comes from `SchemaNumberMixin`, which extends `SchemaRules`.
   extends SchemaNumberMixin<$Item>,
-    BaseSchema<$Item> {
+    Omit<BaseSchema<$Item>, 'rules'> {
   /**
    * The type of the component.
    */
@@ -1400,9 +1453,8 @@ export interface UploadSchema<$Item = any> extends BaseSchema<$Item> {
   accept?: OrArrayOf<string>
   /**
    * The maximum size of the file expressed as number of bytes or as a string
-   * like `'200kb'`, `'1mb'`, `'3.2gb'`, etc.
-   *
-   * @see {@link https://github.com/patrickkettner/filesize-parser/blob/master/test.js String Examples}
+   * like `'200kB'`, `'1MB'`, `'3.2GB'`, etc., using base 10 (1 kB = 1000
+   * bytes). IEC units like `'1MiB'` use base 2 (1 KiB = 1024 bytes).
    */
   maxSize?: string | number
   /**
@@ -1502,7 +1554,7 @@ type SectionContent<$Data> = {
   /**
    * A form schema for the section's content. Use this
    * instead of `components` to get form-level options
-   * like `label`, `tabs`, and `mutate`.
+   * like `label` and `tabs`.
    */
   form?: ResolvableForm<$Data>
   /**
@@ -1679,7 +1731,9 @@ export type ColorFormat =
   | 'hsl'
   | 'hsv'
 export interface ColorSchema<$Item = any>
-  extends BaseSchema<$Item>,
+  // `format` is the color format here, not the formatting function of
+  // `BaseSchema`.
+  extends Omit<BaseSchema<$Item>, 'format'>,
     SchemaAffixMixin<$Item> {
   /**
    * The type of the component.
@@ -1801,7 +1855,7 @@ export interface ListSchema<$Item = { [key: string]: any }>
   /**
    * Grouped event handlers.
    */
-  events?: {
+  events?: BaseSchemaEvents<$Item> & {
     /**
      * Called when a collapsible inlined list is
      * toggled open or closed.
@@ -1930,7 +1984,12 @@ export type DitoContext<$Item = any> = {
   sourceComponent: DitoSourceInstance | null
   /** The currently focused option in a select. */
   option: any
-  /** All available options in a select. */
+  /**
+   * All available options in a select. In `compute()`, they are
+   * loaded when first read, also when the field isn't rendered,
+   * and are `undefined` while loading; the callback runs again
+   * once they are loaded.
+   */
   options: any
   /**
    * Whether a pulldown/select is currently open.
@@ -2062,6 +2121,14 @@ export interface DitoComponentInstanceBase<$Item = any>
   name: string
   /** Full dot-separated path to the current data. */
   dataPath: string
+  /**
+   * The path of component names through views, tabs,
+   * panels and forms, with item indices from the data
+   * path, e.g. `main/chapters/0/title`. Unlike
+   * `dataPath`, it tells apart components that display
+   * the same data. Used as the component's DOM id.
+   */
+  componentPath: string
   /** The schema definition for the current component. */
   schema: Component
   /** The component type from the schema. */
@@ -2409,6 +2476,36 @@ export interface DitoFormInstance<$Item = any>
    */
   isCreating: boolean
 
+  /**
+   * Whether the form's processed data differs from
+   * the data it was loaded, saved or applied with.
+   * Values that are derived when the data is set up,
+   * e.g. defaults and computed values, don't count.
+   * Forms with `mutate: true` aren't dirty
+   * themselves, their changes make the form that
+   * owns the data dirty.
+   */
+  isDirty: boolean
+
+  /**
+   * Makes clean changes to the data, which don't
+   * make the form dirty, while other changes still
+   * do, e.g. to apply what an action on the server
+   * already saved. `makeChanges()` is called
+   * synchronously, the returned promise resolves
+   * once the values derived from the changes are
+   * clean too.
+   *
+   * @example
+   * ```js
+   * const shopOrder = await request({ method: 'post', url })
+   * formComponent.applyCleanChanges(() => {
+   *   item.templateShopOrder = shopOrder
+   * })
+   * ```
+   */
+  applyCleanChanges(makeChanges: () => void): Promise<void>
+
   /**
    * Submits the form data to the API. Returns
    * `true` on success, `false` if validation
@@ -2435,7 +2532,9 @@ export interface DitoFormInstance<$Item = any>
   close(): Promise<void>
 
   /**
-   * Validates all fields in the form. Optionally
+   * Validates all fields in the form's data, including
+   * fields that aren't rendered, e.g. in collapsed
+   * sections or closed nested forms. Optionally
    * filter fields with a match pattern. Returns
    * `true` if all matched fields are valid.
    */
@@ -2497,8 +2596,12 @@ export interface DitoFormInstance<$Item = any>
   ensureData(): void
   /** Clears the loaded data. */
   clearData(): void
-  /** Sets the component's loaded data directly. */
-  setData(data: any): void
+  /**
+   * Sets the component's loaded data directly, and
+   * returns it as the component's reactive data,
+   * which can be modified to update it.
+   */
+  setData(data: any): any
   /**
    * Creates a new data object with default values
    * from the schema. Optionally sets a `type`
@@ -2576,13 +2679,17 @@ export interface DitoViewInstance<$Item = any>
    * a resource.
    */
   providesData: boolean
-  /** Sets the view's data directly. */
-  setData(data: any): void
+  /**
+   * Sets the view's data directly, and returns it
+   * as the view's reactive data.
+   */
+  setData(data: any): any
 
   // -- Validation (ValidatorMixin) --
 
   /**
-   * Validates all fields in the view.
+   * Validates all fields in the view's data,
+   * including fields that aren't rendered.
    * Optionally filter fields with a match pattern.
    * Returns `true` if all matched fields are valid.
    */
@@ -2611,9 +2718,12 @@ export interface DitoViewInstance<$Item = any>
 export interface DitoSchemaInstance<$Item = any>
   extends DitoComponentInstanceBase<$Item> {
   /**
-   * Validates all fields in the schema.
+   * Validates all fields in the schema's data,
+   * including fields that aren't rendered, e.g. in
+   * collapsed sections or closed nested forms.
    * Optionally filter fields with a match pattern
-   * (string, string[], RegExp, or function).
+   * (string, string[], RegExp, or function) over
+   * their data paths.
    * Returns `true` if all matched fields are
    * valid.
    */
@@ -2717,11 +2827,14 @@ export interface DitoSourceInstance<$Item = any>
   deleteItem(item: any, index: number): void
   /**
    * Navigates to a component identified by its
-   * data path.
+   * data path. With `shouldRevealInlinedOnly`, only
+   * components in inlined schemas are revealed,
+   * without navigating to nested forms.
    */
   navigateToComponent(
     dataPath: string,
-    onComplete?: Function
+    onComplete?: Function,
+    options?: { shouldRevealInlinedOnly?: boolean }
   ): Promise<boolean>
   /**
    * Navigates to the route component associated
@@ -2756,8 +2869,12 @@ export interface DitoSourceInstance<$Item = any>
   ensureData(): void
   /** Clears the loaded data. */
   clearData(): void
-  /** Sets the component's loaded data directly. */
-  setData(data: any): void
+  /**
+   * Sets the component's loaded data directly, and
+   * returns it as the component's reactive data,
+   * which can be modified to update it.
+   */
+  setData(data: any): any
   /**
    * Creates a new data object with default values
    * from the schema. Optionally sets a `type`
@@ -2883,7 +3000,7 @@ export interface ObjectSchema<$Item = { [key: string]: any }>
   /**
    * Grouped event handlers.
    */
-  events?: {
+  events?: BaseSchemaEvents<$Item> & {
     /**
      * Called when a collapsible inlined object is
      * toggled open or closed.
@@ -2953,8 +3070,9 @@ export interface SpacerSchema<$Item = any> extends BaseSchema<$Item> {
 }
 
 export interface ProgressSchema<$Item = any>
+  // `rules` comes from `SchemaNumberMixin`, which extends `SchemaRules`.
   extends SchemaNumberMixin<$Item>,
-    BaseSchema<$Item> {
+    Omit<BaseSchema<$Item>, 'rules'> {
   /**
    * The type of the component.
    */
@@ -2993,6 +3111,7 @@ type NonSectionComponent<$Item = any> =
 export type Component<$Item = any> =
   | NonSectionComponent<$Item>
   | SectionSchema<$Item>
+  | PanelSchema<$Item>
 
 /**
  * Source components (list, object, tree) that contain nested
@@ -3107,11 +3226,14 @@ export type Components<$Item = any> = 0 extends 1 & $Item
   ? Record<string, Component>
   : {
       [K in keyof $Item]?: [$Item[K]] extends [never]
-        ? NonSectionComponent<$Item> | SectionSchema<$Item>
+        ? // Sections and panels that share the data of their schema.
+          NonSectionComponent<$Item> | SectionSchema<$Item> | PanelSchema<$Item>
         : NonNullable<$Item[K]> extends (infer E)[]
           ? E extends Record<string, any>
             ? NonSectionComponent<E>
-            : NonSectionComponent<$Item>
+            : // Lists of primitive values edit them wrapped in objects under
+              // the key given by `wrapPrimitives`, see `SchemaSourceMixin`.
+              NonSectionComponent<Record<string, E>>
           : NonNullable<$Item[K]> extends Record<string, any>
             ?
                 | NonOptionFieldComponent<$Item>
@@ -3147,13 +3269,6 @@ export interface Form<$Item = any> extends SchemaRoute<$Item> {
    * The label of the form.
    */
   label?: OrItemAccessor<$Item, {}, string | boolean>
-  /**
-   * Whether the form directly mutates the parent data instead
-   * of working on a copy.
-   *
-   * @defaultValue `false`
-   */
-  mutate?: boolean
   /**
    * The property name used as the item's unique identifier.
    *

package/src/mixins/DataMixin.js

@@ -1,131 +0,0 @@
-import {
-  isObject,
-  isFunction,
-  isPromise,
-  normalizeDataPath,
-  getValueAtDataPath
-} from '@ditojs/utils'
-import { markRaw, ref } from 'vue'
-import LoadingMixin from './LoadingMixin.js'
-
-// @vue/component
-export default {
-  mixins: [LoadingMixin],
-
-  data() {
-    return {
-      isLoading: false,
-      asyncDataEntries: markRaw({})
-    }
-  },
-
-  methods: {
-    handleDataSchema(schema, name, loadingOptions) {
-      if (!isObject(schema)) {
-        schema = { data: schema }
-      }
-      let { data = undefined, dataPath = null } = schema
-      // Create a reactive entry for the async data, if it doesn't exist yet.
-      // NOTE: `markRaw()` is used to avoid reactivity on `asyncDataEntries`
-      // itself, as reactivity is only desired on `reactiveVersion`, which is
-      // used to trigger controlled reevaluation of the computed getter.
-      const asyncEntry = (this.asyncDataEntries[name] ??= {
-        reactiveVersion: ref(1),
-        dependencyFunction: null,
-        resolvedData: undefined,
-        resolving: false,
-        resolved: false
-      })
-      // If the data callback provided a dependency function when it was called,
-      // cal it in every call of `handleDataSchema()` to force Vue to keep track
-      // of the async dependencies. Also access `reactiveVersion.value` right
-      // away, to ensure that the reactive property is tracked as a dependency:
-      asyncEntry.reactiveVersion.value &&
-      asyncEntry.dependencyFunction?.(this.context)
-
-      if (asyncEntry.resolved) {
-        // If the data was resolved already, return it and clear the resolved
-        // value. This works because Vue caches the result of computed getters
-        // and only reevaluates if one of the dependencies changed. This is to
-        // ensure that a cached value here doesn't block / override
-        // reevaluation when a dependency changes:
-        const { resolvedData } = asyncEntry
-        asyncEntry.resolvedData = undefined
-        asyncEntry.resolved = false
-        return resolvedData
-      }
-      // Avoid calling the data function twice:
-      if (asyncEntry.resolving) {
-        data = null
-      } else if (data) {
-        if (isFunction(data)) {
-          const result = data(this.context)
-          // If the result of the data function is another function, then the
-          // first data function is there to track dependencies and the real
-          // data loading happens in the function that it returned. Keep track
-          // it in `dependencyFunction` so it can be called on each call of
-          // `handleDataSchema()` to keep the dependencies intact, and call
-          // the function that it returned once to get the actual data:
-          if (isFunction(result)) {
-            asyncEntry.dependencyFunction = data
-            data = result(this.context)
-          } else {
-            data = result
-          }
-        }
-        // NOTE: If the data is not a promise, it is resolved already.
-        if (isPromise(data)) {
-          // If the data is asynchronous, it can't be returned straight away.
-          // But we can cheat using computed properties and `resolvedData`,
-          // which is going to receive the loaded data asynchronously,
-          // triggering a recompute of the computed property that calls
-          // `handleDataSchema()`.
-          asyncEntry.resolving = true
-          this.resolveData(data, loadingOptions)
-            .then(data => {
-              asyncEntry.resolvedData = data
-              asyncEntry.resolving = false
-              asyncEntry.resolved = true
-              // Trigger reevaluation of the computed getter by increasing the
-              // `reactiveVersion` value.
-              asyncEntry.reactiveVersion.value++
-            })
-            .catch(error => {
-              console.error(error)
-              asyncEntry.resolving = false
-            })
-          // Clear data until promise is resolved and `resolvedData` is set
-          data = null
-        }
-      } else if (dataPath) {
-        data = getValueAtDataPath(
-          this.rootData,
-          normalizeDataPath(`${this.dataPath}/${dataPath}`)
-        )
-      }
-      return data
-    },
-
-    async resolveData(load, loadingOptions = {}) {
-      // Use a timeout to allow already resolved promises to return data without
-      // showing a loading indicator.
-      let clearLoading = false
-      const timer = setTimeout(() => {
-        this.setLoading(true, loadingOptions)
-        clearLoading = true
-      }, 0)
-      let data = null
-      try {
-        data = await (isFunction(load) ? load() : load)
-      } catch (error) {
-        this.addError(error.message || error)
-      }
-      if (clearLoading) {
-        this.setLoading(false, loadingOptions)
-      } else {
-        clearTimeout(timer)
-      }
-      return data
-    }
-  }
-}