@declarion/react 0.1.91 → 0.1.92

package/dist-lib/embed/protocol.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The `source` discriminator stamped on every embed frame. The host SDK and
+ * the iframe both filter inbound messages on this value so unrelated
+ * `postMessage` traffic (browser extensions, other widgets) is ignored.
+ */
+export declare const EMBED_MESSAGE_SOURCE: "declarion-embed";
+/**
+ * The protocol version. Bumped only on a breaking envelope/payload change.
+ * The host SDK warns when its version and the iframe's version differ.
+ */
+export declare const EMBED_PROTOCOL_VERSION: 1;
+/**
+ * Every protocol message `type`. The object key is the camelCase name used in
+ * code; the value is the on-wire string. Events (iframe -> host) are past
+ * tense; commands (host -> iframe) are imperative - see the naming contract
+ * at the top of this file.
+ */
+export declare const EMBED_MESSAGE_TYPES: {
+    /** iframe -> host: SDK mounted, requests the first token. */
+    readonly ready: "ready";
+    /** host -> iframe: deliver or refresh the embed token. */
+    readonly setToken: "set-token";
+    /** iframe -> host: token rejected or near expiry. */
+    readonly tokenExpired: "token-expired";
+    /** iframe -> host: the iframe must be reloaded. */
+    readonly reloadRequired: "reload-required";
+    /** iframe -> host: embed content height changed. */
+    readonly resized: "resized";
+    /** iframe -> host: `self` mode internal navigation happened. */
+    readonly navigated: "navigated";
+    /** iframe -> host: `delegated` mode navigation requested, iframe stayed. */
+    readonly navigationRequested: "navigation-requested";
+    /** iframe -> host: the embedded screen's unsaved-edits state flipped. */
+    readonly dirtyChanged: "dirty-changed";
+    /** host -> iframe: drive the iframe to a screen (deep-linking). */
+    readonly navigate: "navigate";
+    /** host -> iframe: runtime theme switch. */
+    readonly setTheme: "set-theme";
+};
+/** The union of all on-wire message `type` strings. */
+export type EmbedMessageType = (typeof EMBED_MESSAGE_TYPES)[keyof typeof EMBED_MESSAGE_TYPES];
+/** `ready` payload: empty - the frame itself is the signal. */
+export type EmbedReadyPayload = Record<string, never>;
+/** `set-token` payload: the embed token and its absolute expiry. */
+export interface EmbedSetTokenPayload {
+    /** The scoped, refresh-less embed JWT. */
+    readonly token: string;
+    /** RFC 3339 expiry timestamp of the token. */
+    readonly expires_at: string;
+}
+/** `token-expired` payload: empty - the host re-mints via `getToken`. */
+export type EmbedTokenExpiredPayload = Record<string, never>;
+/** `reload-required` payload: a human-readable reason for the reload. */
+export interface EmbedReloadRequiredPayload {
+    /** Why the iframe must be reloaded (asset drift, terminal auth failure). */
+    readonly reason: string;
+}
+/** `resized` payload: the measured content height in CSS pixels. */
+export interface EmbedResizedPayload {
+    /** Content height in CSS pixels. */
+    readonly height: number;
+}
+/**
+ * `navigated` / `navigation-requested` payload: the screen route and, when
+ * resolvable, the bound entity code and record id.
+ *
+ * `entity` and `recordId` are optional: a `custom` screen has no entity, and
+ * a list route has no record id.
+ */
+export interface EmbedNavigationPayload {
+    /** The Declarion screen route path the navigation targets. */
+    readonly route: string;
+    /** The bound entity code, when the route resolves to one. */
+    readonly entity?: string;
+    /** The record id, when the route is a detail route with an id. */
+    readonly recordId?: string;
+}
+/**
+ * `dirty-changed` payload: whether the embedded screen currently has unsaved
+ * edits. The host tracks this so it can guard its own navigation (its menu,
+ * a host-initiated `navigate`) before moving the iframe away from a dirty
+ * screen - the iframe never pops a dialog for host-driven navigation.
+ */
+export interface EmbedDirtyChangedPayload {
+    /** True when the embedded screen has unsaved edits. */
+    readonly dirty: boolean;
+}
+/** `navigate` payload: the route the host drives the iframe to. */
+export interface EmbedNavigatePayload {
+    /** The Declarion screen route the host wants opened. */
+    readonly route: string;
+}
+/** `set-theme` payload: the theme the host switches the iframe to. */
+export interface EmbedSetThemePayload {
+    /** The requested theme. */
+    readonly theme: "light" | "dark";
+}
+/**
+ * Maps each message type to its payload shape. Used to type `postToParent`
+ * so the payload argument is checked against the message type.
+ */
+export interface EmbedMessagePayloadMap {
+    [EMBED_MESSAGE_TYPES.ready]: EmbedReadyPayload;
+    [EMBED_MESSAGE_TYPES.setToken]: EmbedSetTokenPayload;
+    [EMBED_MESSAGE_TYPES.tokenExpired]: EmbedTokenExpiredPayload;
+    [EMBED_MESSAGE_TYPES.reloadRequired]: EmbedReloadRequiredPayload;
+    [EMBED_MESSAGE_TYPES.resized]: EmbedResizedPayload;
+    [EMBED_MESSAGE_TYPES.navigated]: EmbedNavigationPayload;
+    [EMBED_MESSAGE_TYPES.navigationRequested]: EmbedNavigationPayload;
+    [EMBED_MESSAGE_TYPES.dirtyChanged]: EmbedDirtyChangedPayload;
+    [EMBED_MESSAGE_TYPES.navigate]: EmbedNavigatePayload;
+    [EMBED_MESSAGE_TYPES.setTheme]: EmbedSetThemePayload;
+}
+/**
+ * The wire envelope. Every embed frame is exactly this shape: a fixed
+ * `source` + `protocol` pair, a discriminating `type`, and the typed
+ * `payload` for that type.
+ */
+export interface EmbedMessage<T extends EmbedMessageType = EmbedMessageType> {
+    readonly source: typeof EMBED_MESSAGE_SOURCE;
+    readonly protocol: typeof EMBED_PROTOCOL_VERSION;
+    readonly type: T;
+    readonly payload: EmbedMessagePayloadMap[T];
+}
+/**
+ * Post an enveloped embed message to the host page.
+ *
+ * Targets the EXACT `parentOrigin` - never `"*"` - so a malicious page that
+ * re-frames the iframe cannot intercept auth or navigation frames.
+ *
+ * No-op (returns false) when:
+ *  - `parentOrigin` is null or empty (no trusted origin to target), or
+ *  - the document is not framed (`window.parent === window`), or
+ *  - there is no `window` (SSR / unit environment without a DOM).
+ *
+ * Returns true when a message was posted.
+ */
+export declare function postToParent<T extends EmbedMessageType>(parentOrigin: string | null, type: T, payload: EmbedMessagePayloadMap[T]): boolean;

