@umbra.ui/core 0.4.6 → 0.5.0

package/src/skills/umbra.ui-input-search/SKILL.md

@@ -0,0 +1,43 @@
+# Umbra Skill: Search Overlay
+
+Use this skill for global/local search overlays built with `SearchOverlay` and `SearchResultCell`.
+
+## When To Use
+- You need a keyboard-driven searchable overlay UI.
+- You need paged results with optional "load more".
+- You need customizable result rendering with path segments.
+
+## Required Context Checklist
+- Open/close control state and trigger mechanism.
+- Query state, results state, and active index state.
+- Search provider contract (search, recent, select, pagination).
+- Selection behavior (navigate, focus item, open detail, etc.).
+- Slot customization vs default result cell usage.
+
+## Ask Developer If Missing
+- "What data provider should back search and recent results?"
+- "What should happen when a result is selected?"
+- "Do we need custom result rendering, or default `SearchResultCell`?"
+- "How should pagination/load-more work?"
+
+## Implementation Recipe
+1. Import `SearchOverlay` and optionally `SearchResultCell`.
+2. Manage state:
+   - `isOpen`, `query`, `results`, `activeIndex`, `canLoadMore`
+3. Render `SearchOverlay` with two-way updates:
+   - `@update:model-value`
+   - `@update:query`
+   - `@update:active-index`
+4. Wire `@select` and `@load-more`.
+5. Optionally use `#result` slot with `SearchResultCell`.
+
+## Validation And Edge Cases
+- Keyboard nav (up/down/enter/escape) works.
+- Active index resets safely when result set changes.
+- Load-more appends without scroll glitches.
+- Empty states and recent-results mode render correctly.
+
+## Definition Of Done
+- Overlay opens/closes and query updates correctly.
+- Results render and select behavior is correct.
+- Provider and pagination integration is stable.

package/src/skills/umbra.ui-input-search/reference.md

@@ -0,0 +1,45 @@
+# Reference: Search Input Family
+
+Source of truth:
+- `packages/core/src/components/inputs/search/README.md`
+- `packages/core/src/components/inputs/search/types.ts`
+
+## Components In Scope
+- `SearchOverlay`
+- `SearchResultCell`
+
+## Core Types
+- `SearchPathSegment`:
+  - `id`, `type`, `title`
+- `SearchOverlayResult`:
+  - `id`, `path`, `pathSegments`, `title`, `excerpt`
+- `SearchProvider<T>`:
+  - `search(query, { limit, offset })`
+  - `getRecent()`
+  - `select(item)`
+
+## SearchOverlay Contract
+Key props:
+- `modelValue`, `query`, `results`, `activeIndex`
+- `showRecent`, `searchLabel`, `resultsLabel`
+- `placeholder`, empty labels
+- `canLoadMore`
+
+Key events:
+- `update:modelValue`
+- `update:query`
+- `update:activeIndex`
+- `select`
+- `load-more`
+
+## Integration Pitfalls
+- Keep provider operations async-safe and race-safe for rapid typing.
+- Reset `activeIndex` when result set changes.
+- Ensure selecting a row and segment-click navigation do not conflict.
+- "Recent" and "results" empty states should be explicitly handled.
+
+## Agent Verification Checklist
+- Overlay opens/closes and focus behavior is correct.
+- Keyboard selection and enter-to-select work.
+- Load-more appends and preserves interaction state.
+- Slot rendering with `SearchResultCell` shows highlighted/segmented paths correctly.

package/src/skills/umbra.ui-input-secure/SKILL.md

