@cratis/scene.blueprint.default 4.35.0 → 4.37.0

package/foundation/ActivityFeed.tsx

@@ -0,0 +1,61 @@
+// 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 { RegisteredComponentProps } from '@cratis/scene.react';
+import { readOptionalString } from '../shell/elementProperties';
+import { ActivityKind, groupByDay, readActivity } from './activityModel';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon, FoundationIconName } from './FoundationIcon';
+import { formatDate, formatDay, readLocale } from './formatting';
+import { readFoundationStrings } from './foundationStrings';
+import { FoundationFrame } from './StateFrame';
+
+const icons: Record<ActivityKind, FoundationIconName> = {
+    [ActivityKind.Comment]: 'user', [ActivityKind.Change]: 'refresh', [ActivityKind.Status]: 'check', [ActivityKind.System]: 'info',
+};
+
+/**
+ * The `activityFeed` component: what happened to a record, newest first, under a heading for each day.
+ *
+ * `entries` carry an id, who (`actor`), what (`action`), the instant (`at`, ISO 8601), a `kind` and an optional `body` such as a comment's
+ * text. The feed is an ordered list; each entry names its kind in words for assistive technology as well as by icon, and its time is a
+ * `time` element formatted for the locale. Content is supplied by the application - this only lays it out - and a feed of any length
+ * stays one list. `order="ascending"` reads oldest first, and `timeZone` fixes the zone days are cut in.
+ */
+export function ActivityFeed({ element, interactions }: RegisteredComponentProps) {
+    const entries = useMemo(() => readActivity(element.properties.entries), [element.properties.entries]);
+    const strings = readFoundationStrings(element);
+    const locale = readLocale(element);
+    const timeZone = readOptionalString(element, 'timeZone');
+    const days = useMemo(() => groupByDay(entries, element.properties.order === 'ascending', timeZone), [entries, element.properties.order, timeZone]);
+    const state = readComponentState(element, entries.length > 0);
+    const kindText: Record<ActivityKind, string> = { comment: strings.activityComment, change: strings.activityChange, status: strings.activityStatus, system: strings.activitySystem };
+    const emptyElement = state === ComponentState.Empty ? { ...element, properties: { emptyHeadline: strings.activityEmpty, ...element.properties } } : element;
+
+    return (
+        <FoundationFrame element={emptyElement} interactions={interactions} name='activity-feed' state={state} skeleton={[60, 90, 70, 85]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && days.map(day => (
+                <section key={day.day} className='foundation-activity-day'>
+                    <h3 className='foundation-activity-heading'><time dateTime={day.day}>{formatDay(day.day, locale)}</time></h3>
+                    <ol className='foundation-activity-list'>
+                        {day.entries.map(entry => (
+                            <li key={entry.id} className='foundation-activity-entry' data-kind={entry.kind}>
+                                <span className='foundation-activity-icon'><FoundationIcon name={icons[entry.kind]} /></span>
+                                <div className='foundation-activity-content'>
+                                    <p className='foundation-activity-summary'>
+                                        <span className='foundation-visually-hidden'>{`${kindText[entry.kind]}: `}</span>
+                                        <strong>{entry.actor}</strong> {entry.action}
+                                    </p>
+                                    {entry.body && <p className='foundation-activity-body'>{entry.body}</p>}
+                                    <time className='foundation-count' dateTime={entry.at}>{formatDate(entry.at, locale, true)}</time>
+                                </div>
+                            </li>
+                        ))}
+                    </ol>
+                </section>
+            ))}
+        </FoundationFrame>
+    );
+}
+

package/foundation/ApprovalChainStepper.tsx

