@plitzi/sdk-server 0.38.6 → 0.38.7

package/skills/plitzi-authoring/reference/elements-and-styles.md

@@ -18,7 +18,7 @@ container([hero, grid])             // an array is the children
 | `id` | the ONE name this element answers to — its key in the document, a binding's source, a step's target. Unique across the WHOLE space |
 | `class` | a shared class: a `styles()` declaration or a name from the space's `classes`; a list for several. Exclusive with `css` |
 | `css` | rules of this element's own: one set, or one per breakpoint (`{ desktop, tablet, mobile }`) |
-| `states` | `hover`, `focus-visible`, `current` (a link to the page shown), `hidden`… beside the element's own `css` |
+| `states` | `hover`, `focus-visible`, `current` (the chosen link, toggle, tab), `expanded`, `first`/`last`/`odd`/`even`, `hidden`… |
 | `variant` | a variant of the class it wears (when the class declares it) or of its type |
 | `slots` | a class for one of the element's OTHER selectors — a form control's `input` |
 | `bind` | where a value comes from |
@@ -73,13 +73,9 @@ indented with space below it: `{ margin: '0px', padding: '0px' }` on its class t
 children sit in the parent's layout and a `class` on it styles nothing (`STYLE_WITHOUT_TAG`). Put the layout on the
 parent, or give it `attributes: { subType: 'div' }`.
 
-A type this SDK does not ship — a plugin — is authored the same way: `defineElement<Props>({ type, … })`,
-`element<Props>('type', props)`, or `elementsFromManifest(manifest)`. See [plugins](plugins.md).
+A plugin's type is authored the same way: `defineElement<Props>({ type, … })` — see [plugins](plugins.md).
 
-**What a type takes, answered by the package** instead of the 7,000-line `.d.ts`: every catalogue is exported, keyed by
-type — `elementCatalog` (what it is for), `elementDefaultAttributes`, `elementAttributeNames`, `elementTriggers`,
-`elementCallbacks`, `elementSlots`, `elementSourceTypes`, `elementLeafTypes`, plus `BUILTIN_TRANSFORMERS` — and
-`npx @plitzi/cli explain formControl` prints them for one type.
+**What a type takes:** `npx @plitzi/cli explain formControl`, or the exported catalogues ([validation.md](validation.md)).
 
 ## CSS
 
