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

package/docs/more/02-advanced-forms.mdx

@@ -0,0 +1,137 @@
+---
+title: 'Advanced Forms'
+description: 'Coercion helpers, parseFormData, form flash internals, and sensitive field stripping.'
+slug: 'advanced-forms'
+---
+
+# Advanced Forms
+
+This page covers advanced form patterns beyond [Forms and Actions](/docs/forms-and-actions): coercion helpers, raw FormData parsing, form flash internals, and sensitive field stripping.
+
+## Coercing FormData Values
+
+HTML forms send everything as strings. Use `coerce` helpers to convert FormData values before schema validation:
+
+```ts
+import { coerce } from '@timber-js/app/server';
+import { z } from 'zod/v4';
+
+const eventSchema = z.object({
+  title: z.string().min(1),
+  maxAttendees: z.preprocess(coerce.number, z.number().min(1)),
+  isPublic: z.preprocess(coerce.checkbox, z.boolean()),
+  date: z.preprocess(coerce.date, z.date()),
+});
+```
+
+| Helper            | Input               | Output              |
+| ----------------- | ------------------- | ------------------- |
+| `coerce.number`   | `"42"`, `""`        | `42`, `undefined`   |
+| `coerce.checkbox` | `"on"`, `undefined` | `true`, `false`     |
+| `coerce.json`     | `'{"a":1}'`         | `{ a: 1 }`          |
+| `coerce.date`     | `"2024-01-15"`      | `Date`              |
+| `coerce.file`     | `File`, empty input | `File`, `undefined` |
+
+`coerce.file` accepts options for validation:
+
+```ts
+z.preprocess(
+  coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),
+  z.instanceof(File)
+);
+```
+
+## `parseFormData`
+
+For advanced cases, `parseFormData` converts raw `FormData` into a plain object before schema validation:
+
+```ts
+import { parseFormData } from '@timber-js/app/server';
+
+const obj = parseFormData(formData);
+```
+
+It handles common patterns:
+
+- **Duplicate keys → arrays**: `tags=js&tags=ts` → `{ tags: ["js", "ts"] }`
+- **Dot-path nesting**: `user.name=Alice` → `{ user: { name: "Alice" } }`
+- **Empty strings → undefined**: Enables `.optional()` semantics
+- **Empty file inputs → undefined**: File inputs with no selection become `undefined`
+
+`createActionClient` calls `parseFormData` automatically — you only need it for manual FormData handling.
+
+## Form Flash Internals
+
+When JavaScript is disabled and a server action returns validation errors, timber re-renders the page with flash data available via `getFormFlash()`:
+
+```ts
+interface FormFlashData {
+  validationErrors: Record<string, string[]>;
+  submittedValues: Record<string, unknown>;
+  serverError?: { code: string; data?: Record<string, unknown> };
+}
+```
+
+- `validationErrors` — field-level errors keyed by field name
+- `submittedValues` — raw input for repopulating form fields (File objects excluded, sensitive fields stripped)
+- `serverError` — present if an `ActionError` was thrown
+
+Flash data is server-side only — stored in AsyncLocalStorage for the duration of the re-render. Never serialized to cookies or headers.
+
+## Sensitive Field Stripping
+
+On validation failure timber echoes submitted form values back so users don't re-type everything. To prevent plaintext passwords or credit-card numbers from leaking through the RSC payload or into HTML `defaultValue` attributes, timber automatically strips a deny-list of sensitive field names.
+
+**Built-in deny-list** (case-insensitive, nested objects walked recursively):
+
+- `password`, `passwd`, `pwd` (and variants like `currentPassword`, `newPassword`)
+- `secret`, `apiKey`, `accessToken`, `refreshToken`, `privateKey`
+- `cvv`, `cvc`, `cardNumber`, `cardCvc`
+- `ssn`, `socialSecurityNumber`
+- `otp`, `totp`, `mfaCode`, `twoFactorCode`
+- `token` (exact match only — `csrfToken` is preserved)
+
+Stripped fields are omitted from `submittedValues` entirely — not replaced with empty strings.
+
+### Global Configuration
+
+```ts title="timber.config.ts"
+import { defineConfig } from '@timber-js/app';
+
+export default defineConfig({
+  forms: {
+    // true / omitted — use built-in deny-list (default)
+    // false — disable all stripping (NEVER in prod)
+    // string[] — extra field names merged with built-in list
+    stripSensitiveFields: ['internalCode', 'bankAccount'],
+  },
+});
+```
+
+### Per-Action Override
+
+```ts
+import { createActionClient } from '@timber-js/app/server';
+
+const action = createActionClient({
+  stripSensitiveFields: (name) => name.startsWith('secret_'),
+});
+```
+
+Per-action config takes precedence over global config, which takes precedence over the built-in default.
+
+## Shared Schemas for Client + Server Validation
+
+Define Zod schemas in shared files and import them on both sides for instant client-side validation while keeping the server as the source of truth:
+
+```ts title="lib/schemas/contact.ts"
+import { z } from 'zod/v4';
+
+export const contactSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100),
+  email: z.string().email('Invalid email address'),
+  message: z.string().min(10).max(2000),
+});
+```
+
+Use in the server action via `.schema(contactSchema)` and in the client form for `onBlur` validation. Client validation is a UX enhancement — always validate on the server.

