@alchemy.run/sigil 0.0.0-alpha.4 → 0.0.0-alpha.6

package/dist/router.d.ts

@@ -0,0 +1,392 @@
+import { t as Props } from "./Text-BobFKi74.js";
+import { ReactElement, ReactNode } from "react";
+//#region src/router/history.d.ts
+/**
+The type of navigation that produced the current location:
+
+- `"POP"` — moving through existing history entries (`navigate(-1)`, initial load).
+- `"PUSH"` — a new entry was added to the stack.
+- `"REPLACE"` — the current entry was overwritten.
+*/
+type NavigationType = "POP" | "PUSH" | "REPLACE";
+/**
+The two parseable pieces of a route path. Sigil routes have no hash — a
+terminal has no scroll anchors.
+*/
+type Path = {
+  /**
+      The path of the screen, beginning with `/`.
+      */
+  pathname: string;
+  /**
+      The query string, beginning with `?`, or an empty string.
+      */
+  search: string;
+};
+/**
+An entry in the navigation stack.
+*/
+type Location<State = unknown> = Path & {
+  /**
+      Arbitrary state attached to this entry via `navigate(to, {state})`. Unlike the
+      browser, this is held in memory and never serialized — any value works.
+      */
+  state: State;
+  /**
+      A unique key for this entry, stable across re-renders. Useful as a React
+      `key` to remount a screen when re-navigating to the same path.
+      */
+  key: string;
+};
+/**
+A destination to navigate to: either a path string (`"/users/123?tab=posts"`)
+or a partial `Path` object.
+*/
+type To = string | Partial<Path>;
+/**
+Splits a path string into its pathname and search parts.
+*/
+declare const parsePath: (path: string) => Partial<Path>;
+/**
+Joins a `Path` back into a single string.
+*/
+declare const createPath: ({ pathname, search }: Partial<Path>) => string;
+/**
+An entry to seed the navigation stack with: a path string or a partial
+`Location` (which may carry `state`).
+*/
+type InitialEntry = string | Partial<Location>;
+//#endregion
+//#region src/router/matcher.d.ts
+/**
+A route definition. Used as JSX via `<Route>` or passed as plain objects to
+`useRoutes`.
+*/
+type RouteObject = {
+  /**
+      The path pattern to match against the current location, relative to the
+      parent route. Supports `:param` dynamic segments, optional segments
+      (`:param?`, `edit?`), and a trailing `*` splat.
+      */
+  path?: string;
+  /**
+      An index route renders in its parent's `<Outlet>` at the parent's exact path.
+      Index routes cannot have children.
+      */
+  index?: boolean;
+  /**
+      The element to render when this route matches.
+      */
+  element?: ReactNode;
+  /**
+      Nested child routes, rendered into this route's `<Outlet>`.
+      */
+  children?: RouteObject[];
+};
+/**
+Parsed params from dynamic segments of a matched path. The splat segment, if
+any, is available under the `"*"` key.
+*/
+type Params<Key extends string = string> = { readonly [key in Key]: string | undefined; };
+/**
+A route object matched against a location, along with the params and the
+portion of the pathname it consumed.
+*/
+type RouteMatch<RouteObjectType extends RouteObject = RouteObject> = {
+  params: Params;
+  pathname: string;
+  pathnameBase: string;
+  route: RouteObjectType;
+};
+/**
+A pattern for matching some portion of a pathname with `matchPath`.
+*/
+type PathPattern = {
+  /**
+      The path pattern to match against.
+      */
+  path: string;
+  /**
+      Should be `true` (the default) if the pattern must consume the entire
+      pathname; `false` allows matching a prefix.
+      */
+  end?: boolean;
+};
+/**
+The result of matching a `PathPattern` against a pathname.
+*/
+type PathMatch<ParamKey extends string = string> = {
+  params: Params<ParamKey>;
+  pathname: string;
+  pathnameBase: string;
+  pattern: PathPattern;
+};
+/**
+Matches a set of (possibly nested) routes against a location and returns the
+chain of matches from the root route down to the leaf, or `null` if nothing
+matches.
+*/
+declare function matchRoutes<RouteObjectType extends RouteObject = RouteObject>(routes: RouteObjectType[], locationArg: Partial<Location> | string): RouteMatch<RouteObjectType>[] | null;
+/**
+Matches a single path pattern against a pathname. Returns the match with
+extracted params, or `null` if the pattern does not match.
+*/
+declare function matchPath<ParamKey extends string = string>(pattern: PathPattern | string, pathname: string): PathMatch<ParamKey> | null;
+/**
+Interpolates params into a route path pattern.
+
+```ts
+generatePath("/users/:id", { id: "42" }); // "/users/42"
+```
+*/
+declare function generatePath(originalPath: string, params?: Record<string, string | null>): string;
+/**
+Resolves a `To` value against a starting pathname, handling `.` and `..`
+segments.
+*/
+declare function resolvePath(to: To, fromPathname?: string): Path;
+//#endregion
+//#region src/router/context.d.ts
+/**
+The imperative interface `useNavigate` drives. Backed by the memory history
+inside `<MemoryRouter>`.
+*/
+type Navigator = {
+  push: (to: Path, state?: unknown) => void;
+  replace: (to: Path, state?: unknown) => void;
+  go: (delta: number) => void;
+  canGoBack: () => boolean;
+  canGoForward: () => boolean;
+};
+//#endregion
+//#region src/router/hooks.d.ts
+/**
+Returns `true` when rendered inside a `<MemoryRouter>`. Useful for components
+that optionally integrate with routing.
+*/
+declare const useInRouterContext: () => boolean;
+/**
+Returns the current `Location`.
+*/
+declare const useLocation: () => Location;
+/**
+Returns the type of navigation that produced the current location: `"POP"`,
+`"PUSH"`, or `"REPLACE"`.
+*/
+declare const useNavigationType: () => NavigationType;
+type NavigateOptions = {
+  /**
+      Replace the current entry in the navigation stack instead of pushing a new
+      one.
+      */
+  replace?: boolean;
+  /**
+      Arbitrary state to attach to the destination location, readable via
+      `useLocation().state`. Held in memory, never serialized.
+      */
+  state?: unknown;
+};
+/**
+Navigates to a destination, or through the navigation stack when passed a
+number (`navigate(-1)` goes back).
+*/
+type NavigateFunction = {
+  (to: To, options?: NavigateOptions): void;
+  (delta: number): void;
+};
+/**
+Returns a stable function for imperative navigation.
+*/
+declare const useNavigate: () => NavigateFunction;
+/**
+Returns whether the navigation stack has entries behind/ahead of the current
+one — i.e. whether `navigate(-1)` / `navigate(1)` will move anywhere. Handy
+for "Esc goes back, unless at root" bindings.
+*/
+declare const useNavigationStack: () => {
+  canGoBack: boolean;
+  canGoForward: boolean;
+};
+/**
+Returns the params from all dynamic segments matched by the current route and
+its ancestors.
+*/
+declare const useParams: <ParamsOrKey extends Record<string, string | undefined> | string = string>() => Readonly<[ParamsOrKey] extends [string] ? Params<ParamsOrKey> : Partial<ParamsOrKey>>;
+/**
+Matches a path pattern against the current location's pathname. Returns the
+match (with params) or `null`.
+*/
+declare const useMatch: <ParamKey extends string = string>(pattern: PathPattern | string) => PathMatch<ParamKey> | null;
+/**
+Resolves a `To` value against the current route, exactly as `useNavigate`
+would. Useful for building navigation UI.
+*/
+declare const useResolvedPath: (to: To) => Path;
+/**
+Returns the element for the child route at this level of the route hierarchy,
+or `null` if there is none. Used internally by `<Outlet>`.
+*/
+declare const useOutlet: (context?: unknown) => ReactElement | null;
+/**
+Returns the value passed to the nearest parent `<Outlet context={...}>`.
+*/
+declare const useOutletContext: <Context = unknown>() => Context;
+type SearchParamsInit = string | string[][] | Record<string, string | string[]> | URLSearchParams;
+/**
+Creates a `URLSearchParams` from common initializer shapes, including
+`{ key: ["a", "b"] }` for repeated keys.
+*/
+declare const createSearchParams: (init?: SearchParamsInit) => URLSearchParams;
+type SetSearchParams = (nextInit: SearchParamsInit | ((prev: URLSearchParams) => SearchParamsInit), navigateOptions?: NavigateOptions) => void;
+/**
+Returns the current location's search params and a setter that navigates to
+the same pathname with the new params.
+*/
+declare const useSearchParams: (defaultInit?: SearchParamsInit) => [URLSearchParams, SetSearchParams];
+/**
+Matches a set of route objects against the current location (or an override)
+and returns the rendered element tree. The plain-object alternative to
+`<Routes>`.
+*/
+declare const useRoutes: (routes: RouteObject[], locationArg?: Partial<Location> | string) => ReactElement | null;
+//#endregion
+//#region src/router/components.d.ts
+type MemoryRouterProps = {
+  /**
+      The navigation stack to start with. Defaults to `["/"]`.
+      */
+  initialEntries?: InitialEntry[];
+  /**
+      The index of the initial entry to render. Defaults to the last entry.
+      */
+  initialIndex?: number;
+  children?: ReactNode;
+};
+/**
+The routing container for a Sigil app. Stores the navigation stack in memory —
+routes aren't URLs, they're screen states.
+
+```tsx
+<MemoryRouter>
+  <Routes>
+    <Route path="/" element={<Home />} />
+    <Route path="/settings" element={<Settings />} />
+  </Routes>
+</MemoryRouter>
+```
+*/
+declare function MemoryRouter({ initialEntries, initialIndex, children }: MemoryRouterProps): import("react").JSX.Element;
+type RouteProps = {
+  /**
+      The path pattern to match, relative to the parent route. Supports `:param`
+      dynamic segments, optional segments (`:param?`, `edit?`), and a trailing
+      `*` splat.
+      */
+  path?: string;
+  /**
+      Render this route in the parent's `<Outlet>` at the parent's exact path.
+      Index routes cannot have children.
+      */
+  index?: boolean;
+  /**
+      The element to render when this route matches.
+      */
+  element?: ReactNode;
+  /**
+      Nested `<Route>` elements, rendered into this route's `<Outlet>`.
+      */
+  children?: ReactNode;
+};
+/**
+Declares a route. Only valid as a child of `<Routes>` or another `<Route>`.
+*/
+declare function Route(_props: RouteProps): ReactElement | null;
+type RoutesProps = {
+  children?: ReactNode;
+  /**
+      Match against this location instead of the current one. Useful for
+      rendering a screen other than the one navigated to (e.g. transitions).
+      */
+  location?: Partial<Location> | string;
+};
+/**
+Renders the branch of child `<Route>` elements that best matches the current
+location.
+*/
+declare function Routes({ children, location }: RoutesProps): ReactElement | null;
+type OutletProps = {
+  /**
+      A value to make available to descendant routes via `useOutletContext()`.
+      */
+  context?: unknown;
+};
+/**
+Renders the matching child route of a parent route, or nothing if no child
+matches.
+*/
+declare function Outlet(props: OutletProps): ReactElement | null;
+type NavigateProps = {
+  to: To;
+  replace?: boolean;
+  state?: unknown;
+};
+/**
+Navigates as soon as it renders. The component form of `useNavigate`, for
+declarative redirects:
+
+```tsx
+<Route path="/" element={<Navigate to="/home" replace />} />
+```
+*/
+declare function Navigate({ to, replace, state }: NavigateProps): null;
+type LinkRenderState = {
+  /**
+      Whether this link currently has focus.
+      */
+  isFocused: boolean;
+  /**
+      Whether the current location is the link's destination or a descendant of
+      it.
+      */
+  isActive: boolean;
+};
+type LinkProps = Omit<Props, "children"> & {
+  /**
+      The destination to navigate to when the link is activated.
+      */
+  to: To;
+  /**
+      Replace the current entry in the navigation stack instead of pushing.
+      */
+  replace?: boolean;
+  /**
+      State to attach to the destination location.
+      */
+  state?: unknown;
+  /**
+      Focus this link if nothing else is focused yet.
+      */
+  autoFocus?: boolean;
+  /**
+      An ID for programmatic focus via `useFocusManager().focus(id)`.
+      */
+  id?: string;
+  /**
+      Link content. Pass a function to take full control of rendering based on
+      focus and active state.
+      */
+  children?: ReactNode | ((state: LinkRenderState) => ReactNode);
+};
+/**
+A focusable navigation element — the terminal's `<a>` tag. Focus it with
+<kbd>Tab</kbd> and activate it with <kbd>Enter</kbd>. By default the focused
+link renders inverse; pass a function as `children` (or any `Text` props) to
+customize.
+
+```tsx
+<Link to="/settings">Settings</Link>
+```
+*/
+declare function Link({ to, replace, state, autoFocus, id, children, ...textProps }: LinkProps): import("react").JSX.Element;
+//#endregion
+export { type InitialEntry, Link, type LinkProps, type Location, MemoryRouter, type MemoryRouterProps, Navigate, type NavigateFunction, type NavigateOptions, type NavigateProps, type NavigationType, type Navigator, Outlet, type OutletProps, type Params, type Path, type PathMatch, type PathPattern, Route, type RouteMatch, type RouteObject, type RouteProps, Routes, type RoutesProps, type To, createPath, createSearchParams, generatePath, matchPath, matchRoutes, parsePath, resolvePath, useInRouterContext, useLocation, useMatch, useNavigate, useNavigationStack, useNavigationType, useOutlet, useOutletContext, useParams, useResolvedPath, useRoutes, useSearchParams };