@antelopejs/dms 0.8.3 → 0.9.0

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

package/frontend-vue/layers/dms-core/shared/types/app-config.ts

@@ -12,6 +12,51 @@ export interface DmsLogoSources {
   dark: string;
 }
 
+/** The logos of an instance, one per place it is drawn. */
+export interface DmsBrandingLogo {
+  /** The expanded sidebar and the auth pages. */
+  default: DmsLogoSources;
+  /** The icon-only sidebar. */
+  collapsed: DmsLogoSources;
+  /**
+   * The header of the emails, in place of `default.light`. A PNG or a JPEG:
+   * Gmail and Outlook refuse SVG, and an email leaves out a logo they cannot
+   * load. `dark` goes to the mail clients that follow the reader's dark mode.
+   */
+  email?: DmsLogoSources;
+  /**
+   * The browser tab icon. `light` and `dark` follow the operating system's
+   * color scheme, not the dashboard's color mode: the browser draws the tab
+   * outside the page.
+   */
+  favicon?: DmsLogoSources;
+}
+
+/**
+ * The Tailwind palette each Nuxt UI color role resolves to (`ui.colors`): a
+ * stock palette name, or one whose `--color-<name>-*` shades a stylesheet
+ * declares.
+ */
+export interface DmsUiColors {
+  primary: string;
+  secondary: string;
+  neutral: string;
+  success: string;
+  warning: string;
+  error: string;
+  info: string;
+}
+
+/**
+ * The DMS's own logos and palettes, kept whatever a layer sets in their place,
+ * so a tool can preview a return to the DMS look (the builder's theme editor).
+ * A layer overrides `branding.logo` and `ui.colors`, never these.
+ */
+export interface DmsBrandingDefaults {
+  logo: DmsBrandingLogo;
+  colors: DmsUiColors;
+}
+
 /**
  * What the footer of the public and auth pages shows besides its links
  * (`registerFooterLink`).
@@ -33,11 +78,10 @@ export interface DmsBrandingConfig {
    * Absent when an instance ships no logo of its own; the layer's app config
    * supplies the AntelopeJS one by default.
    */
-  logo?: {
-    default: DmsLogoSources;
-    collapsed: DmsLogoSources;
-  };
+  logo?: DmsBrandingLogo;
   footer?: DmsFooterConfig;
+  /** Supplied by the DMS layout layer's app config. */
+  defaults?: DmsBrandingDefaults;
 }
 
 export interface DmsAppConfig {

package/frontend-vue/layers/dms-layout/app/app.config.ts

@@ -1,3 +1,7 @@
+import type {
+  DmsBrandingLogo,
+  DmsUiColors,
+} from "#dms-core/shared/types/app-config";
 import { EYEBROW_CLASS } from "#dms-ui/app/build/utils/eyebrow";
 import { actionsTheme } from "./theme/actions";
 import { dataTheme } from "./theme/data";
@@ -8,21 +12,44 @@ import {
 } from "./theme/navigation";
 import { surfacesTheme } from "./theme/surfaces";
 
+const ANTELOPE_ICON = "/images/antelope-logo/icon.svg";
+
+// The palettes and logos are built afresh for each place that holds them: a
+// merged app config keeps the very objects no layer overrides, so a live edit
+// of `ui.colors` or `branding.logo` would otherwise rewrite
+// `branding.defaults` too.
+
+function dmsColors(): DmsUiColors {
+  return {
+    primary: "dms",
+    // The AI accent of the v2 design.
+    secondary: "violet",
+    neutral: "neutral",
+    // Design semantic hexes map exactly onto these Tailwind palettes:
+    // success #10b981 (emerald), warning #f59e0b (amber),
+    // error #ef4444 (red), info #06b6d4 (cyan).
+    success: "emerald",
+    warning: "amber",
+    error: "red",
+    info: "cyan",
+  };
+}
+
+// No email logo: the AntelopeJS logos are SVG, which mail clients refuse.
+function dmsLogo(): DmsBrandingLogo {
+  return {
+    default: {
+      light: "/images/antelope-logo/light.svg",
+      dark: "/images/antelope-logo/dark.svg",
+    },
+    collapsed: { light: ANTELOPE_ICON, dark: ANTELOPE_ICON },
+    favicon: { light: ANTELOPE_ICON, dark: ANTELOPE_ICON },
+  };
+}
+
 export default {
   ui: {
-    colors: {
-      primary: "dms",
-      // The AI accent of the v2 design.
-      secondary: "violet",
-      neutral: "neutral",
-      // Design semantic hexes map exactly onto these Tailwind palettes:
-      // success #10b981 (emerald), warning #f59e0b (amber),
-      // error #ef4444 (red), info #06b6d4 (cyan).
-      success: "emerald",
-      warning: "amber",
-      error: "red",
-      info: "cyan",
-    },
+    colors: dmsColors(),
     icons: {
       arrowDown: "i-ph-arrow-down-light",
       arrowLeft: "i-ph-arrow-left-light",
@@ -184,16 +211,8 @@ export default {
     },
   },
   branding: {
-    logo: {
-      default: {
-        light: "/images/antelope-logo/light.svg",
-        dark: "/images/antelope-logo/dark.svg",
-      },
-      collapsed: {
-        light: "/images/antelope-logo/icon.svg",
-        dark: "/images/antelope-logo/icon.svg",
-      },
-    },
+    logo: dmsLogo(),
+    defaults: { logo: dmsLogo(), colors: dmsColors() },
     footer: {
       copyright: "Antelope",
       githubStar: true,