@sigx/lynx-navigation 0.1.0 → 0.1.1

package/src/types.ts

@@ -51,6 +51,20 @@ export interface RouteDefinition<
 > {
     /** Component factory or lazy importer. */
     component: ComponentLike;
+    /**
+     * Fallback shown while a lazy `component` is loading.
+     *
+     * Set this only on routes whose `component` was created with `lazy(...)`.
+     * The fallback is rendered inside a `<Suspense>` boundary wrapping the
+     * screen mount, so the user sees this UI while the screen's chunk is
+     * being fetched. When omitted, lazy routes still work — the caller is
+     * responsible for placing its own `<Suspense>` boundary (e.g. above the
+     * `<NavigationRoot>` or inside the screen component).
+     *
+     * Accepts a component factory (`MyLoadingScreen`) or a function returning
+     * JSX (`() => <Spinner />`). Eager routes ignore this field.
+     */
+    fallback?: ComponentLike | (() => unknown);
     /** Standard-Schema validator for path params. Optional. */
     params?: Params;
     /** Standard-Schema validator for query/search params. Optional. */
@@ -169,3 +183,45 @@ export interface TransitionState {
     /** Animation progress signal — typed loosely; cast at the runtime boundary. */
     readonly progress: unknown;
 }
+
+/**
+ * Per-screen display options written by `<Screen>` into its entry's registry.
+ *
+ * Read by persistent navigator chrome (the `<HeaderBar>` shipped in the
+ * `header` slice; `<TabBar>` later). All fields are optional — consumers
+ * apply sensible defaults (headerShown defaults to true, gestureEnabled to
+ * true, title falls back to the route name).
+ *
+ * `title` accepts a function so the header can be derived from reactive
+ * state (e.g. a user's display name signal). Plain strings are wrapped in
+ * a thunk by consumers when read.
+ */
+export interface ScreenOptions {
+    /** Header title. Either a static string or a getter (re-tracked each render). */
+    title?: string | (() => string);
+    /** When false, the navigator's header is hidden for this screen. Default true. */
+    headerShown?: boolean;
+    /** When false, the iOS edge-swipe-back gesture is disabled for this screen. Default true. */
+    gestureEnabled?: boolean;
+}
+
+/**
+ * Slot fills written by `<Screen.Header>` / `<Screen.HeaderLeft>` /
+ * `<Screen.HeaderRight>` / `<Screen.TabBarItem>`.
+ *
+ * Each fill is the rendered output of that sub-component's `default` slot,
+ * captured as a thunk so the navigator's persistent chrome can call it at
+ * render time. `tabBarItem` is a scoped slot — the consumer passes
+ * `{ active }` so the same screen's tab-bar item can style itself
+ * differently when focused vs. not.
+ */
+export interface ScreenSlotFills {
+    /** Full header replacement. When set, takes precedence over title + headerLeft/Right. */
+    header?: () => unknown;
+    /** Left-side header content (typically back arrow override). */
+    headerLeft?: () => unknown;
+    /** Right-side header content (typically action buttons). */
+    headerRight?: () => unknown;
+    /** Tab-bar item — scoped slot receives `{ active }` indicating focus. */
+    tabBarItem?: (ctx: { active: boolean }) => unknown;
+}

package/src/url/build.ts

@@ -0,0 +1,35 @@
+/**
+ * Typed → URL: build the `url` field of an Href from a route's params/search.
+ *
+ * Mirror of parse.ts. Used by `hrefFor()` after schema validation succeeds.
+ */
+
+import { formatSearch } from './format.js';
+import { getCompiledPath, getRouteRegistry } from './registry.js';
+
+/**
+ * Build the URL form of a route + params + search, or `null` if the route
+ * declares no `path` template (typed navigation still works — only deep-link
+ * serialization is unavailable).
+ *
+ * Params must already be valid for the route's schema (callers run this after
+ * `validateSync`). Search values are stringified as-is — schema-validated
+ * inputs survive round-tripping because `parseHref` re-runs the same schema.
+ */
+export function buildUrl(
+    routeName: string,
+    params: Record<string, unknown> | undefined,
+    search: Record<string, unknown> | undefined,
+): string | null {
+    const registry = getRouteRegistry();
+    const compiled = getCompiledPath(registry, routeName);
+    if (!compiled) return null;
+    const formatted = compiled.format(
+        // The compiler accepts string|number; we widen to unknown and let it
+        // String()-coerce. Booleans/null get filtered by the missing-param
+        // check, which is what we want — boolean path params don't exist.
+        (params ?? {}) as Record<string, string | number>,
+    );
+    const querystring = formatSearch(search);
+    return querystring.length > 0 ? `${formatted}?${querystring}` : formatted;
+}

package/src/url/compile.ts

@@ -0,0 +1,109 @@
+/**
+ * Path template compiler.
+ *
+ * Turns a route's `path` (e.g. `/users/:id/posts/:postId`) into a compiled
+ * object that can both match a URL pathname against it and format a typed
+ * params object back into a URL.
+ *
+ * Supported syntax (intentionally minimal for v1):
+ *   - Literal segments:  `/users`, `/users/me`
+ *   - Named params:      `:id` (matches `[^/]+`)
+ *   - Trailing slashes tolerated on match
+ *
+ * Out of scope for v1 (future-compatible — additions won't break v1 paths):
+ *   - Wildcards `*`
+ *   - Optional params `:id?`
+ *   - Typed/constrained params `:id<number>` or `:id(\\d+)`
+ */
+
+/** Result of compiling a path template — used by parse + format. */
+export interface CompiledPath {
+    readonly source: string;
+    readonly paramNames: readonly string[];
+    /** Regex that matches a URL pathname. Captures are param values in order. */
+    readonly regex: RegExp;
+    /**
+     * Render a URL pathname for this template given param values. Each value
+     * is `encodeURIComponent`-encoded. Throws if a required `:name` is missing.
+     */
+    format(params: Record<string, string | number>): string;
+}
+
+const PARAM_RE = /:([A-Za-z_][A-Za-z0-9_]*)/g;
+
+/**
+ * Compile a path template. Throws on malformed input (duplicate param names,
+ * unexpected `:` syntax). Pure — safe to memoize.
+ */
+export function compilePath(template: string): CompiledPath {
+    if (typeof template !== 'string') {
+        throw new TypeError(`compilePath: expected string, got ${typeof template}`);
+    }
+    if (template.length === 0) {
+        throw new Error('compilePath: path template must not be empty');
+    }
+    // Normalize: ensure leading `/`. Trailing slashes are tolerated on match,
+    // but the canonical formatted output preserves the template's trailing
+    // slash policy.
+    const normalized = template.startsWith('/') ? template : `/${template}`;
+
+    const paramNames: string[] = [];
+    // Build the regex by replacing :name with a capture group. We escape the
+    // surrounding literal text so paths with regex-special chars (`.`, `+`)
+    // match literally — only `:name` is treated as a placeholder.
+    let lastIndex = 0;
+    let pattern = '';
+    PARAM_RE.lastIndex = 0;
+    for (let m = PARAM_RE.exec(normalized); m !== null; m = PARAM_RE.exec(normalized)) {
+        const name = m[1];
+        if (paramNames.includes(name)) {
+            throw new Error(
+                `compilePath: duplicate param name ':${name}' in '${template}'`,
+            );
+        }
+        paramNames.push(name);
+        pattern += escapeRegex(normalized.slice(lastIndex, m.index));
+        pattern += '([^/]+)';
+        lastIndex = m.index + m[0].length;
+    }
+    pattern += escapeRegex(normalized.slice(lastIndex));
+
+    // Trim a trailing slash from the pattern so `/users/` and `/users` both
+    // match `/users/:?`. We keep the formatter's output as-templated.
+    const matchPattern = pattern.endsWith('/') ? pattern.slice(0, -1) : pattern;
+    const regex = new RegExp(`^${matchPattern}/?$`);
+
+    return {
+        source: template,
+        paramNames,
+        regex,
+        format(params: Record<string, string | number>): string {
+            let out = '';
+            let i = 0;
+            PARAM_RE.lastIndex = 0;
+            for (
+                let m = PARAM_RE.exec(normalized);
+                m !== null;
+                m = PARAM_RE.exec(normalized)
+            ) {
+                const name = m[1];
+                const value = params[name];
+                if (value === undefined || value === null) {
+                    throw new Error(
+                        `compilePath.format: missing required param ':${name}' for '${template}'`,
+                    );
+                }
+                out += normalized.slice(i, m.index);
+                out += encodeURIComponent(String(value));
+                i = m.index + m[0].length;
+            }
+            out += normalized.slice(i);
+            return out;
+        },
+    };
+}
+
+const REGEX_SPECIALS = /[.*+?^${}()|[\]\\]/g;
+function escapeRegex(s: string): string {
+    return s.replace(REGEX_SPECIALS, '\\$&');
+}

package/src/url/format.ts

@@ -0,0 +1,92 @@
+/**
+ * Format helpers: typed params/search → URL string.
+ *
+ * Used by `hrefFor()` to render the `url` field of an Href.
+ */
+
+/**
+ * Serialize an object as a `key=value&key=value` querystring.
+ *
+ * Keys are sorted to make the output deterministic (useful for tests and
+ * persistence diffs). `undefined`/`null` values are skipped. Non-primitive
+ * values are JSON-stringified — parseHref reverses this on the receiving end.
+ *
+ * Returns `''` (empty string) when there are no entries — callers join with
+ * `?` only when the result is non-empty.
+ */
+export function formatSearch(search: Record<string, unknown> | undefined): string {
+    if (!search) return '';
+    const keys = Object.keys(search).sort();
+    const parts: string[] = [];
+    for (const key of keys) {
+        const value = search[key];
+        if (value === undefined || value === null) continue;
+        const encoded = encodeURIComponent(key);
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item === undefined || item === null) continue;
+                parts.push(`${encoded}=${encodeURIComponent(serializeScalar(item))}`);
+            }
+        } else {
+            parts.push(`${encoded}=${encodeURIComponent(serializeScalar(value))}`);
+        }
+    }
+    return parts.join('&');
+}
+
+/**
+ * Parse a `key=value&key=value` querystring into a string-keyed bag. Values
+ * are decoded but kept as strings — typed coercion happens in the route's
+ * `search` schema (e.g. Zod's `z.coerce.number()`).
+ *
+ * Multiple occurrences of the same key produce an array. Schemas that don't
+ * expect arrays will reject this — that's the right failure mode.
+ */
+export function parseSearch(query: string): Record<string, string | string[]> {
+    const result: Record<string, string | string[]> = {};
+    if (!query) return result;
+    // Strip leading `?` if present (formatHref doesn't include it but callers
+    // sometimes pass `?a=1`).
+    const cleaned = query.startsWith('?') ? query.slice(1) : query;
+    if (!cleaned) return result;
+    for (const pair of cleaned.split('&')) {
+        if (!pair) continue;
+        const eqIdx = pair.indexOf('=');
+        const rawKey = eqIdx === -1 ? pair : pair.slice(0, eqIdx);
+        const rawValue = eqIdx === -1 ? '' : pair.slice(eqIdx + 1);
+        const key = safeDecode(rawKey);
+        const value = safeDecode(rawValue);
+        const existing = result[key];
+        if (existing === undefined) {
+            result[key] = value;
+        } else if (Array.isArray(existing)) {
+            existing.push(value);
+        } else {
+            result[key] = [existing, value];
+        }
+    }
+    return result;
+}
+
+function serializeScalar(v: unknown): string {
+    switch (typeof v) {
+        case 'string': return v;
+        case 'number':
+        case 'boolean':
+        case 'bigint':
+            return String(v);
+        default:
+            // Objects/arrays/etc — JSON. Schemas can decide how to interpret.
+            return JSON.stringify(v);
+    }
+}
+
+function safeDecode(s: string): string {
+    try {
+        return decodeURIComponent(s.replace(/\+/g, ' '));
+    } catch {
+        // Malformed % escape — fall back to the raw text rather than throwing
+        // from a navigation hot path. The schema will reject if it matters.
+        return s;
+    }
+}

