@antelopejs/dms 0.5.6 → 0.6.1

package/frontend-vue/layers/dms-ui/app/composables/table-view/useTableDataChanges.ts

@@ -0,0 +1,41 @@
+import { computed, type ComputedRef } from "vue";
+
+/**
+ * A version per data API location (`/api/tables/admin-invites`), moved on each
+ * time a table view reads its rows again because they changed: a form saved,
+ * a row action or a bulk action ran, a realtime event came in, or the user
+ * refreshed it.
+ *
+ * Whatever summarises the same rows elsewhere — a navigation count, an
+ * overview card — watches the version and reads its figure again, instead of
+ * polling or waiting for the next page change.
+ *
+ * Shared state, so a table on one page and a count in the shell agree.
+ */
+export const useTableDataChanges = () => {
+  const versions = useDmsState<Record<string, number>>(
+    "dms-table-data-versions",
+    () => ({}),
+  );
+
+  /** Says the rows behind a data API location changed. */
+  function notifyTableDataChanged(location: string | undefined): void {
+    if (!location) return;
+    versions.value = {
+      ...versions.value,
+      [location]: (versions.value[location] ?? 0) + 1,
+    };
+  }
+
+  /**
+   * The combined version of some locations: changes whenever the rows behind
+   * any of them do.
+   */
+  function tableDataVersion(locations: readonly string[]): ComputedRef<string> {
+    return computed(() =>
+      locations.map((location) => versions.value[location] ?? 0).join(":"),
+    );
+  }
+
+  return { notifyTableDataChanged, tableDataVersion };
+};

package/frontend-vue/layers/dms-ui/app/composables/table-view/useTableViewDisplays.ts

