@sarimarcus/content-sites-core 0.50.0 → 0.51.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 CHANGED
@@ -2,6 +2,10 @@
2
2
 
3
3
  All packages in the platform release in lockstep; entries are per release version.
4
4
 
5
+ ## 0.51.0 (2026-10-27)
6
+
7
+ - `people`: `createPeople`, `roleLabel`, `PersonLink`; `eras`: `dossiersFromHubs`; `text`: `pagedTopicMeta`, `pagedEraMeta` (SLA-3333).
8
+
5
9
  ## 0.50.0 (2026-10-27)
6
10
 
7
11
  - No changes; lockstep release with ui (SLA-3535).
@@ -46,4 +46,12 @@ export declare function formatYearRange(yearStart?: number, yearEnd?: number): s
46
46
  export declare function formatTemporalCoverage(yearStart: number, yearEnd?: number | null): string;
47
47
  /** The item's temporalCoverage, or undefined without an integer `yearStart`. */
48
48
  export declare function temporalCoverageOf(data: unknown): string | undefined;
49
+ /** An era's `dossiers` list from a site's hub map: each key's `{label: hub.title, href: hub.href}`; throws on an unknown key. */
50
+ export declare function dossiersFromHubs(hubs: Readonly<Partial<Record<string, {
51
+ title: string;
52
+ href: string;
53
+ }>>>, ...keys: string[]): {
54
+ label: string;
55
+ href: string;
56
+ }[];
49
57
  export {};
@@ -66,3 +66,12 @@ export function temporalCoverageOf(data) {
66
66
  const end = data.yearEnd === null ? null : Number.isInteger(data.yearEnd) ? data.yearEnd : undefined;
67
67
  return formatTemporalCoverage(data.yearStart, end);
68
68
  }
