@mantis-core/ui 0.4.0 → 0.6.0

package/docs/components/tag.md

@@ -0,0 +1,27 @@
+---
+name: Tag
+category: feedback
+import: '@mantis-core/ui/components/feedback/Tag'
+whenToUse: Styled label chip for status labels, categories, or counts; wraps the PR11 Tag primitive.
+baseLibrary: '@primereact/ui/tag'
+relatedComponents: ['StatusBadge', 'Avatar']
+relatedNextCore: []
+props:
+  - { name: children, type: ReactNode, required: false, description: 'Tag content — PR11 dropped value/icon; content is now children.' }
+  - { name: severity, type: "'secondary' | 'success' | 'info' | 'warn' | 'danger' | 'contrast'", required: false }
+  - { name: rounded, type: boolean, required: false, default: 'false' }
+---
+
+## Example
+
+```tsx
+import Tag from '@mantis-core/ui/components/feedback/Tag';
+
+function Example() {
+  return <Tag severity='success' rounded>Sold</Tag>;
+}
+```
+
+## Notes
+
+- PR11 `Tag` has no `value`/`icon` props like PR10 did — pass content as `children` instead.

package/docs/components/tags-input.md

@@ -0,0 +1,32 @@
+---
+name: TagsInput
+category: forms
+import: '@mantis-core/ui/components/Forms/TagsInput'
+whenToUse: RHF-bound tag/chip input over PR11's compound InputTags; stores value as string[].
+baseLibrary: '@primereact/ui/inputtags'
+formContract: FieldControllerProps
+relatedComponents: []
+relatedNextCore: []
+props:
+  - { name: placeholder, type: string, required: false, description: 'Shown on the entry input only while no tags are present.' }
+  - { name: max, type: number, required: false, description: 'Max number of tags.' }
+  - { name: delimiter, type: 'string | RegExp', required: false, description: 'Extra character(s) that commit a tag besides Enter.' }
+  - { name: allowDuplicate, type: boolean, required: false }
+---
+
+## Example
+
+```tsx
+import { TagsInput } from '@mantis-core/ui/components/Forms/TagsInput';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { tags: [] as string[] } });
+  return <TagsInput name='tags' control={control} label='Etiquetas' placeholder='Agregar etiqueta...' />;
+}
+```
+
+## Notes
+
+- Value shape: `string[]`, `[]` when unset. Enter (or `delimiter`) commits a tag; Backspace on an empty entry removes the last one.
+- Chips render as themed `Chip.*`; the entry input is chrome-less (`.p-inputtags` owns the border/focus ring) to avoid a doubled focus ring.

package/docs/components/text-area.md

@@ -1,20 +1,30 @@
-# TextArea
-
-- Export: `TextArea`
-- Extra exports: `TextAreaProps`
-- Import: `import { TextArea } from "@mantis-core/ui";`
-- Base library: `primereact/inputtextarea`
-- Base typing: `Omit<InputTextareaProps, "name" | "defaultValue" | "ref" | "onChange"> & { controller: ControllerProps; block?: boolean; loading?: boolean }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/inputs.scss`
+---
+name: TextArea
+category: forms
+import: '@mantis-core/ui/components/Forms/TextArea'
+whenToUse: Multi-line text field wired to react-hook-form.
+baseLibrary: '@primereact/ui/textarea'
+formContract: FieldControllerProps
+relatedComponents: ['TextField']
+relatedNextCore: []
+props:
+  - { name: rows, type: number, required: false, description: 'Native <textarea> passthrough beyond FieldControllerProps.' }
+---
 
 ## Example
 
 ```tsx
-<TextArea
-  controller={{ name: "description", control: form.control }}
-  block
-  rows={6}
-  autoResize
-/>
+import { TextArea } from '@mantis-core/ui/components/Forms/TextArea';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { notes: '' } });
+  return <TextArea name='notes' control={control} label='Notes' rows={4} />;
+}
 ```
+
+## Notes
+
+- Thin wrapper over PR11 `Textarea`: value/onChange are native (`e.target.value`).
+- Any extra prop not listed above (native `<textarea>` attrs or `TextareaProps`) passes straight
+  through as an escape hatch.

package/docs/components/text-field.md

