@cratis/scene.primereact 4.5.0 → 4.7.0

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}`;
+}

package/data/readableValue.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Nested deeper than this is shown as an ellipsis, so a cyclic or enormous value cannot flood the page. */
+const maximumDepth = 3;
+
+/**
+ * Writes any authored value as text a person can read.
+ *
+ * Scalars are shown as they are. An array is its readable entries joined by commas, and an object is
+ * `name: value` pairs joined by semicolons - never `[object Object]`, and never a raw JSON document. `null`
+ * and `undefined` are empty.
+ *
+ * @param value The authored value.
+ * @param depth How deep the value is nested already; callers leave it out.
+ */
+export function readableValue(value: unknown, depth = 0): string {
+    if (value === undefined || value === null) return '';
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') return String(value);
+    if (depth >= maximumDepth) return '…';
+    if (Array.isArray(value)) return value.map(entry => readableValue(entry, depth + 1)).filter(text => text !== '').join(', ');
+    if (typeof value === 'object') {
+        return Object.entries(value)
+            .map(([name, entry]) => [name, readableValue(entry, depth + 1)])
+            .filter(([, text]) => text !== '')
+            .map(([name, text]) => `${name}: ${text}`)
+            .join('; ');
+    }
+
+    return '';
+}

package/data/selectionKeysOf.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The keys of one node, whichever of the shapes a selection may use. */
+function keyOf(value: unknown): string | undefined {
+    if (typeof value === 'string' && value !== '') return value;
+    return typeof value === 'number' && Number.isFinite(value) ? String(value) : undefined;
+}
+
+function nodeKeyOf(value: unknown): string | undefined {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return keyOf(value);
+    return keyOf((value as { key?: unknown }).key);
+}
+
+/**
+ * Reads the keys an authored `selection` selects.
+ *
+ * Every shape a legacy document may hold is accepted, and none is rewritten:
+ * - one key, string or number (`'b'`, `6`);
+ * - an array mixing keys and `{ key }` objects (`['a', 6, { key: 'c' }]`);
+ * - one `{ key }` object;
+ * - PrimeReact's key map (`{ b: { checked: true, partialChecked: false } }`), whose `checked` entries are
+ *   selected. A `partialChecked` entry is derived state, not a selection, so it is ignored: the control
+ *   computes it from the selected descendants.
+ *
+ * Numeric keys are matched as the strings the tree builds from them.
+ *
+ * @param value The authored selection.
+ */
+export function selectionKeysOf(value: unknown): Set<string> {
+    if (Array.isArray(value)) return new Set(value.flatMap(entry => nodeKeyOf(entry) ?? []));
+    const single = nodeKeyOf(value);
+    if (single !== undefined) return new Set([single]);
+
+    if (typeof value === 'object' && value !== null && keyOf((value as { key?: unknown }).key) === undefined) {
+        return new Set(Object.entries(value).filter(([, state]) => (state as { checked?: unknown } | null)?.checked === true).map(([key]) => key));
+    }
+
+    return new Set();
+}

package/data/treeTableRows.ts

@@ -0,0 +1,32 @@
+// 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 { TreeTableRow } from './TreeTableRow';
+
+/**
+ * Flattens the nodes into the rows that are visible: a node's children follow it only while it is expanded.
+ *
+ * @param nodes The sibling nodes to flatten.
+ * @param expanded The keys of the expanded nodes.
+ */
+export function visibleRows(nodes: TreeNode[], expanded: ReadonlySet<string>, depth = 0, parentKey?: string): TreeTableRow[] {
+    return nodes.flatMap((node, index) => {
+        const key = node.key ?? '';
+        const row: TreeTableRow = { node, key, depth, parentKey, position: index + 1, siblings: nodes.length };
+        return [row, ...(node.children !== undefined && expanded.has(key) ? visibleRows(node.children, expanded, depth + 1, key) : [])];
+    });
+}
+
+/** The keys of the nodes authored as expanded, at any depth, in tree order. */
+export function expandedKeysOf(nodes: TreeNode[]): string[] {
+    return nodes.flatMap(node => [
+        ...(node.expanded === true && node.key !== undefined ? [node.key] : []),
+        ...expandedKeysOf(node.children ?? []),
+    ]);
+}
+
+/** A node's own text for naming it: its label, else its key. */
+export function nodeLabel(node: TreeNode): string {
+    return node.label ?? node.key ?? '';
+}

package/data/useIncrementalLoad.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useCallback, useState } from 'react';
+
+/** How much of a list is loaded and how to load more. */
+export interface IncrementalLoad {
+    /** The number of entries loaded, never more than the total. */
+    loaded: number;
+
+    /** Loads the next chunk. */
+    loadMore(): void;
+}
+
+/**
+ * Tracks how many entries of a list are loaded, a chunk at a time.
+ *
+ * The count follows the authored properties: it starts over at one chunk when the chunk size changes or when
+ * `resetKey` does, so a document edit that replaces the items does not leave the old count behind. Pass a
+ * structurally stable `resetKey` (see `useStructuralValue`), or every render would reset it.
+ *
+ * @param total The number of entries there are.
+ * @param chunk The number of entries per load.
+ * @param resetKey Changes when the entries are replaced.
+ */
+export function useIncrementalLoad(total: number, chunk: number, resetKey: unknown): IncrementalLoad {
+    const [state, setState] = useState({ resetKey, chunk, loaded: chunk });
+    let loaded = state.loaded;
+    if (state.resetKey !== resetKey || state.chunk !== chunk) {
+        setState({ resetKey, chunk, loaded: chunk });
+        loaded = chunk;
+    }
+
+    const loadMore = useCallback(() => setState(current => ({ ...current, loaded: Math.min(current.loaded + chunk, total) })), [chunk, total]);
+    return { loaded: Math.min(loaded, total), loadMore };
+}

package/data/useLoadOnReach.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RefObject, useEffect } from 'react';
+
+/**
+ * Calls `onReach` while the sentinel is visible, which is what scrolling to the end of a list means.
+ *
+ * The observer is rebuilt whenever `revision` changes, so a sentinel that is still visible after a chunk was
+ * loaded loads the next one, until the viewport is filled or the list ends. `root` is the element that
+ * scrolls for an inline list; `null` observes the page's own viewport. Where there is no
+ * `IntersectionObserver` nothing is observed and the list's own button remains the way to load more.
+ *
+ * @param sentinel The element placed after the last loaded entry.
+ * @param root The scrolling container, or `null` for the page.
+ * @param active Whether reaching the end should load anything.
+ * @param revision A value that changes each time the list changed.
+ * @param onReach Loads the next chunk.
+ */
+export function useLoadOnReach(sentinel: RefObject<HTMLElement | null>, root: RefObject<HTMLElement | null> | null, active: boolean, revision: unknown, onReach: () => void): void {
+    useEffect(() => {
+        const target = sentinel.current;
+        if (!active || target === null || typeof IntersectionObserver === 'undefined') return undefined;
+
+        const observer = new IntersectionObserver(entries => {
+            if (entries.some(entry => entry.isIntersecting)) onReach();
+        }, { root: root?.current ?? null, rootMargin: '0px 0px 48px 0px' });
+        observer.observe(target);
+        return () => observer.disconnect();
+    }, [sentinel, root, active, revision, onReach]);
+}