@tale-ui/utils 0.0.3

package/esm/store/ReactStore.js

@@ -0,0 +1,199 @@
+/* False positives - ESLint thinks we're calling a hook from a class component. */
+/* eslint-disable react-hooks/rules-of-hooks */
+'use client';
+
+import * as React from 'react';
+import { Store } from "./Store.js";
+import { useStore } from "./useStore.js";
+import { useStableCallback } from "../useStableCallback.js";
+import { useIsoLayoutEffect } from "../useIsoLayoutEffect.js";
+import { NOOP } from "../empty.js";
+
+/**
+ * A Store that supports controlled state keys, non-reactive values and provides utility methods for React.
+ */
+export class ReactStore extends Store {
+  /**
+   * Creates a new ReactStore instance.
+   *
+   * @param state Initial state of the store.
+   * @param context Non-reactive context values.
+   * @param selectors Optional selectors for use with `useState`.
+   */
+  constructor(state, context = {}, selectors) {
+    super(state);
+    this.context = context;
+    this.selectors = selectors;
+  }
+
+  /**
+   * Non-reactive values such as refs, callbacks, etc.
+   */
+
+  /**
+   * Synchronizes a single external value into the store.
+   *
+   * Note that the while the value in `state` is updated immediately, the value returned
+   * by `useState` is updated before the next render (similarly to React's `useState`).
+   */
+  useSyncedValue(key, value) {
+    React.useDebugValue(key);
+    useIsoLayoutEffect(() => {
+      if (this.state[key] !== value) {
+        this.set(key, value);
+      }
+    }, [key, value]);
+  }
+
+  /**
+   * Synchronizes a single external value into the store and
+   * cleans it up (sets to `undefined`) on unmount.
+   *
+   * Note that the while the value in `state` is updated immediately, the value returned
+   * by `useState` is updated before the next render (similarly to React's `useState`).
+   */
+  useSyncedValueWithCleanup(key, value) {
+    // eslint-disable-next-line consistent-this
+    const store = this;
+    useIsoLayoutEffect(() => {
+      if (store.state[key] !== value) {
+        store.set(key, value);
+      }
+      return () => {
+        store.set(key, undefined);
+      };
+    }, [store, key, value]);
+  }
+
+  /**
+   * Synchronizes multiple external values into the store.
+   *
+   * Note that the while the values in `state` are updated immediately, the values returned
+   * by `useState` are updated before the next render (similarly to React's `useState`).
+   */
+  useSyncedValues(statePart) {
+    // eslint-disable-next-line consistent-this
+    const store = this;
+    if (process.env.NODE_ENV !== 'production') {
+      // Check that an object with the same shape is passed on every render
+      React.useDebugValue(statePart, p => Object.keys(p));
+      const keys = React.useRef(Object.keys(statePart)).current;
+      const nextKeys = Object.keys(statePart);
+      if (keys.length !== nextKeys.length || keys.some((key, index) => key !== nextKeys[index])) {
+        console.error('ReactStore.useSyncedValues expects the same prop keys on every render. Keys should be stable.');
+      }
+    }
+    const dependencies = Object.values(statePart);
+    useIsoLayoutEffect(() => {
+      store.update(statePart);
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store, ...dependencies]);
+  }
+
+  /**
+   * Registers a controllable prop pair (`controlled`, `defaultValue`) for a specific key. If `controlled`
+   * is non-undefined, the store's state at `key` is updated to match `controlled`.
+   */
+  useControlledProp(key, controlled) {
+    React.useDebugValue(key);
+    const isControlled = controlled !== undefined;
+    useIsoLayoutEffect(() => {
+      if (isControlled && !Object.is(this.state[key], controlled)) {
+        // Set the internal state to match the controlled value.
+        super.setState({
+          ...this.state,
+          [key]: controlled
+        });
+      }
+    }, [key, controlled, isControlled]);
+    if (process.env.NODE_ENV !== 'production') {
+      // eslint-disable-next-line
+      const cache = this.controlledValues ??= new Map();
+      if (!cache.has(key)) {
+        cache.set(key, isControlled);
+      }
+      const previouslyControlled = cache.get(key);
+      if (previouslyControlled !== undefined && previouslyControlled !== isControlled) {
+        console.error(`A component is changing the ${isControlled ? '' : 'un'}controlled state of ${key.toString()} to be ${isControlled ? 'un' : ''}controlled. Elements should not switch from uncontrolled to controlled (or vice versa).`);
+      }
+    }
+  }
+
+  /** Gets the current value from the store using a selector with the provided key.
+   *
+   * @param key Key of the selector to use.
+   */
+
+  select(key, a1, a2, a3) {
+    const selector = this.selectors[key];
+    return selector(this.state, a1, a2, a3);
+  }
+
+  /**
+   * Returns a value from the store's state using a selector function.
+   * Used to subscribe to specific parts of the state.
+   * This methods causes a rerender whenever the selected state changes.
+   *
+   * @param key Key of the selector to use.
+   */
+
+  useState(key, a1, a2, a3) {
+    React.useDebugValue(key);
+    return useStore(this, this.selectors[key], a1, a2, a3);
+  }
+
+  /**
+   * Wraps a function with `useStableCallback` to ensure it has a stable reference
+   * and assigns it to the context.
+   *
+   * @param key Key of the event callback. Must be a function in the context.
+   * @param fn Function to assign.
+   */
+  useContextCallback(key, fn) {
+    React.useDebugValue(key);
+    const stableFunction = useStableCallback(fn ?? NOOP);
+    this.context[key] = stableFunction;
+  }
+
+  /**
+   * Returns a stable setter function for a specific key in the store's state.
+   * It's commonly used to pass as a ref callback to React elements.
+   *
+   * @param key Key of the state to set.
+   */
+  useStateSetter(key) {
+    const ref = React.useRef(undefined);
+    if (ref.current === undefined) {
+      ref.current = value => {
+        this.set(key, value);
+      };
+    }
+    return ref.current;
+  }
+
+  /**
+   * Observes changes derived from the store's selectors and calls the listener when the selected value changes.
+   *
+   * @param key Key of the selector to observe.
+   * @param listener Listener function called when the selector result changes.
+   */
+
+  observe(selector, listener) {
+    let selectFn;
+    if (typeof selector === 'function') {
+      selectFn = selector;
+    } else {
+      selectFn = this.selectors[selector];
+    }
+    let prevValue = selectFn(this.state);
+    listener(prevValue, prevValue, this);
+    return this.subscribe(nextState => {
+      const nextValue = selectFn(nextState);
+      if (!Object.is(prevValue, nextValue)) {
+        const oldValue = prevValue;
+        prevValue = nextValue;
+        listener(nextValue, oldValue, this);
+      }
+    });
+  }
+}

