@umbra.ui/core 0.4.6 → 0.5.0

package/src/skills/umbra.ui-control-segmented-control/SKILL.md

@@ -0,0 +1,33 @@
+# Umbra Skill: SegmentedControl
+
+Use this skill for compact single-choice switching with Umbra `SegmentedControl`.
+
+## When To Use
+- View mode toggles (grid/list/card).
+- Filter tabs and sub-mode selectors.
+- Settings where immediate choice switching is desired.
+
+## Required Context Checklist
+- Segment `items: ControlItem[]`.
+- Selected index state and default.
+- Side effects when selected segment changes.
+- Disabled segment handling if applicable.
+
+## Ask Developer If Missing
+- "What options should each segment show?"
+- "Which segment is default-selected?"
+- "Do we trigger behavior on click or only on index update?"
+
+## Implementation Recipe
+1. Import `SegmentedControl`.
+2. Define segment items and `selectedIndex`.
+3. Render with `:items` and `:selected-index`.
+4. Handle `@update:selected-index` and/or `@click`.
+
+## Validation And Edge Cases
+- Keep selection index valid when items are dynamic.
+- Avoid expensive side effects on every toggle if not needed.
+- Verify text remains readable across themes.
+
+## Definition Of Done
+- Segment switching is smooth and updates app state correctly.

package/src/skills/umbra.ui-control-slider/SKILL.md

@@ -0,0 +1,33 @@
+# Umbra Skill: Slider
+
+Use this skill for single-value continuous selection with Umbra `Slider`.
+
+## When To Use
+- Percent-like settings (volume, opacity, confidence).
+- Numeric tuning in bounded ranges.
+- Visual controls where drag is more natural than text input.
+
+## Required Context Checklist
+- Boundaries (`min`, `max`) and current `value`.
+- Style variant (`default`, `capline`, `capsule`).
+- Value formatting for nearby labels/hints.
+- Persistence and debounce strategy if updates are frequent.
+
+## Ask Developer If Missing
+- "What min/max/value range should be used?"
+- "Should changes apply live while dragging?"
+- "Which slider style best matches this surface?"
+
+## Implementation Recipe
+1. Import `Slider`.
+2. Maintain parent-controlled numeric `value`.
+3. Render with range + style props.
+4. Handle `@update:value` and sync to store/form.
+
+## Validation And Edge Cases
+- Clamp external values before rendering.
+- Handle decimal values deliberately if range needs precision.
+- Verify touch dragging on mobile.
+
+## Definition Of Done
+- Slider tracks the expected value and updates reliably in app state.

package/src/skills/umbra.ui-control-stepper/SKILL.md

@@ -0,0 +1,33 @@
+# Umbra Skill: Stepper
+
+Use this skill for bounded increment/decrement numeric inputs with Umbra `Stepper`.
+
+## When To Use
+- Quantity controls, counters, and integer configs.
+- Inputs where explicit step increments are required.
+- Numeric forms where free text entry is not preferred.
+
+## Required Context Checklist
+- Controlled `value` binding.
+- Limits (`min`, `max`) and `step` size.
+- Integer vs decimal expectations.
+- Interaction with sibling controls (totals, pricing, validation).
+
+## Ask Developer If Missing
+- "What are min/max/step rules?"
+- "Should decimal steps be allowed?"
+- "What state updates when value changes?"
+
+## Implementation Recipe
+1. Import `Stepper`.
+2. Render with `:value`, `:min`, `:max`, `:step`.
+3. Handle `@update:value` and persist.
+4. Add surrounding label/context for meaning of the number.
+
+## Validation And Edge Cases
+- Keep model value clamped to min/max.
+- Watch for floating point precision if decimal step is used.
+- Prevent downstream logic from assuming unrestricted values.
+
+## Definition Of Done
+- Stepper changes value predictably and respects configured bounds.

package/src/skills/umbra.ui-control-switch/SKILL.md