package/dist-lib/embed/screen-location.d.ts

@@ -0,0 +1,20 @@
+import type { EmbedNavigationPayload } from "./protocol";
+import type { Screen } from "../types/schema";
+/**
+ * Resolve the embed navigation payload for a router pathname.
+ *
+ * Matches the pathname against every registered screen route. An exact
+ * (wildcard-free) route wins over a `:param` route, mirroring
+ * `screenTitleForPath`, so `/cases` resolves to the list screen even though
+ * the detail route `/cases/:id` also shares the prefix.
+ *
+ * - `route` is the matched screen's own route pattern, or the raw pathname
+ *   when no screen owns it (a route always exists in the payload).
+ * - `entity` is the matched screen's bound entity code, when it has one.
+ * - `recordId` is the last path segment for a detail (`:param`) route, when
+ *   that segment is present and non-empty.
+ *
+ * `screens` may be undefined (schema not yet loaded); the payload then
+ * carries just the raw pathname as `route`.
+ */
+export declare function resolveEmbedNavigationPayload(pathname: string, screens: Record<string, Screen> | undefined): EmbedNavigationPayload;

package/dist-lib/embed/theme.d.ts

@@ -0,0 +1,34 @@
+import { type EmbedTheme } from "./params";
+/**
+ * Apply an embed theme to <html> immediately, WITHOUT persisting it.
+ *
+ * The single theme-apply path for embed mode: the pre-paint URL bootstrap
+ * (`applyEmbedThemeFromQuery`) and the runtime `theme` postMessage handler
+ * both route through here, so they can never diverge.
+ *
+ * `applyAppearance` is the single writer of <html> theme attributes; it
+ * keeps accent / density / etc. intact. The appearance store slice is then
+ * set directly (not via `setMany`) so later reads stay consistent WITHOUT
+ * writing localStorage - the embed theme is a host-supplied, ephemeral hint,
+ * not a user choice.
+ */
+export declare function applyEmbedTheme(theme: EmbedTheme): void;
+/**
+ * Read the embed `theme` param from the given query string and, when it is a
+ * valid `light`/`dark` value under an active `embed=1`, apply it to
+ * <html> immediately.
+ *
+ * Returns true when an embed theme was applied, false otherwise.
+ *
+ * Apply path: routes through `applyEmbedTheme`, which writes `data-theme` and
+ * updates the appearance store but deliberately does NOT touch localStorage.
+ */
+export declare function applyEmbedThemeFromQuery(query: string | URLSearchParams): boolean;
+/**
+ * Apply the embed theme from `window.location.search` at module load.
+ *
+ * Called once from the embed barrel so importing the embed entry point is
+ * enough to get pre-paint theming, exactly like the appearance module's
+ * own module-load `applyAppearance(initial)`.
+ */
+export declare function applyEmbedThemeFromLocation(): boolean;

