@q1travel/design-system 0.30.7 → 0.30.9

package/contracts/cascader.md

@@ -0,0 +1,41 @@
+# Cascader
+
+Cascader 在已知层级中选择节点。平面搜索使用 Combobox / MultiCombobox；仅显示路径而不逐层浏览的需求不使用 Cascader。
+
+## 数据和受控选择
+
+`mode` 必填且生命周期内不切换。single 的 value 为 string | null；multiple 为 string[]。onChange 第二参数为完整 CascaderPath 或清除时的 null。value 始终由调用方回写；多选父子独立，新选追加，移除只删该值，无联选、半选或深度限制。
+
+CascaderNode 的 value 为全树稳定唯一非空字符串，label 可重复；禁止循环、重复身份及搜索结果与路径末项不一致。children 非空表示已有子级；hasChildren=true 且 children 为空表示待加载。selectable 默认 true，false 仅禁止提交，仍可浏览；disabled 默认 false，禁止选择、浏览与请求，但可到达以读取状态。
+
+selectedPaths 优先回显末项，再用已加载节点，再回退 value。远端选择保留组件存活期间的路径快照；持久路径由调用方提供，不自动请求祖先。打开时恢复首个已知选值路径；节点更新时保留有效路径，失效截到最近祖先，不改选择。
+
+## 字段与可选省略
+
+query 省略为内部空串；传 query 必须配 onQueryChange。关闭保留查询。searchResults 省略本地检索 label 与完整路径；传入包括 [] 即由调用方接管。IME 组合期间仅维护草稿，结束通知最终文字一次。
+
+label 便捷入口关联真实 trigger，名称优先 aria-labelledby、aria-label、内置 label。省略 label 由调用方提供外部名称。placeholder 默认「请选择…」，searchPlaceholder 默认「搜索选项…」，emptyText 默认「没有匹配项」，自定义内容替换默认文案且仅一个 role=status。required 默认 false，仅提示，不写无效按钮 aria-required、不自动校验。invalid 默认 false，error 隐含 invalid；errorId、内置错误和 aria-describedby 去重合并。
+
+disabled/readOnly 默认 false；只读可聚焦但不能展开、请求、搜索或清除。clearable 默认 false，启用后独立具名按钮清除/移除，不能嵌套触发器。name 每个值输出同名 hidden input，空值无条目，disabled 同步禁用。id/ref 指向真实按钮，className 只到根。onOpenChange 通知每次开闭；无公开 open/defaultOpen。
+
+## 异步与焦点
+
+onBrowse 接收完整路径，loading/retrying 时不重复；省略不请求。branchStates 的空串键用于根，其余为父节点值；searchState 只管非空查询。状态顺序 loading、error、empty、content。error 必带 message/onRetry，可带 retrying；重试用 RegionErrorState inline/polite 保留按钮，加载用 Spinner。成功时仅当焦点仍在待卸载的区域/重试按钮才转移到列表或搜索；已离开不抢焦点。请求、取消、竞态、缓存、合并与分页归调用方。
+
+## Tier A 关联 listbox
+
+采用有名称的关联 listbox 列与非空查询的搜索 combobox，不声称 tree 模型。列名为「第 n 级」，n>1 时追加父路径末项 label；当前列一个 Tab 停靠点，aria-activedescendant 指已挂载稳定 option id。option 的选中和活动分离；aria-posinset/setsize 表达完整集合；无交互子项。listbox 不使用浏览器默认 outline，仅 :focus-visible 显示既有 DS 焦点阴影。有子级与仅浏览通过描述表达，不给 option 添加 tree 的 aria-expanded。
+
+触发器 Enter/Space/Down 打开聚焦搜索，Up 直接到当前列末项。列 Up/Down、Home/End 在本列移动，端点停止；前缀字符跳转。ArrowRight 进入子级，ArrowLeft 返回父项。Enter/Space 提交可选节点，单选关闭回触发器，多选保持；仅浏览节点进入下一级。非空搜索 Up/Down 在结果移动且输入持焦；Enter 提交；Space/Home/End/左右保留文字编辑。Tab/Shift+Tab 正常经过列头分支选择按钮、当前列、重试及 footer，边界关闭离开，不困焦点。Escape 由组件显式回焦有效触发器并只关闭最上层，不清查询和值。组合输入与 keyCode=229 暂停导航、提交及 Escape。
+
+指针（含触屏）点击有子级节点进入下一列；单选可选分支同时提交但保持弹层，叶子提交关闭。多选分支行只浏览，每行行首统一预留 aria-hidden 图形命中区，未选空心框、已选勾选、禁用禁用态、不可选同宽留白；点击图形切换可选节点，叶子行切换。单选不预留。进入可选分支后下一列 listbox 外列头提供 Tab 可达的 DS Button（secondary、sm，前置装饰性空心框/勾选）「选择“<label>”」/「取消选择“<label>”」，click 切换并同步 aria-selected 与按钮名称；窄屏放在返回行下方。键盘行为不变。
+
+多选非空时控件只显示标签，不显示可见数量摘要；标签与移除按钮保持 trigger 兄弟，标签换行、控件随内容增高，trigger 覆盖整个控件，标签文字与空白均可打开；移除/清除按钮层级更高且不打开弹层，全部清除与箭头图形固定右上，标签区域预留两者空间，普通与 coarse 指针下均不重叠。describedby 保留完整数量与路径摘要。弹层名称直接为字段可访问名称，不加前缀，无名兜底「选择」；已选标签列表名为「已选项」。
+
+Popover 为非模态 dialog，无锁滚动或焦点陷阱。footer 独立于列表，激活关闭；打开新层不得覆盖新焦点。外点保留目标焦点。窗口按列和搜索结果独立测量长文本、字体和触摸高度，保留离屏活项，不以截断冒充窗口化。
+
+## 样式和公开边界
+
+公开类名：q1-cascader；__label、__control、__trigger、__placeholder、__tags、__tag、__remove、__popup、__panel、__search、__columns、__column、__list、__option、__copy、__path、__forward、__results、__back、__status、__footer、__error。只使用既有 token，不新增刻度。每列优选 space-10 × 6，高度上限 min(space-10 × 6, 40dvh)；视口低于 space-10 × 12 + space-6 时同一 Popover 单列钻取，有完整父路径和返回，隐藏列带 hidden，SSR 默认单列。亮暗继承 anchor 局部主题。
+
+新增导出 Cascader、CascaderProps、CascaderNode、CascaderPathItem、CascaderPath、CascaderSearchResult、CascaderAsyncState、CascaderBranchStates 与 /components/cascader 文档入口。没有使用端迁移，既有选择器默认行为不变。接入时适配业务规则为标准节点，输出在 onChange 转换；回滚先撤新增调用和路由再撤导出，发布另行授权。

