@sigx/lynx-navigation 0.1.0

package/src/hooks/use-nav-internal.ts

@@ -0,0 +1,47 @@
+import { defineInjectable, type SharedValue } from '@sigx/lynx';
+import type { RouteMap } from '../types.js';
+
+/**
+ * Internal injectable: the route registry passed into `<NavigationRoot>`.
+ * Components (Stack, Screen) read this to look up route definitions by name.
+ *
+ * Not exported from the package barrel — use `useNav()` for navigation, and
+ * the registry is implicit from `<NavigationRoot routes={...}>`.
+ */
+export const useNavRoutes = defineInjectable<RouteMap>(() => {
+    throw new Error(
+        '[lynx-navigation] No <NavigationRoot> found in the component tree.',
+    );
+});
+
+/**
+ * Internal injectable: low-level navigator handles used by the edge-back
+ * gesture. Holds the progress SharedValue (so gesture worklets can write it
+ * directly on MT) plus BG-side begin/commit/cancel functions invoked via
+ * `runOnBackground` from gesture worklets.
+ *
+ * `progress` is `null` when the navigator was created with `animated={false}`
+ * (e.g. tests). `beginBackGesture` is also a no-op in that case.
+ */
+export interface NavInternals {
+    /** MT-driven transition progress; null when animations are disabled. */
+    readonly progress: SharedValue<number> | null;
+    /**
+     * Set transition state for a gesture-driven pop. Does not start any
+     * automatic animation — the gesture worklet writes `progress` directly
+     * per frame, then animates to the commit/cancel endpoint on release.
+     */
+    beginBackGesture(): void;
+    /** Commit the back gesture: pop top entry + clear transition. */
+    commitBackGesture(): void;
+    /** Cancel the back gesture: clear transition without popping. */
+    cancelBackGesture(): void;
+    /** Whether the user opted into the edge-swipe-back gesture. */
+    readonly edgeSwipeEnabled: boolean;
+}
+
+export const useNavInternals = defineInjectable<NavInternals>(() => {
+    throw new Error(
+        '[lynx-navigation] No <NavigationRoot> found in the component tree.',
+    );
+});

package/src/hooks/use-nav.ts

@@ -0,0 +1,118 @@
+import { defineInjectable } from '@sigx/lynx';
+import type { RegisteredRoutes, RouteId, RouteParams, RouteSearch } from '../register.js';
+import type {
+    PopOptions,
+    PushOptions,
+    RouteRequiresParams,
+    StackEntry,
+    TransitionState,
+} from '../types.js';
+
+/**
+ * Subset of registered route names that declare a `params` schema (and so
+ * require a `params` argument when navigating).
+ *
+ * Computed via mapped-type filtering rather than a conditional inside the
+ * method signature: when a conditional like `RouteRequiresParams<R[K]>` is
+ * embedded inside a generic method parameter, TS evaluates it at definition
+ * time with K bound to the *whole* union of route ids — which distributes
+ * `RouteRequiresParams` over every route and collapses the result to
+ * `boolean`, breaking the conditional. Filtering once at the type level avoids
+ * the issue and produces clean overload candidates.
+ */
+export type RoutesWithParams = {
+    [K in RouteId]: RouteRequiresParams<RegisteredRoutes[K]> extends true ? K : never;
+}[RouteId];
+
+/** Routes that don't declare a `params` schema. */
+export type RoutesWithoutParams = Exclude<RouteId, RoutesWithParams>;
+
+/**
+ * The navigator handle returned by `useNav()`.
+ *
+ * Read access (`current`, `stack`, `canGoBack`) is reactive — these properties
+ * are getters that read from the underlying stack signal, so accessing them
+ * inside a component's render function (or inside `effect` / `computed`) takes
+ * a reactive dependency. Mutating methods (`push`, `pop`, etc.) trigger the
+ * dependents to update.
+ *
+ * `push` and `replace` are split into two overloads — one for routes without a
+ * params schema (no params arg) and one for routes with a params schema
+ * (params required). See `RoutesWithParams` above for why this isn't a single
+ * conditional return type.
+ */
+export interface Nav {
+    /** Push a route that has no params schema. */
+    push<K extends RoutesWithoutParams>(
+        name: K,
+        search?: RouteSearch<K>,
+        options?: PushOptions,
+    ): void;
+    /** Push a route that requires params. */
+    push<K extends RoutesWithParams>(
+        name: K,
+        params: RouteParams<K>,
+        search?: RouteSearch<K>,
+        options?: PushOptions,
+    ): void;
+
+    /** Replace the top entry — same overload pattern as push. */
+    replace<K extends RoutesWithoutParams>(
+        name: K,
+        search?: RouteSearch<K>,
+        options?: PushOptions,
+    ): void;
+    replace<K extends RoutesWithParams>(
+        name: K,
+        params: RouteParams<K>,
+        search?: RouteSearch<K>,
+        options?: PushOptions,
+    ): void;
+
+    /** Pop one or more entries off the top of the stack. */
+    pop(count?: number, options?: PopOptions): void;
+
+    /** Pop entries until the named route is at the top. */
+    popTo<K extends RouteId>(name: K): void;
+
+    /** Pop all the way to the root entry. */
+    popToRoot(): void;
+
+    /** Wholesale-replace the stack. */
+    reset(state: { stack: ReadonlyArray<StackEntry> }): void;
+
+    /** Dismiss the topmost modal stack (no-op if none active). */
+    dismiss(): void;
+
+    /** Currently-focused entry. Reactive via property access. */
+    readonly current: StackEntry;
+
+    /** Full stack, top last. Reactive. */
+    readonly stack: ReadonlyArray<StackEntry>;
+
+    /** Whether the user can go back from the current entry. Reactive. */
+    readonly canGoBack: boolean;
+
+    /** Parent navigator (e.g. the Tabs above this Stack), or null at the root. */
+    readonly parent: Nav | null;
+
+    /**
+     * In-flight transition, or null when navigation is at rest. Reactive —
+     * `<Stack>` reads this to decide whether to render one screen or two
+     * (during a slide transition both the outgoing and incoming screens
+     * stay mounted with `useAnimatedStyle`-driven transforms).
+     */
+    readonly transition: TransitionState | null;
+}
+
+/**
+ * Access the innermost navigator. Provided by `<NavigationRoot>` via
+ * `defineProvide`. Throws when called outside a NavigationRoot subtree.
+ *
+ * Mirrors `@sigx/router`'s `useRouter` pattern (`packages/router/src/router.ts:30`).
+ */
+export const useNav = defineInjectable<Nav>(() => {
+    throw new Error(
+        '[lynx-navigation] useNav() called but no <NavigationRoot> is mounted in the component tree.',
+    );
+});

