@cratis/scene.primereact 4.5.0 → 4.7.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,15 +109,47 @@ 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 |
-| --- | --- |
-| `chart` | PrimeReact's `Chart` is a thin wrapper over Chart.js and does nothing without `chart.js` installed and a full Chart.js configuration object. Adding a charting library as a dependency of a component-mapping package is out of scope; charting deserves its own Scene package with its own vocabulary. |
-| `editor` | `Editor` wraps Quill and needs `quill` installed. Same reasoning — a rich-text editor is a product decision, not a mapping. |
+### 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
+a host that never renders a chart can omit it. **A host that renders charts must install `chart.js`**,
+including when a bundler resolves imports statically: without it the build can fail to resolve
+`chart.js/auto`, or the chart reports that it could not be drawn.
+
+The adapter only imports Chart.js after its canvas mounts, which keeps SSR safe. It rebuilds the chart when
+the type, data or options change in content, not when a document edit hands it equal data in a new object.
+
+`chart` accepts canonical string types (`bar`, `line`, `pie`, `doughnut`, `polarArea`, `radar`, `bubble`,
+`scatter`), the numeric values `0` to `7` of the old .NET enum, and that enum's Pascal case names, without
+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
 
-Both are genuinely useful and both are deliberate omissions, not oversights. A profile needing them
-should activate a package that owns that dependency.
+Most specifications run under jsdom with `yarn test`. Painted pixels, keyboard behavior and computed theme
+styles need a real browser, so `yarn test:browser` bundles the controls and drives headless Chromium through
+`playwright-core`. Install the browser once with `yarn playwright-core install chromium`. These specifications
+are not part of `yarn test` and fail, rather than skip, when Chromium is missing.
 
 Also worth knowing: `column` renders nothing on its own, and since PrimeReact 11 that is *our* semantics
 rather than PrimeReact's. v11 removed `primereact/column`, so `data/Column.tsx` is a Cratis-owned
@@ -140,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/chart/ChartGallery.stories.tsx

@@ -0,0 +1,63 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { SceneElementView } from '@cratis/scene.react';
+import { primeReactComponents } from '../primeReactComponents';
+import { sceneComponent } from '../storyElements';
+
+const meta = {
+    title: 'PrimeReact/Chart',
+    component: SceneElementView,
+    tags: ['autodocs'],
+} satisfies Meta<typeof SceneElementView>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** A Chart.js chart rendered through the Scene element and package registry. */
+const salesData = {
+    labels: ['January', 'February', 'March'],
+    datasets: [{ label: 'Sales', data: [12, 19, 8], backgroundColor: '#6366f1' }],
+};
+
+export const Bar: Story = {
+    args: {
+        element: sceneComponent('sales', 'chart', {
+            type: 'bar', data: salesData, options: { maintainAspectRatio: false }, style: { height: 240 }, ariaLabel: 'Monthly sales',
+        }),
+        registry: primeReactComponents,
+        resolveBinding: () => undefined,
+    },
+};
+
+/** A migrated chart that has no data yet. It says so instead of drawing a blank canvas or inventing values. */
+export const MigratedWithoutData: Story = {
+    args: {
+        element: sceneComponent('legacy-empty', 'chart', { type: 0, style: { height: 72 }, ariaLabel: 'Migrated chart without data', legacyType: 'PrimeReact.Chart' }),
+        registry: primeReactComponents,
+        resolveBinding: () => undefined,
+    },
+};
+
+/** A chart type the renderer does not know is reported rather than drawn as a bar chart. */
+export const UnsupportedType: Story = {
+    args: {
+        element: sceneComponent('unsupported', 'chart', { type: 8, data: salesData }),
+        registry: primeReactComponents,
+        resolveBinding: () => undefined,
+    },
+};
+
+/** A migrated element that retains the original numeric ChartType enum value in its own properties. */
+export const MigratedLegacyBar: Story = {
+    args: {
+        element: sceneComponent('legacy-sales', 'chart', {
+            type: 0, data: salesData, options: { maintainAspectRatio: false }, style: { height: 240 }, ariaLabel: 'Migrated monthly sales',
+            legacyType: 'PrimeReact.Chart', legacyExtras: { canvas: { x: 256, y: 184 } },
+        }),
+        registry: primeReactComponents,
+        resolveBinding: () => undefined,
+    },
+};

