@q1travel/design-system 0.10.0 → 0.11.0

package/README.md

@@ -60,4 +60,4 @@ docs/  review/         架构骨架、agent 规范、历史决策记录
 - **AI Agent 必须遵循根目录 `AGENTS.md`**（Claude Code 与 Codex 共用的 canonical 入口：命令速查、红线约束、工作闭环与知识索引）；`CLAUDE.md` 仅为其薄包装。
 - `docs/architecture.md` — 双构建管线、契约生成与下游消费模型、发布溯源链路。
 - `docs/adr/template.md` — 新 ADR 从此模板开始；早期已接受决策存于 `review/decision-log/`。
-- 下游消费方式：安装 `@q1travel/design-system` 后 import 组件与 `style.css` / `tokens.css`；`npx q1-design sync` 把包内 skill 与契约物化为只读缓存，`q1-design verify` 校验缓存未被改动，`q1-design lint` 执行 `Q1-DS-*` 机械规则；`q1-design ls` 列出随包组件，`q1-design doc <组件名>` 打印其公共 API（两者现推自随包的 `.d.ts`，不另存清单）。
+- 下游消费方式：安装 `@q1travel/design-system` 后 import 组件与 `style.css` / `tokens.css`；`npx q1-design sync` 把包内 skill 与契约物化为只读缓存，`q1-design verify` 校验缓存未被改动，`q1-design lint` 执行 `Q1-DS-*` 机械规则；`q1-design ls` 列出随包组件，`q1-design doc <组件名>` 打印其公共 API（两者现推自随包的 `.d.ts`，不另存清单）；`q1-design overrides` 统计并分类消费方对组件外观的覆写。

package/bin/q1-design.mjs

@@ -896,8 +896,154 @@ function runDoc(consumerRootDir, requestedName) {
   }
 }
 
