@cratis/scene.blueprint.components 0.1.0

package/gallery/previewProfile.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { UiProfile } from '@cratis/scene.model';
+import { PackageCatalog } from '@cratis/scene.engine';
+import { corePackageManifest } from '@cratis/scene.react';
+import { cratisComponentsPackageManifest } from '@cratis/scene.components';
+import { defaultBlueprintManifest, defaultBlueprintName } from '@cratis/scene.blueprint.default';
+import { ComponentName } from '../ComponentName';
+import { componentsBlueprintName } from '../packageName';
+
+/**
+ * The names this blueprint borrows from `PrimeReact`.
+ *
+ * Every other package in the catalog below contributes its *real* manifest, because this package takes an
+ * npm dependency on each of them. `PrimeReact` is the exception: this blueprint depends on it in the
+ * manifest sense - `column` comes from there - without depending on its bundle, so its declaration is not
+ * importable here and the borrowed names are written out instead.
+ *
+ * Every name below was checked against `primeReactPackage.ts`'s own component list rather than assumed.
+ * The default blueprint learned why that matters when it referenced `chart` and `fileUpload`, which
+ * neither library declares - names that look obvious and render as dashed red boxes.
+ *
+ * A host that has all five packages loaded should build this catalog from their manifests instead. The
+ * shape is the same, and anything that has drifted then fails this blueprint's specs rather than a preview.
+ */
+export const primeReactComponentNames: string[] = ['column', 'dataTable', 'table', 'dialog', 'button', 'card', 'text', 'toolbar', 'dropdown', 'tooltip', 'menu', 'breadcrumb', 'sidebar'];
+
+/**
+ * The profile this blueprint's templates resolve against.
+ *
+ * Declaration order is ascending priority, which is why this exact order matters rather than being
+ * cosmetic. `Cratis.Components` outranks `PrimeReact`, so a template naming `table` or `dialog` gets the
+ * Arc-aware one and PrimeReact's is recorded as shadowed. Both blueprints outrank both libraries, so
+ * `pageHeader` and `arcPageHeader` resolve to the packages that declare them. And this blueprint sits at
+ * the top, which costs nothing today - it declares one name nobody else does - but is the correct place
+ * for the package doing the layering.
+ *
+ * `core` is listed explicitly rather than left to `effectivePackages` to prepend, because a theme's
+ * compatibility is checked against exactly what a profile declares, and a profile leaning on the implicit
+ * fallback would make a theme look incompatible with a package the profile never admitted to using.
+ *
+ * Unlike the default blueprint, this package needs no separate *preview* profile. That blueprint takes no
+ * npm dependency on the libraries its templates reference, so previewing it from its own package resolves
+ * most names to implementations that are not loaded. This one depends on `@cratis/scene.components` and
+ * `@cratis/scene.blueprint.default` for real, so everything its templates name is loadable except
+ * PrimeReact's `column` - and a `column` never reaches the DOM at design time anyway, because the table it
+ * belongs to is a placeholder until a host registers its query.
+ */
+export const componentsBlueprintProfile: UiProfile = {
+    name: 'Arc pages',
+    targetPlatform: 'web',
+    packages: ['core', 'PrimeReact', cratisComponentsPackageManifest.name, defaultBlueprintName, componentsBlueprintName],
+};
+
+/**
+ * The component catalog the templates resolve against.
+ *
+ * Four of the five entries are the owning package's real declared list, read straight off its manifest, so
+ * a name renamed upstream fails a spec here instead of rendering as a dashed box in someone's application.
+ */
+export const componentsBlueprintCatalog: PackageCatalog = {
+    [corePackageManifest.name]: corePackageManifest.components,
+    PrimeReact: primeReactComponentNames,
+    [cratisComponentsPackageManifest.name]: cratisComponentsPackageManifest.components,
+    [defaultBlueprintName]: defaultBlueprintManifest.components,
+    [componentsBlueprintName]: Object.values(ComponentName),
+};

package/gallery/screens.ts

