@wisdomgarden/torque 0.1.0

package/dist/components/checkbox/checkbox.module.css.js

@@ -0,0 +1,12 @@
+"use client";
+const e = "_wrapper_16kmo_2", c = "_checkbox_16kmo_7", o = "_label_16kmo_120", a = {
+  wrapper: e,
+  checkbox: c,
+  label: o
+};
+export {
+  c as checkbox,
+  a as default,
+  o as label,
+  e as wrapper
+};

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

@@ -0,0 +1,41 @@
+import React from 'react';
+import { CommonColor, FormProps, InputWrapProps, RefProps } from '../../common/components.types';
+export type CheckboxColor = Omit<CommonColor, 'gray'>;
+export interface CheckboxGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, InputWrapProps, FormProps, RefProps<HTMLDivElement> {
+    /** 当前选中的值的列表 */
+    value?: string[];
+    /** 非受控状态下的默认值 */
+    defaultValue?: string[];
+    /** 值改变的回调事件 */
+    onChange?: (value: string[]) => void;
+    /** input标签的 的 name字段，默认会随机赋值 */
+    name?: string;
+    /** 一般是Checkbox组件 */
+    children?: React.ReactNode;
+    /** 可以用来修改group的布局 */
+    groupClassName?: string;
+}
+export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'form' | 'color'>, RefProps<HTMLInputElement> {
+    /** 选择框右边的文字 */
+    label?: React.ReactNode;
+    /** 半选状态 */
+    indeterminate?: boolean;
+    /** 外层容器的自定义类名 */
+    wrapperClassName?: string;
+    /**
+     * label 的自定义类名
+     */
+    labelClassName?: string;
+    /** 颜色 */
+    color?: CheckboxColor;
+    /** 仅渲染复选框视觉，不输出可交互 input；用于 option 等已有交互语义的容器内。 */
+    visualOnly?: boolean;
+}
+export interface CheckboxContextValue {
+    /** input标签的 的 name字段, 如果有Group，则不需要指定 */
+    name: string;
+    /** 当前选中的值 */
+    value: string[] | undefined;
+    /** input改变的回传事件, 如果有Group，则不需要指定 */
+    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+}

package/dist/components/checkbox/index.d.ts

@@ -0,0 +1,3 @@
+export * from './checkbox.types';
+export * from './checkbox';
+export * from './checkbox-group';

package/dist/components/checkbox/index.js

@@ -0,0 +1,8 @@
+"use client";
+import { Checkbox as x } from "./checkbox.js";
+import { CheckboxContext as t, CheckboxGroup as c } from "./checkbox-group.js";
+export {
+  x as Checkbox,
+  t as CheckboxContext,
+  c as CheckboxGroup
+};

package/dist/components/combobox/combobox-context.d.ts

@@ -0,0 +1,9 @@
+import type { ComboboxOptionProps } from './combobox.types';
+import type { ComboboxStore } from './hooks/use-combobox';
+export interface ComboboxContextValue {
+    store: ComboboxStore;
+    listboxId: string;
+    onOptionSubmit: (value: string | number, optionProps: ComboboxOptionProps) => void;
+}
+export declare const ComboboxContext: import("react").Context<ComboboxContextValue | null>;
+export declare function useComboboxContext(): ComboboxContextValue;

package/dist/components/combobox/combobox-context.js

@@ -0,0 +1,15 @@
+"use client";
+import { useContext as t, createContext as e } from "react";
+const n = e(null);
+function x() {
+  const o = t(n);
+  if (!o)
+    throw new Error(
+      "Combobox compound components must be used within <Combobox>"
+    );
+  return o;
+}
+export {
+  n as ComboboxContext,
+  x as useComboboxContext
+};

