@fluixi/core 1.0.0-alpha.100

package/dist/src/lib/router/index.d.ts

@@ -0,0 +1,274 @@
+import { type TransitionMode } from './transition.js';
+import { type GetAtPath } from '@fluixi/utils/object';
+import type { IsUndefined } from '@fluixi/utils/primitive';
+import { type RouteDefinition, type Router as CoreRouter, type HistoryAdapter, type RouterLocation, type NavigateOptions } from '@fluixi/router';
+interface RouterCtxValue {
+    router: CoreRouter<any>;
+    location: () => RouterLocation;
+    params: () => Record<string, string>;
+    /** True from a navigation's start until the route it lands on has its modules and data. */
+    isRouting: () => boolean;
+    /** Counts a layer's data load toward `isRouting` until the promise settles. */
+    trackLoad: <T>(result: T) => T;
+}
+export interface RouterProps<C = any> {
+    routes: RouteDefinition<C>[];
+    base?: string;
+    history?: HistoryAdapter;
+    /**
+     * Rendered when the current URL matches no route, a component, an element, or any renderable.
+     * Defaults to a minimal built-in 404 so an unmatched URL never renders a blank page. For a 404
+     * that keeps your layout/chrome, add a catch-all file route instead (`[...slug].tsx` -> `*`).
+     */
+    notFound?: any;
+    /**
+     * How route changes are presented. `'auto'` (the default) hands the DOM swap to the
+     * browser's View Transition API where there is one, and navigates directly where
+     * there is not; `'none'` always navigates directly.
+     *
+     * A reader who asked for reduced motion never gets an animation either way. Styling
+     * is the native mechanism: `::view-transition-old(root)` and
+     * `::view-transition-new(root)`: so the router imposes no visual style of its own.
+     */
+    transition?: TransitionMode;
+}
+/**
+ * The router. Matches the current URL against `routes` and renders what matches.
+ *
+ * Supplies the router context everything below reaches through `useRouter`,
+ * `useNavigate` and `Link`, so those only work inside it. `history` defaults to a
+ * browser history; pass a memory history for tests or a server render. An unmatched URL
+ * renders `notFound`, which defaults to a minimal built-in page so a bad URL is never
+ * blank. For a 404 that keeps your layout, add a catch-all file route instead.
+ *
+ * @example
+ * ```ts
+ * html`<${Router} routes=${routes} base="/app" />`;
+ * ```
+ */
+export declare function Router<C = any>(props: RouterProps<C>): any;
+/** Renders this layout's child route, inside this layout's context. */
+export declare function Outlet(): any;
+/**
+ * Whether a navigation is in progress: from the moment it starts until the route it lands on
+ * has loaded its modules and its route data. For a progress bar or a busy cursor.
+ *
+ * `delay` holds the `true` back until the navigation has lasted that many milliseconds, so a
+ * navigation that settles at once shows nothing. It still turns `false` the moment it ends.
+ *
+ * @example
+ * ```tsx
+ * const routing = useIsRouting({ delay: 120 });
+ * <div class="progress" data-active={() => (routing() ? '' : undefined)} />
+ * ```
+ */
+export declare function useIsRouting(options?: {
+    delay?: number;
+}): () => boolean;
+/** Navigate to `to` on mount (replace by default). Renders nothing. */
+export declare function Redirect(props: {
+    to: string;
+    replace?: boolean;
+}): null;
+/**
+ * The router context: the router itself, the current match, and the location.
+ *
+ * Safe to call during a server render, where a detached context yields a no-op stub
+ * rather than throwing, since an SSR pass has nowhere to navigate to. On the client a
+ * missing router is genuine misuse and throws, because the alternative is a component
+ * that silently never navigates.
+ */
+export declare function useRouter(): RouterCtxValue;
+/**
+ * Reactive merged params across all matched layers, as an accessor. Deep-equal
+ * memoized so it only notifies when a value actually changes (the underlying
+ * params object is rebuilt on every transition).
+ */
+export declare function useParams<T extends Record<string, string> = Record<string, string>>(): () => T;
+/** Params introduced at the nearest matched layer. */
+export declare function useLevelParams(): Record<string, string>;
+/**
+ * Reactive accessor for a single route param. Default `===` equality on the
+ * string value, so it only re-triggers when this key changes, not when other
+ * params at the same level change.
+ */
+export declare function useParam(key: string): () => string | undefined;
+/**
+ * Derive a stable value from route params. Only re-triggers when the selector's
+ * return value changes. For object returns, pass a custom `equals`.
+ *
+ * @example
+ * const ids = useParamSelector((p) => ({ wsId: p.workspaceId, chId: p.channelId }), deepEqual);
+ */
+export declare function useParamSelector<T>(selector: (params: Record<string, string>) => T, equals?: (a: T, b: T) => boolean): () => T;
+/**
+ * Match a path pattern against the current pathname, reactively. Returns the
+ * matched `{ params, path }` or null.
+ */
+export declare function useMatch(path: (() => string) | string): () => {
+    params: Record<string, string>;
+    path: string;
+} | null;
+/**
+ * Read/write the current query string. Returns `[params, setParams]`: `params`
+ * is a reactive accessor of the parsed query; `setParams` merges the given keys
+ * (null deletes) and navigates. Matches the old router.
+ */
+export declare function useSearchParams(): readonly [
+    () => Record<string, string>,
+    (next: Record<string, string | null>, options?: NavigateOptions) => void
+];
+/**
+ * Stable accessor from any reactive source with deep-equal memoization. Pass a
+ * `key` to select a nested property. Only re-triggers downstream when the value
+ * (or selected field) actually changes.
+ *
+ * @example
+ * const ws = select(store.activeWorkspace);        // whole object
+ * const id = select(store.activeWorkspace, 'id');  // single field
+ */
+export declare function select<T, K extends string = never>(source: () => T, key?: K): () => IsUndefined<K> extends true ? T : GetAtPath<T, K>;
+/**
+ * The current location as a reactive object: reading a property (pathname, etc.)
+ * subscribes to location changes. Matches the old router's useLocation().
+ */
+export declare function useLocation(): RouterLocation;
+export interface LinkNavigationOptions {
+    /** Replace the current history entry instead of pushing a new one. */
+    replace?: boolean;
+    /** How this navigation is presented. Defaults to the Router's own setting. */
+    transition?: TransitionMode;
+    /**
+     * Called with the resolved URL before navigating. Return false to leave the click
+     * alone, for a section of the app that must load as a document (a different
+     * bundle, a server-rendered admin area, a file route).
+     */
+    shouldNavigate?: (url: URL, anchor: HTMLAnchorElement) => boolean;
+}
+/**
+ * A delegated click handler that turns plain `<a>` elements into client-side navigations.
+ *
+ * `<Link>` covers the links an app writes as JSX. This covers the ones it doesn't own:
+ * markdown or CMS HTML dropped in through `innerHTML`, where there is no component to
+ * bind to and the anchors arrive as prerendered text. Put it on the container and every
+ * link inside it navigates without reloading the document:
+ *
+ * ```tsx
+ * const onClick = useLinkNavigation();
+ * <article onClick={onClick} innerHTML={doc.html} />
+ * ```
+ *
+ * The anchors stay real anchors: middle-click, right-click -> open in new tab, "copy
+ * link address" and crawlers all keep working, because the element is untouched and only
+ * a plain left-click is intercepted.
+ *
+ * Left alone: modified clicks, anything but the primary button, an already-prevented
+ * event, `target`, `download`, `rel="external"`, a non-http scheme (`mailto:`, `tel:`),
+ * another origin, and a hash pointing inside the current page, that last one is the
+ * browser's scroll, and hijacking it breaks in-page anchors.
+ */
+export declare function useLinkNavigation(options?: LinkNavigationOptions): (event: MouseEvent) => void;
+/**
+ * A function that navigates, for use outside a `Link`.
+ *
+ * Reach for it after an action rather than for a plain link: a form that redirects on
+ * success, a guard that bounces an unauthenticated visitor. Prefer `Link` for anything a
+ * visitor clicks, since an anchor is what middle-click, copy-link and a crawler expect.
+ *
+ * Navigation is a no-op during a server render, for the reason `useRouter` explains.
+ *
+ * @example
+ * ```ts
+ * const navigate = useNavigate();
+ * await save(form);
+ * navigate(`/posts/${id}`, { replace: true });
+ * ```
+ */
+export declare function useNavigate(): (to: string, options?: NavigateOptions & {
+    transition?: TransitionMode;
+}) => void;
+/**
+ * The resolved data for the nearest route that declared a `data` loader. Always
+ * returns a callable accessor (matching the old router): it suspends under
+ * <Suspense> while loading and yields undefined when no ancestor declared data.
+ */
+export declare function useRouteData<T = any>(): () => T | undefined;
+type MaybeAccessor<T> = T | (() => T);
+export interface LinkProps {
+    href: MaybeAccessor<string>;
+    replace?: MaybeAccessor<boolean>;
+    /** Override active state. Defaults to current pathname === href. */
+    active?: MaybeAccessor<boolean>;
+    class?: MaybeAccessor<string>;
+    className?: MaybeAccessor<string>;
+    /** Class added while the link is active. */
+    activeClass?: MaybeAccessor<string>;
+    slot?: string;
+    children?: any;
+    /**
+     * Everything else is forwarded onto the `<a>`: id, style, title, aria-*,
+     * data-*, event handlers. Typed openly because the forwarding is
+     * allow-by-default: a prop this interface forgot still reaches the DOM, and
+     * refusing it here would only mean the type disagreeing with the runtime.
+     */
+    [key: string]: unknown;
+}
+/**
+ * An anchor that navigates without a full page load.
+ *
+ * Renders a real `<a href>`, so middle-click, copy-link, and a crawler all behave. A
+ * plain left click is intercepted and routed instead.
+ *
+ * Active state defaults to the current pathname matching `href`, and `activeClass` is
+ * added while it holds. Override `active` when a section link should stay lit for its
+ * children.
+ *
+ * @example
+ * ```ts
+ * html`<${Link} href="/about" activeClass="current">About</${Link}>`;
+ * ```
+ */
+export declare function Link(props: LinkProps): any;
+/** Alias for {@link Link}. */
+export declare const A: typeof Link;
+import type { Action } from './data.js';
+export interface ActionFormProps {
+    /** The action to run on submit (typically wrapping a `"use server"` function). */
+    action: Action<any, any>;
+    /** Extra class on the <form>. */
+    class?: string;
+    children?: any;
+    [key: string]: any;
+}
+/**
+ * A `<form>` wired to a router action: on submit it builds `FormData` from the form and calls
+ * `action(formData)` (which tracks submission state via `useSubmission`), without a full
+ * page navigation. The markup carries `method="post"` + `action={action.url}` so it's
+ * progressive-enhancement-ready.
+ *
+ *   <ActionForm action={save}>
+ *     <input name="title" />
+ *     <button>Save</button>
+ *   </ActionForm>
+ *
+ * It sends what the fields hold and checks nothing. For a form whose fields are validated
+ * first, use `@fluixi-ui/form`'s `Form` with an `action`.
+ */
+export declare function ActionForm(props: ActionFormProps): any;
+/**
+ * Download the lazy component chunks for the route(s) matching `pathname` and resolve when
+ * they're all loaded. Await this before hydrating: once each matched lazy file-route is
+ * resolved it renders synchronously on the first pass (no Suspense fallback, no late
+ * re-render), so hydration adopts the server DOM in place instead of building a duplicate
+ * subtree next to it. No-op for routes with no lazy components. Safe to call when the URL
+ * matches nothing (resolves immediately).
+ */
+export declare function preloadRoutes<C = any>(routes: RouteDefinition<C>[], pathname: string): Promise<void>;
+export { createMemoryHistory, createBrowserHistory, matchRoutes, matchPath, } from '@fluixi/router';
+export type { RouteDefinition, RouteMatch, MatchedRoute, RouterLocation, NavigateOptions, HistoryAdapter, } from '@fluixi/router';
+export { cache, action, revalidate, createAsync, useSubmission, useSubmissions, useAction, } from './data.js';
+export type { RouteDataArgs, RouteLoadFunc, Action, ActionOptions, CacheOptions, Submission, CacheFn, } from './data.js';
+export { lazy } from '../render/lazy.js';
+export { supportsViewTransitions, prefersReducedMotion, type TransitionMode, } from './transition.js';
+export { runWithOwner } from '@fluixi/reactive/signal';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/lib/router/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/router/index.ts"],"names":[],"mappings":"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"}