@orbit-work/ui 0.1.0

package/src/components/primitives/Radio/index.tsx

@@ -0,0 +1,161 @@
+"use client"
+
+import { type KeyboardEvent, type ReactNode, createContext, useCallback, useContext, useEffect, useRef } from "react"
+import { cn } from "../../../lib/utils"
+
+export type RadioProps = {
+  checked?: boolean
+  onChange?: (checked: boolean) => void
+  disabled?: boolean
+  className?: string
+  value?: string
+  children?: ReactNode
+  id?: string
+  "aria-label"?: string
+}
+
+export type RadioGroupProps = {
+  value: string
+  onChange: (value: string) => void
+  children: ReactNode
+  disabled?: boolean
+  className?: string
+  "aria-label"?: string
+  /** @deprecated DS 2.0 Radio 单一 16px 规格（§7），无尺寸档。仅为包外旧调用编译兼容，无任何效果。 */
+  size?: "sm" | "md"
+}
+
+const RadioGroupContext = createContext<{
+  value: string
+  onChange: (value: string) => void
+  disabled: boolean
+} | null>(null)
+
+/**
+ * Radio — Orbitwork DS 2.0
+ * 16×16px circular control, 1.5px border. Checked ring + 8px inner dot use
+ * --ow-control-on (achromatic pole); unchecked border --ow-control-off with
+ * hover → --ow-border-strong (§6 input grammar). Hit target padded to 24×24
+ * via ::after without changing the visual (§7). Inside a RadioGroup the
+ * group handles roving focus + arrow-key navigation.
+ */
+export function Radio({ checked, onChange, disabled, className = "", value, id, "aria-label": ariaLabel }: RadioProps) {
+  const group = useContext(RadioGroupContext)
+  const isChecked = group && value !== undefined ? group.value === value : (checked ?? false)
+  const isDisabled = disabled ?? group?.disabled ?? false
+
+  const handleClick = useCallback(() => {
+    if (isDisabled || isChecked) return
+    if (group && value !== undefined) group.onChange(value)
+    onChange?.(true)
+  }, [group, value, isChecked, isDisabled, onChange])
+
+  return (
+    <button
+      id={id}
+      type="button"
+      role="radio"
+      aria-checked={isChecked}
+      aria-label={ariaLabel}
+      disabled={isDisabled}
+      data-slot="radio"
+      data-ow-part="control"
+      data-ow-role={isChecked ? "on" : "off"}
+      data-ow-value={value}
+      className={cn(
+        "relative inline-flex items-center justify-center w-4 h-4 rounded-full border-[1.5px] p-0 bg-transparent",
+        // ≥24px hit target without growing the 16px visual (§7)
+        "after:content-[''] after:absolute after:-inset-1 after:rounded-full",
+        "transition-[border-color,background-color] duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+        // R2：焦点语法归一到 .ow-focus-ring（同 Checkbox/Switch/Button）。
+        "ow-focus-ring",
+        isChecked
+          ? "border-[color:var(--ow-control-on)]"
+          : "border-[color:var(--ow-control-off)] hover:border-[color:var(--ow-border-strong)] active:bg-[var(--ow-press)]",
+        isDisabled
+          ? "cursor-not-allowed border-[color:var(--ow-disabled-border)] bg-[var(--ow-disabled-bg)] hover:border-[color:var(--ow-disabled-border)] active:bg-[var(--ow-disabled-bg)]"
+          : "cursor-pointer",
+        className,
+      )}
+      onClick={handleClick}
+    >
+      {isChecked && (
+        <span
+          className={cn(
+            "w-2 h-2 rounded-full",
+            isDisabled ? "bg-[var(--ow-disabled-text)]" : "bg-[var(--ow-control-on)]",
+          )}
+        />
+      )}
+    </button>
+  )
+}
+
+/**
+ * RadioGroup — groups Radio buttons under one value with roving tabindex:
+ * Tab enters the group on the checked (or first enabled) radio;
+ * Arrow keys (←→↑↓) move selection and focus; Home/End jump to the ends.
+ */
+export function RadioGroup({
+  value,
+  onChange,
+  children,
+  disabled = false,
+  className = "",
+  "aria-label": ariaLabel,
+}: RadioGroupProps) {
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  const getRadios = useCallback(() => {
+    const root = rootRef.current
+    if (!root) return []
+    return Array.from(root.querySelectorAll<HTMLButtonElement>('[role="radio"]:not(:disabled)'))
+  }, [])
+
+  // Roving tabindex: checked radio (or first enabled) is the single tab stop.
+  useEffect(() => {
+    const radios = getRadios()
+    if (radios.length === 0) return
+    const checkedIdx = radios.findIndex((r) => r.getAttribute("aria-checked") === "true")
+    radios.forEach((r, i) => {
+      r.tabIndex = i === (checkedIdx >= 0 ? checkedIdx : 0) ? 0 : -1
+    })
+  })
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      const keys = ["ArrowRight", "ArrowDown", "ArrowLeft", "ArrowUp", "Home", "End"]
+      if (!keys.includes(e.key)) return
+      const radios = getRadios()
+      if (radios.length === 0) return
+      const current = radios.indexOf(e.target as HTMLButtonElement)
+      let next: number
+      if (e.key === "Home") next = 0
+      else if (e.key === "End") next = radios.length - 1
+      else if (e.key === "ArrowRight" || e.key === "ArrowDown") next = current < 0 ? 0 : (current + 1) % radios.length
+      else next = current < 0 ? 0 : (current - 1 + radios.length) % radios.length
+      e.preventDefault()
+      const target = radios[next]
+      if (!target) return
+      target.focus()
+      const v = target.getAttribute("data-ow-value")
+      if (v !== null && v !== value) onChange(v)
+    },
+    [getRadios, onChange, value],
+  )
+
+  return (
+    <RadioGroupContext.Provider value={{ value, onChange, disabled }}>
+      <div
+        ref={rootRef}
+        data-slot="radio-group"
+        className={cn("flex flex-col gap-2", className)}
+        role="radiogroup"
+        aria-label={ariaLabel}
+        onKeyDown={handleKeyDown}
+      >
+        {children}
+      </div>
+    </RadioGroupContext.Provider>
+  )
+}

