@12-apps/ui 1.0.0

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

@@ -0,0 +1,332 @@
+import type {
+  PaletteColor} from '@mui/material';
+import {
+  alpha,
+  Box,
+  CircularProgress,
+  keyframes,
+  LinearProgress,
+  Typography,
+} from '@mui/material';
+import type { Theme} from '@mui/material/styles';
+import { styled, useTheme } from '@mui/material/styles';
+import React from 'react';
+
+import type { ProgressProps, ProgressSize, ProgressVariant } from './Progress.types';
+
+// Define pulse animation
+const pulseAnimation = keyframes`
+  0% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.7;
+  }
+  100% {
+    opacity: 1;
+  }
+`;
+
+const getColorFromTheme = (theme: Theme, color: string): PaletteColor => {
+  const colorMap: Record<string, PaletteColor> = {
+    primary: theme.palette.primary,
+    secondary: theme.palette.secondary,
+    success: theme.palette.success,
+    warning: theme.palette.warning,
+    error: theme.palette.error,
+    danger: theme.palette.error, // Add danger alias
+  };
+
+  // Handle special case for neutral (grey) which is a Color, not PaletteColor
+  if (color === 'neutral') {
+    return {
+      light: theme.palette.grey[300],
+      main: theme.palette.grey[500],
+      dark: theme.palette.grey[700],
+      contrastText: theme.palette.getContrastText(theme.palette.grey[500]),
+    };
+  }
+
+  const selectedColor = colorMap[color];
+  // Ensure we always return a valid color object with main and dark properties
+  return selectedColor || theme.palette.primary;
+};
+
+const getSizeStyles = (size: ProgressSize) => {
+  const sizeMap: Record<ProgressSize, { height: number; circularSize: number; fontSize: string }> =
+    {
+      sm: { height: 4, circularSize: 32, fontSize: '0.75rem' },
+      md: { height: 6, circularSize: 40, fontSize: '0.875rem' },
+      lg: { height: 8, circularSize: 48, fontSize: '1rem' },
+    };
+
+  return sizeMap[size] || sizeMap.md;
+};
+
+const StyledLinearProgress = styled(LinearProgress, {
+  shouldForwardProp: (prop) =>
+    !['customVariant', 'customSize', 'customColor', 'glow', 'pulse'].includes(prop as string),
+})<{
+  customVariant?: ProgressVariant;
+  customSize?: ProgressSize;
+  customColor?: string;
+  glow?: boolean;
+  pulse?: boolean;
+}>(({ theme, customVariant, customSize = 'md', customColor = 'primary', glow, pulse }) => {
+  const colorPalette = getColorFromTheme(theme, customColor);
+  const sizeStyles = getSizeStyles(customSize);
+
+  return {
+    height: sizeStyles.height,
+    borderRadius: sizeStyles.height / 2,
+    backgroundColor: alpha(colorPalette.main, 0.1),
+
+    '& .MuiLinearProgress-bar': {
+      borderRadius: 'inherit',
+      transition: 'all 0.3s ease',
+
+      ...(customVariant === 'linear' && {
+        backgroundColor: colorPalette.main,
+      }),
+
+      ...(customVariant === 'gradient' && {
+        background: `linear-gradient(90deg, ${colorPalette.main} 0%, ${colorPalette.dark || colorPalette.main} 100%)`,
+      }),
+
+      ...(customVariant === 'glass' && {
+        backgroundColor: alpha(colorPalette.main, 0.8),
+        backdropFilter: 'blur(10px)',
+        border: `1px solid ${alpha(colorPalette.main, 0.3)}`,
+      }),
+
+      // Glow effect
+      ...(glow &&
+        !pulse && {
+          boxShadow: `0 0 10px 2px ${alpha(colorPalette.main, 0.4)}`,
+          filter: 'brightness(1.1)',
+        }),
+
+      // Pulse animation
+      ...(pulse &&
+        !glow && {
+          animation: `${pulseAnimation} 2s infinite`,
+        }),
+
+      // Both glow and pulse
+      ...(glow &&
+        pulse && {
+          boxShadow: `0 0 10px 2px ${alpha(colorPalette.main, 0.4)}`,
+          filter: 'brightness(1.1)',
+          animation: `${pulseAnimation} 2s infinite`,
+        }),
+    },
+  };
+});
+
+const StyledCircularProgress = styled(CircularProgress, {
+  shouldForwardProp: (prop) => !['customColor', 'glow', 'pulse'].includes(prop as string),
+})<{
+  customColor?: string;
+  glow?: boolean;
+  pulse?: boolean;
+}>(({ theme, customColor = 'primary', glow, pulse }) => {
+  const colorPalette = getColorFromTheme(theme, customColor);
+
+  return {
+    color: colorPalette.main,
+
+    // Glow effect
+    ...(glow &&
+      !pulse && {
+        filter: `drop-shadow(0 0 8px ${alpha(colorPalette.main, 0.6)})`,
+      }),
+
+    // Pulse animation
+    ...(pulse &&
+      !glow && {
+        animation: `${pulseAnimation} 2s infinite`,
+      }),
+
+    // Both glow and pulse
+    ...(glow &&
+      pulse && {
+        filter: `drop-shadow(0 0 8px ${alpha(colorPalette.main, 0.6)})`,
+        animation: `${pulseAnimation} 2s infinite`,
+      }),
+  };
+});
+
+const SegmentedProgress: React.FC<{
+  value?: number;
+  segments: number;
+  color: string;
+  size: ProgressSize;
+  glow: boolean;
+  pulse: boolean;
+  dataTestId?: string;
+}> = ({ value = 0, segments, color, size, glow, pulse, dataTestId }) => {
+  const theme = useTheme();
+  const colorPalette = getColorFromTheme(theme, color);
+  const sizeStyles = getSizeStyles(size);
+  const filledSegments = Math.floor((value / 100) * segments);
+
+  return (
+    <Box sx={{ display: 'flex', gap: 0.5, width: '100%' }} data-testid={`${dataTestId}-segments-container`}>
+      {Array.from({ length: segments }, (_, index) => (
+        <Box
+          key={index}
+          data-testid={`${dataTestId}-segment-${index}`}
+          sx={{
+            flex: 1,
+            height: sizeStyles.height,
+            borderRadius: sizeStyles.height / 2,
+            backgroundColor:
+              index < filledSegments ? colorPalette.main : alpha(colorPalette.main, 0.1),
+            transition: 'all 0.3s ease',
+            ...(glow &&
+              index < filledSegments && {
+                boxShadow: `0 0 6px 1px ${alpha(colorPalette.main, 0.4)}`,
+              }),
+            ...(pulse &&
+              index < filledSegments && {
+                animation: `${pulseAnimation} 2s infinite`,
+              }),
+          }}
+        />
+      ))}
+    </Box>
+  );
+};
+
+export const Progress = React.forwardRef<HTMLDivElement, ProgressProps>(
+  (
+    {
+      variant = 'linear',
+      size = 'md',
+      color = 'primary',
+      glow = false,
+      pulse = false,
+      showLabel = false,
+      label,
+      segments = 10,
+      thickness = 4,
+      circularSize,
+      value,
+      dataTestId = 'progress',
+      ...props
+    },
+    ref,
+  ) => {
+    const sizeStyles = getSizeStyles(size);
+    const finalCircularSize = circularSize || sizeStyles.circularSize;
+
+    const displayValue = value || 0;
+    const displayLabel = label || (showLabel ? `${Math.round(displayValue)}%` : '');
+
+    if (variant === 'circular') {
+      return (
+        <Box ref={ref} sx={{ position: 'relative', display: 'inline-flex' }} data-testid={dataTestId}>
+          <StyledCircularProgress
+            variant={value !== undefined ? 'determinate' : 'indeterminate'}
+            value={displayValue}
+            size={finalCircularSize}
+            thickness={thickness}
+            customColor={color}
+            glow={glow}
+            pulse={pulse}
+            data-testid={`${dataTestId}-circular`}
+            {...props}
+          />
+          {showLabel && value !== undefined && (
+            <Box
+              sx={{
+                top: 0,
+                left: 0,
+                bottom: 0,
+                right: 0,
+                position: 'absolute',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+              }}
+            >
+              <Typography
+                variant="caption"
+                component="div"
+                color="text.secondary"
+                sx={{ fontSize: sizeStyles.fontSize, fontWeight: 600 }}
+                data-testid={`${dataTestId}-label`}
+              >
+                {displayLabel}
+              </Typography>
+            </Box>
+          )}
+        </Box>
+      );
+    }
+
+    if (variant === 'segmented') {
+      return (
+        <Box ref={ref} sx={{ width: '100%' }} data-testid={dataTestId} {...props}>
+          <SegmentedProgress
+            value={displayValue}
+            segments={segments}
+            color={color}
+            size={size}
+            glow={glow}
+            pulse={pulse}
+            dataTestId={dataTestId}
+          />
+          {showLabel && (
+            <Typography
+              variant="caption"
+              sx={{
+                display: 'block',
+                textAlign: 'center',
+                mt: 1,
+                fontSize: sizeStyles.fontSize,
+                fontWeight: 600,
+              }}
+              data-testid={`${dataTestId}-label`}
+            >
+              {displayLabel}
+            </Typography>
+          )}
+        </Box>
+      );
+    }
+
+    return (
+      <Box ref={ref} sx={{ width: '100%' }} data-testid={dataTestId}>
+        <StyledLinearProgress
+          variant={value !== undefined ? 'determinate' : 'indeterminate'}
+          value={displayValue}
+          customVariant={variant}
+          customSize={size}
+          customColor={color}
+          glow={glow}
+          pulse={pulse}
+          data-testid={`${dataTestId}-linear`}
+          {...props}
+        />
+        {showLabel && (
+          <Typography
+            variant="caption"
+            sx={{
+              display: 'block',
+              textAlign: 'center',
+              mt: 1,
+              fontSize: sizeStyles.fontSize,
+              fontWeight: 600,
+            }}
+            data-testid={`${dataTestId}-label`}
+          >
+            {displayLabel}
+          </Typography>
+        )}
+      </Box>
+    );
+  },
+);
+
+Progress.displayName = 'Progress';

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

