@cratis/scene.primereact 0.1.0

package/screen/PrimeTitle.tsx

@@ -0,0 +1,27 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createElement } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { numberProperty, stringProperty } from '../properties';
+
+/**
+ * The `PrimeReact:title` component - one of Screenplay's screen directives.
+ *
+ * Renders a real heading element at the authored level rather than a styled span, because heading level
+ * is the document outline a screen reader navigates by; getting it right is not a styling choice. The
+ * level is clamped to 1-6 so an out-of-range value degrades to a valid heading instead of an invalid tag.
+ */
+export function PrimeTitle({ element }: RegisteredComponentProps) {
+    const level = Math.min(6, Math.max(1, Math.round(numberProperty(element, 'level', 1))));
+    const sizes = ['text-3xl', 'text-2xl', 'text-xl', 'text-lg', 'text-base', 'text-sm'];
+    return createElement(
+        `h${level}`,
+        {
+            'data-scene-id': element.id,
+            className: `${sizes[level - 1]} font-semibold`,
+            style: { color: 'var(--scene-text-color)' },
+        },
+        stringProperty(element, 'text', '')
+    );
+}

package/screen/ScreenGallery.stories.tsx

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { SceneElementView } from '@cratis/scene.react';
+import { primeReactComponents } from '../primeReactComponents';
+import { sceneComponent, sceneGallery } from '../storyElements';
+
+const meta = {
+    title: 'PrimeReact/Screen',
+    component: SceneElementView,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: { description: { component: 'Screenplay\'s screen vocabulary, plus `text` - the third name shared with `core`. A screen compiled from a .play file emits these directive kinds, so declaring them is what lets it render through this package with no translation step.' } },
+    },
+} satisfies Meta<typeof SceneElementView>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** Every component in this family, rendered through the real registry by the real renderer. */
+export const Gallery: Story = {
+    args: {
+        element: sceneGallery('gallery', [
+            sceneComponent('text', 'text', { text: 'A run of prose that follows the theme.' }),
+            sceneComponent('title', 'title', { text: 'Project overview', level: 2 }),
+            sceneComponent('field', 'field', { label: 'Owner', value: 'Ada Lovelace' }),
+            sceneComponent('section', 'section', { title: 'Contact' }, { content: [sceneComponent('sectionField', 'field', { label: 'Email', value: 'ada@example.com' })] }),
+            sceneComponent('summary', 'summary', { title: 'At a glance', items: [{ label: 'Status', value: 'Active' }, { label: 'Owner', value: 'Ada' }] }),
+            sceneComponent('action', 'action', { label: 'Archive project', intent: 'destructive' }),
+        ]),
+        registry: primeReactComponents,
+        resolveBinding: () => undefined,
+    },
+};

package/screen/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './PrimeText';
+export * from './PrimeTitle';
+export * from './PrimeField';
+export * from './PrimeSection';
+export * from './PrimeSummary';
+export * from './PrimeAction';

