@cratis/scene.primereact 4.21.0 → 4.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.primereact",
-    "version": "4.21.0",
+    "version": "4.22.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",
@@ -59,15 +59,15 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.21.0",
-        "@cratis/scene.model": "4.21.0",
-        "@cratis/scene.react": "4.21.0",
+        "@cratis/scene.engine": "4.22.0",
+        "@cratis/scene.model": "4.22.0",
+        "@cratis/scene.react": "4.22.0",
         "@primeuix/themes": "^3.0.1"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.21.0",
-        "@cratis/scene.model": "4.21.0",
-        "@cratis/scene.react": "4.21.0",
+        "@cratis/scene.engine": "4.22.0",
+        "@cratis/scene.model": "4.22.0",
+        "@cratis/scene.react": "4.22.0",
         "@primereact/core": "11.2.0",
         "@primereact/headless": "11.2.0",
         "@primereact/types": "11.2.0",
@@ -76,7 +76,7 @@
         "@storybook/react-vite": "^10.6.1",
         "chart.js": "4.5.1",
         "esbuild": "0.28.2",
-        "playwright-core": "1.63.0",
+        "playwright-core": "1.64.0",
         "primeicons": "8.0.2",
         "primereact": "11.2.0",
         "quill": "2.0.3",

package/primeReactDescriptors.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { ComponentDescriptor, PropertyValueType } from '@cratis/scene.model';
+import { BindingSourceKind, ComponentDescriptor, PropertyDescriptor, PropertyEditorKind, PropertyValueType } from '@cratis/scene.model';
 import { componentRegistryKey } from '@cratis/scene.react';
 import { chartTypeChoices } from './chart/chartTypeChoices';
 import { legacyEnumerationChoices } from './legacyEnumerationChoices';
@@ -12,6 +12,82 @@ import { primeReactInputDescriptors } from './inputDescriptors';
 
 const key = (name: string) => componentRegistryKey('PrimeReact', name);
 
