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

package/src/components/PageLoader/PageLoader.stories.tsx

@@ -0,0 +1,217 @@
+import React, { useState, useEffect } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box, Button, Paper, Typography } from '@mui/material';
+
+import { PageLoader } from './PageLoader';
+
+const meta: Meta<typeof PageLoader> = {
+  title: 'Components/PageLoader',
+  component: PageLoader,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Loader visual para estados de carga, tanto a nivel de página completa (splash screen) como inline dentro de un contenedor. Reemplaza el `LayoutSplashScreen` de Metronic.',
+      },
+    },
+  },
+  argTypes: {
+    fullscreen: {
+      control: 'boolean',
+      description: 'Ocupa toda la ventana con backdrop. Default: true.',
+    },
+    size: {
+      control: { type: 'number', min: 16, max: 120, step: 4 },
+      description: 'Tamaño del spinner en px.',
+    },
+    open: {
+      control: 'boolean',
+      description: 'Si es false, el loader se desmonta (con fade en fullscreen).',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof PageLoader>;
+
+// ── Stories ──────────────────────────────────────────────────────────────
+
+export const FullscreenDefault: Story = {
+  args: {
+    fullscreen: true,
+    open: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Loader full-page sin texto ni logo. Caso más minimal.',
+      },
+    },
+  },
+};
+
+export const FullscreenWithMessage: Story = {
+  args: {
+    fullscreen: true,
+    open: true,
+    message: 'Cargando aplicación...',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Splash screen típico con mensaje bajo el spinner.',
+      },
+    },
+  },
+};
+
+export const FullscreenWithLogo: Story = {
+  args: {
+    fullscreen: true,
+    open: true,
+    message: 'Inicializando...',
+    logo: (
+      <Box
+        sx={{
+          width: 120,
+          height: 120,
+          borderRadius: '50%',
+          bgcolor: 'primary.main',
+          color: '#fff',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          fontSize: 36,
+          fontWeight: 700,
+        }}
+      >
+        fri
+      </Box>
+    ),
+    size: 40,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Splash de arranque de app con logo/branding arriba del spinner. Equivalente visual al `LayoutSplashScreen` de Metronic.',
+      },
+    },
+  },
+};
+
+export const Inline: Story = {
+  args: {
+    fullscreen: false,
+    open: true,
+    message: 'Cargando datos',
+    size: 32,
+  },
+  render: (args) => (
+    <Paper sx={{ maxWidth: 480, mx: 'auto', mt: 4 }}>
+      <Box sx={{ p: 2, borderBottom: 1, borderColor: 'divider' }}>
+        <Typography variant="subtitle1" sx={{ fontWeight: 600 }}>
+          Panel de resumen
+        </Typography>
+      </Box>
+      <PageLoader {...args} />
+    </Paper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Loader inline (no fullscreen). Ocupa el ancho del contenedor padre y tiene una altura mínima. Útil dentro de cards mientras se cargan datos.',
+      },
+    },
+  },
+};
+
+export const ToggledFullscreen: Story = {
+  render: () => {
+    const [loading, setLoading] = useState(false);
+
+    const simulate = () => {
+      setLoading(true);
+      setTimeout(() => setLoading(false), 1800);
+    };
+
+    return (
+      <Box sx={{ p: 4, height: '100vh' }}>
+        <Typography variant="h5" gutterBottom>
+          Simulación de carga
+        </Typography>
+        <Typography color="text.secondary" sx={{ mb: 2 }}>
+          Al hacer click, el loader aparece por 1.8s y luego desaparece con fade.
+        </Typography>
+        <Button variant="contained" onClick={simulate}>
+          Simular carga
+        </Button>
+
+        <PageLoader
+          fullscreen
+          open={loading}
+          message="Procesando..."
+          logo={
+            <Box
+              sx={{
+                width: 72,
+                height: 72,
+                borderRadius: 2,
+                bgcolor: 'primary.main',
+                color: '#fff',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                fontSize: 24,
+                fontWeight: 700,
+              }}
+            >
+              fri
+            </Box>
+          }
+        />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Ejemplo controlado: el loader se monta/desmonta según un estado externo, con fade de salida. Patrón típico para bloquear la app durante una operación crítica (auth, inicialización, navegación global).',
+      },
+    },
+  },
+};
+
+export const AutoDismiss: Story = {
+  render: () => {
+    const [open, setOpen] = useState(true);
+
+    useEffect(() => {
+      const t = setTimeout(() => setOpen(false), 2000);
+      return () => clearTimeout(t);
+    }, []);
+
+    return (
+      <Box sx={{ p: 4, height: '100vh' }}>
+        {!open && (
+          <Typography variant="h5">
+            App lista. (El loader se cerró tras 2s.)
+          </Typography>
+        )}
+        <PageLoader open={open} message="Cargando..." />
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Arranque típico: el loader aparece al montar, y el consumer lo cierra cuando termina la inicialización. Aquí simulamos 2 segundos fijos.',
+      },
+    },
+  },
+};

