@cratis/scene.primereact 4.6.0 → 4.8.0

package/.storybook/preview.tsx

@@ -3,6 +3,8 @@
 
 import type { Decorator, Preview } from '@storybook/react';
 import { PrimeReactProvider } from '@primereact/core';
+import { QuillLoaderProvider } from '../editor';
+import { loadQuill } from '../loadQuill';
 import { primeReactTheme, usePrimeReactTheme } from '../theme';
 import '../primeReactTheme.css';
 import './preview.css';
@@ -12,6 +14,9 @@ import './preview.css';
 // resolve to. Only the icon font is still a stylesheet.
 import 'primeicons/primeicons.css';
 
+// A host that wants editable rich text installs Quill and its stylesheet, and provides the loader.
+import 'quill/dist/quill.snow.css';
+
 /**
  * Puts every story inside a `PrimeReactProvider` carrying a real Scene theme.
  *
@@ -29,7 +34,9 @@ const withTheme: Decorator = (Story) => {
 
     return (
         <PrimeReactProvider value={configuration}>
-            <Story />
+            <QuillLoaderProvider loader={loadQuill}>
+                <Story />
+            </QuillLoaderProvider>
         </PrimeReactProvider>
     );
 };

package/EnumerationResolution.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The outcome of resolving an authored enumeration value: the member, or the reason none could be chosen. */
+export type EnumerationResolution<TMember extends string> =
+    | { isValid: true; value: TMember }
+    | { isValid: false; value: unknown; message: string };

package/README.md

@@ -109,16 +109,9 @@ twenty-fifth theme cannot be added without it. The full attribution table is in
 components - through the semantic token layer `SceneThemeProvider` applies to the whole subtree, though
 not through the `--p-*` properties, which only PrimeReact's own components read.
 
-## Not covered
+## Optional peers
 
-| Component | Why |
-| --- | --- |
-| `editor` | `Editor` wraps Quill and needs `quill` installed. Same reasoning — a rich-text editor is a product decision, not a mapping. |
-
-The editor is a deliberate omission, not an oversight. A profile needing it should activate a package
-that owns its dependency.
-
-## Chart.js peer dependency
+### Chart.js peer dependency
 
 PrimeReact 11 removed its former Chart.js wrapper, so the Scene `chart` adapter mounts a Chart.js canvas
 itself. `chart.js@^4.5.1` is an optional peer dependency of `@cratis/scene.primereact`, optional only in that
@@ -134,6 +127,23 @@ the type, data or options change in content, not when a document edit hands it e
 rewriting the stored element. Any other type is reported instead of drawn as a bar chart. A chart without data
 points shows its `emptyLabel`.
 
