@cratis/pi 2.22.0 → 2.23.1

package/package/corpus/rules/components.md

@@ -7,54 +7,66 @@ profile: application
 
 # Building React Components
 
-## Cratis Components — pick the wrapper, import from subpaths
+The frontend is composed from **Cratis Components** (`@cratis/components` **4.x**). Components owns its markup, styling contract and public types; React Aria supplies focus, overlay, collection and date behavior *internally* — you never import or style it. Components declares **no** PrimeReact, PrimeIcons or PrimeUI dependency or peer, and it ships no vendor CSS. PrimeReact (11 and 10) and MUI exist only as optional *presentation adapters* (`@cratis/components.primereact`, `.primereact10`, `.mui`) that adapt nine primitive slots — button, icon-button, text input, text area, checkbox, radio, switch, progress bar, surface — and nothing else. Dialogs, dropdowns, tables, date pickers, toasts and steppers are always Components-owned.
 
-Reach PrimeReact almost exclusively through Cratis Components wrappers. Import from **subpaths**, not the root barrel (the barrel pulls optional-peer-heavy exports):
+## Import from subpaths — the root is setup-only
+
+The package root exports **only** setup (`CratisComponentsProvider`, configuration and message types). Every component ships from its own subpath; the Components 3 root namespaces are gone, and `@cratis/eslint-plugin-components`' `no-root-barrel-import` keeps them gone.
 
 | Need | Use | Subpath |
 |---|---|---|
-| Page chrome | `Page` | `@cratis/components/Common` |
-| Query list page | `DataPage` | `@cratis/components/DataPage` |
-| Standalone query table | `DataTableForQuery` / `DataTableForObservableQuery` | `@cratis/components/DataTables` |
-| Form section | `FormElement` | `@cratis/components/Common` |
-| Icon | `Icon` / `IconDisplay` | `@cratis/components/Common` |
+| App root | `CratisComponentsProvider` | `@cratis/components` |
+| Page chrome, buttons, basic controls | `Page`, `Button`, `IconButton`, `TextInput`, `TextArea`, `NumberInput`, `Checkbox`, `Radio`, `Switch`, `Tooltip`, `ErrorBoundary`, `FormElement`, `ComboBox` (≥ 4.6.0 — single-selection, text-searching entity picker) | `@cratis/components/Common` |
+| Icon | `Icon` (type) / `IconDisplay` | `@cratis/components/Common` |
+| Query list page | `DataPage`, `MenuItem`, `Column` | `@cratis/components/DataPage` |
+| Standalone query table | `DataTableForQuery` / `DataTableForObservableQuery`, `Column` | `@cratis/components/DataTables` |
 | Dropdown | `Dropdown` | `@cratis/components/Dropdown` |
-| Command dialog | `CommandDialog` / `StepperCommandDialog` | `@cratis/components/CommandDialog` |
-| Data/confirmation dialog | `Dialog` / `ConfirmationDialog` / `BusyIndicatorDialog` | `@cratis/components/Dialogs` |
-| Command form fields | `InputTextField`, `PasswordField`, `ToggleSwitchField`, `RatingField`, … | `@cratis/components/CommandForm` |
-| Notifications (toasts) | `Toaster` / `toast` / `toastCommandResult` | `@cratis/components/Notifications` |
-| Status & display | `Tag` / `Badge` / `Chip` / `Skeleton` / `Avatar` / `ProgressBar` | `@cratis/components/Display` |
-| Canvas tool palette | `Toolbar` | `@cratis/components/Toolbar` |
+| Command dialog | `CommandDialog`, `StepperCommandDialog`, `StepperPanel` | `@cratis/components/CommandDialog` |
+| Standalone stepper | `CommandStepper` | `@cratis/components/CommandStepper` |
+| Data / confirmation / busy dialog | `Dialog`, `ConfirmationDialog`, `BusyIndicatorDialog` | `@cratis/components/Dialogs` |
+| Command form fields | `InputTextField`, `NumberField`, `DropdownField`, `CheckboxField`, `CalendarField`, …, `AutoCommandForm` | `@cratis/components/CommandForm` |
+| Notifications | `Toaster`, `toast`, `toastCommandResult` | `@cratis/components/Notifications` |
+| Status & display | `Tag`, `Badge`, `Chip`, `Skeleton`, `Avatar`, `ProgressBar`, `ProgressSpinner`, `Message` | `@cratis/components/Display` |
+| Canvas tool palette | `Toolbar`, `ToolbarButton`, … | `@cratis/components/Toolbar` |
+| Shared types | `JsonSchema`, `Json`, … | `@cratis/components/types` |
 
-Use `Dropdown` from `@cratis/components/Dropdown` (not raw `primereact/dropdown`) — it appends to the document body and stacks correctly above overlays, avoiding the z-index issues raw PrimeReact dropdowns have inside dialogs.
+Use `Dropdown` from `@cratis/components/Dropdown`, never a vendor select: it renders through the Components overlay environment, so it stacks correctly above dialogs, and it follows the WAI-ARIA button/listbox (or combobox, when `filter` is on) pattern. Its `onChange` receives the **value**, not an event — as do every CommandForm field's.
 
 ### Notifications — feedback for commands run outside a dialog
 
 `CommandDialog` handles success/error feedback itself. For a command executed
-**programmatically** (`command.execute()` outside a dialog), mount one
-`<Toaster />` near the app root and surface the result with `toastCommandResult`
-(both from `@cratis/components/Notifications`) — it maps the granular
-`ICommandResult` flags to the right toast (success, not-authorized, validation
-with per-field messages, exceptions — never stack traces):
+**programmatically** (`command.execute()` outside a dialog), mount the toast region once —
+`toaster` on `CratisComponentsProvider`, or one `<Toaster />` near the root — and surface the result
+with `toastCommandResult` (`@cratis/components/Notifications`). It maps the granular
+`ICommandResult` flags to the right toast (success, not-authorized, validation with per-field
+messages, exceptions — never stack traces):
 
 ```tsx
 const result = await command.execute();
 if (toastCommandResult(result, { successTitle: 'Author registered' })) refresh();
 ```
 
