toiljs 0.0.11 → 0.0.14

package/examples/basic/client/routes/features/actions.tsx

@@ -1,67 +1,67 @@
-// Mutations: a `loader` reads, an action writes, then revalidation refetches the loader so the UI
-// reflects the new state with no manual refetch. Here a module-level counter stands in for a server.
-let serverCount = 0;
-async function wait(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-export const metadata: Toil.Metadata = {
-    title: 'Actions and forms',
-    description: 'useAction and <Form> mutations with pending state and revalidation.',
-};
-
-export const loader = async () => {
-    await wait(150);
-    return { count: serverCount };
-};
-
-export default function ActionsDemo() {
-    const { count } = Toil.useLoaderData(loader);
-
-    // useAction: run a mutation, track pending/error, then revalidate this route's loader on success.
-    const increment = Toil.useAction(
-        async (by: number) => {
-            await wait(400);
-            serverCount += by;
-            return serverCount;
-        },
-        { revalidate: true },
-    );
-
-    return (
-        <main>
-            <h1>Actions and forms</h1>
-            <p>
-                Server count (from the loader): <strong>{count}</strong>
-            </p>
-
-            <p>
-                <button type="button" disabled={increment.pending} onClick={() => void increment.run(1)}>
-                    {increment.pending ? 'Saving' : 'Increment via useAction'}
-                </button>
-                {increment.error ? <span style={{ color: 'crimson' }}> failed</span> : null}
-            </p>
-
-            {/* The declarative form: submits to an action, revalidates on success, exposes pending. */}
-            <Toil.Form
-                action={async (form) => {
-                    await wait(400);
-                    serverCount += Number(form.get('by') || 0);
-                }}
-                revalidate>
-                {({ pending }) => (
-                    <>
-                        <input name="by" type="number" defaultValue={5} disabled={pending} />
-                        <button type="submit" disabled={pending}>
-                            {pending ? 'Saving' : 'Add via <Form>'}
-                        </button>
-                    </>
-                )}
-            </Toil.Form>
-
-            <p>
-                <Toil.Link href="/features">Back to features</Toil.Link>
-            </p>
-        </main>
-    );
-}
+// Mutations: a `loader` reads, an action writes, then revalidation refetches the loader so the UI
+// reflects the new state with no manual refetch. Here a module-level counter stands in for a server.
+let serverCount = 0;
+async function wait(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export const metadata: Toil.Metadata = {
+    title: 'Actions and forms',
+    description: 'useAction and <Form> mutations with pending state and revalidation.'
+};
+
+export const loader = async () => {
+    await wait(150);
+    return { count: serverCount };
+};
+
+export default function ActionsDemo() {
+    const { count } = Toil.useLoaderData(loader);
+
+    // useAction: run a mutation, track pending/error, then revalidate this route's loader on success.
+    const increment = Toil.useAction(
+        async (by: number) => {
+            await wait(400);
+            serverCount += by;
+            return serverCount;
+        },
+        { revalidate: true }
+    );
+
+    return (
+        <main>
+            <h1>Actions and forms</h1>
+            <p>
+                Server count (from the loader): <strong>{count}</strong>
+            </p>
+
+            <p>
+                <button type="button" disabled={increment.pending} onClick={() => void increment.run(1)}>
+                    {increment.pending ? 'Saving' : 'Increment via useAction'}
+                </button>
+                {increment.error ? <span style={{ color: 'crimson' }}> failed</span> : null}
+            </p>
+
+            {/* The declarative form: submits to an action, revalidates on success, exposes pending. */}
+            <Toil.Form
+                action={async (form) => {
+                    await wait(400);
+                    serverCount += Number(form.get('by') || 0);
+                }}
+                revalidate>
+                {({ pending }) => (
+                    <>
+                        <input name="by" type="number" defaultValue={5} disabled={pending} />
+                        <button type="submit" disabled={pending}>
+                            {pending ? 'Saving' : 'Add via <Form>'}
+                        </button>
+                    </>
+                )}
+            </Toil.Form>
+
+            <p>
+                <Toil.Link href="/features">Back to features</Toil.Link>
+            </p>
+        </main>
+    );
+}

package/examples/basic/client/routes/features/error/index.tsx

@@ -1,27 +1,27 @@
-import { useState } from 'react';
-
-export const metadata: Toil.Metadata = { title: 'Error boundary' };
-
-// When a route throws during render, the nearest `error.tsx` catches it and renders instead of a
-// blank screen. Click the button to flip into a throwing render and watch error.tsx take over.
-export default function ErrorDemo() {
-    const [boom, setBoom] = useState(false);
-    if (boom) throw new Error('Kaboom from features/error, caught by error.tsx');
-    return (
-        <main>
-            <h1>Error boundary</h1>
-            <p>
-                A thrown render is caught by <code>error.tsx</code> in this folder, scoped to this
-                segment so the rest of the app keeps working.
-            </p>
-            <p>
-                <button type="button" onClick={() => setBoom(true)}>
-                    Throw an error
-                </button>
-            </p>
-            <p>
-                <Toil.Link href="/features">Back to features</Toil.Link>
-            </p>
-        </main>
-    );
-}
+import { useState } from 'react';
+
+export const metadata: Toil.Metadata = { title: 'Error boundary' };
+
+// When a route throws during render, the nearest `error.tsx` catches it and renders instead of a
+// blank screen. Click the button to flip into a throwing render and watch error.tsx take over.
+export default function ErrorDemo() {
+    const [boom, setBoom] = useState(false);
+    if (boom) throw new Error('Kaboom from features/error, caught by error.tsx');
+    return (
+        <main>
+            <h1>Error boundary</h1>
+            <p>
+                A thrown render is caught by <code>error.tsx</code> in this folder, scoped to this segment so the rest
+                of the app keeps working.
+            </p>
+            <p>
+                <button type="button" onClick={() => setBoom(true)}>
+                    Throw an error
+                </button>
+            </p>
+            <p>
+                <Toil.Link href="/features">Back to features</Toil.Link>
+            </p>
+        </main>
+    );
+}

package/examples/basic/client/routes/features/head.tsx

@@ -1,38 +1,38 @@
-import { useState } from 'react';
-
-// The imperative head API, for when the title or tags depend on component state rather than a static
-// export. `useTitle` / `useHead` apply for the component's lifetime and revert on unmount; `<Toil.Head>`
-// is the declarative form. They compose with (and can override) the route `metadata`.
-export default function HeadDemo() {
-    const [count, setCount] = useState(0);
-
-    // Live title: the tab updates every render as `count` changes.
-    Toil.useTitle(`Clicked ${count} times`);
-
-    // Add a meta tag and a canonical link for this page only.
-    Toil.useHead({
-        meta: [{ name: 'description', content: `Imperative head demo, clicked ${count} times.` }],
-        link: [{ rel: 'canonical', href: 'https://toil.example/features/head' }],
-    });
-
-    return (
-        <main>
-            <h1>Imperative head</h1>
-            <p>
-                The tab title is driven by component state via <code>Toil.useTitle</code>. Click the
-                button and watch it change, then leave the page and the title reverts.
-            </p>
-            <p>
-                <button type="button" onClick={() => setCount((c) => c + 1)}>
-                    Clicked {count} times
-                </button>
-            </p>
-            {/* Declarative equivalent, the same merge rules apply. */}
-            <Toil.Head meta={[{ property: 'og:title', content: `Clicked ${count} times` }]} />
-            <p>
-                <Toil.Link href="/features/seo">Compare with route metadata</Toil.Link>{' '}
-                <Toil.Link href="/features">Back to features</Toil.Link>
-            </p>
-        </main>
-    );
-}
+import { useState } from 'react';
+
+// The imperative head API, for when the title or tags depend on component state rather than a static
+// export. `useTitle` / `useHead` apply for the component's lifetime and revert on unmount; `<Toil.Head>`
+// is the declarative form. They compose with (and can override) the route `metadata`.
+export default function HeadDemo() {
+    const [count, setCount] = useState(0);
+
+    // Live title: the tab updates every render as `count` changes.
+    Toil.useTitle(`Clicked ${count} times`);
+
+    // Add a meta tag and a canonical link for this page only.
+    Toil.useHead({
+        meta: [{ name: 'description', content: `Imperative head demo, clicked ${count} times.` }],
+        link: [{ rel: 'canonical', href: 'https://toil.example/features/head' }]
+    });
+
+    return (
+        <main>
+            <h1>Imperative head</h1>
+            <p>
+                The tab title is driven by component state via <code>Toil.useTitle</code>. Click the button and watch it
+                change, then leave the page and the title reverts.
+            </p>
+            <p>
+                <button type="button" onClick={() => setCount((c) => c + 1)}>
+                    Clicked {count} times
+                </button>
+            </p>
+            {/* Declarative equivalent, the same merge rules apply. */}
+            <Toil.Head meta={[{ property: 'og:title', content: `Clicked ${count} times` }]} />
+            <p>
+                <Toil.Link href="/features/seo">Compare with route metadata</Toil.Link>{' '}
+                <Toil.Link href="/features">Back to features</Toil.Link>
+            </p>
+        </main>
+    );
+}

package/examples/basic/client/routes/features/index.tsx

@@ -1,75 +1,83 @@
-// The feature hub: one place that links to a live demo of every ToilJS capability. Its own tab
-// title comes from the `metadata` export below (rendered as "Features | ToilJS" via the layout
-// template) and is baked into build/client/features/index.html at build time.
-export const metadata: Toil.Metadata = {
-    title: 'Features',
-    description: 'Live demos of every ToilJS feature: routing, data, head/SEO, components, realtime, and binary IO.',
-    openGraph: { title: 'Every ToilJS feature, demoed', type: 'website' },
-};
-
-const groups: { heading: string; items: { href: Toil.Href; label: string; note: string }[] }[] = [
-    {
-        heading: 'Routing',
-        items: [
-            { href: '/blog/42', label: 'Dynamic route', note: 'blog/[id].tsx, /blog/42' },
-            { href: '/docs/getting/started', label: 'Catch-all', note: 'docs/[...slug].tsx' },
-            { href: '/files', label: 'Optional catch-all', note: 'files/[[...slug]].tsx, matches /files and /files/a/b' },
-            { href: '/privacy', label: 'Route group', note: '(legal)/privacy.tsx, no URL segment' },
-            { href: '/gallery', label: 'Parallel + intercepting', note: '@modal/(.)photo/[id], a real modal route' },
-            { href: '/features/template', label: 'Templates', note: 'template.tsx remounts on every navigation' },
-            { href: '/features/error', label: 'Error boundary', note: 'error.tsx catches a thrown route' },
-        ],
-    },
-    {
-        heading: 'Data',
-        items: [
-            { href: '/loader-demo', label: 'Loader + revalidate', note: 'data before render, cached, refetchable' },
-            { href: '/features/actions', label: 'Actions + Form', note: 'useAction / <Form>, pending state, revalidate' },
-        ],
-    },
-    {
-        heading: 'Head and SEO',
-        items: [
-            { href: '/features/seo', label: 'Route metadata', note: 'export const metadata, title override' },
-            { href: '/features/head', label: 'Imperative head', note: 'useTitle / useHead / <Head>' },
-        ],
-    },
-    {
-        heading: 'Components and runtime',
-        items: [
-            { href: '/features/script', label: 'Script', note: 'Toil.Script with a load strategy' },
-            { href: '/features/realtime', label: 'WebSocket channel', note: 'Toil.useChannel against /_toil' },
-            { href: '/io', label: 'Binary IO', note: 'BinaryWriter / BinaryReader / FastSet, no import' },
-        ],
-    },
-];
-
-export default function Features() {
-    return (
-        <main>
-            <h1>Every feature, live</h1>
-            <p>
-                Each link is a working demo served from <code>client/routes/</code>. Watch the tab
-                title change as you navigate, that is the per-route <code>metadata</code> at work.
-            </p>
-            {groups.map((g) => (
-                <section key={g.heading} style={{ marginTop: 24 }}>
-                    <h2 style={{ fontSize: '1rem', opacity: 0.7 }}>{g.heading}</h2>
-                    <ul style={{ display: 'grid', gap: 8, listStyle: 'none', padding: 0 }}>
-                        {g.items.map((it) => (
-                            <li key={it.href}>
-                                <Toil.Link href={it.href} style={{ fontWeight: 600 }}>
-                                    {it.label}
-                                </Toil.Link>
-                                <span style={{ opacity: 0.6 }}> , {it.note}</span>
-                            </li>
-                        ))}
-                    </ul>
-                </section>
-            ))}
-            <p style={{ marginTop: 24 }}>
-                <Toil.Link href="/">Back home</Toil.Link>
-            </p>
-        </main>
-    );
-}
+// The feature hub: one place that links to a live demo of every ToilJS capability. Its own tab
+// title comes from the `metadata` export below (rendered as "Features | ToilJS" via the layout
+// template) and is baked into build/client/features/index.html at build time.
+export const metadata: Toil.Metadata = {
+    title: 'Features',
+    description: 'Live demos of every ToilJS feature: routing, data, head/SEO, components, realtime, and binary IO.',
+    openGraph: { title: 'Every ToilJS feature, demoed', type: 'website' }
+};
+
+const groups: { heading: string; items: { href: Toil.Href; label: string; note: string }[] }[] = [
+    {
+        heading: 'Routing',
+        items: [
+            { href: '/blog/42', label: 'Dynamic route', note: 'blog/[id].tsx, /blog/42' },
+            { href: '/docs/getting/started', label: 'Catch-all', note: 'docs/[...slug].tsx' },
+            {
+                href: '/files',
+                label: 'Optional catch-all',
+                note: 'files/[[...slug]].tsx, matches /files and /files/a/b'
+            },
+            { href: '/privacy', label: 'Route group', note: '(legal)/privacy.tsx, no URL segment' },
+            { href: '/gallery', label: 'Parallel + intercepting', note: '@modal/(.)photo/[id], a real modal route' },
+            { href: '/features/template', label: 'Templates', note: 'template.tsx remounts on every navigation' },
+            { href: '/features/error', label: 'Error boundary', note: 'error.tsx catches a thrown route' }
+        ]
+    },
+    {
+        heading: 'Data',
+        items: [
+            { href: '/loader-demo', label: 'Loader + revalidate', note: 'data before render, cached, refetchable' },
+            {
+                href: '/features/actions',
+                label: 'Actions + Form',
+                note: 'useAction / <Form>, pending state, revalidate'
+            }
+        ]
+    },
+    {
+        heading: 'Head and SEO',
+        items: [
+            { href: '/features/seo', label: 'Route metadata', note: 'export const metadata, title override' },
+            { href: '/features/head', label: 'Imperative head', note: 'useTitle / useHead / <Head>' }
+        ]
+    },
+    {
+        heading: 'Components and runtime',
+        items: [
+            { href: '/features/script', label: 'Script', note: 'Toil.Script with a load strategy' },
+            { href: '/features/realtime', label: 'WebSocket channel', note: 'Toil.useChannel against /_toil' },
+            { href: '/io', label: 'Binary IO', note: 'BinaryWriter / BinaryReader / FastSet, no import' }
+        ]
+    }
+];
+
+export default function Features() {
+    return (
+        <main>
+            <h1>Every feature, live</h1>
+            <p>
+                Each link is a working demo served from <code>client/routes/</code>. Watch the tab title change as you
+                navigate, that is the per-route <code>metadata</code> at work.
+            </p>
+            {groups.map((g) => (
+                <section key={g.heading} style={{ marginTop: 24 }}>
+                    <h2 style={{ fontSize: '1rem', opacity: 0.7 }}>{g.heading}</h2>
+                    <ul style={{ display: 'grid', gap: 8, listStyle: 'none', padding: 0 }}>
+                        {g.items.map((it) => (
+                            <li key={it.href}>
+                                <Toil.Link href={it.href} style={{ fontWeight: 600 }}>
+                                    {it.label}
+                                </Toil.Link>
+                                <span style={{ opacity: 0.6 }}> , {it.note}</span>
+                            </li>
+                        ))}
+                    </ul>
+                </section>
+            ))}
+            <p style={{ marginTop: 24 }}>
+                <Toil.Link href="/">Back home</Toil.Link>
+            </p>
+        </main>
+    );
+}

package/examples/basic/client/routes/features/realtime.tsx

@@ -1,32 +1,34 @@
-export const metadata: Toil.Metadata = {
-    title: 'Realtime',
-    description: 'A typed WebSocket channel to the server with connect, reconnect, and message decoding.',
-};
-
-// Toil.useChannel opens a WebSocket to the server (default path /_toil), tracks `connected`, collects
-// `messages`, and exposes `send`. It reconnects automatically. With no server socket running the demo
-// simply shows "disconnected", the API is the same once the server handles the channel.
-export default function RealtimeDemo() {
-    const chat = Toil.useChannel({ path: '/_toil' });
-    return (
-        <main>
-            <h1>Realtime</h1>
-            <p>
-                Connection: <strong>{chat.connected ? 'connected' : 'disconnected'}</strong>, messages
-                received: <strong>{chat.messages.length}</strong>.
-            </p>
-            <p>
-                <button type="button" onClick={() => chat.send('ping')}>
-                    Send ping
-                </button>
-            </p>
-            <p style={{ opacity: 0.6 }}>
-                <code>const chat = Toil.useChannel({'{'} path: '/_toil' {'}'})</code>, connect, reconnect,
-                and decoding are handled for you.
-            </p>
-            <p>
-                <Toil.Link href="/features">Back to features</Toil.Link>
-            </p>
-        </main>
-    );
-}
+export const metadata: Toil.Metadata = {
+    title: 'Realtime',
+    description: 'A typed WebSocket channel to the server with connect, reconnect, and message decoding.'
+};
+
+// Toil.useChannel opens a WebSocket to the server (default path /_toil), tracks `connected`, collects
+// `messages`, and exposes `send`. It reconnects automatically. With no server socket running the demo
+// simply shows "disconnected", the API is the same once the server handles the channel.
+export default function RealtimeDemo() {
+    const chat = Toil.useChannel({ path: '/_toil' });
+    return (
+        <main>
+            <h1>Realtime</h1>
+            <p>
+                Connection: <strong>{chat.connected ? 'connected' : 'disconnected'}</strong>, messages received:{' '}
+                <strong>{chat.messages.length}</strong>.
+            </p>
+            <p>
+                <button type="button" onClick={() => chat.send('ping')}>
+                    Send ping
+                </button>
+            </p>
+            <p style={{ opacity: 0.6 }}>
+                <code>
+                    const chat = Toil.useChannel({'{'} path: '/_toil' {'}'})
+                </code>
+                , connect, reconnect, and decoding are handled for you.
+            </p>
+            <p>
+                <Toil.Link href="/features">Back to features</Toil.Link>
+            </p>
+        </main>
+    );
+}

package/examples/basic/client/routes/features/script.tsx

@@ -1,31 +1,31 @@
-import { useState } from 'react';
-
-export const metadata: Toil.Metadata = {
-    title: 'Script',
-    description: 'Load third-party scripts with a strategy, deduplicated so they never run twice.',
-};
-
-// Toil.Script injects an external or inline script once (deduped by src/id), with a load strategy.
-// `onReady` fires when it has loaded. Here we load a tiny public script and report when it is ready.
-export default function ScriptDemo() {
-    const [ready, setReady] = useState(false);
-    return (
-        <main>
-            <h1>Script</h1>
-            <p>
-                <code>Toil.Script</code> loads external scripts with a <code>strategy</code>{' '}
-                (<code>afterInteractive</code>, <code>lazyOnload</code>, <code>beforeInteractive</code>)
-                and dedupes them, so the same script never runs twice across navigations.
-            </p>
-            <Toil.Script
-                src="https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js"
-                strategy="afterInteractive"
-                onReady={() => setReady(true)}
-            />
-            <p>Status: {ready ? 'script ready' : 'loading'}</p>
-            <p>
-                <Toil.Link href="/features">Back to features</Toil.Link>
-            </p>
-        </main>
-    );
-}
+import { useState } from 'react';
+
+export const metadata: Toil.Metadata = {
+    title: 'Script',
+    description: 'Load third-party scripts with a strategy, deduplicated so they never run twice.'
+};
+
+// Toil.Script injects an external or inline script once (deduped by src/id), with a load strategy.
+// `onReady` fires when it has loaded. Here we load a tiny public script and report when it is ready.
+export default function ScriptDemo() {
+    const [ready, setReady] = useState(false);
+    return (
+        <main>
+            <h1>Script</h1>
+            <p>
+                <code>Toil.Script</code> loads external scripts with a <code>strategy</code> (
+                <code>afterInteractive</code>, <code>lazyOnload</code>, <code>beforeInteractive</code>) and dedupes
+                them, so the same script never runs twice across navigations.
+            </p>
+            <Toil.Script
+                src="https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/dist/confetti.browser.min.js"
+                strategy="afterInteractive"
+                onReady={() => setReady(true)}
+            />
+            <p>Status: {ready ? 'script ready' : 'loading'}</p>
+            <p>
+                <Toil.Link href="/features">Back to features</Toil.Link>
+            </p>
+        </main>
+    );
+}