@antelopejs/dms 0.7.9 → 0.7.10

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

@@ -1,23 +1,46 @@
-import { readonly, ref, type Ref } from "vue";
-import type { PageLiveOptions } from "../../../types/live";
+import {
+  computed,
+  readonly,
+  ref,
+  shallowRef,
+  type ComputedRef,
+  type Ref,
+} from "vue";
+import type {
+  PageLiveNote,
+  PageLiveNoteInput,
+  PageLiveOptions,
+} from "../../../types/live";
+import { refreshLivePageBlocks } from "../../../utils/blockRefresh";
+import { liveIntervalMs } from "./liveCadence";
+import { LiveHolds, toLiveNote } from "./liveHolds";
+import { LivePoller } from "./livePoller";
+import { liveStorageKey, readStoredPause, storePause } from "./liveStorage";
+import { MissedTally } from "./missedTally";
 
-const MS_PER_SECOND = 1000;
-const STORAGE_KEY_PREFIX = "dms.live.paused:";
-const PAUSED_VALUE = "1";
+/**
+ * Why a page hidden in a background tab is paused.
+ *
+ * @internal
+ */
+export const HIDDEN_TAB_NOTE: PageLiveNote = {
+  text: "$dms.live.reason_hidden",
+};
 
 /**
  * One block or table of a live page: what it reads again, and what it missed
- * while the page was paused.
+ * while the page was paused or the block held.
  *
  * @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`.
+   * reaching several blocks counts once in the page's `missedCount`; its
+   * `payload.ids` or `payload.count` say how many rows it stands for.
    */
   trigger(event?: object): void;
-  /** Events the block received while paused and has not read yet. */
+  /** Rows and events the block received while paused or held, 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>>;
@@ -28,11 +51,29 @@ export interface LiveSubscription {
    * forgets what was missed, and a waiting trailing read is dropped.
    */
   acknowledge(): void;
+  /**
+   * Holds the block alone while the page stays live: its events are counted,
+   * not read. Released on a live page, it reads once if it missed any.
+   */
+  setHeld(isHeld: boolean): void;
   unsubscribe(): void;
 }
 
+/** How the page starts, beside what the browser remembers. @internal */
+export interface PageLiveStart {
+  /** The URL asked for the page paused (`?live=0`): not remembered. */
+  isPausedByUrl?: boolean;
+  /** Reads the page's blocks while the stream is down; `refreshLivePageBlocks`. */
+  poll?: () => void;
+  /**
+   * Starts live whatever the browser remembers, until `restoreChoice()`: the
+   * page renderer restores it once mounted, so hydration matches the server.
+   */
+  isRestoreDeferred?: boolean;
+}
+
 /**
- * The Direct / Pause state of one page and the gate every refetch of its
+ * The Live / Pause state of one page and the gate every refetch of its
  * blocks goes through (see `PageLiveOptions` in interface-dms).
  *
  * @internal
@@ -40,97 +81,110 @@ export interface LiveSubscription {
 export interface PageLiveController {
   readonly pageId: string;
   readonly isPaused: Readonly<Ref<boolean>>;
+  /** Why the page paused by itself; `null` when live or paused by the user. */
+  readonly pauseReason: ComputedRef<PageLiveNote | null>;
   /** When the page last read its data (ms since the epoch). */
   readonly lastUpdatedAt: Readonly<Ref<number>>;
-  /** Distinct events received since the pause. */
+  /** Rows and distinct events received since the pause. */
   readonly missedCount: Readonly<Ref<number>>;
+  /** What a module's component says the missed events hold. */
+  readonly missedDetail: Readonly<Ref<PageLiveNote | null>>;
+  /** The stream is down and the page reads its blocks on a clock. */
+  readonly isPolling: Readonly<Ref<boolean>>;
+  /**
+   * Applies the remembered choice and `?live=0`, once: what the controller
+   * does on creation unless `isRestoreDeferred`.
+   */
+  restoreChoice(): void;
   pause(): void;
+  /** Leaves the user's pause and lifts the holds of the moment. */
   resume(): void;
   toggle(): void;
