From 789c3b0e8c331d9d07b1baf4e1cf06d6af1cd641 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:20:07 +0200
Subject: [PATCH 01/23] Add --cratis-* CSS variable token layer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce a Cratis-scoped token layer that every internal component reads
from instead of PrimeReact theme variables directly. Each --cratis-* token
defaults to the matching PrimeReact variable so a consumer's PrimeReact theme
just works, while still allowing consumers to take full control by overriding
the tokens on :root or any scope — with or without a PrimeReact theme.

Tokens cover surfaces, text, primary brand, highlight, semantic accents
(green/orange/red), border radius, focus ring, and overlay mask. The token
file is auto-bundled into the compiled @cratis/components/styles stylesheet
via the existing Tailwind build pipeline.
---
 Source/tailwind.css |  9 ++++---
 Source/tokens.css   | 65 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 3 deletions(-)
 create mode 100644 Source/tokens.css

diff --git a/Source/tailwind.css b/Source/tailwind.css
index c31c9eb..ae4d996 100644
--- a/Source/tailwind.css
+++ b/Source/tailwind.css
@@ -2,12 +2,15 @@
 /* Licensed under the MIT license. See LICENSE file in the project root for full license information. */
 
 /*
- * Tailwind utility classes compiled at build time.
- * This stylesheet is generated during the package build and contains only
- * the utility classes that are actually used across all components.
+ * Tailwind utility classes + Cratis CSS variable tokens compiled at build time.
+ * This stylesheet is generated during the package build and contains only the
+ * utility classes that are actually used across all components, plus the
+ * --cratis-* token layer that every internal component depends on for theming.
+ *
  * It intentionally excludes preflight/base resets — those are the consumer app's responsibility.
  *
  * Usage in your app:
  *   import '@cratis/components/styles';
  */
 @import "tailwindcss";
+@import "./tokens.css";
diff --git a/Source/tokens.css b/Source/tokens.css
new file mode 100644
index 0000000..1e2f145
--- /dev/null
+++ b/Source/tokens.css
@@ -0,0 +1,65 @@
+/* Copyright (c) Cratis. All rights reserved. */
+/* Licensed under the MIT license. See LICENSE file in the project root for full license information. */
+
+/*
+ * Cratis Components — CSS variable tokens.
+ *
+ * Every internal component references the --cratis-* variables defined here
+ * instead of PrimeReact theme variables directly. Each token defaults to the
+ * matching PrimeReact CSS variable, so when a consumer loads any PrimeReact
+ * theme the components are fully themed out of the box.
+ *
+ * To take full control of the look and feel (with or without PrimeReact's
+ * unstyled / pt mechanism, Tailwind, or your own CSS), override the relevant
+ * --cratis-* tokens on :root (or any ancestor element):
+ *
+ *   :root {
+ *       --cratis-surface-card: #1f2937;
+ *       --cratis-text-color:   #f3f4f6;
+ *   }
+ *
+ * Tokens are intentionally fallback-free — if neither a PrimeReact theme nor
+ * a consumer override is present, the variable resolves to nothing and the
+ * affected rule no-ops. That keeps the library theme-agnostic without
+ * imposing a default palette on consumers.
+ */
+
+:root {
+    /* Surfaces */
+    --cratis-surface-0:        var(--surface-0);
+    --cratis-surface-100:      var(--surface-100);
+    --cratis-surface-ground:   var(--surface-ground);
+    --cratis-surface-section:  var(--surface-section);
+    --cratis-surface-card:     var(--surface-card);
+    --cratis-surface-overlay:  var(--surface-overlay);
+    --cratis-surface-hover:    var(--surface-hover);
+    --cratis-surface-border:   var(--surface-border);
+
+    /* Text */
+    --cratis-text-color:           var(--text-color);
+    --cratis-text-color-secondary: var(--text-color-secondary);
+
+    /* Primary brand */
+    --cratis-primary-color:      var(--primary-color);
+    --cratis-primary-color-text: var(--primary-color-text);
+    --cratis-primary-300:        var(--primary-300);
+    --cratis-primary-400:        var(--primary-400);
+    --cratis-primary-500:        var(--primary-500);
+    --cratis-primary-600:        var(--primary-600);
+
+    /* Highlight / selection */
+    --cratis-highlight-bg:         var(--highlight-bg);
+    --cratis-highlight-text-color: var(--highlight-text-color);
+
+    /* Semantic accents */
+    --cratis-green-500:  var(--green-500);
+    --cratis-orange-500: var(--orange-500);
+    --cratis-red-500:    var(--red-500);
+
+    /* Geometry */
+    --cratis-border-radius: var(--border-radius);
+
+    /* Effects */
+    --cratis-focus-ring: var(--focus-ring);
+    --cratis-maskbg:     var(--maskbg);
+}

From 48131fe8d557345face92d34c9e00e4399f9f909 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:30:27 +0200
Subject: [PATCH 02/23] Migrate internal styles from PrimeReact theme vars to
 --cratis-* tokens

Rename every `var(--surface-*)`, `var(--text-color*)`, `var(--primary-color*)`,
`var(--highlight-*)`, `var(--border-radius)`, `var(--green-500)`,
`var(--orange-500)`, and `var(--red-500)` reference in production CSS, story
files, and trivial inline styles to its `--cratis-*` equivalent.

The tokens cascade to the underlying PrimeReact variables by default, so
behavior is unchanged when a PrimeReact theme is loaded. Consumers wanting to
take control now have a stable, scoped token surface to override on `:root`
or any ancestor.

This commit covers the files whose only change is the rename. Files that
combine var renames with code refactors are migrated in subsequent commits.
---
 .../CommandDialog/CommandStepper.stories.tsx  |   8 +-
 Source/CommandDialog/CommandStepper.tsx       |   6 +-
 Source/CommandForm/fields/Fields.stories.tsx  |  12 +-
 Source/Common/Icon.stories.tsx                |   4 +-
 Source/Common/Tooltip.css                     |   6 +-
 .../ObjectNavigationalBar.stories.tsx         |   2 +-
 Source/PivotViewer/PivotViewer.css            | 260 +++++++++---------
 Source/PivotViewer/components/Spinner.css     |  16 +-
 Source/SchemaEditor/NameCell.tsx              |   2 +-
 Source/SchemaEditor/SchemaEditor.stories.tsx  |   2 +-
 Source/Toolbar/Toolbar.css                    |  34 +--
 Source/Toolbar/Toolbar.stories.tsx            |  22 +-
 12 files changed, 187 insertions(+), 187 deletions(-)

diff --git a/Source/CommandDialog/CommandStepper.stories.tsx b/Source/CommandDialog/CommandStepper.stories.tsx
index f4a4eba..f42729b 100644
--- a/Source/CommandDialog/CommandStepper.stories.tsx
+++ b/Source/CommandDialog/CommandStepper.stories.tsx
@@ -112,7 +112,7 @@ export const Default: Story = {
                 </CommandStepper>
 
                 {result && (
-                    <div className="p-2 mt-3 border-round surface-100" style={{ border: '1px solid var(--surface-border)' }}>
+                    <div className="p-2 mt-3 border-round surface-100" style={{ border: '1px solid var(--cratis-surface-border)' }}>
                         {result}
                     </div>
                 )}
@@ -166,7 +166,7 @@ export const InDialogFrame: Story = {
                             </StepperPanel>
                         </CommandStepper>
                         {result && (
-                            <div className="p-2 mt-3 border-round surface-100" style={{ border: '1px solid var(--surface-border)' }}>
+                            <div className="p-2 mt-3 border-round surface-100" style={{ border: '1px solid var(--cratis-surface-border)' }}>
                                 {result}
                             </div>
                         )}
@@ -229,7 +229,7 @@ export const InDialogFrameWithCenteredHeader: Story = {
                             </StepperPanel>
                         </CommandStepper>
                         {result && (
-                            <div className="p-2 mt-3 border-round surface-100" style={{ border: '1px solid var(--surface-border)' }}>
+                            <div className="p-2 mt-3 border-round surface-100" style={{ border: '1px solid var(--cratis-surface-border)' }}>
                                 {result}
                             </div>
                         )}
@@ -289,7 +289,7 @@ export const WithValidationIndicators: Story = {
                 </CommandStepper>
 
                 {result && (
-                    <div className="p-2 mt-3 border-round surface-100" style={{ border: '1px solid var(--surface-border)' }}>
+                    <div className="p-2 mt-3 border-round surface-100" style={{ border: '1px solid var(--cratis-surface-border)' }}>
                         {result}
                     </div>
                 )}
diff --git a/Source/CommandDialog/CommandStepper.tsx b/Source/CommandDialog/CommandStepper.tsx
index f246fb0..a7c4a92 100644
--- a/Source/CommandDialog/CommandStepper.tsx
+++ b/Source/CommandDialog/CommandStepper.tsx
@@ -187,16 +187,16 @@ export const CommandStepperContent = ({
                     const isVisited = visitedSteps.has(idx);
 
                     const bgColor = hasError
-                        ? 'var(--red-500, #ef4444)'
+                        ? 'var(--cratis-red-500, #ef4444)'
                         : isVisited
-                            ? 'var(--green-500, #22c55e)'
+                            ? 'var(--cratis-green-500, #22c55e)'
                             : null;
 
                     if (!bgColor) return existing;
                     const existingStyle = existing.style as Record<string, unknown> | undefined;
                     return {
                         ...existing,
-                        style: { ...existingStyle, backgroundColor: bgColor, color: 'var(--primary-color-text)' }
+                        style: { ...existingStyle, backgroundColor: bgColor, color: 'var(--cratis-primary-color-text)' }
                     };
                 }
             }
diff --git a/Source/CommandForm/fields/Fields.stories.tsx b/Source/CommandForm/fields/Fields.stories.tsx
index 5b2943f..eab412e 100644
--- a/Source/CommandForm/fields/Fields.stories.tsx
+++ b/Source/CommandForm/fields/Fields.stories.tsx
@@ -192,7 +192,7 @@ export const AllFields: Story = {
                             description="Standard text input field with validation"
                         />
                         {validationState.errors.textInput && (
-                            <div style={{ color: 'var(--red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
+                            <div style={{ color: 'var(--cratis-red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
                                 {validationState.errors.textInput}
                             </div>
                         )}
@@ -205,7 +205,7 @@ export const AllFields: Story = {
                             description="Email input with email validation"
                         />
                         {validationState.errors.emailInput && (
-                            <div style={{ color: 'var(--red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
+                            <div style={{ color: 'var(--cratis-red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
                                 {validationState.errors.emailInput}
                             </div>
                         )}
@@ -218,7 +218,7 @@ export const AllFields: Story = {
                             description="Password input field (min 6 characters)"
                         />
                         {validationState.errors.passwordInput && (
-                            <div style={{ color: 'var(--red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
+                            <div style={{ color: 'var(--cratis-red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
                                 {validationState.errors.passwordInput}
                             </div>
                         )}
@@ -239,7 +239,7 @@ export const AllFields: Story = {
                             step={1}
                         />
                         {validationState.errors.numberInput && (
-                            <div style={{ color: 'var(--red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
+                            <div style={{ color: 'var(--cratis-red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
                                 {validationState.errors.numberInput}
                             </div>
                         )}
@@ -274,7 +274,7 @@ export const AllFields: Story = {
                             optionLabel="name"
                         />
                         {validationState.errors.dropdown && (
-                            <div style={{ color: 'var(--red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
+                            <div style={{ color: 'var(--cratis-red-500)', fontSize: '0.875rem', marginTop: '0.25rem', marginBottom: '1rem' }}>
                                 {validationState.errors.dropdown}
                             </div>
                         )}
@@ -414,7 +414,7 @@ export const AllFields: Story = {
                             Submit Form
                         </button>
                         {!validationState.canSubmit && Object.keys(validationState.errors).length > 0 && (
-                            <span style={{ color: 'var(--orange-500)', fontSize: '0.875rem' }}>
+                            <span style={{ color: 'var(--cratis-orange-500)', fontSize: '0.875rem' }}>
                                 Please fix validation errors
                             </span>
                         )}
diff --git a/Source/Common/Icon.stories.tsx b/Source/Common/Icon.stories.tsx
index 0a4fafc..76f4a35 100644
--- a/Source/Common/Icon.stories.tsx
+++ b/Source/Common/Icon.stories.tsx
@@ -61,7 +61,7 @@ export const StringVsReactNode: Story = {
         <div style={{ display: 'flex', gap: '2rem', alignItems: 'center' }}>
             <div style={{ textAlign: 'center' }}>
                 <IconDisplay icon='pi pi-home' className='text-2xl' />
-                <p style={{ fontSize: '0.75rem', marginTop: '0.5rem', color: 'var(--text-color-secondary)' }}>
+                <p style={{ fontSize: '0.75rem', marginTop: '0.5rem', color: 'var(--cratis-text-color-secondary)' }}>
                     string (CSS class)
                 </p>
             </div>
@@ -80,7 +80,7 @@ export const StringVsReactNode: Story = {
                         </svg>
                     }
                 />
-                <p style={{ fontSize: '0.75rem', marginTop: '0.5rem', color: 'var(--text-color-secondary)' }}>
+                <p style={{ fontSize: '0.75rem', marginTop: '0.5rem', color: 'var(--cratis-text-color-secondary)' }}>
                     ReactNode (SVG)
                 </p>
             </div>
diff --git a/Source/Common/Tooltip.css b/Source/Common/Tooltip.css
index bfc9388..0f9d6a3 100644
--- a/Source/Common/Tooltip.css
+++ b/Source/Common/Tooltip.css
@@ -3,8 +3,8 @@
 
 /* ── Tooltip bubble ──────────────────────────────────────────────────────── */
 .tooltip-bubble {
-    background: var(--surface-100);
-    color: var(--text-color);
-    border: 1px solid var(--surface-border);
+    background: var(--cratis-surface-100);
+    color: var(--cratis-text-color);
+    border: 1px solid var(--cratis-surface-border);
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
 }
diff --git a/Source/ObjectNavigationalBar/ObjectNavigationalBar.stories.tsx b/Source/ObjectNavigationalBar/ObjectNavigationalBar.stories.tsx
index d9b3ee1..261a406 100644
--- a/Source/ObjectNavigationalBar/ObjectNavigationalBar.stories.tsx
+++ b/Source/ObjectNavigationalBar/ObjectNavigationalBar.stories.tsx
@@ -30,7 +30,7 @@ export const Interactive: Story = {
         };
 
         return (
-            <div style={{ padding: '1rem', background: 'var(--surface-ground)', minHeight: '200px' }}>
+            <div style={{ padding: '1rem', background: 'var(--cratis-surface-ground)', minHeight: '200px' }}>
                 <h3>Current Path: {navigationPath.length > 0 ? navigationPath.join(' > ') : 'Root'}</h3>
                 <ObjectNavigationalBar
                     navigationPath={navigationPath}
diff --git a/Source/PivotViewer/PivotViewer.css b/Source/PivotViewer/PivotViewer.css
index 762d50d..8208cbd 100644
--- a/Source/PivotViewer/PivotViewer.css
+++ b/Source/PivotViewer/PivotViewer.css
@@ -8,8 +8,8 @@
   max-height: 100%; /* respect parent height if set */
   width: 100%;
   /* Keep root neutral; move visual background to the viewport so it never exceeds the container */
-  background: var(--surface-ground);
-  color: var(--text-color);
+  background: var(--cratis-surface-ground);
+  color: var(--cratis-text-color);
   overflow: hidden;
   font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
   /* Ensure we shrink within flex parent */
@@ -20,8 +20,8 @@
   position: fixed;
   width: min(280px, calc(100% - 2rem));
   max-height: calc(100vh - 6.5rem);
-  background: linear-gradient(180deg, var(--surface-card), var(--surface-ground));
-  border: 1px solid var(--surface-border);
+  background: linear-gradient(180deg, var(--cratis-surface-card), var(--cratis-surface-ground));
+  border: 1px solid var(--cratis-surface-border);
   border-radius: 1rem;
   box-shadow: 0 24px 60px rgba(0, 0, 0, 0.3);
   backdrop-filter: blur(14px);
@@ -46,8 +46,8 @@
   gap: 0.5rem;
   padding: 0.75rem 1rem;
   cursor: grab;
-  background: var(--surface-section);
-  border-bottom: 1px solid var(--surface-border);
+  background: var(--cratis-surface-section);
+  border-bottom: 1px solid var(--cratis-surface-border);
   flex-shrink: 0;
 }
 
@@ -60,7 +60,7 @@
   font-size: 0.85rem;
   letter-spacing: 0.04em;
   text-transform: uppercase;
-  color: var(--text-color);
+  color: var(--cratis-text-color);
   flex: 1;
   pointer-events: none;
 }
@@ -75,8 +75,8 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  background: var(--highlight-bg);
-  color: var(--text-color);
+  background: var(--cratis-highlight-bg);
+  color: var(--cratis-text-color);
   font-size: 1rem;
   font-weight: 500;
   cursor: pointer;
@@ -85,7 +85,7 @@
 
 .pv-minimize-btn:hover,
 .pv-close-btn:hover {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
 }
 
 .pv-close-btn {
@@ -116,17 +116,17 @@
   width: 100%;
   padding: 0.65rem 0.85rem;
   border-radius: 0.75rem;
-  border: 1px solid var(--surface-border);
-  background: var(--surface-ground);
+  border: 1px solid var(--cratis-surface-border);
+  background: var(--cratis-surface-ground);
   color: inherit;
   font-size: 0.95rem;
-  box-shadow: inset 0 1px 0 var(--surface-border);
+  box-shadow: inset 0 1px 0 var(--cratis-surface-border);
 }
 
 .pv-search input:focus {
   outline: none;
-  border-color: var(--primary-color);
-  box-shadow: var(--focus-ring);
+  border-color: var(--cratis-primary-color);
+  box-shadow: var(--cratis-focus-ring);
 }
 
 
@@ -137,15 +137,15 @@
 }
 
 .pv-filter {
-  background: var(--surface-overlay);
-  border: 1px solid var(--surface-border);
+  background: var(--cratis-surface-overlay);
+  border: 1px solid var(--cratis-surface-border);
   border-radius: 0.85rem;
   padding: 0.75rem 0.85rem;
   transition: border-color 180ms ease, box-shadow 180ms ease;
 }
 
 .pv-filter.expanded {
-  border-color: var(--primary-color);
+  border-color: var(--cratis-primary-color);
   box-shadow: 0 15px 38px rgba(0, 0, 0, 0.3);
 }
 
@@ -184,16 +184,16 @@
   min-width: 1.5rem;
   padding: 0.15rem 0.45rem;
   border-radius: 999px;
-  background: var(--highlight-bg);
-  color: var(--text-color);
+  background: var(--cratis-highlight-bg);
+  color: var(--cratis-text-color);
   font-size: 0.7rem;
 }
 
 .pv-filter-chevron {
   width: 0.65rem;
   height: 0.65rem;
-  border-right: 2px solid var(--text-color);
-  border-bottom: 2px solid var(--text-color);
+  border-right: 2px solid var(--cratis-text-color);
+  border-bottom: 2px solid var(--cratis-text-color);
   transform: rotate(45deg);
   transition: transform 180ms ease;
 }
@@ -217,7 +217,7 @@
   opacity: 1;
   margin-top: 0.75rem;
   padding-top: 0.75rem;
-  border-top-color: var(--surface-border);
+  border-top-color: var(--cratis-surface-border);
   overflow-y: auto;
 }
 
@@ -242,12 +242,12 @@
 }
 
 .pv-filter-content li label:hover {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
 }
 
 .pv-filter-content input[type='checkbox'],
 .pv-filter-content input[type='radio'] {
-  accent-color: var(--primary-color);
+  accent-color: var(--cratis-primary-color);
 }
 
 .pv-filter-content li label span {
@@ -260,8 +260,8 @@
   border: none;
   border-radius: 0.55rem;
   padding: 0.4rem 0.75rem;
-  background: var(--highlight-bg);
-  color: var(--text-color);
+  background: var(--cratis-highlight-bg);
+  color: var(--cratis-text-color);
   font-size: 0.72rem;
   text-transform: uppercase;
   letter-spacing: 0.08em;
@@ -271,7 +271,7 @@
 .pv-option-count {
   font-feature-settings: "tnum";
   font-variant-numeric: tabular-nums;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
   font-size: 0.75rem;
 }
 
@@ -291,8 +291,8 @@
   justify-content: space-between;
   align-items: center;
   padding: 0.75rem 1.75rem;
-  border-bottom: 1px solid var(--surface-border);
-  background: var(--surface-section);
+  border-bottom: 1px solid var(--cratis-surface-border);
+  background: var(--cratis-surface-section);
   backdrop-filter: blur(12px);
   position: sticky;
   top: 0;
@@ -329,9 +329,9 @@
   gap: 0.35rem;
   padding: 0.3rem 0.65rem;
   border-radius: 999px;
-  background: var(--highlight-bg);
+  background: var(--cratis-highlight-bg);
   font-size: 0.8rem;
-  color: var(--text-color);
+  color: var(--cratis-text-color);
 }
 
 .pv-filter-button {
@@ -339,8 +339,8 @@
   border: none;
   border-radius: 999px;
   padding: 0.45rem 1rem;
-  background: var(--highlight-bg);
-  color: var(--text-color);
+  background: var(--cratis-highlight-bg);
+  color: var(--cratis-text-color);
   font-size: 0.8rem;
   letter-spacing: 0.08em;
   text-transform: uppercase;
@@ -350,8 +350,8 @@
 
 .pv-filter-button.active,
 .pv-filter-button:hover {
-  background: var(--surface-hover);
-  box-shadow: var(--focus-ring);
+  background: var(--cratis-surface-hover);
+  box-shadow: var(--cratis-focus-ring);
 }
 
 /* Filter Icon Button */
@@ -365,19 +365,19 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  background: var(--highlight-bg);
-  color: var(--text-color);
+  background: var(--cratis-highlight-bg);
+  color: var(--cratis-text-color);
   cursor: pointer;
   transition: background 180ms ease, box-shadow 180ms ease;
 }
 
 .pv-filter-icon-button:hover {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
 }
 
 .pv-filter-icon-button.active {
-  background: var(--surface-hover);
-  box-shadow: var(--focus-ring);
+  background: var(--cratis-surface-hover);
+  box-shadow: var(--cratis-focus-ring);
 }
 
 .pv-filter-badge {
@@ -390,8 +390,8 @@
   align-items: center;
   justify-content: center;
   border-radius: 999px;
-  background: var(--primary-color);
-  color: var(--primary-color-text);
+  background: var(--cratis-primary-color);
+  color: var(--cratis-primary-color-text);
   font-size: 0.65rem;
   font-weight: 600;
   padding: 0 0.25rem;
@@ -402,8 +402,8 @@
   position: fixed;
   width: min(320px, calc(100vw - 2rem));
   max-height: calc(100vh - 8rem);
-  background: linear-gradient(180deg, var(--surface-card), var(--surface-ground));
-  border: 1px solid var(--surface-border);
+  background: linear-gradient(180deg, var(--cratis-surface-card), var(--cratis-surface-ground));
+  border: 1px solid var(--cratis-surface-border);
   border-radius: 0.85rem;
   box-shadow: 0 20px 50px rgba(0, 0, 0, 0.4);
   backdrop-filter: blur(16px);
@@ -425,8 +425,8 @@
   display: inline-flex;
   align-items: center;
   border-radius: 999px;
-  background: var(--surface-section);
-  border: 1px solid var(--surface-border);
+  background: var(--cratis-surface-section);
+  border: 1px solid var(--cratis-surface-border);
   padding: 0.2rem;
   gap: 0.2rem;
 }
@@ -436,7 +436,7 @@
   border: none;
   border-radius: 999px;
   padding: 0.35rem 0.9rem;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
   background: transparent;
   font-size: 0.75rem;
   letter-spacing: 0.06em;
@@ -446,16 +446,16 @@
 }
 
 .pv-view-toggle button.active {
-  background: var(--primary-color);
-  color: var(--primary-color-text);
+  background: var(--cratis-primary-color);
+  color: var(--cratis-primary-color-text);
 }
 
 .pv-zoom-controls {
   display: inline-flex;
   align-items: center;
   gap: 0.5rem;
-  background: var(--surface-section);
-  border: 1px solid var(--surface-border);
+  background: var(--cratis-surface-section);
+  border: 1px solid var(--cratis-surface-border);
   border-radius: 0.6rem;
   padding: 0.25rem 0.5rem;
 }
@@ -464,7 +464,7 @@
   appearance: none;
   border: none;
   background: transparent;
-  color: var(--text-color);
+  color: var(--cratis-text-color);
   font-size: 1.1rem;
   width: 1.75rem;
   height: 1.75rem;
@@ -477,8 +477,8 @@
 }
 
 .pv-zoom-controls button:hover {
-  background: var(--surface-hover);
-  color: var(--text-color);
+  background: var(--cratis-surface-hover);
+  color: var(--cratis-text-color);
 }
 
 .pv-zoom-controls button:disabled {
@@ -490,7 +490,7 @@
   width: 80px;
   height: 4px;
   appearance: none;
-  background: var(--surface-border);
+  background: var(--cratis-surface-border);
   border-radius: 2px;
   cursor: pointer;
 }
@@ -499,8 +499,8 @@
   appearance: none;
   width: 14px;
   height: 14px;
-  background: var(--primary-color);
-  border: 2px solid var(--text-color);
+  background: var(--cratis-primary-color);
+  border: 2px solid var(--cratis-text-color);
   border-radius: 50%;
   cursor: pointer;
   box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
@@ -514,8 +514,8 @@
 .pv-zoom-slider::-moz-range-thumb {
   width: 14px;
   height: 14px;
-  background: var(--primary-color);
-  border: 2px solid var(--text-color);
+  background: var(--cratis-primary-color);
+  border: 2px solid var(--cratis-text-color);
   border-radius: 50%;
   cursor: pointer;
   box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
@@ -523,7 +523,7 @@
 
 .pv-zoom-controls span {
   font-size: 0.75rem;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
   min-width: 3rem;
   text-align: center;
   font-variant-numeric: tabular-nums;
@@ -534,17 +534,17 @@
 }
 
 .pv-zoom-controls span:hover {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
 }
 
 .pv-zoom-level-input {
   width: 3rem;
   font-size: 0.75rem;
   text-align: center;
-  background: var(--surface-ground);
-  border: 1px solid var(--primary-color);
+  background: var(--cratis-surface-ground);
+  border: 1px solid var(--cratis-primary-color);
   border-radius: 0.4rem;
-  color: var(--text-color);
+  color: var(--cratis-text-color);
   padding: 0.25rem 0.5rem;
   font-variant-numeric: tabular-nums;
   outline: none;
@@ -561,12 +561,12 @@
   align-items: center;
   gap: 0.6rem;
   font-size: 0.9rem;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
 }
 
 .pv-dimension-select select {
-  background: var(--surface-ground);
-  border: 1px solid var(--surface-border);
+  background: var(--cratis-surface-ground);
+  border: 1px solid var(--cratis-surface-border);
   border-radius: 0.6rem;
   color: inherit;
   font-size: 0.9rem;
@@ -615,7 +615,7 @@
 
 /* Visual background belongs to the scrollable viewport area so it respects container bounds */
 .pv-viewport {
-  background: radial-gradient(circle at 25% 20%, var(--primary-500), var(--surface-ground));
+  background: radial-gradient(circle at 25% 20%, var(--cratis-primary-500), var(--cratis-surface-ground));
 }
 
 .pv-groups-grouped {
@@ -663,13 +663,13 @@
 
 .pv-group-grouped:hover::before,
 .pv-group-grouped.highlighted::before {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
 }
 
 /* Zebra striping hover state - combine with stripe background */
 .pv-group-grouped:nth-child(even):hover::before,
 .pv-group-grouped:nth-child(even).highlighted::before {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
 }
 
 .pv-group:hover {
@@ -692,8 +692,8 @@
 
 .pv-group header span {
   font-size: 0.75rem;
-  color: var(--text-color-secondary);
-  background: var(--highlight-bg);
+  color: var(--cratis-text-color-secondary);
+  background: var(--cratis-highlight-bg);
   padding: 0.15rem 0.5rem;
   border-radius: 999px;
 }
@@ -726,8 +726,8 @@
 .pv-axis-labels {
   display: flex;
   align-items: stretch;
-  background: var(--surface-section);
-  border-top: 1px solid var(--surface-border);
+  background: var(--cratis-surface-section);
+  border-top: 1px solid var(--cratis-surface-border);
   padding: 0.5rem 0; /* padding-left set dynamically from JS; no right padding to prevent skew */
   gap: 0; /* No extra gap to avoid skew */
   overflow-x: hidden; /* Disable independent scroll - synced via JS */
@@ -759,29 +759,29 @@
 
 .pv-axis-label:hover,
 .pv-axis-label.highlighted {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
 }
 
 /* Zebra striping hover/highlight for even labels */
 .pv-axis-label:nth-child(even):hover,
 .pv-axis-label:nth-child(even).highlighted {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
 }
 
 .pv-axis-label.selected {
-  border-color: var(--primary-color);
-  background: var(--highlight-bg);
+  border-color: var(--cratis-primary-color);
+  background: var(--cratis-highlight-bg);
 }
 
 .pv-axis-label:focus-visible {
   outline: none;
-  border-color: var(--primary-color);
-  box-shadow: var(--focus-ring);
+  border-color: var(--cratis-primary-color);
+  box-shadow: var(--cratis-focus-ring);
 }
 
 .pv-axis-label-text {
   font-size: 0.75rem;
-  color: var(--text-color);
+  color: var(--cratis-text-color);
   font-weight: 500;
   white-space: nowrap;
   overflow: hidden;
@@ -791,7 +791,7 @@
 
 .pv-axis-label-count {
   font-size: 0.65rem;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
   margin-top: 0.15rem;
   font-variant-numeric: tabular-nums;
 }
@@ -873,14 +873,14 @@
 }
 
 .pv-cards-collection .pv-card {
-  background: linear-gradient(180deg, var(--surface-card), var(--surface-ground));
+  background: linear-gradient(180deg, var(--cratis-surface-card), var(--cratis-surface-ground));
 }
 
 .pv-card {
   border: none;
   text-align: left;
   padding: 0;
-  background: linear-gradient(180deg, var(--surface-card), var(--surface-ground));
+  background: linear-gradient(180deg, var(--cratis-surface-card), var(--cratis-surface-ground));
   border-radius: 0.85rem;
   cursor: pointer;
   color: inherit;
@@ -890,13 +890,13 @@
 
 .pv-card:focus-visible {
   outline: none;
-  border-color: var(--primary-color);
-  box-shadow: var(--focus-ring);
+  border-color: var(--cratis-primary-color);
+  box-shadow: var(--cratis-focus-ring);
 }
 
 .pv-card.selected {
-  border-color: var(--primary-color);
-  box-shadow: var(--focus-ring), 0 8px 20px rgba(0, 0, 0, 0.2);
+  border-color: var(--cratis-primary-color);
+  box-shadow: var(--cratis-focus-ring), 0 8px 20px rgba(0, 0, 0, 0.2);
 }
 
 .pv-card-body {
@@ -920,14 +920,14 @@
   grid-template-columns: minmax(0, 0.9fr) minmax(0, 1fr);
   gap: calc(0.5rem * var(--zoom-scale, 1));
   font-size: calc(0.8rem * var(--zoom-scale, 1));
-  color: var(--text-color);
+  color: var(--cratis-text-color);
   margin-bottom: calc(0.35rem * var(--zoom-scale, 1));
   line-height: 1.3;
 }
 
 .pv-card-row dt {
   margin: 0;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
   font-weight: 500;
   overflow: hidden;
   text-overflow: ellipsis;
@@ -943,7 +943,7 @@
 
 .pv-card-more {
   margin-top: calc(0.4rem * var(--zoom-scale, 1));
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
   text-align: right;
   font-size: calc(0.9rem * var(--zoom-scale, 1));
 }
@@ -952,7 +952,7 @@
   width: 100%;
   text-align: center;
   padding: 3rem;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
   font-size: 1.05rem;
 }
 
@@ -963,8 +963,8 @@
   right: 0;
   bottom: 0;
   width: 380px;
-  background: var(--surface-overlay);
-  border-left: 1px solid var(--surface-border);
+  background: var(--cratis-surface-overlay);
+  border-left: 1px solid var(--cratis-surface-border);
   display: flex;
   flex-direction: column;
   z-index: 14;
@@ -976,27 +976,27 @@
   align-items: center;
   justify-content: space-between;
   padding: 1rem 1.25rem;
-  border-bottom: 1px solid var(--surface-border);
+  border-bottom: 1px solid var(--cratis-surface-border);
   flex-shrink: 0;
 }
 
 .pv-detail-panel header h2 {
   margin: 0;
   font-size: 1.1rem;
-  color: var(--text-color);
+  color: var(--cratis-text-color);
 }
 
 .pv-detail-panel header p {
   margin: 0.25rem 0 0;
   font-size: 0.8rem;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
 }
 
 .pv-detail-panel header button {
   appearance: none;
   border: none;
-  background: var(--surface-hover);
-  color: var(--text-color);
+  background: var(--cratis-surface-hover);
+  color: var(--cratis-text-color);
   width: 32px;
   height: 32px;
   border-radius: 8px;
@@ -1009,7 +1009,7 @@
 }
 
 .pv-detail-panel header button:hover {
-  background: var(--highlight-bg);
+  background: var(--cratis-highlight-bg);
 }
 
 .pv-detail-panel-content {
@@ -1023,7 +1023,7 @@
   font-size: 0.85rem;
   text-transform: uppercase;
   letter-spacing: 0.06em;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
 }
 
 .pv-detail-panel section + section {
@@ -1036,7 +1036,7 @@
 }
 
 .pv-detail-panel dl > div {
-  background: var(--surface-section);
+  background: var(--cratis-surface-section);
   border-radius: 0.6rem;
   padding: 0.5rem 0.7rem;
 }
@@ -1046,13 +1046,13 @@
   font-size: 0.7rem;
   text-transform: uppercase;
   letter-spacing: 0.08em;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
 }
 
 .pv-detail-panel dd {
   margin: 0.15rem 0 0;
   font-size: 0.85rem;
-  color: var(--text-color);
+  color: var(--cratis-text-color);
   white-space: pre-wrap;
   word-break: break-word;
 }
@@ -1072,7 +1072,7 @@
   display: none;
   position: fixed;
   inset: 0;
-  background: var(--maskbg);
+  background: var(--cratis-maskbg);
   backdrop-filter: blur(6px);
   display: flex;
   align-items: flex-end;
@@ -1083,13 +1083,13 @@
 
 .pv-detail {
   width: min(720px, 100%);
-  background: var(--surface-overlay);
-  border: 1px solid var(--surface-border);
+  background: var(--cratis-surface-overlay);
+  border: 1px solid var(--cratis-surface-border);
   border-radius: 1.25rem;
   padding: 1.75rem;
   max-height: min(80vh, 640px);
   overflow-y: auto;
-  color: var(--text-color);
+  color: var(--cratis-text-color);
 }
 
 .pv-detail header {
@@ -1107,7 +1107,7 @@
 .pv-detail header p {
   margin: 0;
   font-size: 0.9rem;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
 }
 
 .pv-detail header button {
@@ -1115,7 +1115,7 @@
   border: none;
   border-radius: 0.75rem;
   padding: 0.5rem 1rem;
-  background: var(--highlight-bg);
+  background: var(--cratis-highlight-bg);
   color: inherit;
   cursor: pointer;
 }
@@ -1136,7 +1136,7 @@
 }
 
 .pv-detail dl > div {
-  background: var(--surface-section);
+  background: var(--cratis-surface-section);
   border-radius: 0.75rem;
   padding: 0.55rem 0.75rem;
 }
@@ -1146,13 +1146,13 @@
   font-size: 0.75rem;
   text-transform: uppercase;
   letter-spacing: 0.08em;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
 }
 
 .pv-detail dd {
   margin: 0.2rem 0 0;
   font-size: 0.9rem;
-  color: var(--text-color);
+  color: var(--cratis-text-color);
   white-space: pre-wrap;
   word-break: break-word;
 }
@@ -1173,10 +1173,10 @@
   gap: 0.35rem;
   padding: 0.35rem 0.65rem;
   border-radius: 999px;
-  background: var(--highlight-bg);
-  color: var(--text-color);
+  background: var(--cratis-highlight-bg);
+  color: var(--cratis-text-color);
   font-size: 0.8rem;
-  border: 1px solid var(--surface-border);
+  border: 1px solid var(--cratis-surface-border);
 }
 
 /* Range Histogram Filter */
@@ -1196,7 +1196,7 @@
 .pv-histogram-bar {
   flex: 1;
   min-width: 8px;
-  background: var(--highlight-bg);
+  background: var(--cratis-highlight-bg);
   border: none;
   border-radius: 2px 2px 0 0;
   cursor: pointer;
@@ -1205,16 +1205,16 @@
 }
 
 .pv-histogram-bar:hover {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
   transform: scaleY(1.02);
 }
 
 .pv-histogram-bar.in-range {
-  background: var(--primary-color);
+  background: var(--cratis-primary-color);
 }
 
 .pv-histogram-bar.partial {
-  background: var(--highlight-bg);
+  background: var(--cratis-highlight-bg);
 }
 
 .pv-range-slider {
@@ -1229,7 +1229,7 @@
   left: 0;
   right: 0;
   height: 4px;
-  background: var(--surface-border);
+  background: var(--cratis-surface-border);
   border-radius: 2px;
   transform: translateY(-50%);
 }
@@ -1238,7 +1238,7 @@
   position: absolute;
   top: 50%;
   height: 4px;
-  background: var(--primary-color);
+  background: var(--cratis-primary-color);
   border-radius: 2px;
   transform: translateY(-50%);
   cursor: grab;
@@ -1253,8 +1253,8 @@
   top: 50%;
   width: 16px;
   height: 16px;
-  background: var(--primary-color);
-  border: 2px solid var(--text-color);
+  background: var(--cratis-primary-color);
+  border: 2px solid var(--cratis-text-color);
   border-radius: 50%;
   transform: translate(-50%, -50%);
   cursor: ew-resize;
@@ -1264,14 +1264,14 @@
 
 .pv-range-handle:hover {
   transform: translate(-50%, -50%) scale(1.15);
-  box-shadow: 0 4px 12px var(--primary-color);
+  box-shadow: 0 4px 12px var(--cratis-primary-color);
 }
 
 .pv-range-labels {
   display: flex;
   justify-content: space-between;
   font-size: 0.75rem;
-  color: var(--text-color-secondary);
+  color: var(--cratis-text-color-secondary);
   font-variant-numeric: tabular-nums;
 }
 
@@ -1281,8 +1281,8 @@
   border: none;
   border-radius: 0.55rem;
   padding: 0.4rem 0.75rem;
-  background: var(--highlight-bg);
-  color: var(--text-color);
+  background: var(--cratis-highlight-bg);
+  color: var(--cratis-text-color);
   font-size: 0.72rem;
   text-transform: uppercase;
   letter-spacing: 0.08em;
@@ -1291,7 +1291,7 @@
 }
 
 .pv-range-clear:hover {
-  background: var(--surface-hover);
+  background: var(--cratis-surface-hover);
 }
 
 @media (max-width: 900px) {
diff --git a/Source/PivotViewer/components/Spinner.css b/Source/PivotViewer/components/Spinner.css
index f3c9674..80ee30d 100644
--- a/Source/PivotViewer/components/Spinner.css
+++ b/Source/PivotViewer/components/Spinner.css
@@ -21,48 +21,48 @@
 }
 
 .pv-spinner-ring:nth-child(1) {
-  border-top-color: var(--primary-300);
+  border-top-color: var(--cratis-primary-300);
   animation: spinner-rotate 1.5s linear infinite;
 }
 
 .pv-spinner-ring:nth-child(2) {
-  border-right-color: var(--primary-400);
+  border-right-color: var(--cratis-primary-400);
   animation: spinner-rotate 1.5s linear infinite;
   animation-delay: -0.1875s;
 }
 
 .pv-spinner-ring:nth-child(3) {
-  border-bottom-color: var(--primary-500);
+  border-bottom-color: var(--cratis-primary-500);
   animation: spinner-rotate 1.5s linear infinite;
   animation-delay: -0.375s;
 }
 
 .pv-spinner-ring:nth-child(4) {
-  border-left-color: var(--primary-600);
+  border-left-color: var(--cratis-primary-600);
   animation: spinner-rotate 1.5s linear infinite;
   animation-delay: -0.5625s;
 }
 
 .pv-spinner-ring:nth-child(5) {
-  border-top-color: var(--primary-400);
+  border-top-color: var(--cratis-primary-400);
   animation: spinner-rotate 1.5s linear infinite reverse;
   animation-delay: -0.75s;
 }
 
 .pv-spinner-ring:nth-child(6) {
-  border-right-color: var(--primary-500);
+  border-right-color: var(--cratis-primary-500);
   animation: spinner-rotate 1.5s linear infinite reverse;
   animation-delay: -0.9375s;
 }
 
 .pv-spinner-ring:nth-child(7) {
-  border-bottom-color: var(--primary-300);
+  border-bottom-color: var(--cratis-primary-300);
   animation: spinner-rotate 1.5s linear infinite reverse;
   animation-delay: -1.125s;
 }
 
 .pv-spinner-ring:nth-child(8) {
-  border-left-color: var(--primary-600);
+  border-left-color: var(--cratis-primary-600);
   animation: spinner-rotate 1.5s linear infinite reverse;
   animation-delay: -1.3125s;
 }
diff --git a/Source/SchemaEditor/NameCell.tsx b/Source/SchemaEditor/NameCell.tsx
index de9eab7..467e824 100644
--- a/Source/SchemaEditor/NameCell.tsx
+++ b/Source/SchemaEditor/NameCell.tsx
@@ -31,7 +31,7 @@ export const NameCell = ({ rowData, isEditMode, onUpdate, validationError }: Nam
                 {rowData.description && (
                     <faIcons.FaCircleInfo
                         className="schema-description-tooltip"
-                        style={{ color: 'var(--text-color-secondary)', fontSize: '0.875rem' }}
+                        style={{ color: 'var(--cratis-text-color-secondary)', fontSize: '0.875rem' }}
                         data-pr-tooltip={rowData.description}
                         data-pr-position="right"
                     />
diff --git a/Source/SchemaEditor/SchemaEditor.stories.tsx b/Source/SchemaEditor/SchemaEditor.stories.tsx
index f286436..3734f98 100644
--- a/Source/SchemaEditor/SchemaEditor.stories.tsx
+++ b/Source/SchemaEditor/SchemaEditor.stories.tsx
@@ -89,7 +89,7 @@ export const Interactive: Story = {
         const [schema, setSchema] = useState<JsonSchema>(JSON.parse(JSON.stringify(sampleSchema)));
 
         return (
-            <div style={{ height: '600px', background: 'var(--surface-ground)' }}>
+            <div style={{ height: '600px', background: 'var(--cratis-surface-ground)' }}>
                 <SchemaEditor
                     schema={schema}
                     eventTypeName="User"
diff --git a/Source/Toolbar/Toolbar.css b/Source/Toolbar/Toolbar.css
index 3b05877..fdd82d6 100644
--- a/Source/Toolbar/Toolbar.css
+++ b/Source/Toolbar/Toolbar.css
@@ -3,32 +3,32 @@
 
 /* ── Toolbar container ───────────────────────────────────────────────────── */
 .toolbar {
-    background: var(--surface-card);
-    border: 1px solid var(--surface-border);
+    background: var(--cratis-surface-card);
+    border: 1px solid var(--cratis-surface-border);
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
 }
 
 /* ── Toolbar button ──────────────────────────────────────────────────────── */
 .toolbar-button {
-    color: var(--text-color-secondary);
+    color: var(--cratis-text-color-secondary);
     background: transparent;
     border: none;
     transition: background 0.15s, color 0.15s;
 }
 
 .toolbar-button:hover {
-    background: var(--surface-100);
-    color: var(--text-color);
+    background: var(--cratis-surface-100);
+    color: var(--cratis-text-color);
 }
 
 .toolbar-button--active {
-    background: var(--primary-color);
-    color: var(--primary-color-text);
+    background: var(--cratis-primary-color);
+    color: var(--cratis-primary-color-text);
 }
 
 .toolbar-button--active:hover {
-    background: var(--primary-color);
-    color: var(--primary-color-text);
+    background: var(--cratis-primary-color);
+    color: var(--cratis-primary-color-text);
 }
 
 .toolbar-button--draggable {
@@ -51,7 +51,7 @@
     padding: 0 8px;
     font-size: 0.875rem;
     font-weight: 500;
-    color: var(--text-color);
+    color: var(--cratis-text-color);
     white-space: nowrap;
 }
 
@@ -100,7 +100,7 @@
 /* ── Toolbar separator ───────────────────────────────────────────────────── */
 
 .toolbar-separator {
-    background: var(--surface-border);
+    background: var(--cratis-surface-border);
     flex-shrink: 0;
     align-self: stretch;
 }
@@ -142,8 +142,8 @@
     align-items: center;
     gap: 0.25rem;
     padding: 0.5rem;
-    background: var(--surface-card);
-    border: 1px solid var(--surface-border);
+    background: var(--cratis-surface-card);
+    border: 1px solid var(--cratis-surface-border);
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
     border-radius: 1rem;
     white-space: nowrap;
@@ -207,8 +207,8 @@
     grid-auto-rows: minmax(2.5rem, auto);
     gap: 0.25rem;
     padding: 0.5rem;
-    background: var(--surface-card);
-    border: 1px solid var(--surface-border);
+    background: var(--cratis-surface-card);
+    border: 1px solid var(--cratis-surface-border);
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
     border-radius: 1rem;
     z-index: 10;
@@ -279,8 +279,8 @@
  * of a standalone Toolbar.
  */
 .toolbar-group {
-    background: var(--surface-card);
-    border: 1px solid var(--surface-border);
+    background: var(--cratis-surface-card);
+    border: 1px solid var(--cratis-surface-border);
     box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
 }
 
diff --git a/Source/Toolbar/Toolbar.stories.tsx b/Source/Toolbar/Toolbar.stories.tsx
index d47e9a8..75e79e0 100644
--- a/Source/Toolbar/Toolbar.stories.tsx
+++ b/Source/Toolbar/Toolbar.stories.tsx
@@ -424,9 +424,9 @@ export const DragAndDrop: Story = {
                         style={{
                             width: 240,
                             height: 180,
-                            borderColor: isDragOver ? 'var(--primary-color)' : 'var(--surface-border)',
-                            background: isDragOver ? 'var(--highlight-bg)' : 'var(--surface-card)',
-                            color: 'var(--text-color-secondary)',
+                            borderColor: isDragOver ? 'var(--cratis-primary-color)' : 'var(--cratis-surface-border)',
+                            background: isDragOver ? 'var(--cratis-highlight-bg)' : 'var(--cratis-surface-card)',
+                            color: 'var(--cratis-text-color-secondary)',
                             fontSize: '0.875rem',
                         }}
                     >
@@ -501,7 +501,7 @@ export const FolderGridVsList: Story = {
     render: () => (
         <div className='flex gap-8 items-start'>
             <div className='flex flex-col items-center gap-2'>
-                <span style={{ color: 'var(--text-color-secondary)', fontSize: '0.75rem' }}>Grid (default)</span>
+                <span style={{ color: 'var(--cratis-text-color-secondary)', fontSize: '0.75rem' }}>Grid (default)</span>
                 <Toolbar>
                     <ToolbarFolder icon='pi pi-th-large' title='Tools' mode='grid'>
                         <ToolbarButton icon='pi pi-pencil' title='Draw' />
@@ -514,7 +514,7 @@ export const FolderGridVsList: Story = {
                 </Toolbar>
             </div>
             <div className='flex flex-col items-center gap-2'>
-                <span style={{ color: 'var(--text-color-secondary)', fontSize: '0.75rem' }}>List</span>
+                <span style={{ color: 'var(--cratis-text-color-secondary)', fontSize: '0.75rem' }}>List</span>
                 <Toolbar>
                     <ToolbarFolder icon='pi pi-list' title='Tools' mode='list'>
                         <ToolbarButton icon='pi pi-pencil' title='Draw freehand' />
@@ -647,7 +647,7 @@ export const WithSlotInContext: Story = {
 
                         <div className='flex flex-col gap-4 items-center'>
                             <div className='flex flex-col gap-2 items-center'>
-                                <span className='text-xs' style={{ color: 'var(--text-color-secondary)' }}>Context</span>
+                                <span className='text-xs' style={{ color: 'var(--cratis-text-color-secondary)' }}>Context</span>
                                 <div className='flex gap-2'>
                                     {(['drawing', 'text'] as const).map(ctx => (
                                         <button
@@ -667,7 +667,7 @@ export const WithSlotInContext: Story = {
                             </div>
 
                             <div className='flex flex-col gap-2 items-center'>
-                                <span className='text-xs' style={{ color: 'var(--text-color-secondary)' }}>Slot content (drawing-extras)</span>
+                                <span className='text-xs' style={{ color: 'var(--cratis-text-color-secondary)' }}>Slot content (drawing-extras)</span>
                                 <div className='flex gap-2'>
                                     {(['none', 'favorite', 'bookmark'] as const).map(s => (
                                         <button
@@ -725,9 +725,9 @@ export const WithMultipleSlotContributors: Story = {
 
                     <div
                         className='flex flex-col gap-1 p-4 rounded-lg border text-sm'
-                        style={{ borderColor: 'var(--surface-border)', background: 'var(--surface-ground)', color: 'var(--text-color-secondary)' }}
+                        style={{ borderColor: 'var(--cratis-surface-border)', background: 'var(--cratis-surface-ground)', color: 'var(--cratis-text-color-secondary)' }}
                     >
-                        <strong style={{ color: 'var(--text-color)' }}>Three independent contributors</strong>
+                        <strong style={{ color: 'var(--cratis-text-color)' }}>Three independent contributors</strong>
                         <p>Rendered order: B (5) → A (10) → C (20)</p>
                         <ButtonA />
                         <ButtonB />
@@ -809,7 +809,7 @@ export const LayoutForEditorModules: Story = {
                                 { label: 'Review tools', enabled: reviewToolsEnabled, toggle: () => setReviewToolsEnabled(v => !v) },
                             ].map(({ label, enabled, toggle }) => (
                                 <div key={label} className='flex flex-col items-center gap-2'>
-                                    <span className='text-xs' style={{ color: 'var(--text-color-secondary)' }}>{label}</span>
+                                    <span className='text-xs' style={{ color: 'var(--cratis-text-color-secondary)' }}>{label}</span>
                                     <button
                                         type='button'
                                         onClick={toggle}
@@ -907,7 +907,7 @@ export const LayoutWithSmoothEditorTransitions: Story = {
                         </ToolbarSlot>
 
                         <div className='flex flex-col items-center gap-3'>
-                            <span className='text-xs' style={{ color: 'var(--text-color-secondary)' }}>Active editor</span>
+                            <span className='text-xs' style={{ color: 'var(--cratis-text-color-secondary)' }}>Active editor</span>
                             <div className='flex gap-2'>
                                 {(['canvas', 'text', 'schema'] as const).map(editor => (
                                     <button

From d028ffc04746325d94ccb94647f46d43d4a69d08 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:31:39 +0200
Subject: [PATCH 03/23] Add CratisComponentsProvider with merge contract and
 spec
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduce a thin wrapper over PrimeReact's PrimeReactProvider so Cratis has a
single discoverable setup point and a place to layer in defaults later. The
provider deep-merges Cratis-wide defaults with the consumer's value and hands
the result to PrimeReact's context, exposing the full PrimeReact API options
(unstyled, pt, ptOptions, inputStyle, locale, ripple, autoZIndex, …).

`cratisDefaults` is intentionally empty today — it reserves room for future
Cratis-wide opinions without forcing them on consumers now. The pure
`mergeCratisComponentsConfig` helper is exported so the deep-merge contract
can be verified without rendering React, side-stepping the project's
`isolate: false` vitest configuration.
---
 Source/Common/CratisComponentsProvider.tsx    | 61 +++++++++++++++++++
 .../when_merging_user_value.ts                | 35 +++++++++++
 Source/Common/index.ts                        |  1 +
 3 files changed, 97 insertions(+)
 create mode 100644 Source/Common/CratisComponentsProvider.tsx
 create mode 100644 Source/Common/for_mergeCratisComponentsConfig/when_merging_user_value.ts

diff --git a/Source/Common/CratisComponentsProvider.tsx b/Source/Common/CratisComponentsProvider.tsx
new file mode 100644
index 0000000..fe7efc7
--- /dev/null
+++ b/Source/Common/CratisComponentsProvider.tsx
@@ -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 React, { useMemo } from 'react';
+import { PrimeReactProvider } from 'primereact/api';
+import type { APIOptions } from 'primereact/api';
+import { merge } from 'ts-deepmerge';
+
+/**
+ * Configuration accepted by {@link CratisComponentsProvider}. Mirrors PrimeReact's
+ * {@link APIOptions} — the most commonly used members are `unstyled`, `pt`, `ptOptions`,
+ * `inputStyle`, `ripple`, `appendTo`, `zIndex` and `locale`.
+ */
+export type CratisComponentsConfig = Partial<APIOptions>;
+
+export interface CratisComponentsProviderProps {
+    /**
+     * Cratis-wide and PrimeReact pass-through configuration. Merged on top of the
+     * library's defaults and made available to every Cratis component below in the tree.
+     */
+    value?: CratisComponentsConfig;
+
+    children: React.ReactNode;
+}
+
+/**
+ * Default configuration applied to every consumer. Intentionally empty today —
+ * reserved for Cratis-wide opinions we may want to ship in the future (for example,
+ * a default pt preset that complements the --cratis-* token layer). Anything added
+ * here is deep-merged with the consumer's `value` so consumer settings always win.
+ *
+ * Exported so specs can verify the merge contract without re-rendering React.
+ */
+export const cratisDefaults: CratisComponentsConfig = {};
+
+/**
+ * Pure merge of {@link cratisDefaults} and consumer-supplied config. Exposed for
+ * specs; the provider component uses the same logic inside its `useMemo`.
+ */
+export const mergeCratisComponentsConfig = (value: CratisComponentsConfig | undefined): CratisComponentsConfig =>
+    merge(cratisDefaults, value ?? {}) as CratisComponentsConfig;
+
+/**
+ * Single setup point for Cratis Components. Wraps {@link PrimeReactProvider} so the
+ * library can layer Cratis-wide defaults on top of PrimeReact's pass-through and
+ * unstyled mechanisms while still letting the consumer take complete control:
+ *
+ * - Pass `unstyled: true` to disable every PrimeReact base style. The wrappers in
+ *   this package then render structurally only and pick up all visuals from your
+ *   own CSS, Tailwind, or pt definitions.
+ * - Pass `pt` / `ptOptions` to apply global per-component pass-through.
+ *
+ * Consumers who want to talk to PrimeReact directly may still mount
+ * {@link PrimeReactProvider} themselves — this component is an optional convenience,
+ * not a requirement.
+ */
+export const CratisComponentsProvider = ({ value, children }: CratisComponentsProviderProps) => {
+    const merged = useMemo<CratisComponentsConfig>(() => mergeCratisComponentsConfig(value), [value]);
+
+    return <PrimeReactProvider value={merged}>{children}</PrimeReactProvider>;
+};
diff --git a/Source/Common/for_mergeCratisComponentsConfig/when_merging_user_value.ts b/Source/Common/for_mergeCratisComponentsConfig/when_merging_user_value.ts
new file mode 100644
index 0000000..34e1f6d
--- /dev/null
+++ b/Source/Common/for_mergeCratisComponentsConfig/when_merging_user_value.ts
@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { mergeCratisComponentsConfig } from '../CratisComponentsProvider';
+
+describe('when merging user value', () => {
+    const userPt = { dialog: { root: { className: 'consumer-dialog' } } };
+    let withoutValue: Record<string, unknown>;
+    let withValue: Record<string, unknown>;
+
+    beforeEach(() => {
+        withoutValue = mergeCratisComponentsConfig(undefined) as Record<string, unknown>;
+        withValue = mergeCratisComponentsConfig({ unstyled: true, ripple: true, pt: userPt }) as Record<string, unknown>;
+    });
+
+    it('should return an object when no value is given', () => {
+        withoutValue.should.not.be.undefined;
+    });
+
+    it('should pass an empty config when no value is given', () => {
+        Object.keys(withoutValue).should.have.lengthOf(0);
+    });
+
+    it('should forward unstyled from user value', () => {
+        withValue.unstyled!.should.equal(true);
+    });
+
+    it('should forward ripple from user value', () => {
+        withValue.ripple!.should.equal(true);
+    });
+
+    it('should deep-merge pt from user value', () => {
+        withValue.pt!.should.deep.equal(userPt);
+    });
+});
diff --git a/Source/Common/index.ts b/Source/Common/index.ts
index 076e0ab..e73b42c 100644
--- a/Source/Common/index.ts
+++ b/Source/Common/index.ts
@@ -1,6 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+export * from './CratisComponentsProvider';
 export * from './ErrorBoundary';
 export * from './Icon';
 export * from './Page';

From 0fa924512d8d6bec7b75c073e599ac0ccf373610 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:33:01 +0200
Subject: [PATCH 04/23] Replace hard-coded PrimeReact / PrimeFlex class hooks
 and accept className on composites
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Make ObjectContentEditor, ObjectNavigationalBar, SchemaEditor, FormElement,
TypeCell and friends consumer-styleable in unstyled mode by removing every
hard-coded `p-button-text`, `p-button-sm`, `p-button-danger`, `p-error`,
`p-inputgroup`, `border-bottom-1`, and `surface-border` className hook and
replacing each with one of:

- A typed PrimeReact prop on the wrapper (Button `text` / `size` / `severity`).
- An inline style using a `--cratis-*` token (e.g. `var(--cratis-red-500)`
  for inline validation error text replacing `<small className="p-error">`).
- A structural CSS class colocated with the component that uses `--cratis-*`
  tokens (`cratis-form-element__addon`, `cratis-object-navigational-bar`,
  `SchemaEditor.module.css#bottomBorder`).

Add a `className` prop on the composite wrappers (`ObjectContentEditor`,
`ObjectNavigationalBar`, `SchemaEditor`) so consumers can append layout
classes to the root without forking. Fine-grained restyling of the inner
PrimeReact widgets keeps going through the global `pt` preset on
`CratisComponentsProvider`.

A small number of `p-menuitem-link` / `p-menuitem-text` class hooks remain in
SchemaEditor's Menubar custom-template — those are required by PrimeReact's
slot-rendering contract to match the surrounding default-rendered items, so
they have no effect in unstyled mode and stay aligned in themed mode.
---
 Source/Common/FormElement.css                 | 26 ++++++
 Source/Common/FormElement.tsx                 | 28 +++++-
 .../ObjectContentEditor.tsx                   | 86 +++++++++++++------
 .../ObjectNavigationalBar.css                 |  6 ++
 .../ObjectNavigationalBar.tsx                 | 37 +++++++-
 Source/SchemaEditor/SchemaEditor.module.css   |  6 +-
 Source/SchemaEditor/SchemaEditor.tsx          | 86 +++++++++++++++----
 Source/SchemaEditor/TypeCell.tsx              | 14 +--
 8 files changed, 236 insertions(+), 53 deletions(-)
 create mode 100644 Source/Common/FormElement.css
 create mode 100644 Source/ObjectNavigationalBar/ObjectNavigationalBar.css

diff --git a/Source/Common/FormElement.css b/Source/Common/FormElement.css
new file mode 100644
index 0000000..fc67611
--- /dev/null
+++ b/Source/Common/FormElement.css
@@ -0,0 +1,26 @@
+/* Copyright (c) Cratis. All rights reserved. */
+/* Licensed under the MIT license. See LICENSE file in the project root for full license information. */
+
+.cratis-form-element {
+    display: flex;
+    flex: 1 1 auto;
+    align-items: stretch;
+}
+
+.cratis-form-element__addon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0 0.75rem;
+    color: var(--cratis-text-color-secondary);
+    background: var(--cratis-surface-100);
+    border: 1px solid var(--cratis-surface-border);
+    border-right: 0;
+    border-top-left-radius: var(--cratis-border-radius);
+    border-bottom-left-radius: var(--cratis-border-radius);
+}
+
+.cratis-form-element > *:not(.cratis-form-element__addon) {
+    flex: 1 1 auto;
+    min-width: 0;
+}
diff --git a/Source/Common/FormElement.tsx b/Source/Common/FormElement.tsx
index e4c0b10..cbcf457 100644
--- a/Source/Common/FormElement.tsx
+++ b/Source/Common/FormElement.tsx
@@ -1,16 +1,40 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import './FormElement.css';
+
+/**
+ * Props for {@link FormElement}.
+ */
 export interface FormElementProps {
+    /** The form input rendered to the right of the icon addon (typically an `InputText`, `Dropdown`, etc.). */
     children: React.ReactNode;
+
+    /**
+     * Icon node displayed inside the leading addon. Can be any React node —
+     * a PrimeIcons `<i className="pi pi-…" />`, an `<svg>`, or a `react-icons`
+     * component.
+     */
     icon: React.ReactNode;
 }
 
+/**
+ * Lightweight wrapper that places an icon addon to the left of a form input,
+ * styled with the `--cratis-*` token layer (background, border, radius). Use
+ * it to give input fields a leading icon without pulling in PrimeReact's
+ * `InputGroup` chrome.
+ *
+ * ```tsx
+ * <FormElement icon={<i className="pi pi-user" />}>
+ *     <InputText value={name} onChange={…} />
+ * </FormElement>
+ * ```
+ */
 export const FormElement = (props: FormElementProps) => {
     return (
         <div className="flex flex-col md:flex-row gap-3">
-            <div className="p-inputgroup flex-1">
-                <span className="p-inputgroup-addon">
+            <div className="cratis-form-element">
+                <span className="cratis-form-element__addon">
                     {props.icon}
                 </span>
                 {props.children}
diff --git a/Source/ObjectContentEditor/ObjectContentEditor.tsx b/Source/ObjectContentEditor/ObjectContentEditor.tsx
index a23955a..f6c917d 100644
--- a/Source/ObjectContentEditor/ObjectContentEditor.tsx
+++ b/Source/ObjectContentEditor/ObjectContentEditor.tsx
@@ -13,25 +13,63 @@ import { Checkbox } from 'primereact/checkbox';
 import { Calendar } from 'primereact/calendar';
 import { InputTextarea } from 'primereact/inputtextarea';
 
+/**
+ * Props for {@link ObjectContentEditor}.
+ */
 export interface ObjectContentEditorProps {
+    /** The JSON value to display or edit. */
     object: Json;
+
+    /** Optional snapshot timestamp displayed at the bottom of the editor. */
     timestamp?: Date;
+
+    /**
+     * JSON Schema describing the structure of {@link object}. Drives field
+     * detection, label rendering, required-field markers, and per-field input
+     * type selection in edit mode.
+     */
     schema: JsonSchema;
+
     /**
-     * When true, renders editable input fields for each property respecting type/format
+     * When true, renders editable input fields for each property respecting
+     * the JSON Schema's `type` and `format` annotations. Defaults to read-only.
      */
     editMode?: boolean;
+
     /**
-     * Called with the updated object after any field edit
+     * Invoked with the updated object after any field edit. Required to
+     * actually persist user changes when {@link editMode} is true.
      */
     onChange?: (object: Json) => void;
+
     /**
-     * Called when the validation state changes
+     * Invoked whenever the validation state of the editor changes (true when
+     * one or more fields fail their schema check). Useful for disabling a
+     * surrounding Save button while errors are present.
      */
     onValidationChange?: (hasErrors: boolean) => void;
+
+    /**
+     * Extra CSS class names appended to the editor root, combined with the
+     * default `order-content` class. For fine-grained styling of the internal
+     * PrimeReact inputs, use a global `pt` preset on `CratisComponentsProvider`.
+     */
+    className?: string;
 }
 
-export const ObjectContentEditor = ({ object, timestamp, schema, editMode = false, onChange, onValidationChange }: ObjectContentEditorProps) => {
+/**
+ * Renders a structured view (or editor) of any JSON object whose shape is
+ * described by a JSON Schema. In view mode it lays out properties as a labeled
+ * table with breadcrumb-style navigation into nested objects and arrays. In
+ * edit mode it switches to the appropriate input type for each property
+ * (`InputText`, `InputNumber`, `Checkbox`, `Calendar`, `InputTextarea`).
+ *
+ * The component composes many PrimeReact widgets internally; for fine-grained
+ * pass-through styling use a global `pt` preset on `CratisComponentsProvider`.
+ *
+ * @param props - {@link ObjectContentEditorProps}.
+ */
+export const ObjectContentEditor = ({ object, timestamp, schema, editMode = false, onChange, onValidationChange, className }: ObjectContentEditorProps) => {
     const [navigationPath, setNavigationPath] = useState<string[]>([]);
     const [validationErrors, setValidationErrors] = useState<Record<string, string>>({});
 
@@ -144,12 +182,12 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
     };
 
     const rowStyle: React.CSSProperties = {
-        borderBottom: '1px solid var(--surface-border)',
+        borderBottom: '1px solid var(--cratis-surface-border)',
     };
 
     const labelStyle: React.CSSProperties = {
         padding: '8px 12px',
-        color: 'var(--text-color-secondary)',
+        color: 'var(--cratis-text-color-secondary)',
         textAlign: 'left',
         fontWeight: 500,
         width: '140px',
@@ -158,13 +196,13 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
 
     const valueStyle: React.CSSProperties = {
         padding: '8px 12px',
-        color: 'var(--text-color)',
+        color: 'var(--cratis-text-color)',
         textAlign: 'left',
     };
 
     const infoIconStyle: React.CSSProperties = {
         fontSize: '0.875rem',
-        color: 'var(--text-color-secondary)',
+        color: 'var(--cratis-text-color-secondary)',
         flexShrink: 0,
     };
 
@@ -195,7 +233,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
 
         const inputStyle = {
             width: '100%',
-            ...(error ? { borderColor: 'var(--red-500)' } : {})
+            ...(error ? { borderColor: 'var(--cratis-red-500)' } : {})
         };
 
         if (property.type === 'boolean') {
@@ -205,7 +243,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         checked={Boolean(value)}
                         onChange={(e) => handleChange(e.checked ?? false)}
                     />
-                    {error && <small className="p-error">{error}</small>}
+                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
                 </div>
             );
         }
@@ -220,7 +258,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         useGrouping={false}
                         style={inputStyle}
                     />
-                    {error && <small className="p-error">{error}</small>}
+                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
                 </div>
             );
         }
@@ -236,7 +274,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         showIcon
                         style={inputStyle}
                     />
-                    {error && <small className="p-error">{error}</small>}
+                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
                 </div>
             );
         }
@@ -251,14 +289,14 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         showIcon
                         style={inputStyle}
                     />
-                    {error && <small className="p-error">{error}</small>}
+                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
                 </div>
             );
         }
 
         if (property.type === 'array') {
             return (
-                <div className="flex items-center gap-2" style={{ color: 'var(--text-color-secondary)', fontStyle: 'italic' }}>
+                <div className="flex items-center gap-2" style={{ color: 'var(--cratis-text-color-secondary)', fontStyle: 'italic' }}>
                     <span>Array editing not yet supported</span>
                 </div>
             );
@@ -266,7 +304,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
 
         if (property.type === 'object') {
             return (
-                <div className="flex items-center gap-2" style={{ color: 'var(--text-color-secondary)', fontStyle: 'italic' }}>
+                <div className="flex items-center gap-2" style={{ color: 'var(--cratis-text-color-secondary)', fontStyle: 'italic' }}>
                     <span>Object editing not yet supported</span>
                 </div>
             );
@@ -283,7 +321,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         rows={3}
                         style={inputStyle}
                     />
-                    {error && <small className="p-error">{error}</small>}
+                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
                 </div>
             );
         }
@@ -295,7 +333,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                     onChange={(e) => handleChange(e.target.value)}
                     style={inputStyle}
                 />
-                {error && <small className="p-error">{error}</small>}
+                {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
             </div>
         );
     };
@@ -308,7 +346,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                 <div
                     className="flex items-center gap-2 cursor-pointer"
                     onClick={() => navigateToProperty(propertyName)}
-                    style={{ color: 'var(--primary-color)', display: 'flex', alignItems: 'center' }}
+                    style={{ color: 'var(--cratis-primary-color)', display: 'flex', alignItems: 'center' }}
                 >
                     <span>Array[{value.length}]</span>
                     <faIcons.FaArrowRight style={{ fontSize: '0.875rem', display: 'inline-flex' }} />
@@ -321,7 +359,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                 <div
                     className="flex items-center gap-2 cursor-pointer"
                     onClick={() => navigateToProperty(propertyName)}
-                    style={{ color: 'var(--primary-color)', display: 'flex', alignItems: 'center' }}
+                    style={{ color: 'var(--cratis-primary-color)', display: 'flex', alignItems: 'center' }}
                 >
                     <span>Object</span>
                     <faIcons.FaArrowRight style={{ fontSize: '0.875rem', display: 'inline-flex' }} />
@@ -334,7 +372,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
 
     const renderTable = () => {
         if (Array.isArray(currentData)) {
-            if (currentData.length === 0) return <div style={{ padding: '12px', color: 'var(--text-color-secondary)' }}>Empty array</div>;
+            if (currentData.length === 0) return <div style={{ padding: '12px', color: 'var(--cratis-text-color-secondary)' }}>Empty array</div>;
 
             const firstItem = currentData[0];
             if (typeof firstItem === 'object' && firstItem !== null && !Array.isArray(firstItem)) {
@@ -346,7 +384,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                             {currentData.map((item, index) => (
                                 <React.Fragment key={index}>
                                     {index > 0 && (
-                                        <tr style={{ height: '8px', background: 'var(--surface-hover)' }}>
+                                        <tr style={{ height: '8px', background: 'var(--cratis-surface-hover)' }}>
                                             <td colSpan={2}></td>
                                         </tr>
                                     )}
@@ -422,7 +460,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
     };
 
     return (
-        <div className="order-content" style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
+        <div className={className ? `order-content ${className}` : 'order-content'} style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
             <Tooltip target="[data-pr-tooltip]" />
             <ObjectNavigationalBar
                 navigationPath={navigationPath}
@@ -433,10 +471,10 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                 <div style={{
                     marginTop: '20px',
                     padding: '12px',
-                    background: 'var(--highlight-bg)',
+                    background: 'var(--cratis-highlight-bg)',
                     borderRadius: '8px',
                     fontSize: '12px',
-                    color: 'var(--text-color-secondary)'
+                    color: 'var(--cratis-text-color-secondary)'
                 }}>
                     Snapshot captured: {timestamp.toLocaleString()}
                 </div>
diff --git a/Source/ObjectNavigationalBar/ObjectNavigationalBar.css b/Source/ObjectNavigationalBar/ObjectNavigationalBar.css
new file mode 100644
index 0000000..07c6723
--- /dev/null
+++ b/Source/ObjectNavigationalBar/ObjectNavigationalBar.css
@@ -0,0 +1,6 @@
+/* Copyright (c) Cratis. All rights reserved. */
+/* Licensed under the MIT license. See LICENSE file in the project root for full license information. */
+
+.cratis-object-navigational-bar {
+    border-bottom: 1px solid var(--cratis-surface-border);
+}
diff --git a/Source/ObjectNavigationalBar/ObjectNavigationalBar.tsx b/Source/ObjectNavigationalBar/ObjectNavigationalBar.tsx
index 864d977..fd2a2f9 100644
--- a/Source/ObjectNavigationalBar/ObjectNavigationalBar.tsx
+++ b/Source/ObjectNavigationalBar/ObjectNavigationalBar.tsx
@@ -5,27 +5,56 @@ import { useMemo } from 'react';
 import { Button } from 'primereact/button';
 import * as faIcons from 'react-icons/fa6';
 import { buildNavigationBreadcrumbs } from './breadcrumbHelpers';
+import './ObjectNavigationalBar.css';
 
+/**
+ * Props for {@link ObjectNavigationalBar}.
+ */
 export interface ObjectNavigationalBarProps {
+    /**
+     * Ordered list of property keys representing the current navigation depth
+     * into a nested object (e.g. `['shipping', 'address']`). An empty array
+     * means the navigation bar is at the root.
+     */
     navigationPath: string[];
+
+    /**
+     * Invoked when the user clicks a breadcrumb or the back arrow. Receives
+     * the destination index in {@link navigationPath} (`0` means root).
+     */
     onNavigate: (index: number) => void;
+
+    /** Extra CSS class names appended to the navigation bar root. */
+    className?: string;
 }
 
-export function ObjectNavigationalBar({ navigationPath, onNavigate }: ObjectNavigationalBarProps) {
+/**
+ * Breadcrumb-style navigation bar showing the user's path through a nested
+ * object structure, with a back-arrow button and clickable breadcrumb
+ * segments. Pairs with {@link ObjectContentEditor} but can be reused for any
+ * tree-like data exploration UI.
+ *
+ * @param props - {@link ObjectNavigationalBarProps}.
+ */
+export function ObjectNavigationalBar({ navigationPath, onNavigate, className }: ObjectNavigationalBarProps) {
     const breadcrumbItems = useMemo(() => buildNavigationBreadcrumbs(navigationPath), [navigationPath]);
+    const rootClassName = className
+        ? `cratis-object-navigational-bar px-4 py-2 mb-2 ${className}`
+        : 'cratis-object-navigational-bar px-4 py-2 mb-2';
 
     return (
-        <div className="px-4 py-2 mb-2 border-bottom-1 surface-border">
+        <div className={rootClassName}>
             <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
                 <Button
                     icon={<faIcons.FaArrowLeft />}
-                    className="p-button-text p-button-sm"
+                    text
+                    size="small"
                     onClick={() => onNavigate(navigationPath.length - 1)}
                     tooltip="Navigate back"
                     tooltipOptions={{ position: 'top' }}
                     disabled={navigationPath.length === 0}
                 />
-                <div style={{ fontSize: '0.9rem', color: 'var(--text-color-secondary)' }}>
+                <div style={{ fontSize: '0.9rem', color: 'var(--cratis-text-color-secondary)' }}>
                     {breadcrumbItems.map((item, index) => (
                         <span key={index}>
                             {index > 0 && <span className="mx-2">&gt;</span>}
diff --git a/Source/SchemaEditor/SchemaEditor.module.css b/Source/SchemaEditor/SchemaEditor.module.css
index 83b78ee..d529e7d 100644
--- a/Source/SchemaEditor/SchemaEditor.module.css
+++ b/Source/SchemaEditor/SchemaEditor.module.css
@@ -7,5 +7,9 @@
 }
 
 .navigableRow:hover {
-    background-color: var(--surface-hover) !important;
+    background-color: var(--cratis-surface-hover) !important;
+}
+
+.bottomBorder {
+    border-bottom: 1px solid var(--cratis-surface-border);
 }
diff --git a/Source/SchemaEditor/SchemaEditor.tsx b/Source/SchemaEditor/SchemaEditor.tsx
index ae24517..e1d1af7 100644
--- a/Source/SchemaEditor/SchemaEditor.tsx
+++ b/Source/SchemaEditor/SchemaEditor.tsx
@@ -16,32 +16,83 @@ import { validatePropertyName, buildBreadcrumbItems } from './schemaHelpers';
 import css from './SchemaEditor.module.css';
 import { MenuItem } from 'primereact/menuitem';
 
+/**
+ * Props for {@link SchemaEditor}.
+ */
 export interface SchemaEditorProps {
+    /** The JSON Schema being viewed or edited. */
     schema: JsonSchema;
+
+    /** Optional event-type label displayed in the editor header. */
     eventTypeName?: string;
+
+    /** When false, the Edit action is hidden; defaults to `true`. */
     canEdit?: boolean;
+
+    /**
+     * When {@link canEdit} is false, this string is shown as a tooltip on the
+     * disabled Edit menu item to explain why editing is unavailable.
+     */
     canNotEditReason?: string;
+
+    /** Invoked with the updated schema after any structural change. */
     onChange?: (schema: JsonSchema) => void;
+
+    /** Invoked when the user activates the Save action. */
     onSave?: () => void;
+
+    /** Invoked when the user activates the Cancel action. */
     onCancel?: () => void;
+
+    /** Initial edit-mode state; defaults to `false` (read-only). */
     editMode?: boolean;
+
+    /** When true, hides the Save menu item even while in edit mode. */
     saveDisabled?: boolean;
+
+    /** When true, hides the Cancel menu item even while in edit mode. */
     cancelDisabled?: boolean;
+
+    /**
+     * Override the list of selectable type formats per JSON Schema type. Each
+     * entry contributes options to the type-format dropdown shown in edit
+     * mode. Defaults to {@link DEFAULT_TYPE_FORMATS}.
+     */
     typeFormats?: TypeFormat[];
+
+    /**
+     * Extra CSS class names appended to the editor root. Combined with the
+     * default `schema-editor` class. For fine-grained styling of internal
+     * PrimeReact components, use a global `pt` preset on `CratisComponentsProvider`.
+     */
+    className?: string;
 }
 
-export const SchemaEditor = ({ 
-    schema, 
-    eventTypeName = '', 
-    canEdit = true, 
-    canNotEditReason, 
-    onChange, 
-    onSave, 
-    onCancel, 
-    editMode, 
-    saveDisabled = false, 
+/**
+ * A breadcrumb-navigated editor for JSON Schemas. Lets users browse nested
+ * `object` and `array` property definitions, add or remove properties, change
+ * types and formats, and validate naming rules in place. Designed to drive
+ * UIs around event payload schemas and similar structural documents.
+ *
+ * The editor composes a PrimeReact `DataTable`, `Menubar`, and several form
+ * widgets internally; for restyling, use a global `pt` preset on
+ * `CratisComponentsProvider`.
+ *
+ * @param props - {@link SchemaEditorProps}.
+ */
+export const SchemaEditor = ({
+    schema,
+    eventTypeName = '',
+    canEdit = true,
+    canNotEditReason,
+    onChange,
+    onSave,
+    onCancel,
+    editMode,
+    saveDisabled = false,
     cancelDisabled = false,
-    typeFormats = DEFAULT_TYPE_FORMATS
+    typeFormats = DEFAULT_TYPE_FORMATS,
+    className
 }: SchemaEditorProps) => {
     const [currentPath, setCurrentPath] = useState<string[]>([]);
     const [properties, setProperties] = useState<JsonSchemaProperty[]>([]);
@@ -339,7 +390,7 @@ export const SchemaEditor = ({
     const currentDescription = getCurrentDescription();
 
     return (
-        <div className="schema-editor" style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
+        <div className={className ? `schema-editor ${className}` : 'schema-editor'} style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
             <div className="px-4 py-4">
                 <Tooltip target="[data-pr-tooltip]" />
                 <div className="schema-editor-menubar">
@@ -347,17 +398,18 @@ export const SchemaEditor = ({
                 </div>
             </div>
 
-            <div className="px-4 py-2 border-bottom-1 surface-border">
+            <div className={`px-4 py-2 ${css.bottomBorder}`}>
                 <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
                     <Button
                         icon={<faIcons.FaArrowLeft />}
-                        className="p-button-text p-button-sm"
+                        text
+                        size="small"
                         onClick={navigateBack}
                         disabled={isAtRoot}
                         tooltip="Navigate back"
                         tooltipOptions={{ position: 'top' }}
                     />
-                    <div style={{ fontSize: '0.9rem', color: 'var(--text-color-secondary)', cursor: 'pointer' }}>
+                    <div style={{ fontSize: '0.9rem', color: 'var(--cratis-text-color-secondary)', cursor: 'pointer' }}>
                         {breadcrumbItems.map((item, index) => (
                             <span key={index}>
                                 {index > 0 && <span className="mx-2">&gt;</span>}
@@ -372,7 +424,7 @@ export const SchemaEditor = ({
                     </div>
                 </div>
                 {currentDescription && (
-                    <div style={{ fontSize: '0.875rem', color: 'var(--text-color-secondary)', marginTop: '0.5rem', marginLeft: '2.5rem', fontStyle: 'italic', display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
+                    <div style={{ fontSize: '0.875rem', color: 'var(--cratis-text-color-secondary)', marginTop: '0.5rem', marginLeft: '2.5rem', fontStyle: 'italic', display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
                         <faIcons.FaCircleInfo />
                         <span>{currentDescription}</span>
                     </div>
@@ -407,7 +459,7 @@ export const SchemaEditor = ({
                     }}
                     pt={{
                         root: { style: { border: 'none' } },
-                        tbody: { style: { borderTop: '1px solid var(--surface-border)' } }
+                        tbody: { style: { borderTop: '1px solid var(--cratis-surface-border)' } }
                     }}
                 >
                     <Column
diff --git a/Source/SchemaEditor/TypeCell.tsx b/Source/SchemaEditor/TypeCell.tsx
index 652c961..5893117 100644
--- a/Source/SchemaEditor/TypeCell.tsx
+++ b/Source/SchemaEditor/TypeCell.tsx
@@ -104,7 +104,7 @@ export const TypeCell = ({
                         <>
                             <div style={{ flex: 1 }} />
                             <span style={{ display: 'flex', alignItems: 'center' }}>
-                                <faIcons.FaArrowRight style={{ fontSize: '1rem', color: 'var(--primary-color)' }} />
+                                <faIcons.FaArrowRight style={{ fontSize: '1rem', color: 'var(--cratis-primary-color)' }} />
                             </span>
                         </>
                     )}
@@ -121,7 +121,7 @@ export const TypeCell = ({
                     <span>Object</span>
                     <div style={{ flex: 1 }} />
                     <span style={{ display: 'flex', alignItems: 'center' }}>
-                        <faIcons.FaArrowRight style={{ fontSize: '1rem', color: 'var(--primary-color)' }} />
+                        <faIcons.FaArrowRight style={{ fontSize: '1rem', color: 'var(--cratis-primary-color)' }} />
                     </span>
                 </div>
             );
@@ -152,7 +152,8 @@ export const TypeCell = ({
                 {rowData.type === 'array' && rowData.items?.type === 'object' && rowData.name && (
                     <Button
                         icon={<faIcons.FaArrowRight />}
-                        className="p-button-text p-button-sm"
+                        text
+                        size="small"
                         onClick={() => onNavigateToArrayItems(rowData.name!)}
                         tooltip="Navigate to item definition"
                         tooltipOptions={{ position: 'top' }}
@@ -161,7 +162,8 @@ export const TypeCell = ({
                 {rowData.type === 'object' && rowData.name && (
                     <Button
                         icon={<faIcons.FaArrowRight />}
-                        className="p-button-text p-button-sm"
+                        text
+                        size="small"
                         onClick={() => onNavigateToProperty(rowData.name!)}
                         tooltip="Navigate to object properties"
                         tooltipOptions={{ position: 'top' }}
@@ -170,7 +172,9 @@ export const TypeCell = ({
                 {rowData.name && (
                     <Button
                         icon={<faIcons.FaTrash />}
-                        className="p-button-text p-button-danger p-button-sm"
+                        text
+                        severity="danger"
+                        size="small"
                         onClick={() => onRemoveProperty(rowData.name!)}
                         tooltip="Delete property"
                         tooltipOptions={{ position: 'top' }}

From 197769afc6e29dfb5c59ac236a1afe8a73e6388c Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:34:27 +0200
Subject: [PATCH 05/23] Forward pt / ptOptions / unstyled / className on Dialog
 wrappers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add pass-through pt/ptOptions/unstyled and className on Dialog and
CommandDialog so consumers can fully restyle (or unstyle) the underlying
PrimeReact Dialog without forking. The props plumb straight through to
PrimeDialog with no transformation.

For StepperCommandDialog — which renders both a Dialog and a Stepper — keep
the inherited `pt`/`ptOptions`/`unstyled` targeting the Stepper (matching
StepperCustomizationProps) and add explicit `dialogPt`/`dialogPtOptions`/
`dialogUnstyled`/`dialogClassName` siblings for the outer Dialog. This makes
each slot independently styleable and matches the convention introduced
elsewhere for multi-slot composites.

BusyIndicatorDialog only documents its behavior — per-instance pt is not
exposed because its request type is owned by `@cratis/arc.react`. Consumers
restyle it via the global pt preset on CratisComponentsProvider.
---
 Source/CommandDialog/CommandDialog.tsx        |  58 +++++++
 Source/CommandDialog/StepperCommandDialog.tsx |  70 +++++++++
 Source/Dialogs/BusyIndicatorDialog.tsx        |  22 ++-
 Source/Dialogs/Dialog.tsx                     | 148 ++++++++++++++++--
 4 files changed, 285 insertions(+), 13 deletions(-)

diff --git a/Source/CommandDialog/CommandDialog.tsx b/Source/CommandDialog/CommandDialog.tsx
index 0f0faa3..f6cf258 100644
--- a/Source/CommandDialog/CommandDialog.tsx
+++ b/Source/CommandDialog/CommandDialog.tsx
@@ -13,9 +13,23 @@ import {
     type CommandFormProps
 } from '@cratis/arc.react/commands';
 
+/**
+ * Props for {@link CommandDialog}. Combines the props of a `CommandForm`
+ * (`command`, `initialValues`, `onSuccess`, `onValidationFailure`, `onFailed`,
+ * `onBeforeExecute`, etc.) with the props of a {@link Dialog} (`title`,
+ * `buttons`, `width`, `pt`, `unstyled`, …).
+ *
+ * @typeParam TCommand - The command record type (must extend `object`).
+ * @typeParam TResponse - The response payload type returned by a successful command. Defaults to `object`.
+ */
 export interface CommandDialogProps<TCommand extends object, TResponse = object>
     extends Omit<CommandFormProps<TCommand, TResponse>, 'children'>,
         Omit<DialogProps, 'children'> {
+    /**
+     * Form fields and arbitrary content for the dialog body. Children that are
+     * `CommandFormField` instances are automatically wrapped so they bind to
+     * the command instance.
+     */
     children?: React.ReactNode;
 }
 
@@ -39,6 +53,10 @@ const CommandDialogWrapper = <TCommand extends object, TResponse = object>({
     onValidationFailure,
     onFailed,
     onBeforeExecute,
+    className,
+    pt,
+    ptOptions,
+    unstyled,
     children
 }: {
     title: string;
@@ -60,6 +78,10 @@ const CommandDialogWrapper = <TCommand extends object, TResponse = object>({
     onValidationFailure?: CommandFormProps<TCommand, TResponse>['onValidationFailure'];
     onFailed?: CommandFormProps<TCommand, TResponse>['onFailed'];
     onBeforeExecute?: (values: TCommand) => TCommand;
+    className?: DialogProps['className'];
+    pt?: DialogProps['pt'];
+    ptOptions?: DialogProps['ptOptions'];
+    unstyled?: DialogProps['unstyled'];
     children?: React.ReactNode;
 }) => {
     const { setCommandValues, setCommandResult, isValid: isCommandFormValid } = useCommandFormContext<TCommand>();
@@ -147,6 +169,10 @@ const CommandDialogWrapper = <TCommand extends object, TResponse = object>({
             noLabel={noLabel}
             isValid={isDialogValid}
             isBusy={isBusy}
+            className={className}
+            pt={pt}
+            ptOptions={ptOptions}
+            unstyled={unstyled}
         >
             <div style={{ display: 'flex', flexDirection: 'column', width: '100%' }}>
                 {processedChildren}
@@ -155,6 +181,30 @@ const CommandDialogWrapper = <TCommand extends object, TResponse = object>({
     );
 };
 
+/**
+ * A {@link Dialog} that wraps a `CommandForm`, executes the bound command on
+ * confirm, and closes only when the command succeeds. While the command is
+ * running the dialog enters a busy state and disables its action buttons; on
+ * validation or execution failure it stays open and propagates the result to
+ * the form so field-level errors render automatically.
+ *
+ * Children that are `CommandFormField` instances bind to the command's
+ * properties via the `value` accessor (`value={c => c.name}`); arbitrary
+ * non-field children are rendered as plain content.
+ *
+ * ```tsx
+ * <CommandDialog<RegisterAuthor> title="Register author"
+ *                                command={RegisterAuthor}
+ *                                onSuccess={onCreated}>
+ *     <InputTextField value={c => c.name} title="Name" />
+ *     <InputTextField value={c => c.email} title="Email" />
+ * </CommandDialog>
+ * ```
+ *
+ * @typeParam TCommand - The command record type. Defaults to `object`.
+ * @typeParam TResponse - The success payload type. Defaults to `object`.
+ * @param props - {@link CommandDialogProps}.
+ */
 const CommandDialogComponent = <TCommand extends object = object, TResponse = object>(props: CommandDialogProps<TCommand, TResponse>) => {
     const {
         title,
@@ -172,6 +222,10 @@ const CommandDialogComponent = <TCommand extends object = object, TResponse = ob
         onClose,
         onConfirm,
         onCancel,
+        className,
+        pt,
+        ptOptions,
+        unstyled,
         children,
         ...commandFormProps
     } = props;
@@ -198,6 +252,10 @@ const CommandDialogComponent = <TCommand extends object = object, TResponse = ob
                 onValidationFailure={props.onValidationFailure}
                 onFailed={props.onFailed}
                 onBeforeExecute={commandFormProps.onBeforeExecute}
+                className={className}
+                pt={pt}
+                ptOptions={ptOptions}
+                unstyled={unstyled}
             >
                 {children}
             </CommandDialogWrapper>
diff --git a/Source/CommandDialog/StepperCommandDialog.tsx b/Source/CommandDialog/StepperCommandDialog.tsx
index 407e081..6250113 100644
--- a/Source/CommandDialog/StepperCommandDialog.tsx
+++ b/Source/CommandDialog/StepperCommandDialog.tsx
@@ -15,6 +15,18 @@ import {
 import type { CloseDialog, ConfirmCallback, CancelCallback } from '../Dialogs/Dialog';
 import { CommandStepperContent, type StepperCustomizationProps } from './CommandStepper';
 
+/**
+ * Props for {@link StepperCommandDialog}. Combines the command-form props,
+ * the stepper customization props (`orientation`, `headerPosition`, `linear`,
+ * `pt`, …), and dialog-specific props for the outer modal.
+ *
+ * The Stepper customization props (`pt`/`ptOptions`/`unstyled`) target the
+ * inner Stepper. To customize the outer Dialog use `dialogPt`, `dialogPtOptions`,
+ * `dialogUnstyled`, and `dialogClassName`.
+ *
+ * @typeParam TCommand - The command record type.
+ * @typeParam TResponse - The response payload type returned by a successful command.
+ */
 export interface StepperCommandDialogProps<TCommand extends object, TResponse = object>
     extends Omit<CommandFormProps<TCommand, TResponse>, 'children'>,
         StepperCustomizationProps {
@@ -44,6 +56,17 @@ export interface StepperCommandDialogProps<TCommand extends object, TResponse =
     nextLabel?: string;
     /** Label for the previous step button. Defaults to `'Previous'`. */
     previousLabel?: string;
+    /**
+     * Extra CSS class name forwarded to the underlying PrimeReact Dialog root.
+     * Use the inherited `pt`/`ptOptions`/`unstyled` props to customize the Stepper.
+     */
+    dialogClassName?: string;
+    /** PrimeReact pass-through configuration applied to the outer Dialog. */
+    dialogPt?: PrimeDialogProps['pt'];
+    /** PrimeReact pass-through options applied to the outer Dialog. */
+    dialogPtOptions?: PrimeDialogProps['ptOptions'];
+    /** When true, disables every base PrimeReact style on the outer Dialog. */
+    dialogUnstyled?: boolean;
     /** StepperPanel children defining each wizard step. */
     children?: React.ReactNode;
 }
@@ -75,6 +98,10 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
     pt,
     ptOptions,
     unstyled,
+    dialogClassName,
+    dialogPt,
+    dialogPtOptions,
+    dialogUnstyled,
     children
 }: {
     title: string;
@@ -94,6 +121,10 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
     okLabel?: string;
     nextLabel?: string;
     previousLabel?: string;
+    dialogClassName?: string;
+    dialogPt?: PrimeDialogProps['pt'];
+    dialogPtOptions?: PrimeDialogProps['ptOptions'];
+    dialogUnstyled?: boolean;
     children?: React.ReactNode;
 } & StepperCustomizationProps) => {
     const { setCommandValues, setCommandResult, isValid: isCommandFormValid, getFieldError } = useCommandFormContext<TCommand>();
@@ -230,6 +261,10 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
             contentStyle={contentStyle}
             resizable={resizable}
             closable
+            className={dialogClassName}
+            pt={dialogPt}
+            ptOptions={dialogPtOptions}
+            unstyled={dialogUnstyled}
         >
             <CommandStepperContent
                 activeStep={activeStep}
@@ -256,6 +291,33 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
     );
 };
 
+/**
+ * A multi-step wizard dialog backed by a single Cratis command. Wraps PrimeReact's
+ * `Stepper` inside a Cratis `Dialog`, tracks per-step visit state, surfaces
+ * inline error indicators on steps with invalid fields, and executes the bound
+ * command when the user submits the last step.
+ *
+ * Use it when one command needs to be split into named stages that the user can
+ * navigate forward and backward through. For single-stage commands, use
+ * {@link CommandDialog} instead.
+ *
+ * ```tsx
+ * <StepperCommandDialog<RegisterOrder> command={RegisterOrder}
+ *                                       title="New order"
+ *                                       onSuccess={onCreated}>
+ *     <StepperPanel header="Customer">
+ *         <InputTextField value={c => c.customerName} title="Name" />
+ *     </StepperPanel>
+ *     <StepperPanel header="Items">
+ *         <ChipsField value={c => c.items} title="Items" />
+ *     </StepperPanel>
+ * </StepperCommandDialog>
+ * ```
+ *
+ * @typeParam TCommand - The command record type. Defaults to `object`.
+ * @typeParam TResponse - The success payload type. Defaults to `object`.
+ * @param props - {@link StepperCommandDialogProps}.
+ */
 const StepperCommandDialogComponent = <TCommand extends object = object, TResponse = object>(
     props: StepperCommandDialogProps<TCommand, TResponse>
 ) => {
@@ -282,6 +344,10 @@ const StepperCommandDialogComponent = <TCommand extends object = object, TRespon
         pt,
         ptOptions,
         unstyled,
+        dialogClassName,
+        dialogPt,
+        dialogPtOptions,
+        dialogUnstyled,
         children,
         ...commandFormProps
     } = props;
@@ -315,6 +381,10 @@ const StepperCommandDialogComponent = <TCommand extends object = object, TRespon
                 pt={pt}
                 ptOptions={ptOptions}
                 unstyled={unstyled}
+                dialogClassName={dialogClassName}
+                dialogPt={dialogPt}
+                dialogPtOptions={dialogPtOptions}
+                dialogUnstyled={dialogUnstyled}
             >
                 {children}
             </StepperCommandDialogWrapper>
diff --git a/Source/Dialogs/BusyIndicatorDialog.tsx b/Source/Dialogs/BusyIndicatorDialog.tsx
index 32d5f71..96c1185 100644
--- a/Source/Dialogs/BusyIndicatorDialog.tsx
+++ b/Source/Dialogs/BusyIndicatorDialog.tsx
@@ -5,11 +5,27 @@ import { BusyIndicatorDialogRequest } from '@cratis/arc.react/dialogs';
 import { ProgressSpinner } from 'primereact/progressspinner';
 import { Dialog } from './Dialog';
 
+/**
+ * Modal "busy" dialog used by the `@cratis/arc.react` dialog host when a
+ * long-running operation needs to block user interaction. Renders a spinner
+ * and a message, with no confirm/cancel buttons.
+ *
+ * The component is consumed by the dialog host machinery — applications do
+ * not instantiate it directly. To trigger one, call the host's
+ * `showBusyIndicator(...)` helper, which internally constructs a
+ * {@link BusyIndicatorDialogRequest} and renders this component.
+ *
+ * Styling is controlled globally via the `pt` / `unstyled` settings on
+ * `CratisComponentsProvider`. Per-instance pass-through is not exposed
+ * because the request type lives in `@cratis/arc.react`.
+ *
+ * @param props - The request from the dialog host, including `title` and `message`.
+ */
 export const BusyIndicatorDialog = (props: BusyIndicatorDialogRequest) => {
     return (
-        <Dialog 
-            title={props.title} 
-            visible={true} 
+        <Dialog
+            title={props.title}
+            visible={true}
             onCancel={() => undefined}
             buttons={null}
         >
diff --git a/Source/Dialogs/Dialog.tsx b/Source/Dialogs/Dialog.tsx
index b25627c..633312e 100644
--- a/Source/Dialogs/Dialog.tsx
+++ b/Source/Dialogs/Dialog.tsx
@@ -6,48 +6,172 @@ import { Button } from 'primereact/button';
 import { DialogResult, DialogButtons, useDialogContext } from '@cratis/arc.react/dialogs';
 import { ReactNode } from 'react';
 
+/**
+ * Callback used by {@link Dialog} (and its wrappers) when the dialog is about to
+ * close. Returning `false` (sync or via promise) keeps the dialog open — useful
+ * for confirming or surfacing an error to the user before letting it close.
+ */
 export type CloseDialog = (result: DialogResult) => boolean | void | Promise<boolean> | Promise<void>;
+
+/**
+ * Callback invoked when the user activates the confirm action (Ok / Yes).
+ * Return `false` (sync or via promise) to keep the dialog open after the
+ * confirm callback completes.
+ */
 export type ConfirmCallback = () => boolean | void | Promise<boolean> | Promise<void>;
+
+/**
+ * Callback invoked when the user activates the cancel / dismiss action.
+ * Return `false` to keep the dialog open after the cancel callback completes.
+ */
 export type CancelCallback = () => boolean | void | Promise<boolean> | Promise<void>;
 
+/**
+ * Props for {@link Dialog}.
+ */
 export interface DialogProps {
+    /** Header text shown at the top of the dialog. */
     title: string;
+
+    /** Controls visibility. Defaults to `true`; set to `false` to hide without unmounting. */
     visible?: boolean;
+
+    /**
+     * Catch-all close callback invoked for both confirm and cancel paths when no
+     * matching {@link onConfirm} / {@link onCancel} handler is supplied. Receives
+     * the {@link DialogResult} the user produced.
+     */
     onClose?: CloseDialog;
+
+    /** Invoked when the user activates the confirm action (Ok / Yes). */
     onConfirm?: ConfirmCallback;
+
+    /** Invoked when the user activates the cancel / dismiss action. */
     onCancel?: CancelCallback;
+
+    /**
+     * Footer button configuration. Pass a {@link DialogButtons} value for one of
+     * the predefined sets (`Ok`, `OkCancel`, `YesNo`, `YesNoCancel`), `null` for
+     * no footer, or a custom React node to fully render your own footer.
+     * Defaults to `DialogButtons.OkCancel`.
+     */
     buttons?: DialogButtons | ReactNode;
+
+    /** Dialog body content. */
     children: ReactNode;
+
+    /** Dialog width, any valid CSS length. Defaults to `'450px'`. */
     width?: string;
+
+    /** Inline style forwarded to the underlying PrimeReact Dialog root. */
     style?: PrimeDialogProps['style'];
+
+    /** Inline style forwarded to the dialog's inner content area. */
     contentStyle?: PrimeDialogProps['contentStyle'];
+
+    /** When true, allows the user to resize the dialog. Defaults to `false`. */
     resizable?: boolean;
+
+    /**
+     * Controls whether the confirm button is enabled. Defaults to `true` when
+     * omitted; set to `false` to disable confirm (e.g. when form validation
+     * fails).
+     */
     isValid?: boolean;
+
+    /**
+     * When true, disables all dialog buttons and shows a loading state on the
+     * confirm button. Used by command-executing wrappers while a command runs.
+     */
     isBusy?: boolean;
+
+    /** Override the Ok button label. Defaults to `'Ok'`. */
     okLabel?: string;
+
+    /** Override the Cancel button label. Defaults to `'Cancel'`. */
     cancelLabel?: string;
+
+    /** Override the Yes button label. Defaults to `'Yes'`. */
     yesLabel?: string;
+
+    /** Override the No button label. Defaults to `'No'`. */
     noLabel?: string;
+
+    /**
+     * Extra CSS class names forwarded to the underlying PrimeReact Dialog root.
+     */
+    className?: string;
+
+    /**
+     * PrimeReact pass-through configuration. Applies to the underlying Dialog's
+     * slots — see PrimeReact's Dialog `pt` reference for the available keys.
+     * Use this (or set a global preset on `CratisComponentsProvider`) to take
+     * full control of styling.
+     */
+    pt?: PrimeDialogProps['pt'];
+
+    /**
+     * PrimeReact pass-through options. Controls merge vs. replace behavior for
+     * the {@link pt} preset.
+     */
+    ptOptions?: PrimeDialogProps['ptOptions'];
+
+    /**
+     * When true, disables every base PrimeReact style on the underlying Dialog.
+     * Combine with {@link pt} or with the global setting from
+     * `CratisComponentsProvider` to fully restyle.
+     */
+    unstyled?: boolean;
 }
 
-export const Dialog = ({ 
-    title, 
-    visible = true, 
-    onClose, 
+/**
+ * Cratis wrapper around PrimeReact's `Dialog` that provides:
+ *
+ * - A typed footer-button enum (`DialogButtons.Ok` / `OkCancel` / `YesNo` /
+ *   `YesNoCancel`) with localizable labels.
+ * - A confirm/cancel callback contract (`onConfirm`, `onCancel`, `onClose`)
+ *   where returning `false` keeps the dialog open — useful for surfacing
+ *   inline command failures.
+ * - A busy state that disables actions and shows a loading indicator on the
+ *   confirm button while a command runs.
+ * - Pass-through of `pt`, `ptOptions`, `unstyled`, and `className` to the
+ *   underlying PrimeReact Dialog so consumers can fully restyle it.
+ * - Automatic integration with `@cratis/arc.react`'s `DialogContext` when
+ *   used inside a `<DialogHost>` — the dialog closes through the host on
+ *   confirm/cancel without manual wiring.
+ *
+ * ```tsx
+ * <Dialog title="Delete project?" buttons={DialogButtons.YesNo}
+ *         onConfirm={() => deleteProject(id)}>
+ *     This action cannot be undone.
+ * </Dialog>
+ * ```
+ *
+ * @param props - {@link DialogProps}.
+ */
+
+export const Dialog = ({
+    title,
+    visible = true,
+    onClose,
     onConfirm,
     onCancel,
-    buttons = DialogButtons.OkCancel, 
-    children, 
-    width = '450px', 
+    buttons = DialogButtons.OkCancel,
+    children,
+    width = '450px',
     style,
     contentStyle,
-    resizable = false, 
+    resizable = false,
     isValid,
     isBusy = false,
     okLabel = 'Ok',
     cancelLabel = 'Cancel',
     yesLabel = 'Yes',
-    noLabel = 'No'
+    noLabel = 'No',
+    className,
+    pt,
+    ptOptions,
+    unstyled
 }: DialogProps) => {
     // useDialogContext() is called unconditionally on every render — the try/catch only suppresses
     // the exception when Dialog is used standalone (outside a provider). React's Rules of Hooks
@@ -159,7 +283,11 @@ export const Dialog = ({
             style={{ width, ...style }}
             contentStyle={contentStyle}
             resizable={resizable}
-            closable={typeof buttons === 'number'}>
+            closable={typeof buttons === 'number'}
+            className={className}
+            pt={pt}
+            ptOptions={ptOptions}
+            unstyled={unstyled}>
             {children}
         </PrimeDialog>
     );

From 48b7ec4c31142d7a33cedcecdb0c4b14341a46a7 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:36:50 +0200
Subject: [PATCH 06/23] Forward pt / ptOptions / unstyled / className on
 DataPage and DataTables

Open up DataPage, DataTableForQuery, and DataTableForObservableQuery for
consumer restyling.

The DataTable wrappers forward `pt`/`ptOptions`/`unstyled`/`className` to
the underlying PrimeReact DataTable plus a sibling set of
`paginatorPt`/`paginatorPtOptions`/`paginatorUnstyled` for the inner
Paginator.

DataPage composes both a DataTable and a Menubar, so it exposes per-slot
props mirroring the slot pattern: `tablePt` / `tablePtOptions` / `tableUnstyled`
/ `tableClassName` for the data table, and `menubarPt` / `menubarPtOptions` /
`menubarUnstyled` / `menubarClassName` for the action Menubar. The inner
`Columns` and `MenuItems` components read these from the surrounding
DataPage context and forward them to the appropriate primitive.

Border colors that were previously inline-styled with `var(--surface-border)`
are migrated to `var(--cratis-surface-border)` so consumer overrides take
effect alongside the new pt forwarding.
---
 Source/DataPage/DataPage.tsx                  | 142 ++++++++++++++++--
 .../DataTableForObservableQuery.tsx           |  67 +++++++--
 Source/DataTables/DataTableForQuery.tsx       |  66 ++++++--
 3 files changed, 246 insertions(+), 29 deletions(-)

diff --git a/Source/DataPage/DataPage.tsx b/Source/DataPage/DataPage.tsx
index 8835fd9..91f861c 100644
--- a/Source/DataPage/DataPage.tsx
+++ b/Source/DataPage/DataPage.tsx
@@ -5,33 +5,62 @@ import { ReactNode, useMemo } from 'react';
 import { Page } from '../Common/Page';
 import React from 'react';
 import { MenuItem as PrimeMenuItem } from 'primereact/menuitem';
-import { Menubar } from 'primereact/menubar';
+import { Menubar, type MenubarProps } from 'primereact/menubar';
 import { IObservableQueryFor, IQueryFor, QueryFor } from '@cratis/arc/queries';
 import { DataTableForObservableQuery } from '../DataTables/DataTableForObservableQuery';
-import { DataTableFilterMeta, DataTableSelectionSingleChangeEvent } from 'primereact/datatable';
+import { DataTableFilterMeta, DataTableSelectionSingleChangeEvent, type DataTableProps as PrimeDataTableProps } from 'primereact/datatable';
 import { DataTableForQuery } from '../DataTables/DataTableForQuery';
 import { Allotment } from 'allotment';
 import { Constructor } from '@cratis/fundamentals';
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+/**
+ * Props for {@link MenuItem}. Extends PrimeReact's `MenuItem` shape with one
+ * Cratis-specific flag.
+ */
 export interface MenuItemProps extends PrimeMenuItem {
+    /**
+     * When true, the menu item is disabled while no row is selected in the
+     * surrounding {@link DataPage}. Use it for context-sensitive actions like
+     * "Edit" or "Delete" that require a selection.
+     */
     disableOnUnselected?: boolean;
 }
 
+/**
+ * Declarative menu item for use inside `<DataPage.MenuItems>`. Renders nothing
+ * directly; the surrounding {@link MenuItems} component reads its props and
+ * forwards them to the action `Menubar`.
+ */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export const MenuItem = (_: MenuItemProps) => {
     return null;
 };
 
+/**
+ * Props for {@link MenuItems}.
+ */
 export interface MenuItemsProps {
+    /** One or more `<DataPage.MenuItem>` elements. */
     children: ReactNode;
 }
 
+/**
+ * Props for {@link Columns}.
+ */
 export interface ColumnProps {
+    /** PrimeReact `<Column>` elements describing each visible column. */
     children: ReactNode;
 }
 
+/**
+ * Renders an action `Menubar` at the top of a {@link DataPage}, populated from
+ * `<DataPage.MenuItem>` children. Each menu item's `disableOnUnselected` flag
+ * is automatically honored against the current row selection.
+ *
+ * Use as `<DataPage.MenuItems>` inside a `<DataPage>`.
+ */
 export const MenuItems = ({ children }: MenuItemsProps) => {
     const context = useDataPageContext();
 
@@ -56,10 +85,26 @@ export const MenuItems = ({ children }: MenuItemsProps) => {
 
     return (
         <div className="px-4 py-2">
-            <Menubar aria-label="Actions" model={items} />
+            <Menubar
+                aria-label="Actions"
+                model={items}
+                className={context.menubarClassName}
+                pt={context.menubarPt}
+                ptOptions={context.menubarPtOptions}
+                unstyled={context.menubarUnstyled}
+            />
         </div>);
 };
 
+/**
+ * Renders the data table at the body of a {@link DataPage}. Automatically
+ * selects between {@link DataTableForQuery} (snapshot query) and
+ * {@link DataTableForObservableQuery} (real-time observable) based on the
+ * `query` type provided to the surrounding `<DataPage>`.
+ *
+ * Use as `<DataPage.Columns>` inside a `<DataPage>`, with PrimeReact `<Column>`
+ * children defining the table columns.
+ */
 export const Columns = ({ children }: ColumnProps) => {
 
     const context = useDataPageContext();
@@ -70,7 +115,11 @@ export const Columns = ({ children }: ColumnProps) => {
                 {...context}
                 selection={context.selectedItem}
                 onSelectionChange={context.onSelectionChanged}
-                clientFiltering={context.clientFiltering}>
+                clientFiltering={context.clientFiltering}
+                className={context.tableClassName}
+                pt={context.tablePt}
+                ptOptions={context.tablePtOptions}
+                unstyled={context.tableUnstyled}>
                 {children}
             </DataTableForQuery>);
 
@@ -80,14 +129,31 @@ export const Columns = ({ children }: ColumnProps) => {
                 {...context}
                 selection={context.selectedItem}
                 onSelectionChange={context.onSelectionChanged}
-                clientFiltering={context.clientFiltering}>
+                clientFiltering={context.clientFiltering}
+                className={context.tableClassName}
+                pt={context.tablePt}
+                ptOptions={context.tablePtOptions}
+                unstyled={context.tableUnstyled}>
                 {children}
             </DataTableForObservableQuery>);
     }
 };
 
+/**
+ * Props passed to the optional details component rendered on the right pane
+ * of a {@link DataPage} when a row is selected.
+ *
+ * @typeParam TDataType - The type of the selected item.
+ */
 export interface IDetailsComponentProps<TDataType> {
+    /** The currently-selected row. */
     item: TDataType;
+
+    /**
+     * Callback the details component can invoke to ask the surrounding page to
+     * refresh its data — for example after the details panel has performed a
+     * mutating action.
+     */
     onRefresh?: () => void;
 }
 
@@ -107,7 +173,11 @@ function useDataPageContext(): IDataPageContext {
 }
 
 /**
- * Props for the DataPage component
+ * Props for {@link DataPage}.
+ *
+ * @typeParam TQuery - The query class — either a snapshot `IQueryFor` or a real-time `IObservableQueryFor`.
+ * @typeParam TDataType - The row type returned by the query.
+ * @typeParam TArguments - The query's argument object type, or `object` if the query takes none.
  */
 export interface DataPageProps<TQuery extends IQueryFor<TDataType> | IObservableQueryFor<TDataType>, TDataType, TArguments> {
     /**
@@ -174,12 +244,66 @@ export interface DataPageProps<TQuery extends IQueryFor<TDataType> | IObservable
      * Callback triggered to signal data refresh
      */
     onRefresh?(): void;
+
+    /**
+     * Extra CSS class name forwarded to the inner DataTable root.
+     */
+    tableClassName?: string;
+
+    /** PrimeReact pass-through configuration applied to the inner DataTable. */
+    tablePt?: PrimeDataTableProps<any>['pt'];
+
+    /** PrimeReact pass-through options applied to the inner DataTable. */
+    tablePtOptions?: PrimeDataTableProps<any>['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the inner DataTable. */
+    tableUnstyled?: boolean;
+
+    /**
+     * Extra CSS class name forwarded to the action Menubar root.
+     */
+    menubarClassName?: string;
+
+    /** PrimeReact pass-through configuration applied to the action Menubar. */
+    menubarPt?: MenubarProps['pt'];
+
+    /** PrimeReact pass-through options applied to the action Menubar. */
+    menubarPtOptions?: MenubarProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the action Menubar. */
+    menubarUnstyled?: boolean;
 }
 
 /**
- * Represents a data driven page with a menu and custom defined columns for the data table.
- * @param props Props for the DataPage component
- * @returns Function to render the DataPage component
+ * A page primitive that combines an action menubar, a query-backed data table,
+ * and an optional details pane into one layout. Wraps Allotment for resizable
+ * split-pane behavior when a details component is supplied.
+ *
+ * Composition is declarative — use the static children:
+ *
+ * ```tsx
+ * <DataPage<AllAuthors, Author, never>
+ *     title="Authors" query={AllAuthors}
+ *     detailsComponent={AuthorDetails}>
+ *     <DataPage.MenuItems>
+ *         <DataPage.MenuItem icon={FaPlus} label="Add"     command={onAdd} />
+ *         <DataPage.MenuItem icon={FaPencil} label="Edit"  command={onEdit}
+ *                            disableOnUnselected />
+ *     </DataPage.MenuItems>
+ *     <DataPage.Columns>
+ *         <Column field="name"  header="Name" sortable />
+ *         <Column field="email" header="Email" />
+ *     </DataPage.Columns>
+ * </DataPage>
+ * ```
+ *
+ * Both `IQueryFor` (snapshot) and `IObservableQueryFor` (real-time) queries are
+ * supported automatically — the inner table type is selected at runtime.
+ *
+ * @typeParam TQuery - The query class.
+ * @typeParam TDataType - The row type returned by the query.
+ * @typeParam TArguments - The query's argument object type.
+ * @param props - {@link DataPageProps}.
  */
 const DataPage = <TQuery extends IQueryFor<TDataType> | IObservableQueryFor<TDataType, TArguments>, TDataType, TArguments extends object>(props: DataPageProps<TQuery, TDataType, TArguments>) => {
     const [selectedItem, setSelectedItem] = React.useState(undefined);
diff --git a/Source/DataTables/DataTableForObservableQuery.tsx b/Source/DataTables/DataTableForObservableQuery.tsx
index e2b2dbd..a9baae3 100644
--- a/Source/DataTables/DataTableForObservableQuery.tsx
+++ b/Source/DataTables/DataTableForObservableQuery.tsx
@@ -1,15 +1,19 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { DataTable, DataTableFilterMeta, DataTableSelectionSingleChangeEvent } from 'primereact/datatable';
-import { Paginator } from 'primereact/paginator';
+import { DataTable, DataTableFilterMeta, DataTableSelectionSingleChangeEvent, type DataTableProps as PrimeDataTableProps } from 'primereact/datatable';
+import { Paginator, type PaginatorProps } from 'primereact/paginator';
 import { Constructor } from '@cratis/fundamentals';
 import { IObservableQueryFor, Paging } from '@cratis/arc/queries';
 import { useObservableQueryWithPaging } from '@cratis/arc.react/queries';
 import { ReactNode, useState, useRef, useEffect } from 'react';
 
 /**
- * Props for the DataTableForQuery component
+ * Props for {@link DataTableForObservableQuery}.
+ *
+ * @typeParam TQuery - The query class implementing `IObservableQueryFor`.
+ * @typeParam TDataType - The row type returned by the query.
+ * @typeParam TArguments - The query's argument object type.
  */
 export interface DataTableForObservableQueryProps<TQuery extends IObservableQueryFor<TDataType, TArguments>, TDataType extends object, TArguments extends object> {
     /**
@@ -61,14 +65,50 @@ export interface DataTableForObservableQueryProps<TQuery extends IObservableQuer
      * Enable client-side filtering for the data table
      */
     clientFiltering?: boolean;
+
+    /**
+     * Extra CSS class name forwarded to the underlying PrimeReact DataTable root.
+     */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying DataTable. */
+    pt?: PrimeDataTableProps<TDataType[]>['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying DataTable. */
+    ptOptions?: PrimeDataTableProps<TDataType[]>['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying DataTable. */
+    unstyled?: boolean;
+
+    /** PrimeReact pass-through configuration applied to the inner Paginator. */
+    paginatorPt?: PaginatorProps['pt'];
+
+    /** PrimeReact pass-through options applied to the inner Paginator. */
+    paginatorPtOptions?: PaginatorProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the inner Paginator. */
+    paginatorUnstyled?: boolean;
 }
 
 const paging = new Paging(0, 20);
 
 /**
- * Represents a DataTable for a query.
- * @param props Props for the component
- * @returns Function to render the DataTableForQuery component
+ * A paged data table bound to a Cratis observable query (`IObservableQueryFor`).
+ * Subscribes via `useObservableQueryWithPaging`, so the table re-renders
+ * automatically as the underlying read model changes server-side. The table
+ * height is observed and matched to its container to keep scrollable content
+ * sized correctly inside flex layouts.
+ *
+ * Use {@link DataTableForQuery} instead for snapshot queries that don't need
+ * live updates. For a higher-level page layout, use {@link DataPage}.
+ *
+ * Children should be PrimeReact `<Column>` elements describing the visible
+ * columns.
+ *
+ * @typeParam TQuery - The observable query class.
+ * @typeParam TDataType - The row type returned by the query.
+ * @typeParam TArguments - The query's argument object type.
+ * @param props - {@link DataTableForObservableQueryProps}.
  */
 export const DataTableForObservableQuery = <TQuery extends IObservableQueryFor<TDataType, TArguments>, TDataType extends object, TArguments extends object>(props: DataTableForObservableQueryProps<TQuery, TDataType, TArguments>) => {
     const [filters, setFilters] = useState<DataTableFilterMeta>(props.defaultFilters ?? {});
@@ -124,8 +164,8 @@ export const DataTableForObservableQuery = <TQuery extends IObservableQueryFor<T
                 display: 'flex',
                 flexDirection: 'column',
                 height: '100%',
-                border: '1px solid var(--surface-border)',
-                borderRadius: 'var(--border-radius)',
+                border: '1px solid var(--cratis-surface-border)',
+                borderRadius: 'var(--cratis-border-radius)',
                 overflow: 'hidden'
             }}>
             <div style={{ height: `${tableHeight}px`, overflow: 'hidden' }}>
@@ -150,17 +190,24 @@ export const DataTableForObservableQuery = <TQuery extends IObservableQueryFor<T
                         }
                     }}
                     globalFilterFields={props.globalFilterFields}
-                    emptyMessage={props.emptyMessage}>
+                    emptyMessage={props.emptyMessage}
+                    className={props.className}
+                    pt={props.pt}
+                    ptOptions={props.ptOptions}
+                    unstyled={props.unstyled}>
                     {props.children}
                 </DataTable>
             </div>
             {result.paging.totalItems > 0 && (
-                <div style={{ borderTop: '1px solid var(--surface-border)' }}>
+                <div style={{ borderTop: '1px solid var(--cratis-surface-border)' }}>
                     <Paginator
                         first={result.paging.page * paging.pageSize}
                         rows={paging.pageSize}
                         totalRecords={result.paging.totalItems}
                         onPageChange={(e) => setPage(e.page)}
+                        pt={props.paginatorPt}
+                        ptOptions={props.paginatorPtOptions}
+                        unstyled={props.paginatorUnstyled}
                     />
                 </div>
             )}
diff --git a/Source/DataTables/DataTableForQuery.tsx b/Source/DataTables/DataTableForQuery.tsx
index a2ee3c2..3cbdfce 100644
--- a/Source/DataTables/DataTableForQuery.tsx
+++ b/Source/DataTables/DataTableForQuery.tsx
@@ -1,15 +1,19 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { DataTable, DataTableFilterMeta, DataTableSelectionSingleChangeEvent } from 'primereact/datatable';
-import { Paginator } from 'primereact/paginator';
+import { DataTable, DataTableFilterMeta, DataTableSelectionSingleChangeEvent, type DataTableProps as PrimeDataTableProps } from 'primereact/datatable';
+import { Paginator, type PaginatorProps } from 'primereact/paginator';
 import { Constructor } from '@cratis/fundamentals';
 import { IQueryFor, Paging } from '@cratis/arc/queries';
 import { useQueryWithPaging } from '@cratis/arc.react/queries';
 import { ReactNode, useState, useRef } from 'react';
 
 /**
- * Props for the DataTableForQuery component
+ * Props for {@link DataTableForQuery}.
+ *
+ * @typeParam TQuery - The query class implementing `IQueryFor`.
+ * @typeParam TDataType - The row type returned by the query.
+ * @typeParam TArguments - The query's argument object type, or `object` if it takes none.
  */
 export interface DataTableForQueryProps<TQuery extends IQueryFor<TDataType, TArguments>, TDataType extends object, TArguments extends object> {
     /**
@@ -61,14 +65,49 @@ export interface DataTableForQueryProps<TQuery extends IQueryFor<TDataType, TArg
      * Enable client-side filtering for the data table
      */
     clientFiltering?: boolean;
+
+    /**
+     * Extra CSS class name forwarded to the underlying PrimeReact DataTable root.
+     */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying DataTable. */
+    pt?: PrimeDataTableProps<TDataType[]>['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying DataTable. */
+    ptOptions?: PrimeDataTableProps<TDataType[]>['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying DataTable. */
+    unstyled?: boolean;
+
+    /** PrimeReact pass-through configuration applied to the inner Paginator. */
+    paginatorPt?: PaginatorProps['pt'];
+
+    /** PrimeReact pass-through options applied to the inner Paginator. */
+    paginatorPtOptions?: PaginatorProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the inner Paginator. */
+    paginatorUnstyled?: boolean;
 }
 
 const paging = new Paging(0, 20);
 
 /**
- * Represents a DataTable for a query.
- * @param props Props for the component
- * @returns Function to render the DataTableForQuery component
+ * A paged data table bound to a snapshot Cratis query (`IQueryFor`). Issues
+ * the query through `useQueryWithPaging`, renders results in a PrimeReact
+ * `DataTable`, and shows a `Paginator` when the result set exceeds one page.
+ *
+ * For queries that should update in real time as the read model changes, use
+ * {@link DataTableForObservableQuery} instead. For a higher-level page layout
+ * that combines this table with a menubar and details pane, use {@link DataPage}.
+ *
+ * Children should be PrimeReact `<Column>` elements describing the visible
+ * columns.
+ *
+ * @typeParam TQuery - The query class.
+ * @typeParam TDataType - The row type returned by the query.
+ * @typeParam TArguments - The query's argument object type.
+ * @param props - {@link DataTableForQueryProps}.
  */
 export const DataTableForQuery = <TQuery extends IQueryFor<TDataType, TArguments>, TDataType extends object, TArguments extends object>(props: DataTableForQueryProps<TQuery, TDataType, TArguments>) => {
     const [filters, setFilters] = useState<DataTableFilterMeta>(props.defaultFilters ?? {});
@@ -85,8 +124,8 @@ export const DataTableForQuery = <TQuery extends IQueryFor<TDataType, TArguments
                 display: 'flex',
                 flexDirection: 'column',
                 height: '100%',
-                border: '1px solid var(--surface-border)',
-                borderRadius: 'var(--border-radius)',
+                border: '1px solid var(--cratis-surface-border)',
+                borderRadius: 'var(--cratis-border-radius)',
                 overflow: 'hidden'
             }}>
             <div style={{ flex: 1, minHeight: 0, overflow: 'auto' }}>
@@ -110,18 +149,25 @@ export const DataTableForQuery = <TQuery extends IQueryFor<TDataType, TArguments
                     }}
                     globalFilterFields={props.globalFilterFields}
                     emptyMessage={props.emptyMessage}
-                    style={{ minWidth: '100%' }}>
+                    style={{ minWidth: '100%' }}
+                    className={props.className}
+                    pt={props.pt}
+                    ptOptions={props.ptOptions}
+                    unstyled={props.unstyled}>
                     {props.children}
                 </DataTable>
             </div>
 
             {result.paging.totalItems > 0 && (
-                <div style={{ borderTop: '1px solid var(--surface-border)', flexShrink: 0 }}>
+                <div style={{ borderTop: '1px solid var(--cratis-surface-border)', flexShrink: 0 }}>
                     <Paginator
                         first={result.paging.page * paging.pageSize}
                         rows={paging.pageSize}
                         totalRecords={result.paging.totalItems}
                         onPageChange={(e) => setPage(e.page)}
+                        pt={props.paginatorPt}
+                        ptOptions={props.paginatorPtOptions}
+                        unstyled={props.paginatorUnstyled}
                     />
                 </div>
             )}

From 082e7cf1ab274ba2b455c95aabd00328a233d121 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:37:06 +0200
Subject: [PATCH 07/23] Forward pt / ptOptions / unstyled / className on every
 CommandForm field

Each of the 13 CommandForm field wrappers (InputTextField, TextAreaField,
NumberField, DropdownField, RadioGroupField, RadioButtonField, CalendarField,
CheckboxField, SliderField, ChipsField, MultiSelectField, ColorPickerField)
now accepts `pt`, `ptOptions`, `unstyled`, and `className` and forwards each
straight to its underlying PrimeReact widget. The default `w-full` Tailwind
class is preserved by combining it with any consumer-supplied `className`.

This gives consumers full per-field styling control on top of (or instead of)
the global `pt` preset set on `CratisComponentsProvider`. Each prop is typed
from the underlying PrimeReact component's own type so autocomplete reflects
the real pt slot surface.
---
 Source/CommandForm/fields/CalendarField.tsx   | 46 +++++++++++++++++-
 Source/CommandForm/fields/CheckboxField.tsx   | 30 +++++++++++-
 Source/CommandForm/fields/ChipsField.tsx      | 39 ++++++++++++++-
 .../CommandForm/fields/ColorPickerField.tsx   | 35 +++++++++++++-
 Source/CommandForm/fields/DropdownField.tsx   | 41 +++++++++++++++-
 Source/CommandForm/fields/InputTextField.tsx  | 43 ++++++++++++++++-
 .../CommandForm/fields/MultiSelectField.tsx   | 48 ++++++++++++++++++-
 Source/CommandForm/fields/NumberField.tsx     | 38 ++++++++++++++-
 .../CommandForm/fields/RadioButtonField.tsx   | 34 ++++++++++++-
 Source/CommandForm/fields/RadioGroupField.tsx | 43 ++++++++++++++++-
 Source/CommandForm/fields/SliderField.tsx     | 35 +++++++++++++-
 Source/CommandForm/fields/TextAreaField.tsx   | 36 +++++++++++++-
 12 files changed, 446 insertions(+), 22 deletions(-)

diff --git a/Source/CommandForm/fields/CalendarField.tsx b/Source/CommandForm/fields/CalendarField.tsx
index fcd3923..baa6a58 100644
--- a/Source/CommandForm/fields/CalendarField.tsx
+++ b/Source/CommandForm/fields/CalendarField.tsx
@@ -2,19 +2,58 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
-import { Calendar } from 'primereact/calendar';
+import { Calendar, type CalendarProps } from 'primereact/calendar';
 import React from 'react';
 
+/**
+ * Component-level props for {@link CalendarField}.
+ */
 interface CalendarFieldComponentProps extends WrappedFieldProps<Date | null> {
+    /** Placeholder text shown when no date is selected. */
     placeholder?: string;
+
+    /** PrimeReact-style date format mask (e.g. `'yy-mm-dd'`). */
     dateFormat?: string;
+
+    /** When true, renders a trailing calendar icon button. */
     showIcon?: boolean;
+
+    /** When true, includes time selection alongside the date. */
     showTime?: boolean;
+
+    /** Hour format used when {@link showTime} is true. */
     hourFormat?: '12' | '24';
+
+    /** Earliest selectable date. */
     minDate?: Date;
+
+    /** Latest selectable date. */
     maxDate?: Date;
+
+    /** Extra CSS class name combined with the default `w-full`. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying Calendar. */
+    pt?: CalendarProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying Calendar. */
+    ptOptions?: CalendarProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying Calendar. */
+    unstyled?: boolean;
 }
 
+/**
+ * A date (or date-time) picker field for use inside a `CommandForm`. Binds to
+ * a `Date | null` property on the command.
+ *
+ * ```tsx
+ * <CalendarField value={c => c.dueDate}
+ *                title="Due date"
+ *                showIcon
+ *                minDate={new Date()} />
+ * ```
+ */
 export const CalendarField = asCommandFormField<CalendarFieldComponentProps>(
     (props) => (
         <Calendar
@@ -29,7 +68,10 @@ export const CalendarField = asCommandFormField<CalendarFieldComponentProps>(
             hourFormat={props.hourFormat}
             minDate={props.minDate}
             maxDate={props.maxDate}
-            className="w-full"
+            className={props.className ? `w-full ${props.className}` : 'w-full'}
+            pt={props.pt}
+            ptOptions={props.ptOptions}
+            unstyled={props.unstyled}
         />
     ),
     {
diff --git a/Source/CommandForm/fields/CheckboxField.tsx b/Source/CommandForm/fields/CheckboxField.tsx
index a366c67..efd53c7 100644
--- a/Source/CommandForm/fields/CheckboxField.tsx
+++ b/Source/CommandForm/fields/CheckboxField.tsx
@@ -1,14 +1,38 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Checkbox } from 'primereact/checkbox';
+import { Checkbox, type CheckboxProps } from 'primereact/checkbox';
 import React from 'react';
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
 
+/**
+ * Component-level props for {@link CheckboxField}.
+ */
 interface CheckboxFieldComponentProps extends WrappedFieldProps<boolean> {
+    /** Optional label displayed next to the checkbox. */
     label?: string;
+
+    /** Extra CSS class name forwarded to the underlying Checkbox. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying Checkbox. */
+    pt?: CheckboxProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying Checkbox. */
+    ptOptions?: CheckboxProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying Checkbox. */
+    unstyled?: boolean;
 }
 
+/**
+ * A single boolean checkbox field for use inside a `CommandForm`. Binds to
+ * a boolean property on the command.
+ *
+ * ```tsx
+ * <CheckboxField value={c => c.acceptedTerms} label="I agree to the terms" />
+ * ```
+ */
 export const CheckboxField = asCommandFormField<CheckboxFieldComponentProps>(
     (props) => (
         <div className="flex align-items-center">
@@ -17,6 +41,10 @@ export const CheckboxField = asCommandFormField<CheckboxFieldComponentProps>(
                 onChange={props.onChange}
                 onBlur={props.onBlur}
                 invalid={props.invalid}
+                className={props.className}
+                pt={props.pt}
+                ptOptions={props.ptOptions}
+                unstyled={props.unstyled}
             />
             {props.label && <label className="ml-2">{props.label}</label>}
         </div>
diff --git a/Source/CommandForm/fields/ChipsField.tsx b/Source/CommandForm/fields/ChipsField.tsx
index d2e09b1..461fd79 100644
--- a/Source/CommandForm/fields/ChipsField.tsx
+++ b/Source/CommandForm/fields/ChipsField.tsx
@@ -2,17 +2,49 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
-import { Chips } from 'primereact/chips';
+import { Chips, type ChipsProps } from 'primereact/chips';
 import React from 'react';
 
+/**
+ * Component-level props for {@link ChipsField}.
+ */
 interface ChipsFieldComponentProps extends WrappedFieldProps<string[]> {
+    /** Placeholder text shown when the chip list is empty. */
     placeholder?: string;
+
+    /** Maximum number of chips allowed. */
     max?: number;
+
+    /** Character (or regex source) that splits typed input into multiple chips. */
     separator?: string;
+
+    /** When true, the current input is committed as a chip on blur. */
     addOnBlur?: boolean;
+
+    /** When true, the same chip value may be added multiple times. */
     allowDuplicate?: boolean;
+
+    /** Extra CSS class name combined with the default `w-full`. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying Chips. */
+    pt?: ChipsProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying Chips. */
+    ptOptions?: ChipsProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying Chips. */
+    unstyled?: boolean;
 }
 
+/**
+ * A tag/chip input field for use inside a `CommandForm`. Binds to a
+ * `string[]` property on the command — each entered token becomes a chip.
+ *
+ * ```tsx
+ * <ChipsField value={c => c.tags} title="Tags" separator="," />
+ * ```
+ */
 export const ChipsField = asCommandFormField<ChipsFieldComponentProps>(
     (props) => (
         <Chips
@@ -25,7 +57,10 @@ export const ChipsField = asCommandFormField<ChipsFieldComponentProps>(
             separator={props.separator}
             addOnBlur={props.addOnBlur}
             allowDuplicate={props.allowDuplicate}
-            className="w-full"
+            className={props.className ? `w-full ${props.className}` : 'w-full'}
+            pt={props.pt}
+            ptOptions={props.ptOptions}
+            unstyled={props.unstyled}
         />
     ),
     {
diff --git a/Source/CommandForm/fields/ColorPickerField.tsx b/Source/CommandForm/fields/ColorPickerField.tsx
index 8a4d62e..91ab24b 100644
--- a/Source/CommandForm/fields/ColorPickerField.tsx
+++ b/Source/CommandForm/fields/ColorPickerField.tsx
@@ -2,18 +2,46 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
-import { ColorPicker } from 'primereact/colorpicker';
+import { ColorPicker, type ColorPickerProps } from 'primereact/colorpicker';
 import React from 'react';
 
+/**
+ * Component-level props for {@link ColorPickerField}.
+ */
 interface ColorPickerFieldComponentProps extends WrappedFieldProps<string> {
+    /** When true, renders the color picker inline rather than as a popover. */
     inline?: boolean;
+
+    /** Initial color shown when the bound property is empty. Defaults to `'000000'`. */
     defaultColor?: string;
+
+    /** Extra CSS class name forwarded to the underlying ColorPicker. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying ColorPicker. */
+    pt?: ColorPickerProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying ColorPicker. */
+    ptOptions?: ColorPickerProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying ColorPicker. */
+    unstyled?: boolean;
 }
 
+/**
+ * A color picker field for use inside a `CommandForm`. Binds to a string
+ * property holding a hex color value (e.g. `"60a5fa"`).
+ *
+ * ```tsx
+ * <ColorPickerField value={c => c.accentColor} title="Accent" inline />
+ * ```
+ */
 export const ColorPickerField = asCommandFormField<ColorPickerFieldComponentProps>(
     (props) => {
         const defaultColor = props.defaultColor ?? '000000';
         const value = typeof props.value === 'string' && props.value.length > 0 ? props.value : defaultColor;
+        const invalidClass = props.invalid ? 'p-invalid' : undefined;
+        const className = [invalidClass, props.className].filter(Boolean).join(' ') || undefined;
 
         return (
             <ColorPicker
@@ -22,7 +50,10 @@ export const ColorPickerField = asCommandFormField<ColorPickerFieldComponentProp
                 onBlur={props.onBlur}
                 inline={props.inline}
                 defaultColor={defaultColor}
-                className={props.invalid ? 'p-invalid' : undefined}
+                className={className}
+                pt={props.pt}
+                ptOptions={props.ptOptions}
+                unstyled={props.unstyled}
             />
         );
     },
diff --git a/Source/CommandForm/fields/DropdownField.tsx b/Source/CommandForm/fields/DropdownField.tsx
index a0b4960..50c5258 100644
--- a/Source/CommandForm/fields/DropdownField.tsx
+++ b/Source/CommandForm/fields/DropdownField.tsx
@@ -1,17 +1,51 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Dropdown } from 'primereact/dropdown';
+import { Dropdown, type DropdownProps } from 'primereact/dropdown';
 import React from 'react';
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
 
+/**
+ * Component-level props for {@link DropdownField}.
+ */
 interface DropdownFieldComponentProps extends WrappedFieldProps<string | number> {
+    /** Source array of objects to populate the dropdown options. */
     options: Array<{ [key: string]: unknown }>;
+
+    /** Property name on each option object used as the underlying value. */
     optionValue: string;
+
+    /** Property name on each option object used as the visible label. */
     optionLabel: string;
+
+    /** Placeholder text shown when no option is selected. */
     placeholder?: string;
+
+    /** Extra CSS class name combined with the default `w-full`. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying Dropdown. */
+    pt?: DropdownProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying Dropdown. */
+    ptOptions?: DropdownProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying Dropdown. */
+    unstyled?: boolean;
 }
 
+/**
+ * A single-select dropdown field for use inside a `CommandForm`. Binds to
+ * a string or numeric property on the command.
+ *
+ * ```tsx
+ * <DropdownField value={c => c.country}
+ *                options={countries}
+ *                optionValue="code"
+ *                optionLabel="name"
+ *                title="Country" />
+ * ```
+ */
 export const DropdownField = asCommandFormField<DropdownFieldComponentProps>(
     (props) => (
         <Dropdown
@@ -23,7 +57,10 @@ export const DropdownField = asCommandFormField<DropdownFieldComponentProps>(
             optionLabel={props.optionLabel}
             placeholder={props.placeholder}
             invalid={props.invalid}
-            className="w-full"
+            className={props.className ? `w-full ${props.className}` : 'w-full'}
+            pt={props.pt}
+            ptOptions={props.ptOptions}
+            unstyled={props.unstyled}
         />
     ),
     {
diff --git a/Source/CommandForm/fields/InputTextField.tsx b/Source/CommandForm/fields/InputTextField.tsx
index 146e3d5..49cccc5 100644
--- a/Source/CommandForm/fields/InputTextField.tsx
+++ b/Source/CommandForm/fields/InputTextField.tsx
@@ -1,15 +1,51 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { InputText } from 'primereact/inputtext';
+import { InputText, type InputTextProps } from 'primereact/inputtext';
 import React from 'react';
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
 
+/**
+ * Component-level props for {@link InputTextField}. Combined at runtime with
+ * the field-level props injected by `asCommandFormField` (`value`, `onChange`,
+ * `onBlur`, `invalid`).
+ */
 interface InputTextComponentProps extends WrappedFieldProps<string> {
+    /** HTML input type. Defaults to `'text'`. */
     type?: 'text' | 'email' | 'password' | 'color' | 'date' | 'datetime-local' | 'time' | 'url' | 'tel' | 'search';
+
+    /** Placeholder text shown when the field is empty. */
     placeholder?: string;
+
+    /** Extra CSS class name forwarded to the PrimeReact InputText. Combined with the default `w-full`. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying InputText. */
+    pt?: InputTextProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying InputText. */
+    ptOptions?: InputTextProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying InputText. */
+    unstyled?: boolean;
 }
 
+/**
+ * A single-line text field for use inside a `CommandForm`. Binds to a string
+ * property on the command via the `value` accessor (`value={c => c.name}`)
+ * and forwards user input through the form context.
+ *
+ * Supports all the input types PrimeReact's `InputText` does (`text`, `email`,
+ * `password`, `url`, `tel`, `date`, etc.) and forwards `pt` / `ptOptions` /
+ * `unstyled` for full restyling control.
+ *
+ * ```tsx
+ * <InputTextField value={c => c.email}
+ *                 type="email"
+ *                 title="Email"
+ *                 placeholder="you@example.com" />
+ * ```
+ */
 export const InputTextField = asCommandFormField<InputTextComponentProps>(
     (props) => (
         <InputText
@@ -19,7 +55,10 @@ export const InputTextField = asCommandFormField<InputTextComponentProps>(
             onBlur={props.onBlur}
             invalid={props.invalid}
             placeholder={props.placeholder}
-            className="w-full"
+            className={props.className ? `w-full ${props.className}` : 'w-full'}
+            pt={props.pt}
+            ptOptions={props.ptOptions}
+            unstyled={props.unstyled}
         />
     ),
     {
diff --git a/Source/CommandForm/fields/MultiSelectField.tsx b/Source/CommandForm/fields/MultiSelectField.tsx
index 518a46a..54b5c93 100644
--- a/Source/CommandForm/fields/MultiSelectField.tsx
+++ b/Source/CommandForm/fields/MultiSelectField.tsx
@@ -2,20 +2,61 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
-import { MultiSelect } from 'primereact/multiselect';
+import { MultiSelect, type MultiSelectProps } from 'primereact/multiselect';
 import React from 'react';
 
+/**
+ * Component-level props for {@link MultiSelectField}.
+ */
 interface MultiSelectFieldComponentProps extends WrappedFieldProps<Array<string | number>> {
+    /** Source array of objects to populate the multi-select options. */
     options: Array<Record<string, unknown>>;
+
+    /** Property name on each option object used as the underlying value. */
     optionValue?: string;
+
+    /** Property name on each option object used as the visible label. */
     optionLabel?: string;
+
+    /** Placeholder text shown when nothing is selected. */
     placeholder?: string;
+
+    /** How the selection is displayed in the field: comma-separated or as chips. */
     display?: 'comma' | 'chip';
+
+    /** Maximum number of selected labels to show before collapsing into a count. */
     maxSelectedLabels?: number;
+
+    /** When true, shows a filter input in the dropdown panel. */
     filter?: boolean;
+
+    /** When true, shows a clear icon that resets the selection. */
     showClear?: boolean;
+
+    /** Extra CSS class name combined with the default `w-full`. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying MultiSelect. */
+    pt?: MultiSelectProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying MultiSelect. */
+    ptOptions?: MultiSelectProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying MultiSelect. */
+    unstyled?: boolean;
 }
 
+/**
+ * A multi-select dropdown field for use inside a `CommandForm`. Binds to an
+ * array of strings or numbers on the command. Use for "pick any subset of
+ * these" controls with optional filtering inside the panel.
+ *
+ * ```tsx
+ * <MultiSelectField value={c => c.tagIds}
+ *                   options={tags} optionValue="id" optionLabel="name"
+ *                   display="chip" filter title="Tags" />
+ * ```
+ */
 export const MultiSelectField = asCommandFormField<MultiSelectFieldComponentProps>(
     (props) => (
         <MultiSelect
@@ -31,7 +72,10 @@ export const MultiSelectField = asCommandFormField<MultiSelectFieldComponentProp
             filter={props.filter}
             showClear={props.showClear}
             invalid={props.invalid}
-            className="w-full"
+            className={props.className ? `w-full ${props.className}` : 'w-full'}
+            pt={props.pt}
+            ptOptions={props.ptOptions}
+            unstyled={props.unstyled}
         />
     ),
     {
diff --git a/Source/CommandForm/fields/NumberField.tsx b/Source/CommandForm/fields/NumberField.tsx
index bad5972..0f2427d 100644
--- a/Source/CommandForm/fields/NumberField.tsx
+++ b/Source/CommandForm/fields/NumberField.tsx
@@ -1,17 +1,48 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { InputNumber } from 'primereact/inputnumber';
+import { InputNumber, type InputNumberProps } from 'primereact/inputnumber';
 import React from 'react';
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
 
+/**
+ * Component-level props for {@link NumberField}.
+ */
 interface NumberFieldComponentProps extends WrappedFieldProps<number> {
+    /** Placeholder text shown when the field is empty. */
     placeholder?: string;
+
+    /** Minimum allowed value. */
     min?: number;
+
+    /** Maximum allowed value. */
     max?: number;
+
+    /** Increment/decrement step applied by the spinner buttons. */
     step?: number;
+
+    /** Extra CSS class name combined with the default `w-full`. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying InputNumber. */
+    pt?: InputNumberProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying InputNumber. */
+    ptOptions?: InputNumberProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying InputNumber. */
+    unstyled?: boolean;
 }
 
+/**
+ * A numeric input field for use inside a `CommandForm`. Binds to a number
+ * property on the command. Defaults to integer mode without grouping; pass
+ * a `step` to enable spinner increments.
+ *
+ * ```tsx
+ * <NumberField value={c => c.quantity} title="Quantity" min={0} step={1} />
+ * ```
+ */
 export const NumberField = asCommandFormField<NumberFieldComponentProps>(
     (props) => (
         <InputNumber
@@ -23,7 +54,10 @@ export const NumberField = asCommandFormField<NumberFieldComponentProps>(
             min={props.min}
             max={props.max}
             step={props.step}
-            className="w-full"
+            className={props.className ? `w-full ${props.className}` : 'w-full'}
+            pt={props.pt}
+            ptOptions={props.ptOptions}
+            unstyled={props.unstyled}
         />
     ),
     {
diff --git a/Source/CommandForm/fields/RadioButtonField.tsx b/Source/CommandForm/fields/RadioButtonField.tsx
index d9d4296..334add7 100644
--- a/Source/CommandForm/fields/RadioButtonField.tsx
+++ b/Source/CommandForm/fields/RadioButtonField.tsx
@@ -1,15 +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 { RadioButton, RadioButtonChangeEvent } from 'primereact/radiobutton';
+import { RadioButton, RadioButtonChangeEvent, type RadioButtonProps } from 'primereact/radiobutton';
 import React from 'react';
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
 
+/**
+ * Component-level props for {@link RadioButtonField}.
+ */
 interface RadioButtonFieldComponentProps extends WrappedFieldProps<string | number> {
+    /** Optional label displayed next to the radio button. */
     label?: string;
+
+    /**
+     * The value this radio button represents. The field is selected when the
+     * bound command property equals this value.
+     */
     buttonValue: string | number;
+
+    /** Extra CSS class name forwarded to the underlying RadioButton. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying RadioButton. */
+    pt?: RadioButtonProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying RadioButton. */
+    ptOptions?: RadioButtonProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying RadioButton. */
+    unstyled?: boolean;
 }
 
+/**
+ * A single radio button bound to a command property. Multiple
+ * {@link RadioButtonField} instances with the same `value` accessor and
+ * distinct `buttonValue` props together form a mutually-exclusive group.
+ * For most cases prefer {@link RadioGroupField} which manages the group as
+ * a single field.
+ */
 export const RadioButtonField = asCommandFormField<RadioButtonFieldComponentProps>(
     (props) => (
         <div className="flex align-items-center">
@@ -19,6 +47,10 @@ export const RadioButtonField = asCommandFormField<RadioButtonFieldComponentProp
                 onChange={(e: RadioButtonChangeEvent) => props.onChange(e.value)}
                 onBlur={props.onBlur}
                 invalid={props.invalid}
+                className={props.className}
+                pt={props.pt}
+                ptOptions={props.ptOptions}
+                unstyled={props.unstyled}
             />
             {props.label && <label className="ml-2">{props.label}</label>}
         </div>
diff --git a/Source/CommandForm/fields/RadioGroupField.tsx b/Source/CommandForm/fields/RadioGroupField.tsx
index e0665e6..1a8481f 100644
--- a/Source/CommandForm/fields/RadioGroupField.tsx
+++ b/Source/CommandForm/fields/RadioGroupField.tsx
@@ -1,22 +1,58 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { RadioButton, RadioButtonChangeEvent } from 'primereact/radiobutton';
+import { RadioButton, RadioButtonChangeEvent, type RadioButtonProps } from 'primereact/radiobutton';
 import React from 'react';
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
 
+/**
+ * Component-level props for {@link RadioGroupField}.
+ */
 interface RadioGroupFieldComponentProps extends WrappedFieldProps<string | number> {
+    /** Source array of objects to populate the radio options. */
     options: Array<Record<string, unknown>>;
+
+    /** Property name on each option object used as the visible label. */
     optionLabel: string;
+
+    /** Property name on each option object used as the underlying value. */
     optionValue: string;
+
+    /** Layout orientation. Defaults to `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
+    /** Extra CSS class name forwarded to the group container. */
+    className?: string;
+    /** PrimeReact pass-through configuration applied to every inner RadioButton. */
+    pt?: RadioButtonProps['pt'];
+    /** PrimeReact pass-through options applied to every inner RadioButton. */
+    ptOptions?: RadioButtonProps['ptOptions'];
+    /** When true, disables every base PrimeReact style on the inner RadioButtons. */
+    unstyled?: boolean;
 }
 
+/**
+ * A radio-button group field for use inside a `CommandForm`. Binds to a
+ * string or numeric property on the command. Use for small mutually-exclusive
+ * choice sets; for larger sets, prefer {@link DropdownField}.
+ *
+ * ```tsx
+ * <RadioGroupField value={c => c.priority}
+ *                  options={priorityOptions}
+ *                  optionLabel="label"
+ *                  optionValue="value"
+ *                  layout="horizontal"
+ *                  title="Priority" />
+ * ```
+ */
 export const RadioGroupField = asCommandFormField<RadioGroupFieldComponentProps>(
     (props) => {
         const layout = props.layout ?? 'vertical';
+        const layoutClasses = layout === 'horizontal' ? 'flex-row gap-4 flex-wrap' : 'flex-column gap-2';
+        const containerClassName = props.className
+            ? `flex ${layoutClasses} ${props.className}`
+            : `flex ${layoutClasses}`;
         return (
-            <div className={`flex ${layout === 'horizontal' ? 'flex-row gap-4 flex-wrap' : 'flex-column gap-2'}`}>
+            <div className={containerClassName}>
                 {props.options.map((option) => {
                     const optValue = option[props.optionValue] as string | number;
                     const optLabel = option[props.optionLabel] as string;
@@ -28,6 +64,9 @@ export const RadioGroupField = asCommandFormField<RadioGroupFieldComponentProps>
                                 onChange={(e: RadioButtonChangeEvent) => props.onChange(e.value)}
                                 onBlur={props.onBlur}
                                 invalid={props.invalid}
+                                pt={props.pt}
+                                ptOptions={props.ptOptions}
+                                unstyled={props.unstyled}
                             />
                             <label className="ml-2">{optLabel}</label>
                         </div>
diff --git a/Source/CommandForm/fields/SliderField.tsx b/Source/CommandForm/fields/SliderField.tsx
index 880911e..e53b527 100644
--- a/Source/CommandForm/fields/SliderField.tsx
+++ b/Source/CommandForm/fields/SliderField.tsx
@@ -1,16 +1,44 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { Slider } from 'primereact/slider';
+import { Slider, type SliderProps } from 'primereact/slider';
 import React from 'react';
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
 
+/**
+ * Component-level props for {@link SliderField}.
+ */
 interface SliderFieldComponentProps extends WrappedFieldProps<number> {
+    /** Minimum value. Defaults to `0`. */
     min?: number;
+
+    /** Maximum value. Defaults to `100`. */
     max?: number;
+
+    /** Increment between selectable values. Defaults to `1`. */
     step?: number;
+
+    /** Extra CSS class name combined with the default `w-full`. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying Slider. */
+    pt?: SliderProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying Slider. */
+    ptOptions?: SliderProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying Slider. */
+    unstyled?: boolean;
 }
 
+/**
+ * A horizontal slider field for use inside a `CommandForm`. Binds to a number
+ * property and shows the current value below the track.
+ *
+ * ```tsx
+ * <SliderField value={c => c.volume} title="Volume" min={0} max={100} />
+ * ```
+ */
 export const SliderField = asCommandFormField<SliderFieldComponentProps>(
     (props) => (
         <div className="w-full" onBlur={props.onBlur}>
@@ -20,7 +48,10 @@ export const SliderField = asCommandFormField<SliderFieldComponentProps>(
                 min={props.min ?? 0}
                 max={props.max ?? 100}
                 step={props.step ?? 1}
-                className="w-full"
+                className={props.className ? `w-full ${props.className}` : 'w-full'}
+                pt={props.pt}
+                ptOptions={props.ptOptions}
+                unstyled={props.unstyled}
             />
             <div className="text-center mt-2">
                 <span className="font-semibold">{props.value}</span>
diff --git a/Source/CommandForm/fields/TextAreaField.tsx b/Source/CommandForm/fields/TextAreaField.tsx
index e1de09b..3f9080f 100644
--- a/Source/CommandForm/fields/TextAreaField.tsx
+++ b/Source/CommandForm/fields/TextAreaField.tsx
@@ -1,16 +1,45 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { InputTextarea } from 'primereact/inputtextarea';
+import { InputTextarea, type InputTextareaProps } from 'primereact/inputtextarea';
 import React from 'react';
 import { asCommandFormField, WrappedFieldProps } from '@cratis/arc.react/commands';
 
+/**
+ * Component-level props for {@link TextAreaField}.
+ */
 interface TextAreaFieldComponentProps extends WrappedFieldProps<string> {
+    /** Placeholder text shown when the field is empty. */
     placeholder?: string;
+
+    /** Number of visible text rows. Defaults to `5`. */
     rows?: number;
+
+    /** Number of visible character columns. */
     cols?: number;
+
+    /** Extra CSS class name combined with the default `w-full`. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying InputTextarea. */
+    pt?: InputTextareaProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying InputTextarea. */
+    ptOptions?: InputTextareaProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying InputTextarea. */
+    unstyled?: boolean;
 }
 
+/**
+ * A multi-line text field for use inside a `CommandForm`. Binds to a string
+ * property on the command via the `value` accessor. Use for descriptions,
+ * notes, or any free-form text longer than a single line.
+ *
+ * ```tsx
+ * <TextAreaField value={c => c.description} title="Description" rows={4} />
+ * ```
+ */
 export const TextAreaField = asCommandFormField<TextAreaFieldComponentProps>(
     (props) => (
         <InputTextarea
@@ -21,7 +50,10 @@ export const TextAreaField = asCommandFormField<TextAreaFieldComponentProps>(
             placeholder={props.placeholder}
             rows={props.rows ?? 5}
             cols={props.cols}
-            className="w-full"
+            className={props.className ? `w-full ${props.className}` : 'w-full'}
+            pt={props.pt}
+            ptOptions={props.ptOptions}
+            unstyled={props.unstyled}
         />
     ),
     {

From e1e2f93278375c70dd21f106eb3050b2d0815a42 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:37:28 +0200
Subject: [PATCH 08/23] Add PrimeReact-style JSDoc on remaining public
 components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Document every consumer-facing component and prop interface that was
previously undocumented or thinly documented, using the same JSDoc style as
PrimeReact itself — one block on the component covering purpose, behavior,
and a short usage example, plus a block on every prop in the props interface.

Covers CommandStepper, Common/ErrorBoundary, Common/Page, Dropdown,
PivotViewer, and TimeMachine/{EventsView,ReadModelView}. Together with the
JSDoc landed alongside each pt-forwarding commit, the entire public surface
of the package now has consistent prop-level documentation that surfaces in
IDE intellisense.
---
 Source/CommandDialog/CommandStepper.tsx | 30 ++++++++++++++++++
 Source/Common/ErrorBoundary.tsx         | 42 +++++++++++++++++++++++++
 Source/Common/Page.tsx                  | 37 ++++++++++++++++++++++
 Source/Dropdown/Dropdown.tsx            | 17 ++++++++++
 Source/PivotViewer/PivotViewer.tsx      | 19 +++++++++++
 Source/TimeMachine/EventsView.tsx       | 15 +++++++++
 Source/TimeMachine/ReadModelView.tsx    | 29 +++++++++++++++++
 7 files changed, 189 insertions(+)

diff --git a/Source/CommandDialog/CommandStepper.tsx b/Source/CommandDialog/CommandStepper.tsx
index a7c4a92..f11c3cf 100644
--- a/Source/CommandDialog/CommandStepper.tsx
+++ b/Source/CommandDialog/CommandStepper.tsx
@@ -389,6 +389,36 @@ const CommandStepperWrapper = <TCommand extends object, TResponse = object>({
     );
 };
 
+/**
+ * A multi-step wizard backed by a single Cratis command — the embedded
+ * counterpart of {@link StepperCommandDialog} that lives directly inside
+ * a page rather than inside a modal dialog.
+ *
+ * Wraps PrimeReact's `Stepper` with a `CommandForm` and a built-in
+ * previous / next / submit footer. Steps with field errors are visually
+ * marked so the user can see which step needs attention without clicking
+ * through every page.
+ *
+ * Use this when a complex form fills a page region (a panel, a route);
+ * use {@link StepperCommandDialog} when the same wizard should appear in
+ * a modal dialog.
+ *
+ * ```tsx
+ * <CommandStepper<RegisterAuthor> command={RegisterAuthor}
+ *                                 onSuccess={onCreated}>
+ *     <StepperPanel header="Basics">
+ *         <InputTextField value={c => c.name} title="Name" />
+ *     </StepperPanel>
+ *     <StepperPanel header="Contact">
+ *         <InputTextField value={c => c.email} title="Email" />
+ *     </StepperPanel>
+ * </CommandStepper>
+ * ```
+ *
+ * @typeParam TCommand - The command record type. Defaults to `object`.
+ * @typeParam TResponse - The success payload type. Defaults to `object`.
+ * @param props - {@link CommandStepperProps}.
+ */
 export const CommandStepper = <TCommand extends object = object, TResponse = object>(
     props: CommandStepperProps<TCommand, TResponse>
 ) => {
diff --git a/Source/Common/ErrorBoundary.tsx b/Source/Common/ErrorBoundary.tsx
index 4b4c9b4..a0d5652 100644
--- a/Source/Common/ErrorBoundary.tsx
+++ b/Source/Common/ErrorBoundary.tsx
@@ -3,24 +3,66 @@
 
 import { Component, ErrorInfo, ReactNode } from 'react';
 
+/**
+ * Props for {@link ErrorBoundary}.
+ */
 interface Props {
+    /** The subtree the boundary protects. Rendered as-is when no error is caught. */
     children: ReactNode;
 }
+
+/**
+ * Internal state captured when a child throws during render or commit.
+ */
 interface State {
+    /** True once a child has thrown; switches the render path to the fallback UI. */
     hasError: boolean;
+    /** The thrown error. Held so the fallback UI can show message and stack. */
     error: Error;
 }
 
+/**
+ * React error boundary that catches errors thrown by its descendants during
+ * render, lifecycle, and constructor calls. On error, it renders a minimal
+ * inline diagnostic (message + stack) so the rest of the application keeps
+ * working instead of crashing the whole tree.
+ *
+ * Wrap the boundary around any subtree whose failure should be isolated:
+ *
+ * ```tsx
+ * <ErrorBoundary>
+ *     <RiskyFeature />
+ * </ErrorBoundary>
+ * ```
+ *
+ * Use one boundary per logical UI region rather than a single root-level one,
+ * so failures stay scoped to the feature that caused them.
+ */
 export class ErrorBoundary extends Component<Props, State> {
+    /** Initial state — no error captured. */
     public state: State = {
         hasError: false,
         error: new Error(),
     };
 
+    /**
+     * React lifecycle hook invoked when a descendant throws. Returns the
+     * next state, which switches the boundary into its fallback render path.
+     *
+     * @param error - The error thrown by the descendant.
+     */
     public static getDerivedStateFromError(error: Error): State {
         return { hasError: true, error: error };
     }
 
+    /**
+     * React lifecycle hook invoked alongside {@link getDerivedStateFromError}.
+     * Forwards the error and React's component stack to the console so the
+     * failure is observable in DevTools.
+     *
+     * @param error - The error thrown by the descendant.
+     * @param errorInfo - React-supplied metadata including the component stack.
+     */
     public componentDidCatch(error: Error, errorInfo: ErrorInfo) {
         console.error('Uncaught error:', error, errorInfo);
     }
diff --git a/Source/Common/Page.tsx b/Source/Common/Page.tsx
index 6b1f50f..5822492 100644
--- a/Source/Common/Page.tsx
+++ b/Source/Common/Page.tsx
@@ -3,13 +3,50 @@
 
 import { HTMLAttributes, ReactNode } from 'react';
 
+/**
+ * Props for {@link Page}. Extends the standard `div` attributes so callers can
+ * forward `id`, `aria-*`, `data-*`, custom styles, and event handlers to the
+ * root element.
+ */
 export interface PageProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Title of the page. Always passed in; only rendered when {@link showTitle}
+     * is true, but kept on every page so it's available for browser tab titles
+     * and accessibility tooling.
+     */
     title: string;
+
+    /**
+     * When true, renders the title as a level-1 heading at the top of the page.
+     * Defaults to `false` because many pages use a custom header or breadcrumb
+     * trail rendered inside `children` instead.
+     */
     showTitle?: boolean;
+
+    /** Page body content. */
     children?: ReactNode;
+
+    /**
+     * When true, wraps the body in a "panel" container that applies the
+     * surface, border, and radius styling defined by the `--cratis-*` tokens.
+     * Useful when the page is the sole occupant of a viewport region.
+     */
     panel?: boolean
 }
 
+/**
+ * Top-level page layout primitive. Renders a flex column that fills its parent
+ * vertically, with optional title heading and optional `panel` chrome around
+ * the main content area. Intended as the root element of every routable view.
+ *
+ * ```tsx
+ * <Page title="Authors" showTitle panel>
+ *     <AuthorList />
+ * </Page>
+ * ```
+ *
+ * @param props - {@link PageProps}.
+ */
 export const Page = ({ title, showTitle = false, children, panel, ...rest }: PageProps) => {
     return (
         <div className='flex flex-col h-full flex-1' {...rest}>
diff --git a/Source/Dropdown/Dropdown.tsx b/Source/Dropdown/Dropdown.tsx
index 1200e5e..cc32ff1 100644
--- a/Source/Dropdown/Dropdown.tsx
+++ b/Source/Dropdown/Dropdown.tsx
@@ -5,8 +5,25 @@ import React from 'react';
 import { Dropdown as PrimeDropdown, DropdownProps as PrimeDropdownProps } from 'primereact/dropdown';
 import { useOverlayZIndex } from '../useOverlayZIndex';
 
+/**
+ * Props for {@link Dropdown}. Identical to PrimeReact's `DropdownProps` —
+ * the wrapper does not add new props of its own.
+ */
 export type DropdownProps = PrimeDropdownProps;
 
+/**
+ * Thin wrapper around PrimeReact's `Dropdown` that fixes two ergonomic
+ * issues for Cratis apps:
+ *
+ * - Defaults `appendTo` to `document.body` so dropdown panels escape parent
+ *   scroll containers (a common gotcha inside dialogs and data table rows).
+ * - Forces a high z-index on the dropdown panel via {@link useOverlayZIndex}
+ *   so it appears above modal dialogs.
+ *
+ * The component forwards refs and spreads all other props, so it accepts
+ * the full PrimeReact `Dropdown` API including `pt`, `ptOptions`, and
+ * `unstyled` for restyling.
+ */
 export const Dropdown = React.forwardRef<PrimeDropdown, DropdownProps>((props, ref) => {
     // Force z-index on the dropdown panel to appear above dialogs
     useOverlayZIndex('p-dropdown-panel');
diff --git a/Source/PivotViewer/PivotViewer.tsx b/Source/PivotViewer/PivotViewer.tsx
index 14cd9f5..8c92e30 100644
--- a/Source/PivotViewer/PivotViewer.tsx
+++ b/Source/PivotViewer/PivotViewer.tsx
@@ -25,6 +25,25 @@ import { useScrollSync } from './hooks/useScrollSync';
 import { useAnimationModeTracking } from './hooks/useAnimationModeTracking';
 import { useViewModeScrollHandling } from './hooks/useViewModeScrollHandling';
 
+/**
+ * A faceted, zoomable card-grid visualization inspired by Microsoft's PivotViewer.
+ * Renders a large set of items as cards that can be grouped by any of a set of
+ * declared dimensions, filtered through faceted panels, searched by text, and
+ * zoomed/panned around freely. A detail pane shows the selected card's full
+ * information.
+ *
+ * Backed by PIXI.js for high-performance rendering, so it gracefully handles
+ * thousands of items. Consumers supply their own `cardRenderer` and
+ * `detailRenderer` to control card and detail content; the component handles
+ * grouping, filtering, panning, zooming, and selection internally.
+ *
+ * Use this for exploratory data analysis UIs over large collections (catalogs,
+ * inventories, telemetry samples). For tabular display, use {@link DataPage}
+ * or {@link DataTableForQuery}.
+ *
+ * @typeParam TItem - The item type contained in {@link PivotViewerProps.data}.
+ * @param props - {@link PivotViewerProps}.
+ */
 export function PivotViewer<TItem extends object>({
     data,
     dimensions,
diff --git a/Source/TimeMachine/EventsView.tsx b/Source/TimeMachine/EventsView.tsx
index 5f28ece..4a7740c 100644
--- a/Source/TimeMachine/EventsView.tsx
+++ b/Source/TimeMachine/EventsView.tsx
@@ -7,10 +7,25 @@ import type { Event } from './types';
 import { Properties } from './Properties';
 import './EventsView.css';
 
+/**
+ * Props for {@link EventsView}.
+ */
 interface EventsViewProps {
+    /** The events to display, in chronological order. */
     events: Event[];
 }
 
+/**
+ * Vertical timeline visualization of an ordered list of Cratis events.
+ * Renders each event on alternating sides of a central spine with its
+ * properties shown in a popup, and tracks scroll boundaries so up/down
+ * arrows appear only when there's content to scroll to.
+ *
+ * Used inside {@link TimeMachine} to show the events that produced a given
+ * read-model version, but can be reused for any event timeline UI.
+ *
+ * @param props - {@link EventsViewProps}.
+ */
 export const EventsView: React.FC<EventsViewProps> = ({ events }) => {
     // Use test data if no events provided
     const displayEvents = events.length > 0 ? events : [];
diff --git a/Source/TimeMachine/ReadModelView.tsx b/Source/TimeMachine/ReadModelView.tsx
index eb5f788..7985c22 100644
--- a/Source/TimeMachine/ReadModelView.tsx
+++ b/Source/TimeMachine/ReadModelView.tsx
@@ -5,14 +5,43 @@ import React, { useState } from 'react';
 import type { Version } from './types';
 import { Properties } from './Properties';
 
+/**
+ * Props for {@link ReadModelView}.
+ */
 interface ReadModelViewProps {
+    /** Ordered list of read-model versions to display. */
     versions: Version[];
+
+    /** Index of the currently-selected (committed) version. */
     selectedIndex: number;
+
+    /**
+     * Index of the currently-hovered version, or `null` when nothing is hovered.
+     * Used to preview a version without committing the selection.
+     */
     hoveredIndex: number | null;
+
+    /** Invoked when the user clicks a version card to select it. */
     onVersionSelect: (index: number) => void;
+
+    /**
+     * Invoked when the hover state over any card changes — true on enter,
+     * false on leave. Lets the parent coordinate the surrounding chrome with
+     * the hover state.
+     */
     onHoveringCardChange: (isHovering: boolean) => void;
 }
 
+/**
+ * Visual representation of a read-model's version history as a row of
+ * flippable "window" cards. Each card shows the read-model state at that
+ * version on its front face and can be flipped to reveal additional metadata.
+ *
+ * Selection and hover are externally controlled so the parent {@link TimeMachine}
+ * can synchronize the read-model view with the events timeline.
+ *
+ * @param props - {@link ReadModelViewProps}.
+ */
 export const ReadModelView: React.FC<ReadModelViewProps> = ({
     versions,
     selectedIndex,

From d54261a5ae6434305c771714bad1355bb162143d Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:42:42 +0200
Subject: [PATCH 09/23] Restructure package.json and re-export Provider from
 the root entry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bring the published package metadata in line with the actual shipping
surface and current React-library packaging best practices.

- Add `"sideEffects": ["**/*.css"]` so bundlers can tree-shake unused JS
  modules while still preserving the colocated CSS imports.
- Fix the broken `./CommandStepper` export — it pointed at
  `./dist/{esm,cjs}/CommandStepper/index.js` which does not exist. The
  compiled file lives at `./dist/{esm,cjs}/CommandDialog/CommandStepper.js`
  because the source resides in `CommandDialog/`.
- Add the three exports that were missing from the map even though their
  built indexes ship in dist: `./ObjectContentEditor`,
  `./ObjectNavigationalBar`, `./SchemaEditor`.
- Add the new `./tokens` stylesheet entry so consumers who only want the
  `--cratis-*` token layer (without the bundled Tailwind utilities) can
  `import '@cratis/components/tokens'`.
- Move `primereact`, `primeicons`, and `react-router-dom` from
  `dependencies` to `peerDependencies` to avoid duplicate copies in
  consumer apps and the resulting PrimeReact context fragmentation.
- Move `pixi.js`, `framer-motion`, and `allotment` to peerDependencies
  with `peerDependenciesMeta.optional = true` — they're only needed when
  the corresponding component (PivotViewer, animated panels, DataPage
  split panes) is actually used. Mirror them in devDependencies so the
  package can still typecheck and build locally.
- Re-export `CratisComponentsProvider`, `cratisDefaults`,
  `mergeCratisComponentsConfig`, and their types from the package root so
  `import { CratisComponentsProvider } from '@cratis/components'` works
  without consumers having to know about the `Common` subpath.
---
 Source/index.ts     | 10 +++++++++
 Source/package.json | 54 +++++++++++++++++++++++++++++++++++++--------
 2 files changed, 55 insertions(+), 9 deletions(-)

diff --git a/Source/index.ts b/Source/index.ts
index 119236e..aabe187 100644
--- a/Source/index.ts
+++ b/Source/index.ts
@@ -35,3 +35,13 @@ export {
     Types,
 };
 
+// Re-export the primary setup surface from the root so the recommended
+// `import { CratisComponentsProvider } from '@cratis/components'` works
+// without consumers having to know about the `Common` subpath.
+export {
+    CratisComponentsProvider,
+    cratisDefaults,
+    mergeCratisComponentsConfig,
+    type CratisComponentsConfig,
+    type CratisComponentsProviderProps,
+} from './Common/CratisComponentsProvider';
diff --git a/Source/package.json b/Source/package.json
index bdd1252..77e525f 100644
--- a/Source/package.json
+++ b/Source/package.json
@@ -17,6 +17,9 @@
     "main": "dist/cjs/index.js",
     "module": "dist/esm/index.js",
     "types": "dist/esm/index.d.ts",
+    "sideEffects": [
+        "**/*.css"
+    ],
     "exports": {
         "./package.json": "./package.json",
         ".": {
@@ -30,9 +33,9 @@
             "import": "./dist/esm/CommandDialog/index.js"
         },
         "./CommandStepper": {
-            "types": "./dist/esm/CommandStepper/index.d.ts",
-            "require": "./dist/cjs/CommandStepper/index.js",
-            "import": "./dist/esm/CommandStepper/index.js"
+            "types": "./dist/esm/CommandDialog/CommandStepper.d.ts",
+            "require": "./dist/cjs/CommandDialog/CommandStepper.js",
+            "import": "./dist/esm/CommandDialog/CommandStepper.js"
         },
         "./CommandForm": {
             "types": "./dist/esm/CommandForm/index.d.ts",
@@ -69,11 +72,26 @@
             "require": "./dist/cjs/Dropdown/index.js",
             "import": "./dist/esm/Dropdown/index.js"
         },
+        "./ObjectContentEditor": {
+            "types": "./dist/esm/ObjectContentEditor/index.d.ts",
+            "require": "./dist/cjs/ObjectContentEditor/index.js",
+            "import": "./dist/esm/ObjectContentEditor/index.js"
+        },
+        "./ObjectNavigationalBar": {
+            "types": "./dist/esm/ObjectNavigationalBar/index.d.ts",
+            "require": "./dist/cjs/ObjectNavigationalBar/index.js",
+            "import": "./dist/esm/ObjectNavigationalBar/index.js"
+        },
         "./PivotViewer": {
             "types": "./dist/esm/PivotViewer/index.d.ts",
             "require": "./dist/cjs/PivotViewer/index.js",
             "import": "./dist/esm/PivotViewer/index.js"
         },
+        "./SchemaEditor": {
+            "types": "./dist/esm/SchemaEditor/index.d.ts",
+            "require": "./dist/cjs/SchemaEditor/index.js",
+            "import": "./dist/esm/SchemaEditor/index.js"
+        },
         "./TimeMachine": {
             "types": "./dist/esm/TimeMachine/index.d.ts",
             "require": "./dist/cjs/TimeMachine/index.js",
@@ -89,7 +107,8 @@
             "require": "./dist/cjs/types/index.js",
             "import": "./dist/esm/types/index.js"
         },
-        "./styles": "./dist/esm/tailwind-utilities.css"
+        "./styles": "./dist/esm/tailwind-utilities.css",
+        "./tokens": "./dist/esm/tokens.css"
     },
     "scripts": {
         "prepare": "yarn g:build",
@@ -106,26 +125,43 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
+        "react-icons": "5.6.0",
+        "ts-deepmerge": "8.0.0",
+        "usehooks-ts": "3.1.1"
+    },
+    "devDependencies": {
         "allotment": "1.20.5",
         "framer-motion": "12.40.0",
         "pixi.js": "^8.17.1",
         "primeicons": "7.0.0",
         "primereact": "10.9.8",
-        "react-icons": "5.6.0",
         "react-router-dom": "7.15.1",
-        "ts-deepmerge": "8.0.0",
-        "usehooks-ts": "3.1.1"
-    },
-    "devDependencies": {
         "storybook": "^10.3.4"
     },
     "peerDependencies": {
         "@cratis/arc": "^20.3.1",
         "@cratis/arc.react": "^20.3.1",
         "@cratis/arc.vite": "^20.3.1",
+        "allotment": "^1.20.0",
+        "framer-motion": "^12.0.0",
+        "pixi.js": "^8.0.0",
+        "primeicons": "^7.0.0",
+        "primereact": "^10.9.0",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
+        "react-router-dom": "^7.0.0",
         "reflect-metadata": "0.2.2",
         "tsyringe": "4.10.0"
+    },
+    "peerDependenciesMeta": {
+        "allotment": {
+            "optional": true
+        },
+        "framer-motion": {
+            "optional": true
+        },
+        "pixi.js": {
+            "optional": true
+        }
     }
 }

From aaa2dda583f26ab7305a3b864cd524f2b66420a5 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 22:44:45 +0200
Subject: [PATCH 10/23] Rewrite README into a comprehensive styling guide with
 three paths
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the prior reference-only Styling section with a guide structured
around the three documented paths a consumer can choose between:

  A. PrimeReact-themed — fastest start; load a PrimeReact theme stylesheet
     and let the --cratis-* tokens cascade through.
  B. Cratis-themed — override --cratis-* tokens directly without loading a
     PrimeReact theme, optionally via Tailwind's @layer base + theme().
  C. Fully unstyled — disable PrimeReact's base styles entirely and ship
     visuals via a pt preset, your own CSS, or both.

Each path has a worked example pair (plain CSS and TailwindCSS), the full
--cratis-* token reference table, and concrete "Choose this when…" guidance.
Adds a "Mixing paths" section showing how to compose them (themed app with
one unstyled component, unstyled app with one themed island, scoped
dark-mode token overrides).

Also fix the available-subpaths list:
- Remove the stale `@cratis/components/EventModeling` claim — that path
  does not exist in the exports map and never has.
- Add the missing entries that do ship: CommandStepper, CommandForm/fields,
  ObjectContentEditor, ObjectNavigationalBar, SchemaEditor, Toolbar, types.
- Add a callout at the top of the Styling section pointing at the new
  Storybook styling toolbar so consumers can preview each path live.
- Update the install command and add the optional peer-dependency table to
  match the package.json restructure.
---
 Source/README.md | 443 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 440 insertions(+), 3 deletions(-)

diff --git a/Source/README.md b/Source/README.md
index b78b3a9..c9fcc08 100644
--- a/Source/README.md
+++ b/Source/README.md
@@ -23,11 +23,27 @@ The package provides dual CommonJS and ES Module builds with proper conditional
 ## Installation
 
 ```bash
-npm install @cratis/components
+npm install @cratis/components primereact primeicons react-router-dom
 # or
-yarn add @cratis/components
+yarn add @cratis/components primereact primeicons react-router-dom
 ```
 
+`primereact`, `primeicons`, and `react-router-dom` are peer dependencies —
+installing them in your app ensures a single copy is shared with the wrappers
+in this package. The `@cratis/arc*` packages and `react`/`react-dom` are also
+peer dependencies; you typically already have them.
+
+The following are **optional** peer dependencies, only required if you use the
+component that depends on them:
+
+| Component | Optional peer |
+|---|---|
+| `PivotViewer` | `pixi.js` |
+| `CommandStepper`, animated panels | `framer-motion` |
+| `DataPage` resizable layout | `allotment` |
+
+Install them only when you reach for the corresponding component.
+
 ## Usage
 
 ### Importing Components
@@ -46,16 +62,437 @@ import { TimeMachine, DataPage } from '@cratis/components';
 
 ### Available Subpath Exports
 
+Components:
+
+- `@cratis/components` — package root (re-exports `CratisComponentsProvider` and the namespaced component groups)
 - `@cratis/components/CommandDialog`
+- `@cratis/components/CommandStepper`
 - `@cratis/components/CommandForm`
+- `@cratis/components/CommandForm/fields`
 - `@cratis/components/Common`
 - `@cratis/components/DataPage`
 - `@cratis/components/DataTables`
 - `@cratis/components/Dialogs`
 - `@cratis/components/Dropdown`
-- `@cratis/components/EventModeling`
+- `@cratis/components/ObjectContentEditor`
+- `@cratis/components/ObjectNavigationalBar`
 - `@cratis/components/PivotViewer`
+- `@cratis/components/SchemaEditor`
 - `@cratis/components/TimeMachine`
+- `@cratis/components/Toolbar`
+- `@cratis/components/types`
+
+Stylesheets:
+
+- `@cratis/components/styles` — Tailwind utilities + Cratis CSS variable tokens (single stylesheet, recommended)
+- `@cratis/components/tokens` — only the `--cratis-*` CSS variable tokens (for consumers using their own utility CSS solution)
+
+## Styling
+
+This package ships primarily for its functionality and Arc integrations.
+Styling is designed to stay out of the way: pick the path that matches how
+much control you want, and the other layers stay invisible.
+
+> **Tip — see each path live:** every Storybook story includes a **Styling**
+> toolbar (paintbrush icon) that flips between the five modes corresponding to
+> the three paths below: *Lara Dark Blue*, *Lara Light Blue*, *Cratis-themed
+> (custom tokens)*, *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 — pick a path
+
+| Path | When | Effort | What you write |
+|---|---|---|---|
+| **A. PrimeReact-themed** | You want it to look good immediately and tweak from there. | Lowest | One CSS import + provider |
+| **B. Cratis-themed (no PrimeReact theme)** | You want a custom look but don't want to fight a third-party theme. | Low | Override `--cratis-*` tokens |
+| **C. Fully unstyled** | You're integrating into a tightly-controlled design system. | Highest | A `pt` preset (in CSS or Tailwind) |
+
+All three paths use the same one-line setup and remain switchable later — you
+won't repaint yourself into a corner.
+
+### One-line setup (every path)
+
+```tsx
+import '@cratis/components/styles';
+import { CratisComponentsProvider } from '@cratis/components';
+
+export const App = () => (
+    <CratisComponentsProvider>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+- `@cratis/components/styles` ships the Tailwind utility classes used inside
+  the package plus the `--cratis-*` CSS variable token layer that every
+  internal component reads from. (Use `@cratis/components/tokens` instead if
+  you're bringing your own Tailwind.)
+- `CratisComponentsProvider` is a thin wrapper over PrimeReact's
+  `PrimeReactProvider` so Cratis has one place to layer in defaults. Drop in
+  raw `PrimeReactProvider` if you'd rather.
+
+The three paths below differ only in **what else** you load on top of this
+setup.
+
+---
+
+### Path A — PrimeReact-themed (fastest start)
+
+Load any PrimeReact theme stylesheet alongside Cratis Components. The
+`--cratis-*` tokens cascade to PrimeReact's matching theme variables, so every
+component picks the theme up automatically.
+
+```tsx
+// 1. Theme first, then Cratis styles so any --cratis-* override wins.
+import 'primereact/resources/themes/lara-dark-blue/theme.css';
+import 'primeicons/primeicons.css';
+import '@cratis/components/styles';
+
+import { CratisComponentsProvider } from '@cratis/components';
+
+export const App = () => (
+    <CratisComponentsProvider>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+#### 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`:
+
+```css
+/* yourApp.css */
+.p-button {
+    border-radius: 999px;            /* pill buttons everywhere */
+}
+
+.dangerous-button {
+    background: var(--cratis-red-500);
+    color: white;
+}
+```
+
+```tsx
+<Button label="Delete" className="dangerous-button" />
+```
+
+#### Override a single component with Tailwind
+
+Pass Tailwind utility classes through the wrapper's `className` prop:
+
+```tsx
+<InputTextField value={c => c.name}
+                className="rounded-2xl bg-slate-900 text-slate-50" />
+
+<Dialog title="Confirm" className="shadow-2xl rounded-3xl">
+    {/* … */}
+</Dialog>
+```
+
+**Choose Path A when:** you're prototyping, building internal tools, or are
+happy with one of the prebuilt PrimeReact themes.
+
+---
+
+### Path B — Cratis-themed (no PrimeReact theme)
+
+Skip the PrimeReact theme stylesheet and define the look in one place by
+overriding `--cratis-*` tokens on `:root` (or any ancestor scope). The
+components render with structural defaults from the bundled stylesheet and
+pull every color, border, and surface from your tokens.
+
+#### With plain CSS
+
+```css
+/* tokens.override.css — imported once, anywhere after @cratis/components/styles */
+:root {
+    /* Surfaces */
+    --cratis-surface-0:        #0f172a;
+    --cratis-surface-100:      #1e293b;
+    --cratis-surface-ground:   #020617;
+    --cratis-surface-section:  #0f172a;
+    --cratis-surface-card:     #1e293b;
+    --cratis-surface-overlay:  #1e293b;
+    --cratis-surface-hover:    #334155;
+    --cratis-surface-border:   #334155;
+
+    /* Text */
+    --cratis-text-color:           #f8fafc;
+    --cratis-text-color-secondary: #94a3b8;
+
+    /* Brand */
+    --cratis-primary-color:      #38bdf8;
+    --cratis-primary-color-text: #0b1220;
+    --cratis-primary-500:        #38bdf8;
+    --cratis-primary-600:        #0ea5e9;
+
+    /* Selection / accents */
+    --cratis-highlight-bg:         #1e40af;
+    --cratis-highlight-text-color: #ffffff;
+    --cratis-red-500:              #ef4444;
+    --cratis-green-500:            #22c55e;
+    --cratis-orange-500:           #f97316;
+
+    /* Geometry */
+    --cratis-border-radius: 10px;
+}
+```
+
+```tsx
+import '@cratis/components/styles';
+import './tokens.override.css';   // <-- after, so it wins
+```
+
+#### Scoped (dark-on-light, light-on-dark, etc.)
+
+Tokens cascade, so any ancestor scope works:
+
+```css
+.dark-zone {
+    --cratis-surface-card:   #0b1220;
+    --cratis-text-color:     #f8fafc;
+    --cratis-primary-color:  #60a5fa;
+}
+```
+
+```tsx
+<div className="dark-zone">
+    <Dialog title="Always dark">…</Dialog>
+</div>
+```
+
+#### With Tailwind CSS
+
+Tailwind's `@layer base` is the idiomatic spot — write tokens once and
+Tailwind handles cascade and dark mode:
+
+```css
+/* app.css */
+@import "tailwindcss";
+@import "@cratis/components/styles";
+
+@layer base {
+    :root {
+        --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 {
+        --cratis-surface-card:   theme('colors.slate.900');
+        --cratis-text-color:     theme('colors.slate.100');
+    }
+}
+```
+
+#### Complete token reference
+
+| 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` |
+
+Tokens default to PrimeReact's matching theme variables, so Path A and Path B
+mix cleanly — load a PrimeReact theme to get a baseline, then override the
+specific tokens you want to change.
+
+**Choose Path B when:** you want a custom look, you're shipping multiple
+themes (light/dark/brand variants), or you don't want a PrimeReact theme in
+your bundle.
+
+---
+
+### Path C — Fully unstyled (you own every visual)
+
+Turn off every PrimeReact base style at the provider and supply visuals
+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';   // tokens + Tailwind utilities still useful for spacing/layout
+import { CratisComponentsProvider } from '@cratis/components';
+
+export const App = () => (
+    <CratisComponentsProvider value={{ unstyled: true, pt: globalPt }}>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+#### A `pt` preset in plain CSS
+
+Attach a `className` from your own stylesheet via a global preset:
+
+```ts
+// pt-preset.ts
+export const globalPt = {
+    button: {
+        root: { className: 'my-btn' },
+    },
+    dialog: {
+        root: { className: 'my-dialog' },
+        header: { className: 'my-dialog__header' },
+        content: { className: 'my-dialog__body' },
+    },
+    inputtext: {
+        root: { className: 'my-input' },
+    },
+} as const;
+```
+
+```css
+/* yourApp.css */
+.my-btn {
+    display: inline-flex;
+    align-items: center;
+    padding: 0.5rem 1rem;
+    background: var(--cratis-primary-color);
+    color: var(--cratis-primary-color-text);
+    border: none;
+    border-radius: var(--cratis-border-radius);
+    cursor: pointer;
+}
+
+.my-dialog__header {
+    padding: 1rem 1.25rem;
+    background: var(--cratis-surface-card);
+    border-bottom: 1px solid var(--cratis-surface-border);
+    font-weight: 600;
+}
+```
+
+#### A `pt` preset in Tailwind
+
+Same shape, Tailwind utilities as the class strings:
+
+```ts
+// pt-preset.ts
+export const globalPt = {
+    button: {
+        root: { className: 'inline-flex items-center px-4 py-2 rounded-lg bg-sky-500 text-white hover:bg-sky-400 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' },
+    },
+    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' },
+    },
+} as const;
+```
+
+#### Per-instance overrides
+
+Anything global can be overridden per-instance — useful when one component
+needs to look different:
+
+```tsx
+<Dialog
+    title="Brand callout"
+    pt={{ root: { className: 'rounded-none' },
+          header: { className: 'bg-pink-600 text-white' } }}>
+    …
+</Dialog>
+
+<InputTextField value={c => c.name}
+                pt={{ root: { className: 'border-2 border-pink-500' } }} />
+```
+
+#### Composite components in unstyled mode
+
+`DataPage` and `StepperCommandDialog` compose multiple PrimeReact widgets and
+expose explicit per-slot props. The global `pt` reaches every internal widget;
+per-instance overrides target the inner slot directly:
+
+```tsx
+<DataPage<AllAuthors, Author, never>
+    title="Authors" query={AllAuthors}
+    tablePt={{ table: { className: 'min-w-full divide-y divide-slate-700' } }}
+    menubarPt={{ root: { className: 'px-3 py-2 bg-slate-900' } }}>
+    <DataPage.MenuItems>…</DataPage.MenuItems>
+    <DataPage.Columns>…</DataPage.Columns>
+</DataPage>
+
+<StepperCommandDialog<RegisterOrder> command={RegisterOrder} title="New order"
+    /* pt targets the Stepper */
+    pt={{ stepperpanel: { content: { className: 'pt-6' } } }}
+    /* dialogPt targets the outer Dialog */
+    dialogPt={{ header: { className: 'bg-slate-900' } }}>
+    …
+</StepperCommandDialog>
+```
+
+`ObjectContentEditor`, `ObjectNavigationalBar`, and `SchemaEditor` accept only
+`className` on the root — restyle their internals via the **global** `pt`
+preset.
+
+**Choose Path C when:** you have a design system to honor, you're matching a
+brand kit, or you want zero PrimeReact CSS in the final bundle.
+
+---
+
+### Mixing paths
+
+The paths compose, so you don't have to pick 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** — use Path B tokens scoped to `.dark` and toggle the class on
+  the root element. Every internal component (including those used in Path C)
+  follows automatically because they all read from the same tokens.
+
+### Per-component `pt` cheat sheet
+
+Three patterns, depending on how much PrimeReact a wrapper composes:
+
+1. **Single-widget wrappers** — `Dialog`, every `CommandForm` field, the
+   underlying `DataTable`/`Paginator` exposed by `DataTableForQuery` /
+   `DataTableForObservableQuery`, and `Dropdown` forward `pt`, `ptOptions`,
+   `unstyled`, and `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) — each slot has `*PtOptions`, `*Unstyled`, and `*ClassName`
+   siblings.
+3. **Large composites** — `ObjectContentEditor`, `ObjectNavigationalBar`,
+   `SchemaEditor` expose `className` only; restyle internals via the global
+   `pt` preset.
+
+### What is *not* fully pass-through
+
+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.
+
+`BusyIndicatorDialog` only honors the global `pt` set via
+`CratisComponentsProvider`; it does not accept per-instance `pt` because its
+request type is owned by `@cratis/arc.react`.
 
 ## Troubleshooting
 

From 69d0440b41deffc4813281e751a21fe3263ba688 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 23:04:58 +0200
Subject: [PATCH 11/23] Add multi-path styling toolbar to Storybook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extend the Storybook theme toolbar from one option (PrimeReact theme) to
five entries that line up with the three documented styling paths in the
README, so consumers can see the same component rendered under each setup
by toggling a single dropdown.

Toolbar entries:

  - Path A — Lara Dark Blue        (PrimeReact dark theme + provider defaults)
  - Path A — Lara Light Blue       (PrimeReact light theme)
  - Path B — Cratis-themed         (no PrimeReact theme; slate surfaces + sky brand via scoped --cratis-* overrides)
  - Path C — Unstyled (bare)       (provider unstyled=true, no pt — shows raw structural rendering)
  - Path C — Unstyled + Tailwind pt (provider unstyled=true with sample tailwindPtPreset)

The decorator toggles three things per mode: the injected PrimeReact theme
link, a body class that activates the right --cratis-* token override, and
the `value` passed to `CratisComponentsProvider` (unstyled + pt).

Also fixes a latent bug in the previous storybook setup: the neutral
fallback tokens were declared at `:root` unconditionally and so blocked the
loaded PrimeReact theme from driving --cratis-* via the cascade in the dark/
light modes. Scoping the fallbacks under body classes lets the theme cascade
naturally in Path A modes.

`pt-preset.ts` ships a sample Tailwind-utility-class pt preset covering
Button, Dialog, InputText, InputTextarea, InputNumber, Dropdown, Checkbox,
DataTable, Paginator, and Menubar — Storybook-only, intended as a starting
point consumers can fork into their own apps.
---
 Source/.storybook/preview.css  | 126 ++++++++++++++++++++---
 Source/.storybook/preview.js   |  79 +++++++++++++--
 Source/.storybook/pt-preset.ts | 177 +++++++++++++++++++++++++++++++++
 3 files changed, 360 insertions(+), 22 deletions(-)
 create mode 100644 Source/.storybook/pt-preset.ts

diff --git a/Source/.storybook/preview.css b/Source/.storybook/preview.css
index 50215c6..000fcac 100644
--- a/Source/.storybook/preview.css
+++ b/Source/.storybook/preview.css
@@ -1,10 +1,110 @@
 /* 1. Tailwind (includes preflight reset) — must come first */
 @import "tailwindcss";
-/* 2. PrimeReact theme is injected dynamically by the Storybook theme decorator */
+/* 2. PrimeReact theme is injected dynamically by the Storybook theme decorator
+ *    (omitted when the decorator's 'Cratis-themed' or 'Unstyled' modes are selected) */
+
+/*
+ * Storybook-only token overrides per styling path.
+ *
+ * In real consumer apps the consumer either loads a PrimeReact theme (which
+ * populates the underlying --surface-*, --text-color, etc., and the --cratis-*
+ * tokens forward to them) or overrides --cratis-* tokens themselves. Storybook
+ * needs a working baseline for every documented path so each toolbar mode is
+ * visually intelligible.
+ *
+ * The decorator toggles one of the body classes below, so the right token set
+ * wins for each mode. When no class is set we leave tokens alone so the
+ * loaded PrimeReact theme can drive --cratis-* through tokens.css.
+ */
+
+/* Path B — Cratis-themed (no PrimeReact theme): slate surfaces, sky brand. */
+body.cratis-themed {
+    --cratis-surface-0:        #1e293b;
+    --cratis-surface-100:      #1e293b;
+    --cratis-surface-ground:   #020617;
+    --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-primary-300:        #7dd3fc;
+    --cratis-primary-400:        #38bdf8;
+    --cratis-primary-500:        #0ea5e9;
+    --cratis-primary-600:        #0284c7;
+
+    --cratis-highlight-bg:         #1e40af;
+    --cratis-highlight-text-color: #ffffff;
+
+    --cratis-green-500:  #22c55e;
+    --cratis-orange-500: #f97316;
+    --cratis-red-500:    #ef4444;
+
+    --cratis-border-radius: 10px;
+}
+
+/*
+ * Path C bare — Unstyled with no consumer styling. PrimeReact base styles are
+ * disabled at the provider; tokens are intentionally set to neutral dark
+ * grays so structural elements (borders, text) remain readable but no brand
+ * personality leaks in. Consumers see what they'd start from.
+ */
+body.cratis-unstyled-bare {
+    --cratis-surface-0:        #1f2937;
+    --cratis-surface-100:      #1f2937;
+    --cratis-surface-ground:   #111827;
+    --cratis-surface-section:  #111827;
+    --cratis-surface-card:     #1f2937;
+    --cratis-surface-overlay:  #1f2937;
+    --cratis-surface-hover:    #374151;
+    --cratis-surface-border:   #374151;
+
+    --cratis-text-color:           #f3f4f6;
+    --cratis-text-color-secondary: #9ca3af;
+
+    --cratis-primary-color:      #60a5fa;
+    --cratis-primary-color-text: #0b1220;
+    --cratis-primary-300:        #93c5fd;
+    --cratis-primary-400:        #60a5fa;
+    --cratis-primary-500:        #3b82f6;
+    --cratis-primary-600:        #2563eb;
+
+    --cratis-highlight-bg:         #1e3a8a;
+    --cratis-highlight-text-color: #ffffff;
+
+    --cratis-green-500:  #22c55e;
+    --cratis-orange-500: #f97316;
+    --cratis-red-500:    #ef4444;
+
+    --cratis-border-radius: 6px;
+}
+
+/*
+ * Path C with Tailwind pt — Unstyled, with a sample pt preset applied. The
+ * pt preset (see .storybook/pt-preset.ts) carries every visual; tokens are
+ * still useful for any wrapper that uses --cratis-* directly (e.g.
+ * ObjectNavigationalBar's border).
+ */
+body.cratis-unstyled-pt {
+    --cratis-surface-border: #334155;
+    --cratis-text-color:     #f8fafc;
+    --cratis-text-color-secondary: #94a3b8;
+    --cratis-primary-color:      #38bdf8;
+    --cratis-primary-color-text: #0b1220;
+    --cratis-red-500:    #ef4444;
+    --cratis-green-500:  #22c55e;
+    --cratis-orange-500: #f97316;
+    --cratis-border-radius: 10px;
+}
 
 html, body {
-  background-color: var(--surface-ground);
-  color: var(--text-color);
+  background-color: var(--cratis-surface-ground, #111827);
+  color: var(--cratis-text-color, #f3f4f6);
   min-height: 100vh;
   margin: 0;
   font-family: Inter, Avenir, Helvetica, Arial, sans-serif;
@@ -19,24 +119,24 @@ html, body {
   justify-content: center;
   min-height: 100vh;
   padding: 1rem;
-  background-color: var(--surface-ground);
+  background-color: var(--cratis-surface-ground, #111827);
 }
 
 /* Utility classes matching Chronicle Workbench */
 .highlight {
-  background-color: var(--highlight-bg);
-  color: var(--highlight-text-color);
+  background-color: var(--cratis-highlight-bg);
+  color: var(--cratis-highlight-text-color);
 }
 
 .contentBackground {
-  background-color: var(--surface-0);
+  background-color: var(--cratis-surface-0);
 }
 
 .panel {
-  background: var(--surface-card);
-  border: 1px solid var(--surface-border);
-  border-radius: var(--border-radius);
-  color: var(--text-color);
+  background: var(--cratis-surface-card);
+  border: 1px solid var(--cratis-surface-border);
+  border-radius: var(--cratis-border-radius);
+  color: var(--cratis-text-color);
   display: flex;
   flex-direction: column;
   min-height: 0;
@@ -48,7 +148,7 @@ html, body {
   min-height: 0;
 }
 
-/* DataTable layout helpers */
+/* DataTable layout helpers — only effective when the PrimeReact theme is loaded */
 .p-datatable {
   display: flex;
   flex-direction: column;
@@ -80,5 +180,5 @@ html, body {
 }
 
 .p-menubar {
-  border: 1px solid var(--surface-border) !important;
+  border: 1px solid var(--cratis-surface-border) !important;
 }
diff --git a/Source/.storybook/preview.js b/Source/.storybook/preview.js
index 80b4556..dc93955 100644
--- a/Source/.storybook/preview.js
+++ b/Source/.storybook/preview.js
@@ -6,18 +6,62 @@ import 'primeicons/primeicons.css';
 import './preview.css';
 import darkThemeUrl from 'primereact/resources/themes/lara-dark-blue/theme.css?url';
 import lightThemeUrl from 'primereact/resources/themes/lara-light-blue/theme.css?url';
+import { CratisComponentsProvider } from '../Common/CratisComponentsProvider';
+import { tailwindPtPreset } from './pt-preset';
+
+/**
+ * Each toolbar entry maps to one of the three documented styling paths in
+ * Source/README.md. Stories don't need to change — every mode renders the
+ * same component tree under a different provider/theme/token combination.
+ */
+const STYLING_MODES = {
+    'lara-dark': {
+        title: 'Path A — Lara Dark Blue',
+        themeUrl: darkThemeUrl,
+        bodyClass: null,
+        providerValue: {},
+    },
+    'lara-light': {
+        title: 'Path A — Lara Light Blue',
+        themeUrl: lightThemeUrl,
+        bodyClass: null,
+        providerValue: {},
+    },
+    'cratis-themed': {
+        title: 'Path B — Cratis-themed (custom tokens)',
+        themeUrl: null,
+        bodyClass: 'cratis-themed',
+        providerValue: {},
+    },
+    'unstyled-bare': {
+        title: 'Path C — Unstyled (bare structure)',
+        themeUrl: null,
+        bodyClass: 'cratis-unstyled-bare',
+        providerValue: { unstyled: true },
+    },
+    'unstyled-pt': {
+        title: 'Path C — Unstyled + Tailwind pt',
+        themeUrl: null,
+        bodyClass: 'cratis-unstyled-pt',
+        providerValue: { unstyled: true, pt: tailwindPtPreset },
+    },
+};
+
+const ALL_BODY_CLASSES = Object.values(STYLING_MODES)
+    .map(mode => mode.bodyClass)
+    .filter(Boolean);
 
 export const globalTypes = {
     theme: {
-        name: 'Theme',
-        description: 'PrimeReact theme',
-        defaultValue: 'dark',
+        name: 'Styling',
+        description: 'Which README styling path to render the story under',
+        defaultValue: 'lara-dark',
         toolbar: {
             icon: 'paintbrush',
-            items: [
-                { value: 'dark', title: 'Lara Dark Blue' },
-                { value: 'light', title: 'Lara Light Blue' },
-            ],
+            items: Object.entries(STYLING_MODES).map(([value, mode]) => ({
+                value,
+                title: mode.title,
+            })),
             showName: true,
         },
     },
@@ -25,6 +69,10 @@ export const globalTypes = {
 
 function applyThemeLink(href) {
     let link = document.getElementById('primereact-theme');
+    if (href === null) {
+        if (link) link.remove();
+        return;
+    }
     if (!link) {
         link = document.createElement('link');
         link.id = 'primereact-theme';
@@ -34,10 +82,23 @@ function applyThemeLink(href) {
     if (link.href !== href) link.href = href;
 }
 
+function applyBodyClass(className) {
+    document.body.classList.remove(...ALL_BODY_CLASSES);
+    if (className) document.body.classList.add(className);
+}
+
 export const decorators = [
     (Story, context) => {
-        applyThemeLink(context.globals.theme === 'light' ? lightThemeUrl : darkThemeUrl);
-        return React.createElement(Story);
+        const mode = STYLING_MODES[context.globals.theme] ?? STYLING_MODES['lara-dark'];
+
+        applyThemeLink(mode.themeUrl);
+        applyBodyClass(mode.bodyClass);
+
+        return React.createElement(
+            CratisComponentsProvider,
+            { value: mode.providerValue },
+            React.createElement(Story)
+        );
     },
 ];
 
diff --git a/Source/.storybook/pt-preset.ts b/Source/.storybook/pt-preset.ts
new file mode 100644
index 0000000..56ee1b5
--- /dev/null
+++ b/Source/.storybook/pt-preset.ts
@@ -0,0 +1,177 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Sample PrimeReact `pt` (pass-through) preset that demonstrates the Path C
+ * styling story from the README: drop into `CratisComponentsProvider` with
+ * `unstyled: true`, and every covered PrimeReact widget picks up a fresh look
+ * built entirely from Tailwind utility classes.
+ *
+ * This file is Storybook-only and not part of the published package. Treat it
+ * as a starting point you can fork into your own app.
+ */
+
+const surface = 'bg-slate-900 text-slate-50';
+const border = 'border border-slate-700';
+const focusRing = 'focus:outline-none focus-visible:ring-2 focus-visible:ring-sky-400';
+
+export const tailwindPtPreset = {
+    button: {
+        root: {
+            className: [
+                'inline-flex items-center justify-center gap-2',
+                'px-4 py-2 rounded-lg font-medium',
+                'bg-sky-500 text-white',
+                'hover:bg-sky-400 active:bg-sky-600',
+                'disabled:opacity-50 disabled:cursor-not-allowed',
+                'transition-colors',
+                focusRing,
+            ].join(' '),
+        },
+        label: { className: 'whitespace-nowrap' },
+        icon: { className: 'shrink-0' },
+    },
+
+    inputtext: {
+        root: {
+            className: [
+                'w-full px-3 py-2 rounded-md',
+                surface, border,
+                'placeholder:text-slate-400',
+                'focus:border-sky-400',
+                focusRing,
+            ].join(' '),
+        },
+    },
+
+    inputtextarea: {
+        root: {
+            className: [
+                'w-full px-3 py-2 rounded-md',
+                surface, border,
+                'placeholder:text-slate-400 resize-y',
+                'focus:border-sky-400',
+                focusRing,
+            ].join(' '),
+        },
+    },
+
+    inputnumber: {
+        root: { className: 'w-full' },
+        input: {
+            root: {
+                className: [
+                    'w-full px-3 py-2 rounded-md',
+                    surface, border,
+                    'focus:border-sky-400',
+                    focusRing,
+                ].join(' '),
+            },
+        },
+    },
+
+    dropdown: {
+        root: {
+            className: [
+                'w-full inline-flex items-center justify-between gap-2',
+                'px-3 py-2 rounded-md cursor-pointer',
+                surface, border,
+                'hover:border-slate-500',
+                focusRing,
+            ].join(' '),
+        },
+        input: { className: 'flex-1 truncate text-left' },
+        trigger: { className: 'shrink-0 text-slate-400' },
+        panel: {
+            className: [
+                'mt-1 rounded-md shadow-xl overflow-hidden',
+                surface, border,
+            ].join(' '),
+        },
+        item: {
+            className: 'px-3 py-2 cursor-pointer hover:bg-slate-800',
+        },
+    },
+
+    checkbox: {
+        root: { className: 'inline-flex items-center' },
+        box: {
+            className: [
+                'w-4 h-4 rounded',
+                'border border-slate-500 bg-slate-800',
+                'data-[p-highlight=true]:bg-sky-500 data-[p-highlight=true]:border-sky-500',
+                focusRing,
+            ].join(' '),
+        },
+        icon: { className: 'text-white text-xs' },
+    },
+
+    dialog: {
+        root: {
+            className: [
+                'rounded-2xl shadow-2xl overflow-hidden',
+                surface,
+            ].join(' '),
+        },
+        header: {
+            className: [
+                'flex items-center justify-between gap-4',
+                'px-5 py-3 font-semibold',
+                'bg-slate-800 text-slate-50 border-b border-slate-700',
+            ].join(' '),
+        },
+        headerTitle: { className: 'text-base' },
+        closeButton: {
+            className: 'p-1 rounded hover:bg-slate-700 transition-colors',
+        },
+        content: {
+            className: 'p-5 bg-slate-900 text-slate-100',
+        },
+        footer: {
+            className: 'px-5 py-3 bg-slate-800 border-t border-slate-700 flex justify-end gap-2',
+        },
+        mask: {
+            className: 'bg-slate-950/70 backdrop-blur-sm',
+        },
+    },
+
+    datatable: {
+        root: { className: 'w-full' },
+        table: { className: 'w-full text-sm' },
+        thead: {
+            className: 'bg-slate-800 text-slate-300 uppercase text-xs tracking-wider',
+        },
+        headerRow: { className: 'border-b border-slate-700' },
+        headerCell: { className: 'px-3 py-2 text-left font-medium' },
+        tbody: {
+            className: 'divide-y divide-slate-800',
+        },
+        bodyRow: {
+            className: [
+                'hover:bg-slate-800/60 data-[p-highlight=true]:bg-sky-500/10',
+                'data-[p-highlight=true]:text-sky-100',
+                'transition-colors',
+            ].join(' '),
+        },
+        bodyCell: { className: 'px-3 py-2 text-slate-100' },
+    },
+
+    paginator: {
+        root: {
+            className: 'flex items-center justify-end gap-1 px-3 py-2 bg-slate-800 border-t border-slate-700',
+        },
+        pageButton: {
+            className: 'px-3 py-1 rounded hover:bg-slate-700 data-[p-highlight=true]:bg-sky-500 data-[p-highlight=true]:text-white',
+        },
+    },
+
+    menubar: {
+        root: {
+            className: 'flex items-center gap-1 px-3 py-2 bg-slate-800 border-b border-slate-700',
+        },
+        menuitem: { className: 'rounded' },
+        action: {
+            className: 'inline-flex items-center gap-2 px-3 py-1.5 rounded hover:bg-slate-700 cursor-pointer',
+        },
+    },
+} as const;

From 17d7de612cd5787452217cbaa62499425d9a183d Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 23:26:28 +0200
Subject: [PATCH 12/23] Clean up workspace dependencies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drop entries that are unused, duplicated, or misclassified across the
workspace root and the published Source package.

Unused at runtime:
- Remove `react-router-dom` from the published package's dependencies and
  peer dependencies entirely (and from the install instructions in the
  README). No file in the published surface imports it.
- Remove `usehooks-ts` from the published package's runtime dependencies.
  No file in the published surface imports it.
- Remove `@types/leaflet` from the workspace root devDependencies. No file
  imports anything from Leaflet.
- Remove `rollup-plugin-copy` from the workspace root devDependencies. No
  rollup config references it.

Duplicated across workspaces:
- Remove `storybook` from the published package's devDependencies. The
  workspace root already lists it at the current pin (`^10.4.1`); the local
  override (`^10.3.4`) just lagged behind.

Misclassified:
- Move `@cratis/arc.vite` from peerDependencies to devDependencies in the
  published Source package. It is only imported by `Source/vite.config.ts`
  (the local dev / storybook config). Nothing in the published runtime
  references it, so we should not promise consumers they need to provide
  it.

Storybook 8 plugin in a Storybook 10 setup:
- Remove `@storybook/addon-storysource@8.6.14` from the root devDependencies
  and drop its entry from `.storybook/main.ts`. The addon shipped against
  Storybook 8 internals and was incompatible with the Storybook 10 host
  registered alongside it. (Dropping the addon does not fix the pre-existing
  lightningcss `Invalid empty selector` build-storybook failure — that lives
  elsewhere in the CSS processing pipeline — but it removes one source of
  version drift.)
---
 Source/.storybook/main.ts |  4 +---
 Source/README.md          | 12 ++++++------
 Source/package.json       | 10 +++-------
 package.json              |  7 ++-----
 4 files changed, 12 insertions(+), 21 deletions(-)

diff --git a/Source/.storybook/main.ts b/Source/.storybook/main.ts
index 6048360..5ec4cfa 100644
--- a/Source/.storybook/main.ts
+++ b/Source/.storybook/main.ts
@@ -11,9 +11,7 @@ const config: StorybookConfig = {
     '!../dist/**',
     '!../storybook-static/**'
   ],
-  addons: [
-    '@storybook/addon-storysource'
-  ],
+  addons: [],
   framework: {
     name: '@storybook/react-vite',
     options: {}
diff --git a/Source/README.md b/Source/README.md
index c9fcc08..786896c 100644
--- a/Source/README.md
+++ b/Source/README.md
@@ -23,15 +23,15 @@ The package provides dual CommonJS and ES Module builds with proper conditional
 ## Installation
 
 ```bash
-npm install @cratis/components primereact primeicons react-router-dom
+npm install @cratis/components primereact primeicons
 # or
-yarn add @cratis/components primereact primeicons react-router-dom
+yarn add @cratis/components primereact primeicons
 ```
 
-`primereact`, `primeicons`, and `react-router-dom` are peer dependencies —
-installing them in your app ensures a single copy is shared with the wrappers
-in this package. The `@cratis/arc*` packages and `react`/`react-dom` are also
-peer dependencies; you typically already have them.
+`primereact` and `primeicons` are peer dependencies — installing them in your
+app ensures a single copy is shared with the wrappers in this package. The
+`@cratis/arc*` packages and `react`/`react-dom` are also peer dependencies;
+you typically already have them.
 
 The following are **optional** peer dependencies, only required if you use the
 component that depends on them:
diff --git a/Source/package.json b/Source/package.json
index 77e525f..d1d8542 100644
--- a/Source/package.json
+++ b/Source/package.json
@@ -126,22 +126,19 @@
     },
     "dependencies": {
         "react-icons": "5.6.0",
-        "ts-deepmerge": "8.0.0",
-        "usehooks-ts": "3.1.1"
+        "ts-deepmerge": "8.0.0"
     },
     "devDependencies": {
+        "@cratis/arc.vite": "^20.3.1",
         "allotment": "1.20.5",
         "framer-motion": "12.40.0",
         "pixi.js": "^8.17.1",
         "primeicons": "7.0.0",
-        "primereact": "10.9.8",
-        "react-router-dom": "7.15.1",
-        "storybook": "^10.3.4"
+        "primereact": "10.9.8"
     },
     "peerDependencies": {
         "@cratis/arc": "^20.3.1",
         "@cratis/arc.react": "^20.3.1",
-        "@cratis/arc.vite": "^20.3.1",
         "allotment": "^1.20.0",
         "framer-motion": "^12.0.0",
         "pixi.js": "^8.0.0",
@@ -149,7 +146,6 @@
         "primereact": "^10.9.0",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
-        "react-router-dom": "^7.0.0",
         "reflect-metadata": "0.2.2",
         "tsyringe": "4.10.0"
     },
diff --git a/package.json b/package.json
index 28699ab..019fee4 100644
--- a/package.json
+++ b/package.json
@@ -27,14 +27,13 @@
     "version": "0.0.0",
     "packageManager": "yarn@4.5.3",
     "devDependencies": {
-        "@cratis/arc": "^20.28.0",
-        "@cratis/arc.react": "^20.28.0",
+        "@cratis/arc": "^20.33.1",
+        "@cratis/arc.react": "^20.33.1",
         "@cratis/arc.vite": "^20.28.0",
         "@eslint/eslintrc": "^3.3.5",
         "@eslint/js": "^10.0.1",
         "@rollup/plugin-node-resolve": "^16.0.3",
         "@rollup/plugin-typescript": "^12.3.0",
-        "@storybook/addon-storysource": "8.6.14",
         "@storybook/react": "^10.4.1",
         "@storybook/react-vite": "^10.4.1",
         "@tailwindcss/postcss": "^4.3.0",
@@ -42,7 +41,6 @@
         "@tony.ganchev/eslint-plugin-header": "^3.4.4",
         "@types/chai": "^5.2.3",
         "@types/chai-as-promised": "^8.0.2",
-        "@types/leaflet": "^1.9.21",
         "@types/mocha": "^10.0.10",
         "@types/node": "^25.9.1",
         "@types/react": "^19.2.15",
@@ -74,7 +72,6 @@
         "react-dom": "^19.2.6",
         "reflect-metadata": "0.2.2",
         "rollup": "^4.60.4",
-        "rollup-plugin-copy": "^3.5.0",
         "rollup-plugin-peer-deps-external": "^2.2.4",
         "sinon": "^22.0.0",
         "sinon-chai": "^4.0.1",

From 8d0d1551cef7ce1cdac8bdbb3e67ba934cc4e444 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Thu, 28 May 2026 23:46:28 +0200
Subject: [PATCH 13/23] Correct Path B framing: PrimeReact theme + palette
 override, not tokens-only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous Path B description ("Cratis-themed without a PrimeReact theme")
was misleading and the Storybook mode that reflected it produced the
visually-broken bare-bones rendering captured in review.

The root cause: in PrimeReact 10 every widget's structural CSS (padding,
borders, dialog frame, focus rings, button shapes) ships inside the theme
file. There is no separate primitives stylesheet. So a setup without any
PrimeReact theme has no widget chrome at all — components render as the raw
HTML primitives the browser supplies by default.

The --cratis-* tokens are a Cratis-scoped tint layer for surfaces *our*
wrappers own (validation error text, the FormElement addon, breadcrumb
borders, etc.) — they are not, by themselves, sufficient to skin PrimeReact
widgets. PrimeReact widgets read --surface-card / --text-color /
--primary-color / etc. directly, never the --cratis-* siblings.

Reframe Path B as "Themed with custom palette": a PrimeReact theme provides
the structural baseline, and the consumer overrides PrimeReact's own
variables (--surface-card, --text-color, --primary-color, …) on :root to
retint every widget. The --cratis-* tokens follow along through tokens.css's
cascade, and can be overridden independently when Cratis-scoped surfaces
should differ from PrimeReact widgets.

- Storybook decorator: Path B mode now loads Lara Dark Blue as the
  structural baseline and the body.cratis-themed class overrides PrimeReact
  variables (plus a few --cratis-* siblings) to produce the slate/sky palette.
- README: rewrite the Path B section with accurate CSS (overrides
  PrimeReact variables, not just --cratis-*), an explanatory call-out about
  why a PrimeReact theme is still in Paths A and B, and a clarifying
  "What --cratis-* tokens are for" subsection.
- Mixing paths > Dark mode example updated to use the same approach.
---
 Source/.storybook/preview.css |  74 +++++++++------
 Source/.storybook/preview.js  |   8 +-
 Source/README.md              | 163 +++++++++++++++++++++-------------
 3 files changed, 153 insertions(+), 92 deletions(-)

diff --git a/Source/.storybook/preview.css b/Source/.storybook/preview.css
index 000fcac..f52cb54 100644
--- a/Source/.storybook/preview.css
+++ b/Source/.storybook/preview.css
@@ -17,35 +17,57 @@
  * loaded PrimeReact theme can drive --cratis-* through tokens.css.
  */
 
-/* Path B — Cratis-themed (no PrimeReact theme): slate surfaces, sky brand. */
+/*
+ * Path B — Themed with custom palette. A PrimeReact theme (Lara Dark Blue in
+ * Storybook) supplies the structural chrome. This block then overrides
+ * PrimeReact's own variables so every widget repaints in slate/sky, with the
+ * --cratis-* siblings updated in parallel so Cratis-scoped surfaces follow
+ * suit.
+ *
+ * In a consumer app the same pattern would live in the consumer's own CSS,
+ * applied either on :root or scoped to a region.
+ */
 body.cratis-themed {
-    --cratis-surface-0:        #1e293b;
-    --cratis-surface-100:      #1e293b;
-    --cratis-surface-ground:   #020617;
-    --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;
-
+    /* PrimeReact theme 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;
+    --primary-300:        #7dd3fc;
+    --primary-400:        #38bdf8;
+    --primary-500:        #0ea5e9;
+    --primary-600:        #0284c7;
+
+    --highlight-bg:         #1e40af;
+    --highlight-text-color: #ffffff;
+
+    --green-500:  #22c55e;
+    --orange-500: #f97316;
+    --red-500:    #ef4444;
+
+    --border-radius: 10px;
+
+    /* --cratis-* tokens default to var(--surface-*) etc. via tokens.css, so
+     * the overrides above flow through automatically. The explicit settings
+     * below let a consumer tint Cratis-scoped surfaces (validation errors,
+     * the FormElement addon, breadcrumb borders) independently if they want
+     * to make Cratis surfaces visually distinct from PrimeReact widgets. */
     --cratis-primary-color:      #38bdf8;
     --cratis-primary-color-text: #0b1220;
-    --cratis-primary-300:        #7dd3fc;
-    --cratis-primary-400:        #38bdf8;
-    --cratis-primary-500:        #0ea5e9;
-    --cratis-primary-600:        #0284c7;
-
-    --cratis-highlight-bg:         #1e40af;
-    --cratis-highlight-text-color: #ffffff;
-
-    --cratis-green-500:  #22c55e;
-    --cratis-orange-500: #f97316;
-    --cratis-red-500:    #ef4444;
-
-    --cratis-border-radius: 10px;
+    --cratis-red-500:            #ef4444;
+    --cratis-green-500:          #22c55e;
+    --cratis-orange-500:         #f97316;
+    --cratis-border-radius:      10px;
 }
 
 /*
diff --git a/Source/.storybook/preview.js b/Source/.storybook/preview.js
index dc93955..540e950 100644
--- a/Source/.storybook/preview.js
+++ b/Source/.storybook/preview.js
@@ -28,8 +28,12 @@ const STYLING_MODES = {
         providerValue: {},
     },
     'cratis-themed': {
-        title: 'Path B — Cratis-themed (custom tokens)',
-        themeUrl: null,
+        title: 'Path B — Themed with custom palette',
+        // Path B = a PrimeReact theme provides the structural chrome, then the
+        // body class overrides PrimeReact's own --surface-* / --text-color /
+        // --primary-color variables (and the --cratis-* siblings) to retint
+        // every widget with a Cratis-flavored slate + sky palette.
+        themeUrl: darkThemeUrl,
         bodyClass: 'cratis-themed',
         providerValue: {},
     },
diff --git a/Source/README.md b/Source/README.md
index 786896c..cf912c1 100644
--- a/Source/README.md
+++ b/Source/README.md
@@ -95,8 +95,8 @@ much control you want, and the other layers stay invisible.
 
 > **Tip — see each path live:** every Storybook story includes a **Styling**
 > toolbar (paintbrush icon) that flips between the five modes corresponding to
-> the three paths below: *Lara Dark Blue*, *Lara Light Blue*, *Cratis-themed
-> (custom tokens)*, *Unstyled (bare structure)*, and *Unstyled + Tailwind pt*.
+> the three paths below: *Lara Dark Blue*, *Lara Light Blue*, *Themed with
+> custom palette*, *Unstyled (bare structure)*, and *Unstyled + Tailwind pt*.
 > Open any story (`yarn dev`) and switch modes to see the same component under
 > each setup.
 
@@ -105,9 +105,24 @@ much control you want, and the other layers stay invisible.
 | Path | When | Effort | What you write |
 |---|---|---|---|
 | **A. PrimeReact-themed** | You want it to look good immediately and tweak from there. | Lowest | One CSS import + provider |
-| **B. Cratis-themed (no PrimeReact theme)** | You want a custom look but don't want to fight a third-party theme. | Low | Override `--cratis-*` tokens |
+| **B. Themed with custom palette** | You want PrimeReact's chrome but in your own colors. | Low | A PrimeReact theme + a small CSS override block |
 | **C. Fully unstyled** | You're integrating into a tightly-controlled design system. | Highest | A `pt` preset (in CSS or Tailwind) |
 
+> **Why a PrimeReact theme is still in Paths A and B**
+>
+> In PrimeReact 10, every widget's *structural* CSS (padding, borders, dialog
+> frame, focus rings, button shapes) ships **inside the theme file**. There is
+> no separate "primitives" stylesheet. So a consumer who doesn't load any
+> PrimeReact theme also has no structural CSS — components render as their
+> raw HTML primitives.
+>
+> The `--cratis-*` token layer is therefore an **additive Cratis-scoped tint**
+> for surfaces *our* wrappers own (validation error text, the FormElement
+> addon, breadcrumb borders, etc.). It is not, by itself, enough to skin
+> PrimeReact widgets. Use Path B if you want a custom palette on top of
+> PrimeReact's chrome, and Path C if you want to ditch PrimeReact's chrome
+> entirely.
+
 All three paths use the same one-line setup and remain switchable later — you
 won't repaint yourself into a corner.
 
@@ -139,9 +154,9 @@ setup.
 
 ### Path A — PrimeReact-themed (fastest start)
 
-Load any PrimeReact theme stylesheet alongside Cratis Components. The
-`--cratis-*` tokens cascade to PrimeReact's matching theme variables, so every
-component picks the theme up automatically.
+Load any PrimeReact theme stylesheet alongside Cratis Components. PrimeReact's
+own widgets paint themselves from the theme, and the `--cratis-*` tokens cascade
+to the matching theme variables so Cratis-scoped surfaces follow along.
 
 ```tsx
 // 1. Theme first, then Cratis styles so any --cratis-* override wins.
@@ -197,64 +212,68 @@ happy with one of the prebuilt PrimeReact themes.
 
 ---
 
-### Path B — Cratis-themed (no PrimeReact theme)
+### Path B — Themed with custom palette
 
-Skip the PrimeReact theme stylesheet and define the look in one place by
-overriding `--cratis-*` tokens on `:root` (or any ancestor scope). The
-components render with structural defaults from the bundled stylesheet and
-pull every color, border, and surface from your tokens.
+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.
 
 #### With plain CSS
 
 ```css
-/* tokens.override.css — imported once, anywhere after @cratis/components/styles */
+/* palette.override.css — imported once, after @cratis/components/styles */
 :root {
-    /* Surfaces */
-    --cratis-surface-0:        #0f172a;
-    --cratis-surface-100:      #1e293b;
-    --cratis-surface-ground:   #020617;
-    --cratis-surface-section:  #0f172a;
-    --cratis-surface-card:     #1e293b;
-    --cratis-surface-overlay:  #1e293b;
-    --cratis-surface-hover:    #334155;
-    --cratis-surface-border:   #334155;
-
-    /* Text */
-    --cratis-text-color:           #f8fafc;
-    --cratis-text-color-secondary: #94a3b8;
-
-    /* Brand */
-    --cratis-primary-color:      #38bdf8;
-    --cratis-primary-color-text: #0b1220;
-    --cratis-primary-500:        #38bdf8;
-    --cratis-primary-600:        #0ea5e9;
-
-    /* Selection / accents */
-    --cratis-highlight-bg:         #1e40af;
-    --cratis-highlight-text-color: #ffffff;
-    --cratis-red-500:              #ef4444;
-    --cratis-green-500:            #22c55e;
-    --cratis-orange-500:           #f97316;
-
-    /* Geometry */
-    --cratis-border-radius: 10px;
+    /* 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;
 }
 ```
 
 ```tsx
+// 1. PrimeReact theme provides the structure.
+import 'primereact/resources/themes/lara-dark-blue/theme.css';
+import 'primeicons/primeicons.css';
 import '@cratis/components/styles';
-import './tokens.override.css';   // <-- after, so it wins
+// 2. Your palette overrides — must come after the theme so they win.
+import './palette.override.css';
 ```
 
 #### Scoped (dark-on-light, light-on-dark, etc.)
 
-Tokens cascade, so any ancestor scope works:
+PrimeReact variables cascade like any other CSS variable, so an ancestor
+scope works:
 
 ```css
 .dark-zone {
-    --cratis-surface-card:   #0b1220;
-    --cratis-text-color:     #f8fafc;
-    --cratis-primary-color:  #60a5fa;
+    --surface-card: #0b1220;
+    --text-color:   #f8fafc;
+    --primary-color: #60a5fa;
 }
 ```
 
@@ -266,31 +285,46 @@ Tokens cascade, so any ancestor scope works:
 
 #### With Tailwind CSS
 
-Tailwind's `@layer base` is the idiomatic spot — write tokens once and
+Tailwind's `@layer base` is the idiomatic spot — declare the palette once and
 Tailwind handles cascade and dark mode:
 
 ```css
 /* app.css */
 @import "tailwindcss";
+@import "primereact/resources/themes/lara-dark-blue/theme.css";
 @import "@cratis/components/styles";
 
 @layer base {
     :root {
-        --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');
+        --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-red-500: theme('colors.red.500');
     }
 
     .dark {
-        --cratis-surface-card:   theme('colors.slate.900');
-        --cratis-text-color:     theme('colors.slate.100');
+        --surface-card: theme('colors.slate.900');
+        --text-color:   theme('colors.slate.100');
     }
 }
 ```
 
-#### Complete token reference
+#### 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`.
+
+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.
+
+#### `--cratis-*` token reference (Cratis-scoped surfaces)
 
 | Group | Tokens |
 |---|---|
@@ -302,13 +336,13 @@ Tailwind handles cascade and dark mode:
 | Geometry | `--cratis-border-radius` |
 | Effects | `--cratis-focus-ring`, `--cratis-maskbg` |
 
-Tokens default to PrimeReact's matching theme variables, so Path A and Path B
-mix cleanly — load a PrimeReact theme to get a baseline, then override the
-specific tokens you want to change.
+Each defaults to the PrimeReact variable with the same name minus the
+`--cratis-` prefix (e.g. `--cratis-surface-card` → `var(--surface-card)`).
 
-**Choose Path B when:** you want a custom look, you're shipping multiple
-themes (light/dark/brand variants), or you don't want a PrimeReact theme in
-your bundle.
+**Choose Path B when:** you want a custom look without writing a PrimeReact
+theme from scratch, you're shipping multiple palette variants (light/dark/
+brand), or you want Cratis-scoped surfaces tinted differently from PrimeReact
+widgets.
 
 ---
 
@@ -461,9 +495,10 @@ The paths compose, so you don't have to pick one for the whole app:
       </CratisComponentsProvider>
   </CratisComponentsProvider>
   ```
-- **Dark mode** — use Path B tokens scoped to `.dark` and toggle the class on
-  the root element. Every internal component (including those used in Path C)
-  follows automatically because they all read from the same tokens.
+- **Dark mode** — use Path B's palette overrides scoped 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.
 
 ### Per-component `pt` cheat sheet
 

From 8323ae7cfc14b3bf4079eeb95a364eaa3dc404a6 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Fri, 29 May 2026 00:13:45 +0200
Subject: [PATCH 14/23] Add Styling section to the DocFX documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Build out the styling story in Documentation/ so consumers can self-serve
through the three documented paths without reading the README. Markdown
verification passes (markdownlint + link check, 77 files scanned).

New Styling section (Documentation/Styling/):
- index.md ............ Overview, decision tree, mental model.
- getting-started.md .. The one-line setup every path shares.
- themed.md ........... Path A: PrimeReact theme + CSS / className / pt
                        tweaks.
- custom-palette.md ... Path B: PrimeReact theme + override of the
                        PrimeReact CSS variables on :root for a custom
                        palette, with worked CSS and TailwindCSS examples.
- unstyled.md ......... Path C: provider unstyled=true plus pt presets in
                        both plain CSS and TailwindCSS, per-instance
                        overrides, and composite-component slot props.
- cratis-tokens.md .... Full reference for every --cratis-* token, the
                        Cratis-scoped surface it tints, and how cratis
                        tokens relate to PrimeReact variables.
- pass-through.md ..... Per-component pt cheat sheet: single-widget
                        wrappers, multi-slot composites (DataPage,
                        StepperCommandDialog, DataTables), large
                        composites (ObjectContentEditor, NavigationalBar,
                        SchemaEditor), and BusyIndicatorDialog.
- mixing-paths.md ..... Themed app with unstyled island, unstyled app
                        with themed island, app-wide dark mode, per-region
                        brand zones, per-component overrides.
- toc.yml ............. Wires the section into DocFX navigation.

New Common page:
- cratis-components-provider.md ..... Full reference for the provider:
  purpose, basic setup, value prop (APIOptions members), direct
  PrimeReactProvider alternative, and the pure mergeCratisComponentsConfig
  / cratisDefaults helpers exported for tests and library extensions.

Updates:
- Documentation/toc.yml: insert the new Styling section before Components.
- Documentation/index.md: introduce the styling system, point at the
  three paths and the token reference, mention the optional peer deps,
  list CratisComponentsProvider under Common.
- Documentation/Common/toc.yml + index.md: add the new provider page.
- Documentation/Common/form-element.md: rewrite from scratch — the
  previous content described a label/required/error API that the
  component has never had. Document the real `icon` + `children` props
  with worked examples, list the --cratis-* tokens that tint the addon,
  show the stable `cratis-form-element` class hooks for unstyled mode,
  and point at the styling section.
---
 .../Common/cratis-components-provider.md      | 111 +++++++
 Documentation/Common/form-element.md          | 198 ++++++-------
 Documentation/Common/index.md                 |  15 +-
 Documentation/Common/toc.yml                  |   2 +
 Documentation/Styling/cratis-tokens.md        | 158 ++++++++++
 Documentation/Styling/custom-palette.md       | 148 ++++++++++
 Documentation/Styling/getting-started.md      |  62 ++++
 Documentation/Styling/index.md                |  42 +++
 Documentation/Styling/mixing-paths.md         | 158 ++++++++++
 Documentation/Styling/pass-through.md         | 137 +++++++++
 Documentation/Styling/themed.md               | 104 +++++++
 Documentation/Styling/toc.yml                 |  16 +
 Documentation/Styling/unstyled.md             | 277 ++++++++++++++++++
 Documentation/index.md                        |  73 ++++-
 Documentation/toc.yml                         |   2 +
 15 files changed, 1375 insertions(+), 128 deletions(-)
 create mode 100644 Documentation/Common/cratis-components-provider.md
 create mode 100644 Documentation/Styling/cratis-tokens.md
 create mode 100644 Documentation/Styling/custom-palette.md
 create mode 100644 Documentation/Styling/getting-started.md
 create mode 100644 Documentation/Styling/index.md
 create mode 100644 Documentation/Styling/mixing-paths.md
 create mode 100644 Documentation/Styling/pass-through.md
 create mode 100644 Documentation/Styling/themed.md
 create mode 100644 Documentation/Styling/toc.yml
 create mode 100644 Documentation/Styling/unstyled.md

diff --git a/Documentation/Common/cratis-components-provider.md b/Documentation/Common/cratis-components-provider.md
new file mode 100644
index 0000000..5268fe4
--- /dev/null
+++ b/Documentation/Common/cratis-components-provider.md
@@ -0,0 +1,111 @@
+# CratisComponentsProvider
+
+Single setup point for Cratis Components. Wraps PrimeReact's `PrimeReactProvider` so the package can layer Cratis-wide defaults on top of PrimeReact's pass-through and unstyled mechanisms while still letting the consumer take complete control.
+
+## Purpose
+
+- Hosts the PrimeReact `pt` / `unstyled` / `ptOptions` / `inputStyle` / `ripple` / `appendTo` / `zIndex` / `locale` configuration for every Cratis wrapper below it in the tree.
+- Deep-merges Cratis-wide defaults with the consumer's value, so future Cratis defaults can land without breaking consumer overrides.
+- Re-exported from the package root so the recommended setup is one import:
+
+  ```ts
+  import { CratisComponentsProvider } from '@cratis/components';
+  ```
+
+## Basic usage
+
+Mount once at the root of your tree:
+
+```tsx
+import '@cratis/components/styles';
+import { CratisComponentsProvider } from '@cratis/components';
+
+export const App = () => (
+    <CratisComponentsProvider>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+## Configuring `pt` / `unstyled` globally
+
+The `value` prop accepts the full PrimeReact `APIOptions` shape. The most commonly used members are `unstyled`, `pt`, `ptOptions`, `inputStyle`, `ripple`, and `appendTo`:
+
+```tsx
+import { CratisComponentsProvider } from '@cratis/components';
+import { globalPt } from './pt-preset';
+
+export const App = () => (
+    <CratisComponentsProvider value={{ unstyled: true, pt: globalPt }}>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+The `value` is deep-merged with the Cratis defaults (currently empty) so consumer settings always win. Pass a stable reference (a module-level constant or a `useMemo` result) to avoid unnecessary re-renders.
+
+## Props
+
+### `value`
+
+`Partial<APIOptions>` — Cratis-wide and PrimeReact pass-through configuration. Merged on top of the library's defaults and made available to every Cratis component below in the tree.
+
+The most useful members:
+
+| Member | Purpose |
+|---|---|
+| `unstyled` | When `true`, disables every PrimeReact base style. Combine with `pt` (or per-component CSS / Tailwind) to fully restyle. |
+| `pt` | Per-component pass-through configuration. Keys are PrimeReact component names (`button`, `dialog`, `inputtext`, …); values are slot configuration objects. |
+| `ptOptions` | Controls merge vs. replace behavior for `pt`. Default is `{ mergeSections: true }` which merges per-instance `pt` with the global preset. |
+| `inputStyle` | `'outlined'` or `'filled'` — switches the default input rendering across the whole app. |
+| `ripple` | Enables PrimeReact's ripple animation on supported components. |
+| `appendTo` | Where overlays mount (`document.body`, `'self'`, or a DOM ref). The Cratis `Dropdown` defaults to `document.body` independently of this setting. |
+| `zIndex` | Per-overlay-type z-index baseline (`{ modal: 1100, overlay: 1000, … }`). |
+| `locale` | PrimeReact locale string. |
+
+The full type is re-exported as `CratisComponentsConfig`.
+
+### `children`
+
+`React.ReactNode` — your application tree.
+
+## Using `PrimeReactProvider` directly
+
+`CratisComponentsProvider` is optional. If you'd rather mount PrimeReact's own provider directly, that works too — every Cratis wrapper reads the same context:
+
+```tsx
+import { PrimeReactProvider } from 'primereact/api';
+
+export const App = () => (
+    <PrimeReactProvider value={{ unstyled: true, pt: globalPt }}>
+        <YourApp />
+    </PrimeReactProvider>
+);
+```
+
+The Cratis provider exists to give Cratis one place to layer in defaults later without breaking consumers, and to keep the setup discoverable from a single import path.
+
+## Pure helpers (testing / library extension)
+
+The merge logic is exported so the contract can be verified without rendering React:
+
+```ts
+import { mergeCratisComponentsConfig, cratisDefaults } from '@cratis/components';
+
+const merged = mergeCratisComponentsConfig({ unstyled: true, pt: myPt });
+// → { ...cratisDefaults, unstyled: true, pt: myPt }
+```
+
+| Export | Description |
+|---|---|
+| `CratisComponentsProvider`     | The React component. |
+| `CratisComponentsProviderProps` | Props type. |
+| `CratisComponentsConfig`        | Alias for `Partial<APIOptions>`. |
+| `cratisDefaults`                | The Cratis-wide defaults that ship today (currently `{}`). |
+| `mergeCratisComponentsConfig`   | Pure deep-merge helper used inside the provider. |
+
+## See also
+
+- [Styling Overview](../Styling/index.md) — three styling paths and where the provider fits
+- [Pass-through cheat sheet](../Styling/pass-through.md) — what `pt` reaches in each Cratis wrapper
+- [Path C — Fully unstyled](../Styling/unstyled.md) — full `pt` preset walk-through
diff --git a/Documentation/Common/form-element.md b/Documentation/Common/form-element.md
index 3cc5d8d..d251582 100644
--- a/Documentation/Common/form-element.md
+++ b/Documentation/Common/form-element.md
@@ -1,165 +1,131 @@
 # FormElement
 
-Wrapper component for form inputs with label and validation display.
+Lightweight wrapper that places an icon addon to the left of a form input, styled with the `--cratis-*` token layer. Use it to give input fields a leading icon without pulling in PrimeReact's `InputGroup` chrome.
 
 ## Purpose
 
-FormElement provides consistent styling and structure for form input fields with labels and validation messages.
+FormElement is a structural primitive — it lays out an icon addon and a child input side by side, with rounded-on-the-left chrome around the addon. It does **not** render labels, required indicators, or validation messages — those concerns live on the underlying input itself or on the surrounding command form.
 
 ## Key Features
 
-- Label positioning
-- Validation error display
-- Required field indication
-- Consistent spacing
-- Integration with form validation
+- Icon addon styled from `--cratis-*` tokens (background, border, radius).
+- Independent of PrimeReact's `p-inputgroup` / `p-inputgroup-addon` classes — works the same with or without a PrimeReact theme loaded.
+- Accepts any React node as the icon (PrimeIcons class, `<svg>`, third-party icon component, …).
+
+## Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `icon` | `React.ReactNode` | Icon node displayed inside the leading addon. Can be any React node — a PrimeIcons `<i className="pi pi-…" />`, an `<svg>`, or a `react-icons` component. |
+| `children` | `React.ReactNode` | The form input rendered to the right of the icon addon (typically an `InputText`, `Dropdown`, etc.). |
 
 ## Basic Usage
 
-```typescript
+```tsx
 import { FormElement } from '@cratis/components';
 import { InputText } from 'primereact/inputtext';
 
 function MyForm() {
     return (
-        <FormElement label="Name" required={true} error="Name is required">
+        <FormElement icon={<i className="pi pi-user" />}>
             <InputText value={name} onChange={(e) => setName(e.target.value)} />
         </FormElement>
     );
 }
 ```
 
-## Props
-
-- `label`: Label text for the field
-- `required`: Show required indicator (default: false)
-- `error`: Validation error message to display
-- `children`: The form input component
-
 ## Examples
 
-### Text Input
+### Email field with envelope icon
 
-```typescript
-<FormElement label="Email" required>
-    <InputText 
+```tsx
+<FormElement icon={<i className="pi pi-envelope" />}>
+    <InputText
         type="email"
-        value={email} 
-        onChange={(e) => setEmail(e.target.value)} 
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="you@example.com"
     />
 </FormElement>
 ```
 
-### With Validation Error
-
-```typescript
-<FormElement 
-    label="Password" 
-    required 
-    error={passwordError}
->
-    <InputText 
-        type="password"
-        value={password} 
-        onChange={(e) => setPassword(e.target.value)} 
-    />
-</FormElement>
-```
+### Search field with react-icons
 
-### Dropdown
+```tsx
+import { FaMagnifyingGlass } from 'react-icons/fa6';
 
-```typescript
-<FormElement label="Country" required>
-    <Dropdown 
-        value={country}
-        options={countries}
-        onChange={(e) => setCountry(e.value)}
+<FormElement icon={<FaMagnifyingGlass />}>
+    <InputText
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder="Search…"
     />
 </FormElement>
 ```
 
-### Checkbox
+### Dropdown with category icon
 
-```typescript
-<FormElement label="Agree to Terms">
-    <Checkbox 
-        checked={agreed}
-        onChange={(e) => setAgreed(e.checked)}
+```tsx
+import { FaLayerGroup } from 'react-icons/fa6';
+
+<FormElement icon={<FaLayerGroup />}>
+    <Dropdown
+        value={category}
+        options={categories}
+        onChange={(e) => setCategory(e.value)}
+        optionLabel="name"
+        optionValue="id"
     />
 </FormElement>
 ```
 
-### Text Area
+## Styling
 
-```typescript
-<FormElement label="Description">
-    <InputTextarea 
-        value={description}
-        onChange={(e) => setDescription(e.target.value)}
-        rows={5}
-    />
-</FormElement>
-```
+The addon's background, border, and radius are driven by the [`--cratis-*` token layer](../Styling/cratis-tokens.md):
 
-## Complete Form Example
+| Token | Surface |
+|---|---|
+| `--cratis-surface-100` | Addon background. |
+| `--cratis-surface-border` | Addon border. |
+| `--cratis-text-color-secondary` | Icon color. |
+| `--cratis-border-radius` | Rounded-on-the-left corner radius. |
 
-```typescript
-function UserForm() {
-    const [formData, setFormData] = useState({
-        name: '',
-        email: '',
-        role: null
-    });
-    const [errors, setErrors] = useState({});
+Override the tokens to retint the addon without forking the component:
 
-    return (
-        <form onSubmit={handleSubmit}>
-            <FormElement 
-                label="Full Name" 
-                required 
-                error={errors.name}
-            >
-                <InputText 
-                    value={formData.name}
-                    onChange={(e) => handleChange('name', e.target.value)}
-                />
-            </FormElement>
-
-            <FormElement 
-                label="Email Address" 
-                required 
-                error={errors.email}
-            >
-                <InputText 
-                    type="email"
-                    value={formData.email}
-                    onChange={(e) => handleChange('email', e.target.value)}
-                />
-            </FormElement>
-
-            <FormElement 
-                label="Role" 
-                required 
-                error={errors.role}
-            >
-                <Dropdown 
-                    value={formData.role}
-                    options={roleOptions}
-                    onChange={(e) => handleChange('role', e.value)}
-                />
-            </FormElement>
-
-            <Button type="submit" label="Save" />
-        </form>
-    );
+```css
+:root {
+    --cratis-surface-100:   #1e293b;
+    --cratis-surface-border: #334155;
+    --cratis-border-radius:  10px;
+}
+```
+
+For per-instance restyling, wrap the FormElement with your own class and target it in CSS:
+
+```css
+.brand-form-element .cratis-form-element__addon {
+    background: var(--brand-accent);
+    color: var(--brand-on-accent);
 }
 ```
 
-## Best Practices
+```tsx
+<div className="brand-form-element">
+    <FormElement icon={<i className="pi pi-shield" />}>
+        <InputText … />
+    </FormElement>
+</div>
+```
+
+For full styling control under `unstyled` mode (Path C), the addon classes are stable: `cratis-form-element` on the row and `cratis-form-element__addon` on the leading slot.
+
+## When to use FormElement vs CommandForm fields
+
+- Use **`FormElement`** for ad-hoc forms outside of a `CommandForm`, when you want the icon-addon visual on top of any input you control.
+- Use **CommandForm fields** (`InputTextField`, `NumberField`, `DropdownField`, …) inside a `CommandForm` or `CommandDialog` — they bind to a command property, surface validation state, and render the appropriate input type.
+
+## See Also
 
-1. Always use FormElement for consistent form layouts
-2. Show required indicators on mandatory fields
-3. Display validation errors clearly
-4. Keep labels concise
-5. Group related fields together
-6. Use appropriate input types for data
+- [Styling Overview](../Styling/index.md) — three styling paths and where FormElement fits
+- [Cratis token reference](../Styling/cratis-tokens.md) — every token and the surfaces it tints
+- [CommandForm Field Types](../CommandForm/index.md) — command-bound field wrappers
diff --git a/Documentation/Common/index.md b/Documentation/Common/index.md
index 533a594..1229019 100644
--- a/Documentation/Common/index.md
+++ b/Documentation/Common/index.md
@@ -1,17 +1,20 @@
 # Common Components
 
-The Common module provides reusable UI components that serve as building blocks for applications.
+The Common module provides reusable UI components and the styling setup primitive that serve as building blocks for applications.
 
 ## Components
 
-- **Icon / IconDisplay**: Unified icon type that accepts a PrimeIcons CSS class string or any React node
-- **Page**: Layout component for consistent page structures
-- **FormElement**: Wrapper for form inputs with labels and validation
-- **ErrorBoundary**: Error handling for React component trees
+- **CratisComponentsProvider**: Single setup point for Cratis Components — wraps PrimeReact's `PrimeReactProvider` and hosts the `pt`, `unstyled`, locale, and other global configuration.
+- **Icon / IconDisplay**: Unified icon type that accepts a PrimeIcons CSS class string or any React node.
+- **Page**: Layout primitive for consistent page structures.
+- **FormElement**: Lightweight wrapper that places an icon addon to the left of a form input.
+- **ErrorBoundary**: Error handling for React component trees.
 
 ## See Also
 
+- [CratisComponentsProvider](cratis-components-provider.md) — global setup, `pt` / `unstyled` configuration
 - [Icon](icon.md) - Icon type and IconDisplay component
 - [Page](page.md) - Page layout component
-- [FormElement](form-element.md) - Form field wrapper
+- [FormElement](form-element.md) - Form field icon-addon wrapper
 - [ErrorBoundary](error-boundary.md) - Error boundary component
+- [Styling Overview](../Styling/index.md) — three styling paths and how Common fits in
diff --git a/Documentation/Common/toc.yml b/Documentation/Common/toc.yml
index 780c0e3..f7906fb 100644
--- a/Documentation/Common/toc.yml
+++ b/Documentation/Common/toc.yml
@@ -1,5 +1,7 @@
 - name: Overview
   href: index.md
+- name: CratisComponentsProvider
+  href: cratis-components-provider.md
 - name: Icon
   href: icon.md
 - name: Page
diff --git a/Documentation/Styling/cratis-tokens.md b/Documentation/Styling/cratis-tokens.md
new file mode 100644
index 0000000..fd603bf
--- /dev/null
+++ b/Documentation/Styling/cratis-tokens.md
@@ -0,0 +1,158 @@
+# Cratis token reference
+
+The `--cratis-*` CSS variable layer is the Cratis-scoped tint surface every Cratis wrapper reads from. Each token defaults to a matching PrimeReact theme variable via `tokens.css`, so loading a PrimeReact theme (Paths [A](themed.md) and [B](custom-palette.md)) automatically gives every Cratis surface the right color without any further work.
+
+You override `--cratis-*` tokens when you want **just** Cratis-scoped surfaces (validation error text, FormElement addon, breadcrumb borders, …) tinted independently of PrimeReact widgets. To repaint PrimeReact widgets themselves, override the PrimeReact variables directly — see [Path B](custom-palette.md).
+
+## Loading the tokens
+
+The token layer ships at two import paths:
+
+```ts
+import '@cratis/components/styles';
+```
+
+The recommended one — ships the Tailwind utility classes used inside the package **plus** the `--cratis-*` token declarations as a single stylesheet.
+
+```ts
+import '@cratis/components/tokens';
+```
+
+Just the token declarations, with no Tailwind utilities. Use this if you bring your own utility CSS solution (or use Tailwind with custom classnames that don't match what the package ships).
+
+## Token catalogue
+
+Each token defaults to the PrimeReact variable with the same name minus the `--cratis-` prefix (e.g. `--cratis-surface-card` → `var(--surface-card)`). Set the token to override that default.
+
+### Surfaces
+
+| Token | Cratis surfaces tinted by it |
+|---|---|
+| `--cratis-surface-0`      | Reserved for any Cratis-scoped surface that maps to PrimeReact's `--surface-0`. |
+| `--cratis-surface-100`    | `FormElement` addon background. |
+| `--cratis-surface-ground` | Reserved for any Cratis-scoped surface that maps to PrimeReact's `--surface-ground`. |
+| `--cratis-surface-section` | Reserved for any Cratis-scoped surface that maps to PrimeReact's `--surface-section`. |
+| `--cratis-surface-card`   | Backgrounds of the `ObjectContentEditor` snapshot card and similar panels. |
+| `--cratis-surface-overlay` | Overlay backgrounds inside Cratis wrappers. |
+| `--cratis-surface-hover`  | Hover state on row alternation inside `ObjectContentEditor`. |
+| `--cratis-surface-border` | `FormElement` addon border, `ObjectNavigationalBar` bottom border, `SchemaEditor` bottom border, table/paginator borders inside `DataTableForQuery` / `DataTableForObservableQuery`. |
+
+### Text
+
+| Token | Cratis surfaces tinted by it |
+|---|---|
+| `--cratis-text-color`           | Default body text inside Cratis wrappers. |
+| `--cratis-text-color-secondary` | `ObjectContentEditor` label column, `ObjectNavigationalBar` breadcrumbs, `SchemaEditor` secondary labels. |
+
+### Brand
+
+| Token | Cratis surfaces tinted by it |
+|---|---|
+| `--cratis-primary-color`      | `ObjectContentEditor` navigation links into nested objects/arrays, default brand accent. |
+| `--cratis-primary-color-text` | Foreground used on top of `--cratis-primary-color` backgrounds (e.g. CommandStepper step number color). |
+| `--cratis-primary-300`        | Reserved for lighter brand variants. |
+| `--cratis-primary-400`        | Reserved for lighter brand variants. |
+| `--cratis-primary-500`        | Reserved for brand mid-tones. |
+| `--cratis-primary-600`        | Reserved for brand darker variants. |
+
+### Selection / highlight
+
+| Token | Cratis surfaces tinted by it |
+|---|---|
+| `--cratis-highlight-bg`         | Background of timestamp/highlight chips inside `ObjectContentEditor`. |
+| `--cratis-highlight-text-color` | Text on top of `--cratis-highlight-bg`. |
+
+### Semantic accents
+
+| Token | Cratis surfaces tinted by it |
+|---|---|
+| `--cratis-green-500`  | `CommandStepper` visited-step indicator. |
+| `--cratis-orange-500` | Reserved for warning accents. |
+| `--cratis-red-500`    | Inline validation error text (replaces PrimeReact's `.p-error` styling), `CommandStepper` error-step indicator, error border tint inside `ObjectContentEditor`. |
+
+### Geometry
+
+| Token | Cratis surfaces tinted by it |
+|---|---|
+| `--cratis-border-radius` | Border radius on `FormElement` addon and any Cratis surface that mirrors PrimeReact's `--border-radius`. |
+
+### Effects
+
+| Token | Cratis surfaces tinted by it |
+|---|---|
+| `--cratis-focus-ring` | Reserved for Cratis-managed focus rings. |
+| `--cratis-maskbg`     | Reserved for any Cratis-managed modal mask. |
+
+## Overriding tokens
+
+Apply on `:root` for an app-wide override:
+
+```css
+:root {
+    --cratis-red-500: #f97316;
+    --cratis-border-radius: 12px;
+}
+```
+
+…or on an ancestor scope for a region-specific look:
+
+```css
+.brand-region {
+    --cratis-surface-border: theme('colors.violet.500');
+    --cratis-text-color-secondary: theme('colors.violet.300');
+}
+```
+
+```tsx
+<div className="brand-region">
+    <ObjectNavigationalBar navigationPath={path} onNavigate={…} />
+</div>
+```
+
+Cratis tokens cascade like any other CSS variable, so any selector that increases specificity over `:root` wins.
+
+## With TailwindCSS
+
+Tailwind's `@layer base` is the idiomatic spot — declare tokens once and let Tailwind handle cascade and dark mode:
+
+```css
+@import "tailwindcss";
+@import "@cratis/components/tokens";
+
+@layer base {
+    :root {
+        --cratis-surface-border: theme('colors.slate.700');
+        --cratis-text-color:     theme('colors.slate.50');
+        --cratis-red-500:        theme('colors.red.500');
+    }
+
+    .dark {
+        --cratis-surface-border: theme('colors.slate.600');
+        --cratis-text-color:     theme('colors.slate.100');
+    }
+}
+```
+
+## Relationship to PrimeReact variables
+
+The Cratis token layer is **additive** on top of PrimeReact's theme system, not a replacement for it. The cascade in `tokens.css` looks like:
+
+```css
+:root {
+    --cratis-surface-card: var(--surface-card);
+    --cratis-text-color:   var(--text-color);
+    /* … */
+}
+```
+
+That means:
+
+- Override `--surface-card` (PrimeReact) → both PrimeReact widgets *and* Cratis surfaces follow.
+- Override `--cratis-surface-card` (Cratis) → only Cratis surfaces follow; PrimeReact widgets keep their existing color.
+
+Use the PrimeReact variable when you want a whole-UI repaint (Path B). Use the Cratis token when you want a Cratis-specific accent that differs from PrimeReact widgets.
+
+## See also
+
+- [Path B — Custom palette](custom-palette.md) — for whole-UI repainting with PrimeReact variables
+- [Pass-through cheat sheet](pass-through.md) — for per-slot styling beyond what tokens reach
diff --git a/Documentation/Styling/custom-palette.md b/Documentation/Styling/custom-palette.md
new file mode 100644
index 0000000..fe1bde5
--- /dev/null
+++ b/Documentation/Styling/custom-palette.md
@@ -0,0 +1,148 @@
+# Path B — Themed with custom palette
+
+You want PrimeReact's chrome — its dialog frames, button shapes, focus rings, input borders — but in your own colors. You don't want to write a PrimeReact theme from scratch.
+
+This path keeps a PrimeReact theme as the **structural baseline** and overrides PrimeReact's own CSS variables on `:root` to repaint the whole UI. The `--cratis-*` tokens follow along through `tokens.css`'s cascade, so Cratis-scoped surfaces stay in sync. You can also override the Cratis tokens independently when you want Cratis surfaces to differ from PrimeReact widgets.
+
+## Setup
+
+```tsx
+// 1. PrimeReact theme provides the structure.
+import 'primereact/resources/themes/lara-dark-blue/theme.css';
+import 'primeicons/primeicons.css';
+import '@cratis/components/styles';
+// 2. Your palette overrides — must come after the theme so they win.
+import './palette.override.css';
+```
+
+## With plain CSS
+
+Override PrimeReact's variables — these are what its widgets read directly:
+
+```css
+/* palette.override.css */
+:root {
+    /* Surfaces */
+    --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 */
+    --text-color:           #f8fafc;
+    --text-color-secondary: #94a3b8;
+
+    /* Brand */
+    --primary-color:      #38bdf8;
+    --primary-color-text: #0b1220;
+
+    /* Selection */
+    --highlight-bg:         #1e40af;
+    --highlight-text-color: #ffffff;
+
+    /* Geometry */
+    --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;
+}
+```
+
+## With TailwindCSS
+
+Tailwind's `@layer base` is the idiomatic spot — declare the palette once and Tailwind handles cascade and dark mode:
+
+```css
+/* app.css */
+@import "tailwindcss";
+@import "primereact/resources/themes/lara-dark-blue/theme.css";
+@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-red-500:  theme('colors.red.500');
+    }
+
+    .dark {
+        --surface-card: theme('colors.slate.900');
+        --text-color:   theme('colors.slate.100');
+    }
+}
+```
+
+## Scoped overrides
+
+PrimeReact variables cascade like any other CSS variable, so an ancestor scope works for region-specific looks:
+
+```css
+.dark-zone {
+    --surface-card:  #0b1220;
+    --text-color:    #f8fafc;
+    --primary-color: #60a5fa;
+}
+```
+
+```tsx
+<>
+    <Dialog title="Standard look">…</Dialog>
+
+    <div className="dark-zone">
+        <Dialog title="Always dark in here">…</Dialog>
+    </div>
+</>
+```
+
+## Shipping multiple palettes (light / dark / brand variants)
+
+Put each palette behind a class on the root element and toggle the class with your theme switcher:
+
+```css
+:root.theme-light {
+    --surface-card: #ffffff;
+    --text-color:   #0f172a;
+    /* … */
+}
+
+:root.theme-dark {
+    --surface-card: #1e293b;
+    --text-color:   #f8fafc;
+    /* … */
+}
+
+:root.theme-brand {
+    --surface-card: #1f1147;
+    --text-color:   #ede9fe;
+    --primary-color: #a78bfa;
+    /* … */
+}
+```
+
+```tsx
+document.documentElement.classList.add('theme-dark');
+```
+
+## What `--cratis-*` tokens are for in this path
+
+Two override surfaces are available, with different reach:
+
+- **PrimeReact variables** (`--surface-card`, `--text-color`, `--primary-color`, …) — read by PrimeReact widgets directly. Override these to repaint the whole UI (PrimeReact widgets *and* Cratis-scoped surfaces, because Cratis tokens cascade to PrimeReact's via `tokens.css`).
+- **`--cratis-*` tokens** — read only by Cratis-scoped surfaces (validation errors, FormElement addon, breadcrumb borders, etc.). Override these when you want Cratis surfaces to differ from PrimeReact widgets, *without* repainting PrimeReact widgets.
+
+See [Cratis token reference](cratis-tokens.md) for the full Cratis token list, and [Pass-through cheat sheet](pass-through.md) when you want even tighter per-component control.
+
+## When to switch paths
+
+You'll outgrow Path B when:
+
+- You need to restyle the structural chrome itself — for example, a non-rectangular Dialog frame, a completely different Button shape, or a design system with a custom focus-ring system. Switch to [Path C](unstyled.md) and bring the visuals yourself.
diff --git a/Documentation/Styling/getting-started.md b/Documentation/Styling/getting-started.md
new file mode 100644
index 0000000..6e8a079
--- /dev/null
+++ b/Documentation/Styling/getting-started.md
@@ -0,0 +1,62 @@
+# Getting Started
+
+Every styling path shares the same one-line setup. The differences come from what you load **on top** of this baseline.
+
+## Install
+
+Install `@cratis/components` along with the required PrimeReact peer dependencies. You only need to add them to your own `package.json` once; npm/yarn won't pull them in transitively:
+
+```bash
+npm install @cratis/components primereact primeicons
+# or
+yarn add @cratis/components primereact primeicons
+```
+
+The optional peers (`pixi.js`, `framer-motion`, `allotment`) are only required when you use the corresponding component:
+
+| Component | Optional peer |
+|---|---|
+| `PivotViewer` | `pixi.js` |
+| `CommandStepper`, animated panels | `framer-motion` |
+| `DataPage` resizable layout | `allotment` |
+
+## Wire the provider
+
+Mount [`CratisComponentsProvider`](../Common/cratis-components-provider.md) once at the root of your tree. The provider is a thin wrapper around PrimeReact's own `PrimeReactProvider` and is where you configure `unstyled`, `pt`, `ptOptions`, `inputStyle`, `ripple`, `appendTo`, and the rest of PrimeReact's API options:
+
+```tsx
+import '@cratis/components/styles';
+import { CratisComponentsProvider } from '@cratis/components';
+
+export const App = () => (
+    <CratisComponentsProvider>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+`@cratis/components/styles` ships the Tailwind utility classes used inside the package plus the `--cratis-*` CSS variable token layer that every internal Cratis surface reads from.
+
+If you bring your own Tailwind setup and want only the token layer, import `@cratis/components/tokens` instead:
+
+```tsx
+import '@cratis/components/tokens';
+```
+
+## What's loaded so far
+
+With nothing else, you've imported:
+
+- The Tailwind utility classes used internally by Cratis wrappers (so layout, spacing, sizing all work)
+- The `--cratis-*` token layer (so Cratis-scoped surfaces have a stable variable surface to read from)
+- The provider that hosts `pt` / `unstyled` / locale / overlay z-index settings
+
+That's enough for the wrappers to render structurally, but PrimeReact widgets need **either** a theme (Path A or B) or `unstyled: true` + a `pt` preset (Path C) to look like anything other than raw browser primitives. Pick your path:
+
+- [Path A — PrimeReact-themed](themed.md) — load a theme stylesheet and start tweaking
+- [Path B — Custom palette](custom-palette.md) — same theme, your colors
+- [Path C — Fully unstyled](unstyled.md) — bring everything yourself
+
+## Using `PrimeReactProvider` directly
+
+`CratisComponentsProvider` is optional. If you'd rather mount `PrimeReactProvider` from `primereact/api` directly, that works too — every Cratis wrapper reads the same context. The Cratis provider exists to give Cratis a single place to layer in defaults later without breaking consumers, and to keep the setup discoverable. See [CratisComponentsProvider](../Common/cratis-components-provider.md) for the full prop reference.
diff --git a/Documentation/Styling/index.md b/Documentation/Styling/index.md
new file mode 100644
index 0000000..72f4c4e
--- /dev/null
+++ b/Documentation/Styling/index.md
@@ -0,0 +1,42 @@
+# Styling
+
+Cratis Components is built on top of PrimeReact and stays out of your way when it comes to styling. You can ship the look that PrimeReact gives you out of the box, repaint the whole UI in your own palette, or take complete control and bring your own visuals from scratch — all without forking the library or fighting it.
+
+There are three documented paths. They are not mutually exclusive: every component still exposes the same building blocks, so you can mix them per-component or per-region of your app.
+
+## TL;DR — pick a path
+
+| Path | When | Effort | What you write |
+|---|---|---|---|
+| [**A. PrimeReact-themed**](themed.md) | You want it to look good immediately and tweak from there. | Lowest | One CSS import + provider |
+| [**B. Custom palette**](custom-palette.md) | You want PrimeReact's chrome but in your own colors. | Low | A PrimeReact theme + a small CSS override block |
+| [**C. Fully unstyled**](unstyled.md) | You're integrating into a tightly-controlled design system. | Highest | A `pt` preset (in CSS or Tailwind) |
+
+All three paths use the same one-line setup described in [Getting Started](getting-started.md). They remain switchable later — you won't repaint yourself into a corner.
+
+## Why a PrimeReact theme is still in Paths A and B
+
+In PrimeReact 10 every widget's *structural* CSS — padding, borders, dialog frame, focus rings, button shapes — ships **inside the theme file**. There is no separate primitives stylesheet. So a setup without any PrimeReact theme has no widget chrome at all and components render as the raw HTML primitives the browser supplies by default.
+
+The `--cratis-*` token layer is an additive Cratis-scoped tint for surfaces the wrappers in this package own — validation error text, the FormElement addon background, breadcrumb borders — and **is not, by itself, sufficient to skin PrimeReact widgets**. Use Path B if you want a custom palette on top of PrimeReact's chrome, and Path C if you want to ditch PrimeReact's chrome entirely.
+
+## Mental model
+
+Every component you import from `@cratis/components` is a thin wrapper around a PrimeReact component plus a few Cratis additions (validation hooks, command-form integration, …). Styling flows in three layers:
+
+1. **PrimeReact theme variables** — `--surface-card`, `--text-color`, `--primary-color`, … Read directly by PrimeReact widgets. Override these to repaint the whole UI.
+2. **Cratis tokens** — `--cratis-surface-card`, `--cratis-text-color`, `--cratis-primary-color`, … Read only by Cratis-scoped surfaces. Default to the matching PrimeReact variable via cascade in `tokens.css`. Override these when you want a Cratis surface tinted differently from the surrounding PrimeReact widgets.
+3. **PrimeReact `pt` (pass-through)** — A per-component prop that lets you attach CSS class names (or inline styles) to every slot inside a PrimeReact widget. The strongest customization knob; works hand-in-hand with `unstyled` mode.
+
+The [Cratis token reference](cratis-tokens.md) lists every token and the surface it tints. The [pass-through cheat sheet](pass-through.md) lists every Cratis wrapper and which pt props it exposes.
+
+## See also
+
+- [Getting Started](getting-started.md) — the one-line setup every path shares
+- [Path A — PrimeReact-themed](themed.md)
+- [Path B — Custom palette](custom-palette.md)
+- [Path C — Fully unstyled](unstyled.md)
+- [Cratis token reference](cratis-tokens.md)
+- [Pass-through (pt) cheat sheet](pass-through.md)
+- [Mixing paths](mixing-paths.md)
+- [CratisComponentsProvider](../Common/cratis-components-provider.md)
diff --git a/Documentation/Styling/mixing-paths.md b/Documentation/Styling/mixing-paths.md
new file mode 100644
index 0000000..96cf2af
--- /dev/null
+++ b/Documentation/Styling/mixing-paths.md
@@ -0,0 +1,158 @@
+# Mixing paths
+
+The three paths compose. You don't have to pick one for the whole app — every Cratis wrapper still exposes the same building blocks, so you can mix them per-component or per-region.
+
+## Themed app with one unstyled island
+
+Keep the PrimeReact theme as your global baseline and opt one specific component out with the per-instance `unstyled` prop:
+
+```tsx
+import 'primereact/resources/themes/lara-dark-blue/theme.css';
+import '@cratis/components/styles';
+import { CratisComponentsProvider, Dialog } from '@cratis/components';
+
+const brandDialogPt = {
+    root:    { className: 'rounded-3xl bg-violet-900 text-violet-50' },
+    header:  { className: 'px-6 py-4 border-b border-violet-700 font-semibold' },
+    content: { className: 'p-6' },
+};
+
+export const App = () => (
+    <CratisComponentsProvider>
+        <YourApp />
+
+        {/* This one Dialog opts out of the theme and uses its own brand visuals. */}
+        <Dialog title="Brand callout" unstyled pt={brandDialogPt}>
+            …
+        </Dialog>
+    </CratisComponentsProvider>
+);
+```
+
+## Unstyled app with one themed island
+
+Run the app fully unstyled and restore PrimeReact's defaults inside a single subtree by nesting a second `CratisComponentsProvider`:
+
+```tsx
+import 'primereact/resources/themes/lara-dark-blue/theme.css';
+import '@cratis/components/styles';
+import { CratisComponentsProvider } from '@cratis/components';
+import { globalPt } from './pt-preset';
+
+export const App = () => (
+    <CratisComponentsProvider value={{ unstyled: true, pt: globalPt }}>
+        <YourApp />
+
+        {/* Inside this subtree, components use PrimeReact's theme defaults. */}
+        <CratisComponentsProvider value={{ unstyled: false }}>
+            <PrimeReactThemedSubtree />
+        </CratisComponentsProvider>
+    </CratisComponentsProvider>
+);
+```
+
+## App-wide dark mode
+
+Put each palette behind a class on the root element and toggle the class with your theme switcher. PrimeReact widgets and Cratis surfaces both follow because the `--cratis-*` tokens cascade from PrimeReact variables by default:
+
+```css
+:root.theme-light {
+    --surface-card: #ffffff;
+    --surface-border: #e2e8f0;
+    --text-color:   #0f172a;
+    --primary-color: #2563eb;
+}
+
+:root.theme-dark {
+    --surface-card: #1e293b;
+    --surface-border: #334155;
+    --text-color:   #f8fafc;
+    --primary-color: #38bdf8;
+}
+```
+
+```tsx
+const ThemeToggle = () => {
+    const toggle = () => {
+        const root = document.documentElement;
+        root.classList.toggle('theme-dark');
+        root.classList.toggle('theme-light');
+    };
+    return <button onClick={toggle}>Toggle theme</button>;
+};
+```
+
+Combine with `prefers-color-scheme` for the initial mode:
+
+```css
+@media (prefers-color-scheme: dark) {
+    :root:not(.theme-light):not(.theme-dark) {
+        --surface-card: #1e293b;
+        --text-color: #f8fafc;
+    }
+}
+```
+
+## Per-region brand zones
+
+Token overrides cascade, so any ancestor scope works for tinting Cratis-scoped surfaces in a region:
+
+```css
+.brand-zone {
+    --cratis-surface-border: #c4b5fd;
+    --cratis-text-color-secondary: #a78bfa;
+    --cratis-primary-color: #7c3aed;
+}
+```
+
+```tsx
+<div className="brand-zone">
+    <ObjectNavigationalBar navigationPath={path} onNavigate={…} />
+    <ObjectContentEditor object={data} schema={schema} />
+</div>
+```
+
+If you want PrimeReact widgets in the region to follow too, override the PrimeReact variables in the same scope:
+
+```css
+.brand-zone {
+    --surface-card:  #1f1147;
+    --text-color:    #ede9fe;
+    --primary-color: #a78bfa;
+    /* …and the --cratis-* siblings above */
+}
+```
+
+## Per-component themed override inside unstyled mode
+
+When you're on Path C globally, single components can still pull in classes from a separate stylesheet via the `className` prop or per-instance `pt`:
+
+```tsx
+import './custom-table.css';
+
+<CratisComponentsProvider value={{ unstyled: true, pt: globalPt }}>
+    {/* All other DataTables use globalPt; this one uses a bespoke look. */}
+    <DataTableForQuery
+        query={AllAuthors}
+        emptyMessage="No authors"
+        className="custom-table"
+        pt={{ table: { className: 'custom-table__inner' } }}
+    >
+        …
+    </DataTableForQuery>
+</CratisComponentsProvider>
+```
+
+## What to keep in mind
+
+- **Provider value updates re-render**: changing `value` on `CratisComponentsProvider` rebuilds the merged config. Use a stable reference (e.g. `useMemo` or a module-level constant) to avoid spurious re-renders.
+- **`pt` merging is deep**: PrimeReact merges global `pt` with per-instance `pt` by default. Set `ptOptions={{ mergeSections: false }}` on the wrapper if you need a hard replace.
+- **Cratis tokens are scoped**: overriding a `--cratis-*` token only changes Cratis surfaces. To repaint PrimeReact widgets too, override the PrimeReact variable. See [Cratis token reference](cratis-tokens.md).
+
+## See also
+
+- [Path A — PrimeReact-themed](themed.md)
+- [Path B — Custom palette](custom-palette.md)
+- [Path C — Fully unstyled](unstyled.md)
+- [Pass-through cheat sheet](pass-through.md)
+- [CratisComponentsProvider](../Common/cratis-components-provider.md)
diff --git a/Documentation/Styling/pass-through.md b/Documentation/Styling/pass-through.md
new file mode 100644
index 0000000..d4c3bc5
--- /dev/null
+++ b/Documentation/Styling/pass-through.md
@@ -0,0 +1,137 @@
+# Pass-through (`pt`) cheat sheet
+
+Every Cratis wrapper forwards PrimeReact's `pt`, `ptOptions`, and `unstyled` props somewhere — but **where** depends on how much PrimeReact the wrapper composes. This page summarizes the pattern per component so you know which prop to reach for.
+
+## Three patterns
+
+### 1. Single-widget wrappers
+
+The wrapper renders exactly one PrimeReact widget and forwards `pt` / `ptOptions` / `unstyled` / `className` straight to it. The pt slot names are PrimeReact's own — see the underlying component's documentation.
+
+| Wrapper | Underlying widget | pt slot reference |
+|---|---|---|
+| `Dialog`            | `primereact/dialog` Dialog          | PrimeReact Dialog `pt` |
+| `Dropdown`          | `primereact/dropdown` Dropdown      | PrimeReact Dropdown `pt` |
+| `InputTextField`    | `primereact/inputtext` InputText    | PrimeReact InputText `pt` |
+| `TextAreaField`     | `primereact/inputtextarea` InputTextarea | PrimeReact InputTextarea `pt` |
+| `NumberField`       | `primereact/inputnumber` InputNumber | PrimeReact InputNumber `pt` |
+| `DropdownField`     | `primereact/dropdown` Dropdown      | PrimeReact Dropdown `pt` |
+| `RadioGroupField`   | `primereact/radiobutton` RadioButton (one per option) | PrimeReact RadioButton `pt` |
+| `RadioButtonField`  | `primereact/radiobutton` RadioButton | PrimeReact RadioButton `pt` |
+| `CalendarField`     | `primereact/calendar` Calendar      | PrimeReact Calendar `pt` |
+| `CheckboxField`     | `primereact/checkbox` Checkbox      | PrimeReact Checkbox `pt` |
+| `SliderField`       | `primereact/slider` Slider          | PrimeReact Slider `pt` |
+| `ChipsField`        | `primereact/chips` Chips            | PrimeReact Chips `pt` |
+| `MultiSelectField`  | `primereact/multiselect` MultiSelect | PrimeReact MultiSelect `pt` |
+| `ColorPickerField`  | `primereact/colorpicker` ColorPicker | PrimeReact ColorPicker `pt` |
+
+Example:
+
+```tsx
+<InputTextField
+    value={c => c.email}
+    title="Email"
+    pt={{ root: { className: 'border-2 border-sky-500' } }}
+/>
+```
+
+### 2. Multi-slot composites
+
+The wrapper composes more than one PrimeReact widget and exposes a sibling set of `*Pt` / `*PtOptions` / `*Unstyled` / `*ClassName` props per slot.
+
+#### `Dialog`-based dialogs
+
+`CommandDialog` is a single Dialog and forwards `pt`/`ptOptions`/`unstyled` to that Dialog.
+
+`StepperCommandDialog` composes a Dialog **and** a Stepper:
+
+| Prop | Targets |
+|---|---|
+| `pt` / `ptOptions` / `unstyled` | The inner PrimeReact Stepper. |
+| `dialogPt` / `dialogPtOptions` / `dialogUnstyled` / `dialogClassName` | The outer PrimeReact Dialog. |
+
+```tsx
+<StepperCommandDialog<RegisterAuthor>
+    command={RegisterAuthor}
+    title="Register author"
+    pt={{ stepperpanel: { content: { className: 'pt-6' } } }}
+    dialogPt={{ header: { className: 'bg-slate-900 text-slate-50' } }}
+    dialogClassName="shadow-2xl"
+>
+    …
+</StepperCommandDialog>
+```
+
+#### Data tables and pages
+
+`DataTableForQuery` and `DataTableForObservableQuery` each compose a DataTable **and** a Paginator:
+
+| Prop | Targets |
+|---|---|
+| `pt` / `ptOptions` / `unstyled` / `className` | The inner DataTable. |
+| `paginatorPt` / `paginatorPtOptions` / `paginatorUnstyled` | The inner Paginator. |
+
+`DataPage` composes a DataTable **and** a Menubar:
+
+| Prop | Targets |
+|---|---|
+| `tablePt` / `tablePtOptions` / `tableUnstyled` / `tableClassName` | The inner DataTable. |
+| `menubarPt` / `menubarPtOptions` / `menubarUnstyled` / `menubarClassName` | The action Menubar. |
+
+```tsx
+<DataPage<AllAuthors, Author, never>
+    title="Authors"
+    query={AllAuthors}
+    tablePt={{ table: { className: 'min-w-full divide-y divide-slate-700' } }}
+    menubarPt={{ root: { className: 'px-3 py-2 bg-slate-900' } }}
+>
+    <DataPage.MenuItems>…</DataPage.MenuItems>
+    <DataPage.Columns>…</DataPage.Columns>
+</DataPage>
+```
+
+### 3. Large composites
+
+These wrappers render many PrimeReact widgets internally (`InputText`, `InputNumber`, `Checkbox`, `Calendar`, `InputTextarea`, `Dropdown`, `Button`, `Menubar`, …). Exposing a `pt` prop per inner widget would be impractical; instead, they expose **`className`** on the root for layout/positioning, and you restyle their internals via the **global `pt` preset** on [`CratisComponentsProvider`](../Common/cratis-components-provider.md).
+
+| Wrapper | What it accepts | How to restyle internals |
+|---|---|---|
+| `ObjectContentEditor`   | `className` | Global `pt` on `CratisComponentsProvider` covering `inputtext`, `inputnumber`, `checkbox`, `calendar`, `inputtextarea`. |
+| `ObjectNavigationalBar` | `className` | Global `pt` covering `button`; `--cratis-surface-border` for the bottom border. |
+| `SchemaEditor`          | `className` | Global `pt` covering `menubar`, `button`, `datatable`, `dropdown`, `inputtext`. |
+
+Example with a global preset:
+
+```tsx
+<CratisComponentsProvider value={{
+    unstyled: true,
+    pt: {
+        inputtext: { root: { className: 'my-input' } },
+        inputnumber: { input: { root: { className: 'my-input' } } },
+        button: { root: { className: 'my-btn' } },
+        /* … */
+    }
+}}>
+    <ObjectContentEditor object={data} schema={schema} editMode />
+</CratisComponentsProvider>
+```
+
+## Where the global `pt` reaches
+
+A `pt` preset on `CratisComponentsProvider` flows into **every** PrimeReact widget rendered by every wrapper — including the internals of the large composites. Per-instance `pt` props on individual wrappers are *merged* with the global preset (PrimeReact's `ptOptions.mergeSections` defaults to `true`).
+
+To replace a slot's preset entirely on a single instance, opt out of merging:
+
+```tsx
+<Button label="Special" pt={{ root: { className: 'special-btn' } }}
+        ptOptions={{ mergeSections: false }} />
+```
+
+## Components that do NOT accept per-instance `pt`
+
+- **`BusyIndicatorDialog`** — the dialog is rendered by the dialog host on demand and the request type lives in `@cratis/arc.react`, so no per-instance prop is plumbed through. Use the **global `pt`** on `CratisComponentsProvider` to restyle it.
+
+## See also
+
+- [CratisComponentsProvider](../Common/cratis-components-provider.md) — global `pt` / `unstyled` setup
+- [Path C — Fully unstyled](unstyled.md) — full pt-preset walk-through
diff --git a/Documentation/Styling/themed.md b/Documentation/Styling/themed.md
new file mode 100644
index 0000000..7ebb7b5
--- /dev/null
+++ b/Documentation/Styling/themed.md
@@ -0,0 +1,104 @@
+# Path A — PrimeReact-themed (fastest start)
+
+You want components to look reasonable out of the box and only intervene when needed. Pick this path for prototypes, internal tools, or any app where one of the prebuilt PrimeReact themes is good enough.
+
+## Setup
+
+Load any PrimeReact theme stylesheet alongside Cratis Components. PrimeReact's own widgets paint themselves from the theme, and the `--cratis-*` tokens cascade to the matching theme variables so Cratis-scoped surfaces follow along:
+
+```tsx
+// 1. Theme first, then Cratis styles so any --cratis-* override wins.
+import 'primereact/resources/themes/lara-dark-blue/theme.css';
+import 'primeicons/primeicons.css';
+import '@cratis/components/styles';
+
+import { CratisComponentsProvider } from '@cratis/components';
+
+export const App = () => (
+    <CratisComponentsProvider>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+Available themes ship inside the `primereact/resources/themes/` directory — Lara, Soho, Viva, Vela, Bootstrap, Material, Tailwind, and others, each in light/dark and a handful of accent colors. Pick whichever matches your app.
+
+## Override one component with CSS
+
+When you want to tweak a single widget without redesigning anything, plain CSS works on top of the theme. Target PrimeReact's own class names for global overrides:
+
+```css
+/* yourApp.css */
+.p-button {
+    border-radius: 999px;  /* pill buttons everywhere */
+}
+```
+
+…or target your own class names on Cratis wrappers:
+
+```css
+.dangerous-button {
+    background: var(--cratis-red-500);
+    color: white;
+}
+```
+
+```tsx
+<Button label="Delete" className="dangerous-button" />
+```
+
+## Override one component with Tailwind
+
+Every Cratis wrapper accepts a `className` prop. Pass Tailwind utility classes straight through:
+
+```tsx
+<InputTextField value={c => c.name}
+                className="rounded-2xl bg-slate-900 text-slate-50" />
+
+<Dialog title="Confirm" className="shadow-2xl rounded-3xl">
+    {/* … */}
+</Dialog>
+```
+
+For multi-slot composites like `StepperCommandDialog` or `DataPage`, the `className` is on the outer wrapper. Use the per-slot props (`dialogClassName`, `tableClassName`, `menubarClassName`) when you need to target an inner widget. See the [pass-through cheat sheet](pass-through.md) for the full list.
+
+## Tint a specific Cratis surface
+
+Validation error text, the FormElement addon, breadcrumb bottom borders, and other Cratis-specific surfaces read from `--cratis-*` tokens (not from PrimeReact's variables). Override the relevant token to retint just those surfaces while leaving the PrimeReact theme untouched:
+
+```css
+:root {
+    /* Make Cratis validation errors a brand-distinct orange-red. */
+    --cratis-red-500: #f97316;
+
+    /* Round Cratis addons a bit harder than the theme. */
+    --cratis-border-radius: 12px;
+}
+```
+
+See the [Cratis token reference](cratis-tokens.md) for the full list and which surface each token controls.
+
+## Per-instance pass-through
+
+When CSS overrides aren't enough — for example, when you need to attach a class to a specific slot inside a PrimeReact widget — use the `pt` prop:
+
+```tsx
+<Dialog
+    title="Confirm"
+    pt={{
+        header: { className: 'bg-sky-600 text-white' },
+        content: { className: 'p-6' },
+    }}
+>
+    …
+</Dialog>
+```
+
+`pt`, `ptOptions`, and `unstyled` are typed from the underlying PrimeReact component, so your IDE autocompletes the available slot names.
+
+## When to switch paths
+
+You'll outgrow Path A when:
+
+- The PrimeReact theme is "almost" but not your brand — switch to [Path B](custom-palette.md) and override the PrimeReact variables on `:root`.
+- You're integrating into a design system that defines its own button, dialog, and input visuals — switch to [Path C](unstyled.md) and bring everything yourself.
diff --git a/Documentation/Styling/toc.yml b/Documentation/Styling/toc.yml
new file mode 100644
index 0000000..44ad126
--- /dev/null
+++ b/Documentation/Styling/toc.yml
@@ -0,0 +1,16 @@
+- name: Overview
+  href: index.md
+- name: Getting Started
+  href: getting-started.md
+- name: Path A — PrimeReact-themed
+  href: themed.md
+- name: Path B — Custom palette
+  href: custom-palette.md
+- name: Path C — Fully unstyled
+  href: unstyled.md
+- name: Cratis token reference
+  href: cratis-tokens.md
+- name: Pass-through (pt) cheat sheet
+  href: pass-through.md
+- name: Mixing paths
+  href: mixing-paths.md
diff --git a/Documentation/Styling/unstyled.md b/Documentation/Styling/unstyled.md
new file mode 100644
index 0000000..e1a13c2
--- /dev/null
+++ b/Documentation/Styling/unstyled.md
@@ -0,0 +1,277 @@
+# Path C — Fully unstyled (you own every visual)
+
+You're integrating Cratis Components into a design system that defines its own button, dialog, and input visuals. You want zero PrimeReact CSS in the final bundle.
+
+This path disables every PrimeReact base style at the provider and supplies visuals through PrimeReact's `pt` (pass-through) mechanism, your own CSS, or both. Components render structurally only — they become a blank canvas you paint.
+
+## Setup
+
+```tsx
+import '@cratis/components/styles';   // tokens + Tailwind utilities still useful for spacing/layout
+import { CratisComponentsProvider } from '@cratis/components';
+import { globalPt } from './pt-preset';
+
+export const App = () => (
+    <CratisComponentsProvider value={{ unstyled: true, pt: globalPt }}>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+`unstyled: true` removes every PrimeReact base style. The `pt` preset is what fills the visual vacuum. Without one, components render as raw HTML elements with browser defaults.
+
+The two sub-paths below show the same preset in two different styling languages. Pick whichever your design system uses.
+
+## With plain CSS
+
+Attach class names from your own stylesheet via a global preset:
+
+```ts
+// pt-preset.ts
+export const globalPt = {
+    button: {
+        root: { className: 'my-btn' },
+    },
+    dialog: {
+        root:    { className: 'my-dialog' },
+        header:  { className: 'my-dialog__header' },
+        content: { className: 'my-dialog__body' },
+        mask:    { className: 'my-dialog__mask' },
+    },
+    inputtext: {
+        root: { className: 'my-input' },
+    },
+} as const;
+```
+
+```css
+/* yourApp.css */
+.my-btn {
+    display: inline-flex;
+    align-items: center;
+    padding: 0.5rem 1rem;
+    background: var(--cratis-primary-color);
+    color: var(--cratis-primary-color-text);
+    border: none;
+    border-radius: var(--cratis-border-radius);
+    cursor: pointer;
+}
+
+.my-btn:hover  { filter: brightness(1.1); }
+.my-btn:active { filter: brightness(0.9); }
+.my-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+
+.my-dialog {
+    border-radius: 16px;
+    overflow: hidden;
+    box-shadow: 0 20px 40px rgba(0, 0, 0, 0.4);
+}
+
+.my-dialog__header {
+    padding: 1rem 1.25rem;
+    background: var(--cratis-surface-card);
+    border-bottom: 1px solid var(--cratis-surface-border);
+    font-weight: 600;
+}
+
+.my-dialog__body {
+    padding: 1.25rem;
+    background: var(--cratis-surface-card);
+    color: var(--cratis-text-color);
+}
+
+.my-dialog__mask {
+    background: rgba(15, 23, 42, 0.7);
+    backdrop-filter: blur(4px);
+}
+
+.my-input {
+    width: 100%;
+    padding: 0.5rem 0.75rem;
+    background: var(--cratis-surface-100);
+    border: 1px solid var(--cratis-surface-border);
+    border-radius: 6px;
+    color: var(--cratis-text-color);
+}
+
+.my-input:focus {
+    outline: 2px solid var(--cratis-primary-color);
+    outline-offset: 1px;
+}
+```
+
+This is the most discoverable shape: every PrimeReact slot gets a single dedicated class in your own CSS file. You can grep, refactor, and reuse the same classes outside Cratis Components without coupling to PrimeReact's internals.
+
+## With TailwindCSS
+
+Same shape, Tailwind utility classes as the class strings:
+
+```ts
+// pt-preset.ts
+export const globalPt = {
+    button: {
+        root: {
+            className: [
+                'inline-flex items-center justify-center gap-2',
+                'px-4 py-2 rounded-lg font-medium',
+                'bg-sky-500 text-white',
+                'hover:bg-sky-400 active:bg-sky-600',
+                'disabled:opacity-50 disabled:cursor-not-allowed',
+                'transition-colors',
+                'focus:outline-none focus-visible:ring-2 focus-visible:ring-sky-400',
+            ].join(' '),
+        },
+        label: { className: 'whitespace-nowrap' },
+        icon:  { className: 'shrink-0' },
+    },
+
+    inputtext: {
+        root: {
+            className: [
+                'w-full px-3 py-2 rounded-md',
+                'bg-slate-800 text-slate-50',
+                'border border-slate-700',
+                'placeholder:text-slate-400',
+                'focus:border-sky-400 focus:outline-none',
+                'focus-visible:ring-2 focus-visible:ring-sky-400',
+            ].join(' '),
+        },
+    },
+
+    dialog: {
+        root: {
+            className: [
+                'rounded-2xl shadow-2xl overflow-hidden',
+                'bg-slate-900 text-slate-50',
+            ].join(' '),
+        },
+        header: {
+            className: [
+                'flex items-center justify-between gap-4',
+                'px-5 py-3 font-semibold',
+                'bg-slate-800 text-slate-50 border-b border-slate-700',
+            ].join(' '),
+        },
+        headerTitle: { className: 'text-base' },
+        closeButton: { className: 'p-1 rounded hover:bg-slate-700 transition-colors' },
+        content:     { className: 'p-5 bg-slate-900 text-slate-100' },
+        footer:      { className: 'px-5 py-3 bg-slate-800 border-t border-slate-700 flex justify-end gap-2' },
+        mask:        { className: 'bg-slate-950/70 backdrop-blur-sm' },
+    },
+
+    dropdown: {
+        root: {
+            className: [
+                'w-full inline-flex items-center justify-between gap-2',
+                'px-3 py-2 rounded-md cursor-pointer',
+                'bg-slate-800 text-slate-50 border border-slate-700',
+                'hover:border-slate-500',
+                'focus:outline-none focus-visible:ring-2 focus-visible:ring-sky-400',
+            ].join(' '),
+        },
+        input:   { className: 'flex-1 truncate text-left' },
+        trigger: { className: 'shrink-0 text-slate-400' },
+        panel:   { className: 'mt-1 rounded-md shadow-xl overflow-hidden bg-slate-800 border border-slate-700' },
+        item:    { className: 'px-3 py-2 cursor-pointer hover:bg-slate-800' },
+    },
+
+    checkbox: {
+        root: { className: 'inline-flex items-center' },
+        box: {
+            className: [
+                'w-4 h-4 rounded',
+                'border border-slate-500 bg-slate-800',
+                'data-[p-highlight=true]:bg-sky-500 data-[p-highlight=true]:border-sky-500',
+            ].join(' '),
+        },
+        icon: { className: 'text-white text-xs' },
+    },
+
+    datatable: {
+        root:       { className: 'w-full' },
+        table:      { className: 'w-full text-sm' },
+        thead:      { className: 'bg-slate-800 text-slate-300 uppercase text-xs tracking-wider' },
+        headerRow:  { className: 'border-b border-slate-700' },
+        headerCell: { className: 'px-3 py-2 text-left font-medium' },
+        tbody:      { className: 'divide-y divide-slate-800' },
+        bodyRow:    { className: 'hover:bg-slate-800/60 transition-colors' },
+        bodyCell:   { className: 'px-3 py-2 text-slate-100' },
+    },
+
+    menubar: {
+        root:     { className: 'flex items-center gap-1 px-3 py-2 bg-slate-800 border-b border-slate-700' },
+        menuitem: { className: 'rounded' },
+        action:   { className: 'inline-flex items-center gap-2 px-3 py-1.5 rounded hover:bg-slate-700 cursor-pointer' },
+    },
+} as const;
+```
+
+A nearly-identical preset ships in the Storybook (`.storybook/pt-preset.ts`) — use it as a starter and fork into your own app.
+
+## Per-instance overrides
+
+Anything global can be overridden per-instance:
+
+```tsx
+<Dialog
+    title="Brand callout"
+    pt={{
+        root:   { className: 'rounded-none' },
+        header: { className: 'bg-pink-600 text-white' },
+    }}
+>
+    …
+</Dialog>
+
+<InputTextField
+    value={c => c.name}
+    pt={{ root: { className: 'border-2 border-pink-500' } }}
+/>
+```
+
+Per-instance `pt` is **merged** with the global preset by default (`ptOptions.mergeSections: true` is PrimeReact's default). To replace a slot entirely instead, set `ptOptions={{ mergeSections: false }}` on the wrapper.
+
+## Composite components in unstyled mode
+
+`DataPage` and `StepperCommandDialog` compose multiple PrimeReact widgets and expose explicit per-slot props. The global `pt` reaches every internal widget; per-instance overrides target the inner slot directly:
+
+```tsx
+<DataPage<AllAuthors, Author, never>
+    title="Authors"
+    query={AllAuthors}
+    tablePt={{ table: { className: 'min-w-full divide-y divide-slate-700' } }}
+    menubarPt={{ root: { className: 'px-3 py-2 bg-slate-900' } }}
+>
+    <DataPage.MenuItems>…</DataPage.MenuItems>
+    <DataPage.Columns>…</DataPage.Columns>
+</DataPage>
+
+<StepperCommandDialog<RegisterOrder>
+    command={RegisterOrder}
+    title="New order"
+    /* pt targets the inner Stepper */
+    pt={{ stepperpanel: { content: { className: 'pt-6' } } }}
+    /* dialogPt targets the outer Dialog */
+    dialogPt={{ header: { className: 'bg-slate-900' } }}
+>
+    …
+</StepperCommandDialog>
+```
+
+`ObjectContentEditor`, `ObjectNavigationalBar`, and `SchemaEditor` accept only `className` on the root — restyle their internals via the **global** `pt` preset set on `CratisComponentsProvider`. See [Pass-through cheat sheet](pass-through.md) for the full per-component reference.
+
+## What `--cratis-*` tokens give you in this path
+
+In Path C the `pt` preset carries every visual, so you don't strictly need any `--cratis-*` token. However, a few Cratis surfaces are styled with token-driven CSS (FormElement addon, ObjectNavigationalBar bottom border, inline validation errors) — overriding the relevant tokens lets you tint those surfaces consistently with your preset:
+
+```css
+:root {
+    --cratis-surface-border: theme('colors.slate.700');
+    --cratis-text-color:     theme('colors.slate.50');
+    --cratis-text-color-secondary: theme('colors.slate.400');
+    --cratis-red-500:        theme('colors.red.500');
+    --cratis-border-radius:  8px;
+}
+```
+
+See [Cratis token reference](cratis-tokens.md) for the full list and which surface each token controls.
diff --git a/Documentation/index.md b/Documentation/index.md
index 6f52692..a97774c 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -18,11 +18,25 @@ This library includes specialized components for:
 - Integrates seamlessly with Cratis Arc framework
 - Uses PrimeReact components for consistent UI/UX
 - Supports both queries and observable queries
+- Three documented [styling paths](Styling/index.md) — themed, custom palette, fully unstyled
+- Full PrimeReact `pt` (pass-through) forwarding on every wrapper for per-slot styling
 - Comprehensive Storybook documentation
 - Accessibility-focused design
 
 ## Getting Started
 
+### Install
+
+Install `@cratis/components` along with the required PrimeReact peer dependencies:
+
+```bash
+npm install @cratis/components primereact primeicons
+# or
+yarn add @cratis/components primereact primeicons
+```
+
+The optional peers (`pixi.js` for `PivotViewer`, `framer-motion` for animated panels, `allotment` for `DataPage` resizable layout) are only required when you use the corresponding component.
+
 ### Importing Styles
 
 The library ships pre-compiled utility styles that must be imported once in your application entry point (e.g. `main.tsx`):
@@ -31,7 +45,34 @@ The library ships pre-compiled utility styles that must be imported once in your
 import '@cratis/components/styles';
 ```
 
-This is required because the components use Tailwind utility classes that are compiled into the package at build time. Without this import the layout, spacing, and sizing of components will not render correctly. The import works with any bundler (Vite, webpack, Rollup) regardless of whether your application uses Tailwind.
+This is required because the components use Tailwind utility classes that are compiled into the package at build time, and because it ships the [`--cratis-*` token layer](Styling/cratis-tokens.md) every Cratis-scoped surface reads from. The import works with any bundler (Vite, webpack, Rollup) regardless of whether your application uses Tailwind.
+
+If you bring your own Tailwind setup and want only the token layer, import `@cratis/components/tokens` instead.
+
+### Wire the Provider
+
+Mount [`CratisComponentsProvider`](Common/cratis-components-provider.md) at the root of your tree to configure PrimeReact's global settings — `unstyled`, `pt`, `ptOptions`, locale, ripple, overlay z-index, and the rest:
+
+```tsx
+import '@cratis/components/styles';
+import { CratisComponentsProvider } from '@cratis/components';
+
+export const App = () => (
+    <CratisComponentsProvider>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+### Pick a styling path
+
+The components render structurally as soon as the provider is mounted. To give them a visual identity, pick one of the three documented paths:
+
+- [**Path A — PrimeReact-themed**](Styling/themed.md) — load a PrimeReact theme; tweak with CSS or `className` as needed.
+- [**Path B — Custom palette**](Styling/custom-palette.md) — keep a PrimeReact theme as the structural baseline; repaint with CSS variables on `:root`.
+- [**Path C — Fully unstyled**](Styling/unstyled.md) — disable PrimeReact's base styles; bring everything yourself via a `pt` preset (in CSS or Tailwind).
+
+See the [Styling overview](Styling/index.md) for the full mental model.
 
 ### Importing Components
 
@@ -41,23 +82,43 @@ All components are exported from the main package and can be imported as needed:
 import { CommandDialog, DataPage, PivotViewer } from '@cratis/components';
 ```
 
+For tree-shaking-friendly subpath imports:
+
+```typescript
+import { Dialog } from '@cratis/components/Dialogs';
+import { DataPage } from '@cratis/components/DataPage';
+import { InputTextField } from '@cratis/components/CommandForm/fields';
+```
+
 ## Component Categories
 
 ### Command Components
 
-Components for handling command execution and user interactions.
+Components for handling command execution and user interactions — `CommandDialog`, `StepperCommandDialog`, `CommandStepper`, and the full `CommandForm/fields` set (text, number, dropdown, date, checkbox, radio, slider, multiselect, chips, color picker).
 
 ### Data Components
 
-Components for displaying and interacting with data from queries.
+Components for displaying and interacting with data from queries — `DataPage`, `DataTableForQuery`, `DataTableForObservableQuery`.
 
 ### Common Components
 
-Reusable UI elements for building consistent layouts.
+Reusable UI elements for building consistent layouts — [`CratisComponentsProvider`](Common/cratis-components-provider.md), `Page`, `FormElement`, `Icon`, `Tooltip`, `ErrorBoundary`.
 
 ### Specialized Components
 
-Advanced components for specific use cases like schema editing and time-based data exploration.
+Advanced components for specific use cases — `PivotViewer`, `TimeMachine`, `SchemaEditor`, `ObjectContentEditor`, `ObjectNavigationalBar`.
+
+## Styling
+
+Styling is designed to stay out of the way: pick the path that matches how much control you want, and the other layers stay invisible. See the dedicated [Styling section](Styling/index.md) for:
+
+- [Getting Started](Styling/getting-started.md) — the one-line setup every path shares
+- [Path A — PrimeReact-themed](Styling/themed.md)
+- [Path B — Custom palette](Styling/custom-palette.md)
+- [Path C — Fully unstyled](Styling/unstyled.md)
+- [Cratis token reference](Styling/cratis-tokens.md)
+- [Pass-through (pt) cheat sheet](Styling/pass-through.md)
+- [Mixing paths](Styling/mixing-paths.md)
 
 ## Development
 
@@ -65,7 +126,7 @@ The components are built using:
 
 - Vite for development and bundling
 - Vitest for testing
-- Storybook for component documentation
+- Storybook for component documentation (`yarn dev` from `Source/`)
 - yarn for package management
 
 ## Documentation
diff --git a/Documentation/toc.yml b/Documentation/toc.yml
index 883660e..bcf30d6 100644
--- a/Documentation/toc.yml
+++ b/Documentation/toc.yml
@@ -172,6 +172,8 @@
             - name: High Scroll Sensitivity
               href: storybook.md?story=timemachine-timemachine--high-scroll-sensitivity
       href: storybook.md?story=timemachine-eventsview--default
+- name: Styling
+  href: Styling/toc.yml
 - name: Components
   items:
     - name: Command Components

From a16adda57665ba7a4ade7d8c262d7975ba3f1ae5 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Fri, 29 May 2026 00:17:53 +0200
Subject: [PATCH 15/23] Add migration guide for upgrading from earlier
 @cratis/components releases
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cover everything a consumer needs to know to land the upgrade safely:

Required actions
- Quick checklist with the must-do install (primereact + primeicons as
  peer deps, plus the optional peers for PivotViewer / CommandStepper /
  resizable DataPage).

Breaking changes
- primereact and primeicons moved from dependencies to peerDependencies
  (with rationale: avoids the duplicate-installation + fragmented
  PrimeReact context pitfall).
- pixi.js / framer-motion / allotment moved to optional peers (no longer
  shipped to consumers who never use those components).
- react-router-dom removed entirely (never imported by the package).

Visual changes
- FormElement addon now uses bespoke --cratis-* token styling instead of
  PrimeReact's p-inputgroup-addon chrome. Shape identical; pixels may
  drift in unusual themes.
- ObjectNavigationalBar and SchemaEditor bottom border now actually
  renders (was silent no-op without PrimeFlex). With instructions for
  overriding to transparent if the borderless look was preferred.
- Catalogue of removed hard-coded PrimeReact / PrimeFlex class hooks with
  their replacements (Button text/size/severity props, inline
  --cratis-red-500 in place of p-error, etc.).

Subpath import changes
- @cratis/components/CommandStepper now resolves (the previous exports
  map pointed at a non-existent path).
- @cratis/components/EventModeling was never real — documented and the
  README claim removed.
- New subpaths: ObjectContentEditor, ObjectNavigationalBar, SchemaEditor,
  tokens.

Recommended migrations
- Switch PrimeReactProvider call sites to CratisComponentsProvider from
  the package root.
- Consolidate per-component CSS overrides into --cratis-* token blocks
  where the surface is Cratis-scoped.
- Replace global .p-button CSS rules with per-instance pt slot config to
  avoid collisions with future PrimeReact theme updates.
- Adopt subpath imports for tree-shaking.

New optional capabilities tour
- Per-component pt / ptOptions / unstyled / className.
- Per-slot props on composites (StepperCommandDialog, DataPage,
  DataTables).
- className on the large composite editors.
- The --cratis-* token layer.
- Storybook styling toolbar.

Before / after recipes
- Root setup, restyling one Dialog, restyling the inner DataTable in
  DataPage, switching to a fully-unstyled design system.

Troubleshooting
- Module resolution failures, peer-dep warnings, sparse visuals after
  upgrade, the stale @cratis/components/EventModeling claim, and the
  pre-existing yarn build-storybook failure.

Also: wire the new guide into Documentation/toc.yml between Styling and
Components, and link it from Documentation/index.md in a new "Upgrading
from an earlier release" section. Markdown verification still passes
(markdownlint + link check, 78 files scanned).
---
 Documentation/index.md     |   4 +
 Documentation/migration.md | 422 +++++++++++++++++++++++++++++++++++++
 Documentation/toc.yml      |   2 +
 3 files changed, 428 insertions(+)
 create mode 100644 Documentation/migration.md

diff --git a/Documentation/index.md b/Documentation/index.md
index a97774c..28c2065 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -120,6 +120,10 @@ Styling is designed to stay out of the way: pick the path that matches how much
 - [Pass-through (pt) cheat sheet](Styling/pass-through.md)
 - [Mixing paths](Styling/mixing-paths.md)
 
+## Upgrading from an earlier release
+
+See the [Migration guide](migration.md) for the required install changes (PrimeReact and PrimeIcons are now peer dependencies), the visual differences to be aware of, and a tour of the new optional capabilities (Cratis Components Provider, `--cratis-*` tokens, full `pt` forwarding).
+
 ## Development
 
 The components are built using:
diff --git a/Documentation/migration.md b/Documentation/migration.md
new file mode 100644
index 0000000..66bf18b
--- /dev/null
+++ b/Documentation/migration.md
@@ -0,0 +1,422 @@
+# Migration guide — upgrading from earlier `@cratis/components`
+
+This release is the first to expose the three styling paths described in the [Styling section](Styling/index.md) and the first to ship `CratisComponentsProvider`, the `--cratis-*` token layer, and full `pt` / `unstyled` forwarding on every wrapper. It is also the release that moves PrimeReact and friends from runtime `dependencies` to `peerDependencies`, which is the dominant breaking signal.
+
+This page tells you what to change in your app, what to be aware of visually, and what new capabilities you can opt in to once the upgrade lands.
+
+## Quick checklist
+
+If you do these three things, your app will install and render correctly after the upgrade:
+
+1. **Add `primereact` and `primeicons` to your own `package.json`**:
+
+   ```bash
+   npm install primereact primeicons
+   # or
+   yarn add primereact primeicons
+   ```
+
+2. **If you use the optional components, add their peer too**:
+
+   | Component | Optional peer |
+   |---|---|
+   | `PivotViewer` | `pixi.js` |
+   | `CommandStepper` / animated panels | `framer-motion` |
+   | `DataPage` resizable layout | `allotment` |
+
+3. **Skim the [Visual changes](#visual-changes) section below** to spot anywhere the new rendering would surprise you.
+
+Everything else in this release is additive — your existing component calls continue to work without code changes.
+
+## Breaking changes
+
+### 1. `primereact` and `primeicons` are now peer dependencies
+
+In earlier releases these were direct `dependencies` of `@cratis/components`, so `npm install @cratis/components` was enough to pull them in transitively.
+
+In this release they are `peerDependencies`. You must declare them in your own `package.json`. If you don't, the install will emit a peer-dependency warning and the bundler will fail to resolve `primereact/dialog`, `primereact/button`, etc. at build time.
+
+This change avoids the duplicate-installation pitfall: consumers who already had `primereact` in their app were previously ending up with two copies — their own plus the one inside `@cratis/components` — and PrimeReact's React context fragmented across them, so `unstyled` / `pt` on one provider didn't reach widgets rendered through the other.
+
+```jsonc
+// your-app/package.json
+{
+  "dependencies": {
+    "@cratis/components": "^X.Y.Z",
+    "primereact":         "^10.9.0",
+    "primeicons":         "^7.0.0"
+    // …
+  }
+}
+```
+
+The `@cratis/arc*` packages, `react`, and `react-dom` are also peer dependencies, but you almost certainly already have them.
+
+### 2. The optional dependencies are now optional peer dependencies
+
+`pixi.js`, `framer-motion`, and `allotment` moved to peer dependencies with `peerDependenciesMeta.optional = true`. They were previously bundled as direct dependencies of `@cratis/components`, which meant **every** consumer downloaded ~5 MB of WebGL canvas code (`pixi.js`) even if they never used `PivotViewer`.
+
+| You use… | …so add to your install |
+|---|---|
+| `PivotViewer` | `pixi.js` |
+| `CommandStepper` / animated panels | `framer-motion` |
+| `DataPage` with resizable layout | `allotment` |
+
+If you don't use these components, you don't need to do anything.
+
+### 3. `react-router-dom` is no longer a dependency
+
+It was listed as a runtime dependency but never imported by anything inside `@cratis/components`. If your app uses it directly (which is very likely), you should already have it in your own `package.json` — nothing changes for you.
+
+If you were somehow relying on the transitive copy from `@cratis/components`, add it to your own deps:
+
+```bash
+yarn add react-router-dom
+```
+
+## Visual changes
+
+The styling work removes a few couplings to PrimeReact theme internals. These changes are intentional and almost always invisible, but there are two places where pixel-perfect rendering may shift.
+
+### `FormElement` addon is now Cratis-bespoke
+
+Earlier releases rendered the icon addon using PrimeReact's `p-inputgroup` / `p-inputgroup-addon` classes, so the addon picked up PrimeReact's theme-driven background and border.
+
+This release renders the addon with structural CSS using the [`--cratis-*` tokens](Styling/cratis-tokens.md):
+
+```text
+.cratis-form-element            // row
+.cratis-form-element__addon     // leading icon slot
+```
+
+The shape and intent are identical. The exact background, border, and radius now come from `--cratis-surface-100`, `--cratis-surface-border`, and `--cratis-border-radius` rather than from the loaded PrimeReact theme. In Paths [A](Styling/themed.md) and [B](Styling/custom-palette.md) the values still cascade from the PrimeReact theme by default, so the visual is essentially the same. In Path C (unstyled) the addon **still renders** instead of disappearing — a strict improvement.
+
+If you were relying on the exact PrimeReact `p-inputgroup-addon` look, the [FormElement reference](Common/form-element.md#styling) shows how to override the tokens or attach your own class via `pt` to restore it.
+
+### `ObjectNavigationalBar` and `SchemaEditor` bottom border now actually renders
+
+Earlier releases used `border-bottom-1 surface-border` — utility class names from **PrimeFlex**, a separate PrimeReact package that this library never depended on. If your app didn't already have PrimeFlex loaded, the classes were silent no-ops and the breadcrumb bar / schema editor toolbar had no visible bottom border.
+
+This release uses structural CSS that reads from `--cratis-surface-border`, so the border actually appears regardless of whether PrimeFlex is installed.
+
+If your app *did* have PrimeFlex installed, the border was already visible and looks essentially the same after upgrade. If your app *didn't* have PrimeFlex installed, you'll see a new horizontal line under the breadcrumbs and the schema editor menubar where there wasn't one before.
+
+This is arguably a bug fix — the original code was always meant to draw the border — but if you preferred the borderless look, override the token to `transparent`:
+
+```css
+:root {
+    /* Just for the navigational surfaces — PrimeReact's --surface-border stays untouched. */
+    --cratis-surface-border: transparent;
+}
+```
+
+### Other PrimeReact class hooks removed
+
+The library no longer uses these hard-coded PrimeReact class names internally:
+
+| Old class hook | Replacement |
+|---|---|
+| `p-button-text p-button-sm` | PrimeReact `Button` props: `text` and `size="small"`. |
+| `p-button-text p-button-danger p-button-sm` | PrimeReact `Button` props: `text`, `severity="danger"`, `size="small"`. |
+| `<small className="p-error">` | Inline `<small>` styled with `--cratis-red-500`. |
+| `border-bottom-1 surface-border` | See [section above](#objectnavigationalbar-and-schemaeditor-bottom-border-now-actually-renders). |
+| `p-inputgroup` / `p-inputgroup-addon` | See [section above](#formelement-addon-is-now-cratis-bespoke). |
+
+When a PrimeReact theme is loaded (Paths A and B), the Button `text` / `size` / `severity` props produce the same styling as the old class hooks — there's no visible change.
+
+## Subpath import changes
+
+### `@cratis/components/CommandStepper` now resolves
+
+Earlier releases declared a `./CommandStepper` subpath in the exports map, but it pointed at `dist/{esm,cjs}/CommandStepper/index.js`, which did not exist. The file lives at `dist/{esm,cjs}/CommandDialog/CommandStepper.js` because the source resides in `CommandDialog/`.
+
+Any consumer who tried `import { CommandStepper } from '@cratis/components/CommandStepper'` would have hit a module-resolution error. After this release, that import works.
+
+### `@cratis/components/EventModeling` was never real — it's now removed from the docs
+
+Earlier README listed `@cratis/components/EventModeling` in the available subpath exports. The path did not exist in the package's `exports` map and never did. If you tried to import from it, the import always failed. The README has been corrected.
+
+### New subpath exports
+
+Three component-folder subpaths that already had built indexes but were missing from the `exports` map have been added:
+
+```ts
+import { ObjectContentEditor } from '@cratis/components/ObjectContentEditor';
+import { ObjectNavigationalBar } from '@cratis/components/ObjectNavigationalBar';
+import { SchemaEditor } from '@cratis/components/SchemaEditor';
+```
+
+A new stylesheet subpath is also available — useful if you bring your own Tailwind setup and only want the `--cratis-*` token layer:
+
+```ts
+import '@cratis/components/tokens';
+```
+
+The recommended `@cratis/components/styles` (Tailwind utilities + tokens) continues to work and is unchanged.
+
+## Recommended migrations
+
+These are optional. Nothing in your app breaks if you skip them — but adopting them will make your code more idiomatic and unlock the new customization surface.
+
+### 1. Wrap your app in `CratisComponentsProvider`
+
+If you previously mounted `PrimeReactProvider` from `primereact/api` directly, you can keep doing that — every Cratis wrapper still reads the same context. The Cratis provider adds nothing today but reserves a single place for Cratis-wide defaults later.
+
+```tsx
+// Before — still works
+import { PrimeReactProvider } from 'primereact/api';
+
+export const App = () => (
+    <PrimeReactProvider value={{ /* … */ }}>
+        <YourApp />
+    </PrimeReactProvider>
+);
+```
+
+```tsx
+// After — recommended
+import { CratisComponentsProvider } from '@cratis/components';
+
+export const App = () => (
+    <CratisComponentsProvider value={{ /* same APIOptions */ }}>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+See [CratisComponentsProvider](Common/cratis-components-provider.md) for the full prop reference.
+
+### 2. Switch styling overrides to `--cratis-*` tokens where possible
+
+If you previously sprinkled CSS overrides across components (`.p-button { … }`, ad-hoc class names, etc.) to customize Cratis-specific surfaces — validation error color, the FormElement addon, breadcrumb borders — you can now consolidate those into a single `--cratis-*` override block:
+
+```css
+/* Before — multiple ad-hoc rules */
+.p-error { color: #f97316; }
+.my-form-addon { background: #1e293b; border-color: #334155; }
+.my-breadcrumb-bar { border-bottom: 1px solid #334155; }
+```
+
+```css
+/* After — three token overrides */
+:root {
+    --cratis-red-500:        #f97316;  /* drives p-error replacement automatically */
+    --cratis-surface-100:    #1e293b;  /* FormElement addon background */
+    --cratis-surface-border: #334155;  /* FormElement addon border, NavigationalBar border */
+}
+```
+
+See [Cratis token reference](Styling/cratis-tokens.md) for the per-token surface mapping.
+
+### 3. Replace per-component className overrides with `pt`
+
+Many wrappers now forward PrimeReact's `pt` (pass-through) prop, which lets you attach class names to individual slots inside a widget. For one-off styling, `pt` is more targeted and less likely to collide with future PrimeReact theme updates than overriding `.p-button` globally:
+
+```tsx
+// Before — class collision risk; affects all Buttons in the subtree
+<style>{`.confirm-section .p-button { background: #f97316; }`}</style>
+<div className="confirm-section">
+    <Dialog title="Confirm">…</Dialog>
+</div>
+```
+
+```tsx
+// After — scoped to this one Dialog, targets a single slot
+<Dialog
+    title="Confirm"
+    pt={{
+        header: { className: 'bg-orange-500' },
+        content: { className: 'p-6' },
+    }}
+>
+    …
+</Dialog>
+```
+
+See [Pass-through cheat sheet](Styling/pass-through.md) for every wrapper's available slots and the per-component patterns (single-widget vs. multi-slot composite vs. large composite).
+
+### 4. Adopt subpath imports for tree-shaking
+
+If you only use a few components, prefer subpath imports so unused parts of the package tree-shake out:
+
+```ts
+// Before — pulls in everything
+import { Dialog, DataPage, InputTextField } from '@cratis/components';
+```
+
+```ts
+// After — tree-shaking-friendly
+import { Dialog } from '@cratis/components/Dialogs';
+import { DataPage } from '@cratis/components/DataPage';
+import { InputTextField } from '@cratis/components/CommandForm/fields';
+```
+
+The root import (`@cratis/components`) still works and is fine when you use most of the package.
+
+## New optional capabilities
+
+These are additions, not migrations — nothing in your code needs to change to use them. They become available once you upgrade.
+
+### Per-component `pt` / `ptOptions` / `unstyled` / `className`
+
+Every Cratis wrapper now forwards PrimeReact's pass-through and unstyled props to the underlying widget. Pass them per-instance to restyle one component, or set a global preset on `CratisComponentsProvider` to apply across the whole app:
+
+```tsx
+<CratisComponentsProvider value={{ unstyled: true, pt: globalPt }}>
+    <YourApp />
+</CratisComponentsProvider>
+```
+
+The [Pass-through cheat sheet](Styling/pass-through.md) lists each wrapper's slot surface.
+
+### Per-slot props on composites
+
+Wrappers that compose more than one PrimeReact widget expose explicit per-slot props so you can target each slot independently:
+
+| Composite | Per-slot props |
+|---|---|
+| `StepperCommandDialog` | `pt` / `unstyled` (Stepper) + `dialogPt` / `dialogPtOptions` / `dialogUnstyled` / `dialogClassName` (Dialog). |
+| `DataPage` | `tablePt` / `tablePtOptions` / `tableUnstyled` / `tableClassName` + `menubarPt` / `menubarPtOptions` / `menubarUnstyled` / `menubarClassName`. |
+| `DataTableForQuery` / `DataTableForObservableQuery` | `pt` / `unstyled` / `className` (DataTable) + `paginatorPt` / `paginatorPtOptions` / `paginatorUnstyled` (Paginator). |
+
+### `className` on composite editors
+
+`ObjectContentEditor`, `ObjectNavigationalBar`, and `SchemaEditor` now accept a `className` prop on the root for layout / positioning. Internal widget restyling continues to go through the global `pt` preset on `CratisComponentsProvider`.
+
+### `--cratis-*` token layer
+
+A scoped Cratis token layer is now part of every install. Tokens default to the PrimeReact theme variable with the same name minus the `--cratis-` prefix, so Paths A and B continue to look the way they always did. Override `--cratis-*` only when you want a Cratis-scoped surface tinted independently of the surrounding PrimeReact widgets — see [Cratis token reference](Styling/cratis-tokens.md).
+
+### Storybook styling toolbar
+
+`yarn dev` from `Source/` opens Storybook with a five-mode **Styling** toolbar (paintbrush icon) that flips between the three documented paths — useful for previewing how each path looks before committing to one in your app.
+
+## Migration recipes — before / after
+
+A handful of common patterns shown as before/after diffs.
+
+### Set up styling once at the root
+
+```tsx
+// Before
+import 'primereact/resources/themes/lara-dark-blue/theme.css';
+import 'primeicons/primeicons.css';
+import '@cratis/components/styles';
+import { PrimeReactProvider } from 'primereact/api';
+
+export const App = () => (
+    <PrimeReactProvider value={{ ripple: true }}>
+        <YourApp />
+    </PrimeReactProvider>
+);
+```
+
+```tsx
+// After
+import 'primereact/resources/themes/lara-dark-blue/theme.css';
+import 'primeicons/primeicons.css';
+import '@cratis/components/styles';
+import { CratisComponentsProvider } from '@cratis/components';
+
+export const App = () => (
+    <CratisComponentsProvider value={{ ripple: true }}>
+        <YourApp />
+    </CratisComponentsProvider>
+);
+```
+
+### Restyle one Dialog instance
+
+```tsx
+// Before — global CSS rule
+// styles.css
+// .confirm-dialog .p-dialog-header { background: #1e40af; color: white; }
+
+<Dialog title="Confirm" className="confirm-dialog">…</Dialog>
+```
+
+```tsx
+// After — per-instance pt
+<Dialog
+    title="Confirm"
+    pt={{ header: { className: 'bg-blue-700 text-white' } }}
+>
+    …
+</Dialog>
+```
+
+### Restyle the inner DataTable in DataPage
+
+```tsx
+// Before — only the outer wrapper had a className escape hatch
+<DataPage title="Authors" query={AllAuthors}>
+    <DataPage.MenuItems>…</DataPage.MenuItems>
+    <DataPage.Columns>…</DataPage.Columns>
+</DataPage>
+// Couldn't reach the inner DataTable without forking.
+```
+
+```tsx
+// After — per-slot pt
+<DataPage
+    title="Authors"
+    query={AllAuthors}
+    tablePt={{ table: { className: 'min-w-full divide-y divide-slate-700' } }}
+    menubarPt={{ root: { className: 'bg-slate-900' } }}
+>
+    <DataPage.MenuItems>…</DataPage.MenuItems>
+    <DataPage.Columns>…</DataPage.Columns>
+</DataPage>
+```
+
+### Switch to a fully-unstyled design system
+
+```tsx
+// Before — there was no path here. You either lived with PrimeReact theming
+// or wrote a custom PrimeReact theme.
+
+// After — flip the provider into unstyled mode and supply a pt preset.
+<CratisComponentsProvider value={{ unstyled: true, pt: globalPt }}>
+    <YourApp />
+</CratisComponentsProvider>
+```
+
+See [Path C — Fully unstyled](Styling/unstyled.md) for complete worked examples in both plain CSS and TailwindCSS.
+
+## Troubleshooting
+
+### "Cannot find module 'primereact/dialog'" after upgrade
+
+You haven't added `primereact` to your own `package.json`. Run:
+
+```bash
+yarn add primereact primeicons
+```
+
+### Peer-dependency warnings on install
+
+Same root cause — the install is telling you which peer is missing. The required peers are `primereact` and `primeicons`; the optional ones (`pixi.js`, `framer-motion`, `allotment`) only matter if you use the corresponding component.
+
+### Sparse / missing visuals after upgrade
+
+You've already loaded a PrimeReact theme (you're not in Path C). Most likely one of:
+
+- You're using `FormElement` and the addon now looks slightly different — see [FormElement addon is now Cratis-bespoke](#formelement-addon-is-now-cratis-bespoke).
+- You're seeing the bottom border under `ObjectNavigationalBar` or `SchemaEditor`'s menubar where you didn't see it before — see [the section on that](#objectnavigationalbar-and-schemaeditor-bottom-border-now-actually-renders).
+
+If components look fully unstyled (no padding, no borders, no dialog frame), you forgot to load a PrimeReact theme. See [Path A — PrimeReact-themed](Styling/themed.md).
+
+### "Module not found: '@cratis/components/EventModeling'"
+
+This subpath never existed — the README claimed it did. There's no replacement to migrate to. If you were relying on this import, please open an issue describing what you were importing from it.
+
+### Storybook static build (`yarn build-storybook`) fails
+
+Pre-existing issue in the Storybook + lightningcss + Vite pipeline, not introduced by this release. The dev server (`yarn dev`) is unaffected and is the recommended consumer path.
+
+## See also
+
+- [Styling Overview](Styling/index.md) — three styling paths and the mental model
+- [CratisComponentsProvider](Common/cratis-components-provider.md) — provider configuration
+- [Cratis token reference](Styling/cratis-tokens.md) — `--cratis-*` token catalogue
+- [Pass-through cheat sheet](Styling/pass-through.md) — per-component `pt` surface
diff --git a/Documentation/toc.yml b/Documentation/toc.yml
index bcf30d6..aca6a09 100644
--- a/Documentation/toc.yml
+++ b/Documentation/toc.yml
@@ -174,6 +174,8 @@
       href: storybook.md?story=timemachine-eventsview--default
 - name: Styling
   href: Styling/toc.yml
+- name: Migration guide
+  href: migration.md
 - name: Components
   items:
     - name: Command Components

From 53ff5fee27aa3f3019a895e7cf9e03d7b380fc3b Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Fri, 29 May 2026 07:53:37 +0200
Subject: [PATCH 16/23] Expand component-level JSDoc with Arc integration and
 unique-feature notes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previous JSDoc on the exported components covered the props well but was
thin on what the components actually do, how they integrate with the Arc
framework, and what makes each one distinct from the underlying PrimeReact
widget. Rewrite the component-level docblocks to fill that gap so the
IDE-surfaced documentation answers the questions a consumer would ask
encountering the component for the first time.

Dialog
- Document the @cratis/arc.react/dialogs host integration: how a Dialog
  inside a DialogHost discovers the context via useDialogContext() and
  closes through it automatically, with a worked useDialog + closeDialog
  call-site example.
- Cover the confirm/cancel callback contract (return false keeps open),
  the busy state used by command-executing wrappers, the validity gate,
  and the typed DialogButtons enum.

CommandDialog
- Spell out where TCommand comes from (auto-generated proxy from a C#
  [Command] record produced by dotnet build) and what the typed result
  contract is.
- Walk through what happens on confirm: onBeforeExecute transform →
  Arc command pipeline → onSuccess / onValidationFailure / onFailed
  branches, with the dialog's isBusy state tracked throughout.
- Document the value={c => c.prop} accessor as the field-binding pattern,
  including the type-inference behavior.
- Add a worked example with useDialog<CommandResult<TResponse>>() showing
  the typed-result idiom.
- Call out what's special vs. raw Dialog + CommandForm.

StepperCommandDialog
- Explain that TCommand is a single command split into stages, not
  multiple commands.
- Document the per-step error indicator behavior (red step number when
  any field in a visited step has an error), the linear-progression
  default, the visited-step tracking, and that submit only fires on the
  last step.
- Add a worked example using useDialog<CommandResult<...>> with
  StepperPanel children.
- Spell out the pt vs. dialogPt slot distinction.

CommandStepper
- Position as the embedded, non-modal counterpart of
  StepperCommandDialog for use directly inside a page region.
- Note the absence of dialogPt because there is no outer dialog.

BusyIndicatorDialog
- Make explicit that consumers do not instantiate this directly — it is
  rendered by the dialog host in response to showBusyIndicator from
  @cratis/arc.react/dialogs. Worked usage example with the typical
  try/finally pattern around a long-running operation.
- Explain why per-instance pt is not exposed (request type owned by
  arc.react) and how to restyle via the global pt preset.

DataPage
- Explain that both IQueryFor and IObservableQueryFor are accepted and
  the correct inner table (DataTableForQuery vs ForObservableQuery) is
  selected automatically via runtime prototype inspection.
- Document the three declarative children (MenuItems, Columns, optional
  detailsComponent), the selection lifecycle, and the
  disableOnUnselected pattern.
- Worked example with three menu items, two columns, and a details pane.

DataTableForQuery
- Identify the query class as Arc proxy from a C# read model static
  query method.
- Document lazy paging (server returns one page at a time), the
  clientFiltering toggle, and defaultFilters seeding.
- Worked example.

DataTableForObservableQuery
- Position as the real-time variant: WebSocket subscription via
  useObservableQueryWithPaging from @cratis/arc.react/queries; rows
  appear and disappear as the underlying read model changes server-side.
- Document the ResizeObserver-driven scrollable-height behavior.
- Worked example using a sessions read model.

CommandForm fields (13 files)
- InputTextField becomes the canonical reference: explains the
  value={c => c.prop} accessor, how asCommandFormField from
  @cratis/arc.react/commands wires up the binding, the end-to-end
  type inference, and the automatic validation-state propagation.
- The other twelve fields keep their existing examples but now include
  the specific TypeScript type they bind to (string, number, boolean,
  Date | null, string[], Array<string | number>, etc.) and link back
  to InputTextField for the full binding model.

tsc, eslint and the 146 vitest specs remain clean.
---
 Source/CommandDialog/CommandDialog.tsx        | 98 ++++++++++++++++---
 Source/CommandDialog/CommandStepper.tsx       | 72 ++++++++++----
 Source/CommandDialog/StepperCommandDialog.tsx | 97 ++++++++++++++----
 Source/CommandForm/fields/CalendarField.tsx   |  6 +-
 Source/CommandForm/fields/CheckboxField.tsx   |  5 +-
 Source/CommandForm/fields/ChipsField.tsx      |  6 +-
 .../CommandForm/fields/ColorPickerField.tsx   |  6 +-
 Source/CommandForm/fields/DropdownField.tsx   |  7 +-
 Source/CommandForm/fields/InputTextField.tsx  | 36 +++++--
 .../CommandForm/fields/MultiSelectField.tsx   |  7 +-
 Source/CommandForm/fields/NumberField.tsx     |  7 +-
 .../CommandForm/fields/RadioButtonField.tsx   | 13 ++-
 Source/CommandForm/fields/RadioGroupField.tsx |  8 +-
 Source/CommandForm/fields/SliderField.tsx     |  5 +-
 Source/CommandForm/fields/TextAreaField.tsx   |  8 +-
 Source/DataPage/DataPage.tsx                  | 71 ++++++++++++--
 .../DataTableForObservableQuery.tsx           | 66 +++++++++++--
 Source/DataTables/DataTableForQuery.tsx       | 62 ++++++++++--
 Source/Dialogs/BusyIndicatorDialog.tsx        | 51 ++++++++--
 Source/Dialogs/Dialog.tsx                     | 81 +++++++++++----
 20 files changed, 565 insertions(+), 147 deletions(-)

diff --git a/Source/CommandDialog/CommandDialog.tsx b/Source/CommandDialog/CommandDialog.tsx
index f6cf258..6d43ab3 100644
--- a/Source/CommandDialog/CommandDialog.tsx
+++ b/Source/CommandDialog/CommandDialog.tsx
@@ -182,27 +182,93 @@ const CommandDialogWrapper = <TCommand extends object, TResponse = object>({
 };
 
 /**
- * A {@link Dialog} that wraps a `CommandForm`, executes the bound command on
- * confirm, and closes only when the command succeeds. While the command is
- * running the dialog enters a busy state and disables its action buttons; on
- * validation or execution failure it stays open and propagates the result to
- * the form so field-level errors render automatically.
+ * A {@link Dialog} that hosts a Cratis Arc `CommandForm`, runs the bound
+ * command on confirm, and only closes when the command succeeds. This is
+ * the standard pattern for "user fills in a form, clicks OK, command runs
+ * server-side, dialog dismisses" — `CommandDialog` collapses about thirty
+ * lines of orchestration into the props on a single component.
  *
- * Children that are `CommandFormField` instances bind to the command's
- * properties via the `value` accessor (`value={c => c.name}`); arbitrary
- * non-field children are rendered as plain content.
+ * ## Where `TCommand` comes from
+ *
+ * `TCommand` is an auto-generated TypeScript class produced by the Arc proxy
+ * generator from a C# `[Command]` record. `dotnet build` writes a `.ts` file
+ * per command with the right property types and a typed `execute()` method;
+ * importing the class is all the connection-to-the-backend you need. The
+ * class also exposes a `.use()` hook for direct (non-dialog) usage and a
+ * `useWithChangeTracking()` variant.
+ *
+ * ## What happens on confirm
+ *
+ * 1. If `onBeforeExecute` is supplied, it transforms the command values.
+ *    Used for generated IDs (`Guid.create()`) that the user did not type in.
+ * 2. The command's `execute()` runs through Arc's command pipeline. The
+ *    backend handler returns either a typed response (mapped to `TResponse`)
+ *    or a `ValidationResult[]`.
+ * 3. On `IsSuccess: true`, `onSuccess(response)` fires and the dialog closes
+ *    through the dialog host context.
+ * 4. On a validation failure, `onValidationFailure(errors)` fires and the
+ *    form's per-field error display is updated. The dialog stays open.
+ * 5. On a domain or transport failure, `onFailed(result)` fires. The dialog
+ *    stays open and the `CommandResult` is set on the form context so the
+ *    UI can surface the error to the user.
+ *
+ * Throughout, the dialog is in the `isBusy` state — every action button is
+ * disabled and the confirm button shows a spinner.
+ *
+ * ## Field binding
+ *
+ * Children that are `CommandFormField` instances (`InputTextField`,
+ * `NumberField`, `DropdownField`, every `@cratis/components/CommandForm/fields`
+ * widget) bind to a property on the command via the `value` accessor:
+ *
+ * ```tsx
+ * <InputTextField value={c => c.name} title="Name" />
+ * ```
+ *
+ * The accessor's argument is the command instance — TypeScript infers
+ * `c.name` is a string and the field type-checks against that. Arbitrary
+ * non-field children (custom layout, additional text, decorative elements)
+ * are rendered as plain content.
+ *
+ * ## Typed dialog host usage
+ *
+ * Combine with `useDialog<CommandResult<TResponse>>()` from
+ * `@cratis/arc.react/dialogs` to get a fully-typed result at the call site:
  *
  * ```tsx
- * <CommandDialog<RegisterAuthor> title="Register author"
- *                                command={RegisterAuthor}
- *                                onSuccess={onCreated}>
- *     <InputTextField value={c => c.name} title="Name" />
- *     <InputTextField value={c => c.email} title="Email" />
- * </CommandDialog>
+ * import { useDialog, DialogResult } from '@cratis/arc.react/dialogs';
+ * import { CommandDialog } from '@cratis/components/CommandDialog';
+ * import { RegisterAuthor } from './RegisterAuthor';   // proxy from C#
+ *
+ * type RegisterAuthorResponse = { authorId: string };
+ *
+ * const RegisterAuthorDialog = () => {
+ *     const { closeDialog } = useDialogContext<CommandResult<RegisterAuthorResponse>>();
+ *     return (
+ *         <CommandDialog<RegisterAuthor, RegisterAuthorResponse>
+ *             command={RegisterAuthor}
+ *             title="Register author"
+ *             okLabel="Register"
+ *             onSuccess={(response) => closeDialog(DialogResult.Ok)}
+ *             onCancel={() => closeDialog(DialogResult.Cancelled)}>
+ *             <InputTextField value={c => c.name}  title="Name" />
+ *             <InputTextField value={c => c.email} title="Email" />
+ *         </CommandDialog>
+ *     );
+ * };
  * ```
  *
- * @typeParam TCommand - The command record type. Defaults to `object`.
- * @typeParam TResponse - The success payload type. Defaults to `object`.
+ * ## What's special vs. raw Dialog + CommandForm
+ *
+ * - Confirm wiring (`onConfirm` → `commandInstance.execute()`) is handled
+ *   internally; you only supply `onSuccess` / `onValidationFailure` / `onFailed`.
+ * - The dialog's `isBusy` state tracks the in-flight command without manual
+ *   `useState`.
+ * - Field error propagation from `CommandResult.validationResults` to the
+ *   form context is automatic.
+ *
+ * @typeParam TCommand - The command class (proxy generated from C# `[Command]`).
+ * @typeParam TResponse - The success payload type returned by the command's `Handle()` method on the backend.
  * @param props - {@link CommandDialogProps}.
  */
 const CommandDialogComponent = <TCommand extends object = object, TResponse = object>(props: CommandDialogProps<TCommand, TResponse>) => {
diff --git a/Source/CommandDialog/CommandStepper.tsx b/Source/CommandDialog/CommandStepper.tsx
index f11c3cf..8bbcc18 100644
--- a/Source/CommandDialog/CommandStepper.tsx
+++ b/Source/CommandDialog/CommandStepper.tsx
@@ -390,33 +390,63 @@ const CommandStepperWrapper = <TCommand extends object, TResponse = object>({
 };
 
 /**
- * A multi-step wizard backed by a single Cratis command — the embedded
- * counterpart of {@link StepperCommandDialog} that lives directly inside
- * a page rather than inside a modal dialog.
+ * A multi-step wizard backed by a single Cratis Arc command — the embedded,
+ * non-modal counterpart of {@link StepperCommandDialog}. Renders directly
+ * inside a page region (a panel, a route, a wizard view) rather than inside
+ * a modal dialog. Use this when the wizard *is* the page; use
+ * {@link StepperCommandDialog} when the same wizard should appear over the
+ * current page in a modal.
  *
- * Wraps PrimeReact's `Stepper` with a `CommandForm` and a built-in
- * previous / next / submit footer. Steps with field errors are visually
- * marked so the user can see which step needs attention without clicking
- * through every page.
+ * ## Mechanics
  *
- * Use this when a complex form fills a page region (a panel, a route);
- * use {@link StepperCommandDialog} when the same wizard should appear in
- * a modal dialog.
+ * - Wraps PrimeReact's `Stepper` inside an Arc `CommandForm` so each
+ *   `<StepperPanel>` becomes a logical grouping of fields that all bind to
+ *   the same single command.
+ * - Provides a built-in Previous / Next / Submit footer. The Submit button
+ *   only appears on the last step and only when the form passes its
+ *   validity gate.
+ * - Steps with field errors are visually marked (red step indicator) so
+ *   the user can see at a glance which step needs attention — useful in
+ *   wizards long enough that a missed-required-field on page 1 would
+ *   otherwise be hidden behind page 4.
+ * - On final Submit, the bound command runs through Arc's command pipeline.
+ *   Failure paths (`onValidationFailure` / `onFailed`) keep the wizard
+ *   open and re-surface field errors automatically.
+ *
+ * ## What `TCommand` is
+ *
+ * `TCommand` is the auto-generated TypeScript class produced by the Arc
+ * proxy generator from a C# `[Command]` record. The wizard's UI is a
+ * presentation grouping of one command's fields — every panel binds to
+ * properties on the same single command instance.
+ *
+ * ## What's unique vs. {@link StepperCommandDialog}
+ *
+ * Mechanically identical, but lives inline on a page instead of inside a
+ * modal Dialog. There is no `dialogPt` / `dialogUnstyled` prop because
+ * there is no outer dialog — `pt` / `ptOptions` / `unstyled` target the
+ * Stepper directly.
  *
  * ```tsx
- * <CommandStepper<RegisterAuthor> command={RegisterAuthor}
- *                                 onSuccess={onCreated}>
- *     <StepperPanel header="Basics">
- *         <InputTextField value={c => c.name} title="Name" />
- *     </StepperPanel>
- *     <StepperPanel header="Contact">
- *         <InputTextField value={c => c.email} title="Email" />
- *     </StepperPanel>
- * </CommandStepper>
+ * import { CommandStepper } from '@cratis/components/CommandStepper';
+ * import { StepperPanel } from 'primereact/stepperpanel';
+ * import { RegisterAuthor } from './RegisterAuthor';   // proxy from C#
+ *
+ * export const RegisterAuthorPage = () => (
+ *     <CommandStepper<RegisterAuthor> command={RegisterAuthor}
+ *                                     onSuccess={() => navigate('/authors')}>
+ *         <StepperPanel header="Basics">
+ *             <InputTextField value={c => c.name} title="Name" />
+ *         </StepperPanel>
+ *         <StepperPanel header="Contact">
+ *             <InputTextField value={c => c.email} title="Email" />
+ *         </StepperPanel>
+ *     </CommandStepper>
+ * );
  * ```
  *
- * @typeParam TCommand - The command record type. Defaults to `object`.
- * @typeParam TResponse - The success payload type. Defaults to `object`.
+ * @typeParam TCommand - The command class (proxy generated from C# `[Command]`).
+ * @typeParam TResponse - The success payload type returned by the command's `Handle()` method on the backend.
  * @param props - {@link CommandStepperProps}.
  */
 export const CommandStepper = <TCommand extends object = object, TResponse = object>(
diff --git a/Source/CommandDialog/StepperCommandDialog.tsx b/Source/CommandDialog/StepperCommandDialog.tsx
index 6250113..af59e74 100644
--- a/Source/CommandDialog/StepperCommandDialog.tsx
+++ b/Source/CommandDialog/StepperCommandDialog.tsx
@@ -292,30 +292,89 @@ const StepperCommandDialogWrapper = <TCommand extends object, TResponse = object
 };
 
 /**
- * A multi-step wizard dialog backed by a single Cratis command. Wraps PrimeReact's
- * `Stepper` inside a Cratis `Dialog`, tracks per-step visit state, surfaces
- * inline error indicators on steps with invalid fields, and executes the bound
- * command when the user submits the last step.
+ * A multi-step wizard dialog backed by a single Cratis Arc command. Wraps
+ * PrimeReact's `Stepper` inside a Cratis {@link Dialog}, tracks per-step
+ * visit state, surfaces inline error indicators on steps with invalid
+ * fields, and executes the bound command when the user submits the last
+ * step. Use it when one command has enough fields that they should be
+ * broken into named stages; for single-stage commands, use
+ * {@link CommandDialog}.
  *
- * Use it when one command needs to be split into named stages that the user can
- * navigate forward and backward through. For single-stage commands, use
- * {@link CommandDialog} instead.
+ * ## What `TCommand` is
+ *
+ * `TCommand` is the auto-generated TypeScript class produced by the Arc
+ * proxy generator from a C# `[Command]` record. The wizard fields all bind
+ * to properties on this single command — the multi-step UI is purely a
+ * presentation grouping of one command's fields, not multiple commands.
+ *
+ * ## What's unique vs. {@link CommandDialog}
+ *
+ * - **Progressive disclosure**: fields are grouped into `<StepperPanel>`
+ *   children and the user advances through them with explicit Previous /
+ *   Next buttons before reaching Submit on the last step.
+ * - **Per-step error indicators**: the step number circle paints red when
+ *   any field inside that step has a validation error and the step has
+ *   been visited, so a long wizard doesn't hide a single-field error on
+ *   page 1 behind page 4. The CratisStepper handles this by reading
+ *   `getFieldError` from the form context and inspecting which fields
+ *   belong to which step.
+ * - **Visited tracking**: only visited steps show error indicators; an
+ *   un-visited step is never marked red just because its fields are blank.
+ * - **Linear mode (default)**: the user must complete a step before
+ *   advancing. Set `linear={false}` to allow free navigation.
+ * - **Submit only fires on the last step**: the command runs through Arc's
+ *   command pipeline only when the user clicks the final Submit button —
+ *   not on every Next click. Failure paths
+ *   (`onValidationFailure` / `onFailed`) work exactly like
+ *   {@link CommandDialog}: dialog stays open, errors surface back to the
+ *   form.
+ *
+ * ## Typed dialog host usage
+ *
+ * Same pattern as {@link CommandDialog} — combine with
+ * `useDialog<CommandResult<TResponse>>()` from `@cratis/arc.react/dialogs`
+ * to get a fully-typed result at the call site:
  *
  * ```tsx
- * <StepperCommandDialog<RegisterOrder> command={RegisterOrder}
- *                                       title="New order"
- *                                       onSuccess={onCreated}>
- *     <StepperPanel header="Customer">
- *         <InputTextField value={c => c.customerName} title="Name" />
- *     </StepperPanel>
- *     <StepperPanel header="Items">
- *         <ChipsField value={c => c.items} title="Items" />
- *     </StepperPanel>
- * </StepperCommandDialog>
+ * import { useDialog, DialogResult } from '@cratis/arc.react/dialogs';
+ * import { StepperCommandDialog } from '@cratis/components/CommandDialog';
+ * import { StepperPanel } from 'primereact/stepperpanel';
+ * import { RegisterOrder } from './RegisterOrder';   // proxy from C#
+ *
+ * const RegisterOrderDialog = () => {
+ *     const { closeDialog } = useDialogContext<CommandResult<RegisterOrderResponse>>();
+ *     return (
+ *         <StepperCommandDialog<RegisterOrder, RegisterOrderResponse>
+ *             command={RegisterOrder}
+ *             title="New order"
+ *             onSuccess={() => closeDialog(DialogResult.Ok)}
+ *             onCancel={() => closeDialog(DialogResult.Cancelled)}>
+ *             <StepperPanel header="Customer">
+ *                 <InputTextField value={c => c.customerName} title="Name" />
+ *                 <InputTextField value={c => c.email} title="Email" />
+ *             </StepperPanel>
+ *             <StepperPanel header="Items">
+ *                 <ChipsField value={c => c.items} title="Items" />
+ *                 <NumberField value={c => c.quantity} title="Quantity" min={1} />
+ *             </StepperPanel>
+ *             <StepperPanel header="Confirm">
+ *                 <CheckboxField value={c => c.confirmed} label="I confirm the order" />
+ *             </StepperPanel>
+ *         </StepperCommandDialog>
+ *     );
+ * };
  * ```
  *
- * @typeParam TCommand - The command record type. Defaults to `object`.
- * @typeParam TResponse - The success payload type. Defaults to `object`.
+ * ## Styling
+ *
+ * The inherited `pt` / `ptOptions` / `unstyled` props target the inner
+ * **Stepper**. Use `dialogPt` / `dialogPtOptions` / `dialogUnstyled` /
+ * `dialogClassName` to style the outer **Dialog** independently. See the
+ * [pass-through cheat sheet](../../Documentation/Styling/pass-through.md)
+ * for the slot reference.
+ *
+ * @typeParam TCommand - The command class (proxy generated from C# `[Command]`).
+ * @typeParam TResponse - The success payload type returned by the command's `Handle()` method on the backend.
  * @param props - {@link StepperCommandDialogProps}.
  */
 const StepperCommandDialogComponent = <TCommand extends object = object, TResponse = object>(
diff --git a/Source/CommandForm/fields/CalendarField.tsx b/Source/CommandForm/fields/CalendarField.tsx
index baa6a58..8275345 100644
--- a/Source/CommandForm/fields/CalendarField.tsx
+++ b/Source/CommandForm/fields/CalendarField.tsx
@@ -44,8 +44,10 @@ interface CalendarFieldComponentProps extends WrappedFieldProps<Date | null> {
 }
 
 /**
- * A date (or date-time) picker field for use inside a `CommandForm`. Binds to
- * a `Date | null` property on the command.
+ * A date (or date-time) picker field bound to a `Date | null` property on a
+ * Cratis Arc command. Set `showTime` to add a time selector alongside the
+ * date. See {@link InputTextField} for the full `value={c => c.prop}`
+ * binding model.
  *
  * ```tsx
  * <CalendarField value={c => c.dueDate}
diff --git a/Source/CommandForm/fields/CheckboxField.tsx b/Source/CommandForm/fields/CheckboxField.tsx
index efd53c7..d1c7010 100644
--- a/Source/CommandForm/fields/CheckboxField.tsx
+++ b/Source/CommandForm/fields/CheckboxField.tsx
@@ -26,8 +26,9 @@ interface CheckboxFieldComponentProps extends WrappedFieldProps<boolean> {
 }
 
 /**
- * A single boolean checkbox field for use inside a `CommandForm`. Binds to
- * a boolean property on the command.
+ * A single boolean checkbox field bound to a `boolean` property on a Cratis
+ * Arc command. See {@link InputTextField} for the full `value={c => c.prop}`
+ * binding model.
  *
  * ```tsx
  * <CheckboxField value={c => c.acceptedTerms} label="I agree to the terms" />
diff --git a/Source/CommandForm/fields/ChipsField.tsx b/Source/CommandForm/fields/ChipsField.tsx
index 461fd79..6ba3be4 100644
--- a/Source/CommandForm/fields/ChipsField.tsx
+++ b/Source/CommandForm/fields/ChipsField.tsx
@@ -38,8 +38,10 @@ interface ChipsFieldComponentProps extends WrappedFieldProps<string[]> {
 }
 
 /**
- * A tag/chip input field for use inside a `CommandForm`. Binds to a
- * `string[]` property on the command — each entered token becomes a chip.
+ * A tag/chip input field bound to a `string[]` property on a Cratis Arc
+ * command. Each entered token becomes a chip; `separator` splits pasted
+ * input into multiple chips at once. See {@link InputTextField} for the
+ * full `value={c => c.prop}` binding model.
  *
  * ```tsx
  * <ChipsField value={c => c.tags} title="Tags" separator="," />
diff --git a/Source/CommandForm/fields/ColorPickerField.tsx b/Source/CommandForm/fields/ColorPickerField.tsx
index 91ab24b..e5fd63b 100644
--- a/Source/CommandForm/fields/ColorPickerField.tsx
+++ b/Source/CommandForm/fields/ColorPickerField.tsx
@@ -29,8 +29,10 @@ interface ColorPickerFieldComponentProps extends WrappedFieldProps<string> {
 }
 
 /**
- * A color picker field for use inside a `CommandForm`. Binds to a string
- * property holding a hex color value (e.g. `"60a5fa"`).
+ * A color picker field bound to a `string` property on a Cratis Arc command,
+ * holding a hex color value without the leading `#` (e.g. `"60a5fa"`). Set
+ * `inline` to render the picker inline rather than as a popover. See
+ * {@link InputTextField} for the full `value={c => c.prop}` binding model.
  *
  * ```tsx
  * <ColorPickerField value={c => c.accentColor} title="Accent" inline />
diff --git a/Source/CommandForm/fields/DropdownField.tsx b/Source/CommandForm/fields/DropdownField.tsx
index 50c5258..41aa19c 100644
--- a/Source/CommandForm/fields/DropdownField.tsx
+++ b/Source/CommandForm/fields/DropdownField.tsx
@@ -35,8 +35,11 @@ interface DropdownFieldComponentProps extends WrappedFieldProps<string | number>
 }
 
 /**
- * A single-select dropdown field for use inside a `CommandForm`. Binds to
- * a string or numeric property on the command.
+ * A single-select dropdown field bound to a `string` or `number` property
+ * on a Cratis Arc command. The `options` array supplies the choices;
+ * `optionValue` and `optionLabel` declare which property on each option
+ * holds the bound value and which one holds the visible label. See
+ * {@link InputTextField} for the full `value={c => c.prop}` binding model.
  *
  * ```tsx
  * <DropdownField value={c => c.country}
diff --git a/Source/CommandForm/fields/InputTextField.tsx b/Source/CommandForm/fields/InputTextField.tsx
index 49cccc5..7686cae 100644
--- a/Source/CommandForm/fields/InputTextField.tsx
+++ b/Source/CommandForm/fields/InputTextField.tsx
@@ -31,13 +31,37 @@ interface InputTextComponentProps extends WrappedFieldProps<string> {
 }
 
 /**
- * A single-line text field for use inside a `CommandForm`. Binds to a string
- * property on the command via the `value` accessor (`value={c => c.name}`)
- * and forwards user input through the form context.
+ * A single-line text field for use inside a Cratis Arc `CommandForm` (or any
+ * of its dialog-hosted variants like {@link CommandDialog},
+ * {@link StepperCommandDialog}, {@link CommandStepper}).
  *
- * Supports all the input types PrimeReact's `InputText` does (`text`, `email`,
- * `password`, `url`, `tel`, `date`, etc.) and forwards `pt` / `ptOptions` /
- * `unstyled` for full restyling control.
+ * ## How it binds to the command
+ *
+ * The `value` prop is an accessor function — `value={c => c.name}` — where
+ * `c` is the typed command instance. The `asCommandFormField` HOC from
+ * `@cratis/arc.react/commands` reads the accessor, subscribes the field to
+ * that property on the form context, and threads validation state back to
+ * the input. You never read or write the command instance directly; the
+ * field handles it.
+ *
+ * The accessor pattern means the *binding* is fully typechecked end-to-end
+ * — if the command's `name` property is a `string`, the field's value type
+ * is inferred as `string` and TypeScript catches any mismatch.
+ *
+ * ## What's unique vs. PrimeReact's `InputText`
+ *
+ * - Bound to a single command property, no manual `onChange`/`setState`.
+ * - Validation state (`invalid` border) is driven automatically from the
+ *   `CommandResult.validationResults` returned by the backend's `Handle()`.
+ * - All HTML input `type`s PrimeReact supports (`text`, `email`,
+ *   `password`, `url`, `tel`, `date`, `datetime-local`, `time`, `color`,
+ *   `search`) work the same way.
+ *
+ * ## Styling
+ *
+ * Forwards `pt` / `ptOptions` / `unstyled` / `className` to the underlying
+ * `InputText`. The default `w-full` class is preserved when consumer
+ * `className` is supplied. See [pass-through cheat sheet](../../../Documentation/Styling/pass-through.md).
  *
  * ```tsx
  * <InputTextField value={c => c.email}
diff --git a/Source/CommandForm/fields/MultiSelectField.tsx b/Source/CommandForm/fields/MultiSelectField.tsx
index 54b5c93..60e69f5 100644
--- a/Source/CommandForm/fields/MultiSelectField.tsx
+++ b/Source/CommandForm/fields/MultiSelectField.tsx
@@ -47,9 +47,10 @@ interface MultiSelectFieldComponentProps extends WrappedFieldProps<Array<string
 }
 
 /**
- * A multi-select dropdown field for use inside a `CommandForm`. Binds to an
- * array of strings or numbers on the command. Use for "pick any subset of
- * these" controls with optional filtering inside the panel.
+ * A multi-select dropdown field bound to an `Array<string | number>`
+ * property on a Cratis Arc command. Use for "pick any subset of these"
+ * controls with optional in-panel filtering. See {@link InputTextField}
+ * for the full `value={c => c.prop}` binding model.
  *
  * ```tsx
  * <MultiSelectField value={c => c.tagIds}
diff --git a/Source/CommandForm/fields/NumberField.tsx b/Source/CommandForm/fields/NumberField.tsx
index 0f2427d..72f3fce 100644
--- a/Source/CommandForm/fields/NumberField.tsx
+++ b/Source/CommandForm/fields/NumberField.tsx
@@ -35,9 +35,10 @@ interface NumberFieldComponentProps extends WrappedFieldProps<number> {
 }
 
 /**
- * A numeric input field for use inside a `CommandForm`. Binds to a number
- * property on the command. Defaults to integer mode without grouping; pass
- * a `step` to enable spinner increments.
+ * A numeric input field bound to a `number` property on a Cratis Arc
+ * command. Defaults to integer mode without thousands grouping; pass `step`
+ * to enable spinner increments and `min` / `max` to clamp the range. See
+ * {@link InputTextField} for the full `value={c => c.prop}` binding model.
  *
  * ```tsx
  * <NumberField value={c => c.quantity} title="Quantity" min={0} step={1} />
diff --git a/Source/CommandForm/fields/RadioButtonField.tsx b/Source/CommandForm/fields/RadioButtonField.tsx
index 334add7..261a256 100644
--- a/Source/CommandForm/fields/RadioButtonField.tsx
+++ b/Source/CommandForm/fields/RadioButtonField.tsx
@@ -32,11 +32,14 @@ interface RadioButtonFieldComponentProps extends WrappedFieldProps<string | numb
 }
 
 /**
- * A single radio button bound to a command property. Multiple
- * {@link RadioButtonField} instances with the same `value` accessor and
- * distinct `buttonValue` props together form a mutually-exclusive group.
- * For most cases prefer {@link RadioGroupField} which manages the group as
- * a single field.
+ * A single radio button bound to a `string` or `number` property on a
+ * Cratis Arc command. Multiple {@link RadioButtonField} instances with the
+ * same `value` accessor and distinct `buttonValue` props together form a
+ * mutually-exclusive group — useful when the radios need to be laid out
+ * non-contiguously in the form. For the common case where the radios sit
+ * in one place, prefer {@link RadioGroupField} which manages the group as
+ * a single field. See {@link InputTextField} for the full
+ * `value={c => c.prop}` binding model.
  */
 export const RadioButtonField = asCommandFormField<RadioButtonFieldComponentProps>(
     (props) => (
diff --git a/Source/CommandForm/fields/RadioGroupField.tsx b/Source/CommandForm/fields/RadioGroupField.tsx
index 1a8481f..f10f3e7 100644
--- a/Source/CommandForm/fields/RadioGroupField.tsx
+++ b/Source/CommandForm/fields/RadioGroupField.tsx
@@ -31,9 +31,11 @@ interface RadioGroupFieldComponentProps extends WrappedFieldProps<string | numbe
 }
 
 /**
- * A radio-button group field for use inside a `CommandForm`. Binds to a
- * string or numeric property on the command. Use for small mutually-exclusive
- * choice sets; for larger sets, prefer {@link DropdownField}.
+ * A radio-button group field bound to a `string` or `number` property on a
+ * Cratis Arc command. Use for small mutually-exclusive choice sets where
+ * all options should be visible at once; for larger sets, prefer
+ * {@link DropdownField}. See {@link InputTextField} for the full
+ * `value={c => c.prop}` binding model.
  *
  * ```tsx
  * <RadioGroupField value={c => c.priority}
diff --git a/Source/CommandForm/fields/SliderField.tsx b/Source/CommandForm/fields/SliderField.tsx
index e53b527..cb27a47 100644
--- a/Source/CommandForm/fields/SliderField.tsx
+++ b/Source/CommandForm/fields/SliderField.tsx
@@ -32,8 +32,9 @@ interface SliderFieldComponentProps extends WrappedFieldProps<number> {
 }
 
 /**
- * A horizontal slider field for use inside a `CommandForm`. Binds to a number
- * property and shows the current value below the track.
+ * A horizontal slider field bound to a `number` property on a Cratis Arc
+ * command. The current value is rendered below the track for feedback. See
+ * {@link InputTextField} for the full `value={c => c.prop}` binding model.
  *
  * ```tsx
  * <SliderField value={c => c.volume} title="Volume" min={0} max={100} />
diff --git a/Source/CommandForm/fields/TextAreaField.tsx b/Source/CommandForm/fields/TextAreaField.tsx
index 3f9080f..c6168da 100644
--- a/Source/CommandForm/fields/TextAreaField.tsx
+++ b/Source/CommandForm/fields/TextAreaField.tsx
@@ -32,9 +32,11 @@ interface TextAreaFieldComponentProps extends WrappedFieldProps<string> {
 }
 
 /**
- * A multi-line text field for use inside a `CommandForm`. Binds to a string
- * property on the command via the `value` accessor. Use for descriptions,
- * notes, or any free-form text longer than a single line.
+ * A multi-line text field bound to a `string` property on a Cratis Arc
+ * command. Use for descriptions, notes, or any free-form text longer than
+ * a single line. See {@link InputTextField} for the full
+ * `value={c => c.prop}` binding model that every field in this folder
+ * follows.
  *
  * ```tsx
  * <TextAreaField value={c => c.description} title="Description" rows={4} />
diff --git a/Source/DataPage/DataPage.tsx b/Source/DataPage/DataPage.tsx
index 91f861c..6310427 100644
--- a/Source/DataPage/DataPage.tsx
+++ b/Source/DataPage/DataPage.tsx
@@ -275,19 +275,65 @@ export interface DataPageProps<TQuery extends IQueryFor<TDataType> | IObservable
 }
 
 /**
- * A page primitive that combines an action menubar, a query-backed data table,
- * and an optional details pane into one layout. Wraps Allotment for resizable
- * split-pane behavior when a details component is supplied.
+ * A page primitive that combines an action menubar, a query-backed data
+ * table, and an optional details pane into one layout. Designed as the
+ * default rendering for "list view" pages in an Arc app.
  *
- * Composition is declarative — use the static children:
+ * ## What `TQuery` is
+ *
+ * `TQuery` is the auto-generated TypeScript class produced by the Arc proxy
+ * generator from a C# read model query. Two flavors are accepted and
+ * **selected automatically at runtime** based on the class hierarchy:
+ *
+ * - **`IQueryFor<TDataType, TArguments>`** — a snapshot query. Re-fetched
+ *   when `queryArguments` change or when the page is mounted. Rendered
+ *   through {@link DataTableForQuery} internally.
+ * - **`IObservableQueryFor<TDataType, TArguments>`** — a real-time
+ *   subscription. Connects to the backend over WebSocket and re-renders
+ *   automatically whenever the underlying read model changes server-side.
+ *   Rendered through {@link DataTableForObservableQuery} internally.
+ *
+ * You don't pick which inner table to use — `DataPage` inspects the
+ * prototype chain (`context.query.prototype instanceof QueryFor`) and
+ * mounts the correct one.
+ *
+ * ## Declarative composition
+ *
+ * Three children build up the page:
+ *
+ * - **`<DataPage.MenuItems>`** wraps `<DataPage.MenuItem>` elements that
+ *   become the action `Menubar` at the top. Each item declares its `icon`,
+ *   `label`, and `command` (an `onClick` handler). Items can be marked
+ *   `disableOnUnselected` so they automatically grey out until the user
+ *   picks a row — useful for Edit / Delete actions that need a target.
+ *
+ * - **`<DataPage.Columns>`** wraps PrimeReact `<Column>` elements that
+ *   describe the visible columns. The columns themselves are
+ *   PrimeReact's — anything supported by their `DataTable` `<Column>` is
+ *   supported here (sorting, filtering, custom body templates, …).
+ *
+ * - **`detailsComponent`** (optional) is a React component rendered in a
+ *   right-hand pane via Allotment when a row is selected. It receives the
+ *   selected item as `item` and an `onRefresh` callback the parent can
+ *   invoke to ask the page to refetch.
+ *
+ * ## Selection lifecycle
+ *
+ * `DataPage` keeps the current selection in local state and threads it to
+ * the inner table, the menubar (`disableOnUnselected` items follow it),
+ * and the optional details pane. The `onSelectionChange` prop is invoked
+ * after every change if the consumer also needs to react to it.
  *
  * ```tsx
  * <DataPage<AllAuthors, Author, never>
- *     title="Authors" query={AllAuthors}
+ *     title="Authors"
+ *     query={AllAuthors}                          // proxy from C#
  *     detailsComponent={AuthorDetails}>
  *     <DataPage.MenuItems>
- *         <DataPage.MenuItem icon={FaPlus} label="Add"     command={onAdd} />
- *         <DataPage.MenuItem icon={FaPencil} label="Edit"  command={onEdit}
+ *         <DataPage.MenuItem icon={FaPlus}   label="Add"    command={onAdd} />
+ *         <DataPage.MenuItem icon={FaPencil} label="Edit"   command={onEdit}
+ *                            disableOnUnselected />
+ *         <DataPage.MenuItem icon={FaTrash}  label="Delete" command={onDelete}
  *                            disableOnUnselected />
  *     </DataPage.MenuItems>
  *     <DataPage.Columns>
@@ -297,10 +343,15 @@ export interface DataPageProps<TQuery extends IQueryFor<TDataType> | IObservable
  * </DataPage>
  * ```
  *
- * Both `IQueryFor` (snapshot) and `IObservableQueryFor` (real-time) queries are
- * supported automatically — the inner table type is selected at runtime.
+ * ## Styling
+ *
+ * The inner DataTable and Menubar each have their own per-slot props:
+ * `tablePt` / `tableUnstyled` / `tableClassName` for the table;
+ * `menubarPt` / `menubarUnstyled` / `menubarClassName` for the action
+ * menubar. See the [pass-through cheat sheet](../../Documentation/Styling/pass-through.md)
+ * for the full slot reference.
  *
- * @typeParam TQuery - The query class.
+ * @typeParam TQuery - The query class (proxy generated from a C# read model query).
  * @typeParam TDataType - The row type returned by the query.
  * @typeParam TArguments - The query's argument object type.
  * @param props - {@link DataPageProps}.
diff --git a/Source/DataTables/DataTableForObservableQuery.tsx b/Source/DataTables/DataTableForObservableQuery.tsx
index a9baae3..5a9008d 100644
--- a/Source/DataTables/DataTableForObservableQuery.tsx
+++ b/Source/DataTables/DataTableForObservableQuery.tsx
@@ -93,19 +93,65 @@ export interface DataTableForObservableQueryProps<TQuery extends IObservableQuer
 const paging = new Paging(0, 20);
 
 /**
- * A paged data table bound to a Cratis observable query (`IObservableQueryFor`).
- * Subscribes via `useObservableQueryWithPaging`, so the table re-renders
- * automatically as the underlying read model changes server-side. The table
- * height is observed and matched to its container to keep scrollable content
- * sized correctly inside flex layouts.
+ * A paged data table bound to a Cratis Arc **observable** query
+ * (`IObservableQueryFor<TDataType, TArguments>`). Subscribes via
+ * `useObservableQueryWithPaging` from `@cratis/arc.react/queries`, which
+ * opens a WebSocket connection to the backend and re-renders the table
+ * automatically whenever the underlying read model changes server-side.
  *
- * Use {@link DataTableForQuery} instead for snapshot queries that don't need
- * live updates. For a higher-level page layout, use {@link DataPage}.
+ * ## What `TQuery` is
  *
- * Children should be PrimeReact `<Column>` elements describing the visible
- * columns.
+ * `TQuery` is the auto-generated TypeScript class produced by the Arc proxy
+ * generator from a C# read model's static observable query method (one
+ * that returns `ISubject<TDataType>` on the backend). The proxy hooks the
+ * WebSocket subscription up; you only deal with the resulting React data.
  *
- * @typeParam TQuery - The observable query class.
+ * ## What's unique
+ *
+ * - **Real-time updates**: server-side projection writes flow into the
+ *   table within the same render cycle, with no manual polling or refresh
+ *   button. The connection re-subscribes automatically when
+ *   `queryArguments` change.
+ * - **Resize-aware scrollable height**: the wrapper observes its container
+ *   via `ResizeObserver` and adjusts the inner DataTable height to fit,
+ *   so the table behaves correctly inside flex layouts (it never overflows
+ *   beyond its parent or shrinks below 200px).
+ * - **Lazy paging + optional client filtering**: same modes as
+ *   {@link DataTableForQuery}, but the page is re-issued through the
+ *   observable subscription when the user pages.
+ *
+ * Use {@link DataTableForQuery} for snapshot queries that don't need live
+ * updates. Use {@link DataPage} for a higher-level layout that combines
+ * this table with a menubar, selection, and a details pane.
+ *
+ * ## Children
+ *
+ * Children are PrimeReact `<Column>` elements — same as
+ * {@link DataTableForQuery}.
+ *
+ * ```tsx
+ * import { DataTableForObservableQuery } from '@cratis/components/DataTables';
+ * import { Column } from 'primereact/column';
+ * import { ActiveSessions } from './ActiveSessions';   // proxy from C#
+ *
+ * <DataTableForObservableQuery
+ *     query={ActiveSessions}
+ *     emptyMessage="No active sessions">
+ *     <Column field="userName"  header="User" />
+ *     <Column field="startedAt" header="Started" />
+ * </DataTableForObservableQuery>
+ * ```
+ *
+ * Rows appear and disappear in this table as users log in / log out
+ * server-side — no manual refresh required.
+ *
+ * ## Styling
+ *
+ * Identical to {@link DataTableForQuery}: `pt` / `ptOptions` / `unstyled` /
+ * `className` target the inner DataTable; `paginatorPt` and friends target
+ * the inner Paginator. See [pass-through cheat sheet](../../Documentation/Styling/pass-through.md).
+ *
+ * @typeParam TQuery - The observable query class (proxy generated from C# `IObservableQueryFor`).
  * @typeParam TDataType - The row type returned by the query.
  * @typeParam TArguments - The query's argument object type.
  * @param props - {@link DataTableForObservableQueryProps}.
diff --git a/Source/DataTables/DataTableForQuery.tsx b/Source/DataTables/DataTableForQuery.tsx
index 3cbdfce..1ff309b 100644
--- a/Source/DataTables/DataTableForQuery.tsx
+++ b/Source/DataTables/DataTableForQuery.tsx
@@ -93,18 +93,62 @@ export interface DataTableForQueryProps<TQuery extends IQueryFor<TDataType, TArg
 const paging = new Paging(0, 20);
 
 /**
- * A paged data table bound to a snapshot Cratis query (`IQueryFor`). Issues
- * the query through `useQueryWithPaging`, renders results in a PrimeReact
- * `DataTable`, and shows a `Paginator` when the result set exceeds one page.
+ * A paged data table bound to a snapshot Cratis Arc query
+ * (`IQueryFor<TDataType, TArguments>`). Subscribes via
+ * `useQueryWithPaging` from `@cratis/arc.react/queries`, renders the result
+ * page in a PrimeReact `DataTable`, and shows a `Paginator` when the result
+ * set exceeds one page.
  *
- * For queries that should update in real time as the read model changes, use
- * {@link DataTableForObservableQuery} instead. For a higher-level page layout
- * that combines this table with a menubar and details pane, use {@link DataPage}.
+ * ## What `TQuery` is
  *
- * Children should be PrimeReact `<Column>` elements describing the visible
- * columns.
+ * `TQuery` is the auto-generated TypeScript class produced by the Arc proxy
+ * generator from a C# read model's static query method. `dotnet build`
+ * writes a `.ts` file per query with the right return type and a `use()`
+ * hook; importing the class is all the connection-to-the-backend you need.
  *
- * @typeParam TQuery - The query class.
+ * ## What's unique
+ *
+ * - **Lazy paging**: the table runs in PrimeReact's `lazy` mode by default
+ *   so the server returns one page at a time. The Paginator's
+ *   `onPageChange` calls back into the Arc hook to fetch the next page.
+ * - **Client-side filtering toggle**: pass `clientFiltering` to keep the
+ *   page-fetched rows in the browser and filter locally — useful for
+ *   small result sets where you want PrimeReact's filter UI but don't want
+ *   to round-trip every keystroke.
+ * - **Default filter state**: `defaultFilters` seeds the table's filter
+ *   meta on first render so saved or URL-encoded filter state can be
+ *   rehydrated.
+ *
+ * Use {@link DataTableForObservableQuery} for queries that should update in
+ * real time as the underlying read model changes server-side. Use
+ * {@link DataPage} for a higher-level layout that combines this table with
+ * a menubar, selection, and a details pane.
+ *
+ * ## Children
+ *
+ * Children are PrimeReact `<Column>` elements describing the visible
+ * columns — sorting, filtering, custom body templates, everything
+ * PrimeReact's `<Column>` supports.
+ *
+ * ```tsx
+ * import { DataTableForQuery } from '@cratis/components/DataTables';
+ * import { Column } from 'primereact/column';
+ * import { AllAuthors } from './AllAuthors';     // proxy from C#
+ *
+ * <DataTableForQuery query={AllAuthors} emptyMessage="No authors">
+ *     <Column field="name"  header="Name" sortable />
+ *     <Column field="email" header="Email" />
+ * </DataTableForQuery>
+ * ```
+ *
+ * ## Styling
+ *
+ * Forward `pt` / `ptOptions` / `unstyled` / `className` to the underlying
+ * PrimeReact DataTable. Use `paginatorPt` / `paginatorPtOptions` /
+ * `paginatorUnstyled` to style the inner Paginator independently. See
+ * [pass-through cheat sheet](../../Documentation/Styling/pass-through.md).
+ *
+ * @typeParam TQuery - The query class (proxy generated from C# `IQueryFor`).
  * @typeParam TDataType - The row type returned by the query.
  * @typeParam TArguments - The query's argument object type.
  * @param props - {@link DataTableForQueryProps}.
diff --git a/Source/Dialogs/BusyIndicatorDialog.tsx b/Source/Dialogs/BusyIndicatorDialog.tsx
index 96c1185..d6b052e 100644
--- a/Source/Dialogs/BusyIndicatorDialog.tsx
+++ b/Source/Dialogs/BusyIndicatorDialog.tsx
@@ -6,20 +6,51 @@ import { ProgressSpinner } from 'primereact/progressspinner';
 import { Dialog } from './Dialog';
 
 /**
- * Modal "busy" dialog used by the `@cratis/arc.react` dialog host when a
+ * Modal "busy" dialog used by the `@cratis/arc.react` dialog host whenever a
  * long-running operation needs to block user interaction. Renders a spinner
- * and a message, with no confirm/cancel buttons.
+ * and a message, with no confirm/cancel/X buttons — the dialog dismisses
+ * itself when the host removes it.
  *
- * The component is consumed by the dialog host machinery — applications do
- * not instantiate it directly. To trigger one, call the host's
- * `showBusyIndicator(...)` helper, which internally constructs a
- * {@link BusyIndicatorDialogRequest} and renders this component.
+ * ## How to use it
  *
- * Styling is controlled globally via the `pt` / `unstyled` settings on
- * `CratisComponentsProvider`. Per-instance pass-through is not exposed
- * because the request type lives in `@cratis/arc.react`.
+ * **You do not instantiate this component directly.** It's rendered by the
+ * dialog host machinery in response to a request. Trigger one from anywhere
+ * in your tree by calling the host's `showBusyIndicator` helper:
  *
- * @param props - The request from the dialog host, including `title` and `message`.
+ * ```tsx
+ * import { useDialogs } from '@cratis/arc.react/dialogs';
+ *
+ * const Save = () => {
+ *     const { showBusyIndicator, hideBusyIndicator } = useDialogs();
+ *
+ *     const onSave = async () => {
+ *         showBusyIndicator({ title: 'Saving', message: 'Persisting your changes…' });
+ *         try {
+ *             await someLongRunningCommand.execute();
+ *         } finally {
+ *             hideBusyIndicator();
+ *         }
+ *     };
+ *
+ *     return <Button label="Save" onClick={onSave} />;
+ * };
+ * ```
+ *
+ * The host renders the BusyIndicatorDialog in response, threading the
+ * `title` / `message` from your request through to the rendered modal.
+ *
+ * ## What's unique
+ *
+ * - **No interactive buttons.** A busy indicator is a wait-state, not a
+ *   confirmation prompt. The dialog has no Ok / Cancel / X — only the host
+ *   can dismiss it.
+ * - **No per-instance pass-through.** The request type
+ *   ({@link BusyIndicatorDialogRequest}) is owned by `@cratis/arc.react`, so
+ *   `pt` / `unstyled` are not exposed on a per-call basis. Restyle the
+ *   busy dialog (and every dialog) via the global `pt` preset on
+ *   `CratisComponentsProvider`.
+ *
+ * @param props - The request from the dialog host, containing `title` and `message`.
  */
 export const BusyIndicatorDialog = (props: BusyIndicatorDialogRequest) => {
     return (
diff --git a/Source/Dialogs/Dialog.tsx b/Source/Dialogs/Dialog.tsx
index 633312e..8874911 100644
--- a/Source/Dialogs/Dialog.tsx
+++ b/Source/Dialogs/Dialog.tsx
@@ -125,28 +125,75 @@ export interface DialogProps {
 }
 
 /**
- * Cratis wrapper around PrimeReact's `Dialog` that provides:
+ * Cratis wrapper around PrimeReact's `Dialog` that adds the surface every Arc
+ * app needs on top of PrimeReact's bare modal:
  *
- * - A typed footer-button enum (`DialogButtons.Ok` / `OkCancel` / `YesNo` /
- *   `YesNoCancel`) with localizable labels.
- * - A confirm/cancel callback contract (`onConfirm`, `onCancel`, `onClose`)
- *   where returning `false` keeps the dialog open — useful for surfacing
- *   inline command failures.
- * - A busy state that disables actions and shows a loading indicator on the
- *   confirm button while a command runs.
- * - Pass-through of `pt`, `ptOptions`, `unstyled`, and `className` to the
- *   underlying PrimeReact Dialog so consumers can fully restyle it.
- * - Automatic integration with `@cratis/arc.react`'s `DialogContext` when
- *   used inside a `<DialogHost>` — the dialog closes through the host on
- *   confirm/cancel without manual wiring.
+ * - **Typed footer-button enum** (`DialogButtons.Ok` / `OkCancel` / `YesNo` /
+ *   `YesNoCancel`) with localizable labels. Pass `null` for a footer-less
+ *   dialog with your own buttons, or a `ReactNode` to fully render the
+ *   footer yourself.
+ * - **Confirm/cancel callback contract** (`onConfirm`, `onCancel`, `onClose`)
+ *   where returning `false` (sync or via promise) keeps the dialog open.
+ *   This is the contract used to surface inline command failures: when a
+ *   command's `execute()` returns `IsSuccess: false`, the dialog stays open
+ *   and the form re-renders with field-level errors.
+ * - **Busy state** (`isBusy`) that disables every action and shows a loading
+ *   spinner on the confirm button. Command-executing wrappers
+ *   ({@link CommandDialog}, {@link StepperCommandDialog}) flip this
+ *   automatically while a command runs.
+ * - **Validity gate** (`isValid`) that disables the confirm button without
+ *   disabling the cancel button. Used by command-executing wrappers to
+ *   block submission while form validation fails.
+ *
+ * ## Arc dialog host integration
+ *
+ * When mounted inside a `<DialogHost>` from `@cratis/arc.react/dialogs`, the
+ * Dialog automatically discovers the host through `useDialogContext()` and
+ * closes through it on confirm/cancel — no manual `closeDialog` wiring at
+ * the call site. The typical pattern at the host's request site:
+ *
+ * ```tsx
+ * import { useDialog, DialogResult } from '@cratis/arc.react/dialogs';
+ *
+ * const [DeleteProjectDialog, showDeleteProjectDialog] = useDialog(DeleteProject);
+ *
+ * const onDeleteClick = async () => {
+ *     const [result] = await showDeleteProjectDialog();
+ *     if (result === DialogResult.Yes) {
+ *         // user confirmed
+ *     }
+ * };
+ * ```
+ *
+ * Inside the dialog component itself the close path goes through
+ * `useDialogContext()`:
  *
  * ```tsx
- * <Dialog title="Delete project?" buttons={DialogButtons.YesNo}
- *         onConfirm={() => deleteProject(id)}>
- *     This action cannot be undone.
- * </Dialog>
+ * import { Dialog, DialogButtons, DialogResult, useDialogContext } from '@cratis/arc.react/dialogs';
+ *
+ * export const DeleteProject = () => {
+ *     const { closeDialog } = useDialogContext();
+ *     return (
+ *         <Dialog title="Delete project?" buttons={DialogButtons.YesNo}
+ *                 onConfirm={() => closeDialog(DialogResult.Yes)}
+ *                 onCancel={() => closeDialog(DialogResult.No)}>
+ *             This action cannot be undone.
+ *         </Dialog>
+ *     );
+ * };
  * ```
  *
+ * The Dialog also works **outside** a host — the `useDialogContext()` call is
+ * wrapped in a try/catch so standalone use does not throw.
+ *
+ * ## Styling
+ *
+ * Pass `pt`, `ptOptions`, `unstyled`, or `className` to forward straight to
+ * the underlying PrimeReact Dialog. See the [Styling section](../../Documentation/Styling/index.md)
+ * for the three documented styling paths and the
+ * [pass-through cheat sheet](../../Documentation/Styling/pass-through.md)
+ * for available slots.
+ *
  * @param props - {@link DialogProps}.
  */
 

From 47d141370e36fe0087a16d32dad0f38e1a2a4d32 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Fri, 29 May 2026 18:15:04 +0200
Subject: [PATCH 17/23] Enhance documentation and improve component styling for
 better clarity and consistency

- Updated token references in cratis-tokens.md for accurate descriptions.
- Consolidated optional peer dependencies in getting-started.md and migration.md.
- Added EventsView component to pass-through documentation in pass-through.md.
- Improved CheckboxField, ColorPickerField, RadioButtonField, and RadioGroupField components for consistent styling.
- Adjusted Dialog story for proper flex layout.
- Updated README with clearer optional peer dependency information.
- Fixed NameCell component to handle validation errors correctly.
- Enhanced EventsView component to support additional props for styling and configuration.
- Excluded story files from package distribution in package.json.
---
 Documentation/Styling/cratis-tokens.md        | 18 +++++-----
 Documentation/Styling/getting-started.md      |  3 +-
 Documentation/Styling/pass-through.md         |  1 +
 Documentation/migration.md                    | 34 +++++++++++++------
 Source/CommandForm/fields/CheckboxField.tsx   |  2 +-
 .../CommandForm/fields/ColorPickerField.tsx   |  4 +++
 .../CommandForm/fields/RadioButtonField.tsx   |  2 +-
 Source/CommandForm/fields/RadioGroupField.tsx |  4 +--
 Source/Dialogs/Dialog.stories.tsx             |  2 +-
 Source/README.md                              | 15 ++++----
 Source/SchemaEditor/NameCell.tsx              |  3 +-
 Source/TimeMachine/EventsView.tsx             | 21 ++++++++++--
 Source/package.json                           | 11 +++---
 13 files changed, 78 insertions(+), 42 deletions(-)

diff --git a/Documentation/Styling/cratis-tokens.md b/Documentation/Styling/cratis-tokens.md
index fd603bf..4d2dd99 100644
--- a/Documentation/Styling/cratis-tokens.md
+++ b/Documentation/Styling/cratis-tokens.md
@@ -30,9 +30,9 @@ Each token defaults to the PrimeReact variable with the same name minus the `--c
 |---|---|
 | `--cratis-surface-0`      | Reserved for any Cratis-scoped surface that maps to PrimeReact's `--surface-0`. |
 | `--cratis-surface-100`    | `FormElement` addon background. |
-| `--cratis-surface-ground` | Reserved for any Cratis-scoped surface that maps to PrimeReact's `--surface-ground`. |
-| `--cratis-surface-section` | Reserved for any Cratis-scoped surface that maps to PrimeReact's `--surface-section`. |
-| `--cratis-surface-card`   | Backgrounds of the `ObjectContentEditor` snapshot card and similar panels. |
+| `--cratis-surface-ground` | `PivotViewer` canvas and panel backgrounds. |
+| `--cratis-surface-section` | `PivotViewer` panel section backgrounds. |
+| `--cratis-surface-card`   | Backgrounds of the `ObjectContentEditor` snapshot card and similar panels; `PivotViewer` card gradients. |
 | `--cratis-surface-overlay` | Overlay backgrounds inside Cratis wrappers. |
 | `--cratis-surface-hover`  | Hover state on row alternation inside `ObjectContentEditor`. |
 | `--cratis-surface-border` | `FormElement` addon border, `ObjectNavigationalBar` bottom border, `SchemaEditor` bottom border, table/paginator borders inside `DataTableForQuery` / `DataTableForObservableQuery`. |
@@ -50,10 +50,10 @@ Each token defaults to the PrimeReact variable with the same name minus the `--c
 |---|---|
 | `--cratis-primary-color`      | `ObjectContentEditor` navigation links into nested objects/arrays, default brand accent. |
 | `--cratis-primary-color-text` | Foreground used on top of `--cratis-primary-color` backgrounds (e.g. CommandStepper step number color). |
-| `--cratis-primary-300`        | Reserved for lighter brand variants. |
-| `--cratis-primary-400`        | Reserved for lighter brand variants. |
-| `--cratis-primary-500`        | Reserved for brand mid-tones. |
-| `--cratis-primary-600`        | Reserved for brand darker variants. |
+| `--cratis-primary-300`        | `PivotViewer` loading spinner ring. |
+| `--cratis-primary-400`        | `PivotViewer` loading spinner ring. |
+| `--cratis-primary-500`        | `PivotViewer` loading spinner ring and card gradient. |
+| `--cratis-primary-600`        | `PivotViewer` loading spinner ring. |
 
 ### Selection / highlight
 
@@ -80,8 +80,8 @@ Each token defaults to the PrimeReact variable with the same name minus the `--c
 
 | Token | Cratis surfaces tinted by it |
 |---|---|
-| `--cratis-focus-ring` | Reserved for Cratis-managed focus rings. |
-| `--cratis-maskbg`     | Reserved for any Cratis-managed modal mask. |
+| `--cratis-focus-ring` | Focus-ring box-shadow on interactive `PivotViewer` elements. |
+| `--cratis-maskbg`     | `PivotViewer` modal mask background. |
 
 ## Overriding tokens
 
diff --git a/Documentation/Styling/getting-started.md b/Documentation/Styling/getting-started.md
index 6e8a079..67e63ad 100644
--- a/Documentation/Styling/getting-started.md
+++ b/Documentation/Styling/getting-started.md
@@ -16,8 +16,7 @@ The optional peers (`pixi.js`, `framer-motion`, `allotment`) are only required w
 
 | Component | Optional peer |
 |---|---|
-| `PivotViewer` | `pixi.js` |
-| `CommandStepper`, animated panels | `framer-motion` |
+| `PivotViewer` | `pixi.js` (canvas) and `framer-motion` (animated panels) |
 | `DataPage` resizable layout | `allotment` |
 
 ## Wire the provider
diff --git a/Documentation/Styling/pass-through.md b/Documentation/Styling/pass-through.md
index d4c3bc5..75be415 100644
--- a/Documentation/Styling/pass-through.md
+++ b/Documentation/Styling/pass-through.md
@@ -24,6 +24,7 @@ The wrapper renders exactly one PrimeReact widget and forwards `pt` / `ptOptions
 | `ChipsField`        | `primereact/chips` Chips            | PrimeReact Chips `pt` |
 | `MultiSelectField`  | `primereact/multiselect` MultiSelect | PrimeReact MultiSelect `pt` |
 | `ColorPickerField`  | `primereact/colorpicker` ColorPicker | PrimeReact ColorPicker `pt` |
+| `EventsView`        | `primereact/timeline` Timeline      | PrimeReact Timeline `pt` |
 
 Example:
 
diff --git a/Documentation/migration.md b/Documentation/migration.md
index 66bf18b..e23f5d1 100644
--- a/Documentation/migration.md
+++ b/Documentation/migration.md
@@ -20,8 +20,7 @@ If you do these three things, your app will install and render correctly after t
 
    | Component | Optional peer |
    |---|---|
-   | `PivotViewer` | `pixi.js` |
-   | `CommandStepper` / animated panels | `framer-motion` |
+   | `PivotViewer` | `pixi.js` (canvas) and `framer-motion` (animated panels) |
    | `DataPage` resizable layout | `allotment` |
 
 3. **Skim the [Visual changes](#visual-changes) section below** to spot anywhere the new rendering would surprise you.
@@ -50,7 +49,7 @@ This change avoids the duplicate-installation pitfall: consumers who already had
 }
 ```
 
-The `@cratis/arc*` packages, `react`, and `react-dom` are also peer dependencies, but you almost certainly already have them.
+The `@cratis/arc*` packages, `@cratis/fundamentals`, `react`, and `react-dom` are also peer dependencies, but you almost certainly already have them (`@cratis/fundamentals` comes in transitively with `@cratis/arc`).
 
 ### 2. The optional dependencies are now optional peer dependencies
 
@@ -58,25 +57,28 @@ The `@cratis/arc*` packages, `react`, and `react-dom` are also peer dependencies
 
 | You use… | …so add to your install |
 |---|---|
-| `PivotViewer` | `pixi.js` |
-| `CommandStepper` / animated panels | `framer-motion` |
+| `PivotViewer` | `pixi.js` and `framer-motion` |
 | `DataPage` with resizable layout | `allotment` |
 
-If you don't use these components, you don't need to do anything.
+If you don't use these components, you don't need to do anything — provided your bundler tree-shakes. `PivotViewer` and `DataPage` are re-exported from the package root (`@cratis/components`) and statically import their optional peers, so a modern bundler (Vite, Rollup, esbuild, webpack 5) drops them when unused — the package marks its JS side-effect-free apart from CSS. If you import from the root with a bundler that does **not** tree-shake, install the optional peers too, or import the components you use from their subpaths (`@cratis/components/Dialogs`, `@cratis/components/CommandForm`, …) so the heavy components are never pulled into the graph.
 
-### 3. `react-router-dom` is no longer a dependency
+### 3. `react-router-dom` and `usehooks-ts` are no longer dependencies
 
-It was listed as a runtime dependency but never imported by anything inside `@cratis/components`. If your app uses it directly (which is very likely), you should already have it in your own `package.json` — nothing changes for you.
+Both were listed as runtime dependencies but never imported by anything inside `@cratis/components`, so they have been dropped. If your app uses `react-router-dom` directly (very likely), you should already have it in your own `package.json` — nothing changes for you.
 
-If you were somehow relying on the transitive copy from `@cratis/components`, add it to your own deps:
+If you were somehow relying on the transitive copy of either, add it to your own deps:
 
 ```bash
 yarn add react-router-dom
 ```
 
+### 4. `@cratis/arc.vite` is no longer a peer dependency
+
+It was only ever used by the package's own dev `vite.config.ts`, so it moved to `devDependencies`. If you previously installed it solely to satisfy the peer requirement, you can drop it — nothing in the shipped library imports it.
+
 ## Visual changes
 
-The styling work removes a few couplings to PrimeReact theme internals. These changes are intentional and almost always invisible, but there are two places where pixel-perfect rendering may shift.
+The styling work removes a few couplings to PrimeReact theme internals. These changes are intentional and almost always invisible, but there are a handful of places where rendering may shift.
 
 ### `FormElement` addon is now Cratis-bespoke
 
@@ -110,6 +112,14 @@ This is arguably a bug fix — the original code was always meant to draw the bo
 }
 ```
 
+### `RadioGroupField` vertical layout now stacks correctly
+
+`RadioGroupField` defaults to `layout="vertical"`, which is meant to stack the options in a column. Earlier releases expressed that with `flex-column` / `align-items-center` — again **PrimeFlex** class names the library never shipped — so the classes no-op'd and the options laid out in a **row** instead. The horizontal layout used valid Tailwind classes and worked correctly.
+
+This release uses the library's own Tailwind utilities (`flex-col` / `items-center`), so a default (vertical) `RadioGroupField` now renders as a true vertical stack, and the control/label of every `CheckboxField`, `RadioButtonField`, and `RadioGroupField` option is vertically centered.
+
+This is a bug fix — vertical was always the intended default — but if you had compensated for the broken row layout (for example by setting `layout="vertical"` and relying on the row rendering, or by adding your own wrapping styles), revisit those call sites after upgrading. To keep the old row layout, set `layout="horizontal"` explicitly.
+
 ### Other PrimeReact class hooks removed
 
 The library no longer uses these hard-coded PrimeReact class names internally:
@@ -136,6 +146,10 @@ Any consumer who tried `import { CommandStepper } from '@cratis/components/Comma
 
 Earlier README listed `@cratis/components/EventModeling` in the available subpath exports. The path did not exist in the package's `exports` map and never did. If you tried to import from it, the import always failed. The README has been corrected.
 
+### `@cratis/components/CommandForm/fields` now resolves under CommonJS
+
+This subpath's CJS target was never emitted by the build, so `require('@cratis/components/CommandForm/fields')` failed (ESM `import` worked). Because the subpath is equivalent to `@cratis/components/CommandForm` — which already re-exports every field — its `exports` entry now points at that same barrel, so both `import` and `require` resolve. Existing imports from either path keep working unchanged.
+
 ### New subpath exports
 
 Three component-folder subpaths that already had built indexes but were missing from the `exports` map have been added:
diff --git a/Source/CommandForm/fields/CheckboxField.tsx b/Source/CommandForm/fields/CheckboxField.tsx
index d1c7010..71c1caa 100644
--- a/Source/CommandForm/fields/CheckboxField.tsx
+++ b/Source/CommandForm/fields/CheckboxField.tsx
@@ -36,7 +36,7 @@ interface CheckboxFieldComponentProps extends WrappedFieldProps<boolean> {
  */
 export const CheckboxField = asCommandFormField<CheckboxFieldComponentProps>(
     (props) => (
-        <div className="flex align-items-center">
+        <div className="flex items-center">
             <Checkbox
                 checked={props.value}
                 onChange={props.onChange}
diff --git a/Source/CommandForm/fields/ColorPickerField.tsx b/Source/CommandForm/fields/ColorPickerField.tsx
index e5fd63b..7cbda44 100644
--- a/Source/CommandForm/fields/ColorPickerField.tsx
+++ b/Source/CommandForm/fields/ColorPickerField.tsx
@@ -42,6 +42,10 @@ export const ColorPickerField = asCommandFormField<ColorPickerFieldComponentProp
     (props) => {
         const defaultColor = props.defaultColor ?? '000000';
         const value = typeof props.value === 'string' && props.value.length > 0 ? props.value : defaultColor;
+        // PrimeReact's ColorPicker is the one form component that exposes no `invalid` prop,
+        // so we apply the `p-invalid` state class directly. This is the exact class the
+        // `invalid` prop emits on the other fields, so the rendered DOM stays consistent —
+        // it picks up a theme's invalid styling and harmlessly no-ops in unstyled mode.
         const invalidClass = props.invalid ? 'p-invalid' : undefined;
         const className = [invalidClass, props.className].filter(Boolean).join(' ') || undefined;
 
diff --git a/Source/CommandForm/fields/RadioButtonField.tsx b/Source/CommandForm/fields/RadioButtonField.tsx
index 261a256..91d96e9 100644
--- a/Source/CommandForm/fields/RadioButtonField.tsx
+++ b/Source/CommandForm/fields/RadioButtonField.tsx
@@ -43,7 +43,7 @@ interface RadioButtonFieldComponentProps extends WrappedFieldProps<string | numb
  */
 export const RadioButtonField = asCommandFormField<RadioButtonFieldComponentProps>(
     (props) => (
-        <div className="flex align-items-center">
+        <div className="flex items-center">
             <RadioButton
                 value={props.buttonValue}
                 checked={props.value === props.buttonValue}
diff --git a/Source/CommandForm/fields/RadioGroupField.tsx b/Source/CommandForm/fields/RadioGroupField.tsx
index f10f3e7..3190395 100644
--- a/Source/CommandForm/fields/RadioGroupField.tsx
+++ b/Source/CommandForm/fields/RadioGroupField.tsx
@@ -49,7 +49,7 @@ interface RadioGroupFieldComponentProps extends WrappedFieldProps<string | numbe
 export const RadioGroupField = asCommandFormField<RadioGroupFieldComponentProps>(
     (props) => {
         const layout = props.layout ?? 'vertical';
-        const layoutClasses = layout === 'horizontal' ? 'flex-row gap-4 flex-wrap' : 'flex-column gap-2';
+        const layoutClasses = layout === 'horizontal' ? 'flex-row gap-4 flex-wrap' : 'flex-col gap-2';
         const containerClassName = props.className
             ? `flex ${layoutClasses} ${props.className}`
             : `flex ${layoutClasses}`;
@@ -59,7 +59,7 @@ export const RadioGroupField = asCommandFormField<RadioGroupFieldComponentProps>
                     const optValue = option[props.optionValue] as string | number;
                     const optLabel = option[props.optionLabel] as string;
                     return (
-                        <div key={String(optValue)} className="flex align-items-center">
+                        <div key={String(optValue)} className="flex items-center">
                             <RadioButton
                                 value={optValue}
                                 checked={props.value === optValue}
diff --git a/Source/Dialogs/Dialog.stories.tsx b/Source/Dialogs/Dialog.stories.tsx
index 7463203..702b3e1 100644
--- a/Source/Dialogs/Dialog.stories.tsx
+++ b/Source/Dialogs/Dialog.stories.tsx
@@ -94,7 +94,7 @@ export const WithForm: Story = {
                     onCancel={() => closeDialog(DialogResult.Cancelled)}
                     isValid={name.trim().length > 0}
                 >
-                    <div className="flex flex-column gap-2">
+                    <div className="flex flex-col gap-2">
                         <label htmlFor="name">Name</label>
                         <InputText
                             id="name"
diff --git a/Source/README.md b/Source/README.md
index cf912c1..8296aed 100644
--- a/Source/README.md
+++ b/Source/README.md
@@ -38,8 +38,7 @@ component that depends on them:
 
 | Component | Optional peer |
 |---|---|
-| `PivotViewer` | `pixi.js` |
-| `CommandStepper`, animated panels | `framer-motion` |
+| `PivotViewer` | `pixi.js` (canvas) and `framer-motion` (animated panels) |
 | `DataPage` resizable layout | `allotment` |
 
 Install them only when you reach for the corresponding component.
@@ -504,14 +503,14 @@ The paths compose, so you don't have to pick one for the whole app:
 
 Three patterns, depending on how much PrimeReact a wrapper composes:
 
-1. **Single-widget wrappers** — `Dialog`, every `CommandForm` field, the
-   underlying `DataTable`/`Paginator` exposed by `DataTableForQuery` /
-   `DataTableForObservableQuery`, and `Dropdown` forward `pt`, `ptOptions`,
-   `unstyled`, and `className` straight to their inner PrimeReact component.
+1. **Single-widget wrappers** — `Dialog`, every `CommandForm` field,
+   `EventsView`, and `Dropdown` forward `pt`, `ptOptions`, `unstyled`, and
+   `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) — each slot has `*PtOptions`, `*Unstyled`, and `*ClassName`
-   siblings.
+   for Menubar), and `DataTableForQuery` / `DataTableForObservableQuery`
+   (`pt` for DataTable, `paginatorPt` for Paginator) — each slot has
+   `*PtOptions`, `*Unstyled`, and (where applicable) `*ClassName` siblings.
 3. **Large composites** — `ObjectContentEditor`, `ObjectNavigationalBar`,
    `SchemaEditor` expose `className` only; restyle internals via the global
    `pt` preset.
diff --git a/Source/SchemaEditor/NameCell.tsx b/Source/SchemaEditor/NameCell.tsx
index 467e824..c71ce4d 100644
--- a/Source/SchemaEditor/NameCell.tsx
+++ b/Source/SchemaEditor/NameCell.tsx
@@ -44,7 +44,8 @@ export const NameCell = ({ rowData, isEditMode, onUpdate, validationError }: Nam
         <InputText
             value={rowData.name || ''}
             onChange={(e) => onUpdate(rowData.name || '', 'name', e.target.value)}
-            className={`w-full ${validationError ? 'p-invalid' : ''}`}
+            className="w-full"
+            invalid={!!validationError}
             data-pr-tooltip={validationError}
             data-pr-position="top"
         />
diff --git a/Source/TimeMachine/EventsView.tsx b/Source/TimeMachine/EventsView.tsx
index 4a7740c..48dbe8c 100644
--- a/Source/TimeMachine/EventsView.tsx
+++ b/Source/TimeMachine/EventsView.tsx
@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import React, { useEffect, useRef, useState } from 'react';
-import { Timeline } from 'primereact/timeline';
+import { Timeline, type TimelineProps } from 'primereact/timeline';
 import type { Event } from './types';
 import { Properties } from './Properties';
 import './EventsView.css';
@@ -13,6 +13,18 @@ import './EventsView.css';
 interface EventsViewProps {
     /** The events to display, in chronological order. */
     events: Event[];
+
+    /** Extra CSS class name forwarded to the underlying Timeline, alongside the component's own. */
+    className?: string;
+
+    /** PrimeReact pass-through configuration applied to the underlying Timeline. */
+    pt?: TimelineProps['pt'];
+
+    /** PrimeReact pass-through options applied to the underlying Timeline. */
+    ptOptions?: TimelineProps['ptOptions'];
+
+    /** When true, disables every base PrimeReact style on the underlying Timeline. */
+    unstyled?: boolean;
 }
 
 /**
@@ -26,7 +38,7 @@ interface EventsViewProps {
  *
  * @param props - {@link EventsViewProps}.
  */
-export const EventsView: React.FC<EventsViewProps> = ({ events }) => {
+export const EventsView: React.FC<EventsViewProps> = ({ events, className, pt, ptOptions, unstyled }) => {
     // Use test data if no events provided
     const displayEvents = events.length > 0 ? events : [];
     const containerRef = useRef<HTMLDivElement>(null);
@@ -115,7 +127,10 @@ export const EventsView: React.FC<EventsViewProps> = ({ events }) => {
                 align="alternate"
                 content={customContent}
                 marker={customMarker}
-                className="events-view-timeline"
+                className={className ? `events-view-timeline ${className}` : 'events-view-timeline'}
+                pt={pt}
+                ptOptions={ptOptions}
+                unstyled={unstyled}
             />
             {canScrollDown && (
                 <div className="events-view-scroll-button-wrapper events-view-scroll-button-wrapper--bottom">
diff --git a/Source/package.json b/Source/package.json
index d1d8542..4ae8b9f 100644
--- a/Source/package.json
+++ b/Source/package.json
@@ -12,7 +12,9 @@
         "access": "public"
     },
     "files": [
-        "dist"
+        "dist",
+        "!dist/**/*.stories.*",
+        "!dist/**/given.*"
     ],
     "main": "dist/cjs/index.js",
     "module": "dist/esm/index.js",
@@ -43,9 +45,9 @@
             "import": "./dist/esm/CommandForm/index.js"
         },
         "./CommandForm/fields": {
-            "types": "./dist/esm/CommandForm/fields/index.d.ts",
-            "require": "./dist/cjs/CommandForm/fields/index.js",
-            "import": "./dist/esm/CommandForm/fields/index.js"
+            "types": "./dist/esm/CommandForm/index.d.ts",
+            "require": "./dist/cjs/CommandForm/index.js",
+            "import": "./dist/esm/CommandForm/index.js"
         },
         "./Common": {
             "types": "./dist/esm/Common/index.d.ts",
@@ -139,6 +141,7 @@
     "peerDependencies": {
         "@cratis/arc": "^20.3.1",
         "@cratis/arc.react": "^20.3.1",
+        "@cratis/fundamentals": "^7.10.3",
         "allotment": "^1.20.0",
         "framer-motion": "^12.0.0",
         "pixi.js": "^8.0.0",

From 68d5f87beb4de61d918bc68f717a8d85de7107db Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Fri, 29 May 2026 23:09:39 +0200
Subject: [PATCH 18/23] Refine documentation for styling options and improve
 clarity across multiple files

---
 .../Common/cratis-components-provider.md      |  4 +-
 Documentation/Common/form-element.md          |  4 +-
 Documentation/Common/index.md                 |  2 +-
 Documentation/Styling/cratis-tokens.md        |  8 +--
 Documentation/Styling/custom-palette.md       | 12 ++---
 Documentation/Styling/getting-started.md      | 10 ++--
 Documentation/Styling/index.md                | 30 +++++------
 Documentation/Styling/mixing-paths.md         | 14 ++---
 Documentation/Styling/pass-through.md         |  2 +-
 Documentation/Styling/themed.md               | 12 ++---
 Documentation/Styling/toc.yml                 |  8 +--
 Documentation/Styling/unstyled.md             | 10 ++--
 Documentation/index.md                        | 24 ++++-----
 Documentation/migration.md                    | 20 +++----
 Source/Dialogs/Dialog.tsx                     |  2 +-
 Source/README.md                              | 54 +++++++++----------
 16 files changed, 108 insertions(+), 108 deletions(-)

diff --git a/Documentation/Common/cratis-components-provider.md b/Documentation/Common/cratis-components-provider.md
index 5268fe4..7191c2c 100644
--- a/Documentation/Common/cratis-components-provider.md
+++ b/Documentation/Common/cratis-components-provider.md
@@ -106,6 +106,6 @@ const merged = mergeCratisComponentsConfig({ unstyled: true, pt: myPt });
 
 ## See also
 
-- [Styling Overview](../Styling/index.md) — three styling paths and where the provider fits
+- [Styling Overview](../Styling/index.md) — the supported styling options and where the provider fits
 - [Pass-through cheat sheet](../Styling/pass-through.md) — what `pt` reaches in each Cratis wrapper
-- [Path C — Fully unstyled](../Styling/unstyled.md) — full `pt` preset walk-through
+- [Use fully unstyled mode](../Styling/unstyled.md) — full `pt` preset walk-through
diff --git a/Documentation/Common/form-element.md b/Documentation/Common/form-element.md
index d251582..37c46bc 100644
--- a/Documentation/Common/form-element.md
+++ b/Documentation/Common/form-element.md
@@ -117,7 +117,7 @@ For per-instance restyling, wrap the FormElement with your own class and target
 </div>
 ```
 
-For full styling control under `unstyled` mode (Path C), the addon classes are stable: `cratis-form-element` on the row and `cratis-form-element__addon` on the leading slot.
+For full styling control under `unstyled` mode, the addon classes are stable: `cratis-form-element` on the row and `cratis-form-element__addon` on the leading slot.
 
 ## When to use FormElement vs CommandForm fields
 
@@ -126,6 +126,6 @@ For full styling control under `unstyled` mode (Path C), the addon classes are s
 
 ## See Also
 
-- [Styling Overview](../Styling/index.md) — three styling paths and where FormElement fits
+- [Styling Overview](../Styling/index.md) — the supported styling options and where FormElement fits
 - [Cratis token reference](../Styling/cratis-tokens.md) — every token and the surfaces it tints
 - [CommandForm Field Types](../CommandForm/index.md) — command-bound field wrappers
diff --git a/Documentation/Common/index.md b/Documentation/Common/index.md
index 1229019..08f9996 100644
--- a/Documentation/Common/index.md
+++ b/Documentation/Common/index.md
@@ -17,4 +17,4 @@ The Common module provides reusable UI components and the styling setup primitiv
 - [Page](page.md) - Page layout component
 - [FormElement](form-element.md) - Form field icon-addon wrapper
 - [ErrorBoundary](error-boundary.md) - Error boundary component
-- [Styling Overview](../Styling/index.md) — three styling paths and how Common fits in
+- [Styling Overview](../Styling/index.md) — the supported styling options and how Common fits in
diff --git a/Documentation/Styling/cratis-tokens.md b/Documentation/Styling/cratis-tokens.md
index 4d2dd99..9d048e2 100644
--- a/Documentation/Styling/cratis-tokens.md
+++ b/Documentation/Styling/cratis-tokens.md
@@ -1,8 +1,8 @@
 # Cratis token reference
 
-The `--cratis-*` CSS variable layer is the Cratis-scoped tint surface every Cratis wrapper reads from. Each token defaults to a matching PrimeReact theme variable via `tokens.css`, so loading a PrimeReact theme (Paths [A](themed.md) and [B](custom-palette.md)) automatically gives every Cratis surface the right color without any further work.
+The `--cratis-*` CSS variable layer is the Cratis-scoped tint surface every Cratis wrapper reads from. Each token defaults to a matching PrimeReact theme variable via `tokens.css`, so loading a PrimeReact theme automatically gives every Cratis surface the right color without any further work.
 
-You override `--cratis-*` tokens when you want **just** Cratis-scoped surfaces (validation error text, FormElement addon, breadcrumb borders, …) tinted independently of PrimeReact widgets. To repaint PrimeReact widgets themselves, override the PrimeReact variables directly — see [Path B](custom-palette.md).
+You override `--cratis-*` tokens when you want **just** Cratis-scoped surfaces (validation error text, FormElement addon, breadcrumb borders, …) tinted independently of PrimeReact widgets. To repaint PrimeReact widgets themselves, override the PrimeReact variables directly — see [the custom palette setup](custom-palette.md).
 
 ## Loading the tokens
 
@@ -150,9 +150,9 @@ That means:
 - Override `--surface-card` (PrimeReact) → both PrimeReact widgets *and* Cratis surfaces follow.
 - Override `--cratis-surface-card` (Cratis) → only Cratis surfaces follow; PrimeReact widgets keep their existing color.
 
-Use the PrimeReact variable when you want a whole-UI repaint (Path B). Use the Cratis token when you want a Cratis-specific accent that differs from PrimeReact widgets.
+Use the PrimeReact variable when you want a whole-UI repaint. Use the Cratis token when you want a Cratis-specific accent that differs from PrimeReact widgets.
 
 ## See also
 
-- [Path B — Custom palette](custom-palette.md) — for whole-UI repainting with PrimeReact variables
+- [Use a custom palette on top of a PrimeReact theme](custom-palette.md) — for whole-UI repainting with PrimeReact variables
 - [Pass-through cheat sheet](pass-through.md) — for per-slot styling beyond what tokens reach
diff --git a/Documentation/Styling/custom-palette.md b/Documentation/Styling/custom-palette.md
index fe1bde5..809da26 100644
--- a/Documentation/Styling/custom-palette.md
+++ b/Documentation/Styling/custom-palette.md
@@ -1,8 +1,8 @@
-# Path B — Themed with custom palette
+# Use a custom palette on top of a PrimeReact theme
 
 You want PrimeReact's chrome — its dialog frames, button shapes, focus rings, input borders — but in your own colors. You don't want to write a PrimeReact theme from scratch.
 
-This path keeps a PrimeReact theme as the **structural baseline** and overrides PrimeReact's own CSS variables on `:root` to repaint the whole UI. The `--cratis-*` tokens follow along through `tokens.css`'s cascade, so Cratis-scoped surfaces stay in sync. You can also override the Cratis tokens independently when you want Cratis surfaces to differ from PrimeReact widgets.
+This setup keeps a PrimeReact theme as the **structural baseline** and overrides PrimeReact's own CSS variables on `:root` to repaint the whole UI. The `--cratis-*` tokens follow along through `tokens.css`'s cascade, so Cratis-scoped surfaces stay in sync. You can also override the Cratis tokens independently when you want Cratis surfaces to differ from PrimeReact widgets.
 
 ## Setup
 
@@ -132,7 +132,7 @@ Put each palette behind a class on the root element and toggle the class with yo
 document.documentElement.classList.add('theme-dark');
 ```
 
-## What `--cratis-*` tokens are for in this path
+## What `--cratis-*` tokens are for in this setup
 
 Two override surfaces are available, with different reach:
 
@@ -141,8 +141,8 @@ Two override surfaces are available, with different reach:
 
 See [Cratis token reference](cratis-tokens.md) for the full Cratis token list, and [Pass-through cheat sheet](pass-through.md) when you want even tighter per-component control.
 
-## When to switch paths
+## When to use fully unstyled mode
 
-You'll outgrow Path B when:
+This setup stops being a good fit when:
 
-- You need to restyle the structural chrome itself — for example, a non-rectangular Dialog frame, a completely different Button shape, or a design system with a custom focus-ring system. Switch to [Path C](unstyled.md) and bring the visuals yourself.
+- You need to restyle the structural chrome itself — for example, a non-rectangular Dialog frame, a completely different Button shape, or a design system with a custom focus-ring system. Use [fully unstyled mode](unstyled.md) and bring the visuals yourself.
diff --git a/Documentation/Styling/getting-started.md b/Documentation/Styling/getting-started.md
index 67e63ad..00bd529 100644
--- a/Documentation/Styling/getting-started.md
+++ b/Documentation/Styling/getting-started.md
@@ -1,6 +1,6 @@
 # Getting Started
 
-Every styling path shares the same one-line setup. The differences come from what you load **on top** of this baseline.
+Every styling option shares the same one-line setup. The differences come from what you load **on top** of this baseline.
 
 ## Install
 
@@ -50,11 +50,11 @@ With nothing else, you've imported:
 - The `--cratis-*` token layer (so Cratis-scoped surfaces have a stable variable surface to read from)
 - The provider that hosts `pt` / `unstyled` / locale / overlay z-index settings
 
-That's enough for the wrappers to render structurally, but PrimeReact widgets need **either** a theme (Path A or B) or `unstyled: true` + a `pt` preset (Path C) to look like anything other than raw browser primitives. Pick your path:
+That's enough for the wrappers to render structurally, but PrimeReact widgets need **either** a theme or `unstyled: true` + a `pt` preset to look like anything other than raw browser primitives. Choose the setup that matches how much visual control you need:
 
-- [Path A — PrimeReact-themed](themed.md) — load a theme stylesheet and start tweaking
-- [Path B — Custom palette](custom-palette.md) — same theme, your colors
-- [Path C — Fully unstyled](unstyled.md) — bring everything yourself
+- [Use a PrimeReact theme](themed.md) — load a theme stylesheet and start tweaking
+- [Use a custom palette on top of a PrimeReact theme](custom-palette.md) — keep the theme's structure and supply your colors
+- [Use fully unstyled mode](unstyled.md) — disable PrimeReact styling and bring every visual yourself
 
 ## Using `PrimeReactProvider` directly
 
diff --git a/Documentation/Styling/index.md b/Documentation/Styling/index.md
index 72f4c4e..1e789aa 100644
--- a/Documentation/Styling/index.md
+++ b/Documentation/Styling/index.md
@@ -1,24 +1,24 @@
 # Styling
 
-Cratis Components is built on top of PrimeReact and stays out of your way when it comes to styling. You can ship the look that PrimeReact gives you out of the box, repaint the whole UI in your own palette, or take complete control and bring your own visuals from scratch — all without forking the library or fighting it.
+Cratis Components is built on top of PrimeReact and stays out of your way when it comes to styling. You can use the look that PrimeReact gives you out of the box, keep PrimeReact's structure while applying your own palette, or take complete control and provide every visual yourself — all without forking the library or fighting it.
 
-There are three documented paths. They are not mutually exclusive: every component still exposes the same building blocks, so you can mix them per-component or per-region of your app.
+There are three supported styling options. They are not mutually exclusive: every component still exposes the same building blocks, so you can combine them per-component or per-region of your app.
 
-## TL;DR — pick a path
+## TL;DR — choose a styling setup
 
-| Path | When | Effort | What you write |
+| Setup | When | Effort | What you write |
 |---|---|---|---|
-| [**A. PrimeReact-themed**](themed.md) | You want it to look good immediately and tweak from there. | Lowest | One CSS import + provider |
-| [**B. Custom palette**](custom-palette.md) | You want PrimeReact's chrome but in your own colors. | Low | A PrimeReact theme + a small CSS override block |
-| [**C. Fully unstyled**](unstyled.md) | You're integrating into a tightly-controlled design system. | Highest | A `pt` preset (in CSS or Tailwind) |
+| [**Use a PrimeReact theme**](themed.md) | You want components to look good immediately and tweak from there. | Lowest | Theme CSS import + provider |
+| [**Use a custom palette on top of a PrimeReact theme**](custom-palette.md) | You want PrimeReact's structure but your own colors. | Low | A PrimeReact theme + CSS variable overrides |
+| [**Use fully unstyled mode**](unstyled.md) | You're integrating into a tightly controlled design system. | Highest | `unstyled: true` + a `pt` preset in CSS or Tailwind |
 
-All three paths use the same one-line setup described in [Getting Started](getting-started.md). They remain switchable later — you won't repaint yourself into a corner.
+All three setups use the same one-line setup described in [Getting Started](getting-started.md). You can change direction later because the same provider, tokens, and `pt` hooks stay available.
 
-## Why a PrimeReact theme is still in Paths A and B
+## Why the first two options still load a PrimeReact theme
 
 In PrimeReact 10 every widget's *structural* CSS — padding, borders, dialog frame, focus rings, button shapes — ships **inside the theme file**. There is no separate primitives stylesheet. So a setup without any PrimeReact theme has no widget chrome at all and components render as the raw HTML primitives the browser supplies by default.
 
-The `--cratis-*` token layer is an additive Cratis-scoped tint for surfaces the wrappers in this package own — validation error text, the FormElement addon background, breadcrumb borders — and **is not, by itself, sufficient to skin PrimeReact widgets**. Use Path B if you want a custom palette on top of PrimeReact's chrome, and Path C if you want to ditch PrimeReact's chrome entirely.
+The `--cratis-*` token layer is an additive Cratis-scoped tint for surfaces the wrappers in this package own — validation error text, the FormElement addon background, breadcrumb borders — and **is not, by itself, sufficient to skin PrimeReact widgets**. Override PrimeReact's variables when you want the whole UI in your palette. Use `unstyled: true` and a `pt` preset when you want to replace PrimeReact's visuals entirely.
 
 ## Mental model
 
@@ -32,11 +32,11 @@ The [Cratis token reference](cratis-tokens.md) lists every token and the surface
 
 ## See also
 
-- [Getting Started](getting-started.md) — the one-line setup every path shares
-- [Path A — PrimeReact-themed](themed.md)
-- [Path B — Custom palette](custom-palette.md)
-- [Path C — Fully unstyled](unstyled.md)
+- [Getting Started](getting-started.md) — the one-line setup every option shares
+- [Use a PrimeReact theme](themed.md)
+- [Use a custom palette on top of a PrimeReact theme](custom-palette.md)
+- [Use fully unstyled mode](unstyled.md)
 - [Cratis token reference](cratis-tokens.md)
 - [Pass-through (pt) cheat sheet](pass-through.md)
-- [Mixing paths](mixing-paths.md)
+- [Combining styling setups](mixing-paths.md)
 - [CratisComponentsProvider](../Common/cratis-components-provider.md)
diff --git a/Documentation/Styling/mixing-paths.md b/Documentation/Styling/mixing-paths.md
index 96cf2af..887c24c 100644
--- a/Documentation/Styling/mixing-paths.md
+++ b/Documentation/Styling/mixing-paths.md
@@ -1,6 +1,6 @@
-# Mixing paths
+# Combining styling setups
 
-The three paths compose. You don't have to pick one for the whole app — every Cratis wrapper still exposes the same building blocks, so you can mix them per-component or per-region.
+The three styling options compose. You don't have to choose one for the whole app — every Cratis wrapper still exposes the same building blocks, so you can combine them per-component or per-region.
 
 ## Themed app with one unstyled island
 
@@ -123,9 +123,9 @@ If you want PrimeReact widgets in the region to follow too, override the PrimeRe
 }
 ```
 
-## Per-component themed override inside unstyled mode
+## Per-component visual override inside unstyled mode
 
-When you're on Path C globally, single components can still pull in classes from a separate stylesheet via the `className` prop or per-instance `pt`:
+When you're using fully unstyled mode globally, single components can still pull in classes from a separate stylesheet via the `className` prop or per-instance `pt`:
 
 ```tsx
 import './custom-table.css';
@@ -151,8 +151,8 @@ import './custom-table.css';
 
 ## See also
 
-- [Path A — PrimeReact-themed](themed.md)
-- [Path B — Custom palette](custom-palette.md)
-- [Path C — Fully unstyled](unstyled.md)
+- [Use a PrimeReact theme](themed.md)
+- [Use a custom palette on top of a PrimeReact theme](custom-palette.md)
+- [Use fully unstyled mode](unstyled.md)
 - [Pass-through cheat sheet](pass-through.md)
 - [CratisComponentsProvider](../Common/cratis-components-provider.md)
diff --git a/Documentation/Styling/pass-through.md b/Documentation/Styling/pass-through.md
index 75be415..cf422b5 100644
--- a/Documentation/Styling/pass-through.md
+++ b/Documentation/Styling/pass-through.md
@@ -135,4 +135,4 @@ To replace a slot's preset entirely on a single instance, opt out of merging:
 ## See also
 
 - [CratisComponentsProvider](../Common/cratis-components-provider.md) — global `pt` / `unstyled` setup
-- [Path C — Fully unstyled](unstyled.md) — full pt-preset walk-through
+- [Use fully unstyled mode](unstyled.md) — full `pt` preset walk-through
diff --git a/Documentation/Styling/themed.md b/Documentation/Styling/themed.md
index 7ebb7b5..4db41ca 100644
--- a/Documentation/Styling/themed.md
+++ b/Documentation/Styling/themed.md
@@ -1,6 +1,6 @@
-# Path A — PrimeReact-themed (fastest start)
+# Use a PrimeReact theme
 
-You want components to look reasonable out of the box and only intervene when needed. Pick this path for prototypes, internal tools, or any app where one of the prebuilt PrimeReact themes is good enough.
+You want components to look reasonable out of the box and only intervene when needed. Use this setup for prototypes, internal tools, or any app where one of the prebuilt PrimeReact themes is a good fit.
 
 ## Setup
 
@@ -96,9 +96,9 @@ When CSS overrides aren't enough — for example, when you need to attach a clas
 
 `pt`, `ptOptions`, and `unstyled` are typed from the underlying PrimeReact component, so your IDE autocompletes the available slot names.
 
-## When to switch paths
+## When to choose another setup
 
-You'll outgrow Path A when:
+This setup stops being a good fit when:
 
-- The PrimeReact theme is "almost" but not your brand — switch to [Path B](custom-palette.md) and override the PrimeReact variables on `:root`.
-- You're integrating into a design system that defines its own button, dialog, and input visuals — switch to [Path C](unstyled.md) and bring everything yourself.
+- The PrimeReact theme is "almost" but not your brand — use [a custom palette on top of a PrimeReact theme](custom-palette.md) and override the PrimeReact variables on `:root`.
+- You're integrating into a design system that defines its own button, dialog, and input visuals — use [fully unstyled mode](unstyled.md) and bring every visual yourself.
diff --git a/Documentation/Styling/toc.yml b/Documentation/Styling/toc.yml
index 44ad126..52c4493 100644
--- a/Documentation/Styling/toc.yml
+++ b/Documentation/Styling/toc.yml
@@ -2,15 +2,15 @@
   href: index.md
 - name: Getting Started
   href: getting-started.md
-- name: Path A — PrimeReact-themed
+- name: Use a PrimeReact theme
   href: themed.md
-- name: Path B — Custom palette
+- name: Use a custom palette on top of a PrimeReact theme
   href: custom-palette.md
-- name: Path C — Fully unstyled
+- name: Use fully unstyled mode
   href: unstyled.md
 - name: Cratis token reference
   href: cratis-tokens.md
 - name: Pass-through (pt) cheat sheet
   href: pass-through.md
-- name: Mixing paths
+- name: Combining styling setups
   href: mixing-paths.md
diff --git a/Documentation/Styling/unstyled.md b/Documentation/Styling/unstyled.md
index e1a13c2..591a920 100644
--- a/Documentation/Styling/unstyled.md
+++ b/Documentation/Styling/unstyled.md
@@ -1,8 +1,8 @@
-# Path C — Fully unstyled (you own every visual)
+# Use fully unstyled mode
 
 You're integrating Cratis Components into a design system that defines its own button, dialog, and input visuals. You want zero PrimeReact CSS in the final bundle.
 
-This path disables every PrimeReact base style at the provider and supplies visuals through PrimeReact's `pt` (pass-through) mechanism, your own CSS, or both. Components render structurally only — they become a blank canvas you paint.
+This setup disables every PrimeReact base style at the provider and supplies visuals through PrimeReact's `pt` (pass-through) mechanism, your own CSS, or both. Components render structurally only until your `pt` preset and CSS provide the actual UI.
 
 ## Setup
 
@@ -20,7 +20,7 @@ export const App = () => (
 
 `unstyled: true` removes every PrimeReact base style. The `pt` preset is what fills the visual vacuum. Without one, components render as raw HTML elements with browser defaults.
 
-The two sub-paths below show the same preset in two different styling languages. Pick whichever your design system uses.
+The two examples below show the same preset in two different styling languages. Pick whichever your design system uses.
 
 ## With plain CSS
 
@@ -260,9 +260,9 @@ Per-instance `pt` is **merged** with the global preset by default (`ptOptions.me
 
 `ObjectContentEditor`, `ObjectNavigationalBar`, and `SchemaEditor` accept only `className` on the root — restyle their internals via the **global** `pt` preset set on `CratisComponentsProvider`. See [Pass-through cheat sheet](pass-through.md) for the full per-component reference.
 
-## What `--cratis-*` tokens give you in this path
+## What `--cratis-*` tokens give you in fully unstyled mode
 
-In Path C the `pt` preset carries every visual, so you don't strictly need any `--cratis-*` token. However, a few Cratis surfaces are styled with token-driven CSS (FormElement addon, ObjectNavigationalBar bottom border, inline validation errors) — overriding the relevant tokens lets you tint those surfaces consistently with your preset:
+In fully unstyled mode the `pt` preset carries every PrimeReact visual, so you don't strictly need any `--cratis-*` token. However, a few Cratis surfaces are styled with token-driven CSS (FormElement addon, ObjectNavigationalBar bottom border, inline validation errors) — overriding the relevant tokens lets you tint those surfaces consistently with your preset:
 
 ```css
 :root {
diff --git a/Documentation/index.md b/Documentation/index.md
index 28c2065..64bd709 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -18,7 +18,7 @@ This library includes specialized components for:
 - Integrates seamlessly with Cratis Arc framework
 - Uses PrimeReact components for consistent UI/UX
 - Supports both queries and observable queries
-- Three documented [styling paths](Styling/index.md) — themed, custom palette, fully unstyled
+- Three supported [styling options](Styling/index.md) — use a PrimeReact theme, apply your own palette, or run fully unstyled
 - Full PrimeReact `pt` (pass-through) forwarding on every wrapper for per-slot styling
 - Comprehensive Storybook documentation
 - Accessibility-focused design
@@ -64,13 +64,13 @@ export const App = () => (
 );
 ```
 
-### Pick a styling path
+### Choose how styling works
 
-The components render structurally as soon as the provider is mounted. To give them a visual identity, pick one of the three documented paths:
+The components render structurally as soon as the provider is mounted. To give them a visual identity, choose the setup that matches how much control you need:
 
-- [**Path A — PrimeReact-themed**](Styling/themed.md) — load a PrimeReact theme; tweak with CSS or `className` as needed.
-- [**Path B — Custom palette**](Styling/custom-palette.md) — keep a PrimeReact theme as the structural baseline; repaint with CSS variables on `:root`.
-- [**Path C — Fully unstyled**](Styling/unstyled.md) — disable PrimeReact's base styles; bring everything yourself via a `pt` preset (in CSS or Tailwind).
+- [**Use a PrimeReact theme**](Styling/themed.md) — load a theme stylesheet and tweak with CSS or `className` as needed.
+- [**Use a custom palette on top of a PrimeReact theme**](Styling/custom-palette.md) — keep the theme's structure and repaint with CSS variables on `:root`.
+- [**Use fully unstyled mode**](Styling/unstyled.md) — disable PrimeReact's base styles and provide the visuals through a `pt` preset in CSS or Tailwind.
 
 See the [Styling overview](Styling/index.md) for the full mental model.
 
@@ -110,15 +110,15 @@ Advanced components for specific use cases — `PivotViewer`, `TimeMachine`, `Sc
 
 ## Styling
 
-Styling is designed to stay out of the way: pick the path that matches how much control you want, and the other layers stay invisible. See the dedicated [Styling section](Styling/index.md) for:
+Styling is designed to stay out of the way: choose the setup that matches how much control you want, and the other layers stay invisible. See the dedicated [Styling section](Styling/index.md) for:
 
-- [Getting Started](Styling/getting-started.md) — the one-line setup every path shares
-- [Path A — PrimeReact-themed](Styling/themed.md)
-- [Path B — Custom palette](Styling/custom-palette.md)
-- [Path C — Fully unstyled](Styling/unstyled.md)
+- [Getting Started](Styling/getting-started.md) — the one-line setup every option shares
+- [Use a PrimeReact theme](Styling/themed.md)
+- [Use a custom palette on top of a PrimeReact theme](Styling/custom-palette.md)
+- [Use fully unstyled mode](Styling/unstyled.md)
 - [Cratis token reference](Styling/cratis-tokens.md)
 - [Pass-through (pt) cheat sheet](Styling/pass-through.md)
-- [Mixing paths](Styling/mixing-paths.md)
+- [Combining styling setups](Styling/mixing-paths.md)
 
 ## Upgrading from an earlier release
 
diff --git a/Documentation/migration.md b/Documentation/migration.md
index e23f5d1..b5932e8 100644
--- a/Documentation/migration.md
+++ b/Documentation/migration.md
@@ -1,6 +1,6 @@
 # Migration guide — upgrading from earlier `@cratis/components`
 
-This release is the first to expose the three styling paths described in the [Styling section](Styling/index.md) and the first to ship `CratisComponentsProvider`, the `--cratis-*` token layer, and full `pt` / `unstyled` forwarding on every wrapper. It is also the release that moves PrimeReact and friends from runtime `dependencies` to `peerDependencies`, which is the dominant breaking signal.
+This release is the first to document the supported styling setups described in the [Styling section](Styling/index.md): use a PrimeReact theme, keep the theme structure but apply your own palette, or run fully unstyled with a `pt` preset. It is also the first release to ship `CratisComponentsProvider`, the `--cratis-*` token layer, and full `pt` / `unstyled` forwarding on every wrapper. The dominant breaking signal is that PrimeReact and friends move from runtime `dependencies` to `peerDependencies`.
 
 This page tells you what to change in your app, what to be aware of visually, and what new capabilities you can opt in to once the upgrade lands.
 
@@ -91,7 +91,7 @@ This release renders the addon with structural CSS using the [`--cratis-*` token
 .cratis-form-element__addon     // leading icon slot
 ```
 
-The shape and intent are identical. The exact background, border, and radius now come from `--cratis-surface-100`, `--cratis-surface-border`, and `--cratis-border-radius` rather than from the loaded PrimeReact theme. In Paths [A](Styling/themed.md) and [B](Styling/custom-palette.md) the values still cascade from the PrimeReact theme by default, so the visual is essentially the same. In Path C (unstyled) the addon **still renders** instead of disappearing — a strict improvement.
+The shape and intent are identical. The exact background, border, and radius now come from `--cratis-surface-100`, `--cratis-surface-border`, and `--cratis-border-radius` rather than from the loaded PrimeReact theme. When you [use a PrimeReact theme](Styling/themed.md) or [apply a custom palette on top of one](Styling/custom-palette.md), the values still cascade from the PrimeReact theme by default, so the visual is essentially the same. In [fully unstyled mode](Styling/unstyled.md) the addon **still renders** instead of disappearing — a strict improvement.
 
 If you were relying on the exact PrimeReact `p-inputgroup-addon` look, the [FormElement reference](Common/form-element.md#styling) shows how to override the tokens or attach your own class via `pt` to restore it.
 
@@ -132,7 +132,7 @@ The library no longer uses these hard-coded PrimeReact class names internally:
 | `border-bottom-1 surface-border` | See [section above](#objectnavigationalbar-and-schemaeditor-bottom-border-now-actually-renders). |
 | `p-inputgroup` / `p-inputgroup-addon` | See [section above](#formelement-addon-is-now-cratis-bespoke). |
 
-When a PrimeReact theme is loaded (Paths A and B), the Button `text` / `size` / `severity` props produce the same styling as the old class hooks — there's no visible change.
+When a PrimeReact theme is loaded, the Button `text` / `size` / `severity` props produce the same styling as the old class hooks — there's no visible change.
 
 ## Subpath import changes
 
@@ -299,11 +299,11 @@ Wrappers that compose more than one PrimeReact widget expose explicit per-slot p
 
 ### `--cratis-*` token layer
 
-A scoped Cratis token layer is now part of every install. Tokens default to the PrimeReact theme variable with the same name minus the `--cratis-` prefix, so Paths A and B continue to look the way they always did. Override `--cratis-*` only when you want a Cratis-scoped surface tinted independently of the surrounding PrimeReact widgets — see [Cratis token reference](Styling/cratis-tokens.md).
+A scoped Cratis token layer is now part of every install. Tokens default to the PrimeReact theme variable with the same name minus the `--cratis-` prefix, so theme-based setups continue to look the way they always did. Override `--cratis-*` only when you want a Cratis-scoped surface tinted independently of the surrounding PrimeReact widgets — see [Cratis token reference](Styling/cratis-tokens.md).
 
 ### Storybook styling toolbar
 
-`yarn dev` from `Source/` opens Storybook with a five-mode **Styling** toolbar (paintbrush icon) that flips between the three documented paths — useful for previewing how each path looks before committing to one in your app.
+`yarn dev` from `Source/` opens Storybook with a five-mode **Styling** toolbar (paintbrush icon) that demonstrates the supported styling setups — useful for previewing how each one looks before committing to it in your app.
 
 ## Migration recipes — before / after
 
@@ -386,7 +386,7 @@ export const App = () => (
 ### Switch to a fully-unstyled design system
 
 ```tsx
-// Before — there was no path here. You either lived with PrimeReact theming
+// Before — there was no supported setup for this. You either lived with PrimeReact theming
 // or wrote a custom PrimeReact theme.
 
 // After — flip the provider into unstyled mode and supply a pt preset.
@@ -395,7 +395,7 @@ export const App = () => (
 </CratisComponentsProvider>
 ```
 
-See [Path C — Fully unstyled](Styling/unstyled.md) for complete worked examples in both plain CSS and TailwindCSS.
+See [Use fully unstyled mode](Styling/unstyled.md) for complete worked examples in both plain CSS and TailwindCSS.
 
 ## Troubleshooting
 
@@ -413,12 +413,12 @@ Same root cause — the install is telling you which peer is missing. The requir
 
 ### Sparse / missing visuals after upgrade
 
-You've already loaded a PrimeReact theme (you're not in Path C). Most likely one of:
+You've already loaded a PrimeReact theme (you're not using fully unstyled mode). Most likely one of:
 
 - You're using `FormElement` and the addon now looks slightly different — see [FormElement addon is now Cratis-bespoke](#formelement-addon-is-now-cratis-bespoke).
 - You're seeing the bottom border under `ObjectNavigationalBar` or `SchemaEditor`'s menubar where you didn't see it before — see [the section on that](#objectnavigationalbar-and-schemaeditor-bottom-border-now-actually-renders).
 
-If components look fully unstyled (no padding, no borders, no dialog frame), you forgot to load a PrimeReact theme. See [Path A — PrimeReact-themed](Styling/themed.md).
+If components look fully unstyled (no padding, no borders, no dialog frame), you forgot to load a PrimeReact theme. See [Use a PrimeReact theme](Styling/themed.md).
 
 ### "Module not found: '@cratis/components/EventModeling'"
 
@@ -430,7 +430,7 @@ Pre-existing issue in the Storybook + lightningcss + Vite pipeline, not introduc
 
 ## See also
 
-- [Styling Overview](Styling/index.md) — three styling paths and the mental model
+- [Styling Overview](Styling/index.md) — the theme, custom-palette, and fully unstyled setup options
 - [CratisComponentsProvider](Common/cratis-components-provider.md) — provider configuration
 - [Cratis token reference](Styling/cratis-tokens.md) — `--cratis-*` token catalogue
 - [Pass-through cheat sheet](Styling/pass-through.md) — per-component `pt` surface
diff --git a/Source/Dialogs/Dialog.tsx b/Source/Dialogs/Dialog.tsx
index 8874911..4df6cc0 100644
--- a/Source/Dialogs/Dialog.tsx
+++ b/Source/Dialogs/Dialog.tsx
@@ -190,7 +190,7 @@ export interface DialogProps {
  *
  * Pass `pt`, `ptOptions`, `unstyled`, or `className` to forward straight to
  * the underlying PrimeReact Dialog. See the [Styling section](../../Documentation/Styling/index.md)
- * for the three documented styling paths and the
+ * for the supported styling options and the
  * [pass-through cheat sheet](../../Documentation/Styling/pass-through.md)
  * for available slots.
  *
diff --git a/Source/README.md b/Source/README.md
index 8296aed..6cec797 100644
--- a/Source/README.md
+++ b/Source/README.md
@@ -89,25 +89,25 @@ Stylesheets:
 ## Styling
 
 This package ships primarily for its functionality and Arc integrations.
-Styling is designed to stay out of the way: pick the path that matches how
+Styling is designed to stay out of the way: choose the setup that matches how
 much control you want, and the other layers stay invisible.
 
-> **Tip — see each path live:** every Storybook story includes a **Styling**
-> toolbar (paintbrush icon) that flips between the five modes corresponding to
-> the three paths below: *Lara Dark Blue*, *Lara Light Blue*, *Themed with
+> **Tip — see each setup live:** every Storybook story includes a **Styling**
+> toolbar (paintbrush icon) that flips between five modes that demonstrate
+> the three setups below: *Lara Dark Blue*, *Lara Light Blue*, *Themed with
 > custom palette*, *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 — pick a path
+### TL;DR — choose a styling setup
 
-| Path | When | Effort | What you write |
+| Setup | When | Effort | What you write |
 |---|---|---|---|
-| **A. PrimeReact-themed** | You want it to look good immediately and tweak from there. | Lowest | One CSS import + provider |
-| **B. Themed with custom palette** | You want PrimeReact's chrome but in your own colors. | Low | A PrimeReact theme + a small CSS override block |
-| **C. Fully unstyled** | You're integrating into a tightly-controlled design system. | Highest | A `pt` preset (in CSS or Tailwind) |
+| **Use a PrimeReact theme** | You want components to look good immediately and tweak from there. | Lowest | Theme CSS import + provider |
+| **Use a custom palette on top of a PrimeReact theme** | You want PrimeReact's structure but your own colors. | Low | A PrimeReact theme + CSS variable overrides |
+| **Use fully unstyled mode** | You're integrating into a tightly controlled design system. | Highest | `unstyled: true` + a `pt` preset in CSS or Tailwind |
 
-> **Why a PrimeReact theme is still in Paths A and B**
+> **Why the first two options still load a PrimeReact theme**
 >
 > In PrimeReact 10, every widget's *structural* CSS (padding, borders, dialog
 > frame, focus rings, button shapes) ships **inside the theme file**. There is
@@ -118,14 +118,14 @@ much control you want, and the other layers stay invisible.
 > The `--cratis-*` token layer is therefore an **additive Cratis-scoped tint**
 > for surfaces *our* wrappers own (validation error text, the FormElement
 > addon, breadcrumb borders, etc.). It is not, by itself, enough to skin
-> PrimeReact widgets. Use Path B if you want a custom palette on top of
-> PrimeReact's chrome, and Path C if you want to ditch PrimeReact's chrome
-> entirely.
+> PrimeReact widgets. Override PrimeReact's variables when you want the whole
+> UI in your palette. Use `unstyled: true` and a `pt` preset when you want to
+> replace PrimeReact's visuals entirely.
 
-All three paths use the same one-line setup and remain switchable later — you
-won't repaint yourself into a corner.
+All three setups use the same one-line setup. You can change direction later
+because the same provider, tokens, and `pt` hooks stay available.
 
-### One-line setup (every path)
+### One-line setup (every styling option)
 
 ```tsx
 import '@cratis/components/styles';
@@ -146,12 +146,12 @@ export const App = () => (
   `PrimeReactProvider` so Cratis has one place to layer in defaults. Drop in
   raw `PrimeReactProvider` if you'd rather.
 
-The three paths below differ only in **what else** you load on top of this
+The three setups below differ only in **what else** you load on top of this
 setup.
 
 ---
 
-### Path A — PrimeReact-themed (fastest start)
+### Use a PrimeReact theme
 
 Load any PrimeReact theme stylesheet alongside Cratis Components. PrimeReact's
 own widgets paint themselves from the theme, and the `--cratis-*` tokens cascade
@@ -206,12 +206,12 @@ Pass Tailwind utility classes through the wrapper's `className` prop:
 </Dialog>
 ```
 
-**Choose Path A when:** you're prototyping, building internal tools, or are
+**Use this setup when:** you're prototyping, building internal tools, or are
 happy with one of the prebuilt PrimeReact themes.
 
 ---
 
-### Path B — Themed with custom palette
+### 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
@@ -338,14 +338,14 @@ The upshot:
 Each defaults to the PrimeReact variable with the same name minus the
 `--cratis-` prefix (e.g. `--cratis-surface-card` → `var(--surface-card)`).
 
-**Choose Path B when:** you want a custom look without writing a PrimeReact
+**Use this setup when:** you want a custom look without writing a PrimeReact
 theme from scratch, you're shipping multiple palette variants (light/dark/
 brand), or you want Cratis-scoped surfaces tinted differently from PrimeReact
 widgets.
 
 ---
 
-### Path C — Fully unstyled (you own every visual)
+### Use fully unstyled mode
 
 Turn off every PrimeReact base style at the provider and supply visuals
 through PrimeReact's `pt` (pass-through) mechanism, your own CSS, or both.
@@ -470,14 +470,14 @@ per-instance overrides target the inner slot directly:
 `className` on the root — restyle their internals via the **global** `pt`
 preset.
 
-**Choose Path C when:** you have a design system to honor, you're matching a
+**Use this setup when:** you have a design system to honor, you're matching a
 brand kit, or you want zero PrimeReact CSS in the final bundle.
 
 ---
 
-### Mixing paths
+### Combining styling setups
 
-The paths compose, so you don't have to pick one for the whole app:
+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:
@@ -494,7 +494,7 @@ The paths compose, so you don't have to pick one for the whole app:
       </CratisComponentsProvider>
   </CratisComponentsProvider>
   ```
-- **Dark mode** — use Path B's palette overrides scoped to `.dark` (override
+- **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.
@@ -552,4 +552,4 @@ If using TypeScript 4.7+, try updating your `tsconfig.json`:
 
 ### Import Errors
 
-Ensure you're using the correct import paths. The package uses case-sensitive paths that match the actual component names.
\ No newline at end of file
+Ensure you're using the correct import paths. The package uses case-sensitive paths that match the actual component names.

From dd4a17f89e637c6df442d6701f2a60486212c2bf Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Sat, 30 May 2026 01:17:30 +0200
Subject: [PATCH 19/23] Type DataPage pass-through props with row type instead
 of any

The new tablePt/tablePtOptions props used PrimeDataTableProps<any>. Use
the in-scope TDataType, constraining it to object to match the inner
DataTableForQuery/DataTableForObservableQuery, removing the any hole.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 Source/DataPage/DataPage.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Source/DataPage/DataPage.tsx b/Source/DataPage/DataPage.tsx
index 6310427..3ce4226 100644
--- a/Source/DataPage/DataPage.tsx
+++ b/Source/DataPage/DataPage.tsx
@@ -179,7 +179,7 @@ function useDataPageContext(): IDataPageContext {
  * @typeParam TDataType - The row type returned by the query.
  * @typeParam TArguments - The query's argument object type, or `object` if the query takes none.
  */
-export interface DataPageProps<TQuery extends IQueryFor<TDataType> | IObservableQueryFor<TDataType>, TDataType, TArguments> {
+export interface DataPageProps<TQuery extends IQueryFor<TDataType> | IObservableQueryFor<TDataType>, TDataType extends object, TArguments> {
     /**
      * The title of the page
      */
@@ -251,10 +251,10 @@ export interface DataPageProps<TQuery extends IQueryFor<TDataType> | IObservable
     tableClassName?: string;
 
     /** PrimeReact pass-through configuration applied to the inner DataTable. */
-    tablePt?: PrimeDataTableProps<any>['pt'];
+    tablePt?: PrimeDataTableProps<TDataType[]>['pt'];
 
     /** PrimeReact pass-through options applied to the inner DataTable. */
-    tablePtOptions?: PrimeDataTableProps<any>['ptOptions'];
+    tablePtOptions?: PrimeDataTableProps<TDataType[]>['ptOptions'];
 
     /** When true, disables every base PrimeReact style on the inner DataTable. */
     tableUnstyled?: boolean;
@@ -356,7 +356,7 @@ export interface DataPageProps<TQuery extends IQueryFor<TDataType> | IObservable
  * @typeParam TArguments - The query's argument object type.
  * @param props - {@link DataPageProps}.
  */
-const DataPage = <TQuery extends IQueryFor<TDataType> | IObservableQueryFor<TDataType, TArguments>, TDataType, TArguments extends object>(props: DataPageProps<TQuery, TDataType, TArguments>) => {
+const DataPage = <TQuery extends IQueryFor<TDataType> | IObservableQueryFor<TDataType, TArguments>, TDataType extends object, TArguments extends object>(props: DataPageProps<TQuery, TDataType, TArguments>) => {
     const [selectedItem, setSelectedItem] = React.useState(undefined);
 
     const selectionChanged = (e: DataTableSelectionSingleChangeEvent<any>) => {

From 06734901eedbd47ac876094cf94e657c34d57abf Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Sat, 30 May 2026 01:17:34 +0200
Subject: [PATCH 20/23] Reattach Dialog JSDoc to its declaration

A blank line between the doc comment and the export detached it from
the symbol, dropping it from TypeDoc output and IDE hover.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 Source/Dialogs/Dialog.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Source/Dialogs/Dialog.tsx b/Source/Dialogs/Dialog.tsx
index 4df6cc0..a021d1c 100644
--- a/Source/Dialogs/Dialog.tsx
+++ b/Source/Dialogs/Dialog.tsx
@@ -196,7 +196,6 @@ export interface DialogProps {
  *
  * @param props - {@link DialogProps}.
  */
-
 export const Dialog = ({
     title,
     visible = true,

From bf3a5db0333c0915bbfd144d953f27d5617e2fb7 Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Sat, 30 May 2026 01:17:38 +0200
Subject: [PATCH 21/23] Extract repeated field error style in
 ObjectContentEditor

The validation-error <small> style was duplicated inline six times.
Hoist it into a fieldErrorStyle const alongside the other style
constants, matching the file's existing pattern.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../ObjectContentEditor/ObjectContentEditor.tsx | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/Source/ObjectContentEditor/ObjectContentEditor.tsx b/Source/ObjectContentEditor/ObjectContentEditor.tsx
index f6c917d..fe374da 100644
--- a/Source/ObjectContentEditor/ObjectContentEditor.tsx
+++ b/Source/ObjectContentEditor/ObjectContentEditor.tsx
@@ -206,6 +206,11 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
         flexShrink: 0,
     };
 
+    const fieldErrorStyle: React.CSSProperties = {
+        color: 'var(--cratis-red-500)',
+        fontSize: '0.75rem',
+    };
+
     const updateValue = useCallback((propertyName: string, newValue: Json) => {
         if (!onChange) return;
 
@@ -243,7 +248,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         checked={Boolean(value)}
                         onChange={(e) => handleChange(e.checked ?? false)}
                     />
-                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
+                    {error && <small style={fieldErrorStyle}>{error}</small>}
                 </div>
             );
         }
@@ -258,7 +263,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         useGrouping={false}
                         style={inputStyle}
                     />
-                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
+                    {error && <small style={fieldErrorStyle}>{error}</small>}
                 </div>
             );
         }
@@ -274,7 +279,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         showIcon
                         style={inputStyle}
                     />
-                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
+                    {error && <small style={fieldErrorStyle}>{error}</small>}
                 </div>
             );
         }
@@ -289,7 +294,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         showIcon
                         style={inputStyle}
                     />
-                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
+                    {error && <small style={fieldErrorStyle}>{error}</small>}
                 </div>
             );
         }
@@ -321,7 +326,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                         rows={3}
                         style={inputStyle}
                     />
-                    {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
+                    {error && <small style={fieldErrorStyle}>{error}</small>}
                 </div>
             );
         }
@@ -333,7 +338,7 @@ export const ObjectContentEditor = ({ object, timestamp, schema, editMode = fals
                     onChange={(e) => handleChange(e.target.value)}
                     style={inputStyle}
                 />
-                {error && <small style={{ color: 'var(--cratis-red-500)', fontSize: '0.75rem' }}>{error}</small>}
+                {error && <small style={fieldErrorStyle}>{error}</small>}
             </div>
         );
     };

From 99db7e3c25d8f4f4c092a39cf1c269790f22c90e Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Sat, 30 May 2026 01:56:15 +0200
Subject: [PATCH 22/23] Resolve --cratis-* tokens v11-first with v10 fallback

PrimeReact v11 (@primeuix/themes) replaces the legacy --surface-*/
--primary-* theme variables with a different token vocabulary
(--p-* primitives + semantic content/surface/text/primary tokens),
verified against the primeuix base preset.

Repoint every --cratis-* token to var(--p-<v11>, var(--<v10>)) so the
same build works on PrimeReact 10 and 11 and a 10->11 upgrade becomes a
one-file change instead of touching every component. Token names are
unchanged, so the component layer and the consumer override contract
are untouched. Where v11 has no 1:1 equivalent (surface-ground/section/
overlay, composite focus-ring) the closest durable semantic token is
used and noted inline.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 Documentation/Styling/cratis-tokens.md | 19 +++---
 Source/tokens.css                      | 82 ++++++++++++++++----------
 2 files changed, 61 insertions(+), 40 deletions(-)

diff --git a/Documentation/Styling/cratis-tokens.md b/Documentation/Styling/cratis-tokens.md
index 9d048e2..6750c57 100644
--- a/Documentation/Styling/cratis-tokens.md
+++ b/Documentation/Styling/cratis-tokens.md
@@ -1,6 +1,8 @@
 # Cratis token reference
 
-The `--cratis-*` CSS variable layer is the Cratis-scoped tint surface every Cratis wrapper reads from. Each token defaults to a matching PrimeReact theme variable via `tokens.css`, so loading a PrimeReact theme automatically gives every Cratis surface the right color without any further work.
+The `--cratis-*` CSS variable layer is the Cratis-scoped tint surface every Cratis wrapper reads from. Each token resolves the **PrimeReact v11 design token first** (`@primeuix/themes`, e.g. `--p-content-border-color`), falling back to the **legacy v10 theme variable** (e.g. `--surface-border`) via `tokens.css`. Loading any PrimeReact theme — v10 *or* v11 — therefore gives every Cratis surface the right color without any further work, and the same build keeps working across a PrimeReact 10 → 11 upgrade.
+
+This indirection is deliberate: it is the single seam that insulates your code (and your consumers' `--cratis-*` overrides) from PrimeReact's token system changing underneath you.
 
 You override `--cratis-*` tokens when you want **just** Cratis-scoped surfaces (validation error text, FormElement addon, breadcrumb borders, …) tinted independently of PrimeReact widgets. To repaint PrimeReact widgets themselves, override the PrimeReact variables directly — see [the custom palette setup](custom-palette.md).
 
@@ -22,7 +24,7 @@ Just the token declarations, with no Tailwind utilities. Use this if you bring y
 
 ## Token catalogue
 
-Each token defaults to the PrimeReact variable with the same name minus the `--cratis-` prefix (e.g. `--cratis-surface-card` → `var(--surface-card)`). Set the token to override that default.
+Each token resolves the PrimeReact v11 design token first, then the v10 legacy variable (e.g. `--cratis-surface-border` → `var(--p-content-border-color, var(--surface-border))`). v11 is not a 1:1 rename of v10 — where v11's vocabulary has no direct equivalent for a v10 concept (`surface-ground`, `surface-section`, `surface-overlay`, the composite `focus-ring`), the closest durable v11 semantic token is used (see the inline notes in `tokens.css`). Set the `--cratis-*` token to override regardless of which PrimeReact version is loaded.
 
 ### Surfaces
 
@@ -135,22 +137,23 @@ Tailwind's `@layer base` is the idiomatic spot — declare tokens once and let T
 
 ## Relationship to PrimeReact variables
 
-The Cratis token layer is **additive** on top of PrimeReact's theme system, not a replacement for it. The cascade in `tokens.css` looks like:
+The Cratis token layer is **additive** on top of PrimeReact's theme system, not a replacement for it. The cascade in `tokens.css` resolves the v11 token first, then the v10 legacy variable:
 
 ```css
 :root {
-    --cratis-surface-card: var(--surface-card);
-    --cratis-text-color:   var(--text-color);
+    /* v11 (@primeuix/themes) first, v10 legacy fallback */
+    --cratis-surface-card: var(--p-content-background, var(--surface-card));
+    --cratis-text-color:   var(--p-text-color, var(--text-color));
     /* … */
 }
 ```
 
 That means:
 
-- Override `--surface-card` (PrimeReact) → both PrimeReact widgets *and* Cratis surfaces follow.
-- Override `--cratis-surface-card` (Cratis) → only Cratis surfaces follow; PrimeReact widgets keep their existing color.
+- Repaint PrimeReact itself — on **v11** customize the preset (`definePreset` / `--p-*` tokens), on **v10** override the legacy `--surface-*` / `--text-color` variables — and both PrimeReact widgets *and* Cratis surfaces follow.
+- Override `--cratis-surface-card` (Cratis) → only Cratis surfaces follow; PrimeReact widgets keep their existing color, on either version.
 
-Use the PrimeReact variable when you want a whole-UI repaint. Use the Cratis token when you want a Cratis-specific accent that differs from PrimeReact widgets.
+Use the PrimeReact token when you want a whole-UI repaint. Use the Cratis token when you want a Cratis-specific accent that differs from PrimeReact widgets.
 
 ## See also
 
diff --git a/Source/tokens.css b/Source/tokens.css
index 1e2f145..3d82441 100644
--- a/Source/tokens.css
+++ b/Source/tokens.css
@@ -5,9 +5,23 @@
  * Cratis Components — CSS variable tokens.
  *
  * Every internal component references the --cratis-* variables defined here
- * instead of PrimeReact theme variables directly. Each token defaults to the
- * matching PrimeReact CSS variable, so when a consumer loads any PrimeReact
- * theme the components are fully themed out of the box.
+ * instead of PrimeReact's theme variables directly. This indirection is the
+ * single seam that lets the library span PrimeReact major versions: each token
+ * resolves the PrimeReact v11 design token first, falling back to the legacy
+ * v10 theme variable, so the same build works whether the consumer is on
+ * PrimeReact 10 or 11 during the upgrade window.
+ *
+ *   --cratis-surface-border: var(--p-content-border-color, var(--surface-border));
+ *                                  ^ PrimeReact v11 (@primeuix/themes)  ^ v10 legacy
+ *
+ * - Consumer on v11: the --p-* token resolves and wins.
+ * - Consumer on v10: --p-* is undefined, so the legacy --surface-* value wins.
+ *
+ * v11 is not a rename of v10 — it is a different token vocabulary (a primitive
+ * palette plus semantic content/surface/text/primary/highlight tokens). Where
+ * v11 has no 1:1 equivalent for a v10 concept (surface-ground / surface-section
+ * / surface-overlay / the composite focus-ring), the closest durable v11
+ * semantic token is used and noted inline; consumers can always override.
  *
  * To take full control of the look and feel (with or without PrimeReact's
  * unstyled / pt mechanism, Tailwind, or your own CSS), override the relevant
@@ -18,48 +32,52 @@
  *       --cratis-text-color:   #f3f4f6;
  *   }
  *
- * Tokens are intentionally fallback-free — if neither a PrimeReact theme nor
- * a consumer override is present, the variable resolves to nothing and the
- * affected rule no-ops. That keeps the library theme-agnostic without
- * imposing a default palette on consumers.
+ * Tokens are intentionally fallback-free at the end of the chain — if neither a
+ * PrimeReact theme (v10 or v11) nor a consumer override is present, the variable
+ * resolves to nothing and the affected rule no-ops. That keeps the library
+ * theme-agnostic without imposing a default palette on consumers.
  */
 
 :root {
     /* Surfaces */
-    --cratis-surface-0:        var(--surface-0);
-    --cratis-surface-100:      var(--surface-100);
-    --cratis-surface-ground:   var(--surface-ground);
-    --cratis-surface-section:  var(--surface-section);
-    --cratis-surface-card:     var(--surface-card);
-    --cratis-surface-overlay:  var(--surface-overlay);
-    --cratis-surface-hover:    var(--surface-hover);
-    --cratis-surface-border:   var(--surface-border);
+    --cratis-surface-0:        var(--p-surface-0, var(--surface-0));
+    --cratis-surface-100:      var(--p-surface-100, var(--surface-100));
+    /* v11 has no page-canvas/section token — map to the neutral content surface;
+     * separation in v11 comes from borders (content-border-color), not fills. */
+    --cratis-surface-ground:   var(--p-content-background, var(--surface-ground));
+    --cratis-surface-section:  var(--p-content-hover-background, var(--surface-section));
+    --cratis-surface-card:     var(--p-content-background, var(--surface-card));
+    /* v11 splits overlay backgrounds by type — use the modal surface as the general overlay. */
+    --cratis-surface-overlay:  var(--p-overlay-modal-background, var(--surface-overlay));
+    --cratis-surface-hover:    var(--p-content-hover-background, var(--surface-hover));
+    --cratis-surface-border:   var(--p-content-border-color, var(--surface-border));
 
     /* Text */
-    --cratis-text-color:           var(--text-color);
-    --cratis-text-color-secondary: var(--text-color-secondary);
+    --cratis-text-color:           var(--p-text-color, var(--text-color));
+    --cratis-text-color-secondary: var(--p-text-muted-color, var(--text-color-secondary));
 
     /* Primary brand */
-    --cratis-primary-color:      var(--primary-color);
-    --cratis-primary-color-text: var(--primary-color-text);
-    --cratis-primary-300:        var(--primary-300);
-    --cratis-primary-400:        var(--primary-400);
-    --cratis-primary-500:        var(--primary-500);
-    --cratis-primary-600:        var(--primary-600);
+    --cratis-primary-color:      var(--p-primary-color, var(--primary-color));
+    --cratis-primary-color-text: var(--p-primary-contrast-color, var(--primary-color-text));
+    --cratis-primary-300:        var(--p-primary-300, var(--primary-300));
+    --cratis-primary-400:        var(--p-primary-400, var(--primary-400));
+    --cratis-primary-500:        var(--p-primary-500, var(--primary-500));
+    --cratis-primary-600:        var(--p-primary-600, var(--primary-600));
 
     /* Highlight / selection */
-    --cratis-highlight-bg:         var(--highlight-bg);
-    --cratis-highlight-text-color: var(--highlight-text-color);
+    --cratis-highlight-bg:         var(--p-highlight-background, var(--highlight-bg));
+    --cratis-highlight-text-color: var(--p-highlight-color, var(--highlight-text-color));
 
-    /* Semantic accents */
-    --cratis-green-500:  var(--green-500);
-    --cratis-orange-500: var(--orange-500);
-    --cratis-red-500:    var(--red-500);
+    /* Semantic accents (primitive palette) */
+    --cratis-green-500:  var(--p-green-500, var(--green-500));
+    --cratis-orange-500: var(--p-orange-500, var(--orange-500));
+    --cratis-red-500:    var(--p-red-500, var(--red-500));
 
     /* Geometry */
-    --cratis-border-radius: var(--border-radius);
+    --cratis-border-radius: var(--p-content-border-radius, var(--border-radius));
 
     /* Effects */
-    --cratis-focus-ring: var(--focus-ring);
-    --cratis-maskbg:     var(--maskbg);
+    /* v11 decomposes the focus ring; --p-focus-ring-shadow is the box-shadow form. */
+    --cratis-focus-ring: var(--p-focus-ring-shadow, var(--focus-ring));
+    --cratis-maskbg:     var(--p-mask-background, var(--maskbg));
 }

From e73698940bc7fb0bc28dad20d34859e84ce94dfc Mon Sep 17 00:00:00 2001
From: woksin <sindrewilting@gmail.com>
Date: Sat, 30 May 2026 02:07:07 +0200
Subject: [PATCH 23/23] Document PrimeReact 10/11 token compatibility in
 styling guides
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Explain that the --cratis-* layer resolves PrimeReact v11 design tokens
(@primeuix/themes) first and falls back to v10, so the same build works
across both majors. Updates the styling overview's mental model, adds a
PrimeReact-version note to the custom-palette guide, and adds a
'PrimeReact 10 and 11' section to the migration guide — with the scope
caveat that full v11 component/pt-slot support is a separate follow-up.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 Documentation/Styling/custom-palette.md |  2 ++
 Documentation/Styling/index.md          |  8 +++++---
 Documentation/migration.md              | 13 ++++++++++++-
 3 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/Documentation/Styling/custom-palette.md b/Documentation/Styling/custom-palette.md
index 809da26..c9453bc 100644
--- a/Documentation/Styling/custom-palette.md
+++ b/Documentation/Styling/custom-palette.md
@@ -4,6 +4,8 @@ You want PrimeReact's chrome — its dialog frames, button shapes, focus rings,
 
 This setup keeps a PrimeReact theme as the **structural baseline** and overrides PrimeReact's own CSS variables on `:root` to repaint the whole UI. The `--cratis-*` tokens follow along through `tokens.css`'s cascade, so Cratis-scoped surfaces stay in sync. You can also override the Cratis tokens independently when you want Cratis surfaces to differ from PrimeReact widgets.
 
+> **PrimeReact version note.** The examples below override PrimeReact **v10** theme variables (`--surface-*`, `--primary-color`, …). On **PrimeReact v11**, customize the palette through `@primeuix/themes` instead — define a preset with `definePreset` (or override the `--p-*` design tokens). Either way you don't touch the `--cratis-*` layer: it resolves the v11 design token first and falls back to the v10 variable, so Cratis-scoped surfaces follow your palette on both majors.
+
 ## Setup
 
 ```tsx
diff --git a/Documentation/Styling/index.md b/Documentation/Styling/index.md
index 1e789aa..b015d75 100644
--- a/Documentation/Styling/index.md
+++ b/Documentation/Styling/index.md
@@ -16,16 +16,18 @@ All three setups use the same one-line setup described in [Getting Started](gett
 
 ## Why the first two options still load a PrimeReact theme
 
-In PrimeReact 10 every widget's *structural* CSS — padding, borders, dialog frame, focus rings, button shapes — ships **inside the theme file**. There is no separate primitives stylesheet. So a setup without any PrimeReact theme has no widget chrome at all and components render as the raw HTML primitives the browser supplies by default.
+In PrimeReact 10 every widget's *structural* CSS — padding, borders, dialog frame, focus rings, button shapes — ships **inside the theme file**. There is no separate primitives stylesheet. So a setup without any PrimeReact theme has no widget chrome at all and components render as the raw HTML primitives the browser supplies by default. PrimeReact 11's styled mode (`@primeuix/themes`) works the same way — the active preset supplies the chrome — so the reasoning here is unchanged across versions.
 
 The `--cratis-*` token layer is an additive Cratis-scoped tint for surfaces the wrappers in this package own — validation error text, the FormElement addon background, breadcrumb borders — and **is not, by itself, sufficient to skin PrimeReact widgets**. Override PrimeReact's variables when you want the whole UI in your palette. Use `unstyled: true` and a `pt` preset when you want to replace PrimeReact's visuals entirely.
 
+The token layer is **version-spanning**: each `--cratis-*` token resolves the PrimeReact v11 design token (`@primeuix/themes`) first and falls back to the v10 theme variable, so the same build of this package is themed correctly whether your app is on PrimeReact 10 or 11. (Note: this covers the *theming* surface only — full PrimeReact 11 component/`pt`-slot compatibility is tracked separately.)
+
 ## Mental model
 
 Every component you import from `@cratis/components` is a thin wrapper around a PrimeReact component plus a few Cratis additions (validation hooks, command-form integration, …). Styling flows in three layers:
 
-1. **PrimeReact theme variables** — `--surface-card`, `--text-color`, `--primary-color`, … Read directly by PrimeReact widgets. Override these to repaint the whole UI.
-2. **Cratis tokens** — `--cratis-surface-card`, `--cratis-text-color`, `--cratis-primary-color`, … Read only by Cratis-scoped surfaces. Default to the matching PrimeReact variable via cascade in `tokens.css`. Override these when you want a Cratis surface tinted differently from the surrounding PrimeReact widgets.
+1. **PrimeReact theme tokens** — on v10 the theme variables `--surface-card`, `--text-color`, `--primary-color`, …; on v11 the `@primeuix/themes` design tokens (`--p-*`, customized via `definePreset`). Read directly by PrimeReact widgets. Override these to repaint the whole UI.
+2. **Cratis tokens** — `--cratis-surface-card`, `--cratis-text-color`, `--cratis-primary-color`, … Read only by Cratis-scoped surfaces. In `tokens.css` each resolves the PrimeReact v11 design token (e.g. `--p-content-border-color`) first and falls back to the v10 theme variable (e.g. `--surface-border`), so they stay in sync with the loaded PrimeReact theme on either major. Override these when you want a Cratis surface tinted differently from the surrounding PrimeReact widgets.
 3. **PrimeReact `pt` (pass-through)** — A per-component prop that lets you attach CSS class names (or inline styles) to every slot inside a PrimeReact widget. The strongest customization knob; works hand-in-hand with `unstyled` mode.
 
 The [Cratis token reference](cratis-tokens.md) lists every token and the surface it tints. The [pass-through cheat sheet](pass-through.md) lists every Cratis wrapper and which pt props it exposes.
diff --git a/Documentation/migration.md b/Documentation/migration.md
index b5932e8..b543bb8 100644
--- a/Documentation/migration.md
+++ b/Documentation/migration.md
@@ -299,7 +299,18 @@ Wrappers that compose more than one PrimeReact widget expose explicit per-slot p
 
 ### `--cratis-*` token layer
 
-A scoped Cratis token layer is now part of every install. Tokens default to the PrimeReact theme variable with the same name minus the `--cratis-` prefix, so theme-based setups continue to look the way they always did. Override `--cratis-*` only when you want a Cratis-scoped surface tinted independently of the surrounding PrimeReact widgets — see [Cratis token reference](Styling/cratis-tokens.md).
+A scoped Cratis token layer is now part of every install. Each token resolves the PrimeReact v11 design token (`@primeuix/themes`) first and falls back to the matching v10 theme variable, so theme-based setups continue to look the way they always did on either PrimeReact major. Override `--cratis-*` only when you want a Cratis-scoped surface tinted independently of the surrounding PrimeReact widgets — see [Cratis token reference](Styling/cratis-tokens.md).
+
+### PrimeReact 10 and 11 — one build, both majors
+
+The `--cratis-*` token layer is version-spanning by design. Every token is declared as `var(--p-<v11-token>, var(--<v10-variable>))`, so:
+
+- On **PrimeReact 10**, the `--p-*` design tokens are undefined and the legacy `--surface-*` / `--primary-*` / `--text-color` values win.
+- On **PrimeReact 11**, the `@primeuix/themes` `--p-*` tokens resolve and win.
+
+The same build of `@cratis/components` is therefore themed correctly on both majors, and a PrimeReact 10 → 11 upgrade in your app needs **no change** to how Cratis components pick up your theme. PrimeReact 11 is not a rename of 10 — it uses a different token vocabulary — so where v11 has no direct equivalent for a v10 concept (`surface-ground` / `surface-section` / `surface-overlay`, the composite `focus-ring`), the closest durable v11 semantic token is used; the inline notes in `tokens.css` record each mapping.
+
+> **Scope:** this makes the **theming** surface forward-compatible — the most pervasive part of a PrimeReact upgrade. It does **not** make the library fully PrimeReact 11-compatible: v11 also changes component prop APIs and `pt` slot names, so per-slot `pt` presets will need revisiting when the `primereact` peer range is widened to allow v11. That work is tracked separately; the `primereact` peer is still `^10.9.0` today.
 
 ### Storybook styling toolbar