@sarimarcus/content-sites-tourism 0.34.2 → 0.36.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,14 @@
2
2
 
3
3
  All packages in the platform release in lockstep; entries are per release version.
4
4
 
5
+ ## 0.36.0 (2026-10-14)
6
+
7
+ - No changes; lockstep release with ui (SLA-3084).
8
+
9
+ ## 0.35.0 (2026-10-13)
10
+
11
+ - `sections`: added `RelatedBlock`, which resolves `relatedContent` refs into cards with optional scored backfill, dedup against `excludeHrefs` and lead cards. The site's corpus, ref resolution, route table and card list come in through the `deps` prop (`RelatedBlockDeps`) (SLA-3042).
12
+
5
13
  ## 0.34.2 (2026-10-13)
6
14
 
7
15
  - No changes; lockstep release with ui (SLA-3072).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sarimarcus/content-sites-tourism",
3
- "version": "0.34.2",
3
+ "version": "0.36.0",
4
4
  "description": "City-tourism vertical: city-entity components, pages templates and utilities for the tourism sites.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -35,7 +35,7 @@
35
35
  "peerDependencies": {
36
36
  "astro": "^7.0.6",
37
37
  "tailwindcss": "^4.1.18",
38
- "@sarimarcus/content-sites-core": "0.34.2",
39
- "@sarimarcus/content-sites-ui": "0.34.2"
38
+ "@sarimarcus/content-sites-core": "0.36.0",
39
+ "@sarimarcus/content-sites-ui": "0.36.0"
40
40
  }
41
41
  }
@@ -20,6 +20,7 @@ export const LABELS = {
20
20
  landmark: 'Landmark',
21
21
  } as Record<string, string>,
22
22
  },
23
+ relatedBlock: { title: 'Related' },
23
24
  whoItsFor: { label: "Who it's for", ariaLabel: 'Related audiences and themes' },
