@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/cascader-select/stories.tsx

@@ -0,0 +1,118 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import * as React from 'react';
+
+import { CascaderSelect } from '.';
+import type { CascaderOption } from '.';
+
+const options: CascaderOption[] = [
+  {
+    value: 'zhejiang',
+    label: '浙江',
+    children: [
+      {
+        value: 'hangzhou',
+        label: '杭州',
+        children: [
+          { value: 'xihu', label: '西湖区' },
+          { value: 'binjiang', label: '滨江区' },
+        ],
+      },
+      {
+        value: 'ningbo',
+        label: '宁波',
+        children: [
+          { value: 'yinzhou', label: '鄞州区' },
+          { value: 'haishu', label: '海曙区' },
+        ],
+      },
+    ],
+  },
+  {
+    value: 'jiangsu',
+    label: '江苏',
+    children: [
+      {
+        value: 'nanjing',
+        label: '南京',
+        children: [
+          { value: 'xuanwu', label: '玄武区' },
+          { value: 'jianye', label: '建邺区' },
+        ],
+      },
+    ],
+  },
+];
+
+const meta: Meta<typeof CascaderSelect> = {
+  title: '数据录入 · Data Entry/CascaderSelect 级联选择',
+  component: CascaderSelect,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '级联选择 — 多层级数据的逐级选择，适合省/市/区、分类目录等场景。',
+      },
+    },
+    layout: 'padded',
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ minHeight: 160 }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof CascaderSelect>;
+
+export const Basic: Story = {
+  name: '基础级联',
+  args: { options },
+};
+
+export const DefaultValue: Story = {
+  name: '默认值',
+  args: { options, defaultValue: ['zhejiang', 'hangzhou', 'xihu'] },
+};
+
+export const SmallSize: Story = {
+  name: '小尺寸',
+  args: { options, size: 'sm' },
+};
+
+export const Disabled: Story = {
+  name: '禁用',
+  args: {
+    options,
+    disabled: true,
+    defaultValue: ['jiangsu', 'nanjing', 'xuanwu'],
+  },
+};
+
+/** 有选中值时右侧 chevron 切为 ×，点击清空。优先级：loading > clear > chevron。 */
+export const WithClear: Story = {
+  name: '可清除',
+  render: () => {
+    const [value, setValue] = React.useState<string[]>([
+      'zhejiang',
+      'hangzhou',
+      'xihu',
+    ]);
+    return (
+      <CascaderSelect
+        options={options}
+        value={value}
+        onChange={(next) => setValue(next)}
+      />
+    );
+  },
+};
+
+/** 加载态：`loading` 为 `true` 时右侧图标替换为旋转 spinner。 */
+export const Loading: Story = {
+  name: '加载态',
+  args: { options, loading: true },
+};

package/src/components/checkbox/index.tsx

