@sarimarcus/content-sites-core 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.14.0 (2026-10-01)
+
+- New `./schema` (compiled): JSON-LD types, URL/date/price/address normalisers, opening-hours parsing and specs, graph assembly and generic builders (article, FAQ, collection, item lists, event, how-to, website/organization, about/contact, person, offers, hotel, activity, tourist trip) driven by site policy; the opening-hours validator imports it (SLA-2737).
+
+## 0.13.0 (2026-10-01)
+
+- No changes; lockstep release with ui (SLA-2819).
+
 ## 0.12.1 (2026-10-01)
 
 - No changes; lockstep release with tourism (SLA-2739).

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`, `dates`, `geo`, `dom`, `text`, `config` and `types` (`src/internal` is never exported). No `.astro`
+Named entry points: `url`, `dates`, `geo`, `dom`, `text`, `config`, `types` and `schema` (`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`).
 
@@ -15,3 +15,11 @@ missing or stale `dist/`.
 
 Core code never imports `astro:content`, never reads `import.meta.env` or `import.meta.glob` (values and glob
 results come in as parameters), and never names a site or vertical. `validate-packages.mjs` enforces all three.
+
+`schema` assembles a page's JSON-LD graph: `createSchemaContext` (site URL, base path, page path, and the site's
+author lookup, public-file check, markdown stripper, publisher policy and route map), `assembleGraph` (base nodes,
+breadcrumb, then each entry's builder in call order, with hooks before and after the entries) and `finalizeGraph`.
+Builders are factories whose options carry each site's differences, so a site reproduces its current output byte
+for byte, key order included. It also holds the opening-hours model (`generateOpeningHours`, `parseHoursString`,
+`assertedOpenDays`, `hoursStringOpenDays`) that `scripts/validate-opening-hours.mjs` imports. The factory scripts
+load `dist/`; `scripts/lib/core-dist.mjs` rebuilds it when it is missing or older than `src/`.

package/dist/schema/context.d.ts

@@ -0,0 +1,11 @@
+import type { JsonLdNode, ResolvedAuthor, SchemaContext, SchemaContextInput } from './types.ts';
+/** The site root with a trailing slash (either form) collapses to the bare base URL. */
+export declare function normalizeHomepageUrl(url: string, siteUrl: string, siteBaseUrl: string): string;
+/** Every string in a JSON-LD value through `normalizeSiteUrl` + `normalizeHomepageUrl`, keys in their order. */
+export declare function normalizeStructuredDataUrls<T>(value: T, siteUrl: string, basePath: string): T;
+/** ISO 8601, never in the future: a date-only value becomes UTC midnight, a future one is clamped to `now`. */
+export declare function formatSchemaDate(dateStr: string | undefined, defaultToNow?: boolean, now?: () => Date): string | undefined;
+export declare function createPersonSchema(author: ResolvedAuthor): JsonLdNode;
+/** The node, preceded by its author's Person node when the author resolves. */
+export declare function withAuthorPersonSchema(ctx: SchemaContext, node: JsonLdNode, authorName: string | undefined): JsonLdNode | JsonLdNode[];
+export declare function createSchemaContext(input: SchemaContextInput): SchemaContext;

package/dist/schema/context.js

@@ -0,0 +1,95 @@
+import { normalizeSiteUrl, toAbsoluteSiteUrl } from "../url/index.js";
+import { slugify } from "../text/index.js";
+/** The site root with a trailing slash (either form) collapses to the bare base URL. */
+export function normalizeHomepageUrl(url, siteUrl, siteBaseUrl) {
+    return (url === `${siteUrl}/` || url === `${siteBaseUrl}/`) ? siteBaseUrl : url;
+}
+/** Every string in a JSON-LD value through `normalizeSiteUrl` + `normalizeHomepageUrl`, keys in their order. */
+export function normalizeStructuredDataUrls(value, siteUrl, basePath) {
+    const siteBaseUrl = `${siteUrl}${basePath || ''}`;
+    const walk = (v) => {
+        if (Array.isArray(v))
+            return v.map(walk);
+        if (v && typeof v === 'object') {
+            return Object.fromEntries(Object.entries(v).map(([key, entryValue]) => [key, walk(entryValue)]));
+        }
+        if (typeof v === 'string')
+            return normalizeHomepageUrl(normalizeSiteUrl(v, siteUrl, basePath), siteUrl, siteBaseUrl);
+        return v;
+    };
+    return walk(value);
+}
+/** ISO 8601, never in the future: a date-only value becomes UTC midnight, a future one is clamped to `now`. */
+export function formatSchemaDate(dateStr, defaultToNow = false, now = () => new Date()) {
+    if (!dateStr)
+        return defaultToNow ? now().toISOString() : undefined;
+    const isoDate = dateStr.includes('T') ? dateStr : `${dateStr}T00:00:00Z`;
+    const current = now();
+    if (new Date(isoDate) > current)
+        return current.toISOString();
+    return isoDate;
+}
+export function createPersonSchema(author) {
+    return {
+        '@type': 'Person',
+        '@id': author.id,
+        name: author.name,
+        url: author.url,
+        image: author.image,
+        sameAs: author.sameAs,
+    };
+}
+/** The node, preceded by its author's Person node when the author resolves. */
+export function withAuthorPersonSchema(ctx, node, authorName) {
+    const author = ctx.resolveAuthor(authorName);
+    return author ? [createPersonSchema(author), node] : node;
+}
+export function createSchemaContext(input) {
+    const siteUrl = input.siteUrl.replace(/\/$/, '');
+    const basePath = input.basePath;
+    const siteBaseUrl = `${siteUrl}${basePath || ''}`;
+    const fileExists = input.fileExists ?? (() => false);
+    const marker = input.ogImageMarker ?? '/og/';
+    const routes = input.routes ?? {};
+    const now = input.now ?? (() => new Date());
+    const ctx = {
+        siteUrl,
+        basePath,
+        siteBaseUrl,
+        pageUrl: toAbsoluteSiteUrl(input.pagePath, siteUrl, basePath),
+        orgId: `${siteBaseUrl}#organization`,
+        websiteId: `${siteBaseUrl}#website`,
+        abs: (path) => `${siteUrl}${basePath}${path}`,
+        absOrHttp: (path) => (path.startsWith('http') ? path : `${siteUrl}${basePath}${path}`),
+        route: (kind, slug) => `${siteUrl}${basePath}/${routes[kind] ?? kind}/${slug}`,
+        fileExists,
+        // /images/{type}/{name}.webp → /images/og/{type}/{name}.jpg, falling back to the slug's jpg (SLA-2817);
+        // omitted rather than pointing at a file that is not there.
+        resolveImageUrl(imagePath, slug) {
+            if (!imagePath)
+                return undefined;
+            if (imagePath.startsWith('http'))
+                return imagePath;
+            const ogPath = imagePath.includes(marker)
+                ? imagePath
+                : imagePath.replace(/^\/images\//, '/images/og/').replace(/\.(webp|png|jpeg)$/, '.jpg');
+            const slugOgPath = slug ? ogPath.replace(/[^/]+$/, `${slug}.jpg`) : undefined;
+            const resolved = [ogPath, slugOgPath].find((p) => p && fileExists(p));
+            return resolved ? `${siteUrl}${basePath}${resolved}` : undefined;
+        },
+        resolveAuthor(authorName) {
+            if (!authorName)
+                return null;
+            const profile = input.findAuthor?.(authorName);
+            const url = `${siteUrl}${basePath}/author/${profile?.slug || slugify(authorName)}`;
+            const image = profile?.photo
+                ? (profile.photo.startsWith('http') ? profile.photo : `${siteUrl}${basePath}${profile.photo}`)
+                : undefined;
+            return { id: `${url}#person`, name: authorName, url, image, sameAs: profile?.socialLinks };
+        },
+        formatDate: (dateStr, defaultToNow = false) => formatSchemaDate(dateStr, defaultToNow, now),
+        plainText: input.plainText ?? ((markdown) => markdown),
+        publisherFor: (authorName) => (input.publisher ? input.publisher(authorName, ctx) : { '@id': ctx.orgId }),
+    };
+    return ctx;
+}

