@ceedcv-maya/shared-layout-react 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maya-AQSS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @ceedcv-maya/shared-layout-react
+
+App layout primitives for React: AppShell, useDarkMode, Sidebar slot, header/topbar widgets — wired to shared-auth/UI by props.
+
+Part of the [ceedcv-maya/maya_platform](https://github.com/Maya-AQSS/maya_platform) mono-repo. Distributed independently for reuse outside the Maya ecosystem.
+
+## Installation
+
+```bash
+npm install @ceedcv-maya/shared-layout-react @ceedcv-maya/shared-auth-react @ceedcv-maya/shared-ui-react
+```
+
+```tsx
+import { AppShell, useDarkMode } from '@ceedcv-maya/shared-layout-react'
+
+export function Layout({ children }) {
+  return <AppShell sidebar={<MySidebar />} topbar={<MyTopbar />}>{children}</AppShell>
+}
+```
+
+
+## Peer dependencies
+
+This package expects the following sibling packages to be installed by the consumer:
+
+- `@ceedcv-maya/shared-auth-react`
+- `@ceedcv-maya/shared-ui-react`
+
+## TypeScript / build notes
+This package ships TypeScript source (`src/index.ts` as entry). Consumers using Vite or Webpack with `ts-loader` work out of the box. Next.js consumers must add this package to `transpilePackages` in `next.config.js`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Reporting issues
+
+The canonical source lives in [Maya-AQSS/maya_platform](https://github.com/Maya-AQSS/maya_platform). File issues there; this read-only split repo is only the published artifact.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@ceedcv-maya/shared-layout-react",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0",
+    "react-i18next": "^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0",
+    "@ceedcv-maya/shared-auth-react": "^0.2.0",
+    "@ceedcv-maya/shared-ui-react": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.0.0",
+    "react-i18next": "^17.0.0",
+    "i18next": "^26.0.0",
+    "@types/react-router-dom": "^5.3.3"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "test": "echo \"no tests yet\" && exit 0",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"no linter configured\""
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maya-AQSS/maya_platform.git",
+    "directory": "packages/js/shared-layout-react"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "App layout primitives for React: AppShell, useDarkMode, Sidebar slot, header/topbar widgets \u2014 wired to shared-auth/UI by props.",
+  "keywords": [
+    "react",
+    "layout",
+    "appshell",
+    "sidebar",
+    "darkmode",
+    "ceedcv",
+    "maya"
+  ],
+  "author": {
+    "name": "CEEDCV",
+    "email": "info@ceedcv.es",
+    "homepage": "https://ceedcv.es"
+  },
+  "homepage": "https://github.com/Maya-AQSS/shared-layout-react#readme",
+  "bugs": {
+    "url": "https://github.com/Maya-AQSS/maya_platform/issues"
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "tsconfig.json"
+  ]
+}

package/src/AppLayout.tsx

@@ -0,0 +1,135 @@
+import type { ReactNode } from 'react'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Outlet } from 'react-router-dom'
+import { Sidebar } from './Sidebar'
+import { useDarkMode } from './useDarkMode'
+import { HamburgerIcon } from './navIcons'
+import type { NavItem } from './types'
+
+type AppLayoutProps = {
+  navItems: NavItem[]
+  brandName: string
+  brandVersion?: string
+  /** Imagen del logo de la app (opcional). Si no se aporta, usa logo Maya. */
+  brandLogoUrl?: string
+
+  // Datos de usuario (van al fondo del sidebar)
+  userName: string
+  userEmail?: string
+  userInitials: string
+  userAvatarUrl?: string | null
+  onLogout: () => void
+  onProfile?: () => void
+
+  // Slots opcionales en el footer del sidebar
+  /** Bloque de favoritos (típicamente <SidebarFavorites />). */
+  favoritesSlot?: ReactNode
+  /** Notificaciones (típicamente <NotificationsBell />). */
+  notificationsSlot?: ReactNode
+
+  /** Si se aporta, renderiza children en lugar de <Outlet />. */
+  children?: ReactNode
+}
+
+/**
+ * Layout principal Maya — versión 2026 sin Topbar.
+ * - Sidebar con brand, nav, y footer apilado (favoritos / notificaciones / usuario).
+ * - El contenido principal renderiza directamente las rutas; cada página gestiona
+ *   su propio `<PageTitle>` (sin header global).
+ * - Toggle de tema, perfil y logout viven en el SidebarUserBlock al fondo del sidebar.
+ *
+ * Skip-link `#main-content` para WCAG 2.4.1 (Bypass Blocks).
+ */
+export function AppLayout({
+  navItems,
+  brandName,
+  brandVersion,
+  brandLogoUrl,
+  userName,
+  userEmail,
+  userInitials,
+  userAvatarUrl,
+  onLogout,
+  onProfile,
+  favoritesSlot,
+  notificationsSlot,
+  children,
+}: AppLayoutProps) {
+  const { t } = useTranslation('common')
+  const { isDark, toggle: handleToggleDark } = useDarkMode()
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false)
+  const [mobileOpen, setMobileOpen] = useState(false)
+
+  // Exponemos el ancho efectivo del sidebar como CSS variable para que
+  // overlays/modales descendientes puedan posicionarse al lado del aside
+  // sin cubrirlo. Se actualiza con la transición y respeta el modo móvil.
+  const sidebarWidthDesktop = sidebarCollapsed ? '4.25rem' : '17rem'
+
+  return (
+    <div
+      className="min-h-screen bg-app-gradient font-sans"
+      style={{ ['--sidebar-w' as string]: sidebarWidthDesktop }}
+    >
+      {/* Skip-link: visible solo al recibir foco con Tab. WCAG 2.4.1. */}
+      <a
+        href="#main-content"
+        className="
+          sr-only focus:not-sr-only
+          focus:fixed focus:top-2 focus:left-2 focus:z-[var(--z-index-toast,500)]
+          focus:px-3 focus:py-2 focus:rounded-md
+          focus:bg-gradient-primary focus:text-text-inverse
+          focus:shadow-card-md focus:outline-none focus:ring-2 focus:ring-odoo-purple/35
+          text-sm font-semibold
+        "
+      >
+        {t('layout.skipToContent', { defaultValue: 'Skip to main content' })}
+      </a>
+
+      <Sidebar
+        navItems={navItems}
+        brandName={brandName}
+        brandVersion={brandVersion}
+        brandLogoUrl={brandLogoUrl}
+        collapsed={sidebarCollapsed}
+        onToggle={() => setSidebarCollapsed((prev) => !prev)}
+        mobileOpen={mobileOpen}
+        onMobileClose={() => setMobileOpen(false)}
+        favoritesSlot={favoritesSlot}
+        notificationsSlot={notificationsSlot}
+        userName={userName}
+        userEmail={userEmail}
+        userInitials={userInitials}
+        userAvatarUrl={userAvatarUrl}
+        onLogout={onLogout}
+        onProfile={onProfile}
+        isDark={isDark}
+        onToggleDark={handleToggleDark}
+      />
+
+      {/* Botón hamburguesa flotante en móvil (sin topbar). */}
+      <button
+        type="button"
+        onClick={() => setMobileOpen(true)}
+        aria-label={t('layout.openSidebarMenu', { defaultValue: 'Open side menu' })}
+        className="md:hidden fixed top-4 left-4 z-[90] inline-flex items-center justify-center w-10 h-10 rounded-full bg-gradient-primary text-text-inverse shadow-[0_4px_14px_-4px_rgba(113,75,103,0.55)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-odoo-purple/35"
+      >
+        <HamburgerIcon />
+      </button>
+
+      <div
+        className={`flex flex-col min-h-screen transition-[margin] duration-200 ${
+          sidebarCollapsed ? 'md:ml-[4.25rem]' : 'md:ml-[17rem]'
+        }`}
+      >
+        <main
+          id="main-content"
+          tabIndex={-1}
+          className="flex-1 p-4 sm:p-6 md:p-8 overflow-x-clip focus-visible:outline-none"
+        >
+          {children ?? <Outlet />}
+        </main>
+      </div>
+    </div>
+  )
+}