package/src/components/primitives/SegmentedControl/SegmentedControl.stories.tsx

@@ -0,0 +1,110 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { SegmentedControl } from "./index"
+
+const meta = {
+  title: "Primitives/SegmentedControl",
+  component: SegmentedControl,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof SegmentedControl>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const viewOptions = [
+  { value: "list", label: "列表" },
+  { value: "board", label: "看板" },
+  { value: "timeline", label: "时间线" },
+]
+
+export const Default: Story = {
+  args: {
+    options: viewOptions,
+    defaultValue: "list",
+    "aria-label": "视图切换",
+  },
+}
+
+export const Small: Story = {
+  args: {
+    options: viewOptions,
+    defaultValue: "board",
+    size: "sm",
+    "aria-label": "视图切换（28px 档）",
+  },
+}
+
+/**
+ * 线框档（A3-B4，原型 template.dc.html L1654–1658）：透明面 ＋ 1px `--ow-border` 外框，
+ * 段角 4、字号 caption，选中＝`--ow-current-bg` ＋ 500。
+ * 用在**没有托盘可坐**的地方 —— 插件页筛选行右端那枚「全部 / 我的」就是它：那一排直接坐在
+ * 页底上，托盘档的 `--ow-surface-2` 井扣上去会凭空多出一块灰面。选中语汇与同排的分类 chip
+ * （`Chip selected`）、侧栏 current 同一套「位置极」，不占状态极、不引功能色。
+ */
+export const Outline: Story = {
+  args: {
+    options: [
+      { value: "all", label: "全部" },
+      { value: "mine", label: "我的" },
+    ],
+    defaultValue: "all",
+    variant: "outline",
+    size: "sm",
+    "aria-label": "按归属筛选",
+  },
+}
+
+export const WithDisabledSegment: Story = {
+  args: {
+    options: [
+      { value: "all", label: "全部" },
+      { value: "running", label: "运行中" },
+      { value: "archived", label: "已归档", disabled: true },
+    ],
+    defaultValue: "all",
+    "aria-label": "任务筛选",
+  },
+}
+
+export const DisabledGroup: Story = {
+  args: {
+    options: viewOptions,
+    defaultValue: "list",
+    disabled: true,
+    "aria-label": "禁用的视图切换",
+  },
+}
+
+export const Controlled: Story = {
+  args: {
+    options: viewOptions,
+    "aria-label": "受控示例",
+  },
+  render: (args) => {
+    const [value, setValue] = useState("list")
+    return (
+      <div className="flex flex-col items-center gap-3">
+        <SegmentedControl {...args} value={value} onChange={setValue} />
+        <span className="text-sm text-ow-text-2">
+          当前：<span className="font-mono [font-variant-numeric:tabular-nums]">{value}</span>
+        </span>
+      </div>
+    )
+  },
+}
+
+export const BothSizes: Story = {
+  args: {
+    options: viewOptions,
+    "aria-label": "两档高度",
+  },
+  render: () => (
+    <div className="flex flex-col items-start gap-4">
+      <SegmentedControl options={viewOptions} defaultValue="list" size="sm" aria-label="28px 档" />
+      <SegmentedControl options={viewOptions} defaultValue="list" size="md" aria-label="32px 档" />
+    </div>
+  ),
+}

package/src/components/primitives/SegmentedControl/SegmentedControlSource.test.mjs

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const source = await readFile(new URL("./index.tsx", import.meta.url), "utf8")
+/** Comments name the retired V1 idioms as documentation; bans are checked on code only. */
+const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^[ \t]*\/\/.*$/gm, "")
+
+test("shell: 8px radius, surface-2 well, 28/32 height tiers", () => {
+  // R2：圆角写法统一到全库口径 [border-radius:var(--ow-radius-*)]（原 rounded-[var(…)] 是第二套写法）。
+  assert.match(source, /\[border-radius:var\(--ow-radius-sm\)\]/)
+  assert.match(source, /variant === "well" \? "bg-\[var\(--ow-surface-2\)\]"/)
+  // A3-B4：外壳不再写死 h-7/h-8，高度＝内钮(24/28) ＋ 2px 内距（outline 再叠 1px 边），
+  // well 档两档仍是 28/32 逐像素不变；断言改问内钮档。
+  assert.match(source, /size === "sm" \? "h-6" : "h-7"/)
+})
+
+// A3-B4 线框档（原型 template.dc.html L1654–1658）：透明面 ＋ 1px --ow-border 外框，
+// 段角收到 radius-2xs(4)、字号收到 caption，选中＝--ow-current-bg ＋ 500（位置极语汇，
+// 与同排的 Chip selected 分类 chip 同一套；不占状态极、不引功能色）。
+test("outline variant: 1px border shell, current-bg selection, 4px segment radius", () => {
+  assert.match(source, /export type SegmentedControlVariant = "well" \| "outline"/)
+  assert.match(code, /bg-transparent border border-\[color:var\(--ow-border\)\]/)
+  assert.match(
+    code,
+    /variant === "well" \? "\[border-radius:var\(--ow-radius-xs\)\]" : "\[border-radius:var\(--ow-radius-2xs\)\]"/,
+  )
+  assert.match(code, /variant === "well" \? "bg-\[var\(--ow-segment-on-bg\)\]" : "bg-\[var\(--ow-current-bg\)\]"/)
+  assert.doesNotMatch(code, /--ow-primary|--ow-beacon/)
+})
+
+// W5 终扫：§12「圆角不开放自由值」——段圆角原写字面量 rounded-[6px]，全走 token。
+test("segment radius is a token, never a literal", () => {
+  assert.match(code, /\[border-radius:var\(--ow-radius-xs\)\]/)
+  assert.doesNotMatch(code, /rounded-\[/)
+})
+
+// W3：分段控件贴地不离地，§5「影子只属离地之物」——托盘影删除，选中只剩
+// surface 提亮 ＋ 500 字重两层编码（R1 仍是双编码：底色 ＋ 字重）。
+test("selected segment: surface lift + 500 weight, no grounded shadow (dual encoding, R1)", () => {
+  // R2：选中段底改取 --ow-segment-on-bg。原写死 --ow-surface，浅档是提亮、暗档反而比托盘更暗
+  // （--ow-surface 在暗档低于 --ow-surface-2），选中段渲成凹陷格，与「surface 递进」相反。
+  // A3-B4：选中段的「500 字重 ＋ --ow-text」与「选中底色」拆成两截（底色随 variant 走），
+  // 断言改为分别问这两半。
+  assert.match(code, /"font-medium text-\[color:var\(--ow-text\)\]"/)
+  assert.match(code, /bg-\[var\(--ow-segment-on-bg\)\]/)
+  assert.doesNotMatch(code, /--ow-shadow-1|shadow-\[/)
+  assert.doesNotMatch(code, /--ow-beacon|--ow-yellow|--ow-accent-dot/)
+})
+
+test("state completeness: hover/press on surface tokens, focus ring, per-token disabled", () => {
+  assert.match(source, /hover:bg-\[var\(--ow-hover\)\] active:bg-\[var\(--ow-press\)\]/)
+  // R2：焦点语法全库归一到 .ow-focus-ring（outline 三件套），不再走 --ow-focus-shadow。
+  assert.match(source, /ow-focus-ring focus-visible:relative/)
+  assert.doesNotMatch(code, /--ow-focus-shadow/)
+  assert.match(source, /text-\[color:var\(--ow-disabled-text\)\]/)
+  assert.doesNotMatch(source, /disabled:opacity|opacity-disabled/)
+})
+
+test("keyboard: radiogroup semantics with left/right roving navigation", () => {
+  assert.match(source, /role="radiogroup"/)
+  assert.match(source, /role="radio"/)
+  assert.match(source, /ArrowRight/)
+  assert.match(source, /ArrowLeft/)
+  assert.match(source, /tabIndex/)
+})
+
+test("motion: 120ms ease-beacon color transitions only, no slide/scale", () => {
+  assert.match(source, /duration-\[var\(--ow-dur-1\)\] ease-\[var\(--ow-ease-beacon\)\]/)
+  // 影没了，过渡里也不该再留 box-shadow 这一路。
+  assert.match(code, /transition-\[background-color,color\]/)
+  // Built via constructor so the DS2 guard's own grep does not flag this test file.
+  const moveClasses = new RegExp(["hover:" + "scale", "hover:" + "translate", "translate" + "-x"].join("|"))
+  assert.doesNotMatch(source, moveClasses)
+})

package/src/components/primitives/SegmentedControl/index.tsx

@@ -0,0 +1,188 @@
+"use client"
+
+import { type KeyboardEvent, type ReactNode, useCallback, useEffect, useRef, useState } from "react"
+import { cn } from "../../../lib/utils"
+
+export type SegmentedControlOption = {
+  value: string
+  label: ReactNode
+  icon?: ReactNode
+  disabled?: boolean
+}
+
+export type SegmentedControlSize = "sm" | "md"
+
+/**
+ * 外壳档（A3-B4 新增 outline）。
+ * - `well`（默认）：托盘档 —— `--ow-surface-2` 井，选中段以 `--ow-segment-on-bg` 提亮。
+ *   设置页那类「坐在卡面上的模式切换」用它。
+ * - `outline`：线框档 —— **透明面 ＋ 1px `--ow-border` 外框**，选中段落 `--ow-current-bg`。
+ *   给筛选行右端那种「坐在页底上的归属/范围切换」用（原型 template.dc.html L1654–1658）：
+ *   那一排本来就没有托盘可坐，井色扣在页底上会凭空多出一块灰面；它与同排的分类 chip
+ *   （`Chip selected`）共用一套「1px 边 ＋ --ow-current-bg 选中 ＋ 500」的位置极语汇。
+ */
+export type SegmentedControlVariant = "well" | "outline"
+
+export type SegmentedControlProps = {
+  options: SegmentedControlOption[]
+  value?: string
+  defaultValue?: string
+  onChange?: (value: string) => void
+  /** sm = 24px 内钮（外壳 28 / outline 30）, md = 28px 内钮（外壳 32 / outline 34）——§7 控件高度档 */
+  size?: SegmentedControlSize
+  /** 外壳档；默认 well（托盘）。筛选行右端用 outline（线框）。 */
+  variant?: SegmentedControlVariant
+  disabled?: boolean
+  className?: string
+  "aria-label"?: string
+}
+
+/**
+ * SegmentedControl — Orbitwork DS 2.0 原语（新造件，蓝图批次①）
+ * 分段单选：8px 圆角外壳，选中段以底色 **提亮** ＋ 500 字重（双编码：底色＋字重，R1）。
+ * 两档高度：sm 内钮 24（外壳 28）/ md 内钮 28（外壳 32）；outline 档各再叠 1px 边。
+ * A3-B4 加 `variant`：well＝托盘档（--ow-surface-2 井 ＋ --ow-segment-on-bg 选中，原有全部
+ * 消费方逐像素不变），outline＝线框档（透明面 ＋ 1px --ow-border ＋ --ow-current-bg 选中），
+ * 后者收编插件页筛选行右端那枚手搓的 `.plaza__scope`（原型 L1654–1658）。
+ *
+ * R2：选中段原写死 --ow-surface，浅档确是提亮（#FDFDFC on #F1F0EA），暗档却比托盘更暗
+ * （#1E2025 on #23252B）——同一句注释在两档指向相反方向，暗档实际渲成凹陷格。
+ * 既定态「无彩选中＝surface **递进**」两档同向，故改取 --ow-segment-on-bg：
+ * 浅档 = --ow-surface，暗档 = pop 档面色，两档都比托盘亮一级。
+ * W3 验收修：选中段原来还叠 --ow-shadow-1 托盘影。分段控件贴地不离地，§5「影子只属
+ * 离地之物」——贴地＝0 影，选中靠 surface 提亮＋字重两层编码即可，托盘影是 V1 残留。
+ * W5 终扫：段圆角原写字面量 rounded-[6px]，§12「圆角不开放自由值」——改走 --ow-radius-xs(6)。
+ * 键盘 ←→/Home/End 移动选择（roving tabindex）。中性件，无信标元素（R3）。
+ * 动效仅底色/文字色过渡 120ms --ow-ease-beacon（§9，无位移滑块）。
+ */
+export function SegmentedControl({
+  options,
+  value,
+  defaultValue,
+  onChange,
+  size = "md",
+  variant = "well",
+  disabled = false,
+  className,
+  "aria-label": ariaLabel,
+}: SegmentedControlProps) {
+  const [internalValue, setInternalValue] = useState(defaultValue ?? options[0]?.value ?? "")
+  const current = value ?? internalValue
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  const select = useCallback(
+    (v: string) => {
+      if (disabled || v === current) return
+      setInternalValue(v)
+      onChange?.(v)
+    },
+    [disabled, current, onChange],
+  )
+
+  const getSegments = useCallback(() => {
+    const root = rootRef.current
+    if (!root) return []
+    return Array.from(root.querySelectorAll<HTMLButtonElement>('[role="radio"]:not(:disabled)'))
+  }, [])
+
+  // Roving tabindex: the selected segment (or first enabled) is the tab stop.
+  useEffect(() => {
+    const segments = getSegments()
+    if (segments.length === 0) return
+    const selectedIdx = segments.findIndex((s) => s.getAttribute("aria-checked") === "true")
+    segments.forEach((s, i) => {
+      s.tabIndex = i === (selectedIdx >= 0 ? selectedIdx : 0) ? 0 : -1
+    })
+  })
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      const keys = ["ArrowRight", "ArrowLeft", "Home", "End"]
+      if (!keys.includes(e.key)) return
+      const segments = getSegments()
+      if (segments.length === 0) return
+      const currentIdx = segments.indexOf(e.target as HTMLButtonElement)
+      let next: number
+      if (e.key === "Home") next = 0
+      else if (e.key === "End") next = segments.length - 1
+      else if (e.key === "ArrowRight") next = currentIdx < 0 ? 0 : (currentIdx + 1) % segments.length
+      else next = currentIdx < 0 ? 0 : (currentIdx - 1 + segments.length) % segments.length
+      e.preventDefault()
+      const target = segments[next]
+      if (!target) return
+      target.focus()
+      const v = target.getAttribute("data-ow-value")
+      if (v !== null) select(v)
+    },
+    [getSegments, select],
+  )
+
+  return (
+    <div
+      ref={rootRef}
+      role="radiogroup"
+      aria-label={ariaLabel}
+      data-slot="segmented-control"
+      data-size={size}
+      data-variant={variant}
+      data-ow-part="control"
+      onKeyDown={handleKeyDown}
+      className={cn(
+        // W5 记的是「不再写 rounded-[6px]」，写法仍是 rounded-[var()]；R2 统一到全库口径 [border-radius:var()]。
+        "inline-flex items-stretch gap-0.5 p-0.5 [border-radius:var(--ow-radius-sm)]",
+        // A3-B4：外壳高度改由内钮给（sm 24 / md 28）＋ 2px 内距，well 档逐像素等于原来的
+        // h-7/h-8；outline 档再叠 1px 边（30 / 34），不写第二套写死高度。
+        variant === "well" ? "bg-[var(--ow-surface-2)]" : "bg-transparent border border-[color:var(--ow-border)]",
+        disabled && "cursor-not-allowed",
+        className,
+      )}
+    >
+      {options.map((opt) => {
+        const isSelected = current === opt.value
+        const isDisabled = disabled || opt.disabled
+        return (
+          <button
+            key={opt.value}
+            type="button"
+            role="radio"
+            aria-checked={isSelected}
+            disabled={isDisabled}
+            data-ow-part="segment"
+            data-ow-role={isSelected ? "on" : "off"}
+            data-ow-value={opt.value}
+            onClick={() => select(opt.value)}
+            className={cn(
+              "inline-flex items-center justify-center gap-1.5 px-2.5 border-none",
+              size === "sm" ? "h-6" : "h-7",
+              // 段圆角随外壳档走：托盘里是 6（radius-xs），线框里收到 4（radius-2xs）——
+              // 线框只留 2px 内距，段角必须比外壳(8)小两级才不会顶着框画出双弧。
+              variant === "well" ? "[border-radius:var(--ow-radius-xs)]" : "[border-radius:var(--ow-radius-2xs)]",
+              variant === "well" ? "text-[length:var(--ow-fs-ui)]" : "text-[length:var(--ow-fs-caption)]",
+              "leading-none whitespace-nowrap",
+              "transition-[background-color,color] duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+              // R2：焦点语法归一到 .ow-focus-ring；outline 画在盒外不需要假缝，
+              // 原 --ow-focus-shadow 的 2px 缝写死 var(--ow-surface)，段坐在 surface-2 托盘上会露一圈近白晕。
+              "ow-focus-ring focus-visible:relative focus-visible:z-[1]",
+              isSelected
+                ? cn(
+                    "font-medium text-[color:var(--ow-text)]",
+                    variant === "well" ? "bg-[var(--ow-segment-on-bg)]" : "bg-[var(--ow-current-bg)]",
+                  )
+                : "bg-transparent font-normal text-[color:var(--ow-text-2)] hover:text-[color:var(--ow-text)] hover:bg-[var(--ow-hover)] active:bg-[var(--ow-press)]",
+              isDisabled
+                ? "cursor-not-allowed text-[color:var(--ow-disabled-text)] hover:text-[color:var(--ow-disabled-text)] hover:bg-transparent active:bg-transparent"
+                : "cursor-pointer",
+            )}
+          >
+            {opt.icon && (
+              <span className="inline-flex items-center justify-center w-3.5 h-3.5 [&>svg]:w-full [&>svg]:h-full">
+                {opt.icon}
+              </span>
+            )}
+            {opt.label}
+          </button>
+        )
+      })}
+    </div>
+  )
+}