@@ -0,0 +1,208 @@
+/**
+ * 多选框 Checkbox
+ *
+ * 在一组选项中进行多项选择，或单独表示「是/否」状态切换。
+ *
+ * @when
+ * - 需要用户在一组选项中选择多个时（搭配 CheckboxGroup）
+ * - 需要表示单个布尔开关（如「同意条款」）时
+ * - 需要表达「部分选中」中间态（如树形选择父级、表格全选半选）时
+ *
+ * 组合结构：CheckboxGroup > Checkbox（dataSource 数组驱动 或 children 自由组合）
+ */
+
+import * as React from 'react';
+import { Checkbox as CheckboxPrimitive } from 'radix-ui';
+import { CheckIcon, MinusIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+// ─── Group Context ──────────────────────────────────────────────────────────
+
+interface CheckboxGroupContextValue {
+  value: string[];
+  onItemChange: (value: string, checked: boolean) => void;
+  disabled?: boolean;
+}
+
+const CheckboxGroupContext =
+  React.createContext<CheckboxGroupContextValue | null>(null);
+
+// ─── Checkbox ───────────────────────────────────────────────────────────────
+
+export interface CheckboxProps
+  extends Omit<
+    React.ComponentProps<typeof CheckboxPrimitive.Root>,
+    'checked' | 'defaultChecked' | 'onCheckedChange'
+  > {
+  /** 受控选中状态，可为布尔值或 'indeterminate'。 */
+  checked?: boolean | 'indeterminate';
+  /** 默认选中状态（非受控）。@default false */
+  defaultChecked?: boolean | 'indeterminate';
+  /** 选中状态变化回调。 */
+  onCheckedChange?: (checked: boolean | 'indeterminate') => void;
+  /**
+   * 中间态便利 prop（等价于 checked='indeterminate'）。
+   * 仅影响视觉，不改变实际 checked 值。
+   */
+  indeterminate?: boolean;
+  /** 表单值；在 CheckboxGroup 内同时作为分组 key。 */
+  value?: string;
+}
+
+function Checkbox({
+  className,
+  checked,
+  defaultChecked,
+  onCheckedChange,
+  indeterminate,
+  disabled,
+  value,
+  ...props
+}: CheckboxProps) {
+  const groupCtx = React.useContext(CheckboxGroupContext);
+  const inGroup = groupCtx !== null && value !== undefined;
+
+  // 在 group 内时 checked / onCheckedChange / disabled 由 group 接管
+  const resolvedChecked = inGroup
+    ? groupCtx!.value.includes(value!)
+    : indeterminate
+    ? 'indeterminate'
+    : checked;
+  const resolvedDisabled = inGroup ? groupCtx!.disabled || disabled : disabled;
+  const handleChange = inGroup
+    ? (next: boolean | 'indeterminate') =>
+        groupCtx!.onItemChange(value!, next === true)
+    : onCheckedChange;
+
+  return (
+    <CheckboxPrimitive.Root
+      data-slot="checkbox"
+      checked={resolvedChecked}
+      defaultChecked={inGroup ? undefined : defaultChecked}
+      onCheckedChange={handleChange}
+      disabled={resolvedDisabled}
+      value={value}
+      className={cn(
+        'peer relative flex size-4 shrink-0 cursor-pointer items-center justify-center rounded-(--radius-checkbox) border border-input transition-colors outline-none group-has-disabled/field:opacity-50 after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=indeterminate]:border-primary data-[state=indeterminate]:bg-primary data-[state=indeterminate]:text-primary-foreground',
+        className,
+      )}
+      {...props}
+    >
+      <CheckboxPrimitive.Indicator
+        data-slot="checkbox-indicator"
+        className="grid place-content-center text-current transition-none [&>svg]:size-3.5"
+      >
+        {resolvedChecked === 'indeterminate' ? <MinusIcon /> : <CheckIcon />}
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  );
+}
+
+// ─── CheckboxGroup ──────────────────────────────────────────────────────────
+
+/** CheckboxGroup 选项数据项（对象形式）。 */
+export interface CheckboxOption {
+  /** 选项值。 */
+  value: string;
+  /** 选项展示文本（不传则回退为 value）。 */
+  label?: React.ReactNode;
+  /** 单项禁用。 */
+  disabled?: boolean;
+}
+
+export interface CheckboxGroupProps
+  extends Omit<React.ComponentProps<'div'>, 'onChange' | 'defaultValue'> {
+  /**
+   * 数据驱动模式的选项列表。
+   * 每项可为字符串（同时作为 value 与 label）或对象（{ value, label?, disabled? }）。
+   */
+  dataSource?: Array<string | CheckboxOption>;
+  /** 受控选中值列表。 */
+  value?: string[];
+  /** 默认选中值列表（非受控）。 */
+  defaultValue?: string[];
+  /** 选中值变化回调，参数为最新选中值数组。 */
+  onChange?: (value: string[]) => void;
+  /** 整体禁用（覆盖单项 disabled = true）。 */
+  disabled?: boolean;
+  /** 排列方向。 @default 'horizontal' */
+  direction?: 'horizontal' | 'vertical';
+  /** 子元素模式（与 dataSource 互斥；children 模式下子项需通过 value prop 关联分组）。 */
+  children?: React.ReactNode;
+}
+
+function CheckboxGroup({
+  dataSource,
+  value,
+  defaultValue,
+  onChange,
+  disabled,
+  direction = 'horizontal',
+  children,
+  className,
+  ...props
+}: CheckboxGroupProps) {
+  const isControlled = value !== undefined;
+  const [internalValue, setInternalValue] = React.useState<string[]>(
+    defaultValue ?? [],
+  );
+  const currentValue = isControlled ? value ?? [] : internalValue;
+
+  const onItemChange = React.useCallback(
+    (itemValue: string, checked: boolean) => {
+      const next = checked
+        ? currentValue.includes(itemValue)
+          ? currentValue
+          : [...currentValue, itemValue]
+        : currentValue.filter((v) => v !== itemValue);
+      if (!isControlled) setInternalValue(next);
+      onChange?.(next);
+    },
+    [currentValue, isControlled, onChange],
+  );
+
+  const ctxValue = React.useMemo<CheckboxGroupContextValue>(
+    () => ({ value: currentValue, onItemChange, disabled }),
+    [currentValue, onItemChange, disabled],
+  );
+
+  return (
+    <CheckboxGroupContext.Provider value={ctxValue}>
+      <div
+        data-slot="checkbox-group"
+        data-direction={direction}
+        role="group"
+        className={cn(
+          'flex',
+          direction === 'horizontal'
+            ? 'flex-row flex-wrap gap-x-4 gap-y-2'
+            : 'flex-col gap-2',
+          className,
+        )}
+        {...props}
+      >
+        {dataSource?.map((raw) => {
+          const opt: CheckboxOption =
+            typeof raw === 'string' ? { value: raw, label: raw } : raw;
+          return (
+            <label
+              key={opt.value}
+              data-slot="checkbox-group-item"
+              className={cn(
+                'inline-flex cursor-pointer items-center gap-2 text-xs',
+                (opt.disabled || disabled) && 'cursor-not-allowed opacity-50',
+              )}
+            >
+              <Checkbox value={opt.value} disabled={opt.disabled} />
+              <span>{opt.label ?? opt.value}</span>
+            </label>
+          );
+        })}
+        {children}
+      </div>
+    </CheckboxGroupContext.Provider>
+  );
+}
+
+export { Checkbox, CheckboxGroup };

package/src/components/checkbox/meta.md

@@ -0,0 +1,166 @@
+# Checkbox
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+多选框 Checkbox
+在一组选项中进行多项选择，或单独表示「是/否」状态切换。
+
+## 使用场景
+
+- 需要用户在一组选项中选择多个时（搭配 CheckboxGroup）
+- 需要表示单个布尔开关（如「同意条款」）时
+- 需要表达「部分选中」中间态（如树形选择父级、表格全选半选）时
+- 组合结构：CheckboxGroup > Checkbox（dataSource 数组驱动 或 children 自由组合）
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `checked` | `boolean \| 'indeterminate'` | – | – | 受控选中状态，可为布尔值或 'indeterminate'。 |
+| `defaultChecked` | `boolean \| 'indeterminate'` | – | – | 默认选中状态（非受控）。@default false |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | – | – | 选中状态变化回调。 |
+| `indeterminate` | `boolean` | – | – | 中间态便利 prop（等价于 checked='indeterminate'）。 仅影响视觉，不改变实际 checked 值。 |
+| `value` | `string` | – | – | 表单值；在 CheckboxGroup 内同时作为分组 key。 |
+| `dataSource` | `Array<string \| CheckboxOption>` | – | – | 数据驱动模式的选项列表。 每项可为字符串（同时作为 value 与 label）或对象（{ value, label?, disabled? }）。 |
+| `value` | `string[]` | – | – | 受控选中值列表。 |
+| `defaultValue` | `string[]` | – | – | 默认选中值列表（非受控）。 |
+| `onChange` | `(value: string[]) => void` | – | – | 选中值变化回调，参数为最新选中值数组。 |
+| `disabled` | `boolean` | – | – | 整体禁用（覆盖单项 disabled = true）。 |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | – | 排列方向。 |
+| `children` | `React.ReactNode` | – | – | 子元素模式（与 dataSource 互斥；children 模式下子项需通过 value prop 关联分组）。 |
+
+## 示例
+
+### Checked
+
+默认选中状态。
+
+```tsx
+<div className="flex items-center gap-2">
+  <Checkbox id="checked" defaultChecked />
+  <label htmlFor="checked" className="text-xs">
+    已选中
+  </label>
+</div>
+```
+
+### Indeterminate
+
+中间态：用于树形/全选半选场景，可用 `indeterminate` 便利 prop 或 `checked='indeterminate'`。
+
+```tsx
+<div className="flex items-center gap-2">
+  <Checkbox id="indet" indeterminate />
+  <label htmlFor="indet" className="text-xs">
+    部分选中
+  </label>
+</div>
+```
+
+### Disabled
+
+禁用状态。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex items-center gap-2">
+    <Checkbox id="disabled-unchecked" disabled />
+    <label
+      htmlFor="disabled-unchecked"
+      className="text-xs text-muted-foreground"
+    >
+      禁用未选中
+    </label>
+  </div>
+  <div className="flex items-center gap-2">
+    <Checkbox id="disabled-checked" disabled defaultChecked />
+    <label
+      htmlFor="disabled-checked"
+      className="text-xs text-muted-foreground"
+    >
+      禁用已选中
+    </label>
+  </div>
+</div>
+```
+
+### Group
+
+CheckboxGroup 数据驱动模式（默认横向排列）。
+
+```tsx
+<CheckboxGroup
+  defaultValue={['banana']}
+  dataSource={['apple', 'banana', 'orange']}
+/>
+```
+
+### GroupWithOptions
+
+CheckboxGroup 对象形式 dataSource，支持自定义 label 与单项禁用。
+
+```tsx
+<CheckboxGroup
+  defaultValue={['apple']}
+  dataSource={[
+    { value: 'apple', label: '苹果' },
+    { value: 'banana', label: '香蕉' },
+    { value: 'orange', label: '橙子', disabled: true },
+  ]}
+/>
+```
+
+### GroupVertical
+
+CheckboxGroup 纵向排列。
+
+```tsx
+<CheckboxGroup
+  direction="vertical"
+  defaultValue={['banana']}
+  dataSource={[
+    { value: 'apple', label: '苹果' },
+    { value: 'banana', label: '香蕉' },
+    { value: 'orange', label: '橙子' },
+  ]}
+/>
+```
+
+### GroupDisabled
+
+CheckboxGroup 整组禁用。
+
+```tsx
+<CheckboxGroup
+  disabled
+  defaultValue={['apple']}
+  dataSource={[
+    { value: 'apple', label: '苹果' },
+    { value: 'banana', label: '香蕉' },
+    { value: 'orange', label: '橙子' },
+  ]}
+/>
+```
+
+### GroupWithChildren
+
+CheckboxGroup children 模式：自由组合 Checkbox 子元素，仍由 group 接管选中状态。
+
+```tsx
+<CheckboxGroup defaultValue={['banana']} direction="vertical">
+  <label className="inline-flex cursor-pointer items-center gap-2 text-xs">
+    <Checkbox value="apple" />
+    <span>苹果（自定义渲染）</span>
+  </label>
+  <label className="inline-flex cursor-pointer items-center gap-2 text-xs">
+    <Checkbox value="banana" />
+    <span>香蕉（自定义渲染）</span>
+  </label>
+  <label className="inline-flex cursor-pointer items-center gap-2 text-xs">
+    <Checkbox value="orange" />
+    <span>橙子（自定义渲染）</span>
+  </label>
+</CheckboxGroup>
+```

package/src/components/checkbox/stories.tsx

@@ -0,0 +1,206 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import * as React from 'react';
+import { Checkbox, CheckboxGroup } from './index';
+
+const meta: Meta<typeof Checkbox> = {
+  title: '数据录入 · Data Entry/Checkbox 多选框',
+  component: Checkbox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { source: { type: 'dynamic' } },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 默认未选中的复选框，搭配外部 label 使用。 */
+export const Default: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Checkbox id="terms" />
+      <label htmlFor="terms" className="text-xs">
+        同意服务条款
+      </label>
+    </div>
+  ),
+};
+
+/** 默认选中状态。 */
+export const Checked: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Checkbox id="checked" defaultChecked />
+      <label htmlFor="checked" className="text-xs">
+        已选中
+      </label>
+    </div>
+  ),
+};
+
+/** 中间态：用于树形/全选半选场景，可用 `indeterminate` 便利 prop 或 `checked='indeterminate'`。 */
+export const Indeterminate: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Checkbox id="indet" indeterminate />
+      <label htmlFor="indet" className="text-xs">
+        部分选中
+      </label>
+    </div>
+  ),
+};
+
+/** 禁用状态。 */
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center gap-2">
+        <Checkbox id="disabled-unchecked" disabled />
+        <label
+          htmlFor="disabled-unchecked"
+          className="text-xs text-muted-foreground"
+        >
+          禁用未选中
+        </label>
+      </div>
+      <div className="flex items-center gap-2">
+        <Checkbox id="disabled-checked" disabled defaultChecked />
+        <label
+          htmlFor="disabled-checked"
+          className="text-xs text-muted-foreground"
+        >
+          禁用已选中
+        </label>
+      </div>
+    </div>
+  ),
+};
+
+/** CheckboxGroup 数据驱动模式（默认横向排列）。 */
+export const Group: Story = {
+  render: () => (
+    <CheckboxGroup
+      defaultValue={['banana']}
+      dataSource={['apple', 'banana', 'orange']}
+    />
+  ),
+};
+
+/** CheckboxGroup 对象形式 dataSource，支持自定义 label 与单项禁用。 */
+export const GroupWithOptions: Story = {
+  render: () => (
+    <CheckboxGroup
+      defaultValue={['apple']}
+      dataSource={[
+        { value: 'apple', label: '苹果' },
+        { value: 'banana', label: '香蕉' },
+        { value: 'orange', label: '橙子', disabled: true },
+      ]}
+    />
+  ),
+};
+
+/** CheckboxGroup 纵向排列。 */
+export const GroupVertical: Story = {
+  render: () => (
+    <CheckboxGroup
+      direction="vertical"
+      defaultValue={['banana']}
+      dataSource={[
+        { value: 'apple', label: '苹果' },
+        { value: 'banana', label: '香蕉' },
+        { value: 'orange', label: '橙子' },
+      ]}
+    />
+  ),
+};
+
+/** CheckboxGroup 受控用法 + onChange 回调。 */
+export const GroupControlled: Story = {
+  render: () => {
+    const [value, setValue] = React.useState<string[]>(['apple']);
+    return (
+      <div className="flex flex-col gap-2">
+        <CheckboxGroup
+          value={value}
+          onChange={setValue}
+          dataSource={[
+            { value: 'apple', label: '苹果' },
+            { value: 'banana', label: '香蕉' },
+            { value: 'orange', label: '橙子' },
+          ]}
+        />
+        <div className="text-xs text-muted-foreground">
+          已选：{value.join(', ') || '无'}
+        </div>
+      </div>
+    );
+  },
+};
+
+/** CheckboxGroup 整组禁用。 */
+export const GroupDisabled: Story = {
+  render: () => (
+    <CheckboxGroup
+      disabled
+      defaultValue={['apple']}
+      dataSource={[
+        { value: 'apple', label: '苹果' },
+        { value: 'banana', label: '香蕉' },
+        { value: 'orange', label: '橙子' },
+      ]}
+    />
+  ),
+};
+
+/** CheckboxGroup children 模式：自由组合 Checkbox 子元素，仍由 group 接管选中状态。 */
+export const GroupWithChildren: Story = {
+  render: () => (
+    <CheckboxGroup defaultValue={['banana']} direction="vertical">
+      <label className="inline-flex cursor-pointer items-center gap-2 text-xs">
+        <Checkbox value="apple" />
+        <span>苹果（自定义渲染）</span>
+      </label>
+      <label className="inline-flex cursor-pointer items-center gap-2 text-xs">
+        <Checkbox value="banana" />
+        <span>香蕉（自定义渲染）</span>
+      </label>
+      <label className="inline-flex cursor-pointer items-center gap-2 text-xs">
+        <Checkbox value="orange" />
+        <span>橙子（自定义渲染）</span>
+      </label>
+    </CheckboxGroup>
+  ),
+};
+
+/** 全选 / 半选 / 反选联动。 */
+export const CheckAll: Story = {
+  render: () => {
+    const options = ['apple', 'banana', 'orange'];
+    const [value, setValue] = React.useState<string[]>(['apple']);
+    const allChecked = value.length === options.length;
+    const indeterminate = value.length > 0 && !allChecked;
+
+    return (
+      <div className="flex flex-col gap-3">
+        <label className="inline-flex cursor-pointer items-center gap-2 text-xs">
+          <Checkbox
+            checked={allChecked}
+            indeterminate={indeterminate}
+            onCheckedChange={(c) => setValue(c === true ? options : [])}
+          />
+          <span>全选</span>
+        </label>
+        <CheckboxGroup
+          value={value}
+          onChange={setValue}
+          dataSource={[
+            { value: 'apple', label: '苹果' },
+            { value: 'banana', label: '香蕉' },
+            { value: 'orange', label: '橙子' },
+          ]}
+        />
+      </div>
+    );
+  },
+};