package/chart/ChartType.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The canonical names of the Chart.js chart types Scene's `chart` component supports. */
+export enum ChartType {
+    Bar = 'bar',
+    Line = 'line',
+    Pie = 'pie',
+    Doughnut = 'doughnut',
+    PolarArea = 'polarArea',
+    Radar = 'radar',
+    Bubble = 'bubble',
+    Scatter = 'scatter',
+}

package/chart/ChartTypeResolution.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ChartType } from './ChartType';
+
+/**
+ * What an authored chart `type` resolved to: a Chart.js type, or the reason it names none.
+ *
+ * A value that is not a known type is never replaced by a default. Drawing a bar chart for a document that
+ * asked for something else hides a data problem behind a plausible picture.
+ */
+export type ChartTypeResolution =
+    | { isValid: true; type: ChartType }
+    | { isValid: false; value: unknown; message: string };

package/chart/PrimeChart.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CSSProperties, useMemo, useRef } from 'react';
+import type { ChartConfiguration, ChartData, ChartOptions } from 'chart.js';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { booleanProperty, recordProperty, stringProperty } from '../properties';
+import { useStructuralValue } from '../useStructuralValue';
+import { chartHasData } from './chartHasData';
+import { resolveChartType } from './resolveChartType';
+import { useChart } from './useChart';
+
+/**
+ * The `PrimeReact:chart` component, rendered by Chart.js because PrimeReact 11 no longer ships its
+ * former Chart.js wrapper.
+ *
+ * Three states are explicit rather than a blank canvas: an unsupported `type` is reported (the right chart
+ * cannot be guessed), a chart with no data points shows its `emptyLabel` (data is never invented), and a
+ * chart Chart.js could not draw says why. Only a chart with data and a supported type reaches Chart.js.
+ *
+ * Chart.js is an optional peer dependency of this package: a host that renders charts must install
+ * `chart.js` itself. The chart rebuilds only when its resolved type, data or options change in content -
+ * every edit to a Scene document clones the whole document, and a clone with equal content is not a change.
+ *
+ * The chart fills the authored size: `maintainAspectRatio` defaults to `false` here (Chart.js defaults to
+ * `true`, which shrinks the chart inside its box) and an authored `options.maintainAspectRatio` wins. The
+ * `responsive` property is authoritative over `options.responsive` when both are set.
+ */
+export function PrimeChart({ element, interactions }: RegisteredComponentProps) {
+    const canvas = useRef<HTMLCanvasElement>(null);
+    const resolution = resolveChartType(element);
+    const data = useStructuralValue(recordProperty(element, 'data') as ChartData | undefined);
+    const options = useStructuralValue(recordProperty(element, 'options') as ChartOptions | undefined);
+    const style = recordProperty(element, 'style') as CSSProperties | undefined;
+    const responsive = booleanProperty(element, 'responsive', options?.responsive ?? true);
+    const ariaLabel = stringProperty(element, 'ariaLabel', element.name || 'Chart');
+    const emptyLabel = stringProperty(element, 'emptyLabel', 'No chart data');
+    const hasData = chartHasData(data);
+    const type = resolution.isValid ? resolution.type : undefined;
+    const enabled = type !== undefined && hasData;
+
+    const configuration = useMemo(() => ({
+        type,
+        data: data ?? { datasets: [] },
+        options: { maintainAspectRatio: false, ...options, responsive },
+    }) as unknown as ChartConfiguration, [type, data, options, responsive]);
+
+    const failure = useChart(canvas, configuration, enabled);
+
+    return (
+        <div
+            data-scene-id={element.id}
+            data-scene-component='chart'
+            style={{ position: 'relative', width: element.size.width ?? '100%', height: element.size.height ?? '100%', ...style }}
+            {...interactions}>
+            {!resolution.isValid && <div role='alert' data-scene-state='unsupported-type'>{resolution.message}</div>}
+            {resolution.isValid && !hasData && <div role='status' data-scene-state='empty'>{emptyLabel}</div>}
+            {failure !== undefined && <div role='alert' data-scene-state='unavailable'>{`The chart could not be drawn: ${failure}`}</div>}
+            {enabled && <canvas ref={canvas} role='img' aria-label={ariaLabel} hidden={failure !== undefined} />}
+        </div>
+    );
+}

