@cratis/scene.blueprint.default 4.36.0 → 4.37.0

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

@@ -52,3 +52,11 @@ export const AvatarStackLight: Story = { args: { component: ComponentName.Avatar
 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>
+    );
+}

package/foundation/approvalModel.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Where one step of an approval chain stands. */
+export enum ApprovalState {
+    Pending = 'pending',
+    Current = 'current',
+    Approved = 'approved',
+    Rejected = 'rejected',
+    Skipped = 'skipped',
+}
+
+/** One step of an approval chain: who decides, and what they decided. */
+export interface ApprovalStep {
+    label: string;
+    approver?: string;
+    state: ApprovalState;
+    at?: string;
+    comment?: string;
+}
+
+/** A step as it is drawn, after the chain's own rules are applied. */
+export interface EffectiveStep extends ApprovalStep {
+    /** True when an earlier rejection stopped the chain before this step was reached. */
+    notReached: boolean;
+}
+
+/** How the chain as a whole stands. */
+export enum ChainOutcome {
+    /** Every step approved. */
+    Approved = 'approved',
+
+    /** A step rejected: the chain stops there. */
+    Rejected = 'rejected',
+
+    /** At least one step is decided and the rest are waiting. */
+    InProgress = 'inProgress',
+
+    /** Nothing decided yet. */
+    Pending = 'pending',
+}
+
+/** Reads steps out of a property value, dropping entries without a label; an unknown state is pending. */
+export function readSteps(value: unknown): ApprovalStep[] {
+    if (!Array.isArray(value)) return [];
+
+    return value.flatMap((entry): ApprovalStep[] => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return [];
+        const { label, approver, state, at, comment } = entry as Record<string, unknown>;
+        if (typeof label !== 'string' || label.length === 0) return [];
+
+        return [{
+            label,
+            state: (Object.values(ApprovalState) as string[]).includes(state as string) ? (state as ApprovalState) : ApprovalState.Pending,
+            ...(typeof approver === 'string' ? { approver } : {}),
+            ...(typeof at === 'string' ? { at } : {}),
+            ...(typeof comment === 'string' && comment.length > 0 ? { comment } : {}),
+        }];
+    });
+}
+
+/**
+ * Applies the chain's rules to the steps as written.
+ *
+ * A rejection stops the chain: every step after the first rejected one has not been reached, so it is drawn skipped however it was written.
+ * With no step marked current and no rejection, the first step that is not yet decided is the current one - the person the chain is waiting
+ * for - so a chain written only as approved and pending steps still says whose turn it is. Only one step is ever current.
+ */
+export function effectiveSteps(steps: ApprovalStep[]): EffectiveStep[] {
+    const rejected = steps.findIndex(step => step.state === ApprovalState.Rejected);
+    const explicitCurrent = steps.findIndex(step => step.state === ApprovalState.Current);
+    const waiting = rejected >= 0 ? -1 : explicitCurrent >= 0 ? explicitCurrent : steps.findIndex(step => step.state === ApprovalState.Pending);
+
+    return steps.map((step, index) => {
+        if (rejected >= 0 && index > rejected) return { ...step, state: ApprovalState.Skipped, notReached: true };
+        if (step.state === ApprovalState.Current && index !== waiting) return { ...step, state: ApprovalState.Pending, notReached: false };
+        if (index === waiting && step.state === ApprovalState.Pending) return { ...step, state: ApprovalState.Current, notReached: false };
+        return { ...step, notReached: false };
+    });
+}
+
+/** The state of the chain as a whole. A skipped step counts as decided, because it was never going to be asked. */
+export function chainOutcome(steps: ApprovalStep[]): ChainOutcome {
+    const effective = effectiveSteps(steps);
+    if (effective.some(step => step.state === ApprovalState.Rejected)) return ChainOutcome.Rejected;
+    if (effective.length > 0 && effective.every(step => step.state === ApprovalState.Approved || step.state === ApprovalState.Skipped)) return ChainOutcome.Approved;
+    return effective.some(step => step.state === ApprovalState.Approved) ? ChainOutcome.InProgress : ChainOutcome.Pending;
+}

package/foundation/foundationComponentMetadata.ts

