@cratis/pi 0.0.1

package/skills/cratis-arc-react-page/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: cratis-arc-react-page
+description: Build a React page in a Cratis Arc application with Cratis Components — DataPage lists, columns, toolbar menu items, command dialogs, confirmation and busy-indicator dialogs, row selection, details panes, snapshot and observable queries, paging, and MVVM view models. Use when building or changing a page that lists or displays data, wiring Add/Edit/Delete actions, connecting a component to a generated Arc query or command proxy, or asking the user to confirm something. Do not use for a multi-step wizard dialog alone, for a canvas tool palette, or for backend command and read-model work.
+license: MIT
+---
+
+# Cratis Arc React pages
+
+Build the page from the generated Arc proxies and the Cratis Components
+wrappers. Do not hand-roll a table, a dialog, or a fetch.
+
+## Verified product sources
+
+This skill is verified against these exact package contracts:
+
+| Package | Version | Verified from |
+| --- | --- | --- |
+| `@cratis/components` | `3.0.0` | its package manifest and component sources |
+| `@cratis/arc` | `>=20.3.1 <23` | peer range declared by `@cratis/components@3.0.0` |
+| `@cratis/arc.react` | `>=20.3.1 <23` | peer range declared by `@cratis/components@3.0.0` |
+| `primereact` | `^11.0.0` | peer of `@cratis/components@3.0.0` |
+| `primeicons` | `^8.0.0` | peer of `@cratis/components@3.0.0` |
+| `react` | `^19.0.0` | peer of `@cratis/components@3.0.0` |
+
+`@cratis/arc.react.mvvm` ships with `@cratis/arc.react` and is an explicit
+application dependency. Reverify before claiming another version.
+
+## Import from subpaths, never the root barrel
+
+The root `@cratis/components` entry exports **namespaces**, not components —
+`import { DataPage } from '@cratis/components'` yields a namespace object whose
+component is `DataPage.DataPage`. Always import from the subpath:
+
+```tsx
+import { DataPage, MenuItem, Column } from '@cratis/components/DataPage';
+import { CommandDialog } from '@cratis/components/CommandDialog';
+import { InputTextField } from '@cratis/components/CommandForm';
+import { Dialog } from '@cratis/components/Dialogs';
+import { DialogProps, DialogResult, useDialog } from '@cratis/arc.react/dialogs';
+```
+
+## Step 1 — Prerequisites
+
+- The backend query and command must already exist, and a Debug build must have
+  regenerated the TypeScript proxies. Generated proxies carry a
+  `**DO NOT EDIT** - This file is an automatically generated file.` header —
+  fix the C# source and rebuild instead of editing one.
+- The app must mount `CratisComponentsProvider` (from
+  `@cratis/components/Common`) above every Cratis component. PrimeReact 11
+  resolves its configuration from a provider, so components fail without one.
+- The app must import the stylesheets explicitly; components no longer import
+  their own CSS:
+
+  ```ts
+  import '@cratis/components/tokens';   // the --cratis-* token layer
+  import '@cratis/components/styles';   // every component stylesheet
+  import '@cratis/components/theme';    // optional license-free baseline look
+  ```
+
+  See the **cratis-components-styling** skill for the full theming contract.
+
+## Step 2 — The DataPage shell
+
+`DataPage` owns the query subscription, paging, selection, action menubar, and
+the optional details split. Do not pre-fetch rows and pass an array.
+
+Required props: `title`, `query`, `emptyMessage`, `children`. Columns and
+toolbar actions are compositional children.
+
+```tsx
+import { Column, DataPage } from '@cratis/components/DataPage';
+import { AllAccounts } from './AllAccounts';
+
+export const AccountsPage = () => (
+    <DataPage title='Accounts' query={AllAccounts} emptyMessage='No accounts yet.' dataKey='id'>
+        <DataPage.Columns>
+            <Column field='name' header='Name' sortable />
+            <Column field='balance' header='Balance' />
+        </DataPage.Columns>
+    </DataPage>
+);
+```
+
+Only `DataPage.Columns` and `DataPage.MenuItems` exist as compound members.
+`MenuItem` and `Column` are **named exports** — there is no `DataPage.MenuItem`
+and no `DataPage.Column`. Pass `dataKey` whenever the read model has an
+identity.
+
+See [data-page.md](references/data-page.md) for every prop, and
+[data-tables.md](references/data-tables.md) when you need a table without the
+page chrome.
+
+## Step 3 — Toolbar actions
+
+Menu items go in `<DataPage.MenuItems>`. `MenuItem` takes `command`, not
+`onClick`, and its `icon` is a **React component type**, not an icon class
+string. `disableOnUnselected` greys the item out until a row is selected.
+
+```tsx
+import { DataPage, MenuItem } from '@cratis/components/DataPage';
+import { useDialog } from '@cratis/arc.react/dialogs';
+import { CreateAccountDialog } from './CreateAccountDialog';
+
+const [CreateAccountWrapper, showCreateAccount] = useDialog(CreateAccountDialog);
+
+<DataPage title='Accounts' query={AllAccounts} emptyMessage='No accounts yet.'>
+    <DataPage.MenuItems>
+        <MenuItem label='Add account' icon={() => <i className='pi pi-plus' />} command={() => showCreateAccount()} />
+        <MenuItem label='Edit account' icon={() => <i className='pi pi-pencil' />} command={() => showEditAccount()} disableOnUnselected />
+    </DataPage.MenuItems>
+    <DataPage.Columns>
+        <Column field='name' header='Name' />
+    </DataPage.Columns>
+</DataPage>
+<CreateAccountWrapper />
+```
+
+Render the wrapper returned by `useDialog` once in the tree. See
+[dialogs.md](references/dialogs.md) for the full dialog contract.
+
+## Step 4 — Command dialogs
+
+A dialog that runs a command is its own component built on `CommandDialog`.
+Bind each input with a `CommandForm` field whose `value` accessor selects the
+command property; the label prop is `title`.
+
+```tsx
+import { CommandDialog } from '@cratis/components/CommandDialog';
+import { InputTextField } from '@cratis/components/CommandForm';
+import { DialogResult, useDialogContext } from '@cratis/arc.react/dialogs';
+import { CreateAccount } from './CreateAccount';
+
+export const CreateAccountDialog = () => {
+    const { closeDialog } = useDialogContext();
+
+    return (
+        <CommandDialog<CreateAccount>
+            command={CreateAccount}
+            title='Create account'
+            okLabel='Create'
+            onSuccess={() => closeDialog(DialogResult.Ok)}
+            onCancel={() => closeDialog(DialogResult.Cancelled)}>
+            <InputTextField<CreateAccount> value={c => c.name} title='Account name' />
+        </CommandDialog>
+    );
+};
+```
+
+Never put a raw PrimeReact control inside a command dialog for a command value —
+it bypasses the field wrapper, so validation never re-runs and the submit button
+stays disabled. Seed values that must be present for validity with
+`initialValues`, not `onBeforeExecute`.
+
+## Step 5 — Confirming, and showing that work is in progress
+
+Do not build a confirmation or busy dialog into a page. `ConfirmationDialog` and
+`BusyIndicatorDialog` are registered once at the app root through
+`DialogComponents` and raised by hook, which is what keeps every one of them
+identical:
+
+```tsx
+import { DialogComponents } from '@cratis/arc.react/dialogs';
+import { BusyIndicatorDialog, ConfirmationDialog } from '@cratis/components/Dialogs';
+
+<DialogComponents confirmation={ConfirmationDialog} busyIndicator={BusyIndicatorDialog}>
+    <YourApp />
+</DialogComponents>
+```
+
+```tsx
+import { DialogButtons, DialogResult, useBusyIndicator, useConfirmationDialog } from '@cratis/arc.react/dialogs';
+
+const [confirm] = useConfirmationDialog();
+if (await confirm('Delete this account?', `"${account.name}" disappears permanently.`, DialogButtons.YesNo) !== DialogResult.Yes) return;
+```
+
+A busy indicator is modal and deliberately non-dismissible, so reserve it for
+work the user genuinely cannot proceed past — a multi-step import, a migration.
+For an ordinary command behind a button, the in-flight disabled button is the
+right control; a modal that flashes for 200 ms tells the user nothing. When you
+do use one, pair it with the close call in a `finally`:
+
+```tsx
+const [showBusy, closeBusy] = useBusyIndicator('Importing', 'This takes a moment.');
+showBusy();
+try { await importEverything(); } finally { closeBusy(); }
+```
+
+## Step 6 — Row selection and a details pane
+
+`selection` and `onSelectionChange` are controlled. The change event carries
+`value`, which is `null` when the selection is cleared.
+
+```tsx
+import type { DataTableSelectionChangeEvent } from '@cratis/components/DataTables';
+
+const [selected, setSelected] = useState<AccountSummary | null>(null);
+
+<DataPage
+    title='Accounts'
+    query={AllAccounts}
+    emptyMessage='No accounts yet.'
+    dataKey='id'
+    selection={selected}
+    onSelectionChange={(event: DataTableSelectionChangeEvent<AccountSummary>) => setSelected(event.value)}
+    detailsComponent={AccountDetails}>
+    <DataPage.Columns>
+        <Column field='name' header='Name' />
+    </DataPage.Columns>
+</DataPage>
+```
+
+`detailsComponent` receives `IDetailsComponentProps<T>` — `{ item, onRefresh? }`
+— and renders beside the table for the selected row.
+
+## Step 7 — Snapshot or observable query
+
+The **same `query` prop** takes a snapshot query or an observable query. There
+is no separate `observableQuery` prop: `DataPage` inspects the query prototype
+and picks the snapshot or observable table itself. Pass an observable query and
+the page stays live; pass a snapshot query and call `onRefresh` after a command
+succeeds.
+
+Read [queries-and-commands.md](references/queries-and-commands.md) for the
+generated proxy hooks, their exact return tuples, paging, and how to read a
+command result.
+
+## Step 8 — MVVM for pages with real logic
+
+Extract a view model as soon as the component has three or more `useState`
+calls, a state-synchronizing `useEffect`, or derived values. Keep the component
+declarative and read `viewModel.x` **inside** JSX so MobX tracks it.
+
+```tsx
+import { withViewModel } from '@cratis/arc.react.mvvm';
+import { injectable } from 'tsyringe';
+
+@injectable()
+export class AccountsViewModel {
+    selected: AccountSummary | null = null;
+    select(account: AccountSummary | null) { this.selected = account; }
+}
+
+export const AccountsPage = withViewModel(AccountsViewModel, ({ viewModel }) => (
+    <DataPage title='Accounts' query={AllAccounts} emptyMessage='No accounts yet.' dataKey='id'
+        selection={viewModel.selected}
+        onSelectionChange={event => viewModel.select(event.value)}>
+        <DataPage.Columns>
+            <Column field='name' header='Name' />
+        </DataPage.Columns>
+    </DataPage>
+));
+```
+
+`withViewModel` applies `makeAutoObservable` itself — do not call it in the
+constructor. See [mvvm.md](references/mvvm.md) for injection, route parameters,
+props handling, and teardown.
+
+## Quick decision guide
+
+| Need | Use |
+| --- | --- |
+| Read-only list page | `DataPage` with a snapshot query |
+| Live-updating list page | `DataPage` with an observable query on the same `query` prop |
+| Add or create action | `<DataPage.MenuItems>` + `MenuItem` + `CommandDialog` + `useDialog` |
+| Edit the selected row | `selection` / `onSelectionChange` + `CommandDialog` + `initialValues` / `currentValues` |
+| Detail for the selected row | `detailsComponent` |
+| Table without page chrome | `DataTableForQuery` / `DataTableForObservableQuery` |
+| Ask the user to confirm | `useConfirmationDialog` — never `window.confirm`, never a hand-rolled Yes/No dialog |
+| Multi-step wizard dialog | the **cratis-components-stepper-command-dialog** skill |
+| Canvas tool palette | the **cratis-components-toolbar** skill |
+| Complex page state | `withViewModel` |
+
+## Verify
+
+- Every Cratis Components import uses a subpath, not the root barrel.
+- `CratisComponentsProvider` wraps the tree and the three stylesheets are
+  imported once at the app entry point.
+- `DataPage` receives `title`, `query`, `emptyMessage`, and children, and
+  `dataKey` when the read model has an identity.
+- Columns sit in `<DataPage.Columns>`; menu items sit in
+  `<DataPage.MenuItems>` and use `command`, not `onClick`.
+- No component pre-fetches rows and passes them to `DataPage` as an array.
+- Every command value in a dialog is bound through a `CommandForm` field.
+- Values required for validity come from `initialValues`, not
+  `onBeforeExecute`.
+- Confirmations and busy indicators are raised by hook, registered once at the
+  app root.
+- Every `showBusy()` has a matching close in a `finally`.
+- No generated proxy file was edited.
+- Lint, the frontend test gate, and the TypeScript build all pass.