package/src/components/PageLoader/PageLoader.tsx

@@ -0,0 +1,96 @@
+import React, { type ReactNode } from 'react';
+import { Box, CircularProgress, Typography, Fade } from '@mui/material';
+import type { SxProps, Theme } from '@mui/material/styles';
+
+export interface PageLoaderProps {
+  /**
+   * Si es true, muestra el loader ocupando toda la ventana (fixed, 100vh/vw)
+   * con backdrop. Default: true.
+   */
+  fullscreen?: boolean;
+  /** Texto bajo el spinner. */
+  message?: ReactNode;
+  /** Logo/imagen opcional arriba del spinner. */
+  logo?: ReactNode;
+  /** Tamaño del spinner en px. Default: 48. */
+  size?: number;
+  /**
+   * Control explícito. Si es undefined, el loader se muestra apenas se monta.
+   * Útil para fades.
+   */
+  open?: boolean;
+  /** Color del backdrop (solo fullscreen). Default: usa theme.palette.background.default. */
+  backdropColor?: string;
+  /** sx del root. */
+  sx?: SxProps<Theme>;
+  className?: string;
+}
+
+/**
+ * Loader full-page o inline. Reemplaza el `LayoutSplashScreen` de Metronic.
+ *
+ * ```tsx
+ * // Splash de arranque
+ * <PageLoader logo={<img src={logo} />} message="Cargando..." />
+ *
+ * // Loader local dentro de una card
+ * <PageLoader fullscreen={false} size={32} />
+ * ```
+ */
+export function PageLoader({
+  fullscreen = true,
+  message,
+  logo,
+  size = 48,
+  open = true,
+  backdropColor,
+  sx,
+  className,
+}: PageLoaderProps) {
+  const rootSx: SxProps<Theme> = [
+    (theme) => ({
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+      justifyContent: 'center',
+      gap: 2,
+      ...(fullscreen
+        ? {
+            position: 'fixed',
+            inset: 0,
+            zIndex: theme.zIndex.modal + 10,
+            backgroundColor:
+              backdropColor ?? theme.palette.background.default,
+          }
+        : {
+            width: '100%',
+            minHeight: 160,
+          }),
+    }),
+    ...(Array.isArray(sx) ? sx : sx ? [sx] : []),
+  ];
+
+  const content = (
+    <Box className={className} sx={rootSx} role="status" aria-live="polite">
+      {logo && <Box sx={{ mb: 1 }}>{logo}</Box>}
+      <CircularProgress size={size} thickness={4} />
+      {message && (
+        <Typography variant="body2" color="text.secondary">
+          {message}
+        </Typography>
+      )}
+    </Box>
+  );
+
+  if (!fullscreen) {
+    return open ? content : null;
+  }
+
+  return (
+    <Fade in={open} timeout={{ enter: 0, exit: 200 }} unmountOnExit>
+      {content}
+    </Fade>
+  );
+}
+
+export default PageLoader;

