@cratis/scene.blueprint.default 0.1.0

package/gallery/nesting.ts

@@ -0,0 +1,82 @@
+// 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 { ComponentName } from '../ComponentName';
+import { SlotName, column, slotLeaf } from '../layouts';
+import { TemplateSlotName } from './TemplateSlotName';
+import { button, externalComponent } from './elements';
+import { pageHeader } from './widgets';
+
+/**
+ * A worked three-level chain, from the application layout down to a slice.
+ *
+ * The nesting rule is one rule applied at every depth: a template names, in `fitsSlot`, a slot declared by
+ * whatever contains it. A module's template fits the application layout's `content`; a feature's template
+ * fits a slot the module's template declares; a slice's fits one the feature's declares. Nothing here is a
+ * special case for a particular level - which is exactly why the hierarchy can be arbitrarily deep without
+ * a second mechanism.
+ *
+ * These three exist to make that concrete and to be asserted by a spec, because "it composes recursively"
+ * is the kind of claim that is true in a design document and wrong in the code.
+ */
+
+/**
+ * Module level: fits the application shell's `content` slot.
+ *
+ * It brings its own header - a module always has a name and a description - and offers a body for the
+ * feature inside it plus an optional side panel.
+ */
+export const moduleWorkspaceTemplate: ScreenTemplate = {
+    name: 'ModuleWorkspace',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Body }, { name: TemplateSlotName.SidePanel }],
+    content: {
+        [TemplateSlotName.Header]: [pageHeader('module-header', 'Operations', 'Everything the operations module owns')],
+    },
+    displayName: 'Module workspace',
+    description: 'Module level: fits the application layout content slot and offers a body for one feature.',
+};
+
+/**
+ * Feature level: fits the module workspace's `body` slot.
+ *
+ * It brings a toolbar, because a feature is where actions belong - a module is a grouping, a slice is one
+ * behavior, and the feature in between is what a user thinks of as a screen with buttons on it.
+ */
+export const featureSectionTemplate: ScreenTemplate = {
+    name: 'FeatureSection',
+    fitsSlot: TemplateSlotName.Body,
+    slots: [{ name: TemplateSlotName.Toolbar }, { name: TemplateSlotName.Body }],
+    content: {
+        [TemplateSlotName.Toolbar]: [
+            button('feature-new', 'New', { severity: 'primary', icon: 'pi pi-plus' }),
+            button('feature-export', 'Export', { severity: 'secondary', icon: 'pi pi-download' }),
+        ],
+    },
+    displayName: 'Feature section',
+    description: 'Feature level: fits a module workspace body slot and brings the action toolbar.',
+};
+
+/**
+ * Slice level: fits the feature section's `body` slot.
+ *
+ * The end of the chain, and deliberately the thinnest thing in it - one behavior's surface, with somewhere
+ * to put it and somewhere to put its actions.
+ */
+export const sliceSectionTemplate: ScreenTemplate = {
+    name: 'SliceSection',
+    fitsSlot: TemplateSlotName.Body,
+    slots: [{ name: TemplateSlotName.Body }, { name: TemplateSlotName.Actions }],
+    arrangement: {
+        root: column([slotLeaf(TemplateSlotName.Body, { grow: 1 }), slotLeaf(TemplateSlotName.Actions)]),
+    },
+    content: {
+        [TemplateSlotName.Body]: [externalComponent('slice-body', ComponentName.PageHeader, { title: 'Adjustment', subtitle: 'One behavior, one surface' })],
+    },
+    displayName: 'Slice section',
+    description: 'Slice level: fits a feature section body slot and hosts one behavior.',
+};
+
+/** The chain, outermost first - what a spec walks to prove `fitsSlot` resolves at every level. */
+export const nestingChainTemplates: ScreenTemplate[] = [moduleWorkspaceTemplate, featureSectionTemplate, sliceSectionTemplate];