@@ -22,4 +22,7 @@ export const foundationComponentMetadata: Record<string, ComponentMetadata> = {
     [ComponentName.ActivityFeed]: m('Activity feed', ComponentCategory.DataDisplay, 'activity', ['timeline', 'history', 'comments', 'audit', 'log']),
     [ComponentName.AvatarStack]: m('Avatar stack', ComponentCategory.DataDisplay, 'users', ['people', 'members', 'assignees', 'team']),
     [ComponentName.FileUploader]: m('File uploader', ComponentCategory.Input, 'upload', ['attachments', 'files', 'drop zone', 'documents']),
+    [ComponentName.ApprovalChainStepper]: m('Approval chain', ComponentCategory.Navigation, 'workflow', ['approvals', 'steps', 'workflow', 'sign off', 'stepper']),
+    [ComponentName.OrgTree]: m('Org tree', ComponentCategory.DataDisplay, 'network', ['organization', 'hierarchy', 'org chart', 'reports to', 'tree']),
+    [ComponentName.PermissionMatrix]: m('Permission matrix', ComponentCategory.Input, 'shield-check', ['roles', 'permissions', 'access', 'grants', 'rbac']),
 };

package/foundation/foundationDescriptors.ts

@@ -6,6 +6,7 @@ import { componentRegistryKey, valueOutputProperty } from '@cratis/scene.react';
 import { ComponentName } from '../ComponentName';
 import { defaultBlueprintName } from '../packageName';
 import { ActivityKind } from './activityModel';
+import { ApprovalState } from './approvalModel';
 import { ChartKind } from './chartGeometry';
 import { ComponentState } from './ComponentState';
 import { FilterFieldType } from './filterModel';
@@ -279,5 +280,78 @@ export const foundationDescriptors: ComponentDescriptor[] = [
             ...standardStateProperties.filter(property => property.path !== 'actionPermission'),
         ],
     },
+    {
+        component: key(ComponentName.ApprovalChainStepper),
+        displayName: 'Approval chain',
+        description: 'The steps a request goes through, who decides each and where it stands. A rejection stops the chain; the first undecided step is the current one.',
+        properties: [
+            {
+                ...list('steps', 'Steps', 'Data', 'Step', [
+                    text('label', 'Step', 'Content', undefined, { constraints: { required: true } }),
+                    text('approver', 'Approver', 'Data'),
+                    choice('state', 'State', 'Data', {
+                        [ApprovalState.Pending]: 'Pending', [ApprovalState.Current]: 'Awaiting decision', [ApprovalState.Approved]: 'Approved', [ApprovalState.Rejected]: 'Rejected', [ApprovalState.Skipped]: 'Skipped',
+                    }, ApprovalState.Pending),
+                    text('at', 'Decided at', 'Data', 'An ISO 8601 date and time.'),
+                    text('comment', 'Comment', 'Data'),
+                ], 'The approvers in order.'),
+                acceptedBindingKinds: bindable,
+            },
+            choice('orientation', 'Orientation', 'Appearance', { horizontal: 'Horizontal', vertical: 'Vertical' }, 'horizontal', 'A phone always reads vertically.'),
+            ...standardStateProperties,
+        ],
+    },
+    {
+        component: key(ComponentName.OrgTree),
+        displayName: 'Org tree',
+        description: 'An organization as an expandable tree built from rows of who reports to whom. Publishes the selected id as the value output.',
+        properties: [
+            {
+                ...list('nodes', 'People', 'Data', 'Person', [
+                    text('id', 'Id', 'Data', undefined, { constraints: { required: true }, editorKind: PropertyEditorKind.Field }),
+                    text('label', 'Name', 'Data', undefined, { editorKind: PropertyEditorKind.Field }),
+                    text('title', 'Title', 'Data', undefined, { editorKind: PropertyEditorKind.Field }),
+                    text('parentId', 'Reports to', 'Data', 'The id of the person above; empty for the top.', { editorKind: PropertyEditorKind.Field }),
+                ], 'One row per person or unit.'),
+                acceptedBindingKinds: bindable,
+            },
+            number('expandedDepth', 'Levels open at first', 'Appearance', undefined, { default: 2, constraints: { minimum: 1, integer: true } }),
+            text('selected', 'Selected', 'Data', 'The id of the selected node; bind it to start from one.'),
+            valueOutputProperty(PropertyValueType.String, 'The id of the selected node, published as the user selects.'),
+            ...standardStateProperties,
+        ],
+    },
+    {
+        component: key(ComponentName.PermissionMatrix),
+        displayName: 'Permission matrix',
+        description: 'Roles across, permissions down, a checkbox where they meet. Publishes the grants as the value output.',
+        properties: [
+            {
+                ...list('roles', 'Roles', 'Data', 'Role', [
+                    text('id', 'Id', 'Data', undefined, { constraints: { required: true } }),
+                    text('label', 'Name', 'Data'),
+                ], 'The columns.'),
+                acceptedBindingKinds: bindable,
+            },
+            {
+                ...list('permissions', 'Permissions', 'Data', 'Permission', [
+                    text('id', 'Id', 'Data', undefined, { constraints: { required: true } }),
+                    text('label', 'Name', 'Data'),
+                    text('group', 'Group', 'Data', 'A heading the permission is listed under.'),
+                ], 'The rows.'),
+                acceptedBindingKinds: bindable,
+            },
+            {
+                ...list('grants', 'Grants', 'Data', 'Grant', [
+                    text('role', 'Role', 'Data', 'The id of a role.', { constraints: { required: true } }),
+                    text('permission', 'Permission', 'Data', 'The id of a permission.', { constraints: { required: true } }),
+                ], 'What each role holds.'),
+                acceptedBindingKinds: bindable,
+            },
+            rule('editPermission', 'Edit permission', 'Enabled lets the user change grants; otherwise the matrix is read-only.'),
+            valueOutputProperty(PropertyValueType.Json, 'The grants as the user has changed them: rows of role and permission, published as they change.'),
+            ...standardStateProperties,
+        ],
+    },
 ];
 