package/src/MayaLogoIcon.tsx

@@ -0,0 +1,30 @@
+/**
+ * Logo Maya por defecto — círculo con gradiente y "M" en blanco.
+ * Sirve como fallback cuando el consumidor no aporta `brandLogoUrl`.
+ */
+export function MayaLogoIcon({ size = 32 }: { size?: number }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 32 32"
+      role="img"
+      aria-label="Maya"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <defs>
+        <linearGradient id="maya-logo-grad" x1="0%" y1="0%" x2="100%" y2="100%">
+          <stop offset="0%" stopColor="#714B67" />
+          <stop offset="55%" stopColor="#5A3A52" />
+          <stop offset="100%" stopColor="#017E84" />
+        </linearGradient>
+      </defs>
+      <rect x="0" y="0" width="32" height="32" rx="9" fill="url(#maya-logo-grad)" />
+      <path
+        d="M8.5 22.5V10.5h2.6l4.4 7.6 4.4-7.6h2.6v12h-2.4v-7.5l-3.6 6.1h-2l-3.6-6.1v7.5z"
+        fill="#FFFFFF"
+        fillOpacity="0.96"
+      />
+    </svg>
+  )
+}

package/src/Sidebar.tsx

@@ -0,0 +1,226 @@
+import type { ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+import { NavLink } from 'react-router-dom'
+import { SidebarUserBlock } from './SidebarUserBlock'
+import { MayaLogoIcon } from './MayaLogoIcon'
+import { SidebarCollapsedProvider } from './SidebarCollapsedContext'
+import type { NavItem } from './types'
+
+interface SidebarProps {
+  navItems: NavItem[]
+  brandName: string
+  brandVersion?: string
+  /** URL de imagen del logo. Si no se aporta, se usa `<MayaLogoIcon />`. */
+  brandLogoUrl?: string
+  collapsed: boolean
+  onToggle: () => void
+  mobileOpen: boolean
+  onMobileClose: () => void
+
+  // Footer en orden vertical: favoritos → user block
+  favoritesSlot?: ReactNode
+  /** Notificaciones — se ubican en el header (top-right). */
+  notificationsSlot?: ReactNode
+
+  // Datos para el bloque de usuario
+  userName: string
+  userEmail?: string
+  userInitials: string
+  userAvatarUrl?: string | null
+  onLogout: () => void
+  onProfile?: () => void
+
+  // Toggle dark mode (movido del Topbar al UserBlock)
+  isDark: boolean
+  onToggleDark: () => void
+}
+
+function ChevronIcon({ collapsed }: { collapsed: boolean }) {
+  return (
+    <svg
+      className={`w-3.5 h-3.5 transition-transform duration-200 ${collapsed ? 'rotate-180' : ''}`}
+      fill="none"
+      stroke="currentColor"
+      viewBox="0 0 24 24"
+      aria-hidden="true"
+    >
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2.5} d="M15 19l-7-7 7-7" />
+    </svg>
+  )
+}
+
+export function Sidebar({
+  navItems,
+  brandName,
+  brandVersion,
+  brandLogoUrl,
+  collapsed,
+  onToggle,
+  mobileOpen,
+  onMobileClose,
+  favoritesSlot,
+  notificationsSlot,
+  userName,
+  userEmail,
+  userInitials,
+  userAvatarUrl,
+  onLogout,
+  onProfile,
+  isDark,
+  onToggleDark,
+}: SidebarProps) {
+  const { t } = useTranslation('common')
+  const effectiveCollapsed = collapsed && !mobileOpen
+
+  return (
+    <>
+      {mobileOpen && (
+        <div
+          className="fixed inset-0 bg-black/50 z-[99] md:hidden"
+          onClick={onMobileClose}
+          aria-hidden="true"
+        />
+      )}
+
+      <aside
+        className={[
+          'fixed inset-y-0 left-0 bg-sidebar-gradient text-text-inverse',
+          'flex flex-col z-[100] border-r border-text-inverse/8',
+          mobileOpen
+            ? 'translate-x-0 pointer-events-auto'
+            : '-translate-x-full md:translate-x-0 pointer-events-none md:pointer-events-auto',
+        ].join(' ')}
+        style={{
+          width: effectiveCollapsed ? '4.25rem' : '17rem',
+          transition: 'width 200ms ease, transform 200ms ease',
+        }}
+      >
+        {/* ── Header: logo + brand + (notificaciones top-right) ── */}
+        <div
+          className={[
+            'h-16 flex items-center border-b border-text-inverse/8 shrink-0',
+            effectiveCollapsed ? 'justify-center px-2' : 'gap-2.5 px-4',
+          ].join(' ')}
+        >
+          <span className="shrink-0 flex items-center justify-center">
+            {brandLogoUrl ? (
+              <img
+                src={brandLogoUrl}
+                alt={brandName}
+                className="w-9 h-9 object-contain"
+              />
+            ) : (
+              <MayaLogoIcon size={36} />
+            )}
+          </span>
+
+          {!effectiveCollapsed && (
+            <span className="flex-1 min-w-0 text-base font-display font-bold text-text-inverse tracking-wide truncate">
+              {brandName}
+            </span>
+          )}
+
+          {!effectiveCollapsed && notificationsSlot ? (
+            <div className="shrink-0 ml-auto flex items-center">
+              {notificationsSlot}
+            </div>
+          ) : null}
+        </div>
+
+        {/* Notificaciones flotantes (solo cuando el sidebar está colapsado en
+            desktop). Se ubican a la derecha del sidebar para no taparlo.
+            Estilo oscuro tipo sidebar para diferenciarse del fondo claro. */}
+        {notificationsSlot && effectiveCollapsed ? (
+          <div
+            className="hidden md:flex fixed top-3 z-[101] items-center justify-center w-11 h-11 rounded-full bg-sidebar-gradient text-text-inverse border border-text-inverse/10 shadow-[0_8px_22px_-8px_rgba(0,0,0,0.45)]"
+            style={{ left: 'calc(4.25rem + 0.75rem)' }}
+          >
+            {notificationsSlot}
+          </div>
+        ) : null}
+
+        {/* ── Nav: items + favoritos en línea ── */}
+        <nav className="flex-1 py-4 px-2.5 space-y-1 overflow-y-auto overflow-x-hidden">
+          {navItems.map((item) => (
+            <NavLink
+              key={item.id}
+              to={item.path}
+              title={effectiveCollapsed ? item.label : undefined}
+              onClick={(event) => {
+                item.onClick?.(event)
+                if (mobileOpen && !event.defaultPrevented) onMobileClose()
+              }}
+              className={({ isActive }: { isActive: boolean }) =>
+                [
+                  'relative w-full flex items-center rounded-xl text-left text-sm font-medium',
+                  'motion-safe:transition-all motion-safe:duration-150',
+                  'overflow-hidden whitespace-nowrap py-2.5',
+                  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-text-inverse/30',
+                  effectiveCollapsed ? 'justify-center px-0' : 'gap-3 px-3.5',
+                  isActive
+                    ? 'bg-gradient-primary text-text-inverse shadow-[0_4px_14px_-4px_rgba(113,75,103,0.55)]'
+                    : 'text-text-inverse/70 hover:bg-text-inverse/8 hover:text-text-inverse',
+                ].join(' ')
+              }
+            >
+              <span className="w-6 h-6 flex items-center justify-center shrink-0">
+                <item.icon />
+              </span>
+              {!effectiveCollapsed && <span className="truncate">{item.label}</span>}
+            </NavLink>
+          ))}
+
+          {/* Favoritos justo debajo de los enlaces (no pinned al fondo). El
+              propio componente devuelve null si no hay favoritos, por lo que
+              no se reserva espacio cuando está vacío. En modo colapsado los
+              widgets internos (SidebarFavorites, SidebarProcesos) reciben el
+              estado vía `useSidebarCollapsed()` para renderizar solo iconos. */}
+          <SidebarCollapsedProvider value={effectiveCollapsed}>
+            {favoritesSlot}
+          </SidebarCollapsedProvider>
+        </nav>
+
+        {/* ── Botón flotante de colapso (estilo Beluga) ── */}
+        <button
+          type="button"
+          onClick={onToggle}
+          className={[
+            'hidden md:flex absolute top-20 -right-3 z-[101]',
+            'w-6 h-6 items-center justify-center rounded-full',
+            'bg-ui-card dark:bg-ui-dark-card text-text-secondary dark:text-text-dark-secondary',
+            'border border-ui-border-l dark:border-ui-dark-border shadow-card-md',
+            'hover:text-odoo-purple dark:hover:text-odoo-dark-purple',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-odoo-purple/35',
+            'transition-colors',
+          ].join(' ')}
+          aria-label={collapsed
+            ? t('layout.expandSidebarMenu', { defaultValue: 'Expand side menu' })
+            : t('layout.collapseSidebarMenu', { defaultValue: 'Collapse side menu' })}
+        >
+          <ChevronIcon collapsed={collapsed} />
+        </button>
+
+        {/* ── Footer: solo bloque de usuario ── */}
+        <div className="shrink-0">
+          <SidebarUserBlock
+            userName={userName}
+            userEmail={userEmail}
+            userInitials={userInitials}
+            userAvatarUrl={userAvatarUrl}
+            onLogout={onLogout}
+            onProfile={onProfile}
+            isDark={isDark}
+            onToggleDark={onToggleDark}
+            collapsed={effectiveCollapsed}
+          />
+
+          {brandVersion && !effectiveCollapsed ? (
+            <p className="px-4 pb-3 pt-0.5 text-xs text-text-inverse/35 whitespace-nowrap">
+              {brandVersion}
+            </p>
+          ) : null}
+        </div>
+      </aside>
+    </>
+  )
+}

