@ditojs/admin 3.1.3 → 3.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ditojs/admin",
-  "version": "3.1.3",
+  "version": "3.2.1",
   "type": "module",
   "description": "Dito.js Admin is a schema based admin interface for Dito.js Server, featuring auto-generated views and forms and built with Vue.js",
   "repository": "https://github.com/ditojs/dito/tree/main/packages/admin",
@@ -41,8 +41,8 @@
     "not ie_mob > 0"
   ],
   "dependencies": {
-    "@ditojs/ui": "^3.1.3",
-    "@ditojs/utils": "^3.1.3"
+    "@ditojs/ui": "^3.2.0",
+    "@ditojs/utils": "^3.2.0"
   },
   "peerDependencies": {
     "@kyvg/vue3-notification": "^3.4.2",
@@ -87,7 +87,7 @@
     "vue-upload-component": "^3.2.2"
   },
   "devDependencies": {
-    "@ditojs/build": "^3.1.3",
+    "@ditojs/build": "^3.2.0",
     "@kyvg/vue3-notification": "^3.4.2",
     "@tiptap/core": "^3.31.4",
     "@tiptap/extension-blockquote": "^3.31.4",
@@ -131,5 +131,5 @@
     "vue-router": "^5.3.1",
     "vue-upload-component": "^3.2.2"
   },
-  "gitHead": "3dba854ad248a56da1614122b960ad8a7eda70dd"
+  "gitHead": "c81ea5a206255d00588ea8b23f9df34af52cae01"
 }

package/src/mixins/TypeMixin.js

