@cratis/scene.blueprint.default 4.39.0 → 4.41.0

package/foundation/templates/dashboardScreenTemplate.ts

@@ -0,0 +1,37 @@
+// 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 { column, grid, row, slotLeaf } from '../../layouts/flowBuilders';
+import { component, foundationTemplateProvenance, fromQuery, thumbnailOf } from './templateParts';
+
+/**
+ * The dashboard: key figures across the top, charts and tables below, an aside for what needs attention. Every region is its own component with its
+ * own five states, so one failed query shows the other regions - the page never fails as a whole.
+ */
+export const dashboardScreenTemplate: ScreenTemplate = {
+    name: 'DashboardScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'header' }, { name: 'kpis' }, { name: 'charts' }, { name: 'tables' }, { name: 'aside' }],
+    arrangement: {
+        root: column([slotLeaf('header'), slotLeaf('kpis'), grid([slotLeaf('charts', { span: 2 }), slotLeaf('aside')], 3, 16), slotLeaf('tables')], 16),
+        overrides: [{ width: WidthSizeClass.Compact, root: column([slotLeaf('header'), slotLeaf('kpis'), slotLeaf('charts'), slotLeaf('tables'), slotLeaf('aside')], 16) }],
+    },
+    content: {
+        header: [component('dashboard-header', 'pageHeader', { title: 'Sales overview', subtitle: 'This quarter compared to last' })],
+        kpis: [
+            component('kpi-pipeline', 'statCard', { label: 'Open pipeline', value: fromQuery('Kpis', '0.value'), change: fromQuery('Kpis', '0.change'), format: 'currency', currency: 'USD', comparison: 'last quarter' }),
+            component('kpi-won', 'statCard', { label: 'Deals won', value: fromQuery('Kpis', '1.value'), change: fromQuery('Kpis', '1.change'), comparison: 'last quarter' }),
+            component('kpi-response', 'statCard', { label: 'Response time (hours)', value: fromQuery('Kpis', '2.value'), change: fromQuery('Kpis', '2.change'), goodDirection: 'down', comparison: 'last quarter' }),
+        ],
+        charts: [
+            component('chart-revenue', 'chartWrapper', { title: 'Revenue by quarter', kind: 'line', categories: fromQuery('RevenueChart', '0.categories'), series: fromQuery('RevenueChart', '0.series') }),
+            component('chart-stages', 'chartWrapper', { title: 'Deals by stage', kind: 'funnel', categories: fromQuery('StageChart', '0.categories'), series: fromQuery('StageChart', '0.series') }),
+        ],
+        tables: [component('dashboard-deals', 'dataList', { label: 'Closing soon', rows: fromQuery('Deals'), columns: fromQuery('DealColumns'), titleField: 'name', pageSize: 5 })],
+        aside: [component('dashboard-activity', 'activityFeed', { label: 'Recent activity', entries: fromQuery('Activity') })],
+    },
+    displayName: 'Dashboard',
+    description: 'Key figures, charts and tables, each region with its own loading, empty and error states.',
+    metadata: { ...foundationTemplateProvenance, type: 'Dashboard', category: 'Foundation / Dashboard', thumbnail: thumbnailOf('DashboardScreen') },
+};

package/foundation/templates/formScreenTemplate.ts

@@ -0,0 +1,28 @@
+// 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 { column, grid, row, slotLeaf } from '../../layouts/flowBuilders';
+import { component, foundationTemplateProvenance, fromQuery, thumbnailOf } from './templateParts';
+
+/**
+ * The form: titled sections of fields in a one-to-three column grid, validated, with Save, Save and new and Cancel. One template serves create, edit, read-only
+ * and settings (a save for each section) by its mode, and warns before unsaved changes are lost.
+ */
+export const formScreenTemplate: ScreenTemplate = {
+    name: 'FormScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'header' }, { name: 'body' }, { name: 'actions' }],
+    arrangement: {
+        root: column([slotLeaf('header'), slotLeaf('body'), slotLeaf('actions')], 16),
+        overrides: [{ width: WidthSizeClass.Compact, root: column([slotLeaf('header'), slotLeaf('body'), slotLeaf('actions')], 16) }],
+    },
+    content: {
+        header: [component('form-header', 'pageHeader', { title: 'New account', subtitle: 'Fields marked * are required' })],
+        body: [component('form-body', 'formScreenBody', { mode: 'create', sections: fromQuery('RecordSections'), values: fromQuery('RecordValues', '0'), errors: fromQuery('FormErrors', '0') })],
+        actions: [],
+    },
+    displayName: 'Form',
+    description: 'Sections of validated fields with Save, Save and new, Cancel and an unsaved-changes guard.',
+    metadata: { ...foundationTemplateProvenance, type: 'Form', category: 'Foundation / Form', thumbnail: thumbnailOf('FormScreen') },
+};

