klun-ui 0.6.0 → 0.7.1

package/dist/index.d.cts

@@ -495,8 +495,482 @@ declare const locales: {
     idID: Locale;
 };
 
+/**
+ * KDS 尺寸契约（size contract）——**每个组件尺寸的唯一来源**。
+ *
+ * 背景（KDS `01-foundations.md` §1.5 / `02-components.md` §2.2）：
+ * 库在 0.6.0 之前有 **20 套互不相同的 size 取值集合**，全局 `ConfigProvider size`
+ * 只覆盖 25/137 个组件，于是「每个组件每一档多高」既无法一处定义，也无法机器校验。
+ * 本文件把这件事收成一张表：
+ *
+ *   - `SIZE_CONTRACTS[组件名]` 声明该组件的自有档位、默认档位、以及
+ *     **全局档位 → 自有档位**的映射；
+ *   - 不跟随全局档位的组件必须写 `exempt`（理由），不允许"沉默地不跟随"；
+ *   - `resolveSize()` 是唯一的解析函数：**显式 prop > 全局档位 > 默认值**；
+ *   - `scripts/kds-size-contract.mjs` 以本表为准做门禁：新增 size prop 而未登记、
+ *     登记了却不接解析器、或类型里出现未登记的档位值，都会失败。
+ *
+ * 规范档位（KDS §1.5 的控件阶梯）是 `SizeType`；全局档位 `GlobalSize` 少一档
+ * `xsmall`——`xsmall` 是"附属尺寸"（tiny / compact 动作），不做整库默认。
+ */
+/** KDS §1.5 规范控件档位（由小到大）。 */
+type SizeType = "xsmall" | "small" | "medium" | "large";
+/** `ConfigProvider size` 的取值：全局默认档位（无 xsmall，见文件头说明）。 */
+type GlobalSize = "small" | "medium" | "large";
+/** 一条尺寸契约。 */
+interface SizeContract<S extends string = string> {
+    /** 组件自有档位（由小到大），必须与组件 TS 里的 size 取值集合完全一致。 */
+    readonly scale: readonly S[];
+    /** 没有 prop、也没有全局档位时使用的档位；必须与组件此前的默认值一致。 */
+    readonly fallback: S;
+    /** 全局档位 → 自有档位。与 `exempt` 二选一。 */
+    readonly fromGlobal?: Readonly<Record<GlobalSize, S>>;
+    /** 不跟随全局档位时的理由（门禁要求非空）。与 `fromGlobal` 二选一。 */
+    readonly exempt?: string;
+    /**
+     * 本组件把尺寸**原样转发**给另一个已登记组件（如 CheckboxGroup → Checkbox），
+     * 由被转发方解析全局档位。门禁接受这种形态，但要求实现里确有该转发。
+     * （用 string 而非 SizeContractName，避免与 `keyof typeof SIZE_CONTRACTS` 形成循环。）
+     */
+    readonly inherits?: string;
+    /** 规范档位视图，供规格文档使用；不填则由 `fromGlobal` 反推。 */
+    readonly tiers?: Readonly<Partial<Record<SizeType, S>>>;
+    /**
+     * 同一个文件里**其它**组件的尺寸刻度（如 `Button.tsx` 的 fancy/compact/link 变体）。
+     * 它们不参与全局档位解析，但门禁要求显式登记——避免"文件里还藏着第二套刻度"。
+     */
+    readonly extraScales?: ReadonlyArray<readonly S[]>;
+}
+declare const SIZE_CONTRACTS: {
+    readonly Button: {
+        readonly scale: readonly ["tiny", "xsmall", "small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+        readonly tiers: {
+            readonly xsmall: "xsmall";
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+        readonly extraScales: readonly [readonly ["small", "medium", "large"], readonly ["small", "medium"]];
+    };
+    readonly ButtonGroup: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly Input: {
+        readonly scale: readonly ["xsmall", "small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+        readonly tiers: {
+            readonly xsmall: "xsmall";
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly Select: {
+        readonly scale: readonly ["xsmall", "small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+        readonly tiers: {
+            readonly xsmall: "xsmall";
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly Textarea: {
+        readonly scale: readonly ["xsmall", "small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly AutoComplete: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly Cascader: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly SelectMenu: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly CounterInput: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly DigitInput: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly CronEditor: {
+        readonly scale: readonly ["small", "medium"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "medium";
+        };
+    };
+    readonly Checkbox: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly Radio: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly Switch: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly Slider: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly RangeSlider: {
+        readonly scale: readonly ["sm", "md", "lg"];
+        readonly fallback: "md";
+        readonly fromGlobal: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "lg";
+        };
+        readonly tiers: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "lg";
+        };
+    };
+    readonly ColorSlider: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly HorizontalFilter: {
+        readonly scale: readonly ["small", "medium"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "medium";
+        };
+    };
+    readonly CompactSelect: {
+        readonly scale: readonly ["xsmall", "small", "medium"];
+        readonly fallback: "small";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "medium";
+        };
+    };
+    readonly CompactSelectForInput: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "small";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly ColorDot: {
+        readonly scale: readonly ["sm", "md", "lg"];
+        readonly fallback: "md";
+        readonly fromGlobal: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "lg";
+        };
+        readonly tiers: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "lg";
+        };
+    };
+    readonly Badge: {
+        readonly scale: readonly ["small", "medium"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "medium";
+        };
+        readonly tiers: {
+            readonly xsmall: "small";
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "medium";
+        };
+    };
+    readonly StatusBadge: {
+        readonly scale: readonly ["small", "medium"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "medium";
+        };
+    };
+    readonly ChartLegend: {
+        readonly scale: readonly ["sm", "md"];
+        readonly fallback: "md";
+        readonly fromGlobal: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "md";
+        };
+    };
+    readonly ContentLabel: {
+        readonly scale: readonly ["sm", "md"];
+        readonly fallback: "md";
+        readonly fromGlobal: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "md";
+        };
+    };
+    readonly GaugeBar: {
+        readonly scale: readonly ["sm", "md", "lg"];
+        readonly fallback: "md";
+        readonly fromGlobal: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "lg";
+        };
+    };
+    readonly KeyIcon: {
+        readonly scale: readonly ["xs", "sm", "md", "lg", "xl"];
+        readonly fallback: "md";
+        readonly fromGlobal: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "lg";
+        };
+    };
+    readonly Money: {
+        readonly scale: readonly ["sm", "md", "lg", "big"];
+        readonly fallback: "md";
+        readonly fromGlobal: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "lg";
+        };
+    };
+    readonly StatusDot: {
+        readonly scale: readonly ["xs", "sm", "md", "lg"];
+        readonly fallback: "sm";
+        readonly fromGlobal: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "lg";
+        };
+    };
+    readonly Item: {
+        readonly scale: readonly ["default", "small", "xsmall"];
+        readonly fallback: "default";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "default";
+            readonly large: "default";
+        };
+    };
+    readonly Toggle: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly CopyButton: {
+        readonly scale: readonly ["sm", "md", "lg"];
+        readonly fallback: "md";
+        readonly fromGlobal: {
+            readonly small: "sm";
+            readonly medium: "md";
+            readonly large: "lg";
+        };
+    };
+    readonly CheckboxGroup: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+        readonly inherits: "Checkbox";
+    };
+    readonly Statistic: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly Descriptions: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly List: {
+        readonly scale: readonly ["small", "medium", "large"];
+        readonly fallback: "medium";
+        readonly fromGlobal: {
+            readonly small: "small";
+            readonly medium: "medium";
+            readonly large: "large";
+        };
+    };
+    readonly Avatar: {
+        readonly scale: readonly ["20", "24", "32", "40", "48", "56", "64", "72", "80"];
+        readonly fallback: "40";
+        readonly exempt: string;
+    };
+    readonly ActorAvatar: {
+        readonly scale: readonly ["20", "24", "32", "40", "56"];
+        readonly fallback: "24";
+        readonly exempt: "同 Avatar：像素刻度，不是控件档位。";
+    };
+    readonly AvatarGroup: {
+        readonly scale: readonly ["24", "32", "40", "48"];
+        readonly fallback: "40";
+        readonly exempt: "同 Avatar：像素刻度（决定叠加头像与 +N 徽标的直径）。";
+    };
+    readonly Space: {
+        readonly scale: readonly ["none", "xs", "sm", "md", "lg", "xl", "2xl"];
+        readonly fallback: "md";
+        readonly exempt: "这是**间距刻度**（gap），不是控件尺寸；KDS §1.4 的空间阶与控件档位是两条轴。";
+    };
+    readonly InputGroup: {
+        readonly scale: readonly ["xsmall", "icon-xsmall", "icon-small"];
+        readonly fallback: "xsmall";
+        readonly exempt: "该 size 描述的是组内嵌按钮的变体（含 icon-* 形态），不是控件高度档位。";
+    };
+    readonly Drawer: {
+        readonly scale: readonly ["default", "large"];
+        readonly fallback: "default";
+        readonly exempt: "宽度档位（480/640/800 口径），不是控件尺寸；浮层宽度由任务决定，不随全局 size 漂移。";
+    };
+    readonly CircularProgress: {
+        readonly scale: readonly ["number"];
+        readonly fallback: "number";
+        readonly exempt: "数值直径（px），由调用方按容器给定。";
+    };
+    readonly ImageUpload: {
+        readonly scale: readonly ["number"];
+        readonly fallback: "number";
+        readonly exempt: "数值边长（px），由调用方按容器给定。";
+    };
+    readonly Rating: {
+        readonly scale: readonly ["number"];
+        readonly fallback: "number";
+        readonly exempt: "数值星标字号（px）。";
+    };
+    readonly Spinner: {
+        readonly scale: readonly ["number"];
+        readonly fallback: "number";
+        readonly exempt: "数值直径（px）；命名档位见 SpinnerSize，由调用方按容器选定。";
+    };
+    readonly Splitter: {
+        readonly scale: readonly ["number"];
+        readonly fallback: "number";
+        readonly exempt: "分割条厚度/尺寸，接受数值或 CSS 长度，属布局量而非控件档位。";
+    };
+};
+type SizeContractName = keyof typeof SIZE_CONTRACTS;
+/** 取某个组件契约里的档位联合类型。 */
+type ContractSize<K extends SizeContractName> = (typeof SIZE_CONTRACTS)[K] extends SizeContract<infer S> ? S : never;
+/**
+ * 唯一的尺寸解析入口：**显式 prop > 全局档位 > 组件默认值**。
+ * 组件实现不应该再自己写 `size ?? "medium"`。
+ */
+declare function resolveSize<K extends SizeContractName>(name: K, explicit: ContractSize<K> | undefined, global: GlobalSize | undefined): ContractSize<K>;
+/** 规格文档用：组件在某规范档位下的自有档位（无对应档位返回 undefined）。 */
+declare function tierOf<K extends SizeContractName>(name: K, tier: SizeType): ContractSize<K> | undefined;
+
 /** Global default size for components whose scale includes these values. */
