@soyfri/shared-library 2.0.0-beta.3 → 2.0.0-beta.4

package/src/hooks/ClipBoard/ClipBoard.tsx

@@ -0,0 +1,131 @@
+// useClipboard.tsx (Versión Unificada)
+import React, { useRef, useEffect, useState, useCallback } from 'react';
+import { Snackbar, Alert } from '@mui/material';
+import { AlertProps } from '@mui/material/Alert';
+
+// Tipo para las opciones del Snackbar
+interface SnackbarOptions {
+  message?: string;
+  duration?: number;
+  severity?: AlertProps['severity'];
+  position?: { vertical: 'top' | 'bottom'; horizontal: 'left' | 'center' | 'right' };
+}
+
+/**
+ * Hook 'useClipboard'.
+ * Proporciona funcionalidad de copiado de texto y feedback visual (Snackbar).
+ * Permite dos modos de uso:
+ * 1. Uso por Referencia (ref): Se adjunta a un elemento, copia su innerText al hacer clic.
+ * 2. Uso por Función (copy): Recibe el texto a copiar directamente como argumento.
+ *
+ * @param options Opciones de configuración para el Snackbar de feedback.
+ * @returns Un objeto que contiene:
+ * - 'ref': Una React Ref para adjuntar a un elemento (Modo Ref).
+ * - 'copy': Una función (text: string) => void para copiar texto (Modo Función).
+ * - 'CopyMessage': El componente Snackbar para renderizar el feedback.
+ */
+export function useClipboard(options?: SnackbarOptions) {
+  // --- Elementos de Copiado por Referencia ---
+  const elementRef = useRef<HTMLElement>(null);
+
+  // --- Estados y Opciones del Snackbar ---
+  const [snackbarOpen, setSnackbarOpen] = useState(false);
+  const [snackbarMessage, setSnackbarMessage] = useState(options?.message || '¡Copiado al portapapeles!');
+  const [snackbarSeverity, setSnackbarSeverity] = useState<AlertProps['severity']>(options?.severity || 'success');
+  const [snackbarPosition, setSnackbarPosition] = useState<import('@mui/material').SnackbarOrigin>(options?.position || { vertical: 'bottom', horizontal: 'center' });
+  const [snackbarDuration, setSnackbarDuration] = useState(options?.duration ?? 3000);
+
+  // Función para cerrar el Snackbar
+  const handleSnackbarClose = useCallback((event?: React.SyntheticEvent | Event, reason?: string) => {
+    if (reason === 'clickaway') {
+      return;
+    }
+    setSnackbarOpen(false);
+  }, []);
+
+  /**
+   * FUNCIÓN PRINCIPAL DE COPIADO.
+   * Se usa internamente para 'ref' y se expone para 'copy(text)'.
+   * @param text El texto exacto a copiar.
+   */
+  const executeCopy = useCallback((text: string) => {
+    try {
+      if (navigator.clipboard && window.isSecureContext) {
+        // 1. API moderna
+        navigator.clipboard.writeText(text);
+      } else {
+        // 2. Fallback usando textarea
+        const textarea = document.createElement('textarea');
+        textarea.value = text;
+        document.body.appendChild(textarea);
+        textarea.select();
+        document.execCommand('copy');
+        document.body.removeChild(textarea);
+      }
+      
+      // Mostrar éxito
+      setSnackbarMessage(options?.message || '¡Copiado al portapapeles!');
+      setSnackbarSeverity(options?.severity || 'success');
+      setSnackbarPosition(options?.position || { vertical: 'bottom', horizontal: 'center' });
+      setSnackbarDuration(options?.duration ?? 3000);
+      setSnackbarOpen(true);
+
+    } catch (err) {
+      // Mostrar error
+      console.error('Error al copiar al portapapeles:', err);
+      setSnackbarMessage('Error al copiar.');
+      setSnackbarSeverity('error');
+      setSnackbarPosition(options?.position || { vertical: 'bottom', horizontal: 'center' });
+      setSnackbarDuration(options?.duration ?? 3000);
+      setSnackbarOpen(true);
+    }
+  }, [options]); 
+
+  // --- Lógica del Modo Ref ---
+  const copyFromRef = useCallback(() => {
+    if (elementRef.current) {
+        const textToCopy = elementRef.current.innerText || '';
+        executeCopy(textToCopy);
+    }
+  }, [executeCopy]);
+
+  // Adjunta un event listener de clic al elemento referenciado (Modo Ref)
+  useEffect(() => {
+    const currentElement = elementRef.current;
+    if (currentElement) {
+      currentElement.style.cursor = 'pointer';
+      // Adjuntamos la función que copia el texto del ref
+      currentElement.addEventListener('click', copyFromRef);
+    }
+
+    return () => {
+      if (currentElement) {
+        currentElement.removeEventListener('click', copyFromRef);
+      }
+    };
+  }, [copyFromRef]);
+
+
+  // Componente Snackbar encapsulado. Solo se renderiza si duration es > 0.
+  const CopyMessage = () => {
+    if (snackbarDuration <= 0) return null; // No renderizar si la duración es 0
+
+    return (
+      <Snackbar
+        open={snackbarOpen}
+        autoHideDuration={snackbarDuration}
+        onClose={handleSnackbarClose}
+        anchorOrigin={snackbarPosition}
+      >
+        <Alert onClose={handleSnackbarClose} severity={snackbarSeverity} sx={{ width: '100%' }}>
+          {snackbarMessage}
+        </Alert>
+      </Snackbar>
+    );
+  };
+
+  // Retorna ambas funcionalidades para que el usuario elija
+  return { ref: elementRef, copy: executeCopy, CopyMessage };
+}
+
+export default useClipboard;

