@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Stepper/Stepper.tsx

@@ -0,0 +1,258 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Stepper.tsx
+ * @input Uses React, stylex, theme tokens, StepperContext
+ * @output Exports Stepper component and StepperProps
+ * @position Core container component; consumed by index.ts
+ *
+ * Besides the props it is given, this component tracks the `activeStep` it
+ * last rendered with and publishes it on the context. Steps need the distance
+ * and direction of a change to choreograph their connector fill; see the
+ * CONNECTOR FILL block in Step.tsx.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Stepper/Stepper.doc.mjs (props table, features, implementation notes)
+ * - /packages/core/src/Stepper/Stepper.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Stepper/index.ts (exports if types change)
+ * - /apps/storybook/stories/Stepper.stories.tsx (storybook stories)
+ * - /packages/cli/assets/templates/blocks/components/Stepper/ (showcase blocks)
+ */
+
+import {useCallback, useMemo, useRef, useState, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import {spacingVars} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import type {BaseProps} from '../BaseProps';
+import {themeProps} from '../utils';
+import {useTranslator} from '../i18n';
+import {
+  StepperContext,
+  type StepperOrientation,
+  type StepperIndicatorPosition,
+  type StepperContextValue,
+} from './StepperContext';
+
+export interface StepperProps extends BaseProps<HTMLOListElement> {
+  /** Ref forwarded to the root element */
+  ref?: React.Ref<HTMLOListElement>;
+  /**
+   * Zero-based index of the active step.
+   */
+  activeStep: number;
+  /**
+   * Step elements to render.
+   */
+  children: ReactNode;
+  /**
+   * Layout direction of the stepper.
+   * @default 'horizontal'
+   */
+  orientation?: StepperOrientation;
+  /**
+   * Called when a step indicator is clicked. Enables non-linear navigation.
+   * When provided, completed and current steps become clickable.
+   */
+  onStepClick?: (index: number) => void;
+  /**
+   * Accessible label describing the set of steps. Defaults to a translated
+   * "Progress" when unset.
+   */
+  label?: string;
+  /**
+   * Controls density (padding) of all steps.
+   * @default 'balanced'
+   */
+  density?: 'compact' | 'balanced' | 'spacious';
+  /**
+   * Controls where each step's indicator sits relative to the connector track.
+   * - 'separated': indicator lives in the label row, distinct from the progress
+   *   bar (the original Astryx layout).
+   * - 'on-track': indicator is slotted into the connector line as a node on the
+   *   track (the on-track indicator design).
+   * @default 'separated'
+   */
+  indicatorPosition?: StepperIndicatorPosition;
+}
+
+const styles = stylex.create({
+  root: {
+    display: 'flex',
+    width: '100%',
+    listStyleType: 'none',
+    margin: 0,
+    padding: 0,
+  },
+  horizontal: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: spacingVars['--spacing-0-5'],
+  },
+  vertical: {
+    flexDirection: 'column',
+    gap: spacingVars['--spacing-0-5'],
+  },
+  // On-track: steps must abut so their connector segments form one continuous
+  // line, so the inter-step gap collapses to zero.
+  horizontalOnTrack: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: 0,
+  },
+  verticalOnTrack: {
+    flexDirection: 'column',
+    gap: 0,
+  },
+});
+
+/**
+ * A stepper component for multi-step workflows. Displays numbered steps
+ * with visual indicators for completed, active, and upcoming states.
+ *
+ * Each Step child must provide a `step` prop (zero-based index) so it
+ * can derive its state from the parent's activeStep. The on-track layout
+ * hides the leading connector on the first step and the trailing connector
+ * on the last step structurally, from each step's own `<li>` position, so
+ * it works regardless of how the steps are grouped.
+ *
+ * Rendered as an ordered list (`<ol>`/`<li>`) rather than a `nav`
+ * landmark: a stepper communicates *progress through a sequence*, not a
+ * set of site navigation links. The active step is marked with
+ * `aria-current="step"` (handled per-step) and the list carries an
+ * accessible `label`. This follows the WAI-ARIA pattern for steppers /
+ * progress sequences and avoids polluting the page's landmark map.
+ *
+ * @example
+ * ```
+ * <Stepper activeStep={1}>
+ *   <Step step={0} label="Account" />
+ *   <Step step={1} label="Profile" />
+ *   <Step step={2} label="Review" />
+ * </Stepper>
+ * ```
+ */
+export function Stepper({
+  activeStep,
+  children,
+  orientation = 'horizontal',
+  onStepClick,
+  label: labelFromProps,
+  density = 'balanced',
+  indicatorPosition = 'separated',
+  xstyle,
+  className,
+  style,
+  ref,
+  ...rest
+}: StepperProps) {
+  const t = useTranslator();
+  const label = labelFromProps ?? t('@astryx.stepper.label');
+
+  // Dev-mode duplicate step index detection. Steps register on mount and
+  // deregister on unmount; a Map tracks count per index so we can warn when
+  // two Steps share the same `step` value (which breaks aria-current).
+  const stepCountsRef = useRef<Map<number, number>>(new Map());
+  const registerStep = useCallback((index: number) => {
+    const counts = stepCountsRef.current;
+    const prev = counts.get(index) ?? 0;
+    counts.set(index, prev + 1);
+    if (process.env.NODE_ENV !== 'production' && prev + 1 > 1) {
+      console.warn(
+        `[Stepper] Duplicate step index ${index}: two <Step> elements share the same \`step\` value. ` +
+          `This breaks \`aria-current="step"\` and causes both to show as active simultaneously.`,
+      );
+    }
+    return () => {
+      const cur = counts.get(index) ?? 1;
+      if (cur <= 1) {
+        counts.delete(index);
+      } else {
+        counts.set(index, cur - 1);
+      }
+    };
+  }, []);
+
+  // The step we came *from*. Steps need it to stagger their connector fill:
+  // the distance and direction of the change decide which segment moves first
+  // and how long the whole sweep may take (see Step.tsx's CONNECTOR FILL).
+  //
+  // Derived during render from state rather than written in an effect. An
+  // effect runs after paint, so the browser would already have committed the
+  // new fill states with last render's delays — the first frame of the sweep
+  // would be wrong, and on a jump of one that is the entire animation. React
+  // discards and re-runs a render that sets its own state before committing,
+  // so this costs a re-render but never a wrong frame.
+  //
+  // Seeding both halves from the current `activeStep` is what suppresses the
+  // cascade on mount: a stepper that opens on step 3 has no previous step to
+  // have travelled from, so its completed segments paint filled at once. That
+  // also makes the first render pure and identical on the server, so there is
+  // nothing for hydration to disagree about. Storing the pair in one state
+  // object keeps the update idempotent under StrictMode's double render — both
+  // invocations read the same `seen` and queue the same successor.
+  const [seen, setSeen] = useState(() => ({
+    current: activeStep,
+    previous: activeStep,
+  }));
+  if (seen.current !== activeStep) {
+    setSeen({current: activeStep, previous: seen.current});
+  }
+  const previousActiveStep =
+    seen.current === activeStep ? seen.previous : seen.current;
+
+  const ctxValue = useMemo<StepperContextValue>(
+    () => ({
+      activeStep,
+      previousActiveStep,
+      orientation,
+      isNonLinear: onStepClick != null,
+      onStepClick: onStepClick ?? null,
+      density,
+      indicatorPosition,
+      registerStep,
+    }),
+    [
+      activeStep,
+      previousActiveStep,
+      orientation,
+      onStepClick,
+      density,
+      indicatorPosition,
+      registerStep,
+    ],
+  );
+
+  const isOnTrack = indicatorPosition === 'on-track';
+  const orientationStyle =
+    orientation === 'horizontal'
+      ? isOnTrack
+        ? styles.horizontalOnTrack
+        : styles.horizontal
+      : isOnTrack
+        ? styles.verticalOnTrack
+        : styles.vertical;
+
+  return (
+    <StepperContext value={ctxValue}>
+      <ol
+        ref={ref}
+        aria-label={label}
+        {...rest}
+        {...mergeProps(
+          themeProps('stepper', {orientation, indicatorPosition}),
+          stylex.props(styles.root, orientationStyle, xstyle),
+          className,
+          style,
+        )}>
+        {/* Each step renders its own progress bar segment; no child
+            introspection needed — steps derive state from context. */}
+        {children}
+      </ol>
+    </StepperContext>
+  );
+}
+
+Stepper.displayName = 'Stepper';

