@maple-design/use 0.0.0-stage → 1.1.0

package/lib/index.d.cts

@@ -0,0 +1,161 @@
+import * as vue from 'vue';
+import { Ref, ComponentInternalInstance, ComputedRef, WatchSource, ShallowRef, InjectionKey } from 'vue';
+import { MotionState } from '@maple-design/shared';
+
+type UseEventListenerTarget = EventTarget | Ref<EventTarget | undefined | null> | (() => EventTarget | undefined | null);
+interface UseEventListenerOptions {
+    capture?: boolean;
+    passive?: boolean;
+}
+declare function useEventListener<T extends keyof DocumentEventMap>(target: UseEventListenerTarget, type: T, listener: (event: DocumentEventMap[T]) => void, options?: UseEventListenerOptions): () => void;
+declare function useEventListener(target: UseEventListenerTarget, type: string, listener: EventListener, options?: UseEventListenerOptions): () => void;
+
+type UseClickOutsideTarget = Element | Ref<Element | undefined | null> | (() => Element | undefined | null);
+declare function useClickOutside(target: UseClickOutsideTarget, type: string, listener: EventListener): void;
+
+declare function onSmartMounted(hook: () => void): void;
+
+declare function onSmartUnmounted(hook: () => void): void;
+
+interface UseChildrenBaseProvider<C> {
+    childInstances: ComponentInternalInstance[];
+    collect(instance: ComponentInternalInstance, childProvider: C): void;
+    clear(instance: ComponentInternalInstance, childProvider: C): void;
+}
+declare function useChildren<P, C>(key: symbol | string): {
+    length: ComputedRef<number>;
+    childProviders: C[];
+    bindChildren: (parentProvider: P) => void;
+};
+
+declare function keyInProvides(key: symbol | string): boolean;
+declare function useParent<P, C>(key: symbol | string): {
+    index: null;
+    parentProvider: null;
+    bindParent: null;
+} | {
+    index: ComputedRef<number>;
+    parentProvider: Omit<P & UseChildrenBaseProvider<C>, "clear" | "childInstances" | "collect">;
+    bindParent: (childProvider: C) => void;
+};
+
+declare function onWindowResize(listener: EventListener): void;
+
+declare function useInitialized<T>(source: WatchSource<T>, value: T): vue.Ref<boolean, boolean>;
+
+type TouchDirection = 'horizontal' | 'vertical';
+declare function useTouch(): {
+    startX: vue.Ref<number, number>;
+    startY: vue.Ref<number, number>;
+    deltaX: vue.Ref<number, number>;
+    deltaY: vue.Ref<number, number>;
+    offsetX: vue.Ref<number, number>;
+    offsetY: vue.Ref<number, number>;
+    prevX: vue.Ref<number, number>;
+    prevY: vue.Ref<number, number>;
+    moveX: vue.Ref<number, number>;
+    moveY: vue.Ref<number, number>;
+    direction: vue.Ref<TouchDirection | undefined, TouchDirection | undefined>;
+    touching: vue.Ref<boolean, boolean>;
+    dragging: vue.Ref<boolean, boolean>;
+    startTime: vue.Ref<number, number>;
+    distance: vue.Ref<number, number>;
+    resetTouch: () => void;
+    startTouch: (event: TouchEvent) => void;
+    moveTouch: (event: TouchEvent) => void;
+    endTouch: () => void;
+    isReachTop: (element: Element | Window) => boolean;
+    isReachBottom: (element: Element, offset?: number) => boolean;
+};
+
+/** Vue 3.5 supplies hydration-safe IDs. Earlier Vue versions defer IDs to mount. */
+declare function useId(): vue.Ref<string | undefined, string | undefined>;
+
+declare function useClientId(): vue.Ref<string | undefined, string | undefined>;
+
+interface UseWindowSizeOptions {
+    initialWidth?: number;
+    initialHeight?: number;
+}
+declare function useWindowSize(options?: UseWindowSizeOptions): {
+    width: vue.Ref<number, number>;
+    height: vue.Ref<number, number>;
+};
+
+type ModelEvent<T> = [T][T extends any ? 0 : never];
+interface UseVModelOptions<P, K extends keyof P, E extends string = `update:${K & (string | number)}`> {
+    passive?: boolean;
+    eventName?: E;
+    defaultValue?: P[K];
+    emit?: (event: ModelEvent<E>, value: P[K]) => void;
+}
+declare function useVModel<P extends Record<string, any>, K extends keyof P, E extends string = `update:${K & (string | number)}`>(props: P, key: K, options?: UseVModelOptions<P, K, E>): Ref<P[K]>;
+
+interface UseMotionOptions {
+    from: number | (() => number);
+    to: number | (() => number);
+    duration?: number | (() => number);
+    timingFunction?: (v: number) => number;
+    onFinished?: (value: number) => void;
+}
+declare function useMotion(options: UseMotionOptions): {
+    value: vue.Ref<number, number>;
+    state: vue.Ref<MotionState, MotionState>;
+    start: () => void;
+    pause: () => void;
+    reset: () => void;
+};
+
+interface AsyncDataContext {
+    signal: AbortSignal;
+}
+/** A zero-argument business function is also accepted; mapping stays in the loader. */
+type AsyncDataLoader<T> = (context: AsyncDataContext) => T | Promise<T>;
+type AsyncDataResult<T> = {
+    status: 'success';
+    data: T;
+} | {
+    status: 'cancelled';
+} | {
+    status: 'error';
+    error: unknown;
+};
+interface AsyncDataOptions<T> {
+    initialData: T;
+    /** Run once on client mount. Changing the loader does not rerun it. */
+    immediate?: boolean;
+    /** Milliseconds; applies to manual execute calls, not initial loading or refresh. */
+    debounce?: number;
+    /** Per-instance TTL in milliseconds. Disabled by default; at most 50 entries. */
+    cacheTime?: number;
+}
+interface AsyncDataExecuteOptions<T> {
+    loader?: AsyncDataLoader<T>;
+    /** Explicitly distinguish query, tenant, permissions, etc. Never inferred from a function. */
+    cacheKey?: string;
+    force?: boolean;
+}
+interface AsyncDataReturn<T> {
+    data: ShallowRef<T>;
+    loading: Readonly<Ref<boolean>>;
+    error: Readonly<ShallowRef<unknown>>;
+    execute: (request?: AsyncDataExecuteOptions<T>) => Promise<AsyncDataResult<T>>;
+    refresh: () => Promise<AsyncDataResult<T>>;
+    cancel: () => void;
+    clearCache: () => void;
+}
+/** Array/object agnostic async state. Each invocation owns its state and cache. */
+declare function useAsyncData<T>(loader: AsyncDataLoader<T>, options: AsyncDataOptions<T>): AsyncDataReturn<T>;
+
+type ReadingDirection = 'ltr' | 'rtl';
+declare const readingDirectionKey: InjectionKey<Readonly<Ref<ReadingDirection | undefined>>>;
+/** Provide reading direction without changing the direction of the document. */
+declare function provideDirection(direction: Readonly<Ref<ReadingDirection | undefined>>): void;
+declare function resolveDirection(element?: Element | null, fallback?: ReadingDirection): ReadingDirection;
+/** DOM scopes take precedence over injection, so native nested dir containers work too. */
+declare function useDirection(target?: () => Element | null | undefined, explicit?: () => unknown): {
+    dir: vue.ComputedRef<ReadingDirection>;
+    isRtl: vue.ComputedRef<boolean>;
+};
+
+export { AsyncDataContext, AsyncDataExecuteOptions, AsyncDataLoader, AsyncDataOptions, AsyncDataResult, AsyncDataReturn, ReadingDirection, TouchDirection, UseChildrenBaseProvider, UseClickOutsideTarget, UseEventListenerOptions, UseEventListenerTarget, UseMotionOptions, UseVModelOptions, UseWindowSizeOptions, keyInProvides, onSmartMounted, onSmartUnmounted, onWindowResize, provideDirection, readingDirectionKey, resolveDirection, useAsyncData, useChildren, useClickOutside, useClientId, useDirection, useEventListener, useId, useInitialized, useMotion, useParent, useTouch, useVModel, useWindowSize };

