@cdx-ui/components 0.3.4 → 0.3.6

package/src/components/Stepper/index.tsx

@@ -0,0 +1,452 @@
+import {
+  Children,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useContext,
+  useMemo,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { Text, View, type TextProps, type ViewProps } from 'react-native';
+import {
+  Slot,
+  StepperRoot,
+  StepperStep,
+  StepperStepTrigger,
+  dataAttributes,
+  mergeDataAttributes,
+  useStepperContext,
+  useStepperIndex,
+  useStepperStep,
+  type IStepperProps,
+  type IStepperStepProps,
+} from '@cdx-ui/primitives';
+import { CheckCircle } from '@cdx-ui/icons';
+import { cn, flattenChildren, mergeRefs } from '@cdx-ui/utils';
+import { Icon } from '../Icon';
+import { ProgressRing } from '../ProgressCircle/ProgressRing';
+import {
+  getStepperLayout,
+  STEPPER_INDICATOR_SIZE,
+  STEPPER_RING_STROKE_WIDTH,
+  stepperContentVariants,
+  stepperDescriptionVariants,
+  stepperIndicatorCheckVariants,
+  stepperIndicatorDiscVariants,
+  stepperIndicatorNumeralVariants,
+  stepperIndicatorRingVariants,
+  stepperIndicatorVariants,
+  stepperSeparatorVariants,
+  stepperStepBodyVariants,
+  stepperStepLabelVariants,
+  stepperStepMainVariants,
+  stepperStepTriggerVariants,
+  stepperStepVariants,
+  stepperTitleVariants,
+  stepperVariants,
+} from './styles';
+import { useStepperLabelFit, type StepperLabelFit } from './useStepperLabelFit';
+import { useStepperRingColors } from './useStepperRingColors';
+
+export { useStepperStep } from '@cdx-ui/primitives';
+export type {
+  StepperLabelPlacement,
+  StepperOrientation,
+  StepperStepState,
+} from '@cdx-ui/primitives';
+
+const StepperLabelFitContext = createContext<StepperLabelFit>('shrink');
+
+/** Counts steps the way `StepperRoot` numbers them, so the label-fit decision resets with them. */
+function countSteps(children: ReactNode, asChild: boolean | undefined): number {
+  const source =
+    asChild && isValidElement<{ children?: ReactNode }>(children)
+      ? children.props.children
+      : children;
+  return flattenChildren(source).filter((child) => isValidElement(child)).length;
+}
+
+const HIDDEN_FROM_AT = {
+  'aria-hidden': true,
+  accessibilityElementsHidden: true,
+  importantForAccessibility: 'no-hide-descendants',
+} as const;
+
+// =============================================================================
+// ROOT
+// =============================================================================
+
+export interface StepperProps extends IStepperProps {
+  readonly className?: string;
+  /**
+   * `Stepper.Step` elements. Every direct element child is a step and is numbered by position;
+   * arrays and fragments are unwrapped, and `false`/`null` children are skipped.
+   */
+  readonly children?: ReactNode;
+}
+
+const StepperRootComponent = forwardRef<View, StepperProps>(
+  (
+    { className, style, orientation = 'vertical', labelPlacement = 'end', children, ...props },
+    ref,
+  ) => {
+    const layout = getStepperLayout(orientation, labelPlacement);
+    const { fit, measureRef } = useStepperLabelFit(
+      layout === 'horizontal-end',
+      countSteps(children, props.asChild),
+    );
+    const rootRef = useMemo(
+      () => (measureRef === undefined ? ref : mergeRefs(ref, measureRef)),
+      [ref, measureRef],
+    );
+
+    return (
+      <StepperLabelFitContext.Provider value={fit}>
+        <StepperRoot
+          ref={rootRef}
+          className={cn(stepperVariants({ layout }), className)}
+          style={style}
+          orientation={orientation}
+          labelPlacement={labelPlacement}
+          {...props}
+          {...mergeDataAttributes(props, dataAttributes({ slot: 'stepper' }))}
+        >
+          {children}
+        </StepperRoot>
+      </StepperLabelFitContext.Provider>
+    );
+  },
+);
+
+StepperRootComponent.displayName = 'Stepper';
+
+// =============================================================================
+// STEP
+// =============================================================================
+
+export interface StepperStepProps extends IStepperStepProps {
+  readonly className?: string;
+  /**
+   * `Stepper.Indicator`, `Stepper.Title`, `Stepper.Description`, `Stepper.Content` and
+   * `Stepper.Separator`. They must be **direct** children: the step sorts them into regions by
+   * component identity, so a `memo()`/HOC wrapper is not recognized and renders as content.
+   * Only the first of each slot is used. `asChild` skips the sorting.
+   */
+  readonly children?: ReactNode;
+}
+
+function isSlot(child: ReactNode, type: unknown): child is ReactElement {
+  return isValidElement(child) && child.type === type;
+}
+
+const StepperStepComponent = forwardRef<View, StepperStepProps>(
+  ({ asChild, className, style, children, ...props }, ref) => {
+    const { orientation, labelPlacement, count } = useStepperContext();
+    const layout = getStepperLayout(orientation, labelPlacement);
+    const labelFit = useContext(StepperLabelFitContext);
+    const isLast = useStepperIndex() === count - 1;
+    const stepClass = cn(stepperStepVariants({ layout, isLast, labelFit }), className);
+    const slotAttributes = mergeDataAttributes(props, dataAttributes({ slot: 'stepper-step' }));
+
+    if (asChild) {
+      return (
+        <StepperStep
+          ref={ref}
+          asChild
+          className={stepClass}
+          style={style}
+          {...props}
+          {...slotAttributes}
+        >
+          {children}
+        </StepperStep>
+      );
+    }
+
+    // Indicator, Title and Description form the step trigger, which carries the accessible
+    // name; everything else is the body below the title. The Separator sits in the indicator
+    // track: before the main column when vertical, after it when horizontal.
+    const childArray = Children.toArray(children);
+    const indicator = childArray.find((child) => isSlot(child, StepperIndicatorComponent));
+    const title = childArray.find((child) => isSlot(child, StepperTitleComponent));
+    const description = childArray.find((child) => isSlot(child, StepperDescriptionComponent));
+    const separator = childArray.find((child) => isSlot(child, StepperSeparatorComponent));
+    const body = childArray.filter(
+      (child) =>
+        !isSlot(child, StepperIndicatorComponent) &&
+        !isSlot(child, StepperTitleComponent) &&
+        !isSlot(child, StepperDescriptionComponent) &&
+        !isSlot(child, StepperSeparatorComponent),
+    );
+    const hasLabel = title !== undefined || description !== undefined;
+
+    return (
+      <StepperStep ref={ref} className={stepClass} style={style} {...props} {...slotAttributes}>
+        {layout === 'vertical' ? separator : null}
+        <View className={cn(stepperStepMainVariants({ layout, labelFit }))}>
+          <StepperStepTrigger
+            className={stepperStepTriggerVariants({ layout })}
+            {...dataAttributes({ slot: 'stepper-step-trigger' })}
+          >
+            {indicator}
+            {hasLabel ? (
+              <View className={cn(stepperStepLabelVariants({ layout, labelFit }))}>
+                {title}
+                {description}
+              </View>
+            ) : null}
+          </StepperStepTrigger>
+          {body.length > 0 ? (
+            <View className={stepperStepBodyVariants({ layout })}>{body}</View>
+          ) : null}
+        </View>
+        {layout === 'vertical' ? null : separator}
+      </StepperStep>
+    );
+  },
+);
+
+StepperStepComponent.displayName = 'Stepper.Step';
+
+// =============================================================================
+// INDICATOR
+// =============================================================================
+
+export interface StepperIndicatorProps extends ViewProps {
+  /** Replaces the whole indicator with the child element via `Slot`. */
+  readonly asChild?: boolean;
+  readonly className?: string;
+  /**
+   * Replaces the glyph inside the disc. The disc, tone and progress ring still render.
+   * Defaults to a check when the step is complete, otherwise the 1-based step number.
+   */
+  readonly children?: ReactNode;
+}
+
+const StepperIndicatorComponent = forwardRef<View, StepperIndicatorProps>(
+  ({ asChild, className, style, children, ...props }, ref) => {
+    const { index, isCurrent, isComplete, hasProgress, progress } = useStepperStep();
+    const ringColors = useStepperRingColors(isCurrent);
+    const currentAttribute = dataAttributes({ current: isCurrent });
+    const indicatorClass = cn(stepperIndicatorVariants(), className);
+    const indicatorAttributes = mergeDataAttributes(
+      props,
+      dataAttributes({
+        slot: 'stepper-indicator',
+        current: isCurrent,
+        complete: isComplete,
+        progress: hasProgress,
+      }),
+    );
+
+    if (asChild) {
+      return (
+        <Slot
+          ref={ref}
+          className={indicatorClass}
+          style={style}
+          {...props}
+          {...HIDDEN_FROM_AT}
+          {...indicatorAttributes}
+        >
+          {children}
+        </Slot>
+      );
+    }
+
+    const hasCustomGlyph = children !== undefined && children !== null;
+
+    return (
+      <View
+        ref={ref}
+        className={indicatorClass}
+        style={style}
+        {...props}
+        {...HIDDEN_FROM_AT}
+        {...indicatorAttributes}
+      >
+        {hasProgress ? (
+          <View className={stepperIndicatorRingVariants()}>
+            <ProgressRing
+              size={STEPPER_INDICATOR_SIZE}
+              strokeWidth={STEPPER_RING_STROKE_WIDTH}
+              value={progress}
+              trackColor={ringColors.track}
+              indicatorColor={ringColors.indicator}
+            />
+          </View>
+        ) : null}
+        {isComplete && !hasCustomGlyph ? (
+          <Icon
+            as={CheckCircle}
+            filled
+            className={stepperIndicatorCheckVariants()}
+            {...currentAttribute}
+          />
+        ) : (
+          <View className={stepperIndicatorDiscVariants()} {...currentAttribute}>
+            {hasCustomGlyph ? (
+              children
+            ) : (
+              <Text className={stepperIndicatorNumeralVariants()} {...currentAttribute}>
+                {String(index + 1)}
+              </Text>
+            )}
+          </View>
+        )}
+      </View>
+    );
+  },
+);
+
+StepperIndicatorComponent.displayName = 'Stepper.Indicator';
+
+// =============================================================================
+// TITLE
+// =============================================================================
+
+export interface StepperTitleProps extends TextProps {
+  readonly asChild?: boolean;
+  readonly className?: string;
+  readonly children?: ReactNode;
+}
+
+const StepperTitleComponent = forwardRef<Text, StepperTitleProps>(
+  ({ asChild, className, style, ...props }, ref) => {
+    const { isCurrent, orientation, labelPlacement } = useStepperStep();
+    const isCentered = getStepperLayout(orientation, labelPlacement) === 'horizontal-bottom';
+    const Comp = asChild ? Slot : Text;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(stepperTitleVariants({ isCentered }), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({ slot: 'stepper-title', current: isCurrent }),
+        )}
+      />
+    );
+  },
+);
+
+StepperTitleComponent.displayName = 'Stepper.Title';
+
+// =============================================================================
+// DESCRIPTION
+// =============================================================================
+
+export interface StepperDescriptionProps extends TextProps {
+  readonly asChild?: boolean;
+  readonly className?: string;
+  readonly children?: ReactNode;
+}
+
+const StepperDescriptionComponent = forwardRef<Text, StepperDescriptionProps>(
+  ({ asChild, className, style, ...props }, ref) => {
+    const { orientation, labelPlacement } = useStepperStep();
+    const isCentered = getStepperLayout(orientation, labelPlacement) === 'horizontal-bottom';
+    const Comp = asChild ? Slot : Text;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(stepperDescriptionVariants({ isCentered }), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'stepper-description' }))}
+      />
+    );
+  },
+);
+
+StepperDescriptionComponent.displayName = 'Stepper.Description';
+
+// =============================================================================
+// CONTENT
+// =============================================================================
+
+export interface StepperContentProps extends ViewProps {
+  readonly asChild?: boolean;
+  readonly className?: string;
+}
+
+const StepperContentComponent = forwardRef<View, StepperContentProps>(
+  ({ asChild, className, style, ...props }, ref) => {
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(stepperContentVariants(), className)}
+        style={style}
+        {...props}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'stepper-content' }))}
+      />
+    );
+  },
+);
+
+StepperContentComponent.displayName = 'Stepper.Content';
+
+// =============================================================================
+// SEPARATOR
+// =============================================================================
+
+export interface StepperSeparatorProps extends ViewProps {
+  readonly asChild?: boolean;
+  readonly className?: string;
+}
+
+const StepperSeparatorComponent = forwardRef<View, StepperSeparatorProps>(
+  ({ asChild, className, style, ...props }, ref) => {
+    const { isLast, orientation, labelPlacement } = useStepperStep();
+
+    if (isLast) {
+      return null;
+    }
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(
+          stepperSeparatorVariants({ layout: getStepperLayout(orientation, labelPlacement) }),
+          className,
+        )}
+        style={style}
+        {...props}
+        {...HIDDEN_FROM_AT}
+        {...mergeDataAttributes(props, dataAttributes({ slot: 'stepper-separator' }))}
+      />
+    );
+  },
+);
+
+StepperSeparatorComponent.displayName = 'Stepper.Separator';
+
+// =============================================================================
+// COMPOUND EXPORT
+// =============================================================================
+
+type StepperCompoundComponent = typeof StepperRootComponent & {
+  Step: typeof StepperStepComponent;
+  Indicator: typeof StepperIndicatorComponent;
+  Title: typeof StepperTitleComponent;
+  Description: typeof StepperDescriptionComponent;
+  Content: typeof StepperContentComponent;
+  Separator: typeof StepperSeparatorComponent;
+};
+
+export const Stepper = Object.assign(StepperRootComponent, {
+  Step: StepperStepComponent,
+  Indicator: StepperIndicatorComponent,
+  Title: StepperTitleComponent,
+  Description: StepperDescriptionComponent,
+  Content: StepperContentComponent,
+  Separator: StepperSeparatorComponent,
+}) as StepperCompoundComponent;