package/foundation/templates/index.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { boardScreenTemplate } from './boardScreenTemplate';
+import { dashboardScreenTemplate } from './dashboardScreenTemplate';
+import { formScreenTemplate } from './formScreenTemplate';
+import { listScreenTemplate } from './listScreenTemplate';
+import { masterDetailScreenTemplate } from './masterDetailScreenTemplate';
+import { recordPageTemplate } from './recordPageTemplate';
+import { wizardScreenTemplate } from './wizardScreenTemplate';
+import { workspaceScreenTemplate } from './workspaceScreenTemplate';
+
+export * from './templateParts';
+export * from './boardScreenTemplate';
+export * from './dashboardScreenTemplate';
+export * from './formScreenTemplate';
+export * from './listScreenTemplate';
+export * from './masterDetailScreenTemplate';
+export * from './recordPageTemplate';
+export * from './wizardScreenTemplate';
+export * from './workspaceScreenTemplate';
+
+/** The foundation screen templates, in the order the manifest lists them. The workspace comes first: it is the container the master/detail nests in. */
+export const foundationScreenTemplates = [
+    workspaceScreenTemplate, dashboardScreenTemplate, listScreenTemplate, boardScreenTemplate, masterDetailScreenTemplate, recordPageTemplate, formScreenTemplate, wizardScreenTemplate,
+];

package/foundation/templates/listScreenTemplate.ts

@@ -0,0 +1,37 @@
+// 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 { column, grid, row, slotLeaf } from '../../layouts/flowBuilders';
+import { component, foundationTemplateProvenance, fromQuery, thumbnailOf } from './templateParts';
+
+/**
+ * The collection screen: search, filters, a list that is a table, grouped, or cards, a bar that appears when rows are selected, and a footer for paging.
+ * Search, sort, page and selection live in the address, so a link shares the list as it is. On a phone the table becomes cards.
+ */
+export const listScreenTemplate: ScreenTemplate = {
+    name: 'ListScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'header' }, { name: 'toolbar' }, { name: 'filters' }, { name: 'list' }, { name: 'bulkBar' }, { name: 'footer' }],
+    arrangement: {
+        root: column([slotLeaf('header'), row([slotLeaf('toolbar')], 8), slotLeaf('filters'), slotLeaf('bulkBar'), slotLeaf('list'), slotLeaf('footer')], 12),
+        overrides: [{ width: WidthSizeClass.Compact, root: column([slotLeaf('header'), slotLeaf('toolbar'), slotLeaf('filters'), slotLeaf('bulkBar'), slotLeaf('list'), slotLeaf('footer')], 16) }],
+    },
+    content: {
+        header: [component('list-header', 'pageHeader', { title: 'Deals', subtitle: 'Every open and closed deal' })],
+        toolbar: [
+            component('list-search', 'globalSearch', { placeholder: 'Search deals', label: 'Search deals', urlKey: 'dealsq' }),
+            component('list-views', 'savedViewsMenu', { views: fromQuery('DealViews'), savePermission: 'enabled', managePermission: 'enabled' }),
+            component('list-columns', 'columnChooser', { columns: fromQuery('DealColumnChoices') }),
+        ],
+        filters: [component('list-filter', 'filterBuilder', { fields: fromQuery('DealFilterFields') })],
+        list: [component('list-records', 'dataList', {
+            label: 'Deals', rows: fromQuery('Deals'), columns: fromQuery('DealColumns'), titleField: 'name', selectionMode: 'multiple', pageSize: 10, rowActions: ['Open', 'Archive'], urlKey: 'deals',
+        })],
+        bulkBar: [component('list-bulk', 'bulkBar', { selection: fromQuery('DealSelection'), actions: ['Assign', 'Archive'] })],
+        footer: [],
+    },
+    displayName: 'List',
+    description: 'A searchable, filterable collection that is a table, grouped or cards, with a bulk bar for selected rows.',
+    metadata: { ...foundationTemplateProvenance, type: 'List', category: 'Foundation / List', thumbnail: thumbnailOf('ListScreen') },
+};

package/foundation/templates/masterDetailScreenTemplate.ts

