pda-kit-mcp-server 2.0.1

package/spec-data/selectable-list.md

@@ -0,0 +1,331 @@
+---
+id: selectable-list
+name: 可勾选列表 Selectable List
+category: "表单/Form"
+version: "1.0.0"
+source: PDAKit-基础组件
+source_url: https://mastergo.ky-tech.com.cn/goto/UgTWrOWt
+source_doc_id: 103417331857122
+component_count: 1
+---
+
+# 可勾选列表 Selectable List
+
+白底勾选列表，支持**单选**和**多选**两种选择模式。每条占一行 `480×70px`，左侧勾选图标 + 标题文字，右侧可选统计徽章。常用于目的地选择、服务类型勾选、分类筛选等场景。
+
+> **颜色规则**：全部使用 Token（`--color-{色系}-{色阶}`），禁止 Hex。
+> **字体**：PingFang SC。
+
+---
+
+## 容器规格
+
+| 属性 | 值 |
+|------|-----|
+| 宽度 | `480px`（撑满父容器） |
+| 背景 | `--color-grey-1`（`#FFFFFF`） |
+| 布局 | 垂直排列，可选顶部分割线 |
+
+---
+
+## 列表项规格
+
+| 属性 | 值 |
+|------|-----|
+| 高度 | `70px` |
+| 布局 | `flex` + `space-between` + `align-items: center` |
+| 内边距 | `0 16px`（左右 16px） |
+| 背景 | `--color-grey-1`（`#FFFFFF`） |
+| 按下态 | `:active → background: var(--color-grey-2)` |
+| 底部分割线 | `1px` 高，`--color-black-2`（`#DDDDDD`），撑满宽度 |
+
+### 左侧：标题（+ 描述文字）
+
+| 属性 | 值 |
+|------|------|
+| 布局 | `flex-col` + `justify-content: center` |
+| 标题 | `font-size: 20px / line-height: 28px`，`font-weight: 600` |
+| 描述文字（可选） | `font-size: 16px / line-height: 22px`，`color: --color-black-4` |
+
+### 右侧：勾选图标 + 统计徽章
+
+| 属性 | 值 |
+|------|------|
+| 布局 | `flex` + `align-items: center` + `gap: 8px` |
+| 勾选图标 | `32×32px` |
+| 徽章背景 | `--color-grey-2`（`#F3F4F6`） |
+| 徽章边框 | `1px solid --color-grey-3`（`#E0E4F0`） |
+| 徽章圆角 | `8px` |
+| 徽章内边距 | `4px 8px` |
+| 徽章文字 | `font-size: 18px / line-height: 25px`，`color: --color-grey-7`（`#383B6F`） |
+
+> 右侧勾选图标必填，统计徽章可选。
+
+### 选中态 vs 未选中态
+
+| 状态 | 勾选图标 | 图标颜色 | 文字颜色 |
+|------|---------|---------|---------|
+| **选中** | `common_ic_check_two.svg` | `--color-green-6`（`#03C15F`） | 不变 |
+| **未选中** | `common_ic_radio_o.svg` | 原始色 | `--color-black-6`（`#333333`） |
+
+> 选中态图标需通过 CSS `filter` 染为绿色：`filter: invert(48%) sepia(79%) saturate(2476%) hue-rotate(116deg) brightness(96%) contrast(101%);`
+
+---
+
+## 两种选择模式
+
+### 单选（Radio 行为）
+
+同一列表组中同时只有 1 项处于选中态。点击某项 → 该项选中，其余全部取消。
+
+| 交互 | 行为 |
+|------|------|
+| 点击未选中项 | 清除全组选中 → 该项变为选中态 |
+| 点击已选中项 | 无变化（不取消） |
+
+### 多选（Checkbox 行为）
+
+同一列表组中可同时选中多项。点击某项 → 切换该项选中/未选状态。
+
+| 交互 | 行为 |
+|------|------|
+| 点击未选中项 | 该项 → 选中态 |
+| 点击已选中项 | 该项 → 未选中态 |
+
+> 切换通过 JS 添加/移除 `.selected` class 控制文字颜色，同时替换 `img.src` 切换图标。不依赖 CSS `content` 属性。
+
+---
+
+## 布局结构
+
+```
+┌──────────────────────────────────────────┐
+│  ───  1px 顶部分割线（可选） ───            │
+├──────────────────────────────────────────┤
+│  北京                          [✓]  12  │  ← 选中态：文字紫色
+│  北京市辖区                                │
+├──────────────────────────────────────────┤
+│  ───  1px 分割线 ───                      │
+├──────────────────────────────────────────┤
+│  上海                          [○]       │  ← 未选中态
+├──────────────────────────────────────────┤
+│  ───  1px 分割线 ───                      │
+├──────────────────────────────────────────┤
+│  广州                          [○]   8  │  ← 右侧徽章可选
+│  广东省广州市                              │
+└──────────────────────────────────────────┘
+```
+
+---
+
+## 尺寸速查
+
+| 元素 | 值 |
+|------|------|
+| 列表项高度 | `70px` |
+| 列表项左右内边距 | `16px` |
+| 勾选图标 | `32 × 32px` |
+| 左侧间距（图标 ↔ 文字） | `12px` |
+| 标题字号 | `20px / 28px`，Semibold（`600`） |
+| 徽章字号 | `18px / 25px` |
+| 徽章圆角 | `8px` |
+| 徽章内边距 | `4px 8px` |
+| 分割线 | `1px`，`--color-black-2` |
+
+---
+
+## HTML 示例
+
+### 单选项
+
+```html
+<div class="selectable-list">
+  <div class="selectable-item" data-value="beijing" onclick="selectSingle(this, 'single-group')">
+    <div class="selectable-left">
+      <span class="selectable-text">北京</span>
+      <span class="selectable-desc">北京市辖区</span>
+    </div>
+    <div class="selectable-right">
+      <img class="selectable-checkbox" src="./icons/assets/common_ic_radio_o.svg" width="32" height="32" alt="">
+    </div>
+  </div>
+  <div class="selectable-divider"></div>
+  <div class="selectable-item" data-value="shanghai" onclick="selectSingle(this, 'single-group')">
+    <div class="selectable-left">
+      <span class="selectable-text">上海</span>
+    </div>
+    <div class="selectable-right">
+      <img class="selectable-checkbox" src="./icons/assets/common_ic_radio_o.svg" width="32" height="32" alt="">
+    </div>
+  </div>
+</div>
+```
+
+### 多选项（带徽章）
+
+```html
+<div class="selectable-list">
+  <div class="selectable-item" data-value="express" onclick="toggleSelect(this)">
+    <div class="selectable-left">
+      <span class="selectable-text">快递服务</span>
+    </div>
+    <div class="selectable-right">
+      <img class="selectable-checkbox" src="./icons/assets/common_ic_radio_o.svg" width="32" height="32" alt="">
+      <span class="selectable-badge">12</span>
+    </div>
+  </div>
+  <div class="selectable-divider"></div>
+  <div class="selectable-item" data-value="logistics" onclick="toggleSelect(this)">
+    <div class="selectable-left">
+      <span class="selectable-text">物流配送</span>
+    </div>
+    <div class="selectable-right">
+      <img class="selectable-checkbox" src="./icons/assets/common_ic_radio_o.svg" width="32" height="32" alt="">
+    </div>
+  </div>
+</div>
+```
+
+### JS 交互脚本
+
+```javascript
+// 单选
+function selectSingle(el, groupId) {
+  const parent = el.parentElement;
+  parent.querySelectorAll('.selectable-item').forEach(item => {
+    item.classList.remove('selected');
+    item.querySelector('.selectable-checkbox').src = './icons/assets/common_ic_radio_o.svg';
+  });
+  el.classList.add('selected');
+  el.querySelector('.selectable-checkbox').src = './icons/assets/common_ic_check_two.svg';
+}
+
+// 多选
+function toggleSelect(el) {
+  const checkbox = el.querySelector('.selectable-checkbox');
+  if (el.classList.contains('selected')) {
+    el.classList.remove('selected');
+    checkbox.src = './icons/assets/common_ic_radio_o.svg';
+  } else {
+    el.classList.add('selected');
+    checkbox.src = './icons/assets/common_ic_check_two.svg';
+  }
+}
+```
+
+---
+
+## CSS
+
+```css
+/* 列表容器 */
+.selectable-list {
+  width: 100%;
+  background: var(--color-grey-1);
+}
+
+/* 列表项 */
+.selectable-item {
+  width: 100%;
+  height: 70px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0 16px;
+  background: var(--color-grey-1);
+  cursor: pointer;
+}
+
+/* 按下态 */
+.selectable-item:active {
+  background: var(--color-grey-2);
+}
+
+/* 选中态：图标变绿 */
+.selectable-item.selected .selectable-checkbox {
+  filter: invert(48%) sepia(79%) saturate(2476%) hue-rotate(116deg) brightness(96%) contrast(101%);
+}
+
+/* 左侧：标题 + 描述 */
+.selectable-left {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  flex: 1;
+  min-width: 0;
+}
+
+/* 标题文字 */
+.selectable-text {
+  font: 600 20px/28px "PingFang SC", -apple-system, sans-serif;
+  color: var(--color-black-6);
+}
+
+/* 描述文字（可选） */
+.selectable-desc {
+  font: 400 16px/22px "PingFang SC", -apple-system, sans-serif;
+  color: var(--color-black-4);
+  margin-top: 2px;
+}
+
+/* 右侧：勾选图标 + 徽章 */
+.selectable-right {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+/* 勾选图标 */
+.selectable-checkbox {
+  width: 32px;
+  height: 32px;
+  flex-shrink: 0;
+}
+
+/* 统计徽章 */
+.selectable-badge {
+  display: flex;
+  align-items: center;
+  padding: 4px 8px;
+  background: var(--color-grey-2);
+  border: 1px solid var(--color-grey-3);
+  border-radius: 8px;
+  font: 400 18px/25px "PingFang SC", -apple-system, sans-serif;
+  color: var(--color-grey-7);
+}
+
+/* 分割线 */
+.selectable-divider {
+  width: 100%;
+  height: 1px;
+  background: var(--color-black-2);
+}
+```
+
+---
+
+## 颜色 Token
+
+| Token | 色值 | 使用场景 |
+|-------|------|---------|
+| `--color-grey-1` | `#FFFFFF` | 列表容器、列表项背景 |
+| `--color-grey-2` | `#F3F4F6` | 按下态背景、徽章背景 |
+| `--color-grey-3` | `#E0E4F0` | 徽章边框 |
+| `--color-grey-7` | `#383B6F` | 徽章文字 |
+| `--color-main-6` | `#6445D1` | 选中态文字 |
+| `--color-black-2` | `#DDDDDD` | 分割线 |
+| `--color-black-6` | `#333333` | 未选中文字 |
+
+---
+
+## 使用规则（AI 必读）
+
+1. **勾选图标固定 `32×32`**，比 input-row 的 Radio 图标（`28×28`）更大
+2. **两种选择模式**：`radio` 行为（单选，同一组仅一项选中）和 `checkbox` 行为（多选，可同时选多项）
+3. **选中态**：图标切为 `common_ic_check_two.svg`，文字色变为 `--color-main-6`
+4. **未选中态**：图标用 `common_ic_radio_o.svg`，文字色 `--color-black-6`
+5. **按下态必须响应**：所有列表项 `:active` 时背景变 `--color-grey-2`
+6. **右侧徽章可选**：有统计数据时展示，无统计数据时省略
+7. **分割线固定**：每行底部 `1px` `--color-black-2`，列表顶部可选
+8. **切换通过 JS**：添加/移除 `.selected` class + 替换 `img.src`，不依赖 CSS `content` 伪属性

