@plitzi/sdk-server 0.37.2 → 0.37.4

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

@@ -4,43 +4,77 @@ Plitzi's templates are Twig, run by Plitzi's own interpreter. What a `{{ … }}`
 
 ## Where a template runs
 
-| Written in | What is evaluated | Use it for |
+| Written in | What is evaluated | What it can read |
 | --- | --- | --- |
-| a binding's `twigTemplate` transformer | the whole template: conditions, filters, `{% set %}`, loops, tests | anything computed — this is where logic goes |
-| a flow step's params | the whole template | values a step sends or stores |
-| an ATTRIBUTE (`href`, `src`, `content`…) | only `{{ name }}` and `{{ name|filter }}` tokens | dropping a value into a string |
+| a binding's `twigTemplate` transformer | the whole template: conditions, filters, `{% set %}`, loops, tests | `source` (the bound value), `sourceTo`, the globals, the variables by bare name, and every source around the element |
+| a flow step's params | the whole template | the trigger's payload and earlier steps by name, the globals, sources around the element |
+| an ATTRIBUTE (`href`, `src`, `content`…) | only `{{ name }}` tokens (a filter after the name is allowed) | the globals, the variables and the page's route params by bare name (`{{ apiUrl }}`, `{{ slug }}`), and every source around the element (`{{ list_games.item.slug }}`) |
 
-An attribute holding only a condition — `href: "/x/{{ on ? 'a' : 'b' }}"` — is used **as written** (`authorSpace` warns
-`template-never-resolved`). Move the expression into a binding:
+A **query parameter** is `navigation.queryParams.<name>` everywhere — never a bare name.
+
+An attribute holding a condition — `href: "/x/{{ on ? 'a' : 'b' }}"` — is used **as written** (`authorSpace` warns
+`template-never-resolved`). Move the expression into a binding with `bindTemplate`:
+
+```ts
+link({ href: '/', mode: 'internal', bind: [bindTemplate('href', 'state.workspace.id', "{{ source ? '/workspace/' ~ source : '/' }}")] })
+```
+
+A value that came from a BINDING is data, never a template: a comment reading `{{ auth.accessToken }}` prints those
+characters. Only what you authored is interpolated.
+
+### A template's value, not its text
+
+A binding's template renders TEXT by default. For an attribute that holds a list, a number or a flag — a list's
+`items` above all — hand over the VALUE with `returns: 'value'` (`returnMode: 'value'` on the transformer). The
+template must be a single `{{ expression }}`:
 
 ```ts
-link({ href: '/', bind: [{ to: 'href', source: 'state.workspace.id',
-  transformers: [{ action: 'twigTemplate', params: { template: "{{ source ? '/workspace/' ~ source : '/' }}" } }] }] })
+list({ id: 'shown', source: 'controlled',
+  bind: [bindTemplate('items', 'games.data.games', '{{ source|filter(g => state.genre == "" or g.genre == state.genre) }}', { returns: 'value' })],
+  children: [ … ] })
 ```
 
-In a binding, `source` is the value at the binding's `source`; everything else in scope is a source named in full.
+A text template feeding `items` is refused: the list would receive the array written out as JSON and render nothing.
 
 ## Naming sources inside a template
 
 Always the full name — the element's kind, an underscore, its id: `apiContainer_stats`, `list_rows`,
-`modalContainer_credits`. The globals (`state`, `auth`, `navigation`, `variables`, `theme`) are named as themselves. In
-a flow, an earlier step is read by the name given with `named('quote', …)`: `{{ quote.output.total }}`.
+`modalContainer_credits`. The globals (`state`, `auth`, `navigation`, `variables`, `host`, `theme`, `computed`) are named
+as themselves. In a flow, an earlier step is read by the name given with `named('quote', …)`: `{{ quote.output.total }}`.
+
+An id with a hyphen is one name inside a template — `{{ apiContainer_tn-data.data.total }}` reads that provider. So
+subtraction is written with spaces: `{{ total - used }}`, never `total-used`.
 
