@yahoo/uds 3.58.2-beta.1 → 3.59.0-beta.1

package/src/components/client/Radio/Radio.tsx

@@ -0,0 +1,351 @@
+import type { RadioSize, RadioVariant, UniversalRadioProps } from '@yahoo/uds/tokens';
+import { m, useReducedMotion } from 'motion/react';
+import type { ChangeEvent, FocusEvent } from 'react';
+import React, { forwardRef, useCallback, useId, useMemo, useRef, useState } from 'react';
+
+import { cx, getStyles } from '../../../styles/styler';
+import { Box } from '../../Box';
+import { FormLabel } from '../../FormLabel';
+import { SpringMotionConfig } from '../SpringMotionConfig';
+import { useRadioGroup } from './useRadioGroup';
+
+type NativeInputProps = Omit<
+  React.InputHTMLAttributes<HTMLInputElement>,
+  'type' | 'checked' | 'value' | 'size' | 'height' | 'width' | 'color' | 'required'
+>;
+
+interface RadioProps extends NativeInputProps, UniversalRadioProps {
+  layerClassNames?: {
+    root?: string;
+    radio?: string;
+    label?: string;
+  };
+}
+
+const RADIO_VARIANTS: RadioVariant[] = ['primary', 'secondary'];
+const RADIO_SIZES: RadioSize[] = ['sm', 'md'];
+
+const VARIANT_ERROR_MAP: Record<RadioVariant, 'alert' | 'alert-secondary'> = {
+  primary: 'alert',
+  secondary: 'alert-secondary',
+};
+
+const MotionBox = m.create(Box);
+
+const hoverTransition = { layoutVariant: 'smooth', layoutSpeed: '3' } as const;
+const pressTransition = { layoutVariant: 'veryBouncy', layoutSpeed: '4' } as const;
+
+/**
+ * **⚙️️ A Radio.
+ *
+ * @componentType Client component
+ *
+ * @description
+ * A radio component allows users to select one or multiple options from a set. Unlike checkbox, radio buttons cannot have multiple selected in a form, allowing only 1 selection in a group. It represents a binary state, typically as selected or unselected.
+ *
+ * @see
+ * Check out the {@link https://uds.build/docs/components/radio Radio Docs} for more info
+ *
+ * @usage
+ * - Forms: Radio
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ * import { Radio } from "@yahoo/uds";
+ *
+ * <Radio label="Name" />
+ *```
+ *
+ * @related [Radio](https://uds.build/docs/components/Radio).
+ **/
+const Radio = forwardRef<HTMLInputElement, RadioProps>(function Radio(
+  {
+    id,
+    name: nameProp,
+    label,
+    labelPosition = 'start',
+    variant: variantProp = 'primary',
+    size = 'md',
+    reduceMotion: forceReduceMotion,
+    value: valueProp = '', // Matches HTML
+    checked: checkedProp,
+    defaultChecked,
+    disabled,
+    hasError,
+    onChange,
+    onFocus,
+    onBlur,
+    className,
+    layerClassNames,
+    ...radioProps
+  },
+  parentRef,
+) {
+  const generatedId = useId();
+  const uid = id ?? `uds-radio-${generatedId}`;
+
+  const innerRef = useRef<HTMLInputElement | null>(null);
+
+  /**
+   * State
+   */
+  const { name, isControlled, checked, setGroupValue } = useRadioGroup({
+    name: nameProp,
+    value: valueProp,
+    checked: checkedProp,
+    defaultChecked,
+  });
+
+  const [isHovered, setIsHovered] = useState(false);
+  const [isPressed, setIsPressed] = useState(false);
+
+  /**
+   * Derived values
+   */
+  const variant = useMemo(
+    () => (hasError ? VARIANT_ERROR_MAP[variantProp] : variantProp),
+    [hasError, variantProp],
+  );
+
+  const showHoverEffect = useMemo(() => !disabled && isHovered, [disabled, isHovered]);
+
+  const showPressedEffect = useMemo(
+    () => !disabled && !checked && isPressed,
+    [checked, disabled, isPressed],
+  );
+
+  const scale = useMemo(
+    () => (showPressedEffect ? 0.9 : showHoverEffect ? 1.1 : 1),
+    [showHoverEffect, showPressedEffect],
+  );
+
+  const checkOpacity = useMemo(
+    () => (checked ? (showPressedEffect ? 'opacity-55' : 'opacity-100') : 'opacity-0'),
+    [checked, showPressedEffect],
+  );
+
+  const showShadow = useMemo(() => {
+    const pressedAndUnchecked = showPressedEffect && !checked;
+    const hoverAndChecked = showHoverEffect && checked;
+
+    return !disabled && (pressedAndUnchecked || hoverAndChecked);
+  }, [checked, disabled, showHoverEffect, showPressedEffect]);
+
+  const motionAnimate = useMemo(() => ({ scale }), [scale]);
+
+  const motionTransition = useMemo(
+    () => (isPressed ? pressTransition : hoverTransition),
+    [isPressed],
+  );
+
+  /**
+   * Handlers
+   */
+  const handleOnChange = useCallback(
+    (e: ChangeEvent<HTMLInputElement>) => {
+      setGroupValue(e.target.value);
+      onChange?.(e);
+    },
+    [onChange, setGroupValue],
+  );
+
+  const handleFocus = useCallback(
+    (e: FocusEvent<HTMLInputElement>) => {
+      onFocus?.(e);
+    },
+    [onFocus],
+  );
+
+  const handleBlur = useCallback(
+    (e: FocusEvent<HTMLInputElement>) => {
+      onBlur?.(e);
+    },
+    [onBlur],
+  );
+
+  const handleHoverStart = useCallback(() => {
+    setIsHovered(true);
+  }, []);
+
+  const handleHoverEnd = useCallback(() => {
+    setIsHovered(false);
+  }, []);
+
+  const handleTapStart = useCallback(() => {
+    setIsPressed(true);
+  }, []);
+
+  const handleTapEnd = useCallback(() => {
+    setIsPressed(false);
+  }, []);
+
+  // Motion
+  const prefersReducedMotion = useReducedMotion();
+  const reduceMotion = forceReduceMotion ? 'always' : 'user';
+
+  const cssAnimationDuration =
+    prefersReducedMotion || forceReduceMotion ? 'duration-0' : 'duration-120';
+
+  const classNames = {
+    root: getStyles({
+      radioSizeRoot: size,
+      radioVariantValueRoot: checked ? 'checked' : 'unchecked',
+      radioVariantRoot: variant,
+      display: 'flex',
+      flexDirection: labelPosition === 'start' ? 'row' : 'row-reverse',
+      alignItems: 'center',
+      className: cx([
+        {
+          'cursor-pointer': !disabled,
+          'cursor-default': disabled,
+          'opacity-50': disabled,
+        },
+
+        className,
+        layerClassNames?.root,
+      ]),
+    }),
+
+    radio: getStyles({
+      radioSizeRadio: size,
+      radioVariantRadio: variant,
+      radioVariantValueRadio: checked ? 'checked' : 'unchecked',
+      className: cx([
+        'border',
+
+        'uds-ring',
+        'uds-ring-within',
+
+        cssAnimationDuration,
+        'transition-[background-color,border-color]',
+        'transition-shadow',
+
+        layerClassNames?.radio,
+      ]),
+    }),
+
+    radioCircle: getStyles({
+      radioVariantRadioCircle: variant,
+      radioVariantValueRadioCircle: checked ? 'checked' : 'unchecked',
+      className: cx([
+        'pointer-events-none',
+        'w-[8px]',
+        'h-[8px]',
+
+        // Variant/state specific check opacity override only used when checked.
+        checkOpacity,
+
+        cssAnimationDuration,
+        'transition-opacity',
+      ]),
+    }),
+
+    htmlRadio: cx(
+      // Control the cursor at the top of the component
+      // and don't let the input override it back to the
+      // default value.
+      'cursor-[inherit]',
+
+      'absolute',
+      'opacity-0',
+      'top-1/2',
+      'left-1/2',
+      'w-[calc(100%+2px)]',
+      'h-[calc(100%+2px)]',
+      'transform',
+      'translate-x-[-50%]',
+      'translate-y-[-50%]',
+    ),
+
+    label: cx(labelPosition === 'start' ? 'text-start' : 'text-end', layerClassNames?.label),
+  };
+
+  const RootElement = label ? m.label : m.div;
+
+  return (
+    <SpringMotionConfig reducedMotion={reduceMotion} {...motionTransition}>
+      <RootElement
+        className={classNames.root}
+        data-testid="container"
+        onHoverStart={handleHoverStart}
+        onHoverEnd={handleHoverEnd}
+        onTapStart={handleTapStart}
+        onTap={handleTapEnd}
+        onTapCancel={handleTapEnd}
+        tabIndex={-1}
+      >
+        <MotionBox
+          position="relative"
+          borderRadius="full"
+          alignItems="center"
+          justifyContent="center"
+          flex="none"
+          className={classNames.radio}
+          animate={motionAnimate}
+          insetShadow={showShadow ? 'lg-invert' : 'none'}
+        >
+          <input
+            type="radio"
+            // Required for Safari to render a focus ring
+            tabIndex={0}
+            // These are standard HTML input props for customization.
+            {...radioProps}
+            //
+            // Provide a ref to the underlying input element for customization.
+            ref={(ref) => {
+              // Set internal ref.
+              innerRef.current = ref;
+
+              // Forward the ref to parent.
+              if (typeof parentRef === 'function') {
+                parentRef(ref);
+              } else if (parentRef !== null) {
+                parentRef.current = ref;
+              }
+            }}
+            //
+            // Track focus as a prop for easier styling.
+            onFocus={handleFocus}
+            onBlur={handleBlur}
+            //
+            // Core props for the Radio.
+            id={uid}
+            name={name}
+            value={valueProp}
+            disabled={disabled}
+            aria-invalid={hasError}
+            onChange={handleOnChange}
+            {...(isControlled
+              ? {
+                  checked,
+                }
+              : {
+                  defaultChecked,
+                })}
+            //
+            // styles
+            className={classNames.htmlRadio}
+          />
+
+          <Box borderRadius="full" className={classNames.radioCircle} />
+        </MotionBox>
+
+        {label && (
+          <FormLabel
+            as="div"
+            variant="inherit"
+            color="inherit"
+            label={label}
+            className={classNames.label}
+          />
+        )}
+      </RootElement>
+    </SpringMotionConfig>
+  );
+});
+
+// Need to re-set this because of the forwardRef wrapper
+Radio.displayName = 'Radio';
+
+export { Radio, RADIO_SIZES, RADIO_VARIANTS, type RadioProps };