package/src/hooks/ClipBoard/ClipboardUnifiedDemo.tsx

@@ -0,0 +1,111 @@
+// ClipboardUnifiedDemo.tsx
+import React from 'react';
+import { Button, Table, TableBody, TableCell, TableRow, Paper, Stack, Typography, Box, TableContainer, TableHead } from '@mui/material';
+import ContentCopyIcon from '@mui/icons-material/ContentCopy';
+import { useClipboard } from './ClipBoard'; 
+
+// Datos de ejemplo para la tabla (Modo Función)
+const mockData = [
+  { id: 1, content: 'dato-A-456' },
+  { id: 2, content: 'dato-B-789' },
+];
+
+/**
+ * Componente Wrapper para demostrar ambos modos de uso del hook useClipboard unificado.
+ * @param {object} args - Propiedades del Snackbar que se pasan al hook.
+ */
+interface ClipboardDemoProps {
+  message: string;
+  severity: 'success' | 'info' | 'warning' | 'error';
+  duration: number;
+  vertical: 'top' | 'bottom';
+  horizontal: 'left' | 'center' | 'right';
+}
+
+const ClipboardUnifiedDemo: React.FC<ClipboardDemoProps> = ({ message, severity, duration, vertical, horizontal }) => {
+  const options = {
+    message,
+    severity,
+    duration,
+    position: { vertical, horizontal } as const // 'as const' para tipado correcto
+  };
+  
+  // 1. Llamada al hook para el MODO FUNCIÓN (se usará 'copy' y 'CopyMessage')
+  const { copy, CopyMessage } = useClipboard(options);
+  
+  // 2. Llamada al hook para el MODO REF (se usará 'ref' y 'CopyMessageRef')
+  // Nota: Creamos una segunda instancia con opciones distintas para diferenciar el feedback
+  const { ref: refModeRef, CopyMessage: CopyMessageRef } = useClipboard({
+    ...options, 
+    message: options.message + ' (MODO REF)', 
+    severity: 'warning' // Diferenciamos el color
+  });
+  
+  return (
+    <Stack spacing={4} sx={{ width: '100%', minWidth: 500, p: 3 }}>
+        <Typography variant="h5">Hook Unificado: Ref vs. Función</Typography>
+        
+        {/* ========================================= */}
+        {/* A. MODO REF (Copia el innerText por clic) */}
+        {/* ========================================= */}
+        <Box>
+            <Typography variant="h6">1. MODO REF (Copia un solo elemento por clic)</Typography>
+            <Paper 
+                sx={{
+                    p: 2, mt: 1,
+                    border: '1px solid #ccc',
+                    borderRadius: '8px',
+                    backgroundColor: '#eef',
+                    cursor: 'pointer',
+                    '&:hover': { backgroundColor: '#dde' },
+                }}
+            >
+                {/* Adjuntamos la ref. El hook maneja el evento de clic */}
+                <Typography ref={refModeRef} variant="body1" sx={{ userSelect: 'none' }}>
+                    Texto para copiar con **REF**: Esta línea contiene el texto completo.
+                </Typography>
+                <ContentCopyIcon sx={{ fontSize: 16, ml: 1, verticalAlign: 'middle', color: 'text.secondary' }} />
+            </Paper>
+            <CopyMessageRef /> {/* Su propio Snackbar */}
+        </Box>
+        
+        {/* ========================================= */}
+        {/* B. MODO FUNCIÓN (Copia en Iteración) */}
+        {/* ========================================= */}
+        <Box>
+            <Typography variant="h6">2. MODO FUNCIÓN (Copia múltiples elementos en tabla)</Typography>
+            <TableContainer component={Paper}>
+                <Table size="small">
+                    <TableHead>
+                        <TableRow><TableCell>ID</TableCell><TableCell>Contenido</TableCell><TableCell>Acción</TableCell></TableRow>
+                    </TableHead>
+                    <TableBody>
+                        {/* Iteración: Se usa la función 'copy' */}
+                        {mockData.map((item) => (
+                            <TableRow key={item.id}>
+                                <TableCell>{item.id}</TableCell>
+                                <TableCell>{item.content}</TableCell>
+                                <TableCell>
+                                    <Button 
+                                        variant="contained" 
+                                        size="small"
+                                        // Llamada a copy() con el texto específico de la fila
+                                        onClick={() => copy(item.content)}
+                                    >
+                                        Copiar {item.id}
+                                    </Button>
+                                </TableCell>
+                            </TableRow>
+                        ))}
+                    </TableBody>
+                </Table>
+            </TableContainer>
+        </Box>
+
+        {/* El Snackbar del modo FUNCIÓN se renderiza una sola vez */}
+        <CopyMessage /> 
+    </Stack>
+  );
+};
+
+export default ClipboardUnifiedDemo;

package/src/hooks/ClipBoard/index.ts

@@ -0,0 +1 @@
+export { default as useClipboard } from './ClipBoard';

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).',
+      },
+    },
+  },
+};