@sarimarcus/content-sites-core 0.40.0 → 0.41.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,14 @@
2
2
 
3
3
  All packages in the platform release in lockstep; entries are per release version.
4
4
 
5
+ ## 0.41.1 (2026-10-21)
6
+
7
+ - `eras`: new `formatYearRange(yearStart, yearEnd)`, the display form of an item's years in the historians' count (`929`, `206–100 BCE`, `206 BCE–500 CE`), `undefined` without a start. No change to existing exports (SLA-3274).
8
+
9
+ ## 0.41.0 (2026-10-20)
10
+
11
+ - New `./eras` export for per-site historical-era classification: `EraDefinition` (the era data a site supplies), `eraHref`, `findEra`, `eraSchemaFields(z, eraValues)` (optional `era`, `yearStart`, `yearEnd` for a content collection), `eraYearIssues` (no year 0, `yearStart <= yearEnd`, for a superRefine), `eraFieldIssues`, `formatTemporalCoverage` and `temporalCoverageOf`. Years use the historians' count (`-206` = 206 BCE) and are written to ISO 8601 astronomically (`-0205`). `schema`: `renderSchemaPolicy` adds `temporalCoverage` to an entry's `Article` node when its data has `yearStart` (a single year, or an interval with `yearEnd`); JSON-LD is unchanged for every entry without it (SLA-3251).
12
+
5
13
  ## 0.40.0 (2026-10-18)
6
14
 
