@wix/patterns 1.413.0 → 1.415.0

package/src/components/SetupWidget/SetupWidget.tsx

@@ -0,0 +1,253 @@
+import React from 'react';
+import { observer } from 'mobx-react-lite';
+import { Box } from '@wix/design-system';
+import { SetupWidgetState, SetupWidgetStep } from '@wix/bex-core';
+import { useWixPatternsContainer } from '@wix/bex-core/react';
+import { CardContainer } from '../CardContainer';
+import { useIsMobile } from '../../hooks/useIsMobile';
+import { useIntersectionObserver } from '../../hooks/useIntersectionObserver';
+import { SetupWidgetHeader } from './SetupWidgetHeader';
+import { SetupStepRow } from './SetupStepRow';
+import { SetupStepCard } from './SetupStepCard';
+import { SetupStepGroup } from './SetupStepGroup';
+import { AllCompleteState } from './AllCompleteState';
+import { SetupWidgetSkeleton } from './SetupWidgetSkeleton';
+
+export interface SetupWidgetProps {
+  /**
+   * A Setup widget state instance created with `useSetupWidget`. The widget
+   * owns loading / error / refetch; the state exposes the steps and a public
+   * API to change a step's status.
+   */
+  state: SetupWidgetState;
+  /**
+   * Inline-expansion content for a step, supplied at render time (the data does
+   * not carry it). Returned for the currently-expanded inline step.
+   */
+  renderStepContent?: (step: SetupWidgetStep) => React.ReactNode;
+  /** Fired when a `navigate` step (or its CTA) is activated. */
+  onStepClick?: (step: SetupWidgetStep) => void;
+  /**
+   * Fired when a *completed* step's CTA (or row) is activated — a distinct
+   * action from `onStepClick` (mirrors `onCompletedCtaClick` in dashboard-setup,
+   * which targets the step's separate `completedCta`).
+   */
+  onCompletedStepClick?: (step: SetupWidgetStep) => void;
+  /**
+   * Fired once when a step (or group) scrolls into view — for the consumer to
+   * report view telemetry (BI/dealer). The widget itself stays
+   * telemetry-agnostic. Click telemetry hooks into `onStepClick` /
+   * `onCompletedStepClick`.
+   */
+  onStepView?: (step: SetupWidgetStep) => void;
+  /** Fired when the "all complete" celebratory CTA is clicked. */
+  onAllCompleteClick?: () => void;
+  /**
+   * Replaces the default error UI when the initial load fails. Receives a
+   * `retry` callback (re-runs the load) and the thrown `error`. When omitted, a
+   * standard error card with a "Try again" retry is shown.
+   */
+  renderError?: (params: {
+    retry: () => void;
+    error: unknown;
+  }) => React.ReactNode;
+  /** Applies a data-hook attribute for tests. */
+  dataHook?: string;
+}
+
+// Fires `onView` once when the wrapped step scrolls into view. Only mounted
+// when the consumer passes `onStepView`, so view tracking adds no DOM/observer
+// overhead otherwise.
+const StepViewTracker = ({
+  stepId,
+  onView,
+  children,
+}: {
+  stepId: string;
+  onView: () => void;
+  children: React.ReactNode;
+}) => {
+  const { elementRef } = useIntersectionObserver(onView);
+  return (
+    <div
+      ref={elementRef as React.RefObject<HTMLDivElement>}
+      data-hook={`setup-step-view-${stepId}`}
+    >
+      {children}
+    </div>
+  );
+};
+
+const _SetupWidget = ({
+  state,
+  renderStepContent,
+  onStepClick,
+  onCompletedStepClick,
+  onStepView,
+  onAllCompleteClick,
+  renderError,
+  dataHook,
+}: SetupWidgetProps) => {
+  const { translate: t } = useWixPatternsContainer();
+  const isMobile = useIsMobile();
+  const { status } = state._loadTask.status;
+
+  const activateStep = (step: SetupWidgetStep) => {
+    // Completed steps fire their own action (never expand) — distinct from the
+    // active/navigate `onStepClick`.
+    if (step.status === 'completed') {
+      onCompletedStepClick?.(step);
+      return;
+    }
+    if (step.expansionMode === 'inline') {
+      state._toggleStep(step.id);
+    } else {
+      onStepClick?.(step);
+    }
+  };
+
+  // Children of an aggregated group are leaf steps — they never toggle/expand;
+  // completed children fire the completed action, the rest navigate.
+  const activateChild = (child: SetupWidgetStep) => {
+    if (child.status === 'completed') {
+      onCompletedStepClick?.(child);
+    } else {
+      onStepClick?.(child);
+    }
+  };
+
+  const renderLeaf = (step: SetupWidgetStep, isChild = false) => {
+    const expanded =
+      !isChild &&
+      step.expansionMode === 'inline' &&
+      state._expandedStepId === step.id;
+    const onActivate = () =>
+      isChild ? activateChild(step) : activateStep(step);
+
+    return isMobile ? (
+      <SetupStepCard
+        key={step.id}
+        step={step}
+        isPrimary={!isChild && step.id === state._primaryStepId}
+        expanded={expanded}
+        onActivate={onActivate}
+        renderStepContent={renderStepContent}
+      />
+    ) : (
+      <SetupStepRow
+        key={step.id}
+        step={step}
+        isFocused={!isChild && (step.id === state._primaryStepId || expanded)}
+        expanded={expanded}
+        onActivate={onActivate}
+        renderStepContent={renderStepContent}
+      />
+    );
+  };
+
+  // All-complete is a distinct success surface with its own card.
+  if (status === 'success' && state._isAllComplete) {
+    return (
+      <AllCompleteState dataHook={dataHook} onCtaClick={onAllCompleteClick} />
+    );
+  }
+
+  // Built-in loading skeleton, shaped like the widget (desktop card / mobile
+  // bare) so there's no layout jump when data resolves.
+  if (status === 'idle' || status === 'loading') {
+    return <SetupWidgetSkeleton isMobile={isMobile} dataHook={dataHook} />;
+  }
+
+  // Consumer-supplied error UI fully replaces the default error card.
+  if (status === 'error' && renderError) {
+    return (
+      <>
+        {renderError({
+          retry: () => state._retry(),
+          error: state._loadTask.errorStatus?.error,
+        })}
+      </>
+    );
+  }
+
+  const header = (
+    <SetupWidgetHeader
+      title={state._title}
+      completedCount={state._completedCount}
+      totalCount={state._totalCount}
+      progressPercentage={state._progressPercentage}
+      isMobile={isMobile}
+    />
+  );
+
+  const list = (
+    <Box direction="vertical" gap={isMobile ? 'SP3' : 'SP1'}>
+      {state.steps.map((step) => {
+        const node = step.steps?.length ? (
+          <SetupStepGroup
+            step={step}
+            isMobile={isMobile}
+            expanded={state._expandedStepId === step.id}
+            isPrimary={step.id === state._primaryStepId}
+            onToggle={() => state._toggleStep(step.id)}
+            renderChild={(child) => renderLeaf(child, true)}
+          />
+        ) : (
+          renderLeaf(step)
+        );
+
+        return onStepView ? (
+          <StepViewTracker
+            key={step.id}
+            stepId={step.id}
+            onView={() => onStepView(step)}
+          >
+            {node}
+          </StepViewTracker>
+        ) : (
+          <React.Fragment key={step.id}>{node}</React.Fragment>
+        );
+      })}
+    </Box>
+  );
+
+  const body = (
+    <>
+      {header}
+      {list}
+    </>
+  );
+
+  // Mobile success renders bare — no outer card (matches the mobile design;
+  // the consumer composes the surrounding page). Loading / error still flow
+  // through CardContainer so the widget owns those states everywhere.
+  if (isMobile && status === 'success') {
+    return (
+      <Box dataHook={dataHook} direction="vertical" gap="SP3">
+        {body}
+      </Box>
+    );
+  }
+
+  return (
+    <CardContainer
+      dataHook={dataHook}
+      status={status}
+      errorState={{
+        dataHook: 'error-state',
+        title: t('cairo.setupWidget.error.title'),
+        subtitle: t('cairo.setupWidget.error.subtitle'),
+        action: {
+          text: t('cairo.setupWidget.error.cta'),
+          onClick: () => state._retry(),
+        },
+      }}
+    >
+      <Box direction="vertical" padding="SP6">
+        {body}
+      </Box>
+    </CardContainer>
+  );
+};
+
+export const SetupWidget = observer(_SetupWidget);