@@ -0,0 +1,28 @@
+// 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 { column, grid, row, slotLeaf } from '../../layouts/flowBuilders';
+import { component, foundationTemplateProvenance, fromQuery, thumbnailOf } from './templateParts';
+
+/**
+ * The master/detail: a list beside the selected record. The selection lives in the address, so a link opens a record and the back button returns to the
+ * list; on a phone the two become a navigation stack - the list, then the record with a way back. It lives in a module workspace's `moduleContent`.
+ */
+export const masterDetailScreenTemplate: ScreenTemplate = {
+    name: 'MasterDetailScreen',
+    fitsSlot: 'WorkspaceScreen.moduleContent',
+    slots: [{ name: 'list' }, { name: 'details' }],
+    arrangement: {
+        root: grid([slotLeaf('list'), slotLeaf('details', { span: 2 })], 3, 16),
+        overrides: [{ width: WidthSizeClass.Compact, root: column([slotLeaf('list'), slotLeaf('details')], 16) }],
+    },
+    content: {
+        list: [component('md-list', 'dataList', { label: 'Accounts', rows: fromQuery('Deals'), columns: fromQuery('DealColumns'), titleField: 'name', selectionMode: 'single', urlKey: 'md' })],
+        details: [component('md-detail', 'tabSet', { tabs: fromQuery('RecordTabs'), urlKey: 'mdtab', label: 'Account' })],
+    },
+    displayName: 'Master/detail with address selection',
+    description: 'A list beside the selected record that stacks into a navigation stack on a phone.',
+    outlets: [{ name: 'master-detail.detail', description: 'The selected record.', accepts: ['Detail'] }],
+    metadata: { ...foundationTemplateProvenance, type: 'Workspace', category: 'Foundation / Workspace', thumbnail: thumbnailOf('MasterDetailScreen') },
+};

package/foundation/templates/recordPageTemplate.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.
+
+import { ScreenTemplate, WidthSizeClass } from '@cratis/scene.model';
+import { column, grid, row, slotLeaf } from '../../layouts/flowBuilders';
+import { component, foundationTemplateProvenance, fromQuery, thumbnailOf } from './templateParts';
+
+/**
+ * The record page: a header, the key facts, then tabs (overview, related, files, history) with the record's main content, its related records and its
+ * activity, and an aside. The tabs are configurable by changing one property.
+ */
+export const recordPageTemplate: ScreenTemplate = {
+    name: 'RecordPage',
+    fitsSlot: 'content',
+    slots: [{ name: 'header' }, { name: 'summary' }, { name: 'tabs' }, { name: 'main' }, { name: 'related' }, { name: 'activity' }, { name: 'aside' }],
+    arrangement: {
+        root: column([slotLeaf('header'), slotLeaf('summary'), grid([column([slotLeaf('tabs'), slotLeaf('main'), slotLeaf('related'), slotLeaf('activity')], 16, { span: 2 }), slotLeaf('aside')], 3, 16)], 16),
+        overrides: [{ width: WidthSizeClass.Compact, root: column([slotLeaf('header'), slotLeaf('summary'), slotLeaf('tabs'), slotLeaf('main'), slotLeaf('related'), slotLeaf('activity'), slotLeaf('aside')], 16) }],
+    },
+    content: {
+        header: [component('record-header', 'pageHeader', { title: fromQuery('RecordValues', '0.name'), subtitle: 'Account' })],
+        summary: [
+            component('record-value', 'statCard', { label: 'Lifetime value', value: fromQuery('Kpis', '0.value'), format: 'currency', currency: 'USD' }),
+            component('record-status', 'statusChip', { status: fromQuery('Deals', '0.status'), tone: 'info' }),
+            component('record-people', 'avatarStack', { people: fromQuery('People') }),
+        ],
+        tabs: [component('record-tabs', 'tabSet', { tabs: fromQuery('RecordTabs'), urlKey: 'tab', label: 'Record sections' })],
+        main: [component('record-form', 'formScreenBody', { mode: 'readOnly', sections: fromQuery('RecordSections'), values: fromQuery('RecordValues', '0') })],
+        related: [component('record-related', 'dataList', { label: 'Related deals', rows: fromQuery('Deals'), columns: fromQuery('DealColumns'), titleField: 'name', pageSize: 5 })],
+        activity: [component('record-activity', 'activityFeed', { label: 'History', entries: fromQuery('Activity') })],
+        aside: [component('record-checklist', 'checklistSection', { sections: fromQuery('Checklist') })],
+    },
+    displayName: 'Record page',
+    description: 'One record: its key facts, tabbed sections, related records and history.',
+    metadata: { ...foundationTemplateProvenance, type: 'Detail', category: 'Foundation / Detail', thumbnail: thumbnailOf('RecordPage') },
+};

