@qoretechnologies/reqraft 0.10.65 → 0.10.66-pr.137.ga1983bf

package/.tasks/STORY_NETWORK_ISOLATION.md

@@ -1,98 +0,0 @@
-# Story network isolation — ExpressionField stories fail off-network
-
-**Status:** done pending user verify — folded into `fix/per-field-templates`
-(PR #115) so every open reqraft fix ships in one PR; not yet pushed.
-Originally built and verified on `develop` (stories 479/479, unit 930/930,
-off-network), then re-verified on the combined branch.
-
-## Symptom
-
-`yarn test:stories ExpressionField` failed 6 of 8 on `develop` locally, while the
-same file passed in CI (run 34250300001, 2026-09-08). Siblings failed the same
-way: FormEngineRemote 11/11, AutoFormField 1, SchemaDefinitionField 2,
-useWebsocket 3, TemplateField 1.
-
-## Root causes
-
-1. **An LSP connection outlived the story that opened it.** `useRenderExpression`
-   holds the endpoint's `LspSharedConnection` for the page lifetime. `Default`
-   (no mock LSP) dialled the real instance; `Empty` / `Text Mode` then joined that
-   connection's never-settling handshake, so their mock LSP was never dialled
-   ("Connecting to language server…" forever). Each passes when run alone.
-2. **The shared connection had no way out of a dead socket** (product bug). No
-   `onReconnectFailed` handling: a first handshake whose socket gave up stayed
-   pending forever for every later client; one that had completed kept reporting
-   the dead socket as ready. `close()` also abandoned an in-flight handshake, and
-   `release()` could evict a connection that had replaced its own after a reset.
-3. **Requests components make on their own were unmocked.** FormEngine gates on
-   `system/qorus-type-info`; TemplateField's "Use Expression" waits on the
-   expression catalogue; every `ReqraftWebSocket` reconnect awaits a `system/pid`
-   probe. Against an unreachable instance none settles — the form stays a
-   skeleton, the menu entry never appears, the socket never reconnects or gives
-   up. CI's live instance answered all three, which is why CI stayed green.
-4. **Mock URLs hard-coded the hq host.** Both mock layers match on host, so
-   overriding `REACT_APP_QORUS_INSTANCE` silently disabled every mock.
-
-## Fix
-
-- `src/utils/lspClient.ts` — give-up / close settle the handshake and forget the
-  socket; retry paths guarded by identity; `release()` only evicts itself.
-  4 new unit tests + the disconnect-mid-handshake test now asserts the rejection.
-- `src/stories/storyNetwork.ts` — `STORY_QORUS_INSTANCE`, `storyApiUrl`,
-  `storySocketUrl`, `GLOBAL_STORY_MOCK_DATA` (types catalogue, empty expression
-  catalogue, reconnect probe),
-  `TStoryMockResponse` (the addon silently ignores non-object responses).
-- `.storybook/preview.tsx` — `mockAddonConfigs.globalMockData`, per-story LSP
-  reset in a project `beforeEach`; `.storybook/vitest.setup.ts` mirrors the
-  addon's global + story merge.
-- All mock URLs moved to the helpers; FormEngine's duplicate types mock and
-  DpqlEditor's ad-hoc `closeAll()` removed.
-
-### Reconciled with `fix/per-field-templates`
-
-- That branch had already met the leak from the fixture side:
-  `createMockLspServer` reset the shared connections on create and close. The
-  project-level `beforeEach` covers the same ground plus stories that never
-  create a mock server (and the render client), so the fixture resets were
-  dropped in favour of the one mechanism.
-- Its `query()` strips a path's leading slash and uses a `noApiPrefix` url
-  verbatim; `buildReqraftApiUrl` follows those rules, so the doubled-slash mock
-  spellings are gone.
-- **A page-freezing render loop in the row menu** (from `a21640b`), reachable
-  only once FormEngine rendered offline: `FormEngine › Compact Expressions`
-  froze the tab and hung the whole suite with no output. The row kept ONE
-  `{key, items}` slot, and an expression's operands — separate TemplateFields
-  in the same row — published different keys into it, each overwrite
-  re-rendering the row and both operands. The same slot also kept an unmounted
-  editor's handlers when a reopened row offered the same key. Fixed in
-  `rowMenuContext.ts` (per-publisher registration via `useId`, withdrawn on
-  unmount, clicks delegated to the latest handler) and `TemplateField` (claims
-  the channel and hides it from what it renders, so operands keep their own
-  menu). Unit tests reproduce the loop and both stale-handler cases.
-- `ExpressionField › Field Menu Stays In The Toolbar` had gone stale on that
-  branch: `a21640b` moved a row field's menu into the row's ⋮ (one menu per
-  control) after the story was written. The story now asserts that single
-  menu — the row's `.options-readfirst-more`, with no `.template-more` beside
-  it — still sits level with the toolbar.
-
-## Not causes (checked)
-
-- "No Preview" in failure output: addon-vitest injects Storybook's hidden preview
-  body into every test page; a failed query's DOM dump prints it.
-- A `+` in the checkout path hangs `yarn test:stories` before any test runs
-  (mechanism not traced); unrelated to the stories.
-
-## Follow-ups (not done)
-
-- `users?action=current` is still unmocked for most stories — harmless today
-  (`waitForStorage={false}`), but CI renders a real user while local runs render
-  none. Candidate for a default mock once permission-gated snapshots are checked.
-- Unmocked requests still pass through to the network. Failing them loudly for
-  non-live stories would make this class impossible rather than documented.
-- `ReqraftWebSocketsManager.closeAll()` deletes entries by `socket.url` rather than
-  the pool key, and closing a CONNECTING socket reports code 1006, which schedules
-  a reconnect. Not exercised by this fix.
-- ~~`tests.yml` runs only on `pull_request`~~ — done on this branch: it now also
-  runs on pushes to `develop` (the push trigger had been dropped in 2021 with no
-  recorded reason). Conflicting PRs still get no `pull_request` runs until they
-  merge up.

package/.tasks/TEMPLATE_TOKEN_GRAMMAR.md

@@ -1,72 +0,0 @@
-# Template token grammar — braced context refs rehydrate as chips
-
-**Status:** in PR #96 to develop — reworked per Foxhoundn's build-123 qlip review: chips only for BRACED context refs (`isBracedTemplateToken`); plain `$local:*` word tokens keep the template-offering input (his 14 denials), matching his accepted `BracedTemplateValue` baseline. Also added the requested SchemaDefinition Empty play (wait for form rows, not just tab chrome).
-
-No standalone design doc — this is a two-repo bugfix; the qorus-ide twin
-(`src/helpers/templateValue.ts` there) is the reference for the shared
-grammar, and the drift analysis lives in the qorus-ide session that found
-it. Short form below.
-
-## Problem
-
-A saved template value in the braced state-output form —
-`$data:{W2n_BuSHbaNrbvV1MkfPF.filename}` — rehydrates as **raw token text
-in a textarea** instead of a template chip. Two causes:
-
-1. No strict token grammar existed here: `isValueTemplate` is loose
-   (starts with `$`, has `:`), and nothing could distinguish a
-   well-formed whole token from a user-typed dollar-string.
-2. `TemplateField`'s template-mode-with-custom-values branch renders
-   `LongStringField` — a plain textarea that can never chip, so ANY
-   template value (word or braced) shows as its literal text there.
-
-Reqraft's `TemplateField` is a near-1:1 extraction of qorus-ide's; the
-same bug was fixed there the same day (grammar + wiring). The qorus-ide
-IDE surface that exposed it: FSM draft 70, `split($data:{…filename}, …)`.
-
-## Surface area
-
-| File | Change |
-|---|---|
-| `src/helpers/templates.ts` | `TEMPLATE_TOKEN_SOURCE` (canonical grammar, braced segments allow `.: -` and spaces) + strict `isCompleteTemplateToken` |
-| `src/components/form/fields/template/TemplateField.tsx` | auto-mode flip guard narrowed to complete tokens; whole-token template values render the `TemplateDropdownSelector` picker chip instead of the LongString textarea |
-| `src/components/form/fields/template/TemplateField.stories.tsx` | new `BracedTemplateValue` regression story; `TemplateCanBeSelected` play updated to assert the chip (was asserting the raw-token textarea) |
-| `__tests__/templates.test.ts` | strict-grammar cases (braced, colon-braces, dashed keys, spaced paths, negatives) + alias resolution |
-| `package.json` | `0.10.36` → `0.10.38` (every-PR-bumps rule; re-bumped after develop published `0.10.37`) |
-
-### Second fix in this PR — the state-identity alias
-
-An FSM state has TWO identities: its key in the `states` hash and its own
-`id`. The IDE gives both the same nanoid, so nothing authored there can tell
-them apart — but a **template** hand-writes numbered keys (`'1'`, `'2'`, …)
-over meaningful ids (`dc_ai_reply`), its saved `$data:{…}` refs use the id,
-and the server's catalogue (`sprintf("$data:{%s.%s}", state_id, name)`)
-spells item values with the key. They never match as text, so every
-template-derived Qog printed the raw token where a named chip belongs —
-`$data:{dc_ai_reply.choices}` in the Discord assistant's Save Reply state.
-
-`findTemplate` now also accepts an item's `metadata.aliasValues`. The
-producer that holds the states (qorus-ide's `buildTemplates`) attaches the
-alternate spelling; reqraft only consumes it. Nothing rewrites either
-spelling, so a picked value still stores exactly what the catalogue says —
-this is display-only. The alternative (emitting the id from the server, or
-rewriting catalogue values FE-side) changes what new picks store and needs
-the id's uniqueness enforced first; see the qorus-side write-up.
-
-Deliberately NOT done here: the qorus-ide-style rich-editor treatment for
-template mode. Develop's `RichTextFormField` has no string mode — that is
-the in-flight `bugfix/richtext-string-storage-serialization` work
-(`returnValueType`) — and a nodes round-trip without it reintroduces the
-reset-while-typing hazard. Mixed text+token strings therefore keep the
-textarea until that lands; whole tokens (the overwhelmingly common case)
-chip now.
-
-## Phases
-
-- [x] Grammar + strict helper in `helpers/templates.ts`, unit-tested
-- [x] `TemplateField` guard + render wiring, story-tested
-- [x] `yarn precheck` green (lint, 593/593 unit, prod tsc)
-- [x] Qlip PNGs read for `BracedTemplateValue` + `TemplateCanBeSelected` (chips confirmed)
-- [x] **STOP — user signed off 2026-08-27** (see `VERIFY.local.md`)
-- [x] Commit + PR to develop — `0ef167c`; version re-checked at push time (beta `0.10.36`, ours `0.10.37` ✓; PR #95's prereleases ALSO sit at `0.10.37` — whichever merges second rebases and re-bumps)
-- [ ] Pin the CI prerelease (`0.10.37-pr.<N>.g<sha>`) in qorus-ide, lockfile committed; after merge, move qorus-ide to the released version

package/CODE_OF_CONDUCT.md

@@ -1,105 +0,0 @@
-<div align="center">
-  <br><br><br>
-  <img src="./public/qoreLogo.png" alt="Unstated Logo" width="500">
-  <br><br><br>
-</div>
-
-# Code of Conduct
-
-Qore Technologies use [Contributor Covenant v2.0](https://contributor-covenant.org/version/2/0/code_of_conduct) as their code of conduct. The full text is included [below](#contributor-covenant-code-of-conduct-v20) in English, and [translations](https://www.contributor-covenant.org/translations) are available on the Contributor Covenant website.
-
-## Commitment
-
-All recipients of reports commit to:
-
-- maintain the confidentiality with regard to the reporter and victim of an incident
-
-## Report an issue in a project
-
-1. To report an issue in one of our projects, please follow the security guidelines from that repository.
-
-## More Info
-
-For more information, refer to the full
-[Contributor covenant code of conduct page](https://contributor-covenant.org/version/2/0/code_of_conduct).
-
----
-
-## Contributor Covenant Code of Conduct v2.0
-
-### Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
-
-### Our Standards
-
-Examples of behavior that contributes to a positive environment for our community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address, without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a professional setting
-
-### Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
-
-### Scope
-
-This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
-
-### Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at the email addresses listed above in the [Reporting](#report-an-issue-in-a-project) and [Escalation](#escalate-an-issue) sections. All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the reporter of any incident.
-
-### Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
-
-#### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
-
-#### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of actions.
-
-**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
-
-#### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
-
-#### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the project community.
-
-### Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at [contributor-covenant.org/version/2/0/code_of_conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct).
-
-Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
-
-For answers to common questions about this code of conduct, see the FAQ at
-[contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are available at [contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).

package/CONTRIBUTING.MD

@@ -1,78 +0,0 @@
-<div align="center">
-  <br><br><br>
-  <img src="./public/qoreLogo.png" alt="Unstated Logo" width="500">
-  <br><br><br>
-</div>
-
-# Contributing to Qore Technologies
-
-> First off, thanks for taking the time to contribute!
-
-Contributions are always welcome. Before contributing please read the
-[code of conduct](CODE_OF_CONDUCT.md) &
-[search the issue tracker](https://github.com/qoretechnologies/qorus-ui/issues) your issue may have already been discussed or fixed in `master`. To contribute,
-[fork](https://help.github.com/articles/fork-a-repo/) QorusToolkit, commit your changes,
-& [send a pull request](https://help.github.com/articles/using-pull-requests/).
-
-We put together a set of guidelines for contributing to Qore Technologies and it's packages, which are hosted in the [Qore Technologies Organization](https://github.com/qoretechnologies/reqore) on GitHub. The provided guidelines are not rules but recommendations. Use your best judgement, and feel free to propose changes to this document with a pull request.
-
-## We host our open-source on Github
-
-We use github to host our open-source code, to track issues and feature requests, as well as accept pull requests.
-
-> We Use [Github Flow](https://guides.github.com/introduction/flow/index.html) for code contributions
-
-## How to contribute
-
-Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
-
-1. Fork the repo and create your branch from `develop`.
-2. If you've added code that should be tested, add tests.
-3. If you've changed APIs, update the documentation.
-4. Ensure the test suite passes.
-5. Make sure your code lints.
-6. Issue that pull request!
-
-## Any contributions you make will be under the MIT Software License
-
-In short, when you submit code changes, your submissions are understood to be under the same [MIT License](http://choosealicense.com/licenses/mit/) that covers the project. Feel free to contact the maintainers if that's a concern.
-
-## Report bugs using Github's issues
-
-We use GitHub issues to track public bugs. Report a bug by opening a new issue on <code>github.com/qoretechnologies/qorus-ui/issues</code> it's that easy!
-
-## Write bug reports with detail, background, and sample code
-
-**Great Bug Reports** tend to have:
-
-- A quick summary and/or background of a bug
-- Steps to reproduce
-  - Be specific!
-  - Give sample code if you can.
-- Expected behavior according to your understanding
-- Current behavior which includes the bug
-- Notes (includes, your reasoning behind the problem or steps you tried to solve the bug)
-
-We _love_ thorough bug reports so that we can act fast on them.
-
-## Use a Consistent Coding Style
-
-> Reference [Facebook's Guidelines](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md)
-
-- 2 spaces for indentation rather than tabs
-- 100 character line length
-- Run `npm run lint` to conform to our lint rules
-
-## Community
-
-- [GitHub Organization](https://github.com/qoretechnologies) for Official open-source projects
-- [Discord](https://discord.gg/MWUwDKRR) for support, discussion, news and latest release updates
-- [Qore Technologies Website](https://www.qoretechnologies.com)
-
-## License
-
-By contributing, you agree that your contributions will be licensed under its MIT License.
-
-## References
-
-This document was adapted from the open-source contribution guidelines for Reference [Facebook's Guidelines](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md)

package/SECURITY.md

@@ -1,3 +0,0 @@
-# Reporting and Fixing Security Issues
-
-Please do not open GitHub issues or pull requests - this makes the problem immediately visible to everyone, including malicious actors. Security issues in Reqore can be safely reported via email <b>security@qoretechnologies.com</b>

package/chromatic.config.json

@@ -1,5 +0,0 @@
-{
-  "onlyChanged": true,
-  "projectId": "Project:662bcb94acac0fd11755c83a",
-  "zip": true
-}

package/design/COMPACT_ENGINE_REDESIGN.md

@@ -1,156 +0,0 @@
-# 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/COMPACT_INFO_DISPLAY.md

@@ -1,87 +0,0 @@
-# Compact mode — descriptions, short descriptions & messages
-
-**Status: DECIDED — `stripe-expand` (variant C), 2026-06-11.** Promoted to be *the* compact
-info display: an intent edge-stripe on rows carrying Tier-1 messages plus a per-row expandable
-panel (short_desc + all messages; auto-open on Tier 1, ⓘ toggle in the fixed info slot
-otherwise). The losing variants (subtitle-inline, icon-cluster, adaptive), the temporary
-`compactInfoDisplay` prop, and the Compare sidebar folder (`FormEngineCompare.stories.tsx`)
-were deleted per the `compactHashView` lifecycle. The stress coverage lives on as the regular
-stories **CompactShowcase** and **CompactShowcaseMobile** (360 px) in
-`FormEngine.stories.tsx`. While a row is being edited inline, the editor suppresses its own
-schema-message strip — the panel below the editing row is the single renderer.
-Tier-1/Tier-2 computation is shared with the editor via the extracted
-`getOptionFieldMessages` helper (`OptionFieldMessages.tsx`) — one source of truth.
-(The 360 px finding from the evaluation — value cells truncating in the three-column grid —
-was resolved by the responsive pass: rows stack below 480 px measured form width.)
-
-Before this work the compact (read-first) form hid almost all field *information* until a row
-was expanded. This doc inventories what a field can carry, classifies how urgently each piece
-must be seen, and sets the acceptance criteria the shipped display meets. The four-variant
-evaluation that drove the pick is archived in §5 (the `compactHashView` lifecycle: build as
-knobs → compare in stories → pick → delete the losers).
-
-## 1. Inventory — what information a field can carry
-
-Grounded in the engine/schema (`FormEngine.tsx`, `OptionFieldMessages.tsx`, the Basic fixture):
-
-| Information | Source | Intent | Today in compact (read row) |
-|---|---|---|---|
-| Schema **messages** | `schema.messages[]` `{intent, title, content}` | success / info / warning / **danger** | **Invisible** — only rendered inside the expanded editor (`renderOption`) |
-| **Validation / required** | `isOptionValid`, `required`, `required_groups` | danger / warning | `Required` tag on the row; group context invisible |
-| **Dependency state** | `OptionFieldMessages`: "disabled because dependencies are not fulfilled: X", required-group hints | warning / danger | **Invisible** until expanded |
-| **Short description** | `schema.short_desc` | neutral | Hover `title` tooltip — useless on touch |
-| **Long description** | `schema.desc` (markdown) | neutral | `?` icon → help dialog (works, incl. touch) |
-| **Default-value note** | `default_value_desc`, `default_value_display_name` | neutral | Invisible |
-| Read-only / disabled reason | `readonly`, `disabled` flags | neutral | Lock icon only (readonly); disabled rows look normal |
-
-## 2. Criticality tiers (the actual decision behind "what must show before open")
-
-- **Tier 1 — visible without any interaction:** danger/warning messages, validation state,
-  "disabled because of unmet dependency". If a user never expands the row, they must still see
-  these. *(Today: mostly invisible — the real gap.)*
-- **Tier 2 — glanceable, one tap away at most:** `short_desc`, info/success messages,
-  default-value note, required-group membership ("one of: …").
-- **Tier 3 — on demand:** long markdown `desc` (the existing `?` dialog is fine).
-
-## 3. Acceptance criteria (pass/fail per variant)
-
-1. Works at **~360 px** width (phone) — no horizontal overflow, everything reachable by tap.
-2. **No hover-only affordances.** Tooltips/popovers must open on tap (reqore supports
-   `handler: 'click'`).
-3. A field with **no** Tier-1 info and **no** short_desc stays a **single ~38 px row** — "doesn't
-   crowd the view", made measurable.
-4. Tier-1 info is readable **without any interaction** (colour alone is not enough — icon/text too).
-5. Uses existing product language: `ReqoreMessage` intents, `ReqoreTag` badges, the muted-subtitle
-   style the IDE restyled creator already uses for field descriptions
-   (`RestyledFields.tsx` renders desc as a muted 12 px line under the label).
-
-## 4. Research notes
-
-**In-product conventions (consistency first):**
-- The IDE restyled creator shows the field description as a **muted line under the label** — the
-  exact pattern is already shipped in the form this compact mode replaces.
-- `ReqoreMessage` (small/minimal/opaque=false) is the established intent-strip; the engine already
-  uses it inside editors and for the invalid-fields banner.
-- Intent-tinting (Draft/Ready badge, DataView value chips) is the established "severity at a
-  glance" language; reqore popovers support `handler='click'` for touch.
-
-**External (design systems / UX research):**
-- Helper text belongs **below/beside the field, persistently visible**, not in placeholders or
-  hover tooltips; long hints must wrap — key for mobile
-  ([UX Collective](https://uxdesign.cc/text-fields-forms-design-ui-components-series-2b32b2beebd0),
-  [UI Content](https://uicontent.co/designing-help-text-for-form-fields-real-examples/),
-  [NN/g on placeholders](https://www.nngroup.com/articles/form-design-placeholders/)).
-- Inline validation: show the indicator **next to the field**, with the message adjacent
-  ([Smart Interface Design Patterns](https://smart-interface-design-patterns.com/articles/inline-validation-ux/),
-  [NN/g error guidelines](https://www.nngroup.com/articles/errors-forms-design-guidelines/)).
-- **Alert icons alone are easy to miss in dense UIs** — a badge/icon-only variant risks failing
-  Tier 1; severity colour coding (ok/warning/critical) works when paired with text.
-
-## 5. Decision record
-
-The four-variant evaluation (proposals A–D, the comparison matrix, and the review
-checklist) lived here while the pick was open. `stripe-expand` (variant C) won on
-2026-06-11; the losing variants and the temporary `compactInfoDisplay` prop were
-deleted. The full pre-decision analysis is preserved in the task log
-([.tasks/FORM_ENGINE_COMPACT_READ_FIRST.md](../.tasks/FORM_ENGINE_COMPACT_READ_FIRST.md),
-"Info-display variant evaluation (archived)").