@cratis/scene.blueprint.components 0.1.0

package/templates/dataElements.ts

@@ -0,0 +1,97 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { externalComponent } from '@cratis/scene.blueprint.default';
+import { BorrowedComponentName } from '../BorrowedComponentName';
+import { CompositeName } from '../CompositeName';
+import { ColumnDefinition } from './ColumnDefinition';
+import { TableOptions } from './TableOptions';
+
+/**
+ * The Arc-bound data elements this blueprint's templates are built from.
+ *
+ * Each one is a single `ExternalComponent` carrying a query *name* in its property bag, which is the whole
+ * contract: `resolveElementBinding` in `@cratis/scene.components` reads that name out at render time and
+ * looks it up in the binding registry, and a name nothing is registered under renders as a placeholder
+ * naming what it wanted. Nothing here invents a second way to reach a backend, because there is only one
+ * and it belongs to the component library.
+ */
+
+/**
+ * The columns of a data table, as the `content` slot children the library's tables take.
+ *
+ * The name is PrimeReact's rather than `Cratis.Components`' - see {@link BorrowedComponentName.Column} for
+ * why - and `sortable` is set on every column because a table that performs a real query can sort against
+ * the server, and a column that quietly cannot is the more surprising default.
+ */
+export function columns(id: string, definitions: ColumnDefinition[]): SceneElement[] {
+    return definitions.map(definition =>
+        externalComponent(`${id}-${definition.field}`, BorrowedComponentName.Column, {
+            field: definition.field,
+            header: definition.header,
+            sortable: true,
+        }),
+    );
+}
+
+/**
+ * A `dataPage` - the library's whole list-screen composite, driven from one query.
+ *
+ * This is the archetype the package exists for. Reproducing it out of a table, a toolbar and a filter in a
+ * screen would be pages of modeling for a worse result, and every one of those pages would then be an
+ * application's to maintain. Here it is one element with a name in it.
+ *
+ * Its own `title` is deliberately empty. Every template in this package opens with an `arcPageHeader`, and
+ * that header already states the page's name, its trail and what it is bound to; letting the composite
+ * print the same word again directly underneath would be two sources for one fact, and they would
+ * disagree the first time either changed.
+ */
+export function dataPage(id: string, query: string, options: TableOptions, definitions: ColumnDefinition[]): SceneElement {
+    return externalComponent(id, CompositeName.DataPage, { query, title: '', ...options }, { content: columns(`${id}-column`, definitions) });
+}
+
+/**
+ * A `dataTable` - the same server-side querying without the page chrome around it.
+ *
+ * Used where a template already has a header of its own and only needs the rows, which is most places a
+ * table appears inside a larger page.
+ */
+export function dataTable(id: string, query: string, options: TableOptions, definitions: ColumnDefinition[]): SceneElement {
+    return externalComponent(id, CompositeName.DataTable, { query, ...options }, { content: columns(`${id}-column`, definitions) });
+}
+
+/**
+ * An `observableDataTable` - the live variant.
+ *
+ * A separate element rather than a flag, because the difference is in the *proxy* a host registers: an
+ * observable query opens a subscription and re-renders when the read model changes, and a plain one does
+ * not. A template that names an observable query is stating that its data is live, which is a design
+ * decision worth being able to read off the page.
+ */
+export function observableDataTable(id: string, query: string, options: TableOptions, definitions: ColumnDefinition[]): SceneElement {
+    return externalComponent(id, CompositeName.ObservableDataTable, { query, ...options }, { content: columns(`${id}-column`, definitions) });
+}
+
+/** The columns of the invoice list every list-shaped template in this package shows. */
+export const invoiceColumns: ColumnDefinition[] = [
+    { field: 'number', header: 'Number' },
+    { field: 'customer', header: 'Customer' },
+    { field: 'issued', header: 'Issued' },
+    { field: 'amount', header: 'Amount' },
+    { field: 'status', header: 'Status' },
+];
+
+/** The columns of the adjustment list, for the templates that show one. */
+export const adjustmentColumns: ColumnDefinition[] = [
+    { field: 'recorded', header: 'Recorded' },
+    { field: 'reason', header: 'Reason' },
+    { field: 'amount', header: 'Amount' },
+];
+
+/** The table options an invoice list uses, so eight templates cannot disagree about the empty message. */
+export const invoiceTableOptions: TableOptions = {
+    emptyMessage: 'No invoices yet',
+    dataKey: 'invoiceId',
+    globalFilterFields: ['number', 'customer', 'status'],
+};