package/spec-data/stepper.md

@@ -0,0 +1,247 @@
+---
+id: stepper
+name: 步进器
+category: "表单/Form"
+version: "1.0.0"
+source: PDAKit-业务组件
+source_url: https://mastergo.ky-tech.com.cn/goto/TZDV10eK
+source_doc_id: 103417331857122
+---
+
+# 步进器 Stepper
+
+数值步进控件，**[-] 按钮 + 数值显示 + [+] 按钮**，用于数量调整、数字输入等场景。支持边界禁用。
+
+> **核心规则**：点击 [-] 减 1，点击 [+] 加 1。数值达到最小值 ↘ [-] 禁用；达到最大值 ↗ [+] 禁用。
+> **数值范围**：`0` ~ `9999`。
+> **颜色规则**：全部使用 Token（`--color-{色系}-{色阶}`），禁止 Hex。
+> **字体**：PingFang SC。
+
+---
+
+## Props
+
+| Prop | 类型 | 值 | 默认 |
+|------|------|-----|------|
+| 数值 | number | 当前数值（0 ~ 9999） | `0` |
+| 最小值 | number | 最小允许值 | `0` |
+| 最大值 | number | 最大允许值 | `9999` |
+| 步长 | number | 每次加减量 | `1` |
+| 状态 | enum | `正常` / `禁用` | `正常` |
+| 宽度 | number | 组件整体宽度 | `146px` |
+
+---
+
+## 整体规格
+
+| 属性 | 值 |
+|------|------|
+| 宽度 | `146px` |
+| 高度 | `40px` |
+| 布局 | `flex-row`, `justify-content: center`, `align-items: center` |
+| 背景 | `--color-grey-1`（`#FFFFFF`） |
+| 描边 | `1px solid --color-black-2`（`#DDDDDD`） |
+| 圆角 | `4px` |
+
+### 内部结构
+
+```
+┌── 146px ──────────┐
+│ ┌──┐ ┌────────┐ ┌──┐ │
+│ │- │ │  9999   │ │+ │ │
+│ └──┘ └────────┘ └──┘ │
+│  40   66(flex:1)  40  │
+└──────────────────────┘
+```
+
+| 元素 | 宽 | 说明 |
+|------|:--:|------|
+| [-] 按钮 | `40px` | 左按钮，点击减 1 |
+| 数值容器 | `flex: 1` | 居中显示当前值 |
+| [+] 按钮 | `40px` | 右按钮，点击加 1 |
+
+---
+
+## 1. [-] / [+] 按钮
+
+| 属性 | 值 |
+|------|------|
+| 尺寸 | `40×40px` |
+| 图标 | `svg` 内嵌 +/- 符号 |
+
+### 按钮状态
+
+| 状态 | 外观 | 行为 |
+|------|------|------|
+| 正常 | 背景 `--color-grey-1`，图标 `--color-black-6`，可点击 | 点击执行 ±1 |
+| 禁用 | 背景 `--color-black-1`（`#EEEEEE`），图标 `--color-black-2` | 点击无响应 |
+
+---
+
+## 2. 数值显示区
+
+| 属性 | 值 |
+|------|------|
+| 宽度 | `flex: 1`（≈66px） |
+| 背景 | `transparent`（继承容器白底） |
+| 布局 | `flex-column`, `justify-content: center`, `align-items: center` |
+| 内边距 | `6px 8px` |
+| 溢出 | `overflow: hidden` |
+| 文字 | `20px / 28px`, font-weight `600`, `--color-black-6`（`#333333`）, text-align `center` |
+| 缩略 | `flex-shrink: 0` |
+
+---
+
+## 3. 边界禁用逻辑
+
+| 条件 | [-] | [+] |
+|------|:--:|:--:|
+| min < value < max | 正常 | 正常 |
+| value = min（= 0） | **禁用** | 正常 |
+| value = max（= 9999） | 正常 | **禁用** |
+
+---
+
+## CSS 示例
+
+```css
+.stepper {
+  width: 146px;
+  height: 40px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  flex-shrink: 0;
+  background: var(--color-grey-1);
+  border: 1px solid var(--color-black-2);
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+.stepper-btn {
+  width: 40px;
+  height: 40px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  cursor: pointer;
+  flex-shrink: 0;
+  border: none;
+  background: var(--color-grey-1);
+  color: var(--color-black-6);
+}
+.stepper-btn:active:not(.disabled) { opacity: 0.7; }
+.stepper-btn.disabled {
+  background: var(--color-black-1);
+  color: var(--color-black-2);
+  cursor: not-allowed;
+  pointer-events: none;
+}
+.stepper-btn svg {
+  width: 24px;
+  height: 24px;
+}
+
+.stepper-value {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  padding: 6px 8px;
+  overflow: hidden;
+}
+.stepper-value-text {
+  flex-shrink: 0;
+  color: var(--color-black-6);
+  font-size: 20px;
+  line-height: 28px;
+  font-weight: 600;
+  font-family: PingFang SC;
+  text-align: center;
+}
+```
+
+---
+
+## HTML 骨架
+
+```html
+<div class="stepper" id="stepper">
+  <!-- [-] 按钮 -->
+  <button class="stepper-btn" onclick="stepDown()">
+    <svg viewBox="0 0 24 24" fill="none">
+      <rect x="4" y="11" width="16" height="2" rx="1" fill="currentColor"/>
+    </svg>
+  </button>
+
+  <!-- 数值 -->
+  <div class="stepper-value">
+    <span class="stepper-value-text">0</span>
+  </div>
+
+  <!-- [+] 按钮 -->
+  <button class="stepper-btn" onclick="stepUp()">
+    <svg viewBox="0 0 24 24" fill="none">
+      <rect x="4" y="11" width="16" height="2" rx="1" fill="currentColor"/>
+      <rect x="11" y="4" width="2" height="16" rx="1" fill="currentColor"/>
+    </svg>
+  </button>
+</div>
+```
+
+---
+
+## JS 交互逻辑
+
+```javascript
+let value = 0;
+const min = 0;
+const max = 9999;
+
+function stepUp() {
+  if (value >= max) return;
+  value += 1;
+  render();
+}
+
+function stepDown() {
+  if (value <= min) return;
+  value -= 1;
+  render();
+}
+
+function render() {
+  document.getElementById('stepperValue').textContent = value;
+
+  const btnMinus = document.getElementById('btnMinus');
+  const btnPlus = document.getElementById('btnPlus');
+
+  btnMinus.classList.toggle('disabled', value <= min);
+  btnPlus.classList.toggle('disabled', value >= max);
+}
+```
+
+---
+
+## ⚙️ PDA 硬性约束
+
+| # | 约束 | 值 | 原因 |
+|---|------|-----|------|
+| 1 | 最小触控热区 | [-] [+] 按钮 **40×40px** | 仓储手套操作 |
+| 2 | 数值范围 | **0 ~ 9999** | 上限防止溢出 |
+| 3 | 字体下界 | 数值文字 ≥ 20px, font-weight 600 | 小屏可读性 |
+| 4 | 边界禁用 | 值=min 时 [-] 禁用；值=max 时 [+] 禁用 | 防止越界 |
+| 5 | 禁用反馈 | 按钮背景变 `--color-black-1`（`#EEEEEE`）+ 图标变 `--color-black-2` + cursor: not-allowed | 明确不可操作 |
+
+---
+
+## 🔴 常见 AI 错误
+
+| # | ❌ 错误 | ✅ 正确 |
+|---|--------|--------|
+| 1 | [-] [+] 按钮用文字而非图标 | 必须用 SVG 图标，40×40px |
+| 2 | 数值范围未限制 | min=0, max=9999，边界禁用 |
+| 3 | 数值文字未加粗 | font-weight: 600 |
+| 4 | 组件宽度随意 | 固定 `146px` |
+| 5 | 点击边界不阻止 | 值=min 时 stepDown 直接 return，不加也不减 |