toiljs 0.0.12 → 0.0.15

package/examples/basic/client/routes/search.tsx

@@ -1,61 +1,61 @@
-import { useState } from 'react';
-
-export const metadata: Toil.Metadata = {
-    title: 'Search',
-    description: 'Search every page by its metadata and jump straight to it.',
-    keywords: ['search', 'find', 'pages', 'metadata']
-};
-
-// A tiny site-wide search box. `usePageSearch` queries the compiler-built index of every page's
-// metadata (title/description/keywords/OpenGraph + static `searchHints` on dynamic routes), returns
-// ranked matches with their route `path`, and `goTo` navigates to whichever one you pick.
-export default function Search() {
-    const [query, setQuery] = useState('');
-    const { results, pages, goTo } = Toil.usePageSearch(query, { includeDynamic: true });
-
-    return (
-        <main>
-            <h1>Search</h1>
-            <p>
-                Type to search across the metadata of all {pages.length} pages — title, description, keywords, and
-                OpenGraph. Indexed at build by <code>client/routes/*</code>.
-            </p>
-
-            <input
-                type="search"
-                value={query}
-                onChange={(e) => {
-                    setQuery(e.target.value);
-                }}
-                placeholder="Search pages… (try “blog”, “features”, “started”)"
-                aria-label="Search pages"
-                autoFocus
-                style={{ width: '100%', padding: '0.6rem 0.8rem', fontSize: '1rem' }}
-            />
-
-            {query.trim() !== '' && (
-                <ul style={{ listStyle: 'none', padding: 0, marginTop: '1rem' }}>
-                    {results.length === 0 && <li>No pages match “{query}”.</li>}
-                    {results.map((r) => (
-                        <li key={r.page.path} style={{ marginBottom: '0.75rem' }}>
-                            <button
-                                type="button"
-                                onClick={() => {
-                                    goTo(r);
-                                }}
-                                disabled={r.page.dynamic}
-                                title={r.page.dynamic ? 'Dynamic route — needs params to open' : undefined}
-                                style={{ textAlign: 'left', cursor: r.page.dynamic ? 'default' : 'pointer' }}>
-                                <strong>{r.page.metadata.title ?? r.page.path}</strong> <code>{r.page.path}</code>
-                                {r.page.metadata.description !== undefined && <div>{r.page.metadata.description}</div>}
-                                <small>
-                                    score {r.score.toFixed(1)} · matched {r.matches.join(', ')}
-                                </small>
-                            </button>
-                        </li>
-                    ))}
-                </ul>
-            )}
-        </main>
-    );
-}
+import { useState } from 'react';
+
+export const metadata: Toil.Metadata = {
+    title: 'Search',
+    description: 'Search every page by its metadata and jump straight to it.',
+    keywords: ['search', 'find', 'pages', 'metadata']
+};
+
+// A tiny site-wide search box. `usePageSearch` queries the compiler-built index of every page's
+// metadata (title/description/keywords/OpenGraph + static `searchHints` on dynamic routes), returns
+// ranked matches with their route `path`, and `goTo` navigates to whichever one you pick.
+export default function Search() {
+    const [query, setQuery] = useState('');
+    const { results, pages, goTo } = Toil.usePageSearch(query, { includeDynamic: true });
+
+    return (
+        <main>
+            <h1>Search</h1>
+            <p>
+                Type to search across the metadata of all {pages.length} pages, title, description, keywords, and
+                OpenGraph. Indexed at build by <code>client/routes/*</code>.
+            </p>
+
+            <input
+                type="search"
+                value={query}
+                onChange={(e) => {
+                    setQuery(e.target.value);
+                }}
+                placeholder="Search pages… (try “blog”, “features”, “started”)"
+                aria-label="Search pages"
+                autoFocus
+                style={{ width: '100%', padding: '0.6rem 0.8rem', fontSize: '1rem' }}
+            />
+
+            {query.trim() !== '' && (
+                <ul style={{ listStyle: 'none', padding: 0, marginTop: '1rem' }}>
+                    {results.length === 0 && <li>No pages match “{query}”.</li>}
+                    {results.map((r) => (
+                        <li key={r.page.path} style={{ marginBottom: '0.75rem' }}>
+                            <button
+                                type="button"
+                                onClick={() => {
+                                    goTo(r);
+                                }}
+                                disabled={r.page.dynamic}
+                                title={r.page.dynamic ? 'Dynamic route, needs params to open' : undefined}
+                                style={{ textAlign: 'left', cursor: r.page.dynamic ? 'default' : 'pointer' }}>
+                                <strong>{r.page.metadata.title ?? r.page.path}</strong> <code>{r.page.path}</code>
+                                {r.page.metadata.description !== undefined && <div>{r.page.metadata.description}</div>}
+                                <small>
+                                    score {r.score.toFixed(1)} · matched {r.matches.join(', ')}
+                                </small>
+                            </button>
+                        </li>
+                    ))}
+                </ul>
+            )}
+        </main>
+    );
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.12",
+    "version": "0.0.15",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "engines": {
@@ -77,7 +77,7 @@
         "build:io": "tsc -p tsconfig.io.json",
         "build:backend": "tsc -p tsconfig.backend.json",
         "build:compiler": "tsc -p tsconfig.compiler.json",
-        "build:cli": "tsc -p tsconfig.cli.json",
+        "build:cli": "tsc -p tsconfig.cli.json --noEmit && esbuild src/cli/index.ts --bundle --platform=node --format=esm --outfile=build/cli/index.js --external:toiljs/*",
         "build:server": "toilscript --target release",
         "test": "vitest run --coverage",
         "test:watch": "vitest",
@@ -94,7 +94,6 @@
         "@btc-vision/as-bignum": "^1.0.0",
         "@btc-vision/as-loader": "^0.0.0",
         "@btc-vision/hyper-express": "^6.17.4",
-        "@clack/prompts": "^1.5.0",
         "@eslint-react/eslint-plugin": "^5.8.8",
         "@eslint/js": "^10.0.1",
         "@typescript-eslint/utils": "^8.60.0",
@@ -118,6 +117,7 @@
     },
     "devDependencies": {
         "@babel/core": "^7.29.7",
+        "@clack/prompts": "^1.5.0",
         "@babel/preset-env": "^7.29.7",
         "@babel/preset-typescript": "^7.29.7",
         "@btc-vision/as-covers-assembly": "^0.4.5",
@@ -133,6 +133,7 @@
         "@types/react-dom": "^19.2.3",
         "@vitest/coverage-v8": "^4.1.7",
         "@vitest/ui": "^4.1.7",
+        "esbuild": "^0.28.0",
         "eslint": "^10.4.1",
         "jsdom": "^29.1.1",
         "micromatch": "^4.0.8",

package/src/client/head/metadata.ts

@@ -1,94 +1,112 @@
-/**
- * Route metadata, the declarative SEO counterpart to `useHead`/`<Head>`. A route file may
- * `export const metadata` (static) or `export const generateMetadata` (dynamic, using its loader
- * data); the compiler-driven loader resolves it to a {@link HeadSpec} that the router applies as the
- * route's baseline head (component-level `useHead`/`<Head>` still compose on top and can override).
- */
-import type { HeadSpec, LinkTag, MetaTag } from './head.js';
-import type { RouteParams } from '../routing/match.js';
-
-/** OpenGraph fields, expanded to `og:*` meta tags. */
-export interface OpenGraph {
-    readonly title?: string;
-    readonly description?: string;
-    readonly type?: string;
-    readonly url?: string;
-    readonly image?: string;
-    readonly siteName?: string;
-}
-
-/** A route's metadata. Convenience fields expand to the right `<meta>`/`<link>` tags. */
-export interface Metadata {
-    /** Document title. */
-    readonly title?: string;
-    /** Template applied to the title (`%s` = the title), e.g. `'%s · toiljs'`. */
-    readonly titleTemplate?: string;
-    /** `<meta name="description">`. */
-    readonly description?: string;
-    /** `<meta name="keywords">`, joined with `, ` if an array. */
-    readonly keywords?: string | readonly string[];
-    /** `<link rel="canonical">`. */
-    readonly canonical?: string;
-    /** `<meta name="robots">`, e.g. `'noindex, nofollow'`. */
-    readonly robots?: string;
-    /** `<meta name="theme-color">`. */
-    readonly themeColor?: string;
-    /** OpenGraph (`og:*`) tags. */
-    readonly openGraph?: OpenGraph;
-    /** Escape hatch: extra raw `<meta>` tags. */
-    readonly meta?: readonly MetaTag[];
-    /** Escape hatch: extra raw `<link>` tags. */
-    readonly link?: readonly LinkTag[];
-}
-
-/** Arguments passed to {@link GenerateMetadata}: route params, query, and the loader's data. */
-export interface GenerateMetadataArgs<T = unknown> {
-    readonly params: RouteParams;
-    readonly searchParams: URLSearchParams;
-    readonly data: T;
-}
-
-/** A route's `export const generateMetadata`, dynamic metadata derived from params/query/loader data. */
-export type GenerateMetadata<T = unknown> = (
-    args: GenerateMetadataArgs<T>,
-) => Metadata | Promise<Metadata>;
-
-/** Expands a {@link Metadata} into a {@link HeadSpec} (title + concrete meta/link tags). */
-export function resolveMetadata(metadata: Metadata): HeadSpec {
-    const meta: MetaTag[] = [];
-    if (metadata.description !== undefined) {
-        meta.push({ name: 'description', content: metadata.description });
-    }
-    if (metadata.keywords !== undefined) {
-        const content =
-            typeof metadata.keywords === 'string'
-                ? metadata.keywords
-                : metadata.keywords.join(', ');
-        meta.push({ name: 'keywords', content });
-    }
-    if (metadata.robots !== undefined) meta.push({ name: 'robots', content: metadata.robots });
-    if (metadata.themeColor !== undefined) {
-        meta.push({ name: 'theme-color', content: metadata.themeColor });
-    }
-    const og = metadata.openGraph;
-    if (og) {
-        const pairs: readonly [string, string | undefined][] = [
-            ['og:title', og.title],
-            ['og:description', og.description],
-            ['og:type', og.type],
-            ['og:url', og.url],
-            ['og:image', og.image],
-            ['og:site_name', og.siteName],
-        ];
-        for (const [property, content] of pairs) {
-            if (content !== undefined) meta.push({ property, content });
-        }
-    }
-    if (metadata.meta) meta.push(...metadata.meta);
-
-    const link: LinkTag[] = [];
-    if (metadata.canonical !== undefined) link.push({ rel: 'canonical', href: metadata.canonical });
-    if (metadata.link) link.push(...metadata.link);
-
-    return { title: metadata.title, titleTemplate: metadata.titleTemplate, meta, link };
-}
+/**
+ * Route metadata, the declarative SEO counterpart to `useHead`/`<Head>`. A route file may
+ * `export const metadata` (static) or `export const generateMetadata` (dynamic, using its loader
+ * data); the compiler-driven loader resolves it to a {@link HeadSpec} that the router applies as the
+ * route's baseline head (component-level `useHead`/`<Head>` still compose on top and can override).
+ */
+import { useHead, type HeadSpec, type LinkTag, type MetaTag } from './head.js';
+import type { RouteParams } from '../routing/match.js';
+
+/** OpenGraph fields, expanded to `og:*` meta tags. */
+export interface OpenGraph {
+    readonly title?: string;
+    readonly description?: string;
+    readonly type?: string;
+    readonly url?: string;
+    readonly image?: string;
+    readonly siteName?: string;
+}
+
+/** A route's metadata. Convenience fields expand to the right `<meta>`/`<link>` tags. */
+export interface Metadata {
+    /** Document title. */
+    readonly title?: string;
+    /** Template applied to the title (`%s` = the title), e.g. `'%s · toiljs'`. */
+    readonly titleTemplate?: string;
+    /** `<meta name="description">`. */
+    readonly description?: string;
+    /** `<meta name="keywords">`, joined with `, ` if an array. */
+    readonly keywords?: string | readonly string[];
+    /** `<link rel="canonical">`. */
+    readonly canonical?: string;
+    /** `<meta name="robots">`, e.g. `'noindex, nofollow'`. */
+    readonly robots?: string;
+    /** `<meta name="theme-color">`. */
+    readonly themeColor?: string;
+    /** OpenGraph (`og:*`) tags. */
+    readonly openGraph?: OpenGraph;
+    /** Escape hatch: extra raw `<meta>` tags. */
+    readonly meta?: readonly MetaTag[];
+    /** Escape hatch: extra raw `<link>` tags. */
+    readonly link?: readonly LinkTag[];
+}
+
+/** Arguments passed to {@link GenerateMetadata}: route params, query, and the loader's data. */
+export interface GenerateMetadataArgs<T = unknown> {
+    readonly params: RouteParams;
+    readonly searchParams: URLSearchParams;
+    readonly data: T;
+}
+
+/** A route's `export const generateMetadata`, dynamic metadata derived from params/query/loader data. */
+export type GenerateMetadata<T = unknown> = (
+    args: GenerateMetadataArgs<T>,
+) => Metadata | Promise<Metadata>;
+
+/** Expands a {@link Metadata} into a {@link HeadSpec} (title + concrete meta/link tags). */
+export function resolveMetadata(metadata: Metadata): HeadSpec {
+    const meta: MetaTag[] = [];
+    if (metadata.description !== undefined) {
+        meta.push({ name: 'description', content: metadata.description });
+    }
+    if (metadata.keywords !== undefined) {
+        const content =
+            typeof metadata.keywords === 'string'
+                ? metadata.keywords
+                : metadata.keywords.join(', ');
+        meta.push({ name: 'keywords', content });
+    }
+    if (metadata.robots !== undefined) meta.push({ name: 'robots', content: metadata.robots });
+    if (metadata.themeColor !== undefined) {
+        meta.push({ name: 'theme-color', content: metadata.themeColor });
+    }
+    const og = metadata.openGraph;
+    if (og) {
+        const pairs: readonly [string, string | undefined][] = [
+            ['og:title', og.title],
+            ['og:description', og.description],
+            ['og:type', og.type],
+            ['og:url', og.url],
+            ['og:image', og.image],
+            ['og:site_name', og.siteName],
+        ];
+        for (const [property, content] of pairs) {
+            if (content !== undefined) meta.push({ property, content });
+        }
+    }
+    if (metadata.meta) meta.push(...metadata.meta);
+
+    const link: LinkTag[] = [];
+    if (metadata.canonical !== undefined) link.push({ rel: 'canonical', href: metadata.canonical });
+    if (metadata.link) link.push(...metadata.link);
+
+    return { title: metadata.title, titleTemplate: metadata.titleTemplate, meta, link };
+}
+
+/**
+ * Applies a route-style {@link Metadata} object from inside any component for that component's
+ * lifetime, reverting on unmount. The runtime counterpart of a route's `metadata` export, for
+ * content that isn't itself a route file (a rendered article, a widget, ...). Composes through the
+ * head manager like {@link useHead}; a route's own `metadata` (applied last) still wins for keys it
+ * sets, so this fills in for routes that declare none. Resolved fresh each render, the head manager
+ * dedupes by value, so passing a computed object is fine.
+ */
+export function useMetadata(metadata: Metadata): void {
+    useHead(resolveMetadata(metadata));
+}
+
+/** Declarative form of {@link useMetadata}: `<Metadata title="…" openGraph={…} />`. Renders nothing. */
+export function Metadata(props: Metadata): null {
+    useMetadata(props);
+    return null;
+}

package/src/client/index.ts

@@ -1,79 +1,89 @@
-/**
- * toiljs client runtime, published as `toiljs/client`. Re-exports the router (mount/Router/Link),
- * navigation hooks, prefetching, and the route types consumed by the compiler-generated entry.
- * Zero imports needed in user route files beyond this package.
- *
- * Internals are split by concern: route `types`, history-based `navigation`, the params
- * `params-context` + `hooks`, `lazy` component resolution, the `Link`/`Router` components,
- * `mount`, `match` (pure matcher), `prefetch` (link prefetcher), and `channel` (WebSocket helper).
- */
-
-export { mount } from './routing/mount.js';
-export { Router } from './routing/Router.js';
-export { Link } from './navigation/Link.js';
-export type { LinkProps } from './navigation/Link.js';
-export { NavLink, matchActive } from './navigation/NavLink.js';
-export type { NavLinkProps, NavLinkState } from './navigation/NavLink.js';
-export { navigate, back, forward, refresh, setViewTransitions } from './navigation/navigation.js';
-export type { NavigateOptions } from './navigation/navigation.js';
-export {
-    useParams,
-    useNavigate,
-    useLocation,
-    usePathname,
-    useSearchParams,
-    useRouter,
-    useNavigationPending,
-} from './routing/hooks.js';
-export type { RouterInstance } from './routing/hooks.js';
-export { useLoaderData, revalidate, invalidateLoaderData } from './routing/loader.js';
-export type { LoaderArgs, LoaderFunction, LoaderData, Revalidate } from './routing/loader.js';
-export { useAction } from './routing/action.js';
-export type {
-    UseActionOptions,
-    ActionState,
-    ActionHandle,
-    RevalidateTarget,
-} from './routing/action.js';
-export { prefetch } from './navigation/prefetch.js';
-export type {
-    RouteDef,
-    LayoutLoader,
-    LayoutComponentLoader,
-    NotFoundLoader,
-    RouteErrorProps,
-    Register,
-    RoutePath,
-    Href,
-} from './types.js';
-export { matchRoute } from './routing/match.js';
-export type { RouteParams } from './routing/match.js';
-export { connectChannel, useChannel, resolveChannelUrl } from './channel/channel.js';
-export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel/channel.js';
-export { useHead, useTitle, Head, mergeHead } from './head/head.js';
-export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head/head.js';
-export { resolveMetadata } from './head/metadata.js';
-export type {
-    Metadata,
-    GenerateMetadata,
-    GenerateMetadataArgs,
-    OpenGraph,
-} from './head/metadata.js';
-export { searchPages, registerPages, getPages, pagePath } from './search/search.js';
-export type {
-    PageMeta,
-    PageSearchResult,
-    PageSearchOptions,
-    SearchField,
-    SearchHints,
-} from './search/search.js';
-export { usePageSearch } from './search/use-page-search.js';
-export type { PageSearch } from './search/use-page-search.js';
-export { Image } from './components/Image.js';
-export type { ImageProps } from './components/Image.js';
-export { Script } from './components/Script.js';
-export type { ScriptProps, ScriptStrategy } from './components/Script.js';
-export { Form } from './components/Form.js';
-export type { FormProps } from './components/Form.js';
-export { Slot } from './components/Slot.js';
-export type { SlotProps } from './components/Slot.js';
+/**
+ * toiljs client runtime, published as `toiljs/client`. Re-exports the router (mount/Router/Link),
+ * navigation hooks, prefetching, and the route types consumed by the compiler-generated entry.
+ * Zero imports needed in user route files beyond this package.
+ *
+ * Internals are split by concern: route `types`, history-based `navigation`, the params
+ * `params-context` + `hooks`, `lazy` component resolution, the `Link`/`Router` components,
+ * `mount`, `match` (pure matcher), `prefetch` (link prefetcher), and `channel` (WebSocket helper).
+ */
+
+export { mount } from './routing/mount.js';
+export { Router } from './routing/Router.js';
+export { Link } from './navigation/Link.js';
+export type { LinkProps } from './navigation/Link.js';
+export { NavLink, matchActive } from './navigation/NavLink.js';
+export type { NavLinkProps, NavLinkState } from './navigation/NavLink.js';
+export {
+    navigate,
+    back,
+    forward,
+    refresh,
+    setViewTransitions,
+    setTransitions,
+    href,
+} from './navigation/navigation.js';
+export type { NavigateOptions } from './navigation/navigation.js';
+export {
+    useParams,
+    useNavigate,
+    useLocation,
+    usePathname,
+    useSearchParams,
+    useRouter,
+    useNavigationPending,
+} from './routing/hooks.js';
+export type { RouterInstance } from './routing/hooks.js';
+export { useLoaderData, revalidate, invalidateLoaderData } from './routing/loader.js';
+export type {
+    LoaderArgs,
+    LoaderFunction,
+    LoaderData,
+    Revalidate,
+    StaticParams,
+    GenerateStaticParams,
+} from './routing/loader.js';
+export { useAction } from './routing/action.js';
+export type {
+    UseActionOptions,
+    ActionState,
+    ActionHandle,
+    RevalidateTarget,
+} from './routing/action.js';
+export { prefetch } from './navigation/prefetch.js';
+export type {
+    RouteDef,
+    LayoutLoader,
+    LayoutComponentLoader,
+    NotFoundLoader,
+    RouteErrorProps,
+    Register,
+    RoutePath,
+    Href,
+} from './types.js';
+export { matchRoute } from './routing/match.js';
+export type { RouteParams } from './routing/match.js';
+export { connectChannel, useChannel, resolveChannelUrl } from './channel/channel.js';
+export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel/channel.js';
+export { useHead, useTitle, Head, mergeHead } from './head/head.js';
+export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head/head.js';
+export { resolveMetadata, useMetadata, Metadata } from './head/metadata.js';
+export type { GenerateMetadata, GenerateMetadataArgs, OpenGraph } from './head/metadata.js';
+export { searchPages, registerPages, getPages, pagePath } from './search/search.js';
+export type {
+    PageMeta,
+    PageSearchResult,
+    PageSearchOptions,
+    SearchField,
+    SearchHints,
+} from './search/search.js';
+export { usePageSearch } from './search/use-page-search.js';
+export type { PageSearch } from './search/use-page-search.js';
+export { Image } from './components/Image.js';
+export type { ImageProps } from './components/Image.js';
+export { Script } from './components/Script.js';
+export type { ScriptProps, ScriptStrategy } from './components/Script.js';
+export { Form } from './components/Form.js';
+export type { FormProps } from './components/Form.js';
+export { Slot } from './components/Slot.js';
+export type { SlotProps } from './components/Slot.js';