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.
- An accepted
.playmodel under the model root covers the behavior, or the repository is opted in (pergeneral.md"Model first"; wherecratis-screenplay-modeling-lifecycleis installed, run itsscripts/model-first-status.mjs): change the model first withcratis-screenplay-event-modeling. If the Screenplay skills are not installed, say so and do not author.playfrom memory. Read the model'sscreenandformwith from-screenplay.md. Edit code here only for infrastructure, clients, adapters, Screenplay code attachments, or gap-fill scope (cratis-screenplay-render-and-gap-fill); never edit Stage-managed output.
Product sources
This skill follows the @cratis/components package manifest (exports, peers), Source/DataPage/*,
Source/DataTables/*, Source/Dialogs/*, Source/CommandDialog/* and Source/MIGRATION.md.
Peers declared by @cratis/components: @cratis/arc and @cratis/arc.react and react.
Requires @cratis/arc and @cratis/arc.react 20.3.1 or later (below 23) and react 19 or later, as @cratis/components declares them peers.
@cratis/arc.react.mvvm ships with @cratis/arc.react and is an explicit
application dependency.
Import from subpaths, never the root barrel
The root @cratis/components entry is setup-only — CratisComponentsProvider
and its configuration types. import { DataPage } from '@cratis/components' is a
compile error; the Components 3 root namespaces are gone. Always import from the
subpath:
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';
Guid command fields
Requires Components 4.31.0 and matching Arc/Arc React 22.19.1 for GuidField invalid-draft execution blocking; check yarn why @cratis/components and yarn why @cratis/arc.react, or keep a host-validated field.
Opt into GuidField from @cratis/components/CommandForm. It binds native
Fundamentals Guid values, accepts partial text drafts and never generates an
identifier. Register it once through registerFieldTypeProvider for
AutoCommandForm; it is not a built-in provider. Invalid drafts clear the bound
value. Preserve host-set errors and use resetKey to discard an unchanged empty
value's draft.
Initial focus
DialogInitialFocus.Confirm is the default and arms the confirm button, so a destructive dialog uses DialogInitialFocus.Cancel. Read dialogs.md for the three options.
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 the package root,@cratis/components) above every Cratis component — it carries the locale, the Components-owned labels. Enabletoaster(or mount one<Toaster />) for notifications; without it eventoastCommandResultdisplays nothing. Mount exactly one toaster, not both. Thecratistemplate mounts<CratisComponentsProvider toaster>inside<Arc>(Templates/Cratis/.frontend/main.tsx; Requires Templates 1.7.3 or later, earlier ones mount it outside<Arc>without a toaster), so check its entry point rather than adding a second toaster.The app must import the stylesheets explicitly; components do not import their own CSS:
In
index.css, imported by the entry withimport './index.css':@import '@cratis/components/tokens'; @import '@cratis/components/styles'; @import '@cratis/components/theme'; /* optional baseline */CSS subpath imports from TypeScript need ambient declarations on TypeScript 6; use CSS
@importto avoid TS2882. For a smaller bundle usestyles/baseplus the needed area sheets (DataPage/styles, etc.); area order does not matter. Importreflect-metadataat the entry point; it remains required.tsyringeis optional for Components but installed by Arc React.Components has no vendor UI dependency — do not install PrimeReact or an icon font for it. Menu icons are React component types (
react-iconsworks).See the cratis-components-styling skill for the full theming contract.
Step 2 — Trace every field to its origin
Before writing JSX, list every value the page shows or captures, and where it comes from. A value with no origin gets faked on the client or invented as a proxy property, so find the gap before the page exists.
| Origin | Written as | Bound through |
|---|---|---|
| Query result | <Query>.<property> |
DataPage query, Column field, detailsComponent |
| Command input | <Command>.<property> |
a CommandForm field value accessor |
| Route parameter | route:<name> |
the view model's route parameters (Step 9) |
| Display-only calculation | derived:<expression> |
a view-model getter, with a spec |
- The caller's identity is never a command input. Take it on the server, not from a form field.
- A value with no origin is a gap in the backend or the model, not in the page.
Do not compute it from other queries on the client and do not add a property to
a generated proxy. Stop building that part of the page and add the property to
the read model or command first (
cratis-arc-command,cratis-chronicle-read-model) or, where one exists, to the.playmodel. - A component that shows one part of a page lists only that part's fields.
- When the page implements a
.playscreen or form, the model is the source of the list: follow from-screenplay.md.
Step 3 — 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.
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>
);
DataPage.Columns, DataPage.MenuItems and DataPage.MenuItem are the
compound members; MenuItem and Column are also named exports of the
subpath (there is no DataPage.Column). Pass dataKey whenever the read model has an
identity.
Read data-page.md when configuring DataPage props; it lists every prop, and data-tables.md when you need a table without the page chrome.
Step 4 — 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.
import { FaPencil, FaPlus } from 'react-icons/fa6';
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={FaPlus} command={() => showCreateAccount()} />
<MenuItem label='Edit account' icon={FaPencil} 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. Read
dialogs.md when implementing dialog opening, closing, input, response, validation, or focus behavior; it gives the full dialog contract.
Step 5 — 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.
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'
=> closeDialog(DialogResult.Ok)}
=> closeDialog(DialogResult.Cancelled)}>
<InputTextField<CreateAccount> value={c => c.name} title='Account name' />
</CommandDialog>
);
};
Never put a raw control (a Common TextInput, a native <input>) inside a
command dialog for a command value — it is not bound to the command, so
validation never re-runs and the submit button stays disabled. Seed values that must be present for validity with
initialValues, not onBeforeExecute.
Step 6 — Confirming, and showing that work is in progress
Do not build a confirmation or busy dialog into a page: register ConfirmationDialog and BusyIndicatorDialog once at the app root through DialogComponents and raise them by hook (useConfirmationDialog, useBusyIndicator). A busy indicator is modal and non-dismissible, so reserve it for work the user cannot proceed past, and pair showBusy() with a close in a finally. Read dialogs.md for the registration and hook examples.
Step 7 — Row selection and a details pane
selection and onSelectionChange are controlled (value is null when cleared), and detailsComponent receives { item, onRefresh? } for the selected row. Read data-page.md for the controlled-selection example.
Step 8 — 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. onRefresh only forwards a caller callback to the details
component; it never refetches the table. DataPage has no snapshot refresh handle.
Use an observable query when commands must update the list.
Read queries-and-commands.md when using generated proxy hooks, implementing paging, or handling command results; it covers the generated proxy hooks, their exact return tuples, paging, and how to read a command result.
Step 9 — 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.
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}
=> 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. Read mvvm.md when implementing view-model injection, route parameters,
props handling, or 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 |
A .play screen or form is the spec |
from-screenplay.md |
Verify
- Every Cratis Components import uses a subpath, not the root barrel.
CratisComponentsProviderwraps the tree, one toaster is mounted for notifications, and the CSS entries are imported once via the app's CSS file.DataPagereceivestitle,query,emptyMessage, and children, anddataKeywhen the read model has an identity.- Columns sit in
<DataPage.Columns>; menu items sit in<DataPage.MenuItems>and usecommand, notonClick. - No component pre-fetches rows and passes them to
DataPageas an array. - Every command value in a dialog is bound through a
CommandFormfield. - Values required for validity come from
initialValues, notonBeforeExecute. - Confirmations and busy indicators are raised by hook, registered once at the app root.
- Every
showBusy()has a matching close in afinally. - Every displayed or captured value has an origin from the Step 2 table; none is computed from another query on the client.
- Each page's states are designed: empty (
emptyMessage), loading, a command that fails (read through the granularCommandResultflags in queries-and-commands.md), denied (a persona that can reach the page but whose policy refuses the action), and the state after success. - When a
.playmodel describes the page, the page matches it element by element and adds no data or action the model lacks (from-screenplay.md). - No generated proxy file was edited.
- Lint, the frontend test gate, and the TypeScript build all pass.
Route near misses
- A multi-step wizard dialog:
cratis-components-stepper-command-dialog. - A canvas tool palette:
cratis-components-toolbar. - Colors, tokens and theming:
cratis-components-styling. - The backend command or read model behind the page:
cratis-arc-command,cratis-chronicle-read-model. - Specifying page behavior with specs:
cratis-application-react-specifications.
Lineage
Read references/provenance.md when checking source attribution or adaptation permissions.