@sarimarcus/content-sites-core 0.39.0 → 0.41.0
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 +12 -0
- package/README.md +2 -2
- package/dist/config/index.d.ts +0 -1
- package/dist/config/index.js +1 -1
- package/dist/eras/index.d.ts +44 -0
- package/dist/eras/index.js +68 -0
- package/dist/schema/context.js +3 -3
- package/dist/schema/policy.js +18 -1
- package/dist/schema/types.d.ts +1 -1
- package/dist/url/index.d.ts +1 -1
- package/dist/url/index.js +1 -1
- package/dist/url/routes.d.ts +2 -0
- package/dist/url/routes.js +5 -1
- package/package.json +5 -1
- package/src/config/index.ts +1 -1
- package/src/eras/index.ts +96 -0
- package/src/schema/context.ts +3 -3
- package/src/schema/policy.ts +20 -1
- package/src/schema/types.ts +1 -1
- package/src/url/index.ts +1 -1
- package/src/url/routes.ts +6 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
All packages in the platform release in lockstep; entries are per release version.
|
|
4
4
|
|
|
5
|
+
## 0.41.0 (2026-10-20)
|
|
6
|
+
|
|
7
|
+
- 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).
|
|
8
|
+
|
|
9
|
+
## 0.40.0 (2026-10-18)
|
|
10
|
+
|
|
11
|
+
- `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).
|
|
12
|
+
|
|
13
|
+
### Breaking
|
|
14
|
+
|
|
15
|
+
- `./config` no longer exports `mergeConfig`, `resolveConfig`, `siteConfigValues` or `hasCapability` (no importer existed; the module stays internal until a consumer needs it). `scripts/platform/migrations/remove-deprecated.mjs` asserts a site imports none of them (SLA-3046).
|
|
16
|
+
|
|
5
17
|
## 0.39.0 (2026-10-16)
|
|
6
18
|
|
|
7
19
|
- `schema`: `hours.ts` exports `CLOCK_TIME`, the clock-time pattern `parseHoursShifts` and `latestClosing` now share; no behaviour change (SLA-3045).
|
package/README.md
CHANGED
|
@@ -4,9 +4,9 @@ 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
|
|
|
11
11
|
Code Node loads directly (config builders imported by `astro.config.mjs`) ships compiled to `dist/` with
|
|
12
12
|
type declarations. Node will not strip types from files under `node_modules`. So every entry point resolves to
|
package/dist/config/index.d.ts
CHANGED
|
@@ -3,4 +3,3 @@ export type { SiteConfigOptions, SitemapRule, PagefindIntegration } from './site
|
|
|
3
3
|
export { outboundLinkRel } from './outboundLinkRel.ts';
|
|
4
4
|
export type { OutboundLinkRelOptions } from './outboundLinkRel.ts';
|
|
5
5
|
export { latestGuideDate, guideDateMap, guidePublishDates } from './guideDates.ts';
|
|
6
|
-
export { mergeConfig, resolveConfig, siteConfigValues, hasCapability } from './precedence.ts';
|
package/dist/config/index.js
CHANGED
|
@@ -2,4 +2,4 @@
|
|
|
2
2
|
export { defineSiteConfig, buildLastmodMap, sitemapSerialize, PAGEFIND_EXCLUDE_SELECTORS } from "./siteConfig.js";
|
|
3
3
|
export { outboundLinkRel } from "./outboundLinkRel.js";
|
|
4
4
|
export { latestGuideDate, guideDateMap, guidePublishDates } from "./guideDates.js";
|
|
5
|
-
|
|
5
|
+
// precedence.ts (resolveConfig & co.) is internal until a consumer needs it: SLA-3046.
|
|
@@ -0,0 +1,44 @@
|
|
|
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
|
+
/** ISO 8601: 929..1031 → "0929/1031", -206..500 → "-0205/0500", a single year → "1236", null end (to present) → "0929/..". */
|
|
41
|
+
export declare function formatTemporalCoverage(yearStart: number, yearEnd?: number | null): string;
|
|
42
|
+
/** The item's temporalCoverage, or undefined without an integer `yearStart`. */
|
|
43
|
+
export declare function temporalCoverageOf(data: unknown): string | undefined;
|
|
44
|
+
export {};
|
|
@@ -0,0 +1,68 @@
|
|
|
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
|
+
/** ISO 8601: 929..1031 → "0929/1031", -206..500 → "-0205/0500", a single year → "1236", null end (to present) → "0929/..". */
|
|
57
|
+
export function formatTemporalCoverage(yearStart, yearEnd) {
|
|
58
|
+
if (yearEnd === undefined)
|
|
59
|
+
return isoYear(yearStart);
|
|
60
|
+
return `${isoYear(yearStart)}/${yearEnd === null ? '..' : isoYear(yearEnd)}`;
|
|
61
|
+
}
|
|
62
|
+
/** The item's temporalCoverage, or undefined without an integer `yearStart`. */
|
|
63
|
+
export function temporalCoverageOf(data) {
|
|
64
|
+
if (!isObject(data) || !Number.isInteger(data.yearStart))
|
|
65
|
+
return undefined;
|
|
66
|
+
const end = data.yearEnd === null ? null : Number.isInteger(data.yearEnd) ? data.yearEnd : undefined;
|
|
67
|
+
return formatTemporalCoverage(data.yearStart, end);
|
|
68
|
+
}
|
package/dist/schema/context.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { normalizeSiteUrl, toAbsoluteSiteUrl } from "../url/index.js";
|
|
1
|
+
import { normalizeSiteUrl, routeSegment, toAbsoluteSiteUrl } from "../url/index.js";
|
|
2
2
|
import { slugify } from "../text/index.js";
|
|
3
3
|
/** The site root with a trailing slash (either form) collapses to the bare base URL. */
|
|
4
4
|
export function normalizeHomepageUrl(url, siteUrl, siteBaseUrl) {
|
|
@@ -61,7 +61,7 @@ export function createSchemaContext(input) {
|
|
|
61
61
|
websiteId: `${siteBaseUrl}#website`,
|
|
62
62
|
abs: (path) => `${siteUrl}${basePath}${path}`,
|
|
63
63
|
absOrHttp: (path) => (path.startsWith('http') ? path : `${siteUrl}${basePath}${path}`),
|
|
64
|
-
route: (kind, slug) => `${siteUrl}${basePath}/${
|
|
64
|
+
route: (kind, slug) => `${siteUrl}${basePath}/${routeSegment(kind, routes)}/${slug}`,
|
|
65
65
|
fileExists,
|
|
66
66
|
// /images/{type}/{name}.webp → /images/og/{type}/{name}.jpg, falling back to the slug's jpg (SLA-2817);
|
|
67
67
|
// omitted rather than pointing at a file that is not there.
|
|
@@ -81,7 +81,7 @@ export function createSchemaContext(input) {
|
|
|
81
81
|
if (!authorName)
|
|
82
82
|
return null;
|
|
83
83
|
const profile = input.findAuthor?.(authorName);
|
|
84
|
-
const url =
|
|
84
|
+
const url = ctx.route('author', profile?.slug || slugify(authorName));
|
|
85
85
|
const image = profile?.photo
|
|
86
86
|
? (profile.photo.startsWith('http') ? profile.photo : `${siteUrl}${basePath}${profile.photo}`)
|
|
87
87
|
: undefined;
|
package/dist/schema/policy.js
CHANGED
|
@@ -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/dist/schema/types.d.ts
CHANGED
|
@@ -28,7 +28,7 @@ export interface ResolvedAuthor {
|
|
|
28
28
|
image?: string;
|
|
29
29
|
sameAs?: string[];
|
|
30
30
|
}
|
|
31
|
-
/** Path segment per
|
|
31
|
+
/** Path segment per kind, e.g. `{ hotel: 'lodges' }`; the same map as `SiteRoutes`. A kind not listed uses `DEFAULT_ROUTES`, then its own name. */
|
|
32
32
|
export type RouteMap = Partial<Record<string, string>>;
|
|
33
33
|
export interface SchemaContextInput {
|
|
34
34
|
/** Site origin, with or without a trailing slash. */
|
package/dist/url/index.d.ts
CHANGED
|
@@ -5,7 +5,7 @@ export { buildImageMap } from './imageMap.ts';
|
|
|
5
5
|
export { articleFeedItem } from './feed.ts';
|
|
6
6
|
export type { FeedArticle, FeedItem } from './feed.ts';
|
|
7
7
|
export { pageTypeOf } from './pageType.ts';
|
|
8
|
-
export { DEFAULT_ROUTES, routePath } from './routes.ts';
|
|
8
|
+
export { DEFAULT_ROUTES, routePath, routeSegment } from './routes.ts';
|
|
9
9
|
export type { RouteKind, SiteRoutes } from './routes.ts';
|
|
10
10
|
export { outboundClassifier, outboundHostKey, applyOutboundRel } from './outbound.ts';
|
|
11
11
|
export type { OutboundDomainStore } from './outbound.ts';
|
package/dist/url/index.js
CHANGED
|
@@ -5,6 +5,6 @@ export { normalizeHref, extractProseHrefs, dedupRelated } from "./relatedDedup.j
|
|
|
5
5
|
export { buildImageMap } from "./imageMap.js";
|
|
6
6
|
export { articleFeedItem } from "./feed.js";
|
|
7
7
|
export { pageTypeOf } from "./pageType.js";
|
|
8
|
-
export { DEFAULT_ROUTES, routePath } from "./routes.js";
|
|
8
|
+
export { DEFAULT_ROUTES, routePath, routeSegment } from "./routes.js";
|
|
9
9
|
export { outboundClassifier, outboundHostKey, applyOutboundRel } from "./outbound.js";
|
|
10
10
|
export { RELATED_ZONE_ROLES, closerHeading, featuredInGuides, buildTakenHrefs } from "./relatedZone.js";
|
package/dist/url/routes.d.ts
CHANGED
|
@@ -7,5 +7,7 @@ export declare const DEFAULT_ROUTES: {
|
|
|
7
7
|
};
|
|
8
8
|
export type RouteKind = keyof typeof DEFAULT_ROUTES;
|
|
9
9
|
export type SiteRoutes = Partial<Record<RouteKind, string>>;
|
|
10
|
+
/** Path segment for `kind`: the site's override, then `DEFAULT_ROUTES`, then the kind's own name (vertical entity kinds). */
|
|
11
|
+
export declare function routeSegment(kind: string, routes?: Partial<Record<string, string>>): string;
|
|
10
12
|
/** `/<segment>` for `kind`, or `/<segment>/<slug>`, from `routes` first and then the default. Base path not applied. */
|
|
11
13
|
export declare function routePath(kind: RouteKind, slug?: string, routes?: SiteRoutes): string;
|
package/dist/url/routes.js
CHANGED
|
@@ -5,8 +5,12 @@ export const DEFAULT_ROUTES = {
|
|
|
5
5
|
author: 'author',
|
|
6
6
|
neighborhood: 'neighborhood',
|
|
7
7
|
};
|
|
8
|
+
/** Path segment for `kind`: the site's override, then `DEFAULT_ROUTES`, then the kind's own name (vertical entity kinds). */
|
|
9
|
+
export function routeSegment(kind, routes = {}) {
|
|
10
|
+
return routes[kind] ?? DEFAULT_ROUTES[kind] ?? kind;
|
|
11
|
+
}
|
|
8
12
|
/** `/<segment>` for `kind`, or `/<segment>/<slug>`, from `routes` first and then the default. Base path not applied. */
|
|
9
13
|
export function routePath(kind, slug, routes = {}) {
|
|
10
|
-
const segment =
|
|
14
|
+
const segment = routeSegment(kind, routes);
|
|
11
15
|
return slug === undefined ? `/${segment}` : `/${segment}/${slug}`;
|
|
12
16
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sarimarcus/content-sites-core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.41.0",
|
|
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"
|
package/src/config/index.ts
CHANGED
|
@@ -4,4 +4,4 @@ export type { SiteConfigOptions, SitemapRule, PagefindIntegration } from './site
|
|
|
4
4
|
export { outboundLinkRel } from './outboundLinkRel.ts';
|
|
5
5
|
export type { OutboundLinkRelOptions } from './outboundLinkRel.ts';
|
|
6
6
|
export { latestGuideDate, guideDateMap, guidePublishDates } from './guideDates.ts';
|
|
7
|
-
|
|
7
|
+
// precedence.ts (resolveConfig & co.) is internal until a consumer needs it: SLA-3046.
|
|
@@ -0,0 +1,96 @@
|
|
|
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
|
+
/** ISO 8601: 929..1031 → "0929/1031", -206..500 → "-0205/0500", a single year → "1236", null end (to present) → "0929/..". */
|
|
86
|
+
export function formatTemporalCoverage(yearStart: number, yearEnd?: number | null): string {
|
|
87
|
+
if (yearEnd === undefined) return isoYear(yearStart);
|
|
88
|
+
return `${isoYear(yearStart)}/${yearEnd === null ? '..' : isoYear(yearEnd)}`;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** The item's temporalCoverage, or undefined without an integer `yearStart`. */
|
|
92
|
+
export function temporalCoverageOf(data: unknown): string | undefined {
|
|
93
|
+
if (!isObject(data) || !Number.isInteger(data.yearStart)) return undefined;
|
|
94
|
+
const end = data.yearEnd === null ? null : Number.isInteger(data.yearEnd) ? (data.yearEnd as number) : undefined;
|
|
95
|
+
return formatTemporalCoverage(data.yearStart as number, end);
|
|
96
|
+
}
|
package/src/schema/context.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { normalizeSiteUrl, toAbsoluteSiteUrl } from '../url/index.ts';
|
|
1
|
+
import { normalizeSiteUrl, routeSegment, toAbsoluteSiteUrl } from '../url/index.ts';
|
|
2
2
|
import { slugify } from '../text/index.ts';
|
|
3
3
|
import type { JsonLdNode, ResolvedAuthor, SchemaContext, SchemaContextInput } from './types.ts';
|
|
4
4
|
|
|
@@ -65,7 +65,7 @@ export function createSchemaContext(input: SchemaContextInput): SchemaContext {
|
|
|
65
65
|
websiteId: `${siteBaseUrl}#website`,
|
|
66
66
|
abs: (path) => `${siteUrl}${basePath}${path}`,
|
|
67
67
|
absOrHttp: (path) => (path.startsWith('http') ? path : `${siteUrl}${basePath}${path}`),
|
|
68
|
-
route: (kind, slug) => `${siteUrl}${basePath}/${
|
|
68
|
+
route: (kind, slug) => `${siteUrl}${basePath}/${routeSegment(kind, routes)}/${slug}`,
|
|
69
69
|
fileExists,
|
|
70
70
|
// /images/{type}/{name}.webp → /images/og/{type}/{name}.jpg, falling back to the slug's jpg (SLA-2817);
|
|
71
71
|
// omitted rather than pointing at a file that is not there.
|
|
@@ -82,7 +82,7 @@ export function createSchemaContext(input: SchemaContextInput): SchemaContext {
|
|
|
82
82
|
resolveAuthor(authorName) {
|
|
83
83
|
if (!authorName) return null;
|
|
84
84
|
const profile = input.findAuthor?.(authorName);
|
|
85
|
-
const url =
|
|
85
|
+
const url = ctx.route('author', profile?.slug || slugify(authorName));
|
|
86
86
|
const image = profile?.photo
|
|
87
87
|
? (profile.photo.startsWith('http') ? profile.photo : `${siteUrl}${basePath}${profile.photo}`)
|
|
88
88
|
: undefined;
|
package/src/schema/policy.ts
CHANGED
|
@@ -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
|
}));
|
package/src/schema/types.ts
CHANGED
|
@@ -34,7 +34,7 @@ export interface ResolvedAuthor {
|
|
|
34
34
|
sameAs?: string[];
|
|
35
35
|
}
|
|
36
36
|
|
|
37
|
-
/** Path segment per
|
|
37
|
+
/** Path segment per kind, e.g. `{ hotel: 'lodges' }`; the same map as `SiteRoutes`. A kind not listed uses `DEFAULT_ROUTES`, then its own name. */
|
|
38
38
|
export type RouteMap = Partial<Record<string, string>>;
|
|
39
39
|
|
|
40
40
|
export interface SchemaContextInput {
|
package/src/url/index.ts
CHANGED
|
@@ -6,7 +6,7 @@ export { buildImageMap } from './imageMap.ts';
|
|
|
6
6
|
export { articleFeedItem } from './feed.ts';
|
|
7
7
|
export type { FeedArticle, FeedItem } from './feed.ts';
|
|
8
8
|
export { pageTypeOf } from './pageType.ts';
|
|
9
|
-
export { DEFAULT_ROUTES, routePath } from './routes.ts';
|
|
9
|
+
export { DEFAULT_ROUTES, routePath, routeSegment } from './routes.ts';
|
|
10
10
|
export type { RouteKind, SiteRoutes } from './routes.ts';
|
|
11
11
|
export { outboundClassifier, outboundHostKey, applyOutboundRel } from './outbound.ts';
|
|
12
12
|
export type { OutboundDomainStore } from './outbound.ts';
|
package/src/url/routes.ts
CHANGED
|
@@ -9,8 +9,13 @@ export const DEFAULT_ROUTES = {
|
|
|
9
9
|
export type RouteKind = keyof typeof DEFAULT_ROUTES;
|
|
10
10
|
export type SiteRoutes = Partial<Record<RouteKind, string>>;
|
|
11
11
|
|
|
12
|
+
/** Path segment for `kind`: the site's override, then `DEFAULT_ROUTES`, then the kind's own name (vertical entity kinds). */
|
|
13
|
+
export function routeSegment(kind: string, routes: Partial<Record<string, string>> = {}): string {
|
|
14
|
+
return routes[kind] ?? (DEFAULT_ROUTES as Record<string, string>)[kind] ?? kind;
|
|
15
|
+
}
|
|
16
|
+
|
|
12
17
|
/** `/<segment>` for `kind`, or `/<segment>/<slug>`, from `routes` first and then the default. Base path not applied. */
|
|
13
18
|
export function routePath(kind: RouteKind, slug?: string, routes: SiteRoutes = {}): string {
|
|
14
|
-
const segment =
|
|
19
|
+
const segment = routeSegment(kind, routes);
|
|
15
20
|
return slug === undefined ? `/${segment}` : `/${segment}/${slug}`;
|
|
16
21
|
}
|