package/storyElements.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Control, ExternalComponent, HorizontalAlignment, Panel, SceneElement, VerticalAlignment, Visibility } from '@cratis/scene.model';
+import { componentRegistryKey } from '@cratis/scene.react';
+
+/**
+ * Builders for the Scene element trees the stories in this package render.
+ *
+ * The stories deliberately do not call an adapter directly. They build a real element tree, hand it to
+ * the real `SceneElementView` with the real `primeReactComponents` registry, and let the engine walk it -
+ * because the thing worth having visual coverage of is the whole path, not the leaf. A story that
+ * rendered `<PrimeDropdown element={...} />` would keep passing after the registry key was misspelled.
+ *
+ * These live in the source tree rather than in a story file because ten galleries share them.
+ */
+
+/**
+ * The base every visual element carries, filled with the neutral values a story never varies.
+ */
+function control(id: string): Control {
+    return {
+        id,
+        name: id,
+        properties: {},
+        visibility: Visibility.Visible,
+        isEnabled: true,
+        opacity: 1,
+        size: {},
+        zIndex: 0,
+        minimumSize: {},
+        maximumSize: {},
+        margin: { left: 0, top: 0, right: 0, bottom: 0 },
+        horizontalAlignment: HorizontalAlignment.Stretch,
+        verticalAlignment: VerticalAlignment.Stretch,
+        borderThickness: { left: 0, top: 0, right: 0, bottom: 0 },
+        padding: { left: 0, top: 0, right: 0, bottom: 0 },
+        tabIndex: 0,
+    };
+}
+
+/**
+ * An `ExternalComponent` naming one of this package's components.
+ *
+ * The name is passed bare and qualified here with {@link componentRegistryKey}, so a story reads as the
+ * abstract name a screen would write rather than as a registry key.
+ *
+ * @param id A unique id within the story's tree.
+ * @param componentName The bare component name, as declared in the manifest.
+ * @param properties The element's authored configuration.
+ * @param slots Child elements, by slot name.
+ * @returns The element.
+ */
+export function sceneComponent(
+    id: string,
+    componentName: string,
+    properties: Record<string, unknown> = {},
+    slots: Record<string, SceneElement[]> = {}
+): ExternalComponent {
+    return { ...control(id), properties, componentName: componentRegistryKey('PrimeReact', componentName), slots };
+}
+
+/**
+ * A panel holding children - the renderer turns it into a plain wrapping `div`.
+ *
+ * @param id A unique id within the story's tree.
+ * @param children The children to lay out.
+ * @returns The panel.
+ */
+export function scenePanel(id: string, children: SceneElement[]): Panel {
+    return { ...control(id), children };
+}
+
+/**
+ * A gallery: every entry wrapped in this package's own `section` component so it is labeled with the
+ * abstract name it demonstrates.
+ *
+ * Using `section` rather than a hand-written heading means the labels themselves go through the registry,
+ * so a gallery that renders proves one more adapter than it appears to.
+ *
+ * @param id A unique id within the story's tree.
+ * @param entries The components to show, each with the abstract name it is registered under.
+ * @returns The panel to hand to `SceneElementView`.
+ */
+export function sceneGallery(id: string, entries: ExternalComponent[]): Panel {
+    return scenePanel(
+        id,
+        entries.map((entry) =>
+            sceneComponent(`${entry.id}-section`, 'section', { title: entry.componentName.slice('PrimeReact:'.length) }, { content: [entry] })
+        )
+    );
+}

package/theme/ThemeSwitching.stories.tsx

@@ -0,0 +1,92 @@
+// 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 type { Meta, StoryObj } from '@storybook/react';
+import { Theme } from '@cratis/scene.model';
+import { SceneElementView, SceneThemeProvider } from '@cratis/scene.react';
+import { primeReactComponents } from '../primeReactComponents';
+import { sceneComponent, sceneGallery } from '../storyElements';
+import { primeReactThemes } from './primeReactThemes';
+import { usePrimeReactTheme } from './usePrimeReactTheme';
+
+const showcase = sceneGallery('theme-showcase', [
+    sceneComponent('themeTitle', 'title', { text: 'Live theme switching', level: 3 }),
+    sceneComponent('themeButtons', 'buttonGroup', { buttons: ['Save', 'Duplicate', 'Archive'] }),
+    sceneComponent('themeDropdown', 'dropdown', { options: ['Draft', 'In review', 'Published'], value: 'In review' }),
+    sceneComponent('themeSwitch', 'toggleSwitch', { label: 'Notify the team', checked: true }),
+    sceneComponent('themeTable', 'table', {
+        rows: [
+            { name: 'Ada', role: 'Engineer' },
+            { name: 'Grace', role: 'Admiral' },
+        ],
+    }),
+    sceneComponent('themeMessage', 'message', { severity: 'info', text: 'Every surface below follows the selected theme.' }),
+    sceneComponent('themeSummary', 'summary', {
+        title: 'At a glance',
+        items: [
+            { label: 'Status', value: 'Active' },
+            { label: 'Owner', value: 'Ada' },
+        ],
+    }),
+]);
+
+/**
+ * Both halves of theming, wired together the way an application does it.
+ *
+ * `usePrimeReactTheme` swaps the compiled PrimeReact stylesheet that skins the components;
+ * `SceneThemeProvider` writes the same theme's semantic tokens onto the wrapping element, which is what
+ * reaches this package's own wrappers and anything else reading `--scene-*`. Neither half is enough
+ * alone - drop the hook and PrimeReact's components keep the old skin; drop the provider and the
+ * wrappers around them do not follow.
+ *
+ * Nothing reloads and nothing below the provider remounts, so state survives the switch: type into a
+ * field, change the theme, and what you typed is still there.
+ */
+const ThemeSwitcher = () => {
+    const [theme, setTheme] = useState<Theme>(primeReactThemes[0]);
+    usePrimeReactTheme(theme);
+
+    return (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+            <select
+                aria-label='Theme'
+                value={theme.name}
+                onChange={(event) => setTheme(primeReactThemes.find((candidate) => candidate.name === event.target.value) ?? primeReactThemes[0])}>
+                {primeReactThemes.map((candidate) => (
+                    <option key={candidate.name} value={candidate.name}>
+                        {candidate.name}
+                        {candidate.isDark ? ' (dark)' : ''}
+                    </option>
+                ))}
+            </select>
+            <SceneThemeProvider theme={theme}>
+                <div style={{ padding: '1rem' }}>
+                    <SceneElementView element={showcase} registry={primeReactComponents} resolveBinding={() => undefined} />
+                </div>
+            </SceneThemeProvider>
+        </div>
+    );
+};
+
+const meta = {
+    title: 'PrimeReact/Theme switching',
+    component: ThemeSwitcher,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+        docs: {
+            description: {
+                component:
+                    'Switch between all 25 free PrimeTek themes this package ships. Every theme credits PrimeTek and is used under the MIT license the primereact package ships under.',
+            },
+        },
+    },
+} satisfies Meta<typeof ThemeSwitcher>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** Pick a theme and watch the stylesheet and the tokens change together, with no reload. */
+export const Playground: Story = {};

