@cdx-ui/primitives 0.3.4 → 0.3.6

package/src/stepper/StepperStepTrigger.tsx

@@ -0,0 +1,38 @@
+import { forwardRef, type ComponentRef } from 'react';
+import { View } from 'react-native';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { useStepperContext, useStepperStep } from './context';
+import { StepperStepPressable } from './StepperStepPressable';
+import type { IStepperStepTriggerProps } from './types';
+
+/**
+ * Internal step region that carries the step's accessible name: the grouped visible
+ * content (indicator, title, description) followed by the state phrase. It becomes a
+ * `button` while the step is clickable. Not a public styled part; the styled
+ * `Stepper.Step` renders it around those slots.
+ */
+export const StepperStepTrigger = forwardRef<ComponentRef<typeof View>, IStepperStepTriggerProps>(
+  ({ children, ...props }, ref) => {
+    const state = useStepperStep();
+    const { getStepAccessibilityText } = useStepperContext();
+    const phrase = getStepAccessibilityText(state);
+    const Comp = state.isClickable ? StepperStepPressable : View;
+
+    return (
+      <Comp
+        ref={ref}
+        accessible
+        accessibilityValue={phrase ? { text: phrase } : undefined}
+        {...props}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({ clickable: state.isClickable, disabled: state.isDisabled }),
+        )}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+StepperStepTrigger.displayName = 'StepperStepTrigger';

package/src/stepper/StepperStepTrigger.web.tsx

@@ -0,0 +1,69 @@
+import { forwardRef, useLayoutEffect, useMemo, useRef, type ComponentRef } from 'react';
+import { View } from 'react-native';
+import { VisuallyHidden } from '@react-aria/visually-hidden';
+import { composeEventHandlers, mergeRefs } from '@cdx-ui/utils';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { useStepperContext, useStepperStep } from './context';
+import { StepperStepPressable } from './StepperStepPressable';
+import type { IStepperStepTriggerProps } from './types';
+
+/**
+ * Internal step region that carries the step's accessible name. On web the state phrase
+ * is screen-reader-only text after the visible content, because browse-mode screen
+ * readers ignore `aria-label` on a list item. It becomes a `button` while the step is
+ * clickable. Not a public styled part.
+ */
+export const StepperStepTrigger = forwardRef<ComponentRef<typeof View>, IStepperStepTriggerProps>(
+  ({ children, ...props }, ref) => {
+    const state = useStepperStep();
+    const { getStepAccessibilityText } = useStepperContext();
+    const phrase = getStepAccessibilityText(state);
+    const Comp = state.isClickable ? StepperStepPressable : View;
+
+    const nodeRef = useRef<ComponentRef<typeof View> | null>(null);
+    const mergedRef = useMemo(() => mergeRefs(ref, nodeRef), [ref]);
+    // Activating a step makes it current, which swaps the focused button for a plain region
+    // and would drop focus to the document. Focus moves to that region instead, outside the
+    // Tab order.
+    const restoreFocusRef = useRef(false);
+
+    useLayoutEffect(() => {
+      const node = nodeRef.current as unknown as HTMLElement | null;
+      if (!restoreFocusRef.current || state.isClickable || node === null) {
+        return;
+      }
+      restoreFocusRef.current = false;
+      node.tabIndex = -1;
+      node.focus({ preventScroll: true });
+    }, [state.isClickable]);
+
+    const pressProps = state.isClickable
+      ? {
+          onPress: () => {
+            restoreFocusRef.current =
+              document.activeElement === (nodeRef.current as unknown as HTMLElement | null);
+          },
+          onBlur: composeEventHandlers(props.onBlur, () => {
+            restoreFocusRef.current = false;
+          }),
+        }
+      : {};
+
+    return (
+      <Comp
+        ref={mergedRef}
+        {...props}
+        {...pressProps}
+        {...mergeDataAttributes(
+          props,
+          dataAttributes({ clickable: state.isClickable, disabled: state.isDisabled }),
+        )}
+      >
+        {children}
+        {phrase ? <VisuallyHidden elementType="span">{`, ${phrase}`}</VisuallyHidden> : null}
+      </Comp>
+    );
+  },
+);
+
+StepperStepTrigger.displayName = 'StepperStepTrigger';

package/src/stepper/context.tsx

@@ -0,0 +1,11 @@
+import { createContext } from '@cdx-ui/utils';
+import type { StepperContextValue, StepperStepState } from './types';
+
+export const [StepperProvider, useStepperContext] =
+  createContext<StepperContextValue>('StepperContext');
+
+/** Position of a direct child of `StepperRoot`, supplied by the root while it renders. */
+export const [StepperIndexProvider, useStepperIndex] = createContext<number>('StepperIndex');
+
+/** Resolved state of the enclosing step. `useStepperStep` throws outside a `StepperStep`. */
+export const [StepperStepProvider, useStepperStep] = createContext<StepperStepState>('StepperStep');

package/src/stepper/index.ts

@@ -0,0 +1,16 @@
+export type {
+  IStepperProps,
+  IStepperStepProps,
+  IStepperStepTriggerProps,
+  InterfaceStepperProps,
+  InterfaceStepperStepProps,
+  StepperContextValue,
+  StepperLabelPlacement,
+  StepperOrientation,
+  StepperStepState,
+} from './types';
+
+export { useStepperContext, useStepperIndex, useStepperStep } from './context';
+export { StepperRoot, type StepperRootProps } from './StepperRoot';
+export { StepperStep, type StepperStepProps } from './StepperStep';
+export { StepperStepTrigger } from './StepperStepTrigger';

package/src/stepper/types.ts

@@ -0,0 +1,104 @@
+import type { ViewProps } from 'react-native';
+
+export type StepperOrientation = 'horizontal' | 'vertical';
+
+export type StepperLabelPlacement = 'end' | 'bottom';
+
+export interface StepperStepState {
+  /** Zero-based position among the steps. */
+  readonly index: number;
+  /** Number of steps rendered. */
+  readonly count: number;
+  readonly isCurrent: boolean;
+  /** Resolved completion: the explicit `isComplete`, or `index < currentStep`. */
+  readonly isComplete: boolean;
+  /** Clamped to 0–100. Non-finite values are 0. */
+  readonly progress: number;
+  /** True when the partial ring is drawn: `0 < progress` and not complete. */
+  readonly hasProgress: boolean;
+  readonly isLast: boolean;
+  /** True when the step renders as a button. */
+  readonly isClickable: boolean;
+  readonly isDisabled: boolean;
+  readonly orientation: StepperOrientation;
+  readonly labelPlacement: StepperLabelPlacement;
+}
+
+export interface InterfaceStepperProps extends ViewProps {
+  /**
+   * Controlled, zero-based current step. A value outside `0…count-1` means no step is
+   * current; a value `>= count` makes every step complete by default.
+   */
+  readonly currentStep?: number;
+  /**
+   * Uncontrolled starting step. Ignored when `currentStep` is set.
+   * @default 0
+   */
+  readonly defaultStep?: number;
+  /** Called with the pressed step's index. Setting it makes eligible steps clickable. */
+  readonly onStepChange?: (index: number) => void;
+  /**
+   * When `true`, only complete steps are clickable. When `false`, every non-current,
+   * non-disabled step is.
+   * @default true
+   */
+  readonly isLinear?: boolean;
+  /**
+   * `'horizontal'` lays the steps out in a row. `labelPlacement` chooses where each label sits.
+   * @default 'vertical'
+   */
+  readonly orientation?: StepperOrientation;
+  /**
+   * Horizontal only; ignored when `orientation` is `'vertical'`. `'end'` puts each label after
+   * its indicator, sizes steps to their labels and stretches the separators between them.
+   * `'bottom'` gives every step an equal column with the indicator and label centered.
+   * @default 'end'
+   */
+  readonly labelPlacement?: StepperLabelPlacement;
+  /**
+   * Returns the state phrase appended to each step's title for assistive technology,
+   * replacing the English default (for example `"current step, 40% complete"`).
+   */
+  readonly getStepAccessibilityText?: (state: StepperStepState) => string;
+  /** @default false */
+  readonly asChild?: boolean;
+}
+
+export type IStepperProps = InterfaceStepperProps;
+
+export interface InterfaceStepperStepProps extends ViewProps {
+  /**
+   * Whether the step is complete. An explicit value wins in both directions.
+   * @default index < currentStep
+   */
+  readonly isComplete?: boolean;
+  /**
+   * Partial progress, 0–100. Values outside the range are clamped; non-finite values are `0`.
+   * @default 0
+   */
+  readonly progress?: number;
+  /**
+   * Only affects clickability. A disabled step still shows its state.
+   * @default false
+   */
+  readonly isDisabled?: boolean;
+  /** @default false */
+  readonly asChild?: boolean;
+}
+
+export type IStepperStepProps = InterfaceStepperStepProps;
+
+export type IStepperStepTriggerProps = ViewProps;
+
+export interface StepperContextValue {
+  /** Resolved current step (controlled or uncontrolled). */
+  readonly currentStep: number;
+  readonly count: number;
+  readonly orientation: StepperOrientation;
+  readonly labelPlacement: StepperLabelPlacement;
+  readonly isLinear: boolean;
+  /** True when the consumer passed `onStepChange`. */
+  readonly hasStepChangeHandler: boolean;
+  readonly setCurrentStep: (index: number) => void;
+  readonly getStepAccessibilityText: (state: StepperStepState) => string;
+}