@svgrid/grid 1.2.23 → 1.2.25

package/src/createTree.svelte.ts

@@ -0,0 +1,216 @@
+/**
+ * createTree - the HEADLESS core behind <SvTree>, in the same spirit as
+ * `createSvGrid` for the grid: a runes-based state machine (expand/collapse,
+ * single-select highlight, cascading tri-state checkboxes, full keyboard) with
+ * **prop-getters** you spread onto YOUR OWN markup. The visible tree is
+ * flattened into `rows` so roving-focus keyboard nav stays a flat index walk.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createTree } from '@svgrid/grid'
+ *   let selected = $state<string | null>(null)
+ *   const tree = createTree({ nodes: () => nodes, selected: () => selected, onSelect: (id) => (selected = id) })
+ * </script>
+ * <div {...tree.treeProps()}>
+ *   {#each tree.rows as row (row.node.id)}
+ *     <div {...tree.itemProps(row)}>{row.node.label}</div>
+ *   {/each}
+ * </div>
+ * ```
+ *
+ * The styled <SvTree> is just one renderer over this core. The cascade math
+ * (`treeDescendantIds`, `treeCheckState`) is exported as pure functions.
+ */
+export type TreeNode = {
+  id: string
+  label: string
+  children?: TreeNode[]
+  disabled?: boolean
+}
+
+export type CheckState = 'checked' | 'indeterminate' | 'unchecked'
+
+/** A single visible (flattened) tree row. */
+export type TreeRow = {
+  node: TreeNode
+  depth: number
+  hasChildren: boolean
+  open: boolean
+  parentId: string | null
+  index: number
+}
+
+/** All descendant ids of `node` (pure, depth-first). */
+export function treeDescendantIds(node: TreeNode): string[] {
+  const ids: string[] = []
+  const walk = (n: TreeNode) => { for (const c of n.children ?? []) { ids.push(c.id); walk(c) } }
+  walk(node)
+  return ids
+}
+
+/** Tri-state check status of `node` given the set of checked ids (pure). */
+export function treeCheckState(node: TreeNode, checked: ReadonlySet<string>): CheckState {
+  if (!node.children?.length) return checked.has(node.id) ? 'checked' : 'unchecked'
+  const desc = treeDescendantIds(node)
+  const on = desc.filter((id) => checked.has(id)).length
+  if (on === 0 && !checked.has(node.id)) return 'unchecked'
+  if (on === desc.length) return 'checked'
+  return 'indeterminate'
+}
+
+function findNode(list: ReadonlyArray<TreeNode>, id: string): TreeNode | null {
+  for (const n of list) {
+    if (n.id === id) return n
+    if (n.children) { const f = findNode(n.children, id); if (f) return f }
+  }
+  return null
+}
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type TreeConfig = {
+  nodes: () => ReadonlyArray<TreeNode>
+  selected?: () => string | null
+  onSelect?: (id: string) => void
+  /** Seed the internally-managed expanded set (read once). */
+  expandedIds?: () => string[] | undefined
+  onToggle?: (id: string, expanded: boolean) => void
+  checkable?: () => boolean
+  checked?: () => string[]
+  onCheck?: (ids: string[]) => void
+  ariaLabel?: () => string | undefined
+}
+
+export function createTree(config: TreeConfig) {
+  const nodes = () => config.nodes()
+  const checkable = () => config.checkable?.() ?? false
+  const selected = () => config.selected?.() ?? null
+
+  // Internal expanded set, seeded from the prop once (then self-managed).
+  let expanded = $state<Set<string>>(new Set())
+  let seeded = false
+  $effect(() => {
+    if (!seeded) { seeded = true; const ids = config.expandedIds?.(); if (ids) expanded = new Set(ids) }
+  })
+
+  const rows = $derived.by<TreeRow[]>(() => {
+    const out: TreeRow[] = []
+    const walk = (list: ReadonlyArray<TreeNode>, depth: number, parentId: string | null) => {
+      for (const node of list) {
+        const hasChildren = !!node.children?.length
+        const open = expanded.has(node.id)
+        out.push({ node, depth, hasChildren, open, parentId, index: out.length })
+        if (hasChildren && open) walk(node.children!, depth + 1, node.id)
+      }
+    }
+    walk(nodes(), 0, null)
+    return out
+  })
+
+  let active = $state(0)
+  $effect(() => { if (active >= rows.length) active = Math.max(0, rows.length - 1) })
+
+  const checkedSet = $derived(new Set(config.checked?.() ?? []))
+
+  // Roving focus target; `focusTick` bumps only on keyboard moves.
+  let focusTick = $state(0)
+  function setActive(i: number, focus = false) { active = i; if (focus) focusTick++ }
+
+  const checkStateOf = (node: TreeNode): CheckState => treeCheckState(node, checkedSet)
+  const isExpanded = (id: string) => expanded.has(id)
+  const isSelected = (id: string) => id === selected()
+
+  function toggleExpand(node: TreeNode) {
+    if (!node.children?.length) return
+    const next = new Set(expanded)
+    const willOpen = !next.has(node.id)
+    willOpen ? next.add(node.id) : next.delete(node.id)
+    expanded = next
+    config.onToggle?.(node.id, willOpen)
+  }
+  const toggle = (id: string) => { const n = findNode(nodes(), id); if (n) toggleExpand(n) }
+
+  function select(node: TreeNode) {
+    if (node.disabled) return
+    config.onSelect?.(node.id)
+  }
+  const selectId = (id: string) => { const n = findNode(nodes(), id); if (n) select(n) }
+
+  function toggleCheck(node: TreeNode) {
+    if (node.disabled) return
+    const next = new Set(checkedSet)
+    const ids = [node.id, ...treeDescendantIds(node)]
+    const currentlyOn = checkStateOf(node) === 'checked'
+    for (const id of ids) currentlyOn ? next.delete(id) : next.add(id)
+    config.onCheck?.([...next])
+  }
+
+  function onKeydown(e: KeyboardEvent) {
+    const item = rows[active]
+    if (!item) return
+    switch (e.key) {
+      case 'ArrowDown': e.preventDefault(); setActive(Math.min(active + 1, rows.length - 1), true); break
+      case 'ArrowUp': e.preventDefault(); setActive(Math.max(active - 1, 0), true); break
+      case 'ArrowRight':
+        e.preventDefault()
+        if (item.hasChildren && !item.open) toggleExpand(item.node)
+        else if (item.hasChildren && item.open) setActive(Math.min(active + 1, rows.length - 1), true)
+        break
+      case 'ArrowLeft':
+        e.preventDefault()
+        if (item.hasChildren && item.open) toggleExpand(item.node)
+        else if (item.parentId) { const pi = rows.findIndex((r) => r.node.id === item.parentId); if (pi >= 0) setActive(pi, true) }
+        break
+      case 'Enter': e.preventDefault(); select(item.node); break
+      case ' ': e.preventDefault(); checkable() ? toggleCheck(item.node) : select(item.node); break
+      case 'Home': e.preventDefault(); setActive(0, true); break
+      case 'End': e.preventDefault(); setActive(rows.length - 1, true); break
+    }
+  }
+
+  return {
+    /** Internally-managed set of expanded node ids. */
+    get expanded() { return expanded },
+    /** Selected node id (single-select highlight). */
+    get selected() { return selected() },
+    /** Flattened list of visible rows. */
+    get rows() { return rows },
+    /** Roving-focus row index. */
+    get activeIndex() { return active },
+    /** Monotonic counter; changes only on keyboard navigation. */
+    get focusTick() { return focusTick },
+    isExpanded,
+    isSelected,
+    checkStateOf,
+    toggle,
+    toggleExpand,
+    select: selectId,
+    toggleCheck,
+    setActive,
+    onKeydown,
+    /** Spread onto the tree container element. */
+    treeProps: () => ({
+      role: 'tree' as const,
+      'aria-label': config.ariaLabel?.(),
+      'aria-multiselectable': checkable(),
+    }),
+    /** Spread onto the treeitem element for a flattened `row`. */
+    itemProps: (row: TreeRow) => {
+      const cs = checkable() ? checkStateOf(row.node) : 'unchecked'
+      const ariaChecked: 'true' | 'mixed' | 'false' | undefined =
+        checkable() ? (cs === 'checked' ? 'true' : cs === 'indeterminate' ? 'mixed' : 'false') : undefined
+      return {
+        role: 'treeitem' as const,
+        'aria-level': row.depth + 1,
+        'aria-selected': row.node.id === selected(),
+        'aria-expanded': row.hasChildren ? row.open : undefined,
+        'aria-checked': ariaChecked,
+        'data-row': row.index,
+        tabindex: row.index === active ? 0 : -1,
+        onclick: () => { setActive(row.index); select(row.node) },
+        onkeydown: onKeydown,
+      }
+    },
+  }
+}
+
+export type Tree = ReturnType<typeof createTree>