@@ -0,0 +1,33 @@
+# Umbra Skill: Switch
+
+Use this skill for binary on/off settings with Umbra `Switch`.
+
+## When To Use
+- Feature toggles and preferences.
+- Enable/disable behavior flags in settings forms.
+- Boolean values that benefit from immediate visual state.
+
+## Required Context Checklist
+- Controlled boolean source (`isChecked`).
+- Visual mode (`switchType`) and size.
+- Checked color requirements (default vs custom color).
+- Side effects when toggled.
+
+## Ask Developer If Missing
+- "What boolean field should this control?"
+- "Default or outline style?"
+- "Any custom on-color needed for semantic meaning?"
+
+## Implementation Recipe
+1. Import `Switch`.
+2. Bind with `:is-checked`.
+3. Handle `@update:is-checked` and persist value.
+4. Place clear label text adjacent to switch.
+
+## Validation And Edge Cases
+- Ensure toggling cannot desync from external state.
+- Handle disabled/permission scenarios at parent level if needed.
+- Verify switch remains understandable in both themes.
+
+## Definition Of Done
+- Toggle reflects and updates boolean state correctly.

package/src/skills/umbra.ui-dialog-alert/SKILL.md

@@ -0,0 +1,34 @@
+# Umbra Skill: Alert
+
+Use this skill for blocking confirmation/info dialogs with Umbra `Alert`.
+
+## When To Use
+- Confirm destructive or irreversible actions.
+- Present important messages requiring explicit acknowledgment.
+- Offer 1..N dialog actions with semantic action types.
+
+## Required Context Checklist
+- Visibility source of truth (`show` boolean).
+- Alert copy (`title`, `description`).
+- Action list (`AlertAction[]`) and action ordering.
+- Behavior on close (`update:show`) and side effects per action.
+
+## Ask Developer If Missing
+- "Is this confirm/cancel only, or multi-option?"
+- "Which action is destructive and should be emphasized?"
+- "Should dialog close automatically after each action?"
+
+## Implementation Recipe
+1. Import `Alert` and `AlertAction`.
+2. Manage `showAlert` state in parent.
+3. Define typed `actions` with `title`, `type`, and `action`.
+4. Render `<Alert :show ... :actions ... @update:show="...">`.
+5. Ensure each action updates dialog state as intended.
+
+## Validation And Edge Cases
+- Do not allow hidden destructive behavior behind neutral labels.
+- Make sure `update:show` keeps parent and UI synchronized.
+- Keep descriptions concise and explicit for high-risk actions.
+
+## Definition Of Done
+- Alert messaging and action semantics are correct and safe.

package/src/skills/umbra.ui-dialog-toast/SKILL.md

@@ -0,0 +1,35 @@
+# Umbra Skill: Toast
+
+Use this skill for non-blocking user feedback with Umbra toast system.
+
+## When To Use
+- Success/error/warning/info feedback after user actions.
+- Background process updates that should not block interaction.
+- Temporary notices with optional actions.
+
+## Required Context Checklist
+- Plugin setup (`ToastPlugin`) and `<ToastContainer />` mounting.
+- Invocation style (`useToast` helpers vs `addToast`).
+- Toast type, duration, dismissibility, and position.
+- Whether actions are needed inside the toast.
+
+## Ask Developer If Missing
+- "Is ToastPlugin already installed at app root?"
+- "Where is ToastContainer rendered?"
+- "Should this message auto-dismiss, and after how long?"
+- "Do we need CTA actions in the toast?"
+
+## Implementation Recipe
+1. Ensure app installs `ToastPlugin`.
+2. Ensure a `ToastContainer` exists in app shell.
+3. In feature code, call `useToast()`.
+4. Prefer `showSuccess/showError/showWarning/showInfo` for standard cases.
+5. Use `addToast` for advanced cases (custom type, actions, persistent toasts).
+
+## Validation And Edge Cases
+- Avoid spam: debounce repetitive toasts from rapid events.
+- Use `duration: 0` only when persistent toast is truly required.
+- Ensure critical errors are not toast-only if they require explicit user action.
+
+## Definition Of Done
+- Toasts render with correct type/style/timing and are actionable when needed.

package/src/skills/umbra.ui-indicator-progress-bar/SKILL.md

@@ -0,0 +1,33 @@
+# Umbra Skill: ProgressBar
+
+Use this skill for visual progress feedback with Umbra `ProgressBar`.
+
+## When To Use
+- Upload/download progress.
+- Multi-step flow completion indicators.
+- Background task progress where users need status visibility.
+
+## Required Context Checklist
+- Progress source value and update cadence.
+- Bar style (`default`, `capsule`, `capline`).
+- Color and height requirements.
+- Whether to clamp, round, or debounce progress updates.
+
+## Ask Developer If Missing
+- "What data source drives progress?"
+- "Which visual style should be used?"
+- "Do we need custom colors to match status semantics?"
+
+## Implementation Recipe
+1. Import `ProgressBar`.
+2. Bind `:progress` from parent state/store.
+3. Configure `barType`, colors, and `height` if needed.
+4. Update progress from task events and keep values in 0-100.
+
+## Validation And Edge Cases
+- Prevent regressions from stale async events.
+- Verify behavior at boundaries (0, 100).
+- Keep screen reader text nearby for critical workflows.
+
+## Definition Of Done
+- Progress reflects real task state and is visually consistent.