package/templates/dialogElements.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { externalComponent } from '@cratis/scene.blueprint.default';
+import { CompositeName } from '../CompositeName';
+
+/**
+ * The dialog elements this blueprint's dialog templates are built from.
+ *
+ * Each is a whole dialog rather than a piece of one, and that is why this package's dialog templates look
+ * so different from the default blueprint's. The default blueprint composes a dialog out of primitives - a
+ * title, a message, a row of buttons - because it has nothing better available. Here the library ships
+ * dialogs that resolve their result through Arc's dialog context, so the frame, the buttons and the
+ * protocol behind them all belong to the composite. A template's job is to configure one, not to rebuild it.
+ */
+
+/**
+ * The Arc-aware dialog: a frame whose result resolves through Arc's dialog context.
+ *
+ * Worth shadowing PrimeReact's `dialog` for. PrimeReact's is a modal frame and nothing more; this one lets
+ * a caller `await` a `DialogResult` instead of threading `visible` state and callbacks by hand, which is
+ * the difference between a dialog you can call and a dialog you have to wire.
+ *
+ * `visible` is left at the adapter's default of `true`, because a dialog placed in a template is placed to
+ * be seen; a host that drives visibility sets the property itself.
+ */
+export function dialog(id: string, title: string, okLabel: string, cancelLabel: string, content: SceneElement[]): SceneElement {
+    return externalComponent(id, CompositeName.Dialog, { title, okLabel, cancelLabel, width: '28rem' }, { content });
+}
+
+/**
+ * A dialog whose confirm button *is* the command's execution.
+ *
+ * Worth using instead of composing `dialog` with `commandForm`, because a hand-composed pair has no way to
+ * keep the dialog open on a rejected command without reimplementing the protocol: this one submits, feeds
+ * the backend's validation results back onto the fields, and only closes when the command succeeded.
+ */
+export function commandDialog(id: string, command: string, title: string, okLabel: string, fields: SceneElement[]): SceneElement {
+    return externalComponent(id, CompositeName.CommandDialog, { command, title, okLabel, cancelLabel: 'Cancel', width: '32rem' }, { content: fields });
+}
+
+/**
+ * The blocking spinner shown while a long-running command is in flight.
+ *
+ * In a running application it is the Arc dialog host that renders this, threading its own title and
+ * message through. Shipping it as a template is what lets its wording and placement be *designed* rather
+ * than discovered the first time an operation takes a while - which is the only moment anyone ever sees it,
+ * and the worst moment to be reading a sentence nobody wrote on purpose.
+ */
+export function busyIndicatorDialog(id: string, title: string, message: string): SceneElement {
+    return externalComponent(id, CompositeName.BusyIndicatorDialog, { title, message });
+}

package/templates/dialogTemplates.ts

