@cdx-ui/utils 0.0.1-beta.9 → 0.0.1-beta.90

package/lib/typescript/form-control/useFormControl.d.ts

@@ -1,6 +1,17 @@
 import React from 'react';
-import { type TextInput } from 'react-native';
 type HTMLProps = Record<string, unknown>;
+/**
+ * Minimal contract for any control registered on `FormControlContextValue.inputRef`.
+ *
+ * `Field.Label` / `focusInput()` only need to call `.focus()` on the registered node;
+ * narrower control-specific shapes (`TextInput`, `HTMLInputElement`, custom focus
+ * bridges like `Select.Trigger`'s) all satisfy this contract. Consumers that need
+ * more (e.g. reading `.value`) should cast locally — keeping the context type
+ * minimal avoids a typed lie when a non-input bridge is registered.
+ */
+export interface Focusable {
+    focus(): void;
+}
 export interface FormControlState {
     isRequired: boolean;
     isInvalid: boolean;
@@ -21,9 +32,16 @@ export interface FormControlContextValue extends FormControlState {
     /**
      * @platform native — set by `Input.Field` / `Select.Trigger` for label press-to-focus.
      * On web, use `<label htmlFor>` with a labelable control (`input`, `button`, `select`, …).
+     *
+     * Typed as `Focusable` so any control (TextInput, HTMLInputElement, custom focus
+     * bridge) can register without a cast at the assignment site. Consumers that need
+     * the narrower shape cast locally.
      */
-    inputRef?: React.RefObject<TextInput | null>;
+    inputRef?: React.RefObject<Focusable | null>;
     focusInput?: () => void;
+    /** True when the primary child control is focused or (for Select) open — drives `Field.Label` styling. */
+    isLabelFocused?: boolean;
+    setIsLabelFocused?: React.Dispatch<React.SetStateAction<boolean>>;
 }
 export declare const FormControlContext: React.Context<Partial<FormControlContextValue>>;
 export interface FormControlFieldProps extends Partial<FormControlState> {
@@ -49,14 +67,21 @@ export interface FormControlRootReturn {
     feedbackId: string;
     helpTextId: string;
     htmlProps: HTMLProps;
-    inputRef?: React.RefObject<TextInput | null>;
+    inputRef?: React.RefObject<Focusable | null>;
     focusInput?: () => void;
+    isLabelFocused: boolean;
+    setIsLabelFocused: React.Dispatch<React.SetStateAction<boolean>>;
 }
 /**
  * Builds state and ids for a `Form` primitive root (`createFormRoot`). Pass the returned object
  * (minus `htmlProps`) to `FormControlContext.Provider` — this is not a React context consumer hook.
  */
 export declare function useFormControlRoot(props: FormControlRootProps): FormControlRootReturn;
+/**
+ * Reports focus/active state from `Input` / `Select.Trigger` to the parent `Field` for label styling.
+ * No-ops outside a `Field` (no `setIsLabelFocused` on context).
+ */
+export declare function useReportFormControlLabelFocus(isActive: boolean): void;
 /**
  * Hook that merges local field props with the nearest form field context
  * and returns normalised HTML / ARIA attributes for input elements.

package/lib/typescript/form-control/useFormControl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFormControl.d.ts","sourceRoot":"","sources":["../../../src/form-control/useFormControl.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAGxD,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzC,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,kBAAkB,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,cAAc,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,eAAO,MAAM,kBAAkB,iDAA4D,CAAC;AAE5F,MAAM,WAAW,qBAAsB,SAAQ,OAAO,CAAC,gBAAgB,CAAC;IACtE,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,4FAA4F;AAC5F,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,GAAG;IAC7D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,SAAS,CAAC;AAEd,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CAkDrF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,qBAAqB;;;;;;;;;;;EA4B1D;AAED,eAAO,MAAM,qBAAqB,wCAEjC,CAAC"}
+{"version":3,"file":"useFormControl.d.ts","sourceRoot":"","sources":["../../../src/form-control/useFormControl.tsx"],"names":[],"mappings":"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"}

package/lib/typescript/style/index.d.ts

@@ -1,3 +1,2 @@
 export * from './context';
-export * from './withStyleContext';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/style/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/style/index.tsx"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/style/index.tsx"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdx-ui/utils",
-  "version": "0.0.1-beta.9",
+  "version": "0.0.1-beta.90",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "react-native": "src/index.ts",
@@ -22,6 +22,7 @@
   "react-native-builder-bob": {
     "source": "src",
     "output": "lib",
+    "exclude": "**/{__tests__/**,__fixtures__/**,__mocks__/**,*.test.ts,*.test.tsx,*.spec.ts,*.spec.tsx}",
     "targets": [
       "commonjs",
       "module",
@@ -67,6 +68,7 @@
   },
   "scripts": {
     "build": "bob build",
-    "lint": "eslint src/"
+    "lint": "eslint src/",
+    "test": "jest --config ../../jest.config.js --selectProjects utils"
   }
 }

package/src/common/accessibilityUtils.test.ts

@@ -0,0 +1,12 @@
+import { ariaAttr } from './accessibilityUtils';
+
+describe('ariaAttr', () => {
+  it('returns true when condition is true', () => {
+    expect(ariaAttr(true)).toBe(true);
+  });
+
+  it('returns undefined when condition is false or undefined', () => {
+    expect(ariaAttr(false)).toBeUndefined();
+    expect(ariaAttr(undefined)).toBeUndefined();
+  });
+});

package/src/common/cn.test.ts

@@ -0,0 +1,19 @@
+import { cn } from './cn';
+
+describe('cn', () => {
+  it('merges conflicting Tailwind classes', () => {
+    expect(cn('px-2', 'px-4')).toBe('px-4');
+  });
+
+  it('joins non-conflicting classes', () => {
+    expect(cn('px-2', 'py-1')).toBe('px-2 py-1');
+  });
+
+  it('ignores falsy inputs', () => {
+    expect(cn('foo', undefined, null, false, '')).toBe('foo');
+  });
+
+  it('returns empty string when called with no inputs', () => {
+    expect(cn()).toBe('');
+  });
+});

package/src/common/composeEventHandlers.test.ts

@@ -0,0 +1,35 @@
+import { composeEventHandlers } from './composeEventHandlers';
+
+describe('composeEventHandlers', () => {
+  it('calls handlers in order', () => {
+    const order: number[] = [];
+    const first = jest.fn(() => {
+      order.push(1);
+    });
+    const second = jest.fn(() => {
+      order.push(2);
+    });
+
+    composeEventHandlers(first, second)({ type: 'press' });
+
+    expect(order).toEqual([1, 2]);
+    expect(first).toHaveBeenCalledWith({ type: 'press' });
+    expect(second).toHaveBeenCalledWith({ type: 'press' });
+  });
+
+  it('skips null and undefined handlers', () => {
+    const handler = jest.fn();
+
+    composeEventHandlers(null, undefined, handler)({});
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns a no-op when no handlers are provided', () => {
+    const handleEvent = composeEventHandlers();
+
+    expect(() => {
+      handleEvent({});
+    }).not.toThrow();
+  });
+});

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/context/createContext.tsx

@@ -5,8 +5,25 @@ import {
   useContext,
 } from 'react';
 
-export function createContext<T>(displayName: string) {
-  const Context = createReactContext<T | undefined>(undefined);
+interface CreateContextOptions<T> {
+  /**
+   * Value returned by the consumer hook when no matching provider is mounted.
+   * Only meaningful when `strict` is `false`; when omitted the hook returns `undefined`.
+   */
+  defaultValue?: T;
+  /**
+   * When `true` (default) the consumer hook throws if used outside its provider.
+   * Set to `false` to allow the hook to run without a provider, returning
+   * `defaultValue` (or `undefined`) instead of throwing.
+   * @default true
+   */
+  strict?: boolean;
+}
+
+export function createContext<T>(displayName: string, options?: CreateContextOptions<T>) {
+  const { defaultValue, strict = true } = options ?? {};
+
+  const Context = createReactContext<T | undefined>(defaultValue);
 
   const Provider: ComponentType<{ children: ReactNode; value: T }> = (props) => {
     const { children, value } = props;
@@ -17,10 +34,10 @@ export function createContext<T>(displayName: string) {
 
   function useC(): T {
     const context = useContext(Context);
-    if (context === undefined) {
+    if (context === undefined && strict) {
       throw new Error(`use${displayName} must be used within a ${displayName}Provider`);
     }
-    return context;
+    return context as T;
   }
 
   return [Provider, useC] as const;

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';