@ditojs/admin 3.2.6 → 3.3.0

package/src/utils/FileDropTargets.js

@@ -0,0 +1,97 @@
+import { shallowRef } from 'vue'
+
+// FileDropTargets tracks the files that are dragged over the document, and the
+// elements that accept them, e.g. the ones of `DitoTypeUpload`, which handle
+// the dropped files themselves. The root of the admin creates one instance and
+// passes it the drag events of the document, see `DitoRoot`. A drag of files
+// only begins while there are targets, and only targets let files be dropped,
+// so that the browser doesn't open files dropped elsewhere.
+// `isDraggingFiles` is reactive.
+
+export class FileDropTargets {
+  #targets = new Set()
+  #isDraggingFiles = shallowRef(false)
+  // The number of elements that the drag entered and didn't leave yet, as
+  // `dragenter` and `dragleave` are triggered for each element.
+  #enteredElementCount = 0
+
+  get isDraggingFiles() {
+    return this.#isDraggingFiles.value
+  }
+
+  get hasTargets() {
+    return this.#targets.size > 0
+  }
+
+  // Adds `element` as a target, and returns the function that removes it.
+  add(element) {
+    this.#targets.add(element)
+    return () => {
+      this.#targets.delete(element)
+    }
+  }
+
+  // Returns whether `node` is a target or inside one.
+  isInTarget(node) {
+    for (const target of this.#targets) {
+      if (target.contains(node)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  // Returns the handlers of the drag events of the document, to be added to it
+  // by the owner of the instance.
+  getDocumentEventHandlers() {
+    return {
+      dragenter: event => this.#onDragEnter(event),
+      dragleave: event => this.#onDragLeave(event),
+      dragover: event => this.#onDragOver(event),
+      drop: event => this.#onDrop(event)
+    }
+  }
+
+  #onDragEnter(event) {
+    if (isDraggingFiles(event)) {
+      this.#enteredElementCount++
+      if (this.#enteredElementCount === 1 && this.hasTargets) {
+        this.#isDraggingFiles.value = true
+      }
+    }
+  }
+
+  #onDragLeave(event) {
+    if (isDraggingFiles(event) && this.#enteredElementCount > 0) {
+      this.#enteredElementCount--
+      if (this.#enteredElementCount === 0) {
+        this.#isDraggingFiles.value = false
+      }
+    }
+  }
+
+  #onDragOver(event) {
+    if (isDraggingFiles(event)) {
+      if (this.isInTarget(event.target)) {
+        // The target allows the drop by preventing the default itself.
+        event.dataTransfer.dropEffect = 'copy'
+      } else {
+        // Prevent the default, which opens the files in the browser, and show
+        // that they can't be dropped here instead.
+        event.preventDefault()
+        event.dataTransfer.dropEffect = 'none'
+      }
+    }
+  }
+
+  #onDrop(event) {
+    if (isDraggingFiles(event)) {
+      this.#enteredElementCount = 0
+      this.#isDraggingFiles.value = false
+    }
+  }
+}
+
+function isDraggingFiles(event) {
+  return !!event.dataTransfer?.types?.includes('Files')
+}

package/src/utils/ItemStores.js

@@ -0,0 +1,31 @@
+import { markRaw, reactive } from 'vue'
+
+// The stores of the items of a source, see `DitoMixin.getStore()`, keyed by
+// the uids of the items, see `getItemUid()`, so that each item keeps its store
+// when items are inserted, moved or removed. They are kept in the store of the
+// source, so that they live as long as it.
+export class ItemStores {
+  #storesByUid = new Map()
+
+  // Returns the item stores kept in `store`, the store of a source.
+  static getFromStore(store) {
+    store.$itemStores ??= markRaw(new ItemStores())
+    return store.$itemStores
+  }
+
+  // Returns the store of the item with `uid`, created on first access. This
+  // happens while rendering the item, which is safe as the map of the stores
+  // isn't reactive, only the stores themselves are.
+  getStore(uid) {
+    let store = this.#storesByUid.get(uid)
+    if (!store) {
+      store = reactive({})
+      this.#storesByUid.set(uid, store)
+    }
+    return store
+  }
+
+  removeStore(uid) {
+    this.#storesByUid.delete(uid)
+  }
+}

package/src/utils/ListQuery.js

