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

package/src/components/Drawer/Drawer.stories.tsx

@@ -0,0 +1,270 @@
+import React, { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Box, Typography, Avatar } from '@mui/material';
+import HomeIcon from '@mui/icons-material/Home';
+import PersonIcon from '@mui/icons-material/Person';
+import SettingsIcon from '@mui/icons-material/Settings';
+import ReceiptIcon from '@mui/icons-material/Receipt';
+import LogoutIcon from '@mui/icons-material/Logout';
+import NotificationsIcon from '@mui/icons-material/Notifications';
+
+import { Drawer } from './Drawer';
+import { DrawerItem } from './DrawerItem';
+
+const meta: Meta<typeof Drawer> = {
+  title: 'Components/Drawer',
+  component: Drawer,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Drawer lateral para navegación. Soporta modo `collapsed` (mini-variant con solo iconos) y reemplaza el `DrawerComponent` de Metronic. Los sub-componentes `DrawerItem` reaccionan al estado `collapsed` vía context y muestran tooltip automático al hover cuando el drawer está mini.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['permanent', 'persistent', 'temporary'],
+      description:
+        '`permanent` (default) = siempre visible en desktop. `persistent` = oculta/muestra empujando contenido. `temporary` = flotante con backdrop (típico móvil).',
+    },
+    anchor: {
+      control: 'select',
+      options: ['left', 'right', 'top', 'bottom'],
+    },
+    collapsed: {
+      control: 'boolean',
+      description: 'Estado mini (solo iconos). Solo aplica en `permanent`/`persistent`.',
+    },
+    expandedWidth: { control: { type: 'number', min: 180, max: 400, step: 10 } },
+    collapsedWidth: { control: { type: 'number', min: 48, max: 120, step: 4 } },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Drawer>;
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+const SampleLogo = () => (
+  <Typography variant="h6" sx={{ fontWeight: 700, color: 'primary.main' }}>
+    soyfri
+  </Typography>
+);
+
+const SampleFooter = ({ collapsed }: { collapsed: boolean }) => (
+  <Box sx={{ display: 'flex', alignItems: 'center', gap: 1.5 }}>
+    <Avatar sx={{ width: 36, height: 36 }}>AP</Avatar>
+    {!collapsed && (
+      <Box sx={{ minWidth: 0 }}>
+        <Typography variant="body2" noWrap sx={{ fontWeight: 600 }}>
+          Andrea Pérez
+        </Typography>
+        <Typography variant="caption" color="text.secondary" noWrap>
+          admin@soyfri.com
+        </Typography>
+      </Box>
+    )}
+  </Box>
+);
+
+// ── Stories ──────────────────────────────────────────────────────────────
+
+export const ExpandedPermanent: Story = {
+  args: {
+    variant: 'permanent',
+    anchor: 'left',
+    collapsed: false,
+    expandedWidth: 260,
+    collapsedWidth: 72,
+    header: <SampleLogo />,
+  },
+  render: (args) => (
+    <Box sx={{ display: 'flex', height: '100vh' }}>
+      <Drawer {...args}>
+        <DrawerItem icon={<HomeIcon />} label="Inicio" active />
+        <DrawerItem icon={<PersonIcon />} label="Perfil" />
+        <DrawerItem
+          icon={<NotificationsIcon />}
+          label="Notificaciones"
+          endAdornment={
+            <Typography
+              variant="caption"
+              sx={{
+                bgcolor: 'primary.main',
+                color: '#fff',
+                borderRadius: 10,
+                px: 1,
+                py: 0.25,
+                fontWeight: 600,
+              }}
+            >
+              3
+            </Typography>
+          }
+        />
+        <DrawerItem icon={<ReceiptIcon />} label="Facturación" />
+        <DrawerItem icon={<SettingsIcon />} label="Configuración" />
+      </Drawer>
+      <Box sx={{ flex: 1, p: 3 }}>
+        <Typography variant="h5">Contenido principal</Typography>
+        <Typography color="text.secondary">
+          El drawer permanente convive con el contenido y no lo tapa.
+        </Typography>
+      </Box>
+    </Box>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Drawer permanente expandido con logo en header y lista de items. Uno de los items tiene un badge como `endAdornment`.',
+      },
+    },
+  },
+};
+
+export const CollapsedPermanent: Story = {
+  ...ExpandedPermanent,
+  args: {
+    ...ExpandedPermanent.args,
+    collapsed: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'El mismo drawer en modo mini. Los labels se ocultan y al hacer hover sobre cada item aparece un tooltip con su texto. Notar que el badge `endAdornment` se oculta también en modo collapsed.',
+      },
+    },
+  },
+};
+
+export const ToggleableDrawer: Story = {
+  render: () => {
+    const [collapsed, setCollapsed] = useState(false);
+
+    return (
+      <Box sx={{ display: 'flex', height: '100vh' }}>
+        <Drawer
+          variant="permanent"
+          collapsed={collapsed}
+          onToggleCollapse={() => setCollapsed((v) => !v)}
+          header={<SampleLogo />}
+          footer={<SampleFooter collapsed={collapsed} />}
+        >
+          <DrawerItem icon={<HomeIcon />} label="Inicio" active />
+          <DrawerItem icon={<PersonIcon />} label="Perfil" />
+          <DrawerItem icon={<ReceiptIcon />} label="Facturación" />
+          <DrawerItem icon={<SettingsIcon />} label="Configuración" />
+          <DrawerItem icon={<LogoutIcon />} label="Cerrar sesión" danger />
+        </Drawer>
+        <Box sx={{ flex: 1, p: 3 }}>
+          <Typography variant="h5">
+            Drawer: {collapsed ? 'colapsado' : 'expandido'}
+          </Typography>
+          <Typography color="text.secondary">
+            Usá el chevron del header para alternar. El footer se adapta
+            (avatar solo cuando está mini, avatar + texto cuando está
+            expandido).
+          </Typography>
+        </Box>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Drawer con botón chevron funcional (el que provee el paquete) y footer que reacciona al estado. Incluye un item `danger` (cerrar sesión) que se pinta en color error.',
+      },
+    },
+  },
+};
+
+export const TemporaryDrawer: Story = {
+  render: () => {
+    const [open, setOpen] = useState(false);
+
+    return (
+      <Box sx={{ height: '100vh', p: 3 }}>
+        <Typography variant="h5" gutterBottom>
+          Drawer temporal (para móvil)
+        </Typography>
+        <Typography
+          sx={{ cursor: 'pointer', color: 'primary.main' }}
+          onClick={() => setOpen(true)}
+        >
+          → Abrir drawer
+        </Typography>
+
+        <Drawer
+          variant="temporary"
+          open={open}
+          onClose={() => setOpen(false)}
+          header={<SampleLogo />}
+        >
+          <DrawerItem
+            icon={<HomeIcon />}
+            label="Inicio"
+            onClick={() => setOpen(false)}
+          />
+          <DrawerItem
+            icon={<PersonIcon />}
+            label="Perfil"
+            onClick={() => setOpen(false)}
+          />
+          <DrawerItem
+            icon={<SettingsIcon />}
+            label="Configuración"
+            onClick={() => setOpen(false)}
+          />
+        </Drawer>
+      </Box>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Drawer `temporary`: flota por encima del contenido con backdrop. Cierra con ESC, click en backdrop, o handler explícito en cada item. El modo `collapsed` no aplica acá.',
+      },
+    },
+  },
+};
+
+export const RightAnchored: Story = {
+  args: {
+    variant: 'permanent',
+    anchor: 'right',
+    expandedWidth: 320,
+    header: (
+      <Typography variant="subtitle1" sx={{ fontWeight: 600 }}>
+        Panel lateral
+      </Typography>
+    ),
+  },
+  render: (args) => (
+    <Box sx={{ display: 'flex', height: '100vh' }}>
+      <Box sx={{ flex: 1, p: 3 }}>
+        <Typography variant="h5">Contenido principal</Typography>
+      </Box>
+      <Drawer {...args}>
+        <DrawerItem icon={<NotificationsIcon />} label="Notificaciones" />
+        <DrawerItem icon={<PersonIcon />} label="Contactos" />
+        <DrawerItem icon={<SettingsIcon />} label="Ajustes" />
+      </Drawer>
+    </Box>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Drawer anclado a la derecha. Útil para paneles secundarios (inbox, notificaciones, detalles) en lugar de navegación principal.',
+      },
+    },
+  },
+};