package/src/hooks/use-params.ts

@@ -0,0 +1,23 @@
+import type { RouteId, RouteParams } from '../register.js';
+import { useNav } from './use-nav.js';
+
+/**
+ * Read the typed params for the current screen, asserted against the named
+ * route from the registry.
+ *
+ * Returns the current entry's params snapshot. The `name` arg is the type
+ * discriminator at compile time; we don't currently runtime-check that the
+ * caller's route matches the active entry — the dev-mode warning lands in a
+ * later slice along with schema validation.
+ *
+ * **Reactivity**: each `nav.push` / `replace` produces a new entry with a
+ * fresh `key`. `<Stack>` keys the rendered component on `entry.key`, so the
+ * screen component fully remounts on every navigation — useParams runs again
+ * during the new mount and reads the new params. There is no "in-place params
+ * update for the same mounted screen" path in v0.1, so a snapshot at setup
+ * time is correct.
+ */
+export function useParams<K extends RouteId>(_name: K): RouteParams<K> {
+    const nav = useNav();
+    return nav.current.params as RouteParams<K>;
+}

package/src/hooks/use-search.ts

@@ -0,0 +1,15 @@
+import type { RouteId, RouteSearch } from '../register.js';
+import { useNav } from './use-nav.js';
+
+/**
+ * Read the typed search/query params for the current screen, asserted against
+ * the named route from the registry.
+ *
+ * Returns the current entry's search snapshot. See `useParams` for the
+ * reactivity story — each navigation triggers a remount via the entry-keyed
+ * Stack, so a setup-time snapshot is sufficient.
+ */
+export function useSearch<K extends RouteId>(_name: K): RouteSearch<K> {
+    const nav = useNav();
+    return nav.current.search as RouteSearch<K>;
+}

package/src/href.ts

