@cratis/scene.blueprint.default 4.39.0 → 4.40.0

package/foundation/BulkBar.tsx

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { ActionButton } from './ActionButton';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { readPermissionRule } from './PermissionRule';
+
+/** How many records a selection holds: an array's length, a number as given, anything else none. */
+export function selectionCount(selection: unknown): number {
+    if (Array.isArray(selection)) return selection.length;
+    return typeof selection === 'number' && Number.isFinite(selection) && selection > 0 ? Math.floor(selection) : 0;
+}
+
+/**
+ * The `bulkBar` component: appears when records are selected, says how many, offers the bulk actions and clears the selection.
+ *
+ * `selection` is the selected records (or their count) - a list screen binds it to the table's selection output - and the bar is not rendered
+ * at all while nothing is selected. It is announced politely when it appears or its count changes. `actions` (strings) are the bulk actions; each
+ * runs the behaviors attached to the element and honours `actionPermission` (enabled, disabled with its reason, or hidden). "Clear selection"
+ * runs the same behaviors with no action, which a screen wires to emptying the table's selection.
+ */
+export function BulkBar({ element, interactions }: RegisteredComponentProps) {
+    const count = selectionCount(element.properties.selection);
+    const strings = readFoundationStrings(element);
+    const actions = Array.isArray(element.properties.actions) ? element.properties.actions.filter((action): action is string => typeof action === 'string') : [];
+    const rule = readPermissionRule(element, 'actionPermission');
+
+    return (
+        <div className='foundation foundation-bulk-bar' data-scene-id={element.id} role='region' aria-label={strings.bulkActions} hidden={count === 0}>
+            <span className='foundation-bulk-count' role='status'>{count > 0 ? formatText(strings.bulkSelected, { count }) : ''}</span>
+            <span className='foundation-bulk-actions'>
+                {actions.map(action => <ActionButton key={action} rule={rule} emphasis='secondary' disabledReason={strings.disabledNoPermission} onClick={interactions?.onClick}>{action}</ActionButton>)}
+            </span>
+            <ActionButton emphasis='quiet' disabledReason={strings.disabledNoPermission} onClick={interactions?.onClick}>{strings.bulkClear}</ActionButton>
+        </div>
+    );
+}

package/foundation/DataList.tsx

