@plitzi/cli 0.38.11 → 0.38.12

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # @plitzi/cli
 
+## 0.38.12
+
+### Patch Changes
+
+- 1301338: ## Builder
+
+  - **Icons in the canvas again** (`@plitzi/plitzi-builder`): the canvas inlined the SDK's Font Awesome sheet into its
+    `<style>`, where the sheet's `url(webfonts/…)` resolved against the editor's URL — a `srcdoc` frame takes it as its
+    base — so every icon was a 404 under `/spaces/<space>/webfonts/` and drew as an empty box. Only the Vite dev server,
+    which rewrites the URL, hid it. The canvas and the element preview now link the sheet from where the host serves it:
+    a new prop, `sdkIconsStylePath`, the one the host already gives the pages it renders
+    (`/sdk-assets/plitzi-sdk-icons.css` for sdk-server). Absent, the canvas links no icon sheet.
+
+  ## Plugins
+  - **A plugin's other elements, hosted by `custom`** (`@plitzi/sdk-elements`): `custom({ renderType: 'jamDisc' })` on a
+    space with a plugin installed whose main element is another (`plitzi plugin pack` of several folders: the first is the
+    plugin, the rest go in it) rendered "Custom Component jamDisc Not Found" — the page registers only the plugin's main
+    element, and a `custom` host looked nowhere else. It now loads the type from the installed plugin that packs it, as
+    an element of the type itself always did, so the two ways the docs give to place a plugin's element are the same
+    everywhere: in a project `plitzi create` wrote, and once the project is on Plitzi.
+  - **One way to place a plugin's element** (`@plitzi/sdk-authoring`, `@plitzi/cli`, docs): from its declaration,
+    `const seatPicker = defineElement(declaration)` then `seatPicker({ id, … })` — typed by what it
+    declares, and the element the builder adds when somebody drops it. The welcome space `plitzi create` writes, the
+    plugin package's preview, `plitzi plugin add` and `plitzi explain` all write it so (the template's
+    `PluginHostOptions` now takes the plugin's `type` and `declaration: { from, attributes? }`; `custom`/`element` hosting
+    is gone). `pluginFolders(folder)` (`@plitzi/sdk-authoring/node`) reads each plugin with the folder it is in;
+    `pluginDeclarations` is built on it. A `custom({ renderType })` naming a plugin the space was handed the declaration
+    of is offered the declaration instead — suggestion `plugin-custom-host`. `custom` stays for a component registered
+    by name with no declaration. The skills, the CLI README, the MCP guide, `docs/en` and the website say the same.
+  - **`definePlugin`** (`@plitzi/sdk-authoring/plugin`, a new entry of 3 KB with nothing else in it): a plugin's
+    declaration written from what only it can say —
+    `definePlugin<SeatPickerAttributes>()({ type, label, attributes, triggers, callbacks })` — and every other field
+    at the default all plugins share (the builder's gestures, the catalogue entry, each attribute bindable, an empty
+    style). It answers the whole declaration, branded with its attributes, so `defineElement(declaration)` is typed
+    without a generic. `plitzi plugin add` and `create --plugin` write declarations with it (about a third of the lines).
+  - **`usePluginTrigger(declaration)`** (`@plitzi/plitzi-sdk`): fires a plugin's declared event on its element — the
+    event name and what each hands a flow typed off the declaration's `preview` — on a live page only. The hook every
+    plugin wrote for itself (and `plugin add` generated as `use<Name>Events`) is gone from the scaffold.
+  - **Attributes as the types their defaults are** (`@plitzi/sdk-elements`): a plugin's attribute bound from text — a
+    state, a row, a channel message — reaches its component as the number or the flag its declared default is (`'112'`
+    as 112, `'true'` as true). A plugin no longer types its props `number | string` and parses them.
+
+  ## Server actions and functions
+  - **Task params with rules** (`@plitzi/sdk-server`, `@plitzi/sdk-shared`): a task declares `required`, a text's
+    `maxLength` and a number's `min`/`max`, and the runner refuses a call that breaks any of them — every rule broken at
+    once, in the words the page shows (`Title is required; Seconds is at most 300`) — before the code runs. A `text` param
+    bound to a number arrives as its digits. The manifest keeps the rules, so the platform's sandbox checks the same.
+  - **`taskAction(task, { trigger })`** (`@plitzi/sdk-authoring`): the action that runs one of the space's tasks and
+    answers its result, derived from the task — its id (`<namespace>-<action>`), name, description and input (the task's
+    params, once). An action of more than one step is still `defineAction`.
+  - **`ctx.rateLimit(bucket, { …, refuse })`**: past the limit the call is refused with those words instead of answering
+    `allowed: false` for the code to check — natively and in the sandbox.
+
+  ## Authoring
+  - **`runServerActionOrNotify(id, params, fallback)`**: a server action run and the notice the visitor reads when it
+    fails — the action's own refusal, or the fallback — as two steps to spread into a flow.
+  - **`repeated-shape` reads what copies bind**: copies whose bindings read their data in different forms (a count, a
+    total of a quota) and copies holding a provider resolved on the server (found by its own id) are no longer offered
+    as one component.
+  - **`element-color-inherited`** (suggestion): `elements` giving a heading, a text, a link… `color: inherit` or the
+    page's own colour. **A link inherits the page's colour** (`@plitzi/plitzi-sdk`, `@plitzi/sdk-elements`) rather than
+    holding the SDK's grey — the same by default, and the space's palette inside a card that is a link. The template
+    every space starts from writes its colours once, on the page.
+
+  ## Fixes
+  - **A dialog opened with an id** (`@plitzi/sdk-elements`): `openDialog('dialog', '{{ row.id }}')` reads the id as its
+    `content`, as `openModal` already did — a numeric id parsed as the number and the dialog's bindings read nothing.
+  - **A select's chevron** (`@plitzi/plitzi-sdk`): a drawn chevron in the field's own colour, sized by its type, in place
+    of the `▼` glyph — and laid out in the box, so it ends where the box's padding begins whatever that padding is, and
+    the chosen option stops short of it instead of running under it. A disabled select's is faded.
+  - **Every element has its settings** (`@plitzi/plitzi-builder`, `@plitzi/sdk-elements`): the builder found none for
+    `tabContainerHeader` (registered under a misspelt type), `themeToggle`, `dropdownPopup`, `loading` and `notFound`.
+    The theme toggle's panel sets its mode, its labels and whether it offers "System"; the registry is typed by element
+    type and must hold one for each.
+  - **A plugin's panel** (`@plitzi/cli`): `plitzi doctor` warns of a plugin with no `Settings.tsx`, or one its entry never
+    passes as `pluginSettings` (`plugin-settings-missing`); the example `create` writes has its panel, as every element
+    `plugin add` writes does, and the panels it generates are laid out as the project's Prettier lays them out.
+  - **A refused or failed run reaches `onFlowError` in every mode** (`@plitzi/sdk-interactions`): an awaited server
+    action the server refused fired no `onFlowError` on the element that started it, as `detached` and `stream` ones do
+    — a board rolling its edits back on a refusal never did; and a run answered `status: 'failed'` fired `onFlowEnd`
+    (detached) or nothing (awaited) rather than `onFlowError`.
+  - **A source renamed** (`@plitzi/sdk-shared`): the binding picker lists a provider, a form or a modal by the name its
+    element has now, not the one it had when it mounted.
+  - **A text's words in the builder** (`@plitzi/sdk-elements`): a `paragraph`, `text` or `heading` whose `content` is
+    `0` shows `0` while editing too, not its placeholder; one bound to nothing shows nothing rather than `null`.
+  - **Built-in declarations** (`@plitzi/sdk-shared`): `elementDeclaration` fills in what every element shares — the
+    builder's gestures, Plitzi's catalogue entry, a visible element with no bindings, its style named by its label —
+    from the defaults `definePlugin` uses; each element's declaration says only what is its own (a third of the lines).
+
+  ## Typed for plugins and hosts
+  - **`usePlitzi()` and `PlitziProvider`** (`@plitzi/sdk-shared/hooks/usePlitzi`, `@plitzi/plitzi-sdk`): what were
+    `usePlitziServiceContext()` and `PlitziServiceProvider` (and `PlitziServiceContextValue`, now `PlitziContextValue`),
+    holding only what the host rendering a space knows — `settings`, `root`, `utils`. Its `contexts` and
+    `customContexts` are gone: every context it carried is a shared one already, imported from its own module
+    (`@plitzi/sdk-interactions/InteractionsContext`, `@plitzi/sdk-shared/network/NetworkContext`…), and
+    `PluginsContext` moves to `@plitzi/sdk-shared/plugins/PluginsContext` beside the others.
+  - **`InteractionsManagerApi`** (`@plitzi/sdk-shared`): the interactions manager as everything outside
+    `@plitzi/sdk-interactions` reaches it, declared where every package can name it and implemented by
+    `InteractionsManager`, so `use(InteractionsContext)` is typed — `interactionTrigger`, `createChildManager`… — where it
+    was `any`.
+  - **`getPathsFromObject`** (`@plitzi/sdk-shared/helpers/utils`), spelt right; `getPathsFromObeject` is gone.
+  - **`ElementWords` places itself** (`@plitzi/sdk-elements`): `contentPlacement` and the element's children, so a button
+    and a link write their words once.
+
+- Updated dependencies [1301338]
+  - @plitzi/sdk-authoring@0.38.12
+
 ## 0.38.11
 
 ### Patch Changes