-type ComponentSize = "small" | "medium" | "large";
+type ComponentSize = GlobalSize;
 /** Text direction. */
 type Direction = "ltr" | "rtl";
 /** Color scheme. */
@@ -515,12 +989,16 @@ type Accent = "blue" | "purple" | "orange" | "green" | "slate" | "metronic" | "k
  */
 type Radius = "default" | "sharp" | "square" | "rounded";
 /**
- * Global control density (maps to `data-density`). `"compact"` shifts every
- * control-size token (heights, inline padding, checkbox/radio/switch sizing)
- * down one tier — for dense admin, toolbar and data-table surfaces. The size
- * props (`size="small"` …) keep working on top of it.
+ * Global control density (maps to `data-density`).
+ *
+ * - `"compact"` 把每条控件尺寸 token 下移一档，用于密集后台/工具栏/数据表；
+ * - `"kk"` 是 kk 控制台的紧凑尺度（2xs…xl = 18/20/24/28/32/36），第 62 批从
+ *   `[data-mode="kk"]` 皮肤里搬出来成为**显式密度轴**——皮肤不再顺带改几何，
+ *   `size` 因此成为跨皮肤稳定的契约。
+ *
+ * `size` props 在这两条密度上照常生效。
  */
-type Density = "default" | "compact";
+type Density = "default" | "compact" | "kk";
 interface KlunConfig {
     /** Active locale dictionary. */
     locale: Locale;
@@ -595,6 +1073,23 @@ declare function useSize<S extends string = ComponentSize>(explicit?: S): S;
  * supports); with no provider size it returns `fallback`.
  */
 declare function useMappedSize<S extends string>(explicit: S | undefined, map: Record<ComponentSize, S>, fallback: S): S;
