@choice-ui/react 1.4.0 → 1.4.1

package/dist/index.d.ts

@@ -1,3 +1,2 @@
 export * from './components';
-export * from './shared/hooks';
-export * from './shared/utils';
+export * from "./shared"

package/dist/shared/index.d.ts

@@ -0,0 +1,420 @@
+import * as React$1 from 'react';
+import { useLayoutEffect, MutableRefObject, SetStateAction, PointerEvent as PointerEvent$1, KeyboardEvent, ReactNode, ComponentType, ReactElement } from 'react';
+import cx from 'classnames';
+import { TV } from 'tailwind-variants';
+export { TV, TVReturnType, VariantProps } from 'tailwind-variants';
+
+/**
+ * 创建一个始终保持最新值的稳定引用
+ *
+ * 这个 Hook 解决了闭包中访问过期值的问题，确保在回调函数中始终能访问到最新的 props 或 state。
+ * 它会在每次渲染时同步更新 ref 的值，但 ref 对象本身保持不变。
+ *
+ * @param data - 需要保持最新引用的数据
+ * @returns 包含最新数据的稳定引用对象
+ *
+ * @example
+ * ```tsx
+ * const Component = ({ onClick }) => {
+ *   const onClickRef = useAsRef(onClick)
+ *
+ *   const handleClick = useCallback(() => {
+ *     // 总是调用最新的 onClick 函数
+ *     onClickRef.current?.()
+ *   }, [onClickRef])
+ *
+ *   return <button onClick={handleClick}>Click me</button>
+ * }
+ * ```
+ */
+declare function useAsRef<T>(data: T): React$1.MutableRefObject<T>;
+
+/**
+ * 同构布局效果 Hook
+ *
+ * 这个 Hook 解决了 SSR（服务端渲染）环境中 useLayoutEffect 的兼容性问题。
+ * 在浏览器环境中使用 useLayoutEffect，在服务端环境中使用 useEffect。
+ *
+ * useLayoutEffect 在 DOM 更新后同步执行，适用于需要同步读取 DOM 布局信息的场景。
+ * 但在服务端环境中，window 对象不存在，使用 useLayoutEffect 会产生警告。
+ *
+ * @example
+ * ```tsx
+ * const Component = () => {
+ *   const [height, setHeight] = useState(0)
+ *   const ref = useRef<HTMLDivElement>(null)
+ *
+ *   useIsomorphicLayoutEffect(() => {
+ *     if (ref.current) {
+ *       // 同步读取 DOM 尺寸信息
+ *       setHeight(ref.current.offsetHeight)
+ *     }
+ *   }, [])
+ *
+ *   return <div ref={ref}>高度: {height}px</div>
+ * }
+ * ```
+ */
+declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;
+
+type Direction = "ltr" | "rtl";
+/**
+ * 文本方向上下文
+ *
+ * 用于在组件树中传递文本方向信息（从左到右或从右到左）
+ */
+declare const DirectionContext: React$1.Context<Direction | undefined>;
+/**
+ * 获取文本方向的 Hook
+ *
+ * 这个 Hook 用于确定组件的文本方向，支持国际化应用。
+ * 优先级：props > context > 默认值(ltr)
+ *
+ * @param dirProp - 通过 props 传入的方向值
+ * @returns 最终确定的文本方向
+ *
+ * @example
+ * ```tsx
+ * const Component = ({ dir }) => {
+ *   const direction = useDirection(dir)
+ *
+ *   return (
+ *     <div dir={direction}>
+ *       {direction === 'rtl' ? 'من اليمين إلى اليسار' : 'Left to Right'}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useDirection(dirProp?: Direction): Direction;
+
+declare function useDisableScroll({ ref }: {
+    ref: React.RefObject<HTMLDivElement>;
+}): {
+    disableScrollProps: {
+        onFocus: () => void;
+        onBlur: () => void;
+        onMouseEnter: () => void;
+        onMouseLeave: () => void;
+    };
+};
+
+/**
+ * 懒加载引用 Hook
+ *
+ * 这个 Hook 用于延迟初始化一个引用值，只有在第一次访问时才会执行初始化函数。
+ * 适用于创建成本较高的对象（如 Map、Set、复杂对象等）。
+ *
+ * 与 useState 的懒加载不同，这个 Hook 创建的是一个稳定的引用，
+ * 不会触发组件重新渲染，适用于需要在多次渲染间保持同一个对象实例的场景。
+ *
+ * @param fn - 初始化函数，只会在第一次调用时执行
+ * @returns 包含初始化值的稳定引用对象
+ *
+ * @example
+ * ```tsx
+ * const Component = () => {
+ *   // 只在第一次渲染时创建 Map 实例
+ *   const mapRef = useLazyRef(() => new Map<string, any>())
+ *
+ *   const addItem = (key: string, value: any) => {
+ *     mapRef.current!.set(key, value)
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => addItem('key1', 'value1')}>
+ *         添加项目
+ *       </button>
+ *       <p>Map 大小: {mapRef.current!.size}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useLazyRef<T>(fn: () => T): MutableRefObject<T>;
+
+/**
+ * useMergedValue 钩子的配置选项
+ * @template T - 状态值的类型
+ */
+type Options<T> = {
+    /**
+     * 是否允许使用空值。当设置为 true 时，
+     * 即使所有值源都是 undefined，也不会显示警告。
+     */
+    allowEmpty?: boolean;
+    /**
+     * 内部状态的默认值，当 value 和 defaultValue 都未提供时使用。
+     * 可以是一个值或返回值的函数（惰性初始化）。
+     */
+    defaultStateValue?: T | (() => T);
+    /**
+     * 非受控模式下的初始值。仅在组件首次渲染时使用。
+     * 只有在未提供 value 时才会使用此值。
+     */
+    defaultValue?: T;
+    /**
+     * 值变化时的回调函数。
+     * 在受控模式下，此回调应更新 value。
+     */
+    onChange?: (value: T) => void;
+    /**
+     * 当尝试设置与当前值相同的值时触发的回调。
+     */
+    onUnchange?: () => void;
+    /**
+     * 受控模式下的值。提供此参数会使组件进入受控模式。
+     * 在受控模式下，组件状态完全由此值控制。
+     */
+    value?: T;
+};
+/**
+ * 合并受控和非受控状态的 Hook
+ *
+ * 该 Hook 处理组件的受控和非受控两种模式：
+ * - 受控模式：当提供 value 时，组件状态完全由外部控制
+ * - 非受控模式：当仅提供 defaultValue 时，组件内部维护自己的状态
+ *
+ * @template T - 状态值的类型
+ * @param options - 配置选项
+ * @returns [currentValue, setValue] - 当前值和设置值的函数
+ */
+declare function useMergedValue<T>(options: Options<T>): readonly [T, (this: any, v: SetStateAction<T>, forceTrigger?: any) => void];
+
+/**
+ * 处理键盘修饰键状态的钩子
+ * @param disabled 是否禁用键盘监听
+ * @returns 修饰键状态
+ */
+declare function useModifierKeys(disabled?: boolean): {
+    shiftPressed: boolean;
+    metaPressed: boolean;
+    ctrlPressed: boolean;
+};
+
+type PressEvent = PointerEvent$1<HTMLElement> | KeyboardEvent<HTMLElement>;
+type PressProps = {
+    disabled?: boolean;
+    onPress?: (event: PressEvent) => void;
+    onPressEnd?: (event: PressEvent) => void;
+    onPressStart?: (event: PressEvent) => void;
+};
+declare function usePress({ disabled, onPress, onPressStart, onPressEnd }: PressProps): {
+    isPressed: boolean;
+    pressProps: {
+        onPointerDown: (event: PointerEvent$1<HTMLElement>) => void;
+        onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+        onKeyUp: (event: KeyboardEvent<HTMLElement>) => void;
+    };
+};
+
+type PressMoveProps = PressProps & {
+    disabled?: boolean;
+    onPressEnd?: (e: PointerEvent) => void;
+    onPressMove?: (e: PointerEvent) => void;
+    onPressMoveBottom?: (delta: number) => void;
+    onPressMoveLeft?: (delta: number) => void;
+    onPressMoveRight?: (delta: number) => void;
+    onPressMoveTop?: (delta: number) => void;
+    onPressStart?: (e: PointerEvent) => void;
+};
+interface PressMoveResult {
+    isPressed: boolean;
+    pressMoveProps: {
+        onPointerDown: (e: React.PointerEvent<HTMLElement>) => void;
+        ref: (el: HTMLElement | null) => void;
+        style?: React.CSSProperties;
+    };
+}
+declare const usePressMove: ({ onPressMove, onPressMoveLeft, onPressMoveRight, onPressMoveTop, onPressMoveBottom, onPressStart, onPressEnd, ...rest }: PressMoveProps) => PressMoveResult;
+
+declare const tcx: (...args: cx.ArgumentArray) => string;
+declare const tcv: TV;
+
+interface Props {
+    [key: string]: unknown;
+}
+type PropsArg = Props | null | undefined;
+type TupleTypes<T> = {
+    [P in keyof T]: T[P];
+} extends {
+    [key: number]: infer V;
+} ? NullToObject<V> : never;
+type NullToObject<T> = T extends null | undefined ? object : T;
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+ * Merges multiple props objects together. Event handlers are chained,
+ * classNames are combined, and ids are deduplicated.
+ * For all other props, the last prop object overrides all previous ones.
+ * @param args - Multiple sets of props to merge together.
+ */
+declare function mergeProps<T extends PropsArg[]>(...args: T): UnionToIntersection<TupleTypes<T>>;
+
+type ReactRef<T> = React$1.RefObject<T> | React$1.MutableRefObject<T> | React$1.Ref<T>;
+/**
+ * Assigns a value to a ref function or object
+ *
+ * @param ref the ref to assign to
+ * @param value the value
+ */
+declare function assignRef<T>(ref: ReactRef<T> | undefined, value: T | null): void;
+/**
+ * Combine multiple React refs into a single ref function.
+ * This is used mostly when you need to allow consumers forward refs to
+ * internal components
+ *
+ * @param refs refs to assign to value to
+ */
+declare function mergeRefs<T>(...refs: (ReactRef<T> | undefined)[]): (node: T | null) => void;
+
+declare function assert(condition: unknown, message?: string): asserts condition;
+declare function assertNever(value: never, message?: string): never;
+type Dict<T = unknown> = Record<string, T>;
+declare function isArray<T>(value: unknown): value is Array<T>;
+declare function isEmptyArray(value: unknown): boolean;
+declare function isObject(value: unknown): value is Dict;
+declare function isEmptyObject(value: unknown): boolean;
+declare function isEmpty(value: unknown): boolean;
+declare function isFunction<T extends (...args: unknown[]) => unknown = (...args: unknown[]) => unknown>(value: unknown): value is T;
+type Booleanish = boolean | "true" | "false";
+declare const dataAttr: (condition: boolean | undefined) => Booleanish;
+declare const isNumeric: (value?: string | number) => boolean;
+declare const isMultiElement: (children: ReactNode) => boolean;
+declare const findChildByType: (children: ReactNode, componentType: ComponentType<any>) => ReactElement | null;
+
+declare function formatBytes(bytes: number): string;
+
+type SupportedLanguage = "en" | "cn" | "ja" | "ko" | "es" | "fr" | "de" | "pt" | "ru" | "ar";
+interface TimezoneOptions {
+    referenceTime?: Date;
+    useUTC?: boolean;
+}
+interface CustomFormatOptions {
+    fullDate?: string;
+    monthDay?: string;
+    time?: string;
+}
+interface FormatRelativeTimeOptions {
+    customFormat?: CustomFormatOptions;
+    daysThreshold?: number;
+    forceNumericFormat?: boolean;
+    language?: SupportedLanguage;
+    showSpecificTime?: boolean;
+    timezone?: TimezoneOptions;
+    yearThreshold?: number;
+}
+
+/**
+ * Formats a date into a human-readable relative time string with internationalization support
+ *
+ * @param date - The date to format
+ * @param options - Configuration options for formatting
+ * @returns A formatted date string
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * formatRelativeTime(new Date()) // "a few seconds ago"
+ *
+ * // With Chinese locale
+ * formatRelativeTime(new Date(), { language: "cn" }) // "几秒前"
+ *
+ * // Show specific time for recent dates
+ * formatRelativeTime(new Date(), {
+ *   showSpecificTime: true,
+ *   language: "en"
+ * }) // "Today at 2:30 PM"
+ *
+ * // Custom thresholds
+ * formatRelativeTime(oldDate, {
+ *   daysThreshold: 30,
+ *   yearThreshold: 2
+ * })
+ * ```
+ */
+declare const formatRelativeTime: (date: Date, options?: FormatRelativeTimeOptions) => string;
+/**
+ * Creates a date formatter with default configuration
+ *
+ * @param defaultOptions - Default options to use for all formatting operations
+ * @returns A configured formatter function
+ *
+ * @example
+ * ```typescript
+ * const formatter = createDateFormatter({
+ *   language: "cn",
+ *   daysThreshold: 14,
+ *   showSpecificTime: true
+ * })
+ *
+ * formatter(new Date()) // Uses configured defaults
+ * formatter(new Date(), { language: "en" }) // Overrides language
+ * ```
+ */
+declare const createDateFormatter: (defaultOptions?: FormatRelativeTimeOptions) => (date: Date, options?: FormatRelativeTimeOptions) => string;
+/**
+ * Formats a date to a simple readable format
+ *
+ * @param date - The date to format
+ * @param options - Formatting options
+ * @returns A simple formatted date string
+ *
+ * @example
+ * ```typescript
+ * formatSimpleDate(new Date()) // "Jan 15, 2024"
+ * formatSimpleDate(new Date(), { language: "cn" }) // "2024年1月15日"
+ * ```
+ */
+declare const formatSimpleDate: (date: Date, options?: Pick<FormatRelativeTimeOptions, "language" | "customFormat">) => string;
+/**
+ * Formats time only from a date
+ *
+ * @param date - The date to extract time from
+ * @param options - Formatting options
+ * @returns A formatted time string
+ *
+ * @example
+ * ```typescript
+ * formatTime(new Date()) // "2:30 PM"
+ * formatTime(new Date(), { language: "cn" }) // "14:30"
+ * ```
+ */
+declare const formatTime: (date: Date, options?: Pick<FormatRelativeTimeOptions, "language" | "customFormat">) => string;
+
+/**
+ * 通用 i18n 工具系统
+ * 提供简洁的API，无需为每个组件单独封装Hook
+ */
+/**
+ * 深度合并两个对象，用户配置会覆盖默认配置
+ */
+declare const mergeI18nConfig: <T extends Record<string, unknown>>(defaultConfig: T, userConfig?: Partial<T>) => T;
+/**
+ * 通用的 i18n Hook，自动缓存合并结果
+ * 直接使用，无需为每个组件单独封装
+ *
+ * @example
+ * const i18n = useI18n(defaultConfig, userConfig)
+ */
+declare const useI18n: <T extends Record<string, unknown>>(defaultConfig: T, userConfig?: Partial<T>) => T;
+/**
+ * 从嵌套对象中安全获取值，支持点号路径
+ * @example getI18nText(i18n, 'url.placeholder') // 获取 i18n.url.placeholder
+ */
+declare const getI18nText: <T extends Record<string, unknown>>(i18n: T, path: string, fallback?: string) => string;
+
+/**
+ * Check if code is running in browser environment
+ */
+declare const isBrowser: boolean;
+/**
+ * SSR-safe window access helper
+ */
+declare function getWindow(): Window | undefined;
+/**
+ * SSR-safe document access helper
+ */
+declare function getDocument(): Document | undefined;
+
+export { type Dict, DirectionContext, type FormatRelativeTimeOptions, type PressMoveProps, type PressMoveResult, type PressProps, type ReactRef, type SupportedLanguage, assert, assertNever, assignRef, createDateFormatter, dataAttr, findChildByType, formatBytes, formatRelativeTime, formatSimpleDate, formatTime, getDocument, getI18nText, getWindow, isArray, isBrowser, isEmpty, isEmptyArray, isEmptyObject, isFunction, isMultiElement, isNumeric, isObject, mergeI18nConfig, mergeProps, mergeRefs, tcv, tcx, useAsRef, useDirection, useDisableScroll, useI18n, useIsomorphicLayoutEffect, useLazyRef, useMergedValue, useModifierKeys, usePress, usePressMove };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@choice-ui/react",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "A desktop-first React UI component library built for professional desktop applications with comprehensive documentation",
   "sideEffects": false,
   "type": "module",
@@ -113,7 +113,7 @@
     "react-dom": ">=18.0.0"
   },
   "scripts": {
-    "build": "pnpm run clean && vite build",
+    "build": "pnpm run clean && pnpm --filter @choice-ui/shared build && vite build",
     "build:watch": "vite build --watch",
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,css,md}\"",
     "lint": "eslint --ignore-path .gitignore --cache --cache-location ./node_modules/.cache/eslint .",