@@ -0,0 +1,105 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DialogTemplate } from '@cratis/scene.model';
+import { TemplateSlotName } from '@cratis/scene.blueprint.default';
+import { busyIndicatorDialog, commandDialog, dialog } from './dialogElements';
+import { icon } from './elements';
+import { calendarField, inputTextField, numberField, textAreaField } from './formElements';
+import { SampleBindingName } from './SampleBindingName';
+
+/**
+ * The three dialog shapes an Arc application repeats: submit a command, confirm something destructive, and
+ * say that something long-running is in flight.
+ *
+ * A dialog template has no `fitsSlot`, and that absence is the whole distinction from a screen template. A
+ * screen template is *placed* - it fills a slot on whatever contains it, and the containment chain decides
+ * where it appears. A dialog is *summoned*: it opens over the application from wherever the code that
+ * opened it happens to be, so there is no parent slot for it to name.
+ *
+ * Every one of these declares exactly one slot, which is a real departure from how the default blueprint
+ * builds its dialogs, and the reason is worth stating. The default blueprint composes a dialog out of
+ * primitives - a title, a message, a row of buttons - because primitives are all it has. Here the library
+ * ships whole dialogs that resolve their result through Arc's dialog context, so the frame, the title bar
+ * and the buttons all belong to the composite. A template that declared `header` and `actions` slots would
+ * be offering regions that render *outside* the modal, which is worse than not offering them: a screen
+ * would fill them, and the content would appear somewhere nobody expected.
+ */
+
+/**
+ * A command dialog: a short capture whose confirm button is the command's execution.
+ *
+ * Worth reaching for instead of composing `dialog` with `commandForm`, because a hand-composed pair has no
+ * way to keep the dialog open on a rejected command without reimplementing the protocol. This one submits,
+ * feeds the backend's validation results back onto the fields, and only closes when the command succeeded.
+ *
+ * The fields are placed by hand rather than generated, which is the opposite choice from `CommandFormPage`
+ * and deliberate. A dialog is a *short* capture: three or four properties chosen because they are the ones
+ * a person can answer in an overlay. Generating every property of the command would turn an overlay into a
+ * page, which is precisely the decision a dialog is supposed to have already made.
+ */
+export const commandDialogTemplate: DialogTemplate = {
+    name: 'CommandDialog',
+    slots: [{ name: TemplateSlotName.Body }],
+    content: {
+        [TemplateSlotName.Body]: [
+            commandDialog('command-dialog', SampleBindingName.RecordAdjustment, 'Record an adjustment', 'Record', [
+                numberField('command-dialog-amount', 'amount', 'Amount'),
+                inputTextField('command-dialog-reason', 'reason', 'Reason', 'Damaged goods'),
+                calendarField('command-dialog-effective', 'effective', 'Effective from'),
+                textAreaField('command-dialog-note', 'note', 'Note', 3),
+            ]),
+        ],
+    },
+    displayName: 'Command dialog',
+    description: 'A short capture whose confirm button submits the command and only closes when it succeeded.',
+};
+
+/**
+ * A confirmation dialog: one question, the consequence spelled out, and a way back.
+ *
+ * The Arc-aware `dialog` rather than PrimeReact's, because a caller `await`s a `DialogResult` from it
+ * instead of threading `visible` state and callbacks by hand - which is the difference between a
+ * confirmation you can call from a handler and one you have to wire into a component's state.
+ *
+ * The confirm label says what will happen rather than `OK`. A confirmation whose buttons are `OK` and
+ * `Cancel` makes the reader map the question onto the answer under time pressure, which is exactly when
+ * they will get it wrong.
+ */
+export const confirmDialogTemplate: DialogTemplate = {
+    name: 'ConfirmDialog',
+    slots: [{ name: TemplateSlotName.Body }],
+    content: {
+        [TemplateSlotName.Body]: [
+            dialog('confirm-dialog', 'Void this invoice?', 'Void it', 'Keep it', [
+                icon('confirm-dialog-icon', 'pi pi-exclamation-triangle'),
+                inputTextField('confirm-dialog-reason', 'reason', 'Why is it being voided?', 'Duplicate of INV-2041'),
+            ]),
+        ],
+    },
+    displayName: 'Confirmation dialog',
+    description: 'One question with the consequence spelled out, answered through Arc dialog context.',
+};
+
+/**
+ * A busy dialog: the blocking spinner shown while a long-running command is in flight.
+ *
+ * In a running application the Arc dialog host renders this, threading its own title and message through.
+ * Shipping it as a template is what lets its wording be *designed* rather than discovered the first time an
+ * operation takes a while - which is the only moment anyone ever sees it, and the worst possible moment to
+ * be reading a sentence nobody wrote on purpose.
+ */
+export const busyDialogTemplate: DialogTemplate = {
+    name: 'BusyDialog',
+    slots: [{ name: TemplateSlotName.Body }],
+    content: {
+        [TemplateSlotName.Body]: [
+            busyIndicatorDialog('busy-dialog', 'Recording the adjustment', 'The invoice will reappear as soon as the read model catches up.'),
+        ],
+    },
+    displayName: 'Busy dialog',
+    description: 'The blocking spinner shown while a long-running command is in flight, with wording chosen up front.',
+};
+
+/** The dialog templates this blueprint provides. */
+export const componentsDialogTemplates: DialogTemplate[] = [commandDialogTemplate, confirmDialogTemplate, busyDialogTemplate];

