@almadar/ui 5.152.0 → 5.154.0

package/dist/{EntityBindingContext-CD9ZoXb4.d.cts → EntityBindingContext-BfZGeDfX.d.cts}

@@ -84,7 +84,7 @@ declare function useEntitySchema(): EntitySchemaContextValue;
 declare function useEntitySchemaOptional(): EntitySchemaContextValue | null;
 
 /** Wire-format client effect tuple from the server response. */
-type ClientEffectTuple = ['render-ui', string, AnyPatternConfig | null, ...SExpr[]] | ['navigate', string, ...SExpr[]] | ['notify', string, ...SExpr[]];
+type ClientEffectTuple = ['render-ui', string, AnyPatternConfig | null, ...SExpr[]] | ['navigate', string, ...SExpr[]] | ['navigate-back'] | ['notify', string, ...SExpr[]];
 interface OrbitalEventResponse {
     success: boolean;
     transitioned: boolean;
@@ -114,11 +114,13 @@ interface OrbitalEventResponse {
     error?: string;
 }
 interface ServerClientEffect {
-    type: 'render-ui' | 'navigate' | 'notify';
+    type: 'render-ui' | 'navigate' | 'navigate-back' | 'notify';
     slot?: string;
     pattern?: AnyPatternConfig;
     route?: string;
     params?: EventPayload;
+    /** Nav-stack entry label carried by the navigate effect's options. */
+    crumb?: string;
     message?: string;
     /**
      * Trait that emitted this effect. Used by `<TraitFrame>` to resolve

package/dist/{EntityBindingContext-CD9ZoXb4.d.ts → EntityBindingContext-BfZGeDfX.d.ts}

@@ -84,7 +84,7 @@ declare function useEntitySchema(): EntitySchemaContextValue;
 declare function useEntitySchemaOptional(): EntitySchemaContextValue | null;
 
 /** Wire-format client effect tuple from the server response. */
-type ClientEffectTuple = ['render-ui', string, AnyPatternConfig | null, ...SExpr[]] | ['navigate', string, ...SExpr[]] | ['notify', string, ...SExpr[]];
+type ClientEffectTuple = ['render-ui', string, AnyPatternConfig | null, ...SExpr[]] | ['navigate', string, ...SExpr[]] | ['navigate-back'] | ['notify', string, ...SExpr[]];
 interface OrbitalEventResponse {
     success: boolean;
     transitioned: boolean;
@@ -114,11 +114,13 @@ interface OrbitalEventResponse {
     error?: string;
 }
 interface ServerClientEffect {
-    type: 'render-ui' | 'navigate' | 'notify';
+    type: 'render-ui' | 'navigate' | 'navigate-back' | 'notify';
     slot?: string;
     pattern?: AnyPatternConfig;
     route?: string;
     params?: EventPayload;
+    /** Nav-stack entry label carried by the navigate effect's options. */
+    crumb?: string;
     message?: string;
     /**
      * Trait that emitted this effect. Used by `<TraitFrame>` to resolve

package/dist/NavStackContext-BoVV9nWb.d.cts

@@ -0,0 +1,83 @@
+import React__default from 'react';
+import { NavStackEntry } from '@almadar/core';
+
+/**
+ * Navigation-stack core — the pure logic behind the orbital-scoped
+ * client-session navigation stack both execution paths share.
+ *
+ * The stack is what detail-page breadcrumb bands and the `navigate-back`
+ * effect read. It lives client-side only (per browser tab): the runtime
+ * path's OrbPreview and the compiled app's App.tsx both mount
+ * `NavStackProvider` (providers/NavStackContext.tsx), which drives this
+ * module on every route change.
+ *
+ * Semantics (deterministic):
+ * - One stack per ORBITAL, keyed by the orbital owning the current page.
+ * - On route change: an entry with the same href already in the stack
+ *   truncates back to it (revisit); otherwise the new entry is pushed.
+ * - Cold load (deep link): the stack seeds from the declared page-path
+ *   hierarchy — every declared page whose pattern matches a strict prefix
+ *   of the concrete path becomes an ancestor entry — so the trail is never
+ *   empty and back always has a target on nested paths.
+ * - Entry label = the `crumb` carried by the navigate effect when one was
+ *   staged for this href, else the page's declared name humanized.
+ */
+
+/** One declared page as the nav stack needs it: path pattern + name + owning orbital. */
+interface NavPageDecl {
+    path: string;
+    name: string;
+    orbital: string;
+}
+
+/**
+ * NavStackProvider — the orbital-scoped client-session navigation stack.
+ *
+ * One provider instance per app host. Both execution paths mount it:
+ * - Runtime path: OrbPreview supplies `currentPath` + `navigate` explicitly.
+ * - Compiled path: the emitted App.tsx mounts `NavStackRouterBridge`, which
+ *   reads react-router's location/navigate and renders this provider.
+ *
+ * Pure stack semantics live in lib/navStack.ts (one owner for both paths).
+ * State persists to sessionStorage (per-tab) so a compiled app's full page
+ * reload keeps the trail; every storage access is guarded with an in-memory
+ * fallback.
+ */
+
+interface NavStackApi {
+    /** Stack of the current page's orbital, root-first (empty when no declared page matches). */
+    entries: readonly NavStackEntry[];
+    /** True when a previous entry exists for the current page's orbital. */
+    canGoBack: boolean;
+    /** Stage the crumb label for the entry the target page will record, then call navigate yourself. */
+    beginNavigate: (href: string, crumb?: string) => void;
+    /** Pop the current orbital's stack: navigate to the previous entry (no-op without one). */
+    back: () => void;
+    /** Navigate to an arbitrary stack entry (breadcrumb click). */
+    goTo: (href: string) => void;
+}
+declare function useNavStack(): NavStackApi;
+interface NavStackProviderProps {
+    pages: readonly NavPageDecl[];
+    /** Concrete current path (route params substituted), e.g. /contracts/42. */
+    currentPath: string;
+    /** Host navigation function (SPA route change). */
+    navigate: (path: string) => void;
+    /** sessionStorage key; omit to keep the stack in memory only. */
+    storageKey?: string;
+    children: React__default.ReactNode;
+}
+declare const NavStackProvider: React__default.FC<NavStackProviderProps>;
+interface NavStackRouterBridgeProps {
+    pages: readonly NavPageDecl[];
+    storageKey?: string;
+    children: React__default.ReactNode;
+}
+/**
+ * Compiled-path host: binds NavStackProvider to react-router. Must render
+ * inside a Router (the emitted App.tsx mounts it directly under
+ * BrowserRouter).
+ */
+declare const NavStackRouterBridge: React__default.FC<NavStackRouterBridgeProps>;
+
+export { type NavPageDecl as N, type NavStackApi as a, NavStackProvider as b, type NavStackProviderProps as c, NavStackRouterBridge as d, type NavStackRouterBridgeProps as e, useNavStack as u };

package/dist/NavStackContext-BoVV9nWb.d.ts

@@ -0,0 +1,83 @@
+import React__default from 'react';
+import { NavStackEntry } from '@almadar/core';
+
+/**
+ * Navigation-stack core — the pure logic behind the orbital-scoped
+ * client-session navigation stack both execution paths share.
+ *
+ * The stack is what detail-page breadcrumb bands and the `navigate-back`
+ * effect read. It lives client-side only (per browser tab): the runtime
+ * path's OrbPreview and the compiled app's App.tsx both mount
+ * `NavStackProvider` (providers/NavStackContext.tsx), which drives this
+ * module on every route change.
+ *
+ * Semantics (deterministic):
+ * - One stack per ORBITAL, keyed by the orbital owning the current page.
+ * - On route change: an entry with the same href already in the stack
+ *   truncates back to it (revisit); otherwise the new entry is pushed.
+ * - Cold load (deep link): the stack seeds from the declared page-path
+ *   hierarchy — every declared page whose pattern matches a strict prefix
+ *   of the concrete path becomes an ancestor entry — so the trail is never
+ *   empty and back always has a target on nested paths.
+ * - Entry label = the `crumb` carried by the navigate effect when one was
+ *   staged for this href, else the page's declared name humanized.
+ */
+
+/** One declared page as the nav stack needs it: path pattern + name + owning orbital. */
+interface NavPageDecl {
+    path: string;
+    name: string;
+    orbital: string;
+}
+
+/**
+ * NavStackProvider — the orbital-scoped client-session navigation stack.
+ *
+ * One provider instance per app host. Both execution paths mount it:
+ * - Runtime path: OrbPreview supplies `currentPath` + `navigate` explicitly.
+ * - Compiled path: the emitted App.tsx mounts `NavStackRouterBridge`, which
+ *   reads react-router's location/navigate and renders this provider.
+ *
+ * Pure stack semantics live in lib/navStack.ts (one owner for both paths).
+ * State persists to sessionStorage (per-tab) so a compiled app's full page
+ * reload keeps the trail; every storage access is guarded with an in-memory
+ * fallback.
+ */
+
+interface NavStackApi {
+    /** Stack of the current page's orbital, root-first (empty when no declared page matches). */
+    entries: readonly NavStackEntry[];
+    /** True when a previous entry exists for the current page's orbital. */
+    canGoBack: boolean;
+    /** Stage the crumb label for the entry the target page will record, then call navigate yourself. */
+    beginNavigate: (href: string, crumb?: string) => void;
+    /** Pop the current orbital's stack: navigate to the previous entry (no-op without one). */
+    back: () => void;
+    /** Navigate to an arbitrary stack entry (breadcrumb click). */
+    goTo: (href: string) => void;
+}
+declare function useNavStack(): NavStackApi;
+interface NavStackProviderProps {
+    pages: readonly NavPageDecl[];
+    /** Concrete current path (route params substituted), e.g. /contracts/42. */
+    currentPath: string;
+    /** Host navigation function (SPA route change). */
+    navigate: (path: string) => void;
+    /** sessionStorage key; omit to keep the stack in memory only. */
+    storageKey?: string;
+    children: React__default.ReactNode;
+}
+declare const NavStackProvider: React__default.FC<NavStackProviderProps>;
+interface NavStackRouterBridgeProps {
+    pages: readonly NavPageDecl[];
+    storageKey?: string;
+    children: React__default.ReactNode;
+}
+/**
+ * Compiled-path host: binds NavStackProvider to react-router. Must render
+ * inside a Router (the emitted App.tsx mounts it directly under
+ * BrowserRouter).
+ */
+declare const NavStackRouterBridge: React__default.FC<NavStackRouterBridgeProps>;
+
+export { type NavPageDecl as N, type NavStackApi as a, NavStackProvider as b, type NavStackProviderProps as c, NavStackRouterBridge as d, type NavStackRouterBridgeProps as e, useNavStack as u };