@@ -0,0 +1,75 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Screen, ScreenTemplate } from '@cratis/scene.model';
+import { LayoutName, appShellLayout, nestScreenTemplates, templateContentInLayout } from '@cratis/scene.blueprint.default';
+import { componentsScreenTemplates, nestingChainTemplates } from '../templates';
+import { componentsApplicationChrome } from './applicationChrome';
+import { componentsNavigationContributions } from './navigation';
+
+/**
+ * The gallery: one {@link Screen} per template, ready to boot through the real engine.
+ *
+ * These exist so a preview is a working miniature application rather than a set of pictures - the same
+ * `Screen` shape Stage produces, put through the same `Scene.Engine` and `Scene.React`, with no separate
+ * preview pipeline and nothing mocked.
+ *
+ * They will render with unregistered bindings, and that is the normal design-time state rather than a
+ * shortcoming of the gallery. A host owns the generated Arc proxies; a gallery is not a host. What a
+ * preview therefore shows is every Arc-bound region as a placeholder naming the binding it wanted, every
+ * Arc-free region rendered for real, and a header on each page saying which of the two you are looking at.
+ *
+ * Every screen renders in the default blueprint's `AppShell`. There is no full-page variant here because
+ * there is no Arc-bound page that belongs outside the application shell - a sign-in screen queries nothing
+ * and submits no command, so it stays where it already is, in the default blueprint.
+ */
+
+/**
+ * Builds the {@link Screen} that instantiates one template.
+ *
+ * A screen is an instance, not a shape: it names the layout it renders in, the template it fills, the
+ * content that fills it, and what it contributes elsewhere. Everything structural comes from the template,
+ * which is why adding a screen is a handful of lines rather than another copy of the chrome.
+ */
+function screenFor(template: ScreenTemplate): Screen {
+    const placeable = nestScreenTemplates(containmentChainFor(template));
+
+    return {
+        name: template.name,
+        layout: LayoutName.AppShell,
+        screenTemplate: template.name,
+        slotContent: mergeSlotContent(componentsApplicationChrome(template.name), templateContentInLayout(placeable, appShellLayout)),
+        forms: [],
+        contributions: componentsNavigationContributions,
+    };
+}
+
+/**
+ * The chain of templates a screen renders through, outermost first.
+ *
+ * The eight page templates fit the layout's own `content` slot, so each one's chain is just itself. The
+ * three nesting-chain templates are the exception and the only ones that need the walk - which is the
+ * honest version of the story: nesting exists for the applications that need it, and costs nothing for the
+ * ones that do not.
+ */
+function containmentChainFor(template: ScreenTemplate): ScreenTemplate[] {
+    const depth = nestingChainTemplates.findIndex(candidate => candidate.name === template.name);
+    return depth < 0 ? [template] : nestingChainTemplates.slice(0, depth + 1);
+}
+
+function mergeSlotContent(chrome: Record<string, Screen['slotContent'][string]>, content: Record<string, Screen['slotContent'][string]>): Screen['slotContent'] {
+    const merged: Screen['slotContent'] = { ...chrome };
+    for (const [slotName, elements] of Object.entries(content)) {
+        merged[slotName] = [...(merged[slotName] ?? []), ...elements];
+    }
+
+    return merged;
+}
+
+/** One screen per screen template this blueprint provides. */
+export const componentsGalleryScreens: Screen[] = componentsScreenTemplates.map(screenFor);
+
+/** One gallery screen by name, for a story or a host that boots a specific one. */
+export function componentsGalleryScreen(name: string): Screen | undefined {
+    return componentsGalleryScreens.find(screen => screen.name === name);
+}

package/header/ArcHeading.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Everything {@link ArcPageHeader} renders, derived from one binding name and a handful of properties.
+ *
+ * It is a separate type from the component so the derivation can be specified without rendering anything.
+ * That matters more here than it usually does: the whole argument for this being a component rather than
+ * a content tree is that it *derives* rather than holds, so the derivation is the part that has to be
+ * provably right.
+ */
+export interface ArcHeading {
+    /** The heading text - the screen's `title`, or the binding name read as a sentence when it set none. */
+    title: string;
+
+    /** The line under the heading, when the screen supplied one. */
+    subtitle?: string;
+
+    /**
+     * The breadcrumb trail, outermost first, ending in {@link title}.
+     *
+     * Derived rather than authored, which is the point: a screen states its section once and the trail
+     * follows the heading automatically, so the two can never drift apart the way two literals do.
+     */
+    trail: string[];
+
+    /** The binding name the header was given, or `undefined` when the screen named none. */
+    bindingName?: string;
+
+    /** Whether a host has actually registered {@link bindingName}. */
+    isBound: boolean;
+
+    /**
+     * The design-time state, in words - what a designer reads off the header when a page is not yet
+     * wired. The three cases are genuinely different problems: nothing named, named but unregistered, and
+     * working.
+     */
+    bindingLabel: string;
+}

