@cdx-ui/primitives 0.1.5 → 0.1.7

package/src/toggle-button/ToggleButtonRoot.web.tsx

@@ -0,0 +1,225 @@
+import { forwardRef, useEffect, useMemo, useRef, type ComponentRef } from 'react';
+import { Pressable, type PressableProps } from 'react-native';
+import { composeEventHandlers, mergeRefs, useControllableState } from '@cdx-ui/utils';
+import { useFocus, useFocusRing } from '@react-native-aria/focus';
+import { useHover, usePress } from '@react-native-aria/interactions';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { ToggleButtonProvider, useOptionalToggleButtonGroupContext } from './context';
+import { getToggleState } from './toggleState';
+import type { IToggleButtonProps } from './types';
+import { getRovingFocusValue } from './useToggleButtonGroupNavigation';
+
+export interface ToggleButtonRootProps extends IToggleButtonProps {}
+
+export const ToggleButtonRoot = forwardRef<ComponentRef<typeof Pressable>, ToggleButtonRootProps>(
+  (
+    {
+      asChild = false,
+      value,
+      isSelected: controlledSelected,
+      defaultSelected,
+      onSelectedChange,
+      isDisabled: isDisabledProp = false,
+      children,
+      onPress,
+      onFocus,
+      onBlur,
+      style,
+      ...rest
+    },
+    ref,
+  ) => {
+    const group = useOptionalToggleButtonGroupContext();
+
+    const [standaloneSelected = false, setStandaloneSelected] = useControllableState<boolean>({
+      prop: controlledSelected,
+      defaultProp: defaultSelected ?? false,
+      onChange: (next) => {
+        onSelectedChange?.(next);
+      },
+    });
+
+    const isSelected = group ? group.isSelected(value) : standaloneSelected;
+    const isDisabled = (group?.isGroupDisabled ?? false) || isDisabledProp;
+
+    const { focusProps, isFocused } = useFocus();
+    const { isFocusVisible, focusProps: focusRingProps } = useFocusRing() as {
+      isFocusVisible: boolean;
+      focusProps: typeof focusProps;
+    };
+    const { pressProps, isPressed } = usePress({ isDisabled });
+    const { hoverProps, isHovered } = useHover();
+
+    const selectionType: 'single' | 'multiple' | 'standalone' = group ? group.type : 'standalone';
+
+    const role = selectionType === 'single' ? ('radio' as const) : ('button' as const);
+
+    const accessibilityState = useMemo(
+      () => ({
+        disabled: isDisabled,
+        ...(selectionType === 'single'
+          ? { checked: isSelected, selected: isSelected }
+          : { selected: isSelected }),
+      }),
+      [isDisabled, isSelected, selectionType],
+    );
+
+    const ariaProps =
+      selectionType === 'single' ? { 'aria-checked': isSelected } : { 'aria-pressed': isSelected };
+
+    const nodeRef = useRef<ComponentRef<typeof Pressable> | null>(null);
+    const setRefs = mergeRefs(ref, nodeRef);
+
+    const registerItem = group?.registerItem;
+    const unregisterItem = group?.unregisterItem;
+    const getItems = group?.getItems;
+    const focusedValue = group?.focusedValue;
+    const anchorValue =
+      group?.type === 'single'
+        ? typeof group.value === 'string'
+          ? group.value
+          : undefined
+        : Array.isArray(group?.value) && group.value.length > 0
+          ? group.value[0]
+          : undefined;
+
+    useEffect(() => {
+      if (!registerItem || !unregisterItem) {
+        return;
+      }
+
+      registerItem(value, {
+        disabled: !!isDisabled,
+        node: nodeRef.current as { focus?: () => void } | null,
+      });
+
+      return () => unregisterItem(value);
+    }, [value, isDisabled, registerItem, unregisterItem]);
+
+    const isRovingTabStop = useMemo(() => {
+      if (!group || isDisabled) {
+        return !group;
+      }
+
+      const enabledItems = getItems?.().filter(([, entry]) => !entry.disabled) ?? [];
+      const rovingValue = getRovingFocusValue(focusedValue, anchorValue, enabledItems);
+
+      return value === rovingValue;
+    }, [anchorValue, focusedValue, getItems, group, isDisabled, value]);
+
+    const toggleButtonContext = useMemo(
+      () => ({
+        value,
+        isSelected,
+        isDisabled,
+        selectionType,
+        hover: isHovered,
+        active: isPressed,
+        focus: isFocused,
+        focusVisible: isFocusVisible,
+      }),
+      [
+        value,
+        isSelected,
+        isDisabled,
+        selectionType,
+        isHovered,
+        isPressed,
+        isFocused,
+        isFocusVisible,
+      ],
+    );
+
+    const markRovingFocus = () => {
+      if (!isDisabled) {
+        group?.setFocusedValue?.(value);
+      }
+    };
+
+    const toggle = () => {
+      if (isDisabled) {
+        return;
+      }
+      if (group) {
+        markRovingFocus();
+        group.toggleValue(value);
+      } else {
+        setStandaloneSelected(!standaloneSelected);
+      }
+    };
+
+    const composedOnPress = composeEventHandlers(onPress, toggle);
+
+    // RNW's press responder already turns Space into a press for role="button", but ignores
+    // it for role="radio", so only single-select items handle Space here.
+    const handleKeyDown = (event: {
+      key: string;
+      repeat?: boolean;
+      preventDefault: () => void;
+    }) => {
+      if (selectionType !== 'single') {
+        return;
+      }
+      if (event.key === ' ' || event.key === 'Spacebar') {
+        event.preventDefault();
+        if (!event.repeat) {
+          toggle();
+        }
+      }
+    };
+
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <ToggleButtonProvider value={toggleButtonContext}>
+        <Comp
+          ref={setRefs}
+          accessibilityRole={role}
+          role={role}
+          accessibilityState={accessibilityState}
+          {...ariaProps}
+          {...(isDisabled ? { 'aria-disabled': true as const } : {})}
+          disabled={isDisabled}
+          tabIndex={group ? (isDisabled ? -1 : isRovingTabStop ? 0 : -1) : undefined}
+          {...(rest as PressableProps)}
+          {...mergeDataAttributes(
+            rest,
+            dataAttributes({
+              selected: isSelected,
+              disabled: isDisabled,
+              active: isPressed,
+              hover: isHovered,
+              focus: isFocused,
+              focusVisible: isFocusVisible,
+              toggleState: getToggleState(isSelected, isPressed, isHovered),
+            }),
+          )}
+          style={style}
+          onPress={isDisabled ? undefined : composedOnPress}
+          onKeyDown={composeEventHandlers(
+            (rest as { onKeyDown?: (e: { key: string; preventDefault: () => void }) => void })
+              .onKeyDown,
+            handleKeyDown,
+          )}
+          onPressIn={composeEventHandlers(rest.onPressIn, pressProps.onPressIn)}
+          onPressOut={composeEventHandlers(rest.onPressOut, pressProps.onPressOut)}
+          onHoverIn={composeEventHandlers(rest.onHoverIn, hoverProps.onHoverIn)}
+          onHoverOut={composeEventHandlers(rest.onHoverOut, hoverProps.onHoverOut)}
+          onFocus={composeEventHandlers(
+            composeEventHandlers(onFocus, markRovingFocus),
+            composeEventHandlers(focusProps.onFocus, focusRingProps.onFocus),
+          )}
+          onBlur={composeEventHandlers(
+            composeEventHandlers(onBlur, focusProps.onBlur),
+            focusRingProps.onBlur,
+          )}
+        >
+          {children}
+        </Comp>
+      </ToggleButtonProvider>
+    );
+  },
+);
+
+ToggleButtonRoot.displayName = 'ToggleButtonRoot';

