@svgrid/grid 2.1.22 → 2.2.0

package/src/createForm.svelte.ts

@@ -0,0 +1,333 @@
+/**
+ * createForm - the HEADLESS core behind <SvForm>: values / errors / touched
+ * state, required + rule + custom validation (validate-on-blur-then-live), and a
+ * submit that validates every field first. No markup, no controls - you render
+ * the fields however you like and read/write through the core.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createForm } from '@svgrid/grid'
+ *   const form = createForm({ fields: () => fields, onSubmit: (v) => save(v) })
+ * </script>
+ * <form onsubmit={(e) => { e.preventDefault(); form.submit() }}>
+ *   {#each fields as f}
+ *     <input value={form.value(f.name) ?? ''}
+ *       oninput={(e) => form.setValue(f.name, e.currentTarget.value)}
+ *       onblur={() => form.handleBlur(f.name)} />
+ *     {#if form.error(f.name)}<span>{form.error(f.name)}</span>{/if}
+ *   {/each}
+ * </form>
+ * ```
+ */
+import { flattenFields, type FormField, type FormEntry } from './form-field'
+import { runRules } from './validators'
+
+export type FormConfig = {
+  /** The schema - a mix of flat fields and titled sections. */
+  fields: () => ReadonlyArray<FormEntry>
+  /** Seed values on creation. */
+  initial?: Record<string, any>
+  /** Called with the (visible-field) values on a valid submit. May be async;
+   *  `submitting` stays true until the returned promise settles. */
+  onSubmit?: (values: Record<string, any>) => void | Promise<void>
+  onChange?: (values: Record<string, any>) => void
+}
+
+/** Deep-ish equality for dirty tracking: identity for primitives, structural
+ *  (JSON) for arrays/objects. Good enough for form values. */
+function eq(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    try { return JSON.stringify(a) === JSON.stringify(b) } catch { return false }
+  }
+  return false
+}
+
+/** Resolve a `boolean | (values) => boolean` field flag. */
+function resolveFlag(
+  flag: boolean | ((values: Record<string, any>) => boolean) | undefined,
+  dflt: boolean,
+  values: Record<string, any>,
+): boolean {
+  if (flag == null) return dflt
+  return typeof flag === 'function' ? !!flag(values) : !!flag
+}
+
+export function createForm(config: FormConfig) {
+  let values = $state<Record<string, any>>({ ...(config.initial ?? {}) })
+  let errors = $state<Record<string, string>>({})
+  let touched = $state<Record<string, boolean>>({})
+  let submitting = $state(false)
+  let validating = $state<Record<string, boolean>>({})
+  // Baseline for dirty tracking + reset. Rebased when `reset(next)` is passed.
+  let baseline = { ...(config.initial ?? {}) }
+  // Async-validation bookkeeping: debounce timers + a per-field run sequence so
+  // only the latest response wins (stale responses are dropped).
+  const asyncTimers = new Map<string, ReturnType<typeof setTimeout>>()
+  const asyncSeq = new Map<string, number>()
+
+  // The flat field list (sections flattened) drives all values/validation.
+  const flat = () => flattenFields(config.fields())
+  const fieldOf = (name: string) => flat().find((f) => f.name === name)
+  const isVisible = (name: string) => resolveFlag(fieldOf(name)?.visible, true, values)
+  const isDisabled = (name: string) => resolveFlag(fieldOf(name)?.disabled, false, values)
+
+  function setError(name: string, err: string | null | undefined) {
+    const next = { ...errors }
+    if (err) next[name] = err
+    else delete next[name]
+    errors = next
+  }
+
+  /** The synchronous checks: required, then declarative rules, then a sync
+   *  `validate`. Returns the first error message, or null. `ctx` is the values
+   *  object rules/validate see - the form values, or a single item for array
+   *  rows (so within-row cross-field rules work). */
+  function syncError(field: FormField, v: any, ctx: Record<string, any> = values): string | null {
+    if (field.required && (v == null || v === '' || (Array.isArray(v) && !v.length)))
+      return `${field.label} is required`
+    if (field.rules) { const e = runRules(v, field.rules, ctx); if (e) return e }
+    if (field.validate) { const e = field.validate(v, ctx); if (e) return e }
+    return null
+  }
+
+  function cancelAsync(name: string) {
+    const t = asyncTimers.get(name)
+    if (t) { clearTimeout(t); asyncTimers.delete(name) }
+    // Bump the sequence so any in-flight response is treated as stale.
+    asyncSeq.set(name, (asyncSeq.get(name) ?? 0) + 1)
+    if (validating[name]) validating = { ...validating, [name]: false }
+  }
+
+  /** Run a field's async validator now (guarded against stale responses). */
+  async function runAsync(name: string): Promise<boolean> {
+    const field = fieldOf(name)
+    if (!field?.asyncValidate || !isVisible(name)) return true
+    if (syncError(field, values[name])) return false // sync error already shown
+    const seq = (asyncSeq.get(name) ?? 0) + 1
+    asyncSeq.set(name, seq)
+    validating = { ...validating, [name]: true }
+    try {
+      const err = await field.asyncValidate(values[name], values)
+      if (asyncSeq.get(name) !== seq) return true // superseded - ignore
+      setError(name, err ?? null)
+      return !err
+    } finally {
+      if (asyncSeq.get(name) === seq) validating = { ...validating, [name]: false }
+    }
+  }
+
+  function scheduleAsync(name: string) {
+    const field = fieldOf(name)
+    if (!field?.asyncValidate) return
+    const prev = asyncTimers.get(name)
+    if (prev) clearTimeout(prev)
+    asyncTimers.set(name, setTimeout(() => { asyncTimers.delete(name); runAsync(name) }, field.asyncDebounce ?? 300))
+  }
+
+  function validateField(name: string): boolean {
+    const field = fieldOf(name)
+    if (!field) return true
+    // Hidden fields never block submit; clear any stale error + pending check.
+    if (!isVisible(name)) { setError(name, null); cancelAsync(name); return true }
+    if (field.type === 'array') return validateArray(field)
+    const err = syncError(field, values[name])
+    setError(name, err)
+    if (err) { cancelAsync(name); return false }
+    // Sync passed - kick off the debounced async check if there is one.
+    if (field.asyncValidate) scheduleAsync(name)
+    return true
+  }
+
+  // --- Field arrays (repeatable groups) -----------------------------------
+  const arrayItems = (name: string): Record<string, any>[] =>
+    Array.isArray(values[name]) ? values[name] : []
+  const itemValue = (name: string, i: number, field: string) => arrayItems(name)[i]?.[field]
+  const itemError = (name: string, i: number, field: string) => errors[`${name}.${i}.${field}`]
+
+  function clearNamespacedErrors(name: string) {
+    const prefix = `${name}.`
+    const next = { ...errors }
+    let changed = false
+    for (const k of Object.keys(next)) if (k.startsWith(prefix)) { delete next[k]; changed = true }
+    if (changed) errors = next
+  }
+
+  function setItems(name: string, next: Record<string, any>[]) {
+    values = { ...values, [name]: next }
+    config.onChange?.(values)
+  }
+
+  function addItem(name: string, item?: Record<string, any>) {
+    const seed = item ?? Object.fromEntries((fieldOf(name)?.itemFields ?? []).map((f) => [f.name, undefined]))
+    setItems(name, [...arrayItems(name), seed])
+  }
+  function removeItem(name: string, i: number) {
+    const items = arrayItems(name).slice()
+    items.splice(i, 1)
+    clearNamespacedErrors(name) // item indices shift - drop stale keys
+    setItems(name, items)
+  }
+  function moveItem(name: string, from: number, to: number) {
+    const items = arrayItems(name).slice()
+    if (from < 0 || from >= items.length || to < 0 || to >= items.length) return
+    const [it] = items.splice(from, 1)
+    items.splice(to, 0, it as Record<string, any>)
+    clearNamespacedErrors(name)
+    setItems(name, items)
+  }
+  function setItemValue(name: string, i: number, field: string, v: any) {
+    setItems(name, arrayItems(name).map((it, ix) => (ix === i ? { ...it, [field]: v } : it)))
+    if (touched[`${name}.${i}.${field}`]) validateItemField(name, i, field)
+  }
+  function handleItemBlur(name: string, i: number, field: string) {
+    touched = { ...touched, [`${name}.${i}.${field}`]: true }
+    validateItemField(name, i, field)
+  }
+  function validateItemField(name: string, i: number, fieldName: string): boolean {
+    const itemField = fieldOf(name)?.itemFields?.find((f) => f.name === fieldName)
+    if (!itemField) return true
+    const item = arrayItems(name)[i] ?? {}
+    const err = syncError(itemField, item[fieldName], item)
+    setError(`${name}.${i}.${fieldName}`, err)
+    return !err
+  }
+  function validateArray(field: FormField): boolean {
+    const name = field.name
+    const items = arrayItems(name)
+    let arrErr: string | null = null
+    if (field.required && items.length === 0) arrErr = `${field.label} is required`
+    else if (field.minItems != null && items.length < field.minItems) arrErr = `Add at least ${field.minItems} item(s)`
+    else if (field.maxItems != null && items.length > field.maxItems) arrErr = `At most ${field.maxItems} item(s)`
+    setError(name, arrErr)
+    let ok = !arrErr
+    clearNamespacedErrors(name) // rebuild fresh per-item errors
+    for (let i = 0; i < items.length; i++)
+      for (const itf of field.itemFields ?? [])
+        if (!validateItemField(name, i, itf.name)) ok = false
+    return ok
+  }
+
+  function setValue(name: string, v: any) {
+    values = { ...values, [name]: v }
+    config.onChange?.(values)
+    // Re-validate live once the field has been blurred at least once.
+    if (touched[name]) validateField(name)
+  }
+
+  function handleBlur(name: string) {
+    touched = { ...touched, [name]: true }
+    validateField(name)
+  }
+
+  async function submit(): Promise<boolean> {
+    let ok = true
+    const t: Record<string, boolean> = { ...touched }
+    for (const f of flat()) {
+      if (!isVisible(f.name)) continue
+      t[f.name] = true
+      if (!validateField(f.name)) ok = false
+    }
+    touched = t
+    if (!ok) return false
+    // Await async validators (run now, skipping their debounce). Any failure blocks.
+    const asyncFields = flat().filter((f) => f.asyncValidate && isVisible(f.name))
+    if (asyncFields.length) {
+      for (const f of asyncFields) { const timer = asyncTimers.get(f.name); if (timer) { clearTimeout(timer); asyncTimers.delete(f.name) } }
+      const results = await Promise.all(asyncFields.map((f) => runAsync(f.name)))
+      if (results.some((r) => !r)) return false
+    }
+    // Exclude hidden fields from the submitted payload; keep any non-field keys.
+    const payload = { ...values }
+    for (const f of flat()) if (!isVisible(f.name)) delete payload[f.name]
+    submitting = true
+    try {
+      await config.onSubmit?.(payload)
+    } finally {
+      submitting = false
+    }
+    return true
+  }
+
+  /** Validate a subset of fields by name (sync + their async validators). Used
+   *  to gate a wizard step before advancing. Returns true when all pass. */
+  async function validateFields(names: string[]): Promise<boolean> {
+    let ok = true
+    const t = { ...touched }
+    for (const name of names) {
+      if (!isVisible(name)) continue
+      t[name] = true
+      if (!validateField(name)) ok = false
+    }
+    touched = t
+    if (!ok) return false
+    const asyncNames = names.filter((n) => fieldOf(n)?.asyncValidate && isVisible(n))
+    if (asyncNames.length) {
+      for (const n of asyncNames) { const timer = asyncTimers.get(n); if (timer) { clearTimeout(timer); asyncTimers.delete(n) } }
+      const results = await Promise.all(asyncNames.map((n) => runAsync(n)))
+      if (results.some((r) => !r)) return false
+    }
+    return true
+  }
+
+  /** Restore values to the baseline (or a new one), clearing errors + touched. */
+  function reset(next?: Record<string, any>) {
+    if (next) baseline = { ...next }
+    values = { ...baseline }
+    errors = {}
+    touched = {}
+    config.onChange?.(values)
+  }
+
+  /** Inject errors (e.g. server-side validation after submit) and mark those
+   *  fields touched so the messages show. Empty message clears a field's error. */
+  function setErrors(map: Record<string, string>) {
+    const nextErr = { ...errors }
+    const nextTouched = { ...touched }
+    for (const [k, msg] of Object.entries(map)) {
+      if (msg) { nextErr[k] = msg; nextTouched[k] = true }
+      else delete nextErr[k]
+    }
+    errors = nextErr
+    touched = nextTouched
+  }
+
+  const isFieldDirty = (name: string) => !eq(values[name], baseline[name])
+
+  return {
+    get values() { return values },
+    get submitting() { return submitting },
+    get isDirty() {
+      const keys = new Set([...Object.keys(values), ...Object.keys(baseline)])
+      for (const k of keys) if (!eq(values[k], baseline[k])) return true
+      return false
+    },
+    value: (name: string) => values[name],
+    error: (name: string): string | undefined => errors[name],
+    isTouched: (name: string) => !!touched[name],
+    hasError: (name: string) => !!errors[name],
+    isValidating: (name: string) => !!validating[name],
+    isFieldDirty,
+    isVisible,
+    isDisabled,
+    entries: () => config.fields(),
+    // Field arrays
+    arrayItems,
+    itemValue,
+    itemError,
+    addItem,
+    removeItem,
+    moveItem,
+    setItemValue,
+    handleItemBlur,
+    setValue,
+    handleBlur,
+    validateField,
+    validateFields,
+    submit,
+    reset,
+    setErrors,
+  }
+}
+
+export type Form = ReturnType<typeof createForm>

