@antelopejs/dms 0.8.3 → 0.9.1

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

@@ -8,22 +8,39 @@ import {
   type PeriodPreset,
   type PeriodRange,
 } from "./types";
+import { readerClock } from "./periodClock";
+
+// Resolved in the reader's calendar (`readerClock`): the browser's zone, on
+// the server as in the browser.
+function atTime(
+  date: Date,
+  hours: number,
+  minutes: number,
+  seconds: number,
+  milliseconds: number,
+): Date {
+  const clock = readerClock();
+  return clock.instant({
+    ...clock.wall(date),
+    hours,
+    minutes,
+    seconds,
+    milliseconds,
+  });
+}
 
 function startOfDay(date: Date): Date {
-  const next = new Date(date);
-  next.setHours(0, 0, 0, 0);
-  return next;
+  return atTime(date, 0, 0, 0, 0);
 }
 
 function endOfDay(date: Date): Date {
-  const next = new Date(date);
-  next.setHours(
+  return atTime(
+    date,
     END_OF_DAY_HOURS,
     END_OF_DAY_MINUTES,
     END_OF_DAY_SECONDS,
     END_OF_DAY_MS,
   );
-  return next;
 }
 
 function addDays(date: Date, amount: number): Date {
@@ -34,35 +51,47 @@ function addHours(date: Date, amount: number): Date {
   return new Date(date.getTime() + amount * MS_PER_HOUR);
 }
 
+/** Midnight of a day given as year, month and day; they roll over as `Date`'s. */
+function dayStart(year: number, month: number, day: number): Date {
+  return readerClock().instant({
+    year,
+    month,
+    day,
+    hours: 0,
+    minutes: 0,
+    seconds: 0,
+    milliseconds: 0,
+  });
+}
+
 function startOfMonth(date: Date, monthOffset = 0): Date {
-  return new Date(date.getFullYear(), date.getMonth() + monthOffset, 1);
+  const { year, month } = readerClock().wall(date);
+  return dayStart(year, month + monthOffset, 1);
 }
 
 function endOfMonth(date: Date, monthOffset = 0): Date {
-  const next = new Date(
-    date.getFullYear(),
-    date.getMonth() + monthOffset + 1,
-    0,
-  );
-  return endOfDay(next);
+  const { year, month } = readerClock().wall(date);
+  return endOfDay(dayStart(year, month + monthOffset + 1, 0));
 }
 
 function startOfQuarter(date: Date, quarterOffset = 0): Date {
-  const quarter = Math.floor(date.getMonth() / 3) + quarterOffset;
-  return new Date(date.getFullYear(), quarter * 3, 1);
+  const { year, month } = readerClock().wall(date);
+  const quarter = Math.floor(month / 3) + quarterOffset;
+  return dayStart(year, quarter * 3, 1);
 }
 
 function endOfQuarter(date: Date, quarterOffset = 0): Date {
-  const quarter = Math.floor(date.getMonth() / 3) + quarterOffset;
-  return endOfDay(new Date(date.getFullYear(), quarter * 3 + 3, 0));
+  const { year, month } = readerClock().wall(date);
+  const quarter = Math.floor(month / 3) + quarterOffset;
+  return endOfDay(dayStart(year, quarter * 3 + 3, 0));
 }
 
 function startOfYear(date: Date, yearOffset = 0): Date {
-  return new Date(date.getFullYear() + yearOffset, 0, 1);
+  return dayStart(readerClock().wall(date).year + yearOffset, 0, 1);
 }
 
 function endOfYear(date: Date, yearOffset = 0): Date {
-  return endOfDay(new Date(date.getFullYear() + yearOffset, 11, 31));
+  return endOfDay(dayStart(readerClock().wall(date).year + yearOffset, 11, 31));
 }
 
 const PRESET_RANGE_RESOLVERS: Record<

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

@@ -1,8 +1,10 @@
 import {
   computed,
   getCurrentScope,
+  onMounted,
   onScopeDispose,
   ref,
+  shallowRef,
   watch,
   type ComputedRef,
   type Ref,
@@ -23,6 +25,7 @@ import {
   resolvePresetRange,
 } from "./presetResolvers";
 import { resolveComparisonRange } from "./compareResolvers";
+import { periodRenderNow } from "./periodRenderNow";
 
 export interface UsePeriodOptions {
   defaultPreset?: PeriodPreset;
@@ -47,6 +50,11 @@ export interface UsePeriodReturn {
   presets: ComputedRef<PeriodPreset[]>;
   comparisons: ComputedRef<PeriodComparison[]>;
   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`).
+   */
+  resolvedAt: ComputedRef<Date>;
   setPreset: (preset: PeriodPreset) => void;
   setComparison: (comparison: PeriodComparison) => void;
   setCustomRange: (range: PeriodRange | null) => void;
@@ -135,8 +143,7 @@ interface PeriodRefs {
   customCompareRange: Ref<PeriodRange | null>;
 }
 
-function buildState(refs: PeriodRefs): PeriodState {
-  const now = new Date();
+function buildState(refs: PeriodRefs, now: Date): PeriodState {
   const fallback = refs.customRange.value ?? defaultFallbackRange(now);
   const range = resolvePresetRange(refs.preset.value, now, fallback);
   const compareRange = resolveComparisonRange(
@@ -176,6 +183,9 @@ function makeSetters(refs: PeriodRefs) {
  * Reactive period state machine behind `PeriodSelector` — presets,
  * 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.
+ *
  * Relative presets (`last-hour`, `last-24h`) re-resolve every minute, and
  * calendar presets (`today`, `last-7-days`, `this-month`...) at each local
  * midnight, so a page left open overnight moves on to the new day.
@@ -201,10 +211,28 @@ export function usePeriod(options: UsePeriodOptions = {}): UsePeriodReturn {
     () => options.comparisons ?? DEFAULT_COMPARISONS,
   );
   const presetClock = usePresetClock(refs.preset, options.holdClock);
-  const state = computed<PeriodState>(() => {
+  // 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());
+  if (renderNow.value) {
+    onMounted(() => {
+      watch(
+        [presetClock, ...Object.values(refs)],
+        () => {
+          renderNow.value = null;
+        },
+        { flush: "sync" },
+      );
+    });
+  }
+  const resolution = computed(() => {
     void presetClock.value;
-    return buildState(refs);
+    const now = renderNow.value ?? new Date();
+    return { now, state: buildState(refs, now) };
   });
+  const state = computed<PeriodState>(() => resolution.value.state);
+  const resolvedAt = computed<Date>(() => resolution.value.now);
   const setters = makeSetters(refs);
 
   return {
@@ -212,6 +240,7 @@ export function usePeriod(options: UsePeriodOptions = {}): UsePeriodReturn {
     presets,
     comparisons,
     state,
+    resolvedAt,
     ...setters,
   };
 }

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

@@ -1,4 +1,5 @@
-import { computed, ref, type ComputedRef } from "vue";
+import { computed, markRaw, ref, type ComputedRef, type Ref } from "vue";
+import { resolvesPeriodsAsBrowser } from "./periodTimeZone";
 import type { PeriodState } from "./types";
 
 interface PeriodScopeRegistration {
@@ -6,65 +7,117 @@ interface PeriodScopeRegistration {
   refCount: number;
 }
 
-const periodScopeRegistry = new Map<string, PeriodScopeRegistration>();
-const registryVersion = ref(0);
+interface PeriodScopeRegistry {
+  scopes: Map<string, PeriodScopeRegistration>;
+  version: Ref<number>;
+}
+
+const PERIOD_SCOPES_STATE_KEY = "dms-period-scopes";
 
-function bumpRegistry(): void {
-  registryVersion.value += 1;
+function createRegistry(): PeriodScopeRegistry {
+  return markRaw({ scopes: new Map(), version: ref(0) });
 }
 
-const noopUnregister = (): void => undefined;
+// A browser tab runs one application, whose scopes every caller shares; a
+// server renders many requests at once, each with its own scopes.
+const browserRegistry = createRegistry();
+
+function usePeriodScopeRegistry(): PeriodScopeRegistry {
+  if (typeof window !== "undefined") return browserRegistry;
+  return useDmsState(PERIOD_SCOPES_STATE_KEY, createRegistry).value;
+}
 
 export function registerPeriodScope(
   id: string,
   state: ComputedRef<PeriodState>,
 ): () => void {
-  if (typeof window === "undefined") return noopUnregister;
-  const existing = periodScopeRegistry.get(id);
+  const registry = usePeriodScopeRegistry();
+  const existing = registry.scopes.get(id);
   if (existing) {
     existing.state = state;
     existing.refCount += 1;
   } else {
-    periodScopeRegistry.set(id, { state, refCount: 1 });
+    registry.scopes.set(id, { state, refCount: 1 });
   }
-  bumpRegistry();
+  registry.version.value += 1;
   return () => {
-    const entry = periodScopeRegistry.get(id);
+    const entry = registry.scopes.get(id);
     if (!entry) return;
     entry.refCount -= 1;
-    if (entry.refCount <= 0) periodScopeRegistry.delete(id);
-    bumpRegistry();
+    if (entry.refCount <= 0) registry.scopes.delete(id);
+    registry.version.value += 1;
   };
 }
 
 const warnedMissingScopes = new Set<string>();
 const MISSING_SCOPE_WARN_DELAY_MS = 250;
 
-function deferMissingScopeWarn(id: string): void {
+function deferMissingScopeWarn(
+  registry: PeriodScopeRegistry,
+  id: string,
+): void {
   if (warnedMissingScopes.has(id)) return;
   warnedMissingScopes.add(id);
   if (typeof window === "undefined") return;
   setTimeout(() => {
-    if (periodScopeRegistry.has(id)) return;
+    if (registry.scopes.has(id)) return;
     console.warn(
       `[dms] periodScope "${id}" is not registered. The consumer will run without period filtering. Add a PeriodSelector with id="${id}" to bind it.`,
     );
   }, MISSING_SCOPE_WARN_DELAY_MS);
 }
 
+function readPeriodScope(
+  registry: PeriodScopeRegistry,
+  id: string,
+): PeriodState | null {
+  void registry.version.value;
+  const entry = registry.scopes.get(id);
+  if (!entry) {
+    deferMissingScopeWarn(registry, id);
+    return null;
+  }
+  return entry.state.value;
+}
+
+/**
+ * The state of a period scope, `null` while no selector registers it.
+ *
+ * A server render reads it once, as the caller sets up: a selector that sets
+ * up later (further down the page) leaves the caller to the browser, whose
+ * 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.
+ */
 export function usePeriodScope(
   id: string | undefined,
 ): ComputedRef<PeriodState | null> {
-  return computed(() => {
-    if (!id) return null;
-    void registryVersion.value;
-    const entry = periodScopeRegistry.get(id);
-    if (!entry) {
-      deferMissingScopeWarn(id);
-      return null;
-    }
-    return entry.state.value;
-  });
+  if (!id) return computed(() => null);
+  const registry = usePeriodScopeRegistry();
+  if (typeof window !== "undefined")
+    return computed(() => readPeriodScope(registry, id));
+  const state = readPeriodScope(registry, id);
+  const resolvesAsBrowser = state !== null && resolvesPeriodsAsBrowser();
+  return computed(() => (resolvesAsBrowser ? state : null));
+}
+
+/**
+ * The preset of a period scope, `null` while no selector registers it: what
+ * a card's period badge names. A server render reads it once, as the caller
+ * sets up, like `usePeriodScope`, but whatever bounds the browser would
+ * resolve the period to: a preset is the same name on both sides, so the
+ * server prints the badge the browser hydrates.
+ */
+export function usePeriodScopePreset(
+  id: string | undefined,
+): ComputedRef<PeriodState["preset"] | null> {
+  if (!id) return computed(() => null);
+  const registry = usePeriodScopeRegistry();
+  if (typeof window !== "undefined")
+    return computed(() => readPeriodScope(registry, id)?.preset ?? null);
+  const preset = readPeriodScope(registry, id)?.preset ?? null;
+  return computed(() => preset);
 }
 
 /**

package/frontend-vue/layers/dms-core/app/composables/realtime/usePageRealtime.ts

@@ -10,6 +10,8 @@ export interface PageRealtimeApi {
   subscribe(topic: string, handler: RealtimeTopicHandler): () => void;
   sessionId: Ref<string | undefined>;
   pageId: Ref<string | undefined>;
+  /** The page's realtime topics, once the session is subscribed to it. */
+  pageTopics: Ref<string[]>;
 }
 
 interface PageClaim {
@@ -70,6 +72,7 @@ export function usePageRealtime(
     subscribe: user.subscribe,
     sessionId: user.sessionId,
     pageId: resolvedPageId,
+    pageTopics: user.pageTopics,
   };
 }
 

package/frontend-vue/layers/dms-core/app/composables/realtime/useUserRealtime.ts

@@ -51,12 +51,18 @@ export interface UserRealtimeApi {
    * announced in the greeting.
    */
   menuTopics: Ref<string[]>;
+  /**
+   * The realtime topics of the page this session is on, as its subscription
+   * answered them: an event on one means the page's data moved.
+   */
+  pageTopics: Ref<string[]>;
 }
 
 interface UserRealtimeState {
   sessionId: Ref<string | undefined>;
   pageId: Ref<string | undefined>;
   menuTopics: Ref<string[]>;
+  pageTopics: Ref<string[]>;
   appliedPageId: Ref<string | null>;
   handlers: Map<string, Set<RealtimeTopicHandler>>;
   snapshots: Map<string, RealtimeSnapshotEvent>;
@@ -230,22 +236,42 @@ const connectWithBackoff = (
   };
 };
 
+interface PageSubscriptionAnswer {
+  topics?: unknown;
+}
+
+/** The topics a page subscription answered, none when it answered none. */
+const readPageTopics = async (response: Response): Promise<string[]> => {
+  let answer: PageSubscriptionAnswer | null;
+  try {
+    answer = (await response.json()) as PageSubscriptionAnswer | null;
+  } catch {
+    return [];
+  }
+  const topics = answer?.topics;
+  return Array.isArray(topics)
+    ? topics.filter((topic): topic is string => typeof topic === "string")
+    : [];
+};
+
+/** Subscribes the session to `pageId`, or to no page; returns its topics. */
 const callPageEndpoint = async (
   state: UserRealtimeState,
   pageId: string | null,
   baseUrl: string,
-): Promise<void> => {
+): Promise<string[]> => {
   const sessionId = state.sessionId.value;
-  if (!sessionId) return;
+  if (!sessionId) return [];
   const headers: Record<string, string> = { [SESSION_HEADER]: sessionId };
   const url = pageId
     ? `${baseUrl}${REALTIME_SUBSCRIBE_PATH_PREFIX}${pageId}`
     : `${baseUrl}${REALTIME_UNSUBSCRIBE_PATH}`;
-  await fetch(url, {
+  const response = await fetch(url, {
     method: "POST",
     headers,
     credentials: "include",
   });
+  return pageId && response.ok ? readPageTopics(response) : [];
 };
 
 const applyDesiredPage = async (
@@ -256,11 +282,12 @@ const applyDesiredPage = async (
   const sessionId = state.sessionId.value;
   if (state.appliedPageId.value === desired) return;
   if (!sessionId) return;
-  await callPageEndpoint(state, desired, baseUrl);
+  const topics = await callPageEndpoint(state, desired, baseUrl);
   // A reconnect during the call replaced the session: the page is applied to
   // the dead one, and the new one still needs it.
   if (state.sessionId.value !== sessionId) return;
   state.appliedPageId.value = desired;
+  state.pageTopics.value = topics;
 };
 
 /**
@@ -288,6 +315,7 @@ const reconcilePage = (
 const resetSession = (state: UserRealtimeState): void => {
   state.sessionId.value = undefined;
   state.appliedPageId.value = null;
+  state.pageTopics.value = [];
   state.snapshots.clear();
 };
 
@@ -299,10 +327,12 @@ const buildApi = (): UserRealtimeApi => {
   const menuTopics = useDmsState<string[]>(MENU_TOPICS_STATE_KEY, () => []);
   const appliedPageId = ref<string | null>(null);
   const pageId = ref<string | undefined>(undefined);
+  const pageTopics = ref<string[]>([]);
   const state: UserRealtimeState = {
     sessionId,
     pageId,
     menuTopics,
+    pageTopics,
     appliedPageId,
     handlers: new Map(),
     snapshots: new Map(),
@@ -310,7 +340,7 @@ const buildApi = (): UserRealtimeApi => {
   };
 
   const config = useDmsRuntimeConfig();
-  const { loggedIn } = useUserSession();
+  const { loggedIn } = useDmsUserSession();
   const { refreshSession, redirectToAuth } = useSessionRecovery();
   const baseUrl = config.public.dms.baseURL as string;
 
@@ -366,7 +396,7 @@ const buildApi = (): UserRealtimeApi => {
     await reconcilePage(state, baseUrl);
   };
 
-  return { subscribe, setPage, sessionId, pageId, menuTopics };
+  return { subscribe, setPage, sessionId, pageId, menuTopics, pageTopics };
 };
 
 export function useUserRealtime(): UserRealtimeApi {

package/frontend-vue/layers/dms-core/app/composables/user/useUserRegionalPreferences.ts

@@ -27,7 +27,7 @@ function localeTimeFormat(locale: string): TimeFormatPreference {
  * the values themselves, such as a calendar's `weekStartsOn`.
  */
 export function useUserRegionalPreferences() {
-  const { user } = useUserSession<RegionalPreferenceFields>();
+  const { user } = useDmsUserSession<RegionalPreferenceFields>();
   const { locale } = useI18n();
 
   const preferences = computed<RegionalPreferences>(() =>

package/frontend-vue/layers/dms-core/app/plugins/async-data-scope.ts

@@ -0,0 +1,26 @@
+import { watch } from "vue";
+import {
+  defineDmsPlugin,
+  setDmsAsyncDataScope,
+  useDmsUserSession,
+} from "#dms/frontend-module";
+import {
+  asyncDataScopeOf,
+  type ScopedSession,
+} from "../build/utils/asyncDataScope";
+
+/**
+ * Keeps every `useApiData` / `useDmsAsyncData` key in the scope of the
+ * session's account and workspace, on both sides before the page renders:
+ * the browser finds the data the server transferred under the same scope,
+ * and a switch of account or workspace drops the data of the previous one
+ * instead of showing it under the new session.
+ */
+export default defineDmsPlugin(() => {
+  const { session } = useDmsUserSession<unknown, ScopedSession>();
+  const scope = () => asyncDataScopeOf(session.value);
+  setDmsAsyncDataScope(scope());
+  // One app per request on a server: its session never changes there.
+  if (typeof window === "undefined") return;
+  watch(scope, (next) => setDmsAsyncDataScope(next));
+});

package/frontend-vue/layers/dms-core/app/utils/pageRoutes.ts

@@ -0,0 +1,22 @@
+// Mirror of PAGE_ROUTE_PREFIX and pageRoutePath from
+// @antelopejs/interface-dms/page.
+
+/**
+ * Where the backend serves the routes a page controller declares, and its
+ * layout: under the DMS's own prefix, which the frontend server proxies. The
+ * page's own path is the page, never a backend route.
+ */
+export const PAGE_ROUTE_PREFIX = "/dms/pages";
+
+/**
+ * The backend path of a page's route, as the browser calls it:
+ * `pageRoutePath("/settings/user/security", "/sessions")` is
+ * `/dms/pages/settings/user/security/sessions`.
+ *
+ * @param pageSlug The page's path, such as `/settings/user/security`
+ * @param route The route below the page; none for the page's own route
+ */
+export function pageRoutePath(pageSlug: string, route = ""): string {
+  const path = `${PAGE_ROUTE_PREFIX}/${pageSlug}/${route}`.replace(/\/+/g, "/");
+  return path.endsWith("/") ? path.slice(0, -1) : path;
+}

package/frontend-vue/layers/dms-core/app/utils/regional.ts

@@ -37,6 +37,7 @@ export interface RegionalOptionsSettings {
 }
 
 type PreferencesSource = () => RegionalPreferences;
+type ReaderTimeZoneSource = () => string | null | undefined;
 
 const WEEK_STARTS: readonly number[] = [0, 1, 6];
 const TIME_FORMATS: readonly string[] = ["h23", "h12"];
@@ -73,6 +74,7 @@ const NUMERIC_DATE: Intl.DateTimeFormatOptions = {
 
 const knownTimeZones = new Map<string, boolean>();
 let preferencesSource: PreferencesSource | undefined;
+let readerTimeZoneSource: ReaderTimeZoneSource | undefined;
 
 /** Whether the runtime knows `timeZone` (an unknown one would throw in Intl). */
 export function isKnownTimeZone(timeZone: string): boolean {
@@ -125,6 +127,35 @@ export function setRegionalPreferencesSource(source: PreferencesSource): void {
   preferencesSource = source;
 }
 
+/**
+ * Tells a server render where to read the zone of the browser it renders for
+ * (its `dms-time-zone` cookie). Called on every read, so it resolves the
+ * request being rendered rather than a value captured once.
+ */
+export function setReaderTimeZoneSource(source: ReaderTimeZoneSource): void {
+  readerTimeZoneSource = source;
+}
+
+/**
+ * The time zone of the browser the page is for, when it is not the zone the
+ * code runs in: `undefined` in the browser, where it is; on a server, the zone
+ * the browser's cookie names, if this runtime knows it. Dates computed or
+ * written for the browser use it, so the server renders what the browser
+ * renders.
+ */
+export function readerTimeZone(): string | undefined {
+  if (typeof window !== "undefined") return undefined;
+  let zone: string | null | undefined;
+  try {
+    zone = readerTimeZoneSource?.();
+  } catch {
+    return undefined;
+  }
+  return zone && zone !== browserTimeZone() && isKnownTimeZone(zone)
+    ? zone
+    : undefined;
+}
+
 /** The current user's preferences; none outside an application. */
 export function currentRegionalPreferences(): RegionalPreferences {
   try {
@@ -195,8 +226,10 @@ export function withRegionalOptions(
   let result = preferences.dateFormat
     ? DATE_FORMAT_REWRITES[preferences.dateFormat](options)
     : { ...options };
-  if (preferences.timeZone && !settings.keepLocalZone && !result.timeZone) {
-    result = { ...result, timeZone: preferences.timeZone };
+  const timeZone =
+    (!settings.keepLocalZone && preferences.timeZone) || readerTimeZone();
+  if (timeZone && !result.timeZone) {
+    result = { ...result, timeZone };
   }
   const statesClock =
     result.hour12 !== undefined || result.hourCycle !== undefined;
@@ -238,7 +271,7 @@ export function regionalDayNumber(
   preferences: RegionalPreferences = currentRegionalPreferences(),
 ): number {
   const parts = new Intl.DateTimeFormat("en-US", {
-    timeZone: preferences.timeZone,
+    timeZone: preferences.timeZone ?? readerTimeZone(),
     year: "numeric",
     month: "numeric",
     day: "numeric",

package/frontend-vue/layers/dms-core/app/utils/trailingDeduper.ts

@@ -1,5 +1,11 @@
 export interface TrailingDeduper {
   run(task: () => Promise<void>): Promise<void>;
+  /**
+   * Joins the run in flight, or starts one: for a caller that needs a result
+   * rather than a fresh one, such as a first load, which a run started
+   * before it answers as well as its own would.
+   */
+  join(task: () => Promise<void>): Promise<void>;
 }
 
 /**
@@ -38,5 +44,8 @@ export function createTrailingDeduper(): TrailingDeduper {
     return trailing;
   };
 
-  return { run };
+  const join = (task: () => Promise<void>): Promise<void> =>
+    inFlight ?? run(task);
+
+  return { run, join };
 }