@sarimarcus/content-sites-core 0.27.0 → 0.28.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.28.1 (2026-10-06)
+
+- `./schema` structured data no longer publishes false facts (SLA-2983):
+  - `isFreeEntry` / `parsePriceFromString`: price or fee text is free only when it leads with "free" and names no amount and no condition. Paid text with a free concession ("€15 general … free under 10") gives `isAccessibleForFree: false` and its first price; a conditional leading "free" ("Free for EU citizens; €4.50 for others") omits `isAccessibleForFree` and gives no price, so an event emits no Offer priced at a side cost. A `free` tag still wins.
+  - `aggregateRating` returns nothing without a real `ratingCount`, instead of inventing `reviewCount: 1`.
+  - `itemListBuilder` and touristTrip stop URLs resolve through the RouteMap (`ctx.route`), so Dark Skies lists link `/lodges/` and `/events/` instead of the redirecting `/hotel/` and `/event/`.
+  Output changes on the affected pages only; no API change, no migration.
+
+## 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).

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/dist/schema/pages.d.ts

@@ -28,7 +28,7 @@ export interface ItemListOptions {
     /** `data.itemType` → schema type. Given: each item is a typed nested entity; absent: name/url on the ListItem. */
     itemTypes?: Record<string, string>;
 }
-/** ItemList of `data.items` linked at `/${data.itemType}/${slug}`. */
+/** ItemList of `data.items` linked at the `data.itemType` route. */
 export declare function itemListBuilder(options?: ItemListOptions): SchemaBuilder;
 export declare function howToBuilder(): SchemaBuilder;
 export interface AboutPageOptions {

package/dist/schema/pages.js

@@ -108,7 +108,7 @@ export function collectionPageBuilder(options = {}) {
         };
     };
 }