package/contracts/design.dark.md

@@ -175,6 +175,7 @@ semantic-colors:
   auth-text-secondary: "#d1d5db"
   auth-text-muted: "#9ca3af"
   auth-border-strong: "#343943"
+  auth-border-control: "#616b7b"
   auth-surface-card: "#17191d"
   auth-surface-subtle: "#101216"
   auth-surface-input: "#101216"
@@ -489,7 +490,7 @@ These components ship in the package. Compose from this list before writing new
 - FormField positions its visually hidden label and empty live status within its own containing block so an overflowing inline row cannot enlarge the page scroll width.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
 
-**Option fields.** ControlOption, Checkbox, Radio, RadioGroup, Choicebox, Combobox, MultiSelect, MultiCombobox, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
+**Option fields.** ControlOption, Checkbox, Radio, RadioGroup, Choicebox, Combobox, MultiSelect, MultiCombobox, Cascader, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
 
 **Checkbox task completion circle.** `Checkbox` adds `shape?: 'square' | 'circle'` (default square). Circle-only `tone?: 'neutral' | 'info' | 'warning' | 'danger'` defaults to neutral; `size?: 'sm' | 'md'` defaults to sm. 圆形只用于任务与清单的完成场景；表单多选一律用方形。 Native checkbox, ref, bare accessible names and Space activation remain intact; Enter does not toggle. Circle rejects indeterminate with a development warning. `readOnly` remains focusable, exposes aria-disabled and prevents toggles, hover previews and press feedback; completed readonly circles keep a desaturated fill and tick.
 
