# Bootstrap 5 Audit - 2026-06-12

Estado base:
- Backend/frontend principal ya estan en Laravel 12, Vue 3, Element Plus y Node 22.22.0.
- Bootstrap activo sigue siendo 4.6.2 en `package.json`.
- Layout tenant principal carga Bootstrap desde `public/cuba/assets/...`, no solo desde npm.
- Existen layouts separados para tenant, POS, ecommerce, restaurant y system. No migrar en big-bang.

## Conteo inicial

Busqueda en `resources/views`, `resources/js` y `modules`, excluyendo vendor, public y backups:

| Patron | Conteo |
|---|---:|
| `data-toggle=` | 70 |
| `data-target=` | 1 |
| `data-dismiss=` | 11 |
| `data-placement=` | 35 |
| jQuery `.modal(...)` | 15 |
| jQuery `.tooltip/.popover/.dropdown(...)` | 1 |
| `ml-*` / `mr-*` | 291 |
| `pl-*` / `pr-*` | 190 |
| `text-left` / `text-right` | 409 |
| `float-left` / `float-right` | 66 |
| `font-weight-*` / `font-italic` | 522 |
| `border-left/right` / `rounded-left/right` | 153 |
| `form-group` | 2481 |
| `custom-*` forms | 25 |
| `input-group-append/prepend` | 19 |
| `btn-block` | 82 |
| `badge-*` contextual/pill | 52 |

## Riesgos reales

- Bootstrap JS cambia de jQuery plugins a API nativa (`bootstrap.Modal`, `bootstrap.Tooltip`, etc.).
- Atributos `data-toggle`, `data-target`, `data-dismiss`, `data-placement` pasan a `data-bs-*`.
- Utilidades RTL cambian: `ml/mr/pl/pr` pasan a `ms/me/ps/pe`, `text-left/right` a `text-start/end`, `float-left/right` a `float-start/end`.
- `form-group` desaparece en BS5, pero hay 2481 usos. Se debe resolver por CSS compat o por modulo, no reemplazo masivo ciego.
- `input-group-append/prepend`, `custom-*`, `btn-block`, `badge-pill` requieren migracion semantica.
- `jquery`, `popper.js`, `@popperjs/core` conviven. No eliminar jQuery durante BS5: aun hay plugins Porto/Cuba/Summernote y codigo legacy.

## Orden recomendado

1. Crear capa de compatibilidad temporal BS4/BS5 en CSS para `form-group`, validacion, botones block y badges.
2. Migrar solo tenant layout principal y dashboard/POS/documentos con gate Playwright.
3. Cambiar atributos `data-*` en Vue/Blade activos a `data-bs-*`.
4. Reemplazar llamadas jQuery `.modal()` en ecommerce/cart por `bootstrap.Modal`.
5. Migrar utilidades left/right por modulo, priorizando vistas activas y dejando exports/PDF para el final.
6. Auditar layouts separados: ecommerce, restaurant, system, auth y POS.
7. Solo al final actualizar dependencia Bootstrap y assets vendorizados Cuba/Porto.

## Gate minimo por bloque

Ejecutar:

```powershell
npm run prod
npm run qa:e2e:smoke
```

Validar manualmente con Playwright MCP:
- Login tenant.
- Dashboard carga sin errores de consola.
- POS: buscar producto, agregar, abrir acciones.
- Documents create/list: dropdowns, tooltips y modales.
- Ecommerce cart: modal de documento de identidad.
- Header tenant: tooltips e indicadores.

## Decision

Bootstrap 5 es la unica fase grande pendiente, pero debe hacerse por bloques. El primer bloque mas seguro es compat CSS + atributos `data-bs-*` en el layout tenant principal y componentes Vue activos. No tocar ecommerce/restaurant/system en el mismo commit.

## Fase 6.1 aplicada

Cambios realizados:
- `resources/sass/modern.scss`: bridge temporal BS4/BS5 para `form-group`, `btn-block`, badges, spacing left/right, text/float alignment, font weight/style, borders, input groups y custom forms basicos.
- `resources/js/vendor/custom.js`: bridge runtime para duplicar atributos `data-*` y `data-bs-*` antes de inicializar tooltips/popovers.
- Inicializacion compatible con BS4 jQuery plugins y BS5 `window.bootstrap.Tooltip/Popover`.

Validacion:
- `npm run prod`: OK.
- Playwright MCP dashboard: carga OK, 0 errores de consola.
- Warning restante: deprecacion conocida de Element Plus `type.text`, no relacionada con Bootstrap.

## Fase 6 — Migracion markup aplicada (2026-06-13)

Se aplico la migracion de markup BS4 -> BS5 a las superficies que corren Bootstrap 5
(admin tenant + POS-full), via scripts deterministas con boundary de clase:
`ml/mr/pl/pr -> ms/me/ps/pe`, `text-left/right -> start/end`, `float-*`, `font-weight-* -> fw-*`,
`form-group -> mb-3`, `no-gutters -> g-0`, `badge-color -> bg-*`, `custom-* -> form-check/form-select`,
`data-toggle/target/dismiss -> data-bs-*`, y unwrap de `input-group-append/prepend`.
Build verde, gate visual Playwright OK (dashboard, cajas, expenses, documents). 0 errores de consola.