package/src/components/primitives/Select/Select.stories.tsx

@@ -0,0 +1,158 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { Select, SelectTrigger } from "./index"
+
+const meta = {
+  title: "Primitives/Select",
+  component: Select,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof Select>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const options = [
+  { label: "全部设备", value: "all" },
+  { label: "工作台机器", value: "workstation" },
+  { label: "家用笔记本", value: "laptop" },
+]
+
+const subOptions = [
+  { label: "简体中文", value: "zh", sub: "Chinese" },
+  { label: "English", value: "en", sub: "英语" },
+  { label: "日本語", value: "ja", sub: "日语" },
+]
+
+function ControlledSelect(props: Omit<React.ComponentProps<typeof Select>, "onChange">) {
+  const [value, setValue] = useState(props.value)
+  return <Select {...props} value={value} onChange={setValue} />
+}
+
+export const Default: Story = {
+  args: {
+    value: "",
+    options,
+    onChange: () => {},
+    placeholder: "选择设备",
+  },
+  render: (args) => (
+    <div style={{ width: 260 }}>
+      <ControlledSelect {...args} />
+    </div>
+  ),
+}
+
+export const WithValue: Story = {
+  args: {
+    value: "workstation",
+    options,
+    onChange: () => {},
+  },
+  render: (args) => (
+    <div style={{ width: 260 }}>
+      <ControlledSelect {...args} />
+    </div>
+  ),
+}
+
+/** 28 / 32 / 40 三档控件高度 */
+export const Sizes: Story = {
+  args: { value: "all", options, onChange: () => {} },
+  render: (args) => (
+    <div style={{ width: 260, display: "flex", flexDirection: "column", gap: 12 }}>
+      <ControlledSelect {...args} size="sm" />
+      <ControlledSelect {...args} size="md" />
+      <ControlledSelect {...args} size="lg" />
+    </div>
+  ),
+}
+
+/** 行内副文案（sub）与选中打勾（不靠底色） */
+export const WithSubText: Story = {
+  args: {
+    value: "zh",
+    options: subOptions,
+    onChange: () => {},
+  },
+  render: (args) => (
+    <div style={{ width: 260 }}>
+      <ControlledSelect {...args} />
+    </div>
+  ),
+}
+
+export const Disabled: Story = {
+  args: {
+    value: "",
+    options,
+    onChange: () => {},
+    placeholder: "暂无可选设备",
+    disabled: true,
+  },
+  render: (args) => (
+    <div style={{ width: 260 }}>
+      <Select {...args} />
+    </div>
+  ),
+}
+
+/** 长列表滚动 + 键盘导航（焦点留在触发器，↑↓/Home/End/Enter/Esc） */
+export const ManyOptions: Story = {
+  args: {
+    value: "8",
+    options: Array.from({ length: 20 }, (_, i) => ({
+      label: `会话分组 ${i + 1}`,
+      value: String(i + 1),
+    })),
+    onChange: () => {},
+    placeholder: "选择分组",
+  },
+  render: (args) => (
+    <div style={{ width: 260 }}>
+      <ControlledSelect {...args} />
+    </div>
+  ),
+}
+
+/** footer 插槽：钉在选项列表下方的自定义内容（ProjectSelect 配方即用此位） */
+export const WithFooter: Story = {
+  args: {
+    value: "all",
+    options,
+    onChange: () => {},
+    footer: (
+      <div
+        style={{
+          marginTop: 6,
+          borderTop: "1px solid var(--ow-border)",
+          padding: "6px 8px 2px",
+          fontSize: 12,
+          lineHeight: 1.4,
+          color: "var(--ow-text-3)",
+        }}
+      >
+        找不到设备？请先在客户端登录
+      </div>
+    ),
+  },
+  render: (args) => (
+    <div style={{ width: 260 }}>
+      <ControlledSelect {...args} />
+    </div>
+  ),
+}
+
+/** 独立触发器壳（SelectTrigger）——供 ModelSelect 等预设配方复用 */
+export const TriggerShell: Story = {
+  args: { value: "", options, onChange: () => {} },
+  render: () => (
+    <div style={{ width: 260, display: "flex", flexDirection: "column", gap: 12 }}>
+      <SelectTrigger>已选中的值</SelectTrigger>
+      <SelectTrigger open>展开状态（focus 档边框）</SelectTrigger>
+      <SelectTrigger disabled>禁用状态</SelectTrigger>
+    </div>
+  ),
+}