@q1travel/design-system 0.8.0 → 0.9.0

package/contracts/pagination-migration.md

@@ -33,6 +33,50 @@ The `0.8.0` candidate freezes two independent product models:
 
 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.
 
+## #111 Shared slots and loading accessibility
+
+Status: accepted locally
+
+Decision date: 2026-08-07
+
+This contract applies to the current known-total and unknown-tail models. A future true-cursor model must reuse these shared semantics, but this decision does not add a cursor prop or infer cursor ownership before #110 supplies a real consumer and request boundary.
+
+### Shared public types
+
+`PaginationCommonProps` is the named public type for props shared by every product-pagination model. `PaginationSummaryArgs` remains the public callback input type. The model-specific types extend the common type and remain mutually exclusive.
+
+### Summary
+
+- The summary is rendered before the controls inside the named pagination `nav`.
+- The summary uses `aria-live="polite"` and `aria-atomic="true"`. Page changes and loading completion may update this region; consumer-provided text must be concise and stable enough to announce.
+- A summary callback receives `page`, `pageSize`, `total`, `totalPages`, `start`, and `end`. Unknown-tail supplies no fabricated `total` or `totalPages` and uses `start: 0` and `end: 0` unless the consumer supplies a different summary node.
+- The package owns the default summary formatting, but does not own data-fetching status or consumer-specific result wording.
+
+### `pageSizeSlot`
+
+- `pageSizeSlot` is a consumer-owned `ReactNode`, rendered before the pagination buttons in the controls region.
+- The package positions the node but does not create, control, label, or synchronize a page-size control.
+- If the slot contains an interactive control, the consumer must provide a programmatic label association, such as a `label`/`htmlFor` pair or `aria-label`/`aria-labelledby`. A bare text wrapper is not an accessible label contract.
+- The slot may wrap in compact or narrow layouts; the consumer remains responsible for the control's value, state, and update handling.
+
+### Loading, focus, and completion
+
+- While `loading` is true, the pagination `nav` exposes `aria-busy="true"` and the existing Spinner exposes the polite status text `加载中…`.
+- Structural boundary controls and empty-state controls remain natively disabled.
+- Actionable pagination controls remain focusable while loading and expose `aria-disabled="true"`. Their click and keyboard handlers are inert until loading ends. This preserves the user's current focus rather than moving focus to a newly rendered control.
+- The current-page marker and `aria-current="page"` remain stable while loading.
+- After a real loading-to-idle transition, a separate polite, atomic completion region announces `分页已更新`. The summary may additionally announce the new range or page.
+
+### Responsive and unavailable states
+
+- `compact` and the existing tokenized responsive layout own dense and narrow presentation; the shared semantics do not change at smaller widths.
+- `total={0}` exposes the existing `暂无数据` summary and does not fabricate page numbers.
+- Error or unavailable presentation is consumer-owned composition around `Pagination` (for example, an adjacent alert and a disabled/empty pagination state); #111 does not add an `error` or `unavailable` prop.
+
+### Required evidence
+
+The package contract must be backed by generated public declarations, a TypeScript consumer fixture, static markup assertions for summary/slot/busy semantics, and browser assertions for native keyboard activation, visible focus, loading `aria-disabled`, focus retention, completion announcement, empty state, and labelled page-size controls. Web migration, true-cursor adoption, publication, and issue closure remain independent gates.
+
 ## 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.

package/contracts/table-migration.md

