@teamix-evo/ui 0.7.1 → 0.7.2

package/src/components/pagination/meta.md

@@ -37,3 +37,206 @@
 | `showQuickJumper` | `boolean` | `false` | – | normal 类型下显示快速跳转输入框。 |
 | `siblingCount` | `number` | `5` | – | 中间显示几个页号(建议奇数)。 |
 | `className` | `string` | – | – | 容器 className。 |
+
+## 示例
+
+### Playground
+
+完全可交互的受控分页，可通过 Controls 面板调整所有参数。
+
+```tsx
+<Pagination
+  {...args}
+  current={page}
+  showQuickJumper
+  onChange={(p) => setPage(p)}
+/>
+```
+
+### Uncontrolled
+
+非受控模式，组件自行管理当前页状态。
+
+```tsx
+<Pagination total={245} defaultCurrent={2} />
+```
+
+### Types
+
+三种类型对比：normal（完整）/ simple（简化）/ mini（极简）。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <div className="flex flex-col gap-1">
+    <span className="text-xs text-muted-foreground">normal</span>
+    <Pagination
+      total={245}
+      type="normal"
+      current={p1}
+      onChange={(p) => setP1(p)}
+    />
+  </div>
+  <div className="flex flex-col gap-1">
+    <span className="text-xs text-muted-foreground">simple</span>
+    <Pagination
+      total={245}
+      type="simple"
+      current={p2}
+      onChange={(p) => setP2(p)}
+    />
+  </div>
+  <div className="flex flex-col gap-1">
+    <span className="text-xs text-muted-foreground">mini</span>
+    <Pagination
+      total={245}
+      type="mini"
+      current={p3}
+      onChange={(p) => setP3(p)}
+    />
+  </div>
+</div>
+```
+
+### Sizes
+
+三档尺寸对比：sm(h-6) / md(h-8) / lg(h-9)。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <div className="flex flex-col gap-1">
+    <span className="text-xs text-muted-foreground">sm</span>
+    <Pagination
+      total={245}
+      size="sm"
+      current={p1}
+      onChange={(p) => setP1(p)}
+    />
+  </div>
+  <div className="flex flex-col gap-1">
+    <span className="text-xs text-muted-foreground">md</span>
+    <Pagination
+      total={245}
+      size="md"
+      current={p2}
+      onChange={(p) => setP2(p)}
+    />
+  </div>
+  <div className="flex flex-col gap-1">
+    <span className="text-xs text-muted-foreground">lg</span>
+    <Pagination
+      total={245}
+      size="lg"
+      current={p3}
+      onChange={(p) => setP3(p)}
+    />
+  </div>
+</div>
+```
+
+### Matrix
+
+type × size 的完整矩阵（9 个组合），用于一眼比对视觉密度。
+
+```tsx
+<div className="flex flex-col gap-6">
+  {types.map((t) => (
+    <div key={t} className="flex flex-col gap-3">
+      <div className="text-sm font-medium text-muted-foreground">
+        type = {t}
+      </div>
+      {sizes.map((s) => (
+        <MatrixRow key={`${t}-${s}`} type={t} size={s} />
+      ))}
+    </div>
+  ))}
+</div>
+```
+
+### WithPageSizeSelector
+
+启用 showSizeChanger，用户可切换每页显示条数。
+
+```tsx
+<Pagination
+  total={1234}
+  current={page}
+  pageSize={size}
+  showSizeChanger
+  pageSizeOptions={[10, 20, 50, 100]}
+  onChange={(p, s) => {
+    setPage(p);
+    setSize(s);
+  }}
+  onPageSizeChange={(s) => setSize(s)}
+/>
+```
+
+### WithJumpAndFirstLast
+
+启用跳转输入框 + 首末页快捷按钮 + showSizeChanger 的完整形态。
+
+```tsx
+<Pagination
+  total={1234}
+  current={page}
+  showFirstLast
+  showQuickJumper
+  showSizeChanger
+  onChange={(p) => setPage(p)}
+/>
+```
+
+### CustomTotal
+
+自定义 totalRender 函数，展示 "1-10 of 245" 格式。
+
+```tsx
+<Pagination
+  total={245}
+  current={page}
+  onChange={(p) => setPage(p)}
+  totalRender={(t, [s, e]) => `${s}–${e} of ${t}`}
+/>
+```
+
+### HideJump
+
+showQuickJumper=false 时强制隐藏跳转框（即使页数较多）。
+
+```tsx
+<Pagination
+  total={500}
+  current={page}
+  showQuickJumper={false}
+  onChange={(p) => setPage(p)}
+/>
+```
+
+### FewItems
+
+数据少于一页时的展示效果（仅 1 页）。
+
+```tsx
+const [page, setPage] = React.useState(1);
+return <Pagination total={5} current={page} onChange={(p) => setPage(p)} />;
+```
+
+### LargeDataset
+
+大数据量（10000 条）带 showSizeChanger 和跳转。
+
+```tsx
+<Pagination
+  total={10000}
+  current={page}
+  pageSize={size}
+  showSizeChanger
+  showQuickJumper
+  showFirstLast
+  onChange={(p, s) => {
+    setPage(p);
+    setSize(s);
+  }}
+  onPageSizeChange={(s) => setSize(s)}
+/>
+```

