@cratis/scene.primereact

The PrimeReact component package for Scene. It maps Scene's abstract component names onto real PrimeReact 11 components, and PrimeTek's @primeuix/themes presets onto Scene Theme objects.

User-facing documentation lives in Documentation/primereact-package/. This file is the contributor's note: the conventions the source follows and the reasoning behind them.

Layout

primereact/
├── primeReactPackage.ts        the ScenePackage manifest + the ScenePackageBundle
├── primeReactComponents.ts     the ComponentRegistry - every abstract name to its adapter
├── properties.ts               typed readers for element.properties
├── menuItems.ts, treeNodes.ts  shared readers for the two nested models the menus and trees reuse
├── MenuItem.ts, TreeNode.ts    those two models - Scene's own since v11 removed PrimeReact's
├── primeReactTheme.css         the Scene token <-> PrimeReact design-token bridge
├── storyElements.ts            fixture builders the galleries share
├── button/ data/ form/ media/ menu/ messages/ misc/ overlay/ panel/ screen/
│                               one adapter per file, grouped by PrimeReact family
├── theme/                      the theme catalog and the preset resolution behind it
└── for_*/                      BDD specs beside the code they specify

Conventions

Adapters are named Prime<Component>. The adapter for dropdown is PrimeDropdown, in form/PrimeDropdown.tsx. The prefix exists because the file also imports PrimeReact's own Dropdown, and two things called Dropdown in one file is how confusion starts. It follows the CoreButton / CoreText precedent in @cratis/scene.react.

Abstract names are lowerCamelCase — inputText, dataTable, selectButton. The abstract name follows what the component is, not what PrimeReact happens to call it this major version: toggleSwitch mapped onto v10's InputSwitch, and v11 renamed that component to ToggleSwitch - the abstract name had been right all along and did not move.

Three names are deliberately shared with core — text, button and card. That is override priority working as designed, not a collision. Seven more (table, column, title, field, section, summary, action) are the directive kinds Screenplay's screen vocabulary compiles to.

Read properties through properties.ts, never with a cast. @typescript-eslint/no-explicit-any is an error here, and a cast would let a mistyped property reach PrimeReact instead of falling back. The readers treat a wrongly typed property exactly like a missing one.

Local state where a Scene element cannot express it. A SceneElement's properties are authored design-time configuration; there is nowhere in the model to put "what the user typed" or "the user closed the dialog". Every interactive adapter therefore seeds local state from its properties. The consequence is intentional: a preview is operable rather than frozen, and the interaction stays local to the rendered component.

The token vocabulary

Thirteen semantic tokens, and every Scene package must agree on them — a vocabulary that grows per package is one no package can rely on. primeReactTheme.css is the only place the Scene names and PrimeReact's names meet.

The v10 column of this table was an ad-hoc vocabulary that could only be learned by reading compiled stylesheets; v11's is one systematic --p-* namespace derived from the preset's own token paths, so the bridge shrank.

The bridge runs both ways, and the scoping is load-bearing. On :root, each Scene token falls back to the active preset's --p-* value. Inside [data-scene-theme-root] — the element SceneThemeProvider writes tokens onto — the Scene tokens are fed back onto PrimeReact's variables. The second rule must never move to :root: custom properties that reference each other on the same element form a cycle, are invalid at computed-value time, and resolve to nothing.

Themes

24 themes across the four @primeuix/themes preset families - Aura, Lara, Nora and Material - each bound to one of the preset's own primitive color ramps for its accent.

The token values are generated, not transcribed. A v10 theme was a compiled stylesheet whose :root block could be read with a text editor; a v11 preset is a JavaScript object whose values are token references ({emerald.500}, light-dark({surface.0}, {surface.900})) that @primeuix/styled resolves at runtime. What is committed in themePresets.ts is the output of running those same resolution rules, so the catalog stays plain data a picker can read without booting a theme engine while still agreeing with what the preset renders. A spec fails the build if any token still holds an unresolved reference.

Every theme is PrimeTek's design work and none is ours - Scene picks the accent and nothing else. Attribution is applied once in primeReactThemes.ts to every preset rather than written per theme, so a twenty-fifth theme cannot be added without it. The full attribution table is in the theme reference.

compatibleWith is ['PrimeReact', 'Tailwind', 'core']. core is listed deliberately: ThemeCompatibility has no implicit exemption for it, and these themes genuinely reach core's components - through the semantic token layer SceneThemeProvider applies to the whole subtree, though not through the --p-* properties, which only PrimeReact's own components read.

Mixed-library themes

