@12-apps/ui 1.0.0

package/src/components/data-display/SectionOnboarding/SectionOnboarding.test.stories.tsx

@@ -0,0 +1,190 @@
+import { Box, Chip, TextField } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+
+import { SectionOnboarding } from './SectionOnboarding';
+
+const MockForm = () => (
+  <TextField label="Token do PagBank" type="password" data-testid="mock-form-field" />
+);
+
+const SETUP_STEPS = [
+  { id: 'connect', label: 'Conectar conta' },
+  { id: 'homolog', label: 'Homologar' },
+  { id: 'activate', label: 'Ativar vendas' },
+];
+
+const meta: Meta<typeof SectionOnboarding> = {
+  title: 'DataDisplay/AsyncStates/SectionOnboarding/Tests',
+  component: SectionOnboarding,
+  parameters: {
+    layout: 'padded',
+    chromatic: { disableSnapshot: false },
+  },
+  tags: ['autodocs', 'test', 'component:SectionOnboarding'],
+};
+
+export default meta;
+export type Story = StoryObj<typeof meta>;
+
+export const UnconfiguredShowsHeroAndCta: Story = {
+  args: {
+    status: 'unconfigured',
+    title: 'Receba pagamentos',
+    description: 'Conecte sua conta PagBank.',
+    steps: SETUP_STEPS,
+    primaryAction: { label: 'Começar configuração', onClick: fn() },
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+
+    // Root reflects the status.
+    const root = canvas.getByTestId('section-onboarding');
+    await expect(root).toHaveAttribute('data-status', 'unconfigured');
+
+    // Hero title + step preview are present.
+    await expect(canvas.getByRole('heading', { name: 'Receba pagamentos' })).toBeInTheDocument();
+    await expect(canvas.getByTestId('section-onboarding-steps')).toBeInTheDocument();
+
+    // CTA fires.
+    const cta = canvas.getByRole('button', { name: 'Começar configuração' });
+    await userEvent.click(cta);
+    await expect(args.primaryAction?.onClick).toHaveBeenCalledTimes(1);
+
+    // The real form is NOT rendered before setup starts.
+    await waitFor(() => expect(canvas.queryByTestId('mock-form-field')).not.toBeInTheDocument());
+  },
+};
+
+export const InProgressShowsStepsAndForm: Story = {
+  args: {
+    status: 'in-progress',
+    title: 'Conectar conta',
+    steps: SETUP_STEPS,
+    activeStepId: 'homolog',
+    completedStepIds: ['connect'],
+    children: <MockForm />,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const root = canvas.getByTestId('section-onboarding');
+    await expect(root).toHaveAttribute('data-status', 'in-progress');
+
+    // Steps AND the form are both visible during active setup.
+    await expect(canvas.getByTestId('section-onboarding-steps')).toBeInTheDocument();
+    await expect(canvas.getByTestId('mock-form-field')).toBeInTheDocument();
+  },
+};
+
+export const ConfiguredCollapsesFormBehindToggle: Story = {
+  args: {
+    status: 'configured',
+    title: 'PagBank',
+    configuredTitle: 'PagBank conectado',
+    configuredSummary: <Chip label="Ativo" color="success" size="small" />,
+    children: <MockForm />,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    const root = canvas.getByTestId('section-onboarding');
+    await expect(root).toHaveAttribute('data-status', 'configured');
+
+    // Compact summary is shown; the form starts hidden.
+    await expect(canvas.getByText('PagBank conectado')).toBeInTheDocument();
+    await waitFor(() => expect(canvas.queryByTestId('mock-form-field')).not.toBeInTheDocument());
+
+    // Reveal the form via the edit toggle.
+    const toggle = canvas.getByTestId('section-onboarding-edit-toggle');
+    await expect(toggle).toHaveAttribute('aria-expanded', 'false');
+    await userEvent.click(toggle);
+    await expect(toggle).toHaveAttribute('aria-expanded', 'true');
+    await expect(canvas.getByTestId('mock-form-field')).toBeVisible();
+  },
+};
+
+export const ConfiguredDefaultExpanded: Story = {
+  args: {
+    status: 'configured',
+    title: 'PagBank',
+    configuredSummary: <Chip label="Ativo" color="success" size="small" />,
+    defaultExpanded: true,
+    children: <MockForm />,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // With defaultExpanded, the form is visible immediately.
+    await expect(canvas.getByTestId('mock-form-field')).toBeVisible();
+    await expect(canvas.getByTestId('section-onboarding-edit-toggle')).toHaveAttribute(
+      'aria-expanded',
+      'true',
+    );
+  },
+};
+
+export const HeroCtaRevealsFormInPlace: Story = {
+  args: {
+    status: 'unconfigured',
+    title: 'Receba pagamentos',
+    description: 'Conecte sua conta PagBank.',
+    steps: SETUP_STEPS,
+    startLabel: 'Começar configuração',
+    children: <MockForm />,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // No custom primaryAction => the built-in start CTA is offered and the
+    // form is hidden until the user starts.
+    await expect(canvas.getByTestId('section-onboarding')).toHaveAttribute(
+      'data-status',
+      'unconfigured',
+    );
+    await waitFor(() => expect(canvas.queryByTestId('mock-form-field')).not.toBeInTheDocument());
+
+    const startCta = canvas.getByRole('button', { name: 'Começar configuração' });
+    await userEvent.click(startCta);
+
+    // Now the form is revealed in place — no parent state required.
+    await expect(canvas.getByTestId('section-onboarding')).toHaveAttribute('data-status', 'started');
+    await expect(canvas.getByTestId('mock-form-field')).toBeVisible();
+  },
+};
+
+export const NoStepsRendersSingleStepHero: Story = {
+  args: {
+    status: 'unconfigured',
+    title: 'Integração com IA',
+    description: 'Deixe a IA responder o seu cardápio.',
+    primaryAction: { label: 'Começar', onClick: fn() },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // No steps => no stepper preview, but the hero still renders.
+    await waitFor(() =>
+      expect(canvas.queryByTestId('section-onboarding-steps')).not.toBeInTheDocument(),
+    );
+    await expect(canvas.getByRole('heading', { name: 'Integração com IA' })).toBeInTheDocument();
+  },
+};
+
+export const ConfiguredWithoutChildrenHidesToggle: Story = {
+  render: () => (
+    <Box>
+      <SectionOnboarding
+        status="configured"
+        title="PagBank"
+        configuredSummary={<Chip label="Ativo" color="success" size="small" />}
+      />
+    </Box>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // No children => no edit toggle offered.
+    await waitFor(() =>
+      expect(canvas.queryByTestId('section-onboarding-edit-toggle')).not.toBeInTheDocument(),
+    );
+    await expect(canvas.getByTestId('section-onboarding-summary')).toBeInTheDocument();
+  },
+};

