@cratis/scene.blueprint.default 4.34.0 → 4.36.0

package/foundation/foundationSamples.ts

@@ -49,6 +49,35 @@ export const foundationSamples: Record<string, FoundationSample> = {
         properties: { views: [{ id: 'all', label: 'All leads' }, { id: 'mine', label: 'Mine' }, { id: 'overdue', label: 'Overdue' }], activeView: 'mine' },
         data: ['Mine'], stateful: true,
     },
+    [ComponentName.ChecklistSection]: {
+        properties: {
+            today: '2026-03-10', locale: 'en-US',
+            sections: [
+                { title: 'Before day one', items: [{ id: 't1', label: 'Send the contract', owner: 'Grace', due: '2026-03-01', done: true }, { id: 't2', label: 'Order a laptop', owner: 'Linus', due: '2026-03-05' }] },
+                { title: 'First week', items: [{ id: 't3', label: 'Security training', owner: 'Ada', due: '2026-03-20' }] },
+            ],
+        },
+        data: ['Send the contract', '1 of 2 complete'], stateful: true,
+    },
+    [ComponentName.ActivityFeed]: {
+        properties: {
+            locale: 'en-US', timeZone: 'UTC',
+            entries: [
+                { id: 'a1', actor: 'Ada Lovelace', action: 'commented', kind: 'comment', at: '2026-03-10T09:30:00Z', body: 'Sent the revised quote.' },
+                { id: 'a2', actor: 'Grace Hopper', action: 'changed the owner to Linus', kind: 'change', at: '2026-03-09T16:00:00Z' },
+                { id: 'a3', actor: 'System', action: 'marked the deal as qualified', kind: 'status', at: '2026-03-09T08:00:00Z' },
+            ],
+        },
+        data: ['Sent the revised quote.'], stateful: true,
+    },
+    [ComponentName.AvatarStack]: {
+        properties: { people: [{ name: 'Ada Lovelace' }, { name: 'Grace Hopper' }, { name: 'Linus Torvalds' }, { name: 'Margaret Hamilton' }, { name: 'Alan Turing' }, { name: 'Barbara Liskov' }], max: 4 },
+        data: ['+2'], stateful: true,
+    },
+    [ComponentName.FileUploader]: {
+        properties: { accept: '.pdf, image/*', maxSizeMb: 10, multiple: true },
+        data: [], stateful: true,
+    },
 };
 
 /** A scene element for a foundation component, populated with its sample unless properties are given, with the state forced when asked. */

package/foundation/foundationStrings.ts