package/src/editor-contract.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest'
+import { editorAria, editorErrorId } from './editor-contract'
+
+describe('editor-contract', () => {
+  it('emits ARIA only for the flags that are set (undefined => attribute omitted)', () => {
+    expect(editorAria({})).toEqual({
+      'aria-invalid': undefined,
+      'aria-required': undefined,
+      'aria-describedby': undefined,
+      'aria-label': undefined,
+    })
+  })
+
+  it('wires invalid + required + describedby + label', () => {
+    const a = editorAria({ id: 'qty', invalid: true, required: true, error: 'Too big', ariaLabel: 'Quantity' })
+    expect(a['aria-invalid']).toBe('true')
+    expect(a['aria-required']).toBe('true')
+    expect(a['aria-describedby']).toBe('qty__error')
+    expect(a['aria-label']).toBe('Quantity')
+  })
+
+  it('describedby is only set when there is an error AND an id', () => {
+    expect(editorAria({ id: 'qty', error: '' })['aria-describedby']).toBeUndefined()
+    expect(editorAria({ error: 'x' })['aria-describedby']).toBeUndefined() // no id
+    expect(editorAria({ id: 'qty', error: 'x' })['aria-describedby']).toBe('qty__error')
+  })
+
+  it('editorErrorId', () => {
+    expect(editorErrorId('a')).toBe('a__error')
+    expect(editorErrorId(undefined)).toBeUndefined()
+  })
+})

