@teamix-evo/ui 0.7.0 → 0.7.2

package/src/components/input-group/stories.tsx

@@ -63,7 +63,7 @@ export const WithTrailingIcon: Story = {
  * 仅当 value 非空时显示清除按钮。
  */
 export const Search: Story = {
-  render: function SearchStory() {
+  render: () => {
     const [value, setValue] = useState('');
     return (
       <InputGroup className="w-64">
@@ -93,7 +93,7 @@ export const Search: Story = {
  * 仅当 `visible` 为 true 时渲染，点击由父级清空 `value`。
  */
 export const Clear: Story = {
-  render: function ClearStory() {
+  render: () => {
     const [value, setValue] = useState('hello world');
     return (
       <InputGroup className="w-64">
@@ -117,7 +117,7 @@ export const Clear: Story = {
  * 密码输入：使用 `InputGroupPasswordToggle` 受控版，由父级同时控制 `type` 与 `visible`。
  */
 export const Password: Story = {
-  render: function PasswordStory() {
+  render: () => {
     const [visible, setVisible] = useState(false);
     return (
       <InputGroup className="w-64">
@@ -138,7 +138,7 @@ export const Password: Story = {
 
 /** 金额输入：后置货币符号，展示带格式化的数值输入。 */
 export const Currency: Story = {
-  render: function CurrencyStory() {
+  render: () => {
     const [value, setValue] = useState('1234.56');
     const format = (v: string) => {
       const num = parseFloat(v.replace(/,/g, ''));
@@ -199,7 +199,7 @@ export const Loading: Story = {
  * 超过 maxLength 时计数自动转 destructive 色。
  */
 export const WithCount: Story = {
-  render: function WithCountStory() {
+  render: () => {
     const [value, setValue] = useState('');
     const max = 20;
     return (
@@ -223,7 +223,7 @@ export const WithCount: Story = {
  * 对齐 cloud-design `hasLimitHint` 的视觉位置。
  */
 export const MultilineWithCount: Story = {
-  render: function MultilineWithCountStory() {
+  render: () => {
     const [value, setValue] = useState('');
     const max = 100;
     return (

package/src/components/input-ip/index.tsx

@@ -224,7 +224,7 @@ const InputIP = React.forwardRef<HTMLDivElement, InputIPProps>(
         {octets.map((octet, i) => (
           <React.Fragment key={i}>
             {i > 0 && (
-              <span className="select-none text-muted-foreground">.</span>
+              <span className="text-muted-foreground select-none">.</span>
             )}
             <input
               ref={(el) => {
@@ -248,7 +248,7 @@ const InputIP = React.forwardRef<HTMLDivElement, InputIPProps>(
         ))}
         {showCidr && (
           <>
-            <span className="select-none px-0.5 text-muted-foreground">/</span>
+            <span className="px-0.5 text-muted-foreground select-none">/</span>
             <Select
               value={cidr || undefined}
               onValueChange={handleCidrChange}

package/src/components/input-ip/meta.md

@@ -27,6 +27,28 @@ IP 地址输入框 InputIP
 
 ## 示例
 
+### Controlled
+
+受控模式，外部管理 value。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <InputIP value={value} onChange={setValue} />
+  <span className="text-xs text-muted-foreground">当前值：{value}</span>
+</div>
+```
+
+### WithCidr
+
+带 CIDR 前缀选择的网段输入。右侧 CIDR 选择器使用 ui Select。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <InputIP showCidr value={value} onChange={setValue} />
+  <span className="text-xs text-muted-foreground">当前值：{value}</span>
+</div>
+```
+
 ### Sizes
 
 三种尺寸。
@@ -39,6 +61,14 @@ IP 地址输入框 InputIP
 </div>
 ```
 
+### Disabled
+
+禁用态。
+
+```tsx
+<InputIP className="w-52" defaultValue="10.0.0.1" disabled />
+```
+
 ### Invalid
 
 错误态（校验失败）。

package/src/components/input-ip/stories.tsx

@@ -21,7 +21,7 @@ export const Default: Story = {
 
 /** 受控模式，外部管理 value。 */
 export const Controlled: Story = {
-  render: function ControlledStory() {
+  render: () => {
     const [value, setValue] = useState('192.168.1.1');
     return (
       <div className="flex flex-col gap-2">
@@ -34,7 +34,7 @@ export const Controlled: Story = {
 
 /** 带 CIDR 前缀选择的网段输入。右侧 CIDR 选择器使用 ui Select。 */
 export const WithCidr: Story = {
-  render: function CidrStory() {
+  render: () => {
     const [value, setValue] = useState('192.168.1.0/24');
     return (
       <div className="flex flex-col gap-2">

package/src/components/input-number/index.tsx

@@ -304,7 +304,7 @@ const InputNumber = React.forwardRef<HTMLInputElement, InputNumberProps>(
           onWheel={handleWheel}
           data-slot="input-number-control"
           className={cn(
-            'w-full bg-transparent px-2.5 text-foreground placeholder:text-muted-foreground focus-visible:outline-none disabled:cursor-not-allowed read-only:cursor-default',
+            'w-full bg-transparent px-2.5 text-foreground placeholder:text-muted-foreground read-only:cursor-default focus-visible:outline-none disabled:cursor-not-allowed',
             variant === 'inline' && 'text-center',
           )}
           {...props}
@@ -325,7 +325,8 @@ const InputNumber = React.forwardRef<HTMLInputElement, InputNumberProps>(
         {controls && variant === 'default' ? (
           <div
             data-slot="input-number-handlers"
-            className="flex flex-col divide-y divide-input border-l border-input opacity-0 transition-opacity group-hover/input-number:opacity-100 group-focus-within/input-number:opacity-100"
+            // eslint-disable-next-line tailwindcss/no-contradicting-classname -- divide-color ≠ border-color
+            className="flex flex-col divide-y divide-input border-l border-input opacity-0 transition-opacity group-focus-within/input-number:opacity-100 group-hover/input-number:opacity-100"
           >
             <button
               type="button"

package/src/components/input-number/meta.md

@@ -125,6 +125,14 @@
 </div>
 ```
 
+### ReadOnly
+
+`readOnly` 只读：可聚焦/复制但不可编辑、不可步进。
+
+```tsx
+<InputNumber readOnly defaultValue={42} className="w-40" />
+```
+
 ### Inline
 
 `variant="inline"` 两侧加减按钮，适合紧凑场景。
@@ -147,6 +155,38 @@
 <InputNumber controls={false} placeholder="纯输入" className="w-40" />
 ```
 
+### ChangeOnBlur
+
+`changeOnBlur={false}` 让 onChange 在每次有效输入时触发，否则仅 blur/Enter 提交。
+
+```tsx
+<div className="flex flex-col gap-3 text-xs">
+  <div className="flex items-center gap-3">
+    <InputNumber value={a} onChange={setA} className="w-40" />
+    <span className="text-muted-foreground">
+      默认（仅 blur/Enter 触发）：{String(a)}
+    </span>
+  </div>
+  <div className="flex items-center gap-3">
+    <InputNumber
+      value={b}
+      onChange={setB}
+      changeOnBlur={false}
+      className="w-40"
+    />
+    <span className="text-muted-foreground">实时触发：{String(b)}</span>
+  </div>
+</div>
+```
+
+### ChangeOnWheel
+
+`changeOnWheel` 启用滚轮调整（仅在聚焦时生效，默认关闭防误触）。
+
+```tsx
+<InputNumber changeOnWheel defaultValue={0} className="w-40" />
+```
+
 ### Keyboard
 
 `keyboard={false}` 关闭键盘 ↑↓ 步进。
@@ -154,3 +194,30 @@
 ```tsx
 <InputNumber keyboard={false} defaultValue={0} className="w-40" />
 ```
+
+### Invalid
+
+`aria-invalid` 视觉与 Input 一致。
+
+```tsx
+<InputNumber aria-invalid defaultValue={42} className="w-40" />
+```
+
+### Disabled
+
+禁用状态。
+
+```tsx
+<InputNumber disabled defaultValue={42} className="w-40" />
+```
+
+### Controlled
+
+受控模式。
+
+```tsx
+<div className="flex items-center gap-3">
+  <InputNumber value={val} onChange={setVal} className="w-40" />
+  <span className="text-xs text-muted-foreground">值: {String(val)}</span>
+</div>
+```

package/src/components/input-number/stories.tsx

@@ -126,7 +126,7 @@ export const NoControls: Story = {
 
 /** `changeOnBlur={false}` 让 onChange 在每次有效输入时触发，否则仅 blur/Enter 提交。 */
 export const ChangeOnBlur: Story = {
-  render: function ChangeOnBlurDemo() {
+  render: () => {
     const [a, setA] = useState<number | string | null>(0);
     const [b, setB] = useState<number | string | null>(0);
     return (
@@ -175,7 +175,7 @@ export const Disabled: Story = {
 
 /** 受控模式。 */
 export const Controlled: Story = {
-  render: function ControlledDemo() {
+  render: () => {
     const [val, setVal] = useState<number | string | null>(10);
     return (
       <div className="flex items-center gap-3">

package/src/components/item/index.tsx

@@ -66,7 +66,7 @@ function ItemGroupHeader({ className, ...props }: ItemGroupHeaderProps) {
     <div
       data-slot="item-group-header"
       className={cn(
-        'flex items-center px-3 py-2.5 text-sm font-medium border-b border-border',
+        'flex items-center border-b border-border px-3 py-2.5 text-sm font-medium',
         className,
       )}
       {...props}
@@ -83,7 +83,7 @@ function ItemGroupFooter({ className, ...props }: ItemGroupFooterProps) {
     <div
       data-slot="item-group-footer"
       className={cn(
-        'flex items-center px-3 py-2.5 text-xs text-muted-foreground border-t border-border',
+        'flex items-center border-t border-border px-3 py-2.5 text-xs text-muted-foreground',
         className,
       )}
       {...props}
@@ -94,7 +94,7 @@ function ItemGroupFooter({ className, ...props }: ItemGroupFooterProps) {
 // ─── Item ─────────────────────────────────────────────────────────────────────
 
 const itemVariants = cva(
-  'group/item flex w-full items-center text-xs outline-none transition-colors duration-100 focus-visible:ring-1 focus-visible:ring-ring',
+  'group/item flex w-full items-center text-xs transition-colors duration-100 outline-none focus-visible:ring-1 focus-visible:ring-ring',
   {
     variants: {
       variant: {
@@ -103,7 +103,7 @@ const itemVariants = cva(
         muted: 'rounded-md bg-muted/50',
       },
       size: {
-        default: 'gap-3 px-3 py-3',
+        default: 'gap-3 p-3',
         sm: 'gap-2.5 px-3 py-2.5',
         xs: 'gap-2 px-2.5 py-2',
       },

package/src/components/label/meta.md

@@ -54,6 +54,14 @@
 </div>
 ```
 
+### Required
+
+必填标记
+
+```tsx
+<Label required>用户名</Label>
+```
+
 ### RequiredWithInput
 
 必填 + 关联输入框

package/src/components/mentions/meta.md

@@ -63,6 +63,21 @@
 </div>
 ```
 
+### AsyncSearch
+
+通过 `onSearch` 配合 `filterOption={false}` 实现服务端搜索。
+
+```tsx
+<Mentions
+  options={opts}
+  loading={loading}
+  filterOption={false}
+  onSearch={handleSearch}
+  placeholder="输入 @ 远程搜索用户"
+  className="max-w-sm"
+/>
+```
+
 ### PlacementTop
 
 浮层向上展开，适合靠近底部的输入区。

package/src/components/menubar/index.tsx

@@ -132,7 +132,7 @@ function MenubarItem({
       data-inset={inset}
       data-variant={variant}
       className={cn(
-        'group/menubar-item relative flex h-8 cursor-pointer items-center gap-1.5 rounded-md px-1.5 py-1 text-xs outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive!',
+        'group/menubar-item relative flex h-8 cursor-pointer items-center gap-1.5 rounded-md px-1.5 py-1 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-inset:pl-7 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive!',
         className,
       )}
       {...props}
@@ -154,7 +154,7 @@ function MenubarCheckboxItem({
       data-slot="menubar-checkbox-item"
       data-inset={inset}
       className={cn(
-        'relative flex h-8 cursor-pointer items-center gap-1.5 rounded-md py-1 pr-1.5 pl-7 text-xs outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none [&_svg]:pointer-events-none [&_svg]:shrink-0',
+        'relative flex h-8 cursor-pointer items-center gap-1.5 rounded-md py-1 pr-1.5 pl-7 text-xs outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-disabled:pointer-events-none data-inset:pl-7 [&_svg]:pointer-events-none [&_svg]:shrink-0',
         className,
       )}
       checked={checked}
@@ -183,7 +183,7 @@ function MenubarRadioItem({
       data-slot="menubar-radio-item"
       data-inset={inset}
       className={cn(
-        'relative flex h-8 cursor-pointer items-center gap-1.5 rounded-md py-1 pr-1.5 pl-7 text-xs outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-7 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+        'relative flex h-8 cursor-pointer items-center gap-1.5 rounded-md py-1 pr-1.5 pl-7 text-xs outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 data-inset:pl-7 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
         className,
       )}
       {...props}
@@ -285,7 +285,7 @@ function MenubarSubContent({
     <MenubarPrimitive.SubContent
       data-slot="menubar-sub-content"
       className={cn(
-        'z-50 min-w-32 origin-(--radix-menubar-content-transform-origin) overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/10 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',
+        'z-50 min-w-32 origin-(--radix-menubar-content-transform-origin) overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/10 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}

package/src/components/navigation-menu/index.tsx

@@ -120,7 +120,7 @@ function NavigationMenuTrigger({
     >
       {children}{' '}
       <ChevronDownIcon
-        className="relative top-px ml-1 size-3 transition duration-300 group-data-popup-open/navigation-menu-trigger:rotate-180 group-data-open/navigation-menu-trigger:rotate-180"
+        className="relative top-px ml-1 size-3 transition duration-300 group-data-open/navigation-menu-trigger:rotate-180 group-data-popup-open/navigation-menu-trigger:rotate-180"
         aria-hidden="true"
       />
     </NavigationMenuPrimitive.Trigger>
@@ -136,7 +136,7 @@ function NavigationMenuContent({
     <NavigationMenuPrimitive.Content
       data-slot="navigation-menu-content"
       className={cn(
-        'top-0 left-0 w-full p-1 ease-[cubic-bezier(0.22,1,0.36,1)] group-data-[viewport=false]/navigation-menu:top-full group-data-[viewport=false]/navigation-menu:mt-1.5 group-data-[viewport=false]/navigation-menu:overflow-hidden group-data-[viewport=false]/navigation-menu:rounded-md group-data-[viewport=false]/navigation-menu:bg-popover group-data-[viewport=false]/navigation-menu:text-popover-foreground group-data-[viewport=false]/navigation-menu:shadow group-data-[viewport=false]/navigation-menu:ring-1 group-data-[viewport=false]/navigation-menu:ring-foreground/10 group-data-[viewport=false]/navigation-menu:duration-300 data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 data-[motion^=from-]:animate-in data-[motion^=from-]:fade-in data-[motion^=to-]:animate-out data-[motion^=to-]:fade-out **:data-[slot=navigation-menu-link]:focus:ring-0 **:data-[slot=navigation-menu-link]:focus:outline-none md:absolute md:w-auto group-data-[viewport=false]/navigation-menu:data-[state=open]:animate-in group-data-[viewport=false]/navigation-menu:data-[state=open]:fade-in-0 group-data-[viewport=false]/navigation-menu:data-[state=open]:zoom-in-95 group-data-[viewport=false]/navigation-menu:data-[state=closed]:animate-out group-data-[viewport=false]/navigation-menu:data-[state=closed]:fade-out-0 group-data-[viewport=false]/navigation-menu:data-[state=closed]:zoom-out-95',
+        'top-0 left-0 w-full p-1 ease-[cubic-bezier(0.22,1,0.36,1)] group-data-[viewport=false]/navigation-menu:top-full group-data-[viewport=false]/navigation-menu:mt-1.5 group-data-[viewport=false]/navigation-menu:overflow-hidden group-data-[viewport=false]/navigation-menu:rounded-md group-data-[viewport=false]/navigation-menu:bg-popover group-data-[viewport=false]/navigation-menu:text-popover-foreground group-data-[viewport=false]/navigation-menu:shadow group-data-[viewport=false]/navigation-menu:ring-1 group-data-[viewport=false]/navigation-menu:ring-foreground/10 group-data-[viewport=false]/navigation-menu:duration-300 data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 data-[motion^=from-]:animate-in data-[motion^=from-]:fade-in data-[motion^=to-]:animate-out data-[motion^=to-]:fade-out **:data-[slot=navigation-menu-link]:focus:ring-0 **:data-[slot=navigation-menu-link]:focus:outline-none group-data-[viewport=false]/navigation-menu:data-[state=closed]:animate-out group-data-[viewport=false]/navigation-menu:data-[state=closed]:fade-out-0 group-data-[viewport=false]/navigation-menu:data-[state=closed]:zoom-out-95 group-data-[viewport=false]/navigation-menu:data-[state=open]:animate-in group-data-[viewport=false]/navigation-menu:data-[state=open]:fade-in-0 group-data-[viewport=false]/navigation-menu:data-[state=open]:zoom-in-95 md:absolute md:w-auto',
         className,
       )}
       {...props}
@@ -158,7 +158,7 @@ function NavigationMenuViewport({
       <NavigationMenuPrimitive.Viewport
         data-slot="navigation-menu-viewport"
         className={cn(
-          'origin-top-center relative mt-1.5 h-(--radix-navigation-menu-viewport-height) w-full overflow-hidden rounded-md bg-popover text-popover-foreground shadow ring-1 ring-foreground/10 duration-100 md:w-(--radix-navigation-menu-viewport-width) data-[state=open]:animate-in data-[state=open]:zoom-in-90 data-[state=closed]:animate-out data-[state=closed]:zoom-out-90',
+          'origin-top-center relative mt-1.5 h-(--radix-navigation-menu-viewport-height) w-full overflow-hidden rounded-md bg-popover text-popover-foreground shadow ring-1 ring-foreground/10 duration-100 data-[state=closed]:animate-out data-[state=closed]:zoom-out-90 data-[state=open]:animate-in data-[state=open]:zoom-in-90 md:w-(--radix-navigation-menu-viewport-width)',
           className,
         )}
         {...props}
@@ -198,7 +198,7 @@ function NavigationMenuIndicator({
       )}
       {...props}
     >
-      <div className="relative top-3/5 h-2 w-2 rotate-45 rounded-tl-sm bg-border shadow-md" />
+      <div className="relative top-3/5 size-2 rotate-45 rounded-tl-sm bg-border shadow-md" />
     </NavigationMenuPrimitive.Indicator>
   );
 }

package/src/components/page-header/index.tsx

@@ -102,7 +102,7 @@ const PageHeaderHeading = React.forwardRef<
         aria-label="返回"
         className={cn(
           'inline-flex shrink-0 cursor-pointer items-center justify-center rounded-sm text-muted-foreground transition-colors',
-          'hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+          'hover:text-foreground focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-none',
         )}
       >
         <ArrowLeft className="size-6" aria-hidden="true" />
@@ -166,7 +166,7 @@ const PageHeaderDescription = React.forwardRef<
   <p
     ref={ref}
     data-slot="page-header-description"
-    className={cn('my-2 text-xs text-muted-foreground', className)}
+    className={cn('mt-2 text-xs text-muted-foreground', className)}
     {...props}
   />
 ));

package/src/components/page-header/meta.md

@@ -23,6 +23,151 @@
 
 ## 示例
 
+### WithDescription
+
+标题 + 描述：标题下方附加一行描述文字。
+
+```tsx
+<PageHeader>
+  <PageHeaderContent>
+    <div className="flex flex-col">
+      <PageHeaderHeading>
+        <PageHeaderTitle>页面标题</PageHeaderTitle>
+      </PageHeaderHeading>
+      <PageHeaderDescription>
+        页面描述页面描述页面描述页面描述页面描述页面描述页面描述
+      </PageHeaderDescription>
+    </div>
+  </PageHeaderContent>
+</PageHeader>
+```
+
+### OnlyBreadcrumb
+
+仅面包屑：只有面包屑导航，无标题。
+
+```tsx
+<PageHeader>
+  <PageHeaderNav>
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">首页</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">实例列表</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>实例详情</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  </PageHeaderNav>
+</PageHeader>
+```
+
+### WithBreadcrumb
+
+面包屑 + 标题：面包屑导航 + 标题，常见于二级页面。
+
+```tsx
+<PageHeader>
+  <PageHeaderNav>
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">首页</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">实例列表</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>实例详情</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  </PageHeaderNav>
+  <PageHeaderContent>
+    <PageHeaderHeading>
+      <PageHeaderTitle>实例详情</PageHeaderTitle>
+    </PageHeaderHeading>
+  </PageHeaderContent>
+</PageHeader>
+```
+
+### Full
+
+完整版页头：面包屑 + 帮助链接 + 返回 + 主图标 + 标题（含 ⓘ） + 描述 + 多操作。
+
+```tsx
+<PageHeader>
+  <PageHeaderNav>
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">首页</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">实例列表</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>实例详情</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+    <div className="flex items-center gap-4">
+      <a
+        href="#"
+        className="inline-flex items-center gap-1 text-muted-foreground hover:text-foreground"
+      >
+        <BookOpen className="size-3.5" aria-hidden="true" />
+        帮助文档
+      </a>
+      <a href="#" className="text-muted-foreground hover:text-foreground">
+        切换实例
+      </a>
+    </div>
+  </PageHeaderNav>
+  <PageHeaderContent>
+    <div className="flex flex-col">
+      <PageHeaderHeading goBack onBack={() => alert('返回')}>
+        <span
+          aria-hidden="true"
+          className="flex size-8 shrink-0 items-center justify-center rounded-md bg-primary text-primary-foreground"
+        >
+          <Boxes className="size-5" />
+        </span>
+        <PageHeaderTitle tooltip="该实例为生产环境，建议谨慎操作。">
+          页面标题
+        </PageHeaderTitle>
+        <Tag variant="solid" color="success" size="lg">
+          标签一
+        </Tag>
+        <Tag variant="solid" color="primary" size="lg">
+          标签二
+        </Tag>
+        <Tag variant="solid" color="destructive" size="lg">
+          标签三
+        </Tag>
+      </PageHeaderHeading>
+      <PageHeaderDescription>
+        页面描述页面描述页面描述页面描述页面描述页面描述页面描述
+      </PageHeaderDescription>
+    </div>
+    <PageHeaderActions>
+      <Button variant="outline">普通按钮</Button>
+      <Button>主要按钮</Button>
+    </PageHeaderActions>
+  </PageHeaderContent>
+</PageHeader>
+```
+
 ### WithStatistic
 
 带数据概览：右侧使用 Statistic 组件展示 KPI 指标。

package/src/components/page-shell/index.tsx

@@ -93,7 +93,7 @@ function PageShell({
       // 受限容器（如 storybook `LayoutSandbox`）通过外级注入 `min-height: 0; height: 100%` 重置。
       // 说明：传入的 sidebar 如果是默认 collapsible="offcanvas"，其内部使用 `position: fixed`、
       // 高度 100svh，适用于全屏页面；在受限容器中需使用 `collapsible="none"` 退出 fixed 布局。
-      className={cn('!flex-col', className)}
+      className={cn('!h-svh !flex-col', className)}
       style={
         {
           '--sidebar-width': sidebarWidth,
@@ -103,11 +103,11 @@ function PageShell({
       {...props}
     >
       {header}
-      <div className="flex w-full flex-1 min-h-0">
+      <div className="flex min-h-0 w-full flex-1">
         {sidebar}
         <SidebarInset
           data-slot="page-shell-content"
-          className={cn('!min-h-0 overflow-y-auto', bgClass)}
+          className={cn('!min-h-0 overflow-hidden', bgClass)}
         >
           {children}
         </SidebarInset>

package/src/components/pagination/index.tsx

@@ -487,7 +487,7 @@ function Pagination({
         {/* 页码指示器 */}
         <span
           className={cn(
-            'ml-2 tabular-nums text-muted-foreground',
+            'ml-2 text-muted-foreground tabular-nums',
             sizeClass[size],
           )}
         >