@manohub/app-kit 0.1.0

package/dist/components/components.css

@@ -0,0 +1,597 @@
+/**
+ * 页面组件样式（AppTable / AppPagination）。
+ */
+
+/* AppTable：撑满 Body(mode="table")，内部滚动（FDataGrid fit 模式） */
+.ak-table {
+  height: 100%;
+  overflow: hidden;
+}
+
+/* ===== AppBadge（徽标 / 标签）=====
+   批次 5 前 4 个应用各自手搓徽标，这里按设计稿收敛为 tone × shape × size × dot 的正交组合。
+   每个 tone 先铺一组局部变量（前景 / 底色 / 描边 / 圆点），形态类只决定「用哪几个变量」。 */
+.ak-badge {
+  --ak-badge-fg: var(--ui-base-content);
+  --ak-badge-bg: transparent;
+  --ak-badge-border: transparent;
+  --ak-badge-dot: var(--ui-base-content-subtle);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  box-sizing: border-box;
+  border: 1px solid transparent;
+  font-size: var(--ui-font-caption);
+  line-height: 1;
+  white-space: nowrap;
+  color: var(--ak-badge-fg);
+  background: var(--ak-badge-bg);
+  border-color: var(--ak-badge-border);
+}
+
+.ak-badge--sm {
+  height: 20px;
+  padding: 0 6px;
+  min-width: 36px;
+  border-radius: var(--ui-radius-sm);
+}
+
+.ak-badge--md {
+  height: 24px;
+  padding: 0 8px;
+  border-radius: var(--ui-radius-md);
+}
+
+.ak-badge--default {
+  --ak-badge-fg: var(--ui-base-content);
+  --ak-badge-dot: var(--ui-base-content-subtle);
+}
+
+.ak-badge--primary {
+  --ak-badge-fg: var(--ui-primary);
+  --ak-badge-bg: var(--ui-primary-weak);
+  --ak-badge-border: var(--ui-primary);
+  --ak-badge-dot: var(--ui-primary);
+}
+
+.ak-badge--info {
+  --ak-badge-fg: var(--ui-info);
+  --ak-badge-bg: var(--ui-info-weak);
+  --ak-badge-border: var(--ui-info);
+  --ak-badge-dot: var(--ui-info);
+}
+
+.ak-badge--success {
+  --ak-badge-fg: var(--ui-success);
+  --ak-badge-bg: var(--ui-success-weak);
+  --ak-badge-border: var(--ui-success);
+  --ak-badge-dot: var(--ui-success);
+}
+
+.ak-badge--warning {
+  --ak-badge-fg: var(--ui-warning);
+  --ak-badge-bg: var(--ui-warning-weak);
+  --ak-badge-border: var(--ui-warning);
+  --ak-badge-dot: var(--ui-warning);
+}
+
+.ak-badge--error {
+  --ak-badge-fg: var(--ui-error);
+  --ak-badge-bg: var(--ui-error-weak);
+  --ak-badge-border: var(--ui-error);
+  --ak-badge-dot: var(--ui-error);
+}
+
+/* 浅底标签：只取浅底 + 同色文字（无描边） */
+.ak-badge--soft {
+  background: var(--ak-badge-bg);
+  border-color: transparent;
+}
+
+.ak-badge--soft.ak-badge--default {
+  --ak-badge-bg: var(--ui-base-50);
+  --ak-badge-fg: var(--ui-base-content-muted);
+}
+
+.ak-badge--soft.ak-badge--primary {
+  --ak-badge-bg: var(--ui-primary-subtle);
+}
+
+/* 描边：浅底 + 同色描边；default 退化为白底 + 中性描边 + 正文色（状态胶囊） */
+.ak-badge--outline {
+  background: var(--ak-badge-bg);
+  border-color: var(--ak-badge-border);
+}
+
+.ak-badge--outline.ak-badge--default {
+  --ak-badge-bg: var(--ui-base-100);
+  --ak-badge-border: var(--ui-base-300);
+  --ak-badge-fg: var(--ui-base-content);
+}
+
+/* 无底无框：靠圆点表达状态；成功 / 中性用正文色，错误用危险色 */
+.ak-badge--plain {
+  background: transparent;
+  border-color: transparent;
+}
+
+.ak-badge--plain.ak-badge--default {
+  --ak-badge-fg: var(--ui-base-content-muted);
+}
+
+.ak-badge--plain.ak-badge--success {
+  --ak-badge-fg: var(--ui-base-content);
+}
+
+.ak-badge--plain.ak-badge--error {
+  --ak-badge-fg: var(--ui-error);
+}
+
+.ak-badge__dot {
+  width: 8px;
+  height: 8px;
+  flex: none;
+  border-radius: var(--ui-radius-full);
+}
+
+.ak-badge--dot-filled .ak-badge__dot {
+  background: var(--ak-badge-dot);
+}
+
+.ak-badge--dot-ring .ak-badge__dot {
+  box-sizing: border-box;
+  border: 2px solid var(--ak-badge-dot);
+  background: var(--ui-base-100);
+}
+
+/* AppTable 清单卡外框（framed）：1px 描边 + 8px 圆角。
+   原先是 skill-topic 在业务 CSS 里自绘的 `.topic-grid` 外框，此处上收为标准形态。 */
+.ak-table--framed {
+  border: 1px solid var(--ui-base-300);
+  border-radius: var(--ui-radius-md);
+}
+
+/* AppTable 自绘选择列（farris 内置选择列不启用，避免选中态双通道） */
+.ak-table-check {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+}
+
+.ak-table-check input {
+  width: 14px;
+  height: 14px;
+  margin: 0;
+  cursor: pointer;
+  accent-color: var(--ui-primary);
+}
+
+.ak-table-check.is-disabled,
+.ak-table-check.is-disabled input {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+.ak-pagination {
+  display: flex;
+  justify-content: flex-end;
+}
+
+/* AppFilter：条件区容器（farris 自带表单类由 FQuerySolution 输出，这里只补间距契约） */
+.ak-filter {
+  width: 100%;
+}
+
+/* AppTabs：撑满容器时的高度契约（farrs fill 模式另有补丁，见 farris-bridge.css） */
+.ak-tabs-fill {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+/* AppDialog：模态内容默认不撑满（fitContent 由 farris 控制） */
+.ak-dialog-body {
+  max-height: 60vh;
+  overflow: auto;
+}
+
+/* 弹窗按钮 loading spinner（AppModalButton.loading 内部映射到该类） */
+@keyframes ak-modal-spin {
+  to { transform: rotate(360deg); }
+}
+
+.ak-modal-btn-spinner {
+  display: inline-block;
+  width: 14px;
+  height: 14px;
+  border: 2px solid currentColor;
+  border-top-color: transparent;
+  border-radius: var(--ui-radius-full);
+  animation: ak-modal-spin 0.6s linear infinite;
+}
+
+/* AppDialog 页脚按钮的品牌化外观。
+   原先是 skill-topic 与 repository 各自 CSS 里逐字重复的 `.farris-modal-footer .btn-*` 覆盖块
+   （app 侧写 farris 选择器，违反 C1），此处上收为全仓唯一定义；两段式选择器压过 farris 单类规则。 */
+.app-container .farris-modal-footer .btn {
+  height: 34px;
+  padding: 0 20px;
+  border-radius: var(--ui-radius-md);
+  font-size: var(--ui-font-body);
+  line-height: 32px;
+}
+
+.app-container .farris-modal-footer .btn-primary {
+  background: var(--ui-primary);
+  border-color: var(--ui-primary);
+}
+
+.app-container .farris-modal-footer .btn-primary:hover {
+  background: var(--ui-primary-hover);
+  border-color: var(--ui-primary-hover);
+}
+
+.app-container .farris-modal-footer .btn-light {
+  background: var(--ui-base-100);
+  border: 1px solid var(--ui-base-400);
+  color: var(--ui-base-content);
+}
+
+.app-container .farris-modal-footer .btn-light:hover {
+  border-color: var(--ui-primary);
+  color: var(--ui-primary);
+}
+
+/* 表格容器宽度测量宿主：仅在消费方传 onContainerResize / resizePollInterval 时渲染
+   （不传时 AppTable 的 DOM 结构与以前完全一致）。 */
+.ak-table-host {
+  height: 100%;
+  min-height: 0;
+}
+
+/* ===== AppPanel（区域容器，无框）=====
+   无框契约：面板自身不写描边 / 圆角 / 阴影 / 独立底色 / 单侧边框，
+   分区感只由 Header 下方 1px 分隔线提供（与 .ak-shell-header 同一手法）；
+   两栏之间的竖直分隔线由 AppShell.Split 提供；卡片外观由内容件承载（表格用 AppTable.framed）。
+
+   滚动归属：Header 固定（flex-shrink:0），Body 承担**区域内**滚动（overflow:auto）。
+   Split 两栏因此让出滚动（overflow:hidden），避免同栏两层滚动容器。 */
+.ak-panel {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.ak-panel__header {
+  flex-shrink: 0;
+  height: var(--ui-header-height);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--ui-space-3);
+  padding: 0 var(--ui-space-2);
+}
+
+.ak-panel__header-title {
+  font-size: var(--ui-font-body);
+  font-weight: var(--ui-weight-semibold);
+  color: var(--ui-base-content);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* 右侧组：toolbar（本区域筛选）在左、actions（本区域操作）在右，内部间距锁死 */
+.ak-panel__header-right {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  min-width: 0;
+}
+
+.ak-panel__header-toolbar,
+.ak-panel__header-actions {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+}
+
+.ak-panel__body {
+  flex: 1;
+  min-height: 0;
+  min-width: 0;
+  overflow: auto;
+}
+
+/* 面板页脚：区域内**常驻**控件（本区域表格的分页条等），不随内容滚动。
+   与 Header 同款 flex-shrink:0；不加边框（面板无框契约只管分区感由 Header 下边线提供），
+   左右内距与 Body 对齐，让分页条与表格左右边缘齐平。 */
+.ak-panel__footer {
+  flex-shrink: 0;
+}
+
+/* ===== AppTree（自建树：节点行 + 缩进 + 展开箭头 + 计数徽标位）=====
+   几何与各态对齐 `@aihub/theme` 的 `components/tree.css` 与 Tree 专页实测：
+   - 行高 30（紧凑档 28）、圆角 6、字号 13、行内 padding 承载缩进（**行底满宽、只有内容缩进**）
+   - 缩进 = 基础内距 8 + level × 步进 10，**无上限**；level 由组件在行上下发
+   - 三态：滑过 Ne11、点击瞬态 #F4F5F9、选中 Au02 底 + Th03 字
+   - 箭头 8px 折线，收起态转 −90°；叶子节点用占位保持层级对齐
+
+   缩进为什么走 CSS 变量而不是行内 paddingLeft：主题包用 typed `attr(data-level type(<number>))`
+   一步算出（`padding-left: calc(8px + attr(...) * 10px)`）；为兼容尚无该能力的引擎，这里由组件
+   同时下发 `--ak-tree-level`，公式仍在 CSS 内（数值只取令牌，不散落字面量）。 */
+.ak-tree {
+  display: flex;
+  flex-direction: column;
+  row-gap: 2px;
+  width: 100%;
+}
+
+.ak-tree__row {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-1);
+  height: var(--ui-tree-row-height);
+  padding: 0 var(--ui-space-2);
+  /* 缩进：基础内距 + level × 步进（level 由组件下发） */
+  padding-left: calc(var(--ui-tree-indent-base) + var(--ak-tree-level, 0) * var(--ui-tree-indent-step));
+  border-radius: var(--ui-radius-control);
+  font-size: var(--ui-font-caption);
+  color: var(--ui-base-content);
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+/* 紧凑档（S）：节点行 28px */
+.ak-tree--compact .ak-tree__row {
+  height: var(--ui-tree-row-height-compact);
+}
+
+.ak-tree__row:hover {
+  background: var(--ui-base-200);
+}
+
+.ak-tree__row:active {
+  background: var(--ui-tree-active-bg);
+}
+
+.ak-tree__row[data-selected='true'] {
+  background: var(--ui-primary-subtle);
+  color: var(--ui-primary);
+}
+
+/* 展开箭头：纯 CSS 三角（不引图标字体）；默认指向右（收起），展开时转 90° 向下 */
+.ak-tree__caret {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 14px;
+  height: 14px;
+  color: var(--ui-base-content-subtle);
+  cursor: pointer;
+}
+
+.ak-tree__caret::before {
+  content: '';
+  display: block;
+  width: 0;
+  height: 0;
+  border-left: calc(var(--ui-tree-caret-size) / 2) solid currentColor;
+  border-top: calc(var(--ui-tree-caret-size) / 2 - 0.5px) solid transparent;
+  border-bottom: calc(var(--ui-tree-caret-size) / 2 - 0.5px) solid transparent;
+  transition: transform 0.15s ease;
+}
+
+.ak-tree__caret[data-expanded='true']::before {
+  transform: rotate(90deg);
+}
+
+/* 叶子节点：占位不显示图形，但保留槽位让同层文字对齐 */
+.ak-tree__caret--empty {
+  cursor: default;
+}
+
+.ak-tree__caret--empty::before {
+  visibility: hidden;
+}
+
+.ak-tree__label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ak-tree__extra {
+  display: inline-flex;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+/* ===== AppForm（自建表单：label + 控件 + 错误 + 说明）=====
+   沿 farris 表单的既有约定：label **右对齐**、必填星号在 label 文本**左侧**。
+   与 farris 动态表单的两处有意差异：① 控件撑满剩余宽度（按需用 controlWidth 收敛），
+   不受 farris「字段 max-width 26.625rem」约束；② 错误与说明走**文档流**排在控件下方
+   （farris 用绝对定位的浮层提示条，在弹窗里会压住下一行控件）。
+
+   label 列宽只由变量驱动：AppForm / AppForm.Item 落 `--ak-form-label-width`，默认取令牌，
+   故换宽窄不需要在消费方写 CSS。 */
+/* 行距取 8px 档：AppForm.Item 自己已经是一个完整行（label 与控件等高 + 错误/说明按文档流往下排），
+   再用 16px 行距会把表单拉得很散 —— 尤其是步骤⑤那种「只读文本行」的摘要，行与行之间会显得发虚。
+   要更松的排版属于消费方场景，改这里之前先确认不是想把「行距」当成区块间距在用。 */
+.ak-form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ui-space-2);
+}
+
+/* 两列（AppForm columns=2）：`auto-fit` + 列最小宽度 ⇒ 容器够宽才并排、窄了**自动回落一列**
+   （不需要媒体查询，也不需要容器查询）。`align-items: start` 让同一行的两个字段各自顶部对齐，
+   不被隔壁那个「错误 + 多行说明」撑高的格子拉扯。 */
+.ak-form--two-column {
+  display: grid;
+  /* 上限 2 列 + 最小列宽：track 下限取「最小列宽」与「按 2 列等分」的较大者
+     —— 否则宽表单里 auto-fit 会一路排到 4 列（实测 1400px 得 4 列），
+     而 `columns={2}` 承诺的是"最多 2 列、窄了回落"（与 AppLayout.Row 同一公式）。 */
+  grid-template-columns: repeat(
+    auto-fit,
+    minmax(
+      max(var(--ui-form-column-min), calc((100% - var(--ui-space-2)) / 2)),
+      1fr
+    )
+  );
+  align-items: start;
+}
+
+/* 跨满整行：说明行 / 卡片组 / 表格 / 文本域这类整块内容（单列时 grid-column 无效，无副作用） */
+.ak-form-item--full {
+  grid-column: 1 / -1;
+}
+
+/* ===== AppSection（区块：区块标题 + 一组内容；表单内写 AppForm.Section，是同一个件）=====
+   内容行距必须由本件自己给：父容器（如 `AppForm`）的 gap 只作用于它的**直接子元素**，
+   内容一旦被包进本件，里面的行距就没人管了（自绘 `<div class="xx-sub-title">` 最常踩的正是这个坑：
+   标题有了、间距乱了）。故固定两档：内容 8px、区块 16px 叠父级 gap（合 24px）——
+   3:1 的对比才读得出「这是两块」。 */
+.ak-section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ui-space-2);
+}
+
+/* 区块间距走 :not(:first-child)：不依赖兄弟结构（两块之间可能夹着别的东西），
+   也让本件能脱离表单单独使用（如「校验结果」这类不成表单的区块）。 */
+.ak-section:not(:first-child) {
+  margin-top: var(--ui-space-4);
+}
+
+/*
+ * 嵌套区块（区块里再分组，如「来源和目标列」下的「来源列 / 目标列」）：
+ * 直接子区块**不再叠区块间距** —— 父级 gap（8px）就是组内行距；再叠 16px 会让二级分组
+ * 离上一块比离自己的标题还远（`:not(:first-child)` 本意是「两块平级区块之间」，不是层级内部）。
+ * 选择器与上面的间距规则同特异性、写在后面，故嵌套时以后者为准（不靠源码外的顺序假设）。
+ */
+.ak-section > .ak-section {
+  margin-top: 0;
+}
+
+/* 区块标题：14px/600。有意不打到 16px（`--ui-font-heading` 是弹窗标题那一档），
+   区块标题只需与字段 label（14px/400）拉出字重差；`extra` 槽（计数、行内按钮）跟在文本之后。 */
+.ak-section__title {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-space-2);
+  font-size: var(--ui-font-body);
+  font-weight: var(--ui-weight-semibold);
+  line-height: var(--ui-line-body);
+  color: var(--ui-base-content);
+}
+
+/* 嵌套区块的标题**降到常规字重**：层级差改由「一级 14/600 ↔ 二级 14/400」表达。
+ * 二级若同样吃 600，与一级抢同一档 ⇒ 读不出从属关系（嵌套里两个 600 并排即为此坑）。 */
+.ak-section > .ak-section > .ak-section__title {
+  font-weight: var(--ui-weight-regular);
+}
+
+.ak-form-item {
+  /* label 列宽：Item 行内下发 --ak-form-label-width；未传时取令牌 */
+  --ak-form-label-width: var(--ui-form-label-width);
+  display: flex;
+  align-items: flex-start;
+}
+
+/* label 列：固定宽 + **右对齐**（与 farris 的动态表单一致，也是水平表单的通行默认）。
+   min-height 取**控件真实高度**（--ui-form-control-height 由桥接层按 farris 控件规则给出）：
+   label 盒与控件盒等高 ⇒ 两侧文字各自居中后落在同一条中线上。
+   曾经写的是 32px 令牌，而 farris 控件实际 ≈24px（rem，随根字号）⇒ label 明显偏低，已修。 */
+.ak-form-item__label {
+  flex: 0 0 auto;
+  width: var(--ak-form-label-width);
+  box-sizing: border-box;
+  min-height: var(--ui-form-control-height, auto);
+  padding-right: var(--ui-space-3);
+  display: flex;
+  align-items: center;
+  /* 右对齐：label 文本贴着控件列，短标签也不会在列里留下大段空隙（与 farris 动态表单一致） */
+  justify-content: flex-end;
+  gap: 2px;
+  font-size: var(--ui-font-body);
+  line-height: var(--ui-line-body);
+  color: var(--ui-base-content);
+}
+
+.ak-form-item__required {
+  flex: 0 0 auto;
+  color: var(--ui-error);
+}
+
+/* label 对齐：基类默认右对齐（贴控件列，`labelAlign` 缺省档）；
+   `labelAlign="left"` 时挂这个修饰类改成左对齐 —— 只给「非默认值」挂类，避免两段声明争胜出顺序。
+   位置必须在基类规则之后：`.ak-form-item__label {` 是它的子串，测试取规则体时按首次出现命中。 */
+.ak-form-item--label-left .ak-form-item__label {
+  justify-content: flex-start;
+}
+
+/* 只读展示行（`AppForm.Item` 的 `text` 形态，或显式 `readonly`）的 label 降一档为**次要色**：
+   值与字段名同取正文色时，摘要 / 详情读起来是一串并列文本，分不清哪个是字段名
+   （原型 .sum-group td.k / .field-item .k 用的正是次要色）。值侧不变，仍是正文色。
+   `muted` 而非 `subtle`：空值占位「—」已经是 subtle，label 再用同色会让空行整行同调。
+   位置同样必须在基类 `.ak-form-item__label {` 之后（spec 的 ruleBody 按首次出现取规则体）。 */
+.ak-form-item--readonly .ak-form-item__label {
+  color: var(--ui-base-content-muted);
+}
+
+/* label 文本过长时省略而不是换行（换行会把控件列挤错位） */
+.ak-form-item__label-text {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ak-form-item__control {
+  flex: 1;
+  min-width: 0;
+}
+
+/* 只读文本行（AppForm.Item 的 text 形态：摘要 / 详情）：正文色与行高，
+   长文案（SQL where、列说明）按词折行；`pre-wrap` 保留换行符（多行过滤条件回显）。 */
+.ak-form-item__text {
+  min-height: var(--ui-form-control-height);
+  display: flex;
+  align-items: center;
+  font-size: var(--ui-font-body);
+  line-height: var(--ui-line-body);
+  color: var(--ui-base-content);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+/* 空值占位（组件统一给 `—`）：压成次要色，避免它被当成真实取值 */
+.ak-form-item__text[data-empty='true'] {
+  color: var(--ui-base-content-subtle);
+}
+
+.ak-form-item__error {
+  margin-top: var(--ui-space-1);
+  font-size: var(--ui-font-caption);
+  line-height: var(--ui-line-caption);
+  color: var(--ui-error);
+}
+
+.ak-form-item__hint {
+  margin-top: var(--ui-space-1);
+  font-size: var(--ui-font-caption);
+  line-height: var(--ui-line-caption);
+  color: var(--ui-base-content-subtle);
+}
+
+/* ===== AppSteps（封装 farris FStep）=====
+   节点圆点 / 连接线 / 三角全部沿用上游样式（本件复刻其 DOM 结构、只替换完成勾图标），
+   故这里没有自有规则；只读档（clickable=false）的光标在 farris-bridge.css。 */

package/dist/composables/use-client-pagination.d.ts

@@ -0,0 +1,39 @@
+import { type MaybeRefOrGetter, type Ref } from 'vue';
+export interface UseClientPaginationOptions {
+    /** 初始页大小；缺省取 `pageSizeOptions[0]` */
+    pageSize?: number;
+    /** 页大小候选；缺省 `[10, 20, 50]`（与 AppPagination 默认一致） */
+    pageSizeOptions?: number[];
+}
+export interface UseClientPagination<T = unknown> {
+    /** 当前页码（**0 基**，与 AppPagination 契约一致） */
+    page: Ref<number>;
+    pageSize: Ref<number>;
+    /** 总条数（切片前） */
+    total: Ref<number>;
+    /** 总页数（至少 1） */
+    pageCount: Ref<number>;
+    /** 当前页数据（已切片，直接喂给 AppTable.rows） */
+    pageRows: Ref<T[]>;
+    pageSizeOptions: number[];
+    setPage: (page: number) => void;
+    setPageSize: (size: number) => void;
+}
+/**
+ * 客户端分页状态（切片 + 越界回退），与 `AppPagination` 同契约（**0 基**）。
+ *
+ * 为什么不在 `AppTable` 内建分页：已接入应用的既有契约是「页面持有 page/pageSize、
+ * 分页器放 `AppShell.Footer`」，`AppTable` 保持纯表格职责。本 composable 把
+ * 「切片 + 越界回退 + 页大小切换回首页」这三件样板事收起来。
+ *
+ * 越界回退：数据变少（过滤 / 删除）导致当前页超出范围时，自动回退到最后一页，
+ * 避免出现「空白页但分页器显示有数据」。
+ *
+ * @example
+ * const list = useClientPagination(() => filteredDefinitions.value)
+ * <AppTable :rows="list.pageRows" ... />
+ * <AppPagination :page="list.page" :pageSize="list.pageSize" :total="list.total"
+ *   :pageSizeOptions="list.pageSizeOptions"
+ *   :onPageChange="list.setPage" :onPageSizeChange="list.setPageSize" />
+ */
+export declare function useClientPagination<T>(rows: MaybeRefOrGetter<T[]>, options?: UseClientPaginationOptions): UseClientPagination<T>;

package/dist/composables/use-client-pagination.js

@@ -0,0 +1,29 @@
+import { ref, computed, toValue, watch } from "vue";
+function useClientPagination(rows, options = {}) {
+  const pageSizeOptions = options.pageSizeOptions ?? [10, 20, 50];
+  const pageSize = ref(options.pageSize ?? pageSizeOptions[0]);
+  const page = ref(0);
+  const total = computed(() => toValue(rows).length);
+  const pageCount = computed(() => Math.max(1, Math.ceil(total.value / pageSize.value)));
+  watch([total, pageSize], () => {
+    const last = pageCount.value - 1;
+    if (page.value > last) page.value = last;
+    if (page.value < 0) page.value = 0;
+  });
+  const pageRows = computed(() => {
+    const start = page.value * pageSize.value;
+    return toValue(rows).slice(start, start + pageSize.value);
+  });
+  const setPage = (next) => {
+    const last = pageCount.value - 1;
+    page.value = Math.min(Math.max(0, next), last);
+  };
+  const setPageSize = (size) => {
+    pageSize.value = size;
+    page.value = 0;
+  };
+  return { page, pageSize, total, pageCount, pageRows, pageSizeOptions, setPage, setPageSize };
+}
+export {
+  useClientPagination
+};

package/dist/entry/create-query-client.d.ts

@@ -0,0 +1,8 @@
+import { QueryClient } from '@tanstack/vue-query';
+/**
+ * 缺省 QueryClient：createSubApp 未显式传入 queryClient 时使用。
+ *
+ * 与各子应用现状 providers.tsx 的公共默认一致（staleTime 30s、不因窗口聚焦重取）；
+ * 带全局错误缓存/自定义 retry 的应用应自建 QueryClient 后经 createSubApp 注入。
+ */
+export declare function createQueryClient(): QueryClient;

package/dist/entry/create-query-client.js

@@ -0,0 +1,14 @@
+import { QueryClient } from "@tanstack/vue-query";
+function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 30 * 1e3,
+        refetchOnWindowFocus: false
+      }
+    }
+  });
+}
+export {
+  createQueryClient
+};