package/src/Stepper/StepperContext.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file StepperContext.ts
+ * @input Uses React createContext/use
+ * @output Exports StepperContext, useStepperContext, and context types
+ * @position Context for Stepper <-> Step communication
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Stepper/Stepper.doc.mjs
+ * - /packages/core/src/Stepper/index.ts
+ */
+
+import {createContext, use} from 'react';
+
+export type StepperOrientation = 'horizontal' | 'vertical';
+export type StepperDensity = 'compact' | 'balanced' | 'spacious';
+
+/**
+ * Controls where each step's indicator sits relative to the connector track.
+ * - 'separated': indicator lives in the label row, distinct from the progress
+ *   bar (Astryx's original layout).
+ * - 'on-track': indicator is slotted *into* the connector line as a node on the
+ *   track, with the label beside (vertical) or below (horizontal). Aligns with
+ *   the on-track stepper design.
+ */
+export type StepperIndicatorPosition = 'separated' | 'on-track';
+
+export interface StepperContextValue {
+  activeStep: number;
+  /**
+   * The `activeStep` this stepper last rendered with, so a Step can tell
+   * whether the change it is reacting to was a single step forward — the one
+   * change that animates the connector fill — and which span that change
+   * crossed (see the CONNECTOR FILL block in Step.tsx). Equal to `activeStep`
+   * on the first render, which is what keeps a stepper that mounts mid-flow
+   * from animating its way to the step it opened on.
+   *
+   * Internal: not part of the public API, and deliberately not a Stepper prop.
+   * When the connector animates is behaviour the stepper owns, not something a
+   * consumer configures.
+   */
+  previousActiveStep: number;
+  orientation: StepperOrientation;
+  isNonLinear: boolean;
+  onStepClick: ((index: number) => void) | null;
+  density: StepperDensity;
+  indicatorPosition: StepperIndicatorPosition;
+  /**
+   * Dev-mode index registration. Each Step calls this on mount with its `step`
+   * index. The Stepper tracks the set and warns if two Steps share the same
+   * index. Returns a cleanup function to call on unmount.
+   */
+  registerStep: (index: number) => () => void;
+}
+
+export const StepperContext = createContext<StepperContextValue | null>(null);
+StepperContext.displayName = 'StepperContext';
+
+export function useStepperContext(): StepperContextValue {
+  const ctx = use(StepperContext);
+  if (ctx == null) {
+    throw new Error(
+      'useStepperContext must be used within Stepper. ' +
+        'Wrap your Step in <Stepper>.',
+    );
+  }
+  return ctx;
+}