+### Quill peer dependency
+
+`quill` is not imported by the package root, so a host that renders no rich text needs neither `quill` nor its
+stylesheet to build. A host that wants editable rich text installs `quill@^2.0.3` and opts in explicitly:
+
+```tsx
+import 'quill/dist/quill.snow.css';
+import { QuillLoaderProvider } from '@cratis/scene.primereact';
+import { loadQuill } from '@cratis/scene.primereact/quill';
+
+<QuillLoaderProvider loader={loadQuill}>{screen}</QuillLoaderProvider>
+```
+
+`@cratis/scene.primereact/quill` (sources in `loadQuill/`) is the only module that names `quill`. Without a
+loader the editor shows its content read-only and says so. Authored HTML always passes an allowlist first; see
+the [component reference](../../../Documentation/primereact-package/component-reference.md#rich-text-and-quill).
+
 ## Browser specifications
 
 Most specifications run under jsdom with `yarn test`. Painted pixels, keyboard behavior and computed theme
@@ -162,9 +172,9 @@ The short version for a contributor:
   compiles cleanly and silently swaps an overlay for a static shell.
 - **v11 ships zero CSS.** There is no `primereact/resources` directory. A look comes from a preset handed
   to `PrimeReactProvider`; `usePrimeReactTheme` returns that configuration for a Scene theme.
-- **14 abstract names are now backed by Cratis-owned components** built here because v11 removed theirs,
-  2 are expressed over `@primereact/headless` hooks, and 4 were dropped from the manifest
-  (`cascadeSelect`, `inputMask`, `treeTable`, `virtualScroller`).
+- **16 abstract names are now backed by Cratis-owned components** built here because v11 removed theirs,
+  2 are expressed over `@primereact/headless` hooks, and 3 were dropped from the manifest
+  (`cascadeSelect`, `inputMask`, `virtualScroller`).
 - **`MenuItem` and `TreeNode` are Scene's types now** - `primereact/menuitem` and `primereact/treenode`
   were removed. Import them from this package, never from `primereact/*`.
 

package/data/DataGallery.stories.tsx

@@ -37,7 +37,13 @@ export const Gallery: Story = {
             ),
             sceneComponent('dataTable', 'dataTable', { rows: [{ id: 1, title: 'Inferred columns' }] }),
             sceneComponent('dataView', 'dataView', { rows: [{ title: 'Kickoff', description: 'Agree the scope' }] }),
+            sceneComponent('dataScroller', 'dataScroller', { items: ['First', 'Second', 'Third'], rows: 2, inline: true, scrollHeight: 96 }),
             sceneComponent('tree', 'tree', { nodes: [{ label: 'Documents', children: ['Work', 'Home'] }] }),
+            sceneComponent('treeTable', 'treeTable', {
+                columns: [{ field: 'name', header: 'Name' }, { field: 'type', header: 'Type' }],
+                items: [{ label: 'Documents', data: { name: 'Documents', type: 'Folder' }, children: [{ label: 'Plan', data: { name: 'Plan', type: 'File' } }] }],
+                selectionMode: 'checkbox', paginator: true, rows: 1,
+            }),
             sceneComponent('timeline', 'timeline', {
                 events: [{ title: 'Ordered', description: 'Order placed', date: '09:00' }, { title: 'Shipped', description: 'Left the depot', date: '14:20' }],
             }),

package/data/DataScrollerRow.tsx

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readableValue } from './readableValue';
+
+/** The fields that, when present as text, name a record. */
+const titleFields = ['label', 'title', 'name', 'text', 'header'];
+
+/**
+ * One authored data row, shown readably.
+ *
+ * A scalar is its text. A record is titled by its first text field among `label`, `title`, `name`, `text` and
+ * `header`, and every other field follows as a name and a readable value. No row is ever dumped as JSON.
+ */
+export function DataScrollerRow({ value }: { value: unknown }) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return <>{readableValue(value)}</>;
+
+    const record = value as Record<string, unknown>;
+    const titleField = titleFields.find(field => typeof record[field] === 'string' && record[field] !== '');
+    const details = Object.entries(record)
+        .filter(([name]) => name !== titleField)
+        .map(([name, entry]) => [name, readableValue(entry)] as const)
+        .filter(([, text]) => text !== '');
+
+    return (
+        <>
+            {titleField !== undefined && <strong>{record[titleField] as string}</strong>}
+            {details.length > 0 && (
+                <dl>
+                    {details.map(([name, text]) => <div key={name}><dt>{name}</dt><dd>{text}</dd></div>)}
+                </dl>
+            )}
+        </>
+    );
+}

package/data/PrimeDataScroller.tsx

