@cratis/scene.primereact 4.5.0 → 4.6.0

package/dist/esm/useStructuralValue.d.ts

@@ -0,0 +1,2 @@
+export declare function useStructuralValue<TValue>(value: TValue): TValue;
+//# sourceMappingURL=useStructuralValue.d.ts.map

package/dist/esm/useStructuralValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStructuralValue.d.ts","sourceRoot":"","sources":["../../useStructuralValue.ts"],"names":[],"mappings":"AAYA,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhE"}

package/dist/esm/useStructuralValue.js

@@ -0,0 +1,18 @@
+import { useRef } from 'react';
+import { structurallyEqual } from './structurallyEqual.js';
+
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Returns the same reference for as long as the content of `value` is unchanged.
+ *
+ * Use it for authored data that feeds an effect dependency list: a cloned document gives that data a new
+ * identity on every unrelated edit, which would otherwise rerun the effect and rebuild whatever it owns.
+ */ function useStructuralValue(value) {
+    const stable = useRef(value);
+    if (!structurallyEqual(stable.current, value)) stable.current = value;
+    return stable.current;
+}
+
+export { useStructuralValue };
+//# sourceMappingURL=useStructuralValue.js.map

package/dist/esm/useStructuralValue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStructuralValue.js","sources":["../../useStructuralValue.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\nimport { useRef } from 'react';\nimport { structurallyEqual } from './structurallyEqual';\n\n/**\n * Returns the same reference for as long as the content of `value` is unchanged.\n *\n * Use it for authored data that feeds an effect dependency list: a cloned document gives that data a new\n * identity on every unrelated edit, which would otherwise rerun the effect and rebuild whatever it owns.\n */\nexport function useStructuralValue<TValue>(value: TValue): TValue {\n    const stable = useRef(value);\n    if (!structurallyEqual(stable.current, value)) stable.current = value;\n    return stable.current;\n}\n"],"names":["useStructuralValue","value","stable","useRef","structurallyEqual","current"],"mappings":";;;AAAA;AACA;AAKA;;;;;IAMO,SAASA,kBAAAA,CAA2BC,KAAa,EAAA;AACpD,IAAA,MAAMC,SAASC,MAAAA,CAAOF,KAAAA,CAAAA;IACtB,IAAI,CAACG,kBAAkBF,MAAAA,CAAOG,OAAO,EAAEJ,KAAAA,CAAAA,EAAQC,MAAAA,CAAOG,OAAO,GAAGJ,KAAAA;AAChE,IAAA,OAAOC,OAAOG,OAAO;AACzB;;"}

package/form/FormGallery.stories.tsx

