iter(g52): 新增 colorPicker 颜色选择组件

2026-10-26 12:16:11 +08:00
parent 95b46a05e7
commit 81ea18936c
12 changed files with 370 additions and 10 deletions
@@ -0,0 +1,99 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import type { Signal } from '@ui-arch/frame';
+import { pushOverlay } from './overlay.js';
+import { flip } from './position.js';
+import type { ColorPickerProps } from './types.js';
+
+// 缺省色板：直接取语义令牌，天然跟随暗色主题切换，不写死任何十六进制
+const DEFAULT_PRESETS = ['var(--ua-color-accent)', 'var(--ua-color-success)', 'var(--ua-color-warning)', 'var(--ua-color-danger)', 'var(--ua-color-text)', 'var(--ua-color-border)'];
+
+/*** 颜色选择：色板点选 + 自定义取色 / 手输，value 信号双向绑定，Esc 收起，色块本身即预览 ***/ 
+export function colorPicker(props: ColorPickerProps): HTMLElement {
+  // —— 状态集中声明 ——
+  const value: Signal<string> = props.value ?? signal(''); // 当前颜色
+  const open = signal(false);                              // 弹层开合
+  const place = signal<'top' | 'bottom'>('bottom');        // 实际方位
+  const presets = props.presets ?? DEFAULT_PRESETS;        // 预设色板
+  let releaseEsc: (() => void) | null = null;              // Esc 栈注销函数
+
+  /*** 提交颜色：写信号 + 回调 + 收起，输入框同步回填便于手改 ***/
+  const commit = (color: string): void => {
+    const c = color.trim();
+    if (!c) return; // 卫语句：空值不提交
+    value(c);
+    props.onChange?.(c);
+    open(false);
+    trigger.focus();
+  };
+
+  const swatch = h('span', { class: 'ua-colorpicker-swatch', 'aria-hidden': 'true' }) as HTMLElement;
+  const trigger = h(
+    'button',
+    {
+      type: 'button',
+      class: 'ua-colorpicker-trigger',
+      'aria-haspopup': 'dialog',
+      'aria-expanded': () => String(open()),
+      disabled: props.disabled,
+      onClick: () => open(!open()),
+    },
+    swatch,
+    h('span', { class: () => `ua-colorpicker-value${value() ? '' : ' is-empty'}` }, () => value() || props.placeholder || '请选择颜色'),
+    h('span', { class: 'ua-colorpicker-caret', 'aria-hidden': 'true' }, '▾'),
+  );
+
+  // 预设色板：每个色块是一颗按钮，选中项描边标记
+  const grid = h('div', { class: 'ua-colorpicker-grid', role: 'listbox', 'aria-label': '预设颜色' });
+  const cells = presets.map((c) =>
+    h('button', {
+      type: 'button',
+      class: () => `ua-colorpicker-cell${value() === c ? ' is-selected' : ''}`,
+      role: 'option',
+      'aria-selected': () => String(value() === c),
+      'aria-label': c,
+      title: c,
+      style: `background:${c}`, // 色块底色直接取预设值（令牌或自定义色）
+      onClick: () => commit(c),
+    }),
+  );
+  grid.append(...cells);
+
+  // 自定义区：原生取色器负责拾色，文本框负责粘 CSS 颜色串（含 var(--ua-*)）
+  const native = h('input', { type: 'color', class: 'ua-colorpicker-native', 'aria-label': '取色器', value: () => (/^#[0-9a-f]{6}$/i.test(value()) ? value() : '#000000') }) as HTMLInputElement;
+  native.addEventListener('input', () => commit(native.value));
+  const hex = h('input', {
+    type: 'text',
+    class: 'ua-colorpicker-hex',
+    placeholder: 'CSS 颜色，如 var(--ua-color-accent)',
+    'aria-label': '颜色值',
+    value: () => value(),
+    onkeydown: (e: KeyboardEvent) => {
+      if (e.key !== 'Enter') return; // 卫语句：只处理回车提交
+      e.preventDefault();
+      commit((e.target as HTMLInputElement).value);
+    },
+  }) as HTMLInputElement;
+
+  const pop = h(
+    'div',
+    { class: () => `ua-colorpicker-pop${open() ? ' ua-open' : ''}${place() === 'top' ? ' is-flip' : ''}` },
+    grid,
+    h('div', { class: 'ua-colorpicker-custom' }, native, hex),
+  );
+  const root = h('div', { class: () => `ua-colorpicker${open() ? ' ua-open' : ''}` }, trigger, pop) as HTMLElement;
+
+  document.addEventListener('click', (e) => {
+    if (root.contains(e.target as Node)) return; // 卫语句：组件内点击不处理
+    open(false);
+  });
+  effect(() => {
+    swatch.style.background = value() || 'transparent'; // 触发器色块实时预览
+    swatch.classList.toggle('is-empty', !value());
+  });
+  effect(() => {
+    if (open()) releaseEsc ??= pushOverlay(() => { open(false); trigger.focus(); }); // 入栈逐层关闭
+    else { releaseEsc?.(); releaseEsc = null; }
+  });
+  effect(() => { if (open()) place(flip(trigger, pop, 'bottom')); });
+  return root;
+}
@@ -50,3 +50,4 @@ export { splitter } from './splitter.js';
 export { autoComplete } from './autoComplete.js';
 export { datePicker } from './datePicker.js';
 export { backTop } from './backTop.js';
+export { colorPicker } from './colorPicker.js';
@@ -559,4 +559,13 @@ export interface BackTopProps {
  onClick?: () => void;          // 点回顶部之后的回调（如埋点）
 }

+/*** 颜色选择入参 ***/
+export interface ColorPickerProps {
+  value?: Signal<string>;                 // 颜色值（CSS 颜色串，如 var(--ua-color-accent) 或 #1f6feb）
+  presets?: string[];                     // 预设色板；缺省取语义令牌色
+  placeholder?: string;                   // 未选时占位文案；缺省「请选择颜色」
+  disabled?: boolean | Signal<boolean>;   // 禁用触发器
+  onChange?: (color: string) => void;     // 选定回调（色板或自定义输入）
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方
@@ -64,7 +64,8 @@
      "splitter(props)：可拖拽分栏容器，分隔条支持指针拖拽 / 方向键微调 / 双击复位，sizes 为百分比数组信号",
      "autoComplete(props)：输入联想，输入即过滤候选、↑↓ 环形高亮 / Enter 选中 / Esc 收起，options 可传函数做远程联想",
      "datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航",
-      "backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶"
+      "backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶",
+      "colorPicker(props)：颜色选择，预设色板（缺省语义令牌色）+ 原生取色器 + 手输 CSS 颜色串，value 为颜色串信号"
    ],
    "keyTypes": [
      "ButtonProps",
@@ -2204,6 +2205,45 @@
          "progress 为 true 时外环弧长等于已滚比例；内滚容器用 target 传入该元素",
          "点击平滑回顶；系统开启「减少动效」时改为瞬间跳转"
        ]
+      },
+      {
+        "id": "colorPicker",
+        "title": "颜色选择 ColorPicker",
+        "demo": "sec-colorpicker",
+        "props": [
+          {
+            "n": "value",
+            "t": "Signal<string>",
+            "d": "颜色值信号（CSS 颜色串，支持 var(--ua-*)）；不传则内部维护"
+          },
+          {
+            "n": "presets",
+            "t": "string[]",
+            "d": "预设色板；缺省取语义令牌色（accent/success/warning/danger/text/border）"
+          },
+          {
+            "n": "placeholder",
+            "t": "string",
+            "d": "未选时占位文案；缺省「请选择颜色」"
+          },
+          {
+            "n": "disabled",
+            "t": "boolean | Signal<boolean>",
+            "d": "禁用触发器"
+          },
+          {
+            "n": "onChange",
+            "t": "(color: string) => void",
+            "d": "选定回调（点色板、取色器或手输回车）"
+          }
+        ],
+        "example": "colorPicker({ value: colorVal, onChange: (c) => toast.success(c) })",
+        "steps": [
+          "点触发器展开弹层：上方是预设色板，下方是原生取色器 + 手输框",
+          "预设缺省直接用 --ua-* 令牌色，所以暗色主题切换后色块自动跟着变，无需维护两套色值",
+          "点色块即提交；手输框支持任意 CSS 颜色串（含 var(--ua-color-accent)），回车提交",
+          "触发器左侧色块始终预览当前值，点击外部或 Esc 收起"
+        ]
      }
    ]
  }