package/src/skills/umbra.ui-indicator-tooltip/SKILL.md

@@ -0,0 +1,33 @@
+# Umbra Skill: Tooltip
+
+Use this skill for contextual hover help with Umbra tooltip system.
+
+## When To Use
+- Inline help for controls, icons, and dense interfaces.
+- Explain disabled states or ambiguous actions.
+- Provide non-blocking guidance near interactive elements.
+
+## Required Context Checklist
+- App-level `TooltipProvider` presence.
+- Usage mode: `v-tooltip` directive vs `useTooltip` composable.
+- Tooltip content, placement, delay, and offset.
+- Accessibility expectations and fallback text placement.
+
+## Ask Developer If Missing
+- "Is `TooltipProvider` already mounted in app shell?"
+- "Should we use directive syntax or programmatic binding?"
+- "What placement and delay feel best for this surface?"
+
+## Implementation Recipe
+1. Ensure `<TooltipProvider />` exists at app level.
+2. For simple cases, apply `v-tooltip` to target element.
+3. For dynamic/programmatic cases, use `useTooltip` and `bindTooltip`.
+4. Configure `content`, `placement`, `delay`, and `offset`.
+
+## Validation And Edge Cases
+- Avoid tooltip-only critical information.
+- Verify on mobile/ touch-only contexts where hover is limited.
+- Confirm tooltip positioning in scrollable/overflow containers.
+
+## Definition Of Done
+- Tooltip appears with correct content/timing/placement and does not obstruct interaction.

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

@@ -0,0 +1,42 @@
+# Umbra Skill: InputCard
+
+Use this skill for credit-card number entry with card detection, masking, and validity emission.
+
+## When To Use
+- You need card-number capture with brand detection.
+- You need formatted display plus raw digit emission.
+- You need validity signal for payment submit gating.
+
+## Required Context Checklist
+- Exact mount location and form context (checkout, saved card, etc.).
+- Raw vs formatted storage requirement in parent.
+- Whether card brand UI should be shown.
+- Submit gating behavior using `update:valid`.
+- External payment-provider error handling with parent `state='error'`.
+
+## Ask Developer If Missing
+- "Should parent store raw digits (`update:value`) or formatted string?"
+- "Do we show card type icon (`showCardType`) in this surface?"
+- "What should happen when `update:valid` is false at submit?"
+- "Any gateway/server error state to map to `state='error'`?"
+
+## Implementation Recipe
+1. Import `InputCard`.
+2. Bind:
+   - `v-model:value="cardDigits"`
+   - optional `@update:formatted`, `@update:cardType`, `@update:valid`
+3. Use `cardValid` to gate submit actions.
+4. Keep CVV/expiry/zip as separate fields.
+5. Keep parent business errors separate via `state='error'`.
+
+## Validation And Edge Cases
+- Input should reject over-length card numbers.
+- Internal error should show on blur for non-empty invalid input.
+- Error should hide while focused and editing.
+- Paste should sanitize and clamp to supported format length.
+
+## Definition Of Done
+- Card input clamps to valid lengths for detected card patterns.
+- Emitted raw/formatted/cardType/valid events are consumed correctly.
+- Blur-only internal error behavior is consistent and non-noisy.
+- Parent/server errors still render immediately via `state='error'`.

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