package/src/SidebarCollapsedContext.tsx

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * Estado del sidebar (colapsado vs expandido). Lo provee el `AppLayout`
+ * y lo consumen widgets que viven dentro del `favoritesSlot`, como
+ * `SidebarFavorites` o el `SidebarProcesos` de DMS, para renderizar
+ * en modo icono-only cuando el aside está colapsado.
+ *
+ * Default `false` (expandido) — si un consumidor olvida envolver con el
+ * provider, los componentes seguirán funcionando como antes.
+ */
+const SidebarCollapsedContext = createContext<boolean>(false)
+
+export const SidebarCollapsedProvider = SidebarCollapsedContext.Provider
+
+export function useSidebarCollapsed(): boolean {
+  return useContext(SidebarCollapsedContext)
+}

package/src/SidebarUserBlock.tsx

@@ -0,0 +1,276 @@
+import {
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactElement,
+  useEffect,
+  useRef,
+  useState,
+} from 'react'
+import { useTranslation } from 'react-i18next'
+import { Avatar } from '@ceedcv-maya/shared-ui-react'
+
+type Props = {
+  userName: string
+  userEmail?: string
+  userInitials: string
+  userAvatarUrl?: string | null
+  onLogout: () => void
+  onProfile?: () => void
+  isDark: boolean
+  onToggleDark: () => void
+  /** Cuando el sidebar está colapsado, muestra solo el avatar. */
+  collapsed?: boolean
+}
+
+/**
+ * Bloque de usuario al fondo del sidebar.
+ * - Expandido: avatar + nombre + email; al hacer click abre un menú con
+ *   tema, perfil y cerrar sesión.
+ * - Colapsado: solo avatar; mismo menú al click (se abre a la derecha).
+ *
+ * Patrón ARIA `menubutton` con flechas, Home/End, Esc y restauración de foco.
+ */
+export function SidebarUserBlock({
+  userName,
+  userEmail,
+  userInitials,
+  userAvatarUrl,
+  onLogout,
+  onProfile,
+  isDark,
+  onToggleDark,
+  collapsed = false,
+}: Props) {
+  const { t } = useTranslation('common')
+  const [open, setOpen] = useState(false)
+  const triggerRef = useRef<HTMLButtonElement | null>(null)
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const itemsRef = useRef<HTMLButtonElement[]>([])
+
+  useEffect(() => {
+    if (!open) return
+    function onClickOutside(e: MouseEvent) {
+      if (rootRef.current && !rootRef.current.contains(e.target as Node)) {
+        setOpen(false)
+      }
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        setOpen(false)
+        triggerRef.current?.focus()
+      }
+    }
+    document.addEventListener('mousedown', onClickOutside)
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('mousedown', onClickOutside)
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [open])
+
+  useEffect(() => {
+    if (!open) return
+    const t = window.setTimeout(() => itemsRef.current[0]?.focus(), 0)
+    return () => window.clearTimeout(t)
+  }, [open])
+
+  function onItemKey(e: ReactKeyboardEvent<HTMLButtonElement>, idx: number) {
+    const items = itemsRef.current
+    if (items.length === 0) return
+    if (e.key === 'ArrowDown') {
+      e.preventDefault()
+      items[(idx + 1) % items.length]?.focus()
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      items[(idx - 1 + items.length) % items.length]?.focus()
+    } else if (e.key === 'Home') {
+      e.preventDefault()
+      items[0]?.focus()
+    } else if (e.key === 'End') {
+      e.preventDefault()
+      items[items.length - 1]?.focus()
+    }
+  }
+
+  function registerItem(idx: number) {
+    return (el: HTMLButtonElement | null) => {
+      if (el) itemsRef.current[idx] = el
+      else itemsRef.current.splice(idx, 1)
+    }
+  }
+
+  // Construye dinámicamente la lista de items para indexar correctamente refs y teclas.
+  const menuItems: Array<{
+    label: string
+    onClick: () => void
+    danger?: boolean
+    icon: () => ReactElement
+    iconClass: string
+  }> = []
+
+  menuItems.push({
+    label: isDark ? t('userMenu.lightMode') : t('userMenu.darkMode'),
+    onClick: onToggleDark,
+    icon: () => (isDark ? <SunIcon /> : <MoonIcon />),
+    // Sol amber, luna púrpura — refleja el modo destino al pulsar.
+    iconClass: isDark ? 'text-warning' : 'text-odoo-purple dark:text-odoo-dark-purple',
+  })
+
+  if (onProfile) {
+    menuItems.push({
+      label: t('userMenu.profile'),
+      onClick: onProfile,
+      icon: () => <ProfileIcon />,
+      iconClass: 'text-odoo-teal dark:text-odoo-teal-d',
+    })
+  }
+
+  menuItems.push({
+    label: t('userMenu.logout'),
+    onClick: onLogout,
+    danger: true,
+    icon: () => <LogoutIcon />,
+    iconClass: 'text-danger',
+  })
+
+  // Posicionamiento del menú:
+  // - Expandido: pop-up por encima del bloque, alineado a la izquierda del trigger.
+  // - Colapsado: pop-out a la derecha del avatar.
+  const menuPositionClass = collapsed
+    ? 'left-full bottom-0 ml-2'
+    : 'bottom-full left-3 right-3 mb-2'
+
+  return (
+    <div ref={rootRef} className="relative border-t border-text-inverse/8 px-3 py-3">
+      <button
+        ref={triggerRef}
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        title={userEmail ? `${userName} · ${userEmail}` : userName}
+        className={[
+          'w-full rounded-lg focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-text-inverse/30',
+          collapsed
+            ? 'flex items-center justify-center'
+            : 'flex items-center gap-3 px-2 py-2 text-left hover:bg-text-inverse/5 transition-colors',
+        ].join(' ')}
+      >
+        <Avatar
+          src={userAvatarUrl ?? undefined}
+          initials={userInitials}
+          name={userName}
+          size="md"
+          interactive={collapsed}
+          className="ring-2 ring-text-inverse/10 shrink-0"
+        />
+        {!collapsed && (
+          <>
+            <span className="flex-1 min-w-0 text-base font-semibold text-text-inverse truncate">
+              {userName}
+            </span>
+            <ChevronUpIcon
+              className={`w-3 h-3 text-text-inverse/50 shrink-0 transition-transform duration-150 ${
+                open ? '' : 'rotate-180'
+              }`}
+            />
+          </>
+        )}
+      </button>
+
+      {open ? (
+        <div
+          role="menu"
+          aria-label={t('layout.userMenuOf', {
+            name: userName,
+            defaultValue: `Menu of ${userName}`,
+          })}
+          className={[
+            'absolute z-[210] min-w-[200px] py-1',
+            'bg-ui-card dark:bg-ui-dark-card border border-ui-border dark:border-ui-dark-border rounded-lg shadow-dropdown',
+            menuPositionClass,
+          ].join(' ')}
+        >
+          {/* En modo colapsado el trigger no muestra texto, así que el menú lo
+              añade en su cabecera. En expandido el trigger ya muestra el
+              nombre y omitimos esta sección para no duplicar. */}
+          {collapsed ? (
+            <div className="px-3 py-2 border-b border-ui-border-l dark:border-ui-dark-border-l">
+              <p className="text-sm font-semibold text-text-primary dark:text-text-dark-primary truncate">
+                {userName}
+              </p>
+            </div>
+          ) : null}
+          {menuItems.map((item, idx) => (
+            <button
+              key={item.label}
+              ref={registerItem(idx)}
+              type="button"
+              role="menuitem"
+              onClick={() => {
+                setOpen(false)
+                item.onClick()
+              }}
+              onKeyDown={(e) => onItemKey(e, idx)}
+              className={[
+                'w-full text-left px-3 py-2 text-sm flex items-center gap-2.5',
+                'focus-visible:outline-none transition-colors',
+                item.danger
+                  ? 'text-danger dark:text-danger hover:bg-danger/10 focus-visible:bg-danger/10'
+                  : 'text-text-primary dark:text-text-dark-primary hover:bg-ui-body dark:hover:bg-ui-dark-bg focus-visible:bg-ui-body dark:focus-visible:bg-ui-dark-bg',
+              ].join(' ')}
+            >
+              <span className={`w-4 h-4 flex items-center justify-center shrink-0 ${item.iconClass}`}>
+                {item.icon()}
+              </span>
+              <span>{item.label}</span>
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+function MoonIcon() {
+  return (
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+    </svg>
+  )
+}
+
+function SunIcon() {
+  return (
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <circle cx="12" cy="12" r="4" />
+      <path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41" />
+    </svg>
+  )
+}
+
+function ProfileIcon() {
+  return (
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <circle cx="12" cy="8" r="4" />
+      <path d="M4 21a8 8 0 0 1 16 0" />
+    </svg>
+  )
+}
+
+function LogoutIcon() {
+  return (
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" />
+      <polyline points="16 17 21 12 16 7" />
+      <line x1="21" y1="12" x2="9" y2="12" />
+    </svg>
+  )
+}
+
+function ChevronUpIcon({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <polyline points="18 15 12 9 6 15" />
+    </svg>
+  )
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export { AppLayout } from './AppLayout';
+export { Sidebar } from './Sidebar';
+export { SidebarUserBlock } from './SidebarUserBlock';
+export { MayaLogoIcon } from './MayaLogoIcon';
+export { useDarkMode } from './useDarkMode';
+export {
+  SidebarCollapsedProvider,
+  useSidebarCollapsed,
+} from './SidebarCollapsedContext';
+export type { NavItem } from './types';
+export {
+  FolderIcon,
+  HomeIcon,
+  UploadIcon,
+  SearchIcon,
+  UsersIcon,
+  TemplateIcon,
+  HamburgerIcon,
+  MoonIcon,
+  SunIcon,
+  GridIcon,
+  UserIcon,
+  ShieldIcon,
+  KeyIcon,
+  AppsIcon,
+} from './navIcons';

package/src/navIcons.tsx

@@ -0,0 +1,106 @@
+/** Iconos SVG compartidos para menú lateral y topbar. */
+
+export const FolderIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path d="M2 6a2 2 0 012-2h4l2 2h4a2 2 0 012 2v6a2 2 0 01-2 2H4a2 2 0 01-2-2V6z" />
+  </svg>
+);
+
+export const HomeIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path d="M10.707 2.293a1 1 0 00-1.414 0l-7 7a1 1 0 001.414 1.414L4 10.414V17a1 1 0 001 1h2a1 1 0 001-1v-2a1 1 0 011-1h2a1 1 0 011 1v2a1 1 0 001 1h2a1 1 0 001-1v-6.586l.293.293a1 1 0 001.414-1.414l-7-7z" />
+  </svg>
+);
+
+export const UploadIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path
+      fillRule="evenodd"
+      d="M3 17a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zM6.293 6.707a1 1 0 010-1.414l3-3a1 1 0 011.414 0l3 3a1 1 0 01-1.414 1.414L11 5.414V13a1 1 0 11-2 0V5.414L7.707 6.707a1 1 0 01-1.414 0z"
+      clipRule="evenodd"
+    />
+  </svg>
+);
+
+export const SearchIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path
+      fillRule="evenodd"
+      d="M8 4a4 4 0 100 8 4 4 0 000-8zM2 8a6 6 0 1110.89 3.476l4.817 4.817a1 1 0 01-1.414 1.414l-4.816-4.816A6 6 0 012 8z"
+      clipRule="evenodd"
+    />
+  </svg>
+);
+
+export const UsersIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path d="M9 6a3 3 0 11-6 0 3 3 0 016 0zM17 6a3 3 0 11-6 0 3 3 0 016 0zM12.93 17c.046-.327.07-.66.07-1a6.97 6.97 0 00-1.5-4.33A5 5 0 0119 16v1h-6.07zM6 11a5 5 0 015 5v1H1v-1a5 5 0 015-5z" />
+  </svg>
+);
+
+export const TemplateIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path d="M4 3a2 2 0 00-2 2v10a2 2 0 002 2h12a2 2 0 002-2V5a2 2 0 00-2-2H4zm0 2h16v10H4V5zm2 2h8v2H6V7zm0 4h12v2H6v-2zm0 4h8v2H6v-2z" />
+  </svg>
+);
+
+export const HamburgerIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path
+      fillRule="evenodd"
+      d="M3 5a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zM3 10a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zM3 15a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1z"
+      clipRule="evenodd"
+    />
+  </svg>
+);
+
+export const MoonIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path d="M17.293 13.293A8 8 0 016.707 2.707a8.001 8.001 0 1010.586 10.586z" />
+  </svg>
+);
+
+export const SunIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path
+      fillRule="evenodd"
+      d="M10 2a1 1 0 011 1v1a1 1 0 11-2 0V3a1 1 0 011-1zm4 8a4 4 0 11-8 0 4 4 0 018 0zm-.464 4.95l.707.707a1 1 0 001.414-1.414l-.707-.707a1 1 0 00-1.414 1.414zm2.12-10.607a1 1 0 010 1.414l-.706.707a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 0zM17 11a1 1 0 100-2h-1a1 1 0 100 2h1zm-7 4a1 1 0 011 1v1a1 1 0 11-2 0v-1a1 1 0 011-1zM5.05 6.464A1 1 0 106.465 5.05l-.708-.707a1 1 0 00-1.414 1.414l.707.707zm1.414 8.486l-.707.707a1 1 0 01-1.414-1.414l.707-.707a1 1 0 011.414 1.414zM4 11a1 1 0 100-2H3a1 1 0 000 2h1z"
+      clipRule="evenodd"
+    />
+  </svg>
+);
+
+/** Icono de grid (apps/herramientas) — usado por maya_dashboard */
+export const GridIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path d="M5 3a2 2 0 00-2 2v2a2 2 0 002 2h2a2 2 0 002-2V5a2 2 0 00-2-2H5zM5 11a2 2 0 00-2 2v2a2 2 0 002 2h2a2 2 0 002-2v-2a2 2 0 00-2-2H5zM11 5a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2V5zM11 13a2 2 0 012-2h2a2 2 0 012 2v2a2 2 0 01-2 2h-2a2 2 0 01-2-2v-2z" />
+  </svg>
+);
+
+/** Icono de perfil de usuario — usado por maya_dashboard */
+export const UserIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path fillRule="evenodd" d="M10 9a3 3 0 100-6 3 3 0 000 6zm-7 9a7 7 0 1114 0H3z" clipRule="evenodd" />
+  </svg>
+);
+
+/** Icono de escudo — usado por maya_authorization (roles) */
+export const ShieldIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path fillRule="evenodd" d="M10 1.944A11.954 11.954 0 012.166 5C2.056 5.649 2 6.319 2 7c0 5.225 3.34 9.67 8 11.317C14.66 16.67 18 12.225 18 7c0-.682-.057-1.35-.166-2.001A11.954 11.954 0 0110 1.944zM11 14a1 1 0 11-2 0 1 1 0 012 0zm0-7a1 1 0 10-2 0v3a1 1 0 102 0V7z" clipRule="evenodd" />
+  </svg>
+);
+
+/** Icono de llave — usado por maya_authorization (permisos) */
+export const KeyIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path fillRule="evenodd" d="M18 8a6 6 0 01-7.743 5.743L10 14l-1 1-1 1H6v2H2v-4l4.257-4.257A6 6 0 1118 8zm-6-4a1 1 0 100 2 2 2 0 012 2 1 1 0 102 0 4 4 0 00-4-4z" clipRule="evenodd" />
+  </svg>
+);
+
+/** Icono de cuadrados apilados — usado por maya_authorization (aplicaciones) */
+export const AppsIcon = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className="w-[22px] h-[22px]">
+    <path d="M7 3a1 1 0 000 2h6a1 1 0 100-2H7zM4 7a1 1 0 011-1h10a1 1 0 110 2H5a1 1 0 01-1-1zM2 11a2 2 0 012-2h12a2 2 0 012 2v4a2 2 0 01-2 2H4a2 2 0 01-2-2v-4z" />
+  </svg>
+);

