@done-coding/admin-core 0.24.1-alpha.0 → 0.25.1-alpha.0

package/types/components/page-layout/AppPageListDetailSplit.vue.d.ts

@@ -0,0 +1,47 @@
+import { AppPageListDetailDetailScope, AppPageListDetailEmptyScope, AppPageListDetailListProps, AppPageListDetailProps } from './types';
+declare const _default: <T extends Record<string, any>, R = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{} & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, never> & {
+        listProps: AppPageListDetailListProps<T>;
+        ctx: Omit<AppPageListDetailDetailScope<T, R>, "data" | "loading">;
+        listEmpty: boolean;
+        listWidth: string;
+        /**
+         * 本形态不消费，但 [MUST] 声明 —— 门面用 `<component :is>` 给两个形态下发**同一组绑定**，
+         * 某形态不声明的键会退化成 fallthrough attr、经 $attrs 泄漏成 AppPage 上的 DOM 属性
+         * （实测漏出 `sheetsize="70%"`）。
+         */
+        sheetSize?: string | number;
+        /** 同 `sheetSize`：本形态不消费，[MUST] 声明以防 attr 泄漏成 DOM 属性 */
+        sheetLayerType?: "drawer" | "modal";
+        detailApi?: AppPageListDetailProps<R>["detailApi"];
+        detailTitle?: AppPageListDetailProps<R>["detailTitle"];
+    } & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
+    attrs: any;
+    slots: Readonly<{
+        list?: (scope: {
+            listProps: AppPageListDetailListProps<T>;
+        }) => unknown;
+        detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        empty?: (scope: AppPageListDetailEmptyScope) => unknown;
+        top?: () => unknown;
+        bottom?: () => unknown;
+        right?: () => unknown;
+    }> & {
+        list?: (scope: {
+            listProps: AppPageListDetailListProps<T>;
+        }) => unknown;
+        detail?: (scope: AppPageListDetailDetailScope<T, R>) => unknown;
+        empty?: (scope: AppPageListDetailEmptyScope) => unknown;
+        top?: () => unknown;
+        bottom?: () => unknown;
+        right?: () => unknown;
+    };
+    emit: {};
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/types/components/page-layout/index.d.ts

@@ -0,0 +1,4 @@
+import { default as AppPageListDetailLayout } from './AppPageListDetailLayout.vue';
+import { default as AppPageDetail } from './AppPageDetail.vue';
+export { AppPageListDetailLayout, AppPageDetail, };
+export * from './types';

package/types/components/page-layout/types.d.ts