@@ -0,0 +1,115 @@
+import { pickBy } from '@ditojs/utils'
+import { formatQuery } from './route.js'
+
+// The query of a source that loads its list through its resource, e.g. its
+// scope, page, order and filters, see `ResourceMixin.queryParams`. The route
+// holds the query, so that the list can be linked and reloaded, and the store
+// of the source remembers it, so that the list shows it again when navigating
+// back to it, see `DitoMixin.getStore()`. All changes of the query go through
+// the router, and the source loads its list when the route query changes, see
+// the `$route` watcher in `SourceMixin`.
+export class ListQuery {
+  constructor({ router, getRoute, getSourceStore, getDefaultQuery }) {
+    this.router = router
+    this.getRoute = getRoute
+    this.getSourceStore = getSourceStore
+    this.getDefaultQuery = getDefaultQuery
+    // The navigation of the last `update()` while it is pending, with the
+    // query that it navigates to, see `whenNavigated()`.
+    this.pendingNavigation = null
+  }
+
+  // The stored query, with the defaults of the source for missing values.
+  get query() {
+    return this.withDefaults(this.getSourceStore().query)
+  }
+
+  // Navigates to the query with `changes`, e.g. `{ scope: 'published' }`.
+  // With `resetPage`, a set page is reset to the first one if the changes
+  // change the query, as the list then has other pages.
+  update(changes, { resetPage = false } = {}) {
+    const { query } = this
+    const changedQuery = removeEmptyValues({ ...query, ...changes })
+    if (isSameQuery(changedQuery, query)) {
+      return Promise.resolve()
+    }
+    if (resetPage && changedQuery.page != null) {
+      changedQuery.page = 0
+    }
+    const promise = this.router.push({
+      query: changedQuery,
+      // Preserve the hash for tabs:
+      hash: this.getRoute().hash
+    })
+    const navigation = { query: changedQuery, promise }
+    this.pendingNavigation = navigation
+    const settle = () => {
+      if (this.pendingNavigation === navigation) {
+        this.pendingNavigation = null
+      }
+    }
+    promise.then(settle, settle)
+    return promise
+  }
+
+  // Returns `null` if no navigation of `update()` is pending, or the route
+  // already holds its query. Otherwise returns a promise that resolves once
+  // it settled, to whether the route then holds its query, as the navigation
+  // may fail or be superseded, e.g. by a navigation guard.
+  whenNavigated() {
+    const navigation = this.pendingNavigation
+    if (!navigation || this.isRouteQuery(navigation.query)) {
+      return null
+    }
+    const hasNavigated = () => this.isRouteQuery(navigation.query)
+    return navigation.promise.then(hasNavigated, hasNavigated)
+  }
+
+  isRouteQuery(query) {
+    return isSameQuery(query, this.getRoute().query)
+  }
+
+  // Merges the stored query with the route query, so that the list shows the
+  // same query again when navigating back to it, while the route query can
+  // override it, e.g. through links. The route query is replaced with the
+  // merged query, so that it holds the defaults and the stored values too.
+  syncWithRoute() {
+    const route = this.getRoute()
+    const query = this.withDefaults({
+      ...this.getSourceStore().query,
+      ...route.query
+    })
+    this.getSourceStore().query = query
+    if (!isSameQuery(query, route.query)) {
+      this.router.replace({ query, hash: route.hash }).catch(console.error)
+    }
+  }
+
+  // Stores the query of the route after it changed, and returns whether it
+  // changed the stored query, which the source then needs to load.
+  setFromRoute(routeQuery) {
+    const query = this.withDefaults(routeQuery)
+    const hasChanged = !isSameQuery(query, this.query)
+    this.getSourceStore().query = query
+    return hasChanged
+  }
+
+  withDefaults(query) {
+    return removeEmptyValues({ ...this.getDefaultQuery(), ...query })
+  }
+}
+
+function removeEmptyValues(query) {
+  return pickBy(query, value => value != null)
+}
+
+// Compares queries like the route does, where all values are strings, and
+// regardless of the order of their keys.
+function isSameQuery(query1, query2) {
+  const getSearchParams = query => {
+    const searchParams = new URLSearchParams(formatQuery(query))
+    searchParams.sort()
+    return searchParams.toString()
+  }
+  return getSearchParams(query1) === getSearchParams(query2)
+}

package/src/utils/LoadingTracker.js