package/src/components/SetupWidget/SetupWidget.uni.driver.ts

@@ -0,0 +1,59 @@
+import { UniDriver } from '@wix/wix-ui-test-utils/unidriver';
+import { baseUniDriverFactory } from '../../unidriver';
+import {
+  ButtonUniDriver,
+  TextButtonUniDriver,
+} from '@wix/design-system/dist/testkit/unidriver';
+
+export default (base: UniDriver, body: UniDriver) => {
+  const tryAgainButton = () =>
+    TextButtonUniDriver(
+      base.$(`[data-hook="error-card-state-action-button"]`),
+      body,
+    );
+
+  const stepCta = (id: string) =>
+    ButtonUniDriver(base.$(`[data-hook="setup-step-cta-${id}"]`), body);
+
+  return {
+    /** Widget title text. */
+    getTitle: () => base.$(`[data-hook="setup-widget-title"]`).text(),
+    /** "X/Y completed" progress label text. */
+    getProgressLabel: () =>
+      base.$(`[data-hook="setup-widget-progress"]`).text(),
+    /** Titles of all rendered steps, in order. */
+    getStepTitles: () =>
+      base.$$(`[data-hook^="setup-step-title-"]`).map((el) => el.text()),
+    /** Whether a given step row/card is rendered. */
+    stepExists: (id: string) =>
+      base.$(`[data-hook="setup-step-${id}"]`).exists(),
+    /** Click a step's row/card (triggers inline toggle or navigate). */
+    clickStep: (id: string) => base.$(`[data-hook="setup-step-${id}"]`).click(),
+    /** Click a step's CTA button. */
+    clickStepCta: (id: string) => stepCta(id).click(),
+    /** Whether a step's CTA is rendered. */
+    stepCtaExists: (id: string) =>
+      base.$(`[data-hook="setup-step-cta-${id}"]`).exists(),
+    /** Whether a disabled step's permission tooltip wraps its CTA. */
+    disabledTooltipExists: (id: string) =>
+      base.$(`[data-hook="setup-step-disabled-tooltip-${id}"]`).exists(),
+    /** Whether a step's inline-expansion content is shown. */
+    isStepExpanded: (id: string) =>
+      base.$(`[data-hook="setup-step-content-${id}"]`).exists(),
+    /** Whether an aggregated group's children are shown. */
+    isGroupExpanded: (id: string) =>
+      base.$(`[data-hook="setup-step-children-${id}"]`).exists(),
+    /** Click an arbitrary element by data-hook within the widget. */
+    clickByDataHook: (dataHook: string) =>
+      base.$(`[data-hook="${dataHook}"]`).click(),
+    /** Whether the all-complete success surface is shown. */
+    isAllComplete: () => base.$(`[data-hook="setup-all-complete"]`).exists(),
+    /** Whether the loading skeleton is shown. */
+    isLoading: () => base.$(`[data-hook="setup-widget-skeleton"]`).exists(),
+    /** Whether the error state is shown. */
+    isError: () => base.$(`[data-hook="error-card-state"]`).exists(),
+    /** Click the error state's "try again" button (refetches). */
+    clickTryAgain: () => tryAgainButton().click(),
+    ...baseUniDriverFactory(base),
+  };
+};

