@antelopejs/dms 0.7.7 → 0.7.9

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

@@ -0,0 +1,229 @@
+import { readonly, ref, type Ref } from "vue";
+import type { PageLiveOptions } from "../../../types/live";
+
+const MS_PER_SECOND = 1000;
+const STORAGE_KEY_PREFIX = "dms.live.paused:";
+const PAUSED_VALUE = "1";
+
+/**
+ * One block or table of a live page: what it reads again, and what it missed
+ * while the page was paused.
+ *
+ * @internal
+ */
+export interface LiveSubscription {
+  /**
+   * An event behind the block arrived. `event` identifies it, so one event
+   * reaching several blocks counts once in the page's `missedCount`.
+   */
+  trigger(event?: object): void;
+  /** Events the block received while paused and has not read yet. */
+  readonly missed: Readonly<Ref<number>>;
+  /** When the block last read through the gate (ms since the epoch), 0 before. */
+  readonly lastReadAt: Readonly<Ref<number>>;
+  /** Reads now, whatever the state, and forgets what was missed. */
+  catchUp(): void;
+  /**
+   * Records a read the block made by itself (one the user asked for): it
+   * forgets what was missed, and a waiting trailing read is dropped.
+   */
+  acknowledge(): void;
+  unsubscribe(): void;
+}
+
+/**
+ * The Direct / Pause state of one page and the gate every refetch of its
+ * blocks goes through (see `PageLiveOptions` in interface-dms).
+ *
+ * @internal
+ */
+export interface PageLiveController {
+  readonly pageId: string;
+  readonly isPaused: Readonly<Ref<boolean>>;
+  /** When the page last read its data (ms since the epoch). */
+  readonly lastUpdatedAt: Readonly<Ref<number>>;
+  /** Distinct events received since the pause. */
+  readonly missedCount: Readonly<Ref<number>>;
+  pause(): void;
+  resume(): void;
+  toggle(): void;
+  subscribe(refresh: () => void): LiveSubscription;
+  dispose(): void;
+}
+
+interface SubscriberState {
+  refresh: () => void;
+  missed: Ref<number>;
+  lastRunAt: Ref<number>;
+  timer: ReturnType<typeof setTimeout> | null;
+  /** The event the trailing call stands for, counted if the page pauses first. */
+  pendingEvent: object | undefined;
+}
+
+/** Browser storage of the paused pages; absent on the server or when denied. */
+function liveStorage(): Storage | undefined {
+  try {
+    return typeof window === "undefined" ? undefined : window.localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+function readStoredPause(pageId: string): boolean {
+  return liveStorage()?.getItem(STORAGE_KEY_PREFIX + pageId) === PAUSED_VALUE;
+}
+
+function storePause(pageId: string, isPaused: boolean): void {
+  const storage = liveStorage();
+  if (!storage) return;
+  try {
+    if (isPaused) storage.setItem(STORAGE_KEY_PREFIX + pageId, PAUSED_VALUE);
+    else storage.removeItem(STORAGE_KEY_PREFIX + pageId);
+  } catch {
+    // A full or locked storage only loses the memory of the choice.
+  }
+}
+
+class PageLive implements PageLiveController {
+  readonly isPaused: Readonly<Ref<boolean>>;
+  readonly lastUpdatedAt: Readonly<Ref<number>>;
+  readonly missedCount: Readonly<Ref<number>>;
+  private readonly paused: Ref<boolean>;
+  private readonly updatedAt = ref(Date.now());
+  private readonly missedTotal = ref(0);
+  private readonly subscribers = new Set<SubscriberState>();
+  private countedEvents = new WeakSet<object>();
+  private readonly minIntervalMs: number;
+
+  constructor(
+    readonly pageId: string,
+    options: PageLiveOptions,
+  ) {
+    this.minIntervalMs = (options.maxRate ?? 0) * MS_PER_SECOND;
+    this.paused = ref(readStoredPause(pageId));
+    this.isPaused = readonly(this.paused);
+    this.lastUpdatedAt = readonly(this.updatedAt);
+    this.missedCount = readonly(this.missedTotal);
+  }
+
+  pause(): void {
+    if (this.paused.value) return;
+    this.paused.value = true;
+    storePause(this.pageId, true);
+    // A trailing read still waiting stands for an event not shown yet.
+    for (const state of this.subscribers) {
+      if (!state.timer) continue;
+      const event = state.pendingEvent;
+      clearTimer(state);
+      this.countMissed(state, event);
+    }
+  }
+
+  resume(): void {
+    if (!this.paused.value) return;
+    this.paused.value = false;
+    storePause(this.pageId, false);
+    this.missedTotal.value = 0;
+    this.countedEvents = new WeakSet();
+    this.updatedAt.value = Date.now();
+    for (const state of this.subscribers) {
+      if (state.missed.value === 0) continue;
+      state.missed.value = 0;
+      this.run(state);
+    }
+  }
+
+  toggle(): void {
+    if (this.paused.value) this.resume();
+    else this.pause();
+  }
+
+  subscribe(refresh: () => void): LiveSubscription {
+    const state: SubscriberState = {
+      refresh,
+      missed: ref(0),
+      lastRunAt: ref(0),
+      timer: null,
+      pendingEvent: undefined,
+    };
+    this.subscribers.add(state);
+    return {
+      trigger: (event) => this.trigger(state, event),
+      missed: readonly(state.missed),
+      lastReadAt: readonly(state.lastRunAt),
+      catchUp: () => {
+        state.missed.value = 0;
+        this.run(state);
+      },
+      acknowledge: () => {
+        state.missed.value = 0;
+        this.markRead(state);
+      },
+      unsubscribe: () => {
+        clearTimer(state);
+        this.subscribers.delete(state);
+      },
+    };
+  }
+
+  dispose(): void {
+    for (const state of this.subscribers) clearTimer(state);
+    this.subscribers.clear();
+  }
+
+  private trigger(state: SubscriberState, event: object | undefined): void {
+    if (this.paused.value) this.countMissed(state, event);
+    else this.triggerDirect(state, event);
+  }
+
+  // Leading and trailing: the first event of a quiet block reads at once, the
+  // ones within `maxRate` of a read collapse into one read when it ends, so
+  // the last event of a burst is never lost.
+  private triggerDirect(state: SubscriberState, event: object | undefined) {
+    if (state.timer) return;
+    const wait = state.lastRunAt.value + this.minIntervalMs - Date.now();
+    if (wait <= 0) {
+      this.run(state);
+      return;
+    }
+    state.pendingEvent = event;
+    state.timer = setTimeout(() => this.run(state), wait);
+  }
+
+  private run(state: SubscriberState): void {
+    this.markRead(state);
+    state.refresh();
+  }
+
+  private markRead(state: SubscriberState): void {
+    clearTimer(state);
+    state.lastRunAt.value = Date.now();
+    this.updatedAt.value = state.lastRunAt.value;
+  }
+
+  private countMissed(state: SubscriberState, event: object | undefined) {
+    state.missed.value += 1;
+    if (event && this.countedEvents.has(event)) return;
+    if (event) this.countedEvents.add(event);
+    this.missedTotal.value += 1;
+  }
+}
+
+function clearTimer(state: SubscriberState): void {
+  if (state.timer) clearTimeout(state.timer);
+  state.timer = null;
+  state.pendingEvent = undefined;
+}
+
+/**
+ * The controller of a page declared with `live`. Starts in the state the
+ * browser remembers for `pageId`, Direct otherwise.
+ *
+ * @internal
+ */
+export function createPageLiveController(
+  pageId: string,
+  options: PageLiveOptions,
+): PageLiveController {
+  return new PageLive(pageId, options);
+}

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

@@ -0,0 +1,8 @@
+/** Switches the page between Direct and Pause, while a LiveToggle is on it. */
+export const LIVE_TOGGLE_L_METADATA: ShortcutMetadata = {
+  key: ["l"],
+  descriptionKey: "$dms.shortcuts.livetoggle.l.description",
+  component: "$dms.components.livetoggle",
+};
+
+export const LIVE_TOGGLE_SHORTCUTS_METADATA = [LIVE_TOGGLE_L_METADATA];

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

@@ -0,0 +1,25 @@
+import { onBeforeUnmount, onMounted } from "vue";
+
+// The toggles mounted on the page, in mount order: the first one owns the L
+// key, so a page showing two toggles still switches once per press.
+const claims: symbol[] = [];
+
+/**
+ * Binds L to `toggle` for the first LiveToggle mounted on the page; the next
+ * one takes over when it goes.
+ *
+ * @internal
+ */
+export function useLiveToggleShortcut(toggle: () => void): void {
+  const claim = Symbol("live-toggle");
+  onMounted(() => claims.push(claim));
+  onBeforeUnmount(() => {
+    const index = claims.indexOf(claim);
+    if (index >= 0) claims.splice(index, 1);
+  });
+  defineShortcuts({
+    l: () => {
+      if (claims[0] === claim) toggle();
+    },
+  });
+}

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

@@ -0,0 +1,46 @@
+import { onScopeDispose, watch } from "vue";
+import type { PageLiveOptions } from "../../../types/live";
+import { setCurrentPageLive } from "./currentPageLive";
+import {
+  createPageLiveController,
+  type PageLiveController,
+} from "./pageLiveController";
+
+/** The page the renderer shows: its id and its `live` option. */
+export interface PageLiveSource {
+  pageId: string | undefined;
+  live: PageLiveOptions | undefined;
+}
+
+/**
+ * Gives the page on screen its live controller while it declares `live`, and
+ * a new one when the renderer moves to another page. Browser only.
+ *
+ * @internal
+ */
+export function usePageLiveHost(source: () => PageLiveSource): void {
+  if (typeof window === "undefined") return;
+  let controller: PageLiveController | null = null;
+
+  const install = (next: PageLiveController | null) => {
+    controller?.dispose();
+    controller = next;
+    setCurrentPageLive(next);
+  };
+
+  watch(
+    () => {
+      const { pageId, live } = source();
+      return pageId && live ? JSON.stringify([pageId, live]) : "";
+    },
+    (key) => {
+      const { pageId, live } = source();
+      install(
+        key && pageId && live ? createPageLiveController(pageId, live) : null,
+      );
+    },
+    { immediate: true },
+  );
+
+  onScopeDispose(() => install(null));
+}

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));
+}