@ditojs/admin 3.2.7 → 3.3.0

package/src/utils/clipboard.js

@@ -0,0 +1,55 @@
+import { reactive } from 'vue'
+
+// The clipboard data that the admin knows of, shared by all clipboard buttons:
+// The data last copied, or read from the system clipboard. Copied data also
+// serves as fallback when the system clipboard can't be read.
+const clipboardState = reactive({
+  data: null
+})
+
+// Counts the copies and the reads of the system clipboard, so that the result
+// of a read is ignored when a newer copy or read started in the meantime.
+let clipboardVersion = 0
+
+// Returns the clipboard data if it was copied from a schema named
+// `schemaName`, without the `$schema` marker, otherwise `null`. Reactive, so
+// it can be used in computed properties.
+export function getClipboardData(schemaName) {
+  if (!clipboardState.data) {
+    return null
+  }
+  const { $schema, ...data } = clipboardState.data
+  return $schema === schemaName ? data : null
+}
+
+export function hasClipboardData(schemaName) {
+  return !!getClipboardData(schemaName)
+}
+
+// Copies `data` of the schema named `schemaName`, marked with `$schema` so
+// that it can only be pasted into schemas of the same name.
+export async function copyClipboardData(schemaName, data) {
+  const clipboardData = data ? { $schema: schemaName, ...data } : null
+  clipboardVersion++
+  clipboardState.data = clipboardData
+  try {
+    const json = JSON.stringify(clipboardData, null, 2)
+    await navigator.clipboard?.writeText?.(json)
+  } catch (error) {
+    // The copied data remains available inside the admin.
+    console.error(error, error.name, error.message)
+  }
+}
+
+// Reads the system clipboard into the clipboard state. Throws a `SyntaxError`
+// when its content isn't JSON, and the errors of the Clipboard API, e.g. when
+// reading isn't permitted. In both cases, the state remains unchanged.
+export async function readClipboardData() {
+  const version = ++clipboardVersion
+  const json = await navigator.clipboard?.readText?.()
+  // Ignore the result if a newer copy or read started in the meantime, as it
+  // may be outdated, and keep the state if the clipboard is empty.
+  if (json && version === clipboardVersion) {
+    clipboardState.data = JSON.parse(json)
+  }
+}

package/src/utils/data.js

@@ -66,23 +66,28 @@ export function parseParentItemDataPath(dataPath, nested = false) {
   return null
 }
 
+// Returns `null` for items without a parent item, e.g. the root item.
 export function getParentItemDataPath(dataPath, nested = false) {
-  return normalizeDataPath(parseParentItemDataPath(dataPath, nested))
+  const path = parseParentItemDataPath(dataPath, nested)
+  return path ? normalizeDataPath(path) : null
 }
 
+// Returns `null` if there's no item at the data path, e.g. for removed items.
 export function getItem(rootItem, dataPath, nested = false) {
   const path = parseItemDataPath(dataPath, nested)
-  return path ? getValueAtDataPath(rootItem, path) : null
+  return path ? getValueAtDataPath(rootItem, path, () => null) : null
 }
 
