@hozu/cli 0.21.0 → 0.22.0

package/skill/topics/patterns.md

@@ -20,8 +20,8 @@ ui.form({ on: { submit: ui.send(Toggle, { id: ui.dom.form('id') }) } }, [
 ```
 - **Filter in the URL** (shareable, no JS): `search` on the route, options as
   `ui.a({ href: ui.link(home, null, { show: s.value }), 'aria-current': search.show === s.value }, [s.label])`.
-- **Filter as you type, empty state:** context `search: z.string()`, `on: { input: ui.send(Search, { text:
-  ui.dom.value }) }`, filter and test emptiness with a `fn` (see --more).
+- **Filter as you type, empty state:** context `search: z.string()`, `on: { input: ui.set(ctx.search, ui.dom.value)
+  }`, filter and test emptiness with a `fn` (see --more).
 - **Detail page with a 404:** `hozu docs pages`.
 
 <!-- more -->
@@ -42,10 +42,10 @@ isEmpty({ items, show: ctx.show })
   : ui.ul({}, [ui.each(visible({ items, show: ctx.show }), 'id', (i) => ui.li({}, [i.title]))])
 ```
 - **Search as you type:** context `search: z.string()`; `ui.input({ type: 'search', 'aria-label': 'Search', value:
-  ctx.search, on: { input: ui.send(Search, { text: ui.dom.value }) } })`; `on(Search, { target: 'idle', assign: (e) =>
-  { ctx.search = e.text } })`; filter with a `fn({ input: z.object({ items, text: z.string() }), … })`.
+  ctx.search, on: { input: ui.set(ctx.search, ui.dom.value) } })`; filter with a
+  `fn({ input: z.object({ items, text: z.string() }), … })`.
 - **Toggle buttons:** for each option of a constant list,
-  `ui.button({ type: 'button', 'aria-pressed': ctx.show === s.value, on: { click: ui.send(SetShow, { show: s.value }) } }, [s.label])`.
+  `ui.button({ type: 'button', 'aria-pressed': ctx.show === s.value, on: { click: ui.set(ctx.show, s.value) } }, [s.label])`.
 - **In the URL and as you type** (`/?q=park` is a link to share, typing filters live): seed the machine from the URL,
   read only the context, and write the address back with `replace` on the typing transition
   (`replace: () => ui.link(home, null, { q: ctx.q })`). A GET form with `name="q"` sets it without JS.
@@ -55,9 +55,10 @@ export const Board = ui.view({ machine: m, route: home, seed: ({ search }) => ({
     ui.input({ type: 'search', name: 'q', 'aria-label': 'Search', value: ctx.q, on: { input: ui.send(Search, { q: ui.dom.value }) } }),
     /* … */ ui.each(visible({ items, q: ctx.q, district: ctx.district }), 'id', (s) => …) ]) })
 ```