package/dist/components/combobox/combobox-dropdown.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { PopoverDropdownProps } from '../popover/popover.types';
+type ComboboxDropdownProps = Omit<PopoverDropdownProps, 'role'> & {
+    /** 移动端 BottomDrawer 标题，桌面端忽略 */
+    readonly title?: string;
+};
+/**
+ * 桌面端：包装 Popover.Dropdown，移除默认的 role="dialog"。
+ * 移动端：渲染 BottomDrawer，opened/onClose 由 ComboboxContext 控制。
+ * Combobox 的列表语义由内层 Combobox.Options 的 role="listbox" 承担。
+ */
+export declare function ComboboxDropdown({ children, title, ...rest }: ComboboxDropdownProps): React.JSX.Element;
+export {};

package/dist/components/combobox/combobox-dropdown.js

@@ -0,0 +1,35 @@
+"use client";
+import { jsx as m } from "react/jsx-runtime";
+import { clsx as s } from "clsx";
+import "../../provider/ui-context.js";
+import "react";
+import { useDeviceType as i, useLocale as a } from "../../provider/hooks.js";
+import { PopoverDropdown as c } from "../popover/popover-dropdown.js";
+import l from "./styles/combobox.module.css.js";
+import { ComboboxBottomDrawerDropdown as n } from "./subs/combobox-bottom-drawer-dropdown.js";
+function y({
+  children: o,
+  title: r,
+  ...e
+}) {
+  const { deviceType: p } = i(), t = a();
+  return p !== "desktop" ? /* @__PURE__ */ m(
+    n,
+    {
+      title: r,
+      "aria-label": r ?? t.pleaseSelect,
+      children: o
+    }
+  ) : /* @__PURE__ */ m(
+    c,
+    {
+      role: void 0,
+      ...e,
+      className: s(l.dropdown, e.className),
+      children: o
+    }
+  );
+}
+export {
+  y as ComboboxDropdown
+};

package/dist/components/combobox/combobox-infinite-dropdown.d.ts

@@ -0,0 +1,51 @@
+import React from 'react';
+import { PopoverDropdownProps } from '../popover/popover.types';
+export type ComboboxInfiniteDropdownProps = Omit<PopoverDropdownProps, 'children'> & {
+    /** 移动端 BottomDrawer 标题，桌面端忽略 */
+    readonly title?: string;
+    /** 是否还有下一页；为 `false` 时不渲染哨兵，也不再触发回调 */
+    readonly hasMore: boolean;
+    /** 是否正在加载下一页；为 `true` 时阻止重复触发 */
+    readonly loading?: boolean;
+    /** 哨兵进入滚动容器可视区且 `hasMore && !loading` 时触发，业务在此加载下一页 */
+    readonly onLoadMore: () => void;
+    /** 底部加载态插槽，默认 `<Loader type="dots" size="sm" />` */
+    readonly loadingIndicator?: React.ReactNode;
+    /** 提前触发距离（px），作用于滚动容器底部 @default 200 */
+    readonly threshold?: number;
+    /** 透传给内部 `Combobox.Options` 的 className */
+    readonly optionsClassName?: string;
+    /** 固定在选项滚动区之上的节点，常用于下拉内搜索框（不随选项滚动） */
+    readonly header?: React.ReactNode;
+    /** 选项节点（`Combobox.Option` 列表，或空态提示） */
+    readonly children: React.ReactNode;
+};
+/**
+ * 带无限滚动能力的 Combobox 下拉。
+ *
+ * 在 `Combobox.Dropdown` + `Combobox.Options` 基础上，于列表底部放置哨兵节点，
+ * 当其进入滚动容器可视区且 `hasMore && !loading` 时调用 `onLoadMore`。
+ * 仅封装「滚动到底 → 回调」能力，**不负责**取数、搜索、选中等业务逻辑。
+ *
+ * @example
+ * ```tsx
+ * <Combobox store={combobox} onOptionSubmit={handleSubmit}>
+ *   <Combobox.Target targetType="input">
+ *     <TextInput value={search} onChange={handleSearch} />
+ *   </Combobox.Target>
+ *   <Combobox.InfiniteDropdown
+ *     hasMore={hasMore}
+ *     loading={loadingMore}
+ *     onLoadMore={loadMore}
+ *     loadingIndicator={<Loader type="dots" size="sm" />}
+ *   >
+ *     {results.map(item => (
+ *       <Combobox.Option key={item.id} value={item.id}>
+ *         {item.name}
+ *       </Combobox.Option>
+ *     ))}
+ *   </Combobox.InfiniteDropdown>
+ * </Combobox>
+ * ```
+ */
+export declare function ComboboxInfiniteDropdown({ children, hasMore, loading, onLoadMore, loadingIndicator, threshold, optionsClassName, header, ...rest }: ComboboxInfiniteDropdownProps): React.JSX.Element;