## DECISION DE ARQUITECTURA — Bootstrap multi-version por layout (PERMANENTE)

La app NO usa una sola version de Bootstrap, y es **intencional**. Cada familia de layout
arrastra el tema con el que fue construida:

| Superficie | Tema | Bootstrap | Quien lo mantiene |
|---|---|---|---|
| **Admin tenant (farmacia)** | Cuba | **BS 5.3.3** | nosotros — migrado a BS5 |
| **POS pantalla completa** | mixto (app.css con puente) | **BS 5** | nosotros |
| **System (super-admin)** | porto-light | **BS 4.x** | **tercero (tema Porto)** |
| **Storefront ecommerce/restaurant** | porto-ecommerce | **BS 4.1.3** | **tercero (tema Porto)** |

### Por que NO migramos system ni el storefront a BS5

- **Los temas Porto (porto-light, porto-ecommerce) son productos de terceros** (ThemeForest),
  construidos sobre Bootstrap 4: su CSS, su `theme.js`, `main.min.js` y `plugins.min.js`
  asumen la API de BS4 y **llaman plugins jQuery eliminados en BS5** (`.modal()`, `.tab()`,
  `.collapse()`, `.tooltip()`, `.popover()`). Cambiar solo el bundle a BS5 **rompe el tema entero**
  (sliders, mega-menu, sticky header, carrito, checkout).
- Actualizar esos temas a su version BS5 **le corresponde al proveedor del tema**, no a nosotros.
  No modificamos assets de terceros vendorizados. NOTA: Porto YA tiene version BS5 (Porto Admin
  v4.3.0, ene-2025, es Bootstrap 5 + SCSS; lo instalado aqui es Porto viejo con **BS 4.1.0/4.1.3**
  de ~2018). El camino correcto es comprar/obtener el release Porto BS5 actual y reemplazar el
  paquete completo (porto-light, porto-ecommerce) + re-integrar; recien ahi se migra ese markup.
  Es una tarea de actualizacion de producto de terceros, no un port manual BS4->BS5 nuestro.
- **Restaurant** es codigo muerto (resto del SaaS base, no se usa en farmacia). No se invierte.
- **Storefront ecommerce** no se usa al 100% hoy; es feature futura (tienda web tipo mifarma).
  Cuando se construya en serio, se hace UI nueva sobre el stack moderno (Vue3/BS5/Vite),
  no sobre el Porto BS4 actual. Ver [reference_pro8_ecommerce] en memoria del proyecto.

### Como conviven sin romperse

- `mb-*/mt-*/mx-*/p-*` (escala de spacing) son IDENTICOS en BS4 y BS5 -> funcionan en todos lados.
- Solo difieren las direccionales `ms/me/ps/pe`, `text-start/end`, `fw-*`, `float-start/end`, `g-0`.
  Por eso las superficies BS4 (Porto) deben conservar el markup BS4 (`ml/mr`, `text-left/right`, etc).
- El puente CSS BS4/5 (`modern.scss` seccion 32) + el puente JS `data-bs-* <-> data-*`
  (`resources/js/vendor/custom.js`) cubren el admin tenant/POS y se cargan solo donde corresponde.
- **Regla:** NO aplicar utilidades/atributos BS5 en blades servidos por layouts Porto BS4
  (`system/layouts/*`, `modules/Ecommerce/.../layouts/*`, `modules/Restaurant/.../layouts/*`,
  `resources/views/tenant/ecommerce/*`). Si un script de migracion los toca, revertir esas
  superficies (ver commit `a9eda42d`).

**Conclusion:** Fase 6 (Bootstrap 5) se considera COMPLETA para lo que esta bajo nuestro control
(admin BS5). Las superficies Porto quedan en BS4 de forma consciente y documentada, pendientes de
que el proveedor del tema entregue su version BS5. No es deuda tecnica a resolver por nosotros.

## Insumo disponible: Porto BS5 descargado (para la tienda futura)

Ya se cuenta con el tema **Porto v7.8.5 (Bootstrap 5.0.1)** descargado en
`D:\DESCARGAS\Porto Theme v7.8.5\porto` — version **WordPress** (templates PHP de WP/WooCommerce
inservibles para Laravel; solo los assets `css/js/scss` BS5 son reutilizables).

NO es un reemplazo drop-in del Porto actual (~v4.x BS4.1.x): entre Porto 4 y 7 cambiaron clases,
estructura HTML de componentes, API de `theme.js` y utilidades de grid (BS4->BS5). Actualizar
implica **re-skinear** el markup de las vistas, no intercambiar archivos.

**Decision:** el storefront ecommerce NO se usa al 100% hoy (feature futura tipo mifarma), asi que
NO se invierte ahora. Cuando se construya la tienda en serio, se hace **nueva sobre Porto 7.x / BS5**
(idealmente con la version HTML standalone de Porto como referencia de markup, no la de WordPress),
reusando solo la logica de dominio del modulo Ecommerce. Hasta entonces, el storefront queda en
Porto BS4 funcional. Ver referencia de features en [reference_pro8_ecommerce] (memoria del proyecto).