@cratis/scene.blueprint.default 4.40.0 → 4.41.0

package/foundation/index.ts

@@ -56,3 +56,4 @@ export * from './foundationDescriptors';
 export * from './foundationComponentMetadata';
 export * from './foundationSamples';
 export * from './FoundationStates';
+export * from './templates';

package/foundation/templates/boardScreenTemplate.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 board: columns mapped to a status or stage, cards that move between them - by dragging or by each card's own Move-to menu, so the board is as
+ * usable from a keyboard and a screen reader as with a pointer.
+ */
+export const boardScreenTemplate: ScreenTemplate = {
+    name: 'BoardScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'header' }, { name: 'toolbar' }, { name: 'board' }],
+    arrangement: {
+        root: column([slotLeaf('header'), row([slotLeaf('toolbar')], 8), slotLeaf('board')], 12),
+        overrides: [{ width: WidthSizeClass.Compact, root: column([slotLeaf('header'), slotLeaf('toolbar'), slotLeaf('board')], 16) }],
+    },
+    content: {
+        header: [component('board-header', 'pageHeader', { title: 'Pipeline', subtitle: 'Drag a deal to a new stage' })],
+        toolbar: [component('board-search', 'globalSearch', { placeholder: 'Search the pipeline', label: 'Search the pipeline' })],
+        board: [component('board-columns', 'kanbanBoard', { columns: fromQuery('PipelineColumns'), cards: fromQuery('PipelineCards') })],
+    },
+    displayName: 'Board',
+    description: 'Columns mapped to a stage with cards that move by dragging or by menu.',
+    metadata: { ...foundationTemplateProvenance, type: 'Board', category: 'Foundation / Board', thumbnail: thumbnailOf('BoardScreen') },
+};

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/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'] {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.blueprint.default",
-    "version": "4.40.0",
+    "version": "4.41.0",
     "description": "The default blueprint: application shell layouts, the screen and dialog templates that go inside them, the components that fill their slots, and two themes.",
     "keywords": [
         "cratis",
@@ -23,6 +23,8 @@
     },
     "files": [
         "dist",
+        "sampleData",
+        "thumbnails",
         "**/*.ts",
         "**/*.tsx",
         "shell/layout.css",
@@ -55,15 +57,15 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.40.0",
-        "@cratis/scene.model": "4.40.0",
-        "@cratis/scene.react": "4.40.0"
+        "@cratis/scene.engine": "4.41.0",
+        "@cratis/scene.model": "4.41.0",
+        "@cratis/scene.react": "4.41.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.40.0",
-        "@cratis/scene.model": "4.40.0",
-        "@cratis/scene.primereact": "4.40.0",
-        "@cratis/scene.react": "4.40.0",
+        "@cratis/scene.engine": "4.41.0",
+        "@cratis/scene.model": "4.41.0",
+        "@cratis/scene.primereact": "4.41.0",
+        "@cratis/scene.react": "4.41.0",
         "@primereact/core": "11.2.0",
         "@primereact/headless": "11.2.0",
         "@primeuix/themes": "^3.0.1",