package/docs/more/03-coming-from-nextjs.mdx

@@ -0,0 +1,186 @@
+---
+title: 'Coming from Next.js'
+description: 'A practical mapping for Next.js developers — in Next.js you did X, in timber you do Y.'
+slug: 'coming-from-nextjs'
+---
+
+# Coming from Next.js
+
+This page maps Next.js patterns to timber equivalents. It's not a comparison (see [timber vs Next.js](/docs/timber-vs-nextjs) for that) — it's a migration mental model.
+
+## Data Fetching
+
+**Next.js:** `getServerSideProps`, `getStaticProps`, or `fetch()` with implicit caching.
+
+**timber:** Async server components. No loaders, no special functions. `fetch()` is never patched or cached — use `timber.cache()` explicitly when you want caching.
+
+```tsx title="app/products/page.tsx"
+// timber — just an async component
+export default async function ProductsPage() {
+  const products = await db.products.findMany();
+  return <ProductList products={products} />;
+}
+```
+
+## `loading.tsx`
+
+**Next.js:** `loading.tsx` convention inserts a Suspense boundary automatically.
+
+**timber:** No `loading.tsx`. Place `<Suspense>` explicitly where you want it. This keeps you in control of what streams and what blocks the HTTP status code.
+
+```tsx
+// timber — explicit Suspense
+import { Suspense } from 'react';
+
+export default async function Page() {
+  const product = await getProduct(id); // blocks, can affect status code
+  return (
+    <div>
+      <h1>{product.name}</h1>
+      <Suspense fallback={<Skeleton />}>
+        <Reviews productId={id} /> {/* streams in */}
+      </Suspense>
+    </div>
+  );
+}
+```
+
+## Middleware
+
+**Next.js:** Single global `middleware.ts` at the project root. Matcher patterns select routes.
+
+**timber:** Per-segment `middleware.ts` files. Place them at the route level that matches the concern. `proxy.ts` for global concerns (CORS, rate limiting, security headers).
+
+```
+app/
+  proxy.ts                    # Global — every request (like Next.js middleware but with next())
+  dashboard/
+    middleware.ts             # Only runs for /dashboard/*
+    settings/
+      middleware.ts           # Only runs for /dashboard/settings/*
+```
+
+## `useSearchParams`
+
+**Next.js:** `useSearchParams()` hook returns a `URLSearchParams` object.
+
+**timber:** Typed search params via `defineSearchParams` in any module you import. Server reads via `.get()`, client reads/writes via `.useQueryStates()`. Segment params are defined globally in `app/schema.ts` via `defineSchema()`, accessed with `getSegmentParams(SEGMENT_PATH)` using the `$segment` module.
+
+```ts title="app/products/search-params.ts"
+import { defineSearchParams } from '@timber-js/app/search-params';
+import { z } from 'zod/v4';
+
+export const searchParams = defineSearchParams({
+  page: z.coerce.number().default(1),
+  sort: z.enum(['price', 'name']).default('name'),
+});
+```
+
+## Caching
+
+**Next.js:** Implicit fetch caching, `unstable_cache`, ISR with `revalidate`.
+
+**timber:** No implicit caching. No ISR. Explicit `cache.data()` with TTL and tags:
+
+```ts
+import { cache } from '@timber-js/app/cache';
+
+declare const db: { products: { findPopular(): Promise<{ id: string; name: string }[]> } };
+
+const getProducts = cache.data(
+  async () => db.products.findPopular(),
+  { ttl: 300, tags: ['products'] }
+);
+```
+
+## Authorization
+
+**Next.js:** Usually done in middleware or layout components. No built-in access gate pattern.
+
+**timber:** `access.ts` per segment. Runs inside the React tree with `React.cache` sharing. Supports slot degradation (a denied slot renders `denied.tsx` instead of failing the whole page).
+
+```ts title="app/(auth)/access.ts"
+import { redirect, getCookieJar } from '@timber-js/app/server';
+
+declare function getSessionFromCookie(jar: ReturnType<typeof getCookieJar>): { userId: string } | null;
+
+export default async function access() {
+  const session = getSessionFromCookie(getCookieJar());
+  if (!session) redirect('/login');
+}
+```
+
+## Server Actions
+
+**Next.js:** Server actions with `'use server'`. `useFormState` / `useFormStatus`.
+
+**timber:** `createActionClient` for reusable middleware (auth, validation). `useActionState` from `@timber-js/app/client` returns a 4-tuple with auto-derived errors. Forms work without JavaScript via form flash.
+
+```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 };
+  },
+});
+```
+
+## `notFound()`
+
+**Next.js:** `notFound()` function.
+
+**timber:** `deny(404)` — sends a real HTTP 404 status code:
+
+```tsx
+import { deny } from '@timber-js/app/server';
+
+if (!product) deny(404);
+```
+
+## `redirect()`
+
+**Next.js:** `redirect()` from `next/navigation`.
+
+**timber:** `redirect()` from `@timber-js/app/server`. Same concept, different import:
+
+```ts
+import { redirect } from '@timber-js/app/server';
+
+redirect('/login');        // 302 by default
+redirect('/login', 301);   // Permanent redirect
+```
+
+Code that imports `redirect()` or `notFound()` from `next/navigation` works unmodified — including calls during client component render, which timber converts into an SPA navigation (`redirect`) or your nearest 404 boundary (`notFound`), matching Next.js behavior.
+
+## Metadata
+
+**Next.js:** `export const metadata` or `export async function generateMetadata()`.
+
+**timber:** Same pattern — export `metadata` (static) or a `metadata()` function (dynamic) from any page or layout.
+
+## Imports
+
+| Next.js import            | timber import                              |
+| ------------------------- | ------------------------------------------ |
+| `next/link`               | `@timber-js/app/client` (`Link`)           |
+| `next/navigation`         | `@timber-js/app/client` (`useRouter`, etc) |
+| `next/headers`            | `@timber-js/app/server` (`getHeaders`)     |
+| `next/server`             | `@timber-js/app/server`                    |
+| `unstable_cache`          | `@timber-js/app/cache` (`cache`)           |
+
+## Key Differences Summary
+
+| Concept              | Next.js                          | timber                                |
+| -------------------- | -------------------------------- | ------------------------------------- |
+| Fetch caching        | Implicit, patched `fetch`        | Explicit `timber.cache()`             |
+| ISR                  | Built-in                         | Not supported (use cache + TTL)       |
+| `loading.tsx`        | Convention                       | Use explicit `<Suspense>`             |
+| Middleware            | Single global file              | Per-segment + global `proxy.ts`       |
+| Status codes         | Often 200 for errors            | Real HTTP status codes always         |
+| Auth                 | In middleware or components      | `access.ts` with slot degradation     |
+| Search params        | Untyped `URLSearchParams`       | Typed codecs with validation          |
+| Forms without JS     | Limited support                 | Full form flash support               |