@@ -0,0 +1,168 @@
+# Table 公共合同
+
+Status: accepted locally
+
+Decision date: 2026-08-08
+
+Related: q1travel-design-system#25
+
+This contract freezes the first public boundary for a shared `Table`. It records
+the behavior and ownership decisions needed before implementation; it does not
+implement the component, change q1travel-web, create migration tickets, or
+claim consumer adoption.
+
+## Public boundary
+
+`Table` is a consumer-controlled, native-semantic table. It renders the rows and
+columns supplied by the consumer, but it does not fetch data, own router state,
+infer a data-set selection, or implement pagination.
+
+The first implementation is split into three responsibilities:
+
+| Responsibility | Frozen public boundary | Ownership |
+| --- | --- | --- |
+| Core | `columns`, `data`, stable `rowKey`, native `table` / `thead` / `tbody` / `th` semantics, composed rows, and consumer-owned loading/empty/error content | Table owns structure and semantics; the consumer owns data and state content |
+| Interaction | Controlled selection, current-page select-all, bulk actions, action columns, and keyboard-operable row activation | The consumer owns selected state and action effects; Table owns selection wiring and accessible interaction states |
+| Layout and data behavior | Controlled sorting with `aria-sort`, `stickyHeader`, `maxBodyHeight`, explicit density, `minWidth`, column-group composition, `renderRow`, and `showHeader` | Table owns layout wiring and state attributes; the consumer owns sort state, render decisions, and data ordering |
+
+The public component must not require a business-specific workflow, request
+library, router, or product-side data model.
+
+## Core contract
+
+- `columns` and `data` are consumer-owned inputs. A column identifies its
+  heading and cell rendering without requiring Table to know the domain model.
+- `rowKey` is a stable consumer-owned key. Table must not use the array index as
+  the identity for selection, updates, or row activation.
+- The default structure uses native table elements and `th scope="col"`.
+  Table does not promote the surface to `role="grid"` or add arrow-key grid
+  navigation in this contract.
+- `renderRow` and composed cells may extend row presentation, but they must
+  preserve the table's heading, cell, focus, and selection semantics.
+- Loading, empty, and error states are explicit consumer-owned surfaces. Table
+  must not invent fetch status, error copy, recovery actions, or business
+  permissions. An empty result may be rendered as an adjacent Empty State
+  rather than as an artificial table row.
+- `showHeader` is a presentation option, not permission to remove the
+  accessible relationship between cells and their column headings. A consumer
+  that hides the visual header remains responsible for an accessible table
+  name and header semantics.
+
+The current documentation-only `striped`, `bordered`, `divided`, `interactive`,
+and virtualized specimens do not automatically become public variant props.
+They remain evidence and comparison material until a consumer-backed contract
+requires each capability.
+
+## Controlled interaction contract
+
+### Selection
+
+- Selection is controlled by the consumer. Table receives the selected row keys
+  and reports the next selected-key collection through its change callback; it
+  does not keep an independent authoritative selection store.
+- A row is selectable only when the consumer exposes it as selectable. Selection
+  controls use native checkboxes with accessible names and a visible
+  `:focus-visible` state.
+- The header select-all control operates on the currently rendered/selectable
+  page only.
+- Selecting all adds the selectable keys visible on the current page to the
+  consumer's existing selected keys. Clearing all removes only those current
+  page keys. Keys belonging to other pages are preserved in both operations.
+- The header state is derived from current-page selectable rows: unchecked when
+  none are selected, mixed when only some are selected, and checked when all
+  current-page selectable rows are selected.
+- Table must not infer that the entire data set is selected, emit a hidden
+  "select all pages" sentinel, fetch other pages, or rewrite keys it cannot see.
+- Bulk actions and action-column content are consumer-provided. Table may
+  expose the current selection boundary to the action surface, but it does not
+  execute business mutations or decide confirmation, retry, or success copy.
+
+### Row activation
+
+- A consumer may provide row activation. The activation target must be
+  keyboard-operable with the same outcome as pointer activation and must expose
+  a visible focus state.
+- Enter and Space activation must not be implemented by turning the entire
+  table into a grid. Arrow-key row navigation, roving focus, and cell editing
+  are outside this first contract.
+- A row action must not conflict with a nested native link, button, checkbox,
+  or other interactive cell control; nested controls retain their native
+  behavior.
+
+### Sorting
+
+- Sorting is controlled: the consumer owns the active sort key and direction,
+  receives the sort-change event, and owns data ordering or server requests.
+- A sortable heading is a native button inside the heading cell. The heading
+  exposes `aria-sort` with the applicable `none`, `ascending`, or `descending`
+  value. The sort icon is decorative and is not the only state cue.
+- Table does not silently sort data, fetch a new page, mutate URL/query state,
+  or fabricate a total while sorting.
+
+## Layout and responsive contract
+
+- `density` is explicit consumer input; Table must not infer density from a
+  parent page or from being rendered inside a data surface.
+- `stickyHeader` and `maxBodyHeight` are layout capabilities. When they create a
+  scroll region, the region must remain usable with keyboard focus and must not
+  create an unnecessary second scrollbar.
+- `minWidth` and column-group composition are consumer-visible layout inputs;
+  intrinsic table sizing remains the default and JavaScript measurement is not
+  required for normal layout.
+- The implementation must remain usable at small, laptop, desktop, and wide
+  widths, with horizontal overflow owned by the table surface when columns
+  cannot fit.
+- Light and dark themes use canonical q1travel tokens. No Web page-local
+  `--ds-*` token becomes a new public Table token.
+
+## Accessibility and state evidence
+
+The component follows the existing native-semantic accessibility bar:
+
+- native table structure and column-heading relationships;
+- native buttons, links, and checkboxes for interactive cells;
+- visible focus for every focusable control;
+- accessible names for select-all, row, and action controls;
+- redundant selected, sorted, loading, empty, and error cues;
+- consumer-owned async announcements and recovery actions where state changes.
+
+The implementation gate must add generated public declarations, a TypeScript
+consumer fixture, package-level markup assertions, and browser evidence for:
+
+1. controlled selection and current-page select-all while preserving off-page
+   keys;
+2. indeterminate and checked header states;
+3. sortable headings and `aria-sort` transitions through native keyboard input;
+4. row activation, nested-control isolation, focus visibility, and disabled
+   rows/controls where applicable;
+5. loading, empty, error, dense, narrow, light, and dark states; and
+6. sticky/max-height behavior without losing focus or introducing an unwanted
+   scroll trap.
+
+The existing Table documentation page and its browser checks prove only the
+page-local specimen. They are not package or consumer evidence for this
+contract.
+
+## Pagination and migration boundary
+
+- `Table` receives the visible data it must render and does not own `page`,
+  `pageSize`, `total`, cursor tokens, query-string state, or data fetching.
+- Dataset pagination is composed with the public `Pagination` component;
+  documentation sequence navigation remains the separate `DocsPagination`
+  boundary.
+- The current-page select-all rule remains valid when the consumer changes
+  pages: off-page selected keys stay in the consumer's controlled collection,
+  while the header state is recalculated from the newly visible page.
+- q1travel-web migration is a separate gate. It may begin only after the
+  package export, generated types, focused tests, published package identity,
+  and consumer adoption have each been independently verified.
+- This contract does not modify q1travel-web, publish the package, migrate a
+  consumer, close #25, or create implementation issues.
+
+## Implementation sequence
+
+`Table core` → `Interaction` → `Layout` → `export/types/tests` → `published
+package verification` → `q1travel-web migration`
+
+Each arrow is a separate acceptance gate. A passing documentation specimen,
+local package build, or source-level assertion does not establish the next gate.

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