-For ad-hoc notifications, call the imperative `toast.success/info/warn/error(...)`
-— each takes an **options object**, not a bare string: `toast.info({ title: 'Saved', description: '…' })`.
+For ad-hoc notifications, call the imperative `toast.success/info/warn/error(...)` — each takes an
+**options object**, not a bare string: `toast.info({ title: 'Saved', description: '…' })`.
 
 ### Column filtering & display components
 
-`<Column>` supports `filter` (a per-column filter menu with match modes) and
-`DataPage` / the data tables show a global search box when `globalFilterFields`
-is set. Use the `Display` components (`Tag`, `Badge`, `Skeleton`, …) for status
-indicators and loading states in tables and detail views.
+`<Column>` supports `sortable` and `filter` (a per-column filter popup with match modes), and
+`DataPage` / the data tables show a search box when `globalFilterFields` is set. **Sorting and
+filtering apply to the currently loaded page**; complete-result filtering belongs in the query's
+arguments and the server-side query, before paging (`clientFiltering` is a deprecated no-op). Use the
+`Display` components (`Tag`, `Badge`, `Skeleton`, …) for status indicators and loading states.
 
 ### `DataPage` — query list pages
 
-`DataPage` (from `@cratis/components/DataPage`) owns the data table's subscription, paging, selection, action menubar, and details split — **do not pre-fetch rows and pass an `items` array**. Required props: `title`, `query` (`Constructor<TQuery>`; snapshot and observable queries are auto-detected), `emptyMessage`, and `children`. Other props: `queryArguments`, `dataKey` (pass whenever the read model has an identity), `selection` / `onSelectionChange`, `globalFilterFields` / `defaultFilters` / `clientFiltering`, `detailsComponent` (`React.FC<IDetailsComponentProps<T>>` = `{ item, onRefresh? }`), `onRefresh`, and PrimeReact pass-through `tablePt`/`tableClassName`/`menubarPt`/`menubarClassName`.
+`DataPage` (from `@cratis/components/DataPage`) owns the data table's subscription, paging,
+selection, action menubar, and details split — **do not pre-fetch rows and pass an `items` array**.
+Required props: `title`, `query` (`Constructor<TQuery>`; snapshot and observable queries are
+auto-detected), `emptyMessage`, and `children`. Other props: `queryArguments`, `dataKey` (pass
+whenever the read model has an identity), `selection` / `onSelectionChange`, `globalFilterFields` /
+`defaultFilters`, `detailsComponent` (`React.FC<IDetailsComponentProps<T>>` = `{ item, onRefresh? }`),
+`onRefresh`, and the Cratis part props `tablePt: DataTableParts` / `paginatorPt: TablePaginatorParts`
+/ `menubarPt: ButtonParts` (plus `tableClassName` / `menubarClassName`).
 
 Columns and toolbar actions are compositional children:
 
@@ -71,7 +83,10 @@ import { DataPage, MenuItem, Column } from '@cratis/components/DataPage';
 </DataPage>
 ```
 
-`MenuItem` is a PrimeReact menu item (use `command`, not `onClick`); `disableOnUnselected` greys it out until a row is selected. See the **cratis-react-page** skill for the full page workflow.
+`MenuItem` is a declarative Components element read by `DataPage.MenuItems` (use `command`, not
+`onClick`); `disableOnUnselected` greys it out until a row is selected; its `icon` is a **React
+component type** (e.g. a `react-icons` icon), not an `Icon`. See the **cratis-arc-react-page** skill
+for the full page workflow.
 
 ## Composition over Monoliths
 
@@ -100,33 +115,48 @@ Add an `index.ts` that re-exports the public surface so import paths stay stable
 
 ## Styling
 
-Consistent styling comes from discipline: static styles in CSS files, dynamic values inline, and colors always from PrimeReact's design tokens. This ensures theming works automatically and no component breaks the visual language.
+Consistent styling comes from discipline: static styles in CSS files, dynamic values inline, and colors always from the `--cratis-*` design tokens. This ensures theming works automatically and no component breaks the visual language.
 
 ### App setup — the imports Cratis Components needs
 
-From `@cratis/components` **3.0.0** (PrimeReact 11), an app must do two things or the components render unstyled and PrimeReact may end up with two React contexts:
+An app does three things, once, at its root — or the components render unstyled:
 
-1. **Install PrimeReact yourself** — it is a **peer dependency**, not bundled: `primereact@^11`, `@primereact/core@^11`, `@primereact/headless@^11`, `primeicons@^8`. Two copies of PrimeReact means two `PrimeReactProvider` contexts, which breaks overlays and `pt` silently. Delete any `resolutions`/`overrides` pin that used to work around this.
-2. **Import the stylesheets explicitly**, in this order — components no longer import their own CSS:
+1. **Import the stylesheets, in this order** — components do not import their own CSS:
 
    ```ts