package/templates/editorElements.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { externalComponent } from '@cratis/scene.blueprint.default';
+import { CompositeName } from '../CompositeName';
+import { invoiceDocument, invoiceFilters, invoiceNavigationPath, invoiceSchema, invoiceVersions } from './sampleData';
+
+/**
+ * The Arc-free editing and inspection elements this blueprint's templates are built from.
+ *
+ * Unlike everything else in this package these need no binding at all - they take their content straight
+ * out of the property bag - so a template built from them renders as a working page with no host, no
+ * proxies and no backend. That is what makes the editor templates the ones to open first when looking at
+ * this blueprint.
+ */
+
+/**
+ * A JSON schema edited as a typed property tree rather than as text.
+ *
+ * `canEdit` and `canNotEditReason` belong together: in an event-sourced application a schema is very often
+ * deliberately read-only, and saying *why* in the same place is what keeps that from looking like a bug.
+ */
+export function schemaEditor(id: string, eventTypeName: string, canEdit: boolean, canNotEditReason?: string): SceneElement {
+    return externalComponent(id, CompositeName.SchemaEditor, {
+        schema: invoiceSchema,
+        eventTypeName,
+        canEdit,
+        canNotEditReason,
+        editMode: canEdit,
+    });
+}
+
+/** A document rendered against its schema, so nested values are navigable and each is edited by its declared type. */
+export function objectContentEditor(id: string, editMode: boolean): SceneElement {
+    return externalComponent(id, CompositeName.ObjectContentEditor, { object: invoiceDocument, schema: invoiceSchema, editMode });
+}
+
+/** The trail saying where you are inside a nested document, and the way back out. */
+export function objectNavigationalBar(id: string): SceneElement {
+    return externalComponent(id, CompositeName.ObjectNavigationalBar, { navigationPath: invoiceNavigationPath });
+}
+
+/**
+ * The timeline of successive versions.
+ *
+ * Worth a place on a detail page in a way it would not be in a CRUD application: in an event-sourced
+ * system everything *has* a history rather than only a current value, so scrubbing through it is the
+ * natural way to look at a record rather than a special feature.
+ */
+export function timeMachine(id: string): SceneElement {
+    return externalComponent(id, CompositeName.TimeMachine, { versions: invoiceVersions, currentVersionIndex: 0 });
+}
+
+/**
+ * The filter toggle and the panel it anchors, as one element.
+ *
+ * One element rather than two because `FilterPanel` is a portal anchored to a button - it renders next to
+ * whatever opened it, so it cannot be placed on its own, and the element tree has no way to express an
+ * anchor relationship. The adapter owns both halves, and a template places one thing.
+ */
+export function filterPanel(id: string, label: string): SceneElement {
+    return externalComponent(id, CompositeName.FilterPanel, { label, filters: invoiceFilters, searchPlaceholder: 'Search filters' });
+}
+
+/** A standalone selection control, not bound to a command property. */
+export function dropdown(id: string, placeholder: string, options: { label: string; value: string }[]): SceneElement {
+    return externalComponent(id, CompositeName.Dropdown, { placeholder, options, showClear: true });
+}

package/templates/editorTemplates.ts

