@cratis/scene.primereact 0.1.0

package/theme/themePresets.ts

@@ -0,0 +1,535 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Theme } from '@cratis/scene.model';
+
+/**
+ * One PrimeReact theme, minus everything that is identical for all of them.
+ *
+ * Attribution and compatibility are deliberately *not* here: they are added once, for every preset, in
+ * `primeReactThemes`. Every one of these themes was made by PrimeTek and none of them by us, so crediting
+ * them one entry at a time would make it possible to add a twenty-sixth and forget - and a dropped
+ * credit is not the kind of mistake a code review reliably catches.
+ */
+export type ThemePreset = Omit<Theme, 'compatibleWith' | 'author' | 'authorUrl' | 'license'>;
+
+/**
+ * Every free PrimeReact 10 theme this package exposes, and the Scene tokens each one stands for.
+ *
+ * This is data, not logic. Each `name` is the folder the theme lives in under
+ * `primereact/resources/themes`, which is what makes `primeReactThemeStylesheet` a direct lookup rather
+ * than a table that could fall out of step with the files on disk.
+ *
+ * The token values are read verbatim out of each theme's own `theme.css` `:root` block, so a Scene token
+ * always agrees with what the PrimeReact stylesheet actually renders. That fidelity is the point of the
+ * bridge, and it is kept even where a theme's own values are odd - `lara-light-teal` really does ship
+ * the same color for `--highlight-bg` and `--highlight-text-color`, and mirroring it keeps the token
+ * layer honest about what the component skin will do.
+ *
+ * There is exactly one deliberate deviation: PrimeReact 10.9.8 ships `viva-dark` with an unresolved SCSS
+ * expression, `rgba($primaryColor, 0.08)`, for `--surface-hover`. That is not valid CSS and resolves to
+ * nothing at all, so it cannot be mirrored; the intended value - the theme's primary color at 8% - is
+ * used instead.
+ */
+export const themePresets: ThemePreset[] = [
+    {
+        name: 'lara-light-blue',
+        description: 'The PrimeReact default: a clean, roomy light theme on a blue accent.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#3b82f6',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#f9fafb',
+            'surface.card': '#ffffff',
+            'surface.border': '#dfe7ef',
+            'surface.hover': '#f6f9fc',
+            'surface.overlay': '#ffffff',
+            'text.color': '#4b5563',
+            'text.mutedColor': '#6b7280',
+            'highlight.background': '#eff6ff',
+            'highlight.color': '#1d4ed8',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 0.2rem #bfdbfe',
+        },
+    },
+    {
+        name: 'lara-dark-blue',
+        description: 'The Lara family in dark, on a blue accent.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#60a5fa',
+            'primary.contrastColor': '#030712',
+            'surface.background': '#111827',
+            'surface.card': '#1f2937',
+            'surface.border': 'rgba(255, 255, 255, 0.1)',
+            'surface.hover': 'rgba(255, 255, 255, 0.03)',
+            'surface.overlay': '#1f2937',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(96, 165, 250, 0.16)',
+            'highlight.color': 'rgba(255, 255, 255, 0.87)',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 0.2rem rgba(96, 165, 250, 0.2)',
+        },
+    },
+    {
+        name: 'lara-light-indigo',
+        description: 'Lara light with an indigo accent.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#6366f1',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#f9fafb',
+            'surface.card': '#ffffff',
+            'surface.border': '#dfe7ef',
+            'surface.hover': '#f6f9fc',
+            'surface.overlay': '#ffffff',
+            'text.color': '#4b5563',
+            'text.mutedColor': '#6b7280',
+            'highlight.background': '#eef2ff',
+            'highlight.color': '#4338ca',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 0.2rem #c7d2fe',
+        },
+    },
+    {
+        name: 'lara-dark-indigo',
+        description: 'Lara dark with an indigo accent.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#818cf8',
+            'primary.contrastColor': '#030712',
+            'surface.background': '#111827',
+            'surface.card': '#1f2937',
+            'surface.border': 'rgba(255, 255, 255, 0.1)',
+            'surface.hover': 'rgba(255, 255, 255, 0.03)',
+            'surface.overlay': '#1f2937',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(129, 140, 248, 0.16)',
+            'highlight.color': 'rgba(255, 255, 255, 0.87)',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 0.2rem rgba(129, 140, 248, 0.2)',
+        },
+    },
+    {
+        name: 'lara-light-purple',
+        description: 'Lara light with a purple accent.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#8b5cf6',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#f9fafb',
+            'surface.card': '#ffffff',
+            'surface.border': '#dfe7ef',
+            'surface.hover': '#f6f9fc',
+            'surface.overlay': '#ffffff',
+            'text.color': '#4b5563',
+            'text.mutedColor': '#6b7280',
+            'highlight.background': '#f5f3ff',
+            'highlight.color': '#6d28d9',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 0.2rem #ddd6fe',
+        },
+    },
+    {
+        name: 'lara-dark-purple',
+        description: 'Lara dark with a purple accent.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#a78bfa',
+            'primary.contrastColor': '#030712',
+            'surface.background': '#111827',
+            'surface.card': '#1f2937',
+            'surface.border': 'rgba(255, 255, 255, 0.1)',
+            'surface.hover': 'rgba(255, 255, 255, 0.03)',
+            'surface.overlay': '#1f2937',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(167, 139, 250, 0.16)',
+            'highlight.color': 'rgba(255, 255, 255, 0.87)',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 0.2rem rgba(167, 139, 250, 0.2)',
+        },
+    },
+    {
+        name: 'lara-light-teal',
+        description: 'Lara light with a teal accent.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#14b8a6',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#f9fafb',
+            'surface.card': '#ffffff',
+            'surface.border': '#dfe7ef',
+            'surface.hover': '#f6f9fc',
+            'surface.overlay': '#ffffff',
+            'text.color': '#4b5563',
+            'text.mutedColor': '#6b7280',
+            'highlight.background': '#0f766e',
+            'highlight.color': '#0f766e',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 0.2rem #99f6e4',
+        },
+    },
+    {
+        name: 'lara-dark-teal',
+        description: 'Lara dark with a teal accent.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#2dd4bf',
+            'primary.contrastColor': '#030712',
+            'surface.background': '#111827',
+            'surface.card': '#1f2937',
+            'surface.border': 'rgba(255, 255, 255, 0.1)',
+            'surface.hover': 'rgba(255, 255, 255, 0.03)',
+            'surface.overlay': '#1f2937',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(45, 212, 191, 0.16)',
+            'highlight.color': 'rgba(255, 255, 255, 0.87)',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 0.2rem rgba(45, 212, 191, 0.2)',
+        },
+    },
+    {
+        name: 'saga-blue',
+        description: 'PrimeTek\'s earlier light theme: tighter spacing and smaller radii than Lara.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#2196f3',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#f8f9fa',
+            'surface.card': '#ffffff',
+            'surface.border': '#dee2e6',
+            'surface.hover': '#e9ecef',
+            'surface.overlay': '#ffffff',
+            'text.color': '#495057',
+            'text.mutedColor': '#6c757d',
+            'highlight.background': '#e3f2fd',
+            'highlight.color': '#495057',
+            'content.borderRadius': '3px',
+            'focus.ring': '0 0 0 0.2rem #a6d5fa',
+        },
+    },
+    {
+        name: 'vela-blue',
+        description: 'Saga\'s dark counterpart, on a desaturated blue-grey ground.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#64b5f6',
+            'primary.contrastColor': '#212529',
+            'surface.background': '#17212f',
+            'surface.card': '#1f2d40',
+            'surface.border': '#304562',
+            'surface.hover': 'rgba(255, 255, 255, 0.03)',
+            'surface.overlay': '#1f2d40',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(100, 181, 246, 0.16)',
+            'highlight.color': 'rgba(255, 255, 255, 0.87)',
+            'content.borderRadius': '3px',
+            'focus.ring': '0 0 0 1px #93cbf9',
+        },
+    },
+    {
+        name: 'arya-blue',
+        description: 'Saga\'s near-black dark counterpart, for high-contrast dark surfaces.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#64b5f6',
+            'primary.contrastColor': '#212529',
+            'surface.background': '#121212',
+            'surface.card': '#1e1e1e',
+            'surface.border': '#383838',
+            'surface.hover': 'rgba(255, 255, 255, 0.03)',
+            'surface.overlay': '#1e1e1e',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(100, 181, 246, 0.16)',
+            'highlight.color': 'rgba(255, 255, 255, 0.87)',
+            'content.borderRadius': '3px',
+            'focus.ring': '0 0 0 1px #93cbf9',
+        },
+    },
+    {
+        name: 'bootstrap4-light-blue',
+        description: 'PrimeTek\'s interpretation of the Bootstrap 4 look, in light.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#007bff',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#efefef',
+            'surface.card': '#ffffff',
+            'surface.border': '#dee2e6',
+            'surface.hover': '#e9ecef',
+            'surface.overlay': '#ffffff',
+            'text.color': '#212529',
+            'text.mutedColor': '#6c757d',
+            'highlight.background': '#007bff',
+            'highlight.color': '#ffffff',
+            'content.borderRadius': '4px',
+            'focus.ring': '0 0 0 0.2rem rgba(38, 143, 255, 0.5)',
+        },
+    },
+    {
+        name: 'bootstrap4-dark-blue',
+        description: 'PrimeTek\'s interpretation of the Bootstrap 4 look, in dark.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#8dd0ff',
+            'primary.contrastColor': '#151515',
+            'surface.background': '#20262e',
+            'surface.card': '#2a323d',
+            'surface.border': '#3f4b5b',
+            'surface.hover': 'rgba(255, 255, 255, 0.04)',
+            'surface.overlay': '#2a323d',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': '#8dd0ff',
+            'highlight.color': '#151515',
+            'content.borderRadius': '4px',
+            'focus.ring': '0 0 0 1px #e3f3fe',
+        },
+    },
+    {
+        name: 'soho-light',
+        description: 'A soft, low-contrast light theme on a violet accent.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#7254f3',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#eff3f8',
+            'surface.card': '#ffffff',
+            'surface.border': '#dfe7ef',
+            'surface.hover': '#f6f9fc',
+            'surface.overlay': '#ffffff',
+            'text.color': '#043d75',
+            'text.mutedColor': '#708da9',
+            'highlight.background': '#e2dcfc',
+            'highlight.color': '#7254f3',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 1px #c7bbfa',
+        },
+    },
+    {
+        name: 'soho-dark',
+        description: 'Soho in dark, on the same violet accent.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#b19df7',
+            'primary.contrastColor': 'hsl(234, 15%, 13%)',
+            'surface.background': '#1d1e27',
+            'surface.card': '#282936',
+            'surface.border': '#3e4053',
+            'surface.hover': 'rgba(255, 255, 255, 0.03)',
+            'surface.overlay': '#282936',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(177, 157, 247, 0.16)',
+            'highlight.color': '#b19df7',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 1px #e0d8fc',
+        },
+    },
+    {
+        name: 'viva-light',
+        description: 'A neutral, understated light theme on a muted indigo accent.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#5472d4',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#f5f5f5',
+            'surface.card': '#ffffff',
+            'surface.border': '#ebebeb',
+            'surface.hover': '#edf0fa',
+            'surface.overlay': '#ffffff',
+            'text.color': '#6c6c6c',
+            'text.mutedColor': '#898989',
+            'highlight.background': '#ced6f1',
+            'highlight.color': '#585858',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 0.1rem #bbc7ee',
+        },
+    },
+    {
+        name: 'viva-dark',
+        description: 'Viva in dark, on a near-black blue-grey ground.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#9eade6',
+            'primary.contrastColor': '#121212',
+            'surface.background': '#0e1315',
+            'surface.card': '#161d21',
+            'surface.border': '#263238',
+            'surface.hover': 'rgba(158, 173, 230, 0.08)',
+            'surface.overlay': '#161d21',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(158, 173, 230, 0.16)',
+            'highlight.color': '#9eade6',
+            'content.borderRadius': '6px',
+            'focus.ring': '0 0 0 1px #9eade6',
+        },
+    },
+    {
+        name: 'md-light-indigo',
+        description: 'PrimeTek\'s interpretation of Material Design, in light on indigo.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#3F51B5',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#fafafa',
+            'surface.card': '#ffffff',
+            'surface.border': 'rgba(0, 0, 0, 0.12)',
+            'surface.hover': 'rgba(0, 0, 0, 0.04)',
+            'surface.overlay': '#ffffff',
+            'text.color': 'rgba(0, 0, 0, 0.87)',
+            'text.mutedColor': 'rgba(0, 0, 0, 0.6)',
+            'highlight.background': 'rgba(63, 81, 181, 0.12)',
+            'highlight.color': '#3F51B5',
+            'content.borderRadius': '4px',
+            'focus.ring': 'none',
+        },
+    },
+    {
+        name: 'md-dark-indigo',
+        description: 'PrimeTek\'s interpretation of Material Design, in dark on indigo.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#9FA8DA',
+            'primary.contrastColor': '#121212',
+            'surface.background': '#121212',
+            'surface.card': '#1e1e1e',
+            'surface.border': 'hsla(0, 0%, 100%, 0.12)',
+            'surface.hover': 'hsla(0, 0%, 100%, 0.04)',
+            'surface.overlay': '#262626',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(159, 168, 218, 0.16)',
+            'highlight.color': '#9FA8DA',
+            'content.borderRadius': '4px',
+            'focus.ring': 'none',
+        },
+    },
+    {
+        name: 'mdc-light-indigo',
+        description: 'The Material interpretation with compact density, in light.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#3F51B5',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#fafafa',
+            'surface.card': '#ffffff',
+            'surface.border': 'rgba(0, 0, 0, 0.12)',
+            'surface.hover': 'rgba(0, 0, 0, 0.04)',
+            'surface.overlay': '#ffffff',
+            'text.color': 'rgba(0, 0, 0, 0.87)',
+            'text.mutedColor': 'rgba(0, 0, 0, 0.6)',
+            'highlight.background': 'rgba(63, 81, 181, 0.12)',
+            'highlight.color': '#3F51B5',
+            'content.borderRadius': '4px',
+            'focus.ring': 'none',
+        },
+    },
+    {
+        name: 'mdc-dark-indigo',
+        description: 'The Material interpretation with compact density, in dark.',
+        isDark: true,
+        tokens: {
+            'primary.color': '#9FA8DA',
+            'primary.contrastColor': '#121212',
+            'surface.background': '#121212',
+            'surface.card': '#1e1e1e',
+            'surface.border': 'hsla(0, 0%, 100%, 0.12)',
+            'surface.hover': 'hsla(0, 0%, 100%, 0.04)',
+            'surface.overlay': '#262626',
+            'text.color': 'rgba(255, 255, 255, 0.87)',
+            'text.mutedColor': 'rgba(255, 255, 255, 0.6)',
+            'highlight.background': 'rgba(159, 168, 218, 0.16)',
+            'highlight.color': '#9FA8DA',
+            'content.borderRadius': '4px',
+            'focus.ring': 'none',
+        },
+    },
+    {
+        name: 'nano',
+        description: 'A dense, near-square theme for information-heavy screens.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#1174c0',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#f2f4f8',
+            'surface.card': '#ffffff',
+            'surface.border': '#dee2e6',
+            'surface.hover': '#dde1e6',
+            'surface.overlay': '#ffffff',
+            'text.color': '#343a3f',
+            'text.mutedColor': '#697077',
+            'highlight.background': '#44a1d9',
+            'highlight.color': '#ffffff',
+            'content.borderRadius': '1px',
+            'focus.ring': '0 0 0 0.2rem #90c9f5',
+        },
+    },
+    {
+        name: 'mira',
+        description: 'A calm light theme on a Nord-inspired blue-grey palette.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#5e81ac',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#eceff4',
+            'surface.card': '#ffffff',
+            'surface.border': '#e5e9f0',
+            'surface.hover': '#d8dee9',
+            'surface.overlay': '#ffffff',
+            'text.color': '#4c566a',
+            'text.mutedColor': '#81a1c1',
+            'highlight.background': '#d8dee9',
+            'highlight.color': '#2e3440',
+            'content.borderRadius': '4px',
+            'focus.ring': '0 0 0 0.2rem #c0d0e0',
+        },
+    },
+    {
+        name: 'fluent-light',
+        description: 'PrimeTek\'s interpretation of the Microsoft Fluent look, in light.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#0078d4',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#faf9f8',
+            'surface.card': '#ffffff',
+            'surface.border': '#edebe9',
+            'surface.hover': '#f3f2f1',
+            'surface.overlay': '#ffffff',
+            'text.color': '#323130',
+            'text.mutedColor': '#605e5c',
+            'highlight.background': '#edebe9',
+            'highlight.color': '#323130',
+            'content.borderRadius': '2px',
+            'focus.ring': 'inset 0 0 0 1px #605e5c',
+        },
+    },
+    {
+        name: 'tailwind-light',
+        description: 'PrimeTek\'s interpretation of the Tailwind UI look, in light.',
+        isDark: false,
+        tokens: {
+            'primary.color': '#4f46e5',
+            'primary.contrastColor': '#ffffff',
+            'surface.background': '#fafafa',
+            'surface.card': '#ffffff',
+            'surface.border': '#e5e7eb',
+            'surface.hover': '#f4f4f5',
+            'surface.overlay': '#ffffff',
+            'text.color': '#3f3f46',
+            'text.mutedColor': '#71717a',
+            'highlight.background': '#eef2ff',
+            'highlight.color': '#312e81',
+            'content.borderRadius': '0.375rem',
+            'focus.ring': '0 0 0 1px #6366f1',
+        },
+    },
+];