-   import '@cratis/components/tokens';   // the --cratis-* layer every component reads
-   import '@cratis/components/styles';   // every component stylesheet, in one file
-   import '@cratis/components/theme';    // optional: the license-free baseline look
+   import '@cratis/components/tokens';   // the semantic --cratis-* variables every component reads
+   import '@cratis/components/styles';   // structural rules for every component, in low-priority Cratis layers
+   import '@cratis/components/theme';    // optional: the baseline light/dark look (auto, or `cratis-dark`/`cratis-light`)
    ```
 
-PrimeReact 11 ships **zero CSS** — there is no `primereact/resources/themes/*.css`. A styled look comes from a `@primeuix/themes` preset passed through the provider (`value={{ theme: { preset: Aura } }}`, license-gated), from `@cratis/components/theme` (no license), or from your own `pt`/CSS.
+   A product with its own design system omits `theme`, defines the `--cratis-*` variables itself, and imports those values *after* the two Components entries so they win the cascade.
+
+2. **Mount `CratisComponentsProvider`** (from the package root) around the app. Its `value` carries `locale` (BCP 47 — drives dates, numbers, keyboard behavior and announcements) and `messages` (the Components-owned labels for `paginator`, `datePicker`, `dropdown`, `dialog`, `stepper`, `notifications`, `dataTable`, `columnFilter`, `toolbar`); `toaster` mounts the toast region. Renderer keys from Components 3 — `license`, `theme`, `pt`, `ripple`, `unstyled`, z-index — are a **type error**, on purpose. Keep the `value` object stable when it carries a large message catalog.
 
-### Writing styles inside the library
+   ```tsx
+   import { CratisComponentsProvider } from '@cratis/components';
+
+   export const App = () => (
+       <CratisComponentsProvider value={{ locale: 'en-US' }} toaster>
+           <Application />
+       </CratisComponentsProvider>
+   );
+   ```
 
-- Use **CSS classes in co-located `.css` files** for static styles, and add an `@import` for each new stylesheet to `Source/styles.css` — the build fails if a component stylesheet is not reachable from that manifest. **Never** add `import './Foo.css'` to a `.tsx`: a CSS file in the JavaScript module graph is what made the published package unloadable in Node (Cratis/Components#118).
-- Each component must have its own CSS file — never add sub-component styles to the parent's CSS. This keeps styles co-located with the component they belong to.
+3. **Install nothing else.** No PrimeReact, no PrimeIcons, no theme preset, no vendor provider. Only if the product wants a vendor's *look* on the nine primitive slots does it install one adapter package and pass its manifest to the provider's `library` prop — and the vendor's own provider, theme and license then stay the application's, outside Components.
+
+### Writing styles
+
+- Use **CSS classes in co-located `.css` files** for static styles; each component has its own CSS file — never add sub-component styles to the parent's CSS.
 - The composition root's CSS only contains layout/grid rules for positioning children — it should not style the children themselves.
 - Use inline `style` props **only** for runtime-dynamic values (pixel positions, computed sizes).
-- Use **PrimeReact CSS variables** for all colors, backgrounds, borders. This ensures the application respects theming and dark/light mode switches:
-  - `var(--surface-0)` through `var(--surface-900)`, `var(--surface-card)`, `var(--surface-border)`, `var(--surface-ground)`
-  - `var(--text-color)`, `var(--text-color-secondary)`, `var(--primary-color)`, `var(--primary-color-text)`, `var(--highlight-bg)`
-  - Never hard-code hex or `rgb()` for UI chrome — it will break when themes change. Only hard-code colors that are intentionally theme-independent (e.g. brand-specific accent dots, traffic-light indicators).
+- Use the **`--cratis-*` tokens** for every color, background, border, shadow and radius, so theming and dark mode work automatically:
+  - surfaces — `var(--cratis-surface-0)`, `var(--cratis-surface-100)`, `var(--cratis-surface-card)`, `var(--cratis-surface-ground)`, `var(--cratis-surface-section)`, `var(--cratis-surface-overlay)`, `var(--cratis-surface-hover)`, `var(--cratis-surface-border)`
+  - text & accent — `var(--cratis-text-color)`, `var(--cratis-text-color-secondary)`, `var(--cratis-primary-color)`, `var(--cratis-primary-color-text)`, `var(--cratis-highlight-bg)`, `var(--cratis-highlight-text-color)`, `var(--cratis-focus-ring)`
+  - status — `var(--cratis-success-background)`/`-text`, `var(--cratis-warning-*)`, `var(--cratis-danger-*)`, `var(--cratis-info-*)`
+  - shape — `var(--cratis-border-radius)`, `var(--cratis-control-height)`, `var(--cratis-shadow-subtle)`/`-overlay`/`-dialog`
+  - Never hard-code hex or `rgb()` for UI chrome. Only hard-code colors that are intentionally theme-independent (brand accent dots, traffic-light indicators).
+- **Reach inside a component through its parts, not its DOM.** Every meaningful element carries `data-cratis-part="<name>"` and state attributes (`data-selected`, `data-invalid`, `data-disabled`, `data-active`, `data-position`). Style them with those selectors, or pass per-part attributes through the component's `pt` prop typed by its `*Parts` type (`DialogParts`, `StepperParts`, `DataTableParts`, `TablePaginatorParts`, `ButtonParts`, the `Toolbar*Parts` family). Never target React Aria class names or the internal element structure — they are not a contract.
 - Name CSS classes with a BEM-like prefix matching the component name.
 
 ## Props
@@ -136,16 +166,19 @@ Props are a component's public API. They should be clear, minimal, and well-docu
 - Each sub-component declares its own `*Props` interface with JSDoc on every prop.
 - Pass only needed props — avoid threading large prop bags through component trees.
 - Event handlers follow `on*` naming: `onPointerDown`, `onSelect`.
+- Model visual variation the way `Button` does — one typed `variant` (`solid | outline | ghost | link`), one `tone` (`neutral | accent | positive | caution | critical`), one `shape` — not a pile of boolean flags.
 
 ## Dialogs
 
 See [dialogs.md](./dialogs.md) for the full dialog guide.
 
-**Summary:** Never import `Dialog` from `primereact/dialog`. Use `CommandDialog` from `@cratis/components/CommandDialog` for command-executing dialogs and `Dialog` from `@cratis/components/Dialogs` for data-collection dialogs. Do not render manual `<Button>` components for dialog actions — the dialog components handle footers.
+**Summary:** Use `CommandDialog` from `@cratis/components/CommandDialog` for command-executing dialogs and `Dialog` from `@cratis/components/Dialogs` for data-collection dialogs; confirmations and busy indicators are raised through hooks, never built. Never import a vendor dialog. Do not render manual `<Button>` components for dialog actions — the dialog components handle footers.
 
 ## Icons
 
-Follow these rules when working with SVG icons:
+Components accepts an **`Icon`** (`@cratis/components/Common`) wherever a control takes an icon: either a React node — preferred — or a complete, consumer-owned icon-font class string. Components installs **no icon font**: a string is rendered on an `<i>` unchanged, so the product must load that stylesheet itself. `react-icons` is a Components dependency and the natural source of React icon nodes (`<FaHouse aria-hidden="true" />`). Not every `icon` prop has that shape — `DataPage.MenuItem.icon` is a React component *type* because the page instantiates it; follow the exported prop type.
+
+For the application's own SVG icons:
 
 - **Distinguish icons from status/interactive components.** A pure SVG icon is a simple presentational element. A component that wraps an icon with interactive behavior (e.g. a dropdown, tooltip, or complex state) is a _component_, not an icon — name it accordingly (e.g. `SliceStatus`, not `SliceStatusIcon`).
 - **Store each SVG as a separate `.svg` file** inside the icon's folder. Do not embed SVG markup directly in `.tsx` files.

package/package/corpus/rules/dialogs.md

@@ -7,14 +7,14 @@ paths:
 
 # Using Dialogs
 
-The Cratis dialog wrappers handle command execution, validation timing, loading states, and footer buttons consistently. Using PrimeReact's raw `Dialog` bypasses all of this and leads to inconsistent UX.
+The Cratis dialogs handle command execution, validation timing, busy state, focus, dismissal and footer buttons consistently. A vendor dialog, or a hand-rolled modal, bypasses all of this and leads to inconsistent UX — and a second focus trap around a Components dialog breaks keyboard and screen-reader behavior.
 
 ## Choose the Correct Dialog Type
 
 - If confirm executes a command, use `CommandDialog` from `@cratis/components/CommandDialog`.
 - If no command is executed on confirm, use `Dialog` from `@cratis/components/Dialogs`.
 - If you are **asking the user to confirm** or **showing that something is in progress**, do not build a dialog at all — raise the host-rendered one through its hook (below).
-- **Never** import `Dialog` from `primereact/dialog` directly.
+- **Never** use a vendor or hand-rolled modal. Dialogs are Components-owned; the optional renderer adapters do not replace them.
 
 ## Confirmations and busy indicators are host-rendered — register once, raise by hook
 
@@ -109,24 +109,24 @@ if (result === DialogResult.Ok) {
 
 ### `onBeforeExecute` is a transformer
 
-It receives the current command values and **must return them** (mutated or not). **Returning `void` executes the command with `undefined` values.** It runs only on submit — never use it to seed *required* values (validation runs against pre-transform state, so a value seeded here never makes the form valid and the submit button stays permanently disabled). Seed required values via `initialValues`; reserve `onBeforeExecute` for transforms that don't affect validity (e.g. a generated id).
+It receives the current command values and **must return them** (mutated or not). **Returning `void` does not execute with `undefined`** — the current values are kept and a `console.warn` is logged; still, always return the values. It runs only on submit — never use it to seed *required* values (validation runs against pre-transform state, so a value seeded here never makes the form valid and the submit button stays permanently disabled). Seed required values via `initialValues`; reserve `onBeforeExecute` for transforms that don't affect validity (e.g. a generated id).
 
 ### CommandForm fields
 
-Use built-in `CommandForm` fields (from `@cratis/components/CommandForm`) for every user-input value — a raw PrimeReact control inside a command dialog bypasses `CommandFormFieldWrapper`, so validation never re-runs and the submit button stays **permanently disabled**. Catalog: `InputTextField`, `PasswordField`, `NumberField`, `DropdownField`, `CheckboxField`, `ToggleSwitchField`, `TextAreaField`, `CalendarField`, `RadioButtonField`, `RadioGroupField`, `ChipsField`, `MultiSelectField`, `ColorPickerField`, `SliderField`, `RatingField`.
+Use built-in `CommandForm` fields (from `@cratis/components/CommandForm`) for every user-input value — a raw control (a `Common` `TextInput`, a native `<input>`) inside a command dialog is not bound to the command, so validation never re-runs and the submit button stays **permanently disabled**. Catalog: `InputTextField`, `PasswordField`, `NumberField`, `NumberInputField`, `DropdownField`, `CheckboxField`, `ToggleSwitchField`, `TextAreaField`, `CalendarField`, `RadioButtonField`, `RadioGroupField`, `ChipsField`, `MultiSelectField`, `ColorPickerField`, `SliderField`, `RatingField`. `AutoCommandForm` generates the field list from the command's properties (`string` → `InputTextField`, `number` → `NumberField`, `boolean` → `CheckboxField`, `Date` → `CalendarField`; other types need a registered field-type provider) — use it for plain forms, hand-write fields when the layout or a concept type needs it. Several `RadioButtonField`s bound to one property need the same explicit `name`.
 
-- The `value={c => c.name}` **accessor lambda doubles as the binding and type-checked field selection** — renaming a command property surfaces a compile error at every binding.
+- The `value={c => c.name}` **accessor lambda doubles as the binding and type-checked field selection** — renaming a command property surfaces a compile error at every binding. The binding is inferred from the accessor's *source text*, so a computed accessor (`c => c[descriptor.name]`) cannot be inferred — name it explicitly with `fieldName="…"` (Arc ≥ 22.16.0).
 - **`RadioGroupField<T>`** renders a whole group from data (`options`/`optionLabel`/`optionValue`, `layout='horizontal'|'vertical'`); **`RadioButtonField<T>`** is one component per option (each takes a `buttonValue`). Both infer the value type from the accessor — no `as string` casts.
 - **`asCommandFormField(Component, opts)`** (`asCommandFormField`, `WrappedFieldProps` from `@cratis/arc.react/commands`) wraps a custom input so it participates in `CommandForm` like a built-in. `WrappedFieldProps<T>` gives `{ value, onChange, invalid, required, errors }` (`errors` is `string[]` → `errors.join(', ')`); options are `{ defaultValue, extractValue: e => ... }`.
-- **`useCommandInstance(Command)`** (`@cratis/arc.react/commands`) returns the live reactive instance the form is bound to — **read** it to drive dependent fields (e.g. read `command.country` to choose a `DropdownField`'s options); never mutate (mutations go through field bindings).
+- **`useCommandInstance<TCommand>()`** (`@cratis/arc.react/commands`, no argument — reads the enclosing form's context) returns the live reactive instance the form is bound to — **read** it to drive dependent fields (e.g. read `command.country` to choose a `DropdownField`'s options); never mutate (mutations go through field bindings).
 
 ### Opening dialogs — `useDialog` / `useDialogContext`
 
-`useDialog<TResponse, TInput>(Component)` returns `[Wrapper, showFn]`: render `<Wrapper />` in JSX and call `showFn(input)` to open it; it resolves to `[DialogResult, TResponse?]` when the dialog closes. For a new dialog, prefer reading input as **plain typed props** (`<Name>Input`) and obtaining `closeDialog` from **`useDialogContext<TResponse>()`** — rather than declaring a props interface that extends `DialogProps` to thread both input and `closeDialog`. (Existing dialogs that destructure `closeDialog` from `DialogProps` remain valid.) Signal the outcome with `closeDialog(DialogResult.Ok | Cancelled, response?)`.
+`useDialog<TResponse, TInput>(Component)` returns `[Wrapper, showFn, context]` (the third element is rarely needed): render `<Wrapper />` in JSX and call `showFn(input)` to open it; it resolves to `[DialogResult, TResponse?]` when the dialog closes. For a new dialog, prefer reading input as **plain typed props** (`<Name>Input`) and obtaining `closeDialog` from **`useDialogContext<TRequest, TResponse>()`** (request type first) — rather than declaring a props interface that extends `DialogProps` to thread both input and `closeDialog`. (Existing dialogs that destructure `closeDialog` from `DialogProps` remain valid.) Signal the outcome with `closeDialog(DialogResult.Ok | Cancelled, response?)`.
 
 ### Multi-step wizards — `StepperCommandDialog`
 
-For a command split across named steps use `StepperCommandDialog` (`@cratis/components/CommandDialog`) — see the **stepper-command-dialog** skill. Conditional steps written as `{condition && <StepperPanel/>}` are supported **from 2.7.1**: only the steps that actually render are counted, so Next and Submit appear where the user expects them. ⚠️ On earlier versions a hidden step is still counted — Submit never appears on the real last step and a dead Next takes its place, so check what you are pinned to before relying on this. ⚠️ A `<>…</>` fragment wrapping several panels still counts as **one** step — give each step its own `StepperPanel` child. When a step needs non-CommandForm inputs, or cross-step state is complex, fall back to a manual `Dialog` + PrimeReact `Stepper`.
+For a command split across named steps use `StepperCommandDialog` (`@cratis/components/CommandDialog`) — see the **cratis-components-stepper-command-dialog** skill. Conditional steps written as `{condition && <StepperPanel/>}` are supported: only the steps that actually render are counted, so Next and Submit appear where the user expects them, and the active step is clamped if a late-resolving condition removes a step the user had passed. ⚠️ A `<>…</>` fragment wrapping several panels counts as **one** step — give each step its own `StepperPanel` child. Stepper parts are Cratis-owned (`root`, `list`, `step`, `header`, `number`, `title`, `separator`, `panels`, `panel`; `StepperParts` from `@cratis/components/CommandDialog`). When the wizard belongs inline in a page region rather than in a modal, use the sibling `CommandStepper` (`@cratis/components/CommandStepper`) — same steps, same command execution, no dialog chrome.
 
 ## When Using `Dialog`
 
@@ -136,7 +136,7 @@ Use this for dialogs that collect data and return it without executing a command
 import { useState } from 'react';
 import { DialogProps, DialogResult } from '@cratis/arc.react/dialogs';
 import { Dialog } from '@cratis/components/Dialogs';
-import { InputText } from 'primereact/inputtext';
+import { TextInput } from '@cratis/components/Common';
 
 export const AddProject = ({ closeDialog }: DialogProps<{ name: string }>) => {
     const [name, setName] = useState('');
@@ -150,10 +150,10 @@ export const AddProject = ({ closeDialog }: DialogProps<{ name: string }>) => {
             onConfirm={() => closeDialog(DialogResult.Ok, { name })}
             onCancel={() => closeDialog(DialogResult.Cancelled)}
         >
-            <InputText
+            <TextInput
                 value={name}
-                onChange={event => setName(event.target.value)}
-                autoFocus
+                onChange={value => setName(value)}
+                aria-label="Project name"
             />
         </Dialog>
     );
@@ -249,16 +249,20 @@ Use `buttons={null}` for dialogs that contain their own internal actions (e.g. a
 
 | Prop | Type | Notes |
 |---|---|---|
-| `title` | `string` | Header text (replaces PrimeReact `header`) |
-| `visible` | `boolean` | Controls visibility |
+| `title` | `string` | Header text |
+| `visible` | `boolean` | Controlled open state; defaults to `true` |
 | `buttons` | `DialogButtons \| ReactNode \| null` | Prefer `DialogButtons` enum; `null` for no footer |
 | `isValid` | `boolean` | Disables the confirm button when `false` |
-| `okLabel` | `string` | Override the Ok/Confirm button label |
-| `cancelLabel` | `string` | Override the Cancel button label |
+| `isBusy` | `boolean` | Disables every action **and every dismissal path** while work is in flight |
+| `initialFocus` | `DialogInitialFocus` | Where focus lands on open; defaults to the confirmation action — the **cratis-components-accessibility** skill covers the armed-Enter hazard |
+| `okLabel` / `cancelLabel` / `yesLabel` / `noLabel` | `string` | Per-dialog label; falls back to the provider's `messages.dialog`, then English |
+| `closeAriaLabel` | `string` | Accessible name of the header close button; same fallback chain |
 | `onConfirm` | `() => boolean \| void \| Promise<boolean> \| Promise<void>` | Called when Ok is clicked; return `false` to keep dialog open, `true` to close |
-| `onCancel` | `() => void \| Promise<void>` | Called when Cancel is clicked |
+| `onCancel` | `() => boolean \| void \| Promise<boolean> \| Promise<void>` | Called when Cancel is clicked |
 | `onClose` | `(result: DialogResult) => boolean \| void \| Promise<...>` | Combined handler for both Ok and Cancel |
-| `width` | `string` | Dialog width (e.g. `'50vw'`) — replaces PrimeReact `style={{ width }}` |
-| `resizable` | `boolean` | Default `false` |
+| `width` | `string` | Dialog width (e.g. `'50vw'`); defaults to `450px` |
+| `dismissable` | `boolean` | Header close, Escape and backdrop dismissal (when not busy) |
+| `style` / `contentStyle` / `className` | | Modal-root and content-region styling |
+| `pt` | `DialogParts` | Per-part attributes: `backdrop`, `positioner`, `root`, `header`, `title`, `close`, `content`, `footer`, `confirm`, `cancel` |
 
-`style`, `contentStyle`, and `dismissable` **are** supported. The other v10 PrimeReact Dialog props (`modal`, `dismissableMask`, `draggable`, `footer`, `onHide`) are **not** available — do not use them. (`resizable` is accepted for compatibility but is a no-op in PrimeReact 11.)
+`resizable`, `ptOptions` and `unstyled` are accepted for source compatibility and do nothing. There is no `modal`, `draggable`, `footer` or `onHide` — the dialog is always modal, the footer comes from `buttons`, and closing is reported through `onCancel`/`onClose`. Style the dialog through its parts (`pt`, or `[data-cratis-part='root']` selectors), never through React Aria class names.

package/package/corpus/rules/efcore.md

@@ -10,226 +10,74 @@ profile: application
 > **⚠️ APPLIES ONLY TO PROJECTS USING ENTITY FRAMEWORK CORE**
 > If your project does not reference `Microsoft.EntityFrameworkCore` or any EF Core packages, **ignore this entire file**. These rules are irrelevant outside of EF Core contexts.
 
-## Project Structure
+`Cratis.Arc.EntityFrameworkCore` gives an Arc application EF Core-backed read models: two `DbContext` base types, convention-based registration, provider selection from the connection string, cross-database column helpers for migrations, concept-aware value conversion, and live observation of a `DbSet`. **That is the whole of what Arc ships** — it has no migration runner, no table-name constant convention, no design-time factory and no prescribed project split. Where an application adds one of those, it is that application's local convention, not Cratis; keep such conventions in the repository's own instructions, never present them as framework. The step-by-step workflow, the exact signatures and the traps live in the **cratis-arc-ef-core-migration** skill; this rule states the invariants.
 
-Responsibilities are split across three projects:
+## DbContext base types **[contract]**
 
-| Project | Responsibility |
-|---------|----------------|
-| `Database` | Migrations only – no entities, no DbContexts |
-| `Core` | Entities and feature DbContexts (co-located with features) |
-| `Infrastructure` | DbContext registration, migration runner, cross-cutting EF setup |
+Always derive from one of Arc's base types — never directly from `DbContext`:
 
-**Critical dependency rule**: `Database` must NEVER import from `Core`. Migrations reference only `WellKnownTables` constants (strings) and EF migration types. The dependency chain is:
-
-```
-Core → Infrastructure → Database
-```
-
-## DbContext Base Types
-
-Always use the Cratis Arc base types — never inherit directly from `DbContext`:
-
-- **`ReadOnlyDbContext`** — for all read model / projection contexts (the vast majority)
-- **`BaseDbContext`** — only for writable contexts that own state (e.g. device state, infrastructure state)
+- **`ReadOnlyDbContext`** — for every read model / projection context (the vast majority). Its save-changes interceptor **throws** on any `SaveChanges`, so a projection cannot be bypassed by accident.
+- **`BaseDbContext`** — only for a writable context that genuinely owns state (device state, infrastructure state).
 
 ```csharp
-// ✅ Read model context
 public class StartupPhaseDbContext(DbContextOptions<StartupPhaseDbContext> options)
     : ReadOnlyDbContext(options)
 {
     public DbSet<StartupPhase> StartupPhases => Set<StartupPhase>();
-    public DbSet<PersonnelAssignment> PersonnelAssignments => Set<PersonnelAssignment>();
-}
-
-// ✅ Writable (state-owning) context
-public class DeviceStateDbContext(DbContextOptions<DeviceStateDbContext> options)
-    : BaseDbContext(options)
-{
-    public DbSet<DeviceState> DeviceStates => Set<DeviceState>();
 }
 ```
 
-Use the primary constructor pattern. Expose `DbSet<T>` as expression-bodied properties using `Set<T>()`.
+Use the primary constructor; expose each `DbSet<T>` as an expression-bodied property over `Set<T>()`. Co-locate the context with the feature whose read models it holds.
 
-## Feature Contexts — Not God Contexts
+## Feature contexts — not god contexts **[convention]**
 
-Create one focused DbContext per feature or tightly-related feature group. Never aggregate unrelated entities into a single context.
+One focused `DbContext` per feature or tightly related feature group. Never aggregate unrelated entities into a single context: a context's shape is a cohesion boundary, and a god context couples every feature's schema change to every other's.
 
-```csharp
-// ❌ God context
-public class AppDbContext : DbContext
-{
-    public DbSet<Mission> Missions { get; set; }
-    public DbSet<User> Users { get; set; }
-    public DbSet<Station> Stations { get; set; }
-    // ... many more
-}
-
-// ✅ Focused feature context
-public class StartupPhaseDbContext(DbContextOptions<StartupPhaseDbContext> options)
-    : ReadOnlyDbContext(options)
-{
-    public DbSet<StartupPhase> StartupPhases => Set<StartupPhase>();
-    public DbSet<PersonnelAssignment> PersonnelAssignments => Set<PersonnelAssignment>();
-}
-```
-
-Co-locate the DbContext file with its feature:
-
-```
-Missions/Ongoing/StartupPhase/
-├── StartupPhase.cs
-├── StartupPhaseDbContext.cs
-└── ...
-```
-
-## State Mutation — The Golden Rule
+## State mutation — the golden rule **[convention]**
 
 > **Never mutate state directly through a DbContext.**
 
-All state changes must flow through events and Chronicle projections. Direct writes bypass the audit trail and event log.
-
-```csharp
-// ❌ Direct mutation — forbidden
-dbContext.StartupPhases.Add(new StartupPhase(...));
-await dbContext.SaveChangesAsync();
-
-// ✅ Correct: emit an event, let the projection handle writes
-[Command]
-public record UpdateStartupPhase(MissionId MissionId, ...) { ... }
-```
-
-Only infrastructure projection code, the Chronicle event engine, and reference data sync may write through DbContexts.
+All state changes flow through events and Chronicle projections; a direct write bypasses the event log and the audit trail. Only projection infrastructure, the Chronicle engine, and deliberate reference-data synchronization write through a context — and those are `BaseDbContext`s, never `ReadOnlyDbContext`s.
 
-## Registration
-
-Use the Cratis Arc `Cratis.Arc.EntityFrameworkCore` extension methods:
-
-```csharp
-// Register a single writable DbContext
-services.AddDbContextWithConnectionString<DeviceStateDbContext>(connectionString, optionalConfigure);
-
-// Auto-discover and register ALL ReadOnlyDbContext subtypes from given assemblies
-services.AddReadModelDbContextsWithConnectionStringFromAssemblies(
-    connectionString,
-    configureOptions,
-    [Assembly.GetExecutingAssembly()]);
-```
+## Registration **[contract]**
 
-Configure the database provider using `UseDatabaseFromConnectionString`, which auto-detects PostgreSQL vs SQLite from the connection string:
+Wire EF Core through the Arc builder and give it the connection string:
 
 ```csharp
-options.UseDatabaseFromConnectionString(connectionString);
+builder.AddCratisArc(arc => arc.WithEntityFrameworkCore(
+    options => options.ConnectionString = connectionString));
 ```
 
-Centralize all DbContext setup in a single `AddApplicationDbContexts` extension method per layer.
+With a non-empty connection string and `AutoDiscoverDbContexts` (the default), Arc discovers every public `BaseDbContext` subtype not marked `[IgnoreAutoRegistration]`, registering `ReadOnlyDbContext` subtypes read-only and the rest read-write. ⚠️ `WithEntityFrameworkCore()` with **no** connection string discovers nothing. Explicit registration remains available (`AddDbContextWithConnectionString<T>`, `AddReadOnlyDbContextWithConnectionString<T>`, `AddReadModelDbContextsFromAssemblies`, `AddReadModelDbContextsWithConnectionStringFromAssemblies`).
 
-## Multiple Database Support
+Select the provider with **`UseDatabaseFromConnectionString(connectionString)`** — never hard-code `UseSqlite` / `UseNpgsql` / `UseSqlServer`. It infers `DatabaseType` (`Sqlite`, `SqlServer`, `PostgreSql`) from the connection string, ensures a SQLite file's directory exists, and installs Arc's migrations SQL generator for that provider (which is what adds the JSON validation constraint for `[Json]` columns). An unsupported connection string throws `UnsupportedDatabaseType`.
 
-The application supports both PostgreSQL (ASP.NET mode) and SQLite (MAUI mode) from the same code. The provider is selected at runtime via the connection string — `UseDatabaseFromConnectionString` handles the detection.
+## Migrations **[contract]/[convention]**
 
-Never hardcode a provider (e.g. `UseSqlite` or `UseNpgsql`) in application code. Always use `UseDatabaseFromConnectionString`.
-
-## Migrations
-
-Migrations live exclusively in the **`Database`** project, never in `Core` or `Infrastructure`.
-
-### Organization
-
-Each entity category has its own folder with versioned migration files:
-
-```
-Database/
-├── Missions/
-│   ├── v1_0_0.cs
-│   └── v1_1_0.cs
-├── Users/
-│   └── v1_0_0.cs
-└── WellKnownTables.cs
-```
-
-### Naming
-
-Version files using the pattern `v{major}_{minor}_{patch}.cs` and place them inside a namespace matching their folder:
-
-```csharp
-namespace Database.Missions;
-
-public class v1_0_0 : Migration
-{
-    protected override void Up(MigrationBuilder migrationBuilder) { ... }
-    protected override void Down(MigrationBuilder migrationBuilder) { ... }
-}
-```
-
-The migration ID is composed as `{folder}_{ClassName}` (e.g. `Missions_v1_0_0`).
-
-### Cross-Database Column Helpers
-
-Always use the Cratis Arc `MigrationBuilder` extension helpers to define columns. These abstract over PostgreSQL and SQLite type differences:
+Migrations are created and applied with the **standard EF Core tooling** (`dotnet ef migrations add`, `dotnet ef database update`, or `Database.Migrate()` at startup). Arc adds only the column helpers that keep one migration valid across all three providers — use them instead of raw `table.Column<T>()`:
 
 | Helper | Use for |
-|--------|---------|
-| `table.StringColumn(migrationBuilder)` | Text / varchar columns |
-| `table.GuidColumn(migrationBuilder)` | UUID / GUID columns |
-| `table.NumberColumn<T>(migrationBuilder)` | Integer, long, or numeric columns |
-| `table.DateTimeOffsetColumn(migrationBuilder)` | Timestamps with timezone |
-
-Never use raw EF `table.Column<string>()` etc. — the helpers ensure cross-database compatibility.
-
-```csharp
-// ✅ Cross-database migration
-migrationBuilder.CreateTable(
-    name: WellKnownTables.Missions,
-    columns: table => new
-    {
-        Id = table.StringColumn(migrationBuilder, nullable: false),
-        Title = table.StringColumn(migrationBuilder, maxLength: 200, nullable: false),
-        ResourceId = table.NumberColumn<int>(migrationBuilder, nullable: true),
-        DispatchTime = table.DateTimeOffsetColumn(migrationBuilder),
-        UrgencyId = table.GuidColumn(migrationBuilder)
-    },
-    constraints: table =>
-    {
-        table.PrimaryKey("PK_Missions", x => x.Id);
-        table.ForeignKey("FK_Missions_Urgency", x => x.UrgencyId,
-            WellKnownTables.MissionUrgencies, "Id", onDelete: ReferentialAction.SetNull);
-    });
-```
-
-### Table Names — WellKnownTables
-
-Always reference table names from `WellKnownTables` constants. Never use magic strings directly in migrations.
+| --- | --- |
+| `table.StringColumn(migrationBuilder, …)` | text |
+| `table.GuidColumn(migrationBuilder, …)` | GUID / UUID |
+| `table.NumberColumn<T>(migrationBuilder, …)` | integers, longs, decimals |
+| `table.BoolColumn(migrationBuilder, …)` | booleans |
+| `table.DateTimeOffsetColumn(migrationBuilder, …)` | timestamps with offset |
+| `table.AutoIncrementColumn(migrationBuilder, …)` | identity columns |
+| `table.JsonColumn<TProperty>(migrationBuilder, …)` | a `[Json]`-mapped property |
+| `migrationBuilder.Add{String,Guid,Number,Bool,DateTimeOffset,AutoIncrement,Json,Point,LineString,Polygon}Column(…)` | adding a column to an existing table |
 
-```csharp
-// ❌ Magic string
-migrationBuilder.CreateTable(name: "Missions", ...);
-
-// ✅ Constant
-migrationBuilder.CreateTable(name: WellKnownTables.Missions, ...);
-```
-
-Add new table names to `Database/WellKnownTables.cs` before writing the migration.
+Where a repository organizes its migrations (a dedicated project, a versioned file naming scheme, a table-name constants class) is its own convention: follow what the repository already does, and do not introduce one as if Arc required it.
 
-### Applying Migrations
+## Concepts and JSON **[contract]**
 
-Migrations are applied via a custom runner from the `Database` project (not `dotnet ef database update`):
-
-```csharp
-// ASP.NET mode
-await app.ApplyAllMigrations(connectionString);
-
-// MAUI / IServiceProvider mode
-await services.ApplyAllMigrations(connectionString);
-```
+`ConceptAs<T>` properties map to their underlying primitive without per-property value converters: `BaseDbContext.OnModelCreating` applies the concept conversions, and every Arc registration path calls `AddConceptAsSupport()` so concepts also work inside LINQ predicates. (A context you register with plain EF `AddDbContext` must call `options.AddConceptAsSupport()` itself.) Mark a property `[Json]` to store it as a JSON column with the provider's validation constraint.
 
-The runner discovers all `Migration` subclasses from the `Database` assembly, checks the EF history table, and applies pending migrations in version order within a transaction. Both PostgreSQL and SQLite are supported through the same runner.
+## Observation **[contract]**
 
-## Auto-Discovery
+An EF Core read model can back an observable query: `dbSet.Observe(...)`, `ObserveById(...)` and `ObserveSingle(...)` (extension methods declared in the `Microsoft.EntityFrameworkCore` namespace, so they are in scope wherever the `DbSet` is) push changes through the provider's change notifier — see the skill for what each provider supports.
 
-The Cratis Arc `IImplementationsOf<T>` mechanism discovers DbContext types at runtime:
+## See also
 
-- `IImplementationsOf<BaseDbContext>` — all `DbContext` subtypes across all loaded assemblies.
-- `DiscoverAndFilterDbContextTypes<ReadOnlyDbContext>(assemblies)` — discovers the read-model contexts; the registration helpers (`AddReadModelDbContextsWithConnectionStringFromAssemblies` / `AddReadModelDbContextsFromAssemblies`) build on it.
-- To isolate **writable** contexts, filter the discovered set on assignability — `types.Where(t => !typeof(ReadOnlyDbContext).IsAssignableFrom(t))` — rather than a dedicated extension.
+- the **cratis-arc-ef-core-migration** skill — wiring, making an EF read model injectable into a command, writing a migration, observing, and specs.
+- [efcore.specs.md](./efcore.specs.md) — `DbContext` specs with SQLite in-memory.

package/package/corpus/rules/framework.md

@@ -24,7 +24,7 @@ Each framework repo is organized by what it builds, not by feature slices:
 - **Fundamentals** — the base library. `ConceptAs<T>`, type discovery (`IInstancesOf<T>` / `IImplementationsOf<T>`), serialization, common primitives. `Source/DotNET` (C#) + `Source/JavaScript` (`@cratis/fundamentals`) + the shared ESLint config.
 - **Arc** — the CQRS + model-binding + proxy-generation engine. `Source/DotNET` (the command/query pipeline, validation, authorization, identity, the Roslyn **proxy generator**) + `Source/JavaScript` (`@cratis/arc`, `@cratis/arc.react`, `@cratis/arc.react.mvvm`). Arc.Core does **not** depend on Chronicle.
 - **Chronicle** — the event-sourcing engine. `Source/Kernel` (the engine: **Orleans grains**, event sequences, observers/projections/reducers, storage providers — MongoDB and others), `Source/Clients` (the client SDKs incl. `DotNET` and `Testing`), `Infrastructure`, `Tools`, `Workbench`. The kernel is the deep, performance- and consistency-critical core.
-- **Components** — the React component library on PrimeReact. `Source/<Component>/` folder per component (`CommandDialog`, `DataPage`, `DataTables`, …) with Storybook stories; published as `@cratis/components`. (Application rules *consume* these components; here you *build* them.)
+- **Components** — the React component library (Components-owned markup and styling contract; React Aria internally; optional PrimeReact/MUI presentation adapters under `Adapters/`). `Source/<Component>/` folder per component (`CommandDialog`, `DataPage`, `DataTables`, …) with Storybook stories; published as `@cratis/components`. (Application rules *consume* these components; here you *build* them.)
 
 Repo conventions follow from this: `Source/DotNET` + `Source/JavaScript` for dual-stack libraries; `Kernel` vs `Clients` for Chronicle; a folder-per-component library layout for Components. Match the structure of the area you are editing — do not introduce app-style layouts.
 

package/package/corpus/rules/frontend-quality.md

@@ -29,7 +29,7 @@ Stop-and-fix signals during implementation and review:
 |---|---|---|
 | New component added without checking the shared component surface and `@cratis/components` | Duplicates fragment the design system | Reuse an existing primitive/wrapper, or document the missing one |
 | Slice-local helper promoted to the shared component folder after one use | Freezes a one-off as a shared API | Keep it beside the slice until a second real consumer appears |
-| Raw `primereact/*` import where a Cratis wrapper exists | Bypasses Arc behavior, overlay fixes, validation | Use the `@cratis/components` subpath wrapper |
+| A vendor UI control (any `primereact/*`, `@mui/*`, … import) where a Cratis component exists | Bypasses Arc binding, the overlay environment and validation; adds a second focus owner | Use the `@cratis/components` subpath component |
 | Import from the `@cratis/components` root barrel in new code | Pulls optional-peer-heavy exports, hides intent | Import from subpaths (`CommandDialog`, `DataPage`, `DataTables`, `Dialogs`, `Dropdown`, `Toolbar`, `Common`) |
 | Component API has many boolean visual flags (`primary`, `selected`, `muted`, …) | State combinations become undefined | One typed `variant`/`tone` union, or split components |
 | A reusable component reaches into domain strings, generated proxies, identity, query, command, or navigation | It is no longer a primitive | Move it to the slice, or make it explicitly Cratis-aware and test/story it as such |