sass-template-common 0.10.1 → 0.10.11

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

@@ -51,6 +51,15 @@ export declare type Analytics = {
     comscore: string | undefined;
 };
 
+/**
+ * Red de seguridad runtime para consumidores JS (sin type-check). El tipo
+ * marca la forma en build; esto valida presencia de cada slot y que matchee
+ * el formato exacto en runtime — enforcement doble, decisión del owner (§3).
+ */
+export declare function assertImageSizesContract(x: unknown): asserts x is ImageSizesContract;
+
+export declare const assetsImagesPrefixer: (imagePath: string, assetsClient?: string) => string;
+
 export declare const AssetsPreconnect: () => false | "" | JSX.Element | undefined;
 
 export declare function auditConfigOrigin(entry: ConfigOriginAuditEntry): void;
@@ -179,15 +188,14 @@ export declare const bannersReplace: (bannerLineAd: string, replaces?: {
 }) => string;
 
 /**
- * Splits a single large news-list fetch into `batchCount` parallel requests
- * of `batchSize` items each, then combines results in order.
+ * Variante metadata: mismo split que `createBatchedFetch` pero devuelve
+ * `hasNextPage` (último batch lleno) y el primer response crudo, para derivar
+ * next/prev y el título de sección. Lee el conteo de batches del MISMO
+ * `CONFIG_batchedFetch` que el render (vía `resolveBatchCount`), de modo que la
+ * paginación de metadata y la lista visible nunca discrepan.
  *
- * Page mapping (batchCount=3, newsListLimit=45 → batchSize=15):
- *   userPage=1 → API pages 1, 2, 3  (items 1–45)
- *   userPage=2 → API pages 4, 5, 6  (items 46–90)
- *
- * hasNextPage is true when the last batch came back full (length === batchSize),
- * which is equivalent to the original `data.length === newsListLimit` check.
+ * `ceil` (antes `floor`) alinea la matemática con `createBatchedFetch`; para los
+ * totales usados en prod (45, 15) ambos coinciden por ser divisibles.
  */
 export declare function batchedNewsFetch({ fetchFn, baseParams, userPage, newsListLimit, batchCount, }: BatchFetchParams): Promise<BatchFetchResult>;
 
