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

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();
+  });
+});

package/src/form-control/useFormControl.tsx

@@ -1,9 +1,22 @@
 import React from 'react';
-import { Platform, type TextInput } from 'react-native';
+import { Platform } from 'react-native';
 import { ariaAttr } from '../common/accessibilityUtils';
 
 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;
@@ -25,9 +38,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 const FormControlContext = React.createContext<Partial<FormControlContextValue>>({});
@@ -57,8 +77,10 @@ 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>>;
 }
 
 /**
@@ -87,7 +109,9 @@ export function useFormControlRoot(props: FormControlRootProps): FormControlRoot
    */
   const [hasHelpText, setHasHelpText] = React.useState(false);
 
-  const inputRef = React.useRef<TextInput | null>(null);
+  const [isLabelFocused, setIsLabelFocused] = React.useState(false);
+
+  const inputRef = React.useRef<Focusable | null>(null);
 
   const focusInput = React.useCallback(() => {
     const node = inputRef.current;
@@ -111,12 +135,32 @@ export function useFormControlRoot(props: FormControlRootProps): FormControlRoot
     feedbackId,
     helpTextId,
     htmlProps,
+    isLabelFocused,
+    setIsLabelFocused,
     ...(Platform.OS !== 'web' ? { inputRef, focusInput } : {}),
   };
 
   return context;
 }
 
+/**
+ * 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 function useReportFormControlLabelFocus(isActive: boolean) {
+  const { setIsLabelFocused } = useFormControlContext();
+
+  React.useLayoutEffect(() => {
+    if (typeof setIsLabelFocused !== 'function') {
+      return undefined;
+    }
+    setIsLabelFocused(isActive);
+    return () => {
+      setIsLabelFocused(false);
+    };
+  }, [isActive, setIsLabelFocused]);
+}
+
 /**
  * Hook that merges local field props with the nearest form field context
  * and returns normalised HTML / ARIA attributes for input elements.

package/src/style/context/index.test.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+import { renderHook } from '@testing-library/react-native';
+import { ParentContext, useParentContext, useStyleContext } from './index';
+
+describe('style context hooks', () => {
+  it('reads parent context values', () => {
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <ParentContext.Provider value={{ Button: { size: 'lg' }, Card: { padded: true } }}>
+        {children}
+      </ParentContext.Provider>
+    );
+
+    const { result: parentResult } = renderHook(() => useParentContext(), { wrapper });
+    const { result: styleResult } = renderHook(() => useStyleContext('Button'), { wrapper });
+
+    expect(parentResult.current).toEqual({ Button: { size: 'lg' }, Card: { padded: true } });
+    expect(styleResult.current).toEqual({ size: 'lg' });
+  });
+
+  it('defaults to Global scope', () => {
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <ParentContext.Provider value={{ Global: { theme: 'dark' } }}>
+        {children}
+      </ParentContext.Provider>
+    );
+
+    const { result } = renderHook(() => useStyleContext(), { wrapper });
+
+    expect(result.current).toEqual({ theme: 'dark' });
+  });
+});

package/src/style/index.tsx

@@ -1,2 +1 @@
 export * from './context';
-export * from './withStyleContext';

package/lib/commonjs/style/withStyleContext/index.js

@@ -1,33 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.withStyleContext = void 0;
-var _react = require("react");
-var _context = require("../context");
-var _jsxRuntime = require("react/jsx-runtime");
-const withStyleContext = (Component, scope = 'Global') => {
-  const Wrapped = /*#__PURE__*/(0, _react.forwardRef)(({
-    context,
-    ...props
-  }, ref) => {
-    const parentContextValues = (0, _context.useParentContext)();
-    const contextValues = (0, _react.useMemo)(() => {
-      return {
-        ...parentContextValues,
-        [scope]: context
-      };
-    }, [parentContextValues, context]);
-    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_context.ParentContext.Provider, {
-      value: contextValues,
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(Component, {
-        ...props,
-        ref: ref
-      })
-    });
-  });
-  return Wrapped;
-};
-exports.withStyleContext = withStyleContext;
-//# sourceMappingURL=index.js.map

package/lib/commonjs/style/withStyleContext/index.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["_react","require","_context","_jsxRuntime","withStyleContext","Component","scope","Wrapped","forwardRef","context","props","ref","parentContextValues","useParentContext","contextValues","useMemo","jsx","ParentContext","Provider","value","children","exports"],"sourceRoot":"../../../../src","sources":["style/withStyleContext/index.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AASA,IAAAC,QAAA,GAAAD,OAAA;AAAmF,IAAAE,WAAA,GAAAF,OAAA;AAM5E,MAAMG,gBAAgB,GAAGA,CAAwBC,SAAY,EAAEC,KAAK,GAAG,QAAQ,KAAK;EAIzF,MAAMC,OAAO,gBAAG,IAAAC,iBAAU,EAAa,CAAC;IAAEC,OAAO;IAAE,GAAGC;EAAM,CAAC,EAAEC,GAAG,KAAK;IACrE,MAAMC,mBAAmB,GAAG,IAAAC,yBAAgB,EAAC,CAAC;IAE9C,MAAMC,aAA8B,GAAG,IAAAC,cAAO,EAAC,MAAM;MACnD,OAAO;QAAE,GAAGH,mBAAmB;QAAE,CAACN,KAAK,GAAGG;MAAQ,CAAC;IACrD,CAAC,EAAE,CAACG,mBAAmB,EAAEH,OAAO,CAAC,CAAC;IAElC,oBACE,IAAAN,WAAA,CAAAa,GAAA,EAACd,QAAA,CAAAe,aAAa,CAACC,QAAQ;MAACC,KAAK,EAAEL,aAAc;MAAAM,QAAA,eAE3C,IAAAjB,WAAA,CAAAa,GAAA,EAACX,SAAS;QAAA,GAAKK,KAAK;QAAEC,GAAG,EAAEA;MAAI,CAAE;IAAC,CACZ,CAAC;EAE7B,CAAC,CAAC;EAEF,OAAOJ,OAAO;AAChB,CAAC;AAACc,OAAA,CAAAjB,gBAAA,GAAAA,gBAAA","ignoreList":[]}

