@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.190

package/docs/learn/04-loading-states.mdx

@@ -0,0 +1,67 @@
+---
+title: 'You Might Not Need A loading.tsx'
+description: 'When timber commits the HTTP status code and why it matters.'
+slug: 'loading-states'
+notAI: true
+---
+
+# You Might Not Need A `loading.tsx`
+
+Most React frameworks push you towards building page-level skeletons or loading states. Though it's entirely trivial to build out that experience with timber, we nudge you away from that for several reasons.
+
+This is not referring to loading states on things like mutations (like submitting a form) or other actions. This is referring to initial (server) or secondary (client) page loading.
+
+This is how we as frontend engineers make browsing the web a less anxiety-inducing experience.
+
+### Loading States Are an Extra Class of UI to Maintain
+
+You have to design loading states. Decide between spinners and skeletons, and then mimic your UI in the skeleton.
+
+### Loading States Cause Content Layout Shift
+
+Loading states are fixed and content is most often dynamic both in size (think text length) and count (think number of rows). So even if you work incredibly hard to avoid major CLS, you'll invariably end up with CLS somewhere.
+
+### Loading States Are a Flash of UI
+
+Loading states are inherently temporary, so this adds flashes of content. This causes anxiety as the page spasms before finally reaching an undetermined final state. The user is left in a daze wondering if the page is finally ready.
+
+Every possible "finite state" of UI is another that you and the user have to keep in context. You'll be _surprised_ how much simpler a website feels when a page has one major representation, vs several.
+
+### Loading States Hide Prior Context
+
+Go to an old PHP site and click a URL. The _browser_ shows a loading state, but the prior page remains visible. The new page only becomes visible once it is ready. There's little advantage to hiding the past context while the user waits for the new context to load.
+
+### timber Includes a Global Route-Based Loading State
+
+On every route change, timber triggers a global page-level toploader loading state. If you want to add a secondary loading state that dims the prior content, you can easily do so.
+
+### Loading States Break JavaScript Disabled Requests
+
+`curl` a page with a `loading.tsx` and you'll get back a shell, not the content. Though people downsell the cost, it genuinely does hinder both SEO and agentic requests.
+
+Leaning on the web as intended is always better than assuming _all_ consumers have JavaScript enabled. Plus, sticking JavaScript in between your _hot_ rendering path is _inherently_ slower. It's just not necessary when you adopt a comprehensive web architecture like React Server Components.
+
+### Loading States Break Status Codes
+
+Loading states flush before the content is even fetched. This feels _faster_, but you are flushing before you know if the user is authenticated, the data exists, or any other class of issue. By flushing immediately, you are forced to send a 200 and lean on JavaScript-injected meta tags to signify errors.
+
+This breaks the contract of the web for any consumer that isn't a human. Use real status codes, you will gain downstream benefits from doing so.
+
+### Most Loading States Paper Over a Bad Data Architecture
+
+People often use loading states because their database is poorly optimized, or 50ms away from their rendering server, or otherwise. With a well designed data infrastructure, you can often fetch your data plenty fast to render your entire page in < 100ms.
+
+And when you can't, you can stream and flush those rare pages trivially.
+
+### Loading States Still Have Value, but More-So as Opt-In Secondary or Tertiary Content
+
+To add a loading state as a small sub-section of a page is trivial – just wrap your component in `<Suspense>` and you can defer slower, lower priority content.
+
+If you decide you want a full page level loading state, you can wrap your layout or page in `<Suspense>` on a case by case basis. No `loading.tsx` needed.
+
+
+--------
+
+A `loading.tsx` forces your flush point up ever so slightly, but you give up all the things above. Instead, timber asks you to place `<Suspense>` boundaries yourself – thereby _explicitly_ opting into the flush point.
+
+Now you get a calm, performant website that doesn't have immense content-layout-shift, doesn't hide prior content during loading, and can return proper status codes. The `loading.tsx` seems innocent enough, but its cost both cognitively and architecturally is high.

