@limonify/zest-ui 0.1.0

package/src/fieldset/root/FieldsetRoot.tsx

@@ -0,0 +1,58 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { ZestUIComponentProps } from '../../types';
+import { FieldsetRootContext } from './FieldsetRootContext';
+
+/**
+ * Groups related fields, with an optional `Fieldset.Legend`.
+ * Renders a `<View>`.
+ *
+ * A disabled fieldset disables every `Field.Root` inside it.
+ */
+export function FieldsetRoot(componentProps: FieldsetRoot.Props) {
+  const { render, className, style, disabled = false, ref, ...elementProps } = componentProps;
+
+  const [legendId, setLegendId] = React.useState<string | undefined>(undefined);
+
+  const state: FieldsetRoot.State = React.useMemo(() => ({ disabled }), [disabled]);
+
+  const contextValue: FieldsetRootContext = React.useMemo(
+    () => ({ disabled, legendId, setLegendId }),
+    [disabled, legendId],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [
+      { role: 'group' as const, accessibilityLabelledBy: legendId, 'aria-labelledby': legendId },
+      elementProps,
+    ],
+  });
+
+  return (
+    <FieldsetRootContext.Provider value={contextValue}>{element}</FieldsetRootContext.Provider>
+  );
+}
+
+export interface FieldsetRootState {
+  /**
+   * Whether the fieldset is disabled.
+   */
+  disabled: boolean;
+}
+
+export interface FieldsetRootProps extends ZestUIComponentProps<typeof View, FieldsetRootState> {
+  /**
+   * Whether the fieldset and all fields inside it are disabled.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+}
+
+export namespace FieldsetRoot {
+  export type State = FieldsetRootState;
+  export type Props = FieldsetRootProps;
+}

package/src/fieldset/root/FieldsetRootContext.ts

@@ -0,0 +1,26 @@
+'use client';
+import * as React from 'react';
+
+export interface FieldsetRootContext {
+  /**
+   * Whether the fieldset (and every field inside it) is disabled.
+   */
+  disabled: boolean;
+  legendId: string | undefined;
+  setLegendId: (id: string | undefined) => void;
+}
+
+export const FieldsetRootContext = React.createContext<FieldsetRootContext | undefined>(undefined);
+
+export function useFieldsetRootContext(optional: false): FieldsetRootContext | undefined;
+export function useFieldsetRootContext(optional?: true): FieldsetRootContext;
+export function useFieldsetRootContext(optional = true): FieldsetRootContext | undefined {
+  const context = React.useContext(FieldsetRootContext);
+  if (context === undefined && optional) {
+    throw new Error(
+      'Zest: FieldsetRootContext is missing. Fieldset parts must be placed within <Fieldset.Root>.',
+    );
+  }
+
+  return context;
+}

package/src/globals.d.ts

@@ -0,0 +1,21 @@
+/*
+ * Minimal ambient declarations for globals that exist in every React Native
+ * runtime (Hermes / JSC / react-native-web) but aren't part of the ES lib.
+ * We deliberately avoid pulling in the full DOM lib or @types/node.
+ */
+
+declare const process: { env: { NODE_ENV?: string } };
+
+type FrameRequestCallback = (time: number) => void;
+
+declare function requestAnimationFrame(callback: FrameRequestCallback): number;
+declare function cancelAnimationFrame(handle: number): void;
+
+declare function setTimeout(handler: (...args: any[]) => void, timeout?: number): number;
+declare function clearTimeout(handle?: number): void;
+declare function setInterval(handler: (...args: any[]) => void, timeout?: number): number;
+declare function clearInterval(handle?: number): void;
+
+// Aliased to `global` on native and in react-native's jest setup; native on
+// react-native-web. Referenced only behind `typeof` guards.
+declare const window: unknown | undefined;

package/src/hooks/index.ts

@@ -0,0 +1,14 @@
+export * from './useAnimationFrame';
+export * from './useControlled';
+export * from './useForcedRerendering';
+export * from './useId';
+export * from './useInterval';
+export * from './useIsoLayoutEffect';
+export * from './useMergedRefs';
+export * from './useOnFirstRender';
+export * from './useOnMount';
+export * from './usePreviousValue';
+export * from './useRefWithInit';
+export * from './useStableCallback';
+export * from './useTimeout';
+export * from './useValueAsRef';

package/src/hooks/useAnimationFrame.ts

