@sarimarcus/content-sites-core 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.28.0 (2026-10-05)
+
+- `./articles`: `selectFeaturedArticles(sorted, snapshot, { slugOf, now, shelfSize = 3, maxAgeDays = 21 })` splits a newest-first article list into a hero, a trending shelf and the rest, from the committed `src/data/featured-articles.json` snapshot the factory writes from GSC data. A snapshot older than `maxAgeDays`, or naming no current article, falls back to the newest article as hero with no shelf. It replaces the sites' `getFeaturedAndRest` copies (SLA-2972).
+
+## 0.27.0 (2026-10-05)
+
+- No changes; lockstep release with ui (SLA-2975).
+
 ## 0.26.0 (2026-10-05)
 
 - `./url`: `publicImageUrl(image, basePath = '/')` — a `public/` asset path under the base path; absolute, protocol-relative and relative values pass through, no image stays undefined. It replaces the copies in the sites' affiliate utils (SLA-2921).

package/README.md

@@ -4,7 +4,7 @@ Non-visual code shared by the content sites: generic utilities, Astro config bui
 and the type contracts `ui` and `tourism` build on (for example the card item and tag-link shapes that
 today's ui components import from tourism code).
 
-Named entry points: `url`, `affiliate`, `dates`, `geo`, `dom`, `text`, `config`, `types`, `schema`, `interludes` and `images` (`src/internal` is never exported). No `.astro`
+Named entry points: `url`, `affiliate`, `dates`, `geo`, `dom`, `text`, `config`, `types`, `schema`, `interludes`, `images` and `articles` (`src/internal` is never exported). No `.astro`
 files. Lowest layer: imports nothing from the other packages; its one runtime dependency is `marked` (`readingTime`). Ownership per path is in
 `.planning/platform/catalogue.json` (owner `core`).
 

package/dist/articles/featured.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Articles-hub selection from a committed trending snapshot (SLA-2972).
+ *
+ * The factory writes `src/data/featured-articles.json` from GSC data; the hub never reads GSC.
+ * A snapshot older than `maxAgeDays`, or one naming no current article, falls back to the
+ * newest article, so the hero cannot freeze when nobody refreshes it.
+ */
+export interface FeaturedSnapshot {
+    generatedAt: string;
+    featured: {
+        slug: string;
+    }[];
+}
+export interface FeaturedSelection<T> {
+    hero: T | null;
+    shelf: T[];
+    /** Every other article, in the order given: the paginated "Latest" grid. */
+    rest: T[];
+    source: 'trending' | 'latest';
+}
+export declare const FEATURED_SHELF_SIZE = 3;
+export declare const FEATURED_MAX_AGE_DAYS = 21;
+/**
+ * Split newest-first articles into the hero, the trending shelf and the rest.
+ * Pass `buildNow()` as `now` so two pages of one build agree.
+ */
+export declare function selectFeaturedArticles<T>(sorted: T[], snapshot: FeaturedSnapshot | null | undefined, options: {
+    slugOf: (article: T) => string;
+    now: Date;
+    shelfSize?: number;
+    maxAgeDays?: number;
+}): FeaturedSelection<T>;

package/dist/articles/featured.js

@@ -0,0 +1,35 @@
+/**
+ * Articles-hub selection from a committed trending snapshot (SLA-2972).
+ *
+ * The factory writes `src/data/featured-articles.json` from GSC data; the hub never reads GSC.
+ * A snapshot older than `maxAgeDays`, or one naming no current article, falls back to the
+ * newest article, so the hero cannot freeze when nobody refreshes it.
+ */
+export const FEATURED_SHELF_SIZE = 3;
+export const FEATURED_MAX_AGE_DAYS = 21;
+const DAY_MS = 86_400_000;
+function snapshotAgeDays(snapshot, now) {
+    const generated = Date.parse(`${snapshot.generatedAt}T00:00:00Z`);
+    return Number.isNaN(generated) ? Infinity : Math.floor((now.getTime() - generated) / DAY_MS);
+}
+/**
+ * Split newest-first articles into the hero, the trending shelf and the rest.
+ * Pass `buildNow()` as `now` so two pages of one build agree.
+ */
+export function selectFeaturedArticles(sorted, snapshot, options) {
+    const { slugOf, now, shelfSize = FEATURED_SHELF_SIZE, maxAgeDays = FEATURED_MAX_AGE_DAYS } = options;
+    const bySlug = new Map(sorted.map((a) => [slugOf(a), a]));
+    const fresh = snapshot && Array.isArray(snapshot.featured) && snapshotAgeDays(snapshot, now) <= maxAgeDays;
+    const picked = fresh
+        ? [...new Set(snapshot.featured.map((f) => f?.slug))].flatMap((slug) => {
+            const article = typeof slug === 'string' ? bySlug.get(slug) : undefined;
+            return article ? [article] : [];
+        }).slice(0, 1 + shelfSize)
+        : [];
+    if (picked.length === 0) {
+        const [hero = null, ...rest] = sorted;
+        return { hero, shelf: [], rest, source: 'latest' };
+    }
+    const taken = new Set(picked);
+    return { hero: picked[0], shelf: picked.slice(1), rest: sorted.filter((a) => !taken.has(a)), source: 'trending' };
+}

package/dist/articles/index.d.ts

@@ -0,0 +1,2 @@
+export { selectFeaturedArticles, FEATURED_SHELF_SIZE, FEATURED_MAX_AGE_DAYS } from './featured.ts';
+export type { FeaturedSnapshot, FeaturedSelection } from './featured.ts';

package/dist/articles/index.js

@@ -0,0 +1,2 @@
+// Public surface of @sarimarcus/content-sites-core/articles.
+export { selectFeaturedArticles, FEATURED_SHELF_SIZE, FEATURED_MAX_AGE_DAYS } from "./featured.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-core",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,10 @@
       "types": "./dist/dom/index.d.ts",
       "default": "./dist/dom/index.js"
     },