package/README.md

@@ -160,7 +160,8 @@ with its fix). A plugin is declared by its folder: the server, `author` and `pag
 `src/plugins/<Name>/declaration.ts` (`pluginDeclarations` from `@plitzi/sdk-authoring/node`). What the server does
 besides serving the space is the project's own, in files it reads: `src/config/serverOptions.ts` (handed to `serveProject` —
 `images`, `action.limits`, `action.kv`, `rsc`) and, with `--source local`, `src/actions/index.ts` (the space's server
-actions, one `defineAction` each, a file each as they grow).
+actions, one `defineAction` each — `taskAction(task, { trigger })` for one that only runs a task — a file each as they
+grow).
 What `serveProject` wires itself — where the space comes from, the plugins, `public/`, `src/data/`, `src/functions/`,
 the actions' lookups — is left out of `serverOptions`' type (`ProjectServerOptions`), and comes after it, so an option
 there can never unwire it.
@@ -427,8 +428,8 @@ What a name means when authoring, from the catalogues the checks themselves read
 otherwise be a search through the SDK's types. A name no catalogue holds — `pageFamily`, `styles`, `SpaceSpec` — is any
 export of `@plitzi/sdk-authoring`, answered from the `.d.ts` the project installed, so it is the version the project
 runs. An element of the project's own — `src/plugins/<Name>/` — is explained by its type the same way: what it takes
-(each attribute at its default), fires and answers, and the `custom({ … renderType })` that places it, which `plugin
-add` prints too. `--json` answers in one object; over MCP it is `plitzi://explain/{name}`.
+(each attribute at its default), fires and answers, and how it is placed — its declaration imported and
+`defineElement(declaration)` called — which `plugin add` prints too. `--json` answers in one object; over MCP it is `plitzi://explain/{name}`.
 
 ## `doctor`
 
