@hozu/cli 0.24.0 → 0.25.0

package/skill/topics/pages.md

@@ -66,4 +66,6 @@ export default project({
 - A detail view: `ui.view({ route: itemPage, render: ({ params }) => ui.query(getItem, { id: params.id }, { ready,
   failed: { NotFound: () => ui.p({}, ['Not found']), Unexpected: () => … } }) })`.
 - A page loads JS only when a machine-bound part renders on it (`hozu plan <route or path>`). Every link loads a document;
-  state across pages lives in the URL (`seed`), on the server (queries) or in a client component's own storage.
+  a machine whose view both pages show (or the same address) resumes its calm state, the last state without `invoke`,
+  from `sessionStorage`; a reload or a page without that view starts from `initialContext` (or `seed`). What must
+  survive a reload lives in the URL (`seed`), on the server (queries) or in a client component's own storage.

package/skill/topics/patterns.md

@@ -3,9 +3,9 @@
 The controls are plain elements; in an app with a kit, use its components (`ui.use(Button, …)`,
 `hozu docs components`).
 
-- **Busy state:** render every control once; the state with `invoke` drops repeated submits. Progress:
-  `when(['adding'], [ui.p({ 'aria-busy': 'true' }, ['Saving…'])])`. Do not duplicate controls under `when`.
-- **Optimistic item:** `when(['adding'], [ui.li({ class: 'opacity-50' }, [ctx.draft])])`; leaving the state removes it
+- **Busy state:** render every control once and disable it: `disabled: is(['adding'])` (`invoke` drops repeats).
+  Progress: `is(['adding']) && ui.p({ 'aria-busy': 'true' }, ['Saving…'])`.
+- **Optimistic item:** `is(['adding']) && ui.li({ class: 'opacity-50' }, [ctx.draft])`; leaving the state removes it
   and the refreshed query shows the real item.
 - **Refresh after a mutation:** tag the query, list the tag in the mutation's `invalidates`.
 - **Go to what was just created:** `done: { target: 'idle', navigate: (r) => ui.link(itemPage, { id: r.id }) }`.
@@ -82,6 +82,7 @@ ui.each(items, 'id', (item) => ui.li({}, [ui.input({ type: 'checkbox', form: bul
   `ui.each(ctx.cursors, null, (cursor) => ui.query(listPage, { cursor }, { ready: (page) => … }))`; on the last page
   (`cursor === ctx.last && page.next !== null`) a sentinel `on: { visible: ui.send(More, { cursor: page.next }) }`;
   `More` pushes the cursor, guarded by `e.cursor !== null && e.cursor !== ctx.last`.
-- **A link starts the page again:** every internal link is a document navigation, so a machine's context starts
-  from `initialContext` (or `seed`). Keep what must survive in the URL: put both filters in `search` and `seed` the
-  context from it, instead of one in the URL and one in context.
+- **What a link keeps:** every internal link loads a document. A machine whose view both pages show (or the same
+  address) resumes its calm state, the last state without `invoke`, from `sessionStorage`; a reload or a page
+  without that view starts from `initialContext` (or `seed`). Keep what must survive a reload or a shared link in
+  the URL: put both filters in `search` and `seed` the context from it, not one in the URL and one in context.

package/skill/topics/recipes.md

@@ -20,8 +20,8 @@ The list is the visitor's own: it lives in their browser, so two visitors never
 - **feature.ts:** `fetch: new URL('./fetch.ts', import.meta.url)`; `app.ts`: `components: bundleComponents`.
 - **Data about the items** (quotes, prices) is public: a `runs: 'server'` (or `'either'`) query inside the list's
   `ready` branch, `ui.query(quotes, { symbols }, …)`.
-- Refresh controls (Pause / Resume / Refresh now): states `live` / `paused`, `refresh: () => [quotesTag()]` on
-  `RefreshNow` and on `live`'s `after: [{ ms: 30_000, target: 'live', … }]`; adds return with `done: 'previous'`.
+- Pause / Resume / Refresh now: `paused` is a context field (a mode), `refresh: () => [quotesTag()]` on
+  `RefreshNow`, on `Resume` (`target: 'idle'` restarts the timer) and on the guarded `after` (`hozu docs machine`).
 - **Ask the server before saving** (normalize "2330" to "2330.TW"): a `runs: 'server'` query `resolveSymbol`, then
   the browser mutation: `looking: { invoke: invoke(resolveSymbol, { input: { q: ctx.symbol }, done: { target:
   'saving', assign: (r) => { ctx.symbol = r.symbol } }, failed: { … target: 'previous' } }) }`, `saving: { invoke:
@@ -89,8 +89,16 @@ const staffHead = { query: me, render: (m) => ({ title: `${m.name} · Admin` }),
 const staff = (route, View) => ui.page(route, { views: [Sidebar, View], head: staffHead })
 export default project({ /* … */ pages: [staff(orders, OrderList), staff(orderDetail, OrderPage), …] })
 ```
-The sidebar marks its sections with `current(route)` from its render:
-`'aria-current': current(orders) || current(orderDetail)`, styled `aria-[current]:font-bold`.
+The sidebar marks its sections with `current(route)` from its render, one line per section:
+```ts
+render: ({ current }) => ui.nav({}, [
+  ...[
+    [orders, 'Orders', current(orders) || current(orderDetail)],
+    [customers, 'Customers', current(customers) || current(customer)],
+  ].map(([r, label, here]) => ui.a({ href: ui.link(r, null), 'aria-current': here, class: 'aria-[current]:font-bold' }, [label])),
+])
+```
+A store's categories: `current(shop, { category: c })` over a constant list of categories.
 
 ## Screens with different state
 One machine per feature: an order list (filters, selection) and an order page (shipping, refund) are two features,
@@ -99,8 +107,9 @@ One machine per feature: an order list (filters, selection) and an order page (s
 ## A multi-step checkout that also works without JavaScript
 Each step is a state and each step's form posts only its own fields: after a native post the server renders the next
 step, and every form on that page carries the machine's state in a signed hidden field, so the next post continues
-from it (going back to edit a step too). Prefill from the member with
-`seed: ({ query }) => ({ email: query(me, {}).email })`.
+from it (going back to edit a step too; the field is `__hozu_state`, sealed with `SESSION_SECRET`). Prefill from
+the member on the view that has both `machine` and `route` (HZ048):
+`ui.view({ machine: checkout, route: checkoutPage, seed: ({ query }) => ({ email: query(me, {}).email }), render })`.
 
 ## A notice after saving
 A `notice` context field set in `done` and cleared by `after: [{ ms: 4000, target: 'idle' }]` on a `saved` state;

package/skill/topics/testing.md

@@ -80,6 +80,13 @@
     `--select <css>`, `--screenshot shot.png` (after the steps), `--viewport 390x844` (a phone; default 1280x800) and
     `--reduced-motion`.
   - It also prints the client components on the page (mounted, failed, size, canvases).
+- **More checks in a step:**
+  - A click that would land on another element fails the step: `the click would land on <h3>, which contains it, above
+    <a href="/x">: a person cannot click it` (an overlay, a card covering its link).
+  - A navigation shows how it arrived: `→ /x (loaded, 32 ms)` or `(prerendered, 4 ms)`; with `--js both`, per mode.
+  - `--select` prints each element's `class` too. An element moved to another parent is not a flash.
+- A server error that `get` or `browse` lists is noted once with `a production server shows "Internal error" here`:
+  the visitor sees that text and the call id; `onError` gets the message.
 - **`testApp`:** `app` is the default export of `app.ts`; `.post(path, fields)` submits a native form, with fields as
   a record or as `[name, value]` pairs for repeated names. `testApp(app, { session: store })` may swap only the
   session store (a test issuer). `testApp` reads no env files: pass `testApp(app, { env: process.env })` (or a record)

package/skill/topics/views.md

@@ -2,10 +2,10 @@
 
 ```ts
 export const Board = ui.view({
-  machine: m,        // optional: without it, no ctx / when / events, and 0 JS
+  machine: m,        // optional: without it, no ctx / is / events, and 0 JS
   route: home,       // optional: render gets { params, search } typed by the route
   seed: ({ search }) => ({ q: search.q }),   // optional, with machine + route: context fields from the URL
-  render: ({ ctx, when, is, params, search, locale }) => ui.main({ class: 'mx-auto max-w-xl' }, [ /* children */ ]),
+  render: ({ ctx, is, current, params, search, locale }) => ui.main({ class: 'mx-auto max-w-xl' }, [ /* children */ ]),
 })
 ```
 - **Elements:** `ui.<tag>(attrs, children)` for every HTML and SVG element; void tags (`input`, `img`) take only attrs.
@@ -13,10 +13,10 @@ export const Board = ui.view({
 - **Classes:** `class` is a static string of Tailwind classes that must exist (HZ026); conditional classes:
   `toggle: { 'bg-indigo-600 text-white': ctx.tab === t }`. No `style`.
 - **Conditions:** `ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error])`, `item.done ? 'done' : 'open'`.
-  By machine state: `is(['paused']) ? resume : pause`, `!is(['idle']) && ui.p({}, ['Saving…'])`,
-  `disabled: is(['saving'])` (keep a control and disable it rather than hide it while busy: no flash).
-- **Dialogs, popovers, menus:** native, no machine state: `ui.button({ commandfor: 'd', command: 'show-modal' })` +
-  `ui.dialog({ id: 'd', closedby: 'any' }, [...])`, `popover` / `popovertarget`, `ui.details`.
+  By machine state: `!is(['idle']) && ui.p({}, ['Saving…'])`,
+  `disabled: is(['saving'])` (disable a control while busy, not hide it: it stays put).
+- **Dialogs, popovers, menus:** native (bound to the machine: --more): `ui.button({ commandfor: 'd', command:
+  'show-modal' })` + `ui.dialog({ id: 'd', closedby: 'any' }, [...])`, `popover` / `popovertarget`, `ui.details`.
 - **Lists:** `ui.each(items, 'id', (item) => ui.li({}, [item.title]))`. Never `.map` over data.
 - **Numbers and dates:** `ui.format.number(q.price, { style: 'currency', currency: 'USD' })`, `ui.format.date(x,
   { dateStyle: 'medium' })`, `ui.format.relative(n, 'day')`, `ui.format.list(xs)` (Intl, the page's locale).
@@ -33,7 +33,10 @@ export const Board = ui.view({
 <!-- more -->
 
 - **Motion:** what an update adds fades in by itself (not with reduced motion); a view two pages show stays still
-  across a page change. `hozu browse` reports a flash or a layout shift: fix those.
+  across a page change. `hozu browse` reports a flash or a layout shift: fix those. `c ? a : b` whose branches are
+  one element of the same tag and shape (`ctx.paused ? resumeButton : pauseButton`) keeps the element: its text,
+  classes, attributes and listener follow `c`, and focus stays (not when a differing value computes, such as a `fn`
+  or a template string, or links elsewhere).
 - **Attributes:** HTML names in lower case (`for`, `minlength`, `aria-pressed`, `data-x`), typed per tag. Values are
   literals or data: `'aria-pressed': ctx.show === 'all'`, `title: ctx.error ?? 'OK'`.
 - **Sizes and colours from data:** `vars` with an arbitrary-value class: `class: 'w-[calc(var(--pct)*1%)]'`,
@@ -42,7 +45,9 @@ export const Board = ui.view({
   (runs on the server, and in the browser inside an island).
 - **More conditions:** `list.length === 0 ? ui.p({}, ['Empty']) : ui.ul({}, [...])`; a `?:` / `&&` branch may be a list:
   `open ? [a, b] : null`. A query branch or an each item returns one node: wrap several in an element (HZ014).
-  With an enter/leave animation: `ui.if(cond, [then], [else], 'fade')` (the motion name is required).
+  With an enter/leave animation (only then): `ui.if(cond, [then], [else], 'fade')`, by machine state
+  `when(['saving'], [children], 'fade')`, and list rows `ui.each(items, 'id', row, 'fade')` (the motion name is
+  required; without a motion, `is([...]) && …`).
 - **More lists:** `ui.each(tags, null, (t) => …)` for primitives. `.map` only over constants:
   `['a', 'b'].map((k) => ui.option({ value: k }, [k]))`.
 - **Text:** template strings work: `` `${n} items` ``.
@@ -50,27 +55,34 @@ export const Board = ui.view({
   `row(item)`; it is inlined, so the IR equals the inline form. A plain function that receives data is HZ059.
 - **Shared UI:** use the kit component, not a styled `ui.button` per page (`example/` uses a kit).
 - **More events:** any DOM event name plus `visible` (entered the viewport). Payload fields also:
-  `ui.dom.formAll('name')`, `ui.dom.checked`, `ui.dom.valueAsNumber`, `ui.dom.key`. `ui.dom.value` / `ui.dom.form`
+  `ui.dom.formAll('name')`, `ui.dom.checked`, `ui.dom.valueAsNumber`, `ui.dom.key`. Keyboard shortcuts:
+  `ui.window({ on: { keydown: ui.send(Open, {}, { keys: ['Mod+k', '/'] }) } })` sends only on those presses and
+  stops the browser's own (`Mod` is ⌘ on Apple, Ctrl elsewhere; also `Ctrl`, `Meta`, `Alt`, `Shift`); a printable
+  key without a modifier waits while the person types in a field (`Escape` does not). `ui.dom.value` / `ui.dom.form`
   fill an enum field only from a `<select>`, radios or submit buttons whose literal values are all members (HZ033).
 - **Search in links:** the third argument of `ui.link` is optional and exists only when the route declares `search`:
   omitted means every default, and a search lists only the fields that differ: `ui.link(home, null, { show: 'done' })`.
 - **More data:** `pending: ui.p({}, ['Loading…'])` is optional; a branch may return `null` to render nothing.
   Server-fetched data is sent with the page and never fetched again; after a mutation, queries whose tags it
-  invalidates refresh in place.
+  invalidates refresh in place. 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.
 - **From Vue or React:** `computed` → a `fn`; `ref` + `@click` → a context field + `ui.set`; `v-if` → `?:` / `&&`
-  (with `is([...])` for a machine state); `v-for` + `:key` → `ui.each(list, 'id', …)`; `setInterval` → `after` with
-  `refresh` (`hozu docs machine`); `watch` → a transition's `assign`; DOM libraries (charts, maps) → a client component
+  (with `is([...])` for a machine state); `v-for` + `:key` → `ui.each(list, 'id', …)`; `setInterval` → `freshness: { poll: s }`
+  for data that changes on its own (`hozu docs data`), `after` with `refresh` for a refresh the visitor pauses
+  (`hozu docs machine`); `watch` → a transition's `assign`; DOM libraries (charts, maps) → a client component
   (`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 address shown gets `aria-current="page"`. Which links mark a section is yours to say: the render's
   `current(route)` is true on that route's pages, so a menu writes
   `ui.a({ href: ui.link(orders, null), 'aria-current': current(orders) || current(orderDetail) }, ['Orders'])` and
   styles `aria-[current]:font-bold`: `true` is written `"page"` on the address itself, `false` writes nothing.
+  `current(shop, { category: 'apparel' })` also compares those params (search is ignored). A menu is a constant
+  list mapped to links, one line per section:
+  `...[[orders, 'Orders'], [customers, 'Customers']].map(([r, label]) => ui.a({ href: ui.link(r, null),
+  'aria-current': current(r) }, [label]))`; `current(a) || current(b)` works there too.
 - `ui.dialog({ open: is(['editing']), on: { close: ui.send(Cancel, {}) } }, [...])` opens as a modal and closes with
   the machine; Escape sends `close`. It needs JavaScript: a dialog that must open without it uses the native
   `commandfor` button (the short form) and closes when the data that shows it changes.