@wisdomgarden/torque 0.1.0

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

@@ -0,0 +1,211 @@
+import React from 'react';
+export type PopoverSide = 'top' | 'right' | 'bottom' | 'left';
+export type PopoverPlacement = 'start' | 'end';
+export type PopoverPosition = PopoverSide | `${PopoverSide}-${PopoverPlacement}`;
+/** `'none'`：不注入任何事件处理，由外层组件完全控制开关（Combobox 等受控场景） */
+export type PopoverTrigger = 'click' | 'hover' | 'none';
+export type PopoverStrategy = 'absolute' | 'fixed';
+export type PopoverRadius = 'xs' | 'sm' | 'md' | 'lg';
+export interface PopoverProps {
+    /**
+     * 需要包裹的子节点，即 `<Popover.Target>` 和 `<Popover.Dropdown>`
+     */
+    children: React.ReactNode;
+    /**
+     * 弹出方向
+     * @default 'bottom'
+     */
+    position?: PopoverPosition;
+    /**
+     * 弹出框与触发元素的间距（px）
+     * @default 8
+     */
+    offset?: number;
+    /**
+     * 受控模式：是否展开
+     */
+    opened?: boolean;
+    /**
+     * 非受控模式：初始是否展开
+     * @default false
+     */
+    defaultOpened?: boolean;
+    /**
+     * 展开状态变更回调
+     */
+    onOpenChange?: (opened: boolean) => void;
+    /**
+     * 是否禁用
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 是否显示箭头
+     * @default false
+     */
+    withArrow?: boolean;
+    /**
+     * 箭头尺寸（px）
+     * @default 8
+     */
+    arrowSize?: number;
+    /**
+     * 触发方式
+     * hover方式无法支持无障碍，请慎用
+     * @default 'click'
+     */
+    trigger?: PopoverTrigger;
+    /**
+     * 点击外部区域时关闭
+     * @default true
+     */
+    closeOnClickOutside?: boolean;
+    /**
+     * 按下 Escape 键时关闭当前栈顶浮层；嵌套时保留外层浮层。
+     * @default true
+     */
+    closeOnEscape?: boolean;
+    /**
+     * Escape 关闭后恢复焦点的方法；默认直接聚焦 Popover Target。
+     * 当 Target 的可聚焦节点会随关闭状态变化时，可传入延迟恢复方法。
+     */
+    restoreFocus?: () => void;
+    /**
+     * CSS 定位策略
+     * @default 'absolute'
+     */
+    strategy?: PopoverStrategy;
+    /**
+     * 打开时将焦点送到指定元素（click 触发模式下生效）。
+     * 不传时默认落到浮层内 DOM 顺序第一个可聚焦元素；若 ref.current 为 null
+     * 也会回退到该默认行为。典型用法：日历默认聚焦到当前日期格而非"上一月"按钮。
+     */
+    initialFocusRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * 是否在浮层内做 Tab 焦点陷阱：
+     * Tab 到最后一个可聚焦元素后继续按 Tab 会循环回第一个，Shift+Tab 反之。
+     * 用于复合内容浮层（日期 / 时间选择器等），避免键盘用户 Tab 出浮层后迷路。
+     * @default false
+     */
+    trapFocus?: boolean;
+    /**
+     * 阻止浮层打开时自动将焦点转移到浮层内部。
+     * 使用 `aria-activedescendant` 模式的组件（如 Combobox）需要焦点始终留在触发区，
+     * 必须将此项设为 `true`。
+     * @default false
+     */
+    preventAutoFocus?: boolean;
+    /**
+     * 浮层 `role="dialog"` 的可访问名字：指向含标题的元素 id。
+     * 不传时读屏只会报"dialog"而没有上下文；建议为复合浮层提供。
+     */
+    'aria-labelledby'?: string;
+}
+/**
+ * 所有 HTML 属性均可传入。`onClick` 会与内部开关逻辑合并执行（内部先，用户后）；
+ * 其余属性直接覆盖内部默认值（如 `aria-haspopup`、`aria-label` 等）。
+ */
+export interface PopoverTargetProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+    /**
+     * 触发弹出框的元素（应该是一个有效的 DOM 元素）
+     */
+    children: React.ReactNode;
+    ref?: React.Ref<any>;
+}
+/**
+ * 除以下自定义 props 外，所有标准 HTML 属性均可传入并覆盖浮层容器的内部默认值。
+ * 例如：传入 `role={undefined}` 可移除默认的 `role="dialog"`（适用于 Combobox 等场景）。
+ */
+export interface PopoverDropdownProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * 弹出框内容
+     */
+    children: React.ReactNode;
+    /**
+     * 箭头自定义 className
+     */
+    arrowClassName?: string;
+    /**
+     * 浮层 z-index
+     * 默认使用项目 Popover 层级 300；嵌套浮层在父层实际层级上递增。
+     * @default 300
+     */
+    zIndex?: number;
+    /**
+     * 弹出框宽度
+     */
+    width?: number | string;
+    /**
+     * 弹出框最大高度。number 按 px 处理。
+     * 仅设置 max-height、不附带 overflow——内容滚动请由内部滚动容器处理，
+     * 或自行通过 className 配置 overflow（与 withArrow 同用时箭头会被裁切）。
+     */
+    maxHeight?: number | string;
+    /**
+     * 是否自动设置弹出框宽度等于触发元素的宽度
+     * @default false
+     */
+    matchTargetWidth?: boolean;
+    /**
+     * 弹出框圆角
+     * @default 'sm'
+     */
+    radius?: PopoverRadius;
+    /**
+     * 是否将浮层渲染到 `Portal` 中（挂到 body）。
+     * 嵌套 Popover 会自动登记 Portal 浮层关系，父层能够识别子浮层交互。
+     * @default true
+     */
+    withinPortal?: boolean;
+    /**
+     * 关闭时是否保留浮层内容挂载。
+     * 适用于内容需要在首次打开前完成数据加载或副作用注册的场景。
+     * @default false
+     */
+    keepMounted?: boolean;
+    ref?: React.Ref<HTMLDivElement>;
+}
+export interface PopoverContextValue {
+    opened: boolean;
+    setOpen: (next: boolean) => void;
+    toggle: () => void;
+    trigger: PopoverTrigger;
+    disabled: boolean;
+    id: string;
+    withArrow: boolean;
+    arrowSize: number;
+    x: number | null;
+    y: number | null;
+    strategy: PopoverStrategy;
+    resolvedSide: PopoverSide;
+    middlewareData: {
+        arrow?: {
+            x?: number;
+            y?: number;
+        };
+        hide?: {
+            referenceHidden?: boolean;
+            escaped?: boolean;
+        };
+    };
+    hoverTimerRef: React.MutableRefObject<number | undefined>;
+    referenceRef: React.RefObject<HTMLElement | null>;
+    floatingRef: React.RefObject<HTMLDivElement | null>;
+    arrowRef: React.RefObject<HTMLDivElement | null>;
+    setReference: (node: HTMLElement | null) => void;
+    setFloating: (node: HTMLDivElement | null) => void;
+    /** 当前 Popover 的逻辑嵌套深度，用于浮层层级和 Escape 栈排序 */
+    depth: number;
+    /** 将后代 Portal 浮层登记到当前 Popover 的交互与焦点范围中 */
+    registerNestedFloatingElement: (element: HTMLElement) => () => void;
+    /** 返回当前浮层及所有已登记后代浮层，用于外部点击与焦点判断 */
+    getFloatingScopeElements: () => HTMLElement[];
+    /** 外部传入的初始焦点目标；`usePopoverFocus` 有值时优先聚焦该元素 */
+    initialFocusRef?: React.RefObject<HTMLElement | null>;
+    /** 是否启用 Tab 焦点陷阱（由 `PopoverDropdown` 渲染哨兵节点实现） */
+    trapFocus: boolean;
+    /** 阻止浮层打开时自动将焦点转移到浮层内部（Combobox 等 aria-activedescendant 场景使用） */
+    preventAutoFocus: boolean;
+    /** dialog 的 `aria-labelledby` id；由 `PopoverDropdown` 写到 role="dialog" 元素上 */
+    ariaLabelledby?: string;
+}