@@ -0,0 +1,156 @@
+'use client';
+import { useRefWithInit } from './useRefWithInit';
+import { useOnMount } from './useOnMount';
+
+type AnimationFrameId = number;
+
+/* Unlike `setTimeout`, rAF doesn't guarantee a positive integer return value, so we can't have
+ * a monomorphic `uint` type with `0` meaning empty. */
+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. */
+
+  callbacks = [] as (FrameRequestCallback | null)[];
+
+  callbacksCount = 0;
+
+  nextId = 1;
+
+  startId = 1;
+
+  isScheduled = false;
+
+  /* The handle of the frame `tick` is scheduled on. Kept only so
+   * `resetAnimationFrameScheduler` can cancel it; the hot path never does. */
+  scheduledFrameId: AnimationFrameId | null = EMPTY;
+
+  tick = (timestamp: number) => {
+    this.isScheduled = false;
+    this.scheduledFrameId = EMPTY;
+
+    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: FrameRequestCallback) {
+    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) {
+      this.scheduledFrameId = requestAnimationFrame(this.tick);
+      this.isScheduled = true;
+    }
+    return id;
+  }
+
+  cancel(id: AnimationFrameId) {
+    const index = id - this.startId;
+    if (index < 0 || index >= this.callbacks.length) {
+      return;
+    }
+    this.callbacks[index] = null;
+    this.callbacksCount -= 1;
+  }
+}
+
+let scheduler = new Scheduler();
+
+/**
+ * Replaces the shared scheduler and drops all pending animation frame callbacks.
+ *
+ * For test environments only. The scheduler is process-global, so a callback scheduled in one test
+ * but never run would otherwise survive into a later test and run there against stale state.
+ */
+export function resetAnimationFrameScheduler() {
+  const previous = scheduler;
+  scheduler = new Scheduler();
+  scheduler.nextId = previous.nextId;
+  scheduler.startId = previous.nextId;
+  previous.callbacks = [];
+  previous.callbacksCount = 0;
+
+  /* Dropping the callbacks is not enough: the frame `tick` is scheduled on is still pending, and
+   * jest-expo implements `requestAnimationFrame` as a `setTimeout` that reads the (by then torn
+   * down) Jest environment. Leaving it queued surfaces as a "you are trying to access ... after it
+   * has been torn down" error attributed to whichever test file scheduled it. */
+  if (previous.scheduledFrameId !== EMPTY) {
+    cancelAnimationFrame(previous.scheduledFrameId);
+    previous.scheduledFrameId = EMPTY;
+    previous.isScheduled = false;
+  }
+}
+
+export class AnimationFrame {
+  static create() {
+    return new AnimationFrame();
+  }
+
+  static request(fn: FrameRequestCallback) {
+    return scheduler.request(fn);
+  }
+
+  static cancel(id: AnimationFrameId) {
+    return scheduler.cancel(id);
+  }
+
+  currentId: AnimationFrameId | null = EMPTY;
+
+  /**
+   * Executes `fn` on the next frame, clearing any previously scheduled call.
+   */
+  request(fn: Function) {
+    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/src/hooks/useControlled.ts

@@ -0,0 +1,111 @@
+'use client';
+/* eslint-disable react-hooks/rules-of-hooks, react-hooks/exhaustive-deps */
+import * as React from 'react';
+import { error } from '../utils/error';
+
+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 function useControlled<T = unknown>({
+  controlled,
+  default: defaultProp,
+  name,
+  state = 'value',
+}: UseControlledProps<T>): [T, (newValue: T | ((prevValue: T) => T)) => void] {
+  // 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)) {
+        error(
+          [
+            `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(() => {
+      if (
+        !isControlled &&
+        serializeToDevModeString(defaultValue) !== serializeToDevModeString(defaultProp)
+      ) {
+        error(
+          [
+            `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'),
+        );
+      }
+    }, [defaultProp]);
+  }
+
+  const setValueIfUncontrolled = React.useCallback((newValue: React.SetStateAction<T>) => {
+    if (!isControlled) {
+      setValue(newValue as T);
+    }
+  }, []);
+
+  return [value as T, setValueIfUncontrolled];
+}
+
+function serializeToDevModeString(input: unknown) {
+  let nextId = 0;
+  const seen = new WeakMap<object, number>();
+
+  try {
+    const result = JSON.stringify(input, function replacer(key, value) {
+      if (key === '_owner' && this != null && typeof this === 'object' && '$$typeof' in this) {
+        return undefined;
+      }
+
+      if (typeof value === 'bigint') {
+        return `__bigint__:${value}`;
+      }
+
+      if (value !== null && typeof value === 'object') {
+        const id = seen.get(value);
+        if (id !== undefined) {
+          return `__object__:${id}`;
+        }
+
+        seen.set(value, nextId);
+        nextId += 1;
+      }
+
+      return value;
+    });
+
+    return result ?? `__top__:${typeof input}`;
+  } catch {
+    return '__unserializable__';
+  }
+}

