@svgrid/grid 1.2.23 → 1.2.25

package/src/createCombobox.svelte.ts

@@ -0,0 +1,158 @@
+/**
+ * createCombobox - the HEADLESS core behind <SvComboBox>, in the same spirit as
+ * `createListbox` / `createSvGrid`: a runes-based state machine (type-to-filter,
+ * roving active index, full keyboard, unmatched-text revert) exposed as
+ * **prop-getters** you spread onto YOUR OWN markup. No styles, no DOM, no portal
+ * or measurement - those render concerns stay in the styled component.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createCombobox } from '@svgrid/grid'
+ *   let value = $state<string | null>(null)
+ *   const cb = createCombobox({ options: () => options, value: () => value, onChange: (v) => (value = v) })
+ * </script>
+ * <input {...cb.inputProps()} />
+ * {#if cb.open}
+ *   <ul {...cb.listboxProps()}>
+ *     {#each cb.filtered as opt, i (opt.value)}<li {...cb.optionProps(i)}>{opt.label}</li>{/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
+import { filterOptions, type ListOption } from './list-option'
+
+export type ComboboxValue = string | number | null
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type ComboboxConfig = {
+  options: () => ReadonlyArray<ListOption>
+  value: () => ComboboxValue
+  onChange?: (value: ComboboxValue) => void
+  disabled?: () => boolean
+  ariaLabel?: () => string | undefined
+  /** DOM focus hooks provided by the renderer; the core itself never touches the DOM. */
+  focusInput?: () => void
+  blurInput?: () => void
+}
+
+let uid = 0
+
+export function createCombobox(config: ComboboxConfig) {
+  const id = `sv-combo-${uid++}`
+  const listId = `${id}-list`
+  const opts = () => config.options()
+  const disabled = () => config.disabled?.() ?? false
+
+  let open = $state(false)
+  let query = $state('')
+  let active = $state(0)
+  let editing = $state(false)
+
+  const selected = $derived(opts().find((o) => o.value === config.value()) ?? null)
+  const filtered = $derived(editing ? filterOptions(opts(), query) : [...opts()])
+  const shownText = $derived(editing ? query : selected?.label ?? '')
+
+  // While not actively editing, keep the shown text in sync with the selection.
+  $effect(() => { if (!editing) query = selected?.label ?? '' })
+
+  const optionId = (i: number) => `${listId}-opt-${i}`
+
+  function openPanel() { if (disabled() || open) return; open = true; active = 0 }
+  function close(revert = true) {
+    open = false; editing = false
+    if (revert) query = selected?.label ?? ''
+  }
+  function toggle() { if (open) { close() } else { config.focusInput?.(); openPanel() } }
+  function pick(o: ListOption | undefined) {
+    if (!o || o.disabled) return
+    config.onChange?.(o.value); query = o.label; editing = false; open = false; config.blurInput?.()
+  }
+  function setActive(i: number) { const o = filtered[i]; if (o && !o.disabled) active = i }
+  function onInput(e: Event) {
+    query = (e.currentTarget as HTMLInputElement).value
+    editing = true; active = 0
+    if (!open) openPanel()
+  }
+  function onFocus() { editing = true; query = selected?.label ?? ''; openPanel() }
+  function onKeydown(e: KeyboardEvent) {
+    if (disabled()) return
+    if (!open && e.key === 'ArrowDown') { e.preventDefault(); editing = true; openPanel(); return }
+    if (e.key === 'ArrowDown') { e.preventDefault(); active = Math.min(active + 1, filtered.length - 1) }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); active = Math.max(active - 1, 0) }
+    else if (e.key === 'Enter') { e.preventDefault(); pick(filtered[active]) }
+    else if (e.key === 'Escape') { e.preventDefault(); close() }
+  }
+
+  return {
+    /** Panel open state. */
+    get open() { return open },
+    /** Highlighted option index into `filtered`. */
+    get activeIndex() { return active },
+    /** True while the user is typing a filter query. */
+    get editing() { return editing },
+    /** Current filter query text. */
+    get query() { return query },
+    /** Options after the live substring filter. */
+    get filtered() { return filtered },
+    /** The option matching the controlled value, if any. */
+    get selected() { return selected },
+    /** Text shown in the field (query while editing, else the selected label). */
+    get shownText() { return shownText },
+    /** Controlled value. */
+    get value() { return config.value() },
+    /** id of the listbox element (matches inputProps `aria-controls`). */
+    listId,
+    isActive: (i: number) => i === active,
+    isSelected: (o: ListOption) => o.value === config.value(),
+    setActive,
+    openPanel,
+    close,
+    toggle,
+    pick,
+    onInput,
+    onFocus,
+    onKeydown,
+    /** Spread onto the editable <input>. */
+    inputProps: () => ({
+      role: 'combobox' as const,
+      'aria-expanded': open,
+      'aria-controls': listId,
+      'aria-autocomplete': 'list' as const,
+      'aria-label': config.ariaLabel?.(),
+      value: shownText,
+      disabled: disabled(),
+      oninput: onInput,
+      onfocus: onFocus,
+      onkeydown: onKeydown,
+    }),
+    /** Spread onto the chevron/toggle <button>. */
+    triggerProps: () => ({
+      type: 'button' as const,
+      tabindex: -1,
+      'aria-label': 'Toggle',
+      disabled: disabled(),
+      onclick: toggle,
+    }),
+    /** Spread onto the listbox container. */
+    listboxProps: () => ({
+      id: listId,
+      role: 'listbox' as const,
+    }),
+    /** Spread onto the option at `index` (index into `filtered`). */
+    optionProps: (index: number) => {
+      const o = filtered[index]
+      return {
+        role: 'option' as const,
+        id: optionId(index),
+        tabindex: -1,
+        'aria-selected': o ? o.value === config.value() : false,
+        'aria-disabled': o?.disabled,
+        'data-idx': index,
+        onclick: () => pick(o),
+        onpointermove: () => { if (o && !o.disabled) active = index },
+      }
+    },
+  }
+}
+
+export type Combobox = ReturnType<typeof createCombobox>