@@ -0,0 +1,76 @@
+import { shallowRef } from 'vue'
+
+// LoadingTracker counts the pending operations of a scope, e.g. the requests of
+// a resource component, of all components in a view, or of the whole admin.
+// Each operation is forwarded to the tracker of the enclosing scope, so that a
+// scope is loading as long as any operation within it is pending, regardless
+// of the order in which they finish. `isLoading` is reactive.
+
+export class LoadingTracker {
+  #pendingCount = shallowRef(0)
+
+  constructor(parent = null) {
+    this.parent = parent
+  }
+
+  get isLoading() {
+    return this.#pendingCount.value > 0
+  }
+
+  // The tracker of the outermost scope, e.g. to show that something is loading
+  // without disabling the scopes in between.
+  get root() {
+    return this.parent?.root ?? this
+  }
+
+  // Begins an operation in this scope and its enclosing ones, and returns the
+  // function that ends it. Ending an operation more than once has no effect.
+  begin() {
+    this.#pendingCount.value++
+    const endInParent = this.parent?.begin()
+    let isEnded = false
+    return () => {
+      if (!isEnded) {
+        isEnded = true
+        this.#pendingCount.value--
+        endInParent?.()
+      }
+    }
+  }
+
+  // Tracks the operation that `callback()` performs until its returned promise
+  // settles, and returns its result.
+  async track(callback) {
+    const end = this.begin()
+    try {
+      return await callback()
+    } finally {
+      end()
+    }
+  }
+}
+
+// A loading operation that is switched on and off instead of begun and ended,
+// for the deprecated `setLoading(isLoading)` methods. Switching it on while it
+// is on has no effect, as does switching it off while it is off.
+export class LoadingSwitch {
+  #tracker
+  #endOperation = null
+
+  constructor(tracker) {
+    this.#tracker = tracker
+  }
+
+  get isOn() {
+    return !!this.#endOperation
+  }
+
+  set(isOn) {
+    if (isOn) {
+      this.#endOperation ??= this.#tracker.begin()
+    } else {
+      this.#endOperation?.()
+      this.#endOperation = null
+    }
+  }
+}

package/src/utils/SchemaGraph.js

@@ -113,9 +113,10 @@ export class SchemaGraph {
           let id = value?.[idKey]
           if (id != null) {
             if (removeId) {
+              // Unrelated sources don't need their ids on the clipboard, not
+              // even temporary ones, since nothing references them.
               delete value[idKey]
-            }
-            if (referenceId || isTemporaryId(id)) {
+            } else if (referenceId || isTemporaryId(id)) {
               if (isTemporaryId(id)) {
                 id = id.slice(1)
               }

package/src/utils/Session.js

@@ -0,0 +1,151 @@
+import appState from '../appState.js'
+import DitoUser from '../DitoUser.js'
+
+// Session holds the logged in user of the admin, see `user`, and logs users in
+// and out through the `api.users` resources. The views depend on the user, so
+// the session resolves them for each login and clears them once the user is
+// logged out, see `ViewRegistry`.
+//
+// Logging in asks for the credentials through the user interface that the
+// admin's root component attaches, see `attachUserInterface()`, which also
+// notifies of authentication errors.
+
+export class Session {
+  #api
+  #viewRegistry
+  #redirectAfterLogin
+  #userInterface = null
+
+  constructor({ api, viewRegistry, redirectAfterLogin = null }) {
+    this.#api = api
+    this.#viewRegistry = viewRegistry
+    this.#redirectAfterLogin = redirectAfterLogin
+  }
+
+  // The logged in user, or `null`. Reactive, as it's kept in the app state.
+  get user() {
+    return appState.user
+  }
+
+  // Attaches the user interface of the session:
+  // - `requestLoginData()` asks for the credentials, and returns them, or
+  //   `null` if the user cancels.
+  // - `notify(options)` shows a notification.
+  // Returns the function that detaches it again.
+  attachUserInterface({ requestLoginData, notify }) {
+    const userInterface = { requestLoginData, notify }
+    this.#userInterface = userInterface
+    return () => {
+      if (this.#userInterface === userInterface) {
+        this.#userInterface = null
+      }
+    }
+  }
+
+  // Starts the session with the user of the server's session if there is one,
+  // or else asks to log in.
+  async start() {
+    if (await this.fetchUser()) {
+      await this.#resolveViews()
+    } else {
+      await this.login()
+    }
+  }
+
+  // Asks for the credentials and logs in with them, again after each failure,
+  // until it succeeds or the user cancels. Returns the user, or `null`.
+  async login() {
+    const loginData = await this.#userInterface?.requestLoginData()
+    if (!loginData) {
+      return null
+    }
+    let user
+    try {
+      const response = await this.#request(this.#api.users.login, loginData)
+      user = response.data.user
+    } catch (error) {
+      this.#notifyError(error)
+      return this.login()
+    }
+    if (this.#redirectAfterLogin) {
+      location.replace(this.#redirectAfterLogin)
+    } else {
+      this.#setUser(user)
+      await this.#resolveViews()
+    }
+    return user
+  }
+
+  async logout() {
+    try {
+      const response = await this.#request(this.#api.users.logout)
+      if (response.data.success) {
+        this.#setUser(null)
+      }
+    } catch (error) {
+      console.error(error)
+    }
+  }
+
+  // Fetches the user of the server's session, and returns it, or `null` if
+  // there is none, e.g. as the session expired.
+  async fetchUser() {
+    let user = null
+    try {
+      const response = await this.#request(this.#api.users.session)
+      user = response.data.user || null
+    } catch (error) {
+      this.#notifyError(error)
+    }
+    this.#setUser(user)
+    return user
+  }
+
+  // Makes sure that a user is logged in before requesting the API, and asks to
+  // log in if the session expired.
+  async ensureUser() {
+    if (!(await this.fetchUser())) {
+      await this.login()
+    }
+  }
+
+  #setUser(user) {
+    // Responses loaded with `cache: 'global'` belong to the user that loaded
+    // them, so they are dropped when the user logs out or another one logs in,
+    // but kept when the same user is fetched again, see `ensureUser()`:
+    if (!user || user.id !== appState.user?.id) {
+      appState.loadCache = {}
+    }
+    appState.user = user && Object.setPrototypeOf(user, DitoUser.prototype)
+    if (!user) {
+      this.#viewRegistry.clear()
+    }
+  }
+
+  // Resolves the views for the logged in user, and asks to log in again if
+  // they can't be resolved, e.g. as the API refuses the user.
+  async #resolveViews() {
+    if (!(await this.#viewRegistry.resolve())) {
+      await this.login()
+    }
+  }
+
+  #request(resource, data = null) {
+    const url = this.#api.getApiUrl({ url: this.#api.resources.any(resource) })
+    return this.#api.request({ method: resource.method, url, data })
+  }
+
+  #notifyError(error) {
+    const responseError = error.response?.data?.error || error
+    if (this.#userInterface) {
+      this.#userInterface.notify({
+        type: 'error',
+        error: responseError,
+        title: 'Authentication Error',
+        text: responseError
+      })
+    } else {
+      console.error(responseError)
+    }
+  }
+}