package/gallery/previewProfile.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 { UiProfile } from '@cratis/scene.model';
+import { PackageCatalog } from '@cratis/scene.engine';
+import { ComponentName } from '../ComponentName';
+import { defaultBlueprintName } from '../packageName';
+import { coreComponentNames, cratisComponentsNames, primeReactComponentNames } from './dependencyComponentNames';
+
+/**
+ * The profile the gallery is previewed against.
+ *
+ * `core` is listed explicitly rather than left to `effectivePackages` to prepend, because a theme's
+ * compatibility is checked against exactly what the profile declares - and a profile that leans on the
+ * implicit fallback would make a theme look incompatible with a package the profile never admitted to
+ * using. Declaration order is ascending priority, so this blueprint's own names win over the component
+ * libraries', which is what lets it provide a `breadcrumb` of its own without hiding PrimeReact's.
+ */
+export const galleryProfile: UiProfile = {
+    name: 'Gallery',
+    targetPlatform: 'web',
+    packages: ['core', 'PrimeReact', 'Cratis.Components', defaultBlueprintName],
+};
+
+/**
+ * The profile a *preview* resolves against, when only some of those packages are actually loaded.
+ *
+ * Same four packages, different order, and the difference is deliberate. This blueprint takes no npm
+ * dependency on PrimeReact's or Cratis Components' bundles - a blueprint declares its dependencies in its
+ * manifest, not in its bundler graph - so a preview run from this package has `core` and this blueprint
+ * implemented and nothing else. Ranking `core` above the two libraries means `text`, `button` and `card`
+ * resolve to something that exists, and the preview shows real content instead of a wall of placeholders.
+ *
+ * Names only the libraries declare - `dataTable`, `timeline`, `tag` - still resolve to them, find no
+ * implementation, and render as `UnresolvedComponent`'s dashed box naming what is missing. That is the
+ * right outcome rather than a papered-over one: previewing a blueprint against half a profile *should*
+ * look visibly incomplete. A host with all four bundles loaded uses {@link galleryProfile} and sees the
+ * real widgets.
+ */
+export const galleryPreviewProfile: UiProfile = {
+    name: 'Gallery preview',
+    targetPlatform: 'web',
+    packages: ['PrimeReact', 'Cratis.Components', 'core', defaultBlueprintName],
+};
+
+/**
+ * The component catalog the gallery resolves against.
+ *
+ * This blueprint's own entry is its real declared component list; the other three are the subsets it
+ * borrows, each name checked against the owning package's own manifest (see `dependencyComponentNames.ts`).
+ * A host that has all four packages loaded should build this 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 galleryComponentCatalog: PackageCatalog = {
+    core: coreComponentNames,
+    PrimeReact: primeReactComponentNames,
+    'Cratis.Components': cratisComponentsNames,
+    [defaultBlueprintName]: Object.values(ComponentName),
+};

package/gallery/resolveElementNames.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ContentControl, ExternalComponent, ItemsControl, Panel, SceneElement, UiProfile } from '@cratis/scene.model';
+import { PackageCatalog, isContentControl, isExternalComponent, isItemsControl, isPanel, resolveComponentName } from '@cratis/scene.engine';
+import { componentRegistryKey } from '@cratis/scene.react';
+
+/**
+ * Rewrites an element tree's bare component names into the keys the React registry is keyed by.
+ *
+ * The renderer looks a component up by `element.componentName` against a registry keyed by
+ * `componentRegistryKey(package, name)`, so something has to resolve bare names against the active profile
+ * first. Wiring that into the renderer proper is Stage's job and does not exist yet; this is the small
+ * local version that lets the gallery boot through the *real* engine and the *real* registry today rather
+ * than waiting for it.
+ *
+ * A name nothing declares is left exactly as written. That is deliberate: the renderer then falls back to
+ * `UnresolvedComponent` and shows a dashed red box naming the component, which is far more useful than a
+ * throw from inside a tree walk.
+ *
+ * @param element The tree to rewrite.
+ * @param profile The profile whose package priority decides which package wins a bare name.
+ * @param catalog Each active package's declared component names.
+ * @returns A new tree; the original is untouched.
+ */
+export function resolveElementComponentNames(element: SceneElement, profile: UiProfile, catalog: PackageCatalog): SceneElement {
+    if (isExternalComponent(element)) {
+        const resolution = resolveComponentName(element.componentName, profile, catalog);
+        const resolved: ExternalComponent = {
+            ...element,
+            componentName: resolution ? componentRegistryKey(resolution.package, resolution.name) : element.componentName,
+            slots: Object.fromEntries(
+                Object.entries(element.slots).map(([name, children]) => [name, children.map(child => resolveElementComponentNames(child, profile, catalog))]),
+            ),
+        };
+        return resolved;
+    }
+
+    if (isContentControl(element)) {
+        const contentControl: ContentControl = { ...element, content: resolveElementComponentNames(element.content, profile, catalog) };
+        return contentControl;
+    }
+
+    if (isItemsControl(element)) {
+        const itemsControl: ItemsControl = { ...element, itemTemplate: resolveElementComponentNames(element.itemTemplate, profile, catalog) };
+        return itemsControl;
+    }
+
+    if (isPanel(element)) {
+        const panel: Panel = { ...element, children: element.children.map(child => resolveElementComponentNames(child, profile, catalog)) };
+        return panel;
+    }
+
+    return element;
+}

