@svgrid/grid 2.1.22 → 2.2.0

package/src/createPopoverSelect.svelte.ts

@@ -1,210 +1,206 @@
-/**
- * createPopoverSelect - the shared HEADLESS engine behind the kit's dropdown
- * selects (SvMultiSelect, SvTreeSelect, SvGridSelect and any future one). It
- * owns the parts every anchored-panel select repeats: open/close state, the
- * `anchoredRect` positioning (reposition on scroll/resize), outside/Escape
- * dismissal via the shared layer stack, a roving `active` index over the visible
- * items, the WAI-ARIA combobox wiring (`aria-expanded` / `aria-controls` /
- * `aria-activedescendant` + stable option ids), and focus management (focus
- * moves into the panel on open, back to the trigger on close).
- *
- * The component owns its own `bind:this` refs and item rendering; it passes the
- * refs in as getters and spreads the returned prop-getters onto its trigger,
- * panel and items. Runes-based, like `createListbox`.
- */
-import { anchoredRect, type AnchoredRect } from './popover'
-import { createDismissableLayer } from './a11y/dismissable'
-
-let uidSeq = 0
-
-export type PopoverSelectConfig = {
-  /** Number of currently-visible/navigable items (post-filter). */
-  itemCount: () => number
-  /** Whether item `i` is disabled (skipped by roving, not selectable). */
-  disabled?: (index: number) => boolean
-  /** Commit the item at `index` (Enter or a click the component forwards). */
-  onSelect: (index: number) => void
-  /** Notified whenever the open state changes. */
-  onOpenChange?: (open: boolean) => void
-  /** The trigger element (component owns `bind:this`, passes a getter). */
-  getTrigger: () => HTMLElement | null
-  /** The panel element. */
-  getPanel: () => HTMLElement | null
-  /** Element focused when the panel opens (e.g. a search input). Defaults to the
-   *  panel itself. Its id-holder also carries `aria-activedescendant`. */
-  getInitialFocus?: () => HTMLElement | null
-  /** Estimated panel height, for the flip-up decision. Default 280. */
-  estimatedHeight?: () => number
-  /** Minimum panel width. Default 200. */
-  minWidth?: () => number
-  /** Close after a selection (single-select). Default true. */
-  closeOnSelect?: () => boolean
-  /** Active index to start on when opening (e.g. the selected row). Default 0. */
-  initialActive?: () => number
-  /** Handle a key the core doesn't (e.g. tree ArrowLeft/Right). Return true if
-   *  handled to stop the core's default handling. */
-  onExtraKey?: (event: KeyboardEvent, active: number) => boolean
-  idPrefix?: string
-}
-
-export function createPopoverSelect(config: PopoverSelectConfig) {
-  const id = `${config.idPrefix ?? 'sv-pop'}-${uidSeq++}`
-  const panelId = `${id}-panel`
-  const optionId = (i: number) => `${id}-opt-${i}`
-
-  let open = $state(false)
-  let active = $state(0)
-  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false })
-
-  const count = () => config.itemCount()
-  const isDisabled = (i: number) => config.disabled?.(i) ?? false
-
-  function enabledIndices(): number[] {
-    const out: number[] = []
-    const n = count()
-    for (let i = 0; i < n; i++) if (!isDisabled(i)) out.push(i)
-    return out
-  }
-  function clampActive(i: number): number {
-    const n = count()
-    return n <= 0 ? 0 : Math.max(0, Math.min(i, n - 1))
-  }
-
-  function setOpen(v: boolean) {
-    if (v === open) return
-    open = v
-    config.onOpenChange?.(v)
-  }
-  function openPanel() {
-    active = clampActive(config.initialActive?.() ?? 0)
-    setOpen(true)
-  }
-  function closePanel() {
-    setOpen(false)
-    config.getTrigger()?.focus()
-  }
-  function toggle() {
-    open ? setOpen(false) : openPanel()
-  }
-
-  function move(delta: number) {
-    const list = enabledIndices()
-    if (!list.length) return
-    const pos = list.indexOf(active)
-    active = list[(pos + delta + list.length) % list.length] ?? list[0]!
-  }
-  function first() { active = enabledIndices()[0] ?? 0 }
-  function last() { active = enabledIndices().at(-1) ?? 0 }
-  function selectActive() {
-    if (count() === 0 || isDisabled(active)) return
-    config.onSelect(active)
-    if (config.closeOnSelect?.() ?? true) closePanel()
-  }
-
-  function updatePos() {
-    const t = config.getTrigger()
-    if (!t) return
-    rect = anchoredRect(t.getBoundingClientRect(), {
-      estimatedHeight: config.estimatedHeight?.() ?? 280,
-      minWidth: config.minWidth?.() ?? 200,
-    })
-  }
-
-  // While open: position, focus into the panel, reposition on scroll/resize, and
-  // register a dismissable layer (Escape / outside-click, top-of-stack first).
-  $effect(() => {
-    if (!open) return
-    updatePos()
-    const initial = config.getInitialFocus?.() ?? config.getPanel()
-    queueMicrotask(() => initial?.focus())
-    const rp = () => updatePos()
-    window.addEventListener('scroll', rp, true)
-    window.addEventListener('resize', rp)
-    const layer = createDismissableLayer({
-      element: () => [config.getTrigger(), config.getPanel()],
-      onDismiss: () => setOpen(false),
-    })
-    layer.activate()
-    return () => {
-      window.removeEventListener('scroll', rp, true)
-      window.removeEventListener('resize', rp)
-      layer.release()
-    }
-  })
-
-  function onTriggerKeydown(e: KeyboardEvent) {
-    if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault()
-      openPanel()
-    } else if (e.key === 'ArrowUp') {
-      e.preventDefault()
-      openPanel()
-      last()
-    } else if (e.key === 'Escape') {
-      setOpen(false)
-    }
-  }
-  function onPanelKeydown(e: KeyboardEvent) {
-    if (config.onExtraKey?.(e, active)) return
-    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 'Enter': e.preventDefault(); selectActive(); break
-      case 'Escape': e.preventDefault(); closePanel(); break
-      case 'Tab': setOpen(false); break
-    }
-  }
-
-  /** The current active-descendant id (for the focused element), or undefined. */
-  const activeDescendant = () => (open && count() > 0 ? optionId(active) : undefined)
-
-  return {
-    get open() { return open },
-    set open(v: boolean) { setOpen(v) },
-    get active() { return active },
-    set active(i: number) { active = clampActive(i) },
-    get rect() { return rect },
-    /** Stable id of the panel element (for aria-controls / labelling). */
-    panelId,
-    /** Stable id of the option at `i` (for aria-activedescendant + item id). */
-    optionId,
-    activeDescendant,
-    openPanel,
-    closePanel,
-    toggle,
-    move,
-    first,
-    last,
-    selectActive,
-    updatePos,
-    onPanelKeydown,
-    /** True when item `i` is the roving-active one. */
-    isActive: (i: number) => i === active,
-    /** Spread onto the trigger button. Pass the ARIA popup type the panel
-     *  exposes (mirrors `focusOwnerProps(role)`); defaults to 'listbox' for
-     *  the classic select panels. */
-    triggerProps: (haspopup: 'listbox' | 'tree' | 'grid' = 'listbox') => ({
-      'aria-haspopup': haspopup,
-      'aria-expanded': open,
-      'aria-controls': open ? panelId : undefined,
-      onkeydown: onTriggerKeydown,
-    }),
-    /** Attributes for the element that OWNS focus + activedescendant (the panel,
-     *  or a search input). Pass the ARIA role the panel should expose. */
-    focusOwnerProps: (role: 'listbox' | 'tree' | 'grid' = 'listbox') => ({
-      role,
-      'aria-activedescendant': activeDescendant(),
-      onkeydown: onPanelKeydown,
-    }),
-    /** Spread onto the item element at `i`. */
-    itemProps: (i: number) => ({
-      id: optionId(i),
-      'data-active': i === active ? '' : undefined,
-      onpointermove: () => { if (!isDisabled(i)) active = i },
-    }),
-  }
-}
-
-export type PopoverSelect = ReturnType<typeof createPopoverSelect>
+/**
+ * createPopoverSelect - the shared HEADLESS engine behind the kit's dropdown
+ * selects (SvMultiSelect, SvTreeSelect, SvGridSelect and any future one). It
+ * owns the parts every anchored-panel select repeats: open/close state, the
+ * `anchoredRect` positioning (reposition on scroll/resize), outside/Escape
+ * dismissal via the shared layer stack, a roving `active` index over the visible
+ * items, the WAI-ARIA combobox wiring (`aria-expanded` / `aria-controls` /
+ * `aria-activedescendant` + stable option ids), and focus management (focus
+ * moves into the panel on open, back to the trigger on close).
+ *
+ * The component owns its own `bind:this` refs and item rendering; it passes the
+ * refs in as getters and spreads the returned prop-getters onto its trigger,
+ * panel and items. Runes-based, like `createListbox`.
+ */
+import { anchoredRect, type AnchoredRect } from './popover'
+import { createDismissableLayer } from './a11y/dismissable'
+import { enabledIndices as enabledIndicesOf, wrapMove } from './list-nav'
+
+let uidSeq = 0
+
+export type PopoverSelectConfig = {
+  /** Number of currently-visible/navigable items (post-filter). */
+  itemCount: () => number
+  /** Whether item `i` is disabled (skipped by roving, not selectable). */
+  disabled?: (index: number) => boolean
+  /** Commit the item at `index` (Enter or a click the component forwards). */
+  onSelect: (index: number) => void
+  /** Notified whenever the open state changes. */
+  onOpenChange?: (open: boolean) => void
+  /** The trigger element (component owns `bind:this`, passes a getter). */
+  getTrigger: () => HTMLElement | null
+  /** The panel element. */
+  getPanel: () => HTMLElement | null
+  /** Element focused when the panel opens (e.g. a search input). Defaults to the
+   *  panel itself. Its id-holder also carries `aria-activedescendant`. */
+  getInitialFocus?: () => HTMLElement | null
+  /** Estimated panel height, for the flip-up decision. Default 280. */
+  estimatedHeight?: () => number
+  /** Minimum panel width. Default 200. */
+  minWidth?: () => number
+  /** Close after a selection (single-select). Default true. */
+  closeOnSelect?: () => boolean
+  /** Active index to start on when opening (e.g. the selected row). Default 0. */
+  initialActive?: () => number
+  /** Handle a key the core doesn't (e.g. tree ArrowLeft/Right). Return true if
+   *  handled to stop the core's default handling. */
+  onExtraKey?: (event: KeyboardEvent, active: number) => boolean
+  idPrefix?: string
+}
+
+export function createPopoverSelect(config: PopoverSelectConfig) {
+  const id = `${config.idPrefix ?? 'sv-pop'}-${uidSeq++}`
+  const panelId = `${id}-panel`
+  const optionId = (i: number) => `${id}-opt-${i}`
+
+  let open = $state(false)
+  let active = $state(0)
+  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false, maxHeight: 0, availHeight: 0 })
+
+  const count = () => config.itemCount()
+  const isDisabled = (i: number) => config.disabled?.(i) ?? false
+
+  function enabledIndices(): number[] {
+    return enabledIndicesOf(count(), isDisabled)
+  }
+  function clampActive(i: number): number {
+    const n = count()
+    return n <= 0 ? 0 : Math.max(0, Math.min(i, n - 1))
+  }
+
+  function setOpen(v: boolean) {
+    if (v === open) return
+    open = v
+    config.onOpenChange?.(v)
+  }
+  function openPanel() {
+    active = clampActive(config.initialActive?.() ?? 0)
+    setOpen(true)
+  }
+  function closePanel() {
+    setOpen(false)
+    config.getTrigger()?.focus()
+  }
+  function toggle() {
+    open ? setOpen(false) : openPanel()
+  }
+
+  function move(delta: number) {
+    const next = wrapMove(enabledIndices(), active, delta)
+    if (next >= 0) active = next
+  }
+  function first() { active = enabledIndices()[0] ?? 0 }
+  function last() { active = enabledIndices().at(-1) ?? 0 }
+  function selectActive() {
+    if (count() === 0 || isDisabled(active)) return
+    config.onSelect(active)
+    if (config.closeOnSelect?.() ?? true) closePanel()
+  }
+
+  function updatePos() {
+    const t = config.getTrigger()
+    if (!t) return
+    rect = anchoredRect(t.getBoundingClientRect(), {
+      estimatedHeight: config.estimatedHeight?.() ?? 280,
+      minWidth: config.minWidth?.() ?? 200,
+    })
+  }
+
+  // While open: position, focus into the panel, reposition on scroll/resize, and
+  // register a dismissable layer (Escape / outside-click, top-of-stack first).
+  $effect(() => {
+    if (!open) return
+    updatePos()
+    const initial = config.getInitialFocus?.() ?? config.getPanel()
+    queueMicrotask(() => initial?.focus())
+    const rp = () => updatePos()
+    window.addEventListener('scroll', rp, true)
+    window.addEventListener('resize', rp)
+    const layer = createDismissableLayer({
+      element: () => [config.getTrigger(), config.getPanel()],
+      onDismiss: () => setOpen(false),
+    })
+    layer.activate()
+    return () => {
+      window.removeEventListener('scroll', rp, true)
+      window.removeEventListener('resize', rp)
+      layer.release()
+    }
+  })
+
+  function onTriggerKeydown(e: KeyboardEvent) {
+    if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      openPanel()
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      openPanel()
+      last()
+    } else if (e.key === 'Escape') {
+      setOpen(false)
+    }
+  }
+  function onPanelKeydown(e: KeyboardEvent) {
+    if (config.onExtraKey?.(e, active)) return
+    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 'Enter': e.preventDefault(); selectActive(); break
+      case 'Escape': e.preventDefault(); closePanel(); break
+      case 'Tab': setOpen(false); break
+    }
+  }
+
+  /** The current active-descendant id (for the focused element), or undefined. */
+  const activeDescendant = () => (open && count() > 0 ? optionId(active) : undefined)
+
+  return {
+    get open() { return open },
+    set open(v: boolean) { setOpen(v) },
+    get active() { return active },
+    set active(i: number) { active = clampActive(i) },
+    get rect() { return rect },
+    /** Stable id of the panel element (for aria-controls / labelling). */
+    panelId,
+    /** Stable id of the option at `i` (for aria-activedescendant + item id). */
+    optionId,
+    activeDescendant,
+    openPanel,
+    closePanel,
+    toggle,
+    move,
+    first,
+    last,
+    selectActive,
+    updatePos,
+    onPanelKeydown,
+    /** True when item `i` is the roving-active one. */
+    isActive: (i: number) => i === active,
+    /** Spread onto the trigger button. Pass the ARIA popup type the panel
+     *  exposes (mirrors `focusOwnerProps(role)`); defaults to 'listbox' for
+     *  the classic select panels. */
+    triggerProps: (haspopup: 'listbox' | 'tree' | 'grid' = 'listbox') => ({
+      'aria-haspopup': haspopup,
+      'aria-expanded': open,
+      'aria-controls': open ? panelId : undefined,
+      onkeydown: onTriggerKeydown,
+    }),
+    /** Attributes for the element that OWNS focus + activedescendant (the panel,
+     *  or a search input). Pass the ARIA role the panel should expose. */
+    focusOwnerProps: (role: 'listbox' | 'tree' | 'grid' = 'listbox') => ({
+      role,
+      'aria-activedescendant': activeDescendant(),
+      onkeydown: onPanelKeydown,
+    }),
+    /** Spread onto the item element at `i`. */
+    itemProps: (i: number) => ({
+      id: optionId(i),
+      'data-active': i === active ? '' : undefined,
+      onpointermove: () => { if (!isDisabled(i)) active = i },
+    }),
+  }
+}
+
+export type PopoverSelect = ReturnType<typeof createPopoverSelect>