package/dist/schema/events.d.ts

@@ -0,0 +1,31 @@
+import { type AddressPolicy } from './values.ts';
+import type { JsonLdNode, SchemaBuilder } from './types.ts';
+/** Where events take place and who runs them; every value is the site's. */
+export interface EventPolicy {
+    address: AddressPolicy;
+    /** Place name when the item has no `location`. Absent: such an item gets no `location`. */
+    defaultLocationName?: string;
+    /** Add `geo` from `coordinates` to the Place. */
+    geo?: boolean;
+    organizer(data: Record<string, any>): JsonLdNode;
+    performer(data: Record<string, any>): JsonLdNode | undefined;
+    currency?: string;
+}
+export interface EventOptions extends EventPolicy {
+    /** Map `data.offers[]` to Offers when present (else one Offer from `price`). */
+    offersArray?: boolean;
+    /** Emit the Event node; when false only the companion Article is emitted. Default: always. */
+    emitEvent?: (data: Record<string, any>) => boolean;
+    articleSection?: string;
+    inLanguage?: string;
+}
+/** Event at route `event`, its author's Person first, and a companion Article (SLA-357). */
+export declare function eventBuilder(options: EventOptions): SchemaBuilder;
+export interface EventItemListOptions extends EventPolicy {
+    /** Organizer of a listed item (may differ from the event page's). */
+    itemOrganizer(item: Record<string, any>): JsonLdNode;
+    /** A listed item is an Event only when this holds (else a WebPage). Default: it has a `startDate`. */
+    isEvent?: (item: Record<string, any>) => boolean;
+}
+/** ItemList of events, each linked at its `url`; an item that cannot be a valid Event becomes a WebPage. */
+export declare function eventItemListBuilder(options: EventItemListOptions): SchemaBuilder;

