@cdx-ui/utils 0.0.1-beta.7 → 0.0.1-beta.70

package/src/common/getSpacedChild.test.tsx

@@ -0,0 +1,64 @@
+import React, { isValidElement } from 'react';
+import { Text } from 'react-native';
+import { flattenChildren } from './getSpacedChild';
+
+describe('flattenChildren', () => {
+  it('flattens fragment children', () => {
+    const result = flattenChildren(
+      <>
+        <Text key="a">A</Text>
+        <Text key="b">B</Text>
+      </>,
+    );
+
+    expect(result).toHaveLength(2);
+    expect(isValidElement(result[0]) && result[0].type).toBe(Text);
+    expect(isValidElement(result[1]) && result[1].type).toBe(Text);
+  });
+
+  it('assigns composite keys to nested fragment children', () => {
+    const result = flattenChildren(
+      <React.Fragment key="group">
+        <Text key="child">Child</Text>
+      </React.Fragment>,
+    );
+
+    expect(result).toHaveLength(1);
+    const key = isValidElement(result[0]) ? String(result[0].key) : '';
+    expect(key).toContain('group');
+    expect(key).toContain('child');
+  });
+
+  it('passes through non-element children', () => {
+    const result = flattenChildren(['plain', <Text key="t">T</Text>]);
+
+    expect(result).toHaveLength(2);
+    expect(result[0]).toBe('plain');
+  });
+
+  it('preserves explicit element keys', () => {
+    const result = flattenChildren(<Text key="explicit">Label</Text>);
+
+    expect(result).toHaveLength(1);
+    const key = isValidElement(result[0]) ? String(result[0].key) : '';
+    expect(key).toContain('explicit');
+  });
+
+  it('uses index keys when fragment and child keys are missing', () => {
+    const result = flattenChildren(
+      <>
+        <Text>First</Text>
+        <React.Fragment>
+          <Text>Nested</Text>
+        </React.Fragment>
+      </>,
+    );
+
+    expect(result).toHaveLength(2);
+    const firstKey = isValidElement(result[0]) ? String(result[0].key) : '';
+    const secondKey = isValidElement(result[1]) ? String(result[1].key) : '';
+    expect(firstKey).toContain('0');
+    expect(secondKey).toContain('1');
+    expect(secondKey).toContain('0');
+  });
+});

package/src/common/mergeRefs.test.ts