package/dist/components/combobox/combobox-infinite-dropdown.js

@@ -0,0 +1,56 @@
+"use client";
+import { jsxs as l, jsx as p } from "react/jsx-runtime";
+import { Loader as C } from "@mantine/core";
+import { useRef as E, useCallback as d, useEffect as v, useLayoutEffect as y } from "react";
+import { ComboboxDropdown as R } from "./combobox-dropdown.js";
+import { ComboboxOptions as a } from "./combobox-options.js";
+import D from "./styles/combobox.module.css.js";
+const S = 200, u = (e) => {
+  if (!e || e === document.body || e === document.documentElement)
+    return null;
+  const { overflowY: t } = window.getComputedStyle(e);
+  return t === "auto" || t === "scroll" || t === "overlay" ? e : u(e.parentElement);
+};
+function k({
+  children: e,
+  hasMore: t,
+  loading: o = !1,
+  onLoadMore: f,
+  loadingIndicator: b = /* @__PURE__ */ p(C, { type: "dots", size: "sm" }),
+  threshold: r = S,
+  optionsClassName: x,
+  header: g,
+  ...w
+}) {
+  const s = E(null), c = d(() => {
+    !o && t && f();
+  }, [o, t, f]);
+  return v(() => {
+    const n = s.current;
+    if (!n || !t) return;
+    const i = new IntersectionObserver(
+      (m) => {
+        m[0]?.isIntersecting && c();
+      },
+      {
+        root: u(n),
+        rootMargin: `0px 0px ${r}px 0px`
+      }
+    );
+    return i.observe(n), () => i.disconnect();
+  }, [t, r, c]), y(() => {
+    const n = s.current;
+    if (o || !t || !n) return;
+    const i = u(n), m = i ? i.getBoundingClientRect().bottom + r : window.innerHeight + r;
+    n.getBoundingClientRect().top <= m && c();
+  }, [o, t, r, c]), /* @__PURE__ */ l(R, { ...w, children: [
+    g,
+    /* @__PURE__ */ l(a, { className: x, children: [
+      e,
+      t && /* @__PURE__ */ p("div", { ref: s, className: D.infiniteSentinel, children: o ? b : null })
+    ] })
+  ] });
+}
+export {
+  k as ComboboxInfiniteDropdown
+};

package/dist/components/combobox/combobox-option.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import { ComboboxOptionProps } from './combobox.types';
+export declare function ComboboxOption(props: ComboboxOptionProps): React.JSX.Element;

package/dist/components/combobox/combobox-option.js

@@ -0,0 +1,50 @@
+"use client";
+import { jsx as f } from "react/jsx-runtime";
+import { clsx as x } from "clsx";
+import { useId as v } from "react";
+import { useComboboxContext as C } from "./combobox-context.js";
+import M from "./styles/combobox.module.css.js";
+function w(t) {
+  const {
+    value: n,
+    children: i,
+    active: s = !1,
+    disabled: e = !1,
+    className: a,
+    onClick: r,
+    onMouseDown: d,
+    onMouseEnter: l,
+    ...c
+  } = t, { onOptionSubmit: m } = C(), u = v(), b = (o) => {
+    e || m(n, t), r?.(o);
+  }, p = (o) => {
+    l?.(o);
+  };
+  return (
+    // eslint-disable-next-line jsx-a11y/click-events-have-key-events
+    /* @__PURE__ */ f(
+      "div",
+      {
+        ...c,
+        id: u,
+        role: "option",
+        tabIndex: -1,
+        "aria-selected": s,
+        "aria-disabled": e || void 0,
+        "data-value": n,
+        "data-combobox-disabled": e ? "true" : void 0,
+        "data-combobox-selected": s ? "true" : void 0,
+        className: x(M.option, a),
+        onMouseDown: (o) => {
+          o.preventDefault(), d?.(o);
+        },
+        onClick: b,
+        onMouseEnter: p,
+        children: i
+      }
+    )
+  );
+}
+export {
+  w as ComboboxOption
+};