@@ -0,0 +1,32 @@
+---
+name: TextField
+category: forms
+import: '@mantis-core/ui/components/Forms/TextField'
+whenToUse: Single-line text field wired to react-hook-form.
+baseLibrary: '@primereact/ui/inputtext'
+formContract: FieldControllerProps
+relatedComponents: ['TextArea', 'NumberField', 'FieldShell']
+relatedNextCore: []
+props:
+  - { name: placeholder, type: string, required: false, description: 'Native <input> passthrough beyond FieldControllerProps.' }
+  - { name: maxLength, type: number, required: false, description: 'Native <input> passthrough beyond FieldControllerProps.' }
+---
+
+## Example
+
+```tsx
+import { TextField } from '@mantis-core/ui/components/Forms/TextField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { title: '' } });
+  return <TextField name='title' control={control} label='Title' rules={{ required: true }} />;
+}
+```
+
+## Notes
+
+- Thin wrapper over PR11 `InputText`: value/onChange are native (`e.target.value`), unlike the
+  compound `InputNumber`/`Select` primitives.
+- Any extra prop not listed above (native `<input>` attrs or `InputTextProps`) passes straight
+  through as an escape hatch.

package/docs/components/timeline.md

@@ -0,0 +1,31 @@
+---
+name: Timeline
+category: data
+import: '@mantis-core/ui/components/data/Timeline'
+whenToUse: Vertical event timeline backed by the PR11 Timeline compound; items render a title, description, date, and optional icon/color.
+baseLibrary: '@primereact/ui/timeline'
+relatedNextCore: []
+props:
+  - { name: items, type: '{ title: string; description?: string; date?: string; icon?: ReactNode; color?: string }[]', required: true }
+---
+
+## Example
+
+```tsx
+import Timeline from '@mantis-core/ui/components/data/Timeline';
+
+function Example() {
+  return (
+    <Timeline
+      items={[
+        { title: 'Lead created', date: '2025-01-10', description: 'Web form' },
+        { title: 'Contacted', date: '2025-01-11' },
+      ]}
+    />
+  );
+}
+```
+
+## Notes
+
+- PR11's `Timeline` is fully compound (`Root`/`Event`/`Separator`/`Marker`/`Connector`/`Content`) with no render-prop API — the wrapper maps each `items` entry onto the sub-part tree for you, so callers keep the old flat item-list shape.

package/docs/components/toggle-inline-button.md

@@ -1,22 +1,53 @@
-# ToggleInlineButton
-
-- Export: `ToggleInlineButton`
-- Extra exports: `ToggleInlineButtonProps`
-- Import: `import { ToggleInlineButton } from "@mantis-core/ui";`
-- Base library: `primereact/selectbutton`
-- Base typing: `{ controller: ControllerProps; options: any[]; variant?: ButtonVariant; multiple?: boolean }`
-- Form contract: [`ControllerProps`](../contracts/controller-props.md)
-- Required styles: `@mantis-core/styles/scss/select-button.scss`
+---
+name: ToggleInlineButton
+category: forms
+import: '@mantis-core/ui/components/Forms/ToggleInlineButton'
+whenToUse: Segmented single- or multi-choice control over PR11's ToggleButtonGroup; pass `multiple` for array-value mode.
+baseLibrary: '@primereact/ui/togglebutton'
+formContract: ChoiceFieldControllerProps
+relatedComponents: ['RadioGroup', 'SelectField']
+relatedNextCore: []
+props:
+  - { name: options, type: 'Record<string, unknown>[]', required: true, description: 'Option rows rendered as segments.' }
+  - { name: optionLabel, type: string, required: false, default: '''label''', description: 'Key read for each option''s display label.' }
+  - { name: optionValue, type: string, required: false, default: '''value''', description: 'Key read for each option''s bound value.' }
+  - { name: multiple, type: boolean, required: false, default: 'false', description: 'Array-value mode; toggles per-segment selection instead of single scalar selection.' }
+  - { name: renderOption, type: '(option: Record<string, unknown>, index: number) => ReactNode', required: false, description: 'Escape hatch: full custom per-segment render.' }
+---
 
 ## Example
 
 ```tsx
-<ToggleInlineButton
-  controller={{ name: "visibility", control: form.control }}
-  variant="accent"
-  options={[
-    { label: "Public", value: "public" },
-    { label: "Private", value: "private" },
-  ]}
-/>
+import { ToggleInlineButton } from '@mantis-core/ui/components/Forms/ToggleInlineButton';
+import { useForm } from 'react-hook-form';
+
+const VIEWS = [
+  { label: 'List', value: 'list' },
+  { label: 'Grid', value: 'grid' },
+];
+
+function Example() {
+  const { control } = useForm({ defaultValues: { view: 'list' } });
+  return (
+    <ToggleInlineButton
+      name='view'
+      control={control}
+      label='View'
+      options={VIEWS}
+      optionLabel='label'
+      optionValue='value'
+    />
+  );
+}
 ```
