@svgrid/grid 1.2.33 → 2.0.0

package/src/countries.ts

@@ -68,4 +68,29 @@ export const COUNTRIES: Country[] = [
   { code: 'MX', name: 'Mexico', dial: '+52' },
 ]
 
+/**
+ * Expected national (post-dial-code) significant-digit count per country, as an
+ * exact length or an inclusive [min, max] range. A pragmatic length-based check
+ * (not full libphonenumber). Countries without an entry accept any non-empty
+ * number.
+ */
+export const PHONE_NATIONAL_LENGTHS: Record<string, number | [number, number]> = {
+  US: 10, CA: 10, GB: 10, IE: 9, FR: 9, DE: [10, 11], ES: 9, IT: [9, 10], NL: 9, BE: [8, 9],
+  CH: 9, AT: [10, 12], SE: [7, 9], NO: 8, DK: 8, FI: [9, 10], PL: 9, PT: 9, GR: 10, CZ: 9,
+  RU: 10, TR: 10, IL: 9, AE: 9, SA: 9, IN: 10, PK: 10, CN: 11, HK: 8, JP: 10, KR: [9, 10],
+  SG: 8, MY: [9, 10], TH: 9, ID: [9, 11], PH: 10, VN: 9, AU: 9, NZ: [8, 10], ZA: 9, NG: 10,
+  EG: 10, KE: 9, MA: 9, BR: 11, AR: 10, CL: 9, CO: 10, MX: 10,
+}
+
+/**
+ * Whether `nationalDigits` is a plausible national number for `code` (length
+ * check). Unknown countries pass on any non-empty input. Pure.
+ */
+export function phoneDigitsValid(code: string, nationalDigits: string): boolean {
+  const n = (nationalDigits.match(/\d/g) ?? []).length
+  const rule = PHONE_NATIONAL_LENGTHS[code.toUpperCase()]
+  if (rule == null) return n > 0
+  return typeof rule === 'number' ? n === rule : n >= rule[0] && n <= rule[1]
+}
+
 export const COUNTRY_BY_CODE = new Map(COUNTRIES.map((c) => [c.code, c]))

package/src/createAccordion.svelte.ts

