Instalación

npm / pnpm / yarn

pnpm add glubox

Peer dependencies

pnpm add react react-dom

React 18+ es requerido.

Estilos

Importa el CSS en el entry point de tu aplicación:

import 'glubox/style.css';

Sin este import los componentes no tendrán layout ni tokens visuales.

Temas globales (opcional)

import 'glubox/themes/default.css';   // uno solo
// import 'glubox/themes/index.css'; // los tres temas

document.documentElement.setAttribute('data-theme', 'default');
document.documentElement.setAttribute('data-mode', 'dark');

Archivo	Paleta pastel
glubox/themes/default.css	Periwinkle (indigo suave)
glubox/themes/modern.css	Sage (verde suave)
glubox/themes/enterprise.css	Powder blue (azul suave)

Guía completa: Temas y apariencia.

Label outlined en cards

Si usas labelPosition="outlined" sobre un panel con fondo distinto al de la página:

.mi-panel {
  --glb-field-canvas: var(--glb-surface);
}

Iconos del menú

gluBox no incluye Lucide, Iconify ni otras librerías de iconos. Los nombres vienen de tu API ("receipt", "settings", …) y los resuelves con la prop renderIcon.

Los iconos de UI del sidebar (chevron, contraer/expandir) ya vienen integrados.

Con Lucide (recomendado)

pnpm add lucide-react

import { Circle, Receipt, Settings, type LucideIcon } from 'lucide-react';
import type { IconResolver } from 'glubox';

const iconRegistry: Record<string, LucideIcon> = {
  receipt: Receipt,
  settings: Settings,
};

export const renderMenuIcon: IconResolver = (name, className) => {
  const Icon = iconRegistry[name] ?? Circle;
  return <Icon className={className} aria-hidden />;
};

<Sidebar menu={menu} userPermissions={permissions} renderIcon={renderMenuIcon} />

Tamaño de iconos

El Sidebar aplica la clase sidebar__icon. No es necesario pasar size en Lucide; el CSS controla el tamaño en modo expandido y colapsado.

Nombres resueltos internamente (no registrar en tu renderIcon):

• chevron-down
• panel-left-close
• panel-left-open

Uso básico

import { useState } from 'react';
import { Sidebar } from 'glubox';
import type { MenuConfig } from 'glubox';
import 'glubox/style.css';

const menu: MenuConfig = {
  items: [
    {
      id: 'home',
      label: 'Inicio',
      icon: 'layout-dashboard',
      path: '/',
      permissions: ['dashboard:read'],
    },
  ],
};

export function AppShell() {
  const [collapsed, setCollapsed] = useState(false);

  return (
    <Sidebar
      menu={menu}
      userPermissions={['dashboard:read']}
      collapsed={collapsed}
      onCollapsedChange={setCollapsed}
      renderIcon={renderMenuIcon}
      theme="dark"
    />
  );
}

Con router (React Router)

import { useLocation, useNavigate } from 'react-router-dom';

const navigate = useNavigate();
const { pathname } = useLocation();

<Sidebar
  menu={menu}
  userPermissions={permissions}
  activePath={pathname}
  onNavigate={navigate}
  renderIcon={renderMenuIcon}
/>

Guía completa: Integración con routing.

TypeScript

Tipos y utilidades exportados:

import {
  Sidebar,
  Button,
  Select,
  TextBox,
  DateBox,
  RangeDateBox,
  OptionGroup,
  CheckButton,
  Popup,
  ToastProvider,
  useToast,
  sidebarThemes,
  buttonThemes,
  selectThemes,
  textBoxThemes,
  dateBoxThemes,
  rangeDateBoxThemes,
  optionGroupThemes,
  checkButtonThemes,
  popupThemes,
  toastThemes,
  hasPermission,
  filterVisibleMenu,
} from 'glubox';

import type {
  SidebarProps,
  MenuConfig,
  ButtonProps,
  SelectProps,
  TextBoxProps,
  DateBoxProps,
  RangeDateBoxProps,
  OptionGroupProps,
  CheckButtonProps,
  PopupProps,
  ShowToastOptions,
  Permission,
  IconResolver,
  // Handlers de eventos (tipado de callbacks)
  SelectOnChangeHandler,
  PopupOnCloseHandler,
  ToastShowHandler,
  OptionalEventHandler,
  EventHandlerPayload,
} from 'glubox';

• hasPermission(userPermissions, required?) — regla OR para guards de ruta.
• filterVisibleMenu(menu, userPermissions) — misma lógica que aplica el Sidebar internamente.
• Tipos *OnChangeHandler, *OnCloseHandler, etc. — ver Tipos de eventos.

Siguiente paso

• Tipos de eventos
• Formularios
• Overlays (Popup / Toast)
• Esquema del menú para tu API
• Referencia completa del Sidebar