+  hold(owner: symbol, reason: PageLiveNoteInput): void;
+  release(owner: symbol): void;
+  setMissedDetail(detail: PageLiveNoteInput | null): void;
+  setHidden(isHidden: boolean): void;
+  setStreamConnected(isConnected: boolean): void;
+  /** The span of a period the page shows, `null` once it is gone. */
+  reportPeriodSpan(owner: symbol, spanMs: number | null): void;
   subscribe(refresh: () => void): LiveSubscription;
   dispose(): void;
 }
 
 interface SubscriberState {
   refresh: () => void;
-  missed: Ref<number>;
+  tally: MissedTally;
   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.
-  }
+  /** The events the trailing call stands for, counted if the page pauses first. */
+  pendingEvents: Array<object | undefined>;
+  isHeld: boolean;
 }
 
 class PageLive implements PageLiveController {
   readonly isPaused: Readonly<Ref<boolean>>;
+  readonly pauseReason: ComputedRef<PageLiveNote | null>;
   readonly lastUpdatedAt: Readonly<Ref<number>>;
   readonly missedCount: Readonly<Ref<number>>;
-  private readonly paused: Ref<boolean>;
+  readonly missedDetail: Readonly<Ref<PageLiveNote | null>>;
+  readonly isPolling: Readonly<Ref<boolean>>;
+  private readonly paused = ref(false);
+  private readonly isUserPaused = ref(false);
+  private readonly isPausedByUrl: boolean;
+  private isRestored = false;
+  private readonly isHidden = ref(false);
+  private readonly holds = new LiveHolds();
+  private readonly detail = shallowRef<PageLiveNote | null>(null);
   private readonly updatedAt = ref(Date.now());
-  private readonly missedTotal = ref(0);
+  private readonly tally = new MissedTally();
   private readonly subscribers = new Set<SubscriberState>();
-  private countedEvents = new WeakSet<object>();
-  private readonly minIntervalMs: number;
+  private readonly periodSpans = new Map<symbol, number>();
+  private readonly poller: LivePoller;
+  private readonly storageKey: string;
+  private isStreamConnected = true;
 
   constructor(
     readonly pageId: string,
-    options: PageLiveOptions,
+    private readonly options: PageLiveOptions,
+    start: PageLiveStart = {},
   ) {
-    this.minIntervalMs = (options.maxRate ?? 0) * MS_PER_SECOND;
-    this.paused = ref(readStoredPause(pageId));
+    this.storageKey = liveStorageKey(pageId, options.rememberKey);
+    this.isPausedByUrl = !!start.isPausedByUrl;
+    this.poller = new LivePoller(
+      () => this.intervalMs(),
+      start.poll ?? refreshLivePageBlocks,
+    );
     this.isPaused = readonly(this.paused);
+    this.pauseReason = computed(() => this.reason());
     this.lastUpdatedAt = readonly(this.updatedAt);
-    this.missedCount = readonly(this.missedTotal);
+    this.missedCount = this.tally.total;
+    this.missedDetail = readonly(this.detail);
+    this.isPolling = this.poller.isPolling;
+    if (!start.isRestoreDeferred) this.restoreChoice();
+  }
+
+  restoreChoice(): void {
+    if (this.isRestored) return;
+    this.isRestored = true;
+    if (!this.isPausedByUrl && !readStoredPause(this.storageKey)) return;
+    this.isUserPaused.value = true;
+    this.sync();
   }
 
   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);
-    }
+    if (this.isUserPaused.value) return;
+    this.isUserPaused.value = true;
+    storePause(this.storageKey, true);
+    this.sync();
   }
 
   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);
+    if (this.isUserPaused.value) {
+      this.isUserPaused.value = false;
+      storePause(this.storageKey, false);
     }
