@cratis/scene.blueprint.default 4.12.0 → 4.14.0

package/gallery/ApplicationScreens.stories.tsx

@@ -19,7 +19,7 @@ const meta = {
         layout: 'fullscreen',
         docs: {
             description: {
-                component: 'The ten in-application screen templates plus the three-level nesting chain, each booted through the real engine as a screen.',
+                component: 'The eleven in-application screen templates plus the three-level nesting chain, each booted through the real engine as a screen.',
             },
         },
     },
@@ -36,6 +36,9 @@ export const Dashboard: Story = { args: { screenName: 'Dashboard' } };
 /** A searchable product table with a header and a primary action. */
 export const List: Story = { args: { screenName: 'CrudList' } };
 
+/** A list beside the selected record, stacking on narrow screens. */
+export const MasterDetail: Story = { args: { screenName: 'MasterDetail' } };
+
 /** One record: header, sections and a summary panel. */
 export const Detail: Story = { args: { screenName: 'DetailView' } };
 

package/gallery/GalleryScreenPreview.tsx

@@ -11,6 +11,8 @@ import { composeScreenElement } from './composeScreen';
 import { galleryComponentCatalog, galleryPreviewProfile } from './previewProfile';
 import { resolveElementComponentNames } from './resolveElementNames';
 import { galleryScreen } from './screens';
+import { TemplatePreviewState } from './TemplatePreviewState';
+import { applyTemplatePreviewState } from './applyTemplatePreviewState';
 
 /**
  * The registry a preview resolves against when a host does not supply one: `core` plus this blueprint.
@@ -33,6 +35,9 @@ export interface GalleryScreenPreviewProps {
 
     /** 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;
 }
 
 /**
@@ -48,15 +53,15 @@ 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 }: GalleryScreenPreviewProps) {
+export function GalleryScreenPreview({ screenName, initialConfig, themes = defaultBlueprintThemes, registry = galleryPreviewRegistry, state = TemplatePreviewState.Populated }: GalleryScreenPreviewProps) {
     const element = useMemo(() => {
         const screen = galleryScreen(screenName);
         if (!screen) {
             throw new Error(`The gallery has no screen named '${screenName}'.`);
         }
 
-        return resolveElementComponentNames(composeScreenElement(screen), galleryPreviewProfile, galleryComponentCatalog);
-    }, [screenName]);
+        return applyTemplatePreviewState(resolveElementComponentNames(composeScreenElement(screen), galleryPreviewProfile, galleryComponentCatalog), state);
+    }, [screenName, state]);
 
     return (
         <LayoutConfigProvider initialConfig={initialConfig} storage={null}>

package/gallery/PreviewStates.stories.tsx

@@ -0,0 +1,56 @@
+// 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 { corePackage, mergePackageRegistries } from '@cratis/scene.react';
+import { primeReactPackage } from '@cratis/scene.primereact';
+import { defaultBlueprint } from '../defaultBlueprint';
+import { GalleryScreenPreview } from './GalleryScreenPreview';
+import { TemplatePreviewState } from './TemplatePreviewState';
+
+/**
+ * The data templates in each data state, rendered against the packages the blueprint depends on - `core`,
+ * PrimeReact and the blueprint itself - so the tables are PrimeReact's own and each state is the table's own
+ * empty message, loading status or error alert rather than a placeholder.
+ */
+const registry = mergePackageRegistries([corePackage, primeReactPackage, defaultBlueprint]);
+
+const meta = {
+    title: 'Blueprint/Preview states',
+    component: GalleryScreenPreview,
+    parameters: {
+        layout: 'fullscreen',
+        docs: { description: { component: 'Populated, empty, loading and error states of the data templates, through the real packages.' } },
+    },
+    args: { registry },
+    argTypes: { state: { control: 'select', options: Object.values(TemplatePreviewState) } },
+    tags: ['autodocs'],
+} satisfies Meta<typeof GalleryScreenPreview>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** The list with its seeded products. */
+export const ListPopulated: Story = { args: { screenName: 'CrudList', state: TemplatePreviewState.Populated } };
+
+/** The list once the query returns nothing. */
+export const ListEmpty: Story = { args: { screenName: 'CrudList', state: TemplatePreviewState.Empty } };
+
+/** The list while the query has not answered. */
+export const ListLoading: Story = { args: { screenName: 'CrudList', state: TemplatePreviewState.Loading } };
+
+/** The list when the query failed. */
+export const ListError: Story = { args: { screenName: 'CrudList', state: TemplatePreviewState.Error } };
+
+/** Master/detail with its customers. */
+export const MasterDetailPopulated: Story = { args: { screenName: 'MasterDetail', state: TemplatePreviewState.Populated } };
+
+/** Master/detail while loading. */
+export const MasterDetailLoading: Story = { args: { screenName: 'MasterDetail', state: TemplatePreviewState.Loading } };
+
+/** The dashboard when its widgets' data failed to load. */
+export const DashboardError: Story = { args: { screenName: 'Dashboard', state: TemplatePreviewState.Error } };
+
+/** User administration with no users yet. */
+export const UsersEmpty: Story = { args: { screenName: 'UserManagement', state: TemplatePreviewState.Empty } };

