toiljs 0.0.115 → 0.0.117

package/docs/frontend/scripts.md

@@ -1,118 +0,0 @@
-# Scripts
-
-`Toil.Script` loads an external or inline `<script>` for you, with control over *when* it runs and a guarantee it runs only *once* across your whole app. Use it instead of a hand-written `<script>` tag for third-party snippets (analytics, chat widgets, embeds). It is the toiljs analog of Next.js `next/script`.
-
-## Why not just write a `<script>` tag?
-
-Dropping a raw `<script>` into your JSX is unreliable in a single-page app (an app where the browser loads one HTML shell and JavaScript swaps pages in place, with no full reload). Two problems:
-
-1. **It may not execute.** When React inserts a `<script>` element into the page, the browser does not always run it the way it runs scripts present in the original HTML.
-2. **It runs too often.** As the user navigates between routes that both render that script, React can mount it more than once, so an analytics library or a widget initialises twice.
-
-`Toil.Script` fixes both: it injects a real `<script>` into `<head>` so the browser runs it, and it **deduplicates** by a key so a given script executes at most once for the whole life of the app, even across client-side navigations. It renders nothing into your layout.
-
-## The simplest usage: an external script
-
-Give it a `src`. By default it loads once the app is interactive, which is right for most third-party scripts:
-
-```tsx
-// client/layout.tsx
-import { type ReactNode } from 'react';
-
-export default function Layout({ children }: { children?: ReactNode }) {
-  return (
-    <div className="app">
-      <Toil.Script src="https://cdn.example-analytics.com/analytics.js" />
-      {children}
-    </div>
-  );
-}
-```
-
-Putting it in the root layout means it loads once for the whole app and stays loaded as the user navigates. For an external script, the dedup key defaults to its `src`, so you never need an `id`.
-
-## Load strategies
-
-The `strategy` prop decides *when* the script is injected, relative to your app becoming interactive:
-
-| Strategy | When it runs | Use it for |
-| --- | --- | --- |
-| `afterInteractive` (default) | On mount, once the app is running. | Analytics, chat widgets, most third-party scripts. |
-| `lazyOnload` | Deferred until the browser is idle, after the page's `load` event. | Low-priority extras (a feedback button, a social embed) that should not compete with the initial render. |
-| `beforeInteractive` | As early as possible: injected immediately on first mount. | A script other code depends on immediately. |
-
-One honest caveat about `beforeInteractive`: a toiljs frontend is a client-only single-page app, so there is no server-rendered `<script>` to run before hydration. `beforeInteractive` therefore still runs *after* hydration, just as early and eagerly as possible on the first mount. It is a priority hint, not a true "before the page is interactive" guarantee.
-
-```tsx
-<Toil.Script
-  src="https://widget.example.com/embed.js"
-  strategy="lazyOnload"
-/>
-```
-
-## Inline scripts
-
-To run a snippet of code instead of loading a URL, put the code in `children` (as a **string**) and give the script an `id`. An inline script has no `src`, so the `id` is what identifies it for dedup, and it is required:
-
-```tsx
-<Toil.Script id="init-theme" strategy="beforeInteractive">
-  {`document.documentElement.dataset.theme =
-      localStorage.getItem('theme') ?? 'light';`}
-</Toil.Script>
-```
-
-Without an `id` (and no `src`), an inline script has nothing to dedup on, so `Toil.Script` does nothing at all. This is a deliberate no-op, not an error, so remember the `id`.
-
-## Reacting to load
-
-Three optional callbacks let you run code around the script's lifecycle:
-
-```tsx
-<Toil.Script
-  src="https://widget.example.com/embed.js"
-  strategy="lazyOnload"
-  onReady={() => {
-    // The global the script defines is now available.
-    window.MyWidget?.init();
-  }}
-  onError={(err) => {
-    console.warn('widget failed to load', err);
-  }}
-/>
-```
-
-- `onLoad` fires **once**, when an external script finishes loading (or an inline script is inserted).
-- `onReady` fires after load **and on every later mount** once the script is already loaded. So if a route that renders the `Toil.Script` is left and revisited, `onReady` runs again, which is the right place to re-initialise a widget.
-- `onError` fires if an **external** script fails to load. After an error the script's key is cleared, so a later remount retries the load.
-
-## All props
-
-Read them straight from the source (`src/client/components/Script.tsx`):
-
-| Prop | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `src` | `string` | (none) | URL of an external script. Omit it when you provide an inline body via `children`. |
-| `children` | `string` | (none) | Inline script body. Mutually exclusive with `src`. |
-| `strategy` | `'beforeInteractive' \| 'afterInteractive' \| 'lazyOnload'` | `'afterInteractive'` | When to inject the script (see above). |
-| `id` | `string` | `src` for external scripts | Stable identity for dedup. **Required** for inline scripts. |
-| `type` | `string` | (none) | The `type` attribute, e.g. `'module'` or `'application/json'`. |
-| `onLoad` | `() => void` | (none) | Fired once the script has loaded (external) or been inserted (inline). |
-| `onReady` | `() => void` | (none) | Fired after load, and on every later mount once the script is already loaded. |
-| `onError` | `(error: unknown) => void` | (none) | Fired if an external script fails to load. |
-
-External scripts are injected with `async` set, so they never block other work while downloading.
-
-## Gotchas
-
-- **Inline scripts need an `id`.** No `id` and no `src` means nothing to dedup on, so the component quietly does nothing.
-- **Dedup is app-wide and survives navigation.** The same `Toil.Script` rendered on two different routes runs a total of once, keyed by `id` (or `src`). This is the point, but it means you cannot use two copies of the same key to run something twice.
-- **Props are read at injection time, and the script re-injects only if its key or strategy changes.** Changing a handler or an inline body *without* changing the `id` will not re-run the script. If you truly need to re-inject a changed inline script, change its `id`.
-- **`onReady` versus `onLoad`.** Use `onLoad` for one-time setup that must happen exactly once; use `onReady` for setup that should also run each time a component remounts against an already-loaded script.
-- **`beforeInteractive` is not truly before hydration** in a client-only app (see the caveat above). Do not rely on it running before your React tree mounts.
-- **`Toil.Script` renders nothing.** It returns `null`, so you can place it anywhere in your component tree; a layout is the usual home for app-wide scripts.
-
-## Related
-
-- [Rendering and SSR](./rendering.md): how the client-only app and its first paint fit together.
-- [Metadata and SEO](./metadata.md): for `<head>` tags (title, meta, Open Graph), which is a different job from loading scripts.
-- [Frontend overview](./README.md): the `Toil` global and the rest of the client API.

