@svgrid/grid 2.1.22 → 2.2.0

package/src/createCombobox.svelte.ts

@@ -1,179 +1,179 @@
-/**
- * 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'
-import { editorAria, type EditorAriaState } from './editor-contract'
-
-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
-  /** Filter the options locally by the query. Set false for server-side search. */
-  localFilter?: () => boolean
-  /** DOM focus hooks provided by the renderer; the core itself never touches the DOM. */
-  focusInput?: () => void
-  blurInput?: () => void
-  // Editor contract (ARIA + validation) - folded into inputProps().
-  id?: () => string | undefined
-  invalid?: () => boolean
-  required?: () => boolean
-  error?: () => string | undefined
-  hint?: () => string | undefined
-}
-
-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 localFilter = () => config.localFilter?.() ?? true
-  const selected = $derived(opts().find((o) => o.value === config.value()) ?? null)
-  const filtered = $derived(editing && localFilter() ? 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}`
-
-  const ariaState = (): EditorAriaState => ({
-    id: config.id?.(),
-    invalid: config.invalid?.(),
-    required: config.required?.(),
-    error: config.error?.(),
-    hint: config.hint?.(),
-    ariaLabel: config.ariaLabel?.(),
-  })
-
-  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: () => ({
-      id: config.id?.(),
-      role: 'combobox' as const,
-      'aria-expanded': open,
-      'aria-controls': listId,
-      'aria-autocomplete': 'list' as const,
-      'aria-activedescendant': open && filtered[active] ? optionId(active) : undefined,
-      ...editorAria(ariaState()),
-      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>
+/**
+ * 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'
+import { editorAria, type EditorAriaState } from './editor-contract'
+
+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
+  /** Filter the options locally by the query. Set false for server-side search. */
+  localFilter?: () => boolean
+  /** DOM focus hooks provided by the renderer; the core itself never touches the DOM. */
+  focusInput?: () => void
+  blurInput?: () => void
+  // Editor contract (ARIA + validation) - folded into inputProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
+}
+
+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 localFilter = () => config.localFilter?.() ?? true
+  const selected = $derived(opts().find((o) => o.value === config.value()) ?? null)
+  const filtered = $derived(editing && localFilter() ? 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}`
+
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
+  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: () => ({
+      id: config.id?.(),
+      role: 'combobox' as const,
+      'aria-expanded': open,
+      'aria-controls': listId,
+      'aria-autocomplete': 'list' as const,
+      'aria-activedescendant': open && filtered[active] ? optionId(active) : undefined,
+      ...editorAria(ariaState()),
+      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/createCommand.svelte.ts

@@ -0,0 +1,125 @@
+/**
+ * createCommand - the HEADLESS core behind <SvCommand> (the ⌘K palette): the
+ * fuzzy-filtered result list, roving active index, run/close, the global toggle
+ * hotkey, and the WAI-ARIA combobox wiring (activedescendant) - as prop-getters
+ * you spread onto your own input/list/option markup. The overlay lifecycle
+ * (focus-trap + scroll-lock + dismissal) is a separate concern; pair this with
+ * `createOverlay`. Runes-based, like `createListbox`.
+ */
+import type { CommandItem } from './ui-app.types'
+import { fuzzyScore } from './fuzzy'
+import { nextEditorId } from './editor-contract'
+
+export type CommandConfig = {
+  commands: () => ReadonlyArray<CommandItem>
+  /** Whether the palette is open (used to reset query/active on open). */
+  open: () => boolean
+  onRun?: (cmd: CommandItem) => void
+  /** Close the palette (a command ran, or requested by the input). */
+  onClose?: () => void
+  /** Toggle open/closed - fired by the global hotkey. */
+  onToggleOpen?: () => void
+  /** Global toggle hotkey (Cmd/Ctrl + key). `false` disables it. Default 'mod+k'. */
+  hotkey?: () => 'mod+k' | 'mod+p' | false
+  /** DOM hook to scroll the newly-active option into view. */
+  scrollActiveIntoView?: (index: number) => void
+}
+
+export function createCommand(config: CommandConfig) {
+  const id = nextEditorId('sv-cmd')
+  const listId = `${id}-list`
+  const optionId = (i: number) => `${id}-opt-${i}`
+
+  let query = $state('')
+  let active = $state(0)
+
+  const results = $derived.by(() => {
+    const q = query.trim()
+    const list = config.commands().filter((c) => !c.disabled)
+    if (!q) return list
+    return list
+      .map((c) => ({ c, s: fuzzyScore(`${c.label} ${c.keywords ?? ''} ${c.group ?? ''}`, q) }))
+      .filter((x) => x.s !== null)
+      .sort((a, b) => (b.s as number) - (a.s as number))
+      .map((x) => x.c)
+  })
+
+  function run(cmd: CommandItem | undefined) {
+    if (!cmd || cmd.disabled) return
+    config.onClose?.()
+    config.onRun?.(cmd)
+    cmd.onRun?.()
+  }
+  function move(delta: number) {
+    const n = results.length
+    if (!n) return
+    active = (active + delta + n) % n
+    config.scrollActiveIntoView?.(active)
+  }
+  function onInputKeydown(e: KeyboardEvent) {
+    if (e.key === 'ArrowDown') { e.preventDefault(); move(1) }
+    else if (e.key === 'ArrowUp') { e.preventDefault(); move(-1) }
+    else if (e.key === 'Enter') { e.preventDefault(); run(results[active]) }
+    // Escape + outside-click are owned by the overlay/dismissable layer.
+  }
+
+  // Reset the active row as the query changes.
+  $effect(() => { void query; active = 0 })
+  // Reset query + active each time the palette opens.
+  $effect(() => { if (config.open()) { query = ''; active = 0 } })
+  // Global toggle hotkey.
+  $effect(() => {
+    const hk = config.hotkey?.() ?? 'mod+k'
+    if (!hk) return
+    const key = hk === 'mod+p' ? 'p' : 'k'
+    const onKey = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === key) {
+        e.preventDefault()
+        config.onToggleOpen?.()
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  })
+
+  return {
+    get query() { return query },
+    set query(v: string) { query = v },
+    get active() { return active },
+    get results() { return results },
+    isActive: (i: number) => i === active,
+    move,
+    run,
+    /** Arrow/Enter handler - attach to the panel (catches events bubbled from the
+     *  input) so keys work whether dispatched on the input or the dialog. */
+    onKeydown: onInputKeydown,
+    /** Id of the list element (for aria-controls). */
+    listId,
+    /** Id of the option at `i` (for aria-activedescendant + item id). */
+    optionId,
+    /** Spread onto the search `<input>`. */
+    inputProps: () => ({
+      role: 'combobox' as const,
+      'aria-expanded': true as const,
+      'aria-controls': listId,
+      'aria-activedescendant': results[active] ? optionId(active) : undefined,
+      value: query,
+      oninput: (e: Event) => { query = (e.currentTarget as HTMLInputElement).value },
+      // Arrow/Enter is handled on the panel (see `onKeydown`) via bubbling, so it
+      // works for both input-dispatched and panel-dispatched key events.
+    }),
+    /** Spread onto the `<ul>` list. */
+    listProps: () => ({ id: listId, role: 'listbox' as const }),
+    /** Spread onto the option element at `i`. */
+    optionProps: (i: number) => ({
+      id: optionId(i),
+      'data-idx': i,
+      role: 'option' as const,
+      'aria-selected': i === active,
+      onpointermove: () => { active = i },
+      onclick: () => run(results[i]),
+    }),
+  }
+}
+
+export type Command = ReturnType<typeof createCommand>