toiljs 0.0.14 → 0.0.16

package/src/client/search/use-page-search.ts

@@ -1,73 +1,73 @@
-/**
- * React binding for the page-metadata {@link searchPages search}. Gives a route component reactive,
- * memoized search results plus a `goTo` helper that navigates straight to a matched page, a drop-in
- * for a site-wide "jump to page" / command-palette style search box.
- */
-import { useMemo } from 'react';
-
-import { navigate, type NavigateOptions } from '../navigation/navigation.js';
-import type { Href } from '../types.js';
-import {
-    getPages,
-    type PageMeta,
-    pagePath,
-    type PageSearchOptions,
-    type PageSearchResult,
-    searchPages,
-} from './search.js';
-
-/** What {@link usePageSearch} returns. */
-export interface PageSearch {
-    /** Ranked matches for the current query (best first); empty when the query is blank. */
-    readonly results: readonly PageSearchResult[];
-    /** The full registered page index (handy for rendering an "all pages" listing). */
-    readonly pages: readonly PageMeta[];
-    /**
-     * Navigates to a result / page / raw path. A dynamic (`:param`) page can't be navigated to
-     * as-is, so passing one (or its result) is a no-op unless you pass a concrete path string with
-     * the params already filled in. A stable reference, safe to destructure.
-     */
-    readonly goTo: (
-        target: string | PageMeta | PageSearchResult,
-        options?: NavigateOptions,
-    ) => void;
-}
-
-/** Whether a path can be navigated to directly (no unfilled dynamic segments). */
-function isNavigable(path: string): boolean {
-    return !/[:*]/.test(path);
-}
-
-/**
- * Searches the project's pages by `query` and returns ranked {@link PageSearchResult}s, recomputed
- * only when the query or options change. Use the returned `goTo` to redirect to a match:
- *
- * ```tsx
- * const { results, goTo } = usePageSearch(query);
- * return results.map((r) => (
- *   <button key={r.page.path} onClick={() => { goTo(r); }}>{r.page.metadata.title ?? r.page.path}</button>
- * ));
- * ```
- */
-export function usePageSearch(query: string, options: PageSearchOptions = {}): PageSearch {
-    const { limit, includeDynamic, fields } = options;
-    const fieldsKey = fields?.join(',');
-    const results = useMemo(
-        () => searchPages(query, { limit, includeDynamic, fields }),
-        // `fields` is compared by content (fieldsKey) so a fresh array literal each render is fine.
-        [query, limit, includeDynamic, fieldsKey],
-    );
-
-    return useMemo<PageSearch>(
-        () => ({
-            results,
-            pages: getPages(),
-            goTo(target, navOptions) {
-                const path = pagePath(target);
-                if (typeof target !== 'string' && !isNavigable(path)) return;
-                navigate(path as Href, navOptions);
-            },
-        }),
-        [results],
-    );
-}
+/**
+ * React binding for the page-metadata {@link searchPages search}. Gives a route component reactive,
+ * memoized search results plus a `goTo` helper that navigates straight to a matched page, a drop-in
+ * for a site-wide "jump to page" / command-palette style search box.
+ */
+import { useMemo } from 'react';
+
+import { navigate, type NavigateOptions } from '../navigation/navigation.js';
+import type { Href } from '../types.js';
+import {
+    getPages,
+    type PageMeta,
+    pagePath,
+    type PageSearchOptions,
+    type PageSearchResult,
+    searchPages,
+} from './search.js';
+
+/** What {@link usePageSearch} returns. */
+export interface PageSearch {
+    /** Ranked matches for the current query (best first); empty when the query is blank. */
+    readonly results: readonly PageSearchResult[];
+    /** The full registered page index (handy for rendering an "all pages" listing). */
+    readonly pages: readonly PageMeta[];
+    /**
+     * Navigates to a result / page / raw path. A dynamic (`:param`) page can't be navigated to
+     * as-is, so passing one (or its result) is a no-op unless you pass a concrete path string with
+     * the params already filled in. A stable reference, safe to destructure.
+     */
+    readonly goTo: (
+        target: string | PageMeta | PageSearchResult,
+        options?: NavigateOptions,
+    ) => void;
+}
+
+/** Whether a path can be navigated to directly (no unfilled dynamic segments). */
+function isNavigable(path: string): boolean {
+    return !/[:*]/.test(path);
+}
+
+/**
+ * Searches the project's pages by `query` and returns ranked {@link PageSearchResult}s, recomputed
+ * only when the query or options change. Use the returned `goTo` to redirect to a match:
+ *
+ * ```tsx
+ * const { results, goTo } = usePageSearch(query);
+ * return results.map((r) => (
+ *   <button key={r.page.path} onClick={() => { goTo(r); }}>{r.page.metadata.title ?? r.page.path}</button>
+ * ));
+ * ```
+ */
+export function usePageSearch(query: string, options: PageSearchOptions = {}): PageSearch {
+    const { limit, includeDynamic, fields } = options;
+    const fieldsKey = fields?.join(',');
+    const results = useMemo(
+        () => searchPages(query, { limit, includeDynamic, fields }),
+        // `fields` is compared by content (fieldsKey) so a fresh array literal each render is fine.
+        [query, limit, includeDynamic, fieldsKey],
+    );
+
+    return useMemo<PageSearch>(
+        () => ({
+            results,
+            pages: getPages(),
+            goTo(target, navOptions) {
+                const path = pagePath(target);
+                if (typeof target !== 'string' && !isNavigable(path)) return;
+                navigate(path as Href, navOptions);
+            },
+        }),
+        [results],
+    );
+}