@@ -0,0 +1,84 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, useEffect, useMemo, useRef } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { arrayProperty, booleanProperty, numberProperty, stringProperty } from '../properties';
+import { useStructuralValue } from '../useStructuralValue';
+import { DataScrollerRow } from './DataScrollerRow';
+import { isSerializedLegacyElement, legacyElementMessage } from './isSerializedLegacyElement';
+import { useIncrementalLoad } from './useIncrementalLoad';
+import { useLoadOnReach } from './useLoadOnReach';
+
+/** How tall an inline scroller is when no `scrollHeight` was authored: without a height it would never overflow. */
+const defaultScrollHeight = 320;
+
+/**
+ * The `PrimeReact:dataScroller` component, a list that loads a chunk at a time as its end is reached.
+ *
+ * The entries are read as data: strings, numbers and records (see {@link DataScrollerRow}) from `items`, then
+ * any child elements authored in the `items` (or `content`) slot, which render as themselves. Serialized
+ * legacy UI elements in `items` are refused with a visible message, not shown as JSON.
+ *
+ * - `inline: true` scrolls inside the control, `scrollHeight` pixels tall (320 when omitted). `inline: false`
+ *   loads as the page scrolls the end of the list into view.
+ * - The "Load more" button remains for keyboard and assistive technology; focus moves to the first entry it
+ *   loads, and the number shown is announced.
+ * - A disabled element loads nothing on scroll and its button is disabled.
+ * - The loaded count restarts when `rows` or the content of `items` changes.
+ */
+export function PrimeDataScroller({ element, slots, interactions }: RegisteredComponentProps) {
+    const authored = useStructuralValue(arrayProperty(element, 'items'));
+    const data = useMemo(() => authored.filter(entry => !isSerializedLegacyElement(entry) && entry !== null && entry !== undefined), [authored]);
+    const refusal = legacyElementMessage(authored, 'items', "Author them as child elements in the 'items' slot, or as data.");
+    const slotted = slots.items ?? slots.content ?? [];
+    const rows = useMemo<ReactNode[]>(() => [...data.map((value, index) => <DataScrollerRow key={index} value={value} />), ...slotted], [data, slotted]);
+    const chunk = Math.max(Math.floor(numberProperty(element, 'rows', 10)), 1);
+    const inline = booleanProperty(element, 'inline', false);
+    const scrollHeight = numberProperty(element, 'scrollHeight', defaultScrollHeight);
+    const enabled = element.isEnabled;
+    const { loaded, loadMore } = useIncrementalLoad(rows.length, chunk, data);
+    const canLoad = loaded < rows.length;
+    const scroller = useRef<HTMLDivElement>(null);
+    const sentinel = useRef<HTMLDivElement>(null);
+    const entries = useRef<(HTMLLIElement | null)[]>([]);
+    const focusIndex = useRef<number | undefined>(undefined);
+
+    useLoadOnReach(sentinel, inline ? scroller : null, enabled && canLoad, loaded, loadMore);
+
+    useEffect(() => {
+        if (focusIndex.current === undefined) return;
+        entries.current[focusIndex.current]?.focus();
+        focusIndex.current = undefined;
+    }, [loaded]);
+
+    const loadByButton = () => {
+        focusIndex.current = loaded;
+        loadMore();
+    };
+
+    return (
+        <div
+            data-scene-id={element.id}
+            data-scene-component='dataScroller'
+            aria-disabled={!enabled}
+            onClick={interactions?.onClick}
+            onDoubleClick={interactions?.onDoubleClick}>
+            <div
+                ref={scroller}
+                role='region'
+                tabIndex={inline ? 0 : undefined}
+                aria-label={stringProperty(element, 'ariaLabel', 'Scrollable data')}
+                style={inline ? { maxHeight: `${scrollHeight}px`, overflowY: 'auto' } : undefined}>
+                <ol>
+                    {rows.slice(0, loaded).map((row, index) => <li key={index} tabIndex={-1} ref={node => { entries.current[index] = node; }}>{row}</li>)}
+                </ol>
+                {canLoad && <div ref={sentinel} aria-hidden='true' />}
+            </div>
+            {rows.length === 0 && <p role='status'>{stringProperty(element, 'emptyLabel', 'No items to show')}</p>}
+            {refusal !== undefined && <p role='alert' data-scene-state='legacy-elements'>{refusal}</p>}
+            {canLoad && <button type='button' disabled={!enabled} onClick={loadByButton}>Load more</button>}
+            {rows.length > 0 && <output aria-live='polite'>{`Showing ${loaded} of ${rows.length} items`}</output>}
+        </div>
+    );
+}

