@antelopejs/dms 0.9.8 → 0.11.0

package/frontend-vue/layers/dms-core/app/composables/auth/useApiData.ts

@@ -6,7 +6,8 @@ import type {
   UseDmsPagedDataOptions,
   UseFetchOptions,
 } from "#dms/frontend-module";
-import type { MaybeRefOrGetter } from "vue";
+import { getCurrentInstance, toValue, watch, type MaybeRefOrGetter } from "vue";
+import { useLivePauseSource } from "../live/livePauseSource";
 
 /** The authenticated fetch `useAuthFetch` returns. */
 type AuthFetch = ReturnType<typeof useAuthFetch>["$authFetch"];
@@ -61,7 +62,9 @@ export type ApiDataResult<T> = DmsAsyncDataResult<T>;
  * - `refreshInterval: ms` reads again on an interval while the caller shows
  *   the data and the page is visible: polling. A ref or a getter changes it,
  *   and `0` or `null` stops it; a call from a plugin polls for as long as
- *   the application runs.
+ *   the application runs. On a page declared with `live`, a component's
+ *   polling stops while the page is paused, and reads once on resume if a
+ *   poll fell due meanwhile.
  * - The page's refreshes (`refreshPageBlocks()`) and the events of its
  *   realtime topics read the data again; `refreshOnPageRefresh: false` opts
  *   out, for data with refresh triggers of its own.
