@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/rate/stories.tsx

@@ -0,0 +1,107 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Heart } from 'lucide-react';
+
+import { Rate } from '.';
+
+const meta: Meta<typeof Rate> = {
+  title: '数据录入 · Data Entry/Rate 评分',
+  component: Rate,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Rate>;
+
+export const Basic: Story = {
+  name: '基础',
+  args: { defaultValue: 3 },
+};
+
+export const HalfStar: Story = {
+  name: '半星',
+  args: { allowHalf: true, defaultValue: 2.5 },
+};
+
+export const Disabled: Story = {
+  name: '禁用',
+  args: { value: 3, disabled: true },
+};
+
+export const ReadOnly: Story = {
+  name: '只读',
+  args: { value: 4, readOnly: true },
+};
+
+export const Sizes: Story = {
+  name: '尺寸',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Rate size="sm" defaultValue={3} />
+      <Rate size="default" defaultValue={3} />
+      <Rate size="lg" defaultValue={3} />
+    </div>
+  ),
+};
+
+export const CustomCount: Story = {
+  name: '自定义数量',
+  args: { count: 8, defaultValue: 5 },
+};
+
+export const Controlled: Story = {
+  name: '受控',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [value, setValue] = React.useState(3);
+    return (
+      <div className="flex items-center gap-3">
+        <Rate value={value} onValueChange={setValue} />
+        <span className="text-sm text-muted-foreground">{value} / 5</span>
+      </div>
+    );
+  },
+};
+
+export const WithLabel: Story = {
+  name: '等级文案',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const grades = ['很差', '一般', '还行', '不错', '完美'];
+    const [value, setValue] = React.useState(3);
+    return (
+      <div className="flex items-center gap-3">
+        <Rate value={value} onValueChange={setValue} />
+        <span className="text-sm text-foreground">
+          {grades[value - 1] ?? '未评分'}
+        </span>
+      </div>
+    );
+  },
+};
+
+export const CustomCharacter: Story = {
+  name: '自定义图标',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Rate
+      defaultValue={3}
+      character={<Heart className="size-4 fill-current" aria-hidden />}
+    />
+  ),
+};
+
+export const Keyboard: Story = {
+  name: '键盘无障碍',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Rate defaultValue={3} allowHalf />
+      <p className="text-xs text-muted-foreground">
+        Tab 聚焦后按 ←↓ / →↑ 调整，Home / End 跳到最小 / 最大，Enter 或 Space
+        在已有值时清零。
+      </p>
+    </div>
+  ),
+};

package/src/components/resizable/index.tsx

