前端设计系统实践：组件交互行为的文档化方案与落地步骤

┌────────────────────────────────────────┐
│ 1. 状态矩阵 (State Matrix)              │ -> 罗列视觉与行为状态
├────────────────────────────────────────┤
│ 2. 交互行为契约 (Interaction Contracts) │ -> 触发条件、时序与副作用
├────────────────────────────────────────┤
│ 3. 键盘与无障碍映射 (A11y & Keyboard)   │ -> 焦点流转与屏幕阅读器支持
└────────────────────────────────────────┘

# Select 选择器 (Searchable Multi-Select)

用于多项数据的检索与挑选。

## 交互行为规范

### 1. 下拉浮层开闭逻辑
- **打开**：点击选择框主体，或在聚焦时按下 `ArrowDown` / `Enter`。
- **关闭**：
  - 点击浮层外部区域（Click Outside）。
  - 按下 `Escape` 键。
  - 单选模式下选中项后自动关闭；多选模式下保持展开。

### 2. 键盘导航时序
```text
[聚焦触发器] --按 Enter--> [展开面板 & 输入框自动聚焦]
                         |--按 ArrowDown--> [高亮第一项]
                         |--按 Enter------> [选中/反选该项]
                         |--按 Escape-----> [关闭面板 & 焦点回到触发器]
```

### 3. 可交互示例 (Interactive Sandbox)
<Canvas of={SelectStories.SearchableMulti} />

import type { Meta, StoryObj } from '@storybook/react';
import { userEvent, within, expect } from '@storybook/test';
import { MultiSelect } from './MultiSelect';

const meta: Meta<typeof MultiSelect> = {
  title: 'Components/MultiSelect',
  component: MultiSelect,
};

export default meta;
type Story = StoryObj<typeof MultiSelect>;

export const KeyboardSelectionFlow: Story = {
  args: {
    options: [
      { label: 'Vue.js', value: 'vue' },
      { label: 'React', value: 'react' },
      { label: 'Angular', value: 'angular' },
    ],
    placeholder: '请选择技术栈',
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const trigger = canvas.getByRole('combobox');

    // 1. 模拟用户点击打开下拉框
    await userEvent.click(trigger);

    // 2. 验证下拉浮层展开
    const listbox = await canvas.findByRole('listbox');
    await expect(listbox).toBeInTheDocument();

    // 3. 模拟键盘向下移动并回车选中
    await userEvent.keyboard('{ArrowDown}');
    await userEvent.keyboard('{Enter}');

    // 4. 验证已生成 Tag
    const tag = await canvas.findByText('Vue.js');
    await expect(tag).toBeInTheDocument();
  },
};