@antelopejs/dms 0.5.5 → 0.6.0

package/frontend-vue/layers/dms-ui/app/build/composables/form/keyValueRows.ts

@@ -0,0 +1,64 @@
+/** A pair as the key-value editor shows it: a row of the repeater. */
+export interface KeyValueRow {
+  key?: string;
+  value?: unknown;
+  /** Whether the pair is on (`toggleable` editors only). */
+  enabled?: boolean;
+}
+
+/** A pair's value in a `toggleable` editor. */
+interface ToggledValue {
+  value: unknown;
+  enabled: boolean;
+}
+
+const KEY_MISSING = "$dms.field_errors.key_missing";
+const KEY_DUPLICATE = "$dms.field_errors.key_duplicate";
+
+const nameOf = (row: KeyValueRow): string => (row.key ?? "").trim();
+const isBlank = (value: unknown): boolean =>
+  value === undefined || value === null || value === "";
+const isUnfilled = (row: KeyValueRow): boolean =>
+  !nameOf(row) && isBlank(row.value);
+
+/** The rows of a key-value object, in its order. */
+export function keyValueRows(
+  value: Record<string, unknown> | null | undefined,
+  toggleable: boolean | undefined,
+): KeyValueRow[] {
+  return Object.entries(value ?? {}).map(([key, entry]) => {
+    if (!toggleable) return { key, value: entry };
+    const toggled = (entry ?? {}) as Partial<ToggledValue>;
+    return { key, value: toggled.value, enabled: toggled.enabled ?? true };
+  });
+}
+
+/** The object the rows stand for, the rows nobody filled left out. */
+export function keyValueObject(
+  rows: readonly KeyValueRow[],
+  toggleable: boolean | undefined,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    rows
+      .filter((row) => !isUnfilled(row))
+      .map((row) => [
+        nameOf(row),
+        toggleable
+          ? { value: row.value ?? null, enabled: row.enabled ?? true }
+          : row.value,
+      ]),
+  );
+}
+
+/**
+ * What keeps the rows from being an object (an i18n key): a value without
+ * a name, or a name given twice.
+ */
+export function keyValueProblem(
+  rows: readonly KeyValueRow[],
+): string | undefined {
+  const filled = rows.filter((row) => !isUnfilled(row));
+  if (filled.some((row) => !nameOf(row))) return KEY_MISSING;
+  const names = filled.map(nameOf);
+  return new Set(names).size === names.length ? undefined : KEY_DUPLICATE;
+}

package/frontend-vue/layers/dms-ui/app/build/composables/form/tagValues.ts

@@ -0,0 +1,43 @@
+/** What the tags of a tags field are (interface-dms `TagItemType`). */
+export type TagItemType = "string" | "email";
+
+export interface AddTagsOptions {
+  itemType?: TagItemType;
+  max?: number;
+}
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// Addresses compare in lower case: "Ann@acme.io" is the one "ann@acme.io".
+const NORMALIZERS: Record<TagItemType, (item: string) => string> = {
+  string: (item) => item.trim(),
+  email: (item) => item.trim().toLowerCase(),
+};
+
+/**
+ * The items of a tags field once more are added: each trimmed (an address
+ * in lower case), a repeated one ignored, none past `max`.
+ */
+export function addTags(
+  current: readonly string[],
+  incoming: readonly string[],
+  options: AddTagsOptions = {},
+): string[] {
+  const normalize = NORMALIZERS[options.itemType ?? "string"];
+  const next: string[] = [];
+  for (const item of [...current, ...incoming].map(normalize)) {
+    if (!item || next.includes(item)) continue;
+    if (options.max !== undefined && next.length >= options.max) break;
+    next.push(item);
+  }
+  return next;
+}
+
+/** The items a field of this type refuses: an address that is none. */
+export function invalidTags(
+  items: readonly string[],
+  itemType: TagItemType | undefined,
+): string[] {
+  if (itemType !== "email") return [];
+  return items.filter((item) => !EMAIL_PATTERN.test(item));
+}

package/frontend-vue/layers/dms-ui/app/build/composables/form/useControlError.ts