@@ -0,0 +1,126 @@
+/**
+ * createAccordion - the HEADLESS core behind <SvAccordion>: a WAI-ARIA accordion
+ * (collapsible sections) with single- or multiple-expand, roving header focus
+ * (Up/Down/Home/End) and full ARIA, exposed as **prop-getters** you spread onto
+ * YOUR OWN markup. No styles, no DOM. Parity: Smart `smart-accordion`.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createAccordion } from '@svgrid/grid'
+ *   let expanded = $state<string[]>(['a'])
+ *   const acc = createAccordion({ items: () => items, expanded: () => expanded, onChange: (ids) => (expanded = ids) })
+ * </script>
+ * {#each items as it, i (it.id)}
+ *   <h3><button {...acc.headerProps(i)}>{it.label}</button></h3>
+ *   {#if acc.isExpanded(it.id)}<div {...acc.panelProps(i)}>...</div>{/if}
+ * {/each}
+ * ```
+ *
+ * The styled <SvAccordion> is one renderer over this core. DOM focus movement is
+ * a render concern: the component watches `focusTick`/`focusIndex` and calls
+ * `.focus()` itself.
+ */
+export type AccordionItem = { id: string; label: string; disabled?: boolean }
+/** `single` keeps at most one panel open; `multiple` allows any number. */
+export type AccordionExpandMode = 'single' | 'multiple'
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type AccordionConfig = {
+  items: () => ReadonlyArray<AccordionItem>
+  /** Expanded item ids (controlled). */
+  expanded: () => string[]
+  onChange?: (expandedIds: string[]) => void
+  expandMode?: () => AccordionExpandMode
+  disabled?: () => boolean
+  dir?: () => 'ltr' | 'rtl' | 'auto' | undefined
+}
+
+let uid = 0
+
+export function createAccordion(config: AccordionConfig) {
+  const id = `sv-acc-${uid++}`
+  const items = () => config.items()
+  const expandMode = () => config.expandMode?.() ?? 'single'
+  const disabled = () => config.disabled?.() ?? false
+
+  const expandedSet = $derived(new Set(config.expanded()))
+  const enabledIdx = $derived(items().map((it, i) => (it.disabled ? -1 : i)).filter((i) => i >= 0))
+
+  let focusIndex = $state(0)
+  let focusTick = $state(0)
+  const requestFocus = (i: number) => { focusIndex = i; focusTick++ }
+
+  const headerId = (i: number) => `${id}-h-${i}`
+  const panelId = (i: number) => `${id}-p-${i}`
+  const isExpanded = (itemId: string) => expandedSet.has(itemId)
+
+  function toggle(i: number) {
+    const it = items()[i]
+    if (!it || it.disabled || disabled()) return
+    const open = expandedSet.has(it.id)
+    if (expandMode() === 'single') {
+      config.onChange?.(open ? [] : [it.id])
+    } else {
+      const next = new Set(expandedSet)
+      open ? next.delete(it.id) : next.add(it.id)
+      config.onChange?.([...next])
+    }
+  }
+
+  function move(delta: number) {
+    if (!enabledIdx.length) return
+    const pos = enabledIdx.indexOf(focusIndex)
+    const base = pos < 0 ? 0 : pos
+    const next = enabledIdx[(base + delta + enabledIdx.length) % enabledIdx.length]
+    if (next != null) requestFocus(next)
+  }
+
+  function onHeaderKeydown(e: KeyboardEvent, i: number) {
+    if (disabled()) return
+    switch (e.key) {
+      case 'ArrowDown': e.preventDefault(); move(1); break
+      case 'ArrowUp': e.preventDefault(); move(-1); break
+      case 'Home': e.preventDefault(); requestFocus(enabledIdx[0] ?? 0); break
+      case 'End': e.preventDefault(); requestFocus(enabledIdx.at(-1) ?? 0); break
+      case 'Enter':
+      case ' ': e.preventDefault(); toggle(i); break
+    }
+  }
+
+  return {
+    /** Header index that should hold DOM focus after the latest keyboard move. */
+    get focusIndex() { return focusIndex },
+    /** Monotonic counter; changes only on keyboard navigation. */
+    get focusTick() { return focusTick },
+    /** Currently-expanded item ids. */
+    get expandedIds() { return [...expandedSet] },
+    isExpanded,
+    toggle,
+    /** Spread onto the accordion root container. */
+    rootProps: () => ({
+      'data-orientation': 'vertical' as const,
+    }),
+    /** Spread onto the header <button> at `index`. */
+    headerProps: (index: number) => {
+      const it = items()[index]
+      return {
+        type: 'button' as const,
+        id: headerId(index),
+        'data-idx': index,
+        'aria-expanded': it ? isExpanded(it.id) : false,
+        'aria-controls': panelId(index),
+        disabled: disabled() || it?.disabled || undefined,
+        onclick: () => toggle(index),
+        onkeydown: (e: KeyboardEvent) => onHeaderKeydown(e, index),
+      }
+    },
+    /** Spread onto the panel/region element at `index`. */
+    panelProps: (index: number) => ({
+      role: 'region' as const,
+      id: panelId(index),
+      'aria-labelledby': headerId(index),
+    }),
+  }
+}
+
+export type Accordion = ReturnType<typeof createAccordion>

package/src/createAutocomplete.svelte.ts