@@ -1,45 +1,59 @@
-import type {
-  TableViewDisplay,
-  TableViewDisplayCapabilities,
+import {
+  storeTableViewDisplay,
+  useTableViewDisplayState,
+} from "../../build/composables/table-view/displayRegistry";
+import {
+  RESERVED_TABLE_VIEW_DISPLAY_IDS,
+  type TableViewDisplay,
+  type TableViewDisplayCapabilities,
 } from "./types/display";
 
-const TABLE_VIEW_DISPLAYS_STATE_KEY = "dms:table-view-displays";
 const DEFAULT_ORDER = 100;
-
-function useDisplayState() {
-  return useDmsState<TableViewDisplay[]>(TABLE_VIEW_DISPLAYS_STATE_KEY, () => []);
-}
+// `<module>:<id>`: the module's name, then the display's own id.
+const MODULE_DISPLAY_ID = /^[a-z0-9][\w-]*:[\w-]+$/i;
 
 function displayOrder(display: TableViewDisplay): number {
   return display.order ?? DEFAULT_ORDER;
 }
 
 /**
- * Register (or replace, by id) a table view display. Keyed DMS app state lets any
- * module register without a build-time dependency on this layer. Call from a
- * `.client.ts` plugin: displays carry callables (component, isAvailable) that are
- * stripped from the SSR payload, so the registry is client-only. Data behaviour
- * and chrome (selfManagedData/capabilities) are config-driven for SSR safety; the
- * registry powers the client-side switcher and component resolution.
+ * Register a table view display a module contributes. Keyed DMS app state lets
+ * any module register without a build-time dependency on this layer. Register
+ * from a universal plugin so the server render draws the switcher too (a
+ * `.client` plugin works, but its display only joins the switcher after
+ * hydration). Data behaviour and chrome (selfManagedData/capabilities) are
+ * config-driven; the registry powers the switcher and component resolution.
+ *
+ * The id is `<module>:<id>` (`"saas:plan-cards"`): the built-in ids
+ * (`table`, `kanban`, `cards`, `grouped`) are reserved, and an id is
+ * registered once — this throws for a reserved id, an unprefixed one, or one
+ * another registration already claimed.
  */
-export function registerTableViewDisplay(display: TableViewDisplay): void {
-  const displays = useDisplayState();
-  const existingIndex = displays.value.findIndex(
-    (entry) => entry.id === display.id,
-  );
+export function registerTableViewDisplay(entry: TableViewDisplay): void {
+  assertModuleDisplayId(entry.id);
+  storeTableViewDisplay(entry);
+}
 
-  if (existingIndex === -1) {
-    displays.value = [...displays.value, display];
-    return;
+function assertModuleDisplayId(id: string): void {
+  if ((RESERVED_TABLE_VIEW_DISPLAY_IDS as readonly string[]).includes(id)) {
+    throw new Error(
+      `[DMS] Table view display "${id}" is a built-in display: register a module display under its own id, "<module>:${id}"`,
+    );
+  }
+  if (!MODULE_DISPLAY_ID.test(id)) {
+    throw new Error(
+      `[DMS] Table view display "${id}" must be named "<module>:<id>", e.g. "saas:plan-cards"`,
+    );
+  }
+  if (useTableViewDisplayState().value.some((display) => display.id === id)) {
+    throw new Error(
+      `[DMS] Table view display "${id}" is already registered: one registration per id`,
+    );
   }
-
-  const next = [...displays.value];
-  next[existingIndex] = display;
-  displays.value = next;
 }
 
 export function useTableViewDisplays() {
-  const displays = useDisplayState();
+  const displays = useTableViewDisplayState();
   const all = computed<TableViewDisplay[]>(() =>
     [...displays.value].sort((a, b) => displayOrder(a) - displayOrder(b)),
   );
@@ -62,5 +76,6 @@ export function resolveDisplayCapabilities(
     search: capabilities?.search ?? true,
     sorting: capabilities?.sorting ?? true,
     tabs: capabilities?.tabs ?? true,
+    header: capabilities?.header ?? true,
   };
 }

package/frontend-vue/layers/dms-ui/app/composables/unsaved-changes/index.ts

@@ -0,0 +1,2 @@
+export * from "./useFormDirty";
+export * from "./useUnsavedChanges";

package/frontend-vue/layers/dms-ui/app/composables/unsaved-changes/useFormDirty.ts

@@ -0,0 +1,54 @@
+import { computed, shallowRef, type ComputedRef, type ShallowRef } from "vue";
+import {
+  sameFormValue,
+  snapshotFormValue,
+} from "../../build/composables/unsaved-changes/formValue";
+
+export interface UseFormDirtyOptions<T> {
+  /**
+   * The values the form started from, when the caller keeps them (the
+   * profile it loaded, the role it saved): compared live instead of a
+   * snapshot taken here.
+   */
+  initial?: () => T;
+}
+
+export interface UseFormDirtyReturn<T> {
+  /** Whether the values differ, by value, from the starting ones. */
+  dirty: ComputedRef<boolean>;
+  /** The snapshot compared against (without an `initial` getter). */
+  baseline: ShallowRef<T>;
+  /**
+   * Makes the current values (or the given ones) the new starting point:
+   * after a successful save, or once the form is loaded.
+   */
+  markClean: (values?: T) => void;
+}
+
+/**
+ * The "unsaved changes" state of a form: dirty while its values differ, deeply
+ * and by value, from the ones it loaded or last saved. Putting the original
+ * value back makes it clean again; `markClean` after a save resets the
+ * starting point.
+ *
+ * @param values - The current values (read reactively).
+ */
+export function useFormDirty<T>(
+  values: () => T,
+  options: UseFormDirtyOptions<T> = {},
+): UseFormDirtyReturn<T> {
+  const baseline = shallowRef<T>(snapshotFormValue(values()));
+  const dirty = computed(
+    () =>
+      !sameFormValue(
+        values(),
+        options.initial ? options.initial() : baseline.value,
+      ),
+  );
+
+  function markClean(next: T = values()): void {
+    baseline.value = snapshotFormValue(next);
+  }
+
+  return { dirty, baseline, markClean };
+}

package/frontend-vue/layers/dms-ui/app/composables/unsaved-changes/useUnsavedChanges.ts

@@ -0,0 +1,120 @@
+import {
+  computed,
+  onScopeDispose,
+  toValue,
+  watch,
+  type ComponentPublicInstance,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+} from "vue";
+import { useLeaveGuard } from "#dms-core/app/composables/leave-guard";
+import { useConfirm } from "../confirm/useConfirm";
+import {
+  confirmLeave,
+  installBrowserLeaveGuards,
+  registerUnsavedChanges,
+} from "../../build/composables/unsaved-changes/registry";
+
+/** The element a form renders, or the component rendering it. */
+type ElementSource = Element | ComponentPublicInstance | null | undefined;
+
+export interface UseUnsavedChangesOptions {
+  /** Whether the form holds unsaved changes (see `useFormDirty`). */
+  dirty: MaybeRefOrGetter<boolean>;
+  /**
+   * The drawer or modal the form sits in: closing it (X, Escape, a click
+   * outside, Cancel) asks first. Left out, only leaving the page does.
+   */
+  containerId?: MaybeRefOrGetter<string | undefined>;
+  /** The form's root: a tab switch hiding it asks first. */
+  element?: MaybeRefOrGetter<ElementSource>;
+}
+
+export interface UseUnsavedChangesReturn {
+  /** Whether the form holds unsaved changes. */
+  isDirty: ComputedRef<boolean>;
+  /**
+   * Asks before throwing this form's changes away (a Cancel button of its
+   * own, another entry picked in an editor); resolves `true` to go ahead,
+   * straight away when there is nothing to lose.
+   */
+  confirmLeave: () => Promise<boolean>;
+}
+
+function resolveElement(source: ElementSource): Element | null {
+  if (!source) return null;
+  if (source instanceof Element) return source;
+  const element = (source as ComponentPublicInstance).$el;
+  return element instanceof Element ? element : null;
+}
+
+/**
+ * The confirmation every form with unsaved changes asks before they are
+ * lost, in the warning tone: "Discard unsaved changes?", with "Keep editing"
+ * and "Discard changes".
+ */
+export function useDiscardChangesPrompt(): () => Promise<boolean> {
+  const { confirm } = useConfirm();
+  const { t } = useI18n();
+  return () =>
+    confirm({
+      title: t("dms.leave_guard.title"),
+      description: t("dms.leave_guard.description"),
+      confirmLabel: t("dms.leave_guard.discard"),
+      cancelLabel: t("dms.leave_guard.keep_editing"),
+      // Staying is the safe answer: Enter keeps editing.
+      initialFocus: "cancel",
+      color: "warning",
+      icon: "i-ph-warning",
+    });
+}
+
+/**
+ * Guards a form's unsaved changes: while it is dirty, leaving it (closing its
+ * drawer or modal, navigating away, the browser's Back button, a reload or a
+ * closed tab) asks once in a warning dialog. Nothing asks once it is saved,
+ * discarded or put back as it was.
+ */
+export function useUnsavedChanges(
+  options: UseUnsavedChangesOptions,
+): UseUnsavedChangesReturn {
+  const isDirty = computed(() => !!toValue(options.dirty));
+  if (import.meta.env.SSR) {
+    return { isDirty, confirmLeave: async () => true };
+  }
+
+  const prompt = useDiscardChangesPrompt();
+  const route = useDmsRoute();
+  const containerId = toValue(options.containerId);
+  const { entry, unregister } = registerUnsavedChanges(
+    {
+      isDirty: () => isDirty.value,
+      containerId,
+      element: () => resolveElement(toValue(options.element)),
+    },
+    prompt,
+  );
+  const router = useDmsRouter();
+  installBrowserLeaveGuards({
+    path: () => route.path,
+    revisit: (href) => router.push(href),
+  });
+
+  // A discarded form asks again once it was clean in between (another role
+  // picked in the editor, then edited).
+  watch(isDirty, (dirty) => {
+    if (!dirty) entry.released = false;
+  });
+
+  // The drawer or modal runs its guards before closing.
+  const removeGuard = containerId
+    ? useLeaveGuard().addGuard(containerId, () => confirmLeave({ containerId }))
+    : undefined;
+
+  onScopeDispose(() => {
+    unregister();
+    removeGuard?.();
+  });
+
+  return { isDirty, confirmLeave: () => confirmLeave({ entry }) };
+}

package/frontend-vue/layers/dms-ui/app/composables/usePasswordStrength.ts

@@ -39,13 +39,19 @@ type StrengthColor =
   | "warning"
   | "neutral";
 
+// The rules list under the field details what is missing: the field error
+// only says the password is empty or misses one of them.
+const PASSWORD_REQUIRED = { message: "$dms.field_errors.required" };
+const PASSWORD_RULES = { message: "$dms.field_errors.password_rules" };
+
 export const passwordSchema = z
-  .string()
-  .min(MIN_PASSWORD_LENGTH, { message: "" })
-  .regex(/[A-Z]/, { message: "" })
-  .regex(/\d/, { message: "" })
-  .regex(/[@$!%*?&]/, { message: "" })
-  .regex(ALLOWED_CHARS_REGEX, { message: "" });
+  .string(PASSWORD_REQUIRED)
+  .min(1, PASSWORD_REQUIRED)
+  .min(MIN_PASSWORD_LENGTH, PASSWORD_RULES)
+  .regex(/[A-Z]/, PASSWORD_RULES)
+  .regex(/\d/, PASSWORD_RULES)
+  .regex(/[@$!%*?&]/, PASSWORD_RULES)
+  .regex(ALLOWED_CHARS_REGEX, PASSWORD_RULES);
 
 export function usePasswordStrength(password: Ref<string>) {
   const { t } = useI18n();

package/frontend-vue/layers/dms-ui/app/config/shortcuts-registry.ts

@@ -1,9 +1,13 @@
+import { GLOBAL_SHORTCUTS_METADATA } from "../build/composables/global/shortcuts";
 import { TAB_SHORTCUTS_METADATA } from "../composables/tab/shortcuts";
 import { TABLE_VIEW_SHORTCUTS_METADATA } from "../composables/table-view/shortcuts";
-import { TREE_SHORTCUTS_METADATA } from "../composables/tree/shortcuts";
 import type { ComponentShortcuts } from "../types/shortcuts";
 
 export default [
+  {
+    component: "Global",
+    shortcuts: GLOBAL_SHORTCUTS_METADATA,
+  },
   {
     component: "Tab",
     shortcuts: TAB_SHORTCUTS_METADATA,
@@ -12,8 +16,4 @@ export default [
     component: "TableView",
     shortcuts: TABLE_VIEW_SHORTCUTS_METADATA,
   },
-  {
-    component: "Tree",
-    shortcuts: TREE_SHORTCUTS_METADATA,
-  },
 ] satisfies ComponentShortcuts[];

package/frontend-vue/layers/dms-ui/app/plugins/register.ts

@@ -1,9 +1,11 @@
 import { registerDefaultDataTypes } from "../build/composables/data-types/registerDefaults";
 import { registerDefaultFunctions } from "../build/composables/table-view/registerDefaultFunctions";
 import { registerFormFunctions } from "../build/composables/form/registerFormFunctions";
+import { registerBlockFunctions } from "../build/composables/blocks/registerBlockFunctions";
 
 export default defineDmsPlugin(() => {
   registerDefaultDataTypes();
   registerDefaultFunctions();
   registerFormFunctions();
+  registerBlockFunctions();
 });

package/frontend-vue/layers/dms-ui/app/plugins/shortcuts.ts

@@ -1,4 +1,6 @@
 import aggregatedShortcuts from "#shortcuts-aggregated";
+import { useShortcutRegistry } from "../build/composables/shortcuts/useShortcutRegistry";
+
 export default defineDmsPlugin(() => {
   const { registerShortcut } = useShortcutRegistry();
 

package/frontend-vue/layers/dms-ui/app/plugins/table-view-displays.ts

@@ -0,0 +1,55 @@
+import { defineAsyncComponent } from "vue";
+import { storeTableViewDisplay } from "../build/composables/table-view/displayRegistry";
+import { isEligibleKanbanColumn } from "../composables/table-view/kanban";
+import {
+  CARDS_DISPLAY_ID,
+  GROUPED_DISPLAY_ID,
+  KANBAN_DISPLAY_ID,
+  TABLE_DISPLAY_ID,
+} from "../composables/table-view/types";
+
+const KanbanDisplay = defineAsyncComponent(
+  () => import("../components/table-view/KanbanDisplay.vue"),
+);
+
+const CardsDisplay = defineAsyncComponent(
+  () => import("../build/components/table-view/CardsDisplay.vue"),
+);
+
+// Registers the presentation of the built-in displays on the server as well:
+// the switcher then renders in the server pass, so hydration finds it there
+// instead of inserting it (and shifting the toolbar) afterwards. Data
+// behaviour and chrome (selfManagedData/capabilities) stay config-driven.
+export default defineDmsPlugin(() => {
+  storeTableViewDisplay({
+    id: TABLE_DISPLAY_ID,
+    label: "dms.table.view_mode_table",
+    icon: "i-ph-rows",
+    order: 10,
+  });
+
+  // The grid itself, its rows under group headers: no component of its own.
+  storeTableViewDisplay({
+    id: GROUPED_DISPLAY_ID,
+    label: "dms.table.view_mode_grouped",
+    icon: "i-ph-rows-plus-bottom",
+    order: 15,
+  });
+
+  storeTableViewDisplay({
+    id: KANBAN_DISPLAY_ID,
+    label: "dms.table.view_mode_kanban",
+    icon: "i-ph-kanban",
+    order: 20,
+    component: KanbanDisplay,
+    isAvailable: (ctx) => ctx.columns.some(isEligibleKanbanColumn),
+  });
+
+  storeTableViewDisplay({
+    id: CARDS_DISPLAY_ID,
+    label: "dms.table.view_mode_cards",
+    icon: "i-ph-cards",
+    order: 30,
+    component: CardsDisplay,
+  });
+});

package/frontend-vue/layers/dms-ui/app/types/modal.ts

@@ -6,4 +6,6 @@ export type ModalSize =
   | "2xl"
   | "3xl"
   | "4xl"
-  | "5xl";
+  | "5xl"
+  /** Near full-screen, with a scrolling body (imports, multi-step flows). */
+  | "full";

package/frontend-vue/layers/dms-ui/app/types/row-action.ts

@@ -1,12 +1,39 @@
 import type { ActionTarget } from "../composables/table-view/types/action-target";
 import type { RowActionRule } from "#dms-core/app/types/row-action";
+import type { ActionConfirm } from "#dms-core/app/types/confirm-dialog";
+
+/** A bulk custom action offered after "Select all N matching" too. */
+export interface CustomRowActionBulkOptions {
+  allMatching?: true;
+}
+
+/**
+ * A custom row action on the selection bar (backend `bulk`): for the
+ * selected rows, or with `allMatching` every row the filters match.
+ */
+export type CustomRowActionBulk = true | CustomRowActionBulkOptions;
 
 export interface CustomRowAction {
   label: string;
   icon?: string;
   target: ActionTarget;
+  /** Asked before the target runs: a fixed dialog, or `{ from }`. */
+  confirm?: ActionConfirm;
   rule?: RowActionRule;
+  /** Inline button instead of a menu entry (the backend serializes `isVisible`). */
+  isVisible?: boolean;
+  /** Legacy spelling of `isVisible`, still honoured. */
   visible?: boolean;
   /** Preferred row-click target when its rule accepts the row. */
   isDefault?: boolean;
+  /** Color of the inline button or menu entry. */
+  color?: ColorValue;
+  /** Variant of the inline button; `ghost` by default. */
+  variant?: "solid" | "outline" | "soft" | "ghost" | "link";
+  /** The inline button shows its label next to its icon. */
+  showLabel?: boolean;
+  /** Offered on the selection bar too. */
+  bulk?: CustomRowActionBulk;
+  /** The drawer or modal it opens is reflected in the URL (`?record=`). */
+  deepLink?: boolean;
 }

package/frontend-vue/layers/dms-ui/app/types/tone.ts

@@ -0,0 +1,13 @@
+/**
+ * The semantic tones a component shows a state in (a status pill, an icon
+ * well, an empty state, a list value), the `Tone` of interface-dms. A
+ * component that supports fewer narrows the union with `Extract<>`.
+ */
+export type Tone =
+  | "neutral"
+  | "primary"
+  | "secondary"
+  | "success"
+  | "warning"
+  | "error"
+  | "info";

package/frontend-vue/layers/dms-ui/app/utils/blockRefresh.ts

@@ -0,0 +1,28 @@
+/**
+ * The window event a data block (StatGroup, KeyValueList, NavCardGrid,
+ * ActivityFeed, KPI, top list, meter, chart, a tab set's badges) re-fetches
+ * on, keeping its values on screen until the new answer lands.
+ */
+export const BLOCK_REFRESH_EVENT = "DmsComponent.Block.Refresh";
+
+/** The watch functions every block can name (see interface-dms). */
+export const BlockFunctions = {
+  REFRESH_PAGE: "DmsComponent.Block.RefreshPage",
+} as const;
+
+/**
+ * Asks every data block mounted on the page to read its data again: what a
+ * component calls once an action of its own changed the record the page
+ * shows. The page header calls it after a button changed something.
+ */
+export function refreshPageBlocks(): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(BLOCK_REFRESH_EVENT));
+}
+
+/** Calls `handler` on each `refreshPageBlocks()`; returns the unsubscribe. */
+export function onPageBlocksRefresh(handler: () => void): () => void {
+  if (typeof window === "undefined") return () => {};
+  window.addEventListener(BLOCK_REFRESH_EVENT, handler);
+  return () => window.removeEventListener(BLOCK_REFRESH_EVENT, handler);
+}

package/frontend-vue/layers/dms-ui/app/utils/semanticTint.ts

@@ -17,5 +17,5 @@ export const SOFT_TINT: Record<SemanticColor, string> = {
   warning: "bg-warning/10 text-warning",
   info: "bg-info/10 text-info",
   primary: "bg-primary/10 text-primary",
-  neutral: "bg-elevated text-muted",
+  neutral: "bg-(--dms-neutral-tint) text-muted",
 };