package/src/createGrid.svelte.ts

@@ -1,42 +1,42 @@
-import { createSvGridCore } from './core'
-import type {
-  RowData,
-  SvGrid,
-  SvGridOptions,
-  TableFeatures,
-} from './core'
-
-export type SvelteGrid<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TSelected = {},
-> = SvGrid<TData> & {
-  readonly state: Readonly<TSelected>
-}
-
-export function createSvGrid<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TSelected = {},
->(
-  gridOptions: SvGridOptions<TFeatures, TData>,
-  selector: (state: Record<string, any>) => TSelected = () => ({}) as TSelected,
-): SvelteGrid<TFeatures, TData, TSelected> {
-  const grid = createSvGridCore(gridOptions) as SvelteGrid<TFeatures, TData, TSelected>
-  let selected = $state(selector(grid.store.state))
-  grid.store.subscribe(() => {
-    selected = selector(grid.store.state)
-  })
-
-  Object.defineProperty(grid, 'state', {
-    get() {
-      return selected
-    },
-    configurable: true,
-    enumerable: true,
-  })
-
-  return grid
-}
-
-export const createGrid = createSvGrid
+import { createSvGridCore } from './core'
+import type {
+  RowData,
+  SvGrid,
+  SvGridOptions,
+  TableFeatures,
+} from './core'
+
+export type SvelteGrid<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected = {},
+> = SvGrid<TData> & {
+  readonly state: Readonly<TSelected>
+}
+
+export function createSvGrid<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected = {},
+>(
+  gridOptions: SvGridOptions<TFeatures, TData>,
+  selector: (state: Record<string, any>) => TSelected = () => ({}) as TSelected,
+): SvelteGrid<TFeatures, TData, TSelected> {
+  const grid = createSvGridCore(gridOptions) as SvelteGrid<TFeatures, TData, TSelected>
+  let selected = $state(selector(grid.store.state))
+  grid.store.subscribe(() => {
+    selected = selector(grid.store.state)
+  })
+
+  Object.defineProperty(grid, 'state', {
+    get() {
+      return selected
+    },
+    configurable: true,
+    enumerable: true,
+  })
+
+  return grid
+}
+
+export const createGrid = createSvGrid

