@sarimarcus/content-sites-core 0.55.3 → 0.56.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.
@@ -28,8 +28,20 @@ type ZodBuilders = Pick<typeof Zod, 'discriminatedUnion' | 'object' | 'literal'
28
28
  export declare function createInterludeSchema(z: ZodBuilders, config: InterludeSchemaConfig): Zod.ZodDiscriminatedUnion<[Zod.ZodObject<{
29
29
  type: Zod.ZodLiteral<"quote">;
30
30
  variant: Zod.ZodEnum<{
31
+ pull: "pull";
31
32
  external: "external";
33
+ }>;
34
+ content: Zod.ZodString;
35
+ attribution: Zod.ZodOptional<Zod.ZodObject<{
36
+ name: Zod.ZodString;
37
+ role: Zod.ZodOptional<Zod.ZodString>;
38
+ }, Zod.z.core.$strip>>;
39
+ afterParagraph: Zod.ZodNumber;
40
+ }, Zod.z.core.$strip>, ...(Zod.ZodObject<{
41
+ type: Zod.ZodLiteral<"quote">;
42
+ variant: Zod.ZodEnum<{
32
43
  pull: "pull";
44
+ external: "external";
33
45
  }>;
34
46
  content: Zod.ZodString;
35
47
  attribution: Zod.ZodOptional<Zod.ZodObject<{
@@ -37,40 +49,40 @@ export declare function createInterludeSchema(z: ZodBuilders, config: InterludeS
37
49
  role: Zod.ZodOptional<Zod.ZodString>;
38
50
  }, Zod.z.core.$strip>>;
39
51
  afterParagraph: Zod.ZodNumber;
40
- }, Zod.z.core.$strip>, Zod.ZodObject<{
52
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
41
53
  type: Zod.ZodLiteral<"stat-fact">;
42
54
  figure: Zod.ZodString;
43
55
  caption: Zod.ZodString;
44
56
  afterParagraph: Zod.ZodNumber;
45
- }, Zod.z.core.$strip>, Zod.ZodObject<{
57
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
46
58
  type: Zod.ZodLiteral<"evidence-context">;
47
59
  finding: Zod.ZodString;
48
60
  basis: Zod.ZodString;
49
61
  boundary: Zod.ZodString;
50
62
  afterParagraph: Zod.ZodNumber;
51
- }, Zod.z.core.$strip>, Zod.ZodObject<{
63
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
52
64
  type: Zod.ZodLiteral<"related-card">;
53
65
  relatedType: Zod.ZodEnum<{
54
66
  [x: string]: string;
55
67
  }>;
56
68
  relatedSlug: Zod.ZodString;
57
69
  afterParagraph: Zod.ZodNumber;
58
- }, Zod.z.core.$strip>, Zod.ZodObject<{
70
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
59
71
  type: Zod.ZodLiteral<"tldr">;
60
72
  content: Zod.ZodOptional<Zod.ZodString>;
61
73
  bullets: Zod.ZodOptional<Zod.ZodArray<Zod.ZodString>>;
62
74
  title: Zod.ZodOptional<Zod.ZodString>;
63
75
  position: Zod.ZodLiteral<"end">;
64
- }, Zod.z.core.$strip>, Zod.ZodObject<{
76
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
65
77
  type: Zod.ZodLiteral<"answer-box">;
66
78
  question: Zod.ZodString;
67
79
  answer: Zod.ZodString;
68
80
  afterParagraph: Zod.ZodNumber;
69
- }, Zod.z.core.$strip>, Zod.ZodObject<{
81
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
70
82
  type: Zod.ZodLiteral<"field-note">;
71
83
  content: Zod.ZodString;
72
84
  afterParagraph: Zod.ZodNumber;
73
- }, Zod.z.core.$strip>, Zod.ZodObject<{
85
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
74
86
  type: Zod.ZodLiteral<"caution">;
75
87
  variant: Zod.ZodEnum<{
76
88
  tip: "tip";
@@ -80,16 +92,16 @@ export declare function createInterludeSchema(z: ZodBuilders, config: InterludeS
80
92
  title: Zod.ZodOptional<Zod.ZodString>;
81
93
  content: Zod.ZodString;
82
94
  afterParagraph: Zod.ZodNumber;
83
- }, Zod.z.core.$strip>, Zod.ZodObject<{
95
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
84
96
  type: Zod.ZodLiteral<"checklist">;
85
97
  title: Zod.ZodString;
86
98
  items: Zod.ZodArray<Zod.ZodString>;
87
99
  afterParagraph: Zod.ZodNumber;
88
- }, Zod.z.core.$strip>, Zod.ZodObject<{
100
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
89
101
  type: Zod.ZodLiteral<"did-you-know">;
90
102
  content: Zod.ZodString;
91
103
  afterParagraph: Zod.ZodNumber;
92
- }, Zod.z.core.$strip>, Zod.ZodObject<{
104
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
93
105
  type: Zod.ZodLiteral<"timeline">;
94
106
  events: Zod.ZodArray<Zod.ZodObject<{
95
107
  date: Zod.ZodString;
@@ -97,21 +109,21 @@ export declare function createInterludeSchema(z: ZodBuilders, config: InterludeS
97
109
  description: Zod.ZodOptional<Zod.ZodString>;
98
110
  }, Zod.z.core.$strip>>;
99
111
  afterParagraph: Zod.ZodNumber;
100
- }, Zod.z.core.$strip>, Zod.ZodObject<{
112
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
101
113
  type: Zod.ZodLiteral<"comparison-table">;
102
114
  headers: Zod.ZodArray<Zod.ZodString>;
103
115
  rows: Zod.ZodArray<Zod.ZodArray<Zod.ZodString>>;
104
116
  afterParagraph: Zod.ZodNumber;
105
- }, Zod.z.core.$strip>, Zod.ZodObject<{
117
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
106
118
  relatedType: Zod.ZodEnum<{
107
119
  [x: string]: string;
108
120
  }>;
109
121
  afterParagraph: Zod.ZodNumber;
110
122
  relatedSlug?: Zod.ZodOptional<Zod.ZodString> | undefined;
111
123
  type: Zod.ZodLiteral<"monument-feature">;
112
- }, Zod.z.core.$strip>, Zod.ZodObject<{
124
+ }, Zod.z.core.$strip> | Zod.ZodObject<{
113
125
  type: Zod.ZodLiteral<"article-feature">;
114
126
  afterParagraph: Zod.ZodNumber;
115
- }, Zod.z.core.$strip>], "type">;
127
+ }, Zod.z.core.$strip>)[]], "type">;
116
128
  export { pickBandSlot } from './bandSlot.ts';
117
129
  export { relocateArticleFeature, pickFeatureParagraph } from './relocateFeature.ts';
@@ -20,10 +20,12 @@ const nonEmpty = (values, field) => {
20
20
  */
21
21
  export function createInterludeSchema(z, config) {
22
22
  const relatedCardTypes = nonEmpty(config.relatedCardTypes, 'relatedCardTypes');
23
- const featureTypes = nonEmpty(config.featureTypes.types, 'featureTypes.types');
23
+ const featureTypes = config.featureTypes.types.length
24
+ ? config.featureTypes.types
25
+ : null;
24
26
  const after = z.number().int().min(0);
25
27
  const cited = (field) => z.string().min(1).max(260).regex(/\[\^\d+\]\s*$/, `${field} must end with a [^N] citation marker`);
26
- return z.discriminatedUnion('type', [
28
+ const baseVariants = [
27
29
  z.object({
28
30
  type: z.literal('quote'),
29
31
  variant: z.enum(['pull', 'external']),
@@ -78,16 +80,21 @@ export function createInterludeSchema(z, config) {
78
80
  rows: z.array(z.array(z.string())).min(2),
79
81
  afterParagraph: after,
80
82
  }),
81
- // The mandatory mid-article feature: despite the name, any entity with its own page. Without a pinned slug the
82
- // template auto-selects it and injects relatedType/relatedSlug.
83
- z.object({
84
- type: z.literal('monument-feature'),
85
- ...(config.featureTypes.allowPinnedSlug ? { relatedSlug: z.string().optional() } : {}),
86
- relatedType: z.enum(featureTypes),
87
- afterParagraph: after,
88
- }),
83
+ ...(featureTypes
84
+ ? [
85
+ // The mandatory mid-article feature: despite the name, any entity with its own page. Without a pinned slug the
86
+ // template auto-selects it and injects relatedType/relatedSlug.
87
+ z.object({
88
+ type: z.literal('monument-feature'),
89
+ ...(config.featureTypes.allowPinnedSlug ? { relatedSlug: z.string().optional() } : {}),
90
+ relatedType: z.enum(featureTypes),
91
+ afterParagraph: after,
92
+ }),
93
+ ]
94
+ : []),
89
95
  z.object({ type: z.literal('article-feature'), afterParagraph: after }),
90
- ]);
96
+ ];
97
+ return z.discriminatedUnion('type', baseVariants);
91
98
  }
92
99
  export { pickBandSlot } from "./bandSlot.js";
93
100
  export { relocateArticleFeature, pickFeatureParagraph } from "./relocateFeature.js";
@@ -124,4 +124,40 @@ export declare function createPeople<P extends PersonData, I = unknown>(options:
124
124
  personPortrait: (slug: string) => I | undefined;
125
125
  personHref: (slug: string) => string;
126
126
  };
127
+ /**
128
+ * Shared Zod field map for an `authors` collection (SLA-3721), covering every field used by
129
+ * `AuthorPage`, `AuthorsIndexPage`, `AuthorStrip`, `ArticleMetadata`, and `personBuilder`.
130
+ */
131
+ export declare function authorSchemaFields(z: ZodBuilders): {
132
+ name: Zod.ZodString;
133
+ slug: Zod.ZodString;
134
+ role: Zod.ZodOptional<Zod.ZodString>;
135
+ jobTitle: Zod.ZodOptional<Zod.ZodString>;
136
+ bio: Zod.ZodString;
137
+ description: Zod.ZodOptional<Zod.ZodString>;
138
+ credentials: Zod.ZodOptional<Zod.ZodString>;
139
+ photo: Zod.ZodOptional<Zod.ZodString>;
140
+ socialLinks: Zod.ZodOptional<Zod.ZodArray<Zod.ZodString>>;
141
+ sameAs: Zod.ZodOptional<Zod.ZodArray<Zod.ZodString>>;
142
+ expertise: Zod.ZodOptional<Zod.ZodArray<Zod.ZodString>>;
143
+ featured: Zod.ZodOptional<Zod.ZodBoolean>;
144
+ dateModified: Zod.ZodOptional<Zod.ZodString>;
145
+ };
146
+ export interface AuthorEntryLike<D extends {
147
+ name: string;
148
+ slug: string;
149
+ } = {
150
+ name: string;
151
+ slug: string;
152
+ }> {
153
+ data: D;
154
+ }
155
+ /**
156
+ * Resolves a human-readable author `name` (or `slug`) against a loaded `authors` collection,
157
+ * returning the matching entry's `.data` or `null` if unknown.
158
+ */
159
+ export declare function findAuthorByName<D extends {
160
+ name: string;
161
+ slug: string;
162
+ }>(authors: readonly (AuthorEntryLike<D> | D)[], name: string | undefined | null): D | null;
127
163
  export {};
@@ -173,3 +173,40 @@ export function createPeople(options) {
173
173
  const personPortrait = (slug) => portraits[slug];
174
174
  return { toPersonLink, resolvePeople, personPortrait, personHref };
175
175
  }
176
+ /**
177
+ * Shared Zod field map for an `authors` collection (SLA-3721), covering every field used by
178
+ * `AuthorPage`, `AuthorsIndexPage`, `AuthorStrip`, `ArticleMetadata`, and `personBuilder`.
179
+ */
180
+ export function authorSchemaFields(z) {
181
+ return {
182
+ name: z.string().min(1),
183
+ slug: z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/),
184
+ role: z.string().optional(),
185
+ jobTitle: z.string().max(60, 'jobTitle renders as an eyebrow and Person.jobTitle: max 60 chars.').optional(),
186
+ bio: z.string().min(1),
187
+ description: z.string().optional(),
188
+ credentials: z.string().optional(),
189
+ photo: z.string().optional(),
190
+ socialLinks: z.array(z.string().url()).optional(),
191
+ sameAs: z.array(z.string().url()).optional(),
192
+ expertise: z.array(z.string().max(40, 'expertise entries render as chips: max 40 chars each.')).optional(),
193
+ featured: z.boolean().optional(),
194
+ dateModified: z.string().optional(),
195
+ };
196
+ }
197
+ /**
198
+ * Resolves a human-readable author `name` (or `slug`) against a loaded `authors` collection,
199
+ * returning the matching entry's `.data` or `null` if unknown.
200
+ */
201
+ export function findAuthorByName(authors, name) {
202
+ if (!name)
203
+ return null;
204
+ const target = name.trim().toLowerCase();
205
+ for (const raw of authors) {
206
+ const data = 'data' in raw ? raw.data : raw;
207
+ if (data.name.trim().toLowerCase() === target || data.slug.toLowerCase() === target) {
208
+ return data;
209
+ }
210
+ }
211
+ return null;
212
+ }
@@ -7,8 +7,8 @@ export { DAY_KEYS, HOURS_ALWAYS_OPEN, parseHoursShifts, closedFieldDays, resolve
7
7
  export type { DayKey, OpeningHoursInput, OpeningHoursBucket } from './hours.ts';
8
8
  export { openingHoursRows, openingHoursSummary, latestClosing } from './hoursDisplay.ts';
9
9
  export type { OpeningHours, HoursRow } from './hoursDisplay.ts';
10
- export { renderSchemaPolicy } from './policy.ts';
11
- export type { SchemaPolicy } from './policy.ts';
10
+ export { renderSchemaPolicy, profilePageAfterEntries, editorialSchemaPolicy } from './policy.ts';
11
+ export type { SchemaPolicy, EditorialSchemaPolicyOptions } from './policy.ts';
12
12
  export { offer, placeNode, siteOrganizationNode, siteWebsiteNode } from './nodes.ts';
13
13
  export type { OfferFields, SiteNodeFields, OrganizationLogo } from './nodes.ts';
14
14
  export { buildBreadcrumbList, buildWebPageNode, assembleGraph, finalizeGraph } from './graph.ts';
@@ -3,7 +3,7 @@ export { parsePriceFromString, isFreeEntry, cleanStreetAddress, normalizePriceRa
3
3
  export { parsePriceRange, calculateAggregatePriceRange } from "./price.js";
4
4
  export { DAY_KEYS, HOURS_ALWAYS_OPEN, parseHoursShifts, closedFieldDays, resolveOpeningHours, assertedOpenDays, generateOpeningHours, parseHoursString, hoursStringOpenDays, } from "./hours.js";
5
5
  export { openingHoursRows, openingHoursSummary, latestClosing } from "./hoursDisplay.js";
6
- export { renderSchemaPolicy } from "./policy.js";
6
+ export { renderSchemaPolicy, profilePageAfterEntries, editorialSchemaPolicy } from "./policy.js";
7
7
  export { offer, placeNode, siteOrganizationNode, siteWebsiteNode } from "./nodes.js";
8
8
  export { buildBreadcrumbList, buildWebPageNode, assembleGraph, finalizeGraph } from "./graph.js";
9
9
  export { faqPageBuilder, articleBuilder, collectionPageBuilder, itemListBuilder, howToBuilder, aboutPageBuilder, contactPageBuilder, personBuilder, historicalPersonSchema, aggregateOfferBuilder, touristDestinationBuilder, organizationBuilder, } from "./pages.js";
@@ -1,4 +1,6 @@
1
1
  import { type AssembleOptions, type PageInput } from './graph.ts';
2
+ import { type OrganizationLogo, type SiteNodeFields } from './nodes.ts';
3
+ import { type AboutPageOptions, type ArticleOptions, type CollectionPageOptions, type ItemListOptions, type PersonOptions } from './pages.ts';
2
4
  import type { JsonLdNode, SchemaBuilders, SchemaContext, SchemaContextInput, SchemaEntry } from './types.ts';
3
5
  /** A site's JSON-LD policy: its context options, base nodes, builders and graph hooks. */
4
6
  export interface SchemaPolicy {
@@ -10,6 +12,34 @@ export interface SchemaPolicy {
10
12
  builders: SchemaBuilders;
11
13
  hooks?(ctx: SchemaContext, entries: SchemaEntry[]): Pick<AssembleOptions, 'beforeEntries' | 'afterEntries'>;
12
14
  }
15
+ /**
16
+ * Promotes the page's `WebPage` node into `ProfilePage` with `mainEntity` pointing at `${ctx.pageUrl}#person`
17
+ * whenever a `Person` or `HistoricalPerson` node with that `@id` is emitted on the page (SLA-3717).
18
+ */
19
+ export declare function profilePageAfterEntries(ctx: SchemaContext): NonNullable<AssembleOptions['afterEntries']>;
20
+ export interface EditorialSchemaPolicyOptions {
21
+ /** Base Organization + WebSite fields (`name`, `description`, `inLanguage`, plus optional `logo`, `sameAs`, `searchPath`). */
22
+ site: SiteNodeFields & {
23
+ logo?: OrganizationLogo;
24
+ sameAs?: string[];
25
+ searchPath?: string;
26
+ };
27
+ /** Optional `SchemaContextInput` overrides (`inLanguage`, `routes`, `findAuthor`, `publisher`). */
28
+ context?: Partial<SchemaContextInput>;
29
+ article?: ArticleOptions;
30
+ collectionPage?: CollectionPageOptions;
31
+ itemList?: ItemListOptions;
32
+ aboutPage?: AboutPageOptions;
33
+ person?: PersonOptions;
34
+ /** Additional or override builders merged on top of the editorial defaults. */
35
+ extraBuilders?: SchemaBuilders;
36
+ }
37
+ /**
38
+ * Complete `SchemaPolicy` for an articles-only / editorial site without any tourism vertical dependency (SLA-3717).
39
+ * Includes `Organization`, `WebSite`, `Article`, `CollectionPage`, `ItemList`, `AboutPage`, `ContactPage`, `Person`,
40
+ * `HistoricalPerson`, `FAQPage`, `HowTo`, and the `ProfilePage` `afterEntries` hook.
41
+ */
42
+ export declare function editorialSchemaPolicy(options: EditorialSchemaPolicyOptions): SchemaPolicy;
13
43
  /**
14
44
  * One page's finalised JSON-LD under a site policy: context, base nodes, entries, hooks. The site adapter and the
15
45
  * factory schema goldens both render through this, so the goldens test the wiring that ships.
@@ -1,6 +1,80 @@
1
1
  import { temporalCoverageOf } from "../eras/index.js";
2
2
  import { createSchemaContext } from "./context.js";
3
3
  import { assembleGraph, finalizeGraph } from "./graph.js";
4
+ import { siteOrganizationNode, siteWebsiteNode } from "./nodes.js";
5
+ import { aboutPageBuilder, articleBuilder, collectionPageBuilder, contactPageBuilder, faqPageBuilder, historicalPersonSchema, howToBuilder, itemListBuilder, organizationBuilder, personBuilder, } from "./pages.js";
6
+ /**
7
+ * Promotes the page's `WebPage` node into `ProfilePage` with `mainEntity` pointing at `${ctx.pageUrl}#person`
8
+ * whenever a `Person` or `HistoricalPerson` node with that `@id` is emitted on the page (SLA-3717).
9
+ */
10
+ export function profilePageAfterEntries(ctx) {
11
+ return (graph) => {
12
+ const personId = `${ctx.pageUrl}#person`;
13
+ if (graph.some((node) => node['@id'] === personId)) {
14
+ const webPage = graph.find((node) => node['@id'] === ctx.pageUrl);
15
+ if (webPage) {
16
+ webPage['@type'] = 'ProfilePage';
17
+ webPage.mainEntity = { '@id': personId };
18
+ }
19
+ }
20
+ };
21
+ }
22
+ /**
23
+ * Complete `SchemaPolicy` for an articles-only / editorial site without any tourism vertical dependency (SLA-3717).
24
+ * Includes `Organization`, `WebSite`, `Article`, `CollectionPage`, `ItemList`, `AboutPage`, `ContactPage`, `Person`,
25
+ * `HistoricalPerson`, `FAQPage`, `HowTo`, and the `ProfilePage` `afterEntries` hook.
26
+ */
27
+ export function editorialSchemaPolicy(options) {
28
+ const { site, context, article = { imageVariants: true, defaultSection: 'Article' }, collectionPage, itemList, aboutPage, person, extraBuilders, } = options;
29
+ const { logo, sameAs, searchPath, ...siteFields } = site;
30
+ const faqBuilder = faqPageBuilder();
31
+ const baseBuilders = {
32
+ Article: articleBuilder({ imageVariants: true, defaultSection: 'Article', ...article }),
33
+ article: articleBuilder({ imageVariants: true, defaultSection: 'Article', ...article }),
34
+ CollectionPage: collectionPageBuilder(collectionPage),
35
+ collectionPage: collectionPageBuilder(collectionPage),
36
+ ItemList: itemListBuilder(itemList),
37
+ itemList: itemListBuilder(itemList),
38
+ AboutPage: aboutPageBuilder(aboutPage),
39
+ aboutPage: aboutPageBuilder(aboutPage),
40
+ ContactPage: contactPageBuilder(),
41
+ contactPage: contactPageBuilder(),
42
+ Person: personBuilder(person),
43
+ person: personBuilder(person),
44
+ HistoricalPerson: historicalPersonSchema(),
45
+ historicalPerson: historicalPersonSchema(),
46
+ FAQPage: faqBuilder,
47
+ faqPage: faqBuilder,
48
+ faq: faqBuilder,
49
+ HowTo: howToBuilder(),
50
+ howTo: howToBuilder(),
51
+ Organization: organizationBuilder(),
52
+ organization: organizationBuilder(),
53
+ ...extraBuilders,
54
+ };
55
+ return {
56
+ ...(context ? { context } : {}),
57
+ nodes: (ctx) => ({
58
+ organization: siteOrganizationNode(ctx, siteFields, logo, sameAs?.length ? { sameAs } : {}),
59
+ website: siteWebsiteNode(ctx, siteFields, searchPath
60
+ ? {
61
+ potentialAction: {
62
+ '@type': 'SearchAction',
63
+ target: {
64
+ '@type': 'EntryPoint',
65
+ urlTemplate: `${ctx.siteBaseUrl}${searchPath}?q={search_term_string}`,
66
+ },
67
+ 'query-input': 'required name=search_term_string',
68
+ },
69
+ }
70
+ : {}),
71
+ }),
72
+ builders: baseBuilders,
73
+ hooks: (ctx) => ({
74
+ afterEntries: profilePageAfterEntries(ctx),
75
+ }),
76
+ };
77
+ }
4
78
  // schema.org defines temporalCoverage on CreativeWork only; a Place node (TouristAttraction) would not validate.
5
79
  const TEMPORAL_TYPES = new Set(['Article']);
6
80
  const withCoverage = (node, coverage) => {
@@ -2,7 +2,9 @@
2
2
  export declare const DEFAULT_ROUTES: {
3
3
  readonly articles: "articles";
4
4
  readonly articleTopic: "articles/topic";
5
+ readonly articleTag: "articles/tag";
5
6
  readonly author: "author";
7
+ readonly authors: "authors";
6
8
  readonly neighborhood: "neighborhood";
7
9
  };
8
10
  export type RouteKind = keyof typeof DEFAULT_ROUTES;
@@ -2,7 +2,9 @@
2
2
  export const DEFAULT_ROUTES = {
3
3
  articles: 'articles',
4
4
  articleTopic: 'articles/topic',
5
+ articleTag: 'articles/tag',
5
6
  author: 'author',
7
+ authors: 'authors',
6
8
  neighborhood: 'neighborhood',
7
9
  };
8
10
  /** Path segment for `kind`: the site's override, then `DEFAULT_ROUTES`, then the kind's own name (vertical entity kinds). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sarimarcus/content-sites-core",
3
- "version": "0.55.3",
3
+ "version": "0.56.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",
@@ -8,3 +8,18 @@ export {
8
8
  shapeFor, checkFormat, checkCounts, checkKeyFactCount, checkWords, countBodyWords, validateShape, articleShapeIssues,
9
9
  } from './formats.ts';
10
10
  export type { ArticleFormat, ArticleMode, ArticleShape, FormatCard, Range, ShapeIssue, ShapeRanges } from './formats.ts';
11
+ export {
12
+ articleSchemaFields, articleSuperRefineIssues, createArticleSchema,
13
+ } from './schema.ts';
14
+ export type { ArticleSchemaOptions, ArticleTagMeta } from './schema.ts';
15
+ export {
16
+ ARTICLES_PAGE_SIZE, MIN_HUB_ARTICLES, MIN_INDEXABLE_HUB_ARTICLES, MIN_INDEXABLE_TAG_ARTICLES,
17
+ publishedInstant, sortArticles, totalArticlePages, articlesForPage, articlePagePath, articleTagPath,
18
+ topicNeighbours, hubCategories, hubNavCategories,
19
+ tagArticles, populatedTags, indexableTags, topTags, topCategoryTags,
20
+ } from './listing.ts';
21
+ export type { ArticleHubCopy, ListableArticle, ListableArticleData } from './listing.ts';
22
+ export {
23
+ splitParagraphs, renderInlineMarkdown, toISO, mergeAnswerBoxFaqs,
24
+ } from './render.ts';
25
+ export type { AnswerBoxSectionLike } from './render.ts';
@@ -0,0 +1,226 @@
1
+ // Shared article listing, pagination, category-hub, and controlled-tag helpers (SLA-3716).
2
+ // Pure functions parameterized over article shape `{ data: { slug, title, datePublished, category?, tags? } }`
3
+ // so travel sites and editorial sites share one implementation.
4
+ import { routePath, type SiteRoutes } from '../url/routes.ts';
5
+ import type { ArticleTagMeta } from './schema.ts';
6
+
7
+ export const ARTICLES_PAGE_SIZE = 12;
8
+
9
+ /** Minimum articles in a category for `/articles/topic/<category>` to build. */
10
+ export const MIN_HUB_ARTICLES = 1;
11
+
12
+ /** Minimum articles for a topic hub to self-canonicalize and index (`< 4` is `noindex, follow` → `/articles`). */
13
+ export const MIN_INDEXABLE_HUB_ARTICLES = 4;
14
+
15
+ /** Minimum articles for a tag hub `/articles/tag/<tag>` to self-canonicalize and index. */
16
+ export const MIN_INDEXABLE_TAG_ARTICLES = 4;
17
+
18
+ export interface ArticleHubCopy {
19
+ /** Visible H1 on page 1 (page 2+ appends `— Page N`). */
20
+ h1: string;
21
+ /** `<title>` on page 1 (50–60 chars). */
22
+ seoTitle: string;
23
+ /** `<meta name="description">` on page 1 (150–160 chars). */
24
+ description: string;
25
+ /** Two-to-three sentence editorial lede rendered below the H1 on page 1 only. */
26
+ intro: string;
27
+ }
28
+
29
+ export interface ListableArticleData {
30
+ slug: string;
31
+ title: string;
32
+ datePublished: string;
33
+ category?: string;
34
+ tags?: readonly string[];
35
+ }
36
+
37
+ export interface ListableArticle<D extends ListableArticleData = ListableArticleData> {
38
+ data: D;
39
+ }
40
+
41
+ /**
42
+ * Ordering timestamp for an article. A bare `YYYY-MM-DD` has no time-of-day, so articles shipped on the same day tie on
43
+ * `Date.parse`; we spread bare dates deterministically across the UTC day using `deterministicId(slug)` (1..86399s) so
44
+ * same-day articles get a stable, non-alphabetical order while any explicit `T…` timestamp wins accurately.
45
+ */
46
+ export function publishedInstant(data: { slug: string; datePublished: string }): number {
47
+ const raw = data.datePublished;
48
+ const base = Date.parse(raw);
49
+ if (raw.includes('T')) return base;
50
+ let h = 5381;
51
+ for (let i = 0; i < data.slug.length; i++) h = ((h * 33) ^ data.slug.charCodeAt(i)) >>> 0;
52
+ return base + ((h % 86399) + 1) * 1000;
53
+ }
54
+
55
+ /** Sort articles newest-first by `publishedInstant`, with `slug` as a final deterministic tiebreaker. */
56
+ export function sortArticles<T extends ListableArticle>(articles: readonly T[]): T[] {
57
+ return [...articles].sort(
58
+ (a, b) =>
59
+ publishedInstant(b.data) - publishedInstant(a.data) ||
60
+ a.data.slug.localeCompare(b.data.slug),
61
+ );
62
+ }
63
+
64
+ export function totalArticlePages(count: number, pageSize: number = ARTICLES_PAGE_SIZE): number {
65
+ return Math.max(1, Math.ceil(count / pageSize));
66
+ }
67
+
68
+ export function articlesForPage<T>(
69
+ sorted: readonly T[],
70
+ page: number,
71
+ pageSize: number = ARTICLES_PAGE_SIZE,
72
+ ): T[] {
73
+ const start = (page - 1) * pageSize;
74
+ return sorted.slice(start, start + pageSize);
75
+ }
76
+
77
+ /**
78
+ * Path for page `page` of `/articles` (no category) or `/articles/topic/<category>`.
79
+ * Page 1 is the canonical root (`/articles` or `/articles/topic/<category>`), never `/page/1`.
80
+ */
81
+ export function articlePagePath(page: number, category?: string, routes: SiteRoutes = {}): string {
82
+ const root = category
83
+ ? routePath('articleTopic', category, routes)
84
+ : routePath('articles', undefined, routes);
85
+ return page <= 1 ? root : `${root}/page/${page}`;
86
+ }
87
+
88
+ /** Path for a controlled tag hub `/articles/tag/<tag>`. */
89
+ export function articleTagPath(tag: string, routes: SiteRoutes = {}): string {
90
+ return routePath('articleTag', tag, routes);
91
+ }
92
+
93
+ /**
94
+ * Previous (older) and next (newer) articles in the same category, for `ArticleTopicPager`.
95
+ * `sorted` must be in `sortArticles` order (newest first, index 0 = newest).
96
+ */
97
+ export function topicNeighbours<T extends ListableArticle>(
98
+ sorted: readonly T[],
99
+ currentSlug: string,
100
+ category: string | undefined,
101
+ ): {
102
+ prev: { slug: string; title: string } | null;
103
+ next: { slug: string; title: string } | null;
104
+ } {
105
+ if (!category) return { prev: null, next: null };
106
+ const inCat = sorted.filter((a) => a.data.category === category);
107
+ const idx = inCat.findIndex((a) => a.data.slug === currentSlug);
108
+ if (idx === -1) return { prev: null, next: null };
109
+ const newer = idx > 0 ? inCat[idx - 1]! : null;
110
+ const older = idx < inCat.length - 1 ? inCat[idx + 1]! : null;
111
+ return {
112
+ prev: older ? { slug: older.data.slug, title: older.data.title } : null,
113
+ next: newer ? { slug: newer.data.slug, title: newer.data.title } : null,
114
+ };
115
+ }
116
+
117
+ /**
118
+ * Categories that qualify for a built `/articles/topic/<category>` hub (`count >= minArticles`),
119
+ * in the declaration order of `categoryMap`.
120
+ */
121
+ export function hubCategories<C extends string>(
122
+ articles: readonly ListableArticle[],
123
+ categoryMap: Readonly<Record<C, string>>,
124
+ minArticles: number = MIN_HUB_ARTICLES,
125
+ ): { category: C; label: string; count: number }[] {
126
+ const counts = new Map<string, number>();
127
+ for (const a of articles) {
128
+ const cat = a.data.category;
129
+ if (cat) counts.set(cat, (counts.get(cat) ?? 0) + 1);
130
+ }
131
+ return (Object.entries(categoryMap) as [C, string][])
132
+ .map(([category, label]) => ({ category, label, count: counts.get(category) ?? 0 }))
133
+ .filter((entry) => entry.count >= minArticles);
134
+ }
135
+
136
+ /**
137
+ * Subset of `hubCategories` that clear `MIN_INDEXABLE_HUB_ARTICLES` (`>= 4`).
138
+ * Used by `ArticleCategoryNav`, `ArticlesNavMenu`, and footer topic links so navigation
139
+ * never funnels internal PageRank to `noindex` hubs.
140
+ */
141
+ export function hubNavCategories<C extends string>(
142
+ articles: readonly ListableArticle[],
143
+ categoryMap: Readonly<Record<C, string>>,
144
+ minIndexable: number = MIN_INDEXABLE_HUB_ARTICLES,
145
+ ): { category: C; label: string; count: number }[] {
146
+ return hubCategories(articles, categoryMap, minIndexable);
147
+ }
148
+
149
+ /** Filter and sort articles carrying `tag`. */
150
+ export function tagArticles<T extends ListableArticle>(
151
+ articles: readonly T[],
152
+ tag: string,
153
+ ): T[] {
154
+ return sortArticles(articles.filter((a) => a.data.tags?.includes(tag)));
155
+ }
156
+
157
+ /**
158
+ * Tags from `tagMap` that have at least `minArticles` (default 1) in `articles`,
159
+ * sorted by descending article count then declaration order.
160
+ */
161
+ export function populatedTags<K extends string>(
162
+ articles: readonly ListableArticle[],
163
+ tagMap: Readonly<Record<K, ArticleTagMeta>>,
164
+ minArticles: number = 1,
165
+ ): { tag: K; meta: ArticleTagMeta; count: number }[] {
166
+ const counts = new Map<string, number>();
167
+ for (const a of articles) {
168
+ for (const t of a.data.tags ?? []) {
169
+ counts.set(t, (counts.get(t) ?? 0) + 1);
170
+ }
171
+ }
172
+ return (Object.entries(tagMap) as [K, ArticleTagMeta][])
173
+ .map(([tag, meta]) => ({ tag, meta, count: counts.get(tag) ?? 0 }))
174
+ .filter((entry) => entry.count >= minArticles)
175
+ .sort((a, b) => b.count - a.count);
176
+ }
177
+
178
+ /** Tags that clear `MIN_INDEXABLE_TAG_ARTICLES` (`>= 4`). */
179
+ export function indexableTags<K extends string>(
180
+ articles: readonly ListableArticle[],
181
+ tagMap: Readonly<Record<K, ArticleTagMeta>>,
182
+ minIndexable: number = MIN_INDEXABLE_TAG_ARTICLES,
183
+ ): { tag: K; meta: ArticleTagMeta; count: number }[] {
184
+ return populatedTags(articles, tagMap, minIndexable);
185
+ }
186
+
187
+ /**
188
+ * Top `limit` tags across the corpus for the header "Trending Topics" sub-bar.
189
+ * Prefers indexable tags (`>= 4` articles), falling back to populated tags (`>= 1`) on smaller corpora.
190
+ */
191
+ export function topTags<K extends string>(
192
+ articles: readonly ListableArticle[],
193
+ tagMap: Readonly<Record<K, ArticleTagMeta>>,
194
+ limit: number = 6,
195
+ routes: SiteRoutes = {},
196
+ ): { tag: K; label: string; href: string; count: number }[] {
197
+ const indexable = indexableTags(articles, tagMap);
198
+ const pool = indexable.length >= Math.min(3, limit) ? indexable : populatedTags(articles, tagMap, 1);
199
+ return pool.slice(0, limit).map(({ tag, meta, count }) => ({
200
+ tag,
201
+ label: meta.label,
202
+ href: articleTagPath(tag, routes),
203
+ count,
204
+ }));
205
+ }
206
+
207
+ /**
208
+ * Top `limit` sub-tags appearing on articles in `category`, for Xataka-style topic rail quick-pills.
209
+ */
210
+ export function topCategoryTags<K extends string>(
211
+ articles: readonly ListableArticle[],
212
+ category: string,
213
+ tagMap: Readonly<Record<K, ArticleTagMeta>>,
214
+ limit: number = 4,
215
+ routes: SiteRoutes = {},
216
+ ): { tag: K; label: string; href: string; count: number }[] {
217
+ const inCat = articles.filter((a) => a.data.category === category);
218
+ return populatedTags(inCat, tagMap, 1)
219
+ .slice(0, limit)
220
+ .map(({ tag, meta, count }) => ({
221
+ tag,
222
+ label: meta.label,
223
+ href: articleTagPath(tag, routes),
224
+ count,
225
+ }));
226
+ }