package/src/components/Drawer/Drawer.sx.ts

@@ -0,0 +1,106 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+
+export interface BuildDrawerSxArgs {
+  /** Ancho actual del drawer (expanded o collapsed). */
+  width: number;
+  /** Duración de la transición de ancho en ms. */
+  transitionDuration?: number;
+}
+
+/**
+ * sx aplicado al root del MuiDrawer. Controla el ancho animado y el paper
+ * interno. Los estilos visuales del paper (background, border) se dejan en
+ * manos del theme / preset.
+ */
+export function buildDrawerSx({
+  width,
+  transitionDuration = 200,
+}: BuildDrawerSxArgs): SxProps<Theme> {
+  return {
+    width,
+    flexShrink: 0,
+    whiteSpace: 'nowrap',
+    boxSizing: 'border-box',
+    transition: (theme) =>
+      theme.transitions.create('width', {
+        easing: theme.transitions.easing.sharp,
+        duration: transitionDuration,
+      }),
+    '& .MuiDrawer-paper': {
+      width,
+      boxSizing: 'border-box',
+      overflowX: 'hidden',
+      transition: (theme) =>
+        theme.transitions.create('width', {
+          easing: theme.transitions.easing.sharp,
+          duration: transitionDuration,
+        }),
+    },
+  };
+}
+
+export interface BuildDrawerItemSxArgs {
+  collapsed: boolean;
+  active?: boolean;
+  danger?: boolean;
+}
+
+/**
+ * sx para un item del drawer. Centra el icono cuando está colapsado y
+ * tiñe el fondo cuando el item está activo.
+ */
+export function buildDrawerItemSx({
+  collapsed,
+  active,
+  danger,
+}: BuildDrawerItemSxArgs): SxProps<Theme> {
+  return (theme) => ({
+    minHeight: 44,
+    px: collapsed ? 1 : 2,
+    py: 1,
+    mx: 1,
+    my: 0.25,
+    borderRadius: 1,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: collapsed ? 'center' : 'flex-start',
+    gap: collapsed ? 0 : 1.5,
+    cursor: 'pointer',
+    color: danger
+      ? theme.palette.error.main
+      : active
+        ? theme.palette.primary.main
+        : theme.palette.text.primary,
+    backgroundColor: active
+      ? theme.palette.action.selected
+      : 'transparent',
+    transition: theme.transitions.create(
+      ['background-color', 'color', 'padding'],
+      { duration: 150 },
+    ),
+    '&:hover': {
+      backgroundColor: danger
+        ? theme.palette.error.light + '22'
+        : theme.palette.action.hover,
+    },
+    '& .drawer-item__icon': {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      flexShrink: 0,
+      minWidth: 24,
+    },
+    '& .drawer-item__label': {
+      flex: 1,
+      minWidth: 0,
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+      whiteSpace: 'nowrap',
+      opacity: collapsed ? 0 : 1,
+      width: collapsed ? 0 : 'auto',
+      transition: theme.transitions.create(['opacity', 'width'], {
+        duration: collapsed ? 100 : 200,
+      }),
+    },
+  });
+}

