@soyfri/shared-library 2.0.0-beta.17 → 2.0.0-beta.18

package/src/components/AppBar/AppBar.stories.tsx

@@ -0,0 +1,316 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Box,
+  Button,
+  Divider,
+  IconButton,
+  Tooltip,
+  Typography,
+} from '@mui/material';
+import NotificationsIcon from '@mui/icons-material/Notifications';
+import HelpOutlineIcon from '@mui/icons-material/HelpOutline';
+import PersonIcon from '@mui/icons-material/Person';
+import SettingsIcon from '@mui/icons-material/Settings';
+import LogoutIcon from '@mui/icons-material/Logout';
+import DashboardIcon from '@mui/icons-material/Dashboard';
+
+import { AppBar } from './AppBar';
+import { AppBarMenuToggle } from './AppBarMenuToggle';
+import { ActionMenu, ActionMenuItem } from '../ActionMenu';
+import { Avatar } from '../Avatar';
+import { Icon } from '../Icon';
+
+const meta: Meta<typeof AppBar> = {
+  title: 'Components/AppBar',
+  component: AppBar,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'AppBar (header superior) pensado como shell compositivo. El consumer arma el contenido libremente (logo, título, menú de usuario, etc.) y puede usar `AppBarMenuToggle` para el botón hamburguesa sincronizado con el drawer.',
+      },
+    },
+  },
+  argTypes: {
+    position: {
+      control: 'select',
+      options: ['fixed', 'sticky', 'static', 'absolute', 'relative'],
+    },
+    color: {
+      control: 'select',
+      options: ['default', 'primary', 'secondary', 'transparent', 'inherit'],
+    },
+    elevation: { control: { type: 'number', min: 0, max: 24, step: 1 } },
+    height: { control: { type: 'number', min: 48, max: 96, step: 4 } },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof AppBar>;
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+const SampleLogo = () => (
+  <Box
+    sx={{
+      width: 32,
+      height: 32,
+      borderRadius: 1,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      backgroundColor: 'primary.main',
+      color: 'primary.contrastText',
+      fontWeight: 700,
+      fontSize: 14,
+    }}
+  >
+    F
+  </Box>
+);
+
+const SampleBrand = ({
+  title,
+  subtitle,
+  onClick,
+}: {
+  title: string;
+  subtitle?: string;
+  onClick?: () => void;
+}) => (
+  <Box
+    role={onClick ? 'button' : undefined}
+    tabIndex={onClick ? 0 : undefined}
+    onClick={onClick}
+    sx={{
+      display: 'flex',
+      alignItems: 'center',
+      gap: 1.25,
+      cursor: onClick ? 'pointer' : 'default',
+      userSelect: 'none',
+      minWidth: 0,
+    }}
+  >
+    <SampleLogo />
+    <Box sx={{ display: 'flex', flexDirection: 'column', lineHeight: 1.2 }}>
+      <Typography component="span" variant="subtitle1" noWrap sx={{ fontWeight: 700 }}>
+        {title}
+      </Typography>
+      {subtitle && (
+        <Typography component="span" variant="caption" color="text.secondary" noWrap>
+          {subtitle}
+        </Typography>
+      )}
+    </Box>
+  </Box>
+);
+
+const SampleUserMenu = () => (
+  <ActionMenu
+    menuSx={{ minWidth: 240 }}
+    trigger={
+      <IconButton size="small" aria-label="Cuenta" sx={{ p: 0.5 }}>
+        <Avatar
+          items={[{ badge: 'AP', text: 'Andrea Pineda' }]}
+          size="sm"
+          showText={false}
+        />
+      </IconButton>
+    }
+  >
+    <Box sx={{ px: 2, py: 1.25 }}>
+      <Typography variant="subtitle2" sx={{ fontWeight: 700 }} noWrap>
+        Andrea Pineda
+      </Typography>
+      <Typography variant="caption" color="text.secondary" noWrap>
+        andrea@soyfri.com
+      </Typography>
+    </Box>
+    <Divider />
+    <ActionMenuItem icon={<Icon size="xs"><PersonIcon fontSize="small" /></Icon>}>
+      Mi perfil
+    </ActionMenuItem>
+    <ActionMenuItem icon={<Icon size="xs"><SettingsIcon fontSize="small" /></Icon>}>
+      Configuración
+    </ActionMenuItem>
+    <Divider />
+    <ActionMenuItem
+      icon={<Icon size="xs"><LogoutIcon fontSize="small" /></Icon>}
+      sx={(theme) => ({
+        color: theme.palette.error.main,
+        '& .MuiListItemIcon-root': { color: theme.palette.error.main },
+      })}
+    >
+      Cerrar sesión
+    </ActionMenuItem>
+  </ActionMenu>
+);
+
+const SampleBody = () => (
+  <Box sx={{ p: 3 }}>
+    <Typography variant="h5" gutterBottom>
+      Contenido de la página
+    </Typography>
+    <Typography variant="body2" color="text.secondary" sx={{ mb: 2 }}>
+      Este bloque sólo demuestra el layout bajo el AppBar.
+    </Typography>
+    {Array.from({ length: 20 }).map((_, idx) => (
+      <Typography key={idx} variant="body2" sx={{ mb: 1 }}>
+        Línea {idx + 1} — contenido de ejemplo para scroll sticky.
+      </Typography>
+    ))}
+  </Box>
+);
+
+// ── Stories ──────────────────────────────────────────────────────────────
+
+export const BasicHeader: Story = {
+  args: {
+    position: 'sticky',
+    color: 'default',
+    elevation: 1,
+    height: 64,
+  },
+  render: (args) => (
+    <>
+      <AppBar {...args}>
+        <SampleBrand title="Afiliaciones" subtitle="Panel administrativo" />
+      </AppBar>
+      <SampleBody />
+    </>
+  ),
+};
+
+export const WithMenuToggle: Story = {
+  render: (args) => {
+    const [open, setOpen] = useState(false);
+    return (
+      <>
+        <AppBar
+          {...args}
+          onMenuToggle={() => setOpen((value) => !value)}
+          menuOpen={open}
+        >
+          <AppBarMenuToggle />
+          <SampleBrand title="Afiliaciones" />
+        </AppBar>
+        <Box sx={{ p: 3 }}>
+          <Typography variant="body2">
+            Drawer {open ? 'abierto' : 'cerrado'} — el icono cambia según el
+            estado. Click en el botón hamburguesa para alternar.
+          </Typography>
+        </Box>
+      </>
+    );
+  },
+};
+
+export const WithUserMenu: Story = {
+  render: (args) => (
+    <>
+      <AppBar {...args}>
+        <SampleBrand title="Afiliaciones" />
+        <Box sx={{ flex: 1 }} />
+        <SampleUserMenu />
+      </AppBar>
+      <SampleBody />
+    </>
+  ),
+};
+
+export const CompleteDashboardHeader: Story = {
+  render: (args) => {
+    const [open, setOpen] = useState(true);
+    return (
+      <>
+        <AppBar
+          {...args}
+          onMenuToggle={() => setOpen((value) => !value)}
+          menuOpen={open}
+        >
+          <AppBarMenuToggle />
+          <SampleBrand
+            title="Afiliaciones"
+            subtitle="Panel administrativo"
+            onClick={() => console.log('go home')}
+          />
+          <Box sx={{ flex: 1 }} />
+          <Tooltip title="Notificaciones" arrow>
+            <IconButton color="inherit">
+              <Icon size="sm"><NotificationsIcon /></Icon>
+            </IconButton>
+          </Tooltip>
+          <Tooltip title="Ayuda" arrow>
+            <IconButton color="inherit">
+              <Icon size="sm"><HelpOutlineIcon /></Icon>
+            </IconButton>
+          </Tooltip>
+          <SampleUserMenu />
+        </AppBar>
+        <SampleBody />
+      </>
+    );
+  },
+};
+
+export const TransparentVariant: Story = {
+  args: {
+    color: 'transparent',
+    elevation: 0,
+  },
+  render: (args) => (
+    <Box
+      sx={{
+        minHeight: '100vh',
+        background:
+          'linear-gradient(135deg, #f0f4ff 0%, #e6f7ff 50%, #fff5f5 100%)',
+      }}
+    >
+      <AppBar {...args}>
+        <SampleBrand title="Afiliaciones" />
+        <Box sx={{ flex: 1 }} />
+        <Button variant="contained" color="primary" size="small">
+          Iniciar sesión
+        </Button>
+      </AppBar>
+      <Box sx={{ p: 3 }}>
+        <Typography variant="h5">Landing page transparente</Typography>
+        <Typography variant="body2" color="text.secondary">
+          Sin sombra, con borde sutil — útil para headers sobre hero sections.
+        </Typography>
+      </Box>
+    </Box>
+  ),
+};
+
+export const PrimaryColorWithMenu: Story = {
+  args: {
+    color: 'primary',
+  },
+  render: (args) => {
+    const [open, setOpen] = useState(false);
+    return (
+      <>
+        <AppBar
+          {...args}
+          onMenuToggle={() => setOpen((value) => !value)}
+          menuOpen={open}
+        >
+          <AppBarMenuToggle />
+          <Box sx={{ mr: 1, display: 'flex', alignItems: 'center' }}>
+            <Icon size="sm"><DashboardIcon /></Icon>
+          </Box>
+          <Typography variant="h6" sx={{ fontWeight: 700 }}>
+            Dashboard
+          </Typography>
+          <Box sx={{ flex: 1 }} />
+          <SampleUserMenu />
+        </AppBar>
+        <SampleBody />
+      </>
+    );
+  },
+};

package/src/components/AppBar/AppBar.sx.ts

@@ -0,0 +1,32 @@
+import type { SxProps, Theme } from '@mui/material/styles';
+
+export interface BuildAppBarSxArgs {
+  /** Altura en px. Default: 64. */
+  height?: number;
+  /** Color del AppBar (se pasa al MuiAppBar). */
+  transparent?: boolean;
+}
+
+/**
+ * sx del root del MuiAppBar. Define altura fija y layout flex del Toolbar
+ * interno. El color/elevación se dejan a las props nativas de MuiAppBar.
+ */
+export function buildAppBarSx({
+  height = 64,
+  transparent = false,
+}: BuildAppBarSxArgs): SxProps<Theme> {
+  return (theme) => ({
+    minHeight: height,
+    justifyContent: 'center',
+    backgroundImage: 'none',
+    ...(transparent && {
+      backgroundColor: 'transparent',
+      boxShadow: 'none',
+      borderBottom: `1px solid ${theme.palette.divider}`,
+    }),
+    '& .MuiToolbar-root': {
+      minHeight: height,
+      gap: 1.5,
+    },
+  });
+}

package/src/components/AppBar/AppBar.tsx

@@ -0,0 +1,119 @@
+import React, { useMemo, type ReactNode } from 'react';
+import {
+  AppBar as MuiAppBar,
+  Toolbar,
+  type AppBarProps as MuiAppBarProps,
+} from '@mui/material';
+import {
+  useTheme,
+  type SxProps,
+  type Theme,
+} from '@mui/material/styles';
+
+import { AppBarContext } from './AppBarContext';
+import { buildAppBarSx } from './AppBar.sx';
+import { resolvePreset } from '../_shared/resolvePreset';
+
+export type AppBarPosition = 'fixed' | 'sticky' | 'static' | 'absolute' | 'relative';
+export type AppBarColor =
+  | 'default'
+  | 'primary'
+  | 'secondary'
+  | 'transparent'
+  | 'inherit';
+
+export interface AppBarProps {
+  /** Contenido del AppBar (típicamente sub-componentes + acciones custom). */
+  children?: ReactNode;
+  /** Posicionamiento. Default: `'sticky'`. */
+  position?: AppBarPosition;
+  /** Color. Default: `'default'`. */
+  color?: AppBarColor;
+  /** Nivel de sombra. Default: 1. */
+  elevation?: number;
+  /** Altura en px. Default: 64. */
+  height?: number;
+  /**
+   * Handler del botón hamburguesa. Se expone vía AppBarContext para que el
+   * sub-componente `<AppBarMenuToggle>` lo consuma sin prop drilling.
+   */
+  onMenuToggle?: () => void;
+  /** Estado del drawer asociado (para que el icono del toggle cambie). */
+  menuOpen?: boolean;
+  /**
+   * Nombre del preset de estilo registrado en `theme.styles.AppBar`.
+   * - `"default"` (o ausente) = estilo built-in del paquete.
+   */
+  preset?: string;
+  /** sx del root (se mergea después del preset). */
+  sx?: SxProps<Theme>;
+  /** sx del Toolbar interno. */
+  toolbarSx?: SxProps<Theme>;
+  className?: string;
+  /** Otras props nativas del MuiAppBar (ej. `enableColorOnDark`). */
+  appBarProps?: Omit<
+    MuiAppBarProps,
+    'position' | 'color' | 'elevation' | 'sx' | 'children' | 'className'
+  >;
+}
+
+/**
+ * AppBar (header superior) del paquete. Se diseñó como un shell compositivo
+ * — el consumer arma el contenido libremente (logo, título, menú de usuario,
+ * etc.) y puede usar `<AppBarMenuToggle>` para el botón hamburguesa
+ * integrado con el contexto.
+ *
+ * Patrón recomendado para navegación en dashboards:
+ *
+ * ```tsx
+ * <AppBar onMenuToggle={toggleDrawer}>
+ *   <AppBarMenuToggle />
+ *   <MyBrand />
+ *   <Box sx={{ flex: 1 }} />
+ *   <MyUserMenu />
+ * </AppBar>
+ * ```
+ */
+export function AppBar({
+  children,
+  position = 'sticky',
+  color = 'default',
+  elevation = 1,
+  height = 64,
+  onMenuToggle,
+  menuOpen,
+  preset,
+  sx,
+  toolbarSx,
+  appBarProps,
+}: AppBarProps) {
+  const theme = useTheme();
+  const presetSx = resolvePreset('AppBar', preset, theme);
+
+  const rootSx: SxProps<Theme> = [
+    buildAppBarSx({ height, transparent: color === 'transparent' }),
+    ...(presetSx ? [presetSx] : []),
+    ...(Array.isArray(sx) ? sx : sx ? [sx] : []),
+  ];
+
+  const contextValue = useMemo(
+    () => ({ onMenuToggle, menuOpen }),
+    [onMenuToggle, menuOpen],
+  );
+
+  return (
+    <AppBarContext.Provider value={contextValue}>
+      <MuiAppBar
+        position={position}
+        color={color}
+        elevation={elevation}
+        sx={rootSx}
+        {...appBarProps}
+      >
+        <Toolbar sx={toolbarSx}>{children}</Toolbar>
+      </MuiAppBar>
+    </AppBarContext.Provider>
+  );
+}
+
+export default AppBar;

package/src/components/AppBar/AppBarContext.ts

@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Context interno del AppBar. Permite que sub-componentes (MenuToggle, etc.)
+ * consuman callbacks registrados en el AppBar padre sin tener que pasarlos
+ * por props explícitas.
+ */
+export interface AppBarContextValue {
+  /** Handler del botón hamburguesa. Si es undefined, el toggle se oculta. */
+  onMenuToggle?: () => void;
+  /** Estado actual del drawer asociado (usado por el icono del toggle). */
+  menuOpen?: boolean;
+}
+
+export const AppBarContext = createContext<AppBarContextValue | null>(null);
+
+/**
+ * Hook para leer el contexto del AppBar. Si se llama fuera de un `<AppBar>`,
+ * devuelve un objeto vacío — los sub-componentes caen en modo "standalone"
+ * con sus defaults en lugar de romper.
+ */
+export function useAppBarContext(): AppBarContextValue {
+  const ctx = useContext(AppBarContext);
+  return ctx ?? {};
+}

package/src/components/AppBar/AppBarMenuToggle.tsx

@@ -0,0 +1,90 @@
+import { type ReactNode } from 'react';
+import { IconButton, Tooltip } from '@mui/material';
+import MenuIcon from '@mui/icons-material/Menu';
+import MenuOpenIcon from '@mui/icons-material/MenuOpen';
+import type { SxProps, Theme } from '@mui/material/styles';
+
+import { useAppBarContext } from './AppBarContext';
+
+export interface AppBarMenuToggleProps {
+  /**
+   * Callback explícito. Si se omite, se consume del `AppBarContext`. Útil para
+   * usar el toggle fuera de un `<AppBar>` (p.ej. en un header custom).
+   */
+  onClick?: () => void;
+  /** Estado del drawer asociado. Si se omite, se lee del `AppBarContext`. */
+  menuOpen?: boolean;
+  /** Icono custom cuando el drawer está cerrado. Default: `<MenuIcon />`. */
+  closedIcon?: ReactNode;
+  /** Icono custom cuando el drawer está abierto. Default: `<MenuOpenIcon />`. */
+  openIcon?: ReactNode;
+  /** Texto de tooltip. Default: "Menú". */
+  tooltip?: string;
+  /** aria-label del botón. Default: el mismo tooltip. */
+  ariaLabel?: string;
+  /** Tamaño del IconButton. Default: `'medium'`. */
+  size?: 'small' | 'medium' | 'large';
+  /** Oculta el botón cuando no hay handler disponible. Default: true. */
+  hideIfNoHandler?: boolean;
+  sx?: SxProps<Theme>;
+  className?: string;
+}
+
+/**
+ * Botón hamburguesa del AppBar. Por default consume `onMenuToggle` y
+ * `menuOpen` del `AppBarContext` (pattern composicional), pero permite
+ * overrides explícitos si se usa fuera de un `<AppBar>`.
+ *
+ * ```tsx
+ * <AppBar onMenuToggle={toggleDrawer} menuOpen={open}>
+ *   <AppBarMenuToggle />
+ *   ...
+ * </AppBar>
+ * ```
+ */
+export function AppBarMenuToggle({
+  onClick,
+  menuOpen,
+  closedIcon,
+  openIcon,
+  tooltip = 'Menú',
+  ariaLabel,
+  size = 'medium',
+  hideIfNoHandler = true,
+  sx,
+  className,
+}: AppBarMenuToggleProps) {
+  const ctx = useAppBarContext();
+
+  const handler = onClick ?? ctx.onMenuToggle;
+  const open = menuOpen ?? ctx.menuOpen ?? false;
+
+  if (!handler && hideIfNoHandler) {
+    return null;
+  }
+
+  const icon = open
+    ? (openIcon ?? <MenuOpenIcon />)
+    : (closedIcon ?? <MenuIcon />);
+
+  return (
+    <Tooltip title={tooltip} arrow>
+      <span>
+        <IconButton
+          size={size}
+          edge="start"
+          color="inherit"
+          aria-label={ariaLabel ?? tooltip}
+          onClick={handler}
+          disabled={!handler}
+          className={className}
+          sx={sx}
+        >
+          {icon}
+        </IconButton>
+      </span>
+    </Tooltip>
+  );
+}
+
+export default AppBarMenuToggle;

package/src/components/AppBar/index.ts

@@ -0,0 +1,12 @@
+export { AppBar, default } from './AppBar';
+export type {
+  AppBarProps,
+  AppBarPosition,
+  AppBarColor,
+} from './AppBar';
+
+export { AppBarMenuToggle } from './AppBarMenuToggle';
+export type { AppBarMenuToggleProps } from './AppBarMenuToggle';
+
+export { AppBarContext, useAppBarContext } from './AppBarContext';
+export type { AppBarContextValue } from './AppBarContext';