@@ -0,0 +1,102 @@
+import { ActiveRecordKey } from '../../hooks/use-active-record';
+import { NoInferType } from '../../types';
+/** 形态：`auto` 按视口宽定档（默认）｜`split` 强制宽屏并排｜`sheet` 强制窄屏抽屉 */
+export type AppPageListDetailMode = "auto" | "split" | "sheet";
+/**
+ * `#list` 插槽 scope 携带的「列表接线包」——业务 [MUST] 整体 `v-bind` 到列表组件上：
+ *
+ * ```vue
+ * <template #list="{ listProps }">
+ *   <ListLayout v-bind="listProps" :api="api" :columns="columns" row-key="id" />
+ * </template>
+ * ```
+ *
+ * 它同时接了三条线：两个「当前项」model（双向）+ `dataChange`（门面据此算序列 / 自动激活首条）
+ * + `ref`（门面据此调 `refresh()` 实现 `refreshList`）。少接一条对应能力即静默失效。
+ */
+export interface AppPageListDetailListProps<T = any> {
+    activeId: ActiveRecordKey | undefined;
+    "onUpdate:activeId": (v: ActiveRecordKey | undefined) => void;
+    activeData: T | undefined;
+    "onUpdate:activeData": (v: T | undefined) => void;
+    onDataChange: (rows: T[]) => void;
+    ref: (el: unknown) => void;
+}
+/** `#detail` 插槽 scope（`data` / `loading` 仅在传了 `detailApi` 时有值） */
+export interface AppPageListDetailDetailScope<T = any, R = any> {
+    /** 当前项唯一键 */
+    id: ActiveRecordKey | undefined;
+    /** 当前项对应的**列表 item**（恒为列表接口原样，[MUST NOT] 被详情回写） */
+    record: T | undefined;
+    /** 当前项在序列中的位置（1 基；不在序列内 = 0） */
+    index: number;
+    /** 序列总条数（= 列表当前页条数，本期不跨页） */
+    total: number;
+    hasPrev: boolean;
+    hasNext: boolean;
+    goPrev: () => void;
+    goNext: () => void;
+    /** 触发列表整体刷新（REQ-06 唯一通路，[MUST NOT] 反向回写 record） */
+    refreshList: () => void;
+    /** 详情接口数据（未传 `detailApi` 时恒为 undefined——此时详情数据由业务自持） */
+    data: R | undefined;
+    /** 详情接口拉取中（未传 `detailApi` 时恒为 false） */
+    loading: boolean;
+}
+/** `#empty` 插槽 scope */
+export interface AppPageListDetailEmptyScope {
+    /** true = 列表本身无数据；false = 有数据但未选中。两种空态文案不同，由业务分流 */
+    listEmpty: boolean;
+}
+/** `AppPageListDetailLayout` props（不含两个 v-model，见 README） */
+export interface AppPageListDetailProps<R = any> {
+    /** 形态；默认 `auto`（按视口宽 `splitAt` 定档） */
+    mode?: AppPageListDetailMode;
+    /** `auto` 档的切档阈值（px，视口宽），默认 1200 */
+    splitAt?: number;
+    /** 分栏态列表列宽（CSS 长度）。[MUST NOT] 写死 px，默认 `clamp(280px, 28%, 420px)` */
+    listWidth?: string;
+    /**
+     * 列表出数后自动激活第一条。**两形态默认值不同**：`split` 默认 `true`（宽屏右半屏不该空着）、
+     * `sheet` 默认 `false`（窄屏自动弹抽屉是打扰）。显式传值优先。
+     * ⚠️ 详情若有副作用（如「打开即标记已读」）[MUST] 显式关掉。
+     */
+    autoActiveFirst?: boolean;
+    /** 传了才把 `activeId` 同步进 URL query（`replace` 不 `push`）。复原仍走不变式校验 */
+    queryKey?: string;
+    /**
+     * 详情接口。传了则内置 `ViewLayout`（零配置拿到导航 + `refreshToken` 接线）；
+     * 不传则 `#detail` 原样渲染、门面不发任何详情请求（覆盖「详情即列表数据」形态）。
+     * 入参为 `{ id: activeId }`。
+     */
+    detailApi?: (params?: {
+        id: ActiveRecordKey;
+    }) => Promise<R>;
+    /**
+     * 详情区标题。字符串 = 固定标题；函数 = 按数据算标题。
+     *
+     * 函数签名 `(detailData, record) => string`：
+     * - `detailData` = 详情接口数据（**未传 `detailApi` 时恒 `undefined`**）
+     * - `record` = 当前项对应的列表 item（两种形态下都有），**「详情即列表数据」形态靠它出标题**
+     *
+     * 渲染位置：**详情区顶部**（两形态一致），而非 sheet 弹层的 header —— 详情数据只在
+     * 详情区内部（`ViewLayout` 插槽作用域）可得，弹层那一层拿不到。缺省不传则不渲染标题条，
+     * 业务照旧可在 `#detail` 里自绘。
+     *
+     * ⚠️ 首参用 `NoInferType<R>`（本仓自带、非 TS 5.4 内置 `NoInfer` —— 内置的会原样落进
+     * 发布的 d.ts，下游 TS < 5.4 会报找不到）：`R` [MUST] 只由 `detailApi` 的返回类型定。否则本回调的参数标注
+     * 也会参与 `R` 推断，与 `detailApi` 推出的候选打架（实测：`detailApi` 返
+     * `Promise<X | undefined>`、回调标 `(d?: X)` 时报 TS2322，把别扭甩给消费方）。
+     */
+    detailTitle?: string | ((detailData: NoInferType<R> | undefined, record: any) => string);
+    /**
+     * sheet 形态的弹层形态：`drawer` 抽屉（默认）｜`modal` 居中弹窗。透传 `ModalConfirm.layerType`。
+     * 详情区两种承载都支持；窄屏下抽屉更常见，故默认抽屉。
+     */
+    sheetLayerType?: "drawer" | "modal";
+    /**
+     * sheet 形态的弹层尺寸（透传 `ModalConfirm.width`）：`drawer` 下是抽屉尺寸、
+     * `modal` 下是弹窗宽度，两形态同一个口子，默认 `"70%"`。
+     */
+    sheetSize?: string | number;
+}