package/src/Stepper/index.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+export {Stepper} from './Stepper';
+export type {StepperProps} from './Stepper';
+
+export {Step} from './Step';
+export type {StepProps, StepIndicatorPreset} from './Step';
+
+export type {StepStatus} from './StepStatus';
+
+export {useStepperContext} from './StepperContext';
+export type {
+  StepperContextValue,
+  StepperOrientation,
+  StepperIndicatorPosition,
+} from './StepperContext';

package/src/Stepper/stepper.stylex.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file stepper.stylex.ts
+ * @input StyleX marker system
+ * @output stepMarker — a scoped marker applied to each Step's <li>
+ * @position Shared StyleX marker consumed by Step for structural selectors
+ *
+ * Applied to each Step's root `<li>` so the on-track connector segments can
+ * key their first/last-node visibility off `stylex.when.ancestor(':first-child'
+ * | ':last-child', stepMarker)` — matching only the parent step row, never the
+ * outer `<ol>`. This replaces counting children in the parent, so steps behave
+ * correctly regardless of how the consumer groups them (arrays, fragments).
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+export const stepMarker: ReturnType<typeof stylex.defineMarker> =
+  stylex.defineMarker();

package/src/Switch/Switch.doc.mjs

@@ -167,6 +167,7 @@ export const docs = {
         className: 'astryx-switch-field',
         visualProps: ['labelPosition', 'labelSpacing'],
       },