@@ -0,0 +1,148 @@
+import { createRef } from 'react';
+import { mergeRefs } from './mergeRefs';
+
+describe('mergeRefs', () => {
+  it('assigns value to object refs', () => {
+    const refA = createRef<string>();
+    const refB = createRef<string>();
+
+    mergeRefs(refA, refB)('value');
+
+    expect(refA.current).toBe('value');
+    expect(refB.current).toBe('value');
+  });
+
+  it('invokes callback refs', () => {
+    const callback = jest.fn();
+
+    mergeRefs(callback)('value');
+
+    expect(callback).toHaveBeenCalledWith('value');
+  });
+
+  it('skips undefined refs and assigns null', () => {
+    const ref = createRef<string | null>();
+
+    mergeRefs(undefined, ref)(null);
+
+    expect(ref.current).toBeNull();
+  });
+
+  it('updates callback and object refs together', () => {
+    const callback = jest.fn();
+    const objectRef = createRef<string | null>();
+
+    mergeRefs(callback, objectRef)('shared');
+
+    expect(callback).toHaveBeenCalledWith('shared');
+    expect(objectRef.current).toBe('shared');
+  });
+
+  describe('React 19 ref-cleanup semantics', () => {
+    it('returns a cleanup function when called with a non-null value', () => {
+      const ref = createRef<string>();
+      const merged = mergeRefs(ref);
+
+      const cleanup = merged('value');
+
+      expect(typeof cleanup).toBe('function');
+    });
+
+    it('does not return a cleanup when called with null', () => {
+      const ref = createRef<string>();
+      const merged = mergeRefs(ref);
+
+      const result = merged(null);
+
+      expect(result).toBeUndefined();
+    });
+
+    it('cleanup nulls object refs', () => {
+      const refA = createRef<string>();
+      const refB = createRef<string>();
+      const merged = mergeRefs(refA, refB);
+
+      const cleanup = merged('value') as () => void;
+      expect(refA.current).toBe('value');
+      expect(refB.current).toBe('value');
+
+      cleanup();
+      expect(refA.current).toBeNull();
+      expect(refB.current).toBeNull();
+    });
+
+    it('cleanup calls callback refs with null when they did not return a cleanup', () => {
+      const callback = jest.fn();
+      const merged = mergeRefs(callback);
+
+      const cleanup = merged('value') as () => void;
+      expect(callback).toHaveBeenCalledWith('value');
+
+      callback.mockClear();
+      cleanup();
+      expect(callback).toHaveBeenCalledWith(null);
+    });
+
+    it('cleanup invokes the inner cleanup instead of calling ref(null) for refs that returned one', () => {
+      const innerCleanup = jest.fn();
+      const callbackWithCleanup = jest.fn().mockReturnValue(innerCleanup);
+      const merged = mergeRefs(callbackWithCleanup);
+
+      const cleanup = merged('element') as () => void;
+      expect(callbackWithCleanup).toHaveBeenCalledWith('element');
+
+      callbackWithCleanup.mockClear();
+      cleanup();
+      expect(innerCleanup).toHaveBeenCalledTimes(1);
+      expect(callbackWithCleanup).not.toHaveBeenCalled();
+    });
+
+    it('handles mixed refs: object, callback with cleanup, callback without cleanup', () => {
+      const objectRef = createRef<string>();
+      const innerCleanup = jest.fn();
+      const callbackWithCleanup = jest.fn().mockReturnValue(innerCleanup);
+      const callbackNoCleanup = jest.fn();
+
+      const merged = mergeRefs(objectRef, callbackWithCleanup, callbackNoCleanup);
+      const cleanup = merged('node') as () => void;
+
+      expect(objectRef.current).toBe('node');
+      expect(callbackWithCleanup).toHaveBeenCalledWith('node');
+      expect(callbackNoCleanup).toHaveBeenCalledWith('node');
+
+      callbackWithCleanup.mockClear();
+      callbackNoCleanup.mockClear();
+      cleanup();
+
+      expect(objectRef.current).toBeNull();
+      expect(innerCleanup).toHaveBeenCalledTimes(1);
+      expect(callbackWithCleanup).not.toHaveBeenCalled();
+      expect(callbackNoCleanup).toHaveBeenCalledWith(null);
+    });
+
+    it('null-call path still works for React 18 compat (calls all refs with null)', () => {
+      const objectRef = createRef<string>();
+      const callback = jest.fn();
+      const merged = mergeRefs(objectRef, callback);
+
+      merged('value');
+      callback.mockClear();
+
+      merged(null);
+
+      expect(objectRef.current).toBeNull();
+      expect(callback).toHaveBeenCalledWith(null);
+    });
+
+    it('skips undefined entries in cleanup', () => {
+      const objectRef = createRef<string>();
+      const merged = mergeRefs(undefined, objectRef, undefined);
+
+      const cleanup = merged('value') as () => void;
+      expect(objectRef.current).toBe('value');
+
+      cleanup();
+      expect(objectRef.current).toBeNull();
+    });
+  });
+});

package/src/common/mergeRefs.ts

@@ -1,13 +1,56 @@
 import type { Ref, RefCallback } from 'react';
 
