@mks2508/sidebar-headless 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1663 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, CSSProperties, ElementType, ComponentType, RefObject, MouseEvent } from 'react';
+import { GlassConfig } from '@liquid-svg-glass/core';
+import { ClassValue } from 'clsx';
+
+interface SidebarLiquidConfig extends GlassConfig {
+    /** Habilitar chromatic aberration (Phase 2) - solo para tooltips por defecto */
+    enableChromaticAberration?: boolean;
+}
+
+/**
+ * Modo de colapso del sidebar
+ * @enum {string}
+ */
+declare enum SidebarCollapseMode {
+    /** Colapsa el sidebar a un ancho mínimo mostrando solo iconos */
+    COLLAPSE = "collapse",
+    /** Oculta completamente el sidebar */
+    HIDE = "hide"
+}
+/**
+ * Comportamiento del sidebar cuando está en modo hide
+ * @enum {string}
+ */
+declare enum SidebarHideBehaviour {
+    /** Muestra un botón indicador para reabrir el sidebar */
+    SHOW_INDICATOR = "showIndicator",
+    /** El sidebar es completamente controlado externamente sin indicador */
+    CONTROLLED = "controlled"
+}
+/**
+ * Comportamiento al abrir desde el estado hide
+ * @enum {string}
+ */
+declare enum SidebarHideOpensBehavior {
+    /** Abre al tamaño colapsado (solo iconos) */
+    COLLAPSED = "collapsed",
+    /** Abre al tamaño expandido completo */
+    EXPANDED = "expanded"
+}
+/**
+ * Comportamiento de layout del sidebar
+ * @enum {string}
+ */
+declare enum SidebarLayoutBehaviour {
+    /** Sidebar flotante con z-index que NO desplaza el contenido (default) */
+    FLOATING = "floating",
+    /** Sidebar como parte del layout que SÍ desplaza el contenido */
+    INLINE = "inline"
+}
+/**
+ * Anchos predefinidos del sidebar
+ * @enum {string}
+ */
+declare enum SidebarWidth {
+    /** Ancho en estado colapsado (solo iconos) */
+    COLLAPSED = "5rem",
+    /** Ancho expandido completo */
+    EXPANDED = "16rem",
+    /** Ancho mínimo absoluto */
+    MIN = "3rem",
+    /** Ancho máximo absoluto */
+    MAX = "20rem"
+}
+/**
+ * Duraciones de transición en milisegundos
+ * @enum {number}
+ */
+declare enum SidebarTransitionDuration {
+    /** Transición rápida para cambios de opacidad */
+    FAST = 200,
+    /** Transición normal para width y transforms */
+    NORMAL = 300,
+    /** Transición lenta para animaciones complejas */
+    SLOW = 500
+}
+/**
+ * Índices Z para capas del sidebar
+ * @enum {number}
+ */
+declare enum SidebarZIndex {
+    /** Base del contenedor wrapper */
+    BASE = 0,
+    /** Indicador visual */
+    INDICATOR = 5,
+    /** Contenido interno del sidebar */
+    CONTENT = 10,
+    /** Botón de toggle */
+    TOGGLE = 30
+}
+/**
+ * Radios de borde predefinidos
+ * @enum {string}
+ */
+declare enum SidebarBorderRadius {
+    /** Sin radio de borde */
+    NONE = "0",
+    /** Radio pequeño */
+    SM = "0.25rem",
+    /** Radio medio */
+    MD = "0.5rem",
+    /** Radio grande */
+    LG = "1rem",
+    /** Radio completo (circular) */
+    FULL = "9999px"
+}
+/**
+ * Posiciones para SidebarSafeArea
+ * @enum {string}
+ */
+declare enum SidebarSafeAreaPosition {
+    /** Área segura superior */
+    TOP = "top",
+    /** Área segura inferior */
+    BOTTOM = "bottom"
+}
+/**
+ * Timing functions para transiciones CSS
+ * @enum {string}
+ */
+declare enum SidebarTimingFunction {
+    /** Ease estándar */
+    EASE = "ease",
+    /** Linear (velocidad constante) */
+    LINEAR = "linear",
+    /** Ease in (aceleración) */
+    EASE_IN = "ease-in",
+    /** Ease out (desaceleración) */
+    EASE_OUT = "ease-out",
+    /** Ease in out (aceleración y desaceleración) */
+    EASE_IN_OUT = "ease-in-out",
+    /** Cubic bezier personalizado */
+    CUSTOM = "cubic-bezier(0.4, 0, 0.2, 1)"
+}
+/**
+ * Configuración de estilo visual del sidebar
+ * @interface
+ */
+interface SidebarVisualStyle {
+    /** Margen superior (separación del borde superior) */
+    marginTop?: string;
+    /** Margen inferior (separación del borde inferior) */
+    marginBottom?: string;
+    /** Margen izquierdo (separación del borde izquierdo) */
+    marginLeft?: string;
+    /** Margen derecho (generalmente 0 en modo inline) */
+    marginRight?: string;
+    /** Altura del sidebar (default: "100vh") */
+    height?: string;
+    /** Radio de borde redondeado */
+    borderRadius?: string;
+    /** Sombra del sidebar */
+    boxShadow?: string;
+}
+/**
+ * Configuración de dimensiones del sidebar
+ * @interface
+ */
+interface SidebarDimensions {
+    /** Ancho cuando está colapsado */
+    collapsedWidth: string;
+    /** Ancho cuando está expandido */
+    expandedWidth: string;
+    /** Altura del indicador visual */
+    indicatorHeight: string;
+    /** Distancia del tooltip al borde del sidebar (CSS-first con Anchor API) */
+    tooltipDistance?: string;
+    /** Configuración de estilo visual */
+    visualStyle?: SidebarVisualStyle;
+}
+/**
+ * Configuración de áreas seguras (safe areas)
+ * @interface
+ */
+interface SidebarSafeAreas {
+    /** Porcentaje de altura para área segura superior */
+    topPercent: number;
+    /** Porcentaje de altura para área segura inferior */
+    bottomPercent: number;
+}
+/**
+ * Configuración de animaciones
+ * @interface
+ */
+interface SidebarAnimations {
+    /** Duración de transición de width en ms */
+    widthTransitionDuration: number;
+    /** Duración de transición de opacidad en ms */
+    opacityTransitionDuration: number;
+    /** Función de timing para animaciones */
+    timingFunction: string;
+}
+/**
+ * Configuración experimental de Liquid Glass V2
+ *
+ * @description
+ * Feature flags para habilitar efectos avanzados de liquid glass basados en:
+ * - SVG Displacement Mapping (Snell's Law refraction)
+ * - Chromatic Aberration (RGB channel separation)
+ * - Edge Glass 3D (dual backdrop layers)
+ * - Backdrop Extension (Josh Comeau technique)
+ *
+ * @interface
+ * @experimental
+ */
+interface SidebarLiquidGlassConfig {
+    /**
+     * Habilitar Liquid Glass V2 (master flag)
+     *
+     * @description
+     * Activa el uso de FluidHoverIndicatorV2 y SidebarTooltipV2 con SVG displacement mapping
+     * en lugar de las versiones básicas con backdrop-blur CSS.
+     *
+     * @default false
+     */
+    enableLiquidGlassV2?: boolean;
+    /**
+     * Habilitar Chromatic Aberration (Phase 2)
+     *
+     * @description
+     * Activa la separación real de canales RGB usando feColorMatrix + feOffset
+     * en lugar del método legacy basado en diferentes escalas de displacement.
+     * Proporciona +15% de realismo visual según benchmarks.
+     *
+     * **Requiere**: enableLiquidGlassV2 = true
+     *
+     * @default false
+     */
+    enableChromaticAberration?: boolean;
+    /**
+     * Habilitar Edge Glass 3D (tooltips)
+     *
+     * @description
+     * Activa dual backdrop layers con blur diferenciado para crear ilusión de profundidad:
+     * - Depth layer: blur alto (16px) con brightness 1.15
+     * - Surface layer: blur moderado (8px) con brightness 1.25
+     *
+     * **Solo aplica a**: SidebarTooltipV2
+     * **Requiere**: enableLiquidGlassV2 = true
+     *
+     * @default true
+     */
+    enableEdgeGlass3D?: boolean;
+    /**
+     * Habilitar Backdrop Extension (Josh Comeau)
+     *
+     * @description
+     * Extiende el área de backdrop-filter al 200% de altura con mask
+     * para capturar elementos cercanos y mejorar el realismo de la refracción.
+     *
+     * **Solo aplica a**: SidebarTooltipV2
+     * **Requiere**: enableLiquidGlassV2 = true
+     *
+     * @default true
+     */
+    enableBackdropExtension?: boolean;
+    /**
+     * Habilitar animaciones staggered de items en tooltips
+     *
+     * @description
+     * Activa entrada/salida escalonada de items del tooltip usando CSS custom properties.
+     * Incluye grid trick para height auto transitions y direction-aware animations.
+     *
+     * **Solo aplica a**: SidebarTooltipV2
+     *
+     * @default true
+     * @experimental
+     */
+    enableTooltipItemAnimations?: boolean;
+    /**
+     * Habilitar animación 3D de cilindro para títulos de tooltips
+     *
+     * @description
+     * Activa efecto de cilindro rotatorio 3D para el título del tooltip usando Web Animations API.
+     * Mantiene historial circular de últimos 10 títulos y rota según dirección de navegación.
+     *
+     * **Features**:
+     * - Rotación 3D con rotateX
+     * - Direction-aware (up/down navigation)
+     * - Historial circular de títulos
+     * - Duración: 400ms, easing cubic-bezier
+     *
+     * **Solo aplica a**: SidebarTooltip
+     *
+     * @default false
+     * @experimental
+     */
+    enableCylinderTitle?: boolean;
+    /**
+     * Overrides de preset para configuración avanzada de Liquid Glass
+     *
+     * @description
+     * Permite sobrescribir valores del preset 'sidebar' para debugging y ajuste fino.
+     * Incluye parámetros visuales como frost, blur, scale, chromatic aberration RGB, etc.
+     *
+     * **Ejemplo**:
+     * ```tsx
+     * presetOverrides: {
+     *   frost: 0.08,
+     *   blur: 12,
+     *   blurBackground: 10,
+     *   scale: -200,
+     *   r: 5,
+     *   g: 15,
+     *   b: 25
+     * }
+     * ```
+     *
+     * **Requiere**: enableLiquidGlassV2 = true
+     *
+     * @default undefined
+     * @experimental
+     */
+    presetOverrides?: Partial<SidebarLiquidConfig>;
+}
+/**
+ * Librería de iconos a utilizar
+ * @enum {string}
+ */
+declare enum SidebarIconLibrary {
+    /** Iconos de lucide-react */
+    LUCIDE = "lucide",
+    /** Iconos custom proporcionados por el usuario */
+    CUSTOM = "custom"
+}
+/**
+ * Estado compartido del sidebar
+ * @interface
+ */
+interface SidebarState {
+    /** Indica si el sidebar está abierto */
+    open: boolean;
+    /** Indica si el sidebar está colapsado (solo en modo COLLAPSE) */
+    collapsed: boolean;
+    /** Modo de colapso actual */
+    collapseMode: SidebarCollapseMode;
+    /** Comportamiento de layout actual */
+    layoutBehaviour: SidebarLayoutBehaviour;
+}
+/**
+ * Estado del botón toggle
+ * @interface
+ */
+interface SidebarToggleState {
+    /** Indica si el toggle está activo/presionado */
+    active: boolean;
+    /** Indica si el sidebar está abierto */
+    open: boolean;
+}
+/**
+ * Estado de un item del sidebar
+ * @interface
+ */
+interface SidebarItemState {
+    /** Indica si el item está enfocado por teclado */
+    focused: boolean;
+    /** Indica si el mouse está sobre el item */
+    hovered: boolean;
+    /** Indica si el item está deshabilitado */
+    disabled: boolean;
+}
+/**
+ * Estado del indicador visual
+ * @interface
+ */
+interface SidebarIndicatorState {
+    /** Indica si el indicador está visible */
+    visible: boolean;
+    /** Posición Y del indicador en píxeles */
+    position: number;
+}
+/**
+ * Tipo para render prop de Sidebar
+ */
+type SidebarRenderProp = (state: SidebarState) => ReactNode;
+/**
+ * Tipo para render prop de SidebarToggle
+ */
+type SidebarToggleRenderProp = (state: SidebarToggleState) => ReactNode;
+/**
+ * Tipo para render prop de SidebarItem
+ */
+type SidebarItemRenderProp = (state: SidebarItemState) => ReactNode;
+/**
+ * Tipo para render prop de SidebarIndicator
+ */
+type SidebarIndicatorRenderProp = (state: SidebarIndicatorState) => ReactNode;
+/**
+ * Valor del contexto compartido del Sidebar
+ * @interface
+ */
+interface SidebarContextValue {
+    /** Estado inicial del sidebar (solo lectura) */
+    defaultOpen: boolean;
+    /** Estado actual open/closed del sidebar */
+    open: boolean;
+    /** Función para actualizar el estado open */
+    setOpen: (open: boolean) => void;
+    /** Modo de colapso actual */
+    collapseMode: SidebarCollapseMode;
+    /** Comportamiento en modo hide */
+    hideBehaviour: SidebarHideBehaviour;
+    /** Comportamiento al abrir desde hide */
+    hideOpensBehavior: SidebarHideOpensBehavior;
+    /** Comportamiento de layout del sidebar */
+    layoutBehaviour: SidebarLayoutBehaviour;
+    /** Configuración de dimensiones */
+    dimensions: SidebarDimensions;
+    /** Configuración de safe areas */
+    safeAreas: SidebarSafeAreas;
+    /** Configuración de animaciones */
+    animations: SidebarAnimations;
+    /** ID del toggle input */
+    toggleId: string;
+    /** Modo debug para visualizar safe areas */
+    debug: boolean;
+    /** Ref al contenedor de navegación */
+    navRef: RefObject<HTMLElement | null>;
+    /** Ref al contenedor de items */
+    contentRef: RefObject<HTMLDivElement | null>;
+    /** Ref al indicador visual */
+    indicatorRef: RefObject<HTMLDivElement | null>;
+    /** Registrar un item para navegación por teclado */
+    registerItem: (element: HTMLElement) => void;
+    /** Des-registrar un item */
+    unregisterItem: (element: HTMLElement) => void;
+    /** Items registrados actualmente */
+    items: HTMLElement[];
+    /** Indica si el indicador debe mostrarse por navegación de teclado */
+    showIndicatorForKeyboard: boolean;
+    /** Función para activar/desactivar el indicador por teclado */
+    setShowIndicatorForKeyboard: (show: boolean) => void;
+    /** Indica si el cursor/focus está sobre el área de items */
+    isOverItems: boolean;
+    /** Función para actualizar el estado de isOverItems */
+    setIsOverItems: (isOver: boolean) => void;
+    /** Habilitar FluidHoverIndicator (glassmorphism + spring physics) */
+    enableFluidIndicator: boolean;
+    /** Habilitar tooltip en hover (muestra label o subcategorías) */
+    enableTooltip: boolean;
+    /** Elemento del item actualmente hovered/focused (para FluidIndicator) */
+    currentItemElement: HTMLElement | null;
+    /** Función para actualizar el currentItemElement */
+    setCurrentItemElement: (element: HTMLElement | null) => void;
+    /** Configuración experimental de Liquid Glass V2 */
+    liquidGlass: SidebarLiquidGlassConfig;
+}
+/**
+ * Props del componente Sidebar (root container)
+ * @interface
+ */
+interface SidebarProps {
+    /** Contenido del sidebar (puede ser ReactNode o render prop) */
+    children: ReactNode | SidebarRenderProp;
+    /** Clase CSS adicional para el wrapper */
+    className?: string;
+    /** Estilos inline para el wrapper */
+    style?: CSSProperties;
+    /** Estado inicial abierto (modo uncontrolled) */
+    defaultOpen?: boolean;
+    /** Estado abierto (modo controlled) */
+    open?: boolean;
+    /** Callback cuando cambia el estado open */
+    onOpenChange?: (open: boolean) => void;
+    /** Modo de colapso del sidebar */
+    collapseMode?: SidebarCollapseMode;
+    /** Comportamiento en modo hide */
+    hideBehaviour?: SidebarHideBehaviour;
+    /** Comportamiento al abrir desde hide */
+    hideOpensBehavior?: SidebarHideOpensBehavior;
+    /** Comportamiento de layout del sidebar */
+    layoutBehaviour?: SidebarLayoutBehaviour;
+    /** Configuración de dimensiones (partial override) */
+    dimensions?: Partial<SidebarDimensions>;
+    /** Configuración de áreas seguras (partial override) */
+    safeAreas?: Partial<SidebarSafeAreas>;
+    /** Configuración de animaciones (partial override) */
+    animations?: Partial<SidebarAnimations>;
+    /** ID personalizado para el toggle input */
+    toggleId?: string;
+    /** Modo debug (muestra bordes y labels) */
+    debug?: boolean;
+    /** Habilitar FluidHoverIndicator (glassmorphism + spring physics) */
+    enableFluidIndicator?: boolean;
+    /** Habilitar tooltip en hover (muestra label o subcategorías) */
+    enableTooltip?: boolean;
+    /**
+     * Configuración experimental de Liquid Glass V2 (partial override)
+     *
+     * @description
+     * Permite activar/desactivar features experimentales de liquid glass mediante flags:
+     *
+     * @example
+     * ```tsx
+     * <Sidebar
+     *   liquidGlass={{
+     *     enableLiquidGlassV2: true,
+     *     enableChromaticAberration: true,
+     *     enableEdgeGlass3D: true,
+     *     enableBackdropExtension: true
+     *   }}
+     * >
+     *   ...
+     * </Sidebar>
+     * ```
+     *
+     * @experimental
+     */
+    liquidGlass?: Partial<SidebarLiquidGlassConfig>;
+    /** Elemento o componente a renderizar */
+    as?: ElementType;
+}
+/**
+ * Props del componente SidebarNav
+ * @interface
+ */
+interface SidebarNavProps {
+    /** Contenido del nav */
+    children: ReactNode;
+    /** Clase CSS adicional */
+    className?: string;
+    /** Estilos inline */
+    style?: CSSProperties;
+    /** Label ARIA para el nav */
+    "aria-label"?: string;
+    /** Elemento o componente a renderizar */
+    as?: ElementType;
+}
+/**
+ * Props del componente SidebarToggle
+ * @interface
+ */
+interface SidebarToggleProps {
+    /** Contenido del botón (puede ser ReactNode o render prop) */
+    children?: ReactNode | SidebarToggleRenderProp;
+    /** Librería de iconos a utilizar (Lucide o custom) */
+    iconLibrary?: SidebarIconLibrary;
+    /** Clase CSS adicional */
+    className?: string;
+    /** Estilos inline */
+    style?: CSSProperties;
+    /** Label ARIA para el botón */
+    "aria-label"?: string;
+    /** Elemento o componente a renderizar */
+    as?: ElementType;
+}
+/**
+ * Props del componente SidebarContent
+ * @interface
+ */
+interface SidebarContentProps {
+    /** Contenido (items del sidebar) */
+    children: ReactNode;
+    /** Clase CSS adicional */
+    className?: string;
+    /** Estilos inline */
+    style?: CSSProperties;
+    /** Elemento o componente a renderizar */
+    as?: ElementType;
+}
+/**
+ * Props del componente SidebarIndicator
+ * @interface
+ */
+interface SidebarIndicatorProps {
+    /** Contenido personalizado del indicador (opcional) */
+    children?: ReactNode | SidebarIndicatorRenderProp;
+    /** Clase CSS adicional */
+    className?: string;
+    /** Estilos inline */
+    style?: CSSProperties;
+    /** Elemento o componente a renderizar */
+    as?: ElementType;
+}
+/**
+ * Props del componente SidebarSafeArea
+ * @interface
+ */
+interface SidebarSafeAreaProps {
+    /** Contenido del área segura */
+    children?: ReactNode;
+    /** Posición del área segura (top o bottom) */
+    position: SidebarSafeAreaPosition;
+    /** Porcentaje de altura del sidebar (override del config) */
+    percent?: number;
+    /** Clase CSS adicional */
+    className?: string;
+    /** Estilos inline */
+    style?: CSSProperties;
+    /** Elemento o componente a renderizar */
+    as?: ElementType;
+}
+/**
+ * Props del componente SidebarItem
+ * @interface
+ */
+interface SidebarItemProps {
+    /** URL de destino */
+    href?: string;
+    /** Icono del item */
+    icon?: ReactNode;
+    /** Label/texto del item */
+    label?: string;
+    /** Contenido del item (puede ser ReactNode o render prop) */
+    children?: ReactNode | SidebarItemRenderProp;
+    /** Componente Link personalizado (ej: React Router Link, Next Link) */
+    LinkComponent?: ComponentType<any>;
+    /** Props adicionales para el LinkComponent */
+    linkProps?: Record<string, any>;
+    /** Clase CSS adicional */
+    className?: string;
+    /** Estilos inline */
+    style?: CSSProperties;
+    /** Callback al hacer hover */
+    onHover?: () => void;
+    /** Callback al hacer click */
+    onClick?: () => void;
+    /** Item deshabilitado */
+    disabled?: boolean;
+    /** Elemento o componente a renderizar */
+    as?: ElementType;
+}
+/**
+ * Configuración completa del sidebar (sin partials)
+ */
+interface SidebarConfig {
+    defaultOpen: boolean;
+    collapseMode: SidebarCollapseMode;
+    hideBehaviour: SidebarHideBehaviour;
+    hideOpensBehavior: SidebarHideOpensBehavior;
+    layoutBehaviour: SidebarLayoutBehaviour;
+    dimensions: SidebarDimensions;
+    safeAreas: SidebarSafeAreas;
+    animations: SidebarAnimations;
+    toggleId: string;
+    debug: boolean;
+    liquidGlass: SidebarLiquidGlassConfig;
+}
+
+/**
+ * Componente raíz del Sidebar con arquitectura headless
+ *
+ * @description
+ * Componente principal que provee el contexto compartido a todos los
+ * componentes primitivos del sidebar (SidebarNav, SidebarToggle, etc.).
+ *
+ * Este componente NO renderiza ningún elemento visual por sí mismo,
+ * solo provee el Provider de contexto. Los estilos y estructura visual
+ * se definen componiendo los primitivos hijos.
+ *
+ * Soporta dos modos:
+ * - **Uncontrolled**: Usa `defaultOpen` para estado interno
+ * - **Controlled**: Usa `open` + `onOpenChange` para control externo
+ *
+ * También soporta render props para acceder al estado del sidebar:
+ *
+ * @example
+ * ```tsx
+ * // Uso básico (children estáticos)
+ * <Sidebar defaultOpen={true} collapseMode="collapse">
+ *   <SidebarNav>
+ *     <SidebarToggle />
+ *     <SidebarContent>
+ *       <SidebarItem href="/" icon={<HomeIcon />} />
+ *     </SidebarContent>
+ *   </SidebarNav>
+ * </Sidebar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con render props (acceso al estado)
+ * <Sidebar>
+ *   {({ open, collapsed }) => (
+ *     <>
+ *       <SidebarNav className={cn(!open && 'hidden')}>
+ *         <SidebarContent>
+ *           <SidebarItem label={open ? "Home" : undefined} />
+ *         </SidebarContent>
+ *       </SidebarNav>
+ *       <div>Sidebar is {open ? 'open' : 'closed'}</div>
+ *     </>
+ *   )}
+ * </Sidebar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Modo controlled
+ * function App() {
+ *   const [open, setOpen] = useState(true)
+ *
+ *   return (
+ *     <Sidebar open={open} onOpenChange={setOpen}>
+ *       <SidebarNav>...</SidebarNav>
+ *     </Sidebar>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con configuración custom
+ * <Sidebar
+ *   collapseMode="hide"
+ *   dimensions={{ expandedWidth: "20rem" }}
+ *   animations={{ widthTransitionDuration: 500 }}
+ * >
+ *   <SidebarNav>...</SidebarNav>
+ * </Sidebar>
+ * ```
+ *
+ * @note
+ * Los colores se obtienen automáticamente de los tokens CSS de shadcn definidos
+ * en globals.css (--sidebar, --sidebar-accent, --sidebar-primary, etc.)
+ */
+declare function Sidebar({ children, className, style, defaultOpen, open, onOpenChange, collapseMode, hideBehaviour, hideOpensBehavior, layoutBehaviour, dimensions, animations, toggleId, debug, enableFluidIndicator, enableTooltip, liquidGlass, as, }: SidebarProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Componente de navegación del Sidebar
+ *
+ * @description
+ * Contenedor de navegación que renderiza un elemento `<nav>` por defecto.
+ * Gestiona los eventos de mouse y teclado para el indicador visual y
+ * la navegación accesible.
+ *
+ * Este componente:
+ * - Aplica data attributes para reflejar el estado (open/collapsed)
+ * - Gestiona eventos de mouse para el indicador visual
+ * - Gestiona navegación por teclado (arrows, home, end)
+ * - Expone una ref al elemento DOM para mediciones
+ *
+ * Usa forwardRef para permitir acceso al elemento DOM desde componentes padre.
+ *
+ * @example
+ * ```tsx
+ * <Sidebar>
+ *   <SidebarNav className="bg-zinc-900 border-zinc-800">
+ *     <SidebarToggle />
+ *     <SidebarIndicator />
+ *     <SidebarContent>
+ *       <SidebarItem href="/" />
+ *     </SidebarContent>
+ *   </SidebarNav>
+ * </Sidebar>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con data attributes para styling
+ * <SidebarNav className="data-[open=true]:w-64 data-[open=false]:w-16">
+ *   {children}
+ * </SidebarNav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con elemento personalizado
+ * <SidebarNav as="aside" aria-label="Navegación lateral">
+ *   {children}
+ * </SidebarNav>
+ * ```
+ */
+declare const SidebarNav: react.ForwardRefExoticComponent<SidebarNavProps & react.RefAttributes<HTMLElement>>;
+
+/**
+ * Componente de botón toggle del Sidebar
+ *
+ * @description
+ * Botón que controla el estado abierto/cerrado del sidebar.
+ * Renderiza un `<label>` por defecto que controla un checkbox oculto,
+ * permitiendo gestionar el estado con CSS puro (:checked selector).
+ *
+ * Características:
+ * - Soporta render props para acceso al estado (open, active)
+ * - Renderiza icono de chevron por defecto (customizable)
+ * - Aplica data attributes para styling CSS
+ * - Accesibilidad completa (aria-label, aria-expanded)
+ * - Soporta prop `as` para usar elemento/componente custom
+ *
+ * @example
+ * ```tsx
+ * // Uso básico con icono por defecto
+ * <SidebarToggle />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con render props para estado
+ * <SidebarToggle>
+ *   {({ open, active }) => (
+ *     <div className={cn(active && 'bg-blue-500')}>
+ *       {open ? <CloseIcon /> : <MenuIcon />}
+ *     </div>
+ *   )}
+ * </SidebarToggle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con icono custom
+ * <SidebarToggle className="bg-zinc-800">
+ *   <CustomChevronIcon />
+ * </SidebarToggle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Como botón real (sin checkbox)
+ * <SidebarToggle as="button" onClick={() => setOpen(!open)}>
+ *   Toggle
+ * </SidebarToggle>
+ * ```
+ */
+declare const SidebarToggle: react.ForwardRefExoticComponent<SidebarToggleProps & react.RefAttributes<HTMLButtonElement | HTMLLabelElement>>;
+
+/**
+ * Componente de contenido del Sidebar (contenedor de items)
+ *
+ * @description
+ * Contenedor que agrupa los items de navegación (SidebarItem).
+ * Renderiza un `<div>` por defecto y aplica estilos de layout flex.
+ *
+ * Este componente:
+ * - Registra su ref en el contexto para cálculos del indicador
+ * - Aplica rol ARIA "list" para accesibilidad
+ * - Centra y distribuye items verticalmente
+ * - Permite customización completa con className y style
+ *
+ * Los items dentro de este contenedor son utilizados por:
+ * - useSidebarIndicator: Para calcular posición del indicador
+ * - useSidebarKeyboard: Para navegación por teclado
+ *
+ * @example
+ * ```tsx
+ * <SidebarNav>
+ *   <SidebarContent>
+ *     <SidebarItem href="/" icon={<HomeIcon />} />
+ *     <SidebarItem href="/settings" icon={<SettingsIcon />} />
+ *   </SidebarContent>
+ * </SidebarNav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con estilos custom
+ * <SidebarContent className="gap-2 py-4">
+ *   <SidebarItem href="/" />
+ * </SidebarContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Como lista semántica
+ * <SidebarContent as="ul">
+ *   <SidebarItem as="li" href="/" />
+ * </SidebarContent>
+ * ```
+ */
+declare const SidebarContent: react.ForwardRefExoticComponent<SidebarContentProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Componente de indicador visual del Sidebar
+ *
+ * @description
+ * Indicador visual que sigue al cursor del mouse (o item enfocado) dentro
+ * del área de navegación. Proporciona feedback visual claro al usuario.
+ *
+ * Características:
+ * - Se muestra solo cuando el mouse está sobre el área de items
+ * - Sigue al cursor con animación suave
+ * - Se posiciona en el item enfocado al navegar por teclado
+ * - Totalmente customizable con className y style
+ * - Soporta render props para control total del contenido
+ * - Color y dimensiones configurables via contexto
+ *
+ * El indicador se oculta automáticamente cuando:
+ * - El mouse sale del sidebar
+ * - El cursor está fuera del área de items
+ * - Se pierde el focus del sidebar
+ *
+ * @example
+ * ```tsx
+ * // Uso básico con estilos por defecto
+ * <SidebarNav>
+ *   <SidebarIndicator />
+ *   <SidebarContent>...</SidebarContent>
+ * </SidebarNav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con estilos custom
+ * <SidebarIndicator className="bg-red-500 w-1" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con render props
+ * <SidebarIndicator>
+ *   {({ visible, position }) => (
+ *     <div
+ *       className={cn('indicator', visible && 'opacity-100')}
+ *       style={{ top: position }}
+ *     >
+ *       <span>→</span>
+ *     </div>
+ *   )}
+ * </SidebarIndicator>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Como elemento custom
+ * <SidebarIndicator as={motion.div} animate={{ opacity: 1 }} />
+ * ```
+ */
+declare const SidebarIndicator: react.ForwardRefExoticComponent<SidebarIndicatorProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Props del SidebarFluidIndicator
+ * @interface
+ */
+interface SidebarFluidIndicatorProps {
+    /** Elemento del item actualmente hovered/focused */
+    targetElement: HTMLElement | null;
+    /** Indica si el indicador está visible */
+    isVisible: boolean;
+}
+/**
+ * Componente wrapper de FluidHoverIndicator para Sidebar
+ *
+ * @description
+ * Wrapper que conecta el FluidHoverIndicator (glassmorphism + spring physics)
+ * con el sistema de estado del Sidebar. Este componente decide automáticamente
+ * qué versión renderizar basándose en las feature flags:
+ *
+ * - **V1 (default)**: FluidHoverIndicator con backdrop-blur CSS básico
+ * - **V2 (experimental)**: FluidHoverIndicatorV2 con SVG displacement mapping
+ *
+ * Feature flags del contexto:
+ * - `liquidGlass.enableLiquidGlassV2`: Activa la versión V2
+ * - `liquidGlass.enableChromaticAberration`: Activa chromatic aberration (Phase 2)
+ *
+ * @example
+ * ```tsx
+ * <SidebarNav>
+ *   <SidebarIndicator />
+ *   <SidebarFluidIndicator targetElement={currentItemElement} isVisible={isVisible} />
+ *   <SidebarContent>...</SidebarContent>
+ * </SidebarNav>
+ * ```
+ */
+declare function SidebarFluidIndicator({ targetElement, isVisible }: SidebarFluidIndicatorProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Componente de área segura del Sidebar
+ *
+ * @description
+ * Área reservada en la parte superior o inferior del sidebar para
+ * contenido especial como logos, usuario, configuración, etc.
+ *
+ * Las áreas seguras:
+ * - No contienen items de navegación
+ * - Tienen altura porcentual configurable
+ * - Pueden mostrar patrones de debug
+ * - Son completamente customizables
+ *
+ * Casos de uso comunes:
+ * - Top: Logo, título de la aplicación, búsqueda
+ * - Bottom: Usuario, configuración, logout
+ *
+ * @example
+ * ```tsx
+ * <SidebarNav>
+ *   <SidebarSafeArea position="top" percent={20}>
+ *     <img src="/logo.png" alt="Logo" />
+ *   </SidebarSafeArea>
+ *
+ *   <SidebarContent>
+ *     <SidebarItem href="/" />
+ *   </SidebarContent>
+ *
+ *   <SidebarSafeArea position="bottom" percent={15}>
+ *     <UserProfile />
+ *   </SidebarSafeArea>
+ * </SidebarNav>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con estilos custom
+ * <SidebarSafeArea
+ *   position="top"
+ *   className="bg-zinc-950 border-b border-zinc-800"
+ * >
+ *   <h1>Mi App</h1>
+ * </SidebarSafeArea>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Override de porcentaje
+ * <SidebarSafeArea position="bottom" percent={30}>
+ *   <ExtendedFooter />
+ * </SidebarSafeArea>
+ * ```
+ */
+declare const SidebarSafeArea: react.ForwardRefExoticComponent<SidebarSafeAreaProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Componente item de navegación del Sidebar
+ *
+ * @description
+ * Item individual de navegación dentro del sidebar.
+ * Renderiza un `<a>` por defecto, pero puede ser cualquier elemento
+ * o componente (ej: React Router Link, Next.js Link).
+ *
+ * Características:
+ * - Soporta iconos y labels
+ * - Gestiona estados de hover y focus
+ * - Se registra automáticamente para navegación por teclado
+ * - Aplica data attributes para styling
+ * - Soporta render props para control total
+ * - Compatible con React Router, Next.js, etc. via prop `as`
+ * - Label oculto automáticamente cuando sidebar está colapsado (via CSS container queries)
+ *
+ * @example
+ * ```tsx
+ * // Uso básico
+ * <SidebarItem
+ *   href="/"
+ *   icon={<HomeIcon />}
+ *   label="Home"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con React Router
+ * <SidebarItem
+ *   as={Link}
+ *   to="/dashboard"
+ *   icon={<DashboardIcon />}
+ *   label="Dashboard"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con Next.js Link
+ * <SidebarItem
+ *   LinkComponent={Link}
+ *   href="/profile"
+ *   icon={<UserIcon />}
+ *   label="Profile"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con render props
+ * <SidebarItem href="/settings">
+ *   {({ focused, hovered, disabled }) => (
+ *     <div className={cn(
+ *       'flex items-center gap-2',
+ *       focused && 'ring-2',
+ *       hovered && 'bg-zinc-800',
+ *       disabled && 'opacity-50'
+ *     )}>
+ *       <SettingsIcon />
+ *       <span>Settings</span>
+ *     </div>
+ *   )}
+ * </SidebarItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Con callbacks
+ * <SidebarItem
+ *   href="/analytics"
+ *   icon={<ChartIcon />}
+ *   label="Analytics"
+ *   onHover={() => prefetchAnalytics()}
+ *   onClick={() => trackNavigation('analytics')}
+ * />
+ * ```
+ */
+declare const SidebarItem: react.ForwardRefExoticComponent<SidebarItemProps & react.RefAttributes<HTMLAnchorElement>>;
+
+interface SidebarSubContentProps {
+    children: ReactNode;
+    title?: string;
+}
+declare function SidebarSubContent({ children, title }: SidebarSubContentProps): null;
+declare namespace SidebarSubContent {
+    var displayName: string;
+}
+
+interface SidebarSubLinkProps {
+    href: string;
+    children: ReactNode;
+    icon?: ReactNode;
+    LinkComponent?: ComponentType<any>;
+    linkProps?: Record<string, any>;
+    className?: string;
+    onClick?: (e: MouseEvent<HTMLAnchorElement>) => void;
+    animationOrder?: number;
+    animationState?: 'entering' | 'leaving' | 'static';
+    style?: CSSProperties;
+}
+declare function SidebarSubLink({ href, children, icon, LinkComponent, linkProps, className, onClick, animationOrder, animationState, style, }: SidebarSubLinkProps): react_jsx_runtime.JSX.Element;
+declare namespace SidebarSubLink {
+    var displayName: string;
+}
+
+interface SidebarTooltipProps {
+    /** Contenido del tooltip */
+    children: ReactNode;
+    /** Título opcional del tooltip */
+    title?: string;
+    /** Modo debug para visualizar safety triangle y layers */
+    debug?: boolean;
+    /** Handler llamado cuando el mouse sale del tooltip */
+    onMouseLeave?: () => void;
+    /** Habilitar liquid glass con SVG displacement filters (false = backdrop-blur básico) */
+    enableLiquidGlass?: boolean;
+    /** Habilitar Edge Glass 3D (dual backdrop layers para profundidad) */
+    enableEdgeGlass3D?: boolean;
+    /** Habilitar Backdrop Extension (Josh Comeau technique - 200% height) */
+    enableBackdropExtension?: boolean;
+    /** Habilitar chromatic aberration RGB (requiere enableLiquidGlass) */
+    enableChromaticAberration?: boolean;
+    /** Habilitar animaciones staggered de items (entrada/salida escalonada) */
+    enableTooltipItemAnimations?: boolean;
+    /** Habilitar animación 3D de cilindro para el título del tooltip */
+    enableCylinderTitle?: boolean;
+}
+declare const SidebarTooltip: react.NamedExoticComponent<SidebarTooltipProps>;
+
+/**
+ * Hook para acceder al contexto del Sidebar
+ *
+ * @description
+ * Hook personalizado que provee acceso al contexto compartido del Sidebar.
+ * Debe ser utilizado dentro de un componente que esté envuelto por
+ * `<Sidebar>` o `<SidebarProvider>`.
+ *
+ * Lanza un error si se utiliza fuera del contexto apropiado, ayudando
+ * a detectar problemas de composición durante el desarrollo.
+ *
+ * @throws {Error} Si se usa fuera de un SidebarProvider
+ *
+ * @returns {SidebarContextValue} El valor del contexto del sidebar
+ *
+ * @example
+ * ```tsx
+ * function CustomToggle() {
+ *   const { open, setOpen } = useSidebarContext()
+ *
+ *   return (
+ *     <button onClick={() => setOpen(!open)}>
+ *       {open ? 'Cerrar' : 'Abrir'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Acceder a configuración
+ * function CustomItem() {
+ *   const { colors, dimensions } = useSidebarContext()
+ *
+ *   return (
+ *     <div style={{
+ *       background: colors.hover,
+ *       width: dimensions.expandedWidth
+ *     }}>
+ *       Item
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useSidebarContext(): SidebarContextValue;
+
+/**
+ * Valor de retorno del hook useSidebarKeyboard
+ * @interface
+ */
+interface UseSidebarKeyboardReturn {
+    /** Índice del item actualmente enfocado (-1 si ninguno) */
+    focusedIndex: number;
+    /** Función para cambiar el índice enfocado manualmente */
+    setFocusedIndex: (index: number) => void;
+    /** Callback para actualizar el indicador según el item enfocado */
+    updateIndicatorForFocus: (index: number) => void;
+}
+/**
+ * Hook para gestionar la navegación por teclado en el Sidebar
+ *
+ * @description
+ * Hook que implementa navegación accesible por teclado para los items
+ * del sidebar, siguiendo las especificaciones WAI-ARIA:
+ *
+ * - ArrowDown: Navegar al siguiente item
+ * - ArrowUp: Navegar al item anterior
+ * - Home: Ir al primer item
+ * - End: Ir al último item
+ * - Tab: Navegación estándar que actualiza el indicador
+ *
+ * También sincroniza el indicador visual con el item enfocado.
+ *
+ * @returns {UseSidebarKeyboardReturn} Estado y funciones para navegación
+ *
+ * @example
+ * ```tsx
+ * function SidebarNav() {
+ *   const { focusedIndex, updateIndicatorForFocus } = useSidebarKeyboard()
+ *
+ *   return (
+ *     <nav>
+ *       {items.map((item, index) => (
+ *         <SidebarItem
+ *           key={item.id}
+ *           focused={index === focusedIndex}
+ *           onFocus={() => updateIndicatorForFocus(index)}
+ *         />
+ *       ))}
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+declare function useSidebarKeyboard(): UseSidebarKeyboardReturn;
+
+/**
+ * Valor de retorno del hook useSidebarIndicator
+ * @interface
+ */
+interface UseSidebarIndicatorReturn {
+    /** Indica si el indicador está visible */
+    isVisible: boolean;
+    /** Indica si el mouse está sobre el área de items */
+    isOverItems: boolean;
+    /** Elemento del item actualmente hovered o enfocado (para FluidHoverIndicator) */
+    currentItemElement: HTMLElement | null;
+    /** ID del item bajo el indicador (para tooltip con subContent) */
+    hoveredItemId: string | null;
+    /** Label del item hovered (para tooltip simple) */
+    hoveredLabel: string | null;
+    /** Manejador de evento mousemove */
+    handleMouseMove: (e: MouseEvent<HTMLDivElement>) => void;
+    /** Manejador de evento mouseenter */
+    handleMouseEnter: () => void;
+    /** Manejador de evento mouseleave */
+    handleMouseLeave: () => void;
+    /** Manejador de evento focus */
+    handleFocus: () => void;
+    /** Manejador de evento blur */
+    handleBlur: (e: React.FocusEvent) => void;
+    /** Función para limpiar el estado hovered desde fuera (tooltip mouseleave) */
+    clearHoveredState: () => void;
+}
+/**
+ * Hook para gestionar el indicador visual del Sidebar
+ *
+ * @description
+ * Hook que implementa la lógica del indicador visual que sigue al cursor
+ * del mouse dentro del sidebar. El indicador se muestra cuando:
+ * - El mouse está sobre el sidebar (isHovering = true)
+ * - El cursor está en el área de items (isOverItems = true)
+ *
+ * Utiliza requestAnimationFrame para optimizar el rendimiento y evitar
+ * cálculos excesivos durante el movimiento del mouse.
+ *
+ * El indicador también se actualiza cuando se navega por teclado,
+ * integrándose con useSidebarKeyboard.
+ *
+ * @returns {UseSidebarIndicatorReturn} Estado y manejadores de eventos
+ *
+ * @example
+ * ```tsx
+ * function SidebarNav() {
+ *   const {
+ *     isVisible,
+ *     handleMouseMove,
+ *     handleMouseEnter,
+ *     handleMouseLeave
+ *   } = useSidebarIndicator()
+ *
+ *   return (
+ *     <nav
+ *       onMouseMove={handleMouseMove}
+ *       onMouseEnter={handleMouseEnter}
+ *       onMouseLeave={handleMouseLeave}
+ *     >
+ *       <SidebarIndicator visible={isVisible} />
+ *       {children}
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+declare function useSidebarIndicator(): UseSidebarIndicatorReturn;
+
+interface SubContentData {
+    itemId: string;
+    subContent: ReactNode;
+    title?: string;
+}
+
+declare function useSubContent(): {
+    subContentMap: Map<string, SubContentData>;
+    registerSubContent: (itemId: string, data: SubContentData) => void;
+    unregisterSubContent: (itemId: string) => void;
+    getSubContent: (itemId: string) => SubContentData | undefined;
+};
+
+/**
+ * Dimensiones por defecto del sidebar
+ * @constant
+ */
+declare const DEFAULT_DIMENSIONS: SidebarDimensions;
+/**
+ * Áreas seguras por defecto
+ * @constant
+ */
+declare const DEFAULT_SAFE_AREAS: SidebarSafeAreas;
+/**
+ * Animaciones por defecto
+ * @constant
+ */
+declare const DEFAULT_ANIMATIONS: SidebarAnimations;
+/**
+ * Configuración por defecto del sidebar
+ * @constant
+ *
+ * @description
+ * Los colores se obtienen automáticamente de los tokens CSS de shadcn:
+ * - --sidebar: Color de fondo
+ * - --sidebar-foreground: Color de texto
+ * - --sidebar-primary: Color primario (indicador)
+ * - --sidebar-accent: Color de hover
+ * - --sidebar-border: Color de bordes
+ */
+declare const DEFAULT_CONFIG: SidebarConfig;
+/**
+ * Teclas de navegación del sidebar
+ * @constant
+ */
+declare const SIDEBAR_KEYBOARD_KEYS: {
+    /** Flecha abajo - navegar al siguiente item */
+    readonly ARROW_DOWN: "ArrowDown";
+    /** Flecha arriba - navegar al item anterior */
+    readonly ARROW_UP: "ArrowUp";
+    /** Home - ir al primer item */
+    readonly HOME: "Home";
+    /** End - ir al último item */
+    readonly END: "End";
+    /** Tab - navegación estándar */
+    readonly TAB: "Tab";
+    /** Escape - cerrar sidebar o quitar focus */
+    readonly ESCAPE: "Escape";
+};
+/**
+ * Atributos data-* para styling CSS y selección de elementos
+ * @constant
+ */
+declare const SIDEBAR_DATA_ATTRIBUTES: {
+    /** data-open - indica si el sidebar está abierto */
+    readonly OPEN: "data-open";
+    /** data-collapsed - indica si el sidebar está colapsado */
+    readonly COLLAPSED: "data-collapsed";
+    /** data-focused - indica si un elemento está enfocado */
+    readonly FOCUSED: "data-focused";
+    /** data-hovered - indica si el mouse está sobre un elemento */
+    readonly HOVERED: "data-hovered";
+    /** data-disabled - indica si un elemento está deshabilitado */
+    readonly DISABLED: "data-disabled";
+    /** data-sidebar-item - marca un item del sidebar para navegación */
+    readonly ITEM: "data-sidebar-item";
+    /** data-active - indica si un toggle/botón está activo */
+    readonly ACTIVE: "data-active";
+    /** data-visible - indica si un elemento es visible */
+    readonly VISIBLE: "data-visible";
+};
+/**
+ * Clases Tailwind reutilizables para componentes del sidebar
+ * @constant
+ */
+declare const SIDEBAR_TAILWIND_CLASSES: {
+    /** Clases base para el wrapper */
+    readonly wrapper: "relative";
+    /** Clases base para el nav */
+    readonly nav: "relative h-screen border-r";
+    /** Clases base para el indicador */
+    readonly indicator: "absolute left-0 rounded-r-full pointer-events-none";
+    /** Clases base para el botón toggle */
+    readonly toggleButton: "block w-6 h-6 rounded-full cursor-pointer flex items-center justify-center transition-colors";
+    /** Clases para el wrapper del botón toggle */
+    readonly toggleButtonWrapper: "absolute top-6 z-30";
+    /** Clases base para el contenedor de items */
+    readonly content: "flex flex-col items-center";
+    /** Clases base para áreas seguras */
+    readonly safeArea: "flex items-center justify-center";
+    /** Clases de borde debug */
+    readonly debugBorder: "border-dashed";
+    /** Clases de focus ring (accesibilidad) */
+    readonly focusRing: "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2";
+    /** Clases SR-only (screen reader only) */
+    readonly srOnly: "sr-only";
+};
+/**
+ * Patrones visuales para modo debug
+ * @constant
+ */
+declare const SIDEBAR_DEBUG_PATTERNS: {
+    /** Patrón de rayas para áreas seguras */
+    readonly safeArea: "repeating-linear-gradient(45deg, transparent, transparent 10px, rgba(255,255,255,0.03) 10px, rgba(255,255,255,0.03) 20px)";
+    /** Fondo semi-transparente para área de contenido */
+    readonly contentArea: "rgba(0, 0, 0, 0.5)";
+    /** Color de borde para debug */
+    readonly borderColor: "rgb(34 197 94)";
+    /** Opacidad de borde debug */
+    readonly borderOpacity: "0.3";
+};
+/**
+ * Roles ARIA para accesibilidad
+ * @constant
+ */
+declare const SIDEBAR_ARIA_ROLES: {
+    /** Rol para el nav principal */
+    readonly navigation: "navigation";
+    /** Rol para lista de items */
+    readonly list: "list";
+    /** Rol para item individual */
+    readonly listitem: "listitem";
+    /** Rol para botón toggle */
+    readonly button: "button";
+};
+/**
+ * Labels ARIA por defecto para accesibilidad
+ * @constant
+ */
+declare const SIDEBAR_ARIA_LABELS: {
+    /** Label para toggle */
+    readonly toggleSidebar: "Alternar sidebar";
+    /** Label para navegación principal */
+    readonly mainNavigation: "Navegación principal";
+    /** Label cuando sidebar está abierto */
+    readonly sidebarOpen: "Sidebar abierto";
+    /** Label cuando sidebar está cerrado */
+    readonly sidebarClosed: "Sidebar cerrado";
+};
+/**
+ * Configuración de estilo visual por defecto del sidebar
+ * @constant
+ */
+declare const DEFAULT_VISUAL_STYLE: {
+    readonly marginTop: "0";
+    readonly marginBottom: "0";
+    readonly marginLeft: "0";
+    readonly marginRight: "0";
+    readonly height: "100vh";
+    readonly borderRadius: "0";
+    readonly boxShadow: "none";
+};
+/**
+ * Preconfiguraciones de estilo visual para el sidebar
+ * @constant
+ */
+declare const SIDEBAR_VISUAL_PRESETS: {
+    /** Estilo por defecto: pegado a bordes */
+    readonly DEFAULT: {
+        readonly marginTop: "0";
+        readonly marginBottom: "0";
+        readonly marginLeft: "0";
+        readonly marginRight: "0";
+        readonly height: "100vh";
+        readonly borderRadius: "0";
+        readonly boxShadow: "none";
+    };
+    /** Estilo floating: separado y con sombra */
+    readonly FLOATING_CARD: {
+        readonly marginTop: "1rem";
+        readonly marginBottom: "1rem";
+        readonly marginLeft: "1rem";
+        readonly marginRight: "0";
+        readonly height: "calc(100vh - 2rem)";
+        readonly borderRadius: "0.75rem";
+        readonly boxShadow: "0 10px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)";
+    };
+    /** Estilo moderno: esquinas redondeadas suaves */
+    readonly MODERN_ROUNDED: {
+        readonly marginTop: "0.5rem";
+        readonly marginBottom: "0.5rem";
+        readonly marginLeft: "0.5rem";
+        readonly marginRight: "0";
+        readonly height: "calc(100vh - 1rem)";
+        readonly borderRadius: "1rem";
+        readonly boxShadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)";
+    };
+    /** Estilo minimal: ligera separación */
+    readonly MINIMAL_SPACED: {
+        readonly marginTop: "0.25rem";
+        readonly marginBottom: "0.25rem";
+        readonly marginLeft: "0.25rem";
+        readonly marginRight: "0";
+        readonly height: "calc(100vh - 0.5rem)";
+        readonly borderRadius: "0.5rem";
+        readonly boxShadow: "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)";
+    };
+};
+/**
+ * Tipo para los presets de estilo visual
+ */
+type SidebarVisualPreset = keyof typeof SIDEBAR_VISUAL_PRESETS;
+/**
+ * Breakpoints para responsive behavior
+ * @constant
+ */
+declare const SIDEBAR_BREAKPOINTS: {
+    /** Ancho mínimo para mostrar sidebar expandido */
+    readonly minExpandedWidth: 768;
+    /** Ancho mínimo para sidebar colapsado */
+    readonly minCollapsedWidth: 640;
+    /** Ancho para forzar modo mobile */
+    readonly mobileWidth: 480;
+};
+/**
+ * Límites y valores seguros para validación
+ * @constant
+ */
+declare const SIDEBAR_LIMITS: {
+    /** Porcentaje mínimo para safe area */
+    readonly minSafeAreaPercent: 0;
+    /** Porcentaje máximo para safe area */
+    readonly maxSafeAreaPercent: 50;
+    /** Número máximo de items recomendado */
+    readonly maxRecommendedItems: 20;
+    /** Duración mínima de transición (ms) */
+    readonly minTransitionDuration: 0;
+    /** Duración máxima de transición (ms) */
+    readonly maxTransitionDuration: 1000;
+};
+/**
+ * Nombres de CSS variables utilizadas
+ * @constant
+ */
+declare const SIDEBAR_CSS_VARIABLES: {
+    /** Ancho cuando cerrado */
+    readonly widthClosed: "--sidebar-width-closed";
+    /** Ancho cuando abierto */
+    readonly widthOpen: "--sidebar-width-open";
+    /** Ancho actual */
+    readonly width: "--sidebar-width";
+    /** Color de fondo */
+    readonly background: "--sidebar-bg";
+    /** Color de borde (variable interna para evitar colisión con --sidebar-border de shadcn) */
+    readonly borderColor: "--sidebar-border-color";
+    /** Color de hover */
+    readonly hover: "--sidebar-hover";
+    /** Color del indicador */
+    readonly indicator: "--sidebar-indicator";
+    /** Altura del indicador */
+    readonly indicatorHeight: "--sidebar-indicator-height";
+    /** Distancia del tooltip al sidebar */
+    readonly tooltipDistance: "--sidebar-tooltip-distance";
+    /** Comportamiento de layout */
+    readonly layoutBehaviour: "--sidebar-layout-behaviour";
+    /** Flag para modo inline */
+    readonly isInline: "--sidebar-is-inline";
+    /** Variables de estilo visual */
+    readonly marginTop: "--sidebar-margin-top";
+    readonly marginBottom: "--sidebar-margin-bottom";
+    readonly marginLeft: "--sidebar-margin-left";
+    readonly marginRight: "--sidebar-margin-right";
+    readonly sidebarHeight: "--sidebar-height";
+    readonly sidebarBorderRadius: "--sidebar-border-radius";
+    readonly sidebarBoxShadow: "--sidebar-box-shadow";
+};
+
+/**
+ * Configuración para el generador de estilos
+ * @interface
+ */
+interface StyleGeneratorConfig {
+    dimensions: SidebarDimensions;
+    animations: SidebarAnimations;
+    collapseMode: SidebarCollapseMode;
+    hideOpensBehavior: SidebarHideOpensBehavior;
+    layoutBehaviour: SidebarLayoutBehaviour;
+    visualStyle: SidebarVisualStyle;
+}
+/**
+ * Genera los estilos CSS del sidebar usando CSS-in-JS y tokens de shadcn
+ *
+ * @description
+ * Función que genera todo el CSS necesario para el sidebar,
+ * utilizando los tokens CSS de shadcn definidos en globals.css:
+ *
+ * **Tokens utilizados:**
+ * - `--sidebar`: Color de fondo
+ * - `--sidebar-foreground`: Color de texto
+ * - `--sidebar-primary`: Color primario (indicador, elementos activos)
+ * - `--sidebar-accent`: Color de hover y estados secundarios
+ * - `--sidebar-border`: Color de bordes
+ * - `--sidebar-ring`: Color de focus ring (accesibilidad)
+ *
+ * Usa CSS Layers para organización y control de especificidad:
+ * - sidebar-base: Variables y estilos base
+ * - sidebar-states: Estados (:checked, :hover, etc.)
+ * - sidebar-animations: Transiciones y animaciones
+ *
+ * @param {StyleGeneratorConfig} config - Configuración de dimensiones y animaciones
+ * @returns {string} String con el CSS completo
+ *
+ * @example
+ * ```tsx
+ * const styles = generateSidebarStyles({
+ *   dimensions: DEFAULT_DIMENSIONS,
+ *   animations: DEFAULT_ANIMATIONS,
+ *   collapseMode: SidebarCollapseMode.COLLAPSE,
+ *   hideOpensBehavior: SidebarHideOpensBehavior.COLLAPSED
+ * })
+ *
+ * <style jsx>{styles}</style>
+ * ```
+ *
+ * @note
+ * Los colores NO se configuran aquí, se obtienen automáticamente de los tokens
+ * CSS de shadcn. Esto permite soporte automático para dark/light mode.
+ */
+declare function generateSidebarStyles({ dimensions, animations, collapseMode, hideOpensBehavior, layoutBehaviour, visualStyle, }: StyleGeneratorConfig): string;
+/**
+ * Genera estilos para el indicador visual usando tokens CSS
+ *
+ * @description
+ * Función auxiliar para generar estilos dinámicos del indicador.
+ * Útil para aplicar estilos inline con estado reactivo.
+ *
+ * Utiliza el token `--sidebar-primary` para el color del indicador,
+ * asegurando consistencia con el theme del sidebar.
+ *
+ * @param {boolean} isVisible - Si el indicador está visible
+ * @returns {React.CSSProperties} Objeto de estilos inline
+ *
+ * @example
+ * ```tsx
+ * const indicatorStyles = generateIndicatorStyles(isHovering && isOverItems)
+ *
+ * <div style={indicatorStyles} />
+ * ```
+ */
+declare function generateIndicatorStyles(isVisible: boolean): React.CSSProperties;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+export { DEFAULT_ANIMATIONS, DEFAULT_CONFIG, DEFAULT_DIMENSIONS, DEFAULT_SAFE_AREAS, DEFAULT_VISUAL_STYLE, SIDEBAR_ARIA_LABELS, SIDEBAR_ARIA_ROLES, SIDEBAR_BREAKPOINTS, SIDEBAR_CSS_VARIABLES, SIDEBAR_DATA_ATTRIBUTES, SIDEBAR_DEBUG_PATTERNS, SIDEBAR_KEYBOARD_KEYS, SIDEBAR_LIMITS, SIDEBAR_TAILWIND_CLASSES, SIDEBAR_VISUAL_PRESETS, Sidebar, type SidebarAnimations, SidebarBorderRadius, SidebarCollapseMode, type SidebarConfig, SidebarContent, type SidebarContentProps, type SidebarContextValue, type SidebarDimensions, SidebarFluidIndicator, SidebarHideBehaviour, SidebarHideOpensBehavior, SidebarIconLibrary, SidebarIndicator, type SidebarIndicatorProps, type SidebarIndicatorRenderProp, type SidebarIndicatorState, SidebarItem, type SidebarItemProps, type SidebarItemRenderProp, type SidebarItemState, SidebarLayoutBehaviour, SidebarNav, type SidebarNavProps, type SidebarProps, type SidebarRenderProp, SidebarSafeArea, SidebarSafeAreaPosition, type SidebarSafeAreaProps, type SidebarSafeAreas, type SidebarState, SidebarSubContent, type SidebarSubContentProps, SidebarSubLink, type SidebarSubLinkProps, SidebarTimingFunction, SidebarToggle, type SidebarToggleProps, type SidebarToggleRenderProp, type SidebarToggleState, SidebarTooltip, type SidebarTooltipProps, SidebarTransitionDuration, type SidebarVisualPreset, type SidebarVisualStyle, SidebarWidth, SidebarZIndex, cn, generateIndicatorStyles, generateSidebarStyles, useSidebarContext, useSidebarIndicator, useSidebarKeyboard, useSubContent };