package/src/components/Drawer/Drawer.tsx

@@ -0,0 +1,214 @@
+import React, { useMemo, type ReactNode } from 'react';
+import {
+  Drawer as MuiDrawer,
+  IconButton,
+  Box,
+  type DrawerProps as MuiDrawerProps,
+} from '@mui/material';
+import {
+  useTheme,
+  type SxProps,
+  type Theme,
+} from '@mui/material/styles';
+import ChevronLeftIcon from '@mui/icons-material/ChevronLeft';
+import ChevronRightIcon from '@mui/icons-material/ChevronRight';
+
+import { DrawerContext } from './DrawerContext';
+import { buildDrawerSx } from './Drawer.sx';
+import { resolvePreset } from '../_shared/resolvePreset';
+
+// ── Tipos públicos ──────────────────────────────────────────────────────
+export type DrawerVariant = 'permanent' | 'persistent' | 'temporary';
+export type DrawerAnchor = 'left' | 'right' | 'top' | 'bottom';
+
+export interface DrawerProps {
+  /** Contenido del drawer (típicamente `<DrawerItem>`s). */
+  children?: ReactNode;
+  /**
+   * Variante del drawer:
+   * - `permanent` (default): siempre visible en desktop, soporta collapsed (mini).
+   * - `persistent`: se oculta/muestra, empuja el contenido principal.
+   * - `temporary`: flotante con backdrop (típico móvil).
+   */
+  variant?: DrawerVariant;
+  /** Lado del viewport. Default: `'left'`. */
+  anchor?: DrawerAnchor;
+  /**
+   * Estado mini (solo iconos). Solo se aplica con `variant="permanent"` o
+   * `"persistent"`. Si no se provee, el drawer está siempre expandido.
+   */
+  collapsed?: boolean;
+  /** Callback del botón de toggle (chevron). */
+  onToggleCollapse?: () => void;
+  /** Estado abierto/cerrado (aplica a `temporary` y `persistent`). */
+  open?: boolean;
+  /** Callback de cierre (backdrop o ESC en temporary). */
+  onClose?: MuiDrawerProps['onClose'];
+  /** Ancho en estado expandido. Default: 260. */
+  expandedWidth?: number;
+  /** Ancho en estado colapsado (solo iconos). Default: 72. */
+  collapsedWidth?: number;
+  /** Muestra el botón chevron para toggle collapsed. Default: true si `onToggleCollapse` está definido. */
+  showCollapseButton?: boolean;
+  /** Contenido del header (por encima de los items). Típicamente logo/brand. */
+  header?: ReactNode;
+  /** Contenido del footer (por debajo de los items). Típicamente user profile. */
+  footer?: ReactNode;
+  /**
+   * Nombre del preset de estilo registrado en `theme.styles.Drawer`.
+   * - `"default"` (o ausente) = estilo built-in del paquete.
+   */
+  preset?: string;
+  /** sx aplicado al Drawer (root). Se mergea después del preset. */
+  sx?: SxProps<Theme>;
+  /** sx aplicado al Paper interno. */
+  paperSx?: SxProps<Theme>;
+  className?: string;
+}
+
+export function Drawer({
+  children,
+  variant = 'permanent',
+  anchor = 'left',
+  collapsed = false,
+  onToggleCollapse,
+  open,
+  onClose,
+  expandedWidth = 260,
+  collapsedWidth = 72,
+  showCollapseButton,
+  header,
+  footer,
+  preset,
+  sx,
+  paperSx,
+  className,
+}: DrawerProps) {
+  const theme = useTheme();
+  const presetSx = resolvePreset('Drawer', preset, theme);
+
+  // El mini-variant solo tiene sentido en permanent / persistent.
+  const supportsCollapsed = variant !== 'temporary';
+  const effectiveWidth =
+    supportsCollapsed && collapsed ? collapsedWidth : expandedWidth;
+
+  const contextValue = useMemo(
+    () => ({
+      collapsed: supportsCollapsed && collapsed,
+      width: effectiveWidth,
+    }),
+    [supportsCollapsed, collapsed, effectiveWidth],
+  );
+
+  const rootSx: SxProps<Theme> = [
+    buildDrawerSx({ width: effectiveWidth }),
+    ...(presetSx ? [presetSx] : []),
+    ...(Array.isArray(sx) ? sx : sx ? [sx] : []),
+  ];
+
+  const shouldShowToggle =
+    showCollapseButton ?? (supportsCollapsed && !!onToggleCollapse);
+
+  const openProp =
+    variant === 'permanent'
+      ? true
+      : open !== undefined
+        ? open
+        : false;
+
+  return (
+    <DrawerContext.Provider value={contextValue}>
+      <MuiDrawer
+        variant={variant}
+        anchor={anchor}
+        open={openProp}
+        onClose={onClose}
+        className={className}
+        sx={rootSx}
+        PaperProps={{
+          sx: paperSx,
+        }}
+      >
+        {header && (
+          <Box
+            sx={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: contextValue.collapsed
+                ? 'center'
+                : 'space-between',
+              px: contextValue.collapsed ? 1 : 2,
+              py: 1.5,
+              minHeight: 64,
+              flexShrink: 0,
+            }}
+          >
+            {!contextValue.collapsed && (
+              <Box sx={{ flex: 1, minWidth: 0 }}>{header}</Box>
+            )}
+            {shouldShowToggle && (
+              <IconButton
+                size="small"
+                onClick={onToggleCollapse}
+                aria-label={collapsed ? 'Expandir menú' : 'Colapsar menú'}
+              >
+                {collapsed ? <ChevronRightIcon /> : <ChevronLeftIcon />}
+              </IconButton>
+            )}
+          </Box>
+        )}
+
+        {!header && shouldShowToggle && (
+          <Box
+            sx={{
+              display: 'flex',
+              justifyContent: contextValue.collapsed
+                ? 'center'
+                : 'flex-end',
+              px: 1,
+              py: 1,
+            }}
+          >
+            <IconButton
+              size="small"
+              onClick={onToggleCollapse}
+              aria-label={collapsed ? 'Expandir menú' : 'Colapsar menú'}
+            >
+              {collapsed ? <ChevronRightIcon /> : <ChevronLeftIcon />}
+            </IconButton>
+          </Box>
+        )}
+
+        <Box
+          component="nav"
+          sx={{
+            flex: 1,
+            overflowY: 'auto',
+            overflowX: 'hidden',
+            py: 1,
+          }}
+        >
+          {children}
+        </Box>
+
+        {footer && (
+          <Box
+            sx={{
+              flexShrink: 0,
+              borderTop: (t) => `1px solid ${t.palette.divider}`,
+              p: contextValue.collapsed ? 1 : 1.5,
+              display: 'flex',
+              justifyContent: contextValue.collapsed
+                ? 'center'
+                : 'flex-start',
+            }}
+          >
+            {footer}
+          </Box>
+        )}
+      </MuiDrawer>
+    </DrawerContext.Provider>
+  );
+}
+
+export default Drawer;

package/src/components/Drawer/DrawerContext.ts

@@ -0,0 +1,26 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Context interno del Drawer. Permite que los sub-componentes (DrawerItem,
+ * DrawerSection, etc.) reaccionen al estado `collapsed` sin necesidad de
+ * recibirlo por props explícitas.
+ */
+export interface DrawerContextValue {
+  /** Si el drawer está en modo mini (solo iconos). */
+  collapsed: boolean;
+  /** Ancho actual del drawer (útil para sub-componentes que necesiten layout). */
+  width: number;
+}
+
+export const DrawerContext = createContext<DrawerContextValue | null>(null);
+
+/**
+ * Hook para leer el estado del drawer desde cualquier sub-componente. Si se
+ * llama fuera de un `<Drawer>`, devuelve valores por defecto (collapsed=false)
+ * para que los items renderizados sueltos no exploten.
+ */
+export function useDrawerContext(): DrawerContextValue {
+  const ctx = useContext(DrawerContext);
+  if (ctx) return ctx;
+  return { collapsed: false, width: 260 };
+}