package/src/components/SetupWidget/SetupWidgetHeader.tsx

@@ -0,0 +1,64 @@
+import React from 'react';
+import { Box, Heading, Text, LinearProgressBar } from '@wix/design-system';
+import { useWixPatternsContainer } from '@wix/bex-core/react';
+
+export interface SetupWidgetHeaderProps {
+  /** Defaults to the translated "Setup" when omitted. */
+  title?: string | null;
+  completedCount: number;
+  totalCount: number;
+  progressPercentage: number;
+  isMobile: boolean;
+}
+
+/**
+ * Widget header: title + "X/Y completed" ratio + progress bar.
+ * - Desktop: title left, ratio + bar inline on the right.
+ * - Mobile: large heading stacked above the ratio and a full-width bar.
+ */
+export const SetupWidgetHeader = ({
+  title,
+  completedCount,
+  totalCount,
+  progressPercentage,
+  isMobile,
+}: SetupWidgetHeaderProps) => {
+  const { translate: t } = useWixPatternsContainer();
+  const resolvedTitle = title ?? t('cairo.setupWidget.title');
+  const ratioLabel = t('cairo.setupWidget.progress.label', {
+    completed: completedCount,
+    total: totalCount,
+  });
+
+  if (isMobile) {
+    return (
+      <Box direction="vertical" gap="SP2">
+        <Heading dataHook="setup-widget-title" size="large">
+          {resolvedTitle}
+        </Heading>
+        <Text dataHook="setup-widget-progress" size="small" secondary>
+          {ratioLabel}
+        </Text>
+        <Box width="100%">
+          <LinearProgressBar skin="standard" value={progressPercentage} />
+        </Box>
+      </Box>
+    );
+  }
+
+  return (
+    <Box align="space-between" verticalAlign="middle" marginBottom="SP4">
+      <Heading dataHook="setup-widget-title" size="medium">
+        {resolvedTitle}
+      </Heading>
+      <Box gap="SP1" verticalAlign="middle">
+        <Text dataHook="setup-widget-progress" size="tiny" weight="thin">
+          {ratioLabel}
+        </Text>
+        <Box width={220} marginLeft="-8px">
+          <LinearProgressBar skin="standard" value={progressPercentage} />
+        </Box>
+      </Box>
+    </Box>
+  );
+};

