@plitzi/sdk-server 0.37.9 → 0.37.10

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

@@ -1,7 +1,9 @@
 # Structuring a space that grows
 
-A one-screen space fits in `src/space.ts`. Past a few pages, split it by what changes together — and keep every
-repeated thing in exactly one place.
+A one-screen space fits in `src/space.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.
 
 ```text
 src/space/
@@ -20,29 +22,36 @@ src/space/
 
 ## Components are functions
 
-The same block in two places is a function with parameters. Its ids come from a parameter, because ids are one
-namespace for the whole space:
+The same block in two places is a function with parameters. Ids are one namespace for the whole space, so the
+function builds inside `scope()`: every `id` given in it is prefixed by the scope's name, and `ref()` names one of them
+in full for a binding, a step's target or a template:
 
 ```ts
 export const panel = (params: { id: string; title: string; sub?: string; link?: { href: string; label: string }; children: ElementSpec[] }): ElementSpec =>
-  container({
-    id: params.id,
-    class: panelCard,
-    children: [
-      container({
-        id: `${params.id}-head`,
-        class: panelHead,
-        children: [
-          heading(params.title, { id: `${params.id}-title`, subType: 'h3', class: panelTitle }),
-          ...(params.sub ? [text(params.sub, { id: `${params.id}-sub`, class: panelSub })] : []),
-          ...(params.link ? [link({ id: `${params.id}-link`, href: params.link.href, class: panelLink, children: [text(params.link.label)] })] : [])
-        ]
-      }),
-      ...params.children
-    ]
-  });
+  scope(params.id, () =>
+    container({
+      id: 'panel',
+      class: panelCard,
+      children: [
+        container({
+          id: 'head',
+          class: panelHead,
+          children: [
+            heading(params.title, { id: 'title', subType: 'h3', class: panelTitle }),
+            ...(params.sub ? [text(params.sub, { id: 'sub', class: panelSub })] : []),
+            ...(params.link ? [link({ id: 'link', href: params.link.href, class: panelLink, children: [text(params.link.label)] })] : [])
+          ]
+        }),
+        ...params.children
+      ]
+    })
+  );
 ```
 
+`panel({ id: 'hm-traffic', … })` writes `hm-traffic-panel`, `hm-traffic-title`… Whatever names one of them from inside
+takes it from the function's argument — `scope(params.id, ref => …)`, then `scrollBy(ref('row'), …)` or
+`` `{{ list_${ref('row')}.index }}` ``. Scopes nest; a list's `row` already reads its list by its full name.
+
 A page then reads as what it shows: `panel({ id: 'hm-traffic', title: 'Traffic', link: { href: 'analytics', label:
 'Open analytics →' }, children: [chart] })`.
 

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

@@ -0,0 +1,19 @@
+# From Tailwind classes
+
+`tw()` turns Tailwind classes into the rules `styles()` takes, when the space is written — nothing of Tailwind runs in
+the page, and the class is an ordinary one the builder edits:
+
+```ts
+const pill = styles('nav-pill', tw('inline-flex items-center gap-2 px-5 py-2 rounded-full bg-slate-950/90 hover:scale-105 md:text-sm'));
+const t = createTw({ colors: tokens(variables) });   // bg-surface → var(--surface), text-ink/60 → a tint of it
+```
+
+- Tailwind v4's scales and palette, its arbitrary values (`w-[220px]`, `shadow-[0_0_20px_rgb(6_182_212/0.35)]`), CSS
+  variables (`bg-(--accent)`) and any property (`[mask-type:luminance]`).
+- Breakpoints become Plitzi's ranges: `md:` is tablet and desktop, `lg:` desktop, `max-md:` mobile, `max-lg:` tablet and
+  mobile. A property only a wider range sets is `revert` below it.
+- `hover:`, `focus-visible:`, `active:`… are the class's states; `group-hover/card:` is how it looks inside an
+  ancestor wearing the class `card`.
+- What has no exact equivalent is refused with what to write instead (`tw-no-equivalent`): `sm:`/`xl:`, `dark:` (a
+  token with both values), `space-x-*` (`gap`), `animate-*` (keyframes in `customCss`). An unknown class is
+  `tw-unknown-class` with the closest one; two classes that tie on a property are `tw-class-conflict`.

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