+
+## Notes
+
+- Value shape: scalar (or `null`) by default; an ARRAY when `multiple` — selecting a segment
+  appends its value, deselecting filters it out.
+- `labelMode` defaults to `'beside'` for this wrapper (not the global config default).
+- PR11 `11.0.0-rc.1` gotcha (same as `RadioGroup`): the styled `ToggleButtonGroup` and
+  `ToggleButton.Root` are wired through two different React contexts in this rc, so the group's
+  `value`/`onValueChange` never reaches its children (verified in-browser). Until fixed upstream,
+  this wrapper binds each `ToggleButton.Root` individually via its documented `pressed`/
+  `onPressedChange` props; `ToggleButtonGroup` itself is used for layout/styling only.

package/docs/components/upload-files-preview.md

@@ -1,26 +1,45 @@
-# UploadFilesPreview
-
-- Export: `UploadFilesPreview`
-- Extra exports: `UploadFilesPreviewProps`, `UploadPreviewItem`, `UploadFilesPreviewCopy`
-- Import: `import { UploadFilesPreview } from "@mantis-core/ui";`
-- Base library: custom upload queue and sortable preview grid
-- Base typing: `UploadFilesPreviewProps<TItem extends UploadPreviewItem = UploadPreviewItem>`
-- Required styles: none
+---
+name: UploadFilesPreview
+category: forms
+import: '@mantis-core/ui/components/Forms/UploadFilesPreview'
+whenToUse: Drag-and-drop upload zone with live preview grid, drag-to-reorder, and async upload queue; designed for image galleries, not react-hook-form bound.
+baseLibrary: custom
+relatedComponents: [FileDropzone]
+relatedNextCore: []
+props:
+  - { name: previews, type: 'TItem[]', required: false, default: '[]', description: 'Already-uploaded items to display in the preview grid' }
+  - { name: onUploadFile, type: '(file: File) => Promise<TItem>', required: true, description: 'Called per file; resolves to the stored item' }
+  - { name: onFileUploaded, type: '(file: TItem) => void', required: true, description: 'Called after each successful upload' }
+  - { name: onRemoveFile, type: '(item: TItem) => void', required: true, description: 'Called when user removes a preview item' }
+  - { name: onReorder, type: '(items: TItem[]) => void', required: true, description: 'Called after drag-to-reorder with new order' }
+  - { name: accept, type: string, required: false, default: '''image/*''', description: 'Accepted MIME types for the file input' }
+  - { name: disabled, type: boolean, required: false, default: 'false', description: 'Disable uploads and interactions' }
+  - { name: disabledMessage, type: string, required: false, description: 'Message shown in the drop zone when disabled' }
+  - { name: copy, type: 'Partial<UploadFilesPreviewCopy>', required: false, description: 'Override any UI text strings' }
+---
 
 ## Example
 
 ```tsx
-type PhotoItem = {
-  id: string;
-  fullUrl: string;
-  storagePath: string;
-};
+import UploadFilesPreview from '@mantis-core/ui/components/Forms/UploadFilesPreview';
 
-<UploadFilesPreview<PhotoItem>
-  previews={photos}
-  onUploadFile={uploadPhoto}
-  onFileUploaded={(photo) => setPhotos((prev) => [...prev, photo])}
-  onRemoveFile={(photo) => removePhoto(photo.id)}
-  onReorder={setPhotos}
-/>
+function Example() {
+  return (
+    <UploadFilesPreview
+      previews={[{ id: '1', fullUrl: 'https://example.com/photo.jpg' }]}
+      onUploadFile={async (file) => ({ id: file.name, fullUrl: URL.createObjectURL(file) })}
+      onFileUploaded={() => {}}
+      onRemoveFile={() => {}}
+      onReorder={() => {}}
+    />
+  );
+}
 ```
+
+## Notes
+
+- Generic over `TItem extends { id: string; fullUrl: string }` — pass richer item shapes for
+  gallery-specific metadata.
+- Uploads run per-file via `Promise.allSettled`; a failed `onUploadFile` marks that item `error` in
+  the queue with a discard action, it does not throw or block the rest of the batch.
+- Not react-hook-form bound — the parent owns `previews` state and persistence via the callbacks.

