@cratis/scene.blueprint.default 4.13.0 → 4.15.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/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/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

@@ -75,7 +75,7 @@ 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' }),
             ]),
         ],

package/gallery/supportTemplates.ts

@@ -150,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?'),

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

@@ -9,8 +9,8 @@ import { emptyState, field, formActions, pageHeader, statCard, table, widget } f
 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
@@ -103,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(
@@ -161,6 +161,60 @@ export const detailViewTemplate: ScreenTemplate = {
     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. */
 export const formPageTemplate: ScreenTemplate = {
     name: 'FormPage',
@@ -201,4 +255,4 @@ export const emptyTemplate: ScreenTemplate = {
 };
 
 /** The five workspace templates. */
-export const workspaceTemplates: ScreenTemplate[] = [dashboardTemplate, crudListTemplate, detailViewTemplate, formPageTemplate, emptyTemplate];
+export const workspaceTemplates: ScreenTemplate[] = [dashboardTemplate, crudListTemplate, masterDetailTemplate, detailViewTemplate, formPageTemplate, emptyTemplate];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.blueprint.default",
-    "version": "4.13.0",
+    "version": "4.15.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",
@@ -54,14 +54,15 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.13.0",
-        "@cratis/scene.model": "4.13.0",
-        "@cratis/scene.react": "4.13.0"
+        "@cratis/scene.engine": "4.15.0",
+        "@cratis/scene.model": "4.15.0",
+        "@cratis/scene.react": "4.15.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.13.0",
-        "@cratis/scene.model": "4.13.0",
-        "@cratis/scene.react": "4.13.0",
+        "@cratis/scene.engine": "4.15.0",
+        "@cratis/scene.model": "4.15.0",
+        "@cratis/scene.primereact": "4.15.0",
+        "@cratis/scene.react": "4.15.0",
         "@primereact/core": "11.2.0",
         "@primereact/headless": "11.2.0",
         "@primeuix/themes": "^3.0.1",