@manyducks.co/dolla 2.0.0 → 3.0.0

package/dist/router/router.d.ts

@@ -1,166 +1,23 @@
 import { Context } from "../core/context.js";
-import { type MarkupNode } from "../core/markup.js";
-import { type Signal } from "../core/signals.js";
-import type { View } from "../types.js";
-export type Stringable = {
-    toString(): string;
-};
-export interface Match {
-    /**
-     * The path as it appears in the URL bar.
-     */
-    path: string;
-    /**
-     * The pattern that this path was matched with.
-     */
-    pattern: string;
-    /**
-     * Named route params parsed from `path`.
-     */
-    params: Record<string, string>;
-    /**
-     * Query params parsed from `path`.
-     */
-    query: Record<string, string>;
-    /**
-     * Freeform data you wish to store with this route.
-     * Merged `data` from all matched layers are available from `router.$match()`.
-     */
-    data: Record<string, any>;
-}
-export interface RouteMatchContext extends Match {
-    /**
-     * Stores `value` at `key` in this context's state.
-     */
-    setState<T>(key: any, value: T): void;
-    /**
-     * For each tuple in `entries`, stores `value` at `key` in this context's state.
-     */
-    setState(entries: [key: any, value: any][]): void;
-    /**
-     * Redirects the user to a different route instead of matching the current one.
-     */
-    redirect(path: string): void;
-}
-export interface Route {
-    /**
-     * The path or path fragment to match.
-     */
-    path: string;
-    /**
-     * Path to redirect to when this route is matched, or a callback function that returns such path.
-     */
-    redirect?: string | ((ctx: RouteRedirectContext) => string) | ((ctx: RouteRedirectContext) => Promise<string>);
-    /**
-     * View to display when this route is matched.
-     */
-    view?: View<any>;
-    /**
-     * Subroutes.
-     */
-    routes?: Route[];
-    /**
-     * Called after the match is identified but before it is acted on. Use this to set state, load data, etc.
-     */
-    beforeMatch?: (ctx: RouteMatchContext) => void | Promise<void>;
-    /**
-     * Arbitrary data you'd like to store on this route.
-     * This object will be available at `router.$match` while the route is active.
-     *
-     * In the case of nested routes, data from all layers will be merged into a single data object.
-     */
-    data?: Record<string, any>;
-}
-export interface RouteMeta {
-    redirect?: string | ((ctx: RouteRedirectContext) => string) | ((ctx: RouteRedirectContext) => Promise<string>);
-    pattern?: string;
-    layers?: RouteLayer[];
-    beforeMatch?: {
-        fn: (ctx: RouteMatchContext) => void | Promise<void>;
-        layerId: number;
-    }[];
-    data?: Record<string, any>;
-}
-export interface RouteConfig {
-    pattern: string;
-    meta: RouteMeta;
-}
-export interface RouteLayer {
-    id: number;
-    view: View<{}>;
-}
+import { DollaPlugin } from "../core/index.js";
+import { DynamicNode } from "../core/markup/nodes/dynamic.js";
+import type { LazyLoader, LazyView, RouterOptions } from "./types.js";
 /**
- * Object passed to redirect callbacks. Contains information useful for determining how to redirect.
+ * Lazy loads a view when its route is first matched.
+ *
+ * @example
+ * {
+ * path: "/users",
+ * view: lazy(() => import("./views/users.js"))
+ * }
  */