package/esm/store/Store.d.ts

@@ -0,0 +1,58 @@
+type Listener<T> = (state: T) => void;
+/**
+ * A data store implementation that allows subscribing to state changes and updating the state.
+ * It uses an observer pattern to notify subscribers when the state changes.
+ */
+export declare class Store<State> {
+  /**
+   * The current state of the store.
+   * This property is updated immediately when the state changes as a result of calling {@link setState}, {@link update}, or {@link set}.
+   * To subscribe to state changes, use the {@link useState} method. The value returned by {@link useState} is updated after the component renders (similarly to React's useState).
+   * The values can be used directly (to avoid subscribing to the store) in effects or event handlers.
+   *
+   * Do not modify properties in state directly. Instead, use the provided methods to ensure proper state management and listener notification.
+   */
+  state: State;
+  private listeners;
+  private updateTick;
+  constructor(state: State);
+  /**
+   * Registers a listener that will be called whenever the store's state changes.
+   *
+   * @param fn The listener function to be called on state changes.
+   * @returns A function to unsubscribe the listener.
+   */
+  subscribe: (fn: Listener<State>) => () => void;
+  /**
+   * Returns the current state of the store.
+   */
+  getSnapshot: () => State;
+  /**
+   * Updates the entire store's state and notifies all registered listeners.
+   *
+   * @param newState The new state to set for the store.
+   */
+  setState(newState: State): void;
+  /**
+   * Merges the provided changes into the current state and notifies listeners if there are changes.
+   *
+   * @param changes An object containing the changes to apply to the current state.
+   */
+  update(changes: Partial<State>): void;
+  /**
+   * Sets a specific key in the store's state to a new value and notifies listeners if the value has changed.
+   *
+   * @param key The key in the store's state to update.
+   * @param value The new value to set for the specified key.
+   */
+  set<T>(key: keyof State, value: T): void;
+  /**
+   * Gives the state a new reference and updates all registered listeners.
+   */
+  notifyAll(): void;
+  use<F extends (...args: any) => any>(selector: F, ...args: SelectorArgs<F>): ReturnType<F>;
+}
+export type ReadonlyStore<State> = Pick<Store<State>, 'getSnapshot' | 'subscribe' | 'state'>;
+type SelectorArgs<Selector> = Selector extends ((...params: infer Params) => any) ? Tail<Params> : never;
+type Tail<T extends readonly any[]> = T extends readonly [any, ...infer Rest] ? Rest : [];
+export {};

