@12-apps/ui 1.0.0 → 1.3.1

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

@@ -1,68 +1,24 @@
-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 { resolveProgressProps } from './Progress.helpers';
+import {
+  barEmphasisStyles,
+  barVariantStyles,
+  circularEmphasisStyles,
+  getColorFromTheme,
+  getSizeStyles,
+  pulseAnimation,
+} from './Progress.styles';
 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),
@@ -72,7 +28,7 @@ const StyledLinearProgress = styled(LinearProgress, {
   customColor?: string;
   glow?: boolean;
   pulse?: boolean;
-}>(({ theme, customVariant, customSize = 'md', customColor = 'primary', glow, pulse }) => {
+}>(({ theme, customVariant, customSize, customColor = 'primary', glow, pulse }) => {
   const colorPalette = getColorFromTheme(theme, customColor);
   const sizeStyles = getSizeStyles(customSize);
 
@@ -84,41 +40,8 @@ const StyledLinearProgress = styled(LinearProgress, {
     '& .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`,
-        }),
+      ...barVariantStyles(customVariant, colorPalette),
+      ...barEmphasisStyles(colorPalette, glow, pulse),
     },
   };
 });
@@ -134,25 +57,7 @@ const StyledCircularProgress = styled(CircularProgress, {
 
   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`,
-      }),
+    ...circularEmphasisStyles(colorPalette, glow, pulse),
   };
 });
 
@@ -198,135 +103,202 @@ const SegmentedProgress: React.FC<{
   );
 };
 
-export const Progress = React.forwardRef<HTMLDivElement, ProgressProps>(
+interface ViewProps {
+  size: ProgressSize;
+  color: string;
+  glow: boolean;
+  pulse: boolean;
+  showLabel: boolean;
+  displayValue: number;
+  displayLabel: string;
+  /** Absent means indeterminate — the bar animates rather than reporting progress. */
+  value?: number;
+  dataTestId: string;
+}
+
+const ProgressLabel: React.FC<{ size: ProgressSize; label: string; testId: string }> = ({
+  size,
+  label,
+  testId,
+}) => (
+  <Typography
+    variant="caption"
+    sx={{
+      display: 'block',
+      textAlign: 'center',
+      mt: 1,
+      fontSize: getSizeStyles(size).fontSize,
+      fontWeight: 600,
+    }}
+    data-testid={testId}
+  >
+    {label}
+  </Typography>
+);
+
+const CircularView = React.forwardRef<
+  HTMLDivElement,
+  ViewProps & { thickness: number; circularSize?: number }
+>(
   (
     {
-      variant = 'linear',
-      size = 'md',
-      color = 'primary',
-      glow = false,
-      pulse = false,
-      showLabel = false,
-      label,
-      segments = 10,
-      thickness = 4,
-      circularSize,
+      size,
+      color,
+      glow,
+      pulse,
+      showLabel,
+      displayValue,
+      displayLabel,
       value,
-      dataTestId = 'progress',
+      dataTestId,
+      thickness,
+      circularSize,
       ...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
+      <Box ref={ref} sx={{ position: 'relative', display: 'inline-flex' }} data-testid={dataTestId}>
+        <StyledCircularProgress
           variant={value !== undefined ? 'determinate' : 'indeterminate'}
           value={displayValue}
-          customVariant={variant}
-          customSize={size}
+          size={circularSize || sizeStyles.circularSize}
+          thickness={thickness}
           customColor={color}
           glow={glow}
           pulse={pulse}
-          data-testid={`${dataTestId}-linear`}
+          data-testid={`${dataTestId}-circular`}
           {...props}
         />
-        {showLabel && (
-          <Typography
-            variant="caption"
+        {showLabel && value !== undefined && (
+          <Box
             sx={{
-              display: 'block',
-              textAlign: 'center',
-              mt: 1,
-              fontSize: sizeStyles.fontSize,
-              fontWeight: 600,
+              top: 0,
+              left: 0,
+              bottom: 0,
+              right: 0,
+              position: 'absolute',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
             }}
-            data-testid={`${dataTestId}-label`}
           >
-            {displayLabel}
-          </Typography>
+            <Typography
+              variant="caption"
+              component="div"
+              color="text.secondary"
+              sx={{ fontSize: sizeStyles.fontSize, fontWeight: 600 }}
+              data-testid={`${dataTestId}-label`}
+            >
+              {displayLabel}
+            </Typography>
+          </Box>
         )}
       </Box>
     );
   },
 );
 
+CircularView.displayName = 'ProgressCircularView';
+
+const SegmentedView = React.forwardRef<HTMLDivElement, ViewProps & { segments: number }>(
+  (
+    { size, color, glow, pulse, showLabel, displayValue, displayLabel, dataTestId, segments, value: _value, ...props },
+    ref,
+  ) => (
+    <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 && (
+        <ProgressLabel size={size} label={displayLabel} testId={`${dataTestId}-label`} />
+      )}
+    </Box>
+  ),
+);
+
+SegmentedView.displayName = 'ProgressSegmentedView';
+
+const LinearView = React.forwardRef<HTMLDivElement, ViewProps & { variant: ProgressVariant }>(
+  (
+    { size, color, glow, pulse, showLabel, displayValue, displayLabel, value, dataTestId, variant, ...props },
+    ref,
+  ) => (
+    <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 && (
+        <ProgressLabel size={size} label={displayLabel} testId={`${dataTestId}-label`} />
+      )}
+    </Box>
+  ),
+);
+
+LinearView.displayName = 'ProgressLinearView';
+
+export const Progress = React.forwardRef<HTMLDivElement, ProgressProps>(
+  (rawProps, ref) => {
+    const {
+      variant,
+      size,
+      color,
+      glow,
+      pulse,
+      showLabel,
+      label,
+      segments,
+      thickness,
+      circularSize,
+      value,
+      dataTestId,
+      // LinearProgressProps carries a `ref` typed for its own element; the
+      // forwarded one below is the ref that matters.
+      ref: _ref,
+      ...props
+    } = resolveProgressProps(rawProps);
+    const displayValue = value || 0;
+    const shared = {
+      size,
+      color,
+      glow,
+      pulse,
+      showLabel,
+      displayValue,
+      displayLabel: label || (showLabel ? `${Math.round(displayValue)}%` : ''),
+      value,
+      dataTestId,
+      ...props,
+    };
+
+    if (variant === 'circular') {
+      return (
+        <CircularView ref={ref} {...shared} thickness={thickness} circularSize={circularSize} />
+      );
+    }
+
+    if (variant === 'segmented') {
+      return <SegmentedView ref={ref} {...shared} segments={segments} />;
+    }
+
+    return <LinearView ref={ref} {...shared} variant={variant} />;
+  },
+);
+
 Progress.displayName = 'Progress';

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

@@ -1,4 +1,4 @@
-import { CreditCard } from '@mui/icons-material';
+import CreditCard from '@mui/icons-material/CreditCard';
 import { Box, Chip, SvgIcon, TextField, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { fn } from 'storybook/test';

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { CheckCircle } from '@mui/icons-material';
+import CheckCircle from '@mui/icons-material/CheckCircle';
 import { Box, Button, Collapse, Stack, Typography, useTheme } from '@mui/material';
 import React from 'react';
 

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

@@ -0,0 +1,117 @@
+# StatCard
+
+A KPI tile: one labelled figure, an optional period-over-period delta, an
+optional leading icon, an optional hint line, and a loading state. It is the
+single shared tile for dashboard KPI rows and summary bands, so surfaces stop
+hand-rolling the label/value pattern.
+
+## Features
+
+- **Pre-formatted values**: the tile never formats money, percentages or
+  locale — `value` and `delta.value` arrive as strings the caller already
+  shaped, so currency/locale rules stay with the data owner.
+- **Direction separate from meaning**: `delta.direction` picks the arrow;
+  `delta.tone` picks the colour. A rising cost can render an up arrow and still
+  read as negative.
+- **Semantic colour only**: `success.main` / `error.main` / `text.secondary`
+  from the MUI palette — no hardcoded hex, so themes and dark mode work.
+- **Accessible**: the tile is a `role="group"` labelled by its own label; the
+  arrow is `aria-hidden` and the delta carries a direction-aware sentence that
+  callers can localize.
+- **Loading state**: skeletons replace value and delta while the label stays put,
+  so a KPI grid does not reflow when data lands.
+
+## Props
+
+| Prop          | Type                    | Default | Description                                                     |
+| ------------- | ----------------------- | ------- | --------------------------------------------------------------- |
+| `label`       | `string`                | —       | What the figure measures, e.g. `"Receita"`.                      |
+| `value`       | `ReactNode`             | —       | The figure, already formatted.                                   |
+| `delta`       | `StatCardDelta`         | —       | Optional period-over-period change (see below).                  |
+| `icon`        | `ReactNode`             | —       | Optional leading icon beside the label (decorative).             |
+| `hint`        | `string`                | —       | Optional clarifying line under the value, e.g. the range.        |
+| `loading`     | `boolean`               | `false` | Swaps value/delta for skeletons and marks the tile `aria-busy`.  |
+| `className`   | `string`                | —       | Custom class on the tile root.                                   |
+| `dataTestId`  | `string`                | `'stat-card'` | Root test id; child ids derive from it.                    |
+
+### `StatCardDelta`
+
+| Field       | Type                              | Default            | Description                                                       |
+| ----------- | --------------------------------- | ------------------ | ----------------------------------------------------------------- |
+| `value`     | `string`                          | —                  | The pre-formatted change, e.g. `"+12,5%"`.                        |
+| `direction` | `'up' \| 'down' \| 'neutral'`     | —                  | Which way the metric moved (picks the arrow).                     |
+| `tone`      | `'positive' \| 'negative' \| 'neutral'` | derived from `direction` | How the movement should read (picks the colour).       |
+| `label`     | `string`                          | —                  | Comparison context, e.g. `"vs. período anterior"`.                |
+| `ariaLabel` | `string`                          | generated (English) | Overrides the screen-reader sentence — pass a localized string.  |
+
+## Usage
+
+### Basic
+
+```tsx
+import { StatCard } from '@12-apps/ui/data-display/StatCard';
+
+<StatCard label="Receita" value="R$ 12.480,00" />;
+```
+
+### With a period-over-period delta
+
+```tsx
+<StatCard
+  label="Receita"
+  value="R$ 12.480,00"
+  delta={{ value: '+12,5%', direction: 'up', label: 'vs. período anterior' }}
+/>
+```
+
+### "Lower is better" metrics
+
+Cost going up is not good news. Keep the honest arrow and override the tone:
+
+```tsx
+<StatCard
+  label="Custo (CMV)"
+  value="R$ 4.900,00"
+  delta={{ value: '+9,4%', direction: 'up', tone: 'negative' }}
+/>
+```
+
+### Loading
+
+```tsx
+<StatCard label="Receita" value={revenueLabel} delta={revenueDelta} loading={isPending} />
+```
+
+### A KPI row
+
+```tsx
+<Box sx={{ display: 'grid', gap: 2, gridTemplateColumns: 'repeat(4, 1fr)' }}>
+  <StatCard label="Receita" value={revenue} dataTestId="kpi-revenue" />
+  <StatCard label="Custo (CMV)" value={cogs} dataTestId="kpi-cogs" />
+  <StatCard label="Lucro bruto" value={profit} dataTestId="kpi-profit" />
+  <StatCard label="Pedidos" value={orders} dataTestId="kpi-orders" />
+</Box>
+```
+
+## Accessibility
+
+- The root is a `role="group"` with `aria-labelledby` pointing at the label, so
+  assistive tech announces the tile as "Receita, group" rather than reading two
+  unrelated strings.
+- The direction arrow is `aria-hidden` — it duplicates information the delta's
+  `aria-label` already carries, and would otherwise be announced twice.
+- The delta's generated sentence ("Increase of +12,5% vs. período anterior") is
+  English. Non-English apps pass `delta.ariaLabel` to localize it.
+- While `loading`, the tile sets `aria-busy="true"` and keeps its label, so the
+  metric is still identifiable before the number lands.
+
+## Best Practices
+
+- Format on the way in. If two tiles disagree about decimal places, that belongs
+  to the caller's formatter, not to the tile.
+- Set `tone` explicitly for any metric where lower is better (cost, refunds,
+  churn) — the default reading assumes higher is better.
+- Give each tile in a grid its own `dataTestId` so tests target a specific KPI
+  instead of an index.
+- Use `hint` for the measured window ("Últimos 30 dias"), not for the delta's
+  comparison text — that belongs in `delta.label`.