package/src/components/data-display/SectionOnboarding/SectionOnboarding.tsx

@@ -0,0 +1,224 @@
+'use client';
+
+import { CheckCircle } from '@mui/icons-material';
+import { Box, Button, Collapse, Stack, Typography, useTheme } from '@mui/material';
+import React from 'react';
+
+import { EmptyState } from '../EmptyState/EmptyState';
+import { Stepper } from '../Stepper/Stepper';
+import type { SectionOnboardingProps } from './SectionOnboarding.types';
+
+/** The setup steps rendered above the hero / form. Returns null when omitted. */
+const OnboardingSteps: React.FC<
+  Pick<SectionOnboardingProps, 'steps' | 'activeStepId' | 'completedStepIds'> & {
+    dataTestId: string;
+  }
+> = ({ steps, activeStepId, completedStepIds, dataTestId }) => {
+  if (!steps || steps.length === 0) return null;
+  // Preview mode (no active step): highlight the first so the flow reads L→R.
+  const activeId = activeStepId ?? steps[0]?.id ?? '';
+  return (
+    <Box sx={{ width: '100%', overflowX: 'auto', pb: 1 }}>
+      <Stepper
+        steps={steps}
+        activeId={activeId}
+        completed={new Set(completedStepIds ?? [])}
+        size="sm"
+        data-testid={`${dataTestId}-steps`}
+      />
+    </Box>
+  );
+};
+
+/** The compact "already connected" header shown in the configured state. */
+const ConfiguredSummary: React.FC<
+  Pick<SectionOnboardingProps, 'configuredTitle' | 'title' | 'configuredSummary'> & {
+    dataTestId: string;
+    expanded: boolean;
+    onToggle: () => void;
+    editLabel: string;
+    collapseLabel: string;
+    hasChildren: boolean;
+  }
+> = ({
+  configuredTitle,
+  title,
+  configuredSummary,
+  dataTestId,
+  expanded,
+  onToggle,
+  editLabel,
+  collapseLabel,
+  hasChildren,
+}) => {
+  const theme = useTheme();
+  return (
+    <Stack
+      direction={{ xs: 'column', sm: 'row' }}
+      spacing={2}
+      alignItems={{ xs: 'flex-start', sm: 'center' }}
+      data-testid={`${dataTestId}-summary`}
+    >
+      <CheckCircle sx={{ color: theme.palette.success.main }} aria-hidden />
+      <Box sx={{ minWidth: 0 }}>
+        <Typography variant="subtitle1" component="h3" fontWeight="medium">
+          {configuredTitle ?? title}
+        </Typography>
+        {configuredSummary && (
+          <Typography variant="body2" color="text.secondary" component="div">
+            {configuredSummary}
+          </Typography>
+        )}
+      </Box>
+      {hasChildren && (
+        <Button
+          variant="outlined"
+          size="small"
+          onClick={onToggle}
+          aria-expanded={expanded}
+          data-testid={`${dataTestId}-edit-toggle`}
+        >
+          {expanded ? collapseLabel : editLabel}
+        </Button>
+      )}
+    </Stack>
+  );
+};
+
+/**
+ * Per-section onboarding wrapper: the same config surface renders three ways
+ * depending on `status`, so a first-time user meets a friendly hero + CTA
+ * instead of a wall of empty fields, while a returning user sees a compact
+ * "it's connected" summary with the form tucked behind an "Editar" toggle.
+ *
+ * Composes the existing {@link EmptyState} (the hero) and {@link Stepper} (the
+ * progress preview) — drop it onto any settings/integration page and drive it
+ * from whatever "is this configured?" signal the feature already has.
+ */
+/** Configured state: compact success summary + the form behind an "Editar" toggle. */
+const ConfiguredView: React.FC<SectionOnboardingProps> = ({
+  title,
+  configuredTitle,
+  configuredSummary,
+  editLabel = 'Editar',
+  collapseLabel = 'Ocultar',
+  defaultExpanded = false,
+  children,
+  className,
+  dataTestId = 'section-onboarding',
+}) => {
+  const [expanded, setExpanded] = React.useState(defaultExpanded);
+  return (
+    <Box
+      className={className}
+      data-testid={dataTestId}
+      data-status="configured"
+      sx={{ p: 2, borderRadius: 1, border: 1, borderColor: 'divider' }}
+    >
+      <ConfiguredSummary
+        configuredTitle={configuredTitle}
+        title={title}
+        configuredSummary={configuredSummary}
+        dataTestId={dataTestId}
+        expanded={expanded}
+        onToggle={() => setExpanded((prev) => !prev)}
+        editLabel={editLabel}
+        collapseLabel={collapseLabel}
+        hasChildren={Boolean(children)}
+      />
+      {children && (
+        <Collapse in={expanded} unmountOnExit>
+          <Box sx={{ mt: 3 }} data-testid={`${dataTestId}-content`}>
+            {children}
+          </Box>
+        </Collapse>
+      )}
+    </Box>
+  );
+};
+
+/** In-progress state (or a started hero): the live stepper + the form. */
+const InProgressView: React.FC<SectionOnboardingProps & { statusAttr: string }> = ({
+  steps,
+  activeStepId,
+  completedStepIds,
+  children,
+  className,
+  statusAttr,
+  dataTestId = 'section-onboarding',
+}) => (
+  <Stack className={className} data-testid={dataTestId} data-status={statusAttr} spacing={3}>
+    <OnboardingSteps
+      steps={steps}
+      activeStepId={activeStepId}
+      completedStepIds={completedStepIds}
+      dataTestId={dataTestId}
+    />
+    {children && <Box data-testid={`${dataTestId}-content`}>{children}</Box>}
+  </Stack>
+);
+
+/** Unconfigured hero: optional step preview + the EmptyState hero + CTA. */
+const HeroView: React.FC<SectionOnboardingProps & { onStart: () => void }> = ({
+  title,
+  description,
+  illustration,
+  steps,
+  activeStepId,
+  completedStepIds,
+  primaryAction,
+  startLabel = 'Começar',
+  secondaryAction,
+  helpLink,
+  children,
+  className,
+  onStart,
+  dataTestId = 'section-onboarding',
+}) => {
+  // With no custom primaryAction, offer a built-in CTA that reveals the form.
+  const heroPrimary =
+    primaryAction ?? (children ? { label: startLabel, onClick: onStart } : undefined);
+  return (
+    <Stack className={className} data-testid={dataTestId} data-status="unconfigured" spacing={1}>
+      <OnboardingSteps
+        steps={steps}
+        activeStepId={activeStepId}
+        completedStepIds={completedStepIds}
+        dataTestId={dataTestId}
+      />
+      <EmptyState
+        variant={illustration ? 'illustrated' : 'action'}
+        title={title}
+        description={description}
+        illustration={illustration}
+        primaryAction={heroPrimary}
+        secondaryAction={secondaryAction}
+        helpLink={helpLink}
+        dataTestId={`${dataTestId}-hero`}
+      />
+    </Stack>
+  );
+};
+
+export const SectionOnboarding: React.FC<SectionOnboardingProps> = (props) => {
+  // Lets the hero reveal the form in place, so a server page can adopt
+  // onboarding by passing `status` + children alone — no client wrapper.
+  const [started, setStarted] = React.useState(false);
+
+  if (props.status === 'configured') {
+    return <ConfiguredView {...props} />;
+  }
+  if (props.status === 'in-progress' || started) {
+    return (
+      <InProgressView
+        {...props}
+        statusAttr={props.status === 'in-progress' ? 'in-progress' : 'started'}
+      />
+    );
+  }
+  return <HeroView {...props} onStart={() => setStarted(true)} />;
+};
+
+SectionOnboarding.displayName = 'SectionOnboarding';
+
+export default SectionOnboarding;