package/foundation/foundationSamples.ts

@@ -78,6 +78,36 @@ export const foundationSamples: Record<string, FoundationSample> = {
         properties: { accept: '.pdf, image/*', maxSizeMb: 10, multiple: true },
         data: [], stateful: true,
     },
+    [ComponentName.ApprovalChainStepper]: {
+        properties: {
+            locale: 'en-US',
+            steps: [
+                { label: 'Team lead', approver: 'Grace Hopper', state: 'approved', at: '2026-03-09T10:00:00Z', comment: 'Looks fine.' },
+                { label: 'Finance', approver: 'Linus Torvalds', state: 'current' },
+                { label: 'Director', approver: 'Ada Lovelace', state: 'pending' },
+            ],
+        },
+        data: ['Grace Hopper', 'Looks fine.'], stateful: true,
+    },
+    [ComponentName.OrgTree]: {
+        properties: {
+            nodes: [
+                { id: 'ceo', label: 'Ada Lovelace', title: 'Chief executive' },
+                { id: 'cto', label: 'Grace Hopper', title: 'Chief technology officer', parentId: 'ceo' },
+                { id: 'cfo', label: 'Linus Torvalds', title: 'Chief financial officer', parentId: 'ceo' },
+                { id: 'dev', label: 'Margaret Hamilton', title: 'Engineering manager', parentId: 'cto' },
+            ],
+        },
+        data: ['Chief technology officer'], stateful: true,
+    },
+    [ComponentName.PermissionMatrix]: {
+        properties: {
+            roles: [{ id: 'admin', label: 'Administrator' }, { id: 'sales', label: 'Sales' }],
+            permissions: [{ id: 'view', label: 'View deals', group: 'Deals' }, { id: 'edit', label: 'Edit deals', group: 'Deals' }, { id: 'users', label: 'Manage users', group: 'Administration' }],
+            grants: [{ role: 'admin', permission: 'view' }, { role: 'admin', permission: 'edit' }, { role: 'admin', permission: 'users' }, { role: 'sales', permission: 'view' }],
+        },
+        data: ['Edit deals', 'Manage users'], 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

@@ -113,13 +113,24 @@ export const foundationStrings = {
     approvalRejected: 'Rejected',
     approvalSkipped: 'Skipped',
     approvalChain: 'Approval chain',
+    approvalStep: 'Step {n} of {total}',
+    approvalNotReached: 'Not reached',
+    approvalOutcomeApproved: 'Approved by everyone',
+    approvalOutcomeRejected: 'Rejected',
+    approvalOutcomeInProgress: 'Waiting for a decision',
+    approvalOutcomePending: 'Not started',
     orgExpand: 'Expand {name}',
     orgCollapse: 'Collapse {name}',
     orgReports: '{count} reports',
+    orgTree: 'Organization',
+    orgNone: 'There is nobody in the organization yet',
     matrixAllowed: 'Allowed',
     matrixDenied: 'Not allowed',
     matrixGrant: 'Grant {permission} to {role}',
     matrixReadOnly: 'Read-only',
+    matrixPermission: 'Permission',
+    matrixScroll: 'Permission matrix, scrolls sideways',
+    matrixGroupAll: 'Other',
 } as const;
 
 /** The name of one of the foundation strings. */

package/foundation/index.ts

@@ -30,6 +30,12 @@ export * from './AvatarStack';
 export * from './uploadModel';
 export * from './FileUploaderHandler';
 export * from './FileUploader';
+export * from './approvalModel';
+export * from './ApprovalChainStepper';
+export * from './orgModel';
+export * from './OrgTree';
+export * from './permissionModel';
+export * from './PermissionMatrix';
 export * from './foundationDescriptors';
 export * from './foundationComponentMetadata';
 export * from './foundationSamples';

package/foundation/orgModel.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A person or unit in an organization, with who they report to. */
+export interface OrgNode {
+    id: string;
+    label: string;
+    title?: string;
+    parentId?: string;
+}
+
+/** A node placed in the tree. */
+export interface OrgTreeNode extends OrgNode {
+    children: OrgTreeNode[];
+    depth: number;
+}
+
+/** Reads nodes out of a property value, dropping entries without an id and keeping the first of a repeated id. */
+export function readOrgNodes(value: unknown): OrgNode[] {
+    if (!Array.isArray(value)) return [];
+
+    const seen = new Set<string>();
+    return value.flatMap((entry): OrgNode[] => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return [];
+        const { id, label, title, parentId } = entry as Record<string, unknown>;
+        if (typeof id !== 'string' || id.length === 0 || seen.has(id)) return [];
+        seen.add(id);
+        return [{ id, label: typeof label === 'string' && label.length > 0 ? label : id, ...(typeof title === 'string' ? { title } : {}), ...(typeof parentId === 'string' && parentId.length > 0 ? { parentId } : {}) }];
+    });
+}
+
+/**
+ * Builds the tree from the flat rows a query returns.
+ *
+ * Someone whose manager is not in the data becomes a root rather than vanishing, and a reporting cycle is broken at the node that closes it
+ * - which becomes a root - so malformed data draws something and never loops. Siblings keep the order of the rows.
+ */
+export function buildOrgTree(nodes: OrgNode[]): OrgTreeNode[] {
+    const known = new Set(nodes.map(node => node.id));
+    const parentOf = new Map<string, string | undefined>(nodes.map(node => [node.id, node.parentId !== undefined && known.has(node.parentId) && node.parentId !== node.id ? node.parentId : undefined]));
+
+    for (const node of nodes) {
+        const path = new Set<string>([node.id]);
+        for (let current = parentOf.get(node.id); current !== undefined; current = parentOf.get(current)) {
+            if (path.has(current)) { parentOf.set(node.id, undefined); break; }
+            path.add(current);
+        }
+    }
+
+    const placed = new Map<string, OrgTreeNode>(nodes.map(node => [node.id, { ...node, children: [], depth: 0 }]));
+    const roots: OrgTreeNode[] = [];
+    for (const node of nodes) {
+        const parent = parentOf.get(node.id);
+        if (parent === undefined) roots.push(placed.get(node.id)!);
+        else placed.get(parent)!.children.push(placed.get(node.id)!);
+    }
+
+    const assignDepth = (level: OrgTreeNode[], depth: number) => level.forEach(node => { node.depth = depth; assignDepth(node.children, depth + 1); });
+    assignDepth(roots, 1);
+    return roots;
+}
+
+/** The nodes that can be reached from the roots with the given expansion, in the order they are drawn. */
+export function visibleNodes(roots: OrgTreeNode[], expanded: ReadonlySet<string>): OrgTreeNode[] {
+    return roots.flatMap(node => [node, ...(expanded.has(node.id) ? visibleNodes(node.children, expanded) : [])]);
+}
+
+/** The ids of every node down to a depth: what is expanded when the tree first opens. */
+export function expandedToDepth(roots: OrgTreeNode[], depth: number): Set<string> {
+    const result = new Set<string>();
+    const walk = (level: OrgTreeNode[]) => level.forEach(node => { if (node.depth < depth && node.children.length > 0) result.add(node.id); walk(node.children); });
+    walk(roots);
+    return result;
+}
+
+/** The number of people below a node, at any depth. */
+export const descendantCount = (node: OrgTreeNode): number => node.children.reduce((sum, child) => sum + 1 + descendantCount(child), 0);
+
+/** For each node, the nodes that share its parent (itself included, in order) and its parent: what a tree needs for its set size and position, and for Left to go up. */
+export function placements(roots: OrgTreeNode[]): Map<string, { siblings: OrgTreeNode[]; parent?: OrgTreeNode }> {
+    const result = new Map<string, { siblings: OrgTreeNode[]; parent?: OrgTreeNode }>();
+    const walk = (level: OrgTreeNode[], parent?: OrgTreeNode) => level.forEach(node => { result.set(node.id, { siblings: level, parent }); walk(node.children, node); });
+    walk(roots);
+    return result;
+}