package/gallery/TemplatePreviewState.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The data states a template preview can show. A template is only worth choosing if it looks right in all
+ * four, because an application spends real time in each of them.
+ */
+export enum TemplatePreviewState {
+    /** The seeded, realistic records. */
+    Populated = 'populated',
+
+    /** The query returned nothing; each table shows its empty message. */
+    Empty = 'empty',
+
+    /** The query has not answered yet; each table announces that it is loading. */
+    Loading = 'loading',
+
+    /** The query failed; each table announces the error in place of its rows. */
+    Error = 'error',
+}

package/gallery/applyTemplatePreviewState.ts

@@ -0,0 +1,69 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ExternalComponent, Panel, SceneElement } from '@cratis/scene.model';
+import { TemplatePreviewState } from './TemplatePreviewState';
+
+/** What a table in a preview says when its data could not be loaded. */
+export const previewErrorMessage = 'The data could not be loaded. Try again in a moment.';
+
+/**
+ * Puts every data-bearing element of a composed screen into one data state, leaving everything else - the
+ * shell, headers, actions and static content - exactly as authored.
+ *
+ * A data-bearing element is one whose `rows` are records: the seeded rows are what a query would return,
+ * so the states are expressed as a query's outcomes in the table's own vocabulary - no rows, `loading`, or
+ * an `error` message - rather than by swapping in a different component. The authored tree is not changed.
+ */
+export function applyTemplatePreviewState<T extends SceneElement>(element: T, state: TemplatePreviewState): T {
+    if (state === TemplatePreviewState.Populated) return element;
+    return transform(element, state) as T;
+}
+
+/** Whether a composed screen contains anything a data state changes. */
+export function hasPreviewData(element: SceneElement): boolean {
+    const properties = (element as Partial<ExternalComponent>).properties;
+    if (isDataBearing(properties)) return true;
+    return childrenOf(element).some(hasPreviewData);
+}
+
+function transform(element: SceneElement, state: TemplatePreviewState): SceneElement {
+    const external = element as Partial<ExternalComponent>;
+    const panel = element as Partial<Panel>;
+    let result: SceneElement = element;
+
+    if (isDataBearing(external.properties)) {
+        result = { ...result, properties: { ...external.properties, ...stateProperties(state) } } as SceneElement;
+    }
+
+    if (external.slots) {
+        const slots = Object.fromEntries(Object.entries(external.slots).map(([name, children]) => [name, children.map(child => transform(child, state))]));
+        result = { ...result, slots } as SceneElement;
+    }
+
+    if (Array.isArray(panel.children)) {
+        result = { ...result, children: panel.children.map(child => transform(child, state)) } as SceneElement;
+    }
+
+    return result;
+}
+
+function stateProperties(state: TemplatePreviewState): Record<string, unknown> {
+    switch (state) {
+        case TemplatePreviewState.Empty: return { rows: [] };
+        case TemplatePreviewState.Loading: return { rows: [], loading: true };
+        case TemplatePreviewState.Error: return { rows: [], error: previewErrorMessage };
+        default: return {};
+    }
+}
+
+function isDataBearing(properties: Record<string, unknown> | undefined): boolean {
+    const rows = properties?.rows;
+    return Array.isArray(rows) && rows.every(row => typeof row === 'object' && row !== null && !Array.isArray(row));
+}
+
+function childrenOf(element: SceneElement): SceneElement[] {
+    const external = element as Partial<ExternalComponent>;
+    const panel = element as Partial<Panel>;
+    return [...Object.values(external.slots ?? {}).flat(), ...(Array.isArray(panel.children) ? panel.children : [])];
+}