package/src/toggle-button/context.tsx

@@ -0,0 +1,30 @@
+import { createContext as createReactContext, useContext } from 'react';
+import { createContext } from '@cdx-ui/utils';
+import type { IToggleButtonGroupContextValue } from './types';
+
+export const [ToggleButtonProvider, useToggleButtonContext] = createContext<{
+  value: string;
+  isSelected: boolean;
+  isDisabled: boolean;
+  selectionType: 'single' | 'multiple' | 'standalone';
+  hover: boolean;
+  active: boolean;
+  focus: boolean;
+  focusVisible: boolean;
+}>('ToggleButtonContext');
+
+const ToggleButtonGroupContext = createReactContext<IToggleButtonGroupContextValue | null>(null);
+
+export const ToggleButtonGroupContextProvider = ToggleButtonGroupContext.Provider;
+
+export function useToggleButtonGroupContext(): IToggleButtonGroupContextValue {
+  const ctx = useContext(ToggleButtonGroupContext);
+  if (!ctx) {
+    throw new Error('ToggleButton must be used within ToggleButtonGroup');
+  }
+  return ctx;
+}
+
+export function useOptionalToggleButtonGroupContext(): IToggleButtonGroupContextValue | null {
+  return useContext(ToggleButtonGroupContext);
+}

package/src/toggle-button/index.ts