@@ -80,11 +80,26 @@ export const foundationStrings = {
     viewsNone: 'There are no saved views',
     checklistProgress: '{done} of {total} complete',
     checklistOwner: 'Owner',
+    checklistOverdue: 'Overdue',
+    checklistDone: 'Done',
+    checklistOpen: 'Open',
+    checklistItemProgress: 'Progress of {title}',
+    checklistNone: 'This checklist has no tasks',
     checklistDue: 'Due',
     activityEmpty: 'No activity yet',
+    activityComment: 'Comment',
+    activityChange: 'Change',
+    activityStatus: 'Status',
+    activitySystem: 'System',
+    activityBy: 'by {actor}',
     avatarOverflow: '{count} more',
     avatarPeople: '{count} people',
     uploadDrop: 'Drop files here or',
+    uploadLimits: 'Up to {limit} each',
+    uploadAccepts: 'Accepts {types}',
+    uploadSelected: 'Selected files',
+    uploadQueued: 'Ready to upload',
+    uploadSingle: 'Only one file can be uploaded at a time',
     uploadBrowse: 'Browse files',
     uploadRemove: 'Remove {name}',
     uploadTooLarge: '{name} is larger than {limit}',

package/foundation/index.ts

@@ -21,6 +21,15 @@ export * from './columnModel';
 export * from './ColumnChooser';
 export * from './viewModel';
 export * from './SavedViewsMenu';
+export * from './checklistModel';
+export * from './ChecklistSection';
+export * from './activityModel';
+export * from './ActivityFeed';
+export * from './avatarModel';
+export * from './AvatarStack';
+export * from './uploadModel';
+export * from './FileUploaderHandler';
+export * from './FileUploader';
 export * from './foundationDescriptors';
 export * from './foundationComponentMetadata';
 export * from './foundationSamples';

package/foundation/uploadModel.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Where a file is in being uploaded. */
+export enum UploadStatus {
+    Queued = 'queued',
+    Uploading = 'uploading',
+    Done = 'done',
+    Failed = 'failed',
+}
+
+/** The rules a selection is checked against before anything is sent. */
+export interface UploadRules {
+    /** A comma-separated `accept` list: extensions (`.pdf`), MIME types (`image/png`) and wildcards (`image/*`). */
+    accept: string;
+    maximumBytes: number;
+    multiple: boolean;
+}
+
+/** What the checker needs of a file. */
+export interface SelectedFile {
+    name: string;
+    size: number;
+    type: string;
+}
+
+/** Why a file was refused. */
+export enum UploadRefusal {
+    WrongType = 'wrongType',
+    TooLarge = 'tooLarge',
+    Single = 'single',
+}
+
+/** Whether a file matches an `accept` list; an empty list accepts everything, and matching ignores case. */
+export function matchesAccept(file: SelectedFile, accept: string): boolean {
+    const patterns = accept.split(',').map(pattern => pattern.trim().toLowerCase()).filter(pattern => pattern.length > 0);
+    if (patterns.length === 0) return true;
+
+    const name = file.name.toLowerCase();
+    const type = file.type.toLowerCase();
+    return patterns.some(pattern => pattern.startsWith('.') ? name.endsWith(pattern) : pattern.endsWith('/*') ? type.startsWith(pattern.slice(0, -1)) : type === pattern);
+}
+
+/** Sorts a selection into the files to take and the reasons for refusing the others. Only the first is taken when one file is allowed. */
+export function checkSelection<T extends SelectedFile>(files: T[], rules: UploadRules, alreadySelected = 0): { accepted: T[]; refused: { file: T; reason: UploadRefusal }[] } {
+    const accepted: T[] = [];
+    const refused: { file: T; reason: UploadRefusal }[] = [];
+
+    for (const file of files) {
+        if (!matchesAccept(file, rules.accept)) refused.push({ file, reason: UploadRefusal.WrongType });
+        else if (rules.maximumBytes > 0 && file.size > rules.maximumBytes) refused.push({ file, reason: UploadRefusal.TooLarge });
+        else if (!rules.multiple && alreadySelected + accepted.length >= 1) refused.push({ file, reason: UploadRefusal.Single });
+        else accepted.push(file);
+    }
+
+    return { accepted, refused };
+}
+
+/** A file size in the largest unit that keeps it under 1024, for the locale. */
+export function formatBytes(bytes: number, locale: string): string {
+    const units = ['B', 'KB', 'MB', 'GB'];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) { value /= 1024; unit++; }
+    return `${new Intl.NumberFormat(locale, { maximumFractionDigits: unit === 0 ? 0 : 1 }).format(value)} ${units[unit]}`;
+}

package/package.json

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

package/preview-host/ApplicationHost.tsx

