@antelopejs/dms 0.9.8 → 0.10.0

package/frontend-vue/layers/dms-ui/app/build/composables/form/toasterClearance.ts

@@ -0,0 +1,118 @@
+import { onBeforeUnmount, onMounted, watch } from "vue";
+
+/**
+ * The CSS variable the toaster's bottom offset adds (theme/surfaces.ts): how
+ * far above the viewport's bottom edge a bar anchored there reaches.
+ */
+export const TOASTER_CLEARANCE_VAR = "--dms-toaster-clearance";
+
+/**
+ * How close to the viewport's bottom edge a bar has to end to count as
+ * anchored there: the floating save bar floats 16px off it. A bar that ends
+ * higher (a short form's bar, a card's footer band mid-page) leaves the
+ * toaster's corner free.
+ */
+const BOTTOM_EDGE_REACH = 48;
+
+/** The part of a bar's bounding box the clearance reads. */
+export interface BarBox {
+  top: number;
+  bottom: number;
+  height: number;
+}
+
+/**
+ * The room the toaster leaves above the bars anchored to the bottom of a
+ * viewport `viewportHeight` tall: the distance from that edge to the highest
+ * such bar's top, 0 when none is.
+ */
+export function toasterClearance(
+  boxes: BarBox[],
+  viewportHeight: number,
+): number {
+  let clearance = 0;
+  for (const box of boxes) {
+    const isAnchored =
+      box.height > 0 &&
+      box.top < viewportHeight &&
+      box.bottom >= viewportHeight - BOTTOM_EDGE_REACH;
+    if (isAnchored)
+      clearance = Math.max(clearance, Math.ceil(viewportHeight - box.top));
+  }
+  return clearance;
+}
+
+type BarElement = () => HTMLElement | null | undefined;
+
+// Only mounted, shown bars count, so a server render never adds to it.
+const shownBars = new Map<symbol, BarElement>();
+let frame = 0;
+
+function applyClearance(): void {
+  frame = 0;
+  const boxes = [...shownBars.values()]
+    .map((element) => element()?.getBoundingClientRect())
+    .filter((box): box is DOMRect => !!box);
+  const clearance = toasterClearance(boxes, window.innerHeight);
+  const { style } = document.documentElement;
+  if (clearance > 0) style.setProperty(TOASTER_CLEARANCE_VAR, `${clearance}px`);
+  else style.removeProperty(TOASTER_CLEARANCE_VAR);
+}
+
+// A bar moves with the scroll (a sticky bar reaches the edge, a form's end
+// leaves it), the viewport, its own show transition and a drawer's opening
+// animation: one measure a frame.
+function scheduleClearance(): void {
+  if (frame) return;
+  frame = requestAnimationFrame(applyClearance);
+}
+
+const LISTENED_EVENTS = [
+  "scroll",
+  "resize",
+  "transitionend",
+  "animationend",
+] as const;
+
+function listen(isListening: boolean): void {
+  const method = isListening ? "addEventListener" : "removeEventListener";
+  for (const event of LISTENED_EVENTS)
+    window[method](event, scheduleClearance, { capture: true, passive: true });
+}
+
+function setBarShown(id: symbol, element: BarElement, isShown: boolean): void {
+  const wasEmpty = shownBars.size === 0;
+  if (isShown) shownBars.set(id, element);
+  else shownBars.delete(id);
+  if (wasEmpty !== (shownBars.size === 0)) listen(shownBars.size > 0);
+  scheduleClearance();
+}
+
+/**
+ * Keeps the toaster clear of the calling bar while `isShown` holds and the
+ * bar sits on the bottom edge of the viewport: the toast stack rises above
+ * it instead of covering its buttons, and drops back once it hides.
+ */
+export function trackToasterClearance(
+  element: BarElement,
+  isShown: () => boolean,
+): void {
+  const id = Symbol("toaster-clearance");
+  let isMounted = false;
+  const stop = watch(
+    isShown,
+    (shown) => {
+      if (isMounted) setBarShown(id, element, shown);
+    },
+    { flush: "post" },
+  );
+  onMounted(() => {
+    isMounted = true;
+    setBarShown(id, element, isShown());
+  });
+  onBeforeUnmount(() => {
+    stop();
+    isMounted = false;
+    setBarShown(id, element, false);
+  });
+}

package/frontend-vue/layers/dms-ui/app/build/composables/form/useInstantForm.ts