@@ -0,0 +1,16 @@
+export { ToggleButtonRoot, type ToggleButtonRootProps } from './ToggleButtonRoot';
+export { ToggleButtonGroup, type ToggleButtonGroupProps } from './ToggleButtonGroup';
+export {
+  ToggleButtonProvider,
+  useToggleButtonContext,
+  useToggleButtonGroupContext,
+  useOptionalToggleButtonGroupContext,
+} from './context';
+export type {
+  IToggleButtonProps,
+  IToggleButtonGroupProps,
+  IToggleButtonGroupSingleProps,
+  IToggleButtonGroupMultipleProps,
+  IToggleButtonGroupContextValue,
+  ToggleButtonGroupType,
+} from './types';

package/src/toggle-button/toggleState.ts

@@ -0,0 +1,19 @@
+// Keyed `selected:active:hover`. Press outranks hover so each combination maps to exactly one
+// value, letting the styled layer use single-condition selectors that also work on native.
+const TOGGLE_STATES = {
+  'false:false:false': 'idle',
+  'false:false:true': 'hover',
+  'false:true:false': 'active',
+  'false:true:true': 'active',
+  'true:false:false': 'selected',
+  'true:false:true': 'selected-hover',
+  'true:true:false': 'selected-active',
+  'true:true:true': 'selected-active',
+} as const;
+
+export type ToggleState = (typeof TOGGLE_STATES)[keyof typeof TOGGLE_STATES];
+
+export function getToggleState(selected: boolean, active: boolean, hover: boolean): ToggleState {
+  const key = [selected, active, hover].map((flag) => (flag ? 'true' : 'false')).join(':');
+  return TOGGLE_STATES[key as keyof typeof TOGGLE_STATES];
+}

package/src/toggle-button/types.ts

@@ -0,0 +1,94 @@
+import type { PressableProps, ViewProps } from 'react-native';
+
+export type ToggleButtonGroupType = 'single' | 'multiple';
+
+export type ToggleButtonGroupValue = string | string[] | undefined;
+
+interface IToggleButtonGroupBaseProps extends ViewProps {
+  /** Merge group props onto a single child instead of rendering the default View. */
+  asChild?: boolean;
+  /** Disables every item in the group. */
+  isDisabled?: boolean;
+  /**
+   * Layout direction and arrow-key axis.
+   * @default 'horizontal'
+   */
+  orientation?: 'horizontal' | 'vertical';
+  /** Accessible name for the group (required when no visible label). */
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+}
+
+export interface IToggleButtonGroupSingleProps extends IToggleButtonGroupBaseProps {
+  /**
+   * Single-select (radio semantics). `value` is the selected item's `value`.
+   * @default 'single'
+   */
+  type?: 'single';
+  /** Currently selected item `value` (controlled). */
+  value?: string;
+  /** Initially selected item `value` (uncontrolled). */
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+}
+
+export interface IToggleButtonGroupMultipleProps extends IToggleButtonGroupBaseProps {
+  /**
+   * Multi-select (pressed-button semantics). `value` is an array of selected item `value`s.
+   */
+  type: 'multiple';
+  /** Currently selected item `value`s (controlled). */
+  value?: string[];
+  /** Initially selected item `value`s (uncontrolled). */
+  defaultValue?: string[];
+  onValueChange?: (value: string[]) => void;
+}
+
+/**
+ * Discriminated union: `type` narrows `value` / `defaultValue` / `onValueChange`.
+ */
+export type IToggleButtonGroupProps =
+  | IToggleButtonGroupSingleProps
+  | IToggleButtonGroupMultipleProps;
+
+export interface RegisteredToggleButton {
+  disabled: boolean;
+  node: { focus?: () => void } | null;
+}
+
+export interface IToggleButtonGroupContextValue {
+  type: ToggleButtonGroupType;
+  orientation: 'horizontal' | 'vertical';
+  value: ToggleButtonGroupValue;
+  toggleValue: (buttonValue: string) => void;
+  isSelected: (buttonValue: string) => boolean;
+  isGroupDisabled: boolean;
+  focusedValue?: string | undefined;
+  setFocusedValue?: (value: string | undefined) => void;
+  registerItem?: (value: string, entry: RegisteredToggleButton) => void;
+  unregisterItem?: (value: string) => void;
+  getItems?: () => [string, RegisteredToggleButton][];
+}
+
+export interface IToggleButtonProps extends PressableProps {
+  /** Render the consumer's child in place of the default `Pressable` host. */
+  asChild?: boolean;
+  /**
+   * Identifies this button within a `ToggleButtonGroup`. Must be unique within the group.
+   * Standalone buttons still require a value.
+   */
+  value: string;
+  /**
+   * Controlled selected state (standalone only; ignored inside `ToggleButtonGroup`).
+   */
+  isSelected?: boolean;
+  /**
+   * Uncontrolled initial selected state (standalone only).
+   * @default false
+   */
+  defaultSelected?: boolean;
+  /** Called when standalone selected state changes. */
+  onSelectedChange?: (isSelected: boolean) => void;
+  /** @default false */
+  isDisabled?: boolean;
+}

