@xihan-ui/styles 1.0.0 → 2.0.0

package/css/page-header.css

@@ -1,3 +1,10 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 page header 样式。 */
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='page-header'] {
@@ -9,14 +16,19 @@
     --xh-_page-header-py: var(--xh-space-4);
     --xh-_page-header-row-gap: var(--xh-space-2);
     --xh-_page-header-title-size: var(--xh-text-heading-3-size);
+    /* 形态档只换这两个：不画面的那一档左右不留内衬、也不切圆角 */
+    --xh-_page-header-px: 0;
+    --xh-_page-header-radius: 0;
 
-    /* 一行排不下就折行；返回位、标题、副标题排在同一行，操作贴到行尾，页脚整行另起 */
-    display: flex;
-    flex-wrap: wrap;
+    /* 返回、媒体、标题区与操作区分列；标题与说明上下排列。 */
+    display: grid;
+    grid-auto-flow: dense;
+    grid-template-columns: auto auto minmax(0, 1fr) auto;
     align-items: center;
-    column-gap: var(--xh-page-header-column-gap, var(--xh-space-3));
     row-gap: var(--xh-page-header-row-gap, var(--xh-_page-header-row-gap));
     padding-block: var(--xh-page-header-py, var(--xh-_page-header-py));
+    padding-inline: var(--xh-page-header-px, var(--xh-_page-header-px));
+    border-radius: var(--xh-page-header-radius, var(--xh-_page-header-radius));
     color: var(--xh-page-header-fg, var(--xh-fg-default));
   }
 
@@ -39,58 +51,131 @@
   }
 
   /* —— 分隔线 —— */
