@stealthscale/provider-router 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,489 @@
+import { ComponentProps, FunctionComponent, ReactNode } from "react";
+export * from "@tanstack/react-router";
+//#region src/declaration.d.ts
+/**
+ * Loads a page on first navigation, rather than with the bundle that declared it.
+ *
+ * @remarks
+ *   A wrapper rather than a bare function, because a React component is a function too and nothing
+ *   at run time separates one from an importer.
+ */
+interface LazyPage {
+  /**
+   * The export the page is published under. The module's default export where it states none.
+   */
+  readonly export?: string | undefined;
+  /**
+   * Imports the module holding the page.
+   */
+  readonly load: () => Promise<Readonly<Record<string, FunctionComponent>>>;
+}
+/**
+ * Reports one fault a schema found.
+ */
+interface SearchIssue {
+  /**
+   * The fault, in words a person can read.
+   */
+  readonly message: string;
+}
+/**
+ * Reports that a value was refused, and why.
+ */
+interface SearchRefused {
+  /**
+   * Each fault the schema found.
+   */
+  readonly issues: readonly SearchIssue[];
+}
+/**
+ * Reports that a value was accepted, and what it read as.
+ */
+interface SearchRead {
+  /**
+   * Nothing, which is how a reader tells an acceptance from a refusal.
+   */
+  readonly issues?: undefined;
+  /**
+   * The value, as the schema read it.
+   */
+  readonly value: unknown;
+}
+/**
+ * Checks a value against a schema, in the shape Standard Schema settled on.
+ */
+interface StandardSurface {
+  /**
+   * Checks a value and returns what it read, or why it refused.
+   */
+  readonly validate: (value: unknown) => Promise<SearchRead | SearchRefused> | SearchRead | SearchRefused;
+}
+/**
+ * Reads a search string into the values a route draws with.
+ *
+ * @remarks
+ *   Stated structurally rather than by the library's own name, so a declaration carries a validator
+ *   from any library that implements Standard Schema without this package depending on any of them.
+ */
+interface SearchValidator {
+  /**
+   * The Standard Schema surface, which is the whole of what the library reads.
+   */
+  readonly "~standard": StandardSurface;
+}
+/**
+ * Draws a frame around whatever a route below it draws.
+ */
+interface LayoutProps {
+  /**
+   * The route drawn inside the frame, which React supplies.
+   */
+  readonly children?: ReactNode | undefined;
+  /**
+   * The options the declaration stated for this layout, passed through untouched.
+   */
+  readonly options?: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * Describes one route a host declares, in the form the compiler takes.
+ *
+ * @remarks
+ *   The condition is generic because this package cannot read a session and does not know the
+ *   language conditions are written in. A host states its own and supplies the evaluator that reads
+ *   it.
+ */
+interface RouteDeclaration<Condition = unknown> {
+  /**
+   * Draws the page, either directly or loaded on first navigation.
+   */
+  readonly component: FunctionComponent | LazyPage;
+  /**
+   * The id a host and a plugin refer to it by, which resolves to a path through the map.
+   */
+  readonly id: string;
+  /**
+   * The layouts it is drawn in, outermost first. Drawn bare where it names none.
+   */
+  readonly layout?: readonly string[] | undefined;
+  /**
+   * Passed to each layout untouched, for whatever the layout reads.
+   */
+  readonly layoutOptions?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * The menu entry a menu reads, which the compiler writes onto the route without reading.
+   */
+  readonly navigation?: unknown;
+  /**
+   * The pane it is drawn in, which this package refuses because it draws no panes.
+   */
+  readonly outlet?: string | undefined;
+  /**
+   * Another declaration it nests under, by id. The compiler's own parent where it names none.
+   */
+  readonly parent?: string | undefined;
+  /**
+   * The path pattern, relative to the parent, in the library's `$id` form.
+   */
+  readonly path: string;
+  /**
+   * A sample of the parameters, which a plugin's own tests open the page at.
+   */
+  readonly sample?: Readonly<Record<string, string>> | undefined;
+  /**
+   * Reads the search string this route draws with.
+   */
+  readonly search?: SearchValidator | undefined;
+  /**
+   * When it is routed at all. Routed always where it states none.
+   */
+  readonly when?: Condition | undefined;
+}
+/**
+ * Carries the name a route goes by, and whatever a menu reads off it.
+ *
+ * @remarks
+ *   Written onto the route's `staticData`, which the library hands back on every match. A menu, a
+ *   breadcrumb or a telemetry hook therefore reads the name off the page it is drawing rather than
+ *   holding a second copy of the list.
+ */
+interface DeclaredRoute {
+  /**
+   * The id the route is named under.
+   */
+  readonly id: string;
+  /**
+   * The menu entry the declaration carried, passed through untouched.
+   */
+  readonly navigation?: unknown;
+}
+/**
+ * Reports whether a route's condition holds for whoever is asking.
+ *
+ * @remarks
+ *   Returning false makes the route a 404, because a route nobody may reach does not exist. An
+ *   evaluator wanting anything else, such as sending an unauthenticated person to sign in, throws
+ *   the library's own `redirect` instead.
+ */
+type Evaluate<Condition = unknown> = (when: Condition) => boolean;
+import * as import__tanstack_react_router from "@tanstack/react-router";
+//#endregion
+//#region src/compile.d.ts
+/**
+ * Describes what one compilation needs beyond the declarations themselves.
+ */
+interface CompileOptions<Condition = unknown> {
+  /**
+   * Draws a page whose own component threw or failed to load, named per declaration.
+   */
+  readonly errorComponent?: ((declaration: RouteDeclaration<Condition>) => tanstack_d_exports.ErrorRouteComponent) | undefined;
+  /**
+   * Reports whether a route's condition holds. Required where any declaration states one.
+   */
+  readonly evaluate?: Evaluate<Condition> | undefined;
+  /**
+   * The layouts a declaration may name.
+   */
+  readonly layouts?: Readonly<Record<string, FunctionComponent<LayoutProps>>> | undefined;
+  /**
+   * The route every compiled route hangs under, which this compilation never changes.
+   */
+  readonly parent: tanstack_d_exports.AnyRoute;
+}
+/**
+ * Compiles declarations into routes under the parent a caller states.
+ *
+ * @remarks
+ *   Pure with respect to the caller. It creates routes and never mutates the parent, so a second
+ *   call returns a second set of routes sharing no object with the first. That is what keeps two
+ *   routers in one process from reading each other's tree through the library's process-wide cache.
+ *   Compile every contributor's declarations in one call. Two calls under one parent cannot see
+ *   each other's paths, and `routeMap` reports the collision once the tree is assembled.
+ * @param declarations - The routes to compile, in any order.
+ * @param options - The parent, and what the declarations may name.
+ * @returns The routes to place in the parent's own `addChildren` call.
+ * @throws {@link Error} Where two declarations share an id, where one names a parent or a layout
+ *   nothing provides, where one names a layout a route above it already draws, where parents form a
+ *   cycle, where one states a condition and no evaluator was given, or where one states an outlet.
+ */
+export declare function compileRoutes<Condition = unknown>(declarations: ReadonlyArray<RouteDeclaration<Condition>>, options: CompileOptions<Condition>): readonly tanstack_d_exports.AnyRoute[];
+//#endregion
+//#region src/reference.d.ts
+/**
+ * Points at a route without naming a path, a module or an address.
+ */
+/**
+ * The parameters a route names where its reference states none.
+ */
+type AnyParams = Readonly<Record<string, string>>;
+/**
+ * Points at a route by the id it was declared under, carrying the parameters its path names.
+ *
+ * @remarks
+ *   Stated structurally rather than imported, so a plugin SDK's own reference type satisfies it
+ *   without this package depending on that SDK. A reference carries no path, because the path is
+ *   whoever composed the application's to choose and a link written against one would move when
+ *   they re-placed the route.
+ *   The parameters live in the type alone. Nothing reads `~types` at run time, and it is there so
+ *   a link to a route filling `id` is refused where the route names `invoice`.
+ */
+interface RouteRef<Params extends AnyParams = AnyParams> {
+  /**
+   * The parameters, in the type alone.
+   */
+  readonly "~types"?: {
+    /**
+     * The parameters the route's path names, which a link fills.
+     */
+    readonly params: Params;
+  };
+  /**
+   * The full id the route was declared under.
+   */
+  readonly id: string;
+}
+/**
+ * Points at a route, either by a reference or by the bare id one carries.
+ */
+type RouteTarget<Params extends AnyParams = AnyParams> = RouteRef<Params> | string;
+//#endregion
+//#region src/declared.d.ts
+/**
+ * Describes the part of a match this package reads.
+ */
+interface MatchedRoute {
+  /**
+   * The data the route was given to carry, which the library hands back untouched.
+   */
+  readonly staticData: object;
+}
+/**
+ * Reads the id and the menu entry a matched route carries, or nothing where it carries neither.
+ *
+ * @remarks
+ *   A route carries its id in `staticData`, which is where the library keeps whatever a route wants
+ *   to carry. The compiler writes it for a route built from a declaration and `namedRoute` writes
+ *   it for one written in code, so a menu, a breadcrumb or a telemetry hook reads what it needs off
+ *   the match either way. The shape is checked rather than trusted, because `staticData` is untyped
+ *   by design and a route may carry anything under the same name. The checked object itself is
+ *   returned, so every read of one route gives one reference.
+ * @param match - A match, as `useMatches` returns one.
+ * @returns The id and the menu entry it carries, or nothing.
+ */
+export declare function declaredOf(match: MatchedRoute): DeclaredRoute | undefined;
+/**
+ * Reads the name the deepest named route the page is on goes by.
+ *
+ * @remarks
+ *   The deepest match rather than the first, because a named route nested under another is the page
+ *   a person is looking at. A page drawn entirely from unnamed routes returns nothing.
+ *   The selector returns the object the route carries rather than a copy of it. A route's static
+ *   data is fixed once the tree is built, so the reference is the same one until a different route
+ *   matches, and a navigation that left the page alone re-renders nothing.
+ * @returns The id and the menu entry, or nothing where no matched route carries either.
+ */
+export declare function useDeclaredRoute(): DeclaredRoute | undefined;
+/**
+ * Reads the parameters of the page being drawn, typed by the reference the caller holds.
+ *
+ * @remarks
+ *   A compiled route is outside the tree an application registered, so `useParams` types against a
+ *   tree the route is not in. The parameters are read off the match instead, and the reference
+ *   carries their names. This checks at run time that the page really is the route the reference
+ *   names before it makes the claim.
+ *   The selector returns the id and the parameters alone, which are strings. Structural sharing
+ *   compares them, so a navigation that changed neither re-renders nothing.
+ * @param to - A reference to the route the calling component draws.
+ * @returns The parameters the route's path named.
+ * @throws {@link Error} Where the page being drawn is not the route the reference names.
+ */
+export declare function useRouteParams<Params extends AnyParams>(to: RouteRef<Params>): Params;
+//#endregion
+//#region src/defaults.d.ts
+/**
+ * How a router in this design system behaves before an application says otherwise.
+ */
+/**
+ * The options every application's router starts from, spread before its own.
+ *
+ * @remarks
+ *   A route preloads on intent, which is when the pointer rests on a link or the link takes focus,
+ *   so a page is usually loaded before it is asked for.
+ *   A preloaded route never counts as fresh on its own. The query client decides freshness for
+ *   everything it loads, and a router keeping its own staleness would serve a copy the client had
+ *   already replaced.
+ *   Scroll position is restored on the way back, because a person returning to a list expects to be
+ *   where they left it rather than at the top.
+ */
+export declare const routerDefaults: {
+  readonly defaultPreload: "intent";
+  readonly defaultPreloadStaleTime: 0;
+  readonly scrollRestoration: true;
+};
+//#endregion
+//#region src/map.d.ts
+/**
+ * Every id anything links by, against the route that draws it.
+ */
+type RouteMap = ReadonlyMap<string, tanstack_d_exports.AnyRoute>;
+/**
+ * Carries a route's name where the library hands it back on every match.
+ */
+interface StaticName {
+  /**
+   * The static data the route carries, which `declaredOf` reads the name out of.
+   */
+  readonly staticData: Readonly<Record<"declared", DeclaredRoute>>;
+}
+/**
+ * Gives a route written in code the id everything else links to it by.
+ *
+ * @remarks
+ *   A route carries its id in `staticData`, which is where the compiler writes the id of a route
+ *   built from a declaration. One mechanism names both, so a link does not need to know which of
+ *   the two it is pointing at.
+ * @param id - The id to name the route under.
+ * @returns The static data to spread into `createRoute`.
+ */
+export declare function namedRoute(id: string): StaticName;
+/**
+ * Reads every id a tree names, against the route that draws it.
+ *
+ * @remarks
+ *   Derived from the tree rather than collected beside it, so a route written in code and a route
+ *   built from a declaration reach the map the same way. The walk also reports two routes that
+ *   serve one URL, which a development build reports as a duplicate route and a production build
+ *   resolves by keeping the first and dropping the rest in silence.
+ * @param tree - The assembled tree, as `createRouter` takes it.
+ * @returns Every id, against its route.
+ * @throws {@link Error} Where two routes carry one id, or where two serve one path under a shared
+ *   parent.
+ */
+export declare function routeMap(tree: tanstack_d_exports.AnyRoute): RouteMap;
+//#endregion
+//#region src/href.d.ts
+/**
+ * Resolves a declared id to a path, with the parameters the path names filled in.
+ *
+ * @remarks
+ *   Throwing is deliberate in all three cases. Interpolation otherwise returns a path with a
+ *   literal `$id` still in it, and a route the library has not worked a full path out for yet
+ *   returns the site root. A link that navigates somewhere wrong is worse than one that fails where
+ *   somebody wrote it.
+ * @param map - The map every route is named in.
+ * @param to - A reference to the route, or the bare id one carries.
+ * @param params - The parameters the path names, typed by the reference where one was given.
+ * @returns The path, ready to navigate to.
+ * @throws {@link Error} Where the map holds no such id, where no router has processed the tree the
+ *   route was placed in, or where a parameter the path names is missing.
+ */
+export declare function routeHref<Params extends AnyParams>(map: RouteMap, to: RouteTarget<Params>, params?: Params): string;
+/**
+ * Reads the map every route is named in, from the router's own context.
+ *
+ * @remarks
+ *   The map reaches a component through the router's own context rather than a provider of this
+ *   package's own, so an application mounts nothing extra to make a link by id work.
+ *   Take the map rather than a resolved path where the route is chosen after the render: a hook
+ *   cannot run inside an event handler, and `routeHref` can.
+ * @returns Every id the router knows, against the route that serves it.
+ * @throws {@link Error} Where the router was built without one.
+ */
+export declare function useRouteMap(): RouteMap;
+/**
+ * Resolves a reference to a path, through the map the router context holds.
+ *
+ * @remarks
+ *   A hook, so the route has to be known while the component renders. Use `useRouteMap` where the
+ *   route is chosen later, such as in the handler of a row a person clicked.
+ * @param to - A reference to the route, or the bare id one carries.
+ * @param params - The parameters the path names, typed by the reference where one was given.
+ * @returns The path, ready to navigate to.
+ * @throws {@link Error} Where no map is in the router context, where it holds no such id, or where
+ *   a parameter the path names is missing.
+ */
+export declare function useRouteHref<Params extends AnyParams>(to: RouteTarget<Params>, params?: Params): string;
+//#endregion
+//#region src/link.d.ts
+/**
+ * Describes a link to a declared route.
+ *
+ * @remarks
+ *   Everything the library's own `Link` takes passes through, so a declared link is styled,
+ *   labelled and given an active state the way any other link is. Only `to` and `params` are
+ *   restated, because a declared id is not a path the compiler knows.
+ */
+type RouteLinkProps<Params extends AnyParams = AnyParams> = {
+  /**
+   * The parameters the route's path names, typed by the reference where one was given.
+   */
+  readonly params?: Params | undefined;
+  /**
+   * A reference to the route, or the bare id one carries.
+   */
+  readonly to: RouteTarget<Params>;
+} & Omit<ComponentProps<typeof tanstack_d_exports.Link>, "params" | "to">;
+/**
+ * Links to a route by the id a manifest declared it under.
+ *
+ * @remarks
+ *   A declared route is outside the tree an application registered, so `Link` refuses its path at
+ *   compile time. This resolves the id at run time and hands the library a plain string, which is
+ *   the one place in this package where a path is not checked by the compiler.
+ * @param props - The declared id, its parameters, and whatever else the library's `Link` takes.
+ * @returns An anchor to the resolved path.
+ */
+export declare function RouteLink<Params extends AnyParams>({ params, to, ...rest }: RouteLinkProps<Params>): ReactNode;
+//#endregion
+//#region src/options.d.ts
+/**
+ * Describes the one member this package expects a router's context to carry.
+ *
+ * @remarks
+ *   A component resolves a declared id through the router's own context rather than through a
+ *   provider of this package's own, so an application mounts nothing extra to make a declared link
+ *   work.
+ */
+interface RoutesContext {
+  /**
+   * Every declared id, against the route compiled for it.
+   */
+  readonly routes?: RouteMap | undefined;
+}
+/**
+ * Describes the options a caller spreads into `createRouter`.
+ */
+type AppRouterOptions<Context extends object> = {
+  /**
+   * The context the router hands every loader and every route component.
+   */
+  readonly context: Context;
+} & typeof routerDefaults;
+/**
+ * Collects the options every router in this design system starts from.
+ *
+ * @remarks
+ *   An object to spread rather than a factory that calls `createRouter`. The library states
+ *   forty-eight router options, and a factory would expose the few it thought of and hide the rest.
+ *   Spreading leaves every one of them the caller's to set, the four stated here included.
+ * @param context - The context the router hands a loader, holding the route map where a caller compiled
+ *   declarations.
+ * @returns The options, to spread into `createRouter` before the caller's own.
+ */
+export declare function routerOptions<Context extends object>(context: Context): AppRouterOptions<Context>;
+//#endregion
+//#region src/root.d.ts
+/**
+ * Builds a root route whose context holds whatever the application states and the route map.
+ *
+ * @remarks
+ *   Calling the library's `createRootRoute` instead leaves the context typed as empty, and the
+ *   first sign of it is `createRouter` refusing the options `routerOptions` returned. The error
+ *   then names the router rather than the root, which is the file that has to change.
+ * @returns The root route factory, to call with the route's own options.
+ */
+export declare function createAppRootRoute<Context extends object = RoutesContext>(): ReturnType<typeof tanstack_d_exports.createRootRouteWithContext<Context>>;
+declare namespace index_d_exports {
+  export { AnyParams, AppRouterOptions, CompileOptions, DeclaredRoute, Evaluate, LayoutProps, LazyPage, MatchedRoute, RouteDeclaration, RouteLink, RouteLinkProps, RouteMap, RouteRef, RouteTarget, RoutesContext, SearchValidator, StaticName, compileRoutes, createAppRootRoute, declaredOf, namedRoute, routeHref, routeMap, routerDefaults, routerOptions, useDeclaredRoute, useRouteHref, useRouteMap, useRouteParams };
+}
+//#endregion
+export type { AnyParams, AppRouterOptions, CompileOptions, DeclaredRoute, Evaluate, LayoutProps, LazyPage, MatchedRoute, RouteDeclaration, RouteLinkProps, RouteMap, RouteRef, RouteTarget, RoutesContext, SearchValidator, StaticName };