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

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,123 @@
+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 con los sub-componentes que exporta el
+ * paquete (`AppBarBrand`, `AppBarMenuToggle`, `AppBarUserMenu`) + cualquier
+ * otra cosa custom.
+ *
+ * Patrón recomendado para navegación en dashboards:
+ *
+ * ```tsx
+ * <AppBar onMenuToggle={toggleDrawer}>
+ *   <AppBarMenuToggle />
+ *   <AppBarBrand logo={<Logo />} title="Afiliaciones" />
+ *   <Box sx={{ flex: 1 }} />
+ *   <AppBarUserMenu user={user} items={menuItems} />
+ * </AppBar>
+ * ```
+ */
+export function AppBar({
+  children,
+  position = 'sticky',
+  color = 'default',
+  elevation = 1,
+  height = 64,
+  onMenuToggle,
+  menuOpen,
+  preset,
+  sx,
+  toolbarSx,
+  className,
+  appBarProps,
+}: AppBarProps) {
+  const theme = useTheme();
+  const presetSx = resolvePreset('AppBar', preset, theme);
+
+  const transparent = color === 'transparent';
+
+  const rootSx: SxProps<Theme> = [
+    buildAppBarSx({ height, 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 === 'transparent' ? 'transparent' : color}
+        elevation={elevation}
+        className={className}
+        sx={rootSx}
+        {...appBarProps}
+      >
+        <Toolbar sx={toolbarSx}>{children}</Toolbar>
+      </MuiAppBar>
+    </AppBarContext.Provider>
+  );
+}
+
+export default AppBar;

package/src/components/AppBar/AppBarBrand.tsx

@@ -0,0 +1,120 @@
+import React, { type ReactNode, type MouseEvent } from 'react';
+import { Box, Typography } from '@mui/material';
+import type { SxProps, Theme } from '@mui/material/styles';
+
+export interface AppBarBrandProps {
+  /** Logo (img, svg, componente). Se muestra a la izquierda del título. */
+  logo?: ReactNode;
+  /** Título del sistema. */
+  title?: ReactNode;
+  /** Subtítulo opcional (p.ej. nombre de módulo actual). */
+  subtitle?: ReactNode;
+  /** Handler de click sobre todo el brand (típicamente navega al home). */
+  onClick?: (event: MouseEvent<HTMLDivElement>) => void;
+  /** Oculta solo el título en viewports pequeños (mantiene el logo). Default: true. */
+  hideTitleOnMobile?: boolean;
+  sx?: SxProps<Theme>;
+  className?: string;
+}
+
+/**
+ * Brand del AppBar: combina logo + título + subtítulo opcional con un
+ * click handler global (típicamente para navegar al home).
+ *
+ * ```tsx
+ * <AppBarBrand
+ *   logo={<img src={logo} alt="" height={32} />}
+ *   title="Afiliaciones"
+ *   subtitle="Panel administrativo"
+ *   onClick={() => navigate('/')}
+ * />
+ * ```
+ */
+export function AppBarBrand({
+  logo,
+  title,
+  subtitle,
+  onClick,
+  hideTitleOnMobile = true,
+  sx,
+  className,
+}: AppBarBrandProps) {
+  const clickable = !!onClick;
+
+  const rootSx: SxProps<Theme> = [
+    {
+      display: 'flex',
+      alignItems: 'center',
+      gap: 1.25,
+      cursor: clickable ? 'pointer' : 'default',
+      userSelect: 'none',
+      minWidth: 0,
+    },
+    ...(Array.isArray(sx) ? sx : sx ? [sx] : []),
+  ];
+
+  return (
+    <Box
+      role={clickable ? 'button' : undefined}
+      tabIndex={clickable ? 0 : undefined}
+      onClick={onClick}
+      onKeyDown={(event) => {
+        if (!clickable) return;
+        if (event.key === 'Enter' || event.key === ' ') {
+          event.preventDefault();
+          onClick?.(event as unknown as MouseEvent<HTMLDivElement>);
+        }
+      }}
+      className={className}
+      sx={rootSx}
+    >
+      {logo && (
+        <Box
+          component="span"
+          sx={{
+            display: 'flex',
+            alignItems: 'center',
+            flexShrink: 0,
+          }}
+        >
+          {logo}
+        </Box>
+      )}
+      {(title || subtitle) && (
+        <Box
+          sx={{
+            display: hideTitleOnMobile
+              ? { xs: 'none', sm: 'flex' }
+              : 'flex',
+            flexDirection: 'column',
+            minWidth: 0,
+            lineHeight: 1.2,
+          }}
+        >
+          {title && (
+            <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>
+  );
+}
+
+export default AppBarBrand;

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 React, { 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/AppBarUserMenu.tsx

@@ -0,0 +1,217 @@
+import React, { useState, type ReactNode, type MouseEvent } from 'react';
+import {
+  Avatar,
+  Box,
+  Divider,
+  IconButton,
+  ListItemIcon,
+  ListItemText,
+  Menu,
+  MenuItem,
+  Tooltip,
+  Typography,
+} from '@mui/material';
+import type { SxProps, Theme } from '@mui/material/styles';
+
+export interface AppBarUserMenuItem {
+  /** Key única. Si no se provee, se usa el label. */
+  key?: string;
+  /** Texto del item. */
+  label: ReactNode;
+  /** Icono opcional a la izquierda. */
+  icon?: ReactNode;
+  /** Handler de click. */
+  onClick?: (event: MouseEvent<HTMLLIElement>) => void;
+  /** Deshabilita el item. */
+  disabled?: boolean;
+  /** Pinta el item en color error (típico para "Cerrar sesión"). */
+  danger?: boolean;
+  /** Inserta un `<Divider />` ANTES de este item. */
+  dividerBefore?: boolean;
+}
+
+export interface AppBarUserMenuUser {
+  /** Nombre a mostrar en el header del menú. */
+  name?: ReactNode;
+  /** Email / subtítulo secundario. */
+  email?: ReactNode;
+  /** URL del avatar. Si se omite, se muestran iniciales del `name`. */
+  avatarUrl?: string;
+  /** Iniciales custom. Si se omite, se calculan del `name`. */
+  initials?: string;
+}
+
+export interface AppBarUserMenuProps {
+  /** Datos del usuario a mostrar. */
+  user?: AppBarUserMenuUser;
+  /** Items del menú. */
+  items: AppBarUserMenuItem[];
+  /**
+   * Si `true`, oculta la fila con nombre + email en el tope del menú.
+   * Default: `false`.
+   */
+  hideUserHeader?: boolean;
+  /** Tooltip del trigger. Default: "Cuenta". */
+  triggerTooltip?: string;
+  /** Tamaño del Avatar en px. Default: 36. */
+  avatarSize?: number;
+  /** sx del Paper del Menu. */
+  menuSx?: SxProps<Theme>;
+  /** sx del trigger (IconButton). */
+  triggerSx?: SxProps<Theme>;
+  className?: string;
+}
+
+function computeInitials(name?: ReactNode): string {
+  if (typeof name !== 'string') return '?';
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return '?';
+  const first = parts[0]?.charAt(0) ?? '';
+  const last = parts.length > 1 ? (parts[parts.length - 1]?.charAt(0) ?? '') : '';
+  return (first + last).toUpperCase();
+}
+
+/**
+ * Menú de usuario del AppBar: avatar clickable que despliega un menú con la
+ * info del usuario (nombre + email) y una lista de acciones (perfil, cerrar
+ * sesión, etc).
+ *
+ * ```tsx
+ * <AppBarUserMenu
+ *   user={{ name: 'Andrea', email: 'a@soyfri.com' }}
+ *   items={[
+ *     { label: 'Perfil', icon: <PersonIcon />, onClick: goToProfile },
+ *     { label: 'Cerrar sesión', icon: <LogoutIcon />, onClick: logout, danger: true, dividerBefore: true },
+ *   ]}
+ * />
+ * ```
+ */
+export function AppBarUserMenu({
+  user,
+  items,
+  hideUserHeader = false,
+  triggerTooltip = 'Cuenta',
+  avatarSize = 36,
+  menuSx,
+  triggerSx,
+  className,
+}: AppBarUserMenuProps) {
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
+  const open = Boolean(anchorEl);
+
+  const handleOpen = (event: MouseEvent<HTMLElement>) => {
+    setAnchorEl(event.currentTarget);
+  };
+  const handleClose = () => setAnchorEl(null);
+
+  const handleItemClick = (
+    event: MouseEvent<HTMLLIElement>,
+    item: AppBarUserMenuItem,
+  ) => {
+    event.stopPropagation();
+    item.onClick?.(event);
+    handleClose();
+  };
+
+  const initials = user?.initials ?? computeInitials(user?.name);
+  const showUserHeader = !hideUserHeader && (user?.name || user?.email);
+
+  return (
+    <Box component="span" className={className}>
+      <Tooltip title={triggerTooltip} arrow>
+        <IconButton
+          onClick={handleOpen}
+          size="small"
+          aria-label={triggerTooltip}
+          aria-haspopup="menu"
+          aria-expanded={open || undefined}
+          sx={[{ p: 0.5 }, ...(Array.isArray(triggerSx) ? triggerSx : triggerSx ? [triggerSx] : [])]}
+        >
+          <Avatar
+            src={user?.avatarUrl}
+            sx={{
+              width: avatarSize,
+              height: avatarSize,
+              fontSize: avatarSize * 0.4,
+              fontWeight: 600,
+            }}
+          >
+            {!user?.avatarUrl && initials}
+          </Avatar>
+        </IconButton>
+      </Tooltip>
+
+      <Menu
+        anchorEl={anchorEl}
+        open={open}
+        onClose={handleClose}
+        anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+        transformOrigin={{ vertical: 'top', horizontal: 'right' }}
+        slotProps={{
+          paper: {
+            sx: { minWidth: 240, ...(menuSx as any) },
+          },
+        }}
+      >
+        {showUserHeader && (
+          <Box
+            sx={{
+              px: 2,
+              py: 1.25,
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 0.25,
+            }}
+          >
+            {user?.name && (
+              <Typography variant="subtitle2" noWrap sx={{ fontWeight: 700 }}>
+                {user.name}
+              </Typography>
+            )}
+            {user?.email && (
+              <Typography variant="caption" color="text.secondary" noWrap>
+                {user.email}
+              </Typography>
+            )}
+          </Box>
+        )}
+        {showUserHeader && <Divider />}
+
+        {items.map((item, idx) => {
+          const key = item.key ?? `${String(item.label)}-${idx}`;
+          const node = (
+            <MenuItem
+              key={key}
+              disabled={item.disabled}
+              onClick={(event) => handleItemClick(event, item)}
+              sx={(theme) => ({
+                color: item.danger ? theme.palette.error.main : 'inherit',
+                '& .MuiListItemIcon-root': {
+                  color: item.danger
+                    ? theme.palette.error.main
+                    : 'inherit',
+                  minWidth: 32,
+                },
+              })}
+            >
+              {item.icon && <ListItemIcon>{item.icon}</ListItemIcon>}
+              <ListItemText primary={item.label} />
+            </MenuItem>
+          );
+
+          if (item.dividerBefore && idx > 0) {
+            return (
+              <React.Fragment key={`${key}-frag`}>
+                <Divider />
+                {node}
+              </React.Fragment>
+            );
+          }
+          return node;
+        })}
+      </Menu>
+    </Box>
+  );
+}
+
+export default AppBarUserMenu;

package/src/components/AppBar/index.ts

@@ -0,0 +1,25 @@
+export { AppBar, default } from './AppBar';
+export type {
+  AppBarProps,
+  AppBarPosition,
+  AppBarColor,
+} from './AppBar';
+
+export { AppBarBrand } from './AppBarBrand';
+export type { AppBarBrandProps } from './AppBarBrand';
+
+export { AppBarMenuToggle } from './AppBarMenuToggle';
+export type { AppBarMenuToggleProps } from './AppBarMenuToggle';
+
+export { AppBarUserMenu } from './AppBarUserMenu';
+export type {
+  AppBarUserMenuProps,
+  AppBarUserMenuItem,
+  AppBarUserMenuUser,
+} from './AppBarUserMenu';
+
+export { AppBarContext, useAppBarContext } from './AppBarContext';
+export type { AppBarContextValue } from './AppBarContext';
+
+export { buildAppBarSx } from './AppBar.sx';
+export type { BuildAppBarSxArgs } from './AppBar.sx';