package/src/components/popconfirm/meta.md

@@ -98,6 +98,31 @@
 </Popconfirm>
 ```
 
+### Controlled
+
+```tsx
+const ControlledDemo = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div className="flex items-center gap-4">
+      <Popconfirm
+        open={open}
+        onOpenChange={setOpen}
+        title="受控确认"
+        description="open / onOpenChange 受外部驱动。"
+        onConfirm={() => console.log('confirmed')}
+      >
+        <Button>触发</Button>
+      </Popconfirm>
+      <span className="text-xs text-muted-foreground">
+        当前：{open ? '打开' : '关闭'}
+      </span>
+    </div>
+  );
+};
+return <ControlledDemo />;
+```
+
 ### CustomButtons
 
 ```tsx
@@ -125,6 +150,26 @@
 </div>
 ```
 
+### Placement
+
+```tsx
+<div className="grid grid-cols-3 gap-4">
+  {sides.flatMap((side) =>
+    aligns.map((align) => (
+      <Popconfirm
+        key={`${side}-${align}`}
+        title={`${side} / ${align}`}
+        side={side}
+        align={align}
+        onConfirm={() => {}}
+      >
+        <Button>{`${side}-${align}`}</Button>
+      </Popconfirm>
+    )),
+  )}
+</div>
+```
+
 ### Disabled
 
 ```tsx

package/src/components/popover/index.tsx