@@ -0,0 +1,34 @@
+import { formFieldInjectionKey } from "@nuxt/ui/composables/useFormField";
+import { type InjectionKey, inject, onBeforeUnmount, ref } from "vue";
+
+/** Where a form collects the errors its controls report, by field id. */
+export interface FormControlErrors {
+  report: (fieldId: string, message: string | undefined) => void;
+}
+
+export const FORM_CONTROL_ERRORS_KEY: InjectionKey<FormControlErrors> = Symbol(
+  "dms-form-control-errors",
+);
+
+/**
+ * Lets a control refuse what was typed into it (a duration or JSON it cannot
+ * read): inside a form, the message becomes the field's error, which blocks
+ * the submit and joins the form's summary like any other. `message` holds it
+ * for a control used outside a form.
+ */
+export function useControlError() {
+  const field = inject(formFieldInjectionKey, undefined);
+  const errors = inject(FORM_CONTROL_ERRORS_KEY, null);
+  const message = ref<string>();
+
+  function report(next: string | undefined): void {
+    if (message.value === next) return;
+    message.value = next;
+    const name = field?.value?.name;
+    if (name) errors?.report(name, next);
+  }
+
+  onBeforeUnmount(() => report(undefined));
+
+  return { message, report };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/form/useInstantForm.ts

@@ -0,0 +1,125 @@
+import { type ComputedRef, type Ref, watch } from "vue";
+import type { FormField } from "../../../composables/form/types/field";
+import type { FormFieldValue } from "../../../composables/form/types/value";
+import { cloneFormValue } from "../../../composables/form/useForm";
+import { sameFormValue } from "../unsaved-changes/formValue";
+import {
+  type InstantSave,
+  useInstantSave,
+} from "../instant-save/useInstantSave";
+
+type FormValues = Record<string, unknown>;
+
+// Fields typed in rather than picked: they save once typing pauses, a pick
+// (a select, a switch, a date) at once. A field without a type is a text;
+// so is a field made of typed parts (an address, the rows of a repeater).
+const TYPED_FIELD_TYPES = new Set([
+  "string",
+  "address",
+  "array",
+  "key_value",
+  "code",
+  "secret",
+  "email",
+  "url",
+  "phone",
+  "password",
+  "number",
+  "price",
+  "percentage",
+  "rich_text",
+  "string_time",
+]);
+
+/** Whether a field's changes wait for typing to pause before saving. */
+export function savesOnPause(
+  field: Pick<FormField, "type" | "localized">,
+): boolean {
+  return !!field.localized || TYPED_FIELD_TYPES.has(field.type ?? "string");
+}
+
+export interface InstantFormOptions {
+  state: Ref<FormValues>;
+  fields: ComputedRef<FormField[]>;
+  /** Until the user acts on the form, a change is a control settling. */
+  isTouched: () => boolean;
+  /** Validates one field: an invalid value is shown, never sent. */
+  isFieldValid: (field: FormField) => Promise<boolean>;
+  /** Sends the changed fields, alone (a partial submit). */
+  submit: (changes: FormValues) => Promise<void>;
+  /** Says why a save was refused, once its values are put back. */
+  onRefused: (error: unknown) => void;
+}
+
+export interface InstantForm extends InstantSave<FormValues> {
+  /** The form loaded or was reset: its values are the confirmed ones. */
+  start: () => void;
+}
+
+const clone = (value: unknown): unknown =>
+  cloneFormValue(value as FormFieldValue | undefined);
+
+/**
+ * The instant save of a `Form` (`saveMode: "instant"`): each field the user
+ * changes is validated, then saved alone through the shared instant save —
+ * a text once typing pauses, a pick at once — and put back to the value the
+ * server last confirmed when refused.
+ */
+export function useInstantForm(options: InstantFormOptions): InstantForm {
+  // The value each field shows as far as the save knows: a value put back
+  // after a refusal is not a change of the user's.
+  const shown = new Map<string, unknown>();
+  // The latest check of each field: an older one ending late is dropped.
+  const checks = new Map<string, number>();
+
+  const instant = useInstantSave<FormValues>({
+    read: (key) => options.state.value[key],
+    write: (key, value) => {
+      shown.set(key, clone(value));
+      options.state.value[key] = clone(value);
+    },
+    save: options.submit,
+    onError: options.onRefused,
+  });
+
+  function start(): void {
+    const values: FormValues = {};
+    for (const field of options.fields.value) {
+      const value = clone(options.state.value[field.id]);
+      shown.set(field.id, value);
+      values[field.id] = value;
+    }
+    instant.confirm(values);
+  }
+
+  async function saveField(field: FormField, value: unknown): Promise<void> {
+    const check = (checks.get(field.id) ?? 0) + 1;
+    checks.set(field.id, check);
+    const isValid = await options.isFieldValid(field);
+    if (checks.get(field.id) !== check) return;
+    if (!isValid) {
+      instant.cancel(field.id);
+      return;
+    }
+    instant.queue(field.id, value, { debounce: savesOnPause(field) });
+  }
+
+  watch(
+    () => options.fields.value.map((field) => options.state.value[field.id]),
+    () => {
+      for (const field of options.fields.value) {
+        const value = clone(options.state.value[field.id]);
+        if (sameFormValue(shown.get(field.id), value)) continue;
+        shown.set(field.id, value);
+        if (!options.isTouched()) {
+          instant.confirm({ [field.id]: value });
+          continue;
+        }
+        void saveField(field, value);
+      }
+    },
+    { deep: true },
+  );
+
+  return { ...instant, start };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/global/searchShortcuts.ts

@@ -0,0 +1,61 @@
+const GLOBAL_COMPONENT = "$dms.components.global";
+
+/**
+ * Focuses the navigation search: the settings menu's on every settings page
+ * (and the module search on the Modules page, which has no settings menu).
+ */
+export const NAV_SEARCH_SHORTCUT = "/";
+
+/**
+ * Focuses a page's own search (⌘ / on macOS, Ctrl / elsewhere), so it never
+ * competes with "/" for the navigation search. `meta` is read as Ctrl off
+ * macOS by `defineShortcuts`. The shifted variant is the same physical keys
+ * on layouts where "/" needs Shift (AZERTY: Shift + :), which
+ * `defineShortcuts` would otherwise reject as an extra modifier.
+ */
+export const PAGE_SEARCH_SHORTCUTS = ["meta_/", "meta_shift_/"] as const;
+
+/**
+ * The page search keys as hint chips, by `defineShortcuts` key name: print
+ * them with `keyboardKeyLabel` ("⌘" "/" on macOS, "Ctrl" "/" elsewhere).
+ */
+export const PAGE_SEARCH_HINT_KEYS = ["meta", "/"] as const;
+
+/** `aria-keyshortcuts` of an input focused by the page search keys. */
+export function pageSearchAriaKeyshortcuts(macOS: boolean): string {
+  return macOS ? "Meta+/" : "Control+/";
+}
+
+/** `defineShortcuts` map focusing the navigation search on "/". */
+export function buildNavSearchShortcuts(
+  focus: () => void,
+): Record<string, () => void> {
+  return { [NAV_SEARCH_SHORTCUT]: focus };
+}
+
+/** `defineShortcuts` map focusing a page's own search on ⌘ / or Ctrl /. */
+export function buildPageSearchShortcuts(
+  focus: () => void,
+): Record<string, () => void> {
+  return Object.fromEntries(PAGE_SEARCH_SHORTCUTS.map((key) => [key, focus]));
+}
+
+/** "/" focuses the navigation search (listed on the shortcuts page). */
+export const GLOBAL_SLASH_METADATA: ShortcutMetadata = {
+  key: [NAV_SEARCH_SHORTCUT],
+  descriptionKey: "$dms.shortcuts.global.slash.description",
+  component: GLOBAL_COMPONENT,
+  condition: {
+    descriptionKey: "$dms.shortcuts.global.slash.condition",
+  },
+};
+
+/** ⌘ / or Ctrl / focuses the page's own search (listed on the shortcuts page). */
+export const GLOBAL_META_SLASH_METADATA: ShortcutMetadata = {
+  key: ["$keyboard.meta", "/"],
+  descriptionKey: "$dms.shortcuts.global.meta_slash.description",
+  component: GLOBAL_COMPONENT,
+  condition: {
+    descriptionKey: "$dms.shortcuts.global.meta_slash.condition",
+  },
+};

package/frontend-vue/layers/dms-ui/app/build/composables/global/shortcuts.ts

@@ -0,0 +1,31 @@
+import {
+  GLOBAL_META_SLASH_METADATA,
+  GLOBAL_SLASH_METADATA,
+} from "./searchShortcuts";
+
+const GLOBAL_COMPONENT = "$dms.components.global";
+
+/** Opens the command palette from anywhere in the dashboard. */
+export const GLOBAL_META_K_METADATA: ShortcutMetadata = {
+  key: ["$keyboard.meta", "k"],
+  descriptionKey: "$dms.shortcuts.global.meta_k.description",
+  component: GLOBAL_COMPONENT,
+};
+
+/** Closes the topmost dialog, menu or the command palette. */
+export const GLOBAL_ESCAPE_METADATA: ShortcutMetadata = {
+  key: ["$keyboard.escape"],
+  descriptionKey: "$dms.shortcuts.global.escape.description",
+  component: GLOBAL_COMPONENT,
+};
+
+/**
+ * Shortcuts the dashboard shell handles everywhere. They are only listed for
+ * the shortcuts page: the shell components bind them themselves.
+ */
+export const GLOBAL_SHORTCUTS_METADATA = [
+  GLOBAL_META_K_METADATA,
+  GLOBAL_SLASH_METADATA,
+  GLOBAL_META_SLASH_METADATA,
+  GLOBAL_ESCAPE_METADATA,
+];

package/frontend-vue/layers/dms-ui/app/build/composables/instant-save/useInstantSave.ts

@@ -0,0 +1,260 @@
+import {
+  computed,
+  onScopeDispose,
+  reactive,
+  ref,
+  type ComputedRef,
+  type Ref,
+} from "vue";
+import type { SaveStatusState } from "../../../components/save-bar/SaveStatus.vue";
+import { combineSaveStates } from "#dms-layout/app/composables/layout/useInstantSaveHeader";
+import { sameFormValue } from "../unsaved-changes/formValue";
+
+/** How long typing pauses before a text saves. */
+export const INSTANT_SAVE_DEBOUNCE_MS = 500;
+/** How long a key keeps its "Saved" tick. */
+export const INSTANT_SAVED_STATE_MS = 2000;
+
+type InstantSaveKey<V> = Extract<keyof V, string>;
+
+/**
+ * Where instantly saved values live: what the page shows (`read`, `write`)
+ * and where they are kept (`save`: a request to the server, or nothing more
+ * than the write for a value kept in a cookie).
+ */
+export interface InstantSaveSource<V extends object> {
+  /** The value a key shows now. */
+  read: <K extends InstantSaveKey<V>>(key: K) => V[K];
+  /** Shows a value: the one picked, or the one a failed save puts back. */
+  write: <K extends InstantSaveKey<V>>(key: K, value: V[K]) => void;
+  /** Keeps the changed keys; rejects when they are refused. */
+  save: (changes: Partial<V>) => Promise<void>;
+  /** Called after a refused save is put back (field errors, a toast). */
+  onError?: (error: unknown, changes: Partial<V>) => void;
+}
+
+export interface InstantChangeOptions {
+  /** Wait for typing to pause (a text) instead of saving at once (a pick). */
+  debounce?: boolean;
+}
+
+export interface InstantSave<V extends object> {
+  /** The save state of each key changed so far. */
+  states: Partial<Record<InstantSaveKey<V>, SaveStatusState>>;
+  /** The page's one state, for its header pill. */
+  state: ComputedRef<SaveStatusState>;
+  /** The changes of the saves that failed, until retried. */
+  failed: Ref<Partial<V> | null>;
+  /** Shows a value and saves it. */
+  change: <K extends InstantSaveKey<V>>(
+    key: K,
+    value: V[K],
+    options?: InstantChangeOptions,
+  ) => void;
+  /** Shows and saves several values in one request. */
+  changeMany: (changes: Partial<V>) => void;
+  /** Saves a value the source already shows (a control bound to it). */
+  queue: <K extends InstantSaveKey<V>>(
+    key: K,
+    value: V[K],
+    options?: InstantChangeOptions,
+  ) => void;
+  /** Drops a change still waiting for typing to pause. */
+  cancel: (key: InstantSaveKey<V>) => void;
+  /** Saves the changes still waiting, at once. */
+  flush: () => Promise<void>;
+  /** Saves again what failed. */
+  retry: () => void;
+  /** The values the server holds (once loaded): what a failure puts back. */
+  confirm: (values: Partial<V>) => void;
+}
+
+type Timer = ReturnType<typeof setTimeout>;
+
+/** The saves of one page: what waits, what runs, what the server holds. */
+class InstantSaveQueue<V extends object> {
+  readonly states = reactive({}) as Partial<
+    Record<InstantSaveKey<V>, SaveStatusState>
+  >;
+  readonly failed = ref<Partial<V> | null>(null) as Ref<Partial<V> | null>;
+  private readonly confirmed = new Map<InstantSaveKey<V>, unknown>();
+  private readonly pending = new Map<InstantSaveKey<V>, unknown>();
+  private readonly inFlight = new Set<InstantSaveKey<V>>();
+  private readonly debounceTimers = new Map<InstantSaveKey<V>, Timer>();
+  private readonly savedTimers = new Map<InstantSaveKey<V>, Timer>();
+
+  constructor(private readonly source: InstantSaveSource<V>) {}
+
+  /** The value a failure puts back: the server's, or the one first shown. */
+  remember(key: InstantSaveKey<V>): void {
+    if (!this.confirmed.has(key)) {
+      this.confirmed.set(key, this.source.read(key));
+    }
+  }
+
+  confirm(values: Partial<V>): void {
+    for (const [key, value] of Object.entries(values)) {
+      this.confirmed.set(key as InstantSaveKey<V>, value);
+    }
+  }
+
+  /** A change to send with the next save of its key. */
+  put(key: InstantSaveKey<V>, value: unknown): void {
+    clearTimeout(this.debounceTimers.get(key));
+    this.pending.set(key, value);
+  }
+
+  wait(key: InstantSaveKey<V>, value: unknown, debounce: boolean): void {
+    this.put(key, value);
+    if (!debounce) {
+      void this.send([key]);
+      return;
+    }
+    this.debounceTimers.set(
+      key,
+      setTimeout(() => void this.send([key]), INSTANT_SAVE_DEBOUNCE_MS),
+    );
+  }
+
+  cancel(key: InstantSaveKey<V>): void {
+    clearTimeout(this.debounceTimers.get(key));
+    this.pending.delete(key);
+  }
+
+  async flush(): Promise<void> {
+    for (const timer of this.debounceTimers.values()) clearTimeout(timer);
+    await this.send([...this.pending.keys()]);
+  }
+
+  dispose(): void {
+    for (const timer of this.savedTimers.values()) clearTimeout(timer);
+  }
+
+  async send(keys: InstantSaveKey<V>[]): Promise<void> {
+    const ready = keys.filter(
+      (key) => this.pending.has(key) && !this.inFlight.has(key),
+    );
+    if (ready.length === 0) return;
+    const changes = this.take(ready);
+    try {
+      await this.source.save(changes);
+      this.onSaved(changes);
+    } catch (error) {
+      this.onRefused(error, changes);
+    } finally {
+      for (const key of ready) this.inFlight.delete(key);
+      const followers = ready.filter((key) => this.pending.has(key));
+      if (followers.length) void this.send(followers);
+    }
+  }
+
+  /** Moves the waiting changes of these keys to a running save. */
+  private take(keys: InstantSaveKey<V>[]): Partial<V> {
+    const changes = Object.fromEntries(
+      keys.map((key) => [key, this.pending.get(key)]),
+    ) as Partial<V>;
+    for (const key of keys) {
+      this.pending.delete(key);
+      this.inFlight.add(key);
+      this.setState(key, "saving");
+    }
+    return changes;
+  }
+
+  private onSaved(changes: Partial<V>): void {
+    for (const key of Object.keys(changes) as InstantSaveKey<V>[]) {
+      this.confirmed.set(key, changes[key]);
+      this.setState(key, "saved");
+    }
+    this.settleFailed(changes, false);
+  }
+
+  private onRefused(error: unknown, changes: Partial<V>): void {
+    for (const key of Object.keys(changes) as InstantSaveKey<V>[]) {
+      // A newer value picked meanwhile stays on screen: its own save follows.
+      const isShown =
+        !this.pending.has(key) &&
+        sameFormValue(this.source.read(key), changes[key]);
+      if (isShown) {
+        this.source.write(key, this.confirmed.get(key) as V[typeof key]);
+      }
+      this.setState(key, "error");
+    }
+    this.settleFailed(changes, true);
+    this.source.onError?.(error, changes);
+  }
+
+  private settleFailed(changes: Partial<V>, isRefused: boolean): void {
+    const rest = { ...this.failed.value } as Record<string, unknown>;
+    for (const key of Object.keys(changes)) delete rest[key];
+    const next = isRefused ? { ...rest, ...changes } : rest;
+    this.failed.value = Object.keys(next).length ? (next as Partial<V>) : null;
+  }
+
+  private setState(key: InstantSaveKey<V>, state: SaveStatusState): void {
+    clearTimeout(this.savedTimers.get(key));
+    this.states[key] = state;
+    if (state !== "saved") return;
+    this.savedTimers.set(
+      key,
+      setTimeout(() => (this.states[key] = "idle"), INSTANT_SAVED_STATE_MS),
+    );
+  }
+}
+
+/**
+ * The instant save of a page or a form: each change shows at once and saves
+ * on its own — a pick right away, a text once typing pauses — with a state per
+ * key (saving, saved, error). A refused save puts back the value the server
+ * last confirmed and keeps the change for `retry`. Changes of a key made while
+ * its save runs follow once it ends, so the last one always wins.
+ */
+export function useInstantSave<V extends object>(
+  source: InstantSaveSource<V>,
+): InstantSave<V> {
+  const saves = new InstantSaveQueue(source);
+
+  const queue: InstantSave<V>["queue"] = (key, value, options = {}) =>
+    saves.wait(key, value, !!options.debounce);
+
+  const change: InstantSave<V>["change"] = (key, value, options) => {
+    saves.remember(key);
+    source.write(key, value);
+    queue(key, value, options);
+  };
+
+  const changeMany: InstantSave<V>["changeMany"] = (changes) => {
+    const keys = Object.keys(changes) as InstantSaveKey<V>[];
+    for (const key of keys) {
+      saves.remember(key);
+      source.write(key, changes[key] as V[typeof key]);
+      saves.put(key, changes[key]);
+    }
+    void saves.send(keys);
+  };
+
+  const retry: InstantSave<V>["retry"] = () => {
+    const changes = saves.failed.value;
+    saves.failed.value = null;
+    if (changes) changeMany(changes);
+  };
+
+  // A text still waiting for typing to pause is saved when the page goes.
+  onScopeDispose(() => {
+    saves.dispose();
+    void saves.flush();
+  });
+
+  return {
+    states: saves.states,
+    state: computed(() => combineSaveStates(Object.values(saves.states))),
+    failed: saves.failed,
+    change,
+    changeMany,
+    queue,
+    cancel: (key) => saves.cancel(key),
+    flush: () => saves.flush(),
+    retry,
+    confirm: (values) => saves.confirm(values),
+  };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/navigation/useNavBadges.ts

@@ -0,0 +1,24 @@
+/**
+ * Fresh counts a page publishes for its navigation entry, by page full id
+ * (`settings.workspace.members` → `"7"`, `""` for none). The server counts a table
+ * view tab declared with `navBadge: true` when the menu loads; the table
+ * publishes its own counter here once shown, which navigation surfaces draw
+ * over the server's badge.
+ *
+ * Shared state, so a count published on one page stays shown on the others.
+ */
+export const useNavBadges = () => {
+  const badges = useDmsState<Record<string, string>>(
+    "dms-nav-badges",
+    () => ({}),
+  );
+
+  /** Sets, or with `undefined` clears, the badge of a page. */
+  function setNavBadge(fullId: string, badge: string | undefined): void {
+    if (badges.value[fullId] === badge) return;
+    const { [fullId]: _previous, ...rest } = badges.value;
+    badges.value = badge === undefined ? rest : { ...rest, [fullId]: badge };
+  }
+
+  return { badges, setNavBadge };
+};