@@ -0,0 +1,43 @@
+# Umbra Skill: InputSecure
+
+Use this skill for password flows that need requirement checks, strength UI, and optional generation/copy controls.
+
+## When To Use
+- You need secure password entry with configurable policy requirements.
+- You need strength feedback and validation events.
+- You need optional generate/copy behavior in create flows.
+
+## Required Context Checklist
+- Usage mode (`create`, `confirm`, `enter`).
+- Password policy requirements (min length, charset requirements, common-password rule).
+- Whether to show strength and requirements panels.
+- Whether generate/copy controls are allowed.
+- Parent submit behavior based on `update:valid`.
+
+## Ask Developer If Missing
+- "Which usage mode should this field use (`create`, `confirm`, `enter`)?"
+- "What password policy is required (length, uppercase, numbers, special chars)?"
+- "Should generate/copy controls be shown?"
+- "Should we block submit unless `update:valid` is true?"
+
+## Implementation Recipe
+1. Import `InputSecure`.
+2. Bind:
+   - `v-model:value="password"`
+   - `@update:valid="passwordValid = $event"`
+   - optional `@update:strength="strength = $event"`
+3. Configure policy props per product requirements.
+4. Use parent submit guard with `passwordValid`.
+5. Keep parent business errors explicit via `state='error'`.
+
+## Validation And Edge Cases
+- Internal invalid error is blur-gated and hidden while focused editing.
+- Requirements panel should support focused editing without noisy error state.
+- Confirm/enter usage modes should suppress irrelevant UI elements.
+- Readonly/disabled must prevent interaction with action buttons.
+
+## Definition Of Done
+- Policy requirements match spec.
+- `update:valid` and `update:strength` drive parent UX as expected.
+- Blur-only internal error behavior is correct.
+- Generate/copy controls behave per mode and permissions.

package/src/skills/umbra.ui-input-secure/reference.md

@@ -0,0 +1,44 @@
+# Reference: InputSecure
+
+Source of truth:
+- `packages/core/src/components/inputs/InputSecure/InputSecure.vue`
+- `packages/core/src/components/inputs/InputSecure/README.md`
+
+## Public Props
+- `usage: "create" | "confirm" | "enter"`
+- `value?: string`
+- `placeholder?: string`
+- `showStrength?: boolean`
+- `allowGenerate?: boolean`
+- `allowCopy?: boolean`
+- `showRequirements?: boolean`
+- `minLength?: number`
+- `requireUppercase?: boolean`
+- `requireLowercase?: boolean`
+- `requireNumbers?: boolean`
+- `requireSpecialChars?: boolean`
+- `preventCommon?: boolean`
+- `state?: "normal" | "active" | "disabled" | "readonly" | "error"`
+- `validate?: (value: string) => boolean | { valid: boolean; message?: string }`
+
+## Emitted Events
+- `update:value` -> password string
+- `update:valid` -> boolean
+- `update:strength` -> 0..4
+
+## Validation/Behavior Notes
+- Uses custom `validate` when provided; otherwise requirement-based validity.
+- Internal invalid visual state is blur-gated (`hasBlurred` + `!isFocused`).
+- Requirements panel is shown during focus and/or post-blur invalid state.
+- Parent `state="error"` remains immediate.
+
+## Integration Pitfalls
+- `usage` changes visible controls; do not assume generate/copy always present.
+- If you use custom `validate`, verify requirement UI messaging still matches product expectations.
+- Avoid duplicating strength logic externally unless needed for analytics.
+
+## Agent Verification Checklist
+- Focus invalid password -> no internal error container.
+- Blur invalid password -> internal error/requirements state visible.
+- Focus again -> internal error visuals hide while editing.
+- `update:valid` and `update:strength` emit as password changes.

package/src/skills/umbra.ui-input-string-capture/SKILL.md

@@ -0,0 +1,41 @@
+# Umbra Skill: StringCapture
+
+Use this skill for trigger-driven popover text entry using Umbra `StringCapture`.
+
+## When To Use
+- You need "click to edit/add text" popover capture UX.
+- You need compact inline editing without routing to separate forms.
+- You need explicit submit/cancel events for controlled state updates.
+
+## Required Context Checklist
+- Trigger element and placement in DOM.
+- Bound value and update contract.
+- Header/placeholder copy and validation rules.
+- Submit/cancel side effects.
+- Loading behavior for async submit.
+
+## Ask Developer If Missing
+- "What element should trigger the capture popover?"
+- "Should value update only on submit, or live during typing?"
+- "What should happen on cancel (revert, keep draft, close only)?"
+- "Do we show loading state during async save?"
+
+## Implementation Recipe
+1. Import `StringCapture`.
+2. Bind `v-model` to string state.
+3. Provide trigger content via default slot.
+4. Handle:
+   - `@submit` for confirm
+   - `@cancel` for dismiss
+5. Use `loading` prop if save is async.
+
+## Validation And Edge Cases
+- Enter should submit, Escape should cancel.
+- Overlay click should dismiss safely.
+- Focus should move to input when opened.
+- Empty-submit behavior should match product requirement.
+
+## Definition Of Done
+- Trigger opens capture popover in expected location.
+- Submit/cancel lifecycle updates state correctly.
+- Keyboard and overlay interactions behave predictably.

