@q1travel/design-system 0.12.0 → 0.14.0

package/README.md

@@ -12,10 +12,11 @@ q1travel 产品家族的设计权威上游仓，三件事集于一处：`@q1trav
 - Generated mirrors（生成镜像，勿手改）：`public/design.md`、`public/design.dark.md` 由 `scripts/sync-design-contracts.mjs` 从契约源逐字节复制；`public/design.css` 由 `scripts/build-design-css.mjs` 把两份契约 frontmatter 的取值注入 `contracts/design.css` 的类词汇后生成，因而自足、可被独立 HTML 页面直接加载。
 - Runtime tokens：`src/styles/tokens.css`（canonical `--q1-*`，仅 `:root` 与 `:root[data-theme='dark']` 两个扁平 selector）。
 - 发布台账：`contracts/releases/`（仅存于仓库，不进 npm 包）。
+- npm 发布与下游自动更新：[发布操作说明](docs/npm-release.md)。
 
 ## Getting Started
 
-前置要求：Node.js 22+（CI 基线 22）与 npm（依赖锁定在 `package-lock.json`）；运行 `check:browser` 需要本机 Chrome（可用 `CHROME_PATH` 指定）。
+前置要求：Node.js 22+（CI 基线 22）与 npm（依赖锁定在 `package-lock.json`）；运行 `check:browser` 需要本机 Chrome（可用 `CHROME_PATH` 指定）。`check:browser` 在本地与 CI 都默认使用 `--headless=new`，不探测 TTY 或 `DISPLAY`；只有显式设置 `Q1_DESIGN_BROWSER_HEADLESS=false` 才切换到 headed 模式。
 
 ```bash
 npm install

package/bin/q1-design.mjs

@@ -180,7 +180,7 @@ export function findsRawMotionLiteral(lineContent, commentState) {
     // 「用户动作到界面回应完毕」有多久；无限循环按定义不是对输入的响应，它的周期是该组件
     // 自己的节奏（spinner 1.2s、skeleton 1.6s），塞进 120–300ms 只会压坏它，或逼出假 token。
     if (/\binfinite\b/.test(segment)) return false;
-    // 值来自 var() 时不判——`transition: var(--q1-navigation-chevron-transition)` 是合法组件 token。
+    // 值整体来自 var() 时不判——例如 `transition: var(--q1-duration-base)`，静态规则不能展开变量内容。
     const withoutVars = segment.replace(VAR_CALL_PATTERN, '');
     return BARE_DURATION_PATTERN.test(withoutVars) || BARE_EASING_PATTERN.test(withoutVars);
   });

package/contracts/design.dark.md

@@ -378,7 +378,7 @@ These components ship in the package. Compose from this list before writing new
 - SplitButton is a primary action with an adjacent menu whose first entry mirrors it. Do not use it to hide unrelated actions behind a chevron.
 - IconButton requires an accessible name. An icon-only control without one is not deliverable.
 
-**Text fields.** FormField, Label, Input, ClearableInput, SearchInput, Textarea, Select, Fieldset, ErrorMessage.
+**Text fields.** FormField, Label, Input, ClearableInput, SearchInput, VerificationCodeInput, Textarea, Select, Fieldset, ErrorMessage.
 
 - FormField owns the label, help text, and error slot. Do not assemble those three around a bare Input.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
@@ -535,3 +535,5 @@ Before delivery, confirm each of these. They are observable; none of them is a m
 - Nothing scrolls horizontally at the page level.
 
 In this repository, `npm run check` is the full gate; a partial run is not a pass. In consuming repositories, run their design and token gates before reporting completion.