package/dist/schema/events.js

@@ -0,0 +1,139 @@
+import { createPersonSchema } from "./context.js";
+import { geoCoordinates, postalAddress } from "./values.js";
+function eventPrice(data) {
+    const isFree = data.tags?.includes('free') || data.price?.toLowerCase().includes('free');
+    const priceMatch = data.price?.match(/(\d+)/);
+    return { isFree, price: isFree ? 0 : (priceMatch ? parseFloat(priceMatch[1]) : null) };
+}
+// Offers open three months before the start date.
+function validFrom(startDate) {
+    if (!startDate)
+        return null;
+    const from = new Date(new Date(startDate));
+    from.setMonth(from.getMonth() - 3);
+    return from.toISOString();
+}
+function eventLocation(policy, data) {
+    const name = data.location || policy.defaultLocationName;
+    if (!name)
+        return undefined;
+    const geo = policy.geo ? geoCoordinates(data.coordinates) : undefined;
+    return {
+        '@type': 'Place',
+        name,
+        address: postalAddress(policy.address, data),
+        ...(geo && { geo }),
+    };
+}
+const EVENT_STATUS = (rescheduled) => (rescheduled ? 'https://schema.org/EventRescheduled' : 'https://schema.org/EventScheduled');
+const OFFLINE = 'https://schema.org/OfflineEventAttendanceMode';
+/** Event at route `event`, its author's Person first, and a companion Article (SLA-357). */
+export function eventBuilder(options) {
+    const { offersArray = false, emitEvent = () => true, articleSection = 'Events', inLanguage = 'en', currency = 'EUR' } = options;
+    return (data, ctx) => {
+        const { isFree, price } = eventPrice(data);
+        const from = validFrom(data.startDate);
+        const pageRoute = ctx.route('event', data.slug);
+        const singleOffer = price !== null ? {
+            '@type': 'Offer',
+            price,
+            priceCurrency: currency,
+            availability: 'https://schema.org/InStock',
+            url: data.officialWebsite || pageRoute,
+            validFrom: from,
+        } : undefined;
+        const event = {
+            '@type': 'Event',
+            name: data.name,
+            description: data.description,
+            image: ctx.resolveImageUrl(data.image, data.slug),
+            startDate: data.startDate || undefined,
+            endDate: data.endDate || undefined,
+            previousStartDate: data.previousStartDate || undefined,
+            eventStatus: EVENT_STATUS(data.previousStartDate),
+            eventAttendanceMode: OFFLINE,
+            isAccessibleForFree: isFree,
+            location: eventLocation(options, data),
+            organizer: options.organizer(data),
+            performer: options.performer(data),
+            offers: offersArray && (data.offers?.length ?? 0) > 0
+                ? data.offers.map((o) => ({
+                    '@type': 'Offer',
+                    price: o.price,
+                    priceCurrency: o.priceCurrency || currency,
+                    availability: `https://schema.org/${o.availability || 'InStock'}`,
+                    url: o.url || data.officialWebsite || pageRoute,
+                    validFrom: from,
+                }))
+                : singleOffer,
+            mainEntityOfPage: { '@id': ctx.pageUrl },
+            url: pageRoute,
+        };
+        const author = ctx.resolveAuthor(data.author);
+        const article = {
+            '@type': 'Article',
+            '@id': `${pageRoute}#article`,
+            headline: data.name,
+            description: data.description,
+            image: ctx.resolveImageUrl(data.image, data.slug),
+            datePublished: ctx.formatDate(data.datePublished || data.dateModified),
+            dateModified: ctx.formatDate(data.dateModified),
+            author: author ? { '@id': author.id } : undefined,
+            publisher: ctx.publisherFor(data.author),
+            mainEntityOfPage: { '@id': ctx.pageUrl },
+            articleSection,
+            inLanguage,
+        };
+        const nodes = emitEvent(data) ? [event, article] : [article];
+        return author ? [createPersonSchema(author), ...nodes] : nodes;
+    };
+}
+/** ItemList of events, each linked at its `url`; an item that cannot be a valid Event becomes a WebPage. */
+export function eventItemListBuilder(options) {
+    const { isEvent = (item) => Boolean(item.startDate), currency = 'EUR' } = options;
+    return (data, ctx) => ({
+        '@type': 'ItemList',
+        name: data.name,
+        numberOfItems: data.items?.length || 0,
+        itemListElement: data.items?.map((item) => {
+            const { isFree, price } = eventPrice(item);
+            const from = validFrom(item.startDate);
+            const performer = options.performer(item);
+            if (!isEvent(item)) {
+                return {
+                    '@type': 'ListItem',
+                    position: item.position,
+                    item: { '@type': 'WebPage', name: item.name, description: item.description, url: ctx.abs(item.url) },
+                };
+            }
+            return {
+                '@type': 'ListItem',
+                position: item.position,
+                item: {
+                    '@type': 'Event',
+                    name: item.name,
+                    description: item.description,
+                    image: ctx.resolveImageUrl(item.image, item.slug),
+                    url: ctx.abs(item.url),
+                    startDate: item.startDate,
+                    endDate: item.endDate,
+                    previousStartDate: item.previousStartDate || undefined,
+                    eventStatus: EVENT_STATUS(item.previousStartDate),
+                    eventAttendanceMode: OFFLINE,
+                    isAccessibleForFree: isFree,
+                    location: eventLocation(options, item),
+                    organizer: options.itemOrganizer(item),
+                    performer,
+                    offers: price !== null ? {
+                        '@type': 'Offer',
+                        price,
+                        priceCurrency: currency,
+                        availability: 'https://schema.org/InStock',
+                        url: item.officialWebsite || ctx.route('event', item.slug),
+                        validFrom: from,
+                    } : undefined,
+                },
+            };
+        }),
+    });
+}