package/data/PrimeTreeTable.tsx

@@ -0,0 +1,145 @@
+// 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 } from '@cratis/scene.react';
+import { arrayProperty, booleanProperty, numberProperty, stringProperty } from '../properties';
+import { resolveEnumeration } from '../resolveEnumeration';
+import { countUnreadableEntries, toTreeNodes } from '../treeNodes';
+import { useResettingState } from '../useResettingState';
+import { useStructuralValue } from '../useStructuralValue';
+import { ColumnDefinition } from './ColumnDefinition';
+import { TreeTableRow } from './TreeTableRow';
+import { TreeTableRowView } from './TreeTableRowView';
+import { TreeTableSelectionMode } from './TreeTableSelectionMode';
+import { columnDefinitions } from './columnDefinitions';
+import { SettledSelection, settleSelection, toggleCheckbox } from './checkboxSelection';
+import { isSerializedLegacyElement, legacyElementMessage } from './isSerializedLegacyElement';
+import { selectionKeysOf } from './selectionKeysOf';
+import { expandedKeysOf, visibleRows } from './treeTableRows';
+import { useTreeGridNavigation } from './useTreeGridNavigation';
+
+const labelColumn: ColumnDefinition[] = [{ field: 'label', header: 'Label', sortable: false }];
+
+/**
+ * The `PrimeReact:treeTable` component, an ARIA tree grid over the canonical Scene node and column properties.
+ *
+ * `items` is an array of nodes - strings, numbers, or records with `key`, `label`, `data`, `children`,
+ * `expanded` and `selectable` - and the columns come from nested `column` elements, a `columns` property or the
+ * fields of the first row's `data`, in that order (see `columnDefinitions`). Serialized legacy UI elements in
+ * `items` or `columns` are refused with a visible message; see the package documentation for how they map to
+ * canonical slots.
+ *
+ * - Selection follows the authored `selection` (keys, numbers, `{ key }` objects or PrimeReact's key map) and
+ *   starts over when it changes; expansion starts from the authored `expanded` flags the same way. An unrelated
+ *   property edit leaves what the user did alone.
+ * - In checkbox mode a parent checks and unchecks its subtree and shows a partial state when only some of it is
+ *   checked.
+ * - The rows form a `treegrid` with a roving tab index and the usual arrow-key navigation.
+ * - Object cell values are shown readably, never as `[object Object]`.
+ */
+export function PrimeTreeTable({ element, interactions }: RegisteredComponentProps) {
+    const authoredItems = useStructuralValue(arrayProperty(element, 'items'));
+    const items = useMemo(() => authoredItems.filter(entry => !isSerializedLegacyElement(entry)), [authoredItems]);
+    const nodes = useMemo(() => toTreeNodes(items), [items]);
+    const modeResolution = resolveEnumeration('selectionMode', element.properties.selectionMode, TreeTableSelectionMode, TreeTableSelectionMode.None);
+    const mode = modeResolution.isValid ? modeResolution.value : TreeTableSelectionMode.None;
+    const enabled = element.isEnabled;
+    const pageSize = Math.max(Math.floor(numberProperty(element, 'rows', 10)), 1);
+    const paginator = booleanProperty(element, 'paginator', false);
+    const [expanded, setExpanded] = useResettingState(expandedKeysOf(nodes), () => new Set(expandedKeysOf(nodes)));
+    const [requested, setRequested] = useResettingState(element.properties.selection, () => selectionKeysOf(element.properties.selection));
+    const [page, setPage] = useState(0);
+    const pageCount = Math.max(Math.ceil(nodes.length / pageSize), 1);
+    const currentPage = Math.min(page, pageCount - 1);
+    const rows = useMemo(() => visibleRows(paginator ? nodes.slice(currentPage * pageSize, (currentPage + 1) * pageSize) : nodes, expanded), [nodes, paginator, currentPage, pageSize, expanded]);
+    const settled = useMemo<SettledSelection>(
+        () => mode === TreeTableSelectionMode.Checkbox ? settleSelection(nodes, requested) : { checked: requested, states: new Map() },
+        [mode, nodes, requested]
+    );
+    const columns = useMemo(() => {
+        const first = rows.find(row => typeof row.node.data === 'object' && row.node.data !== null && !Array.isArray(row.node.data))?.node.data as Record<string, unknown> | undefined;
+        const defined = columnDefinitions(element, first === undefined ? [] : [first]);
+        return defined.length > 0 ? defined : labelColumn;
+    }, [element, rows]);
+
+    useEffect(() => setPage(current => Math.min(current, pageCount - 1)), [pageCount]);
+
+    const toggle = (key: string) => {
+        if (enabled) setExpanded(current => {
+            const next = new Set(current);
+            if (next.has(key)) next.delete(key); else next.add(key);
+            return next;
+        });
+    };
+
+    const select = (row: TreeTableRow) => {
+        if (mode === TreeTableSelectionMode.None || !enabled || row.node.selectable === false) return;
+        if (mode === TreeTableSelectionMode.Checkbox) {
+            setRequested(toggleCheckbox(nodes, settled, row.node));
+        } else if (mode === TreeTableSelectionMode.Single) {
+            setRequested(new Set([row.key]));
+        } else {
+            const next = new Set(settled.checked);
+            if (next.has(row.key)) next.delete(row.key); else next.add(row.key);
+            setRequested(next);
+        }
+
+        interactions?.onSelect?.();
+        interactions?.onChange?.();
+    };
+
+    const navigation = useTreeGridNavigation({ rows, expanded, enabled, toggle, select });
+    const changePage = (target: number) => { if (enabled && target >= 0 && target < pageCount) setPage(target); };
+    const refusals = [
+        modeResolution.isValid ? undefined : modeResolution.message,
+        legacyElementMessage(authoredItems, 'items', 'Provide items as node data: strings, numbers, or records with key, label, data and children.'),
+        legacyElementMessage(arrayProperty(element, 'columns'), 'columns', "Author them as child elements in the 'columns' slot, or as column definitions."),
+    ].filter((message): message is string => message !== undefined);
+    const skipped = countUnreadableEntries(items);
+
+    return (
+        <div data-scene-id={element.id} data-scene-component='treeTable' aria-disabled={!enabled} onClick={interactions?.onClick} onDoubleClick={interactions?.onDoubleClick}>
+            <table
+                role='treegrid'
+                aria-label={stringProperty(element, 'ariaLabel', 'Hierarchical data')}
+                aria-multiselectable={mode === TreeTableSelectionMode.Multiple || mode === TreeTableSelectionMode.Checkbox ? true : undefined}>
+                <thead>
+                    <tr role='row'>{columns.map((column, index) => <th key={index} role='columnheader'>{column.header}</th>)}</tr>
+                </thead>
+                <tbody>
+                    {rows.map(row => (
+                        <TreeTableRowView
+                            key={row.key}
+                            row={row}
+                            columns={columns}
+                            mode={mode}
+                            enabled={enabled}
+                            expanded={expanded.has(row.key)}
+                            selected={settled.checked.has(row.key)}
+                            checkState={settled.states.get(row.key)}
+                            tabStop={navigation.tabStopKey === row.key}
+                            register={navigation.register}
+                            onActivate={() => navigation.activate(row.key)}
+                            onToggle={() => toggle(row.key)}
+                            onSelect={() => select(row)}
+                            onKeyDown={event => navigation.onKeyDown(row, event)}
+                        />
+                    ))}
+                    {rows.length === 0 && (
+                        <tr role='row'><td role='gridcell' colSpan={columns.length}>{stringProperty(element, 'emptyLabel', 'No records found')}</td></tr>
+                    )}
+                </tbody>
+            </table>
+            {paginator && (
+                <nav aria-label='Tree table pages'>
+                    <button type='button' aria-disabled={!enabled || currentPage === 0} onClick={() => changePage(currentPage - 1)}>Previous</button>
+                    <span>{currentPage + 1} / {pageCount}</span>
+                    <button type='button' aria-disabled={!enabled || currentPage + 1 >= pageCount} onClick={() => changePage(currentPage + 1)}>Next</button>
+                </nav>
+            )}
+            {refusals.map(message => <p key={message} role='alert' data-scene-state='refused'>{message}</p>)}
+            {skipped > 0 && <p role='status'>{`${skipped} entr${skipped === 1 ? 'y' : 'ies'} of items could not be read as a node and ${skipped === 1 ? 'was' : 'were'} skipped.`}</p>}
+        </div>
+    );
+}

