@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/docs/api/30-api-server.mdx

@@ -0,0 +1,236 @@
+---
+title: 'API: @timber-js/app/server'
+description: 'Server-side exports — deny, redirect, getHeaders, getCookieJar, createActionClient, and context types.'
+slug: 'api-server'
+---
+
+# @timber-js/app/server
+
+Server-side utilities and types. Import from `@timber-js/app/server`.
+
+## Navigation & Status
+
+### `deny(statusOrOptions?, data?)`
+
+Universal denial/error primitive. Produces an HTTP error status and renders the matching status file. Accepts any 4xx or 5xx status code. Default status is 403.
+
+```ts
+import { deny } from '@timber-js/app/server';
+
+deny(); // 403 (default)
+deny(404); // 404 Not Found
+deny(503, { retry: true }); // 503 with data
+deny({ status: 500, data: { title: 'Error' } }); // object form
+```
+
+### `redirect(url, type?)`
+
+Redirect to a URL. Sends HTTP 307 (temporary) by default.
+
+```ts
+import { redirect } from '@timber-js/app/server';
+
+redirect('/login'); // 302 Temporary Redirect
+redirect('/new-page', { permanent: true }); // 308 Permanent Redirect
+redirect('/new-page', { status: 301 }); // 301 (explicit status)
+redirect('/new-page', 301); // 301 (shorthand)
+```
+
+The `permanent` option defaults to status **308** (preserves HTTP method). If you need 301 specifically, pass `status: 301`. When both `permanent` and `status` are provided, `status` wins.
+
+### `redirectExternal(url, allowList, status?)`
+
+Redirect to an external URL. The target origin must be in the provided allow-list. Only `http:` and `https:` schemes are permitted — this prevents open redirect vulnerabilities and blocks `javascript:` scheme injection.
+
+```ts
+import { redirectExternal } from '@timber-js/app/server';
+
+// Redirect to an allowed external domain
+redirectExternal('https://auth.example.com/login', ['https://auth.example.com']);
+
+// With a custom status code
+redirectExternal('https://docs.example.com', ['https://docs.example.com'], 301);
+```
+
+| Parameter   | Type       | Default | Description                                                |
+| ----------- | ---------- | ------- | ---------------------------------------------------------- |
+| `url`       | `string`   | —       | Absolute URL to redirect to                                |
+| `allowList` | `string[]` | —       | Allowed origins (e.g. `['https://example.com']`)           |
+| `status`    | `number`   | `302`   | HTTP redirect status code (3xx)                            |
+
+Throws if the origin is not in the allow-list, the scheme isn't `http:` or `https:`, or the URL is invalid.
+
+## Request Context
+
+### `getHeaders()`
+
+Returns the incoming request headers. ALS-backed — works in server components, middleware, access checks.
+
+```ts
+import { getHeaders } from '@timber-js/app/server';
+
+const h = getHeaders();
+const auth = h.get('authorization');
+```
+
+Returns `ReadonlyHeaders` — a read-only `Headers` interface (sync).
+
+### `getCookieJar()`
+
+Returns the request cookies with mutation methods.
+
+```ts
+import { getCookieJar } from '@timber-js/app/server';
+
+const c = getCookieJar();
+c.get('session'); // Read
+c.set('theme', 'dark'); // Set (before flush only)
+c.delete('session'); // Delete
+c.clear(); // Clear all
+```
+
+Mutations are only allowed before the response flushes. Attempting to set a cookie after flush throws in dev mode.
+
+For typed cookies with validation and a client React hook, see [`defineCookie()`](/docs/typed-params) from `@timber-js/app/cookies`.
+
+Cookies queued before a middleware error are included once on the HTTP 500 response. They also survive when `proxy.ts` awaits `next()` and then throws. This applies to both document requests and client navigations; a later error does not roll back queued cookie writes.
+
+## Actions
+
+### `createActionClient(options)`
+
+Create a reusable action client with middleware for auth and validation.
+
+```ts
+import { createActionClient, ActionError } from '@timber-js/app/server';
+import { getUser } from '@/lib/auth';
+
+const action = createActionClient({
+  middleware: async () => {
+    const user = await getUser();
+    if (!user) throw new ActionError('UNAUTHORIZED');
+    return { user };
+  },
+});
+
+// Usage:
+const myAction = action.schema(z.object({ title: z.string() })).action(async ({ input, ctx }) => {
+  // ctx.user is typed from middleware return
+});
+```
+
+### `ActionError`
+
+Throw from action middleware or bodies to produce a typed error result.
+
+```ts
+throw new ActionError('UNAUTHORIZED');
+throw new ActionError('VALIDATION_FAILED', { field: 'email' });
+```
+
+### `revalidatePath(path)`
+
+Re-render a path and return the RSC payload as part of the action response.
+
+### `revalidateTag(tag)`
+
+Invalidate all cache entries with the given tag.
+
+## Segment Params
+
+### `getSegmentParams(segmentPath?)`
+
+Returns route path params for the current request. Pass a `SEGMENT_PATH` string from `$segment` for exact types, or omit for `Partial<AllSegmentParams>`. ALS-backed — works in server components, middleware, access checks, and server actions.
+
+```ts
+import { SEGMENT_PATH } from './$segment';
+import { getSegmentParams } from '@timber-js/app/server';
+
+const { id } = getSegmentParams(SEGMENT_PATH);  // Exact types from schema
+const params = getSegmentParams();        // Partial<AllSegmentParams>
+```
+
+For typed coercion, define codecs in `app/schema.ts` with `defineSchema()`. See [Typed Params](/docs/typed-params).
+
+## Types
+
+### `RouteContext`
+
+```ts
+interface RouteContext {
+  req: Request;
+  headers: Headers;        // Response headers (writable)
+}
+```
+
+Segment params and query params are **not** on `RouteContext`. Read them the same way pages do — `getSegmentParams(SEGMENT_PATH)` (importing `SEGMENT_PATH` from the route's `./$segment` module) and `searchParams.get()` on an imported definition. For the raw query string, use `new URL(ctx.req.url).searchParams`.
+
+### `MiddlewareContext`
+
+```ts
+interface MiddlewareContext {
+  req: Request;
+  segmentParams: Record<string, string | string[]>;
+  headers: Headers; // Response headers (writable)
+  requestHeaders: Headers; // Request headers (injectable)
+  readonly nonce: string;  // Per-request CSP nonce, generated on first read
+}
+```
+
+### `AccessContext`
+
+Empty interface — `access.ts` takes no arguments. Use ALS-backed imports like `getSegmentParams(SEGMENT_PATH)`.
+
+### `Metadata`
+
+The full metadata type — see [Metadata & SEO](/docs/metadata-and-fonts) for usage.
+
+### `MetadataRoute`
+
+Type for metadata route files (sitemap, robots, etc.).
+
+## Tracing
+
+### `getTraceId()`
+
+Returns the current request's 32-char hex trace ID. Works in middleware, access checks, server components, and server actions.
+
+```ts
+import { getTraceId } from '@timber-js/app/server';
+
+const id = getTraceId();
+```
+
+### `getSpanId()`
+
+Returns the current OTEL span ID, or `undefined` if OTEL is not active.
+
+### `withSpan(name, attributes, fn)`
+
+Run a function within an OTEL span. No-op passthrough if OTEL is not available.
+
+```ts
+import { withSpan } from '@timber-js/app/server';
+
+declare const db: { query(...args: unknown[]): Promise<unknown> };
+
+const result = await withSpan('db.query', { table: 'users' }, () => db.query());
+```
+
+### `addSpanEvent(name, attributes?)`
+
+Add an event to the current active span.
+
+See [Instrumentation & Tracing](/docs/instrumentation) for full documentation.
+
+## Lifecycle
+
+### `waitUntil(promise)`
+
+Register a promise to be kept alive after the response is sent. Platform-dependent — works on Cloudflare Workers and other platforms that support it.
+
+```ts
+import { waitUntil } from '@timber-js/app/server';
+
+waitUntil(analytics.track(event));
+```

package/docs/api/31-api-client.mdx

@@ -0,0 +1,167 @@
+---
+title: 'API: @timber-js/app/client'
+description: 'Client-side exports — Link, useRouter, usePathname, navigation hooks, and form utilities.'
+slug: 'api-client'
+---
+
+# @timber-js/app/client
+
+Client-side components and hooks. Import from `@timber-js/app/client`.
+
+## Components
+
+### `<Link>`
+
+Client-side navigation link. Type-checks `href` against the generated route map.
+
+```tsx
+import { Link } from '@timber-js/app/client';
+
+<Link href="/about">About</Link>
+<Link href="/products/123" replace>Product</Link>
+<Link href="/gallery" onNavigate={(e) => { /* intercept */ }}>Gallery</Link>
+```
+
+#### Props
+
+| Prop         | Type                | Description                                 |
+| ------------ | ------------------- | ------------------------------------------- |
+| `href`       | `string`            | Target URL (type-checked against route map) |
+| `replace`    | `boolean`           | Use `replaceState` instead of `pushState`   |
+| `prefetch`   | `boolean`           | Prefetch the RSC payload on hover           |
+| `onNavigate` | `OnNavigateHandler` | Intercept navigation before routing         |
+
+`prefetch` also works for previously visited URLs. A click can reuse the prefetched payload for 30 seconds; after expiry, navigation fetches a fresh payload. Same-page fragment links only scroll within the page and do not prefetch.
+
+### `<TimberErrorBoundary>`
+
+Error boundary component with reset support.
+
+## Hooks
+
+### `useRouter()`
+
+Programmatic navigation.
+
+```tsx
+const router = useRouter();
+router.push('/dashboard');
+router.replace('/settings');
+router.refresh();
+router.back();
+router.forward();
+```
+
+#### `RouterInstance`
+
+| Method          | Description                        |
+| --------------- | ---------------------------------- |
+| `push(href)`    | Navigate, add history entry        |
+| `replace(href)` | Navigate, replace history entry    |
+| `refresh()`     | Re-fetch current route RSC payload |
+| `back()`        | Go back                            |
+| `forward()`     | Go forward                         |
+
+A `deny()` reached by a client navigation renders your status page in place, without a page load — the denial travels in the navigation payload, and the boundary for the matching status file renders it. The payload response itself is always HTTP 200; the status code contract is a property of full page loads, where the browser, crawlers, and CDNs are the ones reading it.
+
+If the server cannot answer a navigation or a `refresh()` at all, the router hands the URL back to the server as a full page load so it can render the error page as HTML with the right status code. That applies to back/forward too. None of these methods report the failure to your code — there is nothing to catch, and nothing to render a fallback for.
+
+### `usePathname()`
+
+Returns the current pathname as a string.
+
+```tsx
+const pathname = usePathname(); // "/dashboard/settings"
+```
+
+### `useSelectedLayoutSegment()`
+
+Returns the active child segment within a layout.
+
+```tsx
+const segment = useSelectedLayoutSegment(); // "settings"
+```
+
+### `useSelectedLayoutSegments()`
+
+Returns all active segments below the current layout.
+
+```tsx
+const segments = useSelectedLayoutSegments(); // ["settings", "profile"]
+```
+
+### `usePendingNavigation()`
+
+Returns whether a navigation is in flight. Use instead of wrapping `children` in `<Suspense>`.
+
+```tsx
+const pending = usePendingNavigation();
+```
+
+### `useLinkStatus()`
+
+Per-link pending state. Must be used inside a `<Link>` component's children.
+
+```tsx
+const { isPending } = useLinkStatus();
+```
+
+### `useSegmentParams(segmentPath?)`
+
+Returns the current route segment params. Pass `SEGMENT_PATH` from `$segment` for exact types.
+
+```tsx
+import { SEGMENT_PATH } from './$segment';
+import { useSegmentParams } from '@timber-js/app/client';
+
+const { id } = useSegmentParams(SEGMENT_PATH);  // Exact types from schema
+const params = useSegmentParams();        // Partial<AllSegmentParams>
+```
+
+## Form Hooks
+
+### `useActionState(action, initialState)`
+
+Typed wrapper around React 19's `useActionState`. Returns `[result, formAction, isPending, errors]` — the 4th element auto-derives field and form-level errors from the result.
+
+```tsx
+const [result, action, isPending, errors] = useActionState(createTodo, flash);
+
+errors.hasErrors         // boolean
+errors.fieldErrors       // Record<string, string[]>
+errors.formErrors        // string[]
+errors.serverError       // { code, data? } | null
+errors.getFieldError('title') // string | null
+```
+
+### `useFormAction(action)`
+
+Bind a server action to a form with pending state.
+
+## Utilities
+
+### `interpolateParams(pattern, params)`
+
+Fill a route pattern with param values.
+
+```ts
+interpolateParams('/products/[id]', { id: '123' }); // "/products/123"
+```
+
+### `defineSearchParams().useQueryStates()`
+
+Sync typed search params to the URL. Called on a `defineSearchParams()` definition. See [Search Params](/docs/typed-params).
+
+## Cookie Hooks
+
+### `defineCookie().useCookie()`
+
+Reactive cookie access in client components. Define a typed cookie with `defineCookie()` from `@timber-js/app/cookies`, then call `.useCookie()` in client components. Returns `[value, setter, deleter]`.
+
+```tsx
+import { themeCookie } from '../lib/cookies';
+
+const [theme, setTheme, deleteTheme] = themeCookie.useCookie();
+```
+
+See [Cookies](/docs/typed-params) for full documentation.