@svgrid/grid 1.2.22 → 1.2.24

package/src/createDropdownList.svelte.ts

@@ -0,0 +1,125 @@
+/**
+ * createDropdownList - the HEADLESS core behind <SvDropDownList>: a single-select
+ * dropdown state machine (trigger open/close, roving active index over enabled
+ * options, full keyboard) exposed as **prop-getters** you spread onto YOUR OWN
+ * markup. No styles, no DOM, no portal/measurement - those stay in the styled
+ * component.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createDropdownList } from '@svgrid/grid'
+ *   let value = $state<string | null>(null)
+ *   const dd = createDropdownList({ options: () => options, value: () => value, onChange: (v) => (value = v) })
+ * </script>
+ * <button {...dd.triggerProps()}>{dd.selected?.label ?? 'Select'}</button>
+ * {#if dd.open}
+ *   <ul {...dd.listboxProps()}>
+ *     {#each options as opt, i (opt.value)}<li {...dd.optionProps(i)}>{opt.label}</li>{/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
+import type { ListOption } from './list-option'
+
+export type DropdownValue = string | number | null
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type DropdownListConfig = {
+  options: () => ReadonlyArray<ListOption>
+  value: () => DropdownValue
+  onChange?: (value: string | number) => void
+  disabled?: () => boolean
+  ariaLabel?: () => string | undefined
+  /** DOM focus hook provided by the renderer; the core never touches the DOM. */
+  focusTrigger?: () => void
+}
+
+export function createDropdownList(config: DropdownListConfig) {
+  const opts = () => config.options()
+  const disabled = () => config.disabled?.() ?? false
+
+  let open = $state(false)
+  let active = $state(-1)
+
+  const selected = $derived(opts().find((o) => o.value === config.value()) ?? null)
+  const enabledIdx = $derived(opts().map((o, i) => (o.disabled ? -1 : i)).filter((i) => i >= 0))
+
+  function openPanel() {
+    if (disabled() || open) return
+    open = true
+    active = Math.max(0, opts().findIndex((o) => o.value === config.value()))
+  }
+  function close() { open = false }
+  function toggle() { if (open) { close() } else { openPanel() } }
+  function pick(i: number) {
+    const o = opts()[i]
+    if (!o || o.disabled) return
+    config.onChange?.(o.value); close(); config.focusTrigger?.()
+  }
+  function setActive(i: number) { const o = opts()[i]; if (o && !o.disabled) active = i }
+  function move(d: number) {
+    const pos = enabledIdx.indexOf(active)
+    active = enabledIdx[(pos + d + enabledIdx.length) % enabledIdx.length] ?? active
+  }
+  function onKeydown(e: KeyboardEvent) {
+    if (disabled()) return
+    if (!open && (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ')) { e.preventDefault(); openPanel(); return }
+    if (!open) return
+    if (e.key === 'ArrowDown') { e.preventDefault(); move(1) }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); move(-1) }
+    else if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); pick(active) }
+    else if (e.key === 'Escape') { e.preventDefault(); close(); config.focusTrigger?.() }
+    else if (e.key === 'Home') { active = enabledIdx[0] ?? 0 }
+    else if (e.key === 'End') { active = enabledIdx.at(-1) ?? 0 }
+  }
+
+  return {
+    /** Panel open state. */
+    get open() { return open },
+    /** Highlighted option index into `options`. */
+    get activeIndex() { return active },
+    /** The option matching the controlled value, if any. */
+    get selected() { return selected },
+    /** Controlled value. */
+    get value() { return config.value() },
+    isActive: (i: number) => i === active,
+    isSelected: (o: ListOption) => o.value === config.value(),
+    setActive,
+    openPanel,
+    close,
+    toggle,
+    pick,
+    move,
+    onKeydown,
+    /** Spread onto the trigger <button>. */
+    triggerProps: () => ({
+      type: 'button' as const,
+      'aria-haspopup': 'listbox' as const,
+      'aria-expanded': open,
+      'aria-label': config.ariaLabel?.(),
+      disabled: disabled(),
+      onclick: toggle,
+      onkeydown: onKeydown,
+    }),
+    /** Spread onto the listbox container. */
+    listboxProps: () => ({
+      role: 'listbox' as const,
+      tabindex: -1,
+    }),
+    /** Spread onto the option at `index` (index into `options`). */
+    optionProps: (index: number) => {
+      const o = opts()[index]
+      return {
+        role: 'option' as const,
+        tabindex: -1,
+        'aria-selected': o ? o.value === config.value() : false,
+        'aria-disabled': o?.disabled,
+        'data-idx': index,
+        onclick: () => pick(index),
+        onpointermove: () => { if (o && !o.disabled) active = index },
+      }
+    },
+  }
+}
+
+export type DropdownList = ReturnType<typeof createDropdownList>

