@soyfri/shared-library 2.0.0-beta.2 → 2.0.0-beta.20

package/src/components/Stepper/Stepper.tsx

@@ -0,0 +1,194 @@
+import {
+  Children,
+  isValidElement,
+  type FC,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  Stepper as MuiStepper,
+  Step as MuiStep,
+  StepLabel as MuiStepLabel,
+  Box,
+} from '@mui/material';
+
+import { StepProps } from './Step';
+import { useStepper } from './StepperContext';
+import { useHorizontalScroll } from './_hooks/useHorizontalScroll';
+import { StepperScrollArrow } from './_parts/StepperScrollArrow';
+
+export interface StepperProps {
+  /** Uno o varios `<Step>`. Children que no sean `<Step>` se ignoran. */
+  children: ReactNode;
+  orientation?: 'horizontal' | 'vertical';
+  alternateLabel?: boolean;
+  /**
+   * Índice 0-based del paso activo. Si no se provee, el Stepper intenta
+   * leerlo del `StepperContext` (si está dentro de un `<StepperProvider>`).
+   * Si tampoco hay provider, el default es 0.
+   */
+  currentStep?: number;
+  keepMounted?: boolean;
+  sx?: object;
+}
+
+export const Stepper: FC<StepperProps> = ({
+  children,
+  orientation = 'horizontal',
+  alternateLabel = false,
+  currentStep: currentStepProp,
+  keepMounted = false,
+  sx,
+}) => {
+  // Lee el paso desde el StepperContext cuando el consumer no lo pasa como prop.
+  const stepperCtx = useStepper();
+  const currentStep =
+    currentStepProp !== undefined
+      ? currentStepProp
+      : stepperCtx.totalSteps > 0
+        ? stepperCtx.currentStep
+        : 0;
+
+  const isHorizontal = orientation === 'horizontal';
+
+  // Filtra los children a los que tengan displayName="Step" — acepta arrays,
+  // single child, fragments, y descarta cualquier otra cosa (strings, null, etc.).
+  const steps: ReactElement<StepProps>[] = Children.toArray(children).filter(
+    (child): child is ReactElement<StepProps> =>
+      isValidElement(child) &&
+      (child.type as { displayName?: string })?.displayName === 'Step',
+  );
+
+  const { scrollRef, canScrollLeft, canScrollRight, scrollBy } = useHorizontalScroll(
+    isHorizontal,
+    [steps.length, currentStep],
+  );
+
+  const showArrows = isHorizontal && (canScrollLeft || canScrollRight);
+
+  return (
+    <Box sx={sx}>
+      <Box
+        sx={
+          isHorizontal
+            ? { display: 'flex', alignItems: 'center', width: '100%', gap: 0.5 }
+            : undefined
+        }
+      >
+        {isHorizontal && (
+          <StepperScrollArrow
+            direction="left"
+            enabled={canScrollLeft}
+            visible={showArrows}
+            onClick={() => scrollBy(-160)}
+          />
+        )}
+        <Box
+          ref={scrollRef}
+          sx={
+            isHorizontal
+              ? {
+                flex: '1 1 auto',
+                minWidth: 0,
+                overflowX: 'auto',
+                scrollBehavior: 'smooth',
+                WebkitOverflowScrolling: 'touch',
+                scrollbarWidth: 'none',
+                '&::-webkit-scrollbar': { display: 'none' },
+              }
+              : undefined
+          }
+        >
+          <MuiStepper
+            activeStep={currentStep}
+            orientation={orientation}
+            alternativeLabel={alternateLabel}
+            sx={
+              isHorizontal
+                ? {
+                  display: 'inline-flex',
+                  flexWrap: 'nowrap',
+                  minWidth: '100%',
+                  width: 'max-content',
+                  '& .MuiStep-root': { flex: '0 0 auto', minWidth: 120 },
+                }
+                : undefined
+            }
+          >
+            {steps.map((step, idx) => {
+              const {
+                label,
+                completed,
+                disabled,
+                className,
+                sx: stepSx,
+                dotColor,
+                activeDotColor,
+                completedDotColor,
+                iconTextColor,
+              } = step.props;
+              const key = step.key ?? idx;
+              return (
+                <MuiStep
+                  key={key}
+                  completed={completed}
+                  disabled={disabled}
+                  className={className}
+                  sx={stepSx}
+                >
+                  <MuiStepLabel
+                    sx={{
+                      pointerEvents: 'none',
+                      '& .MuiStepIcon-root': { color: dotColor },
+                      '& .MuiStepIcon-active': { color: activeDotColor },
+                      '& .MuiStepIcon-completed': { color: completedDotColor },
+                      '& .MuiStepIcon-text': { fill: iconTextColor },
+                    }}
+                  >
+                    {label}
+                  </MuiStepLabel>
+                </MuiStep>
+              );
+            })}
+          </MuiStepper>
+        </Box>
+        {isHorizontal && (
+          <StepperScrollArrow
+            direction="right"
+            enabled={canScrollRight}
+            visible={showArrows}
+            onClick={() => scrollBy(160)}
+          />
+        )}
+      </Box>
+
+      {/* Cuerpos de los steps — render según el modo `keepMounted` */}
+      <Box mt={2}>
+        {keepMounted
+          ? steps.map((step, idx) => {
+            const key = step.key ?? idx;
+            const isActive = idx === currentStep;
+            return (
+              <Box
+                key={key}
+                // `display: none` mantiene el nodo en el DOM — state de los
+                // hijos (inputs, useState, etc.) no se pierde al navegar.
+                sx={{ display: isActive ? 'block' : 'none' }}
+                // Accesibilidad: oculta del flujo de lectura pero no del DOM.
+                aria-hidden={!isActive}
+              >
+                {step.props.children}
+              </Box>
+            );
+          })
+          : steps.map((step, idx) => {
+            if (idx !== currentStep) return null;
+            const key = step.key ?? idx;
+            return <Box key={key}>{step.props.children}</Box>;
+          })}
+      </Box>
+    </Box>
+  );
+};
+
+export default Stepper;

