@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/color-picker/meta.md

@@ -0,0 +1,83 @@
+# ColorPicker
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+颜色选择器 ColorPicker
+完整的颜色选取器 — 色相/饱和度/明度面板 + 色相滑条 + 透明度滑条 +
+格式切换 (hex/rgb/hsb) + 预设色板分组，支持受控/非受控、自定义触发器。
+
+## 使用场景
+
+- 主题定制 / 品牌色设置
+- 图表 / 可视化编辑器中选色
+- 标签 / 分类颜色标注
+- 需要精确颜色输入（含 alpha 透明度）时
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `"sm" \| "default" \| "lg"` | `"default"` | – | – |
+| `value` | `string \| Color` | – | – | 当前颜色值（受控）。 |
+| `defaultValue` | `string \| Color` | – | – | 默认颜色值。@default "#1677ff" |
+| `format` | `ColorFormat` | – | – | 颜色格式。@default "hex" |
+| `defaultFormat` | `ColorFormat` | – | – | 默认颜色格式（非受控）。@default "hex" |
+| `onFormatChange` | `(format: ColorFormat) => void` | – | – | 格式变化回调。 |
+| `presets` | `ColorPresets` | – | – | 预设色板 — 字符串数组或分组数组。 |
+| `disabled` | `boolean` | – | – | 是否禁用。@default false |
+| `onChange` | `(color: Color, hex: string) => void` | – | – | 颜色变化回调（拖拽中持续触发）。 |
+| `onChangeComplete` | `(color: Color, hex: string) => void` | – | – | 颜色变化完成回调（拖拽松手 / 输入确认后触发）。 |
+| `showText` | `boolean \| ((color: Color) => React.ReactNode)` | – | – | 触发器旁显示颜色文本。 |
+| `allowClear` | `boolean` | – | – | 允许清除。@default false |
+| `onClear` | `() => void` | – | – | 清除回调。 |
+| `disabledAlpha` | `boolean` | – | – | 禁用透明度通道。@default false |
+| `open` | `boolean` | – | – | 受控弹出状态。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 弹出状态变化回调。 |
+| `children` | `React.ReactNode` | – | – | 自定义触发器。 |
+| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | – | – | 弹出位置。@default "bottom" |
+
+## 示例
+
+### Sizes
+
+```tsx
+<div className="flex items-center gap-3">
+  <ColorPicker size="sm" defaultValue="#52c41a" />
+  <ColorPicker size="default" defaultValue="#1677ff" />
+  <ColorPicker size="lg" defaultValue="#ff4d4f" />
+</div>
+```
+
+### ShowText
+
+```tsx
+<div className="flex flex-col gap-3">
+  <ColorPicker defaultValue="#1677ff" showText />
+  <ColorPicker
+    defaultValue="#52c41a"
+    showText={(c) => <span>{c.toRgbString()}</span>}
+  />
+</div>
+```
+
+### FormatSwitch
+
+```tsx
+<div className="flex flex-col gap-3">
+  <ColorPicker defaultValue="#1677ff" defaultFormat="hex" showText />
+  <ColorPicker defaultValue="#1677ff" defaultFormat="rgb" showText />
+  <ColorPicker defaultValue="#1677ff" defaultFormat="hsb" showText />
+</div>
+```
+
+### CustomTrigger
+
+```tsx
+<ColorPicker defaultValue="#722ed1">
+  <Button variant="outline" size="sm">
+    选择颜色
+  </Button>
+</ColorPicker>
+```

package/src/components/color-picker/stories.tsx