@@ -0,0 +1,129 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ScreenTemplate, WidthSizeClass } from '@cratis/scene.model';
+import { SlotName, TemplateSlotName, column, row, slotLeaf } from '@cratis/scene.blueprint.default';
+import { filterPanel, objectContentEditor, objectNavigationalBar, schemaEditor, timeMachine } from './editorElements';
+import { arcPageHeader, errorBoundary, page, toolbar, toolbarButton, toolbarSeparator } from './elements';
+import { SampleBindingName } from './SampleBindingName';
+
+/**
+ * The two inspection pages: one for a type's shape, one for an instance's content.
+ *
+ * These are the templates to open first when looking at this blueprint, because they are the two that
+ * render completely with nothing registered. The schema editor, the document editor, the navigational bar
+ * and the time machine all read their content out of the property bag rather than from a query, so a
+ * preview of either page is a working page rather than a page of placeholders.
+ *
+ * That is not a trick to make a demo look better. It is the honest shape of the library: most of
+ * `@cratis/components` is Arc-bound and needs a host, and a meaningful part of it is not. A blueprint built
+ * on it should make both halves visible.
+ */
+
+/**
+ * The schema editor page: an event type's shape, edited as a typed property tree.
+ *
+ * Its header names no binding, and that is correct rather than an omission. A schema is design-time
+ * metadata about an event type, not a read model anyone queries, so there is nothing for the header to be
+ * bound to - and the header says `No binding` instead of implying a wiring step that does not exist. It is
+ * the one page in this package where the unbound state is the finished state.
+ *
+ * `canEdit` is paired with `canNotEditReason` deliberately: in an event-sourced application a stored event
+ * type's schema is very often deliberately locked, and saying why in the same place is what stops that
+ * from reading as a bug.
+ */
+export const schemaEditorPageTemplate: ScreenTemplate = {
+    name: 'SchemaEditorPage',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Toolbar }, { name: TemplateSlotName.Body }],
+    arrangement: {
+        root: column([slotLeaf(TemplateSlotName.Header), slotLeaf(TemplateSlotName.Toolbar), slotLeaf(TemplateSlotName.Body, { grow: 1 })], 16),
+    },
+    content: {
+        [TemplateSlotName.Header]: [
+            arcPageHeader('schema-header', {
+                title: 'InvoiceRegistered',
+                subtitle: 'The shape of the event, and what a new generation would be allowed to change',
+                section: 'Event types',
+            }),
+        ],
+        [TemplateSlotName.Toolbar]: [
+            toolbar('schema-toolbar', [
+                toolbarButton('schema-edit', 'Edit the schema', 'pi pi-pencil', 'Edit'),
+                toolbarButton('schema-generation', 'Start a new generation', 'pi pi-clone', 'New generation'),
+                toolbarSeparator('schema-separator'),
+                toolbarButton('schema-download', 'Download as JSON Schema', 'pi pi-download'),
+            ]),
+        ],
+        [TemplateSlotName.Body]: [
+            page('schema-body', 'InvoiceRegistered', [schemaEditor('schema-editor', 'InvoiceRegistered', true)]),
+        ],
+    },
+    displayName: 'Schema editor page',
+    description: "An event type's schema edited as a typed property tree, with the actions that evolve it.",
+};
+
+/**
+ * The object editor page: one document, its trail, and its history beside it.
+ *
+ * Bound to `InvoiceById`, because that is what a real page like this is: you arrive with an id, the query
+ * fetches the record, and the editor renders it against its schema. The editors themselves take their
+ * content from the property bag, so the page is fully legible before the query is wired - and the header
+ * still says which query it is waiting for.
+ *
+ * The document is wrapped in an `errorBoundary` and the history is not, which is the decision this element
+ * exists to let a template make. A malformed document should cost the document region; it should not take
+ * the trail and the timeline down with it, and the timeline is the thing you would reach for to find out
+ * *when* the document became malformed.
+ */
+export const objectEditorPageTemplate: ScreenTemplate = {
+    name: 'ObjectEditorPage',
+    fitsSlot: SlotName.Content,
+    slots: [
+        { name: TemplateSlotName.Header },
+        { name: TemplateSlotName.Toolbar },
+        { name: TemplateSlotName.Body },
+        { name: TemplateSlotName.SidePanel },
+    ],
+    arrangement: {
+        root: column([
+            slotLeaf(TemplateSlotName.Header),
+            slotLeaf(TemplateSlotName.Toolbar),
+            row([slotLeaf(TemplateSlotName.Body, { grow: 2 }), slotLeaf(TemplateSlotName.SidePanel, { grow: 1 })], 16),
+        ]),
+        overrides: [
+            {
+                width: WidthSizeClass.Compact,
+                root: column(
+                    [
+                        slotLeaf(TemplateSlotName.Header),
+                        slotLeaf(TemplateSlotName.Toolbar),
+                        slotLeaf(TemplateSlotName.Body),
+                        slotLeaf(TemplateSlotName.SidePanel),
+                    ],
+                    16,
+                ),
+            },
+        ],
+    },
+    content: {
+        [TemplateSlotName.Header]: [
+            arcPageHeader('object-header', {
+                title: 'INV-2043',
+                subtitle: 'The document as it stands, and every version it has been',
+                section: 'Billing',
+                query: SampleBindingName.InvoiceById,
+            }),
+        ],
+        [TemplateSlotName.Toolbar]: [objectNavigationalBar('object-trail'), filterPanel('object-filters', 'Filters')],
+        [TemplateSlotName.Body]: [
+            errorBoundary('object-guard', [page('object-body', 'Document', [objectContentEditor('object-editor', true)])]),
+        ],
+        [TemplateSlotName.SidePanel]: [page('object-history', 'History', [timeMachine('object-time-machine')])],
+    },
+    displayName: 'Object editor page',
+    description: 'One document edited against its schema, with its navigation trail and its version history.',
+};
+
+/** The two editor-shaped templates. */
+export const editorTemplates: ScreenTemplate[] = [schemaEditorPageTemplate, objectEditorPageTemplate];

