@cratis/components 3.3.4 → 3.5.0

package/README.md

@@ -25,9 +25,9 @@ there is no `require()` entry.
 ## Installation
 
 ```bash
-npm install @cratis/components primereact @primereact/core @primereact/headless primeicons
+npm install @cratis/components primereact @primereact/core @primereact/headless @primereact/hooks primeicons
 # or
-yarn add @cratis/components primereact @primereact/core @primereact/headless primeicons
+yarn add @cratis/components primereact @primereact/core @primereact/headless @primereact/hooks primeicons
 ```
 
 **PrimeReact is a peer dependency** as of 3.0.0. You install it; the library uses
@@ -39,18 +39,18 @@ Nothing errors; overlays just stack wrongly and `pt` / `unstyled` silently fail
 apply. If your app carries a `resolutions` / `overrides` pin to collapse PrimeReact
 into one copy, you can now delete it.
 
-`primereact` pins `@primereact/core` and `@primereact/headless` to its own exact
+`primereact` pins `@primereact/core`, `@primereact/headless` and `@primereact/hooks` to its own exact
 version, so one `primereact@11.x` install gives you matching copies of all three;
 declaring them is what makes a strict installer (pnpm, Yarn PnP) resolve them for the
 library too. `@primereact/types` is an **optional** peer — needed only if your own
 code imports the prop types the wrappers re-export.
 
 The other **peer dependencies** you provide are `react` / `react-dom` (**19+**), the
-`@cratis/arc*` packages (`>=20.3.1 <22` — Arc 20 and 21 both work), `reflect-metadata`
+`@cratis/arc*` packages (`>=20.3.1 <23` — Arc 20, 21 and 22 work), `reflect-metadata`
 and `tsyringe`; you typically already have these in a Cratis app. `pixi.js`,
 `framer-motion`, `allotment` and `react-icons` remain regular dependencies and are
