@plitzi/sdk-server 0.36.1 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # @plitzi/sdk-server
 
+## 0.37.0
+
+### Minor Changes
+
+- - A `button` takes a `title`: shown as a tooltip, and its accessible name when it has no text of its own — an
+    icon-only button without one was announced as nothing. The builder's settings offer it as "Tooltip". The JSON export
+    is two files, `schema.json` and `style.json`, shown as tabs; each group of changes in the export folds away.
+
+  - `BindingTransformer.params` is `Record<string, string | number | boolean>`: a param the builder draws as a checkbox
+    (`styleVariant`'s `append`) is stored as the boolean it is and read as one, so the type now says so. The MCP compares
+    such a param with its catalog options as text. A `container` may be an `li`, for the rows of a list. The export
+    keeps every element id with `keepIds`, and the header's Publish dialog opens wider.
+
+  - **The builder exports the space on screen — on paid plans.** **Export** in the header opens a wide dialog: the
+    format as tabs (TypeScript in one file, TypeScript with a file per page as a `.zip`, or JSON), generated as soon as
+    it is picked, shown read-only in CodeMirror — beside a file list when there are several — with one row of actions,
+    **Copy** and **Download**. What the export tidied is a one-line note that unfolds into readable groups. On the free
+    plan the dialog explains what export is instead; the server refuses the code with a 402 (`limit: 'spaceExport'`)
+    whatever the builder shows. `useSpaceExport` is the one way into it, for anything else that needs the space as files.
+
+  - **A space document can be read back into code.** `specFromSpace(documents)` turns a `{ schema, style }` pair — a
+    builder export, a seed checked in as JSON — into the `SpaceSpec` that authors it, and `specToSource(spec, { exportName })`
+    writes that spec out as the TypeScript a person would write: one factory call per element, the attributes a type
+    already defaults to left out, the longhands the document stores written back as `padding: 10px 20px`, and every class
+    something names as a `styles()` declaration held in a variable. `split: true` writes one file per page and per layout.
+    `compareSpaces(expected, actual)` proves the round trip: it lists every way two pairs render differently — the tree,
+    the attributes, the rules that apply to each element whatever its selector is called, bindings, flows, pages, layouts
+    and settings — and nothing else. A selector used by one element becomes that element's own `css`; one shared, or
+    spelled out anywhere in the document (a `customCss` rule, a template), stays a class under its own name; an element id
+    nothing refers to is left out and derived again.
+
+    What an older builder left behind is repaired on the way, and every repair is reported in `corrections` rather than
+    made silently: element types that no longer exist (`navbar` → a `list` laid out in a row, `navbarItem` → `listItem`),
+    a hover stored as a class of its own (`card:hover`) folded into the class, fields and attributes no component reads,
+    a setting nothing reads, a link `target` of `_blank` (the component adds the underscore, so it rendered as `__blank`),
+    `null` or an empty list where an attribute is unset, a binding to a source nothing publishes, a flow with a step that
+    runs nothing, and a global callback registered on the wrong module. A CSS property the style editor cannot hold is
+    kept in `customCss` under the same selector, so the page still renders it.
+
+  - **What a spec can say grew to what a document holds.** A selector carries its states and variants beside its rules —
+    `styles('card', { css, states: { hover }, variants: { active } })`, and `states` on an element's own `css` — and the
+    selector cache is now written by `processSelector`, the function the style editor writes it with. An element type's
+    defaults (`elements`) take states, variants, per-breakpoint rules and `slots` for its other selectors (a modal's
+    `rootContainer`). A space declares `layouts` — shells that pages render inside, named by `layout: { id, slot }` on a
+    page or on another layout, with the slot checked to be inside the shell — and a page takes `keepState` and
+    `stateStorage`. `visible: false` starts an element hidden for a flow to reveal, and `loadStrategy` is carried through.
+    An element's own selector never takes the name of a declared class any more, however that class happens to be called.
+
+  - `elementAttributeNames` lists, as data, the attributes each built-in element can be authored with — `null` for one
+    that takes any. It is generated from the elements' attribute types (`yarn generate:attribute-names`) and a type test
+    fails when the two disagree. `defaultAttributes(type)` and `defaultLabel(type)` expose what a factory fills in.
+
+  - `CustomAttributes` accepts any attribute, because the component a custom element's `renderType` names reads its own
+    attributes off it; and `FormControlAttributes` declares `previewError`, which `withFieldValue` reads.
+
+### Patch Changes
+
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.37.0
+  - @plitzi/sdk-shared@0.37.0
+
+## 0.36.2
+
+### Patch Changes
+
+- v0.36.2
+- Updated dependencies
+  - @plitzi/plitzi-sdk@0.36.2
+  - @plitzi/sdk-shared@0.36.2
+
 ## 0.36.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/sdk-server",
-  "version": "0.36.1",
+  "version": "0.37.0",
   "license": "AGPL-3.0",
   "files": [
     "dist",
@@ -58,12 +58,12 @@
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/plitzi-sdk": "0.36.1",
-    "@plitzi/sdk-shared": "0.36.1",
+    "@plitzi/plitzi-sdk": "0.37.0",
+    "@plitzi/sdk-shared": "0.37.0",
     "ejs": "^6.0.1",
     "esbuild": "^0.28.2",
     "jsonwebtoken": "^9.0.3",
-    "nodemailer": "^10.0.9"
+    "nodemailer": "^10.0.10"
   },
   "peerDependencies": {
     "mysql2": "^3",
@@ -78,11 +78,11 @@
   "devDependencies": {
     "@types/ejs": "^3.1.5",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/node": "^26.5.1",
-    "@types/nodemailer": "^8.0.1",
+    "@types/node": "^26.6.1",
+    "@types/nodemailer": "^8.0.2",
     "@types/react": "^19.3.0",
     "@vitejs/plugin-react": "^6.1.1",
-    "@vitest/coverage-v8": "^5.0.0",
+    "@vitest/coverage-v8": "^5.0.1",
     "eslint": "^9.39.5",
     "eslint-plugin-import": "^2.32.0",
     "mysql2": "^3.24.4",
@@ -92,7 +92,7 @@
     "typescript": "^6.0.3",
     "vite": "^8.3.0",
     "vite-plugin-dts": "^5.1.0",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "prepack": "node scripts/copy-authoring-skill.mjs",

package/skills/plitzi-authoring/SKILL.md

@@ -99,7 +99,11 @@ property outside the vocabulary is an error naming the correct key (`paddingTop`
 - **Fonts are declared, not assumed.** A `font-family` loads only if the space lists the face in `fonts`
   (`{ source: 'google', family: 'Fraunces', fallback: 'Georgia, serif', weights: [400, 600], styles: ['normal'] }`);
   the page server writes exactly that list into the document, and anything else renders in the fallback.
-- Per element TYPE defaults go in `elements: { heading: { base: …, variants: { … } } }`.
+- Per element TYPE defaults go in `elements: { heading: { base: …, states: { … }, variants: { … }, slots: { … } } }`
+  — `slots` dresses the type's other selectors (a modal's `rootContainer`) for every element of the type.
+- **`:hover` is part of the selector, not a rule in `customCss`.** `styles('card', { css: { … }, states: { hover: { … } },
+  variants: { active: { … } } })`, and `states` beside an element's own `css`. Written in `customCss` it renders and
+  then cannot be read back or edited per breakpoint.
 
 **Share a rule as a class, never as a spread.** Writing a rule set once in a `const` and spreading it into each
 element's `css` shares the source and duplicates the document — one selector per element, so re-theming the card
@@ -115,8 +119,13 @@ Accepted anywhere a class name is — `class`, a `slot`, a page's `class` — an
 names it. One name declared twice with rules that disagree is refused. `classes` at the top of the space is the
 same mechanism for what describes the space rather than one section of it.
 
-An element has exactly ONE base selector, so a variant is its own class over a shared plain object
-(`styles('button-primary', { ...base, … })`), never two classes layered on top of each other.
+An element has exactly ONE base selector, so a look that never changes is its own class over a shared plain object
+(`styles('button-primary', { ...base, … })`), never two classes layered on top of each other. A class's `variants`
+are for what the page switches while it runs — a binding with the `styleVariant` transformer picks one.
+
+**Shells go in `layouts`.** A header or a sidebar every page shows is a layout the pages name —
+`layout: { id: 'app-shell', slot: 'main' }`, the slot being the element in the shell where the body goes — never a
+copy on each page. `visible: false` starts an element hidden for a flow to reveal.
 
 ## Data
 
@@ -137,6 +146,13 @@ is the quietest failure a space can carry.
 Server-resolved sections are an `apiContainer` with `runtime: 'server'` naming a connector or an action, and a
 space that has any needs `rsc: { enabled: true }`.
 
+**A provider has no box unless you give it a tag.** An `apiContainer` renders no element of its own while its
+`subType` is empty — the default, the builder's "Container Tag: None" — so its children sit directly in the parent's
+layout. That is usually what you want (the provider stays invisible to the layout), and it means a `class` or `css`
+on it styles nothing: the `gap` you wrote between its sections is simply not there. Put the layout on the parent, or
+give the provider a tag (`attributes: { subType: 'div' }`) when it should be the box. `validateSpace` — and so
+`authorSpace` and the MCP — warns with `STYLE_WITHOUT_TAG`.
+
 **Never ask the data for a field's opposite.** Both sides of one question are `visible: 'x'` and `visible: '!x'` —
 not an `x` and a `notX` beside it in the server's answer. The `!` is the `not` transformer, which reads a boolean
 that travelled as text (`"false"`, `"0"`) and treats an empty array as false; an empty object is true. Only for a
@@ -247,6 +263,14 @@ Everything a space is held to still applies, and two more things apply because a
 `validateTemplate(template)` runs the same gate over a manifest you did not author here — one exported by the
 builder, or edited by hand — before you publish it.
 
+## From an exported JSON
+
+Never rewrite an exported space by hand. `specFromSpace({ schema, style })` reads it into the spec that authors it,
+repairing what an older builder left behind and listing each repair in `corrections`; `specToSource(spec,
+{ exportName })` writes that spec as factory calls; `compareSpaces(original, authorSpace(spec))` must list nothing but
+what `corrections` explains. The builder's **Export** (and `POST /utils/transform-to-authoring`) does all three. Edit
+the code it writes from then on, not the JSON.
+
 ## Rules
 
 1. **Never hand-write `flat`, element ids, `styleSelectors`, `beforeNode`/`afterNode`/`flowId`.** They are derived.