package/dist/components/popover/styles/popover.module.css.js

@@ -0,0 +1,12 @@
+"use client";
+const a = "_popover_15v5e_2", e = "_arrow_15v5e_78", o = "_fallbackTarget_15v5e_109", r = {
+  popover: a,
+  arrow: e,
+  fallbackTarget: o
+};
+export {
+  e as arrow,
+  r as default,
+  o as fallbackTarget,
+  a as popover
+};

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

@@ -0,0 +1,8 @@
+export declare const Radio: {
+    ({ ref, ...props }: import("./radio.types").RadioProps): import("react").JSX.Element;
+    displayName: string;
+} & {
+    Group: ({ ref, ...props }: import("./radio.types").RadioGroupProps) => import("react").JSX.Element;
+};
+export * from './radio.types';
+export * from './radio-group';

package/dist/components/radio/index.js

@@ -0,0 +1,12 @@
+"use client";
+import { Radio as o } from "./radio.js";
+import { RadioGroup as i } from "./radio-group.js";
+import { useRadioContext as s } from "./radio-group.js";
+const a = Object.assign(o, {
+  Group: i
+});
+export {
+  a as Radio,
+  i as RadioGroup,
+  s as useRadioContext
+};

package/dist/components/radio/radio-group.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import { RadioContextValue, RadioGroupProps } from './radio.types';
+export declare const useRadioContext: () => RadioContextValue | null;
+/**
+ * RadioGroup 组件
+ *
+ * 用于管理一组 `Radio` 组件的状态，支持受控和非受控模式。
+ * 配合 `FormItemWrapper` 提供表单项的标签、必填、错误提示等功能。
+ *
+ * @example
+ * ```tsx
+ * <RadioGroup label="选择项" value={value} onChange={setValue}>
+ *   <Radio value="1" label="选项1" />
+ *   <Radio value="2" label="选项2" />
+ * </RadioGroup>
+ * ```
+ */
+export declare const RadioGroup: ({ ref, ...props }: RadioGroupProps) => React.JSX.Element;