package/dist/schema/graph.d.ts

@@ -0,0 +1,35 @@
+import type { JsonLdNode, SchemaBuilders, SchemaContext, SchemaEntry } from './types.ts';
+export interface BreadcrumbInput {
+    name: string;
+    url: string;
+}
+export declare function buildBreadcrumbList(ctx: SchemaContext, breadcrumbs: BreadcrumbInput[]): JsonLdNode;
+export interface PageInput {
+    entries: SchemaEntry[];
+    breadcrumbs?: BreadcrumbInput[];
+    pageTitle?: string;
+    pageDescription?: string;
+    datePublished?: string;
+    dateModified?: string;
+}
+/** The page's WebPage node: name/description/dates fall back to the first entries that carry them. */
+export declare function buildWebPageNode(ctx: SchemaContext, page: PageInput, inLanguage?: string): JsonLdNode;
+export interface AssembleOptions extends PageInput {
+    /** The site's Organization node (`@id` = `ctx.orgId`). */
+    organization: JsonLdNode;
+    /** The site's WebSite node (`@id` = `ctx.websiteId`). */
+    website: JsonLdNode;
+    builders: SchemaBuilders;
+    inLanguage?: string;
+    /** Runs after the base nodes and breadcrumb, before any entry. */
+    beforeEntries?: (graph: JsonLdNode[]) => void;
+    /** Runs once every entry is in the graph. */
+    afterEntries?: (graph: JsonLdNode[]) => void;
+}
+/**
+ * The page graph in emission order: Organization, WebSite, WebPage, BreadcrumbList (when breadcrumbs are given),
+ * then each entry's node(s) in call order. A type with no builder, or a builder returning null, emits nothing.
+ */
+export declare function assembleGraph(ctx: SchemaContext, options: AssembleOptions): JsonLdNode[];
+/** The serialisable JSON-LD document: `@context` plus the graph with every URL normalised. */
+export declare function finalizeGraph(ctx: SchemaContext, graph: JsonLdNode[]): JsonLdNode;