@@ -0,0 +1,61 @@
+import type { LinearProgressProps } from '@mui/material';
+
+export type ProgressVariant = 'linear' | 'circular' | 'segmented' | 'gradient' | 'glass';
+export type ProgressSize = 'sm' | 'md' | 'lg';
+
+export interface ProgressProps extends Omit<LinearProgressProps, 'variant' | 'color'> {
+  /**
+   * The variant of the progress
+   */
+  variant?: ProgressVariant;
+
+  /**
+   * The size of the progress
+   */
+  size?: ProgressSize;
+
+  /**
+   * The color of the progress
+   */
+  color?: 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'neutral';
+
+  /**
+   * Whether the progress should have a glow effect
+   */
+  glow?: boolean;
+
+  /**
+   * Whether the progress should have a pulse animation
+   */
+  pulse?: boolean;
+
+  /**
+   * Show percentage text
+   */
+  showLabel?: boolean;
+
+  /**
+   * Custom label text
+   */
+  label?: string;
+
+  /**
+   * Number of segments for segmented variant
+   */
+  segments?: number;
+
+  /**
+   * Thickness for circular variant
+   */
+  thickness?: number;
+
+  /**
+   * Size for circular variant
+   */
+  circularSize?: number;
+
+  /**
+   * Test ID for testing purposes
+   */
+  dataTestId?: string;
+}

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