package/dist/components/radio/radio-group.js

@@ -0,0 +1,54 @@
+"use client";
+import { jsx as r } from "react/jsx-runtime";
+import { useId as i, useUncontrolled as R } from "@mantine/hooks";
+import { clsx as y } from "clsx";
+import { useCallback as P, useMemo as V, useContext as F, createContext as G } from "react";
+import { useFormWrapperProps as N } from "../../common/use-form-wrapper-props.js";
+import { FormItemWrapper as W } from "../form-wrapper/form-item-wrapper.js";
+import _ from "./radio.module.css.js";
+const s = G(null), q = () => F(s), z = ({ ref: d, ...e }) => {
+  const o = i(e.id), { wrapProps: u, rest: c, outerDescribedBy: m, labelId: p } = N(
+    e,
+    o
+  ), {
+    children: C,
+    value: b,
+    defaultValue: f,
+    onChange: h,
+    name: g,
+    id: j,
+    groupClassName: x
+  } = {
+    ...c
+  }, a = i(g), [t, l] = R({
+    value: b,
+    defaultValue: f,
+    finalValue: "",
+    onChange: h
+  }), n = P(
+    (I) => {
+      l(I.currentTarget.value);
+    },
+    [l]
+  ), v = V(
+    () => ({ name: a, value: t, onChange: n }),
+    [a, t, n]
+  );
+  return /* @__PURE__ */ r(W, { ...u, id: o, children: /* @__PURE__ */ r(s.Provider, { value: v, children: /* @__PURE__ */ r(
+    "div",
+    {
+      ref: d,
+      role: "radiogroup",
+      id: o,
+      "aria-label": e["aria-label"],
+      "aria-labelledby": p,
+      "aria-describedby": m,
+      className: y(_.radioGroup, x),
+      children: C
+    }
+  ) }) });
+};
+export {
+  z as RadioGroup,
+  q as useRadioContext
+};

