haze-ui 1.26.0 → 1.28.0

package/dist/tokens/colors.js

@@ -1,5 +1,4 @@
 
-"use client";
 /* empty css                 */
 //#region src/lib/tokens/colors.ts
 var e = "haze-colors__lightTheme", t = "haze-colors__darkTheme";

package/dist/tokens/index.js

@@ -1,4 +1,3 @@
-"use client";
 import { darkTheme as e, lightTheme as t } from "./colors.js";
 import { spacing as n } from "./spacing.js";
 import { typography as r } from "./typography.js";

package/dist/tokens/motion.js

@@ -1,5 +1,4 @@
 
-"use client";
 /* empty css                 */
 //#region src/lib/tokens/motion.ts
 var e = "haze-motion__motion";

package/dist/tokens/oklch.js

@@ -1,4 +1,3 @@
-"use client";
 function e(e) {
 	return e <= .04045 ? e / 12.92 : ((e + .055) / 1.055) ** 2.4;
 }

package/dist/tokens/palette.js

@@ -1,4 +1,3 @@
-"use client";
 import { clampChroma as e, formatOklch as t, parseHex as n, parseOklch as r } from "./oklch.js";
 //#region src/lib/tokens/palette.ts
 var i = {

package/dist/tokens/registry.js

@@ -1,4 +1,3 @@
-"use client";
 import { formatOklch as e } from "./oklch.js";
 import { SEMANTIC_COLOR_TOKENS as t } from "./palette.js";
 //#region src/lib/tokens/registry.ts
@@ -448,29 +447,7 @@ var n = [
 		"--haze-text-sm",
 		"--haze-weight-medium"
 	],
-	button: [
-		"--haze-color-primary",
-		"--haze-color-primary-hover",
-		"--haze-color-primary-active",
-		"--haze-color-text",
-		"--haze-color-text-inverse",
-		"--haze-color-border",
-		"--haze-color-border-hover",
-		"--haze-color-bg-subtle",
-		"--haze-color-bg-muted",
-		"--haze-color-focus-ring",
-		"--haze-font-sans",
-		"--haze-leading-tight",
-		"--haze-radius-md",
-		"--haze-space-1",
-		"--haze-space-2",
-		"--haze-space-3",
-		"--haze-space-4",
-		"--haze-space-6",
-		"--haze-text-sm",
-		"--haze-text-base",
-		"--haze-weight-medium"
-	],
+	button: /* @__PURE__ */ "--haze-button-font-size-lg.--haze-button-font-size-md.--haze-button-font-size-sm.--haze-button-height-lg.--haze-button-height-md.--haze-button-height-sm.--haze-button-radius.--haze-color-primary.--haze-color-primary-hover.--haze-color-primary-active.--haze-color-text.--haze-color-text-inverse.--haze-color-border.--haze-color-border-hover.--haze-color-bg-subtle.--haze-color-bg-muted.--haze-color-focus-ring.--haze-font-sans.--haze-leading-tight.--haze-radius-md.--haze-space-1.--haze-space-2.--haze-space-3.--haze-space-4.--haze-space-6.--haze-text-sm.--haze-text-base.--haze-weight-medium".split("."),
 	card: [
 		"--haze-color-bg",
 		"--haze-color-border",
@@ -552,19 +529,24 @@ var n = [
 	],
 	combobox: [
 		"--haze-color-bg",
+		"--haze-color-bg-subtle",
 		"--haze-color-border",
-		"--haze-color-text",
-		"--haze-color-primary",
 		"--haze-color-focus-ring",
-		"--haze-color-bg-subtle",
+		"--haze-color-primary",
+		"--haze-color-primary-subtle",
+		"--haze-color-text",
+		"--haze-color-text-muted",
+		"--haze-duration-fast",
 		"--haze-font-sans",
 		"--haze-leading-normal",
 		"--haze-radius-md",
+		"--haze-radius-sm",
 		"--haze-shadow-lg",
 		"--haze-space-1",
 		"--haze-space-2",
 		"--haze-space-3",
 		"--haze-text-sm",
+		"--haze-text-xs",
 		"--haze-weight-medium"
 	],
 	datepicker: [
@@ -591,13 +573,20 @@ var n = [
 		"--haze-weight-medium"
 	],
 	dialog: [
+		"--haze-dialog-padding",
+		"--haze-dialog-radius",
+		"--haze-dialog-title-font-size",
+		"--haze-dialog-title-gap",
+		"--haze-dialog-width",
 		"--haze-color-bg",
 		"--haze-color-text",
 		"--haze-color-focus-ring",
 		"--haze-font-sans",
 		"--haze-radius-xl",
 		"--haze-shadow-xl",
-		"--haze-space-6"
+		"--haze-space-4",
+		"--haze-space-6",
+		"--haze-text-lg"
 	],
 	diffviewer: [
 		"--haze-color-border",

package/dist/tokens/spacing.js

@@ -1,5 +1,4 @@
 
-"use client";
 /* empty css                  */
 //#region src/lib/tokens/spacing.ts
 var e = "haze-spacing__spacing";

package/dist/tokens/typography.js

@@ -1,5 +1,4 @@
 
-"use client";
 /* empty css                     */
 //#region src/lib/tokens/typography.ts
 var e = "haze-typography__typography";

package/dist/types/components/Anchor/Anchor.d.ts

@@ -0,0 +1,25 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ControlOrValue } from 'react-use-control';
+export type AnchorItem = {
+    /** Section id — the scroll target is `document.getElementById(id)`. */
+    id: string;
+    /** Link content. */
+    label: ReactNode;
+};
+type AnchorProps = {
+    /** Anchor sections, in document order. */
+    items: AnchorItem[];
+    /** Highlighted section id. Accepts a control (controlled) or a plain value (uncontrolled initial). */
+    activeId?: ControlOrValue<string>;
+    /** Fires when a link is clicked, after the highlight moves and before scrolling is queued. */
+    onClick?: (id: string) => void;
+    /** Distance kept between the container top and the section top when scrolling (sticky header height), px. */
+    offsetTop?: number;
+    /** Scroll-spy trigger line, px from the container top (fallback engines only). */
+    bounds?: number;
+    /** Scroll container; defaults to `window`. */
+    getContainer?: () => HTMLElement | Window;
+    className?: string;
+} & Omit<ComponentPropsWithoutRef<'nav'>, 'className' | 'onClick' | 'children'>;
+export default function Anchor({ items, activeId: activeIdControl, onClick, offsetTop, bounds, getContainer, className, ...rest }: AnchorProps): import("react").JSX.Element;
+export type { AnchorProps };

package/dist/types/components/Anchor/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Anchor } from './Anchor';
+export type { AnchorProps, AnchorItem } from './Anchor';

package/dist/types/components/AppShell/AppShell.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ControlOrValue } from 'react-use-control';
+type AppShellProps = {
+    /** Top region, rendered inside a sticky <header> spanning the full width. */
+    header?: ReactNode;
+    /** Side region, rendered inside an <aside> column left of the content. */
+    sidebar?: ReactNode;
+    /** Bottom region, rendered inside a <footer> spanning the full width. */
+    footer?: ReactNode;
+    /** Collapsed state of the sidebar column; a Control drives it live, a plain boolean is the uncontrolled initial value. */
+    sidebarCollapsed?: ControlOrValue<boolean>;
+    /** Expanded sidebar width, any CSS width. Consumers theme it by overriding --haze-appshell-sidebar-width instead of hardcoding. */
+    sidebarWidth?: string;
+    children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
+export default function AppShell({ header: headerSlot, sidebar: sidebarSlot, footer: footerSlot, sidebarCollapsed: collapsedControl, sidebarWidth, className, style, children, ...rest }: AppShellProps): import("react").JSX.Element;
+export type { AppShellProps };

package/dist/types/components/AppShell/index.d.ts

@@ -0,0 +1,2 @@
+export { default as AppShell } from './AppShell';
+export type { AppShellProps } from './AppShell';

package/dist/types/components/Badge/badge-styles.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared Badge skin — the base, variant and size classes the `Badge`
+ * component wears. Living in their own module keeps the component file
+ * free of style internals (react-refresh boundary) and lets the
+ * variants/sizes maps ship as public constants (`badgeVariants` /
+ * `badgeSizes`, the shadcn `buttonVariants` precedent) for consumers
+ * composing custom elements with the same skin; split-css groups the
+ * emitted CSS into `haze-ui/css/badge.css` with them.
+ */
+export declare const base: import("@linaria/core").LinariaClassName;
+export declare const variants: {
+    readonly default: import("@linaria/core").LinariaClassName;
+    readonly success: import("@linaria/core").LinariaClassName;
+    readonly warning: import("@linaria/core").LinariaClassName;
+    readonly danger: import("@linaria/core").LinariaClassName;
+    readonly info: import("@linaria/core").LinariaClassName;
+};
+export declare const sizes: {
+    readonly sm: import("@linaria/core").LinariaClassName;
+    readonly md: import("@linaria/core").LinariaClassName;
+};

package/dist/types/components/Badge/index.d.ts

@@ -1,2 +1,3 @@
 export { default as Badge } from './Badge';
 export type { BadgeProps } from './Badge';
+export { variants as badgeVariants, sizes as badgeSizes } from './badge-styles';

package/dist/types/components/BottomSheet/BottomSheet.d.ts

@@ -1,10 +1,59 @@
-import type { ReactNode, ComponentPropsWithoutRef } from 'react';
+import type { ReactNode, ComponentPropsWithoutRef, Ref } from 'react';
 import type { ControlOrValue } from 'react-use-control';
+/**
+ * Imperative handle exposed through the React 19 `ref` prop (same API
+ * choice as VirtualList). Unlike Dialog/Drawer there is no native close
+ * event to defer to — every exit path (overlay click, Escape, handle)
+ * runs through the same `handleClose`, so `onClose` still fires exactly
+ * once per close.
+ */
+type BottomSheetHandle = {
+    /** Show the sheet (Presence mounts it, focus moves in). */
+    open: () => void;
+    /** Close the sheet through the animated exit; `onClose` fires once. */
+    close: () => void;
+    /** Focus the element that held focus when the sheet last opened. */
+    focusTrigger: () => void;
+};
 type BottomSheetProps = {
     open?: ControlOrValue<boolean>;
     onClose?: () => void;
+    /**
+     * 开/关状态翻转是否包进 View Transitions API（默认 `false`，行为与
+     * 不传完全一致）。开启后每次显隐翻转都运行在
+     * `document.startViewTransition(() => flushSync(...))` 里（React 官方
+     * 要求的同步 DOM 更新模式），页面获得原生过渡；命令式 handle、
+     * Esc、遮罩点击等路径共用同一出口。引擎不支持
+     * `startViewTransition` 或用户偏好 `prefers-reduced-motion: reduce`
+     * 时自动退化为直接翻转。过渡外观由消费方的 `::view-transition-*`
+     * 样式定义，组件自身的进退场动画照常运行在新快照内。
+     */
+    viewTransition?: boolean;
+    /**
+     * 开启移动端下滑关闭手势（默认 `false`，不开启时零行为、零 DOM
+     * 差异——不挂任何 pointer 监听）。开启后 sheet 可被 pointer 拖拽
+     * 向下：拖拽实时跟随（`translateY`），松手时超过阈值（`88px` 与
+     * sheet 高度 25% 取小）走既有关闭路径（`onClose` 恰好一次，退场
+     * 动画照常从当前位置滑出），不足阈值则以 `--haze-duration-fast`
+     * 回弹。与内容滚动的冲突按 touch 惯例处理：仅当拖拽起点到 sheet
+     * 之间的滚动容器都已滚到顶部、且方向向下时才接管手势，否则让位给
+     * 原生滚动。手势本身不受 `prefers-reduced-motion` 影响（用户驱动），
+     * 只有回弹动画时长走 motion token（reduce 偏好下自动归零）。
+     */
+    swipeToDismiss?: boolean;
+    /**
+     * 开启虚拟键盘避让（默认 `false`，对标 Base UI Drawer 的
+     * VirtualKeyboardProvider）。开启后监听 `window.visualViewport` 的
+     * `resize`/`scroll`：键盘弹出（视口高度收缩/被上推）时把 sheet 上移
+     * `translateY(-inset)` 并压低最大高度，贴底的 sheet 不被键盘遮住；
+     * 当前 inset 同时以 inline 自定义属性 `--haze-sheet-kb-inset` 暴露
+     * 给消费方 CSS。环境无 `visualViewport`（SSR/jsdom）时静默降级为
+     * `dvh` 基线（`max-height: min(80dvh, 100dvh - inset)`），不抛错。
+     */
+    virtualKeyboard?: boolean;
     children: ReactNode;
     className?: string;
+    ref?: Ref<BottomSheetHandle>;
 } & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
-export default function BottomSheet({ open: openControl, onClose, children, className, ...rest }: BottomSheetProps): import("react").JSX.Element;
-export type { BottomSheetProps };
+export default function BottomSheet({ open: openControl, onClose, viewTransition, swipeToDismiss, virtualKeyboard, children, className, style, ref, ...rest }: BottomSheetProps): import("react").JSX.Element;
+export type { BottomSheetProps, BottomSheetHandle };

package/dist/types/components/BottomSheet/index.d.ts

@@ -1,2 +1,2 @@
 export { default as BottomSheet } from './BottomSheet';
-export type { BottomSheetProps } from './BottomSheet';
+export type { BottomSheetProps, BottomSheetHandle } from './BottomSheet';

package/dist/types/components/Button/Button.d.ts

@@ -1,4 +1,11 @@
 import type { ComponentPropsWithoutRef } from 'react';
+/**
+ * Component-level tokens: Button can be rethemed per-component by setting
+ * `--haze-button-*` custom properties on `:root` or any ancestor —
+ * `--haze-button-height-sm|md|lg`, `--haze-button-font-size-sm|md|lg`,
+ * `--haze-button-radius` (fallbacks and usage documented in ./styles).
+ * ButtonLink and Toggle wear the same skin and follow along.
+ */
 type ButtonProps = {
     variant?: 'solid' | 'outline' | 'ghost';
     size?: 'sm' | 'md' | 'lg';

package/dist/types/components/Button/ButtonLink.d.ts

@@ -16,6 +16,9 @@ import type { ComponentPropsWithoutRef } from 'react';
  * `aria-disabled` (and `tabIndex={-1}` to drop it from the focus
  * order) — ButtonLink styles `aria-disabled` exactly like Button's
  * `:disabled`.
+ *
+ * Component-level theming tokens (`--haze-button-*`) apply here too —
+ * this anchor wears the exact same skin as Button (see ./styles).
  */
 type ButtonLinkProps = {
     variant?: 'solid' | 'outline' | 'ghost';

package/dist/types/components/Button/index.d.ts

@@ -2,3 +2,4 @@ export { default as Button } from './Button';
 export type { ButtonProps } from './Button';
 export { default as ButtonLink } from './ButtonLink';
 export type { ButtonLinkProps } from './ButtonLink';
+export { variants as buttonVariants, sizes as buttonSizes } from './styles';

package/dist/types/components/Button/styles.d.ts

@@ -4,6 +4,23 @@
  * components' visual contract in one place (one edit re-skins both) and
  * keeps component files free of style internals; split-css groups the
  * emitted CSS into `haze-ui/css/button.css` with them.
+ *
+ * ## Component-level tokens
+ *
+ * The skin exposes component-scoped custom properties for per-component
+ * theming. The library never *defines* them — every usage below is a
+ * fallback chain, so the shipped look is the fallback until a consumer
+ * sets the variable on `:root` or any ancestor (scoping is plain CSS
+ * inheritance: set it on a wrapper to retheme only that subtree):
+ *
+ * - `--haze-button-height-sm` / `-md` / `-lg` — height per size
+ *   (fallback `auto`: content-driven, the unchanged shipped look)
+ * - `--haze-button-font-size-sm` / `-md` / `-lg` — label size per size
+ *   (fallbacks `--haze-text-sm` / `--haze-text-sm` / `--haze-text-base`)
+ * - `--haze-button-radius` — corner radius (fallback `--haze-radius-md`)
+ *
+ * `Button`, `ButtonLink`, `Toggle` and the Toolbar items all wear this
+ * skin, so one variable rethemes the whole family.
  */
 export declare const base: import("@linaria/core").LinariaClassName;
 export declare const variants: {

package/dist/types/components/Calendar/Calendar.d.ts

@@ -1,21 +1,85 @@
 import type { ComponentPropsWithoutRef } from 'react';
 import type { ControlOrValue } from 'react-use-control';
+/** Granularity Calendar picks at. Each mode serializes its `value` and
+ * `onSelect` payload to a plain string: `"YYYY-MM-DD"` (date),
+ * `"YYYY-MM"` (month), `"YYYY-Qn"` with n 1–4 (quarter) or `"YYYY"`
+ * (year). */
+type CalendarPickerMode = 'date' | 'month' | 'quarter' | 'year';
 type CalendarProps = {
-    /** Selected date as "YYYY-MM-DD"; empty string means nothing selected. */
+    /**
+     * Granularity the calendar picks at. `"date"` (default) renders the
+     * day grid; `"month"` a 3×4 month grid over one year; `"quarter"`
+     * a 4-quarter grid over one year; `"year"` a 12-year grid stepped a
+     * decade at a time. Values follow each mode's serialization (see
+     * {@link CalendarPickerMode}); `months`, `showWeekNumbers`,
+     * `weekStartsOn` and the range props apply to the day grid only.
+     * @default 'date'
+     */
+    picker?: CalendarPickerMode;
+    /**
+     * Selected value as a plain string whose format follows `picker`:
+     * "YYYY-MM-DD" (date, the default), "YYYY-MM" (month), "YYYY-Qn"
+     * (quarter) or "YYYY" (year). Empty string means nothing selected.
+     */
     value?: ControlOrValue<string>;
-    /** Earliest selectable date ("YYYY-MM-DD"). */
+    /**
+     * Earliest selectable date ("YYYY-MM-DD"). In the month/quarter/year
+     * modes a cell is disabled only when its whole period lies before
+     * `min` (the period's last day < `min`).
+     */
     min?: string;
-    /** Latest selectable date ("YYYY-MM-DD"). */
+    /**
+     * Latest selectable date ("YYYY-MM-DD"). In the month/quarter/year
+     * modes a cell is disabled only when its whole period lies after
+     * `max` (the period's first day > `max`).
+     */
     max?: string;
+    /**
+     * Disables individual cells by predicate, alongside `min`/`max` (a
+     * cell is disabled when either hits). Called with the cell's
+     * representative date as a local-midnight `Date`: the day itself in
+     * the date mode, day 1 of the month in the month mode, day 1 of the
+     * quarter's first month in the quarter mode, January 1 in the year
+     * mode. Disabled cells render natively disabled (inert to clicks,
+     * skipped by keyboard roving).
+     */
+    disabledDate?: (date: Date) => boolean;
     /** BCP 47 locale used for month and weekday formatting. */
     locale?: string;
     /** Explicit first day of the week: 0 = Sunday, 1 = Monday. */
     weekStartsOn?: 0 | 1;
     /**
-     * Called with the picked "YYYY-MM-DD" date. Still fires alongside the
-     * controllable `value` for callers that prefer event-style wiring.
+     * Render a leading ISO 8601 week-number column on every month grid
+     * (labeled "Wk" / localized via the `calendar.weekNumber` string).
+     * @default false
+     */
+    showWeekNumbers?: boolean;
+    /**
+     * Number of adjacent month grids rendered side by side. Both grids
+     * share one navigation state: prev/next, the Today button and the
+     * month quick-select move every grid together, and each grid keeps
+     * its own keyboard roving.
+     * @default 1
+     */
+    months?: 1 | 2;
+    /**
+     * Start of a highlighted date range ("YYYY-MM-DD"), drawn as a filled
+     * endpoint on its day. Purely presentational — range picking logic
+     * stays with the caller (see DateRangePicker's dual-month panel).
+     */
+    rangeStart?: string;
+    /**
+     * End of a highlighted date range ("YYYY-MM-DD"); together with
+     * `rangeStart` fills every day in between with a subtle background.
+     */
+    rangeEnd?: string;
+    /**
+     * Called with the picked value — "YYYY-MM-DD" (date), "YYYY-MM"
+     * (month), "YYYY-Qn" (quarter) or "YYYY" (year), matching `picker`.
+     * Still fires alongside the controllable `value` for callers that
+     * prefer event-style wiring.
      */
     onSelect?: (date: string) => void;
 } & Omit<ComponentPropsWithoutRef<'div'>, 'onSelect'>;
-export default function Calendar({ value: valueControl, min, max, locale, weekStartsOn, onSelect, className, ...rest }: CalendarProps): import("react").JSX.Element;
-export type { CalendarProps };
+export default function Calendar({ picker, value: valueControl, min, max, disabledDate, locale, weekStartsOn, showWeekNumbers, months, rangeStart, rangeEnd, onSelect, className, ...rest }: CalendarProps): import("react").JSX.Element;
+export type { CalendarProps, CalendarPickerMode };

package/dist/types/components/Calendar/date.d.ts

@@ -59,6 +59,18 @@ export declare function getLeadingDays(year: number, month: number, weekStart: n
  * added. The result length is always a multiple of 7.
  */
 export declare function buildMonthCells(year: number, month: number, weekStart: number): CalendarCell[];
+/**
+ * ISO 8601 week number of a civil date. ISO weeks run Monday–Sunday and
+ * week 1 is the week containing the year's first Thursday, so days at the
+ * year's edges borrow the neighbor year's numbering (2025-12-31 is week 1
+ * of 2026; 2027-01-01 is week 53 of 2026). The weekday is read from the
+ * local-midnight Date of the civil triple (a calendar date's weekday is a
+ * civil property, identical in every zone); the day arithmetic then moves
+ * to UTC milliseconds — whole-day multiples with no DST drift — to reach
+ * the week's Thursday, whose year is the ISO year, and counts seven-day
+ * spans from that ISO year's January 1.
+ */
+export declare function getISOWeekNumber(year: number, month: number, day: number): number;
 /**
  * Format a civil date as the `"YYYY-MM-DD"` string Calendar uses as its
  * value. Value semantics: the string denotes the **local** civil date — it
@@ -67,6 +79,46 @@ export declare function buildMonthCells(year: number, month: number, weekStart:
  * behind UTC). Pure string math; no Date construction.
  */
 export declare function formatDate(year: number, month: number, day: number): string;
+/**
+ * Format a month as the `"YYYY-MM"` string Calendar's `picker="month"`
+ * mode uses as its value. Pure string math; no Date construction.
+ */
+export declare function formatMonthValue(year: number, month: number): string;
+/**
+ * Parse a `"YYYY-MM"` month-picker value (`{@link formatMonthValue}`'s
+ * inverse). Returns `null` unless the month is `01`…`12`; anything with
+ * another shape (`"2026-3"`, `"2026-03-15"`, malformed input) is rejected.
+ */
+export declare function parseMonthValue(value: string): {
+    year: number;
+    month: number;
+} | null;
+/**
+ * Format a quarter as the `"YYYY-Qn"` string Calendar's
+ * `picker="quarter"` mode uses as its value, with `quarter` 1-based
+ * (`2026` Q1 → `"2026-Q1"`).
+ */
+export declare function formatQuarterValue(year: number, quarter: number): string;
+/**
+ * Parse a `"YYYY-Qn"` quarter-picker value (`{@link formatQuarterValue}`'s
+ * inverse). Returns `null` unless `n` is 1…4.
+ */
+export declare function parseQuarterValue(value: string): {
+    year: number;
+    quarter: number;
+} | null;
+/**
+ * Format a year as the `"YYYY"` string Calendar's `picker="year"` mode
+ * uses as its value.
+ */
+export declare function formatYearValue(year: number): string;
+/**
+ * Parse a `"YYYY"` year-picker value (`{@link formatYearValue}`'s
+ * inverse). Returns `null` for anything that is not exactly four digits.
+ */
+export declare function parseYearValue(value: string): {
+    year: number;
+} | null;
 /**
  * Parse a `"YYYY-MM-DD"` value string into a local-midnight Date — the
  * inverse of {@link formatDate} and the only safe way to turn a value into

package/dist/types/components/Calendar/index.d.ts

@@ -1,2 +1,2 @@
 export { default as Calendar } from './Calendar';
-export type { CalendarProps } from './Calendar';
+export type { CalendarProps, CalendarPickerMode } from './Calendar';

package/dist/types/components/Cascader/Cascader.d.ts

@@ -1,10 +1,24 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
 import type { ControlOrValue } from 'react-use-control';
 export type CascaderOption = {
     label: ReactNode;
     value: string;
     children?: CascaderOption[];
 };
+/** Metrics override for the `virtualized` columns of Cascader. */
+type CascaderVirtualizedConfig = {
+    /**
+     * Row height in px of one column item. Defaults to 37 — the natural
+     * box of a column item: space-2 padding top+bottom + text-sm at
+     * leading-normal = 8 + 21 + 8. Virtualization math needs it as a JS
+     * number; items are stretched to fill it (`virtualRow`), so the two
+     * cannot drift apart.
+     */
+    itemHeight?: number;
+    /** Extra rows kept mounted above/below the visible window. Defaults
+     * to VirtualList's 5. */
+    overscan?: number;
+};
 type CascaderProps = {
     /** Full option tree; each level becomes one column in the drill-down panel. */
     options: CascaderOption[];
@@ -20,7 +34,38 @@ type CascaderProps = {
     changeOnSelect?: boolean;
     /** Whether hovering a parent option expands its column; defaults to click. */
     expandTrigger?: 'click' | 'hover';
+    /**
+     * Remote search: when set, the panel opens with a search input on top
+     * of the columns and all local option logic defers to the consumer —
+     * typing fires this callback with the raw query (empty queries
+     * included, and the reset back to `''` when the panel closes, so the
+     * consumer can restore the full tree), and the panel simply renders
+     * whatever `options` the consumer rebuilds in response. Selecting
+     * from a rebuilt tree commits the path that tree defines. Pair with
+     * `loading` for the pending state; debouncing is the consumer's
+     * concern.
+     */
+    onSearch?: (query: string) => void;
+    /**
+     * Async option state: the panel's column area shows a Spinner with
+     * `aria-busy="true"` on the panel instead of the (stale) columns
+     * until it clears. Works with or without `onSearch` (lazy root-tree
+     * loads included).
+     */
+    loading?: boolean;
+    /**
+     * Render every column through VirtualList so wide trees mount only
+     * the visible window (plus overscan) per column instead of the full
+     * DOM list. `false`/omitted (default) keeps the plain DOM path
+     * byte-for-byte; an object additionally customizes row metrics.
+     */
+    virtualized?: boolean | CascaderVirtualizedConfig;
     className?: string;
+    /**
+     * Forwarded to the trigger `<button>` (not the root div) — the element
+     * form bridges and `ref.current.focus()` reach.
+     */
+    ref?: Ref<HTMLButtonElement>;
 } & Omit<ComponentPropsWithoutRef<'div'>, 'onChange' | 'className'>;
-export default function Cascader({ options, value: valueControl, onChange, placeholder, changeOnSelect, expandTrigger, className, ...rest }: CascaderProps): import("react").JSX.Element;
-export type { CascaderProps };
+export default function Cascader({ options, value: valueControl, onChange, placeholder, changeOnSelect, expandTrigger, onSearch, loading, virtualized, className, ref, ...rest }: CascaderProps): import("react").JSX.Element;
+export type { CascaderProps, CascaderVirtualizedConfig };

package/dist/types/components/Chart/Chart.d.ts

@@ -0,0 +1,43 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+import type { ChartSeries, ChartTooltipEntry, ChartTooltipPayload, ChartType } from './chart-elements';
+type ChartProps<T> = {
+    /** Which recharts chart family to render. `pie` maps each datum to one
+     * sector named by `xKey` and valued by each series `key`. */
+    type: ChartType;
+    /** One datum per point (pie: per sector); series values are read by
+     * `ChartSeries.key`. */
+    data: T[];
+    /** The series to plot — colors cycle through the semantic status tokens
+     * when `color` is omitted. With `type='pie'` each series is one
+     * concentric ring. */
+    series: ChartSeries[];
+    /** Datum field driving the X axis (pie: naming each sector). */
+    xKey: keyof T & string;
+    /** Container height in px; the chart stretches to the full width. */
+    height?: number;
+    /** Pie only: inner radius in px (or a % string) — above 0 renders a
+     * donut. Multiple pie series band the radial space evenly; a %
+     * `innerRadius` offsets the innermost ring. Default `0`. */
+    innerRadius?: number | string;
+    /** Cartesian charts only: `vertical` swaps the axes for horizontal
+     * bars/lines (ignored by `pie`). Default `'horizontal'`. */
+    layout?: 'horizontal' | 'vertical';
+    /** Replaces the default recharts tooltip. Receives the hovered label
+     * (X value / sector name) plus one entry per series or sector. */
+    renderTooltip?: (payload: ChartTooltipPayload<T>) => ReactNode;
+    /** Renders a recharts Legend naming each series. Default `false`. */
+    showLegend?: boolean;
+    /** Renders background grid lines (cartesian charts only). Default
+     * `true`. */
+    showGrid?: boolean;
+    /** Renders a hover tooltip. Default `true`. */
+    showTooltip?: boolean;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
+/** Token-driven chart over recharts: line, area, bar or pie series
+ * rendered with haze semantic colors, axis/grid/tooltip/legend chrome
+ * toggles, and the default-omittable `series`/`xKey` mapping. recharts is
+ * an optional peer — this module's helpers import it statically, so under
+ * preserveModules only bundles that actually render Chart resolve the
+ * dependency. */
+export default function Chart<T>({ type, data, series, xKey, height, innerRadius, layout, renderTooltip, showLegend, showGrid, showTooltip, className, style, ...rest }: ChartProps<T>): import("react").JSX.Element;
+export type { ChartProps, ChartSeries, ChartTooltipEntry, ChartTooltipPayload, ChartType, };