package/types/components/page-layout/use-list-detail.d.ts

@@ -0,0 +1,58 @@
+import { ComputedRef, Ref, ShallowRef } from 'vue';
+import { ActiveRecordKey } from '../../hooks/use-active-record';
+import { AppPageListDetailMode } from './types';
+/**
+ * 形态定档（`AppPageListDetailLayout` 内部组合函数，**[MUST NOT] 出桶导出**）。
+ *
+ * 判据 [MUST] 用**视口宽**（matchMedia），[MUST NOT] 用容器宽（ResizeObserver）——
+ * 设备宽固定 ≠ 容器宽固定：侧边栏折叠是同设备内的高频操作、会改内容区容器宽，
+ * 用容器断点会折一下侧栏就跨阈值触发形态重建（spec D4 / Ⓒ）。
+ *
+ * 不复用 `useBreakpoint`：那是固定五档梯子（xs…xl），承不住任意 `splitAt` 阈值。
+ */
+export declare function useAppPageListDetailMode(options: {
+    mode: () => AppPageListDetailMode;
+    splitAt: () => number;
+}): {
+    isSplit: ComputedRef<boolean>;
+};
+/**
+ * 序列 + 导航（`AppPageListDetailLayout` 内部组合函数，**[MUST NOT] 出桶导出**）。
+ *
+ * 序列来源 = 列表组件的 `dataChange`（门面经 `#list` 插槽 scope 的 `listProps` 把
+ * `onDataChange` 交给业务 `v-bind` 上去）——门面不持有列表数据、也不知道 `rowKey`。
+ *
+ * 定位当前项用**对象身份**（`rows.indexOf(activeData)`）而非键比对：`activeData` 恒为
+ * 列表数据原样（同一数组里的那个对象，由 `useActiveRecord` 保证），故身份必命中；
+ * 命中失败（当前项不在序列内）→ `index=0` / 两端皆 false，正是 spec 要的边界行为。
+ */
+export declare function useAppPageListDetailSequence<T extends Record<string, any>>(options: {
+    activeId: Ref<ActiveRecordKey | undefined>;
+    activeData: Ref<T | undefined>;
+    autoActiveFirst: () => boolean;
+}): {
+    rows: ShallowRef<T[]>;
+    onDataChange: (rows: T[]) => void;
+    index: ComputedRef<number>;
+    total: ComputedRef<number>;
+    hasPrev: ComputedRef<boolean>;
+    hasNext: ComputedRef<boolean>;
+    goPrev: () => void;
+    goNext: () => void;
+    /** 深链复原用：把 query 里的 id 挂起，等列表首次出数再写（写入合法性交给列表校验） */
+    pendingId: Ref<ActiveRecordKey | undefined>;
+};
+/**
+ * `activeId` ↔ URL query 同步（`AppPageListDetailLayout` 内部组合函数，**[MUST NOT] 出桶导出**）。
+ *
+ * - **[MUST] 用 `replace` 而非 `push`**：连点「下一条」10 次会攒 10 条 history，
+ *   用户要按 10 次后退才能离开页面（spec D9；TabsMain queryKey 期踩过同族坑）。
+ * - 复原**不绕过不变式**：读到的 id 先挂起（`pendingId`），等列表首次出数再写入，
+ *   合法性由列表族的不变式内核校验（查不到 → 忽略 + warn，不激活）。
+ * - 无 router 环境（单测 / 脱离路由）静默降级，[MUST NOT] 抛错。
+ */
+export declare function useAppPageListDetailQuerySync(options: {
+    queryKey: () => string | undefined;
+    activeId: Ref<ActiveRecordKey | undefined>;
+    pendingId: Ref<ActiveRecordKey | undefined>;
+}): void;

