@declarion/react 0.5.0 → 0.6.1

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

@@ -7,9 +7,11 @@ export { classifyInboundMessage, createInboundMessageListener, type InboundClass
 export { EmbedAuthBootstrap } from "./EmbedAuthBootstrap";
 export { EmbedResizeReporter } from "./EmbedResizeReporter";
 export { EmbedDirtyReporter } from "./EmbedDirtyReporter";
-export { EMBED_MESSAGE_SOURCE, EMBED_PROTOCOL_VERSION, EMBED_MESSAGE_TYPES, postToParent, type EmbedMessageType, type EmbedMessage, type EmbedMessagePayloadMap, type EmbedReadyPayload, type EmbedSetTokenPayload, type EmbedTokenExpiredPayload, type EmbedReloadRequiredPayload, type EmbedResizedPayload, type EmbedNavigationPayload, type EmbedDirtyChangedPayload, type EmbedNavigatePayload, type EmbedSetThemePayload, } from "./protocol";
-export { resolveEmbedNavigationPayload } from "./screen-location";
-export { useEmbedNavigate, useEmbedScreenNavigate } from "./useEmbedNavigate";
+export { EMBED_MESSAGE_SOURCE, EMBED_PROTOCOL_VERSION, EMBED_MESSAGE_TYPES, postToParent, type EmbedMessageType, type EmbedMessage, type EmbedMessagePayloadMap, type EmbedReadyPayload, type EmbedSetTokenPayload, type EmbedTokenExpiredPayload, type EmbedReloadRequiredPayload, type EmbedResizedPayload, type EmbedNavigationPayload, type EmbedDirtyChangedPayload, type EmbedNavigationFailedPayload, type EmbedNavigatePayload, type EmbedSetThemePayload, } from "./protocol";
+export { resolveEmbedNavigation, resolveEmbedNavigationPayload, } from "./screen-location";
+export type { EmbedNavigationResolution } from "./screen-location";
+export { useEmbedNavigate, useEmbedScreenNavigate, useEmbedNavigationFailed, } from "./useEmbedNavigate";
+export { useGlobalLinkInterceptor, interceptedNavigationTarget, interceptedProgrammaticTarget, NATIVE_LINK_ATTR, } from "./useGlobalLinkInterceptor";
 export { EmbedLocationReporter } from "./EmbedLocationReporter";
 export { useEmbedDirtyStore, useReportEmbedDirty } from "./embed-dirty";
 export { EmbedUnsavedGuard } from "./EmbedUnsavedGuard";

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

@@ -32,6 +32,9 @@ export declare const EMBED_MESSAGE_TYPES: {
     readonly navigationRequested: "navigation-requested";
     /** iframe -> host: the embedded screen's unsaved-edits state flipped. */
     readonly dirtyChanged: "dirty-changed";
+    /** iframe -> host: an in-frame navigation could not be handled (unknown
+     *  route, or a 404 the host should recover from). The iframe stayed put. */
+    readonly navigationFailed: "navigation-failed";
     /** host -> iframe: drive the iframe to a screen (deep-linking). */
     readonly navigate: "navigate";
     /** host -> iframe: runtime theme switch. */
@@ -62,14 +65,22 @@ export interface EmbedResizedPayload {
 }
 /**
  * `navigated` / `navigation-requested` payload: the screen route and, when
- * resolvable, the bound entity code and record id.
+ * resolvable, the matched screen code, 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.
+ * `screenCode`, `entity`, and `recordId` are optional: an unregistered path
+ * resolves to none of them, a `custom` screen has no entity, and a list route
+ * has no record id. The host needs `screenCode` to mint a scoped embed token
+ * for the target screen when it executes a `delegated` navigation intent.
  */
 export interface EmbedNavigationPayload {
     /** The Declarion screen route path the navigation targets. */
     readonly route: string;
+    /**
+     * The matched screen's code (its key in the schema screen map), when a
+     * registered screen owns the route. Absent for an unresolved path. The host
+     * passes this as `screen_code` to `auth.create_embed_session`.
+     */
+    readonly screenCode?: 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. */
@@ -85,6 +96,21 @@ export interface EmbedDirtyChangedPayload {
     /** True when the embedded screen has unsaved edits. */
     readonly dirty: boolean;
 }
+/**
+ * `navigation-failed` payload: an in-frame navigation the iframe refused or
+ * could not resolve. The iframe stayed put; the host owns recovery (show its
+ * own not-found, reset its sidebar selection, etc.).
+ *
+ * `reason` is a closed set, each with a real producer: `not_found` from the
+ * embedded 404 catch-all, `unresolved` from the navigation chokepoint when the
+ * target route matches no registered screen.
+ */
+export interface EmbedNavigationFailedPayload {
+    /** The route that could not be navigated to. */
+    readonly route: string;
+    /** Why it failed. */
+    readonly reason: "not_found" | "unresolved";
+}
 /** `navigate` payload: the route the host drives the iframe to. */
 export interface EmbedNavigatePayload {
     /** The Declarion screen route the host wants opened. */
@@ -108,6 +134,7 @@ export interface EmbedMessagePayloadMap {
     [EMBED_MESSAGE_TYPES.navigated]: EmbedNavigationPayload;
     [EMBED_MESSAGE_TYPES.navigationRequested]: EmbedNavigationPayload;
     [EMBED_MESSAGE_TYPES.dirtyChanged]: EmbedDirtyChangedPayload;
+    [EMBED_MESSAGE_TYPES.navigationFailed]: EmbedNavigationFailedPayload;
     [EMBED_MESSAGE_TYPES.navigate]: EmbedNavigatePayload;
     [EMBED_MESSAGE_TYPES.setTheme]: EmbedSetThemePayload;
 }

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

@@ -1,20 +1,50 @@
 import type { EmbedNavigationPayload } from "./protocol";
 import type { Screen } from "../types/schema";
 /**
- * Resolve the embed navigation payload for a router pathname.
+ * The result of resolving a router pathname against the screen schema.
+ *
+ * `matched` is the load-bearing flag for the navigation chokepoint: when a
+ * registered screen owns the path it is `true` and `screenCode` names that
+ * screen; when no screen owns the path it is `false` (the chokepoint then
+ * refuses an embed navigation and emits `navigation-failed`). `payload` is
+ * always present - it carries the matched screen route (or the raw pathname
+ * when unmatched) for the `navigated` / `navigation-requested` messages.
+ */
+export interface EmbedNavigationResolution {
+    /** True when a registered screen route owns this pathname. */
+    readonly matched: boolean;
+    /** The matched screen's code (its key in `screens`), when matched. */
+    readonly screenCode?: string;
+    /** The matched screen's `type` (`list` / `detail` / `custom` / ...), when
+     *  matched. The same-surface rule reads it to identify a true list/detail
+     *  pair (vs. a same-entity custom or record-list screen). */
+    readonly screenType?: string;
+    /** The navigation payload to emit (route always set; ids when resolvable). */
+    readonly payload: EmbedNavigationPayload;
+}
+/**
+ * Resolve a router pathname against the screen schema, with match status.
  *
  * 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.
+ * - `matched` is true only when a registered screen owns the path.
+ * - `screenCode` is the matched screen's map key (so the host can mint a
+ *   scoped token for it).
+ * - `payload.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).
+ * - `payload.entity` is the matched screen's bound entity code, when it has one.
+ * - `payload.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`.
+ * `screens` may be undefined (schema not yet loaded); the result is then
+ * `matched: false` with the raw pathname as `payload.route`.
+ */
+export declare function resolveEmbedNavigation(pathname: string, screens: Record<string, Screen> | undefined): EmbedNavigationResolution;
+/**
+ * Convenience wrapper returning just the payload, for the `navigated` and
+ * `navigation-requested` emitters that do not need the match status.
  */
 export declare function resolveEmbedNavigationPayload(pathname: string, screens: Record<string, Screen> | undefined): EmbedNavigationPayload;

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

@@ -1,4 +1,5 @@
 import { type NavigateOptions } from "react-router-dom";
+import { type EmbedNavigationFailedPayload } from "./protocol";
 /**
  * The shared embed navigation policy, decoupled from React Router's hook.
  *
@@ -25,3 +26,11 @@ export declare function useEmbedScreenNavigate(): (to: string, opts?: NavigateOp
  * them.
  */
 export declare function useEmbedNavigate(): (to: string, opts?: NavigateOptions) => void;
+/**
+ * Emit a `navigation-failed` event to the host. Used where an in-frame
+ * navigation cannot be handled OUTSIDE the chokepoint - chiefly the embedded
+ * 404 page, which the iframe reaches via a host-driven `navigate` command, a
+ * bad initial route, or a hard reload (none of which pass through the
+ * chokepoint's own guard). A no-op outside embed mode.
+ */
+export declare function useEmbedNavigationFailed(): (route: string, reason: EmbedNavigationFailedPayload["reason"]) => void;

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

@@ -0,0 +1,66 @@
+/**
+ * Attribute that opts an anchor out of interception. A react-router `<Link>`
+ * (or any anchor) that must keep native / router-managed click semantics
+ * (relative resolution, `replace`, navigation `state`) carries this and the
+ * interceptor leaves it to the browser / the router's own onClick.
+ */
+export declare const NATIVE_LINK_ATTR = "data-declarion-native-link";
+/**
+ * Decide whether a click should be intercepted for in-app navigation, and to
+ * where. Returns the in-app path (`pathname + search + hash`) to navigate to,
+ * or `null` to leave the click to the browser.
+ *
+ * Pure (no side effects, no `preventDefault`): the caller prevents default and
+ * routes. The guard order is cheap-first so the common "not for us" click
+ * exits immediately. Mirrors React Router `shouldProcessLinkClick`, Turbo
+ * `LinkClickObserver`, and the SvelteKit client router.
+ */
+export declare function interceptedNavigationTarget(event: MouseEvent, loc?: {
+    origin: string;
+    pathname: string;
+    search: string;
+}): string | null;
+/**
+ * Minimal structural shape of the Navigation API `navigate` event - typed
+ * locally because `window.navigation` / `NavigateEvent` are not yet in the
+ * ambient DOM lib across our toolchain.
+ */
+export interface NavigateEventLike {
+    readonly canIntercept: boolean;
+    readonly hashChange: boolean;
+    readonly downloadRequest: string | null;
+    readonly formData: unknown;
+    readonly cancelable: boolean;
+    readonly destination: {
+        readonly url: string;
+        readonly sameDocument: boolean;
+    };
+    preventDefault(): void;
+}
+/**
+ * Decide whether a Navigation API `navigate` event is a programmatic, same-
+ * origin, FULL-document escape that must be kept inside the SPA / embed
+ * boundary, and to where. Returns the in-app path, or null to leave it alone.
+ *
+ * This is the layer the click interceptor cannot cover: `location.assign`,
+ * `location.href = ...`, `<meta http-equiv=refresh>`, etc. - navigations not
+ * triggered by an anchor click. Same-document navigations (react-router's own
+ * `pushState` SPA transitions) are skipped via `destination.sameDocument`, so
+ * we never re-process or loop on our own router. Cross-origin and non-http
+ * destinations are left to the browser (the iframe sandbox contains them);
+ * downloads and hash changes are left alone. A POST form submission carries a
+ * body (`formData` non-null) and must reach the server, so it is left alone
+ * too; a GET form navigating to a same-origin route has no body and is routed
+ * like any internal navigation (kept in-frame, not full-loaded out of embed).
+ */
+export declare function interceptedProgrammaticTarget(event: NavigateEventLike, loc?: {
+    origin: string;
+}): string | null;
+/**
+ * Mount the single global link interceptor. Call once, high in the tree that
+ * renders screens (the app `Layout`), so it covers every embedded and
+ * standalone screen. It is intentionally NOT mounted on the auth routes
+ * (`/login`, `/signup`, ...), which live outside `Layout`, so those pages keep
+ * their native react-router `<Link>` semantics.
+ */
+export declare function useGlobalLinkInterceptor(): void;