@ditojs/admin 3.2.6 → 3.3.0

package/src/mixins/DitoMixin.js

@@ -4,15 +4,16 @@ import {
   isFunction,
   equals,
   labelize,
-  hyphenate,
   format
 } from '@ditojs/utils'
 import appState from '../appState.js'
 import DitoContext from '../DitoContext.js'
 import EmitterMixin from './EmitterMixin.js'
 import { flattenViews } from '../utils/schema/setup.js'
+import { getSchemaEventEntries } from '../utils/schema/events.js'
 import { getSchemaValue, shouldRenderSchema } from '../utils/schema/data.js'
 import { getResource, getMemberResource } from '../utils/resource.js'
+import { getRequestCacheKey } from '../utils/request.js'
 import { appendDataPath, getRelativeDataPath } from '../utils/data.js'
 import { computed, reactive } from 'vue'
 
@@ -22,6 +23,7 @@ export default {
 
   inject: [
     'api',
+    'session',
     '$verbs',
     '$views',
     '$isPopulated',
@@ -34,7 +36,8 @@ export default {
     '$dialogComponent',
     '$dataModel',
     '$panelComponent',
-    '$tabComponent'
+    '$tabComponent',
+    '$loadingTracker'
   ],
 
   provide() {
@@ -73,7 +76,7 @@ export default {
     },
 
     user() {
-      return appState.user
+      return this.session.user
     },
 
     // $verbs, $verbs and $isPopulated are defined as functions, to preserve
@@ -206,11 +209,6 @@ export default {
     this.isMounted = true
   },
 
-  beforeCreate() {
-    const uid = nextUid++
-    Object.defineProperty(this, '$uid', { get: () => uid })
-  },
-
   methods: {
     labelize,
 
@@ -235,44 +233,11 @@ export default {
       delete this.store[key]
     },
 
-    getStoreKeyByIndex(index) {
-      return this.store.$keysByIndex?.[index]
-    },
-
-    setStoreKeyByIndex(index, key) {
-      this.store.$keysByIndex ??= {}
-      this.store.$keysByIndex[index] = key
-    },
-
-    getChildStore(key, index) {
-      let store = this.getStore(key)
-      if (!store && index != null) {
-        // When storing, temporary ids change to permanent ones and thus the key
-        // can change. To still find the store, we reference by index as well,
-        // to be able to find the store again after the item was saved.
-        const oldKey = this.getStoreKeyByIndex(index)
-        store = this.getStore(oldKey)
-        if (store) {
-          this.setStore(key, store)
-          this.removeStore(oldKey)
-        }
-      }
-      if (!store) {
-        store = this.setStore(key, reactive({}))
-      }
-      if (index != null) {
-        // temporary uid keys will change between persistence, so we need to
-        // assign the key to the index even when the store already existed.
-        this.setStoreKeyByIndex(index, key)
-      }
-      return store
-    },
-
-    removeChildStore(key, index) {
-      // GEt the child-store first, so that indices can be transferred over
-      // temporary id changes during persistence.
-      this.getChildStore(key, index)
-      this.removeStore(key)
+    // Returns the store of the child component named `name`, e.g. of the
+    // components of a pane. The stores of list items are kept separately, see
+    // `ItemStores`.
+    getChildStore(name) {
+      return this.getStore(name) ?? this.setStore(name, reactive({}))
     },
 
     getSchemaValue(
@@ -301,21 +266,6 @@ export default {
         : labelize(name) || ''
     },
 
-    getButtonAttributes(verb, subject = null, text = null) {
-      // Buttons that display text are named by it, others by what they act on
-      // if known, e.g. 'Add Section'.
-      const label = text
-        ? null
-        : `${labelize(verb)}${subject ? ` ${subject}` : ''}`
-      return {
-        class: `dito-button--${verb}`,
-        ...(label && {
-          'title': label,
-          'aria-label': label
-        })
-      }
-    },
-
     // TODO: Rename *Link() to *Route().
     getQueryLink(query) {
       return {
@@ -375,7 +325,7 @@ export default {
       method ||= resource?.method
       const checkUser = !internal && this.api.isApiUrl(url)
       if (checkUser) {
-        await this.rootComponent.ensureUser()
+        await this.session.ensureUser()
       }
       const response = await this.api.request({
         method,
@@ -390,7 +340,7 @@ export default {
         method === 'patch' &&
         equals(resource, getMemberResource(this.user.id, this.api.users))
       ) {
-        await this.rootComponent.fetchUser()
+        await this.session.fetchUser()
       }
       return response
     },
@@ -407,28 +357,24 @@ export default {
     request({ cache, ...options }) {
       // Allow caching of loaded data on two levels:
       // - 'global': cache globally, for the entire admin session
-      // - 'local': cache locally within the closest route component that is
-      //    associated with a resource and loads its own data.
-      const cacheParent = (
-        cache &&
-        {
-          global: this.appState,
-          local: this.dataComponent
-        }[cache]
-      )
-      const loadCache = cacheParent?.loadCache
-      // Build a cache key from the config:
+      // - 'local': cache locally within the closest route component, i.e. the
+      //   form or view, for as long as it is shown. Components outside of
+      //   route components, e.g. in dialogs, don't cache locally.
+      const loadCache =
+        cache === 'global'
+          ? this.appState.loadCache
+          : cache === 'local'
+            ? this.routeComponent?.loadCache
+            : null
+      // Requests to resources are told apart by the URLs that they resolve to:
+      const { resource } = options
       const cacheKey = (
         loadCache &&
-        `${
-          options.method || 'get'
-        } ${
-          options.url
-        } ${
-          JSON.stringify(options.query || '')
-        } ${
-          JSON.stringify(options.data || '')
-        }`
+        getRequestCacheKey({
+          ...options,
+          method: options.method || resource?.method,
+          url: options.url || (resource ? this.getResourceUrl(resource) : null)
+        })
       )
       if (loadCache && (cacheKey in loadCache)) {
         return loadCache[cacheKey]
@@ -438,7 +384,12 @@ export default {
       const res = this.sendRequest(options)
         .then(response => response.data)
         .catch(error => {
-          // Convert axios errors to normal errors
+          // Failed requests aren't cached, so they can be retried:
+          if (loadCache?.[cacheKey] === res) {
+            delete loadCache[cacheKey]
+          }
+          // Convert errors of responses with data, e.g. Dito.js errors, to
+          // errors with the message and properties of that data:
           const data = error.response?.data
           throw data
             ? Object.assign(new Error(data.message), data)
@@ -514,6 +465,7 @@ export default {
     setupMethods() {
       for (const [key, value] of Object.entries(this.schema.methods || {})) {
         if (isFunction(value)) {
+          warnAboutOverriddenMember(this, key, 'method')
           this[key] = value
         } else {
           console.error(`Invalid method definition: ${key}: ${value}`)
@@ -537,6 +489,7 @@ export default {
             ? getComputedAccessor(item)
             : null
         if (accessor) {
+          warnAboutOverriddenMember(this, key, 'computed property')
           Object.defineProperty(this, key, accessor)
         } else {
           console.error(
@@ -547,7 +500,7 @@ export default {
     },
 
     setupEvents() {
-      const { watch, events } = this.schema
+      const { watch } = this.schema
       if (watch) {
         const handlers = isFunction(watch) ? watch.call(this) : watch
         if (isObject(handlers)) {
@@ -565,33 +518,30 @@ export default {
         }
       }
 
-      const addEvent = (key, event, callback) => {
+      const eventEntries = getSchemaEventEntries(this.schema)
+      for (const { key, event, callback } of eventEntries) {
         if (isFunction(callback)) {
-          this.on(hyphenate(event), callback)
+          this.on(event, callback)
         } else {
           console.error(`Invalid event definition: ${key}: ${callback}`)
         }
       }
-
-      if (events) {
-        for (const [key, value] of Object.entries(events)) {
-          addEvent(key, key, value)
-        }
-      }
-      // Also scan schema for `on[A-Z]`-style callbacks and add them
-      // TODO: Deprecate one format or the other, in favour of only one way of
-      // doing things. Decide which one to remove.
-      for (const [key, value] of Object.entries(this.schema)) {
-        if (/^on[A-Z]/.test(key)) {
-          addEvent(key, key.slice(2), value)
-        }
-      }
     },
 
     emitEvent(event, {
       context = null,
-      parent = null
+      parent = null,
+      ...unsupportedOptions
     } = {}) {
+      const unsupportedKeys = Object.keys(unsupportedOptions)
+      if (unsupportedKeys.length > 0) {
+        // Values for the handlers are passed through `context`, e.g.
+        // `emitEvent('error', { context: { error } })`.
+        console.warn(
+          `Unsupported options for event '${event}': ` +
+          `${unsupportedKeys.join(', ')}. Pass them through \`context\`.`
+        )
+      }
       const hasListeners = this.hasListeners(event)
       const parentHasListeners = parent?.hasListeners(event)
       if (hasListeners || parentHasListeners) {
@@ -622,17 +572,15 @@ export default {
 
     // Waits until the data model settled: its loads finished, and it wrote the
     // values that it derives from the data, e.g. before submitting. Shows the
-    // spinner in the header while loads are pending, like requests do.
+    // spinner in the header while loads are pending, like requests do, but
+    // without disabling the view, as the user may still be editing.
     async waitUntilDataModelSettled() {
       await this.$nextTick()
       const { dataModel } = this
       if (dataModel?.hasPendingLoads) {
-        this.rootComponent.registerLoading(true)
-        try {
-          await dataModel.waitUntilSettled()
-        } finally {
-          this.rootComponent.registerLoading(false)
-        }
+        await this.$loadingTracker().root.track(() =>
+          dataModel.waitUntilSettled()
+        )
       }
     },
 
@@ -642,7 +590,26 @@ export default {
   }
 }
 
-let nextUid = 0
+// The keys of the members that the schemas define on components, through
+// `methods` and `computed`, to tell them apart from the component's own ones
+// when the schema is set up again.
+const schemaMemberKeysByComponent = new WeakMap()
+
+// Warns when the schema defines a method or computed property that overrides
+// a member of the component, e.g. a method or property of Dito.js itself.
+function warnAboutOverriddenMember(component, key, kind) {
+  let schemaMemberKeys = schemaMemberKeysByComponent.get(component)
+  if (!schemaMemberKeys) {
+    schemaMemberKeys = new Set()
+    schemaMemberKeysByComponent.set(component, schemaMemberKeys)
+  }
+  if (key in component && !schemaMemberKeys.has(key)) {
+    console.warn(
+      `The schema ${kind} '${key}' overrides a member of the component.`
+    )
+  }
+  schemaMemberKeys.add(key)
+}
 
 function getParentComponent(component, key) {
   const current = component[key]

package/src/mixins/DomMixin.js

@@ -3,27 +3,25 @@ import { addEvents } from '@ditojs/ui/src'
 
 // @vue/component
 export default {
-  data() {
-    return {
-      domHandlers: []
-    }
+  created() {
+    // Aborted when the component is unmounted, which removes all handlers that
+    // are still added then. Not reactive, and nothing is kept per handler.
+    this.domAbortController = new AbortController()
   },
 
   unmounted() {
-    for (const { remove } of this.domHandlers) {
-      remove()
-    }
-    this.domHandlers = []
+    this.domAbortController.abort()
   },
 
   methods: {
+    // Adds the event handlers to `element`, and returns an object with a
+    // `remove()` method that removes them again. Handlers that are still added
+    // when the component is unmounted are removed then.
     domOn(element, type, handler) {
-      const result = addEvents(
-        element,
-        isObject(type) ? type : { [type]: handler }
-      )
-      this.domHandlers.push(result)
-      return result
+      const events = isObject(type) ? type : { [type]: handler }
+      return addEvents(element, events, {
+        signal: this.domAbortController.signal
+      })
     }
   }
 }

package/src/mixins/EmitterMixin.js

@@ -46,8 +46,9 @@ export default {
 
     off(event, callback) {
       if (!arguments.length) {
-        // Remove all events
-        delete this.listeners
+        // Remove all events. Reset rather than `delete` the data property,
+        // which Vue's component proxy doesn't support.
+        this.listeners = null
       } else if (isArray(event)) {
         for (const ev of event) {
           this.off(ev, callback)

package/src/mixins/ItemMixin.js

@@ -1,10 +1,15 @@
 import DitoContext from '../DitoContext.js'
-import { isListSource } from '../utils/schema/structure.js'
 import { getItemFormSchema } from '../utils/schema/lookup.js'
-import { getItemId, getItemUid } from '../utils/schema/data.js'
+import { getItemUid } from '../utils/schema/data.js'
+import {
+  getItemIdOrIndex,
+  findItemIndexById,
+  getItemLabel
+} from '../utils/schema/item.js'
 import { appendDataPath } from '../utils/data.js'
-import { isObject, isString, isNumber, isFunction } from '@ditojs/utils'
 
+// Delegates to the item functions in `utils/schema/item.js`, with the data
+// path, context and `isTransient` state of the component that mixes it in.
 // @vue/component
 export default {
   methods: {
@@ -13,9 +18,10 @@ export default {
     getItemUid,
 
     getItemId(sourceSchema, item, index = null) {
-      return this.isTransient && index !== null
-        ? String(index)
-        : getItemId(sourceSchema, item)
+      return getItemIdOrIndex(sourceSchema, item, {
+        index,
+        isTransient: this.isTransient
+      })
     },
 
     getItemDataPath(sourceSchema, index) {
@@ -29,36 +35,18 @@ export default {
       return dataPath
     },
 
-    getItemStore(sourceSchema, item, index) {
-      return this.getChildStore(this.getItemUid(sourceSchema, item), index)
-    },
-
-    removeItemStore(sourceSchema, item, index) {
-      this.removeChildStore(this.getItemUid(sourceSchema, item), index)
-    },
-
     findItemIdIndex(sourceSchema, data, itemId) {
-      const index = this.isTransient
-        ? // For transient data, the index is used as the id
-          itemId
-        : data?.findIndex(
-            (item, index) => (
-              this.getItemId(sourceSchema, item, index) === itemId
-            )
-          )
-      return index !== -1 ? index : null
+      return findItemIndexById(sourceSchema, data, itemId, {
+        isTransient: this.isTransient
+      })
     },
 
+    // Returns the label of `item` as HTML, see `getItemLabel()`.
     getItemLabel(sourceSchema, item, {
       index = null,
       extended = false,
       asObject = false
     } = {}) {
-      const { itemLabel } = sourceSchema
-      if (!item || !extended && itemLabel === false) {
-        return null
-      }
-
       let dataPath
       const getDataPath = () =>
         (dataPath ??= this.getItemDataPath(sourceSchema, index))
@@ -69,74 +57,30 @@ export default {
           getItemFormSchema(sourceSchema, item, this.context)
         ))
 
-      let text
-      let prefix
-      let suffix
-      if (isFunction(itemLabel)) {
-        const label = itemLabel.call(
-          this,
-          new DitoContext(this, {
-            nested: false,
-            data: item,
-            value: item,
-            index,
+      return getItemLabel(sourceSchema, item, {
+        index,
+        extended,
+        asObject,
+        getFormLabel,
+        evaluateItemLabel: () =>
+          sourceSchema.itemLabel.call(
+            this,
+            new DitoContext(this, {
+              nested: false,
+              data: item,
+              value: item,
+              index,
 
-            get dataPath() {
-              return getDataPath()
-            },
+              get dataPath() {
+                return getDataPath()
+              },
 
-            get formLabel() {
-              return getFormLabel()
-            }
-          })
-        )
-        if (isObject(label)) {
-          ;({ text, prefix, suffix } = label)
-        } else {
-          text = label
-        }
-        // It's up to `itemLabel()` entirely to produce the label:
-        extended = false
-      } else if (isString(itemLabel) && !(itemLabel in item)) {
-        // `itemLabel` can be both a key, or simply a label.
-        text = itemLabel
-      } else {
-        // Look up the name on the item, by these rules:
-        // 1. If `itemLabel` is a string, use it as the property key
-        // 2. Otherwise, if there are columns, use the value of the first
-        // 3. Otherwise, see if the item has a property named 'name'
-        const { columns } = sourceSchema
-        const key = (
-          isString(itemLabel) && itemLabel ||
-          isListSource(sourceSchema) && columns && Object.keys(columns)[0] ||
-          'name'
-        )
-        const value = item[key]
-        // Only primitives display as a label. If the property holds an array
-        // or object, fall through to the auto-generated label.
-        text = isString(value) || isNumber(value) ? value : null
-      }
-      const hadLabel = !!text
-      // If no label was found so far, try to produce one from the index.
-      if (text == null) {
-        // Always use extended style when auto-generating labels from index/id:
-        extended = true
-        text =
-          isListSource(sourceSchema) && index !== null ? `${index + 1}` : ''
-      }
-      if (extended) {
-        const formLabel = getFormLabel()
-        if (formLabel) {
-          // If a label was provided, put in quotes when prefixed with the
-          // form label for the extended style:
-          text = `${formLabel} ${hadLabel ? `'${text}'` : text}`
-        }
-      }
-      return asObject
-        ? text || prefix || suffix
-          ? { text, prefix, suffix }
-          : null
-        : text
+              get formLabel() {
+                return getFormLabel()
+              }
+            })
+          )
+      })
     }
   }
 }

package/src/mixins/OptionsMixin.js

@@ -1,6 +1,6 @@
 import { toRaw } from 'vue'
 import DitoContext from '../DitoContext.js'
-import { hasViewSchema, getViewEditPath } from '../utils/schema/lookup.js'
+import { hasViewSchema } from '../utils/schema/lookup.js'
 import { getMultipleValue } from '../utils/schema/data.js'
 import { getSchemaAccessor } from '../utils/accessor.js'
 import { setTemporaryId, isReference } from '../utils/data.js'
@@ -207,12 +207,6 @@ export default {
       }
     }),
 
-    editPath() {
-      return this.editable && this.selectedValue
-        ? getViewEditPath(this.schema, this.selectedValue, this.context)
-        : null
-    },
-
     groupByLabel() {
       return this.groupBy ? 'label' : null
     },
@@ -241,16 +235,25 @@ export default {
       }
     },
 
-    'optionsResolver.lastLoadError'(error) {
+    // The error of the last load replaces the error of the previous one, e.g.
+    // when the options load again after the data is replaced.
+    'optionsResolver.lastLoadError'(error, previousError) {
+      if (previousError) {
+        this.removeError(getLoadErrorMessage(previousError))
+      }
       if (error) {
-        this.addError(error.message || error)
+        this.addError(getLoadErrorMessage(error))
       }
     }
   },
 
   methods: {
     getOptionKey(key) {
-      const [option] = this.activeOptions
+      const [firstEntry] = this.activeOptions
+      // Grouped options are looked up in their first group.
+      const option = this.groupBy
+        ? firstEntry?.[this.groupByOptions]?.[0]
+        : firstEntry
       return isObject(option) && key in option ? key : null
     },
 
@@ -297,13 +300,19 @@ export default {
       return this.relate && isObject(option) && option.id == null
     },
 
+    // Returns the option of the value, or the value itself without
+    // `optionValue`, as plain value options are their own values.
     getOptionForValue(value) {
-      const findOption = (options, value, groupBy) => {
-        // Search for the option object with the given value and return the
-        // whole object.
+      return this.optionValue ? this.findOptionForValue(value) : value
+    },
+
+    // Searches the options for the one with the given value, matched through
+    // `optionEquals` if provided, and returns it.
+    findOptionForValue(value) {
+      const findOption = (options, groupBy) => {
         for (const option of options) {
           if (groupBy) {
-            const found = findOption(option.options, value, null)
+            const found = findOption(option.options, null)
             if (found) {
               return found
             }
@@ -318,17 +327,17 @@ export default {
         }
       }
 
-      const { optionValue, groupBy } = this
-      return optionValue
-        ? (findOption(this.activeOptions, value, groupBy) ??
-          // Options filtered out of the active options, e.g. by a search, are
-          // still options of the value.
-          (
-            this.areOptionsFiltered
-              ? findOption(this.options, value, groupBy)
-              : undefined
-          ))
-        : value
+      const { groupBy } = this
+      return (
+        findOption(this.activeOptions, groupBy) ??
+        // Options filtered out of the active options, e.g. by a search, are
+        // still options of the value.
+        (
+          this.areOptionsFiltered
+            ? findOption(this.options, groupBy)
+            : undefined
+        )
+      )
     },
 
     // Returns the related object in the value with the given value of its
@@ -388,3 +397,7 @@ export default {
     return value
   }
 }
+
+function getLoadErrorMessage(error) {
+  return error.message || error
+}