+    this.holds.liftAll();
+    this.sync();
   }
 
   toggle(): void {
@@ -138,27 +192,55 @@ class PageLive implements PageLiveController {
     else this.pause();
   }
 
+  hold(owner: symbol, reason: PageLiveNoteInput): void {
+    this.holds.set(owner, reason);
+    this.sync();
+  }
+
+  release(owner: symbol): void {
+    this.holds.release(owner);
+    this.sync();
+  }
+
+  setMissedDetail(detail: PageLiveNoteInput | null): void {
+    this.detail.value = detail === null ? null : toLiveNote(detail);
+  }
+
+  setHidden(isHidden: boolean): void {
+    this.isHidden.value = isHidden;
+    this.sync();
+  }
+
+  setStreamConnected(isConnected: boolean): void {
+    this.isStreamConnected = isConnected;
+    this.updatePolling();
+  }
+
+  reportPeriodSpan(owner: symbol, spanMs: number | null): void {
+    if (spanMs === null) this.periodSpans.delete(owner);
+    else this.periodSpans.set(owner, spanMs);
+  }
+
   subscribe(refresh: () => void): LiveSubscription {
     const state: SubscriberState = {
       refresh,
-      missed: ref(0),
+      tally: new MissedTally(),
       lastRunAt: ref(0),
       timer: null,
-      pendingEvent: undefined,
+      pendingEvents: [],
+      isHeld: false,
     };
     this.subscribers.add(state);
     return {
       trigger: (event) => this.trigger(state, event),
-      missed: readonly(state.missed),
+      missed: state.tally.total,
       lastReadAt: readonly(state.lastRunAt),
-      catchUp: () => {
-        state.missed.value = 0;
-        this.run(state);
-      },
+      catchUp: () => this.catchUp(state),
       acknowledge: () => {
-        state.missed.value = 0;
+        state.tally.reset();
         this.markRead(state);
       },
+      setHeld: (isHeld) => this.setHeld(state, isHeld),
       unsubscribe: () => {
         clearTimer(state);
         this.subscribers.delete(state);
@@ -169,27 +251,100 @@ class PageLive implements PageLiveController {
   dispose(): void {
     for (const state of this.subscribers) clearTimer(state);
     this.subscribers.clear();
+    this.poller.stop();
+  }
+
+  // A hidden tab outranks everything: nobody sees the page. The user's pause
+  // comes next, and says nothing more; a hold names its reason.
+  private reason(): PageLiveNote | null {
+    if (this.isHidden.value) return HIDDEN_TAB_NOTE;
+    if (this.isUserPaused.value) return null;
+    return this.holds.activeNote.value;
+  }
+
+  private sync(): void {
+    const shouldPause =
+      this.isUserPaused.value || this.isHidden.value || this.holds.isActive;
+    if (shouldPause !== this.paused.value) {
+      if (shouldPause) this.enterPause();
+      else this.leavePause();
+    }
+    this.updatePolling();
+  }
+
+  private enterPause(): void {
+    this.paused.value = true;
+    // A trailing read still waiting stands for events not shown yet.
+    for (const state of this.subscribers) this.flushPending(state, true);
+  }
+
+  private leavePause(): void {
+    this.paused.value = false;
+    this.tally.reset();
+    this.detail.value = null;
+    this.updatedAt.value = Date.now();
+    for (const state of this.subscribers) {
+      if (state.isHeld || state.tally.total.value === 0) continue;
+      this.catchUp(state);
+    }
+  }
+
+  private updatePolling(): void {
+    this.poller.update(!this.isStreamConnected && !this.paused.value);
+  }
+
+  private intervalMs(): number {
+    const spans = [...this.periodSpans.values()];
+    return liveIntervalMs(
+      this.options,
+      spans.length > 0 ? Math.max(...spans) : null,
+    );
+  }
+
+  private setHeld(state: SubscriberState, isHeld: boolean): void {
+    if (state.isHeld === isHeld) return;
+    state.isHeld = isHeld;
+    if (isHeld) this.flushPending(state, false);
+    else if (!this.paused.value && state.tally.total.value > 0) {
+      this.catchUp(state);
+    }
   }
 
   private trigger(state: SubscriberState, event: object | undefined): void {
-    if (this.paused.value) this.countMissed(state, event);
+    if (this.paused.value) this.countMissed(state, event, true);
+    else if (state.isHeld) this.countMissed(state, event, false);
     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.
+  // ones within the interval 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 (state.timer) {
+      state.pendingEvents.push(event);
+      return;
+    }
+    const wait = state.lastRunAt.value + this.intervalMs() - Date.now();
     if (wait <= 0) {
       this.run(state);
       return;
     }
-    state.pendingEvent = event;
+    state.pendingEvents = [event];
     state.timer = setTimeout(() => this.run(state), wait);
   }
 
+  private flushPending(state: SubscriberState, isPageMissed: boolean): void {
+    if (!state.timer) return;
+    const events = state.pendingEvents;
+    clearTimer(state);
+    for (const event of events) this.countMissed(state, event, isPageMissed);
+  }
+
+  private catchUp(state: SubscriberState): void {
+    state.tally.reset();
+    this.run(state);
+  }
+
   private run(state: SubscriberState): void {
     this.markRead(state);
     state.refresh();
@@ -201,29 +356,33 @@ class PageLive implements PageLiveController {
     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;
+  private countMissed(
+    state: SubscriberState,
+    event: object | undefined,
+    isPageMissed: boolean,
+  ): void {
+    state.tally.add(event);
+    if (isPageMissed) this.tally.add(event);
   }
 }
 
 function clearTimer(state: SubscriberState): void {
   if (state.timer) clearTimeout(state.timer);
   state.timer = null;
-  state.pendingEvent = undefined;
+  state.pendingEvents = [];
 }
 
 /**
- * The controller of a page declared with `live`. Starts in the state the
- * browser remembers for `pageId`, Direct otherwise.
+ * The controller of a page declared with `live`. Starts paused when the URL
+ * asks for it or the browser remembers the page (or its `rememberKey`) paused,
+ * live otherwise.
  *
  * @internal
  */
 export function createPageLiveController(
   pageId: string,
   options: PageLiveOptions,
+  start?: PageLiveStart,
 ): PageLiveController {
-  return new PageLive(pageId, options);
+  return new PageLive(pageId, options, start);
 }

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

@@ -0,0 +1,33 @@
+import { onScopeDispose, watch } from "vue";
+import { currentPageLive } from "./currentPageLive";
+
+/** The range a period selector shows. */
+interface ShownRange {
+  from: Date;
+  to: Date;
+}
+
+/**
+ * Tells the live page on screen how long a period the selector shows, so a
+ * page declaring `live.slowRateAfter` slows down over a long one. Follows
+ * the page's controller as it is installed or replaced, and withdraws the
+ * span when the selector goes. A range without bounds (all time) spans more
+ * than any period.
+ *
+ * @internal
+ */
+export function useLivePeriodSpan(range: () => ShownRange | null): void {
+  if (typeof window === "undefined") return;
+  const owner = Symbol("live-period");
+  const spanOf = (shown: ShownRange | null) =>
+    shown ? shown.to.getTime() - shown.from.getTime() : Number.POSITIVE_INFINITY;
+  const stop = watch(
+    [currentPageLive, () => spanOf(range())],
+    ([controller, span], _previous, onCleanup) => {
+      controller?.reportPeriodSpan(owner, span);
+      onCleanup(() => controller?.reportPeriodSpan(owner, null));
+    },
+    { immediate: true },
+  );
+  onScopeDispose(stop);
+}

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

@@ -1,4 +1,4 @@
-import { onScopeDispose, watch } from "vue";
+import { onMounted, onScopeDispose, watch } from "vue";
 import type { PageLiveOptions } from "../../../types/live";
 import { setCurrentPageLive } from "./currentPageLive";
 import {
@@ -6,25 +6,93 @@ import {
   type PageLiveController,
 } from "./pageLiveController";
 
+/** The URL query key opening a live page paused: `?live=0`. */
+const LIVE_URL_KEY = "live";
+const LIVE_URL_PAUSED = "0";
+
 /** The page the renderer shows: its id and its `live` option. */
 export interface PageLiveSource {
   pageId: string | undefined;
   live: PageLiveOptions | undefined;
 }
 
+/** What the page's controller follows around it. @internal */
+export interface PageLiveEnvironment {
+  /** The realtime stream is open; while it is not, the page polls. */
+  isStreamConnected?: () => boolean;
+}
+
+/** The URL asks for the page paused (`?live=0`). @internal */
+export function isPausedByUrl(): boolean {
+  return (
+    new URLSearchParams(window.location.search).get(LIVE_URL_KEY) ===
+    LIVE_URL_PAUSED
+  );
+}
+
+// Resumed, the page no longer opens paused: a reload keeps it live.
+function dropUrlPause(): void {
+  if (!isPausedByUrl()) return;
+  const url = new URL(window.location.href);
+  url.searchParams.delete(LIVE_URL_KEY);
+  window.history.replaceState(window.history.state, "", url.href);
+}
+
+/**
+ * Binds a controller to the browser around it: a hidden tab pauses it, the
+ * stream state switches its polling, and resuming drops `?live=0` from the
+ * URL. Returns the unbinding.
+ *
+ * @internal
+ */
+export function bindPageLiveEnvironment(
+  controller: PageLiveController,
+  environment: PageLiveEnvironment,
+): () => void {
+  const onVisibility = () =>
+    controller.setHidden(document.visibilityState === "hidden");
+  onVisibility();
+  document.addEventListener("visibilitychange", onVisibility);
+  const stops = [
+    () => document.removeEventListener("visibilitychange", onVisibility),
+    watch(
+      () => environment.isStreamConnected?.() ?? true,
+      (isConnected) => controller.setStreamConnected(isConnected),
+      { immediate: true },
+    ),
+    watch(controller.isPaused, (isPaused) => {
+      if (!isPaused) dropUrlPause();
+    }),
+  ];
+  return () => stops.forEach((stop) => stop());
+}
+
 /**
  * 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 {
+export function usePageLiveHost(
+  source: () => PageLiveSource,
+  environment: PageLiveEnvironment = {},
+): void {
   if (typeof window === "undefined") return;
   let controller: PageLiveController | null = null;
+  let unbind: (() => void) | null = null;
+  // The server renders every page live: the remembered pause applies once
+  // mounted, so the hydrating render draws the same rows.
+  let isMounted = false;
+  onMounted(() => {
+    isMounted = true;
+    controller?.restoreChoice();
+  });
 
   const install = (next: PageLiveController | null) => {
+    unbind?.();
     controller?.dispose();
     controller = next;
+    unbind = next ? bindPageLiveEnvironment(next, environment) : null;
     setCurrentPageLive(next);
   };
 
@@ -35,9 +103,15 @@ export function usePageLiveHost(source: () => PageLiveSource): void {
     },
     (key) => {
       const { pageId, live } = source();
-      install(
-        key && pageId && live ? createPageLiveController(pageId, live) : null,
-      );
+      const next =
+        key && pageId && live
+          ? createPageLiveController(pageId, live, {
+              isPausedByUrl: isPausedByUrl(),
+              isRestoreDeferred: true,
+            })
+          : null;
+      install(next);
+      if (isMounted) next?.restoreChoice();
     },
     { immediate: true },
   );

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

@@ -0,0 +1,70 @@
+import {
+  DEFAULT_COMPARISONS,
+  type PeriodComparison,
+} from "#dms-core/app/composables/period/types";
+
+/** How a selector offers its comparisons. */
+export type ComparisonControl = "menu" | "toggle" | "hidden";
+
+/** What the selector was given about its comparisons. */
+export interface ComparisonControlOptions {
+  comparisons?: PeriodComparison[];
+  defaultComparison?: PeriodComparison;
+  comparisonControl?: ComparisonControl;
+}
+
+/** The comparison control a selector draws, and what its period offers. */
+export interface ResolvedComparisonControl {
+  control: ComparisonControl;
+  /** The comparisons the period accepts: `none` too behind a toggle. */
+  comparisons: PeriodComparison[];
+  defaultComparison: PeriodComparison | undefined;
+  /** The comparison a toggle switches on, else `null`. */
+  toggled: PeriodComparison | null;
+}
+
+const NO_COMPARISON: PeriodComparison = "none";
+
+function defaultControl(activeCount: number): ComparisonControl {
+  return activeCount === 1 ? "toggle" : "menu";
+}
+
+function preferredComparison(
+  active: PeriodComparison[],
+  defaultComparison: PeriodComparison | undefined,
+): PeriodComparison | null {
+  const isActiveDefault =
+    defaultComparison !== undefined && active.includes(defaultComparison);
+  return isActiveDefault ? defaultComparison : (active[0] ?? null);
+}
+
+/**
+ * The comparison control of a selector: a `menu` of its comparisons, an
+ * inline `toggle` switching one comparison on and off (the default when it
+ * offers a single one besides `none`), or `hidden`, the comparison kept on.
+ * A selector offering no comparison besides `none` draws nothing.
+ */
+export function resolveComparisonControl(
+  options: ComparisonControlOptions,
+): ResolvedComparisonControl {
+  const offered = options.comparisons ?? DEFAULT_COMPARISONS;
+  const active = offered.filter((entry) => entry !== NO_COMPARISON);
+  const preferred = preferredComparison(active, options.defaultComparison);
+  const control: ComparisonControl = preferred
+    ? (options.comparisonControl ?? defaultControl(active.length))
+    : "hidden";
+  const isToggle = control === "toggle";
+  const isHidden = control === "hidden";
+  return {
+    control,
+    comparisons:
+      isToggle && !offered.includes(NO_COMPARISON)
+        ? [NO_COMPARISON, ...offered]
+        : [...offered],
+    defaultComparison:
+      isHidden && preferred
+        ? (options.defaultComparison ?? preferred)
+        : options.defaultComparison,
+    toggled: isToggle ? preferred : null,
+  };
+}