package/src/components/SetupWidget/SetupWidgetSkeleton.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+import { Card, Box, SkeletonGroup, SkeletonLine } from '@wix/design-system';
+
+const SKELETON_ROW_COUNT = 4;
+
+// Wrap in a full-width *vertical* Box: a flex column stretches the SkeletonGroup
+// to the container width, so the SkeletonLine's `%` resolves against the row/card
+// (a horizontal wrapper lets the group shrink to content, making lines narrow).
+const Line = ({ width }: { width: string }) => (
+  <Box direction="vertical" width="100%">
+    <SkeletonGroup>
+      <SkeletonLine width={width} />
+    </SkeletonGroup>
+  </Box>
+);
+
+/**
+ * Built-in loading skeleton shaped like the widget — a header (title +
+ * progress bar) over a list of step-row placeholders. Mirrors the success
+ * layout (card-wrapped on desktop, bare on mobile) so there's no layout jump
+ * when the data resolves.
+ */
+export const SetupWidgetSkeleton = ({
+  isMobile,
+  dataHook,
+}: {
+  isMobile: boolean;
+  dataHook?: string;
+}) => {
+  // Header skeleton mirrors SetupWidgetHeader's layout so the progress-bar area
+  // is reserved too (no jump when data resolves):
+  // - Mobile: title, ratio text, then a full-width bar — all stacked.
+  // - Desktop: title on the left; ratio + a 220px bar inline on the right.
+  const header = isMobile ? (
+    <Box direction="vertical" gap="SP2" marginBottom="SP3">
+      <Line width="60%" />
+      <Box width="35%">
+        <Line width="100%" />
+      </Box>
+      {/* progress bar */}
+      <Line width="100%" />
+    </Box>
+  ) : (
+    // No fixed widths: title and progress-bar lines each `flex={1}` (equal
+    // share), and the `gap` guarantees space between them at any card width.
+    <Box verticalAlign="middle" gap="SP6" marginBottom="SP4">
+      {/* title */}
+      <Box flex={1}>
+        <Line width="100%" />
+      </Box>
+      {/* progress bar */}
+      <Box flex={1}>
+        <Line width="100%" />
+      </Box>
+    </Box>
+  );
+
+  const body = (
+    <Box dataHook="setup-widget-skeleton" direction="vertical" width="100%">
+      {header}
+
+      {/* step rows */}
+      <Box direction="vertical" gap={isMobile ? 'SP3' : 'SP1'}>
+        {Array.from({ length: SKELETON_ROW_COUNT }).map((_, index) => (
+          <Box
+            key={index}
+            width="100%"
+            padding={isMobile ? 'SP4' : 'SP1'}
+            minHeight="30px"
+            verticalAlign="middle"
+            border="1px solid"
+            borderColor="D60"
+            borderRadius={isMobile ? '8px' : '4px'}
+          >
+            <Line width="40%" />
+          </Box>
+        ))}
+      </Box>
+    </Box>
+  );
+
+  // Mobile renders bare (no outer card), matching the success layout.
+  if (isMobile) {
+    return (
+      <Box dataHook={dataHook} direction="vertical">
+        {body}
+      </Box>
+    );
+  }
+
+  return (
+    <Card dataHook={dataHook}>
+      <Box direction="vertical" padding="SP6">
+        {body}
+      </Box>
+    </Card>
+  );
+};