@antelopejs/dms 0.7.7 → 0.7.8

package/frontend-vue/layers/dms-ui/app/build/composables/period/periodQuery.ts

@@ -0,0 +1,330 @@
+import {
+  END_OF_DAY_HOURS,
+  END_OF_DAY_MINUTES,
+  END_OF_DAY_MS,
+  END_OF_DAY_SECONDS,
+  type PeriodComparison,
+  type PeriodPreset,
+  type PeriodRange,
+} from "#dms-core/app/composables/period/types";
+
+/** The range half of a selector's choice: a preset, or a custom range. */
+export interface PeriodRangeChoice {
+  preset: PeriodPreset;
+  customRange: PeriodRange | null;
+}
+
+/** The comparison half of a selector's choice. */
+export interface PeriodComparisonChoice {
+  comparison: PeriodComparison;
+  customCompareRange: PeriodRange | null;
+}
+
+/** What a selector keeps in the URL and in the user's preferences. */
+export interface PeriodSelection
+  extends PeriodRangeChoice,
+    PeriodComparisonChoice {}
+
+/** The menus a selection has to fit in. */
+export interface PeriodChoices {
+  presets: readonly PeriodPreset[];
+  comparisons: readonly PeriodComparison[];
+}
+
+/** A page URL query, or a selection kept in the preferences. */
+export type PeriodQuery = Record<string, unknown>;
+
+/** The keys one selector reads and writes. */
+export interface PeriodQueryKeys {
+  period: string;
+  compare: string;
+  from: string;
+  to: string;
+  compareFrom: string;
+  compareTo: string;
+}
+
+/** A source the halves of a selection are read from, in order. */
+export interface PeriodSource {
+  query: PeriodQuery;
+  keys: PeriodQueryKeys;
+}
+
+const CUSTOM_PRESET: PeriodPreset = "custom";
+const CUSTOM_COMPARISON: PeriodComparison = "custom";
+const KEY_NAMES: Array<keyof PeriodQueryKeys> = [
+  "period",
+  "compare",
+  "from",
+  "to",
+  "compareFrom",
+  "compareTo",
+];
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/;
+const MONTH_OFFSET = 1;
+const DATE_PART_LENGTH = 2;
+const YEAR_PART_LENGTH = 4;
+
+/**
+ * The keys of selector `id` in the page URL (`<id>.period`), or the bare keys
+ * (`period`) of a selection kept on its own.
+ */
+export function periodQueryKeys(id?: string): PeriodQueryKeys {
+  const prefix = id ? `${id}.` : "";
+  return Object.fromEntries(
+    KEY_NAMES.map((name) => [name, `${prefix}${name}`]),
+  ) as unknown as PeriodQueryKeys;
+}
+
+function readText(query: PeriodQuery, key: string): string | undefined {
+  const raw = query[key];
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  return typeof value === "string" && value ? value : undefined;
+}
+
+type DayBoundary = "start" | "end";
+
+function dayBoundary(day: Date, boundary: DayBoundary): Date {
+  if (boundary === "end") {
+    day.setHours(
+      END_OF_DAY_HOURS,
+      END_OF_DAY_MINUTES,
+      END_OF_DAY_SECONDS,
+      END_OF_DAY_MS,
+    );
+  }
+  return day;
+}
+
+/** A local calendar day, refused when it does not exist (`2026-02-30`). */
+function parseIsoDay(match: RegExpExecArray, boundary: DayBoundary) {
+  const [year, month, day] = match.slice(1).map(Number);
+  const date = new Date(year!, month! - MONTH_OFFSET, day);
+  const exists =
+    date.getFullYear() === year &&
+    date.getMonth() === month! - MONTH_OFFSET &&
+    date.getDate() === day;
+  return exists ? dayBoundary(date, boundary) : null;
+}
+
+/**
+ * A bound read from the URL: an ISO date is the start (`from`) or the end
+ * (`to`) of that local day, an ISO date-time is that instant. Anything else
+ * is `null`.
+ */
+export function parsePeriodDate(
+  text: string | undefined,
+  boundary: DayBoundary,
+): Date | null {
+  if (!text) return null;
+  const day = ISO_DATE.exec(text);
+  if (day) return parseIsoDay(day, boundary);
+  if (!ISO_DATE_TIME.test(text)) return null;
+  const date = new Date(text);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function pad(value: number, length = DATE_PART_LENGTH): string {
+  return String(value).padStart(length, "0");
+}
+
+function isDayBoundary(date: Date, boundary: DayBoundary): boolean {
+  const day = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+  return dayBoundary(day, boundary).getTime() === date.getTime();
+}
+
+/**
+ * A bound as the URL writes it: the bare local day when it falls on that
+ * day's boundary (a range picked in the calendar), the ISO instant otherwise.
+ */
+export function formatPeriodDate(date: Date, boundary: DayBoundary): string {
+  if (!isDayBoundary(date, boundary)) return date.toISOString();
+  return [
+    pad(date.getFullYear(), YEAR_PART_LENGTH),
+    pad(date.getMonth() + MONTH_OFFSET),
+    pad(date.getDate()),
+  ].join("-");
+}
+
+function readRange(
+  query: PeriodQuery,
+  fromKey: string,
+  toKey: string,
+): PeriodRange | null {
+  const from = parsePeriodDate(readText(query, fromKey), "start");
+  const to = parsePeriodDate(readText(query, toKey), "end");
+  if (!from || !to || from.getTime() > to.getTime()) return null;
+  return { from, to };
+}
+
+/**
+ * The range a source names, when the selector offers it: a custom range
+ * (`from` and `to`) first, then a preset (`period`).
+ */
+export function readRangeChoice(
+  source: PeriodSource,
+  choices: PeriodChoices,
+): PeriodRangeChoice | null {
+  const { query, keys } = source;
+  const customRange = readRange(query, keys.from, keys.to);
+  if (customRange && choices.presets.includes(CUSTOM_PRESET)) {
+    return { preset: CUSTOM_PRESET, customRange };
+  }
+  const preset = choices.presets.find(
+    (entry) => entry === readText(query, keys.period),
+  );
+  if (!preset || preset === CUSTOM_PRESET) return null;
+  return { preset, customRange: null };
+}
+
+/**
+ * The comparison a source names, when the selector offers it; a custom one
+ * needs its `compareFrom` and `compareTo`.
+ */
+export function readComparisonChoice(
+  source: PeriodSource,
+  choices: PeriodChoices,
+): PeriodComparisonChoice | null {
+  const { query, keys } = source;
+  const comparison = choices.comparisons.find(
+    (entry) => entry === readText(query, keys.compare),
+  );
+  if (!comparison) return null;
+  if (comparison !== CUSTOM_COMPARISON) {
+    return { comparison, customCompareRange: null };
+  }
+  const customCompareRange = readRange(query, keys.compareFrom, keys.compareTo);
+  return customCompareRange ? { comparison, customCompareRange } : null;
+}
+
+function firstChoice<C>(
+  sources: PeriodSource[],
+  read: (source: PeriodSource) => C | null,
+): C | undefined {
+  for (const source of sources) {
+    const choice = read(source);
+    if (choice) return choice;
+  }
+  return undefined;
+}
+
+/**
+ * The selection the sources give, read in order (the URL, then the user's
+ * last choice), each half on its own: a half no source names validly comes
+ * from `fallback`, silently.
+ */
+export function resolvePeriodSelection(
+  sources: PeriodSource[],
+  choices: PeriodChoices,
+  fallback: PeriodSelection,
+): PeriodSelection {
+  const range =
+    firstChoice(sources, (source) => readRangeChoice(source, choices)) ??
+    fallback;
+  const comparison =
+    firstChoice(sources, (source) => readComparisonChoice(source, choices)) ??
+    fallback;
+  return {
+    preset: range.preset,
+    customRange: range.customRange,
+    comparison: comparison.comparison,
+    customCompareRange: comparison.customCompareRange,
+  };
+}
+
+function rangeEntries(
+  range: PeriodRange | null,
+  fromKey: string,
+  toKey: string,
+): Array<[string, string]> {
+  if (!range) return [];
+  return [
+    [fromKey, formatPeriodDate(range.from, "start")],
+    [toKey, formatPeriodDate(range.to, "end")],
+  ];
+}
+
+/** A selection as the keys `keys` name. */
+export function writePeriodQuery(
+  selection: PeriodSelection,
+  keys: PeriodQueryKeys,
+): Record<string, string> {
+  const isCustom = selection.preset === CUSTOM_PRESET;
+  const isCustomCompare = selection.comparison === CUSTOM_COMPARISON;
+  return Object.fromEntries([
+    ...(isCustom
+      ? rangeEntries(selection.customRange, keys.from, keys.to)
+      : [[keys.period, selection.preset]]),
+    [keys.compare, selection.comparison],
+    ...(isCustomCompare
+      ? rangeEntries(
+          selection.customCompareRange,
+          keys.compareFrom,
+          keys.compareTo,
+        )
+      : []),
+  ]);
+}
+
+/** Whether `query` already holds what `keys` would write for `selection`. */
+export function isPeriodQueryCurrent(
+  query: PeriodQuery,
+  keys: PeriodQueryKeys,
+  selection: PeriodSelection,
+): boolean {
+  const written = writePeriodQuery(selection, keys);
+  return Object.values(keys).every(
+    (key) => readText(query, key) === written[key],
+  );
+}
+
+/**
+ * The search part of a URL with `selection` written under `keys`, and the
+ * keys it no longer uses (a preset's `period` once a custom range is picked)
+ * removed. Every other parameter, another selector's included, is kept as it
+ * was, in its place.
+ */
+export function mergePeriodSearch(
+  search: string,
+  keys: PeriodQueryKeys,
+  selection: PeriodSelection,
+): string {
+  const params = new URLSearchParams(search);
+  const written = writePeriodQuery(selection, keys);
+  for (const key of Object.values(keys)) {
+    const value = written[key];
+    if (value === undefined) params.delete(key);
+    else params.set(key, value);
+  }
+  const text = params.toString();
+  return text ? `?${text}` : "";
+}
+
+/** The last choices of the selectors, by `rememberedPeriodKey`, oldest first. */
+export type RememberedPeriods = Record<string, Record<string, string>>;
+
+/** How many selectors' last choices the browser keeps. */
+export const REMEMBERED_PERIODS_LIMIT = 20;
+
+/** The entry of selector `id` of page `pageId` among the last choices. */
+export function rememberedPeriodKey(pageId: string, id: string): string {
+  return `${pageId}#${id}`;
+}
+
+/**
+ * The last choices with `key`'s set to `query`, moved last as the most
+ * recent, and only the `limit` most recent kept: the store lives in a
+ * cookie, which must not grow with every page a user ever opened.
+ */
+export function rememberPeriod(
+  store: unknown,
+  key: string,
+  query: Record<string, string>,
+  limit = REMEMBERED_PERIODS_LIMIT,
+): RememberedPeriods {
+  const entries = Object.entries(
+    store && typeof store === "object" ? (store as RememberedPeriods) : {},
+  ).filter(([entry]) => entry !== key);
+  return Object.fromEntries([...entries, [key, query]].slice(-limit));
+}

package/frontend-vue/layers/dms-ui/app/build/composables/period/usePeriodLocation.ts

@@ -0,0 +1,189 @@
+import { router as inertiaRouter } from "@inertiajs/vue3";
+import { onMounted, watch } from "vue";
+import type { UsePeriodReturn } from "#dms-core/app/composables/period/usePeriod";
+import {
+  isPeriodQueryCurrent,
+  mergePeriodSearch,
+  periodQueryKeys,
+  rememberedPeriodKey,
+  rememberPeriod,
+  type RememberedPeriods,
+  type PeriodQuery,
+  type PeriodQueryKeys,
+  type PeriodSelection,
+  type PeriodSource,
+  resolvePeriodSelection,
+  writePeriodQuery,
+} from "./periodQuery";
+
+export interface PeriodLocationOptions {
+  /** The selector's id: the prefix of its URL keys. */
+  id: string;
+  /** The page it is on: its last choice is kept per page and per id. */
+  pageId: string;
+  /** What the period falls back to when no source names a valid one. */
+  fallback: PeriodSelection;
+}
+
+/**
+ * The preference holding the user's last choice of each selector
+ * (`usePreferences`), capped to the most recent ones.
+ */
+export const PERIOD_PREFERENCE_KEY = "periods";
+const STORED_KEYS = periodQueryKeys();
+
+function readSelection(period: UsePeriodReturn): PeriodSelection {
+  return {
+    preset: period.preset.value,
+    comparison: period.comparison.value,
+    customRange: period.customRange.value,
+    customCompareRange: period.customCompareRange.value,
+  };
+}
+
+function applySelection(
+  period: UsePeriodReturn,
+  selection: PeriodSelection,
+): void {
+  period.customRange.value = selection.customRange;
+  period.customCompareRange.value = selection.customCompareRange;
+  period.preset.value = selection.preset;
+  period.comparison.value = selection.comparison;
+}
+
+function urlKeysText(query: PeriodQuery, keys: PeriodQueryKeys): string {
+  return JSON.stringify(Object.values(keys).map((key) => query[key] ?? null));
+}
+
+function selectionText(selection: PeriodSelection): string {
+  return JSON.stringify(writePeriodQuery(selection, STORED_KEYS));
+}
+
+/**
+ * Writes the period into the URL: the history entry is replaced, and no
+ * request reloads the page. The browser's URL is written at once, so a
+ * second selector writing in the same tick merges into it; Inertia's
+ * client-side replace then moves its page URL, which the DMS route follows,
+ * so a component writing the query from the route (a tab, a quick action)
+ * carries the period on instead of the one the page was opened with.
+ */
+function replacePeriodInUrl(
+  keys: PeriodQueryKeys,
+  selection: PeriodSelection,
+): string | null {
+  if (typeof window === "undefined") return null;
+  const url = new URL(window.location.href);
+  const query = Object.fromEntries(url.searchParams);
+  if (isPeriodQueryCurrent(query, keys, selection)) return null;
+  url.search = mergePeriodSearch(url.search, keys, selection);
+  const written = urlKeysText(Object.fromEntries(url.searchParams), keys);
+  window.history.replaceState(window.history.state, "", url);
+  inertiaRouter.replace({
+    url: `${url.pathname}${url.search}${url.hash}`,
+    preserveState: true,
+    preserveScroll: true,
+  });
+  return written;
+}
+
+/** The user's last choice of one selector, kept in the preferences. */
+function useRememberedPeriod(pageId: string, id: string) {
+  const { getPreference, setPreference } = usePreferences();
+  const key = rememberedPeriodKey(pageId, id);
+  const all = () => getPreference<RememberedPeriods>(PERIOD_PREFERENCE_KEY, {});
+  return {
+    source: (): PeriodSource => ({
+      query: all()[key] ?? {},
+      keys: STORED_KEYS,
+    }),
+    remember: (selection: PeriodSelection) =>
+      setPreference(
+        PERIOD_PREFERENCE_KEY,
+        rememberPeriod(all(), key, writePeriodQuery(selection, STORED_KEYS)),
+      ),
+  };
+}
+
+/**
+ * The URL writes of one selector. The route catches up with each write
+ * later, and a pick made meanwhile must not be undone by the URL of the one
+ * before: `isEcho` tells a route naming a URL written here from a change.
+ */
+function usePeriodUrlWriter(keys: PeriodQueryKeys) {
+  const pending: string[] = [];
+  return {
+    write: (selection: PeriodSelection) => {
+      const written = replacePeriodInUrl(keys, selection);
+      if (written !== null) pending.push(written);
+    },
+    isEcho: (text: string) => {
+      const index = pending.indexOf(text);
+      if (index === -1) return false;
+      pending.splice(0, index + 1);
+      return true;
+    },
+  };
+}
+
+/**
+ * Keeps a selector's period in the page URL (`?<id>.period=`, see
+ * `periodQuery`) and its last choice in the user's preferences. The period
+ * starts from the URL, then from that last choice, then from `fallback`. Both
+ * are read in setup, on the server too: the preferences are a cookie, so the
+ * server renders the period the browser will show.
+ *
+ * The URL is written once mounted, so a copied URL always carries the
+ * period, then on every change: the history entry is replaced instead of
+ * pushed, so Back leaves the page rather than stepping through every pick,
+ * and the page is not requested again, only the bound cards and tables
+ * refetch. A route changed from outside (Back to the page with another
+ * period, a link) moves the period.
+ */
+export function usePeriodLocation(
+  period: UsePeriodReturn,
+  options: PeriodLocationOptions,
+): void {
+  const route = useDmsRoute();
+  const urlKeys = periodQueryKeys(options.id);
+  const remembered = useRememberedPeriod(options.pageId, options.id);
+  const writer = usePeriodUrlWriter(urlKeys);
+  const choices = {
+    presets: period.presets.value,
+    comparisons: period.comparisons.value,
+  };
+  const urlSource = (): PeriodSource => ({
+    query: route.query as PeriodQuery,
+    keys: urlKeys,
+  });
+
+  applySelection(
+    period,
+    resolvePeriodSelection(
+      [urlSource(), remembered.source()],
+      choices,
+      options.fallback,
+    ),
+  );
+  onMounted(() => writer.write(readSelection(period)));
+
+  watch(
+    () => selectionText(readSelection(period)),
+    () => {
+      const selection = readSelection(period);
+      remembered.remember(selection);
+      writer.write(selection);
+    },
+  );
+
+  // Only the route is followed here: the preferences move with the period.
+  watch(
+    () => urlKeysText(route.query as PeriodQuery, urlKeys),
+    (text) => {
+      if (writer.isEcho(text)) return;
+      const current = readSelection(period);
+      const next = resolvePeriodSelection([urlSource()], choices, current);
+      if (selectionText(next) === selectionText(current)) return;
+      applySelection(period, next);
+    },
+  );
+}

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

@@ -18,6 +18,11 @@ export interface TableListDataOptions<T extends Record<string, unknown>> {
   archiveQuery: ComputedRef<Query>;
   /** A self-managed display (the kanban) reads its own rows. */
   isSelfManaged: ComputedRef<boolean>;
+  /**
+   * Added to each request when it leaves, never watched: the live hold's
+   * bound must not list the rows again by changing (see useTableLiveHold).
+   */
+  heldQuery?: () => Query;
 }
 
 /** One counter: its id and its list query, as the table view builds it. */
@@ -32,8 +37,12 @@ export interface TableCountsDataOptions<T extends Record<string, unknown>> {
   rows: TableRows<T>;
   queries: ComputedRef<TableCountRequest[]>;
   archiveQuery: ComputedRef<Query>;
+  /** Added to each request when it leaves, never watched (see the list's). */
+  heldQuery?: () => Query;
 }
 
+const NO_HELD_QUERY = (): Query => ({});
+
 const EMPTY_LIST_RESULT: TableViewListResponse<never> = {
   results: [],
   total: 0,
@@ -51,6 +60,7 @@ export function useTableListData<T extends Record<string, unknown>>(
   options: TableListDataOptions<T>,
 ) {
   const { rows, query, archiveQuery, isSelfManaged } = options;
+  const heldQuery = options.heldQuery ?? NO_HELD_QUERY;
   const key = buildTableDataKey({
     componentId: options.componentId,
     pageId: options.pageId,
@@ -61,10 +71,11 @@ export function useTableListData<T extends Record<string, unknown>>(
   });
   return useServerRenderedAsyncData(
     key,
-    (): Promise<TableViewListResponse<T>> =>
+    // `null` while a source waits on its period scope: the table's skeleton.
+    (): Promise<TableViewListResponse<T> | null> =>
       isSelfManaged.value
         ? Promise.resolve(EMPTY_LIST_RESULT)
-        : rows.list({ ...query.value, ...archiveQuery.value }),
+        : rows.list({ ...query.value, ...archiveQuery.value, ...heldQuery() }),
     { watch: [query, archiveQuery, isSelfManaged, rows.sourceUrl] },
   );
 }
@@ -77,6 +88,7 @@ export function useTableCountsData<T extends Record<string, unknown>>(
   options: TableCountsDataOptions<T>,
 ) {
   const { rows, queries, archiveQuery } = options;
+  const heldQuery = options.heldQuery ?? NO_HELD_QUERY;
   const sourceSuffix = rows.sourceUrl.value ? `-${rows.sourceUrl.value}` : "";
   return useServerRenderedAsyncData<Record<string, number>>(
     `table-view-${options.componentId}-${options.pageId}-tab-counts${sourceSuffix}`,
@@ -85,7 +97,7 @@ export function useTableCountsData<T extends Record<string, unknown>>(
       return await rows.countBatch(
         queries.value.map(({ id, query }) => ({
           id,
-          query: { ...query, ...archiveQuery.value },
+          query: { ...query, ...archiveQuery.value, ...heldQuery() },
         })),
       );
     },

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

@@ -0,0 +1,77 @@
+import { computed, ref, watch, type ComputedRef } from "vue";
+import { usePageLive } from "../../../composables/live/usePageLive";
+import type { LiveGate } from "../live/currentPageLive";
+import { LIVE_HELD_AT_QUERY_KEY } from "./useTableRows";
+
+type Query = Record<string, unknown>;
+
+export interface TableLiveHoldOptions {
+  /** The table declares `liveHold`. */
+  isEnabled: boolean;
+  /** A `TableView.fromSource` table: its route receives the hold's bound. */
+  isSource: boolean;
+  /**
+   * The table's refresh gate (useRefreshTriggers), read when used: the table
+   * sets it up after the list this hold bounds.
+   */
+  gate: () => LiveGate;
+}
+
+export interface TableLiveHold {
+  /** The rows are held: the table declares `liveHold` and the page is paused. */
+  isHolding: ComputedRef<boolean>;
+  /** Events the table received since its rows were held or last shown. */
+  newCount: ComputedRef<number>;
+  /** Reads the rows once, staying paused, and holds them from now. */
+  showNew: () => void;
+  /** The bound a source route receives with each request while held. */
+  heldQuery: () => Query;
+}
+
+const NO_QUERY: Query = {};
+
+/**
+ * The `liveHold` of a table view: while its live page is paused, the table
+ * keeps its rows — the gate already requests nothing on its events — and a
+ * source route is told the moment they were frozen, so the user's own search,
+ * sort and pagination list the rows as they stood. Show reads them once more
+ * without leaving the pause.
+ *
+ * @internal
+ */
+export function useTableLiveHold(options: TableLiveHoldOptions): TableLiveHold {
+  const { isEnabled, isPaused } = usePageLive();
+  const pausedAt = ref<number | null>(null);
+  const isHolding = computed(
+    () => options.isEnabled && isEnabled.value && isPaused.value,
+  );
+
+  watch(
+    isHolding,
+    (holding) => {
+      pausedAt.value = holding ? Date.now() : null;
+    },
+    { immediate: true },
+  );
+
+  // The rows are as fresh as the pause, or as the last read the user asked
+  // for since (Show, an action of theirs).
+  const heldAt = () =>
+    pausedAt.value === null
+      ? null
+      : Math.max(pausedAt.value, options.gate().lastReadAt.value);
+
+  return {
+    isHolding,
+    newCount: computed(() =>
+      isHolding.value ? options.gate().missed.value : 0,
+    ),
+    showNew: () => options.gate().catchUp(),
+    heldQuery: () => {
+      const at = heldAt();
+      return options.isSource && at !== null
+        ? { [LIVE_HELD_AT_QUERY_KEY]: new Date(at).toISOString() }
+        : NO_QUERY;
+    },
+  };
+}