package/src/skills/umbra.ui-input-tags/SKILL.md

@@ -0,0 +1,46 @@
+# Umbra Skill: Tags
+
+Use this skill for tag selection/creation flows using `TagBar`, `TagPicker`, and `TagCreation`.
+
+## When To Use
+- Users need multi-tag selection with search/filtering.
+- Users may create new tags inline.
+- Tags need custom visual styles or color schemes.
+
+## Required Context Checklist
+- Data model for available tags and selected tags.
+- Creation rules (who can create, title uniqueness, default style).
+- Overflow mode (`full`, `fixed`, `list`) expectations.
+- Editing constraints (can remove/reorder?).
+- Style requirements (plain tags vs styled tags).
+
+## Ask Developer If Missing
+- "What is the source of truth for all tags and selected tags?"
+- "Can users create new tags, and what naming rules apply?"
+- "Which overflow mode should this surface use?"
+- "Do tags need custom styles/colors, and where should style config come from?"
+
+## Implementation Recipe
+1. Import `TagBar` and Tag types from `@umbra.ui/core`.
+2. Maintain:
+   - `allTags: TagItem[]`
+   - `selectedTags: TagItem[]`
+   - `query`, `matchIndex`
+3. Render `TagBar` with:
+   - `:all-tags`, `:selected-tags`
+   - `v-model:query`, `v-model:match-index`
+   - handlers for `tag-select`, `tag-remove`, `tag-create`.
+4. If style is required, use `createStyledTag` and/or `TagStyleConfig`.
+5. Persist selected tags and created tags to parent/domain store.
+
+## Validation And Edge Cases
+- Prevent duplicate selected tags.
+- Handle empty query and no-result states.
+- Verify keyboard navigation in picker.
+- Verify behavior across overflow modes.
+- Ensure styled tags render legibly in light/dark themes.
+
+## Definition Of Done
+- Users can select/remove/create tags according to rules.
+- Query and highlight state are stable.
+- Styling and overflow behavior match product surface requirements.

package/src/skills/umbra.ui-input-tags/reference.md

@@ -0,0 +1,44 @@
+# Reference: Tags Input Family
+
+Source of truth:
+- `packages/core/src/components/inputs/Tags/README.md`
+- `packages/core/src/components/inputs/Tags/types.ts`
+
+## Components In Scope
+- `TagBar`
+- `TagPicker`
+- `TagCreation`
+
+## Core Interfaces
+- `TagItem`:
+  - `id: string`
+  - `title: string`
+  - `style?: TagStyleConfig`
+- `TagStyleConfig`: direct CSS-style config + optional `hover`, optional `size`, optional `colorScheme`.
+
+## TagBar Contract
+Key props:
+- `allTags`, `selectedTags`, `query`, `matchIndex`
+- `placeholder`
+- `overflow: "full" | "fixed" | "list"`
+- `allowEditing`
+
+Key events:
+- `update:query`
+- `update:matchIndex`
+- `tag-select`
+- `tag-remove`
+- `tag-create`
+- `tag-reorder`
+
+## Integration Pitfalls
+- Keep `allTags` and `selectedTags` as parent-controlled source of truth.
+- Prevent duplicate insertion in `selectedTags`.
+- `tag-create` should apply title normalization/validation before persistence.
+- Styled tag readability must be tested in light/dark modes.
+
+## Agent Verification Checklist
+- Select/remove/create flows all function.
+- Keyboard navigation in picker works.
+- Overflow mode behaves as intended for container size.
+- Reorder events are handled (if enabled) and persisted.

package/src/skills/umbra.ui-input-text/SKILL.md