package/src/types.ts

@@ -0,0 +1,15 @@
+import type { FC, MouseEvent } from 'react';
+
+/**
+ * Item del menú lateral. `path` es el destino estándar (NavLink to=...).
+ * Si se define `onClick`, se invoca antes de navegar — el handler puede
+ * llamar a `event.preventDefault()` para suprimir la navegación
+ * (caso: abrir un drawer secundario en desktop sin cambiar la ruta).
+ */
+export type NavItem = {
+  id: string;
+  label: string;
+  icon: FC;
+  path: string;
+  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+};

package/src/useDarkMode.ts

@@ -0,0 +1,128 @@
+import { useEffect, useRef, useState } from 'react'
+import { readOverrides, writeOverrides } from '@ceedcv-maya/shared-auth-react'
+
+/**
+ * Hook compartido de tema claro/oscuro con sincronización cross-subdomain.
+ *
+ * Cadena de precedencia al inicializar:
+ *   1. Cookie `maya_session_overrides.theme` (única fuente cross-app si
+ *      otra app del ecosistema cambió el tema desde su sidebar).
+ *   2. `localStorage.maya-theme` (cache local same-origin).
+ *   3. `prefers-color-scheme` del sistema operativo.
+ *
+ * Al cambiar el tema desde ESTA app (`toggle` / `setIsDark`):
+ *   - Se aplica `<html class="dark">`.
+ *   - Se persiste en `localStorage.maya-theme`.
+ *   - Se escribe la cookie compartida `maya_session_overrides.theme`,
+ *     que las demás apps leen al recuperar foco.
+ *
+ * Cuando el cambio llega DESDE FUERA (otra app, otra pestaña):
+ *   - `reconcile` recoge el theme de la cookie y actualiza el state local
+ *     sin reescribir la cookie (evita bucles).
+ */
+
+const STORAGE_KEY = 'maya-theme'
+const OVERRIDES_EVENT = 'maya:profile-overrides'
+
+type Theme = 'dark' | 'light'
+
+function readThemeFromOverrides(): Theme | null {
+  const overrides = readOverrides()
+  if (!overrides) return null
+  const value = overrides.theme
+  return value === 'dark' || value === 'light' ? value : null
+}
+
+function readInitialIsDark(): boolean {
+  if (typeof window === 'undefined') return false
+
+  const fromCookie = readThemeFromOverrides()
+  if (fromCookie) return fromCookie === 'dark'
+
+  const stored = localStorage.getItem(STORAGE_KEY)
+  if (stored === 'dark' || stored === 'light') return stored === 'dark'
+
+  return window.matchMedia('(prefers-color-scheme: dark)').matches
+}
+
+export function useDarkMode() {
+  const [isDark, setIsDark] = useState<boolean>(readInitialIsDark)
+
+  // `true` cuando el cambio se inició localmente (toggle/setIsDark) y aún
+  // hay que propagarlo a la cookie. Se baja a `false` en cuanto el effect
+  // de propagación lo persiste, o cuando un listener externo entra primero.
+  const pendingPropagationRef = useRef<boolean>(false)
+
+  // Efecto único: aplica el tema al DOM, al localStorage y, si el cambio
+  // se originó aquí, a la cookie compartida.
+  useEffect(() => {
+    if (typeof document === 'undefined') return
+    const theme: Theme = isDark ? 'dark' : 'light'
+
+    document.documentElement.classList.toggle('dark', isDark)
+    try {
+      localStorage.setItem(STORAGE_KEY, theme)
+    } catch {
+      /* localStorage no disponible — ignorable */
+    }
+
+    if (pendingPropagationRef.current) {
+      pendingPropagationRef.current = false
+      const fromCookie = readThemeFromOverrides()
+      if (fromCookie !== theme) {
+        writeOverrides({ theme })
+      }
+    }
+  }, [isDark])
+
+  // Listeners cross-tab / cross-subdomain: NO escriben cookie, solo
+  // actualizan el state local con lo que la cookie ya trae.
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined
+
+    const reconcile = (): void => {
+      const fromCookie = readThemeFromOverrides()
+      if (!fromCookie) return
+      setIsDark((current) => {
+        const desired = fromCookie === 'dark'
+        return current === desired ? current : desired
+      })
+    }
+
+    const onStorage = (e: StorageEvent): void => {
+      if (e.key !== STORAGE_KEY) return
+      if (e.newValue !== 'dark' && e.newValue !== 'light') return
+      const desired = e.newValue === 'dark'
+      setIsDark((current) => (current === desired ? current : desired))
+    }
+
+    window.addEventListener(OVERRIDES_EVENT, reconcile)
+    document.addEventListener('visibilitychange', reconcile)
+    // `focus` y `pageshow` cubren navegadores/contextos donde
+    // `visibilitychange` no se dispara al alternar entre ventanas (multi-monitor,
+    // popups) o tras navegación back/forward con bfcache.
+    window.addEventListener('focus', reconcile)
+    window.addEventListener('pageshow', reconcile)
+    window.addEventListener('storage', onStorage)
+
+    return () => {
+      window.removeEventListener(OVERRIDES_EVENT, reconcile)
+      document.removeEventListener('visibilitychange', reconcile)
+      window.removeEventListener('focus', reconcile)
+      window.removeEventListener('pageshow', reconcile)
+      window.removeEventListener('storage', onStorage)
+    }
+  }, [])
+
+  const toggle = (): void => {
+    pendingPropagationRef.current = true
+    setIsDark((d) => !d)
+  }
+
+  const setDark = (next: boolean): void => {
+    pendingPropagationRef.current = true
+    setIsDark(next)
+  }
+
+  return { isDark, setIsDark: setDark, toggle } as const
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "esModuleInterop": false,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  },
+  "include": ["src"]
+}