@lotics/ui 46.0.0 → 46.0.1

package/AGENTS.md

@@ -17,7 +17,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW, the `FilesEditor` COMPOUND for a whole section, plus the three-way file INTAKE), stage gates, and the commit-on-blur vs action-press ordering law. |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values; findings, provenance, confidence; **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, and where a commit sits. |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), and where a commit sits. |
 | [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built** — the other docs say what good looks like; this one says how to find out whether you achieved it. GATES that outrank every treatment question, then 11 probes each naming what to COLLECT and the SIGNATURE in the numbers. Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
 | [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |

package/docs/composition.md

@@ -467,6 +467,28 @@ INFORMATIONAL — they never filter or navigate (that's the tabs/chips' job); if
 cross-cutting numbers, drop them. Do NOT put a `KPIStrip` on a register page or a `SummaryLine` on
 a dashboard. Card stat rails use `KPICard`.
 
+## One fact, one surface — and no control that only reveals a number
+
+Two rules that catch the same defect from opposite ends: a screen saying one thing twice.
+
+**A selector and a detail view must not carry the same fact at the same weight.** When a compact
+chooser sits above the thing it chooses — a set of presets over the options they combine, a filter
+row over the facets it sets — the chooser is a SELECTOR and gets one line per item, and the surface
+below carries the detail. Render both as cards and the reader has to work out that the parts add up
+to the whole they already read, which is a puzzle the screen created for them. The tell is a section
+whose two halves are the same height: whichever one is a *shortcut* to the other should be a
+fraction of it.
+
+**A control whose only job is to swap one number for another is more machinery than showing both.**
+A billing-cycle toggle, a unit switch, a per-seat/per-month flip — each hides one figure behind a
+click and adds a piece of state the rest of the screen has to respect. State both: the primary as
+the headline, the alternative as a line under it. This also fixes an ordering problem the toggle
+creates, because it asks the reader to decide something secondary (how it is counted) before they
+have decided the thing itself (which one they want).
+
+The toggle earns its place when the two states differ in more than a number — different rows,
+different units, a different shape of answer. Swapping `1.700.000` for `2.000.000` is not that.
+
 ## Numbers, money, dates
 
 - Free-standing numerals: `<Text tabular>` — always.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "46.0.0",
+  "version": "46.0.1",
   "type": "module",
   "exports": {
     "./vite": {