package/src/components/PageLoader/index.ts

@@ -0,0 +1,2 @@
+export { PageLoader, default } from './PageLoader';
+export type { PageLoaderProps } from './PageLoader';

package/src/components/ScrollTopButton/ScrollTopButton.stories.tsx

@@ -0,0 +1,158 @@
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box, Button, Stack, Typography } from '@mui/material';
+import ArrowUpwardIcon from '@mui/icons-material/ArrowUpward';
+
+import { ScrollTopButton } from './ScrollTopButton';
+import { scrollToTop } from './scrollToTop';
+
+const meta: Meta<typeof ScrollTopButton> = {
+  title: 'Components/ScrollTopButton',
+  component: ScrollTopButton,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Botón flotante que aparece tras scrollear más de `threshold` px y lleva al tope al click. Reemplaza al `ScrollTopComponent` visible de Metronic. Para el caso imperativo (p.ej. tras una mutación) usa el helper `scrollToTop()`.',
+      },
+    },
+  },
+  argTypes: {
+    threshold: { control: { type: 'number', min: 0, max: 1000, step: 50 } },
+    position: {
+      control: 'select',
+      options: ['bottom-right', 'bottom-left', 'bottom-center'],
+    },
+    size: { control: 'select', options: ['small', 'medium', 'large'] },
+    color: {
+      control: 'select',
+      options: ['default', 'primary', 'secondary', 'success', 'warning', 'error'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ScrollTopButton>;
+
+const TallContent = () => (
+  <Box sx={{ p: 3 }}>
+    <Typography variant="h5" gutterBottom>
+      Scrollea hacia abajo para que aparezca el botón
+    </Typography>
+    <Typography variant="body2" color="text.secondary" sx={{ mb: 2 }}>
+      El botón aparece cuando `window.scrollY` supera el `threshold`.
+    </Typography>
+    {Array.from({ length: 60 }).map((_, idx) => (
+      <Typography key={idx} variant="body2" sx={{ mb: 1 }}>
+        Línea {idx + 1} — contenido de relleno para simular una página larga.
+      </Typography>
+    ))}
+  </Box>
+);
+
+export const Default: Story = {
+  args: {
+    threshold: 300,
+    position: 'bottom-right',
+  },
+  render: (args) => (
+    <>
+      <TallContent />
+      <ScrollTopButton {...args} />
+    </>
+  ),
+};
+
+export const BottomLeft: Story = {
+  args: {
+    threshold: 200,
+    position: 'bottom-left',
+  },
+  render: (args) => (
+    <>
+      <TallContent />
+      <ScrollTopButton {...args} />
+    </>
+  ),
+};
+
+export const BottomCenter: Story = {
+  args: {
+    threshold: 200,
+    position: 'bottom-center',
+    color: 'primary',
+  },
+  render: (args) => (
+    <>
+      <TallContent />
+      <ScrollTopButton {...args} />
+    </>
+  ),
+};
+
+export const CustomIcon: Story = {
+  args: {
+    threshold: 200,
+    color: 'primary',
+    icon: <ArrowUpwardIcon />,
+  },
+  render: (args) => (
+    <>
+      <TallContent />
+      <ScrollTopButton {...args} />
+    </>
+  ),
+};
+
+export const SmallSize: Story = {
+  args: {
+    size: 'small',
+    threshold: 150,
+  },
+  render: (args) => (
+    <>
+      <TallContent />
+      <ScrollTopButton {...args} />
+    </>
+  ),
+};
+
+export const ImperativeHelper: Story = {
+  render: () => (
+    <Box sx={{ p: 3 }}>
+      <Typography variant="h5" gutterBottom>
+        Uso imperativo: <code>scrollToTop()</code>
+      </Typography>
+      <Typography variant="body2" color="text.secondary" sx={{ mb: 2 }}>
+        Reemplazo directo de <code>ScrollTopComponent.goTop()</code> de Metronic.
+        Llamar tras mutaciones / aperturas de modales.
+      </Typography>
+      <Stack direction="row" spacing={1} sx={{ mb: 3 }}>
+        <Button variant="contained" onClick={() => scrollToTop()}>
+          scrollToTop() (smooth)
+        </Button>
+        <Button
+          variant="outlined"
+          onClick={() => scrollToTop({ behavior: 'auto' })}
+        >
+          scrollToTop &#123; behavior:'auto' &#125;
+        </Button>
+      </Stack>
+      {Array.from({ length: 50 }).map((_, idx) => (
+        <Typography key={idx} variant="body2" sx={{ mb: 1 }}>
+          Línea {idx + 1}
+        </Typography>
+      ))}
+    </Box>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Demuestra el helper imperativo. Cubre el patrón del legacy: llamar `scrollToTop()` tras una mutación para llevar al usuario a ver el mensaje de confirmación del tope.',
+      },
+    },
+  },
+};

package/src/components/ScrollTopButton/ScrollTopButton.tsx

@@ -0,0 +1,135 @@
+import React, { useEffect, useState, type ReactNode } from 'react';
+import { Fab, Zoom, useTheme } from '@mui/material';
+import KeyboardArrowUpIcon from '@mui/icons-material/KeyboardArrowUp';
+import type { SxProps, Theme } from '@mui/material/styles';
+
+import { resolvePreset } from '../_shared/resolvePreset';
+import { scrollToTop } from './scrollToTop';
+
+export type ScrollTopButtonPosition =
+  | 'bottom-right'
+  | 'bottom-left'
+  | 'bottom-center';
+
+export interface ScrollTopButtonProps {
+  /**
+   * Distancia en px que hay que scrollear antes de mostrar el botón.
+   * Default: `300`.
+   */
+  threshold?: number;
+  /**
+   * Posición del botón en la pantalla. Default: `'bottom-right'`.
+   */
+  position?: ScrollTopButtonPosition;
+  /**
+   * Elemento scrolleable a observar y al que se hace scrollTop. Si se omite,
+   * se usa `window` (caso más común).
+   */
+  scrollTarget?: Window | HTMLElement | null;
+  /** Tamaño del FAB. Default: `'medium'`. */
+  size?: 'small' | 'medium' | 'large';
+  /**
+   * Color del FAB. Default: `'default'`.
+   */
+  color?: 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error';
+  /** Icono custom. Default: `<KeyboardArrowUpIcon />`. */
+  icon?: ReactNode;
+  /** Texto accesible (aria-label). Default: `"Subir al inicio"`. */
+  ariaLabel?: string;
+  /** Preset registrado en `theme.styles.ScrollTopButton`. */
+  preset?: string;
+  /** sx del Fab. Se compone sobre la posición + preset. */
+  sx?: SxProps<Theme>;
+  className?: string;
+}
+
+const positionSx: Record<ScrollTopButtonPosition, SxProps<Theme>> = {
+  'bottom-right': { position: 'fixed', bottom: 24, right: 24 },
+  'bottom-left': { position: 'fixed', bottom: 24, left: 24 },
+  'bottom-center': {
+    position: 'fixed',
+    bottom: 24,
+    left: '50%',
+    transform: 'translateX(-50%)',
+  },
+};
+
+/**
+ * Botón flotante que aparece tras scrollear más de `threshold` px y, al
+ * clickearse, hace scroll suave hasta el tope. Reemplaza al componente
+ * visible de `ScrollTopComponent` de Metronic.
+ *
+ * Para el caso imperativo (llamar `goTop()` tras una mutación), usar el
+ * helper `scrollToTop()` directamente.
+ *
+ * ```tsx
+ * <ScrollTopButton threshold={400} position="bottom-right" />
+ * ```
+ */
+export function ScrollTopButton({
+  threshold = 300,
+  position = 'bottom-right',
+  scrollTarget,
+  size = 'medium',
+  color = 'default',
+  icon,
+  ariaLabel = 'Subir al inicio',
+  preset,
+  sx,
+  className,
+}: ScrollTopButtonProps) {
+  const theme = useTheme();
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    // Si viene scrollTarget explícito, usarlo; si no, window.
+    const target: Window | HTMLElement | null =
+      scrollTarget ?? (typeof window !== 'undefined' ? window : null);
+    if (!target) return;
+
+    const readScrollTop = () =>
+      target === window
+        ? window.scrollY || document.documentElement.scrollTop
+        : (target as HTMLElement).scrollTop;
+
+    const handleScroll = () => {
+      setVisible(readScrollTop() > threshold);
+    };
+
+    handleScroll(); // check inicial por si ya estamos scrolleados
+    target.addEventListener('scroll', handleScroll, { passive: true });
+    return () => target.removeEventListener('scroll', handleScroll);
+  }, [threshold, scrollTarget]);
+
+  const handleClick = () => {
+    scrollToTop({
+      target: scrollTarget ?? (typeof window !== 'undefined' ? window : undefined),
+    });
+  };
+
+  const presetSx = resolvePreset('ScrollTopButton', preset, theme);
+
+  const mergedSx: SxProps<Theme> = [
+    positionSx[position],
+    { zIndex: theme.zIndex.speedDial },
+    ...(presetSx ? [presetSx] : []),
+    ...(Array.isArray(sx) ? sx : sx ? [sx] : []),
+  ];
+
+  return (
+    <Zoom in={visible} unmountOnExit>
+      <Fab
+        size={size}
+        color={color}
+        aria-label={ariaLabel}
+        onClick={handleClick}
+        className={className}
+        sx={mergedSx}
+      >
+        {icon ?? <KeyboardArrowUpIcon />}
+      </Fab>
+    </Zoom>
+  );
+}
+
+export default ScrollTopButton;

