@surstromming/dropdown-menu 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,113 @@
+# @surstromming/dropdown-menu
+
+A menu of actions anchored to a trigger — a row's "⋯", a user menu.
+Data-driven: pass an array, wire a trigger, listen for `select`. Built on the
+[`Popover`](../popover) shell (outside-click + Escape dismissal).
+
+## Dependency graph
+
+```mermaid
+graph LR
+  dropdown_menu["@surstromming/dropdown-menu"]
+  design["@surstromming/design"]
+  icon["@surstromming/icon"]
+  popover["@surstromming/popover"]
+  scroll_area["@surstromming/scroll-area"]
+  util["@surstromming/util"]
+  dropdown_menu --> design
+  dropdown_menu --> icon
+  dropdown_menu --> popover
+  popover --> design
+  popover --> scroll_area
+  scroll_area --> design
+  scroll_area --> util
+```
+
+## Usage
+
+```vue
+<template>
+  <DropdownMenu :items="items" @select="run">
+    <template #trigger="{ toggle }">
+      <Button variant="outline" @click="toggle">Options</Button>
+    </template>
+  </DropdownMenu>
+</template>
+
+<script setup lang="ts">
+import { DropdownMenu, type DropdownMenuItem } from '@surstromming/dropdown-menu'
+import { Button } from '@surstromming/button'
+import { Pencil, Trash } from 'lucide'
+
+const items: DropdownMenuItem[] = [
+  { label: 'Edit', value: 'edit', icon: Pencil },
+  { separator: true },
+  { label: 'Delete', value: 'delete', icon: Trash, destructive: true },
+]
+
+const run = (value: string) => { /* value is 'edit' | 'delete' */ }
+</script>
+```
+
+## Props
+
+| Prop           | Type                 | Default      | Notes                                    |
+| -------------- | -------------------- | ------------ | ---------------------------------------- |
+| `items`        | `DropdownMenuItem[]` | — (required) | Options and separators, in order          |
+| `align`        | `start \| end`       | `start`      | Which trigger edge the menu lines up with |
+| `layer`        | `popover \| menu \| modal` | `popover` | From `Popover` — `menu` clears a teleported sidebar drawer |
+| `v-model:open` | `boolean`            | `false`      | Optional — the trigger toggles it          |
+
+```ts
+type DropdownMenuItem =
+  | { label: string; value: string; icon?: IconNode; disabled?: boolean; destructive?: boolean }
+  | { separator: true }
+```
+
+| Emit     | Payload | When                          |
+| -------- | ------- | ----------------------------- |
+| `select` | `value` | An item is chosen (menu closes) |
+
+## Slots
+
+| Slot      | Props            | Description                                    |
+| --------- | ---------------- | --------------------------------------------- |
+| `trigger` | `{ open, toggle }` | The anchor. Call `toggle` to open/close.      |
+
+The trigger is yours so it can be any control; add `aria-haspopup="menu"` and
+`:aria-expanded="open"` to it for the full a11y contract.
+
+## Anatomy
+
+```
+Popover
+  ├─ <slot name="trigger" />
+  └─ div.menu[role=menu]
+       ├─ button.item[role=menuitem]   // icon + label; .isDestructive
+       └─ div.separator[role=separator]
+```
+
+## Keyboard
+
+| Key           | Action                                              |
+| ------------- | --------------------------------------------------- |
+| `↓` / `↑`     | Move between items (wraps, skips separators/disabled) |
+| `Home` / `End`| First / last item                                    |
+| `Enter` / `Space` | Fire the focused item (native button)            |
+| `Escape`      | Close (from `Popover`)                               |
+| `Tab`         | Close and move on — a menu isn't a tab stop          |
+| outside click | Close (from `Popover`)                               |
+
+Opening moves focus to the first item; closing returns focus to the trigger,
+so a keyboard user never loses their place.
+
+## Tokens
+
+Panel from `Popover` (`popover`, `shadow(md)`). Items: `accent` highlight
+shared by hover and focus; `destructive` items recolour text/icon and use a
+`destructive` @ 10% highlight; separators are a `border` hairline.
+
+## Notes
+
+Actions only — no checkbox/radio items or submenus yet. For a value you keep
+(a chosen option), that's [`Select`](../select), not a menu.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@surstromming/dropdown-menu",
+  "version": "0.1.0",
+  "description": "A menu of actions anchored to a trigger.",
+  "license": "MIT",
+  "author": "Evgeniy Mnatsakanov <evgeniy.mnatsakanov@gmail.com>",
+  "homepage": "https://github.com/hackteck/surstromming/tree/main/packages/dropdown-menu#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hackteck/surstromming.git",
+    "directory": "packages/dropdown-menu"
+  },
+  "bugs": "https://github.com/hackteck/surstromming/issues",
+  "keywords": [
+    "vue",
+    "vue3",
+    "component-library",
+    "design-system",
+    "ui",
+    "scss",
+    "css-modules",
+    "shadcn",
+    "dropdown-menu"
+  ],
+  "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/DropdownMenu.vue

