@plitzi/sdk-server 0.38.3 → 0.38.5

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

@@ -6,7 +6,7 @@ Plitzi's templates are Twig, run by Plitzi's own interpreter. What a `{{ … }}`
 
 | Written in | What is evaluated | What it can read |
 | --- | --- | --- |
-| 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 binding's `twigTemplate` transformer | the whole template: conditions, filters, `{% set %}`, loops, tests | `source` (the bound value — undefined until it has one: `{{ source|default('…') }}`), `sourceTo` (the attribute's value before it), 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 }}`) |
 
@@ -26,7 +26,7 @@ characters. Only what you authored is interpolated.
 
 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 }}`:
+template must be a single `{{ expression }}`, after any `{% set %}` that name its parts:
 
 ```ts
 list({ id: 'shown', source: 'controlled',
@@ -63,7 +63,8 @@ outside the element that publishes it — each with the name it should have been
   `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`.
+- Functions: `range`, `min`, `max`, `cycle`. `abs` is a filter (`x|abs`); floor and ceil are `x|round(0, 'floor')` and
+  `x|round(0, 'ceil')`; a clamp is `min(max(x, low), high)`.
 - **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.
@@ -99,6 +100,8 @@ A lookup across two sources — a row joined to the stats around it:
   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).
+  **One exception: a param that is only a JSON filter (`{{ rows|json_encode }}`) is the value it encodes** — the list,
+  not its text — so an action input receiving it is declared `json`; a `text` field refuses it (422).
 
 ## Dates
 

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

@@ -3,13 +3,20 @@
 ## One call: `inspectPage`
 
 ```ts
-import { authorSpace, inspectPage } from '@plitzi/sdk-authoring';
+import { answerAction, authorSpace, inspectPage, openPage } from '@plitzi/sdk-authoring';
 
 const { handles } = authorSpace(space);
-await page.goto('/');
+await openPage(page, '/');
 expect((await inspectPage(page, handles)).problems).toEqual([]);
 ```
 
+`openPage` waits for the page to settle — loaded, and nothing asked for in half a second — counting no stream that
+stays open: Playwright's `networkidle` never comes on a page with a realtime `channel`.
+
+A test that would SAVE something answers that action itself, before opening the page, so it never writes the server's
+`kv` the next test (or the developer) reads: `await answerAction(page, 'wall', { windows: [] })` — or a function of the
+input. Every other call goes through.
+
 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
@@ -87,7 +94,7 @@ One code on one element; it comes back in `warnings` with the reason, and an ent
 
 ## What to check
 
-- **Every viewport and both themes.** Desktop, tablet (48–64rem) and mobile (below 48rem); `colorScheme: 'dark'` as well
+- **Every viewport and both themes.** Desktop, tablet (48–64rem) and mobile (up to 48rem); `colorScheme: 'dark'` as well
   as light.
 - **No horizontal scroll on a phone.** A column child grows to its content unless its parent stretches it; a code
   block or a wide table is what finds out.

package/skills/plitzi-authoring/reference/typed-sources.md

@@ -1,7 +1,7 @@
 # Data typed by a sample
 
 `source('site', home)` names a provider's source from a sample of its answer — the JSON file it reads, imported
-(`import home from '../../public/data/home.json' with { type: 'json' }`). Every path is then completed by the editor
+(`import home from '../data/home.json' with { type: 'json' }` — `src/data/`, or `public/data/` with no server). Every path is then completed by the editor
 and checked: `site.data.hero.titel` is a type error, and refused `source-field-unknown` if it gets past the types.
 
 ```ts
@@ -18,3 +18,5 @@ apiContainer({ id: site.id, query: '/data/home.json', children: [
   type-checked lint refuses an object in one).
 - A list fed by a path hands its `row` the item typed: every field any item of the sample has.
 - An item of a list is read by position: `site.data.sections[1]`.
+- A provider fed by a server action publishes the action's output at its root: `actionSource('feed', sample)` types
+  it — `feed.stories`, and `feed.data` is a type error — with a sample of what the action's last step answers.

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

@@ -33,7 +33,7 @@ bar.
    ```ts
    import { authorSpace } from '@plitzi/sdk-authoring';
 
-   import { space } from './src/space.ts';
+   import { space } from './src/space/index.ts';
 
    try {
      const { schema, warnings, suggestions } = authorSpace(space, { plugins: [] /* your declarations */ });