@legendapp/state 2.2.0-next.7 → 2.2.0-next.71

package/src/react/{reactInterfaces.d.ts → reactInterfaces.ts}

@@ -1,23 +1,31 @@
 import type { FC, LegacyRef, ReactNode } from 'react';
-import type { Observable, Selector } from '../observableInterfaces';
+import type { Observable } from '../observableTypes';
+import type { Selector } from '../observableInterfaces';
+
 export type ShapeWithNew$<T> = Partial<Omit<T, 'children'>> & {
     [K in keyof T as K extends `$${string & K}` ? K : `$${string & K}`]?: Selector<T[K]>;
-} & {
-    children?: Selector<ReactNode>;
-};
+} & { children?: Selector<ReactNode> };
+
 export interface BindKey<P> {
     handler?: keyof P;
     getValue?: (e: any) => any;
     defaultValue?: any;
     selector?: (propsOut: Record<string, any>, p: Observable<any>) => any;
 }
+
 export type BindKeys<P = any> = Record<keyof P, BindKey<P>>;
+
 export type FCReactiveObject<T> = {
     [K in keyof T]: FC<ShapeWithNew$<T[K]>>;
 };
-export type FCReactive<P, P2> = P & FC<ShapeWithNew$<P2> & {
-    ref?: LegacyRef<P> | undefined;
-}>;
+
+export type FCReactive<P, P2> = P &
+    FC<
+        ShapeWithNew$<P2> & {
+            ref?: LegacyRef<P> | undefined;
+        }
+    >;
+
 export interface UseSelectorOptions {
     suspense?: boolean;
     skipCheck?: boolean;

package/src/react/reactive-observer.tsx

@@ -0,0 +1,210 @@
+import { isFunction, isObservable, Selector } from '@legendapp/state';
+import { ChangeEvent, FC, forwardRef, memo, useCallback } from 'react';
+import { reactGlobals } from './react-globals';
+import type { BindKeys } from './reactInterfaces';
+import { useSelector } from './useSelector';
+
+export type ShapeWithPick$<T, T2 extends keyof T = keyof T> = Partial<T> & {
+    [K in T2 as K extends `$${string & K}` ? K : `$${string & K}`]?: Selector<T[K]>;
+};
+export type ShapeWith$<T> = Partial<T> & {
+    [K in keyof T as K extends `$${string & K}` ? K : `$${string & K}`]?: Selector<T[K]>;
+};
+export type ObjectShapeWith$<T> = {
+    [K in keyof T]: T[K] extends FC<infer P> ? FC<ShapeWith$<P>> : T[K];
+};
+export type ExtractFCPropsType<T> = T extends FC<infer P> ? P : never;
+
+// Extracting the forwardRef inspired by https://github.com/mobxjs/mobx/blob/main/packages/mobx-react-lite/src/observer.ts
+export const hasSymbol = /* @__PURE__ */ typeof Symbol === 'function' && Symbol.for;
+
+// TODOV2: Change bindKeys to an options object, where one of the options is "convertChildren" so that behavior can be optional
+function createReactiveComponent<P = object>(
+    component: FC<P>,
+    observe: boolean,
+    reactive?: boolean,
+    bindKeys?: BindKeys<P>,
+) {
+    const ReactForwardRefSymbol = hasSymbol
+        ? Symbol.for('react.forward_ref')
+        : // eslint-disable-next-line react/display-name, @typescript-eslint/no-unused-vars
+          typeof forwardRef === 'function' && forwardRef((props: any) => null)['$$typeof'];
+
+    const ReactMemoSymbol = hasSymbol
+        ? Symbol.for('react.memo')
+        : // eslint-disable-next-line react/display-name, @typescript-eslint/no-unused-vars
+          typeof forwardRef === 'function' && memo((props) => null)['$$typeof'];
+
+    // If this component is already reactive bail out early
+    // This can happen with Fast Refresh.
+    if ((component as any)['__legend_proxied']) return component;
+
+    let useForwardRef = false;
+    let useMemo = false;
+    let render = component;
+
+    // Unwrap memo on the component
+    if (ReactMemoSymbol && (render as any)['$$typeof'] === ReactMemoSymbol && (render as any)['type']) {
+        useMemo = true;
+        render = (render as any)['type'];
+    }
+    // Unwrap forwardRef on the component
+    if (ReactForwardRefSymbol && (render as any)['$$typeof'] === ReactForwardRefSymbol) {
+        useForwardRef = true;
+        render = (render as any)['render'];
+        if (process.env.NODE_ENV === 'development' && typeof render !== 'function') {
+            throw new Error(`[legend-state] \`render\` property of ForwardRef was not a function`);
+        }
+    }
+
+    const proxyHandler: ProxyHandler<any> = {
+        apply(target, thisArg, argArray) {
+            // If this is a reactive component, convert all props ending in $
+            // to regular props and set up a useSelector listener
+            if (reactive) {
+                const props = argArray[0];
+                const propsOut = {} as Record<string, any>;
+                const keys = Object.keys(props);
+                for (let i = 0; i < keys.length; i++) {
+                    const key = keys[i];
+                    const p = props[key];
+
+                    // Convert children if it's a function
+                    if (key === 'children' && (isFunction(p) || isObservable(p))) {
+                        props[key] = useSelector(p, { skipCheck: true });
+                    }
+                    // Convert reactive props
+                    else if (key.startsWith('$') || key.endsWith('$')) {
+                        // TODOV3 Add this warning and then remove the deprecated endsWith option
+                        // if (
+                        //     process.env.NODE_ENV === 'development' &&
+                        //     !internal.globalState.noDepWarn &&
+                        //     key.endsWith('$')
+                        // ) {
+                        //     console.warn(
+                        //         `[legend-state] Reactive props will be changed to start with $ instead of end with $ in version 2.0. So please change ${key} to $${key.replace(
+                        //             '$',
+                        //             '',
+                        //         )}. See https://legendapp.com/open-source/state/migrating for more details.`,
+                        //     );
+                        // }
+                        const k = key.endsWith('$') ? key.slice(0, -1) : key.slice(1);
+                        // Return raw value and listen to the selector for changes
+
+                        const bind = bindKeys?.[k as keyof P];
+                        const shouldBind = bind && isObservable(p);
+
+                        propsOut[k] = shouldBind && bind?.selector ? bind.selector(propsOut, p) : useSelector(p);
+
+                        // If this key is one of the bind keys set up a two-way binding
+                        if (shouldBind) {
+                            // Use the bind's defaultValue if value is undefined
+                            if (bind.defaultValue !== undefined && propsOut[k] === undefined) {
+                                propsOut[k] = bind.defaultValue;
+                            }
+
+                            if (bind.handler && bind.getValue) {
+                                // Hook up the change lander
+                                const handlerFn = (e: ChangeEvent) => {
+                                    p.set(bind.getValue!(e));
+                                    props[bind.handler!]?.(e);
+                                };
+
+                                (propsOut[bind.handler as string] as any) =
+                                    // If in development mode, don't memoize the handler. fix fast refresh bug
+                                    process.env.NODE_ENV === 'development'
+                                        ? handlerFn
+                                        : useCallback(handlerFn, [props[bind.handler], bindKeys]);
+                            }
+                        }
+
+                        // Delete the reactive key
+                        delete propsOut[key];
+                    } else if (propsOut[key] === undefined) {
+                        propsOut[key] = p;
+                    }
+                }
+                argArray[0] = propsOut;
+            }
+
+            // If observing wrap the whole render in a useSelector to listen to it
+            if (observe) {
+                return useSelector(
+                    () => {
+                        reactGlobals.inObserver = true;
+                        try {
+                            return Reflect.apply(target, thisArg, argArray);
+                        } finally {
+                            reactGlobals.inObserver = false;
+                        }
+                    },
+                    { skipCheck: true },
+                );
+            } else {
+                return Reflect.apply(target, thisArg, argArray);
+            }
+        },
+    };
+
+    const proxy = new Proxy(render, proxyHandler);
+
+    let ret;
+
+    if (useForwardRef) {
+        ret = forwardRef(proxy);
+        (ret as any)['__legend_proxied'] = true;
+    } else {
+        ret = proxy;
+    }
+
+    return observe || useMemo ? memo(ret) : ret;
+}
+
+export function observer<P extends FC<any>>(component: P): P {
+    return createReactiveComponent(component, true);
+}
+
+export function reactive<T extends FC<any>>(
+    component: T,
+    bindKeys?: BindKeys<ExtractFCPropsType<T>>,
+): T | FC<ShapeWith$<ExtractFCPropsType<T>>>;
+export function reactive<T extends FC<any>, T2 extends keyof ExtractFCPropsType<T>>(
+    component: T,
+    bindKeys?: BindKeys<ExtractFCPropsType<T>>,
+): T | FC<ShapeWithPick$<ExtractFCPropsType<T>, T2>>;
+export function reactive<T extends FC<any>>(
+    component: T,
+    bindKeys?: BindKeys<ExtractFCPropsType<T>>,
+): T | FC<ShapeWith$<ExtractFCPropsType<T>>> {
+    return createReactiveComponent(component, false, true, bindKeys);
+}
+
+export function reactiveObserver<T extends FC<any>>(
+    component: T,
+    bindKeys?: BindKeys<ExtractFCPropsType<T>>,
+): T | FC<ShapeWith$<ExtractFCPropsType<T>>>;
+export function reactiveObserver<T extends FC<any>, T2 extends keyof ExtractFCPropsType<T>>(
+    component: T,
+    bindKeys?: BindKeys<ExtractFCPropsType<T>>,
+): T | FC<ShapeWithPick$<ExtractFCPropsType<T>, T2>>;
+export function reactiveObserver<T extends FC<any>>(
+    component: T,
+    bindKeys?: BindKeys<ExtractFCPropsType<T>>,
+): T | FC<ShapeWith$<ExtractFCPropsType<T>>> {
+    return createReactiveComponent(component, true, true, bindKeys);
+}
+
+export function reactiveComponents<P extends Record<string, FC>>(components: P): ObjectShapeWith$<P> {
+    return new Proxy(
+        {},
+        {
+            get(target: Record<string, any>, p: string) {
+                if (!target[p] && components[p]) {
+                    target[p] = createReactiveComponent(components[p], false, true) as FC<ShapeWith$<P>>;
+                }
+
+                return target[p];
+            },
+        },
+    ) as ObjectShapeWith$<P>;
+}

package/src/react/useComputed.ts

@@ -0,0 +1,36 @@
+import { computed, isArray, isFunction, Observable, ObservableParam } from '@legendapp/state';
+import { useMemo, useRef } from 'react';
+
+export function useComputed<T>(compute: () => T | Promise<T>): Observable<T>;
+export function useComputed<T>(compute: () => T | Promise<T>, deps: any[]): Observable<T>;
+export function useComputed<T, T2 = T>(
+    compute: (() => T | Promise<T>) | ObservableParam<T>,
+    set: (value: T2) => void,
+): Observable<T>;
+export function useComputed<T, T2 = T>(
+    compute: (() => T | Promise<T>) | ObservableParam<T>,
+    set: (value: T2) => void,
+    deps: any[],
+): Observable<T>;
+export function useComputed<T, T2 = T>(
+    compute: (() => T | Promise<T>) | ObservableParam<T>,
+    set?: ((value: T2) => void) | any[],
+    deps?: any[],
+): Observable<T> {
+    if (!deps && isArray(set)) {
+        deps = set;
+        set = undefined;
+    }
+    const ref = useRef<{ compute?: (() => T | Promise<T>) | ObservableParam<T>; set?: (value: T2) => void }>({});
+    ref.current.compute = compute;
+    ref.current.set = set as (value: T2) => void;
+
+    return useMemo(
+        () =>
+            computed<T, T2>(
+                () => (isFunction(ref.current.compute) ? ref.current.compute() : ref.current.compute) as any,
+                (set ? (value) => ref.current.set!(value) : undefined) as (value: T2) => void,
+            ),
+        deps || [],
+    );
+}

package/src/react/useEffectOnce.ts

@@ -0,0 +1,41 @@
+import { isFunction } from '@legendapp/state';
+import { useEffect, useRef } from 'react';
+
+export const useEffectOnce = (effect: () => void | (() => void), deps: any[]) => {
+    if (process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test') {
+        const refDispose = useRef<{ dispose?: void | (() => void); num: number }>({ num: 0 });
+
+        useEffect(() => {
+            // This is a hack to work around StrictMode running effects twice.
+            // On the first run it returns a cleanup function that queues the dispose function
+            // in a microtask. This way it will run at the end of the frame after StrictMode's second
+            // run of the effect. If it's run a second time then the microtasked dispose will do nothing,
+            // but the effect will return the dispose again so that when it actually unmounts it will dispose.
+            // If not in StrictMode, then the dispose function will run in the microtask.
+            // It's possible that this is not safe in 100% of cases, but I'm not sure what the
+            // dangerous cases would be. The side effect is that the listener is still active
+            // until the end of the frame, but that's probably not a problem.
+            const { current } = refDispose;
+            current.num++;
+            const dispose = () => {
+                if (current.dispose && current.num < 2) {
+                    (current.dispose as () => void)();
+                    current.dispose = undefined;
+                }
+                current.num--;
+            };
+            if (current.dispose === undefined) {
+                const ret = effect() ?? null;
+                // If ret is a function, then it's a dispose function.
+                if (ret && isFunction(ret)) {
+                    current.dispose = ret;
+                    return () => queueMicrotask(dispose);
+                }
+            } else {
+                return dispose;
+            }
+        }, deps);
+    } else {
+        useEffect(effect, deps);
+    }
+};

package/src/react/useIsMounted.ts

@@ -0,0 +1,16 @@
+import type { Observable } from '@legendapp/state';
+import { useMountOnce } from './useMount';
+import { useObservable } from './useObservable';
+
+export function useIsMounted(): Observable<boolean> {
+    const obs = useObservable(false);
+
+    const { set } = obs;
+    useMountOnce(() => {
+        set(true);
+
+        return () => set(false);
+    });
+
+    return obs;
+}

package/src/react/useMount.ts

@@ -0,0 +1,15 @@
+import { isPromise } from '@legendapp/state';
+import { useEffectOnce } from './useEffectOnce';
+
+export function useMount(fn: () => (void | (() => void)) | Promise<void>) {
+    return useEffectOnce(() => {
+        const ret = fn();
+        // Allow the function to be async but if so ignore its return value
+        if (!isPromise(ret)) {
+            return ret;
+        }
+    }, []);
+}
+
+// TODOV4 Deprecate
+export const useMountOnce = useMount;

package/src/react/useObservable.ts

@@ -0,0 +1,24 @@
+import { observable, Observable, RecursiveValueOrFunction } from '@legendapp/state';
+import { useRef } from 'react';
+
+/**
+ * A React hook that creates a new observable
+ *
+ * @param initialValue The initial value of the observable or a function that returns the initial value
+ *
+ * @see https://www.legendapp.com/dev/state/react/#useObservable
+ */
+export function useObservable<T>(): Observable<T | undefined>;
+export function useObservable<T>(
+    value: Promise<RecursiveValueOrFunction<T>> | (() => RecursiveValueOrFunction<T>) | RecursiveValueOrFunction<T>,
+): Observable<T>;
+export function useObservable<T>(value: T): Observable<T>;
+export function useObservable<T>(value?: T): Observable<any>;
+export function useObservable<T>(initialValue?: T | (() => T) | (() => Promise<T>)): Observable<T> {
+    const ref = useRef<Observable<T>>();
+    if (!ref.current) {
+        // Create the observable from the default value
+        ref.current = observable<T>(initialValue as any);
+    }
+    return ref.current;
+}

package/src/react/useObservableReducer.ts

@@ -0,0 +1,52 @@
+import type { Observable } from '@legendapp/state';
+import { isFunction } from '@legendapp/state';
+import type {
+    Dispatch,
+    DispatchWithoutAction,
+    Reducer,
+    ReducerAction,
+    ReducerState,
+    ReducerStateWithoutAction,
+    ReducerWithoutAction,
+} from 'react';
+import { useObservable } from './useObservable';
+
+export function useObservableReducer<R extends ReducerWithoutAction<any>, I>(
+    reducer: R,
+    initializerArg: I,
+    initializer: (arg: I) => ReducerStateWithoutAction<R>,
+): [Observable<ReducerStateWithoutAction<R>>, DispatchWithoutAction];
+export function useObservableReducer<R extends ReducerWithoutAction<any>>(
+    reducer: R,
+    initializerArg: ReducerStateWithoutAction<R>,
+    initializer?: undefined,
+): [Observable<ReducerStateWithoutAction<R>>, DispatchWithoutAction];
+export function useObservableReducer<R extends Reducer<any, any>, I>(
+    reducer: R,
+    initializerArg: I & ReducerState<R>,
+    initializer: (arg: I & ReducerState<R>) => ReducerState<R>,
+): [Observable<ReducerState<R>>, Dispatch<ReducerAction<R>>];
+export function useObservableReducer<R extends Reducer<any, any>, I>(
+    reducer: R,
+    initializerArg: I,
+    initializer: (arg: I) => ReducerState<R>,
+): [Observable<ReducerState<R>>, Dispatch<ReducerAction<R>>];
+export function useObservableReducer<R extends Reducer<any, any>>(
+    reducer: R,
+    initialState: ReducerState<R>,
+    initializer?: undefined,
+): [Observable<ReducerState<R>>, Dispatch<ReducerAction<R>>];
+export function useObservableReducer<R extends Reducer<any, any>, I>(
+    reducer: R,
+    initializerArg: I & ReducerState<R>,
+    initializer: ((arg: I & ReducerState<R>) => ReducerState<R>) | undefined,
+): [Observable<ReducerState<R>>, Dispatch<ReducerAction<R>>] {
+    const obs = useObservable(() =>
+        initializerArg !== undefined && isFunction(initializerArg) ? initializer!(initializerArg) : initializerArg,
+    );
+    const dispatch = (action: any) => {
+        obs.set(reducer(obs.get(), action));
+    };
+
+    return [obs as Observable<ReducerState<R>>, dispatch];
+}

package/src/react/useObservableState.ts

@@ -0,0 +1,30 @@
+import { isFunction, observable, type Observable } from '@legendapp/state';
+import { useMemo } from 'react';
+import { useSelector } from './useSelector';
+
+export function useObservableState<T>(initialValue?: T | (() => T) | (() => Promise<T>)): [Observable<T>, T] {
+    // Create a memoized observable
+    return useMemo(
+        () =>
+            // Wrap the return array in a Proxy to detect whether the value is accessed
+            new Proxy(
+                [
+                    observable<T>((isFunction(initialValue) ? initialValue() : initialValue) as any),
+                    // Second element of the array just needs to exist for the Proxy to access it
+                    // but we can't ensure it's updated with the real value, and it doesn't really matter since it's proxied,
+                    // so just make it undefined. Alternatively the Proxy handler could manually return 2 for the "length" prop
+                    // but this seems easier and less code.
+                    undefined,
+                ],
+                proxyHandler,
+            ),
+        [],
+    ) as [Observable<T>, T];
+}
+
+const proxyHandler: ProxyHandler<any[]> = {
+    get(target, prop, receiver) {
+        // If the value is accessed at index 1 then `useSelector` to track it for changes
+        return prop === '1' ? useSelector(target[0]) : Reflect.get(target, prop, receiver);
+    },
+};

package/src/react/useObserve.ts

@@ -0,0 +1,54 @@
+import {
+    computeSelector,
+    isFunction,
+    ObservableParam,
+    observe,
+    ObserveEvent,
+    ObserveEventCallback,
+    Selector,
+} from '@legendapp/state';
+import { useRef } from 'react';
+import type { ObserveOptions } from '../observe';
+import { useUnmountOnce } from './useUnmount';
+
+export function useObserve<T>(run: (e: ObserveEvent<T>) => T | void, options?: ObserveOptions): () => void;
+export function useObserve<T>(
+    selector: Selector<T>,
+    reaction?: (e: ObserveEventCallback<T>) => any,
+    options?: ObserveOptions,
+): () => void;
+export function useObserve<T>(
+    selector: Selector<T> | ((e: ObserveEvent<T>) => any),
+    reactionOrOptions?: ((e: ObserveEventCallback<T>) => any) | ObserveOptions,
+    options?: ObserveOptions,
+): () => void {
+    let reaction: ((e: ObserveEventCallback<T>) => any) | undefined;
+    if (isFunction(reactionOrOptions)) {
+        reaction = reactionOrOptions;
+    } else {
+        options = reactionOrOptions;
+    }
+
+    const ref = useRef<{
+        selector?: Selector<T> | ((e: ObserveEvent<T>) => T | void) | ObservableParam<T>;
+        reaction?: (e: ObserveEventCallback<T>) => any;
+        dispose?: () => void;
+    }>({});
+
+    ref.current.selector = selector;
+    ref.current.reaction = reaction;
+
+    if (!ref.current.dispose) {
+        ref.current.dispose = observe<T>(
+            ((e: ObserveEventCallback<T>) => computeSelector(ref.current.selector, e)) as any,
+            (e) => ref.current.reaction?.(e),
+            options,
+        );
+    }
+
+    useUnmountOnce(() => {
+        ref.current?.dispose?.();
+    });
+
+    return ref.current.dispose;
+}

package/src/react/useObserveEffect.ts

@@ -0,0 +1,40 @@
+import { isFunction, ObservableParam, observe, ObserveEvent, ObserveEventCallback, Selector } from '@legendapp/state';
+import { useRef } from 'react';
+import type { ObserveOptions } from '../observe';
+import { useMountOnce } from './useMount';
+
+export function useObserveEffect<T>(run: (e: ObserveEvent<T>) => T | void, options?: ObserveOptions): void;
+export function useObserveEffect<T>(
+    selector: Selector<T>,
+    reaction?: (e: ObserveEventCallback<T>) => any,
+    options?: ObserveOptions,
+): void;
+export function useObserveEffect<T>(
+    selector: Selector<T> | ((e: ObserveEvent<T>) => any),
+    reactionOrOptions?: ((e: ObserveEventCallback<T>) => any) | ObserveOptions,
+    options?: ObserveOptions,
+): void {
+    let reaction: ((e: ObserveEventCallback<T>) => any) | undefined;
+    if (isFunction(reactionOrOptions)) {
+        reaction = reactionOrOptions;
+    } else {
+        options = reactionOrOptions;
+    }
+
+    const ref = useRef<{
+        selector: Selector<T> | ((e: ObserveEvent<T>) => T | void) | ObservableParam<T>;
+        reaction?: (e: ObserveEventCallback<T>) => any;
+    }>({ selector });
+    ref.current = { selector, reaction };
+
+    useMountOnce(() =>
+        observe<T>(
+            ((e: ObserveEventCallback<T>) => {
+                const { selector } = ref.current as { selector: (e: ObserveEvent<T>) => T | void };
+                return isFunction(selector) ? selector(e) : selector;
+            }) as any,
+            (e) => ref.current.reaction?.(e),
+            options,
+        ),
+    );
+}

package/src/react/usePauseProvider.tsx

@@ -0,0 +1,13 @@
+import { Observable, observable } from '@legendapp/state';
+import { ReactNode, createContext, createElement, useState } from 'react';
+
+export const PauseContext = createContext<Observable<boolean>>(null as any);
+
+export function usePauseProvider() {
+    const [value] = useState(() => observable(false));
+    return {
+        PauseProvider: ({ children }: { children: ReactNode }) =>
+            createElement(PauseContext.Provider, { value }, children),
+        isPaused$: value,
+    };
+}