package/gallery/authTemplates.ts

@@ -7,6 +7,7 @@ import { SlotName } from '../layouts';
 import { TemplateSlotName } from './TemplateSlotName';
 import { button, card, externalComponent, text } from './elements';
 import { field, formActions } from './widgets';
+import { defaultBlueprintTemplateProvenance } from '../templateProvenance';
 
 /**
  * The six screens that stand between someone and the application: sign in, register, forgotten password,
@@ -47,6 +48,7 @@ export const loginTemplate: ScreenTemplate = {
     },
     displayName: 'Sign in',
     description: 'Email and password beside the branding panel.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Register. */
@@ -69,6 +71,7 @@ export const registerTemplate: ScreenTemplate = {
     },
     displayName: 'Register',
     description: 'Account creation with a password strength meter and the terms checkbox.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Forgotten password: ask for the address. */
@@ -88,6 +91,7 @@ export const forgotPasswordTemplate: ScreenTemplate = {
     },
     displayName: 'Forgotten password',
     description: 'One field and one button - the whole point is that it asks for nothing else.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** New password: the other end of the link. */
@@ -108,6 +112,7 @@ export const newPasswordTemplate: ScreenTemplate = {
     },
     displayName: 'New password',
     description: 'Where a reset link lands: choose it, confirm it, done.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Verification: the code from the email. */
@@ -128,6 +133,7 @@ export const verificationTemplate: ScreenTemplate = {
     },
     displayName: 'Verification',
     description: 'The code step, with the progress indicator that tells you how much is left.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Lock screen: the session is still there, the person has to prove they are. */
@@ -148,6 +154,7 @@ export const lockScreenTemplate: ScreenTemplate = {
     },
     displayName: 'Lock screen',
     description: 'One person, one password, and no way to lose what was open.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** The six authentication templates. */

package/gallery/dialogTemplates.ts

@@ -5,6 +5,7 @@ import { DialogTemplate } from '@cratis/scene.model';
 import { TemplateSlotName } from './TemplateSlotName';
 import { button, card, externalComponent, panel, text } from './elements';
 import { field } from './widgets';
+import { defaultBlueprintTemplateProvenance } from '../templateProvenance';
 
 /**
  * The three dialog shapes an application repeats: confirm something destructive, capture a short form, and
@@ -32,6 +33,7 @@ export const confirmDialogTemplate: DialogTemplate = {
     },
     displayName: 'Confirmation dialog',
     description: 'One question with the consequence spelled out, and a way back.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Form: a short capture that does not deserve a page of its own. */
@@ -51,6 +53,7 @@ export const formDialogTemplate: DialogTemplate = {
     },
     displayName: 'Form dialog',
     description: 'A handful of fields captured without leaving the page underneath.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Detail: a record shown over the list it came from. */
@@ -73,6 +76,7 @@ export const detailDialogTemplate: DialogTemplate = {
     },
     displayName: 'Detail dialog',
     description: 'A record over the list it came from, with a route to the full page.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** The dialog templates this blueprint provides. */

package/gallery/index.ts

@@ -20,3 +20,5 @@ export * from './componentNames';
 export * from './previewProfile';
 export * from './resolveElementNames';
 export * from './GalleryScreenPreview';
+export * from './TemplatePreviewState';
+export * from './applyTemplatePreviewState';

package/gallery/navigation.ts