@@ -67,7 +67,7 @@ function PopoverContent({
         align={align}
         sideOffset={sideOffset}
         className={cn(
-          'group/popover-content relative z-50 flex w-72 origin-(--radix-popover-content-transform-origin) flex-col gap-2.5 rounded-md bg-popover p-2.5 text-xs text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+          'group/popover-content relative z-50 flex w-72 origin-(--radix-popover-content-transform-origin) flex-col gap-2.5 rounded-md bg-popover p-2.5 text-xs text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
           className,
         )}
         {...props}
@@ -132,7 +132,7 @@ function PopoverClose({
     <Comp
       data-slot="popover-close"
       className={cn(
-        'absolute right-2 top-2 inline-flex size-6 cursor-pointer items-center justify-center rounded-sm text-muted-foreground opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        'absolute top-2 right-2 inline-flex size-6 cursor-pointer items-center justify-center rounded-sm text-muted-foreground opacity-70 transition-opacity hover:opacity-100 focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-none',
         className,
       )}
       {...props}

package/src/components/popover/meta.md

@@ -60,6 +60,32 @@
 </div>
 ```
 
+### Controlled
+
+受控显示，点击内部按钮可程序化关闭。
+
+```tsx
+<Popover open={open} onOpenChange={setOpen}>
+  <PopoverTrigger asChild>
+    <Button>{open ? '收起' : '打开'}</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <PopoverHeader>
+      <PopoverTitle>受控示例</PopoverTitle>
+      <PopoverDescription>open / onOpenChange 受控</PopoverDescription>
+    </PopoverHeader>
+    <div className="flex justify-end gap-2">
+      <Button size="sm" onClick={() => setOpen(false)}>
+        取消
+      </Button>
+      <Button size="sm" onClick={() => setOpen(false)}>
+        确认
+      </Button>
+    </div>
+  </PopoverContent>
+</Popover>
+```
+
 ### WithCloseButton
 
 显示关闭按钮，覆盖 Balloon `closable` 行为。
@@ -80,6 +106,27 @@
 </Popover>
 ```
 
+### AllPositions
+
+12 方向矩阵：side × align 组合。
+
+```tsx
+<div className="grid grid-cols-3 gap-4">
+  {sides.flatMap((side) =>
+    aligns.map((align) => (
+      <Popover key={`${side}-${align}`}>
+        <PopoverTrigger asChild>
+          <Button>{`${side}-${align}`}</Button>
+        </PopoverTrigger>
+        <PopoverContent side={side} align={align}>
+          <p className="text-muted-foreground">{`${side} / ${align}`}</p>
+        </PopoverContent>
+      </Popover>
+    )),
+  )}
+</div>
+```
+
 ### WithArrow
 
 显示尖角箭头。

package/src/components/progress/index.tsx

@@ -165,7 +165,7 @@ function Progress({
       {track}
       <span
         data-slot="progress-info"
-        className="min-w-9 shrink-0 text-right text-xs tabular-nums text-muted-foreground"
+        className="min-w-9 shrink-0 text-right text-xs text-muted-foreground tabular-nums"
       >
         {format ? format(safeValue, max) : `${Math.floor(pct)}%`}
       </span>

package/src/components/progress/meta.md

@@ -93,3 +93,39 @@ size / 语义色 / 渐进色 / 百分比文本 / 自定义渲染等业界流行
   />
 </div>
 ```
+
+### Indeterminate
+
+不确定态：value={null} 时展示常驻动画，不显示百分比文本。
+
+```tsx
+<Progress value={null} className="w-64" />
+```
+
+### Controlled
+
+受控加减：模拟实时进度更新，搭配 progressive 颜色自动切换。
+
+```tsx
+<div className="flex w-80 flex-col gap-3">
+  <div className="flex gap-2">
+    <Button
+      size="sm"
+      variant="outline"
+      disabled={value === 0}
+      onClick={() => setValue((v) => Math.max(0, v - 10))}
+    >
+      -10
+    </Button>
+    <Button
+      size="sm"
+      variant="outline"
+      disabled={value === 100}
+      onClick={() => setValue((v) => Math.min(100, v + 10))}
+    >
+      +10
+    </Button>
+  </div>
+  <Progress value={value} progressive showInfo size="lg" />
+</div>
+```

package/src/components/progress/stories.tsx

@@ -86,7 +86,7 @@ export const Indeterminate: Story = {
 
 /** 受控加减：模拟实时进度更新，搭配 progressive 颜色自动切换。 */
 export const Controlled: Story = {
-  render: function ControlledRender() {
+  render: () => {
     const [value, setValue] = React.useState(0);
     return (
       <div className="flex w-80 flex-col gap-3">

package/src/components/radio-group/meta.md

@@ -85,6 +85,28 @@
 </div>
 ```
 
+### Controlled
+
+受控用法 + `onValueChange` 回调。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <RadioGroup value={value} onValueChange={setValue}>
+    {FRUITS.map((opt) => (
+      <div key={opt.value} className="flex items-center gap-2">
+        <RadioGroupItem value={opt.value} id={`c-${opt.value}`} />
+        <label htmlFor={`c-${opt.value}`} className="text-xs">
+          {opt.label}
+        </label>
+      </div>
+    ))}
+  </RadioGroup>
+  <div className="text-xs text-muted-foreground">
+    已选：{value || '无'}
+  </div>
+</div>
+```
+
 ### WithList
 
 数据驱动写法：业务侧用 `.map` 渲染，无需内置 `dataSource`。
@@ -135,3 +157,50 @@
   </RadioGroup>
 </div>
 ```
+
+### InsideForm
+
+与 react-hook-form Form 集成：`FormField` 接管 value / onChange / aria。
+
+```tsx
+<Form {...form}>
+  <form
+    onSubmit={form.handleSubmit((data) => console.log(data))}
+    className="flex w-72 flex-col gap-4"
+  >
+    <FormField
+      name="plan"
+      rules={{ required: '请选择套餐' }}
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>套餐</FormLabel>
+          <FormControl>
+            <RadioGroup
+              value={field.value}
+              onValueChange={field.onChange}
+            >
+              {[
+                { value: 'free', label: '免费版' },
+                { value: 'pro', label: '专业版' },
+                { value: 'enterprise', label: '企业版' },
+              ].map((opt) => (
+                <div key={opt.value} className="flex items-center gap-2">
+                  <RadioGroupItem
+                    value={opt.value}
+                    id={`f-${opt.value}`}
+                  />
+                  <label htmlFor={`f-${opt.value}`} className="text-xs">
+                    {opt.label}
+                  </label>
+                </div>
+              ))}
+            </RadioGroup>
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+    <Button type="submit">提交</Button>
+  </form>
+</Form>
+```

package/src/components/rate/index.tsx

@@ -177,7 +177,7 @@ function Rate({
       aria-readonly={readOnly || undefined}
       tabIndex={interactive ? 0 : -1}
       className={cn(
-        'inline-flex items-center gap-0.5 rounded-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        'inline-flex items-center gap-0.5 rounded-sm focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-none',
         disabled && 'pointer-events-none opacity-50',
         readOnly && 'pointer-events-none',
         className,

package/src/components/rate/meta.md

@@ -31,6 +31,30 @@
 
 ## 示例
 
+### Basic
+
+```tsx
+<Rate defaultValue={3} />
+```
+
+### HalfStar
+
+```tsx
+<Rate allowHalf defaultValue={2.5} />
+```
+
+### Disabled
+
+```tsx
+<Rate value={3} disabled />
+```
+
+### ReadOnly
+
+```tsx
+<Rate value={4} readOnly />
+```
+
 ### Sizes
 
 ```tsx
@@ -41,6 +65,32 @@
 </div>
 ```
 
+### CustomCount
+
+```tsx
+<Rate count={8} defaultValue={5} />
+```
+
+### Controlled
+
+```tsx
+<div className="flex items-center gap-3">
+  <Rate value={value} onValueChange={setValue} />
+  <span className="text-sm text-muted-foreground">{value} / 5</span>
+</div>
+```
+
+### WithLabel
+
+```tsx
+<div className="flex items-center gap-3">
+  <Rate value={value} onValueChange={setValue} />
+  <span className="text-sm text-foreground">
+    {grades[value - 1] ?? '未评分'}
+  </span>
+</div>
+```
+
 ### CustomCharacter
 
 ```tsx

package/src/components/resizable/index.tsx

@@ -84,7 +84,7 @@ function ResizablePanelGroup({
     <ResizablePrimitive.Group
       data-slot="resizable-panel-group"
       className={cn(
-        'flex h-full w-full aria-[orientation=vertical]:flex-col',
+        'flex size-full aria-[orientation=vertical]:flex-col',
         className,
       )}
       {...props}

package/src/components/select/index.tsx

@@ -112,7 +112,7 @@ function SelectTrigger({
       data-size={size}
       data-loading={loading ? 'true' : undefined}
       className={cn(
-        "flex w-fit cursor-pointer items-center justify-between gap-1.5 rounded-md border border-input bg-transparent py-2 pr-2 pl-2.5 text-xs whitespace-nowrap transition-colors outline-none select-none focus:border-ring focus:ring-ring/20 data-[state=open]:border-ring disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 data-placeholder:text-muted-foreground data-[size=default]:h-8 data-[size=sm]:h-7 data-[size=lg]:h-9 data-[size=lg]:text-sm *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "flex w-fit cursor-pointer items-center justify-between gap-1.5 rounded-md border border-input bg-transparent py-2 pr-2 pl-2.5 text-xs whitespace-nowrap transition-colors outline-none select-none focus:border-ring focus:ring-ring/20 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 data-placeholder:text-muted-foreground data-[size=default]:h-8 data-[size=lg]:h-9 data-[size=lg]:text-sm data-[size=sm]:h-7 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 data-[state=open]:border-ring [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
         className,
       )}
       {...props}
@@ -244,7 +244,7 @@ function SelectItem({
     <SelectPrimitive.Item
       data-slot="select-item"
       className={cn(
-        "relative flex h-8 w-full cursor-pointer items-center gap-1.5 rounded-md py-1 pr-2 pl-7 text-xs outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-[state=checked]:text-primary data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        "relative flex h-8 w-full cursor-pointer items-center gap-1.5 rounded-md py-1 pr-2 pl-7 text-xs outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 data-[state=checked]:text-primary [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
         className,
       )}
       {...props}

package/src/components/select/meta.md

@@ -150,6 +150,26 @@
 </Select>
 ```
 
+### WithClear
+
+已选时右侧 chevron 切为 ×，点击清空 value；chevron 与 × 占同一位置、互斥。
+
+```tsx
+<Select value={value} onValueChange={setValue}>
+  <SelectTrigger
+    className="w-56"
+    onClear={value ? () => setValue('') : undefined}
+  >
+    <SelectValue placeholder="请选择水果" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">苹果</SelectItem>
+    <SelectItem value="banana">香蕉</SelectItem>
+    <SelectItem value="orange">橙子</SelectItem>
+  </SelectContent>
+</Select>
+```
+
 ### Loading
 
 加载态：`<SelectTrigger loading>` 把 chevron 替换为旋转 spinner。

package/src/components/separator/index.tsx

@@ -40,7 +40,7 @@ function Separator({
         // 任何对齐上下文（items-center / items-stretch）都能看到分隔线比容器短 4px。需要全高可用 className="py-0" 覆盖。
         'shrink-0 bg-border',
         'data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full',
-        'data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px data-[orientation=vertical]:py-0.5 data-[orientation=vertical]:bg-clip-content',
+        'data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px data-[orientation=vertical]:bg-clip-content data-[orientation=vertical]:py-0.5',
         className,
       )}
       {...props}