flysoft-react-ui 1.3.2 → 1.4.0

package/AI_CONTEXT.md

@@ -1,1574 +1,1575 @@
-# Flysoft React UI - AI Context & Documentation
-
-This document serves as the source of truth for AI models (Gemini, Claude, GPT, etc.) when generating code that consumes the `flysoft-react-ui` library.
-
-## Library Philosophy
-
-`flysoft-react-ui` is a React component library built with TypeScript. It emphasizes a consistent look and feel, ease of use, and "premium" aesthetics out of the box. All components use CSS variables for theming and FontAwesome 5 (light/outlined style) for icons.
-
-## Critical Rules for AI
-
-1. **Top-Level Imports Only**: Always import from `'flysoft-react-ui'`.
-   - CORRECT: `import { Button, Card } from 'flysoft-react-ui';`
-   - INCORRECT: `import { Button } from 'flysoft-react-ui/components/Button';`
-2. **TypeScript First**: Use the exported types (e.g., `ButtonProps`, `DataTableColumn<T>`) to ensure type safety.
-3. **Style Import at App Root Only**: Add `import 'flysoft-react-ui/styles';` once at the app root. Never import CSS in individual components.
-4. **Do Not Use Docs Internals**: Never import or reference anything from `docs/*` or `src/docs/*`.
-5. **FontAwesome 5 Only**: Use `fa-*` icon classes. Components normalize to light style (`fal`) automatically. Never use other icon libraries.
-6. **Theme CSS Variables**: Use `var(--color-*)`, `var(--shadow-*)`, `var(--radius-*)`, `var(--font-*)` for custom styling. Never hardcode colors.
-
----
-
-## Form Controls
-
-### Button
-
-Customizable button with variants, colors, icons, and ripple effect.
-
-```typescript
-interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  variant?: "primary" | "outline" | "ghost";           // default: "primary"
-  size?: "sm" | "md" | "lg";                           // default: "md"
-  color?: "primary" | "secondary" | "success" | "warning" | "danger" | "info"; // default: "primary"
-  bg?: string;                   // Custom background color (hex, rgb, rgba, hsl, or color name)
-  textColor?: string;            // Custom text color
-  icon?: string;                 // FontAwesome icon class (e.g. "fa-save")
-  iconPosition?: "left" | "right";  // default: "left"
-  loading?: boolean;             // Shows spinner, disables button. default: false
-  children?: React.ReactNode;
-}
-```
-
-```tsx
-<Button variant="primary" icon="fa-save" loading={isLoading} onClick={handleSave}>
-  Guardar
-</Button>
-<Button variant="outline" color="danger" icon="fa-trash">Eliminar</Button>
-<Button variant="ghost" size="sm">Cancelar</Button>
-<Button bg="#8b5cf6" textColor="#fff">Custom Color</Button>
-```
-
-### LinkButton
-
-Anchor-styled button that uses React Router `<Link>` for internal routes and `<a>` for external URLs.
-
-```typescript
-interface LinkButtonProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
-  to: string;                    // Route or URL (required)
-  target?: string;
-  variant?: "primary" | "outline" | "ghost";           // default: "primary"
-  size?: "sm" | "md" | "lg";                           // default: "md"
-  color?: "primary" | "secondary" | "success" | "warning" | "danger" | "info";
-  bg?: string;
-  textColor?: string;
-  icon?: string;
-  iconPosition?: "left" | "right";  // default: "left"
-  children?: React.ReactNode;
-}
-```
-
-```tsx
-<LinkButton to="/users" icon="fa-users">Ver Usuarios</LinkButton>
-<LinkButton to="https://example.com" target="_blank">Sitio Externo</LinkButton>
-```
-
-### Input
-
-Text input with labels, icons, error states, and ref forwarding.
-
-```typescript
-interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> {
-  label?: string;                // Label text above input
-  error?: string;                // Error message below input
-  icon?: string;                 // FontAwesome icon class
-  iconPosition?: "left" | "right";  // default: "left"
-  size?: "sm" | "md" | "lg";        // default: "md"
-  children?: React.ReactNode;
-  onIconClick?: (event: React.MouseEvent<HTMLElement>) => void;  // Makes icon clickable
-  readOnly?: boolean;            // Read-only without disabled appearance
-}
-```
-
-```tsx
-<Input label="Email" type="email" icon="fa-envelope" placeholder="usuario@email.com" />
-<Input label="Búsqueda" icon="fa-search" iconPosition="right" onIconClick={handleSearch} />
-<Input label="Nombre" error="Campo requerido" />
-```
-
-### AutocompleteInput
-
-Searchable dropdown with single and multiple selection support.
-
-```typescript
-interface AutocompleteOption {
-  label: string;
-  value: string;
-  description?: string | number;
-  icon?: string;
-}
-
-interface AutocompleteInputProps<T = AutocompleteOption, K = string>
-  extends Omit<InputProps, "onChange" | "value" | "ref"> {
-  options: T[];                  // Options array (required)
-  value?: string | string[];     // String for single, array for multiple
-  onChange?: ((value: string | string[]) => void) | React.ChangeEventHandler<HTMLInputElement>;
-  onSelectOption?: (option: T, value: K) => void;
-  noResultsText?: string;       // default: "Sin resultados"
-  getOptionLabel?: (item: T) => string;
-  getOptionValue?: (item: T) => K;
-  getOptionDescription?: (item: T) => string | number | undefined;
-  renderOption?: (item: T) => React.ReactNode;
-  readOnly?: boolean;
-  multiple?: boolean;            // Multi-select with checkboxes. default: false
-}
-```
-
-```tsx
-// Single selection
-<AutocompleteInput
-  label="País"
-  options={[{ label: "Argentina", value: "AR" }, { label: "Brasil", value: "BR" }]}
-  value={selectedCountry}
-  onChange={setSelectedCountry}
-/>
-
-// Multiple selection
-<AutocompleteInput
-  label="Categorías"
-  options={categories}
-  multiple
-  value={selectedCategories}
-  onChange={setSelectedCategories}
-/>
-
-// Custom objects
-<AutocompleteInput<User, number>
-  label="Usuario"
-  options={users}
-  getOptionLabel={(u) => u.fullName}
-  getOptionValue={(u) => u.id}
-  getOptionDescription={(u) => u.email}
-/>
-```
-
-### SearchSelectInput
-
-Opens a dialog modal for selecting from async search results. Ideal for large datasets.
-
-```typescript
-interface SearchSelectOption {
-  label: string;
-  value?: string;
-  description?: string | number;
-  icon?: string;
-}
-
-interface SearchSelectInputProps<T = SearchSelectOption, K = string>
-  extends Omit<InputProps, "onChange" | "value" | "ref"> {
-  value?: T | K | string;
-  onChange?: ((value: T | K) => void) | React.ChangeEventHandler<HTMLInputElement>;
-  onSearchPromiseFn: (text: string) => Promise<Array<T> | PaginationInterface<T>>;  // required
-  onSingleSearchPromiseFn: (value: K) => Promise<T | undefined>;  // required
-  onSelectOption?: (option: T, value: K) => void;
-  dialogTitle?: string;          // default: "Seleccione una opción"
-  icon?: string;                 // default: "fa-search"
-  iconPosition?: "left" | "right";  // default: "right"
-  noResultsText?: string;       // default: "Sin resultados"
-  getOptionLabel?: (item: T) => string;
-  getOptionValue?: (item: T) => K;
-  getOptionDescription?: (item: T) => string | number | undefined;
-  renderOption?: (item: T) => React.ReactNode;
-  readOnly?: boolean;
-}
-```
-
-```tsx
-<SearchSelectInput<Product, number>
-  label="Producto"
-  onSearchPromiseFn={(text) => apiClient.get({ url: `/api/products?q=${text}` })}
-  onSingleSearchPromiseFn={(id) => apiClient.get({ url: `/api/products/${id}` })}
-  getOptionLabel={(p) => p.name}
-  getOptionValue={(p) => p.id}
-  getOptionDescription={(p) => `$${p.price}`}
-  onChange={(value) => setProductId(value)}
-/>
-```
-
-### DatePicker
-
-Standalone calendar component for date selection.
-
-```typescript
-interface DatePickerProps {
-  value?: Dayjs | null;
-  onChange?: (date: Dayjs) => void;
-  initialViewDate?: Dayjs;       // Initial month/year when value is null
-  startWeekOn?: "monday" | "sunday";  // default: "sunday"
-  className?: string;
-}
-```
-
-### DateInput
-
-Input field with integrated DatePicker dropdown. Accepts manual text and Dayjs objects.
-
-```typescript
-type DateInputFormat = "dd/mm/yyyy" | "mm/dd/yyyy";
-
-interface DateInputProps extends Omit<InputProps, "type" | "value" | "onChange" | "ref"> {
-  value?: Dayjs | null | string;
-  onChange?: ((date: Dayjs | null) => void) | React.ChangeEventHandler<HTMLInputElement>;
-  format?: DateInputFormat;      // default: "dd/mm/yyyy"
-  datePickerProps?: Omit<DatePickerProps, "value" | "onChange">;
-  readOnly?: boolean;
-}
-```
-
-```tsx
-<DateInput label="Fecha de nacimiento" value={birthDate} onChange={setBirthDate} />
-<DateInput label="Start Date" format="mm/dd/yyyy" />
-```
-
-### Checkbox
-
-Boolean checkbox with label and error support. Ref forwarding supported.
-
-```typescript
-interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
-  label?: string;
-  labelPosition?: "left" | "right";  // default: "right"
-  error?: string;
-  size?: "sm" | "md" | "lg";        // default: "md"
-  readOnly?: boolean;
-}
-```
-
-```tsx
-<Checkbox label="Acepto los términos" checked={accepted} onChange={handleChange} />
-<Checkbox label="Activo" size="lg" readOnly />
-```
-
-### RadioButtonGroup
-
-Single selection from a group of radio options.
-
-```typescript
-interface RadioOption {
-  label: string;
-  value: string | number;
-  disabled?: boolean;
-}
-
-interface RadioButtonGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "children"> {
-  options: RadioOption[];        // required
-  value?: string | number;
-  onChange?: ((value: string | number) => void) | React.ChangeEventHandler<HTMLInputElement>;
-  labelPosition?: "left" | "right";  // default: "right"
-  size?: "sm" | "md" | "lg";        // default: "md"
-  error?: string;
-  direction?: "vertical" | "horizontal";  // default: "vertical"
-  gap?: "sm" | "md" | "lg";         // default: "md"
-  name?: string;
-  disabled?: boolean;
-  onBlur?: (() => void) | React.FocusEventHandler<HTMLInputElement>;
-  readOnly?: boolean;
-}
-```
-
-```tsx
-<RadioButtonGroup
-  options={[
-    { label: "Masculino", value: "M" },
-    { label: "Femenino", value: "F" },
-    { label: "Otro", value: "O" },
-  ]}
-  value={gender}
-  onChange={setGender}
-  direction="horizontal"
-/>
-```
-
-### CurrencyInput
-
-Numeric input with currency formatting (Argentine locale: 1.234,56). Ref forwarding supported.
-
-```typescript
-interface CurrencyInputProps extends Omit<InputProps, "value" | "onChange" | "type"> {
-  value?: number | null;
-  onChange?: (value: any) => void;  // Receives parsed numeric value
-}
-```
-
-```tsx
-<CurrencyInput label="Monto" value={amount} onChange={setAmount} icon="fa-dollar-sign" />
-```
-
-### Pagination
-
-URL-based pagination controls using react-router-dom's `useSearchParams`.
-
-```typescript
-interface PaginationProps {
-  fieldName?: string;            // URL param name. default: "pagina"
-  page?: number;                 // default: 1
-  pages?: number;                // default: 1
-  total?: number;                // default: 0
-  isLoading?: boolean;           // default: false
-}
-```
-
-```tsx
-<Pagination page={currentPage} pages={totalPages} total={totalItems} />
-```
-
----
-
-## Layout Components
-
-### Card
-
-Generic container with header, content, footer, and variants.
-
-```typescript
-interface CardProps {
-  title?: string | React.ReactNode;
-  subtitle?: string | React.ReactNode;
-  children?: React.ReactNode;
-  className?: string;
-  headerActions?: React.ReactNode;
-  footer?: React.ReactNode;
-  variant?: "default" | "elevated" | "outlined";  // default: "default"
-  alwaysDisplayHeaderActions?: boolean;  // default: false (shows on hover on lg+)
-  headerClassName?: string;
-  contentClassName?: string;
-  footerClassName?: string;
-  /**
-   * Override local de densidad: cuando es true, fuerza el preset "compact" en
-   * las variables --flysoft-density-* dentro de esta Card y sus descendientes
-   * (paddings, gaps, tipografía). No depende de la densidad global.
-   */
-  compact?: boolean;             // default: false
-}
-```
-
-```tsx
-<Card title="Usuarios" headerActions={<Button size="sm" icon="fa-plus">Nuevo</Button>}>
-  <p>Contenido</p>
-</Card>
-<Card variant="elevated" compact footer={<Button variant="primary">Guardar</Button>}>
-  <Input label="Nombre" />
-</Card>
-// Card densa que afecta también a los DataField dentro
-<Card title="Datos personales" compact>
-  <Collection direction="row" wrap gap="md">
-    <DataField label="CUIL" value="20-17990271-1" size="sm" />
-    <DataField label="Edad" value={59} size="sm" />
-  </Collection>
-</Card>
-```
-
-### AppLayout
-
-Main application layout with responsive navbar and sidebar drawer.
-
-```typescript
-interface AppLayoutProps {
-  navbar?: NavbarInterface;
-  leftDrawer?: LeftDrawerInterface;
-  contentFooter?: React.ReactNode;
-  children: React.ReactNode;     // required
-  className?: string;
-  isLeftDrawerOpen?: boolean;                        // controlled mobile drawer state
-  onLeftDrawerOpenChange?: (isOpen: boolean) => void;
-}
-
-interface NavbarInterface {
-  navBarLeftNode?: React.ReactNode;
-  navBarRightNode?: React.ReactNode;
-  fullWidthNavbar?: boolean;     // Fixed full-width (true) or relative (false)
-  height?: string;               // default: "64px"
-  className?: string;
-}
-
-interface LeftDrawerInterface {
-  headerNode?: React.ReactNode;
-  contentNode?: React.ReactNode;
-  footerNode?: React.ReactNode;
-  className?: string;
-  width?: string;                // default: "256px"
-}
-```
-
-```tsx
-<AppLayout
-  navbar={{
-    navBarLeftNode: <h1>Mi App</h1>,
-    navBarRightNode: <Avatar text="Admin" />,
-    fullWidthNavbar: true,
-  }}
-  leftDrawer={{
-    headerNode: <h2>Menú</h2>,
-    contentNode: <nav>...</nav>,
-  }}
->
-  <main>Contenido</main>
-</AppLayout>
-```
-
-**Behaviors**: Navbar auto-hides/shows on scroll. Mobile drawer with overlay. Responsive breakpoints. The mobile drawer closes automatically when switching to desktop.
-
-**Closing the drawer from inside**: any component rendered inside `AppLayout` (drawer content, navbar nodes, footer or `children`) can control the drawer with `useLeftDrawer()`:
-
-```typescript
-interface LeftDrawerContextType {
-  isLeftDrawerOpen: boolean;
-  isLeftDrawerCollapsible: boolean;  // true on mobile/tablet with drawer content
-  openLeftDrawer: () => void;
-  closeLeftDrawer: () => void;
-  toggleLeftDrawer: () => void;
-}
-
-const useLeftDrawer: () => LeftDrawerContextType;          // throws outside AppLayout
-const useOptionalLeftDrawer: () => LeftDrawerContextType | undefined;  // returns undefined
-```
-
-```tsx
-// Menú lateral: cerrar el panel al navegar
-const AppMenu = () => {
-  const { closeLeftDrawer } = useLeftDrawer();
-  return (
-    <nav>
-      <LinkButton to="/inicio" onClick={closeLeftDrawer}>Inicio</LinkButton>
-      <LinkButton to="/clientes" onClick={closeLeftDrawer}>Clientes</LinkButton>
-    </nav>
-  );
-};
-```
-
-Calling `closeLeftDrawer()` on desktop is safe — the drawer is always visible there, so nothing changes.
-
-### Collection
-
-Flex container for rendering lists of items, density-aware.
-
-```typescript
-interface CollectionProps {
-  children: React.ReactNode;     // required
-  /**
-   * Presets semánticos ligados a densidad o cualquier valor CSS arbitrario.
-   * "tight" = 0, "sm"/"md"/"lg" leen --flysoft-density-gap-*.
-   */
-  gap?: "tight" | "sm" | "md" | "lg" | string;  // default: "md"
-  direction?: "column" | "row";  // default: "column"
-  wrap?: boolean;                // default: false
-  className?: string;
-  /**
-   * Override local: redefine --flysoft-density-* para esta Collection y
-   * descendientes. Útil para tener una sección densa dentro de un layout cómodo.
-   */
-  density?: "comfortable" | "compact" | "dense";
-}
-```
-
-```tsx
-// Default
-<Collection><DataField label="A" value="1" /><DataField label="B" value="2" /></Collection>
-
-// Horizontal con wrap, gap chico
-<Collection direction="row" wrap gap="sm">
-  <Badge>Activo</Badge><Badge color="info">Verificado</Badge>
-</Collection>
-
-// Sección densa dentro de Card comfortable
-<Collection density="dense">
-  <DataField label="CUIL" value="..." />
-  <DataField label="Edad" value={59} />
-</Collection>
-```
-
-### DataField
-
-Label + value pair display for detail views. Density-aware.
-
-```typescript
-interface DataFieldProps {
-  label?: string;
-  value?: string | number | React.ReactNode;
-  inline?: boolean;              // Horizontal layout. default: false
-  align?: "left" | "right" | "center";  // default: "left"
-  title?: string;                // HTML title tooltip
-  link?: string;                 // Opens URL in new tab
-  className?: string;
-  labelClassName?: string;
-  /**
-   * Override local de tipografía:
-   * - "md" (default): label = font-sm, value = font-base.
-   * - "sm": baja un nivel — label = font-xs, value = font-sm.
-   */
-  size?: "sm" | "md";
-  /** Separación entre label y value en modo stack. "tight" = 0. */
-  gap?: "tight" | "sm" | "md";  // default: "md"
-  /** Oculta el ":" después del label en modo inline. */
-  hideColon?: boolean;          // default: false
-}
-```
-
-```tsx
-<DataField label="Nombre" value="Juan Pérez" />
-<DataField label="Email" value="juan@email.com" link="mailto:juan@email.com" inline />
-// Modo compacto para listas densas
-<DataField label="CUIL" value="20-17990271-1" size="sm" />
-<DataField label="Estado" value="Activo" inline hideColon />
-```
-
-### TabsGroup / TabPanel
-
-Tabbed interfaces with optional URL persistence.
-
-```typescript
-interface Tab {
-  id: string | number;
-  label: string;
-}
-
-interface TabsGroupProps {
-  children?: React.ReactNode;
-  tabs: Tab[];                   // required
-  paramName?: string;            // URL search param for persistence
-  headerNode?: React.ReactNode;  // Right-aligned header content
-  onChangeTab?: (selectedTab: string) => void;
-}
-
-interface TabPanelProps {
-  children?: React.ReactNode;
-  tabId: string | number;        // Must match a Tab.id (required)
-}
-```
-
-```tsx
-<TabsGroup tabs={[{ id: "info", label: "Información" }, { id: "history", label: "Historial" }]}>
-  <TabPanel tabId="info">
-    <p>Información del usuario</p>
-  </TabPanel>
-  <TabPanel tabId="history">
-    <p>Historial de actividad</p>
-  </TabPanel>
-</TabsGroup>
-```
-
-### DataTable\<T\>
-
-High-performance data table with sorting, formatting, actions, and skeleton loading.
-
-```typescript
-interface DataTableColumn<T> {
-  align?: "left" | "right" | "center";  // Auto-set for date/currency/numeric
-  width?: string;
-  header?: string | React.ReactNode;
-  footer?: string | React.ReactNode;
-  value?: string | number | ((row: T) => string | React.ReactNode);
-  tooltip?: (row: T) => string | React.ReactNode;
-  type?: "text" | "numeric" | "currency" | "date";
-  actions?: (row: T) => Array<React.ReactNode>;
-  headerActions?: () => Array<React.ReactNode>;
-}
-
-interface DataTableProps<T> {
-  columns: DataTableColumn<T>[]; // required
-  rows: T[];                     // required
-  className?: string;
-  maxRows?: number;              // Enables sticky header with scroll
-  locale?: string;               // default: "es-AR"
-  isLoading?: boolean;           // Shows skeleton rows. default: false
-  loadingRows?: number;          // default: 5
-  rowClassName?: (row: T) => string;
-  headerClassName?: string;
-  footerClassName?: string;
-  headerCellClassName?: string;
-  footerCellClassName?: string;
-  cellClassName?: string | ((row: T, column: DataTableColumn<T>) => string);
-  /**
-   * Override local de densidad: cuando es true, fuerza el preset "compact" en
-   * las variables --flysoft-density-* dentro de esta DataTable (paddings,
-   * tipografía, altura de fila). También se propaga a los DropdownMenu de
-   * acciones. Independiente de la densidad global del ThemeProvider.
-   */
-  compact?: boolean;             // default: false
-}
-```
-
-```tsx
-interface User { id: number; name: string; salary: number; createdAt: string; }
-
-const columns: DataTableColumn<User>[] = [
-  { header: "ID", value: "id", width: "60px" },
-  { header: "Nombre", value: (row) => row.name },
-  { header: "Salario", value: "salary", type: "currency" },
-  { header: "Fecha", value: "createdAt", type: "date" },
-  {
-    header: "Acciones",
-    actions: (row) => [
-      <Button key="edit" variant="ghost" size="sm" icon="fa-edit" onClick={() => edit(row)}>Editar</Button>,
-      <Button key="del" variant="ghost" size="sm" icon="fa-trash" color="danger" onClick={() => del(row)}>Eliminar</Button>,
-    ],
-  },
-];
-
-<DataTable<User> columns={columns} rows={users} isLoading={loading} maxRows={10} />
-```
-
-**Type formatting**: `currency` → thousands separator, no symbol. `numeric` → locale formatting. `date` → DD/MM/YYYY.
-
-### Accordion
-
-Collapsible content section with smooth animation.
-
-```typescript
-interface AccordionProps {
-  title: string | React.ReactNode;  // required
-  children: React.ReactNode;        // required
-  icon?: string;                 // FontAwesome icon
-  rightNode?: React.ReactNode;
-  defaultOpen?: boolean;         // default: false
-  className?: string;
-  headerClassName?: string;      // clases para el header (botón)
-  contentClassName?: string;     // clases para el contenedor del contenido
-  variant?: "default" | "elevated" | "outlined";  // default: "default"
-  onToggle?: (isOpen: boolean) => void;
-}
-```
-
-```tsx
-<Accordion title="Detalles" icon="fa-info-circle" defaultOpen>
-  <p>Contenido colapsable</p>
-</Accordion>
-```
-
-### Menu
-
-Simple menu list for displaying options.
-
-```typescript
-interface MenuProps<T = { label: string }> {
-  options: T[];                  // required
-  onOptionSelected: (item: T) => void;  // required
-  getOptionLabel?: (item: T) => string;
-  renderOption?: (item: T) => React.ReactNode;
-  className?: string;
-  style?: React.CSSProperties;
-  itemClassName?: string;
-}
-```
-
-### DropdownMenu
-
-Portal-based dropdown menu triggered by a button. Auto-positions above/below.
-
-```typescript
-interface DropdownMenuProps<T = { label: string }> {
-  options: T[];                  // required
-  onOptionSelected: (item: T) => void;  // required
-  renderNode?: React.ReactNode;  // Custom trigger (default: ellipsis icon button)
-  getOptionLabel?: (item: T) => string;
-  renderOption?: (item: T) => React.ReactNode;
-  replaceOnSingleOption?: boolean;  // Show single option inline. default: false
-  openOnHover?: boolean;         // default: false
-}
-```
-
-```tsx
-<DropdownMenu
-  options={[{ label: "Editar" }, { label: "Eliminar" }]}
-  onOptionSelected={(item) => handleAction(item.label)}
-  renderNode={<Button variant="ghost" icon="fa-cog" size="sm" />}
-/>
-```
-
-### DropdownPanel
-
-Portal-based dropdown that renders arbitrary content (not a list).
-
-```typescript
-interface DropdownPanelProps {
-  renderNode?: React.ReactNode;  // Custom trigger (default: ellipsis icon button)
-  children: React.ReactNode;     // required
-  openOnHover?: boolean;         // default: false
-}
-```
-
-### Filter
-
-Versatile filtering component with multiple filter types and optional URL persistence.
-
-```typescript
-// Discriminated union by filterType
-type FilterProps =
-  | TextFilterProps        // filterType?: "text" (default)
-  | NumberFilterProps      // filterType: "number" (+ min?, max?)
-  | DateFilterProps        // filterType: "date"
-  | AutocompleteFilterProps // filterType: "autocomplete" (+ options, multiple?)
-  | SearchFilterProps      // filterType: "search"
-  | SearchSelectFilterProps // filterType: "searchSelect" (+ onSearchPromiseFn, onSingleSearchPromiseFn)
-
-// Common props for all filter types:
-interface BaseFilterProps {
-  paramName?: string;            // URL search param for persistence
-  label?: string;
-  staticOptions?: Array<{ text: string; value: string }>;
-  inputWidth?: string;
-  value?: string;                // Controlled value
-  onChange?: (value: string | undefined) => void;
-  hideEmpty?: boolean;           // default: false
-  disabled?: boolean;            // default: false
-  compact?: boolean;             // default: false — fuerza densidad compacta local
-  bgColor?: string;              // Fondo del badge e input (no del panel flotante). Ej: "#f5f5f5" o "var(--color-bg-secondary)"
-}
-```
-
-```tsx
-<Filter filterType="text" paramName="nombre" label="Nombre" />
-// Fondo personalizado cuando el filtro va sobre una Card blanca:
-<Filter filterType="search" paramName="q" label="Buscar" bgColor="var(--color-bg-secondary)" />
-<Filter filterType="number" paramName="edad" label="Edad" min={0} max={120} />
-<Filter filterType="date" paramName="fecha" label="Fecha" />
-<Filter
-  filterType="autocomplete"
-  paramName="estado"
-  label="Estado"
-  options={[{ label: "Activo", value: "1" }, { label: "Inactivo", value: "0" }]}
-/>
-<Filter
-  filterType="searchSelect"
-  paramName="cliente"
-  label="Cliente"
-  onSearchPromiseFn={(text) => apiClient.get({ url: `/api/clients?q=${text}` })}
-  onSingleSearchPromiseFn={(id) => apiClient.get({ url: `/api/clients/${id}` })}
-/>
-```
-
----
-
-## Utility Components
-
-### Badge
-
-Status/category label with variants and custom colors.
-
-```typescript
-interface BadgeProps {
-  children: React.ReactNode;     // required
-  variant?: "primary" | "secondary" | "success" | "warning" | "danger" | "info";  // default: "primary"
-  size?: "sm" | "md" | "lg";    // default: "md"
-  rounded?: boolean;             // Full border radius. default: false
-  className?: string;
-  icon?: string;
-  iconPosition?: "left" | "right";  // default: "left"
-  iconLabel?: string;            // aria-label for icon
-  bg?: string;                   // Custom background color
-  textColor?: string;            // Custom text color
-  onClick?: (event: React.MouseEvent<HTMLElement>) => void;
-}
-```
-
-```tsx
-<Badge variant="success" icon="fa-check">Activo</Badge>
-<Badge variant="danger" rounded>3</Badge>
-<Badge bg="#8b5cf6" textColor="#fff">Custom</Badge>
-```
-
-### Avatar
-
-User profile display with initials fallback when image fails.
-
-```typescript
-interface AvatarProps {
-  text: string;                  // Name for initials extraction (required)
-  image?: string;                // Image URL
-  bgColor?: string;              // default: "#4b5563"
-  textColor?: string;            // default: "#ffffff"
-  size?: "sm" | "md" | "lg";    // default: "md" (sm=32px, md=40px, lg=48px)
-  className?: string;
-}
-```
-
-```tsx
-<Avatar text="Juan Pérez" image="/avatars/juan.jpg" />
-<Avatar text="Admin User" bgColor="#3b82f6" size="lg" />
-```
-
-### RoadMap
-
-Progress/stage visualization with connected circles and gradient lines.
-
-```typescript
-interface RoadMapStage {
-  name: string;                  // required
-  description?: string;
-  icon?: string;
-  disabled?: boolean;            // Grayed out at 50% opacity
-  variant?: "primary" | "secondary" | "success" | "warning" | "danger" | "info";
-  bg?: string;                   // Custom color (overrides variant)
-}
-
-interface RoadMapProps {
-  stages: RoadMapStage[];        // required
-  className?: string;
-}
-```
-
-```tsx
-<RoadMap stages={[
-  { name: "Creado", icon: "fa-plus", variant: "info" },
-  { name: "En Proceso", icon: "fa-cog", variant: "warning" },
-  { name: "Completado", icon: "fa-check", variant: "success" },
-  { name: "Archivado", icon: "fa-archive", disabled: true },
-]} />
-```
-
-### Dialog
-
-Modal window with overlay, escape-to-close, and scroll lock.
-
-```typescript
-interface DialogProps {
-  isOpen: boolean;               // required
-  title: React.ReactNode;       // required
-  children: React.ReactNode;    // required
-  footer?: React.ReactNode;
-  onClose?: () => void;
-  closeOnOverlayClick?: boolean; // default: false
-  /**
-   * Override local de densidad: cuando es true, fuerza el preset "compact" en
-   * --flysoft-density-* dentro del Dialog (paddings header/body/footer,
-   * tamaño del título, gaps). Independiente de la densidad global.
-   */
-  compact?: boolean;             // default: false
-  bodyWidth?: string | number;   // Custom dialog width (e.g. "800px", "80vw", 600). Default: max-w-lg
-}
-```
-
-```tsx
-<Dialog isOpen={showDialog} title="Confirmar" onClose={() => setShowDialog(false)}
-  footer={
-    <>
-      <Button variant="ghost" onClick={() => setShowDialog(false)}>Cancelar</Button>
-      <Button variant="primary" color="danger" onClick={handleDelete}>Eliminar</Button>
-    </>
-  }
->
-  <p>¿Está seguro que desea eliminar este registro?</p>
-</Dialog>
-```
-
-### Loader
-
-Loading indicator with progress bar. Can wrap content with overlay.
-
-```typescript
-interface LoaderProps {
-  isLoading?: boolean;           // default: false
-  text?: string;                 // Text below progress bar
-  children?: React.ReactNode;
-  keepContentWhileLoading?: boolean;  // Show content faded at 50% opacity
-  contentLoadingNode?: React.ReactNode;  // Custom loading content
-  overlayClassName?: string;     // default: "bg-black/50 backdrop-blur-sm"
-}
-```
-
-```tsx
-<Loader isLoading={loading} text="Cargando datos...">
-  <DataTable ... />
-</Loader>
-<Loader isLoading={loading} keepContentWhileLoading>
-  <Card>...</Card>
-</Loader>
-```
-
-### FiltersDialog
-
-Dialog that groups multiple Filter components. Syncs values from/to URL search params.
-
-```typescript
-interface FilterConfig {
-  filterType: "text" | "number" | "date" | "autocomplete";
-  paramName: string;             // required
-  label?: string;
-  staticOptions?: Array<{ text: string; value: string }>;
-  inputWidth?: string;
-  min?: number;                  // For number filters
-  max?: number;                  // For number filters
-  options?: any[];               // For autocomplete
-  getOptionLabel?: (item: any) => string;
-  getOptionValue?: (item: any) => any;
-  renderOption?: (item: any) => React.ReactNode;
-  noResultsText?: string;
-}
-
-interface FiltersDialogProps {
-  filters: FilterConfig[];       // required
-}
-```
-
-```tsx
-<FiltersDialog filters={[
-  { filterType: "text", paramName: "nombre", label: "Nombre" },
-  { filterType: "number", paramName: "edad", label: "Edad", min: 0, max: 120 },
-  { filterType: "date", paramName: "fecha", label: "Fecha" },
-  { filterType: "autocomplete", paramName: "estado", label: "Estado",
-    options: [{ label: "Activo", value: "1" }, { label: "Inactivo", value: "0" }] },
-]} />
-```
-
-### Snackbar / SnackbarContainer
-
-Toast notification system. SnackbarContainer must be at the app root.
-
-```typescript
-interface SnackbarContainerProps {
-  position?: "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";  // default: "top-right"
-  maxSnackbars?: number;         // default: 5
-}
-
-// Usage via hook (not direct Snackbar component):
-const { showSnackbar } = useSnackbar();
-showSnackbar("Operación exitosa", "success");
-showSnackbar("Error al guardar", "danger", { duration: 5000, icon: "fa-exclamation" });
-```
-
-**Variants**: `"primary"` | `"secondary"` | `"success"` | `"warning"` | `"danger"` | `"info"`
-**Default icons**: success=fa-check-circle, danger=fa-times-circle, warning=fa-exclamation-triangle, info/primary/secondary=fa-info-circle
-
-### Skeleton
-
-Loading placeholder with pulse animation. Fully customizable via className.
-
-```typescript
-interface SkeletonProps {
-  className?: string;  // Tailwind classes to control width, height, shape
-}
-```
-
-```tsx
-<Skeleton className="h-4 w-3/4" />      {/* Text line */}
-<Skeleton className="h-10 w-full" />     {/* Input placeholder */}
-<Skeleton className="h-32 w-32 rounded-full" />  {/* Avatar placeholder */}
-```
-
-### ThemeSwitcher
-
-Self-contained theme toggle. No props. Displays available themes with switch buttons and current theme info.
-
-```tsx
-<ThemeSwitcher />
-```
-
----
-
-## Contexts & State Management
-
-### ThemeProvider / useTheme
-
-Manages application theme with CSS variable injection, presets, and localStorage persistence.
-
-```typescript
-type Density = "comfortable" | "compact" | "dense";
-
-// Provider props
-interface ThemeProviderProps {
-  children: ReactNode;
-  initialTheme?: string | Theme;       // default: "light"
-  storageKey?: string;                 // localStorage key. default: "flysoft-theme"
-  forceInitialTheme?: boolean;         // Ignore localStorage. default: false
-  onThemeChange?: (theme: Theme) => void;
-  density?: Density;                   // Global density. default: "comfortable"
-  densityStorageKey?: string;          // default: "flysoft-density"
-  forceInitialDensity?: boolean;       // default: false
-  onDensityChange?: (density: Density) => void;
-}
-
-// Hook return
-interface ThemeContextType {
-  theme: Theme;                   // Current theme object
-  setTheme: (theme: Theme | string) => void;  // Switch theme by name or object
-  updateTheme: (updates: Partial<Theme> | ((prev: Theme) => Theme)) => void;
-  currentThemeName: string;
-  availableThemes: string[];      // ["light", "dark", "blue", "green"]
-  resetToDefault: () => void;
-  isDark: boolean;
-  density: Density;
-  setDensity: (density: Density) => void;
-}
-```
-
-```tsx
-// App root - default density
-<ThemeProvider initialTheme="light">
-  <App />
-</ThemeProvider>
-
-// App root - data-heavy app (CRUD admin, dashboards)
-<ThemeProvider initialTheme="light" density="dense">
-  <App />
-</ThemeProvider>
-
-// Runtime toggle
-const { theme, setTheme, isDark, density, setDensity } = useTheme();
-<Button onClick={() => setTheme(isDark ? "light" : "dark")}>Toggle Theme</Button>
-<Button onClick={() => setDensity(density === "dense" ? "comfortable" : "dense")}>
-  Toggle Density
-</Button>
-```
-
-**Preset themes**: `lightTheme`, `darkTheme`, `blueTheme`, `greenTheme` (importable).
-**Density presets**: `comfortableDensity`, `compactDensity`, `denseDensity`, `densityPresets` (importable).
-
-**Density CSS variables** (inyectadas automáticamente según la densidad activa):
-`--flysoft-density-padding-x-{sm|md|lg}`, `--flysoft-density-padding-y-{sm|md|lg}`,
-`--flysoft-density-container-padding-{x|y}`,
-`--flysoft-density-gap-{sm|md|lg}`, `--flysoft-density-font-{xs|sm|base|lg|xl}`,
-`--flysoft-density-control-height-{sm|md|lg}`, `--flysoft-density-datatable-row`,
-`--flysoft-density-datatable-header`, `--flysoft-density-card-gap`.
-
-**Componentes que ya consumen densidad automáticamente** (sin necesidad de prop):
-Card, DataField, Collection, Button, LinkButton, Input, AutocompleteInput,
-SearchSelectInput, DateInput, CurrencyInput, DatePicker, DataTable, Dialog,
-Filter (incluye los paneles flotantes), FiltersDialog, Accordion, Menu,
-DropdownMenu, DropdownPanel, TabsGroup, Badge, Checkbox, RadioButtonGroup,
-Pagination, Avatar, RoadMap, Snackbar, Skeleton, Loader. **Toda la librería
-es density-aware.** El default `comfortable` preserva el aspecto previo de
-cada componente, así que los consumidores existentes no ven cambios visuales
-hasta que activan `density="compact"` o `density="dense"`.
-
-**Tipografía global**: dentro del wrapper `.flysoft-theme-reset` (cualquier
-ThemeProvider/AppLayoutProvider lo crea automáticamente), los headings y
-elementos de texto sin clase específica escalan con densidad:
-- `h1` = `font-xl × 1.5`, `h2` = `font-xl × 1.25`, `h3` = `font-xl`,
-  `h4` = `font-lg`, `h5` = `font-base`, `h6` = `font-sm`
-- `p` = `font-base`, `small` = `font-xs`
-- `span`/`div` heredan `font-base` del wrapper
-
-Las reglas son de baja specificity: cualquier `className` Tailwind (`text-lg`,
-`text-2xl`, etc.) o `style` inline las pisa.
-
-**Componentes con prop `compact` como override local de densidad** (fuerzan
-preset compact en `--flysoft-density-*` dentro de sí y descendientes,
-ignorando la densidad global): Card, DataTable, Dialog, Filter, Accordion,
-Menu, DropdownMenu, DropdownPanel, TabsGroup.
-
-**Override de fondo/estilos en form-controls vía `className`**: los form-controls
-(Input, CurrencyInput, DateInput, AutocompleteInput, SearchSelectInput, Button,
-LinkButton, Checkbox, RadioButtonGroup, DatePicker) combinan sus clases con
-`twMerge`, así que un `className` con clase en conflicto pisa la default de forma
-confiable. Para cambiar el fondo por defecto (`bg-[var(--color-bg-default)]`) —por
-ej. cuando el control va sobre una Card del mismo color— pasá un `bg-*`:
-`<Input className="bg-[var(--color-bg-secondary)]" />` o `<Input className="bg-[#f5f5f5]" />`.
-El `Filter` no toma `className` para esto; usa su prop `bgColor`.
-
-### AuthProvider / AuthContext
-
-Manages authentication with automatic token validation and refresh.
-
-```typescript
-interface AuthProviderProps {
-  children: React.ReactNode;
-  getToken: (username: string, password: string) => Promise<AuthTokenInterface>;  // required
-  getUserData: (auth: AuthTokenInterface) => Promise<AuthContextUserInterface>;   // required
-  refreshToken?: (auth: AuthTokenInterface) => Promise<AuthTokenInterface>;
-  removeToken?: (auth: AuthTokenInterface) => Promise<void>;
-  showLog?: boolean;             // default: false
-}
-
-interface AuthContextType {
-  user: AuthContextUserInterface | null;
-  login: (username: string, password: string) => Promise<void>;
-  logout: () => void;
-  isAuthenticated: boolean;
-  isLoading: boolean;
-}
-
-interface AuthContextUserInterface {
-  id?: number | string;
-  name?: string;
-  aditionalData?: any;
-  token?: AuthTokenInterface;
-}
-
-interface AuthTokenInterface {
-  accessToken?: string;
-  expires?: string;              // ISO 8601
-  tokenType?: string;
-  refreshToken?: string;
-  aditionalData?: any;
-}
-```
-
-```tsx
-<AuthProvider
-  getToken={async (user, pass) => {
-    const res = await apiClient.post({ url: "/auth/login", body: { user, pass } });
-    return res.token;
-  }}
-  getUserData={async (auth) => {
-    return await apiClient.get({ url: "/auth/me" });
-  }}
-  refreshToken={async (auth) => {
-    return await apiClient.post({ url: "/auth/refresh", body: { token: auth.refreshToken } });
-  }}
->
-  <App />
-</AuthProvider>
-
-// In components
-const { user, login, logout, isAuthenticated } = useContext(AuthContext);
-```
-
-**Behaviors**: Validates token on mount. Checks expiration every 60s. Auto-refreshes if `refreshToken` provided. Stores in localStorage as `"auth"`.
-
-### CrudProvider / useCrud\<T\>
-
-Generic CRUD context with automatic pagination, URL parameter sync, and snackbar notifications.
-
-```typescript
-interface CrudProviderProps<T> {
-  children: ReactNode;
-  getPromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
-  getItemPromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
-  postPromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
-  putPromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
-  deletePromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
-  urlParams?: Array<string>;     // URL params to watch. default: []
-  limit?: number;                // Items per page. default: 15
-  pageParam?: string;            // URL page param. default: "pagina"
-  singleItemId?: string | number;
-  extraData?: Record<string, any>;
-}
-
-interface CrudContextType<T> {
-  list: Array<T> | undefined;
-  item: T | undefined;
-  page: number;
-  pages: number;
-  total: number;
-  limit: number;
-  isLoading: boolean;
-  pagination: ReactNode;         // Pre-built Pagination component
-  params: Record<string, any>;
-  extraData?: Record<string, any>;
-  setExtraData: Dispatch<SetStateAction<Record<string, any> | undefined>>;
-  fetchItems: { execute: (params?: Record<string, any>) => Promise<void>; isLoading: boolean };
-  fetchItem: { execute: (params?: Record<string, any> | string | number) => Promise<T | undefined>; isLoading: boolean };
-  createItem: { execute: (item: T) => Promise<T | undefined | null>; isLoading: boolean };
-  updateItem: { execute: (item: T) => Promise<T | undefined | null>; isLoading: boolean };
-  deleteItem: { execute: (item: T) => Promise<void>; isLoading: boolean };
-}
-```
-
-```tsx
-<CrudProvider<User>
-  getPromise={(params) => apiClient.get({ url: "/api/users", params })}
-  getItemPromise={(id) => apiClient.get({ url: `/api/users/${id}` })}
-  postPromise={{ execute: (item) => apiClient.post({ url: "/api/users", body: item }), successMessage: "Usuario creado" }}
-  putPromise={{ execute: (item) => apiClient.put({ url: `/api/users/${item.id}`, body: item }), successMessage: "Usuario actualizado" }}
-  deletePromise={{ execute: (item) => apiClient.del({ url: `/api/users/${item.id}` }), successMessage: "Usuario eliminado" }}
-  urlParams={["nombre", "estado"]}
-  limit={20}
->
-  <UserList />
-</CrudProvider>
-
-// In child components
-const { list, isLoading, pagination, createItem, deleteItem } = useCrud<User>();
-```
-
-**Behaviors**: Auto-fetches when URL params change. Resets pagination on filter change. Shows snackbar on success/error.
-
-### SnackbarProvider / useSnackbar
-
-Manages toast notifications.
-
-```typescript
-interface SnackbarActionsType {
-  showSnackbar: (
-    message: string,
-    variant?: SnackbarVariant,
-    options?: { duration?: number; icon?: string; iconLabel?: string }
-  ) => void;
-  removeSnackbar: (id: string) => void;
-}
-```
-
-```tsx
-// App root
-<SnackbarProvider>
-  <SnackbarContainer position="bottom-right" maxSnackbars={3} />
-  <App />
-</SnackbarProvider>
-
-// In components
-const { showSnackbar } = useSnackbar();
-showSnackbar("Guardado exitosamente", "success");
-showSnackbar("Error de conexión", "danger", { duration: 5000 });
-```
-
-### AppLayoutProvider / useAppLayout
-
-Combines ThemeProvider + SnackbarProvider + AppLayout into a single provider.
-
-```typescript
-interface AppLayoutProviderProps {
-  children: ReactNode;
-  initialTheme?: string | Theme;
-  storageKey?: string;
-  forceInitialTheme?: boolean;
-  // Densidad global (propagada al ThemeProvider interno)
-  density?: "comfortable" | "compact" | "dense";  // default: "comfortable"
-  densityStorageKey?: string;                     // default: "flysoft-density"
-  forceInitialDensity?: boolean;
-  onDensityChange?: (density: "comfortable" | "compact" | "dense") => void;
-  initialNavbar?: NavbarInterface;
-  initialLeftDrawer?: LeftDrawerInterface;
-  initialContentFooter?: ReactNode;
-  className?: string;
-}
-
-interface AppLayoutContextType extends ThemeContextType {
-  navbar: NavbarInterface | undefined;
-  leftDrawer: LeftDrawerInterface | undefined;
-  contentFooter: ReactNode | undefined;
-  className: string;
-  setNavbar: Dispatch<SetStateAction<NavbarInterface | undefined>>;
-  setLeftDrawer: Dispatch<SetStateAction<LeftDrawerInterface | undefined>>;
-  setContentFooter: (node: ReactNode | undefined) => void;
-  setClassName: (className: string) => void;
-  setNavBarLeftNode: (node: ReactNode | undefined) => void;
-  setNavbarRightNode: (node: ReactNode | undefined) => void;
-  // Left drawer commands (same state as useLeftDrawer())
-  isLeftDrawerOpen: boolean;
-  openLeftDrawer: () => void;
-  closeLeftDrawer: () => void;
-  toggleLeftDrawer: () => void;
-}
-```
-
-```tsx
-<AppLayoutProvider
-  initialTheme="light"
-  density="dense"   // CRUDs / dashboards / pantallas con mucha info
-  initialNavbar={{ navBarLeftNode: <h1>Mi App</h1>, fullWidthNavbar: true }}
-  initialLeftDrawer={{ contentNode: <nav>...</nav> }}
->
-  <Routes />
-</AppLayoutProvider>
-
-// In pages - dynamically update layout
-const { setNavBarLeftNode, setNavbarRightNode } = useAppLayout();
-useEffect(() => {
-  setNavBarLeftNode(<h1>Dashboard</h1>);
-}, []);
-
-// Close the mobile drawer from anywhere inside the layout
-const { closeLeftDrawer } = useAppLayout();   // or useLeftDrawer()
-<LinkButton to="/clientes" onClick={closeLeftDrawer}>Clientes</LinkButton>
-```
-
----
-
-## Hooks
-
-### useThemeOverride
-
-Applies granular CSS variable overrides without changing the entire theme.
-
-```typescript
-function useThemeOverride(options?: {
-  scope?: "global" | "local";    // default: "global"
-  element?: HTMLElement | null;
-  prefix?: string;               // default: "flysoft"
-}): {
-  applyOverride: (overrides: Record<string, string | number>) => void;
-  revertOverride: (keys: string[]) => void;
-  revertAllOverrides: () => void;
-  getCSSVariable: (key: string) => string | null;
-  isOverrideApplied: (key: string) => boolean;
-  appliedOverridesCount: number;
-}
-```
-
-### useTemporaryOverride
-
-Applies CSS variable overrides that auto-revert after a duration.
-
-```typescript
-function useTemporaryOverride(
-  overrides: Record<string, string | number>,
-  duration?: number,             // default: 3000
-  options?: { scope?: "global" | "local"; element?: HTMLElement | null; prefix?: string }
-): { applyTemporaryOverride: () => Function }
-```
-
-### useBreakpoint
-
-Returns current viewport breakpoint and device type.
-
-```typescript
-type Breakpoint = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
-
-function useBreakpoint(): {
-  breakpoint: Breakpoint;
-  windowSize: { width: number; height: number };
-  isMobile: boolean;             // xs or sm
-  isTablet: boolean;             // md
-  isDesktop: boolean;            // lg, xl, or 2xl
-}
-```
-
-### useElementScroll
-
-Tracks scroll position and direction with requestAnimationFrame optimization.
-
-```typescript
-function useElementScroll(elementRef: React.RefObject<HTMLElement | null>): {
-  scrollY: number;
-  scrollDirection: "up" | "down" | null;
-}
-```
-
-### useAsyncRequest
-
-Manages async operations with loading state and snackbar notifications.
-
-```typescript
-interface AsyncRequestOptions {
-  successMessage?: string;
-  errorMessage?: string | ((error: any) => string);
-  successVariant?: SnackbarVariant;  // default: "success"
-  errorVariant?: SnackbarVariant;    // default: "danger"
-  onSuccess?: (data: any) => void;
-  onError?: (error: any) => void;
-  onFinally?: () => void;
-}
-
-function useAsyncRequest(options?: AsyncRequestOptions): {
-  isLoading: boolean;
-  execute: <T>(requestFn: () => Promise<T>) => Promise<T | undefined>;
-  setLoading: (loading: boolean) => void;
-}
-```
-
-```tsx
-const { execute, isLoading } = useAsyncRequest({
-  successMessage: "Guardado exitosamente",
-  errorMessage: (err) => getErrorMessage(err),
-});
-await execute(() => apiClient.post({ url: "/api/data", body: formData }));
-```
-
-### useEnum
-
-Converts TypeScript enums to arrays for form select options.
-
-```typescript
-function useEnum(baseEnum: any): {
-  getArray: () => Array<NameValueInterface<number>>;
-  getInstance: (id: number) => NameValueInterface<number> | undefined;
-}
-```
-
-### useGlobalThemeStyles
-
-Applies theme colors to `<body>` and `<html>` for full-page theming. No return value.
-
-```tsx
-function useGlobalThemeStyles(): void;
-```
-
----
-
-## Services
-
-### apiClient
-
-Singleton HTTP client (Axios-based) with automatic Bearer token injection.
-
-```typescript
-// Main methods
-apiClient.get<T>(options: { url: string; params?: Record<string, unknown>; headers?: Record<string, string> }): Promise<T>;
-apiClient.post<T>(options: { url: string; body?: unknown; headers?: Record<string, string> }): Promise<T>;
-apiClient.put<T>(options: { url: string; body?: unknown; headers?: Record<string, string> }): Promise<T>;
-apiClient.del<T>(options: { url: string; headers?: Record<string, string> }): Promise<T>;
-
-// File operations
-apiClient.getFile(options): Promise<{ data: Blob; headers: any }>;
-apiClient.getFileAsUrl(options): Promise<string>;
-apiClient.openFile(options): Promise<void>;
-apiClient.downloadFile(options): Promise<void>;
-apiClient.uploadFile<T>(options: { url: string; files: FileList | File[]; headers?: { paramName?: string } }): Promise<T>;
-
-// Token management
-setApiClientTokenProvider(provider?: () => string | undefined): void;
-clearApiClientTokenProvider(): void;
-
-// Create isolated instances
-createApiClient(config?: { baseURL?: string; timeout?: number; headers?: Record<string, string> }): ApiClientService;
-```
-
-```tsx
-// Setup token globally
-setApiClientTokenProvider(() => user?.token?.accessToken);
-
-// API calls
-const users = await apiClient.get<User[]>({ url: "/api/users", params: { page: 1 } });
-await apiClient.post({ url: "/api/users", body: { name: "Juan" } });
-await apiClient.downloadFile({ url: "/api/reports/pdf" });
-await apiClient.uploadFile({ url: "/api/upload", files: fileInput.files });
-```
-
----
-
-## Helpers
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `currencyFormat` | `(value: number) => string` | Formats as `"1.234,56"` (es-AR locale) |
-| `getErrorMessage` | `(error: any) => string` | Extracts message from AxiosError. Default: `"Ha ocurrido un error"` |
-| `getInitialLetters` | `(text: string) => string` | `"Juan Pérez"` → `"JP"` |
-| `getQueryString` | `(params: URLSearchParams, newParams: any) => string` | Merges params, returns `"?key=value"` |
-| `objectToQueryString` | `(source: any) => string` | Object to `"a=1&b=2"` (no leading `?`) |
-| `queryStringToObject` | `(params: string) => Record<string, string>` | `"a=1&b=2"` → `{a: "1", b: "2"}` |
-| `nameValueArrayToObject` | `<T>(arr: NameValueInterface<T>[]) => Record<string, T>` | Array of {name, value} to object |
-| `promiseMapper` | `<T, K>(promise, mapper) => Promise<K \| K[] \| PaginationInterface<K>>` | Maps promise results (arrays, pagination, single) |
-| `RegularExpressions` | Object | `.email`, `.dateString`, `.password(config)` regex patterns |
-
-## Interfaces
-
-```typescript
-interface NameValueInterface<T> {
-  name: string;
-  value: T;
-  extras?: any;
-}
-
-interface PaginationInterface<T> {
-  list: Array<T>;
-  limit: number;
-  page: number;
-  pages: number;
-  total: number;
-}
-```
-
----
-
-## Templates
-
-### LoginForm
-
-```typescript
-interface LoginFormProps {
-  onSubmit?: (data: { email: string; password: string }) => void;
-  loading?: boolean;
-  error?: string;
-  className?: string;
-}
-```
-
-### RegistrationForm
-
-```typescript
-interface RegistrationFormProps {
-  onSubmit?: (data: { firstName: string; lastName: string; email: string; password: string; confirmPassword: string }) => void;
-  loading?: boolean;
-  error?: string;
-  className?: string;
-}
-```
-
-### ContactForm
-
-```typescript
-interface ContactFormProps {
-  onSubmit?: (data: { name: string; email: string; subject: string; message: string }) => void;
-  loading?: boolean;
-  success?: boolean;
-  error?: string;
-  className?: string;
-}
-```
-
-### DashboardLayout
-
-```typescript
-interface DashboardStat {
-  title: string;
-  value: string | number;
-  change?: string;               // e.g. "+12%"
-  changeType?: "positive" | "negative" | "neutral";
-  icon?: string;
-}
-
-interface DashboardLayoutProps {
-  title: string;                 // required
-  subtitle?: string;
-  stats?: DashboardStat[];
-  actions?: React.ReactNode;
-  children: React.ReactNode;     // required
-  className?: string;
-}
-```
-
-### SidebarLayout
-
-```typescript
-interface MenuItem {
-  label: string;
-  icon: string;
-  href: string;
-  badge?: string | number;
-  children?: MenuItem[];
-}
-
-interface User {
-  name: string;
-  email?: string;
-  avatar?: string;
-}
-
-interface SidebarLayoutProps {
-  title: string;                 // required
-  menuItems: MenuItem[];         // required
-  user: User;                    // required
-  children: React.ReactNode;     // required
-  className?: string;
-  onLogout?: () => void;
-}
-```
-
-### FormPattern
-
-```typescript
-interface FormField {
-  name: string;
-  label: string;
-  type?: string;                 // default: "text"
-  placeholder?: string;
-  icon?: string;
-  required?: boolean;
-  validation?: (value: string) => string | undefined;
-  multiline?: boolean;
-  rows?: number;                 // default: 4
-}
-
-interface FormPatternProps {
-  title: string;                 // required
-  subtitle?: string;
-  fields: FormField[];           // required
-  onSubmit: (data: Record<string, string>) => void;  // required
-  submitText?: string;           // default: "Enviar"
-  submitIcon?: string;           // default: "fa-paper-plane"
-  loading?: boolean;
-  error?: string;
-  success?: boolean;
-  className?: string;
-  gridCols?: 1 | 2;             // default: 1
-}
-```
+# Flysoft React UI - AI Context & Documentation
+
+This document serves as the source of truth for AI models (Gemini, Claude, GPT, etc.) when generating code that consumes the `flysoft-react-ui` library.
+
+## Library Philosophy
+
+`flysoft-react-ui` is a React component library built with TypeScript. It emphasizes a consistent look and feel, ease of use, and "premium" aesthetics out of the box. All components use CSS variables for theming and FontAwesome 5 (light/outlined style) for icons.
+
+## Critical Rules for AI
+
+1. **Top-Level Imports Only**: Always import from `'flysoft-react-ui'`.
+   - CORRECT: `import { Button, Card } from 'flysoft-react-ui';`
+   - INCORRECT: `import { Button } from 'flysoft-react-ui/components/Button';`
+2. **TypeScript First**: Use the exported types (e.g., `ButtonProps`, `DataTableColumn<T>`) to ensure type safety.
+3. **Style Import at App Root Only**: Add `import 'flysoft-react-ui/styles';` once at the app root. Never import CSS in individual components.
+4. **Do Not Use Docs Internals**: Never import or reference anything from `docs/*` or `src/docs/*`.
+5. **FontAwesome 5 Only**: Use `fa-*` icon classes. Components normalize to light style (`fal`) automatically. Never use other icon libraries.
+6. **Theme CSS Variables**: Use `var(--color-*)`, `var(--shadow-*)`, `var(--radius-*)`, `var(--font-*)` for custom styling. Never hardcode colors.
+
+---
+
+## Form Controls
+
+### Button
+
+Customizable button with variants, colors, icons, and ripple effect.
+
+```typescript
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: "primary" | "outline" | "ghost";           // default: "primary"
+  size?: "sm" | "md" | "lg";                           // default: "md"
+  color?: "primary" | "secondary" | "success" | "warning" | "danger" | "info"; // default: "primary"
+  bg?: string;                   // Custom background color (hex, rgb, rgba, hsl, or color name)
+  textColor?: string;            // Custom text color
+  icon?: string;                 // FontAwesome icon class (e.g. "fa-save")
+  iconPosition?: "left" | "right";  // default: "left"
+  loading?: boolean;             // Shows spinner, disables button. default: false
+  children?: React.ReactNode;
+}
+```
+
+```tsx
+<Button variant="primary" icon="fa-save" loading={isLoading} onClick={handleSave}>
+  Guardar
+</Button>
+<Button variant="outline" color="danger" icon="fa-trash">Eliminar</Button>
+<Button variant="ghost" size="sm">Cancelar</Button>
+<Button bg="#8b5cf6" textColor="#fff">Custom Color</Button>
+```
+
+### LinkButton
+
+Anchor-styled button that uses React Router `<Link>` for internal routes and `<a>` for external URLs.
+
+```typescript
+interface LinkButtonProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  to: string;                    // Route or URL (required)
+  target?: string;
+  variant?: "primary" | "outline" | "ghost";           // default: "primary"
+  size?: "sm" | "md" | "lg";                           // default: "md"
+  color?: "primary" | "secondary" | "success" | "warning" | "danger" | "info";
+  bg?: string;
+  textColor?: string;
+  icon?: string;
+  iconPosition?: "left" | "right";  // default: "left"
+  children?: React.ReactNode;
+}
+```
+
+```tsx
+<LinkButton to="/users" icon="fa-users">Ver Usuarios</LinkButton>
+<LinkButton to="https://example.com" target="_blank">Sitio Externo</LinkButton>
+```
+
+### Input
+
+Text input with labels, icons, error states, and ref forwarding.
+
+```typescript
+interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size"> {
+  label?: string;                // Label text above input
+  error?: string;                // Error message below input
+  icon?: string;                 // FontAwesome icon class
+  iconPosition?: "left" | "right";  // default: "left"
+  size?: "sm" | "md" | "lg";        // default: "md"
+  children?: React.ReactNode;
+  onIconClick?: (event: React.MouseEvent<HTMLElement>) => void;  // Makes icon clickable
+  readOnly?: boolean;            // Read-only without disabled appearance
+}
+```
+
+```tsx
+<Input label="Email" type="email" icon="fa-envelope" placeholder="usuario@email.com" />
+<Input label="Búsqueda" icon="fa-search" iconPosition="right" onIconClick={handleSearch} />
+<Input label="Nombre" error="Campo requerido" />
+```
+
+### AutocompleteInput
+
+Searchable dropdown with single and multiple selection support.
+
+```typescript
+interface AutocompleteOption {
+  label: string;
+  value: string;
+  description?: string | number;
+  icon?: string;
+}
+
+interface AutocompleteInputProps<T = AutocompleteOption, K = string>
+  extends Omit<InputProps, "onChange" | "value" | "ref"> {
+  options: T[];                  // Options array (required)
+  value?: string | string[];     // String for single, array for multiple
+  onChange?: ((value: string | string[]) => void) | React.ChangeEventHandler<HTMLInputElement>;
+  onSelectOption?: (option: T, value: K) => void;
+  noResultsText?: string;       // default: "Sin resultados"
+  getOptionLabel?: (item: T) => string;
+  getOptionValue?: (item: T) => K;
+  getOptionDescription?: (item: T) => string | number | undefined;
+  renderOption?: (item: T) => React.ReactNode;
+  readOnly?: boolean;
+  multiple?: boolean;            // Multi-select with checkboxes. default: false
+}
+```
+
+```tsx
+// Single selection
+<AutocompleteInput
+  label="País"
+  options={[{ label: "Argentina", value: "AR" }, { label: "Brasil", value: "BR" }]}
+  value={selectedCountry}
+  onChange={setSelectedCountry}
+/>
+
+// Multiple selection
+<AutocompleteInput
+  label="Categorías"
+  options={categories}
+  multiple
+  value={selectedCategories}
+  onChange={setSelectedCategories}
+/>
+
+// Custom objects
+<AutocompleteInput<User, number>
+  label="Usuario"
+  options={users}
+  getOptionLabel={(u) => u.fullName}
+  getOptionValue={(u) => u.id}
+  getOptionDescription={(u) => u.email}
+/>
+```
+
+### SearchSelectInput
+
+Opens a dialog modal for selecting from async search results. Ideal for large datasets.
+
+```typescript
+interface SearchSelectOption {
+  label: string;
+  value?: string;
+  description?: string | number;
+  icon?: string;
+}
+
+interface SearchSelectInputProps<T = SearchSelectOption, K = string>
+  extends Omit<InputProps, "onChange" | "value" | "ref"> {
+  value?: T | K | string;
+  onChange?: ((value: T | K) => void) | React.ChangeEventHandler<HTMLInputElement>;
+  onSearchPromiseFn: (text: string) => Promise<Array<T> | PaginationInterface<T>>;  // required
+  onSingleSearchPromiseFn: (value: K) => Promise<T | undefined>;  // required
+  onSelectOption?: (option: T, value: K) => void;
+  dialogTitle?: string;          // default: "Seleccione una opción"
+  icon?: string;                 // default: "fa-search"
+  iconPosition?: "left" | "right";  // default: "right"
+  noResultsText?: string;       // default: "Sin resultados"
+  getOptionLabel?: (item: T) => string;
+  getOptionValue?: (item: T) => K;
+  getOptionDescription?: (item: T) => string | number | undefined;
+  renderOption?: (item: T) => React.ReactNode;
+  readOnly?: boolean;
+}
+```
+
+```tsx
+<SearchSelectInput<Product, number>
+  label="Producto"
+  onSearchPromiseFn={(text) => apiClient.get({ url: `/api/products?q=${text}` })}
+  onSingleSearchPromiseFn={(id) => apiClient.get({ url: `/api/products/${id}` })}
+  getOptionLabel={(p) => p.name}
+  getOptionValue={(p) => p.id}
+  getOptionDescription={(p) => `$${p.price}`}
+  onChange={(value) => setProductId(value)}
+/>
+```
+
+### DatePicker
+
+Standalone calendar component for date selection.
+
+```typescript
+interface DatePickerProps {
+  value?: Dayjs | null;
+  onChange?: (date: Dayjs) => void;
+  initialViewDate?: Dayjs;       // Initial month/year when value is null
+  startWeekOn?: "monday" | "sunday";  // default: "sunday"
+  className?: string;
+}
+```
+
+### DateInput
+
+Input field with integrated DatePicker dropdown. Accepts manual text and Dayjs objects.
+
+```typescript
+type DateInputFormat = "dd/mm/yyyy" | "mm/dd/yyyy";
+
+interface DateInputProps extends Omit<InputProps, "type" | "value" | "onChange" | "ref"> {
+  value?: Dayjs | null | string;
+  onChange?: ((date: Dayjs | null) => void) | React.ChangeEventHandler<HTMLInputElement>;
+  format?: DateInputFormat;      // default: "dd/mm/yyyy"
+  datePickerProps?: Omit<DatePickerProps, "value" | "onChange">;
+  readOnly?: boolean;
+}
+```
+
+```tsx
+<DateInput label="Fecha de nacimiento" value={birthDate} onChange={setBirthDate} />
+<DateInput label="Start Date" format="mm/dd/yyyy" />
+```
+
+### Checkbox
+
+Boolean checkbox with label and error support. Ref forwarding supported.
+
+```typescript
+interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
+  label?: string;
+  labelPosition?: "left" | "right";  // default: "right"
+  error?: string;
+  size?: "sm" | "md" | "lg";        // default: "md"
+  readOnly?: boolean;
+}
+```
+
+```tsx
+<Checkbox label="Acepto los términos" checked={accepted} onChange={handleChange} />
+<Checkbox label="Activo" size="lg" readOnly />
+```
+
+### RadioButtonGroup
+
+Single selection from a group of radio options.
+
+```typescript
+interface RadioOption {
+  label: string;
+  value: string | number;
+  disabled?: boolean;
+}
+
+interface RadioButtonGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange" | "children"> {
+  options: RadioOption[];        // required
+  value?: string | number;
+  onChange?: ((value: string | number) => void) | React.ChangeEventHandler<HTMLInputElement>;
+  labelPosition?: "left" | "right";  // default: "right"
+  size?: "sm" | "md" | "lg";        // default: "md"
+  error?: string;
+  direction?: "vertical" | "horizontal";  // default: "vertical"
+  gap?: "sm" | "md" | "lg";         // default: "md"
+  name?: string;
+  disabled?: boolean;
+  onBlur?: (() => void) | React.FocusEventHandler<HTMLInputElement>;
+  readOnly?: boolean;
+}
+```
+
+```tsx
+<RadioButtonGroup
+  options={[
+    { label: "Masculino", value: "M" },
+    { label: "Femenino", value: "F" },
+    { label: "Otro", value: "O" },
+  ]}
+  value={gender}
+  onChange={setGender}
+  direction="horizontal"
+/>
+```
+
+### CurrencyInput
+
+Numeric input with currency formatting (Argentine locale: 1.234,56). Ref forwarding supported.
+
+```typescript
+interface CurrencyInputProps extends Omit<InputProps, "value" | "onChange" | "type"> {
+  value?: number | null;
+  onChange?: (value: any) => void;  // Receives parsed numeric value
+}
+```
+
+```tsx
+<CurrencyInput label="Monto" value={amount} onChange={setAmount} icon="fa-dollar-sign" />
+```
+
+### Pagination
+
+URL-based pagination controls using react-router-dom's `useSearchParams`.
+
+```typescript
+interface PaginationProps {
+  fieldName?: string;            // URL param name. default: "pagina"
+  page?: number;                 // default: 1
+  pages?: number;                // default: 1
+  total?: number;                // default: 0
+  isLoading?: boolean;           // default: false
+}
+```
+
+```tsx
+<Pagination page={currentPage} pages={totalPages} total={totalItems} />
+```
+
+---
+
+## Layout Components
+
+### Card
+
+Generic container with header, content, footer, and variants.
+
+```typescript
+interface CardProps {
+  title?: string | React.ReactNode;
+  subtitle?: string | React.ReactNode;
+  children?: React.ReactNode;
+  className?: string;
+  headerActions?: React.ReactNode;
+  footer?: React.ReactNode;
+  variant?: "default" | "elevated" | "outlined";  // default: "default"
+  alwaysDisplayHeaderActions?: boolean;  // default: false (shows on hover on lg+)
+  headerClassName?: string;
+  contentClassName?: string;
+  footerClassName?: string;
+  /**
+   * Override local de densidad: cuando es true, fuerza el preset "compact" en
+   * las variables --flysoft-density-* dentro de esta Card y sus descendientes
+   * (paddings, gaps, tipografía). No depende de la densidad global.
+   */
+  compact?: boolean;             // default: false
+}
+```
+
+```tsx
+<Card title="Usuarios" headerActions={<Button size="sm" icon="fa-plus">Nuevo</Button>}>
+  <p>Contenido</p>
+</Card>
+<Card variant="elevated" compact footer={<Button variant="primary">Guardar</Button>}>
+  <Input label="Nombre" />
+</Card>
+// Card densa que afecta también a los DataField dentro
+<Card title="Datos personales" compact>
+  <Collection direction="row" wrap gap="md">
+    <DataField label="CUIL" value="20-17990271-1" size="sm" />
+    <DataField label="Edad" value={59} size="sm" />
+  </Collection>
+</Card>
+```
+
+### AppLayout
+
+Main application layout with responsive navbar and sidebar drawer.
+
+```typescript
+interface AppLayoutProps {
+  navbar?: NavbarInterface;
+  leftDrawer?: LeftDrawerInterface;
+  contentFooter?: React.ReactNode;
+  children: React.ReactNode;     // required
+  className?: string;
+  isLeftDrawerOpen?: boolean;                        // controlled mobile drawer state
+  onLeftDrawerOpenChange?: (isOpen: boolean) => void;
+}
+
+interface NavbarInterface {
+  navBarLeftNode?: React.ReactNode;
+  navBarRightNode?: React.ReactNode;
+  fullWidthNavbar?: boolean;     // Fixed full-width (true) or relative (false)
+  height?: string;               // default: "64px"
+  className?: string;
+}
+
+interface LeftDrawerInterface {
+  headerNode?: React.ReactNode;
+  contentNode?: React.ReactNode;
+  footerNode?: React.ReactNode;
+  className?: string;
+  width?: string;                // default: "256px"
+}
+```
+
+```tsx
+<AppLayout
+  navbar={{
+    navBarLeftNode: <h1>Mi App</h1>,
+    navBarRightNode: <Avatar text="Admin" />,
+    fullWidthNavbar: true,
+  }}
+  leftDrawer={{
+    headerNode: <h2>Menú</h2>,
+    contentNode: <nav>...</nav>,
+  }}
+>
+  <main>Contenido</main>
+</AppLayout>
+```
+
+**Behaviors**: Navbar auto-hides/shows on scroll. Mobile drawer with overlay. Responsive breakpoints. The mobile drawer closes automatically when switching to desktop.
+
+**Closing the drawer from inside**: any component rendered inside `AppLayout` (drawer content, navbar nodes, footer or `children`) can control the drawer with `useLeftDrawer()`:
+
+```typescript
+interface LeftDrawerContextType {
+  isLeftDrawerOpen: boolean;
+  isLeftDrawerCollapsible: boolean;  // true on mobile/tablet with drawer content
+  openLeftDrawer: () => void;
+  closeLeftDrawer: () => void;
+  toggleLeftDrawer: () => void;
+}
+
+const useLeftDrawer: () => LeftDrawerContextType;          // throws outside AppLayout
+const useOptionalLeftDrawer: () => LeftDrawerContextType | undefined;  // returns undefined
+```
+
+```tsx
+// Menú lateral: cerrar el panel al navegar
+const AppMenu = () => {
+  const { closeLeftDrawer } = useLeftDrawer();
+  return (
+    <nav>
+      <LinkButton to="/inicio" onClick={closeLeftDrawer}>Inicio</LinkButton>
+      <LinkButton to="/clientes" onClick={closeLeftDrawer}>Clientes</LinkButton>
+    </nav>
+  );
+};
+```
+
+Calling `closeLeftDrawer()` on desktop is safe — the drawer is always visible there, so nothing changes.
+
+### Collection
+
+Flex container for rendering lists of items, density-aware.
+
+```typescript
+interface CollectionProps {
+  children: React.ReactNode;     // required
+  /**
+   * Presets semánticos ligados a densidad o cualquier valor CSS arbitrario.
+   * "tight" = 0, "sm"/"md"/"lg" leen --flysoft-density-gap-*.
+   */
+  gap?: "tight" | "sm" | "md" | "lg" | string;  // default: "md"
+  direction?: "column" | "row";  // default: "column"
+  wrap?: boolean;                // default: false
+  className?: string;
+  /**
+   * Override local: redefine --flysoft-density-* para esta Collection y
+   * descendientes. Útil para tener una sección densa dentro de un layout cómodo.
+   */
+  density?: "comfortable" | "compact" | "dense";
+}
+```
+
+```tsx
+// Default
+<Collection><DataField label="A" value="1" /><DataField label="B" value="2" /></Collection>
+
+// Horizontal con wrap, gap chico
+<Collection direction="row" wrap gap="sm">
+  <Badge>Activo</Badge><Badge color="info">Verificado</Badge>
+</Collection>
+
+// Sección densa dentro de Card comfortable
+<Collection density="dense">
+  <DataField label="CUIL" value="..." />
+  <DataField label="Edad" value={59} />
+</Collection>
+```
+
+### DataField
+
+Label + value pair display for detail views. Density-aware.
+
+```typescript
+interface DataFieldProps {
+  label?: string;
+  value?: string | number | React.ReactNode;
+  inline?: boolean;              // Horizontal layout. default: false
+  align?: "left" | "right" | "center";  // default: "left"
+  title?: string;                // HTML title tooltip
+  link?: string;                 // Opens URL in new tab
+  className?: string;
+  labelClassName?: string;
+  /**
+   * Override local de tipografía:
+   * - "md" (default): label = font-sm, value = font-base.
+   * - "sm": baja un nivel — label = font-xs, value = font-sm.
+   */
+  size?: "sm" | "md";
+  /** Separación entre label y value en modo stack. "tight" = 0. */
+  gap?: "tight" | "sm" | "md";  // default: "md"
+  /** Oculta el ":" después del label en modo inline. */
+  hideColon?: boolean;          // default: false
+}
+```
+
+```tsx
+<DataField label="Nombre" value="Juan Pérez" />
+<DataField label="Email" value="juan@email.com" link="mailto:juan@email.com" inline />
+// Modo compacto para listas densas
+<DataField label="CUIL" value="20-17990271-1" size="sm" />
+<DataField label="Estado" value="Activo" inline hideColon />
+```
+
+### TabsGroup / TabPanel
+
+Tabbed interfaces with optional URL persistence.
+
+```typescript
+interface Tab {
+  id: string | number;
+  label: string;
+}
+
+interface TabsGroupProps {
+  children?: React.ReactNode;
+  tabs: Tab[];                   // required
+  paramName?: string;            // URL search param for persistence
+  headerNode?: React.ReactNode;  // Right-aligned header content
+  onChangeTab?: (selectedTab: string) => void;
+}
+
+interface TabPanelProps {
+  children?: React.ReactNode;
+  tabId: string | number;        // Must match a Tab.id (required)
+}
+```
+
+```tsx
+<TabsGroup tabs={[{ id: "info", label: "Información" }, { id: "history", label: "Historial" }]}>
+  <TabPanel tabId="info">
+    <p>Información del usuario</p>
+  </TabPanel>
+  <TabPanel tabId="history">
+    <p>Historial de actividad</p>
+  </TabPanel>
+</TabsGroup>
+```
+
+### DataTable\<T\>
+
+High-performance data table with sorting, formatting, actions, and skeleton loading.
+
+```typescript
+interface DataTableColumn<T> {
+  align?: "left" | "right" | "center";  // Auto-set for date/currency/numeric
+  width?: string;
+  header?: string | React.ReactNode;
+  footer?: string | React.ReactNode;
+  value?: string | number | ((row: T) => string | React.ReactNode);
+  tooltip?: (row: T) => string | React.ReactNode;
+  type?: "text" | "numeric" | "currency" | "date";
+  actions?: (row: T) => Array<React.ReactNode>;
+  headerActions?: () => Array<React.ReactNode>;
+}
+
+interface DataTableProps<T> {
+  columns: DataTableColumn<T>[]; // required
+  rows: T[];                     // required
+  className?: string;
+  maxRows?: number;              // Enables sticky header with scroll
+  locale?: string;               // default: "es-AR"
+  isLoading?: boolean;           // Shows skeleton rows. default: false
+  loadingRows?: number;          // default: 5
+  rowClassName?: (row: T) => string;
+  headerClassName?: string;
+  footerClassName?: string;
+  headerCellClassName?: string;
+  footerCellClassName?: string;
+  cellClassName?: string | ((row: T, column: DataTableColumn<T>) => string);
+  /**
+   * Override local de densidad: cuando es true, fuerza el preset "compact" en
+   * las variables --flysoft-density-* dentro de esta DataTable (paddings,
+   * tipografía, altura de fila). También se propaga a los DropdownMenu de
+   * acciones. Independiente de la densidad global del ThemeProvider.
+   */
+  compact?: boolean;             // default: false
+}
+```
+
+```tsx
+interface User { id: number; name: string; salary: number; createdAt: string; }
+
+const columns: DataTableColumn<User>[] = [
+  { header: "ID", value: "id", width: "60px" },
+  { header: "Nombre", value: (row) => row.name },
+  { header: "Salario", value: "salary", type: "currency" },
+  { header: "Fecha", value: "createdAt", type: "date" },
+  {
+    header: "Acciones",
+    actions: (row) => [
+      <Button key="edit" variant="ghost" size="sm" icon="fa-edit" onClick={() => edit(row)}>Editar</Button>,
+      <Button key="del" variant="ghost" size="sm" icon="fa-trash" color="danger" onClick={() => del(row)}>Eliminar</Button>,
+    ],
+  },
+];
+
+<DataTable<User> columns={columns} rows={users} isLoading={loading} maxRows={10} />
+```
+
+**Type formatting**: `currency` → thousands separator, no symbol. `numeric` → locale formatting. `date` → DD/MM/YYYY.
+
+### Accordion
+
+Collapsible content section with smooth animation.
+
+```typescript
+interface AccordionProps {
+  title: string | React.ReactNode;  // required
+  children: React.ReactNode;        // required
+  icon?: string;                 // FontAwesome icon
+  rightNode?: React.ReactNode;
+  defaultOpen?: boolean;         // default: false
+  className?: string;
+  headerClassName?: string;      // clases para el header (botón)
+  contentClassName?: string;     // clases para el contenedor del contenido
+  variant?: "default" | "elevated" | "outlined";  // default: "default"
+  onToggle?: (isOpen: boolean) => void;
+}
+```
+
+```tsx
+<Accordion title="Detalles" icon="fa-info-circle" defaultOpen>
+  <p>Contenido colapsable</p>
+</Accordion>
+```
+
+### Menu
+
+Simple menu list for displaying options.
+
+```typescript
+interface MenuProps<T = { label: string }> {
+  options: T[];                  // required
+  onOptionSelected: (item: T) => void;  // required
+  getOptionLabel?: (item: T) => string;
+  renderOption?: (item: T) => React.ReactNode;
+  className?: string;
+  style?: React.CSSProperties;
+  itemClassName?: string;
+}
+```
+
+### DropdownMenu
+
+Portal-based dropdown menu triggered by a button. Auto-positions above/below.
+
+```typescript
+interface DropdownMenuProps<T = { label: string }> {
+  options: T[];                  // required
+  onOptionSelected: (item: T) => void;  // required
+  renderNode?: React.ReactNode;  // Custom trigger (default: ellipsis icon button)
+  getOptionLabel?: (item: T) => string;
+  renderOption?: (item: T) => React.ReactNode;
+  replaceOnSingleOption?: boolean;  // Show single option inline. default: false
+  openOnHover?: boolean;         // default: false
+}
+```
+
+```tsx
+<DropdownMenu
+  options={[{ label: "Editar" }, { label: "Eliminar" }]}
+  onOptionSelected={(item) => handleAction(item.label)}
+  renderNode={<Button variant="ghost" icon="fa-cog" size="sm" />}
+/>
+```
+
+### DropdownPanel
+
+Portal-based dropdown that renders arbitrary content (not a list).
+
+```typescript
+interface DropdownPanelProps {
+  renderNode?: React.ReactNode;  // Custom trigger (default: ellipsis icon button)
+  children: React.ReactNode;     // required
+  openOnHover?: boolean;         // default: false
+}
+```
+
+### Filter
+
+Versatile filtering component with multiple filter types and optional URL persistence.
+
+```typescript
+// Discriminated union by filterType
+type FilterProps =
+  | TextFilterProps        // filterType?: "text" (default)
+  | NumberFilterProps      // filterType: "number" (+ min?, max?)
+  | DateFilterProps        // filterType: "date"
+  | AutocompleteFilterProps // filterType: "autocomplete" (+ options, multiple?)
+  | SearchFilterProps      // filterType: "search"
+  | SearchSelectFilterProps // filterType: "searchSelect" (+ onSearchPromiseFn, onSingleSearchPromiseFn)
+
+// Common props for all filter types:
+interface BaseFilterProps {
+  paramName?: string;            // URL search param for persistence
+  label?: string;
+  staticOptions?: Array<{ text: string; value: string }>;
+  inputWidth?: string;
+  value?: string;                // Controlled value
+  onChange?: (value: string | undefined) => void;
+  hideEmpty?: boolean;           // default: false
+  disabled?: boolean;            // default: false
+  compact?: boolean;             // default: false — fuerza densidad compacta local
+  bgColor?: string;              // Fondo del badge e input (no del panel flotante). Ej: "#f5f5f5" o "var(--color-bg-secondary)"
+}
+```
+
+```tsx
+<Filter filterType="text" paramName="nombre" label="Nombre" />
+// Fondo personalizado cuando el filtro va sobre una Card blanca:
+<Filter filterType="search" paramName="q" label="Buscar" bgColor="var(--color-bg-secondary)" />
+<Filter filterType="number" paramName="edad" label="Edad" min={0} max={120} />
+<Filter filterType="date" paramName="fecha" label="Fecha" />
+<Filter
+  filterType="autocomplete"
+  paramName="estado"
+  label="Estado"
+  options={[{ label: "Activo", value: "1" }, { label: "Inactivo", value: "0" }]}
+/>
+<Filter
+  filterType="searchSelect"
+  paramName="cliente"
+  label="Cliente"
+  onSearchPromiseFn={(text) => apiClient.get({ url: `/api/clients?q=${text}` })}
+  onSingleSearchPromiseFn={(id) => apiClient.get({ url: `/api/clients/${id}` })}
+/>
+```
+
+---
+
+## Utility Components
+
+### Badge
+
+Status/category label with variants and custom colors.
+
+```typescript
+interface BadgeProps {
+  children: React.ReactNode;     // required
+  variant?: "primary" | "secondary" | "success" | "warning" | "danger" | "info";  // default: "primary"
+  size?: "sm" | "md" | "lg";    // default: "md"
+  rounded?: boolean;             // Full border radius. default: false
+  className?: string;
+  icon?: string;
+  iconPosition?: "left" | "right";  // default: "left"
+  iconLabel?: string;            // aria-label for icon
+  bg?: string;                   // Custom background color
+  textColor?: string;            // Custom text color
+  onClick?: (event: React.MouseEvent<HTMLElement>) => void;
+}
+```
+
+```tsx
+<Badge variant="success" icon="fa-check">Activo</Badge>
+<Badge variant="danger" rounded>3</Badge>
+<Badge bg="#8b5cf6" textColor="#fff">Custom</Badge>
+```
+
+### Avatar
+
+User profile display with initials fallback when image fails.
+
+```typescript
+interface AvatarProps {
+  text: string;                  // Name for initials extraction (required)
+  image?: string;                // Image URL
+  bgColor?: string;              // default: "#4b5563"
+  textColor?: string;            // default: "#ffffff"
+  size?: "sm" | "md" | "lg";    // default: "md" (sm=32px, md=40px, lg=48px)
+  className?: string;
+}
+```
+
+```tsx
+<Avatar text="Juan Pérez" image="/avatars/juan.jpg" />
+<Avatar text="Admin User" bgColor="#3b82f6" size="lg" />
+```
+
+### RoadMap
+
+Progress/stage visualization with connected circles and gradient lines.
+
+```typescript
+interface RoadMapStage {
+  name: string;                  // required
+  description?: string;
+  icon?: string;
+  disabled?: boolean;            // Grayed out at 50% opacity
+  variant?: "primary" | "secondary" | "success" | "warning" | "danger" | "info";
+  bg?: string;                   // Custom color (overrides variant)
+}
+
+interface RoadMapProps {
+  stages: RoadMapStage[];        // required
+  className?: string;
+}
+```
+
+```tsx
+<RoadMap stages={[
+  { name: "Creado", icon: "fa-plus", variant: "info" },
+  { name: "En Proceso", icon: "fa-cog", variant: "warning" },
+  { name: "Completado", icon: "fa-check", variant: "success" },
+  { name: "Archivado", icon: "fa-archive", disabled: true },
+]} />
+```
+
+### Dialog
+
+Modal window with overlay, escape-to-close, and scroll lock.
+
+```typescript
+interface DialogProps {
+  isOpen: boolean;               // required
+  title: React.ReactNode;       // required
+  children: React.ReactNode;    // required
+  footer?: React.ReactNode;
+  onClose?: () => void;
+  closeOnOverlayClick?: boolean; // default: false
+  /**
+   * Override local de densidad: cuando es true, fuerza el preset "compact" en
+   * --flysoft-density-* dentro del Dialog (paddings header/body/footer,
+   * tamaño del título, gaps). Independiente de la densidad global.
+   */
+  compact?: boolean;             // default: false
+  bodyWidth?: string | number;   // Custom dialog width (e.g. "800px", "80vw", 600). Default: max-w-lg
+}
+```
+
+```tsx
+<Dialog isOpen={showDialog} title="Confirmar" onClose={() => setShowDialog(false)}
+  footer={
+    <>
+      <Button variant="ghost" onClick={() => setShowDialog(false)}>Cancelar</Button>
+      <Button variant="primary" color="danger" onClick={handleDelete}>Eliminar</Button>
+    </>
+  }
+>
+  <p>¿Está seguro que desea eliminar este registro?</p>
+</Dialog>
+```
+
+### Loader
+
+Loading indicator with progress bar. Can wrap content with overlay.
+
+```typescript
+interface LoaderProps {
+  isLoading?: boolean;           // default: false
+  text?: string;                 // Text below progress bar
+  children?: React.ReactNode;
+  keepContentWhileLoading?: boolean;  // Show content faded at 50% opacity
+  contentLoadingNode?: React.ReactNode;  // Custom loading content
+  overlayClassName?: string;     // default: "bg-black/50 backdrop-blur-sm"
+}
+```
+
+```tsx
+<Loader isLoading={loading} text="Cargando datos...">
+  <DataTable ... />
+</Loader>
+<Loader isLoading={loading} keepContentWhileLoading>
+  <Card>...</Card>
+</Loader>
+```
+
+### FiltersDialog
+
+Dialog that groups multiple Filter components. Syncs values from/to URL search params.
+
+```typescript
+interface FilterConfig {
+  filterType: "text" | "number" | "date" | "autocomplete";
+  paramName: string;             // required
+  label?: string;
+  staticOptions?: Array<{ text: string; value: string }>;
+  inputWidth?: string;
+  min?: number;                  // For number filters
+  max?: number;                  // For number filters
+  options?: any[];               // For autocomplete
+  getOptionLabel?: (item: any) => string;
+  getOptionValue?: (item: any) => any;
+  renderOption?: (item: any) => React.ReactNode;
+  noResultsText?: string;
+}
+
+interface FiltersDialogProps {
+  filters: FilterConfig[];       // required
+}
+```
+
+```tsx
+<FiltersDialog filters={[
+  { filterType: "text", paramName: "nombre", label: "Nombre" },
+  { filterType: "number", paramName: "edad", label: "Edad", min: 0, max: 120 },
+  { filterType: "date", paramName: "fecha", label: "Fecha" },
+  { filterType: "autocomplete", paramName: "estado", label: "Estado",
+    options: [{ label: "Activo", value: "1" }, { label: "Inactivo", value: "0" }] },
+]} />
+```
+
+### Snackbar / SnackbarContainer
+
+Toast notification system. SnackbarContainer must be at the app root.
+
+```typescript
+interface SnackbarContainerProps {
+  position?: "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";  // default: "top-right"
+  maxSnackbars?: number;         // default: 5
+}
+
+// Usage via hook (not direct Snackbar component):
+const { showSnackbar } = useSnackbar();
+showSnackbar("Operación exitosa", "success");
+showSnackbar("Error al guardar", "danger", { duration: 5000, icon: "fa-exclamation" });
+```
+
+**Variants**: `"primary"` | `"secondary"` | `"success"` | `"warning"` | `"danger"` | `"info"`
+**Default icons**: success=fa-check-circle, danger=fa-times-circle, warning=fa-exclamation-triangle, info/primary/secondary=fa-info-circle
+
+### Skeleton
+
+Loading placeholder with pulse animation. Fully customizable via className.
+
+```typescript
+interface SkeletonProps {
+  className?: string;  // Tailwind classes to control width, height, shape
+}
+```
+
+```tsx
+<Skeleton className="h-4 w-3/4" />      {/* Text line */}
+<Skeleton className="h-10 w-full" />     {/* Input placeholder */}
+<Skeleton className="h-32 w-32 rounded-full" />  {/* Avatar placeholder */}
+```
+
+### ThemeSwitcher
+
+Self-contained theme toggle. No props. Displays available themes with switch buttons and current theme info.
+
+```tsx
+<ThemeSwitcher />
+```
+
+---
+
+## Contexts & State Management
+
+### ThemeProvider / useTheme
+
+Manages application theme with CSS variable injection, presets, and localStorage persistence.
+
+```typescript
+type Density = "comfortable" | "compact" | "dense";
+
+// Provider props
+interface ThemeProviderProps {
+  children: ReactNode;
+  initialTheme?: string | Theme;       // default: "light"
+  storageKey?: string;                 // localStorage key. default: "flysoft-theme"
+  forceInitialTheme?: boolean;         // Ignore localStorage. default: false
+  onThemeChange?: (theme: Theme) => void;
+  density?: Density;                   // Global density. default: "comfortable"
+  densityStorageKey?: string;          // default: "flysoft-density"
+  forceInitialDensity?: boolean;       // default: false
+  onDensityChange?: (density: Density) => void;
+}
+
+// Hook return
+interface ThemeContextType {
+  theme: Theme;                   // Current theme object
+  setTheme: (theme: Theme | string) => void;  // Switch theme by name or object
+  updateTheme: (updates: Partial<Theme> | ((prev: Theme) => Theme)) => void;
+  currentThemeName: string;
+  availableThemes: string[];      // ["light", "dark", "blue", "green"]
+  resetToDefault: () => void;
+  isDark: boolean;
+  density: Density;
+  setDensity: (density: Density) => void;
+}
+```
+
+```tsx
+// App root - default density
+<ThemeProvider initialTheme="light">
+  <App />
+</ThemeProvider>
+
+// App root - data-heavy app (CRUD admin, dashboards)
+<ThemeProvider initialTheme="light" density="dense">
+  <App />
+</ThemeProvider>
+
+// Runtime toggle
+const { theme, setTheme, isDark, density, setDensity } = useTheme();
+<Button onClick={() => setTheme(isDark ? "light" : "dark")}>Toggle Theme</Button>
+<Button onClick={() => setDensity(density === "dense" ? "comfortable" : "dense")}>
+  Toggle Density
+</Button>
+```
+
+**Preset themes**: `lightTheme`, `darkTheme`, `blueTheme`, `greenTheme` (importable).
+**Density presets**: `comfortableDensity`, `compactDensity`, `denseDensity`, `densityPresets` (importable).
+
+**Density CSS variables** (inyectadas automáticamente según la densidad activa):
+`--flysoft-density-padding-x-{sm|md|lg}`, `--flysoft-density-padding-y-{sm|md|lg}`,
+`--flysoft-density-container-padding-{x|y}`,
+`--flysoft-density-gap-{sm|md|lg}`, `--flysoft-density-font-{xs|sm|base|lg|xl}`,
+`--flysoft-density-control-height-{sm|md|lg}`, `--flysoft-density-datatable-row`,
+`--flysoft-density-datatable-header`, `--flysoft-density-card-gap`.
+
+**Componentes que ya consumen densidad automáticamente** (sin necesidad de prop):
+Card, DataField, Collection, Button, LinkButton, Input, AutocompleteInput,
+SearchSelectInput, DateInput, CurrencyInput, DatePicker, DataTable, Dialog,
+Filter (incluye los paneles flotantes), FiltersDialog, Accordion, Menu,
+DropdownMenu, DropdownPanel, TabsGroup, Badge, Checkbox, RadioButtonGroup,
+Pagination, Avatar, RoadMap, Snackbar, Skeleton, Loader. **Toda la librería
+es density-aware.** El default `comfortable` preserva el aspecto previo de
+cada componente, así que los consumidores existentes no ven cambios visuales
+hasta que activan `density="compact"` o `density="dense"`.
+
+**Tipografía global**: dentro del wrapper `.flysoft-theme-reset` (cualquier
+ThemeProvider/AppLayoutProvider lo crea automáticamente), los headings y
+elementos de texto sin clase específica escalan con densidad:
+- `h1` = `font-xl × 1.5`, `h2` = `font-xl × 1.25`, `h3` = `font-xl`,
+  `h4` = `font-lg`, `h5` = `font-base`, `h6` = `font-sm`
+- `p` = `font-base`, `small` = `font-xs`
+- `span`/`div` heredan `font-base` del wrapper
+
+Las reglas son de baja specificity: cualquier `className` Tailwind (`text-lg`,
+`text-2xl`, etc.) o `style` inline las pisa.
+
+**Componentes con prop `compact` como override local de densidad** (fuerzan
+preset compact en `--flysoft-density-*` dentro de sí y descendientes,
+ignorando la densidad global): Card, DataTable, Dialog, Filter, Accordion,
+Menu, DropdownMenu, DropdownPanel, TabsGroup.
+
+**Override de fondo/estilos en form-controls vía `className`**: los form-controls
+(Input, CurrencyInput, DateInput, AutocompleteInput, SearchSelectInput, Button,
+LinkButton, Checkbox, RadioButtonGroup, DatePicker) combinan sus clases con
+`twMerge`, así que un `className` con clase en conflicto pisa la default de forma
+confiable. Para cambiar el fondo por defecto (`bg-[var(--color-bg-default)]`) —por
+ej. cuando el control va sobre una Card del mismo color— pasá un `bg-*`:
+`<Input className="bg-[var(--color-bg-secondary)]" />` o `<Input className="bg-[#f5f5f5]" />`.
+El `Filter` no toma `className` para esto; usa su prop `bgColor`.
+
+### AuthProvider / AuthContext
+
+Manages authentication with automatic token validation and refresh.
+
+```typescript
+interface AuthProviderProps {
+  children: React.ReactNode;
+  getToken: (username: string, password: string) => Promise<AuthTokenInterface>;  // required
+  getUserData: (auth: AuthTokenInterface) => Promise<AuthContextUserInterface>;   // required
+  refreshToken?: (auth: AuthTokenInterface) => Promise<AuthTokenInterface>;
+  removeToken?: (auth: AuthTokenInterface) => Promise<void>;
+  showLog?: boolean;             // default: false
+}
+
+interface AuthContextType {
+  user: AuthContextUserInterface | null;
+  login: (username: string, password: string) => Promise<void>;
+  logout: () => void;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+}
+
+interface AuthContextUserInterface {
+  id?: number | string;
+  name?: string;
+  aditionalData?: any;
+  token?: AuthTokenInterface;
+}
+
+interface AuthTokenInterface {
+  accessToken?: string;
+  expires?: string;              // ISO 8601
+  tokenType?: string;
+  refreshToken?: string;
+  aditionalData?: any;
+}
+```
+
+```tsx
+<AuthProvider
+  getToken={async (user, pass) => {
+    const res = await apiClient.post({ url: "/auth/login", body: { user, pass } });
+    return res.token;
+  }}
+  getUserData={async (auth) => {
+    return await apiClient.get({ url: "/auth/me" });
+  }}
+  refreshToken={async (auth) => {
+    return await apiClient.post({ url: "/auth/refresh", body: { token: auth.refreshToken } });
+  }}
+>
+  <App />
+</AuthProvider>
+
+// In components
+const { user, login, logout, isAuthenticated } = useContext(AuthContext);
+```
+
+**Behaviors**: Validates token on mount. Checks expiration every 60s. Auto-refreshes if `refreshToken` provided. Stores in localStorage as `"auth"`.
+
+### CrudProvider / useCrud\<T\>
+
+Generic CRUD context with automatic pagination, URL parameter sync, and snackbar notifications.
+
+```typescript
+interface CrudProviderProps<T> {
+  children: ReactNode;
+  getPromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
+  getItemPromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
+  postPromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
+  putPromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
+  deletePromise?: Function | { execute: Function; successMessage?: string; errorMessage?: string | ((error: any) => string) };
+  urlParams?: Array<string>;     // URL params to watch. default: []
+  limit?: number;                // Items per page. default: 15
+  pageParam?: string;            // URL page param. default: "pagina"
+  singleItemId?: string | number;
+  extraData?: Record<string, any>;
+}
+
+interface CrudContextType<T> {
+  list: Array<T> | undefined;
+  item: T | undefined;
+  page: number;
+  pages: number;
+  total: number;
+  limit: number;
+  isLoading: boolean;
+  pagination: ReactNode;         // Pre-built Pagination component
+  params: Record<string, any>;
+  extraData?: Record<string, any>;
+  setExtraData: Dispatch<SetStateAction<Record<string, any> | undefined>>;
+  fetchItems: { execute: (params?: Record<string, any>) => Promise<void>; isLoading: boolean };
+  fetchItem: { execute: (params?: Record<string, any> | string | number) => Promise<T | undefined>; isLoading: boolean };
+  createItem: { execute: (item: T) => Promise<T | undefined | null>; isLoading: boolean };
+  updateItem: { execute: (item: T) => Promise<T | undefined | null>; isLoading: boolean };
+  deleteItem: { execute: (item: T) => Promise<void>; isLoading: boolean };
+}
+```
+
+```tsx
+<CrudProvider<User>
+  getPromise={(params) => apiClient.get({ url: "/api/users", params })}
+  getItemPromise={(id) => apiClient.get({ url: `/api/users/${id}` })}
+  postPromise={{ execute: (item) => apiClient.post({ url: "/api/users", body: item }), successMessage: "Usuario creado" }}
+  putPromise={{ execute: (item) => apiClient.put({ url: `/api/users/${item.id}`, body: item }), successMessage: "Usuario actualizado" }}
+  deletePromise={{ execute: (item) => apiClient.del({ url: `/api/users/${item.id}` }), successMessage: "Usuario eliminado" }}
+  urlParams={["nombre", "estado"]}
+  limit={20}
+>
+  <UserList />
+</CrudProvider>
+
+// In child components
+const { list, isLoading, pagination, createItem, deleteItem } = useCrud<User>();
+```
+
+**Behaviors**: Auto-fetches when URL params change. Resets pagination on filter change. Shows snackbar on success/error.
+
+### SnackbarProvider / useSnackbar
+
+Manages toast notifications.
+
+```typescript
+interface SnackbarActionsType {
+  showSnackbar: (
+    message: string,
+    variant?: SnackbarVariant,
+    options?: { duration?: number; icon?: string; iconLabel?: string }
+  ) => void;
+  removeSnackbar: (id: string) => void;
+}
+```
+
+```tsx
+// App root
+<SnackbarProvider>
+  <SnackbarContainer position="bottom-right" maxSnackbars={3} />
+  <App />
+</SnackbarProvider>
+
+// In components
+const { showSnackbar } = useSnackbar();
+showSnackbar("Guardado exitosamente", "success");
+showSnackbar("Error de conexión", "danger", { duration: 5000 });
+```
+
+### AppLayoutProvider / useAppLayout
+
+Combines ThemeProvider + SnackbarProvider + AppLayout into a single provider.
+
+```typescript
+interface AppLayoutProviderProps {
+  children: ReactNode;
+  initialTheme?: string | Theme;
+  storageKey?: string;
+  forceInitialTheme?: boolean;
+  // Densidad global (propagada al ThemeProvider interno)
+  density?: "comfortable" | "compact" | "dense";  // default: "comfortable"
+  densityStorageKey?: string;                     // default: "flysoft-density"
+  forceInitialDensity?: boolean;
+  onDensityChange?: (density: "comfortable" | "compact" | "dense") => void;
+  initialNavbar?: NavbarInterface;
+  initialLeftDrawer?: LeftDrawerInterface;
+  initialContentFooter?: ReactNode;
+  className?: string;
+}
+
+interface AppLayoutContextType extends ThemeContextType {
+  navbar: NavbarInterface | undefined;
+  leftDrawer: LeftDrawerInterface | undefined;
+  contentFooter: ReactNode | undefined;
+  className: string;
+  setNavbar: Dispatch<SetStateAction<NavbarInterface | undefined>>;
+  setLeftDrawer: Dispatch<SetStateAction<LeftDrawerInterface | undefined>>;
+  setContentFooter: (node: ReactNode | undefined) => void;
+  setClassName: (className: string) => void;
+  setNavBarLeftNode: (node: ReactNode | undefined) => void;
+  setNavbarRightNode: (node: ReactNode | undefined) => void;
+  // Left drawer commands (same state as useLeftDrawer())
+  isLeftDrawerOpen: boolean;
+  openLeftDrawer: () => void;
+  closeLeftDrawer: () => void;
+  toggleLeftDrawer: () => void;
+}
+```
+
+```tsx
+<AppLayoutProvider
+  initialTheme="light"
+  density="dense"   // CRUDs / dashboards / pantallas con mucha info
+  initialNavbar={{ navBarLeftNode: <h1>Mi App</h1>, fullWidthNavbar: true }}
+  initialLeftDrawer={{ contentNode: <nav>...</nav> }}
+>
+  <Routes />
+</AppLayoutProvider>
+
+// In pages - dynamically update layout
+const { setNavBarLeftNode, setNavbarRightNode } = useAppLayout();
+useEffect(() => {
+  setNavBarLeftNode(<h1>Dashboard</h1>);
+}, []);
+
+// Close the mobile drawer from anywhere inside the layout
+const { closeLeftDrawer } = useAppLayout();   // or useLeftDrawer()
+<LinkButton to="/clientes" onClick={closeLeftDrawer}>Clientes</LinkButton>
+```
+
+---
+
+## Hooks
+
+### useThemeOverride
+
+Applies granular CSS variable overrides without changing the entire theme.
+
+```typescript
+function useThemeOverride(options?: {
+  scope?: "global" | "local";    // default: "global"
+  element?: HTMLElement | null;
+  prefix?: string;               // default: "flysoft"
+}): {
+  applyOverride: (overrides: Record<string, string | number>) => void;
+  revertOverride: (keys: string[]) => void;
+  revertAllOverrides: () => void;
+  getCSSVariable: (key: string) => string | null;
+  isOverrideApplied: (key: string) => boolean;
+  appliedOverridesCount: number;
+}
+```
+
+### useTemporaryOverride
+
+Applies CSS variable overrides that auto-revert after a duration.
+
+```typescript
+function useTemporaryOverride(
+  overrides: Record<string, string | number>,
+  duration?: number,             // default: 3000
+  options?: { scope?: "global" | "local"; element?: HTMLElement | null; prefix?: string }
+): { applyTemporaryOverride: () => Function }
+```
+
+### useBreakpoint
+
+Returns current viewport breakpoint and device type.
+
+```typescript
+type Breakpoint = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+
+function useBreakpoint(): {
+  breakpoint: Breakpoint;
+  windowSize: { width: number; height: number };
+  isMobile: boolean;             // xs or sm
+  isTablet: boolean;             // md
+  isDesktop: boolean;            // lg, xl, or 2xl
+}
+```
+
+### useElementScroll
+
+Tracks scroll position and direction with requestAnimationFrame optimization.
+
+```typescript
+function useElementScroll(elementRef: React.RefObject<HTMLElement | null>): {
+  scrollY: number;
+  scrollDirection: "up" | "down" | null;
+}
+```
+
+### useAsyncRequest
+
+Manages async operations with loading state and snackbar notifications.
+
+```typescript
+interface AsyncRequestOptions {
+  successMessage?: string;
+  errorMessage?: string | ((error: any) => string);
+  successVariant?: SnackbarVariant;  // default: "success"
+  errorVariant?: SnackbarVariant;    // default: "danger"
+  onSuccess?: (data: any) => void;
+  onError?: (error: any) => void;
+  onFinally?: () => void;
+}
+
+function useAsyncRequest(options?: AsyncRequestOptions): {
+  isLoading: boolean;
+  execute: <T>(requestFn: () => Promise<T>) => Promise<T | undefined>;
+  setLoading: (loading: boolean) => void;
+}
+```
+
+```tsx
+const { execute, isLoading } = useAsyncRequest({
+  successMessage: "Guardado exitosamente",
+  errorMessage: (err) => getErrorMessage(err),
+});
+await execute(() => apiClient.post({ url: "/api/data", body: formData }));
+```
+
+### useEnum
+
+Converts TypeScript enums to arrays for form select options.
+
+```typescript
+function useEnum(baseEnum: any): {
+  getArray: () => Array<NameValueInterface<number>>;
+  getInstance: (id: number) => NameValueInterface<number> | undefined;
+}
+```
+
+### useGlobalThemeStyles
+
+Applies theme colors to `<body>` and `<html>` for full-page theming. No return value.
+
+```tsx
+function useGlobalThemeStyles(): void;
+```
+
+---
+
+## Services
+
+### apiClient
+
+Singleton HTTP client (Axios-based) with automatic Bearer token injection.
+
+```typescript
+// Main methods
+apiClient.get<T>(options: { url: string; params?: Record<string, unknown>; headers?: Record<string, string> }): Promise<T>;
+apiClient.post<T>(options: { url: string; body?: unknown; headers?: Record<string, string> }): Promise<T>;
+apiClient.put<T>(options: { url: string; body?: unknown; headers?: Record<string, string> }): Promise<T>;
+apiClient.patch<T>(options: { url: string; body?: unknown; headers?: Record<string, string> }): Promise<T>;
+apiClient.del<T>(options: { url: string; headers?: Record<string, string> }): Promise<T>;
+
+// File operations
+apiClient.getFile(options): Promise<{ data: Blob; headers: any }>;
+apiClient.getFileAsUrl(options): Promise<string>;
+apiClient.openFile(options): Promise<void>;
+apiClient.downloadFile(options): Promise<void>;
+apiClient.uploadFile<T>(options: { url: string; files: FileList | File[]; headers?: { paramName?: string } }): Promise<T>;
+
+// Token management
+setApiClientTokenProvider(provider?: () => string | undefined): void;
+clearApiClientTokenProvider(): void;
+
+// Create isolated instances
+createApiClient(config?: { baseURL?: string; timeout?: number; headers?: Record<string, string> }): ApiClientService;
+```
+
+```tsx
+// Setup token globally
+setApiClientTokenProvider(() => user?.token?.accessToken);
+
+// API calls
+const users = await apiClient.get<User[]>({ url: "/api/users", params: { page: 1 } });
+await apiClient.post({ url: "/api/users", body: { name: "Juan" } });
+await apiClient.downloadFile({ url: "/api/reports/pdf" });
+await apiClient.uploadFile({ url: "/api/upload", files: fileInput.files });
+```
+
+---
+
+## Helpers
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `currencyFormat` | `(value: number) => string` | Formats as `"1.234,56"` (es-AR locale) |
+| `getErrorMessage` | `(error: any) => string` | Extracts message from AxiosError. Default: `"Ha ocurrido un error"` |
+| `getInitialLetters` | `(text: string) => string` | `"Juan Pérez"` → `"JP"` |
+| `getQueryString` | `(params: URLSearchParams, newParams: any) => string` | Merges params, returns `"?key=value"` |
+| `objectToQueryString` | `(source: any) => string` | Object to `"a=1&b=2"` (no leading `?`) |
+| `queryStringToObject` | `(params: string) => Record<string, string>` | `"a=1&b=2"` → `{a: "1", b: "2"}` |
+| `nameValueArrayToObject` | `<T>(arr: NameValueInterface<T>[]) => Record<string, T>` | Array of {name, value} to object |
+| `promiseMapper` | `<T, K>(promise, mapper) => Promise<K \| K[] \| PaginationInterface<K>>` | Maps promise results (arrays, pagination, single) |
+| `RegularExpressions` | Object | `.email`, `.dateString`, `.password(config)` regex patterns |
+
+## Interfaces
+
+```typescript
+interface NameValueInterface<T> {
+  name: string;
+  value: T;
+  extras?: any;
+}
+
+interface PaginationInterface<T> {
+  list: Array<T>;
+  limit: number;
+  page: number;
+  pages: number;
+  total: number;
+}
+```
+
+---
+
+## Templates
+
+### LoginForm
+
+```typescript
+interface LoginFormProps {
+  onSubmit?: (data: { email: string; password: string }) => void;
+  loading?: boolean;
+  error?: string;
+  className?: string;
+}
+```
+
+### RegistrationForm
+
+```typescript
+interface RegistrationFormProps {
+  onSubmit?: (data: { firstName: string; lastName: string; email: string; password: string; confirmPassword: string }) => void;
+  loading?: boolean;
+  error?: string;
+  className?: string;
+}
+```
+
+### ContactForm
+
+```typescript
+interface ContactFormProps {
+  onSubmit?: (data: { name: string; email: string; subject: string; message: string }) => void;
+  loading?: boolean;
+  success?: boolean;
+  error?: string;
+  className?: string;
+}
+```
+
+### DashboardLayout
+
+```typescript
+interface DashboardStat {
+  title: string;
+  value: string | number;
+  change?: string;               // e.g. "+12%"
+  changeType?: "positive" | "negative" | "neutral";
+  icon?: string;
+}
+
+interface DashboardLayoutProps {
+  title: string;                 // required
+  subtitle?: string;
+  stats?: DashboardStat[];
+  actions?: React.ReactNode;
+  children: React.ReactNode;     // required
+  className?: string;
+}
+```
+
+### SidebarLayout
+
+```typescript
+interface MenuItem {
+  label: string;
+  icon: string;
+  href: string;
+  badge?: string | number;
+  children?: MenuItem[];
+}
+
+interface User {
+  name: string;
+  email?: string;
+  avatar?: string;
+}
+
+interface SidebarLayoutProps {
+  title: string;                 // required
+  menuItems: MenuItem[];         // required
+  user: User;                    // required
+  children: React.ReactNode;     // required
+  className?: string;
+  onLogout?: () => void;
+}
+```
+
+### FormPattern
+
+```typescript
+interface FormField {
+  name: string;
+  label: string;
+  type?: string;                 // default: "text"
+  placeholder?: string;
+  icon?: string;
+  required?: boolean;
+  validation?: (value: string) => string | undefined;
+  multiline?: boolean;
+  rows?: number;                 // default: 4
+}
+
+interface FormPatternProps {
+  title: string;                 // required
+  subtitle?: string;
+  fields: FormField[];           // required
+  onSubmit: (data: Record<string, string>) => void;  // required
+  submitText?: string;           // default: "Enviar"
+  submitIcon?: string;           // default: "fa-paper-plane"
+  loading?: boolean;
+  error?: string;
+  success?: boolean;
+  className?: string;
+  gridCols?: 1 | 2;             // default: 1
+}
+```