package/types/components/panel/PanelEditSwitch.vue.d.ts

@@ -0,0 +1,30 @@
+import { PanelEditSwitchProps } from './types';
+import { ExcludeNeverProperties, ExtractFormStringifyRawFromObject, FormDataInfo } from '../form';
+declare const _default: <PO extends Record<string, any>, SO extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly onSubmitSuccess?: ((data: ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>) => any) | undefined;
+        readonly "onUpdate:editing"?: ((value: boolean) => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onSubmitSuccess" | "onUpdate:editing"> & ({
+        editing?: boolean;
+    } & PanelEditSwitchProps<PO, SO>) & Partial<{}>> & import('vue').PublicProps;
+    expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
+    attrs: any;
+    slots: {
+        default?(_: {
+            stringifyDraftData: ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>;
+        }): any;
+        default?(_: {
+            stringifyDraftData: ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>;
+        }): any;
+        editor?(_: {
+            stringifyDraftData: ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>;
+        }): any;
+    };
+    emit: ((e: "submitSuccess", data: FormDataInfo<PO, SO>["stringifyData"]) => void) & ((evt: "update:editing", value: boolean) => void);
+}>) => import('vue').VNode & {
+    __ctx?: Awaited<typeof __VLS_setup>;
+};
+export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/types/components/table/TableMain.vue.d.ts

@@ -1,3 +1,4 @@
+import { ActiveRecordKey } from '../../hooks/use-active-record';
 import { TableMainProps, TableMainInstance, ElTableColumnProps, TablePageInfo } from './types';
 declare const _default: <T extends Record<string, any>, SQ extends Record<string, any>, F extends Record<string, any>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
@@ -5,11 +6,15 @@ declare const _default: <T extends Record<string, any>, SQ extends Record<string
         readonly onLoadingChange?: ((value: boolean) => any) | undefined;
         readonly "onUpdate:refreshInterval"?: ((value: number) => any) | undefined;
         readonly "onUpdate:customView"?: ((value: boolean) => any) | undefined;
+        readonly "onUpdate:activeId"?: ((value: ActiveRecordKey | undefined) => any) | undefined;
+        readonly "onUpdate:activeData"?: ((value: T | undefined) => any) | undefined;
         readonly onPageChange?: ((value: number) => any) | undefined;
         readonly onPageSizeChange?: ((value: number) => any) | undefined;
         readonly onDataChange?: ((data: T[]) => any) | undefined;
         readonly onPageInfoChange?: ((info: TablePageInfo) => any) | undefined;
-    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:isAutoRefresh" | "onLoadingChange" | "onUpdate:refreshInterval" | "onUpdate:customView" | "onPageChange" | "onPageSizeChange" | "onDataChange" | "onPageInfoChange"> & ({
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:isAutoRefresh" | "onLoadingChange" | "onUpdate:refreshInterval" | "onUpdate:customView" | "onUpdate:activeId" | "onUpdate:activeData" | "onPageChange" | "onPageSizeChange" | "onDataChange" | "onPageInfoChange"> & ({
+        activeId?: ActiveRecordKey | undefined;
+        activeData?: T | undefined;
         isAutoRefresh?: boolean;
         refreshInterval?: number;
         customView?: boolean;