package/lib/index.d.ts

@@ -0,0 +1,161 @@
+import * as vue from 'vue';
+import { Ref, ComponentInternalInstance, ComputedRef, WatchSource, ShallowRef, InjectionKey } from 'vue';
+import { MotionState } from '@maple-design/shared';
+
+type UseEventListenerTarget = EventTarget | Ref<EventTarget | undefined | null> | (() => EventTarget | undefined | null);
+interface UseEventListenerOptions {
+    capture?: boolean;
+    passive?: boolean;
+}
+declare function useEventListener<T extends keyof DocumentEventMap>(target: UseEventListenerTarget, type: T, listener: (event: DocumentEventMap[T]) => void, options?: UseEventListenerOptions): () => void;
+declare function useEventListener(target: UseEventListenerTarget, type: string, listener: EventListener, options?: UseEventListenerOptions): () => void;
+
+type UseClickOutsideTarget = Element | Ref<Element | undefined | null> | (() => Element | undefined | null);
+declare function useClickOutside(target: UseClickOutsideTarget, type: string, listener: EventListener): void;
+
+declare function onSmartMounted(hook: () => void): void;
+
+declare function onSmartUnmounted(hook: () => void): void;
+
+interface UseChildrenBaseProvider<C> {
+    childInstances: ComponentInternalInstance[];
+    collect(instance: ComponentInternalInstance, childProvider: C): void;
+    clear(instance: ComponentInternalInstance, childProvider: C): void;
+}
+declare function useChildren<P, C>(key: symbol | string): {
+    length: ComputedRef<number>;
+    childProviders: C[];
+    bindChildren: (parentProvider: P) => void;
+};
+
+declare function keyInProvides(key: symbol | string): boolean;
+declare function useParent<P, C>(key: symbol | string): {
+    index: null;
+    parentProvider: null;
+    bindParent: null;
+} | {
+    index: ComputedRef<number>;
+    parentProvider: Omit<P & UseChildrenBaseProvider<C>, "clear" | "childInstances" | "collect">;
+    bindParent: (childProvider: C) => void;
+};
+
+declare function onWindowResize(listener: EventListener): void;
+
+declare function useInitialized<T>(source: WatchSource<T>, value: T): vue.Ref<boolean, boolean>;
+
+type TouchDirection = 'horizontal' | 'vertical';
+declare function useTouch(): {
+    startX: vue.Ref<number, number>;
+    startY: vue.Ref<number, number>;
+    deltaX: vue.Ref<number, number>;
+    deltaY: vue.Ref<number, number>;
+    offsetX: vue.Ref<number, number>;
+    offsetY: vue.Ref<number, number>;
+    prevX: vue.Ref<number, number>;
+    prevY: vue.Ref<number, number>;
+    moveX: vue.Ref<number, number>;
+    moveY: vue.Ref<number, number>;
+    direction: vue.Ref<TouchDirection | undefined, TouchDirection | undefined>;
+    touching: vue.Ref<boolean, boolean>;
+    dragging: vue.Ref<boolean, boolean>;
+    startTime: vue.Ref<number, number>;
+    distance: vue.Ref<number, number>;
+    resetTouch: () => void;
+    startTouch: (event: TouchEvent) => void;
+    moveTouch: (event: TouchEvent) => void;
+    endTouch: () => void;
+    isReachTop: (element: Element | Window) => boolean;
+    isReachBottom: (element: Element, offset?: number) => boolean;
+};
+
+/** Vue 3.5 supplies hydration-safe IDs. Earlier Vue versions defer IDs to mount. */
+declare function useId(): vue.Ref<string | undefined, string | undefined>;
+
+declare function useClientId(): vue.Ref<string | undefined, string | undefined>;
+
+interface UseWindowSizeOptions {
+    initialWidth?: number;
+    initialHeight?: number;
+}
+declare function useWindowSize(options?: UseWindowSizeOptions): {
+    width: vue.Ref<number, number>;
+    height: vue.Ref<number, number>;
+};
+
+type ModelEvent<T> = [T][T extends any ? 0 : never];
+interface UseVModelOptions<P, K extends keyof P, E extends string = `update:${K & (string | number)}`> {
+    passive?: boolean;
+    eventName?: E;
+    defaultValue?: P[K];
+    emit?: (event: ModelEvent<E>, value: P[K]) => void;
+}
+declare function useVModel<P extends Record<string, any>, K extends keyof P, E extends string = `update:${K & (string | number)}`>(props: P, key: K, options?: UseVModelOptions<P, K, E>): Ref<P[K]>;
+
+interface UseMotionOptions {
+    from: number | (() => number);
+    to: number | (() => number);
+    duration?: number | (() => number);
+    timingFunction?: (v: number) => number;
+    onFinished?: (value: number) => void;
+}
+declare function useMotion(options: UseMotionOptions): {
+    value: vue.Ref<number, number>;
+    state: vue.Ref<MotionState, MotionState>;
+    start: () => void;
+    pause: () => void;
+    reset: () => void;
+};
+
+interface AsyncDataContext {
+    signal: AbortSignal;
+}
+/** A zero-argument business function is also accepted; mapping stays in the loader. */
+type AsyncDataLoader<T> = (context: AsyncDataContext) => T | Promise<T>;
+type AsyncDataResult<T> = {
+    status: 'success';
+    data: T;
+} | {
+    status: 'cancelled';
+} | {
+    status: 'error';
+    error: unknown;
+};
+interface AsyncDataOptions<T> {
+    initialData: T;
+    /** Run once on client mount. Changing the loader does not rerun it. */
+    immediate?: boolean;
+    /** Milliseconds; applies to manual execute calls, not initial loading or refresh. */
+    debounce?: number;
+    /** Per-instance TTL in milliseconds. Disabled by default; at most 50 entries. */
+    cacheTime?: number;
+}
+interface AsyncDataExecuteOptions<T> {
+    loader?: AsyncDataLoader<T>;
+    /** Explicitly distinguish query, tenant, permissions, etc. Never inferred from a function. */
+    cacheKey?: string;
+    force?: boolean;
+}
+interface AsyncDataReturn<T> {
+    data: ShallowRef<T>;
+    loading: Readonly<Ref<boolean>>;
+    error: Readonly<ShallowRef<unknown>>;
+    execute: (request?: AsyncDataExecuteOptions<T>) => Promise<AsyncDataResult<T>>;
+    refresh: () => Promise<AsyncDataResult<T>>;
+    cancel: () => void;
+    clearCache: () => void;
+}
+/** Array/object agnostic async state. Each invocation owns its state and cache. */
+declare function useAsyncData<T>(loader: AsyncDataLoader<T>, options: AsyncDataOptions<T>): AsyncDataReturn<T>;
+
+type ReadingDirection = 'ltr' | 'rtl';
+declare const readingDirectionKey: InjectionKey<Readonly<Ref<ReadingDirection | undefined>>>;
+/** Provide reading direction without changing the direction of the document. */
+declare function provideDirection(direction: Readonly<Ref<ReadingDirection | undefined>>): void;
+declare function resolveDirection(element?: Element | null, fallback?: ReadingDirection): ReadingDirection;
+/** DOM scopes take precedence over injection, so native nested dir containers work too. */
+declare function useDirection(target?: () => Element | null | undefined, explicit?: () => unknown): {
+    dir: vue.ComputedRef<ReadingDirection>;
+    isRtl: vue.ComputedRef<boolean>;
+};
+
+export { AsyncDataContext, AsyncDataExecuteOptions, AsyncDataLoader, AsyncDataOptions, AsyncDataResult, AsyncDataReturn, ReadingDirection, TouchDirection, UseChildrenBaseProvider, UseClickOutsideTarget, UseEventListenerOptions, UseEventListenerTarget, UseMotionOptions, UseVModelOptions, UseWindowSizeOptions, keyInProvides, onSmartMounted, onSmartUnmounted, onWindowResize, provideDirection, readingDirectionKey, resolveDirection, useAsyncData, useChildren, useClickOutside, useClientId, useDirection, useEventListener, useId, useInitialized, useMotion, useParent, useTouch, useVModel, useWindowSize };