@tale-ui/utils 0.0.3

package/esm/store/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./createSelector.js";
+export * from "./useStore.js";
+export * from "./Store.js";
+export * from "./ReactStore.js";
+export * from "./StoreInspector.js";

package/esm/store/index.js

@@ -0,0 +1,5 @@
+export * from "./createSelector.js";
+export * from "./useStore.js";
+export * from "./Store.js";
+export * from "./ReactStore.js";
+export * from "./StoreInspector.js";

package/esm/store/useStore.d.ts

@@ -0,0 +1,22 @@
+import { Instance } from "../fastHooks.js";
+import type { ReadonlyStore } from "./Store.js";
+export declare function useStore<State, Value>(store: ReadonlyStore<State>, selector: (state: State) => Value): Value;
+export declare function useStore<State, Value, A1>(store: ReadonlyStore<State>, selector: (state: State, a1: A1) => Value, a1: A1): Value;
+export declare function useStore<State, Value, A1, A2>(store: ReadonlyStore<State>, selector: (state: State, a1: A1, a2: A2) => Value, a1: A1, a2: A2): Value;
+export declare function useStore<State, Value, A1, A2, A3>(store: ReadonlyStore<State>, selector: (state: State, a1: A1, a2: A2, a3: A3) => Value, a1: A1, a2: A2, a3: A3): Value;
+export type StoreInstance = Instance & {
+  syncIndex: number;
+  syncTick: number;
+  syncHooks: {
+    store: any;
+    selector: Function;
+    a1: unknown;
+    a2: unknown;
+    a3: unknown;
+    value: unknown;
+    didChange: boolean;
+  }[];
+  didChangeStore: boolean;
+  subscribe: (onStoreChange: any) => () => void;
+  getSnapshot: () => unknown;
+};

package/esm/store/useStore.js

@@ -0,0 +1,107 @@
+import * as React from 'react';
+/* We need to import the shim because React 17 does not support the `useSyncExternalStore` API.
+ * More info: https://github.com/mui/mui-x/issues/18303#issuecomment-2958392341 */
+import { useSyncExternalStore } from 'use-sync-external-store/shim';
+import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector';
+import { isReactVersionAtLeast } from "../reactVersion.js";
+import { register, getInstance } from "../fastHooks.js";
+/* Some tests fail in R18 with the raw useSyncExternalStore. It may be possible to make it work
+ * but for now we only enable it for R19+. */
+const canUseRawUseSyncExternalStore = isReactVersionAtLeast(19);
+const useStoreImplementation = canUseRawUseSyncExternalStore ? useStoreFast : useStoreLegacy;
+export function useStore(store, selector, a1, a2, a3) {
+  return useStoreImplementation(store, selector, a1, a2, a3);
+}
+function useStoreR19(store, selector, a1, a2, a3) {
+  const getSelection = React.useCallback(() => selector(store.getSnapshot(), a1, a2, a3), [store, selector, a1, a2, a3]);
+  return useSyncExternalStore(store.subscribe, getSelection, getSelection);
+}
+register({
+  before(instance) {
+    instance.syncIndex = 0;
+    if (!instance.didInitialize) {
+      instance.syncTick = 1;
+      instance.syncHooks = [];
+      instance.didChangeStore = true;
+      instance.getSnapshot = () => {
+        let didChange = false;
+        for (let i = 0; i < instance.syncHooks.length; i += 1) {
+          const hook = instance.syncHooks[i];
+          const value = hook.selector(hook.store.state, hook.a1, hook.a2, hook.a3);
+          if (hook.didChange || !Object.is(hook.value, value)) {
+            didChange = true;
+            hook.value = value;
+            hook.didChange = false;
+          }
+        }
+        if (didChange) {
+          instance.syncTick += 1;
+        }
+        return instance.syncTick;
+      };
+    }
+  },
+  after(instance) {
+    if (instance.syncHooks.length > 0) {
+      if (instance.didChangeStore) {
+        instance.didChangeStore = false;
+        instance.subscribe = onStoreChange => {
+          const stores = new Set();
+          for (const hook of instance.syncHooks) {
+            stores.add(hook.store);
+          }
+          const unsubscribes = [];
+          for (const store of stores) {
+            unsubscribes.push(store.subscribe(onStoreChange));
+          }
+          return () => {
+            for (const unsubscribe of unsubscribes) {
+              unsubscribe();
+            }
+          };
+        };
+      }
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      useSyncExternalStore(instance.subscribe, instance.getSnapshot, instance.getSnapshot);
+    }
+  }
+});
+function useStoreFast(store, selector, a1, a2, a3) {
+  const instance = getInstance();
+  if (!instance) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    return useStoreR19(store, selector, a1, a2, a3);
+  }
+  const index = instance.syncIndex;
+  instance.syncIndex += 1;
+  let hook;
+  if (!instance.didInitialize) {
+    hook = {
+      store,
+      selector,
+      a1,
+      a2,
+      a3,
+      value: selector(store.getSnapshot(), a1, a2, a3),
+      didChange: false
+    };
+    instance.syncHooks.push(hook);
+  } else {
+    hook = instance.syncHooks[index];
+    if (hook.store !== store || hook.selector !== selector || !Object.is(hook.a1, a1) || !Object.is(hook.a2, a2) || !Object.is(hook.a3, a3)) {
+      if (hook.store !== store) {
+        instance.didChangeStore = true;
+      }
+      hook.store = store;
+      hook.selector = selector;
+      hook.a1 = a1;
+      hook.a2 = a2;
+      hook.a3 = a3;
+      hook.didChange = true;
+    }
+  }
+  return hook.value;
+}
+function useStoreLegacy(store, selector, a1, a2, a3) {
+  return useSyncExternalStoreWithSelector(store.subscribe, store.getSnapshot, store.getSnapshot, state => selector(state, a1, a2, a3));
+}

