@qontinui/ui-bridge-native 0.6.15 → 0.6.16

package/dist/react/routePattern.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Route-pattern helpers for React Native routers — derive a route TEMPLATE
+ * from the router's own route identifiers, failing closed.
+ *
+ * Why this exists: `useRouteAwareness({ pattern })` is consumed as a route
+ * TEMPLATE (the runner's journey ledger stores it as `pathnameTemplate`, which
+ * must never carry user input). The web SDK derives its pattern by VALUE
+ * substitution (`routePatternFromParams` in `@qontinui/ui-bridge`), because
+ * Next.js exposes only a concrete pathname. Native routers need no
+ * substitution: both already expose template identifiers directly.
+ *
+ * - **Expo Router** — `useSegments()` returns file-route names
+ *   (`['profile', '[user]']`, `['(tabs)', 'runs']`), never the concrete path.
+ *   A not-found render reads `['+not-found']` in its segments. The concrete
+ *   not-found path is never a segment: it is always in `pathname` (which the
+ *   helpers never take), and on the NESTED not-found branch it is also in
+ *   `params['not-found']`; on the top-level branch `params` is `{}`
+ *   (expo-router 6.0.23 `build/global-state/routeInfo.js:22-30, 96-99`).
+ * - **React Navigation** — the navigation state carries each route's `name`,
+ *   a static identifier declared in code (`<Stack.Screen name="Profile">`).
+ *   User values live only in `route.params`, which these helpers never read.
+ *
+ * So the helpers only VALIDATE shape. GUARANTEE, and its precondition: a
+ * non-null result is built solely from the segments / route names the caller
+ * passed, each of which is a non-empty string containing no `/`, `?` or `#`.
+ * It carries no user input ONLY when those inputs are the router's own
+ * route-identifier output — `useSegments()` or the navigation state — and
+ * never `usePathname()`, a URL, or a param value. One residual: when Expo's
+ * navigation state is incomplete it pushes `route.params.screen` strings into
+ * the segments (`routeInfo.js:59-83`). Those are navigator screen names, not
+ * user values, so the guarantee holds as long as an app never navigates with a
+ * user-controlled `screen` param; the shape test bounds what such a value
+ * could carry.
+ *
+ * @example
+ * ```tsx
+ * import { useSegments } from 'expo-router';
+ * import {
+ *   expoRouterPattern,
+ *   expoRouterRouteStack,
+ *   isExpoRouterUnmatched,
+ * } from '@qontinui/ui-bridge-native';
+ *
+ * function useExpoRoute() {
+ *   const segments = useSegments();
+ *   return {
+ *     pattern: expoRouterPattern(segments),
+ *     routeStack: expoRouterRouteStack(segments),
+ *     unmatched: isExpoRouterUnmatched(segments),
+ *   };
+ * }
+ * ```
+ */
+/**
+ * Structural subset of a React Navigation state object — the ROOT state, as
+ * `navigationRef.getRootState()` (from `useNavigationContainerRef()`) or the
+ * `NavigationContainer` `onStateChange` callback returns it. Do NOT use
+ * `useNavigationState((s) => s)`: outside a navigator it throws, and inside a
+ * screen it returns only that navigator's state, truncating the chain.
+ * Declared structurally so this package takes no dependency on
+ * `@react-navigation/*`. `params` is deliberately absent: the helper never
+ * reads it.
+ */
+export interface NavigationStateLike {
+    /**
+     * Index of the focused route in `routes`. When absent (a partial state),
+     * React Navigation's own rule applies: the LAST route for a stack (or a
+     * state with no `type`), the FIRST route for any other navigator type.
+     */
+    index?: number;
+    /** Navigator type (`'stack'`, `'tab'`, `'drawer'`, …), when known. */
+    type?: string;
+    routes: ReadonlyArray<{
+        name: string;
+        /** The nested navigator's state, when this route hosts one. */
+        state?: NavigationStateLike;
+    }>;
+}
+/** Options for {@link reactNavigationPattern}. */
+export interface ReactNavigationPatternOptions {
+    /**
+     * Route names that render the app's not-found screen (the `linking`
+     * config's catch-all screen). When the focused LEAF route has one of these
+     * names the helper returns `null`.
+     */
+    notFoundRouteNames?: readonly string[];
+}
+/**
+ * True when Expo Router's segments name a system route — any segment starting
+ * with `+` (`+not-found`; `+html` / `+api` never render). Expo reserves the
+ * `+` prefix, so no `+` segment names a user screen. Pass the result as
+ * `useRouteAwareness(info, { unmatched })`.
+ */
+export declare function isExpoRouterUnmatched(segments: readonly string[]): boolean;
+/**
+ * Derive a route template from Expo Router's `useSegments()`:
+ * `'/' + segments.join('/')`, with layout groups such as `(tabs)` KEPT.
+ *
+ * - `[]` → `'/'` (Expo already pops a trailing `index`);
+ * - `['profile', '[user]']` → `'/profile/[user]'`;
+ * - `['(tabs)', 'runs']` → `'/(tabs)/runs'`.
+ *
+ * Groups are kept because they are developer-declared names, never user
+ * input, and because two screens in different groups can share a URL — the
+ * group is what keeps them distinct. A consumer that wants the URL shape can
+ * strip `(…)` segments; a stripped pattern cannot be un-stripped.
+ *
+ * Returns `null` when any segment starts with `+` (a system route, see
+ * {@link isExpoRouterUnmatched}) or fails the route-identifier shape test
+ * (empty, not a string, or containing `/`, `?` or `#`).
+ */
+export declare function expoRouterPattern(segments: readonly string[]): string | null;
+/**
+ * Derive the cumulative route stack from Expo Router's `useSegments()`, with
+ * the same meaning as the web `RouteInfo.routeStack` (`["/", "/tasks",
+ * "/tasks/:id"]`): one template per depth, root first.
+ *
+ * - `[]` → `['/']`;
+ * - `['(tabs)', 'runs']` → `['/', '/(tabs)', '/(tabs)/runs']`.
+ *
+ * Fails closed by the same rules as {@link expoRouterPattern}: returns
+ * `undefined` (no stack reported) when any segment is a `+` system route or
+ * fails the route-identifier shape test.
+ */
+export declare function expoRouterRouteStack(segments: readonly string[]): string[] | undefined;
+/**
+ * Derive a route template from a React Navigation state: the focused
+ * route-NAME chain, root to leaf, joined with `/` — e.g. `/HomeTabs/Profile`.
+ *
+ * The whole chain rather than the leaf keeps same-named screens in different
+ * navigators (`Settings` under two tabs) distinct. Route `params` are never
+ * read, so no param shape can leak into the result. Pass the ROOT state
+ * (see {@link NavigationStateLike}); a level with no `index` focuses its last
+ * route for a stack (or an untyped state) and its first for any other type.
+ *
+ * Returns `null` on an empty `routes`, an out-of-range or non-integer
+ * `index`, a route name that fails the route-identifier shape test, or a
+ * focused leaf whose name is in `options.notFoundRouteNames`.
+ *
+ * Expo Router apps should use {@link expoRouterPattern} instead: Expo Router
+ * is React Navigation underneath, and a raw walk of its state yields Expo's
+ * internal route names rather than the file routes.
+ */
+export declare function reactNavigationPattern(state: NavigationStateLike | null | undefined, options?: ReactNavigationPatternOptions): string | null;
+//# sourceMappingURL=routePattern.d.ts.map

