@surstromming/combobox 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evgeniy Mnatsakanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @surstromming/combobox
+
+A [`Select`](../select) with a search field — for lists too long to scan.
+Data-driven: pass options, get the whole control.
+
+## Dependency graph
+
+```mermaid
+graph LR
+  combobox["@surstromming/combobox"]
+  design["@surstromming/design"]
+  icon["@surstromming/icon"]
+  input["@surstromming/input"]
+  popover["@surstromming/popover"]
+  scroll_area["@surstromming/scroll-area"]
+  util["@surstromming/util"]
+  combobox --> design
+  combobox --> icon
+  combobox --> input
+  input --> design
+  combobox --> popover
+  popover --> design
+  popover --> scroll_area
+  scroll_area --> design
+  scroll_area --> util
+```
+
+## Usage
+
+```vue
+<template>
+  <Combobox v-model="framework" :options="frameworks" placeholder="Pick a framework" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Combobox, type ComboboxOption } from '@surstromming/combobox'
+
+const framework = ref('')
+const frameworks: ComboboxOption[] = [
+  { label: 'Vue', value: 'vue' },
+  { label: 'Svelte', value: 'svelte' },
+  { label: 'Angular', value: 'angular', disabled: true },
+]
+</script>
+```
+
+## Props
+
+| Prop                | Type               | Default          | Notes                             |
+| ------------------- | ------------------ | ---------------- | --------------------------------- |
+| `v-model`           | `string`           | —                | The selected `value`               |
+| `options`           | `ComboboxOption[]` | — (required)     | `{ label, value, disabled? }`      |
+| `placeholder`       | `string`           | `Select…`        | Trigger text before a choice       |
+| `searchPlaceholder` | `string`           | `Search…`        |                                    |
+| `emptyText`         | `string`           | `Nothing found.` | Shown when nothing matches         |
+| `disabled`          | `boolean`          | `false`          |                                    |
+
+`id` · `aria-*` fall through **to the trigger button** (`inheritAttrs: false`).
+
+## Anatomy
+
+```
+Popover
+  ├─ button.trigger        // value + up/down chevrons
+  ├─ div.search > Input    // focused on open; cleared on close
+  └─ ul.list[role=listbox]
+       ├─ li.option        // filtered by the query
+       └─ li.empty         // emptyText
+```
+
+## Behavior & keyboard
+
+| Key                | Action                                             |
+| ------------------ | -------------------------------------------------- |
+| `↓` / `Enter` / `Space` (trigger) | Open                                |
+| `↓` / `↑` (search) | Move the active option (skips disabled)             |
+| `Enter` (search)   | Pick the active option                              |
+| `Escape`           | Close (from `Popover`)                              |
+| outside click      | Close (from `Popover`)                              |
+
+- Opening **focuses the search field** — otherwise it's a select with extra
+  steps. Closing clears the query, so the next open starts fresh.
+- Filtering is a case-insensitive substring match on `label`. Re-filtering
+  resets the highlight to the first match, so `Enter` always picks what you're
+  looking at.
+
+## Notes
+
+- Filtering is client-side over the `options` you pass. For a remote search,
+  keep the query in your own state, refetch, and hand the new array back in —
+  the component re-renders from it.
+- Single-select only, like `Select`.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@surstromming/combobox",
+  "version": "0.1.0",
+  "description": "Select with a search field.",
+  "license": "MIT",
+  "author": "Evgeniy Mnatsakanov <evgeniy.mnatsakanov@gmail.com>",
+  "homepage": "https://github.com/hackteck/surstromming/tree/main/packages/combobox#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hackteck/surstromming.git",
+    "directory": "packages/combobox"
+  },
+  "bugs": "https://github.com/hackteck/surstromming/issues",
+  "keywords": [
+    "vue",
+    "vue3",
+    "component-library",
+    "design-system",
+    "ui",
+    "scss",
+    "css-modules",
+    "shadcn",
+    "combobox"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "**/*.scss",
+    "**/*.css"
+  ],
+  "files": [
+    "src"
+  ],
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@surstromming/design": "^0.1.0",
+    "@surstromming/icon": "^0.1.0",
+    "@surstromming/input": "^0.1.0",
+    "@surstromming/popover": "^0.1.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Combobox.vue