package/esm/testUtils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Whether the test runs in JSDOM environment
+ */
+export declare const isJSDOM: boolean;
+export type IfEquals<T, U, Y = unknown, N = never> = (<G>() => G extends T ? 1 : 2) extends (<G>() => G extends U ? 1 : 2) ? Y : N;
+/**
+ * Issues a type error if `Expected` is not identical to `Actual`.
+ *
+ * `Expected` should be declared when invoking `expectType`.
+ * `Actual` should almost always we be a `typeof value` statement.
+ *
+ * @example `expectType<number | string, typeof value>(value)`
+ * TypeScript issues a type error since `value is not assignable to never`.
+ * This means `typeof value` is not identical to `number | string`
+ * @param _actual
+ */
+export declare function expectType<Expected, Actual>(_actual: IfEquals<Actual, Expected, Actual>): void;

package/esm/testUtils.js

@@ -0,0 +1,19 @@
+/**
+ * Whether the test runs in JSDOM environment
+ */
+export const isJSDOM = /jsdom/.test(window.navigator.userAgent);
+
+// https://stackoverflow.com/questions/53807517/how-to-test-if-two-types-are-exactly-the-same
+
+/**
+ * Issues a type error if `Expected` is not identical to `Actual`.
+ *
+ * `Expected` should be declared when invoking `expectType`.
+ * `Actual` should almost always we be a `typeof value` statement.
+ *
+ * @example `expectType<number | string, typeof value>(value)`
+ * TypeScript issues a type error since `value is not assignable to never`.
+ * This means `typeof value` is not identical to `number | string`
+ * @param _actual
+ */
+export function expectType(_actual) {}

package/esm/useAnimationFrame.d.ts

@@ -0,0 +1,18 @@
+type AnimationFrameId = number;
+export declare class AnimationFrame {
+  static create(): AnimationFrame;
+  static request(fn: FrameRequestCallback): number;
+  static cancel(id: AnimationFrameId): void;
+  currentId: AnimationFrameId | null;
+  /**
+   * Executes `fn` after `delay`, clearing any previously scheduled call.
+   */
+  request(fn: Function): void;
+  cancel: () => void;
+  disposeEffect: () => () => void;
+}
+/**
+ * A `requestAnimationFrame` with automatic cleanup and guard.
+ */
+export declare function useAnimationFrame(): AnimationFrame;
+export {};

package/esm/useAnimationFrame.js