package/data/TreeTableCheckState.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** How much of a tree table row's subtree is checked, in checkbox selection mode. */
+export enum TreeTableCheckState {
+    Unchecked = 'unchecked',
+    Partial = 'partial',
+    Checked = 'checked',
+}

package/data/TreeTableRow.ts

@@ -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 { TreeNode } from '../TreeNode';
+
+/** One visible row of a tree table, with where it sits in the tree. */
+export interface TreeTableRow {
+    node: TreeNode;
+    key: string;
+
+    /** Zero for a root row. */
+    depth: number;
+
+    /** The key of the parent row, `undefined` for a root row. */
+    parentKey: string | undefined;
+
+    /** The 1-based position among the siblings, for `aria-posinset`. */
+    position: number;
+
+    /** The number of siblings, for `aria-setsize`. */
+    siblings: number;
+}

package/data/TreeTableRowView.tsx

@@ -0,0 +1,86 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ColumnDefinition } from './ColumnDefinition';
+import { TreeTableCheckState } from './TreeTableCheckState';
+import { TreeTableRow } from './TreeTableRow';
+import { TreeTableSelectionMode } from './TreeTableSelectionMode';
+import { nodeLabel } from './treeTableRows';
+import { readableValue } from './readableValue';
+
+export interface TreeTableRowViewProps {
+    row: TreeTableRow;
+    columns: ColumnDefinition[];
+    mode: TreeTableSelectionMode;
+    enabled: boolean;
+    expanded: boolean;
+    selected: boolean;
+    checkState: TreeTableCheckState | undefined;
+    tabStop: boolean;
+    register(key: string, element: HTMLElement | null): void;
+    onActivate(): void;
+    onToggle(): void;
+    onSelect(): void;
+    onKeyDown(event: React.KeyboardEvent<HTMLElement>): void;
+}
+
+/** One `row` of the tree grid: its cells, its expand button and, in checkbox mode, its tri-state checkbox. */
+export function TreeTableRowView({ row, columns, mode, enabled, expanded, selected, checkState, tabStop, register, onActivate, onToggle, onSelect, onKeyDown }: TreeTableRowViewProps) {
+    const { node } = row;
+    const label = nodeLabel(node);
+    const hasChildren = (node.children?.length ?? 0) > 0;
+    const selectionOffered = mode !== TreeTableSelectionMode.None;
+    const rowSelectable = selectionOffered && node.selectable !== false;
+
+    return (
+        <tr
+            ref={element => register(row.key, element)}
+            role='row'
+            tabIndex={tabStop ? 0 : -1}
+            aria-level={row.depth + 1}
+            aria-posinset={row.position}
+            aria-setsize={row.siblings}
+            aria-expanded={hasChildren ? expanded : undefined}
+            aria-selected={selectionOffered ? selected : undefined}
+            className={node.className}
+            onFocus={onActivate}
+            onKeyDown={onKeyDown}
+            onClick={event => {
+                onActivate();
+                if (mode === TreeTableSelectionMode.Single || mode === TreeTableSelectionMode.Multiple) {
+                    if (!(event.target as HTMLElement).closest('button, input')) onSelect();
+                }
+            }}>
+            {columns.map((column, index) => (
+                <td key={index} role='gridcell' style={index === 0 ? { paddingInlineStart: `${row.depth * 1.25}rem` } : undefined}>
+                    {index === 0 && hasChildren && (
+                        <button type='button' tabIndex={-1} disabled={!enabled} aria-expanded={expanded} aria-label={`${expanded ? 'Collapse' : 'Expand'} ${label}`} onClick={onToggle}>
+                            {expanded ? 'Collapse' : 'Expand'}
+                        </button>
+                    )}
+                    {index === 0 && mode === TreeTableSelectionMode.Checkbox && checkState !== undefined && (
+                        <input
+                            type='checkbox'
+                            tabIndex={-1}
+                            ref={input => { if (input !== null) input.indeterminate = checkState === TreeTableCheckState.Partial; }}
+                            checked={checkState === TreeTableCheckState.Checked}
+                            disabled={!enabled || !rowSelectable}
+                            aria-label={`Select ${label}`}
+                            aria-checked={checkState === TreeTableCheckState.Partial ? 'mixed' : checkState === TreeTableCheckState.Checked}
+                            onChange={onSelect}
+                        />
+                    )}
+                    {cellText(row, column.field, index === 0)}
+                </td>
+            ))}
+        </tr>
+    );
+}
+
+function cellText(row: TreeTableRow, field: string, firstColumn: boolean): string {
+    const { data } = row.node;
+    const record = typeof data === 'object' && data !== null && !Array.isArray(data) ? data as Record<string, unknown> : undefined;
+    if (record !== undefined && record[field] !== undefined) return readableValue(record[field]);
+    if (!firstColumn) return '';
+    return row.node.label ?? (record === undefined ? readableValue(data) : '');
+}

