@antelopejs/dms 0.8.3 → 0.9.1

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

@@ -0,0 +1,47 @@
+/** The part of the session the data scope follows. */
+export interface ScopedSession {
+  accountId?: string;
+  activeTenantId?: string;
+}
+
+const HASH_SEED_LOW = 0xdeadbeef;
+const HASH_SEED_HIGH = 0x41c6ce57;
+const HASH_MULTIPLIER_LOW = 2_654_435_761;
+const HASH_MULTIPLIER_HIGH = 1_597_334_677;
+const HASH_MIX_LOW = 2_246_822_507;
+const HASH_MIX_HIGH = 3_266_489_909;
+const HIGH_WORD = 2 ** 32;
+const HIGH_BITS_MASK = 2_097_151;
+const RADIX = 36;
+
+/**
+ * A 53-bit digest of `text` (cyrb53): the same in a server render and in the
+ * browser, and synchronous, so the scope is set before the page renders.
+ * Not a secret: it only keeps the identifiers out of the page.
+ */
+function digest(text: string): string {
+  let low = HASH_SEED_LOW;
+  let high = HASH_SEED_HIGH;
+  for (let index = 0; index < text.length; index++) {
+    const code = text.charCodeAt(index);
+    low = Math.imul(low ^ code, HASH_MULTIPLIER_LOW);
+    high = Math.imul(high ^ code, HASH_MULTIPLIER_HIGH);
+  }
+  low = Math.imul(low ^ (low >>> 16), HASH_MIX_LOW);
+  low ^= Math.imul(high ^ (high >>> 13), HASH_MIX_HIGH);
+  high = Math.imul(high ^ (high >>> 16), HASH_MIX_LOW);
+  high ^= Math.imul(low ^ (low >>> 13), HASH_MIX_HIGH);
+  return (HIGH_WORD * (HIGH_BITS_MASK & high) + (low >>> 0)).toString(RADIX);
+}
+
+/**
+ * The scope the async data of a session is kept under: a digest of its
+ * account and workspace, or none when signed out. The same key read by
+ * another account, or in another workspace, is another entry.
+ */
+export function asyncDataScopeOf(
+  session: ScopedSession | null | undefined,
+): string | undefined {
+  if (!session?.accountId) return undefined;
+  return digest(`${session.accountId}\n${session.activeTenantId ?? ""}`);
+}

package/frontend-vue/layers/dms-core/app/build/utils/permission-preview.ts

@@ -1,3 +1,4 @@
+import { pageRoutePath } from "#dms-core/app/utils/pageRoutes";
 // "Preview as role" (roles editor): the shapes the preview endpoint answers
 // with, how a preview session travels from the editor tab to the preview tab,
 // and which requests a preview tab may still send. Pure: no Vue, no window.
@@ -9,7 +10,7 @@ export type PermissionPreviewBlock =
 
 export type PermissionPreviewState = PermissionPreviewBlock["state"];
 