package/dist/react/routePattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routePattern.d.ts","sourceRoot":"","sources":["../../src/react/routePattern.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,+DAA+D;QAC/D,KAAK,CAAC,EAAE,mBAAmB,CAAC;KAC7B,CAAC,CAAC;CACJ;AAED,kDAAkD;AAClD,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AA2BD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE1E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAO5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,CAOtF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,EAC7C,OAAO,GAAE,6BAAkC,GAC1C,MAAM,GAAG,IAAI,CAiBf"}

package/dist/react/useRouteAwareness.d.ts

@@ -0,0 +1,106 @@
+/**
+ * useRouteAwareness — report the router's current route TEMPLATE to the
+ * native bridge, emitted on every snapshot as `page.route`.
+ *
+ * `pattern` is a route TEMPLATE, never the concrete pathname: a concrete path
+ * (`/search/<what the user typed>`) reported as a pattern leaks user input into
+ * anything that stores templates — the runner's journey ledger reads
+ * `snapshot.page.route.pattern` and keeps it only under
+ * `patternSource: 'router'`. Derive the pattern with `expoRouterPattern`
+ * (Expo Router `useSegments()`) or `reactNavigationPattern` (React Navigation
+ * state), which return `null` rather than leak, and say where it came from
+ * with `patternSource: 'router'`. NEVER pass `usePathname()`, a URL, or a
+ * param value as the pattern.
+ *
+ * The not-found signal is a plain boolean, `{ unmatched }`. The web SDK needs
+ * a provider-owned context signal and a layout effect because a Next.js layout
+ * renders before its `not-found.tsx` exists, so it cannot know at render time
+ * that the render is a 404. Neither native router has that gap: Expo Router's
+ * `useSegments()` already reads `['+not-found']` in the same render
+ * (`isExpoRouterUnmatched`), and a React Navigation not-found screen is an
+ * ordinary named route in the state the caller already reads. So there is no
+ * signal to wire. While `unmatched` is true the reported `pattern` is `null`
+ * AND `params` is dropped: on a NESTED `+not-found` route expo-router also
+ * carries the concrete not-found path in `params['not-found']` (on the
+ * top-level branch `params` is `{}`; the path is always in `pathname`, which
+ * the hook never takes), so a caller passing the router's search params as
+ * `params` would otherwise ship user input.
+ *
+ * Note: native's `unmatched?: boolean` shares its option KEY with the web
+ * hook's `unmatched?: RouteUnmatchedSignal | null`, but not its type.
+ *
+ * The reported info is cleared when the component unmounts. Outside a
+ * `UIBridgeNativeProvider` the hook is a no-op.
+ *
+ * Usage with Expo Router (in the root layout):
+ *
+ * @example
+ * ```tsx
+ * import { useSegments } from 'expo-router';
+ * import {
+ *   expoRouterPattern,
+ *   expoRouterRouteStack,
+ *   isExpoRouterUnmatched,
+ *   useRouteAwareness,
+ * } from '@qontinui/ui-bridge-native';
+ *
+ * function RouteAwareness() {
+ *   const segments = useSegments();
+ *   useRouteAwareness(
+ *     {
+ *       pattern: expoRouterPattern(segments),
+ *       patternSource: 'router',
+ *       routeStack: expoRouterRouteStack(segments),
+ *     },
+ *     { unmatched: isExpoRouterUnmatched(segments) }
+ *   );
+ *   return null;
+ * }
+ * ```
+ *
+ * Usage with React Navigation: read the ROOT state from the container, not
+ * with `useNavigationState` (which throws outside a navigator and, inside a
+ * screen, sees only that navigator's state). The component must render inside
+ * `UIBridgeNativeProvider`:
+ *
+ * @example
+ * ```tsx
+ * import { useState } from 'react';
+ * import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
+ * import {
+ *   reactNavigationPattern,
+ *   useRouteAwareness,
+ *   type NavigationStateLike,
+ * } from '@qontinui/ui-bridge-native';
+ *
+ * function Navigation({ children }: { children: React.ReactNode }) {
+ *   const navigationRef = useNavigationContainerRef();
+ *   const [rootState, setRootState] = useState<NavigationStateLike | undefined>();
+ *   const syncRootState = () => setRootState(navigationRef.getRootState());
+ *
+ *   const pattern = reactNavigationPattern(rootState, { notFoundRouteNames: ['NotFound'] });
+ *   useRouteAwareness({ pattern, patternSource: 'router' }, { unmatched: pattern === null });
+ *
+ *   return (
+ *     <NavigationContainer ref={navigationRef} onReady={syncRootState} onStateChange={syncRootState}>
+ *       {children}
+ *     </NavigationContainer>
+ *   );
+ * }
+ * ```
+ */
+import type { RouteInfo } from '../core/types';
+export interface UseRouteAwarenessOptions {
+    /**
+     * True while the current route is a not-found screen. The reported
+     * `pattern` is then `null` and `params` is dropped, whatever `info` says.
+     */
+    unmatched?: boolean;
+}
+/**
+ * Report router information to the native bridge's `page.route`.
+ *
+ * The info is cleared when the component unmounts.
+ */
+export declare function useRouteAwareness(info: RouteInfo, options?: UseRouteAwarenessOptions): void;
+//# sourceMappingURL=useRouteAwareness.d.ts.map

package/dist/react/useRouteAwareness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRouteAwareness.d.ts","sourceRoot":"","sources":["../../src/react/useRouteAwareness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,wBAA6B,GAAG,IAAI,CAwB/F"}

package/dist/server/index.js

@@ -2260,7 +2260,7 @@ function createServerHandlers(registry, executor, config) {
       };
       if (config?.appInfo) {
         response.uiBridge = {
-          version: "0.6.15",
+          version: "0.6.16",
           ...config.appInfo,
           capabilities: ["elements", "components", "actions", "design"],
           elementCount: stats.elements,