@cratis/scene.blueprint.default 4.40.0 → 4.42.0

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/stateScreenTemplates.ts

@@ -0,0 +1,107 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ScreenTemplate, TemplateMetadata } from '@cratis/scene.model';
+import { externalComponent, panel } from '../../gallery/elements';
+import { actionButton } from './dialogTemplates';
+import { column, slotLeaf } from '../../layouts/flowBuilders';
+import { component, foundationTemplateProvenance, fromQuery, thumbnailOf } from './templateParts';
+
+const metadataOf = (name: string, type: 'Auth' | 'State'): TemplateMetadata => ({ ...foundationTemplateProvenance, type, category: `Foundation / ${type}`, thumbnail: thumbnailOf(name) });
+
+/** The way back every state screen offers: home, which is always somewhere the person is allowed to be. */
+const backToDashboard = (id: string) => actionButton(id, { label: 'Back to the dashboard', emphasis: 'secondary', targetScreen: 'DashboardScreen' });
+
+/**
+ * The sign-in screen: the logo, the sign-in form, a slot for the identity providers the application offers (`providers` - buttons, each starting its
+ * provider's flow, which the application fills), an error area that is a live region and says why a sign-in failed, and a link to help. The form is
+ * made of the foundation's form components, so it validates and announces like every other form.
+ */
+export const loginScreenTemplate: ScreenTemplate = {
+    name: 'LoginScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'logo' }, { name: 'error' }, { name: 'form' }, { name: 'providers' }, { name: 'help' }],
+    arrangement: { root: column([slotLeaf('logo'), slotLeaf('error'), slotLeaf('form'), slotLeaf('providers'), slotLeaf('help')], 16) },
+    content: {
+        logo: [externalComponent('login-logo', 'logo', { label: 'Contoso', initials: 'C' })],
+        error: [component('login-error', 'notice', { text: fromQuery('SignInError', '0.message'), tone: 'danger' })],
+        form: [component('login-form', 'formScreenBody', {
+            mode: 'create', saveAndNew: false, strings: { formSave: 'Sign in', formCancel: 'Clear' },
+            sections: fromQuery('SignInSections'), values: fromQuery('SignInValues', '0'), errors: fromQuery('FormErrors', '0'),
+        })],
+        providers: [panel('login-providers', [actionButton('login-microsoft', { label: 'Continue with Microsoft', emphasis: 'secondary' }), actionButton('login-github', { label: 'Continue with GitHub', emphasis: 'secondary' })])],
+        help: [actionButton('login-help', { label: 'Need help signing in?', emphasis: 'quiet', targetScreen: 'ForbiddenScreen' })],
+    },
+    displayName: 'Sign in',
+    description: 'A sign-in form with a slot for identity providers, an error area and a help link.',
+    metadata: metadataOf('LoginScreen', 'Auth'),
+};
+
+/** The wrong address: what happened in words, a search, and the way home. */
+export const notFoundScreenTemplate: ScreenTemplate = {
+    name: 'NotFoundScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'message' }, { name: 'search' }, { name: 'actions' }],
+    arrangement: { root: column([slotLeaf('message'), slotLeaf('search'), slotLeaf('actions')], 16) },
+    content: {
+        message: [component('not-found-message', 'emptyState', { icon: 'file', headline: 'That page is not here', hint: 'The link may be old, or the thing it pointed at may have been removed.' })],
+        search: [component('not-found-search', 'globalSearch', { label: 'Search the application', placeholder: 'Search instead' })],
+        actions: [backToDashboard('not-found-home')],
+    },
+    displayName: 'Not found',
+    description: 'A wrong address explained, with a search and a link home.',
+    metadata: metadataOf('NotFoundScreen', 'State'),
+};
+
+/**
+ * The refusal: signed in, and still not allowed. It says so and offers to ask for access, and it shows nothing of what was refused - the template binds
+ * no data at all, so there is nothing to leak.
+ */
+export const forbiddenScreenTemplate: ScreenTemplate = {
+    name: 'ForbiddenScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'message' }, { name: 'actions' }],
+    arrangement: { root: column([slotLeaf('message'), slotLeaf('actions')], 16) },
+    content: {
+        message: [component('forbidden-message', 'emptyState', {
+            icon: 'lock', headline: 'You do not have access to this', hint: 'Your account is signed in, but it is not allowed here. An administrator can change that.', actionLabel: 'Request access',
+        })],
+        actions: [backToDashboard('forbidden-home')],
+    },
+    displayName: 'Forbidden',
+    description: 'A refusal that offers to request access and shows none of what was refused.',
+    metadata: metadataOf('ForbiddenScreen', 'State'),
+};
+
+/** The failure on our side: a plain message, a retry, and the support reference id a person can quote. */
+export const errorScreenTemplate: ScreenTemplate = {
+    name: 'ErrorScreen',
+    fitsSlot: 'content',
+    slots: [{ name: 'message' }, { name: 'reference' }, { name: 'actions' }],
+    arrangement: { root: column([slotLeaf('message'), slotLeaf('reference'), slotLeaf('actions')], 16) },
+    content: {
+        message: [component('error-message', 'emptyState', {
+            icon: 'alert', headline: 'Something went wrong on our side', hint: 'The team has been told. Nothing you were working on was lost.', actionLabel: 'Try again',
+        })],
+        reference: [panel('error-reference', [
+            externalComponent('error-reference-label', 'text', { text: 'Support reference' }),
+            externalComponent('error-reference-id', 'text', { text: fromQuery('SupportReference', '0.id') }),
+        ])],
+        actions: [backToDashboard('error-home')],
+    },
+    displayName: 'Error',
+    description: 'A generic failure with a retry and the support reference id to quote.',
+    metadata: metadataOf('ErrorScreen', 'State'),
+};
+
+/** The four auth and state screens of Part B 2.11. The legacy `Login`, `NotFound`, `AccessDenied` and `Error` remain as they were. */
+export const stateScreenTemplates: ScreenTemplate[] = [loginScreenTemplate, notFoundScreenTemplate, forbiddenScreenTemplate, errorScreenTemplate];
+
+/** The earlier template each spec-named one stands beside: the old name keeps working, and is the alias of the new. */
+export const foundationTemplateAliases: Record<string, string> = {
+    LoginScreen: 'Login',
+    NotFoundScreen: 'NotFound',
+    ForbiddenScreen: 'AccessDenied',
+    ErrorScreen: 'Error',
+    QuickCreateDialog: 'FormDialog',
+};

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/FoundationDialogs.stories.tsx

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { SampleDataPack } from '@cratis/scene.model';
+import { corePackage, mergePackageRegistries } from '@cratis/scene.react';
+import { primeReactPackage } from '@cratis/scene.primereact';
+import { defaultBlueprint } from '../defaultBlueprint';
+import { ComponentState } from '../foundation';
+import { GalleryDialogPreview } from './GalleryDialogPreview';
+import { GalleryScreenPreview } from './GalleryScreenPreview';
+import { TemplatePreviewState } from './TemplatePreviewState';
+
+const registry = mergePackageRegistries([corePackage, primeReactPackage, defaultBlueprint]);
+/** The foundation sample-data pack, fetched from where the package ships it (`sampleData/`), as a host's loader would. */
+const packUrl = new URL('../sampleData/foundation-en.json', import.meta.url).href;
+const loadPack = async () => ({ pack: await (await fetch(packUrl)).json() as SampleDataPack });
+
+/**
+ * The foundation dialogs and the auth and state screens (spec Part B 2.10 and 2.11) in each state, filled from the foundation sample-data pack: the data in the
+ * pack, an empty answer, and each of the standard states forced on the components that own them. A dialog opens in the box a host draws, which its frame takes on:
+ * focus handling, placement and its name.
+ */
+const meta = {
+    title: 'Blueprint/Foundation dialogs',
+    component: GalleryDialogPreview,
+    parameters: { layout: 'fullscreen' },
+    loaders: [loadPack],
+    render: (args, { loaded }) => <GalleryDialogPreview {...args} pack={loaded.pack as SampleDataPack} />,
+    args: { registry, dialogName: 'ConfirmDialog' },
+    tags: ['autodocs'],
+} satisfies Meta<typeof GalleryDialogPreview>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** A destructive confirmation: the consequences listed, the confirming button naming what it does. */
+export const Confirm: Story = {};
+
+/** The short create form, six fields at most. */
+export const QuickCreate: Story = { args: { dialogName: 'QuickCreateDialog' } };
+
+/** The lookup with the pack's accounts. */
+export const Lookup: Story = { args: { dialogName: 'LookupDialog' } };
+
+/** The lookup when the query returns nothing: it says so in words. */
+export const LookupEmpty: Story = { args: { dialogName: 'LookupDialog', state: TemplatePreviewState.Empty } };
+
+/** The lookup while its query has not answered. */
+export const LookupLoading: Story = { args: { dialogName: 'LookupDialog', forceState: { state: ComponentState.Loading } } };
+
+/** The lookup when its query failed: a message and a retry. */
+export const LookupError: Story = { args: { dialogName: 'LookupDialog', forceState: { state: ComponentState.Error, error: 'The server did not answer' } } };
+
+/** The lookup for a user who may not see the accounts: what is missing, and none of the data. */
+export const LookupNoPermission: Story = { args: { dialogName: 'LookupDialog', forceState: { state: ComponentState.NoPermission, permissionSubject: 'the accounts' } } };
+
+/** The lookup when part of it failed: the chrome stays, and the failed part is named. */
+export const LookupPartial: Story = { args: { dialogName: 'LookupDialog', forceState: { state: ComponentState.Partial, failedRegions: ['Accounts'] } } };
+
+/** A drawer from the side hosting a form. */
+export const SideSheet: Story = { args: { dialogName: 'SideSheet' } };
+
+/** The advanced filter builder; on a phone it fills the page. */
+export const Filter: Story = { args: { dialogName: 'FilterDialog' } };
+
+/** Every state screen, as a gallery screen: sign in, not found, forbidden and error. */
+export const StateScreens: StoryObj<typeof GalleryScreenPreview> = {
+    loaders: [loadPack],
+    render: (args, { loaded }) => <GalleryScreenPreview {...args} registry={registry} pack={loaded.pack as SampleDataPack} />,
+    args: { screenName: 'LoginScreen' },
+    argTypes: { screenName: { control: 'select', options: ['LoginScreen', 'NotFoundScreen', 'ForbiddenScreen', 'ErrorScreen'] } },
+};

