@sarimarcus/content-sites-core 0.60.5 → 0.61.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,17 @@
2
2
 
3
3
  All packages in the platform release in lockstep; entries are per release version.
4
4
 
5
+ ## 0.61.0 (2026-11-08)
6
+
7
+ - No changes (lockstep release).
8
+
9
+ ## 0.60.6 (2026-11-07)
10
+
11
+ Additive (SLA-3942); a site that passes nothing new gets the same output, except for the citation dedupe.
12
+
13
+ - `pagedTopicMeta`: new optional `copy` (`PagedMetaCopy`) replaces the English page marker, heads, title tails, opening sentence and optional sentences, so a non-English site gets a localised title and description without the "resident correspondent" phrase (a).
14
+ - `articleBuilder`: `citation` lists each URL once, first occurrence wins (b); new optional `categoryLabels` maps `data.category` to the label emitted as `articleSection` (c).
15
+
5
16
  ## 0.60.5 (2026-11-06)
6
17
 
7
18
  - No changes (lockstep release).
@@ -8,6 +8,8 @@ export interface ArticleOptions {
8
8
  defaultImage?: string;
9
9
  /** `articleSection` when `data.category` is empty. */
10
10
  defaultSection?: string;
11
+ /** Label per `data.category` slug, so `articleSection` carries the reader-facing name; a slug without one is kept. */
12
+ categoryLabels?: Readonly<Record<string, string>>;
11
13
  inLanguage?: string;
12
14
  speakableSelectors?: string[];
13
15
  }
@@ -18,12 +18,27 @@ export function faqPageBuilder() {
18
18
  };
19
19
  };
20
20
  }
21
+ /** One `WebPage` per distinct URL, first occurrence wins; `undefined` when there is none. */
22
+ function citationsOf(sources) {
23
+ if (!Array.isArray(sources) || sources.length === 0)
24
+ return undefined;
25
+ const seen = new Set();
26
+ const out = [];
27
+ for (const s of sources) {
28
+ const url = typeof s === 'string' ? s : s.url;
29
+ if (seen.has(url))
30
+ continue;
31
+ seen.add(url);
32
+ out.push(typeof s === 'string' ? { '@type': 'WebPage', url } : { '@type': 'WebPage', url, ...(s.name ? { name: s.name } : {}) });
33
+ }
34
+ return out;
35
+ }
21
36
  /**
22
37
  * Article (+ its author's Person first, + a FAQPage from `data.questions`). `citation` comes from `data.sources`.
23
38
  * The FAQPage here keeps question and answer text as given, unlike `faqPageBuilder`.
24
39
  */
