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

package/src/components/Timeline/Timeline.tsx

@@ -0,0 +1,49 @@
+import * as React from "react";
+import MuiTimeline from "@mui/lab/Timeline";
+import { timelineContentClasses } from "@mui/lab/TimelineContent";
+import { timelineItemClasses, TimelineItemProps as MuiTimelineItemProps } from "@mui/lab/TimelineItem";
+import { Box } from "@mui/material";
+
+interface TimelineItemProps extends MuiTimelineItemProps {
+  connectorColor?: string;
+  sx?: object;
+}
+
+interface TimelineProps {
+  children: React.ReactElement<TimelineItemProps>[];
+  position?: "left" | "right" | 'alternate' | 'alternate-reverse' ;
+  sx?: object;
+}
+
+export const Timeline: React.FC<TimelineProps> = ({ children, position = "right", sx }) => {
+  const count = React.Children.count(children);
+
+    const customSx = (position === "left" || position === "right")
+    ? {
+        [`& .${timelineItemClasses.root}:before`]: {
+          flex: 0,
+          padding: 0,
+        },
+        ...sx,
+      }
+    : sx;
+    
+  return (
+    <MuiTimeline position={position}
+      sx={{...customSx}}
+      >
+      {React.Children.map(children, (child, idx) =>
+        React.isValidElement(child)
+          ? React.cloneElement(child, {
+            connectorColor: idx < count - 1
+              ? child.props.connectorColor ?? 'gray.main'
+              : undefined,
+          })
+          : null
+      )}
+    </MuiTimeline>
+
+  );
+};
+
+export default Timeline;

package/src/components/Timeline/TimelineItem.tsx

@@ -0,0 +1,31 @@
+
+import MuiTimelineItem from "@mui/lab/TimelineItem";
+import MuiTimelineSeparator from "@mui/lab/TimelineSeparator";
+import MuiTimelineConnector from "@mui/lab/TimelineConnector";
+import MuiTimelineContent from "@mui/lab/TimelineContent";
+import MuiTimelineDot from "@mui/lab/TimelineDot";
+
+export interface TimelineItemProps {
+  dotColor?: 'primary' | 'secondary' | 'grey' | 'inherit' | 'success' | 'error' | 'info' | 'warning';
+  connectorColor?: 'success' | 'error' | 'info' | 'warning' | 'primary' | 'secondary' | 'grey';
+  children: React.ReactNode;
+}
+
+export const TimelineItem: React.FC<TimelineItemProps> = ({
+  dotColor = 'grey',
+  connectorColor,
+  children
+}) => {
+  const color = connectorColor ? `${connectorColor}.main` : 'secondary.main';
+  return (
+    <MuiTimelineItem>
+      <MuiTimelineSeparator>
+        <MuiTimelineDot color={dotColor} />
+        {connectorColor !== undefined && <MuiTimelineConnector sx={{ bgcolor: color }} />}
+      </MuiTimelineSeparator>
+      <MuiTimelineContent>{children}</MuiTimelineContent>
+    </MuiTimelineItem>
+  );
+};
+
+export default TimelineItem

package/src/components/Timeline/index.ts