-installed for you. The styled `@primeuix/themes` presets are optional and only needed
-if you opt into a preset (see [Styling](#styling)).
+installed for you. `@primereact/styles` and `@primeuix/themes` are **optional** peers,
+needed only for PrimeReact's styled mode (see [Styling](#styling)).
 
 ### Stylesheets
 
@@ -58,9 +58,9 @@ Component CSS is no longer imported by the JavaScript — import it once in your
 entry point, in this order:
 
 ```ts
-import '@cratis/components/tokens';   // the --cratis-* token layer
-import '@cratis/components/styles';   // every component stylesheet, in one file
-import '@cratis/components/theme';    // optional — the Cratis baseline look (MIT CSS)
+import '@cratis/components/tokens'; // the --cratis-* token layer
+import '@cratis/components/styles'; // every component stylesheet, in one file
+import '@cratis/components/theme'; // optional — the Cratis baseline look (MIT CSS)
 ```
 
 `./styles` also vendors `allotment/dist/style.css`, which `DataPage` needs for its
@@ -72,23 +72,24 @@ split view, so you do not have to import that yourself.
 was; PrimeReact 11 is part of PrimeTek's commercial **PrimeUI** family, and so are the
 packages it brings with it.
 
-| Package | v10 | v11 |
-|---|---|---|
-| `primereact` | MIT | PrimeUI commercial |
-| `primeicons` | MIT (7.x) | PrimeUI commercial (8.x) |
-| `@primereact/core`, `@primereact/headless` | — | PrimeUI commercial |
-| `@primeuix/themes`, `@primeuix/styled` | — | PrimeUI commercial |
+| Package                                                                               | v10       | v11                      |
+| ------------------------------------------------------------------------------------- | --------- | ------------------------ |
+| `primereact`                                                                          | MIT       | PrimeUI commercial       |
+| `primeicons`                                                                          | MIT (7.x) | PrimeUI commercial (8.x) |
+| `@primereact/core`, `@primereact/headless`, `@primereact/hooks`, `@primereact/styles` | —         | PrimeUI commercial       |
+| `@primeuix/themes`, `@primeuix/styled`                                                | —         | PrimeUI commercial       |
 
 `@cratis/components` itself remains **MIT**. The change is in what it depends on, and it is
 yours to satisfy: PrimeReact is a peer dependency, so you install it and its license terms
-apply to you directly.
+apply to you directly. `@primereact/styles` and `@primeuix/themes` — the two styled mode
+adds — are PrimeUI-licensed too.
 
 ### A key is required regardless of how you style
 
 PrimeReact 11 verifies a license key when `PrimeReactProvider` mounts. The check is not
 conditional on `unstyled`, on whether a theme preset is applied, or on `NODE_ENV` — so
 every styling setup in [Styling](#styling) reaches it. Without a valid key you get a
-console warning and a fixed *"Invalid PrimeUI License"* banner, in development **and**
+console warning and a fixed _"Invalid PrimeUI License"_ banner, in development **and**
 production.
 
 Supply your key through the provider:
@@ -105,7 +106,7 @@ PrimeReact 11, which needs a key.
 
 - **[Community License](https://primeui.dev/licenses/community)** — free. Covers
   individuals, students, non-profits and non-commercial open source outright. For an
-  organization it requires *all* of: under $1M USD annual gross revenue, fewer than 5
+  organization it requires _all_ of: under $1M USD annual gross revenue, fewer than 5
   developers, fewer than 10 employees, and under $3M USD in outside funding. Supports up to
   4 developers and is renewed annually by confirming continued eligibility.
 - **[Commercial License](https://primeui.dev/licenses/commercial)** — for everyone else.
@@ -113,9 +114,9 @@ PrimeReact 11, which needs a key.
 
 ### If you redistribute
 
-PrimeReact 11's terms state: *"You may not … redistribute it as a component library or
+PrimeReact 11's terms state: _"You may not … redistribute it as a component library or
 development tool … Redistributing the software so that third parties can develop with it
-requires a separate OEM License."*
+requires a separate OEM License."_
 
 If you are building an application, that clause is not aimed at you. If you are publishing
 a library or tool that others build with, read it and check your position with PrimeTek.
@@ -161,20 +162,22 @@ Components:
 - `@cratis/components/Dialogs`
 - `@cratis/components/Display` — `Tag`, `Badge`, `Chip`, `Skeleton`, `Avatar`, `ProgressBar`
 - `@cratis/components/Dropdown`
-- `@cratis/components/Notifications` — `Toaster`, `toast`, `toastCommandResult`
+- `@cratis/components/Notifications` — `Toaster`, Cratis-owned `toast` / `ToastDispatch`, `toastCommandResult`
 - `@cratis/components/ObjectContentEditor`
 - `@cratis/components/ObjectNavigationalBar`
 - `@cratis/components/PivotViewer`
 - `@cratis/components/SchemaEditor`
 - `@cratis/components/TimeMachine`
 - `@cratis/components/Toolbar`
+- `@cratis/components/styled` — `styledMode`, `CratisPreset`, `primeReactStyles`, `primeReactCssLayer`, `primeReactCssLayerOrder`, `cratisDarkModeSelector`: PrimeReact's styled mode, wired for the provider (needs `@primereact/styles` + `@primeuix/themes`)
 - `@cratis/components/types`
 
 Stylesheets:
 
-- `@cratis/components/theme` — the **Cratis baseline theme** (light + dark, Cratis-authored MIT CSS, no `@primeuix/themes` dependency); import it and add `class="cratis-theme"` to skin every component from the token layer
+- `@cratis/components/theme` — the **Cratis baseline theme** (light + dark, Cratis-authored MIT CSS, no `@primereact/styles` / `@primeuix/themes` dependency); import it and add `class="cratis-theme"` to skin every component from the token layer
 - `@cratis/components/styles` — **required**: every component stylesheet, the Tailwind utilities used inside the package, and the `allotment` rules `DataPage` needs, in one file
 - `@cratis/components/tokens` — **required**: the `--cratis-*` CSS variable tokens every component reads from
+- `@cratis/components/primereact-v10-palette` — the PrimeReact 10 theme variables (`--surface-*`, `--text-color`, `--primary-color`, the color scales, …) restored with the lara-blue values, for CSS already written against them
 
 ## Styling
 
@@ -184,9 +187,9 @@ much control you want, and the other layers stay invisible.
 
 > **Tip — see each setup live:** every Storybook story includes a **Styling**
 > toolbar (paintbrush icon) that flips between the modes demonstrating the
-> setups below: *Aura Dark* and *Aura Light* (an `@primeuix/themes`
-> preset), *Cratis baseline theme* (light and dark), *Unstyled
-> (bare structure)*, and *Unstyled + Tailwind pt*. Open any story (`yarn dev`)
+> setups below: _Aura Dark_ and _Aura Light_ (an `@primeuix/themes`
+> preset), _Cratis baseline theme_ (light and dark), _Unstyled
+> (bare structure)_, and _Unstyled + Tailwind pt_. Open any story (`yarn dev`)
 > and switch modes to see the same component under each setup.
 
 ### TL;DR — choose a styling setup
@@ -195,27 +198,34 @@ much control you want, and the other layers stay invisible.
 > The styling choice changes how it looks and whether you additionally pull in
 > `@primeuix/themes`; it does not change whether you need a key.
 
-| Setup | When | Effort | Extra dependency | What you write |
-|---|---|---|---|---|
-| **Cratis baseline theme** | You want a polished default look without adding a theme package. | Lowest | None | `unstyled` + `import '@cratis/components/theme'` + `class="cratis-theme"` |
-| **A styled `@primeuix/themes` preset** | You want a prebuilt design system to tweak from. | Low | `@primeuix/themes` | `value={{ theme: { preset } }}` on the provider |
-| **A custom palette over a preset** | You want the preset's structure but your own colors. | Low | `@primeuix/themes` | A preset + CSS variable overrides |
-| **Fully unstyled** | You're integrating into a tightly controlled design system. | Highest | None | `unstyled: true` + a `pt` preset in CSS or Tailwind |
+| Setup                             | When                                                                                                 | Effort  | Extra dependency                          | What you write                                                                                           |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Cratis baseline theme**         | You want a polished default look without adding a theme package.                                     | Lowest  | None                                      | `unstyled` + `import '@cratis/components/theme'` + `class="cratis-theme"`                                |
+| **PrimeReact's styled mode**      | You want PrimeReact's own look — a `@primeuix/themes` preset painting PrimeReact's component styles. | Low     | `@primereact/styles` + `@primeuix/themes` | `value={{ license, ...styledMode() }}` with `styledMode` from `@cratis/components/styled`                |
+| **A custom palette over a theme** | You want the theme's structure but your own colors.                                                  | Low     | As above, or none                         | `--cratis-*` overrides on the baseline theme, or `styledMode({ preset: definePreset(CratisPreset, …) })` |
+| **Fully unstyled**                | You're integrating into a tightly controlled design system.                                          | Highest | None                                      | `unstyled: true` + a `pt` preset in CSS or Tailwind                                                      |
 
 > **Why you need a theme, a baseline stylesheet, or a `pt` preset**
 >
-> PrimeReact 11 is **unstyled-first**: the primitives render structural markup
-> with no built-in visuals. A look comes from one of three sources — a
-> `@primeuix/themes` preset (token-based), the Cratis baseline
-> theme (`@cratis/components/theme`), or your own `pt`/CSS. Load
-> none of them and the components render as their raw HTML primitives.
+> PrimeReact 11 is **unstyled-first**: the `primereact` package is primitives
+> that render structural markup with `data-scope` / `data-part` attributes,
+> no built-in visuals and **no `p-*` class names**. The class names and the
+> CSS behind them live in `@primereact/styles`; PrimeReact's own styled
+> components (`@primereact/ui`) are just the primitives with those styles
+> preset, and this library builds on the primitives. So a look comes from one
+> of three sources — PrimeReact's styled mode (`styledMode()`: a
+> `@primeuix/themes` preset **plus** PrimeReact's component styles), the
+> Cratis baseline theme (`@cratis/components/theme`), or your own `pt`/CSS.
+> Load none of them and the components render as their raw HTML primitives.
+> **A preset alone is not one of the three** — `theme: { preset }` by itself
+> emits `--p-*` tokens but styles nothing rendered here.
 >
 > The `--cratis-*` token layer is an **additive Cratis-scoped tint** for
-> surfaces *our* wrappers own (validation error text, the FormElement addon,
+> surfaces _our_ wrappers own (validation error text, the FormElement addon,
 > breadcrumb borders, etc.). It is not, by itself, enough to skin the
-> PrimeReact widgets — pair it with the baseline theme, a preset, or a `pt`
-> preset. Override the PrimeReact variables (or a preset's `--p-*` tokens) when
-> you want the whole UI in your palette.
+> PrimeReact widgets — pair it with the baseline theme, styled mode, or a `pt`
+> preset. Derive the preset (styled mode) or override the `--cratis-*` tokens
+> (baseline theme) when you want the whole UI in your palette.
 
 All setups share the same one-line provider setup. You can change direction
 later because the same provider, tokens, and `pt` hooks stay available.
@@ -245,7 +255,7 @@ export const App = () => (
   required, not optional.
 - `CratisComponentsProvider` is a thin wrapper over `@primereact/core`'s
   `PrimeReactProvider` so Cratis has one place to layer in defaults (including
-  the optional `value={{ theme: { preset } }}` styled layer). Drop in the raw
+  the optional `...styledMode()` styled layer). Drop in the raw
   `PrimeReactProvider` from `@primereact/core` if you'd rather.
 
 The setups below differ only in **what else** you load on top of this
@@ -253,66 +263,67 @@ provider setup.
 
 ---
 
-### Use a styled preset
+### Use PrimeReact's styled mode
 
 PrimeReact 11 dropped the v10 `primereact/resources/themes/*/theme.css`
-stylesheets in favor of the token-based `@primeuix/themes` layer. Apply a
-preset by passing `value={{ theme: { preset } }}` to `CratisComponentsProvider` —
-no theme CSS import. PrimeReact's own widgets paint themselves from the preset, and the
-`--cratis-*` tokens cascade to the matching variables so Cratis-scoped surfaces
-follow along.
+stylesheets. A theme is now handed to the provider at runtime, in two halves: a
+`@primeuix/themes` **preset** (a token object `@primeuix/styled` turns into
+`--p-*` custom properties) and PrimeReact's **component styles**
+(`@primereact/styles` — the `p-*` class names and the CSS the tokens drive).
+`styledMode()` from `@cratis/components/styled` returns both as
+`{ theme, defaults }`; spread it into the provider `value` next to your
+license key. The `defaults` are `primeReactStyles`, PrimeReact's component
+styles keyed by primitive name, which the provider applies to **every**
+primitive rendered under it — the ones this library renders and the ones your
+app renders itself. That is what puts the `p-*` class names on the elements and
+lets the preset paint them; the `--cratis-*` tokens follow the preset's `--p-*`
+so Cratis-scoped surfaces stay in sync.
+
+```bash
+npm install @primereact/styles @primeuix/themes   # optional peers, styled mode only
+```
 
 ```tsx
-import Aura from '@primeuix/themes/aura';   // or lara / nora / material
 import 'primeicons/primeicons.css';
+import '@cratis/components/tokens';
 import '@cratis/components/styles';
-
 import { CratisComponentsProvider } from '@cratis/components';
+import { styledMode } from '@cratis/components/styled';
 
 export const App = () => (
-    <CratisComponentsProvider value={{ theme: { preset: Aura } }}>
+    <CratisComponentsProvider value={{ license: 'YOUR-PRIMEUI-KEY', ...styledMode() }}>
         <YourApp />
     </CratisComponentsProvider>
 );
 ```
 
-Omit `theme` entirely to stay unstyled-first — ship only structure plus the
-`--cratis-*` tokens and bring your own visuals (see the pass-through / `pt`
-options below).
-
-### Use the Cratis baseline theme
-
-Want a polished default look **without adding `@primeuix/themes`**? Ship the
-components unstyled and import the Cratis baseline theme — Cratis-authored MIT
-CSS that styles every component from the `--cratis-*` layer. (You still need a
-PrimeUI key to run PrimeReact itself — see [Licensing](#licensing).)
-
-```tsx
-import 'primeicons/primeicons.css';
-import '@cratis/components/theme';   // the baseline theme
-
-export const App = () => (
-    <CratisComponentsProvider value={{ unstyled: true }}>
-        <div className="cratis-theme">   {/* scope: put on <body>, app root, or a subtree */}
-            <YourApp />
-        </div>
-    </CratisComponentsProvider>
-);
-```
-
-Add `cratis-dark` to an ancestor for the dark palette. The theme defers to a
-`@primeuix/themes` preset's `--p-*` tokens when one is present, so you can layer
-it under a preset too, and every rule is overridable via your own CSS or `pt`.
+The default preset is `CratisPreset` — Lara with the blue primary and gray
+surfaces of PrimeReact 10's `lara-light-blue` / `lara-dark-blue`, with the dark
+surface scale one step lighter so content sits above the page as it did there,
+both color schemes.
+Options: `preset` (any `@primeuix/themes` preset — Aura, Lara, Nora, Material —
+or a `definePreset` result), `darkModeSelector` (default `.cratis-dark`, the
+class the baseline theme uses too; `'system'` follows `prefers-color-scheme`),
+`cssLayer` (default the `primereact` layer ordered between Tailwind's `base`
+and `components`; `false` emits the theme unlayered).
+
+> **A preset alone styles nothing.** `value={{ theme: { preset } }}` without the
+> `defaults` emits the `--p-*` tokens, but the primitives keep rendering with no
+> `p-*` class, so nothing rendered by this library is painted. Use
+> `styledMode()`.
 
 #### Override a single component with CSS
 
-Plain CSS works fine on top of the theme. Target either PrimeReact's class
-names or your own `className`:
+Plain CSS works fine on top of the theme. In styled mode PrimeReact's elements
+carry their `p-*` class names, and the theme is emitted into the `primereact`
+cascade layer, so a plain unlayered rule in your own stylesheet wins — exactly
+as it did against PrimeReact 10's `@layer primereact` stylesheets. Or target
+your own `className`:
 
 ```css
 /* yourApp.css */
 .p-button {
-    border-radius: 999px;            /* pill buttons everywhere */
+    border-radius: 999px; /* pill buttons everywhere */
 }
 
 .dangerous-button {
@@ -322,7 +333,7 @@ names or your own `className`:
 ```
 
 ```tsx
-<Button label="Delete" className="dangerous-button" />
+<Button className='dangerous-button'>Delete</Button>
 ```
 
 #### Override a single component with Tailwind
@@ -338,78 +349,136 @@ Pass Tailwind utility classes through the wrapper's `className` prop:
 </Dialog>
 ```
 
-**Use this setup when:** you're prototyping, building internal tools, or are
-happy with one of the prebuilt PrimeReact themes.
+**Use this setup when:** you're prototyping, building internal tools, want the
+look Cratis apps had on PrimeReact 10, or are happy with one of the prebuilt
+PrimeReact design systems.
+
+### Use the Cratis baseline theme
+
+Want a polished default look **without adding `@primereact/styles` and
+`@primeuix/themes`**? Ship the components unstyled and import the Cratis baseline
+theme — Cratis-authored MIT CSS that styles every component from the `--cratis-*`
+layer. (You still need a PrimeUI key to run PrimeReact itself — see
+[Licensing](#licensing).)
+
+```tsx
+import 'primeicons/primeicons.css';
+import '@cratis/components/theme'; // the baseline theme
+
+export const App = () => (
+    <CratisComponentsProvider value={{ unstyled: true }}>
+        <div className='cratis-theme'>
+            {' '}
+            {/* scope: put on <body>, app root, or a subtree */}
+            <YourApp />
+        </div>
+    </CratisComponentsProvider>
+);
+```
+
+Add `cratis-dark` to an ancestor for the dark palette. The theme defers to a
+`@primeuix/themes` preset's `--p-*` tokens when one is present, so you can layer
+it under styled mode too, and every rule is overridable via your own CSS or `pt`.
+The baseline theme styles the unstyled primitives through their `[data-scope]`
+attributes — there are no `p-*` class names outside styled mode — so target
+those, or your own `className`, or the `--cratis-*` tokens:
+
+```css
+.cratis-theme [data-scope='button'] {
+    border-radius: 999px;
+} /* pill buttons */
+.dangerous {
+    background: var(--cratis-red-500);
+    color: white;
+}
+```
 
 ---
 
 ### Use a custom palette on top of a PrimeReact theme
 
-Keep a PrimeReact theme as your **structural baseline** (so every widget gets
-its padding, dialog frame, button shape, focus ring, etc.) and override the
-PrimeReact CSS variables on `:root` to repaint the whole UI in your own
-colors. The `--cratis-*` tokens follow along through tokens.css's cascade, so
-Cratis-scoped surfaces stay in sync — and you can override the Cratis tokens
-independently if you want Cratis surfaces to differ from PrimeReact widgets.
+Keep a theme as your **structural baseline** (so every widget gets its
+padding, dialog frame, button shape, focus ring, etc.) and repaint it with your
+own colors. Which knob you turn depends on the theme:
 
-#### With plain CSS
+- **Cratis baseline theme** — override the `--cratis-*` tokens in CSS; the
+  theme paints the widgets from them, so one override repaints widgets and
+  Cratis-scoped surfaces alike.
+- **PrimeReact's styled mode** — derive your own preset with `definePreset` and
+  hand it to `styledMode({ preset })`; the widgets read the preset's `--p-*`
+  tokens, and the `--cratis-*` tokens follow.
+
+#### Baseline theme, plain CSS
 
 ```css
-/* palette.override.css — imported once, after @cratis/components/styles */
-:root {
-    /* PrimeReact variables — these are what PrimeReact widgets read. */
-    --surface-0:        #1e293b;
-    --surface-100:      #1e293b;
-    --surface-ground:   #020617;
-    --surface-section:  #0f172a;
-    --surface-card:     #1e293b;
-    --surface-overlay:  #1e293b;
-    --surface-hover:    #334155;
-    --surface-border:   #334155;
-
-    --text-color:           #f8fafc;
-    --text-color-secondary: #94a3b8;
-
-    --primary-color:      #38bdf8;
-    --primary-color-text: #0b1220;
-
-    --highlight-bg:         #1e40af;
-    --highlight-text-color: #ffffff;
-
-    --border-radius: 10px;
-
-    /* --cratis-* tokens default to var(--surface-*) etc. via tokens.css, so
-       the overrides above flow through automatically. Set these explicitly
-       only if you want Cratis-scoped surfaces tinted differently. */
-    --cratis-red-500:   #ef4444;
-    --cratis-green-500: #22c55e;
+/* palette.override.css — imported once, after @cratis/components/theme */
+.cratis-theme {
+    --cratis-surface-section: #0f172a;
+    --cratis-surface-card: #1e293b;
+    --cratis-surface-overlay: #1e293b;
+    --cratis-surface-hover: #334155;
+    --cratis-surface-border: #334155;
+
+    --cratis-text-color: #f8fafc;
+    --cratis-text-color-secondary: #94a3b8;
+
+    --cratis-primary-color: #38bdf8;
+    --cratis-primary-color-text: #0b1220;
+
+    --cratis-highlight-bg: #1e40af;
+    --cratis-highlight-text-color: #ffffff;
+
+    --cratis-border-radius: 10px;
 }
 ```
 
+#### Styled mode, `definePreset`
+
+```ts
+// brand-preset.ts
+import { definePreset } from '@primeuix/themes';
+import { CratisPreset } from '@cratis/components/styled';
+
+export const BrandPreset = definePreset(CratisPreset, {
+    semantic: {
+        primary: {
+            50: '{sky.50}',
+            100: '{sky.100}',
+            200: '{sky.200}',
+            300: '{sky.300}',
+            400: '{sky.400}',
+            500: '{sky.500}',
+            600: '{sky.600}',
+            700: '{sky.700}',
+            800: '{sky.800}',
+            900: '{sky.900}',
+            950: '{sky.950}',
+        },
+    },
+});
+```
+
 ```tsx
-// 1. A styled preset provides the structure (apply it via the provider — see above).
-import 'primeicons/primeicons.css';
-import '@cratis/components/styles';
-// 2. Your palette overrides — must come after the styles so they win.
-import './palette.override.css';
+<CratisComponentsProvider value={{ license, ...styledMode({ preset: BrandPreset }) }}>
 ```
 
 #### Scoped (dark-on-light, light-on-dark, etc.)
 
-PrimeReact variables cascade like any other CSS variable, so an ancestor
-scope works:
+`--cratis-*` tokens cascade like any other CSS variable, so an ancestor scope
+works under the baseline theme (in styled mode, region-scoped widget colors come
+from the preset; the `--cratis-*` overrides still retint Cratis-scoped surfaces):
 
 ```css
 .dark-zone {
-    --surface-card: #0b1220;
-    --text-color:   #f8fafc;
-    --primary-color: #60a5fa;
+    --cratis-surface-card: #0b1220;
+    --cratis-text-color: #f8fafc;
+    --cratis-primary-color: #60a5fa;
 }
 ```
 
 ```tsx
-<div className="dark-zone">
-    <Dialog title="Always dark">…</Dialog>
+<div className='dark-zone'>
+    <Dialog title='Always dark'>…</Dialog>
 </div>
 ```
 
@@ -420,53 +489,71 @@ Tailwind handles cascade and dark mode:
 
 ```css
 /* app.css */
-@import "tailwindcss";
-@import "@cratis/components/styles";
+@import 'tailwindcss';
+@import '@cratis/components/tokens';
+@import '@cratis/components/styles';
 
 @layer base {
     :root {
-        --surface-card:   theme('colors.slate.800');
-        --surface-border: theme('colors.slate.700');
-        --text-color:     theme('colors.slate.50');
-        --primary-color:  theme('colors.sky.400');
+        --cratis-surface-card: theme('colors.slate.800');
+        --cratis-surface-border: theme('colors.slate.700');
+        --cratis-text-color: theme('colors.slate.50');
+        --cratis-primary-color: theme('colors.sky.400');
         --cratis-red-500: theme('colors.red.500');
     }
 
-    .dark {
-        --surface-card: theme('colors.slate.900');
-        --text-color:   theme('colors.slate.100');
+    .cratis-dark {
+        --cratis-surface-card: theme('colors.slate.900');
+        --cratis-text-color: theme('colors.slate.100');
     }
 }
 ```
 
+#### CSS written against PrimeReact 10's variables
+
+If your stylesheets still use the names a v10 theme published on `:root` —
+`--surface-ground`, `--surface-card`, `--surface-border`, `--text-color`,
+`--primary-color`, the `--surface-0…900` and color scales — import
+`@cratis/components/primereact-v10-palette` after `tokens` and `styles`. It
+restores every one of them with the `lara-light-blue` / `lara-dark-blue`
+values: the semantic names follow the active preset's `--p-*` tokens where
+v11 has an equivalent (Lara as the fallback), the numbered scales are the
+lara-blue values verbatim (the v10 dark surface scale was inverted, so
+`--p-surface-*` cannot stand in for it), and light/dark switch through
+`light-dark()` keyed off `.cratis-dark`. It exists so what is already written
+keeps working — write nothing new against those names; use `--cratis-*` (or
+`--p-*`).
+
 #### What `--cratis-*` tokens are for
 
-PrimeReact widgets read PrimeReact's own variables (`--surface-card`,
-`--text-color`, `--primary-color`, …) directly. Cratis wrappers add some
-surfaces of their own (inline validation error text, the FormElement addon
-background, the breadcrumb bottom border, etc.) — those use a parallel set
-of `--cratis-*` tokens that default to the PrimeReact value via the cascade
-defined in `tokens.css`.
+In styled mode PrimeReact widgets read the preset's `--p-*` design tokens
+directly. Cratis wrappers add some surfaces of their own (inline validation
+error text, the FormElement addon background, the breadcrumb bottom border,
+etc.) — those use a parallel set of `--cratis-*` tokens that resolve the v11
+token first and fall back to the v10 variable, via the cascade defined in
+`tokens.css`. Under the baseline theme the widgets read the `--cratis-*` tokens
+too.
 
 The upshot:
 
-- Override **PrimeReact variables** to repaint the whole UI (PrimeReact widgets + Cratis surfaces).
-- Override **`--cratis-*` tokens** when you specifically want Cratis surfaces to differ from PrimeReact widgets.
+- Repaint the whole UI by deriving the **preset** (styled mode) or overriding the **`--cratis-*` tokens** (baseline theme).
+- Override **`--cratis-*` tokens** in styled mode when you specifically want Cratis surfaces to differ from PrimeReact widgets.
 
 #### `--cratis-*` token reference (Cratis-scoped surfaces)
 
-| Group | Tokens |
-|---|---|
-| Surfaces | `--cratis-surface-0`, `--cratis-surface-100`, `--cratis-surface-ground`, `--cratis-surface-section`, `--cratis-surface-card`, `--cratis-surface-overlay`, `--cratis-surface-hover`, `--cratis-surface-border` |
-| Text | `--cratis-text-color`, `--cratis-text-color-secondary` |
-| Brand | `--cratis-primary-color`, `--cratis-primary-color-text`, `--cratis-primary-300`, `--cratis-primary-400`, `--cratis-primary-500`, `--cratis-primary-600` |
-| Selection | `--cratis-highlight-bg`, `--cratis-highlight-text-color` |
-| Semantic | `--cratis-green-500`, `--cratis-orange-500`, `--cratis-red-500` |
-| Geometry | `--cratis-border-radius` |
-| Effects | `--cratis-focus-ring`, `--cratis-maskbg` |
+| Group     | Tokens                                                                                                                                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Surfaces  | `--cratis-surface-0`, `--cratis-surface-100`, `--cratis-surface-ground`, `--cratis-surface-section`, `--cratis-surface-card`, `--cratis-surface-overlay`, `--cratis-surface-hover`, `--cratis-surface-border` |
+| Text      | `--cratis-text-color`, `--cratis-text-color-secondary`                                                                                                                                                        |
+| Brand     | `--cratis-primary-color`, `--cratis-primary-color-text`, `--cratis-primary-300`, `--cratis-primary-400`, `--cratis-primary-500`, `--cratis-primary-600`                                                       |
+| Selection | `--cratis-highlight-bg`, `--cratis-highlight-text-color`                                                                                                                                                      |
+| Semantic  | `--cratis-green-500`, `--cratis-orange-500`, `--cratis-red-500`                                                                                                                                               |
+| Geometry  | `--cratis-border-radius`                                                                                                                                                                                      |
+| Effects   | `--cratis-focus-ring`, `--cratis-maskbg`                                                                                                                                                                      |
 
-Each defaults to the PrimeReact variable with the same name minus the
-`--cratis-` prefix (e.g. `--cratis-surface-card` → `var(--surface-card)`).
+Each resolves the v11 design token first and falls back to the v10 variable
+with the same name minus the `--cratis-` prefix (e.g. `--cratis-surface-card`
+→ `var(--p-content-background, var(--surface-card))`).
 
 **Use this setup when:** you want a custom look without writing a PrimeReact
 theme from scratch, you're shipping multiple palette variants (light/dark/
@@ -482,7 +569,7 @@ through PrimeReact's `pt` (pass-through) mechanism, your own CSS, or both.
 Components render structurally only and become a blank canvas.
 
 ```tsx
-import '@cratis/components/styles';   // component rules + Tailwind utilities, still needed when unstyled
+import '@cratis/components/styles'; // component rules + Tailwind utilities, still needed when unstyled
 import { CratisComponentsProvider } from '@cratis/components';
 
 export const App = () => (
@@ -492,6 +579,12 @@ export const App = () => (
 );
 ```
 
+#### Verify pass-through compatibility
+
+Components 3 publishes its PrimeReact 11 slot and rendered-marker contract from `@cratis/components/compatibility`. In a DOM test, apply `primeReact11PassThroughSentinelPreset`, render the surfaces your application uses, and call `assertPrimeReact11PassThroughCompatibility(root, components)`. Additions pass; a missing or renamed contracted slot or marker produces an actionable error. The contract is major-version scoped and does not preserve PrimeReact 10 names.
+
+The machine-readable `components3PrimeReact11PassThroughContract` is the source of truth. Contract revision 1 covers the parts rendered by Components 3's supported compositions on PrimeReact 11, rather than every optional part an application could compose directly. See the [pass-through contract documentation](https://cratis.io/Components/styling/pass-through.html) for the supported component and slot list.
+
 #### A `pt` preset in plain CSS
 
 Attach a `className` from your own stylesheet via a global preset:
@@ -503,9 +596,11 @@ export const globalPt = {
         root: { className: 'my-btn' },
     },
     dialog: {
-        root: { className: 'my-dialog' },
-        header: { className: 'my-dialog__header' },
-        content: { className: 'my-dialog__body' },
+        root: {
+            popup: { className: 'my-dialog' },
+            header: { className: 'my-dialog__header' },
+            content: { className: 'my-dialog__body' },
+        },
     },
     inputtext: {
         root: { className: 'my-input' },
@@ -542,15 +637,26 @@ Same shape, Tailwind utilities as the class strings:
 // pt-preset.ts
 export const globalPt = {
     button: {
-        root: { className: 'inline-flex items-center px-4 py-2 rounded-lg bg-sky-700 text-white hover:bg-sky-600 disabled:opacity-50' },
+        root: {
+            className:
+                'inline-flex items-center px-4 py-2 rounded-lg bg-sky-700 text-white hover:bg-sky-600 disabled:opacity-50',
+        },
     },
     dialog: {
-        root:    { className: 'rounded-2xl shadow-2xl overflow-hidden' },
-        header:  { className: 'px-5 py-3 bg-slate-800 text-slate-50 font-semibold border-b border-slate-700' },
-        content: { className: 'p-5 bg-slate-900 text-slate-100' },
+        root: {
+            popup: { className: 'rounded-2xl shadow-2xl overflow-hidden' },
+            header: {
+                className:
+                    'px-5 py-3 bg-slate-800 text-slate-50 font-semibold border-b border-slate-700',
+            },
+            content: { className: 'p-5 bg-slate-900 text-slate-100' },
+        },
     },
     inputtext: {
-        root: { className: 'w-full px-3 py-2 rounded-md bg-slate-800 text-slate-50 border border-slate-700 focus:border-sky-400 focus:outline-none' },
+        root: {
+            className:
+                'w-full px-3 py-2 rounded-md bg-slate-800 text-slate-50 border border-slate-700 focus:border-sky-400 focus:outline-none',
+        },
     },
 } as const;
 ```
@@ -611,23 +717,31 @@ The styling options compose, so you don't have to choose one for the whole app:
 
 - **Themed with one unstyled component** — keep the PrimeReact theme and pass
   `unstyled` per-component to opt that one widget out:
-  ```tsx
-  <Dialog title="Custom" unstyled pt={brandDialogPt}>…</Dialog>
-  ```
-- **Unstyled with one themed island** — wrap a subtree in a second
-  `CratisComponentsProvider` that restores defaults:
-  ```tsx
-  <CratisComponentsProvider value={{ unstyled: true, pt: globalPt }}>
-      <App />
-      <CratisComponentsProvider value={{ unstyled: false }}>
-          <PrimeReactThemedSubtree />
-      </CratisComponentsProvider>
-  </CratisComponentsProvider>
-  ```
-- **Dark mode** — scope the palette overrides to `.dark` (override
-  `--surface-card`, `--text-color`, `--primary-color`, etc., plus any
-  `--cratis-*` tokens you want to diverge) and toggle the class on the root
-  element. PrimeReact widgets and Cratis surfaces both follow the cascade.
+
+    ```tsx
+    <Dialog title='Custom' unstyled pt={brandDialogPt}>
+        …
+    </Dialog>
+    ```
+
+- **Unstyled with one themed island** — the baseline theme's rules are scoped
+  under `.cratis-theme`, so wrapping one element in the class themes just that
+  subtree:
+
+    ```tsx
+    <CratisComponentsProvider value={{ unstyled: true, pt: globalPt }}>
+        <App />
+        <div className='cratis-theme'>
+            <BaselineThemedSubtree />
+        </div>
+    </CratisComponentsProvider>
+    ```
+
+- **Dark mode** — toggle `cratis-dark` on the root element: the baseline
+  theme's dark palette, `styledMode()`'s dark scheme (its default
+  `darkModeSelector`) and the v10 palette all key off it, so PrimeReact widgets
+  and Cratis surfaces follow together. Scope any `--cratis-*` tokens you want
+  to diverge to `.cratis-dark` as well.
 
 ### Per-component `pt` cheat sheet
 
@@ -638,21 +752,32 @@ Three patterns, depending on how much PrimeReact a wrapper composes:
    `className` straight to their inner PrimeReact component.
 2. **Multi-slot composites** — `StepperCommandDialog` (`pt` for Stepper,
    `dialogPt` for Dialog), `DataPage` (`tablePt` for DataTable, `menubarPt`
-   for Menubar), and `DataTableForQuery` / `DataTableForObservableQuery`
-   (`pt` for DataTable, `paginatorPt` for Paginator) — each slot has
-   `*PtOptions`, `*Unstyled`, and (where applicable) `*ClassName` siblings.
+   for the action toolbar's buttons), and `DataTableForQuery` /
+   `DataTableForObservableQuery` (`pt` for DataTable plus
+   `paginatorClassName` / `paginatorAriaLabels` for the Cratis paginator).
 3. **Large composites** — `ObjectContentEditor`, `ObjectNavigationalBar`,
    `SchemaEditor` expose `className` only; restyle internals via the global
    `pt` preset.
 
-### What is *not* fully pass-through
+`Dropdown` routes `id`, `tabIndex`, `aria-label`, `aria-labelledby` and `aria-describedby` to its focusable `role="combobox"` trigger. The outer Select root remains a layout wrapper and does not duplicate the control id. For filterable dropdowns, `filterPlaceholder` can differ from the closed trigger's `placeholder` and defaults to it when omitted.
 
-A small number of internal usages opt into PrimeReact's slot-rendering by
-name (for example, a custom Menubar item template uses `p-menuitem-link` /
-`p-menuitem-text` to match the surrounding default-rendered items). These are
-correct contracts with PrimeReact's own slot rendering, not hard-coded
-theming — they have no effect in `unstyled` mode and match the rest of the
-menu in themed mode.
+Filtered data-table columns accept partial `filterLabels` overrides for trigger, action and boolean-option text, plus a `filterElement` render callback that replaces the built-in value editor while keeping draft/apply behavior. `DataTableFilterMatchMode` supplies the Cratis-owned built-in vocabulary, and `registerDataTableFilterMatcher()` adds custom modes without importing the active rendering adapter.
+
+`DatePickerInput` exposes `id`, `disabled`, `readOnly` and `showButtonBar` directly. Use its runtime `input` slot only for additional attributes; the public type intentionally rejects PrimeReact 11's stale `pcInputText` declaration, which the runtime never emits. The wrapper translates `invalid` to accepted `aria-invalid` and `data-invalid` input attributes instead of forwarding a rejected `invalid` DOM attribute:
+
+```tsx
+<DatePickerInput
+    id='appointment-date'
+    value={selectedDate}
+    onChange={setSelectedDate}
+    disabled={isDisabled}
+    readOnly={isReadOnly}
+    showButtonBar
+    pt={{ input: { 'aria-label': 'Appointment date' } }}
+/>
+```
+
+### What is _not_ fully pass-through
 
 `BusyIndicatorDialog` only honors the global `pt` set via
 `CratisComponentsProvider`; it does not accept per-instance `pt` because its
@@ -674,9 +799,9 @@ If using TypeScript 4.7+, try updating your `tsconfig.json`:
 
 ```json
 {
-  "compilerOptions": {
-    "moduleResolution": "bundler"  // or "node16" / "nodenext"
-  }
+    "compilerOptions": {
+        "moduleResolution": "bundler" // or "node16" / "nodenext"
+    }
 }
 ```