sass-template-common 0.13.8 → 0.14.0

package/README.md

@@ -1,36 +1,36 @@
-# sass-template-common
-
-Librería web, maqueta de configuración y componentes para proyectos sass.
-
-## Publicar nueva versión
-
-Para que los cambios se reflejen al publicar:
-
-1. **Subir versión** (obligatorio; si no, npm rechaza o se usa la misma versión):
-   ```bash
-   pnpm version:patch   # 0.3.21 → 0.3.22
-   # o
-   pnpm version:minor   # 0.3.21 → 0.4.0
-   pnpm version:major   # 0.3.21 → 1.0.0
-   ```
-
-2. **Build limpio + publicar**:
-   ```bash
-   pnpm run clean && pnpm run build && pnpm publish
-   ```
-   O en un solo paso (patch):
-   ```bash
-   pnpm release:patch
-   ```
-
-3. **`prepublishOnly`**: Antes de cada `pnpm publish` se ejecuta `clean` + `build`, así siempre se publica un build nuevo.
-
-4. **En proyectos que consumen la lib**: Actualizar la dependencia y reinstalar:
-   ```bash
-   pnpm update sass-template-common
-   # o cambiar la versión en package.json y luego
-   pnpm install
-   ```
-   Si usan versión fija (`"0.3.21"`), hay que actualizarla a la nueva (p. ej. `"0.3.22"`).
-
-**Si no ves los cambios:** comprueba que subiste la versión (`version:patch` o similar), que hiciste `clean` + `build` antes de publicar, y que el proyecto consumidor tiene actualizada la dependencia (o `^0.3.21` y ha ejecutado `pnpm update`).
+# sass-template-common
+
+Librería web, maqueta de configuración y componentes para proyectos sass.
+
+## Publicar nueva versión
+
+Para que los cambios se reflejen al publicar:
+
+1. **Subir versión** (obligatorio; si no, npm rechaza o se usa la misma versión):
+   ```bash
+   pnpm version:patch   # 0.3.21 → 0.3.22
+   # o
+   pnpm version:minor   # 0.3.21 → 0.4.0
+   pnpm version:major   # 0.3.21 → 1.0.0
+   ```
+
+2. **Build limpio + publicar**:
+   ```bash
+   pnpm run clean && pnpm run build && pnpm publish
+   ```
+   O en un solo paso (patch):
+   ```bash
+   pnpm release:patch
+   ```
+
+3. **`prepublishOnly`**: Antes de cada `pnpm publish` se ejecuta `clean` + `build`, así siempre se publica un build nuevo.
+
+4. **En proyectos que consumen la lib**: Actualizar la dependencia y reinstalar:
+   ```bash
+   pnpm update sass-template-common
+   # o cambiar la versión en package.json y luego
+   pnpm install
+   ```
+   Si usan versión fija (`"0.3.21"`), hay que actualizarla a la nueva (p. ej. `"0.3.22"`).
+
+**Si no ves los cambios:** comprueba que subiste la versión (`version:patch` o similar), que hiciste `clean` + `build` antes de publicar, y que el proyecto consumidor tiene actualizada la dependencia (o `^0.3.21` y ha ejecutado `pnpm update`).

package/dist/sass-template-common.d.ts

@@ -155,9 +155,24 @@ export declare interface AutorInfo {
     };
 }
 
-export declare const BannerAdvertising: ({ banners, name, scope }: Props_28) => JSX.Element | null;
+export declare const BannerAdvertising: ({ banners, name, legacy, scope }: Props_28) => JSX.Element | null;
 
-export declare const BannerAdvertisingMiddle: ({ banners, index, scope }: Props_27) => JSX.Element | null;
+export declare const BannerAdvertisingMiddle: ({ banners, index, name, legacy, scope, }: Props_27) => JSX.Element | null;
+
+/**
+ * Arma la cadena de candidatos de una posición: primero la key canónica
+ * (nomenclatura nueva), después los alias legacy en orden.
+ *
+ * No deduplica por accidente: si un sitio pasa `legacy` igual al canónico el
+ * resultado es el mismo lookup una sola vez.
+ */
+export declare const bannerKeyCandidates: (canonical: string, legacy?: BannerLegacyKey) => string[];
+
+/**
+ * Nombres legacy de una posición de banner. Acepta un string o una lista
+ * ordenada (de más a menos prioritario).
+ */
+export declare type BannerLegacyKey = string | string[] | undefined;
 
 export declare interface BannerResponse {
     key: string;
@@ -1241,6 +1256,22 @@ export declare function fetchWithConfigCache<T>(cacheKey: string, fetchFn: () =>
     staleOnError?: boolean;
 }): Promise<T>;
 
+/**
+ * Resuelve una posición de banner contra la respuesta del CMS con fallback a
+ * nomenclatura vieja.
+ *
+ * REGLA DE CAÍDA — **solo por ausencia**. Se devuelve la primera key que
+ * EXISTE en el array, sin mirar `show` ni `value`. Si la key canónica está
+ * presente pero apagada (`show: false`) NO se cae al legacy: apagar un banner
+ * es una decisión deliberada de tráfico y el fallback no debe revivirlo.
+ *
+ * Los guards de `show`/`value` los sigue aplicando cada componente sobre el
+ * `BannerResponse` devuelto, exactamente como antes de este helper. Por eso,
+ * sin `legacy`, el comportamiento es byte-idéntico al `banners.find(...)`
+ * original: misma búsqueda, mismo resultado.
+ */
+export declare const findBanner: (banners: Array<BannerResponse> | undefined, canonical: string, legacy?: BannerLegacyKey) => BannerResponse | undefined;
+
 export declare const Font: ({ config }: {
     config: Config;
 }) => JSX.Element | null;
