@soyfri/shared-library 1.5.0 → 2.0.0-beta.0

package/src/hooks/Wizard/Wizard.stories.tsx

@@ -0,0 +1,301 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box, Button, Paper, Stack, Typography, Alert } from '@mui/material';
+
+import { WizardProvider } from './WizardContext';
+import { useWizard } from './useWizard';
+import Stepper from '../../components/Stepper/Stepper';
+import Step from '../../components/Stepper/Step';
+
+const meta: Meta = {
+  title: 'Hooks/useWizard',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Hook + provider para administrar la navegación de un wizard multi-paso. Reemplaza el `StepperComponent` imperativo de Metronic y es retro-compatible con el `WizardContext` de `@soyfri/fri-web-components` (mismos nombres: `nextStep`, `prevStep`, `goToStep`, `submitStep`).',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+// ── Sub-componente: controles del wizard ─────────────────────────────────
+
+const WizardControls = () => {
+  const { currentStep, totalSteps, isFirst, isLast, nextStep, prevStep, submitStep, reset, completed } =
+    useWizard();
+
+  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: wizard básico con Stepper ──────────────────────────────────
+
+const BasicWizardBody = () => {
+  const { currentStep, completed } = useWizard();
+
+  return (
+    <Paper sx={{ p: 3, maxWidth: 720, mx: 'auto' }}>
+      {completed && (
+        <Alert severity="success" sx={{ mb: 2 }}>
+          ¡Wizard 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>
+
+      <WizardControls />
+      <Typography
+        variant="caption"
+        color="text.secondary"
+        sx={{ display: 'block', mt: 1, textAlign: 'right' }}
+      >
+        Paso actual (0-based): {currentStep}
+      </Typography>
+    </Paper>
+  );
+};
+
+export const BasicWizard: Story = {
+  render: () => (
+    <WizardProvider
+      totalSteps={3}
+      onSubmit={(step) => console.log('Submit desde paso', step)}
+      onStepChange={(newStep, prevStep) =>
+        console.log(`Cambio: ${prevStep} → ${newStep}`)
+      }
+    >
+      <BasicWizardBody />
+    </WizardProvider>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Wizard de 3 pasos. El `Stepper` lee `currentStep` del `WizardContext` automáticamente (sin necesidad de prop explícita). Los controles usan `useWizard()` para llamar `nextStep`, `prevStep`, `submitStep` y `reset`. Verifica la consola para ver los callbacks `onStepChange` y `onSubmit`.',
+      },
+    },
+  },
+};
+
+// ── Story 2: integración con validación por paso ────────────────────────
+
+const ValidatedWizardBody = () => {
+  const { currentStep, isLast, nextStep, prevStep, submitStep, completed } =
+    useWizard();
+  const [canAdvance, setCanAdvance] = React.useState(false);
+
+  // Cada vez que cambia el paso, reseteamos el "canAdvance" como si hubiera
+  // que validar de nuevo.
+  React.useEffect(() => {
+    setCanAdvance(false);
+  }, [currentStep]);
+
+  const handleValidate = () => setCanAdvance(true);
+
+  return (
+    <Paper sx={{ p: 3, maxWidth: 720, mx: 'auto' }}>
+      {completed && (
+        <Alert severity="success" sx={{ mb: 2 }}>
+          Wizard 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 wizard.</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: () => (
+    <WizardProvider
+      totalSteps={3}
+      onSubmit={() => console.log('Enviado!')}
+    >
+      <ValidatedWizardBody />
+    </WizardProvider>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Patrón común: el botón "Siguiente" permanece 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 responsabilidad del consumer.',
+      },
+    },
+  },
+};
+
+// ── Story 3: navegación directa por click en steps ──────────────────────
+
+const JumpableWizardBody = () => {
+  const { currentStep, totalSteps, goToStep, nextStep, prevStep } = useWizard();
+
+  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: () => (
+    <WizardProvider totalSteps={4}>
+      <JumpableWizardBody />
+    </WizardProvider>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Uso de `goToStep(n)` para saltar a un paso específico. Útil cuando hay un sidebar o tabs que permiten navegación no-lineal (siempre y cuando el consumer valide antes de permitir el salto).',
+      },
+    },
+  },
+};

package/src/hooks/Wizard/WizardContext.tsx

@@ -0,0 +1,166 @@
+import React, {
+  createContext,
+  useCallback,
+  useMemo,
+  useState,
+  type FC,
+  type ReactNode,
+} from 'react';
+
+/**
+ * API expuesta por `useWizard()`.
+ *
+ * Nota de retro-compatibilidad: los nombres `submitStep`, `nextStep`,
+ * `prevStep`, `goToStep` se mantienen idénticos al `WizardContext` de
+ * `@soyfri/fri-web-components` para que consumers migrando no tengan que
+ * cambiar sus llamadas. Se agregan campos extra opcionales que antes no
+ * existían (`currentStep`, `totalSteps`, `isFirst`, `isLast`, `completed`).
+ */
+export interface WizardContextValue {
+  /** Índice del paso actual (0-based). */
+  currentStep: number;
+  /** Total de pasos del wizard. */
+  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 wizard. Marca `completed = true` y dispara el callback
+   * `onSubmit` del provider. En el último paso suele reemplazar a `nextStep`.
+   */
+  submitStep: () => void;
+  /** Resetea el wizard al paso inicial y limpia `completed`. */
+  reset: () => void;
+}
+
+const defaultValue: WizardContextValue = {
+  currentStep: 0,
+  totalSteps: 0,
+  isFirst: true,
+  isLast: true,
+  completed: false,
+  nextStep: () => {},
+  prevStep: () => {},
+  goToStep: () => {},
+  submitStep: () => {},
+  reset: () => {},
+};
+
+export const WizardContext = createContext<WizardContextValue>(defaultValue);
+
+export interface WizardProviderProps {
+  /** Número total de pasos del wizard. 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 wizard. Administra el `currentStep` internamente. El consumer
+ * no necesita gestionar estado — sólo consumirlo con `useWizard()` desde
+ * cualquier descendiente.
+ *
+ * ```tsx
+ * <WizardProvider totalSteps={3} onSubmit={handleFinalSubmit}>
+ *   <Stepper ... />
+ *   <StepContent />
+ *   <WizardControls />
+ * </WizardProvider>
+ * ```
+ */
+export const WizardProvider: FC<WizardProviderProps> = ({
+  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<WizardContextValue>(
+    () => ({
+      currentStep,
+      totalSteps,
+      isFirst: currentStep === 0,
+      isLast: currentStep === totalSteps - 1,
+      completed,
+      nextStep,
+      prevStep,
+      goToStep,
+      submitStep,
+      reset,
+    }),
+    [
+      currentStep,
+      totalSteps,
+      completed,
+      nextStep,
+      prevStep,
+      goToStep,
+      submitStep,
+      reset,
+    ],
+  );
+
+  return (
+    <WizardContext.Provider value={value}>{children}</WizardContext.Provider>
+  );
+};

package/src/hooks/Wizard/index.ts

@@ -0,0 +1,6 @@
+export { useWizard } from './useWizard';
+export {
+  WizardProvider,
+  WizardContext,
+} from './WizardContext';
+export type { WizardContextValue, WizardProviderProps } from './WizardContext';

package/src/hooks/Wizard/useWizard.ts

@@ -0,0 +1,13 @@
+import { useContext } from 'react';
+import { WizardContext, type WizardContextValue } from './WizardContext';
+
+/**
+ * Hook para consumir el `WizardContext` desde cualquier descendiente de
+ * `<WizardProvider>`.
+ *
+ * Si se llama fuera de un provider, devuelve los valores por defecto (no-op)
+ * para mantener compatibilidad con el hook original de fri-web-components.
+ */
+export function useWizard(): WizardContextValue {
+  return useContext(WizardContext);
+}

package/src/index.ts

@@ -1 +1,17 @@
-import './styles.css';
+import './styles.css';
+
+// ── Sistema de presets de estilos (theme.styles) ─────────────────────────
+// Exportar el módulo de tipos ejecuta el `declare module '@mui/material/styles'`
+// para que los consumers tengan `theme.styles` tipado sin imports extra.
+export type {
+  LibraryComponentName,
+  PresetStyle,
+  ComponentPresets,
+  LibraryStyles,
+} from './theme/componentStyles';
+export { DEFAULT_PRESET_NAME, resolvePreset } from './components/_shared/resolvePreset';
+import './theme/componentStyles';
+
+// ── Pass-through de MUI (punto de entrada único para el consumer) ─────────
+// Regla: el consumer nunca importa de '@mui/material'. Todo viene de acá.
+export * from './mui';

package/src/mui.ts

@@ -0,0 +1,44 @@
+// -----------------------------------------------------------------------------
+// Pass-through puro de primitivos de MUI.
+//
+// Regla para el consumer: si está en `@soyfri/shared-library`, impórtalo desde
+// acá. NUNCA directamente desde `@mui/material`. Esto nos da un único punto de
+// entrada y facilita un eventual cambio de librería base.
+//
+// Este archivo NO wrappea nada — solo re-exporta. Si se necesita otro
+// primitivo, agregar la línea correspondiente.
+// -----------------------------------------------------------------------------
+
+// ── Layout primitives ────────────────────────────────────────────────────
+export {
+  Box,
+  Stack,
+  Grid,
+  Container,
+  Paper,
+  Divider,
+} from '@mui/material';
+
+// ── Tipografía ────────────────────────────────────────────────────────────
+export { Typography, Link } from '@mui/material';
+
+// ── Feedback / misc ───────────────────────────────────────────────────────
+export {
+  CircularProgress,
+  LinearProgress,
+  Skeleton,
+  Alert,
+  AlertTitle,
+  Snackbar,
+  Backdrop,
+  Fade,
+  Grow,
+  Zoom,
+  Collapse,
+} from '@mui/material';
+
+// ── Hooks y utilidades de tema ───────────────────────────────────────────
+export { useTheme, useMediaQuery, alpha, styled } from '@mui/material';
+
+// ── Tipos más usados ──────────────────────────────────────────────────────
+export type { SxProps, Theme } from '@mui/material/styles';

package/src/theme/componentStyles.ts

@@ -0,0 +1,47 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+
+/**
+ * Lista de componentes del paquete que soportan presets registrables en el
+ * theme. Si en el futuro se agrega otro componente al sistema, se extiende
+ * esta union.
+ */
+export type LibraryComponentName =
+  | 'Input'
+  | 'Select'
+  | 'Autocomplete'
+  | 'DatePicker'
+  | 'DateTimePicker'
+  | 'Drawer'
+  | 'AppBar'
+  | 'Card'
+  | 'ScrollTopButton';
+
+/**
+ * Un estilo de preset. Puede ser un objeto sx directo o una función del theme
+ * para acceder a palette/typography/etc.
+ */
+export type PresetStyle = SxProps<Theme> | ((theme: Theme) => SxProps<Theme>);
+
+/**
+ * Map de presets disponibles para un componente. Las keys son nombres libres
+ * elegidos por el consumidor (p.ej. `reddit`, `compact-filled`). El paquete
+ * no registra ninguna entrada: `preset="default"` significa "usar el estilo
+ * built-in de fábrica" y no requiere registro.
+ */
+export type ComponentPresets = Record<string, PresetStyle>;
+
+/**
+ * Shape del namespace `theme.styles` — un map de componentes del paquete a
+ * sus presets registrados.
+ */
+export type LibraryStyles = Partial<Record<LibraryComponentName, ComponentPresets>>;
+
+// ── Module augmentation de MUI ───────────────────────────────────────────
+declare module '@mui/material/styles' {
+  interface Theme {
+    styles: LibraryStyles;
+  }
+  interface ThemeOptions {
+    styles?: LibraryStyles;
+  }
+}

package/src/theme/tokens.ts

@@ -0,0 +1,43 @@
+/**
+ * Design tokens compartidos por los componentes de formulario
+ * (Input, Select, Autocomplete, DatePicker, DateTimePicker).
+ *
+ * Centralizar estos valores garantiza que:
+ * - el espaciado, la tipografía y las animaciones del label sean idénticos
+ *   en todos los campos;
+ * - un cambio visual global (p.ej. cambiar el transform del shrink) se haga
+ *   en un único archivo.
+ */
+
+// ── Spacing ──────────────────────────────────────────────────────────────
+/** Margen superior que deja el aire para el label flotante "outside". */
+export const LABEL_MARGIN_TOP = '14px';
+
+/** Padding vertical interno del input (TextField/Select/Picker sections). */
+export const FIELD_INPUT_PADDING_Y = '8.5px';
+
+// ── Label animation ──────────────────────────────────────────────────────
+/** Transform que aplica el label cuando sube arriba del input (shrink). */
+export const LABEL_SHRINK_TRANSFORM = 'translate(4px, -22px) scale(0.85)';
+
+/** Origen del transform para el shrink. */
+export const LABEL_TRANSFORM_ORIGIN = 'top left';
+
+/** Transición del label (color + transform + max-width). */
+export const LABEL_TRANSITION =
+  'color 200ms cubic-bezier(0.0, 0, 0.2, 1) 0ms, ' +
+  'transform 200ms cubic-bezier(0.0, 0, 0.2, 1) 0ms, ' +
+  'max-width 200ms cubic-bezier(0.0, 0, 0.2, 1) 0ms';
+
+// ── Label colors (theme-aware) ───────────────────────────────────────────
+/** Color del label en reposo. */
+export const LABEL_COLOR_REST = 'text.secondary';
+
+/** Color del label cuando el campo tiene valor (shrink). */
+export const LABEL_COLOR_FILLED = 'text.primary';
+
+/** Color del label cuando el campo está focused. */
+export const LABEL_COLOR_FOCUSED = 'primary.main';
+
+/** Peso del label cuando sube (filled/focused). */
+export const LABEL_FONT_WEIGHT_FILLED = 500;