package/docs/frontend/search.md

@@ -1,191 +0,0 @@
-# Page search
-
-toiljs ships a built-in search over your own pages: at build time it indexes every route's metadata (title, description, keywords, Open Graph), and at runtime you query that index to build a search box or a command palette that jumps straight to a page. It is entirely static (no server, no search service), and there is no equivalent in Next.js, so this page explains it from scratch.
-
-## What it is
-
-Every route in your app can export `metadata` (its title, description, and so on, see [Metadata and SEO](./metadata.md)). The toiljs compiler reads that metadata from all your routes at build time and bakes a small **page index** into your bundle: a list of `{ path, title, description, keywords, ... }` for every page. When your app starts, that index is registered in the browser. You can then search it instantly, offline, with zero network calls, and turn a match into a navigation.
-
-This is what powers a "jump to any page" box or a `Cmd+K` command palette without you maintaining a list of pages or standing up a search backend.
-
-```mermaid
-flowchart TD
-  A["Your routes<br/>each with export const metadata"] -->|build: scan + extract| B["Static page index<br/>{ path, dynamic, metadata } per page"]
-  B -->|baked into the bundle| C["App startup: Toil.registerPages(index)"]
-  C --> D["Browser: usePageSearch / searchPages query the index"]
-  D --> E["Ranked results -> goTo() navigates"]
-```
-
-Only **statically-known** metadata is indexed. A route whose `<head>` comes from a dynamic `generateMetadata` (a per-request title) has nothing to index by default; to include it anyway, export `searchHints` (see below).
-
-## The `usePageSearch` hook
-
-`usePageSearch` is the React way in. Give it the current query string, and it hands back ranked results plus a helper to navigate:
-
-```tsx
-const { results, pages, goTo } = Toil.usePageSearch(query);
-```
-
-It returns an object with three fields:
-
-| Field | Type | What it is |
-| --- | --- | --- |
-| `results` | `readonly PageSearchResult[]` | The ranked matches for `query`, best first. Empty when the query is blank. |
-| `pages` | `readonly PageMeta[]` | The full page index, handy for showing an "all pages" listing. |
-| `goTo` | `(target, options?) => void` | Navigates to a result, a page, or a raw path string. A stable reference (safe to pass to a child or destructure). |
-
-Each item in `results` is a `PageSearchResult`:
-
-- `page`: the matched `PageMeta`, which is `{ path, dynamic, metadata }`. `path` is the route URL (`'/about'`), `dynamic` says whether it has `:param` segments, and `metadata` is the indexed title/description/etc.
-- `score`: a relevance number (higher is better; always above zero for a returned result).
-- `matches`: which fields matched, for example `['title', 'keywords']`.
-
-The results are memoised, so they recompute only when the query (or options) change, not on every render.
-
-### A full search box
-
-Here is a complete search page: an input, a ranked result list, and a click that navigates to the chosen page.
-
-```tsx
-// client/routes/search.tsx
-import { useState } from 'react';
-
-export const metadata: Toil.Metadata = {
-  title: 'Search',
-  description: 'Find any page and jump straight to it.',
-  keywords: ['search', 'find', 'pages'],
-};
-
-export default function SearchPage() {
-  const [query, setQuery] = useState('');
-  const { results, pages, goTo } = Toil.usePageSearch(query);
-
-  return (
-    <main>
-      <h1>Search</h1>
-      <input
-        type="search"
-        value={query}
-        onChange={(e) => {
-          setQuery(e.target.value);
-        }}
-        placeholder={`Search ${pages.length} pages...`}
-        aria-label="Search pages"
-        autoFocus
-      />
-
-      {query.trim() !== '' && (
-        <ul>
-          {results.length === 0 && <li>No pages match "{query}".</li>}
-          {results.map((r) => (
-            <li key={r.page.path}>
-              <button
-                type="button"
-                onClick={() => {
-                  goTo(r);
-                }}
-              >
-                <strong>{r.page.metadata.title ?? r.page.path}</strong>{' '}
-                <code>{r.page.path}</code>
-                {r.page.metadata.description !== undefined && (
-                  <p>{r.page.metadata.description}</p>
-                )}
-              </button>
-            </li>
-          ))}
-        </ul>
-      )}
-    </main>
-  );
-}
-```
-
-`goTo` accepts a result (as above), a `PageMeta`, or a plain path string, and takes the same options as `navigate` (see [Routing](./routing.md)). Passing a result is the common case.
-
-### Options
-
-`usePageSearch` takes a second argument to tune the search:
-
-```tsx
-const { results } = Toil.usePageSearch(query, {
-  limit: 8,               // cap the number of results (after ranking)
-  includeDynamic: true,   // include :param routes (see below); default false
-  fields: ['title', 'keywords'], // only match these fields; default all fields
-});
-```
-
-| Option | Type | Default | Effect |
-| --- | --- | --- | --- |
-| `limit` | `number` | no cap | Keep only the top N results after ranking. |
-| `includeDynamic` | `boolean` | `false` | Include dynamic (`:param` / `*catch-all`) routes. Off by default because you cannot navigate to them without filling in the params. |
-| `fields` | array of field names | all fields | Restrict matching to a subset of `'title'`, `'description'`, `'keywords'`, `'path'`, `'openGraph'`. |
-
-## Making dynamic routes searchable with `searchHints`
-
-A dynamic route like `client/routes/blog/[id].tsx` usually produces its `<head>` with a per-post `generateMetadata`, so there is nothing static to index, and the route is missing from search. To surface it anyway, export `searchHints`: a small static object the compiler merges into the index for that route (winning ties against any static `metadata`).
-
-```tsx
-// client/routes/blog/[id].tsx
-
-// The per-post <title> is dynamic, so it cannot be indexed. These static hints
-// put the blog into the search index so it shows up when someone searches "blog".
-export const searchHints: Toil.SearchHints = {
-  title: 'Blog',
-  description: 'Articles and updates.',
-  keywords: ['blog', 'posts', 'articles'],
-};
-```
-
-`SearchHints` has three optional fields: `title`, `description`, and `keywords` (a string or an array of strings).
-
-Two things to keep in mind. First, `searchHints` only affects the index; the route is still dynamic, so it appears in results only when you pass `includeDynamic: true`. Second, you cannot `goTo` a dynamic page directly (it needs concrete params), so `goTo` is a no-op for one unless you hand it a real, filled-in path string. In practice you use `searchHints` to make a *section* discoverable (typing "blog" surfaces the blog), and point the user at a concrete landing URL.
-
-## The lower-level API
-
-The hook is a thin wrapper over a small, framework-agnostic core you can use directly (outside React, in tests, or to build your own UI). All of these are on the `Toil` global:
-
-- `Toil.searchPages(query, options?)`: the pure ranking function behind the hook. Returns `PageSearchResult[]`. Same options as the hook.
-- `Toil.getPages()`: the full registered index (`readonly PageMeta[]`), including dynamic routes. Empty before registration.
-- `Toil.pagePath(target)`: normalises a result, a page, or a raw string down to its path string.
-- `Toil.registerPages(pages)`: replaces the live index. toiljs calls this for you at startup with the compiler-built index, so you rarely call it yourself. It exists for tests and advanced setups that build a custom index.
-
-```tsx
-import { searchPages } from 'toiljs/client';
-
-// Outside a component: the top 5 title/keyword matches for "billing".
-const hits = searchPages('billing', { limit: 5, fields: ['title', 'keywords'] });
-```
-
-## How ranking works
-
-The matcher is simple and predictable:
-
-- The query is lower-cased and split on whitespace into terms. **Every** term must match somewhere (AND semantics), or the page is dropped. A blank query returns nothing.
-- Matching is case-insensitive and substring-based, with bonuses: an exact field match ranks highest, then a match at the start of the field, then a match at the start of a word inside the field, then a plain mid-word substring.
-- Each field carries a weight, so a hit in the title counts for much more than a hit in the description:
-
-| Field | Weight |
-| --- | --- |
-| `title` | 10 |
-| `path` | 6 |
-| `keywords` | 5 |
-| `description` | 3 |
-| `openGraph` | 2 |
-
-- The `path` field is made word-searchable: `/get-started` matches "get" or "started".
-- Results are sorted by score (highest first), ties broken alphabetically by path for a stable order, then cut to `limit` if you set one.
-
-## Gotchas
-
-- **Only static metadata is indexed.** A route whose title comes from `generateMetadata` is invisible to search until you add `searchHints`.
-- **Dynamic routes are excluded by default.** They need `includeDynamic: true` to appear, and even then `goTo` cannot navigate to one without concrete params.
-- **The index is built, not live.** It reflects the metadata at build time. Add a route or change a title and you must rebuild for search to see it.
-- **A blank query returns no results**, not every page. If you want an "all pages" listing for an empty box, render `pages` yourself.
-- **The type names** `PageSearchResult`, `PageSearchOptions`, and `SearchField` are importable from `'toiljs/client'` if you need to annotate them; `PageMeta` and `SearchHints` are also available as `Toil.PageMeta` / `Toil.SearchHints`.
-
-## Related
-
-- [Metadata and SEO](./metadata.md): the `metadata` the search index is built from.
-- [Routing](./routing.md): route paths, dynamic segments, and `navigate` (what `goTo` calls).
-- [Rendering and SSR](./rendering.md): where `searchHints` fits alongside `generateStaticParams` for dynamic routes.
-- [Frontend overview](./README.md): the `Toil` global and the rest of the client API.