package/foundation/templates/templateParts.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingExpression, BindingSourceKind, ExternalComponent, SceneElement, TemplateMetadata } from '@cratis/scene.model';
+import { externalComponent } from '../../gallery/elements';
+import { defaultBlueprintTemplateProvenance } from '../../templateProvenance';
+
+/**
+ * The provenance every foundation template carries. The foundation components draw themselves with no component library, so unlike the earlier
+ * gallery templates these require no PrimeReact or Cratis.Components: a host with only this blueprint renders them.
+ */
+export const foundationTemplateProvenance: Pick<TemplateMetadata, 'compatibility' | 'attribution' | 'license' | 'licenseUrl'> = {
+    compatibility: { scene: defaultBlueprintTemplateProvenance.compatibility!.scene },
+    attribution: { author: 'Cratis', url: 'https://github.com/Cratis/Scene/tree/main/Source/JavaScript/blueprint.default' },
+    license: 'MIT',
+    licenseUrl: 'https://github.com/Cratis/Scene/blob/main/LICENSE',
+};
+
+/** The package-relative thumbnail path of a foundation template. */
+export const thumbnailOf = (templateName: string): string => `thumbnails/${templateName}.svg`;
+
+/**
+ * A property taken from a query result - never a value. A template declares *where* its data comes from and the sample-data pack, or the real
+ * query, supplies the rows (spec SD1); `path` reaches into the result (`0.value` is the first row's `value`, an empty path is the whole result).
+ */
+export const fromQuery = (query: string, path = ''): BindingExpression => ({ kind: BindingSourceKind.QueryResult, query, path });
+
+/** A component of this blueprint, by its bare name, with its properties and slot content. */
+export const component = (id: string, componentName: string, properties: Record<string, unknown> = {}, slots: Record<string, SceneElement[]> = {}): ExternalComponent =>
+    externalComponent(id, componentName, properties, slots);

package/foundation/templates/wizardScreenTemplate.ts

@@ -0,0 +1,33 @@
+// 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 { column, grid, row, slotLeaf } from '../../layouts/flowBuilders';
+import { component, foundationTemplateProvenance, fromQuery, thumbnailOf } from './templateParts';
+
+/**
+ * The wizard: linear steps with a progress list, Back and Next, and a save-draft. The last step is the review. Where the person has got to survives a refresh,
+ * and a refresh can never land past a step that was not done. The content of each step is the slot named by its id.
+ */
+export const wizardScreenTemplate: ScreenTemplate = {
+    name: 'WizardScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'header' }, { name: 'progress' }, { name: 'step' }, { name: 'actions' }],
+    arrangement: {
+        root: column([slotLeaf('header'), slotLeaf('progress'), slotLeaf('step'), slotLeaf('actions')], 16),
+        overrides: [{ width: WidthSizeClass.Compact, root: column([slotLeaf('header'), slotLeaf('progress'), slotLeaf('step'), slotLeaf('actions')], 16) }],
+    },
+    content: {
+        header: [component('wizard-header', 'pageHeader', { title: 'New account', subtitle: 'Three short steps' })],
+        progress: [component('wizard-progress', 'wizardProgress', { steps: fromQuery('WizardSteps'), urlKey: 'step' }, {
+            details: [component('wizard-details', 'formScreenBody', { mode: 'create', sections: fromQuery('RecordSections'), values: fromQuery('RecordValues', '0') })],
+            people: [component('wizard-people', 'avatarStack', { people: fromQuery('People') })],
+            review: [component('wizard-review', 'formScreenBody', { mode: 'readOnly', sections: fromQuery('RecordSections'), values: fromQuery('RecordValues', '0') })],
+        })],
+        step: [],
+        actions: [],
+    },
+    displayName: 'Wizard',
+    description: 'Linear steps with progress, back and next, a saved draft and a review step.',
+    metadata: { ...foundationTemplateProvenance, type: 'Wizard', category: 'Foundation / Wizard', thumbnail: thumbnailOf('WizardScreen') },
+};

