@ditojs/admin 3.0.0 → 3.1.1

package/src/utils/FormModel.js

@@ -9,10 +9,12 @@ import {
 } from '@ditojs/utils'
 import DitoContext from '../DitoContext.js'
 import { DataSchemaResolver } from './DataSchemaResolver.js'
-import { isNested, isSourceWithResource } from './schema/structure.js'
+import { isNested } from './schema/structure.js'
 import { isEmptySchema } from './schema/lookup.js'
 import {
-  shouldRenderSchema,
+  getSchemaValue,
+  shouldSetDefaultValue,
+  getDefaultValue,
   initializeData,
   computeValue,
   hasValueFromDataSchema,
@@ -23,9 +25,10 @@ import {
 // FormModel holds the state of the data edited by a form, view or dialog that
 // is derived from schema and data, independently of what is rendered:
 //
-// - Missing values are set to their defaults when the data is set up, except
-//   the values of components with `compute()`, which fall back to their
-//   defaults when `compute()` doesn't return a value, unlike in new data, see
+// - Missing values are set to their defaults when the data is set up, and when
+//   they go missing later, e.g. in items that code adds, except the values of
+//   components with `compute()`, which fall back to their defaults when
+//   `compute()` doesn't return a value, unlike in new data, see
 //   `initializeData()`.
 // - The items of lists with `orderKey` are numbered when the data is set up,
 //   which doesn't make the data dirty.
@@ -94,12 +97,19 @@ export class FormModel {
       // The entries are read through a computed property, so that the watchers
       // of the entries can check synchronously whether their entry is still
       // current, see `createComputedValueScope()`.
-      this.computedValueEntries = computed(() => this.getComputedValueEntries())
+      this.dataEntries = computed(() => this.getDataEntries())
       watch(
-        () => this.computedValueEntries.value,
+        () => this.dataEntries.value.computedValueEntries,
         entries => this.updateComputedValueRecords(entries),
         { immediate: true }
       )
+      // Values that go missing after the data was set up, e.g. in items that
+      // code adds, get their defaults too:
+      watch(
+        () => this.dataEntries.value.entriesWithMissingValues,
+        entries => this.setDefaultValues(entries),
+        { immediate: true }
+      )
       if (getSourceSchema) {
         // Data that is set up, e.g. loaded, saved or applied, isn't dirty:
         watch(
@@ -285,7 +295,7 @@ export class FormModel {
       initializeData(schema, data, this.component, {
         dataPath: this.dataPath,
         rootData: this.rootData,
-        shouldProcess: entry => !isSourceWithResource(entry.schema),
+        shouldSkipSourcesWithResource: true,
         // The model writes the values of components with `compute()`,
         // including their defaults:
         shouldSetDefaultsOfComponentsWithCompute: false
@@ -293,32 +303,78 @@ export class FormModel {
     }
   }
 
-  // Returns the entries of `processSchemaData()` for all components with
-  // computed values whose `if` doesn't evaluate to `false`, by component path.
-  // Called by a computed property, so that it runs again when the data
-  // structure changes, e.g. when list items are added or removed, or when `if`
-  // conditions change.
-  getComputedValueEntries() {
+  // Walks the data and returns the entries of `processSchemaData()` of the
+  // components whose `if` doesn't evaluate to `false`: the ones with computed
+  // values, by component path, and the ones whose values are missing. Called
+  // by a computed property, so that it runs again when the data structure
+  // changes, e.g. when list items are added or removed, values go missing, or
+  // `if` conditions change.
+  getDataEntries() {
     const schema = this.getSchema()
     const data = this.getData()
-    const entries = new Map()
+    const computedValueEntries = new Map()
+    const entriesWithMissingValues = []
     if (data && !isEmptySchema(schema)) {
       processSchemaData(schema, data, {
         dataPath: this.dataPath,
         componentPath: this.componentPath,
-        shouldProcess: entry => (
-          !isSourceWithResource(entry.schema) &&
-          shouldRenderSchema(entry.schema, this.createEntryContext(entry))
-        ),
+        shouldProcess: entry => this.isEntryShown(entry),
+        shouldSkipSourcesWithResource: true,
         before: entry => {
           if (hasComputedValueSource(entry.schema)) {
-            entries.set(entry.componentPath, entry)
+            computedValueEntries.set(entry.componentPath, entry)
+          }
+          if (this.shouldSetDefaultValue(entry)) {
+            entriesWithMissingValues.push(entry)
           }
         },
         options: { component: this.component, rootData: this.rootData }
       })
     }
-    return entries
+    return { computedValueEntries, entriesWithMissingValues }
+  }
+
+  // Returns whether the `if` of the entry's component doesn't evaluate to
+  // `false`. Unlike `shouldRenderSchema()`, it doesn't evaluate the components
+  // of sections and tabs, as the walk of the data visits them anyway, see
+  // `getDataEntries()`, which leads to the same entries.
+  isEntryShown(entry) {
+    return (
+      entry.schema.if === undefined ||
+      getSchemaValue('if', {
+        type: Boolean,
+        schema: entry.schema,
+        context: this.createEntryContext(entry),
+        default: true
+      })
+    )
+  }
+
+  // Returns whether the value of the entry is missing and needs its default.
+  // The model writes the values of components with `compute()`, including
+  // their defaults, see `computeValue()`.
+  shouldSetDefaultValue(entry) {
+    const { schema, data, name } = entry
+    return shouldSetDefaultValue(
+      schema,
+      data,
+      name,
+      () => this.createEntryContext(entry),
+      { shouldSetDefaultsOfComponentsWithCompute: false }
+    )
+  }
+
+  // Sets the defaults of the values of the entries, unless they were set in
+  // the meantime.
+  setDefaultValues(entries) {
+    for (const entry of entries) {
+      if (this.shouldSetDefaultValue(entry)) {
+        const { schema, data, name } = entry
+        data[name] = getDefaultValue(schema, () =>
+          this.createEntryContext(entry)
+        )
+      }
+    }
   }
 
   // Keeps the records of the components that are still present with the same
@@ -395,9 +451,10 @@ export class FormModel {
   }
 
   // Returns whether the entry is still one of the current entries, with the
-  // same schema and data, see `getComputedValueEntries()`.
+  // same schema and data, see `getDataEntries()`.
   isEntryCurrent({ componentPath, schema, data }) {
-    const currentEntry = this.computedValueEntries.value.get(componentPath)
+    const currentEntry =
+      this.dataEntries.value.computedValueEntries.get(componentPath)
     return currentEntry?.schema === schema && currentEntry.data === data
   }
 
@@ -466,7 +523,7 @@ export class FormModel {
     const tokens = isNested(schema)
       ? parseDataPath(dataPath)
       : [...parseDataPath(dataPath), name]
-    return tokens.slice(parseDataPath(this.dataPath).length)
+    return tokens.slice(parseDataPath(this.dataPath).length).join('/')
   }
 
   // Returns the context for `if`, data schemas and options, with the component
@@ -497,8 +554,9 @@ function takeOverValuesAtDataPaths(
   }
   const result = clone(processedData)
   for (const dataPath of dataPaths) {
-    const parentDataPath = dataPath.slice(0, -1)
-    const key = dataPath.at(-1)
+    const tokens = parseDataPath(dataPath)
+    const parentDataPath = tokens.slice(0, -1)
+    const key = tokens.at(-1)
     const parent = getValueAtDataPath(result, parentDataPath, () => null)
     if (parent && typeof parent === 'object') {
       const value = getValueAtDataPath(
@@ -526,12 +584,13 @@ function takeOverChangedValues(target, before, after) {
     return target
   }
   const isSameShape = (
-    isPlainObject(before) && isPlainObject(after) && isPlainObject(target) ||
-    isArray(before) &&
-    isArray(after) &&
-    isArray(target) &&
-    before.length === after.length &&
-    after.length === target.length
+    isPlainObject(before) && isPlainObject(after) && isPlainObject(target) || (
+      isArray(before) &&
+      isArray(after) &&
+      isArray(target) &&
+      before.length === after.length &&
+      after.length === target.length
+    )
   )
   if (!isSameShape) {
     return clone(after)

package/src/utils/request.js

@@ -0,0 +1,70 @@
+import { isAbsoluteUrl } from '@ditojs/utils'
+import { formatQuery } from './route.js'
+
+export class RequestError extends Error {
+  constructor(response) {
+    super(
+      `Request failed with status code: ${response.status} (${
+        response.statusText
+      })`
+    )
+    this.response = response
+  }
+}
+
+export async function request(api, {
+  url,
+  method = 'get',
+  query = null,
+  headers = null,
+  data = null,
+  signal = null,
+  timeout = api.timeout ?? null
+}) {
+  const isApiUrl = api.isApiUrl(url)
+  // Abort requests that take longer than the timeout, if there is one, so that
+  // nothing waits for them forever, e.g. submitting for pending loads:
+  const signals = [signal, timeout && AbortSignal.timeout(timeout)]
+  signal = AbortSignal.any(signals.filter(Boolean))
+
+  const response = await fetch(api.getApiUrl({ url, query }), {
+    method: method.toUpperCase(),
+    ...(data && { body: JSON.stringify(data) }),
+    headers: {
+      ...(isApiUrl && api.headers),
+      ...headers
+    },
+    credentials:
+      isApiUrl && api.cors?.credentials
+        ? 'include'
+        : 'same-origin',
+    signal
+  })
+
+  if (response.headers.get('Content-Type')?.includes('application/json')) {
+    response.data = await response.json()
+  }
+
+  if (!response.ok) {
+    throw new RequestError(response)
+  }
+  return response
+}
+
+export function isApiUrl(api, url) {
+  return !isAbsoluteUrl(url) || url.startsWith(api.url)
+}
+
+export function getApiUrl(api, { url, query }) {
+  if (!url.startsWith(api.url) && !isAbsoluteUrl(url)) {
+    url = combineUrls(api.url, url)
+  }
+  // Support optional query parameters, to be are added to the URL.
+  const search = formatQuery(query)
+  return search ? `${url}${url.includes('?') ? '&' : '?'}${search}` : url
+}
+
+function combineUrls(baseUrl, relativeUrl) {
+  // Use same approach as axios `combineURLs()` to join baseUrl & relativeUrl:
+  return `${baseUrl.replace(/\/+$/, '')}/${relativeUrl.replace(/^\/+/, '')}`
+}

package/src/utils/schema/data.js

@@ -16,6 +16,7 @@ import {
   someNestedSchemaComponent,
   hasNestedSchemaComponents,
   isPanelWithOwnData,
+  isSourceWithResource,
   isNested
 } from './structure.js'
 import {
@@ -126,10 +127,13 @@ export function shouldIgnoreMissingValue(schema, context) {
 // is missing in `data`: if there's no value, or if the value is `null` and
 // the type treats that as missing, e.g. nested sections.
 export function isMissingValue(schema, data, name, context) {
+  // Only read the value if needed, so that callers that are tracked, e.g. the
+  // walk of the form model's data, don't depend on all values.
   return (
-    !(name in data) ||
-    data[name] === null &&
-    !!getTypeOptions(schema)?.treatNullAsMissing?.(getContext(context))
+    !(name in data) || (
+      !!getTypeOptions(schema)?.treatNullAsMissing?.(getContext(context)) &&
+      data[name] === null
+    )
   )
 }
 
@@ -150,6 +154,22 @@ export function getMultipleValue(schema) {
   return schema.multiple ?? !!getTypeOptions(schema)?.defaultMultiple
 }
 
+/**
+ * Returns whether the value of the component described by `schema` and `name`
+ * is missing in `data` and needs its default, see `initializeData()`.
+ * `shouldSetDefaultsOfComponentsWithCompute` decides for components with
+ * `compute()`, which may derive their missing values instead.
+ */
+export function shouldSetDefaultValue(schema, data, name, context, {
+  shouldSetDefaultsOfComponentsWithCompute = true
+} = {}) {
+  return (
+    (shouldSetDefaultsOfComponentsWithCompute || !schema.compute) &&
+    isMissingValue(schema, data, name, context) &&
+    !shouldIgnoreMissingValue(schema, context)
+  )
+}
+
 /**
  * Initializes `data` for the components of `schema`: Sets missing values to
  * their defaults, so they can be correctly watched for changes, and numbers
@@ -160,6 +180,7 @@ export function initializeData(schema, data = {}, component, {
   dataPath = null,
   rootData = data,
   shouldProcess,
+  shouldSkipSourcesWithResource = false,
   // Whether to also set the defaults of components with `compute()`. New data
   // starts with all defaults, which `compute()` can rely on. In data that was
   // loaded, `compute()` may derive missing values instead, and they fall back
@@ -177,11 +198,14 @@ export function initializeData(schema, data = {}, component, {
         dataPath,
         rootData
       })
-    if (
-      (shouldSetDefaultsOfComponentsWithCompute || !schema.compute) &&
-      isMissingValue(schema, data, name, context) &&
-      !shouldIgnoreMissingValue(schema, context)
-    ) {
+    const shouldSetDefault = shouldSetDefaultValue(
+      schema,
+      data,
+      name,
+      context,
+      { shouldSetDefaultsOfComponentsWithCompute }
+    )
+    if (shouldSetDefault) {
       data[name] = getDefaultValue(schema, context)
     }
     if (hasItemsNumberedByOrderKey(schema) && isArray(data[name])) {
@@ -193,6 +217,7 @@ export function initializeData(schema, data = {}, component, {
     dataPath,
     before,
     shouldProcess,
+    shouldSkipSourcesWithResource,
     options
   })
 }
@@ -203,8 +228,9 @@ export function initializeData(schema, data = {}, component, {
  * value in `data`, or its default if it's missing. Never writes into `data`:
  * Computed values, including the defaults of components with `compute()`, are
  * written by `FormModel`, and other defaults when the data is set up, see
- * `initializeData()`. If provided, `getOptions()` returns the
- * options for `context.options`, called only when they're read.
+ * `initializeData()`, or when they go missing later, see `FormModel`. If
+ * provided, `getOptions()` returns the options for `context.options`, called
+ * only when they're read.
  */
 export function computeValue(schema, data, name, dataPath, {
   component = null,
@@ -406,17 +432,37 @@ export function processData(schema, sourceSchema, data, dataPath, {
  * returns `false` are skipped along with their content. The entries passed to
  * them contain the `componentPath` of the component, tab or panel, continuing
  * `componentPath` like `DitoMixin.componentPath` does.
+ *
+ * With `shouldSkipSourcesWithResource`, sources with their own resource are
+ * skipped along with their items, which they load and save through their
+ * resource, but not their panels, which display the data that contains them,
+ * see `DitoContainer.panelEntries`.
+ *
+ * The primitive values of lists with `wrapPrimitives` are walked wrapped in
+ * objects under the `wrapPrimitives` key, like the admin edits them, see
+ * `SourceMixin`. `wrappedPrimitiveName` is that key while walking such an
+ * object, and its component keeps the data path of the item, where the admin
+ * maps errors of the value to. Values written into the objects don't reach
+ * the data, e.g. defaults, as the primitive values themselves are the data.
  */
 export function processSchemaData(schema, data, {
   dataPath = null,
   componentPath = '',
   processedData = null,
+  wrappedPrimitiveName = null,
   before = null,
   after = null,
   shouldProcess = () => true,
+  shouldSkipSourcesWithResource = false,
   options
 }) {
-  const walkOptions = { before, after, shouldProcess, options }
+  const walkOptions = {
+    before,
+    after,
+    shouldProcess,
+    shouldSkipSourcesWithResource,
+    options
+  }
   const getDataPath = (dataPath, token) =>
     dataPath != null
       ? appendDataPath(dataPath, token)
@@ -426,9 +472,11 @@ export function processSchemaData(schema, data, {
     if (components) {
       for (const [name, componentSchema] of Object.entries(components)) {
         const isNestedComponent = isNested(componentSchema)
-        const componentDataPath = isNestedComponent
-          ? getDataPath(dataPath, name)
-          : dataPath
+        const isWrappedPrimitive = name === wrappedPrimitiveName
+        const componentDataPath =
+          isNestedComponent && !isWrappedPrimitive
+            ? getDataPath(dataPath, name)
+            : dataPath
         const entry = {
           schema: componentSchema,
           data,
@@ -440,6 +488,13 @@ export function processSchemaData(schema, data, {
         if (!shouldProcess(entry)) {
           continue
         }
+        if (
+          shouldSkipSourcesWithResource &&
+          isSourceWithResource(componentSchema)
+        ) {
+          processTabOrPanelSchemas(componentSchema.panels, entry.componentPath)
+          continue
+        }
         if (isPanelWithOwnData(componentSchema)) {
           // The components of panels with their own data don't edit `data`.
           continue
@@ -453,12 +508,12 @@ export function processSchemaData(schema, data, {
             processedData
           })
         } else {
+          const { wrapPrimitives } = componentSchema
           const processItem = (item, index = null) => {
-            if (!isObject(item)) {
-              // Items that aren't objects can't hold component values, e.g.
-              // the unwrapped values of lists with `wrapPrimitives` when
-              // walking data that isn't processed.
-              return item
+            // Data that isn't processed holds the primitive values themselves,
+            // processed data holds them wrapped already, see `processData()`.
+            if (wrapPrimitives && !isObject(item)) {
+              item = { [wrapPrimitives]: item }
             }
             const itemDataPath =
               index !== null
@@ -489,7 +544,8 @@ export function processSchemaData(schema, data, {
                 ...walkOptions,
                 dataPath: itemDataPath,
                 componentPath: itemComponentPath,
-                processedData: processedItem
+                processedData: processedItem,
+                wrappedPrimitiveName: wrapPrimitives ?? null
               })
             } else {
               // Items without a matching form, e.g. of an unknown type, are
@@ -500,29 +556,38 @@ export function processSchemaData(schema, data, {
 
           before?.(entry)
 
-          let value = processedData ? processedData[name] : data[name]
-          if (value != null && hasFormSchema(componentSchema)) {
-            // Recursively process data on nested form items.
-            if (isArray(value)) {
-              // Optimization: No need to collect values if we're not cloning!
-              value = processedData
-                ? value.map(processItem)
-                : value.forEach(processItem)
-            } else {
-              value = processItem(value)
-            }
-            if (processedData) {
-              processedData[name] = value
+          // Only read the values of sources with forms, so that callers that
+          // are tracked, e.g. the walk of the form model's data, don't depend
+          // on all values.
+          if (hasFormSchema(componentSchema)) {
+            let value = processedData ? processedData[name] : data[name]
+            if (value != null) {
+              // Recursively process data on nested form items.
+              if (isArray(value)) {
+                // Optimization: No need to collect values if not cloning!
+                value = processedData
+                  ? value.map(processItem)
+                  : value.forEach(processItem)
+              } else {
+                value = processItem(value)
+              }
+              if (processedData) {
+                processedData[name] = value
+              }
             }
           }
 
           after?.(entry)
+          // The panels of nested components display the data that contains
+          // the components, like the ones of unnested components, see
+          // `DitoContainer.panelEntries`.
+          processTabOrPanelSchemas(componentSchema.panels, entry.componentPath)
         }
       }
     }
   }
 
-  const processTabOrPanelSchemas = schemas => {
+  const processTabOrPanelSchemas = (schemas, parentComponentPath) => {
     // Tabs and panels add their names to component paths, not to data paths.
     for (const [name, tabOrPanelSchema] of Object.entries(schemas || {})) {
       const entry = {
@@ -530,7 +595,7 @@ export function processSchemaData(schema, data, {
         data,
         name: null,
         dataPath,
-        componentPath: appendDataPath(componentPath, name),
+        componentPath: appendDataPath(parentComponentPath, name),
         processedData
       }
       // The components of panels with their own data don't edit `data`.
@@ -541,8 +606,8 @@ export function processSchemaData(schema, data, {
   }
 
   processComponents(schema.components, componentPath)
-  processTabOrPanelSchemas(schema.tabs)
-  processTabOrPanelSchemas(schema.panels)
+  processTabOrPanelSchemas(schema.tabs, componentPath)
+  processTabOrPanelSchemas(schema.panels, componentPath)
 
   return processedData || data
 }

package/src/utils/schema/lookup.js

@@ -176,27 +176,10 @@ export function getButtonSchemas(buttons) {
   )
 }
 
-export function getPanelEntry(
-  schema,
-  dataPath = null,
-  componentPath = '',
-  tabComponent = null
-) {
-  return schema
-    ? {
-        schema,
-        // If the panel provides its own name, append it to the paths. This is
-        // used e.g. for $filters panels.
-        dataPath:
-          dataPath != null && schema.name
-            ? appendDataPath(dataPath, schema.name)
-            : dataPath,
-        componentPath: schema.name
-          ? appendDataPath(componentPath, schema.name)
-          : componentPath,
-        tabComponent
-      }
-    : null
+// 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
 }
 
 export function getPanelEntries(
@@ -224,8 +207,9 @@ export function getPanelEntries(
 
 // Returns the entries of the panel that the type of the component described by
 // `schema` provides, and of the panels in `schema.panels`. The type's panel is
-// addressed relative to `dataPath` and its component path,
-// `dataPathComponentPath`, while the panels in `schema.panels` continue
+// addressed by its name, e.g. `$filters`, relative to `dataPath` and its
+// component path, `dataPathComponentPath`, while the panels in `schema.panels`
+// are addressed by their keys, see `getPanelEntries()`, continuing
 // `schemaComponentPath`, the component path of `schema` itself, which also
 // contains the names of unnested components.
 export function getAllPanelEntries(
@@ -247,8 +231,8 @@ export function getAllPanelEntries(
     ? [
         getPanelEntry(
           panelSchema,
-          dataPath,
-          dataPathComponentPath,
+          appendDataPath(dataPath, panelSchema.name),
+          appendDataPath(dataPathComponentPath, panelSchema.name),
           tabComponent
         )
       ]

package/src/utils/schema/validation.js

@@ -2,7 +2,6 @@ import DitoContext from '../../DitoContext.js'
 import * as validators from '../../validators/index.js'
 import { isFunction, isRegExp, asArray, normalizeDataPath } from '@ditojs/utils'
 import { getTypeOptions } from './types.js'
-import { isSourceWithResource } from './structure.js'
 import {
   getSchemaValue,
   shouldRenderSchema,
@@ -86,10 +85,8 @@ export function getDataValidationErrors(schema, data, {
       rootData
     })
 
-  const shouldProcess = entry => (
-    !isSourceWithResource(entry.schema) &&
+  const shouldProcess = entry =>
     shouldRenderSchema(entry.schema, createContext(entry))
-  )
 
   const before = entry => {
     const { schema, data, name, dataPath } = entry
@@ -112,6 +109,7 @@ export function getDataValidationErrors(schema, data, {
   processSchemaData(schema, data, {
     dataPath,
     shouldProcess,
+    shouldSkipSourcesWithResource: true,
     before,
     options: { component, rootData }
   })

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`).
@@ -330,6 +344,11 @@ export interface BaseSchema<$Item>
    * 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>
   /**
@@ -797,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,