package/gallery/screens.ts

@@ -0,0 +1,111 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Layout, Screen, ScreenTemplate } from '@cratis/scene.model';
+import { LayoutName, appShellLayout, fullPageLayout } from '../layouts';
+import { BreadcrumbEntry, applicationChrome, fullPageChrome } from './applicationChrome';
+import { nestScreenTemplates, templateContentInLayout } from './composeScreen';
+import { authTemplates } from './authTemplates';
+import { navigationContributions } from './navigation';
+import { nestingChainTemplates } from './nesting';
+import { statusTemplates } from './statusTemplates';
+import { supportTemplates } from './supportTemplates';
+import { workspaceTemplates } from './workspaceTemplates';
+
+/**
+ * The screen templates this blueprint provides.
+ *
+ * Ten shapes for inside the application shell, ten for the full-page shell, and the three-level nesting
+ * chain that demonstrates how `fitsSlot` composes. The list is what the manifest's `screenTemplates` names
+ * and what the bundle provides; `validatePackageBundle` proves the two agree.
+ */
+export const galleryScreenTemplates: ScreenTemplate[] = [
+    ...workspaceTemplates,
+    ...supportTemplates,
+    ...authTemplates,
+    ...statusTemplates,
+    ...nestingChainTemplates,
+];
+
+/** Which layout each template renders inside - the application shell unless it is one of the chrome-less screens. */
+const fullPageTemplateNames = new Set([...authTemplates, ...statusTemplates].map(template => template.name));
+
+/** The trail shown above each application-shell screen. */
+const breadcrumbs: Record<string, BreadcrumbEntry[]> = {
+    Dashboard: [{ label: 'Dashboard' }],
+    CrudList: [{ label: 'Catalog', targetScreen: 'Dashboard' }, { label: 'Products' }],
+    DetailView: [{ label: 'Catalog', targetScreen: 'Dashboard' }, { label: 'Products', targetScreen: 'CrudList' }, { label: 'Bamboo Watch' }],
+    FormPage: [{ label: 'Catalog', targetScreen: 'Dashboard' }, { label: 'Products', targetScreen: 'CrudList' }, { label: 'New product' }],
+    Empty: [{ label: 'Catalog', targetScreen: 'Dashboard' }, { label: 'Products' }],
+    Documentation: [{ label: 'Support', targetScreen: 'Dashboard' }, { label: 'Documentation' }],
+    ProfileSettings: [{ label: 'Administration', targetScreen: 'Dashboard' }, { label: 'Your profile' }],
+    UserManagement: [{ label: 'Administration', targetScreen: 'Dashboard' }, { label: 'Users' }],
+    Invoice: [{ label: 'Billing', targetScreen: 'Dashboard' }, { label: 'INV-2043' }],
+    Help: [{ label: 'Support', targetScreen: 'Dashboard' }, { label: 'Help' }],
+    ModuleWorkspace: [{ label: 'Operations' }],
+    FeatureSection: [{ label: 'Operations', targetScreen: 'ModuleWorkspace' }, { label: 'Adjustments' }],
+    SliceSection: [
+        { label: 'Operations', targetScreen: 'ModuleWorkspace' },
+        { label: 'Adjustments', targetScreen: 'FeatureSection' },
+        { label: 'Record an adjustment' },
+    ],
+};
+
+/**
+ * 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 isFullPage = fullPageTemplateNames.has(template.name);
+    const layout: Layout = isFullPage ? fullPageLayout : appShellLayout;
+    const chrome = isFullPage ? fullPageChrome() : applicationChrome(template.name, breadcrumbs[template.name] ?? [{ label: template.displayName ?? template.name }]);
+    const placeable = nestScreenTemplates(containmentChainFor(template));
+
+    return {
+        name: template.name,
+        layout: isFullPage ? LayoutName.FullPage : LayoutName.AppShell,
+        screenTemplate: template.name,
+        slotContent: mergeSlotContent(chrome, templateContentInLayout(placeable, layout)),
+        forms: [],
+        contributions: isFullPage ? [] : navigationContributions,
+    };
+}
+
+/**
+ * The chain of templates a screen renders through, outermost first.
+ *
+ * Almost every template fits the layout's own `content` slot, so its 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;
+}
+
+/**
+ * The gallery: one 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.
+ */
+export const galleryScreens: Screen[] = galleryScreenTemplates.map(screenFor);
+
+/** One gallery screen by name, for a story or a host that boots a specific one. */
+export function galleryScreen(name: string): Screen | undefined {
+    return galleryScreens.find(screen => screen.name === name);
+}