package/docs/frontend/styling.md

@@ -1,147 +0,0 @@
-# Styling
-
-toiljs does not force a styling system on you. It builds with Vite, so you style your app the way you would any Vite + React project: plain CSS, CSS Modules, a preprocessor like Sass, or Tailwind. This page shows the practical options.
-
-## The one import that matters
-
-Your app pulls in global styles from the entry file, `client/toil.tsx`:
-
-```tsx
-// client/toil.tsx
-import { routes, layout, notFound, globalError, slots } from 'toiljs/routes';
-import './styles/main.css';   // <- your global stylesheet
-
-Toil.mount(routes, layout, notFound, globalError, slots);
-```
-
-That one import is where your global CSS (resets, CSS variables, base element styles) lives. A typical `client/styles/main.css` sets up theme variables and base styles:
-
-```css
-/* client/styles/main.css */
-:root {
-  --accent: #2563ff;
-  --bg: #080d11;
-  --text: #f5f6fa;
-}
-
-*, *::before, *::after {
-  box-sizing: border-box;
-}
-
-body {
-  margin: 0;
-  background: var(--bg);
-  color: var(--text);
-  font-family: system-ui, -apple-system, sans-serif;
-  line-height: 1.6;
-}
-```
-
-## Importing CSS anywhere
-
-You are not limited to the one global sheet. Any component can import its own CSS, and Vite bundles it in:
-
-```tsx
-// client/components/Card.tsx
-import './card.css';
-
-export default function Card() {
-  return <div className="card">...</div>;
-}
-```
-
-The class names in a plain `.css` file are global (they apply everywhere), so name them carefully to avoid clashes, or reach for CSS Modules.
-
-## CSS Modules (scoped class names)
-
-If you name a file `*.module.css`, Vite treats it as a **CSS Module**: the class names are locally scoped to the component that imports them, so two components can both use `.title` without colliding. You import the generated names as an object:
-
-```tsx
-// client/components/Card.tsx
-import styles from './card.module.css';
-
-export default function Card() {
-  return <div className={styles.card}>...</div>;
-}
-```
-
-```css
-/* client/components/card.module.css */
-.card {
-  padding: 1rem;
-  border: 1px solid var(--border);
-}
-```
-
-This is the simplest way to get component-scoped styles with no extra tooling.
-
-## Preprocessors: Sass, Less, Stylus
-
-When you create a project (`toiljs create`) you can pick a CSS preprocessor, or add one later to an existing project with the `configure` command:
-
-```sh
-toiljs configure                 # interactive: choose preprocessor + Tailwind
-toiljs configure --style sass    # switch the preprocessor to Sass
-```
-
-`configure` installs the right packages and rewrites your style imports for you. After that, `.scss` / `.sass` / `.less` / `.styl` files import exactly like `.css` files, and Vite compiles them.
-
-## Tailwind
-
-To use Tailwind (a utility-class CSS framework), turn it on at create time or add it later:
-
-```sh
-toiljs configure --tailwind
-```
-
-Tailwind lives in its own stylesheet, `client/styles/tailwind.css`, which is just:
-
-```css
-@import "tailwindcss";
-```
-
-`configure` wires that import in for you. From then on you use Tailwind's utility classes directly in your JSX:
-
-```tsx
-export default function Cta() {
-  return (
-    <button className="rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white">
-      Get started
-    </button>
-  );
-}
-```
-
-## Inline styles and the `style` prop
-
-Standard React inline styles work as always, and are handy for one-off, dynamic values:
-
-```tsx
-<div style={{ padding: 24, background: 'var(--surface)' }}>...</div>
-```
-
-Prefer classes for anything reused; keep inline styles for the truly per-instance case (a computed width, a dynamic color).
-
-## How types work for style and asset imports
-
-toiljs generates a `toil-env.d.ts` in your project that declares the import types, so TypeScript is happy importing stylesheets and images. It covers `.css`, `.scss`, `.sass`, `.less`, `.styl` (and friends), plus image formats (`.svg`, `.png`, `.jpg`, `.webp`, and so on), which import as a URL string:
-
-```tsx
-import logoUrl from './logo.svg';   // logoUrl is a string (a hashed URL)
-
-<img src={logoUrl} alt="Logo" />
-```
-
-For images specifically, prefer the `Toil.Image` component and its `?toil` import, which also handle layout shift and blur placeholders (see [Images](./images.md)).
-
-## Gotchas
-
-- **Global CSS is global.** A plain `.css` import puts its class names in one shared namespace. If two files both define `.button`, the last one loaded wins. Use `*.module.css` (CSS Modules) or unique prefixes to scope styles.
-- **Do not hand-edit `toil-env.d.ts`.** It is generated. If a new file type is not recognized, re-run the build so it regenerates, rather than editing it.
-- **Preprocessor packages are managed by `configure`.** Add or switch preprocessors through `toiljs configure` so the packages and imports stay in sync; do not install them by hand.
-
-## Related
-
-- [Images](./images.md): the `Toil.Image` component and image imports.
-- [The CLI](../cli/README.md): `toiljs configure` and every flag.
-- [Frontend overview](./README.md): where styles fit in the `client/` folder.