@leavepulse/ui 0.43.4 → 0.45.0

package/src/components/LpMediaGallery.vue

@@ -24,7 +24,7 @@
  * cover is per image and the reveal is remembered per image, because a set is
  * usually mixed — one marked screenshot among plain ones.
  */
-import { computed, ref } from "vue"
+import { computed, ref, watch } from "vue"
 import type { LightboxItem } from "./lightbox"
 import { useMergedAttrs } from "../composables/useMergedClass"
 import LpIcon from "./LpIcon.vue"
@@ -88,6 +88,12 @@ defineSlots<{
 const open = ref(false)
 const index = ref(0)
 
+// Closing happens inside the lightbox (Escape, the scrim, the X), so the gallery
+// reports both edges of v-model:open, not only the one it starts.
+watch(open, (value, was) => {
+  if (!value && was) emit("update:open", false)
+})
+
 // `max` counts what is SHOWN, so the badge reads "+N more" rather than "N
 // total". A set of 7 capped at 4 shows 4 cells, the last one badged +3.
 const visible = computed(() =>
@@ -188,8 +194,8 @@ function activate(i: number) {
   const at = openIndexOf(i)
   if (at === -1) return
   index.value = at
+  if (!open.value) emit("update:open", true)
   open.value = true
-  emit("update:open", true)
 }
 
 /** The badge is about the FIRST hidden image, so that is where it opens. */

package/src/components/LpModal.vue

@@ -10,6 +10,7 @@ import {
 } from "reka-ui"
 import { computed, onBeforeUnmount, ref, useSlots, watch } from "vue"
 import { useGlass } from "../composables/useGlass"
+import { useLabels } from "../composables/useLpConfig"
 import { useShift } from "../composables/useShift"
 import { useModalLayer } from "./modalDepth"
 import { CLOSE_ICON } from "./dropdown"
@@ -33,7 +34,8 @@ import LpScrollArea from "./LpScrollArea.vue"
  * same fix, as the lightbox's own rungs in tokens.css — only the depth here is
  * not known until a dialog finds itself inside another.
  */
-const { claim, release, layer } = useModalLayer()
+const panelRef = ref<HTMLElement | null>(null)
+const { claim, release, layer } = useModalLayer({ element: () => panelRef.value?.parentElement })
 
 const props = withDefaults(
   defineProps<{
@@ -70,10 +72,20 @@ const props = withDefaults(
      * `provideGlass`, and without one it is off.
      */
     glass?: boolean
+    /**
+     * Accessible name for a dialog without a visible `title`. Rendered as a
+     * visually hidden title, so assistive tech still announces what opened.
+     */
+    ariaLabel?: string
+    /** `alertdialog` for a prompt that interrupts the user (a confirmation). */
+    role?: "dialog" | "alertdialog"
+    labels?: Partial<{ close: string }>
   }>(),
   { size: "md", autoFocus: "auto", glass: undefined },
 )
 
+const text = useLabels("modal", { close: "Close" }, () => props.labels)
+
 const frosted = useGlass(() => props.glass)
 
 defineEmits<{ (e: "update:open", value: boolean): void }>()
@@ -95,9 +107,10 @@ const onInteractOutside = (event: Event) => {
   }
 }
 
-const describedByAttrs = computed(() =>
-  props.description ? {} : { "aria-describedby": undefined },
-)
+const describedByAttrs = computed(() => ({
+  ...(props.description ? {} : { "aria-describedby": undefined }),
+  ...(props.role ? { role: props.role } : {}),
+}))
 
 const widthClass = computed(() => {
   if (props.width) return ""
@@ -152,15 +165,13 @@ const bodyPad = computed(() =>
  * scroll area exactly as before. A panel whose size never moves is pinned once
  * and never transitions.
  */
-const panelRef = ref<HTMLElement | null>(null)
-
 /**
  * Controls that are worth landing on when the dialog opens, in order of
  * preference. A field the user is going to type in wins over a button, since
  * typing is the reason most dialogs exist.
  */
 const AUTO_FOCUS_ORDER = [
-  "input:not([type=hidden]):not([disabled]):not([readonly])",
+  "input:not([type=hidden]):not([disabled]):not([readonly]):not([tabindex='-1'])",
   "textarea:not([disabled]):not([readonly])",
   "select:not([disabled])",
   "[data-lp-autofocus]",
@@ -178,6 +189,18 @@ const AUTO_FOCUS_ORDER = [
  *
  * Both are fixed here: pick a meaningful target, and mark it so the ring shows.
  */
+/**
+ * Whether a candidate can actually take focus: reka renders hidden form inputs
+ * for its switches and checkboxes, and a control hidden at this breakpoint
+ * (`lg:hidden`) is in the DOM but not on screen.
+ */
+function focusable(el: HTMLElement): boolean {
+  if (el.hasAttribute("disabled") || el.getAttribute("tabindex") === "-1") return false
+  if (el.closest("[aria-hidden='true'], [data-hidden], [inert]")) return false
+  if (typeof el.checkVisibility === "function") return el.checkVisibility({ visibilityProperty: true })
+  return el.getClientRects().length > 0
+}
+
 function onOpenAutoFocus(event: Event) {
   if (props.autoFocus === "none") return
   const panel = panelRef.value
@@ -186,26 +209,26 @@ function onOpenAutoFocus(event: Event) {
   const selectors =
     props.autoFocus === "auto" ? AUTO_FOCUS_ORDER : [props.autoFocus]
   for (const selector of selectors) {
-    const target = panel.querySelector<HTMLElement>(selector)
-    if (!target || target.hasAttribute("disabled")) continue
-    event.preventDefault()
-    // `focus-visible` is the browser's own heuristic and cannot be forced, so
-    // the ring is driven off an attribute the kit owns. Removed as soon as the
-    // element loses focus, leaving normal focus-visible behaviour in charge.
-    //
-    // Skipped for a control whose own shell already draws a ring on
-    // focus-within: our fields put the border and ring on the wrapper, so
-    // adding one to the bare <input> stacks a second ring inside the first.
-    if (!target.closest("[data-lp-ring-owner]")) {
-      target.setAttribute("data-lp-focus-ring", "")
-      target.addEventListener(
-        "blur",
-        () => target.removeAttribute("data-lp-focus-ring"),
-        { once: true },
-      )
+    for (const target of panel.querySelectorAll<HTMLElement>(selector)) {
+      if (!focusable(target)) continue
+      target.focus()
+      // Only once focus really landed: a prevented auto-focus that failed would
+      // leave the keyboard on the page behind the dialog.
+      if (document.activeElement !== target) continue
+      event.preventDefault()
+      // `focus-visible` is the browser's own heuristic and cannot be forced, so
+      // the ring is driven off an attribute the kit owns. Skipped for a control
+      // whose own shell already draws a ring on focus-within.
+      if (!target.closest("[data-lp-ring-owner]")) {
+        target.setAttribute("data-lp-focus-ring", "")
+        target.addEventListener(
+          "blur",
+          () => target.removeAttribute("data-lp-focus-ring"),
+          { once: true },
+        )
+      }
+      return
     }
-    target.focus()
-    return
   }
 }
 // The panel's height eases between content-derived sizes — see
@@ -301,10 +324,13 @@ watch(
       </aside>
       <div
         ref="panelRef"
-        class="flex max-h-[min(90vh,calc(100dvh-2rem))] min-h-0 flex-col overflow-hidden rounded-card border border-line shadow-panel"
+        class="relative flex max-h-[min(90vh,calc(100dvh-2rem))] min-h-0 flex-col overflow-hidden rounded-card border border-line shadow-panel"
         :class="[frosted ? (layer.nested ? 'lp-glass-overlay--nested' : 'lp-glass-overlay') : 'bg-surface-raised', widthClass, tweening ? 'transition-[height] duration-fast ease-[var(--ease-emphasized)] motion-reduce:transition-none' : '']"
         :style="{ ...(width ? { width } : {}), ...(hasAside ? { alignSelf: 'stretch' } : {}) }"
       >
+        <DialogTitle v-if="!(title || $slots.title) && ariaLabel" class="sr-only">
+          {{ ariaLabel }}
+        </DialogTitle>
         <header v-if="title || $slots.title" class="flex shrink-0 items-start justify-between gap-4 p-5 pb-3">
           <div class="flex flex-col gap-1">
             <DialogTitle class="text-base font-semibold text-ink">
@@ -319,7 +345,7 @@ watch(
           <DialogClose
             data-lp-dialog-close
             class="group flex shrink-0 items-center rounded-md p-1 text-muted outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring"
-            aria-label="Close"
+            :aria-label="text.close"
           >
             <LpIcon
               name="lucide:x"

package/src/components/LpModalNav.vue

@@ -14,6 +14,7 @@
  * one the sections are simply unreachable on a phone.
  */
 import { computed, ref } from "vue"
+import { useLabels } from "../composables/useLpConfig"
 import LpButton from "./LpButton.vue"
 import LpIcon from "./LpIcon.vue"
 import LpModal from "./LpModal.vue"
@@ -62,7 +63,6 @@ const props = withDefaults(
     size: "2xl",
     navWidth: "13rem",
     mobileBreakpoint: "lg",
-    navLabel: "Sections",
     navSide: "start",
     glass: undefined,
   },
@@ -73,6 +73,9 @@ const emit = defineEmits<{
   (e: "update:modelValue", value: string): void
 }>()
 
+const text = useLabels("modalNav", { nav: "Sections" })
+const navName = computed(() => props.navLabel ?? text.value.nav)
+
 const navOpen = ref(false)
 
 const active = computed({
@@ -187,7 +190,7 @@ const railStyle = { maxHeight: "min(90vh, calc(100dvh - 2rem))" }
           variant="ghost"
           size="sm"
           square
-          :aria-label="navLabel"
+          :aria-label="navName"
           :class="triggerClass"
           @click="navOpen = true"
         >

package/src/components/LpNotificationBell.vue

@@ -8,13 +8,15 @@
  * `select`. Mirrors the kit convention (cf. LpSidebar): data in, events out,
  * no data fetching inside.
  */
-import { computed, getCurrentInstance } from "vue"
+import { computed, getCurrentInstance, onBeforeUnmount, onMounted, ref } from "vue"
+import { useLabels } from "../composables/useLpConfig"
 import LpBadge from "./LpBadge.vue"
 import LpButton from "./LpButton.vue"
 import LpContextMenu, { type ContextMenuItemDef } from "./LpContextMenu.vue"
 import LpEmptyState from "./LpEmptyState.vue"
 import LpIcon from "./LpIcon.vue"
 import LpPopover from "./LpPopover.vue"
+import LpRollingText from "./LpRollingText.vue"
 import LpScrollArea from "./LpScrollArea.vue"
 import LpShift from "./LpShift.vue"
 
@@ -56,6 +58,15 @@ export interface NotificationLabels {
   dismiss?: string
   empty?: string
   ariaLabel?: string
+  /** Appended to the button's name while there is unread news; `{count}` is filled in. */
+  unread?: string
+  /** Screen-reader marker on an unread row. */
+  unreadItem?: string
+  /** Relative times; `{n}` is filled in. */
+  justNow?: string
+  minutes?: string
+  hours?: string
+  days?: string
 }
 
 const props = withDefaults(
@@ -83,16 +94,32 @@ const props = withDefaults(
 
 // Single lookup for every label, so the template never repeats the fallbacks.
 // `title` stays a top-level prop for compatibility and wins over labels.title.
+const text = useLabels(
+  "notifications",
+  {
+    title: "Notifications",
+    markAllRead: "Mark all read",
+    clear: "Clear",
+    markAsRead: "Mark as read",
+    markAsUnread: "Mark as unread",
+    open: "Open",
+    dismiss: "Dismiss",
+    empty: "No notifications",
+    ariaLabel: "",
+    unread: "{count} unread",
+    unreadItem: "Unread",
+    justNow: "just now",
+    minutes: "{n}m",
+    hours: "{n}h",
+    days: "{n}d",
+  },
+  () => props.labels,
+)
 const l = computed(() => ({
-  title: props.title ?? props.labels?.title ?? "Notifications",
-  markAllRead: props.labels?.markAllRead ?? "Mark all read",
-  clear: props.labels?.clear ?? "Clear",
-  markAsRead: props.labels?.markAsRead ?? "Mark as read",
-  markAsUnread: props.labels?.markAsUnread ?? "Mark as unread",
-  open: props.labels?.open ?? "Open",
-  dismiss: props.labels?.dismiss ?? "Dismiss",
-  empty: props.emptyLabel ?? props.labels?.empty ?? "No notifications",
-  ariaLabel: props.labels?.ariaLabel ?? props.labels?.title ?? "Notifications",
+  ...text.value,
+  title: props.title ?? text.value.title,
+  empty: props.emptyLabel ?? text.value.empty,
+  ariaLabel: text.value.ariaLabel || text.value.title,
 }))
 
 // Popover open state. A defineModel (not a plain `open` prop) gives a local
@@ -119,6 +146,11 @@ const badgeLabel = computed(() =>
 )
 const hasUnread = computed(() => unread.value > 0)
 
+// The badge is drawn, not read: its count goes into the button's own name.
+const buttonLabel = computed(() =>
+  hasUnread.value ? `${l.value.ariaLabel}, ${l.value.unread.replace("{count}", String(unread.value))}` : l.value.ariaLabel,
+)
+
 /** Icon tints for an unread row, keyed by the item's category tone. */
 const TONE_CLASS: Record<string, string> = {
   brand: "bg-brand-soft text-brand",
@@ -208,19 +240,32 @@ function rowMenu(item: NotificationItem): ContextMenuItemDef[] {
 
 // Compact relative time ("just now", "5m", "3h", "2d"); falls back to a date.
 // A `formatTime` prop takes over entirely — that's the localisation seam.
+//
+// The clock is only read after mount and then ticks, so a server render and the
+// hydrating client agree (both print nothing) and "just now" does not stay
+// "just now" for the life of the page.
+const now = ref<number | null>(null)
+let clock: ReturnType<typeof setInterval> | undefined
+onMounted(() => {
+  now.value = Date.now()
+  clock = setInterval(() => (now.value = Date.now()), 30_000)
+})
+onBeforeUnmount(() => clearInterval(clock))
+
 function timeAgo(iso?: string): string {
-  if (!iso) return ""
+  if (!iso || now.value === null) return ""
   if (props.formatTime) return props.formatTime(iso)
   const then = new Date(iso).getTime()
   if (Number.isNaN(then)) return ""
-  const secs = Math.max(0, Math.round((Date.now() - then) / 1000))
-  if (secs < 45) return "just now"
+  const secs = Math.max(0, Math.round((now.value - then) / 1000))
+  const n = (template: string, value: number) => template.replace("{n}", String(value))
+  if (secs < 45) return l.value.justNow
   const mins = Math.round(secs / 60)
-  if (mins < 60) return `${mins}m`
+  if (mins < 60) return n(l.value.minutes, mins)
   const hrs = Math.round(mins / 60)
-  if (hrs < 24) return `${hrs}h`
+  if (hrs < 24) return n(l.value.hours, hrs)
   const days = Math.round(hrs / 24)
-  if (days < 7) return `${days}d`
+  if (days < 7) return n(l.value.days, days)
   return new Date(then).toLocaleDateString()
 }
 </script>
@@ -243,17 +288,25 @@ function timeAgo(iso?: string): string {
           variant="ghost"
           size="sm"
           class="relative"
-          :aria-label="l.ariaLabel"
+          :aria-label="buttonLabel"
           @click="open = !open"
         >
           <LpIcon name="lucide:bell" :size="18" />
-          <LpBadge
-            v-if="hasUnread"
-            tone="danger"
-            class="absolute -right-1 -top-1 min-w-4 justify-center px-1 py-0 text-[10px] leading-4"
+          <!-- The badge pops in and out, and its count rolls rather than
+               swapping, so new mail reads as arriving. -->
+          <Transition
+            enter-active-class="animate-[chip-in_var(--duration-fast)_var(--ease-emphasized)] motion-reduce:animate-none"
+            leave-active-class="animate-[chip-out_var(--duration-fast)_ease] motion-reduce:animate-none"
           >
-            {{ badgeLabel }}
-          </LpBadge>
+            <LpBadge
+              v-if="hasUnread"
+              aria-hidden="true"
+              tone="danger"
+              class="absolute -right-1 -top-1 min-w-4 justify-center px-1 py-0 text-[10px] leading-4"
+            >
+              <LpRollingText :value="badgeLabel" :duration="220" />
+            </LpBadge>
+          </Transition>
         </LpButton>
       </LpContextMenu>
     </template>
@@ -327,6 +380,7 @@ function timeAgo(iso?: string): string {
                   {{ item.title }}
                 </span>
                 <span v-if="!item.read" class="size-1.5 shrink-0 rounded-full bg-brand" />
+                <span v-if="!item.read" class="sr-only">{{ l.unreadItem }}</span>
               </span>
               <span v-if="item.body" class="mt-0.5 line-clamp-2 block text-xs text-muted">
                 {{ item.body }}

package/src/components/LpNumberField.vue

@@ -13,11 +13,12 @@ import {
   NumberFieldInput,
   NumberFieldRoot,
 } from "reka-ui"
-import { useId } from "vue"
+import { computed, useId } from "vue"
 import LpIcon from "./LpIcon.vue"
+import { useFieldControl } from "../composables/useField"
 import { useMergedAttrs } from "../composables/useMergedClass"
 
-defineProps<{
+const props = defineProps<{
   // null = empty field (reka's native state); consumers that need a number
   // should default it themselves, the field doesn't invent a value.
   modelValue?: number | null
@@ -30,6 +31,7 @@ defineProps<{
   // "Depth", "Weight" tells the reader nothing about which one wants grams.
   // Not part of the value: it is never typed, selected, or submitted.
   unit?: string
+  invalid?: boolean
 }>()
 
 defineEmits<{ (e: "update:modelValue", value: number | null): void }>()
@@ -39,9 +41,19 @@ defineEmits<{ (e: "update:modelValue", value: number | null): void }>()
 // and leaves out the milliamps that make it mean anything.
 const unitId = useId()
 
+const field = useFieldControl(() => ({ wrapped: false, invalid: props.invalid, disabled: props.disabled }))
+const describedBy = computed(
+  () => [field.value.describedBy, props.unit ? unitId : undefined].filter(Boolean).join(" ") || undefined,
+)
+
 // The field is full-width with its own control frame — the two things a consumer laying out a compact numeric column needs to change.
-const { class: rootClass, attrs: rest } = useMergedAttrs(
-  "flex h-(--size-control-md) w-full items-center rounded-control border border-line bg-surface-soft transition-colors duration-[var(--duration-fast)] focus-within:border-brand focus-within:ring-2 focus-within:ring-ring data-[disabled]:cursor-not-allowed data-[disabled]:opacity-55",
+const { class: rootClass, attrs: rest } = useMergedAttrs(() =>
+  [
+    "flex h-(--size-control-md) w-full items-center rounded-control border bg-surface-soft transition-colors duration-[var(--duration-fast)] focus-within:ring-2 data-[disabled]:cursor-not-allowed data-[disabled]:opacity-55",
+    field.value.invalid
+      ? "border-danger focus-within:border-danger focus-within:ring-danger-soft"
+      : "border-line focus-within:border-brand focus-within:ring-ring",
+  ].join(" "),
 )
 </script>
 
@@ -51,7 +63,8 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
     :min="min"
     :max="max"
     :step="step"
-    :disabled="disabled"
+    :disabled="field.disabled"
+    :required="field.required"
     data-lp-ring-owner
     :class="rootClass"
     v-bind="rest"
@@ -67,7 +80,9 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
       />
     </NumberFieldDecrement>
     <NumberFieldInput
-      :aria-describedby="unit ? unitId : undefined"
+      :id="field.id"
+      :aria-describedby="describedBy"
+      :aria-invalid="field.invalid || undefined"
       class="min-w-0 flex-1 bg-transparent text-center text-sm text-ink outline-none [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none"
     />
     <!-- The unit sits between the value and the increment button, so a long one

package/src/components/LpNumberFlow.vue

@@ -126,6 +126,15 @@ const travel = (to: number) => {
   const from = displayed.value
   if (from === to) return
 
+  // Infinity and NaN (a rate divided by zero) have no digits to roll through.
+  if (!Number.isFinite(to) || !Number.isFinite(from)) {
+    displayed.value = to
+    lastTarget = to
+    settled.value = true
+    padTo.value = 0
+    return
+  }
+
   if (prefersReducedMotion() || props.duration <= 0) {
     displayed.value = to
     return
@@ -221,7 +230,11 @@ const UNITS = [
 
 const scaleFor = (v: number) => {
   const abs = Math.abs(v)
-  const unit = UNITS.find((u) => abs >= u.limit)
+  let at = UNITS.findIndex((u) => abs >= u.limit)
+  // 999 950 at one place reads "1000.0k"; that is the next unit up.
+  if (at > 0 && Math.abs(Number((v / UNITS[at].limit).toFixed(1))) >= 1000) at--
+  if (at === -1 && abs >= 999.5) at = UNITS.length - 1
+  const unit = UNITS[at]
   if (!unit) return { divisor: 1, suffix: "", decimals: 0 }
   // One decimal is what makes 1.2k readable; a value that lands exactly on the
   // unit (5M) keeps none, matching how these are written by hand.
@@ -234,11 +247,13 @@ const scaleFor = (v: number) => {
 }
 
 
-const formatted = computed(() => {
-  // Rounded first: every branch below should render the shape the endpoints
-  // imply, not whatever precision an intermediate value happens to carry.
-  const v = round(displayed.value)
+const formatted = computed(() => formatAt(round(displayed.value), !settled.value))
+
+// Rounded first by the caller: every branch should render the shape the
+// endpoints imply, not whatever precision an intermediate value carries.
+function formatAt(v: number, padded: boolean): string {
   if (props.format) return props.format(v)
+  if (!Number.isFinite(v)) return String(v)
   if (props.compact) {
     /*
      * The unit tracks the CURRENT value, not the destination — the way a real
@@ -254,7 +269,7 @@ const formatted = computed(() => {
     const places = divisor === 1 ? 0 : 1
     return `${(v / divisor).toFixed(places)}${suffix}`
   }
-  const pad = settled.value ? 1 : Math.max(1, padTo.value)
+  const pad = padded ? Math.max(1, padTo.value) : 1
   if (props.grouped)
     return v.toLocaleString(props.locale, {
       minimumFractionDigits: props.decimals,
@@ -271,7 +286,7 @@ const formatted = computed(() => {
   const int = dot === -1 ? body : body.slice(0, dot)
   const rest = dot === -1 ? "" : body.slice(dot)
   return `${neg ? "-" : ""}${int.padStart(pad, "0")}${rest}`
-})
+}
 
 interface Cell {
   /** Stable across renders so a column keeps its identity as digits shift. */
@@ -357,8 +372,10 @@ const offsetFor = (digit: number) => {
   return digit
 }
 
+/* What a screen reader hears: the settled value, formatted the way it will
+   land, never a frame of the roll. */
 const label = computed(
-  () => `${props.prefix ?? ""}${props.value}${props.suffix ?? ""}`,
+  () => `${props.prefix ?? ""}${formatAt(props.value, false)}${props.suffix ?? ""}`,
 )
 </script>
 
@@ -368,9 +385,8 @@ const label = computed(
   <span
     ref="revealAnchor"
     class="lp-nf inline-flex items-baseline tabular-nums"
-    :aria-label="label"
-    role="text"
   >
+    <span class="sr-only">{{ label }}</span>
     <span v-if="prefix" aria-hidden="true">{{ prefix }}</span>
 
     <span class="lp-nf__track inline-flex items-baseline" aria-hidden="true">

package/src/components/LpOtpInput.vue

@@ -16,8 +16,10 @@ export default { inheritAttrs: false }
  * is filled. Digits-only by default (TOTP); flip `alphanumeric` for backup codes.
  */
 import { PinInputInput, PinInputRoot } from "reka-ui"
-import { computed } from "vue"
+import { computed, ref, watch } from "vue"
+import { useFieldControl } from "../composables/useField"
 import { useMergedAttrs } from "../composables/useMergedClass"
+import { joinCells, splitCode, type OtpCells } from "./otp"
 
 const props = withDefaults(
   defineProps<{
@@ -45,13 +47,44 @@ const emit = defineEmits<{
 
 // reka models the value as an array of per-cell strings; we bridge to a single
 // string at the boundary so callers never touch the array shape.
+//
+// The cells are kept here, positions and all, rather than re-split from the
+// string on every render: clearing a middle cell leaves a gap the string cannot
+// express, and re-splitting it shifted every later digit one cell left. The
+// cells are only rebuilt when the model changes from outside.
+const local = ref<string[]>(splitCode(props.modelValue, props.length))
+let emitted = props.modelValue ?? ""
+watch(
+  () => props.modelValue ?? "",
+  (value) => {
+    if (value === emitted) return
+    emitted = value
+    local.value = splitCode(value, props.length)
+  },
+)
+watch(
+  () => props.length,
+  (length) => {
+    local.value = local.value.slice(0, length)
+  },
+)
 const cells = computed<string[]>({
-  get: () => (props.modelValue ?? "").split("").slice(0, props.length),
-  set: (arr) => emit("update:modelValue", arr.join("")),
+  get: () => local.value,
+  set: (arr) => {
+    local.value = arr
+    emitted = joinCells(arr)
+    emit("update:modelValue", emitted)
+  },
 })
 
-function onComplete(arr: string[]) {
-  emit("complete", arr.join(""))
+const field = useFieldControl(() => ({
+  wrapped: false,
+  invalid: props.invalid,
+  disabled: props.disabled,
+}))
+
+function onComplete(arr: OtpCells) {
+  emit("complete", joinCells(arr))
 }
 
 const cellSize = {
@@ -71,7 +104,7 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
     v-model="cells"
     :type="alphanumeric ? 'text' : 'number'"
     :mask="mask"
-    :disabled="disabled"
+    :disabled="field.disabled"
     otp
     :class="rootClass"
     v-bind="rest"
@@ -81,14 +114,16 @@ const { class: rootClass, attrs: rest } = useMergedAttrs(
       v-for="i in length"
       :key="i"
       :index="i - 1"
-      :aria-invalid="invalid || undefined"
+      :id="i === 1 ? field.id : undefined"
+      :aria-invalid="field.invalid || undefined"
+      :aria-describedby="field.describedBy"
       :class="[
         cellSize[size],
         'rounded-control border bg-surface-soft text-center font-semibold text-ink caret-brand',
         'outline-none transition-colors duration-[var(--duration-fast)]',
         'focus:border-brand focus:ring-2 focus:ring-ring',
         'disabled:cursor-not-allowed disabled:opacity-55',
-        invalid ? 'border-danger focus:border-danger focus:ring-danger-soft' : 'border-line',
+        field.invalid ? 'border-danger focus:border-danger focus:ring-danger-soft' : 'border-line',
       ]"
     />
   </PinInputRoot>