+
+公开 Foundation 集成：`getOverlayCoordinator` 协调 package 与宿主 overlay 的栈序、inert 与滚动锁；契约见 [Overlay Foundation](./overlay-foundation.md#11-o3-公开-host-协调扩展2026-09-08)。

package/contracts/design.md

@@ -378,7 +378,7 @@ These components ship in the package. Compose from this list before writing new
 - SplitButton is a primary action with an adjacent menu whose first entry mirrors it. Do not use it to hide unrelated actions behind a chevron.
 - IconButton requires an accessible name. An icon-only control without one is not deliverable.
 
-**Text fields.** FormField, Label, Input, ClearableInput, SearchInput, Textarea, Select, Fieldset, ErrorMessage.
+**Text fields.** FormField, Label, Input, ClearableInput, SearchInput, VerificationCodeInput, Textarea, Select, Fieldset, ErrorMessage.
 
 - FormField owns the label, help text, and error slot. Do not assemble those three around a bare Input.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
@@ -535,3 +535,5 @@ Before delivery, confirm each of these. They are observable; none of them is a m
 - Nothing scrolls horizontally at the page level.
 
 In this repository, `npm run check` is the full gate; a partial run is not a pass. In consuming repositories, run their design and token gates before reporting completion.
+
+公开 Foundation 集成：`getOverlayCoordinator` 协调 package 与宿主 overlay 的栈序、inert 与滚动锁；契约见 [Overlay Foundation](./overlay-foundation.md#11-o3-公开-host-协调扩展2026-09-08)。

package/contracts/overlay-foundation.md

@@ -242,3 +242,20 @@ D7  q1travel-web adoption/migration
 - [q1travel Token Naming](./token-naming.md)
 - [WAI-ARIA APG: Dialog (Modal) Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
 - 历史范围证据：`docs/superpowers/specs/w2-overlays-familyization-scoping.md`（非当前决策源）
+
+
+## 11. O3 公开 host 协调扩展（2026-09-08）
+
+本节是 O3 要求的独立 public API contract，扩展 v1 的禁止 consumer 注入边界。
+授权范围为 package 实现与 Web 本地构建产物联调；不代表发布或生产采用。
+
+- `getOverlayCoordinator(document?)` 从包主入口导出；同一 Document 返回同一协调器，SSR 无 document 时返回 null。
+- `register({ id, root, blocking = true, getContainer })` 注册一个宿主实例，返回幂等释放函数。id 在整个 document 栈中必须唯一；root 必须属于该 document 且是 body 直接子节点，非法输入抛错。
+- `getSnapshot()` 返回注册顺序 ids 与 blockingCount；`isTopMost(id)` 使用同一实时栈；`subscribe(listener)` 同步通知登记与释放，返回取消订阅函数。快照供即时读取，非 useSyncExternalStore 的缓存快照。
+- 宿主保留渲染、事件、focus trap 与 focus return；Escape、外点、focus trap 必须先检查共享 top-most。Foundation 不替宿主调用关闭回调，也不绕过 dismissable/busy 策略。
+- 所有 package 与宿主 blocking 实例共享唯一 body overflow/paddingRight 快照和计数。宿主必须移除独立 scroll lock、inert 和快捷键阻断计数；最后一个 blocker 释放才恢复原值，非 LIFO 卸载也适用。
+- 活动 root 被显式登记后不作为背景 inert；原有 inert 状态保留。body 后续新增兄弟节点也纳入背景隔离，最终恢复原值。
+- 多 root 临时使用同一 overlay semantic layer，并按各 root 最新登记实例排列 stacking context；宿主负责自身 root 内部顺序。最后一项释放时恢复 root 原有 position/isolation/zIndex，不删除宿主 root。该扩展不允许宿主覆盖 package root 的归属。
+- 宿主每次 open 对应一次登记/释放；改变 blocking 策略应重新登记。idempotent disposer 支持 StrictMode 清理。不同 document 完全隔离。
+
+回归入口：`node --test scripts/check-overlay-coordination.test.mjs`；真实跨 root 的 Escape、焦点、快捷键与滚动锁由 Web consumer 浏览器测试验证。

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

@@ -775,6 +775,14 @@ export declare function ErrorMessage({ label, size, action, children, }: {
 
 export declare type ErrorMessageSize = 'sm' | 'md' | 'lg';
 
+/** A host keeps its own rendering, focus and dismissal policy; Foundation owns shared effects. */
+export declare type ExternalOverlayRegistration = {
+    id: string;
+    root: HTMLElement;
+    blocking?: boolean;
+    getContainer: () => HTMLElement | null;
+};
+
 export declare function Feedback({ label, prompt, placeholder, inline, topics, }: {
     label?: string;
     prompt?: string;
@@ -845,6 +853,9 @@ export declare type GaugeSize = 'xs' | 'sm' | 'md' | 'lg';
 
 export declare type GaugeToneDirection = 'quota' | 'health';
 
+/** One coordinator per document, shared with all package overlays. Null during SSR. */
+export declare function getOverlayCoordinator(doc?: Document | null): OverlayCoordinator | null;
+
 export declare function IconButton({ 'aria-label': canonicalAriaLabel, ariaLabel: legacyAriaLabel, ...rest }: IconButtonProps): JSX.Element;
 
 declare type IconButtonAccessibleName = {
@@ -1169,6 +1180,18 @@ export declare type NoteSize = 'small' | 'default' | 'large';
 
 export declare type NoteTone = 'info' | 'success' | 'warning' | 'error' | 'secondary';
 
+export declare type OverlayCoordinator = {
+    register: (entry: ExternalOverlayRegistration) => () => void;
+    isTopMost: (id: string) => boolean;
+    getSnapshot: () => OverlaySnapshot;
+    subscribe: (listener: () => void) => () => void;
+};
+
+export declare type OverlaySnapshot = {
+    readonly ids: readonly string[];
+    readonly blockingCount: number;
+};
+
 export declare function Pagination({ page, pageSize: pageSizeProp, total, totalPages: totalPagesProp, hasNextPage, onChange, loading, showPageNumbers, summary, pageSizeSlot, prevLabel, nextLabel, compact, className, }: PaginationProps): JSX.Element;
 
 export declare type PaginationCommonProps = {
@@ -1396,7 +1419,7 @@ export declare const Sidebar: typeof SidebarRoot & {
 
 declare function SidebarContent({ className, ...props }: SidebarSlotProps): JSX.Element;
 
-export declare function SidebarDrawer({ 'aria-label': ariaLabel, open, onOpenChange, trigger, header, footer, children, collapseBelow, drawerWidth, variant, }: SidebarDrawerProps): JSX.Element;
+export declare function SidebarDrawer({ 'aria-label': ariaLabel, open, onOpenChange, trigger, header, footer, children, collapseBelow, drawerWidth, variant, dismissOnBackdrop, }: SidebarDrawerProps): JSX.Element;
 
 export declare type SidebarDrawerProps = {
     'aria-label': string;
@@ -1409,6 +1432,7 @@ export declare type SidebarDrawerProps = {
     collapseBelow?: number;
     drawerWidth?: SidebarDrawerWidth;
     variant?: SidebarVariant;
+    dismissOnBackdrop?: boolean;
 };
 
 export declare type SidebarDrawerTriggerProps = {
@@ -1771,6 +1795,33 @@ export declare type UseRadioOptions = {
 
 export declare function useToast(): ToastContextValue;
 
+export declare function VerificationCodeInput({ id, name, value, onValueChange, disabled, readOnly, required, invalid, errorId, size, ref, label, description, error, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': describedBy, }: VerificationCodeInputProps): JSX.Element;
+
+export declare type VerificationCodeInputProps = {
+    id?: string;
+    name?: string;
+    /** 受控的 0–6 位 ASCII 数字字符串；保留前导零。 */
+    value: string;
+    onValueChange: (value: string) => void;
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    invalid?: boolean;
+    errorId?: string;
+    size?: 'md' | 'lg';
+    ref?: Ref<HTMLInputElement>;
+    'aria-describedby'?: string;
+} & ((FieldShellProps & {
+    'aria-label'?: never;
+    'aria-labelledby'?: never;
+}) | (FieldBareProps & ({
+    'aria-label': string;
+    'aria-labelledby'?: never;
+} | {
+    'aria-labelledby': string;
+    'aria-label'?: never;
+})));
+
 export declare function Video({ src, poster, tracks, label, controls, loop, }: VideoProps): JSX.Element;
 
 export declare type VideoProps = {