@@ -35,6 +35,14 @@ export const Gallery: Story = {
             sceneComponent('listBox', 'listBox', { options: ['Daily', 'Weekly', 'Monthly'] }),
             sceneComponent('selectButton', 'selectButton', { options: ['Day', 'Week', 'Month'], value: 'Week' }),
             sceneComponent('checkbox', 'checkbox', { label: 'Notify me', checked: true }),
+            sceneComponent('multiStateCheckbox', 'multiStateCheckbox', {
+                value: null,
+                options: [
+                    { label: 'Approved', value: 'approved', icon: 'pi pi-check' },
+                    { label: 'Rejected', value: 'rejected', icon: 'pi pi-times' },
+                ],
+                ariaLabel: 'Review state',
+            }),
             sceneComponent('radioButton', 'radioButton', { options: ['Email', 'SMS'], value: 'Email' }),
             sceneComponent('toggleSwitch', 'toggleSwitch', { label: 'Enabled', checked: true }),
             sceneComponent('slider', 'slider', { value: 35 }),

package/form/MultiStateGlyph.tsx

@@ -0,0 +1,55 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneIcon } from '@cratis/scene.react';
+import { MultiStateOption } from './MultiStateOption';
+
+export interface MultiStateGlyphProps {
+    /** The state being shown. */
+    state: MultiStateOption | undefined;
+
+    /** Whether the state is the empty (`null`) state, drawn as an empty box. */
+    isEmpty: boolean;
+
+    /** Whether the control is disabled or read only. */
+    isInactive: boolean;
+}
+
+/**
+ * The box a multi-state checkbox draws, themed with the PrimeReact checkbox tokens (`--p-checkbox-*`), so
+ * it follows the active Scene theme and looks like its sibling `checkbox`. It holds the state's icon - a
+ * PrimeIcons class or a qualified icon reference - or a check mark when the state has no icon of its own.
+ * An empty state draws only its own icon, if it has one. It is decorative: the state is announced through the control's text, not through this glyph.
+ */
+export function MultiStateGlyph({ state, isEmpty, isInactive }: MultiStateGlyphProps) {
+    const icon = state?.icon;
+    return (
+        <span
+            aria-hidden='true'
+            data-scene-part='glyph'
+            style={{
+                display: 'inline-flex', alignItems: 'center', justifyContent: 'center', flexShrink: 0, boxSizing: 'border-box',
+                width: 'var(--p-checkbox-width, 1.125rem)', height: 'var(--p-checkbox-height, 1.125rem)',
+                borderRadius: 'var(--p-checkbox-border-radius, 4px)',
+                border: `1px solid ${isEmpty ? 'var(--p-checkbox-border-color, currentColor)' : 'var(--p-checkbox-checked-border-color, currentColor)'}`,
+                backgroundColor: isEmpty ? 'var(--p-checkbox-background, transparent)' : 'var(--p-checkbox-checked-background, currentColor)',
+                color: glyphColor(isEmpty, isInactive),
+                fontSize: 'var(--p-checkbox-icon-size, 0.75rem)',
+            }}>
+            {icon === undefined ? !isEmpty && <CheckMark /> : typeof icon === 'string' ? <i className={icon} /> : <SceneIcon reference={icon} size='var(--p-checkbox-icon-size, 0.75rem)' />}
+        </span>
+    );
+}
+
+function glyphColor(isEmpty: boolean, isInactive: boolean): string {
+    if (isInactive) return 'var(--p-checkbox-icon-disabled-color, currentColor)';
+    return isEmpty ? 'var(--p-checkbox-icon-color, currentColor)' : 'var(--p-checkbox-icon-checked-color, Canvas)';
+}
+
+function CheckMark() {
+    return (
+        <svg viewBox='0 0 12 12' width='1em' height='1em' fill='none' stroke='currentColor' strokeWidth='2' strokeLinecap='round' strokeLinejoin='round'>
+            <path d='M2 6.5 5 9.5 10 3' />
+        </svg>
+    );
+}

package/form/MultiStateOption.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconReference } from '@cratis/scene.model';
+
+/**
+ * One state a {@link PrimeMultiStateCheckbox} can cycle through.
+ *
+ * The `value` is exactly what the document authored - any JSON value, including `null`, numbers, booleans
+ * and objects. The `icon` is either a legacy PrimeIcons class name (`'pi pi-check'`) or a qualified
+ * {@link IconReference}.
+ */
+export interface MultiStateOption {
+    label: string;
+    value: unknown;
+    icon?: string | IconReference;
+}

package/form/PrimeMultiStateCheckbox.tsx