package/src/createStepper.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createStepper } from './createStepper'
+
+function make(over: Partial<{ current: number; count: number; linear: boolean }> = {}) {
+  let current = over.current ?? 2
+  const onChange = vi.fn((i: number) => (current = i))
+  const st = createStepper({
+    count: () => over.count ?? 5,
+    current: () => current,
+    onChange,
+    linear: () => over.linear ?? true,
+  })
+  return { st, onChange }
+}
+
+describe('createStepper', () => {
+  it('reports per-step status relative to the current step', () => {
+    const { st } = make({ current: 2 })
+    expect(st.statusOf(0)).toBe('complete')
+    expect(st.statusOf(1)).toBe('complete')
+    expect(st.statusOf(2)).toBe('active')
+    expect(st.statusOf(3)).toBe('upcoming')
+  })
+
+  it('in linear mode only reached steps are clickable', () => {
+    const { st } = make({ current: 2, linear: true })
+    expect(st.clickable(1)).toBe(true) // complete
+    expect(st.clickable(2)).toBe(true) // active
+    expect(st.clickable(3)).toBe(false) // upcoming
+  })
+
+  it('in free mode every step is clickable', () => {
+    const { st } = make({ current: 2, linear: false })
+    expect(st.clickable(4)).toBe(true)
+  })
+
+  it('go() navigates only to clickable, different steps', () => {
+    const { st, onChange } = make({ current: 2, linear: true })
+    st.go(4) // upcoming, blocked in linear mode
+    expect(onChange).not.toHaveBeenCalled()
+    st.go(0) // reached
+    expect(onChange).toHaveBeenLastCalledWith(0)
+    st.go(2) // same as current
+    expect(onChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('prev/next step through (relative to current)', () => {
+    const fwd = make({ current: 2, linear: false })
+    fwd.st.next()
+    expect(fwd.onChange).toHaveBeenLastCalledWith(3)
+    const back = make({ current: 2, linear: false })
+    back.st.prev()
+    expect(back.onChange).toHaveBeenLastCalledWith(1)
+  })
+
+  it('stepButtonProps marks the active step and disables unreachable ones', () => {
+    const { st } = make({ current: 2, linear: true })
+    expect(st.stepButtonProps(2)['aria-current']).toBe('step')
+    expect(st.stepButtonProps(0)['aria-current']).toBeUndefined()
+    expect(st.stepButtonProps(3).disabled).toBe(true)
+  })
+})

package/src/createStepper.ts

@@ -0,0 +1,61 @@
+/**
+ * createStepper - the HEADLESS core behind <SvStepper>: per-step status
+ * (complete / active / upcoming), the linear-vs-free clickability rule, and
+ * navigation, as pure getters + prop-getters. No runes, framework-free, directly
+ * unit-testable.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createStepper } from '@svgrid/grid'
+ *   const st = createStepper({ count: () => steps.length, current: () => i, onChange: (n) => (i = n) })
+ * </script>
+ * <ol>
+ *   {#each steps as step, idx}
+ *     <li class="is-{st.statusOf(idx)}">
+ *       <button {...st.stepButtonProps(idx)}>{step.label}</button>
+ *     </li>
+ *   {/each}
+ * </ol>
+ * ```
+ */
+export type StepStatus = 'complete' | 'active' | 'upcoming'
+
+export type StepperConfig = {
+  count: () => number
+  /** 0-based index of the active step. */
+  current: () => number
+  onChange?: (index: number) => void
+  /** Only allow navigating to already-reached steps. Default true. */
+  linear?: () => boolean
+}
+
+export function createStepper(config: StepperConfig) {
+  const current = () => config.current()
+  const linear = () => config.linear?.() ?? true
+
+  const statusOf = (i: number): StepStatus =>
+    i < current() ? 'complete' : i === current() ? 'active' : 'upcoming'
+  const clickable = (i: number) => (linear() ? i <= current() : true)
+  const go = (i: number) => {
+    if (clickable(i) && i !== current()) config.onChange?.(i)
+  }
+  const next = () => go(current() + 1)
+  const prev = () => go(current() - 1)
+
+  return {
+    statusOf,
+    clickable,
+    go,
+    next,
+    prev,
+    isActive: (i: number) => i === current(),
+    /** Spread onto a step's button. */
+    stepButtonProps: (i: number) => ({
+      'aria-current': (statusOf(i) === 'active' ? 'step' : undefined) as 'step' | undefined,
+      disabled: !clickable(i),
+      onclick: () => go(i),
+    }),
+  }
+}
+
+export type Stepper = ReturnType<typeof createStepper>

package/src/createTooltip.svelte.ts

@@ -0,0 +1,86 @@
+/**
+ * createTooltip - the HEADLESS core behind <SvTooltip>: the hover/focus open
+ * state machine with a show delay, Escape-to-hide, and the `aria-describedby` /
+ * `role="tooltip"` wiring - as prop-getters you spread onto your own anchor and
+ * tooltip elements. No styles, no positioning (that is a DOM concern the renderer
+ * owns), like `createListbox`.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createTooltip } from '@svgrid/grid'
+ *   const tip = createTooltip({ text: () => label })
+ * </script>
+ * <span {...tip.anchorProps()}>{@render children?.()}</span>
+ * {#if tip.open}
+ *   <div {...tip.tooltipProps()}>{label}</div>
+ * {/if}
+ * ```
+ */
+import { nextEditorId } from './editor-contract'
+
+export type TooltipConfig = {
+  /** The tooltip text; the tooltip never opens when it is empty. */
+  text?: () => string | undefined
+  /** Suppress the tooltip entirely. */
+  disabled?: () => boolean
+  /** Show delay in ms after hover/focus. Default 300. */
+  delay?: () => number
+}
+
+export type TooltipAnchorProps = {
+  'aria-describedby': string | undefined
+  onpointerenter: () => void
+  onpointerleave: () => void
+  onfocusin: () => void
+  onfocusout: () => void
+}
+
+export type TooltipProps = {
+  id: string
+  role: 'tooltip'
+}
+
+export function createTooltip(config: TooltipConfig = {}) {
+  const id = nextEditorId('sv-tip')
+  let open = $state(false)
+  let showTimer: ReturnType<typeof setTimeout> | undefined
+
+  function show() {
+    if ((config.disabled?.() ?? false) || !(config.text?.() ?? '')) return
+    clearTimeout(showTimer)
+    showTimer = setTimeout(() => { open = true }, config.delay?.() ?? 300)
+  }
+  function hide() {
+    clearTimeout(showTimer)
+    open = false
+  }
+
+  // Escape hides the tooltip while it is open (WAI-ARIA tooltip pattern).
+  $effect(() => {
+    if (!open) return
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') hide() }
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  })
+
+  return {
+    get open() { return open },
+    /** Stable id of the tooltip element (for `aria-describedby` + the tip's id). */
+    tipId: id,
+    show,
+    hide,
+    /** Spread onto the anchor/trigger wrapper. Also mirror `tipId` onto the real
+     *  focusable child's `aria-describedby` so AT announces it on focus. */
+    anchorProps: (): TooltipAnchorProps => ({
+      'aria-describedby': open ? id : undefined,
+      onpointerenter: show,
+      onpointerleave: hide,
+      onfocusin: show,
+      onfocusout: hide,
+    }),
+    /** Spread onto the tooltip element. */
+    tooltipProps: (): TooltipProps => ({ id, role: 'tooltip' }),
+  }
+}
+
+export type Tooltip = ReturnType<typeof createTooltip>