@multiplatform.one/components 6.7.0 → 7.0.0

package/src/ProgressSteps/ProgressSteps.spec.tsx

@@ -52,11 +52,31 @@ describe("ProgressSteps", () => {
     expect(current.className).toContain("_bg-accentBackg");
   });
 
-  it("calls onStepChange when jumping to another step", () => {
+  it("calls onStepChange when jumping back to a completed step", () => {
+    const onStepChange = vi.fn();
+    const { container } = renderWithProviders(
+      <ProgressSteps steps={steps} current={1} onStepChange={onStepChange} />,
+    );
+    const jump = container.querySelector('[aria-label="Go to step 1: One"]');
+    expect(jump).toBeTruthy();
+    fireEvent.click(jump as Element);
+    expect(onStepChange).toHaveBeenCalledWith(0);
+  });
+
+  it("keeps upcoming steps inert when linear", () => {
     const onStepChange = vi.fn();
     const { container } = renderWithProviders(
       <ProgressSteps steps={steps} current={0} onStepChange={onStepChange} />,
     );
+    expect(container.querySelector('[aria-label="Go to step 2: Two"]')).toBeFalsy();
+    expect(onStepChange).not.toHaveBeenCalled();
+  });
+
+  it("jumps to upcoming steps when linear is false", () => {
+    const onStepChange = vi.fn();
+    const { container } = renderWithProviders(
+      <ProgressSteps steps={steps} current={0} linear={false} onStepChange={onStepChange} />,
+    );
     const jump = container.querySelector('[aria-label="Go to step 2: Two"]');
     expect(jump).toBeTruthy();
     fireEvent.click(jump as Element);
@@ -67,4 +87,31 @@ describe("ProgressSteps", () => {
     const { container } = renderWithProviders(<ProgressSteps steps={steps} current={0} />);
     expect(container.querySelector('[aria-label="Go to step 2: Two"]')).toBeFalsy();
   });
+
+  it("paints markers at nestedControl size, not the 44px press floor", () => {
+    const { container } = renderWithProviders(<ProgressSteps steps={steps} current={1} />);
+    const marker = container.querySelector("[data-nested-px]") as HTMLElement;
+    expect(marker).toBeTruthy();
+    expect(marker.getAttribute("data-nested-px")).toBe("32");
+    const target = container.querySelector("[data-press-min]") as HTMLElement;
+    expect(target.getAttribute("data-press-min")).toBe("44");
+  });
+
+  it("steps nested marker size down under compact density", () => {
+    const { container } = renderWithProviders(<ProgressSteps steps={steps} current={0} compact />);
+    const marker = container.querySelector("[data-nested-px]") as HTMLElement;
+    expect(marker.getAttribute("data-nested-px")).toBe("28");
+  });
+
+  it("flags an error step on the marker", () => {
+    const { container } = renderWithProviders(
+      <ProgressSteps
+        steps={[{ label: "One" }, { label: "Two", error: true, description: "Fix this" }]}
+        current={1}
+      />,
+    );
+    const marker = container.querySelector('[data-step-state="error"]');
+    expect(marker).toBeTruthy();
+    expect(container.textContent).toContain("Fix this");
+  });
 });

package/src/ProgressSteps/ProgressSteps.stories.tsx

@@ -21,6 +21,7 @@ const meta: Meta<typeof ProgressSteps> = {
     orientation: { control: "select", options: ["horizontal", "vertical"] },
     compact: { control: "boolean" },
     allowJump: { control: "boolean" },
+    linear: { control: "boolean" },
   },
 };
 export default meta;
@@ -46,6 +47,8 @@ export const Interactive: Story = {
   render: () => {
     // Rest mid-range: at step 0 the Back button is bare-disabled at rest
     // (UX-P19 / DG-ST-03) and demos nothing; step 0 stays one click away.
+    // Linear (Material / Orbit): completed steps jump back; Next is the
+    // only way forward.
     const [current, setCurrent] = useState(1);
     return (
       <YStack gap="$4" maxWidth={720}>
@@ -87,3 +90,48 @@ export const Compact: Story = {
     compact: true,
   },
 };
+
+export const Error: Story = {
+  args: {
+    steps: [
+      { id: "account", label: "Account", description: "Email & password" },
+      {
+        id: "profile",
+        label: "Profile",
+        description: "Name is required",
+        error: true,
+      },
+      { id: "team", label: "Team", description: "Invite coworkers" },
+      { id: "done", label: "Done", description: "Review & finish" },
+    ],
+    current: 1,
+  },
+};
+
+export const Optional: Story = {
+  args: {
+    steps: [
+      { id: "account", label: "Account", description: "Email & password" },
+      { id: "profile", label: "Profile", optional: true },
+      { id: "team", label: "Team", description: "Invite coworkers" },
+      { id: "done", label: "Done" },
+    ],
+    current: 1,
+  },
+};
+
+export const NonLinear: Story = {
+  render: () => {
+    const [current, setCurrent] = useState(1);
+    return (
+      <YStack gap="$4" maxWidth={720}>
+        <ProgressSteps
+          steps={demoSteps}
+          current={current}
+          linear={false}
+          onStepChange={setCurrent}
+        />
+      </YStack>
+    );
+  },
+};

package/src/ProgressSteps/index.tsx

@@ -1,9 +1,16 @@
-import { CheckIcon } from "@phosphor-icons/react";
-import { useReadableTextOn, useResolvedKnobs } from "@multiplatform.one/theme";
-import { useTranslation } from "react-i18next";
-import type { ReactNode } from "react";
+import { CheckIcon, WarningIcon } from "@phosphor-icons/react";
+import {
+  MIN_PRESS_TARGET,
+  ensureKeyboardModalityTracking,
+  pressTargetHitSlop,
+  useReadableTextOn,
+  useResolvedKnobs,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
+import { useState, type ReactNode } from "react";
+import { useTranslation } from "../shared/i18n";
 import type { GetProps } from "tamagui";
-import { SizableText, View, XStack, YStack, styled } from "tamagui";
+import { SizableText, View, XStack, YStack, isWeb, styled } from "tamagui";
 import { componentColors } from "../componentColors";
 import { withInterp } from "../shared/t";
 
@@ -14,12 +21,16 @@ export interface ProgressStep {
   id?: string;
   /** Step label shown under / beside the marker. */
   label: ReactNode;
-  /** Optional secondary line. */
+  /** Optional secondary line (Carbon helper / Material subtitle). */
   description?: ReactNode;
   /** Force completed even when index >= current. */
   completed?: boolean;
   /** Disable jump-to for this step. */
   disabled?: boolean;
+  /** Carbon/Material error: invalid or incomplete step. */
+  error?: boolean;
+  /** Material optional: helper reads "Optional" when no description is set. */
+  optional?: boolean;
 }
 
 export interface ProgressStepsProps extends Omit<GetProps<typeof StepsRoot>, "children"> {
@@ -31,32 +42,21 @@ export interface ProgressStepsProps extends Omit<GetProps<typeof StepsRoot>, "ch
   onStepChange?: (index: number) => void;
   /** Orientation. @default "horizontal" */
   orientation?: "horizontal" | "vertical";
-  /** Allow clicking completed / upcoming steps when onStepChange is set. */
+  /** Allow clicking steps when onStepChange is set. @default true */
   allowJump?: boolean;
-  /** Compact markers + type. */
+  /**
+   * Material linear / Orbit wizard: only completed steps are jump targets.
+   * Upcoming stays inert — Next on the page is the only way forward.
+   * Set false for Carbon non-linear / Material non-linear.
+   * @default true
+   */
+  linear?: boolean;
+  /** Compact markers + type (density compact override). */
   compact?: boolean;
 }
 
 type StepState = "completed" | "current" | "upcoming";
-
-// ── Knob-derived geometry ─────────────────────────────────────
-// Markers are R-PILL (always circles); their diameter, glyph, and type scale
-// with the size knob (LC-18; Pagination-indicator class). The `compact` prop
-// steps the resolved sizeToken down via useResolvedKnobs, so medium+compact
-// lands on the old 22px marker.
-
-const markerSizeMap: Record<string, number> = { $3: 22, $4: 28, $5: 34 };
-const markerIconSizeMap: Record<string, number> = { $3: 12, $4: 14, $5: 16 };
-const markerTextSizeMap: Record<string, string> = { $3: "$1", $4: "$2", $5: "$3" };
-const labelSizeMap: Record<string, string> = { $3: "$2", $4: "$3", $5: "$4" };
-
-// space→gap map in the house helper pattern (getTableCellPadding precedent):
-// medium equals the previous hardcoded values so default density is unchanged.
-const stepGapMap: Record<string, { step: string; markerLabel: string }> = {
-  small: { step: "$1.5", markerLabel: "$2" },
-  medium: { step: "$2", markerLabel: "$3" },
-  large: { step: "$3", markerLabel: "$4" },
-};
+type MarkerKind = StepState | "error";
 
 // ── Styled ────────────────────────────────────────────────────
 
@@ -73,6 +73,22 @@ const Marker = styled(View, {
   flexShrink: 0,
 });
 
+const StepButton = styled(View, {
+  name: "ProgressStepButton",
+  backgroundColor: "transparent",
+  borderWidth: 0,
+  cursor: "pointer",
+  // LC-71: the button is the hit target; the ring lives on the marker.
+  outlineWidth: 0,
+  focusStyle: { outlineWidth: 0, outlineStyle: "none" as any },
+  focusVisibleStyle: { outlineWidth: 0, outlineStyle: "none" as any },
+});
+
+const Connector = styled(View, {
+  name: "ProgressStepConnector",
+  flexShrink: 0,
+});
+
 // ── Helpers ───────────────────────────────────────────────────
 
 function stepState(index: number, current: number, forcedCompleted?: boolean): StepState {
@@ -81,12 +97,30 @@ function stepState(index: number, current: number, forcedCompleted?: boolean): S
   return "upcoming";
 }
 
+function splitNestedControl(nested: {
+  px: number;
+  hitSlop: { top: number; bottom: number; left: number; right: number };
+  width: number;
+  height: number;
+  minWidth: number;
+  maxWidth: number;
+  minHeight: number;
+  maxHeight: number;
+}) {
+  const { px, hitSlop, ...box } = nested;
+  return { px, hitSlop, box };
+}
+
 // ── Component ─────────────────────────────────────────────────
 
 /**
  * Multi-step wizard / progress indicator (gallery: Progress indicator /
  * Stepper / Steps). Distinct from forms Progress (continuous bar) and
  * forms Stepper (quantity nudger). Timeline covers the chronological alias.
+ *
+ * Carbon ProgressIndicator + Material Stepper: numbered/check markers,
+ * helper text, error/optional, linear-by-default. Polaris has no wizard
+ * stepper — display-only when `onStepChange` is omitted.
  */
 export function ProgressSteps({
   steps,
@@ -94,67 +128,102 @@ export function ProgressSteps({
   onStepChange,
   orientation = "horizontal",
   allowJump = true,
+  linear = true,
   compact = false,
   ...props
 }: ProgressStepsProps) {
   const { t } = useTranslation();
-  const { knobProps } = useResolvedKnobs({ component: "ProgressSteps", compact });
-  // LC-05: the current marker rides the accent fill, so its step number takes
-  // the luminance-computed paper/ink anchor rather than an assumed `$color1`.
+  const { knobProps, control, disabledState } = useResolvedKnobs({
+    component: "ProgressSteps",
+    compact,
+  });
+  if (isWeb) ensureKeyboardModalityTracking();
+  const [kbFocusIndex, setKbFocusIndex] = useState<number | null>(null);
+  // LC-05: current marker rides the accent fill; completed/error fills pick
+  // paper/ink from luminance rather than an assumed white glyph.
   const onSelected = useReadableTextOn(componentColors.indicator.selected);
-  const markerSize = markerSizeMap[knobProps.sizeToken] ?? 28;
-  const markerIconSize = markerIconSizeMap[knobProps.sizeToken] ?? 14;
-  const markerTextSize = markerTextSizeMap[knobProps.sizeToken] ?? "$2";
-  const labelSize = labelSizeMap[knobProps.sizeToken] ?? "$3";
-  const gaps = stepGapMap[knobProps.space] ?? stepGapMap.medium;
-  // R-BINARY (Axiom 3 NULL): the step marker is a round mode-mark like a radio
-  // dot — square in the `none` world, a full circle at every other value. The
-  // fixed 1000 arc was knob-dead, an undeclared knob-immune shape the old
-  // geometric sweep read as an identity circle (D-09 / LC-60).
+  const onCompleted = useReadableTextOn(componentColors.indicator.completed);
+  const onError = useReadableTextOn("$red9");
+  const { px: markerPx, hitSlop, box: nestedBox } = splitNestedControl(knobProps.nestedControl);
+  const markerIconSize = Math.max(12, Math.round(markerPx * 0.45));
   const markerRadius = knobProps.pointy ? 0 : 1000;
   const connectorThickness = 2;
+  const pressOutset = Math.max(0, Math.ceil((MIN_PRESS_TARGET - markerPx) / 2));
   const interactive = !!onStepChange && allowJump;
   const horizontal = orientation === "horizontal";
+  const gapToken = knobProps.gap.gap;
 
   return (
-    <StepsRoot role="list" aria-label={t("Progress")} {...props}>
+    <StepsRoot role="list" aria-label={t("Progress")} data-density={knobProps.density} {...props}>
       <XStack
         flexDirection={horizontal ? "row" : "column"}
         alignItems={horizontal ? "flex-start" : "stretch"}
         width="100%"
-        gap={horizontal ? 0 : (gaps.step as any)}
+        gap={horizontal ? 0 : gapToken}
       >
         {steps.map((step, index) => {
           const state = stepState(index, current, step.completed);
+          const kind: MarkerKind = step.error ? "error" : state;
           const isLast = index === steps.length - 1;
-          const canActivate = interactive && !step.disabled && state !== "current";
+          const canActivate =
+            interactive &&
+            !step.disabled &&
+            state !== "current" &&
+            (state === "completed" || !linear);
+          const isFocusable = interactive && !step.disabled && (canActivate || state === "current");
           const markerBg =
-            state === "completed"
-              ? componentColors.indicator.completed
-              : state === "current"
-                ? componentColors.indicator.selected
-                : componentColors.interactive.background;
-          const markerBorder = state === "upcoming" ? componentColors.indicator.track : markerBg;
-          const markerFg = state === "upcoming" ? componentColors.text.muted : "$color1";
+            kind === "error"
+              ? "$red9"
+              : kind === "completed"
+                ? componentColors.indicator.completed
+                : kind === "current"
+                  ? componentColors.indicator.selected
+                  : "transparent";
+          const markerBorder = kind === "upcoming" ? componentColors.indicator.track : markerBg;
+          const markerFg =
+            kind === "upcoming"
+              ? componentColors.text.muted
+              : kind === "error"
+                ? (onError ?? "$color1")
+                : kind === "completed"
+                  ? (onCompleted ?? "$color1")
+                  : (onSelected ?? "$color1");
+          const helper =
+            step.description ?? (step.optional && kind !== "error" ? t("Optional") : null);
+          const connectorFill =
+            index < current ? componentColors.indicator.completed : componentColors.indicator.track;
 
           const marker = (
             <Marker
-              width={markerSize}
-              height={markerSize}
+              {...nestedBox}
               borderRadius={markerRadius}
               backgroundColor={markerBg}
               borderColor={markerBorder}
+              data-nested-px={markerPx}
+              data-step-state={kind}
+              transition={knobProps.transition}
               {...(state === "current"
                 ? ({ "aria-current": "step" } as Record<string, unknown>)
                 : undefined)}
+              {...(kbFocusIndex === index ? control.focusVisibleKnobProps : { outlineWidth: 0 })}
+              {...(kind === "upcoming"
+                ? {
+                    hoverStyle: {
+                      borderColor: componentColors.indicator.hover,
+                      backgroundColor: componentColors.indicator.inactive,
+                    },
+                  }
+                : undefined)}
             >
-              {state === "completed" ? (
-                <CheckIcon size={markerIconSize} color="white" weight="bold" />
+              {kind === "error" ? (
+                <WarningIcon size={markerIconSize} color={markerFg} weight="bold" />
+              ) : kind === "completed" ? (
+                <CheckIcon size={markerIconSize} color={markerFg} weight="bold" />
               ) : (
                 <SizableText
-                  fontSize={markerTextSize as any}
+                  {...knobProps.label}
                   fontWeight="600"
-                  color={state === "current" ? (onSelected ?? "$color1") : markerFg}
+                  color={kind === "current" ? (onSelected ?? "$color1") : markerFg}
                 >
                   {index + 1}
                 </SizableText>
@@ -162,121 +231,143 @@ export function ProgressSteps({
             </Marker>
           );
 
+          const markerTarget = (
+            <View
+              width={MIN_PRESS_TARGET}
+              height={MIN_PRESS_TARGET}
+              minWidth={MIN_PRESS_TARGET}
+              minHeight={MIN_PRESS_TARGET}
+              marginVertical={-pressOutset}
+              marginHorizontal={horizontal ? -pressOutset : 0}
+              alignItems="center"
+              justifyContent="center"
+              data-press-min={MIN_PRESS_TARGET}
+              hitSlop={hitSlop ?? pressTargetHitSlop(markerPx)}
+            >
+              {marker}
+            </View>
+          );
+
           const labelBlock = (
             <YStack
               gap="$0.5"
               flexShrink={1}
               {...(horizontal
-                ? { alignItems: "center", marginTop: gaps.step as any, maxWidth: 140 }
+                ? { alignItems: "center", marginTop: gapToken, maxWidth: 160 }
                 : { flexGrow: 1, justifyContent: "center" })}
             >
               <SizableText
                 {...knobProps.body}
-                fontSize={labelSize as any}
-                fontWeight={state === "current" ? "600" : "500"}
+                {...knobProps.label}
+                fontWeight={state === "current" ? "600" : knobProps.body.fontWeight}
                 color={
-                  state === "upcoming" ? componentColors.text.muted : componentColors.text.primary
+                  kind === "error"
+                    ? "$red11"
+                    : state === "upcoming"
+                      ? componentColors.text.muted
+                      : componentColors.text.primary
                 }
-                // undefined = natural start alignment, so vertical labels mirror in RTL
                 textAlign={horizontal ? "center" : undefined}
+                numberOfLines={2}
               >
                 {step.label}
               </SizableText>
-              {step.description != null ? (
+              {helper != null ? (
                 <SizableText
+                  {...knobProps.body}
                   fontSize="$1"
-                  color={componentColors.text.muted}
+                  color={kind === "error" ? "$red11" : componentColors.text.muted}
                   textAlign={horizontal ? "center" : undefined}
+                  numberOfLines={2}
                 >
-                  {step.description}
+                  {helper}
                 </SizableText>
               ) : null}
             </YStack>
           );
 
-          const connector =
-            !isLast && horizontal ? (
-              <View
-                flexGrow={1}
-                height={connectorThickness}
-                backgroundColor={
-                  index < current
-                    ? componentColors.indicator.completed
-                    : componentColors.indicator.track
-                }
-                marginTop={(markerSize - connectorThickness) / 2}
-                marginHorizontal={gaps.step as any}
-                minWidth={16}
-              />
-            ) : !isLast && !horizontal ? (
-              <View
-                width={connectorThickness}
-                height={20}
-                backgroundColor={
-                  index < current
-                    ? componentColors.indicator.completed
-                    : componentColors.indicator.track
-                }
-                marginInlineStart={(markerSize - connectorThickness) / 2}
-                marginVertical={2}
-              />
-            ) : null;
+          const verticalConnector = !isLast ? (
+            <Connector
+              width={connectorThickness}
+              flexGrow={1}
+              minHeight={16}
+              backgroundColor={connectorFill}
+              marginTop={2}
+              transition={knobProps.transition}
+            />
+          ) : null;
+
+          const horizontalConnector = !isLast ? (
+            <Connector
+              flexGrow={1}
+              height={connectorThickness}
+              backgroundColor={connectorFill}
+              marginTop={(markerPx - connectorThickness) / 2}
+              marginHorizontal={gapToken}
+              minWidth={16}
+              transition={knobProps.transition}
+            />
+          ) : null;
 
           const body = horizontal ? (
-            <YStack
-              role="listitem"
-              alignItems="center"
-              flexShrink={0}
-              opacity={step.disabled ? 0.45 : 1}
-            >
-              {marker}
+            <YStack alignItems="center" flexShrink={0}>
+              {markerTarget}
               {labelBlock}
             </YStack>
           ) : (
-            <XStack
-              role="listitem"
-              alignItems="flex-start"
-              gap={gaps.markerLabel as any}
-              opacity={step.disabled ? 0.45 : 1}
-            >
-              {marker}
+            <XStack alignItems="stretch" gap={gapToken} minHeight={MIN_PRESS_TARGET}>
+              <YStack alignItems="center" width={MIN_PRESS_TARGET} flexShrink={0}>
+                {markerTarget}
+                {verticalConnector}
+              </YStack>
               {labelBlock}
             </XStack>
           );
 
-          const wrapped = canActivate ? (
+          const stepName = typeof step.label === "string" ? step.label : index + 1;
+          const goToLabel = withInterp(t("Go to step {{number}}: {{label}}"), {
+            number: index + 1,
+            label: stepName,
+          });
+
+          const wrapped = (
             <View
               key={step.id ?? index}
-              role="button"
-              tabIndex={0}
-              cursor="pointer"
+              role="listitem"
               flexGrow={horizontal ? 0 : undefined}
               flexShrink={horizontal ? 0 : undefined}
-              aria-label={withInterp(t("Go to step {{number}}: {{label}}"), {
-                number: index + 1,
-                label: typeof step.label === "string" ? step.label : index + 1,
-              })}
-              onPress={() => onStepChange?.(index)}
-              focusVisibleStyle={{
-                outlineColor: "$outlineColor",
-                outlineWidth: 2,
-                outlineStyle: "solid",
-                outlineOffset: 2,
-              }}
-              {...({
-                onKeyDown: (e: { key?: string; preventDefault?: () => void }) => {
-                  if (e.key === "Enter" || e.key === " ") {
-                    e.preventDefault?.();
-                    onStepChange?.(index);
-                  }
-                },
-              } as Record<string, unknown>)}
+              {...(step.disabled ? disabledState.chromeKnobProps : undefined)}
             >
-              {body}
-            </View>
-          ) : (
-            <View key={step.id ?? index} flexShrink={horizontal ? 0 : undefined}>
-              {body}
+              {isFocusable ? (
+                <StepButton
+                  render="button"
+                  tabIndex={0}
+                  aria-label={canActivate ? goToLabel : String(stepName)}
+                  aria-disabled={step.disabled || undefined}
+                  cursor={step.disabled ? "not-allowed" : "pointer"}
+                  onPress={() => {
+                    if (canActivate) onStepChange?.(index);
+                  }}
+                  onFocus={() => {
+                    if (wasKeyboardFocus()) setKbFocusIndex(index);
+                  }}
+                  onBlur={() => setKbFocusIndex((prev) => (prev === index ? null : prev))}
+                  {...({
+                    type: "button",
+                    onKeyDown: (e: { key?: string; preventDefault?: () => void }) => {
+                      if (!canActivate) return;
+                      if (e.key === "Enter" || e.key === " ") {
+                        e.preventDefault?.();
+                        onStepChange?.(index);
+                      }
+                    },
+                  } as Record<string, unknown>)}
+                >
+                  {body}
+                </StepButton>
+              ) : (
+                body
+              )}
             </View>
           );
 
@@ -289,7 +380,7 @@ export function ProgressSteps({
               flexBasis={horizontal ? 0 : undefined}
             >
               {wrapped}
-              {connector}
+              {horizontal ? horizontalConnector : null}
             </XStack>
           );
         })}