package/header/ArcPageHeader.tsx

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { BindingKind, resolveElementBinding } from '@cratis/scene.components';
+import { deriveArcHeading } from './deriveArcHeading';
+
+/**
+ * The one component this blueprint registers: a page header whose heading, trail and design-time state all
+ * follow from a single binding name.
+ *
+ * Every template in this package opens with one, and every template gives it the same binding its body is
+ * built around - `AllInvoices` on the list page, `RecordAdjustment` on the command page. Saying it once is
+ * the point. A hand-authored header repeats the page's subject in the title, again in the trail, and a
+ * third time in the table below it, and those three copies drift the first time anything is renamed.
+ *
+ * It also reports whether the binding is registered, which is what makes a design-time preview readable.
+ * A page whose body is one dashed placeholder is ambiguous - is the name wrong, or has the host simply not
+ * wired anything yet? The header answers that at the top of the page, in words, without opening a debugger.
+ *
+ * The `layout-page-header` class names are the default blueprint's, not this package's. That is this
+ * blueprint's whole posture in one detail: it reuses the shell it depends on rather than shipping a rival
+ * one, so a page of Arc-bound content sits inside the default shell looking like it belongs there.
+ */
+export function ArcPageHeader({ element, slots }: RegisteredComponentProps) {
+    const query = resolveElementBinding(element, BindingKind.Query);
+    const kind = query.name === undefined ? BindingKind.Command : BindingKind.Query;
+    const binding = kind === BindingKind.Query ? query : resolveElementBinding(element, BindingKind.Command);
+    const heading = deriveArcHeading(element.properties, binding, kind);
+
+    return (
+        <div className='layout-page-header' data-scene-id={element.id} data-scene-binding={heading.bindingName}>
+            <div>
+                <nav className='layout-page-header-trail' aria-label='Breadcrumb'>
+                    {heading.trail.join(' › ')}
+                </nav>
+                <h1 className='layout-page-header-title'>{heading.title}</h1>
+                {heading.subtitle && <p className='layout-page-header-subtitle'>{heading.subtitle}</p>}
+                <span data-scene-binding-state={heading.isBound ? 'bound' : 'unbound'}>{heading.bindingLabel}</span>
+            </div>
+            {(slots.actions?.length ?? 0) > 0 && <div className='layout-page-header-actions'>{slots.actions}</div>}
+        </div>
+    );
+}

package/header/deriveArcHeading.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingKind, ElementBinding, stringProperty } from '@cratis/scene.components';
+import { ArcHeading } from './ArcHeading';
+import { humanizeBindingName } from './humanizeBindingName';
+
+/**
+ * Derives everything a page header shows from one binding and the few properties around it.
+ *
+ * This function is the entire argument for {@link ArcPageHeader} being a component at all. A screen
+ * template can hold a title, a subtitle and a breadcrumb trail perfectly well - they are three literals in
+ * a property bag, and a tree is the right place for literals. What a tree cannot do is *derive* them from
+ * a single binding name and a registry lookup, and that is what an Arc-bound page needs: the page is about
+ * `AllInvoices`, so the heading, the trail and the design-time state should all follow from saying so once.
+ *
+ * The three binding states are kept apart deliberately, because they are three different problems with
+ * three different fixes. No name at all means the template is incomplete. A name nothing is registered
+ * under means the host has not wired it - which is the *normal* state at design time, not an error. A
+ * resolved name means the page will really talk to a backend.
+ *
+ * @param properties The element's property bag - `title`, `subtitle` and `section` are read from it.
+ * @param binding What the element asked for at its binding site, and what the registry produced.
+ * @param kind Whether the binding was a query or a command, so the state can be described in the right words.
+ * @returns The derived {@link ArcHeading}.
+ */
+export function deriveArcHeading(properties: Record<string, unknown>, binding: ElementBinding, kind: BindingKind): ArcHeading {
+    const title = stringProperty(properties, 'title') ?? (binding.name === undefined ? 'Untitled page' : humanizeBindingName(binding.name));
+    const section = stringProperty(properties, 'section');
+
+    return {
+        title,
+        subtitle: stringProperty(properties, 'subtitle'),
+        trail: section === undefined ? [title] : [section, title],
+        bindingName: binding.name,
+        isBound: binding.target !== undefined,
+        bindingLabel: bindingLabelFor(binding, kind),
+    };
+}
+
+function bindingLabelFor(binding: ElementBinding, kind: BindingKind): string {
+    if (binding.name === undefined) {
+        return 'No binding';
+    }
+
+    return binding.target === undefined ? `No ${kind} registered as ${binding.name}` : `Bound to ${kind} ${binding.name}`;
+}