-A list publishes one scope per row: inside a row, `list_rows.item` is THAT row.
+A source reaches only the elements **inside** the element that publishes it (a layout's providers reach every page in
+it). A list publishes one scope per row: inside a row, `list_rows.item` is THAT row and `list_rows.index` its position;
+a nested list's rows still see the outer row.
+
+`authorSpace` refuses a name nothing answers to, a short name where the full one is needed, and a source read from
+outside the element that publishes it — each with the name it should have been.
 
 ## The language
 
-- Operators: `~` (concat), `+ - * / %`, `== != < > <= >=`, `and or not`, `in`, `a ? b : c`, `a ?? b`.
-- Access: `a.b`, `a.0`, `a[i]`, `(expr).key`, `(expr)[i]`.
-- Blocks: `{% set x = … %}`, `{% if %}…{% elseif %}…{% else %}…{% endif %}`, `{% for item in list %}…{% endfor %}`.
-- Arrow functions in filters: `rows|sort(r => r.at)|first`, `rows|filter(r => r.active)`, `rows|map(r => r.name)`.
-- Tests: `is defined`, `is empty`, `is null`, `is iterable`, `is even`, `is odd`, and their `is not` forms.
+- Operators: `~` (concat), `+ - * / // % **`, `== != < > <= >=`, `and or not`, `in`, `starts with`, `ends with`,
+  `a ? b : c`, `a ? b` (empty when false), `a ?: b` (a when truthy), `a ?? b` (a when defined).
+- Access: `a.b`, `a.0`, `a[i]`, `(expr).key`, `(expr)[i]`, `['x', 'y'][i]`, `{ k: 1 }.k`.
+- Blocks: `{% set x = … %}`, `{% if %}…{% elseif %}…{% else %}…{% endif %}`, `{% for item in list %}…{% endfor %}`,
+  `{% apply upper %}…{% endapply %}`, `{% break %}`, `{% continue %}`.
+- Arrow functions in filters, closing over `{% set %}` variables: `rows|sort(r => r.at)|first`,
+  `rows|sort((a, b) => b.score - a.score)`, `rows|filter(r => r.score >= min)`, `rows|map(r => r.name)`.
+- Tests: `is defined`, `is empty`, `is null`, `is iterable`, `is even`, `is odd`, `is same as(x)` (strict: `false` is
+  not `'false'`, `0` or an unset value), `is divisible by(n)`, and their `is not` forms. `null` and `none` are literals.
 - Functions: `range`, `min`, `max`, `cycle`.
+- **Not supported**: `matches` (no regular expressions are evaluated — use `starts with`, `ends with`, `in`), macros,
+  `include`/`extends`, and any filter or function not listed here. `authorSpace` refuses them, and anything else the
+  interpreter would read past, rather than letting a template render a value nobody wrote.
+
+Filters: `default upper lower trim capitalize title camelize kebab snake ltrim rtrim pad padRight replace slice split
+join reverse length first last contains startswith endswith number number_format round abs format sort batch chunk map
+reduce merge keys values filter column find pluck unique flatten sum without only index_by group_by url_encode nl2br
+striptags spaceless json_encode to_json object_as_json raw date base64_encode base64_decode md5 random`.
 
-Filters: `default upper lower trim capitalize title camelize kebab snake ltrim rtrim pad replace slice split join
-reverse length first last contains startswith endswith number number_format round abs format sort batch chunk map
-reduce merge keys values filter column find pluck unique flatten sum without only index_by group_by url_encode
-striptags spaceless json_encode to_json raw date year month day hours minutes seconds weekday random`.
+`format` is sprintf: `'%02d'|format(n)` → `05`, `'%.1f'|format(x)`, `'%-8s'|format(name)`, `'%+d'|format(delta)`. A bare
+`%f` keeps the number's own digits.
 
 A lookup across two sources — a row joined to the stats around it:
 
@@ -54,16 +88,22 @@ A lookup across two sources — a row joined to the stats around it:
 
 - **An empty list is false**, like an absent one. To tell "arrived and empty" from "not arrived":
   `{{ items is defined and items is empty }}`.
