sass-template-common 0.11.21 → 0.11.23-beta.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

@@ -51,6 +51,16 @@ export declare type Analytics = {
     comscore: string | undefined;
 };
 
+/**
+ * Una pasada sobre el DOM. Exportada aparte de `initRelativeTime` para poder
+ * re-correrla a mano después de inyectar HTML (paginados, "más noticias") —
+ * pasándole las MISMAS `opts` que se le pasaron a `initRelativeTime`.
+ *
+ * Tambien gateada por el flag: sin `enabled` no escribe nada. Es la condición
+ * de que el HTML de un sitio que no opto in sea el de siempre.
+ */
+export declare const applyRelativeTime: (opts?: RelativeTimeOptions) => void;
+
 /**
  * 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
@@ -1248,6 +1258,21 @@ export declare const formatNewsMeta: (meta: any, news: NewListResponseData | und
     };
 };
 
+/**
+ * Relativo ("hace 3 horas") si la nota es más nueva que `maxAgeHours`;
+ * si no, cae a `formatDate` (absoluto).
+ *
+ * `now` entra POR PARÁMETRO, no se lee adentro: así la función es determinista
+ * dado `(date, now)` y el SSR nunca la llama con `Date.now()` por accidente
+ * (un relativo renderizado en servidor queda congelado en el cache del CDN y
+ * a los 40 minutos sigue diciendo "hace 5 minutos" — información incorrecta,
+ * no desactualizada).
+ */
+export declare const formatRelativeDate: (date: number, now: number, maxAgeHours?: number, DATE_CONFIG?: {
+    PUBLIC_LNG: string;
+    DATE_TIMEZONE: string;
+}) => string;
+
 export declare const FormatScripts: (props: ScriptProps) => JSX.Element | null;
 
 export declare const formatVideoData: (meta: any, news: VideoResponseData, config: Config) => {
@@ -1736,6 +1761,19 @@ export declare interface Info {
 
 export declare function initLibrary(userConfig?: LibraryConfig): void;
 
+/**
+ * Reescribe a "hace 3 horas" el texto de todo `[data-rel-ts]` cuya fecha caiga
+ * dentro de `maxAgeHours`, y lo refresca mientras la pestaña esté visible.
+ *
+ * Sin React a propósito: hidratar un nodo de texto con React cuesta más que el
+ * dato. Sin JS —o sin llamar a esta función— queda el absoluto que emitió el
+ * SSR, que es correcto, cacheable y el que lee el crawler.
+ *
+ * Idempotente: una segunda llamada reemplaza los listeners de la anterior.
+ * Devuelve el disposer.
+ */
+export declare const initRelativeTime: (opts?: RelativeTimeOptions) => () => void;
+
 export declare function isConfigOriginAuditEnabled(): boolean;
 
 export declare interface ISection {
@@ -1781,6 +1819,18 @@ export declare class IssuuServices {
 /** True para videos (flash, youtube y embedded) en cualquiera de sus formas. */
 export declare const isVideoContentItem: (item: any) => boolean;
 
+/**
+ * ¿La fecha cae dentro de la ventana en la que corresponde texto relativo?
+ *
+ * Fuente ÚNICA de la decisión relativo-vs-absoluto: la consumen
+ * `formatRelativeDate` (SSR/render) y el hidratador `initRelativeTime`
+ * (cliente), para que nunca puedan discrepar.
+ *
+ * Las fechas futuras (`date > now`) quedan FUERA de la ventana a propósito:
+ * un reloj de cliente atrasado no debe producir "en 3 horas".
+ */
+export declare const isWithinRelativeWindow: (date: number, now: number, maxAgeHours?: number) => boolean;
+
 export declare interface ItemFormatedType extends NewListResponseData {
     gallery?: Array<Preview>;
     videos?: Array<VideoItem>;
@@ -1877,6 +1927,19 @@ export declare type LibraryConfig = {
      * hidratador de imágenes offline). Default `false` → usa `<HomeCard>` React.
      */
     CONFIG_landingFastRender?: boolean;
+    /**
+     * [render] Fecha relativa ("hace 3 horas") en las superficies que emiten
+     * `data-rel-ts`. Solo lo lee el hidratador `initRelativeTime` en el cliente:
+     * el SSR SIEMPRE emite la fecha absoluta, porque el HTML se sirve cacheado y
+     * un relativo renderizado en servidor queda congelado en el CDN.
+     *
+     * Default `undefined` -> comportamiento actual (absoluto, sin hidratador).
+     * `maxAgeHours` default 24: pasada esa antiguedad se muestra el absoluto.
+     */
+    CONFIG_relativeTime?: {
+        enabled: boolean;
+        maxAgeHours?: number;
+    };
     CONFIG_deferBanners?: {
         common?: boolean;
         middle?: boolean;
@@ -3382,6 +3445,49 @@ declare interface Relatedexternal {
     news: boolean;
 }
 
+/**
+ * Marca un elemento como hidratable a fecha relativa. El valor es el timestamp
+ * en milisegundos (el mismo número que consume `formatDate`).
+ */
+export declare const RELATIVE_TIME_ATTR = "data-rel-ts";
+
+/**
+ * Texto literal a preservar ANTES del relativo, para las superficies donde el
+ * elemento contiene `"Autor - fecha"` en un ÚNICO nodo de texto (super,
+ * block-video-2/3, fast-render de la home). Existe para no partir ese texto en
+ * nodos nuevos: el hidratador reescribe el `textContent` como `prefix + relativo`.
+ *
+ * Duplica el nombre del autor en el HTML; al ser una repetición literal dentro
+ * del mismo documento, gzip/brotli la resuelven como back-reference.
+ */
+export declare const RELATIVE_TIME_PREFIX_ATTR = "data-rel-prefix";
+
+/**
+ * Props JSX del contrato. Devuelve `{}` (spread vacío, cero atributos en el
+ * HTML) si el timestamp no sirve: la superficie queda exactamente como hoy.
+ */
+export declare const relativeTimeAttrs: (ts: number | undefined, prefix?: string) => Record<string, string | number>;
+
+/**
+ * La misma info que `relativeTimeAttrs`, para los emisores de HTML-string
+ * (`homeCardFastRender`). Devuelve `''` o un fragmento que ARRANCA con espacio,
+ * listo para concatenar dentro del tag.
+ */
+export declare const relativeTimeAttrsHTML: (ts: number | undefined, prefix?: string) => string;
+
+declare type RelativeTimeOptions = {
+    /**
+     * Gana sobre `CONFIG_relativeTime.enabled`. Sin ninguno de los dos en `true`
+     * el hidratador es un no-op: no observa, no agenda y no toca el DOM.
+     */
+    enabled?: boolean;
+    maxAgeHours?: number;
+    /** Cada cuánto refresca el texto. Default 60_000. `0` desactiva el refresco. */
+    refreshMs?: number;
+    /** Raíz del query. Default `document`. */
+    root?: ParentNode;
+};
+
 export declare const removePages: (pathname: string) => string;
 
 declare type ReplaceProps = {