package/src/client/types.ts

@@ -1,73 +1,73 @@
-/**
- * Public router types shared across the client runtime. Kept dependency-free (type-only React
- * imports) so any module can import them without pulling in component or DOM code.
- */
-import type { ComponentType, ReactNode } from 'react';
-
-/**
- * Augmentation point for the project's generated route types. The compiler emits (into
- * `toil-routes.d.ts`) `declare module 'toiljs/client' { interface Register { routePath: <union> } }`,
- * which narrows {@link RoutePath} from `string` to the project's actual routes.
- */
-export interface Register {}
-
-/**
- * Union of the project's route paths, static routes as literals, dynamic/catch-all as
- * `` `…/${string}` `` templates. Falls back to `string` before the types are generated.
- */
-export type RoutePath = Register extends { routePath: infer P }
-    ? P extends string
-        ? P
-        : string
-    : string;
-
-/**
- * An href accepted by `Link` / `NavLink` / `navigate`: a known {@link RoutePath} (optionally with
- * `?query` or `#hash`), or an absolute/protocol URL (`https:`, `mailto:`, …). When routes haven't
- * been generated yet, this is just `string`.
- */
-export type Href =
-    | RoutePath
-    | `${RoutePath}?${string}`
-    | `${RoutePath}#${string}`
-    | `${string}:${string}`;
-
-/** Lazy loader for a layout component (wraps children). */
-export type LayoutComponentLoader = () => Promise<{
-    default: ComponentType<{ children?: ReactNode }>;
-}>;
-
-/** Props passed to an `error.tsx` / `global-error.tsx` component. */
-export interface RouteErrorProps {
-    readonly error: Error;
-    readonly reset: () => void;
-}
-
-/** Lazy loader for an error component (`error.tsx` / `global-error.tsx`), or `null` if none. */
-export type ErrorComponentLoader =
-    | (() => Promise<{ default: ComponentType<RouteErrorProps> }>)
-    | null;
-
-/**
- * A route entry produced by the compiler: a URL pattern, a lazy loader for its page component, and
- * the chain of nested layout loaders (shallowest → deepest, from nested `layout.tsx` files) that wrap it.
- */
-export interface RouteDef {
-    readonly pattern: string;
-    readonly load: () => Promise<{ default: ComponentType }>;
-    readonly layouts?: readonly LayoutComponentLoader[];
-    /** `template.tsx` chain (root → nested), like layouts, but re-mounted on each navigation. */
-    readonly templates?: readonly LayoutComponentLoader[];
-    /** Nearest `loading.tsx`, shown as the Suspense fallback while this route loads. */
-    readonly loading?: () => Promise<{ default: ComponentType }>;
-    /** Nearest `error.tsx`, rendered by an error boundary around this route. */
-    readonly errorComponent?: () => Promise<{ default: ComponentType<RouteErrorProps> }>;
-    /** Intercepting route (`(.)`/`(..)`/`(...)`), matched in its slot only on soft navigation. */
-    readonly intercept?: boolean;
-}
-
-/** Optional root layout loader (wraps every page). `null` when the project defines no layout. */
-export type LayoutLoader = LayoutComponentLoader | null;
-
-/** Optional custom not-found (404) page loader, rendered when no route matches. */
-export type NotFoundLoader = (() => Promise<{ default: ComponentType }>) | null;
+/**
+ * Public router types shared across the client runtime. Kept dependency-free (type-only React
+ * imports) so any module can import them without pulling in component or DOM code.
+ */
+import type { ComponentType, ReactNode } from 'react';
+
+/**
+ * Augmentation point for the project's generated route types. The compiler emits (into
+ * `toil-routes.d.ts`) `declare module 'toiljs/client' { interface Register { routePath: <union> } }`,
+ * which narrows {@link RoutePath} from `string` to the project's actual routes.
+ */
+export interface Register {}
+
+/**
+ * Union of the project's route paths, static routes as literals, dynamic/catch-all as
+ * `` `…/${string}` `` templates. Falls back to `string` before the types are generated.
+ */
+export type RoutePath = Register extends { routePath: infer P }
+    ? P extends string
+        ? P
+        : string
+    : string;
+
+/**
+ * An href accepted by `Link` / `NavLink` / `navigate`: a known {@link RoutePath} (optionally with
+ * `?query` or `#hash`), or an absolute/protocol URL (`https:`, `mailto:`, …). When routes haven't
+ * been generated yet, this is just `string`.
+ */
+export type Href =
+    | RoutePath
+    | `${RoutePath}?${string}`
+    | `${RoutePath}#${string}`
+    | `${string}:${string}`;
+
+/** Lazy loader for a layout component (wraps children). */
+export type LayoutComponentLoader = () => Promise<{
+    default: ComponentType<{ children?: ReactNode }>;
+}>;
+
+/** Props passed to an `error.tsx` / `global-error.tsx` component. */
+export interface RouteErrorProps {
+    readonly error: Error;
+    readonly reset: () => void;
+}
+
+/** Lazy loader for an error component (`error.tsx` / `global-error.tsx`), or `null` if none. */
+export type ErrorComponentLoader =
+    | (() => Promise<{ default: ComponentType<RouteErrorProps> }>)
+    | null;
+
+/**
+ * A route entry produced by the compiler: a URL pattern, a lazy loader for its page component, and
+ * the chain of nested layout loaders (shallowest → deepest, from nested `layout.tsx` files) that wrap it.
+ */
+export interface RouteDef {
+    readonly pattern: string;
+    readonly load: () => Promise<{ default: ComponentType }>;
+    readonly layouts?: readonly LayoutComponentLoader[];
+    /** `template.tsx` chain (root → nested), like layouts, but re-mounted on each navigation. */
+    readonly templates?: readonly LayoutComponentLoader[];
+    /** Nearest `loading.tsx`, shown as the Suspense fallback while this route loads. */
+    readonly loading?: () => Promise<{ default: ComponentType }>;
+    /** Nearest `error.tsx`, rendered by an error boundary around this route. */
+    readonly errorComponent?: () => Promise<{ default: ComponentType<RouteErrorProps> }>;
+    /** Intercepting route (`(.)`/`(..)`/`(...)`), matched in its slot only on soft navigation. */
+    readonly intercept?: boolean;
+}
+
+/** Optional root layout loader (wraps every page). `null` when the project defines no layout. */
+export type LayoutLoader = LayoutComponentLoader | null;
+
+/** Optional custom not-found (404) page loader, rendered when no route matches. */
+export type NotFoundLoader = (() => Promise<{ default: ComponentType }>) | null;

