@surstromming/select 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/select
+
+Pick one option from a list. Data-driven: pass an array of options, get the
+whole control — a styled trigger plus a listbox in a [`Popover`](../popover).
+
+## Dependency graph
+
+```mermaid
+graph LR
+  select["@surstromming/select"]
+  design["@surstromming/design"]
+  icon["@surstromming/icon"]
+  popover["@surstromming/popover"]
+  scroll_area["@surstromming/scroll-area"]
+  util["@surstromming/util"]
+  select --> design
+  select --> icon
+  select --> popover
+  popover --> design
+  popover --> scroll_area
+  scroll_area --> design
+  scroll_area --> util
+```
+
+## Usage
+
+```vue
+<template>
+  <Label id="fruit-label">Fruit</Label>
+  <Select v-model="fruit" :options="fruits" aria-labelledby="fruit-label" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Select, type SelectOption } from '@surstromming/select'
+
+const fruit = ref('')
+const fruits: SelectOption[] = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Durian', value: 'durian', disabled: true },
+]
+</script>
+```
+
+## Props
+
+| Prop          | Type              | Default     | Notes                                  |
+| ------------- | ----------------- | ----------- | -------------------------------------- |
+| `v-model`     | `string`          | —           | The selected `value`                    |
+| `options`     | `SelectOption[]`  | — (required) | `{ label, value, disabled? }`          |
+| `placeholder` | `string`          | `Select…`   | Shown, dimmed, until something is picked |
+| `size`        | `sm \| md \| lg`  | `md`        | Heights match `Input` and `Button`      |
+| `disabled`    | `boolean`         | `false`     |                                         |
+
+`id` · `aria-*` fall through **to the trigger button** (`inheritAttrs: false`)
+— it's the focusable control.
+
+## Anatomy
+
+```
+Popover
+  ├─ button.trigger    // value + chevron; the focusable control
+  └─ ul.list[role=listbox]
+       └─ li.option[role=option]   // .isActive highlight, check on the selected one
+```
+
+## Keyboard
+
+| Key           | Action                                              |
+| ------------- | --------------------------------------------------- |
+| `↓` / `↑`     | Open; then move the active option (skips disabled)   |
+| `Enter` / `Space` | Open; then pick the active option                |
+| `Escape`      | Close (from `Popover`)                               |
+| outside click | Close (from `Popover`)                               |
+
+Opening highlights the **current** selection, so `↓` moves from where you are.
+Focus stays on the trigger the whole time — nothing to restore on close.
+
+## Tokens
+
+Trigger mirrors [`Input`](../input): `input` border, `radius(md)`, `ring` focus
+ring, `destructive` when `aria-invalid`, dark `input` @ 30% background. Panel
+uses `popover` / `border`; the active option uses `accent`.
+
+## Notes
+
+- Not a native `<select>`: the native one can't be styled to match (its dropdown
+  is drawn by the OS), which is the entire reason this component exists. The
+  trade-off is that we own the keyboard behaviour — see the table above.
+- Single-select only. Multi-select needs chips, a different value type, and a
+  different keyboard model.
+- Need to filter a long list? That's [`Combobox`](../combobox).

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@surstromming/select",
+  "version": "0.1.0",
+  "description": "Pick one option from a list.",
+  "license": "MIT",
+  "author": "Evgeniy Mnatsakanov <evgeniy.mnatsakanov@gmail.com>",
+  "homepage": "https://github.com/hackteck/surstromming/tree/main/packages/select#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hackteck/surstromming.git",
+    "directory": "packages/select"
+  },
+  "bugs": "https://github.com/hackteck/surstromming/issues",
+  "keywords": [
+    "vue",
+    "vue3",
+    "component-library",
+    "design-system",
+    "ui",
+    "scss",
+    "css-modules",
+    "shadcn",
+    "select"
+  ],
+  "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/popover": "^0.1.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Select.vue