package/esm/store/Store.js

@@ -0,0 +1,111 @@
+import { useStore } from "./useStore.js";
+/**
+ * A data store implementation that allows subscribing to state changes and updating the state.
+ * It uses an observer pattern to notify subscribers when the state changes.
+ */
+export class Store {
+  /**
+   * The current state of the store.
+   * This property is updated immediately when the state changes as a result of calling {@link setState}, {@link update}, or {@link set}.
+   * To subscribe to state changes, use the {@link useState} method. The value returned by {@link useState} is updated after the component renders (similarly to React's useState).
+   * The values can be used directly (to avoid subscribing to the store) in effects or event handlers.
+   *
+   * Do not modify properties in state directly. Instead, use the provided methods to ensure proper state management and listener notification.
+   */
+
+  // Internal state to handle recursive `setState()` calls
+
+  constructor(state) {
+    this.state = state;
+    this.listeners = new Set();
+    this.updateTick = 0;
+  }
+
+  /**
+   * Registers a listener that will be called whenever the store's state changes.
+   *
+   * @param fn The listener function to be called on state changes.
+   * @returns A function to unsubscribe the listener.
+   */
+  subscribe = fn => {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  };
+
+  /**
+   * Returns the current state of the store.
+   */
+  getSnapshot = () => {
+    return this.state;
+  };
+
+  /**
+   * Updates the entire store's state and notifies all registered listeners.
+   *
+   * @param newState The new state to set for the store.
+   */
+  setState(newState) {
+    if (this.state === newState) {
+      return;
+    }
+    this.state = newState;
+    this.updateTick += 1;
+    const currentTick = this.updateTick;
+    for (const listener of this.listeners) {
+      if (currentTick !== this.updateTick) {
+        // If the tick has changed, a recursive `setState` call has been made,
+        // and it has already notified all listeners.
+        return;
+      }
+      listener(newState);
+    }
+  }
+
+  /**
+   * Merges the provided changes into the current state and notifies listeners if there are changes.
+   *
+   * @param changes An object containing the changes to apply to the current state.
+   */
+  update(changes) {
+    for (const key in changes) {
+      if (!Object.is(this.state[key], changes[key])) {
+        this.setState({
+          ...this.state,
+          ...changes
+        });
+        return;
+      }
+    }
+  }
+
+  /**
+   * Sets a specific key in the store's state to a new value and notifies listeners if the value has changed.
+   *
+   * @param key The key in the store's state to update.
+   * @param value The new value to set for the specified key.
+   */
+  set(key, value) {
+    if (!Object.is(this.state[key], value)) {
+      this.setState({
+        ...this.state,
+        [key]: value
+      });
+    }
+  }
+
+  /**
+   * Gives the state a new reference and updates all registered listeners.
+   */
+  notifyAll() {
+    const newState = {
+      ...this.state
+    };
+    this.setState(newState);
+  }
+  use(selector, a1, a2, a3) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    return useStore(this, selector, a1, a2, a3);
+  }
+}

package/esm/store/StoreInspector.d.ts

@@ -0,0 +1,41 @@
+import * as React from 'react';
+import { Store } from "./Store.js";
+export interface StoreInspectorProps {
+  /**
+   * Instance of the store to inspect.
+   */
+  store: Store<any>;
+  /**
+   * Additional data to display in the inspector.
+   */
+  additionalData?: any;
+  /**
+   * Title to display in the panel header.
+   */
+  title?: string | undefined;
+  /**
+   * Whether the inspector panel should be open by default.
+   * @default false
+   */
+  defaultOpen?: boolean | undefined;
+}
+/**
+ * A tool to inspect the state of a Store in a floating panel.
+ * This is intended for development and debugging purposes.
+ */
+export declare function StoreInspector(props: StoreInspectorProps): import("react/jsx-runtime").JSX.Element;
+interface PanelProps {
+  store: Store<any>;
+  title?: string | undefined;
+  additionalData?: any;
+  open: boolean;
+  onClose?: (() => void) | undefined;
+}
+export declare function StoreInspectorPanel({
+  store,
+  title,
+  additionalData,
+  open,
+  onClose
+}: PanelProps): React.ReactPortal | null;
+export {};