package/src/compiler/config.ts

@@ -8,6 +8,29 @@ import { type SeoConfig } from './seo.js';
 
 export type { SeoConfig } from './seo.js';
 
+/** Built-in AI providers the dev toolbar can proxy to. */
+export enum AiProvider {
+    Anthropic = 'anthropic',
+    OpenAI = 'openai',
+}
+
+/** Dev toolbar AI integration (dev only; the key stays server-side). */
+export interface DevtoolsAiConfig {
+    /** Built-in provider. With `endpoint` set, that takes precedence. */
+    readonly provider?: AiProvider;
+    /** Model id (e.g. `claude-sonnet-4-6`, `gpt-4o`). */
+    readonly model?: string;
+    /** Name of the env var holding the API key (read by the dev server, never sent to the client). */
+    readonly apiKeyEnv?: string;
+    /** Custom POST endpoint (`{ prompt }` in, `{ text }` out); overrides `provider`. */
+    readonly endpoint?: string;
+}
+
+/** Dev toolbar configuration. */
+export interface DevtoolsConfig {
+    readonly ai?: DevtoolsAiConfig;
+}
+
 /**
  * Client-side (TSX/React/Vite) configuration. All fields optional; sensible defaults applied.
  */
@@ -19,7 +42,7 @@ export interface ClientConfig {
     /**
      * Static assets directory, relative to root. Default `<srcDir>/public` (e.g. `client/public`).
      * Holds the `index.html` template (owned and edited by you) plus any files served as-is at the
-     * base path (favicons, images, …).
+     * base path (favicons, images, and the like).
      */
     readonly publicDir?: string;
     /** Production output directory, relative to root. Default `build/client`. */
@@ -45,6 +68,19 @@ export interface ClientConfig {
      * `prefers-reduced-motion`. Default `false`.
      */
     readonly viewTransitions?: boolean;
+    /**
+     * Wrap client navigations in a React transition, keeping the current page visible while the next
+     * route's loader runs instead of showing its `loading.tsx` right away. Default `false` (a
+     * navigation commits eagerly, so the loading state appears immediately).
+     */
+    readonly transitions?: boolean;
+    /**
+     * The dev toolbar (a floating panel in `toiljs dev` with route/build info, errors, and live
+     * controls). `true` (default) / `false` to disable, or an object to configure its AI integration.
+     * Never included in production builds. The AI key is read server-side from `apiKeyEnv` and never
+     * reaches the browser; the toolbar always offers Claude/ChatGPT hand-off links regardless.
+     */
+    readonly devtools?: boolean | DevtoolsConfig;
     /**
      * Build-time SEO: bakes site-level metadata into the HTML `<head>` (so JS-less crawlers and AI
      * bots see real tags) and generates `robots.txt`, `sitemap.xml`, and `llms.txt`. Omit to skip.
@@ -100,6 +136,12 @@ export interface ResolvedToilConfig {
     readonly fonts: boolean;
     /** Whether animated View Transitions are enabled for navigation. */
     readonly viewTransitions: boolean;
+    /** Whether navigations are wrapped in a React transition (keep current page while loading). */
+    readonly transitions: boolean;
+    /** Whether the dev toolbar is enabled (dev only). */
+    readonly devtools: boolean;
+    /** Dev toolbar AI config (dev only), or `null` when not configured. */
+    readonly devtoolsAi: DevtoolsAiConfig | null;
     /** Build-time SEO config, or `null` when not configured. */
     readonly seo: SeoConfig | null;
     /** Absolute path to the framework client runtime (`toiljs/client`). */
@@ -166,6 +208,10 @@ export async function loadConfig(
         images: client.images ?? true,
         fonts: client.fonts ?? true,
         viewTransitions: client.viewTransitions ?? false,
+        transitions: client.transitions ?? false,
+        devtools: client.devtools !== false,
+        devtoolsAi:
+            typeof client.devtools === 'object' && client.devtools.ai ? client.devtools.ai : null,
         seo: client.seo ?? null,
         runtimePath: resolveRuntimePath(),
         vite: client.vite ?? {},