@@ -21,6 +21,7 @@ export const navigationEntries: NavigationEntry[] = [
     { label: 'Dashboard', targetScreen: 'Dashboard', icon: 'pi pi-home', group: 'Workspace', order: 10 },
     { label: 'Products', targetScreen: 'CrudList', icon: 'pi pi-box', group: 'Workspace', order: 20 },
     { label: 'Product detail', targetScreen: 'DetailView', icon: 'pi pi-file', group: 'Workspace', order: 30 },
+    { label: 'Customers', targetScreen: 'MasterDetail', icon: 'pi pi-users', group: 'Workspace', order: 35 },
     { label: 'New product', targetScreen: 'FormPage', icon: 'pi pi-plus-circle', group: 'Workspace', order: 40 },
     { label: 'Invoices', targetScreen: 'Invoice', icon: 'pi pi-receipt', group: 'Workspace', order: 50 },
     { label: 'Nothing yet', targetScreen: 'Empty', icon: 'pi pi-inbox', group: 'Workspace', order: 60 },

package/gallery/nesting.ts

@@ -7,6 +7,7 @@ import { SlotName, column, slotLeaf } from '../layouts';
 import { TemplateSlotName } from './TemplateSlotName';
 import { button, externalComponent } from './elements';
 import { pageHeader } from './widgets';
+import { defaultBlueprintTemplateProvenance } from '../templateProvenance';
 
 /**
  * A worked three-level chain, from the application layout down to a slice.
@@ -36,6 +37,7 @@ export const moduleWorkspaceTemplate: ScreenTemplate = {
     },
     displayName: 'Module workspace',
     description: 'Module level: fits the application layout content slot and offers a body for one feature.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /**
@@ -56,6 +58,7 @@ export const featureSectionTemplate: ScreenTemplate = {
     },
     displayName: 'Feature section',
     description: 'Feature level: fits a module workspace body slot and brings the action toolbar.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /**
@@ -76,6 +79,7 @@ export const sliceSectionTemplate: ScreenTemplate = {
     },
     displayName: 'Slice section',
     description: 'Slice level: fits a feature section body slot and hosts one behavior.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** The chain, outermost first - what a spec walks to prove `fitsSlot` resolves at every level. */

package/gallery/screens.ts

@@ -15,7 +15,7 @@ import { workspaceTemplates } from './workspaceTemplates';
 /**
  * The screen templates this blueprint provides.
  *
- * Ten shapes for inside the application shell, ten for the full-page shell, and the three-level nesting
+ * Eleven shapes for inside the application shell, ten for the full-page shell, and the three-level nesting
  * chain that demonstrates how `fitsSlot` composes. The list is what the manifest's `screenTemplates` names
  * and what the bundle provides; `validatePackageBundle` proves the two agree.
  */
@@ -34,6 +34,7 @@ const fullPageTemplateNames = new Set([...authTemplates, ...statusTemplates].map
 const breadcrumbs: Record<string, BreadcrumbEntry[]> = {
     Dashboard: [{ label: 'Dashboard' }],
     CrudList: [{ label: 'Catalog', targetScreen: 'Dashboard' }, { label: 'Products' }],
+    MasterDetail: [{ label: 'Sales', targetScreen: 'Dashboard' }, { label: 'Customers' }],
     DetailView: [{ label: 'Catalog', targetScreen: 'Dashboard' }, { label: 'Products', targetScreen: 'CrudList' }, { label: 'Bamboo Watch' }],
     FormPage: [{ label: 'Catalog', targetScreen: 'Dashboard' }, { label: 'Products', targetScreen: 'CrudList' }, { label: 'New product' }],
     Empty: [{ label: 'Catalog', targetScreen: 'Dashboard' }, { label: 'Products' }],

package/gallery/statusTemplates.ts

@@ -7,6 +7,7 @@ import { SlotName } from '../layouts';
 import { TemplateSlotName } from './TemplateSlotName';
 import { button, card, externalComponent, panel, text } from './elements';
 import { widget } from './widgets';
+import { defaultBlueprintTemplateProvenance } from '../templateProvenance';
 
 /**
  * The four screens that are not part of anyone's plan: a server error, a refusal, a wrong address, and the
@@ -37,6 +38,7 @@ export const errorTemplate: ScreenTemplate = {
     },
     displayName: 'Error',
     description: 'A server-side failure, said plainly, with a way onward.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Signed in, and still not allowed. */
@@ -59,6 +61,7 @@ export const accessDeniedTemplate: ScreenTemplate = {
     },
     displayName: 'Access denied',
     description: 'A refusal that distinguishes "not signed in" from "not allowed".',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** No such address. */
@@ -72,13 +75,14 @@ export const notFoundTemplate: ScreenTemplate = {
                 externalComponent('not-found-tag', 'tag', { value: '404', severity: 'info' }),
                 text('not-found-title', 'That page is not here'),
                 text('not-found-message', 'The link may be old, or the thing it pointed at may have been removed.'),
-                externalComponent('not-found-search', 'inputText', { placeholder: 'Search instead' }),
+                externalComponent('not-found-search', 'inputText', { placeholder: 'Search instead', ariaLabel: 'Search' }),
                 button('not-found-home', 'Back to the dashboard', { severity: 'secondary', targetScreen: 'Dashboard' }),
             ]),
         ],
     },
     displayName: 'Not found',
     description: 'A wrong address, with a search box rather than a dead end.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** The page that has to do the selling. */