package/dist/schema/graph.js

@@ -0,0 +1,64 @@
+import { normalizeSiteUrl } from "../url/index.js";
+import { normalizeHomepageUrl, normalizeStructuredDataUrls } from "./context.js";
+export function buildBreadcrumbList(ctx, breadcrumbs) {
+    return {
+        '@type': 'BreadcrumbList',
+        '@id': `${ctx.pageUrl}#breadcrumb`,
+        itemListElement: breadcrumbs.map((item, index) => ({
+            '@type': 'ListItem',
+            position: index + 1,
+            name: item.name,
+            item: normalizeHomepageUrl(normalizeSiteUrl(item.url, ctx.siteUrl, ctx.basePath), ctx.siteUrl, ctx.siteBaseUrl),
+        })),
+    };
+}
+/** The page's WebPage node: name/description/dates fall back to the first entries that carry them. */
+export function buildWebPageNode(ctx, page, inLanguage = 'en') {
+    const { entries } = page;
+    return {
+        '@type': 'WebPage',
+        '@id': ctx.pageUrl,
+        url: ctx.pageUrl,
+        name: page.pageTitle || entries[0]?.data.name || entries[0]?.data.headline,
+        description: page.pageDescription || entries[0]?.data.description,
+        inLanguage,
+        datePublished: ctx.formatDate(page.datePublished
+            || entries.find((s) => s.data.datePublished)?.data.datePublished
+            || entries.find((s) => s.data.dateModified)?.data.dateModified),
+        dateModified: ctx.formatDate(page.dateModified || (() => {
+            const s = entries.find((e) => e.data.dateModified || e.data.datePublished);
+            return s?.data.dateModified || s?.data.datePublished;
+        })()),
+        isPartOf: { '@id': ctx.websiteId },
+        ...(page.breadcrumbs ? { breadcrumb: { '@id': `${ctx.pageUrl}#breadcrumb` } } : {}),
+    };
+}
+/**
+ * The page graph in emission order: Organization, WebSite, WebPage, BreadcrumbList (when breadcrumbs are given),
+ * then each entry's node(s) in call order. A type with no builder, or a builder returning null, emits nothing.
+ */
+export function assembleGraph(ctx, options) {
+    const graph = [options.organization, options.website, buildWebPageNode(ctx, options, options.inLanguage)];
+    if (options.breadcrumbs)
+        graph.push(buildBreadcrumbList(ctx, options.breadcrumbs));
+    options.beforeEntries?.(graph);
+    for (const { type, data } of options.entries) {
+        const builder = options.builders[type];
+        const result = builder ? builder(data, ctx) : null;
+        if (result === null)
+            continue;
+        if (Array.isArray(result))
+            graph.push(...result);
+        else
+            graph.push(result);
+    }
+    options.afterEntries?.(graph);
+    return graph;
+}
+/** The serialisable JSON-LD document: `@context` plus the graph with every URL normalised. */
+export function finalizeGraph(ctx, graph) {
+    return {
+        '@context': 'https://schema.org',
+        '@graph': normalizeStructuredDataUrls(graph, ctx.siteUrl, ctx.basePath),
+    };
+}