@@ -671,3 +672,7 @@ In this repository, `npm run check` is the full gate; a partial run is not a pas
 ### 单行控件尺寸
 
 显式 sm / md / lg 的单行控件与 Button 对齐为 32 / 40 / 48px；使用现有 `--q1-space-8`、`--q1-control-height-default` 与 `--q1-space-2`。SearchInput 与 Menu 文字触发器默认 md，FilterChip 默认 sm32，Switch 外框 sm / md / lg 同高 32 / 40 / 48px，默认 md。Calendar 的 size 只控制网格，触发器使用 fieldSize。空或缺省 label 不创建可见标签行，消费方须提供可访问名称。粗指针最小 44px 命中规则保持现有契约。
+
+## Cascader 层级选择
+
+Cascader 用于已知层级中的节点选择，采用关联 listbox + 搜索 combobox，值完全受控、父子独立多选，默认 selectable=true、clearable=false、关闭保留查询。节点可选规则、异步请求与输出转换归调用方。字段、键盘、默认省略、公开类名和加法迁移见 [Cascader 契约](./cascader.md)。无新增 token，既有选择组件默认行为不变。

package/contracts/design.md

@@ -175,6 +175,7 @@ semantic-colors:
   auth-text-secondary: "#273951"
   auth-text-muted: "#64748d"
   auth-border-strong: "#d6dde6"
+  auth-border-control: "#8290a3"
   auth-surface-card: "#ffffff"
   auth-surface-subtle: "#f8fafc"
   auth-surface-input: "#ffffff"
@@ -489,7 +490,7 @@ These components ship in the package. Compose from this list before writing new
 - FormField positions its visually hidden label and empty live status within its own containing block so an overflowing inline row cannot enlarge the page scroll width.
 - Select is for a short, fixed list. Anything searchable, or longer than roughly seven entries, is a Combobox.
 
-**Option fields.** ControlOption, Checkbox, Radio, RadioGroup, Choicebox, Combobox, MultiSelect, MultiCombobox, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
+**Option fields.** ControlOption, Checkbox, Radio, RadioGroup, Choicebox, Combobox, MultiSelect, MultiCombobox, Cascader, Switch, Toggle, ToggleGroup, Slider, RangeSlider.
 
 **Checkbox task completion circle.** `Checkbox` adds `shape?: 'square' | 'circle'` (default square). Circle-only `tone?: 'neutral' | 'info' | 'warning' | 'danger'` defaults to neutral; `size?: 'sm' | 'md'` defaults to sm. 圆形只用于任务与清单的完成场景；表单多选一律用方形。 Native checkbox, ref, bare accessible names and Space activation remain intact; Enter does not toggle. Circle rejects indeterminate with a development warning. `readOnly` remains focusable, exposes aria-disabled and prevents toggles, hover previews and press feedback; completed readonly circles keep a desaturated fill and tick.
 
@@ -671,3 +672,7 @@ In this repository, `npm run check` is the full gate; a partial run is not a pas
 ### 单行控件尺寸
 
 显式 sm / md / lg 的单行控件与 Button 对齐为 32 / 40 / 48px；使用现有 `--q1-space-8`、`--q1-control-height-default` 与 `--q1-space-2`。SearchInput 与 Menu 文字触发器默认 md，FilterChip 默认 sm32，Switch 外框 sm / md / lg 同高 32 / 40 / 48px，默认 md。Calendar 的 size 只控制网格，触发器使用 fieldSize。空或缺省 label 不创建可见标签行，消费方须提供可访问名称。粗指针最小 44px 命中规则保持现有契约。
