create-hozu 0.7.0 → 0.9.0

package/skill/topics/views.md

@@ -15,18 +15,21 @@ 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 }`. CSS variables: `vars: { '--hue': item.hue }`. No `style`.
 - **Conditions:** `ctx.error !== null && ui.p({ role: 'alert' }, [ctx.error])`, `item.done ? 'done' : 'open'`,
-  `list.length === 0 ? ui.p({}, ['Empty']) : ui.ul({}, [...])`. With an enter/leave animation:
-  `ui.if(cond, [then], [else], 'fade')`.
+  `list.length === 0 ? ui.p({}, ['Empty']) : ui.ul({}, [...])`; a branch may be a list: `open ? [a, b] : null`, also as what a query branch or an each item returns.
+  With an enter/leave animation: `ui.if(cond, [then], [else], 'fade')` (the motion name is required).
 - **By machine state:** `when(['adding', 'saving'], [ui.p({}, ['Saving…'])])`.
 - **Lists:** `ui.each(items, 'id', (item) => ui.li({}, [item.title]))`; `ui.each(tags, null, (t) => …)` for primitives.
   Never `.map` over data (only over constants: `['a', 'b'].map((k) => ui.option({ value: k }, [k]))`).
 - **Text:** template strings work: `` `${n} items` ``.
+- **Reuse:** `export const row = part((item: Item) => ui.li({}, [item.done ? 'Done' : item.title]))`, called as
+  `row(item)`; it is inlined, so the IR equals the inline form. A plain function that receives data is HZ059.
 - **Events:** `on: { click: ui.send(Event, payload) }`, any DOM event name plus `visible` (entered the viewport).
-  Payload fields: literals, data, `ui.dom.value`, `ui.dom.form('name')`, `ui.dom.checked`, `ui.dom.valueAsNumber`,
-  `ui.dom.key`. `ui.dom.value` / `ui.dom.form` fill an enum field only from a `<select>` or radios whose literal
-  option values are all members (HZ033).
+  Payload fields: literals, data, `ui.dom.value`, `ui.dom.form('name')` / `ui.dom.formAll('name')` (submit; `hozu docs
+  forms`), `ui.dom.checked`, `ui.dom.valueAsNumber`, `ui.dom.key`. `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).
 - **Links:** `ui.a({ href: ui.link(itemPage, { id: item.id }) }, [...])`; never a string path (HZ032). The third
-  argument exists only when the route declares `search`: `ui.link(home, null, { show: 'done' })`.
+  argument 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' })`.
 - **Data:** `ui.query(listItems, input, { ready: (items) => …, pending: ui.p({}, ['Loading…']), failed: { NotFound:
   () => …, Unexpected: () => … } })`; `pending` is optional, `failed` lists every declared error plus `Unexpected`; a branch may return `null` to render
   nothing.

package/templates/app/app.ts

@@ -0,0 +1,7 @@
+import { resolvers } from '@hozu/data'
+import { app } from '@hozu/runtime-server'
+import project from './hozu.config.ts'
+
+export default app({
+  resolvers: resolvers(project, () => []),
+})

package/templates/app/hozu.config.ts