package/src/editor-contract.ts

@@ -0,0 +1,60 @@
+/**
+ * The shared "editor contract" for the SvGrid UI kit.
+ *
+ * Every value-bearing editor (inputs, selects, pickers) accepts this common set
+ * of props so forms, validation and accessibility behave IDENTICALLY across the
+ * kit - the same spirit as the grid's headless core, applied to the editors.
+ * Components spread their own `value` / options / behavior on top of this base.
+ *
+ * Framework-free (no Svelte, no DOM) so it can be unit-tested and reused.
+ */
+
+export type EditorSize = 'sm' | 'md' | 'lg'
+
+/** Props shared by every value-bearing editor in the kit. */
+export type SvEditorProps = {
+  /** Disable interaction + form submission. */
+  disabled?: boolean
+  /** Read-only: the value is shown but not editable. */
+  readonly?: boolean
+  /** Required for validation (adds `aria-required` + participates in validity). */
+  required?: boolean
+  /** Marks the control invalid (`aria-invalid` + error styling). */
+  invalid?: boolean
+  /** Error message; when set it is announced via `aria-describedby` and shown. */
+  error?: string
+  /** Control size / density. */
+  size?: EditorSize
+  /** Form field name; the editor emits a hidden input carrying its value. */
+  name?: string
+  /** Root/control element id (the error-text id derives from it). */
+  id?: string
+  /** Accessible name when there is no visible `<label>`. */
+  ariaLabel?: string
+}
+
+/** Stable DOM id for an editor's error text, for `aria-describedby` wiring. */
+export const editorErrorId = (id?: string): string | undefined => (id ? `${id}__error` : undefined)
+
+/** A subset of {@link SvEditorProps} that drives ARIA on the focusable control. */
+export type EditorAriaState = Pick<SvEditorProps, 'id' | 'invalid' | 'required' | 'error' | 'ariaLabel'>
+
+/**
+ * ARIA attributes for the focusable control of an editor, derived from its state.
+ * Spread onto the input/button/combobox:
+ * `<input {...editorAria({ id, invalid, required, error, ariaLabel })} />`
+ * Undefined values are omitted by Svelte, so unset props add no attributes.
+ */
+export function editorAria(state: EditorAriaState): {
+  'aria-invalid': 'true' | undefined
+  'aria-required': 'true' | undefined
+  'aria-describedby': string | undefined
+  'aria-label': string | undefined
+} {
+  return {
+    'aria-invalid': state.invalid ? 'true' : undefined,
+    'aria-required': state.required ? 'true' : undefined,
+    'aria-describedby': state.error ? editorErrorId(state.id) : undefined,
+    'aria-label': state.ariaLabel,
+  }
+}

