@antelopejs/dms 0.8.3 → 0.9.0

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);
+}

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,
   };
 }