@@ -1631,6 +1662,26 @@ declare type HeaderProps = {
     custom_styles?: CSSProperties;
     mobileIcon?: any;
     customComponent?: ReactNode;
+    /**
+     * [banners] Slot `pre_header`: contenido que se renderiza ARRIBA de la barra
+     * del header estatico, en flujo normal dentro del `<header>`. Pensado para el
+     * banner `pre_header` (posicion no estandar: la mayoria de los sitios no la
+     * usa).
+     *
+     * Solo se pinta en el header ESTATICO, nunca en el sticky: el sticky es la
+     * barra compacta del scroll y duplicar ahi el creativo seria una segunda
+     * impresion del mismo slot publicitario.
+     *
+     * CONTRATO DE ALTURA — el header esta pineado (`position: fixed/absolute;
+     * top: 0`) y el contenido lo despeja con un `margin-top` fijo. Un sitio que
+     * active `pre_header` DEBE declarar la altura reservada:
+     *
+     *     :root { --pre-header-height: 90px; }
+     *
+     * `headers-header-1.css` la suma al margen del contenido. Default `0px`, asi
+     * que sin el slot el layout queda byte-identico.
+     */
+    preHeader?: ReactNode;
     prerender_classes?: {
         alert?: string;
     };
@@ -2062,6 +2113,33 @@ export declare type LibraryConfig = {
         middle?: boolean;
         innote?: boolean;
     };
+    /**
+     * [banners] Nomenclatura de keys de banners. **Solo gatea los renombres que
+     * REUSAN un nombre existente**; el resto de la nomenclatura nueva
+     * (`post_header`, `pre_footer`, `pre_header`, `destacado_N`,
+     * `destacado_middle`, `block_N_middle`, `body_N`) no pasa por acá: son
+     * nombres nuevos, sin colisión posible, y se resuelven siempre con fallback
+     * canónico → legacy vía `findBanner`.
+     *
+     * - `'legacy'` (**default**) — comportamiento histórico, byte-idéntico.
+     *   Los middles dinámicos del home siguen siendo `middle_dynamic_<slot>` y
+     *   los middles de nota siguen numerados desde `middle_2`.
+     * - `'v2'` — los middles dinámicos del home pasan a `middle_<slot>` (con
+     *   fallback a `middle_dynamic_<slot>`) y la nota renumera sus middles
+     *   arrancando en `middle_1`.
+     *
+     * POR QUÉ ES UN FLAG Y NO UN FALLBACK MÁS. Estos dos casos no son un
+     * renombre, son un SWAP: `middle_N` sigue existiendo después del cambio pero
+     * apunta a otra posición física. Con fallback gradual, un sitio a medio
+     * migrar resolvería el `middle_1` viejo (estático, arriba) desde la posición
+     * nueva (dinámica, abajo) y duplicaría el banner. El flag garantiza que no
+     * exista estado mixto: se da vuelta el mismo día que se renombran las keys
+     * en el CMS.
+     *
+     * Cutover por sitio. Un sitio en `'legacy'` no ve NINGÚN cambio de
+     * comportamiento por este refactor.
+     */
+    CONFIG_bannerKeys?: 'legacy' | 'v2';
     /**
      * [banners] Rutas cuyo contenido de banners depende de que exista un query
      * string (ej. `'buscar'`: sin query no hay resultados → no hay banners). Para
@@ -3212,13 +3290,36 @@ declare type Props_26 = {
 
 declare type Props_27 = {
     banners: Array<BannerResponse>;
-    index: string | number;
+    /**
+     * Sufijo numérico histórico: la key resuelta es `middle_${index}`. Se sigue
+     * soportando tal cual — todos los call sites que no migraron lo usan.
+     * Ignorado si se pasa `name`.
+     */
+    index?: string | number;
+    /**
+     * Key canónica COMPLETA, sin prefijo `middle_`. Es la vía para las
+     * posiciones que dejaron de ser un middle numerado (`post_header`,
+     * `pre_footer`, `pre_header`, `destacado_middle`, `block_N_middle`).
+     */
+    name?: string;
+    /**
+     * Key(s) con las que esta posición se llamaba antes. Solo se consultan si la
+     * canónica no está en la respuesta del CMS. Ver `findBanner`.
+     */
+    legacy?: BannerLegacyKey;
     scope?: BannerScope;
 };
 
 declare type Props_28 = {
     banners: Array<BannerResponse>;
+    /** Key canónica (nomenclatura nueva). */
     name: string;
+    /**
+     * Key(s) con las que esta misma posición se llamaba antes. Se usan solo si
+     * `name` NO está en la respuesta del CMS, así el renombre es inerte hasta
+     * que se actualicen los banners. Ver `findBanner`.
+     */
+    legacy?: BannerLegacyKey;
     scope?: BannerScope;
 };