package/theme/applyPrimeReactTheme.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { primeReactThemeStylesheet, themeLinkElementId } from './primeReactThemeStylesheet';
+
+/**
+ * Swaps the loaded PrimeReact theme stylesheet, live, with no reload and no remount.
+ *
+ * This follows the mechanism PrimeReact 10.9.8 implements in `PrimeReactContext.changeTheme` (see
+ * `node_modules/primereact/api/api.js`), because a PrimeReact 10 theme is a pre-compiled CSS file rather
+ * than a set of runtime variables - there is nothing to set, only a different file to load. What
+ * `changeTheme` does is find the `<link>` by id, build a new URL, create a *replacement* `<link>` element
+ * and swap it into the same position. Creating a new element rather than assigning to `href` is the part
+ * that matters: some browsers do not reliably re-fetch a stylesheet whose `href` is mutated in place.
+ *
+ * Two things are done differently, both deliberately:
+ *
+ * - PrimeReact string-replaces the old theme name anywhere in the URL. That breaks as soon as a theme
+ *   name also appears elsewhere in the path (an application served from `/nano/`, say, switching away
+ *   from the `nano` theme). This replaces the theme *folder segment* instead, which is unambiguous.
+ * - PrimeReact throws when the `<link>` is missing. Here a missing link is created, because a Scene host
+ *   embedding a preview has no reason to have pre-declared one, and refusing to theme a page for want of
+ *   an element we can add ourselves is not a useful failure.
+ *
+ * The application keeps ownership of *where* themes are served from: when the link already exists, only
+ * its theme folder is rewritten and the rest of the URL is left exactly as the host wrote it.
+ *
+ * @param themeName The theme to load, as named in `primeReactThemes`.
+ * @param linkElementId The id of the stylesheet `<link>`, matching PrimeReact's own `changeTheme` argument.
+ * @returns `true` when the stylesheet was swapped, `false` when the theme is unknown or there is no document.
+ */
+export function applyPrimeReactTheme(themeName: string, linkElementId: string = themeLinkElementId): boolean {
+    const stylesheet = primeReactThemeStylesheet(themeName);
+    if (stylesheet === undefined || typeof document === 'undefined') return false;
+
+    const existing = document.getElementById(linkElementId);
+    const href = existing?.getAttribute('href');
+    const nextHref = href === undefined || href === null ? stylesheet : href.replace(/[^/]+\/theme\.css(\?.*)?$/, `${themeName}/theme.css$1`);
+
+    const link = document.createElement('link');
+    link.setAttribute('rel', 'stylesheet');
+    link.setAttribute('id', linkElementId);
+    link.setAttribute('href', nextHref);
+
+    if (existing?.parentNode) {
+        existing.parentNode.replaceChild(link, existing);
+    } else {
+        document.head.appendChild(link);
+    }
+
+    return true;
+}

package/theme/index.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './themePresets';
+export * from './primeReactThemes';
+export * from './primeReactThemeStylesheet';
+export * from './applyPrimeReactTheme';
+export * from './usePrimeReactTheme';