package/gallery/GalleryDialogPreview.tsx

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useMemo } from 'react';
+import { DialogTemplate, SampleDataPack, Theme } from '@cratis/scene.model';
+import { ComponentRegistry, SceneElementView } from '@cratis/scene.react';
+import { LayoutConfigProvider, LayoutConfigState } from '../configuration';
+import { previewComponents, previewTemplateComponent } from '../preview-host/PreviewTemplate';
+import { LayoutThemeProvider, defaultBlueprintThemes } from '../themes';
+import { externalComponent } from './elements';
+import { ForcedComponentState, forceComponentState, galleryPreviewRegistry, queryResultsOf } from './GalleryScreenPreview';
+import { galleryDialogTemplates } from './dialogTemplates';
+import { galleryComponentCatalog, galleryPreviewProfile } from './previewProfile';
+import { resolveElementComponentNames } from './resolveElementNames';
+import { TemplatePreviewState } from './TemplatePreviewState';
+
+/** One gallery dialog template by name, for a story or a host that opens a specific one. */
+export const galleryDialogTemplate = (name: string): DialogTemplate | undefined => galleryDialogTemplates.find(template => template.name === name);
+
+export interface GalleryDialogPreviewProps {
+    /** The name of the gallery dialog template to open. */
+    dialogName: string;
+
+    /** Configuration to start from. */
+    initialConfig?: Partial<LayoutConfigState>;
+
+    /** The themes the preview may switch between. Defaults to the two this blueprint ships. */
+    themes?: Theme[];
+
+    /** The component registry to render against. Defaults to `core` plus this blueprint's own components. */
+    registry?: ComponentRegistry;
+
+    /** The data state to show. Defaults to the seeded, populated records. */
+    state?: TemplatePreviewState;
+
+    /** The sample-data pack that stands in for the queries the template binds to. */
+    pack?: SampleDataPack;
+
+    /** A standard state (spec Part B 1.4) to force on every foundation component of the dialog that owns the five states. */
+    forceState?: ForcedComponentState;
+}
+
+/**
+ * Opens one gallery dialog template the way a host does: inside a `role="dialog" aria-modal="true"` element, with the template's content in the wrapper
+ * a screen's template gets. Nothing here is a preview-only path - the dialog is a real {@link DialogTemplate} rendered by the real `SceneElementView`,
+ * and the dialog's own frame gives the host element its focus handling, placement and labelling exactly as it does in an application.
+ */
+export function GalleryDialogPreview({ dialogName, initialConfig, themes = defaultBlueprintThemes, registry = galleryPreviewRegistry, state = TemplatePreviewState.Populated, pack, forceState }: GalleryDialogPreviewProps) {
+    const template = galleryDialogTemplate(dialogName);
+    if (!template) throw new Error(`The gallery has no dialog template named '${dialogName}'.`);
+
+    const element = useMemo(() => {
+        const composed = externalComponent(`dialog-${template.name}`, previewTemplateComponent, {}, template.content ?? {});
+        const resolved = resolveElementComponentNames(composed, galleryPreviewProfile, galleryComponentCatalog);
+        return forceState ? forceComponentState(resolved, forceState) : resolved;
+    }, [template, forceState]);
+    const full = useMemo(() => ({ ...registry, ...previewComponents }), [registry]);
+
+    return (
+        <LayoutConfigProvider initialConfig={initialConfig} storage={null}>
+            <LayoutThemeProvider themes={themes}>
+                <div role='dialog' aria-modal='true' aria-label={template.displayName ?? template.name} data-scene-dialog={template.name}>
+                    <SceneElementView element={element} registry={full} resolveBinding={() => undefined} queryResults={queryResultsOf(pack, state)} />
+                </div>
+            </LayoutThemeProvider>
+        </LayoutConfigProvider>
+    );
+}

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],
         },
     };
 }