24
25
  eventCard: {
25
26
  unescoLabel: 'UNESCO',
@@ -0,0 +1,137 @@
1
+ ---
2
+ /**
3
+ * RelatedBlock — resolves a content item's `relatedContent` refs into cards and
4
+ * renders them, optionally topped up with scored backfill.
5
+ *
6
+ * The host passes `deps` (its corpus, ref resolution, route table and card-list
7
+ * component), which read the site's collections and asset globs. The site's
8
+ * RelatedBlock adapter binds them once, so templates keep the plain props below.
9
+ *
10
+ * Backfill is opt-in via `backfillTypes`; a host that omits it renders only what
11
+ * an editor authored. A host using this as its single closer (the related-zone
12
+ * tail) passes `backfillTypes={['article', '<self-type>']}`, `cap`, and
13
+ * `excludeHrefs` from buildTakenHrefs() (core `url`): every card (lead, authored
14
+ * and backfill) is filtered against it through dedupRelated(), the one href
15
+ * normalizer, before the floor/cap arithmetic runs. With `excludeHrefs` omitted
16
+ * nothing is deduped.
17
+ */
18
+ import type { ImageMetadata } from 'astro';
19
+ import { dedupRelated, url } from '@sarimarcus/content-sites-core/url';
20
+ import type { RelatedBlockCard, RelatedBlockDeps } from './relatedBlock.ts';
21
+ import { LABELS } from '../internal/labels';
22
+
23
+ interface Props {
24
+ /** The content item's own data (needs `slug` and `relatedContent`). */
25
+ item: { slug: string; relatedContent?: { type: string; slug: string }[] };
26
+ /** The HOST item's own target type. Drives the self-reference check: without
27
+ * it a restaurant linking its own slug would render a card to the page you
28
+ * are on, and a legitimate cross-type ref to a same-slug article would be
29
+ * dropped as a self-reference. */
30
+ selfType: string;
31
+ deps: RelatedBlockDeps;
32
+ title?: string;
33
+ layout?: 'grid' | 'carousel';
34
+ columns?: 2 | 3;
35
+ class?: string;
36
+ /** Types to backfill from; the host's OWN type is legal. Backfill is
37
+ * render-time selection, not an authored ref, so it does not widen the
38
+ * relatedContent schema. Omit and only authored `relatedContent` renders. */
39
+ backfillTypes?: readonly string[];
40
+ /** Host's own audiences/themes: the overlap signal backfill scores on. */
41
+ audiences?: readonly string[];
42
+ themes?: readonly string[];
43
+ /** Topical terms (usually the host's name and slug) that outrank overlap. */
44
+ boostTerms?: readonly string[];
45
+ /** Backfill only until the block holds this many cards. */
46
+ floor?: number;
47
+ /** Hard ceiling on rendered cards, applied AFTER excludeHrefs filtering, to
48
+ * leads + authored + backfill alike. Omit and nothing is trimmed. */
49
+ cap?: number;
50
+ /** Hrefs already on the page that no card here may repeat. Members MUST be in
51
+ * normalizeHref() form: build the Set with buildTakenHrefs(). */
52
+ excludeHrefs?: Set<string>;
53
+ /** Host-supplied cards placed AHEAD of the resolved refs, for related items
54
+ * that are derived rather than authored (e.g. the guides featuring an
55
+ * entity). A lead pointing at the host page itself is dropped. */
56
+ leadItems?: readonly RelatedBlockCard[];
57
+ }
58
+
59
+ const {
60
+ item,
61
+ selfType,
62
+ deps,
63
+ title = LABELS.relatedBlock.title,
64
+ layout = 'carousel',
65
+ columns = 3,
66
+ class: className = '',
67
+ backfillTypes,
68
+ audiences = [],
69
+ themes = [],
70
+ boostTerms,
71
+ floor = 3,
72
+ cap,
73
+ excludeHrefs,
74
+ leadItems = [],
75
+ } = Astro.props;
76
+
77
+ const { RelatedContent, resolveRelated, formatUnresolved, scoreBackfillCandidates, topUpRelated, cardPath } = deps;
78
+
79
+ const { pools, refIndex, assetByPath } = await deps.getCorpus();
80
+
81
+ const pageImages = (heroImport: string): ImageMetadata | undefined =>
82
+ assetByPath.get(heroImport.replace(/^@\/assets\//, '').replace(/^\/src\/assets\//, ''));
83
+
84
+ const { items: authored, unresolved } = resolveRelated(item.relatedContent, refIndex, { selfSlug: item.slug, selfType, pageImages });
85
+ if (unresolved.length > 0) console.warn(formatUnresolved(item.slug, unresolved));
86
+
87
+ // Leads are spread in ahead of resolveRelated's self-reference drop, so guard them here.
88
+ const selfPath = cardPath(selfType, item.slug);
89
+ const selfHref = selfPath ? url(selfPath) : null;
90
+ const leads = leadItems.filter((i) => i.href !== selfHref);
91
+
92
+ // Deduped by href because a host could pass a lead card that the item ALSO authored as a ref.
93
+ const leadHrefs = new Set(leads.map((i) => i.href));
94
+ const authoredAll = [
95
+ // Type bridge: CardItem.eyebrow is optional, ResolvedRelatedItem's is required.
96
+ ...leads.map((i) => ({ ...i, eyebrow: i.eyebrow ?? '' })),
97
+ ...authored.filter((i) => !leadHrefs.has(i.href)),
98
+ ];
99
+
100
+ // An empty/omitted Set is a no-op.
101
+ const basePath = import.meta.env.BASE_URL.replace(/\/+$/, '');
102
+ const excluded = excludeHrefs ?? new Set<string>();
103
+ const authoredKept = dedupRelated(authoredAll, excluded, basePath);
104
+
105
+ // Authored refs come first; backfill only tops the block up to `floor`, and `cap` trims the merged list.
106
+ const items = backfillTypes?.length
107
+ ? topUpRelated(
108
+ authoredKept,
109
+ dedupRelated(
110
+ scoreBackfillCandidates(pools, refIndex, {
111
+ audiences,
112
+ themes,
113
+ selfSlug: item.slug,
114
+ selfType,
115
+ types: backfillTypes,
116
+ boostTerms,
117
+ }),
118
+ excluded,
119
+ basePath,
120
+ ),
121
+ { floor, cap },
122
+ )
123
+ : cap === undefined
124
+ ? authoredKept
125
+ : authoredKept.slice(0, cap);
126
+ ---
127
+
128
+ {items.length > 0 && (
129
+ <RelatedContent
130
+ title={title}
131
+ items={items}
132
+ layout={layout}
133
+ columns={columns}
134
+ variant="bordered"
135
+ class={className}
136
+ />
137
+ )}
@@ -12,6 +12,7 @@ export { default as HomeTripPlanner } from './HomeTripPlanner.astro';
12
12
  export { default as MonumentBody } from './MonumentBody.astro';
13
13
  export { default as MonumentBodySlot } from './MonumentBodySlot.astro';
14
14
  export { default as ArticleCardGrid } from './ArticleCardGrid.astro';
15
+ export { default as RelatedBlock } from './RelatedBlock.astro';
15
16
  export { default as MonumentHero } from './MonumentHero.astro';
16
17
  export { default as QuartierHero } from './QuartierHero.astro';
17
18
  export type { WalkStop } from './WalkStops.astro';
@@ -27,3 +28,4 @@ export type {
27
28
  } from './monumentBody.ts';
28
29
  export { navMonths, upcomingEventLinks } from './tourismNavigation.ts';
29
30
  export type { TourismNavigationProps, TourismNavHubLink, TourismNavMonth, TourismNavDuration } from './tourismNavigation.ts';
31
+ export type { RelatedBlockCard, RelatedBlockDeps } from './relatedBlock.ts';
@@ -0,0 +1,58 @@
1
+ import type { ImageMetadata } from 'astro';
2
+
3
+ /** A card as RelatedBlock handles it: resolved, never a path string. */
4
+ export interface RelatedBlockCard {
5
+ href: string;
6
+ title: string;
7
+ description?: string;
8
+ eyebrow?: string;
9
+ image?: ImageMetadata;
10
+ imageAlt?: string;
11
+ }
12
+
13
+ type Resolved = RelatedBlockCard & { eyebrow: string };
14
+
15
+ /**
16
+ * Everything RelatedBlock needs from the host site: its corpus, its type→route
17
+ * table and its ref resolution. These read the site's content collections and
18
+ * asset globs, which a package may not do, so the site binds them once in its
19
+ * RelatedBlock adapter.
20
+ */
21
+ export interface RelatedBlockDeps {
22
+ getCorpus(): Promise<{
23
+ pools: unknown;
24
+ refIndex: unknown;
25
+ assetByPath: Map<string, ImageMetadata>;
26
+ }>;
27
+ resolveRelated(
28
+ refs: readonly { type: string; slug: string }[] | undefined,
29
+ refIndex: any,
30
+ opts: {
31
+ selfSlug: string;
32
+ selfType: string;
33
+ pageImages: (heroImport: string) => ImageMetadata | undefined;
34
+ },
35
+ ): { items: Resolved[]; unresolved: unknown[] };
36
+ formatUnresolved(slug: string, unresolved: any): string;
37
+ scoreBackfillCandidates(
38
+ pools: any,
39
+ refIndex: any,
40
+ opts: {
41
+ audiences: readonly string[];
42
+ themes: readonly string[];
43
+ selfSlug: string;
44
+ selfType: string;
45
+ types: readonly string[];
46
+ boostTerms?: readonly string[];
47
+ },
48
+ ): Resolved[];
49
+ topUpRelated(
50
+ items: Resolved[],
51
+ candidates: readonly Resolved[],
52
+ opts: { floor?: number; cap?: number },
53
+ ): Resolved[];
54
+ /** The page path of an item of `type`, or null when the type has none. */
55
+ cardPath(type: string, slug: string): string | null;
56
+ /** The site's card-list component, taking the cards as `items`. */
57
+ RelatedContent: any;
58
+ }