package/dist/components/radio/radio-variables.module.css.js

@@ -0,0 +1,8 @@
+"use client";
+const s = "_radioVars_1d13l_2", a = {
+  radioVars: s
+};
+export {
+  a as default,
+  s as radioVars
+};

package/dist/components/radio/radio.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { RadioProps } from './radio.types';
+/**
+ * 基础 Radio 组件
+ *
+ * 单选框组件，通常与 `RadioGroup` 配合使用。
+ * 支持单独使用，支持受控和非受控模式。
+ *
+ * @example
+ * ```tsx
+ * <Radio value="1" label="选项1" />
+ * ```
+ */
+export declare const Radio: {
+    ({ ref, ...props }: RadioProps): React.JSX.Element;
+    displayName: string;
+};

package/dist/components/radio/radio.js

@@ -0,0 +1,56 @@
+"use client";
+import { jsxs as R, jsx as n } from "react/jsx-runtime";
+import { useId as j } from "@mantine/hooks";
+import { clsx as e } from "clsx";
+import { useRadioContext as v } from "./radio-group.js";
+import w from "./radio-variables.module.css.js";
+import s from "./radio.module.css.js";
+const y = ({ ref: t, ...o }) => {
+  const {
+    id: m,
+    className: h,
+    wrapperClassName: p,
+    label: r,
+    checked: u,
+    onChange: C,
+    name: N,
+    value: l,
+    color: b = "brand",
+    labelClassName: f,
+    ...x
+  } = o, a = v(), c = j(m), d = a ? a.value === l : u, g = (i) => {
+    a?.onChange(i), C?.(i);
+  }, k = a?.name ?? N;
+  return /* @__PURE__ */ R("div", { className: e(s.wrapper, p), children: [
+    /* @__PURE__ */ n(
+      "input",
+      {
+        ...x,
+        "data-color": b,
+        ref: t,
+        type: "radio",
+        id: c,
+        name: k,
+        value: l,
+        checked: d,
+        onChange: g,
+        className: e(h, s.radio, w.radioVars),
+        "aria-checked": d
+      }
+    ),
+    r && // eslint-disable-next-line jsx-a11y/label-has-for
+    /* @__PURE__ */ n(
+      "label",
+      {
+        htmlFor: c,
+        "data-disabled": o.disabled,
+        className: e(s.label, f),
+        children: r
+      }
+    )
+  ] });
+};
+y.displayName = "Radio";
+export {
+  y as Radio
+};

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

@@ -0,0 +1,14 @@
+"use client";
+const r = "_wrapper_4ugrz_2", a = "_radioGroup_4ugrz_7", o = "_radio_4ugrz_7", _ = "_label_4ugrz_78", e = {
+  wrapper: r,
+  radioGroup: a,
+  radio: o,
+  label: _
+};
+export {
+  e as default,
+  _ as label,
+  o as radio,
+  a as radioGroup,
+  r as wrapper
+};

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

@@ -0,0 +1,59 @@
+import React from 'react';
+import { CommonColor, FormProps, InputWrapProps, RefProps } from '../../common/components.types';
+export type RadioColor = Omit<CommonColor, 'gray'>;
+export interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>, InputWrapProps, FormProps, RefProps<HTMLDivElement> {
+    /**
+     * 当前选中的值（受控模式）
+     */
+    value?: string;
+    /**
+     * 非受控状态下的默认值
+     */
+    defaultValue?: string;
+    /**
+     * 原生 input 标签的 name 属性，如果不传内部会自动生成唯一的 id 作为 name，确保一组单选框互斥
+     */
+    name?: string;
+    /**
+     * 选中值改变时的回调事件
+     */
+    onChange?: (value: string) => void;
+    /**
+     * 内部一般是 Radio 组件
+     */
+    children?: React.ReactNode;
+    /**
+     * 用于修改内部 Radio 列表的布局样式（如设置为 flex 布局）
+     */
+    groupClassName?: string;
+}
+export interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'color'>, RefProps<HTMLInputElement> {
+    /**
+     * 选择框右侧的文字描述
+     */
+    label?: React.ReactNode;
+    /**
+     * 外层容器的自定义类名
+     */
+    wrapperClassName?: string;
+    /**
+     * label 的自定义类名
+     */
+    labelClassName?: string;
+    /** 颜色 */
+    color?: RadioColor;
+}
+export interface RadioContextValue {
+    /**
+     * 原生 input 标签的 name 属性。
+     */
+    name: string;
+    /**
+     * 当前选中的值
+     */
+    value: string | undefined;
+    /**
+     * input 改变的回传事件。
+     */
+    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+}

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