@@ -0,0 +1,106 @@
+'use client';
+
+import { useRefWithInit } from "./useRefWithInit.js";
+import { useOnMount } from "./useOnMount.js";
+/** Unlike `setTimeout`, rAF doesn't guarantee a positive integer return value, so we can't have
+ * a monomorphic `uint` type with `0` meaning empty.
+ * See warning note at:
+ * https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame#return_value */
+const EMPTY = null;
+let LAST_RAF = globalThis.requestAnimationFrame;
+class Scheduler {
+  /* This implementation uses an array as a backing data-structure for frame callbacks.
+   * It allows `O(1)` callback cancelling by inserting a `null` in the array, though it
+   * never calls the native `cancelAnimationFrame` if there are no frames left. This can
+   * be much more efficient if there is a call pattern that alterns as
+   * "request-cancel-request-cancel-…".
+   * But in the case of "request-request-…-cancel-cancel-…", it leaves the final animation
+   * frame to run anyway. We turn that frame into a `O(1)` no-op via `callbacksCount`. */
+
+  callbacks = [];
+  callbacksCount = 0;
+  nextId = 1;
+  startId = 1;
+  isScheduled = false;
+  tick = timestamp => {
+    this.isScheduled = false;
+    const currentCallbacks = this.callbacks;
+    const currentCallbacksCount = this.callbacksCount;
+
+    // Update these before iterating, callbacks could call `requestAnimationFrame` again.
+    this.callbacks = [];
+    this.callbacksCount = 0;
+    this.startId = this.nextId;
+    if (currentCallbacksCount > 0) {
+      for (let i = 0; i < currentCallbacks.length; i += 1) {
+        currentCallbacks[i]?.(timestamp);
+      }
+    }
+  };
+  request(fn) {
+    const id = this.nextId;
+    this.nextId += 1;
+    this.callbacks.push(fn);
+    this.callbacksCount += 1;
+
+    /* In a test environment with fake timers, a fake `requestAnimationFrame` can be called
+     * but there's no guarantee that the animation frame will actually run before the fake
+     * timers are teared, which leaves `isScheduled` set, but won't run our `tick()`. */
+    const didRAFChange = process.env.NODE_ENV !== 'production' && LAST_RAF !== requestAnimationFrame && (LAST_RAF = requestAnimationFrame, true);
+    if (!this.isScheduled || didRAFChange) {
+      requestAnimationFrame(this.tick);
+      this.isScheduled = true;
+    }
+    return id;
+  }
+  cancel(id) {
+    const index = id - this.startId;
+    if (index < 0 || index >= this.callbacks.length) {
+      return;
+    }
+    this.callbacks[index] = null;
+    this.callbacksCount -= 1;
+  }
+}
+const scheduler = new Scheduler();
+export class AnimationFrame {
+  static create() {
+    return new AnimationFrame();
+  }
+  static request(fn) {
+    return scheduler.request(fn);
+  }
+  static cancel(id) {
+    return scheduler.cancel(id);
+  }
+  currentId = EMPTY;
+
+  /**
+   * Executes `fn` after `delay`, clearing any previously scheduled call.
+   */
+  request(fn) {
+    this.cancel();
+    this.currentId = scheduler.request(() => {
+      this.currentId = EMPTY;
+      fn();
+    });
+  }
+  cancel = () => {
+    if (this.currentId !== EMPTY) {
+      scheduler.cancel(this.currentId);
+      this.currentId = EMPTY;
+    }
+  };
+  disposeEffect = () => {
+    return this.cancel;
+  };
+}
+
+/**
+ * A `requestAnimationFrame` with automatic cleanup and guard.
+ */
+export function useAnimationFrame() {
+  const timeout = useRefWithInit(AnimationFrame.create).current;
+  useOnMount(timeout.disposeEffect);
+  return timeout;
+}

package/esm/useControlled.d.ts

@@ -0,0 +1,24 @@
+export interface UseControlledProps<T = unknown> {
+  /**
+   * Holds the component value when it's controlled.
+   */
+  controlled: T | undefined;
+  /**
+   * The default value when uncontrolled.
+   */
+  default: T | undefined;
+  /**
+   * The component name displayed in warnings.
+   */
+  name: string;
+  /**
+   * The name of the state variable displayed in warnings.
+   */
+  state?: string | undefined;
+}
+export declare function useControlled<T = unknown>({
+  controlled,
+  default: defaultProp,
+  name,
+  state
+}: UseControlledProps<T>): [T, (newValue: T | ((prevValue: T) => T)) => void];

package/esm/useControlled.js