@@ -0,0 +1,2 @@
+export { default as Timeline } from './Timeline';
+export { default as TimelineItem } from './TimelineItem';

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,129 @@
+import React, { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import Tooltip from './Tooltip'; // Asegúrate que la ruta sea correcta
+import Button from '@mui/material/Button';
+import Stack from '@mui/material/Stack';
+import { Input } from '../Input/Input';
+
+// Helper controlado para envolver nuestro Input propio con estado local
+const TooltipNameInput: React.FC = () => {
+  const [value, setValue] = useState<string | number>('');
+  return (
+    <Input
+      label="Nombre"
+      value={value}
+      onChange={(next) => setValue(next)}
+    />
+  );
+};
+
+// --- Metadatos de la Historia ---
+// Define la configuración global de tu componente en Storybook
+const meta: Meta<typeof Tooltip> = {
+  // Título que aparecerá en el sidebar de Storybook
+  title: 'Components/Tooltip',
+  component: Tooltip,
+  // Parámetros para configurar el comportamiento en la documentación
+  parameters: {
+    layout: 'centered', // Centra el componente en el lienzo
+  },
+  // Documentación de los argumentos (props)
+  
+  tags: ["autodocs"]
+};
+
+export default meta;
+
+// Define el tipo de tu historia para inferir los argumentos (props)
+type Story = StoryObj<typeof Tooltip>;
+
+// --- Definición de Historias ---
+
+const textoLargo = "Este es un texto de Tooltip muy largo para demostrar cómo el 'maxWidth' limita la longitud de la línea y obliga al texto a saltar a la siguiente línea, mejorando la legibilidad en tooltips largos.";
+
+
+/**
+ * Historia 1: Tooltip Básico
+ * Muestra el Tooltip sobre un botón sin especificar un ancho máximo.
+ */
+export const TooltipBasico: Story = {
+  args: {
+    text: 'Información corta y concisa.',
+    children: <Button variant="contained">Pasa el ratón aquí</Button>,
+  },
+};
+
+/**
+ * Historia 2: Tooltip con Ancho Máximo Específico
+ * Muestra un texto largo y aplica un ancho máximo para forzar el salto de línea.
+ */
+export const TooltipConAnchoMaximo: Story = {
+  args: {
+    text: textoLargo,
+    maxWidth: 200, // Aplicamos el ancho máximo
+    children: <Button variant="outlined">Tooltip con Ancho Máximo (200px)</Button>,
+  },
+};
+
+/**
+ * Historia 3: Tooltip Aplicado a un Campo de Texto (TextField)
+ * Demuestra que el componente funciona con cualquier elemento.
+ */
+export const AplicadoAElementoDeFormulario: Story = {
+  args: {
+    text: 'Introduce tu nombre completo y validado.',
+    maxWidth: 300,
+    children: <TooltipNameInput />,
+  },
+};
+
+/**
+ * Historia 4: Ejemplo en un Contenedor con Estilos
+ * Muestra el uso de la propiedad 'sx' opcional en el contenedor.
+ */
+export const ContenedorEstilizado: Story = {
+    args: {
+        text: 'Este texto se muestra al pasar el ratón sobre el span estilizado.',
+        maxWidth: 250,
+        sx: { // Estilos aplicados al Box que envuelve el children
+            border: '2px dashed #007bff',
+            padding: '8px',
+            borderRadius: '4px',
+            backgroundColor: '#e6f7ff',
+        },
+        children: <span>Contenedor Estilizado (Hover aquí)</span>,
+    }
+}
+
+
+/**
+ * Historia 5: Variantes Múltiples
+ * Utiliza el 'render' para mostrar varios ejemplos a la vez.
+ */
+export const VariantesMultiples: Story = {
+    // Necesitamos un Stack para organizar los elementos
+    render: (args) => (
+        <Stack spacing={4} alignItems="flex-start" sx={{ padding: '20px' }}>
+            <Tooltip {...args} text="Tooltip #1: Básico" maxWidth={150}>
+                <Button variant="contained" color="primary">Botón A</Button>
+            </Tooltip>
+
+            <Tooltip {...args} text="Tooltip #2: Un poco más de info" maxWidth={180}>
+                <Button variant="contained" color="secondary">Botón B</Button>
+            </Tooltip>
+
+            <Tooltip {...args} text={textoLargo} maxWidth={280}>
+                <Button variant="text">Texto Largo</Button>
+            </Tooltip>
+        </Stack>
+    ),
+    // Eliminamos el layout centered para esta historia
+    parameters: {
+        layout: 'padded', 
+    },
+    // Dejamos el 'args' de 'text' vacío ya que se sobrescribe en el render
+    args: {
+        text: '', 
+        children: undefined, 
+    }
+};

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import MuiTooltip from '@mui/material/Tooltip'; 
+import Typography from '@mui/material/Typography';
+import Box from '@mui/material/Box';
+import { SxProps, Theme } from '@mui/material';
+
+/**
+ * Propiedades del componente Tooltip.
+ * @param {string} text - El texto a mostrar dentro del Tooltip.
+ * @param {number} [maxWidth] - El ancho máximo opcional del Tooltip en píxeles.
+ * @param {React.ReactNode} children - El elemento al que se le aplicará el Tooltip.
+ * @param {SxProps<Theme>} [sx] - Estilos opcionales para el Box contenedor.
+ */
+interface TooltipProps {
+  text: string;
+  maxWidth?: number;
+  children: React.ReactNode;
+  sx?: SxProps<Theme>;
+}
+
+/**
+ * Componente Tooltip reutilizable.
+ * Muestra un texto al pasar el ratón sobre su elemento hijo, 
+ * permitiendo un ancho máximo configurable.
+ * * @param {TooltipProps} props - Propiedades del Tooltip.
+ */
+const Tooltip: React.FC<TooltipProps> = ({ text, maxWidth, children, sx }) => {
+  
+  const tooltipContentStyle: SxProps<Theme> = {
+    
+    ...(maxWidth && { maxWidth: maxWidth }), 
+    padding: '4px 8px', 
+    textAlign: 'center',
+    
+  };
+
+  return (
+    
+    <MuiTooltip
+      title={
+        
+        <Typography variant="caption" component="span" sx={tooltipContentStyle}>
+          {text}
+        </Typography>
+      }
+      
+      placement="top" 
+      arrow 
+    >
+      
+      <Box component="span" sx={{ display: 'inline-block', ...sx }}>
+        {children}
+      </Box>
+    </MuiTooltip>
+  );
+};
+
+export default Tooltip;

package/src/components/Tooltip/index.ts

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

package/src/components/_shared/formField.sx.ts

@@ -0,0 +1,118 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+
+import {
+  LABEL_COLOR_FILLED,
+  LABEL_COLOR_FOCUSED,
+  LABEL_COLOR_REST,
+  LABEL_FONT_WEIGHT_FILLED,
+  LABEL_MARGIN_TOP,
+  LABEL_SHRINK_TRANSFORM,
+  LABEL_TRANSFORM_ORIGIN,
+  LABEL_TRANSITION,
+} from '../../theme/tokens';
+
+export type LabelPosition = 'outside' | 'floating';
+
+export interface BuildFormFieldSxOptions {
+  borderRadius: number | string;
+  labelPosition: LabelPosition;
+  /**
+   * Si es `true`, los selectores incluyen también la API nueva de MUI X
+   * Pickers (v8): `MuiPickersInputBase-root`, `MuiPickersOutlinedInput-*`.
+   */
+  includePickersApi?: boolean;
+  /**
+   * Selectores/valores extra que se mergean SOLO cuando labelPosition === 'outside'.
+   * Usar para paddings específicos del componente (p.ej. MuiAutocomplete-input).
+   */
+  extraOutsideSx?: Record<string, any>;
+  /**
+   * Selectores/valores extra que se mergean SOLO cuando labelPosition === 'floating'.
+   */
+  extraFloatingSx?: Record<string, any>;
+}
+
+const toRadius = (borderRadius: number | string) =>
+  typeof borderRadius === 'number' ? `${borderRadius}px` : borderRadius;
+
+/**
+ * Builder del sx compartido por todos los campos de formulario
+ * (Input/Select/Autocomplete/DatePicker/DateTimePicker).
+ *
+ * Produce:
+ * - en modo "floating": sólo el border-radius del outlined input;
+ * - en modo "outside": todo el pack (margen superior, label flotante afuera,
+ *   input base, notched outline oculto, helper text sin margen izquierdo).
+ *
+ * Componentes con paddings o selectores propios pueden inyectarlos vía
+ * `extraOutsideSx` / `extraFloatingSx`.
+ */
+export const buildFormFieldSx = ({
+  borderRadius,
+  labelPosition,
+  includePickersApi = false,
+  extraOutsideSx,
+  extraFloatingSx,
+}: BuildFormFieldSxOptions): SxProps<Theme> => {
+  const radius = toRadius(borderRadius);
+
+  // ── Selectores (alternan según la API de pickers) ────────────────────
+  const outlinedRootSelector = includePickersApi
+    ? '& .MuiOutlinedInput-root, & .MuiPickersOutlinedInput-root'
+    : '& .MuiOutlinedInput-root';
+
+  const inputBaseSelector = includePickersApi
+    ? '& .MuiInputBase-root, & .MuiPickersInputBase-root'
+    : '& .MuiInputBase-root';
+
+  const notchedOutlineSelector = includePickersApi
+    ? '& .MuiOutlinedInput-notchedOutline, & .MuiPickersOutlinedInput-notchedOutline'
+    : '& .MuiOutlinedInput-notchedOutline';
+
+  // ── Floating ─────────────────────────────────────────────────────────
+  if (labelPosition === 'floating') {
+    return {
+      [outlinedRootSelector]: { borderRadius: radius },
+      ...(extraFloatingSx ?? {}),
+    };
+  }
+
+  // ── Outside ──────────────────────────────────────────────────────────
+  return {
+    marginTop: LABEL_MARGIN_TOP,
+
+    '& .MuiInputLabel-root': {
+      color: LABEL_COLOR_REST,
+      transition: LABEL_TRANSITION,
+
+      // Estado shrunk (focused o con valor): flota ARRIBA del input.
+      '&.MuiInputLabel-shrink': {
+        transform: LABEL_SHRINK_TRANSFORM,
+        transformOrigin: LABEL_TRANSFORM_ORIGIN,
+        color: LABEL_COLOR_FILLED,
+        fontWeight: LABEL_FONT_WEIGHT_FILLED,
+      },
+
+      '&.Mui-focused': { color: LABEL_COLOR_FOCUSED },
+    },
+
+    // Input base — centra verticalmente (clásico y, si aplica, pickers).
+    [inputBaseSelector]: {
+      borderRadius: radius,
+      display: 'flex',
+      alignItems: 'center',
+    },
+
+    // El label flota afuera: ocultar legend del notch.
+    [notchedOutlineSelector]: {
+      top: 0,
+      '& legend': { display: 'none' },
+    },
+
+    '& .MuiFormHelperText-root': {
+      marginLeft: 0,
+    },
+
+    ...(extraOutsideSx ?? {}),
+  };
+};

package/src/components/_shared/resolvePreset.ts

@@ -0,0 +1,35 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+
+import type { LibraryComponentName, PresetStyle } from '../../theme/componentStyles';
+
+/**
+ * Nombre del preset built-in del paquete. No se registra en el theme: si un
+ * componente recibe `preset="default"` (o no recibe preset), sólo aplica el
+ * estilo base de fábrica.
+ */
+export const DEFAULT_PRESET_NAME = 'default';
+
+/**
+ * Resuelve el sx de un preset registrado en `theme.styles[componentName]`.
+ *
+ * - Si `presetName` es `"default"` o `undefined`, devuelve `undefined`
+ *   (caller sólo aplicará el estilo base del paquete).
+ * - Si la entrada en el theme es una función `(theme) => sx`, se ejecuta.
+ * - Si la entrada no existe, devuelve `undefined` silenciosamente (no se
+ *   rompe el componente — la responsabilidad de registrarlo es del consumer).
+ */
+export function resolvePreset(
+  componentName: LibraryComponentName,
+  presetName: string | undefined,
+  theme: Theme,
+): SxProps<Theme> | undefined {
+  if (!presetName || presetName === DEFAULT_PRESET_NAME) return undefined;
+
+  const componentPresets = theme.styles?.[componentName];
+  if (!componentPresets) return undefined;
+
+  const entry: PresetStyle | undefined = componentPresets[presetName];
+  if (!entry) return undefined;
+
+  return typeof entry === 'function' ? entry(theme) : entry;
+}

package/src/hooks/ClipBoard/ClipBoard.stories.tsx

@@ -0,0 +1,168 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+import { Box, Button, Typography } from '@mui/material';
+
+// Importa el componente de demostración unificado
+import ClipboardUnifiedDemo from './ClipboardUnifiedDemo'; 
+
+// Importa las definiciones de las historias
+
+import useClipboard from './ClipBoard';
+
+// Componente Wrapper (Mantenido para la tipificación)
+const ClipboardDemoWrapper: React.FC = () => <ClipboardUnifiedDemo {...(meta.args as any)} />; 
+
+// =============================================================================
+// Definición de las meta-propiedades para Storybook
+// =============================================================================
+const meta: Meta<typeof ClipboardUnifiedDemo> = {
+  title: 'Hooks/useClipboard (Unificado Ref & Función)',
+  component: ClipboardUnifiedDemo,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: 'Hook unificado que soporta la **copia por Referencia (`ref`)** para un solo elemento y la **copia por Función (`copy(text)`)** para iteraciones (tablas, listas), proporcionando feedback visual con un Snackbar de Material UI.',
+      },
+    },
+  },
+  // Argumentos de control para el MODO FUNCIÓN
+  argTypes: {
+    message: { control: 'text', description: 'Mensaje de éxito para el MODO FUNCIÓN.' },
+    severity: { control: 'select', options: ['success', 'info', 'warning', 'error'], description: 'Gravedad del Alert para el MODO FUNCIÓN.' },
+    duration: { control: { type: 'number', min: 0, max: 5000, step: 500 }, description: 'Duración del Snackbar.' },
+    vertical: { control: 'select', options: ['top', 'bottom'], description: 'Posición vertical.' },
+    horizontal: { control: 'select', options: ['left', 'center', 'right'], description: 'Posición horizontal.' },
+  },
+  args: {
+    message: '¡Dato copiado con la función!',
+    severity: 'success',
+    duration: 2000,
+    vertical: 'bottom',
+    horizontal: 'center',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ClipboardUnifiedDemo>;
+
+// =============================================================================
+// Historias
+// =============================================================================
+
+export const DemoUnificada: Story = {
+  name: 'A. Demostración Completa',
+  args: {
+    message: 'Dato copiado con éxito (Función)',
+    severity: 'success',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Muestra ambos modos de uso (`ref` y `copy`) simultáneamente. El feedback del modo `ref` tiene color amarillo (warning) por defecto para diferenciarlo del modo `copy`."
+      },
+      // source: { code: MultipleFunctionElementsDefinition.trim() }
+    }
+  }
+};
+
+// --------------------------------------------------
+
+export const UsoBasicoPorRef: Story = {
+    name: 'B. Modo Ref: Uso Básico',
+    render: () => {
+        const { ref, CopyMessage } = useClipboard(); // Sin opciones, usa valores por defecto
+        return (
+            <Box>
+                <Typography ref={ref} sx={{ p: 2, border: '1px solid #ccc', cursor: 'pointer' }}>
+                    Texto para copiar por ref (click aquí).
+                </Typography>
+                <CopyMessage />
+            </Box>
+        );
+    },
+    parameters: {
+        docs: {
+            description: {
+                story: "Demuestra el modo **Referencia**, donde el hook adjunta un listener de clic al elemento y copia su `innerText`."
+            },
+            // source: { code: BasicRefUsageDefinition.trim() }
+        }
+    }
+};
+
+// --------------------------------------------------
+
+// Datos simulados para la demostración del modo función
+const mockData = [
+    { id: 1, content: 'Dato 1' },
+    { id: 2, content: 'Dato 2' },
+    { id: 3, content: 'Dato 3' },
+];
+
+export const UsoPorFuncionEnIteracion: Story = {
+    name: 'C. Modo Función: Uso en Iteración',
+    render: () => {
+        const { copy, CopyMessage } = useClipboard({
+            message: 'Contenido de la fila copiado.',
+            severity: 'info',
+            position: { vertical: 'top', horizontal: 'right' }
+        });
+        
+        return (
+            <Box>
+                <Typography variant="h6">Copiar datos individuales:</Typography>
+                {mockData.map(item => (
+                    <Button 
+                        key={item.id}
+                        variant="outlined" 
+                        onClick={() => copy(item.content)} 
+                        sx={{ mr: 2 }}
+                    >
+                        Copiar: {item.content}
+                    </Button>
+                ))}
+                <CopyMessage />
+            </Box>
+        );
+    },
+    parameters: {
+        docs: {
+            description: {
+                story: "Demuestra el modo **Función**, donde se llama a `copy(text)` dentro de un bucle, permitiendo controlar exactamente qué texto se copia."
+            },
+            // source: { code: FunctionModeUsageDefinition.trim() }
+        }
+    }
+};
+
+// --------------------------------------------------
+
+export const CustomConfiguracionRef: Story = {
+    name: 'D. Modo Ref: Con Configuración Custom',
+    render: () => {
+        const { ref, CopyMessage } = useClipboard({
+            message: 'Copia OK en la parte superior.',
+            severity: 'success',
+            duration: 1800,
+            position: { vertical: 'top', horizontal: 'left' }
+        });
+        return (
+            <Box>
+                <Typography ref={ref} sx={{ p: 2, border: '1px solid #0a0', backgroundColor: '#eef', cursor: 'pointer' }}>
+                    Clic. Snackbar aparecerá arriba a la izquierda.
+                </Typography>
+                <CopyMessage />
+            </Box>
+        );
+    },
+    parameters: {
+        docs: {
+            description: {
+                story: "Muestra cómo aplicar opciones personalizadas de Snackbar al modo **Referencia**."
+            },
+            // source: { code: CustomRefUsageDefinition.trim() }
+        }
+    }
+};