-export interface RouteRedirectContext extends Match {
-}
-export interface NavigateOptions {
-    /**
-     * Replace the current item in the history stack instead of adding a new one.
-     * The back button will send the user to the page they visited before this. Defaults to false.
-     */
-    replace?: boolean;
-    /**
-     * Preserve existing query params (if any) when navigating. Defaults to false.
-     * If true, all existing query params are preserved and merged with new ones.
-     * If an array of strings is passed only those keys will be preserved, then merged with any new ones.
-     */
-    preserveQuery?: boolean | string[];
-}
-export interface RouterOptions {
-    routes: Route[];
-    /**
-     * When true, the router will construct routes like "https://www.example.com/#/sub/route" which work without any backend intervention.
-     */
-    hash?: boolean;
-}
-export declare const ROUTER: unique symbol;
-export declare const MOUNT: unique symbol;
-export declare const UNMOUNT: unique symbol;
-export declare const ROOT_VIEW: unique symbol;
-export declare class Router {
-    #private;
-    /**
-     * The current match object.
-     */
-    readonly $match: Signal<Match | undefined>;
-    /**
-     * The currently matched route pattern, if any.
-     */
-    readonly $pattern: Signal<string | undefined>;
-    /**
-     * The current URL path.
-     */
-    readonly $path: Signal<string>;
-    /**
-     * The current named path params.
-     */
-    readonly $params: Signal<Record<string, string>>;
-    /**
-     * The current query params.
-     */
-    readonly $query: Signal<Record<string, string>>;
-    constructor(options: RouterOptions);
-    [MOUNT](parent: Element, context: Context): Promise<MarkupNode>;
-    [UNMOUNT](): Promise<void>;
-    /**
-     * Navigate backward. Pass a number of steps to hit the back button that many times.
-     */
-    back(steps?: number): void;
-    /**
-     * Navigate forward. Pass a number of steps to hit the forward button that many times.
-     */
-    forward(steps?: number): void;
-    /**
-     * Navigates to another route.
-     *
-     * @example
-     * router.go("/login"); // navigate to `/login`
-     * router.go["/users", 215], { replace: true }); // replace current history entry with `/users/215`
-     */
-    go(path: Stringable | Stringable[], options?: NavigateOptions): void;
-    /**
-     * Updates query params, keeping existing ones and applying new ones. Removes the query param if value is set to `null`.
-     */
-    updateQuery(values: Record<string, Stringable | null>): void;
+export declare function lazy(load: LazyLoader): LazyView;
+export declare function createRouterPlugin(options: RouterOptions): DollaPlugin;
+/**
+ * Displays the router's content.
+ */
+export declare function Outlet(this: Context): DynamicNode;
+export declare class RedirectError extends Error {
+    redirectPath: string;
+    constructor(redirectPath: string);
 }

package/dist/router/store.d.ts

@@ -0,0 +1,12 @@
+import { type Context, type Getter, type Setter } from "../core";
+import type { Router } from "./types";
+import { type HistoryAdapter, type Match } from "./utils";
+export interface RouterStoreProps {
+    currentMatch: Getter<Match>;
+    setCurrentMatch: Setter<Match>;
+    progress: Getter<number>;
+    history: HistoryAdapter;
+    updateRoute: () => void;
+    guards: Set<() => boolean | Promise<boolean>>;
+}
+export declare function RouterStore(this: Context, { currentMatch, setCurrentMatch, progress, history, updateRoute, guards }: RouterStoreProps): Router;

package/dist/router/types.d.ts

@@ -0,0 +1,152 @@
+import type { Setter, Getter, MarkupNode, Renderable, View } from "../core";
+import type { Context } from "../core/context";
+import type { Match } from "./utils";
+export type Stringable = {
+    toString(): string;
+};
+export type LazyLoader<Props = any> = () => Promise<{
+    default: View<Props>;
+} | View<Props>>;
+export interface LazyView<Props = any> {
+    _lazy: true;
+    load: LazyLoader<Props>;
+}
+export interface Route<Data = any> {
+    /**
+     * The path or path fragment to match.
+     */
+    path: string;
+    /**
+     * Path to redirect to when this route is matched, or a callback function that returns such path.
+     */
+    redirect?: string | ((match: Match) => string) | ((match: Match) => Promise<string>);
+    preload?: (match: Match) => Data | Promise<Data>;
+    /**
+     * View to display when this route is matched.
+     */
+    view?: View<{
+        data?: Data;
+        children: Renderable;
+    }> | LazyView<{
+        data?: Data;
+        children: Renderable;
+    }>;
+    errorView?: View<{
+        error: Error;
+    }>;
+    /**
+     * Subroutes.
+     */
+    routes?: Route[];
+    /**
+     * Arbitrary data you'd like to store on this route.
+     * This object is accessible via `match.meta` on the `$router` API while the route is active.
+     *
+     * In the case of nested routes, data from all layers will be merged into a single data object.
+     */
+    meta?: Record<string | symbol, any>;
+}
+export interface RouteLayer {
+    id: string;
+    pattern: string;
+    view: View<any> | LazyView<any>;
+    errorView?: View<{
+        error: Error;
+    }>;
+    preload?: (match: Match) => any | Promise<any>;
+}
+/**
+ * An active route layer whose markup has been initialized into a view.
+ */
+export interface ActiveLayer {
+    id: string;
+    key: string;
+    node: MarkupNode;
+    context: Context;
+    slot: Getter<MarkupNode | undefined>;
+    setSlot: Setter<MarkupNode | undefined>;
+}
+/**
+ * A log for a single step in the route resolution process.
+ */
+export interface JourneyStep {
+    kind: "match" | "redirect" | "miss";
+    message: string;
+}
+export interface NavigateOptions {
+    /**
+     * Preserve existing query params (if any) when navigating. Defaults to false.
+     * If true, all existing query params are preserved and merged with new ones.
+     * If an array of strings is passed only those keys will be preserved, then merged with any new ones.
+     */
+    preserveQuery?: boolean | string[];
+}
+export interface RouterOptions {
+    routes: Route[];
+    /**
+     * When true, the router will construct routes like "https://www.example.com/#/sub/route" which work without any backend intervention.
+     */
+    hash?: boolean;
+    /**
+     * Persist query params between pages when navigating. Pass an array to specify a list of params that will be preserved.
+     * By default all query params are cleared when navigating to a new URL (equivalent to `false`).
+     */
+    preserveQuery?: boolean | string[];
+}
+export interface Router {
+    /**
+     * The current path as it is displayed in the URL bar (e.g. `/users/123/edit`).
+     */
+    path: Getter<string>;
+    /**
+     * The route pattern that was matched (e.g. `/users/{#id}/edit`), or undefined if no route is currently matched.
+     */
+    pattern: Getter<string | undefined>;
+    /**
+     * The extracted route parameters from the path. (e.g. `{ id: "123" }`)
+     */
+    params: Getter<Record<string, string>>;
+    /**
+     * The current query params.
+     */
+    query: Getter<Record<string, string>>;
+    /**
+     * The contents of the `meta` fields of all matched route layers.
+     */
+    meta: Getter<Record<string, string>>;
+    /**
+     * Represents the loading progress of the current navigation from 0 to 1.
+     * Returns 0 when no navigation is pending.
+     */
+    progress: Getter<number>;
+    /**
+     * Update query params without changing the route.
+     */
+    setQuery(params: Record<string, Stringable>): Record<string, string>;
+    /**
+     * Go back in the page history. Equivalent to hitting the back button.
+     * Steps is the number of times to hit the back button. The default is 1.
+     */
+    back(steps?: number): void;
+    /**
+     * Go forward in the page history. Equivalent to hitting the forward button.
+     * Steps is the number of times to hit the forward button. The default is 1.
+     */
+    forward(steps?: number): void;
+    /**
+     * Push a new route into the page history and navigate to it.
+     */
+    push(path: string): void;
+    /**
+     * Replace the current route in the page history and navigate to it.
+     */
+    replace(path: string): void;
+    /**
+     * Prevents attempted navigations if the condition returns true.
+     */
+    block(guard: () => boolean | Promise<boolean>): () => void;
+    /**
+     * Contains `true` when the current route matches `path`.
+     */
+    isActive(path: string, exact?: boolean): Getter<boolean>;
+}

package/dist/router/utils.d.ts

@@ -0,0 +1,99 @@
+import type { JourneyStep, Route, RouteLayer, Stringable } from "./types.js";
+export interface Match {
+    /**
+     * The path string that triggered this match.
+     */
+    path: string;
+    /**
+     * The pattern satisfied by `path`.
+     */
+    pattern: string;
+    /**
+     * Named params as parsed from `path`.
+     */
+    params: Record<string, string>;
+    /**
+     * Query params as parsed from `path`.
+     */
+    query: Record<string, string>;
+    /**
+     * Freeform data you wish to store with this route.
+     * Merged `data` from all matched layers are available on the router's `match.meta`.
+     */
+    meta: Record<any, any>;
+}
+export interface RouteMatch extends Match {
+    layers: RouteLayer[];
+    redirect?: string | ((match: Match) => string) | ((match: Match) => Promise<string>);
+}
+export type RoutePayload = {
+    pattern: string;
+    meta: Record<any, any>;
+    layers?: RouteLayer[];
+    redirect?: string | ((match: Match) => string) | ((match: Match) => Promise<string>);
+};
+export type RouteMatchOptions = {
+    willMatch?: (route: RoutePayload) => boolean;
+};
+/**
+ * Separates a URL path into multiple fragments.
+ *
+ * @param path - A path string (e.g. `"/api/users/5"`)
+ * @returns an array of fragments (e.g. `["api", "users", "5"]`)
+ */
+export declare function splitPath(path: string): string[];
+/**
+ * Joins multiple URL path fragments into a single string.
+ *
+ * @param parts - One or more URL fragments (e.g. `["api", "users", 5]`)
+ * @returns a joined path (e.g. `"api/users/5"`)
+ */
+export declare function joinPath(parts: {
+    toString(): string;
+}[]): string;
+export declare function resolvePath(base: string, part?: string | null): string;
+export declare function parseQueryParams(query: string): Record<string, string>;
+export declare function mergeQueryParams(previous: Record<string, string>, current: Record<string, Stringable>, preserve?: boolean | string[]): URLSearchParams;
+export declare class RouteNode {
+    staticChildren: Map<string, RouteNode>;
+    numericChild: RouteNode | null;
+    paramChild: RouteNode | null;
+    wildcardChild: RouteNode | null;
+    route?: RoutePayload;
+    paramName?: string;
+    numericName?: string;
+}
+export declare function buildRouteTree(routes: Route[]): RouteNode;
+export declare function matchRoute(rootNode: RouteNode, url: string, options?: RouteMatchOptions): RouteMatch | undefined;
+export interface ResolvedRoute {
+    match?: RouteMatch;
+    journey: JourneyStep[];
+}
+/**
+ * Takes a URL and finds a match, following redirects.
+ */
+export declare function resolveRoute(rootNode: RouteNode, path: string, journey?: JourneyStep[]): Promise<ResolvedRoute>;
+/**
+ * Intercepts links within the root node.
+ *
+ * This is adapted from https://github.com/choojs/nanohref/blob/master/index.js
+ *
+ * @param root - Element under which to intercept link clicks
+ * @param callback - Function to call when a click event is intercepted
+ * @param _window - (optional) Override for global window object
+ */
+export declare function catchLinks(root: Element, callback: (href: string, anchor: HTMLAnchorElement) => void, _window?: Window & typeof globalThis): () => void;
+export declare function expandOptionalPaths(path: string): string[];
+/**
+ * Replace route pattern param placeholders with real matched values.
+ */
+export declare function replaceParams(path: string, params: Record<string, string | number>): string;
+export interface HistoryAdapter {
+    getPath(): string;
+    getSearch(): string;
+    getKey(): string;
+    getIndex(): number;
+    push(url: string): void;
+    replace(url: string): void;
+}
+export declare function createHistoryAdapter(useHash: boolean): HistoryAdapter;

package/dist/router/utils.test.d.ts

@@ -0,0 +1 @@
+export {};