@gyral/router

npm install @gyral/router

function listen<M>(toMsg: (location: RouteLocation) => M | undefined): Command<M>;

subscriptions: () => [listen((location) => ({ _tag: 'Routed', location }))]

function makeRouter(options?: RouterOptions): RouterDriver;

function navigate(url: string, options?: NavigateOptions): Command<never>;

function routes<const T extends RouteTable>(table: T, options?: {
    readonly matcher?: Matcher;
}): Routes<T>;

function setHead(head: Head): Command<never>;

Routed: (s, m) => [next, [setHead(pageHead(site.match(m.location.href), origin))]]

const router: RouterDriver

interface AfterNavigation {
    /** Scroll to the `#fragment` target or the top (push), or restore (back/forward). */
    readonly scroll: boolean;
    /** Move focus to the first `[autofocus]` element, or reset it to the page start. */
    readonly focusReset: boolean;
}

type LocationLike = Pick<Location, 'href' | 'origin' | 'pathname' | 'search'>;

type Matcher = 'auto' | 'urlpattern' | 'fallback';

interface MemoryOptions {
    /** Starting URL, absolute or relative to `origin`. Default `'/'`. */
    readonly initial?: string;
    /** Origin that relative URLs resolve against. Default `'http://localhost'`. */
    readonly origin?: string;
    /**
     * Intercept same-origin link clicks. **Default `false`** (opt in): a router that captures
     * every link on the page breaks multi-page apps where only one component routes (ADR 0009).
     */
    readonly captureLinks?: boolean;
    /**
     * Where to capture link clicks when `captureLinks` is on. Default: the (global, or the
     * browser history's) `document`. Passing an element also turns capture on and limits it to
     * that subtree; `null` turns it off. Capture is only active while a component listens.
     */
    readonly linkRoot?: EventTarget | null;
}

interface NavigateOptions extends Partial<AfterNavigation> {
    /** Replace the current history entry instead of pushing one. Default `false`. */
    readonly replace?: boolean;
}

type Params<Path extends string> = Path extends `${infer Head}/${infer Rest}` ? Param<Head> & Params<Rest> : Param<Path>;

interface RouteLocation {
    readonly href: string;
    readonly pathname: string;
    readonly search: string;
    readonly hash: string;
    /** Increases on every URL change seen by this router. */
    readonly seq: number;
}

type RouteMatch<T extends RouteTable> = {
    [N in keyof T & string]: {
        readonly name: N;
        readonly params: Params<T[N]>;
        readonly path: string;
    };
}[keyof T & string];

interface RouterDriver extends Driver<RouterInput, RouteLocation | undefined> {
    /** The current URL and last head as this router sees them. */
    readonly snapshot: () => RouterSnapshot;
    /** Removes document listeners and ends running `listen` commands. */
    readonly dispose: () => void;
}

type RouterInput = ({
    readonly _tag: 'Navigate';
    readonly url: string;
    readonly replace: boolean;
} & Partial<AfterNavigation>) | {
    readonly _tag: 'Traverse';
    readonly delta: number;
} | {
    readonly _tag: 'Head';
    readonly head: Head;
} | {
    readonly _tag: 'Listen';
};

interface RouterOptions extends MemoryOptions {
    /** Driver name used for substitution (`el.drivers`). Default `'router'`. */
    readonly name?: string;
    /**
     * `'browser'` (default) drives the real document. `'memory'` keeps entries in memory: no
     * global URL changes, no `window` needed (tests, servers). See `initial` and `origin`.
     * `captureLinks`/`linkRoot` apply to both histories.
     */
    readonly history?: 'browser' | 'memory';
    /** Browser history: default the global window, resolved on first use (safe on a server). */
    readonly window?: Window;
    /** Browser history: use the Navigation API when present. Default `true`. */
    readonly navigationApi?: boolean;
    /**
     * Browser history, once a navigation has rendered: scroll to the `#fragment` target or the
     * top (push) and restore the position on back/forward. Default `true`; `false` for apps that
     * manage scroll themselves. A replace never scrolls unless `navigate(url, { scroll: true })`;
     * `navigate(url, { scroll })` overrides it per call.
     */
    readonly scroll?: boolean;
    /**
     * Browser history, once a navigation has rendered: move focus to the first `[autofocus]`
     * element, or reset it to the page start, unless something took focus during the navigation
     * (a `focus('main h1')` command). Default `true` (a replace: only with `focusReset: true`).
     * `navigate(url, { focusReset })` per call.
     */
    readonly focusReset?: boolean;
}

interface RouterSnapshot {
    readonly href: string;
    /** The last `setHead()` head, if any (the browser applies it to the document too). */
    readonly head: Head | undefined;
    /** Number of history entries (memory history; `history.length` in a browser). */
    readonly length: number;
}

interface Routes<T extends RouteTable> {
    readonly table: T;
    /** First route in table order matching the pathname. A string beginning with / is a path. */
    match(url: string | URL): RouteMatch<T> | undefined;
    /** Percent-encode each parameter or catch-all segment; omit absent optional parameters. */
    href<N extends keyof T & string>(name: N, params: Params<T[N]>): string;
}

type RouteTable = Readonly<Record<string, string>>;