@@ -485,7 +486,7 @@ did you mean `index.ts`, `src/plugins/`? — and one that differs only in case s
 | `machinery` | the CLI's files (`MACHINERY`), as `upgrade` sees them: gone, behind, or the project's own (said, never failed); one it no longer writes, left over (`src/env.ts`); the scaffold record |
 | `config` | `tsconfig.json` reads `src/` and `plitzi/` and sets what Node's type stripping needs; `tsconfig.build.json` writes the file `start:prod` runs; `.gitignore` keeps `.env` out (and `node_modules`, `tmp`, `dist`, `state`) and `.plitzi/` in; `.env` not in git; the signing secret, as long as the project's own server wants it; a cloud project's key |
 | `sources` | what Node runs as written — `src/main.ts`, `src/config/`, `src/actions/`, `src/space/`, `src/runtime/`, `plitzi/author.ts`, the plugins' declarations, and all they import: every relative import a file that is there, with its extension; JSON imported `with { type: 'json' }`; no JSX; every package declared (a devDependency, in what production runs, is said); what the server loads by name exported (`space`, `actions`, the runtime's default) |
-| `plugins` | each folder of `src/plugins/` the server can build: its entry builds and exports its component, its packages declared; its `declaration.ts` loads and its `type` is the folder's (`StatCard` → `statCard`) |
+| `plugins` | each folder of `src/plugins/` the server can build: its entry builds and exports its component, its packages declared; its `declaration.ts` loads and its `type` is the folder's (`StatCard` → `statCard`); its `Settings.tsx`, the panel the builder edits it with, written and passed as `pluginSettings` — even with nothing to set |
 | `data` | every JSON file of `src/data/` and `public/data/` parses — what the server answers with and `space push` sends |
 | `functions` | `src/functions/` built by the project's own `@plitzi/sdk-server` (`buildFunctions`), as every runner builds them |
 | `records` | `.plitzi/space.json`, `scaffold.json` and `functions.json` readable, and of the same space |