+type CleanupFn = () => void;
+
+/**
+ * Merges multiple refs (object or callback) into a single callback ref.
+ *
+ * Supports React 19 ref-cleanup semantics: if an inner callback ref returns a
+ * cleanup function, that cleanup is captured and invoked when the merged ref is
+ * detached — either via the returned cleanup (React 19) or via a subsequent
+ * call with `null` (React 18 backward-compat path).
+ */
 export function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): RefCallback<T> {
-  return (value: T | null) => {
+  return (value: T | null): CleanupFn | undefined => {
+    if (value === null) {
+      for (const ref of refs) {
+        if (typeof ref === 'function') {
+          ref(null);
+        } else if (ref != null) {
+          ref.current = null;
+        }
+      }
+      return undefined;
+    }
+
+    const cleanups: (CleanupFn | undefined)[] = [];
     for (const ref of refs) {
       if (typeof ref === 'function') {
-        ref(value);
+        cleanups.push(ref(value) as CleanupFn | undefined);
       } else if (ref != null) {
         ref.current = value;
+        cleanups.push(undefined);
+      } else {
+        cleanups.push(undefined);
       }
     }
+
+    return () => {
+      for (let i = 0; i < refs.length; i++) {
+        const ref = refs[i];
+        if (ref == null) continue;
+
+        if (typeof ref === 'function') {
+          const refCleanup = cleanups[i];
+          if (typeof refCleanup === 'function') {
+            refCleanup();
+          } else {
+            ref(null);
+          }
+        } else {
+          ref.current = null;
+        }
+      }
+    };
   };
 }

package/src/common/useControllableState.test.tsx

@@ -0,0 +1,90 @@
+import { act, renderHook } from '@testing-library/react-native';
+import { useControllableState } from './useControllableState';
+
+describe('useControllableState', () => {
+  it('manages uncontrolled state from defaultProp', () => {
+    const onChange = jest.fn();
+    const { result } = renderHook(() => useControllableState({ defaultProp: 'initial', onChange }));
+
+    expect(result.current[0]).toBe('initial');
+
+    act(() => {
+      result.current[1]('next');
+    });
+
+    expect(result.current[0]).toBe('next');
+    expect(onChange).toHaveBeenCalledWith('next');
+  });
+
+  it('uses prop value in controlled mode and notifies onChange', () => {
+    const onChange = jest.fn();
+    const { result } = renderHook(() => useControllableState({ prop: 'controlled', onChange }));
+
+    expect(result.current[0]).toBe('controlled');
+
+    act(() => {
+      result.current[1]('updated');
+    });
+
+    expect(onChange).toHaveBeenCalledWith('updated');
+    expect(result.current[0]).toBe('controlled');
+  });
+
+  it('supports function updaters in uncontrolled mode', () => {
+    const { result } = renderHook(() => useControllableState({ defaultProp: 1 }));
+
+    act(() => {
+      result.current[1]((prev: number | undefined) => (prev ?? 0) + 1);
+    });
+
+    expect(result.current[0]).toBe(2);
+  });
+
+  it('follows prop updates in controlled mode', () => {
+    const { result, rerender } = renderHook(({ value }) => useControllableState({ prop: value }), {
+      initialProps: { value: 'a' },
+    });
+
+    rerender({ value: 'b' });
+
+    expect(result.current[0]).toBe('b');
+  });
+
+  it('supports function updaters in controlled mode', () => {
+    const onChange = jest.fn();
+    const { result } = renderHook(() => useControllableState({ prop: 2, onChange }));
+
+    act(() => {
+      result.current[1]((prev: number | undefined) => (prev ?? 0) + 3);
+    });
+
+    expect(onChange).toHaveBeenCalledWith(5);
+    expect(result.current[0]).toBe(2);
+  });
+
+  it('does not notify onChange when controlled value is unchanged', () => {
+    const onChange = jest.fn();
+    const { result } = renderHook(() => useControllableState({ prop: 'same', onChange }));
+
+    act(() => {
+      result.current[1]('same');
+    });
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('switches from uncontrolled to controlled when prop is provided', () => {
+    const { result, rerender } = renderHook(
+      (props: { prop?: string; defaultProp?: string }) => useControllableState(props),
+      { initialProps: { defaultProp: 'internal' } },
+    );
+
+    act(() => {
+      result.current[1]('internal');
+    });
+
+    rerender({ prop: 'external' });
+
+    expect(result.current[0]).toBe('external');
+  });
+});

package/src/context/createContext.test.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+import { renderHook } from '@testing-library/react-native';
+import { createContext } from './createContext';
+
+describe('createContext', () => {
+  it('provides value through Provider and consumer hook', () => {
+    const [Provider, useTestContext] = createContext<{ label: string }>('Test');
+
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <Provider value={{ label: 'hello' }}>{children}</Provider>
+    );
+
+    const { result } = renderHook(() => useTestContext(), { wrapper });
+
+    expect(result.current).toEqual({ label: 'hello' });
+  });
+
+  it('throws when consumer is used outside Provider', () => {
+    const [, useTestContext] = createContext<{ label: string }>('Test');
+
+    expect(() => {
+      renderHook(() => useTestContext());
+    }).toThrow('useTest must be used within a TestProvider');
+  });
+
+  it('names the Provider from the display name argument', () => {
+    const [Provider] = createContext<{ label: string }>('Field');
+
+    expect(Provider.displayName).toBe('FieldProvider');
+  });
+});

package/src/form-control/index.ts

@@ -1,4 +1,5 @@
 export {
+  type Focusable,
   type FormControlContextValue,
   type FormControlFieldProps,
   type FormControlRootProps,
@@ -8,4 +9,5 @@ export {
   useFormControl,
   useFormControlContext,
   useFormControlRoot,
+  useReportFormControlLabelFocus,
 } from './useFormControl';

package/src/form-control/useFormControl.test.tsx

@@ -0,0 +1,214 @@
+import type { ReactNode } from 'react';
+import { Platform, type TextInput } from 'react-native';
+import { act, renderHook } from '@testing-library/react-native';
+import {
+  FormControlContext,
+  useFormControl,
+  useFormControlContext,
+  useFormControlRoot,
+  useReportFormControlLabelFocus,
+} from './useFormControl';
+
+function FormControlTestProvider({
+  children,
+  rootProps,
+  hasFeedbackText = false,
+  hasHelpText = false,
+}: {
+  children: ReactNode;
+  rootProps?: Parameters<typeof useFormControlRoot>[0];
+  hasFeedbackText?: boolean;
+  hasHelpText?: boolean;
+}) {
+  const root = useFormControlRoot(rootProps ?? { id: 'email' });
+
+  return (
+    <FormControlContext.Provider value={{ ...root, hasFeedbackText, hasHelpText }}>
+      {children}
+    </FormControlContext.Provider>
+  );
+}
+
+describe('useFormControlRoot', () => {
+  it('uses provided id and coerces boolean state flags', () => {
+    const { result } = renderHook(() =>
+      useFormControlRoot({
+        id: 'custom-id',
+        isRequired: true,
+        isInvalid: true,
+        isDisabled: false,
+        isReadOnly: false,
+        name: 'email',
+        'data-test': 'root',
+      }),
+    );
+
+    expect(result.current.id).toBe('custom-id');
+    expect(result.current.labelId).toBe('custom-id-label');
+    expect(result.current.isRequired).toBe(true);
+    expect(result.current.isInvalid).toBe(true);
+    expect(result.current.isDisabled).toBe(false);
+    expect(result.current.isReadOnly).toBe(false);
+    expect(result.current.name).toBe('email');
+    expect(result.current.htmlProps).toEqual({ 'data-test': 'root' });
+  });
+
+  it('generates an id when none is provided', () => {
+    const { result } = renderHook(() => useFormControlRoot({}));
+
+    expect(result.current.id).toMatch(/^field-/);
+    expect(result.current.feedbackId).toBe(`${result.current.id}-feedback`);
+  });
+
+  it('ignores empty string id and generates a fallback', () => {
+    const { result } = renderHook(() => useFormControlRoot({ id: '' }));
+
+    expect(result.current.id).toMatch(/^field-/);
+    expect(result.current.id).not.toBe('');
+  });
+
+  it('exposes native focus helpers by default', () => {
+    const { result } = renderHook(() => useFormControlRoot({}));
+
+    expect(result.current.inputRef).toBeDefined();
+    expect(result.current.focusInput).toBeDefined();
+
+    const { inputRef, focusInput } = result.current;
+    if (!inputRef || !focusInput) {
+      throw new Error('expected native focus helpers');
+    }
+
+    const focus = jest.fn();
+    act(() => {
+      inputRef.current = { focus } as TextInput;
+      focusInput();
+    });
+
+    expect(focus).toHaveBeenCalled();
+  });
+
+  it('no-ops focusInput when ref is empty or focus is unavailable', () => {
+    const { result } = renderHook(() => useFormControlRoot({}));
+    const { focusInput, inputRef } = result.current;
+
+    if (!focusInput || !inputRef) {
+      throw new Error('expected native focus helpers');
+    }
+
+    expect(() => {
+      focusInput();
+    }).not.toThrow();
+
+    act(() => {
+      inputRef.current = {} as TextInput;
+      focusInput();
+    });
+
+    expect(inputRef.current).toEqual({});
+  });
+
+  it('omits native focus helpers on web', () => {
+    const originalDescriptor = Object.getOwnPropertyDescriptor(Platform, 'OS');
+    Object.defineProperty(Platform, 'OS', { configurable: true, get: () => 'web' });
+
+    const { result } = renderHook(() => useFormControlRoot({}));
+
+    expect(result.current.inputRef).toBeUndefined();
+    expect(result.current.focusInput).toBeUndefined();
+
+    if (originalDescriptor) {
+      Object.defineProperty(Platform, 'OS', originalDescriptor);
+    }
+  });
+});
+
+describe('useFormControl', () => {
+  it('merges local props with context and composes aria-describedby', () => {
+    const { result } = renderHook(() => useFormControl({ id: 'override', isDisabled: true }), {
+      wrapper: ({ children }) => (
+        <FormControlTestProvider
+          rootProps={{
+            id: 'email',
+            name: 'email',
+            isRequired: true,
+            isInvalid: true,
+            isDisabled: false,
+            isReadOnly: false,
+          }}
+          hasFeedbackText
+          hasHelpText
+        >
+          {children}
+        </FormControlTestProvider>
+      ),
+    });
+
+    expect(result.current.id).toBe('override');
+    expect(result.current.name).toBe('email');
+    expect(result.current.disabled).toBe(true);
+    expect(result.current.required).toBe(true);
+    expect(result.current['aria-invalid']).toBe(true);
+    expect(result.current['aria-labelledby']).toBe('email-label');
+    expect(result.current['aria-describedby']).toBe('email-feedback email-helptext');
+  });
+
+  it('returns undefined aria-describedby when no help or feedback is present', () => {
+    const { result } = renderHook(() => useFormControl({}), {
+      wrapper: ({ children }) => <FormControlTestProvider>{children}</FormControlTestProvider>,
+    });
+
+    expect(result.current['aria-describedby']).toBeUndefined();
+    expect(result.current.id).toBe('email-input');
+  });
+
+  it('composes aria-describedby from feedback or help text alone', () => {
+    const feedbackOnly = renderHook(() => useFormControl({}), {
+      wrapper: ({ children }) => (
+        <FormControlTestProvider hasFeedbackText>{children}</FormControlTestProvider>
+      ),
+    }).result.current['aria-describedby'];
+
+    const helpOnly = renderHook(() => useFormControl({}), {
+      wrapper: ({ children }) => (
+        <FormControlTestProvider hasHelpText>{children}</FormControlTestProvider>
+      ),
+    }).result.current['aria-describedby'];
+
+    expect(feedbackOnly).toBe('email-feedback');
+    expect(helpOnly).toBe('email-helptext');
+  });
+
+  it('merges readOnly from local props and omits id without field context', () => {
+    const { result } = renderHook(() => useFormControl({ isReadOnly: true }));
+
+    expect(result.current.readOnly).toBe(true);
+    expect(result.current.id).toBeUndefined();
+  });
+});
+
+describe('useReportFormControlLabelFocus', () => {
+  it('reports active state to the form control context', () => {
+    const { result, rerender } = renderHook(
+      ({ active }: { active: boolean }) => {
+        useReportFormControlLabelFocus(active);
+        return useFormControlContext().isLabelFocused;
+      },
+      {
+        wrapper: ({ children }) => <FormControlTestProvider>{children}</FormControlTestProvider>,
+        initialProps: { active: true },
+      },
+    );
+
+    expect(result.current).toBe(true);
+
+    rerender({ active: false });
+
+    expect(result.current).toBe(false);
+  });
+
+  it('no-ops when setIsLabelFocused is unavailable', () => {
+    expect(() => {
+      renderHook(() => useReportFormControlLabelFocus(true));
+    }).not.toThrow();
+  });
+});