@@ -112,6 +116,7 @@ export const landingTemplate: ScreenTemplate = {
     },
     displayName: 'Landing',
     description: 'The marketing front door, with its own navigation because it has no application chrome.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** The four status and marketing templates. */

package/gallery/supportTemplates.ts

@@ -6,6 +6,7 @@ import { SlotName } from '../layouts';
 import { TemplateSlotName } from './TemplateSlotName';
 import { button, card, externalComponent, text } from './elements';
 import { field, formActions, pageHeader, table, widget } from './widgets';
+import { defaultBlueprintTemplateProvenance } from '../templateProvenance';
 
 /**
  * The five shapes an application needs that are not the CRUD loop: documentation, the signed-in user's own
@@ -40,6 +41,7 @@ export const documentationTemplate: ScreenTemplate = {
     },
     displayName: 'Documentation',
     description: 'Prose with a table of contents beside it.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Profile settings: the signed-in user editing their own account. */
@@ -67,6 +69,7 @@ export const profileSettingsTemplate: ScreenTemplate = {
     },
     displayName: 'Profile settings',
     description: 'The signed-in user editing their own name, photo, password and notifications.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** User management: administering everybody else. */
@@ -99,6 +102,7 @@ export const userManagementTemplate: ScreenTemplate = {
     },
     displayName: 'User management',
     description: 'The people table, with roles, status and an invitation action.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Invoice: a printable document, which is a different shape from a screen. */
@@ -135,6 +139,7 @@ export const invoiceTemplate: ScreenTemplate = {
     },
     displayName: 'Invoice',
     description: 'A printable document: parties, line items and totals.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** Help: the answers, and a way to ask when they are not there. */