@@ -604,14 +605,15 @@ said before anything is sent, with what to do: a provider reading a file `src/da
 
 Adds elements of your own to the project you are in — one, several at once (`plugin add seat-picker legend`), or one at
 a time as the need comes. Each is a folder, written the way Plitzi's own elements are (`@plitzi/sdk-elements`): the
-component, its `declaration.ts` (its `type`, the events it fires, the actions it answers to, and the element the builder
-adds), its `Settings.tsx` panel for the builder, and the `index.ts` that puts them together — what the folder is built
+component, its `declaration.ts` (`definePlugin` from `@plitzi/sdk-authoring/plugin`: its `type`, the events it fires,
+the actions it answers to, its defaults — the element the builder adds is derived from them), its `Settings.tsx` panel for the builder, and the `index.ts` that puts them together — what the folder is built
 from: `index.ts`, or `index.tsx` for one that writes its JSX there, never both. It asks what to call each, what the
 builder shows, and what it is for, and checks every folder is free before writing any.
 
 - **In a project `plitzi create` wrote**, it goes in `src/plugins`, where the project already looks: nothing to
-  register, and a running `start:dev` picks it up without a restart. Host it with `custom({ renderType: 'seatPicker' })` in `src/space/`
-  — or, when the space lives in Plitzi, with a Custom element in the builder.
+  register, and a running `start:dev` picks it up without a restart. Place it in `src/space/` from its declaration —
+  `defineElement(declaration)`, then `seatPicker({ id: 'seats' })` — or, when the space lives in
+  Plitzi, pack and upload it and add it in the builder.
 - **In a plugin package**, it goes in `src/`, and is added to `src/elements.ts` and `src/declarations.ts`, from which
   the package publishes it.
 - **In any other project**, it asks which folder holds the project's components (`--dir` answers it) and prints how
@@ -628,7 +630,8 @@ plitzi plugin add ticker --prop interval:number=5000 --prop paused:boolean --tri
 `--prop name:type=default` (string, number or boolean) is an attribute: in the props, the declaration's defaults and
 `bindingsAllowed`, and a control in `Settings.tsx`; `--prop rows:list` and `--prop meta:json` are data a binding fills
 (`unknown[]`, `Record<string, unknown>`, empty until it does). `--trigger onTick:count,at` is an event and what a flow
-started by it reads, fired with the `useTickerEvents()` hook it gets — never on the builder's canvas. `--callback reset`
+started by it reads, fired with `usePluginTrigger(declaration)` — `fire('onTick', { count, at })`, typed by the
+declaration, and never on the builder's canvas. `--callback reset`
 is an action a flow can call. `--headless` is an element with nothing to see: hidden on a page, a badge in the builder,
 and `drawsNothing` in its declaration, so a page check does not look for it. The files are written as the project's
 Prettier writes them.
@@ -696,7 +699,6 @@ plitzi source pack src/runtime/index.ts --kind runtime --name runtime -o runtime
 
 What `plugin upload` and `runtime push` keep, written to a file to look at: the closure of the entries named, gzipped.
 
-
 ## `login`, `space use` and `plugin upload`
 
 ```bash