@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/switch/meta.md

@@ -0,0 +1,107 @@
+# Switch
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+开关 Switch
+用于在两种状态间切换（开/关），类似物理开关。
+
+## 使用场景
+
+- 需要表示"开/关"两态切换时（如启用/禁用功能）
+- Checkbox 语义不够直观，需要更强视觉反馈时
+- 需要异步保存切换结果时（配合 `loading`）
+- 组合结构：搭配外部 `<label htmlFor>` 或 `Label` 组件使用；可通过
+- `checkedChildren` / `unCheckedChildren` 在 track 内嵌入文本或图标，
+- track 宽度自适应内文长度。
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `SwitchSize` | `default` | – | 尺寸。 |
+| `loading` | `boolean` | `false` | – | 加载中：展示自旋图标并阻止交互。 |
+| `checkedChildren` | `React.ReactNode` | – | – | 选中时显示在 track 内的内容（文本或 lucide 图标）。 |
+| `unCheckedChildren` | `React.ReactNode` | – | – | 未选中时显示在 track 内的内容（文本或 lucide 图标）。 |
+
+## 示例
+
+### Sizes
+
+两档尺寸：`default`、`sm`。
+
+```tsx
+<div className="flex items-center gap-4">
+  <div className="flex items-center gap-2">
+    <Switch id="size-default" defaultChecked />
+    <Label htmlFor="size-default">默认</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <Switch id="size-sm" size="sm" defaultChecked />
+    <Label htmlFor="size-sm">小号</Label>
+  </div>
+</div>
+```
+
+### WithChildren
+
+内嵌文本：`checkedChildren` / `unCheckedChildren`。 track 宽度自动跟随内文长度自适应。
+
+```tsx
+<div className="flex items-center gap-4">
+  <Switch defaultChecked checkedChildren="开" unCheckedChildren="关" />
+  <Switch
+    size="sm"
+    defaultChecked
+    checkedChildren="开"
+    unCheckedChildren="关"
+  />
+  <Switch
+    defaultChecked
+    checkedChildren="已启用"
+    unCheckedChildren="已关闭"
+  />
+</div>
+```
+
+### WithIcon
+
+内嵌图标：与文本同一对 prop，传 lucide 节点即可。
+
+```tsx
+<div className="flex items-center gap-4">
+  <Switch
+    defaultChecked
+    checkedChildren={<CheckIcon className="size-3" />}
+    unCheckedChildren={<XIcon className="size-3" />}
+  />
+  <Switch
+    size="sm"
+    defaultChecked
+    checkedChildren={<CheckIcon className="size-2" />}
+    unCheckedChildren={<XIcon className="size-2" />}
+  />
+</div>
+```
+
+### Disabled
+
+禁用态：开/关两种。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex items-center gap-2">
+    <Switch disabled />
+    <Label className="text-muted-foreground">禁用（关）</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <Switch disabled defaultChecked />
+    <Label className="text-muted-foreground">禁用（开）</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <Switch disabled checkedChildren="开" unCheckedChildren="关" />
+    <Label className="text-muted-foreground">禁用 + 内文</Label>
+  </div>
+</div>
+```

package/src/components/switch/stories.tsx

@@ -0,0 +1,154 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { CheckIcon, XIcon } from 'lucide-react';
+
+import { Switch } from './index';
+import { Button } from '@/components/button';
+import { Label } from '@/components/label';
+
+const meta: Meta<typeof Switch> = {
+  title: '数据录入 · Data Entry/Switch 开关',
+  component: Switch,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { source: { type: 'dynamic' } },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 默认开关。配合外部 `<Label htmlFor>` 关联点击。 */
+export const Default: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Switch id="airplane-mode" defaultChecked />
+      <Label htmlFor="airplane-mode">飞行模式</Label>
+    </div>
+  ),
+};
+
+/** 两档尺寸：`default`、`sm`。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <div className="flex items-center gap-2">
+        <Switch id="size-default" defaultChecked />
+        <Label htmlFor="size-default">默认</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <Switch id="size-sm" size="sm" defaultChecked />
+        <Label htmlFor="size-sm">小号</Label>
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * 内嵌文本：`checkedChildren` / `unCheckedChildren`。
+ * track 宽度自动跟随内文长度自适应。
+ */
+export const WithChildren: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Switch defaultChecked checkedChildren="开" unCheckedChildren="关" />
+      <Switch
+        size="sm"
+        defaultChecked
+        checkedChildren="开"
+        unCheckedChildren="关"
+      />
+      <Switch
+        defaultChecked
+        checkedChildren="已启用"
+        unCheckedChildren="已关闭"
+      />
+    </div>
+  ),
+};
+
+/** 内嵌图标：与文本同一对 prop，传 lucide 节点即可。 */
+export const WithIcon: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <Switch
+        defaultChecked
+        checkedChildren={<CheckIcon className="size-3" />}
+        unCheckedChildren={<XIcon className="size-3" />}
+      />
+      <Switch
+        size="sm"
+        defaultChecked
+        checkedChildren={<CheckIcon className="size-2" />}
+        unCheckedChildren={<XIcon className="size-2" />}
+      />
+    </div>
+  ),
+};
+
+/** 加载态：`loading` 期间禁用交互，thumb 内显示自旋图标。 */
+export const Loading: Story = {
+  render: () => {
+    const [checked, setChecked] = React.useState(false);
+    const [loading, setLoading] = React.useState(false);
+
+    const handleChange = (next: boolean) => {
+      setLoading(true);
+      setTimeout(() => {
+        setChecked(next);
+        setLoading(false);
+      }, 1000);
+    };
+
+    return (
+      <div className="flex items-center gap-4">
+        <Switch
+          checked={checked}
+          loading={loading}
+          onCheckedChange={handleChange}
+        />
+        <Switch size="sm" loading defaultChecked />
+        <Button
+          variant="outline"
+          size="sm"
+          onClick={() => handleChange(!checked)}
+        >
+          异步切换
+        </Button>
+      </div>
+    );
+  },
+};
+
+/** 禁用态：开/关两种。 */
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center gap-2">
+        <Switch disabled />
+        <Label className="text-muted-foreground">禁用（关）</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <Switch disabled defaultChecked />
+        <Label className="text-muted-foreground">禁用（开）</Label>
+      </div>
+      <div className="flex items-center gap-2">
+        <Switch disabled checkedChildren="开" unCheckedChildren="关" />
+        <Label className="text-muted-foreground">禁用 + 内文</Label>
+      </div>
+    </div>
+  ),
+};
+
+/** 受控用法：通过 `checked` + `onCheckedChange` 接管状态。 */
+export const Controlled: Story = {
+  render: () => {
+    const [checked, setChecked] = React.useState(true);
+    return (
+      <div className="flex items-center gap-2">
+        <Switch checked={checked} onCheckedChange={setChecked} />
+        <Label>{checked ? '开启' : '关闭'}</Label>
+      </div>
+    );
+  },
+};

package/src/components/table/index.tsx

@@ -0,0 +1,350 @@
+/**
+ * 表格 Table
+ *
+ * 展示结构化数据的基础表格组件，shadcn 极薄 composable 范式。提供 size / bordered / striped /
+ * stickyHeader / hoverable / crossline / loading / empty / maxBodyHeight 等视觉与状态能力。
+ * 交互逻辑（排序 / 过滤 / 分页 / 选择 / 展开 / 锁列 / 虚拟滚动等）由 DataTable 高阶组件承载。
+ *
+ * @when
+ * - 需要表格化展示结构化数据
+ * - 作为 DataTable 的底层渲染基础
+ * - 简单数据列表展示，无需交互逻辑时直接使用
+ *
+ * 组合结构：Table > TableHeader / TableBody / TableFooter > TableRow > TableHead / TableCell ; TableCaption 可选
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Loader2, Inbox } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+// ─── Context ────────────────────────────────────────────────────────────────
+
+type TableSize = 'sm' | 'md';
+
+interface TableContextValue {
+  size: TableSize;
+  bordered: boolean;
+  striped: boolean;
+  hoverable: boolean;
+  crossline: boolean;
+  stickyHeader: boolean;
+}
+
+const TableContext = React.createContext<TableContextValue>({
+  size: 'md',
+  bordered: false,
+  striped: false,
+  hoverable: true,
+  crossline: false,
+  stickyHeader: false,
+});
+
+const useTableContext = () => React.useContext(TableContext);
+
+// ─── Variants ───────────────────────────────────────────────────────────────
+
+const tableVariants = cva('w-full caption-bottom text-xs', {
+  variants: {
+    layout: {
+      auto: 'table-auto',
+      fixed: 'table-fixed',
+    },
+  },
+  defaultVariants: {
+    layout: 'auto',
+  },
+});
+
+// ─── Table（根） ─────────────────────────────────────────────────────────────
+
+export interface TableProps
+  extends React.ComponentProps<'table'>,
+    VariantProps<typeof tableVariants> {
+  /** 尺寸，sm = 紧凑（py-2 px-2，白底表头），md = 默认（thead py-3 px-4 + 浅灰底，tbody py-3 px-4） */
+  size?: TableSize;
+  /** 是否显示外边框与单元格分隔线（默认 false：仅保留行底边线 + 表头浅底） */
+  bordered?: boolean;
+  /** 是否启用斑马纹（偶数行底色） */
+  striped?: boolean;
+  /** 是否启用行 hover 高亮（默认开启） */
+  hoverable?: boolean;
+  /** 是否启用十字辅助轴（hover 行 + 列高亮） */
+  crossline?: boolean;
+  /** 是否吸顶表头（配合 maxBodyHeight 使用） */
+  stickyHeader?: boolean;
+  /** 表格容器最大高度，超出滚动；可传字符串如 '400px' 或数字（视为 px） */
+  maxBodyHeight?: number | string;
+  /** 是否显示加载态蒙层 */
+  loading?: boolean;
+  /** 自定义加载态节点；默认居中 spinner */
+  loadingNode?: React.ReactNode;
+  /** 空数据节点；当传入时覆盖 tbody 默认渲染（一般由 DataTable 控制） */
+  empty?: React.ReactNode;
+  /** 容器层 className */
+  containerClassName?: string;
+}
+
+function Table({
+  className,
+  layout,
+  size = 'md',
+  bordered = false,
+  striped = false,
+  hoverable = true,
+  crossline = false,
+  stickyHeader = false,
+  maxBodyHeight,
+  loading = false,
+  loadingNode,
+  empty,
+  containerClassName,
+  children,
+  style,
+  ...props
+}: TableProps) {
+  const ctx = React.useMemo<TableContextValue>(
+    () => ({ size, bordered, striped, hoverable, crossline, stickyHeader }),
+    [size, bordered, striped, hoverable, crossline, stickyHeader],
+  );
+
+  const containerStyle: React.CSSProperties = {};
+  if (maxBodyHeight !== undefined) {
+    containerStyle.maxHeight =
+      typeof maxBodyHeight === 'number' ? `${maxBodyHeight}px` : maxBodyHeight;
+  }
+
+  return (
+    <TableContext.Provider value={ctx}>
+      <div
+        data-slot="table-container"
+        data-bordered={bordered ? '' : undefined}
+        data-sticky-header={stickyHeader ? '' : undefined}
+        className={cn(
+          'relative w-full overflow-auto',
+          bordered && 'rounded-md border border-border',
+          containerClassName,
+        )}
+        style={containerStyle}
+      >
+        <table
+          data-slot="table"
+          data-size={size}
+          data-striped={striped ? '' : undefined}
+          data-hoverable={hoverable ? '' : undefined}
+          data-crossline={crossline ? '' : undefined}
+          className={cn(tableVariants({ layout }), className)}
+          style={style}
+          {...props}
+        >
+          {children}
+        </table>
+        {empty != null ? (
+          <TableEmpty data-slot="table-empty">{empty}</TableEmpty>
+        ) : null}
+        {loading ? (
+          <TableLoadingOverlay>{loadingNode}</TableLoadingOverlay>
+        ) : null}
+      </div>
+    </TableContext.Provider>
+  );
+}
+
+// ─── TableHeader ────────────────────────────────────────────────────────────
+
+function TableHeader({ className, ...props }: React.ComponentProps<'thead'>) {
+  const { stickyHeader, bordered, size } = useTableContext();
+  return (
+    <thead
+      data-slot="table-header"
+      data-sticky={stickyHeader ? '' : undefined}
+      className={cn(
+        '[&_tr]:border-b [&_tr]:border-border-subtle',
+        // 表头行 hover 不变色（覆盖 TableRow 的 hover:bg-muted/50）
+        '[&>tr:hover]:bg-transparent',
+        // 表头颜色与 size 无关：灰底（panel = cd bg-4 #f7f7f7）+ 辅助文字色（foreground-subtle = cd text-4 #808080）
+        'bg-panel [&_th]:text-foreground-subtle',
+        stickyHeader && 'sticky top-0 z-10',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── TableBody ──────────────────────────────────────────────────────────────
+
+function TableBody({ className, ...props }: React.ComponentProps<'tbody'>) {
+  const { striped } = useTableContext();
+  return (
+    <tbody
+      data-slot="table-body"
+      className={cn(striped && '[&_tr:nth-child(even)]:bg-muted/30', className)}
+      {...props}
+    />
+  );
+}
+
+// ─── TableFooter ────────────────────────────────────────────────────────────
+
+function TableFooter({ className, ...props }: React.ComponentProps<'tfoot'>) {
+  return (
+    <tfoot
+      data-slot="table-footer"
+      className={cn(
+        'border-t border-border-subtle font-medium [&>tr]:last:border-b-0 [&>tr:hover]:bg-transparent',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── TableRow ───────────────────────────────────────────────────────────────
+
+const TableRow = React.forwardRef<
+  HTMLTableRowElement,
+  React.ComponentProps<'tr'>
+>(function TableRow({ className, ...props }, ref) {
+  const { hoverable, crossline } = useTableContext();
+  return (
+    <tr
+      ref={ref}
+      data-slot="table-row"
+      className={cn(
+        'border-b border-border-subtle transition-colors',
+        hoverable &&
+          'hover:bg-muted/50 has-aria-expanded:bg-muted/50 data-[state=selected]:bg-muted',
+        crossline && 'group/row',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+// ─── TableHead ──────────────────────────────────────────────────────────────
+
+function TableHead({ className, ...props }: React.ComponentProps<'th'>) {
+  const { size, bordered } = useTableContext();
+  return (
+    <th
+      data-slot="table-head"
+      data-size={size}
+      className={cn(
+        'text-left align-middle font-medium whitespace-nowrap',
+        // md：上下 12px / 左右 16px / 行高 18px；sm：上下 8px / 左右 8px
+        size === 'sm' ? 'px-2 py-2' : 'px-4 py-3 leading-normal',
+        bordered &&
+          '[&:not(:last-child)]:border-r [&:not(:last-child)]:border-border/60',
+        '[&:has([role=checkbox])]:pr-0',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── TableCell ──────────────────────────────────────────────────────────────
+
+function TableCell({ className, ...props }: React.ComponentProps<'td'>) {
+  const { size, bordered } = useTableContext();
+  return (
+    <td
+      data-slot="table-cell"
+      data-size={size}
+      className={cn(
+        'align-middle whitespace-nowrap text-foreground-body',
+        // md：上下 12px / 左右 16px；sm：上下 8px / 左右 8px
+        size === 'sm' ? 'px-2 py-2' : 'px-4 py-3',
+        bordered &&
+          '[&:not(:last-child)]:border-r [&:not(:last-child)]:border-border/60',
+        '[&:has([role=checkbox])]:pr-0',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── TableCaption ───────────────────────────────────────────────────────────
+
+function TableCaption({
+  className,
+  ...props
+}: React.ComponentProps<'caption'>) {
+  return (
+    <caption
+      data-slot="table-caption"
+      className={cn('mt-4 text-xs text-muted-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+// ─── TableLoadingOverlay ────────────────────────────────────────────────────
+
+function TableLoadingOverlay({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="table-loading-overlay"
+      role="status"
+      aria-live="polite"
+      className={cn(
+        'absolute inset-0 z-20 flex items-center justify-center bg-background/60 backdrop-blur-[1px]',
+        className,
+      )}
+      {...props}
+    >
+      {children ?? (
+        <Loader2 className="size-5 animate-spin text-muted-foreground" />
+      )}
+    </div>
+  );
+}
+
+// ─── TableEmpty ─────────────────────────────────────────────────────────────
+
+function TableEmpty({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="table-empty"
+      className={cn(
+        'flex flex-col items-center justify-center gap-2 py-10 text-muted-foreground',
+        className,
+      )}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <Inbox className="size-8 opacity-60" />
+          <span className="text-xs">暂无数据</span>
+        </>
+      )}
+    </div>
+  );
+}
+
+export {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+  TableLoadingOverlay,
+  TableEmpty,
+  tableVariants,
+  useTableContext,
+};