package/foundation/templates/workspaceScreenTemplate.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.
+
+import { ScreenTemplate, WidthSizeClass } from '@cratis/scene.model';
+import { column, grid, row, slotLeaf } from '../../layouts/flowBuilders';
+import { component, foundationTemplateProvenance, fromQuery, thumbnailOf } from './templateParts';
+
+/**
+ * A module's own workspace: its sections beside the content of the section in force. The sections are the module's sub-navigation (a left rail that
+ * becomes tabs on a phone); the section in force is kept in the address, so a deep link or a refresh restores it. Feature screens go in `moduleContent`.
+ */
+export const workspaceScreenTemplate: ScreenTemplate = {
+    name: 'WorkspaceScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'moduleNav' }, { name: 'moduleContent' }],
+    arrangement: {
+        root: grid([slotLeaf('moduleNav'), slotLeaf('moduleContent', { span: 3 })], 4, 16),
+        overrides: [{ width: WidthSizeClass.Compact, root: column([slotLeaf('moduleNav'), slotLeaf('moduleContent')], 16) }],
+    },
+    content: {
+        moduleNav: [component('workspace-sections', 'subNavigation', { items: fromQuery('ModuleSections'), orientation: 'vertical', urlKey: 'section', label: 'Module sections' })],
+        moduleContent: [],
+    },
+    displayName: 'Module workspace',
+    description: 'A module\'s sections beside the content of the section that is open.',
+    metadata: { ...foundationTemplateProvenance, type: 'Workspace', category: 'Foundation / Workspace', thumbnail: thumbnailOf('WorkspaceScreen') },
+};

package/foundation/urlState.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useCallback, useEffect, useState } from 'react';
+
+/** Reads one query-string parameter of the current address, or undefined when it is absent or there is no address (server rendering). */
+export function readUrlParameter(name: string): string | undefined {
+    if (typeof window === 'undefined') return undefined;
+    const value = new URLSearchParams(window.location.search).get(name);
+    return value === null ? undefined : value;
+}
+
+/** Writes one query-string parameter to the address without adding a history entry; an undefined or empty value removes it. */
+export function writeUrlParameter(name: string, value: string | undefined): void {
+    if (typeof window === 'undefined') return;
+    const parameters = new URLSearchParams(window.location.search);
+    if (value === undefined || value === '') parameters.delete(name);
+    else parameters.set(name, value);
+
+    const query = parameters.toString();
+    window.history.replaceState(window.history.state, '', `${window.location.pathname}${query.length > 0 ? `?${query}` : ''}${window.location.hash}`);
+}
+
+/**
+ * State that lives in the address bar: a list's search, sort, page and filters, a master/detail's selection, a module's active section.
+ *
+ * It starts from the address when the address has a value (so a shared link, a refresh and the back button restore the screen as it was),
+ * otherwise from the fallback the template supplies. Changing it rewrites the address in place and does not add a history entry per keystroke.
+ * Several components on one screen use distinct `key`s; a template names them (`q`, `sort`, `page`, `selected`, `section`). Without a
+ * `urlKey` the state is plain component state, which is what a gallery card and a design surface want.
+ *
+ * @param key The query-string parameter, or undefined to keep the state local.
+ * @param fallback The value used when the address has none.
+ * @returns The value and its setter.
+ */
+export function useUrlState(key: string | undefined, fallback: string | undefined): [string | undefined, (value: string | undefined) => void] {
+    const [value, setValue] = useState<string | undefined>(() => (key === undefined ? fallback : readUrlParameter(key) ?? fallback));
+
+    useEffect(() => {
+        if (key === undefined) return;
+        const restore = () => setValue(readUrlParameter(key) ?? fallback);
+        window.addEventListener('popstate', restore);
+        return () => window.removeEventListener('popstate', restore);
+    }, [key, fallback]);
+
+    const update = useCallback((next: string | undefined) => {
+        setValue(next);
+        if (key !== undefined) writeUrlParameter(key, next);
+    }, [key]);
+
+    return [value, update];
+}

package/foundation/useCompactWidth.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useState } from 'react';
+
+/** The width below which a screen is a phone's: the collapse rules of Part B 1.3 (list to cards, master-detail to stack) apply under it. */
+export const compactQuery = '(max-width: 40rem)';
+
+/** Whether the viewport is phone-wide, kept up to date. Without `matchMedia` (a test environment, server rendering) it is false, so the full layout renders. */
+export function useCompactWidth(): boolean {
+    const [compact, setCompact] = useState(() => typeof window !== 'undefined' && typeof window.matchMedia === 'function' && window.matchMedia(compactQuery).matches);
+
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+        const query = window.matchMedia(compactQuery);
+        const update = () => setCompact(query.matches);
+        update();
+        query.addEventListener('change', update);
+        return () => query.removeEventListener('change', update);
+    }, []);
+
+    return compact;
+}