package/src/components/Stepper/StepperContext.tsx

@@ -0,0 +1,176 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  type FC,
+  type ReactNode,
+} from 'react';
+
+/**
+ * API expuesta por `useStepper()`.
+ */
+export interface StepperContextValue {
+  /** Índice del paso actual (0-based). */
+  currentStep: number;
+  /** Total de pasos del stepper. */
+  totalSteps: number;
+  /** True si `currentStep === 0`. */
+  isFirst: boolean;
+  /** True si `currentStep === totalSteps - 1`. */
+  isLast: boolean;
+  /** True tras ejecutar `submitStep()` desde el último paso. */
+  completed: boolean;
+  /** Avanza al siguiente paso (no pasa de `totalSteps - 1`). */
+  nextStep: () => void;
+  /** Retrocede al paso anterior (no baja de 0). */
+  prevStep: () => void;
+  /** Salta a un paso específico (0-based). No-op si fuera de rango. */
+  goToStep: (stepNumber: number) => void;
+  /**
+   * Envía el stepper. Marca `completed = true` y dispara el callback
+   * `onSubmit` del provider. En el último paso suele reemplazar a `nextStep`.
+   */
+  submitStep: () => void;
+  /** Resetea al paso inicial y limpia `completed`. */
+  reset: () => void;
+}
+
+const defaultValue: StepperContextValue = {
+  currentStep: 0,
+  totalSteps: 0,
+  isFirst: true,
+  isLast: true,
+  completed: false,
+  nextStep: () => {},
+  prevStep: () => {},
+  goToStep: () => {},
+  submitStep: () => {},
+  reset: () => {},
+};
+
+export const StepperContext = createContext<StepperContextValue>(defaultValue);
+
+/**
+ * Hook para consumir el `StepperContext` desde cualquier descendiente de
+ * `<StepperProvider>`.
+ *
+ * Si se llama fuera de un provider, devuelve los valores por defecto (no-op)
+ * para que componentes como `<Stepper>` puedan leerlo sin romper cuando no
+ * hay provider envolvente.
+ */
+export function useStepper(): StepperContextValue {
+  return useContext(StepperContext);
+}
+
+export interface StepperProviderProps {
+  /** Número total de pasos. Requerido. */
+  totalSteps: number;
+  /** Paso inicial (0-based). Default: 0. */
+  initialStep?: number;
+  /**
+   * Callback disparado cuando se llama `submitStep()`. Recibe el paso actual.
+   * El paquete NO ejecuta ninguna petición; queda a cargo del consumer.
+   */
+  onSubmit?: (currentStep: number) => void;
+  /**
+   * Callback disparado en cada cambio de paso (next/prev/goTo).
+   * Útil para tracking o validaciones externas.
+   */
+  onStepChange?: (newStep: number, prevStep: number) => void;
+  children?: ReactNode;
+}
+
+/**
+ * Provider del stepper. Administra el `currentStep` internamente. El consumer
+ * no necesita gestionar estado — solo consumirlo con `useStepper()` desde
+ * cualquier descendiente.
+ *
+ * ```tsx
+ * <StepperProvider totalSteps={3} onSubmit={handleFinalSubmit}>
+ *   <Stepper>
+ *     <Step label="Paso 1"><StepOne /></Step>
+ *     <Step label="Paso 2"><StepTwo /></Step>
+ *     <Step label="Paso 3"><StepThree /></Step>
+ *   </Stepper>
+ *   <StepperControls />
+ * </StepperProvider>
+ * ```
+ */
+export const StepperProvider: FC<StepperProviderProps> = ({
+  totalSteps,
+  initialStep = 0,
+  onSubmit,
+  onStepChange,
+  children,
+}) => {
+  const [currentStep, setCurrentStep] = useState(initialStep);
+  const [completed, setCompleted] = useState(false);
+
+  const changeStep = useCallback(
+    (newStep: number) => {
+      setCurrentStep((prev) => {
+        if (newStep === prev) return prev;
+        if (newStep < 0 || newStep >= totalSteps) return prev;
+        onStepChange?.(newStep, prev);
+        return newStep;
+      });
+    },
+    [totalSteps, onStepChange],
+  );
+
+  const nextStep = useCallback(() => {
+    changeStep(currentStep + 1);
+  }, [changeStep, currentStep]);
+
+  const prevStep = useCallback(() => {
+    changeStep(currentStep - 1);
+  }, [changeStep, currentStep]);
+
+  const goToStep = useCallback(
+    (stepNumber: number) => {
+      changeStep(stepNumber);
+    },
+    [changeStep],
+  );
+
+  const submitStep = useCallback(() => {
+    setCompleted(true);
+    onSubmit?.(currentStep);
+  }, [currentStep, onSubmit]);
+
+  const reset = useCallback(() => {
+    setCurrentStep(initialStep);
+    setCompleted(false);
+  }, [initialStep]);
+
+  const value = useMemo<StepperContextValue>(
+    () => ({
+      currentStep,
+      totalSteps,
+      isFirst: currentStep === 0,
+      isLast: currentStep === totalSteps - 1,
+      completed,
+      nextStep,
+      prevStep,
+      goToStep,
+      submitStep,
+      reset,
+    }),
+    [
+      currentStep,
+      totalSteps,
+      completed,
+      nextStep,
+      prevStep,
+      goToStep,
+      submitStep,
+      reset,
+    ],
+  );
+
+  return (
+    <StepperContext.Provider value={value}>{children}</StepperContext.Provider>
+  );
+};

