@qoretechnologies/reqraft 0.10.25 → 0.10.26

package/.claude/CLAUDE.md

@@ -1,4 +1,36 @@
-# ReQraft AI Coding Agent Instructions
+@~/Projects/instruction-files/CLAUDE.md
+@~/Projects/instruction-files/stacks/frontend/FRONTEND.md
+
+# ReQraft (toolkit-react) — Claude entry point
+
+## Shared Qore rules (READ FIRST)
+
+The two `@`-imports above load the shared rules from the **instruction-files**
+repo: the org-wide baseline (`CLAUDE.md`) and the frontend ruleset
+(`stacks/frontend/FRONTEND.md`) — git safety, commit conventions, CI
+monitoring, `/audit`, the Reqore-first rule, the Storybook + Qlip visual-change
+flow, story descriptions, and more. Those files point on to
+`stacks/frontend/BRAND_DESIGN.md` for brand / UI-design decisions (read it
+before building any visual surface). **Everything below this section is
+specific to ReQraft (toolkit-react).**
+
+**If the imports above did not load** — you don't see the shared rules because
+this repo is cloned somewhere other than `~/Projects/instruction-files` — find
+the shared repo before doing any frontend work:
+
+1. Check for a gitignored **`.instruction-files-path`** file at this repo's
+   root. If it exists, read the path `P` from it, then read `P/CLAUDE.md` and
+   `P/stacks/frontend/FRONTEND.md` (+ `P/stacks/frontend/BRAND_DESIGN.md` for
+   UI work) and follow them.
+2. Otherwise locate the `instruction-files` repo on disk (try
+   `~/Projects/instruction-files`, then your other project roots). If found at
+   `P`, write `P` into `.instruction-files-path` (create it — it's gitignored)
+   so future sessions skip the search, then read the files above.
+3. If it isn't cloned anywhere, **STOP and ask the user to clone it**:
+   `git clone git@github.com:qoretechnologies/instruction-files.git ~/Projects/instruction-files`
+   Do not proceed with frontend work until the shared rules are loaded.
+
+# ReQraft (toolkit-react) — project-specific rules
 
 ## Project Overview
 
@@ -12,22 +44,12 @@ ReQraft (`@qoretechnologies/reqraft`) is a **React hooks and components toolkit*
 - **Styling:** styled-components (inherited from ReQore); no CSS modules
 - **State Management:** zustand (stores) + React Context (`use-context-selector`)
 - **Data Fetching:** `@tanstack/react-query` v4 (via `query()` util + `useFetch` hook)
-- **Testing:** Jest + React Testing Library (tests in `__tests__/`)
+- **Testing:** Vitest — a `unit` project (jsdom, tests in `__tests__/`) + a `storybook` project (every story run in a real Chromium browser via Playwright); React Testing Library for component assertions
 - **Documentation:** Storybook (stories co-located in `src/` with `.stories.tsx` suffix)
 - **Storybook port:** `6008` (not 6007 — that's reqore)
 
 ## Architecture Essentials
 
-### General Development Practices
-
-- Focus on user experience and performance first; complexity and tech debt are secondary
-- Follow existing code patterns; refer to similar hooks/components for guidance
-- Check if a helper or utility already exists before writing a new one
-- Use TypeScript with strict typing; prefix interfaces with `I` and types with `T`
-- Always use named exports for React components and hooks
-- Use functional components with React hooks; wrap in `memo()` unless there's a reason not to
-- Wrap callbacks in `useCallback()` and computed values in `useMemo()` unless there's a reason not to
-
 ### Provider Stack (`src/providers/`)
 
 The app must be wrapped in `ReqraftProvider` (or initialized via `initializeReqraft()`):
@@ -133,7 +155,9 @@ A generic `<Field>` component dispatches to the appropriate field by type.
 ```bash
 yarn install
 yarn storybook          # Dev mode on http://localhost:6008
-yarn test:watch         # Jest watch mode
+yarn test               # Vitest unit tests (jsdom)
+yarn test:watch         # Vitest unit watch mode
+yarn test:stories       # Story / interaction tests in a real browser (+ Qlip capture)
 yarn lint               # ESLint check
 yarn build              # TypeScript compilation (tsconfig.prod.json)
 yarn build:test         # Type-check without emit
@@ -145,25 +169,32 @@ yarn build:test         # Type-check without emit
 - `pre-push` hook enforces: `build:test:prod`, `lint`, `test`
 - Branch naming: always start with the issue number, e.g. `feature/49_pooled-connections`
 
+### Versioning — every PR to `develop` MUST bump the version
+
+`.github/workflows/beta_release.yml` runs on **every push to `develop`** and publishes to NPM using whatever `version` is in `package.json` at push time. A merge without a bump therefore tries to re-publish an already-published version and **fails** (NPM refuses to re-publish). This applies to **every** PR — features, fixes, chores, and docs-only changes alike. There is no exception.
+
+- Bump the **patch** for an ordinary PR while in beta (pre-1.0) — e.g. `0.10.9` → `0.10.10`. Do NOT bump minor/major for ordinary feature/fix PRs.
+- Bump in `package.json` only (no git tag): `npm version patch --no-git-tag-version`, and include the bump in the PR's commit.
+- If another PR bumps to the same version before yours merges, rebase and bump again — the version at merge time must be strictly greater than the last published one.
+
 ### Testing Patterns
 
-- Tests live in `__tests__/` (mirror `src/` structure)
-- Wrap tests with `ReqraftProvider` (or at minimum `QueryClientProvider`)
+- Two Vitest projects (see `vitest.config.ts`): **unit** (jsdom; tests in `__tests__/`, mirroring `src/`) and **storybook** (every `*.stories.tsx` run in a real Chromium browser via Playwright). There is no Jest.
+- Wrap unit tests with `ReqraftProvider` (or at minimum `QueryClientProvider`)
 - Use `mock-socket` for WebSocket testing
-- Run: `./node_modules/.bin/jest --passWithNoTests`
+- Run: `yarn test` (unit) · `yarn test:stories [file-substring]` (stories) · `yarn precheck` (lint + unit + `build:test:prod`)
 
-### Storybook Stories
+### Storybook Stories & visual testing
 
 - Stories are co-located alongside source: `src/hooks/useFetch/useFetch.stories.tsx`
 - Storybook port: **6008**
-- Visual testing via Chromatic (`yarn chromatic`)
+- Story + interaction tests run on **Vitest browser mode** (Playwright/Chromium): `yarn test:stories [file-substring]`. Run `yarn install-playwright` once first.
+- **Visual regression via Qlip** (not Chromatic): the story run captures snapshots through the `qlip` Vitest plugin. Upload is gated on `QLIP_UPLOAD_TOKEN` (`vitest.config.ts`), so **local runs capture but never upload** — PNGs land in `qlip/screenshots/<ts>/stories/auto/<StoryId>.png` (gitignored); read the PNG to verify a visual change. CI (`.github/workflows/tests.yml`) sets the token and uploads a build for dashboard review. The full visual-change flow + the `qlip` MCP review skill live in the imported `stacks/frontend/FRONTEND.md`.
 
 ## Code Patterns & Conventions
 
 ### Naming
 
-- Interfaces: `I` prefix (e.g., `IReqraftUseFetch`)
-- Types: `T` prefix (e.g., `TReqraftMenu`)
 - Enums: PascalCase (e.g., `ReqraftWebSocketStatus`)
 - Hooks: `useReqraft*` prefix
 - Providers: `Reqraft*Provider`
@@ -240,11 +271,9 @@ yarn build:test         # Type-check without emit
 | `src/components/log/` | Log display component |
 | `src/components/menu/` | Navigation menu component |
 | `src/types/` | Shared TypeScript types |
-| `__tests__/` | Jest tests |
+| `__tests__/` | Vitest unit tests (jsdom) |
 
 ## Other
 
-- You may need to source zsh to get some commands (like `gh`) working: `source ~/.zshrc`
-- Branch naming convention: `feature/<issue-number>_<short-description>` (e.g., `feature/49_pooled-connections`)
 - This library is a **peer-dependency consumer** of ReQore — do not copy ReQore internals here; import from `@qoretechnologies/reqore` instead
 - `yarn update-reqore` updates ReQore to the latest beta

package/design/COMPACT_ENGINE_REDESIGN.md

@@ -0,0 +1,156 @@
+# Compact FormEngine → "Focus" redesign — migration plan
+
+**Goal:** make the real Compact FormEngine *look* like the `Focus` variant
+prototype (`src/components/form/engine/variants/VariantFocus.tsx`) while keeping
+**100% of its current functionality** and a **green story/test suite**.
+
+**Principle (the user's, and the right one):** _bring our design to the engine,
+not the engine's functionality to our design._ We re-skin the working engine. We
+do **not** rebuild validation, dependent-reset, templates/`on_change`, operators,
+`arg_schema` nesting, focused editing, or draft/commit into the prototype.
+
+The engine is already visually sophisticated and already owns every hard piece:
+
+| Capability | Where it already lives |
+|---|---|
+| Status/intent per row | `CompactRow.tsx` `worstIntent` / `intentColor` / `rowStripeColor` (≈L533, L996) → painted via `--readfirst-stripe` |
+| Sticky glass header | `compactRowStyles.ts` `StyledCompactPanel` + FormEngine scroll-wrap `position: sticky` (≈L193) |
+| Revert-to-loaded | `CompactRow` `revertButton` `.options-readfirst-revert` (L423) |
+| Clear value | `CompactRow` `clearValueButton` `.options-readfirst-clear` (L460) |
+| Focused (fullscreen) editing | `CompactRow` `.options-readfirst-fullscreen` → `setFocusedEditing` → `<FocusedEditing>` (L820, L852) |
+| Dependency lock + nav | `CompactRow` `dependsOnChip` `.options-readfirst-lock-deps` (L922) |
+| Required one-of groups | rail + cluster nodes (`readfirst-cluster-*`, `.options-readfirst-node`) |
+| short_desc inline | `.options-readfirst-label-desc` (revealed by ⓘ `.options-readfirst-info-toggle`) |
+| long desc | `?` help `.options-readfirst-help` + `<Description>` inside `FocusedEditing` |
+
+So this redesign is mostly **subtractive** (flatten the recessed value surface +
+intent stripe → calm flat rows) plus **one structural move** (re-group fields
+into the Needs-attention / Set / Optional boxes, each carrying thin schema-group
+labels) plus **one viz swap** (the required-group rail → the "One of the below is
+required" cluster box).
+
+---
+
+## Answers to the five questions
+
+### 1. How do we show `desc` (long description)?
+Unify the two existing description affordances:
+
+- **`short_desc`** → the toolbar **Descriptions toggle** (icon-only, `info`
+  intent when active — exactly the prototype's button), mapped to the engine's
+  existing `showAllDescriptions`. Renders inline under the field name via
+  `.options-readfirst-label-desc`. The per-field ⓘ stays as a local override.
+- **`desc` (long, markdown)** → stays where you actually read/edit the field:
+  rendered by `<Description longDescriptionShownByDefault>` inside
+  **FocusedEditing**, plus the quick `?` help (`.options-readfirst-help`). No
+  second always-on description button in the row.
+
+### 2. Dependent fields / fields with dependents?
+Engine already models both — we restyle, not rebuild:
+
+- **Disabled-by-dependency** (`depends_on` unmet): keep the **lock + "Depends on"
+  navigable chip** (`.options-readfirst-lock-deps`); clicking a blocker flashes
+  it (`readfirst-row-flash`). These are a distinct **blocked** state — neither
+  todo/set/optional — so they render **dimmed in place in their schema group**
+  (not pulled into Needs-attention; you can't act on them yet).
+- **Fields with dependents**: no read-first badge needed (the engine resets
+  dependents on change). Optional later nicety: an "affects N fields" hint while
+  editing.
+
+### 3. Optional fields wrapper (basic dark)
+The `optional` group (everything `getOptionGroup` routes there — non-preselected,
+non-required, unset) renders in a **collapsible box like the others but a neutral
+/ dark tint** (not amber/green), collapsed by default. Same `ReqorePanel`
+treatment as Set, different intent.
+
+### 4. Focused editing / reset-to-default / clear
+Keep the engine's existing edit-card actions, restyled to match:
+- **Focused editing** (`.options-readfirst-fullscreen` → `<FocusedEditing>`) — unchanged.
+- **Clear value** (`.options-readfirst-clear`) — unchanged.
+- **Revert** (`.options-readfirst-revert`) reverts to the *loaded* value.
+- **NEW: reset-to-default** — `handleValueChange(name, schema.default_value)`,
+  shown only when `default_value` exists and differs. Small addition.
+
+### 5. Sticky header (search + progress)
+Already sticky (`StyledCompactPanel` + the owned scroll context). The redesign
+keeps it; the `CompactToolbar` (completion meter + filter + Descriptions toggle +
+Fields menu) stays pinned. Only its contents/skin change.
+
+---
+
+## Visual-delta map (Focus feature → engine change → test impact)
+
+Legend: **🟢 safe** = CSS-only / additive, no tested DOM·text·interaction change.
+**🟡 needs test updates** = changes asserted text/structure; update listed play
+functions and re-run `test:stories`.
+
+| # | Focus feature | Engine change | File · symbol | Impact |
+|---|---|---|---|---|
+| 1 | Calm flat rows (no recessed surface, no intent stripe) | drop/soften the value-surface `::before` + `border-left` stripe | `compactRowStyles.ts` `StyledGroupBody > *::before` | 🟢 safe |
+| 2 | Status **dot** (one mark, colour = severity) | render a dot from `rowStripeColor`/`worstIntent`; additive element | `CompactRow.tsx` (row label cell) + styles | 🟢 safe (additive class, no removed hooks) |
+| 3 | Thin uppercase group labels | restyle the group header (name → 10px/upper/letter-spaced; drop hairline+chip or calm them) | `FormEngine.tsx` group render + `StyledGroupHeader`/`StyledGroupHeaderLine` | 🟢 mostly (verify no story asserts the chip text) |
+| 4 | Empty value shows `—` not "Not set" | swap the empty-value copy | `CompactRow.tsx` value render | 🟡 7 assertions use `Not set` |
+| 5 | Needs-attention / Set / Optional **boxes** (status grouping, schema labels inside) | regroup: bucket rows by status across schema groups; render 3 `ReqorePanel`s; thin schema labels within | `FormEngine.tsx` group-render loop | 🟡 group-structure & badge ("N to resolve") assertions |
+| 6 | "One of the below is required" **cluster box** | replace rail + cluster nodes with the cluster box | `CompactRow.tsx` cluster nodes/rail + `compactRowStyles.ts` `readfirst-cluster-*`, `StyledClusterNode` | 🟡 `Covered by` / `Covers` / `One of` assertions |
+| 7 | Neutral/dark Optional wrapper | intent/skin on the optional `ReqorePanel` | `FormEngine.tsx` | 🟢 safe |
+| 8 | reset-to-default action | new button calling `handleValueChange(name, default_value)` | `CompactRow.tsx` | 🟢 additive |
+
+**Use Reqore throughout** — `ReqorePanel` (boxes/collapsible), `ReqoreControlGroup`,
+`ReqoreInput`, `ReqoreButton`, `ReqoreTag`, `ReqoreIcon`, `ReqoreCollapsibleContent`,
+`useReqoreTheme` for every colour. No bespoke widgets where a Reqore one fits.
+
+---
+
+## Phased plan (each phase ends green)
+
+- **P1 — Calm re-skin. ✅ DONE + validated.** Flattened the recessed value
+  surface + intent stripe (`StyledGroupBody > *::before` now transparent) and
+  added the trailing **status dot** (`StyledStatusDot`, derived from
+  `worstIntent`/`empty`/`required`/`coveredByLabel`/`groupResolved`). CSS +
+  additive DOM only — every test hook preserved. **Validated: `FormEngine.stories.tsx`
+  = 68 pass / 1 pre-existing fail ("Option With Any Type"), no new failures;**
+  `build:test` + `eslint` green; visually confirmed on :6008. *(Thin group labels
+  deferred to P3, where the group headers change anyway.)*
+
+  > **Validation harness (important):** `vitest run --project storybook <file>`
+  > runs stories in headless chromium and does **NOT** spawn a server on :6008 —
+  > a live `yarn storybook` is untouched. So every phase below is validatable
+  > without disturbing a running Storybook.
+- **P3 — Status boxes. ✅ DONE + validated.** Regrouped into **Needs attention /
+  Set / Optional** boxes (intent-tinted `ReqorePanel`s), each with thin schema
+  sub-labels (`StyledStatusBoxGroupLabel`); neutral Optional. Key decisions:
+  - **One shared status helper** (`getReadFirstStatus`/`getReadFirstBucket` in
+    `readFirst.ts`) drives BOTH the row dot and the box bucket — they can't disagree.
+  - **One-of required-group members travel together** (bucket the whole group by
+    its satisfaction) so the existing rail + "One of"/"Covers"/"Covered by" chips
+    stay intact. Rail→cluster-box swap deferred to P4.
+  - **Freeze-while-editing** (`settledBucket` ref keyed by option, gated on
+    `expandedOptions`): an edited field — or any member of an edited one-of group —
+    keeps its box until the edit ends, so a status flip can't remount it mid-edit
+    and steal focus. (This fixed a real regression the suite guards.)
+  - Only **one** test legitimately changed (sort order is now status-first).
+  - **Validated: 68 pass / 1 pre-existing fail.** Visually confirmed on :6008.
+- **P2 — Copy + empty state (🟡).** `Not set` → `—  <reason>`. Update the ~10
+  assertions (`Not set` ×7, `Required — not set`, `Not in form — add`, covered-by).
+- **P4 — Required cluster (🟡).** Rail → cluster box. Update `Covered by`/`Covers`/
+  `One of` assertions.
+- **P5 — Polish.** reset-to-default action, depends-on dimmed-in-place styling,
+  responsive pass, qlip/Chromatic re-baseline.
+
+---
+
+## Test-impact appendix (the audit)
+
+`test:stories` runs `vitest run --project storybook`, and the storybook-vitest
+plugin's `storybookScript` is `yarn storybook --no-open` → it wants **:6008**,
+which collides with a running `yarn storybook`. **To validate without disturbing a
+live :6008**, run the suite against a separate port (temporarily point the dev
+script / `storybookScript` at e.g. :6010, or stop the live instance first).
+
+Asserted strings that constrain changes (must be preserved, or the test updated):
+`Not set` (×7), `Required — not set`, `Covered by "…"`, `Covers`, `Draft`,
+`Focused Editing`, `Description`, type labels (`<string>`, `<rgbcolor>`),
+`N to resolve` group badges, `1 unsaved change`, plus the class/`data-field`
+hooks listed in the table above. Preserve every `options-readfirst-*` /
+`readfirst-*` class that a play function queries; restyle via CSS rather than
+renaming.

package/design/FORM_ENGINE_COMPACT_UX_PLAN.md

@@ -0,0 +1,353 @@
+# FormEngine Compact — UX Improvement Plan
+
+> Status: **proposal / for review.** Nothing here is implemented yet.
+> Scope: the compact ("read-first") `FormEngine` that will replace the classic
+> engine in the IDE. Goal: keep its density but make it feel **calm, scannable,
+> and guiding** instead of crowded and alarming.
+
+---
+
+## 0. TL;DR
+
+The compact engine's *information architecture is right* (read-first rows you
+drill into). What's wrong is **visual signal management**: it currently runs
+**five overlapping status systems at once** and treats *untouched draft fields*
+as **hard red errors**. The result reads like a form that's on fire when it's
+actually just unfinished.
+
+Three changes do ~80% of the work:
+
+1. **Collapse the 5 status systems into 1.** One global completion signal at the
+   top; demote/remove the redundant red banner and the per-group/per-row status
+   pills.
+2. **Reframe "errors" as "to-dos."** Don't show red validation errors on fields
+   the user hasn't touched. *Unset ≠ error.* Validate on interaction/submit.
+3. **Lock a strict one-line row template** and push everything variable
+   (descriptions, error reasons, nested previews, default hints) **behind
+   progressive disclosure**. One scannable line per field by default.
+
+Everything else (calmer value chips, less chrome, smarter ordering, a "what's
+next" path) compounds these.
+
+---
+
+## 1. North star
+
+> A configuration **summary you can read top-to-bottom in seconds**, that quietly
+> tells you *what's done, what's left, and what to do next* — and gets out of the
+> way when you're just scanning.
+
+The audience is technical (developers configuring Qorus interfaces). They *want*
+density — the model is a **good data table / code editor**, not a consumer
+wizard. So the goal is **"calm density,"** not fewer fields. Think: the
+difference between a well-set spreadsheet and a ransom note.
+
+---
+
+## 2. What's wrong today (diagnosis)
+
+Grounded in the screenshots + the implementation
+([`CompactToolbar.tsx`](../src/components/form/engine/CompactToolbar.tsx),
+[`CompactRow.tsx`](../src/components/form/engine/CompactRow.tsx),
+[`FormEngine.tsx`](../src/components/form/engine/FormEngine.tsx),
+[`compactRowStyles.ts`](../src/components/form/engine/compactRowStyles.ts)).
+
+### 2.1 Five competing status systems
+At one glance the user is shown completeness/validity **five different ways**:
+
+| # | System | Where | Code |
+|---|--------|-------|------|
+| 1 | Draft badge + `12/21 fields set` + progress bar + `57%` | header | `CompactToolbar` `StyledCompletion` |
+| 2 | Red banner: "6 fields are not valid… click to only show invalid" | header | `CompactToolbar` invalid banner |
+| 3 | Per-group pills: `4 OPTIONAL`, `5 TO RESOLVE` | group headers | `FormEngine.tsx:1973` |
+| 4 | Per-row red stripe + red ⓘ button + inline red message box | each invalid row | `CompactRow` tier-1 `StyledInfoPanel` |
+| 5 | Per-row Draft chip / required asterisk / ⓘ toggle | each row | `CompactRow` `draftChip`, asterisk |
+
+These don't reinforce — they **compete**. The user can't tell which is the
+"real" status, so the whole UI reads as urgent. (NN/g *Aesthetic & minimalist
+design*: every extra unit of status dilutes the rest.)
+
+### 2.2 Premature, alarmist validation
+The form is in **DRAFT**, yet untouched fields show **hard red errors** —
+"Text value is empty," "Hash arguments are invalid," "Required — not set." Two
+problems:
+
+- **Unset is not an error.** Showing red on fields the user hasn't even reached
+  punishes them for not-yet-doing-something. This is the single biggest driver
+  of the "overwhelming" feeling. (Baymard / NN/g on inline validation: validate
+  **on blur or on submit**, not aggressively on load; reserve red for *wrong*,
+  not *empty*.)
+- **The error chrome is layout-disruptive.** Full-width dark-red `ReqoreMessage`
+  boxes render *between rows*, shoving content down and shattering the table
+  rhythm that makes the form scannable. Six of them = a wall of red.
+
+### 2.3 No focal point / flat hierarchy
+Every row carries roughly equal visual weight; labels, values, blue chips,
+swatches, nested trees and error boxes all shout at the same volume. There's no
+"look here first," no obvious **next action**. The eye bounces. (Visual
+hierarchy via size/weight/colour/space is absent within the row grid.)
+
+### 2.4 Inconsistent row anatomy breaks scannability
+Rows are one line (`Option with value · 123`), or two (label + sub-description),
+or three+ (label + value + inline error box), or have an embedded object tree
+with "Show more." The **grid rhythm** — the thing that makes a dense list
+scannable — is constantly broken by inline variants rendered **by default**.
+
+### 2.5 The value column has no consistent visual language
+Plain text, **saturated-blue template chips** (`Test (local)`, `Richtext
+Template`), colour swatch + hex, file pill, nested data tree — each a different
+weight and colour. The blue chips in particular are *louder than the field
+labels*, so decoration outshouts meaning. (Tufte: colour should encode data, not
+ornament.)
+
+### 2.6 Heavy non-data "chrome"
+Recessed value surfaces, intent stripes, group spines, required-group rails,
+dividers, hover fills — a lot of subtle lines/fills create a **busy texture**
+before any content is read. (Tufte *data-ink ratio*: most separators could be
+whitespace.)
+
+### 2.7 Weak grouping semantics
+"General" is a vague catch-all; "Optional/General" isn't a meaning the user
+reasons with. 21 fields in 2 buckets, ordered by schema, with no
+prioritisation. Findability relies on the filter box.
+
+---
+
+## 3. Principles we'll design to
+
+| Principle | Source | Applied here |
+|---|---|---|
+| **One primary status channel** | NN/g *Visibility of system status* + *Minimalist design* | Collapse 5 status systems → 1 meter |
+| **Validate at the right time** | Baymard; NN/g *Error prevention* | Unset ≠ error; validate on blur/submit |
+| **Severity = colour, not area** | Tufte; Material/Carbon error patterns | Replace red boxes with a dot/accent |
+| **Progressive disclosure** | NN/g | One line per row; reveal the rest on demand |
+| **Data-ink ratio** | Tufte | Whitespace > borders for separation |
+| **Recognition over recall** | NN/g | Read-first rows (already good) — keep |
+| **Chunking ~5–7** | Miller's law | Smaller, purpose-named groups |
+| **Ask only what's needed** | GOV.UK *question protocol* | Defer/hide rarely-used optional fields |
+| **Error summary + adjacent message** | GOV.UK Design System | A navigable "needs attention" section, not a red bar |
+
+The throughline: **the IDE audience tolerates density but not noise.** Cut
+*ink*, not *information*.
+
+---
+
+## 4. The redesign — concrete moves
+
+### 4.1 Collapse 5 status systems into 1
+
+**Keep** the top completion strip as the *single* global status. **Evolve it** so
+it carries everything the other four systems were saying:
+
+- Segment the bar into **set-&-valid / needs-attention / unset** (e.g. green /
+  amber / track), so "57% done, 6 need attention" is legible in one glance —
+  no separate red banner needed.
+- The **"6 need attention"** count becomes a quiet, clickable affordance *on the
+  meter* ("→ 6 to resolve") that filters to those fields. This replaces the
+  red banner (system #2) with a calm, constructive control.
+- **Drop the per-group `4 OPTIONAL` pill entirely** (the group is already
+  labelled "Optional"). Keep a per-group "N to resolve" **only when > 0**, muted
+  and right-aligned — or better, a thin per-group progress underline.
+- **Demote the per-row Draft chip**: the *global* Draft state is enough; per-row,
+  "changed" is better shown by the revert ↺ affordance alone.
+
+Net: the user has **one** place to read status, and **one** click to act on it.
+
+### 4.2 Errors → To-dos (validation timing & severity)
+
+Introduce a 3-state model for a field's status, and **stop conflating them**:
+
+| State | Meaning | Default treatment |
+|---|---|---|
+| **Unset** | No value, not required | Muted `—` / "Not set". **No alarm.** |
+| **To-do** | Required (or required-group) but unset, untouched | **Quiet amber** dot + "Needs a value". Not red, not a box. |
+| **Invalid** | User entered something that fails validation | **Red**, but only **after the field is touched** or **after a submit attempt**. |
+
+Rules:
+- **Untouched required fields are to-dos, not errors.** In a DRAFT, "Required —
+  not set" should be a calm amber hint, not a red error with a full-width box.
+- **Validation fires on blur / on submit**, not on load. Track a per-field
+  `touched` flag (or a form-level `submitAttempted`).
+- **The error reason moves off the default row.** Show at most a 1-word/short
+  inline hint after the value ("empty", "invalid"); the full message appears
+  **only when the row is focused/expanded** (where the editor's own message strip
+  already lives) or in the "needs attention" summary.
+
+This one change removes the wall of red in the screenshot: those six boxes become
+calm amber to-dos until the user engages or hits Submit.
+
+### 4.3 The row: one strict template + progressive disclosure
+
+Lock a **constant 3-zone row** and keep it one line by default:
+
+```
+[ icon? · Label · req-dot ]   [ value summary ……………… ]   [ status · actions ]
+            label col                 value col (ellipsis)        fixed right
+```
+
+- **Constant height, constant alignment, constant zones.** The current grid is
+  already close (`StyledGroupBody .readfirst-row`); the fix is *what we allow to
+  break it.*
+- **Move out of the default row, behind disclosure (ⓘ / focus / expand):**
+  - field **descriptions / subtitles** (currently inline under the label),
+  - **error/validation messages** (currently full-width boxes),
+  - **default-value hints**,
+  - **nested object/hash previews** (the `schemaOption2 → Show more` tree) →
+    collapse to the "Object · 1 field" summary; reveal the tree only on expand.
+- Result: a 21-field form is **21 scannable lines**, each of which *can* expand —
+  rather than a variable-height stack you have to parse.
+
+### 4.4 Value language: calm & consistent
+
+- **Desaturate the template chips.** `Test (local)` / `Richtext Template`
+  currently use saturated blue and outshout the labels. Use a quiet, low-contrast
+  chip (subtle surface + the `$` template glyph) so the **label leads** and the
+  value supports. Reserve saturated colour for *state* (to-do/invalid), not for
+  *value type*.
+- **One muted weight for all "set" values** (text, hex, filename, count). The
+  swatch/file-icon/`$`-glyph carry the type; the text stays uniform.
+- **"Not set" gets the lightest possible treatment** (muted, no italics arms-race
+  with errors) so empty rows visually *recede* rather than read as problems.
+
+### 4.5 Reduce chrome (data-ink)
+
+- Replace the **red left stripe + red box + red ⓘ** trio with a **single status
+  dot** in the right-hand status slot (colour = severity). One mark, not three.
+- **Whitespace over borders.** Drop the recessed value-surface fill and the
+  group spine where they don't encode meaning; let alignment + a little more
+  vertical rhythm do the grouping. (Keep the **required-group rail** — that one
+  *does* encode a real relationship.)
+- Audit every line/fill in `compactRowStyles.ts` against "does this encode data?"
+  If not, it's a candidate for removal.
+
+### 4.6 Grouping, ordering, findability
+
+- **Default sort within a group = needs-attention → set → optional-unset.** Put
+  what the user must act on at the top of each group automatically (the existing
+  `invalid`/`unset` sort modes, but as the smart default for a draft).
+- **Name groups by purpose.** "General" is a non-answer; if the schema gives no
+  meaningful group, prefer a single **Required / Optional** split over a vague
+  "General" bucket.
+- **A pinned "Needs attention (6)" section** at the very top when there are
+  unresolved fields — the form's built-in answer to "what do I do next," and the
+  constructive replacement for the red banner (GOV.UK error-summary pattern, but
+  calm and always-navigable).
+- Keep optional-but-unset fields **collapsed by default** behind the existing
+  "Optional (N)" disclosure, so the default view is "what's set + what's needed."
+
+### 4.7 The "what's next" path
+
+The form should always answer *what's left?* and make it one click to get there:
+
+- Meter → click "6 to resolve" → filter to unresolved (reuse `showInvalidOnly`,
+  but renamed to *"needs attention"* and including required-unset to-dos).
+- On **Submit** with unresolved fields: scroll-to + focus the first, and *now*
+  promote to-dos to errors (the flash machinery already exists).
+- Optional niceties: keyboard `n`/`p` to jump between unresolved fields; a sticky
+  "Next: <field> →" hint while editing.
+
+---
+
+## 5. Phased roadmap (impact × effort)
+
+### P0 — quick wins (high impact, low effort): "stop shouting"
+1. **Unset ≠ error.** Don't render red boxes/stripes for untouched required/empty
+   fields; downgrade to quiet amber to-dos. *(biggest single win)*
+2. **Remove the red invalid banner**; fold the count into the meter as a quiet
+   "→ N to resolve" control.
+3. **Drop the `N OPTIONAL` group pill**; show "N to resolve" only when > 0, muted.
+4. **Move field descriptions + error messages off the default row** (behind ⓘ /
+   focus). One line per row.
+5. **Desaturate template chips.**
+
+> P0 alone should resolve "crowded and overwhelming" for the screenshot case.
+
+### P1 — structural (medium effort): "calm density"
+6. Segmented completion meter (set / to-do / unset).
+7. Strict row template + collapse nested previews to summaries by default.
+8. Single status-dot system; remove redundant stripes/boxes/ⓘ-buttons.
+9. Validation timing: per-field `touched` + `submitAttempted`.
+10. Smart default ordering (needs-attention first) + purpose-named groups.
+
+### P2 — ambition (higher effort): "truly great"
+11. Pinned **"Needs attention"** navigator section + keyboard jump.
+12. Reduce the "edit card" modality — inline-first editing everywhere it fits.
+13. **Density toggle** (comfortable / compact) for newcomers vs power users.
+14. Per-group progress underline; section-level "all set" collapse.
+15. Telemetry-driven defaults (collapse rarely-touched optional fields).
+
+---
+
+## 6. Component-level change list (where the work lands)
+
+| Area | File | Change |
+|---|---|---|
+| Status consolidation | `CompactToolbar.tsx` | Segmented meter; remove invalid banner; "N to resolve" control |
+| Group header | `FormEngine.tsx:1968` `StyledGroupHeader` | Drop `N OPTIONAL`; muted "to resolve"; optional progress underline |
+| Row template & disclosure | `CompactRow.tsx` | Move desc/error/default-hint behind disclosure; single status dot; calm chips |
+| Validation model | `FormEngine.tsx` validity data + `CompactRow` | `touched`/`submitAttempted`; unset→to-do vs invalid |
+| Visual chrome | `compactRowStyles.ts` | Remove non-data stripes/fills; whitespace rhythm; keep required rail |
+| Ordering / sections | `FormEngine.tsx` group + sort | Needs-attention-first default; "Needs attention" section |
+| Value language | `readFirst.ts` + `CompactRow` `renderReadFirstValue` | Uniform muted weight; desaturated template/richtext chips |
+
+None of this changes the schema/value/`onChange` contract — it's all
+presentation, consistent with the compact mode's existing "purely presentational"
+design.
+
+---
+
+## 7. Open questions (to decide / validate with users)
+
+1. **Validation timing**: blur-only, or also a gentle "you skipped a required
+   field" on navigate-away? (Lean: blur + submit.)
+2. Is **"General"** a real schema group or a fallback bucket? If fallback, can we
+   suppress the group chrome entirely for single-group schemas?
+3. How often are the **nested object/hash previews** actually read at a glance vs
+   noise? (Telemetry / quick user check before investing in them.)
+4. Do power users want the **density toggle**, or should we just ship one
+   well-tuned density?
+5. Should **optional-unset** fields be collapsed by default (cleaner) or visible
+   (discoverable)? Likely collapsed with a strong "+ N optional" affordance.
+
+---
+
+## 8. How we'll know it worked
+
+- **Time-to-first-meaningful-scan** (qual): can a new user say "what's left?" in
+  < 5s?
+- **Perceived calm** (5-pt survey before/after on the same schema).
+- **Error-recovery**: time from Submit-blocked to all-resolved.
+- **Eye-bounce** (optional): fewer fixations to locate the next action.
+- Objective: **default view height** for the screenshot schema should drop
+  substantially once errors/descriptions move behind disclosure.
+
+---
+
+## 9. References
+
+- Nielsen Norman Group — *10 Usability Heuristics* (esp. Aesthetic & minimalist
+  design, Visibility of system status, Error prevention); *Progressive
+  Disclosure*; *Inline Validation in Web Forms*.
+- Baymard Institute — form usability research (inline validation timing;
+  required vs optional).
+- GOV.UK Design System — *Error summary* + *error message* patterns; *question
+  protocol* ("only ask what you need").
+- Edward Tufte — *The Visual Display of Quantitative Information* (data-ink
+  ratio).
+- Miller (1956) — chunking (~7±2).
+- Design-system form guidance: Material 3, IBM Carbon, Shopify Polaris
+  (error/state colour conventions, one-column dense forms).
+
+---
+
+### Appendix — mapping the screenshot to the fixes
+
+| In the screenshot | Why it feels heavy | Fix (section) |
+|---|---|---|
+| Red banner "6 fields are not valid…" | System #2, alarmist | 4.1 / P0-2 |
+| `4 OPTIONAL` / `5 TO RESOLVE` pills | System #3, competes with titles | 4.1 / P0-3 |
+| Red box "Text value is empty" (untouched) | Premature error | 4.2 / P0-1 |
+| Red box "Hash arguments are invalid" inline | Layout-disruptive error | 4.2 / 4.3 |
+| Saturated blue `Test (local)` chip | Decoration outshouts label | 4.4 / P0-5 |
+| `schemaOption2 → Show more` tree inline | Breaks row rhythm | 4.3 / P1-7 |
+| Per-row red stripe + red ⓘ + red box | Three marks for one state | 4.5 / P1-8 |

package/dist/components/FocusedEditing/index.d.ts

@@ -1,6 +1,14 @@
 /// <reference types="react" />
 import { IReqoreModalProps } from '@qoretechnologies/reqore/dist/components/Modal';
-export declare const FocusedEditing: import("react").MemoExoticComponent<({ children, isFullscreen, ...rest }: IReqoreModalProps & {
+export declare const FocusedEditing: import("react").MemoExoticComponent<({ children, isFullscreen, modalOnly, ...rest }: IReqoreModalProps & {
     isFullscreen?: boolean;
+    /**
+     * Render ONLY the modal, not the in-place copy of `children`. For call
+     * sites that already render the field themselves and just need the focused
+     * overlay on top — e.g. the compact row's inline editor, which lives in the
+     * row grid and must stay there. Default (`false`) renders children in place
+     * as well, which is what the classic and card layouts wrap themselves in.
+     */
+    modalOnly?: boolean;
 }) => import("react/jsx-runtime").JSX.Element>;
 //# sourceMappingURL=index.d.ts.map

package/dist/components/FocusedEditing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/FocusedEditing/index.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,iBAAiB,EAAe,MAAM,gDAAgD,CAAC;AAGhG,eAAO,MAAM,cAAc,4EACa,iBAAiB,GAAG;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,6CA8BrF,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/FocusedEditing/index.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,iBAAiB,EAAe,MAAM,gDAAgD,CAAC;AAGhG,eAAO,MAAM,cAAc,uFAMtB,iBAAiB,GAAG;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,6CA8BF,CAAC"}