@@ -0,0 +1,172 @@
+/* eslint-disable teamix-evo/no-color-literal -- ColorPicker stories inherently use color hex values as test data */
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Button } from '@/components/button';
+
+import { ColorPicker, Color } from '.';
+
+const meta: Meta<typeof ColorPicker> = {
+  title: '数据录入 · Data Entry/ColorPicker 颜色选择器',
+  component: ColorPicker,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '颜色选择器 — 色相/饱和度/明度面板 + 色相/透明度滑条 + 格式切换 + 预设色板。',
+      },
+    },
+  },
+  decorators: [(Story) => <div className="pb-80"><Story /></div>],
+};
+
+export default meta;
+type Story = StoryObj<typeof ColorPicker>;
+
+export const Basic: Story = {
+  name: '基础选择',
+  args: {},
+};
+
+export const DefaultValue: Story = {
+  name: '默认值',
+  args: { defaultValue: '#52c41a' },
+};
+
+export const Sizes: Story = {
+  name: '尺寸',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-3">
+      <ColorPicker size="sm" defaultValue="#52c41a" />
+      <ColorPicker size="default" defaultValue="#1677ff" />
+      <ColorPicker size="lg" defaultValue="#ff4d4f" />
+    </div>
+  ),
+};
+
+export const ShowText: Story = {
+  name: '显示颜色文本',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <ColorPicker defaultValue="#1677ff" showText />
+      <ColorPicker
+        defaultValue="#52c41a"
+        showText={(c) => <span>{c.toRgbString()}</span>}
+      />
+    </div>
+  ),
+};
+
+export const FormatSwitch: Story = {
+  name: '格式切换',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <ColorPicker defaultValue="#1677ff" defaultFormat="hex" showText />
+      <ColorPicker defaultValue="#1677ff" defaultFormat="rgb" showText />
+      <ColorPicker defaultValue="#1677ff" defaultFormat="hsb" showText />
+    </div>
+  ),
+};
+
+export const DisabledAlpha: Story = {
+  name: '禁用透明度',
+  args: { disabledAlpha: true, defaultValue: '#1677ff' },
+};
+
+export const AllowClear: Story = {
+  name: '允许清除',
+  args: { allowClear: true, defaultValue: '#faad14' },
+};
+
+export const PresetFlat: Story = {
+  name: '预设色板（扁平）',
+  args: {
+    defaultValue: '#1677ff',
+    presets: [
+      '#f5222d', '#fa541c', '#fa8c16', '#faad14', '#fadb14', '#a0d911',
+      '#52c41a', '#13c2c2', '#1677ff', '#2f54eb', '#722ed1', '#eb2f96',
+    ],
+  },
+};
+
+export const PresetGroups: Story = {
+  name: '预设色板（分组）',
+  args: {
+    defaultValue: '#1677ff',
+    presets: [
+      {
+        label: '推荐色',
+        colors: ['#f5222d', '#fa8c16', '#fadb14', '#52c41a', '#1677ff', '#722ed1'],
+      },
+      {
+        label: '中性色',
+        colors: ['#000000', '#434343', '#8c8c8c', '#bfbfbf', '#d9d9d9', '#ffffff'],
+        defaultOpen: false,
+      },
+    ],
+  },
+};
+
+export const Controlled: Story = {
+  name: '受控模式',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [color, setColor] = React.useState(new Color('#1677ff'));
+    return (
+      <div className="flex items-center gap-3">
+        <ColorPicker
+          value={color}
+          onChange={(c) => setColor(c)}
+          showText
+        />
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => setColor(new Color('#ff4d4f'))}
+        >
+          设为红色
+        </Button>
+      </div>
+    );
+  },
+};
+
+export const OnChangeComplete: Story = {
+  name: 'onChangeComplete',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [hex, setHex] = React.useState('#1677ff');
+    return (
+      <div className="flex items-center gap-3">
+        <ColorPicker
+          defaultValue="#1677ff"
+          onChangeComplete={(c) => setHex(c.toHex())}
+        />
+        <span className="text-xs text-muted-foreground">
+          完成选色: {hex}
+        </span>
+      </div>
+    );
+  },
+};
+
+export const CustomTrigger: Story = {
+  name: '自定义触发器',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ColorPicker defaultValue="#722ed1">
+      <Button variant="outline" size="sm">
+        选择颜色
+      </Button>
+    </ColorPicker>
+  ),
+};
+
+export const Disabled: Story = {
+  name: '禁用',
+  args: { disabled: true, defaultValue: '#faad14' },
+};