package/src/components/Stepper/StepperProvider.stories.tsx

@@ -0,0 +1,286 @@
+import { useEffect, useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box, Button, Paper, Stack, Typography, Alert } from '@mui/material';
+
+import { StepperProvider, useStepper } from './StepperContext';
+import Stepper from './Stepper';
+import Step from './Step';
+
+const meta: Meta = {
+  title: 'Components/Stepper/Provider',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Provider + hook para administrar la navegación de un stepper multi-paso. `<StepperProvider>` mantiene el `currentStep`; `useStepper()` permite a cualquier descendiente leer el estado y llamar `nextStep`, `prevStep`, `goToStep`, `submitStep`, `reset`.',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+// ── Sub-componente: controles del stepper ────────────────────────────────
+
+const StepperControls = () => {
+  const {
+    currentStep,
+    totalSteps,
+    isFirst,
+    isLast,
+    nextStep,
+    prevStep,
+    submitStep,
+    reset,
+    completed,
+  } = useStepper();
+
+  return (
+    <Stack direction="row" spacing={1} justifyContent="flex-end" sx={{ mt: 3 }}>
+      <Button variant="text" onClick={reset} disabled={completed}>
+        Reiniciar
+      </Button>
+      <Button variant="outlined" onClick={prevStep} disabled={isFirst || completed}>
+        Atrás
+      </Button>
+      {isLast ? (
+        <Button
+          variant="contained"
+          color="primary"
+          onClick={submitStep}
+          disabled={completed}
+        >
+          {completed ? 'Enviado' : 'Enviar'}
+        </Button>
+      ) : (
+        <Button variant="contained" onClick={nextStep}>
+          Siguiente
+        </Button>
+      )}
+      <Typography variant="caption" color="text.secondary" sx={{ alignSelf: 'center', ml: 2 }}>
+        Paso {currentStep + 1} de {totalSteps}
+      </Typography>
+    </Stack>
+  );
+};
+
+// ── Story 1: stepper básico ──────────────────────────────────────────────
+
+const BasicStepperBody = () => {
+  const { currentStep, completed } = useStepper();
+
+  return (
+    <Paper sx={{ p: 3, maxWidth: 720, mx: 'auto' }}>
+      {completed && (
+        <Alert severity="success" sx={{ mb: 2 }}>
+          ¡Stepper enviado! Usá "Reiniciar" para volver al paso 1.
+        </Alert>
+      )}
+
+      <Stepper>
+        <Step label="Datos personales">
+          <Box sx={{ p: 2 }}>
+            <Typography variant="h6">Paso 1 — Datos personales</Typography>
+            <Typography color="text.secondary">
+              Acá iría el formulario de nombre, email, teléfono, etc.
+            </Typography>
+          </Box>
+        </Step>
+        <Step label="Dirección">
+          <Box sx={{ p: 2 }}>
+            <Typography variant="h6">Paso 2 — Dirección</Typography>
+            <Typography color="text.secondary">
+              Acá iría el formulario de dirección, ciudad, país.
+            </Typography>
+          </Box>
+        </Step>
+        <Step label="Confirmación">
+          <Box sx={{ p: 2 }}>
+            <Typography variant="h6">Paso 3 — Confirmación</Typography>
+            <Typography color="text.secondary">
+              Revisá los datos antes de enviar.
+            </Typography>
+          </Box>
+        </Step>
+      </Stepper>
+
+      <StepperControls />
+      <Typography
+        variant="caption"
+        color="text.secondary"
+        sx={{ display: 'block', mt: 1, textAlign: 'right' }}
+      >
+        Paso actual (0-based): {currentStep}
+      </Typography>
+    </Paper>
+  );
+};
+
+export const Basic: Story = {
+  render: () => (
+    <StepperProvider
+      totalSteps={3}
+      onSubmit={(step) => console.log('Submit desde paso', step)}
+      onStepChange={(newStep, prevStep) =>
+        console.log(`Cambio: ${prevStep} → ${newStep}`)
+      }
+    >
+      <BasicStepperBody />
+    </StepperProvider>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Stepper de 3 pasos. El `Stepper` lee `currentStep` del `StepperContext` automáticamente. Los controles usan `useStepper()` para `nextStep`, `prevStep`, `submitStep` y `reset`. Mirá la consola para ver los callbacks `onStepChange` y `onSubmit`.',
+      },
+    },
+  },
+};
+
+// ── Story 2: con validación por paso ─────────────────────────────────────
+
+const ValidatedStepperBody = () => {
+  const { currentStep, isLast, nextStep, prevStep, submitStep, completed } =
+    useStepper();
+  const [canAdvance, setCanAdvance] = useState(false);
+
+  // Cada vez que cambia el paso, reseteamos el "canAdvance" como si hubiera
+  // que validar de nuevo.
+  useEffect(() => {
+    setCanAdvance(false);
+  }, [currentStep]);
+
+  const handleValidate = () => setCanAdvance(true);
+
+  return (
+    <Paper sx={{ p: 3, maxWidth: 720, mx: 'auto' }}>
+      {completed && (
+        <Alert severity="success" sx={{ mb: 2 }}>
+          Stepper completado.
+        </Alert>
+      )}
+
+      <Stepper>
+        <Step label="Paso A">
+          <Box sx={{ p: 2 }}>
+            <Typography>Validá este paso para continuar.</Typography>
+          </Box>
+        </Step>
+        <Step label="Paso B">
+          <Box sx={{ p: 2 }}>
+            <Typography>Validá este paso para continuar.</Typography>
+          </Box>
+        </Step>
+        <Step label="Paso C">
+          <Box sx={{ p: 2 }}>
+            <Typography>Último paso — envía el stepper.</Typography>
+          </Box>
+        </Step>
+      </Stepper>
+
+      <Stack direction="row" spacing={1} justifyContent="flex-end" sx={{ mt: 3 }}>
+        <Button variant="text" onClick={handleValidate} disabled={canAdvance}>
+          {canAdvance ? 'Paso válido ✓' : 'Validar paso'}
+        </Button>
+        <Button variant="outlined" onClick={prevStep} disabled={currentStep === 0}>
+          Atrás
+        </Button>
+        {isLast ? (
+          <Button
+            variant="contained"
+            onClick={submitStep}
+            disabled={!canAdvance || completed}
+          >
+            Enviar
+          </Button>
+        ) : (
+          <Button variant="contained" onClick={nextStep} disabled={!canAdvance}>
+            Siguiente
+          </Button>
+        )}
+      </Stack>
+    </Paper>
+  );
+};
+
+export const WithPerStepValidation: Story = {
+  render: () => (
+    <StepperProvider totalSteps={3} onSubmit={() => console.log('Enviado!')}>
+      <ValidatedStepperBody />
+    </StepperProvider>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Patrón típico: el botón "Siguiente" queda deshabilitado hasta que el consumer valide el paso actual (normalmente con react-hook-form `trigger()`). El hook solo maneja la navegación — la validación es del consumer.',
+      },
+    },
+  },
+};
+
+// ── Story 3: navegación por click ────────────────────────────────────────
+
+const JumpableStepperBody = () => {
+  const { currentStep, totalSteps, goToStep, nextStep, prevStep } = useStepper();
+
+  return (
+    <Paper sx={{ p: 3, maxWidth: 720, mx: 'auto' }}>
+      <Typography variant="subtitle1" sx={{ mb: 2 }}>
+        Saltar a un paso específico
+      </Typography>
+
+      <Stack direction="row" spacing={1} sx={{ mb: 3 }}>
+        {Array.from({ length: totalSteps }).map((_, i) => (
+          <Button
+            key={i}
+            size="small"
+            variant={i === currentStep ? 'contained' : 'outlined'}
+            onClick={() => goToStep(i)}
+          >
+            Paso {i + 1}
+          </Button>
+        ))}
+      </Stack>
+
+      <Stepper>
+        <Step label="Uno"><Box sx={{ p: 2 }}>Paso 1</Box></Step>
+        <Step label="Dos"><Box sx={{ p: 2 }}>Paso 2</Box></Step>
+        <Step label="Tres"><Box sx={{ p: 2 }}>Paso 3</Box></Step>
+        <Step label="Cuatro"><Box sx={{ p: 2 }}>Paso 4</Box></Step>
+      </Stepper>
+
+      <Stack direction="row" spacing={1} justifyContent="flex-end" sx={{ mt: 3 }}>
+        <Button variant="outlined" onClick={prevStep} disabled={currentStep === 0}>
+          Atrás
+        </Button>
+        <Button
+          variant="contained"
+          onClick={nextStep}
+          disabled={currentStep === totalSteps - 1}
+        >
+          Siguiente
+        </Button>
+      </Stack>
+    </Paper>
+  );
+};
+
+export const JumpToStep: Story = {
+  render: () => (
+    <StepperProvider totalSteps={4}>
+      <JumpableStepperBody />
+    </StepperProvider>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`goToStep(n)` para saltar a un paso específico. Útil cuando hay un sidebar o tabs que permiten navegación no-lineal (asumiendo que el consumer valide antes de permitir el salto).',
+      },
+    },
+  },
+};