package/foundation/wizardModel.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** One step of a wizard. */
+export interface WizardStep {
+    id: string;
+    label: string;
+    /** Whether the step's own fields are valid; a step that is not valid blocks Next. Defaults to true. */
+    valid: boolean;
+}
+
+/** Where a step stands for the person going through the wizard. */
+export enum StepStatus {
+    Completed = 'completed',
+    Current = 'current',
+    Upcoming = 'upcoming',
+}
+
+/** Reads steps, dropping those without an id and repeated ids. */
+export function readWizardSteps(value: unknown): WizardStep[] {
+    if (!Array.isArray(value)) return [];
+
+    const seen = new Set<string>();
+    return value.flatMap((entry): WizardStep[] => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return [];
+        const { id, label, valid } = entry as Record<string, unknown>;
+        if (typeof id !== 'string' || id.length === 0 || seen.has(id)) return [];
+        seen.add(id);
+        return [{ id, label: typeof label === 'string' && label.length > 0 ? label : id, valid: valid !== false }];
+    });
+}
+
+/** The step to show: the requested one when it exists and every step before it is completed, else the furthest step that is reachable. A refresh can never land past a step that was not done. */
+export function reachableStep(steps: WizardStep[], completed: ReadonlySet<string>, requested: string | undefined): string | undefined {
+    const wanted = steps.findIndex(step => step.id === requested);
+    let furthest = 0;
+    while (furthest < steps.length - 1 && completed.has(steps[furthest].id)) furthest++;
+    return steps[wanted >= 0 && wanted <= furthest ? wanted : furthest]?.id;
+}
+
+/** The status of a step: the current one, a completed one (revisitable), or upcoming. */
+export function statusOf(completed: ReadonlySet<string>, current: string | undefined, id: string): StepStatus {
+    if (id === current) return StepStatus.Current;
+    return completed.has(id) ? StepStatus.Completed : StepStatus.Upcoming;
+}
+
+/** Whether a step may be opened from the progress indicator: a completed one, the current one, or the next one when the current is done. */
+export function canOpen(steps: WizardStep[], completed: ReadonlySet<string>, id: string): boolean {
+    const index = steps.findIndex(step => step.id === id);
+    return index === 0 || steps.slice(0, index).every(step => completed.has(step.id));
+}
+
+/** The step before or after another, or undefined at either end. */
+export const neighbour = (steps: WizardStep[], id: string | undefined, direction: -1 | 1): WizardStep | undefined => steps[steps.findIndex(step => step.id === id) + direction];

package/gallery/GalleryScreenPreview.tsx

@@ -2,10 +2,13 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { useMemo } from 'react';
-import { Theme } from '@cratis/scene.model';
+import { ExternalComponent, SampleDataPack, SceneElement, Theme } from '@cratis/scene.model';
 import { ComponentRegistry, SceneElementView, coreComponents } from '@cratis/scene.react';
 import { LayoutConfigProvider, LayoutConfigState } from '../configuration';
+import { ComponentName } from '../ComponentName';
 import { defaultBlueprintComponents } from '../defaultBlueprintComponents';
+import { ComponentState, foundationSamples } from '../foundation';
+import { defaultBlueprintName } from '../packageName';
 import { LayoutThemeProvider, defaultBlueprintThemes } from '../themes';
 import { composeScreenElement } from './composeScreen';
 import { galleryComponentCatalog, galleryPreviewProfile } from './previewProfile';
@@ -38,8 +41,63 @@ export interface GalleryScreenPreviewProps {
 
     /** The data state to show. Defaults to the seeded, populated records. */
     state?: TemplatePreviewState;
+
+    /**
+     * The sample-data pack that stands in for the queries the templates bind to: each set's `shape` is a query name and its `rows` that query's result.
+     * Templates carry no rows of their own - they declare where the data comes from (spec SD1) - so a preview of a foundation template needs one.
+     */
+    pack?: SampleDataPack;
+
+    /**
+     * A standard state (spec Part B 1.4) to force on every foundation component that owns the five states: loading, error, no-permission or partial.
+     * This is how a designer inspects each one on a real template - it only sets the `state` property the components already read, so there is no
+     * second code path. `error`, `permissionSubject` and `failedRegions` give the state its message.
+     */
+    forceState?: ForcedComponentState;
+}
+
+/** The standard states a preview can force on a template's components. */
+export interface ForcedComponentState {
+    state: ComponentState;
+    error?: string;
+    permissionSubject?: string;
+    failedRegions?: string[];
+}
+
+/** Components that are chrome or controls rather than data-showing regions, and so do not own the five states. */
+const withoutStates = new Set<string>([
+    ComponentName.EmptyState, ComponentName.TrendChip, ComponentName.StatusChip, ComponentName.BulkBar, ComponentName.GlobalSearch, ComponentName.NotificationsButton,
+]);
+
+/** Sets the forced state on every region that owns the five states, leaving chrome and controls as they are. */
+export function forceComponentState(element: SceneElement, forced: ForcedComponentState): SceneElement {
+    const external = element as Partial<ExternalComponent>;
+    const children = (element as { children?: SceneElement[] }).children;
+    const slots = external.slots ? Object.fromEntries(Object.entries(external.slots).map(([slot, inner]) => [slot, inner.map(child => forceComponentState(child, forced))])) : undefined;
+    const bare = typeof external.componentName === 'string' ? external.componentName.substring(external.componentName.lastIndexOf(':') + 1) : undefined;
+    const owns = bare !== undefined && external.componentName!.includes(defaultBlueprintName) && (bare in foundationSamples) && foundationSamples[bare].stateful && !withoutStates.has(bare);
+
+    return {
+        ...element,
+        ...(owns ? { properties: { ...external.properties, ...forced } } : {}),
+        ...(slots ? { slots } : {}),
+        ...(children ? { children: children.map(child => forceComponentState(child, forced)) } : {}),
+    } as SceneElement;
 }
 