package/docs/components/use-field-controller.md

@@ -0,0 +1,58 @@
+---
+name: useFieldController
+category: forms
+import: '@mantis-core/ui/components/Forms/useFieldController'
+whenToUse: 'Hook every RHF field wrapper calls internally to wire useController + a stable id/aria/disabled/error-message resolution; call it directly only when hand-building a new field wrapper (see field-controller.md).'
+baseLibrary: custom
+formContract: FieldControllerProps
+relatedComponents: ['FieldShell', 'TextField']
+relatedNextCore: []
+props: []
+---
+
+## Example
+
+```tsx
+import { FieldShell } from '@mantis-core/ui/components/Forms/FieldShell';
+import { useFieldController, type FieldControllerProps } from '@mantis-core/ui/components/Forms/useFieldController';
+import { useForm, type FieldValues, type FieldPath } from 'react-hook-form';
+
+function RatingField<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>>(
+  props: FieldControllerProps<TFieldValues, TName>,
+) {
+  const f = useFieldController<TFieldValues, TName>(props);
+  return (
+    <FieldShell id={f.id} label={props.label} errorMessage={f.errorMessage}>
+      <input
+        id={f.id}
+        type='number'
+        value={(f.field.value as number) ?? 0}
+        onChange={(e) => f.field.onChange(Number(e.target.value))}
+        onBlur={f.field.onBlur}
+        disabled={f.disabled}
+        {...f.aria}
+      />
+    </FieldShell>
+  );
+}
+
+function Example() {
+  const { control } = useForm({ defaultValues: { rating: 0 } });
+  return <RatingField name='rating' control={control} label='Rating' />;
+}
+```
+
+## Notes
+
+- Takes `FieldControllerProps` verbatim (no extra params) — see
+  [`field-controller.md`](../contracts/field-controller.md) for the full prop list.
+- Returns `{ field, fieldState, formState, id, errorId, helpId, variant, size, fluid, invalid,
+  disabled, errorMessage, aria }`. `disabled` is `props.disabled || formState.isSubmitting`;
+  `aria` is `{ 'aria-invalid', 'aria-describedby' }` (error id wins over help id) — PR11's own
+  `invalid` prop only drives styling, so this hook is the one place aria-invalid gets emitted.
+- Portal-based compounds (e.g. `Select`) have no native blur — call `field.onBlur()` from the
+  compound's `onOpenChange` (fired on close) instead of relying on a bare blur event, and spread
+  `aria` onto the trigger element rather than a hidden input.
+- `TFieldValues` defaults to `FieldValues` (untyped): if a caller omits both `control` and an
+  explicit generic, `name` silently accepts any string — pass `control` (or an explicit generic) to
+  keep full path-typing.

package/docs/components/user-menu.md

@@ -0,0 +1,39 @@
+---
+name: UserMenu
+category: auth
+import: '@mantis-core/ui/components/auth/UserMenu'
+whenToUse: Topbar avatar-triggered dropdown (custom nav items + sign-out); no auth-lib coupling.
+baseLibrary: '@primereact/ui/menu'
+requiredStyles: []
+relatedComponents: [Avatar]
+relatedNextCore: []
+props:
+  - { name: user, type: UserMenuUser, required: true, description: '{ name?, email?, avatarUrl? } — displayName falls back to email.' }
+  - { name: items, type: 'UserMenuItem[]', required: false, description: '{ label, icon?, href?, onClick? }; href navigates via next/navigation, otherwise onClick fires.' }
+  - { name: onSignOut, type: '() => void', required: false, description: 'When set, appends a separator + sign-out item.' }
+  - { name: signOutLabel, type: string, required: false, default: '"Cerrar sesión"' }
+  - { name: className, type: string, required: false }
+---
+
+## Example
+
+```tsx
+import UserMenu from '@mantis-core/ui/components/auth/UserMenu';
+
+function Example() {
+  return (
+    <UserMenu
+      user={{ name: 'Diego Condo', email: 'diego@example.com' }}
+      items={[{ label: 'Perfil', icon: 'pi pi-user', href: '/perfil' }]}
+      onSignOut={() => console.log('sign out')}
+    />
+  );
+}
+```
+
+## Notes
+
+- Migrated to PR11's compound `Menu`: `Menu.Root` owns open state; `Menu.Trigger` renders `as="button"`
+  wrapping the migrated `Avatar`. No manual outside-click listener or inline dropdown (PR10 shape) left.
+- Each entry fires through `onSelect` — `href` items call `router.push` (next/navigation), `onClick`
+  items just run their handler. `icon` is a PrimeIcons class string (e.g. `pi pi-cog`), not a component.