package/src/createGauge.svelte.ts

@@ -0,0 +1,86 @@
+/**
+ * createGauge - the HEADLESS core behind <SvGauge>. A gauge is a display control,
+ * so this core is light: value in, computed arc/needle geometry out, plus a
+ * `rootProps()` with `role="meter"` + `aria-valuenow/min/max`. The styled
+ * <SvGauge> (or your own SVG) reads the geometry and draws it.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createGauge } from '@svgrid/grid'
+ *   const g = createGauge({ value: () => value })
+ * </script>
+ * <div {...g.rootProps()}>
+ *   <svg viewBox={`0 0 ${g.cx * 2} ${g.cy * 2}`}>
+ *     <path d={g.arcPath(0, g.clamped, g.r)} />
+ *   </svg>
+ * </div>
+ * ```
+ */
+export type GaugePoint = { x: number; y: number }
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type GaugeConfig = {
+  value: () => number
+  min?: () => number
+  max?: () => number
+  /** Sweep angle in degrees (default 270, a classic dashboard gauge). */
+  sweep?: () => number
+  size?: () => number
+  thickness?: () => number
+  ariaLabel?: () => string | undefined
+}
+
+export function createGauge(config: GaugeConfig) {
+  const min = () => config.min?.() ?? 0
+  const max = () => config.max?.() ?? 100
+  const sweep = () => config.sweep?.() ?? 270
+  const size = () => config.size?.() ?? 180
+  const thickness = () => config.thickness?.() ?? 14
+
+  const clamped = $derived(Math.min(max(), Math.max(min(), config.value())))
+  const startAngle = $derived(90 + (360 - sweep()) / 2) // symmetric around the bottom
+  const cx = $derived(size() / 2)
+  const cy = $derived(size() / 2)
+  const r = $derived(size() / 2 - thickness() / 2 - 2)
+
+  const frac = (v: number) => (v - min()) / (max() - min())
+  const angleOf = (v: number) => startAngle + frac(v) * sweep()
+  function polar(angleDeg: number, radius: number): GaugePoint {
+    const a = (angleDeg * Math.PI) / 180
+    return { x: cx + radius * Math.cos(a), y: cy + radius * Math.sin(a) }
+  }
+  function arcPath(v0: number, v1: number, radius: number): string {
+    const a0 = angleOf(v0)
+    const a1 = angleOf(v1)
+    const p0 = polar(a0, radius)
+    const p1 = polar(a1, radius)
+    const large = a1 - a0 > 180 ? 1 : 0
+    return `M ${p0.x} ${p0.y} A ${radius} ${radius} 0 ${large} 1 ${p1.x} ${p1.y}`
+  }
+  const needleEnd = $derived(polar(angleOf(clamped), r - thickness() / 2))
+
+  return {
+    /** Value clamped into [min, max]. */
+    get clamped() { return clamped },
+    get startAngle() { return startAngle },
+    get cx() { return cx },
+    get cy() { return cy },
+    get r() { return r },
+    /** Needle tip point (for `<line x2 y2>`). */
+    get needleEnd() { return needleEnd },
+    frac,
+    angleOf,
+    polar,
+    arcPath,
+    /** Spread onto the gauge root element. */
+    rootProps: () => ({
+      role: 'meter' as const,
+      'aria-valuenow': clamped,
+      'aria-valuemin': min(),
+      'aria-valuemax': max(),
+      'aria-label': config.ariaLabel?.() ?? 'Gauge',
+    }),
+  }
+}
+
+export type Gauge = ReturnType<typeof createGauge>