@@ -0,0 +1,46 @@
+# Umbra Skill: InputText
+
+Use this skill when implementing or updating plain text capture with Umbra `InputText`.
+
+## When To Use
+- You need a basic text field with Umbra theming.
+- You need explicit visual state control via `state` (`normal`, `active`, `disabled`, `readonly`, `error`).
+- You need direct `v-model:value` binding with simple string updates.
+
+## Do Not Use
+- For email validation/suggestions: use `InputEmail`.
+- For numeric/range behavior: use `InputNumber`.
+- For masked formats (phone, card, crypto): use specialized inputs.
+
+## Required Context Checklist
+- Target file and exact DOM location where input should be inserted.
+- Data binding variable name/type (`ref<string>`).
+- Desired `state` and `size` behavior.
+- Whether parent/business logic controls `state="error"`.
+- Label/help/error copy requirements.
+
+## Ask Developer If Missing
+- "What exact model ref should this input bind to (`v-model:value`)?"
+- "Should this input be `normal`, `active`, `readonly`, `disabled`, or parent-driven `error`?"
+- "Where in the DOM should it mount (component/section selector)?"
+- "Do you want external validation to drive `state='error'`, and what message should appear nearby?"
+
+## Implementation Recipe
+1. Import `InputText` from `@umbra.ui/core`.
+2. Create `const value = ref(\"\")` in `<script setup lang=\"ts\">`.
+3. Render:
+   - `<InputText v-model:value="value" :state="..." :size="..." placeholder="..." />`
+4. If external validation is required, keep validation in parent and only pass `state="error"` when invalid.
+5. Do not embed heavy validation logic inside this component usage.
+
+## Validation And Edge Cases
+- Confirm `update:value` emits on each input change.
+- Confirm `readonly` and `disabled` behavior stays non-editable.
+- Confirm `state='error'` is parent-controlled and immediate.
+- Confirm placeholder and filled states match expected design.
+
+## Definition Of Done
+- Input renders in correct location.
+- `v-model:value` updates expected state variable.
+- Requested state and size variants work.
+- Parent-driven error handling (if requested) is wired and visible.

package/src/skills/umbra.ui-menu-action-menu/SKILL.md

@@ -0,0 +1,34 @@
+# Umbra Skill: ActionMenu
+
+Use this skill for contextual action lists using Umbra `ActionMenu`.
+
+## When To Use
+- Overflow actions (`...`) on cards/rows.
+- Right-click context menus (`contextMenu=true`).
+- Action lists containing normal and destructive operations.
+
+## Required Context Checklist
+- Menu open-state control (`modelValue`).
+- `items: ActionMenuItem[]` with title/icon/action definitions.
+- Trigger mode (click menu vs context menu).
+- Close behavior after action and analytics expectations.
+
+## Ask Developer If Missing
+- "Should this be click-triggered or right-click context menu?"
+- "What actions should appear, and which are destructive?"
+- "Do item actions run directly or dispatch through store/router?"
+
+## Implementation Recipe
+1. Import `ActionMenu` and `ActionMenuItem`.
+2. Create typed `items` with `title`, `action`, optional `icon`, optional `isDestructive`.
+3. Bind `v-model` for open state.
+4. Provide trigger content in default slot.
+5. Handle `@item-click` for tracking and side effects.
+
+## Validation And Edge Cases
+- Destructive items should be visually and behaviorally clear.
+- Ensure right-click menus position correctly and close on outside click.
+- Keep action handlers idempotent if users click rapidly.
+
+## Definition Of Done
+- Menu actions are discoverable, correctly wired, and safe.

package/src/skills/umbra.ui-model-popover/SKILL.md

@@ -0,0 +1,35 @@
+# Umbra Skill: Popover
+
+Use this skill for anchored floating content using Umbra `Popover`.
+
+## When To Use
+- Contextual help, menus, quick actions, lightweight forms.
+- Content anchored to a trigger with smart placement.
+- UX requiring click or hover trigger behavior.
+
+## Required Context Checklist
+- Open state ownership (`modelValue`/`v-model`).
+- Trigger type (`click` or `hover`) and delays.
+- Placement, offset, arrow, and overlay requirements.
+- Close behavior (`dismissOnClickOutside`, Escape handling).
+
+## Ask Developer If Missing
+- "Should this open on click or hover?"
+- "What placement should be preferred?"
+- "Should outside click close it?"
+- "Do we need backdrop overlay?"
+
+## Implementation Recipe
+1. Import `Popover`.
+2. Bind open state with `v-model`.
+3. Provide `#trigger` slot and default slot content.
+4. Configure placement and interaction props.
+5. Handle `open`/`close` events for analytics or side effects.
+
+## Validation And Edge Cases
+- Ensure popover closes on intended interactions only.
+- Verify viewport-aware placement in constrained containers.
+- Confirm keyboard dismissal (Escape) works for accessibility.
+
+## Definition Of Done
+- Popover opens, positions, and closes exactly as required.