@@ -34,6 +39,8 @@ declare const _default: <T extends Record<string, any>, SQ extends Record<string
             index: number;
             selected: boolean;
             toggleSelect: () => void;
+            active: boolean;
+            setActive: () => void;
         }): any;
     };
     emit: {
@@ -41,7 +48,7 @@ declare const _default: <T extends Record<string, any>, SQ extends Record<string
         (e: "dataChange", data: T[]): void;
         (e: "loadingChange", value: boolean): void;
         (e: "pageInfoChange", info: TablePageInfo): void;
-    } & (((evt: "update:isAutoRefresh", value: boolean) => void) & ((evt: "update:refreshInterval", value: number) => void) & ((evt: "update:customView", value: boolean) => void));
+    } & (((evt: "update:isAutoRefresh", value: boolean) => void) & ((evt: "update:refreshInterval", value: number) => void) & ((evt: "update:customView", value: boolean) => void) & ((evt: "update:activeId", value: ActiveRecordKey | undefined) => void) & ((evt: "update:activeData", value: T | undefined) => void));
 }>) => import('vue').VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };

package/types/components/view-layout/ViewLayoutNavigation.vue.d.ts

@@ -0,0 +1,13 @@
+import { AppPageListDetailNavigationContext } from './types';
+/**
+ * ViewLayout toolbar 内置导航（view-layout 族内部件，**不出桶导出**）。
+ *
+ * 独立成组件的理由：ViewLayout 的 toolbar 在精细流 / 自然流两个分支各写了一遍，
+ * 内联会把同一段导航标记重复两处；抽出后两处各一行引用（且 ViewLayout 主干不涨过程代码）。
+ */
+type __VLS_Props = {
+    /** 由 AppPageListDetailLayout provide 的上下文（ViewLayout 侧已判定非空才渲染本组件） */
+    ctx: AppPageListDetailNavigationContext;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/types/components/view-layout/types.d.ts

@@ -1,4 +1,19 @@
+import { Ref } from 'vue';
 import { ActionBtnConfigItem } from '../display';
+/**
+ * 列表 / 详情同页范式的导航上下文（`APP_PAGE_LIST_DETAIL_CONTEXT` 的值形状）。
+ * 在此重声明一份**结构等价**的类型，是为了让 view-layout 族不反向 import inject 桶
+ * （inject/key.ts 已 import 了 app-layout 的类型，反向引会成环）。
+ */
+export interface AppPageListDetailNavigationContext {
+    hasPrev: Readonly<Ref<boolean>>;
+    hasNext: Readonly<Ref<boolean>>;
+    index: Readonly<Ref<number>>;
+    total: Readonly<Ref<number>>;
+    goPrev: () => void;
+    goNext: () => void;
+    refreshList: () => void;
+}
 /**
  * ViewLayout 默认插槽 scope（注入给插槽内容的数据与操作句柄）
  */
@@ -20,6 +35,19 @@ export interface ViewLayoutButtonContext {
     loading: boolean;
     /** 手动刷新（与右上角刷新按钮同源，等价插槽 scope.refresh） */
     refresh: () => Promise<void>;
+    /**
+     * 以下导航句柄**仅在 `AppPageListDetailLayout` 内**有值（门面 provide 上下文时注入）；
+     * 单独使用 ViewLayout 时恒为 `undefined`。业务自定义按钮可据此做「保存并下一条」等组合动作。
+     */
+    hasPrev?: boolean;
+    hasNext?: boolean;
+    /** 当前项在序列中的位置（1 基；不在序列内 = 0） */
+    index?: number;
+    total?: number;
+    goPrev?: () => void;
+    goNext?: () => void;
+    /** 触发列表整体刷新（REQ-06 唯一通路） */
+    refreshList?: () => void;
 }
 /** ViewLayout toolbar 额外按钮配置（ActionBtnGroup 单项，default-size=small 对齐 table-toolbar 视觉惯例） */
 export type ViewLayoutButtonConfig = ActionBtnConfigItem<ViewLayoutButtonContext>;
@@ -31,6 +59,17 @@ export interface ViewLayoutProps<P = Record<string, any>, R = any> {
     api: (params?: P) => Promise<R>;
     /** 拉取参数；响应式变化不自动重拉（需要时调 scope.refresh()） */
     params?: P;
+    /**
+     * 外部重拉触发口：**值变化即触发一次 `api` 重拉**，且 [MUST NOT] 进 `params`
+     * （不污染请求参数、不发给后端）。默认 `undefined` = 不触发，老行为逐字节不变。
+     *
+     * - 语义是「令牌」而非参数：把「什么时候该重拉」与「拉什么」解耦——需要新参数时改
+     *   `params`（不自动重拉，防请求风暴的既有设计），需要重拉时动 `refreshToken`。
+     * - 变为 `undefined` 时**不触发**（清空令牌 ≠ 要求刷新），避免无谓请求。
+     * - 典型用途：列表 / 详情同页范式里承接 `activeId` 变化（`:refreshToken="activeId"`）。
+     *   [MUST NOT] 改用 `:key="activeId"` 重建 —— 那会连 toolbar / 导航一起重建，连点时闪烁。
+     */
+    refreshToken?: string | number;
     /** 精细流：默认 false（自然流：无高度预算，内容按自身尺寸）；true=包 HeightProvider 精确扣 toolbar reserve，内容区可用高（slot scope viewportHeight + 容器 max-height） */
     refine?: boolean;
     /** 显式视口高，优先级最高；未传降级 inject SCOPE_VIEWPORT_MAX_HEIGHT scope 链 */
@@ -45,6 +84,13 @@ export interface ViewLayoutProps<P = Record<string, any>, R = any> {
     showAutoRefresh?: boolean;
     /** 是否显示手动刷新按钮（默认 true） */
     showRefresh?: boolean;
+    /**
+     * 是否显示内置「上一条 / 下一条」导航（默认 true）。
+     * ⚠️ **真正的显隐判据是可选 inject 探测**：只有置于 `AppPageListDetailLayout` 内
+     * （注入到导航上下文）才渲染；单独使用 ViewLayout 时无论本值为何都不渲染 ——
+     * 故老用法一行不改、零变化。本 prop 用于在门面内**显式关掉**导航。
+     */
+    showNavigation?: boolean;
     /** 左侧额外按钮（ActionBtnGroup 配置，ctx = { loading, refresh }，default-size=small 对齐 table-toolbar） */
     leftExtraButtons?: ViewLayoutButtonConfig[];
     /** 右侧额外按钮（置于 AutoRefreshGroup 之前） */

package/types/hooks/use-active-record.d.ts

@@ -0,0 +1,64 @@
+import { Ref } from 'vue';
+/**
+ * 当前项唯一键：`string | number` **两种都是一等公民**——出口值保持业务数据里的原始类型
+ * （`rowKey` 是字段名时直接取 `row[rowKey]`，数字 id 出数字、字符串 id 出字符串），
+ * 仅**比对**时内部统一 `String()` 归一，故外部传另一种类型也照样命中。
+ */
+export type ActiveRecordKey = string | number;
+/**
+ * 行 → 当前项键值（保原始类型）。`rowKey` 为字段名 → 直取 `row[rowKey]`（number 保持 number）；
+ * 为取键函数 → 用其返回值（契约上是 string）。
+ *
+ * ⚠️ [MUST NOT] 在此 `String()` 归一 —— 那会把业务的数字 id 强制变成字符串吐回去
+ * （归一只发生在比对处，见 `normalizeActiveKey`）。
+ */
+export declare const activeRecordValueOf: <T extends Record<string, any>>(row: T, rowKey: string | ((row: T) => string)) => ActiveRecordKey;
+/**
+ * 「当前项」（active）双 model 同步内核（core 内部组合函数，**[MUST NOT] 出桶导出**——
+ * 见 hooks/index.ts 锁面注释；使用者可枚举：TableMain / DataListView / DataGridView）。
+ *
+ * `activeId`（唯一键）与 `activeData`（列表 item）**同生同灭**，由本 hook 守以下不变式
+ * （spec D2「先有列表，才有详情」）：
+ *
+ * > `activeId` 有值 ⇒ `activeData` 必有值，且 `activeData` 恒为**列表数据原样**（非详情数据）。
+ *
+ * | 触发 | 行为 |
+ * | --- | --- |
+ * | 用户点击某项（`setActive(row)`） | 同时写两者（data 即被点行对象，天然一致） |
+ * | 外部写入 `activeData`（如序列导航切上/下一条） | **对等通道**：按行反查键 → 同步 `activeId`；行不在列表内 → 忽略 + `console.warn` + 回滚 |
+ * | 列表数据刷新 | 按当前 id 在新数据内重查 → 刷新 `activeData`；**查不到 → 两者一并清空** |
+ * | 外部写入不在列表内的 id | **忽略 + `console.warn`**（回滚到上一个合法值），[MUST NOT] 擅自清空用户既有选中 |
+ * | 外部写入 `undefined` | 合法清空（两者一并归零） |
+ *
+ * ⚠️ 外部写入的校验与同步走 `watch`（值变化语义）：**同一 tick 内把 `activeId` 改回原值**
+ * （如 `undefined → "1" → undefined`）净值未变、watch 不触发，`activeData` 会停在中间态。
+ * 实际写入路径（点击走 `setActive` 同步写两者、外部写入天然跨 tick）不会遇到；
+ * [MUST NOT] 在同一 tick 内对 `activeId` 做往返赋值。
+ *
+ * ⚠️ `activeId` **出口值保原始类型**（`rowKey` 为字段名时即 `row[rowKey]`，数字 id 出数字）；
+ * 外部写入用另一种类型（如字符串 `"1"` 对数字 id）同样命中——比对统一 `String()` 归一，
+ * 且**保留调用方写入的原值**，不回写覆盖。
+ *
+ * @param options.data      当前列表数据（getter，数组整体重赋值时触发重查）
+ * @param options.keyOf     行 → 唯一键**原始值**（各消费方用自己的 rowKey 解析，
+ *   [MUST] 走 {@link activeRecordValueOf} 保类型，[MUST NOT] 自行 `String()` 归一）
+ * @param options.activeId  `v-model:activeId`
+ * @param options.activeData `v-model:activeData`
+ * @param options.name      消费方组件名（仅用于 warn 前缀）
+ * @param options.enabled   本实例是否接管不变式（默认 true）。**唯一用途**：TableMain 在
+ *   `customView` 态把渲染与点击交给内层 `DataListView`（后者自带本 hook），此时 TableMain 侧
+ *   [MUST] 关掉，否则同一对 model 上跑两份状态机 —— 双重 warn、两个 `lastValidId` 各自为政。
+ */
+export declare function useActiveRecord<T extends Record<string, any>>(options: {
+    data: () => T[];
+    keyOf: (row: T) => ActiveRecordKey;
+    activeId: Ref<ActiveRecordKey | undefined>;
+    activeData: Ref<T | undefined>;
+    name: string;
+    enabled?: () => boolean;
+}): {
+    /** 该行是否为当前项 */
+    isActive: (row: T) => boolean;
+    /** 设为当前项（传 undefined = 清空）；内部写入路径，不触发非法值告警 */
+    setActive: (row: T | undefined) => void;
+};

package/types/index.d.ts

@@ -9,6 +9,7 @@ export * from './components/table';
 export * from './components/list-layout';
 export * from './components/panel';
 export * from './components/app-layout';
+export * from './components/page-layout';
 export * from './components/slot-layout';
 export * from './components/view-layout';
 export * from './router';

package/types/inject/key.d.ts

@@ -200,3 +200,32 @@ export declare const FORM_NEST_REGISTRY_KEY: InjectionKey<NestFormExposeMap>;
  * Symbol.for 保证跨包/跨 chunk/跨 ESM 实例唯一（规则 8，同上）。
  */
 export declare const NEST_LAYOUT_SCALE_KEY: InjectionKey<Readonly<Ref<number>>>;
+/**
+ * 列表 / 详情同页范式上下文 inject key（`AppPageListDetailLayout` 唯一 provide、后代按需 inject）。
+ * ---
+ * 承载两件事，**刻意合成同一个上下文、[MUST NOT] 另开第二个接缝**：
+ * - **序列导航**（`hasPrev` / `hasNext` / `goPrev` / `goNext` / `index` / `total`）——
+ *   `ViewLayout` 据此**可选探测**是否渲染内置上/下一条按钮：注入到才渲染，
+ *   单独使用 `ViewLayout` 时完全不渲染（老用法一行不改）。
+ * - **`refreshList`**（REQ-06 单向同步的唯一通路）：详情侧判定与列表 item 不同步时触发
+ *   **列表整体刷新**，由列表接口出新数据；[MUST NOT] 由详情反向回写 `activeData`。
+ * ---
+ * `index` 为 **1 基**（无当前项 = 0），直接可作 “第 index / total 条” 展示。
+ * Symbol.for 保证跨包/跨 chunk/跨 ESM 实例唯一（规则 8，同上）。
+ */
+export declare const APP_PAGE_LIST_DETAIL_CONTEXT: InjectionKey<{
+    /** 是否有上一条（当前项不在序列内时为 false） */
+    hasPrev: Readonly<Ref<boolean>>;
+    /** 是否有下一条（当前项不在序列内时为 false） */
+    hasNext: Readonly<Ref<boolean>>;
+    /** 当前项在序列中的位置（1 基；无当前项 / 不在序列内 = 0） */
+    index: Readonly<Ref<number>>;
+    /** 当前序列总条数（= 列表当前页数据条数，本期不跨页） */
+    total: Readonly<Ref<number>>;
+    /** 切到上一条（无上一条时空操作） */
+    goPrev: () => void;
+    /** 切到下一条（无下一条时空操作） */
+    goNext: () => void;
+    /** 触发列表整体刷新（REQ-06 唯一通路） */
+    refreshList: () => void;
+}>;

package/types/injectInfo.json.d.ts

@@ -1,6 +1,6 @@
 declare const _default: {
   "name": "@done-coding/admin-core",
-  "version": "0.24.1-alpha.0",
+  "version": "0.25.1-alpha.0",
   "description": "内部前端库"
 };
 

package/types/types/utility-types.d.ts

@@ -6,3 +6,20 @@
  *     -> { page: { page: number; pageSize: number } }
  */
 export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * 阻断类型推断（等价 TS 5.4 内置的 `NoInfer<T>`，自带一份不依赖下游 TS 版本）。
+ * ---
+ * 用于「同一个泛型参数被多处标注、但只应由其中一处决定」的场景：把不该参与推断的那处
+ * 包上本类型，该位置便只做校验、不产候选。
+ *
+ * ⚠️ [MUST NOT] 直接用 TS 内置 `NoInfer<T>`：core 是发布包，它会原样落进 `.d.ts`，
+ * 下游 TS < 5.4 编译时报 `Cannot find name 'NoInfer'`（本包 devDep 声明的还是 `^5.2.2`）。
+ *
+ * 实现：`[T]` 包一层再按 `T extends any` 取下标——延迟解析使该位置成为非推断位。
+ *
+ * @example
+ *   // R 只由 api 的返回类型定；title 回调的标注不参与推断
+ *   api: () => Promise<R>;
+ *   title?: (data: NoInferType<R>) => string;
+ */
+export type NoInferType<T> = [T][T extends any ? 0 : never];