-/** ItemList of `data.items` linked at `/${data.itemType}/${slug}`. */
+/** ItemList of `data.items` linked at the `data.itemType` route. */
 export function itemListBuilder(options = {}) {
     const { itemTypes } = options;
     return (data, ctx) => ({
@@ -117,7 +117,7 @@ export function itemListBuilder(options = {}) {
         description: data.description,
         numberOfItems: data.items?.length || 0,
         itemListElement: data.items?.map((item, index) => {
-            const url = ctx.abs(`/${data.itemType}/${item.slug}`);
+            const url = ctx.route(data.itemType, item.slug);
             return itemTypes
                 ? { '@type': 'ListItem', position: index + 1, item: { '@type': itemTypes[data.itemType] ?? 'WebPage', name: item.name, url } }
                 : { '@type': 'ListItem', position: index + 1, name: item.name, url };

package/dist/schema/places.js

@@ -61,7 +61,7 @@ export function touristTripBuilder(options = {}) {
                     name: stop.name,
                     description: stop.description,
                     geo: geoCoordinates(stop.coordinates),
-                    ...(stop.slug && stop.type !== 'landmark' ? { url: ctx.abs(`/${stop.type}/${stop.slug}`) } : {}),
+                    ...(stop.slug && stop.type !== 'landmark' ? { url: ctx.route(stop.type, stop.slug) } : {}),
                 },
             })),
         },

package/dist/schema/values.d.ts

@@ -1,9 +1,13 @@
 import type { JsonLdNode } from './types.ts';
-/** First integer in a price string; any "free" reads as 0; null when there is no number. */
+/**
+ * First integer in a price string; 0 when `isFreeText`; null when there is no number, or when the text leads with a
+ * conditional "free", whose first number is a side cost ("Free (…). Shuttle: €2"), not the price.
+ */
 export declare function parsePriceFromString(priceStr: string | undefined): number | null;
 /**
- * Free entry: a `free` tag, or "free" in the price text (`price` for events, `fees` for places). `undefined` when
- * neither is present, so the key drops out of the JSON-LD.
+ * Free entry: a `free` tag, or price text that `isFreeText` accepts (`price` for events, `fees` for places).
+ * `undefined`, so the key drops out of the JSON-LD, when neither is present or the text leads with a conditional
+ * "free" ("Free for EU citizens; …"), which proves neither.
  */
 export declare function isFreeEntry(data: Record<string, any>, field?: 'price' | 'fees'): boolean | undefined;
 /** Street and number only: drops postal code, city and country, and a second part that is a district or postcode. */
@@ -41,6 +45,7 @@ export declare function geoCoordinates(coordinates: {
     lat: number;
     lng: number;
 } | undefined): JsonLdNode | undefined;
+/** Only with a real `ratingCount`: a rating without a count is an invalid AggregateRating, and inventing one is false. */
 export declare function aggregateRating(data: {
     rating?: number;
     ratingCount?: number;

package/dist/schema/values.js

@@ -1,18 +1,42 @@
-/** First integer in a price string; any "free" reads as 0; null when there is no number. */
+const LEADING_FREE = /^\s*free\b/i;
+const FREE_QUALIFIER = /\b(or|for|with|at|except|paid|fees?|charges?|priced|included|rates?|applies|apply)\b/i;
+/**
+ * Price text that says the whole thing is free: it starts with "free" and names no amount and no condition.
+ * "€15 … free under 10" and "Free for EU citizens; €4.50 for others" are not free.
+ */
+function isFreeText(priceStr) {
+    if (!priceStr || !LEADING_FREE.test(priceStr))
+        return false;
+    return !/\d/.test(priceStr) && !FREE_QUALIFIER.test(priceStr);
+}
+/**
+ * First integer in a price string; 0 when `isFreeText`; null when there is no number, or when the text leads with a
+ * conditional "free", whose first number is a side cost ("Free (…). Shuttle: €2"), not the price.
+ */
 export function parsePriceFromString(priceStr) {
     if (!priceStr)
         return null;
-    if (priceStr.toLowerCase().includes('free'))
+    if (isFreeText(priceStr))
         return 0;
+    if (LEADING_FREE.test(priceStr))
+        return null;
     const match = priceStr.match(/(\d+)/);
     return match ? parseFloat(match[1]) : null;
 }
 /**
- * Free entry: a `free` tag, or "free" in the price text (`price` for events, `fees` for places). `undefined` when
- * neither is present, so the key drops out of the JSON-LD.
+ * Free entry: a `free` tag, or price text that `isFreeText` accepts (`price` for events, `fees` for places).
+ * `undefined`, so the key drops out of the JSON-LD, when neither is present or the text leads with a conditional
+ * "free" ("Free for EU citizens; …"), which proves neither.
  */
 export function isFreeEntry(data, field = 'price') {
-    return data.tags?.includes('free') || data[field]?.toLowerCase().includes('free');
+    if (data.tags?.includes('free'))
+        return true;
+    const text = data[field];
+    if (!text)
+        return undefined;
+    if (isFreeText(text))
+        return true;
+    return LEADING_FREE.test(text) ? undefined : false;
 }
 /** Street and number only: drops postal code, city and country, and a second part that is a district or postcode. */
 export function cleanStreetAddress(fullAddress) {
@@ -82,12 +106,13 @@ export function postalAddress(policy, data, parts = {}) {
 export function geoCoordinates(coordinates) {
     return coordinates ? { '@type': 'GeoCoordinates', latitude: coordinates.lat, longitude: coordinates.lng } : undefined;
 }
+/** Only with a real `ratingCount`: a rating without a count is an invalid AggregateRating, and inventing one is false. */
 export function aggregateRating(data) {
-    return data.rating ? {
+    return data.rating && data.ratingCount ? {
         '@type': 'AggregateRating',
         ratingValue: data.rating,
         bestRating: 5,
         worstRating: 1,
-        reviewCount: data.ratingCount ?? 1,
+        reviewCount: data.ratingCount,
     } : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-core",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "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';

package/src/schema/pages.ts

@@ -143,7 +143,7 @@ export interface ItemListOptions {
   itemTypes?: Record<string, string>;
 }
 
-/** ItemList of `data.items` linked at `/${data.itemType}/${slug}`. */
+/** ItemList of `data.items` linked at the `data.itemType` route. */
 export function itemListBuilder(options: ItemListOptions = {}): SchemaBuilder {
   const { itemTypes } = options;
   return (data, ctx) => ({
@@ -152,7 +152,7 @@ export function itemListBuilder(options: ItemListOptions = {}): SchemaBuilder {
     description: data.description,
     numberOfItems: data.items?.length || 0,
     itemListElement: data.items?.map((item: any, index: number) => {
-      const url = ctx.abs(`/${data.itemType}/${item.slug}`);
+      const url = ctx.route(data.itemType, item.slug);
       return itemTypes
         ? { '@type': 'ListItem', position: index + 1, item: { '@type': itemTypes[data.itemType] ?? 'WebPage', name: item.name, url } }
         : { '@type': 'ListItem', position: index + 1, name: item.name, url };

package/src/schema/places.ts

@@ -90,7 +90,7 @@ export function touristTripBuilder(options: TouristTripOptions = {}): SchemaBuil
           name: stop.name,
           description: stop.description,
           geo: geoCoordinates(stop.coordinates),
-          ...(stop.slug && stop.type !== 'landmark' ? { url: ctx.abs(`/${stop.type}/${stop.slug}`) } : {}),
+          ...(stop.slug && stop.type !== 'landmark' ? { url: ctx.route(stop.type, stop.slug) } : {}),
         },
       })),
     },

package/src/schema/values.ts

@@ -1,19 +1,40 @@
 import type { JsonLdNode } from './types.ts';
 
-/** First integer in a price string; any "free" reads as 0; null when there is no number. */
+const LEADING_FREE = /^\s*free\b/i;
+const FREE_QUALIFIER = /\b(or|for|with|at|except|paid|fees?|charges?|priced|included|rates?|applies|apply)\b/i;
+
+/**
+ * Price text that says the whole thing is free: it starts with "free" and names no amount and no condition.
+ * "€15 … free under 10" and "Free for EU citizens; €4.50 for others" are not free.
+ */
+function isFreeText(priceStr: string | undefined): boolean {
+  if (!priceStr || !LEADING_FREE.test(priceStr)) return false;
+  return !/\d/.test(priceStr) && !FREE_QUALIFIER.test(priceStr);
+}
+
+/**
+ * First integer in a price string; 0 when `isFreeText`; null when there is no number, or when the text leads with a
+ * conditional "free", whose first number is a side cost ("Free (…). Shuttle: €2"), not the price.
+ */
 export function parsePriceFromString(priceStr: string | undefined): number | null {
   if (!priceStr) return null;
-  if (priceStr.toLowerCase().includes('free')) return 0;
+  if (isFreeText(priceStr)) return 0;
+  if (LEADING_FREE.test(priceStr)) return null;
   const match = priceStr.match(/(\d+)/);
   return match ? parseFloat(match[1]) : null;
 }
 
 /**
- * Free entry: a `free` tag, or "free" in the price text (`price` for events, `fees` for places). `undefined` when
- * neither is present, so the key drops out of the JSON-LD.
+ * Free entry: a `free` tag, or price text that `isFreeText` accepts (`price` for events, `fees` for places).
+ * `undefined`, so the key drops out of the JSON-LD, when neither is present or the text leads with a conditional
+ * "free" ("Free for EU citizens; …"), which proves neither.
  */
 export function isFreeEntry(data: Record<string, any>, field: 'price' | 'fees' = 'price'): boolean | undefined {
-  return data.tags?.includes('free') || data[field]?.toLowerCase().includes('free');
+  if (data.tags?.includes('free')) return true;
+  const text = data[field];
+  if (!text) return undefined;
+  if (isFreeText(text)) return true;
+  return LEADING_FREE.test(text) ? undefined : false;
 }
 
 /** Street and number only: drops postal code, city and country, and a second part that is a district or postcode. */
@@ -99,12 +120,13 @@ export function geoCoordinates(coordinates: { lat: number; lng: number } | undef
   return coordinates ? { '@type': 'GeoCoordinates', latitude: coordinates.lat, longitude: coordinates.lng } : undefined;
 }
 
+/** Only with a real `ratingCount`: a rating without a count is an invalid AggregateRating, and inventing one is false. */
 export function aggregateRating(data: { rating?: number; ratingCount?: number }): JsonLdNode | undefined {
-  return data.rating ? {
+  return data.rating && data.ratingCount ? {
     '@type': 'AggregateRating',
     ratingValue: data.rating,
     bestRating: 5,
     worstRating: 1,
-    reviewCount: data.ratingCount ?? 1,
+    reviewCount: data.ratingCount,
   } : undefined;
 }