package/src/components/ScrollTopButton/index.ts

@@ -0,0 +1,8 @@
+export { ScrollTopButton, default } from './ScrollTopButton';
+export type {
+  ScrollTopButtonProps,
+  ScrollTopButtonPosition,
+} from './ScrollTopButton';
+
+export { scrollToTop } from './scrollToTop';
+export type { ScrollToTopOptions } from './scrollToTop';

package/src/components/ScrollTopButton/scrollToTop.ts

@@ -0,0 +1,37 @@
+export interface ScrollToTopOptions {
+  /** Comportamiento del scroll. Default: `'smooth'`. */
+  behavior?: ScrollBehavior;
+  /**
+   * Elemento target del scroll. Default: `window`. Útil cuando el contenedor
+   * scrolleable NO es `window` (p.ej. un `<Box>` con `overflow: auto`).
+   */
+  target?: Window | HTMLElement;
+  /** Offset desde el top. Default: `0`. */
+  top?: number;
+}
+
+/**
+ * Reemplaza imperativamente a `ScrollTopComponent.goTop()` de Metronic.
+ *
+ * Llamar tras mutaciones / cambios de filtros / apertura de modales para
+ * asegurar que el usuario vea el mensaje de confirmación en la parte
+ * superior de la página.
+ *
+ * ```ts
+ * // Reemplazo directo del legacy:
+ * // Antes: ScrollTopComponent.goTop()
+ * scrollToTop();
+ *
+ * // Con opciones:
+ * scrollToTop({ behavior: 'auto' });
+ * scrollToTop({ target: myScrollableRef.current });
+ * ```
+ */
+export function scrollToTop({
+  behavior = 'smooth',
+  target = typeof window !== 'undefined' ? window : undefined,
+  top = 0,
+}: ScrollToTopOptions = {}): void {
+  if (!target) return;
+  target.scrollTo({ top, left: 0, behavior });
+}