+
+## Cascader 层级选择
+
+Cascader 用于已知层级中的节点选择，采用关联 listbox + 搜索 combobox，值完全受控、父子独立多选，默认 selectable=true、clearable=false、关闭保留查询。节点可选规则、异步请求与输出转换归调用方。字段、键盘、默认省略、公开类名和加法迁移见 [Cascader 契约](./cascader.md)。无新增 token，既有选择组件默认行为不变。

package/contracts/implementation-map.md

@@ -145,3 +145,7 @@ Accepted 2026-10-08: explicitly sized single-line Button, ButtonLink, Input, Sea
 Owner approved 2026-10-15 (#455): public `RegionErrorState` replaces only a region whose data request failed, while the host keeps its frame (table header, card title, section heading). Props: `title` (required), `description`, `layout` `center` (default; table bodies and large regions, block padding `--q1-space-16` keeps roughly five table rows of height) or `inline` (cards and page sections; the retry button wraps under the description when the component's own container is narrower than 30rem), `headingLevel` 2–6 (default renders `p`, matching EmptyState), `onRetry`, `retrying`, and `live` `polite` (default, `role=status`) or `assertive` (`role=alert`). Accepted 2026-10-25 (#659): `strip` adds `.region-error-state--strip`, a full-width neutral strip with `--q1-color-bg-hover`, `--q1-radius-2`, block padding `--q1-space-2`, inline padding `--q1-space-4`, and minimum block size twice `--q1-space-6`. It shares inline typography and announcements, but its retry always stays inside the right edge without the narrow-container wrap. There is no `size` prop.
 
 The announcement region wraps only the icon, the `q1-sr-only` 「错误：」 prefix, the title and the description, and carries `aria-busy` while `retrying`. The retry Button sits outside that region so its loading status never nests inside another live region. Retry uses Button `loading` (focusable, `aria-disabled`, polite 「正在重试」 status) rather than `busy` (native disabled drops focus); the component stays mounted while retrying, and the visible label swaps 「重试」 to 「正在重试」 (hidden from assistive technology because the loading status already announces it). Icons are rendered internally from the existing icon set (AlertCircle, RotateCcw); no icon is exported. Copy is caller-owned; field errors, 403/404 and backend messages are out of scope. After a successful retry the caller moves focus to the restored content. Existing tokens only; the danger color appears only on the icon.
+
+## Cascader 层级选择
+
+`Cascader`（`src/components/ui/Cascader.tsx`）负责字段及触发器；`cascader/` 的 Types、model、window、Panel 分别负责受控边界、路径与独立选择、测量窗口、关联 listbox 与搜索。复用 Popover/useOverlay、RegionErrorState 和 Spinner；样式来自既有 surface、text、control、space、radius 与 focus token。窄屏同一弹层单列钻取，亮暗继承 anchor。完整约束、可选省略、公开面与回滚见 [Cascader](./cascader.md)。文档入口 `/components/cascader`，不迁移既有选择器。

package/contracts/overlay-foundation.md

@@ -101,8 +101,8 @@ type OverlayRecord = {
 
 #### Modal Escape action mode
 
-- `Modal` 未传 `dismissal` 时 MUST 完整保留既有 `onClose` 与 `dismissable` 行为。
-- `dismissal={{ type: 'escape-action', busy, runAction }}` MUST 与 `onClose` / `dismissable` 互斥；Foundation 只在该 Modal 为 top-most 且 `busy=false` 时消费 Escape，并同步调用一次 `runAction`。
+- `Modal` 未传 `dismissal` 时 MUST 完整保留既有 `onClose` 与 `dismissable` 行为。传统模式可选 `outsideDismiss?: boolean` 默认 true；外点关闭条件 MUST 为 `dismissable && (outsideDismiss ?? true)`，Escape 只受 `dismissable` 控制。`outsideDismiss=false` 保留 Escape 关闭与正常关闭后的触发器回焦，`dismissable=false` 同时禁止 Escape 与外点关闭；省略 `outsideDismiss` 时 DOM、SSR 与交互不变。该属性仅属于 Modal，不改变 Sheet 的 outside pointer=false 策略。
+- `dismissal={{ type: 'escape-action', busy, runAction }}` MUST 与 `onClose` / `dismissable` / `outsideDismiss` 在类型层互斥；Foundation 只在该 Modal 为 top-most 且 `busy=false` 时消费 Escape，并同步调用一次 `runAction`。
 - Foundation MUST 使用即时 command latch 阻止同一 tick 的重复 Escape，并在当前 tick 后独立释放该 latch，不得等待或观察 `busy` cycle；`busy=true` 仍作为独立 gate，不得消费 Escape或重复执行。action mode MUST 忽略 outside pointer、不移动当前焦点，也不把 backdrop 暴露为关闭按钮。
 - 消费方 MUST 让 Escape 与 footer Button 调用同一个同步 command；该 command 自行拥有 Promise、即时 latch、`busy`、错误、polite live-region 与结果焦点。错误 live-region MUST 在 action 开始前以空的 `role=status` / `aria-live=polite` 节点常驻，失败时只更新同一节点文本。Foundation 不 await、不吞掉错误，也不从 `busy` 变化推断 action 的成功或失败。`busy` 期间主操作 MUST 以 `aria-disabled` 与 command guard 阻止重复执行，同时保持可聚焦并留在 Tab 顺序中，不得使用原生 `disabled` 移除焦点。
 - action 失败时消费方保持 Modal 挂载、把 `busy` 还原为 false，并在状态提交后调用该 `escape-action` 的 `controlRef.focusInitialIfTopMost()`；该窄 seam 使用 Foundation registry LIFO 判断 Modal 是否仍为 top-most owner，再恢复既定 initial focus target（否则使用同一 Modal 内的合理 fallback），不得以全局 `[role=dialog]` DOM 顺序近似 stack ownership。若上层 Modal 已接管焦点，底层调用 MUST 为 no-op。action 成功并卸载会话树时 Foundation MUST NOT 强制回焦旧 trigger；新目标页面负责接收焦点。

package/contracts/token-naming.md

@@ -135,7 +135,8 @@ Shipped domain palette (owner-approved 2026-10-13): `auth`, the cool blue-gray p
 | `--q1-color-auth-text-primary` | `#061b31` | `#f3f4f6` | Headings |
 | `--q1-color-auth-text-secondary` | `#273951` | `#d1d5db` | Body copy |
 | `--q1-color-auth-text-muted` | `#64748d` | `#9ca3af` | Supporting notes |
-| `--q1-color-auth-border-strong` | `#d6dde6` | `#343943` | Card and input borders |
+| `--q1-color-auth-border-strong` | `#d6dde6` | `#343943` | Card borders and dividers |
+| `--q1-color-auth-border-control` | `#8290a3` | `#616b7b` | Enabled input and selection control boundaries; at least 3:1 against auth input, card and subtle surfaces |
 | `--q1-color-auth-surface-card` | `#ffffff` | `#17191d` | Card |
 | `--q1-color-auth-surface-subtle` | `#f8fafc` | `#101216` | Preview area |
 | `--q1-color-auth-surface-input` | `#ffffff` | `#101216` | Input background |

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

@@ -433,6 +433,88 @@ declare type CardOwnProps = {
 
 export declare type CardProps = CardAsLink | CardAsContainer;
 
+export declare function Cascader(props: CascaderProps): JSX.Element;
+
+export declare type CascaderAsyncState = {
+    status: 'idle';
+} | {
+    status: 'loading';
+} | {
+    status: 'error';
+    message: string;
+    onRetry: () => void;
+    retrying?: boolean;
+};
+
+export declare type CascaderBranchStates = Readonly<Record<string, CascaderAsyncState>>;
+
+export declare type CascaderNode = {
+    value: string;
+    label: string;
+    children?: CascaderNode[];
+    hasChildren?: boolean;
+    disabled?: boolean;
+    selectable?: boolean;
+};
+
+export declare type CascaderPath = readonly [CascaderPathItem, ...CascaderPathItem[]];
+
+export declare type CascaderPathItem = Pick<CascaderNode, 'value' | 'label'>;
+
+export declare type CascaderProps = CascaderSelectionProps & CascaderQueryProps & {
+    nodes: CascaderNode[];
+    selectedPaths?: readonly CascaderPath[];
+    searchResults?: readonly CascaderSearchResult[];
+    onBrowse?: (path: CascaderPath) => void;
+    branchStates?: CascaderBranchStates;
+    searchState?: CascaderAsyncState;
+    onOpenChange?: (open: boolean) => void;
+    label?: string;
+    placeholder?: string;
+    searchPlaceholder?: string;
+    emptyText?: ReactNode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    invalid?: boolean;
+    errorId?: string;
+    error?: string;
+    clearable?: boolean;
+    footer?: ReactNode;
+    id?: string;
+    name?: string;
+    className?: string;
+    ref?: Ref<HTMLButtonElement>;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+};
+
+declare type CascaderQueryProps = {
+    query: string;
+    onQueryChange: (query: string) => void;
+} | {
+    query?: never;
+    onQueryChange?: (query: string) => void;
+};
+
+export declare type CascaderSearchResult = {
+    value: string;
+    path: CascaderPath;
+    disabled?: boolean;
+    selectable?: boolean;
+};
+
+declare type CascaderSelectionProps = {
+    mode: 'single';
+    value: string | null;
+    onChange: (value: string | null, path: CascaderPath | null) => void;
+} | {
+    mode: 'multiple';
+    value: string[];
+    onChange: (values: string[], changedPath: CascaderPath | null) => void;
+};
+
 export declare function Chart({ data, summary, axisLabels, height, className }: ChartProps): JSX.Element;
 
 export declare type ChartPoint = {
@@ -595,7 +677,7 @@ export declare function CollapsibleBreadcrumb({ items, label, linkComponent }: {
     linkComponent?: LinkComponent;
 }): JSX.Element;
 
-export declare function Combobox({ options, searchPlacement, searchPlaceholder, footer, value, onChange, onSearch, isLoading, placeholder, size, disabled, readOnly, invalid, errorId, error, emptyText, clearable, id, className, name, inputMode, spellCheck, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ref, ...rest }: ComboboxProps): JSX.Element;
+export declare function Combobox({ options, searchPlacement, searchPlaceholder, footer, value, onChange, onSearch, isLoading, placeholder, size, required, disabled, readOnly, invalid, errorId, error, emptyText, clearable, id, className, name, inputMode, spellCheck, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, ref, ...rest }: ComboboxProps): JSX.Element;
 
 export declare type ComboboxOption = {
     /** 禁止空字符串（与「未选」的受控空值歧义，adapter 层保证）。 */
@@ -633,6 +715,7 @@ export declare type ComboboxProps = {
     placeholder?: string;
     /** 家族刻度 sm32/md40/lg48（与 Input/Select/Button 同一体系）。 */
     size?: ComboboxSize;
+    required?: boolean;
     disabled?: boolean;
     /** 值只读：不可输入、不展开列表。 */
     readOnly?: boolean;
@@ -1612,6 +1695,7 @@ declare type ModalEscapeActionProps = {
     dismissal: ModalDismissal;
     onClose?: never;
     dismissable?: never;
+    outsideDismiss?: never;
 };
 
 export declare function ModalInset({ children }: {
@@ -1622,6 +1706,8 @@ declare type ModalLegacyDismissalProps = {
     dismissal?: never;
     onClose: () => void;
     dismissable?: boolean;
+    /** 是否允许外点关闭；默认 true，且仅在 dismissable 允许时生效。 */
+    outsideDismiss?: boolean;
 };
 
 export declare type ModalProps = ModalBaseProps & (ModalLegacyDismissalProps | ModalEscapeActionProps);