+/** Structured values keep accepting what a screen binds them to - a query's rows, a data context - as they did when they were any JSON. */
+const bindable = [BindingSourceKind.DataContext, BindingSourceKind.QueryResult, BindingSourceKind.ComponentProperty];
+const choice = (...values: string[]) => values.map(value => ({ value, label: value }));
+const text = (path: string, label: string, description?: string): PropertyDescriptor => ({ path, label, group: 'Content', valueType: PropertyValueType.String, ...(description ? { description } : {}) });
+const flag = (path: string, label: string, description?: string): PropertyDescriptor => ({ path, label, group: 'Content', valueType: PropertyValueType.Boolean, ...(description ? { description } : {}) });
+const numeric = (path: string, label: string, description?: string): PropertyDescriptor => ({ path, label, group: 'Content', valueType: PropertyValueType.Number, ...(description ? { description } : {}) });
+const list = (path: string, label: string, editorKind: PropertyEditorKind, description?: string): PropertyDescriptor => ({ path, label, group: 'Content', valueType: PropertyValueType.Json, editorKind, ...(description ? { description } : {}) });
+
+/** The Chart.js data object: its labels and its datasets, with the fields of a dataset that authors set most. Anything else a dataset carries is kept. */
+const chartData: PropertyDescriptor['properties'] = [
+    list('labels', 'Labels', PropertyEditorKind.StringList, 'One label for each point of every dataset, in order.'),
+    {
+        path: 'datasets', label: 'Datasets', group: 'Content', valueType: PropertyValueType.Collection,
+        item: {
+            label: 'Dataset',
+            open: true,
+            positional: true,
+            properties: [
+                text('label', 'Label'),
+                list('data', 'Values', PropertyEditorKind.NumberList, 'One value for each label, in order.'),
+                list('backgroundColor', 'Fill colour', PropertyEditorKind.StringOrList, 'One CSS colour for the whole dataset, or one for each point.'),
+                list('borderColor', 'Border colour', PropertyEditorKind.StringOrList, 'One CSS colour for the whole dataset, or one for each point.'),
+                numeric('borderWidth', 'Border width'),
+                flag('fill', 'Fill under the line'),
+                numeric('tension', 'Line tension', 'How much a line curves between points: 0 is straight.'),
+            ],
+        },
+    },
+];
+
+/** The Chart.js options authors set most; any other option the stored value carries is kept. */
+const chartOptions: PropertyDescriptor['properties'] = [
+    flag('responsive', 'Responsive'),
+    flag('maintainAspectRatio', 'Keep the aspect ratio'),
+    numeric('aspectRatio', 'Aspect ratio', 'Width divided by height.'),
+    { path: 'indexAxis', label: 'Index axis', group: 'Content', valueType: PropertyValueType.Enum, choices: choice('x', 'y'), description: 'The axis the labels run along; y draws horizontal bars.' },
+    {
+        path: 'plugins', label: 'Plugins', group: 'Content', valueType: PropertyValueType.Object, open: true,
+        properties: [
+            {
+                path: 'legend', label: 'Legend', group: 'Content', valueType: PropertyValueType.Object, open: true,
+                properties: [flag('display', 'Show the legend'), { path: 'position', label: 'Position', group: 'Content', valueType: PropertyValueType.Enum, choices: choice('top', 'left', 'bottom', 'right') }],
+            },
+            {
+                path: 'title', label: 'Title', group: 'Content', valueType: PropertyValueType.Object, open: true,
+                properties: [flag('display', 'Show the title'), text('text', 'Text')],
+            },
+        ],
+    },
+];
+
+/** The CSS sizes that shape the surface a chart is drawn on. */
+const chartStyle: PropertyDescriptor['properties'] = ['width', 'height', 'minWidth', 'minHeight', 'maxWidth', 'maxHeight'].map(name => text(name, name.replace(/([A-Z])/g, ' $1').replace(/^./, first => first.toUpperCase()), 'A CSS length such as 320px or 100%.'));
+
+/**
+ * A tree node: the fields of Scene's tree model. Children are the same shape; the description goes as deep as a tree is authored by hand,
+ * and a node below that keeps its own children without editing them.
+ */
+function treeNode(depth: number): PropertyDescriptor[] {
+    const fields: PropertyDescriptor[] = [
+        text('key', 'Key', 'Identity across the whole tree. Derived from the node\'s position when it is not set.'),
+        text('label', 'Label'),
+        text('icon', 'Icon', 'A PrimeIcons class name such as pi pi-folder.'),
+        flag('leaf', 'Leaf'),
+        flag('expanded', 'Expanded'),
+        flag('selectable', 'Selectable'),
+        { path: 'data', label: 'Data', group: 'Content', valueType: PropertyValueType.Object, editorKind: PropertyEditorKind.StringMap, description: 'The values the node shows, under the field names the columns use.' },
+    ];
+
+    if (depth > 0) {
+        fields.push({ path: 'children', label: 'Children', group: 'Content', valueType: PropertyValueType.Collection, item: { label: 'Node', open: true, positional: true, properties: treeNode(depth - 1) } });
+    }
+
+    return fields;
+}
+
 /** Design-time descriptors for PrimeReact controls whose authored data has structured configuration. */
 export const primeReactDescriptors: ComponentDescriptor[] = [
     ...primeReactInputDescriptors,
@@ -24,11 +100,11 @@ export const primeReactDescriptors: ComponentDescriptor[] = [
                 path: 'type', label: 'Type', group: 'Chart', valueType: PropertyValueType.Enum, default: ChartType.Bar,
                 choices: chartTypeChoices,
             },
-            { path: 'data', label: 'Data', group: 'Data', valueType: PropertyValueType.Json, description: 'The Chart.js data object, including labels and datasets in their authored order.' },
-            { path: 'options', label: 'Options', group: 'Chart', valueType: PropertyValueType.Json, description: 'The Chart.js options object.' },
+            { path: 'data', label: 'Data', group: 'Data', valueType: PropertyValueType.Object, open: true, properties: chartData, acceptedBindingKinds: bindable, description: 'The Chart.js data object, including labels and datasets in their authored order.' },
+            { path: 'options', label: 'Options', group: 'Chart', valueType: PropertyValueType.Object, open: true, properties: chartOptions, acceptedBindingKinds: bindable, description: 'The Chart.js options object. The options listed here are the ones authors set most; any other option it holds is kept.' },
             { path: 'emptyLabel', label: 'No data label', group: 'Accessibility', valueType: PropertyValueType.String, default: 'No chart data', description: 'Shown instead of the chart while it has no data points. Data is never invented.' },
             { path: 'responsive', label: 'Responsive', group: 'Layout', valueType: PropertyValueType.Boolean, default: true },
-            { path: 'style', label: 'Style', group: 'Layout', valueType: PropertyValueType.Json, description: 'The CSS style object applied to the chart surface.' },
+            { path: 'style', label: 'Style', group: 'Layout', valueType: PropertyValueType.Object, open: true, properties: chartStyle, acceptedBindingKinds: bindable, description: 'The CSS style object applied to the chart surface.' },
             { path: 'ariaLabel', label: 'Accessible name', group: 'Accessibility', valueType: PropertyValueType.String },
         ],
     },