package/src/toggle-button/useToggleButtonGroupNavigation.ts

@@ -0,0 +1,112 @@
+import { useCallback, useRef } from 'react';
+import type { RegisteredToggleButton, ToggleButtonGroupType } from './types';
+
+function isEnabledItemValue(
+  value: string | null | undefined,
+  enabledItems: [string, RegisteredToggleButton][],
+): value is string {
+  return value != null && enabledItems.some(([itemValue]) => itemValue === value);
+}
+
+/** Resolves which item value should hold the roving tab stop / keyboard focus anchor. */
+export function getRovingFocusValue(
+  focusedValue: string | undefined,
+  anchorValue: string | null | undefined,
+  enabledItems: [string, RegisteredToggleButton][],
+): string | undefined {
+  const defaultFocusValue = isEnabledItemValue(anchorValue, enabledItems)
+    ? anchorValue
+    : enabledItems[0]?.[0];
+
+  const resolvedFocusedValue = isEnabledItemValue(focusedValue, enabledItems)
+    ? focusedValue
+    : undefined;
+
+  return resolvedFocusedValue ?? defaultFocusValue;
+}
+
+export interface UseToggleButtonGroupNavigationOptions {
+  type: ToggleButtonGroupType;
+  orientation: 'horizontal' | 'vertical';
+  getItems: () => [string, RegisteredToggleButton][];
+  focusedValue: string | undefined;
+  setFocusedValue: (value: string | undefined) => void;
+  anchorValue: string | null | undefined;
+  selectOnFocus?: (value: string) => void;
+}
+
+export function useToggleButtonGroupNavigation({
+  type,
+  orientation,
+  getItems,
+  focusedValue,
+  setFocusedValue,
+  anchorValue,
+  selectOnFocus,
+}: UseToggleButtonGroupNavigationOptions) {
+  const selectOnFocusRef = useRef(selectOnFocus);
+  selectOnFocusRef.current = selectOnFocus;
+
+  const getEnabledItems = useCallback(
+    () => getItems().filter(([, entry]) => !entry.disabled),
+    [getItems],
+  );
+
+  const moveFocus = useCallback(
+    ([targetValue, targetEntry]: [string, RegisteredToggleButton], shouldSelect: boolean) => {
+      setFocusedValue(targetValue);
+      targetEntry.node?.focus?.();
+      if (shouldSelect) {
+        selectOnFocusRef.current?.(targetValue);
+      }
+    },
+    [setFocusedValue],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: { key: string; preventDefault: () => void }) => {
+      const enabledItems = getEnabledItems();
+      if (enabledItems.length === 0) {
+        return;
+      }
+
+      const currentValue = getRovingFocusValue(focusedValue, anchorValue, enabledItems);
+      const idx = enabledItems.findIndex(([value]) => value === currentValue);
+      const shouldSelectOnFocus = type === 'single';
+
+      const nextKeys = orientation === 'vertical' ? ['ArrowDown'] : ['ArrowRight', 'ArrowDown'];
+      const prevKeys = orientation === 'vertical' ? ['ArrowUp'] : ['ArrowLeft', 'ArrowUp'];
+
+      if (nextKeys.includes(e.key)) {
+        e.preventDefault();
+        moveFocus(enabledItems[idx < enabledItems.length - 1 ? idx + 1 : 0], shouldSelectOnFocus);
+        return;
+      }
+
+      if (prevKeys.includes(e.key)) {
+        e.preventDefault();
+        moveFocus(enabledItems[idx > 0 ? idx - 1 : enabledItems.length - 1], shouldSelectOnFocus);
+        return;
+      }
+
+      switch (e.key) {
+        case 'Home': {
+          e.preventDefault();
+          moveFocus(enabledItems[0], shouldSelectOnFocus);
+          break;
+        }
+        case 'End': {
+          e.preventDefault();
+          const last = enabledItems.at(-1);
+          if (last) {
+            moveFocus(last, shouldSelectOnFocus);
+          }
+          break;
+        }
+      }
+    },
+    [anchorValue, focusedValue, getEnabledItems, moveFocus, orientation, type],
+  );
+
+  return { handleKeyDown };
+}