@cratis/scene.primereact 4.6.0 → 4.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.primereact",
-    "version": "4.6.0",
+    "version": "4.8.0",
     "description": "The PrimeReact component package: maps Scene's abstract component names onto real PrimeReact components, and PrimeReact's free themes onto Scene themes.",
     "keywords": [
         "cratis",
@@ -38,6 +38,11 @@
             "require": "./dist/cjs/index.js",
             "import": "./dist/esm/index.js"
         },
+        "./quill": {
+            "types": "./dist/esm/loadQuill/index.d.ts",
+            "require": "./dist/cjs/loadQuill/index.js",
+            "import": "./dist/esm/loadQuill/index.js"
+        },
         "./primeReactTheme.css": "./primeReactTheme.css"
     },
     "scripts": {
@@ -54,15 +59,15 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.6.0",
-        "@cratis/scene.model": "4.6.0",
-        "@cratis/scene.react": "4.6.0",
+        "@cratis/scene.engine": "4.8.0",
+        "@cratis/scene.model": "4.8.0",
+        "@cratis/scene.react": "4.8.0",
         "@primeuix/themes": "^3.0.1"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.6.0",
-        "@cratis/scene.model": "4.6.0",
-        "@cratis/scene.react": "4.6.0",
+        "@cratis/scene.engine": "4.8.0",
+        "@cratis/scene.model": "4.8.0",
+        "@cratis/scene.react": "4.8.0",
         "@primereact/core": "11.2.0",
         "@primereact/headless": "11.2.0",
         "@primereact/types": "11.2.0",
@@ -74,6 +79,7 @@
         "playwright-core": "1.63.0",
         "primeicons": "8.0.2",
         "primereact": "11.2.0",
+        "quill": "2.0.3",
         "react": "^19.3.0",
         "react-dom": "^19.3.0",
         "storybook": "^10.6.1"
@@ -84,12 +90,16 @@
         "chart.js": "^4.5.1",
         "primeicons": "^8.0.0",
         "primereact": "^11.0.0",
+        "quill": "^2.0.3",
         "react": "^19.0.0",
         "react-dom": "^19.0.0"
     },
     "peerDependenciesMeta": {
         "chart.js": {
             "optional": true
+        },
+        "quill": {
+            "optional": true
         }
     }
 }

package/primeReactComponents.ts