package/skills/cratis-arc-react-page/references/data-page.md

@@ -0,0 +1,125 @@
+# DataPage reference
+
+`DataPage` is the standard list page: an action menubar, a data table, and an
+optional details pane in one component. Import from
+`@cratis/components/DataPage`.
+
+```tsx
+import { Column, DataPage, MenuItem } from '@cratis/components/DataPage';
+import type { IDetailsComponentProps } from '@cratis/components/DataPage';
+```
+
+## Compound members
+
+Exactly two static members exist:
+
+- `DataPage.Columns` — wraps the `Column` elements.
+- `DataPage.MenuItems` — wraps the `MenuItem` elements.
+
+`Column` and `MenuItem` are named exports of the same subpath. There is no
+`DataPage.Column` and no `DataPage.MenuItem`.
+
+## `DataPageProps`
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `title` | `string` | required — menubar title |
+| `query` | `Constructor<TQuery>` | required — a snapshot **or** observable query proxy |
+| `emptyMessage` | `string` | required — shown when the query returns no rows |
+| `children` | `ReactNode` | required — `DataPage.Columns` and optionally `DataPage.MenuItems` |
+| `queryArguments` | `TArguments` | forwarded to the query |
+| `dataKey` | `string \| undefined` | row identity; pass whenever the read model has one |
+| `selection` | `any \| undefined \| null` | controlled selection |
+| `onSelectionChange` | `(event: DataTableSelectionChangeEvent<any>) => void` | `event.value` is the row or `null` |
+| `detailsComponent` | `React.FC<IDetailsComponentProps<any>>` | rendered beside the table for the selected row |
+| `globalFilterFields` | `string[] \| undefined` | enables the global search box over these fields |
+| `defaultFilters` | `DataTableFilterMeta` | initial per-column filter state |
+| `onRefresh` | `() => void` | invoked to re-fetch a snapshot query |
+| `actionsAriaLabel` | `string` | accessible name of the actions menubar, default `'Actions'` |
+| `tableClassName` | `string` | class on the inner table |
+| `tablePt` / `tablePtOptions` / `tableUnstyled` | PrimeReact pass-through | target the inner data table |
+| `menubarClassName` | `string` | class on the action menubar |
+| `menubarPt` / `menubarPtOptions` / `menubarUnstyled` | PrimeReact pass-through | target the action buttons |
+| `clientFiltering` | `boolean` | **deprecated and a no-op** — do not use in new code |
+
+## Snapshot versus observable
+
+There is no `observableQuery` prop. `DataPage` inspects the query prototype at
+render time: a snapshot query renders the snapshot table, anything else renders
+the observable table. Pass an observable query proxy and the page pushes
+updates automatically; pass a snapshot query and re-fetch through `onRefresh`
+after a command succeeds.
+
+## `MenuItemProps`
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `icon` | `React.ComponentType<{ className?: string }>` | a **component**, not an icon class string |
+| `label` | `string` | menu label |
+| `command` | `() => void` | the action — **not** `onClick` |
+| `disabled` | `boolean` | unconditionally disabled |
+| `disableOnUnselected` | `boolean` | disabled until a row is selected |
+
+`MenuItem` renders nothing on its own; it is a marker that `DataPage.MenuItems`
+reads. Icons are usually a small inline component:
+
+```tsx
+<MenuItem label='Add account' icon={() => <i className='pi pi-plus' />} command={() => showCreate()} />
+```
+
+## `IDetailsComponentProps<TDataType>`
+
+```ts
+interface IDetailsComponentProps<TDataType> {
+    item: TDataType;
+    onRefresh?: () => void;
+}
+```
+
+```tsx
+const AccountDetails = ({ item }: IDetailsComponentProps<AccountSummary>) => <div>{item.name}</div>;
+```
+
+## `Column`
+
+`Column` is re-exported from `@cratis/components/DataPage` and defined in
+`@cratis/components/DataTables`. It renders nothing itself — it is a
+declaration the table reads.
+
+| Prop | Type |
+| --- | --- |
+| `field` | `string` |
+| `header` | `React.ReactNode` |
+| `body` | `(rowData: TData) => React.ReactNode` |
+| `sortable` | `boolean` |
+| `filter` | `boolean` |
+| `filterField` | `string` |
+| `filterPlaceholder` | `string` |
+| `dataType` | `'text' \| 'numeric' \| 'date' \| 'boolean'` |
+| `showFilterMatchModes` | `boolean` |
+| `filterElement` | `(options: ColumnFilterElementOptions) => ReactNode` |
+| `filterLabels` | `Partial<ColumnFilterMenuLabels>` |
+| `selectionMode` | `'single' \| 'multiple'` |
+| `style` / `className` | `React.CSSProperties` / `string` |
+| `headerStyle` / `headerClassName` | `React.CSSProperties` / `string` |
+| `bodyStyle` / `bodyClassName` | `React.CSSProperties` / `string` |
+
+Use `body` for a computed or formatted cell:
+
+```tsx
+<Column field='balance' header='Balance' body={row => `$${row.balance.toFixed(2)}`} />
+```
+
+## Type name caution
+
+`@cratis/components/DataPage` exports two different things called
+`ColumnProps` — the props of the `DataPage.Columns` wrapper and the re-exported
+column declaration props. Import `ColumnProps` from
+`@cratis/components/DataTables` when you need the column type, so the reference
+is unambiguous.
+
+## Layout
+
+The details pane renders in a resizable split. Give the page a bounded height —
+the stories wrap `DataPage` in a container with an explicit height — or the
+split has nothing to size against.