@@ -1,6 +1,7 @@
 import { AnchorHTMLAttributes } from 'react';
 import { ButtonHTMLAttributes } from 'react';
 import { ComponentPropsWithoutRef } from 'react';
+import { CSSProperties } from 'react';
 import { FocusEventHandler } from 'react';
 import { HTMLAttributes } from 'react';
 import { InputHTMLAttributes } from 'react';
@@ -12,6 +13,7 @@ import { ReactNode } from 'react';
 import { Ref } from 'react';
 import { RefObject } from 'react';
 import { SelectHTMLAttributes } from 'react';
+import { TableHTMLAttributes } from 'react';
 import { TextareaHTMLAttributes } from 'react';
 
 export declare function addDays(date: Date, amount: number): Date;
@@ -1023,7 +1025,7 @@ export declare type NoteTone = 'info' | 'success' | 'warning' | 'error' | 'secon
 
 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 = {
+export declare type PaginationCommonProps = {
     page: number;
     pageSize?: number;
     onChange: (page: number) => void;
@@ -1359,6 +1361,70 @@ export declare type TabItem = {
     tooltip?: string;
 };
 
+export declare function Table<T>({ data, columns, rowKey, caption, density, stickyHeader, maxBodyHeight, minWidth, colGroup, renderRow, showHeader, sortKey, sortDirection, onSortChange, selection, actions, bulkActions, bulkActionsLabel, rowActivation, className: consumerClassName, style: consumerStyle, ...nativeProps }: TableProps<T>): JSX.Element;
+
+export declare type TableActions<T> = {
+    header: ReactNode;
+    render: (row: T, rowIndex: number) => ReactNode;
+};
+
+export declare type TableColumn<T> = {
+    key: string;
+    header: ReactNode;
+    render: (row: T, rowIndex: number) => ReactNode;
+    sortable?: boolean;
+    sortLabel?: string;
+};
+
+export declare type TableDensity = 'comfortable' | 'compact';
+
+export declare type TableProps<T> = {
+    data: readonly T[];
+    columns: readonly TableColumn<T>[];
+    rowKey: (row: T, rowIndex: number) => TableRowKey;
+    caption?: ReactNode;
+    density?: TableDensity;
+    stickyHeader?: boolean;
+    maxBodyHeight?: CSSProperties['maxHeight'];
+    minWidth?: CSSProperties['minWidth'];
+    colGroup?: ReactNode;
+    renderRow?: (row: T, context: TableRowRenderContext<T>) => ReactNode;
+    showHeader?: boolean;
+    sortKey?: string;
+    sortDirection?: TableSortDirection;
+    onSortChange?: (key: string, direction: TableSortDirection) => void;
+    selection?: TableSelection<T>;
+    actions?: TableActions<T>;
+    bulkActions?: ReactNode;
+    bulkActionsLabel?: string;
+    rowActivation?: TableRowActivation<T>;
+} & Omit<TableHTMLAttributes<HTMLTableElement>, 'children'>;
+
+export declare type TableRowActivation<T> = {
+    getRowLabel: (row: T, rowIndex: number) => string;
+    onActivate: (row: T, rowIndex: number) => void;
+};
+
+export declare type TableRowKey = string | number;
+
+export declare type TableRowRenderContext<T> = {
+    row: T;
+    rowIndex: number;
+    rowKey: TableRowKey;
+    rowProps: TableHTMLAttributes<HTMLTableRowElement>;
+    cells: ReactNode;
+};
+
+export declare type TableSelection<T> = {
+    selectedKeys: readonly TableRowKey[];
+    onSelectionChange: (selectedKeys: TableRowKey[]) => void;
+    getRowLabel: (row: T, rowIndex: number) => string;
+    getRowDisabled?: (row: T, rowIndex: number) => boolean;
+    selectAllLabel?: string;
+};
+
+export declare type TableSortDirection = 'asc' | 'desc';
+
 export declare function Tabs({ tabs, ariaLabel, variant, }: {
     tabs: TabItem[];
     ariaLabel: string;