@sarimarcus/content-sites-core 0.41.2 → 0.42.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 +9 -0
- package/dist/articles/formats.d.ts +2 -4
- package/dist/articles/formats.js +1 -1
- package/dist/config/precedence.js +2 -2
- package/dist/eras/index.d.ts +2 -4
- package/dist/eras/index.js +2 -13
- package/dist/internal/guards.d.ts +5 -0
- package/dist/internal/guards.js +18 -0
- package/dist/internal/issues.d.ts +5 -0
- package/dist/internal/issues.js +1 -0
- package/dist/internal/seo.d.ts +2 -0
- package/dist/internal/seo.js +3 -0
- package/dist/people/index.d.ts +96 -0
- package/dist/people/index.js +143 -0
- package/dist/schema/index.d.ts +1 -1
- package/dist/schema/index.js +1 -1
- package/dist/schema/pages.d.ts +7 -0
- package/dist/schema/pages.js +27 -0
- package/package.json +5 -1
- package/src/articles/formats.ts +4 -6
- package/src/config/precedence.ts +2 -4
- package/src/eras/index.ts +4 -16
- package/src/internal/guards.ts +23 -0
- package/src/internal/issues.ts +5 -0
- package/src/internal/seo.ts +4 -0
- package/src/people/index.ts +190 -0
- package/src/schema/index.ts +1 -1
- package/src/schema/pages.ts +28 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
All packages in the platform release in lockstep; entries are per release version.
|
|
4
4
|
|
|
5
|
+
## 0.42.0 (2026-10-21)
|
|
6
|
+
|
|
7
|
+
- `people`: new `lifeSpan({ birthYear, deathYear })` returns `{ kind: 'range' | 'born' | 'died' | 'none', years?, age? }` (years through `formatYearRange`, an age that skips the missing year 0 across BCE/CE); `formatLifeDates` is built on it with the same output. No change to existing exports (SLA-3290).
|
|
8
|
+
|
|
9
|
+
## 0.41.3 (2026-10-21)
|
|
10
|
+
|
|
11
|
+
- New `./people` export for the people content collection (historical figures): `peopleSchemaFields(z, { eraValues, roleValues, image })` (name, slug, aliases, `birthYear`/`deathYear`/`circa`, optional `era`, roles, description 150-160, seoTitle 50-60, bio, optional `primaryArticle`, `sameAs` with a required Wikidata URL, image, an `imageAlt` that starts with "Illustration of", `dateModified`), `personYearIssues` (no year 0, `birthYear <= deathYear`, for a superRefine), `personFieldIssues` (those plus the alt prefix, for scripts), `personRefIssues` (an item's `people: [slug]` is an array of known, distinct slugs), `primaryArticleIssues`, `buildPersonBacklinks` (person slug to the distinct linking items), `countInboundRefs` (excludes the person's own `primaryArticle`) and `formatLifeDates`. `schema`: new `historicalPersonSchema()` builder, a deceased figure's Person node with the `@id` of its canonical `/person/<slug>` route, `birthDate`/`deathDate` from the years, `sameAs` and `alternateName`, and no `jobTitle` or `worksFor`; `personBuilder` and the author Person are unchanged. No change to existing exports (SLA-3260).
|
|
12
|
+
- `people`: `peopleSchemaFields` requires `targetKeyword` (a trimmed, non-empty string) and `personFieldIssues` reports a missing or blank one, matching the factory people gate (SLA-3260).
|
|
13
|
+
|
|
5
14
|
## 0.41.2 (2026-10-21)
|
|
6
15
|
|
|
7
16
|
- Lockstep release; no change to this package (SLA-3274).
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { FieldIssue } from '../internal/issues.ts';
|
|
1
2
|
export type Range = readonly [number, number];
|
|
2
3
|
export type ArticleMode = 'evergreen' | 'discover';
|
|
3
4
|
export interface ShapeRanges {
|
|
@@ -17,10 +18,7 @@ export interface ArticleShape extends ShapeRanges {
|
|
|
17
18
|
mode: ArticleMode;
|
|
18
19
|
words?: Range;
|
|
19
20
|
}
|
|
20
|
-
export
|
|
21
|
-
path: string;
|
|
22
|
-
message: string;
|
|
23
|
-
}
|
|
21
|
+
export type ShapeIssue = FieldIssue;
|
|
24
22
|
export declare const LEGACY_SHAPE: Record<ArticleMode, ShapeRanges>;
|
|
25
23
|
/** Format names as a tuple, usable in `z.enum`. FORMATS is typed against it, so tsc rejects a missing or extra key. */
|
|
26
24
|
export declare const ARTICLE_FORMATS: readonly ["direct-answer", "explainer", "narrative-profile", "claim-check", "roundup", "how-to", "comparison", "faq-hub"];
|
package/dist/articles/formats.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// Single shape table for article formats (SLA-3037), consumed by the site schemas and the factory gate.
|
|
2
2
|
// Catalogue: .claude/skills/article-craft/references/formats.md. An article without `editorialFormat` keeps the
|
|
3
3
|
// legacy shape (article-craft §1 / discover-mode.md). Pure: no Node APIs, it runs in the Astro build.
|
|
4
|
+
import { isObject } from "../internal/guards.js";
|
|
4
5
|
const DISCOVER = { sections: [3, 6], faqs: [0, 3], words: [700, 1600] };
|
|
5
6
|
const EXPLAINER = { sections: [4, 6], faqs: [5, 9], words: [1500, 2100] };
|
|
6
7
|
export const LEGACY_SHAPE = {
|
|
@@ -42,7 +43,6 @@ export const ARTICLE_SHAPE_UNION = {
|
|
|
42
43
|
keyFacts: span((s) => s.keyFacts),
|
|
43
44
|
};
|
|
44
45
|
const fmt = ([min, max]) => (min === max ? `${min}` : `${min}–${max}`);
|
|
45
|
-
const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
46
46
|
const isFormat = (value) => typeof value === 'string' && Object.hasOwn(FORMATS, value);
|
|
47
47
|
const modeOf = (article) => article?.editorialMode === 'discover' ? 'discover' : 'evergreen';
|
|
48
48
|
/** Effective ranges for an article, or null when its editorialFormat is not a known format. */
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
import { isObject } from "../internal/guards.js";
|
|
2
2
|
/**
|
|
3
3
|
* `over` laid on `base`: a key `over` leaves undefined keeps the base value; an object merges key by key with the same
|
|
4
4
|
* rule; anything else (an array included) replaces the base value whole. Arrays never merge.
|
|
@@ -11,7 +11,7 @@ export function mergeConfig(base, over) {
|
|
|
11
11
|
if (value === undefined)
|
|
12
12
|
continue;
|
|
13
13
|
const prior = out[key];
|
|
14
|
-
out[key] =
|
|
14
|
+
out[key] = isObject(prior) && isObject(value) ? mergeConfig(prior, value) : value;
|
|
15
15
|
}
|
|
16
16
|
return out;
|
|
17
17
|
}
|
package/dist/eras/index.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { z as Zod } from 'astro/zod';
|
|
2
|
+
import type { FieldIssue } from '../internal/issues.ts';
|
|
2
3
|
/** One era of a site's chronology. Years are proleptic Gregorian integers, negative = BCE; `endYear` null = to present. */
|
|
3
4
|
export interface EraDefinition {
|
|
4
5
|
id: string;
|
|
@@ -14,10 +15,7 @@ export interface EraDefinition {
|
|
|
14
15
|
href: string;
|
|
15
16
|
}[];
|
|
16
17
|
}
|
|
17
|
-
export
|
|
18
|
-
path: string;
|
|
19
|
-
message: string;
|
|
20
|
-
}
|
|
18
|
+
export type EraIssue = FieldIssue;
|
|
21
19
|
export declare function eraHref(era: EraDefinition, basePath?: string): string;
|
|
22
20
|
export declare function findEra(eras: readonly EraDefinition[], id: string | undefined): EraDefinition | undefined;
|
|
23
21
|
/** The builders the fields use; `astro:content`'s `z` and `astro/zod` both satisfy it. */
|
package/dist/eras/index.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { isObject, yearPairIssues } from "../internal/guards.js";
|
|
1
2
|
export function eraHref(era, basePath = '/chronology') {
|
|
2
3
|
return `${basePath}#${era.anchor}`;
|
|
3
4
|
}
|
|
@@ -17,21 +18,9 @@ export function eraSchemaFields(z, eraValues) {
|
|
|
17
18
|
yearEnd: z.number().int().optional(),
|
|
18
19
|
};
|
|
19
20
|
}
|
|
20
|
-
const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
21
21
|
/** No year 0 and the yearStart <= yearEnd order, for a site schema's superRefine (`ctx.addIssue` with `path: [path]`). */
|
|
22
22
|
export function eraYearIssues(data) {
|
|
23
|
-
|
|
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;
|
|
23
|
+
return yearPairIssues(data, 'yearStart', 'yearEnd');
|
|
35
24
|
}
|
|
36
25
|
/** Every era-field issue for an item's data, for factory scripts. Pure; never throws on malformed input. */
|
|
37
26
|
export function eraFieldIssues(data, eraValues) {
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { FieldIssue } from './issues.ts';
|
|
2
|
+
export declare const isObject: (value: unknown) => value is Record<string, unknown>;
|
|
3
|
+
export declare const asSet: <T>(values: ReadonlySet<T> | readonly T[]) => ReadonlySet<T>;
|
|
4
|
+
/** No year 0 and `startField <= endField`; the issue for the order sits on `endField`. */
|
|
5
|
+
export declare function yearPairIssues(data: unknown, startField: string, endField: string): FieldIssue[];
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
export const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
2
|
+
export const asSet = (values) => values instanceof Set ? values : new Set(values);
|
|
3
|
+
/** No year 0 and `startField <= endField`; the issue for the order sits on `endField`. */
|
|
4
|
+
export function yearPairIssues(data, startField, endField) {
|
|
5
|
+
if (!isObject(data))
|
|
6
|
+
return [];
|
|
7
|
+
const start = data[startField];
|
|
8
|
+
const end = data[endField];
|
|
9
|
+
const issues = [];
|
|
10
|
+
for (const field of [startField, endField]) {
|
|
11
|
+
if (data[field] === 0)
|
|
12
|
+
issues.push({ path: field, message: `${field}: there is no year 0 (use -1 for 1 BCE, 1 for 1 CE)` });
|
|
13
|
+
}
|
|
14
|
+
if (typeof start === 'number' && typeof end === 'number' && start > end) {
|
|
15
|
+
issues.push({ path: endField, message: `${endField} (${end}) is before ${startField} (${start})` });
|
|
16
|
+
}
|
|
17
|
+
return issues;
|
|
18
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import type { z as Zod } from 'astro/zod';
|
|
2
|
+
import type { FieldIssue } from '../internal/issues.ts';
|
|
3
|
+
/** The builders the fields use; `astro:content`'s `z` and `astro/zod` both satisfy it. */
|
|
4
|
+
type ZodBuilders = Pick<typeof Zod, 'enum' | 'number' | 'string' | 'array' | 'boolean' | 'object'>;
|
|
5
|
+
export declare const PERSON_ROLES: readonly ["ruler", "military", "scholar", "philosopher", "poet", "writer", "architect", "artist", "saint", "cleric", "physician", "patron"];
|
|
6
|
+
export declare const PERSON_ALT_PREFIX = "Illustration of ";
|
|
7
|
+
export interface PeopleSchemaOptions {
|
|
8
|
+
/** The site's era ids (the `eras` module); omit to leave `era` out of the schema. */
|
|
9
|
+
eraValues?: readonly string[];
|
|
10
|
+
/** Defaults to `PERSON_ROLES`. */
|
|
11
|
+
roleValues?: readonly string[];
|
|
12
|
+
/** The site's image field schema (`image()` from `astro:content` for an asset import); defaults to a string path. */
|
|
13
|
+
image?: unknown;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Fields of a `people` collection's `z.object({...})`. `z` is the site's own, as in `eraSchemaFields`. Apply
|
|
17
|
+
* `personYearIssues` in the collection's superRefine for the year order.
|
|
18
|
+
*/
|
|
19
|
+
export declare function peopleSchemaFields(z: ZodBuilders, options?: PeopleSchemaOptions): {
|
|
20
|
+
roles: Zod.ZodArray<Zod.ZodEnum<{
|
|
21
|
+
[x: string]: string;
|
|
22
|
+
}>>;
|
|
23
|
+
description: Zod.ZodString;
|
|
24
|
+
targetKeyword: Zod.ZodString;
|
|
25
|
+
seoTitle: Zod.ZodString;
|
|
26
|
+
bio: Zod.ZodString;
|
|
27
|
+
primaryArticle: Zod.ZodOptional<Zod.ZodString>;
|
|
28
|
+
sameAs: Zod.ZodObject<{
|
|
29
|
+
wikidata: Zod.ZodString;
|
|
30
|
+
wikipedia: Zod.ZodOptional<Zod.ZodString>;
|
|
31
|
+
}, Zod.z.core.$strip>;
|
|
32
|
+
image: ReturnType<ZodBuilders["string"]>;
|
|
33
|
+
imageAlt: Zod.ZodString;
|
|
34
|
+
dateModified: Zod.ZodString;
|
|
35
|
+
era?: Zod.ZodOptional<Zod.ZodEnum<{
|
|
36
|
+
[x: string]: string;
|
|
37
|
+
}>> | undefined;
|
|
38
|
+
name: Zod.ZodString;
|
|
39
|
+
slug: Zod.ZodString;
|
|
40
|
+
aliases: Zod.ZodDefault<Zod.ZodArray<Zod.ZodString>>;
|
|
41
|
+
birthYear: Zod.ZodOptional<Zod.ZodNumber>;
|
|
42
|
+
deathYear: Zod.ZodOptional<Zod.ZodNumber>;
|
|
43
|
+
circa: Zod.ZodOptional<Zod.ZodBoolean>;
|
|
44
|
+
};
|
|
45
|
+
export type PersonIssue = FieldIssue;
|
|
46
|
+
/** No year 0 and birthYear <= deathYear, for the people superRefine (`ctx.addIssue` with `path: [path]`). */
|
|
47
|
+
export declare function personYearIssues(data: unknown): PersonIssue[];
|
|
48
|
+
/** The year checks, a non-blank `targetKeyword` and the `imageAlt` prefix, for factory scripts. Pure; never throws on malformed input. */
|
|
49
|
+
export declare function personFieldIssues(data: unknown): PersonIssue[];
|
|
50
|
+
/** An item that can link people: `people` holds person slugs. */
|
|
51
|
+
export interface PersonRefSource {
|
|
52
|
+
type: string;
|
|
53
|
+
slug: string;
|
|
54
|
+
people?: readonly string[];
|
|
55
|
+
}
|
|
56
|
+
/** Issues in an item's `people` array: not an array of strings, duplicates, and slugs no person has. */
|
|
57
|
+
export declare function personRefIssues(data: unknown, personSlugs: ReadonlySet<string> | readonly string[]): PersonIssue[];
|
|
58
|
+
/** The person's `primaryArticle`, when set, must be an existing article slug. */
|
|
59
|
+
export declare function primaryArticleIssues(person: unknown, articleSlugs: ReadonlySet<string> | readonly string[]): PersonIssue[];
|
|
60
|
+
export interface PersonBacklink {
|
|
61
|
+
type: string;
|
|
62
|
+
slug: string;
|
|
63
|
+
}
|
|
64
|
+
/** Person slug → the distinct items that link it, ordered by type then slug. Slugs not in `personSlugs` are skipped when given. */
|
|
65
|
+
export declare function buildPersonBacklinks(items: readonly PersonRefSource[], personSlugs?: ReadonlySet<string> | readonly string[]): Record<string, PersonBacklink[]>;
|
|
66
|
+
/** Inbound references to a person from other pages, not counting the person's own `primaryArticle` (type `articleTypes`). */
|
|
67
|
+
export declare function countInboundRefs(backlinks: Readonly<Record<string, readonly PersonBacklink[]>>, person: {
|
|
68
|
+
slug: string;
|
|
69
|
+
primaryArticle?: string;
|
|
70
|
+
}, articleTypes?: readonly string[]): number;
|
|
71
|
+
/**
|
|
72
|
+
* Display form of a person's life dates in the historians' count: `889–961`, `c. 889–961`, `b. 889`, `d. 961`, BCE
|
|
73
|
+
* as `4 BCE–65 CE`; undefined with neither year. The marks are replaceable for another language.
|
|
74
|
+
*/
|
|
75
|
+
export declare function formatLifeDates(data: {
|
|
76
|
+
birthYear?: number;
|
|
77
|
+
deathYear?: number;
|
|
78
|
+
circa?: boolean;
|
|
79
|
+
}, marks?: {
|
|
80
|
+
circa?: string;
|
|
81
|
+
born?: string;
|
|
82
|
+
died?: string;
|
|
83
|
+
}): string | undefined;
|
|
84
|
+
/**
|
|
85
|
+
* The years and age behind a "Lived 1138–1204 (about 66 years)" line. `kind` says which years exist; `years` is
|
|
86
|
+
* `formatYearRange` of them; `age` needs both years with death after birth and skips the missing year 0 across BCE/CE.
|
|
87
|
+
*/
|
|
88
|
+
export declare function lifeSpan(data: {
|
|
89
|
+
birthYear?: number;
|
|
90
|
+
deathYear?: number;
|
|
91
|
+
}): {
|
|
92
|
+
kind: 'range' | 'born' | 'died' | 'none';
|
|
93
|
+
years?: string;
|
|
94
|
+
age?: number;
|
|
95
|
+
};
|
|
96
|
+
export {};
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
import { formatYearRange } from "../eras/index.js";
|
|
2
|
+
import { asSet, isObject, yearPairIssues } from "../internal/guards.js";
|
|
3
|
+
import { DESCRIPTION_LENGTH, SEO_TITLE_LENGTH } from "../internal/seo.js";
|
|
4
|
+
export const PERSON_ROLES = [
|
|
5
|
+
'ruler', 'military', 'scholar', 'philosopher', 'poet', 'writer', 'architect', 'artist', 'saint', 'cleric',
|
|
6
|
+
'physician', 'patron',
|
|
7
|
+
];
|
|
8
|
+
export const PERSON_ALT_PREFIX = 'Illustration of ';
|
|
9
|
+
const WIKIDATA_URL = /^https:\/\/www\.wikidata\.org\/(wiki|entity)\/Q\d+$/;
|
|
10
|
+
const DATE = /^\d{4}-\d{2}-\d{2}/;
|
|
11
|
+
/**
|
|
12
|
+
* Fields of a `people` collection's `z.object({...})`. `z` is the site's own, as in `eraSchemaFields`. Apply
|
|
13
|
+
* `personYearIssues` in the collection's superRefine for the year order.
|
|
14
|
+
*/
|
|
15
|
+
export function peopleSchemaFields(z, options = {}) {
|
|
16
|
+
const roles = (options.roleValues ?? PERSON_ROLES);
|
|
17
|
+
if (!roles.length)
|
|
18
|
+
throw new Error('peopleSchemaFields: roleValues is empty');
|
|
19
|
+
const [descMin, descMax] = DESCRIPTION_LENGTH;
|
|
20
|
+
const [titleMin, titleMax] = SEO_TITLE_LENGTH;
|
|
21
|
+
return {
|
|
22
|
+
name: z.string().min(1),
|
|
23
|
+
slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
|
|
24
|
+
aliases: z.array(z.string()).default([]),
|
|
25
|
+
birthYear: z.number().int().optional(),
|
|
26
|
+
deathYear: z.number().int().optional(),
|
|
27
|
+
circa: z.boolean().optional(),
|
|
28
|
+
...(options.eraValues?.length ? { era: z.enum(options.eraValues).optional() } : {}),
|
|
29
|
+
roles: z.array(z.enum(roles)).min(1),
|
|
30
|
+
description: z.string().min(descMin).max(descMax),
|
|
31
|
+
targetKeyword: z.string().trim().min(1),
|
|
32
|
+
seoTitle: z.string().min(titleMin).max(titleMax),
|
|
33
|
+
bio: z.string().min(1),
|
|
34
|
+
primaryArticle: z.string().optional(),
|
|
35
|
+
sameAs: z.object({
|
|
36
|
+
wikidata: z.string().regex(WIKIDATA_URL),
|
|
37
|
+
wikipedia: z.string().url().optional(),
|
|
38
|
+
}),
|
|
39
|
+
image: (options.image ?? z.string()),
|
|
40
|
+
imageAlt: z.string().startsWith(PERSON_ALT_PREFIX),
|
|
41
|
+
dateModified: z.string().regex(DATE),
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
/** No year 0 and birthYear <= deathYear, for the people superRefine (`ctx.addIssue` with `path: [path]`). */
|
|
45
|
+
export function personYearIssues(data) {
|
|
46
|
+
return yearPairIssues(data, 'birthYear', 'deathYear');
|
|
47
|
+
}
|
|
48
|
+
/** The year checks, a non-blank `targetKeyword` and the `imageAlt` prefix, for factory scripts. Pure; never throws on malformed input. */
|
|
49
|
+
export function personFieldIssues(data) {
|
|
50
|
+
if (!isObject(data))
|
|
51
|
+
return [{ path: '', message: 'person: expected a JSON object' }];
|
|
52
|
+
const issues = personYearIssues(data);
|
|
53
|
+
if (typeof data.targetKeyword !== 'string' || !data.targetKeyword.trim()) {
|
|
54
|
+
issues.push({ path: 'targetKeyword', message: 'targetKeyword: required, a non-blank string' });
|
|
55
|
+
}
|
|
56
|
+
if (typeof data.imageAlt === 'string' && !data.imageAlt.startsWith(PERSON_ALT_PREFIX)) {
|
|
57
|
+
issues.push({ path: 'imageAlt', message: `imageAlt must start with "${PERSON_ALT_PREFIX.trim()}"` });
|
|
58
|
+
}
|
|
59
|
+
return issues;
|
|
60
|
+
}
|
|
61
|
+
/** Issues in an item's `people` array: not an array of strings, duplicates, and slugs no person has. */
|
|
62
|
+
export function personRefIssues(data, personSlugs) {
|
|
63
|
+
if (!isObject(data) || data.people === undefined)
|
|
64
|
+
return [];
|
|
65
|
+
if (!Array.isArray(data.people) || data.people.some((slug) => typeof slug !== 'string')) {
|
|
66
|
+
return [{ path: 'people', message: 'people: expected an array of person slugs' }];
|
|
67
|
+
}
|
|
68
|
+
const known = asSet(personSlugs);
|
|
69
|
+
const seen = new Set();
|
|
70
|
+
const issues = [];
|
|
71
|
+
for (const slug of data.people) {
|
|
72
|
+
if (seen.has(slug))
|
|
73
|
+
issues.push({ path: 'people', message: `people: duplicate slug "${slug}"` });
|
|
74
|
+
else if (!known.has(slug))
|
|
75
|
+
issues.push({ path: 'people', message: `people: unknown person "${slug}"` });
|
|
76
|
+
seen.add(slug);
|
|
77
|
+
}
|
|
78
|
+
return issues;
|
|
79
|
+
}
|
|
80
|
+
/** The person's `primaryArticle`, when set, must be an existing article slug. */
|
|
81
|
+
export function primaryArticleIssues(person, articleSlugs) {
|
|
82
|
+
if (!isObject(person) || person.primaryArticle === undefined)
|
|
83
|
+
return [];
|
|
84
|
+
const known = asSet(articleSlugs);
|
|
85
|
+
return typeof person.primaryArticle === 'string' && known.has(person.primaryArticle)
|
|
86
|
+
? []
|
|
87
|
+
: [{ path: 'primaryArticle', message: `primaryArticle: unknown article ${JSON.stringify(person.primaryArticle)}` }];
|
|
88
|
+
}
|
|
89
|
+
/** Person slug → the distinct items that link it, ordered by type then slug. Slugs not in `personSlugs` are skipped when given. */
|
|
90
|
+
export function buildPersonBacklinks(items, personSlugs) {
|
|
91
|
+
const known = personSlugs === undefined ? undefined : asSet(personSlugs);
|
|
92
|
+
const byPerson = new Map();
|
|
93
|
+
for (const item of items) {
|
|
94
|
+
for (const person of item.people ?? []) {
|
|
95
|
+
if (known && !known.has(person))
|
|
96
|
+
continue;
|
|
97
|
+
const links = byPerson.get(person) ?? new Map();
|
|
98
|
+
links.set(`${item.type}\u0000${item.slug}`, { type: item.type, slug: item.slug });
|
|
99
|
+
byPerson.set(person, links);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
const result = {};
|
|
103
|
+
for (const person of [...byPerson.keys()].sort()) {
|
|
104
|
+
result[person] = [...byPerson.get(person).values()].sort((a, b) => a.type.localeCompare(b.type) || a.slug.localeCompare(b.slug));
|
|
105
|
+
}
|
|
106
|
+
return result;
|
|
107
|
+
}
|
|
108
|
+
/** Inbound references to a person from other pages, not counting the person's own `primaryArticle` (type `articleTypes`). */
|
|
109
|
+
export function countInboundRefs(backlinks, person, articleTypes = ['articles', 'article']) {
|
|
110
|
+
return (backlinks[person.slug] ?? []).filter((link) => !(person.primaryArticle !== undefined && articleTypes.includes(link.type) && link.slug === person.primaryArticle)).length;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Display form of a person's life dates in the historians' count: `889–961`, `c. 889–961`, `b. 889`, `d. 961`, BCE
|
|
114
|
+
* as `4 BCE–65 CE`; undefined with neither year. The marks are replaceable for another language.
|
|
115
|
+
*/
|
|
116
|
+
export function formatLifeDates(data, marks = {}) {
|
|
117
|
+
const { kind, years } = lifeSpan(data);
|
|
118
|
+
const { circa: c = 'c.', born = 'b.', died = 'd.' } = marks;
|
|
119
|
+
const lead = data.circa ? `${c} ` : '';
|
|
120
|
+
if (kind === 'range')
|
|
121
|
+
return `${lead}${years}`;
|
|
122
|
+
if (kind === 'born')
|
|
123
|
+
return `${born} ${lead}${years}`;
|
|
124
|
+
if (kind === 'died')
|
|
125
|
+
return `${died} ${lead}${years}`;
|
|
126
|
+
return undefined;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* The years and age behind a "Lived 1138–1204 (about 66 years)" line. `kind` says which years exist; `years` is
|
|
130
|
+
* `formatYearRange` of them; `age` needs both years with death after birth and skips the missing year 0 across BCE/CE.
|
|
131
|
+
*/
|
|
132
|
+
export function lifeSpan(data) {
|
|
133
|
+
const { birthYear, deathYear } = data;
|
|
134
|
+
if (birthYear !== undefined && deathYear !== undefined) {
|
|
135
|
+
const age = deathYear > birthYear ? deathYear - birthYear - (birthYear < 0 && deathYear > 0 ? 1 : 0) : undefined;
|
|
136
|
+
return { kind: 'range', years: formatYearRange(birthYear, deathYear), age };
|
|
137
|
+
}
|
|
138
|
+
if (birthYear !== undefined)
|
|
139
|
+
return { kind: 'born', years: formatYearRange(birthYear) };
|
|
140
|
+
if (deathYear !== undefined)
|
|
141
|
+
return { kind: 'died', years: formatYearRange(deathYear) };
|
|
142
|
+
return { kind: 'none' };
|
|
143
|
+
}
|
package/dist/schema/index.d.ts
CHANGED
|
@@ -13,7 +13,7 @@ export { offer, placeNode, siteOrganizationNode, siteWebsiteNode } from './nodes
|
|
|
13
13
|
export type { OfferFields, SiteNodeFields, OrganizationLogo } from './nodes.ts';
|
|
14
14
|
export { buildBreadcrumbList, buildWebPageNode, assembleGraph, finalizeGraph } from './graph.ts';
|
|
15
15
|
export type { BreadcrumbInput, PageInput, AssembleOptions } from './graph.ts';
|
|
16
|
-
export { faqPageBuilder, articleBuilder, collectionPageBuilder, itemListBuilder, howToBuilder, aboutPageBuilder, contactPageBuilder, personBuilder, aggregateOfferBuilder, touristDestinationBuilder, organizationBuilder, } from './pages.ts';
|
|
16
|
+
export { faqPageBuilder, articleBuilder, collectionPageBuilder, itemListBuilder, howToBuilder, aboutPageBuilder, contactPageBuilder, personBuilder, historicalPersonSchema, aggregateOfferBuilder, touristDestinationBuilder, organizationBuilder, } from './pages.ts';
|
|
17
17
|
export type { ArticleOptions, CollectionPageOptions, ItemListOptions, AboutPageOptions, PersonOptions, AggregateOfferOptions, TouristDestinationFields, } from './pages.ts';
|
|
18
18
|
export { hotelBuilder, activityBuilder } from './places.ts';
|
|
19
19
|
export type { HotelOptions, ActivityOptions } from './places.ts';
|
package/dist/schema/index.js
CHANGED
|
@@ -6,6 +6,6 @@ export { openingHoursRows, openingHoursSummary, latestClosing } from "./hoursDis
|
|
|
6
6
|
export { renderSchemaPolicy } from "./policy.js";
|
|
7
7
|
export { offer, placeNode, siteOrganizationNode, siteWebsiteNode } from "./nodes.js";
|
|
8
8
|
export { buildBreadcrumbList, buildWebPageNode, assembleGraph, finalizeGraph } from "./graph.js";
|
|
9
|
-
export { faqPageBuilder, articleBuilder, collectionPageBuilder, itemListBuilder, howToBuilder, aboutPageBuilder, contactPageBuilder, personBuilder, aggregateOfferBuilder, touristDestinationBuilder, organizationBuilder, } from "./pages.js";
|
|
9
|
+
export { faqPageBuilder, articleBuilder, collectionPageBuilder, itemListBuilder, howToBuilder, aboutPageBuilder, contactPageBuilder, personBuilder, historicalPersonSchema, aggregateOfferBuilder, touristDestinationBuilder, organizationBuilder, } from "./pages.js";
|
|
10
10
|
export { hotelBuilder, activityBuilder } from "./places.js";
|
|
11
11
|
export { eventBuilder, eventItemListBuilder } from "./events.js";
|
package/dist/schema/pages.d.ts
CHANGED
|
@@ -44,6 +44,13 @@ export interface PersonOptions {
|
|
|
44
44
|
mainEntityOfPageOnOwnPage?: boolean;
|
|
45
45
|
}
|
|
46
46
|
export declare function personBuilder(options?: PersonOptions): SchemaBuilder;
|
|
47
|
+
/**
|
|
48
|
+
* A deceased historical figure's Person node (a `people` item: name, slug, aliases, birthYear, deathYear, sameAs,
|
|
49
|
+
* image). The `@id` is the person's canonical route, so every page that references the figure names one entity.
|
|
50
|
+
* Years become ISO year dates; `circa` has no schema.org form and is left to the page copy. No `jobTitle`, no
|
|
51
|
+
* `worksFor`: the author Person (`personBuilder`) is a different thing and is never reused here.
|
|
52
|
+
*/
|
|
53
|
+
export declare function historicalPersonSchema(): SchemaBuilder;
|
|
47
54
|
export interface AggregateOfferOptions {
|
|
48
55
|
currency?: string;
|
|
49
56
|
}
|
package/dist/schema/pages.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { toAbsoluteSiteUrl } from "../url/index.js";
|
|
2
|
+
import { formatTemporalCoverage } from "../eras/index.js";
|
|
2
3
|
import { createPersonSchema } from "./context.js";
|
|
3
4
|
/** FAQPage from `data.questions` (or `data.faq`), with question and answer through `ctx.plainText`. */
|
|
4
5
|
export function faqPageBuilder() {
|
|
@@ -184,6 +185,32 @@ export function personBuilder(options = {}) {
|
|
|
184
185
|
};
|
|
185
186
|
};
|
|
186
187
|
}
|
|
188
|
+
/**
|
|
189
|
+
* A deceased historical figure's Person node (a `people` item: name, slug, aliases, birthYear, deathYear, sameAs,
|
|
190
|
+
* image). The `@id` is the person's canonical route, so every page that references the figure names one entity.
|
|
191
|
+
* Years become ISO year dates; `circa` has no schema.org form and is left to the page copy. No `jobTitle`, no
|
|
192
|
+
* `worksFor`: the author Person (`personBuilder`) is a different thing and is never reused here.
|
|
193
|
+
*/
|
|
194
|
+
export function historicalPersonSchema() {
|
|
195
|
+
return (data, ctx) => {
|
|
196
|
+
const url = ctx.route('person', data.slug);
|
|
197
|
+
const sameAsUrls = [data.sameAs?.wikidata, data.sameAs?.wikipedia].filter((value) => typeof value === 'string' && value);
|
|
198
|
+
const image = typeof data.image === 'string' ? data.image : data.image?.src;
|
|
199
|
+
return {
|
|
200
|
+
'@type': 'Person',
|
|
201
|
+
'@id': `${url}#person`,
|
|
202
|
+
name: data.name,
|
|
203
|
+
alternateName: data.aliases?.length ? data.aliases : undefined,
|
|
204
|
+
description: data.description,
|
|
205
|
+
url,
|
|
206
|
+
image: image ? ctx.absOrHttp(image) : undefined,
|
|
207
|
+
birthDate: Number.isInteger(data.birthYear) ? formatTemporalCoverage(data.birthYear) : undefined,
|
|
208
|
+
deathDate: Number.isInteger(data.deathYear) ? formatTemporalCoverage(data.deathYear) : undefined,
|
|
209
|
+
sameAs: sameAsUrls.length ? sameAsUrls : undefined,
|
|
210
|
+
...(ctx.pageUrl.replace(/\/$/, '') === url ? { mainEntityOfPage: { '@id': ctx.pageUrl } } : {}),
|
|
211
|
+
};
|
|
212
|
+
};
|
|
213
|
+
}
|
|
187
214
|
export function aggregateOfferBuilder(options = {}) {
|
|
188
215
|
const { currency = 'EUR' } = options;
|
|
189
216
|
return (data, ctx) => ({
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sarimarcus/content-sites-core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.42.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",
|
|
@@ -82,6 +82,10 @@
|
|
|
82
82
|
"types": "./dist/eras/index.d.ts",
|
|
83
83
|
"default": "./dist/eras/index.js"
|
|
84
84
|
},
|
|
85
|
+
"./people": {
|
|
86
|
+
"types": "./dist/people/index.d.ts",
|
|
87
|
+
"default": "./dist/people/index.js"
|
|
88
|
+
},
|
|
85
89
|
"./images": {
|
|
86
90
|
"types": "./dist/images/index.d.ts",
|
|
87
91
|
"default": "./dist/images/index.js"
|
package/src/articles/formats.ts
CHANGED
|
@@ -2,6 +2,9 @@
|
|
|
2
2
|
// Catalogue: .claude/skills/article-craft/references/formats.md. An article without `editorialFormat` keeps the
|
|
3
3
|
// legacy shape (article-craft §1 / discover-mode.md). Pure: no Node APIs, it runs in the Astro build.
|
|
4
4
|
|
|
5
|
+
import { isObject } from '../internal/guards.ts';
|
|
6
|
+
import type { FieldIssue } from '../internal/issues.ts';
|
|
7
|
+
|
|
5
8
|
export type Range = readonly [number, number];
|
|
6
9
|
export type ArticleMode = 'evergreen' | 'discover';
|
|
7
10
|
|
|
@@ -23,10 +26,7 @@ export interface ArticleShape extends ShapeRanges {
|
|
|
23
26
|
words?: Range;
|
|
24
27
|
}
|
|
25
28
|
|
|
26
|
-
export
|
|
27
|
-
path: string;
|
|
28
|
-
message: string;
|
|
29
|
-
}
|
|
29
|
+
export type ShapeIssue = FieldIssue;
|
|
30
30
|
|
|
31
31
|
const DISCOVER = { sections: [3, 6], faqs: [0, 3], words: [700, 1600] } as const satisfies { sections: Range; faqs: Range; words: Range };
|
|
32
32
|
const EXPLAINER = { sections: [4, 6], faqs: [5, 9], words: [1500, 2100] } as const satisfies { sections: Range; faqs: Range; words: Range };
|
|
@@ -84,8 +84,6 @@ export const ARTICLE_SHAPE_UNION: ShapeRanges = {
|
|
|
84
84
|
};
|
|
85
85
|
|
|
86
86
|
const fmt = ([min, max]: Range): string => (min === max ? `${min}` : `${min}–${max}`);
|
|
87
|
-
const isObject = (value: unknown): value is Record<string, unknown> =>
|
|
88
|
-
value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
89
87
|
const isFormat = (value: unknown): value is ArticleFormat => typeof value === 'string' && Object.hasOwn(FORMATS, value);
|
|
90
88
|
const modeOf = (article: Record<string, unknown> | null | undefined): ArticleMode =>
|
|
91
89
|
article?.editorialMode === 'discover' ? 'discover' : 'evergreen';
|
package/src/config/precedence.ts
CHANGED
|
@@ -1,8 +1,6 @@
|
|
|
1
|
+
import { isObject } from '../internal/guards.ts';
|
|
1
2
|
import type { ConfigLayer, ConfigValue, SiteConfig } from '../types/index.ts';
|
|
2
3
|
|
|
3
|
-
const isRecord = (v: unknown): v is Record<string, ConfigValue | undefined> =>
|
|
4
|
-
typeof v === 'object' && v !== null && !Array.isArray(v);
|
|
5
|
-
|
|
6
4
|
/**
|
|
7
5
|
* `over` laid on `base`: a key `over` leaves undefined keeps the base value; an object merges key by key with the same
|
|
8
6
|
* rule; anything else (an array included) replaces the base value whole. Arrays never merge.
|
|
@@ -13,7 +11,7 @@ export function mergeConfig<T extends ConfigLayer>(base: T, over: ConfigLayer |
|
|
|
13
11
|
for (const [key, value] of Object.entries(over)) {
|
|
14
12
|
if (value === undefined) continue;
|
|
15
13
|
const prior = out[key];
|
|
16
|
-
out[key] =
|
|
14
|
+
out[key] = isObject(prior) && isObject(value) ? (mergeConfig(prior as ConfigLayer, value as ConfigLayer) as ConfigValue) : value;
|
|
17
15
|
}
|
|
18
16
|
return out as T;
|
|
19
17
|
}
|
package/src/eras/index.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
// Public surface of @sarimarcus/content-sites-core/eras: historical-era classification. The era list is per site
|
|
2
2
|
// data; this module holds the contract, the content-collection fields and the temporalCoverage format.
|
|
3
3
|
import type { z as Zod } from 'astro/zod';
|
|
4
|
+
import { isObject, yearPairIssues } from '../internal/guards.ts';
|
|
5
|
+
import type { FieldIssue } from '../internal/issues.ts';
|
|
4
6
|
|
|
5
7
|
/** One era of a site's chronology. Years are proleptic Gregorian integers, negative = BCE; `endYear` null = to present. */
|
|
6
8
|
export interface EraDefinition {
|
|
@@ -15,10 +17,7 @@ export interface EraDefinition {
|
|
|
15
17
|
dossiers?: { label: string; href: string }[];
|
|
16
18
|
}
|
|
17
19
|
|
|
18
|
-
export
|
|
19
|
-
path: string;
|
|
20
|
-
message: string;
|
|
21
|
-
}
|
|
20
|
+
export type EraIssue = FieldIssue;
|
|
22
21
|
|
|
23
22
|
export function eraHref(era: EraDefinition, basePath = '/chronology'): string {
|
|
24
23
|
return `${basePath}#${era.anchor}`;
|
|
@@ -44,21 +43,10 @@ export function eraSchemaFields(z: ZodBuilders, eraValues: readonly string[]) {
|
|
|
44
43
|
};
|
|
45
44
|
}
|
|
46
45
|
|
|
47
|
-
const isObject = (value: unknown): value is Record<string, unknown> =>
|
|
48
|
-
value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
49
46
|
|
|
50
47
|
/** No year 0 and the yearStart <= yearEnd order, for a site schema's superRefine (`ctx.addIssue` with `path: [path]`). */
|
|
51
48
|
export function eraYearIssues(data: unknown): EraIssue[] {
|
|
52
|
-
|
|
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;
|
|
49
|
+
return yearPairIssues(data, 'yearStart', 'yearEnd');
|
|
62
50
|
}
|
|
63
51
|
|
|
64
52
|
/** Every era-field issue for an item's data, for factory scripts. Pure; never throws on malformed input. */
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// Shared by core modules only: not exported from the package.
|
|
2
|
+
import type { FieldIssue } from './issues.ts';
|
|
3
|
+
|
|
4
|
+
export const isObject = (value: unknown): value is Record<string, unknown> =>
|
|
5
|
+
value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
6
|
+
|
|
7
|
+
export const asSet = <T>(values: ReadonlySet<T> | readonly T[]): ReadonlySet<T> =>
|
|
8
|
+
values instanceof Set ? values : new Set(values);
|
|
9
|
+
|
|
10
|
+
/** No year 0 and `startField <= endField`; the issue for the order sits on `endField`. */
|
|
11
|
+
export function yearPairIssues(data: unknown, startField: string, endField: string): FieldIssue[] {
|
|
12
|
+
if (!isObject(data)) return [];
|
|
13
|
+
const start = data[startField];
|
|
14
|
+
const end = data[endField];
|
|
15
|
+
const issues: FieldIssue[] = [];
|
|
16
|
+
for (const field of [startField, endField]) {
|
|
17
|
+
if (data[field] === 0) issues.push({ path: field, message: `${field}: there is no year 0 (use -1 for 1 BCE, 1 for 1 CE)` });
|
|
18
|
+
}
|
|
19
|
+
if (typeof start === 'number' && typeof end === 'number' && start > end) {
|
|
20
|
+
issues.push({ path: endField, message: `${endField} (${end}) is before ${startField} (${start})` });
|
|
21
|
+
}
|
|
22
|
+
return issues;
|
|
23
|
+
}
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
// Public surface of @sarimarcus/content-sites-core/people: the `people` content collection's fields and checks,
|
|
2
|
+
// the `people: [slug]` link field other collections carry, and the reverse index built from it. Pure and
|
|
3
|
+
// Node-loadable, so factory scripts and the site routes share one definition.
|
|
4
|
+
import type { z as Zod } from 'astro/zod';
|
|
5
|
+
import { formatYearRange } from '../eras/index.ts';
|
|
6
|
+
import { asSet, isObject, yearPairIssues } from '../internal/guards.ts';
|
|
7
|
+
import type { FieldIssue } from '../internal/issues.ts';
|
|
8
|
+
import { DESCRIPTION_LENGTH, SEO_TITLE_LENGTH } from '../internal/seo.ts';
|
|
9
|
+
|
|
10
|
+
/** The builders the fields use; `astro:content`'s `z` and `astro/zod` both satisfy it. */
|
|
11
|
+
type ZodBuilders = Pick<typeof Zod, 'enum' | 'number' | 'string' | 'array' | 'boolean' | 'object'>;
|
|
12
|
+
|
|
13
|
+
export const PERSON_ROLES = [
|
|
14
|
+
'ruler', 'military', 'scholar', 'philosopher', 'poet', 'writer', 'architect', 'artist', 'saint', 'cleric',
|
|
15
|
+
'physician', 'patron',
|
|
16
|
+
] as const;
|
|
17
|
+
|
|
18
|
+
export const PERSON_ALT_PREFIX = 'Illustration of ';
|
|
19
|
+
|
|
20
|
+
const WIKIDATA_URL = /^https:\/\/www\.wikidata\.org\/(wiki|entity)\/Q\d+$/;
|
|
21
|
+
const DATE = /^\d{4}-\d{2}-\d{2}/;
|
|
22
|
+
|
|
23
|
+
export interface PeopleSchemaOptions {
|
|
24
|
+
/** The site's era ids (the `eras` module); omit to leave `era` out of the schema. */
|
|
25
|
+
eraValues?: readonly string[];
|
|
26
|
+
/** Defaults to `PERSON_ROLES`. */
|
|
27
|
+
roleValues?: readonly string[];
|
|
28
|
+
/** The site's image field schema (`image()` from `astro:content` for an asset import); defaults to a string path. */
|
|
29
|
+
image?: unknown;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Fields of a `people` collection's `z.object({...})`. `z` is the site's own, as in `eraSchemaFields`. Apply
|
|
34
|
+
* `personYearIssues` in the collection's superRefine for the year order.
|
|
35
|
+
*/
|
|
36
|
+
export function peopleSchemaFields(z: ZodBuilders, options: PeopleSchemaOptions = {}) {
|
|
37
|
+
const roles = (options.roleValues ?? PERSON_ROLES) as readonly string[];
|
|
38
|
+
if (!roles.length) throw new Error('peopleSchemaFields: roleValues is empty');
|
|
39
|
+
const [descMin, descMax] = DESCRIPTION_LENGTH;
|
|
40
|
+
const [titleMin, titleMax] = SEO_TITLE_LENGTH;
|
|
41
|
+
return {
|
|
42
|
+
name: z.string().min(1),
|
|
43
|
+
slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
|
|
44
|
+
aliases: z.array(z.string()).default([]),
|
|
45
|
+
birthYear: z.number().int().optional(),
|
|
46
|
+
deathYear: z.number().int().optional(),
|
|
47
|
+
circa: z.boolean().optional(),
|
|
48
|
+
...(options.eraValues?.length ? { era: z.enum(options.eraValues as [string, ...string[]]).optional() } : {}),
|
|
49
|
+
roles: z.array(z.enum(roles as [string, ...string[]])).min(1),
|
|
50
|
+
description: z.string().min(descMin).max(descMax),
|
|
51
|
+
targetKeyword: z.string().trim().min(1),
|
|
52
|
+
seoTitle: z.string().min(titleMin).max(titleMax),
|
|
53
|
+
bio: z.string().min(1),
|
|
54
|
+
primaryArticle: z.string().optional(),
|
|
55
|
+
sameAs: z.object({
|
|
56
|
+
wikidata: z.string().regex(WIKIDATA_URL),
|
|
57
|
+
wikipedia: z.string().url().optional(),
|
|
58
|
+
}),
|
|
59
|
+
image: (options.image ?? z.string()) as ReturnType<ZodBuilders['string']>,
|
|
60
|
+
imageAlt: z.string().startsWith(PERSON_ALT_PREFIX),
|
|
61
|
+
dateModified: z.string().regex(DATE),
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export type PersonIssue = FieldIssue;
|
|
66
|
+
|
|
67
|
+
/** No year 0 and birthYear <= deathYear, for the people superRefine (`ctx.addIssue` with `path: [path]`). */
|
|
68
|
+
export function personYearIssues(data: unknown): PersonIssue[] {
|
|
69
|
+
return yearPairIssues(data, 'birthYear', 'deathYear');
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** The year checks, a non-blank `targetKeyword` and the `imageAlt` prefix, for factory scripts. Pure; never throws on malformed input. */
|
|
73
|
+
export function personFieldIssues(data: unknown): PersonIssue[] {
|
|
74
|
+
if (!isObject(data)) return [{ path: '', message: 'person: expected a JSON object' }];
|
|
75
|
+
const issues = personYearIssues(data);
|
|
76
|
+
if (typeof data.targetKeyword !== 'string' || !data.targetKeyword.trim()) {
|
|
77
|
+
issues.push({ path: 'targetKeyword', message: 'targetKeyword: required, a non-blank string' });
|
|
78
|
+
}
|
|
79
|
+
if (typeof data.imageAlt === 'string' && !data.imageAlt.startsWith(PERSON_ALT_PREFIX)) {
|
|
80
|
+
issues.push({ path: 'imageAlt', message: `imageAlt must start with "${PERSON_ALT_PREFIX.trim()}"` });
|
|
81
|
+
}
|
|
82
|
+
return issues;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** An item that can link people: `people` holds person slugs. */
|
|
86
|
+
export interface PersonRefSource {
|
|
87
|
+
type: string;
|
|
88
|
+
slug: string;
|
|
89
|
+
people?: readonly string[];
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** Issues in an item's `people` array: not an array of strings, duplicates, and slugs no person has. */
|
|
93
|
+
export function personRefIssues(data: unknown, personSlugs: ReadonlySet<string> | readonly string[]): PersonIssue[] {
|
|
94
|
+
if (!isObject(data) || data.people === undefined) return [];
|
|
95
|
+
if (!Array.isArray(data.people) || data.people.some((slug) => typeof slug !== 'string')) {
|
|
96
|
+
return [{ path: 'people', message: 'people: expected an array of person slugs' }];
|
|
97
|
+
}
|
|
98
|
+
const known = asSet(personSlugs);
|
|
99
|
+
const seen = new Set<string>();
|
|
100
|
+
const issues: PersonIssue[] = [];
|
|
101
|
+
for (const slug of data.people as string[]) {
|
|
102
|
+
if (seen.has(slug)) issues.push({ path: 'people', message: `people: duplicate slug "${slug}"` });
|
|
103
|
+
else if (!known.has(slug)) issues.push({ path: 'people', message: `people: unknown person "${slug}"` });
|
|
104
|
+
seen.add(slug);
|
|
105
|
+
}
|
|
106
|
+
return issues;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** The person's `primaryArticle`, when set, must be an existing article slug. */
|
|
110
|
+
export function primaryArticleIssues(person: unknown, articleSlugs: ReadonlySet<string> | readonly string[]): PersonIssue[] {
|
|
111
|
+
if (!isObject(person) || person.primaryArticle === undefined) return [];
|
|
112
|
+
const known = asSet(articleSlugs);
|
|
113
|
+
return typeof person.primaryArticle === 'string' && known.has(person.primaryArticle)
|
|
114
|
+
? []
|
|
115
|
+
: [{ path: 'primaryArticle', message: `primaryArticle: unknown article ${JSON.stringify(person.primaryArticle)}` }];
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
export interface PersonBacklink {
|
|
119
|
+
type: string;
|
|
120
|
+
slug: string;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** Person slug → the distinct items that link it, ordered by type then slug. Slugs not in `personSlugs` are skipped when given. */
|
|
124
|
+
export function buildPersonBacklinks(
|
|
125
|
+
items: readonly PersonRefSource[],
|
|
126
|
+
personSlugs?: ReadonlySet<string> | readonly string[],
|
|
127
|
+
): Record<string, PersonBacklink[]> {
|
|
128
|
+
const known = personSlugs === undefined ? undefined : asSet(personSlugs);
|
|
129
|
+
const byPerson = new Map<string, Map<string, PersonBacklink>>();
|
|
130
|
+
for (const item of items) {
|
|
131
|
+
for (const person of item.people ?? []) {
|
|
132
|
+
if (known && !known.has(person)) continue;
|
|
133
|
+
const links = byPerson.get(person) ?? new Map<string, PersonBacklink>();
|
|
134
|
+
links.set(`${item.type}\u0000${item.slug}`, { type: item.type, slug: item.slug });
|
|
135
|
+
byPerson.set(person, links);
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
const result: Record<string, PersonBacklink[]> = {};
|
|
139
|
+
for (const person of [...byPerson.keys()].sort()) {
|
|
140
|
+
result[person] = [...byPerson.get(person)!.values()].sort((a, b) => a.type.localeCompare(b.type) || a.slug.localeCompare(b.slug));
|
|
141
|
+
}
|
|
142
|
+
return result;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** Inbound references to a person from other pages, not counting the person's own `primaryArticle` (type `articleTypes`). */
|
|
146
|
+
export function countInboundRefs(
|
|
147
|
+
backlinks: Readonly<Record<string, readonly PersonBacklink[]>>,
|
|
148
|
+
person: { slug: string; primaryArticle?: string },
|
|
149
|
+
articleTypes: readonly string[] = ['articles', 'article'],
|
|
150
|
+
): number {
|
|
151
|
+
return (backlinks[person.slug] ?? []).filter(
|
|
152
|
+
(link) => !(person.primaryArticle !== undefined && articleTypes.includes(link.type) && link.slug === person.primaryArticle),
|
|
153
|
+
).length;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* Display form of a person's life dates in the historians' count: `889–961`, `c. 889–961`, `b. 889`, `d. 961`, BCE
|
|
158
|
+
* as `4 BCE–65 CE`; undefined with neither year. The marks are replaceable for another language.
|
|
159
|
+
*/
|
|
160
|
+
export function formatLifeDates(
|
|
161
|
+
data: { birthYear?: number; deathYear?: number; circa?: boolean },
|
|
162
|
+
marks: { circa?: string; born?: string; died?: string } = {},
|
|
163
|
+
): string | undefined {
|
|
164
|
+
const { kind, years } = lifeSpan(data);
|
|
165
|
+
const { circa: c = 'c.', born = 'b.', died = 'd.' } = marks;
|
|
166
|
+
const lead = data.circa ? `${c} ` : '';
|
|
167
|
+
if (kind === 'range') return `${lead}${years}`;
|
|
168
|
+
if (kind === 'born') return `${born} ${lead}${years}`;
|
|
169
|
+
if (kind === 'died') return `${died} ${lead}${years}`;
|
|
170
|
+
return undefined;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* The years and age behind a "Lived 1138–1204 (about 66 years)" line. `kind` says which years exist; `years` is
|
|
175
|
+
* `formatYearRange` of them; `age` needs both years with death after birth and skips the missing year 0 across BCE/CE.
|
|
176
|
+
*/
|
|
177
|
+
export function lifeSpan(data: { birthYear?: number; deathYear?: number }): {
|
|
178
|
+
kind: 'range' | 'born' | 'died' | 'none';
|
|
179
|
+
years?: string;
|
|
180
|
+
age?: number;
|
|
181
|
+
} {
|
|
182
|
+
const { birthYear, deathYear } = data;
|
|
183
|
+
if (birthYear !== undefined && deathYear !== undefined) {
|
|
184
|
+
const age = deathYear > birthYear ? deathYear - birthYear - (birthYear < 0 && deathYear > 0 ? 1 : 0) : undefined;
|
|
185
|
+
return { kind: 'range', years: formatYearRange(birthYear, deathYear), age };
|
|
186
|
+
}
|
|
187
|
+
if (birthYear !== undefined) return { kind: 'born', years: formatYearRange(birthYear) };
|
|
188
|
+
if (deathYear !== undefined) return { kind: 'died', years: formatYearRange(deathYear) };
|
|
189
|
+
return { kind: 'none' };
|
|
190
|
+
}
|
package/src/schema/index.ts
CHANGED
|
@@ -28,7 +28,7 @@ export { buildBreadcrumbList, buildWebPageNode, assembleGraph, finalizeGraph } f
|
|
|
28
28
|
export type { BreadcrumbInput, PageInput, AssembleOptions } from './graph.ts';
|
|
29
29
|
export {
|
|
30
30
|
faqPageBuilder, articleBuilder, collectionPageBuilder, itemListBuilder, howToBuilder, aboutPageBuilder,
|
|
31
|
-
contactPageBuilder, personBuilder, aggregateOfferBuilder, touristDestinationBuilder, organizationBuilder,
|
|
31
|
+
contactPageBuilder, personBuilder, historicalPersonSchema, aggregateOfferBuilder, touristDestinationBuilder, organizationBuilder,
|
|
32
32
|
} from './pages.ts';
|
|
33
33
|
export type {
|
|
34
34
|
ArticleOptions, CollectionPageOptions, ItemListOptions, AboutPageOptions, PersonOptions, AggregateOfferOptions,
|
package/src/schema/pages.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { toAbsoluteSiteUrl } from '../url/index.ts';
|
|
2
|
+
import { formatTemporalCoverage } from '../eras/index.ts';
|
|
2
3
|
import { createPersonSchema } from './context.ts';
|
|
3
4
|
import type { JsonLdNode, SchemaBuilder } from './types.ts';
|
|
4
5
|
|
|
@@ -236,6 +237,33 @@ export function personBuilder(options: PersonOptions = {}): SchemaBuilder {
|
|
|
236
237
|
};
|
|
237
238
|
}
|
|
238
239
|
|
|
240
|
+
/**
|
|
241
|
+
* A deceased historical figure's Person node (a `people` item: name, slug, aliases, birthYear, deathYear, sameAs,
|
|
242
|
+
* image). The `@id` is the person's canonical route, so every page that references the figure names one entity.
|
|
243
|
+
* Years become ISO year dates; `circa` has no schema.org form and is left to the page copy. No `jobTitle`, no
|
|
244
|
+
* `worksFor`: the author Person (`personBuilder`) is a different thing and is never reused here.
|
|
245
|
+
*/
|
|
246
|
+
export function historicalPersonSchema(): SchemaBuilder {
|
|
247
|
+
return (data, ctx) => {
|
|
248
|
+
const url = ctx.route('person', data.slug);
|
|
249
|
+
const sameAsUrls = [data.sameAs?.wikidata, data.sameAs?.wikipedia].filter((value: unknown) => typeof value === 'string' && value);
|
|
250
|
+
const image = typeof data.image === 'string' ? data.image : data.image?.src;
|
|
251
|
+
return {
|
|
252
|
+
'@type': 'Person',
|
|
253
|
+
'@id': `${url}#person`,
|
|
254
|
+
name: data.name,
|
|
255
|
+
alternateName: data.aliases?.length ? data.aliases : undefined,
|
|
256
|
+
description: data.description,
|
|
257
|
+
url,
|
|
258
|
+
image: image ? ctx.absOrHttp(image) : undefined,
|
|
259
|
+
birthDate: Number.isInteger(data.birthYear) ? formatTemporalCoverage(data.birthYear) : undefined,
|
|
260
|
+
deathDate: Number.isInteger(data.deathYear) ? formatTemporalCoverage(data.deathYear) : undefined,
|
|
261
|
+
sameAs: sameAsUrls.length ? sameAsUrls : undefined,
|
|
262
|
+
...(ctx.pageUrl.replace(/\/$/, '') === url ? { mainEntityOfPage: { '@id': ctx.pageUrl } } : {}),
|
|
263
|
+
};
|
|
264
|
+
};
|
|
265
|
+
}
|
|
266
|
+
|
|
239
267
|
export interface AggregateOfferOptions {
|
|
240
268
|
currency?: string;
|
|
241
269
|
}
|