@antelopejs/dms 0.5.5 → 0.6.0

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

@@ -0,0 +1,125 @@
+import { computed, getCurrentInstance, onMounted, type Ref } from "vue";
+
+/** How keyboard hints are printed: macOS/iOS symbols, or PC key names. */
+export type KeyboardPlatform = "mac" | "other";
+
+/**
+ * The platform the browser detected, kept in a cookie so the server renders
+ * the right hints from the second page on. The server cannot know it before:
+ * it only sees the request's cookies.
+ */
+export const KEYBOARD_PLATFORM_COOKIE = "dms-keyboard-platform";
+const KEYBOARD_PLATFORM_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+/** What the server renders before the browser has said otherwise. */
+export const DEFAULT_KEYBOARD_PLATFORM: KeyboardPlatform = "other";
+
+const APPLE_PLATFORM_PATTERN = /mac|iphone|ipad|ipod/i;
+
+/**
+ * How each platform prints the modifier and special keys, by `defineShortcuts`
+ * key name. A key left out keeps its own name. `meta` is the key Nuxt UI binds
+ * to ⌘ on macOS and to Ctrl elsewhere.
+ */
+export const KEYBOARD_KEY_LABELS: Record<
+  KeyboardPlatform,
+  Record<string, string>
+> = {
+  mac: {
+    meta: "⌘",
+    ctrl: "⌃",
+    alt: "⌥",
+    shift: "⇧",
+    enter: "↵",
+    delete: "⌫",
+  },
+  other: {
+    meta: "Ctrl",
+    ctrl: "Ctrl",
+    alt: "Alt",
+  },
+};
+
+/** The parts of `navigator` the platform is read from. */
+export interface KeyboardPlatformNavigator {
+  userAgentData?: { platform?: string };
+  platform?: string;
+  userAgent?: string;
+}
+
+/**
+ * The keyboard platform of a browser: macOS and iOS print ⌘, every other one
+ * Ctrl. Reads the client hint first, then the legacy `platform`, then the
+ * user agent; without a navigator (server) it falls back to the default.
+ */
+export function detectKeyboardPlatform(
+  navigator?: KeyboardPlatformNavigator,
+): KeyboardPlatform {
+  if (!navigator) return DEFAULT_KEYBOARD_PLATFORM;
+  const platform =
+    navigator.userAgentData?.platform ||
+    navigator.platform ||
+    navigator.userAgent ||
+    "";
+  return APPLE_PLATFORM_PATTERN.test(platform) ? "mac" : "other";
+}
+
+/** A key's label on a platform: "meta" is ⌘ on macOS, Ctrl elsewhere. */
+export function keyboardKeyLabel(
+  key: string,
+  platform: KeyboardPlatform,
+): string {
+  const label = KEYBOARD_KEY_LABELS[platform][key.toLowerCase()];
+  if (label) return label;
+  return key.length === 1 ? key.toUpperCase() : key;
+}
+
+/**
+ * A key combination as one hint: macOS runs its symbols together ("⌘K"),
+ * other platforms space the key names ("Ctrl K").
+ */
+export function formatKeyboardShortcut(
+  keys: readonly string[],
+  platform: KeyboardPlatform,
+): string {
+  return keys
+    .map((key) => keyboardKeyLabel(key, platform))
+    .join(platform === "mac" ? "" : " ");
+}
+
+function normalizePlatform(value: unknown): KeyboardPlatform {
+  return value === "mac" ? "mac" : "other";
+}
+
+/**
+ * The keyboard platform every hint renders with, shared by all callers. The
+ * server and the hydrating browser both start from the cookie, so their HTML
+ * matches; once mounted, the browser detects its platform and, if the cookie
+ * was wrong or missing, corrects it, which re-renders the hints in place and
+ * lets the next server render get them right. Only labels follow it: the key
+ * bindings themselves stay with `defineShortcuts`.
+ */
+export function useKeyboardPlatform() {
+  const stored: Ref<KeyboardPlatform> = useDmsCookie<KeyboardPlatform>(
+    KEYBOARD_PLATFORM_COOKIE,
+    {
+      default: () => DEFAULT_KEYBOARD_PLATFORM,
+      maxAge: KEYBOARD_PLATFORM_COOKIE_MAX_AGE,
+    },
+  );
+  if (getCurrentInstance()) {
+    onMounted(() => {
+      const detected = detectKeyboardPlatform(window.navigator);
+      if (stored.value !== detected) stored.value = detected;
+    });
+  }
+  const platform = computed(() => normalizePlatform(stored.value));
+  return {
+    platform,
+    isMac: computed(() => platform.value === "mac"),
+    /** A key's label, e.g. `keyLabel("meta")` → "⌘" or "Ctrl". */
+    keyLabel: (key: string) => keyboardKeyLabel(key, platform.value),
+    /** A combination as one hint, e.g. `["meta", "k"]` → "⌘K" or "Ctrl K". */
+    formatShortcut: (keys: readonly string[]) =>
+      formatKeyboardShortcut(keys, platform.value),
+  };
+}

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

