@qoretechnologies/reqraft 0.10.62 → 0.10.63-pr.142.g0b675cd

package/design/COMPACT_PARITY.md

@@ -1,85 +0,0 @@
-# Compact mode — options-schema parity matrix
-
-Answers the call's requirement: *"we have to make sure that we support everything that the
-options support"* (Filip, 2026-06-10). Capability list is taken from the authoritative schema
-type (`@qoretechnologies/ts-toolkit` `forms.d.ts` — `TQorusFormFieldSchema`) plus engine-level
-props; IDE usage was verified by grepping `qorus-ide` (file counts in brackets where relevant).
-
-Legend: ✅ works + covered · 🟡 works, coverage thin/indirect · 🔴 gap (not supported or untested)
-
-## Identity & display
-
-| Capability | Compact behaviour | Coverage |
-|---|---|---|
-| `display_name` | row label | ✅ everywhere |
-| `short_desc` | hover title + the row's ⓘ info panel (stripe-expand display, **decided 2026-06-11**: losers + `compactInfoDisplay` prop deleted) | ✅ `CompactShowcase`, `CompactFieldTypes` "Descriptions & messages" |
-| `desc` (markdown) | `?` → help dialog | ✅ `CompactHelpDialog` |
-| `group` + `groups` prop | collapsible group panels + badges | ✅ `Compact`, `CompactBasic` |
-| `sort` | ✅ fields sort by `schema.sort` (`availableOptions`) — verified | ✅ `CompactSortOrder` (declared out of order, renders 1-2-3) |
-| `icon` / `image` / `badge` / `actions` / `intent` / `tags` (field-level chrome) | ✅ **decided + built** (2026-06-10): rows render `icon`/`image` before the label and `intent` as the edge stripe (card border tints too); `badge` / `actions` / `tags` render on the expanded edit card header — nothing the schema sends is silently dropped | ✅ `CompactFieldTypes` "Field chrome" group (incl. a full-chrome combo) |
-
-## Types & values
-
-| Capability | Compact behaviour | Coverage |
-|---|---|---|
-| full `TQorusType` union | read-first values per family | ✅ `CompactFieldTypes` catalog |
-| colour / file / hash read-first | swatch+hex · filename+size · count + structured tree | ✅ `CompactFieldTypes`, `CompactBasic`, unit tests |
-| `arg_schema` (nested form) | card editor + structured preview | ✅ `CompactBasic`, `CompactHashStructuredView` |
-| YAML-serialized values | summarised, not raw `%YAML` | ✅ `CompactListYamlField`, unit tests |
-| `default_value` (+`_desc`, `_display_name`) | seeded by engine; `default_value_desc` note surfaces in the row's info panel (Tier 2, behind ⓘ) | ✅ `CompactReadonlyDefaultFix`, `CompactShowcase` (toggle journey) |
-| `element_type` / typed lists | read-first join | 🟡 display via `CompactFieldTypes`; editing untested |
-
-## Validation & requirements
-
-| Capability | Compact behaviour | Coverage |
-|---|---|---|
-| `required` | `*`, Required tag, completion meter, Draft/Ready badge | ✅ several stories |
-| `required_groups` | members are **linked** (2026-06-10): unmet members show a "One of: <group>" chip — tap-popover lists siblings (click → scroll + flash, works across panels), hover highlights all members; once satisfied, empty siblings show *"Not set — covered by …"* + Ready transition | ✅ `CompactRequiredGroups` (3 members across 2 panels, full journey) |
-| invalid values | Required tag + banner + filter-to-invalid | ✅ `CompactBasic` (6 invalid) |
-| `messages` (intent) | read rows: Tier-1 (danger/warning) → intent edge-stripe + auto-open info panel; Tier 2 behind the ⓘ toggle; the inline editor suppresses its own message strip (the panel below the editing row is the single renderer) | ✅ `CompactShowcase`, `CompactFieldTypes` "Descriptions & messages" |
-| `rules: ['valid_identifier']` [47 IDE files] | ✅ **wired** (2026-06-10): `validations.ts` maps `rules` → the identifier check; `OptionFieldMessages` now spreads the *field* schema (was the whole map — pre-existing bug). Unknown rule strings are deliberately ignored (documented at the mapping site) | 🟡 `CompactValidIdentifierRule` shows the Draft badge + invalid banner (the rule's *rejection* is asserted in the 3 unit tests, not the play) |
-
-## Selection & editing
-
-| Capability | Compact behaviour | Coverage |
-|---|---|---|
-| `allowed_values` (+`_creatable`) | display label resolution + real dropdown inline | 🟡 `CompactBasic` asserts the resolved display label (incl. broken values); the inline dropdown *interaction* and the `_creatable` add-path are rendered but not driven by a play |
-| `element_allowed_values` (+creatable) [8] | multi-select display join + card editor with the real multi-select | ✅ `CompactMultiSelectEditing` (open + selection labels; deep add/remove interaction still light) |
-| `multiselect` | — | 🟡 covered via the same story |
-| `supports_templates` / `$config:` | raw template shown in read row; toggle inline | ✅ `CompactBasic` (`$local:test`) |
-| `supports_custom_values` | passed through to editor | 🟡 indirect |
-| `sensitive` [21 IDE files] | read row + hover title mask `••••••` (leak fixed 2026-06-10). Known behaviour: the TemplateField *editor* reveals the value while editing (textarea path — same as the IDE; a `password`-input treatment would be a TemplateField change). Nested sensitive inside the structured hash preview NOT masked (ReqoreDataView has no sensitive concept — upstream candidate) | 🟡 `CompactSensitive` asserts the read-row mask + no page-text leak; the edit-state reveal and the hover-title mask are not asserted (+ unit tests) |
-| `is_expression` values | read row shows "Expression" | 🟡 unit test; expression *editing* story still pending (transport live, deferred by Nick) |
-| `supports_expressions` / `expressions_url` / `server_expression_handling` / `default_view` | passed to editor | 🔴 untested in compact (needs expression transport — now live per Nick) |
-| `op` / operators | ✅ **`operators` prop wired** (2026-06-10 — was a dead internal `useState(undefined)`, unreachable in classic AND compact); operator-bearing fields always card-edit | ✅ `CompactOperators` (selector + WHERE/IS summary) |
-| `app` / `action` (custom template menu for `any`) | `getCustomMenuTemplateItems` wired. **Empty-`any` affordance fixed** (2026-06-11, found via `CompactFieldTypesEditingAllRequired`): `allowCustomValues` is hard-false for `any` (the value's TYPE is picked from the template menu first), so an empty `any` card used to render only a bare ⋮ — read as broken. `TemplateField` now renders the menu trigger as a labelled **"Set value"** button whenever the menu is the field's only control (`hasInputAffordance`); valued fields keep the icon-only ⋮. Toolkit is canonical — the IDE inherits this at adoption. | ✅ `CompactFieldTypesEditingAllRequired` (Set value → Set Custom Value → Text → richtext editor mounts), `CompactAnyType` (valued: card opens) |
-
-## Behaviour & lifecycle
-
-| Capability | Compact behaviour | Coverage |
-|---|---|---|
-| `preselected` / hidden optionals | rows + search-add + Fields menu | ✅ `CompactFieldsMenu`, `CompactSearchHidden` |
-| `depends_on` (incl. nested arrays) | unmet deps **lock the row**, and the linkage is **navigable** (2026-06-10): the lock's tap-popover lists each blocker with its state (✓/✗, handles `name=value` and any-of arrays; click → scroll + flash), lock hover highlights the blockers, and **fulfilling a dependency flashes the rows it unlocks** | ✅ `CompactBasic` (full lock → locate → fulfil → unlock-flash journey), `CompactOptionDependsOnOptionOrAnotherOption` (any-of), `CompactOptionDependsOnOptionInRequiredGroup` (dep × group interplay), `CompactOnChangeAndDependents`, `CompactShowcase` |
-| `has_dependents` + `on_change: refetch` | dependents reset + refetch event | ✅ `CompactOnChangeAndDependents` |
-| `disabled` / `readonly` | `disabled` **locks the row** (2026-06-10 — previously it opened a dead editor); form-level `readOnly` still opens in view mode (Close); readonly default-fix | ✅ `CompactBasic` (locked-row asserts), `CompactReadOnly`, `CompactReadonlyDefaultFix` |
-| `focusedEditing` | ✅ compact edit cards now have the fullscreen affordance (2026-06-10): a Fullscreen button opens the same `FocusedEditing` modal as classic, with the field's descriptions | ✅ `CompactFocusedEditing` |
-| `get_message` / `return_message` | **out of scope for FormEngine parity.** These keys belong to the IDE's *legacy Field system* (`components/Field/*`, VSCode-era message bus: `postMessage`/`addMessageListener`); the IDE's options form (`systemOptions.tsx` — what FormEngine is the port of) never uses them, and server options schemas don't carry them. They only appear in the schema *type* because it also models legacy field definitions. Porting them = the separate Field-system migration, where the message bus becomes transport-agnostic callbacks (the `optionsLoader` pattern). | n/a |
-| `optionsLoader` (async schema) | loading/error lifecycle | ✅ `CompactOptionsLoader(+Error)` |
-| narrow containers (mobile / drawers) | stacked rows < 480 px measured form width; inline editing full-width | ✅ `CompactShowcaseMobile` (360 px) |
-
-## Remaining gaps (2026-06-10, after the coverage batch)
-
-Closed in the batch: `rules` wiring (+ the `OptionFieldMessages` field-vs-map spread bug),
-`sensitive` story, operators (prop wiring — it was dead engine-wide — + story), `focusedEditing`
-on compact cards (feature + story), multi-select editing story, `sort` assert.
-
-Still open:
-1. **Expression-editing story** — transport is live (localhost:8012); deferred by Nick.
-2. **Nested `sensitive` in the structured hash preview** — `ReqoreDataView` has no sensitive
-   concept; upstream candidate. Related: the TemplateField editor reveals sensitive values while
-   editing (IDE-parity behaviour; a password-input treatment would be a TemplateField change).
-3. **Deep multi-select interaction** (add/remove via the dropdown) — the story asserts open +
-   selection labels only.
-
-(`get_message`/`return_message` was initially listed here as a gap — that was wrong; see the
-behaviour table: it's legacy-Field-system scope, not options-form parity.)

package/design/EXPRESSION_BUILDER_REPORT_STRATEGY.md

@@ -1,92 +0,0 @@
-# Expression Builder — verbatim re-port strategy
-
-**Status:** locked 2026-06-10. Supersedes the *from-scratch* ExpressionBuilder
-in `design/FORM_ENGINE_EXPRESSIONS.md` (Phases 3/3b/3c/3d). The plumbing
-(catalogue hook, FormEngine `is_expression`, DPQL bridge, validation
-`isFunction` case) from that batch is retained; the visual builder is replaced.
-
-## Why we are redoing it
-
-The first attempt **reimplemented** the visual builder on reqraft's own
-primitives. That diverged from the team's stated method (Filip, 2026-06-10
-call): *copy the IDE component verbatim — with its dependencies and its tests —
-get it looking and passing 1:1, **then** improve.* The from-scratch version
-never looked like the IDE and cost days of "why does it look worse" iteration —
-exactly the danger Filip named (you can't tell a port bug from a deliberate
-change). Nick on the call: the port "wasn't a good job done."
-
-## The blocking finding (why it's not a trivial copy)
-
-A verbatim copy of the IDE's `ExpressionBuilder` (1,857 LOC / 9 files) does NOT
-compile against reqraft today, because **reqraft's shared field stack drifted
-from the IDE** ("reqraft wasn't kept up"). Specifically:
-
-- **The recursion lives in `TemplateField`, not ExpressionBuilder.** Operands
-  render via `<TemplateField component={auto} allowFunctions isFunction={…}>`,
-  and TemplateField recurses back into ExpressionBuilder. reqraft's
-  TemplateField has **no `allowFunctions`/`isFunction`** — it uses a different
-  mechanism (the Phase-1 "Use Expression" menu toggle).
-- Missing helpers: `helpers/expressions` (`getArgumentType`,
-  `argumentMatchesType`), `areQorusTypesCompatible`.
-- `validateField` is private (`_validateField`) in reqraft.
-- `SelectFormField` hardcodes `flat={false}` + `intent='info'` (the chip
-  problem) — not externally controllable.
-- IDE-only seams that can't come along: `AiAssistanceAction` (AI),
-  `render-expression` over the Creator WebSocket (Explain), the hints system.
-
-So the proper port = **re-faithful-ize the field stack first, then copy the
-builder.** Decision (user, 2026-06-10): **re-port (option 1)**, not augment.
-
-## What is kept from the from-scratch batch
-
-- `useExpressions.ts` (catalogue hook — close to the IDE's)
-- `useRenderExpression.ts` (Explain seam — matches the planned `onExplain`/LSP)
-- `types.ts`, FormEngine `is_expression` plumbing, validations `isFunction`
-- **`ExpressionField` DPQL text mode** — NET-NEW (the IDE builder is
-  visual-only; DPQL text editing is the whole point of this branch)
-
-## What is replaced
-
-- `ExpressionBuilder.tsx` (from-scratch) + its stories + the mock-styling work.
-
-## Drawbacks (accepted)
-
-1. Touches `TemplateField` — load-bearing for the entire form engine + the
-   just-landed field migration. Highest-risk surface in the library.
-2. Two expression-on-field models collide (IDE `allowFunctions`/`isFunction`
-   vs the Phase-1 toggle); the IDE model wins.
-3. Never truly verbatim — AI dropped, Explain → `onExplain`/LSP seam.
-
-   *Revised 2026-09-08 — one deliberate departure from the IDE source, in the
-   rest-argument operand mount.* The IDE derives an empty rest argument's `type`
-   and `defaultType` from the value (undefined when empty), so an empty `bool`
-   argument rendered as an untyped `auto` field — a type picker under a label that
-   already said "true or false" — and an empty `any` argument never qualified for
-   `TemplateField`'s template-selector default, which reads `type`. reqraft now
-   falls back to the catalogue's declared `ui_type`, as the first-argument mount
-   and the allowed-values branch already did. Flagged by Foxhoundn on the #118
-   qlip review; matches the read-only-types direction in qorus-ide#178. The IDE
-   inherits it, since it renders reqraft's builder.
-4. Brings the deferred machinery (type-mismatch modals, type-compat) — more
-   surface to own.
-5. Follow-on: the IDE must then *consume* reqraft's builder or they drift again.
-
-## Phases (Filip's method: copy + tests → 1:1 → improve)
-
-- **A — Field-stack parity.** Port verbatim into reqraft (with their IDE
-  tests): `helpers/expressions`, `areQorusTypesCompatible`; export
-  `validateField`; bring `SelectFormField` to forward `flat`/`intent`; bring
-  `TemplateField` to the IDE's `allowFunctions`/`isFunction` mechanism.
-  **GATE:** the field-migration stories + jest still pass.
-- **B — Verbatim ExpressionBuilder.** Copy the 9 files + the IDE's stories &
-  tests; fix import paths; seam out AI (off) / render-expression (`onExplain`
-  prop) / hints (stub). **GATE:** 1:1 vs `:6007`, ported tests pass.
-- **C — Re-wrap reqraft features.** Visual = ported builder, Text =
-  `DpqlEditor`, Explain = seam, inside `ExpressionField`; reconcile FormEngine
-  `is_expression` to the IDE model. **GATE:** field-holds-expression story.
-- **D — Server (out of reqraft).** `render-expression` over LSP/REST; swap
-  `useRenderExpression`. (Filip/Nick file the server issue.)
-- **E — Dedupe (out of scope now).** IDE consumes reqraft's builder.
-
-Between every phase: open Storybook, **compare to `:6007`**, fix, then proceed.
-No commits until the user verifies.

package/design/FORM_ENGINE_COMPACT.md

@@ -1,300 +0,0 @@
-# FormEngine — compact (read-first) mode
-
-## What it is
-
-`FormEngine` ([`src/components/form/engine/FormEngine.tsx`](../src/components/form/engine/FormEngine.tsx))
-renders an options schema (`IQorusFormSchema`) as a form. It has two layouts:
-
-- **Classic** (default) — every option's editor is expanded at once.
-- **Compact (read-first)** — pass `compact` to render each option as a **row showing its current
-  value**; clicking a row expands the real editor inline, and a **Done** action collapses it again.
-  The form reads as a "configuration summary you drill into" rather than a wall of inputs.
-
-Compact mode is purely presentational — editing flows through the **same** machinery as the classic
-layout (templates, `on_change`, validation, dependents). Nothing about the schema, value shape, or
-`onChange` contract changes.
-
-## What `compact` adds
-
-- **Read-first rows.** Each option shows a formatted summary of its value (`formatOptionValue`):
-  booleans as Yes/No, `allowed_values` as their display label, lists as joined item names, rich text
-  flattened to plain text, **colours** as their hex/`rgba()` string (with a swatch preview),
-  **files** as their filename (with a file icon + muted size), and **hashes** as an "N fields" count.
-  Empty options show **Not set**, or **Required — not set** (warning intent) when required.
-- **Hash "view more" preview.** A hash row keeps its "N fields" summary and renders the hash's
-  contents beneath it with the **structured tree** (`StructuredDataView` → `ReqoreDataView` — see
-  the dedicated section below); whether a row gets a preview at all is gated by `getHashEntries`,
-  which recognises `arg_schema` structured forms, serialized-YAML/free-hash values, and schema-less
-  hashes whose entries are the server's typed envelopes (`{ type, value }` unwrapped by its strict
-  shape, so an entry counts as `value1` rather than "2 fields"). The preview is wrapped in a
-  reusable **`ReqraftCollapsibleContent`**: a short hash shows in full, a tall one is clipped behind
-  a **gradient "Show more" fade** (a reveal button that surfaces on hover; expanding adds a
-  "Show less"). Clicking a value chip (or the row itself) opens the full nested editor — the
-  preview is read-first, with the tree's expand/collapse summaries owning their own clicks.
-  `ReqraftCollapsibleContent` ([`src/components/collapsible/CollapsibleContent.tsx`](../src/components/collapsible/CollapsibleContent.tsx))
-  is a standalone, exported, theme-aware toolkit component (extracted from the IDE's chat-bubble
-  `CollapsibleContent` fade-reveal) so the same affordance can be reused elsewhere; the fade colour
-  defaults to the Reqore theme surface (overridable via `fadeColor`).
-- **Inline editing for scalars, card for complex fields.** Clicking a row mounts the real field
-  (`renderOption`) — the editor is **not** mounted while collapsed, and multiple rows can be open at
-  once. *Scalar* fields (string, number, bool, date, colour, selects/allowed-values, …) edit **in
-  place inside the row**: the editor replaces the value cell, with a per-row **↺** (when changed) and
-  a **✓** to collapse; Escape or clicking the label also collapses. *Complex* fields — anything in
-  `COMPACT_COMPLEX_TYPES` (hash, list, file, richtext, any/auto, schema editors, …) plus any field
-  with `arg_schema` or operators — still open the expanded **edit card** with a Done button, per the
-  agreed fallback ("big fields still render a form"). Changes flow through the same
-  `handleValueChange` → debounced `onChange` pipeline in both paths — the engine never persists;
-  *when* to apply the emitted value (immediate vs batched commit) is the consumer's contract.
-- **Completion meter + Incomplete/Ready status.** A single inline bar at the top — Incomplete/Ready status |
-  `N / M fields set` | track (fills remaining) | `%` — matching the IDE's restyled completion strip.
-  The badge is the IDE restyled-hero convention (`RestyledFields`): a minimal small `ReqoreTag`,
-  **Incomplete** (warning) while any field is invalid, required-unset or needs attention, **Ready**
-  (success) once everything validates — driven by the same validity data as the invalid-fields
-  banner; hidden in `readOnly`. It signals form *readiness*, not unsaved changes, which is why the
-  not-ready state is never called "Draft": a form nobody has touched can be Incomplete, and **Draft**
-  means unsaved changes — the batched mode's per-row chip, and nothing else. Unsaved-change state is
-  that chip and the per-row **↺** / "Revert all changes". (`VariantCalmTable`'s meter uses the same
-  two words.) (Product save convention for
-  context: creator forms auto-save to a *draft* via the IDE's `useInterfaceDraft` — debounced
-  auto-draft + explicit Submit — so compact inline edits are draft-persisted by the consumer with no
-  extra engine work.)
-- **Toolbar.** A search box (filter rows by label) plus a **Fields** dropdown (`ReqoreDropdown`,
-  edit-mode only) that consolidates the field-set actions: **Required only** (toggle), **Show field types**
-  (toggle — annotates each row with its type, e.g. `<string>`), **Select all** (add every optional field),
-  **Default fields** (drop user-added optionals + clear the filter, keeping required/preselected/loaded
-  values), **Revert all changes** (undo every edit back to the loaded values), and a searchable
-  **add-optional** list. Filters only affect which rows are listed — the completion meter still reflects the
-  full set. ("Edit code" is *not* here — that stays IDE-side.)
-- **Revert.** A changed row shows a per-field hover **↺** that restores that field to its loaded value;
-  **Revert all changes** in the Fields menu restores the whole form. (Distinct from **Default fields**,
-  which resets to schema defaults + drops added optionals.)
-- **Batched commit (`commitMode='batched'`).** The decided save model (Nick, 2026-06-10): edits
-  stage as a **draft** — each changed row gets an always-visible warning **Draft** chip (the
-  product's draft convention), and a **Save / Discard bar** docks **bottom-right as a sticky,
-  floating card** while anything is dirty (`N unsaved changes`) — `position: sticky` (not fixed)
-  so it stays inside the form's scroll bounds when the engine renders in a drawer/panel. **Save**
-  fires the new **`onCommit`** callback with the
-  staged form and is **disabled while any field is invalid**; **Discard** is the existing
-  revert-all. `onChange` still fires on every staged edit, flagged **`meta.draft`**, so consumers
-  can live-validate without persisting. Default stays `'immediate'` (today's behaviour — no
-  consumer breaks). Stories: `CompactBatchedCommit` (full stage → save → discard journey),
-  `CompactBatchedCommitInvalid` (Save gated on validity).
-- **Search spans hidden fields.** The top search matches *all* schema fields, not just the listed ones: a
-  match that is an optional field not yet in the form is surfaced as a dimmed **"Not in form — add"** row;
-  activating it adds the field and opens its editor.
-- **An unmet `depends_on` withholds the field rather than offering it.** A field whose dependency is
-  not fulfilled is left out of the not-yet-added list entirely — so it is absent from the addable rows,
-  the Fields menu, and its **Select all** alike. All three read the one `filteredOptions` list, which is
-  where the gate lives, so they cannot disagree about what is available. The rule is that
-  `hasAllDependenciesFullfilled` is the *same* predicate that then refuses to let the field be edited:
-  offering one it rejects can only end at a row that opens and says it is disabled. (Reported on auth
-  profiles — an authentication scheme set to Permissive still offered `Cookie Name` and `Redirect URL`,
-  both `depends_on: ['type=cookie']`, and both dead ends.) Fulfilling the dependency brings the rows
-  back and flashes them (`dependencyLockedNames`), which is the discoverable path: pick the scheme, and
-  the fields that scheme has appear. **Only the not-yet-added ones** — a field that already holds a
-  value stays listed when its dependency later stops holding, rendered `readfirst-row-disabled` with the
-  reason, so a value still being submitted is visible and removable instead of silently orphaned.
-- **A field locked by an unmet `depends_on` does not need attention.** A `required` (or one-of
-  `required_groups`) field that is listed but locked is not required while it is locked: the status
-  (`getOptionStatus`) and box (`getOptionBucket`) treat it as optional, so it waits in the Optional box,
-  locked, with what unlocks it, and is not in "Needs attention", the header's attention count or the
-  first-attention autofocus target. Its messages say what unlocks it, not "This field is required"
-  (`getOptionFieldMessages`). The field it depends on carries its own status, and that field is what
-  the author has to do next. Once the dependency holds and the field is still empty, it needs attention
-  again. The same rule holds for form validity (`onValidityChange`, the Incomplete/Ready status,
-  `showInvalidOptionsOnly`): an EMPTY locked field does not apply, so it does not make the form
-  incomplete — otherwise a check of kind Equals could never be saved because Minimum, required for
-  Between alone, is empty, and a form whose only gaps are fields nobody can fill in would read
-  Incomplete with nothing under "Needs attention". A value a locked field still holds is validated
-  as before. (`getUnresolvedRequiredOptions`, which decides whether a form is needed at all before
-  any is shown, still reports a locked required option as unresolved, reason `dependency`.) Stories: `CompactLockedRequiredNeedsNoAttention`,
-  `CompactUnlockedRequiredNeedsAttention`.
-- **Sticky-top toolbar.** The completion meter + search + Fields menu are wrapped in a `position: sticky;
-  top: 0` header (opaque background masks rows scrolling beneath), so filtering and adding optional fields
-  stay reachable while scrolling a long form. (Replaced an earlier bottom "Additional options" bar that, as
-  the last child of the scroll content, could never actually pin to the viewport.)
-- **Zebra field blocks + spacing (no dividers) + mobile left rail.** Every field block (a row, or
-  the wrapper carrying a row plus its message strips / hash preview) gets an alternating
-  theme-derived tint — 3% on desktop, 5% on narrow forms — and blocks separate with an **8px gap**
-  at all widths; the old hairline dividers were retired (zebra + space carry the separation). Each
-  field owns a visible territory and strips never float ownerless. Narrow forms additionally indent
-  content 12px under the label (left rail) and use slightly taller inner padding. Edit cards keep
-  their own surface.
-- **No horizontal overflow.** The row grid's value column is `minmax(0, 1fr)` and the value cell has
-  `min-width: 0`, so a long unbroken value (e.g. a URL) ellipsis-truncates (full value on hover via `title`)
-  instead of forcing a horizontal scrollbar.
-- **Field info: intent stripe + expandable panel** (the decided "stripe-expand" display,
-  2026-06-11 — see `COMPACT_INFO_DISPLAY.md`). Rows carrying critical (Tier 1: danger/warning)
-  messages get a 3px intent edge-stripe and their info panel **auto-opens** below the row —
-  short_desc plus all schema/validation/dependency messages as slim `ReqoreMessage` strips.
-  Fields with only Tier-2 info (info/success messages, `default_value_desc` notes, short_desc)
-  stay one line: a ⓘ toggle in the fixed info slot opens the panel on demand (the per-row
-  override sticks either way). While a row is edited inline, the editor's own schema-message
-  strip is suppressed — the panel below the editing row is the single renderer. Stories:
-  `CompactShowcase` (+`Mobile`).
-- **Accessibility.** Read-first rows are real controls (`role="button"`, `tabIndex={0}`, Enter/Space
-  activate, visible focus ring), not just click handlers; the Done button and dropdowns are native buttons.
-- **The caret follows the row that opens.** An opened row moves the caret into the control it offers —
-  whatever that control is. `findRowFocusTarget` ([`rowFocus.ts`](../src/components/form/engine/rowFocus.ts))
-  prefers a text-entry control (`input` / `textarea` / `contenteditable`) and otherwise takes the first
-  other focusable one (a `<button>` selector, a `[tabindex]` reqore checkbox — a pick-one's choices are
-  not inputs), ignoring an absorbed sibling's editor and the schema-message strip, which belong to other
-  fields. The row is revealed first — `scrollIntoView({ block: 'nearest' })` on the ROW, a no-op when it
-  is already visible — because a caret below the fold changes nothing on screen while the next keystroke
-  goes somewhere invisible; focus itself then uses `preventScroll` so nothing moves twice. A caller that
-  wants the row **opened without the caret** uses `expandFirstRequired` rather than
-  `autoFocusFirstRequired`. The search is re-run by a one-shot `MutationObserver` on the row's value cell,
-  so an editor that mounts its control several commits later (a host editor resolving a catalogue) still
-  gets the caret, and it gives up the moment the caret is somewhere outside this row. Stories:
-  `CompactAutoFocusFirstRequired`, `CompactAutoFocusPickOneFirstQuestion`,
-  `CompactAutoFocusNonFocusableFirstField`, `CompactAutoFocusLateMountingEditor`.
-- **A row the AUTHOR opens into a picker opens the picker with it.** Read-first belongs to the
-  COLLAPSED row; it must not be the answer twice. A picker's editor is a closed trigger printing the
-  value the read row had just printed, so the row opened, nothing on screen changed, and changing the
-  value still cost a second click ("clicking on a closed option like 'Kind' opens the option, but the
-  same chosen value is displayed"). The row decides — it is the only party that knows both that the
-  author opened it (rather than the form) and which control it offers (`findRowFocusTarget`, the same
-  scan that hands over the caret) — and the control obeys, through
-  **`RowOpenPickerContext`** ([`rowOpenPicker.ts`](../src/components/form/engine/rowOpenPicker.ts)), a
-  one-shot `true` scoped to the row's own editor. A control declares itself a picker with
-  **`aria-haspopup`** (`isClosedPickerTrigger` in `rowFocus.ts`), which is the attribute's own meaning
-  and the existing contract with assistive technology — so a host's editor opts in by being accessible.
-  A context value rather than a synthetic click on the trigger: reqore's popover binds its click
-  listener in an effect keyed on the trigger element arriving, so a click dispatched from the row's
-  effect lands before anything is listening.
-  Read-first is kept where it still says something, and each of these is a term in the condition:
-  the collapsed row itself; a row the FORM opened (`initialExpandedOptions` — an address, or
-  qorus-ide's diagram showing a step — and `autoFocusFirstRequired`, which promises the caret and
-  only the caret); and the edit CARD a complex field opens, which is a form in its own right whose
-  first control is one of several. Stories: `CompactRowOpensItsPicker`,
-  `CompactTextRowOpensItsTextBox`; tests: `__tests__/compactRowClickOpensThePicker.test.tsx`.
-- **Grouping.** Rows are grouped by each option's raw `group` key into collapsible `ReqorePanel` sections,
-  each with a `✓ all set` / `⚠ N to resolve` badge (the catch-all `optional` group shows `N optional`
-  instead). Display per group (label / icon / subtitle / order) is
-  supplied by the consumer via the **`groups`** prop (the server sends only the bare group key — see
-  research below); anything omitted defaults to a title-cased key, no icon, and schema order. Ungrouped
-  required/preselected fields fall back to `general`, everything else to `optional`
-  (`getOptionGroup` / `getOptionGroupLabel`).
-- **Dedicated layout.** Compact does **not** reuse the classic `ReqoreCollection` card-per-field layout —
-  it renders its own flat rows (label | value | action, zebra blocks + spacing) so it reads like the
-  IDE's restyled creator rather than a wall of cards. The classic always-expanded path is untouched.
-
-Interface-specific chrome (status hero, value chips, "Edit code", the help Hint) is intentionally **not**
-in the engine — a consumer wraps `FormEngine` and supplies that around it. The **server does not define
-group display metadata** (only the bare `group` string per field; no label/icon/order), so each UI owns
-it — hence the engine takes group display via the `groups` prop rather than hardcoding it.
-
-## Where the logic lives
-
-- [`readFirst.ts`](../src/components/form/engine/readFirst.ts) — pure, unit-tested helpers:
-  `formatOptionValue`, `formatColorValue` / `colorToCss` (colour → hex/`rgba()` + swatch CSS),
-  `formatFileValue` / `getFileSize` / `formatBytes` (file → filename + size), `getHashEntries`
-  (hash → labelled sub-field summaries), `getOptionGroup` (raw key), `getOptionGroupLabel` (key →
-  display label, honouring the `groups` prop), `getReadFirstCompletion`, `isOptionValueEmpty`.
-- `FormEngine.tsx` — when `compact`, the component early-returns `renderCompact()` (the completion meter,
-  invalid-fields message, grouped flat rows via `renderCompactRow`, and the "more options" adder) instead
-  of the classic `ReqoreCollection`. Flat-row styling lives in module-level `styled-components`
-  (`StyledCompactWrap`, `StyledGroupBody`, `StyledEditCard`) with theme-derived colours. The classic path
-  is left exactly as it was.
-
-## Usage
-
-```tsx
-<FormEngine
-  name="my-form"
-  compact
-  options={schema}
-  value={value}
-  onChange={handleChange}
-  // optional: per-group display, keyed by the raw `group` string
-  groups={{
-    info: { label: 'Info', icon: 'IdCardLine', subtitle: 'Identity and core settings', sort: 0 },
-    scaling: { icon: 'BroadcastLine', sort: 1 },
-  }}
-/>
-```
-
-## Async schema (`optionsLoader`)
-
-`FormEngine` normally renders a schema you hand it via `options`. `optionsLoader` lets the engine **fetch
-the schema itself**, owning the loading / error / refetch lifecycle, while staying **transport-agnostic** —
-the consumer supplies an async callback that resolves the schema however it likes (the engine never learns
-about any backend). This is what lets a consumer converge an old "fetch-by-URL" form (e.g. the qorus-ide
-`<Options url=…>` fork) onto the upstream engine without pushing app-specific fetch code into the library.
-
-```tsx
-const loadSchema = useCallback(() => fetchSchemaSomehow(url), [url]); // memoise → refetch only on change
-
-<FormEngine
-  name="protocol-options"
-  compact
-  value={value}
-  optionsLoader={loadSchema}   // no `options` — the engine loads it
-  onChange={handleChange}
-/>
-```
-
-- While loading, the engine shows its skeleton; on rejection it renders the error message; on success it
-  renders the schema and fires `onOptionsLoaded`.
-- The loader re-runs when its **identity changes**, so memoise it (`useCallback`) keyed on its inputs — a
-  fresh function every render would refetch on every render.
-- Works in both compact and classic layouts. (Real consumer: qorus-ide's `useRemoteOptionsLoader` feeding
-  the Connection creator's protocol-specific options panel.)
-
-## Tests
-
-- **Unit:** [`__tests__/readFirst.test.ts`](../__tests__/readFirst.test.ts) — value formatting (incl.
-  colour hex/`rgba()`, file filename, hash field-count + `getHashEntries` expansion, `formatBytes`),
-  grouping, completion.
-- **Field-type catalog:** the `CompactFieldTypes` story is a literal catalog of the whole `TQorusType`
-  union (grouped by family) — every renderable type plus the non-renderable/interface-reference types —
-  asserting colour/file/hash read-first values and the hash "view more" sub-row reveal. Beyond the
-  type families it carries one-capability-per-row groups for **field chrome** (icon / image / intent /
-  badge / actions / tags), **descriptions & messages** (short_desc behind ⓘ, desc → `?` dialog,
-  Tier-1 messages auto-open, Tier-2 behind ⓘ), and **meta** (sensitive / rules / default-value note);
-  the combined worst-case stress form is `CompactShowcase` (the flagship "real form" story). Two everything-open variants:
-  `CompactFieldTypesEditing` (every row activated — all ~70 real editors mounted at once) and
-  `CompactFieldTypesEditingAllRequired` (same, but every field required and unset — each editor in
-  its required/invalid state; the canary for editors that misbehave on empty required values).
-- **Reusable disclosure:** `ReqraftCollapsibleContent` has its own
-  [`CollapsibleContent.stories.tsx`](../src/components/collapsible/CollapsibleContent.stories.tsx)
-  (tall content clips + fades with a hover "Show more"; short content shows whole; custom fade colour).
-- **`optionsLoader`:** `CompactOptionsLoader` (async load → read-first rows + `onOptionsLoaded`),
-  `CompactOptionsLoaderError` (rejection → error message), and `OptionsLoader` (classic-layout parity).
-- **Interaction:** the `Compact*` stories in
-  [`FormEngine.stories.tsx`](../src/components/form/engine/FormEngine.stories.tsx), using the shared
-  `_tests*` helpers. They mirror the classic story matrix: read-first edit (`CompactReadFirstEditing`), the
-  Fields menu / search / search-hidden / overflow + sticky-top header, revert + show-types,
-  on_change/refetch + dependents,
-  and parity scenarios — field types, `required_groups`, `any` type, readonly-default-fix,
-  non-existent-filtered, the help dialog, and render stability.
-- **Full-schema parity:** `CompactBasic` renders compact mode on the **exact** schema + value behind the
-  classic `Basic` story (the shared fixture
-  [`__fixtures__/basicFormOptions.ts`](../src/components/form/engine/__fixtures__/basicFormOptions.ts) —
-  both stories import it, so they can never drift). Every option/state the classic layout exercises runs
-  through the compact path: both hash options, file, auto, list, allowed-values (+creatable/broken), date,
-  rgbcolor, richtext, templates, messages, disabled, readonly, depends_on. Running the full fixture
-  immediately caught two real bugs: `richtextToString` crashing on scalar-valued richtext options, and
-  `getHashEntries` mis-counting typed envelopes.
-- **Workflow-orders hash view:** `StructuredDataView`
-  ([`_structuredData/`](../src/components/form/engine/_structuredData/)) is a thin Qorus wrapper
-  around **`ReqoreDataView`** (upstreamed in reqore ≥0.69 — the toolkit was bumped 0.64 → 0.69.2 for
-  it), mirroring qorus-ide's wrapper of the same name: it plugs in the Qorus typed-envelope
-  allow-list, the embedded-YAML/JSON string parser, and the Qorus date parser/formatter
-  (`structuredData.ts`). Theme-driven (key chips = `info` intent, values intent-tinted by type),
-  scalars stay on the same row as their key at any depth, objects/lists collapse to
-  `Object · N fields` / `List · N items`. It is the **only hash preview** in the compact form —
-  the earlier flat key → value sub-row view was removed after Filip signed off on the structured
-  look (`getHashEntries` remains as the "is this an expandable hash?" gate and for value
-  summaries). See the `CompactHashStructuredView` story (which also contrasts an
-  envelope-encoded hash against a raw order-style payload) plus its own
-  `Form/Engine/StructuredDataView` story. In the compact form the tree is wired up:
-  the Fields-menu **"Show field types"** toggle also drives the per-scalar type chips inside it,
-  clicking a **value chip opens the hash's editor** (parity with the flat sub-rows; section
-  summaries keep their expand/collapse clicks), and `defaultExpandDepth={2}` keeps deep nests
-  collapsed so the preview stays short before the fade. Known gap: key chips show raw keys, not
-  `arg_schema` `display_name`s — suggested upstream as
-  [reqore#568](https://github.com/qoretechnologies/reqore/issues/568) (`keyLabel` callback).
-
-Interface-specific chrome the IDE still wraps around the engine (Phase 3): the status hero, value chips
-(e.g. the language logo), "Edit code", and the "Editing this form" Hint.