@@ -0,0 +1,101 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CSSProperties, useId, useState } from 'react';
+import { isIconReference } from '@cratis/scene.model';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { booleanProperty, stringProperty } from '../properties';
+import { MultiStateGlyph } from './MultiStateGlyph';
+import { multiStateOptions } from './multiStateOptions';
+import { multiStateStates } from './multiStateStates';
+import { useMultiStateSelection } from './useMultiStateSelection';
+
+const visuallyHidden: CSSProperties = {
+    position: 'absolute', width: 1, height: 1, margin: -1, padding: 0, overflow: 'hidden', clip: 'rect(0 0 0 0)', whiteSpace: 'nowrap', border: 0,
+};
+
+/**
+ * The `PrimeReact:multiStateCheckbox` component.
+ *
+ * PrimeReact 11 removed MultiStateCheckbox, so Scene renders its original behavior with a native button.
+ * It cycles through the authored states in order, including the optional empty (`null`) state, and keeps
+ * option values and icons exactly as the element carries them. Each click moves one step; the position is
+ * an index, so duplicated or `null` option values do not make later states unreachable.
+ *
+ * Accessibility: a state cycle is not a true/false choice, so the control does not claim `checkbox`
+ * semantics (every non-empty state would announce as "checked"). It is a button whose name is the authored
+ * `ariaLabel`, whose description is the current state, and whose state changes are announced through a
+ * polite live region. `readOnly` keeps the control focusable and unchanged; `disabled` removes it from the
+ * tab order.
+ *
+ * The control follows the document: a changed `value` or `options` restarts the cycle from the new value,
+ * so an inspector edit is reflected immediately. It does not report its own selection to behaviors -
+ * Scene's interaction handlers carry no value.
+ */
+export function PrimeMultiStateCheckbox({ element, interactions }: RegisteredComponentProps) {
+    const stateId = useId();
+    const allowEmpty = booleanProperty(element, 'empty', true);
+    const emptyLabel = stringProperty(element, 'emptyLabel', 'No selection');
+    const emptyIcon = element.properties.emptyIcon;
+    const states = multiStateStates(
+        multiStateOptions(element, emptyLabel),
+        allowEmpty,
+        emptyLabel,
+        typeof emptyIcon === 'string' || isIconReference(emptyIcon) ? emptyIcon : undefined);
+    const authored = element.properties.value;
+    const { index, advance } = useMultiStateSelection(states, authored === undefined && allowEmpty ? null : authored);
+    const [focused, setFocused] = useState(false);
+
+    const selected = states[index];
+    const readOnly = booleanProperty(element, 'readOnly', false);
+    const disabled = !element.isEnabled || booleanProperty(element, 'disabled', false) || states.length === 0;
+    const ariaLabel = stringProperty(element, 'ariaLabel', element.name || 'Multi-state checkbox');
+    const stateText = selected?.label ?? stringProperty(element, 'placeholder', unmatchedText(states.length, authored, emptyLabel));
+
+    return (
+        <>
+            <button
+                type='button'
+                data-scene-id={element.id}
+                data-scene-component='multiStateCheckbox'
+                data-scene-state-index={index}
+                aria-label={ariaLabel}
+                aria-describedby={stateId}
+                aria-disabled={readOnly ? true : undefined}
+                disabled={disabled}
+                style={{
+                    display: 'inline-flex', alignItems: 'center', gap: '0.5rem', padding: 0, border: 0, background: 'none', font: 'inherit',
+                    color: 'inherit', cursor: disabled ? 'not-allowed' : readOnly ? 'default' : 'pointer', opacity: disabled ? 0.6 : 1,
+                    outline: focused ? 'var(--p-focus-ring-width, 2px) var(--p-focus-ring-style, solid) var(--p-focus-ring-color, currentColor)' : 'none',
+                    outlineOffset: 'var(--p-focus-ring-offset, 2px)',
+                }}
+                onFocus={(event) => setFocused(isFocusVisible(event.currentTarget))}
+                onBlur={() => setFocused(false)}
+                onClick={(event) => {
+                    if (!readOnly) advance();
+                    interactions?.onClick?.(event);
+                    if (readOnly) return;
+                    interactions?.onChange?.();
+                    interactions?.onSelect?.();
+                }}
+                onDoubleClick={interactions?.onDoubleClick}>
+                <MultiStateGlyph state={selected} isEmpty={selected === undefined || selected.value === null} isInactive={disabled || readOnly} />
+                <span aria-hidden='true'>{stateText}</span>
+            </button>
+            <span id={stateId} role='status' style={visuallyHidden}>{stateText}</span>
+        </>
+    );
+}
+
+function unmatchedText(stateCount: number, authored: unknown, emptyLabel: string): string {
+    if (stateCount === 0) return 'No states';
+    return authored === undefined ? emptyLabel : 'No matching state';
+}
+
+function isFocusVisible(target: HTMLElement): boolean {
+    try {
+        return target.matches(':focus-visible');
+    } catch {
+        return true;
+    }
+}