package/src/components/Stepper/styles.ts

@@ -0,0 +1,234 @@
+import { Platform } from 'react-native';
+import type { StepperLabelPlacement, StepperOrientation } from '@cdx-ui/primitives';
+import { cva, type VariantProps } from '@cdx-ui/utils';
+import { TRANSITION_COLORS } from '../../styles/constants';
+
+/** Indicator frame in px. The ring is drawn at this size around the 24px disc. */
+export const STEPPER_INDICATOR_SIZE = 34;
+export const STEPPER_RING_STROKE_WIDTH = 3;
+
+export type StepperLayout = 'vertical' | 'horizontal-end' | 'horizontal-bottom';
+
+export function getStepperLayout(
+  orientation: StepperOrientation,
+  labelPlacement: StepperLabelPlacement,
+): StepperLayout {
+  if (orientation === 'vertical') {
+    return 'vertical';
+  }
+  return labelPlacement === 'bottom' ? 'horizontal-bottom' : 'horizontal-end';
+}
+
+// Horizontal layouts:
+// - `horizontal-end` (label after the indicator): steps start at their content width and every
+//   step but the last grows; that growth goes to its in-flow separator. With `labelFit: 'words'`
+//   (web, while the row fits) steps keep their min-content width so labels wrap between words;
+//   with `'shrink'` RN Web's `min-width: 0` lets them shrink further so the row never overflows.
+// - `horizontal-bottom` (label centered below): equal columns; the separator is absolute, so it
+//   never affects column layout.
+export const stepperVariants = cva([], {
+  variants: {
+    layout: {
+      vertical: 'flex-col',
+      'horizontal-end': 'w-full flex-row items-start',
+      'horizontal-bottom': 'w-full flex-row items-start',
+    },
+  },
+  defaultVariants: {
+    layout: 'vertical',
+  },
+});
+
+export const stepperStepVariants = cva([], {
+  variants: {
+    layout: {
+      vertical: 'flex-row',
+      'horizontal-end': 'min-w-0 flex-row items-start',
+      'horizontal-bottom': 'relative min-w-0 flex-1 basis-0 items-center',
+    },
+    isLast: {
+      true: '',
+      false: '',
+    },
+    labelFit: {
+      words: '',
+      shrink: '',
+    },
+  },
+  compoundVariants: [
+    { layout: 'horizontal-end', isLast: false, className: 'grow shrink basis-auto pe-2' },
+    { layout: 'horizontal-end', isLast: true, className: 'shrink' },
+    { layout: 'horizontal-end', labelFit: 'words', className: 'min-w-auto' },
+  ],
+  defaultVariants: {
+    layout: 'vertical',
+    isLast: false,
+    labelFit: 'shrink',
+  },
+});
+
+// Unexported layout wrappers inside `Stepper.Step` (no `data-slot`).
+export const stepperStepMainVariants = cva(['min-w-0'], {
+  variants: {
+    layout: {
+      vertical: 'flex-1',
+      'horizontal-end': 'shrink',
+      'horizontal-bottom': 'items-center self-stretch px-2',
+    },
+    labelFit: {
+      words: '',
+      shrink: '',
+    },
+  },
+  compoundVariants: [{ layout: 'horizontal-end', labelFit: 'words', className: 'min-w-auto' }],
+  defaultVariants: {
+    layout: 'vertical',
+    labelFit: 'shrink',
+  },
+});
+
+// Each layout pads the hover and press fill and cancels it with an equal negative margin, so a
+// step keeps its geometry when it becomes clickable. The 24px disc sits 5px inside its 34px
+// frame, so sides bounded by the disc get 4px and sides bounded by text get 9px; the fill then
+// looks evenly padded. Each layout aligns the trigger to its content (`self-start`, or
+// `self-center` under a centered label) so the fill hugs the indicator and label instead of
+// spanning the step. Hover, press and focus-visible use the `Tabs` hover tokens and the Forge
+// focus ring until the designer specifies clickable-step states.
+export const stepperStepTriggerVariants = cva(
+  [
+    'rounded-md',
+    TRANSITION_COLORS,
+    Platform.select({
+      default: 'data-[active=true]:bg-surface-secondary-active',
+      web: [
+        'outline-none data-[clickable=true]:cursor-pointer',
+        'data-[hover=true]:bg-surface-secondary-hover data-[active=true]:data-[hover=true]:bg-surface-secondary-active',
+        'web:data-[focus-visible=true]:ring-2 web:data-[focus-visible=true]:ring-stroke-focus web:data-[focus-visible=true]:ring-offset-2',
+      ].join(' '),
+    }),
+  ],
+  {
+    variants: {
+      layout: {
+        vertical: 'flex-row items-start self-start gap-2 -my-1 -ms-1 -me-[9px] py-1 ps-1 pe-[9px]',
+        'horizontal-end':
+          'flex-row items-start self-start gap-2 -my-1 -ms-1 -me-[9px] py-1 ps-1 pe-[9px]',
+        'horizontal-bottom':
+          'min-w-0 items-center self-center gap-1 -mx-[9px] -mt-1 -mb-[9px] px-[9px] pt-1 pb-[9px]',
+      },
+    },
+    defaultVariants: {
+      layout: 'vertical',
+    },
+  },
+);
+
+export const stepperStepLabelVariants = cva(['min-w-0'], {
+  variants: {
+    layout: {
+      vertical: 'shrink py-[7px]',
+      'horizontal-end': 'shrink py-[7px]',
+      'horizontal-bottom': 'self-stretch',
+    },
+    labelFit: {
+      words: '',
+      shrink: '',
+    },
+  },
+  compoundVariants: [{ layout: 'horizontal-end', labelFit: 'words', className: 'min-w-auto' }],
+  defaultVariants: {
+    layout: 'vertical',
+    labelFit: 'shrink',
+  },
+});
+
+export const stepperStepBodyVariants = cva([], {
+  variants: {
+    layout: {
+      vertical: 'ps-[42px]',
+      'horizontal-end': 'ps-[42px]',
+      'horizontal-bottom': 'self-stretch',
+    },
+  },
+  defaultVariants: {
+    layout: 'vertical',
+  },
+});
+
+// Indicator, disc, numeral and check each emit their own `data-current` because native
+// Uniwind cannot style a child from its parent's data attributes.
+export const stepperIndicatorVariants = cva([
+  'relative size-[34px] shrink-0 items-center justify-center',
+]);
+
+export const stepperIndicatorRingVariants = cva(['pointer-events-none absolute inset-0']);
+
+export const stepperIndicatorDiscVariants = cva([
+  'size-6 items-center justify-center rounded-full',
+  'bg-surface-neutral-strong data-[current=true]:bg-surface-brand-strong',
+]);
+
+export const stepperIndicatorNumeralVariants = cva([
+  'body-sm font-medium',
+  'text-content-neutral-on-strong data-[current=true]:text-content-brand-on-strong',
+]);
+
+export const stepperIndicatorCheckVariants = cva([
+  'size-7 text-content-neutral data-[current=true]:text-content-brand',
+]);
+
+// Native text alignment does not inherit from a parent `View`, so centered labels set it on
+// each text part.
+export const stepperTitleVariants = cva(
+  [
+    'body-md text-content-secondary',
+    'data-[current=true]:font-medium data-[current=true]:text-content-primary',
+  ],
+  {
+    variants: {
+      isCentered: {
+        true: 'text-center',
+        false: '',
+      },
+    },
+    defaultVariants: {
+      isCentered: false,
+    },
+  },
+);
+
+export const stepperDescriptionVariants = cva(['body-sm text-content-secondary'], {
+  variants: {
+    isCentered: {
+      true: 'text-center',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    isCentered: false,
+  },
+});
+
+export const stepperContentVariants = cva(['gap-2 py-2']);
+
+// Vertical: rendered before the step's main column with zero net width, centered under the
+// 34px frame; `self-stretch` follows the title and content.
+// `horizontal-end`: in flow after the label, centered on the frame's height; it takes the
+// step's growth, and the step's `pe-2` leaves 8px before the next indicator.
+// `horizontal-bottom`: absolute from this column's center to the next one's (columns are equal
+// and have no gap), inset 25px at each end: half the 34px frame plus 8px.
+// `z-10` keeps the line above a clickable trigger's hover and press fill.
+export const stepperSeparatorVariants = cva(['z-10 bg-stroke-secondary'], {
+  variants: {
+    layout: {
+      vertical: 'relative mt-[34px] min-h-6 w-px self-stretch ms-[16.5px] -me-[17.5px]',
+      'horizontal-end': 'relative mt-[16.5px] h-px min-w-6 flex-1 ms-2',
+      'horizontal-bottom': 'absolute top-[16.5px] start-[50%] end-[-50%] h-px ms-[25px] me-[25px]',
+    },
+  },
+  defaultVariants: {
+    layout: 'vertical',
+  },
+});
+
+export type StepperVariantProps = VariantProps<typeof stepperVariants>;

package/src/components/Stepper/useStepperLabelFit.ts

@@ -0,0 +1,21 @@
+import type { RefCallback } from 'react';
+import type { View } from 'react-native';
+
+/**
+ * How `horizontal-end` labels give way when the row runs out of room. `'words'` keeps each
+ * step at least as wide as its longest word, so labels wrap only between words; `'shrink'` lets
+ * steps shrink below that so the row never overflows.
+ */
+export type StepperLabelFit = 'words' | 'shrink';
+
+export interface StepperLabelFitResult {
+  readonly fit: StepperLabelFit;
+  readonly measureRef: RefCallback<View> | undefined;
+}
+
+const NATIVE_RESULT: StepperLabelFitResult = { fit: 'shrink', measureRef: undefined };
+
+/** Native layout has no min-content sizing, so steps always shrink to fit. */
+export function useStepperLabelFit(_enabled: boolean, _count: number): StepperLabelFitResult {
+  return NATIVE_RESULT;
+}