@@ -189,6 +189,7 @@ export default {
   created() {
     this._register(true)
     this.setupSchemaFields()
+    this.warnAboutUncomputedValue()
   },
 
   unmounted() {
@@ -196,6 +197,21 @@ export default {
   },
 
   methods: {
+    // Only the form model calls `compute()`, see `computeValue()`. Components
+    // that it doesn't visit, e.g. in panels with their own data, never get
+    // their values computed.
+    warnAboutUncomputedValue() {
+      if (
+        this.schema.compute &&
+        !this.formModel.hasComputedValueEntry(this.componentPath)
+      ) {
+        console.warn(
+          `The value of the component at '${this.componentPath}' isn't ` +
+          `computed, as its data isn't part of a form model.`
+        )
+      }
+    },
+
     _register(add) {
       // Provide component to container for schema accessor evaluation.
       this.$emit('update:component', add ? this : null)

package/src/mixins/ValueMixin.js

@@ -1,17 +1,25 @@
 import { isFunction } from '@ditojs/utils'
 import DitoContext from '../DitoContext.js'
-import { computeValue } from '../utils/schema/data.js'
+import { getValueOrDefault } from '../utils/schema/data.js'
 
 export default {
   computed: {
     value: {
       get() {
-        const value = computeValue(
+        // `FormModel` writes computed values into the data, see
+        // `computeValue()`.
+        const value = getValueOrDefault(
           this.schema,
           this.data,
           this.name,
-          this.dataPath,
-          { component: this }
+          () =>
+            DitoContext.createForSchema(this, {
+              schema: this.schema,
+              name: this.name,
+              data: this.data,
+              dataPath: this.dataPath,
+              rootData: this.rootData
+            })
         )
         // Only call `format()` if it's a function, as some types use `format`
         // for other purposes, e.g. `DitoTypeColor` for the color format.

package/src/utils/FormModel.js

@@ -92,7 +92,7 @@ export class FormModel {
       watch(
         [getSchema, getData],
         ([schema, data]) => this.initializeData(schema, data),
-        { immediate: true }
+        modelWatchOptions
       )
       // The entries are read through a computed property, so that the watchers
       // of the entries can check synchronously whether their entry is still
@@ -101,21 +101,23 @@ export class FormModel {
       watch(
         () => this.dataEntries.value.computedValueEntries,
         entries => this.updateComputedValueRecords(entries),
-        { immediate: true }
+        modelWatchOptions
       )
       // 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 }
+        modelWatchOptions
       )
       if (getSourceSchema) {
         // Data that is set up, e.g. loaded, saved or applied, isn't dirty:
+        // After the data is set up, as the watchers run in the order in which
+        // they're created, see `modelWatchOptions`.
         watch(
           getData,
           () => this.takeProcessedDataSnapshot().catch(console.error),
-          { immediate: true }
+          modelWatchOptions
         )
       }
     })
@@ -234,14 +236,14 @@ export class FormModel {
     const data = this.getData()
     return data && !isEmptySchema(schema)
       ? processData(schema, this.getSourceSchema(), data, this.dataPath, {
-          // Like `getComputedValue()`:
+          // Like `getComputedValueResult()`:
           component: this.component.mainSchemaComponent ?? this.component,
           rootData: this.rootData,
           schemaOnly: true,
           target: 'clipboard',
-          // Reading the dirty state doesn't call `compute()` and `process()`,
-          // see `processData()`:
-          shouldCallComputeAndProcess: false
+          // Reading the dirty state doesn't call `process()`, see
+          // `processData()`:
+          shouldCallProcess: false
         })
       : null
   }
@@ -417,15 +419,13 @@ export class FormModel {
           // Return a new object each time, so that the value is also written
           // when only the value in the data changed, e.g. through user input.
           () =>
-            isEntryCurrent.value
-              ? { value: this.getComputedValue(entry) }
-              : null,
+            isEntryCurrent.value ? this.getComputedValueResult(entry) : null,
           computedResult => {
             if (computedResult) {
               this.writeComputedValue(entry, computedResult.value)
             }
           },
-          { immediate: true }
+          modelWatchOptions
         )
       }
       if (hasValueFromDataSchema(entry.schema)) {
@@ -443,13 +443,19 @@ export class FormModel {
               this.writeComputedValue(entry, resolved.value)
             }
           },
-          { immediate: true }
+          modelWatchOptions
         )
       }
     })
     return scope
   }
 
+  // Returns whether the model computes the value of the component at the
+  // component path, i.e. whether its walk of the data visits the component.
+  hasComputedValueEntry(componentPath) {
+    return this.dataEntries.value.computedValueEntries.has(componentPath)
+  }
+
   // Returns whether the entry is still one of the current entries, with the
   // same schema and data, see `getDataEntries()`.
   isEntryCurrent({ componentPath, schema, data }) {
@@ -460,14 +466,37 @@ export class FormModel {
 
   // Calls `schema.compute()` with the main schema component of the data, like
   // `processData()`, and with the options resolved by the model, so that the
-  // result doesn't depend on whether the component is rendered.
-  getComputedValue(entry) {
+  // result doesn't depend on whether the component is rendered. Returns the
+  // value as `{ value }`, or `null` if `compute()` reads options that aren't
+  // loaded, which aborts it, so that the current value is kept until they are
+  // and `compute()` can rely on them. The watcher that calls it depends on the
+  // options through reading them, and calls it again once they're loaded.
+  getComputedValueResult(entry) {
     const { schema, data, name, dataPath } = entry
-    return computeValue(schema, data, name, dataPath, {
-      component: this.component.mainSchemaComponent ?? this.component,
-      rootData: this.rootData,
-      getOptions: schema.options ? () => this.getOptions(entry) : null
-    })
+    try {
+      const value = computeValue(schema, data, name, dataPath, {
+        component: this.component.mainSchemaComponent ?? this.component,
+        rootData: this.rootData,
+        getOptions: schema.options ? () => this.getLoadedOptions(entry) : null
+      })
+      return { value }
+    } catch (error) {
+      if (error === optionsNotLoaded) {
+        return null
+      }
+      throw error
+    }
+  }
+
+  // Returns the options of the component of the entry, or aborts the
+  // `compute()` that reads them, while they aren't loaded, see
+  // `getComputedValueResult()`.
+  getLoadedOptions(entry) {
+    const options = this.getOptions(entry)
+    if (options === undefined) {
+      throw optionsNotLoaded
+    }
+    return options
   }
 
   // Returns the options of the component of the entry, resolved from
@@ -612,6 +641,19 @@ function takeOverChangedValues(target, before, after) {
 
 const notFound = Symbol('notFound')
 
+// The watchers of the model run after the post-flush hooks, so that they write
+// the values that they derive from the data after the components that display
+// them are mounted. Otherwise, the `mounted` hooks of `v-model` directives
+// would restore the values that inputs had when they were mounted, see
+// https://github.com/vuejs/core/issues/15774. Vue processes the updates that
+// the written values cause in the same flush, before the browser renders them.
+// The watchers run in the order in which they're created.
+const modelWatchOptions = { immediate: true, flush: 'post' }
+
+// Aborts `compute()` when it reads options that aren't loaded, see
+// `FormModel.getComputedValueResult()`.
+const optionsNotLoaded = Symbol('optionsNotLoaded')
+
 // Returns whether the schema is a source of computed values, through
 // `schema.compute()` or a data schema of the `computed` types.
 function hasComputedValueSource(schema) {

package/src/utils/schema/data.js

@@ -227,9 +227,9 @@ export function initializeData(schema, data = {}, component, {
  * Returns the value of the component described by `schema` and `name` in
  * `data`: the result of `schema.compute()` if it returns a value, else the
  * 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()`, or when they go missing later, see `FormModel`. If
+ * `FormModel` is the only caller and writes the computed values, including the
+ * defaults of components with `compute()`. Other defaults are written when the
+ * data is set up, see `initializeData()`, or when they go missing later. If
  * provided, `getOptions()` returns the options for `context.options`, called
  * only when they're read.
  */
@@ -287,8 +287,10 @@ export function computeValue(schema, data, name, dataPath, {
 }
 
 // Returns the value in `data`, or its default if it's missing. `context` can be
-// a function that creates the context, called only when it's needed.
-function getValueOrDefault(schema, data, name, context) {
+// a function that creates the context, called only when it's needed. Computed
+// values are in `data` already, as `FormModel` writes them, see
+// `computeValue()`.
+export function getValueOrDefault(schema, data, name, context) {
   const shouldUseDefault = (
     isMissingValue(schema, data, name, context) &&
     !shouldIgnoreMissingValue(schema, context)
@@ -322,35 +324,33 @@ export function processData(schema, sourceSchema, data, dataPath, {
   rootData,
   schemaOnly, // whether to only include data covered by the schema, or all data
   target,
-  // Whether to call the schema callbacks `compute()` and `process()`. Data that
-  // is compared while it's edited, e.g. by `FormModel.isDirty`, isn't validated
-  // yet, which the callbacks may rely on, and `FormModel` writes the computed
-  // values into the data. Without them, the values in the data are used, or
-  // their defaults if they're missing, the types still process them through
-  // `processValue()`, and the excluded values of components with `process()`
-  // are kept, as `process()` may store them elsewhere through `processedItem`.
-  shouldCallComputeAndProcess = true
+  // Whether to call the schema callbacks `process()`. Data that is compared
+  // while it's edited, e.g. by `FormModel.isDirty`, isn't validated yet, which
+  // the callbacks may rely on. Without them, the types still process the values
+  // through `processValue()`, and the excluded values of components with
+  // `process()` are kept, as `process()` may store them elsewhere through
+  // `processedItem`. Computed values are in the data already, as `FormModel`
+  // writes them, see `computeValue()`.
+  shouldCallProcess = true
 } = {}) {
   const options = { component, rootData, schemaOnly, target }
   const processedData = cloneItem(sourceSchema, data, options)
   const graph = new SchemaGraph()
 
   const before = ({ schema, data, name, dataPath, processedData }) => {
-    let value = shouldCallComputeAndProcess
-      ? computeValue(schema, data, name, dataPath, options)
-      : getValueOrDefault(
+    let value = getValueOrDefault(
+      schema,
+      data,
+      name,
+      () =>
+        DitoContext.createForSchema(component, {
           schema,
-          data,
           name,
-          () =>
-            new DitoContext(component, {
-              schema,
-              name,
-              data,
-              dataPath,
-              rootData: options.rootData
-            })
-        )
+          data,
+          dataPath,
+          rootData: options.rootData
+        })
+    )
     // The schema expects the `wrapPrimitives` transformations to be present on
     // the data that it is applied on, so warp before and unwrap after.
     if (isArray(value)) {
@@ -400,13 +400,13 @@ export function processData(schema, sourceSchema, data, dataPath, {
 
     // Handle the user's `process()` callback next, if one is provided, so that
     // it can modify data in `processedData` even if it provides `exclude: true`
-    if (process && shouldCallComputeAndProcess) {
+    if (process && shouldCallProcess) {
       value = process(getContext(context))
     }
 
     // Without calling `process()`, keep the excluded values that it may store
-    // elsewhere, see `shouldCallComputeAndProcess`:
-    const shouldKeepExcludedValue = !!process && !shouldCallComputeAndProcess
+    // elsewhere, see `shouldCallProcess`:
+    const shouldKeepExcludedValue = !!process && !shouldCallProcess
     if (!shouldKeepExcludedValue && shouldExcludeValue(schema, context)) {
       delete processedData[name]
     } else {

package/types/index.d.ts

@@ -343,7 +343,11 @@ export interface BaseSchema<$Item>
    * 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.
+   * `undefined`, the current value is preserved. The
+   * value is computed into the data, which is what is
+   * displayed and saved. As the callback runs whenever
+   * the data it reads changes, it should only return a
+   * value and not change data.
    *
    * As it doesn't depend on the field's component, the
    * context's component properties, e.g. `component`
@@ -1995,9 +1999,10 @@ export type DitoContext<$Item = any> = {
   option: any
   /**
    * 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.
+   * loaded when first read, also when the field isn't rendered.
+   * Reading them while they load ends the callback, which keeps
+   * the current value and runs again once they are loaded, so
+   * they are always available in it.
    */
   options: any
   /**