@astryxdesign/core 0.4.6 → 0.4.7-canary.29be96d

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/TabList/Tab.tsx

@@ -260,7 +260,11 @@ export function Tab({
     ...(isLabelHidden ? {'aria-label': label} : {}),
     [EDGE_COMP_ATTR]: '',
     'data-tab-value': value,
-    'aria-current': isSelected ? ('page' as const) : undefined,
+    // 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,
     // 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

package/src/TabList/TabList.test.tsx

@@ -106,7 +106,7 @@ describe('TabList', () => {
     );
   });
 
-  it('marks selected tab with aria-current', () => {
+  it('marks selected tab with a generic aria-current, not "page"', () => {
     render(
       <TabList value="home" onChange={() => {}}>
         <Tab value="home" label="Home" />
@@ -116,13 +116,30 @@ describe('TabList', () => {
 
     expect(screen.getByRole('button', {name: 'Home'})).toHaveAttribute(
       'aria-current',
-      'page',
+      'true',
     );
     expect(screen.getByRole('button', {name: 'Settings'})).not.toHaveAttribute(
       'aria-current',
     );
   });
 
+  it('marks a selected link tab with the same generic aria-current', () => {
+    render(
+      <TabList value="home" onChange={() => {}}>
+        <Tab value="home" label="Home" href="/home" />
+        <Tab value="settings" label="Settings" href="/settings" />
+      </TabList>,
+    );
+
+    expect(screen.getByRole('link', {name: 'Home'})).toHaveAttribute(
+      'aria-current',
+      'true',
+    );
+    expect(screen.getByRole('link', {name: 'Settings'})).not.toHaveAttribute(
+      'aria-current',
+    );
+  });
+
   it('calls onChange when a tab is clicked', async () => {
     const user = userEvent.setup();
     const handleChange = vi.fn();
@@ -148,7 +165,7 @@ describe('TabList', () => {
 
     expect(screen.getByRole('button', {name: 'Home'})).toHaveAttribute(
       'aria-current',
-      'page',
+      'true',
     );
 
     rerender(
@@ -163,7 +180,7 @@ describe('TabList', () => {
     );
     expect(screen.getByRole('button', {name: 'Settings'})).toHaveAttribute(
       'aria-current',
-      'page',
+      'true',
     );
   });
 

package/src/Table/BaseTable.tsx

@@ -183,9 +183,12 @@ function TableRowInner<T extends Record<string, unknown>>({
     );
 
     const isDefaultRenderer = !col.renderCell;
-    const rawContent = isDefaultRenderer
-      ? defaultCellRenderer(item, col.key)
-      : (col.renderCell?.(item) ?? null);
+    let rawContent: ReactNode = null;
+    if (!cellRenderProps.isContentSuppressed) {
+      rawContent = isDefaultRenderer
+        ? defaultCellRenderer(item, col.key)
+        : (col.renderCell?.(item) ?? null);
+    }
 
     // In truncate mode, wrap default-rendered string content in
     // <Text maxLines={1}> for smart tooltips that only appear

package/src/Table/Table.test.tsx

@@ -602,6 +602,41 @@ describe('BaseTable', () => {
       expect(calls[0]).toEqual({col: 'name', name: 'Alice'});
     });
 
+    it('isContentSuppressed renders an empty cell and never calls the column renderer', () => {
+      const rendered: string[] = [];
+      const withRenderer: TableColumn<User>[] = [
+        {
+          key: 'name',
+          header: 'Name',
+          renderCell: item => {
+            rendered.push(item.name);
+            return <b>{item.name}</b>;
+          },
+        },
+      ];
+      const plugin: TablePlugin<User> = {
+        transformBodyCell: (props, _column, item) =>
+          item.name === 'Bob' ? {...props, isContentSuppressed: true} : props,
+      };
+      render(
+        <BaseTable data={users} columns={withRenderer} plugins={[plugin]} />,
+      );
+      expect(rendered).toEqual(['Alice', 'Charlie']);
+      const cells = screen.getAllByRole('cell');
+      expect(cells[1]).toBeEmptyDOMElement();
+      expect(cells[0]).toHaveTextContent('Alice');
+    });
+
+    it('isContentSuppressed also suppresses the default renderer', () => {
+      const plugin: TablePlugin<User> = {
+        transformBodyCell: props => ({...props, isContentSuppressed: true}),
+      };
+      render(<BaseTable data={users} columns={columns} plugins={[plugin]} />);
+      for (const cell of screen.getAllByRole('cell')) {
+        expect(cell).toBeEmptyDOMElement();
+      }
+    });
+
     it('composes multiple plugins sequentially', () => {
       const plugin1: TablePlugin<User> = {
         transformTable: props => ({

package/src/Table/plugins/groupedRows/useTableGroupedRows-perf.test.tsx

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useTableGroupedRows-perf.test.tsx
+ * @input Table, useTableGroupedRows, React testing utilities
+ * @output Performance tests for grouped-rows render behavior
+ * @position Test file; validates that grouping costs no extra row renders
+ *
+ * The plugin keeps group headers out of cell renderers per cell, at render
+ * time. Doing it by rewriting the columns instead would hand BaseTable a new
+ * column object on every render, and its element-by-element check on the
+ * resolved column array is what stops every row re-rendering.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, act} from '@testing-library/react';
+import {useCallback, useMemo, useState} from 'react';
+import userEvent from '@testing-library/user-event';
+import {Table} from '../../Table';
+import type {TableColumn} from '../../types';
+import {useTableGroupedRows} from './useTableGroupedRows';
+
+interface Person extends Record<string, unknown> {
+  id: string;
+  name: string;
+  team: string;
+}
+
+const people: Person[] = [
+  {id: 'a', name: 'Alice', team: 'Core'},
+  {id: 'b', name: 'Bob', team: 'Core'},
+  {id: 'c', name: 'Carol', team: 'Infra'},
+];
+
+const EMPTY = new Set<string>();
+
+function GroupedRenderCountTable({
+  renderCounts,
+}: {
+  renderCounts: Record<string, number>;
+}) {
+  const [tick, setTick] = useState(0);
+  const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(EMPTY);
+
+  const columns = useMemo<TableColumn<Person>[]>(
+    () => [
+      {
+        key: 'name',
+        header: 'Name',
+        renderCell: (item: Person) => {
+          renderCounts[item.id] = (renderCounts[item.id] ?? 0) + 1;
+          return item.name;
+        },
+      },
+    ],
+    [renderCounts],
+  );
+
+  const grouped = useTableGroupedRows<Person>({
+    data: people,
+    groupBy: useCallback((p: Person) => p.team, []),
+    collapsedGroups,
+    onToggleGroup: useCallback(
+      (key: string) =>
+        setCollapsedGroups(prev => {
+          const next = new Set(prev);
+          if (!next.delete(key)) {
+            next.add(key);
+          }
+          return next;
+        }),
+      [],
+    ),
+    getRowKey: useCallback((p: Person) => p.id, []),
+  });
+
+  return (
+    <>
+      <button type="button" onClick={() => setTick(t => t + 1)}>
+        bump {tick}
+      </button>
+      <Table
+        data={grouped.data}
+        columns={columns}
+        idKey={grouped.idKey}
+        plugins={{grouped: grouped.plugin}}
+      />
+    </>
+  );
+}
+
+describe('Grouped rows render performance', () => {
+  it('renders each real row once and no group header at all', () => {
+    const renderCounts: Record<string, number> = {};
+    render(<GroupedRenderCountTable renderCounts={renderCounts} />);
+    expect(renderCounts).toEqual({a: 1, b: 1, c: 1});
+  });
+
+  it('a re-render of the surrounding component re-renders no rows', async () => {
+    const user = userEvent.setup();
+    const renderCounts: Record<string, number> = {};
+    render(<GroupedRenderCountTable renderCounts={renderCounts} />);
+    const before = {...renderCounts};
+
+    await act(async () => {
+      await user.click(screen.getByRole('button', {name: /bump/}));
+    });
+
+    expect(screen.getByRole('button', {name: 'bump 1'})).toBeInTheDocument();
+    expect(renderCounts).toEqual(before);
+  });
+});