@@ -111,15 +107,20 @@ const card = styles('card', {
 container({ class: card, children: [ … ] });
 ```
 
-- A flat object is the base rules; `{ css, states, variants, ancestors }` when there is more. Each part may be written
+- A flat object is the base rules; `{ css, states, variants, ancestors, pseudos, conditions }` when there is more. Each part may be written
   per breakpoint.
-- **Share a rule as a class, never as a spread.** Spreading a `const` into each element's `css` shares the source and
-  duplicates the document: one selector per element, so restyling one card in the builder restyles one card.
+- **Share a rule as a class, never as a spread** into each element's `css`: that is one selector per element, so
+  restyling one card in the builder restyles one card.
 - **Build a family from a plain object**, not by layering classes: `styles('button-primary', { ...buttonBase, … })`.
+- Of two classes on an element, the one the stylesheet writes later wins (first met; a breakpoint's after the base),
+  not the list's last: write the longhands a class means (`class-overrides-class`).
 - One name declared twice with rules that disagree is refused. Declare a class once, in the module that owns it, and
   import it.
 - `ancestors: { [sidebar.name]: { variants: { collapsed: { display: 'none' } } } }` styles an element by the state or
-  variant of an ancestor class — the way to react to a parent's hover or collapse without a flow.
+  variant of an ancestor class — the way to react to a parent's hover or collapse without a flow; `'>'` is the parent,
+  whatever it wears (a component's part: `{ '>': { states: { expanded: … } } }`).
+- `pseudos: { after: { content: '"→"' } }` (`before`/`after` need a quoted `content`; also `selection`, `marker`,
+  `placeholder`, `first-letter`, `first-line`). `conditions: { 'motion-reduce': …, 'container (max-width: 30rem)': … }`.
 - **`hidden` is how an element looks while its `visible` says no** — where it goes as it hides, and where it comes
   from as it shows. Give the class a transition that includes `display` with `allow-discrete`, and a panel fades or
   slides instead of blinking; the transition on the base is the way in, the one in `hidden` the way out:
@@ -142,16 +143,15 @@ container({ class: card, children: [ … ] });
   What is inside follows its container with `ancestors: { [panel.name]: { states: { hidden: { … } } } }` — a
   different `transition-delay` per item staggers them. A container whose children mount only while it shows
   (`loadStrategy: 'visible'`) empties before it can leave: use `'lazy'` on one that animates out.
-- **The navigation of a site goes in a layout, once.** A link to the page being shown marks itself, and its class
-  dresses it with `states: { current: { … } }` — never a class picked per page, which forces a copy of the header into
-  every page.
-- **`:hover` is part of the selector, not a rule in `customCss`.** `customCss` is for what no class can say:
-  keyframes, pseudo-elements, a rule across two unrelated elements, the inside of a third-party widget.
-- Per element TYPE defaults go in `elements: { heading: { base, states, variants, slots } }` — a whole type at once.
-- **Slots** are an element's other selectors: a `formControl`'s `input`, `label`, `error`; a `modalContainer`'s
-  `backgroundContainer`, `rootContainer`, `headerContainer`, `headerTitle`, `headerCloseButton`, `bodyContainer`; a
-  `dialogContainer`'s footer and buttons. `elementSlots` lists them all by type. Style one element's with `slots`, a
-  whole type's with `elements.<type>.slots`.
+- **The navigation goes in a layout, once:** a link to the page shown dresses itself with its class's
+  `states: { current: { … } }` — never a class picked per page, which copies the header into every page.
+- **`:hover` is part of the selector, not a rule in `customCss`.** `customCss` is for what no class can say: a rule
+  across two unrelated elements, the inside of a third-party widget.
+- Per element TYPE defaults go in `elements: { heading: { base, states, variants, pseudos, slots } }` — a whole type.
+- **Slots** are an element's parts (not `customCss`): a `formControl`'s `input` (the box), `field` (its `<input>`),
+  `label`, `requiredMark`, `error`; a `markdown`'s or `richText`'s `heading`, `heading2`, `link`, `codeBlockFrame`…;
+  a `pagination`'s `page` (the one shown: its `current` state). `plitzi explain <type>` lists them. Style one
+  element's with `slots`, a type's with `elements.<type>.slots`.
 - A `modalContainer` / `dialogContainer` is fixed to the viewport, as tall as its content up to the screen, and 500px
   wide up to the screen; theme its look through its slots.
 
@@ -159,7 +159,7 @@ container({ class: card, children: [ … ] });
 already speak in variant names — `variantFrom(pill, 'runs.item.status', { template: "{{ source == 'completed' ?
 'ok' : 'failed' }}" })`. The binding's key names the CLASS; never write it by hand. A variant while a condition holds
 — the dot of the slide on screen — is `activeWhen(dot, '{{ list_dots.index == state.slide }}')` (`active`, else
-`idle`); for "the current page", `activeOn` in [layouts.md](layouts.md).
+`idle`); for "the current page", `current` in [layouts.md](layouts.md).
 
 ## From Tailwind classes
 
@@ -169,4 +169,4 @@ A design written in Tailwind classes becomes classes the builder edits with `sty
 ## Colours, themes and motion
 
 Every colour is a token with a light and a dark value, read as `var(--name)` (or `tokens(variables)`); keyframes go in
-`customCss` — see [colours-and-motion.md](colours-and-motion.md).
+the space's `keyframes` — see [colours-and-motion.md](colours-and-motion.md).

package/skills/plitzi-authoring/reference/flows.md

@@ -48,7 +48,7 @@ Name the trigger (`named('changed', on('onChange'))`) and read its payload as `{
 
 | Trigger                                                                                                | Payload                                                 |
 | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
-| `onChange` (formControl)                                                                               | `value` (a boolean for a checkbox), `name`              |
+| `onChange` (formControl)                                                                               | `value` (a boolean for a checkbox or switch), `name`    |
 | `onSubmit` (form)                                                                                      | `values` (by control `name`), `actionUrl`, `method`     |
 | `onPageLoad` (page)                                                                                    | `pageId`, `routeParams`, `queryParams`                  |
 | `onApiSuccess` / `onApiError` (apiContainer)                                                           | `url`, `method`, `status`, `data`                       |
@@ -61,6 +61,10 @@ Name the trigger (`named('changed', on('onChange'))`) and read its payload as `{
 `named('quote', step)` is how a later step reads an earlier one: `{{ quote.output.total }}`. The trigger too:
 `named('submitted', onSubmit())` → `{{ submitted.values.email }}`. Unnamed steps get ids nothing can refer to.
 
+`whenSucceeded` / `whenFailed` read a server action's `status` (`runServerAction` only); any other step is asked what
+it publishes (`npx @plitzi/cli explain login` lists it) — after `named('signedIn', authLogin(…))`,
+`when({ field: 'signedIn.ok', operator: '=', value: true }, …)`.
+
 A step's params are templates, evaluated in full (conditions, loops, filters). A source in them is named in full:
 a row's button posts `{ jobId: '{{ list_jobRows.item.id }}' }` — the row that was clicked; the short name is refused.
 
@@ -75,7 +79,7 @@ so `when({ field: 'sent.values.code', operator: '=', value: '' }, …)` never ho
 ## Writes and what they refresh
 
 `webHook` (not GET) refreshes every request to its own site when it succeeds; `runServerAction` refreshes
-everything. Say what it should refresh — `invalidateQueries: 'elements', invalidateElements: ['orders']` — or
+everything, server-driven providers included. Say what it should refresh — `invalidateQueries: 'elements', invalidateElements: ['orders']` — or
 `'none'` for a step that only reads, or when a refresh would make the page act on the new answer mid-flow.
 
 ## Triggers belong to the element that fires them
@@ -134,10 +138,11 @@ without a word.
 
 `addNotification({ content: 'Saved', appearance: 'success' })` — `appearance` is `success`, `danger`, `warning` or
 `info`. They follow the page's theme; how they look is the space's `notifications` — colours (`background`, `text`,
-`success`, `danger`, `warning`, `info`) and shape (`radius`, `font`, `fontSize`, `border`, `shadow`, `padding`):
-`notifications: { background: 'var(--card)', text: 'var(--foreground)', success: 'var(--accent)', radius: '12px',
-font: 'var(--font-sans)', border: '1px solid var(--border)', shadow: 'var(--shadow-lg)' }`. The toast carries no class
-of the space's, so this — not a `.Toastify__toast` rule in `customCss` — is where it is dressed.
+`success`, `danger`, `warning`, `info`), shape (`radius`, `font`, `fontSize`, `fontWeight`, `lineHeight`, `minHeight`,
+`border`, `shadow`, `padding`) and the parts inside (`iconSize`, `iconGap`, `closeColor`, `closeOpacity`,
+`progressHeight`), one CSS value each: `notifications: { background: 'var(--card)', radius: '12px', iconSize: '18px' }`.
+The toast carries no class of the space's, so this — not a `.Toastify__*` rule in `customCss` — is where it is
+dressed.
 
 ## Modals, dropdowns, tabs
 

package/skills/plitzi-authoring/reference/layouts.md

@@ -74,7 +74,6 @@ const navGroup = (group: DocsGroup): ElementSpec =>
         id: `docs-nav-${entry.id}`,
         href: entry.id,
         class: navLink,
-        bind: [activeOn(navLink, entry.id)],
         children: [text(entry.title, { id: `docs-nav-label-${entry.id}` })]
       })
     )
@@ -83,33 +82,31 @@ const navGroup = (group: DocsGroup): ElementSpec =>
 
 Adding a page is one entry in the list: the menu, the index and the neighbours' "next" follow.
 
-## The current entry: `activeOn`
+## The current entry
 
-A menu in a layout is the same nodes on every page, so it cannot have the right entry styled by hand. It asks which
-page is showing:
+A menu in a layout is the same nodes on every page, so it cannot have the right entry styled by hand — and does not
+need to. A link to the page being shown marks itself: `aria-current="page"`, which a screen reader announces, and its
+class's `current` state dresses it:
 
 ```ts
-const navLink = styles('nav-link', {
-  css: { color: 'var(--muted)' },
-  variants: { active: { color: 'var(--foreground)', 'font-weight': '600' } }
-});
+const navLink = styles('nav-link', { css: { color: 'var(--muted)' }, states: { current: { color: 'var(--foreground)' } } });
 
-link({ href: 'spaces', class: navLink, bind: [activeOn(navLink, ['spaces', 'space-record'])] });
+link({ href: '/pricing', mode: 'internal', class: navLink });
 ```
 
-A link to ONE page needs nothing of this: it marks itself — `aria-current="page"`, which a screen reader announces — and
-its class dresses it with the `current` state:
+An entry lit for a SECTION — a journal and its articles, `/automations/runs` while on `/automations/runs/42` — says
+`current: 'section'`: current on its page and on every page under its path, at a `/` (`/runs` holds `/runs/42`, not
+`/runsx`), announced there as the current entry (`aria-current="true"`); the same `current` state dresses it. A link to
+`/` holds every page, so authoring warns (`link-current-section`):
 
 ```ts
-const navLink = styles('nav-link', { css: { color: 'var(--muted)' }, states: { current: { color: 'var(--foreground)' } } });
-
-link({ href: '/pricing', mode: 'internal', class: navLink });
+link({ href: 'runs', class: navLink, current: 'section' });
 ```
 
-`activeOn(class, pageIds, { variant?, slot? })` is for an entry lit on SEVERAL pages — a section and the pages under it,
-a journal and its articles: it binds the class's variant to `navigation.currentPageId`, the `active` variant on those
-pages and `idle` everywhere else. Do not write the binding by hand with a `when` rule per page; that is the long form
-this replaces.
+`activeOn(class, pageIds, { variant?, slot? })` is for an entry lit on pages NOT under its path — `['spaces',
+'space-record']` when a record lives at `/s/:id`: it binds the class's variant to `navigation.currentPageId`, the
+`active` variant on those pages and `idle` everywhere else. Do not write the binding by hand with a `when` rule per
+page; that is the long form this replaces.
 
 ## Pages from a factory
 

package/skills/plitzi-authoring/reference/plugins.md

@@ -96,7 +96,7 @@ const route = usePluginRoute('board'); // from '@plitzi/plitzi-sdk'
 const url = route('/layout'); // undefined where no server runs code (the canvas)
 ```
 
-Its `ctx.kv` is the plugin's own; the space's credentials and channels are not.
+Its `ctx.kv` is the plugin's own; the space's credentials, channels and data are not.
 
 ## Talking to other pages
 

package/skills/plitzi-authoring/reference/review-checklist.md

@@ -50,7 +50,8 @@ Screen readers and browser agents (Claude in Chrome) work a page through its acc
 
 ## No copies
 
-- [ ] Chrome shared by pages is a layout; the current menu entry comes from `activeOn`, not per-page styling.
+- [ ] Chrome shared by pages is a layout; the current menu entry marks itself (`current` state, `current: 'section'`),
+      not per-page styling.
 - [ ] A look used twice is a class; a tree used twice is a function or a `map` over data; a list of pages, links or
       plans is ONE array everything reads.
 - [ ] No positional ids (`container-45`) in what you wrote; every referenced element is named, and a helper that

package/skills/plitzi-authoring/reference/structure.md

@@ -108,7 +108,7 @@ the record is the answer instead: one page, as many addresses as records.
 per page. It renders; it is not maintainable. When you work on such a file, leave it better:
 
 - repeated `css` blocks → one class;
-- a nav with a hand-styled current entry per page → a layout and `activeOn`;
+- a nav with a hand-styled current entry per page → a layout whose links mark themselves (`current: 'section'`);
 - the same tree pasted per item → a function and a `map`;
 - `container-45` → a name.
 
@@ -120,4 +120,5 @@ the rest.
 `npm run lint:space` (`plitzi lint`) reads the source for what this page asks — a file past 400 lines, pages in one
 file, rows of data inline, a colour that is not a token, CSS copied three times, a row singled out by its id inside a
 `map`, a minted id, a file nothing imports — at file:line, beside authoring's suggestions. Leave it clean; a departure
-on purpose says why where it is: `// plitzi-lint-disable-next-line <code> -- why`.
+on purpose says why where it is: `// plitzi-lint-disable-next-line <code> -- why` for lint's own codes. A suggestion of
+authoring's is quieted on its element instead — `quiet: ['repeated-shape']` — where the builder and the MCP read it.