-- **A mode with shared controls** (a tour, an edit mode): put what every mode handles the same way in
-  `machine({ on: [on(Search, { assign: (e) => { ctx.q = e.q } })] })` (no `target`: stays in its state); each state
-  lists only what differs.
+- **A mode with shared controls** (a tour, an edit mode): a `ui.set` already works in every state without `invoke`;
+  put other transitions every mode handles the same way in
+  `machine({ on: [on(Search, { assign: (e) => { ctx.q = e.q; ctx.page = 1 } })] })` (no `target`: stays in its
+  state); each state lists only what differs.
 - **Select many, then act** (bulk delete): checkboxes in the list join one form through a formRef; the invoke
   state drops events, so the checkboxes are disabled while it runs:
 ```ts

package/skill/topics/recipes.md

@@ -81,3 +81,25 @@ Run a fresh scaffold into a scratch app with `--with detail`, and copy the parts
 - Following the system needs no code: Tailwind's `dark:` classes (`bg-white dark:bg-slate-900`).
 - A switch the visitor chooses: a client component (`hozu docs components`) puts `dark` on `<html>` and keeps the
   choice in `localStorage`; `app.css` adds `@custom-variant dark (&:where(.dark, .dark *));`.
+
+## A shell shared by many pages (a back office)
+Pages are config, so a helper is the layout:
+```ts
+const staffHead = { query: me, render: (m) => ({ title: `${m.name} · Admin` }), failed: { Forbidden: signIn } }
+const staff = (route, View) => ui.page(route, { views: [Sidebar, View], head: staffHead })
+export default project({ /* … */ pages: [staff(orders, OrderList), staff(orderDetail, OrderPage), …] })
+```
+The sidebar's links mark the page shown with `aria-current` by themselves (`aria-[current]:font-bold`).
+
+## Screens with different state
+One machine per feature: an order list (filters, selection) and an order page (shipping, refund) are two features,
+`orders` and `order`, sharing declarations through `exports`. Each machine stays small and its contracts few.
+
+## A multi-step checkout that also works without JavaScript
+Each step is a state; the server runs the machine per request, so without JS a step's form posts every earlier field
+again as hidden inputs (`ui.input({ type: 'hidden', name: 'line1', value: ctx.line1 })`), and the last step's
+mutation receives them all. Prefill from the member with `seed: ({ query }) => ({ email: query(me, {}).email })`.
+
+## A notice after saving
+A `notice` context field set in `done` and cleared by `after: [{ ms: 4000, target: 'idle' }]` on a `saved` state;
+the view shows `ctx.notice !== null && ui.p({ role: 'status' }, [ctx.notice])`. There is no global toast store.

package/skill/topics/testing.md

@@ -7,8 +7,8 @@
   `hozu call api.who --input '{"room":"a"}' --header 'Authorization: Bearer t'` (a POST needs `--write`).
 - **Drive the app in a real browser, still without a server:**
   `hozu browse / --session '{"user":"ada"}' --do 'fill New note=Milk' --do 'press Enter' --do 'click Pin in "Milk"'`.
-  - Steps: `fill <label>=<value>`, `select <label>=<option>`, `check` / `uncheck <label>`, `click <name>`,
-    `submit "<form>"`, `press <key>`, `wait <ms>`, `goto <path>`, `post <path> a=1&b=2`,
+  - Steps: `fill <label>=<value>` (`\n`, `\t` work), `select <label>=<option>`, `check` / `uncheck <label>`,
+    `click <name>`, `submit "<form>"`, `press <key>`, `wait <ms>`, `goto <path>`, `post <path> a=1&b=2`,
     `remember <name> from url|<selector> [@attr]` (later steps read `$name`); a target may end with `in "<text>"`
     (for fill and select, before or after `=value`).
   - Labels are what `hozu get <page> --forms` lists; a missing one prints `Did you mean "…"?`. One `--do` may hold
@@ -29,8 +29,12 @@
 
 <!-- more -->
 
-- **A calm page:** a step that rebuilds elements unchanged says `N elements rebuilt unchanged (a flash)` (a control
-  hidden while busy: disable it instead), and layout that moves without input says `layout shift X`. Both are
+- **Server errors:** what the app's `onError` receives (a resolver that threw, an invalid input) is listed under the
+  step or the `get` request that caused it, `server error: <message> (<feature.effect>)`; `--json` `serverErrors`.
+- **A calm page:** a step that rebuilds elements unchanged says `N elements rebuilt unchanged (a flash: main > form >
+  button[type=submit])`, naming up to five (`--json` `flashes.elements` has all; a control hidden while busy: disable
+  it instead). Equal means tag, class, text, `name`, `id`, `href`, `src`, `type` and parent path; a node that moved is
+  no flash. Layout that moves without input says `layout shift X`. Both are
   problems to fix; a calm step prints neither. An address changed with `replace` stays `in place`.
 - **`hozu get`** prints the status, redirect, `set-cookie` attributes (`HttpOnly`, `SameSite`), title, alerts and
   visible text.

package/skill/topics/views.md

@@ -23,10 +23,10 @@ export const Board = ui.view({
 - **Events:** `on: { click: ui.send(Event, payload) }`; payload fields are literals, data, `ui.dom.value`,
   `ui.dom.form('name')` (submit; `hozu docs forms`). A control that only sets a context field:
   `on: { click: ui.set(ctx.open, !ctx.open) }`, `on: { input: ui.set(ctx.q, ui.dom.value) }` (no event to declare).
-- **Links:** `ui.a({ href: ui.link(itemPage, { id: item.id }) }, [...])`; never a string path (HZ032).
+- **Links:** `ui.a({ href: ui.link(itemPage, { id: item.id }) }, [...])`; never a string path (HZ032). Menus,
+  dialogs, plurals: --more.
 - **Data:** `ui.query(listItems, input, { ready: (items) => …, failed: { NotFound: () => …, Unexpected: () => … } })`;
-  `failed` lists every declared error plus `Unexpected`. When the input changes, the rows stay (`aria-busy` on the
-  parent) and update by key; `pending` shows only before the first answer.
+  `failed` lists every declared error plus `Unexpected`.
 - **Shared UI** (buttons, inputs, fields): `ui.use(Button, { variant, props, on }, ['Save'])` of a kit component
   (`hozu docs components`).
 
@@ -63,3 +63,13 @@ export const Board = ui.view({
   (`hozu docs components`; `examples/showcase` has a Chart.js one).
 - **Also:** `ui.html(post.html)` (trusted HTML from query data only, HZ030), `ui.asset(new URL('./x.png',
   import.meta.url))`, `ui.window({ on })` / `ui.document({ on })`, `ui.embed(OtherView)`.
+
+## Menus, dialogs, counting
+- When a query's input changes, the rows stay (`aria-busy` on the parent) and update by key; `pending` shows only
+  before the first answer.
+- A link to the page shown gets `aria-current="page"` (`"true"` for its section): `aria-[current]:font-bold`.
+- `ui.dialog({ open: is(['editing']), on: { close: ui.send(Cancel, {}) } }, [...])` opens as a modal and closes with
+  the machine; Escape sends `close`.
+- `ui.format.plural(n, { one: '# item', other: '# items' })` picks the case for the page's language (`=0` works).
+- `null` and `false` render nothing, also inside a constant list:
+  `ui.ul({}, [...kinds.map((k) => (k === 'draft' ? null : ui.li({}, [k])))])`.