@@ -16,7 +16,7 @@ An attribute holding a condition — `href: "/x/{{ on ? 'a' : 'b' }}"` — is us
 `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 : '/' }}")] })
+link({ href: '/', 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
@@ -39,8 +39,8 @@ A text template feeding `items` is refused: the list would receive the array wri
 ## 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`, `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 }}`.
+`modalContainer_credits`. The globals (`state`, `auth`, `navigation`, `variables`, `host`, `theme`, `flags`, `computed`) are
+named as themselves — `{{ flags.newCheckout }}` is `true` or `false`, see [feature flags](feature-flags.md). 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`.
@@ -69,7 +69,7 @@ outside the element that publishes it — each with the name it should have been
   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
+join reverse length first last contains startswith endswith number number_format currency percent 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`.
 
@@ -93,7 +93,8 @@ A lookup across two sources — a row joined to the stats around it:
   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)`.
+- **Numbers**: `number_format(decimals, point, thousands)`; `round(precision)`; `currency('USD', 'en', { trimZeros: true })`
+  (`$2,040.57`, `$440`); `percent(1)` (`0.256` → `25.6%`). Locale `en` unless named, so server and browser agree.
 - **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

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

@@ -57,6 +57,13 @@ for it; over `max`, `problems` says so. It reads the SDK's render tracing, which
 the space with it (the e2e harness: `renderSpace(page, space, { debugMode: true })`). What to do with the answer is in
 [performance](performance.md).
 
+## Asking the page what it holds
+
+`plitzi check` lists every flow that failed while the page loaded; `--state` adds the state and every source by its
+full name, `--element <id>` one element — what it reads, its own state, whether it is on screen. They come from the
+page's dev tools (debug mode, any development server). In a test, `readDevTools(page, { state: true })` from
+`@plitzi/sdk-authoring` answers the same.
+
 ## 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
@@ -112,6 +119,10 @@ expect(await page.evaluate(() => (window as unknown as { __painted: string[] }).
 
 ## Screenshots and scrolling
 
+A browser holds back CSS animations and transitions in a tab that is not in view, and `onInterval` stops ticking there:
+check motion with `getComputedStyle(element).animationName` (and `animationPlayState`), or two screenshots taken
+apart, in a page that is in front — not a background tab.
+
 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

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

@@ -0,0 +1,20 @@
+# 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
+and checked: `site.data.hero.titel` is a type error, and refused `source-field-unknown` if it gets past the types.
+
+```ts
+const site = source('site', home);
+apiContainer({ id: site.id, query: '/data/home.json', children: [
+  heading({ from: site.data.hero.title }),
+  text({ content: twig`{{ ${site.data.products}|length }} products` }),
+  list({ id: 'products', items: site.data.products, row: p => text({ from: p.item.title }) })
+] })
+```
+
+- A path is the source's full name (`apiContainer_site.data.hero.title`), so it goes in `from`, `items`, `bind` and
+  `visible` as it is, and into a template through `twig` (a plain template literal writes the same text, but a
+  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]`.

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

@@ -36,15 +36,19 @@ bar.
    import { space } from './src/space.ts';
 
    try {
-     const { schema, warnings } = authorSpace(space, { plugins: [] /* your declarations */ });
+     const { schema, warnings, suggestions } = 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}`));
+     suggestions.forEach(({ code, message, saves }) => console.log(`[suggest] ${code} (saves ${saves}): ${message}`));
    } catch (error) {
      console.log((error as Error).message);
    }
    ```
 
-2. **Fix, re-run, until it prints zero warnings.** Then typecheck the project.
+2. **Fix, re-run, until it prints zero warnings.** What has one fix (`author` says how many) is written for you: `npx
+   plitzi fix` shows it as a diff of your source, `--write` writes it and keeps it only if the space authors with each
+   fix gone and nothing new — a fix it cannot place, or that would add a problem, is said with the reason. 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.