@@ -20,6 +20,7 @@
  * ```
  */
 import { filterOptions, type ListOption } from './list-option'
+import { editorAria, type EditorAriaState } from './editor-contract'
 
 /** Reactive inputs are passed as getters so the core tracks live prop changes. */
 export type AutocompleteConfig = {
@@ -32,11 +33,26 @@ export type AutocompleteConfig = {
   ariaLabel?: () => string | undefined
   /** DOM focus hook provided by the renderer; the core never touches the DOM. */
   focusInput?: () => void
+  // Editor contract (ARIA + validation) - folded into inputProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
 }
 
 export function createAutocomplete(config: AutocompleteConfig) {
   const minChars = () => config.minChars?.() ?? 1
 
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
   let open = $state(false)
   let active = $state(0)
 
@@ -75,10 +91,11 @@ export function createAutocomplete(config: AutocompleteConfig) {
     onKeydown,
     /** Spread onto the text <input>. */
     inputProps: () => ({
+      id: config.id?.(),
       role: 'combobox' as const,
       'aria-expanded': open,
       'aria-autocomplete': 'list' as const,
-      'aria-label': config.ariaLabel?.(),
+      ...editorAria(ariaState()),
       value: config.value(),
       disabled: config.disabled?.() ?? false,
       oninput: onInput,

package/src/createButtonGroup.svelte.ts

@@ -0,0 +1,166 @@
+/**
+ * createButtonGroup - the HEADLESS core behind <SvButtonGroup>: a segmented
+ * button bar with single- or multi-select (or plain action buttons), roving
+ * tabindex + full keyboard, exposed as **prop-getters** you spread onto YOUR OWN
+ * markup. No styles, no DOM. Parity: Smart `smart-button-group`.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createButtonGroup } from '@svgrid/grid'
+ *   let value = $state<string | null>('day')
+ *   const g = createButtonGroup({ items: () => items, value: () => value, onChange: (v) => (value = v) })
+ * </script>
+ * <div {...g.rootProps()}>
+ *   {#each items as it, i (it.value)}<button {...g.buttonProps(i)}>{it.label}</button>{/each}
+ * </div>
+ * ```
+ *
+ * The styled <SvButtonGroup> is one renderer over this core.
+ */
+import { editorAria, type EditorAriaState } from './editor-contract'
+
+export type ButtonGroupItem = { value: string | number; label?: string; disabled?: boolean }
+/** `single` = radio semantics; `multiple` = toggle set; `none` = action buttons. */
+export type ButtonGroupMode = 'single' | 'multiple' | 'none'
+export type ButtonGroupValue = string | number | Array<string | number> | null
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type ButtonGroupConfig = {
+  items: () => ReadonlyArray<ButtonGroupItem>
+  value: () => ButtonGroupValue
+  onChange?: (value: string | number | Array<string | number>) => void
+  mode?: () => ButtonGroupMode
+  disabled?: () => boolean
+  orientation?: () => 'horizontal' | 'vertical'
+  /** Under `'rtl'` the horizontal Left/Right arrow direction flips. */
+  dir?: () => 'ltr' | 'rtl' | 'auto' | undefined
+  // Editor contract (ARIA + validation) - folded into rootProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
+  ariaLabel?: () => string | undefined
+}
+
+/** Normalize the value to an array (pure). */
+export function toGroupArray(value: ButtonGroupValue): Array<string | number> {
+  if (value == null) return []
+  return Array.isArray(value) ? [...value] : [value]
+}
+
+export function createButtonGroup(config: ButtonGroupConfig) {
+  const items = () => config.items()
+  const mode = () => config.mode?.() ?? 'single'
+  const disabled = () => config.disabled?.() ?? false
+  const isVert = () => (config.orientation?.() ?? 'horizontal') === 'vertical'
+  const rtl = () => config.dir?.() === 'rtl'
+
+  const selected = $derived(toGroupArray(config.value()))
+  const enabledIdx = $derived(items().map((it, i) => (it.disabled ? -1 : i)).filter((i) => i >= 0))
+
+  const isSelected = (v: string | number) => selected.includes(v)
+  const selectedIdx = $derived(items().findIndex((it) => isSelected(it.value)))
+
+  // Focus cursor. In single (radio) mode moving the cursor also selects, so the
+  // roving-tabindex target follows the selection; multiple/none keep their own
+  // cursor in `active`.
+  let active = $state(0)
+  $effect(() => {
+    const it = items()[active]
+    if (!it || it.disabled) active = enabledIdx[0] ?? 0
+  })
+  const cursor = $derived(
+    mode() === 'single' ? (selectedIdx >= 0 ? selectedIdx : enabledIdx[0] ?? 0) : active,
+  )
+
+  function pick(i: number) {
+    const it = items()[i]
+    if (!it || it.disabled || disabled()) return
+    active = i
+    if (mode() === 'none') { config.onChange?.(it.value); return }
+    if (mode() === 'multiple') {
+      const set = new Set(selected)
+      set.has(it.value) ? set.delete(it.value) : set.add(it.value)
+      config.onChange?.([...set])
+    } else {
+      config.onChange?.(it.value)
+    }
+  }
+
+  function goto(i: number) {
+    // Radio semantics select on move; toggle/action only move focus.
+    if (mode() === 'single') pick(i)
+    else active = i
+  }
+  function move(delta: number) {
+    if (!enabledIdx.length) return
+    const pos = enabledIdx.indexOf(cursor)
+    const next = enabledIdx[(pos + delta + enabledIdx.length) % enabledIdx.length]
+    if (next != null) goto(next)
+  }
+
+  function onKeydown(e: KeyboardEvent) {
+    if (disabled()) return
+    const horiz = !isVert()
+    const rtlH = horiz && rtl()
+    const fwd = horiz ? (rtlH ? 'ArrowLeft' : 'ArrowRight') : 'ArrowDown'
+    const back = horiz ? (rtlH ? 'ArrowRight' : 'ArrowLeft') : 'ArrowUp'
+    if (e.key === fwd) { e.preventDefault(); move(1) }
+    else if (e.key === back) { e.preventDefault(); move(-1) }
+    else if (e.key === 'Home') { e.preventDefault(); goto(enabledIdx[0] ?? 0) }
+    else if (e.key === 'End') { e.preventDefault(); goto(enabledIdx.at(-1) ?? 0) }
+    else if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); pick(cursor) }
+  }
+
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
+  const groupRole = () => (mode() === 'single' ? 'radiogroup' : 'group')
+
+  return {
+    /** Roving-focus target index (follows the selection in single mode). */
+    get activeIndex() { return cursor },
+    /** Selected values as an array (single mode -> 0 or 1 entry). */
+    get selectedValues() { return selected },
+    isSelected,
+    isActive: (i: number) => i === cursor,
+    pick,
+    move,
+    onKeydown,
+    /** Spread onto the group container element. */
+    rootProps: () => ({
+      role: groupRole(),
+      id: config.id?.(),
+      'aria-orientation': isVert() ? ('vertical' as const) : ('horizontal' as const),
+      ...editorAria(ariaState()),
+      onkeydown: onKeydown,
+    }),
+    /** Spread onto the button element at `index`. */
+    buttonProps: (index: number) => {
+      const it = items()[index]
+      const on = it ? isSelected(it.value) : false
+      const single = mode() === 'single'
+      return {
+        type: 'button' as const,
+        role: single ? ('radio' as const) : undefined,
+        'data-idx': index,
+        'aria-checked': single ? on : undefined,
+        'aria-pressed': mode() === 'multiple' ? on : undefined,
+        'data-selected': on ? '' : undefined,
+        disabled: disabled() || it?.disabled || undefined,
+        // Roving tabindex: only the cursor (selection in single mode) is tabbable.
+        tabindex: mode() === 'none' ? 0 : index === cursor ? 0 : -1,
+        onclick: () => pick(index),
+      }
+    },
+  }
+}
+
+export type ButtonGroup = ReturnType<typeof createButtonGroup>

