@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-date-selector/README.md

@@ -0,0 +1,183 @@
+---
+name: sui-date-selector
+selector: sui-date-selector
+resumen: La cabecera de un calendario con el mes y las flechas de anterior y siguiente
+alternativas: [sui-datepicker (el calendario completo, que ya la trae), sui-segmented-control (2 a 4 días o períodos fijos), sui-tab-chips (5 o más)]
+---
+
+# sui-date-selector
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-date-selector`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+Story: [Molecules/Date & Time/Date Selector](https://sui-design-system.web.app/?path=/docs/molecules-date-time-date-selector--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** como cabecera de un **calendario armado a mano** o de una vista que se recorre por
+mes o por semana: «Octubre 2026» con flechas para ir al mes anterior o al siguiente (los gastos
+del mes, las ganancias del repartidor por mes).
+
+**No lo uses** para:
+
+- Un calendario completo: `sui-datepicker` ya lo trae adentro.
+- Elegir entre pocos días: `sui-tab-chips` (como la hoja de pedido programado).
+- Cambiar entre períodos fijos («Hoy», «Esta semana», «Este mes»): `sui-segmented-control` si son 2 a 4,
+  `sui-tab-chips` si son 5 o más. **Período o filtro con 2 a 4 opciones excluyentes → `sui-segmented-control`; con 5 o más, o si no caben y tienen que deslizarse → `sui-tab-chips`** (canon, dueño 04-10-2026).
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente** (vive dentro del datepicker). Las
+> reglas de uso quedaron aprobadas por el dueño (canon, 05-10-2026).
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. Lo usa por dentro
+> `sui-datepicker`.
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `label` | texto | El período visible, con mayúscula inicial y sin abreviar: «Octubre 2026», «Semana del 6 al 12 de octubre». | mayúscula inicial: canon (CANON-SUI §5.1, sentence case) · sin abreviar: canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `leftIcon` + `rightIcon` | `true` / `true` (default) | Lo normal: se puede ir atrás y adelante. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `rightIcon` | `false` | Ya se está en el período actual y no hay futuro que mirar (ganancias, gastos). Mejor que dejar la flecha y que no haga nada. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `leftIcon` | `false` | Ya se está en el primer período con datos (el mes en que se abrió el local). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| los dos en `false` | — | No usar: sin flechas es un título; va un texto. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `disabled` | `true` | Mientras carga el período nuevo, para que no se encadenen toques. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+Tiene `size`: **`medium`** (default, 288 × 36, flechas `sui-compact-button` de 24, Figma) y
+**`large`** (52 de alto, flechas de **44 × 44** con el ícono en 20, mes en 16/24). El
+`sui-datepicker` `xlarge` usa `large`.
+
+| size | barra | flechas | texto | uso | fuente |
+|---|---|---|---|---|---|
+| `large` | 52 (44 + 4 de aire arriba y abajo) | **44 × 44** | 16/24 | mobile | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono |
+| `medium` (default) | 36 | 24 × 24 | 14/20 | web | medido (Figma 442:192) |
+
+```html
+<sui-date-selector size={bp.tactil() ? 'large' : 'medium'} label="Octubre 2026"
+                   rightIcon={!esMesActual()} onPrev={() => mesAnterior()} onNext={() => mesSiguiente()} />
+```
+
+Dentro del `sui-datepicker` `large` (y en mobile con `small`–`large`) el datepicker agranda las
+flechas a 40 por su cuenta; con `xlarge` usa este `size="large"` (44).
+
+### Por dispositivo (D16)
+
+No está en la tabla por componente de D16; las flechas se tocan, así que va como **lo que se
+toca** (dueño, 05-10-2026). `large` es el único size con flechas de 44.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `medium` + área 44 | interino: hoy `large`, porque el DS todavía no estira a 44 el área de las flechas de 24 del `medium` |
+| celular (380–767) | `large` | barra de 52, flechas de 44 |
+| tablet táctil (`pointer: coarse`) | `large` | Apple pide 44 pt también en iPad |
+| computadora (`pointer: fine`) | `medium` | barra de 36, flechas de 24 |
+
+Ultrawide: igual que la computadora; el ancho sigue fijo en 288.
+
+En master-pedidos: `size={bp.tactil() ? 'large' : 'medium'}` (son los mismos literales que
+devuelve `bp.sizeControl()`, que también sirve).
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente suelto (0 usos) | no hay vistas que se recorran mes a mes | ganancias del repartidor o gastos del super admin «por mes», en web |
+| los dos íconos apagados | sin flechas es un título | ninguno |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `disabled` | `disabled` | `boolean` | `false` |
+| `label` | `label` | `string` | — (requerido) |
+| `leftIcon` | `left-icon` | `boolean` | `true` |
+| `rightIcon` | `right-icon` | `boolean` | `true` |
+| `size` | `size` | `"large" \| "medium"` | `'medium'` |
+
+| evento | `event.detail` |
+|---|---|
+| `next` | `void` |
+| `prev` | `void` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `fecha.mesAnterior` | Mes anterior | — |
+| `fecha.mesSiguiente` | Mes siguiente | — |
+<!-- textos:fin -->
+
+## Trampas
+
+- **`leftIcon` y `rightIcon` son booleanos**, no nombres de ícono: prenden o apagan las flechas.
+- **Ancho fijo de 288 px** (`max-width` incluido): no se estira con el contenedor.
+- Con una flecha apagada queda un hueco del ancho de la flecha (24 px en `medium`, 44 en `large`)
+  para que el texto siga centrado.
+- El componente **no sabe de fechas**: el texto lo arma quien lo usa y las flechas solo emiten.
+- Los `aria-label` de las flechas dicen «Mes anterior» y «Mes siguiente» aunque el período sea
+  una semana.
+
+## Bien y mal
+
+**Las flechas en el teléfono**
+
+```html
+<!-- ❌ mal: `medium` deja las flechas en 24 en el celular y la tablet -->
+<sui-date-selector label="Octubre 2026" onPrev={() => mesAnterior()} onNext={() => mesSiguiente()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-date-selector size={bp.tactil() ? 'large' : 'medium'} label="Octubre 2026"
+                   onPrev={() => mesAnterior()} onNext={() => mesSiguiente()} />
+```
+
+**Ya se está en el mes actual**
+
+```html
+<!-- ❌ mal: los dos en `false` es un título con fondo; y abrevia el mes («Qué variante usar») -->
+<sui-date-selector label="Oct. 2026" left-icon="false" right-icon="false" />
+```
+
+```html
+<!-- ✅ bien: se apaga solo la flecha que no lleva a nada -->
+<sui-date-selector label="Octubre 2026" right-icon="false" onPrev={() => mesAnterior()} />
+```
+
+**Períodos fijos**
+
+```html
+<!-- ❌ mal: «Hoy», «Esta semana», «Este mes» no se recorren con flechas («Cuándo no») -->
+<sui-date-selector label={periodo()} onPrev={() => periodoAnterior()} onNext={() => periodoSiguiente()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-segmented-control tabs={periodos} active={periodo} onActiveChange={(e) => (periodo = e.detail)} aria-label="Período" />
+```
+
+## Ejemplo
+
+```html
+<sui-date-selector size={bp.tactil() ? 'large' : 'medium'} label="Octubre 2026"
+                   right-icon="false" onPrev={() => mesAnterior()} />
+```

package/docs/sui-datepicker/README.md

@@ -0,0 +1,323 @@
+---
+name: sui-datepicker
+selector: sui-datepicker
+resumen: Calendario para elegir una fecha o un rango de fechas, en popover o en línea
+alternativas: [sui-input type="date" (una fecha suelta en un formulario: abre el selector del sistema), sui-tab-chips + sui-radio-label (día y franja de un pedido programado), sui-segmented-control (2 a 4 períodos fijos: hoy, 7 días, 30 días), sui-tab-chips (5 o más períodos fijos)]
+---
+
+# sui-datepicker
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-datepicker`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+Story: [Molecules/Date & Time/Datepicker](https://sui-design-system.web.app/?path=/docs/molecules-date-time-datepicker--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir un **rango de fechas** (desde–hasta) con presets al costado, o para mostrar
+un **calendario en línea** donde importa ver el mes entero (días con pedidos marcados con
+`markedDates`, días bloqueados con `min`/`max`).
+
+**No lo uses** para:
+
+- **Una fecha suelta en un formulario** («Válido hasta», «Fecha del gasto»): `sui-input type="date"`.
+  En el celular abre el selector del sistema, mide 48 px en `large` y no tapa la pantalla con un
+  popover de 368 px.
+- **El día y la hora de un pedido programado**: el checkout ya tiene su hoja (`sui-modal-sheet`
+  con `sui-tab-chips` para el día y `sui-radio-label` con `flip` para la franja). Es la maqueta
+  aprobada.
+- **Períodos fijos** («Hoy», «Últimos 7 días», «Este mes») sin rango libre: `sui-segmented-control`
+  si son 2 a 4, `sui-tab-chips` si son 5 o más o se deslizan (canon, dueño 04-10-2026).
+- Una hora: `sui-time-picker`.
+
+Regla corta: **rango o calendario visible → datepicker · una fecha en un formulario → `sui-input
+type="date"` · día + franja de entrega → la hoja del checkout.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS** (página del datepicker): sirve para elegir **una fecha o un rango
+> de fechas**, y trae tres ejemplos: **Popover** (se aplica al tocar el día), **Approval** (con
+> Cancelar/Aplicar: la fecha queda en espera hasta confirmar) y **Range** (rango con un solo mes a
+> la vista). No dice cuándo usar cada uno. Las reglas marcadas canon están aprobadas; lo que sigue en propuesta espera decisión.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **0 usos**.
+> Las fechas de la app van con `sui-input type="date"` (7) y `type="datetime-local"` (1).
+
+### `mode`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `date` (default) | Una fecha cuando el calendario tiene que verse (en línea, con días marcados). Si es un campo de formulario, va `sui-input type="date"`. | guía (una fecha) · el «cuándo» es propuesta |
+| `range` | Un período libre desde–hasta: reportes, filtros de ventas o de gastos con «Personalizado». | guía (rango) · el «cuándo»: canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+
+### `inline`, `showFooter`, `calendars`
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `inline` | `false` (default) | El campo abre el calendario en un popover. Solo en web. | guía (ejemplo Popover) |
+| `inline` | `true` | El calendario es el contenido: un panel de disponibilidad o el calendario de pedidos del día. También dentro de un `sui-modal` en mobile, para no depender del popover. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `showFooter` | `true` (default) | Cancelar/Aplicar: la elección no se guarda hasta confirmar. Úsalo cuando cambiar la fecha recalcula algo caro (un reporte). | guía (ejemplo Approval) |
+| `showFooter` | `false` | Se aplica al tocar el día. Fecha única y nada que recalcular. En `range` no tiene efecto: el rango siempre trae footer. | guía (ejemplo Popover) |
+| `calendars` | `2` (default) | Rango en web: dos meses lado a lado (936 px). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `calendars` | `1` | Rango en un espacio angosto (columna, modal `medium`, tablet en vertical: los 936 px necesitan ≥ 968 de ancho). En mobile (≤ 767) se fuerza a 1 solo; en tablet hay que pasarlo. | guía (Range con un mes) |
+
+### `min`, `max`, `markedDates`, `presets`, `placeholder`, `disabled`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `min` / `max` | Siempre que haya un límite real: un cupón no vence en el pasado (`min` = hoy), un reporte no pasa de hoy (`max` = hoy). Los presets se recortan al límite. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `markedDates` | Días con algo: pedidos programados, gastos cargados. El punto es chico: dice «hay algo», no cuánto. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `presets` | Los 8 de fábrica están en español (Hoy, Últimos 7 días… Todo el tiempo). Recortarlos a los que la pantalla usa: un reporte del local no necesita «Últimos 12 meses» si no hay datos de hace un año. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `placeholder` | Sin pasarlo, el campo dice «Elige una fecha» (`mode="date"`) o «Elige el período» (`mode="range"`), en imperativo con tuteo. Cambiarlo solo para decir qué se elige, también en imperativo («Elige desde cuándo»). | canon (dueño, 05-10-2026, P4 a); el default cambió en la 0.25.0 (antes «Seleccionar fecha» en los dos modos). CANON-SUI §5.7 (infinitivo) necesita esta excepción en master-pedidos |
+| `disabled` | Mientras carga lo que depende de la fecha. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+
+Usos de hoy que rompen la regla: **0** (no hay datepickers). Los 8 campos de fecha son fechas
+sueltas en formularios y ya usan `sui-input` (líneas del `type`, medidas el 04-10-2026):
+`pages/discounts/discounts.html:189` y `:301` («Válido hasta»), `pages/super-admin/super-admin.html:324`,
+`:330` y `:419`, `pages/super-admin/master-gastos/master-gastos.html:220`,
+`pages/central/central-gastos/central-gastos.html:115`, y `pages/promociones/promociones.html:341`
+(`datetime-local`, «Programar»).
+
+**A decidir por el dueño** (la regla de arriba es la lectura plana; la contraria también se sostiene):
+
+| opción | a favor | en contra |
+|---|---|---|
+| fecha suelta → `sui-input type="date"` (la propuesta) | selector del sistema, 48 px, cero código nuevo, 0 cambios en la app | se ve distinto en iOS, Android y web; no marca días |
+| toda fecha → `sui-datepicker` | se ve igual en todos lados, con la marca | el popover de 368 px no es hoja en mobile, el trigger mide 40 px si no se pasa `size="large"`, las celdas de día miden 40 y los presets 36 (ver «Tamaño») |
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: lo que se toca mide **44 px o más** (canon del dueño, 04-10-2026).
+Para eso está **`xlarge`**: con los otros sizes las celdas de día (40) y los presets (36) no llegan.
+En la computadora va `medium`, nunca `small`; la tablet va como el celular (canon, dueño, 05-10-2026, D16). En pantallas de los
+dos se elige con el servicio de breakpoints de la app (`bp`, en `services/breakpoints.service.ts`).
+
+Tiene `size` para el campo: `small` (36), `medium` (40, default, el de siempre), **`large` (48)**,
+el mismo alto que `sui-input` y `sui-select` `large`, y **`xlarge` (52)**, el de `sui-input` `xlarge`.
+Con `large` **y siempre en mobile (≤ 767 px)** el panel también crece: **flechas de mes de 40** y
+**Cancelar / Aplicar en `large` (48)**. Con **`xlarge`** todo lo que se toca llega a 44: **días de
+44 × 44** (`sui-day-cell` `large`, gap 4: grilla de 7 × 44 + 6 × 4 = 332, panel de 358 con padding y borde: entra en una pantalla de 390, y dentro de un modal fullscreen solo con `fullBody`, ver «Por dispositivo»), **flechas de mes de
+44** (`sui-date-selector` `large`, barra de 52) y **rangos predefinidos de 44** (`sui-period-range`
+`large`). En el teléfono el footer del rango pone el resumen «Rango: …» arriba y los dos botones
+abajo, 50/50.
+
+| pieza | web (`medium`) | `large` | mobile (`small`–`large`) | **`xlarge`** | fuente |
+|---|---|---|---|---|---|
+| campo (trigger) | 40 | 48 | el del `size` | **52** | 40: medido · 36 y 48: canon (aprobado por el dueño, 03-10-2026), extensión SUI · 52: canon (dueño, 04-10-2026): piso táctil 44 en el teléfono |
+| celda de día | 40 × 40, paso de 48 | igual | 40 × 40, paso de 44 (**no llega a 44**) | **44 × 44**, paso de 48 | 40: medido · 44: canon (dueño, 04-10-2026): piso táctil 44 en el teléfono |
+| preset del rango (`sui-period-range`) | 168 × 36 | igual | 36 de alto, en fila que se desliza (**no llega a 44**) | **44** de alto | 36: medido · 44: canon (dueño, 04-10-2026): piso táctil 44 en el teléfono |
+| flechas de mes | 24 | 40 | 40 | **44** | 40: canon (aprobado por el dueño, 03-10-2026) · 44: canon (dueño, 04-10-2026): piso táctil 44 en el teléfono |
+| Cancelar / Aplicar | 36 | 48 | 48 | 48 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): con `large` y `xlarge`, la fecha del
+campo (y su placeholder) va en 16/24. Con `large` el calendario no cambia (días, mes y resumen en
+14); con `xlarge` los días, el mes y los rangos predefinidos también van en 16/24 (sus piezas son
+`large`). El resumen del rango sigue en 14.
+
+```html
+<!-- Web: popover. Mobile: en línea dentro de un sui-modal fullscreen con full-body
+     (sin él el body deja ancho − 56 y el panel de 358 no entra; ver «Por dispositivo»). -->
+@if (bp.isMobile()) {
+  <sui-datepicker mode="range" size="xlarge" inline calendars="1" value={rango} onValueChange={(e) => (rango = e.detail)} />
+} @else {
+  <sui-datepicker mode="range" size={bp.tactil() ? 'xlarge' : 'medium'}
+                  calendars={bp.isTablet() ? 1 : 2}
+                  placeholder="Elige el período" value={rango} onValueChange={(e) => (rango = e.detail)} />
+}
+```
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| fecha en un formulario | `xlarge` (días de 44) | `medium` | mobile: canon (dueño, 04-10-2026): piso táctil 44 en el teléfono · web: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| filtro de período de un reporte | `xlarge`, en línea dentro de un modal con `fullBody` | `medium`, popover | mobile: canon (dueño, 04-10-2026): piso táctil 44 en el teléfono · web: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+
+### Por dispositivo (D16)
+
+El datepicker tiene fila propia en D16: los días solo llegan a 44 en `xlarge`, así que todo
+dispositivo táctil va en `xlarge`, también el celular chico.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `xlarge` | **no entra en 360 hoy** (en 375 solo `mode="date"` con `fullBody`, por 1 px). La grilla de días mide 332 (7 × 44 + 6 × 4), pero el panel mide **358** (332 + 2 × 12 de padding + borde). Dentro de un `sui-modal` fullscreen el body deja `ancho − 56` (8 de inset y 20 de padding por lado): 304 en 360. Con `full-body` deja `ancho − 16`: 344 en 360, 359 en 375. En `range` además el panel se fija en `ancho − 32` (328 en 360, 343 en 375) y recorta el domingo. Pendiente: que quepa en 360 es código del DS (gap o padding del calendario), no del README |
+| celular (380–767) | `xlarge` | en línea dentro de un `sui-modal` fullscreen **con `full-body`**: sin él el body deja 334 en 390 y el panel de 358 se sale. Con él quedan 374 en 390. Se fuerza a 1 calendario |
+| tablet táctil (`pointer: coarse`) | `xlarge` | popover. En `mode="date"` el panel mide 368 y entra desde 768. En `range` con 2 calendarios mide 936 (200 + 2 × 368) y necesita ≥ 968 de ancho: un iPad en vertical (820–834) lo recorta, así que va con `calendars="1"` (200 + 368 = 568). Los días, flechas y rangos llegan a 44 por el `size`, no por el ancho |
+| computadora (`pointer: fine`) | `medium` | popover. Ojo: con `medium` el componente pinta Cancelar / Aplicar en `small` (36) por dentro (`footerButtonSize()`); D16 no deja nada en `small`, pero cambiarlo es código del DS, no del README |
+
+Ultrawide: igual que la computadora; el rango ya ocupa sus dos meses (936 px) y el espacio extra no
+agranda nada. Fuente: D16, dueño 05-10-2026.
+
+En master-pedidos: `size={bp.tactil() ? 'xlarge' : 'medium'}` (no hay helper que dé
+`xlarge`/`medium`). `bp.isMobile()` decide solo si va en línea o en popover, que es cuestión de
+ancho, no de puntero. En `range` fuera del celular, `calendars={bp.isTablet() ? 1 : 2}`: el
+componente solo baja a 1 calendario por su cuenta hasta 767. `isTablet()` es hasta 1024, un poco
+conservador (en 1024 los dos meses sí entran), pero es la señal que tiene el servicio.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | las fechas de la app son sueltas y van con `sui-input type="date"`; los períodos son fijos | un filtro «Personalizado» en el resumen de ventas o en gastos del super admin (`mode="range"`) |
+| `mode="date"` en un formulario | `sui-input type="date"` hace lo mismo con el selector del sistema | un calendario que se ve siempre, con días marcados (pedidos programados de la semana para el local) |
+| `markedDates` | no hay calendarios a la vista | días con pedidos programados o con gastos cargados |
+| `calendars="2"` en mobile | se fuerza a 1 solo | — |
+| el popover (`inline=false`) en mobile | no es hoja: es un panel flotante de 368 px (aunque el campo `large` mida 48) | ninguno en mobile; en web, cualquiera |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `calendars` | `calendars` | `1 \| 2` | `2` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `inline` | `inline` | `boolean` | `false` |
+| `markedDates` | — (solo por propiedad JS) | `readonly Date[]` | `[]` |
+| `max` | — (solo por propiedad JS) | `Date \| null` | `null` |
+| `min` | — (solo por propiedad JS) | `Date \| null` | `null` |
+| `mode` | `mode` | `"date" \| "range"` | `'date'` |
+| `placeholder` | `placeholder` | `null \| string` | `null` |
+| `presets` | — (solo por propiedad JS) | `SuiDatepickerPreset[]` | `[
+  { id: 'today',          label: 'Hoy',              resolve: (t) => [startOfDay(t), startOfDay(t)] },
+  { id: 'last-7',         label: 'Últimos 7 días',   resolve: (t) => [startOfDay(subDays(t, 6)), startOfDay(t)] },
+  { id: 'last-30',        label: 'Últimos 30 días',  resolve: (t) => [startOfDay(subDays(t, 29)), startOfDay(t)] },
+  { id: 'last-3-months',  label: 'Últimos 3 meses',  resolve: (t) => [startOfDay(subMonths(t, 3)), startOfDay(t)] },
+  { id: 'last-12-months', label: 'Últimos 12 meses', resolve: (t) => [startOfDay(subYears(t, 1)), startOfDay(t)] },
+  { id: 'month-to-date',  label: 'Mes en curso',     resolve: (t) => [startOfMonth(t), startOfDay(t)] },
+  { id: 'year-to-date',   label: 'Año en curso',     resolve: (t) => [startOfYear(t), startOfDay(t)] },
+  { id: 'all-time',       label: 'Todo el tiempo',   resolve: () => [null, null] },
+]` |
+| `showFooter` | `show-footer` | `boolean` | `true` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xlarge"` | `'medium'` |
+| `value` | — (solo por propiedad JS) | `Date \| SuiDateRange \| null` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `closed` | `void` |
+| `opened` | `void` |
+| `valueChange` | `Date \| SuiDateRange \| null` |
+
+### Diferencias con el SUI Angular
+
+- **Eventos solo de aquí:** `closed`, `opened`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `fecha.rangos` | Rangos predefinidos | — |
+| `fecha.eligePeriodo` | Elige el período | `placeholder` |
+| `fecha.eligeFecha` | Elige una fecha | `placeholder` |
+| `fecha.elegirPeriodo` | Elegir período | — |
+| `fecha.elegirFecha` | Elegir fecha | — |
+<!-- textos:fin -->
+
+Es `ControlValueAccessor`: con `mode="date"` el valor es `Date | null`; con `mode="range"`,
+`{ start, end }`.
+
+```ts
+interface SuiDateRange { start: Date | null; end: Date | null; }
+interface DatepickerPreset { id: DatepickerPresetId; label: string; resolve: (hoy: Date) => [Date | null, Date | null]; }
+```
+
+## Trampas
+
+- El footer dice «Cancelar», «Aplicar» y «Rango: 1 de oct 2026 – …» (antes venía en inglés). No
+  hay input para cambiarlos.
+- **En mobile no es una hoja**, aunque el comentario del código lo diga: es el mismo popover
+  absoluto, de 368 px de ancho, debajo del campo. Para el celular, `inline` dentro de un modal.
+- **`value` cambia de tipo con `mode`**: `Date` en `date`, `{ start, end }` en `range`. Al cambiar
+  el `mode` hay que resetear el valor.
+- Con `inline`, el `value` de entrada se pinta marcado y el calendario abre en su mes (arreglado
+  el 03-10-2026; antes solo se copiaba al abrir el popover, que en línea nunca se abre).
+- El mes sale con mayúscula inicial («Octubre 2026»), arreglado el 03-10-2026.
+- **El rango siempre trae footer**, aunque `showFooter` sea `false`.
+- **El trigger no es un `sui-input`**: no tiene `label`, `hint` ni `error` (sí `size`). El label va
+  aparte con `sui-form-label`.
+- En mobile (hasta 767 px) **se fuerza un solo calendario** aunque `calendars` sea 2.
+- El campo muestra la fecha como `dd/MM/yyyy`; el rango, como «1 de oct 2026 – 7 de oct 2026».
+- «Todo el tiempo» devuelve `{ start: null, end: null }`: quien lo recibe tiene que tratarlo como
+  «sin filtro», no como «vacío». El campo muestra «Todo el tiempo» (antes caía al placeholder y
+  parecía vacío; fix 04-10-2026). Un `{ start: null, end: null }` que llega de afuera se sigue
+  mostrando como placeholder: el componente no sabe si es «todo» o «nada».
+- **Accesibilidad (04-10-2026)**: el panel es un `dialog` modal con nombre («Elegir fecha» /
+  «Elegir período»; `group` en `inline`), la fila LU…DO está dentro de la grilla, cada día se
+  anuncia con la fecha completa («martes 7 de octubre de 2026»), hoy lleva `aria-current="date"`,
+  inicio y fin del rango salen seleccionados, y las flechas mueven el foco entre días (← → un
+  día, ↑ ↓ una semana, Inicio/Fin a la punta de la semana). Las flechas no cambian de mes.
+  El pie (Cancelar/Aplicar) y la lista de rangos predefinidos son `div` (la lista con
+  `role="group"`), no `<footer>`/`<aside>`: esos crean landmarks de página y dos pickers en la
+  misma pantalla los duplicaban (09-10-2026).
+- Cierra con clic afuera y con Escape, y eso **descarta** la elección (como Cancelar).
+- Las piezas internas son `sui-date-selector`, `sui-day-label`, `sui-day-cell` y
+  `sui-period-range`: no se arman a mano.
+
+## Bien y mal
+
+Una fecha suelta en un formulario
+
+```html
+<!-- ❌ mal: un popover de 368 px para un campo «Válido hasta» (Cuándo no) -->
+<sui-form-label label="Válido hasta" />
+<sui-datepicker min={hoy} value={venceEl} onValueChange={(e) => (venceEl = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-input type="date" label="Válido hasta" size={bp.sizeControl()} value={venceEl} onValueChange={(e) => (venceEl = e.detail)} />
+```
+
+Período en el celular
+
+```html
+<!-- ❌ mal: en el celular el popover no es hoja (Trampas), y en medium los días miden 40
+     (Tamaño en mobile y en web) -->
+<sui-datepicker mode="range" value={rango} onValueChange={(e) => (rango = e.detail)} />
+```
+
+```html
+<!-- ✅ bien: [fullBody] porque el panel xlarge mide 358 y el body con padding deja 334 en 390.
+     En < 380 todavía no entra (pendiente del DS, ver «Por dispositivo») -->
+<sui-modal open={eligiendo} onOpenChange={(e) => (eligiendo = e.detail)} fullscreen full-body title="Elige el período">
+  <sui-datepicker mode="range" size="xlarge" inline calendars="1" value={rango} onValueChange={(e) => (rango = e.detail)} />
+</sui-modal>
+```
+
+Rango que se aplica al tocar
+
+```html
+<!-- ❌ mal: en range el footer sale igual; showFooter no tiene efecto (Trampas) -->
+<sui-datepicker mode="range" show-footer="false" value={rango} onValueChange={(e) => (rango = e.detail)} />
+```
+
+```html
+<!-- ✅ bien: el rango siempre confirma con Aplicar; show-footer="false" es solo para mode="date" -->
+<sui-datepicker mode="range" max={hoy} value={rango} onValueChange={(e) => (rango = e.detail)} />
+```
+
+## Ejemplo
+
+```html
+<!-- Filtro de ventas con rango libre (web) -->
+<sui-form-label label="Período" />
+<sui-datepicker mode="range" placeholder="Elige el período" max={hoy} value={rango} onValueChange={(e) => (rango = e.detail)} />
+
+<!-- Calendario a la vista con los días que tienen pedidos programados -->
+<sui-datepicker inline show-footer="false" markedDates={diasConPedidos()}
+                value={diaElegido} onValueChange={(e) => (diaElegido = e.detail)} />
+```