@ceedcv-maya/shared-dashboard-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,33 @@
+# @ceedcv-maya/shared-dashboard-react
+
+Dashboard primitives for React: configurable widget grid (react-grid-layout), widget registry, persistence helpers.
+
+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-dashboard-react react-grid-layout
+```
+
+```tsx
+import { DashboardGrid, registerWidget } from '@ceedcv-maya/shared-dashboard-react'
+
+registerWidget('weather', WeatherWidget)
+
+export function Home() {
+  return <DashboardGrid layout={savedLayout} onChange={persist} />
+}
+```
+
+
+## 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,63 @@
+{
+  "name": "@ceedcv-maya/shared-dashboard-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-grid-layout": "^1.5.0",
+    "react-i18next": "^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@types/react-grid-layout": "^1.3.0",
+    "react-grid-layout": "^1.5.0",
+    "react-i18next": "^17.0.0",
+    "i18next": "^26.0.0"
+  },
+  "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-dashboard-react"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Dashboard primitives for React: configurable widget grid (react-grid-layout), widget registry, persistence helpers.",
+  "keywords": [
+    "react",
+    "dashboard",
+    "widgets",
+    "grid-layout",
+    "ceedcv",
+    "maya"
+  ],
+  "author": {
+    "name": "CEEDCV",
+    "email": "info@ceedcv.es",
+    "homepage": "https://ceedcv.es"
+  },
+  "homepage": "https://github.com/Maya-AQSS/shared-dashboard-react#readme",
+  "bugs": {
+    "url": "https://github.com/Maya-AQSS/maya_platform/issues"
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "tsconfig.json"
+  ]
+}

package/src/DashboardEditToggleButton.tsx

@@ -0,0 +1,58 @@
+import { useTranslation } from 'react-i18next'
+
+interface Props {
+  editable: boolean
+  onToggle: () => void
+  /** Texto del botón cuando NO está en modo edit. Si no se pasa, usa i18n. */
+  editLabel?: string
+  /** Texto del botón cuando SÍ está en modo edit. Si no se pasa, usa i18n. */
+  exitLabel?: string
+}
+
+/**
+ * Botón compartido para entrar/salir del modo edición de los paneles
+ * dashboard. Usa gradiente Maya, visible en ambos temas (claro/oscuro).
+ *
+ * Texto y estilo idéntico en las 4 apps Maya:
+ * - Modo lectura: gradiente púrpura + label de i18n
+ * - Modo edit:    fondo verde + label de i18n
+ *
+ * En viewports < sm el texto se oculta y queda solo el icono (forma circular).
+ */
+export function DashboardEditToggleButton({
+  editable,
+  onToggle,
+  editLabel,
+  exitLabel,
+}: Props) {
+  const { t } = useTranslation('common')
+  const label = editable
+    ? (exitLabel ?? t('dashboard.exitEdit', { defaultValue: 'Done' }))
+    : (editLabel ?? t('actions.edit', { defaultValue: 'Edit' }))
+
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      aria-pressed={editable}
+      aria-label={label}
+      title={label}
+      className={[
+        // Mismo radio (rounded-md) y altura que los botones primary del
+        // resto de la app (ver Button.tsx variant sm). El `mr-4` alinea
+        // el borde derecho del botón con el borde derecho del bloque
+        // de widgets (react-grid-layout aplica containerPadding=16px).
+        'inline-flex items-center justify-center h-9 px-4 rounded-md mr-4',
+        'text-sm font-semibold tracking-wide',
+        'shadow-[0_2px_6px_-2px_rgba(113,75,103,0.45)] hover:shadow-[0_8px_18px_-6px_rgba(113,75,103,0.55)]',
+        'transition-all motion-reduce:transition-none',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-odoo-purple/40',
+        editable
+          ? 'bg-success hover:bg-success-dark text-text-inverse border border-success-dark dark:border-success'
+          : 'bg-gradient-primary bg-gradient-primary-hover text-text-inverse border border-odoo-purple-d dark:border-odoo-dark-purple motion-reduce:bg-odoo-purple motion-reduce:dark:bg-odoo-dark-purple',
+      ].join(' ')}
+    >
+      {label}
+    </button>
+  )
+}

package/src/DashboardEditToolbar.tsx

@@ -0,0 +1,131 @@
+import { useEffect, useRef, useState } from 'react'
+import type { LayoutItem, WidgetRegistry } from './types'
+
+interface Props {
+  /** Layout actual (para saber qué widgets ya están añadidos). */
+  layout: LayoutItem[]
+  /** Catálogo completo de widgets disponibles. */
+  registry: WidgetRegistry
+  /** Función i18n del consumidor — resuelve `titleKey` de cada widget. */
+  t: (key: string) => string
+  onSave: () => void
+  onCancel: () => void
+  onReset: () => void
+  onAddWidget: (widgetId: string) => void
+  /** Etiquetas opcionales (default en español). */
+  labels?: {
+    save?: string
+    cancel?: string
+    reset?: string
+    addWidget?: string
+  }
+}
+
+/**
+ * Submenú de edición compartido por las 4 apps Maya. Diseñado para
+ * renderizarse dentro del slot `actions` de `<PageTitle>`, reemplazando
+ * al `DashboardEditToggleButton` durante el modo edición.
+ *
+ * Botones con altura h-9 y forma rounded-full para coincidir con
+ * `DashboardEditToggleButton`.
+ */
+export function DashboardEditToolbar({
+  layout,
+  registry,
+  t,
+  onSave,
+  onCancel,
+  onReset,
+  onAddWidget,
+  labels,
+}: Props) {
+  const defaultLabels = {
+    save: t('actions.save'),
+    cancel: t('actions.cancel'),
+    reset: t('actions.reset'),
+    addWidget: t('dashboard.addWidget'),
+  }
+  const L = { ...defaultLabels, ...(labels ?? {}) }
+  const [dropdownOpen, setDropdownOpen] = useState(false)
+  const dropdownRef = useRef<HTMLDivElement | null>(null)
+
+  useEffect(() => {
+    if (!dropdownOpen) return
+    function handleClick(e: MouseEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(e.target as Node)) {
+        setDropdownOpen(false)
+      }
+    }
+    document.addEventListener('mousedown', handleClick)
+    return () => document.removeEventListener('mousedown', handleClick)
+  }, [dropdownOpen])
+
+  const existingIds = new Set(layout.map((item) => item.i))
+  const availableToAdd = Object.values(registry).filter((def) => !existingIds.has(def.id))
+
+  const baseBtn = [
+    // rounded-md igual que el resto de botones de la app (Button.tsx).
+    'inline-flex items-center justify-center h-9 px-4 rounded-md',
+    'text-sm font-semibold tracking-wide',
+    'shadow-[0_2px_6px_-2px_rgba(113,75,103,0.35)] hover:shadow-[0_6px_14px_-6px_rgba(113,75,103,0.45)]',
+    'transition-all motion-reduce:transition-none',
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-odoo-purple/40',
+  ].join(' ')
+
+  // Verde sólido: acción positiva (guardar).
+  const primaryBtn = `${baseBtn} bg-success hover:bg-success-dark text-text-inverse border border-success-dark dark:border-success`
+  // Neutro ghost: cancelar (descartar sin perder datos).
+  const cancelBtn = `${baseBtn} bg-transparent border border-ui-border dark:border-ui-dark-border text-text-secondary dark:text-text-dark-secondary hover:bg-ui-body dark:hover:bg-ui-dark-bg hover:text-text-primary dark:hover:text-text-dark-primary`
+  // Outline warning: restablecer (acción destructiva del layout).
+  const resetBtn = `${baseBtn} bg-warning-light dark:bg-warning-dark/20 border border-warning/50 dark:border-warning/60 text-warning-dark dark:text-warning hover:bg-warning/20 dark:hover:bg-warning-dark/40`
+  // Purple primary: acento (añadir widget).
+  const accentBtn = `${baseBtn} bg-gradient-primary bg-gradient-primary-hover text-text-inverse border border-odoo-purple-d dark:border-odoo-dark-purple disabled:opacity-50 disabled:cursor-not-allowed`
+
+  return (
+    // `mr-4` alinea el grupo con el borde derecho del bloque de widgets
+    // (react-grid-layout aplica containerPadding = margin = 16px).
+    <div className="flex items-center gap-2 flex-wrap justify-end mr-4">
+      <button type="button" onClick={onSave} className={primaryBtn} title={L.save}>
+        {L.save}
+      </button>
+      <button type="button" onClick={onCancel} className={cancelBtn} title={L.cancel}>
+        {L.cancel}
+      </button>
+      <div className="relative" ref={dropdownRef}>
+        <button
+          type="button"
+          onClick={() => setDropdownOpen((v) => !v)}
+          disabled={availableToAdd.length === 0}
+          className={accentBtn}
+          title={L.addWidget}
+        >
+          + {L.addWidget}
+        </button>
+        {dropdownOpen && availableToAdd.length > 0 && (
+          <div
+            role="menu"
+            className="absolute right-0 top-full mt-1 z-[300] min-w-[200px] bg-ui-card dark:bg-ui-dark-card border border-ui-border dark:border-ui-dark-border rounded-xl shadow-lg overflow-hidden"
+          >
+            {availableToAdd.map((def) => (
+              <button
+                key={def.id}
+                type="button"
+                role="menuitem"
+                onClick={() => {
+                  onAddWidget(def.id)
+                  setDropdownOpen(false)
+                }}
+                className="w-full text-left px-4 py-2 text-sm text-text-primary dark:text-text-dark-primary hover:bg-ui-body dark:hover:bg-ui-dark-bg transition"
+              >
+                {t(def.titleKey)}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+      <button type="button" onClick={onReset} className={resetBtn} title={L.reset}>
+        {L.reset}
+      </button>
+    </div>
+  )
+}

package/src/DashboardSkeleton.tsx

@@ -0,0 +1,59 @@
+/**
+ * Skeleton placeholder mostrado mientras el layout del dashboard se carga
+ * desde localStorage / backend. Estructura un grid de 12 columnas con
+ * `blocks` configurables; sin props usa 2 bloques al 50% (col-span-6 / h-40).
+ *
+ * Para layouts no triviales pasa `blocks` con `colSpanClasses` + `heightClass`
+ * (cada string es una clase Tailwind completa, no se interpola).
+ *
+ * Ejemplos:
+ *   <DashboardSkeleton />                            ← 2 bloques 50/50 alto 40
+ *   <DashboardSkeleton blockCount={3} />             ← 3 bloques 50/50/100 alto 40
+ *   <DashboardSkeleton blocks={[                     ← layout personalizado
+ *     { colSpanClasses: 'col-span-12 sm:col-span-8', heightClass: 'h-64' },
+ *     { colSpanClasses: 'col-span-12 sm:col-span-4', heightClass: 'h-32' },
+ *   ]} />
+ *
+ * Tailwind: usa las variables del theme Maya (`ui-border-l`,
+ * `ui-dark-border`); asume que el consumidor monta el provider de tema.
+ */
+
+export interface SkeletonBlock {
+  /** Clases Tailwind para columnas, e.g. `'col-span-12 sm:col-span-6'`. */
+  colSpanClasses: string
+  /** Clase Tailwind para altura, e.g. `'h-40'` o `'h-64'`. */
+  heightClass: string
+}
+
+export interface DashboardSkeletonProps {
+  /**
+   * Layout explícito de bloques. Tiene prioridad sobre `blockCount`.
+   */
+  blocks?: SkeletonBlock[]
+  /**
+   * Número de bloques placeholder a renderizar con tamaño default
+   * (col-span-12 sm:col-span-6 / h-40). Ignorado si `blocks` se provee.
+   * Default: 2.
+   */
+  blockCount?: number
+}
+
+const DEFAULT_BLOCK: SkeletonBlock = {
+  colSpanClasses: 'col-span-12 sm:col-span-6',
+  heightClass: 'h-40',
+}
+
+export function DashboardSkeleton({ blocks, blockCount = 2 }: DashboardSkeletonProps) {
+  const layout = blocks ?? Array.from({ length: blockCount }, () => DEFAULT_BLOCK)
+
+  return (
+    <div className="p-4 sm:p-6 grid grid-cols-12 gap-4 animate-pulse">
+      {layout.map((block, i) => (
+        <div
+          key={i}
+          className={`${block.colSpanClasses} ${block.heightClass} bg-ui-border-l dark:bg-ui-dark-border rounded-2xl`}
+        />
+      ))}
+    </div>
+  )
+}

package/src/WidgetFrame.tsx

@@ -0,0 +1,122 @@
+import type { ReactNode } from 'react'
+import { useTranslation } from 'react-i18next'
+
+interface WidgetFrameProps {
+  title?: string
+  hideTitle?: boolean
+  editable?: boolean
+  onRemove?: () => void
+  removeAriaLabel?: string
+  /**
+   * Realza el widget con borde gradiente diagonal (purple → teal).
+   * Pensado para KPI hero del dashboard. Usar con moderación: 1-2 widgets
+   * destacados por pantalla, el resto queda con el frame estándar.
+   */
+  highlight?: boolean
+  /**
+   * Si true, el frame deja crecer su contenido fuera del card. Pensado para
+   * widgets con decoraciones flotantes (megáfono asomando, badges sobresalidos).
+   * Mantén siempre el card relativo: las decoraciones se posicionan absolute.
+   */
+  allowOverflow?: boolean
+  /** Si true, el contenedor de children no aplica padding interno. */
+  bleed?: boolean
+  children?: ReactNode
+}
+
+/**
+ * Marco visual común para los widgets del dashboard: card con bordes
+ * redondeados, opcional barra de título, opcional botón de eliminar
+ * (solo visible en modo edit).
+ *
+ * En modo edit:
+ * - Toda la card actúa como drag-handle (clase `widget-drag-handle`),
+ *   excepto el botón de eliminar y el handle de resize de
+ *   `react-grid-layout` (`.react-resizable-handle`).
+ * - El contenido del widget queda bloqueado a interacciones
+ *   (`pointer-events-none`) para que el usuario solo pueda
+ *   arrastrar/redimensionar.
+ */
+export function WidgetFrame({
+  title,
+  hideTitle = false,
+  editable = false,
+  onRemove,
+  removeAriaLabel,
+  highlight = false,
+  allowOverflow = false,
+  bleed = false,
+  children,
+}: WidgetFrameProps) {
+  const { t } = useTranslation('common')
+  const resolvedRemoveAriaLabel =
+    removeAriaLabel ?? t('dashboard.removeWidget', { defaultValue: 'Remove widget' })
+  const showRemove = editable && typeof onRemove === 'function'
+  // Surface premium: glassmorphism (con fallback automático via @media reduced-transparency)
+  // + sombra extendida con tinte morado + hover lift sutil en modo lectura.
+  // En modo edit no se aplica el lift para no competir con el drag.
+  // En modo highlight, sustituye el borde plano por gradiente diagonal.
+  const baseSurface = highlight
+    ? 'border-glow-glass shadow-card-glass'
+    : 'bg-card-glass shadow-card-glass border border-ui-border/70 dark:border-ui-dark-border/70'
+  const frameClasses = [
+    'relative h-full flex flex-col rounded-2xl',
+    allowOverflow ? 'overflow-visible' : 'overflow-hidden',
+    baseSurface,
+    editable
+      ? 'widget-drag-handle cursor-grab active:cursor-grabbing'
+      : 'motion-safe:transition-all motion-safe:duration-200 ease-out motion-safe:hover:-translate-y-0.5 motion-safe:hover:shadow-card-md',
+    !editable && !highlight
+      ? 'hover:border-odoo-purple/30 dark:hover:border-odoo-dark-purple/40'
+      : '',
+  ]
+    .filter(Boolean)
+    .join(' ')
+    .trim()
+
+  return (
+    <div className={frameClasses}>
+      {!hideTitle && (
+        <div className="flex items-center justify-between px-4 py-2 border-b border-ui-border-l dark:border-ui-dark-border">
+          <span className="text-sm font-semibold text-text-primary dark:text-text-dark-primary truncate">
+            {title}
+          </span>
+          {showRemove && (
+            <button
+              type="button"
+              onClick={onRemove}
+              onMouseDown={(e) => e.stopPropagation()}
+              onTouchStart={(e) => e.stopPropagation()}
+              aria-label={resolvedRemoveAriaLabel}
+              className="ml-2 shrink-0 inline-flex items-center justify-center w-6 h-6 rounded-md text-text-secondary hover:text-danger hover:bg-danger/10 transition-colors text-lg leading-none cursor-pointer"
+            >
+              ×
+            </button>
+          )}
+        </div>
+      )}
+      {hideTitle && showRemove && (
+        <button
+          type="button"
+          onClick={onRemove}
+          onMouseDown={(e) => e.stopPropagation()}
+          onTouchStart={(e) => e.stopPropagation()}
+          aria-label={resolvedRemoveAriaLabel}
+          className="absolute top-1 right-1 z-20 inline-flex items-center justify-center w-6 h-6 rounded-md text-text-secondary hover:text-danger hover:bg-danger/10 transition-colors text-lg leading-none cursor-pointer bg-ui-card/80 dark:bg-ui-dark-card/80 backdrop-blur"
+        >
+          ×
+        </button>
+      )}
+      <div
+        className={[
+          'flex-1',
+          allowOverflow ? 'overflow-visible' : 'overflow-auto',
+          bleed ? '' : 'p-3',
+          editable ? 'pointer-events-none select-none' : '',
+        ].filter(Boolean).join(' ')}
+      >
+        {children}
+      </div>
+    </div>
+  )
+}

package/src/WidgetGrid.tsx

@@ -0,0 +1,113 @@
+import { useCallback } from 'react'
+import { Responsive, WidthProvider, type Layout } from 'react-grid-layout'
+import { WidgetFrame } from './WidgetFrame'
+import type { LayoutItem, WidgetRegistry } from './types'
+
+const ResponsiveGridLayout = WidthProvider(Responsive)
+
+const BREAKPOINTS = { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }
+const COLS = { lg: 12, md: 12, sm: 6, xs: 4, xxs: 2 }
+
+interface WidgetGridProps {
+  /** Definiciones de widgets disponibles. */
+  registry: WidgetRegistry
+  /** Layout actual (posición/tamaño de cada widget). */
+  layout: LayoutItem[]
+  /** Callback al cambiar el layout (drag/resize). */
+  onLayoutChange: (next: LayoutItem[]) => void
+  /** Modo edición — habilita drag y resize. */
+  editable: boolean
+  /** Callback al eliminar un widget. */
+  onRemoveWidget: (widgetId: string) => void
+  /** Función i18n del consumidor — usada para resolver `titleKey` y mensajes. */
+  t: (key: string) => string
+  /** Mensaje cuando no hay widgets visibles. */
+  emptyKey?: string
+  /** Aria label del botón eliminar de cada widget. */
+  removeAriaLabel?: string
+}
+
+/**
+ * Rejilla responsive con drag-and-drop sobre `react-grid-layout`. Renderiza
+ * cada widget de `layout` resolviendo su componente desde `registry`.
+ *
+ * El consumidor mantiene el estado del layout (`layout` + `onLayoutChange`) y
+ * la persistencia (localStorage, backend, etc.).
+ */
+export function WidgetGrid({
+  registry,
+  layout,
+  onLayoutChange,
+  editable,
+  onRemoveWidget,
+  t,
+  emptyKey = 'dashboard.noWidgets',
+  removeAriaLabel,
+}: WidgetGridProps) {
+  // Widgets pueden redimensionarse libremente: minW/minH del layout/registry
+  // se ignoran para permitir tamaños arbitrarios.
+  const validItems = layout
+    .filter((item) => item.i in registry)
+    .map((item) => ({ ...item, minW: 1, minH: 1 }))
+
+  const handleStop = useCallback(
+    (currentLayout: Layout[]) => {
+      if (!editable) return
+      const positionMap = Object.fromEntries(currentLayout.map((l) => [l.i, l]))
+      const merged: LayoutItem[] = layout.map((item) => {
+        const pos = positionMap[item.i]
+        return pos ? { ...item, x: pos.x, y: pos.y, w: pos.w, h: pos.h } : item
+      })
+      onLayoutChange(merged)
+    },
+    [editable, layout, onLayoutChange],
+  )
+
+  if (validItems.length === 0) {
+    return (
+      <p className="text-text-secondary dark:text-text-dark-secondary text-sm text-center py-12">
+        {t(emptyKey)}
+      </p>
+    )
+  }
+
+  return (
+    <ResponsiveGridLayout
+      className="layout"
+      layouts={{ lg: validItems, md: validItems, sm: validItems }}
+      breakpoints={BREAKPOINTS}
+      cols={COLS}
+      rowHeight={60}
+      margin={[16, 16]}
+      isDraggable={editable}
+      isResizable={editable}
+      compactType={null}
+      preventCollision={false}
+      allowOverlap={false}
+      onDragStop={handleStop}
+      onResizeStop={handleStop}
+      draggableHandle=".widget-drag-handle"
+    >
+      {validItems.map((item) => {
+        const def = registry[item.i]
+        const WidgetComponent = def.component
+        return (
+          <div key={item.i} className={def.allowOverflow ? 'maya-widget-item--overflow' : undefined}>
+            <WidgetFrame
+              title={t(def.titleKey)}
+              hideTitle={def.hideTitle}
+              editable={editable}
+              onRemove={() => onRemoveWidget(item.i)}
+              removeAriaLabel={removeAriaLabel}
+              highlight={def.highlight}
+              allowOverflow={def.allowOverflow}
+              bleed={def.bleed}
+            >
+              <WidgetComponent />
+            </WidgetFrame>
+          </div>
+        )
+      })}
+    </ResponsiveGridLayout>
+  )
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { WidgetGrid } from './WidgetGrid'
+export { WidgetFrame } from './WidgetFrame'
+export { DashboardEditToggleButton } from './DashboardEditToggleButton'
+export { DashboardEditToolbar } from './DashboardEditToolbar'
+export { DashboardSkeleton } from './DashboardSkeleton'
+export type { DashboardSkeletonProps, SkeletonBlock } from './DashboardSkeleton'
+export { useDashboardLayoutLocal } from './useDashboardLayoutLocal'
+export type { LayoutItem, WidgetDefinition, WidgetRegistry } from './types'

package/src/types.ts

@@ -0,0 +1,49 @@
+import type { ComponentType } from 'react'
+
+/** Posición y tamaño de un widget en la rejilla. */
+export interface LayoutItem {
+  /** id del widget — debe coincidir con la clave en el `WidgetRegistry`. */
+  i: string
+  x: number
+  y: number
+  w: number
+  h: number
+  minW?: number
+  minH?: number
+}
+
+/** Definición de un widget reutilizable. */
+export interface WidgetDefinition {
+  /** id estable. */
+  id: string
+  /** Clave i18n para el título (resuelta por el consumidor con su `t`). */
+  titleKey: string
+  /** Si true, oculta la barra de título del frame. */
+  hideTitle?: boolean
+  /**
+   * Realza el widget con borde gradiente (purple → teal). Reservar para
+   * KPIs hero (1-2 por dashboard máximo).
+   */
+  highlight?: boolean
+  /**
+   * Si true, el frame deja crecer su contenido fuera del card (`overflow:visible`).
+   * Útil cuando el widget renderiza decoraciones que deben sobresalir
+   * (megáfono, marcadores). Por defecto false — el frame recorta.
+   */
+  allowOverflow?: boolean
+  /**
+   * Si true, el frame no aplica padding interno al contenedor de children.
+   * El widget controla su propio espaciado — necesario para fondos a sangre
+   * que llegan hasta el borde del card.
+   */
+  bleed?: boolean
+  /** Tamaño por defecto al añadir el widget. */
+  defaultSize: { w: number; h: number }
+  /** Tamaño mínimo al redimensionar. */
+  minSize: { w: number; h: number }
+  /** Componente React que renderiza el contenido del widget. */
+  component: ComponentType<Record<string, unknown>>
+}
+
+/** Mapa id → definición. */
+export type WidgetRegistry = Record<string, WidgetDefinition>

package/src/useDashboardLayoutLocal.ts

@@ -0,0 +1,62 @@
+import { useCallback, useEffect, useState } from 'react'
+import type { LayoutItem } from './types'
+
+interface Options {
+  /** Clave única bajo `localStorage` (recomendado: `maya:<app>:dashboard-layout`). */
+  storageKey: string
+  /** Layout por defecto al primer arranque o tras un reset. */
+  defaultLayout: LayoutItem[]
+}
+
+/**
+ * Persistencia simple del layout del dashboard usando localStorage.
+ * Cada app puede usar este hook si no quiere persistir en backend.
+ *
+ *   const { layout, loading, saveLayout, resetToDefault } = useDashboardLayoutLocal({
+ *     storageKey: 'maya:dms:dashboard-layout',
+ *     defaultLayout: DEFAULT_LAYOUT,
+ *   })
+ */
+export function useDashboardLayoutLocal({ storageKey, defaultLayout }: Options) {
+  const [layout, setLayout] = useState<LayoutItem[]>(defaultLayout)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    try {
+      const raw = localStorage.getItem(storageKey)
+      if (raw) {
+        const parsed = JSON.parse(raw)
+        if (Array.isArray(parsed)) {
+          setLayout(parsed as LayoutItem[])
+        }
+      }
+    } catch {
+      /* localStorage no disponible o JSON corrupto — usar default */
+    } finally {
+      setLoading(false)
+    }
+  }, [storageKey])
+
+  const saveLayout = useCallback(
+    async (next: LayoutItem[]) => {
+      setLayout(next)
+      try {
+        localStorage.setItem(storageKey, JSON.stringify(next))
+      } catch {
+        /* noop — el cambio queda en memoria al menos */
+      }
+    },
+    [storageKey],
+  )
+
+  const resetToDefault = useCallback(async () => {
+    setLayout(defaultLayout)
+    try {
+      localStorage.removeItem(storageKey)
+    } catch {
+      /* noop */
+    }
+  }, [storageKey, defaultLayout])
+
+  return { layout, loading, saveLayout, resetToDefault }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"]
+}