+// —— overrides ——
+// 逃生舱口的可见化。Kumo 的做法是把这个 prop 叫 DANGEROUS_className，让每次绕过都自带
+// 羞耻感。本库不照搬，因为实测数据不支持：q1travel-web 里 814 处组件使用中 223 处传了
+// className（27%）。当四分之一的调用都在用它，它已经是事实上的 API——给常态路径起个
+// 羞耻的名字，只会训练出对警告的免疫，那比没有警告更糟；何况改名要迁 227 处调用点。
+//
+// 真正缺的不是羞耻感，是**知道自己在哪里被绕过、绕过去做什么**。所以做成测量命令而不是
+// pass/fail 规则：lint 只看得到 JSX，分不出「加个左边距」和「把按钮从头重画」——那要去
+// 读消费方 CSS 里那个类的内容。这条命令做的正是这件事。
+//
+// 不进 lint 的第二个理由：覆写布局是正当的，规则拦不住也不该拦。一条会把正当用法一起
+// 报红的规则，最后会被整体关掉，连同它本来能抓住的东西。
+
+// 只动外观的属性：这些出现即意味着「在重画组件」，而不是「在摆放组件」。
+const SKIN_PROPERTIES = new Set([
+  'background', 'background-color', 'background-image', 'border', 'border-color',
+  'border-radius', 'border-width', 'border-style', 'color', 'box-shadow',
+  'font-size', 'font-weight', 'outline', 'opacity',
+]);
+// 只摆位置的属性：这些是消费方的正当需求，组件本就不该管。
+const BOX_PROPERTIES = new Set([
+  'margin', 'margin-top', 'margin-bottom', 'margin-left', 'margin-right',
+  'margin-block', 'margin-inline', 'width', 'max-width', 'min-width',
+  'flex', 'flex-grow', 'flex-shrink', 'grid-area', 'grid-column', 'grid-row',
+  'align-self', 'justify-self', 'order', 'position', 'top', 'left', 'right', 'bottom',
+]);
+
+const OVERRIDE_SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
+
+// 消费仓常在自己内部再导出一层（q1travel-web 的 src/components/ui/index.js 就是
+// `export { Button } from "@q1travel/design-system"`，173 个文件走这条路，只有 64 个直接导入）。
+// 只认包名会漏掉绝大多数调用点，所以额外接受调用方声明的再导出路径。
+export function collectDesignSystemComponents(sourceText, reexportPaths = []) {
+  const names = new Set();
+  const sourcePatterns = [PACKAGE_NAME, ...reexportPaths].map((path) =>
+    path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
+  );
+  const importPattern = new RegExp(
+    `import\\s*\\{([^{}]*?)\\}\\s*from\\s*["'](?:${sourcePatterns.join('|')})["']`,
+    'gs',
+  );
+  for (const match of sourceText.matchAll(importPattern)) {
+    for (const part of match[1].split(',')) {
+      const name = part.replace(/\btype\b/, '').trim().split(/\s+as\s+/).pop()?.trim();
+      if (name && /^[A-Z][A-Za-z0-9_]*$/.test(name)) names.add(name);
+    }
+  }
+  return names;
+}
+
+// `<Button ... className={cx('a', 'b')}>` → ['a','b']。取标签内 400 字符窗口：
+// 再长的标签里出现的 className 多半属于嵌套元素，算进来会虚报。
+export function collectOverrideClassNames(sourceText, componentNames) {
+  const found = [];
+  for (const name of componentNames) {
+    const pattern = new RegExp(`<${name}\\b[^>]{0,400}?className=(\\{[^}]*\\}|"[^"]*"|'[^']*')`, 'gs');
+    for (const match of sourceText.matchAll(pattern)) {
+      for (const token of match[1].matchAll(/[A-Za-z][\w-]*/g)) {
+        const value = token[0];
+        if (['cx', 'clsx', 'classNames', 'undefined', 'true', 'false', 'null'].includes(value)) continue;
+        found.push({ component: name, className: value });
+      }
+    }
+  }
+  return found;
+}
+
+export function classifyOverride(className, cssText) {
+  const escaped = className.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const bodies = [...cssText.matchAll(new RegExp(`\\.${escaped}\\b[^{]*\\{([^}]*)\\}`, 'gs'))];
+  if (bodies.length === 0) return 'undefined-in-css';
+  const properties = new Set();
+  for (const body of bodies) {
+    for (const declaration of body[1].split(';')) {
+      const [property] = declaration.split(':');
+      if (property) properties.add(property.trim());
+    }
+  }
+  for (const property of properties) if (SKIN_PROPERTIES.has(property)) return 'skin';
+  for (const property of properties) if (BOX_PROPERTIES.has(property)) return 'box';
+  return 'other';
+}
+
+function runOverrides(consumerRootDir, inputPaths) {
+  const targets = collectLintTargetFiles(inputPaths.length > 0 ? inputPaths : ['src'], consumerRootDir);
+  let cssText = '';
+  const sources = [];
+  for (const file of targets) {
+    const text = readFileSync(file, 'utf8');
+    if (extname(file) === '.css') cssText += `\n${text}`;
+    else if (OVERRIDE_SOURCE_EXTENSIONS.has(extname(file))) sources.push(text);
+  }
+
+  // 自动发现再导出出口：仓内任何 `export { X } from '@q1travel/design-system'` 的模块，
+  // 它的导入路径同样是设计系统的调用点。不自动发现的话，用了再导出的仓库会得到一个
+  // 看起来很干净、实则漏掉大半调用点的报告——那比没有报告更误导。
+  const reexportPaths = [];
+  for (const file of targets) {
+    if (!OVERRIDE_SOURCE_EXTENSIONS.has(extname(file))) continue;
+    const text = readFileSync(file, 'utf8');
+    if (!new RegExp(`export\\s*\\{[^{}]*\\}\\s*from\\s*["']${PACKAGE_NAME}["']`).test(text)) continue;
+    const relative_ = toPosixPath(relative(consumerRootDir, file)).replace(/\/index\.(t|j)sx?$/, '').replace(/\.(t|j)sx?$/, '');
+    reexportPaths.push(relative_, `@/${relative_.replace(/^src\//, '')}`, `~/${relative_.replace(/^src\//, '')}`);
+  }
+
+  const overrides = [];
+  for (const text of sources) {
+    const components = collectDesignSystemComponents(text, reexportPaths);
+    if (components.size === 0) continue;
+    overrides.push(...collectOverrideClassNames(text, components));
+  }
+
+  if (overrides.length === 0) {
+    console.log('[q1-design] overrides: 未发现对设计系统组件的 className 覆写。');
+    return;
+  }
+
+  const buckets = { skin: 0, box: 0, other: 0, 'undefined-in-css': 0 };
+  const perClass = new Map();
+  for (const { component, className } of overrides) {
+    const kind = classifyOverride(className, cssText);
+    buckets[kind] += 1;
+    const key = `${kind}|${component}|${className}`;
+    perClass.set(key, (perClass.get(key) ?? 0) + 1);
+  }
+
+  console.log(`[q1-design] overrides: 共 ${overrides.length} 处`);
+  console.log(`  重画外观 (skin)      ${buckets.skin}`);
+  console.log(`  仅布局   (box)       ${buckets.box}`);
+  console.log(`  其它属性             ${buckets.other}`);
+  console.log(`  CSS 中未找到定义     ${buckets['undefined-in-css']}`);
+  const top = [...perClass.entries()]
+    .filter(([key]) => key.startsWith('skin|'))
+    .sort((left, right) => right[1] - left[1])
+    .slice(0, 10);
+  if (top.length > 0) {
+    console.log('\n重画外观的覆写 Top:');
+    for (const [key, count] of top) {
+      const [, component, className] = key.split('|');
+      console.log(`  ${String(count).padStart(3)}×  <${component} className="${className}">`);
+    }
+    console.log('\n「重画外观」意味着组件缺一档能力，或调用点该换一档现有 variant。');
+    console.log('「仅布局」是正当用法，组件本就不该管间距与排布。');
+  }
+}
+
 function printUsage() {
-  console.error('Usage: q1-design <ls|doc|sync|verify|lint|eval>');
+  console.error('Usage: q1-design <ls|doc|sync|verify|lint|eval|overrides>');
   console.error('  ls              列出随包发布的组件与 hook');
   console.error('  doc <组件名>     打印该组件的公共 API（函数签名 + 同名前缀的类型）');
   console.error(
@@ -907,6 +1053,9 @@ function printUsage() {
     '  lint --diff <base-ref> [路径...]  只扫相对 base-ref 有改动的文件（存量重的仓库用它当增量门禁）',
   );
   console.error('  eval            对 tooling/scripts/evals 的 fixtures 跑 before/after 断言');
+  console.error(
+    '  overrides [路径...]  统计对设计系统组件的 className 覆写，并按「重画外观 / 仅布局」分类',
+  );
 }
 
 // 直跑守卫（与 scripts/ci-path-filter.mjs 同款）：被 import 时只暴露纯函数，不执行 CLI，
@@ -941,6 +1090,8 @@ if (isDirectRun) {
     runLint(args.length > 0 ? args : ['src'], consumerRootDir, diffBaseRef);
   } else if (subcommand === 'eval') {
     runEval();
+  } else if (subcommand === 'overrides') {
+    runOverrides(consumerRootDir, process.argv.slice(3));
   } else {
     printUsage();
     process.exit(1);

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

@@ -18,6 +18,16 @@ import { TextareaHTMLAttributes } from 'react';
 
 export declare function addDays(date: Date, amount: number): Date;
 
+export declare function AuthCard({ title, description, action, className }: AuthCardProps): JSX.Element;
+
+/** Focused presentational card for account entry and connection flows. */
+export declare interface AuthCardProps {
+    title: ReactNode;
+    description: ReactNode;
+    action?: ReactNode;
+    className?: string;
+}
+
 export declare function Avatar({ title, src, letter, glyph, placeholder, icon, iconColor, size, className }: AvatarProps): JSX.Element;
 
 export declare function AvatarGroup({ members, label, size, limit, overlap, reverse, className, }: {
@@ -57,7 +67,7 @@ export declare type AvatarProps = {
     className?: string;
 };
 
-declare type Axis = 'vertical' | 'horizontal' | 'free';
+export declare type Axis = 'vertical' | 'horizontal' | 'free';
 
 export declare function Badge({ tone, subtle, quiet, inverted, size, icon, count, title, className, children, ...rest }: BadgeProps): JSX.Element;
 
@@ -111,7 +121,7 @@ export declare type BannerProps = {
 
 export declare type BannerTone = 'neutral' | 'info' | 'success' | 'warning' | 'danger';
 
-declare type BannerVariant = 'default' | 'success' | 'warning' | 'error';
+export declare type BannerVariant = 'default' | 'success' | 'warning' | 'error';
 
 export declare function Book({ title, variant, color, bandColor, textColor, icon, illustration, textured, width, className, style, ...rest }: BookProps): JSX.Element;
 
@@ -133,7 +143,7 @@ export declare type BookProps = {
     /** 细密交叉纹理（自有配方）；只提供单一纹理样式，未做多纹理体系（记 non-goal）。仅用于主视觉，成排书架勿用。 */
     textured?: boolean;
     /** 数字按 px；字符串原样透传（如 clamp(...) 做响应式宽度）。内部排版随宽度等比缩放。
-     *  width 是唯一尺寸入口：用 style.width 改宽会与内部缩放脱节。 */
+     * width 是唯一尺寸入口：用 style.width 改宽会与内部缩放脱节。 */
     width?: number | string;
 } & Omit<HTMLAttributes<HTMLDivElement>, 'children'>;
 
@@ -143,7 +153,7 @@ export declare function Breadcrumb({ items, label, type, }: {
     type?: 'text' | 'menu';
 }): JSX.Element;
 
-declare type BreadcrumbCrumb = {
+export declare type BreadcrumbCrumb = {
     label: string;
     href?: string;
     icon?: ReactNode;
@@ -202,6 +212,14 @@ declare type ButtonBaseProps = {
     circle?: boolean;
     /** 药丸形（full radius）+ 柔和抬起阴影，营销页/落地页文字 CTA 用。与 circle 互斥。 */
     rounded?: boolean;
+    /**
+     * 双态按钮的「当前已按下/已选中」态：分段控件、筛选器、视图切换里那个当前项。
+     * 它表达状态，不是强调层级，因此与 variant 正交——任何 variant 都可以处于选中态。
+     *
+     * 同时置 `aria-pressed`。视觉与语义在这里必须同源：只画视觉会让读屏用户完全看不到
+     * 选中状态，而这正是消费方手写覆写时普遍漏掉的一半。
+     */
+    selected?: boolean;
     /** 载入态：禁点 + 保留可聚焦 + spinner 的 role=status 播报；不改变控件尺寸。 */
     loading?: boolean;
     /** loading 时 role=status 播报的文案，默认"加载中…"；仅供屏幕阅读器，不影响可见文案。 */
@@ -215,9 +233,9 @@ declare type ButtonBaseProps = {
     shortcut?: string;
     className?: string;
     children?: ReactNode;
-    /** 文字前置图标槽（对齐外部参考 prefix）；14–16px、currentColor，装饰性（自带 aria-hidden）。loading 时被 spinner 接管。 */
+    /** 文字前置图标槽；14–16px、currentColor，装饰性（自带 aria-hidden）。loading 时被 spinner 接管。 */
     prefix?: ReactNode;
-    /** 文字后置图标槽（对齐外部参考 suffix），同上。 */
+    /** 文字后置图标槽，同上。 */
     suffix?: ReactNode;
     'aria-label'?: string;
     /**
@@ -248,7 +266,7 @@ export declare type ButtonLinkProps = Omit<ButtonBaseProps, 'type'> & {
     ref?: Ref<HTMLAnchorElement>;
 };
 
-declare type ButtonProps = ButtonBaseProps & Omit<ComponentPropsWithoutRef<'button'>, keyof ButtonBaseProps> & {
+export declare type ButtonProps = ButtonBaseProps & Omit<ComponentPropsWithoutRef<'button'>, keyof ButtonBaseProps> & {
     [dataAttribute: `data-${string}`]: string | number | boolean | null | undefined;
     /** 供 focus 管理、测量、浮层定位等场景使用。 */
     ref?: Ref<HTMLButtonElement>;
@@ -306,14 +324,44 @@ declare type CardOwnProps = {
 
 export declare type CardProps = CardAsLink | CardAsContainer;
 
-export declare function Checkbox({ ...props }: ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & NativeInputProps): JSX.Element;
+export declare function Chart({ data, summary, axisLabels, height, className }: ChartProps): JSX.Element;
+
+export declare type ChartPoint = {
+    /** 该点的横轴标签（日期、类目名…）。用于轴标签展示。 */
+    label: string;
+    value: number;
+};
+
+export declare type ChartProps = {
+    data: readonly ChartPoint[];
+    /**
+     * 读屏摘要，必填。
+     *
+     * 折线本身对读屏是不可读的——没有摘要，这张图对辅助技术等于不存在。设为必填而不是
+     * 可选，是因为可选的可访问性参数在实践中等于不存在：赶工时第一个被省掉的就是它。
+     * 内容应当是这张图在说什么，例如「销售趋势，近 7 天，累计 1,024 单」。
+     */
+    summary: string;
+    /** 轴标签：两端 / 两端加中点 / 不显示。轴标签对读屏隐藏——摘要里已经说过了。 */
+    axisLabels?: 'ends' | 'ends-and-middle' | false;
+    /** 绘图区高度（px），默认 64。宽度始终撑满容器。 */
+    height?: number;
+    className?: string;
+};
+
+export declare function Checkbox({ ...props }: CheckboxProps): JSX.Element;
 
 declare type CheckboxOnlyProps = {
     /** 半选：视觉态而非第三个值，由父级逻辑驱动（如"部分子项已选"）。AT 读作 mixed。 */
     indeterminate?: boolean;
 };
 
-export declare function Choicebox({ type, label, description, extra, className, ...rest }: ChoiceboxOwnProps & NativeInputProps_2): JSX.Element;
+/** Checkbox 的完整 props。消费方包一层时用它标注，无需知道内部由哪几块组合而成。 */
+export declare type CheckboxProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & ControlOptionNativeInputProps;
+
+export declare function Choicebox({ type, label, description, extra, className, ...rest }: ChoiceboxProps): JSX.Element;
+
+declare type ChoiceboxNativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>;
 
 declare type ChoiceboxOwnProps = {
     type: 'radio' | 'checkbox';
@@ -324,9 +372,12 @@ declare type ChoiceboxOwnProps = {
     extra?: ReactNode;
 };
 
+/** Choicebox 的完整 props。 */
+export declare type ChoiceboxProps = ChoiceboxOwnProps & ChoiceboxNativeInputProps;
+
 export declare function ClearableInput({ id, placeholder, defaultValue, disabled, kbdHint, onClear, ariaLabel, }: ClearableInputProps): JSX.Element;
 
-declare type ClearableInputProps = {
+export declare type ClearableInputProps = {
     id: string;
     placeholder?: string;
     defaultValue?: string;
@@ -336,7 +387,7 @@ declare type ClearableInputProps = {
     /** 清空（点击清除按钮或按 Esc）时回调，用于联动外部状态。 */
     onClear?: () => void;
     /** 无可见 label 时的可访问名。有可见 label（FormField 组合）时勿再传——aria-label 会覆盖
-     *  可见标签成为可访问名，视觉与播报分叉（WCAG 2.5.3 Label in Name）。 */
+     * 可见标签成为可访问名，视觉与播报分叉（WCAG 2.5.3 Label in Name）。 */
     ariaLabel?: string;
 };
 
@@ -362,7 +413,7 @@ export declare type CodeBlockLine = {
     state?: 'highlight' | 'added' | 'removed';
 };
 
-declare type CodeBlockProps = CodeBlockBaseProps & ({
+export declare type CodeBlockProps = CodeBlockBaseProps & ({
     filename?: string;
     lines: CodeBlockLine[];
     tabs?: undefined;
@@ -425,7 +476,7 @@ export declare type ComboboxOption = {
     suffix?: ReactNode;
 };
 
-declare type ComboboxProps = {
+export declare type ComboboxProps = {
     /** 唯一 shape，后端字段在 adapter 层转换。 */
     options: ComboboxOption[];
     /** 受控选中值；'' = 未选。 */
@@ -479,7 +530,7 @@ export declare type CommandMenuItem = {
     suffix?: ReactNode;
 };
 
-declare type CommandMenuProps = {
+export declare type CommandMenuProps = {
     sections: CommandMenuSection[];
     triggerLabel?: string;
     /** 绑定全局 ⌘K（macOS）/ Ctrl+K 打开。 */
@@ -498,7 +549,7 @@ export declare type ContextCardAlign = 'start' | 'center' | 'end';
 
 export declare type ContextCardPlacement = 'top' | 'bottom' | 'left' | 'right';
 
-declare type ContextCardProps = {
+export declare type ContextCardProps = {
     name: string;
     identity: string;
     rows: [string, string][];
@@ -602,9 +653,9 @@ export declare type ContextSwitcherSearch = {
     noResults: ContextSwitcherEmptyState;
 };
 
-export declare function ControlOption({ id, label, description, error, indeterminate, ref, type, ...rest }: ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & {
-    type: 'checkbox' | 'radio';
-} & NativeInputProps): JSX.Element;
+export declare function ControlOption({ id, label, description, error, indeterminate, ref, type, ...rest }: ControlOptionProps): JSX.Element;
+
+declare type ControlOptionNativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'type'>;
 
 declare type ControlOptionOwnProps = {
     /** 缺省走 useId；显式传入时行为同现状（specimen/测试可寻址）。 */
@@ -613,6 +664,11 @@ declare type ControlOptionOwnProps = {
     ref?: Ref<HTMLInputElement>;
 };
 
+/** ControlOption 的完整 props（Checkbox / Radio 的共同底座，须显式给 type）。 */
+export declare type ControlOptionProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & CheckboxOnlyProps & {
+    type: 'checkbox' | 'radio';
+} & ControlOptionNativeInputProps;
+
 export declare function CopyButton({ value, label, successMessage, size, className, }: {
     value: string;
     label: string;
@@ -778,9 +834,9 @@ export declare function Gauge({ value, size, showValue, tone, toneDirection, lab
     indeterminate?: boolean;
 }): JSX.Element;
 
-declare type GaugeSize = 'xs' | 'sm' | 'md' | 'lg';
+export declare type GaugeSize = 'xs' | 'sm' | 'md' | 'lg';
 
-declare type GaugeToneDirection = 'quota' | 'health';
+export declare type GaugeToneDirection = 'quota' | 'health';
 
 export declare function IconButton({ 'aria-label': canonicalAriaLabel, ariaLabel: legacyAriaLabel, ...rest }: IconButtonProps): JSX.Element;
 
@@ -817,7 +873,7 @@ export declare type IconButtonProps = IconButtonAccessibleName & IconButtonBaseP
     ref?: Ref<HTMLButtonElement>;
 };
 
-export declare function Input({ id, label, description, error, invalid, errorId, ref, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, ...rest }: {
+export declare function Input({ id, label, description, error, invalid, errorId, ref, prefix, suffix, prefixStyling, suffixStyling, rounded, wide, size, className, revealable, revealed, onRevealedChange, revealLabel, hideLabel, ...rest }: {
     /** 可选：未传时内部 useId 兜底（对齐 Combobox）；显式传入时行为同 0.3.0。 */
     id?: string;
     /** 置 aria-invalid 的业务校验态，不渲染文案；与壳模式 error 并轨（invalid || Boolean(error)）。 */
@@ -832,6 +888,24 @@ export declare function Input({ id, label, description, error, invalid, errorId,
     prefixStyling?: boolean;
     /** 置 false 去掉后缀的灰块底色与分隔线。 */
     suffixStyling?: boolean;
+    /**
+     * 遮罩输入：渲染 type="password"，并在后缀槽给出显隐切换。
+     *
+     * 名字说的是能力（可揭示）而不是数据分类——后者由 type="password" 表达。
+     *
+     * 存在的理由不是「少写几行」，而是三个每次手写都要重新答对的细节：切换按钮的可访问名
+     * 必须随状态变化（否则读屏用户不知道当前是遮罩还是明文）；它必须 type="button"
+     * （否则在表单里会触发提交）；图标不该在每个消费方各画一遍。
+     */
+    revealable?: boolean;
+    /** 受控显隐。不传则组件自持状态。 */
+    revealed?: boolean;
+    /** 受控显隐的变更回调；非受控时同样触发，供业务侧埋点。 */
+    onRevealedChange?: (revealed: boolean) => void;
+    /** 遮罩态下切换按钮的可访问名，默认「显示内容」。密码场景建议传「显示密码」。 */
+    revealLabel?: string;
+    /** 明文态下切换按钮的可访问名，默认「隐藏内容」。 */
+    hideLabel?: string;
     /** 药丸形全圆角外框（9999px 级 pill 半径）。 */
     rounded?: boolean;
     wide?: boolean;
@@ -850,7 +924,7 @@ export declare type JsonViewProps = {
     /** 初始折叠深度：0 表示只展开根，1 表示展开一层；缺省全部展开。 */
     collapsedDepth?: number;
     /** 需要强调的键。`a.b` 形式按完整路径精确匹配；裸键名（如 `status`）在任意深度命中，
-     *  用于「把所有 status 字段都标出来」这类排查。两种写法可混用。 */
+     * 用于「把所有 status 字段都标出来」这类排查。两种写法可混用。 */
     highlight?: string[];
     /** 嵌入模式：去掉外框、背景与内边距，由宿主容器决定表面。 */
     embedded?: boolean;
@@ -886,12 +960,31 @@ export declare function Label({ htmlFor, required, children, }: {
     children: string;
 }): JSX.Element;
 
+export declare function Link({ href, tone, external, className, children, ref, ...rest }: LinkProps): JSX.Element;
+
+export declare type LinkProps = {
+    /** 目标地址。省略时渲染为不可点的当前项文本（例：面包屑末节、已停用的外链）。 */
+    href?: string;
+    tone?: LinkTone;
+    /**
+     * 站外链接：追加一枚外链图标，并补 rel="noopener noreferrer"。
+     *
+     * 图标不是装饰——它是「点下去会离开当前上下文」的预告。省掉它，用户要到新标签页
+     * 打开之后才知道自己被带走了。
+     */
+    external?: boolean;
+    ref?: Ref<HTMLAnchorElement>;
+    children?: ReactNode;
+} & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>;
+
+export declare type LinkTone = 'default' | 'muted';
+
 export declare function LoadingDots({ label, size }: {
     label?: string;
     size?: LoadingDotsSize;
 }): JSX.Element;
 
-declare type LoadingDotsSize = 'sm' | 'md' | 'lg' | number;
+export declare type LoadingDotsSize = 'sm' | 'md' | 'lg' | number;
 
 export declare function LoadMoreButton({ loading, noGap, noBorderRadius, onClick, children, }: {
     loading?: boolean;
@@ -986,10 +1079,6 @@ export declare function MultiSelect({ options, defaultSelected, placeholder, onC
     onChange?: (next: string[]) => void;
 }): JSX.Element;
 
-declare type NativeInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'id' | 'type'>;
-
-declare type NativeInputProps_2 = Omit<InputHTMLAttributes<HTMLInputElement>, 'type'>;
-
 export declare function Navigation({ className, orientation, ...props }: NavigationProps): JSX.Element;
 
 export declare function NavigationGroup({ label, icon, expanded, defaultExpanded, onExpandedChange, children, }: NavigationGroupProps): JSX.Element;
@@ -1069,7 +1158,7 @@ export declare function Note({ tone, size, filled, disabled, label, action, chil
     children: ReactNode;
 }): JSX.Element;
 
-declare type NoteSize = 'small' | 'default' | 'large';
+export declare type NoteSize = 'small' | 'default' | 'large';
 
 export declare type NoteTone = 'info' | 'success' | 'warning' | 'error' | 'secondary';
 
@@ -1131,7 +1220,7 @@ export declare function Progress({ value, max, tone, slim, stops, label, }: {
     label: string;
 }): JSX.Element;
 
-declare type ProgressStop = number | {
+export declare type ProgressStop = number | {
     at: number;
     label?: string;
 };
@@ -1142,7 +1231,10 @@ export declare function ProjectBanner({ variant, message, cta }: {
     cta: string;
 }): JSX.Element;
 
-export declare function Radio({ ...props }: ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & NativeInputProps): JSX.Element;
+export declare function Radio({ ...props }: RadioProps): JSX.Element;
+
+/** Radio 的完整 props。 */
+export declare type RadioProps = ControlOptionOwnProps & (FieldShellProps | FieldBareProps) & ControlOptionNativeInputProps;
 
 export declare function RangeField({ layout, trigger, size, minValue, maxValue, pinnedTimezone, today, value, onChange, }: {
     layout?: PopoverLayout;
@@ -1340,7 +1432,7 @@ export declare function Snippet({ text, prompt, inverted, tone, copyText, onCopy
     onCopy?: () => void;
 }): JSX.Element;
 
-declare type SnippetTone = 'info' | 'danger' | 'warning';
+export declare type SnippetTone = 'info' | 'danger' | 'warning';
 
 export declare function Spinner({ size, tone, label, }: {
     size?: SpinnerSize;
@@ -1490,7 +1582,10 @@ export declare function Tabs({ tabs, ariaLabel, variant, }: {
     variant?: 'default' | 'secondary';
 }): JSX.Element | null;
 
-export declare function Textarea({ id, label, description, error, invalid, errorId, ref, wide, size, className, maxLength, onInput, ...rest }: {
+export declare function Textarea({ id, label, description, error, invalid, errorId, ref, wide, size, className, maxLength, onInput, ...rest }: TextareaProps): JSX.Element;
+
+/** Textarea 的完整 props。消费方包一层时用它标注，无需知道内部由哪几块组合而成。 */
+export declare type TextareaProps = {
     /** 缺省走 useId；显式传入时行为同现状（specimen/测试可寻址）。 */
     id?: string;
     /** 业务校验模型（主）：置 aria-invalid；文案由业务层经 errorId 关联，组件不渲染。 */
@@ -1501,7 +1596,7 @@ export declare function Textarea({ id, label, description, error, invalid, error
     ref?: Ref<HTMLTextAreaElement>;
     wide?: boolean;
     size?: FieldSize;
-} & (FieldShellProps | FieldBareProps) & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'>): JSX.Element;
+} & (FieldShellProps | FieldBareProps) & Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'id'>;
 
 export declare function TextWithCopyButton({ text, copyValue, successMessage, size, }: {
     text: string;
@@ -1515,7 +1610,7 @@ export declare function ThemeSwitcher({ small, disabled }: {
     disabled?: boolean;
 }): JSX.Element;
 
-declare type ThresholdTone = 'primary' | 'success' | 'warning' | 'danger';
+export declare type ThresholdTone = 'primary' | 'success' | 'warning' | 'danger';
 
 declare type ToastContextValue = {
     push: (toast: ToastOptions) => void;
@@ -1559,6 +1654,24 @@ export declare function Toggle({ checked, defaultOn, onChange, disabled, size, o
 
 export declare type ToggleSize = 'sm' | 'md' | 'lg';
 
+export declare function Toolbar({ 'aria-label': ariaLabel, orientation, children, className, }: ToolbarProps): JSX.Element;
+
+export declare type ToolbarOrientation = 'horizontal' | 'vertical';
+
+export declare type ToolbarProps = {
+    /**
+     * 可访问名，必填。
+     *
+     * 一个没有名字的工具栏在读屏的地标/控件列表里是「toolbar」四个字，用户无从判断
+     * 这是哪一组操作。页面上出现第二个工具栏时，两者完全无法区分。
+     */
+    'aria-label': string;
+    /** 方向决定哪组方向键生效。横向不接管上下键——那会夺走页面滚动。 */
+    orientation?: ToolbarOrientation;
+    children?: ReactNode;
+    className?: string;
+};
+
 export declare function Tooltip({ content, placement, delay, triggerLabel, children, align, tip, center, }: {
     content: ReactNode;
     placement?: TooltipPlacement;
@@ -1575,11 +1688,12 @@ export declare function Tooltip({ content, placement, delay, triggerLabel, child
     center?: boolean;
 }): JSX.Element;
 
-declare type TooltipAlign = 'start' | 'center' | 'end';
+export declare type TooltipAlign = 'start' | 'center' | 'end';
 
 export declare type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
 
-declare type TooltipTriggerProps = {
+/** Tooltip 会向 children 注入的 props：消费方自定义 trigger 元素时用它约束自己的组件签名。 */
+export declare type TooltipTriggerProps = {
     'aria-describedby'?: string;
     onFocus?: (event: never) => void;
     onBlur?: (event: never) => void;
@@ -1603,12 +1717,15 @@ export declare function useCopy(): {
     reset: () => void;
 };
 
-export declare function useRadio({ id, ...rest }: {
-    id: string;
-} & NativeInputProps): {
+export declare function useRadio({ id, ...rest }: UseRadioOptions): {
     component: JSX.Element;
 };
 
+/** useRadio 的入参。 */
+export declare type UseRadioOptions = {
+    id: string;
+} & ControlOptionNativeInputProps;
+
 export declare function useToast(): ToastContextValue;
 
 export declare function Video({ src, poster, tracks, label, controls, loop, }: VideoProps): JSX.Element;