@antelopejs/dms 0.7.6 → 0.7.8

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

@@ -9,6 +9,10 @@ import {
   type ReplaceUrlVariablesContext,
   resolveUrlVariables,
 } from "../../utils/urlVariables";
+import {
+  appendPeriodToUrl,
+  usePeriodScope,
+} from "#dms-core/app/composables/period/usePeriodScope";
 
 type Query = Record<string, unknown>;
 
@@ -37,7 +41,13 @@ const SEARCH_KEY = "search";
 const SORT_KEYS = ["sortKey", "sortDirection"];
 const PAGE_KEYS = ["offset", "limit"];
 const DESCENDING = "desc";
+/**
+ * Sent while a `liveHold` table is paused: the moment its rows were frozen,
+ * for a source route to list the rows as they stood then.
+ */
+export const LIVE_HELD_AT_QUERY_KEY = "liveHeldAt";
 const NO_ROUTE_VALUES: ReplaceUrlVariablesContext = { routeQuery: {} };
+const ROW_ID_TOKEN = "{id}";
 
 type SourceCapabilities = TableViewSourceConfig["capabilities"];
 
@@ -54,6 +64,7 @@ const QUERY_KEY_CAPABILITIES: Array<
 /**
  * The part of the list query a source route handles, by its capabilities: a
  * key no capability names (a controller's `showArchived`…) never reaches it.
+ * The live hold's bound always does: a route not reading it lists as usual.
  */
 export function sourceRouteQuery(
   query: Query,
@@ -61,6 +72,7 @@ export function sourceRouteQuery(
 ): Query {
   return Object.fromEntries(
     Object.entries(query).filter(([key]) => {
+      if (key === LIVE_HELD_AT_QUERY_KEY) return true;
       const entry = QUERY_KEY_CAPABILITIES.find(([matches]) => matches(key));
       return !!entry && !!capabilities[entry[1]];
     }),
@@ -135,28 +147,35 @@ function emptySourcePage<T>(query: Query): TableViewListResponse<T> {
  * the rest to the browser; a route answering one page is taken as it is.
  *
  * A source's `{{params.X}}` and `{{query.X}}` tokens are filled from `route`;
- * while one has no value nothing is requested and the list is empty.
- * `sourceUrl` is the URL requested, for the caller to list again when it
- * changes.
+ * while one has no value nothing is requested and the list is empty. A
+ * source's `periodScope` adds the period of its selector to the URL, like a
+ * chart's; until that selector registers, nothing is requested and the list
+ * answers `null`, which the table draws as its skeleton. `sourceUrl` is the
+ * URL requested, for the caller to list again when it changes.
  */
 export function useTableRows<T extends Record<string, unknown>>(
   options: TableRowsOptions,
 ) {
   const { api, location, source, columns } = options;
-
-  const sourceUrl = computed(() =>
-    source
-      ? resolveUrlVariables(
-          source.fetchUrl,
-          options.route?.() ?? NO_ROUTE_VALUES,
-        )
-      : undefined,
+  const periodScope = usePeriodScope(source?.periodScope);
+  const isPeriodPending = computed(
+    () => !!source?.periodScope && !periodScope.value,
   );
 
+  const sourceUrl = computed(() => {
+    if (!source) return undefined;
+    const url = resolveUrlVariables(
+      source.fetchUrl,
+      options.route?.() ?? NO_ROUTE_VALUES,
+    );
+    return source.periodScope ? appendPeriodToUrl(url, periodScope.value) : url;
+  });
+
   const listFromSource = async (
     sourceConfig: TableViewSourceConfig,
     query: Query,
-  ): Promise<TableViewListResponse<T>> => {
+  ): Promise<TableViewListResponse<T> | null> => {
+    if (isPeriodPending.value) return null;
     const url = sourceUrl.value;
     if (!url) return emptySourcePage(query);
     const { capabilities } = sourceConfig;
@@ -173,7 +192,7 @@ export function useTableRows<T extends Record<string, unknown>>(
     return processSourceRows(response.results, query, capabilities, columns);
   };
 
-  const list = (query: Query): Promise<TableViewListResponse<T>> =>
+  const list = (query: Query): Promise<TableViewListResponse<T> | null> =>
     source
       ? listFromSource(source, query)
       : api<TableViewListResponse<T>>(`${location}/list`, { query });
@@ -190,21 +209,37 @@ export function useTableRows<T extends Record<string, unknown>>(
     }
     const totals = await Promise.all(
       queries.map(async ({ id, query }) => {
-        const { total } = await listFromSource(source, {
+        const page = await listFromSource(source, {
           ...query,
           offset: 0,
           limit: 1,
         });
-        return [id, total] as const;
+        return page ? [[id, page.total] as const] : [];
       }),
     );
-    return Object.fromEntries(totals);
+    return Object.fromEntries(totals.flat());
+  };
+
+  // A source reads one row through its `fetchRowUrl`, if it declares one. It
+  // sends no list query, the period included: one row by id depends on none.
+  const getSourceRow = (
+    sourceConfig: TableViewSourceConfig,
+    id: string,
+  ): Promise<T | undefined> => {
+    const url = resolveUrlVariables(
+      sourceConfig.fetchRowUrl?.replaceAll(
+        ROW_ID_TOKEN,
+        encodeURIComponent(id),
+      ),
+      options.route?.() ?? NO_ROUTE_VALUES,
+    );
+    return url ? api<T>(url) : Promise.resolve(undefined);
   };
 
-  /** One row by id: a source has no route for it. */
+  /** One row by id: a source's `fetchRowUrl`, a controller's `get` route. */
   const getRow = (id: string): Promise<T | undefined> =>
     source
-      ? Promise.resolve(undefined)
+      ? getSourceRow(source, id)
       : api<T>(`${location}/get`, { query: { id } });
 
   return { isSource: !!source, sourceUrl, list, countBatch, getRow };

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

@@ -123,6 +123,7 @@ export const useTableViewConfig = <T extends Data>(
     maxHeight: config.maxHeight,
     rowIdKey: config.rowIdKey,
     rowActions: config.rowActions,
+    rowClick: config.rowClick,
     customNavItems: config.customNavItems,
     componentId: config.componentId,
     formContainer: config.formContainer,

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/utils/recordLink.ts

@@ -1,3 +1,4 @@
+import type { CustomRowAction } from "../../../../types/row-action";
 import { readTableUrlKey, type TableUrlScope } from "./views";
 
 /** Query key of the row a `deepLink` action has open. */
@@ -21,12 +22,70 @@ export function readRecordId(
 /**
  * Writes (or, without an id, removes) the open row in the browser's URL in
  * place: no visit, no history entry, the link and a reload open it again.
+ * Returns what it wrote, for {@link clearWrittenRecord}.
  */
-export function writeRecordId(scope: TableUrlScope, id?: string): void {
-  if (typeof window === "undefined") return;
+export function writeRecordId(
+  scope: TableUrlScope,
+  id?: string,
+): WrittenRecord | undefined {
+  if (typeof window === "undefined") return undefined;
   const url = new URL(window.location.href);
   const key = recordUrlKey(scope);
   if (id) url.searchParams.set(key, id);
   else url.searchParams.delete(key);
   window.history.replaceState(window.history.state, "", url);
+  return id ? { pathname: url.pathname, key, id } : undefined;
+}
+
+/**
+ * Whether an action keeps the row it opens in the URL: a side panel does
+ * unless its target or the action sets `deepLink: false`, a drawer or a modal
+ * only with the action's `deepLink: true`.
+ */
+export function isDeepLinkAction(action: CustomRowAction): boolean {
+  if (action.target.type !== "sidePanel") return !!action.deepLink;
+  return (action.deepLink ?? action.target.deepLink) !== false;
+}
+
+/** The row a table wrote in the URL, and the page it wrote it on. */
+export interface WrittenRecord {
+  pathname: string;
+  key: string;
+  id: string;
+}
+
+/**
+ * Removes the row a table wrote in the URL, only while the URL still holds
+ * it: a container closing as the user leaves the page must not erase the
+ * `?record=` of the page reached.
+ */
+export function clearWrittenRecord(written: WrittenRecord | undefined): void {
+  if (typeof window === "undefined" || !written) return;
+  const url = new URL(window.location.href);
+  if (url.pathname !== written.pathname) return;
+  if (url.searchParams.get(written.key) !== written.id) return;
+  url.searchParams.delete(written.key);
+  window.history.replaceState(window.history.state, "", url);
+}
+
+/** Where a deep link finds its row: among the rows listed, or by id. */
+export interface DeepLinkedRowSource<T> {
+  listed: T[] | undefined;
+  idOf: (row: T) => string | undefined;
+  /** Reads one row: a controller's `get` route, a source's `fetchRowUrl`. */
+  getRow: (id: string) => Promise<T | undefined>;
+}
+
+/**
+ * The row a deep link names: the listed one, else the one read by id — a row
+ * beyond the first page. A row the route cannot answer (gone, a 404) opens
+ * nothing.
+ */
+export async function resolveDeepLinkedRow<T>(
+  id: string,
+  source: DeepLinkedRowSource<T>,
+): Promise<T | undefined> {
+  const listed = source.listed?.find((row) => source.idOf(row) === id);
+  if (listed) return listed;
+  return source.getRow(id).catch(() => undefined);
 }

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

@@ -0,0 +1,73 @@
+/**
+ * What runs a row's click action (backend `TableViewRowClick`): a double-click
+ * by default, or a single click.
+ */
+export type TableViewRowClick = "single" | "double";
+
+/** A reason a pointer event on a row must not run its click action. */
+type RowClickGuard = (event: MouseEvent) => boolean;
+
+interface RowClickTrigger {
+  eventType: string;
+  guards: RowClickGuard[];
+}
+
+const DEFAULT_ROW_CLICK: TableViewRowClick = "double";
+
+// The controls a row may hold: a click on one is that control's, not the
+// row's.
+const ROW_CONTROL_SELECTOR = [
+  "a",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "label",
+  "summary",
+  "[role='button']",
+  "[role='checkbox']",
+  "[role='menuitem']",
+  "[role='switch']",
+  "[contenteditable='true']",
+].join(", ");
+
+// The second click of a double-click: the first one already ran the action.
+const isRepeatClick: RowClickGuard = (event) => event.detail > 1;
+
+const isOnRowControl: RowClickGuard = (event) => {
+  const target = event.target as Element | null;
+  const control = target?.closest?.(ROW_CONTROL_SELECTOR);
+  if (!control) return false;
+  const row = event.currentTarget as Element | null;
+  return !row || row.contains(control);
+};
+
+// A click ending a drag over the cells selects their text: the user copies a
+// value, not opens the row.
+const endsTextSelection: RowClickGuard = () => {
+  if (typeof window === "undefined") return false;
+  const selection = window.getSelection();
+  return !!selection && !selection.isCollapsed && selection.toString() !== "";
+};
+
+const ROW_CLICK_TRIGGERS: Record<TableViewRowClick, RowClickTrigger> = {
+  // Unchanged from before `rowClick` existed: any double-click on the row.
+  double: { eventType: "dblclick", guards: [] },
+  single: {
+    eventType: "click",
+    guards: [isRepeatClick, isOnRowControl, endsTextSelection],
+  },
+};
+
+/**
+ * Whether `event`, a click or a double-click on a row, runs the row's click
+ * action under the table's `rowClick` mode.
+ */
+export function isRowClickTrigger(
+  mode: TableViewRowClick | undefined,
+  event: MouseEvent,
+): boolean {
+  const trigger = ROW_CLICK_TRIGGERS[mode ?? DEFAULT_ROW_CLICK];
+  if (!trigger || event.type !== trigger.eventType) return false;
+  return !trigger.guards.some((guard) => guard(event));
+}

package/frontend-vue/layers/dms-ui/app/components/blocks/LiveToggleBlock.vue

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref } from "vue";
+import DmsSegmented from "../segmented/Segmented.vue";
+import { usePageLive } from "../../composables/live/usePageLive";
+import { formatElapsed } from "../../build/composables/live/formatElapsed";
+import { useLiveToggleShortcut } from "../../build/composables/live/useLiveToggleShortcut";
+import type { DefaultComponentProps } from "../../../../dms-core/app/types/component";
+
+interface LiveToggleBlockProps extends DefaultComponentProps {
+  align?: "left" | "center" | "right";
+  /** Shows "updated N s ago". */
+  showUpdatedAt?: boolean;
+}
+
+const props = withDefaults(defineProps<LiveToggleBlockProps>(), {
+  align: "right",
+  showUpdatedAt: true,
+});
+
+const DIRECT = "direct";
+const PAUSE = "pause";
+const TICK_MS = 1000;
+const ALIGN_CLASSES: Record<
+  NonNullable<LiveToggleBlockProps["align"]>,
+  string
+> = {
+  left: "justify-start",
+  center: "justify-center",
+  right: "justify-end",
+};
+
+const { t } = useI18n();
+const live = usePageLive();
+
+// The state lives in the browser (its storage, its clock): the server and the
+// hydrating render draw nothing, the mounted block draws the real state.
+const isMounted = ref(false);
+const now = ref(Date.now());
+let ticker: ReturnType<typeof setInterval> | undefined;
+
+onMounted(() => {
+  isMounted.value = true;
+  if (props.showUpdatedAt) {
+    ticker = setInterval(() => (now.value = Date.now()), TICK_MS);
+  }
+});
+onBeforeUnmount(() => clearInterval(ticker));
+
+const mode = computed({
+  get: () => (live.isPaused.value ? PAUSE : DIRECT),
+  set: (next: string | number) => {
+    if (next === PAUSE) live.pause();
+    else live.resume();
+  },
+});
+
+const items = computed(() => [
+  { value: DIRECT, label: t("dms.live.direct"), icon: "i-ph-broadcast" },
+  { value: PAUSE, label: t("dms.live.pause"), icon: "i-ph-pause" },
+]);
+
+const updatedLabel = computed(() => {
+  const at = live.lastUpdatedAt.value;
+  if (at === null) return "";
+  const { unit, count } = formatElapsed(now.value - at);
+  return t(`dms.live.updated_${unit}`, { count }, count);
+});
+
+useLiveToggleShortcut(() => live.toggle());
+</script>
+
+<template>
+  <div
+    v-if="isMounted && live.isEnabled.value"
+    class="dms-live-toggle flex flex-wrap items-center gap-2.5"
+    :class="ALIGN_CLASSES[align]"
+  >
+    <span
+      v-if="showUpdatedAt"
+      class="text-muted text-[12.5px] tabular-nums"
+      aria-live="off"
+    >
+      {{ updatedLabel }}
+    </span>
+    <DmsSegmented
+      v-model="mode"
+      :items="items"
+      :aria-label="t('dms.live.aria_label')"
+      size="sm"
+    />
+  </div>
+</template>

package/frontend-vue/layers/dms-ui/app/components/field-row/FieldRow.vue

@@ -107,15 +107,24 @@ const theme = tv({
     disabled: {
       true: { root: "opacity-55" },
     },
+    // Without a label cell, the control is the grid's only child: it spans
+    // both columns instead of falling into the form's 240px label column.
+    labeled: {
+      false: { control: "col-span-full" },
+    },
   },
 });
 
+const hasText = computed(
+  () => !!(props.label || props.description || slots.label || slots.details),
+);
 const ui = computed(() =>
   theme({
     layout: props.layout,
     inset: props.inset,
     spacing: props.spacing,
     disabled: props.disabled,
+    labeled: hasText.value,
   }),
 );
 const labelTag = computed(() => (props.labelFor ? "label" : "div"));
@@ -127,10 +136,7 @@ const { processI18n } = useTranslation();
 <template>
   <div :class="ui.root()">
     <div :class="ui.body()">
-      <div
-        v-if="props.label || props.description || slots.label || slots.details"
-        :class="ui.text()"
-      >
+      <div v-if="hasText" :class="ui.text()">
         <component
           :is="labelTag"
           v-if="props.label || slots.label"

package/frontend-vue/layers/dms-ui/app/components/period/PeriodSelector.vue

@@ -12,6 +12,7 @@ import type {
 } from "#dms-core/app/composables/period/types";
 import type { DefaultComponentProps } from "../../../../dms-core/app/types/component";
 import { usePeriodDraft } from "../../build/composables/period/usePeriodDraft";
+import { usePeriodLocation } from "../../build/composables/period/usePeriodLocation";
 import {
   type CalendarRange,
   calendarToRange,
@@ -21,6 +22,7 @@ import {
 } from "../../build/composables/period/periodDisplay";
 import PeriodRangeCalendar from "../../build/components/period/PeriodRangeCalendar.vue";
 import { useUserRegionalPreferences } from "#dms-core/app/composables/user/useUserRegionalPreferences";
+import { usePageLive } from "../../composables/live/usePageLive";
 
 interface Props extends DefaultComponentProps {
   id: string;
@@ -93,11 +95,28 @@ useWatch(props.watchActions || [], props.componentId);
 
 const { t, locale } = useI18n();
 
+// A paused live page keeps its period where it was: a relative preset
+// sliding every minute would refetch every block reading it.
+const { isPaused: isPagePaused } = usePageLive();
 const period = usePeriod({
   defaultPreset: props.defaultPreset,
   defaultComparison: props.defaultComparison,
   presets: props.presets,
   comparisons: props.comparisons,
+  holdClock: () => isPagePaused.value,
+});
+
+// Before the scope registers, so the cards' first request already carries
+// the period of the URL (or of the user's last choice), never the default.
+usePeriodLocation(period, {
+  id: props.id,
+  pageId: props.pageId,
+  fallback: {
+    preset: period.preset.value,
+    comparison: period.comparison.value,
+    customRange: null,
+    customCompareRange: null,
+  },
 });
 
 const cleanup = registerPeriodScope(props.id, period.state);