package/src/index.ts

@@ -73,6 +73,45 @@ export { default as SvGridDropdown } from './SvGridDropdown.svelte'
 export { default as SvCalendar, type CalendarValue, type CalendarPreset, type CalendarAnimation } from './SvCalendar.svelte'
 export { default as SvTimePicker, type TimeValue } from './SvTimePicker.svelte'
 export { default as SvDateTimePicker, type DateTimeValue } from './SvDateTimePicker.svelte'
+// UI kit - shared editor contract (common props + a11y wiring for every editor)
+export { editorAria, editorErrorId, type SvEditorProps, type EditorSize, type EditorAriaState } from './editor-contract'
+// UI kit - headless cores (state + prop-getters you render yourself, like createSvGrid)
+export {
+  createListbox,
+  toSelectedArray,
+  type Listbox,
+  type ListboxConfig,
+  type ListboxValue,
+  type ListboxRootProps,
+  type OptionProps,
+} from './createListbox.svelte'
+// Selection family cores
+export { createCombobox, type Combobox, type ComboboxConfig, type ComboboxValue } from './createCombobox.svelte'
+export { createDropdownList, type DropdownList, type DropdownListConfig, type DropdownValue } from './createDropdownList.svelte'
+export { createAutocomplete, type Autocomplete, type AutocompleteConfig } from './createAutocomplete.svelte'
+export { createTagsInput, type TagsInput, type TagsInputConfig } from './createTagsInput.svelte'
+export { createCountryInput, type CountryInput, type CountryInputConfig } from './createCountryInput.svelte'
+// Text-input family cores
+export { createNumberInput, type NumberInputConfig, type NumberInputCore } from './createNumberInput.svelte'
+export { createMaskedInput, type MaskedInputConfig, type MaskedInputCore } from './createMaskedInput.svelte'
+export { createPhoneInput, type PhoneInputConfig, type PhoneInputCore } from './createPhoneInput.svelte'
+export { createColorInput, normalizeHex, type ColorInputConfig, type ColorInputCore } from './createColorInput.svelte'
+export { createPasswordInput, passwordStrength, STRENGTH_LABELS, type PasswordInputConfig, type PasswordInputCore } from './createPasswordInput.svelte'
+// Buttons & toggles family cores
+export { createToggle, type Toggle, type ToggleConfig, type ToggleButtonProps } from './createToggle.svelte'
+export { createSwitch, type Switch, type SwitchConfig, type SwitchProps } from './createSwitch.svelte'
+export { createCheckbox, type Checkbox, type CheckboxConfig, type CheckboxBoxProps } from './createCheckbox.svelte'
+export { createRadioGroup, type RadioGroup, type RadioGroupConfig, type RadioProps, type RadioGroupProps } from './createRadioGroup.svelte'
+export { createRating, type Rating, type RatingConfig, type RatingFill, type RatingRootProps, type RatingStarProps } from './createRating.svelte'
+// Date & time family cores
+export { createCalendar, normalizeCalendarValue, type Calendar, type CalendarConfig, type CalendarDayState, type CalendarNavDir, type CalendarNameFormat, type DisplayMode } from './createCalendar.svelte'
+export { createTimePicker, parseTimeValue, type TimePicker, type TimePickerConfig, type TimeSelection, type TimeFormat, type DialTick } from './createTimePicker.svelte'
+export { createDateTimePicker, type DateTimePicker, type DateTimePickerConfig, type DropDownDisplayMode, type DateTimeTab } from './createDateTimePicker.svelte'
+// Layout & range family cores
+export { createTabs, type Tabs, type TabsConfig, type TabsOrientation, type TabsActivation } from './createTabs.svelte'
+export { createTree, treeDescendantIds, treeCheckState, type Tree, type TreeConfig, type TreeRow, type CheckState } from './createTree.svelte'
+export { createSlider, type Slider, type SliderConfig, type SliderValue, type SliderOrientation, type SliderThumb, type SliderPoint } from './createSlider.svelte'
+export { createGauge, type Gauge, type GaugeConfig, type GaugePoint } from './createGauge.svelte'
 // UI kit - Group B (buttons & toggles)
 export { default as SvButton } from './SvButton.svelte'
 export { default as SvRepeatButton } from './SvRepeatButton.svelte'