+/**
+ * 按 **KDS 尺寸契约**解析组件档位（映射表在 `./size.ts` 的 `SIZE_CONTRACTS`）。
+ *
+ * 与 `useSize` / `useMappedSize` 的区别：后两者的映射散落在每个组件里，且只覆盖
+ * 25 个组件；`useScaleSize` 把映射收进一张表，由 `scripts/kds-size-contract.mjs`
+ * 门禁保证「每个 size prop 都被登记、每个登记的组件都真的走这里」。
+ *
+ * 解析顺序：**显式 prop > 全局 `ConfigProvider size` > 组件默认值**。
+ */
+declare function useScaleSize<K extends SizeContractName>(name: K, explicit?: ContractSize<K>): ContractSize<K>;
+/**
+ * 解析当前生效的控件密度：**Provider 优先 > 文档根 `data-density` > `"default"`**。
+ *
+ * JS 侧需要知道密度的组件（目前是 Table 的密度继承）必须用这个 hook，
+ * 不要直接读 `useConfig().density`——那会漏掉 `<html data-density="…">` 这条通道。
+ */
+declare function useDensity(): Density;
 
 declare function localTodayIso(): string;
 interface HeatmapCell {
@@ -1429,7 +1924,7 @@ interface StatusBadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, "color"
  * Centralizes status→color so every list/detail page reads identically.
  * Override or extend with the `map` prop ({ statusKey: tone }) or pass an explicit `tone`.
  */
-declare function StatusBadge({ status, label, tone, map, dot, variant, size, pulse, className, ...props }: StatusBadgeProps): react.JSX.Element;
+declare function StatusBadge({ status, label, tone, map, dot, variant, size: sizeProp, pulse, className, ...props }: StatusBadgeProps): react.JSX.Element;
 declare namespace StatusBadge {
     var displayName: string;
     var STATUS_TONE: Record<string, StatusTone>;
@@ -4295,4 +4790,68 @@ interface PopoverProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children">
  */
 declare const Popover: react.ForwardRefExoticComponent<PopoverProps & react.RefAttributes<HTMLSpanElement>>;
 
-export { type Accent, Accordion, type AccordionItem, type AccordionProps, ActivityHeatmap, type ActivityHeatmapProps, ActorAvatar, type ActorAvatarProps, type ActorAvatarSize, type ActorKind, Alert, type AlertProps, type AlertStatus, type AlertVariant, AutoComplete, type AutoCompleteOption, type AutoCompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, Badge, type BadgeColor, type BadgeProps, type BadgeVariant, Banner, type BannerProps, type BannerStatus, type BannerVariant, BorderBeam, type BorderBeamProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, type Breakpoint, BulkAction, BulkActionBar, type BulkActionBarProps, type BulkActionProps, Button, type ButtonAppearance, ButtonGroup, type ButtonGroupItem, type ButtonGroupProps, type ButtonGroupSize, type ButtonKind, type ButtonProps, type ButtonSize, type ButtonVariant, CRON_PRESETS, CapabilityBanner, type CapabilityBannerProps, type CapabilityReason, type CapabilityResource, CappedNumberFlow, type CappedNumberFlowProps, Card, type CardProps, type CardVariant, Carousel, type CarouselProps, Cascader, type CascaderOption, type CascaderProps, CharacterCounter, type CharacterCounterProps, ChartLegend, type ChartLegendItem, type ChartLegendProps, ChartTooltip, type ChartTooltipProps, type ChartTooltipRow, Checkbox, CheckboxCard, type CheckboxCardAlign, type CheckboxCardProps, CheckboxGroup, type CheckboxGroupOption, type CheckboxGroupProps, type CheckboxProps, type CheckboxSize, ChipColor, CircularProgress, type CircularProgressColor, type CircularProgressProps, type ClassValue, CodeViewer, type CodeViewerProps, Col, type ColProps, type ColSize, Collapse, type CollapseProps, ColorDot, type ColorDotProps, type ColorDotSize, ColorPicker, type ColorPickerProps, ColorSlider, type ColorSliderProps, type ColorSliderSize, type CommandGroup, type CommandItem, CommandMenu, type CommandMenuProps, type CompactButtonAppearance, type CompactButtonProps, type CompactButtonSize, CompactNumberFlow, type CompactNumberFlowProps, CompactSelect, type CompactSelectAppearance, CompactSelectForInput, type CompactSelectForInputProps, type CompactSelectForInputSide, type CompactSelectForInputSize, type CompactSelectProps, type CompactSelectSize, type ComponentSize, ConfigProvider, type ConfigProviderProps, Confirm, type ConfirmIntent, type ConfirmOptions, type ConfirmRequireInput, type ConfirmResult, ContentLabel, type ContentLabelColor, type ContentLabelProps, ContextMenu, type ContextMenuItem, type ContextMenuProps, type ContextMenuState, CopyButton, type CopyButtonProps, type CopyButtonSize, type CopyButtonVariant, type CountdownResult, CounterInput, type CounterInputProps, type CounterInputSize, CronEditor, type CronEditorLabels, type CronEditorProps, type CronPreset, CrossRefBadge, type CrossRefBadgeProps, type CrossRefKind, type CrossRefPreview, CurrencyNumberFlow, type CurrencyNumberFlowProps, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, type DefaultButtonProps, type Density, type DescriptionItem, Descriptions, type DescriptionsLayout, type DescriptionsProps, type DescriptionsSize, type DescriptionsVariant, type DiffHunk, type DiffLine, type DiffLineType, type DiffMode, type DiffSide, DiffViewer, type DiffViewerProps, DigitInput, type DigitInputProps, type DigitInputSize, type Direction, Divider, type DividerProps, type DividerVariant, DotSphere, type DotSphereProps, type DotTone, Drawer, type DrawerPlacement, type DrawerProps, Dropdown, type DropdownItem, type DropdownProps, EmojiPicker, type EmojiPickerProps, EmptyState, type EmptyStateProps, ExpiryCountdown, type ExpiryCountdownProps, type FancyButtonProps, type FancyButtonSize, type FancyButtonVariant, Field, FieldContent, type FieldContentProps, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorProps, FieldGroup, type FieldGroupProps, FieldLabel, type FieldLabelProps, type FieldOrientation, type FieldProps, type FieldSize, FieldTitle, type FieldTitleProps, FileUpload, type FileUploadProps, Flex, type FlexGap, type FlexProps, Form, type FormInstance, FormItem, type FormItemProps, FormList, type FormListField, type FormListOperations, type FormListProps, type FormProps, type FormRule, Format, type FormatApi, GaugeBar, type GaugeBarColor, type GaugeBarProps, type GaugeBarSize, Grid, type Gutter, type HeatmapCell, type HeatmapGrid, type HeatmapMonthLabel, type HeatmapOptions, type HeatmapSummary, Hint, type HintProps, HorizontalFilter, type HorizontalFilterItem, type HorizontalFilterProps, type HorizontalFilterSize, HoverCard, type HoverCardAlign, HoverCardContent, type HoverCardContentProps, type HoverCardProps, type HoverCardSide, HoverCardTrigger, type HoverCardTriggerProps, ICON_GROUPS, type IconGroup, IconPicker, type IconPickerProps, type ImageItem, ImageUpload, type ImageUploadProps, type ImageUploadShape, ImageViewer, type ImageViewerProps, InlineInput, type InlineInputProps, type InlineInputTone, type InlineInputWeight, InlineSelect, type InlineSelectProps, type InlineSelectTone, type InlineSelectWeight, Input, InputGroup, InputGroupAddon, type InputGroupAddonAlign, type InputGroupAddonProps, InputGroupButton, type InputGroupButtonProps, type InputGroupButtonSize, type InputGroupButtonVariant, InputGroupInput, type InputGroupInputProps, type InputGroupProps, InputGroupText, type InputGroupTextProps, type InputProps, Item, ItemActions, type ItemActionsProps, ItemContent, type ItemContentProps, ItemDescription, type ItemDescriptionProps, ItemFooter, type ItemFooterProps, ItemGroup, type ItemGroupProps, ItemHeader, type ItemHeaderProps, ItemMedia, type ItemMediaProps, type ItemMediaVariant, type ItemProps, ItemSeparator, type ItemSeparatorProps, type ItemSize, ItemTitle, type ItemTitleProps, type ItemVariant, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, KeyIcon, type KeyIconAppearance, type KeyIconColor, type KeyIconProps, type KeyIconSize, type KlunConfig, LIST_GRID_BOTTOM_CLEARANCE, Label, type LabelProps, Layout, LayoutContent, type LayoutContentProps, LayoutFooter, type LayoutFooterProps, LayoutHeader, type LayoutHeaderProps, type LayoutProps, LayoutSider, type LinkButtonProps, type LinkButtonSize, type LinkButtonVariant, List, ListGrid, ListGridBody, ListGridCell, ListGridHeader, ListGridHeaderCell, type ListGridHeaderCellProps, type ListGridProps, ListGridRow, type ListGridSortDirection, ListItem, type ListItemProps, type ListProps, LiveDot, type LiveDotProps, type Locale, type LogLevel, type LogLine, LogViewer, type LogViewerProps, Markdown, type MarkdownProps, Masonry, type MasonryBreakpoints, type MasonryColumns, type MasonryGutter, type MasonryProps, Menu, type MenuItem, type MenuProps, Message, type MessageApi, type MessageOptions, type MessageProps, type MessageStatus, Modal, type ModalProps, Money, type MoneyOptions, type MoneyPeriod, type MoneyProps, type MoneyResult, type MoneySize, type MoneyTone, type NamePath, NavigationProgress, type NavigationProgressProps, Notification, type NotificationApi, type NotificationOptions, type NotificationPlacement, type NotificationProps, type NotificationStatus, NumberFlow, type NumberFlowFormat, type NumberFlowProps, PageHeader, type PageHeaderProps, type PageHeaderTab, Pagination, type PaginationProps, PasswordStrength, type PasswordStrengthLevel, type PasswordStrengthProps, type PctOptions, Popconfirm, type PopconfirmProps, Popover, type PopoverProps, ProgressBar, type ProgressBarProps, type ProgressColor, QUICK_EMOJIS, QuickEmojiPicker, type QuickEmojiPickerProps, Radio, RadioCard, type RadioCardAlign, type RadioCardProps, type RadioProps, type RadioSize, type Radius, RangeSlider, type RangeSliderProps, type RangeSliderSize, Rating, type RatingProps, type Reaction, ReactionBar, type ReactionBarProps, type ReactionItem, type RelTimeOptions, RelativeTime, type RelativeTimeProps, type Responsive, Result, type ResultProps, type ResultStatus, RichEditor, type RichEditorProps, RichEditorToolbar, type RichEditorToolbarProps, Row, type RowAlign, type RowJustify, type RowProps, type Rules, type ScreenMap, type SegmentItem, SegmentedControl, type SegmentedControlProps, SegmentedProgress, type SegmentedProgressColor, type SegmentedProgressProps, Select, SelectMenu, type SelectMenuOption, type SelectMenuProps, type SelectMenuSize, type SelectProps, ShimmerText, type ShimmerTextProps, Sidebar, type SidebarMenuItem, type SidebarNavItem, type SidebarProps, type SidebarSection, type SiderProps, type SiderTheme, type SizeOptions, Skeleton, type SkeletonProps, Slider, type SliderProps, type SliderSize, type SortDir, Space, type SpaceProps, type SpaceSize, Spinner, type SpinnerProps, type SpinnerSize, Splitter, type SplitterLayout, SplitterPanel, type SplitterPanelProps, type SplitterProps, StatCard, type StatCardProps, type StatCardTint, Statistic, type StatisticProps, StatusBadge, type StatusBadgeProps, StatusDot, type StatusDotProps, type StatusTone, type Step, StepIndicator, type StepIndicatorProps, Stepper, StepperContent, type StepperContentProps, StepperDescription, type StepperDescriptionProps, StepperIndicator, type StepperIndicatorProps, type StepperIndicators, StepperItem, type StepperItemProps, StepperNav, type StepperNavProps, type StepperOrientation, StepperPanel, type StepperPanelProps, type StepperProps, StepperSeparator, type StepperSeparatorProps, type StepperStepState, StepperTitle, type StepperTitleProps, StepperTrigger, type StepperTriggerProps, Switch, type SwitchProps, type SwitchSize, type TabItem, Table, type TableColumn, type TableMenuItem, type TableProps, type TableSort, Tabs, type TabsProps, type TabsVariant, Tag, type TagProps, Textarea, type TextareaProps, type TextareaSize, type Theme, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastAction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastProps, type ToastStatus, Toaster, type ToasterProps, Toggle, type ToggleProps, type ToggleSize, type ToggleVariant, Tooltip, type TooltipProps, Tree, type TreeNode, type TreeProps, UnicodeSpinner, type UnicodeSpinnerProps, type UseFormOptions, type UseMessageDefaults, type UseNotificationDefaults, type VirtualColumn, VirtualTable, type VirtualTableProps, type WikiLinkResolver, Wizard, type WizardProps, type WizardStep, arSA, buildHeatmapGrid, cx, deDE, describeCron, enUS, esES, fmt, formatAvatarEmoji, frFR, groupReactions, idID, itIT, jaJP, koKR, localTodayIso, locales, nlNL, parseAvatarEmoji, parsePatch, plPL, primaryColorVars, ptBR, renderMarkdown, resolveMove, ruRU, summarizeHeatmap, toast, trTR, useBreakpoint, useConfig, useContextMenu, useForm, useLocale, useMappedSize, useMessage, useNotification, useSize, useStepItem, useStepper, viVN, zhCN, zhTW };
+/**
+ * KDS U04 — 内部浮层栈底座（**不是公开 API**，不从 index.ts 导出）。
+ *
+ * 解决的问题（都是先在生产结构里确认过的真实缺陷）：
+ *
+ * 1. **Escape 会关掉所有打开层。** 每个 Modal/Drawer 实例各自往 document 挂一个
+ *    keydown 监听，按一次 Esc 会依次调用所有实例的关闭回调；两层弹窗时一次全关。
+ *    → 只有栈顶那一层响应（isTopOverlay）。
+ *
+ * 2. **滚动锁没有计数。** 每层打开时记住当时 body.overflow 并在关闭时还原。
+ *    A 先开（记 ""，置 hidden）、B 后开（记 "hidden"，置 hidden）；
+ *    先关 A → 还原成 ""（B 还开着却解锁了）；再关 B → 还原成 "hidden"（body 被永久锁死）。
+ *    → 计数，只有最后一层关闭时才还原。
+ *
+ * 3. **层级靠各组件自己写常量。** 改为按栈深分配（KDS 05-engineering.md §5.3 提案值）。
+ *
+ * 焦点范围（scope）另外登记「属于本层的 DOM 根」：portal 到 body 的子面板
+ * （例如模态里的 Select 下拉）不在 dialog 子树内，必须显式登记，否则会被当成
+ * 「背景」而被 inert，或让 Tab 顺序漏掉它。
+ */
+type OverlayId = symbol;
+
+interface UseOverlayScopeOptions {
+    /** 本层是否处于打开状态。 */
+    active: boolean;
+    /** Escape 回调；仅在**本层是栈顶**且 escapeEnabled 时触发。 */
+    onEscape?: () => void;
+    /** 允许 Escape 关闭（例如 Modal 的 keyboard && closable）。 */
+    escapeEnabled?: boolean;
+    /** 打开后把焦点放到第一个可聚焦元素；没有则聚焦容器本身。 */
+    autoFocus?: boolean;
+    /** 关闭后把焦点还给打开前的元素。 */
+    restoreFocus?: boolean;
+    /** 把本层之外的兄弟节点标记 inert。 */
+    inertBackground?: boolean;
+}
+interface OverlayScope {
+    /** 挂到本层的根元素（dialog / drawer 面板）上。 */
+    ref: (el: HTMLElement | null) => void;
+    scopeId: OverlayId | null;
+    /** 按栈深算出的层级基准；加上 scrim/dialog/popup 偏移使用。 */
+    layerBase: number;
+}
+/**
+ * KDS U04 — 一个浮层（Modal/Drawer/命令面板…）的公共行为：
+ * 栈顶判定、滚动锁计数、层级、焦点陷阱与恢复、背景 inert。
+ *
+ * 刻意只做「所有模态都需要的部分」，不涉及具体视觉。
+ */
+declare function useOverlayScope({ active, onEscape, escapeEnabled, autoFocus, restoreFocus, inertBackground, }: UseOverlayScopeOptions): OverlayScope;
+interface OverlayLayerContextValue {
+    layerBase: number;
+}
+declare function OverlayLayerProvider({ layerBase, children }: {
+    layerBase: number;
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * 面板应该使用的 z-index。
+ * 在浮层内 → 所属浮层基准 + popupOffset（默认 +20，即 KDS §5.3 的该层 popup）；
+ * 不在浮层内 → 页面级 popup（100）。
+ */
+declare function useOverlayLayer(kind?: "popup" | "tooltip"): number;
+
+export { type Accent, Accordion, type AccordionItem, type AccordionProps, ActivityHeatmap, type ActivityHeatmapProps, ActorAvatar, type ActorAvatarProps, type ActorAvatarSize, type ActorKind, Alert, type AlertProps, type AlertStatus, type AlertVariant, AutoComplete, type AutoCompleteOption, type AutoCompleteProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, Badge, type BadgeColor, type BadgeProps, type BadgeVariant, Banner, type BannerProps, type BannerStatus, type BannerVariant, BorderBeam, type BorderBeamProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, type Breakpoint, BulkAction, BulkActionBar, type BulkActionBarProps, type BulkActionProps, Button, type ButtonAppearance, ButtonGroup, type ButtonGroupItem, type ButtonGroupProps, type ButtonGroupSize, type ButtonKind, type ButtonProps, type ButtonSize, type ButtonVariant, CRON_PRESETS, CapabilityBanner, type CapabilityBannerProps, type CapabilityReason, type CapabilityResource, CappedNumberFlow, type CappedNumberFlowProps, Card, type CardProps, type CardVariant, Carousel, type CarouselProps, Cascader, type CascaderOption, type CascaderProps, CharacterCounter, type CharacterCounterProps, ChartLegend, type ChartLegendItem, type ChartLegendProps, ChartTooltip, type ChartTooltipProps, type ChartTooltipRow, Checkbox, CheckboxCard, type CheckboxCardAlign, type CheckboxCardProps, CheckboxGroup, type CheckboxGroupOption, type CheckboxGroupProps, type CheckboxProps, type CheckboxSize, ChipColor, CircularProgress, type CircularProgressColor, type CircularProgressProps, type ClassValue, CodeViewer, type CodeViewerProps, Col, type ColProps, type ColSize, Collapse, type CollapseProps, ColorDot, type ColorDotProps, type ColorDotSize, ColorPicker, type ColorPickerProps, ColorSlider, type ColorSliderProps, type ColorSliderSize, type CommandGroup, type CommandItem, CommandMenu, type CommandMenuProps, type CompactButtonAppearance, type CompactButtonProps, type CompactButtonSize, CompactNumberFlow, type CompactNumberFlowProps, CompactSelect, type CompactSelectAppearance, CompactSelectForInput, type CompactSelectForInputProps, type CompactSelectForInputSide, type CompactSelectForInputSize, type CompactSelectProps, type CompactSelectSize, type ComponentSize, ConfigProvider, type ConfigProviderProps, Confirm, type ConfirmIntent, type ConfirmOptions, type ConfirmRequireInput, type ConfirmResult, ContentLabel, type ContentLabelColor, type ContentLabelProps, ContextMenu, type ContextMenuItem, type ContextMenuProps, type ContextMenuState, type ContractSize, CopyButton, type CopyButtonProps, type CopyButtonSize, type CopyButtonVariant, type CountdownResult, CounterInput, type CounterInputProps, type CounterInputSize, CronEditor, type CronEditorLabels, type CronEditorProps, type CronPreset, CrossRefBadge, type CrossRefBadgeProps, type CrossRefKind, type CrossRefPreview, CurrencyNumberFlow, type CurrencyNumberFlowProps, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, type DefaultButtonProps, type Density, type DescriptionItem, Descriptions, type DescriptionsLayout, type DescriptionsProps, type DescriptionsSize, type DescriptionsVariant, type DiffHunk, type DiffLine, type DiffLineType, type DiffMode, type DiffSide, DiffViewer, type DiffViewerProps, DigitInput, type DigitInputProps, type DigitInputSize, type Direction, Divider, type DividerProps, type DividerVariant, DotSphere, type DotSphereProps, type DotTone, Drawer, type DrawerPlacement, type DrawerProps, Dropdown, type DropdownItem, type DropdownProps, EmojiPicker, type EmojiPickerProps, EmptyState, type EmptyStateProps, ExpiryCountdown, type ExpiryCountdownProps, type FancyButtonProps, type FancyButtonSize, type FancyButtonVariant, Field, FieldContent, type FieldContentProps, FieldDescription, type FieldDescriptionProps, FieldError, type FieldErrorProps, FieldGroup, type FieldGroupProps, FieldLabel, type FieldLabelProps, type FieldOrientation, type FieldProps, type FieldSize, FieldTitle, type FieldTitleProps, FileUpload, type FileUploadProps, Flex, type FlexGap, type FlexProps, Form, type FormInstance, FormItem, type FormItemProps, FormList, type FormListField, type FormListOperations, type FormListProps, type FormProps, type FormRule, Format, type FormatApi, GaugeBar, type GaugeBarColor, type GaugeBarProps, type GaugeBarSize, type GlobalSize, Grid, type Gutter, type HeatmapCell, type HeatmapGrid, type HeatmapMonthLabel, type HeatmapOptions, type HeatmapSummary, Hint, type HintProps, HorizontalFilter, type HorizontalFilterItem, type HorizontalFilterProps, type HorizontalFilterSize, HoverCard, type HoverCardAlign, HoverCardContent, type HoverCardContentProps, type HoverCardProps, type HoverCardSide, HoverCardTrigger, type HoverCardTriggerProps, ICON_GROUPS, type IconGroup, IconPicker, type IconPickerProps, type ImageItem, ImageUpload, type ImageUploadProps, type ImageUploadShape, ImageViewer, type ImageViewerProps, InlineInput, type InlineInputProps, type InlineInputTone, type InlineInputWeight, InlineSelect, type InlineSelectProps, type InlineSelectTone, type InlineSelectWeight, Input, InputGroup, InputGroupAddon, type InputGroupAddonAlign, type InputGroupAddonProps, InputGroupButton, type InputGroupButtonProps, type InputGroupButtonSize, type InputGroupButtonVariant, InputGroupInput, type InputGroupInputProps, type InputGroupProps, InputGroupText, type InputGroupTextProps, type InputProps, Item, ItemActions, type ItemActionsProps, ItemContent, type ItemContentProps, ItemDescription, type ItemDescriptionProps, ItemFooter, type ItemFooterProps, ItemGroup, type ItemGroupProps, ItemHeader, type ItemHeaderProps, ItemMedia, type ItemMediaProps, type ItemMediaVariant, type ItemProps, ItemSeparator, type ItemSeparatorProps, type ItemSize, ItemTitle, type ItemTitleProps, type ItemVariant, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, KeyIcon, type KeyIconAppearance, type KeyIconColor, type KeyIconProps, type KeyIconSize, type KlunConfig, LIST_GRID_BOTTOM_CLEARANCE, Label, type LabelProps, Layout, LayoutContent, type LayoutContentProps, LayoutFooter, type LayoutFooterProps, LayoutHeader, type LayoutHeaderProps, type LayoutProps, LayoutSider, type LinkButtonProps, type LinkButtonSize, type LinkButtonVariant, List, ListGrid, ListGridBody, ListGridCell, ListGridHeader, ListGridHeaderCell, type ListGridHeaderCellProps, type ListGridProps, ListGridRow, type ListGridSortDirection, ListItem, type ListItemProps, type ListProps, LiveDot, type LiveDotProps, type Locale, type LogLevel, type LogLine, LogViewer, type LogViewerProps, Markdown, type MarkdownProps, Masonry, type MasonryBreakpoints, type MasonryColumns, type MasonryGutter, type MasonryProps, Menu, type MenuItem, type MenuProps, Message, type MessageApi, type MessageOptions, type MessageProps, type MessageStatus, Modal, type ModalProps, Money, type MoneyOptions, type MoneyPeriod, type MoneyProps, type MoneyResult, type MoneySize, type MoneyTone, type NamePath, NavigationProgress, type NavigationProgressProps, Notification, type NotificationApi, type NotificationOptions, type NotificationPlacement, type NotificationProps, type NotificationStatus, NumberFlow, type NumberFlowFormat, type NumberFlowProps, type OverlayLayerContextValue, OverlayLayerProvider, type OverlayScope, PageHeader, type PageHeaderProps, type PageHeaderTab, Pagination, type PaginationProps, PasswordStrength, type PasswordStrengthLevel, type PasswordStrengthProps, type PctOptions, Popconfirm, type PopconfirmProps, Popover, type PopoverProps, ProgressBar, type ProgressBarProps, type ProgressColor, QUICK_EMOJIS, QuickEmojiPicker, type QuickEmojiPickerProps, Radio, RadioCard, type RadioCardAlign, type RadioCardProps, type RadioProps, type RadioSize, type Radius, RangeSlider, type RangeSliderProps, type RangeSliderSize, Rating, type RatingProps, type Reaction, ReactionBar, type ReactionBarProps, type ReactionItem, type RelTimeOptions, RelativeTime, type RelativeTimeProps, type Responsive, Result, type ResultProps, type ResultStatus, RichEditor, type RichEditorProps, RichEditorToolbar, type RichEditorToolbarProps, Row, type RowAlign, type RowJustify, type RowProps, type Rules, SIZE_CONTRACTS, type ScreenMap, type SegmentItem, SegmentedControl, type SegmentedControlProps, SegmentedProgress, type SegmentedProgressColor, type SegmentedProgressProps, Select, SelectMenu, type SelectMenuOption, type SelectMenuProps, type SelectMenuSize, type SelectProps, ShimmerText, type ShimmerTextProps, Sidebar, type SidebarMenuItem, type SidebarNavItem, type SidebarProps, type SidebarSection, type SiderProps, type SiderTheme, type SizeContract, type SizeContractName, type SizeOptions, type SizeType, Skeleton, type SkeletonProps, Slider, type SliderProps, type SliderSize, type SortDir, Space, type SpaceProps, type SpaceSize, Spinner, type SpinnerProps, type SpinnerSize, Splitter, type SplitterLayout, SplitterPanel, type SplitterPanelProps, type SplitterProps, StatCard, type StatCardProps, type StatCardTint, Statistic, type StatisticProps, StatusBadge, type StatusBadgeProps, StatusDot, type StatusDotProps, type StatusTone, type Step, StepIndicator, type StepIndicatorProps, Stepper, StepperContent, type StepperContentProps, StepperDescription, type StepperDescriptionProps, StepperIndicator, type StepperIndicatorProps, type StepperIndicators, StepperItem, type StepperItemProps, StepperNav, type StepperNavProps, type StepperOrientation, StepperPanel, type StepperPanelProps, type StepperProps, StepperSeparator, type StepperSeparatorProps, type StepperStepState, StepperTitle, type StepperTitleProps, StepperTrigger, type StepperTriggerProps, Switch, type SwitchProps, type SwitchSize, type TabItem, Table, type TableColumn, type TableMenuItem, type TableProps, type TableSort, Tabs, type TabsProps, type TabsVariant, Tag, type TagProps, Textarea, type TextareaProps, type TextareaSize, type Theme, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastAction, type ToastOptions, type ToastPosition, type ToastPromiseMessages, type ToastProps, type ToastStatus, Toaster, type ToasterProps, Toggle, type ToggleProps, type ToggleSize, type ToggleVariant, Tooltip, type TooltipProps, Tree, type TreeNode, type TreeProps, UnicodeSpinner, type UnicodeSpinnerProps, type UseFormOptions, type UseMessageDefaults, type UseNotificationDefaults, type UseOverlayScopeOptions, type VirtualColumn, VirtualTable, type VirtualTableProps, type WikiLinkResolver, Wizard, type WizardProps, type WizardStep, arSA, buildHeatmapGrid, cx, deDE, describeCron, enUS, esES, fmt, formatAvatarEmoji, frFR, groupReactions, idID, itIT, jaJP, koKR, localTodayIso, locales, nlNL, parseAvatarEmoji, parsePatch, plPL, primaryColorVars, ptBR, renderMarkdown, resolveMove, resolveSize, ruRU, summarizeHeatmap, tierOf, toast, trTR, useBreakpoint, useConfig, useContextMenu, useDensity, useForm, useLocale, useMappedSize, useMessage, useNotification, useOverlayLayer, useOverlayScope, useScaleSize, useSize, useStepItem, useStepper, viVN, zhCN, zhTW };