@@ -0,0 +1,199 @@
+<template>
+  <Popover v-model:open="open" :align="align" :side="side" :layer="layer">
+    <template #trigger>
+      <slot name="trigger" :open="open" :toggle="toggle" />
+    </template>
+
+    <div ref="menu" :class="$style.menu" role="menu" @keydown="onKeydown">
+      <template v-for="(item, index) in items" :key="index">
+        <div v-if="'separator' in item" :class="$style.separator" role="separator" />
+        <button
+          v-else
+          :ref="(el) => setItemRef(el, index)"
+          :class="itemClasses(item)"
+          type="button"
+          role="menuitem"
+          tabindex="-1"
+          :disabled="item.disabled"
+          @click="select(item)"
+        >
+          <Icon v-if="item.icon" :icon="item.icon" :size="16" />
+          {{ item.label }}
+        </button>
+      </template>
+    </div>
+  </Popover>
+</template>
+
+<script setup lang="ts">
+import { nextTick, useCssModule, useTemplateRef, watch } from 'vue'
+import { Icon } from '@surstromming/icon'
+import { Popover, type PopoverLayer } from '@surstromming/popover'
+import type {
+  DropdownMenuAlign,
+  DropdownMenuItem,
+  DropdownMenuOption,
+  DropdownMenuSide,
+} from './index'
+
+const props = withDefaults(
+  defineProps<{
+    items: DropdownMenuItem[]
+    align?: DropdownMenuAlign
+    side?: DropdownMenuSide
+    layer?: PopoverLayer
+  }>(),
+  { align: 'start', side: 'bottom', layer: 'popover' },
+)
+
+const open = defineModel<boolean>('open', { default: false })
+const emit = defineEmits<{ select: [value: string] }>()
+
+const toggle = () => {
+  open.value = !open.value
+}
+
+const menu = useTemplateRef<HTMLElement>('menu')
+
+// Buttons keyed by their index in `items` (separators leave gaps — that's fine,
+// the move helper skips anything that isn't a selectable item).
+const itemRefs: (HTMLButtonElement | null)[] = []
+const setItemRef = (el: unknown, index: number) => {
+  itemRefs[index] = el as HTMLButtonElement | null
+}
+
+const isSelectable = (item: DropdownMenuItem) => !('separator' in item) && !item.disabled
+
+const focusAt = (index: number) => itemRefs[index]?.focus()
+
+const focusEdge = (from: 'start' | 'end') => {
+  const order = from === 'start' ? [...props.items.keys()] : [...props.items.keys()].reverse()
+  const index = order.find((i) => isSelectable(props.items[i]))
+  if (index !== undefined) focusAt(index)
+}
+
+// Steps from the focused item, wrapping, skipping separators and disabled ones.
+const move = (direction: 1 | -1) => {
+  const count = props.items.length
+  const active = itemRefs.findIndex((el) => el === document.activeElement)
+  const from = active === -1 ? (direction === 1 ? -1 : count) : active
+  for (let step = 1; step <= count; step++) {
+    const index = (from + direction * step + count * count) % count
+    if (isSelectable(props.items[index])) {
+      focusAt(index)
+      return
+    }
+  }
+}
+
+const select = (item: DropdownMenuOption) => {
+  emit('select', item.value)
+  open.value = false
+}
+
+const onKeydown = (event: KeyboardEvent) => {
+  switch (event.key) {
+    case 'ArrowDown':
+      move(1)
+      break
+    case 'ArrowUp':
+      move(-1)
+      break
+    case 'Home':
+      focusEdge('start')
+      break
+    case 'End':
+      focusEdge('end')
+      break
+    case 'Tab':
+      open.value = false // Tab leaves the menu rather than cycling inside it
+      return
+    default:
+      return // Enter/Space land on the focused <button> natively; Escape → Popover
+  }
+  event.preventDefault() // arrows/Home/End must not scroll the page
+}
+
+// Opening moves focus into the menu; the trigger it came from gets focus back
+// on close, so a keyboard user never loses their place.
+let trigger: HTMLElement | null = null
+watch(open, async (isOpen) => {
+  if (isOpen) {
+    trigger = document.activeElement as HTMLElement
+    await nextTick()
+    focusEdge('start')
+  } else if (menu.value?.contains(document.activeElement)) {
+    trigger?.focus()
+  }
+})
+
+const $style = useCssModule()
+const itemClasses = (item: DropdownMenuOption) => [
+  $style.item,
+  { [$style.isDestructive]: item.destructive },
+]
+</script>
+
+<style module lang="scss">
+@use '@surstromming/design' as design;
+
+.menu {
+  display: flex;
+  flex-direction: column;
+  min-width: design.spacing(48);
+  padding: design.spacing(1);
+}
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: design.spacing(2);
+  border-radius: design.radius(sm);
+  background-color: transparent;
+  padding: design.spacing(1.5) design.spacing(2);
+  color: design.color(popover-foreground);
+  font-size: 0.875rem;
+  text-align: start;
+  white-space: nowrap;
+  cursor: pointer;
+  outline: none;
+
+  // Hover and keyboard focus share one highlight — the item the pointer or the
+  // arrows landed on is the one Enter would fire.
+  &:hover,
+  &:focus-visible {
+    background-color: design.color(accent);
+    color: design.color(accent-foreground);
+  }
+
+  &:disabled {
+    color: design.color(muted-foreground);
+    pointer-events: none;
+  }
+
+  svg {
+    flex-shrink: 0;
+    color: design.color(muted-foreground);
+  }
+}
+
+.isDestructive {
+  color: design.color(destructive);
+
+  &:hover,
+  &:focus-visible {
+    background-color: design.with-alpha(destructive, 10%);
+    color: design.color(destructive);
+  }
+
+  svg {
+    color: design.color(destructive);
+  }
+}
+
+.separator {
+  height: 1px;
+  margin: design.spacing(1) 0;
+  background-color: design.color(border);
+}
+</style>

package/src/index.ts

@@ -0,0 +1,22 @@
+import type { IconNode } from '@surstromming/icon'
+import type { PopoverAlign, PopoverSide } from '@surstromming/popover'
+
+export type DropdownMenuAlign = PopoverAlign
+export type DropdownMenuSide = PopoverSide
+
+export interface DropdownMenuOption {
+  label: string
+  value: string
+  icon?: IconNode
+  disabled?: boolean
+  /** A dangerous action — delete, revoke — painted in the destructive colour. */
+  destructive?: boolean
+}
+
+export interface DropdownMenuSeparator {
+  separator: true
+}
+
+export type DropdownMenuItem = DropdownMenuOption | DropdownMenuSeparator
+
+export { default as DropdownMenu } from './DropdownMenu.vue'