package/theme/usePrimeReactTheme.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect } from 'react';
+import { Theme } from '@cratis/scene.model';
+import { applyPrimeReactTheme } from './applyPrimeReactTheme';
+import { themeLinkElementId } from './primeReactThemeStylesheet';
+
+/**
+ * Keeps the loaded PrimeReact theme stylesheet in step with the active Scene {@link Theme}.
+ *
+ * Theming a Scene screen that uses this package takes two halves, and this is the half `SceneThemeProvider`
+ * cannot do. The provider writes the theme's semantic tokens onto the wrapping element, which reaches
+ * anything reading `--scene-*` - this package's own wrappers, `core`'s primitives, a layout's CSS. But
+ * PrimeReact 10's components are skinned by a compiled stylesheet, and no amount of token-setting
+ * changes which stylesheet is loaded. So: provider for the tokens, this hook for the stylesheet.
+ *
+ * Use them together:
+ *
+ * ```tsx
+ * const [theme, setTheme] = useState(primeReactTheme('lara-light-blue'));
+ * usePrimeReactTheme(theme);
+ * return <SceneThemeProvider theme={theme}>{children}</SceneThemeProvider>;
+ * ```
+ *
+ * Switching is live: nothing reloads, nothing below the provider remounts, and no state is lost. That is
+ * what lets a gallery change theme as fast as someone can click through a picker, which is the whole
+ * reason theme switching is re-resolution rather than a restart.
+ *
+ * @param theme The active theme. A theme this package does not ship - or `undefined` - leaves the loaded
+ * stylesheet alone rather than unloading it, so a profile mixing in a theme from another package does
+ * not strip PrimeReact's skin on its way past.
+ * @param linkElementId The id of the stylesheet `<link>`, should the application use something other than
+ * PrimeReact's conventional `theme-link`.
+ */
+export function usePrimeReactTheme(theme: Theme | undefined, linkElementId: string = themeLinkElementId): void {
+    const themeName = theme?.name;
+
+    useEffect(() => {
+        if (themeName === undefined) return;
+        applyPrimeReactTheme(themeName, linkElementId);
+    }, [themeName, linkElementId]);
+}