package/src/components/client/Radio/RadioGroupProvider.tsx

@@ -0,0 +1,122 @@
+import type { UniversalRadioGroupProps } from '@yahoo/uds/tokens';
+import React, { forwardRef, useEffect, useMemo } from 'react';
+
+import type { DivProps } from '../../../components/Box';
+import { createSlot } from '../../../utils/createSlot';
+import { RadioGroupContext, RadioGroupStore } from './RadioGroupStore';
+import { useRadioGroupName } from './useRadioGroup';
+
+const Slot = createSlot<React.ComponentType<DivProps>>();
+
+type NativeDivProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'>;
+
+interface RadioGroupProviderProps extends UniversalRadioGroupProps, NativeDivProps {}
+
+/**
+ * A custom RadioGroupStore that extends the default RadioGroupStore to allow for controlled RadioGroups.
+ */
+class RadioGroupProviderStore extends RadioGroupStore {
+  // The callback to notify the controlled RadioGroup of a value change.
+  onChangeCb?: (value: string | undefined) => void;
+
+  // Whether the RadioGroup is controlled
+  isControlled: boolean;
+
+  constructor(name: string, isControlled: boolean) {
+    super(name);
+
+    this.isControlled = isControlled;
+  }
+
+  // Overloads the default setValue to notify the controlled RadioGroup of a value change rather than setting the value directly.
+  setValue(value: string | undefined, force = false) {
+    // If we are being used inside RadioGroupProvider, we can force the store value to be set (and notify the listeners).
+    if (!this.isControlled || force) {
+      super.setValue(value);
+      return;
+    }
+
+    this.onChangeCb?.(value);
+  }
+}
+
+/**
+ * **⚙️️ A RadioGroup that improves accessibility and provides a central component for state manangement.
+ *
+ * @componentType Client component
+ *
+ * @description
+ * Provides a radio group
+ *
+ * @see
+ * Check out the {@link https://uds.build/docs/components/radio Radio Docs} for more info
+ *
+ * @usage
+ * - Forms: RadioGroup
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ * import { RadioGroup } from "@yahoo/uds";
+ *
+ * <RadioGroup name="items" value="1">
+ *   <Radio value="1" label="One" />
+ *   <Radio value="2" label="Two" />
+ * </RadioGroup>
+ *```
+ *
+ * @related [Radio](https://uds.build/docs/components/radio).
+ **/
+const RadioGroupProvider = forwardRef<HTMLDivElement, RadioGroupProviderProps>(
+  function RadioGroupProvider(
+    { asChild, name, value: valueProp, defaultValue, onChange, ...props },
+    ref,
+  ) {
+    const isControlled = valueProp !== undefined;
+    const localName = useRadioGroupName(name);
+
+    // The store for this RadioGroup. Will be created once, memoized and used as the context value.
+    const store = useMemo(() => {
+      const s = new RadioGroupProviderStore(localName, isControlled);
+
+      // Set the initial value of the store
+      s.value = isControlled ? valueProp : defaultValue;
+
+      return s;
+    }, [defaultValue, isControlled, localName, valueProp]);
+
+    useEffect(() => {
+      // The store should call the onChange callback when the a change event is emitted.
+      store.onChangeCb = onChange;
+    }, [onChange, store]);
+
+    useEffect(() => {
+      if (!isControlled) {
+        return;
+      }
+
+      store.setValue(
+        valueProp,
+        true, // Force set the value since we are responding to a controlled prop change.
+      );
+    }, [isControlled, store, valueProp]);
+
+    // When the store changes, trigger a change.
+    useEffect(() => {
+      return store.onChange((value) => onChange?.(value));
+    }, [onChange, store]);
+
+    const Comp = asChild ? Slot : 'div';
+
+    return (
+      <RadioGroupContext.Provider value={store}>
+        <Comp role="radiogroup" ref={ref} {...props} />
+      </RadioGroupContext.Provider>
+    );
+  },
+);
+
+// Need to re-set this because of the forwardRef wrapper
+RadioGroupProvider.displayName = 'RadioGroupProvider';
+
+export { RadioGroupProvider, type RadioGroupProviderProps };