package/dist/components/combobox/combobox-options.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import { ComboboxOptionsProps } from './combobox.types';
+/**
+ * 复合框选项列表组件 (ComboboxOptions)
+ *
+ * 作为选项 (`ComboboxOption`) 的直接父容器，提供 `role="listbox"` 的无障碍列表语义。
+ */
+export declare function ComboboxOptions({ children, className, ...restProps }: ComboboxOptionsProps): React.JSX.Element;

package/dist/components/combobox/combobox-options.js

@@ -0,0 +1,38 @@
+"use client";
+import { jsx as a } from "react/jsx-runtime";
+import { clsx as p } from "clsx";
+import { useLayoutEffect as x } from "react";
+import { useComboboxContext as f } from "./combobox-context.js";
+import g from "./styles/combobox.module.css.js";
+function I({
+  children: u,
+  className: m,
+  ...n
+}) {
+  const { listboxId: e, store: s } = f(), i = n["aria-multiselectable"], c = i === !0 || i === "true";
+  return x(() => {
+    if (!s.opened) return;
+    const t = document.getElementById(e), o = t?.querySelector(
+      "[data-combobox-selected]"
+    );
+    if (!t || !o) return;
+    if (c) {
+      o.scrollIntoView({ block: "nearest" });
+      return;
+    }
+    const l = t.getBoundingClientRect(), r = o.getBoundingClientRect(), b = r.top + r.height / 2, d = l.top + l.height / 2;
+    t.scrollTop += b - d;
+  }, [s.opened, e, c]), /* @__PURE__ */ a(
+    "div",
+    {
+      ...n,
+      role: "listbox",
+      id: e,
+      className: p(g.options, m),
+      children: u
+    }
+  );
+}
+export {
+  I as ComboboxOptions
+};

package/dist/components/combobox/combobox-search.d.ts

@@ -0,0 +1,27 @@
+import { ComboboxSearchProps } from './combobox.types';
+/**
+ * 复合框内嵌搜索框 (ComboboxSearch)
+ *
+ * 放置在 Combobox.Target 内部，在下拉展开时自动聚焦，同时阻止点击事件冒泡，
+ * 防止触发父级的开关逻辑。上下箭头和 Enter 通过事件冒泡由外层 Combobox.Target
+ * 统一处理，Escape 交给 Popover 浮层栈处理。
+ *
+ * @example
+ * ```tsx
+ * <Combobox.Target>
+ *   <BaseInputWrapper component={opened ? 'div' : 'button'} pointer={!opened}>
+ *     {opened ? (
+ *       <Combobox.Search
+ *         value={search}
+ *         placeholder="搜索学生姓名"
+ *         aria-label="搜索学生"
+ *         onChange={e => setSearch(e.target.value)}
+ *       />
+ *     ) : (
+ *       <span>{selected?.name ?? '请选择'}</span>
+ *     )}
+ *   </BaseInputWrapper>
+ * </Combobox.Target>
+ * ```
+ */
+export declare function ComboboxSearch({ onClick, onKeyDown, ...props }: ComboboxSearchProps): import("react").JSX.Element;