package/src/skills/umbra.ui-model-sheet/SKILL.md

@@ -0,0 +1,35 @@
+# Umbra Skill: Sheet
+
+Use this skill for modal sheet surfaces that slide/fade in from an edge.
+
+## When To Use
+- Mobile-style action sheets, forms, detail panels, modal workflows.
+- Temporary overlays needing strong focus and backdrop behavior.
+- Bottom/top/left/right reveal interactions.
+
+## Required Context Checklist
+- Controlled open state and dismissal rules.
+- `side`, size constraints (`width`/`height`/max values).
+- Animation style (`slide` vs `ghost`) and duration.
+- Backdrop style (`blur` vs `dim`) and close behavior.
+
+## Ask Developer If Missing
+- "Which side should the sheet enter from?"
+- "Should backdrop click dismiss the sheet?"
+- "Do we want slide or ghost animation?"
+- "What size constraints should be enforced?"
+
+## Implementation Recipe
+1. Import `Sheet`.
+2. Bind `v-model` boolean for visibility.
+3. Configure side, size, animation, and backdrop props.
+4. Place workflow content in default slot.
+5. Handle `open`, `close`, and `backdrop-click` if needed.
+
+## Validation And Edge Cases
+- Body scroll should lock while sheet is open.
+- Escape/backdrop behavior should match product expectations.
+- Validate on small screens with safe-area constraints.
+
+## Definition Of Done
+- Sheet interaction feels modal, predictable, and responsive.

package/src/skills/umbra.ui-model-sidebar/SKILL.md

@@ -0,0 +1,35 @@
+# Umbra Skill: Sidebar
+
+Use this skill for slide-in navigation or utility panels with Umbra `Sidebar`.
+
+## When To Use
+- App navigation drawers and settings panels.
+- Contextual side panels that coexist with primary content.
+- Mobile action panels entering from bottom/top.
+
+## Required Context Checklist
+- Open state ownership and dismissal behavior.
+- Side (`left`, `right`, `top`, `bottom`) and dimensions.
+- Backdrop style and close policy.
+- Panel content structure (navigation, settings, actions).
+
+## Ask Developer If Missing
+- "Is this navigation, settings, or contextual tools?"
+- "Which side should the sidebar use?"
+- "Should click on backdrop close it?"
+- "Do we need fixed width/height constraints?"
+
+## Implementation Recipe
+1. Import `Sidebar`.
+2. Bind visibility with `v-model`.
+3. Configure side, size, backdrop, and animation duration.
+4. Render panel content in default slot.
+5. Wire close interactions and optional analytics events.
+
+## Validation And Edge Cases
+- Verify body scroll lock and Escape-close behavior.
+- Ensure panel remains usable on small viewports.
+- Keep navigation state synced when sidebar closes.
+
+## Definition Of Done
+- Sidebar opens/closes smoothly and supports intended workflow.

package/src/skills/umbra.ui-picker-collection/SKILL.md

@@ -0,0 +1,36 @@
+# Umbra Skill: CollectionPicker
+
+Use this skill for selecting one item from a user-facing collection, with optional item creation.
+
+## When To Use
+- You need a selectable list of `CollectionItem` objects.
+- You need optional in-picker creation (`item-create`).
+- You need custom trigger UI through the `label` slot.
+
+## Required Context Checklist
+- Collection source and identity fields (`id`, `title`).
+- Selected item ownership (`v-model:selected-item`) and persistence.
+- Whether user can create new items (`allowCreate`).
+- Trigger style choice: default label vs custom `#label` vs hidden.
+
+## Ask Developer If Missing
+- "Where does the item list come from and how is it refreshed?"
+- "Should create flow be enabled, and who persists new items?"
+- "What should happen immediately after item selection?"
+
+## Implementation Recipe
+1. Import `CollectionPicker` and `CollectionItem`.
+2. Bind `:items` and `v-model:selected-item`.
+3. Handle `@item-selected` for side effects.
+4. If enabled, handle `@item-create` and persist before appending.
+5. Optionally provide a custom `#label` trigger.
+
+## Validation And Edge Cases
+- Use stable `id` values; avoid re-creating IDs per render.
+- Guard create flow against empty/duplicate names in parent logic.
+- Keep parent selected item in sync when source list is refreshed.
+
+## Definition Of Done
+- Selection emits and model updates are consistent.
+- Optional create flow persists and selects new item correctly.
+- Trigger UX matches requirements (default/custom/hidden label).