package/src/createCalendar.svelte.ts

@@ -48,6 +48,7 @@ import {
   type SelectionState,
 } from './datetime/date-selection'
 import { isDisabledDay, isImportant, type RestrictOptions } from './datetime/date-restrict'
+import { matchesRecurrence, type RecurrenceRule } from './recurrence'
 
 export type DisplayMode = 'month' | 'year' | 'decade'
 export type CalendarNameFormat = 'narrow' | 'short' | 'long'
@@ -82,6 +83,8 @@ export type CalendarDayState = {
   outside: boolean
   focused: boolean
   preview: boolean
+  /** Matches one of the `recurrence` rules (repeat pattern). */
+  recurring: boolean
 }
 
 /** Reactive inputs are passed as getters so the core tracks live prop changes;
@@ -105,6 +108,8 @@ export type CalendarConfig = {
   dayNameFormat?: () => CalendarNameFormat
   monthNameFormat?: () => CalendarNameFormat
   dateTooltip?: () => ((date: Date) => string | null | undefined) | undefined
+  /** Repeat pattern(s) - matching days get `dayState().recurring = true`. */
+  recurrence?: () => RecurrenceRule | ReadonlyArray<RecurrenceRule> | null
 }
 
 const defaultLocale = () => (typeof navigator !== 'undefined' ? navigator.language : 'en-US')