@@ -88,15 +91,74 @@ export function useApiData<T>(
 ): ApiDataResult<T> {
   const { $authFetch } = useAuthFetch();
   if (typeof handlerOrOptions === "function")
-    return useDmsAsyncData<T>(
-      source,
-      ({ signal }) => handlerOrOptions({ $authFetch, signal }),
+    return followLivePause(
+      useDmsAsyncData<T>(
+        source,
+        ({ signal }) => handlerOrOptions({ $authFetch, signal }),
+        gateLivePolling(options),
+      ),
       options,
     );
-  return useDmsFetch<T>(source, {
-    ...handlerOrOptions,
-    $fetch: $authFetch as UseFetchOptions<T>["$fetch"],
+  return followLivePause(
+    useDmsFetch<T>(source, {
+      ...gateLivePolling(handlerOrOptions),
+      $fetch: $authFetch as UseFetchOptions<T>["$fetch"],
+    }),
+    handlerOrOptions,
+  );
+}
+
+/** The options of a read that polls, as far as its live gate goes. */
+interface PolledReadOptions {
+  refreshInterval?: MaybeRefOrGetter<number | null | undefined>;
+  immediate?: boolean;
+}
+
+// A component's polling is one more read nobody asked for: on a live page it
+// stops while the page is paused, as the blocks' refetches do. A plugin's
+// polling (the shell's, outside any page) keeps running. The pause is read
+// through the app's `LIVE_PAUSE_SOURCE`, which the UI layer provides.
+function isGatedPolling(
+  options: PolledReadOptions | undefined,
+): options is PolledReadOptions {
+  return options?.refreshInterval !== undefined && !!getCurrentInstance();
+}
+
+/** `options` with a `refreshInterval` that is `null` while the page is paused. */
+function gateLivePolling<O extends PolledReadOptions>(
+  options: O | undefined,
+): O | undefined {
+  if (!isGatedPolling(options)) return options;
+  const interval = options.refreshInterval;
+  const isPaused = useLivePauseSource();
+  return {
+    ...options,
+    refreshInterval: () => (isPaused() ? null : toValue(interval)),
+  };
+}
+
+/**
+ * Reads once as the page resumes when a poll fell due while it was paused:
+ * the polling restarts with a full interval, which would show the data of
+ * before the pause that long.
+ */
+function followLivePause<
+  R extends Pick<DmsAsyncDataResult<unknown>, "status" | "refresh">,
+>(result: R, options: PolledReadOptions | undefined): R {
+  if (typeof window === "undefined" || !isGatedPolling(options)) return result;
+  let pausedAt = 0;
+  watch(useLivePauseSource(), (isPaused) => {
+    if (isPaused) {
+      pausedAt = Date.now();
+      return;
+    }
+    const period = toValue(options.refreshInterval);
+    if (!period || period <= 0 || Date.now() - pausedAt < period) return;
+    // Data a caller waits to `execute()` is not read before it is.
+    if (result.status.value === "idle" && options.immediate === false) return;
+    void result.refresh({ dedupe: "defer" });
   });
+  return result;
 }
 
 /** What a handler reading one page of API data receives. */
@@ -139,10 +201,13 @@ export function useApiPagedData<TPage, TCursor = unknown>(
   options: UseDmsPagedDataOptions<TPage, TCursor>,
 ): ApiPagedDataResult<TPage, TCursor> {
   const { $authFetch } = useAuthFetch();
-  return useDmsPagedData<TPage, TCursor>(
-    key,
-    ({ cursor, index, signal }) =>
-      handler({ $authFetch, cursor, index, signal }),
+  return followLivePause(
+    useDmsPagedData<TPage, TCursor>(
+      key,
+      ({ cursor, index, signal }) =>
+        handler({ $authFetch, cursor, index, signal }),
+      gateLivePolling(options) ?? options,
+    ),
     options,
   );
 }

package/frontend-vue/layers/dms-core/app/composables/data-types/useDataType.ts

@@ -36,6 +36,24 @@ export type DataTypeValueComparer = (
   options?: unknown,
 ) => boolean;
 
+/**
+ * The value a filter chip's editor holds for a filter value a view declared
+ * as text (`"0"`, `"2026-10-01,2026-10-15"`), under a compare mode: a number
+ * input refuses `"0"`, a date range wants its two days. The filter itself
+ * keeps its text, so the query is unchanged.
+ */
+export type DataTypeFilterEditorValue = (text: string, mode: string) => unknown;
+
+/**
+ * Where the rows a value names are read: the `select` route of the table a
+ * relation points to, and the keys its rows carry their label and value under
+ * (`label` and `value` unless mapped).
+ */
+export interface DataTypeSelectSource {
+  searchUrl: string;
+  keyMapping?: { label?: string; value?: string };
+}
+
 export interface DataType {
   id: string;
   formatter?: RecordWithDefault<DataTypeFormatter>;
@@ -46,6 +64,14 @@ export interface DataType {
    * or whose order does not count. Without it, values compare deeply.
    */
   isSameValue?: DataTypeValueComparer;
+  /** Without it, a filter's editor reads a declared text value as is. */
+  filterEditorValue?: DataTypeFilterEditorValue;
+  /**
+   * For a type whose value holds the ids of rows another table serves (a
+   * relation): where those rows are read, from the options of the type's
+   * control. A filter chip or a read-only list names the ids through it.
+   */
+  selectSource?: (options: unknown) => DataTypeSelectSource | undefined;
   displayComponent?: Component;
 }
 const dataTypes: Record<string, DataType> = {};

package/frontend-vue/layers/dms-core/app/composables/live/livePauseSource.ts

@@ -0,0 +1,29 @@
+import { inject, type InjectionKey } from "vue";
+
+/**
+ * Whether the page on screen is paused right now (by the user, a hold or a
+ * hidden tab). Reactive: it reads reactive state, so a `watch` or a
+ * `computed` over it follows the pause.
+ */
+export type LivePauseSource = () => boolean;
+
+/**
+ * The extension point the core layer reads a page's pause through. The core
+ * owns `useApiData` but not the page's live controller: the layer that owns
+ * the controller provides a source at the app level
+ * (`app.provide(LIVE_PAUSE_SOURCE, source)`), so every component reads the
+ * same page, drawers and modals included. Without one, nothing is paused.
+ */
+export const LIVE_PAUSE_SOURCE: InjectionKey<LivePauseSource> = Symbol(
+  "dms-live-pause-source",
+);
+
+const NEVER_PAUSED: LivePauseSource = () => false;
+
+/**
+ * The pause source of the app the calling component belongs to; never
+ * paused without one. Call it in a component setup.
+ */
+export function useLivePauseSource(): LivePauseSource {
+  return inject(LIVE_PAUSE_SOURCE, NEVER_PAUSED);
+}

package/frontend-vue/layers/dms-core/app/composables/period/compareResolvers.ts

@@ -1,5 +1,5 @@
 import { readerClock } from "./periodClock";
-import type { PeriodComparison, PeriodRange } from "./types";
+import type { PeriodComparison, PeriodPreset, PeriodRange } from "./types";
 
 const NON_OVERLAP_GAP_MS = 1;
 
@@ -30,7 +30,132 @@ function isWholeDayRange(range: PeriodRange): boolean {
   );
 }
 
-function shiftPreviousPeriod(range: PeriodRange): PeriodRange {
+const MONTHS_PER_YEAR = 12;
+const MONTHS_PER_QUARTER = 3;
+
+// The calendar unit a preset counts in, in months: its previous period is
+// the previous month, quarter or year, not the same number of days before.
+const PRESET_MONTH_SPANS: Partial<Record<PeriodPreset, number>> = {
+  "this-month": 1,
+  "last-month": 1,
+  "this-quarter": MONTHS_PER_QUARTER,
+  "last-quarter": MONTHS_PER_QUARTER,
+  ytd: MONTHS_PER_YEAR,
+  "last-year": MONTHS_PER_YEAR,
+};
+
+/** What a comparison is resolved against beyond the range itself. */
+export interface ComparisonContext {
+  /** The preset the range comes from: a calendar one compares by calendar. */
+  preset?: PeriodPreset;
+  /**
+   * The instant the range was resolved at: a range running past today
+   * (`this-month` on the 18th) compares what has elapsed of it.
+   */
+  now?: Date;
+}
+
+/** `date` moved by whole months, its day kept within the month reached. */
+function shiftMonths(date: Date, months: number): Date {
+  const clock = readerClock();
+  const wall = clock.wall(date);
+  const month = wall.month + months;
+  // Day 0 of the next month is the last day of this one.
+  const lastDay = clock.wall(
+    clock.instant({ ...wall, month: month + 1, day: 0 }),
+  ).day;
+  return clock.instant({ ...wall, month, day: Math.min(wall.day, lastDay) });
+}
+
+/** Whether `date` is the midnight opening a calendar month. */
+function isMonthStart(date: Date): boolean {
+  return isLocalMidnight(date) && readerClock().wall(date).day === 1;
+}
+
+/** Months from one month start to another. */
+function monthsBetween(from: Date, to: Date): number {
+  const clock = readerClock();
+  const start = clock.wall(from);
+  const end = clock.wall(to);
+  return (end.year - start.year) * MONTHS_PER_YEAR + end.month - start.month;
+}
+
+/** The instant right after a range: the start of what follows it. */
+const afterRange = (range: PeriodRange): Date =>
+  new Date(range.to.getTime() + NON_OVERLAP_GAP_MS);
+
+/**
+ * The calendar months a range's previous period steps back by: the unit of a
+ * calendar preset, else the months of a range made of whole months (a custom
+ * September compares to August). Any other range has none.
+ */
+function calendarMonthSpan(
+  range: PeriodRange,
+  preset: PeriodPreset | undefined,
+): number | undefined {
+  if (!isMonthStart(range.from)) return undefined;
+  const presetSpan = preset ? PRESET_MONTH_SPANS[preset] : undefined;
+  if (presetSpan) return presetSpan;
+  const end = afterRange(range);
+  return isMonthStart(end) ? monthsBetween(range.from, end) : undefined;
+}
+
+/** The last millisecond of `date`'s day. */
+function endOfDay(date: Date): Date {
+  const clock = readerClock();
+  const nextDay = clock.instant({
+    ...clock.wall(date),
+    day: clock.wall(date).day + 1,
+    hours: 0,
+    minutes: 0,
+    seconds: 0,
+    milliseconds: 0,
+  });
+  return new Date(nextDay.getTime() - NON_OVERLAP_GAP_MS);
+}
+
+/**
+ * What a comparison measures of a range: all of it, or what has elapsed of
+ * it when it runs past today — the rest holds no data yet, and comparing it
+ * with a whole period reads as a fall.
+ */
+function elapsedEnd(range: PeriodRange, now: Date | undefined): Date {
+  if (!now) return range.to;
+  const today = endOfDay(now);
+  return range.to.getTime() > today.getTime() ? today : range.to;
+}
+
+/**
+ * The same span of the calendar `months` earlier: the whole month, quarter
+ * or year before when the range is complete and ends with a month, else its
+ * elapsed days (the 1st to the 18th of the month before).
+ */
+function shiftCalendarPeriod(
+  range: PeriodRange,
+  months: number,
+  end: Date,
+): PeriodRange {
+  const from = shiftMonths(range.from, -months);
+  const isComplete = end.getTime() === range.to.getTime();
+  if (isComplete && isMonthStart(afterRange(range))) {
+    // The span before ends where the range starts: August, then September.
+    return { from, to: new Date(range.from.getTime() - NON_OVERLAP_GAP_MS) };
+  }
+  return { from, to: endOfDay(shiftMonths(end, -months)) };
+}
+
+function shiftPreviousPeriod(
+  range: PeriodRange,
+  context: ComparisonContext,
+): PeriodRange {
+  const months = calendarMonthSpan(range, context.preset);
+  if (months) {
+    return shiftCalendarPeriod(range, months, elapsedEnd(range, context.now));
+  }
+  return shiftEqualLength(range);
+}
+
+function shiftEqualLength(range: PeriodRange): PeriodRange {
   // Whole-day ranges move by calendar days, so a span crossing a daylight
   // saving change still starts at midnight (a fixed-ms shift lands an hour off).
   if (isWholeDayRange(range)) {
@@ -50,7 +175,14 @@ function shiftPreviousPeriod(range: PeriodRange): PeriodRange {
   };
 }
 
-function shiftPreviousYear(range: PeriodRange): PeriodRange {
+function shiftPreviousYear(
+  range: PeriodRange,
+  context: ComparisonContext,
+): PeriodRange {
+  const end = elapsedEnd(range, context.now);
+  if (end.getTime() !== range.to.getTime()) {
+    return shiftCalendarPeriod(range, MONTHS_PER_YEAR, end);
+  }
   return {
     from: shiftCalendar(range.from, 0, -1),
     to: shiftCalendar(range.to, 0, -1),
@@ -59,7 +191,7 @@ function shiftPreviousYear(range: PeriodRange): PeriodRange {
 
 const COMPARISON_RESOLVERS: Record<
   Exclude<PeriodComparison, "none" | "custom">,
-  (range: PeriodRange) => PeriodRange
+  (range: PeriodRange, context: ComparisonContext) => PeriodRange
 > = {
   "previous-period": shiftPreviousPeriod,
   "previous-year": shiftPreviousYear,
@@ -68,18 +200,27 @@ const COMPARISON_RESOLVERS: Record<
 /**
  * Resolves the range a period is compared against.
  *
- * `previous-period` returns the equal-length span immediately before the
- * range, offset by a single millisecond so the two never overlap. Ranges of
+ * `previous-period` follows the calendar for a calendar range: a month, a
+ * quarter or a year (`this-month`, `last-quarter`, `ytd`…, or a custom range
+ * of whole months) compares to the one before — September to August, Q3 to
+ * Q2. Any other range compares to the equal-length span immediately before
+ * it, offset by a single millisecond so the two never overlap; ranges of
  * whole days are measured in calendar days, so daylight saving changes don't
- * move their midnight boundaries. A range with no bounds (`all`) has nothing
- * to compare against: `null`.
+ * move their midnight boundaries.
+ *
+ * A range running past today (`this-month` on the 18th) compares what has
+ * elapsed of it — the 1st to the 18th of the month before, or of the year
+ * before with `previous-year` — not a whole period against days that hold no
+ * data yet. A range with no bounds (`all`) has nothing to compare against:
+ * `null`.
  */
 export function resolveComparisonRange(
   comparison: PeriodComparison,
   range: PeriodRange | null,
   customRange: PeriodRange | null,
+  context: ComparisonContext = {},
 ): PeriodRange | null {
   if (comparison === "none" || !range) return null;
   if (comparison === "custom") return customRange;
-  return COMPARISON_RESOLVERS[comparison](range);
+  return COMPARISON_RESOLVERS[comparison](range, context);
 }

package/frontend-vue/layers/dms-core/app/composables/period/usePeriod.ts

@@ -25,7 +25,7 @@ import {
   resolvePresetRange,
 } from "./presetResolvers";
 import { resolveComparisonRange } from "./compareResolvers";
-import { periodRenderNow } from "./periodRenderNow";
+import { serverRenderNow } from "../../build/composables/renderNow";
 
 export interface UsePeriodOptions {
   defaultPreset?: PeriodPreset;
@@ -52,7 +52,7 @@ export interface UsePeriodReturn {
   state: ComputedRef<PeriodState>;
   /**
    * The instant `state` was resolved from: what a label relative to now
-   * reads, so it holds still with the period (see `periodRenderNow`).
+   * reads, so it holds still with the period (see `serverRenderNow`).
    */
   resolvedAt: ComputedRef<Date>;
   setPreset: (preset: PeriodPreset) => void;
@@ -150,6 +150,7 @@ function buildState(refs: PeriodRefs, now: Date): PeriodState {
     refs.comparison.value,
     range,
     refs.customCompareRange.value,
+    { preset: refs.preset.value, now },
   );
   const partial = {
     preset: refs.preset.value,
@@ -184,7 +185,7 @@ function makeSetters(refs: PeriodRefs) {
  * comparisons and custom ranges resolved into a publishable `state`.
  *
  * A server render and the browser hydrating it resolve from the same instant
- * (`periodRenderNow`), so both render the same bounds.
+ * (`serverRenderNow`), so both render the same bounds.
  *
  * Relative presets (`last-hour`, `last-24h`) re-resolve every minute, and
  * calendar presets (`today`, `last-7-days`, `this-month`...) at each local
@@ -214,7 +215,8 @@ export function usePeriod(options: UsePeriodOptions = {}): UsePeriodReturn {
   // The server render's instant, until the clock ticks or the period changes
   // once on screen: what the setup applies (the URL's period) the server
   // applied as well.
-  const renderNow = shallowRef(periodRenderNow());
+  const serverNow = serverRenderNow();
+  const renderNow = shallowRef(serverNow === null ? null : new Date(serverNow));
   if (renderNow.value) {
     onMounted(() => {
       watch(

package/frontend-vue/layers/dms-core/app/composables/period/usePeriodScope.ts

@@ -88,7 +88,7 @@ function readPeriodScope(
  * first render must match the HTML. It also answers `null` for a period the
  * browser could resolve to other bounds: before the browser's cookie names
  * its time zone. A relative preset resolves from the instant the server
- * hands the browser (`periodRenderNow`), so both read the same bounds.
+ * hands the browser (`serverRenderNow`), so both read the same bounds.
  */
 export function usePeriodScope(
   id: string | undefined,
@@ -144,3 +144,29 @@ export function appendPeriodToUrl(
   const separator = url.includes("?") ? "&" : "?";
   return `${url}${separator}${params.toString()}`;
 }
+
+/**
+ * The comparison a period scope applies, `null` while no selector registers
+ * it: `none` too when the selected comparison resolves to no window (every
+ * period, `all`, has nothing to compare against), so a consumer hides its
+ * comparison exactly when the request carries no `compareFrom` /
+ * `compareTo`. A server render reads it once, as the caller sets up, like
+ * `usePeriodScopePreset`: the mode is a name, the same on both sides.
+ */
+export function usePeriodScopeComparison(
+  id: string | undefined,
+): ComputedRef<PeriodState["comparison"] | null> {
+  if (!id) return computed(() => null);
+  const registry = usePeriodScopeRegistry();
+  if (typeof window !== "undefined")
+    return computed(() => effectiveComparison(readPeriodScope(registry, id)));
+  const comparison = effectiveComparison(readPeriodScope(registry, id));
+  return computed(() => comparison);
+}
+
+function effectiveComparison(
+  state: PeriodState | null,
+): PeriodState["comparison"] | null {
+  if (!state) return null;
+  return state.compareRange ? state.comparison : "none";
+}