package/src/skills/umbra.ui-picker-collection/reference.md

@@ -0,0 +1,34 @@
+# Reference: CollectionPicker
+
+Source of truth:
+- `packages/core/src/components/pickers/CollectionPicker/CollectionPicker.vue`
+- `packages/core/src/components/pickers/CollectionPicker/README.md`
+
+## Public Props
+- `items: CollectionItem[]`
+- `selectedItem: CollectionItem | null`
+- `loading?: boolean`
+- `label?: boolean` (default `true`)
+- `buttonLabel?: string`
+- `headerLabel?: string`
+- `newItemLabel?: string`
+- `itemIcon?: string`
+- `newItemIcon?: string`
+- `allowCreate?: boolean` (default `true`)
+- `placeholder?: string`
+
+## Events
+- `item-selected` -> `CollectionItem`
+- `item-create` -> `string` (new title)
+- `update:selectedItem` -> `CollectionItem | null`
+
+## Types
+- `CollectionItem` requires:
+  - `id: string`
+  - `title: string`
+  - additional fields are allowed
+
+## Agent Verification Checklist
+- `v-model:selected-item` stays synchronized with selected row.
+- `item-create` is handled and new item appears in source list.
+- Custom `#label` renders, and `:label="false"` hides label content.

package/src/skills/umbra.ui-picker-color/SKILL.md

@@ -0,0 +1,36 @@
+# Umbra Skill: ColorPicker
+
+Use this skill for selecting colors from Umbra's color palette with optional custom trigger rendering.
+
+## When To Use
+- You need a typed `Color` selection model.
+- You need configurable trigger dot styles and palette popover.
+- You need custom trigger UI using the `label` slot.
+
+## Required Context Checklist
+- Selected color state and persistence (`v-model:color`).
+- Whether popup interaction can be disabled (`preventPopup`).
+- Trigger style needs: dot props vs custom `#label`.
+- Whether color metadata (name/weight/hex) should be shown in picker.
+
+## Ask Developer If Missing
+- "Should we use Umbra palette defaults or a preselected custom value?"
+- "Do we need read-only trigger mode using `preventPopup`?"
+- "Is default dot trigger enough, or do you want custom `#label`?"
+
+## Implementation Recipe
+1. Import `ColorPicker` and color helpers as needed.
+2. Bind `v-model:color` to a `ref<Color>`.
+3. Configure trigger via dot props, or provide custom `#label`.
+4. Handle `@update:color` for side effects (theme updates, previews).
+5. Use parent validation/rules for downstream constraints.
+
+## Validation And Edge Cases
+- Keep `Color` objects normalized (`name`, `hex`, `weight`).
+- Avoid invalid custom color payload shapes in parent state.
+- Verify behavior with `preventPopup=true` and disabled-like flows.
+
+## Definition Of Done
+- Selected color updates and emits consistently.
+- Trigger appearance follows design (dot props or custom label).
+- Color-dependent side effects update without stale state.

package/src/skills/umbra.ui-picker-color/reference.md

@@ -0,0 +1,34 @@
+# Reference: ColorPicker
+
+Source of truth:
+- `packages/core/src/components/pickers/ColorPicker/ColorPicker.vue`
+- `packages/core/src/components/pickers/ColorPicker/README.md`
+
+## Public Props
+- `color: Color`
+- `pickerOffsetX: number` (default `0`)
+- `preventPopup: boolean` (default `false`)
+- `label?: boolean` (default `true`)
+- `dotSize?: number | string`
+- `dotRadius?: number | string`
+- `dotBorderWidth?: number`
+- `dotBorderColor?: string`
+- `dotBorderColorActive?: string`
+- `showColorInfo?: boolean` (default `true`)
+
+## Slots
+- `label` -> custom trigger content
+
+## Events
+- `update:color` -> `Color`
+
+## Type Notes
+- `Color` shape:
+  - `name: string | null`
+  - `hex: string`
+  - `weight: number | null`
+
+## Agent Verification Checklist
+- `v-model:color` receives chosen swatch value.
+- Dot props apply when default trigger is used.
+- Custom `#label` and `:label="false"` behave as expected.