Inside SceneThemeProvider, the bridge maps the active Scene palette onto PrimeReact's semantic and component tokens together. Primary buttons, tags and progress labels use the theme's primary/contrast pair; cards and panels use its surface/text pair. Shipped PrimeReact themes retain their primary foreground when it meets normal-text WCAG AA (4.5:1); otherwise Scene selects black or white against the preset's primary fill, keeping small tag text and progress values readable too. Blueprint theme pairs are unchanged. This also exposes the legacy --primary-color, --primary-color-text, --text-color and surface aliases for older consumers without a second palette. Scene's data-scene-color-scheme marker is recognized alongside .scene-dark.

Optional peers

Chart.js peer dependency

PrimeReact 11 removed its former Chart.js wrapper, so the Scene chart adapter mounts a Chart.js canvas itself. chart.js@^4.5.1 is an optional peer dependency of @cratis/scene.primereact, optional only in that a host that never renders a chart can omit it. A host that renders charts must install chart.js, including when a bundler resolves imports statically: without it the build can fail to resolve chart.js/auto, or the chart reports that it could not be drawn.

The adapter only imports Chart.js after its canvas mounts, which keeps SSR safe. It rebuilds the chart when the type, data or options change in content, not when a document edit hands it equal data in a new object.

chart accepts canonical string types (bar, line, pie, doughnut, polarArea, radar, bubble, scatter), the numeric values 0 to 7 of the old .NET enum, and that enum's Pascal case names, without rewriting the stored element. Any other type is reported instead of drawn as a bar chart. A chart without data points shows its emptyLabel.

Quill peer dependency

quill is not imported by the package root, so a host that renders no rich text needs neither quill nor its stylesheet to build. A host that wants editable rich text installs quill@^2.0.3 and opts in explicitly:

import 'quill/dist/quill.snow.css';
import { QuillLoaderProvider } from '@cratis/scene.primereact';
import { loadQuill } from '@cratis/scene.primereact/quill';

<QuillLoaderProvider loader={loadQuill}>{screen}</QuillLoaderProvider>

@cratis/scene.primereact/quill (sources in loadQuill/) is the only module that names quill. Without a loader the editor shows its content read-only and says so. Authored HTML always passes an allowlist first; see the component reference.

Browser specifications

Most specifications run under jsdom with yarn test. Painted pixels, keyboard behavior and computed theme styles need a real browser, so yarn test:browser bundles the controls and drives headless Chromium through playwright-core. Install the browser once with yarn playwright-core install chromium. These specifications are not part of yarn test and fail, rather than skip, when Chromium is missing.

Also worth knowing: column renders nothing on its own, and since PrimeReact 11 that is our semantics rather than PrimeReact's. v11 removed primereact/column, so data/Column.tsx is a Cratis-owned declaration component that returns null. When a column element is nested under dataTable or table, the table reads its field/header/sortable off the model (element.slots) rather than the rendered node - which is why the derivation survived the v11 port unchanged.

PrimeReact 11

This package targets 11.1.0. The full record of the port from 10.9.8 - every rename, every abstract name that lost its component, and what was built, converted or dropped for each - is in the migration page.

The short version for a contributor:

• v11 is compositional. primereact/select exports Select.Root / Trigger / Value / Portal / Positioner / Popup / List / Option and you assemble them. Most renames are more than an import.
• Sidebar is the trap. v10's Sidebar is v11's Drawer, and v11 introduces a brand-new, unrelated Sidebar for application-shell navigation. Following the name rather than the behavior compiles cleanly and silently swaps an overlay for a static shell.
• v11 ships zero CSS. There is no primereact/resources directory. A look comes from a preset handed to PrimeReactProvider; usePrimeReactTheme returns that configuration for a Scene theme.
• 16 abstract names are now backed by Cratis-owned components built here because v11 removed theirs, 2 are expressed over @primereact/headless hooks, and 3 were dropped from the manifest (cascadeSelect, inputMask, virtualScroller).
• MenuItem and TreeNode are Scene's types now - primereact/menuitem and primereact/treenode were removed. Import them from this package, never from primereact/*.

Licensing

PrimeReact 10 was MIT. PrimeReact 11 is not, and neither is primeicons 8, @primereact/core, @primereact/headless, @primeuix/themes or @primeuix/styled - all are under the commercial PrimeUI license and require a license key regardless of how you style. The check runs in PrimeReactProvider on mount with no condition on unstyled, on theme, or on NODE_ENV; without a key you get a console warning and an "Invalid PrimeUI License" banner in development and production alike.

See the migration page for the community and commercial tiers and the redistribution clause.

Gates

Run from this folder:

yarn build          # tsc -b + rollup
yarn test           # vitest
yarn lint:ci        # eslint, zero warnings
yarn build-storybook