package/src/ui-inputs.test.ts

@@ -14,6 +14,32 @@ function mnt(Comp: any, props: Record<string, unknown>) {
   return { target, destroy: () => { unmount(app); target.remove() } }
 }
 
+describe('SvNumberInput validation a11y (editor contract)', () => {
+  it('wires aria-invalid + aria-required + aria-describedby -> error text', () => {
+    const { target, destroy } = mnt(SvNumberInput, { value: 5, id: 'qty', invalid: true, required: true, error: 'Too big' })
+    try {
+      const input = target.querySelector<HTMLInputElement>('.sv-num__input')!
+      expect(input.getAttribute('aria-invalid')).toBe('true')
+      expect(input.getAttribute('aria-required')).toBe('true')
+      expect(input.getAttribute('aria-describedby')).toBe('qty__error')
+      const err = target.querySelector('#qty__error')!
+      expect(err.getAttribute('role')).toBe('alert')
+      expect(err.textContent).toBe('Too big')
+      expect(target.querySelector('.sv-num.is-invalid')).toBeTruthy()
+    } finally { destroy() }
+  })
+
+  it('adds no validation attributes when the props are unset', () => {
+    const { target, destroy } = mnt(SvNumberInput, { value: 1 })
+    try {
+      const input = target.querySelector<HTMLInputElement>('.sv-num__input')!
+      expect(input.getAttribute('aria-invalid')).toBeNull()
+      expect(input.getAttribute('aria-describedby')).toBeNull()
+      expect(target.querySelector('.sv-num.is-invalid')).toBeNull()
+    } finally { destroy() }
+  })
+})
+
 describe('SvNumberInput', () => {
   it('clamps to max on commit', () => {
     let got: number | null | undefined

package/src/ui-selection.test.ts

@@ -39,6 +39,19 @@ describe('SvListBox', () => {
       expect(got).toEqual(['a', 'b'])
     } finally { b.destroy() }
   })
+
+  it('posts its value(s) via hidden inputs when `name` is set (multi -> repeated name)', () => {
+    const m = mnt(SvListBox, { options: OPTS, value: ['a', 'c'], multiple: true, name: 'tags' })
+    try {
+      const hidden = Array.from(m.target.querySelectorAll<HTMLInputElement>('input[type="hidden"][name="tags"]'))
+      expect(hidden.map((h) => h.value)).toEqual(['a', 'c'])
+    } finally { m.destroy() }
+    const s = mnt(SvListBox, { options: OPTS, value: 'b', name: 'choice' })
+    try {
+      const hidden = Array.from(s.target.querySelectorAll<HTMLInputElement>('input[type="hidden"][name="choice"]'))
+      expect(hidden.map((h) => h.value)).toEqual(['b'])
+    } finally { s.destroy() }
+  })
 })
 
 describe('SvDropDownList', () => {