@@ -0,0 +1,208 @@
+// 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 { readOptionalString } from '../shell/elementProperties';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon } from './FoundationIcon';
+import { FoundationFrame } from './StateFrame';
+import { formatDate, formatNumber, NumberFormat, readLocale } from './formatting';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { readPermissionRule } from './PermissionRule';
+import {
+    CellKind, ListColumn, ListRow, ListVariant, filterRows, formatSort, groupRows, nextSort, paginate, parseSelection, parseSort, readListColumns, readListVariant, rowId,
+    searchRows, sortRows, textOf, toggleSelection,
+} from './listModel';
+import { useCompactWidth } from './useCompactWidth';
+import { useUrlState } from './urlState';
+
+function Cell({ column, row, locale }: { column: ListColumn; row: ListRow; locale: string }) {
+    const raw = row[column.field];
+    const text = textOf(row, column.field);
+    switch (column.kind) {
+        case CellKind.Number: return <>{typeof raw === 'number' ? formatNumber(raw, locale) : text}</>;
+        case CellKind.Currency: return <>{typeof raw === 'number' ? formatNumber(raw, locale, NumberFormat.Currency, column.currency ?? 'USD') : text}</>;
+        case CellKind.Date: return <>{formatDate(raw, locale)}</>;
+        case CellKind.Status: {
+            const tone = column.tones[text] ?? 'neutral';
+            const icon = ({ success: 'check', warning: 'alert', danger: 'close', info: 'info', neutral: 'circle' } as const)[tone as 'success'] ?? 'circle';
+            return <span className='foundation-chip' data-tone={tone}><FoundationIcon name={icon} /><span>{text}</span></span>;
+        }
+        default: return <>{text}</>;
+    }
+}
+
+/**
+ * The `dataList` component: the records of a collection as a table, as cards, or grouped with subtotals, with search, sort, paging and
+ * selection that live in the address.
+ *
+ * `rows` and `columns` (`field`, `header`, `kind`: text, number, currency, date or status, `sortable`, `tones`) come from a query; the list takes its
+ * text, filter, sort, page and selection from the address when `urlKey` is given (`<urlKey>q`, `sort`, `page`, `selected`), so a shared link or a refresh restores
+ * the screen as it was. `search` and `filter` (the filter builder's value) narrow the rows. A header is a button that cycles ascending, descending, none, and the
+ * column says so in words. Rows select with checkboxes (`selectionMode` multiple or single), and a row's "Actions" menu names its row. On a phone a table becomes cards -
+ * nothing is hidden or cut. The selection is the `value` output; a row action is the `action` output. Header, row and cell elements are real table elements,
+ * so a screen reader announces the row and column of the cell it is on.
+ */
+export function DataList({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const columns = useMemo(() => readListColumns(element.properties.columns), [element.properties.columns]);
+    const rows = useMemo(() => (Array.isArray(element.properties.rows) ? (element.properties.rows as unknown[]).filter((row): row is ListRow => typeof row === 'object' && row !== null && !Array.isArray(row)) : []), [element.properties.rows]);
+    const idField = readOptionalString(element, 'idField') ?? 'id';
+    const titleField = readOptionalString(element, 'titleField') ?? columns[0]?.field ?? idField;
+    const urlKey = readOptionalString(element, 'urlKey');
+    const keyed = (name: string) => (urlKey === undefined ? undefined : `${urlKey}${name}`);
+    const [searchText, setSearchText] = useUrlState(keyed('q'), readOptionalString(element, 'search'));
+    const [sortText, setSortText] = useUrlState(keyed('sort'), readOptionalString(element, 'sort'));
+    const [pageText, setPageText] = useUrlState(keyed('page'), '1');
+    const [selectedText, setSelectedText] = useUrlState(keyed('selected'), readOptionalString(element, 'selected'));
+    const [openGroups, setOpenGroups] = useState<Set<string> | undefined>();
+    const strings = readFoundationStrings(element);
+    const locale = readLocale(element);
+    const compact = useCompactWidth();
+    const requestedVariant = readListVariant(element.properties.variant);
+    const variant = requestedVariant === ListVariant.Table && compact && element.properties.collapse !== false ? ListVariant.Cards : requestedVariant;
+    const pageSize = typeof element.properties.pageSize === 'number' ? element.properties.pageSize : 0;
+    const multiple = element.properties.selectionMode !== 'single';
+    const selectable = element.properties.selectionMode === 'multiple' || element.properties.selectionMode === 'single';
+    const actions = Array.isArray(element.properties.rowActions) ? element.properties.rowActions.filter((action): action is string => typeof action === 'string') : [];
+    const actionRule = readPermissionRule(element, 'actionPermission');
+    const groupBy = readOptionalString(element, 'groupBy');
+    const totalField = readOptionalString(element, 'totalField');
+    const sort = parseSort(sortText, columns);
+
+    const matching = useMemo(() => filterRows(searchRows(rows, columns, searchText ?? ''), element.properties.filter), [rows, columns, searchText, element.properties.filter]);
+    const sorted = useMemo(() => sortRows(matching, sort, locale), [matching, sort?.field, sort?.descending, locale]);
+    const page = paginate(sorted, Number(pageText), variant === ListVariant.Grouped ? 0 : pageSize);
+    const selected = parseSelection(selectedText);
+    const state = readComponentState(element, rows.length > 0);
+
+    useEffect(() => { if (Number(pageText) !== page.page && pageText !== undefined) setPageText(String(page.page)); }, [page.page, pageText, setPageText]);
+    useValueOutput(bindingOutputs, multiple ? selected : selected[0]);
+
+    const select = (id: string) => { setSelectedText(toggleSelection(selected, id, multiple).join(',') || undefined); interactions?.onSelect?.(); };
+    const run = (action: string, id: string) => { bindingOutputs?.setOutput('action', { action, row: id }); interactions?.onClick?.({ stopPropagation: () => undefined }); };
+    const sortLabel = (column: ListColumn) => (sort?.field === column.field ? `${column.header}, ${sort.descending ? strings.listSortedDescending : strings.listSortedAscending}` : column.header);
+    const nameOf = (row: ListRow, index: number) => textOf(row, titleField) || rowId(row, index, idField);
+    const allOnPage = page.rows.length > 0 && page.rows.every((row, index) => selected.includes(rowId(row, index, idField)));
+    const count = matching.length === rows.length ? formatText(strings.listCount, { count: rows.length }) : formatText(strings.listCountFiltered, { shown: matching.length, total: rows.length });
+
+    const rowActions = (row: ListRow, index: number) => actions.length === 0 || actionRule === 'hidden' ? undefined : (
+        <select className='foundation-row-actions' aria-label={formatText(strings.listRowActions, { name: nameOf(row, index) })} value='' disabled={actionRule === 'disabled'} title={actionRule === 'disabled' ? strings.disabledNoPermission : undefined}
+            onChange={event => { if (event.target.value) run(event.target.value, rowId(row, index, idField)); }}>
+            <option value=''>{strings.listActions}</option>
+            {actions.map(action => <option key={action} value={action}>{action}</option>)}
+        </select>
+    );
+
+    const checkbox = (row: ListRow, index: number) => !selectable ? undefined : (
+        <input type={multiple ? 'checkbox' : 'radio'} name={`${element.id}-select`} checked={selected.includes(rowId(row, index, idField))} aria-label={formatText(strings.listSelectRow, { name: nameOf(row, index) })} onChange={() => select(rowId(row, index, idField))} />
+    );
+
+    const table = (tableRows: ListRow[], offset = 0, caption?: string) => (
+        <div className='foundation-table-scroll'>
+            <table className='foundation-table'>
+                <caption className='foundation-visually-hidden'>{caption ?? readOptionalString(element, 'label') ?? strings.listTable}</caption>
+                <thead>
+                    <tr>
+                        {selectable && (
+                            <th scope='col' className='foundation-table-select'>
+                                {multiple && <input type='checkbox' checked={allOnPage} aria-label={strings.listSelectAll}
+                                    onChange={() => setSelectedText((allOnPage ? selected.filter(id => !page.rows.some((row, index) => rowId(row, index, idField) === id)) : [...new Set([...selected, ...page.rows.map((row, index) => rowId(row, index, idField))])]).join(',') || undefined)} />}
+                            </th>
+                        )}
+                        {columns.map(column => (
+                            <th key={column.field} scope='col' aria-sort={sort?.field === column.field ? (sort.descending ? 'descending' : 'ascending') : undefined}>
+                                {column.sortable ? (
+                                    <button type='button' className='foundation-sort' aria-label={formatText(strings.listSortBy, { column: sortLabel(column) })} onClick={() => { setSortText(formatSort(nextSort(sort, column.field))); setPageText('1'); }}>
+                                        <span>{column.header}</span>
+                                        {sort?.field === column.field && <FoundationIcon name={sort.descending ? 'arrow-down' : 'arrow-up'} />}
+                                    </button>
+                                ) : column.header}
+                            </th>
+                        ))}
+                        {actions.length > 0 && actionRule !== 'hidden' && <th scope='col'><span className='foundation-visually-hidden'>{strings.listActions}</span></th>}
+                    </tr>
+                </thead>
+                <tbody>
+                    {tableRows.map((row, position) => {
+                        const index = offset + position;
+                        const id = rowId(row, index, idField);
+                        return (
+                            <tr key={id} aria-selected={selectable ? selected.includes(id) : undefined} data-selected={selected.includes(id)}>
+                                {selectable && <td className='foundation-table-select'>{checkbox(row, index)}</td>}
+                                {columns.map((column, columnIndex) => columnIndex === 0
+                                    ? <th key={column.field} scope='row'><Cell column={column} row={row} locale={locale} /></th>
+                                    : <td key={column.field} data-kind={column.kind}><Cell column={column} row={row} locale={locale} /></td>)}
+                                {actions.length > 0 && actionRule !== 'hidden' && <td>{rowActions(row, index)}</td>}
+                            </tr>
+                        );
+                    })}
+                </tbody>
+            </table>
+        </div>
+    );
+
+    const cards = (cardRows: ListRow[], offset = 0) => (
+        <ul className='foundation-cards' aria-label={readOptionalString(element, 'label') ?? strings.listCards}>
+            {cardRows.map((row, position) => {
+                const index = offset + position;
+                const id = rowId(row, index, idField);
+                return (
+                    <li key={id} className='foundation-card-row' data-selected={selected.includes(id)}>
+                        <div className='foundation-card-head'>{checkbox(row, index)}<strong>{nameOf(row, index)}</strong></div>
+                        <dl>
+                            {columns.filter(column => column.field !== titleField).map(column => (
+                                <div key={column.field}><dt className='foundation-count'>{column.header}</dt><dd><Cell column={column} row={row} locale={locale} /></dd></div>
+                            ))}
+                        </dl>
+                        {rowActions(row, index)}
+                    </li>
+                );
+            })}
+        </ul>
+    );
+
+    const groups = variant === ListVariant.Grouped && groupBy ? groupRows(sorted, groupBy, totalField) : [];
+    const isOpen = (key: string) => (openGroups === undefined ? true : openGroups.has(key));
+    const toggleGroup = (key: string) => setOpenGroups(current => { const base = current ?? new Set(groups.map(group => group.key)); const next = new Set(base); if (next.has(key)) next.delete(key); else next.add(key); return next; });
+    const totalColumn = columns.find(column => column.field === totalField);
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='data-list' state={state} skeleton={[100, 100, 100, 100]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && (
+                <>
+                    <p className='foundation-count' role='status'>{count}</p>
+                    {matching.length === 0 ? (
+                        <div className='foundation-empty' role='status'>
+                            <strong className='foundation-empty-headline'>{strings.listNoMatches}</strong>
+                            <button type='button' className='foundation-link' onClick={() => { setSearchText(undefined); setPageText('1'); interactions?.onChange?.(); }}>{strings.listClearSearch}</button>
+                        </div>
+                    ) : variant === ListVariant.Grouped && groupBy ? groups.map(group => (
+                        <section key={group.key} className='foundation-list-group'>
+                            <h3>
+                                <button type='button' aria-expanded={isOpen(group.key)} className='foundation-sort' onClick={() => toggleGroup(group.key)}
+                                    aria-label={formatText(isOpen(group.key) ? strings.listGroupCollapse : strings.listGroupExpand, { group: group.key })}>
+                                    <FoundationIcon name={isOpen(group.key) ? 'chevron-down' : 'chevron-right'} />{group.key}
+                                </button>
+                                <span className='foundation-count'>{group.subtotal === undefined ? group.rows.length : formatText(strings.listGroupSubtotal, { count: group.rows.length, total: formatNumber(group.subtotal, locale, totalColumn?.kind === CellKind.Currency ? NumberFormat.Currency : NumberFormat.Number, totalColumn?.currency ?? 'USD') })}</span>
+                            </h3>
+                            {isOpen(group.key) && table(group.rows, 0, group.key)}
+                        </section>
+                    )) : (
+                        <>
+                            {variant === ListVariant.Cards ? cards(page.rows, (page.page - 1) * Math.max(1, pageSize)) : table(page.rows, (page.page - 1) * Math.max(1, pageSize))}
+                            {page.pages > 1 && (
+                                <nav className='foundation-pager' aria-label={formatText(strings.listPage, { page: page.page, pages: page.pages })}>
+                                    <button type='button' className='foundation-button' data-emphasis='secondary' disabled={page.page <= 1} onClick={() => setPageText(String(page.page - 1))}>{strings.listPrevious}</button>
+                                    <span aria-current='page'>{formatText(strings.listPage, { page: page.page, pages: page.pages })}</span>
+                                    <button type='button' className='foundation-button' data-emphasis='secondary' disabled={page.page >= page.pages} onClick={() => setPageText(String(page.page + 1))}>{strings.listNext}</button>
+                                </nav>
+                            )}
+                        </>
+                    )}
+                </>
+            )}
+        </FoundationFrame>
+    );
+}
+