package/chart/chartHasData.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.
+
+/**
+ * Whether chart data holds at least one data point to draw.
+ *
+ * Datasets whose `data` is empty (or absent) draw nothing but axes, so the chart reports it instead.
+ * A dataset may also give its points as keyed records (Chart.js `parsing` over an object), which counts
+ * when it has any keys.
+ */
+export function chartHasData(data: unknown): boolean {
+    if (data === null || typeof data !== 'object') return false;
+    const datasets = (data as Record<string, unknown>).datasets;
+    if (!Array.isArray(datasets)) return false;
+
+    return datasets.some(dataset => {
+        if (dataset === null || typeof dataset !== 'object') return false;
+        const points = (dataset as Record<string, unknown>).data;
+        if (Array.isArray(points)) return points.length > 0;
+        return points !== null && typeof points === 'object' && Object.keys(points).length > 0;
+    });
+}

package/chart/chartTypeChoices.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 { PropertyChoice } from '@cratis/scene.model';
+import { ChartType } from './ChartType';
+import { legacyChartTypes } from './resolveChartType';
+
+const chartTypeLabels: Record<ChartType, string> = {
+    [ChartType.Bar]: 'Bar',
+    [ChartType.Line]: 'Line',
+    [ChartType.Pie]: 'Pie',
+    [ChartType.Doughnut]: 'Doughnut',
+    [ChartType.PolarArea]: 'Polar area',
+    [ChartType.Radar]: 'Radar',
+    [ChartType.Bubble]: 'Bubble',
+    [ChartType.Scatter]: 'Scatter',
+};
+
+/**
+ * The chart type choices: the stable names new documents use, then the ordinals migrated documents carry,
+ * then the Pascal case member names of the original .NET enum that a serialized enum produces.
+ * A migrated chart stores its original `type`; offering every form the renderer accepts keeps that stored
+ * value valid (and its type visible and re-selectable) without rewriting it to another form behind the
+ * author's back. The choices are the same set `resolveChartType` accepts, so what the renderer draws is
+ * exactly what the descriptor allows.
+ */
+export const chartTypeChoices: PropertyChoice[] = [
+    ...Object.values(ChartType).map(type => ({ value: type, label: chartTypeLabels[type] })),
+    ...legacyChartTypes.map((type, ordinal) => ({ value: ordinal, label: `${chartTypeLabels[type]} (legacy ${ordinal})`, description: `The ordinal ${ordinal} of the original chart type enum, as stored by migrated documents.` })),
+    ...(Object.keys(ChartType) as (keyof typeof ChartType)[]).map(name => ({ value: name, label: `${chartTypeLabels[ChartType[name]]} (legacy name ${name})`, description: `The member name ${name} of the original chart type enum, as a serialized enum stores it.` })),
+];
+

package/chart/index.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.
+
+export * from './ChartType';
+export * from './ChartTypeResolution';
+export * from './PrimeChart';
+export * from './resolveChartType';