69
+ /** An era's `dossiers` list from a site's hub map: each key's `{label: hub.title, href: hub.href}`; throws on an unknown key. */
70
+ export function dossiersFromHubs(hubs, ...keys) {
71
+ return keys.map((key) => {
72
+ const hub = hubs[key];
73
+ if (!hub)
74
+ throw new Error(`dossiersFromHubs: unknown dossier hub "${key}"`);
75
+ return { label: hub.title, href: hub.href };
76
+ });
77
+ }
@@ -96,4 +96,32 @@ export declare function lifeSpan(data: {
96
96
  years?: string;
97
97
  age?: number;
98
98
  };
99
+ export interface PersonLink {
100
+ slug: string;
101
+ name: string;
102
+ href: string;
103
+ dates?: string;
104
+ }
105
+ export declare const roleLabel: (role: string) => string;
106
+ type PersonData = {
107
+ slug: string;
108
+ name: string;
109
+ birthYear?: number;
110
+ deathYear?: number;
111
+ circa?: boolean;
112
+ };
113
+ /**
114
+ * The people helpers a site binds to its own data: `load` returns every person's data (called once, cached),
115
+ * `url` is the site's base-path url builder, `portraits` maps a person slug to its image asset.
116
+ */
117
+ export declare function createPeople<P extends PersonData, I = unknown>(options: {
118
+ load: () => Promise<readonly P[]>;
119
+ url: (path: string) => string;
120
+ portraits?: Readonly<Record<string, I>>;
121
+ }): {
122
+ toPersonLink: (person: PersonData) => PersonLink;
123
+ resolvePeople: (slugs: readonly string[] | undefined) => Promise<PersonLink[]>;
124
+ personPortrait: (slug: string) => I | undefined;
125
+ personHref: (slug: string) => string;
126
+ };
99
127
  export {};
@@ -1,5 +1,6 @@
1
1
  import { formatYearRange } from "../eras/index.js";
2
2
  import { asSet, isObject, yearPairIssues } from "../internal/guards.js";
3
+ import { routeSegment } from "../url/routes.js";
3
4
  import { DESCRIPTION_LENGTH, SEO_TITLE_LENGTH } from "../internal/seo.js";
4
5
  export const PERSON_ROLES = [
5
6
  'ruler', 'military', 'scholar', 'philosopher', 'poet', 'writer', 'architect', 'artist', 'saint', 'cleric',
@@ -144,3 +145,31 @@ export function lifeSpan(data) {
144
145
  return { kind: 'died', years: formatYearRange(deathYear) };
145
146
  return { kind: 'none' };
146
147
  }
148
+ export const roleLabel = (role) => role.charAt(0).toUpperCase() + role.slice(1);
149
+ /**
150
+ * The people helpers a site binds to its own data: `load` returns every person's data (called once, cached),
151
+ * `url` is the site's base-path url builder, `portraits` maps a person slug to its image asset.
152
+ */
153
+ export function createPeople(options) {
154
+ const { load, url, portraits = {} } = options;
155
+ const personHref = (slug) => url(`/${routeSegment('person')}/${slug}`);
156
+ const toPersonLink = (person) => ({
157
+ slug: person.slug,
158
+ name: person.name,
159
+ href: personHref(person.slug),
160
+ dates: formatLifeDates(person),
161
+ });
162
+ let bySlug;
163
+ const loadPeople = () => (bySlug ??= load().then((all) => new Map(all.map((p) => [p.slug, p]))));
164
+ async function resolvePeople(slugs) {
165
+ if (!slugs?.length)
166
+ return [];
167
+ const map = await loadPeople();
168
+ return slugs.flatMap((slug) => {
169
+ const person = map.get(slug);
170
+ return person ? [toPersonLink(person)] : [];
171
+ });
172
+ }
173
+ const personPortrait = (slug) => portraits[slug];
174
+ return { toPersonLink, resolvePeople, personPortrait, personHref };
175
+ }
@@ -6,3 +6,5 @@ export { parseMarkdown, parseMarkdownInline, parseMarkdownBlock, stripMarkdown }
6
6
  export { formatFromPrice } from './cardCopy.ts';
7
7
  export { splitBodySections, bodyExtrasHtml } from './bodySections.ts';
8
8
  export type { BodySection, BodyContent, SplitBodyOptions } from './bodySections.ts';
9
+ export { pagedTopicMeta, pagedEraMeta } from './pagedListingMeta.ts';
10
+ export type { PagedMeta } from './pagedListingMeta.ts';
@@ -6,3 +6,4 @@ export { readingTime } from "./readingTime.js";
6
6
  export { parseMarkdown, parseMarkdownInline, parseMarkdownBlock, stripMarkdown } from "./markdown.js";
7
7
  export { formatFromPrice } from "./cardCopy.js";
8
8
  export { splitBodySections, bodyExtrasHtml } from "./bodySections.js";
9
+ export { pagedTopicMeta, pagedEraMeta } from "./pagedListingMeta.js";
@@ -0,0 +1,25 @@
1
+ interface PagedBase {
2
+ /** Place name woven into titles and descriptions, e.g. "Granada". */
3
+ city: string;
4
+ /** Title tail brand; defaults to `Explore ${city}`. */
5
+ brand?: string;
6
+ page: number;
7
+ total: number;
8
+ }
9
+ export interface PagedMeta {
10
+ title: string;
11
+ description: string;
12
+ }
13
+ /**
14
+ * Title (50-60) and description (150-160) for page 2+ of an articles listing; `label` null = the main
15
+ * /articles listing. Labels run from 7 to 24 characters, so no one template fits; the first candidate in range wins.
16
+ */
17
+ export declare function pagedTopicMeta(label: string | null, options: PagedBase): PagedMeta;
18
+ /**
19
+ * The era-listing variant, page 2+. A label that already names `city` ("Nasrid Granada") is not framed
20
+ * "in/under <city>" again; `labelNamesCity` is required: the caller decides, so a site's output never shifts on a label rename.
21
+ */
22
+ export declare function pagedEraMeta(label: string, options: PagedBase & {
23
+ labelNamesCity: boolean;
24
+ }): PagedMeta;
25
+ export {};
@@ -0,0 +1,44 @@
1
+ import { fitLength } from "./fitLength.js";
2
+ function finish(heads, base, noun, { city, brand, page, total }) {
3
+ const pg = `page ${page} of ${total}`;
4
+ const titles = [];
5
+ for (const head of heads) {
6
+ for (const tail of [` | ${brand ?? `Explore ${city}`}`, ` | ${city} guide`, ''])
7
+ titles.push(`${head}, ${pg}${tail}`);
8
+ }
9
+ const extras = [' Each piece is written by a resident correspondent.', ' Every article cites its sources.', ' Practical context included.', ` Browse other ${noun} anytime.`, ` Browse by ${noun === 'topics' ? 'topic' : 'era'}.`];
10
+ const descriptions = [];
11
+ for (let mask = (1 << extras.length) - 1; mask >= 0; mask--) {
12
+ const picked = extras.filter((_, i) => mask & (1 << i));
13
+ if (picked.filter((e) => e.startsWith(' Browse')).length > 1)
14
+ continue;
15
+ descriptions.push(base + picked.join(''));
16
+ }
17
+ return { title: fitLength(titles, 50, 60), description: fitLength(descriptions, 150, 160) };
18
+ }
19
+ /**
20
+ * Title (50-60) and description (150-160) for page 2+ of an articles listing; `label` null = the main
21
+ * /articles listing. Labels run from 7 to 24 characters, so no one template fits; the first candidate in range wins.
22
+ */
23
+ export function pagedTopicMeta(label, options) {
24
+ const { city, page, total } = options;
25
+ const noun = label ? `${label} articles` : 'Articles';
26
+ const lowerNoun = label ? `${label.toLowerCase()} articles` : 'articles';
27
+ const heads = [`${noun} from ${city}`, `More ${lowerNoun} from ${city}`, `${label ?? 'Stories'}: ${city} articles`, `${noun} in ${city}`];
28
+ return finish(heads, `Page ${page} of ${total} of our ${lowerNoun} on ${city}, newest first.`, 'topics', options);
29
+ }
30
+ /**
31
+ * The era-listing variant, page 2+. A label that already names `city` ("Nasrid Granada") is not framed
32
+ * "in/under <city>" again; `labelNamesCity` is required: the caller decides, so a site's output never shifts on a label rename.
33
+ */
34
+ export function pagedEraMeta(label, options) {
35
+ const { city, page, total } = options;
36
+ const named = options.labelNamesCity;
37
+ const heads = named
38
+ ? [`${label}: more articles`, `${label}: articles`, `${label} articles`]
39
+ : [`${label}: ${city} articles`, `${label} in ${city}: more articles`, `${city} under ${label}: articles`, `${label} articles`];
40
+ const base = named
41
+ ? `Page ${page} of ${total} of our articles on ${label}, newest first.`
42
+ : `Page ${page} of ${total} of our articles on ${city} in the ${label} period, newest first.`;
43
+ return finish(heads, base, 'eras', options);
44
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sarimarcus/content-sites-core",
3
- "version": "0.50.0",
3
+ "version": "0.51.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",
package/src/eras/index.ts CHANGED
@@ -96,3 +96,15 @@ export function temporalCoverageOf(data: unknown): string | undefined {
96
96
  const end = data.yearEnd === null ? null : Number.isInteger(data.yearEnd) ? (data.yearEnd as number) : undefined;
97
97
  return formatTemporalCoverage(data.yearStart as number, end);
98
98
  }
99
+
100
+ /** An era's `dossiers` list from a site's hub map: each key's `{label: hub.title, href: hub.href}`; throws on an unknown key. */
101
+ export function dossiersFromHubs(
102
+ hubs: Readonly<Partial<Record<string, { title: string; href: string }>>>,
103
+ ...keys: string[]
104
+ ): { label: string; href: string }[] {
105
+ return keys.map((key) => {
106
+ const hub = hubs[key];
107
+ if (!hub) throw new Error(`dossiersFromHubs: unknown dossier hub "${key}"`);
108
+ return { label: hub.title, href: hub.href };
109
+ });
110
+ }
@@ -5,6 +5,7 @@ import type { z as Zod } from 'astro/zod';
5
5
  import { formatYearRange } from '../eras/index.ts';
6
6
  import { asSet, isObject, yearPairIssues } from '../internal/guards.ts';
7
7
  import type { FieldIssue } from '../internal/issues.ts';
8
+ import { routeSegment } from '../url/routes.ts';
8
9
  import { DESCRIPTION_LENGTH, SEO_TITLE_LENGTH } from '../internal/seo.ts';
9
10
 
10
11
  /** The builders the fields use; `astro:content`'s `z` and `astro/zod` both satisfy it. */
@@ -192,3 +193,45 @@ export function lifeSpan(data: { birthYear?: number; deathYear?: number }): {
192
193
  if (deathYear !== undefined) return { kind: 'died', years: formatYearRange(deathYear) };
193
194
  return { kind: 'none' };
194
195
  }
196
+
197
+ export interface PersonLink {
198
+ slug: string;
199
+ name: string;
200
+ href: string;
201
+ dates?: string;
202
+ }
203
+
204
+ export const roleLabel = (role: string): string => role.charAt(0).toUpperCase() + role.slice(1);
205
+
206
+ type PersonData = { slug: string; name: string; birthYear?: number; deathYear?: number; circa?: boolean };
207
+
208
+ /**
209
+ * The people helpers a site binds to its own data: `load` returns every person's data (called once, cached),
210
+ * `url` is the site's base-path url builder, `portraits` maps a person slug to its image asset.
211
+ */
212
+ export function createPeople<P extends PersonData, I = unknown>(options: {
213
+ load: () => Promise<readonly P[]>;
214
+ url: (path: string) => string;
215
+ portraits?: Readonly<Record<string, I>>;
216
+ }) {
217
+ const { load, url, portraits = {} } = options;
218
+ const personHref = (slug: string): string => url(`/${routeSegment('person')}/${slug}`);
219
+ const toPersonLink = (person: PersonData): PersonLink => ({
220
+ slug: person.slug,
221
+ name: person.name,
222
+ href: personHref(person.slug),
223
+ dates: formatLifeDates(person),
224
+ });
225
+ let bySlug: Promise<Map<string, P>> | undefined;
226
+ const loadPeople = () => (bySlug ??= load().then((all) => new Map(all.map((p) => [p.slug, p]))));
227
+ async function resolvePeople(slugs: readonly string[] | undefined): Promise<PersonLink[]> {
228
+ if (!slugs?.length) return [];
229
+ const map = await loadPeople();
230
+ return slugs.flatMap((slug) => {
231
+ const person = map.get(slug);
232
+ return person ? [toPersonLink(person)] : [];
233
+ });
234
+ }
235
+ const personPortrait = (slug: string): I | undefined => (portraits as Record<string, I>)[slug];
236
+ return { toPersonLink, resolvePeople, personPortrait, personHref };
237
+ }
package/src/text/index.ts CHANGED
@@ -7,3 +7,5 @@ export { parseMarkdown, parseMarkdownInline, parseMarkdownBlock, stripMarkdown }
7
7
  export { formatFromPrice } from './cardCopy.ts';
8
8
  export { splitBodySections, bodyExtrasHtml } from './bodySections.ts';
9
9
  export type { BodySection, BodyContent, SplitBodyOptions } from './bodySections.ts';
10
+ export { pagedTopicMeta, pagedEraMeta } from './pagedListingMeta.ts';
11
+ export type { PagedMeta } from './pagedListingMeta.ts';
@@ -0,0 +1,59 @@
1
+ import { fitLength } from './fitLength.ts';
2
+
3
+ interface PagedBase {
4
+ /** Place name woven into titles and descriptions, e.g. "Granada". */
5
+ city: string;
6
+ /** Title tail brand; defaults to `Explore ${city}`. */
7
+ brand?: string;
8
+ page: number;
9
+ total: number;
10
+ }
11
+
12
+ export interface PagedMeta {
13
+ title: string;
14
+ description: string;
15
+ }
16
+
17
+ function finish(heads: string[], base: string, noun: 'topics' | 'eras', { city, brand, page, total }: PagedBase): PagedMeta {
18
+ const pg = `page ${page} of ${total}`;
19
+ const titles: string[] = [];
20
+ for (const head of heads) {
21
+ for (const tail of [` | ${brand ?? `Explore ${city}`}`, ` | ${city} guide`, '']) titles.push(`${head}, ${pg}${tail}`);
22
+ }
23
+ const extras = [' Each piece is written by a resident correspondent.', ' Every article cites its sources.', ' Practical context included.', ` Browse other ${noun} anytime.`, ` Browse by ${noun === 'topics' ? 'topic' : 'era'}.`];
24
+ const descriptions: string[] = [];
25
+ for (let mask = (1 << extras.length) - 1; mask >= 0; mask--) {
26
+ const picked = extras.filter((_, i) => mask & (1 << i));
27
+ if (picked.filter((e) => e.startsWith(' Browse')).length > 1) continue;
28
+ descriptions.push(base + picked.join(''));
29
+ }
30
+ return { title: fitLength(titles, 50, 60), description: fitLength(descriptions, 150, 160) };
31
+ }
32
+
33
+ /**
34
+ * Title (50-60) and description (150-160) for page 2+ of an articles listing; `label` null = the main
35
+ * /articles listing. Labels run from 7 to 24 characters, so no one template fits; the first candidate in range wins.
36
+ */
37
+ export function pagedTopicMeta(label: string | null, options: PagedBase): PagedMeta {
38
+ const { city, page, total } = options;
39
+ const noun = label ? `${label} articles` : 'Articles';
40
+ const lowerNoun = label ? `${label.toLowerCase()} articles` : 'articles';
41
+ const heads = [`${noun} from ${city}`, `More ${lowerNoun} from ${city}`, `${label ?? 'Stories'}: ${city} articles`, `${noun} in ${city}`];
42
+ return finish(heads, `Page ${page} of ${total} of our ${lowerNoun} on ${city}, newest first.`, 'topics', options);
43
+ }
44
+
45
+ /**
46
+ * The era-listing variant, page 2+. A label that already names `city` ("Nasrid Granada") is not framed
47
+ * "in/under <city>" again; `labelNamesCity` is required: the caller decides, so a site's output never shifts on a label rename.
48
+ */
49
+ export function pagedEraMeta(label: string, options: PagedBase & { labelNamesCity: boolean }): PagedMeta {
50
+ const { city, page, total } = options;
51
+ const named = options.labelNamesCity;
52
+ const heads = named
53
+ ? [`${label}: more articles`, `${label}: articles`, `${label} articles`]
54
+ : [`${label}: ${city} articles`, `${label} in ${city}: more articles`, `${city} under ${label}: articles`, `${label} articles`];
55
+ const base = named
56
+ ? `Page ${page} of ${total} of our articles on ${label}, newest first.`
57
+ : `Page ${page} of ${total} of our articles on ${city} in the ${label} period, newest first.`;
58
+ return finish(heads, base, 'eras', options);
59
+ }