@cdx-ui/utils 0.0.1-alpha.1

package/src/common/useControllableState.ts

@@ -0,0 +1,75 @@
+// This project uses code from WorkOS/Radix Primitives.
+// The code is licensed under the MIT License.
+// https://github.com/radix-ui/primitives/tree/main
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+export interface UseControllableStateParams<T> {
+  prop?: T | undefined;
+  defaultProp?: T | undefined;
+  onChange?: (state: T) => void;
+}
+
+type SetStateFn<T> = (prevState?: T) => T;
+
+function useControllableState<T>({
+  prop,
+  defaultProp,
+  onChange = () => {},
+}: UseControllableStateParams<T>) {
+  const [uncontrolledProp, setUncontrolledProp] = useUncontrolledState({ defaultProp, onChange });
+  const isControlled = prop !== undefined;
+  const value = isControlled ? prop : uncontrolledProp;
+  const handleChange = useCallbackRef(onChange);
+
+  const setValue: React.Dispatch<React.SetStateAction<T | undefined>> = useCallback(
+    (nextValue) => {
+      if (isControlled) {
+        const setter = nextValue as SetStateFn<T>;
+        const value = typeof nextValue === 'function' ? setter(prop) : nextValue;
+        if (value !== prop) handleChange(value as T);
+      } else {
+        setUncontrolledProp(nextValue);
+      }
+    },
+    [isControlled, prop, setUncontrolledProp, handleChange],
+  );
+
+  return [value, setValue] as const;
+}
+
+function useUncontrolledState<T>({
+  defaultProp,
+  onChange,
+}: Omit<UseControllableStateParams<T>, 'prop'>) {
+  const uncontrolledState = useState<T | undefined>(defaultProp);
+  const [value] = uncontrolledState;
+  const prevValueRef = useRef(value);
+  const handleChange = useCallbackRef(onChange);
+
+  useEffect(() => {
+    if (prevValueRef.current !== value) {
+      handleChange(value as T);
+      prevValueRef.current = value;
+    }
+  }, [value, prevValueRef, handleChange]);
+
+  return uncontrolledState;
+}
+
+/**
+ * A custom hook that converts a callback to a ref to avoid triggering re-renders when passed as a
+ * prop or avoid re-executing effects when passed as a dependency
+ */
+function useCallbackRef<T extends (...args: any[]) => any>(callback: T | undefined): T {
+  const callbackRef = useRef(callback);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  // https://github.com/facebook/react/issues/19240
+  return useMemo(() => ((...args) => callbackRef.current?.(...args)) as T, []);
+}
+
+export { useControllableState };

package/src/context/createContext.tsx

@@ -0,0 +1,27 @@
+import {
+  type ComponentType,
+  createContext as createReactContext,
+  type ReactNode,
+  useContext,
+} from 'react';
+
+export function createContext<T>(displayName: string) {
+  const Context = createReactContext<T | undefined>(undefined);
+
+  const Provider: ComponentType<{ children: ReactNode; value: T }> = (props) => {
+    const { children, value } = props;
+    return <Context.Provider value={value}>{children}</Context.Provider>;
+  };
+
+  Provider.displayName = `${displayName}Provider`;
+
+  function useC(): T {
+    const context = useContext(Context);
+    if (context === undefined) {
+      throw new Error(`use${displayName} must be used within a ${displayName}Provider`);
+    }
+    return context;
+  }
+
+  return [Provider, useC] as const;
+}

package/src/context/index.ts

@@ -0,0 +1 @@
+export { createContext } from './createContext';

package/src/form-control/index.ts

@@ -0,0 +1,8 @@
+export {
+  type FormControlContextValue,
+  type FormControlFieldProps,
+  type FormControlState,
+  FormControlContext,
+  useFormControl,
+  useFormControlContext,
+} from './useFormControl';

package/src/form-control/useFormControl.tsx

@@ -0,0 +1,63 @@
+import React from 'react';
+import { ariaAttr } from '../common/accessibilityUtils';
+
+type HTMLProps = Record<string, unknown>;
+
+export interface FormControlState {
+  isRequired: boolean;
+  isInvalid: boolean;
+  isDisabled: boolean;
+  isReadOnly: boolean;
+}
+
+export interface FormControlContextValue extends FormControlState {
+  hasFeedbackText: boolean;
+  hasHelpText: boolean;
+  id: string;
+  labelId: string;
+  feedbackId: string;
+  helpTextId: string;
+  htmlProps: HTMLProps;
+}
+
+export const FormControlContext = React.createContext<Partial<FormControlContextValue>>({});
+
+export interface FormControlFieldProps extends Partial<FormControlState> {
+  id?: string;
+}
+
+/**
+ * Hook that merges local field props with the nearest FormControl context
+ * and returns normalised HTML / ARIA attributes for input elements.
+ */
+export function useFormControl(props: FormControlFieldProps) {
+  const field = useFormControlContext();
+  const describedBy: string[] = [];
+
+  if (field?.hasFeedbackText && field.feedbackId) {
+    describedBy.push(field.feedbackId);
+  }
+  if (field?.hasHelpText && field.helpTextId) {
+    describedBy.push(field.helpTextId);
+  }
+  const ariaDescribedBy = describedBy.join(' ');
+
+  const { isInvalid, isDisabled, isReadOnly, isRequired, ...cleanProps } = props;
+  const id = props.id ?? (field?.id ? `${field.id}-input` : undefined);
+
+  return {
+    ...cleanProps,
+    id,
+    disabled: isDisabled || field?.isDisabled,
+    readOnly: isReadOnly || field?.isReadOnly,
+    required: isRequired || field?.isRequired,
+    'aria-invalid': ariaAttr(isInvalid || field?.isInvalid),
+    'aria-required': ariaAttr(isRequired || field?.isRequired),
+    'aria-readonly': ariaAttr(isReadOnly || field?.isReadOnly),
+    'aria-describedby': ariaDescribedBy || undefined,
+  };
+}
+
+export const useFormControlContext = () => {
+  return React.useContext(FormControlContext);
+};

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './common';
+export * from './context';
+export * from './form-control';
+export * from './style';

package/src/style/context/index.tsx

@@ -0,0 +1,14 @@
+import { createContext, useContext } from 'react';
+
+export type StyleContextMap = Record<string, unknown>;
+
+export const ParentContext = createContext<StyleContextMap>({});
+
+export const useParentContext = (): StyleContextMap => {
+  return useContext(ParentContext);
+};
+
+export const useStyleContext = (scope = 'Global') => {
+  const parentContextValues = useParentContext();
+  return parentContextValues[scope] as Record<string, unknown>;
+};

package/src/style/index.tsx

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

package/src/style/withStyleContext/index.tsx

@@ -0,0 +1,36 @@
+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>>;
+};