+    "./articles": {
+      "types": "./dist/articles/index.d.ts",
+      "default": "./dist/articles/index.js"
+    },
     "./text": {
       "types": "./dist/text/index.d.ts",
       "default": "./dist/text/index.js"

package/src/articles/featured.ts

@@ -0,0 +1,57 @@
+/**
+ * Articles-hub selection from a committed trending snapshot (SLA-2972).
+ *
+ * The factory writes `src/data/featured-articles.json` from GSC data; the hub never reads GSC.
+ * A snapshot older than `maxAgeDays`, or one naming no current article, falls back to the
+ * newest article, so the hero cannot freeze when nobody refreshes it.
+ */
+
+export interface FeaturedSnapshot {
+  generatedAt: string;
+  featured: { slug: string }[];
+}
+
+export interface FeaturedSelection<T> {
+  hero: T | null;
+  shelf: T[];
+  /** Every other article, in the order given: the paginated "Latest" grid. */
+  rest: T[];
+  source: 'trending' | 'latest';
+}
+
+export const FEATURED_SHELF_SIZE = 3;
+export const FEATURED_MAX_AGE_DAYS = 21;
+
+const DAY_MS = 86_400_000;
+
+function snapshotAgeDays(snapshot: FeaturedSnapshot, now: Date): number {
+  const generated = Date.parse(`${snapshot.generatedAt}T00:00:00Z`);
+  return Number.isNaN(generated) ? Infinity : Math.floor((now.getTime() - generated) / DAY_MS);
+}
+
+/**
+ * Split newest-first articles into the hero, the trending shelf and the rest.
+ * Pass `buildNow()` as `now` so two pages of one build agree.
+ */
+export function selectFeaturedArticles<T>(
+  sorted: T[],
+  snapshot: FeaturedSnapshot | null | undefined,
+  options: { slugOf: (article: T) => string; now: Date; shelfSize?: number; maxAgeDays?: number },
+): FeaturedSelection<T> {
+  const { slugOf, now, shelfSize = FEATURED_SHELF_SIZE, maxAgeDays = FEATURED_MAX_AGE_DAYS } = options;
+  const bySlug = new Map(sorted.map((a) => [slugOf(a), a]));
+  const fresh = snapshot && Array.isArray(snapshot.featured) && snapshotAgeDays(snapshot, now) <= maxAgeDays;
+  const picked = fresh
+    ? [...new Set(snapshot.featured.map((f) => f?.slug))].flatMap((slug) => {
+        const article = typeof slug === 'string' ? bySlug.get(slug) : undefined;
+        return article ? [article] : [];
+      }).slice(0, 1 + shelfSize)
+    : [];
+
+  if (picked.length === 0) {
+    const [hero = null, ...rest] = sorted;
+    return { hero, shelf: [], rest, source: 'latest' };
+  }
+  const taken = new Set<T>(picked);
+  return { hero: picked[0], shelf: picked.slice(1), rest: sorted.filter((a) => !taken.has(a)), source: 'trending' };
+}

package/src/articles/index.ts

@@ -0,0 +1,3 @@
+// Public surface of @sarimarcus/content-sites-core/articles.
+export { selectFeaturedArticles, FEATURED_SHELF_SIZE, FEATURED_MAX_AGE_DAYS } from './featured.ts';
+export type { FeaturedSnapshot, FeaturedSelection } from './featured.ts';