@@ -0,0 +1,40 @@
+'use client';
+
+// TODO: uncomment once we enable eslint-plugin-react-compiler // eslint-disable-next-line react-compiler/react-compiler -- process.env never changes, dependency arrays are intentionally ignored
+/* eslint-disable react-hooks/rules-of-hooks, react-hooks/exhaustive-deps */
+import * as React from 'react';
+export function useControlled({
+  controlled,
+  default: defaultProp,
+  name,
+  state = 'value'
+}) {
+  // isControlled is ignored in the hook dependency lists as it should never change.
+  const {
+    current: isControlled
+  } = React.useRef(controlled !== undefined);
+  const [valueState, setValue] = React.useState(defaultProp);
+  const value = isControlled ? controlled : valueState;
+  if (process.env.NODE_ENV !== 'production') {
+    React.useEffect(() => {
+      if (isControlled !== (controlled !== undefined)) {
+        console.error([`Tale UI: A component is changing the ${isControlled ? '' : 'un'}controlled ${state} state of ${name} to be ${isControlled ? 'un' : ''}controlled.`, 'Elements should not switch from uncontrolled to controlled (or vice versa).', `Decide between using a controlled or uncontrolled ${name} ` + 'element for the lifetime of the component.', "The nature of the state is determined during the first render. It's considered controlled if the value is not `undefined`.", 'More info: https://fb.me/react-controlled-components'].join('\n'));
+      }
+    }, [state, name, controlled]);
+    const {
+      current: defaultValue
+    } = React.useRef(defaultProp);
+    React.useEffect(() => {
+      // See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is for more details.
+      if (!isControlled && JSON.stringify(defaultValue) !== JSON.stringify(defaultProp)) {
+        console.error([`Tale UI: A component is changing the default ${state} state of an uncontrolled ${name} after being initialized. ` + `To suppress this warning opt to use a controlled ${name}.`].join('\n'));
+      }
+    }, [JSON.stringify(defaultProp)]);
+  }
+  const setValueIfUncontrolled = React.useCallback(newValue => {
+    if (!isControlled) {
+      setValue(newValue);
+    }
+  }, []);
+  return [value, setValueIfUncontrolled];
+}

package/esm/useEnhancedClickHandler.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+export type InteractionType = 'mouse' | 'touch' | 'pen' | 'keyboard' | '';
+/**
+ * Provides a cross-browser way to determine the type of the pointer used to click.
+ * Safari and Firefox do not provide the PointerEvent to the click handler (they use MouseEvent) yet.
+ * Additionally, this implementation detects if the click was triggered by the keyboard.
+ *
+ * @param handler The function to be called when the button is clicked. The first parameter is the original event and the second parameter is the pointer type.
+ */
+export declare function useEnhancedClickHandler(handler: (event: React.MouseEvent | React.PointerEvent, interactionType: InteractionType) => void): {
+  onClick: (event: React.MouseEvent | React.PointerEvent) => void;
+  onPointerDown: (event: React.PointerEvent) => void;
+};

package/esm/useEnhancedClickHandler.js

@@ -0,0 +1,38 @@
+'use client';
+
+import * as React from 'react';
+/**
+ * Provides a cross-browser way to determine the type of the pointer used to click.
+ * Safari and Firefox do not provide the PointerEvent to the click handler (they use MouseEvent) yet.
+ * Additionally, this implementation detects if the click was triggered by the keyboard.
+ *
+ * @param handler The function to be called when the button is clicked. The first parameter is the original event and the second parameter is the pointer type.
+ */
+export function useEnhancedClickHandler(handler) {
+  const lastClickInteractionTypeRef = React.useRef('');
+  const handlePointerDown = React.useCallback(event => {
+    if (event.defaultPrevented) {
+      return;
+    }
+    lastClickInteractionTypeRef.current = event.pointerType;
+    handler(event, event.pointerType);
+  }, [handler]);
+  const handleClick = React.useCallback(event => {
+    // event.detail has the number of clicks performed on the element. 0 means it was triggered by the keyboard.
+    if (event.detail === 0) {
+      handler(event, 'keyboard');
+      return;
+    }
+    if ('pointerType' in event) {
+      // Chrome and Edge correctly use PointerEvent
+      handler(event, event.pointerType);
+    } else {
+      handler(event, lastClickInteractionTypeRef.current);
+    }
+    lastClickInteractionTypeRef.current = '';
+  }, [handler]);
+  return {
+    onClick: handleClick,
+    onPointerDown: handlePointerDown
+  };
+}

package/esm/useForcedRerendering.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns a function that forces a rerender.
+ */
+export declare function useForcedRerendering(): () => void;

package/esm/useForcedRerendering.js

@@ -0,0 +1,13 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Returns a function that forces a rerender.
+ */
+export function useForcedRerendering() {
+  const [, setState] = React.useState({});
+  return React.useCallback(() => {
+    setState({});
+  }, []);
+}

package/esm/useId.d.ts

@@ -0,0 +1,7 @@
+/**
+ *
+ * @example <div id={useId()} />
+ * @param idOverride
+ * @returns {string}
+ */
+export declare function useId(idOverride?: string, prefix?: string): string | undefined;

package/esm/useId.js