package/src/utils/ViewRegistry.js

@@ -0,0 +1,85 @@
+import { shallowRef } from 'vue'
+import { mapConcurrently } from '@ditojs/utils'
+import { resolveViews, setupView } from './schema/setup.js'
+
+// ViewRegistry resolves the schemas of the admin's views, sets up their routes,
+// and adds them to the router, replacing the routes of the previous resolve.
+// `Session` resolves the views anew for each login and clears them once the
+// user is logged out, as the schemas may depend on the user, e.g. on functions
+// or modules that request the API. `views` and `hasRoutes` are reactive.
+
+export class ViewRegistry {
+  #api
+  #router
+  #unresolvedViews
+  #viewComponent
+  #views = shallowRef({})
+  #removeRoutes = shallowRef(null)
+
+  constructor({ api, router, unresolvedViews, viewComponent }) {
+    this.#api = api
+    this.#router = router
+    this.#unresolvedViews = unresolvedViews
+    this.#viewComponent = viewComponent
+  }
+
+  // The resolved views, provided as `$views`, or an empty object until they
+  // are resolved and once they are cleared.
+  get views() {
+    return this.#views.value
+  }
+
+  // Whether the routes of the views were added to the router.
+  get hasRoutes() {
+    return !!this.#removeRoutes.value
+  }
+
+  // Resolves the views and replaces the routes of the previous resolve with
+  // theirs, keeping the current path. Returns `false` if the views couldn't be
+  // resolved, e.g. because the API refused a request of their schemas.
+  async resolve() {
+    let views
+    try {
+      views = await resolveViews(this.#unresolvedViews)
+    } catch (error) {
+      console.error(error)
+      return false
+    }
+    const routes = await mapConcurrently(
+      Object.entries(views),
+      ([name, schema]) =>
+        setupView(this.#viewComponent, this.#api, schema, name)
+    )
+    // Only provide the views once they are set up, as `DitoMenu` links to
+    // their paths.
+    this.#views.value = views
+    const { fullPath } = this.#router.currentRoute.value
+    this.#removeRoutes.value?.()
+    this.#removeRoutes.value = addRoutes(this.#router, [
+      {
+        name: 'root',
+        path: '/',
+        components: {}
+      },
+      ...routes.flat()
+    ])
+    this.#router.replace(fullPath)
+    return true
+  }
+
+  // Clears the views, e.g. once the user is logged out, and navigates home.
+  // Their routes stay until the views are resolved again.
+  clear() {
+    this.#views.value = {}
+    return this.#router.push('/')
+  }
+}
+
+function addRoutes(router, routes) {
+  const removers = routes.map(route => router.addRoute(route))
+  return () => {
+    for (const remove of removers) {
+      remove()
+    }
+  }
+}