@@ -0,0 +1,3 @@
+export { Select } from './select';
+export type { SelectProps, SelectOptions, } from '../_inner/base-select/common/select.types';
+export type { OptionsDropDownEmptyState } from '../_inner/dropdown/options-drop-down';

package/dist/components/select/index.js

@@ -0,0 +1,5 @@
+"use client";
+import { Select as c } from "./select.js";
+export {
+  c as Select
+};

package/dist/components/select/select.d.ts

@@ -0,0 +1,15 @@
+import { SelectProps } from '../_inner/base-select/common/select.types';
+/**
+ * 基础 Select 单选组件
+ *
+ * 提供了单选和搜索单选的功能。
+ * 会根据设备类型自动适配 Web 端的下拉框（Dropdown）或 Mobile 端的底部抽屉（BottomAction）。
+ * 支持 `FormItemWrapper` 提供的表单包裹功能（label, error, required 等）。
+ *
+ * 不传 `searchable` 时，选项数达到 `SEARCHABLE_OPTION_THRESHOLD` 会自动开启搜索；
+ * 显式传入的 `true` / `false` 优先级更高。
+ */
+export declare const Select: {
+    (props: SelectProps): import("react").JSX.Element;
+    displayName: string;
+};

package/dist/components/select/select.js

@@ -0,0 +1,48 @@
+"use client";
+import { jsx as r } from "react/jsx-runtime";
+import { useId as f } from "@mantine/hooks";
+import "../../provider/ui-context.js";
+import "react";
+import { useDeviceType as d } from "../../provider/hooks.js";
+import { resolveSearchable as S } from "../_inner/base-select/common/searchable.js";
+import { SearchSelect as u } from "../_inner/base-select/search-select/index.js";
+import { SingleSelect as b } from "../_inner/base-select/single-select/single-select.js";
+import { SingleSelectTarget as c } from "../_inner/base-select/target/single-select-target.js";
+import { getFormProps as l } from "../base-input/util.js";
+import { SelectMobile as g } from "./select.mobile.js";
+const T = (e) => {
+  const { borderRadius: t = "full" } = e, { deviceType: n } = d(), a = n == "mobile", o = f(e.id), m = S(e.searchable, e.options);
+  return a ? /* @__PURE__ */ r(
+    g,
+    {
+      ...e,
+      id: o,
+      popoverTitle: e.placeholder,
+      borderRadius: t,
+      ...l(e, e.onClear),
+      searchable: m,
+      renderTarget: (i) => /* @__PURE__ */ r(c, { ...i })
+    }
+  ) : m ? /* @__PURE__ */ r(
+    u,
+    {
+      ...e,
+      id: o,
+      borderRadius: t,
+      ...l(e, e.onClear)
+    }
+  ) : /* @__PURE__ */ r(
+    b,
+    {
+      ...e,
+      id: o,
+      ...l(e, e.onClear),
+      borderRadius: t,
+      renderTarget: (i) => /* @__PURE__ */ r(c, { ...i })
+    }
+  );
+};
+T.displayName = "Select";
+export {
+  T as Select
+};

package/dist/components/select/select.mobile.d.ts

@@ -0,0 +1,12 @@
+import { SelectProps } from '../_inner/base-select/common/select.types';
+export type SelectMobileProps = SelectProps & {
+    readonly renderTarget?: (props: SelectMobileProps) => React.ReactNode;
+    readonly popoverTitle?: string;
+};
+/**
+ * 移动端 Select 内部实现
+ *
+ * 将选项列表渲染为底部动作面板（BottomAction）。
+ * 仅供内部或明确需要在移动端强制渲染时使用。
+ */
+export declare const SelectMobile: (props: SelectMobileProps) => import("react").JSX.Element;