package/src/components/Stepper/_hooks/useHorizontalScroll.ts

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+/**
+ * Hook interno del Stepper para manejar scroll horizontal cuando los steps
+ * no caben en el contenedor. No se exporta desde el barrel — es un detalle
+ * de implementación.
+ *
+ * @param enabled - Si el scroll está activo (típicamente sólo en orientación horizontal).
+ * @param deps    - Cosas que afectan el layout y disparan un recompute (ej. cantidad de steps, paso activo).
+ *
+ * Retorna:
+ * - `scrollRef`: ref a asignar al contenedor con `overflow-x: auto`.
+ * - `canScrollLeft` / `canScrollRight`: flags para habilitar/deshabilitar flechas.
+ * - `scrollBy(delta)`: imperativo con scroll suave.
+ */
+export function useHorizontalScroll(enabled: boolean, deps: unknown[] = []) {
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  const [canScrollLeft, setCanScrollLeft] = useState(false);
+  const [canScrollRight, setCanScrollRight] = useState(false);
+
+  const updateScrollState = useCallback(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const { scrollLeft, scrollWidth, clientWidth } = el;
+    // Tolerancia de 1px por redondeos de subpixel.
+    setCanScrollLeft(scrollLeft > 1);
+    setCanScrollRight(scrollLeft + clientWidth < scrollWidth - 1);
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!enabled) return;
+    updateScrollState();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, updateScrollState, ...deps]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const el = scrollRef.current;
+    if (!el) return;
+    el.addEventListener('scroll', updateScrollState, { passive: true });
+    const ro = new ResizeObserver(updateScrollState);
+    ro.observe(el);
+    return () => {
+      el.removeEventListener('scroll', updateScrollState);
+      ro.disconnect();
+    };
+  }, [enabled, updateScrollState]);
+
+  const scrollBy = useCallback((delta: number) => {
+    const el = scrollRef.current;
+    if (!el) return;
+    el.scrollBy({ left: delta, behavior: 'smooth' });
+  }, []);
+
+  return { scrollRef, canScrollLeft, canScrollRight, scrollBy };
+}