package/src/components/data-display/SectionOnboarding/SectionOnboarding.types.ts

@@ -0,0 +1,101 @@
+import type { ReactNode } from 'react';
+
+import type { Step } from '../Stepper/Stepper.types';
+
+/**
+ * Lifecycle of a configurable page section:
+ * - `unconfigured` — never set up: show the onboarding hero (why + CTA).
+ * - `in-progress`  — actively being set up: show the steps + the real form.
+ * - `configured`   — already set up: show a compact summary, form on demand.
+ */
+export type SectionOnboardingStatus = 'unconfigured' | 'in-progress' | 'configured';
+
+export interface SectionOnboardingAction {
+  label: string;
+  onClick: () => void;
+}
+
+export interface SectionOnboardingHelpLink {
+  label: string;
+  href: string;
+  external?: boolean;
+}
+
+export interface SectionOnboardingProps {
+  /**
+   * Which lifecycle view to render. Derive it on the server from whatever
+   * "is this set up?" signal the feature already has (a `null` config, a
+   * `status` field, a row count) — no new query is needed.
+   */
+  status: SectionOnboardingStatus;
+
+  /** Headline for the onboarding hero (unconfigured / in-progress). */
+  title: string;
+
+  /** Plain-language explanation of what this section does and why. */
+  description?: string;
+
+  /** Optional illustration/icon shown in the hero (unconfigured only). */
+  illustration?: ReactNode;
+
+  /**
+   * Ordered setup steps. Shown as a non-interactive preview in `unconfigured`
+   * and as live progress in `in-progress`. Omit for a single-step section.
+   */
+  steps?: Step[];
+
+  /** Id of the step currently in progress (used when `status` is in-progress). */
+  activeStepId?: string;
+
+  /** Ids of steps already completed (rendered with a check). */
+  completedStepIds?: string[];
+
+  /**
+   * Primary CTA of the hero — e.g. "Começar configuração". Provide this only
+   * when the parent wants to fully control what the button does (e.g. navigate
+   * to a dedicated wizard route). When omitted, the component renders a default
+   * CTA (see `startLabel`) that reveals the `children` form in place — so a
+   * server page can adopt onboarding without any client wrapper of its own.
+   */
+  primaryAction?: SectionOnboardingAction;
+
+  /**
+   * Label of the built-in "start" CTA shown when no `primaryAction` is provided
+   * and `children` exist. Clicking it advances the hero to the in-progress view
+   * (steps + form) without the parent managing state. @default 'Começar'
+   */
+  startLabel?: string;
+
+  /** Optional secondary CTA of the hero — e.g. "Ver como funciona". */
+  secondaryAction?: SectionOnboardingAction;
+
+  /** Optional help link under the hero actions. */
+  helpLink?: SectionOnboardingHelpLink;
+
+  /** Heading for the compact configured summary (defaults to `title`). */
+  configuredTitle?: string;
+
+  /**
+   * The compact "it's connected" summary shown when `configured` — e.g. a
+   * status chip, the account name, the environment. Kept short.
+   */
+  configuredSummary?: ReactNode;
+
+  /** Label of the reveal toggle in the configured state. @default 'Editar' */
+  editLabel?: string;
+
+  /** Label of the reveal toggle while expanded. @default 'Ocultar' */
+  collapseLabel?: string;
+
+  /** Start the configured state with the form already revealed. @default false */
+  defaultExpanded?: boolean;
+
+  /**
+   * The real controls (the credential form / advanced settings). Rendered
+   * directly in `in-progress`, and behind the reveal toggle in `configured`.
+   */
+  children?: ReactNode;
+
+  className?: string;
+  dataTestId?: string;
+}

package/src/components/data-display/SectionOnboarding/index.ts

@@ -0,0 +1,7 @@
+export { default, SectionOnboarding } from './SectionOnboarding';
+export type {
+  SectionOnboardingAction,
+  SectionOnboardingHelpLink,
+  SectionOnboardingProps,
+  SectionOnboardingStatus,
+} from './SectionOnboarding.types';