package/src/createListbox.svelte.ts

@@ -0,0 +1,186 @@
+/**
+ * createListbox - the HEADLESS core behind <SvListBox>, in the same spirit as
+ * `createSvGrid` for the grid: a runes-based state machine (roving active index,
+ * single/multi selection, full keyboard) with **prop-getters** you spread onto
+ * YOUR OWN markup. No styles, no DOM assumptions - render it however you like.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createListbox } from '@svgrid/grid'
+ *   let value = $state<string | null>(null)
+ *   const lb = createListbox({
+ *     options: () => options, value: () => value,
+ *     onChange: (v) => (value = v),
+ *   })
+ * </script>
+ * <ul {...lb.rootProps()}>
+ *   {#each options as opt, i}
+ *     <li {...lb.optionProps(i)}>{opt.label}</li>
+ *   {/each}
+ * </ul>
+ * ```
+ *
+ * The styled <SvListBox> is just one renderer over this core.
+ */
+import type { ListOption } from './list-option'
+
+export type ListboxValue = string | number | Array<string | number> | null
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes
+ *  (the same controlled pattern Svelte headless libraries use). */
+export type ListboxConfig = {
+  options: () => ReadonlyArray<ListOption>
+  value: () => ListboxValue
+  onChange?: (value: string | number | Array<string | number>) => void
+  multiple?: () => boolean
+  disabled?: () => boolean
+  ariaLabel?: () => string | undefined
+}
+
+export type OptionProps = {
+  role: 'option'
+  id: string
+  'aria-selected': boolean
+  'aria-disabled': boolean | undefined
+  'data-idx': number
+  'data-active': '' | undefined
+  'data-selected': '' | undefined
+  onclick: () => void
+  onpointermove: () => void
+}
+
+export type ListboxRootProps = {
+  role: 'listbox'
+  'aria-multiselectable': boolean
+  'aria-label': string | undefined
+  'aria-disabled': boolean
+  'aria-activedescendant': string | undefined
+  tabindex: number
+  onkeydown: (e: KeyboardEvent) => void
+}
+
+export type Listbox = {
+  /** Currently highlighted option index (roving focus). */
+  readonly activeIndex: number
+  /** Selected values as an array (single mode -> 0 or 1 entry). */
+  readonly selectedValues: Array<string | number>
+  isSelected: (value: string | number) => boolean
+  isActive: (index: number) => boolean
+  setActive: (index: number) => void
+  /** Toggle (multi) / set (single) the option at `index`. */
+  pick: (index: number) => void
+  /** Move the active highlight by `delta`, wrapping over enabled options. */
+  move: (delta: number) => void
+  first: () => void
+  last: () => void
+  onKeydown: (e: KeyboardEvent) => void
+  /** Spread onto the list container element. */
+  rootProps: () => ListboxRootProps
+  /** Spread onto the option element at `index`. */
+  optionProps: (index: number) => OptionProps
+}
+
+let uid = 0
+
+/** Normalize a listbox value to an array (pure). */
+export function toSelectedArray(value: ListboxValue, multiple: boolean): Array<string | number> {
+  if (multiple) return Array.isArray(value) ? [...value] : value == null ? [] : [value]
+  return value == null ? [] : [value as string | number]
+}
+
+export function createListbox(config: ListboxConfig): Listbox {
+  const id = `sv-lb-${uid++}`
+  const opts = () => config.options()
+  const multiple = () => config.multiple?.() ?? false
+  const disabled = () => config.disabled?.() ?? false
+
+  let active = $state(0)
+  const selected = $derived(toSelectedArray(config.value(), multiple()))
+  const enabledIdx = $derived(opts().map((o, i) => (o.disabled ? -1 : i)).filter((i) => i >= 0))
+
+  // Keep the active index on an enabled option as options change.
+  $effect(() => {
+    const o = opts()[active]
+    if (!o || o.disabled) active = enabledIdx[0] ?? 0
+  })
+
+  const isSelected = (value: string | number) => selected.includes(value)
+  const isActive = (index: number) => index === active
+  const optionId = (index: number) => `${id}-opt-${index}`
+
+  function setActive(index: number) {
+    const o = opts()[index]
+    if (o && !o.disabled) active = index
+  }
+
+  function pick(index: number) {
+    const o = opts()[index]
+    if (!o || o.disabled || disabled()) return
+    active = index
+    if (multiple()) {
+      const set = new Set(selected)
+      set.has(o.value) ? set.delete(o.value) : set.add(o.value)
+      config.onChange?.([...set])
+    } else {
+      config.onChange?.(o.value)
+    }
+  }
+
+  function move(delta: number) {
+    const list = enabledIdx
+    if (!list.length) return
+    const pos = list.indexOf(active)
+    const next = list[(pos + delta + list.length) % list.length]
+    if (next != null) active = next
+  }
+  const first = () => { active = enabledIdx[0] ?? 0 }
+  const last = () => { active = enabledIdx.at(-1) ?? 0 }
+
+  function onKeydown(e: KeyboardEvent) {
+    if (disabled()) 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 ' ':
+      case 'Enter': e.preventDefault(); pick(active); break
+    }
+  }
+
+  return {
+    get activeIndex() { return active },
+    get selectedValues() { return selected },
+    isSelected,
+    isActive,
+    setActive,
+    pick,
+    move,
+    first,
+    last,
+    onKeydown,
+    rootProps: () => ({
+      role: 'listbox',
+      'aria-multiselectable': multiple(),
+      'aria-label': config.ariaLabel?.(),
+      'aria-disabled': disabled(),
+      'aria-activedescendant': opts()[active] ? optionId(active) : undefined,
+      tabindex: disabled() ? -1 : 0,
+      onkeydown: onKeydown,
+    }),
+    optionProps: (index: number) => {
+      const o = opts()[index]
+      return {
+        role: 'option',
+        id: optionId(index),
+        'aria-selected': o ? isSelected(o.value) : false,
+        'aria-disabled': o?.disabled,
+        'data-idx': index,
+        'data-active': isActive(index) ? '' : undefined,
+        'data-selected': o && isSelected(o.value) ? '' : undefined,
+        onclick: () => pick(index),
+        onpointermove: () => setActive(index),
+      }
+    },
+  }
+}