package/src/url/index.ts

@@ -0,0 +1,18 @@
+/**
+ * URL bridge — internal barrel.
+ *
+ * Not re-exported from the package root. Public surface is `hrefFor` /
+ * `parseHref` in ../href.ts plus `_setRouteRegistry` for tests/bootstrap.
+ */
+
+export { compilePath, type CompiledPath } from './compile.js';
+export { buildUrl } from './build.js';
+export { parseHrefImpl } from './parse.js';
+export { formatSearch, parseSearch } from './format.js';
+export {
+    _setRouteRegistry,
+    _clearRouteRegistry,
+    getRouteRegistry,
+    getCompiledPath,
+} from './registry.js';
+export { validateSync, type ValidateOutcome } from './validate.js';

package/src/url/parse.ts

@@ -0,0 +1,97 @@
+/**
+ * URL → typed Href parser.
+ *
+ * Walks every registered route with a `path`, tries to match its compiled
+ * regex against the URL's pathname, and on a hit validates the extracted
+ * params + search through the route's Standard Schema. First match wins;
+ * iteration order follows `Object.keys` of the registered routes map.
+ *
+ * Validation failures return `null` rather than throwing — deep-link handlers
+ * fall back to the initial route on a bad URL instead of crashing the app.
+ */
+
+import type { Href } from '../href.js';
+import type { RouteId } from '../register.js';
+import { parse as parseUrl } from '@sigx/lynx-linking';
+import type { CompiledPath } from './compile.js';
+import { parseSearch } from './format.js';
+import { getCompiledPath, getRouteRegistry } from './registry.js';
+import { validateSync } from './validate.js';
+
+/**
+ * Parse a URL string against the active route registry.
+ *
+ * Accepts both absolute URLs (`myapp://host/users/42?tab=about`) and
+ * pathname-only forms (`/users/42?tab=about`). Returns `null` if no route's
+ * `path` matches the URL or if schema validation rejects the extracted bits.
+ */
+export function parseHrefImpl(url: string): Href | null {
+    if (typeof url !== 'string' || url.length === 0) return null;
+
+    // Use lynx-linking's parser for the scheme/host split — but accept paths
+    // that don't have a scheme too (raw `/users/42` is the common case from
+    // in-app routing).
+    const { pathname, query } = splitPathAndQuery(url);
+    if (!pathname) return null;
+
+    const registry = getRouteRegistry();
+    const rawSearch = parseSearch(query);
+
+    for (const name of Object.keys(registry.routes)) {
+        const compiled = getCompiledPath(registry, name);
+        if (!compiled) continue;
+        const match = compiled.regex.exec(pathname);
+        if (!match) continue;
+
+        const rawParams = extractParams(compiled, match);
+        const def = registry.routes[name];
+
+        const paramsOutcome = validateSync(def.params, rawParams);
+        if (!paramsOutcome.ok) continue;
+        const searchOutcome = validateSync(def.search, rawSearch);
+        if (!searchOutcome.ok) continue;
+
+        return {
+            route: name as RouteId,
+            params: paramsOutcome.value as Record<string, never>,
+            search: searchOutcome.value as Record<string, never>,
+            url,
+        };
+    }
+    return null;
+}
+
+function extractParams(
+    compiled: CompiledPath,
+    match: RegExpExecArray,
+): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (let i = 0; i < compiled.paramNames.length; i++) {
+        const raw = match[i + 1];
+        try {
+            out[compiled.paramNames[i]] = decodeURIComponent(raw);
+        } catch {
+            out[compiled.paramNames[i]] = raw;
+        }
+    }
+    return out;
+}
+
+function splitPathAndQuery(url: string): { pathname: string; query: string } {
+    // If the URL has a scheme, defer to lynx-linking's parser — handles
+    // `myapp://host/path?q` correctly. Otherwise treat the whole thing as
+    // pathname+query.
+    const hasScheme = /^[a-zA-Z][a-zA-Z0-9+.\-]*:/.test(url);
+    if (hasScheme) {
+        const parsed = parseUrl(url);
+        // Reconstruct the query string from the already-parsed bag. We have
+        // to do this because parseUrl decoded keys/values, but parseSearch
+        // expects encoded form. Simpler: split the original ourselves.
+        const qIdx = url.indexOf('?');
+        const query = qIdx >= 0 ? url.slice(qIdx + 1) : '';
+        return { pathname: parsed.path, query };
+    }
+    const qIdx = url.indexOf('?');
+    if (qIdx === -1) return { pathname: url, query: '' };
+    return { pathname: url.slice(0, qIdx), query: url.slice(qIdx + 1) };
+}