package/src/createCountryInput.svelte.ts

@@ -0,0 +1,126 @@
+/**
+ * createCountryInput - the HEADLESS core behind <SvCountryInput>: a searchable
+ * country picker (search by name, dial code, or ISO code; roving active index +
+ * keyboard) that emits the ISO 3166-1 alpha-2 code. Exposed as **prop-getters**
+ * you spread onto YOUR OWN markup. No styles/DOM/portal - those stay in the
+ * styled component.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createCountryInput, flagEmoji } from '@svgrid/grid'
+ *   let value = $state<string | null>(null)
+ *   const ci = createCountryInput({ value: () => value, onChange: (c) => (value = c) })
+ * </script>
+ * <button {...ci.triggerProps()}>{ci.selected?.name ?? 'Select'}</button>
+ * {#if ci.open}
+ *   <input {...ci.searchProps()} />
+ *   <ul {...ci.listboxProps()}>
+ *     {#each ci.filtered as c, i (c.code)}<li {...ci.optionProps(i)}>{c.name}</li>{/each}
+ *   </ul>
+ * {/if}
+ * ```
+ */
+import { COUNTRIES, COUNTRY_BY_CODE, type Country } from './countries'
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type CountryInputConfig = {
+  value: () => string | null
+  onChange?: (code: string) => void
+  disabled?: () => boolean
+  ariaLabel?: () => string | undefined
+  /** DOM focus hook provided by the renderer; the core never touches the DOM. */
+  focusTrigger?: () => void
+}
+
+export function createCountryInput(config: CountryInputConfig) {
+  const disabled = () => config.disabled?.() ?? false
+
+  let open = $state(false)
+  let query = $state('')
+  let active = $state(0)
+
+  const selected = $derived(config.value() ? COUNTRY_BY_CODE.get(config.value()!) ?? null : null)
+  const filtered = $derived<Country[]>(
+    query.trim() === ''
+      ? COUNTRIES
+      : COUNTRIES.filter(
+          (c) =>
+            c.name.toLowerCase().includes(query.toLowerCase()) ||
+            c.dial.includes(query) ||
+            c.code.toLowerCase() === query.toLowerCase(),
+        ),
+  )
+
+  function openPanel() { if (disabled() || open) return; open = true; query = ''; active = 0 }
+  function close() { open = false; config.focusTrigger?.() }
+  function toggle() { if (open) { open = false } else { openPanel() } }
+  function pick(code: string) { config.onChange?.(code); open = false; config.focusTrigger?.() }
+  function setQuery(v: string) { query = v; active = 0 }
+  function onSearchInput(e: Event) { setQuery((e.currentTarget as HTMLInputElement).value) }
+  function onKeydown(e: KeyboardEvent) {
+    if (!open) return
+    if (e.key === 'ArrowDown') { e.preventDefault(); active = Math.min(active + 1, filtered.length - 1) }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); active = Math.max(active - 1, 0) }
+    else if (e.key === 'Enter') { e.preventDefault(); const c = filtered[active]; if (c) pick(c.code) }
+    else if (e.key === 'Escape') { e.preventDefault(); close() }
+  }
+
+  return {
+    /** Panel open state. */
+    get open() { return open },
+    /** Highlighted country index into `filtered`. */
+    get activeIndex() { return active },
+    /** Current search query. */
+    get query() { return query },
+    /** Countries after the current search filter. */
+    get filtered() { return filtered },
+    /** The selected country, if any. */
+    get selected() { return selected },
+    /** Controlled value (ISO alpha-2 code). */
+    get value() { return config.value() },
+    isActive: (i: number) => i === active,
+    isSelected: (code: string) => code === config.value(),
+    setActive: (i: number) => { active = i },
+    setQuery,
+    openPanel,
+    close,
+    toggle,
+    pick,
+    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,
+    }),
+    /** Spread onto the search <input> inside the panel. */
+    searchProps: () => ({
+      type: 'text' as const,
+      value: query,
+      'aria-label': 'Search countries',
+      oninput: onSearchInput,
+      onkeydown: onKeydown,
+    }),
+    /** Spread onto the listbox container. */
+    listboxProps: () => ({
+      role: 'listbox' as const,
+    }),
+    /** Spread onto the country option at `index` (index into `filtered`). */
+    optionProps: (index: number) => {
+      const c = filtered[index]
+      return {
+        role: 'option' as const,
+        tabindex: -1,
+        'aria-selected': c ? c.code === config.value() : false,
+        'data-idx': index,
+        onclick: () => { if (c) pick(c.code) },
+        onpointermove: () => { active = index },
+      }
+    },
+  }
+}
+
+export type CountryInput = ReturnType<typeof createCountryInput>