@@ -216,6 +221,7 @@ export function createCalendar(config: CalendarConfig) {
       outside: !isSameMonth(d, panelMonth),
       focused: isSameDay(d, focusDate),
       preview: inPreview(d),
+      recurring: matchesRecurrence(d, config.recurrence?.() ?? null),
     }
   }
 

package/src/createCheckbox.svelte.ts

@@ -15,18 +15,30 @@
  *
  * The styled <SvCheckBox> is just one renderer over this core.
  */
+import { editorAria, type EditorAriaState } from './editor-contract'
+
 export type CheckboxConfig = {
   checked: () => boolean
   indeterminate?: () => boolean
   onChange?: (checked: boolean) => void
   disabled?: () => boolean
+  // Editor contract (ARIA + validation) - folded into boxProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
   ariaLabel?: () => string | undefined
 }
 
 export type CheckboxBoxProps = {
   type: 'button'
   role: 'checkbox'
+  id: string | undefined
   'aria-checked': boolean | 'mixed'
+  'aria-invalid': 'true' | undefined
+  'aria-required': 'true' | undefined
+  'aria-describedby': string | undefined
   'aria-label': string | undefined
   disabled: boolean
   'data-checked': '' | undefined
@@ -55,6 +67,15 @@ export function createCheckbox(config: CheckboxConfig): Checkbox {
     config.onChange?.(indeterminate() ? true : !checked())
   }
 
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
   return {
     get checked() { return checked() },
     get indeterminate() { return indeterminate() },
@@ -63,11 +84,12 @@ export function createCheckbox(config: CheckboxConfig): Checkbox {
     boxProps: () => ({
       type: 'button',
       role: 'checkbox',
+      id: config.id?.(),
       'aria-checked': indeterminate() ? 'mixed' : checked(),
-      'aria-label': config.ariaLabel?.(),
       disabled: disabled(),
       'data-checked': checked() && !indeterminate() ? '' : undefined,
       'data-indeterminate': indeterminate() ? '' : undefined,
+      ...editorAria(ariaState()),
       onclick: toggle,
     }),
   }

package/src/createColorInput.svelte.ts

@@ -17,6 +17,7 @@
  * The styled <SvColorInput> is just one renderer over this core (it adds the
  * portal + anchored positioning).
  */
+import { editorAria, type EditorAriaState } from './editor-contract'
 
 export const DEFAULT_PALETTE = [
   '#ef4444', '#f97316', '#f59e0b', '#eab308', '#84cc16', '#22c55e', '#10b981', '#14b8a6',
@@ -39,6 +40,12 @@ export type ColorInputConfig = {
   disabled?: () => boolean
   readonly?: () => boolean
   palette?: () => string[]
+  // Editor contract (ARIA + validation) - folded into swatchProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
   ariaLabel?: () => string | undefined
 }
 
@@ -71,6 +78,15 @@ export function createColorInput(config: ColorInputConfig) {
   }
   const isActive = (c: string) => normalizeHex(c) === normalized
 
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
   // Popover control surface (open state + show/close/toggle), no DOM measurement.
   const popover = {
     get open() { return open },
@@ -96,9 +112,13 @@ export function createColorInput(config: ColorInputConfig) {
     isActive,
     /** Spread onto the swatch trigger button. */
     swatchProps: () => ({
+      id: config.id?.(),
       type: 'button' as const,
       'aria-haspopup': 'dialog' as const,
       'aria-expanded': open,
+      // aria-invalid/required/describedby come from the editor contract; the
+      // aria-label default names the swatch by its current color when unset.
+      ...editorAria(ariaState()),
       'aria-label': config.ariaLabel?.() ?? `Color ${normalized}`,
       disabled: !isInteractive,
       onclick: toggle,

package/src/createCombobox.svelte.ts

@@ -20,6 +20,7 @@
  * ```
  */
 import { filterOptions, type ListOption } from './list-option'
+import { editorAria, type EditorAriaState } from './editor-contract'
 
 export type ComboboxValue = string | number | null
 
@@ -30,9 +31,17 @@ export type ComboboxConfig = {
   onChange?: (value: ComboboxValue) => void
   disabled?: () => boolean
   ariaLabel?: () => string | undefined
+  /** Filter the options locally by the query. Set false for server-side search. */
+  localFilter?: () => boolean
   /** DOM focus hooks provided by the renderer; the core itself never touches the DOM. */
   focusInput?: () => void
   blurInput?: () => void
+  // Editor contract (ARIA + validation) - folded into inputProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
 }
 
 let uid = 0
@@ -48,8 +57,9 @@ export function createCombobox(config: ComboboxConfig) {
   let active = $state(0)
   let editing = $state(false)
 
+  const localFilter = () => config.localFilter?.() ?? true
   const selected = $derived(opts().find((o) => o.value === config.value()) ?? null)
-  const filtered = $derived(editing ? filterOptions(opts(), query) : [...opts()])
+  const filtered = $derived(editing && localFilter() ? filterOptions(opts(), query) : [...opts()])
   const shownText = $derived(editing ? query : selected?.label ?? '')
 
   // While not actively editing, keep the shown text in sync with the selection.
@@ -57,6 +67,15 @@ export function createCombobox(config: ComboboxConfig) {
 
   const optionId = (i: number) => `${listId}-opt-${i}`
 
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
   function openPanel() { if (disabled() || open) return; open = true; active = 0 }
   function close(revert = true) {
     open = false; editing = false
@@ -114,11 +133,12 @@ export function createCombobox(config: ComboboxConfig) {
     onKeydown,
     /** Spread onto the editable <input>. */
     inputProps: () => ({
+      id: config.id?.(),
       role: 'combobox' as const,
       'aria-expanded': open,
       'aria-controls': listId,
       'aria-autocomplete': 'list' as const,
-      'aria-label': config.ariaLabel?.(),
+      ...editorAria(ariaState()),
       value: shownText,
       disabled: disabled(),
       oninput: onInput,

package/src/createCountryInput.svelte.ts

@@ -21,6 +21,7 @@
  * ```
  */
 import { COUNTRIES, COUNTRY_BY_CODE, type Country } from './countries'
+import { editorAria, type EditorAriaState } from './editor-contract'
 
 /** Reactive inputs are passed as getters so the core tracks live prop changes. */
 export type CountryInputConfig = {
@@ -28,13 +29,30 @@ export type CountryInputConfig = {
   onChange?: (code: string) => void
   disabled?: () => boolean
   ariaLabel?: () => string | undefined
+  /** Accessible label for the in-panel search field (localizable). */
+  searchLabel?: () => string | undefined
   /** DOM focus hook provided by the renderer; the core never touches the DOM. */
   focusTrigger?: () => void
+  // Editor contract (ARIA + validation) - folded into triggerProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
 }
 
 export function createCountryInput(config: CountryInputConfig) {
   const disabled = () => config.disabled?.() ?? false
 
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
   let open = $state(false)
   let query = $state('')
   let active = $state(0)
@@ -89,10 +107,11 @@ export function createCountryInput(config: CountryInputConfig) {
     onKeydown,
     /** Spread onto the trigger <button>. */
     triggerProps: () => ({
+      id: config.id?.(),
       type: 'button' as const,
       'aria-haspopup': 'listbox' as const,
       'aria-expanded': open,
-      'aria-label': config.ariaLabel?.(),
+      ...editorAria(ariaState()),
       disabled: disabled(),
       onclick: toggle,
     }),
@@ -100,7 +119,7 @@ export function createCountryInput(config: CountryInputConfig) {
     searchProps: () => ({
       type: 'text' as const,
       value: query,
-      'aria-label': 'Search countries',
+      'aria-label': config.searchLabel?.() ?? 'Search countries',
       oninput: onSearchInput,
       onkeydown: onKeydown,
     }),