package/data/TreeTableSelectionMode.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The canonical selection behavior for a hierarchical table. */
+export enum TreeTableSelectionMode {
+    None = 'none',
+    Single = 'single',
+    Multiple = 'multiple',
+    Checkbox = 'checkbox',
+}

package/data/checkboxSelection.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { TreeNode } from '../TreeNode';
+import { TreeTableCheckState } from './TreeTableCheckState';
+
+/** The outcome of settling a checkbox selection: the keys that are checked, and how each row reads. */
+export interface SettledSelection {
+    checked: Set<string>;
+    states: Map<string, TreeTableCheckState>;
+}
+
+const selectable = (node: TreeNode) => node.selectable !== false;
+
+/**
+ * Settles a checkbox selection against the tree, the way a checkbox tree reads:
+ * - a checked parent has all of its selectable descendants checked;
+ * - a parent is checked when all of its selectable children are, partially checked when some are, and
+ *   unchecked otherwise;
+ * - a node that is not selectable, and has nothing selectable below it, takes no part.
+ *
+ * Applying this to what the user toggled, or to an authored selection, is what keeps both consistent.
+ *
+ * @param nodes The root nodes.
+ * @param requested The keys asked for.
+ */
+export function settleSelection(nodes: TreeNode[], requested: ReadonlySet<string>): SettledSelection {
+    const cascaded = new Set<string>();
+    const cascade = (node: TreeNode, inherited: boolean) => {
+        const on = inherited || requested.has(node.key ?? '');
+        if (on) cascaded.add(node.key ?? '');
+        node.children?.forEach(child => cascade(child, on));
+    };
+    nodes.forEach(node => cascade(node, false));
+
+    const checked = new Set<string>();
+    const states = new Map<string, TreeTableCheckState>();
+    const settle = (node: TreeNode): TreeTableCheckState | undefined => {
+        const key = node.key ?? '';
+        const childStates = (node.children ?? []).map(settle).filter((state): state is TreeTableCheckState => state !== undefined);
+        let state: TreeTableCheckState | undefined;
+        if (childStates.length === 0) {
+            state = selectable(node) ? (cascaded.has(key) ? TreeTableCheckState.Checked : TreeTableCheckState.Unchecked) : undefined;
+        } else if (childStates.every(child => child === TreeTableCheckState.Checked)) {
+            state = TreeTableCheckState.Checked;
+        } else {
+            state = childStates.some(child => child !== TreeTableCheckState.Unchecked) ? TreeTableCheckState.Partial : TreeTableCheckState.Unchecked;
+        }
+
+        if (state !== undefined) states.set(key, state);
+        if (state === TreeTableCheckState.Checked) checked.add(key);
+        return state;
+    };
+    nodes.forEach(settle);
+
+    return { checked, states };
+}
+
+/**
+ * Toggles one row's checkbox: a checked row unchecks its whole subtree, any other row checks it.
+ *
+ * @param nodes The root nodes.
+ * @param settled The current settled selection.
+ * @param node The row's node.
+ * @returns The keys to settle again.
+ */
+export function toggleCheckbox(nodes: TreeNode[], settled: SettledSelection, node: TreeNode): Set<string> {
+    const subtree: string[] = [];
+    const collect = (current: TreeNode) => {
+        subtree.push(current.key ?? '');
+        current.children?.forEach(collect);
+    };
+    collect(node);
+
+    const next = new Set(settled.checked);
+    const checking = settled.states.get(node.key ?? '') !== TreeTableCheckState.Checked;
+    subtree.forEach(key => { if (checking) next.add(key); else next.delete(key); });
+
+    // A checked ancestor would check the unchecked subtree again, so unchecking also unchecks the ancestors.
+    if (!checking) (ancestorKeys(nodes, node.key ?? '') ?? []).forEach(key => next.delete(key));
+    return settleSelection(nodes, next).checked;
+}
+
+function ancestorKeys(nodes: TreeNode[], key: string, path: string[] = []): string[] | undefined {
+    for (const node of nodes) {
+        if (node.key === key) return path;
+        const found = ancestorKeys(node.children ?? [], key, [...path, node.key ?? '']);
+        if (found !== undefined) return found;
+    }
+
+    return undefined;
+}