package/dist/components/combobox/combobox-search.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as m } from "react/jsx-runtime";
+import { useRef as u, useEffect as c } from "react";
+import { BaseInputTarget as f } from "../base-input/subs/base-input-target.js";
+import { useComboboxContext as i } from "./combobox-context.js";
+import { useComboboxSearchInput as a } from "./hooks/use-combobox-search-input.js";
+function I({
+  onClick: e,
+  onKeyDown: n,
+  ...s
+}) {
+  const { store: o } = i(), r = u(null), p = a(n);
+  return c(() => {
+    o.opened && r.current?.focus();
+  }, [o.opened]), /* @__PURE__ */ m(
+    f,
+    {
+      ref: r,
+      ...s,
+      ...p,
+      onClick: (t) => {
+        t.stopPropagation(), e?.(t);
+      }
+    }
+  );
+}
+export {
+  I as ComboboxSearch
+};

package/dist/components/combobox/combobox-target.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import { ComboboxTargetProps } from './combobox.types';
+/**
+ * 复合框触发器组件 (ComboboxTarget)
+ *
+ * 包裹触发下拉面板的元素（如输入框、按钮等）。
+ * 内部会克隆子元素，注入 `role="combobox"` 及相关 `aria-*` 属性，并接管键盘和鼠标交互事件。
+ * - 桌面端：处理聚焦、点击及完整的键盘导航（上下箭头、回车等）。
+ * - 移动端：屏蔽原生焦点事件，仅处理点击行为，避免在抽屉关闭时焦点归还导致意外重新打开。
+ *
+ * @param targetType
+ * - `'button'`（默认）：点击 toggle（适用于只读 trigger，如按钮、Select）
+ * - `'input'`：点击只开不关（适用于可编辑搜索框，避免用户输入时意外关闭）
+ */
+export declare function ComboboxTarget({ children, targetType, }: ComboboxTargetProps): React.JSX.Element;

package/dist/components/combobox/combobox-target.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsx as s } from "react/jsx-runtime";
+import x, { useRef as g } from "react";
+import "../../provider/ui-context.js";
+import { useDeviceType as D } from "../../provider/hooks.js";
+import { PopoverTarget as h } from "../popover/popover-target.js";
+import { useComboboxContext as w } from "./combobox-context.js";
+import { useComboboxTargetKeyDown as C } from "./hooks/use-combobox-target-key-down.js";
+import { ComboboxBottomDrawerTarget as P } from "./subs/combobox-bottom-drawer-target.js";
+function I({
+  children: n,
+  targetType: t = "button"
+}) {
+  const { deviceType: e } = D();
+  return e !== "desktop" ? /* @__PURE__ */ s(P, { children: n }) : /* @__PURE__ */ s(y, { targetType: t, children: n });
+}
+function y({ children: n, targetType: t }) {
+  const { store: e, listboxId: m } = w(), { targetRef: u, opened: c, highlightedOptionId: a } = e, { handleKeyDown: f } = C(t), r = g(!1), p = n, i = p.props, l = (o) => {
+    i.onKeyDown?.(o), o.defaultPrevented || f(o);
+  }, d = x.cloneElement(p, {
+    role: "combobox",
+    "aria-expanded": c,
+    ...a && c ? { "aria-activedescendant": a } : {},
+    onPointerDown(o) {
+      i.onPointerDown?.(o), r.current = !0;
+    },
+    onFocus(o) {
+      i.onFocus?.(o);
+      const b = r.current;
+      r.current = !1, !b && t === "input" && e.open();
+    },
+    onClick(o) {
+      i.onClick?.(o), r.current = !1, t === "input" ? e.open() : e.toggle();
+    }
+  });
+  return /* @__PURE__ */ s(
+    h,
+    {
+      ref: u,
+      "aria-haspopup": "listbox",
+      "aria-controls": m,
+      onKeyDown: l,
+      children: d
+    }
+  );
+}
+export {
+  I as ComboboxTarget
+};

package/dist/components/combobox/combobox.d.ts