package/src/url/registry.ts

@@ -0,0 +1,69 @@
+/**
+ * Module-level route registry for the URL bridge.
+ *
+ * `hrefFor()` and `parseHref()` are designed to be callable from anywhere —
+ * including outside the component tree (e.g. deep-link bootstrapping in
+ * native bridge code). They can't reach the in-tree `useNavRoutes` injectable
+ * directly, so we mirror the active routes here.
+ *
+ * `<NavigationRoot>` sets this synchronously during setup. Tests that exercise
+ * the URL helpers without a NavigationRoot can call `_setRouteRegistry`
+ * directly. The leading underscore is a convention: not part of the supported
+ * public API (test/integration use only).
+ */
+
+import type { CompiledPath } from './compile.js';
+import { compilePath } from './compile.js';
+import type { RouteMap } from '../types.js';
+
+interface RegistryState {
+    readonly routes: RouteMap;
+    /** Lazy-compiled paths keyed by route name. */
+    readonly compiled: Map<string, CompiledPath>;
+}
+
+let current: RegistryState | null = null;
+
+/**
+ * Set the active route registry. Called by `<NavigationRoot>` on setup and
+ * available to tests/bootstrap code as `_setRouteRegistry`.
+ *
+ * Last write wins — multi-root apps and rapid mount/unmount cycles in tests
+ * always see the most recent `<NavigationRoot>`'s routes. If you need a
+ * specific registry for a one-off call, pass it explicitly to the helper
+ * (parseHrefWithRoutes / hrefForWithRoutes — currently internal).
+ */
+export function _setRouteRegistry(routes: RouteMap): void {
+    current = { routes, compiled: new Map() };
+}
+
+/** Clear the registry. Mainly for tests that want to assert the unset path. */
+export function _clearRouteRegistry(): void {
+    current = null;
+}
+
+/** Get the active registry or throw a friendly error if none is set. */
+export function getRouteRegistry(): RegistryState {
+    if (!current) {
+        throw new Error(
+            '[lynx-navigation] No route registry set — render a <NavigationRoot> first, or call _setRouteRegistry() for tests.',
+        );
+    }
+    return current;
+}
+
+/**
+ * Look up (or lazily compile) the path template for a route name. Returns
+ * `null` when the route exists but declares no `path`.
+ */
+export function getCompiledPath(registry: RegistryState, name: string): CompiledPath | null {
+    const def = registry.routes[name];
+    if (!def) return null;
+    if (!def.path) return null;
+    let compiled = registry.compiled.get(name);
+    if (!compiled) {
+        compiled = compilePath(def.path);
+        registry.compiled.set(name, compiled);
+    }
+    return compiled;
+}

