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

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';

package/src/components/Autocomplete/Autocomplete.definitions.ts

@@ -252,3 +252,226 @@ export const ManyOptionsExample = () => {
   );
 };
 `;
+
+// =============================================================================
+// WITH ERROR / HELPER TEXT
+// =============================================================================
+export const WithErrorAutocompleteDefinition = `
+import React, { useState } from 'react';
+import Autocomplete from './Autocomplete';
+import { Box } from '@mui/material';
+
+const options = [
+  { value: '10', label: '10' },
+  { value: '25', label: '25' },
+];
+
+export const WithErrorExample = () => {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Box sx={{ width: 300 }}>
+      <Autocomplete
+        label="Cantidad"
+        options={options}
+        value={value}
+        onChange={(val) => setValue(val as string | null)}
+        error={\!value}
+        helperText={\!value ? 'Debes seleccionar una cantidad' : ' '}
+      />
+    </Box>
+  );
+};
+`;
+
+// =============================================================================
+// LABEL POSITION
+// =============================================================================
+export const LabelPositionAutocompleteDefinition = `
+import React, { useState } from 'react';
+import Autocomplete from './Autocomplete';
+import { Box, Stack } from '@mui/material';
+
+const options = [
+  { value: 'a', label: 'Opción A' },
+  { value: 'b', label: 'Opción B' },
+];
+
+export const LabelPositionExample = () => {
+  const [a, setA] = useState<string | null>(null);
+  const [b, setB] = useState<string | null>(null);
+  return (
+    <Stack spacing={3} sx={{ width: 320 }}>
+      <Autocomplete
+        label="Outside (default)"
+        labelPosition="outside"
+        options={options}
+        value={a}
+        onChange={(val) => setA(val as string | null)}
+      />
+      <Autocomplete
+        label="Floating"
+        labelPosition="floating"
+        options={options}
+        value={b}
+        onChange={(val) => setB(val as string | null)}
+      />
+    </Stack>
+  );
+};
+`;
+
+// =============================================================================
+// CUSTOM BORDER RADIUS
+// =============================================================================
+export const CustomBorderRadiusAutocompleteDefinition = `
+import React, { useState } from 'react';
+import Autocomplete from './Autocomplete';
+import { Box, Stack } from '@mui/material';
+
+const options = [
+  { value: '10', label: '10' },
+  { value: '25', label: '25' },
+];
+
+export const CustomBorderRadiusExample = () => {
+  const [a, setA] = useState<string | null>(null);
+  const [b, setB] = useState<string | null>(null);
+  const [c, setC] = useState<string | null>(null);
+  return (
+    <Stack spacing={2} sx={{ width: 300 }}>
+      <Autocomplete label="0" borderRadius={0} options={options} value={a} onChange={(v) => setA(v as string | null)} />
+      <Autocomplete label="10 (default)" borderRadius={10} options={options} value={b} onChange={(v) => setB(v as string | null)} />
+      <Autocomplete label="24 (pill)" borderRadius={24} options={options} value={c} onChange={(v) => setC(v as string | null)} />
+    </Stack>
+  );
+};
+`;
+
+// =============================================================================
+// EMPTY WITH PLACEHOLDER
+// =============================================================================
+export const EmptyWithPlaceholderAutocompleteDefinition = `
+import React, { useState } from 'react';
+import Autocomplete from './Autocomplete';
+import { Box } from '@mui/material';
+
+const options = [
+  { value: 'mx', label: 'México' },
+  { value: 'co', label: 'Colombia' },
+  { value: 'ar', label: 'Argentina' },
+];
+
+export const EmptyWithPlaceholderExample = () => {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Box sx={{ width: 300 }}>
+      <Autocomplete
+        label="País"
+        placeholder="Buscar país..."
+        options={options}
+        value={value}
+        onChange={(val) => setValue(val as string | null)}
+      />
+    </Box>
+  );
+};
+`;
+
+// =============================================================================
+// REACT HOOK FORM
+// =============================================================================
+export const RHFAutocompleteDefinition = `
+import React from 'react';
+import { useForm } from 'react-hook-form';
+import Autocomplete from './Autocomplete';
+import { Box, Button, Stack } from '@mui/material';
+
+const options = [
+  { value: 'mx', label: 'México' },
+  { value: 'co', label: 'Colombia' },
+  { value: 'ar', label: 'Argentina' },
+];
+
+type FormValues = { country: string | null };
+
+export const RHFExample = () => {
+  const { control, handleSubmit, watch } = useForm<FormValues>({
+    defaultValues: { country: null },
+  });
+
+  return (
+    <Box component="form" onSubmit={handleSubmit((data) => console.log(data))}>
+      <Stack spacing={2} sx={{ width: 320 }}>
+        <Autocomplete
+          name="country"
+          control={control}
+          validation={{ required: 'Campo requerido' }}
+          label="País"
+          placeholder="Seleccione..."
+          options={options}
+        />
+        <Button type="submit" variant="contained">Guardar</Button>
+        <Box>Valor actual: {JSON.stringify(watch('country'))}</Box>
+      </Stack>
+    </Box>
+  );
+};
+`;
+
+// =============================================================================
+// ASYNC — búsqueda remota contra un servicio
+// =============================================================================
+export const AsyncServiceAutocompleteDefinition = [
+'import React, { useState, useEffect, useMemo } from ', "'react'", ';',
+'import Autocomplete from ', "'./Autocomplete'", ';',
+'import { Box } from ', "'@mui/material'", ';',
+'import debounce from ', "'lodash/debounce'", ';',
+'',
+'// Supón que tienes un servicio:',
+'// await fetch(`/api/users?q=${query}`).then(r => r.json())',
+'async function fetchUsers(query: string) {',
+'  const res = await fetch(`/api/users?q=${encodeURIComponent(query)}`);',
+'  const data = await res.json();',
+'  return data.map((u: any) => ({ value: u.id, label: u.name }));',
+'}',
+'',
+'export const AsyncServiceExample = () => {',
+'  const [value, setValue] = useState<string | null>(null);',
+'  const [input, setInput] = useState("");',
+'  const [options, setOptions] = useState<any[]>([]);',
+'  const [loading, setLoading] = useState(false);',
+'',
+'  const search = useMemo(',
+'    () =>',
+'      debounce(async (q: string) => {',
+'        if (\!q) { setOptions([]); return; }',
+'        setLoading(true);',
+'        try {',
+'          setOptions(await fetchUsers(q));',
+'        } finally {',
+'          setLoading(false);',
+'        }',
+'      }, 300),',
+'    [],',
+'  );',
+'',
+'  useEffect(() => { search(input); }, [input, search]);',
+'',
+'  return (',
+'    <Box sx={{ width: 320 }}>',
+'      <Autocomplete',
+'        label="Usuario"',
+'        placeholder="Buscar usuario..."',
+'        options={options}',
+'        value={value}',
+'        onChange={(v) => setValue(v as string | null)}',
+'        inputValue={input}',
+'        onInputChange={(_, v) => setInput(v)}',
+'        loading={loading}',
+'        // Desactiva el filtro cliente: el servicio ya filtra.',
+'        filterOptions={(x) => x}',
+'      />',
+'    </Box>',
+'  );',
+'};',
+].join('\n');