package/skills/cratis-arc-react-page/references/data-tables.md

@@ -0,0 +1,136 @@
+# Data tables reference
+
+Use a standalone table when you need query-backed rows **without** the
+`DataPage` chrome — embedded in a panel, a card, or a dialog. Import from
+`@cratis/components/DataTables`.
+
+```tsx
+import {
+    Column,
+    DataTableForObservableQuery,
+    DataTableForQuery,
+} from '@cratis/components/DataTables';
+import type { DataTableSelectionChangeEvent } from '@cratis/components/DataTables';
+```
+
+## Pick the component by query kind
+
+| Situation | Component |
+| --- | --- |
+| Full list page with menubar and details | `DataPage` |
+| Embedded table, snapshot query | `DataTableForQuery` |
+| Embedded table, observable query | `DataTableForObservableQuery` |
+
+Unlike `DataPage`, these do **not** auto-detect — pass a snapshot query to
+`DataTableForQuery` and an observable query to `DataTableForObservableQuery`.
+
+## Shared props
+
+Both components take the same prop names:
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `query` | `Constructor<TQuery>` | required |
+| `emptyMessage` | `string` | required |
+| `children` | `ReactNode` | the `Column` declarations |
+| `queryArguments` | `TArguments` | forwarded to the query |
+| `dataKey` | `string \| undefined` | row identity |
+| `selection` | `TDataType \| undefined \| null` | controlled selection |
+| `onSelectionChange` | `(event: DataTableSelectionChangeEvent<TDataType>) => void` | `event.value` is the row or `null` |
+| `globalFilterFields` | `string[] \| undefined` | enables the search box |
+| `defaultFilters` | `DataTableFilterMeta` | initial filter state |
+| `className` | `string` | |
+| `pt` / `ptOptions` / `unstyled` | PrimeReact pass-through | |
+| `paginatorClassName` | `string` | |
+| `paginatorAriaLabels` | paginator label overrides | localize the paginator |
+| `clientFiltering` | `boolean` | **deprecated and a no-op** |
+
+```tsx
+<DataTableForQuery<AllAccounts, AccountSummary, object>
+    query={AllAccounts}
+    emptyMessage='No accounts found'
+    dataKey='id'
+    globalFilterFields={['name', 'ownerName']}
+    selection={selected}
+    onSelectionChange={event => setSelected(event.value)}>
+    <Column field='name' header='Name' sortable filter filterPlaceholder='Filter by name' />
+    <Column field='ownerName' header='Owner' />
+</DataTableForQuery>
+```
+
+## Paging
+
+Both tables page server-side through the Arc paging hooks with a fixed page
+size of 20 rows starting at page 0. The paginator renders only when the result
+reports more than one page. There is no page-size prop on these components —
+when you need caller-controlled paging, call the query's paging hook yourself
+(see [queries-and-commands.md](queries-and-commands.md)) and render the rows
+with your own layout.
+
+## Selection event
+
+```ts
+interface DataTableSelectionChangeEvent<TData> {
+    value: TData | null;
+    originalEvent?: SyntheticEvent;
+}
+```
+
+Add a selection column with `<Column selectionMode='single' headerStyle={{ width: '3rem' }} />`
+when you want an explicit selector rather than row click selection.
+
+## Column filtering
+
+Set `filter` on a column to get a per-column filter menu. `dataType` picks the
+match modes (`'text'`, `'numeric'`, `'date'`, `'boolean'`; default `'text'`),
+`showFilterMatchModes={false}` hides the mode picker, and `filterElement`
+replaces the editor entirely:
+
+```tsx
+<Column
+    field='rating'
+    header='Rating'
+    filter
+    filterElement={options => (
+        <RatingEditor value={options.value} onChange={value => options.onChange(value)} onApply={options.onApply} />
+    )} />
+```
+
+`ColumnFilterElementOptions` gives `field`, `value`, `matchMode`, `onChange`,
+`onApply`, and `onClear`.
+
+Filter menu strings are localizable per column with `filterLabels`
+(`filterTriggerAriaLabel`, `clear`, `apply`, `true`, `false`) — never ship a
+hard-coded English accessible name.
+
+## Filter state shape
+
+```ts
+type DataTableFilterConstraint = { value: unknown; matchMode?: DataTableFilterMatchMode };
+type DataTableFilterMeta = Record<string, DataTableFilterConstraint>;
+```
+
+`DataTableFilterMatchMode` is a const object, not an enum:
+`StartsWith`, `Contains`, `NotContains`, `EndsWith`, `Equals`, `NotEquals`,
+`In`, `Between`, `LessThan`, `LessThanOrEqual`, `GreaterThan`,
+`GreaterThanOrEqual`, `DateIs`, `DateIsNot`, `DateBefore`, `DateAfter`.
+
+## Custom match modes
+
+Register a matcher to add a domain-specific mode, and unregister it when the
+owner unmounts:
+
+```ts
+import { registerDataTableFilterMatcher } from '@cratis/components/DataTables';
+
+const registration = registerDataTableFilterMatcher(
+    'startsWithAccountPrefix',
+    (value, filter) => String(value).startsWith(String(filter)));
+
+// later
+registration.unregister();
+```
+
+Registration rejects names that collide with a built-in mode, names that are
+not identifier-like, and prototype-polluting names. Re-registering the same
+name with a *different* function throws — register once per matcher.