@@ -0,0 +1,122 @@
+/**
+ * 可调整大小面板 Resizable
+ *
+ * 支持拖拽调整大小的布局面板，基于 react-resizable-panels。
+ *
+ * @when
+ * - IDE 式布局（侧边栏 + 主内容 + 面板）
+ * - 可调整宽度的分栏展示
+ * - 拖拽调整工作区域
+ */
+'use client';
+
+import { GripVerticalIcon } from 'lucide-react';
+import * as ResizablePrimitive from 'react-resizable-panels';
+
+import { cn } from '@/lib/utils';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ResizablePanelGroupProps
+  extends ResizablePrimitive.GroupProps {
+  /** 面板组方向，决定 Panel 排布与可拖拽方向。 @default 'horizontal' */
+  orientation?: ResizablePrimitive.Orientation;
+  /** 默认布局，键为 Panel id，值为百分比 0..100；可配合 storage 跨刷新持久化。 */
+  defaultLayout?: ResizablePrimitive.GroupProps['defaultLayout'];
+  /** 禁用整组的拖拽尺寸调整。 @default false */
+  disabled?: boolean;
+  /** 禁用拖拽过程中的全局光标视觉反馈。 @default false */
+  disableCursor?: boolean;
+  /** 布局变化回调（拖拽中每帧触发）。 */
+  onLayoutChange?: ResizablePrimitive.GroupProps['onLayoutChange'];
+  /** 布局变化稳定后的回调（拖拽结束触发一次）。 */
+  onLayoutChanged?: ResizablePrimitive.GroupProps['onLayoutChanged'];
+  /** 根 div 的 ref，如需获取 DOM 则传入。 */
+  elementRef?: ResizablePrimitive.GroupProps['elementRef'];
+  /** 命令式 API ref：提供 `getLayout()` / `setLayout(layout)`，可配 `useGroupRef` 使用。 */
+  groupRef?: ResizablePrimitive.GroupProps['groupRef'];
+  /** 拖拽热区最小点击区域，区分鼠标 `fine` 与触控 `coarse`，防误点。 */
+  resizeTargetMinimumSize?: ResizablePrimitive.GroupProps['resizeTargetMinimumSize'];
+}
+
+export interface ResizablePanelProps extends ResizablePrimitive.PanelProps {
+  /** 默认尺寸；数字按百分比 0..100，字符串支持 `px` / `%` / `rem` / `vh` 等单位。 */
+  defaultSize?: ResizablePrimitive.PanelProps['defaultSize'];
+  /** 最小尺寸；超过约束会被夹到此值。 */
+  minSize?: ResizablePrimitive.PanelProps['minSize'];
+  /** 最大尺寸；超过约束会被夹到此值。 */
+  maxSize?: ResizablePrimitive.PanelProps['maxSize'];
+  /** 允许折叠：尺寸小于 `minSize` 时折叠到 `collapsedSize`。 @default false */
+  collapsible?: boolean;
+  /** 折叠后的尺寸。 @default 0 */
+  collapsedSize?: ResizablePrimitive.PanelProps['collapsedSize'];
+  /** 禁用本 Panel 尺寸调整（不影响兄弟 Panel）。 @default false */
+  disabled?: boolean;
+  /** 尺寸变化回调，返回当前百分比与像素尺寸。 */
+  onResize?: ResizablePrimitive.PanelProps['onResize'];
+  /** 根 div 的 ref，如需获取 DOM 则传入。 */
+  elementRef?: ResizablePrimitive.PanelProps['elementRef'];
+  /** 命令式 API ref：`collapse` / `expand` / `getSize` / `isCollapsed` / `resize`。 */
+  panelRef?: ResizablePrimitive.PanelProps['panelRef'];
+  /** 父组变尺时本 Panel 的行为：`preserve-relative-size`（保持百分比）或 `preserve-pixel-size`（保持像素）。 @default 'preserve-relative-size' */
+  groupResizeBehavior?: ResizablePrimitive.PanelProps['groupResizeBehavior'];
+}
+
+export interface ResizableHandleProps
+  extends ResizablePrimitive.SeparatorProps {
+  /** 显示带 GripVertical 图标的可见拖动手柄，提升可发现性。 @default false */
+  withHandle?: boolean;
+  /** 禁用本分隔条的拖拽。 @default false */
+  disabled?: boolean;
+  /** 禁用双击复位到默认布局的行为。 @default false */
+  disableDoubleClick?: boolean;
+  /** 根 div 的 ref，如需获取 DOM 则传入。 */
+  elementRef?: ResizablePrimitive.SeparatorProps['elementRef'];
+}
+
+// ─── Components ─────────────────────────────────────────────────────────────
+
+function ResizablePanelGroup({
+  className,
+  ...props
+}: ResizablePanelGroupProps) {
+  return (
+    <ResizablePrimitive.Group
+      data-slot="resizable-panel-group"
+      className={cn(
+        'flex h-full w-full aria-[orientation=vertical]:flex-col',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function ResizablePanel({ ...props }: ResizablePanelProps) {
+  return <ResizablePrimitive.Panel data-slot="resizable-panel" {...props} />;
+}
+
+function ResizableHandle({
+  withHandle,
+  className,
+  ...props
+}: ResizableHandleProps) {
+  return (
+    <ResizablePrimitive.Separator
+      data-slot="resizable-handle"
+      className={cn(
+        'relative flex w-px items-center justify-center bg-border after:absolute after:inset-y-0 after:left-1/2 after:w-1 after:-translate-x-1/2 focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:outline-hidden aria-[orientation=horizontal]:h-px aria-[orientation=horizontal]:w-full aria-[orientation=horizontal]:after:left-0 aria-[orientation=horizontal]:after:h-1 aria-[orientation=horizontal]:after:w-full aria-[orientation=horizontal]:after:translate-x-0 aria-[orientation=horizontal]:after:-translate-y-1/2 [&[aria-orientation=horizontal]>div]:rotate-90',
+        className,
+      )}
+      {...props}
+    >
+      {withHandle && (
+        <div className="z-10 flex h-4 w-3 items-center justify-center rounded-xs border border-border bg-border">
+          <GripVerticalIcon className="size-2.5" />
+        </div>
+      )}
+    </ResizablePrimitive.Separator>
+  );
+}
+
+export { ResizableHandle, ResizablePanel, ResizablePanelGroup };

package/src/components/resizable/meta.md

@@ -0,0 +1,142 @@
+# ResizablePanelGroup
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+可调整大小面板 Resizable
+支持拖拽调整大小的布局面板，基于 react-resizable-panels。
+
+## 使用场景
+
+- IDE 式布局（侧边栏 + 主内容 + 面板）
+- 可调整宽度的分栏展示
+- 拖拽调整工作区域
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `orientation` | `ResizablePrimitive.Orientation` | `'horizontal'` | – | 面板组方向，决定 Panel 排布与可拖拽方向。 |
+| `defaultLayout` | `ResizablePrimitive.GroupProps['defaultLayout']` | – | – | 默认布局，键为 Panel id，值为百分比 0..100；可配合 storage 跨刷新持久化。 |
+| `disabled` | `boolean` | `false` | – | 禁用整组的拖拽尺寸调整。 |
+| `disableCursor` | `boolean` | `false` | – | 禁用拖拽过程中的全局光标视觉反馈。 |
+| `onLayoutChange` | `ResizablePrimitive.GroupProps['onLayoutChange']` | – | – | 布局变化回调（拖拽中每帧触发）。 |
+| `onLayoutChanged` | `ResizablePrimitive.GroupProps['onLayoutChanged']` | – | – | 布局变化稳定后的回调（拖拽结束触发一次）。 |
+| `elementRef` | `ResizablePrimitive.GroupProps['elementRef']` | – | – | 根 div 的 ref，如需获取 DOM 则传入。 |
+| `groupRef` | `ResizablePrimitive.GroupProps['groupRef']` | – | – | 命令式 API ref：提供 `getLayout()` / `setLayout(layout)`，可配 `useGroupRef` 使用。 |
+| `resizeTargetMinimumSize` | `ResizablePrimitive.GroupProps['resizeTargetMinimumSize']` | – | – | 拖拽热区最小点击区域，区分鼠标 `fine` 与触控 `coarse`，防误点。 |
+| `defaultSize` | `ResizablePrimitive.PanelProps['defaultSize']` | – | – | 默认尺寸；数字按百分比 0..100，字符串支持 `px` / `%` / `rem` / `vh` 等单位。 |
+| `minSize` | `ResizablePrimitive.PanelProps['minSize']` | – | – | 最小尺寸；超过约束会被夹到此值。 |
+| `maxSize` | `ResizablePrimitive.PanelProps['maxSize']` | – | – | 最大尺寸；超过约束会被夹到此值。 |
+| `collapsible` | `boolean` | `false` | – | 允许折叠：尺寸小于 `minSize` 时折叠到 `collapsedSize`。 |
+| `collapsedSize` | `ResizablePrimitive.PanelProps['collapsedSize']` | `0` | – | 折叠后的尺寸。 |
+| `disabled` | `boolean` | `false` | – | 禁用本 Panel 尺寸调整（不影响兄弟 Panel）。 |
+| `onResize` | `ResizablePrimitive.PanelProps['onResize']` | – | – | 尺寸变化回调，返回当前百分比与像素尺寸。 |
+| `elementRef` | `ResizablePrimitive.PanelProps['elementRef']` | – | – | 根 div 的 ref，如需获取 DOM 则传入。 |
+| `panelRef` | `ResizablePrimitive.PanelProps['panelRef']` | – | – | 命令式 API ref：`collapse` / `expand` / `getSize` / `isCollapsed` / `resize`。 |
+| `groupResizeBehavior` | `ResizablePrimitive.PanelProps['groupResizeBehavior']` | `'preserve-relative-size'` | – | 父组变尺时本 Panel 的行为：`preserve-relative-size`（保持百分比）或 `preserve-pixel-size`（保持像素）。 |
+| `withHandle` | `boolean` | `false` | – | 显示带 GripVertical 图标的可见拖动手柄，提升可发现性。 |
+| `disabled` | `boolean` | `false` | – | 禁用本分隔条的拖拽。 |
+| `disableDoubleClick` | `boolean` | `false` | – | 禁用双击复位到默认布局的行为。 |
+| `elementRef` | `ResizablePrimitive.SeparatorProps['elementRef']` | – | – | 根 div 的 ref，如需获取 DOM 则传入。 |
+
+## 示例
+
+### Horizontal
+
+水平方向双栏可拖拽调节宽度。
+
+```tsx
+<ResizablePanelGroup
+  orientation="horizontal"
+  className="min-h-48 max-w-md rounded-lg border border-border"
+>
+  <ResizablePanel defaultSize={50}>
+    <div className="flex h-full items-center justify-center p-4">
+      <span className="text-xs text-muted-foreground">左侧面板</span>
+    </div>
+  </ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={50}>
+    <div className="flex h-full items-center justify-center p-4">
+      <span className="text-xs text-muted-foreground">右侧面板</span>
+    </div>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+
+### Vertical
+
+垂直方向双栏可拖拽调节高度。
+
+```tsx
+<ResizablePanelGroup
+  orientation="vertical"
+  className="min-h-48 max-w-md rounded-lg border border-border"
+>
+  <ResizablePanel defaultSize={50}>
+    <div className="flex h-full items-center justify-center p-4">
+      <span className="text-xs text-muted-foreground">上方面板</span>
+    </div>
+  </ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={50}>
+    <div className="flex h-full items-center justify-center p-4">
+      <span className="text-xs text-muted-foreground">下方面板</span>
+    </div>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+
+### WithHandle
+
+带拖动手柄的分隔条，提升可见性与可操作性。
+
+```tsx
+<ResizablePanelGroup
+  orientation="horizontal"
+  className="min-h-48 max-w-md rounded-lg border border-border"
+>
+  <ResizablePanel defaultSize={40}>
+    <div className="flex h-full items-center justify-center p-4">
+      <span className="text-xs text-muted-foreground">侧栏</span>
+    </div>
+  </ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={60}>
+    <div className="flex h-full items-center justify-center p-4">
+      <span className="text-xs text-muted-foreground">主内容</span>
+    </div>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+
+### ThreeColumns
+
+三栏布局，左侧边栏 + 主内容 + 右侧面板。
+
+```tsx
+<ResizablePanelGroup
+  orientation="horizontal"
+  className="min-h-48 max-w-lg rounded-lg border border-border"
+>
+  <ResizablePanel defaultSize={25} minSize={15}>
+    <div className="flex h-full items-center justify-center p-4">
+      <span className="text-xs text-muted-foreground">导航</span>
+    </div>
+  </ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={50}>
+    <div className="flex h-full items-center justify-center p-4">
+      <span className="text-xs text-muted-foreground">内容</span>
+    </div>
+  </ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={25} minSize={15}>
+    <div className="flex h-full items-center justify-center p-4">
+      <span className="text-xs text-muted-foreground">详情</span>
+    </div>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```

package/src/components/resizable/stories.tsx

@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from './index';
+
+const meta: Meta<typeof ResizablePanelGroup> = {
+  title: '布局 · Layout/Resizable 可调尺寸面板',
+  component: ResizablePanelGroup,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 水平方向双栏可拖拽调节宽度。 */
+export const Horizontal: Story = {
+  render: () => (
+    <ResizablePanelGroup
+      orientation="horizontal"
+      className="min-h-48 max-w-md rounded-lg border border-border"
+    >
+      <ResizablePanel defaultSize={50}>
+        <div className="flex h-full items-center justify-center p-4">
+          <span className="text-xs text-muted-foreground">左侧面板</span>
+        </div>
+      </ResizablePanel>
+      <ResizableHandle />
+      <ResizablePanel defaultSize={50}>
+        <div className="flex h-full items-center justify-center p-4">
+          <span className="text-xs text-muted-foreground">右侧面板</span>
+        </div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  ),
+};
+
+/** 垂直方向双栏可拖拽调节高度。 */
+export const Vertical: Story = {
+  render: () => (
+    <ResizablePanelGroup
+      orientation="vertical"
+      className="min-h-48 max-w-md rounded-lg border border-border"
+    >
+      <ResizablePanel defaultSize={50}>
+        <div className="flex h-full items-center justify-center p-4">
+          <span className="text-xs text-muted-foreground">上方面板</span>
+        </div>
+      </ResizablePanel>
+      <ResizableHandle />
+      <ResizablePanel defaultSize={50}>
+        <div className="flex h-full items-center justify-center p-4">
+          <span className="text-xs text-muted-foreground">下方面板</span>
+        </div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  ),
+};
+
+/** 带拖动手柄的分隔条，提升可见性与可操作性。 */
+export const WithHandle: Story = {
+  render: () => (
+    <ResizablePanelGroup
+      orientation="horizontal"
+      className="min-h-48 max-w-md rounded-lg border border-border"
+    >
+      <ResizablePanel defaultSize={40}>
+        <div className="flex h-full items-center justify-center p-4">
+          <span className="text-xs text-muted-foreground">侧栏</span>
+        </div>
+      </ResizablePanel>
+      <ResizableHandle withHandle />
+      <ResizablePanel defaultSize={60}>
+        <div className="flex h-full items-center justify-center p-4">
+          <span className="text-xs text-muted-foreground">主内容</span>
+        </div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  ),
+};
+
+/** 三栏布局，左侧边栏 + 主内容 + 右侧面板。 */
+export const ThreeColumns: Story = {
+  render: () => (
+    <ResizablePanelGroup
+      orientation="horizontal"
+      className="min-h-48 max-w-lg rounded-lg border border-border"
+    >
+      <ResizablePanel defaultSize={25} minSize={15}>
+        <div className="flex h-full items-center justify-center p-4">
+          <span className="text-xs text-muted-foreground">导航</span>
+        </div>
+      </ResizablePanel>
+      <ResizableHandle />
+      <ResizablePanel defaultSize={50}>
+        <div className="flex h-full items-center justify-center p-4">
+          <span className="text-xs text-muted-foreground">内容</span>
+        </div>
+      </ResizablePanel>
+      <ResizableHandle />
+      <ResizablePanel defaultSize={25} minSize={15}>
+        <div className="flex h-full items-center justify-center p-4">
+          <span className="text-xs text-muted-foreground">详情</span>
+        </div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  ),
+};

package/src/components/scroll-area/index.tsx

@@ -0,0 +1,83 @@
+/**
+ * 滚动区域 ScrollArea
+ *
+ * 自定义滚动条的滚动容器，基于 Radix ScrollArea 原语。
+ *
+ * @when
+ * - 固定高度的列表容器
+ * - 侧边栏内容溢出
+ * - 代码块 / 日志展示区
+ */
+import * as React from 'react';
+import { ScrollArea as ScrollAreaPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+export interface ScrollAreaProps
+  extends Omit<
+    React.ComponentProps<typeof ScrollAreaPrimitive.Root>,
+    'type' | 'scrollHideDelay' | 'dir'
+  > {
+  /**
+   * 滚动条显示策略。
+   * - `auto`（默认）：需要滚动时才显示
+   * - `always`：始终显示
+   * - `scroll`：滚动时显示，停止后淡出
+   * - `hover`：悬停时显示
+   * @default 'hover'
+   */
+  type?: 'auto' | 'always' | 'scroll' | 'hover';
+  /** type='scroll'/'hover' 时滚动条隐藏前的延迟（毫秒）。 @default 600 */
+  scrollHideDelay?: number;
+  /** 文字方向。 */
+  dir?: 'ltr' | 'rtl';
+}
+
+function ScrollArea({ className, children, ...props }: ScrollAreaProps) {
+  return (
+    <ScrollAreaPrimitive.Root
+      data-slot="scroll-area"
+      className={cn('relative', className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport
+        data-slot="scroll-area-viewport"
+        // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- rounded-[inherit] is the only way to inherit parent's border-radius.
+        className="size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-1"
+      >
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  );
+}
+
+function ScrollBar({
+  className,
+  orientation = 'vertical',
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>) {
+  return (
+    <ScrollAreaPrimitive.ScrollAreaScrollbar
+      data-slot="scroll-area-scrollbar"
+      orientation={orientation}
+      className={cn(
+        'flex touch-none p-px transition-colors select-none',
+        orientation === 'vertical' &&
+          'h-full w-2.5 border-l border-l-transparent',
+        orientation === 'horizontal' &&
+          'h-2.5 flex-col border-t border-t-transparent',
+        className,
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.ScrollAreaThumb
+        data-slot="scroll-area-thumb"
+        className="relative flex-1 rounded-full bg-border"
+      />
+    </ScrollAreaPrimitive.ScrollAreaScrollbar>
+  );
+}
+
+export { ScrollArea, ScrollBar };

package/src/components/scroll-area/meta.md

@@ -0,0 +1,85 @@
+# ScrollArea
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+滚动区域 ScrollArea
+自定义滚动条的滚动容器，基于 Radix ScrollArea 原语。
+
+## 使用场景
+
+- 固定高度的列表容器
+- 侧边栏内容溢出
+- 代码块 / 日志展示区
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `type` | `'auto' \| 'always' \| 'scroll' \| 'hover'` | `'hover'` | – | 滚动条显示策略。 - `auto`（默认）：需要滚动时才显示 - `always`：始终显示 - `scroll`：滚动时显示，停止后淡出 - `hover`：悬停时显示 |
+| `scrollHideDelay` | `number` | `600` | – | type='scroll'/'hover' 时滚动条隐藏前的延迟（毫秒）。 |
+| `dir` | `'ltr' \| 'rtl'` | – | – | 文字方向。 |
+
+## 示例
+
+### Vertical
+
+垂直滚动区域，限定高度后内容超出时出现滚动条。
+
+```tsx
+<ScrollArea className="h-72 w-48 rounded-md border border-border">
+  <div className="p-4">
+    <h4 className="mb-3 text-xs font-medium">版本列表</h4>
+    {tags.map((tag) => (
+      <div key={tag}>
+        <div className="py-1.5 text-xs">{tag}</div>
+        <Separator />
+      </div>
+    ))}
+  </div>
+</ScrollArea>
+```
+
+### HorizontalScroll
+
+水平滚动区域，通过设置内容宽度和 `orientation="horizontal"` 实现。
+
+```tsx
+<ScrollArea className="w-96 whitespace-nowrap rounded-md border border-border">
+  <div className="flex gap-4 p-4">
+    {artworks.map((art) => (
+      <figure key={art.title} className="shrink-0">
+        <div className="h-24 w-36 overflow-hidden rounded-md bg-muted" />
+        <figcaption className="pt-2 text-xs">
+          <span className="font-medium">{art.title}</span>
+          <span className="ml-2 text-muted-foreground">{art.artist}</span>
+        </figcaption>
+      </figure>
+    ))}
+  </div>
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>
+```
+
+### BothDirections
+
+同时支持垂直和水平双向滚动的区域。
+
+```tsx
+<ScrollArea className="h-48 w-64 rounded-md border border-border">
+  <div className="w-96 p-4">
+    <p className="text-xs text-muted-foreground">
+      这是一段很长的内容，同时具有纵向和横向滚动。水平方向的内容宽度超出容器，
+      垂直方向的内容高度也超出容器。用户可以在两个方向上自由滚动查看完整内容。
+      这是一段很长的内容，同时具有纵向和横向滚动。水平方向的内容宽度超出容器，
+      垂直方向的内容高度也超出容器。用户可以在两个方向上自由滚动查看完整内容。
+    </p>
+    <p className="mt-4 text-xs text-muted-foreground">
+      这是一段很长的内容，同时具有纵向和横向滚动。水平方向的内容宽度超出容器，
+      垂直方向的内容高度也超出容器。用户可以在两个方向上自由滚动查看完整内容。
+    </p>
+  </div>
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>
+```