package/gallery/statusTemplates.ts

@@ -0,0 +1,118 @@
+// 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 { ComponentName } from '../ComponentName';
+import { SlotName } from '../layouts';
+import { TemplateSlotName } from './TemplateSlotName';
+import { button, card, externalComponent, panel, text } from './elements';
+import { widget } from './widgets';
+
+/**
+ * The four screens that are not part of anyone's plan: a server error, a refusal, a wrong address, and the
+ * page that has to sell the product before any of the others exist.
+ *
+ * They use the full-page layout for the same reason the sign-in screens do - none of them has navigation
+ * to render - and they matter more than their frequency suggests. An error page is the screen most likely
+ * to be someone's first impression of how carefully an application was built.
+ */
+
+/** Something broke on our side. */
+export const errorTemplate: ScreenTemplate = {
+    name: 'Error',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Body }],
+    content: {
+        [TemplateSlotName.Body]: [
+            card('error-card', [
+                externalComponent('error-tag', 'tag', { value: '500', severity: 'danger' }),
+                text('error-title', 'Something went wrong on our side'),
+                text('error-message', 'The team has been told. Try again in a moment - nothing you were working on was lost.'),
+                panel('error-actions', [
+                    button('error-retry', 'Try again', { severity: 'primary' }),
+                    button('error-home', 'Back to the dashboard', { severity: 'secondary', targetScreen: 'Dashboard' }),
+                ]),
+            ]),
+        ],
+    },
+    displayName: 'Error',
+    description: 'A server-side failure, said plainly, with a way onward.',
+};
+
+/** Signed in, and still not allowed. */
+export const accessDeniedTemplate: ScreenTemplate = {
+    name: 'AccessDenied',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Body }],
+    content: {
+        [TemplateSlotName.Body]: [
+            card('denied-card', [
+                externalComponent('denied-tag', 'tag', { value: '403', severity: 'warning' }),
+                text('denied-title', 'You do not have access to this'),
+                text('denied-message', 'Your account is signed in, but it is not allowed here. An administrator can change that.'),
+                panel('denied-actions', [
+                    button('denied-request', 'Request access', { severity: 'primary' }),
+                    button('denied-home', 'Back to the dashboard', { severity: 'secondary', targetScreen: 'Dashboard' }),
+                ]),
+            ]),
+        ],
+    },
+    displayName: 'Access denied',
+    description: 'A refusal that distinguishes "not signed in" from "not allowed".',
+};
+
+/** No such address. */
+export const notFoundTemplate: ScreenTemplate = {
+    name: 'NotFound',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Body }],
+    content: {
+        [TemplateSlotName.Body]: [
+            card('not-found-card', [
+                externalComponent('not-found-tag', 'tag', { value: '404', severity: 'info' }),
+                text('not-found-title', 'That page is not here'),
+                text('not-found-message', 'The link may be old, or the thing it pointed at may have been removed.'),
+                externalComponent('not-found-search', 'inputText', { placeholder: 'Search instead' }),
+                button('not-found-home', 'Back to the dashboard', { severity: 'secondary', targetScreen: 'Dashboard' }),
+            ]),
+        ],
+    },
+    displayName: 'Not found',
+    description: 'A wrong address, with a search box rather than a dead end.',
+};
+
+/** The page that has to do the selling. */
+export const landingTemplate: ScreenTemplate = {
+    name: 'Landing',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Body }, { name: TemplateSlotName.Actions }],
+    content: {
+        [TemplateSlotName.Header]: [
+            panel('landing-nav', [
+                externalComponent('landing-logo', ComponentName.Logo, { label: 'Contoso', initials: 'C' }),
+                button('landing-signin', 'Sign in', { severity: 'secondary', targetScreen: 'Login' }),
+                button('landing-start', 'Start free', { severity: 'primary', targetScreen: 'Register' }),
+            ]),
+        ],
+        [TemplateSlotName.Body]: [
+            card('landing-hero', [
+                text('landing-headline', 'Ship the shell on day one'),
+                text('landing-subhead', 'Eight menu modes, twenty screen templates and two themes, in one blueprint an application picks once.'),
+                button('landing-cta', 'Start free', { severity: 'primary', targetScreen: 'Register' }),
+            ]),
+            widget('landing-feature-modes', 'Every mode people expect', [text('landing-modes-text', 'Static, overlay, slim, slim+, compact, horizontal, reveal and drawer.')]),
+            widget('landing-feature-themes', 'Themeable to the token', [text('landing-themes-text', 'Ten semantic tokens define the whole shell. Swap them and everything follows.')]),
+            widget('landing-feature-templates', 'The pages you were going to build anyway', [
+                text('landing-templates-text', 'Dashboard, list, detail, form, invoice, settings, help - and every screen around signing in.'),
+            ]),
+        ],
+        [TemplateSlotName.Actions]: [
+            panel('landing-footer', [text('landing-copyright', '© Contoso'), button('landing-contact', 'Talk to us', { severity: 'secondary' })]),
+        ],
+    },
+    displayName: 'Landing',
+    description: 'The marketing front door, with its own navigation because it has no application chrome.',
+};
+
+/** The four status and marketing templates. */
+export const statusTemplates: ScreenTemplate[] = [errorTemplate, accessDeniedTemplate, notFoundTemplate, landingTemplate];