package/src/createMaskedInput.svelte.ts

@@ -0,0 +1,81 @@
+/**
+ * createMaskedInput - the HEADLESS core behind <SvMaskedInput>: a runes-based
+ * state machine that owns the pattern-mask formatting (#=digit, A=letter,
+ * *=alnum; other chars are literals) via the pure `./datetime/mask` engine,
+ * exposed as **prop-getters** you spread onto YOUR OWN markup. No styles, no DOM.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createMaskedInput } from '@svgrid/grid'
+ *   let value = $state('')
+ *   const mi = createMaskedInput({ value: () => value, mask: () => '(###) ###-####', onChange: (m) => (value = m) })
+ * </script>
+ * <input {...mi.inputProps()} />
+ * ```
+ *
+ * The styled <SvMaskedInput> is just one renderer over this core.
+ */
+import { applyMask, unmask, isMaskComplete } from './datetime/mask'
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type MaskedInputConfig = {
+  value: () => string
+  /** Called with (masked, raw, complete). */
+  onChange?: (masked: string, raw: string, complete: boolean) => void
+  mask?: () => string
+  placeholder?: () => string | undefined
+  disabled?: () => boolean
+  readonly?: () => boolean
+  ariaLabel?: () => string | undefined
+}
+
+export function createMaskedInput(config: MaskedInputConfig) {
+  const mask = () => config.mask?.() ?? ''
+  const disabled = () => config.disabled?.() ?? false
+  const readonly = () => config.readonly?.() ?? false
+
+  let text = $state('')
+  let lastRaw = ''
+
+  // Reflect controlled `value` into the masked display text.
+  $effect(() => {
+    const m = mask()
+    const raw = m ? unmask(config.value(), m) : config.value()
+    if (raw !== lastRaw) {
+      lastRaw = raw
+      text = m ? applyMask(raw, m).formatted : config.value()
+    }
+  })
+
+  function onInput(e: Event) {
+    const el = e.currentTarget as HTMLInputElement
+    const m = mask()
+    const raw = m ? unmask(el.value, m) : el.value
+    const masked = m ? applyMask(raw, m).formatted : el.value
+    lastRaw = raw
+    text = masked
+    el.value = masked
+    config.onChange?.(masked, raw, m ? isMaskComplete(masked, m) : true)
+  }
+
+  return {
+    /** The current masked display text. */
+    get masked() { return text },
+    /** The raw (unmasked) data characters. */
+    get raw() { return mask() ? unmask(text, mask()) : text },
+    /** Whether every token position in the mask is filled. */
+    get complete() { return mask() ? isMaskComplete(text, mask()) : true },
+    /** Spread onto the text input element. */
+    inputProps: () => ({
+      value: text,
+      type: 'text' as const,
+      placeholder: config.placeholder?.() ?? mask(),
+      disabled: disabled(),
+      readonly: readonly(),
+      'aria-label': config.ariaLabel?.(),
+      oninput: onInput,
+    }),
+  }
+}
+
+export type MaskedInputCore = ReturnType<typeof createMaskedInput>

