@antelopejs/dms 0.7.8 → 0.7.10

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

@@ -0,0 +1,115 @@
+import { computed, type ComputedRef } from "vue";
+import { useChartFetch } from "../../../composables/chart/useChartFetch";
+import {
+  type FetchNotFound,
+  readFetchNotFound,
+} from "../../utils/fetchNotFound";
+import type { BlockAction } from "../../components/blocks/BlockActions.vue";
+import type {
+  EmptyStateSize,
+  EmptyStateVariant,
+} from "../../../components/empty-state/EmptyState.vue";
+import type { Tone } from "../../../types/tone";
+
+/** The empty state a guard shows in place of its children (interface-dms `GuardFallback`). */
+export interface GuardFallback {
+  title?: string;
+  description?: string;
+  variant?: EmptyStateVariant;
+  icon?: string;
+  tone?: Tone;
+  hatched?: boolean;
+  size?: EmptyStateSize;
+  actions?: BlockAction[];
+  code?: { content: string; language?: string; copy?: boolean };
+  card?: boolean;
+}
+
+/** What a guard checks its route for (interface-dms `GuardCondition`). */
+export type GuardCondition = "empty" | "notFound";
+
+/** The route a guard reads and what it checks it for (interface-dms `GuardOptions`). */
+export interface GuardSource {
+  fetchUrl?: string;
+  fetchUrlMethod?: string;
+  periodScope?: string;
+  realtimeTopic?: string | string[];
+  when?: GuardCondition;
+  /** Dot path of the value `empty` checks; the whole answer without it. */
+  field?: string;
+}
+
+/** What the route answers: any value, maybe with an `emptyState` laid over the fallback. */
+export interface GuardResponse {
+  emptyState?: GuardFallback;
+  [field: string]: unknown;
+}
+
+/** Which condition held: the fallback to show, before its defaults. */
+export interface GuardState {
+  condition: GuardCondition;
+  /** The answer's `emptyState`, when the route sent one. */
+  override?: GuardFallback;
+  /** What the 404 said, for `notFound`: its message sets the default texts. */
+  notFound?: FetchNotFound;
+}
+
+const FIELD_PATH_SEPARATOR = ".";
+
+/** The value at a dot path of an answer, `undefined` where the path stops. */
+export function readFieldPath(source: unknown, path: string): unknown {
+  return path.split(FIELD_PATH_SEPARATOR).reduce<unknown>((value, key) => {
+    if (value === null || typeof value !== "object") return undefined;
+    return (value as Record<string, unknown>)[key];
+  }, source);
+}
+
+/** Absent, `null`, `false`, `0`, `""` or an empty list: nothing to show. */
+export function isEmptyValue(value: unknown): boolean {
+  if (Array.isArray(value)) return value.length === 0;
+  return !value;
+}
+
+function answerOverride(answer: unknown): GuardFallback | undefined {
+  if (!answer || typeof answer !== "object" || Array.isArray(answer)) {
+    return undefined;
+  }
+  const { emptyState } = answer as GuardResponse;
+  return emptyState && typeof emptyState === "object" ? emptyState : undefined;
+}
+
+/**
+ * The condition that holds, or `null` while the children show: while the
+ * route loads, after any failure other than the condition, and whenever the
+ * value is set. The route is read like a block's `fetchUrl` (URL tokens,
+ * period scope, realtime topics, page refresh); nothing is requested while
+ * a token has no value.
+ */
+export function useGuard(
+  options: () => GuardSource,
+  routeParams: () => Record<string, string> | undefined,
+): ComputedRef<GuardState | null> {
+  const initial = options();
+  const { data, error } = useChartFetch<unknown>({
+    fetchUrl: initial.fetchUrl,
+    fetchUrlMethod: initial.fetchUrlMethod,
+    periodScope: initial.periodScope,
+    realtimeTopic: initial.realtimeTopic,
+    routeParams,
+  });
+
+  return computed(() => {
+    const { when = "empty", field } = options();
+    const failure = error.value;
+    if (when === "notFound") {
+      const notFound = readFetchNotFound(failure);
+      if (!notFound) return null;
+      return { condition: when, override: notFound.emptyState, notFound };
+    }
+    const answer = data.value;
+    if (failure || answer === null || answer === undefined) return null;
+    const value = field ? readFieldPath(answer, field) : answer;
+    if (!isEmptyValue(value)) return null;
+    return { condition: when, override: answerOverride(answer) };
+  });
+}