package/theme/primeReactThemeStylesheet.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { primeReactTheme } from './primeReactThemes';
+
+/**
+ * The module path of a theme's compiled stylesheet.
+ *
+ * PrimeReact 10 themes are pre-compiled CSS files on disk, one folder per theme, so switching theme is
+ * ultimately a question of which file is loaded. This is the one place that knows the layout of those
+ * folders.
+ *
+ * An unknown name returns `undefined` rather than a plausible-looking path. A string built for a theme
+ * that does not exist would produce a 404 at load time and an unstyled application - a failure that
+ * shows up far from the typo that caused it - whereas `undefined` is checkable at the call site.
+ *
+ * @param themeName The theme name, as it appears in {@link primeReactThemes}.
+ * @returns The stylesheet path, or `undefined` when this package ships no theme by that name.
+ */
+export function primeReactThemeStylesheet(themeName: string): string | undefined {
+    return primeReactTheme(themeName) === undefined ? undefined : `primereact/resources/themes/${themeName}/theme.css`;
+}
+
+/**
+ * The id of the `<link>` element the theme stylesheet is loaded through.
+ *
+ * PrimeReact's own `PrimeReactContext.changeTheme` takes this id as an argument and defaults to nothing;
+ * `theme-link` is the id PrimeReact's documentation and templates use, so matching it means an
+ * application already set up for PrimeReact theme switching needs no extra wiring to work with
+ * {@link usePrimeReactTheme}.
+ */
+export const themeLinkElementId = 'theme-link';

package/theme/primeReactThemes.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Theme } from '@cratis/scene.model';
+import { themePresets } from './themePresets';
+
+/**
+ * The packages a PrimeReact theme declares itself compatible with.
+ *
+ * `PrimeReact` and `Tailwind` are obvious - the stylesheet skins PrimeReact's components, and this
+ * package's own wrappers lay themselves out with Tailwind utilities.
+ *
+ * `core` is the interesting one, and it is listed deliberately rather than by reflex. A theme reaches a
+ * screen in two layers: a stylesheet that only ever matches PrimeReact's own `.p-*` elements, and a set
+ * of semantic Scene tokens that `SceneThemeProvider` writes onto the wrapping element. The second layer
+ * applies to *everything* underneath it, `core`'s unstyled primitives included - they inherit the
+ * theme's type color and can read any token they choose to. So the claim being made is precise: these
+ * themes genuinely reach `core`'s components, through tokens rather than through the component skin.
+ *
+ * This has to be said explicitly because `ThemeCompatibility` has no implicit exemption for `core`. A
+ * theme that leaves it out is reported incompatible for every profile that lists `core`, which for a
+ * theme that really does apply would be a false alarm on nearly every profile there is.
+ */
+export const primeReactThemeCompatibility: string[] = ['PrimeReact', 'Tailwind', 'core'];
+
+/**
+ * Every free PrimeReact 10 theme this package ships, as Scene {@link Theme}s.
+ *
+ * None of these themes are ours. They are PrimeTek's, shipped under the MIT license that covers the
+ * whole `primereact` package (verified in `node_modules/primereact/LICENSE.md`: "The MIT License (MIT),
+ * Copyright (c) 2016-2025 PrimeTek"). Redistributing them without saying so would be dishonest, which is
+ * what `Theme`'s `author`, `authorUrl` and `license` fields exist to prevent - and why the credit is
+ * applied here, once, to every preset, rather than written out per theme where it could be forgotten.
+ *
+ * Several themes are PrimeTek's interpretation of someone else's design language - Bootstrap, Material
+ * Design, Fluent, Tailwind UI. The compiled CSS is still PrimeTek's own work, so PrimeTek is still the
+ * author; the lineage is recorded in each theme's description instead of by misattributing the file.
+ */
+export const primeReactThemes: Theme[] = themePresets.map((preset) => ({
+    ...preset,
+    compatibleWith: primeReactThemeCompatibility,
+    author: 'PrimeTek',
+    authorUrl: 'https://primereact.org',
+    license: 'MIT',
+}));
+
+/**
+ * The names of every theme this package ships, in catalog order - what the manifest declares and what a
+ * theme picker lists.
+ */
+export const primeReactThemeNames: string[] = primeReactThemes.map((theme) => theme.name);
+
+/**
+ * Finds one of this package's themes by name.
+ *
+ * @param name The theme name, which is also its folder under `primereact/resources/themes`.
+ * @returns The theme, or `undefined` when this package does not ship one by that name.
+ */
+export function primeReactTheme(name: string): Theme | undefined {
+    return primeReactThemes.find((theme) => theme.name === name);
+}