@@ -6,6 +6,7 @@ import { PrimeButton, PrimeButtonGroup, PrimeSpeedDial, PrimeSplitButton } from
 import { PrimeChart } from './chart';
 import {
     PrimeColumn,
+    PrimeDataScroller,
     PrimeDataTable,
     PrimeDataView,
     PrimeOrderList,
@@ -14,6 +15,7 @@ import {
     PrimePickList,
     PrimeTimeline,
     PrimeTree,
+    PrimeTreeTable,
 } from './data';
 import {
     PrimeAutoComplete,
@@ -39,6 +41,8 @@ import {
     PrimeToggleSwitch,
     PrimeTreeSelect,
 } from './form';
+import { PrimeEditor } from './editor';
+import { PrimeFileUpload } from './file';
 import { PrimeCarousel, PrimeGalleria, PrimeImage } from './media';
 import {
     PrimeBreadcrumb,
@@ -121,6 +125,8 @@ export const primeReactComponents: ComponentRegistry = {
     [componentRegistryKey('PrimeReact', 'chips')]: PrimeChips,
     [componentRegistryKey('PrimeReact', 'autoComplete')]: PrimeAutoComplete,
     [componentRegistryKey('PrimeReact', 'treeSelect')]: PrimeTreeSelect,
+    [componentRegistryKey('PrimeReact', 'editor')]: PrimeEditor,
+    [componentRegistryKey('PrimeReact', 'fileUpload')]: PrimeFileUpload,
 
     [componentRegistryKey('PrimeReact', 'button')]: PrimeButton,
     [componentRegistryKey('PrimeReact', 'splitButton')]: PrimeSplitButton,
@@ -131,7 +137,9 @@ export const primeReactComponents: ComponentRegistry = {
     [componentRegistryKey('PrimeReact', 'table')]: PrimeDataTable,
     [componentRegistryKey('PrimeReact', 'column')]: PrimeColumn,
     [componentRegistryKey('PrimeReact', 'dataView')]: PrimeDataView,
+    [componentRegistryKey('PrimeReact', 'dataScroller')]: PrimeDataScroller,
     [componentRegistryKey('PrimeReact', 'tree')]: PrimeTree,
+    [componentRegistryKey('PrimeReact', 'treeTable')]: PrimeTreeTable,
     [componentRegistryKey('PrimeReact', 'timeline')]: PrimeTimeline,
     [componentRegistryKey('PrimeReact', 'paginator')]: PrimePaginator,
     [componentRegistryKey('PrimeReact', 'orderList')]: PrimeOrderList,

package/primeReactDescriptors.ts

@@ -4,7 +4,10 @@
 import { ComponentDescriptor, PropertyValueType } from '@cratis/scene.model';
 import { componentRegistryKey } from '@cratis/scene.react';
 import { chartTypeChoices } from './chart/chartTypeChoices';
+import { legacyEnumerationChoices } from './legacyEnumerationChoices';
 import { ChartType } from './chart';
+import { TreeTableSelectionMode } from './data';
+import { FileUploadMode } from './file';
 
 const key = (name: string) => componentRegistryKey('PrimeReact', name);
 
@@ -27,6 +30,66 @@ export const primeReactDescriptors: ComponentDescriptor[] = [
             { path: 'ariaLabel', label: 'Accessible name', group: 'Accessibility', valueType: PropertyValueType.String },
         ],
     },
+    {
+        component: key('fileUpload'),
+        displayName: 'File upload',
+        description: 'An accessible file picker and drop zone. A host provides its upload effect, or the files are posted to the authored server URL. The URL must be on the page\'s own origin unless the host allows another one.',
+        properties: [
+            {
+                path: 'mode', label: 'Mode', group: 'Behavior', valueType: PropertyValueType.Enum, default: FileUploadMode.Advanced,
+                choices: legacyEnumerationChoices(FileUploadMode, { [FileUploadMode.Advanced]: 'Advanced', [FileUploadMode.Basic]: 'Basic', [FileUploadMode.Auto]: 'Automatic' }),
+            },
+            { path: 'url', label: 'Server URL', group: 'Upload', valueType: PropertyValueType.String, description: 'Where the files are posted. Only the origin of the page, or an origin the host allows, is accepted; anything else is refused and nothing is sent.' },
+            { path: 'name', label: 'Request field name', group: 'Upload', valueType: PropertyValueType.String, default: 'files' },
+            { path: 'accept', label: 'Accepted MIME types', group: 'Upload', valueType: PropertyValueType.String },
+            { path: 'multiple', label: 'Allow multiple files', group: 'Behavior', valueType: PropertyValueType.Boolean, default: false },
+            { path: 'maxFileSize', label: 'Maximum file size', group: 'Upload', valueType: PropertyValueType.Number, constraints: { minimum: 0, integer: true } },
+            { path: 'ariaLabel', label: 'Accessible name', group: 'Accessibility', valueType: PropertyValueType.String },
+        ],
+    },
+    {
+        component: key('dataScroller'),
+        displayName: 'Data scroller',
+        description: 'A list that loads a chunk at a time as its end is reached. Items are strings, numbers or records, plus any child elements in the items slot; serialized legacy UI elements are refused.',
+        properties: [
+            { path: 'items', label: 'Items', group: 'Data', valueType: PropertyValueType.Json, description: 'Strings, numbers or records. A record is titled by its label, title, name, text or header field.' },
+            { path: 'rows', label: 'Rows per load', group: 'Behavior', valueType: PropertyValueType.Number, default: 10, constraints: { minimum: 1, integer: true } },
+            { path: 'inline', label: 'Scroll inline', group: 'Layout', valueType: PropertyValueType.Boolean, default: false, description: 'Scroll inside the control (true) or load as the page scrolls the end of the list into view (false).' },
+            { path: 'scrollHeight', label: 'Inline scroll height', group: 'Layout', valueType: PropertyValueType.Number, constraints: { minimum: 1 }, description: 'The height in pixels of an inline scroller. 320 when omitted.' },
+            { path: 'emptyLabel', label: 'No items label', group: 'Accessibility', valueType: PropertyValueType.String, default: 'No items to show' },
+            { path: 'ariaLabel', label: 'Accessible name', group: 'Accessibility', valueType: PropertyValueType.String },
+        ],
+    },
+    {
+        component: key('treeTable'),
+        displayName: 'Tree table',
+        description: 'A hierarchical table with authored columns, selection, and optional pagination. Items are nodes (strings, numbers or records with key, label, data, children); serialized legacy UI elements are refused.',
+        properties: [
+            { path: 'columns', label: 'Columns', group: 'Data', valueType: PropertyValueType.Json, description: 'Column definitions with field and header, or nested column elements. Inferred from the first row when absent.' },
+            { path: 'items', label: 'Items', group: 'Data', valueType: PropertyValueType.Json, description: 'The nodes: strings, numbers, or records with key, label, data, children, expanded and selectable.' },
+            {
+                path: 'selectionMode', label: 'Selection mode', group: 'Behavior', valueType: PropertyValueType.Enum, default: TreeTableSelectionMode.None,
+                choices: legacyEnumerationChoices(TreeTableSelectionMode, { [TreeTableSelectionMode.None]: 'None', [TreeTableSelectionMode.Single]: 'Single', [TreeTableSelectionMode.Multiple]: 'Multiple', [TreeTableSelectionMode.Checkbox]: 'Checkbox' }),
+            },
+            { path: 'selection', label: 'Selection', group: 'Behavior', valueType: PropertyValueType.Json, description: 'The selected node keys: a key, an array of keys or { key } objects, or PrimeReact\'s key map.' },
+            { path: 'paginator', label: 'Show pagination', group: 'Behavior', valueType: PropertyValueType.Boolean, default: false },
+            { path: 'rows', label: 'Rows per page', group: 'Behavior', valueType: PropertyValueType.Number, default: 10, constraints: { minimum: 1, integer: true } },
+            { path: 'emptyLabel', label: 'No records label', group: 'Accessibility', valueType: PropertyValueType.String, default: 'No records found' },
+            { path: 'ariaLabel', label: 'Accessible name', group: 'Accessibility', valueType: PropertyValueType.String },
+        ],
+    },
+    {
+        component: key('editor'),
+        displayName: 'Rich text editor',
+        description: 'A rich-text HTML editor. Editing needs the host to provide Quill (QuillLoaderProvider); without it the content is shown read-only. The HTML is sanitized before it is shown.',
+        properties: [
+            { path: 'value', label: 'HTML value', group: 'Content', valueType: PropertyValueType.String },
+            { path: 'placeholder', label: 'Placeholder', group: 'Content', valueType: PropertyValueType.String },
+            { path: 'showHeader', label: 'Show toolbar', group: 'Behavior', valueType: PropertyValueType.Boolean, default: true },
+            { path: 'readOnly', label: 'Read only', group: 'Behavior', valueType: PropertyValueType.Boolean, default: false },
+            { path: 'ariaLabel', label: 'Accessible name', group: 'Accessibility', valueType: PropertyValueType.String },
+        ],
+    },
     {
         component: key('multiStateCheckbox'),
         displayName: 'Multi-state checkbox',

package/primeReactPackage.ts

@@ -36,8 +36,8 @@ export const primeReactPackageManifest: ScenePackage = {
     components: [
         'inputText', 'inputTextarea', 'inputNumber', 'password', 'floatLabel', 'iconField', 'dropdown', 'multiSelect',
         'listBox', 'selectButton', 'checkbox', 'multiStateCheckbox', 'radioButton', 'toggleSwitch', 'slider', 'rating', 'knob', 'calendar', 'colorPicker',
-        'chips', 'autoComplete', 'treeSelect', 'button', 'splitButton', 'speedDial', 'buttonGroup', 'dataTable', 'table',
-        'column', 'dataView', 'tree', 'timeline', 'paginator', 'orderList', 'pickList', 'organizationChart', 'chart',
+        'chips', 'autoComplete', 'treeSelect', 'editor', 'fileUpload', 'button', 'splitButton', 'speedDial', 'buttonGroup', 'dataTable', 'table',
+        'column', 'dataView', 'dataScroller', 'tree', 'treeTable', 'timeline', 'paginator', 'orderList', 'pickList', 'organizationChart', 'chart',
         'card', 'panel', 'accordion', 'fieldset', 'divider', 'splitter', 'scrollPanel', 'tabView', 'toolbar', 'stepper', 'dialog',
         'confirmDialog', 'overlayPanel', 'sidebar', 'tooltip', 'menu', 'menubar', 'breadcrumb', 'tabMenu', 'steps', 'tieredMenu',
         'panelMenu', 'contextMenu', 'megaMenu', 'dock', 'message', 'inlineMessage', 'toast', 'image', 'galleria', 'carousel', 'avatar',

package/primeReactTheme.css

@@ -109,3 +109,72 @@
     background: var(--scene-surface-background);
     color: var(--scene-text-color);
 }
+
+/*
+ * The Cratis-owned controls that have no PrimeReact component behind them. They read the Scene tokens and
+ * carry a literal fallback, so they stay legible in a host that has not loaded a preset.
+ */
+
+[data-scene-component='editor'] .ql-editor {
+    min-height: 8rem;
+}
+
+[data-scene-component='dataScroller'] ol {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+[data-scene-component='dataScroller'] li {
+    padding: 0.5rem 0.75rem;
+    border-bottom: 1px solid var(--scene-surface-border, #d4d4d8);
+}
+
+[data-scene-component='dataScroller'] dl {
+    margin: 0.25rem 0 0;
+    color: var(--scene-text-muted-color, inherit);
+}
+
+[data-scene-component='dataScroller'] dl > div {
+    display: flex;
+    gap: 0.5rem;
+}
+
+[data-scene-component='dataScroller'] dt {
+    font-weight: 600;
+}
+
+[data-scene-component='dataScroller'] dd {
+    margin: 0;
+}
+
+[data-scene-component='treeTable'] table {
+    width: 100%;
+    border-collapse: collapse;
+}
+
+[data-scene-component='treeTable'] th,
+[data-scene-component='treeTable'] td {
+    padding: 0.5rem 0.75rem;
+    text-align: start;
+    border-bottom: 1px solid var(--scene-surface-border, #d4d4d8);
+}
+
+[data-scene-component='treeTable'] tbody tr:hover {
+    background: var(--scene-surface-hover, #f4f4f5);
+}
+
+[data-scene-component='treeTable'] tbody tr[aria-selected='true'] {
+    background: var(--scene-highlight-background, #e0e7ff);
+    color: var(--scene-highlight-color, inherit);
+}
+
+[data-scene-component='treeTable'] tbody tr:focus-visible {
+    outline: 2px solid var(--scene-primary-color, #4f46e5);
+    outline-offset: -2px;
+}
+
+[data-scene-component='dataScroller'] li:focus-visible {
+    outline: 2px solid var(--scene-primary-color, #4f46e5);
+    outline-offset: -2px;
+}

package/resolveEnumeration.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EnumerationResolution } from './EnumerationResolution';
+
+/**
+ * Resolves an authored value to a member of one of this package's string enums.
+ *
+ * Three forms are accepted, and the stored value is never rewritten:
+ * - the canonical string value the enum declares (`'checkbox'`), which new documents use;
+ * - the ordinal of the original .NET enum (`3`), which migrated documents carry. The ordinal is the member's
+ *   position in declaration order, so that order is part of the stored-data contract and must not change;
+ * - the .NET member name in its original Pascal case (`'Checkbox'`), which a JSON serialization of that enum
+ *   produces.
+ *
+ * An absent value is the one default. Anything else - an out-of-range or fractional ordinal, a numeric
+ * string, a differently cased name, `null` - resolves to a finding with a message, because the intended
+ * behavior cannot be known and a silent fallback hides a mistyped document.
+ *
+ * @param property The property name, used in the message.
+ * @param value The authored value.
+ * @param members The enum object.
+ * @param fallback The member an absent value means.
+ * @returns The resolved member, or the finding.
+ */
+export function resolveEnumeration<TMember extends string>(
+    property: string,
+    value: unknown,
+    members: Record<string, TMember>,
+    fallback: TMember
+): EnumerationResolution<TMember> {
+    if (value === undefined) return { isValid: true, value: fallback };
+
+    const canonical = Object.values(members);
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0 && value < canonical.length) {
+        return { isValid: true, value: canonical[value] };
+    }
+
+    if (typeof value === 'string') {
+        if (canonical.includes(value as TMember)) return { isValid: true, value: value as TMember };
+        if (Object.hasOwn(members, value)) return { isValid: true, value: members[value] };
+    }
+
+    const shown = typeof value === 'string' ? `'${value}'` : JSON.stringify(value) ?? String(value);
+    return {
+        isValid: false,
+        value,
+        message: `Unsupported ${property} ${shown}. Use one of ${canonical.join(', ')}, or a legacy ordinal from 0 to ${canonical.length - 1}.`,
+    };
+}

package/treeNodes.ts

@@ -14,35 +14,73 @@ import { arrayProperty } from './properties';
  * expands the wrong rows the moment two siblings share a label. Deriving the key from the path makes it
  * unique and stable across re-renders without asking the author for anything.
  *
+ * An authored key may be a string or a number (a numeric id is a natural key); it is kept as a string. Keys
+ * are unique across the whole tree: a node whose authored key was already taken by an earlier node falls back
+ * to its path key, so two nodes can never share expansion or selection.
+ *
+ * An entry that is a string, number or boolean is a leaf labeled with it. Anything else that is not a record
+ * (`null`, a nested array) cannot be a node and is skipped; see {@link countUnreadableEntries}.
+ *
  * @param entries The raw entries to convert.
  * @param parentKey The key of the node these entries belong to, used to build stable child keys.
+ * @param usedKeys The keys already given out in this tree, shared down the recursion.
  * @returns The converted nodes, in order.
  */
-export function toTreeNodes(entries: unknown[], parentKey = ''): TreeNode[] {
+export function toTreeNodes(entries: unknown[], parentKey = '', usedKeys: Set<string> = new Set()): TreeNode[] {
     const nodes: TreeNode[] = [];
     entries.forEach((entry, index) => {
         const path = parentKey === '' ? `${index}` : `${parentKey}-${index}`;
-        if (typeof entry === 'string') {
-            nodes.push({ key: path, label: entry });
+        if (typeof entry === 'string' || typeof entry === 'number' || typeof entry === 'boolean') {
+            nodes.push({ key: uniqueKey(undefined, path, usedKeys), label: String(entry) });
             return;
         }
 
         if (typeof entry !== 'object' || entry === undefined || entry === null || Array.isArray(entry)) return;
 
         const record = entry as Record<string, unknown>;
-        const node: TreeNode = { key: typeof record.key === 'string' ? record.key : path };
+        const node: TreeNode = { key: uniqueKey(authoredKey(record.key), path, usedKeys) };
         if (typeof record.label === 'string') node.label = record.label;
         if (typeof record.icon === 'string') node.icon = record.icon;
         if (typeof record.className === 'string') node.className = record.className;
         if (typeof record.leaf === 'boolean') node.leaf = record.leaf;
-        if (typeof record.data === 'object' && record.data !== null) node.data = record.data;
-        if (Array.isArray(record.children)) node.children = toTreeNodes(record.children, node.key as string);
+        if (typeof record.expanded === 'boolean') node.expanded = record.expanded;
+        if (typeof record.selectable === 'boolean') node.selectable = record.selectable;
+        if (record.data !== undefined && record.data !== null) node.data = record.data;
+        if (Array.isArray(record.children)) node.children = toTreeNodes(record.children, node.key as string, usedKeys);
         nodes.push(node);
     });
 
     return nodes;
 }
 
+/**
+ * Counts the entries `toTreeNodes` skips, so a control can say that some of its data was not shown instead
+ * of silently showing less.
+ *
+ * @param entries The raw entries.
+ * @returns How many entries, at any depth, were neither a scalar nor a record.
+ */
+export function countUnreadableEntries(entries: unknown[]): number {
+    return entries.reduce<number>((count, entry) => {
+        if (typeof entry === 'string' || typeof entry === 'number' || typeof entry === 'boolean') return count;
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return count + 1;
+        const children = (entry as { children?: unknown }).children;
+        return count + (Array.isArray(children) ? countUnreadableEntries(children) : 0);
+    }, 0);
+}
+
+function authoredKey(value: unknown): string | undefined {
+    if (typeof value === 'string' && value !== '') return value;
+    return typeof value === 'number' && Number.isFinite(value) ? String(value) : undefined;
+}
+
+function uniqueKey(authored: string | undefined, path: string, usedKeys: Set<string>): string {
+    let key = authored !== undefined && !usedKeys.has(authored) ? authored : path;
+    while (usedKeys.has(key)) key = `${key}~`;
+    usedKeys.add(key);
+    return key;
+}
+
 /**
  * Reads a tree model off a Scene element's properties.
  *

package/useResettingState.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Dispatch, SetStateAction, useCallback, useState } from 'react';
+import { useStructuralValue } from './useStructuralValue';
+
+/**
+ * State that starts from authored data and starts over when that data really changes.
+ *
+ * A control's selection or expansion is runtime state the user changes, yet it is also authored on the
+ * element. Reading the authored value once (`useState(() => authored)`) ignores a later edit of the document;
+ * resetting on every render discards what the user did. This does neither: the state follows `source` when
+ * its content changes, compared structurally because every document edit clones the data, and is otherwise
+ * left alone - so an unrelated property edit does not undo the user's choice.
+ *
+ * @param source The authored data the state derives from.
+ * @param initial Derives the starting state from the authored data.
+ * @returns The state and its setter, like `useState`.
+ */
+export function useResettingState<TState>(source: unknown, initial: () => TState): [TState, Dispatch<SetStateAction<TState>>] {
+    const stable = useStructuralValue(source);
+    const [held, setHeld] = useState(() => ({ source: stable, value: initial() }));
+    let current = held;
+    if (held.source !== stable) {
+        current = { source: stable, value: initial() };
+        setHeld(current);
+    }
+
+    const update = useCallback((action: SetStateAction<TState>) => {
+        setHeld(previous => ({ source: previous.source, value: typeof action === 'function' ? (action as (state: TState) => TState)(previous.value) : action }));
+    }, []);
+
+    return [current.value, update];
+}