@svgrid/grid 1.2.34 → 2.0.1

package/src/createSwitch.svelte.ts

@@ -14,17 +14,29 @@
  *
  * The styled <SvSwitchButton> is just one renderer over this core.
  */
+import { editorAria, type EditorAriaState } from './editor-contract'
+
 export type SwitchConfig = {
   checked: () => boolean
   onChange?: (checked: boolean) => void
   disabled?: () => boolean
+  // Editor contract (ARIA + validation) - folded into switchProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
   ariaLabel?: () => string | undefined
 }
 
 export type SwitchProps = {
   type: 'button'
   role: 'switch'
+  id: string | undefined
   'aria-checked': boolean
+  'aria-invalid': 'true' | undefined
+  'aria-required': 'true' | undefined
+  'aria-describedby': string | undefined
   'aria-label': string | undefined
   disabled: boolean
   'data-checked': '' | undefined
@@ -59,18 +71,29 @@ export function createSwitch(config: SwitchConfig): Switch {
     else if (e.key === 'ArrowLeft') { if (checked()) config.onChange?.(false) }
   }
 
+  // The validation/label ARIA is derived from the editor contract state.
+  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 disabled() { return disabled() },
     toggle,
     onKeydown,
     switchProps: () => ({
-      type: 'button',
-      role: 'switch',
+      type: 'button' as const,
+      role: 'switch' as const,
+      id: config.id?.(),
       'aria-checked': checked(),
-      'aria-label': config.ariaLabel?.(),
       disabled: disabled(),
       'data-checked': checked() ? '' : undefined,
+      ...editorAria(ariaState()),
       onclick: toggle,
       onkeydown: onKeydown,
     }),

package/src/createTabs.svelte.ts

@@ -23,7 +23,9 @@
  * a render concern, so the component watches `focusTick`/`focusId` and calls
  * `.focus()` itself; the core only decides *which* tab should take focus.
  */
-export type TabItem = { id: string; label: string; disabled?: boolean }
+import type { EditorDir } from './editor-contract'
+
+export type TabItem = { id: string; label: string; disabled?: boolean; closable?: boolean }
 
 export type TabsOrientation = 'horizontal' | 'vertical'
 export type TabsActivation = 'automatic' | 'manual'
@@ -33,8 +35,12 @@ export type TabsConfig = {
   tabs: () => ReadonlyArray<TabItem>
   value: () => string | undefined
   onChange?: (id: string) => void
+  /** Fired when a closable tab is closed (Delete key, or the renderer's x). */
+  onClose?: (id: string) => void
   orientation?: () => TabsOrientation
   activation?: () => TabsActivation
+  /** Text direction; under `'rtl'` horizontal Left/Right arrows flip. */
+  dir?: () => EditorDir | undefined
   ariaLabel?: () => string | undefined
 }
 
@@ -64,18 +70,28 @@ export function createTabs(config: TabsConfig) {
     config.onChange?.(tid)
   }
 
+  function close(tid: string) {
+    const t = tabs().find((x) => x.id === tid)
+    if (t?.closable) config.onClose?.(tid)
+  }
+
   function onKeydown(e: KeyboardEvent) {
     const list = enabled
     if (!list.length) return
     const idx = list.findIndex((t) => t.id === active)
-    const fwd = orientation() === 'horizontal' ? 'ArrowRight' : 'ArrowDown'
-    const back = orientation() === 'horizontal' ? 'ArrowLeft' : 'ArrowUp'
+    const horiz = orientation() === 'horizontal'
+    // Under horizontal RTL the Left/Right arrows swap so focus follows the
+    // visual order (Right moves to the previous tab).
+    const rtlH = horiz && config.dir?.() === 'rtl'
+    const fwd = horiz ? (rtlH ? 'ArrowLeft' : 'ArrowRight') : 'ArrowDown'
+    const back = horiz ? (rtlH ? 'ArrowRight' : 'ArrowLeft') : 'ArrowUp'
     let next: string | null = null
     if (e.key === fwd) next = list[(idx + 1) % list.length]?.id ?? null
     else if (e.key === back) next = list[(idx - 1 + list.length) % list.length]?.id ?? null
     else if (e.key === 'Home') next = list[0]?.id ?? null
     else if (e.key === 'End') next = list.at(-1)?.id ?? null
     else if ((e.key === 'Enter' || e.key === ' ') && activation() === 'manual') { e.preventDefault(); select(active); return }
+    else if (e.key === 'Delete') { e.preventDefault(); close(active); return }
     else return
     if (next) {
       e.preventDefault()
@@ -93,6 +109,7 @@ export function createTabs(config: TabsConfig) {
     get focusTick() { return focusTick },
     isActive: (tid: string) => tid === active,
     select,
+    close,
     onKeydown,
     /** Spread onto the tablist container element. */
     tablistProps: () => ({

package/src/createTagsInput.svelte.ts

@@ -19,6 +19,8 @@
  * ```
  */
 
+import { editorAria, type EditorAriaState } from './editor-contract'
+
 /** Reactive inputs are passed as getters so the core tracks live prop changes. */
 export type TagsInputConfig = {
   value: () => string[]
@@ -28,6 +30,16 @@ export type TagsInputConfig = {
   unique?: () => boolean
   max?: () => number
   ariaLabel?: () => string | undefined
+  /** Accessible label for the draft input (localizable). */
+  addLabel?: () => string | undefined
+  /** Accessible label prefix for a chip's remove button (localizable). */
+  removeLabel?: () => string | undefined
+  // Editor contract (ARIA + validation) - folded into rootProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
 }
 
 export function createTagsInput(config: TagsInputConfig) {
@@ -36,6 +48,15 @@ export function createTagsInput(config: TagsInputConfig) {
   const max = () => config.max?.() ?? Infinity
   const tags = () => config.value()
 
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
   let draft = $state('')
 
   function add(raw: string) {
@@ -70,14 +91,14 @@ export function createTagsInput(config: TagsInputConfig) {
     /** Spread onto the container element. */
     rootProps: () => ({
       role: 'group' as const,
-      'aria-label': config.ariaLabel?.(),
+      ...editorAria(ariaState()),
     }),
     /** Spread onto the text <input>. */
     inputProps: () => ({
       type: 'text' as const,
       value: draft,
       disabled: disabled(),
-      'aria-label': config.ariaLabel?.() ?? 'Add tag',
+      'aria-label': config.addLabel?.() ?? config.ariaLabel?.() ?? 'Add tag',
       oninput: onInput,
       onkeydown: onKeydown,
       onblur: onBlur,
@@ -89,7 +110,7 @@ export function createTagsInput(config: TagsInputConfig) {
     /** Spread onto a chip's remove <button> at `index`. */
     removeProps: (index: number) => ({
       type: 'button' as const,
-      'aria-label': `Remove ${tags()[index] ?? ''}`,
+      'aria-label': `${config.removeLabel?.() ?? 'Remove'} ${tags()[index] ?? ''}`.trim(),
       onclick: () => removeAt(index),
     }),
   }

package/src/createToggle.svelte.ts

@@ -16,18 +16,30 @@
  * The styled <SvToggleButton> is just one renderer over this core.
  */
 
+import { editorAria, type EditorAriaState } from './editor-contract'
+
 /** Reactive inputs are passed as getters so the core tracks live prop changes
  *  (the same controlled pattern used across the SvGrid UI kit). */
 export type ToggleConfig = {
   pressed: () => boolean
   onChange?: (pressed: boolean) => void
   disabled?: () => boolean
+  // Editor contract (ARIA + validation) - folded into buttonProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
   ariaLabel?: () => string | undefined
 }
 
 export type ToggleButtonProps = {
   type: 'button'
+  id: string | undefined
   'aria-pressed': boolean
+  'aria-invalid': 'true' | undefined
+  'aria-required': 'true' | undefined
+  'aria-describedby': string | undefined
   'aria-label': string | undefined
   disabled: boolean
   'data-pressed': '' | undefined
@@ -53,16 +65,27 @@ export function createToggle(config: ToggleConfig): Toggle {
     config.onChange?.(!pressed())
   }
 
+  // The validation/label ARIA is derived from the editor contract state.
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
   return {
     get pressed() { return pressed() },
     get disabled() { return disabled() },
     toggle,
     buttonProps: () => ({
-      type: 'button',
+      type: 'button' as const,
+      id: config.id?.(),
       'aria-pressed': pressed(),
-      'aria-label': config.ariaLabel?.(),
       disabled: disabled(),
       'data-pressed': pressed() ? '' : undefined,
+      ...editorAria(ariaState()),
       onclick: toggle,
     }),
   }

package/src/createTree.svelte.ts

@@ -26,6 +26,9 @@ export type TreeNode = {
   label: string
   children?: TreeNode[]
   disabled?: boolean
+  /** Marks a node whose children are loaded on demand (shows an expand arrow
+   *  even with no children yet; the renderer loads them on first expand). */
+  lazy?: boolean
 }
 
 export type CheckState = 'checked' | 'indeterminate' | 'unchecked'
@@ -66,6 +69,64 @@ function findNode(list: ReadonlyArray<TreeNode>, id: string): TreeNode | null {
   return null
 }
 
+/** Where a dragged node lands relative to the drop target. */
+export type TreeDropPosition = 'before' | 'after' | 'inside'
+
+/** True if `id` is inside `node`'s subtree (used to block invalid drops). */
+export function treeContains(node: TreeNode, id: string): boolean {
+  return node.children?.some((c) => c.id === id || treeContains(c, id)) ?? false
+}
+
+/**
+ * Return a NEW node tree with `dragId` moved before/after/inside `targetId`
+ * (pure - the caller sets it back as the controlled `nodes`). No-ops on invalid
+ * moves (self, or into own descendant).
+ */
+export function moveTreeNode(
+  nodes: ReadonlyArray<TreeNode>,
+  dragId: string,
+  targetId: string,
+  position: TreeDropPosition,
+): TreeNode[] {
+  if (dragId === targetId) return [...nodes]
+  const dragged = findNode(nodes, dragId)
+  if (!dragged) return [...nodes]
+  if (dragId === targetId || treeContains(dragged, targetId)) return [...nodes]
+
+  const without = (list: ReadonlyArray<TreeNode>): TreeNode[] => {
+    const out: TreeNode[] = []
+    for (const n of list) {
+      if (n.id === dragId) continue
+      out.push(n.children ? { ...n, children: without(n.children) } : n)
+    }
+    return out
+  }
+  const insert = (list: ReadonlyArray<TreeNode>): TreeNode[] => {
+    const out: TreeNode[] = []
+    for (const n of list) {
+      if (n.id === targetId) {
+        if (position === 'before') { out.push(dragged, n) }
+        else if (position === 'after') { out.push(n, dragged) }
+        else out.push({ ...n, children: [...(n.children ?? []), dragged] })
+      } else if (n.children) {
+        out.push({ ...n, children: insert(n.children) })
+      } else out.push(n)
+    }
+    return out
+  }
+  return insert(without(nodes))
+}
+
+/** Sort siblings (recursively) by a comparator (pure). */
+export function sortTreeNodes(
+  nodes: ReadonlyArray<TreeNode>,
+  compare: (a: TreeNode, b: TreeNode) => number,
+): TreeNode[] {
+  return [...nodes]
+    .sort(compare)
+    .map((n) => (n.children ? { ...n, children: sortTreeNodes(n.children, compare) } : n))
+}
+
 /** Reactive inputs are passed as getters so the core tracks live prop changes. */
 export type TreeConfig = {
   nodes: () => ReadonlyArray<TreeNode>
@@ -78,6 +139,10 @@ export type TreeConfig = {
   checked?: () => string[]
   onCheck?: (ids: string[]) => void
   ariaLabel?: () => string | undefined
+  /** Text direction; under `'rtl'` the Left/Right expand/collapse keys swap. */
+  dir?: () => import('./editor-contract').EditorDir | undefined
+  /** Filter query: show only matching nodes + their ancestors, auto-expanded. */
+  filter?: () => string | undefined
 }
 
 export function createTree(config: TreeConfig) {
@@ -92,14 +157,34 @@ export function createTree(config: TreeConfig) {
     if (!seeded) { seeded = true; const ids = config.expandedIds?.(); if (ids) expanded = new Set(ids) }
   })
 
+  // When filtering, precompute which nodes to show (a match, or an ancestor of a
+  // match) and which to force-open so matches are revealed.
+  const filterInfo = $derived.by(() => {
+    const q = config.filter?.()?.trim().toLowerCase()
+    if (!q) return null
+    const visible = new Set<string>()
+    const forceOpen = new Set<string>()
+    const walk = (node: TreeNode): boolean => {
+      let childMatch = false
+      for (const c of node.children ?? []) childMatch = walk(c) || childMatch
+      const selfMatch = node.label.toLowerCase().includes(q)
+      if (selfMatch || childMatch) { visible.add(node.id); if (childMatch) forceOpen.add(node.id) }
+      return selfMatch || childMatch
+    }
+    for (const n of nodes()) walk(n)
+    return { visible, forceOpen }
+  })
+
   const rows = $derived.by<TreeRow[]>(() => {
     const out: TreeRow[] = []
+    const fi = filterInfo
     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)
+        if (fi && !fi.visible.has(node.id)) continue
+        const hasChildren = !!node.children?.length || !!node.lazy
+        const open = fi ? fi.forceOpen.has(node.id) || expanded.has(node.id) : expanded.has(node.id)
         out.push({ node, depth, hasChildren, open, parentId, index: out.length })
-        if (hasChildren && open) walk(node.children!, depth + 1, node.id)
+        if (open && node.children?.length) walk(node.children, depth + 1, node.id)
       }
     }
     walk(nodes(), 0, null)
@@ -120,7 +205,9 @@ export function createTree(config: TreeConfig) {
   const isSelected = (id: string) => id === selected()
 
   function toggleExpand(node: TreeNode) {
-    if (!node.children?.length) return
+    // Lazy nodes have no children *yet* - they must still be expandable so the
+    // toggle fires onToggle and the host can fetch children on demand.
+    if (!node.children?.length && !node.lazy) return
     const next = new Set(expanded)
     const willOpen = !next.has(node.id)
     willOpen ? next.add(node.id) : next.delete(node.id)
@@ -147,19 +234,22 @@ export function createTree(config: TreeConfig) {
   function onKeydown(e: KeyboardEvent) {
     const item = rows[active]
     if (!item) return
+    // "expand" opens the node or steps into the first child; "collapse" closes it
+    // or jumps to the parent. Under RTL the physical Left/Right keys are swapped.
+    const expand = () => {
+      if (item.hasChildren && !item.open) toggleExpand(item.node)
+      else if (item.hasChildren && item.open) setActive(Math.min(active + 1, rows.length - 1), true)
+    }
+    const collapse = () => {
+      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) }
+    }
+    const rtl = config.dir?.() === 'rtl'
     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 'ArrowRight': e.preventDefault(); (rtl ? collapse : expand)(); break
+      case 'ArrowLeft': e.preventDefault(); (rtl ? expand : collapse)(); 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

package/src/debounce.test.ts

@@ -0,0 +1,50 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { debounce } from './debounce'
+
+beforeEach(() => vi.useFakeTimers())
+afterEach(() => vi.useRealTimers())
+
+describe('debounce', () => {
+  it('runs once after the quiet period with the latest args', () => {
+    const fn = vi.fn()
+    const d = debounce(fn, 200)
+    d('a'); d('b'); d('c')
+    expect(fn).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(199)
+    expect(fn).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(1)
+    expect(fn).toHaveBeenCalledTimes(1)
+    expect(fn).toHaveBeenCalledWith('c')
+  })
+
+  it('resets the timer on each call', () => {
+    const fn = vi.fn()
+    const d = debounce(fn, 200)
+    d('x')
+    vi.advanceTimersByTime(150)
+    d('y') // restarts the 200ms window
+    vi.advanceTimersByTime(150)
+    expect(fn).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(50)
+    expect(fn).toHaveBeenCalledExactlyOnceWith('y')
+  })
+
+  it('cancel() drops the pending call', () => {
+    const fn = vi.fn()
+    const d = debounce(fn, 200)
+    d('a')
+    d.cancel()
+    vi.advanceTimersByTime(500)
+    expect(fn).not.toHaveBeenCalled()
+  })
+
+  it('flush() runs the pending call immediately', () => {
+    const fn = vi.fn()
+    const d = debounce(fn, 200)
+    d('a')
+    d.flush()
+    expect(fn).toHaveBeenCalledExactlyOnceWith('a')
+    vi.advanceTimersByTime(500)
+    expect(fn).toHaveBeenCalledTimes(1) // not called again
+  })
+})

package/src/debounce.ts

@@ -0,0 +1,41 @@
+/**
+ * debounce - coalesce rapid calls into one trailing call after `ms` of quiet.
+ * Used for remote search in the async dropdowns (SvMultiSelect/GridSelect/...),
+ * but general-purpose. Returns the debounced function with `cancel()` (drop the
+ * pending call) and `flush()` (run it now). Framework-free + pure.
+ */
+export type Debounced<A extends unknown[]> = ((...args: A) => void) & {
+  cancel: () => void
+  flush: () => void
+}
+
+export function debounce<A extends unknown[]>(fn: (...args: A) => void, ms: number): Debounced<A> {
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let pending: A | null = null
+
+  const run = () => {
+    timer = null
+    const args = pending
+    pending = null
+    if (args) fn(...args)
+  }
+
+  const debounced = ((...args: A) => {
+    pending = args
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(run, ms)
+  }) as Debounced<A>
+
+  debounced.cancel = () => {
+    if (timer) clearTimeout(timer)
+    timer = null
+    pending = null
+  }
+  debounced.flush = () => {
+    if (timer) {
+      clearTimeout(timer)
+      run()
+    }
+  }
+  return debounced
+}

package/src/duration.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { parseDuration, formatDuration } from './duration'
+
+describe('parseDuration', () => {
+  it('parses h:mm', () => {
+    expect(parseDuration('1:30')).toBe(90)
+    expect(parseDuration('0:05')).toBe(5)
+  })
+  it('rejects invalid minutes in h:mm', () => {
+    expect(parseDuration('1:75')).toBeNull()
+  })
+  it('parses unit form incl. decimals', () => {
+    expect(parseDuration('1h 30m')).toBe(90)
+    expect(parseDuration('1.5h')).toBe(90)
+    expect(parseDuration('45m')).toBe(45)
+  })
+  it('treats a bare number as minutes', () => {
+    expect(parseDuration('90')).toBe(90)
+  })
+  it('returns null for empty / garbage', () => {
+    expect(parseDuration('')).toBeNull()
+    expect(parseDuration('abc')).toBeNull()
+    expect(parseDuration('1h banana')).toBeNull()
+  })
+})
+
+describe('formatDuration', () => {
+  it('formats colon style', () => {
+    expect(formatDuration(90)).toBe('1:30')
+    expect(formatDuration(5)).toBe('0:05')
+  })
+  it('formats unit style', () => {
+    expect(formatDuration(90, 'units')).toBe('1h 30m')
+    expect(formatDuration(60, 'units')).toBe('1h')
+    expect(formatDuration(45, 'units')).toBe('45m')
+  })
+  it('returns empty for invalid input', () => {
+    expect(formatDuration(-1)).toBe('')
+    expect(formatDuration(NaN)).toBe('')
+  })
+})

package/src/duration.ts

@@ -0,0 +1,51 @@
+/**
+ * duration - pure parse/format helpers behind <SvDurationInput>. The canonical
+ * value is a number of MINUTES; these convert to/from the human forms people
+ * type ("1h 30m", "1:30", "90"). Framework-free + pure so they are unit-tested
+ * directly.
+ */
+
+/**
+ * Parse a human duration to minutes, or `null` if unparseable. Accepts:
+ * - `h:mm`         e.g. "1:30" -> 90
+ * - unit form      e.g. "1h 30m", "1.5h", "45m" -> 90 / 90 / 45
+ * - a bare number  e.g. "90" -> 90 (treated as minutes)
+ */
+export function parseDuration(input: string): number | null {
+  const s = input.trim().toLowerCase()
+  if (!s) return null
+
+  const colon = s.match(/^(\d+):(\d{1,2})$/)
+  if (colon) {
+    const mm = parseInt(colon[2]!, 10)
+    if (mm > 59) return null
+    return parseInt(colon[1]!, 10) * 60 + mm
+  }
+
+  const units = s.match(/\d+(?:\.\d+)?\s*[hm]/g)
+  if (units && units.join('').replace(/\s/g, '').length === s.replace(/\s/g, '').length) {
+    let total = 0
+    for (const part of units) {
+      const m = part.match(/(\d+(?:\.\d+)?)\s*([hm])/)!
+      const n = parseFloat(m[1]!)
+      total += m[2] === 'h' ? n * 60 : n
+    }
+    return Math.round(total)
+  }
+
+  const num = Number(s)
+  return Number.isFinite(num) ? Math.round(num) : null
+}
+
+/** Format minutes as `h:mm` (colon) or `Nh Nm` (units). Empty for invalid input. */
+export function formatDuration(minutes: number, style: 'colon' | 'units' = 'colon'): string {
+  if (!Number.isFinite(minutes) || minutes < 0) return ''
+  const h = Math.floor(minutes / 60)
+  const m = Math.round(minutes % 60)
+  if (style === 'units') {
+    if (h && m) return `${h}h ${m}m`
+    if (h) return `${h}h`
+    return `${m}m`
+  }
+  return `${h}:${String(m).padStart(2, '0')}`
+}