package/form/index.ts

@@ -12,6 +12,7 @@ export * from './PrimeMultiSelect';
 export * from './PrimeListBox';
 export * from './PrimeSelectButton';
 export * from './PrimeCheckbox';
+export * from './PrimeMultiStateCheckbox';
 export * from './PrimeRadioButton';
 export * from './PrimeToggleSwitch';
 export * from './PrimeSlider';

package/form/multiStateOptions.ts

@@ -0,0 +1,78 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement, isIconReference } from '@cratis/scene.model';
+import { arrayProperty, stringProperty } from '../properties';
+import { MultiStateOption } from './MultiStateOption';
+
+/**
+ * Reads multi-state options without reshaping their values, dropping any of them, or changing their order.
+ *
+ * This follows the original PrimeReact control. An option that is a record gives its value through
+ * `optionValue` (default, and when that field is absent: its `value` field, and the whole option when it has none) and its label through
+ * `optionLabel` (default: its `label` field). Any other option - a string, number, boolean, `null` or an
+ * array - is its own value. A label that is not text is shown as its JSON, so a numeric or boolean label,
+ * or an option with no label at all, still produces a state the user can reach. A `null` value with no
+ * label of its own is labeled with `emptyLabel`.
+ *
+ * A state's icon is, in order: the option's own `icon`, then the entry of the element's `icons` that is
+ * aligned with the option (an array) or keyed by its value (an object). Either may be a PrimeIcons class
+ * name, kept for legacy documents, or a qualified {@link IconReference}.
+ */
+export function multiStateOptions(element: SceneElement, emptyLabel: string): MultiStateOption[] {
+    const labelPath = stringProperty(element, 'optionLabel');
+    const valuePath = stringProperty(element, 'optionValue');
+    const icons = element.properties.icons;
+
+    return arrayProperty(element, 'options').map((option, index) => {
+        const record = isRecord(option) ? option : undefined;
+        const value = record === undefined ? option : valueOf(record, valuePath);
+        const label = record === undefined ? undefined : resolvePath(record, labelPath ?? 'label');
+        const icon = toIcon(record?.icon) ?? iconAt(icons, value, index);
+        return { label: labelText(label, value, emptyLabel), value, ...(icon === undefined ? {} : { icon }) };
+    });
+}
+
+function valueOf(record: Record<string, unknown>, valuePath: string | undefined): unknown {
+    const authored = valuePath === undefined ? undefined : resolvePath(record, valuePath);
+    if (authored !== undefined) return authored;
+    return record.value !== undefined ? record.value : record;
+}
+
+function resolvePath(record: Record<string, unknown>, path: string): unknown {
+    if (Object.hasOwn(record, path)) return record[path];
+    let current: unknown = record;
+    for (const segment of path.split('.')) {
+        if (!isRecord(current) || !Object.hasOwn(current, segment)) return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+
+function labelText(label: unknown, value: unknown, emptyLabel: string): string {
+    if (typeof label === 'string' && label.length > 0) return label;
+    if (label !== undefined && label !== null && label !== '') return display(label);
+    return value === null ? emptyLabel : display(value);
+}
+
+function display(value: unknown): string {
+    const text = typeof value === 'string' ? value : JSON.stringify(value) ?? String(value);
+    return text === '' ? '""' : text;
+}
+
+function toIcon(candidate: unknown): MultiStateOption['icon'] {
+    if (typeof candidate === 'string' && candidate.length > 0) return candidate;
+    return isIconReference(candidate) ? candidate : undefined;
+}
+
+function iconAt(icons: unknown, value: unknown, index: number): MultiStateOption['icon'] {
+    if (Array.isArray(icons)) return toIcon(icons[index]);
+    if (!isRecord(icons)) return undefined;
+
+    const isKey = value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+    return isKey ? toIcon(icons[String(value)]) : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/form/multiStateStates.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { IconReference } from '@cratis/scene.model';
+import { MultiStateOption } from './MultiStateOption';
+
+/**
+ * Builds the ordered states a multi-state checkbox cycles through.
+ *
+ * With the empty state allowed, a state whose value is `null` comes first - unless an authored option
+ * already has the value `null`, in which case that option *is* the empty state and keeps its authored
+ * position, label and icon. Adding a second `null` state would leave two states with one value, and a
+ * control that finds its place by value could then never move past the first of them.
+ *
+ * @param options The authored options, in order.
+ * @param allowEmpty Whether a `null` state is available.
+ * @param emptyLabel The label of the synthesized empty state.
+ * @param emptyIcon The icon of the synthesized empty state.
+ */
+export function multiStateStates(options: MultiStateOption[], allowEmpty: boolean, emptyLabel: string, emptyIcon: string | IconReference | undefined): MultiStateOption[] {
+    if (!allowEmpty || options.some(option => option.value === null)) return options;
+    return [{ label: emptyLabel, value: null, ...(emptyIcon === undefined ? {} : { icon: emptyIcon }) }, ...options];
+}

package/form/useMultiStateSelection.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useState } from 'react';
+import { structurallyEqual } from '../structurallyEqual';
+import { MultiStateOption } from './MultiStateOption';
+
+interface Selection {
+    source: unknown;
+    values: unknown[];
+    index: number;
+}
+
+/**
+ * The state a multi-state checkbox is in, as an index into its states.
+ *
+ * The position is tracked by index, not recovered by looking the current value up: several states can
+ * share a value (a duplicated option), and a lookup by value always finds the first of them, which would
+ * make every later state unreachable. The index follows the cycle; the value is only used to find the
+ * starting position.
+ *
+ * The control is driven by the document as well as by the user. When the authored `value` or the states
+ * change in content - an edit in the inspector, a hydrated document - the selection starts again from the
+ * new value. A document clone with equal content changes nothing, so the user's position survives it.
+ *
+ * @param states The states, in cycle order.
+ * @param value The authored current value.
+ * @returns The selected index (`-1` when the value matches no state) and a function that moves to the next.
+ */
+export function useMultiStateSelection(states: MultiStateOption[], value: unknown): { index: number; advance(): number } {
+    const values = states.map(state => state.value);
+    const start = (): Selection => ({ source: value, values, index: values.findIndex(candidate => structurallyEqual(candidate, value)) });
+    const [selection, setSelection] = useState<Selection>(start);
+
+    let current = selection;
+    if (!structurallyEqual(selection.source, value) || !structurallyEqual(selection.values, values)) {
+        current = start();
+        setSelection(current);
+    }
+
+    const advance = () => {
+        const index = states.length === 0 ? -1 : (current.index + 1) % states.length;
+        setSelection({ ...current, index });
+        return index;
+    };
+
+    return { index: current.index, advance };
+}

package/index.ts

@@ -10,6 +10,7 @@ export * from './menuItems';
 export * from './treeNodes';
 export * from './button';
 export * from './form';
+export * from './chart';
 export * from './data';
 export * from './panel';
 export * from './overlay';
@@ -20,4 +21,5 @@ export * from './misc';
 export * from './screen';
 export * from './theme';
 export * from './primeReactComponents';
+export * from './primeReactDescriptors';
 export * from './primeReactPackage';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.primereact",
-    "version": "4.5.0",
+    "version": "4.6.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",
@@ -47,27 +47,31 @@
         "lint": "yarn g:lint",
         "lint:ci": "yarn g:lint:ci",
         "test": "yarn g:test",
+        "test:browser": "yarn g:test --config ./vitest.browser.config.mts",
         "ci": "yarn g:ci",
         "up": "yarn g:up",
         "dev": "storybook dev -p 6006",
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.5.0",
-        "@cratis/scene.model": "4.5.0",
-        "@cratis/scene.react": "4.5.0",
+        "@cratis/scene.engine": "4.6.0",
+        "@cratis/scene.model": "4.6.0",
+        "@cratis/scene.react": "4.6.0",
         "@primeuix/themes": "^3.0.1"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.5.0",
-        "@cratis/scene.model": "4.5.0",
-        "@cratis/scene.react": "4.5.0",
+        "@cratis/scene.engine": "4.6.0",
+        "@cratis/scene.model": "4.6.0",
+        "@cratis/scene.react": "4.6.0",
         "@primereact/core": "11.2.0",
         "@primereact/headless": "11.2.0",
         "@primereact/types": "11.2.0",
         "@storybook/addon-links": "^10.6.1",
         "@storybook/react": "^10.6.1",
         "@storybook/react-vite": "^10.6.1",
+        "chart.js": "4.5.1",
+        "esbuild": "0.28.2",
+        "playwright-core": "1.63.0",
         "primeicons": "8.0.2",
         "primereact": "11.2.0",
         "react": "^19.3.0",
@@ -77,9 +81,15 @@
     "peerDependencies": {
         "@primereact/core": "^11.0.0",
         "@primereact/headless": "^11.0.0",
+        "chart.js": "^4.5.1",
         "primeicons": "^8.0.0",
         "primereact": "^11.0.0",
         "react": "^19.0.0",
         "react-dom": "^19.0.0"
+    },
+    "peerDependenciesMeta": {
+        "chart.js": {
+            "optional": true
+        }
     }
 }

package/primeReactComponents.ts

@@ -3,6 +3,7 @@
 
 import { ComponentRegistry, componentRegistryKey } from '@cratis/scene.react';
 import { PrimeButton, PrimeButtonGroup, PrimeSpeedDial, PrimeSplitButton } from './button';
+import { PrimeChart } from './chart';
 import {
     PrimeColumn,
     PrimeDataTable,
@@ -33,6 +34,7 @@ import {
     PrimeRadioButton,
     PrimeRating,
     PrimeSelectButton,
+    PrimeMultiStateCheckbox,
     PrimeSlider,
     PrimeToggleSwitch,
     PrimeTreeSelect,
@@ -108,6 +110,7 @@ export const primeReactComponents: ComponentRegistry = {
     [componentRegistryKey('PrimeReact', 'listBox')]: PrimeListBox,
     [componentRegistryKey('PrimeReact', 'selectButton')]: PrimeSelectButton,
     [componentRegistryKey('PrimeReact', 'checkbox')]: PrimeCheckbox,
+    [componentRegistryKey('PrimeReact', 'multiStateCheckbox')]: PrimeMultiStateCheckbox,
     [componentRegistryKey('PrimeReact', 'radioButton')]: PrimeRadioButton,
     [componentRegistryKey('PrimeReact', 'toggleSwitch')]: PrimeToggleSwitch,
     [componentRegistryKey('PrimeReact', 'slider')]: PrimeSlider,
@@ -134,6 +137,7 @@ export const primeReactComponents: ComponentRegistry = {
     [componentRegistryKey('PrimeReact', 'orderList')]: PrimeOrderList,
     [componentRegistryKey('PrimeReact', 'pickList')]: PrimePickList,
     [componentRegistryKey('PrimeReact', 'organizationChart')]: PrimeOrganizationChart,
+    [componentRegistryKey('PrimeReact', 'chart')]: PrimeChart,
 
     [componentRegistryKey('PrimeReact', 'card')]: PrimeCard,
     [componentRegistryKey('PrimeReact', 'panel')]: PrimePanel,

package/primeReactDescriptors.ts

@@ -0,0 +1,48 @@
+// 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 { componentRegistryKey } from '@cratis/scene.react';
+import { chartTypeChoices } from './chart/chartTypeChoices';
+import { ChartType } from './chart';
+
+const key = (name: string) => componentRegistryKey('PrimeReact', name);
+
+/** Design-time descriptors for PrimeReact controls whose authored data has structured configuration. */
+export const primeReactDescriptors: ComponentDescriptor[] = [
+    {
+        component: key('chart'),
+        displayName: 'Chart',
+        description: 'A Chart.js chart. Legacy numeric types are rendered without changing stored data; new documents use stable type names. The host application must install chart.js.',
+        properties: [
+            {
+                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: '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: 'ariaLabel', label: 'Accessible name', group: 'Accessibility', valueType: PropertyValueType.String },
+        ],
+    },
+    {
+        component: key('multiStateCheckbox'),
+        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: '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: '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 },
+            { path: 'ariaLabel', label: 'Accessible name', group: 'Accessibility', valueType: PropertyValueType.String },
+        ],
+    },
+];

package/primeReactPackage.ts

@@ -4,6 +4,7 @@
 import { PackageKind, ScenePackage } from '@cratis/scene.model';
 import { ScenePackageBundle } from '@cratis/scene.react';
 import { primeReactComponents } from './primeReactComponents';
+import { primeReactDescriptors } from './primeReactDescriptors';
 import { primeReactThemeNames, primeReactThemes } from './theme';
 
 /**
@@ -34,9 +35,9 @@ export const primeReactPackageManifest: ScenePackage = {
 
     components: [
         'inputText', 'inputTextarea', 'inputNumber', 'password', 'floatLabel', 'iconField', 'dropdown', 'multiSelect',
-        'listBox', 'selectButton', 'checkbox', 'radioButton', 'toggleSwitch', 'slider', 'rating', 'knob', 'calendar', 'colorPicker',
+        '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',
+        'column', 'dataView', 'tree', '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',
@@ -85,5 +86,6 @@ export const primeReactPackageManifest: ScenePackage = {
 export const primeReactPackage: ScenePackageBundle = {
     manifest: primeReactPackageManifest,
     components: primeReactComponents,
+    descriptors: primeReactDescriptors,
     themes: primeReactThemes,
 };

package/properties.ts

@@ -106,6 +106,20 @@ export function recordArrayProperty(element: SceneElement, name: string): Record
     );
 }
 
+/**
+ * Reads one structured value off a Scene element.
+ *
+ * Chart data and options intentionally stay as authored objects: these adapters pass their vocabulary to
+ * their underlying library instead of choosing a partial Scene-owned chart schema that would discard
+ * future Chart.js fields during a legacy migration.
+ */
+export function recordProperty(element: SceneElement, name: string): Record<string, unknown> | undefined {
+    const value = element.properties[name];
+    return typeof value === 'object' && value !== undefined && value !== null && !Array.isArray(value)
+        ? value as Record<string, unknown>
+        : undefined;
+}
+
 /**
  * Reads a selection component's options off a Scene element, normalizing both shapes a screen may use.
  *

package/structurallyEqual.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Compares values that can survive a Scene document serialization round trip.
+ *
+ * Authored data (chart datasets, option values, current values) arrives as plain JSON. Every edit to a
+ * Scene document clones the whole document, so the same data gets a new object identity with no change in
+ * content; reference equality would treat each unrelated edit as a change. Primitives compare with
+ * `Object.is`, so `0` and `-0`, or `NaN` and `NaN`, are told apart exactly as `Object.is` does.
+ */
+export function structurallyEqual(left: unknown, right: unknown): boolean {
+    if (Object.is(left, right)) return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left) && Array.isArray(right)
+            && left.length === right.length
+            && left.every((value, index) => structurallyEqual(value, right[index]));
+    }
+
+    if (!isRecord(left) || !isRecord(right)) return false;
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return leftKeys.length === rightKeys.length
+        && leftKeys.every((key, index) => key === rightKeys[index] && structurallyEqual(left[key], right[key]));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object';
+}

package/useStructuralValue.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useRef } from 'react';
+import { structurallyEqual } from './structurallyEqual';
+
+/**
+ * Returns the same reference for as long as the content of `value` is unchanged.
+ *
+ * Use it for authored data that feeds an effect dependency list: a cloned document gives that data a new
+ * identity on every unrelated edit, which would otherwise rerun the effect and rebuild whatever it owns.
+ */
+export function useStructuralValue<TValue>(value: TValue): TValue {
+    const stable = useRef(value);
+    if (!structurallyEqual(stable.current, value)) stable.current = value;
+    return stable.current;
+}