package/dist-lib/embed/token.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Activate embed token mode. Called once at bootstrap by the embed auth
+ * handshake. `parentOrigin` is the exact host origin that `token-expired`
+ * frames are emitted to.
+ *
+ * Idempotent: re-activation only refreshes the parent origin.
+ */
+export declare function initEmbedTokenMode(parentOrigin: string | null): void;
+/**
+ * True when embed token mode is active. Transports branch on this to switch
+ * from the cookie path to the Bearer path. False everywhere outside an
+ * embed iframe, so the cookie path stays byte-equivalent to today.
+ */
+export declare function isEmbedTokenMode(): boolean;
+/** The current embed token string, or null before the first `auth` frame. */
+export declare function getEmbedToken(): string | null;
+/**
+ * The exact parent origin embed frames are emitted to, or null before
+ * `initEmbedTokenMode` runs. Used by transports outside this module (e.g.
+ * the version probe) that need to post a frame to the host.
+ */
+export declare function getEmbedParentOrigin(): string | null;
+/**
+ * Store a token delivered by the host's `auth` frame.
+ *
+ * Resolves any in-flight `awaitEmbedToken()` wait so every transport that
+ * was blocked on a fresh token unblocks at once. A malformed payload
+ * (missing token, unparseable expiry) is ignored - the wait stays pending
+ * until a well-formed frame arrives or the timeout fires.
+ */
+export declare function setEmbedToken(payload: {
+    token: string;
+    expires_at: string;
+}): void;
+/**
+ * Clear the held token. Used when a terminal failure makes the current
+ * token unusable; the next transport call will await a fresh one.
+ */
+export declare function clearEmbedToken(): void;
+/**
+ * Return a usable embed token, requesting a fresh one from the host when
+ * needed.
+ *
+ * SINGLE-FLIGHT: when the held token is still usable it resolves
+ * immediately. When the token is missing or stale, it emits exactly one
+ * `token-expired` frame to the host and waits for the next `auth` frame.
+ * Concurrent callers during that window share the one in-flight wait - the
+ * `token-expired` frame is emitted once, not once per caller.
+ *
+ * The wait is bounded by `TOKEN_WAIT_TIMEOUT_MS`; on timeout the promise
+ * rejects so the transport caller fails loudly instead of hanging.
+ */
+export declare function awaitEmbedToken(): Promise<string>;
+/**
+ * Test-only: reset all module state. Not exposed via package exports.
+ */
+export declare function __resetEmbedTokenForTests(): void;

package/dist-lib/embed/useEmbedNavigate.d.ts

@@ -0,0 +1,27 @@
+import { type NavigateOptions } from "react-router-dom";
+/**
+ * The shared embed navigation policy, decoupled from React Router's hook.
+ *
+ * `rawNavigate` is the underlying navigator (`useNavigate()`'s return value
+ * for `useEmbedNavigate`, the same for `useTabNavigate`). The returned
+ * `screenNavigate` applies the embed branch and reports whether it actually
+ * navigated:
+ *
+ *   - returns `false` in `delegated` embed mode (intercepted; iframe stayed),
+ *   - returns `true` otherwise (a real navigation happened).
+ *
+ * Callers in embed mode use the boolean to skip side effects (opening a tab)
+ * that only make sense for a navigation that actually moved.
+ */
+export declare function useEmbedScreenNavigate(): (to: string, opts?: NavigateOptions) => boolean;
+/**
+ * Embed-aware replacement for `useNavigate` at internal screen-route call
+ * sites. Returns a `navigate(to, opts)` function with the embed branch
+ * applied. Outside embed mode it is `useNavigate()` unchanged.
+ *
+ * Use this for every raw screen transition (cancel-edit, save success,
+ * delete success, Back). Do NOT use it for non-route navigation (anchors,
+ * external URLs); those are not screen routes and embed mode does not touch
+ * them.
+ */
+export declare function useEmbedNavigate(): (to: string, opts?: NavigateOptions) => void;