package/dist/schema/hours.d.ts

@@ -0,0 +1,47 @@
+import type { OpeningHoursSpecification } from './types.ts';
+export declare const DAY_KEYS: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
+export type DayKey = (typeof DAY_KEYS)[number];
+/** The value an `openingHours` bucket uses for a day open around the clock. */
+export declare const HOURS_ALWAYS_OPEN = "24h";
+export interface OpeningHoursInput {
+    weekdays?: unknown;
+    weekends?: unknown;
+    alwaysOpen?: unknown;
+    closed?: unknown;
+    [day: string]: unknown;
+}
+/** One resolved bucket: the hours value and the days it applies to after `closed` and per-day overrides. */
+export interface OpeningHoursBucket {
+    kind: 'grouped' | 'day' | 'alwaysOpen';
+    value: unknown;
+    days: DayKey[];
+}
+/**
+ * Splits a (possibly split-shift) bucket value such as `"13:00-16:00, 20:00-23:30"` into one pair per shift.
+ * A shift whose halves are not both clock times is dropped (SLA-2303); `24h` spans the whole day.
+ */
+export declare function parseHoursShifts(value: string): Array<{
+    opens: string;
+    closes: string;
+}>;
+/** Days a free-text `closed` field names ("Tuesdays", "Monday and Sunday"), in Monday-first order. */
+export declare function closedFieldDays(closed: unknown): Set<DayKey>;
+/**
+ * The day resolution behind `generateOpeningHours`, in emission order: weekdays, weekends, each per-day key,
+ * then `alwaysOpen`. A per-day key wins over a grouped bucket and every `closed` day is subtracted.
+ */
+export declare function resolveOpeningHours(openingHours: OpeningHoursInput): OpeningHoursBucket[];
+/**
+ * Days an `openingHours` object declares open, whether or not each bucket's value parses. The opening-hours gate
+ * asks this, so a malformed bucket still counts as an open claim; the gate reports the malformed value separately.
+ */
+export declare function assertedOpenDays(openingHours: OpeningHoursInput): Set<DayKey>;
+/** `openingHours` object → schema.org OpeningHoursSpecification list, or undefined when nothing is emitted. */
+export declare function generateOpeningHours(openingHours: OpeningHoursInput | null | undefined): OpeningHoursSpecification[] | undefined;
+/**
+ * Free-text hours line ("Tue–Sat: 9am–3pm, Sun: 9am–3pm") → OpeningHoursSpecification list. Any time range it
+ * cannot fully represent drops the whole string: partial hours read as closed to Google (SLA-2829).
+ */
+export declare function parseHoursString(hours: string | null | undefined): OpeningHoursSpecification[] | undefined;
+/** Days the JSON-LD built from a free-text hours line asserts open (the union of its specs' `dayOfWeek`). */
+export declare function hoursStringOpenDays(hours: unknown): Set<DayKey>;