package/docs/contracts/STORYBOOK_IMPLEMENTATION_AND_VOBO.md

@@ -0,0 +1,92 @@
+# Storybook Implementation & VoBo Rules — Mantis Core PR11 Forms stage
+
+This is the executable contract for finishing the PrimeReact 11 migration of the **reusable** surface
+(Forms family + `Button` + Toast) using Storybook as the isolated workbench and sign-off (VoBo) surface.
+A subagent implementing a component MUST follow **Rule Set 1**; a reviewer/supervisor signing off MUST
+apply **Rule Set 2**. Non-Forms components and `apps/demo-prime11` are FROZEN this stage (do not touch).
+
+Scope this stage: existing Forms wrappers (buckets A/B/C), `Button`, Toast migration, and the
+`useDataTableQuery` hook. **Deferred** (segregated but NOT built now): CheckboxGroup, Knob, Listbox,
+ToggleButtonGroup, ButtonGroup, SpeedDial.
+
+---
+
+## Forms segregation by compatibility (READ FIRST)
+
+`ifta`/`float` label modes and icon-fields (`InputGroup` addons) apply **only** to text-box inputs.
+Wrapping a checkbox/rating/otp in `FloatLabel`/`IftaLabel`/`InputGroup` breaks the render. Fields are
+segregated into buckets; the props contract is restricted per bucket so misuse fails at compile time.
+
+| Bucket | Components | labelMode | Icon addons | Props contract |
+| --- | --- | --- | --- | --- |
+| **A — text-box** | TextField, TextArea\*, NumberField, PasswordInput, SearchInput, MaskField, PhoneInput, SelectField, AutoCompleteField, DateField, TagsInput | `ifta` \| `float`(in/on/over) \| `beside` \| `none` | **Yes** (`addonBefore`/`addonAfter`) | `FieldControllerProps` (full) |
+| **B1 — toggle inline** | CheckboxField, SwitchField, ToggleInlineButton | `beside` \| `none` (default `beside`) | No | `ChoiceFieldControllerProps` |
+| **B2 — group/range** | RadioGroup, RangeSlider, RatingInput, OtpInput, ColorPickerInput | `top` \| `none` (default `top`) | No | `ChoiceFieldControllerProps` |
+| **C — special** | CKEditorInput, FileDropzone (+UploadFilesPreview) → `top`/`none`; HiddenField → no shell | per row | No | own |
+
+\* TextArea: label modes yes; icon addons limited/none (document it). PasswordInput/SearchInput/DateField
+have a built-in icon/trigger — document interaction with `addonAfter`.
+
+`ChoiceFieldControllerProps = Omit<FieldControllerProps, "labelMode"|"floatVariant"|"addonBefore"|"addonAfter"|"variant"> & { labelMode?: "beside"|"top"|"none" }`.
+
+---
+
+## Rule Set 1 — Implementation
+
+### 1a. General (every reusable component)
+
+1. **Clean PR11 API.** No legacy PR10 aliases; named imports from PR11 subpaths; use the primitive's compound/headless model.
+2. **Reusable wrapper contract.** Extend/compose the primitive props; **merge `className`/`style`** (never swallow); spread safe `...rest`; overrideable defaults; **typed variants**; `forwardRef` when focus/overlay/scroll/interop matters.
+3. **Token styling.** Base tokens / CSS vars only; **no hardcoded colors**; keep the `mantis-core-*` namespace; `cssLayer` order `theme, base, primereact`.
+4. **Layers.** `app → modules|components|lib`, `components → lib`. Forbidden: `components→modules`, `lib→modules`, `lib→app`.
+5. **Strict typing.** No `any`; `pnpm -s tsc --noEmit` clean.
+6. **Story required**, co-located, with the bucket's minimum set. No story ⇒ not done.
+7. **Fix = root cause.** A defect a story reveals is fixed at the shared point, not patched per caller.
+
+### 1b. Forms-specific (configurable fields + RHF)
+
+8. **Every field routes through the shared contract:** `useFieldController` (RHF binding + aria + id) → `FieldShell` (label/addon/help/error). Do not re-implement binding or label placement in the field.
+9. **Honor the axis per bucket:** A respects `labelMode`(ifta/float/beside/none), `floatVariant`, `variant`, `size`, `fluid` from `useFieldConfig` with per-prop override; B1/B2 use `ChoiceFieldControllerProps` (label `beside`/`top`/`none`, no float/ifta/addons/variant). Never hardcode an applicable axis.
+10. **Wire value/onChange/onBlur** correctly to the PR11 primitive; **one** `useController` per component.
+11. **Type coercion at the controller level** when the primitive emits a different shape than the form (NumberField, DateField, OtpInput…). Document the `field.value` shape.
+12. **Icon groups only in bucket A** via `addonBefore`/`addonAfter`. Pass the addon **wrapped in `InputGroup.Addon`** (from `@primereact/ui/inputgroup`), e.g. `addonBefore={<InputGroup.Addon>@</InputGroup.Addon>}` — raw content (a bare `<span>`) renders detached/unstyled. `FieldShell` owns `InputGroup.Root`; the consumer never wraps the whole field. B/C expose no addons.
+13. **Cross-field dependencies** use `useWatch` (never `watch()` in render).
+14. **`required` marker is presentational**; validation lives in `rules`.
+15. **Docs.** Update the component doc frontmatter / `catalog.json` (`pnpm gen:catalog`) with the `field.value` shape and supported config axes.
+
+### Parametrization (cross-cutting)
+
+Every component must be configurable **globally** (context provider: `MantisThemeProvider` → theme/colors/surfaces/dark + `FieldConfigProvider` → labelMode/floatVariant/variant/size/fluid) **or independently** (per-prop override). `Button` and Toast are parametrized by **theme tokens** (no hardcoded color). Everything is exercised from Storybook: global axes via toolbar `globalTypes`, overrides via per-story args.
+
+### Story taxonomy (CSF3) — per bucket
+
+Common to all: `Default`, `Playground` (args via `argTypes`), `Invalid` (with `errorMessage`), `Disabled`,
+`HelpText`, `WithReactHookForm` (form-decorator with `defaultValues` + submit that shows the captured value).
+Dark mode and size/variant are exercised via toolbar toggles, not separate stories.
+
+- **A (text-box)** — add: `LabelModes` (matrix ifta / float·in / float·on / float·over / beside / none), `Sizes`, `Variants` (outlined/filled), `Fluid`, `WithAddons`. `Async`/`Empty` where applicable (Select/AutoComplete).
+- **B1 (toggle inline)** — add: `LabelBeside`, `LabelNone`. NO float/ifta `LabelModes`, NO `WithAddons`.
+- **B2 (group/range)** — add: `LabelTop`, `LabelNone`, plus control-specific stories (RadioGroup `Options`/`renderOption`, Rating `stars`, Slider `range`). NO float/ifta, NO addons.
+- **C (special)** — a story fitting the component; no label/addon axes.
+- **Button** — `Variants`, `Sizes`, `Severities`, `Outlined`, `Text`, `Rounded`, `Loading`, `Disabled`.
+
+---
+
+## Rule Set 2 — Review & VoBo
+
+A component gets VoBo only when **ALL** hold:
+
+1. **Typing** — `pnpm -s tsc --noEmit` clean; no `any`; generics `<TFieldValues, TName>` correct.
+2. **Best practices / lint** — `pnpm lint` clean; meets the wrapper contract (merge `className`, `...rest`, `forwardRef`, defaults, typed variants); no hardcoded colors.
+3. **Scalability** — composes over the primitive (does not duplicate it); honors the config axis; no layer-breaking coupling.
+4. **Meets Rule Set 1** — item-by-item (incl. 1b for Forms).
+5. **Risk tests** — Vitest green: RHF (value shape, coercion), state, async, transformation.
+6. **Visual VoBo (most important)** — in the running Storybook, walk **every** story: it looks right; styles not bugged; **no overflow / no "arrows sticking out"**; alignment/spacing/focus/hover/dark/size correct; overlays/portals positioned; **zero console errors**. Check each `labelMode`/`floatVariant` and the icon groups specifically.
+7. **Supervisor VoBo** — final human sign-off, recorded per component in the ledger.
+
+**Support automation (cheap, advisory):** a11y addon (axe) 0 violations per story; render-smoke with no console
+errors. `@storybook/test-runner` (Playwright) and Chromatic are deferred — add only if manual visual review
+stops scaling.
+
+Record sign-off in `STORYBOOK_VOBO_LEDGER.md`. A component is not `done` until its row is complete and the
+supervisor has signed.