package/dist/components/select/select.mobile.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsx as i } from "react/jsx-runtime";
+import { useUncontrolled as h } from "@mantine/hooks";
+import { useFormWrapperProps as g } from "../../common/use-form-wrapper-props.js";
+import "../../provider/ui-context.js";
+import "react";
+import { useLocale as v } from "../../provider/hooks.js";
+import { BottomAction as y } from "../_inner/bottom-action/bottom-action.js";
+import { FormItemWrapper as S } from "../form-wrapper/form-item-wrapper.js";
+const L = (e) => {
+  const a = v(), { wrapProps: n, rest: c, outerDescribedBy: d } = g(
+    e,
+    e.id
+  ), {
+    popoverTitle: o,
+    renderOption: m,
+    emptyState: C,
+    searchable: s,
+    ...u
+  } = c, [l, f] = h({
+    value: e.value,
+    defaultValue: e.defaultValue,
+    finalValue: "",
+    onChange: e.onChange
+  }), b = e.options.find((t) => t.value === l)?.label ?? "", p = (t) => {
+    f(t);
+  };
+  return /* @__PURE__ */ i(
+    y,
+    {
+      renderOption: m,
+      selectType: "single",
+      value: l,
+      searchable: s,
+      title: o ?? a.pleaseSelect,
+      triggerAriaLabel: e["aria-label"] ?? o ?? a.pleaseSelect,
+      disabled: e.disabled,
+      actionItems: e.options.map((t) => ({ ...t })),
+      onClick: (t, r) => {
+        r.value != null && p(r.value);
+      },
+      children: /* @__PURE__ */ i(S, { ...n, id: e.id, children: e.renderTarget?.({
+        ...u,
+        value: l,
+        displayValue: b,
+        "aria-describedby": d
+      }) })
+    }
+  );
+};
+export {
+  L as SelectMobile
+};

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

@@ -0,0 +1 @@
+export { Stack } from './stack';

package/dist/components/stack/index.js

@@ -0,0 +1,5 @@
+"use client";
+import { Stack as c } from "./stack.js";
+export {
+  c as Stack
+};

package/dist/components/stack/stack.d.ts

@@ -0,0 +1,6 @@
+import { LayoutElement } from '../box/box.types';
+import type { StackProps } from '../flex/layout.types';
+/**
+ * 垂直堆叠容器。默认横向拉伸、`md` 间距。
+ */
+export declare function Stack<T extends LayoutElement = 'div'>(props: StackProps<T>): import("react").JSX.Element;

package/dist/components/stack/stack.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as e } from "react/jsx-runtime";
+import { Flex as n } from "../flex/flex.js";
+function m(t) {
+  const { gap: r = "md", ...o } = t;
+  return /* @__PURE__ */ e(n, { direction: "column", align: "stretch", gap: r, ...o });
+}
+export {
+  m as Stack
+};

package/dist/components/sticky-box.d.ts

@@ -0,0 +1,2 @@
+import { type StickyBoxCompProps } from '../common/use-sticky-box';
+export declare const StickyBox: (props: StickyBoxCompProps) => import("react").JSX.Element;

package/dist/components/sticky-box.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as m } from "react/jsx-runtime";
+import { useStickyBox as n } from "../common/use-sticky-box.js";
+const x = (o) => {
+  const { offsetTop: t, offsetBottom: e, bottom: s, children: r, className: c, style: f } = o, i = n({ offsetTop: t, offsetBottom: e, bottom: s });
+  return /* @__PURE__ */ m("div", { className: c, style: f, ref: i, children: r });
+};
+export {
+  x as StickyBox
+};

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

@@ -0,0 +1,4 @@
+export { Switch } from './switch';
+export { SwitchGroup } from './switch-group';
+export type { SwitchProps } from './switch';
+export type { SwitchGroupProps } from './switch-group';