package/src/utils/accessor.js

@@ -5,6 +5,14 @@ import {
   normalizeDataPath
 } from '@ditojs/utils'
 
+// Returns an accessor for computed properties that reads `keyOrDataPath` from
+// the schema, which can be overridden by setting the property. `get(value)`
+// can process the schema value further. Getters only receive the value if
+// they declare it as a parameter, as told by their `length`, so that getters
+// that don't need it don't evaluate the schema value. NOTE: Parameters with
+// default values and rest parameters don't count towards the `length`, so
+// getters need to declare the value as a plain parameter, e.g. `get(value)`
+// and not `get(value = null)`.
 export function getSchemaAccessor(
   keyOrDataPath,
   { type, default: def, get, set, callback = true } = {}
@@ -47,6 +55,10 @@ export function getSchemaAccessor(
   }
 }
 
+// Returns an accessor for computed properties that reads and writes `name` in
+// the component's store, see `DitoMixin.getStore()`. The default value is
+// returned for missing values without storing it, as getters shouldn't change
+// state. Only values that are set are stored.
 export function getStoreAccessor(name, { default: def, get, set } = {}) {
   return {
     get() {
@@ -54,10 +66,6 @@ export function getStoreAccessor(name, { default: def, get, set } = {}) {
       if (value === undefined && def !== undefined) {
         // Support `default()` functions:
         value = isFunction(def) ? def.call(this) : def
-        // Trigger setter by setting value and accessor to default:
-        this[name] = value
-        // Now access store again, for reactivity tracking
-        this.getStore(name)
       }
       // Allow the provided getter to further change or process the value
       // retrieved from the store:

package/src/utils/affixes.js

@@ -0,0 +1,33 @@
+// Returns the props of the `DitoInputAffixes` of the input of a type
+// component, by position: The prefix and suffix items come from
+// `schema.prefix` and `schema.suffix`. The suffix also holds the clear button
+// of clearable components with a value, and their info when they have no label
+// to show it, as the label component shows the info otherwise.
+export function getInputAffixesProps({
+  schema,
+  disabled,
+  clearable,
+  value,
+  label,
+  info,
+  context
+}) {
+  return {
+    prefix: {
+      items: schema.prefix ?? null,
+      disabled,
+      clearable: false,
+      hasValue: false,
+      inlineInfo: null,
+      parentContext: context
+    },
+    suffix: {
+      items: schema.suffix ?? null,
+      disabled,
+      clearable: !!clearable,
+      hasValue: value != null,
+      inlineInfo: (!label && info) || null,
+      parentContext: context
+    }
+  }
+}

package/src/utils/changeOnceEdited.js

@@ -0,0 +1,33 @@
+// Emits the change of a value that the user edits only once the editing is
+// done, e.g. once the input lost its focus, and not on every edit while it is
+// still ongoing. Values changed by code don't emit change events, as only the
+// edits marked through `markEdited()` count.
+// `isEditing()` returns whether the editing is still ongoing, and
+// `emitChange()` emits the change event.
+export function createChangeOnceEdited({ isEditing, emitChange }) {
+  // Whether the value was edited since the last change event. Not reactive,
+  // as nothing renders it.
+  let isEdited = false
+
+  return {
+    // Marks the value as edited, to emit its change once the editing is done.
+    markEdited() {
+      isEdited = true
+    },
+
+    // Emits the change if the value was edited and the editing is done. Call
+    // it after each edit and whenever the editing may have ended, e.g. on blur.
+    emitIfDone() {
+      if (isEdited && !isEditing()) {
+        isEdited = false
+        emitChange()
+      }
+    },
+
+    // Forgets the edits, e.g. when they are replaced by a value that emits its
+    // own change event.
+    reset() {
+      isEdited = false
+    }
+  }
+}