package/header/humanizeBindingName.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Reads an Arc binding name as a sentence: `AllInvoices` becomes `All invoices`.
+ *
+ * Arc proxy names are the C# artifact names - a `[ReadModel]`'s static query method, a `[Command]` record -
+ * so they arrive in PascalCase and describe exactly what the page is about. Using them as the fallback
+ * heading means a page template is legible before anyone has written a title, and the heading a designer
+ * sees at design time is the one the backend actually named.
+ *
+ * Only the boundary between a lowercase or numeric character and an uppercase one is treated as a word
+ * break, so a run of capitals stays together: `AllPIIRecords` reads as `All PIIRecords` rather than being
+ * chopped into initials. That is the right trade - a wrong word break in an acronym is much more jarring
+ * than a missing one. For the same reason a word is only lowered when it looks like an ordinary
+ * capitalized word, so an acronym keeps its shape instead of being flattened into `piirecords`.
+ *
+ * @param name The binding name as a screen wrote it.
+ * @returns The name as a sentence, with only the first word capitalized.
+ */
+export function humanizeBindingName(name: string): string {
+    const words = name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/\s+/)
+        .filter(word => word.length > 0);
+
+    if (words.length === 0) {
+        return name;
+    }
+
+    return [words[0], ...words.slice(1).map(lowered)].join(' ');
+}
+
+function lowered(word: string): string {
+    return /^[A-Z][a-z]/.test(word) ? `${word[0].toLowerCase()}${word.slice(1)}` : word;
+}

package/header/index.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './ArcHeading';
+export * from './humanizeBindingName';
+export * from './deriveArcHeading';
+export * from './ArcPageHeader';

package/index.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './packageName';
+export * from './ComponentName';
+export * from './CompositeName';
+export * from './BorrowedComponentName';
+export * from './header';
+export * from './templates';
+export * from './gallery';
+export * from './componentsBlueprintComponents';
+export * from './componentsBlueprint';

package/package.json

@@ -0,0 +1,71 @@
+{
+    "name": "@cratis/scene.blueprint.components",
+    "version": "0.1.0",
+    "description": "A blueprint of Arc-bound screen and dialog templates: full pages built from Cratis Components composites, so a data list, a command form or a master-detail screen is a template rather than something you assemble.",
+    "author": "Cratis",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Cratis/Scene.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "**/*.ts",
+        "**/*.tsx"
+    ],
+    "main": "dist/cjs/index.js",
+    "module": "dist/esm/index.js",
+    "types": "dist/esm/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./dist/esm/index.d.ts",
+            "require": "./dist/cjs/index.js",
+            "import": "./dist/esm/index.js"
+        }
+    },
+    "scripts": {
+        "prepare": "yarn g:build",
+        "clean": "yarn g:clean",
+        "build": "yarn g:build",
+        "lint": "yarn g:lint",
+        "lint:ci": "yarn g:lint:ci",
+        "test": "yarn g:test",
+        "ci": "yarn g:ci",
+        "up": "yarn g:up",
+        "dev": "storybook dev -p 6006",
+        "build-storybook": "storybook build"
+    },
+    "dependencies": {
+        "@cratis/components": "^2.8.1",
+        "@cratis/scene.blueprint.default": "0.1.0",
+        "@cratis/scene.components": "0.1.0",
+        "@cratis/scene.engine": "0.1.0",
+        "@cratis/scene.model": "0.1.0",
+        "@cratis/scene.react": "0.1.0"
+    },
+    "devDependencies": {
+        "@cratis/components": "^2.8.1",
+        "@cratis/scene.blueprint.default": "0.1.0",
+        "@cratis/scene.components": "0.1.0",
+        "@cratis/scene.engine": "0.1.0",
+        "@cratis/scene.model": "0.1.0",
+        "@cratis/scene.react": "0.1.0",
+        "@storybook/addon-links": "^10.4.1",
+        "@storybook/react": "^10.4.1",
+        "@storybook/react-vite": "^10.4.1",
+        "primeicons": "^7.0.0",
+        "primereact": "10.9.8",
+        "react": "^19.2.6",
+        "react-dom": "^19.2.6",
+        "storybook": "^10.4.1"
+    },
+    "peerDependencies": {
+        "primereact": "^10.9.0",
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+    }
+}

