@yh-ui/hooks 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,259 @@
+import * as vue from 'vue';
+import { Ref, InjectionKey, ComputedRef, ShallowRef, MaybeRef } from 'vue';
+import { Language } from '@yh-ui/locale';
+export { Language } from '@yh-ui/locale';
+
+declare const defaultNamespace = "yh";
+declare const namespaceContextKey: InjectionKey<Ref<string>>;
+/**
+ * 获取全局命名空间
+ */
+declare const useGlobalNamespace: () => Ref<string, string>;
+/**
+ * useNamespace - 生成 BEM 类名
+ * @param block - 块名称
+ * @returns BEM 类名生成器
+ *
+ * @example
+ * const ns = useNamespace('button')
+ * ns.b() // 'yh-button'
+ * ns.e('icon') // 'yh-button__icon'
+ * ns.m('primary') // 'yh-button--primary'
+ * ns.is('disabled') // 'is-disabled'
+ * ns.bem('box', 'item', 'active') // 'yh-button-box__item--active'
+ */
+declare const useNamespace: (block: string) => {
+    namespace: Ref<string, string>;
+    b: (blockSuffix?: string) => string;
+    e: (element?: string) => string;
+    m: (modifier?: string) => string;
+    bem: (blockSuffix?: string, element?: string, modifier?: string) => string;
+    em: (element?: string, modifier?: string) => string;
+    is: (state: string, value?: boolean) => string;
+    cssVar: (name: string) => string;
+    cssVarObj: (vars: Record<string, string>) => Record<string, string>;
+    cssVarBlock: (name: string) => string;
+    cssVarBlockObj: (vars: Record<string, string>) => Record<string, string>;
+};
+type UseNamespaceReturn = ReturnType<typeof useNamespace>;
+
+declare const zIndexContextKey: InjectionKey<Ref<number | undefined>>;
+declare const zIndexCounterKey: InjectionKey<{
+    current: number;
+}>;
+declare const getNextZIndex: () => number;
+/**
+ * 重置 z-index 计数器
+ */
+declare const resetZIndex: (value?: number) => void;
+/**
+ * 创建 z-index 计数器（用于 provide）
+ */
+declare const createZIndexCounter: (initialValue?: number) => {
+    current: number;
+};
+/**
+ * useZIndex - z-index 管理
+ * @param zIndexOverrides - 可选的自定义 z-index
+ * @returns z-index 相关方法
+ *
+ * @example
+ * const { currentZIndex, nextZIndex } = useZIndex()
+ */
+declare const useZIndex: (zIndexOverrides?: Ref<number>) => {
+    initialZIndex: vue.ComputedRef<number>;
+    currentZIndex: vue.ComputedRef<number>;
+    nextZIndex: () => number;
+};
+type UseZIndexReturn = ReturnType<typeof useZIndex>;
+
+/**
+ * 获取 dayjs locale code
+ */
+declare const getDayjsLocale: (localeCode: string) => string;
+/**
+ * 动态加载并设置 dayjs locale
+ * 使用动态导入来按需加载，避免打包所有语言
+ */
+declare const setDayjsLocale: (localeCode: string) => Promise<void>;
+/**
+ * 同步设置 dayjs locale（不推荐，会阻塞）
+ * 用于需要立即同步的场景
+ */
+declare const setDayjsLocaleSync: (localeCode: string) => void;
+/**
+ * 使用自定义月份名称更新 dayjs locale
+ * 这样可以确保 dayjs 使用我们语言包中定义的月份名称
+ */
+declare const updateDayjsMonths: (localeCode: string, months: {
+    jan: string;
+    feb: string;
+    mar: string;
+    apr: string;
+    may: string;
+    jun: string;
+    jul: string;
+    aug: string;
+    sep: string;
+    oct: string;
+    nov: string;
+    dec: string;
+}) => void;
+
+/**
+ * useLocale - 国际化
+ * @param localeOverrides - 可选的自定义语言包
+ * @returns 国际化相关方法
+ */
+declare const useLocale: (localeOverrides?: Ref<Language>) => {
+    locale: vue.ComputedRef<Language>;
+    lang: vue.ComputedRef<string>;
+    t: (path: string, options?: Record<string, string | number>) => string;
+    tRaw: <T = unknown>(path: string) => T;
+};
+type UseLocaleReturn = ReturnType<typeof useLocale>;
+
+declare const idInjectionKey: InjectionKey<Ref<string | undefined>>;
+/**
+ * useId - 生成唯一 ID
+ * @param idOverrides - 可选的自定义 ID 前缀
+ * @returns 唯一 ID
+ *
+ * @example
+ * const id = useId() // 'yh-id-1' (or vue native id)
+ * const customId = useId(ref('custom')) // 'custom'
+ */
+declare const useId: (idOverrides?: Ref<string | undefined>) => Ref<string>;
+/**
+ * useIdInjection - ID 注入工具
+ * @description 用于组件内部生成关联 ID
+ */
+declare const useIdInjection: () => {
+    prefix: vue.ComputedRef<string>;
+    current: number;
+};
+type UseIdReturn = ReturnType<typeof useId>;
+
+interface FormContext {
+    model: Record<string, unknown>;
+    rules?: Record<string, unknown>;
+    labelWidth?: string | number;
+    labelPosition?: string;
+    labelSuffix?: string;
+    showMessage?: boolean;
+    scrollToError?: boolean;
+    scrollIntoViewOptions?: boolean | ScrollIntoViewOptions;
+    disabled?: boolean;
+    size?: string;
+    statusIcon?: boolean;
+    layout?: string;
+    addField: (field: FormItemContext) => void;
+    removeField: (field: FormItemContext) => void;
+    themeOverrides?: Record<string, unknown>;
+}
+interface FormItemContext {
+    prop: string;
+    validate: (trigger: string, callback?: (isValid: boolean) => void) => Promise<boolean | unknown>;
+    resetField: () => void;
+    clearValidate: () => void;
+    validateStatus: string;
+    validateMessage: string;
+    label: string;
+    errorId?: string;
+    inputId?: string;
+    size?: string;
+    disabled?: boolean;
+}
+declare const FormContextKey: InjectionKey<FormContext>;
+declare const FormItemContextKey: InjectionKey<FormItemContext>;
+/**
+ * useFormItem - 供组件内部使用的 Hook
+ * @description 获取表单项上下文。已优化内部触发校验逻辑，防止 Promise 拒绝导致控制台报错。
+ */
+declare const useFormItem: () => {
+    form: FormContext | undefined;
+    formItem: FormItemContext | undefined;
+    validate: (trigger: string) => Promise<boolean | unknown>;
+};
+type UseFormItemReturn = ReturnType<typeof useFormItem>;
+
+/**
+ * useVirtualScroll - 虚拟滚动 Hook
+ * @description 用于大数据量列表的虚拟滚动渲染
+ */
+
+interface VirtualScrollOptions<T = unknown> {
+    /** 每项高度 */
+    itemHeight: number;
+    /** 容器高度 */
+    containerHeight: number;
+    /** 数据列表 */
+    items: Ref<T[]> | T[];
+    /** 上下额外渲染数量 */
+    overscan?: number;
+}
+interface VirtualScrollReturn<T = unknown> {
+    /** 可见项列表 */
+    visibleItems: ComputedRef<T[]>;
+    /** 总高度 */
+    totalHeight: ComputedRef<number>;
+    /** Y轴偏移量 */
+    offsetY: ComputedRef<number>;
+    /** 起始索引 */
+    startIndex: Ref<number>;
+    /** 结束索引 */
+    endIndex: Ref<number>;
+    /** 滚动事件处理 */
+    onScroll: (event: Event) => void;
+    /** 滚动到指定索引 */
+    scrollToIndex: (index: number) => void;
+    /** 容器引用 */
+    containerRef: Ref<HTMLElement | null>;
+}
+declare function useVirtualScroll<T = unknown>(options: VirtualScrollOptions<T>): VirtualScrollReturn<T>;
+
+interface UseCacheReturn<T> {
+    data: ShallowRef<T | null>;
+    execute: () => Promise<void>;
+}
+/**
+ * 一个简单的 SSR 友好的缓存 Hook
+ * 在服务端可以将结果存入缓存，客户端可以从缓存中恢复或重新计算
+ */
+declare function useCache<T>(key: string, fetcher: () => T | Promise<T>): UseCacheReturn<T>;
+
+declare function useEventListener(target: MaybeRef<EventTarget | null | undefined> | (() => EventTarget | null | undefined), event: string, handler: (e: Event) => void, options?: boolean | AddEventListenerOptions): void;
+
+/**
+ * useScrollLock - 极致稳定的滚动锁定管理
+ * @description 深度对标 市面组件库 / Naive UI，解决复杂环境（包括 VitePress 等文档站点）下的内容移位问题
+ */
+declare const useScrollLock: (trigger: Ref<boolean>) => {
+    isLocked: Ref<boolean, boolean>;
+};
+
+declare function useClickOutside(target: MaybeRef<HTMLElement | null | undefined>, handler: (evt: MouseEvent | TouchEvent) => void): void;
+
+interface ConfigProviderContext {
+    size?: 'small' | 'default' | 'large';
+    zIndex?: number;
+    locale?: Language;
+    message?: {
+        max?: number;
+        duration?: number;
+        offset?: number;
+    };
+}
+declare const configProviderContextKey: InjectionKey<ComputedRef<ConfigProviderContext>>;
+/**
+ * 获取全局配置 Hook
+ */
+declare const useConfig: () => {
+    config: ComputedRef<ConfigProviderContext> | null;
+    globalSize: ComputedRef<"small" | "default" | "large">;
+    globalZIndex: ComputedRef<number>;
+    globalLocale: ComputedRef<Language | undefined>;
+};
+
+export { FormContextKey, FormItemContextKey, configProviderContextKey, createZIndexCounter, defaultNamespace, getDayjsLocale, getNextZIndex, idInjectionKey, namespaceContextKey, resetZIndex, setDayjsLocale, setDayjsLocaleSync, updateDayjsMonths, useCache, useClickOutside, useConfig, useEventListener, useFormItem, useGlobalNamespace, useId, useIdInjection, useLocale, useNamespace, useScrollLock, useVirtualScroll, useZIndex, zIndexContextKey, zIndexCounterKey };
+export type { ConfigProviderContext, FormContext, FormItemContext, UseCacheReturn, UseFormItemReturn, UseIdReturn, UseLocaleReturn, UseNamespaceReturn, UseZIndexReturn, VirtualScrollOptions, VirtualScrollReturn };