@@ -7,6 +7,7 @@ import { home } from './routes.ts'
 export default project({
   schema: zodAdapter,
   styles: new URL('./app.css', import.meta.url),
+  app: new URL('./app.ts', import.meta.url),
   site: { url: 'http://localhost:3000', name: '__NAME__', lang: 'en' },
   routes: { home },
   pages: [ui.page(home, { views: [Home], head: { render: () => ({ title: '__NAME__' }) } })],

package/templates/guide.md

@@ -3,24 +3,12 @@
 A web app built with Hozu (`@hozu/*`). Hozu is not in your training data.
 
 ## Before writing code
-- __READ__
-- Changing existing code: read `__SKILL__/changing.md` first.
+- __READ__ It has the change loop, the commands and the rules no diagnostic checks.
 - The files in `__SKILL__/` are the whole API. Do not read the framework source in `node_modules/@hozu`.
-
-## The loop
-```
-__RUN__ hozu add feature tasks --page / --with detail,toggle,filter,remove   # then edit the texts it lists
-                                          # add auth to the list for sign-in and per-user data
-__RUN__ hozu map                           # outline of the app with file:line, before a change
-__RUN__ hozu check                         # after every change: types, rules, contracts
-__RUN__ hozu check --update-lock           # only to accept a clean, intended behaviour change
-__RUN__ hozu get / --select button --forms  # try pages without a server: text, attributes, forms
-__RUN__ hozu post / --field title=Ship --next /   # submit a form like a browser
-__RUN__ hozu browse / --do 'click Save'     # real browser, no server: errors, widgets, text after steps
-```
 __NOTE__
 ## Rules
 - After `hozu add feature`, do not print the generated files: edit the texts it lists; `hozu map` shows the rest.
 - Apply the fix each diagnostic gives; do not work around a rule.
-- Every behaviour change comes with a contract change.
-- Do not edit `__SKILL__/`: `__RUN__ hozu skill` rewrites it for the installed Hozu version.
+- `__RUN__ hozu get` and `__RUN__ hozu browse` run the same app as `npm start`; do not start a server to check.
+- Do not edit `__SKILL__/` or the text between the `hozu` markers: `__RUN__ hozu skill` rewrites both for the
+  installed Hozu version.

package/skill/changing.md

@@ -1,45 +0,0 @@
-# Changing a Hozu app
-
-Keep the loop short: map once, edit everything, check once, verify once.
-
-## 1. Read
-- The change request.
-- `pnpm exec hozu map`: every route, query, mutation, event, state, view and contract, each with its `file:line`.
-  Open only the lines the change touches. *model* is `model.ts` (schemas, events, effects, `fn`s, the machine),
-  *views* is `views.ts` (views, contracts); `feature.ts` lists both modules, so new exports need no registration.
-- The API is in `SKILL.md`. `hozu docs recipes` has worked steps for an enum field in the add form, a bulk action
-  button, a detail field and a detail page; `hozu docs <topic>` for anything else.
-
-## 2. What to touch
-| Change | Touch |
-|---|---|
-| New UI-only state (a tab) | model: the context field and its initial value, an event, an `on` whose `assign` sets it → views: the control (no contract: it only copies a value). |
-| Filter / sort / page in the URL | the route's `search` schema (with a default) → links with `ui.link(route, params, { key: value })` → read `search.key` in the view. If the page also filters as you type, `seed: ({ search }) => ({ key: search.key })` on the view and read `ctx.key` only. |
-| A per-item action stored on the server (pin, archive, star) | model: a field on the item, an event, a mutation that `invalidates` the list tag, `on(Event, { target: 'pinning', assign: (e) => { ctx.target = e.id } })` and a state with `invoke` → views: the per-item form from `hozu docs patterns` → server: store it and sort in the list resolver. These transitions only copy values: no contract. |
-| A control that works in every mode | `machine({ on: [...] })` instead of repeating it per state. |
-| New page | `routes.ts` → a view with `route` in `views.ts` → `ui.page(...)` in `hozu.config.ts` (`head`, and `entries` when the route has params). |
-
-Whenever the machine changes:
-- A transition that decides something (a guard, `navigate`, or a `fn` in its values) needs a contract; HZ016
-  prints each missing one ready to paste. Transitions that only copy values are reviewed through the lock.
-- States with `invoke` drop unhandled events by themselves. Other states must handle or `ignore` every event their
-  visible controls send; HZ005 prints the missing entries.
-
-## 3. Check (once, after all edits)
-```
-pnpm exec hozu check
-```
-Fix what it reports. When the behaviour change is intended, run `pnpm exec hozu check --update-lock`: HZ018 shows
-each changed transition as `was: … now: …`, and accepting it updates the lock.
-
-## 4. Verify (once, no server needed)
-- **Pages:** `pnpm exec hozu get / /items/i1` prints the status, title, alerts and visible text.
-- **Attributes and forms:** `--select button` (or `'[role=alert]'`, `a[href]`, `#id`) prints elements with their
-  attributes, e.g. `aria-pressed`; `--forms` lists each form's fields and buttons. Never start a server for this.
-- **Forms:** `pnpm exec hozu post / --field title=A --field priority=high --next /items` fills the form like a
-  browser (other fields keep their defaults). It follows the redirect, then runs the next steps in the same
-  process.
-- **Chaining:** chain what must share data, e.g. `--next 'POST / title=a'` (fields as `a=1&b=2`) or
-  `--next /items/i3`.
-- **A form with only a button:** `--button 'Clear done'`, or `--next 'POST / @Clear done'`. With one form per item,
-  `--field id=t2` picks the item's form.

package/skill/example/serve.ts

@@ -1,14 +0,0 @@
-import { createServer } from '@hozu/adapter-node'
-import { buildProject } from '@hozu/core/ir'
-import { compileStyles } from '@hozu/css'
-import project from './hozu.config.ts'
-import { createResolvers } from './server.ts'
-
-const port = Number(process.env.PORT ?? 3000)
-const build = buildProject(project, { sources: false })
-
-createServer({
-  build,
-  styles: await compileStyles(build),
-  resolvers: createResolvers(),
-}).listen(port, () => console.log(`Bookmarks on http://localhost:${port}`))

package/skill/topics/widgets.md

@@ -1,30 +0,0 @@
-# Widgets (browser APIs, DOM libraries)
-
-Start with `hozu add widget <feature> <Name>`: it writes the declaration, the client module, the `serve.ts` bundle
-and the `@hozu/bundle` dependency. There is no `widget` export; the pieces are:
-```ts
-export const Map = ui.widget({ tag: 'div', props: z.object({ lat: z.number(), lng: z.number() }),
-  events: { picked: z.object({ id: z.string() }) }, client: new URL('./map.client.ts', import.meta.url),
-  load: 'visible', wraps: false })                                      // widgets.ts; the feature lists the module
-ui.use(Map, { props: { lat: ctx.lat, lng: ctx.lng }, on: { picked: (d) => ui.send(Pick, { id: d.id }) },
-  class: 'h-96 w-full' }, [])                                           // in a view
-```
-```ts
-// map.client.ts: a type-only import of the declaration
-import { implement } from '@hozu/core/widget'
-import type { Map } from './widgets.ts'
-export default implement<typeof Map>(({ el, props, emit, signal }) => {
-  const map = createMap(el, props)                          // any DOM library
-  map.on('pick', (id) => emit('picked', { id }))
-  return { update(next) { map.move(next) }, destroy() { map.remove() } }
-})
-```
-- `on` is optional. `ui.use` takes no other attributes: put a role or label on a wrapping element,
-  `ui.section({ role: 'region', 'aria-label': 'Map' }, [ui.use(Map, { props }, [])])`.
-- `load`: `'eager' | 'visible' | 'idle'`; `wraps: true` keeps the children as server HTML.
-- `serve.ts` passes `widgets: await bundleWidgets(build)` (the server refuses to start without it; `hozu build` bundles
-  them itself). A library's CSS goes in `app.css` (`@import "leaflet/dist/leaflet.css";`); a map or chart host needs a
-  height class.
-- Check it with `hozu browse /` (no server): each widget is listed as mounted / failed / not mounted with its size
-  and canvases, next to any error it threw. A mounted host carries `data-hozu-widget="<feature>.<Name>"` and
-  `data-hozu-widget-state="mounted"` for your own browser tests.

package/templates/app/serve.ts

@@ -1,14 +0,0 @@
-import { createServer } from '@hozu/adapter-node'
-import { buildProject } from '@hozu/core/ir'
-import { compileStyles } from '@hozu/css'
-import project from './hozu.config.ts'
-import { createResolvers } from './server.ts'
-
-const port = Number(process.env.PORT ?? 3000)
-const build = buildProject(project, { sources: false })
-
-createServer({
-  build,
-  styles: await compileStyles(build),
-  resolvers: createResolvers(),
-}).listen(port, () => console.log(`__NAME__ on http://localhost:${port}`))

package/templates/app/server.ts

@@ -1,6 +0,0 @@
-import { resolvers } from '@hozu/data'
-import project from './hozu.config.ts'
-
-export function createResolvers() {
-  return resolvers(project, () => [])
-}