feat(ui): add analytics primitives and layout patterns

2026-03-25 19:49:49 +08:00
parent cc1509d2f6
commit a5d75f42e9
63 changed files with 7751 additions and 2 deletions
@@ -0,0 +1,66 @@
+# Value Field Component
+
+- Status: `in_progress`
+- Owner: `codex`
+- Date: `2026-03-25`
+
+## Goal
+
+Add a reusable `ValueField` base component for single-line, read-only value presentation so product
+flows do not have to misuse `Input` for non-editable display values such as backup codes, reference
+ids, tokens, or generated labels.
+
+## Scope
+
+- In scope:
+  - add a new public `ValueField` component to `packages/ui`
+  - support a minimal composable surface for value display plus optional prefix/suffix content
+  - integrate with `Field` context for state and description wiring
+  - document the component in Storybook
+  - cover key behavior with unit tests
+  - use the new component in the docs-only two-factor setup pattern
+- Out of scope:
+  - multiline or rich-text display values
+  - formatted masking, async copy state, or built-in clipboard APIs
+  - replacing every read-only input in the repo
+
+## Constraints
+
+- Keep the component token-first and aligned with the existing input/card/panel visual language.
+- Do not create a second form-field system parallel to `Field`.
+- Keep the public API small and composable.
+- Prefer stable slot names and `data-*` state exposure over one-off booleans.
+
+## Affected Surfaces
+
+- `packages/ui/src/components`
+- `packages/ui/src/index.ts`
+- `packages/ui/src/lib/contracts.ts`
+- `apps/docs/src/components`
+- `apps/docs/src/patterns`
+- `docs/exec-plans`
+
+## Plan
+
+1. Add the execution plan and confirm the API should be a small read-only display primitive rather
+   than a typography helper.
+2. Implement `ValueField` in `packages/ui` with stable slots for root/value/prefix/suffix and
+   Field-context aware ids and state attributes.
+3. Add Storybook stories and update the two-factor setup pattern to use `ValueField` for the manual
+   backup code.
+4. Add unit coverage and run targeted validation for component and docs surfaces.
+
+## Validation
+
+- `pnpm build:docs`
+- targeted component test run for `ValueField`
+
+## Orchestration Task Sketch
+
+- `T1`: implement the `ValueField` component and exports
+- `T2 -> T1`: add docs stories, update the two-factor pattern, and validate
+
+## Status Log
+
+- `2026-03-25 23:40` started after confirming the repo exposes read-only input styling but no
+  dedicated single-line value display component