package/treeNodes.ts

@@ -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 type { TreeNode } from 'primereact/treenode';
+import { SceneElement } from '@cratis/scene.model';
+import { arrayProperty } from './properties';
+
+/**
+ * Turns raw authored entries into the `TreeNode` model PrimeReact's tree, tree table, tree select and
+ * organization chart all share.
+ *
+ * A `key` is synthesized from the node's path when an author did not supply one. That is not cosmetic:
+ * PrimeReact keys expansion, selection and virtual scrolling off `key`, so a tree of unkeyed nodes
+ * 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.
+ *
+ * @param entries The raw entries to convert.
+ * @param parentKey The key of the node these entries belong to, used to build stable child keys.
+ * @returns The converted nodes, in order.
+ */
+export function toTreeNodes(entries: unknown[], parentKey = ''): TreeNode[] {
+    const nodes: TreeNode[] = [];
+    entries.forEach((entry, index) => {
+        const path = parentKey === '' ? `${index}` : `${parentKey}-${index}`;
+        if (typeof entry === 'string') {
+            nodes.push({ key: path, label: 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 };
+        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);
+        nodes.push(node);
+    });
+
+    return nodes;
+}
+
+/**
+ * Reads a tree model off a Scene element's properties.
+ *
+ * @param element The element whose properties to read.
+ * @param name The property name holding the entries.
+ * @returns The converted nodes, empty when the property is missing or is not an array.
+ */
+export function treeNodesProperty(element: SceneElement, name: string): TreeNode[] {
+    return toTreeNodes(arrayProperty(element, name));
+}