package/data/index.ts

@@ -13,3 +13,7 @@ export * from './PrimePaginator';
 export * from './PrimeOrderList';
 export * from './PrimePickList';
 export * from './PrimeOrganizationChart';
+export * from './PrimeDataScroller';
+export * from './PrimeTreeTable';
+export * from './TreeTableSelectionMode';
+export * from './readableValue';

package/data/isSerializedLegacyElement.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Whether an entry is a serialized legacy UI element - an object that names its type in `_derivedTypeId`.
+ *
+ * The original `ItemsControl.Items` and `TreeTable.Columns` held UI elements, not data. Scene does not
+ * read those shapes and has no runtime adapter for them: the controls recognize them only to refuse them
+ * visibly, instead of listing the element's fields as if they were rows. Converting them is the migration
+ * tool's job, which maps each element to a canonical slot (see the package documentation).
+ *
+ * @param entry An entry of `items` or `columns`.
+ */
+export function isSerializedLegacyElement(entry: unknown): boolean {
+    return typeof entry === 'object' && entry !== null && !Array.isArray(entry) && typeof (entry as { _derivedTypeId?: unknown })._derivedTypeId === 'string';
+}
+
+/**
+ * The message for entries that were refused, or `undefined` when there were none.
+ *
+ * @param entries The authored entries.
+ * @param property The property they came from.
+ * @param guidance What the author should do instead, finishing the sentence "Author them ..." or similar.
+ */
+export function legacyElementMessage(entries: unknown[], property: string, guidance: string): string | undefined {
+    const refused = entries.filter(isSerializedLegacyElement).length;
+    return refused === 0
+        ? undefined
+        : `${refused} entr${refused === 1 ? 'y' : 'ies'} of ${property} ${refused === 1 ? 'is a' : 'are'} serialized legacy UI element${refused === 1 ? '' : 's'}, which this control does not read. ${guidance}`;
+}