@@ -0,0 +1,61 @@
+import React from 'react';
+import { ComboboxDropdown } from './combobox-dropdown';
+import { ComboboxInfiniteDropdown } from './combobox-infinite-dropdown';
+import { ComboboxOption } from './combobox-option';
+import { ComboboxOptions } from './combobox-options';
+import { ComboboxSearch } from './combobox-search';
+import { ComboboxTarget } from './combobox-target';
+import { ComboboxProps } from './combobox.types';
+/**
+ * 复合框组件 (Combobox)
+ *
+ * 结合输入框/按钮和下拉列表的复合交互组件。
+ * - 桌面端：以气泡卡片 (Popover) 形式展示下拉列表。
+ * - 移动端：忽略 Popover，通过 BottomDrawer 展示列表。
+ *
+ * 不传 `store` 时内部自动管理状态；传入 `useCombobox()` 创建的 store
+ * 可在组件外部调用 `store.open/close/toggle`。
+ *
+ * 选项提交后默认关闭下拉并将焦点归还给 Target；多选等需要连续操作的场景
+ * 使用 `selectionBehavior="keepOpen"` 保持展开及当前焦点。
+ *
+ * @example
+ * ```tsx
+ * // 单选：默认关闭并归还焦点
+ * const combobox = useCombobox();
+ * <Combobox store={combobox} onOptionSubmit={(val) => {
+ *   setValue(val);
+ * }}>
+ *   <Combobox.Target>
+ *     <Button>选择</Button>
+ *   </Combobox.Target>
+ *   <Combobox.Dropdown>
+ *     <Combobox.Options>
+ *       <Combobox.Option value="1">选项 1</Combobox.Option>
+ *     </Combobox.Options>
+ *   </Combobox.Dropdown>
+ * </Combobox>
+ *
+ * // 多选：选中后保持展开
+ * const combobox = useCombobox();
+ * <Combobox
+ *   store={combobox}
+ *   selectionBehavior="keepOpen"
+ *   onOptionSubmit={(val) => toggleValue(val)}
+ * >
+ *   <Combobox.Target targetType="input">
+ *     <BaseInput onBlur={combobox.close} onChange={handleSearch} />
+ *   </Combobox.Target>
+ *   ...
+ * </Combobox>
+ * ```
+ */
+export declare function Combobox({ store: storeProp, onOptionSubmit, selectionBehavior, position, children, }: ComboboxProps): React.JSX.Element;
+export declare namespace Combobox {
+    var Target: typeof ComboboxTarget;
+    var Dropdown: typeof ComboboxDropdown;
+    var InfiniteDropdown: typeof ComboboxInfiniteDropdown;
+    var Options: typeof ComboboxOptions;
+    var Option: typeof ComboboxOption;
+    var Search: typeof ComboboxSearch;
+}

package/dist/components/combobox/combobox.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsx as e } from "react/jsx-runtime";
+import { useId as C, useCallback as g, useMemo as v } from "react";
+import "../../provider/ui-context.js";
+import { useDeviceType as O } from "../../provider/hooks.js";
+import { Popover as T } from "../popover/index.js";
+import { ComboboxContext as c } from "./combobox-context.js";
+import { ComboboxDropdown as D } from "./combobox-dropdown.js";
+import { ComboboxInfiniteDropdown as w } from "./combobox-infinite-dropdown.js";
+import { ComboboxOption as I } from "./combobox-option.js";
+import { ComboboxOptions as S } from "./combobox-options.js";
+import { ComboboxSearch as h } from "./combobox-search.js";
+import { ComboboxTarget as F } from "./combobox-target.js";
+import { useCombobox as P } from "./hooks/use-combobox.js";
+function r({
+  store: f,
+  onOptionSubmit: m,
+  selectionBehavior: n = "close",
+  position: u = "bottom-start",
+  children: i
+}) {
+  const { deviceType: a } = O(), x = a !== "desktop", d = P(), o = f ?? d, p = C(), s = g(
+    (t, l) => {
+      m?.(t, l), n === "close" && (o.close(), o.focusTarget());
+    },
+    [m, n, o]
+  ), b = v(
+    () => ({ store: o, listboxId: p, onOptionSubmit: s }),
+    [o, p, s]
+  );
+  return x ? /* @__PURE__ */ e(c.Provider, { value: b, children: i }) : /* @__PURE__ */ e(c.Provider, { value: b, children: /* @__PURE__ */ e(
+    T,
+    {
+      position: u,
+      opened: o.opened,
+      onOpenChange: (t) => t ? o.open() : o.close(),
+      preventAutoFocus: !0,
+      trapFocus: !1,
+      trigger: "none",
+      restoreFocus: o.focusTarget,
+      children: i
+    }
+  ) });
+}
+r.Target = F;
+r.Dropdown = D;
+r.InfiniteDropdown = w;
+r.Options = S;
+r.Option = I;
+r.Search = h;
+export {
+  r as Combobox
+};

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