@@ -54,6 +54,11 @@ export interface InstantFormOptions {
 export interface InstantForm extends InstantSave<FormValues> {
   /** The form loaded or was reset: its values are the confirmed ones. */
   start: () => void;
+  /**
+   * A field the server stored on its own (a rotated secret): its value is the
+   * confirmed one, not a change to save again.
+   */
+  confirmField: (id: string, value: unknown) => void;
 }
 
 const clone = (value: unknown): unknown =>
@@ -92,6 +97,12 @@ export function useInstantForm(options: InstantFormOptions): InstantForm {
     instant.confirm(values);
   }
 
+  function confirmField(id: string, value: unknown): void {
+    const confirmed = clone(value);
+    shown.set(id, confirmed);
+    instant.confirm({ [id]: confirmed });
+  }
+
   async function saveField(field: FormField, value: unknown): Promise<void> {
     const check = (checks.get(field.id) ?? 0) + 1;
     checks.set(field.id, check);
@@ -121,5 +132,5 @@ export function useInstantForm(options: InstantFormOptions): InstantForm {
     { deep: true },
   );
 
-  return { ...instant, start };
+  return { ...instant, start, confirmField };
 }

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

@@ -1,14 +1,19 @@
 import {
   computed,
+  getCurrentInstance,
   getCurrentScope,
+  inject,
   onScopeDispose,
+  provide,
   shallowRef,
   type ComputedRef,
+  type InjectionKey,
 } from "vue";
 import type {
   LiveSubscription,
   PageLiveController,
 } from "./pageLiveController";
+import { markPageRead } from "./pageReadClock";
 
 // Client-only state: the page renderer sets it in the browser, where one app
 // shows one page at a time. The server renders no event and no refetch, so it
@@ -36,6 +41,34 @@ export function setCurrentPageLive(controller: PageLiveController | null) {
   currentController.value = controller;
 }
 
+// Server only: whether the page being rendered declares `live`. The browser
+// installs the page's controller before its blocks set up, so they hydrate
+// as on a live page; the server has no controller, and tells them instead.
+const SERVER_PAGE_LIVE_KEY: InjectionKey<() => boolean> = Symbol(
+  "dms-server-page-live",
+);
+
+/**
+ * Tells the blocks of the page the server renders whether it declares `live`.
+ * The page renderer calls it.
+ *
+ * @internal
+ */
+export function provideServerPageLive(isLive: () => boolean): void {
+  provide(SERVER_PAGE_LIVE_KEY, isLive);
+}
+
+/**
+ * While server-rendering, whether the page declares `live`; `false` in the
+ * browser, where `currentPageLive()` answers. Call it in a component setup.
+ *
+ * @internal
+ */
+export function isServerPageLive(): boolean {
+  if (typeof window !== "undefined" || !getCurrentInstance()) return false;
+  return inject(SERVER_PAGE_LIVE_KEY, null)?.() ?? false;
+}
+
 /** @internal */
 export interface LiveGate {
   /** An event behind the block arrived: refetch, now or later, or count it. */
@@ -62,7 +95,7 @@ interface BoundSubscription {
 
 /**
  * The gate a block's refetch goes through. On a page without `live` it calls
- * `refresh` at once, as before. Bound lazily, on the first event, to the
+ * `refresh` at once, as before, and records the read (`pageReadAt`). Bound lazily, on the first event, to the
  * controller of the page on screen: a block of the page layout sets up before
  * the page installs its controller.
  *
@@ -89,6 +122,11 @@ export function useLiveGate(refresh: () => void): LiveGate {
 
   if (getCurrentScope()) onScopeDispose(unbind);
 
+  const refreshUngated = () => {
+    markPageRead();
+    refresh();
+  };
+
   const current = () =>
     bound.value?.controller === currentController.value
       ? (bound.value?.subscription ?? null)
@@ -98,14 +136,14 @@ export function useLiveGate(refresh: () => void): LiveGate {
     trigger: (event) => {
       const subscription = resolve();
       if (subscription) subscription.trigger(event);
-      else refresh();
+      else refreshUngated();
     },
     missed: computed(() => current()?.missed.value ?? 0),
     lastReadAt: computed(() => current()?.lastReadAt.value ?? 0),
     catchUp: () => {
       const subscription = resolve();
       if (subscription) subscription.catchUp();
-      else refresh();
+      else refreshUngated();
     },
     acknowledge: () => resolve()?.acknowledge(),
     setHeld: (isHeld) => resolve()?.setHeld(isHeld),

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

@@ -9,9 +9,15 @@ import { readonly, ref, type Ref } from "vue";
  */
 export class LivePoller {
   private readonly active = ref(false);
+  private readonly hasPolled = 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);
+  /**
+   * The page reads by itself: the stream stayed down for a whole interval and
+   * the first poll ran. Not while a page's stream is still connecting (every
+   * full load starts "down" until it opens), which would flash the polling
+   * hint for a frame.
+   */
+  readonly isPolling: Readonly<Ref<boolean>> = readonly(this.hasPolled);
 
   constructor(
     private readonly intervalMs: () => number,
@@ -31,10 +37,12 @@ export class LivePoller {
     if (this.timer) clearTimeout(this.timer);
     this.timer = null;
     this.active.value = false;
+    this.hasPolled.value = false;
   }
 
   private schedule(): void {
     this.timer = setTimeout(() => {
+      this.hasPolled.value = true;
       this.poll();
       if (this.active.value) this.schedule();
     }, this.intervalMs());

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

@@ -0,0 +1,28 @@
+import { type Ref, readonly, shallowRef } from "vue";
+
+// Client-only, like the live controller: the browser shows one page at a
+// time, and a module-level value on the server would be shared between
+// requests.
+const readAt = shallowRef<number | null>(null);
+
+/**
+ * When the page on screen last read its data (ms since the epoch), on a page
+ * with or without `live`: set when the page is shown, each time its blocks
+ * read again outside a live gate, and once a `refreshPageBlocks()` is done.
+ * `null` before the first page (and on the server). A live page's own clock
+ * is its controller's `lastUpdatedAt`.
+ *
+ * @internal
+ */
+export const pageReadAt: Readonly<Ref<number | null>> = readonly(readAt);
+
+/**
+ * Records that the page on screen read its data now. Does nothing on the
+ * server.
+ *
+ * @internal
+ */
+export function markPageRead(): void {
+  if (typeof window === "undefined") return;
+  readAt.value = Date.now();
+}

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

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

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

@@ -1,10 +1,11 @@
 import { onMounted, onScopeDispose, watch } from "vue";
 import type { PageLiveOptions } from "../../../types/live";
-import { setCurrentPageLive } from "./currentPageLive";
+import { provideServerPageLive, setCurrentPageLive } from "./currentPageLive";
 import {
   createPageLiveController,
   type PageLiveController,
 } from "./pageLiveController";
+import { markPageRead } from "./pageReadClock";
 
 /** The URL query key opening a live page paused: `?live=0`. */
 const LIVE_URL_KEY = "live";
@@ -69,7 +70,10 @@ export function bindPageLiveEnvironment(
 
 /**
  * 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.
+ * a new one when the renderer moves to another page; on every page, starts
+ * its read clock (`pageReadAt`) as it is shown. A server render has no
+ * controller: it only tells the page's blocks whether the page is live, so
+ * they draw what the hydrating browser draws.
  *
  * @internal
  */
@@ -77,7 +81,13 @@ export function usePageLiveHost(
   source: () => PageLiveSource,
   environment: PageLiveEnvironment = {},
 ): void {
-  if (typeof window === "undefined") return;
+  if (typeof window === "undefined") {
+    provideServerPageLive(() => {
+      const { pageId, live } = source();
+      return Boolean(pageId && live);
+    });
+    return;
+  }
   let controller: PageLiveController | null = null;
   let unbind: (() => void) | null = null;
   // The server renders every page live: the remembered pause applies once
@@ -116,5 +126,9 @@ export function usePageLiveHost(
     { immediate: true },
   );
 
+  // The page's blocks read as it is shown: the server's render, or the
+  // browser's on a client navigation.
+  watch(() => source().pageId, markPageRead, { immediate: true });
+
   onScopeDispose(() => install(null));
 }

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

@@ -0,0 +1,38 @@
+import {
+  type ComputedRef,
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+} from "vue";
+import { formatElapsed } from "./formatElapsed";
+
+const TICK_MS = 1000;
+
+/**
+ * "Updated 12 s ago" from the instant `at` gives (ms since the epoch), counted
+ * every second once mounted; empty while `at` is `null`. The clock is the
+ * browser's: render the label once mounted only.
+ *
+ * @internal
+ */
+export function useUpdatedLabel(
+  at: () => number | null,
+  shouldTick = true,
+): ComputedRef<string> {
+  const { t } = useI18n();
+  const now = ref(Date.now());
+  let ticker: ReturnType<typeof setInterval> | undefined;
+  onMounted(() => {
+    now.value = Date.now();
+    if (shouldTick)
+      ticker = setInterval(() => (now.value = Date.now()), TICK_MS);
+  });
+  onBeforeUnmount(() => clearInterval(ticker));
+  return computed(() => {
+    const instant = at();
+    if (instant === null) return "";
+    const { unit, count } = formatElapsed(now.value - instant);
+    return t(`dms.live.updated_${unit}`, { count }, count);
+  });
+}

package/frontend-vue/layers/dms-ui/app/build/composables/page-toolbar/pageToolbarContext.ts

@@ -0,0 +1,75 @@
+import {
+  computed,
+  type ComputedRef,
+  type InjectionKey,
+  inject,
+  onBeforeUnmount,
+  onMounted,
+  provide,
+  ref,
+} from "vue";
+import type { PageToolbarSize } from "../../../types/page-toolbar";
+
+export type { PageToolbarSize };
+
+/**
+ * What a `PageToolbar` gives the blocks it holds.
+ *
+ * @internal
+ */
+export interface PageToolbarContext {
+  /** The size its `LiveToggle` and `PeriodSelector` take unless they set one. */
+  size: ComputedRef<PageToolbarSize>;
+  /** A `LiveToggle` is mounted in it: the toolbar leaves the updated label to it. */
+  hasLiveToggle: ComputedRef<boolean>;
+  /** Counts a mounted `LiveToggle`; returns the uncount. */
+  registerLiveToggle(): () => void;
+}
+
+const PAGE_TOOLBAR_KEY: InjectionKey<PageToolbarContext> =
+  Symbol("dms-page-toolbar");
+
+/**
+ * Provides the context of a `PageToolbar` to the blocks it holds.
+ *
+ * @internal
+ */
+export function providePageToolbar(
+  size: ComputedRef<PageToolbarSize>,
+): PageToolbarContext {
+  const liveToggles = ref(0);
+  const context: PageToolbarContext = {
+    size,
+    hasLiveToggle: computed(() => liveToggles.value > 0),
+    registerLiveToggle() {
+      liveToggles.value += 1;
+      return () => {
+        liveToggles.value -= 1;
+      };
+    },
+  };
+  provide(PAGE_TOOLBAR_KEY, context);
+  return context;
+}
+
+/**
+ * The `PageToolbar` holding the calling block, `null` outside one.
+ *
+ * @internal
+ */
+export function usePageToolbar(): PageToolbarContext | null {
+  return inject(PAGE_TOOLBAR_KEY, null);
+}
+
+/**
+ * Tells the toolbar holding the calling `LiveToggle`, if any, that it is
+ * mounted there, for as long as it is.
+ *
+ * @internal
+ */
+export function useToolbarLiveToggle(toolbar: PageToolbarContext | null): void {
+  if (!toolbar) return;
+  let unregister: (() => void) | undefined;
+  onMounted(() => (unregister = toolbar.registerLiveToggle()));
+  onBeforeUnmount(() => unregister?.());
+}

package/frontend-vue/layers/dms-ui/app/build/composables/page-toolbar/toolbarControlHeight.ts

@@ -0,0 +1,29 @@
+import type { PageToolbarSize } from "./pageToolbarContext";
+
+/**
+ * The one height every control of a toolbar takes at each size -- the live
+ * pill, the segmented presets, the comparison trigger, the refresh button,
+ * the labels and a leading chip -- so a bar is as tall with live as without.
+ * The segmented track's and Nuxt UI's buttons' own steps (24/28/32 px),
+ * written out so a theme's padding cannot change them.
+ *
+ * @internal
+ */
+export const PAGE_TOOLBAR_CONTROL_HEIGHT_CLASSES: Record<
+  PageToolbarSize,
+  string
+> = {
+  xs: "h-6",
+  sm: "h-7",
+  md: "h-8",
+};
+
+/**
+ * The height class of a control drawn at `size`, empty for a size the
+ * toolbar has no step for (a period selector's `lg`, `xl`).
+ *
+ * @internal
+ */
+export function toolbarControlHeightClass(size: string): string {
+  return PAGE_TOOLBAR_CONTROL_HEIGHT_CLASSES[size as PageToolbarSize] ?? "";
+}

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

@@ -0,0 +1,52 @@
+import { computed, type ComputedRef } from "vue";
+import { usePeriodScopeComparison } from "#dms-core/app/composables/period/usePeriodScope";
+import type { PeriodComparison } from "#dms-core/app/composables/period/types";
+
+const COMPARE_LABEL_KEY_PREFIX = "dms.period.compare_labels";
+const COMPARE_LEGEND_KEY_PREFIX = "dms.period.compare_options";
+// A custom window has no name of its own: its legend keeps the generic one.
+const NAMED_LEGEND_COMPARISONS: PeriodComparison[] = [
+  "previous-period",
+  "previous-year",
+];
+
+export interface PeriodComparisonDisplay {
+  /**
+   * The scope compares against nothing: the user picked "no comparison", or
+   * the period (every period, `all`) has no window to compare against. A
+   * card hides its change, its comparison value and its label. `false` while
+   * the card has no scope, or its scope is not registered yet: the card then
+   * shows what its data carries.
+   */
+  isOff: ComputedRef<boolean>;
+  /** "vs previous year", following the scope; `null` without one. */
+  label: ComputedRef<string | null>;
+  /** "Previous year", a chart legend's name for the comparison series. */
+  legendLabel: ComputedRef<string | null>;
+}
+
+/**
+ * What a period-bound card shows of its comparison, following the
+ * comparison selected on the scope's `PeriodSelector`.
+ */
+export function usePeriodComparisonDisplay(
+  periodScope: string | undefined,
+): PeriodComparisonDisplay {
+  const { t } = useI18n();
+  const comparison = usePeriodScopeComparison(periodScope);
+  const activeComparison = computed(() =>
+    comparison.value && comparison.value !== "none" ? comparison.value : null,
+  );
+  return {
+    isOff: computed(() => comparison.value === "none"),
+    label: computed(() => {
+      const active = activeComparison.value;
+      return active ? t(`${COMPARE_LABEL_KEY_PREFIX}.${active}`, active) : null;
+    }),
+    legendLabel: computed(() => {
+      const active = activeComparison.value;
+      if (!active || !NAMED_LEGEND_COMPARISONS.includes(active)) return null;
+      return t(`${COMPARE_LEGEND_KEY_PREFIX}.${active}`, active);
+    }),
+  };
+}

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

@@ -182,6 +182,27 @@ export function formatPeriodRange(
   return formatRangeWith(range, locale, options);
 }
 
+/**
+ * Day-only range label, "16 – 17 Oct": a comparison menu's trigger names the
+ * window it compares with, where the hours would only widen it. A window
+ * shorter than a day keeps its times, its day alone telling nothing.
+ * `withYear: false` drops the year, as in `formatPeriodRange`.
+ */
+export function formatPeriodDays(
+  range: PeriodRange,
+  locale: string,
+  withYear = true,
+): string {
+  const span = range.to.getTime() - range.from.getTime();
+  if (span < MS_PER_DAY - MS_PER_HOUR) {
+    return formatRangeWith(range, locale, { ...DAY_FORMAT, ...TIME_FORMAT });
+  }
+  const options: FormatOptions = withYear
+    ? { ...DAY_FORMAT, year: "numeric" }
+    : DAY_FORMAT;
+  return formatRangeWith(range, locale, options);
+}
+
 export interface PeriodDuration {
   unit: "days" | "hours";
   count: number;

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

@@ -0,0 +1,28 @@
+import type { PeriodPreset } from "#dms-core/app/composables/period/types";
+
+/**
+ * Short mono codes, as trails in the preset list and segmented labels: every
+ * preset has one, so a row of segments stays as narrow with `all` as without
+ * it, where the full label ("All time") widened it. Custom has none: it shows
+ * its range. Each is translated under `dms.period.short_presets.<preset>`
+ * ("24 h", "7 j" in French); these English codes are the fallback for a
+ * locale that lacks one, and the list of presets that have a code.
+ *
+ * @internal
+ */
+export const PRESET_SHORT_LABELS: Partial<Record<PeriodPreset, string>> = {
+  "last-hour": "1H",
+  "last-24h": "24H",
+  today: "1D",
+  yesterday: "-1D",
+  "last-7-days": "7D",
+  "last-30-days": "30D",
+  "last-90-days": "90D",
+  "this-month": "MTD",
+  "last-month": "-1M",
+  "this-quarter": "QTD",
+  "last-quarter": "-1Q",
+  ytd: "YTD",
+  "last-year": "-1Y",
+  all: "ALL",
+};

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

@@ -84,6 +84,7 @@ export function usePeriodDraft(period: UsePeriodReturn): UsePeriodDraftReturn {
       comparison.value,
       range.value,
       period.customCompareRange.value,
+      { preset: preset.value, now: new Date() },
     ),
   );