7
15
  - `url`: new `routeSegment(kind, routes?)` (override, then `DEFAULT_ROUTES`, then the kind's own name); `routePath` uses it. `schema`: `ctx.route` and `resolveAuthor` resolve through it, so one `SiteRoutes` override moves links and JSON-LD URLs together. Before, the schema context only read its own `routes` and the author URL was always `/author/` (SLA-3046).
package/README.md CHANGED
@@ -4,7 +4,7 @@ Non-visual code shared by the content sites: generic utilities, Astro config bui
4
4
  and the type contracts `ui` and `tourism` build on (for example the card item and tag-link shapes that
5
5
  today's ui components import from tourism code).
6
6
 
7
- Named entry points: `url`, `affiliate`, `dates`, `geo`, `dom`, `text`, `config`, `types`, `schema`, `interludes`, `images` and `articles` (`src/internal` is never exported). No `.astro`
7
+ Named entry points: `url`, `affiliate`, `dates`, `geo`, `dom`, `text`, `config`, `types`, `schema`, `interludes`, `eras`, `images` and `articles` (`src/internal` is never exported). No `.astro`
8
8
  files. Lowest layer: imports nothing from the other packages; its one runtime dependency is `marked` (`readingTime`). Ownership per path is in
9
9
  `data/snapshots/platform/catalogue.json` (owner `core`).
10
10
 
@@ -0,0 +1,46 @@
1
+ import type { z as Zod } from 'astro/zod';
2
+ /** One era of a site's chronology. Years are proleptic Gregorian integers, negative = BCE; `endYear` null = to present. */
3
+ export interface EraDefinition {
4
+ id: string;
5
+ label: string;
6
+ startYear: number;
7
+ endYear: number | null;
8
+ rangeLabel: string;
9
+ intro: string;
10
+ /** Fragment id on the chronology page, without '#'. */
11
+ anchor: string;
12
+ dossiers?: {
13
+ label: string;
14
+ href: string;
15
+ }[];
16
+ }
17
+ export interface EraIssue {
18
+ path: string;
19
+ message: string;
20
+ }
21
+ export declare function eraHref(era: EraDefinition, basePath?: string): string;
22
+ export declare function findEra(eras: readonly EraDefinition[], id: string | undefined): EraDefinition | undefined;
23
+ /** The builders the fields use; `astro:content`'s `z` and `astro/zod` both satisfy it. */
24
+ type ZodBuilders = Pick<typeof Zod, 'enum' | 'number'>;
25
+ /**
26
+ * Optional `era`, `yearStart` and `yearEnd` for a collection's `z.object({...})`. `z` is the site's own, as in
27
+ * `createInterludeSchema`. Apply `eraYearIssues` in the collection's superRefine for the yearStart <= yearEnd order.
28
+ */
29
+ export declare function eraSchemaFields(z: ZodBuilders, eraValues: readonly string[]): {
30
+ era: Zod.ZodOptional<Zod.ZodEnum<{
31
+ [x: string]: string;
32
+ }>>;
33
+ yearStart: Zod.ZodOptional<Zod.ZodNumber>;
34
+ yearEnd: Zod.ZodOptional<Zod.ZodNumber>;
35
+ };
36
+ /** No year 0 and the yearStart <= yearEnd order, for a site schema's superRefine (`ctx.addIssue` with `path: [path]`). */
37
+ export declare function eraYearIssues(data: unknown): EraIssue[];
38
+ /** Every era-field issue for an item's data, for factory scripts. Pure; never throws on malformed input. */
39
+ export declare function eraFieldIssues(data: unknown, eraValues: readonly string[]): EraIssue[];
40
+ /** Display form of an item's years: 929 → "929", -206..-100 → "206–100 BCE", -206..500 → "206 BCE–500 CE"; no start → undefined. */
41
+ export declare function formatYearRange(yearStart?: number, yearEnd?: number): string | undefined;
42
+ /** ISO 8601: 929..1031 → "0929/1031", -206..500 → "-0205/0500", a single year → "1236", null end (to present) → "0929/..". */
43
+ export declare function formatTemporalCoverage(yearStart: number, yearEnd?: number | null): string;
44
+ /** The item's temporalCoverage, or undefined without an integer `yearStart`. */
45
+ export declare function temporalCoverageOf(data: unknown): string | undefined;
46
+ export {};
@@ -0,0 +1,79 @@
1
+ export function eraHref(era, basePath = '/chronology') {
2
+ return `${basePath}#${era.anchor}`;
3
+ }
4
+ export function findEra(eras, id) {
5
+ return id === undefined ? undefined : eras.find((era) => era.id === id);
6
+ }
7
+ /**
8
+ * Optional `era`, `yearStart` and `yearEnd` for a collection's `z.object({...})`. `z` is the site's own, as in
9
+ * `createInterludeSchema`. Apply `eraYearIssues` in the collection's superRefine for the yearStart <= yearEnd order.
10
+ */
11
+ export function eraSchemaFields(z, eraValues) {
12
+ if (!eraValues.length)
13
+ throw new Error('eraSchemaFields: eraValues is empty');
14
+ return {
15
+ era: z.enum(eraValues).optional(),
16
+ yearStart: z.number().int().optional(),
17
+ yearEnd: z.number().int().optional(),
18
+ };
19
+ }
20
+ const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
21
+ /** No year 0 and the yearStart <= yearEnd order, for a site schema's superRefine (`ctx.addIssue` with `path: [path]`). */
22
+ export function eraYearIssues(data) {
23
+ if (!isObject(data))
24
+ return [];
25
+ const { yearStart, yearEnd } = data;
26
+ const issues = [];
27
+ for (const field of ['yearStart', 'yearEnd']) {
28
+ if (data[field] === 0)
29
+ issues.push({ path: field, message: `${field}: there is no year 0 (use -1 for 1 BCE, 1 for 1 CE)` });
30
+ }
31
+ if (typeof yearStart === 'number' && typeof yearEnd === 'number' && yearStart > yearEnd) {
32
+ issues.push({ path: 'yearEnd', message: `yearEnd (${yearEnd}) is before yearStart (${yearStart})` });
33
+ }
34
+ return issues;
35
+ }
36
+ /** Every era-field issue for an item's data, for factory scripts. Pure; never throws on malformed input. */
37
+ export function eraFieldIssues(data, eraValues) {
38
+ if (!isObject(data))
39
+ return [{ path: '', message: 'item: expected a JSON object' }];
40
+ const issues = [];
41
+ if (data.era !== undefined && !(typeof data.era === 'string' && eraValues.includes(data.era))) {
42
+ issues.push({ path: 'era', message: `era: unknown era ${JSON.stringify(data.era)} (expected one of: ${eraValues.join(', ')})` });
43
+ }
44
+ for (const field of ['yearStart', 'yearEnd']) {
45
+ if (data[field] !== undefined && !Number.isInteger(data[field])) {
46
+ issues.push({ path: field, message: `${field}: expected an integer year, got ${JSON.stringify(data[field])}` });
47
+ }
48
+ }
49
+ return [...issues, ...eraYearIssues(data)];
50
+ }
51
+ // Content years are historians' (-206 = 206 BCE, no year 0); ISO 8601 counts astronomically (0000 = 1 BCE).
52
+ const isoYear = (year) => {
53
+ const astronomical = year < 0 ? year + 1 : year;
54
+ return `${astronomical < 0 ? '-' : ''}${String(Math.abs(astronomical)).padStart(4, '0')}`;
55
+ };
56
+ /** Display form of an item's years: 929 → "929", -206..-100 → "206–100 BCE", -206..500 → "206 BCE–500 CE"; no start → undefined. */
57
+ export function formatYearRange(yearStart, yearEnd) {
58
+ if (yearStart === undefined)
59
+ return undefined;
60
+ const year = (y) => (y < 0 ? `${-y} BCE` : `${y}`);
61
+ if (yearEnd === undefined || yearEnd === yearStart)
62
+ return year(yearStart);
63
+ if (yearStart < 0 && yearEnd < 0)
64
+ return `${-yearStart}–${-yearEnd} BCE`;
65
+ return `${year(yearStart)}–${yearEnd}${yearStart < 0 ? ' CE' : ''}`;
66
+ }
67
+ /** ISO 8601: 929..1031 → "0929/1031", -206..500 → "-0205/0500", a single year → "1236", null end (to present) → "0929/..". */
68
+ export function formatTemporalCoverage(yearStart, yearEnd) {
69
+ if (yearEnd === undefined)
70
+ return isoYear(yearStart);
71
+ return `${isoYear(yearStart)}/${yearEnd === null ? '..' : isoYear(yearEnd)}`;
72
+ }
73
+ /** The item's temporalCoverage, or undefined without an integer `yearStart`. */
74
+ export function temporalCoverageOf(data) {
75
+ if (!isObject(data) || !Number.isInteger(data.yearStart))
76
+ return undefined;
77
+ const end = data.yearEnd === null ? null : Number.isInteger(data.yearEnd) ? data.yearEnd : undefined;
78
+ return formatTemporalCoverage(data.yearStart, end);
79
+ }
@@ -1,5 +1,22 @@
1
+ import { temporalCoverageOf } from "../eras/index.js";
1
2
  import { createSchemaContext } from "./context.js";
2
3
  import { assembleGraph, finalizeGraph } from "./graph.js";
4
+ // schema.org defines temporalCoverage on CreativeWork only; a Place node (TouristAttraction) would not validate.
5
+ const TEMPORAL_TYPES = new Set(['Article']);
6
+ const withCoverage = (node, coverage) => {
7
+ const types = Array.isArray(node?.['@type']) ? node['@type'] : [node?.['@type']];
8
+ return types.some((t) => TEMPORAL_TYPES.has(t)) ? { ...node, temporalCoverage: coverage } : node;
9
+ };
10
+ /** Adds `temporalCoverage` to an entry's Article node when its data has `yearStart`. */
11
+ function withTemporalCoverage(builders) {
12
+ return Object.fromEntries(Object.entries(builders).map(([type, builder]) => [type, builder && ((data, ctx) => {
13
+ const result = builder(data, ctx);
14
+ const coverage = temporalCoverageOf(data);
15
+ if (!coverage || result === null)
16
+ return result;
17
+ return Array.isArray(result) ? result.map((node) => withCoverage(node, coverage)) : withCoverage(result, coverage);
18
+ })]));
19
+ }
3
20
  /**
4
21
  * One page's finalised JSON-LD under a site policy: context, base nodes, entries, hooks. The site adapter and the
5
22
  * factory schema goldens both render through this, so the goldens test the wiring that ships.
@@ -8,7 +25,7 @@ export function renderSchemaPolicy(input, policy, page) {
8
25
  const ctx = createSchemaContext({ ...input, ...policy.context });
9
26
  return finalizeGraph(ctx, assembleGraph(ctx, {
10
27
  ...policy.nodes(ctx),
11
- builders: policy.builders,
28
+ builders: withTemporalCoverage(policy.builders),
12
29
  ...page,
13
30
  ...policy.hooks?.(ctx, page.entries),
14
31
  }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sarimarcus/content-sites-core",
3
- "version": "0.40.0",
3
+ "version": "0.41.1",
4
4
  "description": "Non-visual utilities, Astro config builders and SEO schema assembly shared by the content sites.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -78,6 +78,10 @@
78
78
  "types": "./dist/interludes/index.d.ts",
79
79
  "default": "./dist/interludes/index.js"
80
80
  },
81
+ "./eras": {
82
+ "types": "./dist/eras/index.d.ts",
83
+ "default": "./dist/eras/index.js"
84
+ },
81
85
  "./images": {
82
86
  "types": "./dist/images/index.d.ts",
83
87
  "default": "./dist/images/index.js"
@@ -0,0 +1,105 @@
1
+ // Public surface of @sarimarcus/content-sites-core/eras: historical-era classification. The era list is per site
2
+ // data; this module holds the contract, the content-collection fields and the temporalCoverage format.
3
+ import type { z as Zod } from 'astro/zod';
4
+
5
+ /** One era of a site's chronology. Years are proleptic Gregorian integers, negative = BCE; `endYear` null = to present. */
6
+ export interface EraDefinition {
7
+ id: string;
8
+ label: string;
9
+ startYear: number;
10
+ endYear: number | null;
11
+ rangeLabel: string;
12
+ intro: string;
13
+ /** Fragment id on the chronology page, without '#'. */
14
+ anchor: string;
15
+ dossiers?: { label: string; href: string }[];
16
+ }
17
+
18
+ export interface EraIssue {
19
+ path: string;
20
+ message: string;
21
+ }
22
+
23
+ export function eraHref(era: EraDefinition, basePath = '/chronology'): string {
24
+ return `${basePath}#${era.anchor}`;
25
+ }
26
+
27
+ export function findEra(eras: readonly EraDefinition[], id: string | undefined): EraDefinition | undefined {
28
+ return id === undefined ? undefined : eras.find((era) => era.id === id);
29
+ }
30
+
31
+ /** The builders the fields use; `astro:content`'s `z` and `astro/zod` both satisfy it. */
32
+ type ZodBuilders = Pick<typeof Zod, 'enum' | 'number'>;
33
+
34
+ /**
35
+ * Optional `era`, `yearStart` and `yearEnd` for a collection's `z.object({...})`. `z` is the site's own, as in
36
+ * `createInterludeSchema`. Apply `eraYearIssues` in the collection's superRefine for the yearStart <= yearEnd order.
37
+ */
38
+ export function eraSchemaFields(z: ZodBuilders, eraValues: readonly string[]) {
39
+ if (!eraValues.length) throw new Error('eraSchemaFields: eraValues is empty');
40
+ return {
41
+ era: z.enum(eraValues as [string, ...string[]]).optional(),
42
+ yearStart: z.number().int().optional(),
43
+ yearEnd: z.number().int().optional(),
44
+ };
45
+ }
46
+
47
+ const isObject = (value: unknown): value is Record<string, unknown> =>
48
+ value !== null && typeof value === 'object' && !Array.isArray(value);
49
+
50
+ /** No year 0 and the yearStart <= yearEnd order, for a site schema's superRefine (`ctx.addIssue` with `path: [path]`). */
51
+ export function eraYearIssues(data: unknown): EraIssue[] {
52
+ if (!isObject(data)) return [];
53
+ const { yearStart, yearEnd } = data;
54
+ const issues: EraIssue[] = [];
55
+ for (const field of ['yearStart', 'yearEnd'] as const) {
56
+ if (data[field] === 0) issues.push({ path: field, message: `${field}: there is no year 0 (use -1 for 1 BCE, 1 for 1 CE)` });
57
+ }
58
+ if (typeof yearStart === 'number' && typeof yearEnd === 'number' && yearStart > yearEnd) {
59
+ issues.push({ path: 'yearEnd', message: `yearEnd (${yearEnd}) is before yearStart (${yearStart})` });
60
+ }
61
+ return issues;
62
+ }
63
+
64
+ /** Every era-field issue for an item's data, for factory scripts. Pure; never throws on malformed input. */
65
+ export function eraFieldIssues(data: unknown, eraValues: readonly string[]): EraIssue[] {
66
+ if (!isObject(data)) return [{ path: '', message: 'item: expected a JSON object' }];
67
+ const issues: EraIssue[] = [];
68
+ if (data.era !== undefined && !(typeof data.era === 'string' && eraValues.includes(data.era))) {
69
+ issues.push({ path: 'era', message: `era: unknown era ${JSON.stringify(data.era)} (expected one of: ${eraValues.join(', ')})` });
70
+ }
71
+ for (const field of ['yearStart', 'yearEnd'] as const) {
72
+ if (data[field] !== undefined && !Number.isInteger(data[field])) {
73
+ issues.push({ path: field, message: `${field}: expected an integer year, got ${JSON.stringify(data[field])}` });
74
+ }
75
+ }
76
+ return [...issues, ...eraYearIssues(data)];
77
+ }
78
+
79
+ // Content years are historians' (-206 = 206 BCE, no year 0); ISO 8601 counts astronomically (0000 = 1 BCE).
80
+ const isoYear = (year: number): string => {
81
+ const astronomical = year < 0 ? year + 1 : year;
82
+ return `${astronomical < 0 ? '-' : ''}${String(Math.abs(astronomical)).padStart(4, '0')}`;
83
+ };
84
+
85
+ /** Display form of an item's years: 929 → "929", -206..-100 → "206–100 BCE", -206..500 → "206 BCE–500 CE"; no start → undefined. */
86
+ export function formatYearRange(yearStart?: number, yearEnd?: number): string | undefined {
87
+ if (yearStart === undefined) return undefined;
88
+ const year = (y: number) => (y < 0 ? `${-y} BCE` : `${y}`);
89
+ if (yearEnd === undefined || yearEnd === yearStart) return year(yearStart);
90
+ if (yearStart < 0 && yearEnd < 0) return `${-yearStart}–${-yearEnd} BCE`;
91
+ return `${year(yearStart)}–${yearEnd}${yearStart < 0 ? ' CE' : ''}`;
92
+ }
93
+
94
+ /** ISO 8601: 929..1031 → "0929/1031", -206..500 → "-0205/0500", a single year → "1236", null end (to present) → "0929/..". */
95
+ export function formatTemporalCoverage(yearStart: number, yearEnd?: number | null): string {
96
+ if (yearEnd === undefined) return isoYear(yearStart);
97
+ return `${isoYear(yearStart)}/${yearEnd === null ? '..' : isoYear(yearEnd)}`;
98
+ }
99
+
100
+ /** The item's temporalCoverage, or undefined without an integer `yearStart`. */
101
+ export function temporalCoverageOf(data: unknown): string | undefined {
102
+ if (!isObject(data) || !Number.isInteger(data.yearStart)) return undefined;
103
+ const end = data.yearEnd === null ? null : Number.isInteger(data.yearEnd) ? (data.yearEnd as number) : undefined;
104
+ return formatTemporalCoverage(data.yearStart as number, end);
105
+ }
@@ -1,3 +1,4 @@
1
+ import { temporalCoverageOf } from '../eras/index.ts';
1
2
  import { createSchemaContext } from './context.ts';
2
3
  import { assembleGraph, finalizeGraph, type AssembleOptions, type PageInput } from './graph.ts';
3
4
  import type { JsonLdNode, SchemaBuilders, SchemaContext, SchemaContextInput, SchemaEntry } from './types.ts';
@@ -10,6 +11,24 @@ export interface SchemaPolicy {
10
11
  hooks?(ctx: SchemaContext, entries: SchemaEntry[]): Pick<AssembleOptions, 'beforeEntries' | 'afterEntries'>;
11
12
  }
12
13
 
14
+ // schema.org defines temporalCoverage on CreativeWork only; a Place node (TouristAttraction) would not validate.
15
+ const TEMPORAL_TYPES = new Set(['Article']);
16
+
17
+ const withCoverage = (node: JsonLdNode, coverage: string): JsonLdNode => {
18
+ const types = Array.isArray(node?.['@type']) ? node['@type'] : [node?.['@type']];
19
+ return types.some((t: unknown) => TEMPORAL_TYPES.has(t as string)) ? { ...node, temporalCoverage: coverage } : node;
20
+ };
21
+
22
+ /** Adds `temporalCoverage` to an entry's Article node when its data has `yearStart`. */
23
+ function withTemporalCoverage(builders: SchemaBuilders): SchemaBuilders {
24
+ return Object.fromEntries(Object.entries(builders).map(([type, builder]) => [type, builder && ((data, ctx) => {
25
+ const result = builder(data, ctx);
26
+ const coverage = temporalCoverageOf(data);
27
+ if (!coverage || result === null) return result;
28
+ return Array.isArray(result) ? result.map((node) => withCoverage(node, coverage)) : withCoverage(result, coverage);
29
+ })]));
30
+ }
31
+
13
32
  /**
14
33
  * One page's finalised JSON-LD under a site policy: context, base nodes, entries, hooks. The site adapter and the
15
34
  * factory schema goldens both render through this, so the goldens test the wiring that ships.
@@ -18,7 +37,7 @@ export function renderSchemaPolicy(input: SchemaContextInput, policy: SchemaPoli
18
37
  const ctx = createSchemaContext({ ...input, ...policy.context });
19
38
  return finalizeGraph(ctx, assembleGraph(ctx, {
20
39
  ...policy.nodes(ctx),
21
- builders: policy.builders,
40
+ builders: withTemporalCoverage(policy.builders),
22
41
  ...page,
23
42
  ...policy.hooks?.(ctx, page.entries),
24
43
  }));