@@ -0,0 +1,58 @@
+import React from 'react';
+import type { PopoverPosition } from '../popover/popover.types';
+import type { ComboboxStore } from './hooks/use-combobox';
+export type { ComboboxStore, UseComboboxOptions } from './hooks/use-combobox';
+/** 复合框内嵌搜索框属性，支持所有标准 HTML input 属性 */
+export interface ComboboxSearchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    /** 显示错误样式 */
+    error?: boolean | string;
+}
+/** 复合框组件属性 */
+export interface ComboboxProps {
+    /**
+     * 外部 store（由 `useCombobox()` 创建）。
+     * 传入时可在组件外部调用 `store.open/close/toggle`；
+     * 不传时 Combobox 内部自动创建。
+     */
+    store?: ComboboxStore;
+    /**
+     * 选中某项后的回调，第二个参数为该 Option 的完整 props。
+     */
+    onOptionSubmit?: (value: string | number, optionProps: ComboboxOptionProps) => void;
+    /**
+     * 选项提交后的行为：
+     * - `'close'`：关闭下拉并将焦点归还给 Target
+     * - `'keepOpen'`：保持下拉展开及当前焦点
+     * @default 'close'
+     */
+    selectionBehavior?: 'close' | 'keepOpen';
+    /** PC 端浮层位置，移动端忽略。@default 'bottom-start' */
+    position?: PopoverPosition;
+    children: React.ReactNode;
+}
+/** 复合框触发器属性 */
+export interface ComboboxTargetProps {
+    /** 单个 React 元素，会被注入 ref、aria-*、事件 */
+    children: React.ReactElement;
+    /**
+     * trigger 类型，决定 onClick 的开关行为：
+     * - `'button'`（默认）：点击 toggle（开→关，关→开）
+     * - `'input'`：点击只开不关（下拉搜索框等场景）
+     * @default 'button'
+     */
+    targetType?: 'button' | 'input';
+}
+/** 复合框选项列表属性 */
+export interface ComboboxOptionsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'role' | 'id' | 'children'> {
+    children: React.ReactNode;
+}
+/** 复合框单项属性 */
+export interface ComboboxOptionProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'role' | 'id' | 'aria-selected' | 'aria-disabled' | 'children'> {
+    /** 选中时传给 onOptionSubmit 的值，数字会被自动转为字符串 */
+    value: string | number;
+    children: React.ReactNode;
+    /** 是否为当前选中项，渲染为 aria-selected */
+    active?: boolean;
+    /** 禁用该项（键盘导航跳过，点击无效） */
+    disabled?: boolean;
+}

package/dist/components/combobox/hooks/use-combobox-search-input.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+/**
+ * 为 Dropdown 内的搜索输入框提供与 Combobox Target 一致的键盘导航和 ARIA 绑定。
+ */
+export declare function useComboboxSearchInput(userOnKeyDown?: React.KeyboardEventHandler<HTMLInputElement>): {
+    onKeyDown: React.KeyboardEventHandler<HTMLInputElement>;
+    'aria-activedescendant'?: string | undefined;
+    role: "combobox";
+    'aria-expanded': boolean;
+    'aria-controls': string;
+};