package/templates/elements.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { externalComponent } from '@cratis/scene.blueprint.default';
+import { ComponentName } from '../ComponentName';
+import { CompositeName } from '../CompositeName';
+import { ArcHeaderOptions } from './ArcHeaderOptions';
+
+/**
+ * The page furniture every template in this package repeats.
+ *
+ * `externalComponent` is imported from the default blueprint rather than written again, and that is worth
+ * pausing on: `ExternalComponent` inherits fifteen required members before it reaches the two a template
+ * author cares about, so a package that redeclared those defaults would be maintaining a second copy of a
+ * decision it does not own. Borrowing the builder is the same choice as depending on the shell - this
+ * blueprint layers on the default one, so it uses its parts.
+ */
+
+/**
+ * This blueprint's page header, given its heading and the one binding the page is about.
+ *
+ * Every template opens with one. The header derives the trail and the design-time binding state itself, so
+ * a template states the page's subject once instead of repeating it in a title, a trail and a table.
+ */
+export function arcPageHeader(id: string, options: ArcHeaderOptions, actions: SceneElement[] = []): SceneElement {
+    return externalComponent(id, ComponentName.ArcPageHeader, { ...options }, { actions });
+}
+
+/**
+ * The library's `page` primitive wrapping content.
+ *
+ * A `div` would have done structurally, and would have been wrong: `page` is the full-height flex column
+ * every other component in `@cratis/components` is laid out inside, drawn from the same `--cratis-*`
+ * tokens as the tables and dialogs it contains. Content wrapped in it gets that consistency for free, and
+ * content wrapped in a `div` has to reinvent it and will drift.
+ */
+export function page(id: string, title: string, content: SceneElement[], panel = true): SceneElement {
+    return externalComponent(id, CompositeName.Page, { title, showTitle: title.length > 0, panel }, { content });
+}
+
+/** One button in a tool palette. `title` is the accessible name as well as the tooltip, so it is never omitted. */
+export function toolbarButton(id: string, title: string, icon: string, text?: string): SceneElement {
+    return externalComponent(id, CompositeName.ToolbarButton, { title, icon, text });
+}
+
+/** Related buttons kept together inside a toolbar. */
+export function toolbarGroup(id: string, buttons: SceneElement[]): SceneElement {
+    return externalComponent(id, CompositeName.ToolbarGroup, { orientation: 'horizontal' }, { content: buttons });
+}
+
+/** The divider between groups of tools. */
+export function toolbarSeparator(id: string): SceneElement {
+    return externalComponent(id, CompositeName.ToolbarSeparator, { orientation: 'horizontal' });
+}
+
+/**
+ * A horizontal tool palette.
+ *
+ * `draggable` is deliberately left off rather than set per button - it is a property of the palette, and
+ * setting it per button is how you end up with a palette that is half draggable.
+ */
+export function toolbar(id: string, content: SceneElement[]): SceneElement {
+    return externalComponent(id, CompositeName.Toolbar, { orientation: 'horizontal' }, { content });
+}
+
+/**
+ * Scopes a failure to one region of a page.
+ *
+ * React's default is that a throw anywhere unmounts the whole tree, which on a composed screen means one
+ * broken widget takes the navigation with it. Which regions deserve a boundary is a decision about the
+ * page, which is exactly why it belongs in a template rather than in the renderer.
+ */
+export function errorBoundary(id: string, content: SceneElement[]): SceneElement {
+    return externalComponent(id, CompositeName.ErrorBoundary, {}, { content });
+}
+
+/** An icon, given a PrimeIcons class name. */
+export function icon(id: string, iconName: string): SceneElement {
+    return externalComponent(id, CompositeName.Icon, { icon: iconName });
+}