@@ -54,7 +130,7 @@ export const primeReactDescriptors: ComponentDescriptor[] = [
         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: 'items', label: 'Items', group: 'Data', valueType: PropertyValueType.Json, editorKind: PropertyEditorKind.StringList, description: 'The text of each item, in order. A record is titled by its label, title, name, text or header field; records authored in a file are kept but not edited here.' },
             { 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.' },
@@ -67,13 +143,16 @@ export const primeReactDescriptors: ComponentDescriptor[] = [
         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: 'columns', label: 'Columns', group: 'Data', valueType: PropertyValueType.Collection, acceptedBindingKinds: bindable, description: 'Column definitions with field and header, or nested column elements. Inferred from the first row when absent.',
+                item: { label: 'Column', open: true, positional: true, properties: [text('field', 'Field', 'The name in a node\'s data that the column shows.'), text('header', 'Header', 'The column heading. The field name when it is not set.'), flag('sortable', 'Sortable')] },
+            },
+            { path: 'items', label: 'Items', group: 'Data', valueType: PropertyValueType.Collection, item: { label: 'Node', open: true, positional: true, properties: treeNode(3) }, acceptedBindingKinds: bindable, description: 'The nodes: 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: 'selection', label: 'Selection', group: 'Behavior', valueType: PropertyValueType.Json, editorKind: PropertyEditorKind.StringOrList, description: 'The key of the selected node, or the keys of the selected nodes.' },
             { 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' },
@@ -97,13 +176,16 @@ export const primeReactDescriptors: ComponentDescriptor[] = [
         displayName: 'Multi-state checkbox',
         description: 'An accessible button that cycles through its authored states in order, showing the current state as a checkbox-style glyph.',
         properties: [
-            { path: 'value', label: 'Value', group: 'State', valueType: PropertyValueType.Json, description: 'The selected value. It may be null when the empty state is enabled.' },
-            { path: 'options', label: 'Options', group: 'State', valueType: PropertyValueType.Json, description: 'The ordered state options. Each may provide label, value, and icon fields.' },
+            { path: 'value', label: 'Value', group: 'State', valueType: PropertyValueType.Json, editorKind: PropertyEditorKind.Scalar, description: 'The selected value: a word, a number or a flag. Not set when the empty state is selected.' },
+            {
+                path: 'options', label: 'Options', group: 'State', valueType: PropertyValueType.Collection, acceptedBindingKinds: bindable, description: 'The ordered state options. Each may provide label, value, and icon fields.',
+                item: { label: 'State', open: true, positional: true, properties: [text('label', 'Label'), text('value', 'Value'), text('icon', 'Icon', 'A PrimeIcons class name such as pi pi-check.')] },
+            },
             { path: 'optionLabel', label: 'Option label field', group: 'State', valueType: PropertyValueType.String, default: 'label' },
             { path: 'optionValue', label: 'Option value field', group: 'State', valueType: PropertyValueType.String, default: 'value' },
             { path: 'empty', label: 'Allow empty state', group: 'State', valueType: PropertyValueType.Boolean, default: true },
             { path: 'emptyLabel', label: 'Empty state label', group: 'Accessibility', valueType: PropertyValueType.String, default: 'No selection' },
-            { path: 'icons', label: 'Icons', group: 'Appearance', valueType: PropertyValueType.Json, description: 'Icons aligned with the options, or keyed by their values. Each is a PrimeIcons class name or a qualified icon reference. Icons inside this value are not tracked by the icon library diagnostics; use the empty state icon where a tracked icon is needed.' },
+            { path: 'icons', label: 'Icons', group: 'Appearance', valueType: PropertyValueType.Json, editorKind: PropertyEditorKind.StringList, description: 'One icon for each option, in the order of the options. Each is a PrimeIcons class name or a qualified icon reference. Icons inside this value are not tracked by the icon library diagnostics; use the empty state icon where a tracked icon is needed.' },
             { path: 'emptyIcon', label: 'Empty state icon', group: 'Appearance', valueType: PropertyValueType.Icon },
             { path: 'readOnly', label: 'Read only', group: 'Behavior', valueType: PropertyValueType.Boolean, default: false },
             { path: 'disabled', label: 'Disabled', group: 'Behavior', valueType: PropertyValueType.Boolean, default: false },