@@ -0,0 +1,211 @@
+<template>
+  <Popover v-model:open="open">
+    <template #trigger>
+      <button
+        :class="$style.trigger"
+        type="button"
+        role="combobox"
+        aria-haspopup="listbox"
+        :aria-expanded="open"
+        :disabled="disabled"
+        v-bind="$attrs"
+        @click="toggle"
+        @keydown="onTriggerKeydown"
+      >
+        <span :class="valueClasses">{{ valueLabel }}</span>
+        <Icon :icon="ChevronsUpDown" :size="16" />
+      </button>
+    </template>
+
+    <div :class="$style.search">
+      <Input
+        ref="search"
+        v-model="query"
+        type="search"
+        :placeholder="searchPlaceholder"
+        @keydown="onSearchKeydown"
+      />
+    </div>
+
+    <ul ref="list" :class="$style.list" role="listbox">
+      <li
+        v-for="(option, index) in matches"
+        :key="option.value"
+        :class="optionClasses(option, index)"
+        role="option"
+        :aria-selected="option.value === model"
+        @click="select(option)"
+        @mousemove="activeIndex = index"
+      >
+        {{ option.label }}
+        <Icon v-if="option.value === model" :icon="Check" :size="16" />
+      </li>
+      <li v-if="!matches.length" :class="$style.empty">{{ emptyText }}</li>
+    </ul>
+  </Popover>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref, useCssModule, useTemplateRef, watch } from 'vue'
+import { Icon } from '@surstromming/icon'
+import { Input } from '@surstromming/input'
+import { Popover } from '@surstromming/popover'
+import { Check, ChevronsUpDown } from 'lucide'
+import type { ComboboxOption } from './index'
+
+// The trigger is the focusable control — id/aria belong on it, not the wrapper.
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(
+  defineProps<{
+    options: ComboboxOption[]
+    placeholder?: string
+    searchPlaceholder?: string
+    emptyText?: string
+    disabled?: boolean
+  }>(),
+  {
+    placeholder: 'Select…',
+    searchPlaceholder: 'Search…',
+    emptyText: 'Nothing found.',
+  },
+)
+
+const model = defineModel<string>()
+
+const open = ref(false)
+const query = ref('')
+const activeIndex = ref(0)
+const search = useTemplateRef<InstanceType<typeof Input>>('search')
+const list = useTemplateRef<HTMLElement>('list')
+
+const selected = computed(() => props.options.find((option) => option.value === model.value))
+const valueLabel = computed(() => selected.value?.label ?? props.placeholder)
+
+const matches = computed(() => {
+  const needle = query.value.trim().toLowerCase()
+  if (!needle) return props.options
+  return props.options.filter((option) => option.label.toLowerCase().includes(needle))
+})
+
+// Every keystroke re-filters, so the old index would point at the wrong option.
+watch(matches, () => {
+  activeIndex.value = 0
+})
+
+// A highlight you can't see is worse than none — follow it in a long list.
+watch(activeIndex, async (index) => {
+  if (!open.value || index < 0) return
+  await nextTick()
+  list.value?.children[index]?.scrollIntoView({ block: 'nearest' })
+})
+
+// A combobox that doesn't focus its search field is just a select with extra steps.
+watch(open, async (isOpen) => {
+  if (!isOpen) {
+    query.value = ''
+    return
+  }
+  await nextTick()
+  search.value?.focus()
+})
+
+const toggle = () => {
+  open.value = !open.value
+}
+
+const select = (option: ComboboxOption) => {
+  model.value = option.value
+  open.value = false
+}
+
+// Skips disabled options; stops at the ends rather than wrapping.
+const move = (step: number) => {
+  const last = matches.value.length - 1
+  let next = activeIndex.value
+  for (let i = next + step; i >= 0 && i <= last; i += step) {
+    if (!matches.value[i].disabled) {
+      next = i
+      break
+    }
+  }
+  activeIndex.value = next
+}
+
+const onTriggerKeydown = (event: KeyboardEvent) => {
+  if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault()
+    open.value = true
+  }
+}
+
+const onSearchKeydown = (event: KeyboardEvent) => {
+  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+    event.preventDefault() // don't move the text caret
+    move(event.key === 'ArrowDown' ? 1 : -1)
+    return
+  }
+
+  if (event.key === 'Enter') {
+    event.preventDefault()
+    const active = matches.value[activeIndex.value]
+    if (active) select(active)
+  }
+}
+
+const $style = useCssModule()
+const valueClasses = computed(() => [$style.value, { [$style.isPlaceholder]: !selected.value }])
+const optionClasses = (option: ComboboxOption, index: number) => [
+  $style.option,
+  { [$style.isActive]: index === activeIndex.value, [$style.isDisabled]: option.disabled },
+]
+</script>
+
+<style module lang="scss">
+@use '@surstromming/design' as design;
+@use 'css/combobox-list';
+
+.trigger {
+  @include design.field;
+
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: design.spacing(2);
+  width: 100%;
+  height: design.spacing(9);
+  padding-inline: design.spacing(3);
+  font-size: 0.875rem;
+  white-space: nowrap;
+  text-align: start;
+  cursor: pointer;
+
+  // The chevrons are affordance, not content.
+  svg {
+    flex-shrink: 0;
+    color: design.color(muted-foreground);
+    pointer-events: none;
+  }
+
+  &:hover {
+    #{design.$darkThemeSelector} & {
+      background-color: design.with-alpha(input, 50%);
+    }
+  }
+}
+
+.value {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.isPlaceholder {
+  color: design.color(muted-foreground);
+}
+
+.search {
+  border-bottom: 1px solid design.color(border);
+  padding: design.spacing(1);
+}
+</style>

package/src/css/combobox-list.scss

@@ -0,0 +1,38 @@
+@use '@surstromming/design' as design;
+
+.list {
+  margin: 0;
+  padding: design.spacing(1);
+  list-style: none;
+}
+
+.option {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: design.spacing(2);
+  border-radius: design.radius(sm);
+  padding: design.spacing(2);
+  font-size: 0.875rem;
+  cursor: pointer;
+  user-select: none;
+}
+
+// Pointer and keyboard share one highlight — the active option is the one
+// Enter would pick, whether the mouse or the arrow keys put it there.
+.isActive {
+  background-color: design.color(accent);
+  color: design.color(accent-foreground);
+}
+
+.isDisabled {
+  pointer-events: none;
+  opacity: 0.5;
+}
+
+.empty {
+  padding: design.spacing(4) design.spacing(2);
+  color: design.color(muted-foreground);
+  font-size: 0.875rem;
+  text-align: center;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export interface ComboboxOption {
+  label: string
+  value: string
+  disabled?: boolean
+}
+
+export { default as Combobox } from './Combobox.vue'