package/templates/formElements.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { externalComponent } from '@cratis/scene.blueprint.default';
+import { CompositeName } from '../CompositeName';
+
+/**
+ * The Arc-bound form elements this blueprint's templates are built from.
+ *
+ * Every field carries a `property` name, which the library turns into an accessor onto the command
+ * instance. That indirection is not incidental: a hand-written form binds a field with
+ * `value={command => command.number}` and is typechecked against the generated proxy, and a template has
+ * no types to check against because it is data. The name is what survives, so the name is what a field
+ * carries.
+ */
+
+/**
+ * A whole form generated from the command's own property descriptors.
+ *
+ * `commandForm` is `AutoCommandForm`, not `CommandForm`, and that is what makes it worth shipping in a
+ * template at all: a template that listed every field by hand would go stale the moment a property was
+ * added to the command on the backend, and a stale template is worse than no template. This one follows
+ * the command, which is the same guarantee Arc's generated proxies give the rest of the stack.
+ *
+ * @param exclude Properties the surrounding template places itself, so the generated form does not produce a second copy.
+ */
+export function commandForm(id: string, command: string, exclude?: string[]): SceneElement {
+    return externalComponent(id, CompositeName.CommandForm, { command, exclude });
+}
+
+/** A single-line text field bound to one command property. */
+export function inputTextField(id: string, property: string, title: string, placeholder?: string): SceneElement {
+    return externalComponent(id, CompositeName.InputTextField, { property, title, placeholder });
+}
+
+/** A numeric field bound to one command property. */
+export function numberField(id: string, property: string, title: string): SceneElement {
+    return externalComponent(id, CompositeName.NumberField, { property, title });
+}
+
+/** A multi-line text field bound to one command property. */
+export function textAreaField(id: string, property: string, title: string, rows = 3): SceneElement {
+    return externalComponent(id, CompositeName.TextAreaField, { property, title, rows });
+}
+
+/** A date field bound to one command property. */
+export function calendarField(id: string, property: string, title: string): SceneElement {
+    return externalComponent(id, CompositeName.CalendarField, { property, title });
+}
+
+/**
+ * A single-selection field over a list the template carries inline.
+ *
+ * Inline options only. A list that has to come from the backend is a different thing entirely - bind it to
+ * a query - because a property bag is the wrong place for data, and a template that embedded a real
+ * lookup table would be shipping someone else's reference data.
+ */
+export function dropdownField(id: string, property: string, title: string, options: { label: string; value: string }[]): SceneElement {
+    return externalComponent(id, CompositeName.DropdownField, { property, title, options });
+}

package/templates/index.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './SampleBindingName';
+export * from './ColumnDefinition';
+export * from './TableOptions';
+export * from './ArcHeaderOptions';
+export * from './sampleData';
+export * from './elements';
+export * from './dataElements';
+export * from './formElements';
+export * from './dialogElements';
+export * from './editorElements';
+export * from './listTemplates';
+export * from './workspaceTemplates';
+export * from './commandTemplates';
+export * from './editorTemplates';
+export * from './nesting';
+export * from './dialogTemplates';
+export * from './screenTemplates';