@@ -145,7 +150,7 @@ export const helpTemplate: ScreenTemplate = {
     content: {
         [TemplateSlotName.Header]: [pageHeader('help-header', 'Help', 'Search the answers, or ask us directly')],
         [TemplateSlotName.Body]: [
-            externalComponent('help-search', 'inputText', { placeholder: 'Search help' }),
+            externalComponent('help-search', 'inputText', { placeholder: 'Search help', ariaLabel: 'Search help' }),
             widget('help-popular', 'Popular answers', [
                 text('help-1', 'How do I invite someone to the workspace?'),
                 text('help-2', 'Why can I not see the sidebar on my phone?'),
@@ -158,6 +163,7 @@ export const helpTemplate: ScreenTemplate = {
     },
     displayName: 'Help',
     description: 'Searchable answers with a route to a human.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** The five support templates. */

package/gallery/widgets.ts

@@ -32,19 +32,28 @@ export function widget(id: string, title: string, content: SceneElement[]): Scen
     return card(id, [text(`${id}-title`, title), ...content], { title });
 }
 
-/** A table with real columns and real rows, so a list template looks like a list. */
-export function table(id: string, columns: { field: string; header: string }[], rows: Record<string, unknown>[]): SceneElement {
+/**
+ * A table with real columns and real rows, so a list template looks like a list.
+ *
+ * The properties are the table's own vocabulary - `rows` for the records and `pageSize` to page them - so
+ * a host with the real table loaded shows the rows rather than an empty grid. `emptyMessage` is what the
+ * same table says once the rows are gone, which is how a preview shows a template's empty state.
+ */
+export function table(id: string, columns: { field: string; header: string }[], rows: Record<string, unknown>[], emptyMessage = 'Nothing to show yet'): SceneElement {
     return externalComponent(
         id,
         'dataTable',
-        { value: rows, dataKey: columns[0]?.field ?? 'id', paginator: rows.length > 8, rows: 8 },
+        { rows, dataKey: columns[0]?.field ?? 'id', emptyMessage, ...(rows.length > 8 ? { pageSize: 8 } : {}) },
         { columns: columns.map(column => externalComponent(`${id}-${column.field}`, 'column', { field: column.field, header: column.header, sortable: true })) },
     );
 }
 
-/** One labeled input in a form template. */
+/**
+ * One labeled input in a form template. The visible label is a separate text element, so the input carries
+ * the same words as its accessible name - otherwise a screen reader announces an unnamed field.
+ */
 export function field(id: string, label: string, componentName: string, properties: Record<string, unknown> = {}): SceneElement {
-    return panel(id, [text(`${id}-label`, label), externalComponent(`${id}-input`, componentName, properties)]);
+    return panel(id, [text(`${id}-label`, label), externalComponent(`${id}-input`, componentName, { ariaLabel: label, ...properties })]);
 }
 
 /** A row of buttons closing a form. */

package/gallery/workspaceTemplates.ts

@@ -6,10 +6,11 @@ import { SlotName, column, grid, slotLeaf } from '../layouts';
 import { TemplateSlotName } from './TemplateSlotName';
 import { button, card, externalComponent, text } from './elements';
 import { emptyState, field, formActions, pageHeader, statCard, table, widget } from './widgets';
+import { defaultBlueprintTemplateProvenance, sakaiCompositionProvenance } from '../templateProvenance';
 
 /**
- * The five workhorse shapes inside an application shell: a dashboard, a list, a detail, a form and the
- * designed empty state.
+ * The six workhorse shapes inside an application shell: a dashboard, a list, master/detail, a detail, a
+ * form and the designed empty state.
  *
  * Every one fits the layout's `content` slot, and every one carries realistic seeded content rather than
  * placeholder text. A gallery whose dashboard shows four boxes labeled "Card" proves the renderer runs; a
@@ -88,6 +89,7 @@ export const dashboardTemplate: ScreenTemplate = {
     },
     displayName: 'Dashboard',
     description: 'Four stat cards over two columns of widgets - the composition every template line opens with.',
+    metadata: { ...sakaiCompositionProvenance },
 };
 
 /** The list: a filter toolbar, a real table, and the row actions a list needs. */
@@ -101,7 +103,7 @@ export const crudListTemplate: ScreenTemplate = {
                 button('crud-new', 'New product', { severity: 'primary', icon: 'pi pi-plus' }),
                 button('crud-import', 'Import', { severity: 'secondary', icon: 'pi pi-upload' }),
             ]),
-            externalComponent('crud-search', 'inputText', { placeholder: 'Search products' }),
+            externalComponent('crud-search', 'inputText', { placeholder: 'Search products', ariaLabel: 'Search products' }),
         ],
         [TemplateSlotName.Body]: [
             table(
@@ -125,6 +127,7 @@ export const crudListTemplate: ScreenTemplate = {
     },
     displayName: 'List',
     description: 'A searchable table with a header, primary action and row data.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** The detail: a summary panel beside the record's own sections. */
@@ -155,6 +158,61 @@ export const detailViewTemplate: ScreenTemplate = {
     },
     displayName: 'Detail',
     description: 'One record: a header with actions, its sections, and a summary panel.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
+};
+
+/**
+ * Master/detail: the list and the selected record side by side, so working through records does not mean
+ * leaving the list. The detail region is an outlet that accepts detail screens, which is what lets a row's
+ * destination open a full detail screen in place.
+ *
+ * At a compact width the two stack, list first, because side-by-side on a phone is two unreadable halves.
+ */
+export const masterDetailTemplate: ScreenTemplate = {
+    name: 'MasterDetail',
+    fitsSlot: SlotName.Content,
+    slots: [{ name: TemplateSlotName.Header }, { name: TemplateSlotName.Primary }, { name: TemplateSlotName.SidePanel }],
+    outlets: [{ name: 'master-detail.detail', description: 'The selected record.', accepts: ['Detail'] }],
+    arrangement: {
+        root: column([slotLeaf(TemplateSlotName.Header), grid([slotLeaf(TemplateSlotName.Primary), slotLeaf(TemplateSlotName.SidePanel)], 2, 16)], 16),
+        overrides: [
+            {
+                width: WidthSizeClass.Compact,
+                root: column([slotLeaf(TemplateSlotName.Header), slotLeaf(TemplateSlotName.Primary), slotLeaf(TemplateSlotName.SidePanel)], 16),
+            },
+        ],
+    },
+    content: {
+        [TemplateSlotName.Header]: [pageHeader('master-header', 'Customers', '1,204 customers, 38 with overdue invoices')],
+        [TemplateSlotName.Primary]: [
+            table(
+                'customers-table',
+                [
+                    { field: 'name', header: 'Customer' },
+                    { field: 'city', header: 'City' },
+                    { field: 'balance', header: 'Balance' },
+                ],
+                [
+                    { name: 'Northwind Traders', city: 'Seattle', balance: '$4,200.00' },
+                    { name: 'Contoso Ltd', city: 'Oslo', balance: '$0.00' },
+                    { name: 'Fabrikam', city: 'Lyon', balance: '$12,940.50' },
+                    { name: 'Adventure Works', city: 'Denver', balance: '$318.20' },
+                ],
+                'No customers match the search',
+            ),
+        ],
+        [TemplateSlotName.SidePanel]: [
+            widget('customer-detail', 'Northwind Traders', [
+                text('customer-contact', 'Contact: Amelia Nyquist'),
+                text('customer-terms', 'Payment terms: 30 days'),
+                externalComponent('customer-status', 'tag', { value: 'Overdue', severity: 'warning' }),
+                button('customer-open', 'Open customer', { severity: 'primary' }),
+            ]),
+        ],
+    },
+    displayName: 'Master/detail',
+    description: 'A list beside the selected record, stacking on narrow screens.',
+    metadata: { ...defaultBlueprintTemplateProvenance, type: 'Workspace' },
 };
 
 /** The form: fields, grouped, with the actions that close them. */
@@ -178,6 +236,7 @@ export const formPageTemplate: ScreenTemplate = {
     },
     displayName: 'Form',
     description: 'A grouped form with the field types an application actually uses.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** The empty state: what a list looks like before anything exists, designed rather than apologized for. */
@@ -192,7 +251,8 @@ export const emptyTemplate: ScreenTemplate = {
     },
     displayName: 'Empty state',
     description: 'The designed empty state for a list that has nothing in it yet.',
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };
 
 /** The five workspace templates. */
-export const workspaceTemplates: ScreenTemplate[] = [dashboardTemplate, crudListTemplate, detailViewTemplate, formPageTemplate, emptyTemplate];
+export const workspaceTemplates: ScreenTemplate[] = [dashboardTemplate, crudListTemplate, masterDetailTemplate, detailViewTemplate, formPageTemplate, emptyTemplate];

package/index.ts

@@ -10,3 +10,4 @@ export * from './shell';
 export * from './themes';
 export * from './defaultBlueprintComponents';
 export * from './defaultBlueprint';
+export * from './templateProvenance';

package/layouts/appShell.ts

@@ -5,6 +5,7 @@ import { FlowArrangement, HeightSizeClass, Layout, WidthSizeClass } from '@crati
 import { LayoutName } from './LayoutName';
 import { SlotName } from './SlotName';
 import { column, row, slotLeaf } from './flowBuilders';
+import { sakaiCompositionProvenance } from '../templateProvenance';
 
 /**
  * The tree at a regular width and height: a topbar across the top, the sidebar column beside the main
@@ -103,4 +104,5 @@ export const appShellLayout: Layout = {
         { name: SlotName.ConfigPanel },
     ],
     arrangement: appShellArrangement,
+    metadata: { ...sakaiCompositionProvenance },
 };

package/layouts/fullPage.ts

@@ -5,6 +5,7 @@ import { FlowArrangement, Layout, WidthSizeClass } from '@cratis/scene.model';
 import { LayoutName } from './LayoutName';
 import { SlotName } from './SlotName';
 import { column, row, slotLeaf } from './flowBuilders';
+import { defaultBlueprintTemplateProvenance } from '../templateProvenance';
 
 /**
  * The tree at a regular width: the branding aside beside the content, with the configurator over both.
@@ -45,4 +46,5 @@ export const fullPageLayout: Layout = {
     name: LayoutName.FullPage,
     slots: [{ name: SlotName.Aside }, { name: SlotName.Content }, { name: SlotName.ConfigPanel }],
     arrangement: fullPageArrangement,
+    metadata: { ...defaultBlueprintTemplateProvenance },
 };