package/docs/more/04-metadata-and-fonts.mdx

@@ -0,0 +1,193 @@
+---
+title: 'Metadata and Fonts'
+description: 'Page titles, Open Graph, metadata routes, Google Fonts, and local fonts.'
+slug: 'metadata-and-fonts'
+---
+
+# Metadata and Fonts
+
+## Metadata
+
+Export `metadata` from any page or layout to control `<head>` tags.
+
+### Static Metadata
+
+```tsx title="app/page.tsx"
+import type { Metadata } from '@timber-js/app/server';
+
+export const metadata: Metadata = {
+  title: 'Dashboard',
+  description: 'Your project dashboard',
+};
+```
+
+### Dynamic Metadata
+
+Export `metadata` as an async function to compute values at request time:
+
+```tsx title="app/products/[id]/page.tsx"
+import type { Metadata } from '@timber-js/app/server';
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+declare function getProduct(id: string): Promise<{ name: string; summary: string; imageUrl: string }>;
+
+export async function metadata(): Promise<Metadata> {
+  const { id } = getSegmentParams(SEGMENT_PATH);
+  const product = await getProduct(id);
+  return {
+    title: product.name,
+    description: product.summary,
+    openGraph: { images: [product.imageUrl] },
+  };
+}
+```
+
+Dynamic `metadata` runs during the render pass — `React.cache` is active, so data fetched here and in the page component is deduplicated.
+
+### Title Templates
+
+Layouts can define a title template. Pages fill in the `%s` placeholder:
+
+```tsx title="app/layout.tsx"
+export const metadata: Metadata = {
+  title: { template: '%s | My App', default: 'My App' },
+};
+```
+
+### Open Graph & Twitter Cards
+
+```tsx
+export const metadata: Metadata = {
+  openGraph: {
+    title: 'My Product',
+    description: 'The best product ever.',
+    images: [{ url: '/og-image.png', width: 1200, height: 630 }],
+  },
+  twitter: {
+    card: 'summary_large_image',
+    title: 'My Product',
+    images: ['/og-image.png'],
+  },
+};
+```
+
+### Metadata Routes
+
+Special files in your route tree generate metadata endpoints:
+
+| File                  | Output                    |
+| --------------------- | ------------------------- |
+| `sitemap.ts`          | `/sitemap.xml`            |
+| `robots.ts`           | `/robots.txt`             |
+| `manifest.ts`         | `/manifest.json`          |
+| `opengraph-image.tsx` | `/opengraph-image.png` + auto `og:image` and `twitter:image` meta tags |
+| `favicon.ico` / `favicon.tsx` | `/favicon.ico`    |
+| `icon.tsx`            | `/icon.png` + auto `<link rel="icon">` |
+
+When `opengraph-image.tsx` exists in a segment, timber automatically emits both `<meta property="og:image">` and `<meta name="twitter:image">` in `<head>` — no need to declare them in your `metadata` export. The auto-linked URL includes a cache-busting hash so social platforms pick up changes on redeploy.
+
+If you declare `openGraph.images` in your metadata, both auto-linked tags are suppressed. If you declare only `twitter.images`, the auto-linked `twitter:image` is suppressed but `og:image` is still emitted. User-declared metadata always wins.
+
+`favicon.tsx` lets you generate favicons dynamically (e.g. tenant branding). The URL stays `/favicon.ico` for browser compatibility.
+
+For OG image generation, use `takumi-js/response` (BYO package — not bundled with timber):
+
+```tsx title="app/opengraph-image.tsx"
+import { ImageResponse } from 'takumi-js/response';
+
+export default async function OpenGraphImage() {
+  return new ImageResponse(
+    <div style={{ fontSize: 48, background: 'white', width: '100%', height: '100%',
+      display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
+      My App
+    </div>,
+    { width: 1200, height: 630 }
+  );
+}
+```
+
+Metadata is always complete before the flush — no client-side injection, no partial `<head>`.
+
+---
+
+## Fonts
+
+timber.js downloads, subsets, and self-hosts fonts at build time. No requests to Google at runtime. No layout shift.
+
+### Google Fonts
+
+```tsx title="app/layout.tsx"
+import { Inter, JetBrains_Mono } from '@timber-js/app/fonts/google';
+
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-sans',
+});
+
+const jetbrainsMono = JetBrains_Mono({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-mono',
+});
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${jetbrainsMono.variable}`}>
+      <body className={inter.className}>{children}</body>
+    </html>
+  );
+}
+```
+
+### Local Fonts
+
+```tsx
+import localFont from '@timber-js/app/fonts/local';
+
+const myFont = localFont({
+  src: [
+    { path: './fonts/MyFont-Regular.woff2', weight: '400' },
+    { path: './fonts/MyFont-Bold.woff2', weight: '700' },
+  ],
+  display: 'swap',
+  variable: '--font-custom',
+});
+```
+
+### Static Analysis Constraints
+
+Font calls look like runtime functions but are a build-time transform, so they must be statically analyzable. The canonical shape is a module-scope `const` (or `export const`) with a literal config object:
+
+```tsx
+const inter = Inter({ subsets: ['latin'] });        // ✅
+export const mono = JetBrains_Mono({ subsets: ['latin'] }); // ✅
+```
+
+Anything else fails the build with a descriptive error instead of silently breaking at runtime:
+
+```tsx
+export default Inter({ subsets: ['latin'] });       // ❌ build error
+const theme = { font: Inter({ subsets: ['latin'] }) }; // ❌ build error
+const cls = Inter({ subsets: ['latin'] }).className;   // ❌ build error
+import * as fonts from 'next/font/google';          // ❌ build error
+```
+
+### CSS Variables
+
+Use the `variable` option and reference it in your styles:
+
+```css title="globals.css"
+body { font-family: var(--font-sans), system-ui, sans-serif; }
+code { font-family: var(--font-mono); }
+```
+
+### Next.js Compatibility
+
+Imports from `next/font/google` and `next/font/local` are shimmed — existing code works without changes:
+
+```tsx
+import { Inter } from 'next/font/google';
+import localFont from 'next/font/local';
+```