package/src/createNumberInput.svelte.ts

@@ -0,0 +1,193 @@
+/**
+ * createNumberInput - the HEADLESS core behind <SvNumberInput>, in the same
+ * spirit as `createListbox` / `createSvGrid`: a runes-based state machine that
+ * owns parse / format / clamp / spinner state + keyboard, exposed as
+ * **prop-getters** you spread onto YOUR OWN markup. No styles, no DOM.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createNumberInput } from '@svgrid/grid'
+ *   let value = $state<number | null>(0)
+ *   const num = createNumberInput({ value: () => value, onChange: (v) => (value = v) })
+ * </script>
+ * <input {...num.inputProps()} />
+ * <button {...num.incrementProps()}>+</button>
+ * <button {...num.decrementProps()}>-</button>
+ * ```
+ *
+ * The styled <SvNumberInput> 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. */
+export type NumberInputConfig = {
+  value: () => number | null
+  onChange?: (value: number | null) => void
+  min?: () => number
+  max?: () => number
+  step?: () => number
+  precision?: () => number | undefined
+  /** Group thousands (1,234) on display. */
+  grouping?: () => boolean
+  prefix?: () => string
+  suffix?: () => string
+  placeholder?: () => string | undefined
+  disabled?: () => boolean
+  readonly?: () => boolean
+  // Editor contract (ARIA + validation) - folded into inputProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  ariaLabel?: () => string | undefined
+}
+
+export function createNumberInput(config: NumberInputConfig) {
+  const min = () => config.min?.() ?? -Infinity
+  const max = () => config.max?.() ?? Infinity
+  const step = () => config.step?.() ?? 1
+  const precision = () => config.precision?.()
+  const grouping = () => config.grouping?.() ?? false
+  const prefix = () => config.prefix?.() ?? ''
+  const suffix = () => config.suffix?.() ?? ''
+  const disabled = () => config.disabled?.() ?? false
+  const readonly = () => config.readonly?.() ?? false
+
+  const isInteractive = $derived(!disabled() && !readonly())
+  let text = $state('')
+  let focused = $state(false)
+  let lastKey = ''
+
+  const fmt = $derived(
+    new Intl.NumberFormat(undefined, {
+      useGrouping: grouping(),
+      minimumFractionDigits: precision() ?? 0,
+      maximumFractionDigits: precision() ?? 20,
+    }),
+  )
+
+  function display(v: number | null): string {
+    if (v == null) return ''
+    return `${prefix()}${fmt.format(v)}${suffix()}`
+  }
+
+  // Reflect controlled `value` into the display text unless the user is editing.
+  $effect(() => {
+    const v = config.value()
+    const key = v == null ? 'null' : String(v)
+    if (key !== lastKey) {
+      lastKey = key
+      if (!focused) text = display(v)
+    }
+  })
+
+  function clamp(n: number): number {
+    let r = Math.min(max(), Math.max(min(), n))
+    const p = precision()
+    if (p != null) r = Math.round(r * 10 ** p) / 10 ** p
+    return r
+  }
+
+  function parse(s: string): number | null {
+    const cleaned = s.replace(prefix(), '').replace(suffix(), '').replace(/[,\s]/g, '').trim()
+    if (cleaned === '' || cleaned === '-') return null
+    const n = Number(cleaned)
+    return isNaN(n) ? null : n
+  }
+
+  function commit() {
+    const parsed = parse(text)
+    const next = parsed == null ? null : clamp(parsed)
+    lastKey = next == null ? 'null' : String(next)
+    config.onChange?.(next)
+    text = display(next)
+  }
+
+  function bump(dir: 1 | -1) {
+    if (!isInteractive) return
+    const base = parse(text) ?? 0
+    const next = clamp(base + dir * step())
+    lastKey = String(next)
+    config.onChange?.(next)
+    text = focused ? String(next) : display(next)
+  }
+  const increment = () => bump(1)
+  const decrement = () => bump(-1)
+
+  function onFocus() {
+    focused = true
+    // Show the bare number for easy editing.
+    const v = config.value()
+    text = v == null ? '' : String(v)
+  }
+  function onBlur() {
+    focused = false
+    commit()
+  }
+  function onInput(e: Event) {
+    text = (e.currentTarget as HTMLInputElement).value
+  }
+  function onKeydown(e: KeyboardEvent) {
+    if (e.key === 'ArrowUp') { e.preventDefault(); bump(1) }
+    else if (e.key === 'ArrowDown') { e.preventDefault(); bump(-1) }
+    else if (e.key === 'Enter') { commit() }
+  }
+
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
+  return {
+    /** The current display text (bind this to your input's value). */
+    get text() { return text },
+    /** Whether the field is being edited. */
+    get focused() { return focused },
+    /** Whether interaction is allowed (not disabled and not readonly). */
+    get isInteractive() { return isInteractive },
+    commit,
+    bump,
+    increment,
+    decrement,
+    /** Spread onto the text input element. */
+    inputProps: () => ({
+      id: config.id?.(),
+      value: text,
+      type: 'text' as const,
+      inputmode: 'decimal' as const,
+      role: 'spinbutton' as const,
+      placeholder: config.placeholder?.(),
+      disabled: disabled(),
+      readonly: readonly(),
+      'aria-valuenow': config.value() ?? undefined,
+      'aria-valuemin': min() === -Infinity ? undefined : min(),
+      'aria-valuemax': max() === Infinity ? undefined : max(),
+      ...editorAria(ariaState()),
+      oninput: onInput,
+      onfocus: onFocus,
+      onblur: onBlur,
+      onkeydown: onKeydown,
+    }),
+    /** Spread onto a native increment button. */
+    incrementProps: () => ({
+      type: 'button' as const,
+      'aria-label': 'Increment',
+      disabled: !isInteractive,
+      tabindex: -1,
+      onclick: increment,
+    }),
+    /** Spread onto a native decrement button. */
+    decrementProps: () => ({
+      type: 'button' as const,
+      'aria-label': 'Decrement',
+      disabled: !isInteractive,
+      tabindex: -1,
+      onclick: decrement,
+    }),
+  }
+}
+
+export type NumberInputCore = ReturnType<typeof createNumberInput>