-- **`json_encode` of a string is the string**, unquoted. Do not build JSON by interpolating text a visitor typed —
-  pass objects as step params instead.
+- **`json_encode` prints JSON for any value** — a string quoted and escaped, nothing as `null` — so a JSON document
+  is built by encoding each value: `'{ "board": {{ id|json_encode }}, "timer": {{ timer|json_encode }} }'`. In a flow
+  step's params and an action's output, `"{{ text }}"` in quotes is safe too — a value inside a string literal of a
+  param written as a JSON document is escaped for it. Anywhere else (an attribute, a binding's template) it is not:
+  encode.
 - **Numbers**: `number_format(decimals, point, thousands)`; `round(precision)`.
-- **A template that renders a number hands on a number** in step params (`'1'` → `1`).
+- **A step param that is one `{{ expression }}` is that value, with its type**: a number stays a number, and a
+  string stays a string however it looks — a password typed `1234` arrives as `"1234"`. Nothing is guessed from the
+  text: to convert, declare the type where the value lands (`setState`'s `type`, the action's input field). Text around
+  the tokens is text, unless it makes a JSON object or array — then it is that document (see `json_encode` above).
 
 ## Dates
 
-- `|date(format, zone)` — tokens `Y m n d j H G i s l F M N w U`. **Always pass a zone** (`'UTC'`) and print it: with
-  no zone the date is formatted in the local time of whoever renders it — the server's for the HTML, the visitor's
-  after hydration — and the two disagree.
+- `|date(format, zone)` — tokens `Y y m n d j H G h g A a i s l D F M N w U`; a backslash prints the next character
+  as it is (`\T`). **Always pass a zone** (`'UTC'`) and print it: with no zone the date is formatted in the local time
+  of whoever renders it — the server's for the HTML, the visitor's after hydration — and the two disagree.
 - A timestamp can be seconds or milliseconds, a number or a string of digits — all read.
 - For "3 minutes ago", the `dateConverter` transformer with `{ asAge: true }`; give it `isUnix: false` for an ISO
   string. Its checkbox params accept real booleans (and `'true'`/`'false'`).

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

@@ -1,19 +1,78 @@
 # Testing what you authored
 
+## One call: `inspectPage`
+
+```ts
+import { authorSpace, inspectPage } from '@plitzi/sdk-authoring';
+
+const { handles } = authorSpace(space);
+await page.goto('/');
+expect((await inspectPage(page, handles)).problems).toEqual([]);
+```
+
+It checks the open page and returns EVERY problem at once, one sentence each, naming the element and the reason:
+
+- every element the page owes is present and visible — its own and those of the layouts around it
+  (`heading "hero-title" is on the page but not visible: display:none on "hero"`);
+- every image arrived — an image element that failed says so (`data-plitzi-failed`), though its fallback loads;
+- nothing scrolls sideways (`the page scrolls sideways by 37px — widest: "cards"`);
+- no text is drawn in the colour painted behind it.
+
+It retries for up to 5 s like an assertion does (`timeout`), so a provider still answering is not a failure. Options:
+`page` (id or slug; the home page by default), `elements: 'all'` to owe the unnamed elements too, `ignore: ['id']` for
+what a test knows is not there yet (a typo is refused), `skip: ['images']` for a check a page breaks on purpose.
+`inspectDocument(page)` runs the page checks alone, for a page whose space is not in hand.
+
 ## Handles
 
 `authorSpace` returns `handles`: every element by id, with the selector that finds it in the rendered page
 (`[data-plitzi-el="<id>"]`). `handles.element(id)` throws on a name that does not exist, and `locate(page, handles)`
-turns an id into a Playwright locator. Pages are in `handles.pages` (each with its `path` and `elements`); a layout's
-elements are in `handles.layouts` and render on every page that names the layout.
+turns an id into a Playwright locator. Pages are in `handles.pages` (each with its `path`, `elements` and `layout`); a
+layout's elements are in `handles.layouts` and render on every page that names the layout. `onScreen(handles, page)` is
+the list `inspectPage` holds a page to.
+
+Three flags say what a bare visit cannot promise, and `onScreen` leaves out:
 
-An element marked `conditional` is on screen only under a condition of its own or of an ancestor — skip it in an
-"every named element is visible" check. A `formControl`'s id names its wrapper: type into
-`locate('email').locator('input')`.
+- `conditional` — on screen only under a condition of its own or of an ancestor;
+- `repeated` — inside a list row, so rendered once per row: several copies, or none while the list is empty. Address
+  one with `.first()` / `.nth(i)`, in a test that knows the data;
+- `boxless` — a provider with no tag, which renders its children and no element of its own.
+
+A `formControl`'s id names its wrapper: type into `locate('email').locator('input')`.
 
 Select by `data-plitzi-el`, never by a generated class name: authoring derives `<type>-<hash>` for an element's own
 rules, and that name changes when the rules do.
 
+## Pressing a shortcut
+
+`pressShortcut(page, 'mod+z')` presses a shortcut written the way `onKey` writes it, with the keys the PAGE listens
+for: `mod` is ⌘ where the page's user agent is a Mac and Ctrl anywhere else. A driver's own "Control or Meta" asks the
+machine running the suite instead, so a suite on a Mac driving an emulated desktop Chrome presses ⌘ at a page waiting
+for Ctrl — the flow never runs and nothing says why. Point at the page first (a click on it) so it has the keys.
+
+## Counting what an interaction renders
+
+`inspectRenders(page, act, { max })` runs `act` and answers every element that rendered, how often and what changed
+for it; over `max`, `problems` says so. It reads the SDK's render tracing, which is on only under `debugMode` — render
+the space with it (the e2e harness: `renderSpace(page, space, { debugMode: true })`). What to do with the answer is in
+[performance](performance.md).
+
+## Spaces written for a test
+
+Author them like any space — never as JSON: the validator is what tells a fixture that tests something from one that
+tests nothing.
+
+```ts
+import { authorSpace, heading, singlePageSpace, withElement } from '@plitzi/sdk-authoring';
+
+const space = singlePageSpace([heading('Hi', { id: 'title', subType: 'h1' })]);   // one page, nothing else
+const edited = withElement(space, 'title', { attributes: { content: 'Changed' } }); // same page, one thing different
+```
+
+A fixture that must break a check ON PURPOSE — the runtime's answer to a document no author would write is the
+subject — names the break: `authorSpace(spec, { allow: [{ code: 'template-unknown-name', element: 'feed', why: '…' }] })`.
+One code on one element; it comes back in `warnings` with the reason, and an entry that no longer matches is refused.
+
 ## What to check
 
 - **Every viewport and both themes.** Desktop, tablet (48–64rem) and mobile (below 48rem); `colorScheme: 'dark'` as well
@@ -50,3 +109,11 @@ expect(await page.evaluate(() => (window as unknown as { __painted: string[] }).
 - **Navigation lands on the new page's content.** After `waitForURL`, wait for an element of the NEW page before typing:
   for a frame the previous page is still mounted, and a form field with the same name there takes the keystrokes.
 - **Console errors are failures.** Collect them and assert the list is empty.
+
+## Screenshots and scrolling
+
+The page scrolls the document in development exactly as in production while the dev-tools panel is folded away (the
+badge). With the panel OPEN, the page shares the window with it and scrolls inside its own pane — close the panel, or
+run with `debugMode: false`, before a `fullPage` screenshot or a scroll measurement. For a screenshot at a width and a
+theme: `page.setViewportSize({ width: 390, height: 844 })`, `page.emulateMedia({ colorScheme: 'dark' })`, and seed state
+with `render(…, { state })` or a flow the test drives.

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

@@ -0,0 +1,73 @@
+# How `authorSpace` checks — and the loop that wastes no attempts
+
+`authorSpace(space, options)` is the whole check. It either returns `{ schema, style, handles, warnings }` or throws, and
+knowing HOW it throws is what turns ten attempts into two.
+
+## Three stages, two ways of failing
+
+| Stage | What it checks | How it fails |
+| --- | --- | --- |
+| 1. Assembly | Each spec as it is turned into a document: fields that exist, CSS properties the editor can read, a class declared twice with different rules, fonts, selector names | **Throws at the FIRST problem**, naming where it was written (`Element "text" (price) at shop/home/0/2`) |
+| 2. Structure | The documents: parents, roots, pages, cycles, style targets | Collected, then thrown together |
+| 3. Linter | What the documents MEAN: every template, binding, flow step, trigger, callback, attribute and link, read the way the runtime reads them | **All errors at once**, one line each: `Invalid space (…):\n  - [code] message` |
+
+The linter only runs once stage 2 holds, so the pattern of a session is: a few single refusals (fix, re-run), then one
+list — **fix every line of the list in one pass** before running again. Each message says what to write instead; do
+exactly that (see [authoring-errors](authoring-errors.md) for every code).
+
+Warnings come back in `warnings` and never throw. Each one is written code that will not do what it says — zero is the
+bar.
+
+## The loop
+
+0. **Before writing an element you have not used, print what it takes.** One command answers attributes, values,
+   triggers, callbacks and slots, and saves a refusal per guess:
+
+   ```bash
+   node --input-type=module -e "import * as a from '@plitzi/sdk-authoring'; const t = 'dropdown'; console.log({ attributes: a.elementDefaultAttributes[t], values: a.elementAttributeValues[t], triggers: a.elementTriggers[t], callbacks: a.elementCallbacks[t], slots: a.elementSlots[t] })"
+   ```
+
+1. **Author once, print everything.** In a project `plitzi create` wrote, `npm run author`. Anywhere else, a file you run
+   with `node` (≥ 22.18 strips the types) — outside the project's source, never committed:
+
+   ```ts
+   import { authorSpace } from '@plitzi/sdk-authoring';
+
+   import { space } from './src/space.ts';
+
+   try {
+     const { schema, warnings } = authorSpace(space, { plugins: [] /* your declarations */ });
+     console.log(`${Object.keys(schema.flat).length} elements, ${warnings.length} warnings`);
+     warnings.forEach(warning => console.log(`[${warning.code}] ${warning.message}`));
+   } catch (error) {
+     console.log((error as Error).message);
+   }
+   ```
+
+2. **Fix, re-run, until it prints zero warnings.** Then typecheck the project.
+3. **Look at it** — in a browser, at desktop and phone width, in both themes (see [testing](testing.md)). Stage 3 is
+   thorough about MEANING and blind to what follows.
+
+## What it cannot see
+
+A space that authors cleanly can still render wrong. These are the places to look with your own eyes:
+
+- **The shape of data it does not have.** A binding to `feed.records` is checked to name a provider; whether the
+  action's output HAS `records`, or its rows a `magnitude`, is known only at run time. Render with real data.
+- **Layout and cascade.** Overflow, stacking, a type's default style under your class (a `button` or `text` default
+  applies beneath your rules), a `gap` holding a slot for a hidden element.
+- **A plugin's inside** — and, unless you hand its declaration over (`plugins: [declaration]`, see
+  [plugins](plugins.md)), its events, actions and attributes too.
+- **Anything positioned by a component.** A map marker, a dropdown popup, a tooltip: the component sets `position` on
+  its root. A class that sets `position` on it (a panel preset spread into it, say) takes that away, and it lands in
+  the page flow — offset, or holding its container open while hidden.
+- **What an ancestor's `backdrop-filter`, `filter` or `transform` does**: it becomes the containing block of every
+  `position: fixed` descendant and a stacking context of its own, so a popup inside it opens offset and paints UNDER
+  its siblings.
+
+## When a CSS property is refused
+
+The style vocabulary is the closed list the editor can read back. What is outside it — `zoom`, `mask`, a custom
+property (`--seismic-accent`), a pseudo-element, a keyframe — is not an error to work around: it goes in the space's
+`customCss`, addressed by the class name (`.panel`, and `.panel--open` for a variant `variantFrom` applies). Shorthands
+inside it ARE accepted and expanded: `inset`, `grid-area`, `outline`, `border`, `padding` all work in `css`.