package/packageName.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The name this blueprint is known by inside a `ui profile`.
+ *
+ * It is not the npm package name: a profile lists Scene package names, a `PackageDependency` refers to
+ * one, and `componentRegistryKey` builds every registry key from this. It therefore lives on its own
+ * rather than inside the manifest, so the registry can key off it without importing the manifest that
+ * describes the registry.
+ */
+export const componentsBlueprintName = 'Cratis.Blueprint.Components';

package/templates/ArcHeaderOptions.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What a template tells its page header.
+ *
+ * `query` and `command` are separate and both optional, and at most one is ever set - which is the header
+ * component's contract, not a convenience here: a page is *about* one thing, and a header bound to both a
+ * query and a command would have nothing sensible to say about either. Setting neither is allowed and
+ * means the header states that no binding was named, which is a legitimate design-time state.
+ */
+export interface ArcHeaderOptions {
+    /** The heading. Left out to let the header read the binding name as a sentence instead. */
+    title?: string;
+
+    /** The line under the heading. */
+    subtitle?: string;
+
+    /** The section this page belongs to, which becomes the first entry of the derived breadcrumb trail. */
+    section?: string;
+
+    /** The query this page is about. */
+    query?: string;
+
+    /** The command this page is about. */
+    command?: string;
+}

package/templates/ColumnDefinition.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * One column of a data table, as a template declares it.
+ *
+ * Two fields and no more, because that is genuinely all a column needs in a template: which property of
+ * the read model it shows, and what the heading says. Everything else a PrimeReact `Column` can do -
+ * sorting, filtering, body templates - is either turned on for the whole table or is application-specific
+ * detail that belongs in the application's own screen rather than in a shipped template.
+ */
+export interface ColumnDefinition {
+    /** The read-model property the column shows. */
+    field: string;
+
+    /** The column heading. */
+    header: string;
+}

package/templates/SampleBindingName.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The Arc query and command names this blueprint's templates ship bound to.
+ *
+ * A template carries a binding *name*, never a class - the binding registry in `@cratis/scene.components`
+ * is what turns a name into the generated proxy at render time, and only a host owns those proxies. So a
+ * template has to write some name, and these are the ones it writes.
+ *
+ * They are defaults, not fixtures. An application picking `DataListPage` replaces `AllInvoices` with its
+ * own query and the page is done; nothing else about the template changes. Shipping a template with no
+ * name at all would have been the alternative, and it is a worse one - it renders as a diagram of a page
+ * rather than a page, and the thing a template most needs to prove is that it composes into something
+ * real.
+ *
+ * The names are deliberately in the shape Arc generates: a `[ReadModel]`'s static query method
+ * (`AllInvoices`), and a `[Command]` record (`RegisterInvoice`). A designer reading a preview should
+ * recognize them as the artifacts they would really be wiring.
+ *
+ * This is an enum of *this package's defaults*, not of every name a binding may take. The element builders
+ * therefore take a plain `string`, so an application can point the same builders at `AllPurchaseOrders`
+ * without having to widen anything - the set of Arc proxies in an application is open, and a closed type
+ * over it would make these builders usable only for the invoices they ship bound to.
+ */
+export enum SampleBindingName {
+    /** Every invoice - the snapshot query a list page reads. */
+    AllInvoices = 'AllInvoices',
+
+    /** Invoices still being processed - an observable query, so the page is live. */
+    InvoicesInFlight = 'InvoicesInFlight',
+
+    /** One invoice by its id - what a detail region reads. */
+    InvoiceById = 'InvoiceById',
+
+    /** Revenue aggregated by month - a dashboard widget's query. */
+    RevenueByMonth = 'RevenueByMonth',
+
+    /** Open support tickets - a second dashboard widget's query. */
+    OpenTickets = 'OpenTickets',
+
+    /** Every adjustment recorded against an invoice. */
+    AllAdjustments = 'AllAdjustments',
+
+    /** Registers a new invoice - the command a form page submits. */
+    RegisterInvoice = 'RegisterInvoice',
+
+    /** Records an adjustment against an invoice - the command a dialog submits. */
+    RecordAdjustment = 'RecordAdjustment',
+}