@@ -308,6 +316,9 @@ declare interface CarruselCardProps extends Omit<CarrouselProps, 'slot_id'> {
 
 export declare const CarruselOpinion: FC<SectionCardCarouselProps>;
 
+/** Corre `resolveImageSizes` y reduce el resultado a pass/fail para CI. */
+export declare function checkImageSizes(input: ImageSizesContractInput | undefined): ImageSizesCheckReport;
+
 /**
  * Recorre recursivamente un schema (objeto o array) y elimina toda entry
  * que quede sin valor. Si una propiedad de un objeto queda sin valor, la
@@ -511,6 +522,11 @@ export declare class CommonServices {
     protected props?: ICommonServices | undefined;
     configVersion: string;
     exclude: string;
+    /**
+     * Contrato de tamaños resuelto UNA vez en el punto de entrada (§3). El resto
+     * de los métodos consume `this.contract.<slot>` — cero literales sueltos.
+     */
+    readonly contract: ImageSizesContract;
     constructor(props?: ICommonServices | undefined);
     generateTokenOffline: (browserId: string) => Promise<any>;
     getEntitySection: (params: Params) => Promise<AxiosResponse<{
@@ -808,6 +824,25 @@ declare interface CreateAssessmentParams {
     userIpAddress?: string;
 }
 
+/**
+ * Divide un fetch de lista en `batches` requests paralelos de `ceil(totalSize/
+ * batches)` ítems cada uno (páginas contiguas del upstream) y concatena los
+ * resultados en orden, devolviendo el MISMO envelope que un fetch único
+ * (`{ data: { data: [] } }`) para que caiga directo en un `PromiseArray` con
+ * `custom_extractData: getResponse`.
+ *
+ * Mapeo de páginas (batches=5, totalSize=45 → batchSize=9):
+ *   userPage=1 → API pages 1..5   (ítems 1–45)
+ *   userPage=2 → API pages 6..10  (ítems 46–90)
+ *
+ * `fetchFn` recibe `(size, page)` y devuelve la respuesta del CMS o `undefined`.
+ */
+export declare function createBatchedFetch(fetchFn: (size: number, page: number) => Promise<any> | undefined, totalSize: number, userPage: number, batches?: number): Promise<{
+    data: {
+        data: any[];
+    };
+}>;
+
 export declare const cutString: (text: string, length?: number) => string;
 
 export declare interface DataNews {
@@ -1056,6 +1091,18 @@ export declare type FetchConfig = {
     newsType: string;
 };
 
+/**
+ * Envuelve `fetchFn` con batch SI la ruta está activada en config; si no, hace
+ * el fetch único (comportamiento de master). Behavior-preserving cuando el batch
+ * está off, así que es seguro envolver todas las rutas de lista de una — solo
+ * las que estén en `CONFIG_batchedFetch.routes` cambian de comportamiento.
+ */
+export declare function fetchMaybeBatched(route: string, fetchFn: (size: number, page: number) => Promise<any> | undefined, totalSize: number, userPage: number): Promise<{
+    data: {
+        data: any[];
+    };
+}>;
+
 /**
  * Cache in-memory + deduplicación de requests en vuelo (misma clave → misma promesa).
  * TTL corto pensado para SSR: evita 4–5 GETs repetidos de menú/banners por instancia.
@@ -1431,10 +1478,24 @@ export declare const HeaderSectionComponent: FC<Props_12>;
 
 export declare function HomeCard(props: SectionCardProps_3): JSX.Element;
 
+/**
+ * Genera el string HTML de una HomeCard de tipo "imagen" sin pasar por React.
+ * Reemplaza a <HomeCard> para el tipo imagen en LandingTemplate.
+ *
+ * - `priorityHigh` (lo decide el caller) → fetchpriority="high" / loading="eager".
+ *   Por default false → low/lazy.
+ * - Sin espacio extra en la clase homeCardImage cuando no hay preRenderClass.
+ */
+export declare function homeCardImagenToHTMLString(item: NewListResponseData, index: number, paths: RoutePathConfig, share?: Omit<NoteShare, 'googleProfile'>, priorityHigh?: boolean): string;
+
 declare interface ICommonServices {
     config?: Config;
+    /** @deprecated Ya no se lee acá; los tamaños salen de `contract` (§3). Se acepta por retrocompat hasta Fase 3. */
     imgSizes?: any;
+    /** @deprecated No se lee en CommonServices; se acepta por retrocompat hasta Fase 3. */
     imgSizesVideo?: any;
+    /** Nuevo contrato de tamaños (REFACTOR_IMGSIZES_PLAN.md §3). Ausente → `resolveImageSizes` cae a los defaults congelados (§4) → output idéntico. */
+    imageSizes?: ImageSizesContractInput;
     axiosApi: AxiosInstance;
     exclude?: string;
 }
@@ -1519,6 +1580,60 @@ declare interface ImageProps_4 {
     figCaption?: string;
 }
 
+export declare interface ImageSizesCheckReport {
+    /** `true` si el contrato no necesitó ningún default congelado. */
+    ok: boolean;
+    legacyFieldsUsed: string[];
+}
+
+export declare interface ImageSizesContract {
+    note: {
+        detailMain: SizeString;
+        detailSecondary: SizeString;
+        itemsListPrimary: SizeString;
+        relatedPrimary: SizeString;
+        relatedThumb: SizeString;
+        listStandard: SizeString;
+        cardTall: SizeString;
+        square: SizeString;
+        gallery: SizeString;
+        featuredSuperSecondary: SizeString;
+        featuredVerticalPrimary: SizeString;
+        featuredVerticalSecondary: SizeString;
+        featuredHorizontalPrimary: SizeString;
+        featuredHorizontalSecondary: SizeString;
+        featuredDiarioImageThumb: SizeString;
+    };
+    author: {
+        avatar: SizeString;
+        multiCrop: SizeString;
+    };
+    video: {
+        xl: SizeString;
+        lg: SizeString;
+        md: SizeString;
+    };
+    og: {
+        social: SizeString;
+    };
+}
+
+/**
+ * Partial real (por slot, no solo por grupo): `Partial<ImageSizesContract>` es
+ * shallow y obligaría a mandar cada grupo completo o nada. Un app puede mandar
+ * solo algunos slots de `note` y dejar el resto en manos del default congelado.
+ */
+export declare type ImageSizesContractInput = {
+    [G in keyof ImageSizesContract]?: Partial<ImageSizesContract[G]>;
+};
+
+export declare interface ImageSizesResolution {
+    /** Siempre completo — nunca undefined para el resto del paquete. */
+    contract: ImageSizesContract;
+    /** Slots resueltos por el default congelado, no provistos por el app. */
+    legacyFieldsUsed: string[];
+}
+
 export declare interface Info {
     type?: string;
     section?: {
@@ -1559,6 +1674,14 @@ export declare const isHomePath: (pathname?: string) => boolean;
 
 export declare const isPhotoGallery: (news: NewListResponseData) => boolean | undefined;
 
+/**
+ * ¿La ruta tiene batch activo? Precedencia:
+ *  1. `CONFIG_batchedFetch.routes[route]` explícito (true/false) gana.
+ *  2. Retro-compat: el legacy `CONFIG_sectionBatchedFetch` solo cubría `seccion`.
+ *  3. Off por default.
+ */
+export declare function isRouteBatched(route: string): boolean;
+
 export declare class IssuuServices {
     private issuuApi;
     private api;
@@ -1666,12 +1789,45 @@ export declare type LibraryConfig = {
      */
     CONFIG_sectionMetaInfo?: boolean;
     /**
-     * [renderizado] Cuando es `true`, la lista de sección se obtiene con
-     * `batchedNewsFetch` (N fetches paralelos en lugar de uno). Hoy implementado
-     * en el sitio soyfutbol; se formaliza acá como opt-in. Default `false`
-     * → un único fetch (comportamiento de master).
+     * @deprecated Reemplazado por `CONFIG_batchedFetch.routes.seccion`. Se mantiene
+     * como shim de retro-compatibilidad: si `CONFIG_batchedFetch` no está seteado y
+     * este flag es `true`, el batch de sección (solo metadata next/prev) sigue
+     * funcionando con el conteo default. Cuando ambos están, `CONFIG_batchedFetch`
+     * gana. Remover cuando todos los sitios migren a `CONFIG_batchedFetch`.
      */
     CONFIG_sectionBatchedFetch?: boolean;
+    /**
+     * [renderizado] Formaliza el fetch de listas de noticias por batches: divide un
+     * único fetch de `config.newsListLimit` ítems en `batches` fetches paralelos
+     * (páginas contiguas del upstream) y los concatena, devolviendo el MISMO
+     * envelope que un fetch único. Es la versión canónica del sistema que vivía
+     * suelto en soyfutbol (`newsListBatches` + `batchFetchRoutes`).
+     *
+     * - `batches`: número de fetches paralelos por lista. Sin la key (o 1) → un
+     *   único fetch = comportamiento de master (aditivo, cero cambio por default).
+     * - `routes`: opt-in por ruta (`home`/`seccion`/`tema`/`ultimas-noticias`/
+     *   `autor`/...). Solo las rutas en `true` se batchean; el resto hace fetch único.
+     *
+     * Unifica render y metadata: cuando una ruta está activa acá, tanto la lista
+     * visible como la derivación next/prev usan el MISMO `batches`, evitando el
+     * desajuste "next dice que hay más pero la página muestra un solo fetch".
+     * Reemplaza al legacy `CONFIG_sectionBatchedFetch`.
+     */
+    CONFIG_batchedFetch?: {
+        /** N fetches paralelos por lista. Default efectivo 3 si algo lo activa sin fijarlo. */
+        batches?: number;
+        /** Opt-in por ruta. Claves = route keys de `MetadataDefaultsKeys`. */
+        routes?: Record<string, boolean>;
+    };
+    /**
+     * [render] Cuando es `true`, `LandingTemplate` renderiza las cards de tipo
+     * `imagen` con el fast-render HTML-string (`homeCardImagenToHTMLString`) en
+     * lugar del componente React `<HomeCard>`, ahorrando reconciliación/hidratación.
+     * El fast-render se saltea online cuando la URL de preview no es absoluta y
+     * SIEMPRE cae a `<HomeCard>` en offline (el path HTML-string no pasa por el
+     * hidratador de imágenes offline). Default `false` → usa `<HomeCard>` React.
+     */
+    CONFIG_landingFastRender?: boolean;
     CONFIG_deferBanners?: {
         common?: boolean;
         middle?: boolean;
@@ -1804,11 +1960,19 @@ export declare interface MainBlock1Props extends SectionCardProps, NewDescriptio
 export declare class MainComponentServices {
     exclude: string;
     config: any;
+    /**
+     * @deprecated Ya no se lee: los tamaños salen de `this.contract` (§3). Bigfish
+     * pasa `imgSizesVideo` acá (quirk documentado en el snapshot de Fase 0), por eso
+     * `this.imgSizes.lg` valía `video.lg`; ahora eso se expresa como `contract.video.lg`.
+     * Se mantiene el parámetro posicional por retrocompat hasta Fase 3.
+     */
     imgSizes: any;
     configVersion: string;
     axiosApi: AxiosInstance | undefined;
     customMainImagesSize: string | undefined;
-    constructor(config: Config, imgSizes: any, axiosApi: AxiosInstance, exclude?: string, customMainImagesSizes?: string);
+    /** Contrato de tamaños resuelto UNA vez (§3); el resto consume `this.contract.<slot>`. */
+    readonly contract: ImageSizesContract;
+    constructor(config: Config, imgSizes: any, axiosApi: AxiosInstance, exclude?: string, customMainImagesSizes?: string, imageSizes?: ImageSizesContractInput);
     getNewsListZone(params: Params): Promise<AxiosResponse<NewListResponse, any, {}> | undefined>;
     getOutstandingBlock(params: Params): Promise<AxiosResponse<    {
     data: Array<Outstanding>;
@@ -2492,7 +2656,10 @@ export declare interface Preview {
     photographer?: string | false;
 }
 
-export declare const processExtractedRelatedNews: (relatedNews: string[][], getNews: (params: any) => any) => Promise<any[]>;
+/** Única función que imprime: nada de `console.warn` en el runtime de la app (§3.1). */
+export declare function printImageSizesReport(report: ImageSizesCheckReport, label?: string): void;
+
+export declare const processExtractedRelatedNews: (relatedNews: string[][], getNews: (params: any) => any, imagesizes?: string) => Promise<any[]>;
 
 export declare type PromiseArray = {
     [key: string]: {
@@ -3113,10 +3280,29 @@ export declare interface ResilientFetchOptions {
     baseDelayMs?: number;
 }
 
+/**
+ * Conteo de batches efectivo leído de `getConfig().CONFIG_batchedFetch.batches`.
+ * Default `3` cuando algo activa el batch sin fijar el número (preserva el
+ * comportamiento histórico del path de metadata, cuyo default era 3).
+ */
+export declare function resolveBatchCount(): number;
+
 export declare function resolveBucketMenuSubtype(path?: string): string;
 
 export declare function resolveBucketOriginUrl(bucket: BucketOriginConfig, servicePrefix: string | undefined, type: 'menu' | 'banners', subtype: string): string;
 
+/**
+ * Recibe lo que el app mande hoy (contrato completo, parcial, o nada) y
+ * devuelve SIEMPRE un contrato completo. Los constructores públicos del
+ * paquete llaman esto una sola vez, en su punto de entrada, y de ahí en
+ * adelante consumen `contract.<slot>` sin condicionales ni valores propios.
+ *
+ * Puede tirar (vía `assertImageSizesContract`) si un slot provisto por el
+ * app no matchea el formato esperado — enforcement doble (§3): tipos en
+ * build, assert en runtime.
+ */
+export declare function resolveImageSizes(input: ImageSizesContractInput | undefined): ImageSizesResolution;
+
 export declare interface RoutePathConfig {
     autor: string | 'autor';
     tema: string | 'tema';
@@ -3296,6 +3482,9 @@ export declare interface SizeImage {
     scale?: string;
 }
 
+/** Formato: `"w:{n},h:{n},t:{n}[,c:{hex}];"` (uno o más, cada uno separado y terminado en `;`). */
+export declare type SizeString = string;
+
 declare interface Social {
     title: boolean;
     description: boolean;