@sigx/lynx-navigation 0.4.0 → 0.4.2

package/src/types.d.ts

@@ -1,217 +0,0 @@
-/**
- * Core types for @sigx/lynx-navigation.
- *
- * The type machinery here is the differentiating DX: route names, params, and
- * search are all inferred end-to-end from the user's `defineRoutes` call so
- * `nav.push('profile', { id: 42 })` is a TS error if `id` is typed as string.
- */
-/**
- * Minimal Standard Schema spec subset — see https://standardschema.dev.
- * Inlined so we don't depend on `@standard-schema/spec` for the type spike.
- * Compatible with Zod, Valibot, ArkType, etc.
- */
-export interface StandardSchemaV1<Input = unknown, Output = Input> {
-    readonly '~standard': {
-        readonly version: 1;
-        readonly vendor: string;
-        readonly types?: {
-            readonly input: Input;
-            readonly output: Output;
-        };
-    };
-}
-/**
- * Infer the validated output type of a Standard Schema, falling back to
- * `unknown` for non-schema values.
- */
-export type InferOutput<S> = S extends StandardSchemaV1<unknown, infer O> ? O : unknown;
-/** Empty record — what `ParamsOf` returns when a route declares no schema. */
-export type EmptyParams = Record<string, never>;
-/**
- * How a route entry is presented on the stack.
- * `card` is the default push; `modal`/`fullScreen` slide up; `transparent-modal`
- * preserves the underlying screen visible (e.g. for popovers).
- */
-export type Presentation = 'card' | 'modal' | 'fullScreen' | 'transparent-modal';
-/**
- * A route definition entry.
- *
- * Users construct this via `defineRoutes({...})`. The `params` and `search`
- * schemas drive runtime validation AND TS inference for `useParams`,
- * `useSearch`, `nav.push`, `<Link>`, etc.
- *
- * `component` accepts an eager component factory or a lazy import — both shapes
- * resolve through sigx's `<Suspense>` boundary at render time.
- */
-export interface RouteDefinition<Params extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, Search extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined> {
-    /** 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. */
-    search?: Search;
-    /** Optional URL pattern for deep-link serialization (e.g. `/users/:id`). */
-    path?: string;
-    /** Default presentation when this route is pushed. */
-    presentation?: Presentation;
-    /** Nested routes — share the URL/path namespace and may inherit options. */
-    children?: Record<string, RouteDefinition>;
-}
-/**
- * The component shape we accept on a route. Kept structural so we don't pull
- * `ComponentFactory` from sigx at type level (avoids a hard dep on sigx purely
- * for types in the spike). Refined to a real ComponentFactory in Phase 0.1
- * runtime work.
- */
-export type ComponentLike = ((...args: any[]) => unknown) | (() => Promise<{
-    default: (...args: any[]) => unknown;
-}>);
-/**
- * Map of route definitions, as returned by `defineRoutes`. Keys are route
- * names; values are typed RouteDefinitions.
- */
-export type RouteMap = Record<string, RouteDefinition>;
-/**
- * Extract params type from a single RouteDefinition.
- * Falls back to `EmptyParams` when the route declares no schema.
- *
- * We use a structural `params: infer S` match (without an `extends
- * StandardSchemaV1` constraint on `S`) because TS conditional types treat the
- * generic-defaulted `StandardSchemaV1<unknown, unknown>` as invariant in this
- * position — a schema typed `StandardSchemaV1<{id:string}>` does not match
- * `extends StandardSchemaV1` reliably under `<const T>` inference. `InferOutput`
- * gracefully handles non-schema `S` by returning `unknown`.
- */
-export type ParamsOf<R> = R extends {
-    params: infer S;
-} ? InferOutput<S> : EmptyParams;
-/**
- * Extract search type from a single RouteDefinition.
- * Falls back to `EmptyParams` when the route declares no schema.
- */
-export type SearchOf<R> = R extends {
-    search: infer S;
-} ? InferOutput<S> : EmptyParams;
-/**
- * Whether a route requires a `params` argument when calling `nav.push` etc.
- * True iff the route definition has a `params` field.
- */
-export type RouteRequiresParams<R> = R extends {
-    params: object;
-} ? true : false;
-/**
- * Per-entry state stored on the stack signal.
- *
- * `key` is unique per entry — needed because the same route can appear more
- * than once (e.g. profile A → message → profile A again). Focus state and
- * scroll position are keyed by `key`, not by route name.
- */
-export interface StackEntry<R extends string = string, P = unknown, S = unknown> {
-    readonly key: string;
-    readonly route: R;
-    readonly params: P;
-    readonly search: S;
-    /** User state — survives suspend/restore. */
-    state: unknown;
-    readonly presentation: Presentation;
-}
-/** Options accepted by `nav.push` / `nav.replace`. */
-export interface PushOptions {
-    /** Override the route's default presentation for this navigation. */
-    presentation?: Presentation;
-    /** User state to attach to the new entry. Survives suspend/restore. */
-    state?: unknown;
-    /**
-     * Skip the slide animation (instant swap). Defaults to true on platforms
-     * where `useAnimatedStyle` isn't available (test renderer); defaults to
-     * false on real Lynx. Tests can force `false` to keep assertions
-     * deterministic.
-     */
-    animated?: boolean;
-}
-/** Options accepted by `nav.pop`. */
-export interface PopOptions {
-    /** Skip the slide animation (instant swap). See `PushOptions.animated`. */
-    animated?: boolean;
-}
-/**
- * Direction of an in-flight transition.
- *  - `push`: a new entry is animating in (progress 0 → 1).
- *  - `pop`:  the current top is animating out (progress 0 → 1, then committed).
- */
-export type TransitionKind = 'push' | 'pop';
-/** Role of a screen during a transition — determines its transform formula. */
-export type TransitionRole = 'top' | 'underneath';
-/**
- * Snapshot of an in-flight transition. Stored on the navigator state so the
- * `<Stack>` component knows to render two entries (`topEntry` above
- * `underneathEntry`) and bind their transforms to `progress`.
- *
- * `progress` is a `SharedValue<number>` (re-exported as `unknown` here to
- * avoid a hard dep on `@sigx/lynx`'s SharedValue type at the contract level —
- * the runtime `<Stack>` casts as needed). The value runs 0 → 1 in both push
- * and pop, with the role/kind pair determining the visual direction.
- */
-export interface TransitionState {
-    readonly kind: TransitionKind;
-    readonly topEntry: StackEntry;
-    readonly underneathEntry: StackEntry;
-    /** 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.d.ts

@@ -1,15 +0,0 @@
-/**
- * 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.
- */
-/**
- * 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 declare function buildUrl(routeName: string, params: Record<string, unknown> | undefined, search: Record<string, unknown> | undefined): string | null;

package/src/url/compile.d.ts

@@ -1,34 +0,0 @@
-/**
- * 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;
-}
-/**
- * Compile a path template. Throws on malformed input (duplicate param names,
- * unexpected `:` syntax). Pure — safe to memoize.
- */
-export declare function compilePath(template: string): CompiledPath;

package/src/url/format.d.ts

@@ -1,28 +0,0 @@
-/**
- * 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 on the way out — `parseSearch` returns the
- * raw string and leaves any JSON decoding to the route's `search` schema
- * (e.g. a Zod `transform`), so the round-trip is intentionally one-way at
- * this layer.
- *
- * Returns `''` (empty string) when there are no entries — callers join with
- * `?` only when the result is non-empty.
- */
-export declare function formatSearch(search: Record<string, unknown> | undefined): string;
-/**
- * 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 declare function parseSearch(query: string): Record<string, string | string[]>;

package/src/url/parse.d.ts

@@ -1,20 +0,0 @@
-/**
- * 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';
-/**
- * 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 declare function parseHrefImpl(url: string): Href | null;

package/src/url/validate.d.ts

@@ -1,23 +0,0 @@
-/**
- * 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';
-/** 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 declare function validateSync(schema: StandardSchemaV1 | undefined, input: unknown): ValidateOutcome;