package/src/components/client/Radio/RadioGroupStore.tsx

@@ -0,0 +1,56 @@
+import { createContext } from 'react';
+
+type RadioGroupStoreOnChange = (value: string | undefined) => void;
+
+/**
+ * A store for a single RadioGroup. This store is used to manage the state of all Radios within a group.
+ */
+class RadioGroupStore {
+  // The html name attribute of the RadioGroup.
+  name: string;
+
+  // The current value of the RadioGroup.
+  value?: string;
+
+  // A count of the number of active Radios in the group. Used to cleanup stores when all Radios are unmounted.
+  activeCount = 0;
+
+  // A set of listeners to call when the value of the RadioGroup changes.
+  #changeListeners = new Set<RadioGroupStoreOnChange>();
+
+  constructor(name: string) {
+    this.name = name;
+  }
+
+  // Register a listener to be called when the value of the RadioGroup changes.
+  onChange(cb: RadioGroupStoreOnChange) {
+    this.#changeListeners.add(cb);
+
+    // Return a function to remove the listener (used as unmount handler in useEffect).
+    return () => {
+      this.#changeListeners.delete(cb);
+    };
+  }
+
+  // Set the value of the RadioGroup and notify all listeners.
+  setValue(value: string | undefined) {
+    this.value = value;
+    this.#changeListeners.forEach((cb) => cb(value));
+  }
+
+  // Create a new store when first encounting a new RadioGroup name.
+  static findOrCreate(radioGroupStores: Map<string, RadioGroupStore>, name: string) {
+    let store = radioGroupStores.get(name);
+
+    if (!store) {
+      store = new RadioGroupStore(name);
+      radioGroupStores.set(name, store);
+    }
+
+    return store;
+  }
+}
+
+const RadioGroupContext = createContext<Map<string, RadioGroupStore> | RadioGroupStore>(new Map());
+
+export { RadioGroupContext, RadioGroupStore };