+      {className: 'astryx-switch-label'},
     ],
   },
   usage: {
@@ -338,6 +339,7 @@ export const docsZh = {
         className: 'astryx-switch-field',
         visualProps: ['labelPosition', 'labelSpacing'],
       },
+      {className: 'astryx-switch-label'},
     ],
   },
   usage: {

package/src/Switch/Switch.test.tsx

@@ -823,3 +823,13 @@ describe('forced colors (WCAG 1.4.11)', () => {
     expect(getForcedColorsRules()).not.toContain('color-mix');
   });
 });
+
+describe('label theme target', () => {
+  it('names its own label so a theme can style it apart from a field label', () => {
+    // See CheckboxInput: the control names the label it owns.
+    render(<Switch label="Wi-Fi" value={false} onChange={() => {}} />);
+    const label = screen.getByText('Wi-Fi').closest('label');
+    expect(label).toHaveClass('astryx-field-label');
+    expect(label).toHaveClass('astryx-switch-label');
+  });
+});

package/src/Switch/Switch.tsx

@@ -41,7 +41,7 @@ import type {IconType} from '../Icon';
 import type {InputStatus} from '../Field/types';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {switchScope} from './switch.markers.stylex';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -49,6 +49,7 @@ import {themeProps} from '../utils/themeProps';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const wrapperSizeStyles = stylex.create({
   sm: {
     width: 32,
@@ -551,7 +552,7 @@ export function Switch({
   const switchElement = (
     <div {...stylex.props(styles.switchWrapper, wrapperSizeStyles[size])}>
       <input
-        ref={mergeRefs(ref, disabledMessageTooltip.positionRef)}
+        ref={useMergedRefs(ref, disabledMessageTooltip.positionRef)}
         id={id}
         type="checkbox"
         role="switch"
@@ -632,6 +633,9 @@ export function Switch({
   const labelElement = (
     <div {...stylex.props(styles.labelWrapper, labelWrapperSizeStyles[size])}>
       <FieldLabel
+        // See CheckboxInput: the control names its own label target rather
+        // than the label guessing at its placement.
+        {...themeProps('switch-label')}
         label={label}
         inputID={id}
         isLabelHidden={isLabelHidden}

package/src/TabList/Tab.doc.mjs

@@ -40,7 +40,13 @@ export const docs = {
       name: 'href',
       type: 'string',
       description:
-        'URL to navigate to; when provided, the tab renders as an anchor element.',
+        'URL to navigate to; when provided, the tab renders as an anchor element. Ignored in a TabList given an explicit role="tablist".',
+    },
+    {
+      name: 'panelId',
+      type: 'string',
+      description:
+        'Id of the panel this tab controls, wired up as aria-controls where the TabList speaks the tabs pattern. Put the same id on the panel element. No effect under the navigation pattern, and a development warning says so.',
     },
     {
       name: 'as',
@@ -138,6 +144,12 @@ export const docsZh = {
       type: 'string',
       description: '要导航到的 URL；提供时，标签渲染为锚点元素。',
     },
+    {
+      name: 'panelId',
+      type: 'string',
+      description:
+        'Id of the panel this tab controls, wired up as aria-controls where the TabList speaks the tabs pattern. Put the same id on the panel element. No effect under the navigation pattern, and a development warning says so.',
+    },
     {
       name: 'as',
       type: 'LinkComponentType',

package/src/TabList/Tab.tsx

@@ -7,7 +7,8 @@
  * @input Uses React, StyleX, TabListContext
  * @output Exports Tab component and TabProps type
  * @position Core tab item; renders as button or anchor in navigation with a
- *   divider-overlay selected indicator
+ *   divider-overlay selected indicator. Where the TabList speaks the tabs
+ *   pattern it is a button with role="tab".
  *
  * SYNC: When modified, update:
  * - /packages/core/src/TabList/TabList.doc.mjs
@@ -35,6 +36,7 @@ import {tabScope} from './tab.markers.stylex';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {mergeProps} from '../utils';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {EDGE_COMP_ATTR} from '../Layout/edgeCompensation.stylex';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
@@ -64,8 +66,20 @@ export interface TabProps extends BaseProps<HTMLButtonElement> {
   isLabelHidden?: boolean;
   /**
    * URL to navigate to. When provided, renders as an anchor element.
+   *
+   * Ignored in a TabList given an explicit `role="tablist"`: activating a tab
+   * there swaps a panel in place, so a tab that navigates would be a false
+   * statement.
    */
   href?: string;
+  /**
+   * Id of the panel this tab controls, wired up as `aria-controls` where the
+   * TabList speaks the tabs pattern. Put the same id on the panel element.
+   *
+   * Has no effect under the navigation pattern, where there is no panel to
+   * associate — a development warning says so.
+   */
+  panelId?: string;
   /**
    * Icon element shown when tab is not selected.
    */
@@ -228,6 +242,7 @@ export function Tab({
   label,
   isLabelHidden = false,
   href,
+  panelId,
   icon,
   selectedIcon,
   endContent,
@@ -242,6 +257,9 @@ export function Tab({
   const isSelected = tabListCtx.value === value;
   const size: TabListSize = tabListCtx.size;
   const isFill = tabListCtx.layout === 'fill';
+  const isTabsPattern = tabListCtx.pattern === 'tabs';
+  const isLink = href != null && !isTabsPattern;
+  const isTabRole = isTabsPattern && !isLink;
   const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
   const hasVisibleLabel = !isLabelHidden && label !== '';
 
@@ -249,6 +267,34 @@ export function Tab({
     tabListCtx.onChange(value);
   }, [tabListCtx, value]);
 
+  useDevWarning(
+    'Tab',
+    'href is ignored in a role="tablist" TabList — a tab swaps a panel in ' +
+      'place rather than navigating. Drop the href, or drop the role for the ' +
+      'navigation pattern.',
+    isTabRole && href != null,
+  );
+
+  // A consumer who wired aria-controls by hand already said which panel this
+  // is, so panelId is the sugar, not the only way in.
+  const controls = panelId ?? restProps['aria-controls'];
+
+  useDevWarning(
+    'Tab',
+    'a tab in a role="tablist" TabList controls nothing: pass panelId with ' +
+      'the id of the panel it opens, so assistive technology can associate ' +
+      'the two.',
+    isTabRole && controls == null,
+  );
+
+  useDevWarning(
+    'Tab',
+    'panelId does nothing outside a role="tablist" TabList — the navigation ' +
+      'pattern has no panel to associate. Give the TabList role="tablist", ' +
+      'or drop the panelId.',
+    !isTabsPattern && panelId != null,
+  );
+
   const iconElement = displayIcon ? (
     <span {...stylex.props(styles.icon, iconSizeStyles[size])}>
       {displayIcon}
@@ -260,11 +306,25 @@ export function Tab({
     ...(isLabelHidden ? {'aria-label': label} : {}),
     [EDGE_COMP_ATTR]: '',
     'data-tab-value': value,
-    // Generic `true` ("the current item within a set"), not `page`: the strip
-    // switches views in place at least as often as it navigates, and claiming
-    // "current page" when no page changed is a false statement to a screen
-    // reader. Stays truthful for the `href` case too, just less specific.
-    'aria-current': isSelected ? ('true' as const) : undefined,
+    ...(isTabRole
+      ? {
+          role: 'tab' as const,
+          'aria-selected': isSelected,
+          // Only when there is a panel to point at: an aria-controls whose
+          // target does not exist is an invalid attribute value, which is a
+          // worse state than saying nothing. The dev warning above asks for
+          // the id instead.
+          'aria-controls': controls,
+        }
+      : {
+          // Generic `true` ("the current item within a set"), not `page`: the
+          // strip switches views in place at least as often as it navigates,
+          // and claiming "current page" when no page changed is a false
+          // statement to a screen reader. Stays truthful for the `href` case
+          // too, just less specific. A tab role states this with
+          // aria-selected instead.
+          'aria-current': isSelected ? ('true' as const) : undefined,
+        }),
     // Roving tabindex: the tab strip is a single Tab stop. The selected tab is
     // the tabbable one; the rest are reachable via arrow keys (handled by
     // TabList's onKeyDown). When no tab is selected, TabList's repair effect
@@ -321,7 +381,7 @@ export function Tab({
     <span {...stylex.props(styles.endContentWrapper)}>{endContent}</span>
   ) : null;
 
-  if (href != null) {
+  if (isLink) {
     return (
       <LinkComponent
         ref={ref}