@@ -1,4 +1,5 @@
 import { camelize, capitalize, type Component } from "vue";
+import { resolveDmsComponent as resolveRegisteredComponent } from "#dms/frontend-module";
 
 function normalizeComponentName(name: string): string {
   return name.toLowerCase().replace(/[^a-z0-9]/g, "");
@@ -24,35 +25,31 @@ function findRegistryKey(
 }
 
 /**
- * Resolve a DMS component by name from the Vue app's global registry.
- * All frontend module components are registered globally as lazy async chunks,
- * so this only returns a loader reference — the component code is fetched
- * when it first renders. Lookup tolerates PascalCase, kebab-case and
- * lowercase variants, matching what backend data may contain.
+ * Resolve a component by its full registered name, prefix included, through
+ * the frontend engine's registry, as a lazy loader: the component code is
+ * fetched when it first renders. Names are compared normalized (a leading
+ * `lazy` and every non-alphanumeric character dropped, case ignored), so
+ * PascalCase, kebab-case and lowercase variants from backend data all match.
  */
 export function resolveDmsComponent(name?: string): Component | undefined {
   if (!name) return undefined;
 
-  // _context is a private Vue API, but it is the only runtime view of the
-  // global registry; the DMS preloader reads it the same way.
-  const components = useDmsApp().vueApp._context.components;
-  const key = findRegistryKey(name, components);
+  const component = resolveRegisteredComponent(name);
 
-  if (!key && import.meta.env.DEV) {
+  if (!component && import.meta.env.DEV) {
     console.warn(
-      `[resolveDmsComponent] No globally registered component matches "${name}". ` +
-        "Check the componentName sent by the backend and that the component's " +
-        "directory is declared with global: true.",
+      `[resolveDmsComponent] No registered component matches "${name}". ` +
+        "Check the componentName sent by the backend and the name the " +
+        "frontend module registers it under.",
     );
   }
 
-  return key ? components[key] : undefined;
+  return component;
 }
 
 /**
- * Resolve the canonical registered name of a DMS component. The DMS app's
- * preloadComponents()/prefetchComponents() look components up by their exact
- * registered name, so backend-provided variants must go through this first.
+ * Resolve the canonical registered name of a component in the Vue app's
+ * global registry, for APIs that take an exact registered name.
  */
 export function resolveDmsComponentName(name?: string): string | undefined {
   if (!name) return undefined;

package/frontend-vue/layers/dms-ui/app/composables/tab/types/props.ts

@@ -24,4 +24,12 @@ export interface TabProps extends TabComponentProps {
   unmountOnHide?: boolean;
   persistState?: boolean;
   stateKey?: string;
+  /**
+   * GET answering `{ [slot]: string | number }`: the badge of each tab it
+   * names, read in one request and again when a watch action fires.
+   */
+  badgesUrl?: string;
 }
+
+/** The badges `badgesUrl` answers with, by tab slot. */
+export type TabBadges = Record<string, string | number>;

package/frontend-vue/layers/dms-ui/app/composables/table-view/types/action-target.ts

@@ -14,16 +14,17 @@ export type ActionTarget =
     }
   | { type: "page"; url: string }
   | { type: "external"; url: string; newTab?: boolean }
+  /** Runs a quick action, by its `category:id` key or bare id. */
+  | { type: "quickAction"; id: string }
   | {
       type: "api";
       url: string;
       method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+      /** JSON body sent with the request. */
+      body?: Record<string, unknown>;
+      /** Field of the JSON response copied to the clipboard on success. */
+      copy?: string;
       successMessage: string;
-      confirm?: {
-        title: string;
-        description: string;
-        confirmColor?: "primary" | "error" | "warning";
-      };
     }
   | {
       type: "exportJob";
@@ -40,9 +41,4 @@ export type ActionTarget =
         errorTitle?: string;
         retry?: string;
       };
-      confirm?: {
-        title: string;
-        description: string;
-        confirmColor?: "primary" | "error" | "warning";
-      };
     };

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

@@ -16,6 +16,13 @@ export interface ReadonlyBehavior {
   view?: ReadonlyBehaviorMode;
 }
 
+/** The display a column's cells are drawn with (backend `ColumnDisplay`). */
+export interface TableViewColumnDisplay {
+  /** Id of the frontend data type drawing the cells. */
+  type: string;
+  options?: Record<string, unknown>;
+}
+
 export interface TableViewColumn {
   id: string;
   header: string;
@@ -36,4 +43,11 @@ export interface TableViewColumn {
   enableColumnFilter?: boolean;
   /** Wrap grid cell content without a line limit; omitted keeps the theme default. */
   cellWrap?: boolean;
+  /** Default grid column width in px (TanStack `size`). */
+  size?: number;
+  /**
+   * Data type the grid draws this column's cells with, instead of `type`
+   * (which keeps driving forms and filters).
+   */
+  display?: TableViewColumnDisplay;
 }

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

@@ -7,6 +7,7 @@ import type { TableViewDisplayCapabilities } from "./display";
 import type { CustomButton } from "./custom-button";
 import type { FormProps } from "../../form/types";
 import type { TableProps, TableFilter } from "../../../types/table";
+import type { BlockAction } from "../../../build/components/blocks/BlockActions.vue";
 
 export interface QueryParamFilter {
   field: string;
@@ -25,10 +26,190 @@ export type RouteParamFilters = Record<string, RouteParamFilter>;
 export interface TableViewTab {
   id: string;
   label: string;
-  filters: TableFilter[];
+  /** Filter the tab applies, on one column (a link tab has none). */
+  filter?: TableFilter;
   icon?: string;
   textColor?: string;
   iconColor?: string;
+  /** Link tab: path of the page it opens (no filter applied). */
+  to?: string;
+  /** Full id of the page a link tab opens, when it is a registered page. */
+  toPage?: string;
+  /** Data API location whose row total a link tab shows. */
+  countFrom?: string;
+  /** Keeps the nav badge of the page it stands for up to date. */
+  navBadge?: boolean;
+}
+
+/**
+ * How much a table draws around its rows (backend `layout`): the full
+ * dashboard grid, or the compact list of a settings page.
+ */
+export type TableViewLayout = "full" | "compact";
+
+/** A one-click dropdown filter of the toolbar (backend `quickFilters`). */
+export interface TableViewQuickFilter {
+  field: string;
+  label?: string;
+  icon?: string;
+  allLabel?: string;
+  mode?: TableViewQuickFilterMode;
+}
+
+/** How a quick filter compares the column with the picked value. */
+export type TableViewQuickFilterMode =
+  | "is"
+  | "is_not"
+  | "include"
+  | "exclude"
+  | "array_contains_string";
+
+/** A figure of the footer band (backend `footer.summary`). */
+export interface TableViewFooterSummaryConfig {
+  /** Id the `summary` route computes it under. */
+  id: string;
+  label: string;
+  field?: string;
+  op: "sum" | "count";
+  /** `Intl.NumberFormat` options; left out, a sum reads like its cells. */
+  format?: Intl.NumberFormatOptions;
+}
+
+/**
+ * How the rows beyond the first page are reached (backend `pagination`): a
+ * pager, a "Load more" button, or more rows as the list's end shows.
+ */
+export type TableViewPaginationMode = "pages" | "loadMore" | "infinite";
+
+/** Texts and figures of the footer band (backend `footer`). */
+export interface TableViewFooter {
+  /** i18n key (`$`) receiving `{ count }`, pluralized on it. */
+  countLabel?: string;
+  hint?: string;
+  summary?: TableViewFooterSummaryConfig[];
+  /** A select column whose items the footer lists as a legend. */
+  legend?: string;
+}
+
+/** What an empty body says for one reason (backend `TableViewEmptyState`). */
+export interface TableViewEmptyStateConfig {
+  title: string;
+  description?: string;
+  icon?: string;
+  actions?: BlockAction[];
+  /** Draws the whole state; receives `state`, `search` and `refresh`. */
+  component?: ComponentInfo;
+}
+
+/** Why a table's body is empty. */
+export type TableViewEmptyStateKind = "firstRun" | "filtered" | "error";
+
+/** The empty states of a table view (backend `emptyStates`). */
+export type TableViewEmptyStatesConfig = Partial<
+  Record<TableViewEmptyStateKind, TableViewEmptyStateConfig>
+>;
+
+/** A field of the expanded row's detail band. */
+export interface TableViewExpandableField {
+  /** Column key; the value renders through that column's data type. */
+  key: string;
+  /** Label shown instead of the column's name (`$`-prefixed: i18n key). */
+  label?: string;
+}
+
+/**
+ * Expandable rows (backend `expandable` option): a caret column opens a
+ * detail band under the row, listing `fields` or rendering `component` (which
+ * receives `TableViewExpandedRowProps` and replaces the field list).
+ */
+export interface TableViewExpandableConfig {
+  fields?: TableViewExpandableField[];
+  fieldsLabel?: string;
+  component?: ComponentInfo;
+  /** Rows open on arrival and after the listed set changes. */
+  defaultExpanded?: "none" | "first" | "all";
+  /** At most one row open at a time. */
+  single?: boolean;
+  /** Reads the row from the data API's `get` route when it opens. */
+  lazyLoad?: boolean;
+}
+
+/** A sort a view applies (backend `TableViewSort`). */
+export interface TableViewViewSort {
+  field: string;
+  desc?: boolean;
+}
+
+/** The columns a view shows and their order (backend `columns`). */
+export interface TableViewViewColumns {
+  visible?: string[];
+  hidden?: string[];
+  order?: string[];
+}
+
+/** What a view sets on the table (backend `TableViewViewState`). */
+export interface TableViewViewStateConfig {
+  filters?: TableFilter[];
+  search?: string;
+  sort?: TableViewViewSort[];
+  columns?: TableViewViewColumns;
+  display?: string;
+  density?: "default" | "compact";
+}
+
+/** A named state of the table (backend `TableViewView`). */
+export interface TableViewViewConfig extends TableViewViewStateConfig {
+  id: string;
+  label: string;
+  icon?: string;
+  /** Colors the view's icon and counter. */
+  tone?: string;
+  /** Status dot before the label. */
+  dot?: string;
+  /** Shows the view's row count. */
+  count?: boolean;
+}
+
+/** Where the views are drawn (backend `TableViewViewsLayout`). */
+export type TableViewViewsLayout = "tabs" | "strip" | "menu";
+
+/** The views of a table view (backend `views` option). */
+export interface TableViewViewsConfig {
+  items: TableViewViewConfig[];
+  layout?: TableViewViewsLayout;
+  defaultView?: string;
+  /** Users may save the current state as a view of their own. */
+  userViews?: boolean;
+}
+
+/** How the `grouped` display cuts the rows (backend `TableViewGroupBy`). */
+export type TableViewGroupBy = "value" | "day" | "week";
+
+/** The `grouped` display's options (backend `grouped`). */
+export interface TableViewGroupedConfig {
+  groupByField: string;
+  by?: TableViewGroupBy;
+  collapsible?: boolean;
+  count?: boolean;
+}
+
+/** Rows ordered by hand on a number column (backend `reorder`). */
+export interface TableViewReorderConfig {
+  field: string;
+}
+
+/** What a source route handles itself (backend `capabilities`). */
+export interface TableViewSourceCapabilities {
+  search?: boolean;
+  sort?: boolean;
+  paginate?: boolean;
+  filter?: boolean;
+}
+
+/** Where a `TableView.fromSource` table reads its rows (backend `source`). */
+export interface TableViewSourceConfig {
+  fetchUrl: string;
+  capabilities: TableViewSourceCapabilities;
 }
 
 export interface TableViewListResponse<T> {
@@ -40,8 +221,6 @@ export interface TableViewListResponse<T> {
 
 export interface KanbanConfig {
   groupByField: string;
-  cardFields?: string[];
-  cardComponent?: ComponentInfo;
   draggable?: boolean;
   columnMaxHeight?: string;
 }
@@ -69,7 +248,10 @@ export interface TableViewDisplayConfig {
 }
 
 export interface TableViewConfig<T extends Data>
-  extends Omit<TableProps<T>, "columns" | "displays"> {
+  extends Omit<
+    TableProps<T>,
+    "columns" | "displays" | "chrome" | "quickFilters" | "footer" | "reorder"
+  > {
   location: string;
   enableTableExport?: boolean;
   archiveMode?: boolean;
@@ -95,4 +277,34 @@ export interface TableViewConfig<T extends Data>
   displays?: TableViewDisplayConfig[];
   /** Display shown by default when the user has no saved preference. Defaults to "table". */
   defaultDisplay?: string;
+  /** Expandable rows: caret column + detail band. */
+  expandable?: TableViewExpandableConfig;
+  /** How much the table draws around its rows. */
+  layout?: TableViewLayout;
+  /** The controller declares `@Searchable` fields. */
+  searchable?: boolean;
+  searchPlaceholder?: string;
+  quickFilters?: TableViewQuickFilter[];
+  /** Rows per page while the user picked none. */
+  pageSize?: number;
+  /** How the rows beyond the first page are reached. */
+  pagination?: TableViewPaginationMode;
+  /** A `TableView.fromSource` table's route, instead of a data controller. */
+  source?: TableViewSourceConfig;
+  /** Rows ordered by hand on a number column. */
+  reorder?: TableViewReorderConfig;
+  /**
+   * Row density while the user picked none in the ⋯ menu: `compact` gives
+   * 36px rows under a 32px header band.
+   */
+  density?: "default" | "compact";
+  footer?: TableViewFooter;
+  /** What the empty body says, per reason it is empty. */
+  emptyStates?: TableViewEmptyStatesConfig;
+  /** Named states of the table, opened from a strip, tabs or a menu. */
+  views?: TableViewViewsConfig;
+  /** Key of the table view in its page, prefixing its URL keys. */
+  tableId?: string;
+  /** The page carries no other table view: `?view=` / `?tab=` are its own. */
+  isSoleTableView?: boolean;
 }

package/frontend-vue/layers/dms-ui/app/composables/table-view/types/custom-button.ts

@@ -1,4 +1,5 @@
 import type { ActionTarget } from "./action-target";
+import type { ActionConfirm } from "#dms-core/app/types/confirm-dialog";
 
 export type CustomButtonVariant = "solid" | "outline" | "ghost" | "link";
 
@@ -10,8 +11,15 @@ export interface CustomButton {
   variant?: CustomButtonVariant;
   color?: ColorValue;
   target: ActionTarget;
+  /** Asked before the target runs: a fixed dialog, or `{ from }`. */
+  confirm?: ActionConfirm;
   /** Set by the server when the button cannot be pressed for this request. */
   disabled?: boolean;
   /** Why the button is disabled, shown in its tooltip. May be an i18n key. */
   disabledReason?: string;
+  /**
+   * `header`: drawn in the page header (the server adds it there) instead of
+   * the toolbar; still pressed by id by a quick action.
+   */
+  placement?: "toolbar" | "header";
 }

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

@@ -2,11 +2,27 @@ import type { Component } from "vue";
 import type { Table } from "@tanstack/vue-table";
 import type { TableViewColumn } from "./column";
 import type { CustomRowAction } from "../../../types/row-action";
+import type { TableViewPaginationMode } from "./config";
 
 /** The built-in grid display id. */
 export const TABLE_DISPLAY_ID = "table";
 /** The built-in kanban display id. */
 export const KANBAN_DISPLAY_ID = "kanban";
+/** The built-in cards display id. */
+export const CARDS_DISPLAY_ID = "cards";
+/** The built-in grouped display id. */
+export const GROUPED_DISPLAY_ID = "grouped";
+
+/**
+ * Display ids the DMS keeps for its built-in displays: a module registers its
+ * own under `<module>:<id>`.
+ */
+export const RESERVED_TABLE_VIEW_DISPLAY_IDS = [
+  TABLE_DISPLAY_ID,
+  KANBAN_DISPLAY_ID,
+  CARDS_DISPLAY_ID,
+  GROUPED_DISPLAY_ID,
+] as const;
 
 /**
  * A row "actor" currently editing an item (realtime presence). Keyed by row id
@@ -47,6 +63,14 @@ export interface TableViewDisplayPagination {
   total: number;
   setPage: (index: number) => void;
   setPageSize: (size: number) => void;
+  /**
+   * How the rows beyond the first page are reached: with `loadMore` and
+   * `infinite`, `items` holds every row loaded so far and `loadMore()`
+   * appends the next page while `hasMore`.
+   */
+  mode: TableViewPaginationMode;
+  hasMore: boolean;
+  loadMore: () => void;
 }
 
 /**
@@ -66,9 +90,66 @@ export interface TableViewDisplayActions<T> {
   delete: (ids: string[]) => void;
   duplicate: (id: string) => void;
   details: (item: T) => void;
+  /** What a click on the row does in the grid: its default action. */
+  open: (item: T) => void;
   custom: (action: CustomRowAction) => void;
 }
 
+/**
+ * The card the `kanban` and `cards` displays draw (backend `card` option):
+ * the columns it shows, or a component drawing it whole.
+ */
+export interface TableViewCardConfig {
+  fields?: string[];
+  component?: ComponentInfo;
+}
+
+/**
+ * The props a custom card component receives, the same in the `kanban` and
+ * `cards` displays.
+ */
+export interface TableViewCardProps<T = Record<string, unknown>> {
+  /** The row the card stands for. */
+  row: T;
+  /** Its id (its `rowIdKey` value). */
+  rowId: string;
+  /** Column metadata of the table view (types, labels). */
+  columns: TableViewColumn[];
+  /** Field naming the row, if configured. */
+  labelKey?: string;
+  /** The table's row actions and their per-row predicates. */
+  actions: TableViewDisplayActions<T>;
+  /** The row is selected. */
+  selected: boolean;
+  /** Selects the row, or unselects it (`false`); toggles without a value. */
+  select: (value?: boolean) => void;
+  /** Does what a click on the row does in the grid. */
+  open: () => void;
+  /** Kanban only: the value of the column the card sits in. */
+  groupValue?: string;
+}
+
+/**
+ * The props a custom detail band receives (backend `expandable.component`):
+ * a card's, without the selection the grid row above it already shows.
+ */
+export interface TableViewExpandedRowProps<T = Record<string, unknown>> {
+  /** The row the band details: the listed one, or the one `lazyLoad` read. */
+  row: T;
+  /** Its id (its `rowIdKey` value). */
+  rowId: string;
+  /** Column metadata of the table view (types, labels). */
+  columns: TableViewColumn[];
+  /** Field naming the row, if configured. */
+  labelKey?: string;
+  /** The table's row actions and their per-row predicates. */
+  actions: TableViewDisplayActions<T>;
+  /** Does what a click on the row does in the grid. */
+  open: () => void;
+  /** Reloads the table, and with it the open bands. */
+  refresh: () => Promise<void> | void;
+}
+
 /**
  * The single, normalized prop every display component receives. A display reads
  * what it needs and ignores the rest; everything is sourced from the table
@@ -126,6 +207,12 @@ export interface TableViewDisplayCapabilities {
   sorting?: boolean;
   /** Filter tabs. Default true (kanban: false). */
   tabs?: boolean;
+  /**
+   * The table's own chrome above the body: caption, actions toolbar, tabs,
+   * filters row and bulk-selection bar. Default true; a display that draws a
+   * complete interface of its own sets it to false.
+   */
+  header?: boolean;
 }
 
 /** Lightweight context passed to {@link TableViewDisplay.isAvailable}. */
@@ -135,13 +222,17 @@ export interface TableViewDisplayAvailabilityContext {
 }
 
 /**
- * A registered display ("table", "kanban", or a project/module-contributed one).
- * Registered from a `.client.ts` plugin via `registerTableViewDisplay`. Holds
+ * A registered display: a built-in one ("table", "kanban", "cards") or one a
+ * module contributes under `<module>:<id>`, registered from a universal plugin
+ * via `registerTableViewDisplay`. Holds
  * presentation only; data behaviour (selfManagedData) and chrome (capabilities)
  * live on the backend config (SSR source of truth) — see TableViewDisplayConfig.
  */
 export interface TableViewDisplay {
-  /** Stable id; matches `displays[].id` / `defaultDisplay` and the persisted preference. */
+  /**
+   * Stable id; matches `displays[].id` / `defaultDisplay` and the persisted
+   * preference. A module's display is `<module>:<id>`.
+   */
   id: string;
   /** i18n key or literal label shown in the view switcher. */
   label: string;