@@ -0,0 +1,36 @@
+# Reference: InputCard
+
+Source of truth:
+- `packages/core/src/components/inputs/InputCard/InputCard.vue`
+- `packages/core/src/components/inputs/InputCard/README.md`
+
+## Public Props
+- `value?: string` (raw digits expected for controlled usage)
+- `placeholder?: string`
+- `showCardType?: boolean` (default `true`)
+- `state?: "normal" | "active" | "disabled" | "readonly" | "error"`
+
+## Emitted Events
+- `update:value` -> normalized raw digits
+- `update:formatted` -> formatted display value
+- `update:cardType` -> detected card name string
+- `update:valid` -> `true` when complete and valid
+
+## Validation/Formatting Notes
+- Card type detection uses prefix patterns (visa/mastercard/amex/discover/diners/jcb).
+- Luhn algorithm validates completed card numbers.
+- Over-length protection is enforced in beforeinput/input/paste paths.
+- Current Visa config is 16-digit only.
+- Internal invalid state is blur-gated for non-empty invalid input.
+- Parent `state="error"` is immediate.
+
+## Integration Pitfalls
+- Do not re-inject stale longer values from parent into `v-model:value`.
+- For submit readiness, combine card validity with other payment fields.
+- Keep CVV/expiry validation external; this component only handles card number.
+
+## Agent Verification Checklist
+- Cannot enter more digits than allowed by detected format.
+- Pasting too many digits clamps correctly.
+- Invalid non-empty card shows error on blur, not while focused typing.
+- Parent `state="error"` overrides internal timing.

package/src/skills/umbra.ui-input-crypto-address/SKILL.md

@@ -0,0 +1,40 @@
+# Umbra Skill: InputCryptoAddress
+
+Use this skill for blockchain address entry with chain-specific validation and optional known-address selection.
+
+## When To Use
+- You need ETH/BTC/SOL address input with inline validity feedback.
+- You need optional known-address dropdown selection.
+- You need custom validator override for chain/app-specific checks.
+
+## Required Context Checklist
+- Which chain is required (`eth`, `btc`, `sol`).
+- Whether known addresses should be provided.
+- How selected/typed address maps to app state.
+- Whether custom validator is needed.
+- Parent error handling requirements.
+
+## Ask Developer If Missing
+- "Which chain should validation target?"
+- "Do you have a known-address list (label + address) for dropdown selection?"
+- "Should we use default validation or provide a custom validator?"
+- "What should happen after selecting a known address (auto-submit, stay editable, etc.)?"
+
+## Implementation Recipe
+1. Import `InputCryptoAddress`.
+2. Bind `v-model:value` to address state.
+3. Pass required `chain`.
+4. Optionally pass `knownAddresses`, `knownAddressesLabel`, and `validator`.
+5. Handle submit/action based on resolved address from the bound model.
+
+## Validation And Edge Cases
+- Invalid internal state should appear on blur, not during active typing.
+- Valid status should still render when value is valid.
+- Known-address dropdown should not break focus/blur flow.
+- Ensure trim/normalization behavior matches backend expectations.
+
+## Definition Of Done
+- Chain-appropriate validation is active.
+- Known-address selection updates bound model correctly.
+- Blur-gated invalid UX and valid messaging both behave correctly.
+- Parent-side error semantics remain explicit and predictable.

package/src/skills/umbra.ui-input-crypto-address/reference.md

@@ -0,0 +1,40 @@
+# Reference: InputCryptoAddress
+
+Source of truth:
+- `packages/core/src/components/inputs/InputCryptoAddress/InputCryptoAddress.vue`
+- `packages/core/src/components/inputs/InputCryptoAddress/README.md`
+
+## Public Props
+- `value?: string`
+- `placeholder?: string`
+- `state?: "normal" | "active" | "disabled" | "readonly" | "error"`
+- `size?: "compact" | "normal"`
+- `chain: "eth" | "btc" | "sol"` (required)
+- `knownAddresses?: { label: string; address: string }[]`
+- `knownAddressesLabel?: string`
+- `validator?: (value: string) => boolean`
+
+## Emitted Events
+- `update:value` -> address string
+
+## Validation/Behavior Notes
+- Chain-specific default validators:
+  - ETH: `0x` + 40 hex chars
+  - BTC: legacy/bech32 pattern
+  - SOL: base58 length 32-44
+- Optional `validator` overrides built-ins.
+- Internal invalid UI is blur-gated.
+- Valid status messaging still appears for valid non-empty input.
+- Parent `state="error"` is immediate and should remain authoritative.
+- Known addresses appear via dropdown-style list on focus.
+
+## Integration Pitfalls
+- Component trims input on update; preserve this expectation in parent.
+- Known-address selection can blur/close list; avoid extra focus handlers that conflict.
+- If custom validator is chain-specific, keep chain and validator aligned.
+
+## Agent Verification Checklist
+- Invalid non-empty value while focused -> no internal invalid state.
+- Blur invalid value -> invalid state/message appears.
+- Valid non-empty value -> valid status appears.
+- Selecting a known address updates bound model and closes list correctly.

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