package/templates/TableOptions.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The settings every table-shaped element in this package shares.
+ *
+ * `emptyMessage` and `dataKey` are required rather than optional on purpose. The library's adapters both
+ * default them to an empty string, and both defaults are quietly wrong in a shipped template: a table with
+ * no empty message reads as broken when the query legitimately returns nothing, and a table with no data
+ * key loses its selection every time the query is re-performed. Making them required means a template
+ * cannot be written without deciding.
+ */
+export interface TableOptions {
+    /** The message shown when the query returns nothing. */
+    emptyMessage: string;
+
+    /** The read-model property that identifies a row, so selection survives a re-query. */
+    dataKey: string;
+
+    /** The fields the search box filters across, when the table offers one. */
+    globalFilterFields?: string[];
+}

package/templates/commandTemplates.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ScreenTemplate } from '@cratis/scene.model';
+import { SlotName, TemplateSlotName, column, slotLeaf } from '@cratis/scene.blueprint.default';
+import { arcPageHeader, page, toolbar, toolbarButton, toolbarSeparator } from './elements';
+import { commandForm } from './formElements';
+import { SampleBindingName } from './SampleBindingName';
+
+/**
+ * The write side: a page whose body is one command, and whose action bar submits it.
+ */
+
+/**
+ * A command form page - a header, the generated form, and the bar that closes it.
+ *
+ * The form is `commandForm`, which is `AutoCommandForm`: it reads the command's own property descriptors
+ * and picks a field component per property type. That is the whole reason a *template* can ship a form at
+ * all. A template that listed fields by hand would be a snapshot of a command as it looked the day the
+ * template was written, and would go quietly wrong the first time a property was added on the backend.
+ * This one follows the command, which is the same guarantee Arc's generated proxies give everywhere else.
+ *
+ * `exclude` names the properties the form should not generate. `invoiceId` is excluded because it is the
+ * event-source identity - Arc resolves it, and a form offering to type it in is offering to break it.
+ *
+ * The action bar is the template's rather than the form's, and it declares its own slot for that reason: a
+ * screen replacing "Register" with "Register and approve" should not have to replace the form.
+ */
+export const commandFormPageTemplate: ScreenTemplate = {
+    name: 'CommandFormPage',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Body }, { name: TemplateSlotName.Actions }],
+    arrangement: {
+        root: column([slotLeaf(TemplateSlotName.Header), slotLeaf(TemplateSlotName.Body, { grow: 1 }), slotLeaf(TemplateSlotName.Actions)], 16),
+    },
+    content: {
+        [TemplateSlotName.Header]: [
+            arcPageHeader('command-form-header', {
+                title: 'Register an invoice',
+                subtitle: 'The form follows the command, so a property added on the backend shows up here',
+                section: 'Billing',
+                command: SampleBindingName.RegisterInvoice,
+            }),
+        ],
+        [TemplateSlotName.Body]: [page('command-form-body', '', [commandForm('command-form', SampleBindingName.RegisterInvoice, ['invoiceId'])])],
+        [TemplateSlotName.Actions]: [
+            toolbar('command-form-actions', [
+                toolbarButton('command-form-submit', 'Register the invoice', 'pi pi-check', 'Register'),
+                toolbarSeparator('command-form-separator'),
+                toolbarButton('command-form-cancel', 'Discard and go back', 'pi pi-times', 'Cancel'),
+            ]),
+        ],
+    },
+    displayName: 'Command form page',
+    description: 'A generated command form under a header that states the command, with its own action bar.',
+};
+
+/** The command-shaped templates. */
+export const commandTemplates: ScreenTemplate[] = [commandFormPageTemplate];