+/**
+ * A pack as the query results the templates bind to: one entry for each set, keyed by the set's shape name.
+ *
+ * The state is a property of the *data*, not of the template: Empty answers every query with no rows; Loading and Error withhold the answer, which is
+ * what a query that has not come back or has failed looks like to a component, so each shows its own skeleton or error exactly as it will in an application.
+ * The elements themselves are untouched, which is why the same template previews in every state with no per-template code.
+ */
+export const queryResultsOf = (pack: SampleDataPack | undefined, state: TemplatePreviewState = TemplatePreviewState.Populated): Record<string, unknown> | undefined => {
+    if (pack === undefined) return undefined;
+    if (state === TemplatePreviewState.Empty) return Object.fromEntries(pack.sets.map(set => [set.shape, []]));
+    return Object.fromEntries(pack.sets.map(set => [set.shape, set.rows]));
+};
+
 /**
  * Boots one gallery screen through the real engine.
  *
@@ -53,20 +111,21 @@ export interface GalleryScreenPreviewProps {
  * a preview of a blueprint against half a profile should look visibly incomplete rather than quietly
  * wrong.
  */
-export function GalleryScreenPreview({ screenName, initialConfig, themes = defaultBlueprintThemes, registry = galleryPreviewRegistry, state = TemplatePreviewState.Populated }: GalleryScreenPreviewProps) {
+export function GalleryScreenPreview({ screenName, initialConfig, themes = defaultBlueprintThemes, registry = galleryPreviewRegistry, state = TemplatePreviewState.Populated, pack, forceState }: GalleryScreenPreviewProps) {
     const element = useMemo(() => {
         const screen = galleryScreen(screenName);
         if (!screen) {
             throw new Error(`The gallery has no screen named '${screenName}'.`);
         }
 
-        return applyTemplatePreviewState(resolveElementComponentNames(composeScreenElement(screen), galleryPreviewProfile, galleryComponentCatalog), state);
-    }, [screenName, state]);
+        const resolved = applyTemplatePreviewState(resolveElementComponentNames(composeScreenElement(screen), galleryPreviewProfile, galleryComponentCatalog), state);
+        return forceState ? forceComponentState(resolved, forceState) : resolved;
+    }, [screenName, state, forceState]);
 
     return (
         <LayoutConfigProvider initialConfig={initialConfig} storage={null}>
             <LayoutThemeProvider themes={themes}>
-                <SceneElementView element={element} registry={registry} resolveBinding={() => undefined} />
+                <SceneElementView element={element} registry={registry} resolveBinding={() => undefined} queryResults={queryResultsOf(pack, state)} />
             </LayoutThemeProvider>
         </LayoutConfigProvider>
     );

package/gallery/applicationChrome.ts

@@ -1,7 +1,7 @@
 // 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 { BindingSourceKind, SceneElement } from '@cratis/scene.model';
 import { ComponentName } from '../ComponentName';
 import { SlotName } from '../layouts';
 import { defaultBlueprintThemes } from '../themes';
