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

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