@antelopejs/dms 0.7.7 → 0.7.9

package/frontend-vue/layers/dms-ui/app/build/composables/actions/useActionTargets.ts

@@ -4,7 +4,7 @@ import {
   isConfirmFrom,
 } from "#dms-core/app/types/confirm-dialog";
 import { get } from "@nuxt/ui/runtime/utils/index.js";
-import type { Component } from "vue";
+import { type Component, getCurrentScope, onScopeDispose } from "vue";
 import type { ActionTarget } from "../../../composables/table-view/types/action-target";
 import type { CustomButton } from "../../../composables/table-view/types/custom-button";
 import type { CustomRowAction } from "../../../types/row-action";
@@ -26,7 +26,18 @@ import {
   type RowNavigationSource,
   rowNavigation,
 } from "./rowNavigation";
-import { writeRecordId } from "../table-view/utils/recordLink";
+import {
+  clearWrittenRecord,
+  isDeepLinkAction,
+  writeRecordId,
+  type WrittenRecord,
+} from "../table-view/utils/recordLink";
+import {
+  closeRowSidePanel,
+  closeRowSidePanelOf,
+  openRowSidePanel,
+  rowSidePanelOwnerKey,
+} from "#dms-layout/app/build/composables/layout/rowSidePanel";
 import type { TableUrlScope } from "../table-view/utils/views";
 import { useActionConfirm } from "../confirm/useActionConfirm";
 import {
@@ -72,6 +83,16 @@ interface TargetRunExtras {
   deepLink?: boolean;
 }
 
+type SidePanelTarget = ActionTarget & { type: "sidePanel" };
+
+/** A side panel to open, and on what. */
+interface SidePanelTargetRun extends TargetRunExtras {
+  target: SidePanelTarget;
+  title: string;
+  containerId: string;
+  rowData?: Data;
+}
+
 /** A drawer or modal to open, and on what. */
 interface ComponentTargetRun extends TargetRunExtras {
   target: ActionTarget & { type: "modal" | "drawer" };
@@ -214,14 +235,84 @@ export function useActionTargets(config: ActionTargetsConfig) {
       : openDrawer({ ...options, direction: run.target.direction });
   };
 
+  const resolveTargetComponent = (componentName: string): Component =>
+    (resolveDmsComponent(componentName) || componentName) as Component;
+
+  const rowIdOf = (row?: Data): string | undefined => {
+    if (!row) return undefined;
+    const idKey =
+      config.rowNavigation?.rowIdKey ?? config.rowIdKey ?? DEFAULT_ROW_ID_KEY;
+    const id = get(row, idKey);
+    return id === undefined || id === null ? undefined : String(id);
+  };
+
+  // A deep-linked action keeps the row it has open in the URL; `undefined`
+  // removes it, but only the row this run wrote, on the page it wrote it:
+  // closing as the user navigates leaves the next page's `?record=` alone.
+  const rowRecorder = (deepLink?: boolean) => {
+    let written: WrittenRecord | undefined;
+    return (row?: Data): void => {
+      if (!deepLink || !config.recordScope || !config.rowNavigation) return;
+      if (!row) {
+        clearWrittenRecord(written);
+        written = undefined;
+        return;
+      }
+      written = writeRecordId(config.recordScope, rowIdOf(row));
+    };
+  };
+
+  const ownerKey = rowSidePanelOwnerKey(config.pageId, config.componentId);
+
+  // The panel belongs to the table that opened it: it closes with it.
+  if (getCurrentScope()) onScopeDispose(() => closeRowSidePanelOf(ownerKey));
+
+  // A side panel opened on a listed row steps through the rows shown in place
+  // (the panel computes its position); a deep-linked one keeps the row in the
+  // URL while it is open. A bulk action's panel receives the selection.
+  const handleSidePanelTarget = (run: SidePanelTargetRun) => {
+    const componentName = run.target.component?.componentName;
+    if (!componentName) return;
+    const session = Symbol(componentName);
+    const component = resolveTargetComponent(componentName);
+    const recordRow = rowRecorder(run.deepLink && !run.selection);
+    const componentOptions = {
+      ...run.target.component?.options,
+      pageId: config.pageId,
+      componentId: config.componentId,
+      containerId: run.containerId,
+      selection: run.selection,
+      onSuccessCallback: () => {
+        closeRowSidePanel(session);
+        config.refreshCallback?.();
+      },
+    };
+    const showRow = (row?: Data) => {
+      openRowSidePanel({
+        session,
+        ownerKey,
+        title: run.title,
+        positionLabel: run.target.positionLabel,
+        component,
+        componentOptions,
+        row,
+        rowKey: rowIdOf(row),
+        source: row ? config.rowNavigation : undefined,
+        showRow,
+        onClose: () => recordRow(undefined),
+      });
+      recordRow(row);
+    };
+    showRow(run.rowData);
+  };
+
   // A container opened on a listed row steps through the rows shown (its
   // `navigation` prop, J and K), mounting its component anew on each; a
   // deep-linked one keeps the row in the URL while it is open.
   const handleComponentTarget = (run: ComponentTargetRun) => {
     const componentName = run.target.component?.componentName;
     if (!componentName) return;
-    const component = (resolveDmsComponent(componentName) ||
-      componentName) as Component;
+    const component = resolveTargetComponent(componentName);
     const source = config.rowNavigation;
     let instance: ContainerInstance | undefined;
     let navigation: RowNavigation | undefined;
@@ -242,13 +333,7 @@ export function useActionTargets(config: ActionTargetsConfig) {
         },
       };
     };
-    const recordRow = (row?: Data) => {
-      if (!run.deepLink || !config.recordScope || !source) return;
-      writeRecordId(
-        config.recordScope,
-        row ? String(get(row, source.rowIdKey)) : undefined,
-      );
-    };
+    const recordRow = rowRecorder(run.deepLink);
     function showRow(row: Data) {
       instance?.patch({
         componentOptions: optionsFor(row),
@@ -286,6 +371,15 @@ export function useActionTargets(config: ActionTargetsConfig) {
       ...extras,
     });
 
+  const sidePanelHandler: TargetHandler = (target, label, rowData, extras) =>
+    handleSidePanelTarget({
+      target: target as SidePanelTarget,
+      title: processI18n((target as SidePanelTarget).title || label),
+      containerId: `${config.pageId}-${config.componentId}-${target.type}`,
+      rowData: extras?.selection ? undefined : rowData,
+      ...extras,
+    });
+
   const targetHandlers: Record<string, TargetHandler> = {
     page: (target, _label, rowData) => {
       const pageTarget = target as ActionTarget & { type: "page" };
@@ -332,6 +426,7 @@ export function useActionTargets(config: ActionTargetsConfig) {
       if (quickAction) dispatchQuickActionTarget(quickAction.target);
     },
     drawer: componentHandler,
+    sidePanel: sidePanelHandler,
   };
 
   const targetUrl = (url: string, rowData?: Data): string =>
@@ -421,7 +516,7 @@ export function useActionTargets(config: ActionTargetsConfig) {
       action.label,
       rowData,
       action.confirm,
-      { deepLink: action.deepLink },
+      { deepLink: isDeepLinkAction(action) },
     );
   };
 

package/frontend-vue/layers/dms-ui/app/build/composables/blocks/useRefreshTriggers.ts

@@ -1,40 +1,55 @@
 import { onBeforeUnmount, onMounted } from "vue";
 import { useRealtimeTopic } from "../../../../../dms-core/app/composables/realtime/useRealtimeTopic";
-import { onPageBlocksRefresh } from "../../../utils/blockRefresh";
+import {
+  onLivePageBlocksRefresh,
+  onPageBlocksRefresh,
+} from "../../../utils/blockRefresh";
+import { type LiveGate, useLiveGate } from "../live/currentPageLive";
 
 /**
  * Calls `onRefresh` whenever the data behind a block moved without its inputs
  * changing: on each event of one of its realtime topics, and each time the
- * page asks its blocks to refresh (refreshPageBlocks).
+ * page asks its blocks to refresh (refreshPageBlocks, refreshLivePageBlocks).
+ *
+ * On a page declared with `live`, the realtime events and the live refreshes
+ * go through the page's gate: in Direct at most once per `maxRate`, in Pause
+ * not at all — the block counts what it missed and refetches once on resume.
+ * A refresh the user asked for (refreshPageBlocks) reads at once, paused or
+ * not. The returned gate says what was missed.
  */
 export function useRefreshTriggers(
   realtimeTopic: string | string[] | undefined,
   onRefresh: () => void,
-): void {
-  subscribeRealtimeTopics(realtimeTopic, onRefresh);
-  subscribePageRefresh(onRefresh);
+): LiveGate {
+  const gate = useLiveGate(onRefresh);
+  subscribeRealtimeTopics(realtimeTopic, gate.trigger);
+  subscribePageRefresh(gate);
+  return gate;
 }
 
 function subscribeRealtimeTopics(
   topic: string | string[] | undefined,
-  onEvent: () => void,
+  onEvent: (event: object) => void,
 ): void {
   if (!topic) return;
   const topics = Array.isArray(topic) ? topic : [topic];
   for (const entry of topics) {
     useRealtimeTopic(entry, (event) => {
       if (!("type" in event)) return;
-      onEvent();
+      onEvent(event);
     });
   }
 }
 
 // Mounted only: the page refresh is a browser event, and a block the server
 // renders has nothing to refetch.
-function subscribePageRefresh(onRefresh: () => void): void {
-  let unsubscribe: (() => void) | undefined;
+function subscribePageRefresh(gate: LiveGate): void {
+  const unsubscribes: Array<() => void> = [];
   onMounted(() => {
-    unsubscribe = onPageBlocksRefresh(onRefresh);
+    unsubscribes.push(
+      onPageBlocksRefresh(() => gate.catchUp()),
+      onLivePageBlocksRefresh(gate.trigger),
+    );
   });
-  onBeforeUnmount(() => unsubscribe?.());
+  onBeforeUnmount(() => unsubscribes.splice(0).forEach((stop) => stop()));
 }

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/cellHelpers.ts

@@ -4,6 +4,8 @@ import {
   type ComposableText,
   isComposedText,
 } from "../../../../../dms-core/app/utils/composedText";
+import type { Tone } from "../../../types/tone";
+import { DMS_TONE_TEXT, isDmsTone } from "../../utils/tone";
 
 // What the cell data types share: reading a sibling field off the row, and
 // the text tones a cell takes.
@@ -13,6 +15,28 @@ export type Row = Record<string, unknown> | undefined;
 export const readRowField = (row: Row, field: string | undefined): unknown =>
   field && row ? get(row, field) : undefined;
 
+/**
+ * The `Tone` a row field holds (`toneField` of a display), or nothing when the
+ * field is unset or holds no known tone.
+ */
+export const readRowTone = (
+  row: Row,
+  field: string | undefined,
+): Tone | undefined => {
+  const tone = readRowField(row, field);
+  return typeof tone === "string" && isDmsTone(tone) ? tone : undefined;
+};
+
+/** The text colour of the row's tone, else `fallback` (the display's own). */
+export const rowToneTextClass = (
+  row: Row,
+  field: string | undefined,
+  fallback: string,
+): string => {
+  const tone = readRowTone(row, field);
+  return tone ? DMS_TONE_TEXT[tone] : fallback;
+};
+
 export const stringOf = (value: unknown): string | undefined =>
   value === null || value === undefined || value === ""
     ? undefined

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/metricCells.ts

@@ -3,8 +3,14 @@ import type { DataType } from "#dms-core/app/composables/data-types/useDataType"
 import StatusPill from "../../../components/status-pill/StatusPill.vue";
 import MonoCell from "../../components/table/MonoCell.vue";
 import { useComposedText } from "../../../../../dms-core/app/composables/translation/useComposedText";
-import { isDmsTone } from "../../utils/tone";
-import { readRowField, readSubline, toneClass, type Row } from "./cellHelpers";
+import {
+  readRowField,
+  readRowTone,
+  readSubline,
+  rowToneTextClass,
+  toneClass,
+  type Row,
+} from "./cellHelpers";
 
 const Sparkline = defineAsyncComponent(
   () => import("../../../components/chart/internal/Sparkline.vue"),
@@ -34,9 +40,7 @@ interface StatusPillOptions {
 
 // A row field that holds no known tone gives way to the column's map.
 function statusPillTone(opts: StatusPillOptions, key: string, row: Row) {
-  const rowTone = readRowField(row, opts.toneField);
-  if (typeof rowTone === "string" && isDmsTone(rowTone)) return rowTone;
-  return opts.tones?.[key] ?? "neutral";
+  return readRowTone(row, opts.toneField) ?? opts.tones?.[key] ?? "neutral";
 }
 
 /**
@@ -186,6 +190,17 @@ const withSymbol = (
 ): string =>
   `${new Intl.NumberFormat(locale, { maximumFractionDigits }).format(value)} ${symbol}`;
 
+/** A duration always in milliseconds, its digits grouped: "2,149 ms". */
+export function formatMilliseconds(ms: number, locale: string): string {
+  const figure = new Intl.NumberFormat(locale, {
+    maximumFractionDigits: 0,
+    // `true` groups a four-digit figure too, where a locale's default (es,
+    // pl) would leave "2149" against "12.149" further down the column.
+    useGrouping: true,
+  }).format(ms);
+  return `${figure} ms`;
+}
+
 /**
  * A duration in its most readable unit: "910 ms", "1.8 s", "4 min 12 s",
  * "2 h 5 min".
@@ -225,8 +240,42 @@ export function formatBytes(bytes: number, locale: string): string {
   );
 }
 
-const figure = (text: string) =>
-  h("span", { class: [FIGURE_CLASS, "block text-right text-toned"] }, text);
+const FIGURE_TONE_CLASS = "text-toned";
+
+const figure = (text: string, toneClass = FIGURE_TONE_CLASS) =>
+  h("span", { class: [FIGURE_CLASS, "block text-right", toneClass] }, text);
+
+interface DurationOptions {
+  unit?: string;
+  /** `readable` (the default) or `ms`. */
+  format?: string;
+  /** Row field holding the figure's tone. */
+  toneField?: string;
+}
+
+const DURATION_FORMATS: Record<string, typeof formatDuration> = {
+  readable: formatDuration,
+  ms: formatMilliseconds,
+};
+
+/**
+ * `duration`: the figure in its most readable unit, or in milliseconds
+ * (`format: "ms"`), in the tone the row gives (`toneField`).
+ */
+function renderDuration(
+  value: unknown,
+  locale: string,
+  options: unknown,
+  row: Row,
+) {
+  const opts = (options ?? {}) as DurationOptions;
+  const ms = numberOf(value) * (DURATION_UNIT_MS[opts.unit ?? "ms"] ?? 1);
+  const format = DURATION_FORMATS[opts.format ?? "readable"] ?? formatDuration;
+  return figure(
+    format(ms, locale),
+    rowToneTextClass(row, opts.toneField, FIGURE_TONE_CLASS),
+  );
+}
 
 /**
  * Cell data types a column picks through its `display` option to draw a
@@ -259,15 +308,8 @@ export const registerMetricCellTypes = (
   registerDataType({
     id: "duration",
     formatter: {
-      default: (value, locale, options) => {
-        const unit = (options as { unit?: string } | undefined)?.unit ?? "ms";
-        return figure(
-          formatDuration(
-            numberOf(value) * (DURATION_UNIT_MS[unit] ?? 1),
-            locale,
-          ),
-        );
-      },
+      default: (value, locale, options, row) =>
+        renderDuration(value, locale, options, row),
     },
   });
   registerDataType({

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/registerDefaults.ts

@@ -1,5 +1,5 @@
 import { registerFieldTypes } from "./registerFieldTypes";
-import { defineAsyncComponent, type VNode } from "vue";
+import { defineAsyncComponent, type VNode, type VNodeChild } from "vue";
 import type { DataType } from "#dms-core/app/composables/data-types/useDataType";
 import UAvatar from "@nuxt/ui/components/Avatar.vue";
 import UBadge from "@nuxt/ui/components/Badge.vue";
@@ -10,6 +10,7 @@ import { mapRelationBeforeState, sameRelationValue } from "./relationValue";
 import {
   isSet,
   readRowField,
+  readRowTone,
   readSubline,
   type Row,
   stringOf,
@@ -21,7 +22,7 @@ import { useComposedText } from "../../../../../dms-core/app/composables/transla
 import StatusPill, {
   type StatusPillVariant,
 } from "../../../components/status-pill/StatusPill.vue";
-import { isDmsTone } from "../../utils/tone";
+import { DMS_TONE_TEXT, isDmsTone } from "../../utils/tone";
 import IdentityCell from "../../components/table-view/IdentityCell.vue";
 import {
   firstNameOf,
@@ -738,6 +739,32 @@ const registerCellTypes = (registerDataType: (dataType: DataType) => void) => {
   });
 };
 
+interface TextOptions {
+  /** Row field holding the text's tone. */
+  toneField?: string;
+}
+
+/**
+ * `string`: the value as written, in the tone the row gives (`toneField`) when
+ * it gives one; a row without one keeps the bare value, as a string column
+ * always drew it.
+ */
+function renderText(
+  value: unknown,
+  _locale: string,
+  options?: unknown,
+  row?: Row,
+): unknown {
+  const tone = readRowTone(
+    row,
+    (options as TextOptions | undefined)?.toneField,
+  );
+  if (!tone) return value;
+  // The value stays the child, as the untoned cell returns it: a number or a
+  // list renders as it did, never as "[object Object]".
+  return h("span", { class: DMS_TONE_TEXT[tone] }, [value as VNodeChild]);
+}
+
 const registerPrimitiveTypes = (
   registerDataType: (dataType: DataType) => void,
 ) => {
@@ -747,7 +774,7 @@ const registerPrimitiveTypes = (
   });
   registerDataType({
     id: "string",
-    formatter: { default: (value: unknown, _locale: string) => value },
+    formatter: { default: renderText },
   });
   registerDataType({
     id: "price",

package/frontend-vue/layers/dms-ui/app/build/composables/live/currentPageLive.ts

@@ -0,0 +1,107 @@
+import {
+  computed,
+  getCurrentScope,
+  onScopeDispose,
+  shallowRef,
+  type ComputedRef,
+} from "vue";
+import type {
+  LiveSubscription,
+  PageLiveController,
+} from "./pageLiveController";
+
+// Client-only state: the page renderer sets it in the browser, where one app
+// shows one page at a time. The server renders no event and no refetch, so it
+// never needs one, and a module-level value there would be shared between
+// requests.
+const currentController = shallowRef<PageLiveController | null>(null);
+
+/**
+ * The live controller of the page on screen, `null` when the page has no
+ * `live` option (or while server-rendering).
+ *
+ * @internal
+ */
+export function currentPageLive(): PageLiveController | null {
+  return currentController.value;
+}
+
+/**
+ * Installs the controller of the page on screen. The page renderer calls it.
+ *
+ * @internal
+ */
+export function setCurrentPageLive(controller: PageLiveController | null) {
+  if (typeof window === "undefined") return;
+  currentController.value = controller;
+}
+
+/** @internal */
+export interface LiveGate {
+  /** An event behind the block arrived: refetch, now or later, or count it. */
+  trigger(event?: object): void;
+  /** Events the block missed while the page is paused. */
+  missed: ComputedRef<number>;
+  /** When the block last read through the gate (ms), 0 before or without `live`. */
+  lastReadAt: ComputedRef<number>;
+  /** Refetches now and forgets what was missed. */
+  catchUp(): void;
+  /** Records a read the caller makes itself (see LiveSubscription). */
+  acknowledge(): void;
+}
+
+interface BoundSubscription {
+  controller: PageLiveController;
+  subscription: LiveSubscription;
+}
+
+/**
+ * The gate a block's refetch goes through. On a page without `live` it calls
+ * `refresh` at once, as before. Bound lazily, on the first event, to the
+ * controller of the page on screen: a block of the page layout sets up before
+ * the page installs its controller.
+ *
+ * @internal
+ */
+export function useLiveGate(refresh: () => void): LiveGate {
+  const bound = shallowRef<BoundSubscription | null>(null);
+
+  const unbind = () => {
+    bound.value?.subscription.unsubscribe();
+    bound.value = null;
+  };
+
+  const resolve = (): LiveSubscription | null => {
+    const controller = currentController.value;
+    if (bound.value?.controller === controller) {
+      return bound.value?.subscription ?? null;
+    }
+    unbind();
+    if (!controller) return null;
+    bound.value = { controller, subscription: controller.subscribe(refresh) };
+    return bound.value.subscription;
+  };
+
+  if (getCurrentScope()) onScopeDispose(unbind);
+
+  const current = () =>
+    bound.value?.controller === currentController.value
+      ? (bound.value?.subscription ?? null)
+      : null;
+
+  return {
+    trigger: (event) => {
+      const subscription = resolve();
+      if (subscription) subscription.trigger(event);
+      else refresh();
+    },
+    missed: computed(() => current()?.missed.value ?? 0),
+    lastReadAt: computed(() => current()?.lastReadAt.value ?? 0),
+    catchUp: () => {
+      const subscription = resolve();
+      if (subscription) subscription.catchUp();
+      else refresh();
+    },
+    acknowledge: () => resolve()?.acknowledge(),
+  };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/live/formatElapsed.ts

@@ -0,0 +1,25 @@
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+
+/** The unit an elapsed time reads in: seconds, then minutes, then hours. */
+export type ElapsedUnit = "seconds" | "minutes" | "hours";
+
+export interface Elapsed {
+  unit: ElapsedUnit;
+  count: number;
+}
+
+/**
+ * A duration as "N s", "N min" or "N h": the largest unit it fills once,
+ * rounded down. A negative duration (a clock set back) reads as 0 s.
+ *
+ * @internal
+ */
+export function formatElapsed(elapsedMs: number): Elapsed {
+  const seconds = Math.max(0, Math.floor(elapsedMs / MS_PER_SECOND));
+  if (seconds < SECONDS_PER_MINUTE) return { unit: "seconds", count: seconds };
+  const minutes = Math.floor(seconds / SECONDS_PER_MINUTE);
+  if (minutes < MINUTES_PER_HOUR) return { unit: "minutes", count: minutes };
+  return { unit: "hours", count: Math.floor(minutes / MINUTES_PER_HOUR) };
+}