@q1travel/design-system 0.7.3 → 0.8.0

package/contracts/overlay-foundation.md

@@ -1,6 +1,6 @@
 # Overlay Foundation Contract
 
-> 状态：Accepted（O1–O7 已确认；仅允许进入 Foundation RED 阶段，未授权 GREEN 或生产实现）。
+> 状态：Accepted（O1–O7 已确认；Foundation GREEN 与首批组件接入已落地；D7 Web migration 与实际 ticket/blocking graph 仍 pending）。
 > Issue：[#27](https://github.com/q1travel/q1travel-design-system/issues/27)
 > 日期：2026-08-06
 > 所有者：`@q1travel/design-system`
@@ -19,9 +19,9 @@
 
 ## 2. 决策边界
 
-### 2.1 本稿确认
+### 2.1 D0/RED 阶段确认（历史边界）
 
-本稿已按 O1–O7 完成 ADR review，可作为 Foundation RED 阶段的行为约束。以下边界仍然有效：
+本稿已按 O1–O7 完成 ADR review，可作为 Foundation RED 阶段的行为约束。以下边界记录的是 D0/RED 阶段的授权范围；当前实现与 provenance 状态以 §7.1 为准：
 
 - 不修改现有 overlay 组件实现；
 - 不新增公开 `OverlayHost`、stack 或 hook API；
@@ -189,6 +189,19 @@ D7  q1travel-web adoption/migration
 - D6 不等于 npm publish；source、PR、CI/review、merge、registry/release、consumer adoption 和 production/smoke 是独立 gates。
 - D7 不属于本仓库 #27 的实现 PR；Web 只能在 package contract、发布和 consumer evidence 都满足后另行授权。
 
+### 7.1 当前实现与 acceptance/provenance closeout（2026-08-06）
+
+本节把 D0–D7 的当前事实与原始 ADR 边界分开记录，不把 package implementation、release、Web adoption 或 issue tracker 状态混为同一个 gate：
+
+- **D0 — ADR/contract：已完成。** O1–O7 已确认，本文件是当前 canonical contract。
+- **D1/D2 — Foundation RED/GREEN：已完成。** `9d0d56da527e66f3d2e793364bf0b2c9e2ebd828` 引入 shared `overlayCore`、`useOverlay` 与 Foundation runtime；当前 targeted runtime/browser contract `node --test scripts/check-overlay-foundation-red.test.mjs` 通过（2/2）。
+- **D3–D5 — 首批组件接入：实现已进入 main。** `Modal`、`DestructiveActionModal`、`Sheet`、`Drawer` 均通过 `useOverlay` 接入；Sheet 保持 `blocking=true/outsidePointer=false`，DestructiveActionModal 的 loading policy 保留。实现证据不等于已建立对应的独立 GitHub blocking tickets。
+- **D6 — package/release provenance：已完成。** 0.7.3 exact package source 为 `224f723f3a4e7bb3d5256ae2364783362b2f8eaf`，`v0.7.3` 已解析到该 source，registry provenance 已由 `b40a3b5ad49156c3d8b0409b226c15b37468f8c7` 写入 remote `main`。
+- **D7 — q1travel-web adoption/migration：pending。** 本次没有修改 Web，也没有把 Web migration 伪装成 package acceptance；Web 仍需独立 ticket、consumer evidence 与单独授权。
+- **Ticket graph：pending。** 当前 GitHub 中没有 Foundation、Modal、Sheet、Drawer、Web migration 的独立 blocking ticket 记录；本 contract 的 D3–D7 图是交付边界，不是 GitHub tracker 已建立的 blocking edges。
+
+因此，#27 的 package-side implementation/provenance evidence 已具备；issue acceptance 仍不能在缺少独立 ticket graph、contract 状态同步与 D7 Web gate 的情况下被解释为全链路完成。
+
 ## 8. 已确认的 ADR decisions
 
 以下结论已在本次 #27 review 中确认。它们定义 RED 阶段的边界，不授权生产实现：
@@ -205,7 +218,7 @@ D7  q1travel-web adoption/migration
 
 ## 9. 非目标
 
-- 不在本票中修复 Modal、Sheet、Drawer、DestructiveActionModal 的现有实现差异。
+- D0/RED 阶段不在本票中修复 Modal、Sheet、Drawer、DestructiveActionModal 的现有实现差异；当前 D2–D5 实现状态以 §7.1 为准。
 - 不在本票中新增动画、视觉 redesign、尺寸/radius/color token 或组件 API。
 - 不在本票中迁移 Web，也不以 Web PR、Web 测试通过或本地浏览器结果替代 package contract acceptance。
 - 不以关闭 #27、创建 PR、merge、publish 或 release 作为本 contract 的隐含后续动作。

package/contracts/pagination-migration.md

@@ -0,0 +1,53 @@
+# Pagination 公共 API 迁移合同
+
+Status: accepted locally
+
+Decision date: 2026-08-07
+
+Related: q1travel-design-system#26, #108, #109
+
+Published baseline: `@q1travel/design-system@0.7.3`
+
+Planned breaking release: `0.8.0`
+
+## Public naming decision
+
+`Pagination` → `DocsPagination` is the accepted documentation-navigation replacement.
+
+The published `Pagination` component in `0.7.3` is the documentation previous/next navigation rail. Its replacement is `DocsPagination`. The new product data-set component owns the public name `Pagination`.
+
+| Boundary | Public meaning | Consumer boundary |
+| --- | --- | --- |
+| `0.7.3` and earlier | `Pagination` means documentation previous/next navigation | Existing consumers remain on the published baseline. |
+| `0.8.0` candidate | `DocsPagination` means documentation previous/next navigation; `Pagination` means controlled product pagination | Consumers migrate their old documentation import to `DocsPagination`. |
+
+This is a breaking public API boundary. The candidate does not add a same-name compatibility alias or a fallback that makes one `Pagination` export mean two different contracts.
+
+## Pagination models
+
+The `0.8.0` candidate freezes two independent product models:
+
+- Known-total: controlled `page` and `onChange`, with either `total` or `totalPages`; numeric page controls and range summary are allowed.
+- Unknown-tail: controlled `page` and `onChange`, with `hasNextPage`; it does not fabricate `total`, a last page, or numeric page-window controls.
+- `true-cursor` remains deferred until a real consumer supplies the cursor ownership, request boundary, and acceptance evidence. It is not inferred from `total`, `page`, or `hasNextPage`.
+
+TypeScript is the public input boundary for the mutually exclusive models. The package does not own q1travel-web data fetching, query-string state, router navigation, or cursor token parsing.
+
+## Route and link ownership
+
+The documentation route `/components/pagination` is retained. It documents both the product `Pagination` boundary and the separate `DocsPagination` sequence-navigation boundary.
+
+`DocsPagination` accepts consumer-owned real `href` values and renders native links. It does not import a q1travel-web router or decide URL construction.
+
+## Compatibility, removal, and rollback
+
+- The compatibility window is the published `0.7.3` baseline: existing documentation-navigation consumers can remain on `Pagination` at that version while they migrate to `DocsPagination`.
+- The old documentation-navigation API is removed from the `Pagination` name only in the planned breaking `0.8.0` release. No same-version alias is added to the candidate.
+- Before publishing `0.8.0`, the release gate must verify the exact package tarball, generated declarations, known q1travel consumer migration, and a rollback path that pins the consumer to `0.7.3`.
+- Unknown third-party consumers cannot be enumerated from q1travel repositories; that limitation is part of the release risk and is not evidence that migration is complete.
+
+## Web migration gate
+
+q1travel-web migration remains a separate gate. This package candidate does not modify q1travel-web, does not claim consumer adoption, and does not publish or deploy. Web migration may start only after a verified published package release and a separately authorized consumer change.
+
+This contract records the public boundary; it does not perform the `0.8.0` version bump, npm publish, Web migration, issue closure, or production validation.

package/dist-pkg/design-system.d.ts

@@ -637,6 +637,18 @@ export declare function DestructiveActionModal({ open, onClose, title, descripti
     onConfirm: () => string | null;
 }): ReactNode;
 
+export declare type DocsPageLink = {
+    title: string;
+    href: string;
+};
+
+export declare function DocsPagination({ previous, next }: DocsPaginationProps): JSX.Element;
+
+export declare type DocsPaginationProps = {
+    previous?: DocsPageLink;
+    next?: DocsPageLink;
+};
+
 export declare function DotsMenu({ entries, size, disabled, align, }: {
     entries: DotsMenuEntry[];
     size?: 'sm' | 'md' | 'lg';
@@ -829,6 +841,18 @@ export declare function Kbd({ meta, shift, alt, ctrl, small, children, }: {
     children?: ReactNode;
 }): JSX.Element;
 
+export declare type KnownTotalPaginationProps = PaginationCommonProps & ({
+    total: number;
+    totalPages?: never;
+    hasNextPage?: never;
+    showPageNumbers?: boolean;
+} | {
+    total?: never;
+    totalPages: number;
+    hasNextPage?: never;
+    showPageNumbers?: boolean;
+});
+
 export declare function Label({ htmlFor, required, children, }: {
     htmlFor?: string;
     required?: boolean;
@@ -997,14 +1021,31 @@ declare type NoteSize = 'small' | 'default' | 'large';
 
 export declare type NoteTone = 'info' | 'success' | 'warning' | 'error' | 'secondary';
 
-declare type PageLink = {
-    title: string;
+export declare function Pagination({ page, pageSize: pageSizeProp, total, totalPages: totalPagesProp, hasNextPage, onChange, loading, showPageNumbers, summary, pageSizeSlot, prevLabel, nextLabel, compact, className, }: PaginationProps): JSX.Element;
+
+declare type PaginationCommonProps = {
+    page: number;
+    pageSize?: number;
+    onChange: (page: number) => void;
+    loading?: boolean;
+    summary?: ReactNode | ((args: PaginationSummaryArgs) => ReactNode);
+    pageSizeSlot?: ReactNode;
+    prevLabel?: string;
+    nextLabel?: string;
+    compact?: boolean;
+    className?: string;
 };
 
-export declare function Pagination({ previous, next }: {
-    previous?: PageLink;
-    next?: PageLink;
-}): JSX.Element;
+export declare type PaginationProps = KnownTotalPaginationProps | UnknownTailPaginationProps;
+
+export declare type PaginationSummaryArgs = {
+    page: number;
+    totalPages?: number;
+    total?: number;
+    pageSize: number;
+    start: number;
+    end: number;
+};
 
 export declare function PeriodCombobox({ presets, activeLabel, onPick, }: {
     presets: CalendarPreset[];
@@ -1424,6 +1465,13 @@ declare type TooltipTriggerProps = {
 
 export declare type TriggerKind = 'default' | 'compact';
 
+export declare type UnknownTailPaginationProps = PaginationCommonProps & {
+    total?: never;
+    totalPages?: never;
+    hasNextPage: boolean;
+    showPageNumbers?: false;
+};
+
 export declare function useCopy(): {
     copied: boolean;
     copy: (value: string, successMessage?: string) => Promise<void>;