@@ -0,0 +1,2 @@
+export { Progress } from './Progress';
+export type { ProgressProps, ProgressSize,ProgressVariant } from './Progress.types';

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

@@ -0,0 +1,108 @@
+# SectionOnboarding Component
+
+**Purpose:** Per-section onboarding wrapper. One configurable page section renders three ways depending on a `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 [`EmptyState`](../EmptyState/EmptyState.md) (the hero) and [`Stepper`](../Stepper/Stepper.md) (the progress preview). Drop it onto any settings/integration page and drive it from whatever "is this configured?" signal the feature already has (a `null` config, a `status` field, a row count) — no new query needed.
+
+```ts
+type SectionOnboardingStatus = 'unconfigured' | 'in-progress' | 'configured';
+
+interface SectionOnboardingProps {
+  status: SectionOnboardingStatus;
+  title: string;
+  description?: string;
+  illustration?: React.ReactNode;
+  steps?: Step[];                 // reuses Stepper's Step type
+  activeStepId?: string;
+  completedStepIds?: string[];
+  primaryAction?: { label: string; onClick: () => void };
+  secondaryAction?: { label: string; onClick: () => void };
+  helpLink?: { label: string; href: string; external?: boolean };
+  configuredTitle?: string;
+  configuredSummary?: React.ReactNode;
+  editLabel?: string;            // default 'Editar'
+  collapseLabel?: string;        // default 'Ocultar'
+  defaultExpanded?: boolean;     // default false
+  children?: React.ReactNode;    // the real form / advanced controls
+  className?: string;
+  dataTestId?: string;
+}
+```
+
+## The three states
+
+| `status`        | What renders                                                                 |
+|-----------------|------------------------------------------------------------------------------|
+| `unconfigured`  | Optional step preview + `EmptyState` hero (title, description, illustration, CTA). **No form.** |
+| `in-progress`   | Live `Stepper` (activeStepId / completedStepIds) + `children` (the form).     |
+| `configured`    | Compact success summary (`configuredSummary`) + an **Editar** toggle that reveals `children`. |
+
+### Self-managed reveal (zero-wrapper adoption)
+
+When `status` is `unconfigured` and you pass **`children` but no `primaryAction`**, the hero
+renders a built-in CTA (label from `startLabel`, default `'Começar'`) that reveals the form in
+place — the root's `data-status` flips to `started`. This means a **server** page can adopt
+onboarding by passing `status` + the form as children, with no client wrapper of its own. Pass a
+custom `primaryAction` only when the button should do something else (e.g. route to a wizard),
+which disables the built-in reveal.
+
+## Deciding the status (server side)
+
+The point is to compute `status` from data you already have — e.g. for the payments page:
+
+```tsx
+const config = await getMaskedPaymentConfig(tenant.id);
+
+const status =
+  config === null            ? 'unconfigured'
+  : config.status !== 'VERIFIED' || !config.enabled ? 'in-progress'
+  : 'configured';
+
+<SectionOnboarding
+  status={status}
+  title="Receba pagamentos na sua loja"
+  description="Conecte sua conta PagBank para vender por PIX e cartão."
+  steps={[
+    { id: 'connect', label: 'Conectar conta' },
+    { id: 'homolog', label: 'Homologar' },
+    { id: 'activate', label: 'Ativar vendas' },
+  ]}
+  primaryAction={{ label: 'Começar configuração', onClick: startSetup }}
+  configuredSummary={<Chip label="Ativo — Produção" color="success" size="small" />}
+>
+  <PaymentIntegrationForm … />
+</SectionOnboarding>
+```
+
+**Note:** `SectionOnboarding` is a client component (`'use client'`) because the configured state manages a reveal toggle. Compute `status` in the server component and pass it down; wire `primaryAction.onClick` from a small client wrapper.
+
+**A11y**
+
+- The edit toggle exposes `aria-expanded`.
+- The success indicator icon is `aria-hidden`; the heading carries the meaning.
+- The hero inherits `EmptyState`'s `role="region"` + `aria-labelledby`.
+
+## Testing
+
+### Test IDs
+
+If `dataTestId` is provided it becomes the prefix; otherwise `section-onboarding` is the default.
+
+| Element | Default Test ID |
+|---------|----------------|
+| Root (carries `data-status`) | `section-onboarding` |
+| Step preview / progress | `section-onboarding-steps` |
+| Hero (unconfigured) | `section-onboarding-hero` (+ EmptyState sub-ids) |
+| Configured summary row | `section-onboarding-summary` |
+| Edit/collapse toggle | `section-onboarding-edit-toggle` |
+| Revealed content wrapper | `section-onboarding-content` |
+
+### Common scenarios
+
+- **Unconfigured** shows the hero + CTA and does **not** render the form.
+- **In-progress** shows steps **and** the form together.
+- **Configured** hides the form behind the toggle (`aria-expanded` flips on click); `defaultExpanded` starts it open.
+- **No `steps`** → no stepper preview, hero still renders.
+- **No `children`** in configured → no edit toggle offered.
+
+See `SectionOnboarding.test.stories.tsx` for the interaction tests covering each.

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

@@ -0,0 +1,160 @@
+import { CreditCard } from '@mui/icons-material';
+import { Box, Chip, SvgIcon, TextField, Typography } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { fn } from 'storybook/test';
+
+import { SectionOnboarding } from './SectionOnboarding';
+
+const PaymentIllustration = () => (
+  <SvgIcon sx={{ fontSize: 72, color: 'primary.main' }}>
+    <CreditCard />
+  </SvgIcon>
+);
+
+/** Stand-in for the real credential form the section wraps. */
+const MockForm = () => (
+  <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2, maxWidth: 480 }}>
+    <TextField label="Token do PagBank" type="password" fullWidth size="small" />
+    <TextField label="Chave pública do cartão (opcional)" fullWidth size="small" />
+  </Box>
+);
+
+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',
+  component: SectionOnboarding,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Per-section onboarding wrapper: one config surface renders three ways ' +
+          '(unconfigured hero → in-progress steps + form → configured summary) so ' +
+          'first-time users meet a friendly CTA instead of a wall of empty fields. ' +
+          'Composes EmptyState + Stepper.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    status: {
+      control: { type: 'select' },
+      options: ['unconfigured', 'in-progress', 'configured'],
+    },
+    children: { control: false },
+    illustration: { control: false },
+    configuredSummary: { control: false },
+    steps: { control: false },
+    primaryAction: { control: false },
+    secondaryAction: { control: false },
+    helpLink: { control: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Unconfigured: Story = {
+  args: {
+    status: 'unconfigured',
+    title: 'Receba pagamentos na sua loja',
+    description:
+      'Conecte sua conta PagBank para vender por PIX e cartão de crédito. Leva alguns minutos e você só ativa quando estiver tudo pronto.',
+    illustration: <PaymentIllustration />,
+    steps: SETUP_STEPS,
+    primaryAction: { label: 'Começar configuração', onClick: fn() },
+    secondaryAction: { label: 'Ver como funciona', onClick: fn() },
+    helpLink: { label: 'Dúvidas? Fale com o suporte', href: '#', external: true },
+  },
+};
+
+export const UnconfiguredNoSteps: Story = {
+  args: {
+    status: 'unconfigured',
+    title: 'Configure a integração com IA',
+    description: 'Deixe a IA responder perguntas do seu cardápio automaticamente.',
+    primaryAction: { label: 'Começar', onClick: fn() },
+  },
+};
+
+export const InProgress: Story = {
+  args: {
+    status: 'in-progress',
+    title: 'Conectar conta PagBank',
+    steps: SETUP_STEPS,
+    activeStepId: 'connect',
+    completedStepIds: [],
+    children: <MockForm />,
+  },
+};
+
+export const InProgressSecondStep: Story = {
+  args: {
+    status: 'in-progress',
+    title: 'Homologação',
+    steps: SETUP_STEPS,
+    activeStepId: 'homolog',
+    completedStepIds: ['connect'],
+    children: <MockForm />,
+  },
+};
+
+export const Configured: Story = {
+  args: {
+    status: 'configured',
+    title: 'PagBank',
+    configuredTitle: 'PagBank conectado',
+    configuredSummary: (
+      <Box sx={{ display: 'flex', gap: 1, alignItems: 'center', mt: 0.5 }}>
+        <Chip label="Ativo" color="success" size="small" />
+        <Typography variant="body2" color="text.secondary">
+          Ambiente: Produção
+        </Typography>
+      </Box>
+    ),
+    children: <MockForm />,
+  },
+};
+
+export const ConfiguredExpanded: Story = {
+  args: {
+    ...Configured.args,
+    defaultExpanded: true,
+  },
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+      <SectionOnboarding
+        status="unconfigured"
+        title="Receba pagamentos na sua loja"
+        description="Conecte sua conta PagBank para vender por PIX e cartão."
+        illustration={<PaymentIllustration />}
+        steps={SETUP_STEPS}
+        primaryAction={{ label: 'Começar configuração', onClick: fn() }}
+      />
+      <SectionOnboarding
+        status="in-progress"
+        title="Conectar conta PagBank"
+        steps={SETUP_STEPS}
+        activeStepId="connect"
+      >
+        <MockForm />
+      </SectionOnboarding>
+      <SectionOnboarding
+        status="configured"
+        title="PagBank"
+        configuredTitle="PagBank conectado"
+        configuredSummary={<Chip label="Ativo — Produção" color="success" size="small" />}
+      >
+        <MockForm />
+      </SectionOnboarding>
+    </Box>
+  ),
+};