@@ -0,0 +1,45 @@
+# Umbra Skill: InputEmail
+
+Use this skill for validated email capture with typo suggestions and domain completion.
+
+## When To Use
+- You need email-specific validation and normalization.
+- You want domain suggestions and typo correction hints.
+- You need `update:valid` to drive form submission state.
+
+## Required Context Checklist
+- Mount location and bound email model.
+- Whether suggestions should be shown.
+- Whether subdomains are allowed.
+- Submit/error behavior based on `update:valid`.
+- Any external/server error flow using `state='error'`.
+
+## Ask Developer If Missing
+- "Should domain suggestions be enabled?"
+- "Should subdomain emails be accepted?"
+- "Do we block submit unless `@update:valid` is true?"
+- "Any backend/server email error we should map to `state='error'`?"
+
+## Implementation Recipe
+1. Import `InputEmail`.
+2. Bind:
+   - `v-model:value="email"`
+   - optional `@update:valid="emailValid = $event"`
+   - optional `@update:suggestion="..."`
+3. Configure:
+   - `:showSuggestions`
+   - `:allowSubdomains`
+4. Use `emailValid` in parent submit guards.
+5. Keep parent-driven errors explicit via `state='error'`.
+
+## Validation And Edge Cases
+- Internal invalid error appears on blur only (not while focused typing).
+- Error should appear even for malformed non-empty emails on blur.
+- Pasted values should be normalized and validated.
+- Suggestions dropdown keyboard behavior should remain intact.
+
+## Definition Of Done
+- Email captures and emits correctly.
+- `update:valid` reflects expected validity.
+- Blur-only internal error behavior works consistently.
+- Suggestion flow works without breaking form interaction.

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

@@ -0,0 +1,39 @@
+# Umbra Skill: InputNumber
+
+Use this skill for numeric fields with optional min/max constraints and unit labels.
+
+## When To Use
+- You need numeric-only input with optional range validation.
+- You need min/max messages and optional unit label (`label` prop).
+- You need parent state control with optional business-rule error.
+
+## Required Context Checklist
+- Mount location and connected model (`ref<number | undefined>` or `ref<number>`).
+- Min/max range requirements.
+- Whether label/unit is needed.
+- Whether submit should block when value is invalid.
+- Whether parent can override with `state='error'`.
+
+## Ask Developer If Missing
+- "What is the accepted numeric range (`min`, `max`)?"
+- "Should empty be allowed or should it coerce to 0?"
+- "Do we need a unit suffix label (%, kg, items)?"
+- "Should the form block submit on invalid range?"
+
+## Implementation Recipe
+1. Import `InputNumber`.
+2. Bind `v-model:value` to numeric state.
+3. Pass `:min`, `:max`, and `label` where applicable.
+4. Handle validation outcome in parent as needed (e.g. submit guard).
+5. Keep parent-driven `state='error'` for external/business validation.
+
+## Validation And Edge Cases
+- Internal range error appears on blur only (current UX behavior).
+- Error hides during focus/edit.
+- Ensure `undefined`/empty handling is acceptable to parent logic.
+- Ensure negative values work when required.
+
+## Definition Of Done
+- Range limits and label render correctly.
+- Blur behavior matches expected UX.
+- Parent logic receives stable numeric values and handles empty state correctly.

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

@@ -0,0 +1,44 @@
+# Umbra Skill: OTP
+
+Use this skill to implement one-time-password code entry with digit cells, keyboard navigation, and completion handling.
+
+## When To Use
+- Verification code entry (2FA, email/phone verification, reset flows).
+- Fixed-length numeric code inputs (typically 4/6/8 digits).
+- UX that needs completion callbacks and optional auto-submit.
+
+## Required Context Checklist
+- Expected OTP length and whether auto submit is desired.
+- Binding contract (`v-model` string source of truth).
+- Verification trigger (on `complete` vs manual submit button).
+- Loading/error lifecycle from backend verification.
+- Retry/resend behavior and cooldown expectations.
+
+## Ask Developer If Missing
+- "How many digits should the OTP require?"
+- "Should verify happen automatically on `complete`, or only after explicit submit?"
+- "What exact error/loading states should appear from backend responses?"
+- "Do we need resend cooldown UI and lockout behavior?"
+
+## Implementation Recipe
+1. Import `OTP` from `@umbra.ui/core`.
+2. Create state:
+   - `otpCode = ref("")`
+   - optional `loading`, `error`, `canSubmit`.
+3. Render:
+   - `<OTP v-model="otpCode" :length="..." :auto-submit="..." @complete="..." />`
+4. If manual flow, set `:auto-submit="false"` and verify on button click.
+5. Clear/reset OTP state on failed verification as product requires.
+
+## Validation And Edge Cases
+- Ensure only digits are accepted.
+- Paste should distribute digits correctly across cells.
+- Backspace and arrow key navigation should behave naturally.
+- `error` and `loading` props should disable inappropriate interactions.
+- Respect exposed methods (`focus()`, `clear()`) when refs are used.
+
+## Definition Of Done
+- OTP input supports expected length and verification flow.
+- Completion and change events wire correctly.
+- Error/loading/retry behavior matches product requirements.
+- Keyboard and paste behavior work in real usage.

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