package/docs/learn/04b-the-flush-point.mdx

@@ -0,0 +1,115 @@
+---
+title: 'The Flush Point'
+description: 'When timber commits the HTTP status code and why it matters.'
+slug: 'the-flush-point'
+# notAI: true
+---
+
+# The Flush Point
+
+The flush point is when the framework sends the first byte of HTML to the browser and commits the HTTP status code. In a traditional PHP website, this happens all at once.
+
+But modern web frameworks, and notably react server components, have embraced a streaming architecture. Allowing you to send content _after_ the flush point.
+
+While this is ultimately incredibly powerful, it brings forth confusion because contextually, code can have different side effects depending on _when_ you call it.
+
+On a next.js app, if I call `notFound()` inside of a `page.tsx` that has a sibling `loading.tsx` – my status code will return `200`. By obfuscating the flush point, we've actually just made developer clarity murky.
+
+So timber works differently. At no point does timber flush early, unless _you_ (the developer), choose to place a `<Suspense>` boundary. Often this will end up being below your `page.tsx` level, so you'll still have access to controlling and sending proper status codes.
+
+------
+
+AI below..
+
+## The Problem
+
+Most streaming frameworks send a `200 OK` immediately and figure out the real outcome later:
+
+```
+Request → 200 OK → ... render ... → oh, it's a 404
+```
+
+By the time the server discovers the page doesn't exist, the status code is already sent. The client sees `200`. Search engines see `200`. CDNs cache it as `200`.
+
+This breaks search engines (deleted pages never deindex), CDNs (404s get cached as successes), monitoring (zero errors while users see broken pages), and `curl`/scripts (`curl -f` won't detect the failure).
+
+## timber's Solution
+
+timber holds the response until it knows the real outcome:
+
+```
+Request arrives
+  → Route matched
+  → proxy.ts runs
+  → middleware.ts runs
+  → access.ts runs
+  → React shell renders (onShellReady)
+  → ✓ Status code committed ← flush point
+  → Shell HTML sent to browser
+  → Suspense boundaries stream in
+```
+
+The status code commits when **all three** conditions are met:
+
+1. Middleware completed without returning a response
+2. All access checks passed (or denied with a real status code)
+3. React's `onShellReady` fired — the synchronous shell rendered without error
+
+A missing page returns a real `404`. A failed auth check returns a real `403`. A redirect returns a real `302`. The HTTP layer tells the truth.
+
+## Before and After the Flush
+
+**Before the flush** (blocking):
+
+- `proxy.ts` — global request processing
+- `middleware.ts` — route-level request processing
+- `access.ts` — authorization gates
+- Synchronous component rendering (the shell)
+
+**After the flush** (streaming):
+
+- `<Suspense>` boundaries resolve and stream in
+- Slow data loads complete
+- The page progressively fills in
+
+``` leading="none"
+         ┌─────── flush point
+         │
+         ▼
+├────────┤──────────────────────────┤
+ blocking    streaming
+ (shell)     (suspense boundaries)
+```
+
+Everything before the flush determines the status code. Everything after streams progressively. You control the boundary by choosing what goes inside `<Suspense>` and what doesn't.
+
+## Pages Work Without JavaScript
+
+Because timber holds the flush until the shell is complete, the browser receives a fully-formed HTML document. Content is visible, links work as standard `<a>` tags, and forms submit as standard POSTs. JavaScript adds client-side navigation, interactive components, and streaming updates — but the page works without it.
+
+This isn't a special mode. It's how timber works by default.
+
+## Early Hints
+
+timber doesn't make you wait for assets while the shell renders. At route-match time — before middleware runs — timber sends `103 Early Hints` with CSS, JS, and font URLs. The browser starts downloading assets while the server is still working:
+
+```
+103 Early Hints
+Link: </styles/main.css>; rel=preload; as=style
+Link: </chunks/page-abc.js>; rel=modulepreload
+
+... middleware runs, shell renders ...
+
+200 OK
+<html>...
+```
+
+You get the correctness of a held flush with the performance of early resource loading.
+
+## How to Think About It
+
+Primary content — the data that defines whether a page exists, who can see it, and what it contains — should load before the flush. Put it in your components directly.
+
+Secondary content — recommendations, activity feeds, analytics widgets — can load after the flush. Wrap it in `<Suspense>`.
+
+The flush point is the dividing line between "what the page _is_" and "what the page _also shows_."

package/docs/learn/05-typed-params.mdx

@@ -0,0 +1,275 @@
+---
+title: 'Typed Params'
+description: 'Codecs, segment params, search params, and cookies — typed values that cross boundaries.'
+slug: 'typed-params'
+---
+
+# Typed Params
+
+Values that cross boundaries — URL path segments, query strings, cookies — arrive as strings. timber provides a unified system for parsing them into typed values using **codecs**.
+
+## Codecs
+
+A codec converts between string values and typed values:
+
+```ts
+interface Codec<T> {
+  parse(value: string | string[] | undefined): T;
+  serialize(value: T): string | string[] | null; // string[] for repeated keys
+}
+```
+
+Any object with `parse` and `serialize` is a valid codec. You can use Zod schemas, [nuqs](https://nuqs.47ng.com/) parsers, or write your own. Standard Schema objects (Zod, Valibot, ArkType) are auto-detected — no wrapper needed.
+
+## Segment Params
+
+Dynamic segments (`[id]`, `[slug]`) capture raw strings from the URL. Define codecs in a global `app/schema.ts` to coerce them into typed values:
+
+
+```ts title="app/schema.ts" id="schema"
+import { defineSchema } from '@timber-js/app/params';
+import { codec } from '@timber-js/app/codec';
+import { z } from 'zod/v4';
+
+export default defineSchema({
+  segmentParams: {
+    '[id]': z.coerce.number().int().positive(),
+    '[artistSlug]': codec.string,
+    '[year]': codec.integer,
+  },
+});
+```
+
+<Callout variant="tip" title="Auto-generated Schema Sync">
+  You can auto-generate this file at any time (or any incremental updates) by running `npx timber schema sync`.
+</Callout>
+
+Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`, `[[...slug]]`). A dynamic segment with no key here defaults to `string`. Invalid values produce a **404** — if `/products/abc` can't parse `abc` as a positive integer, the resource doesn't exist.
+
+Each dynamic segment gets one codec. If you want two different schemas for a dynamic segment, give it another name. For example: if you want `[id]` to be `number` in one place, but `uuid` in another – rename the latter to `[uuid]`.
+
+Every dynamic segment key must be unique across segment types (dynamic, catch-all, optional-catch-all). That means `[id]` and `[...id]` will throw a build error. That way, we can be sure `const { id } = getSegmentParams();` is either a flat or array value. Change the latter to `[...ids]` to fix it.
+
+### Type Narrowing with `$segment`
+
+Each route directory gets a generated `./$segment` virtual module that exports `SEGMENT_PATH` — a string literal typed to the segment's tree path. Import it and pass it to `getSegmentParams()` for exact types:
+
+```tsx title="app/products/[id]/page.tsx" use="schema"
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+export default async function ProductPage() {
+  const { id } = getSegmentParams(SEGMENT_PATH); // id: number — narrowed!
+  const product = await getProduct(id);
+  // ...
+}
+```
+
+Without `SEGMENT_PATH`, `getSegmentParams()` returns `Partial<AllSegmentParams>` — all params optional, honest types. With `SEGMENT_PATH`, you get exact types for the current route depth.
+
+Coercion runs **after route matching, before middleware**. Middleware and access checks receive already-typed params.
+
+### Client Usage
+
+Use `useSegmentParams()` with the same `SEGMENT_PATH` pattern in client components:
+
+```tsx title="app/products/[id]/breadcrumb.tsx" use="schema"
+'use client';
+import { SEGMENT_PATH } from './$segment';
+import { useSegmentParams } from '@timber-js/app/client';
+
+export function ProductBreadcrumb() {
+  const { id } = useSegmentParams(SEGMENT_PATH);
+  return <span>Product {id}</span>;
+}
+```
+
+`SEGMENT_PATH` flows from server → client via RSC serialization — it's just a string.
+
+### Shared Components
+
+Pass `SEGMENT_PATH` as a prop for type-safe shared components:
+
+```tsx title="components/year-header.tsx"
+import { getSegmentParams } from '@timber-js/app/server';
+
+export function YearHeader({ segmentPath }: { segmentPath: string }) {
+  const { artistSlug, year } = getSegmentParams(segmentPath);
+  return <h1>{artistSlug} — {year}</h1>;
+}
+```
+
+### Without Type Narrowing
+
+Omit the argument to get all params as optional:
+
+```tsx
+import { getSegmentParams } from '@timber-js/app/server';
+
+const params = getSegmentParams();
+// ^ Partial<AllSegmentParams> — all optional, honest types
+```
+
+## Search Params
+
+Declare typed search params with `defineSearchParams` in any module, then import it where you need it. Unlike segment params, there is no convention file and nothing is scanned:
+
+```ts title="app/products/search-params.ts" id="search-params"
+import { defineSearchParams, withDefault } from '@timber-js/app/search-params';
+import { parseAsInteger } from 'nuqs';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: withDefault(parseAsInteger, 1),
+  sort: z.enum(['price', 'name', 'date']).default('date'),
+  q: z.string().optional(),
+});
+```
+
+### Server Usage
+
+```tsx title="app/products/page.tsx" use="search-params"
+import { searchParams } from './search-params';
+
+export default async function ProductsPage() {
+  const { page, sort, q } = searchParams.get();
+  const products = await getProducts({ page, sort, query: q });
+  return <ProductList products={products} />;
+}
+```
+
+### Client Usage
+
+```tsx title="app/products/filters.tsx" use="search-params"
+'use client';
+import { searchParams } from './search-params';
+
+export function ProductFilters() {
+  const [params, setParams] = searchParams.useQueryStates();
+
+  return (
+    <div>
+      <input
+        value={params.q ?? ''}
+        onChange={(e) => setParams({ q: e.target.value })}
+      />
+      <select
+        value={params.sort}
+        onChange={(e) => setParams({ sort: e.target.value })}
+      >
+        <option value="date">Date</option>
+        <option value="price">Price</option>
+        <option value="name">Name</option>
+      </select>
+    </div>
+  );
+}
+```
+
+By default, `.useQueryStates()` triggers an RSC navigation when params change. Set `shallow: true` to update the URL without a server roundtrip.
+
+## Cookies
+
+Define typed cookies with `defineCookie()`:
+
+```ts title="lib/cookies.ts"
+import { defineCookie } from '@timber-js/app/cookies';
+import { z } from 'zod/v4';
+
+export const themeCookie = defineCookie('theme', {
+  codec: z.enum(['light', 'dark', 'system']).default('system'),
+  httpOnly: false,
+  maxAge: 60 * 60 * 24 * 365,
+});
+```
+
+Server:
+
+```tsx
+const theme = await themeCookie.getCookie();   // 'light' | 'dark' | 'system'
+await themeCookie.setCookie('dark');            // before flush only
+```
+
+Client:
+
+```tsx
+'use client';
+import { themeCookie } from '../lib/cookies';
+
+export function ThemeToggle() {
+  const [theme, setTheme] = themeCookie.useCookie();
+  return (
+    <select value={theme} onChange={(e) => setTheme(e.target.value as typeof theme)}>
+      <option value="light">Light</option>
+      <option value="dark">Dark</option>
+      <option value="system">System</option>
+    </select>
+  );
+}
+```
+
+{/* ## Built-in Codecs
+
+timber ships zero-dependency codecs for common types:
+
+| Codec                       | Type              | Example                   |
+| --------------------------- | ----------------- | ------------------------- |
+| `parseAsString`             | `string \| null`  | `?q=shoes` → `'shoes'`   |
+| `parseAsInteger`            | `number \| null`  | `?page=2` → `2`          |
+| `parseAsFloat`              | `number \| null`  | `?price=9.99` → `9.99`   |
+| `parseAsBoolean`            | `boolean \| null` | `?debug=true` → `true`   |
+| `parseAsStringEnum(values)` | `T \| null`       | `?sort=price` → `'price'` |
+
+For segment params, use the `codec` namespace:
+
+| Codec              | Type                    | Description              |
+| ------------------ | ----------------------- | ------------------------ |
+| `codec.string`     | `string`                | Default (no-op passthrough) |
+| `codec.integer`    | `number`                | Integer coercion         |
+| `codec.slug`       | `string`                | URL-safe slug            |
+| `codec.stringArray` | `string[]`             | For catch-all segments   |
+| `codec.catchAll(inner)` | `T[]`             | Wraps scalar codec for catch-all segments |
+| `codec.optionalCatchAll(inner)` | `T[] \| undefined` | Wraps scalar codec for optional catch-all segments |
+
+Use `withDefault()` to get a non-nullable type for search params. [nuqs](https://nuqs.47ng.com/) parsers all work as codecs: an absent param is `null` and a repeated one takes the first value. Note that `parseAsArrayOf` reads a comma-separated list from a single key — for repeated keys (`?ids=1&ids=2`) use an array schema, e.g. `z.array(z.string()).default([])`. */}
+
+## Composition
+
+Compose codec maps via plain object spread:
+
+```ts title="lib/search-params/pagination.ts"
+import { withDefault } from '@timber-js/app/search-params';
+import { parseAsInteger } from 'nuqs';
+
+export const pagination = {
+  page: withDefault(parseAsInteger, 1),
+  pageSize: withDefault(parseAsInteger, 20),
+};
+```
+
+```ts title="app/products/search-params.ts"
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { pagination } from '@/lib/search-params/pagination';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  ...pagination,
+  sort: z.enum(['asc', 'desc']).default('asc'),
+});
+```
+
+## URL Key Aliasing
+
+Map a property name to a different URL key with `withUrlKey`:
+
+```ts
+import { defineSearchParams, withUrlKey } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  query: withUrlKey(z.string().nullable().default(null), 'q'),
+});
+// ?q=shoes → { query: 'shoes' }
+```
+
+For the full codec protocol, array codecs, and custom codec guidelines, see the [API: Search Params](/docs/api-params) reference.

package/docs/learn/06-forms-and-actions.mdx

@@ -0,0 +1,146 @@
+---
+title: 'Forms and Actions'
+description: 'Server actions with validation, progressive enhancement, and forms that work without JavaScript.'
+slug: 'forms-and-actions'
+---
+
+# Forms and Actions
+
+Forms in timber.js work without JavaScript. They submit to the server, validate, and return a result. When JavaScript is available, they enhance with client-side state and pending UI.
+
+## Action Clients
+
+Define reusable action middleware with `createActionClient`:
+
+```ts title="lib/action.ts"
+import { createActionClient, ActionError } from '@timber-js/app/server';
+import { getUser } from '@/lib/auth';
+
+export const action = createActionClient({
+  middleware: async () => {
+    const user = await getUser();
+    if (!user) throw new ActionError('UNAUTHORIZED');
+    return { user };
+  },
+});
+```
+
+## Defining Actions
+
+```ts title="app/todos/actions.ts"
+'use server';
+
+import { z } from 'zod/v4';
+import { action } from '@/lib/action';
+import { revalidatePath } from '@timber-js/app/server';
+
+declare const db: { todos: { create(data: { title: string; userId: string }): Promise<void> } };
+
+export const createTodo = action
+  .schema(z.object({ title: z.string().min(1) }))
+  .action(async ({ input, ctx }) => {
+    await db.todos.create({ ...input, userId: ctx.user.id });
+    return revalidatePath('/todos');
+  });
+```
+
+The `.schema()` method accepts any Standard Schema-compatible validator — Zod, Valibot, or ArkType. Validation errors are returned to the client automatically.
+
+## Using Actions in Forms
+
+```tsx title="app/todos/todo-form.tsx"
+'use client';
+
+import { useActionState } from '@timber-js/app/client';
+import { createTodo } from './actions';
+
+export default function TodoForm() {
+  const [state, action, pending, errors] = useActionState(createTodo, null);
+
+  return (
+    <form action={action}>
+      <div>
+        <input name="title" required />
+        {errors.getFieldError('title') && (
+          <p className="text-red-600">{errors.getFieldError('title')}</p>
+        )}
+      </div>
+      {errors.serverError && (
+        <p className="text-red-600">Something went wrong. Please try again.</p>
+      )}
+      <button type="submit" disabled={pending}>
+        {pending ? 'Adding...' : 'Add Todo'}
+      </button>
+    </form>
+  );
+}
+```
+
+Without JS, this submits as a standard form POST. With JS, `useActionState` handles pending state and error display.
+
+### Form Errors
+
+`useActionState` from `@timber-js/app/client` returns a 4-tuple where the 4th element is auto-derived form errors:
+
+```tsx
+const [state, action, pending, errors] = useActionState(myAction, null);
+
+errors.fieldErrors;              // Record<string, string[]>
+errors.formErrors;               // string[] (form-level errors)
+errors.serverError;              // { code: string; data?: Record<string, unknown> } | null
+errors.hasErrors;                // boolean
+errors.getFieldError('title');   // string | null (first error for field)
+```
+
+## After Mutation
+
+| Pattern                   | When to use                                      |
+| ------------------------- | ------------------------------------------------ |
+| `redirect('/path')`       | User should land somewhere new                   |
+| `revalidatePath('/path')` | Current page needs fresh data                    |
+| `useOptimistic`           | Instant UI update, action confirms in background |
+
+## Forms Without JavaScript
+
+When JavaScript is disabled and a server action returns validation errors, timber re-renders the page instead of redirecting. The errors and submitted values are available via `getFormFlash()`:
+
+```tsx title="app/todos/page.tsx"
+import { getFormFlash } from '@timber-js/app/server';
+import { TodoForm } from './todo-form';
+
+export default async function TodosPage() {
+  const flash = getFormFlash();
+  return <TodoForm flash={flash} />;
+}
+```
+
+```tsx title="app/todos/todo-form.tsx"
+'use client';
+
+import { useActionState } from '@timber-js/app/client';
+import { createTodo } from './actions';
+import type { FormFlashData } from '@timber-js/app/server';
+
+export function TodoForm({ flash }: { flash?: FormFlashData | null }) {
+  const [state, action, pending, errors] = useActionState(createTodo, null);
+
+  const fieldError = (field: string) =>
+    errors.getFieldError(field) ?? flash?.validationErrors?.[field]?.[0];
+  const defaultValue = (field: string) =>
+    (flash?.submittedValues?.[field] as string) ?? '';
+
+  return (
+    <form action={action}>
+      <input name="title" defaultValue={defaultValue('title')} />
+      {fieldError('title') && <p className="text-red-600">{fieldError('title')}</p>}
+      <button type="submit" disabled={pending}>
+        {pending ? 'Adding...' : 'Add Todo'}
+      </button>
+    </form>
+  );
+}
+```
+
+Flash data is server-side only — stored in AsyncLocalStorage for the duration of the re-render. Sensitive fields (password, apiKey, cvv, etc.) are automatically stripped from `submittedValues`.
+
+For advanced topics — coercion helpers, `parseFormData`, sensitive field stripping configuration, and the full end-to-end example — see [Advanced Forms](/docs/advanced-forms).