package/lib/module/style/withStyleContext/index.js

@@ -1,28 +0,0 @@
-"use strict";
-
-import { forwardRef, useMemo } from 'react';
-import { ParentContext, useParentContext } from '../context';
-import { jsx as _jsx } from "react/jsx-runtime";
-export const withStyleContext = (Component, scope = 'Global') => {
-  const Wrapped = /*#__PURE__*/forwardRef(({
-    context,
-    ...props
-  }, ref) => {
-    const parentContextValues = useParentContext();
-    const contextValues = useMemo(() => {
-      return {
-        ...parentContextValues,
-        [scope]: context
-      };
-    }, [parentContextValues, context]);
-    return /*#__PURE__*/_jsx(ParentContext.Provider, {
-      value: contextValues,
-      children: /*#__PURE__*/_jsx(Component, {
-        ...props,
-        ref: ref
-      })
-    });
-  });
-  return Wrapped;
-};
-//# sourceMappingURL=index.js.map

package/lib/module/style/withStyleContext/index.js.map

@@ -1 +0,0 @@
-{"version":3,"names":["forwardRef","useMemo","ParentContext","useParentContext","jsx","_jsx","withStyleContext","Component","scope","Wrapped","context","props","ref","parentContextValues","contextValues","Provider","value","children"],"sourceRoot":"../../../../src","sources":["style/withStyleContext/index.tsx"],"mappings":";;AAAA,SAMEA,UAAU,EACVC,OAAO,QACF,OAAO;AACd,SAASC,aAAa,EAAwBC,gBAAgB,QAAQ,YAAY;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAMnF,OAAO,MAAMC,gBAAgB,GAAGA,CAAwBC,SAAY,EAAEC,KAAK,GAAG,QAAQ,KAAK;EAIzF,MAAMC,OAAO,gBAAGT,UAAU,CAAa,CAAC;IAAEU,OAAO;IAAE,GAAGC;EAAM,CAAC,EAAEC,GAAG,KAAK;IACrE,MAAMC,mBAAmB,GAAGV,gBAAgB,CAAC,CAAC;IAE9C,MAAMW,aAA8B,GAAGb,OAAO,CAAC,MAAM;MACnD,OAAO;QAAE,GAAGY,mBAAmB;QAAE,CAACL,KAAK,GAAGE;MAAQ,CAAC;IACrD,CAAC,EAAE,CAACG,mBAAmB,EAAEH,OAAO,CAAC,CAAC;IAElC,oBACEL,IAAA,CAACH,aAAa,CAACa,QAAQ;MAACC,KAAK,EAAEF,aAAc;MAAAG,QAAA,eAE3CZ,IAAA,CAACE,SAAS;QAAA,GAAKI,KAAK;QAAEC,GAAG,EAAEA;MAAI,CAAE;IAAC,CACZ,CAAC;EAE7B,CAAC,CAAC;EAEF,OAAOH,OAAO;AAChB,CAAC","ignoreList":[]}

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

@@ -1,6 +0,0 @@
-import { type ComponentPropsWithoutRef, type ComponentRef, type ElementType, type ForwardRefExoticComponent, type RefAttributes } from 'react';
-export interface WithStyleContextProps {
-    context?: Record<string, unknown>;
-}
-export declare const withStyleContext: <T extends ElementType>(Component: T, scope?: string) => ForwardRefExoticComponent<(ComponentPropsWithoutRef<T> & WithStyleContextProps) & RefAttributes<ComponentRef<T>>>;
-//# sourceMappingURL=index.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/style/withStyleContext/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EAGnB,MAAM,OAAO,CAAC;AAGf,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,WAAW,EAAE,WAAW,CAAC,EAAE,cAAgB,KAmBlE,yBAAyB,CAAC,wDAAQ,aAAa,iBAAK,CACvE,CAAC"}

package/src/style/withStyleContext/index.tsx

@@ -1,36 +0,0 @@
-import {
-  type ComponentPropsWithoutRef,
-  type ComponentRef,
-  type ElementType,
-  type ForwardRefExoticComponent,
-  type RefAttributes,
-  forwardRef,
-  useMemo,
-} from 'react';
-import { ParentContext, type StyleContextMap, useParentContext } from '../context';
-
-export interface WithStyleContextProps {
-  context?: Record<string, unknown>;
-}
-
-export const withStyleContext = <T extends ElementType>(Component: T, scope = 'Global') => {
-  type Ref = ComponentRef<T>;
-  type Props = ComponentPropsWithoutRef<T> & WithStyleContextProps;
-
-  const Wrapped = forwardRef<Ref, Props>(({ context, ...props }, ref) => {
-    const parentContextValues = useParentContext();
-
-    const contextValues: StyleContextMap = useMemo(() => {
-      return { ...parentContextValues, [scope]: context };
-    }, [parentContextValues, context]);
-
-    return (
-      <ParentContext.Provider value={contextValues}>
-        {/* @ts-expect-error -- generic component spread is not fully inferrable */}
-        <Component {...props} ref={ref} />
-      </ParentContext.Provider>
-    );
-  });
-
-  return Wrapped as ForwardRefExoticComponent<Props & RefAttributes<Ref>>;
-};