@@ -0,0 +1,58 @@
+import type { RouteId, RouteParams, RouteSearch } from './register.js';
+import type { RoutesWithoutParams, RoutesWithParams } from './hooks/use-nav.js';
+
+/**
+ * A typed reference to a navigation target — what `<Link to={...}>` consumes
+ * and what `hrefFor()` produces.
+ *
+ * Holds both the typed pieces (route name, params, search) and the serialized
+ * URL form (when the route declares a `path` template). Either side can drive
+ * navigation — typed for in-app links, URL for deep links / sharing.
+ */
+export interface Href<K extends RouteId = RouteId> {
+    readonly route: K;
+    readonly params: RouteParams<K>;
+    readonly search: RouteSearch<K>;
+    /** URL form. `null` when the route declares no `path` template. */
+    readonly url: string | null;
+}
+
+/**
+ * Build a typed Href for a given route. Validates params against the route's
+ * schema at runtime; type-checks them at compile time.
+ *
+ * Overloaded the same way as `nav.push` — one signature for routes without a
+ * params schema, one for routes that require params. See `RoutesWithParams`
+ * in `./hooks/use-nav.js` for why this isn't expressed as a single conditional.
+ *
+ * @example
+ * ```ts
+ * hrefFor('profile', { id: '42' });               // → { route, params, search: {}, url: '/users/42' }
+ * hrefFor('profile', { id: '42' }, { tab: 'about' });
+ * hrefFor('home');                                // params arg omitted (no schema)
+ * ```
+ */
+export function hrefFor<K extends RoutesWithoutParams>(name: K, search?: RouteSearch<K>): Href<K>;
+export function hrefFor<K extends RoutesWithParams>(
+    name: K,
+    params: RouteParams<K>,
+    search?: RouteSearch<K>,
+): Href<K>;
+export function hrefFor(name: string, ..._args: unknown[]): Href {
+    void name;
+    void _args;
+    throw new Error(
+        'hrefFor() runtime is not implemented yet — this is the type spike.',
+    );
+}
+
+/**
+ * Parse a URL string into a typed Href against the registered routes.
+ * Returns `null` if no route's `path` template matches.
+ */
+export function parseHref(url: string): Href | null {
+    void url;
+    throw new Error(
+        'parseHref() runtime is not implemented yet — this is the type spike.',
+    );
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @sigx/lynx-navigation — type-first native stack router.
+ *
+ * Phase 0.1 (current): typed registry, stack runtime, NavigationRoot + Stack.
+ * Coming next: Screen with slot-based header API, MTS transitions, Tabs.
+ */
+
+export { defineRoutes } from './define-routes.js';
+export type { Register, RegisteredRoutes, RouteId, RouteParams, RouteSearch } from './register.js';
+export { useNav } from './hooks/use-nav.js';
+export type { Nav, RoutesWithoutParams, RoutesWithParams } from './hooks/use-nav.js';
+export { useParams } from './hooks/use-params.js';
+export { useSearch } from './hooks/use-search.js';
+export { useHardwareBack } from './hooks/use-hardware-back.js';
+export { hrefFor, parseHref } from './href.js';
+export type { Href } from './href.js';
+export { NavigationRoot } from './components/NavigationRoot.js';
+export { Stack } from './components/Stack.js';
+export { Link } from './components/Link.js';
+export type { LinkProps } from './components/Link.js';
+export type {
+    ComponentLike,
+    EmptyParams,
+    InferOutput,
+    ParamsOf,
+    PopOptions,
+    Presentation,
+    PushOptions,
+    RouteDefinition,
+    RouteMap,
+    RouteRequiresParams,
+    SearchOf,
+    StackEntry,
+    StandardSchemaV1,
+    TransitionKind,
+    TransitionRole,
+    TransitionState,
+} from './types.js';

package/src/internal/screen-width.ts

@@ -0,0 +1,34 @@
+/**
+ * Logical screen width (in dp) read from `lynx.SystemInfo` at module load.
+ * Falls back to 400 (typical phone) if SystemInfo isn't available — module
+ * load happens BG-side after the bundle initializes, by which time
+ * `lynx.SystemInfo` is populated, so the fallback only fires in tests / SSR /
+ * non-Lynx hosts.
+ *
+ * Used by:
+ *   - `<ScreenContainer>` for the slide-from-right transform output range.
+ *   - `<EdgeBackHandle>` for the gesture commit threshold (`dx / width`).
+ *
+ * Both must agree, otherwise the commit threshold and the animation
+ * geometry won't line up. Single shared constant avoids drift.
+ */
+
+declare const lynx:
+    | { SystemInfo?: { pixelWidth?: number; pixelRatio?: number } }
+    | undefined;
+
+function readScreenWidth(): number {
+    try {
+        const info = typeof lynx !== 'undefined' ? lynx?.SystemInfo : undefined;
+        const pw = info?.pixelWidth;
+        const pr = info?.pixelRatio || 1;
+        if (typeof pw === 'number' && pw > 0) {
+            return Math.round(pw / pr);
+        }
+    } catch {
+        // Lynx globals not present (test env / SSR) — use fallback.
+    }
+    return 400;
+}
+
+export const SCREEN_WIDTH = readScreenWidth();