@@ -0,0 +1,45 @@
+# Umbra Skill: InputPhone
+
+Use this skill when implementing phone-number capture with masking, validation, and formatting events.
+
+## When To Use
+- You need phone entry with automatic formatting and validation.
+- You need emitted formatted/valid state for form flow control.
+- You need country-aware behavior (`defaultCountry`, optional international handling).
+
+## Required Context Checklist
+- Target file and mount location.
+- Backing model (`ref<string>`) and whether to store raw vs formatted.
+- Required country behavior (`defaultCountry`, `allowInternational`, `showCountryCode`).
+- Validation UX requirements (blur-only internal error is current behavior).
+- Downstream usage of `update:valid`.
+
+## Ask Developer If Missing
+- "Should we store/display formatted numbers only, or normalize before submit?"
+- "Which country should be default (`US`, `GB`, etc.)?"
+- "Do we allow international numbers?"
+- "Do you need submit blocking based on `@update:valid`?"
+
+## Implementation Recipe
+1. Import `InputPhone` from `@umbra.ui/core`.
+2. Create refs:
+   - `phone = ref(\"\")`
+   - optional `phoneValid = ref(false)`
+   - optional `phoneFormatted = ref(\"\")`
+3. Render:
+   - `<InputPhone v-model:value="phone" @update:valid="..." @update:formatted="..." ... />`
+4. Use `phoneValid` for button-disable/submission guard if needed.
+5. Keep parent `state='error'` for server/business errors only.
+
+## Validation And Edge Cases
+- Blur-only internal error should appear only after blur when invalid.
+- Error should hide while focused/typing.
+- Max digit constraints should prevent over-input.
+- Paste behavior should sanitize and reformat.
+- Disabled/readonly should remain non-editable.
+
+## Definition Of Done
+- Number formats as expected while typing.
+- `update:value`, `update:formatted`, and `update:valid` are consumed correctly.
+- Invalid number shows error on blur, not during active typing.
+- Submit logic honors `phoneValid` where required.

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

@@ -0,0 +1,35 @@
+# Reference: InputPhone
+
+Source of truth:
+- `packages/core/src/components/inputs/InputPhone/InputPhone.vue`
+- `packages/core/src/components/inputs/InputPhone/README.md`
+
+## Public Props
+- `value?: string`
+- `placeholder?: string`
+- `defaultCountry?: string` (default `US`)
+- `allowInternational?: boolean` (default `true`)
+- `showCountryCode?: boolean` (default `true`)
+- `state?: "normal" | "active" | "disabled" | "readonly" | "error"`
+
+## Emitted Events
+- `update:value` -> formatted phone string
+- `update:formatted` -> formatted phone string
+- `update:valid` -> boolean validity
+
+## Validation/Formatting Notes
+- Country detection is heuristic (US/GB/international).
+- Input/paste are digit-sanitized and clamped to country-dependent max digits.
+- Invalid internal state is blur-gated (`hasBlurred` + `!isFocused`).
+- Parent `state="error"` is respected immediately.
+
+## Integration Pitfalls
+- Do not assume `update:value` is raw digits; it is formatted.
+- If backend needs normalized digits, normalize in parent before submit.
+- If you implement additional parent validation, avoid fighting internal blur-gated UX.
+
+## Agent Verification Checklist
+- Type invalid number while focused -> no internal error shown.
+- Blur invalid number -> error icon/message shown.
+- Focus again and edit -> internal error hidden while editing.
+- `state="error"` from parent shows immediately regardless of focus.