@teamix-evo/ui 0.7.0 → 0.7.2

package/manifest.json

@@ -507,7 +507,7 @@
         }
       ],
       "meta": "src/components/dialog/meta.md",
-      "registryDependencies": ["cn", "button"],
+      "registryDependencies": ["cn", "button", "use-radix-popper-guard"],
       "dependencies": {
         "radix-ui": "^1.4.3",
         "class-variance-authority": "^0.7.0",
@@ -551,7 +551,7 @@
         }
       ],
       "meta": "src/components/sheet/meta.md",
-      "registryDependencies": ["cn"],
+      "registryDependencies": ["cn", "use-radix-popper-guard"],
       "dependencies": {
         "radix-ui": "^1.4.3",
         "class-variance-authority": "^0.7.0",
@@ -812,6 +812,20 @@
       ],
       "updateStrategy": "frozen"
     },
+    {
+      "id": "use-radix-popper-guard",
+      "name": "useRadixPopperGuard",
+      "type": "hook",
+      "description": "防止 Radix DismissableLayer 级联关闭 — Dialog/Sheet 内嵌 Select/Popover 时阻止误关宿主弹窗",
+      "files": [
+        {
+          "source": "src/hooks/use-radix-popper-guard.ts",
+          "targetAlias": "hooks",
+          "targetName": "use-radix-popper-guard.ts"
+        }
+      ],
+      "updateStrategy": "frozen"
+    },
     {
       "id": "sidebar",
       "name": "Sidebar",
@@ -1150,11 +1164,6 @@
           "source": "src/components/tree/index.tsx",
           "targetAlias": "components",
           "targetName": "tree.tsx"
-        },
-        {
-          "source": "src/components/tree/utils.ts",
-          "targetAlias": "components",
-          "targetName": "utils.ts"
         }
       ],
       "meta": "src/components/tree/meta.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamix-evo/ui",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Source-injected UI components for Teamix Evo (shadcn-based, antd capabilities)",
   "type": "module",
   "files": [
@@ -51,9 +51,9 @@
     "vite": "^5.4.0",
     "vite-tsconfig-paths": "^6.1.1",
     "zod": "^3",
-    "@teamix-evo/registry": "0.12.0",
-    "@teamix-evo/eslint-config": "0.2.3",
-    "@teamix-evo/tokens": "^0.8.0"
+    "@teamix-evo/eslint-config": "0.3.0",
+    "@teamix-evo/tokens": "^0.8.2",
+    "@teamix-evo/registry": "0.14.0"
   },
   "publishConfig": {
     "access": "public",

package/src/_design-system/theme-tokens/stories.tsx

@@ -655,7 +655,7 @@ function RadiusRow({ k, cls }: { k: string; cls: string }) {
         {/* 隐形 probe 用来取值,与可见样本同一 class 同一渲染路径 */}
         <div ref={probeRef} className={cls} style={{ display: 'none' }} />
         <div
-          className={`flex h-16 w-16 items-center justify-center border-2 border-foreground ${cls}`}
+          className={`flex items-center justify-center border-2 border-foreground size-16 ${cls}`}
           aria-label={`rounded-${k} sample`}
         >
           <span className="font-mono text-xxs uppercase tracking-widest">
@@ -1140,7 +1140,7 @@ function SpacingRow({
           element-A
         </div>
         <div
-          className="w-full border-l-2 border-r-2 border-primary"
+          className="w-full border-primary border-x-2"
           style={{ height: `var(${varName})`, minHeight: '2px' }}
           aria-label={`gap ${varName}`}
         />

package/src/components/accordion/index.tsx

@@ -121,7 +121,7 @@ function AccordionContent({
   return (
     <AccordionPrimitive.Content
       data-slot="accordion-content"
-      className="overflow-hidden text-sm data-[state=open]:animate-accordion-down data-[state=closed]:animate-accordion-up"
+      className="overflow-hidden text-sm data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
       {...props}
     >
       <div

package/src/components/affix/meta.md

@@ -21,3 +21,29 @@
 | `offsetBottom` | `number` | – | – | 距离视口底部指定偏移量后吸底（px）— 与 `offsetTop` 互斥。 |
 | `container` | `() => HTMLElement \| Window` | `() => window` | – | 滚动容器 — 默认 `window`。传入自定义容器时使用 `position: sticky`。 |
 | `onAffixChange` | `(affixed: boolean) => void` | – | – | 吸附状态变化回调。 |
+
+## 示例
+
+### Bottom
+
+吸底 — 滚动时固定在容器底部。
+
+```tsx
+<div
+  ref={ref}
+  className="relative h-[400px] overflow-auto rounded-md border border-border p-4"
+>
+  <div className="h-[500px] rounded-md border border-border bg-card p-4 text-sm text-muted-foreground">
+    向下滚动
+  </div>
+  <div className="mt-3" />
+  <Affix offsetBottom={16} container={() => ref.current!}>
+    <div className="rounded-md border border-border bg-background p-3 shadow-sm">
+      <Button block>立即提交（吸底）</Button>
+    </div>
+  </Affix>
+  <div className="h-[500px] rounded-md border border-border bg-card p-4 mt-3 text-sm text-muted-foreground">
+    底部区域
+  </div>
+</div>
+```

package/src/components/alert/index.tsx

@@ -25,7 +25,7 @@ import {
 } from '@/components/icon';
 
 const alertVariants = cva(
-  'group/alert relative grid w-full grid-cols-[auto_1fr] items-center gap-x-2 rounded-md p-2 text-left text-foreground has-data-[slot=alert-title]:items-start has-data-[slot=alert-action]:pr-18 has-data-[slot=alert-close]:pr-7',
+  'group/alert relative grid w-full grid-cols-[auto_1fr] items-center gap-x-2 rounded-md p-2 text-left text-foreground has-data-[slot=alert-action]:pr-18 has-data-[slot=alert-close]:pr-7 has-data-[slot=alert-title]:items-start',
   {
     variants: {
       variant: {
@@ -33,7 +33,7 @@ const alertVariants = cva(
         success: 'border border-success-bg bg-success-bg',
         warning: 'border border-warning-bg bg-warning-bg',
         destructive: 'border border-destructive-bg bg-destructive-bg',
-        help: 'border border-border border-help-bg bg-help-bg',
+        help: 'border border-help-bg bg-help-bg',
       },
     },
     defaultVariants: {

package/src/components/alert-dialog/index.tsx

@@ -68,7 +68,7 @@ function AlertDialogOverlay({
     <AlertDialogPrimitive.Overlay
       data-slot="alert-dialog-overlay"
       className={cn(
-        'fixed inset-0 z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=closed]:animate-out data-[state=closed]:fade-out-0',
+        'fixed inset-0 z-50 bg-black/10 duration-100 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0 supports-backdrop-filter:backdrop-blur-xs',
         className,
       )}
       {...props}
@@ -101,7 +101,7 @@ function AlertDialogContent({
         data-size={size}
         className={cn(
           // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- mobile viewport needs calc(100% - 2rem) for safe inset; box-shadow drives via component-level token --dialog-shadow per ADR 0026.
-          'group/alert-dialog-content fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 rounded-md bg-popover text-sm text-popover-foreground shadow-[var(--dialog-shadow,0px_6px_24px_0px_rgba(0,0,0,0.1))] duration-100 outline-none data-[size=sm]:sm:max-w-md data-[size=md]:sm:max-w-xl data-[size=lg]:sm:max-w-3xl data-[size=xl]:sm:max-w-6xl 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/alert-dialog-content fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-1/2 rounded-md bg-popover text-sm text-popover-foreground shadow-[var(--dialog-shadow,0px_6px_24px_0px_rgba(0,0,0,0.1))] duration-100 outline-none 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 data-[size=lg]:sm:max-w-3xl data-[size=md]:sm:max-w-xl data-[size=sm]:sm:max-w-md data-[size=xl]:sm:max-w-6xl',
           className,
         )}
         {...props}
@@ -139,7 +139,7 @@ function AlertDialogBody({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
       data-slot="alert-dialog-body"
-      className={cn('pr-5 pl-11 pt-3', className)}
+      className={cn('pt-3 pr-5 pl-11', className)}
       {...props}
     />
   );

package/src/components/alert-dialog/meta.md

@@ -178,3 +178,55 @@
   </AlertDialogContent>
 </AlertDialog>
 ```
+
+### Async
+
+异步确认 — onAction 返回 Promise，loading 期间禁止关闭。
+
+```tsx
+const [open, setOpen] = React.useState(false);
+const [loading, setLoading] = React.useState(false);
+const onConfirm = async (e: React.MouseEvent) => {
+  e.preventDefault();
+  setLoading(true);
+  await new Promise((r) => setTimeout(r, 1500));
+  setLoading(false);
+  setOpen(false);
+};
+return (
+  <AlertDialog
+    open={open}
+    onOpenChange={(next) => {
+      if (loading) return;
+      setOpen(next);
+    }}
+  >
+    <AlertDialogTrigger asChild>
+      <Button variant="destructive">删除</Button>
+    </AlertDialogTrigger>
+    <AlertDialogContent>
+      <AlertDialogHeader>
+        <AlertDialogMedia>
+          <ErrorFilledIcon className="text-destructive" />
+        </AlertDialogMedia>
+        <AlertDialogTitle>确认删除？</AlertDialogTitle>
+      </AlertDialogHeader>
+      <AlertDialogBody>
+        <AlertDialogDescription>
+          onAction 返回 Promise，loading 期间无法关闭对话框。
+        </AlertDialogDescription>
+      </AlertDialogBody>
+      <AlertDialogFooter>
+        <AlertDialogCancel disabled={loading}>取消</AlertDialogCancel>
+        <Button
+          variant="destructive"
+          loading={loading}
+          onClick={onConfirm}
+        >
+          确认删除
+        </Button>
+      </AlertDialogFooter>
+    </AlertDialogContent>
+  </AlertDialog>
+);
+```

package/src/components/alert-dialog/stories.tsx

@@ -221,53 +221,50 @@ export const Warning: Story = {
 export const Async: Story = {
   name: '异步确认',
   render: () => {
-    function Demo() {
-      const [open, setOpen] = React.useState(false);
-      const [loading, setLoading] = React.useState(false);
-      const onConfirm = async (e: React.MouseEvent) => {
-        e.preventDefault();
-        setLoading(true);
-        await new Promise((r) => setTimeout(r, 1500));
-        setLoading(false);
-        setOpen(false);
-      };
-      return (
-        <AlertDialog
-          open={open}
-          onOpenChange={(next) => {
-            if (loading) return;
-            setOpen(next);
-          }}
-        >
-          <AlertDialogTrigger asChild>
-            <Button variant="destructive">删除</Button>
-          </AlertDialogTrigger>
-          <AlertDialogContent>
-            <AlertDialogHeader>
-              <AlertDialogMedia>
-                <ErrorFilledIcon className="text-destructive" />
-              </AlertDialogMedia>
-              <AlertDialogTitle>确认删除？</AlertDialogTitle>
-            </AlertDialogHeader>
-            <AlertDialogBody>
-              <AlertDialogDescription>
-                onAction 返回 Promise，loading 期间无法关闭对话框。
-              </AlertDialogDescription>
-            </AlertDialogBody>
-            <AlertDialogFooter>
-              <AlertDialogCancel disabled={loading}>取消</AlertDialogCancel>
-              <Button
-                variant="destructive"
-                loading={loading}
-                onClick={onConfirm}
-              >
-                确认删除
-              </Button>
-            </AlertDialogFooter>
-          </AlertDialogContent>
-        </AlertDialog>
-      );
-    }
-    return <Demo />;
+    const [open, setOpen] = React.useState(false);
+    const [loading, setLoading] = React.useState(false);
+    const onConfirm = async (e: React.MouseEvent) => {
+      e.preventDefault();
+      setLoading(true);
+      await new Promise((r) => setTimeout(r, 1500));
+      setLoading(false);
+      setOpen(false);
+    };
+    return (
+      <AlertDialog
+        open={open}
+        onOpenChange={(next) => {
+          if (loading) return;
+          setOpen(next);
+        }}
+      >
+        <AlertDialogTrigger asChild>
+          <Button variant="destructive">删除</Button>
+        </AlertDialogTrigger>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogMedia>
+              <ErrorFilledIcon className="text-destructive" />
+            </AlertDialogMedia>
+            <AlertDialogTitle>确认删除？</AlertDialogTitle>
+          </AlertDialogHeader>
+          <AlertDialogBody>
+            <AlertDialogDescription>
+              onAction 返回 Promise，loading 期间无法关闭对话框。
+            </AlertDialogDescription>
+          </AlertDialogBody>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={loading}>取消</AlertDialogCancel>
+            <Button
+              variant="destructive"
+              loading={loading}
+              onClick={onConfirm}
+            >
+              确认删除
+            </Button>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    );
   },
 };

package/src/components/avatar/index.tsx

@@ -91,7 +91,7 @@ function AvatarFallback({
       className={cn(
         'flex size-full items-center justify-center bg-border text-muted-foreground',
         'group-data-[shape=circle]/avatar:rounded-full group-data-[shape=square]/avatar:rounded-md',
-        'group-data-[size=sm]/avatar:text-xs group-data-[size=default]/avatar:text-xs group-data-[size=lg]/avatar:text-sm',
+        'group-data-[size=default]/avatar:text-xs group-data-[size=lg]/avatar:text-sm group-data-[size=sm]/avatar:text-xs',
         '[&>svg]:size-1/2',
         className,
       )}

package/src/components/badge/index.tsx

@@ -144,7 +144,7 @@ function Indicator({
       data-indicator-kind={kind}
       data-size={size}
       className={cn(
-        'pointer-events-none inline-flex items-center justify-center rounded-full font-medium leading-none select-none',
+        'pointer-events-none inline-flex items-center justify-center rounded-full leading-none font-medium select-none',
         // 默认色（content 形态走透明，由 color / 自定义 className 决定）
         !isContent && 'bg-destructive text-destructive-foreground',
         // content 形态 + 有色非透明底 → 白色文字
@@ -162,7 +162,7 @@ function Indicator({
           : 'h-4 min-w-4 px-1 text-xs',
         // wrapped 模式：绝对定位 + ring 描边
         wrapped &&
-          'absolute top-0 right-0 z-10 origin-center -translate-y-1/2 translate-x-1/2 ring-2 ring-background',
+          'absolute top-0 right-0 z-10 origin-center translate-x-1/2 -translate-y-1/2 ring-2 ring-background',
       )}
       style={style}
     >

package/src/components/badge/meta.md

@@ -235,3 +235,51 @@
   </Badge>
 </div>
 ```
+
+### Dynamic
+
+受控示例：count 与 dot 动态切换。
+
+```tsx
+function DynamicDemo() {
+  const [count, setCount] = React.useState(0);
+  const [show, setShow] = React.useState(true);
+  return (
+    <div className="flex flex-col gap-4">
+      <div className="flex items-center gap-3">
+        <Badge count={count}>
+          <Avatar>
+            <AvatarFallback>N</AvatarFallback>
+          </Avatar>
+        </Badge>
+        <Badge count={count} showZero>
+          <Avatar>
+            <AvatarFallback>Z</AvatarFallback>
+          </Avatar>
+        </Badge>
+        <Button size="sm" onClick={() => setCount((c) => c + 1)}>
+          +
+        </Button>
+        <Button
+          size="sm"
+          variant="outline"
+          onClick={() => setCount((c) => Math.max(0, c - 1))}
+        >
+          -
+        </Button>
+      </div>
+      <div className="flex items-center gap-3">
+        <Badge dot={show}>
+          <Avatar>
+            <AvatarFallback>D</AvatarFallback>
+          </Avatar>
+        </Badge>
+        <Button size="sm" onClick={() => setShow((s) => !s)}>
+          Toggle Dot
+        </Button>
+      </div>
+    </div>
+  );
+}
+return <DynamicDemo />;
+```

package/src/components/button/index.tsx

@@ -24,7 +24,7 @@ import { Spinner } from '@/components/spinner';
 // - shadow：组件不写，uni-manager 通过 theme.css scoped CSS [data-slot='button'] 注入
 
 const buttonVariants = cva(
-  'inline-flex shrink-0 cursor-pointer items-center justify-center rounded-md font-normal whitespace-nowrap transition-colors select-none focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+  'inline-flex shrink-0 cursor-pointer items-center justify-center rounded-md font-normal whitespace-nowrap transition-colors select-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-none disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
   {
     variants: {
       variant: {
@@ -54,7 +54,7 @@ const buttonVariants = cva(
       shape: {
         default: '',
         round: 'rounded-full',
-        circle: 'rounded-full aspect-square p-0',
+        circle: 'aspect-square rounded-full p-0',
         square: 'aspect-square p-0',
       },
       block: {

package/src/components/button/meta.md

@@ -96,6 +96,21 @@ Button 只有图标时，应该显示为正方形。
 </div>
 ```
 
+### Loading
+
+通过设置 `loading` 属性即可以让按钮处于加载状态。
+
+```tsx
+<div className="flex gap-2">
+  <Button loading variant="secondary">
+    Loading
+  </Button>
+  <Button loading={loading} onClick={() => setLoading(true)}>
+    Click to loading
+  </Button>
+</div>
+```
+
 ### Disabled
 
 添加 `disabled` 属性即可让按钮处于不可用状态，同时按钮样式也会改变。

package/src/components/button/stories.tsx

@@ -93,7 +93,7 @@ export const IconOnly: Story = {
 
 /** 通过设置 `loading` 属性即可以让按钮处于加载状态。 */
 export const Loading: Story = {
-  render: function LoadingDemo() {
+  render: () => {
     const [loading, setLoading] = useState(false);
     return (
       <div className="flex gap-2">

package/src/components/calendar/index.tsx

@@ -117,7 +117,7 @@ function Calendar({
           defaultClassNames.week_number,
         ),
         day: cn(
-          'group/day relative aspect-square h-full w-full rounded-md p-0 text-center select-none [&:last-child[data-selected=true]_button]:rounded-r-md',
+          'group/day relative aspect-square size-full rounded-md p-0 text-center select-none [&:last-child[data-selected=true]_button]:rounded-r-md',
           props.showWeekNumber
             ? '[&:nth-child(2)[data-selected=true]_button]:rounded-l-md'
             : '[&:first-child[data-selected=true]_button]:rounded-l-md',
@@ -231,7 +231,7 @@ function CalendarDayButton({
       data-range-end={modifiers.range_end}
       data-range-middle={modifiers.range_middle}
       className={cn(
-        'relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 text-xs leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-1 group-data-[focused=true]/day:ring-ring data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-muted data-[range-middle=true]:text-foreground data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md hover:text-foreground [&>span]:text-xs [&>span]:opacity-70',
+        'relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 text-xs leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-1 group-data-[focused=true]/day:ring-ring hover:text-foreground data-[range-end=true]:rounded-md data-[range-end=true]:rounded-r-md data-[range-middle=true]:rounded-none data-[range-middle=true]:bg-muted data-[range-middle=true]:text-foreground data-[range-start=true]:rounded-md data-[range-start=true]:rounded-l-md [&>span]:text-xs [&>span]:opacity-70',
         defaultClassNames.day,
         className,
         isActive &&

package/src/components/card/index.tsx

@@ -28,7 +28,7 @@ import { Skeleton } from '@/components/skeleton';
 // - 垂直 padding 20px (`py-5`) / sm 16px (`py-4`)
 // - normal 无阴影，hover 抬升
 const cardVariants = cva(
-  'group/card flex flex-col overflow-hidden rounded-md bg-card text-card-foreground text-sm has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-md *:[img:last-child]:rounded-b-md',
+  'group/card flex flex-col overflow-hidden rounded-md bg-card text-sm text-card-foreground has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-md *:[img:last-child]:rounded-b-md',
   {
     variants: {
       variant: {

package/src/components/carousel/index.tsx

@@ -344,7 +344,7 @@ function CarouselPrevious({
       className={cn(
         'absolute z-10 touch-manipulation',
         arrowPosition === 'inner' &&
-          'bg-background/80 backdrop-blur-sm shadow-sm',
+          'bg-background/80 shadow-sm backdrop-blur-sm',
         positionClass,
         className,
       )}
@@ -390,7 +390,7 @@ function CarouselNext({
       className={cn(
         'absolute z-10 touch-manipulation',
         arrowPosition === 'inner' &&
-          'bg-background/80 backdrop-blur-sm shadow-sm',
+          'bg-background/80 shadow-sm backdrop-blur-sm',
         positionClass,
         className,
       )}

package/src/components/carousel/meta.md

@@ -172,6 +172,38 @@
 </Carousel>
 ```
 
+### Controlled
+
+受控当前页：外部按钮跳转。
+
+```tsx
+<div className="flex w-full max-w-xs flex-col gap-3 px-12">
+  <Carousel activeIndex={active} onChange={setActive}>
+    <CarouselContent>
+      {slides.map((i) => (
+        <CarouselItem key={i}>
+          <Slide index={i - 1}>{i}</Slide>
+        </CarouselItem>
+      ))}
+    </CarouselContent>
+    <CarouselPrevious />
+    <CarouselNext />
+  </Carousel>
+  <div className="flex flex-wrap gap-2">
+    {slides.map((_, i) => (
+      <Button
+        key={i}
+        size="sm"
+        variant={i === active ? 'default' : 'outline'}
+        onClick={() => setActive(i)}
+      >
+        {i + 1}
+      </Button>
+    ))}
+  </div>
+</div>
+```
+
 ### CustomDots
 
 自定义指示点渲染。
@@ -195,8 +227,8 @@
           onClick={onClick}
           className={
             selected
-              ? 'h-6 w-6 cursor-pointer rounded-md bg-primary text-xs text-primary-foreground'
-              : 'h-6 w-6 cursor-pointer rounded-md bg-muted text-xs text-muted-foreground hover:bg-accent'
+              ? 'cursor-pointer rounded-md bg-primary text-xs text-primary-foreground size-6'
+              : 'cursor-pointer rounded-md bg-muted text-xs text-muted-foreground hover:bg-accent size-6'
           }
         >
           {index + 1}

package/src/components/carousel/stories.tsx

@@ -257,8 +257,8 @@ export const CustomDots: Story = {
               onClick={onClick}
               className={
                 selected
-                  ? 'h-6 w-6 cursor-pointer rounded-md bg-primary text-xs text-primary-foreground'
-                  : 'h-6 w-6 cursor-pointer rounded-md bg-muted text-xs text-muted-foreground hover:bg-accent'
+                  ? 'cursor-pointer rounded-md bg-primary text-xs text-primary-foreground size-6'
+                  : 'cursor-pointer rounded-md bg-muted text-xs text-muted-foreground hover:bg-accent size-6'
               }
             >
               {index + 1}

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

@@ -72,6 +72,7 @@ function CascaderPanel({
   size?: 'sm' | 'default';
 }) {
   return (
+    // eslint-disable-next-line tailwindcss/no-contradicting-classname -- divide-color ≠ border-color
     <div className="flex max-h-56 divide-x divide-border overflow-hidden rounded-md border border-border bg-popover shadow-md">
       {columns.map((column, depth) => (
         <div key={depth} className="min-w-32 overflow-y-auto p-1">
@@ -291,7 +292,7 @@ function CascaderSelect({
 
       {/* Dropdown */}
       {open && (
-        <div className="absolute left-0 top-full z-50 mt-1">
+        <div className="absolute top-full left-0 z-50 mt-1">
           <CascaderPanel
             columns={columns}
             activeValues={activeValues}

package/src/components/cascader-select/meta.md

@@ -26,3 +26,49 @@
 | `size` | `'sm' \| 'default'` | – | – | 尺寸。@default 'default' |
 | `allowClear` | `boolean` | `true` | – | 是否允许清空：有选中值且未加载/未禁用时，右侧 chevron 切为 × 按钮。 与 Select 一致：右侧图标优先级 loading > clear > chevron，三者互斥、占同一位置。 |
 | `loading` | `boolean` | `false` | – | 加载态：将右侧图标替换为旋转 spinner，并标记 `data-loading="true"` 供外部样式穿透。 |
+
+## 示例
+
+### Basic
+
+```tsx
+<CascaderSelect options={options} />
+```
+
+### DefaultValue
+
+```tsx
+<CascaderSelect options={options} defaultValue={['zhejiang'} 'hangzhou'={'hangzhou'} 'xihu']={'xihu']} />
+```
+
+### SmallSize
+
+```tsx
+<CascaderSelect options={options} size="sm" />
+```
+
+### Disabled
+
+```tsx
+<CascaderSelect options={options} disabled defaultValue={['jiangsu'} 'nanjing'={'nanjing'} 'xuanwu']={'xuanwu']} />
+```
+
+### WithClear
+
+有选中值时右侧 chevron 切为 ×，点击清空。优先级：loading > clear > chevron。
+
+```tsx
+<CascaderSelect
+  options={options}
+  value={value}
+  onChange={(next) => setValue(next)}
+/>
+```
+
+### Loading
+
+加载态：`loading` 为 `true` 时右侧图标替换为旋转 spinner。
+
+```tsx
+<CascaderSelect options={options} loading />
+```