@@ -71,6 +71,11 @@ export function applicationChrome(activeScreen: string, breadcrumb: BreadcrumbEn
                 {
                     logo: [logo('topbar-logo')],
                     end: [
+                        // The topbar of Part B 2.1: logo, search, notifications, the environment, and the user. The search and the bell are the foundation
+                        // components, so they work everywhere the shell does; the unread count is a query result, never a value.
+                        externalComponent('topbar-search', ComponentName.GlobalSearch, { placeholder: 'Search', label: 'Search the application' }),
+                        externalComponent('topbar-notifications', ComponentName.NotificationsButton, { count: { kind: BindingSourceKind.QueryResult, query: 'NotificationCount', path: '0.count' } }),
+                        externalComponent('topbar-environment', ComponentName.StatusChip, { status: 'Production', tone: 'info' }),
                         externalComponent('topbar-user', ComponentName.UserMenu, {
                             name: 'Amelia Nyquist',
                             role: 'Owner',

package/gallery/composeScreen.ts

@@ -64,12 +64,14 @@ function placeInside(outer: ScreenTemplate, inner: ScreenTemplate): ScreenTempla
         return outer;
     }
 
-    const innerContent = inner.slots.flatMap(slot => inner.content?.[slot.name] ?? []);
+    // A container-qualified name (`WorkspaceScreen.moduleContent`) says which container; the slot's own name is what the container's content is keyed by.
+    const slot = inner.fitsSlot.substring(inner.fitsSlot.lastIndexOf('.') + 1);
+    const innerContent = inner.slots.flatMap(innerSlot => inner.content?.[innerSlot.name] ?? []);
     return {
         ...outer,
         content: {
             ...outer.content,
-            [inner.fitsSlot]: [...(outer.content?.[inner.fitsSlot] ?? []), ...innerContent],
+            [slot]: [...(outer.content?.[slot] ?? []), ...innerContent],
         },
     };
 }

package/gallery/screens.ts

@@ -2,6 +2,7 @@
 // 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 { foundationScreenTemplates } from '../foundation/templates';
 import { LayoutName, appShellLayout, fullPageLayout } from '../layouts';
 import { BreadcrumbEntry, applicationChrome, fullPageChrome } from './applicationChrome';
 import { nestScreenTemplates, templateContentInLayout } from './composeScreen';
@@ -20,6 +21,7 @@ import { workspaceTemplates } from './workspaceTemplates';
  * and what the bundle provides; `validatePackageBundle` proves the two agree.
  */
 export const galleryScreenTemplates: ScreenTemplate[] = [
+    ...foundationScreenTemplates,
     ...workspaceTemplates,
     ...supportTemplates,
     ...authTemplates,
@@ -43,6 +45,14 @@ const breadcrumbs: Record<string, BreadcrumbEntry[]> = {
     UserManagement: [{ label: 'Administration', targetScreen: 'Dashboard' }, { label: 'Users' }],
     Invoice: [{ label: 'Billing', targetScreen: 'Dashboard' }, { label: 'INV-2043' }],
     Help: [{ label: 'Support', targetScreen: 'Dashboard' }, { label: 'Help' }],
+    DashboardScreen: [{ label: 'Dashboard' }],
+    ListScreen: [{ label: 'Sales', targetScreen: 'DashboardScreen' }, { label: 'Deals' }],
+    BoardScreen: [{ label: 'Sales', targetScreen: 'DashboardScreen' }, { label: 'Pipeline' }],
+    WorkspaceScreen: [{ label: 'Sales' }],
+    MasterDetailScreen: [{ label: 'Sales', targetScreen: 'WorkspaceScreen' }, { label: 'Accounts' }],
+    RecordPage: [{ label: 'Sales', targetScreen: 'DashboardScreen' }, { label: 'Accounts', targetScreen: 'ListScreen' }, { label: 'Account' }],
+    FormScreen: [{ label: 'Sales', targetScreen: 'DashboardScreen' }, { label: 'Accounts', targetScreen: 'ListScreen' }, { label: 'New account' }],
+    WizardScreen: [{ label: 'Sales', targetScreen: 'DashboardScreen' }, { label: 'New account' }],
     ModuleWorkspace: [{ label: 'Operations' }],
     FeatureSection: [{ label: 'Operations', targetScreen: 'ModuleWorkspace' }, { label: 'Adjustments' }],
     SliceSection: [
@@ -85,7 +95,12 @@ function screenFor(template: ScreenTemplate): Screen {
  */
 function containmentChainFor(template: ScreenTemplate): ScreenTemplate[] {
     const depth = nestingChainTemplates.findIndex(candidate => candidate.name === template.name);
-    return depth < 0 ? [template] : nestingChainTemplates.slice(0, depth + 1);
+    if (depth >= 0) return nestingChainTemplates.slice(0, depth + 1);
+
+    // A template that fits a container-qualified slot (`WorkspaceScreen.moduleContent`) renders inside that container, which is what the qualifier is for.
+    const [container] = (template.fitsSlot ?? '').split('.');
+    const outer = container ? foundationScreenTemplates.find(candidate => candidate.name === container) : undefined;
+    return outer ? [outer, template] : [template];
 }
 
 function mergeSlotContent(chrome: Record<string, Screen['slotContent'][string]>, content: Record<string, Screen['slotContent'][string]>): Screen['slotContent'] {