package/src/hooks/useForcedRerendering.ts

@@ -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/src/hooks/useId.ts

@@ -0,0 +1,12 @@
+'use client';
+import * as React from 'react';
+
+/**
+ * Returns a stable unique id, optionally overridden or prefixed.
+ *
+ * @example <View nativeID={useId()} />
+ */
+export function useId(idOverride?: string, prefix?: string): string | undefined {
+  const reactId = React.useId();
+  return idOverride ?? (prefix ? `${prefix}-${reactId}` : reactId);
+}

package/src/hooks/useInterval.ts

@@ -0,0 +1,42 @@
+'use client';
+import { useRefWithInit } from './useRefWithInit';
+import { useOnMount } from './useOnMount';
+import { Timeout } from './useTimeout';
+
+type IntervalId = number;
+
+const EMPTY = 0 as IntervalId;
+
+export class Interval extends Timeout {
+  static override create() {
+    return new Interval();
+  }
+
+  /**
+   * Executes `fn` at `delay` interval, clearing any previously scheduled call.
+   */
+  override start(delay: number, fn: Function) {
+    this.clear();
+    this.currentId = setInterval(() => {
+      fn();
+    }, delay) as unknown as number;
+  }
+
+  override clear = () => {
+    if (this.currentId !== EMPTY) {
+      clearInterval(this.currentId as IntervalId);
+      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/src/hooks/useIsoLayoutEffect.ts

@@ -0,0 +1,13 @@
+'use client';
+import * as React from 'react';
+
+const noop = () => {};
+
+/*
+ * `window` is defined in every client React Native runtime: InitializeCore
+ * aliases it to `global` on native, react-native's jest setup does the same,
+ * and it's native on react-native-web. It is only missing during
+ * react-native-web server rendering, which is exactly when layout effects
+ * must not run.
+ */
+export const useIsoLayoutEffect = typeof window !== 'undefined' ? React.useLayoutEffect : noop;

package/src/hooks/useMergedRefs.ts

@@ -0,0 +1,153 @@
+import * as React from 'react';
+import { useRefWithInit } from './useRefWithInit';
+
+type Empty = null | undefined;
+type InputRef<I> = React.Ref<I> | Empty;
+type Result<I> = React.RefCallback<I> | null;
+type Cleanup = () => void;
+
+type ForkRef<I> = {
+  callback: React.RefCallback<I> | null;
+  cleanup: Cleanup | null;
+  refs: InputRef<I>[];
+};
+
+/**
+ * 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 function useMergedRefs<I>(a: InputRef<I>, b: InputRef<I>): Result<I>;
+export function useMergedRefs<I>(a: InputRef<I>, b: InputRef<I>, c: InputRef<I>): Result<I>;
+export function useMergedRefs<I>(
+  a: InputRef<I>,
+  b: InputRef<I>,
+  c: InputRef<I>,
+  d: InputRef<I>,
+): Result<I>;
+export function useMergedRefs<I>(
+  a: InputRef<I>,
+  b: InputRef<I>,
+  c?: InputRef<I>,
+  d?: InputRef<I>,
+): Result<I> {
+  const forkRef = useRefWithInit(createForkRef<I>).current;
+  if (didChange(forkRef, a, b, c, d)) {
+    update(forkRef, [a, b, c, d]);
+  }
+  return forkRef.callback;
+}
+
+/**
+ * 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 function useMergedRefsN<I>(refs: InputRef<I>[]): Result<I> {
+  const forkRef = useRefWithInit(createForkRef<I>).current;
+  if (didChangeN(forkRef, refs)) {
+    update(forkRef, refs);
+  }
+  return forkRef.callback;
+}
+
+function createForkRef<I>(): ForkRef<I> {
+  return {
+    callback: null,
+    cleanup: null as Cleanup | null,
+    refs: [],
+  };
+}
+
+function didChange<I>(
+  forkRef: ForkRef<I>,
+  a: InputRef<I>,
+  b: InputRef<I>,
+  c: InputRef<I>,
+  d: InputRef<I>,
+) {
+  // prettier-ignore
+  return (
+    forkRef.refs[0] !== a ||
+    forkRef.refs[1] !== b ||
+    forkRef.refs[2] !== c ||
+    forkRef.refs[3] !== d
+  )
+}
+
+function didChangeN<I>(forkRef: ForkRef<I>, newRefs: InputRef<I>[]) {
+  return (
+    forkRef.refs.length !== newRefs.length ||
+    forkRef.refs.some((ref, index) => ref !== newRefs[index])
+  );
+}
+
+function update<I>(forkRef: ForkRef<I>, refs: InputRef<I>[]) {
+  forkRef.refs = refs;
+
+  if (refs.every((ref) => ref == null)) {
+    forkRef.callback = null;
+    return;
+  }
+
+  forkRef.callback = (instance: I) => {
+    if (forkRef.cleanup) {
+      forkRef.cleanup();
+      forkRef.cleanup = null;
+    }
+
+    if (instance != null) {
+      const cleanupCallbacks = Array(refs.length).fill(null) as Array<Cleanup | null>;
+
+      for (let i = 0; i < refs.length; i += 1) {
+        const ref = refs[i];
+        if (ref == null) {
+          continue;
+        }
+        switch (typeof ref) {
+          case 'function': {
+            const refCleanup = ref(instance);
+            if (typeof refCleanup === 'function') {
+              cleanupCallbacks[i] = refCleanup;
+            }
+            break;
+          }
+          case 'object': {
+            ref.current = instance;
+            break;
+          }
+          default:
+        }
+      }
+
+      forkRef.cleanup = () => {
+        for (let i = 0; i < refs.length; i += 1) {
+          const ref = refs[i];
+          if (ref == null) {
+            continue;
+          }
+          switch (typeof ref) {
+            case 'function': {
+              const cleanupCallback = cleanupCallbacks[i];
+              if (typeof cleanupCallback === 'function') {
+                cleanupCallback();
+              } else {
+                // Legacy ref with no attach-time cleanup: detach by calling it with `null`.
+                // It returns nothing; React 19 cleanups are handled in the branch above.
+                void ref(null);
+              }
+              break;
+            }
+            case 'object': {
+              ref.current = null;
+              break;
+            }
+            default:
+          }
+        }
+      };
+    }
+  };
+}

package/src/hooks/useOnFirstRender.ts

@@ -0,0 +1,10 @@
+'use client';
+import * as React from 'react';
+
+export function useOnFirstRender(fn: Function) {
+  const ref = React.useRef(true);
+  if (ref.current) {
+    ref.current = false;
+    fn();
+  }
+}

package/src/hooks/useOnMount.ts

@@ -0,0 +1,11 @@
+'use client';
+import * as React from 'react';
+import { EMPTY_ARRAY } from '../utils/empty';
+
+/**
+ * A React.useEffect equivalent that runs once, when the component is mounted.
+ */
+export function useOnMount(fn: React.EffectCallback) {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  React.useEffect(fn, EMPTY_ARRAY);
+}

package/src/hooks/usePreviousValue.ts

@@ -0,0 +1,20 @@
+'use client';
+import * as React from 'react';
+
+/**
+ * Returns a previous value of its argument.
+ * @param value Current value.
+ * @returns Previous value, or null if there is no previous value.
+ */
+export function usePreviousValue<T>(value: T): T | null {
+  const [state, setState] = React.useState<{ current: T; previous: T | null }>({
+    current: value,
+    previous: null,
+  });
+
+  if (value !== state.current) {
+    setState({ current: value, previous: state.current });
+  }
+
+  return state.previous;
+}

package/src/hooks/useRefWithInit.ts

@@ -0,0 +1,23 @@
+'use client';
+import * as React from 'react';
+
+const UNINITIALIZED = {};
+
+/**
+ * A React.useRef() that is initialized with a function. Note that it accepts an optional
+ * initialization argument, so the initialization function doesn't need to be an inline closure.
+ *
+ * @usage
+ *   const ref = useRefWithInit(sortColumns, columns)
+ */
+export function useRefWithInit<T>(init: () => T): React.RefObject<T>;
+export function useRefWithInit<T, U>(init: (arg: U) => T, initArg: U): React.RefObject<T>;
+export function useRefWithInit(init: (arg?: unknown) => unknown, initArg?: unknown) {
+  const ref = React.useRef(UNINITIALIZED as any);
+
+  if (ref.current === UNINITIALIZED) {
+    ref.current = init(initArg);
+  }
+
+  return ref;
+}