package/gallery/supportTemplates.ts

@@ -0,0 +1,164 @@
+// 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 } from '../layouts';
+import { TemplateSlotName } from './TemplateSlotName';
+import { button, card, externalComponent, text } from './elements';
+import { field, formActions, pageHeader, table, widget } from './widgets';
+
+/**
+ * The five shapes an application needs that are not the CRUD loop: documentation, the signed-in user's own
+ * settings, user administration, a printable document, and help.
+ *
+ * They are in the set because leaving them out is what makes a template line feel thin. Every real
+ * application grows all five, and the ones that were never designed are the ones that end up looking like
+ * a different product.
+ */
+
+/** Documentation: a table of contents beside prose. */
+export const documentationTemplate: ScreenTemplate = {
+    name: 'Documentation',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.SidePanel }, { name: TemplateSlotName.Body }],
+    content: {
+        [TemplateSlotName.SidePanel]: [
+            widget('docs-toc', 'On this page', [
+                text('docs-toc-1', 'Getting started'),
+                text('docs-toc-2', 'Configuring the shell'),
+                text('docs-toc-3', 'Themes'),
+                text('docs-toc-4', 'Publishing a blueprint'),
+            ]),
+        ],
+        [TemplateSlotName.Body]: [
+            pageHeader('docs-header', 'Getting started', 'Everything you need to run the blueprint locally'),
+            card('docs-body', [
+                text('docs-intro', 'Install the blueprint, add it to a ui profile, and pick a layout. The shell reads its mode from the configurator and remembers it.'),
+                externalComponent('docs-note', 'message', { severity: 'info', text: 'The shell needs its stylesheet imported once, at the host.' }),
+            ]),
+        ],
+    },
+    displayName: 'Documentation',
+    description: 'Prose with a table of contents beside it.',
+};
+
+/** Profile settings: the signed-in user editing their own account. */
+export const profileSettingsTemplate: ScreenTemplate = {
+    name: 'ProfileSettings',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Body }, { name: TemplateSlotName.Actions }],
+    content: {
+        [TemplateSlotName.Header]: [pageHeader('profile-header', 'Your profile', 'How you appear to everyone else in the workspace')],
+        [TemplateSlotName.Body]: [
+            card('profile-identity', [
+                externalComponent('profile-avatar', 'avatar', { label: 'AN', size: 'large', shape: 'circle' }),
+                field('profile-name', 'Display name', 'inputText', { value: 'Amelia Nyquist' }),
+                field('profile-email', 'Email', 'inputText', { value: 'amelia@contoso.com' }),
+                externalComponent('profile-photo', 'image', { alt: 'Your current photo' }),
+                button('profile-photo-change', 'Change photo', { severity: 'secondary' }),
+            ]),
+            card('profile-security', [
+                field('profile-current', 'Current password', 'password', {}),
+                field('profile-new', 'New password', 'password', { feedback: true }),
+                field('profile-notify', 'Email me about mentions', 'checkbox', { checked: true }),
+            ]),
+        ],
+        [TemplateSlotName.Actions]: [formActions('profile-actions', 'Save changes')],
+    },
+    displayName: 'Profile settings',
+    description: 'The signed-in user editing their own name, photo, password and notifications.',
+};
+
+/** User management: administering everybody else. */
+export const userManagementTemplate: ScreenTemplate = {
+    name: 'UserManagement',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Toolbar }, { name: TemplateSlotName.Body }],
+    content: {
+        [TemplateSlotName.Toolbar]: [
+            pageHeader('users-header', 'Users', '34 people, 3 pending invitations', [button('users-invite', 'Invite people', { severity: 'primary', icon: 'pi pi-user-plus' })]),
+        ],
+        [TemplateSlotName.Body]: [
+            table(
+                'users-table',
+                [
+                    { field: 'name', header: 'Name' },
+                    { field: 'email', header: 'Email' },
+                    { field: 'role', header: 'Role' },
+                    { field: 'status', header: 'Status' },
+                    { field: 'lastSeen', header: 'Last seen' },
+                ],
+                [
+                    { name: 'Amelia Nyquist', email: 'amelia@contoso.com', role: 'Owner', status: 'Active', lastSeen: '2 minutes ago' },
+                    { name: 'Bjørn Holt', email: 'bjorn@contoso.com', role: 'Administrator', status: 'Active', lastSeen: 'Yesterday' },
+                    { name: 'Chidi Okafor', email: 'chidi@contoso.com', role: 'Editor', status: 'Active', lastSeen: '3 days ago' },
+                    { name: 'Dana Whitfield', email: 'dana@contoso.com', role: 'Viewer', status: 'Invited', lastSeen: 'Never' },
+                ],
+            ),
+        ],
+    },
+    displayName: 'User management',
+    description: 'The people table, with roles, status and an invitation action.',
+};
+
+/** Invoice: a printable document, which is a different shape from a screen. */
+export const invoiceTemplate: ScreenTemplate = {
+    name: 'Invoice',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Body }, { name: TemplateSlotName.Actions }],
+    content: {
+        [TemplateSlotName.Header]: [
+            pageHeader('invoice-header', 'Invoice INV-2043', 'Issued 4 March · Due 3 April', [button('invoice-print', 'Print', { severity: 'secondary', icon: 'pi pi-print' })]),
+        ],
+        [TemplateSlotName.Body]: [
+            card('invoice-parties', [
+                text('invoice-from', 'From: Contoso Ltd, 4 Chandler Street, Dublin'),
+                text('invoice-to', 'To: Northwind Traders, 18 Quay Road, Cork'),
+            ]),
+            table(
+                'invoice-lines',
+                [
+                    { field: 'description', header: 'Description' },
+                    { field: 'quantity', header: 'Quantity' },
+                    { field: 'unitPrice', header: 'Unit price' },
+                    { field: 'amount', header: 'Amount' },
+                ],
+                [
+                    { description: 'Bamboo Watch', quantity: 12, unitPrice: '$65.00', amount: '$780.00' },
+                    { description: 'Blue Band', quantity: 4, unitPrice: '$79.00', amount: '$316.00' },
+                    { description: 'Expedited shipping', quantity: 1, unitPrice: '$144.00', amount: '$144.00' },
+                ],
+            ),
+            card('invoice-total', [text('invoice-subtotal', 'Subtotal: $1,240.00'), text('invoice-vat', 'VAT (23%): $285.20'), text('invoice-due', 'Total due: $1,525.20')]),
+        ],
+        [TemplateSlotName.Actions]: [formActions('invoice-actions', 'Mark as paid', 'Send reminder')],
+    },
+    displayName: 'Invoice',
+    description: 'A printable document: parties, line items and totals.',
+};
+
+/** Help: the answers, and a way to ask when they are not there. */
+export const helpTemplate: ScreenTemplate = {
+    name: 'Help',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Body }, { name: TemplateSlotName.SidePanel }],
+    content: {
+        [TemplateSlotName.Header]: [pageHeader('help-header', 'Help', 'Search the answers, or ask us directly')],
+        [TemplateSlotName.Body]: [
+            externalComponent('help-search', 'inputText', { placeholder: 'Search help' }),
+            widget('help-popular', 'Popular answers', [
+                text('help-1', 'How do I invite someone to the workspace?'),
+                text('help-2', 'Why can I not see the sidebar on my phone?'),
+                text('help-3', 'How do I change the theme?'),
+            ]),
+        ],
+        [TemplateSlotName.SidePanel]: [
+            widget('help-contact', 'Still stuck?', [text('help-contact-text', 'We answer within one working day.'), button('help-contact-button', 'Contact support', { severity: 'primary' })]),
+        ],
+    },
+    displayName: 'Help',
+    description: 'Searchable answers with a route to a human.',
+};
+
+/** The five support templates. */
+export const supportTemplates: ScreenTemplate[] = [documentationTemplate, profileSettingsTemplate, userManagementTemplate, invoiceTemplate, helpTemplate];