package/foundation/FormScreenBody.tsx

@@ -0,0 +1,196 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { ActionButton } from './ActionButton';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FormField, FormFieldType, FormMode, FormSection, FormValues, addressLines, mapServerErrors, readFormMode, readFormSections, sameValues, validate } from './formModel';
+import { readLocale } from './formatting';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { readPermissionRule } from './PermissionRule';
+import { FoundationIcon } from './FoundationIcon';
+import { FoundationFrame } from './StateFrame';
+
+interface FieldProps {
+    field: FormField;
+    value: unknown;
+    error?: string;
+    readOnly: boolean;
+    locale: string;
+    required: string;
+    choose: string;
+    set(value: unknown): void;
+    blur(): void;
+}
+
+function FieldInput({ field, value, error, readOnly, locale, required, choose, set, blur }: FieldProps) {
+    const id = useId();
+    const describedBy = [field.help ? `${id}-help` : undefined, error ? `${id}-error` : undefined].filter(Boolean).join(' ') || undefined;
+    const common = { id, 'aria-invalid': error ? true : undefined, 'aria-required': field.required || undefined, 'aria-describedby': describedBy, disabled: readOnly, onBlur: blur } as const;
+    const text = typeof value === 'string' || typeof value === 'number' ? String(value) : '';
+    let input;
+
+    switch (field.type) {
+        case FormFieldType.Toggle:
+            input = <input {...common} type='checkbox' role='switch' checked={value === true} onChange={event => set(event.target.checked)} />;
+            break;
+        case FormFieldType.Select:
+        case FormFieldType.Lookup:
+            input = <select {...common} value={text} onChange={event => set(event.target.value)}><option value=''>{choose}</option>{field.options.map(option => <option key={option} value={option}>{option}</option>)}</select>;
+            break;
+        case FormFieldType.MultiSelect:
+            input = (
+                <fieldset className='foundation-fieldset' aria-describedby={describedBy} disabled={readOnly}>
+                    {field.options.map(option => (
+                        <label key={option} className='foundation-check'>
+                            <input type='checkbox' checked={Array.isArray(value) && value.includes(option)} onBlur={blur}
+                                onChange={event => set(event.target.checked ? [...(Array.isArray(value) ? value : []), option] : (Array.isArray(value) ? value : []).filter(candidate => candidate !== option))} />
+                            <span>{option}</span>
+                        </label>
+                    ))}
+                </fieldset>
+            );
+            break;
+        case FormFieldType.RichText:
+            input = <textarea {...common} rows={5} value={text} placeholder={field.placeholder} onChange={event => set(event.target.value)} />;
+            break;
+        case FormFieldType.File:
+            input = <input {...common} type='file' onChange={event => set(Array.from(event.target.files ?? []).map(file => file.name))} />;
+            break;
+        case FormFieldType.Address: {
+            const lines = typeof value === 'object' && value !== null ? (value as Record<string, string>) : {};
+            input = (
+                <div className='foundation-address' role='group' aria-describedby={describedBy}>
+                    {addressLines.map(line => (
+                        <input key={line} type='text' aria-label={`${field.label}: ${line}`} placeholder={line} disabled={readOnly} value={lines[line] ?? ''} onBlur={blur} onChange={event => set({ ...lines, [line]: event.target.value })} />
+                    ))}
+                </div>
+            );
+            break;
+        }
+        case FormFieldType.Number:
+        case FormFieldType.Currency:
+            input = <input {...common} type='number' inputMode='decimal' value={text} placeholder={field.placeholder} onChange={event => set(event.target.value === '' ? '' : Number(event.target.value))} />;
+            break;
+        case FormFieldType.Date:
+            input = <input {...common} type='date' lang={locale} value={text} onChange={event => set(event.target.value)} />;
+            break;
+        default:
+            input = <input {...common} type='text' value={text} placeholder={field.placeholder} onChange={event => set(event.target.value)} />;
+    }
+
+    const grouped = field.type === FormFieldType.MultiSelect || field.type === FormFieldType.Address;
+    return (
+        <div className='foundation-field' style={{ gridColumn: `span ${field.span}` }} data-invalid={error ? true : undefined}>
+            {grouped ? <span className='foundation-field-label' id={`${id}-label`}>{field.label}{field.required && <span className='foundation-required' title={required}> *<span className='foundation-visually-hidden'> ({required})</span></span>}</span>
+                : <label htmlFor={id} className='foundation-field-label'>{field.label}{field.required && <span className='foundation-required' title={required}> *<span className='foundation-visually-hidden'> ({required})</span></span>}</label>}
+            {input}
+            {field.help && <span id={`${id}-help`} className='foundation-count'>{field.help}</span>}
+            {error && <span id={`${id}-error`} className='foundation-field-error' role='alert'>{error}</span>}
+        </div>
+    );
+}
+
+/**
+ * The `formScreenBody` component: titled sections of fields in a one-to-three column grid, validated, with the Save / Save and new / Cancel bar and the
+ * unsaved-changes guard.
+ *
+ * `sections` (`title`, `columns`, `fields`) and `values` come from the screen; a field is `text`, `number`, `currency`, `date`, `select`, `multiSelect`, `lookup`,
+ * `toggle`, `file`, `richText` or `address`. Validation is inline on blur and a summary on submit (an alert listing each field as a link back to it); a server's
+ * `errors` map onto the fields, and one for a field the form lacks is shown as a general error so it is never lost. Required fields are marked with an asterisk
+ * *and* the word. `mode` is `create`, `edit`, `readOnly` or `settings` - settings has one Save for each section. The edited values are the `value` output; Save
+ * runs the behaviors attached to the element. While values differ from the saved ones the form says so, warns the browser before the page is left, and offers
+ * "Discard changes". The action bar sticks to the bottom as the form scrolls.
+ */
+export function FormScreenBody({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const sections = useMemo(() => readFormSections(element.properties.sections), [element.properties.sections]);
+    const mode = readFormMode(element.properties.mode);
+    const suppliedValues = (typeof element.properties.values === 'object' && element.properties.values !== null && !Array.isArray(element.properties.values) ? element.properties.values : {}) as FormValues;
+    const suppliedKey = JSON.stringify(suppliedValues);
+    const [saved, setSaved] = useState<FormValues>(suppliedValues);
+    const [values, setValues] = useState<FormValues>(suppliedValues);
+    const [touched, setTouched] = useState<Set<string>>(new Set());
+    const [submitted, setSubmitted] = useState(false);
+    const [justSaved, setJustSaved] = useState(false);
+    const summary = useRef<HTMLDivElement>(null);
+    const strings = readFoundationStrings(element);
+    const locale = readLocale(element);
+    const state = readComponentState(element, sections.length > 0);
+    const readOnly = mode === FormMode.ReadOnly || readPermissionRule(element, 'editPermission') !== 'enabled';
+    const canSave = readPermissionRule(element, 'savePermission');
+    const problems = validate(sections, values);
+    const server = useMemo(() => mapServerErrors(sections, element.properties.errors), [sections, element.properties.errors]);
+    const dirty = !sameValues(values, saved);
+    const labelOf = (name: string) => sections.flatMap(section => section.fields).find(field => field.name === name)?.label ?? name;
+    const wording = (name: string, kind: 'required' | 'invalid') => formatText(kind === 'required' ? strings.formRequiredField : strings.formInvalidField, { label: labelOf(name) });
+    const errorOf = (name: string) => server.byField[name] ?? ((touched.has(name) || submitted) && problems[name] ? wording(name, problems[name]) : undefined);
+    const invalid = Object.keys(problems);
+
+    useEffect(() => { setSaved(suppliedValues); setValues(suppliedValues); setTouched(new Set()); setSubmitted(false); }, [suppliedKey]);
+    useValueOutput(bindingOutputs, values);
+    useEffect(() => {
+        if (!dirty || typeof window === 'undefined') return;
+        const guard = (event: BeforeUnloadEvent) => { event.preventDefault(); event.returnValue = ''; };
+        window.addEventListener('beforeunload', guard);
+        return () => window.removeEventListener('beforeunload', guard);
+    }, [dirty]);
+
+    const submit = (scope?: FormSection) => {
+        setSubmitted(true);
+        const scoped = scope ? scope.fields.filter(field => problems[field.name]) : invalid.map(name => ({ name }));
+        if (scoped.length > 0) { requestAnimationFrame(() => summary.current?.focus()); return; }
+        setSaved(values);
+        setJustSaved(true);
+        interactions?.onClick?.({ stopPropagation: () => undefined });
+    };
+    const edit = (name: string, value: unknown) => { setValues(current => ({ ...current, [name]: value })); setJustSaved(false); interactions?.onChange?.(); };
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='form-screen' state={state} skeleton={[40, 100, 100, 70]}>
+            {state !== ComponentState.Loading && (
+                <form noValidate onSubmit={event => { event.preventDefault(); if (mode !== FormMode.Settings) submit(); }}>
+                    {readOnly && mode === FormMode.ReadOnly && <p className='foundation-count' role='status'>{strings.formReadOnly}</p>}
+                    {(submitted && invalid.length > 0 || server.general.length > 0) && (
+                        <div ref={summary} tabIndex={-1} role='alert' className='foundation-message' data-tone='danger'>
+                            <FoundationIcon name='alert' />
+                            <div className='foundation-message-text'>
+                                <strong>{invalid.length === 1 ? strings.formSummaryOne : formatText(strings.formSummary, { count: invalid.length })}</strong>
+                                <ul>
+                                    {invalid.map(name => <li key={name}>{wording(name, problems[name])}</li>)}
+                                    {server.general.map(message => <li key={message}>{message}</li>)}
+                                </ul>
+                            </div>
+                        </div>
+                    )}
+                    {sections.map(section => (
+                        <fieldset key={section.id} className='foundation-form-section' disabled={false}>
+                            {section.title && <legend>{section.title}</legend>}
+                            <div className='foundation-form-grid' style={{ gridTemplateColumns: `repeat(${section.columns}, minmax(0, 1fr))` }} data-columns={section.columns}>
+                                {section.fields.map(field => (
+                                    <FieldInput key={field.name} field={field} value={values[field.name]} error={errorOf(field.name)} readOnly={readOnly} locale={locale} required={strings.formRequired} choose={strings.formChoose}
+                                        set={value => edit(field.name, value)} blur={() => setTouched(current => new Set(current).add(field.name))} />
+                                ))}
+                            </div>
+                            {mode === FormMode.Settings && !readOnly && (
+                                <div className='foundation-form-section-actions'>
+                                    <ActionButton rule={canSave} emphasis='secondary' disabledReason={strings.disabledNoPermission} onClick={() => submit(section)}>{formatText(strings.formSectionSave, { section: section.title })}</ActionButton>
+                                </div>
+                            )}
+                        </fieldset>
+                    ))}
+                    {mode !== FormMode.Settings && mode !== FormMode.ReadOnly && (
+                        <div className='foundation-form-actions' role='group' aria-label={strings.listActions}>
+                            <span role='status' className='foundation-count'>{dirty ? strings.formUnsaved : justSaved ? strings.formSaved : ''}</span>
+                            <span className='foundation-wizard-spacer' />
+                            {dirty && <ActionButton emphasis='quiet' disabledReason={strings.disabledNoPermission} onClick={() => { setValues(saved); setTouched(new Set()); setSubmitted(false); }}>{strings.formDiscard}</ActionButton>}
+                            <ActionButton emphasis='secondary' disabledReason={strings.disabledNoPermission} onClick={() => interactions?.onClick?.({ stopPropagation: () => undefined })}>{strings.formCancel}</ActionButton>
+                            {mode === FormMode.Create && <ActionButton rule={canSave} emphasis='secondary' disabledReason={strings.disabledNoPermission} onClick={() => { submit(); }}>{strings.formSaveAndNew}</ActionButton>}
+                            <ActionButton rule={canSave} disabledReason={strings.disabledNoPermission} onClick={() => submit()}>{strings.formSave}</ActionButton>
+                        </div>
+                    )}
+                </form>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/FoundationStates.tsx

@@ -35,7 +35,7 @@ export function FoundationStates({ component, theme, properties, rightToLeft }:
         <SceneThemeProvider theme={theme === 'dark' ? darkTheme : lightTheme}>
             <div dir={rightToLeft ? 'rtl' : 'ltr'} className='foundation-states' style={{ display: 'grid', gap: '1rem', padding: '1rem', gridTemplateColumns: 'repeat(auto-fill, minmax(18rem, 1fr))', background: 'var(--scene-surface-background)', color: 'var(--scene-text-color)' }}>
                 {states.map(state => (
-                    <figure key={state} style={{ margin: 0 }}>
+                    <figure key={state} style={{ margin: 0, minInlineSize: 0 }}>
                         <figcaption style={{ fontSize: '0.75rem', textTransform: 'uppercase', marginBlockEnd: '0.5rem' }}>{state}</figcaption>
                         <Component element={foundationElement(component, { ...sample?.properties, ...properties }, state === ComponentState.Ready ? undefined : state)} slots={{}} />
                     </figure>

package/foundation/GlobalSearch.tsx

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { readOptionalString } from '../shell/elementProperties';
+import { FoundationIcon } from './FoundationIcon';
+import { readFoundationStrings } from './foundationStrings';
+import { useUrlState } from './urlState';
+
+/**
+ * The `globalSearch` component: a search box for the topbar or a list's toolbar.
+ *
+ * It is a `search` landmark around a labelled field; the text is the `value` output and, with `urlKey`, is kept in the address so a search is
+ * a shareable link. Pressing Escape clears it. The placeholder and the accessible name come from `placeholder` and `label`, and from the
+ * strings table when absent, so nothing is hard-coded.
+ */
+export function GlobalSearch({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const strings = readFoundationStrings(element);
+    const [text, setText] = useUrlState(readOptionalString(element, 'urlKey'), readOptionalString(element, 'text'));
+    const label = readOptionalString(element, 'label') ?? strings.searchLabel;
+
+    useValueOutput(bindingOutputs, text ?? '');
+
+    return (
+        <form role='search' className='foundation foundation-search' data-scene-id={element.id} onSubmit={event => { event.preventDefault(); interactions?.onChange?.(); }}>
+            <FoundationIcon name='filter' />
+            <input type='search' aria-label={label} placeholder={readOptionalString(element, 'placeholder') ?? strings.searchPlaceholder} value={text ?? ''}
+                onChange={event => { setText(event.target.value); interactions?.onChange?.(); }}
+                onKeyDown={event => { if (event.key === 'Escape' && (text ?? '').length > 0) { event.preventDefault(); setText(undefined); } }} />
+        </form>
+    );
+}

package/foundation/KanbanBoard.tsx

@@ -0,0 +1,97 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DragEvent, useEffect, useMemo, useState } from 'react';
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { BoardCard, BoardColumn, cardsOf, moveCard, overLimit, readCards, readColumnsOfBoard } from './boardModel';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon } from './FoundationIcon';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { readPermissionRule } from './PermissionRule';
+import { FoundationFrame } from './StateFrame';
+
+/**
+ * The `kanbanBoard` component: columns mapped to a status or stage, with cards that move between them.
+ *
+ * `columns` (`id`, `label`, `limit`) and `cards` (`id`, `title`, `column`, `assignee`, up to three `fields`, `badges`) come from a query. A card moves by
+ * dragging it to another column **and** by its own "Move to" menu - the keyboard and screen-reader alternative, so nothing depends on a pointer
+ * - and every move is announced. Columns show their count and a limit indicator that says "Over the limit" in words, and collapse to a
+ * strip. The new arrangement is published as `value` (the cards with their columns) for the screen to save; with `editPermission` not enabled the
+ * board is read-only. A card whose column no longer exists is shown in the first column rather than lost.
+ */
+export function KanbanBoard({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const columns = useMemo(() => readColumnsOfBoard(element.properties.columns), [element.properties.columns]);
+    const supplied = useMemo(() => readCards(element.properties.cards), [element.properties.cards]);
+    const suppliedKey = JSON.stringify(supplied);
+    const [cards, setCards] = useState<BoardCard[]>(supplied);
+    const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
+    const [announcement, setAnnouncement] = useState('');
+    const [dragging, setDragging] = useState<string | undefined>();
+    const strings = readFoundationStrings(element);
+    const state = readComponentState(element, columns.length > 0);
+    const locked = readPermissionRule(element, 'editPermission') !== 'enabled';
+
+    useEffect(() => setCards(supplied), [suppliedKey]);
+    useValueOutput(bindingOutputs, cards.map(card => ({ id: card.id, column: card.column })));
+
+    const move = (id: string, to: string) => {
+        const card = cards.find(candidate => candidate.id === id);
+        const target = columns.find(column => column.id === to);
+        const next = moveCard(columns, cards, id, to);
+        if (!card || !target || next === cards) return;
+        setCards(next);
+        setAnnouncement(formatText(strings.boardMoved, { title: card.title, column: target.label }));
+        interactions?.onChange?.();
+    };
+    const drop = (event: DragEvent, to: string) => { event.preventDefault(); if (dragging) move(dragging, to); setDragging(undefined); };
+    const toggle = (id: string) => setCollapsed(current => { const next = new Set(current); if (next.has(id)) next.delete(id); else next.add(id); return next; });
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='kanban-board' state={state} skeleton={[100, 100, 100]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && (
+                <>
+                    <div role='status' aria-live='polite' className='foundation-visually-hidden'>{announcement}</div>
+                    <div className='foundation-board'>
+                        {columns.map((column: BoardColumn) => {
+                            const inColumn = cardsOf(columns, cards, column.id);
+                            const closed = collapsed.has(column.id);
+                            const over = overLimit(column, inColumn.length);
+                            return (
+                                <section key={column.id} className='foundation-board-column' data-collapsed={closed} data-over={over} aria-label={formatText(strings.boardColumn, { column: column.label, count: inColumn.length })}
+                                    onDragOver={event => { if (!locked) event.preventDefault(); }} onDrop={event => { if (!locked) drop(event, column.id); }}>
+                                    <header className='foundation-board-header'>
+                                        <button type='button' className='foundation-icon-button' aria-expanded={!closed} aria-label={formatText(closed ? strings.boardExpand : strings.boardCollapse, { column: column.label })} onClick={() => toggle(column.id)}>
+                                            <FoundationIcon name={closed ? 'chevron-right' : 'chevron-down'} />
+                                        </button>
+                                        <h3>{column.label}</h3>
+                                        <span className='foundation-count'>{inColumn.length}{column.limit > 0 ? ` / ${column.limit}` : ''}</span>
+                                        {over && <span className='foundation-chip' data-tone='danger'><FoundationIcon name='alert' />{formatText(strings.boardWipExceeded, { limit: column.limit })}</span>}
+                                    </header>
+                                    {!closed && (
+                                        <ul className='foundation-board-cards'>
+                                            {inColumn.length === 0 && <li className='foundation-count'>{strings.boardNoCards}</li>}
+                                            {inColumn.map(card => (
+                                                <li key={card.id} className='foundation-board-card' draggable={!locked} onDragStart={() => setDragging(card.id)} onDragEnd={() => setDragging(undefined)}>
+                                                    <strong>{card.title}</strong>
+                                                    {card.assignee && <span className='foundation-count'><FoundationIcon name='user' /> {card.assignee}</span>}
+                                                    {card.fields.map(field => <span key={field.label} className='foundation-board-field'><span className='foundation-count'>{field.label}</span> {field.value}</span>)}
+                                                    {card.badges.length > 0 && <span className='foundation-board-badges'>{card.badges.map(badge => <span key={badge} className='foundation-chip' data-tone='neutral'>{badge}</span>)}</span>}
+                                                    {!locked && (
+                                                        <select className='foundation-board-move' aria-label={formatText(strings.boardMoveCard, { title: card.title })} value={column.id} onChange={event => move(card.id, event.target.value)}>
+                                                            <option value={column.id} disabled>{strings.boardMoveTo}</option>
+                                                            {columns.filter(other => other.id !== column.id).map(other => <option key={other.id} value={other.id}>{other.label}</option>)}
+                                                        </select>
+                                                    )}
+                                                </li>
+                                            ))}
+                                        </ul>
+                                    )}
+                                </section>
+                            );
+                        })}
+                    </div>
+                </>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/NotificationsButton.tsx

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { FoundationIcon } from './FoundationIcon';
+import { formatNumber, readLocale, NumberFormat } from './formatting';
+import { formatText, readFoundationStrings } from './foundationStrings';
+
+/**
+ * The `notificationsButton` component: the bell of the topbar, with the unread count.
+ *
+ * `count` is the unread number - bind it to a query - and the button says it in words ("3 unread") as well as in the badge, which is hidden from
+ * assistive technology so it is not read twice. Pressing it runs the behaviors attached to the element, which open whatever the application shows its
+ * notifications in. Counts above 99 read "99+" in the badge and in full in the words.
+ */
+export function NotificationsButton({ element, interactions }: RegisteredComponentProps) {
+    const strings = readFoundationStrings(element);
+    const count = typeof element.properties.count === 'number' && element.properties.count > 0 ? Math.floor(element.properties.count) : 0;
+    const spoken = count > 0 ? formatText(strings.notificationsCount, { count: formatNumber(count, readLocale(element), NumberFormat.Number, undefined, 0) }) : strings.notificationsNone;
+
+    return (
+        <button type='button' className='foundation foundation-notifications' data-scene-id={element.id} onClick={interactions?.onClick}>
+            <FoundationIcon name='alert' />
+            <span className='foundation-visually-hidden'>{`${strings.notificationsLabel}: ${spoken}`}</span>
+            {count > 0 && <span className='foundation-notifications-badge' aria-hidden='true'>{count > 99 ? '99+' : count}</span>}
+        </button>
+    );
+}