@@ -0,0 +1,147 @@
+<template>
+  <Popover v-model:open="open">
+    <template #trigger>
+      <button
+        :class="triggerClasses"
+        type="button"
+        role="combobox"
+        aria-haspopup="listbox"
+        :aria-expanded="open"
+        :disabled="disabled"
+        v-bind="$attrs"
+        @click="toggle"
+        @keydown="onKeydown"
+      >
+        <span :class="valueClasses">{{ valueLabel }}</span>
+        <Icon :icon="ChevronDown" :size="16" />
+      </button>
+    </template>
+
+    <ul ref="list" :class="$style.list" role="listbox">
+      <li
+        v-for="(option, index) in options"
+        :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>
+    </ul>
+  </Popover>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref, useCssModule, useTemplateRef, watch } from 'vue'
+import { Icon } from '@surstromming/icon'
+import { Popover } from '@surstromming/popover'
+import { Check, ChevronDown } from 'lucide'
+import type { SelectOption, SelectSize } from './index'
+
+// The trigger is the focusable control — id/aria belong on it, not the wrapper.
+defineOptions({ inheritAttrs: false })
+
+const props = withDefaults(
+  defineProps<{
+    options: SelectOption[]
+    placeholder?: string
+    size?: SelectSize
+    disabled?: boolean
+  }>(),
+  { placeholder: 'Select…', size: 'md' },
+)
+
+const model = defineModel<string>()
+
+const open = ref(false)
+const activeIndex = ref(-1)
+
+const selected = computed(() => props.options.find((option) => option.value === model.value))
+const valueLabel = computed(() => selected.value?.label ?? props.placeholder)
+
+const list = useTemplateRef<HTMLElement>('list')
+
+// A highlight you can't see is worse than none — follow it in a long list.
+const revealActive = async () => {
+  if (!open.value || activeIndex.value < 0) return
+  await nextTick()
+  list.value?.children[activeIndex.value]?.scrollIntoView({ block: 'nearest' })
+}
+
+// Opening lands on the current choice, so ↓ moves from where you are. Revealing
+// it is a separate call rather than a job for the watcher below: reopening on
+// the same option doesn't change the index, so nothing would fire and a
+// selection far down a long list would open off screen.
+watch(open, (isOpen) => {
+  if (!isOpen) return
+  activeIndex.value = props.options.findIndex((o) => o.value === model.value)
+  revealActive()
+})
+
+watch(activeIndex, revealActive)
+
+const toggle = () => {
+  open.value = !open.value
+}
+
+const select = (option: SelectOption) => {
+  model.value = option.value
+  open.value = false
+}
+
+// Skips disabled options; stops at the ends rather than wrapping.
+const move = (step: number) => {
+  const last = props.options.length - 1
+  let next = activeIndex.value
+  for (let i = next + step; i >= 0 && i <= last; i += step) {
+    if (!props.options[i].disabled) {
+      next = i
+      break
+    }
+  }
+  activeIndex.value = next
+}
+
+const onKeydown = (event: KeyboardEvent) => {
+  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+    event.preventDefault() // don't scroll the page
+    if (!open.value) open.value = true
+    else move(event.key === 'ArrowDown' ? 1 : -1)
+    return
+  }
+
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault() // Space would scroll, Enter would submit the form
+    const active = props.options[activeIndex.value]
+    if (open.value && active) select(active)
+    else open.value = true
+  }
+}
+
+const $style = useCssModule()
+const triggerClasses = computed(() => [$style.trigger, $style[`size-${props.size}`]])
+const valueClasses = computed(() => [$style.value, { [$style.isPlaceholder]: !selected.value }])
+const optionClasses = (option: SelectOption, 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/select-trigger';
+@use 'css/select-list';
+
+.value {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.isPlaceholder {
+  color: design.color(muted-foreground);
+}
+</style>

package/src/css/select-list.scss

@@ -0,0 +1,31 @@
+@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;
+}

package/src/css/select-trigger.scss

@@ -0,0 +1,46 @@
+@use '@surstromming/design' as design;
+
+// Metrics mirror Input's, so a Select and an Input line up in one row.
+.trigger {
+  @include design.field;
+
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: design.spacing(2);
+  width: 100%;
+  font-size: 0.875rem;
+  white-space: nowrap;
+  text-align: start;
+  cursor: pointer;
+
+  // The chevron is affordance, not content — it shouldn't compete with the value.
+  svg {
+    flex-shrink: 0;
+    color: design.color(muted-foreground);
+    pointer-events: none;
+  }
+
+  &:hover {
+    #{design.$darkThemeSelector} & {
+      background-color: design.with-alpha(input, 50%);
+    }
+  }
+}
+
+.size {
+  &-sm {
+    height: design.spacing(8);
+    padding-inline: design.spacing(3);
+  }
+
+  &-md {
+    height: design.spacing(9);
+    padding-inline: design.spacing(3);
+  }
+
+  &-lg {
+    height: design.spacing(10);
+    padding-inline: design.spacing(4);
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export type SelectSize = 'sm' | 'md' | 'lg'
+
+export interface SelectOption {
+  label: string
+  value: string
+  disabled?: boolean
+}
+
+export { default as Select } from './Select.vue'