package/dist/index.d.mts

@@ -0,0 +1,259 @@
+import * as vue from 'vue';
+import { Ref, InjectionKey, ComputedRef, ShallowRef, MaybeRef } from 'vue';
+import { Language } from '@yh-ui/locale';
+export { Language } from '@yh-ui/locale';
+
+declare const defaultNamespace = "yh";
+declare const namespaceContextKey: InjectionKey<Ref<string>>;
+/**
+ * 获取全局命名空间
+ */
+declare const useGlobalNamespace: () => Ref<string, string>;
+/**
+ * useNamespace - 生成 BEM 类名
+ * @param block - 块名称
+ * @returns BEM 类名生成器
+ *
+ * @example
+ * const ns = useNamespace('button')
+ * ns.b() // 'yh-button'
+ * ns.e('icon') // 'yh-button__icon'
+ * ns.m('primary') // 'yh-button--primary'
+ * ns.is('disabled') // 'is-disabled'
+ * ns.bem('box', 'item', 'active') // 'yh-button-box__item--active'
+ */
+declare const useNamespace: (block: string) => {
+    namespace: Ref<string, string>;
+    b: (blockSuffix?: string) => string;
+    e: (element?: string) => string;
+    m: (modifier?: string) => string;
+    bem: (blockSuffix?: string, element?: string, modifier?: string) => string;
+    em: (element?: string, modifier?: string) => string;
+    is: (state: string, value?: boolean) => string;
+    cssVar: (name: string) => string;
+    cssVarObj: (vars: Record<string, string>) => Record<string, string>;
+    cssVarBlock: (name: string) => string;
+    cssVarBlockObj: (vars: Record<string, string>) => Record<string, string>;
+};
+type UseNamespaceReturn = ReturnType<typeof useNamespace>;
+
+declare const zIndexContextKey: InjectionKey<Ref<number | undefined>>;
+declare const zIndexCounterKey: InjectionKey<{
+    current: number;
+}>;
+declare const getNextZIndex: () => number;
+/**
+ * 重置 z-index 计数器
+ */
+declare const resetZIndex: (value?: number) => void;
+/**
+ * 创建 z-index 计数器（用于 provide）
+ */
+declare const createZIndexCounter: (initialValue?: number) => {
+    current: number;
+};
+/**
+ * useZIndex - z-index 管理
+ * @param zIndexOverrides - 可选的自定义 z-index
+ * @returns z-index 相关方法
+ *
+ * @example
+ * const { currentZIndex, nextZIndex } = useZIndex()
+ */
+declare const useZIndex: (zIndexOverrides?: Ref<number>) => {
+    initialZIndex: vue.ComputedRef<number>;
+    currentZIndex: vue.ComputedRef<number>;
+    nextZIndex: () => number;
+};
+type UseZIndexReturn = ReturnType<typeof useZIndex>;
+
+/**
+ * 获取 dayjs locale code
+ */
+declare const getDayjsLocale: (localeCode: string) => string;
+/**
+ * 动态加载并设置 dayjs locale
+ * 使用动态导入来按需加载，避免打包所有语言
+ */
+declare const setDayjsLocale: (localeCode: string) => Promise<void>;
+/**
+ * 同步设置 dayjs locale（不推荐，会阻塞）
+ * 用于需要立即同步的场景
+ */
+declare const setDayjsLocaleSync: (localeCode: string) => void;
+/**
+ * 使用自定义月份名称更新 dayjs locale
+ * 这样可以确保 dayjs 使用我们语言包中定义的月份名称
+ */
+declare const updateDayjsMonths: (localeCode: string, months: {
+    jan: string;
+    feb: string;
+    mar: string;
+    apr: string;
+    may: string;
+    jun: string;
+    jul: string;
+    aug: string;
+    sep: string;
+    oct: string;
+    nov: string;
+    dec: string;
+}) => void;
+
+/**
+ * useLocale - 国际化
+ * @param localeOverrides - 可选的自定义语言包
+ * @returns 国际化相关方法
+ */
+declare const useLocale: (localeOverrides?: Ref<Language>) => {
+    locale: vue.ComputedRef<Language>;
+    lang: vue.ComputedRef<string>;
+    t: (path: string, options?: Record<string, string | number>) => string;
+    tRaw: <T = unknown>(path: string) => T;
+};
+type UseLocaleReturn = ReturnType<typeof useLocale>;
+
+declare const idInjectionKey: InjectionKey<Ref<string | undefined>>;
+/**
+ * useId - 生成唯一 ID
+ * @param idOverrides - 可选的自定义 ID 前缀
+ * @returns 唯一 ID
+ *
+ * @example
+ * const id = useId() // 'yh-id-1' (or vue native id)
+ * const customId = useId(ref('custom')) // 'custom'
+ */
+declare const useId: (idOverrides?: Ref<string | undefined>) => Ref<string>;
+/**
+ * useIdInjection - ID 注入工具
+ * @description 用于组件内部生成关联 ID
+ */
+declare const useIdInjection: () => {
+    prefix: vue.ComputedRef<string>;
+    current: number;
+};
+type UseIdReturn = ReturnType<typeof useId>;
+
+interface FormContext {
+    model: Record<string, unknown>;
+    rules?: Record<string, unknown>;
+    labelWidth?: string | number;
+    labelPosition?: string;
+    labelSuffix?: string;
+    showMessage?: boolean;
+    scrollToError?: boolean;
+    scrollIntoViewOptions?: boolean | ScrollIntoViewOptions;
+    disabled?: boolean;
+    size?: string;
+    statusIcon?: boolean;
+    layout?: string;
+    addField: (field: FormItemContext) => void;
+    removeField: (field: FormItemContext) => void;
+    themeOverrides?: Record<string, unknown>;
+}
+interface FormItemContext {
+    prop: string;
+    validate: (trigger: string, callback?: (isValid: boolean) => void) => Promise<boolean | unknown>;
+    resetField: () => void;
+    clearValidate: () => void;
+    validateStatus: string;
+    validateMessage: string;
+    label: string;
+    errorId?: string;
+    inputId?: string;
+    size?: string;
+    disabled?: boolean;
+}
+declare const FormContextKey: InjectionKey<FormContext>;
+declare const FormItemContextKey: InjectionKey<FormItemContext>;
+/**
+ * useFormItem - 供组件内部使用的 Hook
+ * @description 获取表单项上下文。已优化内部触发校验逻辑，防止 Promise 拒绝导致控制台报错。
+ */
+declare const useFormItem: () => {
+    form: FormContext | undefined;
+    formItem: FormItemContext | undefined;
+    validate: (trigger: string) => Promise<boolean | unknown>;
+};
+type UseFormItemReturn = ReturnType<typeof useFormItem>;
+
+/**
+ * useVirtualScroll - 虚拟滚动 Hook
+ * @description 用于大数据量列表的虚拟滚动渲染
+ */
+
+interface VirtualScrollOptions<T = unknown> {
+    /** 每项高度 */
+    itemHeight: number;
+    /** 容器高度 */
+    containerHeight: number;
+    /** 数据列表 */
+    items: Ref<T[]> | T[];
+    /** 上下额外渲染数量 */
+    overscan?: number;
+}
+interface VirtualScrollReturn<T = unknown> {
+    /** 可见项列表 */
+    visibleItems: ComputedRef<T[]>;
+    /** 总高度 */
+    totalHeight: ComputedRef<number>;
+    /** Y轴偏移量 */
+    offsetY: ComputedRef<number>;
+    /** 起始索引 */
+    startIndex: Ref<number>;
+    /** 结束索引 */
+    endIndex: Ref<number>;
+    /** 滚动事件处理 */
+    onScroll: (event: Event) => void;
+    /** 滚动到指定索引 */
+    scrollToIndex: (index: number) => void;
+    /** 容器引用 */
+    containerRef: Ref<HTMLElement | null>;
+}
+declare function useVirtualScroll<T = unknown>(options: VirtualScrollOptions<T>): VirtualScrollReturn<T>;
+
+interface UseCacheReturn<T> {
+    data: ShallowRef<T | null>;
+    execute: () => Promise<void>;
+}
+/**
+ * 一个简单的 SSR 友好的缓存 Hook
+ * 在服务端可以将结果存入缓存，客户端可以从缓存中恢复或重新计算
+ */
+declare function useCache<T>(key: string, fetcher: () => T | Promise<T>): UseCacheReturn<T>;
+
+declare function useEventListener(target: MaybeRef<EventTarget | null | undefined> | (() => EventTarget | null | undefined), event: string, handler: (e: Event) => void, options?: boolean | AddEventListenerOptions): void;
+
+/**
+ * useScrollLock - 极致稳定的滚动锁定管理
+ * @description 深度对标 市面组件库 / Naive UI，解决复杂环境（包括 VitePress 等文档站点）下的内容移位问题
+ */
+declare const useScrollLock: (trigger: Ref<boolean>) => {
+    isLocked: Ref<boolean, boolean>;
+};
+
+declare function useClickOutside(target: MaybeRef<HTMLElement | null | undefined>, handler: (evt: MouseEvent | TouchEvent) => void): void;
+
+interface ConfigProviderContext {
+    size?: 'small' | 'default' | 'large';
+    zIndex?: number;
+    locale?: Language;
+    message?: {
+        max?: number;
+        duration?: number;
+        offset?: number;
+    };
+}
+declare const configProviderContextKey: InjectionKey<ComputedRef<ConfigProviderContext>>;
+/**
+ * 获取全局配置 Hook
+ */
+declare const useConfig: () => {
+    config: ComputedRef<ConfigProviderContext> | null;
+    globalSize: ComputedRef<"small" | "default" | "large">;
+    globalZIndex: ComputedRef<number>;
+    globalLocale: ComputedRef<Language | undefined>;
+};
+
+export { FormContextKey, FormItemContextKey, configProviderContextKey, createZIndexCounter, defaultNamespace, getDayjsLocale, getNextZIndex, idInjectionKey, namespaceContextKey, resetZIndex, setDayjsLocale, setDayjsLocaleSync, updateDayjsMonths, useCache, useClickOutside, useConfig, useEventListener, useFormItem, useGlobalNamespace, useId, useIdInjection, useLocale, useNamespace, useScrollLock, useVirtualScroll, useZIndex, zIndexContextKey, zIndexCounterKey };
+export type { ConfigProviderContext, FormContext, FormItemContext, UseCacheReturn, UseFormItemReturn, UseIdReturn, UseLocaleReturn, UseNamespaceReturn, UseZIndexReturn, VirtualScrollOptions, VirtualScrollReturn };