package/gallery/widgets.ts

@@ -0,0 +1,63 @@
+// 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 { ComponentName } from '../ComponentName';
+import { button, card, externalComponent, panel, text } from './elements';
+
+/**
+ * The repeated pieces the gallery's screen templates are built from.
+ *
+ * The gallery only earns its place if a preview shows something that looks like an application - a
+ * dashboard with four stat cards over two columns of larger widgets, a list with real columns and real
+ * rows. Seeded content that says "Lorem ipsum" proves the renderer runs and nothing else. These builders
+ * are what keep twenty templates' worth of realistic content from becoming twenty pages of literals.
+ */
+
+/** A screen's title, subtitle and actions - the furniture every template starts with. */
+export function pageHeader(id: string, title: string, subtitle: string, actions: SceneElement[] = []): SceneElement {
+    return externalComponent(id, ComponentName.PageHeader, { title, subtitle }, { actions });
+}
+
+/**
+ * One of the four figures across the top of a dashboard - the composition Sakai's dashboard opens with,
+ * and the one every template in the line has copied since.
+ */
+export function statCard(id: string, label: string, value: string, delta: string, icon: string): SceneElement {
+    return card(id, [text(`${id}-label`, label), text(`${id}-value`, value), text(`${id}-delta`, delta)], { icon, variant: 'stat' });
+}
+
+/** A titled surface holding a widget's content. */
+export function widget(id: string, title: string, content: SceneElement[]): SceneElement {
+    return card(id, [text(`${id}-title`, title), ...content], { title });
+}
+
+/** A table with real columns and real rows, so a list template looks like a list. */
+export function table(id: string, columns: { field: string; header: string }[], rows: Record<string, unknown>[]): SceneElement {
+    return externalComponent(
+        id,
+        'dataTable',
+        { value: rows, dataKey: columns[0]?.field ?? 'id', paginator: rows.length > 8, rows: 8 },
+        { columns: columns.map(column => externalComponent(`${id}-${column.field}`, 'column', { field: column.field, header: column.header, sortable: true })) },
+    );
+}
+
+/** One labeled input in a form template. */
+export function field(id: string, label: string, componentName: string, properties: Record<string, unknown> = {}): SceneElement {
+    return panel(id, [text(`${id}-label`, label), externalComponent(`${id}-input`, componentName, properties)]);
+}
+
+/** A row of buttons closing a form. */
+export function formActions(id: string, confirmLabel: string, cancelLabel = 'Cancel'): SceneElement {
+    return panel(id, [button(`${id}-confirm`, confirmLabel, { severity: 'primary' }), button(`${id}-cancel`, cancelLabel, { severity: 'secondary' })]);
+}
+
+/** The empty state a list shows before anything exists - the designed one, never a build-time apology. */
+export function emptyState(id: string, title: string, message: string, actionLabel: string): SceneElement {
+    return card(id, [
+        externalComponent(`${id}-icon`, 'image', { alt: title }),
+        text(`${id}-title`, title),
+        text(`${id}-message`, message),
+        button(`${id}-action`, actionLabel, { severity: 'primary' }),
+    ]);
+}