@hairy/react-lib-composition 1.29.0

package/dist/index.d.ts

@@ -0,0 +1,348 @@
+import { ComputedGetter, DebuggerOptions, ComputedRef, WritableComputedOptions, WritableComputedRef, effectScope as effectScope$1, EffectScope, Reactive, ShallowReactive, DeepReadonly, UnwrapNestedRefs, Ref as Ref$1, UnwrapRef, CustomRefFactory, ShallowRef, WatchSource, WatchCallback, WatchHandle, ReactiveMarker, WatchEffect } from '@vue/reactivity';
+export { isProxy, isReactive, isReadonly, isRef, isShallow, markRaw, toRaw, toReactive, toReadonly, toRef, toRefs, toValue, unref } from '@vue/reactivity';
+import { ArgumentsType, IfAny } from '@hairy/utils';
+import { FunctionComponent, Ref as Ref$2 } from 'react';
+export { Fragment, createElement as h } from 'react';
+
+/**
+ * @module veact.computed
+ * @author Surmon <https://github.com/surmon-china>
+ */
+
+/**
+ * Takes a getter function and returns a readonly reactive ref object for the
+ * returned value from the getter. It can also take an object with get and set
+ * functions to create a writable ref object.
+ *
+ * @param getter - Function that produces the next value.
+ * @param debugOptions - For debugging. See {@link https://vuejs.org/guide/extras/reactivity-in-depth.html#computed-debugging Vue Computed Debugging}.
+ * @see {@link https://vuejs.org/api/reactivity-core.html#computed Vue `computed()`}
+ *
+ * @example
+ * ```js
+ * // Creating a readonly computed ref:
+ * const count = useRef(1)
+ * const plusOne = computed(() => count.value + 1)
+ *
+ * console.log(plusOne.value) // 2
+ * plusOne.value++ // error
+ * ```
+ *
+ * @example
+ * ```js
+ * // Creating a writable computed ref:
+ * const count = useRef(1)
+ * const plusOne = computed({
+ *   get: () => count.value + 1,
+ *   set: (val) => {
+ *     count.value = val - 1
+ *   }
+ * })
+ *
+ * plusOne.value = 1
+ * console.log(count.value) // 0
+ * ```
+ */
+declare function computed<T>(getter: ComputedGetter<T>, debugOptions?: DebuggerOptions): ComputedRef<T>;
+declare function computed<T, S = T>(options: WritableComputedOptions<T, S>, debugOptions?: DebuggerOptions): WritableComputedRef<T, S>;
+
+/**
+ * Creates an effect scope object which can capture the reactive effects (i.e.
+ * computed and watchers) created within it so that these effects can be
+ * disposed together. For detailed use cases of this API, please consult its
+ * corresponding {@link https://github.com/vuejs/rfcs/blob/master/active-rfcs/0041-reactivity-effect-scope.md | RFC}.
+ *
+ * @param detached - Can be used to create a "detached" effect scope.
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#effectscope Vue `effectScope()`}
+ */
+declare function effectScope(...args: ArgumentsType<typeof effectScope$1>): EffectScope;
+declare function withEffectScope<T extends FunctionComponent>(fn: T, detached?: boolean): T;
+/**
+ * Returns the current active effect scope if there is one.
+ *
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#getcurrentscope}
+ */
+declare function getCurrentScope(): EffectScope | undefined;
+/**
+ * Registers a dispose callback on the current active effect scope. The
+ * callback will be invoked when the associated effect scope is stopped.
+ *
+ * @param fn - The callback function to attach to the scope's cleanup.
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#onscopedispose}
+ */
+declare function onScopeDispose(fn: () => void, _failSilently?: boolean): void;
+
+/**
+ * The function is called right after the component is mounted.
+ *
+ * @param fn
+ * @see {@link https://react.dev/reference/react/Component#componentdidmount React `componentDidMount()`}
+ */
+declare function onMounted(fn: () => any): void;
+declare function onBeforeMount(fn: () => any): void;
+/**
+ * The function is called right before the component is unmounted.
+ *
+ * @param fn
+ * @see {@link https://react.dev/reference/react/Component#componentwillunmount React `componentWillUnmount()`}
+ */
+declare function onBeforeUnmount(fn: () => void): void;
+declare function onUnmounted(fn: () => void): void;
+/**
+ * The function is called immediately after the component is re-rendered with updated props or state.
+ * This method is not invoked during the initial render.
+ *
+ * @param fn
+ * @see {@link https://react.dev/reference/react/Component#componentdidupdate React `componentDidUpdate()`}
+ */
+declare function onUpdated(fn: () => void): void;
+declare function onBeforeUpdate(fn: () => void): void;
+
+/**
+ * Returns a reactive proxy of the object.
+ *
+ * The reactive conversion is "deep": it affects all nested properties. A
+ * reactive object also deeply unwraps any properties that are refs while
+ * maintaining reactivity.
+ *
+ * @param target - The source object.
+ * @see {@link https://vuejs.org/api/reactivity-core.html#reactive Vue `reactive()`}
+ *
+ * @example
+ * ```js
+ * const obj = reactive({ count: 0 })
+ * ```
+ */
+declare function reactive<T extends object>(target: T): Reactive<T>;
+/**
+ * Shallow version of {@link reactive()}.
+ *
+ * Unlike {@link reactive()}, there is no deep conversion: only root-level
+ * properties are reactive for a shallow reactive object. Property values are
+ * stored and exposed as-is - this also means properties with ref values will
+ * not be automatically unwrapped.
+ *
+ * @param target - The source object.
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#shallowreactive Vue `shallowReactive()`}
+ *
+ * @example
+ * ```js
+ * const state = shallowReactive({
+ *   foo: 1,
+ *   nested: {
+ *     bar: 2
+ *   }
+ * })
+ *
+ * // mutating state's own properties is reactive
+ * state.foo++
+ *
+ * // ...but does not convert nested objects
+ * isReactive(state.nested) // false
+ *
+ * // NOT reactive
+ * state.nested.bar++
+ * ```
+ */
+declare function shallowReactive<T extends object>(target: T): ShallowReactive<T>;
+
+/**
+ * Converts some of the 'raw Vue' data, which is not already wrapped in a hook,
+ * into reactive hook data to ensure proper reactivity within the component.
+ *
+ * @param getter - A function that returns the data to be deeply watched.
+ * @example
+ * ```tsx
+ * import React from 'react'
+ * import { ref, reactivity } from 'veact'
+ *
+ * const countRef = ref(0)
+ *
+ * export const Component: React.FC = () => {
+ *   // Convert to a reactivity hook
+ *   const count = reactivity(() => countRef)
+ *   const increment = () => {
+ *     count.value++
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <span>{count.value}</span>
+ *       <button onClick={increment}>Increment</button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function reactivity<T = any>(getter: () => T): T;
+
+/**
+ * @module veact.readonly
+ * @author Surmon <https://github.com/surmon-china>
+ */
+
+/**
+ * Takes an object (reactive or plain) or a ref and returns a readonly proxy to
+ * the original.
+ *
+ * A readonly proxy is deep: any nested property accessed will be readonly as
+ * well. It also has the same ref-unwrapping behavior as {@link reactive()},
+ * except the unwrapped values will also be made readonly.
+ *
+ * @param target - The source object.
+ * @see {@link https://vuejs.org/api/reactivity-core.html#readonly Vue `readonly()`}
+ *
+ * @example
+ * ```js
+ * const original = reactive({ count: 0 })
+ * const copy = readonly(original)
+ *
+ * useWatchEffect(() => {
+ *   // works for reactivity tracking
+ *   console.log(copy.count)
+ * })
+ *
+ * // mutating original will trigger watchers relying on the copy
+ * original.count++
+ *
+ * // mutating the copy will fail and result in a warning
+ * copy.count++ // warning!
+ * ```
+ */
+declare function readonly<T extends object>(target: T): DeepReadonly<UnwrapNestedRefs<T>>;
+/**
+ * Shallow version of {@link readonly()}.
+ *
+ * Unlike {@link readonly()}, there is no deep conversion: only root-level
+ * properties are made readonly. Property values are stored and exposed as-is -
+ * this also means properties with ref values will not be automatically
+ * unwrapped.
+ *
+ * @param target - The source object.
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#shallowreadonly Vue `shallowReadonly()`}
+ *
+ * @example
+ * ```js
+ * const state = shallowReadonly({
+ *   foo: 1,
+ *   nested: {
+ *     bar: 2
+ *   }
+ * })
+ *
+ * // mutating state's own properties will fail
+ * state.foo++
+ *
+ * // ...but works on nested objects
+ * isReadonly(state.nested) // false
+ *
+ * // works
+ * state.nested.bar++
+ * ```
+ */
+declare function shallowReadonly<T extends object>(target: T): Readonly<T>;
+
+type Ref<T = any, S = T> = Ref$1<T, S> & Ref$2<NonNullable<T>>;
+/**
+ * Takes an inner value and returns a reactive and mutable ref object, which
+ * has a single property `.value` that points to the inner value.
+ *
+ * @param value - The object to wrap in the ref.
+ * @see {@link https://vuejs.org/api/reactivity-core.html#ref Vue `ref()`}
+ *
+ * @example
+ * ```js
+ * const count = ref(0)
+ * console.log(count.value) // 0
+ *
+ * count.value = 1
+ * console.log(count.value) // 1
+ * ```
+ */
+declare function ref<T>(value: T): [T] extends [Ref] ? IfAny<T, Ref<T>, T> : Ref<UnwrapRef<T>, UnwrapRef<T> | T>;
+declare function ref<T = any>(): Ref<T | undefined>;
+/**
+ * Creates a customized ref with explicit control over its dependency tracking
+ * and updates triggering.
+ *
+ * @param factory - The function that receives the `track` and `trigger` callbacks.
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#customref Vue `customRef()`}
+ */
+declare function customRef<T>(factory: CustomRefFactory<T>): Ref<T>;
+/**
+ *
+ * @param value - The "inner value" for the shallow ref.
+ * @see {@link https://vuejs.org/api/reactivity-advanced.html#shallowref Vue `shallowRef()`}
+ *
+ * @example
+ * ```js
+ * const state = shallowRef({ count: 1 })
+ * // does NOT trigger change
+ * state.value.count = 2
+ * // does trigger change
+ * state.value = { count: 2 }
+ * ```
+ */
+declare function shallowRef<T>(value: T): Ref extends T ? (T extends Ref ? IfAny<T, ShallowRef<T>, T> : ShallowRef<T>) : ShallowRef<T>;
+declare function shallowRef<T = any>(): ShallowRef<T | undefined>;
+
+interface WatchOptions<Immediate = boolean> extends DebuggerOptions {
+    immediate?: Immediate;
+    deep?: boolean | number;
+    once?: boolean;
+}
+type MultiWatchSources = (WatchSource<unknown> | object)[];
+type MaybeUndefined<T, I> = I extends true ? T | undefined : T;
+type MapSources<T, Immediate> = {
+    [K in keyof T]: T[K] extends WatchSource<infer V> ? MaybeUndefined<V, Immediate> : T[K] extends object ? MaybeUndefined<T[K], Immediate> : never;
+};
+/**
+ * Watches one or more reactive data sources and invokes a callback function when the sources change.
+ *
+ * @param source - The watcher's source.
+ * @param callback - This function will be called when the source is changed.
+ * @param options - An optional options object that does not support the `flush` option compared to Vue (3.5.0).
+ * @see {@link https://vuejs.org/api/reactivity-core.html#watch Vue `watch()`}
+ *
+ * @example
+ * ```js
+ * const count = ref(0)
+ * watch(count, (count, prevCount) => {
+ *  // ...
+ * })
+ * ```
+ */
+declare function watch<T, Immediate extends Readonly<boolean> = false>(source: WatchSource<T>, callback: WatchCallback<T, MaybeUndefined<T, Immediate>>, options?: WatchOptions<Immediate>): WatchHandle;
+declare function watch<T extends Readonly<MultiWatchSources>, Immediate extends Readonly<boolean> = false>(sources: readonly [...T] | T, callback: [T] extends [ReactiveMarker] ? WatchCallback<T, MaybeUndefined<T, Immediate>> : WatchCallback<MapSources<T, false>, MapSources<T, Immediate>>, options?: WatchOptions<Immediate>): WatchHandle;
+declare function watch<T extends MultiWatchSources, Immediate extends Readonly<boolean> = false>(sources: [...T], callback: WatchCallback<MapSources<T, false>, MapSources<T, Immediate>>, options?: WatchOptions<Immediate>): WatchHandle;
+declare function watch<T extends object, Immediate extends Readonly<boolean> = false>(source: T, callback: WatchCallback<T, MaybeUndefined<T, Immediate>>, options?: WatchOptions<Immediate>): WatchHandle;
+
+type WatchEffectOptions = DebuggerOptions;
+/**
+ * Runs a function immediately while reactively tracking its dependencies and re-runs it whenever the dependencies are changed.
+ *
+ * @param effect - The effect function to run.
+ * @param options - An optional options object that can be used to adjust the effect's flush timing or to debug the effect's dependencies; the `flush` option is not supported compared to Vue (3.5.0).
+ * @see {@link https://vuejs.org/api/reactivity-core.html#watcheffect Vue `watchEffect()`}
+ *
+ * @example
+ * ```js
+ * const count = useRef(0)
+ * watchEffect(() => console.log(count.value))
+ * // -> logs 0
+ *
+ * count.value++
+ * // -> logs 1
+ * ```
+ */
+declare function watchEffect(effect: WatchEffect, options?: WatchEffectOptions): WatchHandle;
+
+declare const getCurrentInstance: (...args: any) => any;
+declare const hasInjectionContext: (...args: any) => any;
+declare const inject: (...args: any) => any;
+declare const provide: (...args: any) => any;
+declare const nextTick: (...args: any) => any;
+declare const defineComponent: (...args: any) => any;
+declare const TransitionGroup: (...args: any) => any;
+
+export { type MultiWatchSources, type Ref, TransitionGroup, type WatchEffectOptions, type WatchOptions, computed, customRef, defineComponent, effectScope, getCurrentInstance, getCurrentScope, hasInjectionContext, inject, nextTick, onBeforeMount, onBeforeUnmount, onBeforeUpdate, onMounted, onScopeDispose, onUnmounted, onUpdated, provide, reactive, reactivity, readonly, ref, shallowReactive, shallowReadonly, shallowRef, watch, watchEffect, withEffectScope };