package/src/createGrid.test.ts

@@ -1,10 +1,10 @@
-import { describe, expect, it } from 'vitest'
-import { createGridState } from './index'
-
-describe('createGrid', () => {
-  it('createGridState updates controlled values', () => {
-    const [sorting, setSorting] = createGridState([{ id: 'age', desc: false }])
-    setSorting((prev) => prev.map((entry) => ({ ...entry, desc: true })))
-    expect(sorting()[0]?.desc).toBe(true)
-  })
-})
+import { describe, expect, it } from 'vitest'
+import { createGridState } from './index'
+
+describe('createGrid', () => {
+  it('createGridState updates controlled values', () => {
+    const [sorting, setSorting] = createGridState([{ id: 'age', desc: false }])
+    setSorting((prev) => prev.map((entry) => ({ ...entry, desc: true })))
+    expect(sorting()[0]?.desc).toBe(true)
+  })
+})

package/src/createGridState.svelte.ts

@@ -1,17 +1,17 @@
-import type { Updater } from './core'
-
-export function createGridState<TState>(
-  initialValue: TState,
-): [() => TState, (updater: Updater<TState>) => void] {
-  let value = $state(initialValue)
-
-  return [
-    () => value,
-    (updater: Updater<TState>) => {
-      if (updater instanceof Function) value = updater(value)
-      else value = updater
-    },
-  ]
-}
-
-export const createSvGridState = createGridState
+import type { Updater } from './core'
+
+export function createGridState<TState>(
+  initialValue: TState,
+): [() => TState, (updater: Updater<TState>) => void] {
+  let value = $state(initialValue)
+
+  return [
+    () => value,
+    (updater: Updater<TState>) => {
+      if (updater instanceof Function) value = updater(value)
+      else value = updater
+    },
+  ]
+}
+
+export const createSvGridState = createGridState