25
40
  export function articleBuilder(options = {}) {
26
- const { imageVariants = false, defaultImage = '/og-default.jpg', defaultSection = 'Travel Guide', inLanguage: optionInLanguage, speakableSelectors = ['h1', '.article-lede'], } = options;
41
+ const { imageVariants = false, defaultImage = '/og-default.jpg', defaultSection = 'Travel Guide', categoryLabels, inLanguage: optionInLanguage, speakableSelectors = ['h1', '.article-lede'], } = options;
27
42
  return (data, ctx) => {
28
43
  const inLanguage = optionInLanguage ?? ctx.inLanguage ?? 'en';
29
44
  const articleImageUrl = data.image ? ctx.resolveImageUrl(data.image, data.slug) : ctx.abs(defaultImage);
@@ -43,13 +58,9 @@ export function articleBuilder(options = {}) {
43
58
  author: author ? { '@id': author.id } : undefined,
44
59
  publisher: ctx.publisherFor(data.author),
45
60
  mainEntityOfPage: { '@id': ctx.pageUrl },
46
- articleSection: data.category || defaultSection,
61
+ articleSection: (data.category && categoryLabels?.[data.category]) || data.category || defaultSection,
47
62
  inLanguage,
48
- citation: Array.isArray(data.sources) && data.sources.length > 0
49
- ? data.sources.map((s) => (typeof s === 'string'
50
- ? { '@type': 'WebPage', url: s }
51
- : { '@type': 'WebPage', url: s.url, ...(s.name ? { name: s.name } : {}) }))
52
- : undefined,
63
+ citation: citationsOf(data.sources),
53
64
  speakable: { '@type': 'SpeakableSpecification', cssSelector: speakableSelectors },
54
65
  };
55
66
  if ((data.questions?.length ?? 0) > 0) {
@@ -6,5 +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';
9
+ export { pagedTopicMeta, pagedEraMeta, type PagedMetaCopy } from './pagedListingMeta.ts';
10
10
  export type { PagedMeta } from './pagedListingMeta.ts';
@@ -1,3 +1,18 @@
1
+ /** Replaces the English wording for a site in another language; each key left out keeps the default. */
2
+ export interface PagedMetaCopy {
3
+ /** "pagina 2 di 3": the page marker in a title and nowhere else. */
4
+ pageOf: (page: number, total: number) => string;
5
+ /** Title head candidates for `pagedTopicMeta`, first in range wins. */
6
+ heads?: (label: string | null, city: string) => string[];
7
+ /** Title tail candidates after the head and page marker; `''` should come last. */
8
+ titleTails?: (city: string, brand?: string) => string[];
9
+ /** The opening description sentence for `pagedTopicMeta`. */
10
+ description?: (label: string | null, city: string, page: number, total: number) => string;
11
+ /** Optional sentences appended to the description, dropped from the last until it fits. */
12
+ extras?: readonly string[];
13
+ /** Entries of `extras` of which a description carries at most one. */
14
+ exclusiveExtras?: readonly string[];
15
+ }
1
16
  interface PagedBase {
2
17
  /** Place name woven into titles and descriptions, e.g. "Granada". */
3
18
  city: string;
@@ -14,7 +29,9 @@ export interface PagedMeta {
14
29
  * Title (50-60) and description (150-160) for page 2+ of an articles listing; `label` null = the main
15
30
  * /articles listing. Labels run from 7 to 24 characters, so no one template fits; the first candidate in range wins.
16
31
  */
17
- export declare function pagedTopicMeta(label: string | null, options: PagedBase): PagedMeta;
32
+ export declare function pagedTopicMeta(label: string | null, options: PagedBase & {
33
+ copy?: PagedMetaCopy;
34
+ }): PagedMeta;
18
35
  /**
19
36
  * The era-listing variant, page 2+. A label that already names `city` ("Nasrid Granada") is not framed
20
37
  * "in/under <city>" again; `labelNamesCity` is required: the caller decides, so a site's output never shifts on a label rename.
@@ -1,16 +1,19 @@
1
1
  import { fitLength } from "./fitLength.js";
2
- function finish(heads, base, noun, { city, brand, page, total }) {
3
- const pg = `page ${page} of ${total}`;
2
+ function finish(heads, base, noun, { city, brand, page, total }, copy) {
3
+ const pg = copy?.pageOf(page, total) ?? `page ${page} of ${total}`;
4
4
  const titles = [];
5
+ const tails = copy?.titleTails?.(city, brand) ?? [` | ${brand ?? `Explore ${city}`}`, ` | ${city} guide`, ''];
5
6
  for (const head of heads) {
6
- for (const tail of [` | ${brand ?? `Explore ${city}`}`, ` | ${city} guide`, ''])
7
+ for (const tail of tails)
7
8
  titles.push(`${head}, ${pg}${tail}`);
8
9
  }
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 defaultExtras = [' 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'}.`];
11
+ const extras = copy?.extras ?? defaultExtras;
12
+ const exclusive = copy?.exclusiveExtras ?? (copy?.extras ? [] : defaultExtras.filter((e) => e.startsWith(' Browse')));
10
13
  const descriptions = [];
11
14
  for (let mask = (1 << extras.length) - 1; mask >= 0; mask--) {
12
15
  const picked = extras.filter((_, i) => mask & (1 << i));
13
- if (picked.filter((e) => e.startsWith(' Browse')).length > 1)
16
+ if (picked.filter((e) => exclusive.includes(e)).length > 1)
14
17
  continue;
15
18
  descriptions.push(base + picked.join(''));
16
19
  }
@@ -21,11 +24,12 @@ function finish(heads, base, noun, { city, brand, page, total }) {
21
24
  * /articles listing. Labels run from 7 to 24 characters, so no one template fits; the first candidate in range wins.
22
25
  */
23
26
  export function pagedTopicMeta(label, options) {
24
- const { city, page, total } = options;
27
+ const { city, page, total, copy } = options;
25
28
  const noun = label ? `${label} articles` : 'Articles';
26
29
  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);
30
+ const heads = copy?.heads?.(label, city) ?? [`${noun} from ${city}`, `More ${lowerNoun} from ${city}`, `${label ?? 'Stories'}: ${city} articles`, `${noun} in ${city}`];
31
+ const base = copy?.description?.(label, city, page, total) ?? `Page ${page} of ${total} of our ${lowerNoun} on ${city}, newest first.`;
32
+ return finish(heads, base, 'topics', options, copy);
29
33
  }
30
34
  /**
31
35
  * The era-listing variant, page 2+. A label that already names `city` ("Nasrid Granada") is not framed
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sarimarcus/content-sites-core",
3
- "version": "0.60.5",
3
+ "version": "0.61.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",
@@ -20,6 +20,20 @@ export function faqPageBuilder(): SchemaBuilder {
20
20
  };
21
21
  }
22
22
 
23
+ /** One `WebPage` per distinct URL, first occurrence wins; `undefined` when there is none. */
24
+ function citationsOf(sources: unknown): JsonLdNode[] | undefined {
25
+ if (!Array.isArray(sources) || sources.length === 0) return undefined;
26
+ const seen = new Set<string>();
27
+ const out: JsonLdNode[] = [];
28
+ for (const s of sources as any[]) {
29
+ const url = typeof s === 'string' ? s : s.url;
30
+ if (seen.has(url)) continue;
31
+ seen.add(url);
32
+ out.push(typeof s === 'string' ? { '@type': 'WebPage', url } : { '@type': 'WebPage', url, ...(s.name ? { name: s.name } : {}) });
33
+ }
34
+ return out;
35
+ }
36
+
23
37
  export interface ArticleOptions {
24
38
  /** Append each existing `data.imageVariants` path to `image`. */
25
39
  imageVariants?: boolean;
@@ -27,6 +41,8 @@ export interface ArticleOptions {
27
41
  defaultImage?: string;
28
42
  /** `articleSection` when `data.category` is empty. */
29
43
  defaultSection?: string;
44
+ /** Label per `data.category` slug, so `articleSection` carries the reader-facing name; a slug without one is kept. */
45
+ categoryLabels?: Readonly<Record<string, string>>;
30
46
  inLanguage?: string;
31
47
  speakableSelectors?: string[];
32
48
  }
@@ -40,6 +56,7 @@ export function articleBuilder(options: ArticleOptions = {}): SchemaBuilder {
40
56
  imageVariants = false,
41
57
  defaultImage = '/og-default.jpg',
42
58
  defaultSection = 'Travel Guide',
59
+ categoryLabels,
43
60
  inLanguage: optionInLanguage,
44
61
  speakableSelectors = ['h1', '.article-lede'],
45
62
  } = options;
@@ -63,13 +80,9 @@ export function articleBuilder(options: ArticleOptions = {}): SchemaBuilder {
63
80
  author: author ? { '@id': author.id } : undefined,
64
81
  publisher: ctx.publisherFor(data.author),
65
82
  mainEntityOfPage: { '@id': ctx.pageUrl },
66
- articleSection: data.category || defaultSection,
83
+ articleSection: (data.category && categoryLabels?.[data.category]) || data.category || defaultSection,
67
84
  inLanguage,
68
- citation: Array.isArray(data.sources) && data.sources.length > 0
69
- ? data.sources.map((s: any) => (typeof s === 'string'
70
- ? { '@type': 'WebPage', url: s }
71
- : { '@type': 'WebPage', url: s.url, ...(s.name ? { name: s.name } : {}) }))
72
- : undefined,
85
+ citation: citationsOf(data.sources),
73
86
  speakable: { '@type': 'SpeakableSpecification', cssSelector: speakableSelectors },
74
87
  };
75
88
 
package/src/text/index.ts CHANGED
@@ -7,5 +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';
10
+ export { pagedTopicMeta, pagedEraMeta, type PagedMetaCopy } from './pagedListingMeta.ts';
11
11
  export type { PagedMeta } from './pagedListingMeta.ts';
@@ -1,5 +1,21 @@
1
1
  import { fitLength } from './fitLength.ts';
2
2
 
3
+ /** Replaces the English wording for a site in another language; each key left out keeps the default. */
4
+ export interface PagedMetaCopy {
5
+ /** "pagina 2 di 3": the page marker in a title and nowhere else. */
6
+ pageOf: (page: number, total: number) => string;
7
+ /** Title head candidates for `pagedTopicMeta`, first in range wins. */
8
+ heads?: (label: string | null, city: string) => string[];
9
+ /** Title tail candidates after the head and page marker; `''` should come last. */
10
+ titleTails?: (city: string, brand?: string) => string[];
11
+ /** The opening description sentence for `pagedTopicMeta`. */
12
+ description?: (label: string | null, city: string, page: number, total: number) => string;
13
+ /** Optional sentences appended to the description, dropped from the last until it fits. */
14
+ extras?: readonly string[];
15
+ /** Entries of `extras` of which a description carries at most one. */
16
+ exclusiveExtras?: readonly string[];
17
+ }
18
+
3
19
  interface PagedBase {
4
20
  /** Place name woven into titles and descriptions, e.g. "Granada". */
5
21
  city: string;
@@ -14,17 +30,20 @@ export interface PagedMeta {
14
30
  description: string;
15
31
  }
16
32
 
17
- function finish(heads: string[], base: string, noun: 'topics' | 'eras', { city, brand, page, total }: PagedBase): PagedMeta {
18
- const pg = `page ${page} of ${total}`;
33
+ function finish(heads: string[], base: string, noun: 'topics' | 'eras', { city, brand, page, total }: PagedBase, copy?: PagedMetaCopy): PagedMeta {
34
+ const pg = copy?.pageOf(page, total) ?? `page ${page} of ${total}`;
19
35
  const titles: string[] = [];
36
+ const tails = copy?.titleTails?.(city, brand) ?? [` | ${brand ?? `Explore ${city}`}`, ` | ${city} guide`, ''];
20
37
  for (const head of heads) {
21
- for (const tail of [` | ${brand ?? `Explore ${city}`}`, ` | ${city} guide`, '']) titles.push(`${head}, ${pg}${tail}`);
38
+ for (const tail of tails) titles.push(`${head}, ${pg}${tail}`);
22
39
  }
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'}.`];
40
+ const defaultExtras = [' 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'}.`];
41
+ const extras = copy?.extras ?? defaultExtras;
42
+ const exclusive = copy?.exclusiveExtras ?? (copy?.extras ? [] : defaultExtras.filter((e) => e.startsWith(' Browse')));
24
43
  const descriptions: string[] = [];
25
44
  for (let mask = (1 << extras.length) - 1; mask >= 0; mask--) {
26
45
  const picked = extras.filter((_, i) => mask & (1 << i));
27
- if (picked.filter((e) => e.startsWith(' Browse')).length > 1) continue;
46
+ if (picked.filter((e) => exclusive.includes(e)).length > 1) continue;
28
47
  descriptions.push(base + picked.join(''));
29
48
  }
30
49
  return { title: fitLength(titles, 50, 60), description: fitLength(descriptions, 150, 160) };
@@ -34,12 +53,13 @@ function finish(heads: string[], base: string, noun: 'topics' | 'eras', { city,
34
53
  * Title (50-60) and description (150-160) for page 2+ of an articles listing; `label` null = the main
35
54
  * /articles listing. Labels run from 7 to 24 characters, so no one template fits; the first candidate in range wins.
36
55
  */
37
- export function pagedTopicMeta(label: string | null, options: PagedBase): PagedMeta {
38
- const { city, page, total } = options;
56
+ export function pagedTopicMeta(label: string | null, options: PagedBase & { copy?: PagedMetaCopy }): PagedMeta {
57
+ const { city, page, total, copy } = options;
39
58
  const noun = label ? `${label} articles` : 'Articles';
40
59
  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);
60
+ const heads = copy?.heads?.(label, city) ?? [`${noun} from ${city}`, `More ${lowerNoun} from ${city}`, `${label ?? 'Stories'}: ${city} articles`, `${noun} in ${city}`];
61
+ const base = copy?.description?.(label, city, page, total) ?? `Page ${page} of ${total} of our ${lowerNoun} on ${city}, newest first.`;
62
+ return finish(heads, base, 'topics', options, copy);
43
63
  }
44
64
 
45
65
  /**