package/src/createDateTimePicker.svelte.ts

@@ -0,0 +1,216 @@
+/**
+ * createDateTimePicker - the HEADLESS core behind <SvDateTimePicker>: a
+ * runes-based state machine for a masked date-time field (format/parse via the
+ * ./datetime token engine, min/max clamping, nullable clear, spin-button
+ * stepping) plus the dropdown's open/tab state and the calendar/time-picker
+ * wiring. The render-only concerns - the portalled popover positioning, DOM
+ * refs, outside-click + reposition listeners - stay in the styled component.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createDateTimePicker } from '@svgrid/grid'
+ *   let value = $state<Date | null>(new Date())
+ *   const dtp = createDateTimePicker({ value: () => value, onChange: (d) => (value = d) })
+ * </script>
+ * <input bind:value={dtp.text} {...dtp.inputProps()} />
+ * ```
+ */
+import { formatDate, parseDate } from './datetime/date-format'
+import { toDate, clampDate, withTime, startOfDay, type DateLike } from './datetime/date-core'
+
+export type DateTimeValue = Date | string | number | null
+export type DropDownDisplayMode = 'both' | 'calendar' | 'time'
+export type DateTimeTab = 'date' | 'time'
+
+/** Reactive inputs are getters; callbacks are closures. */
+export type DateTimePickerConfig = {
+  value: () => DateTimeValue
+  onChange?: (value: Date | null) => void
+  /** Fired when the value is finalized (Enter, blur, or a single-date pick). */
+  onCommit?: (value: Date | null) => void
+  /** Fired on Escape / dismiss without committing. */
+  onCancel?: () => void
+  formatString?: () => string
+  min?: () => DateLike | null
+  max?: () => DateLike | null
+  nullable?: () => boolean
+  locale?: () => string
+  dropDownDisplayMode?: () => DropDownDisplayMode
+  spinButtons?: () => boolean
+  stepMinutes?: () => number
+  disabled?: () => boolean
+  readonly?: () => boolean
+}
+
+const defaultLocale = () => (typeof navigator !== 'undefined' ? navigator.language : 'en-US')
+
+export function createDateTimePicker(config: DateTimePickerConfig) {
+  const formatString = () => config.formatString?.() ?? 'yyyy-MM-dd HH:mm'
+  const nullable = () => config.nullable?.() ?? true
+  const locale = () => config.locale?.() ?? defaultLocale()
+  const dropDownDisplayMode = () => config.dropDownDisplayMode?.() ?? 'both'
+  const spinButtons = () => config.spinButtons?.() ?? false
+  const stepMinutes = () => config.stepMinutes?.() ?? 1
+  const isDisabled = () => config.disabled?.() ?? false
+  const isReadonly = () => config.readonly?.() ?? false
+
+  const isInteractive = $derived(!isDisabled() && !isReadonly())
+  const minD = $derived(toDate(config.min?.() ?? null))
+  const maxD = $derived(toDate(config.max?.() ?? null))
+
+  let current = $state<Date | null>(null)
+  let text = $state('')
+  let lastKey = '￿'
+  $effect(() => {
+    const d = toDate(config.value() as DateLike)
+    const key = d ? String(d.getTime()) : 'null'
+    if (key !== lastKey) {
+      lastKey = key
+      current = d
+      text = d ? formatDate(d, formatString(), locale()) : ''
+    }
+  })
+
+  // --- Dropdown (open/tab) state; positioning stays in the component ----------
+  let open = $state(false)
+  let tab = $state<DateTimeTab>('date')
+
+  const showDateTab = $derived(dropDownDisplayMode() !== 'time')
+  const showTimeTab = $derived(dropDownDisplayMode() !== 'calendar')
+
+  // --- Commit helpers --------------------------------------------------------
+  function commit(next: Date | null) {
+    const clamped = next ? clampDate(next, minD, maxD) : null
+    current = clamped
+    lastKey = clamped ? String(clamped.getTime()) : 'null'
+    text = clamped ? formatDate(clamped, formatString(), locale()) : ''
+    config.onChange?.(clamped)
+  }
+
+  function commitFromText() {
+    const raw = text.trim()
+    if (!raw) {
+      if (nullable()) commit(null)
+      else text = current ? formatDate(current, formatString(), locale()) : ''
+      return
+    }
+    const parsed = parseDate(raw, formatString(), locale(), 2029, current ?? new Date())
+    if (parsed) commit(parsed)
+    else text = current ? formatDate(current, formatString(), locale()) : '' // revert on bad input
+  }
+
+  function bump(deltaMin: number) {
+    const base = current ?? new Date()
+    commit(new Date(base.getTime() + deltaMin * 60000))
+  }
+
+  // --- Sub-picker wiring -----------------------------------------------------
+  function onCalendarChange(dates: Date[]) {
+    const day = dates[0]
+    if (!day) return
+    commit(withTime(day, current ?? startOfDay(day)))
+    // Date-only picker: a single pick finalizes the value.
+    if (dropDownDisplayMode() === 'calendar') { open = false; config.onCommit?.(current) }
+    else if (dropDownDisplayMode() === 'both') tab = 'time'
+  }
+  function onTimeChange(t: Date) {
+    const base = current ?? new Date()
+    commit(withTime(base, t))
+  }
+
+  // --- Dropdown control ------------------------------------------------------
+  function openPanel() {
+    if (!isInteractive || open) return
+    tab = dropDownDisplayMode() === 'time' ? 'time' : 'date'
+    open = true
+  }
+  function closePanel() { open = false }
+  function toggle() { (open ? closePanel : openPanel)() }
+  function setTab(t: DateTimeTab) { tab = t }
+
+  function onInputKeydown(e: KeyboardEvent) {
+    if (e.key === 'Enter') { e.preventDefault(); commitFromText(); closePanel(); config.onCommit?.(current) }
+    else if (e.key === 'Escape') { closePanel(); config.onCancel?.() }
+    else if (e.key === 'ArrowDown' && (e.altKey || !text)) { e.preventDefault(); openPanel() }
+    else if (spinButtons() && e.key === 'ArrowUp') { e.preventDefault(); bump(stepMinutes()) }
+    else if (spinButtons() && e.key === 'ArrowDown') { e.preventDefault(); bump(-stepMinutes()) }
+  }
+
+  return {
+    // --- Reactive state -------------------------------------------------------
+    get current() { return current },
+    get text() { return text },
+    set text(v: string) { text = v },
+    get open() { return open },
+    get tab() { return tab },
+    get isInteractive() { return isInteractive },
+    get showDateTab() { return showDateTab },
+    get showTimeTab() { return showTimeTab },
+
+    // --- Actions --------------------------------------------------------------
+    commit,
+    commitFromText,
+    bump,
+    onCalendarChange,
+    onTimeChange,
+    openPanel,
+    closePanel,
+    toggle,
+    setTab,
+    onInputKeydown,
+
+    // --- Prop-getters ---------------------------------------------------------
+    /** The text field: masked value round-trips through the token engine. Spread
+     *  alongside `bind:value={dtp.text}`. */
+    inputProps() {
+      return {
+        type: 'text' as const,
+        disabled: isDisabled(),
+        readonly: isReadonly(),
+        onblur: commitFromText,
+        onkeydown: onInputKeydown,
+      }
+    },
+    /** The calendar-toggle button. */
+    toggleProps() {
+      return {
+        type: 'button' as const,
+        'aria-label': 'Open picker',
+        'aria-haspopup': 'dialog' as const,
+        'aria-expanded': open,
+        disabled: !isInteractive,
+        tabindex: -1,
+        onclick: toggle,
+      }
+    },
+    /** The inline clear (x) button (nullable values). */
+    clearProps() {
+      return {
+        type: 'button' as const,
+        'aria-label': 'Clear',
+        onclick: () => commit(null),
+      }
+    },
+    /** A spin (increment/decrement) button that steps by `stepMinutes`. */
+    spinProps(dir: 1 | -1) {
+      return {
+        type: 'button' as const,
+        tabindex: -1,
+        'aria-label': dir === 1 ? 'Increment' : 'Decrement',
+        disabled: !isInteractive,
+        onclick: () => bump(dir * stepMinutes()),
+      }
+    },
+    /** A DATE / TIME tab button. */
+    tabProps(which: DateTimeTab) {
+      return {
+        type: 'button' as const,
+        role: 'tab' as const,
+        'aria-selected': tab === which,
+        onclick: () => setTab(which),
+      }
+    },
+  }
+}
+
+export type DateTimePicker = ReturnType<typeof createDateTimePicker>

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>