+// Returns `null` if there's no parent item at the data path.
 export function getParentItem(rootItem, dataPath, nested = false) {
   const path = parseParentItemDataPath(dataPath, nested)
-  return path ? getValueAtDataPath(rootItem, path) : null
+  return path ? getValueAtDataPath(rootItem, path, () => null) : null
 }
 
 export function getLastDataPathToken(dataPath) {
-  const path = parseDataPath(dataPath)
-  return path[path.length - 1]
+  // `dataPath` is `null` for items without a parent, see
+  // `getParentItemDataPath()`.
+  return parseDataPath(dataPath)?.at(-1)
 }
 
 export function getLastDataPathName(dataPath) {

package/src/utils/dialogs.js

@@ -0,0 +1,59 @@
+// Confirmations, built on the promise-based and focus-trapped dialogs of
+// `DitoRoot.showDialog()`. `component` is the Dito component that asks, for
+// its `showDialog()`, `notify()` and `verbs`, see `DitoMixin`.
+import { labelize } from '@ditojs/utils'
+import DitoConfirmMessage from '../components/DitoConfirmMessage.vue'
+import { getTextFromHtml } from './html.js'
+
+export const transientNote = (
+  '<b>Note</b>: the parent still needs to be saved ' +
+  'in order to persist this change.'
+)
+
+// Asks the user to confirm the HTML `message` with a button for `verb`, and
+// resolves to whether they did. Cancel comes first, to be focused first.
+export async function confirm(component, { message, verb }) {
+  const result = await component.showDialog({
+    components: {
+      message: {
+        type: 'component',
+        component: DitoConfirmMessage,
+        label: false
+      }
+    },
+    buttons: {
+      cancel: {},
+      confirm: { type: 'submit', text: labelize(verb) }
+    },
+    data: { message },
+    settings: { label: getTextFromHtml(message) }
+  })
+  // The dialog resolves with its data when submitted, and with `undefined`
+  // when cancelled, see `DitoDialog.cancel()`.
+  return result !== undefined
+}
+
+// Asks the user to confirm the removal of the item with the HTML `label`, then
+// awaits `remove()`, which returns false if it failed, and notifies of the
+// removal. Transient removals still need the parent to be saved, so they are
+// confirmed with the verbs for removing instead of deleting, and note that.
+export async function confirmAndRemove(
+  component,
+  { label, isTransient, remove }
+) {
+  const { verbs } = component
+  const [verb, pastVerb] = isTransient
+    ? [verbs.remove, verbs.removed]
+    : [verbs.delete, verbs.deleted]
+  const isConfirmed = await confirm(component, {
+    message: `Do you really want to ${verb} ${label}?`,
+    verb
+  })
+  if (isConfirmed && (await remove()) !== false) {
+    component.notify({
+      type: isTransient ? 'info' : 'success',
+      title: 'Successfully Removed',
+      html: [`${label} was ${pastVerb}.`, isTransient && transientNote]
+    })
+  }
+}

package/src/utils/dragResize.js

@@ -0,0 +1,61 @@
+// Resizes the height of `element` through a resize handle, either by dragging
+// it with the pointer or with the arrow keys while it is focused. `onResize()`
+// receives each new height in pixels.
+
+// Starts dragging the resize handle from its `pointerdown` event. The pointer
+// is captured by the handle, so that the drag continues outside of it, and the
+// handlers are removed again when the drag ends.
+export function startDragResize(event, { element, onResize }) {
+  if (event.button !== 0) return
+  const handle = event.currentTarget
+  const { pointerId, clientY: startY } = event
+  const startHeight = getHeight(element)
+  const controller = new AbortController()
+  const { signal } = controller
+
+  const resize = event => {
+    if (event.pointerId === pointerId) {
+      onResize(Math.max(startHeight + event.clientY - startY, 0))
+    }
+  }
+
+  const stop = event => {
+    if (event.pointerId === pointerId) {
+      controller.abort()
+    }
+  }
+
+  handle.setPointerCapture(pointerId)
+  handle.addEventListener('pointermove', resize, { signal })
+  handle.addEventListener(
+    'pointerup',
+    event => {
+      resize(event)
+      stop(event)
+    },
+    { signal }
+  )
+  handle.addEventListener('pointercancel', stop, { signal })
+  handle.addEventListener('lostpointercapture', stop, { signal })
+}
+
+const resizeDirectionsByKey = {
+  ArrowUp: -1,
+  ArrowDown: 1
+}
+
+// Resizes by one step of the element's font size per `ArrowUp` / `ArrowDown`
+// `keydown` event on the focused resize handle, or by ten steps with Shift.
+export function resizeByArrowKey(event, { element, onResize }) {
+  const direction = resizeDirectionsByKey[event.key]
+  if (direction) {
+    event.preventDefault()
+    const fontSize = parseFloat(getComputedStyle(element).fontSize)
+    const step = event.shiftKey ? 10 * fontSize : fontSize
+    onResize(Math.max(getHeight(element) + direction * step, 0))
+  }
+}
+
+function getHeight(element) {
+  return parseFloat(getComputedStyle(element).height)
+}

package/src/utils/filter.js

@@ -1,4 +1,11 @@
-import { isArray, asArray, labelize } from '@ditojs/utils'
+import {
+  isArray,
+  isString,
+  asArray,
+  labelize,
+  normalizeDataPath,
+  parseDataPath
+} from '@ditojs/utils'
 import { getNamedSchemas } from './schema/lookup.js'
 import { applyNestedSchemaDefaults } from './schema/setup.js'
 
@@ -157,6 +164,27 @@ function getDataName(filterName) {
   return `$${filterName}`
 }
 
+// The server keys the validation errors of filters by filter name, e.g.
+// `title/text`, see the server's `models/definitions/filters.js`, while the
+// filters panel keys the filter data by data name, e.g. `$title`. Returns the
+// errors keyed by the data paths of the panel. Paths that already start with a
+// data name, and empty paths, are kept.
+export function getFiltersDataErrors(errors) {
+  const dataErrors = {}
+  for (const [dataPath, errs] of Object.entries(errors)) {
+    const [token, ...rest] = parseDataPath(normalizeDataPath(dataPath))
+    const filtersDataPath = [
+      !token || token.startsWith('$') ? token : getDataName(token),
+      ...rest
+    ].join('/')
+    dataErrors[filtersDataPath] = [
+      ...(dataErrors[filtersDataPath] ?? []),
+      ...errs
+    ]
+  }
+  return dataErrors
+}
+
 function getFilterName(dataName) {
   return dataName.startsWith('$') ? dataName.slice(1) : null
 }
@@ -240,7 +268,13 @@ function parseFiltersData(schema, query) {
   // from $route.query back to param lists per filter:
   if (query) {
     for (const filter of asArray(query.filter)) {
-      const [, filterName, json] = filter.match(/^(\w+):(.*)$/)
+      // Query values without a value, e.g. `?filter`, are `null`:
+      const match = isString(filter) ? filter.match(/^(\w+):(.*)$/) : null
+      if (!match) {
+        console.warn(`Ignoring malformed filter: '${filter}'`)
+        continue
+      }
+      const [, filterName, json] = match
       try {
         filters[filterName] = asArray(JSON.parse(`[${json}]`))
       } catch {}

package/src/utils/html.js

@@ -0,0 +1,9 @@
+// Returns the text of `html`, e.g. of labels, which are HTML with escaped item
+// values, see `getItemLabel()`: Unlike `stripHtml()`, this also unescapes the
+// escaped characters. Documents that `DOMParser` creates are inert: they don't
+// run scripts or load images. Returns `null` for `null` or `undefined`.
+export function getTextFromHtml(html) {
+  if (html == null) return null
+  const { body } = new DOMParser().parseFromString(html, 'text/html')
+  return body.textContent.trim()
+}

package/src/utils/list.js

@@ -0,0 +1,10 @@
+// Returns a copy of `list` with `item` moved by `delta` positions, e.g. by -1
+// to move it up by one, or `null` if `item` isn't in `list` or can't move that
+// far. The item is looked up by identity, see `DitoDragHandle`.
+export function getListWithMovedItem(list, item, delta) {
+  const index = list.indexOf(item)
+  const newIndex = index + delta
+  return index >= 0 && delta !== 0 && newIndex >= 0 && newIndex < list.length
+    ? list.toSpliced(index, 1).toSpliced(newIndex, 0, item)
+    : null
+}

package/src/utils/options.js

@@ -33,7 +33,11 @@ const ditoOptionKeys = [
   'defaultValue',
   'defaultNested',
   'defaultVisible',
+  'defaultMultiple',
+  'defaultWidth',
+  'getSourceType',
   'generateLabel',
+  'rendersOwnLabel',
   'excludeValue',
   'ignoreMissingValue',
   'treatNullAsMissing',

package/src/utils/registration.js

@@ -0,0 +1,18 @@
+// Registers `component` under its `componentPath` by calling
+// `register(add, componentPath)`, and registers it again under the new path
+// whenever its component path changes, e.g. when list items move, see
+// `DitoSchema._registerEntry()`. Returns a function that unregisters it, to be
+// called when the component is unmounted.
+export function trackRegistration(component, register) {
+  let registeredComponentPath = component.componentPath
+  register(true, registeredComponentPath)
+  const unwatch = component.$watch('componentPath', componentPath => {
+    register(false, registeredComponentPath)
+    registeredComponentPath = componentPath
+    register(true, componentPath)
+  })
+  return () => {
+    unwatch()
+    register(false, registeredComponentPath)
+  }
+}

package/src/utils/request.js

@@ -21,24 +21,16 @@ export async function request(api, {
   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 fetchOptions = getFetchOptions(api, url)
   const response = await fetch(api.getApiUrl({ url, query }), {
     method: method.toUpperCase(),
     ...(data && { body: JSON.stringify(data) }),
     headers: {
-      ...(isApiUrl && api.headers),
+      ...fetchOptions.headers,
       ...headers
     },
-    credentials:
-      isApiUrl && api.cors?.credentials
-        ? 'include'
-        : 'same-origin',
-    signal
+    credentials: fetchOptions.credentials,
+    signal: getRequestSignal({ signal, timeout })
   })
 
   if (response.headers.get('Content-Type')?.includes('application/json')) {
@@ -51,8 +43,111 @@ export async function request(api, {
   return response
 }
 
+// Returns the key under which the `request()` method of components, see
+// `DitoMixin`, caches the response of a request.
+export function getRequestCacheKey({ method, url, query, data }) {
+  return [
+    method || 'get',
+    url,
+    JSON.stringify(query || ''),
+    JSON.stringify(data || '')
+  ].join(' ')
+}
+
+// Returns the URL that downloads of `url` fetch and link to: Relative URLs
+// such as `files/1` are resolved against the API, while absolute and
+// root-relative URLs such as `/files/1` stay as they are, unlike in
+// `getApiUrl()`, which prefixes root-relative URLs with the API URL too.
+export function resolveDownloadUrl(api, url) {
+  return isAbsoluteUrl(url) || url.startsWith('/')
+    ? url
+    : api.getApiUrl({ url })
+}
+
+// Fetches the file at `url` as a blob, with the same authentication as
+// `request()`, e.g. for downloads of files that the API protects. `url` is
+// resolved through `resolveDownloadUrl()`.
+export async function fetchBlob(api, url) {
+  const downloadUrl = resolveDownloadUrl(api, url)
+  // Decide on the authentication with the absolute URL, as `isApiUrl()` treats
+  // all root-relative URLs as API URLs, the way `getApiUrl()` resolves them.
+  // Without `api.timeout`, as it would also cut off downloads of large files
+  // that take longer than any request.
+  const response = await fetch(
+    downloadUrl,
+    getFetchOptions(api, getAbsoluteUrl(downloadUrl))
+  )
+  if (!response.ok) {
+    throw new RequestError(response)
+  }
+  return response.blob()
+}
+
+// Returns the options for uploads to `url` through `XMLHttpRequest`, with the
+// same authentication as `request()`.
+export function getUploadOptions(api, url) {
+  const { headers, credentials } = getFetchOptions(api, url)
+  // Leave out the default JSON `Content-Type`, as uploads send multipart form
+  // data, the boundary of which `XMLHttpRequest` needs to set itself.
+  return {
+    headers: Object.fromEntries(
+      Object.entries(headers).filter(
+        ([name]) => name.toLowerCase() !== 'content-type'
+      )
+    ),
+    withCredentials: credentials === 'include'
+  }
+}
+
+// Returns the headers and credentials mode that requests to `url` send: Only
+// requests to the API receive its headers and, with CORS, its credentials.
+function getFetchOptions(api, url) {
+  const isApiUrl = api.isApiUrl(url)
+  return {
+    headers: { ...(isApiUrl && api.headers) },
+    credentials:
+      isApiUrl && api.cors?.credentials
+        ? 'include'
+        : 'same-origin'
+  }
+}
+
+// Returns a signal that aborts with `signal`, and after the timeout if there is
+// one, so that nothing waits for requests forever, e.g. submitting for pending
+// loads.
+function getRequestSignal({ signal = null, timeout = null }) {
+  const signals = [signal, timeout && AbortSignal.timeout(timeout)]
+  return AbortSignal.any(signals.filter(Boolean))
+}
+
+// Returns whether requests to `url` go to the API: Relative and root-relative
+// URLs do, as `getApiUrl()` resolves them against the API, and absolute URLs
+// do if they are under the API URL, compared in their absolute forms so that
+// a root-relative API URL such as `/api` matches too.
 export function isApiUrl(api, url) {
-  return !isAbsoluteUrl(url) || url.startsWith(api.url)
+  return (
+    !isAbsoluteUrl(url) ||
+    isUrlInside(getAbsoluteUrl(url), getAbsoluteUrl(api.url))
+  )
+}
+
+// Returns `url` resolved against the document's base URL.
+function getAbsoluteUrl(url) {
+  return new URL(url, document.baseURI).href
+}
+
+// Returns whether `url` is `baseUrl` or a URL under it, e.g. `/api/books` in
+// `/api`, but not `/api-docs`.
+function isUrlInside(url, baseUrl) {
+  if (!url.startsWith(baseUrl)) {
+    return false
+  }
+  const nextCharacter = url[baseUrl.length]
+  return (
+    baseUrl.endsWith('/') ||
+    nextCharacter === undefined ||
+    '/?#'.includes(nextCharacter)
+  )
 }
 
 export function getApiUrl(api, { url, query }) {

package/src/utils/route.js

@@ -33,21 +33,10 @@ export function formatQuery(query) {
   )
 }
 
-export function replaceRoute({ path, query, hash }) {
-  // Preserve `history.state`, see:
-  // https://router.vuejs.org/guide/migration/#usage-of-history-state
-  const { location } = window
-  history.replaceState(
-    history.state,
-    null,
-    `${
-      location.origin
-    }${
-      path ?? location.pathname
-    }?${
-      query ? formatQuery(query) : location.search.slice(1)
-    }${
-      hash ?? location.hash
-    }`
-  )
+// Returns true if `path` is `basePath` or one of its sub-paths, comparing
+// whole path segments, so that `/items/12` and `/items-archive` aren't within
+// `/items/1` and `/items`.
+export function isPathWithin(path, basePath) {
+  const prefix = basePath.endsWith('/') ? basePath : `${basePath}/`
+  return path === basePath || path.startsWith(prefix)
 }

package/src/utils/schema/data.js

@@ -91,6 +91,24 @@ export function shouldRenderSchema(schema, context) {
   )
 }
 
+// Returns the forms of `schema` for which items can be created, by type. Forms
+// are excluded by `if: false` or `creatable: false`.
+export function getCreatableForms(schema, context) {
+  return Object.fromEntries(
+    Object.entries(getFormSchemas(schema, context)).filter(
+      ([, form]) => (
+        shouldRenderSchema(form, context) &&
+        getSchemaValue('creatable', {
+          type: Boolean,
+          default: true,
+          schema: form,
+          context
+        })
+      )
+    )
+  )
+}
+
 function getContext(context) {
   return isFunction(context) ? context() : context
 }
@@ -242,7 +260,9 @@ export function initializeData(schema, data = {}, component, {
  * 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.
+ * only when they're read. `dataPath` can also be a function that returns it,
+ * called only when `compute()` reads the data path or values derived from it,
+ * e.g. `index` or `parentItem`, so that only these computes depend on it.
  */
 export function computeValue(schema, data, name, dataPath, {
   component = null,
@@ -264,7 +284,9 @@ export function computeValue(schema, data, name, dataPath, {
         },
         name,
         data,
-        dataPath,
+        get dataPath() {
+          return isFunction(dataPath) ? dataPath() : dataPath
+        },
         rootData
       }
       if (getOptions) {

package/src/utils/schema/events.js

@@ -0,0 +1,19 @@
+import { hyphenate } from '@ditojs/utils'
+
+// Returns the event handlers that `schema` defines, both in `events` and as
+// `on[A-Z]` callbacks, e.g. `events: { mouseenter }` and `onMouseenter`, with
+// the hyphenated event names that they are registered and emitted under.
+// TODO: Deprecate one format or the other, in favour of only one way of
+// doing things. Decide which one to remove.
+export function getSchemaEventEntries(schema) {
+  const entries = []
+  for (const [key, callback] of Object.entries(schema.events || {})) {
+    entries.push({ key, event: hyphenate(key), callback })
+  }
+  for (const [key, callback] of Object.entries(schema)) {
+    if (/^on[A-Z]/.test(key)) {
+      entries.push({ key, event: hyphenate(key.slice(2)), callback })
+    }
+  }
+  return entries
+}

package/src/utils/schema/item.js

@@ -0,0 +1,114 @@
+import {
+  isObject,
+  isString,
+  isNumber,
+  isFunction,
+  escapeHtml
+} from '@ditojs/utils'
+import { isListSource } from './structure.js'
+import { getItemId } from './data.js'
+
+// Returns the id of `item`, by which routes address it. Transient items aren't
+// stored yet and may lack ids, so they're addressed by their `index` instead,
+// when it's known.
+export function getItemIdOrIndex(
+  sourceSchema,
+  item,
+  { index = null, isTransient }
+) {
+  return isTransient && index !== null
+    ? String(index)
+    : getItemId(sourceSchema, item)
+}
+
+// Returns the index of the item in `items` that `itemId` addresses, see
+// `getItemIdOrIndex()`, or `null` if there is none. The ids of transient items
+// are their indices already, and are returned as they are.
+export function findItemIndexById(sourceSchema, items, itemId, {
+  isTransient
+}) {
+  const index = isTransient
+    ? itemId
+    : items?.findIndex(item => getItemId(sourceSchema, item) === itemId)
+  return index != null && index !== -1 ? index : null
+}
+
+// Returns the label of `item` as HTML: Values of the item are escaped,
+// while labels that the schema provides, e.g. through `itemLabel()`, can
+// contain HTML, so they need to escape the values that they include.
+// The label depends on the component that displays the item through two
+// callbacks: `evaluateItemLabel()` calls `sourceSchema.itemLabel()` with the
+// item's context, and `getFormLabel()` returns the label of the item's form.
+export function getItemLabel(
+  sourceSchema,
+  item,
+  {
+    index = null,
+    extended = false,
+    asObject = false,
+    evaluateItemLabel,
+    getFormLabel
+  }
+) {
+  const { itemLabel } = sourceSchema
+  if (!item || !extended && itemLabel === false) {
+    return null
+  }
+
+  let text
+  let prefix
+  let suffix
+  if (isFunction(itemLabel)) {
+    const label = evaluateItemLabel()
+    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. Strings are
+    // escaped, as the label is rendered as HTML.
+    text = isString(value)
+      ? escapeHtml(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
+}