package/frontend-vue/layers/dms-ui/app/build/composables/confirm/actionError.ts

@@ -68,7 +68,7 @@ const isTechnical = (text: string) =>
  * as it came. Undefined when it is not user-facing (an untranslated key, JSON,
  * a stack trace…), for the caller to fall back on a generic message.
  */
-const userFacingText = (
+export const userFacingText = (
   text: string | undefined,
   translate: I18nTranslate,
 ): string | undefined => {

package/frontend-vue/layers/dms-ui/app/build/composables/confirm/confirmDialogTexts.ts

@@ -1,6 +1,14 @@
-import type { ConfirmDialog } from "#dms-core/app/types/confirm-dialog";
+import type {
+  ConfirmDialog,
+  ConfirmDialogSecondaryAction,
+  ConfirmDialogSecondaryTarget,
+} from "#dms-core/app/types/confirm-dialog";
+import { interpolateUrl } from "#dms-core/app/utils/url-interpolation";
 import { readTranslationKey } from "#dms-core/app/composables/translation/useTranslation";
-import type { ConfirmOptions } from "../../../composables/confirm/types";
+import type {
+  ConfirmOptions,
+  ConfirmSecondaryAction,
+} from "../../../composables/confirm/types";
 import { processFieldI18n } from "../../utils/fieldOptionsI18n";
 import { interpolateLiteral } from "../../utils/literalText";
 
@@ -28,21 +36,68 @@ export function resolveConfirmText(
     : t(key, params);
 }
 
+/** Runs a dialog's secondary target, its URL already filled in. */
+export type SecondaryTargetRun = (
+  target: ConfirmDialogSecondaryTarget,
+) => Promise<void> | void;
+
+/**
+ * A dialog's secondary target with its URL (and file name) filled in with
+ * the same parameters as its texts.
+ */
+function resolveSecondaryTarget(
+  target: ConfirmDialogSecondaryTarget,
+  params: Record<string, unknown>,
+): ConfirmDialogSecondaryTarget {
+  const url = interpolateUrl(target.url, params);
+  if (target.type !== "download" || target.filename === undefined) {
+    return { ...target, url };
+  }
+  return {
+    ...target,
+    url,
+    filename: interpolateLiteral(target.filename, params),
+  };
+}
+
+function resolveSecondaryAction(
+  action: ConfirmDialogSecondaryAction | undefined,
+  params: Record<string, unknown>,
+  t: ConfirmTranslate,
+  runTarget: SecondaryTargetRun | undefined,
+): ConfirmSecondaryAction | undefined {
+  if (!action || !runTarget) return undefined;
+  const target = resolveSecondaryTarget(action.target, params);
+  return {
+    label: resolveConfirmText(action.label, params, t),
+    icon: action.icon,
+    run: () => runTarget(target),
+  };
+}
+
 /**
  * A confirmation dialog with its texts resolved, ready for `useConfirm()`:
  * interpolated with the row's fields (`row`) and the dialog's own `params`.
+ * Its secondary action is drawn only when given `runTarget` to run it with.
  */
 export function resolveConfirmDialog(
   dialog: ConfirmDialog,
   row: Record<string, unknown> | undefined,
   t: ConfirmTranslate,
+  runTarget?: SecondaryTargetRun,
 ): ConfirmOptions {
   const params = { ...row, ...dialog.params };
   const text = (value: string | undefined) =>
     value === undefined ? undefined : resolveConfirmText(value, params, t);
-  const { params: _params, ...rest } = dialog;
+  const { params: _params, secondaryAction, ...rest } = dialog;
   return {
     ...rest,
+    secondaryAction: resolveSecondaryAction(
+      secondaryAction,
+      params,
+      t,
+      runTarget,
+    ),
     title: text(dialog.title) ?? "",
     description: text(dialog.description),
     confirmLabel: text(dialog.confirmLabel),

package/frontend-vue/layers/dms-ui/app/build/composables/confirm/secondaryTarget.ts

@@ -0,0 +1,86 @@
+import type {
+  ConfirmDialogDownloadTarget,
+  ConfirmDialogLinkTarget,
+  ConfirmDialogSecondaryTarget,
+} from "#dms-core/app/types/confirm-dialog";
+import { downloadFile } from "#dms-core/app/utils/downloadFile";
+import type { SecondaryTargetRun } from "./confirmDialogTexts";
+
+/** The response a download reads: its body and its headers. */
+export interface DownloadResponse {
+  _data?: Blob;
+  headers: Headers;
+}
+
+/** Fetches a download with the user's session (`$authFetch.raw`). */
+export type DownloadFetch = (
+  url: string,
+  options: { responseType: "blob" },
+) => Promise<DownloadResponse>;
+
+const DISPOSITION_NAME = /filename\*?=(?:UTF-8'')?"?([^";]+)"?/i;
+const FALLBACK_FILENAME = "download";
+
+// A malformed escape is kept as written rather than failing the download.
+function decodeName(name: string): string {
+  try {
+    return decodeURIComponent(name);
+  } catch {
+    return name;
+  }
+}
+
+/**
+ * The name a download is saved under: the declared one, else the server's
+ * `Content-Disposition` one, else the URL's last path segment.
+ */
+export function downloadFilename(
+  target: ConfirmDialogDownloadTarget,
+  disposition: string | null,
+): string {
+  if (target.filename) return target.filename;
+  const served = disposition ? DISPOSITION_NAME.exec(disposition)?.[1] : "";
+  if (served) return decodeName(served.trim());
+  const path = target.url.split(/[?#]/)[0] ?? "";
+  return decodeName(path.split("/").pop() || FALLBACK_FILENAME);
+}
+
+function openLink(target: ConfirmDialogLinkTarget): void {
+  if (typeof window === "undefined" || !target.url) return;
+  if (target.newTab) {
+    window.open(target.url, "_blank", "noopener,noreferrer");
+    return;
+  }
+  window.location.href = target.url;
+}
+
+async function saveDownload(
+  target: ConfirmDialogDownloadTarget,
+  fetchRaw: DownloadFetch,
+): Promise<void> {
+  if (!target.url) return;
+  const response = await fetchRaw(target.url, { responseType: "blob" });
+  const blob = response._data ?? new Blob([]);
+  const objectUrl = URL.createObjectURL(blob);
+  try {
+    downloadFile(
+      objectUrl,
+      downloadFilename(target, response.headers.get("content-disposition")),
+    );
+  } finally {
+    URL.revokeObjectURL(objectUrl);
+  }
+}
+
+/**
+ * Runs the target of a confirmation's secondary action, the dialog left
+ * open: a link opens, a download is fetched with `fetchRaw` and saved.
+ */
+export function secondaryTargetRunner(
+  fetchRaw: DownloadFetch,
+): SecondaryTargetRun {
+  return (target: ConfirmDialogSecondaryTarget) =>
+    target.type === "download"
+      ? saveDownload(target, fetchRaw)
+      : openLink(target);
+}

package/frontend-vue/layers/dms-ui/app/build/composables/confirm/useActionConfirm.ts

@@ -13,6 +13,7 @@ import {
   type ConfirmTranslate,
   resolveConfirmDialog,
 } from "./confirmDialogTexts";
+import { type DownloadFetch, secondaryTargetRunner } from "./secondaryTarget";
 
 /** What an action asks its confirmation with. */
 export interface ActionConfirmRequest {
@@ -44,6 +45,9 @@ export function useActionConfirm() {
   const { $authFetch } = useAuthFetch();
   const { t } = useI18n();
   const toast = useToast();
+  const runSecondaryTarget = secondaryTargetRunner(
+    $authFetch.raw as unknown as DownloadFetch,
+  );
 
   const loadDialog = async (
     declared: ActionConfirm,
@@ -81,6 +85,7 @@ export function useActionConfirm() {
       dialog,
       request.row,
       t as ConfirmTranslate,
+      runSecondaryTarget,
     );
     const isConfirmed = await confirm({
       ...request.fallback,

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

@@ -48,6 +48,11 @@ export interface LiveGate {
   catchUp(): void;
   /** Records a read the caller makes itself (see LiveSubscription). */
   acknowledge(): void;
+  /**
+   * Holds the block alone while the page stays live (see LiveSubscription).
+   * Does nothing on a page without `live`.
+   */
+  setHeld(isHeld: boolean): void;
 }
 
 interface BoundSubscription {
@@ -103,5 +108,6 @@ export function useLiveGate(refresh: () => void): LiveGate {
       else refresh();
     },
     acknowledge: () => resolve()?.acknowledge(),
+    setHeld: (isHeld) => resolve()?.setHeld(isHeld),
   };
 }

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

@@ -0,0 +1,42 @@
+import type { PageLiveOptions, PageLivePeriod } from "../../../types/live";
+
+const MS_PER_SECOND = 1000;
+const MS_PER_UNIT: Record<string, number> = {
+  m: 60 * MS_PER_SECOND,
+  h: 60 * 60 * MS_PER_SECOND,
+  d: 24 * 60 * 60 * MS_PER_SECOND,
+};
+const PERIOD_PATTERN = /^(\d+)([mhd])$/;
+
+/**
+ * The length of a `slowRateAfter.period` in ms, `null` when it does not read
+ * like `"30m"`, `"24h"` or `"7d"`.
+ *
+ * @internal
+ */
+export function livePeriodMs(period: PageLivePeriod | string): number | null {
+  const match = PERIOD_PATTERN.exec(period);
+  if (!match) return null;
+  const [, amount, unit] = match;
+  return Number(amount) * (MS_PER_UNIT[unit!] ?? 0) || null;
+}
+
+/**
+ * The shortest interval between two reads of one block, in ms, for a page
+ * showing a period spanning `periodSpanMs` (`null` without a period): the
+ * slower `slowRateAfter` once the span reaches its period, `maxRate` else,
+ * 0 for no cap.
+ *
+ * @internal
+ */
+export function liveIntervalMs(
+  options: PageLiveOptions,
+  periodSpanMs: number | null,
+): number {
+  const slow = options.slowRateAfter;
+  const slowFrom = slow ? livePeriodMs(slow.period) : null;
+  if (slow && slowFrom !== null && periodSpanMs !== null) {
+    if (periodSpanMs >= slowFrom) return slow.maxRate * MS_PER_SECOND;
+  }
+  return (options.maxRate ?? 0) * MS_PER_SECOND;
+}

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

@@ -0,0 +1,66 @@
+import { computed, shallowRef, type ComputedRef } from "vue";
+import type { PageLiveNote, PageLiveNoteInput } from "../../../types/live";
+
+interface HoldEntry {
+  note: PageLiveNote;
+  /** The user resumed over this hold: it no longer pauses the page. */
+  isLifted: boolean;
+}
+
+/**
+ * A note given as its text alone, as a full note.
+ *
+ * @internal
+ */
+export function toLiveNote(input: PageLiveNoteInput): PageLiveNote {
+  return typeof input === "string" ? { text: input } : input;
+}
+
+/**
+ * The components holding a live page paused, each with its reason. A hold the
+ * user resumed over is lifted: it stays lifted while its owner keeps holding,
+ * and pauses again once released and taken anew.
+ *
+ * @internal
+ */
+export class LiveHolds {
+  private readonly entries = shallowRef(new Map<symbol, HoldEntry>());
+
+  /** The reason of the first hold still pausing the page, `null` without one. */
+  readonly activeNote: ComputedRef<PageLiveNote | null> = computed(() => {
+    for (const entry of this.entries.value.values()) {
+      if (!entry.isLifted) return entry.note;
+    }
+    return null;
+  });
+
+  get isActive(): boolean {
+    return this.activeNote.value !== null;
+  }
+
+  set(owner: symbol, note: PageLiveNoteInput): void {
+    const isLifted = this.entries.value.get(owner)?.isLifted ?? false;
+    this.replace((entries) =>
+      entries.set(owner, { note: toLiveNote(note), isLifted }),
+    );
+  }
+
+  release(owner: symbol): void {
+    if (!this.entries.value.has(owner)) return;
+    this.replace((entries) => entries.delete(owner));
+  }
+
+  liftAll(): void {
+    this.replace((entries) => {
+      for (const entry of entries.values()) entry.isLifted = true;
+    });
+  }
+
+  private replace(change: (entries: Map<symbol, HoldEntry>) => void): void {
+    const next = new Map(
+      [...this.entries.value].map(([owner, entry]) => [owner, { ...entry }]),
+    );
+    change(next);
+    this.entries.value = next;
+  }
+}

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

@@ -0,0 +1,42 @@
+import { readonly, ref, type Ref } from "vue";
+
+/**
+ * Reads the page's blocks on a clock while the realtime stream is down: the
+ * fallback of a live page with a cadence. Each tick asks the interval again,
+ * so a period changed meanwhile applies from the next one.
+ *
+ * @internal
+ */
+export class LivePoller {
+  private readonly active = ref(false);
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  /** The poller is running: the stream is down and the page reads by itself. */
+  readonly isPolling: Readonly<Ref<boolean>> = readonly(this.active);
+
+  constructor(
+    private readonly intervalMs: () => number,
+    private readonly poll: () => void,
+  ) {}
+
+  /** Runs while `shouldRun` holds and the page has a cadence; stops else. */
+  update(shouldRun: boolean): void {
+    const isRunning = shouldRun && this.intervalMs() > 0;
+    if (isRunning === this.active.value) return;
+    this.active.value = isRunning;
+    if (isRunning) this.schedule();
+    else this.stop();
+  }
+
+  stop(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.active.value = false;
+  }
+
+  private schedule(): void {
+    this.timer = setTimeout(() => {
+      this.poll();
+      if (this.active.value) this.schedule();
+    }, this.intervalMs());
+  }
+}

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

@@ -0,0 +1,42 @@
+const STORAGE_KEY_PREFIX = "dms.live.paused:";
+const REMEMBER_KEY_PREFIX = "key:";
+const PAUSED_VALUE = "1";
+
+/** 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;
+  }
+}
+
+/**
+ * The storage key of a page's Live / Pause choice: its `live.rememberKey` when it
+ * shares one, its own id else.
+ *
+ * @internal
+ */
+export function liveStorageKey(pageId: string, rememberKey?: string): string {
+  return (
+    STORAGE_KEY_PREFIX +
+    (rememberKey ? REMEMBER_KEY_PREFIX + rememberKey : pageId)
+  );
+}
+
+/** @internal */
+export function readStoredPause(key: string): boolean {
+  return liveStorage()?.getItem(key) === PAUSED_VALUE;
+}
+
+/** @internal */
+export function storePause(key: string, isPaused: boolean): void {
+  const storage = liveStorage();
+  if (!storage) return;
+  try {
+    if (isPaused) storage.setItem(key, PAUSED_VALUE);
+    else storage.removeItem(key);
+  } catch {
+    // A full or locked storage only loses the memory of the choice.
+  }
+}

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

@@ -0,0 +1,65 @@
+import { readonly, ref, type Ref } from "vue";
+
+interface PublishedEvent {
+  topic?: unknown;
+  payload?: { ids?: unknown; count?: unknown };
+}
+
+function rowKeysOf(event: PublishedEvent): string[] {
+  const ids = event.payload?.ids;
+  if (!Array.isArray(ids)) return [];
+  const topic = typeof event.topic === "string" ? event.topic : "";
+  return ids
+    .filter((id) => typeof id === "string" || typeof id === "number")
+    .map((id) => JSON.stringify([topic, id]));
+}
+
+function batchCountOf(event: PublishedEvent): number | null {
+  const count = event.payload?.count;
+  return typeof count === "number" && Number.isInteger(count) && count > 0
+    ? count
+    : null;
+}
+
+/**
+ * What the events received since the pause stand for, published rows rather
+ * than messages: a message naming rows in `payload.ids` counts each row once
+ * (a table view's row events, a bulk write), a batch announcing
+ * `payload.count` counts that many (a module publishing its requests every
+ * second or so), anything else counts one. The same event object reaching
+ * the tally twice (one event, several blocks) counts once.
+ *
+ * @internal
+ */
+export class MissedTally {
+  private readonly count = ref(0);
+  private events = new WeakSet<object>();
+  private rows = new Set<string>();
+  /** The rows and events counted since the last reset. */
+  readonly total: Readonly<Ref<number>> = readonly(this.count);
+
+  add(event: object | undefined): void {
+    if (event) {
+      if (this.events.has(event)) return;
+      this.events.add(event);
+    }
+    this.count.value += this.weightOf(event as PublishedEvent | undefined);
+  }
+
+  reset(): void {
+    this.count.value = 0;
+    this.events = new WeakSet();
+    this.rows = new Set();
+  }
+
+  private weightOf(event: PublishedEvent | undefined): number {
+    if (!event) return 1;
+    const rowKeys = rowKeysOf(event);
+    if (rowKeys.length > 0) {
+      const fresh = rowKeys.filter((key) => !this.rows.has(key));
+      fresh.forEach((key) => this.rows.add(key));
+      return fresh.length;
+    }
+    return batchCountOf(event) ?? 1;
+  }
+}