@@ -3014,3 +3014,132 @@ button.ua-step-dot:hover {
    transition: none;
  }
 }
+.ua-colorpicker {
+  position: relative;
+  display: inline-block;
+  min-width: 200px;
+}
+.ua-colorpicker-trigger {
+  display: flex;
+  align-items: center;
+  gap: var(--ua-space-1);
+  width: 100%;
+  padding: 6px var(--ua-space-2);
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text);
+  background: var(--ua-color-surface);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  cursor: pointer;
+  transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+.ua-colorpicker-trigger:hover {
+  border-color: var(--ua-color-accent);
+}
+.ua-colorpicker-trigger:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.ua-colorpicker.ua-open .ua-colorpicker-trigger {
+  border-color: var(--ua-color-accent);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--ua-color-accent) 18%, transparent);
+}
+.ua-colorpicker-swatch {
+  flex: 0 0 auto;
+  width: 14px;
+  height: 14px;
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+}
+.ua-colorpicker-value {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  text-align: left;
+}
+.ua-colorpicker-value.is-empty {
+  color: var(--ua-color-text-muted);
+}
+.ua-colorpicker-caret {
+  font-size: 10px;
+  color: var(--ua-color-text-muted);
+}
+.ua-colorpicker-pop {
+  position: absolute;
+  z-index: 40;
+  display: none;
+  width: 232px;
+  margin-top: 6px;
+  padding: var(--ua-space-2);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-surface);
+  box-shadow: 0 12px 28px rgba(0, 0, 0, 0.18);
+}
+.ua-colorpicker-pop.ua-open {
+  display: block;
+  animation: ua-cp-in 0.15s ease both;
+}
+.ua-colorpicker-pop.is-flip {
+  margin-top: 0;
+  margin-bottom: 6px;
+}
+.ua-colorpicker-grid {
+  display: grid;
+  grid-template-columns: repeat(6, 1fr);
+  gap: var(--ua-space-1);
+}
+.ua-colorpicker-cell {
+  aspect-ratio: 1;
+  padding: 0;
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  cursor: pointer;
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+.ua-colorpicker-cell:hover {
+  transform: translateY(-1px);
+}
+.ua-colorpicker-cell.is-selected {
+  box-shadow: 0 0 0 2px var(--ua-color-accent);
+}
+.ua-colorpicker-custom {
+  display: flex;
+  gap: var(--ua-space-1);
+  margin-top: var(--ua-space-2);
+}
+.ua-colorpicker-native {
+  flex: 0 0 auto;
+  width: 34px;
+  height: 30px;
+  padding: 0;
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  background: transparent;
+  cursor: pointer;
+}
+.ua-colorpicker-hex {
+  flex: 1;
+  min-width: 0;
+  padding: 4px var(--ua-space-1);
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text);
+  background: var(--ua-color-bg);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-sm);
+  outline: none;
+}
+.ua-colorpicker-hex:focus {
+  border-color: var(--ua-color-accent);
+}
+@keyframes ua-cp-in {
+  from { opacity: 0; transform: translateY(-4px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ua-colorpicker-pop.ua-open { animation: none; }
+  .ua-colorpicker-trigger,
+  .ua-colorpicker-cell { transition: none; }
+}