package/src/components/client/Radio/index.ts

@@ -0,0 +1,2 @@
+export { Radio, type RadioProps } from './Radio';
+export { RadioGroupProvider, type RadioGroupProviderProps } from './RadioGroupProvider';

package/src/components/client/Radio/useRadioGroup.ts

@@ -0,0 +1,149 @@
+import { useCallback, useContext, useEffect, useId, useMemo, useState } from 'react';
+
+import { RadioGroupContext, RadioGroupStore } from './RadioGroupStore';
+
+const useRadioGroupName = (name?: string) => {
+  const uid = useId();
+  return name ?? `uds-radio-group-${uid}`;
+};
+
+/**
+ * A hook that connects a single Radio to its RadioGroupStore. If the Radio is used within a RadioGroupProvider,
+ * it will use the context store. Otherwise, it will use a shared global store across all un-grouped Radios by name.
+ *
+ * @param name The name of the Radio which should be shared across the group.
+ * @param value The value of the Radio.
+ * @param checked Whether the Radio is checked by its controlled prop.
+ * @param defaultChecked The uncontrolled default checked state of the Radio.
+ * @returns The name of the RadioGroup, whether the Radio is controlled, the checked state of the Radio, and a function to set the RadioGroup value.
+ */
+const useRadioGroup = ({
+  name: radioName,
+  value: radioValue,
+  checked: radioIsChecked,
+  defaultChecked: radioDefaultIsChecked,
+}: {
+  name?: string | undefined;
+  value: string;
+  checked?: boolean;
+  defaultChecked?: boolean;
+}): {
+  name: string;
+  isControlled: boolean;
+  checked: boolean | undefined;
+  setGroupValue: (value: string) => void;
+} => {
+  const ctx = useContext(RadioGroupContext);
+  const hasRadioGroupProvider = ctx instanceof RadioGroupStore;
+  const isControlled = radioIsChecked !== undefined || hasRadioGroupProvider;
+
+  // Use either the name passed as a prop on Radio or generate a unique name.
+  const uniqueName = useRadioGroupName(radioName);
+
+  // Get the Store controlling this Radio.
+  const store = useMemo(() => {
+    // Either from RadioGroupProvider
+    if (hasRadioGroupProvider) {
+      return ctx;
+    }
+
+    // Or indexed by name in the global store.
+    return RadioGroupStore.findOrCreate(ctx, uniqueName);
+  }, [ctx, hasRadioGroupProvider, uniqueName]);
+
+  // The internal value of the RadioGroup.
+  const [radioGroupValue, setInternalRadioGroupValue] = useState<string | undefined>(store.value);
+
+  // If the store has a name set, all Radios inside the group should use that name. Otherwise use the Radio's name.
+  const name = store.name ?? uniqueName;
+
+  // Set the value of the RadioGroup.
+  const setGroupValue = useCallback(
+    (value: string) => {
+      // Notify the store.
+      store.setValue(value);
+
+      if (isControlled) {
+        return;
+      }
+
+      // and optimistically update the internal value.
+      setInternalRadioGroupValue(value);
+    },
+    [isControlled, store],
+  );
+
+  // Listen for store changes and update the internal value when it changes.
+  useEffect(() => store.onChange(setInternalRadioGroupValue), [store]);
+
+  useEffect(() => {
+    // Only update the store if a new Radio in the group has become checked.
+    if (radioIsChecked !== true) {
+      return;
+    }
+
+    setGroupValue(radioValue);
+  }, [radioIsChecked, radioValue, setGroupValue]);
+
+  // Register with the global store for relating Radios without a RadioGroupProvider.
+  useEffect(() => {
+    // Don't need the global store if wrapped in a RadioGroupProvider.
+    if (hasRadioGroupProvider) {
+      return;
+    }
+
+    // Get a store given the RadioGroup name.
+    const store = RadioGroupStore.findOrCreate(ctx, name);
+
+    // Increment the number of Radios using this store.
+    store.activeCount += 1;
+
+    // Save the store in the context.
+    ctx.set(name, store);
+
+    // On unmount.
+    return () => {
+      // If this radio is in the store...
+      const entry = ctx.get(name);
+
+      if (!entry) {
+        return;
+      }
+
+      // Decrement the number of Radios using this store.
+      entry.activeCount -= 1;
+
+      // If there are no more Radios using this store, delete it.
+      if (entry.activeCount === 0) {
+        ctx.delete(name);
+      }
+    };
+  }, [ctx, hasRadioGroupProvider, name]);
+
+  // Complicated boolean logic reads better as a IIFE than a ternary.
+  const checked = (() => {
+    // If the Radio is controlled by its checked prop AND it's not in a RadioGroupProvider, use the prop.
+    if (isControlled && !hasRadioGroupProvider) {
+      return radioIsChecked;
+    }
+
+    // If the RadioGroup is controlled by a value prop...
+    if (radioGroupValue !== undefined) {
+      // The Radio is checked if its value matches the current value of the group.
+      return radioValue === radioGroupValue;
+    }
+
+    // Otherwise, we are in an uncontrolled state. If present, our internal value is the defaultChecked prop,
+    // otherwise we are not checked.
+    return radioDefaultIsChecked ?? false;
+  })();
+
+  return {
+    name,
+    isControlled,
+    checked,
+    setGroupValue,
+  };
+};
+
+export { useRadioGroup, useRadioGroupName };