@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { ReactNode, useMemo, useState } from 'react';
-import { SceneElement, type EffectiveConfiguration } from '@cratis/scene.model';
+import { DialogTemplate, SceneElement, type EffectiveConfiguration } from '@cratis/scene.model';
 import { BindingResolver, BindingScope } from '@cratis/scene.engine';
 import {
     ComponentRegistry, SceneElementView, SceneHistory, SceneNavigationContextValue, SceneNavigationModel, SceneNavigationModelProvider,
@@ -50,6 +50,30 @@ export interface ApplicationHostProps {
      */
     renderDialog?(navigation: SceneNavigationContextValue): ReactNode;
 
+    /**
+     * Draws a dialog the document declares, in place of the host's plain one - a host that wants its own backdrop, a close button
+     * and keyboard handling around the template's content. Called inside {@link scope}.
+     * @param template The dialog template that is open.
+     * @param content The template's composed content.
+     * @param navigation Where the user is.
+     */
+    renderDialogTemplate?(template: DialogTemplate, content: SceneElement, navigation: SceneNavigationContextValue): ReactNode;
+
+    /**
+     * What a host provides around everything that renders - the screen on the page and the dialog over it: its data, its command
+     * dispatcher, its chrome state. Inside the navigation providers, so it can read where the user is. Stage puts its data and
+     * interaction scope here, so the screen, a dialog template and a slice dialog all share them.
+     * @param navigation Where the user is.
+     * @param children The screen and the dialog.
+     */
+    scope?(navigation: SceneNavigationContextValue, children: ReactNode): ReactNode;
+
+    /**
+     * Where the shell keeps its layout configuration - the sidebar's state, the chosen theme. A preview keeps none (null, the default);
+     * a running application passes its storage so what a user chose is still chosen on the next visit.
+     */
+    layoutConfigStorage?: Storage | null;
+
     /** Rendered inside the host's providers, after the application. */
     children?: ReactNode;
 }
@@ -61,7 +85,7 @@ export interface ApplicationHostProps {
  * button or a dialog destination opened shown over it - one place for all of it (spec PRV9), so a behaviour that differs between
  * the two hosts is a bug in the host, not a second implementation.
  */
-export function ApplicationHost({ application, composition = {}, navigationModel, registry: hostRegistry, initialScreen, history, resolveBinding, queryResults, renderScreen, renderDialog, children }: ApplicationHostProps) {
+export function ApplicationHost({ application, composition = {}, navigationModel, registry: hostRegistry, initialScreen, history, resolveBinding, queryResults, renderScreen, renderDialog, renderDialogTemplate, scope, layoutConfigStorage = null, children }: ApplicationHostProps) {
     const [memoryHistory] = useState(() => createMemorySceneHistory());
     const registry = useMemo(() => ({ ...previewComponents, ...hostRegistry }), [hostRegistry]);
     const hostHistory = history ?? memoryHistory;
@@ -86,25 +110,37 @@ export function ApplicationHost({ application, composition = {}, navigationModel
     const sliceDialog = !dialogTemplate && navigation.currentDialog && sliceDialogParameters(navigation.currentDialogParameters) !== undefined;
     const dialogName = sliceDialogParameters(navigation.currentDialogParameters)?.title ?? navigation.currentDialog;
 
-    const drawn = composed
-        ? renderScreen?.(composed.element, composed.configuration, navigation)
-            ?? <SceneElementView element={composed.element} registry={registry} resolveBinding={resolveBinding} queryResults={queryResults} configuration={composed.configuration} />
-        : null;
+    const dialogContent = dialogTemplate ? composeDialog(application, dialogTemplate, composition) : undefined;
+
+    const body = (
+        <>
+            <div data-scene-outlet='primary' data-scene-url={navigation.currentUrl} data-scene-screen={navigation.primaryScreen}>
+                {composed && <Drawn>{renderScreen
+                    ? () => renderScreen(composed.element, composed.configuration, navigation)
+                    : () => <SceneElementView element={composed.element} registry={registry} resolveBinding={resolveBinding} queryResults={queryResults} configuration={composed.configuration} />}</Drawn>}
+            </div>
+            {dialogTemplate && dialogContent && (renderDialogTemplate
+                ? <Drawn>{() => renderDialogTemplate(dialogTemplate, dialogContent, navigation)}</Drawn>
+                : (
+                    <div role='dialog' aria-modal='true' aria-label={dialogName} data-scene-dialog={navigation.currentDialog}>
+                        <SceneElementView element={dialogContent} registry={registry} resolveBinding={resolveBinding} queryResults={queryResults} />
+                    </div>
+                ))}
+            {sliceDialog && (
+                <div role='dialog' aria-modal='true' aria-label={dialogName} data-scene-dialog={navigation.currentDialog}>
+                    {renderDialog?.(navigation) ?? <SliceDialogView />}
+                </div>
+            )}
+        </>
+    );
 
     return (
         <SceneNavigationProvider value={navigation}>
             <SceneOutletContext.Provider value={outletContext}>
                 <SceneNavigationModelProvider model={navigationModel}>
-                    {/* The shell reads its layout configuration from a provider; nothing is saved from a hosted application's own. */}
-                    <LayoutConfigProvider storage={null}>
-                        <div data-scene-outlet='primary' data-scene-url={navigation.currentUrl} data-scene-screen={navigation.primaryScreen}>{drawn}</div>
-                        {(dialogTemplate || sliceDialog) && (
-                            <div role='dialog' aria-modal='true' aria-label={dialogName} data-scene-dialog={navigation.currentDialog}>
-                                {dialogTemplate
-                                    ? <SceneElementView element={composeDialog(application, dialogTemplate, composition)} registry={registry} resolveBinding={resolveBinding} queryResults={queryResults} />
-                                    : renderDialog?.(navigation) ?? <SliceDialogView />}
-                            </div>
-                        )}
+                    {/* The shell reads its layout configuration from a provider; nothing is saved unless the host gives it somewhere to. */}
+                    <LayoutConfigProvider storage={layoutConfigStorage}>
+                        {scope ? scope(navigation, body) : body}
                         {children}
                     </LayoutConfigProvider>
                 </SceneNavigationModelProvider>
@@ -112,3 +148,8 @@ export function ApplicationHost({ application, composition = {}, navigationModel
         </SceneNavigationProvider>
     );
 }
+
+/** Calls what a host draws as part of this component, so a hook it uses runs under the providers the host put in scope. */
+function Drawn({ children }: { children(): ReactNode }) {
+    return <>{children()}</>;
+}

package/shell/layout.css

@@ -1607,3 +1607,237 @@
         grid-row: 1;
     }
 }
+
+/* Checklist. */
+.foundation-checklist {
+    display: flex;
+    flex-direction: column;
+    gap: var(--foundation-space-4);
+    padding: var(--foundation-space-4);
+    border: 1px solid var(--foundation-border);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-surface);
+}
+
+.foundation-checklist-header {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: var(--foundation-space-2);
+}
+
+.foundation-checklist-header h3 {
+    margin: 0;
+    font-size: 1rem;
+}
+
+.foundation-progress {
+    overflow: hidden;
+    block-size: 0.5rem;
+    margin-block: var(--foundation-space-2);
+    border-radius: 999px;
+    background: var(--foundation-hover);
+    border: 1px solid var(--foundation-border);
+}
+
+.foundation-progress-bar {
+    display: block;
+    block-size: 100%;
+    background: var(--foundation-primary);
+}
+
+.foundation-checklist-items {
+    display: flex;
+    flex-direction: column;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.foundation-checklist-item {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--foundation-space-1) var(--foundation-space-4);
+    min-block-size: var(--foundation-row-height);
+    border-block-end: 1px solid var(--foundation-border);
+}
+
+.foundation-checklist-item[data-done='true'] .foundation-checklist-label {
+    color: var(--foundation-muted);
+    text-decoration: line-through;
+}
+
+.foundation-checklist-meta {
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: var(--foundation-space-1) var(--foundation-space-4);
+    color: var(--foundation-muted);
+    font-size: 0.875rem;
+}
+
+.foundation-overdue {
+    color: var(--foundation-danger);
+}
+
+/* Activity feed. */
+.foundation-activity-feed {
+    padding: var(--foundation-space-4);
+    border: 1px solid var(--foundation-border);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-surface);
+}
+
+.foundation-activity-heading {
+    margin: var(--foundation-space-3) 0;
+    color: var(--foundation-muted);
+    font-size: 0.875rem;
+    font-weight: 600;
+}
+
+.foundation-activity-list {
+    display: flex;
+    flex-direction: column;
+    gap: var(--foundation-space-3);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.foundation-activity-entry {
+    display: flex;
+    gap: var(--foundation-space-3);
+}
+
+.foundation-activity-icon {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: 2rem;
+    block-size: 2rem;
+    border-radius: 50%;
+    background: var(--foundation-highlight);
+    color: var(--foundation-highlight-text);
+}
+
+.foundation-activity-content {
+    display: flex;
+    flex-direction: column;
+    gap: var(--foundation-space-1);
+    min-inline-size: 0;
+}
+
+.foundation-activity-summary,
+.foundation-activity-body {
+    margin: 0;
+    overflow-wrap: anywhere;
+}
+
+.foundation-activity-body {
+    padding: var(--foundation-space-2) var(--foundation-space-3);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-background);
+}
+
+/* Avatar stack. */
+.foundation-avatars {
+    display: inline-flex;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.foundation-avatar {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+    inline-size: 2.5rem;
+    block-size: 2.5rem;
+    border: 2px solid var(--foundation-surface);
+    border-radius: 50%;
+    background: var(--foundation-highlight);
+    color: var(--foundation-highlight-text);
+    font-size: 0.875rem;
+    font-weight: 700;
+}
+
+.foundation-avatar + .foundation-avatar {
+    margin-inline-start: calc(var(--foundation-space-3) * -1);
+}
+
+.foundation-avatar img {
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+}
+
+.foundation-avatar-more {
+    background: var(--foundation-hover);
+    color: var(--foundation-text);
+}
+
+.foundation-avatars[data-size='small'] .foundation-avatar {
+    inline-size: 1.75rem;
+    block-size: 1.75rem;
+    font-size: 0.75rem;
+}
+
+/* File uploader. */
+.foundation-file-uploader {
+    display: flex;
+    flex-direction: column;
+    gap: var(--foundation-space-3);
+}
+
+.foundation-dropzone {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--foundation-space-2);
+    padding: var(--foundation-space-6);
+    border: 2px dashed var(--foundation-border);
+    border-radius: var(--foundation-radius);
+    background: var(--foundation-surface);
+    text-align: center;
+}
+
+.foundation-dropzone[data-dragging='true'] {
+    border-color: var(--foundation-primary);
+    background: var(--foundation-highlight);
+}
+
+.foundation-upload-problems {
+    color: var(--foundation-danger);
+}
+
+.foundation-upload-list {
+    display: flex;
+    flex-direction: column;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.foundation-upload-item {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--foundation-space-2);
+    min-block-size: var(--foundation-row-height);
+    border-block-end: 1px solid var(--foundation-border);
+}
+
+.foundation-upload-name {
+    flex: 1;
+    min-inline-size: 0;
+    overflow-wrap: anywhere;
+}
+
+.foundation-upload-item[data-status='failed'] .foundation-upload-status {
+    color: var(--foundation-danger);
+    font-weight: 600;
+}