package/src/url/validate.ts

@@ -0,0 +1,67 @@
+/**
+ * Standard Schema validation helper (sync only).
+ *
+ * `hrefFor` and `parseHref` run on hot paths (link rendering, deep-link
+ * resolution) so we restrict to sync validators. Zod/Valibot/ArkType are all
+ * sync, which covers the common case. Async validators throw a clear error.
+ */
+
+import type { StandardSchemaV1 } from '../types.js';
+
+/**
+ * Extended runtime view of a Standard Schema — adds the `validate` function
+ * that the spec mandates but `types.ts`'s minimal type omits (for test-fixture
+ * ergonomics). Treat any schema-shaped object as potentially carrying it.
+ */
+interface StandardSchemaRuntime {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate?: (input: unknown) => StandardResult | PromiseLike<StandardResult>;
+    };
+}
+
+type StandardResult =
+    | { readonly value: unknown; readonly issues?: undefined }
+    | { readonly issues: ReadonlyArray<{ readonly message: string }> };
+
+/** Outcome of a sync validation call — discriminated for explicit handling. */
+export type ValidateOutcome =
+    | { readonly ok: true; readonly value: unknown }
+    | { readonly ok: false; readonly issues: ReadonlyArray<string> };
+
+/**
+ * Run a Standard Schema's `validate` synchronously. When the schema lacks a
+ * `validate` function (e.g. our test `fakeSchema`), passthrough — assume the
+ * input is already in the correct shape. This is a deliberate ergonomic
+ * choice so the type-spike fixtures stay terse.
+ */
+export function validateSync(
+    schema: StandardSchemaV1 | undefined,
+    input: unknown,
+): ValidateOutcome {
+    if (!schema) return { ok: true, value: input };
+    const validate = (schema as StandardSchemaRuntime)['~standard']?.validate;
+    if (!validate) return { ok: true, value: input };
+    const result = validate(input);
+    if (isPromiseLike(result)) {
+        throw new Error(
+            '[lynx-navigation] Async schema validation is not supported on the URL bridge — use a sync validator (Zod/Valibot/ArkType are all sync).',
+        );
+    }
+    if (result.issues !== undefined && result.issues.length > 0) {
+        return {
+            ok: false,
+            issues: result.issues.map((i) => i.message),
+        };
+    }
+    return { ok: true, value: (result as { value: unknown }).value };
+}
+
+function isPromiseLike<T>(v: unknown): v is PromiseLike<T> {
+    return (
+        v !== null
+        && typeof v === 'object'
+        && typeof (v as { then?: unknown }).then === 'function'
+    );
+}