@@ -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.
+
+import { useMemo } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { ApprovalState, ChainOutcome, chainOutcome, effectiveSteps, readSteps } from './approvalModel';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon, FoundationIconName } from './FoundationIcon';
+import { formatDate, readLocale } from './formatting';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { FoundationFrame } from './StateFrame';
+
+const icons: Record<ApprovalState, FoundationIconName> = {
+    [ApprovalState.Pending]: 'circle', [ApprovalState.Current]: 'clock', [ApprovalState.Approved]: 'check', [ApprovalState.Rejected]: 'close', [ApprovalState.Skipped]: 'minus',
+};
+const tones: Record<ApprovalState, string> = {
+    [ApprovalState.Pending]: 'neutral', [ApprovalState.Current]: 'info', [ApprovalState.Approved]: 'success', [ApprovalState.Rejected]: 'danger', [ApprovalState.Skipped]: 'neutral',
+};
+
+/**
+ * The `approvalChainStepper` component: the steps a request goes through, who decides each, and where it stands.
+ *
+ * `steps` are written in order with a `label`, an `approver`, a `state` (pending, current, approved, rejected, skipped), and when it was
+ * decided (`at`) and a `comment`. The chain applies its own rules - a rejection stops the chain and the steps after it read "Not reached", and
+ * with no current step the first undecided one is it - so a request page needs no logic of its own. Every step says its state in words as
+ * well as by icon and color, the current step carries `aria-current="step"`, and the whole is an ordered list with the overall outcome
+ * stated above it. `orientation` is `horizontal` or `vertical`; below a phone's width it is always vertical.
+ */
+export function ApprovalChainStepper({ element, interactions }: RegisteredComponentProps) {
+    const written = useMemo(() => readSteps(element.properties.steps), [element.properties.steps]);
+    const steps = useMemo(() => effectiveSteps(written), [written]);
+    const outcome = chainOutcome(written);
+    const strings = readFoundationStrings(element);
+    const locale = readLocale(element);
+    const state = readComponentState(element, written.length > 0);
+    const stateText: Record<ApprovalState, string> = {
+        pending: strings.approvalPending, current: strings.approvalCurrent, approved: strings.approvalApproved, rejected: strings.approvalRejected, skipped: strings.approvalSkipped,
+    };
+    const outcomeText: Record<ChainOutcome, string> = {
+        approved: strings.approvalOutcomeApproved, rejected: strings.approvalOutcomeRejected, inProgress: strings.approvalOutcomeInProgress, pending: strings.approvalOutcomePending,
+    };
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='approval-chain' state={state} skeleton={[100, 100]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && (
+                <>
+                    <p className='foundation-approval-outcome' data-outcome={outcome}>{outcomeText[outcome]}</p>
+                    <ol className='foundation-approval-steps' aria-label={strings.approvalChain} data-orientation={element.properties.orientation === 'vertical' ? 'vertical' : 'horizontal'}>
+                        {steps.map((step, index) => (
+                            <li key={step.label + index} className='foundation-approval-step' data-state={step.state} aria-current={step.state === ApprovalState.Current ? 'step' : undefined}>
+                                <span className='foundation-chip' data-tone={tones[step.state]}><FoundationIcon name={icons[step.state]} /><span>{step.notReached ? strings.approvalNotReached : stateText[step.state]}</span></span>
+                                <strong className='foundation-approval-label'>
+                                    <span className='foundation-visually-hidden'>{`${formatText(strings.approvalStep, { n: index + 1, total: steps.length })}: `}</span>
+                                    {step.label}
+                                </strong>
+                                {step.approver && <span className='foundation-count'>{step.approver}</span>}
+                                {step.at && <time className='foundation-count' dateTime={step.at}>{formatDate(step.at, locale, true)}</time>}
+                                {step.comment && <span className='foundation-approval-comment'>{step.comment}</span>}
+                            </li>
+                        ))}
+                    </ol>
+                </>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/AvatarStack.tsx

@@ -0,0 +1,43 @@
+// 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 { RegisteredComponentProps } from '@cratis/scene.react';
+import { initialsOf, readPeople, visiblePeople } from './avatarModel';
+import { ComponentState, readComponentState } from './ComponentState';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { FoundationFrame } from './StateFrame';
+
+/**
+ * The `avatarStack` component: overlapping avatars for the people on a record, with a "+N" chip for the rest.
+ *
+ * `people` are names with an optional picture; without one the avatar shows the person's initials. The stack is a labelled group ("5 people"),
+ * each avatar is an image named after its person, and the overflow chip says how many more in words. `max` is how many are shown (4 by
+ * default) and `size` is `small` or `medium`.
+ */
+export function AvatarStack({ element, interactions }: RegisteredComponentProps) {
+    const people = useMemo(() => readPeople(element.properties.people), [element.properties.people]);
+    const strings = readFoundationStrings(element);
+    const { shown, hidden } = visiblePeople(people, typeof element.properties.max === 'number' ? element.properties.max : 4);
+    const state = readComponentState(element, people.length > 0);
+    const size = element.properties.size === 'small' ? 'small' : 'medium';
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='avatar-stack' state={state} skeleton={[35]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && (
+                <ul className='foundation-avatars' role='group' aria-label={formatText(strings.avatarPeople, { count: people.length })} data-size={size}>
+                    {shown.map(person => (
+                        <li key={person.name} className='foundation-avatar' role='img' aria-label={person.name} title={person.name}>
+                            {person.imageUrl ? <img src={person.imageUrl} alt='' /> : <span aria-hidden='true'>{initialsOf(person.name)}</span>}
+                        </li>
+                    ))}
+                    {hidden > 0 && (
+                        <li className='foundation-avatar foundation-avatar-more' role='img' aria-label={formatText(strings.avatarOverflow, { count: hidden })}>
+                            <span aria-hidden='true'>+{hidden}</span>
+                        </li>
+                    )}
+                </ul>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/ChecklistSection.tsx

@@ -0,0 +1,80 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useMemo, useState } from 'react';
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { ChecklistGroup, completed, doneTaskIds, isOverdue, readChecklist, toggleTask } from './checklistModel';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon } from './FoundationIcon';
+import { formatDate, readLocale } from './formatting';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { readPermissionRule } from './PermissionRule';
+import { FoundationFrame } from './StateFrame';
+
+/**
+ * The `checklistSection` component: sections of tasks, each with its owner and due date, and a progress bar per section.
+ *
+ * `sections` give the structure (`title`, and `items` with `id`, `label`, `owner`, `due`, `done`). Ticking a task publishes the ids of all
+ * done tasks as the `value` output and runs the behaviors attached to the element. An open task past its due date says "Overdue" in
+ * words as well as in color. Progress is a labelled progress bar, so "2 of 5 complete" is read, not just seen. With `editPermission`
+ * not enabled the tasks are shown and cannot be changed.
+ */
+export function ChecklistSection({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const supplied = useMemo(() => readChecklist(element.properties.sections), [element.properties.sections]);
+    const suppliedKey = JSON.stringify(supplied);
+    const [groups, setGroups] = useState<ChecklistGroup[]>(supplied);
+    const strings = readFoundationStrings(element);
+    const locale = readLocale(element);
+    const state = readComponentState(element, supplied.some(group => group.items.length > 0));
+    const locked = readPermissionRule(element, 'editPermission') !== 'enabled';
+    const now = useMemo(() => (typeof element.properties.today === 'string' ? new Date(element.properties.today) : new Date()), [element.properties.today]);
+
+    useEffect(() => setGroups(supplied), [suppliedKey]);
+    useValueOutput(bindingOutputs, doneTaskIds(groups));
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='checklist' state={state} skeleton={[40, 100, 90, 95]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && groups.map((group, groupIndex) => {
+                const done = completed(group);
+                const total = group.items.length;
+                return (
+                    <section key={group.title + groupIndex} className='foundation-checklist-group' aria-labelledby={`${element.id}-group-${groupIndex}`}>
+                        <header className='foundation-checklist-header'>
+                            <h3 id={`${element.id}-group-${groupIndex}`}>{group.title}</h3>
+                            <span className='foundation-count'>{formatText(strings.checklistProgress, { done, total })}</span>
+                        </header>
+                        <div className='foundation-progress' role='progressbar' aria-label={formatText(strings.checklistItemProgress, { title: group.title })}
+                            aria-valuemin={0} aria-valuemax={total} aria-valuenow={done} aria-valuetext={formatText(strings.checklistProgress, { done, total })}>
+                            <span className='foundation-progress-bar' style={{ inlineSize: total === 0 ? '0%' : `${(done / total) * 100}%` }} />
+                        </div>
+                        {total === 0 ? <p className='foundation-count'>{strings.checklistNone}</p> : (
+                            <ul className='foundation-checklist-items'>
+                                {group.items.map(item => {
+                                    const overdue = isOverdue(item, now);
+                                    return (
+                                        <li key={item.id} className='foundation-checklist-item' data-done={item.done} data-overdue={overdue}>
+                                            <label className='foundation-check'>
+                                                <input type='checkbox' checked={item.done} disabled={locked} onChange={() => { setGroups(toggleTask(groups, item.id)); interactions?.onChange?.(); }} />
+                                                <span className='foundation-checklist-label'>{item.label}</span>
+                                            </label>
+                                            <span className='foundation-checklist-meta'>
+                                                {item.owner && <span><span className='foundation-visually-hidden'>{`${strings.checklistOwner}: `}</span><FoundationIcon name='user' /> {item.owner}</span>}
+                                                {item.due && (
+                                                    <span>
+                                                        <span className='foundation-visually-hidden'>{`${strings.checklistDue}: `}</span>
+                                                        <time dateTime={item.due}>{formatDate(item.due, locale)}</time>
+                                                        {overdue && <strong className='foundation-overdue'> · <FoundationIcon name='alert' /> {strings.checklistOverdue}</strong>}
+                                                    </span>
+                                                )}
+                                            </span>
+                                        </li>
+                                    );
+                                })}
+                            </ul>
+                        )}
+                    </section>
+                );
+            })}
+        </FoundationFrame>
+    );
+}

package/foundation/FileUploader.tsx

@@ -0,0 +1,122 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ChangeEvent, DragEvent, useRef, useState } from 'react';
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { readOptionalString } from '../shell/elementProperties';
+import { ActionButton } from './ActionButton';
+import { ComponentState, readComponentState } from './ComponentState';
+import { useFileUploaderHandler } from './FileUploaderHandler';
+import { FoundationIcon } from './FoundationIcon';
+import { readLocale } from './formatting';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { readPermissionRule } from './PermissionRule';
+import { FoundationFrame } from './StateFrame';
+import { UploadRefusal, UploadStatus, checkSelection, formatBytes } from './uploadModel';
+
+interface Entry {
+    file: File;
+    status: UploadStatus;
+}
+
+/**
+ * The `fileUploader` component: a drop zone and a button to choose files, checked against type and size before anything is sent.
+ *
+ * `accept` is an `accept` list, `maxSizeMb` the largest file, and `multiple` whether more than one is allowed. The zone is a real file
+ * input behind a labelled button, so it works from the keyboard and with a screen reader; dropping onto it does the same as choosing.
+ * Refusals are announced with their reason. Accepted files are listed with a remove button and a status in words; the selection
+ * (name, size, type) is published as the `value` output. With a `FileUploaderHandlerProvider` in scope the files are sent through it and
+ * marked uploading, done or failed; without one the component only collects. `actionPermission` gates choosing files.
+ */
+export function FileUploader({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const strings = readFoundationStrings(element);
+    const locale = readLocale(element);
+    const handler = useFileUploaderHandler();
+    const [entries, setEntries] = useState<Entry[]>([]);
+    const [problems, setProblems] = useState<string[]>([]);
+    const [dragging, setDragging] = useState(false);
+    const input = useRef<HTMLInputElement>(null);
+    const accept = readOptionalString(element, 'accept') ?? '';
+    const maximumBytes = (typeof element.properties.maxSizeMb === 'number' ? element.properties.maxSizeMb : 0) * 1024 * 1024;
+    const multiple = element.properties.multiple !== false;
+    const rule = readPermissionRule(element, 'actionPermission');
+    const state = readComponentState(element, true);
+    const serverUrl = readOptionalString(element, 'serverUrl');
+
+    useValueOutput(bindingOutputs, entries.map(entry => ({ name: entry.file.name, size: entry.file.size, type: entry.file.type, status: entry.status })));
+
+    const send = async (files: File[]) => {
+        if (!handler) return;
+        const mark = (status: UploadStatus) => setEntries(current => current.map(entry => (files.includes(entry.file) ? { ...entry, status } : entry)));
+        mark(UploadStatus.Uploading);
+        try {
+            await handler(files, serverUrl);
+            mark(UploadStatus.Done);
+        } catch {
+            mark(UploadStatus.Failed);
+        }
+    };
+
+    const take = (chosen: File[]) => {
+        const { accepted, refused } = checkSelection(chosen, { accept, maximumBytes, multiple }, entries.length);
+        setProblems(refused.map(({ file, reason }) => reason === UploadRefusal.WrongType ? formatText(strings.uploadWrongType, { name: file.name })
+            : reason === UploadRefusal.TooLarge ? formatText(strings.uploadTooLarge, { name: file.name, limit: formatBytes(maximumBytes, locale) }) : strings.uploadSingle));
+        if (accepted.length === 0) return;
+
+        setEntries(current => [...current, ...accepted.map(file => ({ file, status: UploadStatus.Queued }))]);
+        interactions?.onChange?.();
+        void send(accepted);
+    };
+
+    const choose = (event: ChangeEvent<HTMLInputElement>) => {
+        take(Array.from(event.target.files ?? []));
+        event.target.value = '';
+    };
+    const drop = (event: DragEvent) => {
+        event.preventDefault();
+        setDragging(false);
+        if (rule === 'enabled') take(Array.from(event.dataTransfer.files));
+    };
+    const statusText: Record<UploadStatus, string> = {
+        queued: strings.uploadQueued, uploading: strings.uploadUploading, done: strings.uploadDone, failed: strings.uploadFailed,
+    };
+    const limits = [accept ? formatText(strings.uploadAccepts, { types: accept }) : '', maximumBytes > 0 ? formatText(strings.uploadLimits, { limit: formatBytes(maximumBytes, locale) }) : ''].filter(Boolean).join(' · ');
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='file-uploader' state={state} skeleton={[100, 40]}>
+            {state !== ComponentState.Loading && (
+                <>
+                    <div className='foundation-dropzone' data-dragging={dragging} onDragOver={event => { event.preventDefault(); setDragging(true); }} onDragLeave={() => setDragging(false)} onDrop={drop}>
+                        <FoundationIcon name='upload' />
+                        <span>{strings.uploadDrop}</span>
+                        <input ref={input} className='foundation-visually-hidden' type='file' tabIndex={-1} accept={accept || undefined} multiple={multiple} disabled={rule !== 'enabled'} onChange={choose} aria-hidden='true' />
+                        <ActionButton rule={rule} emphasis='secondary' disabledReason={strings.disabledNoPermission} onClick={() => input.current?.click()}>
+                            {strings.uploadBrowse}
+                        </ActionButton>
+                        {limits && <span className='foundation-count'>{limits}</span>}
+                    </div>
+                    <div aria-live='polite' className='foundation-upload-problems'>
+                        {problems.map(problem => <p key={problem} className='foundation-message-text' data-tone='danger'>{problem}</p>)}
+                    </div>
+                    {entries.length > 0 && (
+                        <ul className='foundation-upload-list' aria-label={strings.uploadSelected}>
+                            {entries.map((entry, index) => (
+                                <li key={entry.file.name + index} className='foundation-upload-item' data-status={entry.status}>
+                                    <FoundationIcon name='file' />
+                                    <span className='foundation-upload-name'>{entry.file.name}</span>
+                                    <span className='foundation-count'>{formatBytes(entry.file.size, locale)}</span>
+                                    <span className='foundation-upload-status'>{statusText[entry.status]}</span>
+                                    {entry.status === UploadStatus.Failed && <button type='button' className='foundation-link' onClick={() => void send([entry.file])}>{strings.retry}</button>}
+                                    <button type='button' className='foundation-icon-button' aria-label={formatText(strings.uploadRemove, { name: entry.file.name })}
+                                        onClick={() => { setEntries(current => current.filter(existing => existing !== entry)); interactions?.onChange?.(); }}>
+                                        <FoundationIcon name='close' />
+                                    </button>
+                                </li>
+                            ))}
+                        </ul>
+                    )}
+                </>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/FileUploaderHandler.tsx

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, createContext, useContext } from 'react';
+
+/**
+ * What sends the accepted files somewhere: a host's server client, kept out of the portable package.
+ *
+ * The signature is the one `@cratis/scene.primereact` uses for its `fileUpload`, so a host hands the same function to both. A handler that
+ * rejects marks the files as failed, with a retry; without a handler the uploader only collects and publishes the selection.
+ */
+export type FileUploaderHandler = (files: File[], serverUrl?: string) => Promise<void>;
+
+const Context = createContext<FileUploaderHandler | undefined>(undefined);
+
+/** Provides the upload handler to the file uploaders below it. */
+export function FileUploaderHandlerProvider({ handler, children }: { handler?: FileUploaderHandler; children: ReactNode }) {
+    return <Context.Provider value={handler}>{children}</Context.Provider>;
+}
+
+/** The handler in scope, if any. */
+export const useFileUploaderHandler = (): FileUploaderHandler | undefined => useContext(Context);

package/foundation/Foundation.stories.tsx

@@ -44,3 +44,19 @@ export const ColumnChooserLight: Story = { args: { component: ComponentName.Colu
 export const ColumnChooserDark: Story = { args: { component: ComponentName.ColumnChooser, theme: 'dark' } };
 export const SavedViewsMenuLight: Story = { args: { component: ComponentName.SavedViewsMenu, theme: 'light' } };
 export const SavedViewsMenuDark: Story = { args: { component: ComponentName.SavedViewsMenu, theme: 'dark' } };
+export const ChecklistLight: Story = { args: { component: ComponentName.ChecklistSection, theme: 'light' } };
+export const ChecklistDark: Story = { args: { component: ComponentName.ChecklistSection, theme: 'dark' } };
+export const ActivityFeedLight: Story = { args: { component: ComponentName.ActivityFeed, theme: 'light' } };
+export const ActivityFeedDark: Story = { args: { component: ComponentName.ActivityFeed, theme: 'dark' } };
+export const AvatarStackLight: Story = { args: { component: ComponentName.AvatarStack, theme: 'light' } };
+export const AvatarStackDark: Story = { args: { component: ComponentName.AvatarStack, theme: 'dark' } };
+export const FileUploaderLight: Story = { args: { component: ComponentName.FileUploader, theme: 'light' } };
+export const FileUploaderDark: Story = { args: { component: ComponentName.FileUploader, theme: 'dark' } };
+export const ApprovalChainLight: Story = { args: { component: ComponentName.ApprovalChainStepper, theme: 'light' } };
+export const ApprovalChainDark: Story = { args: { component: ComponentName.ApprovalChainStepper, theme: 'dark' } };
+export const OrgTreeLight: Story = { args: { component: ComponentName.OrgTree, theme: 'light' } };
+export const OrgTreeDark: Story = { args: { component: ComponentName.OrgTree, theme: 'dark' } };
+export const PermissionMatrixLight: Story = { args: { component: ComponentName.PermissionMatrix, theme: 'light' } };
+export const PermissionMatrixDark: Story = { args: { component: ComponentName.PermissionMatrix, theme: 'dark' } };
+export const ApprovalChainRejectedLight: Story = { args: { component: ComponentName.ApprovalChainStepper, theme: 'light', properties: { steps: [{ label: 'Team lead', state: 'approved' }, { label: 'Finance', state: 'rejected', comment: 'Over budget.' }, { label: 'Director' }] } } };
+export const PermissionMatrixReadOnlyDark: Story = { args: { component: ComponentName.PermissionMatrix, theme: 'dark', properties: { editPermission: 'disabled' } } };

package/foundation/OrgTree.tsx

@@ -0,0 +1,101 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { KeyboardEvent, useEffect, useMemo, useState } from 'react';
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon } from './FoundationIcon';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { descendantCount, expandedToDepth, OrgTreeNode, buildOrgTree, placements, readOrgNodes, visibleNodes } from './orgModel';
+import { FoundationFrame } from './StateFrame';
+
+/**
+ * The `orgTree` component: an organization as an expandable tree of people and units.
+ *
+ * `nodes` are flat rows - `id`, `label`, `title`, `parentId` - as a query returns them; the tree is built from them, so someone whose manager is
+ * missing becomes a root and a reporting cycle is cut instead of looping. It follows the ARIA tree pattern: one tab stop, Up and Down move,
+ * Right expands or enters, Left collapses or goes to the parent, Home and End jump, Enter or Space selects. Each item says how many reports it
+ * has in words. The selected id is published as the `value` output; `expandedDepth` is how many levels are open at first.
+ */
+export function OrgTree({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const nodes = useMemo(() => readOrgNodes(element.properties.nodes), [element.properties.nodes]);
+    const roots = useMemo(() => buildOrgTree(nodes), [nodes]);
+    const depth = typeof element.properties.expandedDepth === 'number' ? element.properties.expandedDepth : 2;
+    const initial = useMemo(() => expandedToDepth(roots, depth), [roots, depth]);
+    const [expanded, setExpanded] = useState<Set<string>>(initial);
+    const [selected, setSelected] = useState<string | undefined>(typeof element.properties.selected === 'string' ? element.properties.selected : undefined);
+    const [focused, setFocused] = useState<string | undefined>(undefined);
+    const strings = readFoundationStrings(element);
+    const state = readComponentState(element, nodes.length > 0);
+    const visible = visibleNodes(roots, expanded);
+    const placed = useMemo(() => placements(roots), [roots]);
+    const tabStop = visible.find(node => node.id === focused)?.id ?? visible.find(node => node.id === selected)?.id ?? visible[0]?.id;
+    const emptyElement = state === ComponentState.Empty ? { ...element, properties: { emptyHeadline: strings.orgNone, ...element.properties } } : element;
+
+    useEffect(() => setExpanded(initial), [initial]);
+    useValueOutput(bindingOutputs, selected);
+
+    const move = (node: OrgTreeNode, event: KeyboardEvent) => {
+        const index = visible.indexOf(node);
+        const focus = (target: OrgTreeNode | undefined) => {
+            if (!target) return;
+            event.preventDefault();
+            setFocused(target.id);
+            requestAnimationFrame(() => document.getElementById(`${element.id}-${target.id}`)?.focus());
+        };
+        const toggle = (open: boolean) => setExpanded(current => { const next = new Set(current); if (open) next.add(node.id); else next.delete(node.id); return next; });
+        const parent = placed.get(node.id)?.parent;
+
+        switch (event.key) {
+            case 'ArrowDown': focus(visible[index + 1]); break;
+            case 'ArrowUp': focus(visible[index - 1]); break;
+            case 'Home': focus(visible[0]); break;
+            case 'End': focus(visible[visible.length - 1]); break;
+            case 'ArrowRight':
+                if (node.children.length > 0 && !expanded.has(node.id)) { event.preventDefault(); toggle(true); } else focus(node.children[0]);
+                break;
+            case 'ArrowLeft':
+                if (node.children.length > 0 && expanded.has(node.id)) { event.preventDefault(); toggle(false); } else focus(parent);
+                break;
+            case 'Enter':
+            case ' ':
+                event.preventDefault();
+                setSelected(node.id);
+                interactions?.onSelect?.();
+                break;
+            default: break;
+        }
+    };
+
+    return (
+        <FoundationFrame element={emptyElement} interactions={interactions} name='org-tree' state={state} skeleton={[50, 70, 70, 60]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && (
+                <ul role='tree' aria-label={strings.orgTree} className='foundation-tree'>
+                    {visible.map(node => {
+                        const siblings = placed.get(node.id)?.siblings ?? [node];
+                        const reports = descendantCount(node);
+                        const open = expanded.has(node.id);
+                        return (
+                            <li key={node.id} id={`${element.id}-${node.id}`} role='treeitem' tabIndex={node.id === tabStop ? 0 : -1} aria-level={node.depth}
+                                aria-setsize={siblings.length} aria-posinset={siblings.findIndex(sibling => sibling.id === node.id) + 1} aria-expanded={node.children.length > 0 ? open : undefined} aria-selected={node.id === selected}
+                                className='foundation-tree-item' data-selected={node.id === selected} style={{ paddingInlineStart: `calc(var(--foundation-space-4) * ${node.depth - 1})` }}
+                                onKeyDown={event => move(node, event)} onFocus={() => setFocused(node.id)} onClick={() => { setSelected(node.id); interactions?.onSelect?.(); }}>
+                                {node.children.length > 0 ? (
+                                    <button type='button' tabIndex={-1} className='foundation-icon-button' aria-hidden='true'
+                                        onClick={event => { event.stopPropagation(); setExpanded(current => { const next = new Set(current); if (open) next.delete(node.id); else next.add(node.id); return next; }); }}>
+                                        <FoundationIcon name={open ? 'chevron-down' : 'chevron-right'} />
+                                    </button>
+                                ) : <span className='foundation-tree-spacer' />}
+                                <span className='foundation-tree-text'>
+                                    <strong>{node.label}</strong>
+                                    {node.title && <span className='foundation-count'>{node.title}</span>}
+                                </span>
+                                {reports > 0 && <span className='foundation-count'>{formatText(strings.orgReports, { count: reports })}</span>}
+                            </li>
+                        );
+                    })}
+                </ul>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/PermissionMatrix.tsx

@@ -0,0 +1,82 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Fragment, useEffect, useMemo, useState } from 'react';
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon } from './FoundationIcon';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { isGranted, MatrixGrant, readGrants, readPermissions, readRoles, sectionsOf, setGrant } from './permissionModel';
+import { readPermissionRule } from './PermissionRule';
+import { FoundationFrame } from './StateFrame';
+
+/**
+ * The `permissionMatrix` component: roles across, permissions down, a checkbox where they meet.
+ *
+ * `roles` and `permissions` (optionally grouped) give the axes and `grants` - rows of `role` and `permission` - what is held; a grant of a role
+ * or permission that does not exist is ignored. Each box is named in words ("Grant Edit deals to Sales") and every header is a real header
+ * cell, so a screen reader announces the row and column of the box it is on. Changes are published as the `value` output - the grants,
+ * in the same shape - for the screen to save. With `editPermission` not enabled the matrix is read-only and each cell says "Allowed" or
+ * "Not allowed" in words and by icon. Wide matrices scroll sideways inside a keyboard-focusable region, keeping the permission column in view.
+ */
+export function PermissionMatrix({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const roles = useMemo(() => readRoles(element.properties.roles), [element.properties.roles]);
+    const permissions = useMemo(() => readPermissions(element.properties.permissions), [element.properties.permissions]);
+    const supplied = useMemo(() => readGrants(element.properties.grants, roles, permissions), [element.properties.grants, roles, permissions]);
+    const suppliedKey = JSON.stringify(supplied);
+    const [grants, setGrants] = useState<MatrixGrant[]>(supplied);
+    const strings = readFoundationStrings(element);
+    const state = readComponentState(element, roles.length > 0 && permissions.length > 0);
+    const readOnly = readPermissionRule(element, 'editPermission') !== 'enabled';
+    const sections = useMemo(() => sectionsOf(permissions), [permissions]);
+
+    useEffect(() => setGrants(supplied), [suppliedKey]);
+    useValueOutput(bindingOutputs, grants);
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='permission-matrix' state={state} skeleton={[100, 100, 100, 100]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && (
+                <div className='foundation-matrix-scroll' role='region' tabIndex={0} aria-label={strings.matrixScroll}>
+                    <table className='foundation-matrix'>
+                        <thead>
+                            <tr>
+                                <th scope='col'>{strings.matrixPermission}</th>
+                                {roles.map(role => <th key={role.id} scope='col'>{role.label}</th>)}
+                            </tr>
+                        </thead>
+                        <tbody>
+                            {sections.map((section, index) => (
+                                <Fragment key={section.group ?? `ungrouped-${index}`}>
+                                    {section.group && (
+                                        <tr className='foundation-matrix-group'><th scope='colgroup' colSpan={roles.length + 1}>{section.group}</th></tr>
+                                    )}
+                                    {section.permissions.map(permission => (
+                                        <tr key={permission.id}>
+                                            <th scope='row'>{permission.label}</th>
+                                            {roles.map(role => {
+                                                const granted = isGranted(grants, role.id, permission.id);
+                                                return (
+                                                    <td key={role.id} data-granted={granted}>
+                                                        {readOnly ? (
+                                                            <span className='foundation-matrix-state'>
+                                                                <FoundationIcon name={granted ? 'check' : 'minus'} />
+                                                                <span className='foundation-visually-hidden'>{granted ? strings.matrixAllowed : strings.matrixDenied}</span>
+                                                            </span>
+                                                        ) : (
+                                                            <input type='checkbox' checked={granted} aria-label={formatText(strings.matrixGrant, { permission: permission.label, role: role.label })}
+                                                                onChange={event => { setGrants(setGrant(grants, role.id, permission.id, event.target.checked)); interactions?.onChange?.(); }} />
+                                                        )}
+                                                    </td>
+                                                );
+                                            })}
+                                        </tr>
+                                    ))}
+                                </Fragment>
+                            ))}
+                        </tbody>
+                    </table>
+                </div>
+            )}
+        </FoundationFrame>
+    );
+}