-/** Answer of `POST /settings/workspace/roles/preview`. */
+/** Answer of `POST /dms/pages/settings/workspace/roles/preview`. */
 export interface PermissionPreviewResult {
   page: { fullId: string; displayName: string; hidden: boolean } | null;
   /** Blocks keyed by layout path (component key, then child ids). */
@@ -44,7 +45,10 @@ export interface PermissionPreviewSession {
 }
 
 /** Endpoint the preview tab asks; a POST, so the request guard lets it through. */
-export const PERMISSION_PREVIEW_ENDPOINT = "/settings/workspace/roles/preview";
+export const PERMISSION_PREVIEW_ENDPOINT = pageRoutePath(
+  "/settings/workspace/roles",
+  "/preview",
+);
 /** Query parameter that hands a preview session to a new tab. */
 export const PERMISSION_PREVIEW_QUERY_KEY = "dms-preview";
 /** `localStorage` key prefix of the sessions the editor shares with its preview tabs. */

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

@@ -0,0 +1,148 @@
+import type {
+  DmsAsyncDataKey,
+  DmsAsyncDataResult,
+  DmsPagedDataResult,
+  UseAsyncDataOptions,
+  UseDmsPagedDataOptions,
+  UseFetchOptions,
+} from "#dms/frontend-module";
+import type { MaybeRefOrGetter } from "vue";
+
+/** The authenticated fetch `useAuthFetch` returns. */
+type AuthFetch = ReturnType<typeof useAuthFetch>["$authFetch"];
+
+/** What a handler loading API data receives. */
+export interface ApiDataContext {
+  /** `useAuthFetch`'s fetch: the session retry, the language and realtime headers. */
+  $authFetch: AuthFetch;
+  /** Aborted once the result is no longer wanted: pass it to each request. */
+  signal: AbortSignal;
+}
+
+export type ApiDataHandler<T> = (context: ApiDataContext) => Promise<T>;
+
+/** `useDmsFetch`'s options, the fetch function aside: it is `$authFetch`. */
+export type UseApiDataOptions<T> = Omit<UseFetchOptions<T>, "$fetch">;
+
+/** A backend URL to read, or nothing to read while it is null or undefined. */
+export type ApiDataRequest = MaybeRefOrGetter<string | null | undefined>;
+
+/**
+ * What `useApiData` returns: `data`, `status`, `pending`, `error`, the `key`
+ * the data is loaded under, `placeholder` (a reactive request still showing
+ * the previous answer), `execute()`, `refresh()` and `clear()`. Usable at
+ * once, or awaited until the data is there.
+ */
+export type ApiDataResult<T> = DmsAsyncDataResult<T>;
+
+/**
+ * Reads backend data for a component: the one way a module loads what it
+ * renders. A server render waits for it and hands it to the browser with the
+ * page, which then does not ask again; the callers of one request share it.
+ * Data read before shows at once and is read again in the background on each
+ * mount (stale while revalidate).
+ *
+ * - `useApiData(url, options)` reads one URL, like Nuxt's `useFetch`. The URL,
+ *   `method`, `query`, `params` and `body` may be refs or getters, read again
+ *   for each request: the data follows them. A URL that is null or undefined
+ *   reads nothing until it has a value.
+ * - `useApiData(key, handler, options)` loads what the handler returns, like
+ *   Nuxt's `useAsyncData`: for data made of several requests. The handler
+ *   receives `$authFetch` and the `signal` to pass to each request.
+ *
+ * Requests go through `$authFetch` (session retry, language and realtime
+ * headers), and the data is kept per account and workspace: a switch of
+ * either reads it again. The options are the renderer's:
+ *
+ * - `lazy` spares a client navigation the wait; `server: false` leaves the
+ *   data to the browser (for what only the browser knows).
+ * - `immediate: false` waits for `execute()`: a dialog or a drawer reads
+ *   what it shows once it opens.
+ * - `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 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.
+ * - `data` is a shallow ref: replace the value to change it, or pass
+ *   `deep: true`.
+ *
+ * A write stays an `$authFetch` call; once it is done, the page's refresh
+ * reads what changed, or `useDmsData(key)` puts its answer in the data in
+ * place (the URL form names its key with `key`).
+ */
+export function useApiData<T>(
+  url: ApiDataRequest,
+  options?: UseApiDataOptions<T>,
+): ApiDataResult<T>;
+export function useApiData<T>(
+  key: MaybeRefOrGetter<DmsAsyncDataKey>,
+  handler: ApiDataHandler<T>,
+  options?: UseAsyncDataOptions<T>,
+): ApiDataResult<T>;
+export function useApiData<T>(
+  source: ApiDataRequest,
+  handlerOrOptions?: ApiDataHandler<T> | UseApiDataOptions<T>,
+  options?: UseAsyncDataOptions<T>,
+): ApiDataResult<T> {
+  const { $authFetch } = useAuthFetch();
+  if (typeof handlerOrOptions === "function")
+    return useDmsAsyncData<T>(
+      source,
+      ({ signal }) => handlerOrOptions({ $authFetch, signal }),
+      options,
+    );
+  return useDmsFetch<T>(source, {
+    ...handlerOrOptions,
+    $fetch: $authFetch as UseFetchOptions<T>["$fetch"],
+  });
+}
+
+/** What a handler reading one page of API data receives. */
+export interface ApiPagedDataContext<TCursor> extends ApiDataContext {
+  /** The page to read: `initialCursor` (none by default) for the first one. */
+  cursor: TCursor | undefined;
+  /** Its position, from `0`. */
+  index: number;
+}
+
+export type ApiPagedDataHandler<TPage, TCursor> = (
+  context: ApiPagedDataContext<TCursor>,
+) => Promise<TPage>;
+
+/**
+ * What `useApiPagedData` returns: `useApiData`'s result over the pages
+ * loaded, with `pages`, `hasMore`, `loadingMore` and `loadMore()`.
+ */
+export type ApiPagedDataResult<TPage, TCursor> = DmsPagedDataResult<
+  TPage,
+  TCursor
+>;
+
+/**
+ * Reads a backend list page by page under one key: a "load more" button, an
+ * infinite list. The handler reads the page at `cursor` through `$authFetch`;
+ * `nextCursor(page, pages)` gives the next page's cursor, or `null` at the
+ * end. A server render shows the first page, `loadMore()` appends the next
+ * one, and a revalidation (a mount, the page's refreshes, the polling)
+ * reads every page loaded so far again. Put what filters the list in the
+ * key (a ref or a getter for it): a new key starts from its first page.
+ *
+ * @param key The key, or a ref or getter for it
+ * @param handler Reads one page
+ * @param options `nextCursor`, `initialCursor` and `useApiData`'s options
+ */
+export function useApiPagedData<TPage, TCursor = unknown>(
+  key: MaybeRefOrGetter<DmsAsyncDataKey>,
+  handler: ApiPagedDataHandler<TPage, TCursor>,
+  options: UseDmsPagedDataOptions<TPage, TCursor>,
+): ApiPagedDataResult<TPage, TCursor> {
+  const { $authFetch } = useAuthFetch();
+  return useDmsPagedData<TPage, TCursor>(
+    key,
+    ({ cursor, index, signal }) =>
+      handler({ $authFetch, cursor, index, signal }),
+    options,
+  );
+}

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

@@ -1,5 +1,3 @@
-import type { UseFetchOptions } from "#dms/frontend-module";
-
 export const CONTENT_LANGUAGE_HEADER = "x-content-language";
 
 const RETRY_HEADER = "x-auth-retry";
@@ -38,7 +36,7 @@ function isUnauthorized(error: unknown): boolean {
 }
 
 export const useAuthFetch = () => {
-  const { loggedIn: isLoggedIn } = useUserSession();
+  const { loggedIn: isLoggedIn } = useDmsUserSession();
   const { refreshSession, reconcileSession, redirectToAuth } =
     useSessionRecovery();
   const config = useDmsRuntimeConfig();
@@ -51,10 +49,12 @@ export const useAuthFetch = () => {
 
   const baseFetch = $fetch.create({
     baseURL: config.public.dms.baseURL,
-    headers: {
-      [CONTENT_LANGUAGE_HEADER]: dmsApp.$i18n.locale.value,
-    },
     onRequest({ options }) {
+      // Read as each request leaves: a `$authFetch` kept across a language
+      // change asks in the new language. A header the caller sets wins.
+      if (!options.headers.has(CONTENT_LANGUAGE_HEADER)) {
+        options.headers.set(CONTENT_LANGUAGE_HEADER, dmsApp.$i18n.locale.value);
+      }
       if (realtimeSessionId.value) {
         options.headers.set(REALTIME_SESSION_HEADER, realtimeSessionId.value);
       }
@@ -117,18 +117,5 @@ export const useAuthFetch = () => {
     baseFetch.raw(request, options),
   ) as AuthFetch["raw"];
 
-  function useFetchAuth<T>(
-    url: string | (() => string),
-    options?: UseFetchOptions<T>,
-  ) {
-    return useDmsFetch(url, {
-      ...options,
-      $fetch: $authFetch,
-    });
-  }
-
-  return {
-    $authFetch,
-    useFetchAuth,
-  };
+  return { $authFetch };
 };

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

@@ -1,14 +1,14 @@
 /**
  * Global reactive access to the signed-in user's identity (name, email, ...).
  *
- * `user` is the shared session state from `useUserSession`, so every consumer
+ * `user` is the shared session state from `useDmsUserSession`, so every consumer
  * (header menu, switch-account page, ...) re-renders as soon as it changes.
  * `refresh` re-fetches the session through the frontend server session hook
  * pulls a fresh `/api/auth/me`) and syncs the stored multi-account entry, so a
  * profile edit propagates immediately without re-logging in.
  */
 export function useCurrentUser() {
-  const { user, fetch: refreshSession } = useUserSession<User>();
+  const { user, fetch: refreshSession } = useDmsUserSession<User>();
   const { syncActiveAccount } = useMultiAccount();
 
   async function refresh(): Promise<void> {

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

@@ -116,13 +116,23 @@ async function requestAccountSwitch(account: StoredAccount) {
   account.isExpired = false;
 }
 
-async function refreshSessionSurfaces(refreshUser: () => Promise<unknown>) {
+/**
+ * Moves what the browser shows to the session it switched to. The session
+ * read again moves the data scope (the previous account's data is dropped)
+ * and drops the prefetched pages; the site layout and the page come back
+ * through Inertia, whose once prop is keyed on the account and workspace.
+ *
+ * @internal
+ */
+export async function refreshSessionSurfaces(
+  refreshUser: () => Promise<unknown>,
+): Promise<void> {
   await refreshUser();
 
-  const { refresh: refreshSiteLayout } = useSiteLayout();
+  const { resync: reloadSiteLayout } = useSiteLayout();
   const { clear: clearPermissions } = usePermissions();
   clearPermissions();
-  await refreshSiteLayout();
+  await reloadSiteLayout();
 }
 
 export async function validateAccount(account: StoredAccount) {
@@ -187,8 +197,11 @@ function createValidateAllAccounts(
 
 export function useMultiAccount() {
   const accounts = useAccountsStorage();
-  const { user, session, fetch: refreshUser } =
-    useUserSession<User, BrowserSession>();
+  const {
+    user,
+    session,
+    fetch: refreshUser,
+  } = useDmsUserSession<User, BrowserSession>();
 
   const getActiveAccount = (): StoredAccount | undefined =>
     buildActiveAccount(

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

@@ -9,11 +9,29 @@ interface PermissionsState {
   fetchGeneration: Ref<number>;
 }
 
+// The set a server render loads (the `auth` middleware preloads it before the
+// page renders) is the one the page renders with: the browser starts from it
+// rather than asking again, and its age keeps counting from the server's load.
+// The generation only guards the runs in flight of one side.
+const TRANSFERRED = { transfer: true };
+
 function usePermissionsState(): PermissionsState {
   return {
-    permissions: useDmsState<Set<string>>("dms-user-permissions", () => new Set()),
-    isLoaded: useDmsState<boolean>("dms-permissions-loaded", () => false),
-    lastFetchTime: useDmsState<number>("dms-permissions-lastFetch", () => 0),
+    permissions: useDmsState<Set<string>>(
+      "dms-user-permissions",
+      () => new Set(),
+      TRANSFERRED,
+    ),
+    isLoaded: useDmsState<boolean>(
+      "dms-permissions-loaded",
+      () => false,
+      TRANSFERRED,
+    ),
+    lastFetchTime: useDmsState<number>(
+      "dms-permissions-lastFetch",
+      () => 0,
+      TRANSFERRED,
+    ),
     fetchGeneration: useDmsState<number>("dms-permissions-gen", () => 0),
   };
 }
@@ -30,15 +48,25 @@ function createFetchPermissions(state: PermissionsState) {
   };
 
   // A refetch asked while one is in flight gets its own pass instead of the
-  // older response, so an invalidation is never swallowed. Scoped to the DMS app
+  // older response, so an invalidation is never swallowed. Scoped to the DMS
   // app, so concurrent server-rendered requests never share a pass.
   const deduper = useTrailingDeduper("permissions");
-  return (): Promise<void> => deduper.run(runFetch);
+  const fetchPermissions = (): Promise<void> => deduper.run(runFetch);
+  // A caller that only needs a set has nothing to invalidate: it joins the
+  // load in flight instead of queueing a second one.
+  const loadPermissions = async (): Promise<void> => {
+    if (state.isLoaded.value) return;
+    await deduper.join(runFetch);
+    // The run it joined was started before a `clear()` (another account):
+    // its answer was dropped, and this caller still needs one.
+    if (!state.isLoaded.value) await deduper.join(runFetch);
+  };
+  return { fetchPermissions, loadPermissions };
 }
 
 export function usePermissions() {
   const state = usePermissionsState();
-  const fetchPermissions = createFetchPermissions(state);
+  const { fetchPermissions, loadPermissions } = createFetchPermissions(state);
 
   async function refreshIfStale() {
     const elapsed = Date.now() - state.lastFetchTime.value;
@@ -66,6 +94,7 @@ export function usePermissions() {
     permissions: state.permissions,
     isLoaded: state.isLoaded,
     fetchPermissions,
+    loadPermissions,
     refreshIfStale,
     hasPermission,
     clear,

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

@@ -5,7 +5,7 @@ const IN_FLIGHT_REFRESH_KEY = "__dmsAuthInFlightRefresh";
 
 export const useSessionRecovery = () => {
   const dmsApp = useDmsApp();
-  const { loggedIn, fetch: fetchSession } = useUserSession();
+  const { loggedIn, fetch: fetchSession } = useDmsUserSession();
   // useDmsRoute() must not be called here: this composable runs inside route
   // middleware (via useAuthFetch), where the DMS runtime warns that useDmsRoute is
   // misleading. Resolve the route lazily from the router instead.

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

@@ -1,16 +1,25 @@
+import { readerClock } from "./periodClock";
 import type { PeriodComparison, PeriodRange } from "./types";
 
 const NON_OVERLAP_GAP_MS = 1;
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
+// In the reader's calendar (`readerClock`), as the range was resolved.
 function isLocalMidnight(date: Date): boolean {
-  return (
-    date.getHours() === 0 &&
-    date.getMinutes() === 0 &&
-    date.getSeconds() === 0 &&
-    date.getMilliseconds() === 0
-  );
+  const { hours, minutes, seconds, milliseconds } = readerClock().wall(date);
+  return hours === 0 && minutes === 0 && seconds === 0 && milliseconds === 0;
+}
+
+/** `date` moved by whole calendar days and years, its time of day kept. */
+function shiftCalendar(date: Date, days: number, years: number): Date {
+  const clock = readerClock();
+  const wall = clock.wall(date);
+  return clock.instant({
+    ...wall,
+    year: wall.year + years,
+    day: wall.day + days,
+  });
 }
 
 /** A range of whole local days: midnight to the last millisecond of a day. */
@@ -27,10 +36,8 @@ function shiftPreviousPeriod(range: PeriodRange): PeriodRange {
   if (isWholeDayRange(range)) {
     const end = range.to.getTime() + NON_OVERLAP_GAP_MS;
     const days = Math.round((end - range.from.getTime()) / MS_PER_DAY);
-    const from = new Date(range.from);
-    from.setDate(from.getDate() - days);
     return {
-      from,
+      from: shiftCalendar(range.from, -days, 0),
       to: new Date(range.from.getTime() - NON_OVERLAP_GAP_MS),
     };
   }
@@ -44,11 +51,10 @@ function shiftPreviousPeriod(range: PeriodRange): PeriodRange {
 }
 
 function shiftPreviousYear(range: PeriodRange): PeriodRange {
-  const previousFrom = new Date(range.from);
-  previousFrom.setFullYear(previousFrom.getFullYear() - 1);
-  const previousTo = new Date(range.to);
-  previousTo.setFullYear(previousTo.getFullYear() - 1);
-  return { from: previousFrom, to: previousTo };
+  return {
+    from: shiftCalendar(range.from, 0, -1),
+    to: shiftCalendar(range.to, 0, -1),
+  };
 }
 
 const COMPARISON_RESOLVERS: Record<

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

@@ -0,0 +1,121 @@
+import { readerTimeZone } from "../../utils/regional";
+
+/** The fields of a wall-clock time, months counted from 0 as `Date` does. */
+export interface WallTime {
+  year: number;
+  month: number;
+  day: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+  milliseconds: number;
+}
+
+/**
+ * A calendar in one time zone: the wall-clock time of an instant, and the
+ * instant of a wall-clock time. Fields out of range roll over as `Date`'s do
+ * (day 0 is the last day of the month before).
+ */
+export interface PeriodClock {
+  wall(date: Date): WallTime;
+  instant(wall: WallTime): Date;
+}
+
+/** The calendar of the zone the code runs in, through `Date`'s own methods. */
+export const localClock: PeriodClock = {
+  wall: (date) => ({
+    year: date.getFullYear(),
+    month: date.getMonth(),
+    day: date.getDate(),
+    hours: date.getHours(),
+    minutes: date.getMinutes(),
+    seconds: date.getSeconds(),
+    milliseconds: date.getMilliseconds(),
+  }),
+  instant: (wall) =>
+    new Date(
+      wall.year,
+      wall.month,
+      wall.day,
+      wall.hours,
+      wall.minutes,
+      wall.seconds,
+      wall.milliseconds,
+    ),
+};
+
+const WALL_PARTS = ["year", "month", "day", "hour", "minute", "second"];
+const zonedFormatters = new Map<string, Intl.DateTimeFormat>();
+
+function zonedFormatter(timeZone: string): Intl.DateTimeFormat {
+  let formatter = zonedFormatters.get(timeZone);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "numeric",
+      day: "numeric",
+      hour: "numeric",
+      minute: "numeric",
+      second: "numeric",
+    });
+    zonedFormatters.set(timeZone, formatter);
+  }
+  return formatter;
+}
+
+function utcOf(wall: WallTime): number {
+  return Date.UTC(
+    wall.year,
+    wall.month,
+    wall.day,
+    wall.hours,
+    wall.minutes,
+    wall.seconds,
+    wall.milliseconds,
+  );
+}
+
+/** The calendar of `timeZone`, through `Intl` whatever zone the code runs in. */
+export function zonedClock(timeZone: string): PeriodClock {
+  const wall = (date: Date): WallTime => {
+    const parts = Object.fromEntries(
+      zonedFormatter(timeZone)
+        .formatToParts(date)
+        .filter((part) => WALL_PARTS.includes(part.type))
+        .map((part) => [part.type, Number(part.value)]),
+    );
+    return {
+      year: parts.year!,
+      month: parts.month! - 1,
+      day: parts.day!,
+      hours: parts.hour!,
+      minutes: parts.minute!,
+      seconds: parts.second!,
+      milliseconds: date.getUTCMilliseconds(),
+    };
+  };
+  // The zone's offset at an instant: how far its wall clock is from UTC.
+  const offsetAt = (time: number) => utcOf(wall(new Date(time))) - time;
+  return {
+    wall,
+    instant: (target) => {
+      const asUtc = utcOf(target);
+      // Twice: the offset at the first guess is the right one unless the
+      // guess and the answer fall on either side of a daylight saving change.
+      const guess = asUtc - offsetAt(asUtc);
+      return new Date(asUtc - offsetAt(guess));
+    },
+  };
+}
+
+/**
+ * The calendar a period is resolved in: the reader's browser's zone. That is
+ * the code's own in the browser; on a server, the zone the browser's cookie
+ * names (see `readerTimeZone`), or the server's own without one.
+ */
+export function readerClock(): PeriodClock {
+  const zone = readerTimeZone();
+  return zone ? zonedClock(zone) : localClock;
+}

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

@@ -0,0 +1,42 @@
+import { getCurrentInstance } from "vue";
+
+/**
+ * The instant a server render resolves its periods from, handed to the
+ * browser with the page.
+ */
+const RENDER_NOW_STATE_KEY = "dms-period-render-now";
+
+/**
+ * Whether the component setting up is hydrating the server's HTML: Vue binds
+ * a hydrating component's vnode to its server-rendered node before its setup
+ * runs, where a fresh mount has no node yet.
+ */
+function isHydratingSetup(): boolean {
+  return !!getCurrentInstance()?.vnode.el;
+}
+
+/**
+ * The instant a period set up now resolves from, or `null` for the clock's.
+ *
+ * A server render resolves every period of the request from one instant,
+ * which it transfers; the browser hydrating that render resolves from the
+ * same one, so a relative preset (`last-24h`) or a calendar one read across
+ * midnight keeps the bounds, key and labels the server rendered, and nothing
+ * reads again on hydration. Anywhere else (a client navigation, a call
+ * outside a component) it is `null`: the period follows the clock.
+ */
+export function periodRenderNow(): Date | null {
+  if (!getCurrentInstance()) return null;
+  if (typeof window === "undefined") {
+    const now = useDmsState<number>(RENDER_NOW_STATE_KEY, () => Date.now(), {
+      transfer: true,
+    });
+    return new Date(now.value);
+  }
+  if (!isHydratingSetup()) return null;
+  const transferred = useDmsState<number | null>(
+    RENDER_NOW_STATE_KEY,
+    () => null,
+  ).value;
+  return typeof transferred === "number" ? new Date(transferred) : null;
+}

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

@@ -0,0 +1,31 @@
+import type { Ref } from "vue";
+import { isKnownTimeZone } from "../../utils/regional";
+
+/**
+ * The browser's time zone, kept in a cookie for a server render: a period is
+ * made of calendar days in the browser's zone, which the server has no other
+ * way to know.
+ */
+export const TIME_ZONE_COOKIE = "dms-time-zone";
+const TIME_ZONE_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+
+/** The browser's time zone as its cookie holds it; `null` before it is written. */
+export function useTimeZoneCookie(): Ref<string | null> {
+  return useDmsCookie<string | null>(TIME_ZONE_COOKIE, {
+    default: () => null,
+    maxAge: TIME_ZONE_COOKIE_MAX_AGE,
+    path: "/",
+    sameSite: "lax",
+  });
+}
+
+/**
+ * Whether this render resolves a period as the browser does. The browser
+ * always does; a server once the browser's cookie names its time zone, in
+ * which the presets then resolve (`readerClock`).
+ */
+export function resolvesPeriodsAsBrowser(): boolean {
+  if (typeof window !== "undefined") return true;
+  const zone = useTimeZoneCookie().value;
+  return !!zone && isKnownTimeZone(zone);
+}