@@ -0,0 +1,41 @@
+'use client';
+
+import * as React from 'react';
+import { SafeReact } from "./safeReact.js";
+let globalId = 0;
+
+// TODO React 17: Remove `useGlobalId` once React 17 support is removed
+function useGlobalId(idOverride, prefix = 'tale-ui') {
+  const [defaultId, setDefaultId] = React.useState(idOverride);
+  const id = idOverride || defaultId;
+  React.useEffect(() => {
+    if (defaultId == null) {
+      // Fallback to this default id when possible.
+      // Use the incrementing value for client-side rendering only.
+      // We can't use it server-side.
+      // If you want to use random values please consider the Birthday Problem: https://en.wikipedia.org/wiki/Birthday_problem
+      globalId += 1;
+      setDefaultId(`${prefix}-${globalId}`);
+    }
+  }, [defaultId, prefix]);
+  return id;
+}
+const maybeReactUseId = SafeReact.useId;
+
+/**
+ *
+ * @example <div id={useId()} />
+ * @param idOverride
+ * @returns {string}
+ */
+export function useId(idOverride, prefix) {
+  // React.useId() is only available from React 17.0.0.
+  if (maybeReactUseId !== undefined) {
+    const reactId = maybeReactUseId();
+    return idOverride ?? (prefix ? `${prefix}-${reactId}` : reactId);
+  }
+
+  // TODO: uncomment once we enable eslint-plugin-react-compiler // eslint-disable-next-line react-compiler/react-compiler
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- `React.useId` is invariant at runtime.
+  return useGlobalId(idOverride, prefix);
+}

package/esm/useInterval.d.ts

@@ -0,0 +1,13 @@
+import { Timeout } from "./useTimeout.js";
+export declare class Interval extends Timeout {
+  static create(): Interval;
+  /**
+   * Executes `fn` at `delay` interval, clearing any previously scheduled call.
+   */
+  start(delay: number, fn: Function): void;
+  clear: () => void;
+}
+/**
+ * A `setInterval` with automatic cleanup and guard.
+ */
+export declare function useInterval(): Interval;

package/esm/useInterval.js

@@ -0,0 +1,36 @@
+'use client';
+
+import { useRefWithInit } from "./useRefWithInit.js";
+import { useOnMount } from "./useOnMount.js";
+import { Timeout } from "./useTimeout.js";
+const EMPTY = 0;
+export class Interval extends Timeout {
+  static create() {
+    return new Interval();
+  }
+
+  /**
+   * Executes `fn` at `delay` interval, clearing any previously scheduled call.
+   */
+  start(delay, fn) {
+    this.clear();
+    this.currentId = setInterval(() => {
+      fn();
+    }, delay);
+  }
+  clear = () => {
+    if (this.currentId !== EMPTY) {
+      clearInterval(this.currentId);
+      this.currentId = EMPTY;
+    }
+  };
+}
+
+/**
+ * A `setInterval` with automatic cleanup and guard.
+ */
+export function useInterval() {
+  const timeout = useRefWithInit(Interval.create).current;
+  useOnMount(timeout.disposeEffect);
+  return timeout;
+}

package/esm/useIsoLayoutEffect.d.ts

@@ -0,0 +1,2 @@
+import * as React from 'react';
+export declare const useIsoLayoutEffect: typeof React.useLayoutEffect;

package/esm/useIsoLayoutEffect.js

@@ -0,0 +1,5 @@
+'use client';
+
+import * as React from 'react';
+const noop = () => {};
+export const useIsoLayoutEffect = typeof document !== 'undefined' ? React.useLayoutEffect : noop;

package/esm/useMergedRefs.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+type Empty = null | undefined;
+type InputRef<I> = React.Ref<I> | Empty;
+type Result<I> = React.RefCallback<I> | null;
+/**
+ * Merges refs into a single memoized callback ref or `null`.
+ * This makes sure multiple refs are updated together and have the same value.
+ *
+ * This function accepts up to four refs. If you need to merge more, or have an unspecified number of refs to merge,
+ * use `useMergedRefsN` instead.
+ */
+export declare function useMergedRefs<I>(a: InputRef<I>, b: InputRef<I>): Result<I>;
+export declare function useMergedRefs<I>(a: InputRef<I>, b: InputRef<I>, c: InputRef<I>): Result<I>;
+export declare function useMergedRefs<I>(a: InputRef<I>, b: InputRef<I>, c: InputRef<I>, d: InputRef<I>): Result<I>;
+/**
+ * Merges an array of refs into a single memoized callback ref or `null`.
+ *
+ * If you need to merge a fixed number (up to four) of refs, use `useMergedRefs` instead for better performance.
+ */
+export declare function useMergedRefsN<I>(refs: InputRef<I>[]): Result<I>;
+export {};