@zerotal/arch 1.7.4 → 1.8.0

package/docs/email-verification.md

@@ -18,7 +18,7 @@ in `@zerotal/core` signs the link, and `ValidateSignatureMiddleware` in
 `@zerotal/auth` checks it. There is no extra package and no extra table:
 
 ```typescript
-import { Url } from "zerotal";
+import { Url } from "zerotal/http";
 import { ValidateSignatureMiddleware } from "@zerotal/auth";
 ```
 
@@ -51,7 +51,7 @@ register ──▶ Url.sign(/auth/verify?id&email, ttl) ──▶ email link
 
 Add a nullable `email_verified_at` column to your users table:
 
-```typescript
+```typescript fragment
 // database/migrations/002_add_email_verified_at.ts
 export default class AddEmailVerifiedAt extends Migration {
   async up(schema: Schema) {
@@ -140,7 +140,7 @@ The verify route is already guarded by `ValidateSignatureMiddleware`, so the
 controller can trust that the URL is intact — it only checks that the `id`/`email`
 pair still resolves to a real user:
 
-```typescript
+```typescript fragment
 // app/controllers/VerificationController.ts
 import { Auth } from "@zerotal/auth";
 import { Notify } from "@zerotal/notifications";
@@ -199,7 +199,7 @@ export class VerificationController {
 
 ## Routes
 
-```typescript
+```typescript fragment
 // routes/web.ts
 import { ValidateSignatureMiddleware } from "@zerotal/auth";
 import { RequireAuthMiddleware } from "#app/middleware/RequireAuth.ts";
@@ -220,7 +220,7 @@ Router.post("/auth/verify/resend", VerificationController, "resend", [RequireAut
 Call `Notify.queue()` at the end of your registration handler so the HTTP response
 returns immediately while delivery happens in the background:
 
-```typescript
+```typescript fragment
 // app/controllers/AuthController.ts
 import { Notify } from "@zerotal/notifications";
 import { VerifyEmailNotification } from "#app/notifications/VerifyEmailNotification.ts";
@@ -242,7 +242,7 @@ Write a `VerifiedMiddleware` once and apply it to routes that must only be
 accessible to verified users. It extends `BaseMiddleware` (from `zerotal`)
 and reads the current user via `Auth.userOrNull()`:
 
-```typescript
+```typescript fragment
 // app/middleware/Verified.ts
 import { BaseMiddleware } from "zerotal";
 import type { HttpContext, NextFn } from "zerotal";
@@ -273,7 +273,7 @@ export class VerifiedMiddleware extends BaseMiddleware {
 Apply it alongside `RequireAuthMiddleware` so unverified users are bounced to the
 notice page:
 
-```typescript
+```typescript fragment
 // routes/web.ts
 Router.group({ middleware: [RequireAuthMiddleware, VerifiedMiddleware] }, () => {
   Router.get("/dashboard", DashboardController, "index");
@@ -284,7 +284,7 @@ Router.group({ middleware: [RequireAuthMiddleware, VerifiedMiddleware] }, () =>
 
 ## Testing
 
-```typescript
+```typescript fragment
 // tests/email-verification.test.ts
 it("unverified user is redirected to notice page", async () => {
   const user = await UserFactory.create({ emailVerifiedAt: null });

package/docs/encryption.md

@@ -81,7 +81,7 @@ Crypt.decrypt<{ userId: number }>(blob).userId; // 7
 algorithm is auto-detected on verify, so changing the default never breaks
 existing hashes.
 
-```ts
+```ts fragment
 // in a controller or service
 import { Hash } from "zerotal/security";
 
@@ -147,7 +147,7 @@ thread a signing key through your code.
 
 ### Generating a signed URL
 
-```ts
+```ts fragment
 function sign(
   base: string,
   params?: Record<string, string>,
@@ -173,7 +173,7 @@ per-feature invite secret): `Url.sign(base, params, minutes, inviteSecret)`.
 
 ### Verifying a signed URL
 
-```ts
+```ts fragment
 // in a controller
 import { Url } from "zerotal/http";
 
@@ -209,7 +209,7 @@ Apply `ValidateSignatureMiddleware` to any route that receives signed URLs — i
 rejects invalid or expired links with a 403 JSON response, so your controller
 only runs when the signature is good:
 
-```ts
+```ts fragment
 // routes/web.ts
 import { ValidateSignatureMiddleware } from "@zerotal/auth";
 
@@ -277,7 +277,7 @@ that a round-trip test alone would never notice.
 **Tampering must throw**, and proving it is what tells you the payload is
 authenticated rather than merely scrambled:
 
-```typescript
+```typescript fragment
 // tests/security/Crypt.test.ts
 import { DecryptionError } from "zerotal/security";
 
@@ -292,7 +292,7 @@ test("a modified payload is rejected", () => {
 **`encrypt()` round-trips any JSON value**, so a test covering an object confirms
 the serialisation as well as the cipher:
 
-```typescript
+```typescript fragment
 // tests/security/Crypt.test.ts
 const payload = Crypt.encrypt({ userId: 7, scopes: ["read"] });
 
@@ -303,7 +303,7 @@ Hashing has its own trap: every `Hash` method except `needsRehash` is async, and
 forgotten `await` yields a `Promise`, which is always truthy — the one mistake in
 this API that silently passes.
 
-```typescript
+```typescript fragment
 // tests/security/Hash.test.ts
 import { Hash } from "zerotal/security";
 

package/docs/errors.md

@@ -123,7 +123,7 @@ export class QuotaExceededError extends HttpError {
 }
 ```
 
-```typescript
+```typescript fragment
 // in a controller
 throw new PaymentFailedError(charge.id);
 ```
@@ -135,7 +135,7 @@ then register it in `bootstrap/app.ts` with `app.withExceptionHandler(Handler)`.
 The framework calls `report()` first, then `render()`, for every unhandled
 exception:
 
-```typescript
+```typescript fragment
 // app/exceptions/Handler.ts
 import { ExceptionHandler, NotFoundError, ForbiddenError } from "zerotal";
 import type { HttpContext } from "zerotal";
@@ -169,7 +169,7 @@ export class Handler extends ExceptionHandler {
 }
 ```
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { Application } from "zerotal";
 import providers from "./providers.ts";
@@ -193,7 +193,7 @@ reach `console.error`.
 To silence your own classes, list them on the `dontReport` array instead of
 filtering by hand:
 
-```typescript
+```typescript fragment
 // app/exceptions/Handler.ts
 import { ExceptionHandler, ForbiddenError } from "zerotal";
 import { PaymentFailedError } from "./PaymentFailedError.ts";
@@ -227,7 +227,7 @@ The validation system throws automatically — you don't catch anything. It thro
 `ValidationJsonError` (a 422 JSON body for API clients), and both flow straight
 through the handler:
 
-```typescript
+```typescript fragment
 // in a controller
 // Browser → 303 redirect back with flashed errors
 // API     → 422 JSON: { message: 'Validation failed', errors: {...} }
@@ -241,7 +241,7 @@ See the [Validator](/docs/validator) guide for details.
 Every `ZerotalError` carries a machine-readable `code` string alongside the HTTP
 `status`. Use it on the client to distinguish errors that share a status:
 
-```typescript
+```typescript fragment
 // the API client receives:
 // { "message": "Payment failed for charge ch_xxx", "code": "E_PAYMENT_FAILED" }
 

package/docs/events.md

@@ -36,7 +36,7 @@ never use framework events to drive business logic.
 If you want the full side-by-side, here it is — but you can skip it and come back
 once you've read the section for the one you need:
 
-|               | Framework events                  | Application events          |
+| Aspect        | Framework events                  | Application events          |
 | ------------- | --------------------------------- | --------------------------- |
 | Purpose       | Observing the framework           | Reacting to your domain     |
 | Who emits     | The framework                     | Your code                   |
@@ -53,8 +53,9 @@ talks through the bus instead.
 
 ### API
 
-```typescript
-import { FrameworkEvents, QueryExecuted } from "zerotal";
+```typescript fragment
+import { FrameworkEvents } from "zerotal";
+import { QueryExecuted } from "@zerotal/orm";
 
 // Subscribe — returns an unsubscribe function.
 const off = FrameworkEvents.on(QueryExecuted, (event) => {
@@ -87,7 +88,7 @@ dispatch a queue job) from outside the handler.
 Subscribe in `onBooted`, keep the unsubscribe functions, and release them in
 `onStopping` so handlers never leak between boots or test suites:
 
-```typescript
+```typescript fragment
 import { ServiceProvider, FrameworkEvents, RequestFailed } from "zerotal";
 
 export class MetricsProvider extends ServiceProvider {
@@ -185,7 +186,7 @@ the emitting packages knowing you exist.
 Some events carry `ctx`; for those that do not (mail/cache/queue happen outside the
 HTTP frame of reference), resolve the current request lazily:
 
-```typescript
+```typescript fragment
 import { FrameworkEvents, RequestContext } from "zerotal";
 import { CacheQueried } from "@zerotal/cache";
 
@@ -204,7 +205,7 @@ app should react to. Events are plain classes; listeners are classes with a
 
 ### Define an event and a listener
 
-```typescript
+```typescript fragment
 // app/events/UserRegistered.ts
 export class UserRegistered {
   constructor(
@@ -227,7 +228,7 @@ export class SendWelcomeEmail {
 
 ### Register and emit
 
-```typescript
+```typescript fragment
 // usually a provider's onBooted(), or bootstrap code
 import { Events } from "zerotal";
 import { UserRegistered } from "./app/events/UserRegistered.ts";
@@ -266,7 +267,7 @@ You usually don't call `Events.on(...)` yourself. A listener placed in `app/list
 declares the event(s) it handles via `static listens`, and the framework binds it on the
 emitter at boot — no registration code required.
 
-```typescript
+```typescript fragment
 // app/listeners/SendWelcomeEmail.ts
 import { UserRegistered } from "../events/UserRegistered.ts";
 
@@ -284,7 +285,7 @@ export class SendWelcomeEmail {
 `static listens` accepts an array — the listener binds to each event and `handle()`
 receives whichever one fired:
 
-```typescript
+```typescript fragment
 // app/listeners/GrantWelcomeBonus.ts
 import { UserRegistered } from "../events/UserRegistered.ts";
 import { UserReactivated } from "../events/UserReactivated.ts";
@@ -309,7 +310,7 @@ job, so `emit()` returns without waiting for the work to finish. Set `queue` to
 the default queue, or to a queue name. Two optional fields tune the retry behaviour of the
 dispatched job:
 
-```typescript
+```typescript fragment
 // app/listeners/SendWelcomeEmail.ts
 import { UserRegistered } from "../events/UserRegistered.ts";
 
@@ -360,7 +361,7 @@ authorization, and the client side.
 
 Both buses expose a reset so one test never leaks subscriptions into the next:
 
-```typescript
+```typescript fragment
 import { Events, FrameworkEvents } from "zerotal";
 
 // Remove every application listener

package/docs/flow/components.md

@@ -7,7 +7,7 @@ description: The component library that ships with Flow — forms, overlays, tab
 
 Flow ships a library of ready-made native components and unstyled headless primitives. All are imported from `@zerotal/flow`.
 
-> **Tip** — See them live: the example app's component gallery at `/pulse/components` (`apps/example/app/flow/ComponentsPage.tsx`) shows every component, and `/pulse/users` (`UsersPage.tsx`) is a realistic admin screen composing them together.
+> **Tip** — See them live: [the component gallery](/showcase/flow/components) shows modals, drawers, tabs and menus driven by a real server, and [the flow-ui kit](/showcase/flow/ui-kit) walks the styled set. The [full catalogue](/docs/components) documents every component with props.
 
 ## Navigation
 
@@ -54,7 +54,7 @@ cached either way.
 
 `data-current` matches by **prefix** — a link to `/posts` stays active on `/posts/42` — which is what you want for a section parent. For an index link that should be active only on its own exact URL (an "Overview" tab that shouldn't light up on the section's sub-pages), add `exact`:
 
-```tsx
+```tsx fragment
 <Link href="/dashboard" exact class="data-[current]:font-bold">
   Overview
 </Link>
@@ -72,7 +72,7 @@ Some links aren't really going anywhere, though: a sort header, a filter chip, a
 tab strip partway down a long page. Jumping to the top for those loses the
 control the user was just looking at. `preserveScroll` leaves the viewport alone:
 
-```tsx
+```tsx fragment
 <Link href={this.currentUrl({ query: { sort: "title" } })} preserveScroll>
   Title
 </Link>
@@ -101,7 +101,7 @@ import { Head } from "@zerotal/flow";
 
 Shorthand for `<Head><title>…</title></Head>`. Supports interpolation:
 
-```tsx
+```tsx fragment
 import { Title } from "@zerotal/flow";
 
 <Title>{`${this.unreadCount} unread — Inbox`}</Title>;
@@ -113,7 +113,7 @@ import { Title } from "@zerotal/flow";
 
 Preserve an element — and its live state (a playing `<audio>`, an embedded widget) — across `navigate` page visits. Give it a stable `name`; on navigation the bridge re-uses the existing DOM node instead of replacing it. Best placed in your layout:
 
-```tsx
+```tsx fragment
 import { Persist } from "@zerotal/flow";
 
 {
@@ -132,7 +132,7 @@ Elements inside `<Persist>` also survive server-patch morphs (they carry `flow:i
 
 A dialog that bundles reactive visibility, a backdrop, a panel, a transition, a close button, and Escape-to-close — all wired to one boolean prop. Clicking the backdrop, the × button, or pressing Escape sets that prop back to `false`:
 
-```tsx
+```tsx fragment
 import { Modal } from "@zerotal/flow";
 
 export class ContactsPage extends Component {
@@ -175,7 +175,7 @@ export class ContactsPage extends Component {
 
 A slide-over panel — the edge-anchored sibling of `<Modal>`. Same binding and close model (backdrop, × and Escape all close it client-side with no round-trip; focus-trapped), but slides in from an edge:
 
-```tsx
+```tsx fragment
 import { Drawer } from "@zerotal/flow";
 
 <button onClick={() => (this.cartOpen = true)}>Cart ({this.cartCount})</button>
@@ -219,7 +219,7 @@ Levels `success` / `error` / `warning` / `info` map to distinct colors. Click a
 
 A dismissible inline alert. `variant` sets the palette and ARIA role (error/warning announce assertively). Dismissal is client-only — no round-trip:
 
-```tsx
+```tsx fragment
 import { Alert } from "@zerotal/flow";
 
 <Alert variant="success" dismissible>
@@ -237,7 +237,7 @@ import { Alert } from "@zerotal/flow";
 
 Shows its children only while a server action is in flight — and, so a fast action never flashes a spinner, loading **indicators wait out a short delay** (~200ms) by default: an action that finishes inside that window shows nothing at all. This applies to the whole loading family — `<Loading>`, `showOnLoading`, `hideOnLoading`, and `loadingClass`. Only `loadingAttr` (e.g. `loadingAttr="disabled"`) is applied immediately, so a submit button still guards against a double-click even on a sub-100ms action. The `delay` prop is now the default behaviour and kept only for clarity/back-compat:
 
-```tsx
+```tsx fragment
 import { Loading } from "@zerotal/flow";
 
 <button onClick={this.save}>Save</button>
@@ -262,7 +262,7 @@ import { Loading } from "@zerotal/flow";
 
 Renders the component's entire validation error bag as a list. Hidden when there are none:
 
-```tsx
+```tsx fragment
 import { Errors } from "@zerotal/flow";
 
 <Errors />                              {/* every current error */}
@@ -273,7 +273,7 @@ import { Errors } from "@zerotal/flow";
 
 A single field's first error message as a self-hiding `<span>`. Equivalent to `<span error={this.errors.field} />`:
 
-```tsx
+```tsx fragment
 import { ErrorMessage } from "@zerotal/flow";
 
 <input value={this.form.email} />
@@ -286,7 +286,7 @@ Contains a failure in a nested component so it costs that component rather than
 one, a child that throws while mounting or rendering takes the whole response with it — one broken
 widget blanks the dashboard.
 
-```tsx
+```tsx fragment
 import { ErrorBoundary } from "@zerotal/flow";
 
 <ErrorBoundary fallback={<p class="text-sm text-red-600">Sales data unavailable.</p>}>
@@ -297,7 +297,7 @@ import { ErrorBoundary } from "@zerotal/flow";
 `fallback` may be a function, which receives the thrown error. `onError` reports it (for logging or
 an error tracker) without changing what renders:
 
-```tsx
+```tsx fragment
 <ErrorBoundary fallback={(e) => <p>{(e as Error).message}</p>} onError={(e) => Log.error(e)}>
   <RiskyWidget />
 </ErrorBoundary>
@@ -317,7 +317,7 @@ affect the other.
 
 A data table with URL-driven sortable headers. Clicking a sortable header navigates to `?sortBy=key&sortDir=asc|desc`. Pair with `@url sortBy`/`@url sortDir` and sort the rows server-side in `render()`:
 
-```tsx
+```tsx fragment
 import { Table, Pager } from "@zerotal/flow";
 
 export class UsersPage extends Component.using(Pagination) {
@@ -362,7 +362,7 @@ export class UsersPage extends Component.using(Pagination) {
 
 Renders a Prev / numbered / Next pager from either paginator — `Model.paginate()` or the in-memory `paginate()` helper. Links are `navigate` anchors to `?page=N`, so they pair with `@url page` automatically. (The `Pagination` export is the page-state mixin; `<Pager>` is the links UI.)
 
-```tsx
+```tsx fragment
 import { Pager } from "@zerotal/flow";
 
 const users = await User.paginate(this.perPage);
@@ -375,7 +375,7 @@ const users = await User.paginate(this.perPage);
 
 A sentinel element that calls a server action when it scrolls into view. Pass `show` to stop loading when there are no more items:
 
-```tsx
+```tsx fragment
 import { InfiniteScroll } from "@zerotal/flow";
 
 @expose async loadMore(): Promise<void> {
@@ -396,7 +396,7 @@ elements; spacers above and below hold the scrollbar at the size the full collec
 As the viewport moves, `onWindow` is called with `(start, count)` and your action loads that slice.
 The collection never has to reach the client in full.
 
-```tsx
+```tsx fragment
 import { Virtualize } from "@zerotal/flow";
 
 @expose rows: Row[] = [];
@@ -440,7 +440,7 @@ fetch latency.
 
 A click-to-open menu, entirely client-side (no round-trip). Fully keyboard-navigable: Down/Up/Enter opens (focusing first/last item), arrow keys + Home/End move between items, Escape closes and returns focus to the trigger, click-outside dismisses:
 
-```tsx
+```tsx fragment
 import { Dropdown } from "@zerotal/flow";
 
 <Dropdown label="Options" align="right">
@@ -457,7 +457,7 @@ import { Dropdown } from "@zerotal/flow";
 
 Client-side tabbed panels. Pass `items`, each with a `label` and the `content` to show when selected:
 
-```tsx
+```tsx fragment
 import { Tabs } from "@zerotal/flow";
 
 <Tabs
@@ -485,7 +485,7 @@ import { Tabs } from "@zerotal/flow";
 
 A dropzone bound to an `@expose` property. Choosing a file POSTs the bytes to `/__flow/upload` over HTTP, shows live upload progress, and resolves to a signed `TemporaryUploadedFile` reference. Compose the `FileUploads` mixin for the `removeUpload` action:
 
-```tsx
+```tsx fragment
 import { Component, expose, FileUpload, FileUploads, TemporaryUploadedFile } from "@zerotal/flow";
 
 export class AvatarPage extends Component.using(FileUploads) {
@@ -525,7 +525,7 @@ export class AvatarPage extends Component.using(FileUploads) {
 
 For multiple files, use `multiple`:
 
-```tsx
+```tsx fragment
 @expose photos: TemporaryUploadedFile[] = [];
 
 <FileUpload bind={this.photos} multiple accept="image/*" />
@@ -538,7 +538,7 @@ For multiple files, use `multiple`:
 
 Common Alpine plugins are bundled and exposed as props:
 
-```tsx
+```tsx fragment
 {/* Input masking */}
 <input mask="(999) 999-9999" value={this.phone} live />
 <input mask="9999 9999 9999 9999" value={this.cardNumber} live />
@@ -576,7 +576,7 @@ Unstyled, fully accessible interactive primitives that expose state through `dat
 
 An accessible on/off toggle (`role="switch"`, keyboard-operable). Style the on-state with `data-[checked]:…`:
 
-```tsx
+```tsx fragment
 import { Switch } from "@zerotal/flow";
 
 <Switch
@@ -593,7 +593,7 @@ The Switch button is a Tailwind `group`, so the inner knob reacts with `group-da
 
 An accessible checkbox (`role="checkbox"`) bound to a boolean. Style the checked state with `data-[checked]:…`:
 
-```tsx
+```tsx fragment
 import { Checkbox } from "@zerotal/flow";
 
 <Checkbox bind={this.agree} class="h-5 w-5 rounded border border-gray-700 data-[checked]:bg-indigo-600 data-[checked]:border-indigo-600">
@@ -608,7 +608,7 @@ import { Checkbox } from "@zerotal/flow";
 
 A styled native `<select>`. Fully accessible out of the box. Use `<Listbox>` only when you need custom option markup:
 
-```tsx
+```tsx fragment
 import { Select } from "@zerotal/flow";
 
 <Select
@@ -627,7 +627,7 @@ import { Select } from "@zerotal/flow";
 
 `role="radiogroup"` with arrow-key roving. Style the selected option with `data-[checked]:…`:
 
-```tsx
+```tsx fragment
 import { RadioGroup } from "@zerotal/flow";
 
 <RadioGroup
@@ -645,7 +645,7 @@ import { RadioGroup } from "@zerotal/flow";
 
 A fully keyboard-navigable custom select. Arrow keys, Home/End, Enter/Escape, `aria-activedescendant`. `multiple` makes the value an array:
 
-```tsx
+```tsx fragment
 import { Listbox } from "@zerotal/flow";
 
 <Listbox
@@ -662,7 +662,7 @@ States: `data-[selected]`, `data-[active]`, `data-[open]`.
 
 An autocomplete input + filtered dropdown list. Two modes:
 
-```tsx
+```tsx fragment
 import { Combobox } from "@zerotal/flow";
 
 {
@@ -744,7 +744,7 @@ import { Popover } from "@zerotal/flow";
 
 Accessibility glue around a single control. `<Field>` wires `for` / `id` / `aria-describedby` between the label, the control, the description, and the error — keeping screen-reader semantics correct without hand-wiring IDs:
 
-```tsx
+```tsx fragment
 import { Field } from "@zerotal/flow";
 
 <Field label="Email" description="We'll never share it." error={this.errors.email}>
@@ -758,7 +758,7 @@ All three props (`label`, `description`, `error`) are optional. You can also com
 
 Group related fields. A native `<fieldset disabled>` cascades the disabled state to every control inside:
 
-```tsx
+```tsx fragment
 import { Fieldset } from "@zerotal/flow";
 
 <Fieldset legend="Billing address" disabled={this.saving}>
@@ -775,7 +775,7 @@ import { Fieldset } from "@zerotal/flow";
 
 Shows `content` on hover/focus of its children, wired with `aria-describedby` and `role="tooltip"`. Client-only:
 
-```tsx
+```tsx fragment
 import { Tooltip } from "@zerotal/flow";
 
 <Tooltip content="Copy link to clipboard" placement="top">
@@ -825,7 +825,7 @@ ZT_FLOW_CSP_SAFE=true
 
 When on, the client runtime swaps Alpine's evaluator for an eval-free interpreter, the bridge avoids `new Function`, and the AOT compiler emits only CSP-safe expressions:
 
-```tsx
+```tsx fragment
 <button onClick={() => this.count++}>+</button>
 // standard mode → flow:click="() => $flow.count++"
 // CSP mode      → flow:click="$flow.count++"