@plitzi/sdk-server 0.38.4 → 0.38.5

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

@@ -1,6 +1,6 @@
 # Structuring a space that grows
 
-A one-screen space fits in `src/space.ts`. Past a few pages, split it by what changes together — a file per part, short
+A one-screen space fits in `src/space/index.ts`. Past a few pages, split it by what changes together — a file per part, short
 enough to read whole — and keep every repeated thing in exactly one place. `npx @plitzi/cli create shop --template
 catalog` writes a complete small site in this shape (tokens, a layout, a card component, typed data, a page per file)
 to read before writing one.
@@ -71,6 +71,30 @@ container({ id: 'quick', class: quickGrid, children: QUICK.map(item => quickCard
 When items differ in ONE detail (one link needs a binding), put that detail in the item's data as an optional field
 — never an `if (item.id === 'team')` inside the map.
 
+## Pages of one shape are a family
+
+Docs pages, a menu's sections, a team's profiles: the same shape, different words. Write the shape once and the pages
+as data with `pageFamily` — it gives each page its id, slug, titles, folder and layout, and builds each body inside
+`scope(entry.id, …)`, so the ids two pages of the family give are never one:
+
+```ts
+import { pageFamily, heading, markdown } from '@plitzi/sdk-authoring';
+import { SECTIONS } from '../data/sections';   // [{ id: 'starters', title: 'Starters', slug: 'starters', description, body }]
+
+pages: [
+  home,
+  ...pageFamily(
+    { folder: 'menu', layout: { id: 'site', slot: 'site-slot' }, seoTitle: entry => `${entry.title} — Menu`,
+      body: entry => [heading({ id: 'title', content: entry.title }), markdown(entry.body, { id: 'body' })] },
+    SECTIONS
+  )
+]
+```
+
+Adding a page is adding an entry; two entries of one id or slug are refused as any two pages are. For one shape over
+records a visitor browses — a product, a post — a single page with a route param (`slug: 'posts/:postId'`) reading
+the record is the answer instead: one page, as many addresses as records.
+
 ## Names
 
 - **Ids:** `area-role` in kebab-case — `hm-traffic-title`, `docs-nav-docs-data`. Never the builder's positional
@@ -90,3 +114,10 @@ per page. It renders; it is not maintainable. When you work on such a file, leav
 
 Each of those is safe to do on its own: authoring refuses anything that would not render, and the visual check shows
 the rest.
+
+## Checked for you
+
+`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`.

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

@@ -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

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 */ });