package/src/createMenu.svelte.ts

@@ -0,0 +1,202 @@
+/**
+ * createMenu - the HEADLESS core behind <SvMenuList> / <SvMenu>, in the same
+ * spirit as `createListbox`: a runes-based state machine for ONE menu level -
+ * roving focus over enabled items, submenu open/collapse, and the full WAI-ARIA
+ * menu keyboard contract (arrows, Home/End, Enter/Space, Escape, Tab, and
+ * rtl-aware ArrowLeft/Right) - with **prop-getters** you spread onto your own
+ * markup. No styles, no DOM assumptions.
+ *
+ * A menu tree is recursive, so you create one core per nesting level (exactly
+ * what the recursive <SvMenuList> does). The styled component is just one
+ * renderer over this core.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMenu, type MenuItem } from '@svgrid/grid'
+ *   let listEl = $state<HTMLElement | null>(null)
+ *   const menu = createMenu({
+ *     items: () => items,
+ *     onSelect: (it) => run(it),
+ *     onClose: () => close(),
+ *     focusItem: (i) => queueMicrotask(() => listEl?.querySelector(`[data-mi="${i}"]`)?.focus()),
+ *   })
+ * </script>
+ * <div bind:this={listEl} {...menu.listProps()}>
+ *   {#each items as item, i}
+ *     <button {...menu.itemProps(i)}>{item.label}</button>
+ *   {/each}
+ * </div>
+ * ```
+ */
+import type { MenuItem } from './menu-item'
+import type { EditorDir } from './editor-contract'
+import { enabledIndices, wrapMove } from './list-nav'
+
+/** Reactive inputs are getters so the core tracks live prop changes (the same
+ *  controlled pattern as `createListbox`). */
+export type MenuConfig = {
+  items: () => ReadonlyArray<MenuItem>
+  /** Report the chosen leaf item (a non-parent menuitem). */
+  onSelect: (item: MenuItem) => void
+  /** Close the WHOLE menu tree - a leaf was chosen, or Escape / Tab / dismissal. */
+  onClose: () => void
+  /** This level is a submenu: enables ArrowLeft (or ArrowRight under rtl) to
+   *  collapse back into the opener. The root level has nowhere to collapse. */
+  submenu?: () => boolean
+  /** Collapse just THIS submenu level and refocus the item that opened it. */
+  onCollapse?: () => void
+  /** Text direction; under `rtl` the open/collapse arrow keys swap. */
+  dir?: () => EditorDir | undefined
+  /** DOM focus hook, invoked ONLY on keyboard navigation (never on hover) so the
+   *  core stays DOM-free. Receives the item index that should take focus. */
+  focusItem?: (index: number) => void
+}
+
+export type MenuItemProps = {
+  role: 'menuitem'
+  'data-mi': number
+  tabindex: 0 | -1
+  'aria-haspopup': 'menu' | undefined
+  'aria-expanded': boolean | undefined
+  'aria-disabled': true | undefined
+  disabled: boolean | undefined
+  onkeydown: (event: KeyboardEvent) => void
+  onpointerenter: () => void
+  onclick: () => void
+}
+
+let uid = 0
+
+export function createMenu(config: MenuConfig) {
+  const items = () => config.items()
+  const submenu = () => config.submenu?.() ?? false
+  const rtl = () => (config.dir?.() ?? 'ltr') === 'rtl'
+
+  // -1 = nothing focused yet (the first enabled item is the tab stop).
+  let active = $state(-1)
+  let openSub = $state(-1)
+
+  // Real (non-separator, non-disabled) item indices, for roving focus.
+  const focusables = $derived(
+    enabledIndices(items().length, (i) => {
+      const it = items()[i]
+      return !it || it.separator === true || it.disabled === true
+    }),
+  )
+
+  /** Move focus to item `i` (keyboard): highlight it, close any open submenu at
+   *  this level, and drive real DOM focus through the host's hook. */
+  function focus(i: number) {
+    active = i
+    openSub = -1
+    config.focusItem?.(i)
+  }
+  function move(delta: number) {
+    const next = wrapMove(focusables, active, delta)
+    if (next >= 0) focus(next)
+  }
+  function first() {
+    const f = focusables[0]
+    if (f != null) focus(f)
+  }
+  function last() {
+    const l = focusables.at(-1)
+    if (l != null) focus(l)
+  }
+
+  /** Hover highlight: sets active WITHOUT stealing DOM focus, and opens a parent
+   *  item's submenu (mirrors the pointerenter behaviour). */
+  function hover(i: number) {
+    const it = items()[i]
+    if (!it || it.disabled || it.separator) return
+    active = i
+    openSub = it.children?.length ? i : -1
+  }
+
+  function choose(item: MenuItem) {
+    if (item.disabled || item.separator) return
+    if (item.children?.length) {
+      openSub = items().indexOf(item)
+      return
+    }
+    item.onSelect?.()
+    config.onSelect(item)
+    config.onClose()
+  }
+
+  function onItemKeydown(e: KeyboardEvent, i: number) {
+    const item = items()[i]
+    // Open this item's submenu (ArrowRight, or ArrowLeft under rtl).
+    const openThis = () => {
+      if (item?.children?.length) {
+        e.preventDefault()
+        openSub = i
+      }
+    }
+    // Collapse just THIS list back into its parent (opposite key under rtl).
+    const collapseThis = () => {
+      if (submenu()) {
+        e.preventDefault()
+        config.onCollapse?.()
+      }
+    }
+    switch (e.key) {
+      case 'ArrowDown': e.preventDefault(); move(1); break
+      case 'ArrowUp': e.preventDefault(); move(-1); break
+      case 'Home': e.preventDefault(); first(); break
+      case 'End': e.preventDefault(); last(); break
+      case 'ArrowRight': (rtl() ? collapseThis : openThis)(); break
+      case 'ArrowLeft': (rtl() ? openThis : collapseThis)(); break
+      case 'Enter':
+      case ' ': e.preventDefault(); if (item) choose(item); break
+      case 'Escape': e.preventDefault(); config.onClose(); break
+      // Tab leaves the menu entirely (WAI-ARIA menu-button pattern): close the
+      // whole tree rather than trapping focus inside a portalled panel.
+      case 'Tab': config.onClose(); break
+    }
+  }
+
+  function itemTabIndex(i: number): 0 | -1 {
+    return active === i || (active === -1 && i === focusables[0]) ? 0 : -1
+  }
+
+  return {
+    get active() { return active },
+    get openSub() { return openSub },
+    /** Enabled (focusable) item indices. */
+    get focusables() { return focusables },
+    isActive: (i: number) => i === active,
+    isSubOpen: (i: number) => i === openSub,
+    itemTabIndex,
+    move,
+    first,
+    last,
+    /** Highlight + DOM-focus item `i` (e.g. to refocus a submenu's opener). */
+    focus,
+    hover,
+    choose,
+    onItemKeydown,
+    /** Spread onto the menu container element. */
+    listProps: () => ({ role: 'menu' as const }),
+    /** Spread onto the menuitem element at `i`. */
+    itemProps: (i: number): MenuItemProps => {
+      const it = items()[i]
+      const hasKids = !!it?.children?.length
+      return {
+        role: 'menuitem',
+        'data-mi': i,
+        tabindex: itemTabIndex(i),
+        'aria-haspopup': hasKids ? 'menu' : undefined,
+        'aria-expanded': hasKids ? openSub === i : undefined,
+        'aria-disabled': it?.disabled ? true : undefined,
+        disabled: it?.disabled,
+        onkeydown: (e: KeyboardEvent) => onItemKeydown(e, i),
+        onpointerenter: () => hover(i),
+        onclick: () => { if (it) choose(it) },
+      }
+    },
+  }
+}
+
+export type Menu = ReturnType<typeof createMenu>
+export type { MenuItem }