-  [data-scope='page-header'][data-part='root'][data-bordered] {
+  /* 只有贴底的 ghost 画这条下边线：一块切了圆角的面底下横一条直线，两头会露在圆角外面，
+     有面的两档由自己的边界接手同一件事——把页头与下面的内容分开 */
+  [data-scope='page-header'][data-part='root'][data-variant='ghost'][data-split] {
     border-block-end: var(--xh-stroke-thin) solid var(--xh-page-header-border, var(--xh-border-subtle));
   }
 
+  /* —— 形态 —— */
+  /* ghost 不在这儿：它就是上面那套基础取值，贴在页面底色上不画面。
+     画了面的两档左右补上与上下同档的内衬，否则内容会贴着那块面的边 */
+  [data-scope='page-header'][data-part='root']:is([data-variant='outline'], [data-variant='subtle']) {
+    --xh-_page-header-px: var(--xh-_page-header-py);
+    --xh-_page-header-radius: var(--xh-shape-surface);
+  }
+
+  /* outline 是一张静态内容面：--xh-border-default 描边撑住这块面的边界 + surface 底，不叠投影（§5.3）；
+     --xh-border-subtle 只作 ghost 贴底那条分隔线用，不当根面外边 */
+  [data-scope='page-header'][data-part='root'][data-variant='outline'] {
+    border: var(--xh-stroke-thin) solid var(--xh-page-header-border, var(--xh-border-default));
+    background: var(--xh-page-header-bg, var(--xh-bg-surface));
+  }
+
+  /* subtle 用淡底当边界：描边让位给底色但留住 1px 边位（与 outline 同一几何）、无影 */
+  [data-scope='page-header'][data-part='root'][data-variant='subtle'] {
+    border: var(--xh-stroke-thin) solid transparent;
+    background: var(--xh-page-header-bg, var(--xh-bg-subtle));
+  }
+
   /* —— 各段 —— */
+  /* 面包屑占满一整行排在标题之上：它写在标记的最前面，整行铺开就把标题挤到了下一行 */
+  [data-scope='page-header'][data-part='breadcrumb'] {
+    grid-column: 1 / -1;
+    color: var(--xh-page-header-breadcrumb-fg, var(--xh-fg-muted));
+    font-size: var(--xh-page-header-breadcrumb-font-size, var(--xh-text-secondary-size));
+    line-height: var(--xh-leading-normal);
+  }
+
+  /* 头像 / 图标位：不参与伸缩，图形本身多大由作者定 */
+  [data-scope='page-header'][data-part='media'] {
+    grid-column: 2;
+    margin-inline-end: var(--xh-page-header-column-gap, var(--xh-space-3));
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+
   /* 返回位只摆位置与对齐，外观归作者自己的按钮 */
   [data-scope='page-header'][data-part='back-trigger'] {
+    grid-column: 1;
+    margin-inline-end: var(--xh-page-header-column-gap, var(--xh-space-3));
     display: inline-flex;
-    flex: none;
     align-items: center;
     justify-content: center;
   }
 
   [data-scope='page-header'][data-part='title'] {
+    grid-column: 3;
     margin: 0;
-    flex: none;
+    /* 标题不参与伸缩，长过整行时收到行宽为止，中间没有断点的长串在行尾断开，
+       不把整条页头撑出容器 */
+    max-inline-size: 100%;
+    overflow-wrap: anywhere;
     color: var(--xh-page-header-title-fg, var(--xh-fg-default));
     font-size: var(--xh-page-header-title-font-size, var(--xh-_page-header-title-size));
-    font-weight: var(--xh-page-header-title-font-weight, var(--xh-font-weight-semibold));
+    /* 页面级标题：字重走标题档令牌，不直接下探字重原语 */
+    font-weight: var(--xh-page-header-title-font-weight, var(--xh-text-heading-3-weight));
     line-height: var(--xh-leading-tight);
   }
 
   /* 副标题吃掉标题与操作之间的剩余宽度，长文本在这里收窄换行 */
-  [data-scope='page-header'][data-part='subtitle'] {
+  [data-scope='page-header'][data-part='description'] {
+    grid-column: 3;
     margin: 0;
-    flex: 1 1 auto;
     min-inline-size: 0;
-    color: var(--xh-page-header-subtitle-fg, var(--xh-fg-muted));
-    font-size: var(--xh-page-header-subtitle-font-size, var(--xh-text-secondary-size));
+    color: var(--xh-page-header-description-fg, var(--xh-fg-muted));
+    font-size: var(--xh-page-header-description-font-size, var(--xh-text-secondary-size));
     line-height: var(--xh-leading-normal);
   }
 
   /* 操作区贴到行尾，没有副标题占位时也一样靠边 */
   [data-scope='page-header'][data-part='extra'] {
+    grid-column: 4;
     display: flex;
     flex-wrap: wrap;
     align-items: center;
     gap: var(--xh-page-header-extra-gap, var(--xh-space-2));
-    margin-inline-start: auto;
+    margin-inline-start: var(--xh-page-header-column-gap, var(--xh-space-3));
+    justify-self: end;
   }
 
   /* 页脚占满一整行，前面有内容时自然被挤到下一行 */
   [data-scope='page-header'][data-part='footer'] {
-    flex: 1 0 100%;
+    grid-column: 1 / -1;
     color: var(--xh-page-header-footer-fg, var(--xh-fg-muted));
     font-size: var(--xh-page-header-footer-font-size, var(--xh-text-secondary-size));
     line-height: var(--xh-leading-normal);
   }
 
+  [data-scope='page-header'][data-part='root']:has(> [data-part='description'])
+    > :is([data-part='back-trigger'], [data-part='media'], [data-part='extra']) {
+    grid-row: span 2;
+  }
+
+  @media (max-width: 640px) {
+    [data-scope='page-header'][data-part='root'] {
+      grid-template-columns: auto minmax(0, 1fr);
+    }
+
+    [data-scope='page-header'][data-part='media'],
+    [data-scope='page-header'][data-part='title'],
+    [data-scope='page-header'][data-part='description'] {
+      grid-column: 2;
+    }
+
+    [data-scope='page-header'][data-part='root'] > [data-part='extra'] {
+      grid-column: 1 / -1;
+      grid-row: auto;
+      margin-inline-start: 0;
+      justify-self: start;
+    }
+  }
+
   /* 声明过任何 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去。
      写在文件末尾：兜底必须排在该部件所有 display 声明之后 */
   [data-scope='page-header'][data-part='back-trigger'][hidden],
+  [data-scope='page-header'][data-part='media'][hidden],
   [data-scope='page-header'][data-part='extra'][hidden] {
     display: none;
   }

package/css/pagination.css

@@ -1,29 +1,13 @@
-@layer xihan.motion {
-  /* 动画名的查找只认「文档里有没有这个名字」：引用别处文件里的名字，那份文件不一定在场，
-     动画会静默地整个不跑。每份皮肤都能单独引入，所以它用到的关键帧都写在自己身上。 */
-  @keyframes xh-pop-in {
-    from {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
 
-    to {
-      opacity: 1;
-      scale: 1;
-    }
-  }
-  @keyframes xh-pop-out {
-    from {
-      opacity: 1;
-      scale: 1;
-    }
+/* 定义 pagination 样式。 */
 
-    to {
-      opacity: 0;
-      scale: var(--xh-motion-scale-enter);
-    }
-  }
-}
+/* 共享关键帧由 family/motion.css 提供，本皮肤 @import 它，单独引入仍成立；四类格子接 Action Control 配方，同理 */
+@import '../family/motion.css';
+@import '../family/action-control.css';
 
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
@@ -31,14 +15,13 @@
     --xh-pagination-skin: 1;
   }
 
-  /* 根节点是 nav 地标，只负责把上一页 / 页码 / 下一页排成一行。
-     页数为 0 时连接层会打 data-empty，这里不拿它做隐藏：作者常把「第 x-y 条」这类
-     区间回显也写在 nav 里，整块藏掉会连那行字一起吞了，是否隐藏交给作者决定 */
-  [data-scope='pagination'][data-part='root'] {
-    /* 作者塞进上一页/下一页的图标跟着字号走，与皮肤画的兜底字形同一把尺 */
-    --xh-icon-size: var(--xh-pagination-icon-size, var(--xh-glyph-size-text));
+  /* 私有槽同时声明在根与 positioner 上：摊开的页码面板被搬到 portal 落点，
+     不是根的后代，继承不过去。面板里的页码格子与主区那排消费的是同一批槽 */
+  [data-scope='pagination']:is([data-part='root'], [data-part='positioner']) {
+    /* 作者塞进面板或分页行里的图标按档取字形尺（§6.5）；四类格子上另按家族档位取同一把尺 */
+    --xh-icon-size: var(--xh-pagination-icon-size, var(--xh-glyph-size-md));
 
-    /* 尺寸档只换这三个私有槽，上一页/下一页、页码与省略号都从 root 继承它们，
+    /* 尺寸档只换这三个私有槽，上一页/下一页、页码与省略号都从这两处继承它们，
        换档不必给每个部件各写一条选择器 */
     --xh-_pagination-item-size: var(--xh-control-h-md);
     --xh-_pagination-item-px: var(--xh-control-px-md);
@@ -50,7 +33,14 @@
     --xh-_pagination-selected-bg-hover: var(--xh-_tone-hover, var(--xh-bg-brand-hover));
     --xh-_pagination-selected-bg-active: var(--xh-_tone-active, var(--xh-bg-brand-active));
     --xh-_pagination-selected-fg: var(--xh-_tone-on, var(--xh-fg-on-brand));
+    /* 当前页那一格是实心底，顶边画一条极浅的内高光把它衬出厚度（solid 面允许顶高光，经家族的 highlight 槽画） */
+    --xh-_pagination-highlight: var(--xh-_highlight-tone);
+  }
 
+  /* 根节点是 nav 地标，只负责把上一页 / 页码 / 下一页排成一行。
+     页数为 0 时连接层会打 data-empty，这里不拿它做隐藏：作者常把「第 x-y 条」这类
+     区间回显也写在 nav 里，整块藏掉会连那行字一起吞了，是否隐藏交给作者决定 */
+  [data-scope='pagination'][data-part='root'] {
     display: flex;
     align-items: center;
     /* 页码多到一行放不下就换行，宁可折行也不要把按钮压扁或撑出横向滚动 */
@@ -61,13 +51,15 @@
   /* —— 尺寸 —— */
   /* 缺省档写在上面的基础规则里。格子高度、内边距、字号三者各走控件尺的同一档；
      页码格子靠最小宽度撑等宽，内边距只在页码超出最小宽度时才起作用 */
-  [data-scope='pagination'][data-part='root'][data-size='sm'] {
+  [data-scope='pagination']:is([data-part='root'], [data-part='positioner'])[data-size='sm'] {
+    --xh-icon-size: var(--xh-pagination-icon-size, var(--xh-glyph-size-sm));
     --xh-_pagination-item-size: var(--xh-control-h-sm);
     --xh-_pagination-item-px: var(--xh-control-px-sm);
     --xh-_pagination-font-size: var(--xh-control-font-sm);
   }
 
-  [data-scope='pagination'][data-part='root'][data-size='lg'] {
+  [data-scope='pagination']:is([data-part='root'], [data-part='positioner'])[data-size='lg'] {
+    --xh-icon-size: var(--xh-pagination-icon-size, var(--xh-glyph-size-lg));
     --xh-_pagination-item-size: var(--xh-control-h-lg);
     --xh-_pagination-item-px: var(--xh-control-px-lg);
     --xh-_pagination-font-size: var(--xh-control-font-lg);
@@ -77,142 +69,137 @@
     display: none;
   }
 
-  /* 三类格子共用同一副骨架，行高与间距一致，切页时基线不会跳 */
+  /* 四类格子接 Action Control 的 text 档，缺省中性的 ghost 形态（§7.2 只有 Button 品牌实心）：盒型、三档几何、
+     透明描边（省略号也占一条，两者内容盒等高，一行里对得齐）、悬停 100 → 按下 200（画布承载）、禁用面、按压缩放与
+     过渡都由家族给；这里只把使用者槽映射到桥接槽并保留分页自己的排版。
+     等宽的关键：1 与 10 的内容宽度不同，靠最小宽度把它们撑到同一格，行宽才不会随当前页左右抖动 */
   [data-scope='pagination'][data-part='prev-trigger'],
   [data-scope='pagination'][data-part='next-trigger'],
   [data-scope='pagination'][data-part='item'],
-  [data-scope='pagination'][data-part='ellipsis'] {
-    display: inline-flex;
+  [data-scope='pagination'][data-part='ellipsis-trigger'] {
+    --xh-action-min-inline-size: var(--xh-pagination-item-min-size, var(--xh-_pagination-item-size));
+    --xh-action-visual-size: var(--xh-pagination-item-h, var(--xh-_pagination-item-size));
+    --xh-action-padding-inline: var(--xh-pagination-item-px, var(--xh-_pagination-item-px));
+    --xh-action-radius: var(--xh-pagination-item-radius, var(--xh-shape-control));
+    --xh-action-font-size: var(--xh-pagination-font-size, var(--xh-_pagination-font-size));
+    --xh-action-bg-rest: var(--xh-pagination-item-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-pagination-item-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-pagination-item-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-fg-rest: var(--xh-pagination-item-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-pagination-item-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-pagination-item-fg, var(--xh-_action-variant-fg-pressed));
+    /* 作者塞进上一页/下一页的图标按档取字形尺（§6.5），与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-pagination-icon-size, var(--xh-_action-profile-glyph-size));
+
     flex: none;
-    align-items: center;
-    justify-content: center;
-    /* 等宽的关键：1 与 10 的内容宽度不同，靠最小宽度把它们撑到同一格，
-       行宽才不会随当前页左右抖动。三位数超过最小宽度时才自然变宽 */
-    min-inline-size: var(--xh-pagination-item-min-size, var(--xh-_pagination-item-size));
-    block-size: var(--xh-pagination-item-h, var(--xh-_pagination-item-size));
-    padding-inline: var(--xh-pagination-item-px, var(--xh-_pagination-item-px));
-    /* 省略号也占一条透明描边：只给按钮描边的话两者内容盒不等高，一行里就对不齐 */
-    border: var(--xh-stroke-thin) solid transparent;
-    border-radius: var(--xh-pagination-item-radius, var(--xh-shape-control));
-    font-size: var(--xh-pagination-font-size, var(--xh-_pagination-font-size));
-    line-height: var(--xh-leading-none);
+    font-weight: var(--xh-pagination-item-font-weight, var(--xh-text-label-weight));
     /* 等宽数字：1 与 7 的字形宽度在比例字体里并不相同，不定住会让同位数页码抖一格 */
     font-variant-numeric: tabular-nums;
-    white-space: nowrap;
-    user-select: none;
   }
 
   [data-scope='pagination'][data-part='prev-trigger'][hidden],
   [data-scope='pagination'][data-part='next-trigger'][hidden],
   [data-scope='pagination'][data-part='item'][hidden],
-  [data-scope='pagination'][data-part='ellipsis'][hidden] {
+  [data-scope='pagination'][data-part='ellipsis-trigger'][hidden] {
     display: none;
   }
 
-  /* 三个按钮共用的可点观感：默认透明底，只有交互与当前页才上色 */
-  [data-scope='pagination'][data-part='prev-trigger'],
-  [data-scope='pagination'][data-part='next-trigger'],
-  [data-scope='pagination'][data-part='item'] {
-    background: var(--xh-pagination-item-bg, transparent);
-    color: var(--xh-pagination-item-fg, var(--xh-fg-default));
-    font-weight: var(--xh-pagination-item-font-weight, var(--xh-text-label-weight));
-    cursor: pointer;
-    transition:
-      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
-      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
-      border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
-  }
-
-  /* 悬停这条选择器比当前页那条多一节（:hover），同层里权重更高、会反过来压住它，
-     所以悬停一路显式把当前页排除：指针停在当前页上不该把品牌底色洗成灰底。
-     页码条目从不禁用（连接层只给上一页/下一页发原生 disabled），故这边不必再排除 :disabled */
-  [data-scope='pagination'][data-part='prev-trigger']:hover:not(:disabled),
-  [data-scope='pagination'][data-part='next-trigger']:hover:not(:disabled),
-  [data-scope='pagination'][data-part='item']:not([data-current]):hover {
-    background: var(--xh-pagination-item-bg-hover, var(--xh-bg-subtle-hover));
-  }
+  /* 首末页的上一页 / 下一页是原生 disabled（不可聚焦、进不了 Tab 序列），连接层同时给 data-disabled，
+     家族按 data-disabled 画禁用面（透明底 + --xh-fg-disabled）；分页条目从不禁用 */
 
-  [data-scope='pagination'][data-part='prev-trigger']:active:not(:disabled),
-  [data-scope='pagination'][data-part='next-trigger']:active:not(:disabled),
-  [data-scope='pagination'][data-part='item']:not([data-current]):active {
-    background: var(--xh-pagination-item-bg-active, var(--xh-bg-subtle-active));
+  /* 当前页（§7.3 格状当前）：data-current 与 aria-current='page' 由连接层成对给出，样式挂在 data 钩子上，
+     无障碍语义留给 aria。实心品牌面 + 配对前景、不加粗——字重一变字形就变宽，页码格子会跟着长一点，
+     正是这里要避免的抖动；悬停 / 按下沿 brand → brand-hover → brand-active 走，三态都经桥接槽交给家族画，
+     solid 面允许一条顶高光，环色改取面自己的前景 */
+  [data-scope='pagination'][data-part='item'][data-current] {
+    --xh-action-bg-rest: var(--xh-pagination-item-bg-selected, var(--xh-_pagination-selected-bg));
+    --xh-action-bg-hover: var(--xh-pagination-item-bg-selected-hover, var(--xh-_pagination-selected-bg-hover));
+    --xh-action-bg-pressed: var(--xh-pagination-item-bg-selected-active, var(--xh-_pagination-selected-bg-active));
+    --xh-action-bg-focus-visible: var(--xh-pagination-item-bg-selected, var(--xh-_pagination-selected-bg));
+    --xh-action-fg-rest: var(--xh-pagination-item-fg-selected, var(--xh-_pagination-selected-fg));
+    --xh-action-fg-hover: var(--xh-pagination-item-fg-selected, var(--xh-_pagination-selected-fg));
+    --xh-action-fg-pressed: var(--xh-pagination-item-fg-selected, var(--xh-_pagination-selected-fg));
+    --xh-action-fg-focus-visible: var(--xh-pagination-item-fg-selected, var(--xh-_pagination-selected-fg));
+    --xh-action-border-rest: var(--xh-pagination-item-border-selected, var(--xh-_pagination-selected-bg));
+    --xh-action-border-hover: var(--xh-pagination-item-border-selected-hover, var(--xh-_pagination-selected-bg-hover));
+    --xh-action-border-pressed: var(--xh-pagination-item-border-selected-active, var(--xh-_pagination-selected-bg-active));
+    --xh-action-border-focus-visible: var(--xh-pagination-item-border-selected, var(--xh-_pagination-selected-bg));
+    --xh-action-highlight-rest: var(--xh-_pagination-highlight);
+    --xh-action-highlight-hover: var(--xh-_pagination-highlight);
+    --xh-action-highlight-pressed: var(--xh-_pagination-highlight);
+    --xh-action-highlight-focus-visible: var(--xh-_pagination-highlight);
+    --xh-action-shadow-rest: var(--xh-pagination-item-shadow, none);
+    --xh-action-shadow-hover: var(--xh-pagination-item-shadow, none);
+    --xh-action-shadow-pressed: var(--xh-pagination-item-shadow, none);
+    --xh-action-shadow-focus-visible: var(--xh-pagination-item-shadow, none);
+    --xh-action-ring-color-focus-visible: currentColor;
   }
 
-  [data-scope='pagination'][data-part='prev-trigger']:focus-visible,
-  [data-scope='pagination'][data-part='next-trigger']:focus-visible,
-  [data-scope='pagination'][data-part='item']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
+  /* 省略位是可展开的按钮：折进去的那几页只有它一个入口，指针与键盘都得点得到，
+     所以它与页码同一副骨架、同一条阶梯。这里只把字色压淡一档与页码区分开，三态都压——
+     家族的悬停 / 按下规则比基础块特定，只映射静息那一支会在悬停时被换回缺省字色 */
+  [data-scope='pagination'][data-part='ellipsis-trigger'] {
+    --xh-action-fg-rest: var(--xh-pagination-ellipsis-trigger-fg, var(--xh-fg-subtle));
+    --xh-action-fg-hover: var(--xh-pagination-ellipsis-trigger-fg, var(--xh-fg-subtle));
+    --xh-action-fg-pressed: var(--xh-pagination-ellipsis-trigger-fg, var(--xh-fg-subtle));
   }
-
-  /* 首末页的上一页 / 下一页是原生 disabled（不可聚焦、进不了 Tab 序列），
-     所以这里必须用 :disabled；连接层同时给的 data-disabled 只是留给作者的钩子。
-     分页条目从不禁用，那边也就没有对应规则 */
-  [data-scope='pagination'][data-part='prev-trigger']:disabled,
-  [data-scope='pagination'][data-part='next-trigger']:disabled {
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
+  /* 每页条数控制器的挂载点：里头装的是库里的 select，控件本身的描边、底色、聚焦环与
+     浮层都归 select 那份皮肤，这一格只把它摆进分页行 */
+  [data-scope='pagination'][data-part='page-size-select'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
   }
 
-  /* 当前页：data-current 与 aria-current='page' 由连接层成对给出，
-     样式挂在 data 钩子上，无障碍语义留给 aria，两边各司其职。
-     只换底色不加粗——字重一变字形就变宽，页码格子会跟着长一点，正是这里要避免的抖动 */
-  [data-scope='pagination'][data-part='item'][data-current] {
-    border-color: var(--xh-pagination-item-border-selected, var(--xh-_pagination-selected-bg));
-    background: var(--xh-pagination-item-bg-selected, var(--xh-_pagination-selected-bg));
-    color: var(--xh-pagination-item-fg-selected, var(--xh-_pagination-selected-fg));
+  [data-scope='pagination'][data-part='page-size-select'][hidden] {
+    display: none;
   }
 
-  [data-scope='pagination'][data-part='item'][data-current]:hover {
-    border-color: var(--xh-pagination-item-border-selected-hover, var(--xh-_pagination-selected-bg-hover));
-    background: var(--xh-pagination-item-bg-selected-hover, var(--xh-_pagination-selected-bg-hover));
+  /* 信息区：一段次要文字，与页码格子同一条基线 */
+  [data-scope='pagination'][data-part='summary'] {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    block-size: var(--xh-pagination-item-h, var(--xh-_pagination-item-size));
+    color: var(--xh-pagination-summary-fg, var(--xh-fg-muted));
+    font-size: var(--xh-pagination-font-size, var(--xh-_pagination-font-size));
+    line-height: var(--xh-leading-none);
+    white-space: nowrap;
   }
 
-  [data-scope='pagination'][data-part='item'][data-current]:active {
-    border-color: var(--xh-pagination-item-border-selected-active, var(--xh-_pagination-selected-bg-active));
-    background: var(--xh-pagination-item-bg-selected-active, var(--xh-_pagination-selected-bg-active));
+  [data-scope='pagination'][data-part='summary'][hidden] {
+    display: none;
   }
 
-  /* 省略号是纯视觉占位，读屏那边已被 aria-hidden 摘掉：
-     吞掉指针事件，免得它出现悬停反馈、看起来像一颗点得动的按钮 */
-  [data-scope='pagination'][data-part='ellipsis'] {
-    color: var(--xh-pagination-ellipsis-fg, var(--xh-fg-subtle));
-    cursor: default;
-    pointer-events: none;
-  }
-  /* 每页条数控制器：原生 select，抹掉系统外观后与页码格子共用同一副骨架。
-     箭头用背景图而非伪元素——原生 select 不生成 ::before */
-  [data-scope='pagination'][data-part='page-size-select'] {
+  /* 跳页输入框：与每页条数控制器同一副外观，宽度按页码位数留够 */
+  [data-scope='pagination'][data-part='jumper'] {
     flex: none;
+    inline-size: var(--xh-pagination-jumper-w, calc(var(--xh-space-8) * 2));
     block-size: var(--xh-pagination-item-h, var(--xh-_pagination-item-size));
     padding-inline: var(--xh-pagination-item-px, var(--xh-_pagination-item-px));
-    /* 右侧让开箭头 */
-    padding-inline-end: calc(
-      var(--xh-pagination-item-px, var(--xh-_pagination-item-px)) +
-        var(--xh-icon-size, var(--xh-glyph-size-text)) + var(--xh-space-1)
-    );
-    border: var(--xh-stroke-thin) solid var(--xh-pagination-page-size-border, var(--xh-border-default));
+    border: var(--xh-stroke-thin) solid var(--xh-pagination-jumper-border, var(--xh-border-default));
     border-radius: var(--xh-pagination-item-radius, var(--xh-shape-control));
-    background: var(--xh-pagination-page-size-bg, var(--xh-bg-surface));
+    background: var(--xh-pagination-jumper-bg, var(--xh-bg-surface));
     color: var(--xh-pagination-item-fg, var(--xh-fg-default));
     font-size: var(--xh-pagination-font-size, var(--xh-_pagination-font-size));
     line-height: var(--xh-leading-none);
     appearance: none;
-    cursor: pointer;
+    transition:
+      background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      border-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
-  [data-scope='pagination'][data-part='page-size-select']:hover:not(:disabled) {
-    border-color: var(--xh-pagination-page-size-border-hover, var(--xh-border-strong));
+  [data-scope='pagination'][data-part='jumper'][hidden] {
+    display: none;
   }
 
-  [data-scope='pagination'][data-part='page-size-select']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
+  [data-scope='pagination'][data-part='jumper']:hover:not(:disabled) {
+    border-color: var(--xh-pagination-jumper-border-hover, var(--xh-border-strong));
+    background: var(--xh-pagination-jumper-bg-hover, var(--xh-bg-subtle-hover));
   }
 
-  [data-scope='pagination'][data-part='page-size-select']:disabled {
+  [data-scope='pagination'][data-part='jumper']:disabled {
     color: var(--xh-fg-disabled);
-    cursor: not-allowed;
   }
 
   /* 摊开省略位的定位层。三处坐标系必须同为 fixed：机器交给引擎的 strategy、
@@ -221,12 +208,15 @@
     /* 落定那一侧的可用高度，由定位引擎经内联自定义属性写进来，面板继承它限高；
        引擎没算（尚未落位 / 无引擎 / 贴边归零）时不额外限高 */
     --xh-_pagination-available-h: 100vh;
+    /* 落定那一侧的可用宽度，同样由定位引擎经内联自定义属性写进来，行内轴据此夹取；
+       引擎没算（尚未落位 / 无引擎 / 贴边归零）时退到视口宽 */
+    --xh-_pagination-available-w: 100vw;
 
     /* 页码面板的自绘条浮在内容之上：轨道不上底色，实色轨道会在面板右缘糊一条竖灰带 */
     --xh-scrollbar-track-bg: transparent;
 
     position: fixed;
-    z-index: var(--xh-pagination-layer, var(--xh-layer-popover));
+    z-index: var(--xh-pagination-layer, var(--xh-_layer, var(--xh-layer-popover)));
     /* 空壳不吃指针：省略位与面板之间那段间隙要能点得穿 */
     pointer-events: none;
   }
@@ -238,30 +228,32 @@
 
   /* 摊开的页码面板：一串页码格子，横着排、必要时折行 */
   [data-scope='pagination'][data-part='content'] {
-    /* 浮层被搬到 portal 落点，继承不到 root 上那把尺，这里再声明一遍 */
-    --xh-icon-size: var(--xh-pagination-icon-size, var(--xh-glyph-size-text));
-
     display: flex;
     flex-flow: row wrap;
     gap: var(--xh-pagination-gap, var(--xh-space-1));
     /* 页码不可预知有多少：不限高就整块伸出视口且滚不到 */
-    max-inline-size: var(--xh-pagination-content-max-w, var(--xh-overlay-max-w));
+    /* 静态档与落位后的可用宽度取小：窄视口下面板伸出去，最右侧的内容就点不到了 */
+    max-inline-size: min(var(--xh-pagination-content-max-w, var(--xh-overlay-max-w)), var(--xh-_pagination-available-w));
     max-block-size: min(
       var(--xh-pagination-content-max-h, var(--xh-overlay-max-h)),
       var(--xh-_pagination-available-h)
     );
     overflow-y: auto;
+    /* 浮层滚动面：滚到底不把滚动量交给页面（§6.6 只给 Overlay 家族滚动面） */
+    overscroll-behavior: contain;
     padding: var(--xh-pagination-content-p, var(--xh-space-1));
     border: var(--xh-stroke-thin) solid var(--xh-pagination-content-border, var(--xh-border-default));
-    border-radius: var(--xh-pagination-content-radius, var(--xh-shape-surface));
+    border-radius: var(--xh-pagination-content-radius, var(--xh-shape-overlay));
     background: var(--xh-pagination-content-bg, var(--xh-bg-surface));
     box-shadow: var(--xh-pagination-content-shadow, var(--xh-elevation-floating));
     /* 定位层不吃指针，面板本体必须吃：里面的页码要点得到 */
     pointer-events: auto;
   }
 
+  /* 在场那一档才提前备好合成层：属性随 data-state 一起消失，收起后不长期占着 */
   [data-scope='pagination'][data-part='content'][data-state='open'] {
-    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    will-change: opacity, scale;
+    animation: xh-pop-in var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
   }
 
   /* 退场：收起那一帧 hidden 由退场闸门押后，这里才播得出来。forwards 把末态钉住，
@@ -297,6 +289,18 @@
     mask: var(--xh-glyph-mark-chevron-right) center / contain no-repeat;
   }
 
+  /* 省略位不写内容时画三点：折进去那几页的入口，空着就是一格看不出能点的空白 */
+  [data-scope='pagination'][data-part='ellipsis-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-text));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-ellipsis) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-ellipsis) center / contain no-repeat;
+  }
+
   /* rtl 下页序从右往左走，箭头跟着指向行进方向 */
   [dir='rtl'] [data-scope='pagination'][data-part='prev-trigger']:empty::before {
     -webkit-mask-image: var(--xh-glyph-mark-chevron-right);
@@ -307,4 +311,40 @@
     -webkit-mask-image: var(--xh-glyph-mark-chevron-left);
     mask-image: var(--xh-glyph-mark-chevron-left);
   }
+
+  /* 手指落点：命中区由绝对定位的伪元素向块轴两侧外扩，格子的盒一点不动——
+     加高格子会把整条 nav 撑高，行宽也会跟着当前页抖。
+     只扩块轴：格与格在行内轴上只隔一格间距，往两侧扩会与相邻格的命中区叠上。
+     取 8px 是按最矮的 sm 档算的（28 + 8 × 2 = 44），md 与 lg 档更宽裕。
+     用 ::after：::before 已经被两枚箭头的兜底字形占着 */
+  @media (pointer: coarse) {
+    [data-scope='pagination'][data-part='prev-trigger'],
+    [data-scope='pagination'][data-part='next-trigger'],
+    [data-scope='pagination'][data-part='item'] {
+      position: relative;
+    }
+
+    [data-scope='pagination'][data-part='prev-trigger']::after,
+    [data-scope='pagination'][data-part='next-trigger']::after,
+    [data-scope='pagination'][data-part='item']::after {
+      content: '';
+      position: absolute;
+      inset-block: -8px;
+      inset-inline: 0;
+    }
+  }
+
+  @media print {
+    /* 打印：定位层与遮罩是交互期才存在的东西，落到纸上只会盖住底下的正文。
+       收起写在这份皮肤里而不是 reset：reset 层排在组件层之前，组件层里任何一条 display 都压得住它。 */
+    [data-scope='pagination'][data-part='positioner'] {
+      display: none;
+    }
+
+    /* 打印默认丢背景：当前页那格的实心底印不出来，一排页码看上去完全一样。
+       改用字重表达同一件事——常态之所以不加粗是怕格子变宽、行宽跟着抖，纸上没有这回事 */
+    [data-scope='pagination'][data-part='item'][data-current] {
+      font-weight: var(--xh-font-weight-semibold);
+    }
+  }
 }