package/chart/resolveChartType.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { ChartType } from './ChartType';
+import { ChartTypeResolution } from './ChartTypeResolution';
+
+/**
+ * The ordinals of the original .NET `PrimeReact.Charts.ChartType` enum, in declaration order
+ * (`Studio/Source/PrimeReact/Charts/Chart.cs`). Migrated documents keep the ordinal, so the position of
+ * each entry here is part of the stored-data contract and must never be reordered.
+ */
+export const legacyChartTypes: readonly ChartType[] = [
+    ChartType.Bar,
+    ChartType.Line,
+    ChartType.Pie,
+    ChartType.Doughnut,
+    ChartType.PolarArea,
+    ChartType.Radar,
+    ChartType.Bubble,
+    ChartType.Scatter,
+];
+
+/**
+ * Resolves an authored chart type to the Chart.js vocabulary.
+ *
+ * Three forms are accepted, and the stored value is never rewritten:
+ * - a canonical Chart.js name from {@link ChartType} (`'polarArea'`), which new documents use;
+ * - the ordinal of the original .NET enum (`4`), which migrated documents carry;
+ * - the .NET member name in its original Pascal case (`'PolarArea'`), which a JSON serialization of that
+ *   enum produces.
+ *
+ * Anything else - an unknown or fractional ordinal, a numeric string, a differently cased name, `null` -
+ * resolves to a finding with a message, because the right chart cannot be known. An absent `type` is the
+ * one default: the original control defaulted to `Bar`.
+ */
+export function resolveChartType(element: SceneElement): ChartTypeResolution {
+    const value = element.properties.type;
+    if (value === undefined) return { isValid: true, type: ChartType.Bar };
+
+    if (typeof value === 'number') {
+        const type = Number.isInteger(value) ? legacyChartTypes[value] : undefined;
+        return type === undefined ? unsupported(value) : { isValid: true, type };
+    }
+
+    if (typeof value === 'string') {
+        if (Object.values(ChartType).includes(value as ChartType)) return { isValid: true, type: value as ChartType };
+        if (Object.hasOwn(ChartType, value)) return { isValid: true, type: ChartType[value as keyof typeof ChartType] };
+    }
+
+    return unsupported(value);
+}
+
+function unsupported(value: unknown): ChartTypeResolution {
+    const shown = typeof value === 'string' ? `'${value}'` : JSON.stringify(value) ?? String(value);
+    return {
+        isValid: false,
+        value,
+        message: `Unsupported chart type ${shown}. Use one of ${Object.values(ChartType).join(', ')}, or a legacy ordinal from 0 to ${legacyChartTypes.length - 1}.`,
+    };
+}

package/chart/useChart.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RefObject, useEffect, useState } from 'react';
+import type { ChartConfiguration } from 'chart.js';
+
+/**
+ * Draws a Chart.js chart on a canvas and owns its lifetime.
+ *
+ * Chart.js loads only after the canvas has mounted, which keeps server rendering independent of browser
+ * globals. The chart is destroyed before it is rebuilt and when the component unmounts - Chart.js owns
+ * listeners and resize observers, so a retained instance would draw twice and leak them.
+ *
+ * A chart that cannot be drawn is reported rather than left as a blank canvas: `chart.js` not being
+ * installed (it is an optional peer dependency), a failed dynamic import and a rejected configuration all
+ * come back as the returned failure message. A rejected configuration is released from the canvas as well,
+ * so correcting it draws again on the same canvas.
+ *
+ * @param canvas The canvas to draw on. It must be rendered whenever `enabled` is true.
+ * @param configuration The Chart.js configuration. Pass a structurally stable value (see
+ * {@link useStructuralValue}); a new identity rebuilds the chart.
+ * @param enabled Whether there is something to draw.
+ * @returns The reason the chart could not be drawn, or `undefined`.
+ */
+export function useChart(canvas: RefObject<HTMLCanvasElement | null>, configuration: ChartConfiguration, enabled: boolean): string | undefined {
+    const [failure, setFailure] = useState<string | undefined>(undefined);
+
+    useEffect(() => {
+        setFailure(undefined);
+        const target = canvas.current;
+        if (!enabled || target === null) return undefined;
+
+        let disposed = false;
+        let instance: { destroy(): void } | undefined;
+
+        const create = async () => {
+            let chartType: typeof import('chart.js/auto').default | undefined;
+            try {
+                chartType = (await import('chart.js/auto')).default;
+                if (disposed) return;
+                instance = new chartType(target, structuredClone(configuration));
+            } catch (error) {
+                // Chart.js registers a chart on its canvas before the constructor finishes, so a constructor
+                // that throws still leaves a registered instance behind - one `instance` never points at. Left
+                // alone it makes every later attempt fail with "Canvas is already in use" and hides the real
+                // reason, so release whatever is bound to this canvas before reporting.
+                chartType?.getChart(target)?.destroy();
+                if (!disposed) setFailure(error instanceof Error ? error.message : String(error));
+            }
+        };
+
+        void create();
+        return () => {
+            disposed = true;
+            instance?.destroy();
+            instance = undefined;
+        };
+    }, [canvas, configuration, enabled]);
+
+    return failure;
+}

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