@cratis/pi 7.99.0 → 7.100.0

package/package/corpus/skills/cratis-components-toolbar/SKILL.md

@@ -204,6 +204,10 @@ consumer, ordered ascending by `order` (default `0`). `useToolbarSlot(slotName)`
 returns the current content for a custom consumer. `ToolbarContext` also accepts
 a `slotName`.
 
+In a Screenplay model the same idea is authored, not coded: a `feature` or `module` adds buttons to the `toolbar` slot of every
+screen beneath it and links each to a command of the feature (see `cratis-screenplay-ui-composition`, "Feature and module
+toolbars"). Use the slot components above only when writing the React application by hand.
+
 ## Props
 
 ### `Toolbar`

package/package/corpus/skills/cratis-screenplay-model-authoring/references/screen-authoring-workflow.md

@@ -170,6 +170,15 @@ open, read, propose, review, apply, reopen loop; the syntax and rules are in
 5. Switching a module from inherit to override copies the application's items; retarget each copy to the module's own
    features first or the proposal is refused.
 
+### Feature and module toolbars
+
+A feature (or module) toolbar is a `ScreenToolbarSyntax` in the `toolbars` member of its `FeatureSyntax` (or `ModuleSyntax`);
+`syntax-schema` for `FeatureSyntax` lists `toolbars`. `add` a `ScreenToolbarSyntax` with `name`, `items` and `buttons` to the
+feature, and `replace` a `ToolbarButtonSyntax` or `ToolbarItemSyntax` to set its `confirm` text; `remove` takes a button away.
+Read the proposal's diagnostics: a warning says an `item ... action` names a command no slice of that feature (or module)
+declares. The syntax, the `confirm` rule and when to prefer the feature toolbar are in `cratis-screenplay-ui-composition`
+(`references/application-shell.md`, "Feature and module toolbars"; Screenplay 4.238.0 or later).
+
 ### The profile's shell
 
 `ui-profiles` (Screenplay 4.201.0 or later) reads each `ui profile`'s root template, shell options, appearance, new screens default and

package/package/corpus/skills/cratis-screenplay-ui-composition/SKILL.md

@@ -225,7 +225,8 @@ module Sales
 ```
 
 Read [references/application-shell.md](references/application-shell.md) before writing any of it: the inherit/extend/override
-choice, item target and slot, the module-only target rule (`PLAY0750`), buttons, blueprint ranges, sample data, MCP editing
+choice, item target and slot, the module-only target rule (`PLAY0750`), buttons, feature and module toolbars (`toolbar` in a
+`feature` or `module`, `confirm`), blueprint ranges, sample data, MCP editing
 and the review checklist. `contribute to Navigation` stays the flat contribution; a new application uses regions.
 
 ## Interactions — what a click does
@@ -297,7 +298,7 @@ Localized text lives in companion `.strings` files and is referenced unquoted as
 - [ ] No `file` reference is doing work the declaration should be doing.
 - [ ] Every click, submit and screen entry that does something has an `on` or
       `uses`; continuations sit only on actions that can fail.
-- [ ] Navigation regions, slice buttons, blueprint references and sample data follow `references/application-shell.md`: each module's mode is deliberate, no module item targets another module, every button names a State Change slice, every template has a `category`, and the active sample data pack is chosen once in the `ui profile`.
+- [ ] Navigation regions, slice buttons, blueprint references and sample data follow `references/application-shell.md`: each module's mode is deliberate, no module item targets another module, every button names a State Change slice, buttons shared by a feature's screens sit in a feature `toolbar` linked to its commands (`confirm` on destructive ones), every template has a `category`, and the active sample data pack is chosen once in the `ui profile`.
 - [ ] Component bindings, exposed template values, manual form columns, toolbar items, outlets and routes all trace to typed data; no runtime fallback counts as delivery. Report authoring acceptance, executable admission and runtime
       implementation separately.
 

package/package/corpus/skills/cratis-screenplay-ui-composition/references/application-shell.md

@@ -6,6 +6,7 @@
 - One complete shell
 - Navigation regions: inherit, extend or override
 - Toolbar buttons that invoke a State Change slice
+- Feature and module toolbars
 - Template references, categories and blueprints
 - Sample data packs
 - Shapes the compiler refuses
@@ -195,6 +196,41 @@ layout AppShell
 ⚠️ When a screen uses a `template`, put the `toolbar` inside a slot body (`body` above). Stage refuses a screen that
 mixes a top-level `template` directive with other top-level directives.
 
+## Feature and module toolbars
+
+Requires Screenplay 4.238.0 or later (`screenplay --version`); an older compiler refuses `toolbar` in a `feature` or `module`.
+
+A template declares a `toolbar` slot. When the same actions belong to every screen of a feature, write the toolbar once on the
+`feature` (or on the `module` for every feature below it) instead of repeating it on each screen: the entries are contributed to
+the `toolbar` slot of every screen beneath it, sub features included, after the screen's own entries (the nearer toolbar comes
+later), and each entry runs one command of the feature. A screen that needs its own buttons keeps its own `toolbar`.
+
+```text
+module Merchandising
+  feature Publication
+    toolbar actions
+      button approve title "Approve product" slice Merchandising.Publication.ApproveProductForSale emphasis primary icon check
+      button withdraw title "Withdraw product" slice Merchandising.Publication.WithdrawProduct emphasis quiet icon ban
+        confirm "Take this product off sale?"
+      item archive action ArchiveProduct
+        label "Archive"
+        icon archive
+```
+
+- The lines are the ones of a screen toolbar: `item <id> action <Command>` and `button <id> title "<text>" slice <Slice>`, with
+  the `PLAY0761`-`PLAY0765` rules above.
+- `confirm "<text>"` (or a `$strings.<key>` token) is an optional child line of an `item` and of a `button`: the user confirms
+  before the command runs or before the button's dialog opens. Use it for destructive or hard-to-undo commands, not for every entry.
+- An `item ... action <Command>` must name a command that a slice of the feature (or module) declares; otherwise the compiler
+  warns that the command is not the feature's. Fix the name or move the toolbar to the feature that owns the command; never silence the warning.
+- Choose the feature toolbar when the buttons act on the feature as a whole (approve, withdraw, new). A button that needs the row
+  the user picked (a row action) stays an `item ... action` on the screen's table or list, because the toolbar has no row.
+- Preview and Play open the command's form dialog for an entry (or run it after the confirmation); Studio's feature editor has a
+  Toolbar section that adds a button and links it to a command of the feature. All of it is authoring syntax like every screen
+  construct: the printer writes it back where it was written.
+- Verify: `screenplay <model> --warnaserror` is clean (no warning about a command the feature does not declare), then Preview or Play a screen of the feature and see the
+  buttons in the template's toolbar; a destructive one asks first.
+
 ## Template references, categories and blueprints
 
 - Every `layout`, `screen template` and `dialog template` declares a `category`; a template picker groups by it, and a
@@ -323,5 +359,6 @@ pass. Propose, show the difference, apply, reopen. Details: `cratis-screenplay-m
 - [ ] Hierarchy is in the sidebar; sub-items target features of the parent's module.
 - [ ] Every button names a State Change slice; none is left without a slice.
 - [ ] A screen with a `template` keeps its toolbar inside a slot body.
+- [ ] Buttons shared by every screen of a feature sit in a feature `toolbar`, each linked to a command of that feature, with `confirm` on the destructive ones.
 - [ ] Every template has a `category`; every blueprint reference has a valid range and is listed in a profile's `packages`.
 - [ ] The active sample data pack is selected once, in the `ui profile`, and no sample value sits in a component.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.99.0",
+  "version": "7.100.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [