@sarimarcus/content-sites-ui 0.60.6 → 0.62.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 +16 -0
- package/package.json +2 -2
- package/src/composed/FAQ.astro +12 -2
- package/src/composed/faq-anchors.ts +16 -0
- package/src/composed/faq-target.ts +15 -0
- package/src/composed/index.ts +1 -0
- package/src/editorial/ArticleEmbed.astro +70 -0
- package/src/editorial/ArticlePage.astro +35 -2
- package/src/editorial/HubBridge.astro +33 -0
- package/src/editorial/HubNumbers.astro +38 -0
- package/src/editorial/HubQuestions.astro +38 -0
- package/src/editorial/HubSources.astro +30 -0
- package/src/editorial/hub-blocks.ts +158 -0
- package/src/editorial/hub-questions.ts +63 -0
- package/src/editorial/index.ts +7 -0
- package/src/internal/labels.ts +8 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
All packages in the platform release in lockstep; entries are per release version.
|
|
4
4
|
|
|
5
|
+
## 0.62.0 (2026-11-08)
|
|
6
|
+
|
|
7
|
+
Additive (SLA-3977); output of existing pages is unchanged except three new utility classes in the CSS bundle.
|
|
8
|
+
|
|
9
|
+
- `ArticlePage`: renders `sections[].embeds[]` through the new `ArticleEmbed`, a click-to-load facade (thumbnail from `i.ytimg.com`, a `youtube-nocookie.com` iframe only after the click). Sites need `https://www.youtube-nocookie.com` in `frame-src`; all five already have it.
|
|
10
|
+
- Labels: `articleEmbed.playLabel` and `privacyNote` (en, it).
|
|
11
|
+
|
|
12
|
+
## 0.61.0 (2026-11-08)
|
|
13
|
+
|
|
14
|
+
Topic hub blocks (SLA-3969, SLA-3975, epic SLA-3968). Additive: no prop is removed or retyped. One markup change on every article page: FAQ items carry stable ids (below); everything else renders only where a site opts in.
|
|
15
|
+
|
|
16
|
+
- New `HubNumbers`, `HubSources`, `HubBridge` (editorial): a topic hub's key figures, primary sources and related hubs, promoted from curiosity-engineering-it. Each root carries `data-hub-block`; headings default to en/it labels and take props. `HubBridge` uses `ArrowLabel`.
|
|
17
|
+
- New `HubQuestions` (editorial): FAQ questions from a hub's articles as chips linking to their answers; links only, no FAQPage. Pick them with `hubQuestions()` (one per article, at most two per opening word, questions over 80 characters skipped for the chip cap).
|
|
18
|
+
- New helpers (editorial): `statFacts` (with `exclude`), `hubBridge` (shared tags), `hubLinkBridge` (cross-category `relatedContent` links), `sourceAuthorities` (citation count, or hub specificity with `siteArticles`: an authority every hub cites only fills leftover places), `resolveArticleLinks`.
|
|
19
|
+
- `ArticlePage`: each FAQ `<details>` gets an id from `faqAnchorIds()` (`faq-<question slug>`, exported from composed and editorial) plus the page's section scroll margin, and the page opens the item a `#faq-…` link targets. `FAQ` (composed): new optional `itemIds` and `itemScrollMarginClass`; without `itemIds` it renders as in 0.60.6 (`tests/fixtures/render-diff/sla-3975-faq-no-ids.json`).
|
|
20
|
+
|
|
5
21
|
## 0.60.6 (2026-11-07)
|
|
6
22
|
|
|
7
23
|
Hub pages can drop the category row, and the Sotto Scocca audit's package fixes land (SLA-3942). Default markup is unchanged for the hub prop (`render-diff` against 0.60.5 is identical for the topic hub, the paged topic page and the tag page: `tests/fixtures/render-diff/hub-category-nav-default.json`, `article-nav-routes-default.json`); the markup changes below are intended.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sarimarcus/content-sites-ui",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.62.0",
|
|
4
4
|
"description": "Universal Astro UI components, layout shell and design tokens shared by the content sites.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -51,6 +51,6 @@
|
|
|
51
51
|
"@lucide/astro": "^1.23.0",
|
|
52
52
|
"astro": "^7.0.6",
|
|
53
53
|
"tailwindcss": "^4.1.18",
|
|
54
|
-
"@sarimarcus/content-sites-core": "0.
|
|
54
|
+
"@sarimarcus/content-sites-core": "0.62.0"
|
|
55
55
|
}
|
|
56
56
|
}
|
package/src/composed/FAQ.astro
CHANGED
|
@@ -23,6 +23,10 @@ interface Props {
|
|
|
23
23
|
/** Replaces the title's classes. */
|
|
24
24
|
headingClass?: string;
|
|
25
25
|
id?: string;
|
|
26
|
+
/** One id per item, in order. The page opens the item a `#<id>` link targets (openFaqTarget from faq-target.ts). */
|
|
27
|
+
itemIds?: readonly string[];
|
|
28
|
+
/** Scroll offset under the sticky header for an item with an id (default: scroll-mt-28, ArticlePage's). */
|
|
29
|
+
itemScrollMarginClass?: string;
|
|
26
30
|
locale?: string;
|
|
27
31
|
class?: string;
|
|
28
32
|
}
|
|
@@ -33,6 +37,8 @@ const {
|
|
|
33
37
|
icon = true,
|
|
34
38
|
headingClass = 'text-2xl sm:text-3xl font-normal mb-6 flex items-center gap-3 font-display',
|
|
35
39
|
id,
|
|
40
|
+
itemIds,
|
|
41
|
+
itemScrollMarginClass = 'scroll-mt-28',
|
|
36
42
|
class: className = '',
|
|
37
43
|
} = Astro.props;
|
|
38
44
|
---
|
|
@@ -46,8 +52,12 @@ const {
|
|
|
46
52
|
</h2>
|
|
47
53
|
)}
|
|
48
54
|
<div class="space-y-4">
|
|
49
|
-
{items.map((item) => (
|
|
50
|
-
<details
|
|
55
|
+
{items.map((item, i) => (
|
|
56
|
+
<details
|
|
57
|
+
id={itemIds?.[i]}
|
|
58
|
+
class:list={['group p-6 bg-card rounded-xl border border-border hover:border-primary/50 open:border-primary/50 transition-colors', itemIds?.[i] && itemScrollMarginClass]}
|
|
59
|
+
data-faq-track
|
|
60
|
+
>
|
|
51
61
|
<summary class="flex items-center justify-between cursor-pointer list-none">
|
|
52
62
|
<h3 class="text-base font-medium group-hover:text-primary transition-colors pr-4" set:html={item.questionHtml} />
|
|
53
63
|
<svg
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { slugify, stripMarkdown } from '@sarimarcus/content-sites-core/text';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Stable ids for an article's FAQ items, in order: `faq-<question slug>`, a `-2`, `-3` suffix on a repeat. The article
|
|
5
|
+
* page and the topic hub both call this on the same list, so a hub link always lands on its question.
|
|
6
|
+
*/
|
|
7
|
+
export function faqAnchorIds(questions: readonly string[]): string[] {
|
|
8
|
+
const issued = new Set<string>();
|
|
9
|
+
return questions.map((q, i) => {
|
|
10
|
+
const base = `faq-${slugify(stripMarkdown(q)).slice(0, 60).replace(/-+$/, '') || i + 1}`;
|
|
11
|
+
let id = base;
|
|
12
|
+
for (let n = 2; issued.has(id); n++) id = `${base}-${n}`;
|
|
13
|
+
issued.add(id);
|
|
14
|
+
return id;
|
|
15
|
+
});
|
|
16
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/** Opens the FAQ `<details>` the URL hash names, so a hub link lands on an expanded answer. */
|
|
2
|
+
export function openFaqTarget(): void {
|
|
3
|
+
let id: string;
|
|
4
|
+
try {
|
|
5
|
+
id = decodeURIComponent(location.hash.slice(1));
|
|
6
|
+
} catch {
|
|
7
|
+
return;
|
|
8
|
+
}
|
|
9
|
+
if (!id) return;
|
|
10
|
+
const el = document.getElementById(id);
|
|
11
|
+
if (el instanceof HTMLDetailsElement && !el.open) {
|
|
12
|
+
el.open = true;
|
|
13
|
+
el.scrollIntoView({ block: 'start' });
|
|
14
|
+
}
|
|
15
|
+
}
|
package/src/composed/index.ts
CHANGED
|
@@ -4,6 +4,7 @@ export type { TableOfContentsItem } from './tocItem.ts';
|
|
|
4
4
|
export { default as CardCarousel } from './CardCarousel.astro';
|
|
5
5
|
export { default as QuickFacts } from './QuickFacts.astro';
|
|
6
6
|
export { default as FAQ } from './FAQ.astro';
|
|
7
|
+
export { faqAnchorIds } from './faq-anchors';
|
|
7
8
|
export { default as InlineImage } from './InlineImage.astro';
|
|
8
9
|
export { default as Pagination } from './Pagination.astro';
|
|
9
10
|
export { default as EntityCard } from './EntityCard.astro';
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
/**
|
|
3
|
+
* ArticleEmbed — a YouTube video placed between article paragraphs (SLA-3977). Renders a click-to-load facade: a
|
|
4
|
+
* thumbnail link that costs no iframe, no cookie and no layout shift until the reader plays it, then swaps in a
|
|
5
|
+
* youtube-nocookie.com iframe. Without JS the facade is a plain link to the video.
|
|
6
|
+
*/
|
|
7
|
+
import type { TrustedHtml } from '../types/index.ts';
|
|
8
|
+
import Icon from '../primitives/Icon.astro';
|
|
9
|
+
import { getLabels } from '../internal/labels';
|
|
10
|
+
|
|
11
|
+
interface Props {
|
|
12
|
+
/** The 11-character YouTube video id. */
|
|
13
|
+
id: string;
|
|
14
|
+
/** Names the video: the iframe title and the facade's accessible label. */
|
|
15
|
+
title: string;
|
|
16
|
+
/** Caption below the video, already rendered by the site (inline HTML, it sits inside a <p>). */
|
|
17
|
+
captionHtml?: TrustedHtml;
|
|
18
|
+
locale?: string;
|
|
19
|
+
class?: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const { id, title, captionHtml, locale, class: className } = Astro.props;
|
|
23
|
+
const l = getLabels(locale ?? Astro.currentLocale).articleEmbed;
|
|
24
|
+
const watchUrl = `https://www.youtube.com/watch?v=${id}`;
|
|
25
|
+
const thumbUrl = `https://i.ytimg.com/vi/${id}/hqdefault.jpg`;
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
<figure data-article-embed data-embed-id={id} data-embed-title={title} class:list={['not-prose my-8 overflow-hidden rounded-2xl border border-border/50', className]}>
|
|
29
|
+
<div class="relative aspect-video bg-black">
|
|
30
|
+
<a
|
|
31
|
+
href={watchUrl}
|
|
32
|
+
data-article-embed-play
|
|
33
|
+
aria-label={`${l.playLabel}: ${title}`}
|
|
34
|
+
class="group absolute inset-0 block focus:outline-none focus-visible:ring-2 focus-visible:ring-primary"
|
|
35
|
+
>
|
|
36
|
+
<img src={thumbUrl} alt="" width="480" height="360" loading="lazy" decoding="async" class="absolute inset-0 h-full w-full object-cover" />
|
|
37
|
+
<span class="absolute inset-0 flex items-center justify-center">
|
|
38
|
+
<span class="flex h-16 w-16 items-center justify-center rounded-full bg-black/70 text-white motion-safe:transition-transform motion-safe:group-hover:scale-110">
|
|
39
|
+
<Icon name="play" class="h-7 w-7" filled />
|
|
40
|
+
</span>
|
|
41
|
+
</span>
|
|
42
|
+
<span class="absolute inset-x-0 bottom-0 bg-black/70 px-4 py-2 text-xs text-white">{l.privacyNote}</span>
|
|
43
|
+
</a>
|
|
44
|
+
</div>
|
|
45
|
+
{captionHtml && (
|
|
46
|
+
<figcaption class="bg-muted/30 px-4 py-3">
|
|
47
|
+
<p class="font-display text-sm font-medium text-foreground/80" set:html={captionHtml} />
|
|
48
|
+
</figcaption>
|
|
49
|
+
)}
|
|
50
|
+
</figure>
|
|
51
|
+
|
|
52
|
+
<script>
|
|
53
|
+
document.addEventListener('click', (event) => {
|
|
54
|
+
const link = (event.target as Element | null)?.closest<HTMLAnchorElement>('[data-article-embed-play]');
|
|
55
|
+
if (!link || event.metaKey || event.ctrlKey || event.shiftKey) return;
|
|
56
|
+
const figure = link.closest<HTMLElement>('[data-article-embed]');
|
|
57
|
+
const id = figure?.dataset.embedId;
|
|
58
|
+
if (!figure || !id) return;
|
|
59
|
+
event.preventDefault();
|
|
60
|
+
const iframe = document.createElement('iframe');
|
|
61
|
+
iframe.src = `https://www.youtube-nocookie.com/embed/${id}?autoplay=1&rel=0&playsinline=1`;
|
|
62
|
+
iframe.title = figure.dataset.embedTitle ?? '';
|
|
63
|
+
iframe.allow = 'autoplay; encrypted-media; picture-in-picture; fullscreen';
|
|
64
|
+
iframe.allowFullscreen = true;
|
|
65
|
+
iframe.referrerPolicy = 'strict-origin-when-cross-origin';
|
|
66
|
+
iframe.className = 'absolute inset-0 h-full w-full border-0';
|
|
67
|
+
link.replaceWith(iframe);
|
|
68
|
+
iframe.focus();
|
|
69
|
+
});
|
|
70
|
+
</script>
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
import type { ImageMetadata } from 'astro';
|
|
9
9
|
import type { EraDefinition } from '@sarimarcus/content-sites-core/eras';
|
|
10
10
|
import { splitParagraphs, renderInlineMarkdown } from '@sarimarcus/content-sites-core/articles';
|
|
11
|
+
import type { ArticleEmbedProvider } from '@sarimarcus/content-sites-core/articles';
|
|
11
12
|
import { slugify, parseMarkdownInline } from '@sarimarcus/content-sites-core/text';
|
|
12
13
|
import { routePath, type SiteRoutes } from '@sarimarcus/content-sites-core/url';
|
|
13
14
|
import Container from '../layout/Container.astro';
|
|
@@ -18,7 +19,9 @@ import ArticleMetadata from '../seo/ArticleMetadata.astro';
|
|
|
18
19
|
import AuthoritativeSources from '../seo/AuthoritativeSources.astro';
|
|
19
20
|
import type { ArticleAuthor, BreadcrumbItem, DomainClassifier, SourceInput } from '../seo/types';
|
|
20
21
|
import TableOfContents from '../composed/TableOfContents.astro';
|
|
22
|
+
import ArticleEmbed from './ArticleEmbed.astro';
|
|
21
23
|
import FAQ from '../composed/FAQ.astro';
|
|
24
|
+
import { faqAnchorIds } from '../composed/faq-anchors';
|
|
22
25
|
import InlineImage from '../composed/InlineImage.astro';
|
|
23
26
|
import RelatedContent from '../composed/RelatedContent.astro';
|
|
24
27
|
import type { RelatedItem } from '../composed/related';
|
|
@@ -60,6 +63,7 @@ export interface ArticlePageSection {
|
|
|
60
63
|
interludes?: readonly any[];
|
|
61
64
|
inlineImages?: readonly { slug: string; alt: string; caption?: string; afterParagraph: number }[];
|
|
62
65
|
affiliateCarousels?: readonly { ids?: number[]; afterParagraph: number; heading?: string }[];
|
|
66
|
+
embeds?: readonly { provider: ArticleEmbedProvider; id: string; title: string; caption?: string; afterParagraph: number }[];
|
|
63
67
|
}
|
|
64
68
|
|
|
65
69
|
export interface ArticlePageData {
|
|
@@ -248,13 +252,15 @@ const faqItems = (article.faqs ?? []).map((f) => ({
|
|
|
248
252
|
questionHtml: trustedHtml(parseMarkdownInline(f.question, basePath)),
|
|
249
253
|
answerHtml: trustedHtml(parseMarkdownInline(f.answer, basePath, sourcesLen)),
|
|
250
254
|
}));
|
|
255
|
+
const faqIds = faqAnchorIds((article.faqs ?? []).map((f) => f.question));
|
|
251
256
|
|
|
252
257
|
type BodyBlock =
|
|
253
258
|
| { kind: 'paragraph'; html: string }
|
|
254
259
|
| { kind: 'interlude'; data: InterludeData }
|
|
255
260
|
| { kind: 'entity'; card: ArticlePageResolvedCard }
|
|
256
261
|
| { kind: 'image'; image: { slug: string; alt: string; caption?: string; afterParagraph: number }; meta: ImageMetadata }
|
|
257
|
-
| { kind: 'affiliate-carousel'; carousel: { ids?: number[]; afterParagraph: number; heading?: string } }
|
|
262
|
+
| { kind: 'affiliate-carousel'; carousel: { ids?: number[]; afterParagraph: number; heading?: string } }
|
|
263
|
+
| { kind: 'embed'; embed: { id: string; title: string; caption?: string; afterParagraph: number } };
|
|
258
264
|
|
|
259
265
|
function buildSectionBlocks(section: ArticlePageSection): BodyBlock[] {
|
|
260
266
|
const paragraphs = splitParagraphs(section.body, basePath, sourcesLen);
|
|
@@ -262,6 +268,7 @@ function buildSectionBlocks(section: ArticlePageSection): BodyBlock[] {
|
|
|
262
268
|
const interludes = section.interludes ?? [];
|
|
263
269
|
const images = section.inlineImages ?? [];
|
|
264
270
|
const carousels = section.affiliateCarousels ?? [];
|
|
271
|
+
const embeds = section.embeds ?? [];
|
|
265
272
|
|
|
266
273
|
const pushInterlude = (il: any) => {
|
|
267
274
|
if (il.type === 'related-card' || il.type === 'monument-feature' || il.type === 'article-feature') {
|
|
@@ -293,6 +300,10 @@ function buildSectionBlocks(section: ArticlePageSection): BodyBlock[] {
|
|
|
293
300
|
blocks.push({ kind: 'affiliate-carousel', carousel: c });
|
|
294
301
|
}
|
|
295
302
|
}
|
|
303
|
+
|
|
304
|
+
for (const e of embeds) {
|
|
305
|
+
if (e.afterParagraph === idx) blocks.push({ kind: 'embed', embed: e });
|
|
306
|
+
}
|
|
296
307
|
});
|
|
297
308
|
|
|
298
309
|
for (const il of interludes) {
|
|
@@ -314,6 +325,10 @@ function buildSectionBlocks(section: ArticlePageSection): BodyBlock[] {
|
|
|
314
325
|
}
|
|
315
326
|
}
|
|
316
327
|
|
|
328
|
+
for (const e of embeds) {
|
|
329
|
+
if (e.afterParagraph >= paragraphs.length) blocks.push({ kind: 'embed', embed: e });
|
|
330
|
+
}
|
|
331
|
+
|
|
317
332
|
for (const il of interludes) {
|
|
318
333
|
if (il.type === 'tldr' || ('position' in il && il.position === 'end')) {
|
|
319
334
|
pushInterlude(il);
|
|
@@ -517,6 +532,16 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
|
|
|
517
532
|
</div>
|
|
518
533
|
);
|
|
519
534
|
}
|
|
535
|
+
if (block.kind === 'embed') {
|
|
536
|
+
return (
|
|
537
|
+
<ArticleEmbed
|
|
538
|
+
id={block.embed.id}
|
|
539
|
+
title={block.embed.title}
|
|
540
|
+
captionHtml={block.embed.caption ? md(block.embed.caption) : undefined}
|
|
541
|
+
locale={locale}
|
|
542
|
+
/>
|
|
543
|
+
);
|
|
544
|
+
}
|
|
520
545
|
return null;
|
|
521
546
|
})}
|
|
522
547
|
|
|
@@ -537,7 +562,7 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
|
|
|
537
562
|
|
|
538
563
|
{faqItems.length > 0 && (
|
|
539
564
|
<div class="mt-12 pt-8 border-t border-border">
|
|
540
|
-
<FAQ items={faqItems} id="faq" locale={locale} />
|
|
565
|
+
<FAQ items={faqItems} id="faq" itemIds={faqIds} itemScrollMarginClass={sectionScrollMarginClass} locale={locale} />
|
|
541
566
|
</div>
|
|
542
567
|
)}
|
|
543
568
|
|
|
@@ -603,3 +628,11 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
|
|
|
603
628
|
</Container>
|
|
604
629
|
</article>
|
|
605
630
|
</main>
|
|
631
|
+
|
|
632
|
+
<script>
|
|
633
|
+
import { openFaqTarget } from '../composed/faq-target.ts';
|
|
634
|
+
|
|
635
|
+
window.addEventListener('hashchange', openFaqTarget);
|
|
636
|
+
document.addEventListener('astro:page-load', openFaqTarget);
|
|
637
|
+
openFaqTarget();
|
|
638
|
+
</script>
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
/**
|
|
3
|
+
* HubBridge — other topic hubs worth visiting from this one, each with a short reason. Pick them with hubBridge()
|
|
4
|
+
* (shared tags) or hubLinkBridge() (editorial links); the site writes the reason line.
|
|
5
|
+
*/
|
|
6
|
+
import ArrowLabel from '../primitives/ArrowLabel.astro';
|
|
7
|
+
|
|
8
|
+
interface Props {
|
|
9
|
+
heading: string;
|
|
10
|
+
items: readonly { label: string; href: string; reason: string }[];
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
const { heading, items } = Astro.props;
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
{items.length > 0 && (
|
|
17
|
+
<section class="mt-12" aria-labelledby="hub-bridge-h" data-hub-block="bridge">
|
|
18
|
+
<h2 id="hub-bridge-h" class="text-xl font-semibold font-display text-foreground mb-4">{heading}</h2>
|
|
19
|
+
<ul role="list" class="grid gap-4 sm:grid-cols-2">
|
|
20
|
+
{items.map((item) => (
|
|
21
|
+
<li>
|
|
22
|
+
<a
|
|
23
|
+
href={item.href}
|
|
24
|
+
class="group block rounded-xl border border-border bg-card p-5 hover:border-primary transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
|
|
25
|
+
>
|
|
26
|
+
<ArrowLabel class="font-semibold text-foreground">{item.label}</ArrowLabel>
|
|
27
|
+
<span class="mt-1 block text-sm text-muted-foreground">{item.reason}</span>
|
|
28
|
+
</a>
|
|
29
|
+
</li>
|
|
30
|
+
))}
|
|
31
|
+
</ul>
|
|
32
|
+
</section>
|
|
33
|
+
)}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
/**
|
|
3
|
+
* HubNumbers — a topic hub's key figures, one per article, each linking to its article. Pick them with statFacts().
|
|
4
|
+
*/
|
|
5
|
+
import { getLabels } from '../internal/labels';
|
|
6
|
+
|
|
7
|
+
interface Props {
|
|
8
|
+
facts: readonly { figure: string; label: string; href: string; title: string }[];
|
|
9
|
+
/** Renders nothing below this many facts (default 2). */
|
|
10
|
+
min?: number;
|
|
11
|
+
heading?: string;
|
|
12
|
+
locale?: string;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
const { facts, min = 2 } = Astro.props;
|
|
16
|
+
const labels = getLabels(Astro.props.locale ?? Astro.currentLocale).hubNumbers;
|
|
17
|
+
const heading = Astro.props.heading ?? labels.heading(facts.length);
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
{facts.length >= min && (
|
|
21
|
+
<section class="mb-12" aria-labelledby="hub-numbers-h" data-hub-block="numbers">
|
|
22
|
+
<h2 id="hub-numbers-h" class="text-xl font-semibold font-display text-foreground mb-4">{heading}</h2>
|
|
23
|
+
<ul role="list" class="grid gap-4 sm:grid-cols-3">
|
|
24
|
+
{facts.map((f) => (
|
|
25
|
+
<li>
|
|
26
|
+
<a
|
|
27
|
+
href={f.href}
|
|
28
|
+
class="block h-full rounded-xl border border-border bg-card p-5 hover:border-primary transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
|
|
29
|
+
>
|
|
30
|
+
<span class="block font-display text-3xl font-semibold text-foreground leading-none">{f.figure}</span>
|
|
31
|
+
<span class="mt-2 block text-sm text-foreground">{f.label}</span>
|
|
32
|
+
<span class="mt-3 block text-xs text-muted-foreground">{labels.fromArticle} {f.title}</span>
|
|
33
|
+
</a>
|
|
34
|
+
</li>
|
|
35
|
+
))}
|
|
36
|
+
</ul>
|
|
37
|
+
</section>
|
|
38
|
+
)}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
---
|
|
2
|
+
/**
|
|
3
|
+
* HubQuestions — a topic hub's "Questions this topic answers": FAQ questions from its articles, each linking to its
|
|
4
|
+
* answer on the article page. Links only, never FAQPage markup (the hub's own FAQ keeps that schema). Pick the items
|
|
5
|
+
* with hubQuestions(); the site builds each href from the slug and anchor.
|
|
6
|
+
*/
|
|
7
|
+
import Chip from '../primitives/Chip.astro';
|
|
8
|
+
import { getLabels } from '../internal/labels';
|
|
9
|
+
|
|
10
|
+
interface Props {
|
|
11
|
+
items: readonly { question: string; href: string }[];
|
|
12
|
+
heading?: string;
|
|
13
|
+
/** Renders nothing below this many items (default 3). */
|
|
14
|
+
min?: number;
|
|
15
|
+
locale?: string;
|
|
16
|
+
class?: string;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const {
|
|
20
|
+
items,
|
|
21
|
+
heading = getLabels(Astro.props.locale ?? Astro.currentLocale).hubQuestions.heading,
|
|
22
|
+
min = 3,
|
|
23
|
+
class: className = 'mt-12',
|
|
24
|
+
} = Astro.props;
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
{items.length >= min && (
|
|
28
|
+
<section class={className} aria-labelledby="hub-questions-h" data-hub-block="questions">
|
|
29
|
+
<h2 id="hub-questions-h" class="text-xl font-semibold font-display text-foreground mb-4">{heading}</h2>
|
|
30
|
+
<ul role="list" class="flex flex-wrap gap-3">
|
|
31
|
+
{items.map((q) => (
|
|
32
|
+
<li>
|
|
33
|
+
<Chip href={q.href} size="md" tone="outline" accent="primary" text="inherit" weight="inherit">{q.question}</Chip>
|
|
34
|
+
</li>
|
|
35
|
+
))}
|
|
36
|
+
</ul>
|
|
37
|
+
</section>
|
|
38
|
+
)}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
/**
|
|
3
|
+
* HubSources — the primary authorities a topic hub's articles cite. Pick them with sourceAuthorities().
|
|
4
|
+
*/
|
|
5
|
+
import { getLabels } from '../internal/labels';
|
|
6
|
+
|
|
7
|
+
interface Props {
|
|
8
|
+
authorities: readonly { label: string; count: number }[];
|
|
9
|
+
heading?: string;
|
|
10
|
+
lead?: string;
|
|
11
|
+
locale?: string;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
const { authorities } = Astro.props;
|
|
15
|
+
const labels = getLabels(Astro.props.locale ?? Astro.currentLocale).hubSources;
|
|
16
|
+
const heading = Astro.props.heading ?? labels.heading;
|
|
17
|
+
const lead = Astro.props.lead ?? labels.lead;
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
{authorities.length > 0 && (
|
|
21
|
+
<section class="mt-12" aria-labelledby="hub-sources-h" data-hub-block="sources">
|
|
22
|
+
<h2 id="hub-sources-h" class="text-xl font-semibold font-display text-foreground mb-3">{heading}</h2>
|
|
23
|
+
<p class="text-base text-muted-foreground">
|
|
24
|
+
{lead}
|
|
25
|
+
{authorities.map((a, i) => (
|
|
26
|
+
<Fragment><span class="text-foreground font-medium">{a.label}</span>{i < authorities.length - 1 ? ' · ' : '.'}</Fragment>
|
|
27
|
+
))}
|
|
28
|
+
</p>
|
|
29
|
+
</section>
|
|
30
|
+
)}
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
// Pure selection logic for the topic hub blocks (Numbers, Sources, Bridge). Structural types only, so it runs under
|
|
2
|
+
// plain Node for tests.
|
|
3
|
+
import { outboundHostKey } from '@sarimarcus/content-sites-core/url';
|
|
4
|
+
|
|
5
|
+
export interface HubFact {
|
|
6
|
+
figure: string;
|
|
7
|
+
label: string;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
interface Source {
|
|
11
|
+
url?: string;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export interface HubArticle {
|
|
15
|
+
data: {
|
|
16
|
+
slug: string;
|
|
17
|
+
category?: string | null;
|
|
18
|
+
tags?: readonly string[];
|
|
19
|
+
keyFacts?: readonly HubFact[];
|
|
20
|
+
sources?: readonly (Source | string)[];
|
|
21
|
+
relatedContent?: readonly { type?: string; slug?: string }[];
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** Up to `limit` key facts from distinct articles, shortest figure first; `exclude` slugs are skipped. */
|
|
26
|
+
export function statFacts<A extends HubArticle>(
|
|
27
|
+
articles: readonly A[],
|
|
28
|
+
{ limit = 3, exclude = [] as readonly string[] } = {},
|
|
29
|
+
): { article: A; fact: HubFact }[] {
|
|
30
|
+
const skip = new Set(exclude);
|
|
31
|
+
return articles
|
|
32
|
+
.filter((a) => !skip.has(a.data.slug))
|
|
33
|
+
.flatMap((a) => {
|
|
34
|
+
const fact = [...(a.data.keyFacts ?? [])].sort((x, y) => x.figure.length - y.figure.length)[0];
|
|
35
|
+
return fact ? [{ article: a, fact }] : [];
|
|
36
|
+
})
|
|
37
|
+
.sort((x, y) => x.fact.figure.length - y.fact.figure.length)
|
|
38
|
+
.slice(0, limit);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Other topic hubs to suggest from `category`, ranked by tags shared with it, ignoring tags present in `maxSpread`
|
|
43
|
+
* or more categories (they link everything to everything). Each comes with the shared tags as its reason.
|
|
44
|
+
*/
|
|
45
|
+
export function hubBridge(
|
|
46
|
+
articles: readonly HubArticle[],
|
|
47
|
+
category: string,
|
|
48
|
+
{ maxSpread = 4, limit = 2 } = {},
|
|
49
|
+
): { category: string; tags: string[] }[] {
|
|
50
|
+
const tagsByCategory = new Map<string, Set<string>>();
|
|
51
|
+
for (const a of articles) {
|
|
52
|
+
if (!a.data.category) continue;
|
|
53
|
+
const set = tagsByCategory.get(a.data.category) ?? new Set<string>();
|
|
54
|
+
for (const t of a.data.tags ?? []) set.add(t);
|
|
55
|
+
tagsByCategory.set(a.data.category, set);
|
|
56
|
+
}
|
|
57
|
+
const spread = new Map<string, number>();
|
|
58
|
+
for (const set of tagsByCategory.values()) for (const t of set) spread.set(t, (spread.get(t) ?? 0) + 1);
|
|
59
|
+
const own = tagsByCategory.get(category) ?? new Set<string>();
|
|
60
|
+
return [...tagsByCategory.entries()]
|
|
61
|
+
.filter(([c]) => c !== category)
|
|
62
|
+
.map(([c, set]) => ({ category: c, tags: [...set].filter((t) => own.has(t) && (spread.get(t) ?? 0) < maxSpread).sort() }))
|
|
63
|
+
.filter((b) => b.tags.length > 0)
|
|
64
|
+
.sort((x, y) => y.tags.length - x.tags.length || x.category.localeCompare(y.category))
|
|
65
|
+
.slice(0, limit);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Other topic hubs to suggest from `category`, ranked by editorial links between them: relatedContent article links
|
|
70
|
+
* from this hub's articles to theirs, and from theirs to this hub's. `links` counts distinct article pairs.
|
|
71
|
+
*/
|
|
72
|
+
export function hubLinkBridge(
|
|
73
|
+
articles: readonly HubArticle[],
|
|
74
|
+
category: string,
|
|
75
|
+
{ limit = 2, minLinks = 1 } = {},
|
|
76
|
+
): { category: string; links: number }[] {
|
|
77
|
+
const categoryOf = new Map(articles.map((a) => [a.data.slug, a.data.category ?? null]));
|
|
78
|
+
const pairs = new Map<string, Set<string>>();
|
|
79
|
+
for (const a of articles) {
|
|
80
|
+
for (const r of a.data.relatedContent ?? []) {
|
|
81
|
+
if (r.type !== 'article' || !r.slug) continue;
|
|
82
|
+
const from = a.data.category;
|
|
83
|
+
const to = categoryOf.get(r.slug);
|
|
84
|
+
if (!from || !to || from === to || (from !== category && to !== category)) continue;
|
|
85
|
+
const other = from === category ? to : from;
|
|
86
|
+
const key = [a.data.slug, r.slug].sort().join('|');
|
|
87
|
+
const set = pairs.get(other) ?? new Set<string>();
|
|
88
|
+
set.add(key);
|
|
89
|
+
pairs.set(other, set);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
return [...pairs.entries()]
|
|
93
|
+
.map(([c, set]) => ({ category: c, links: set.size }))
|
|
94
|
+
.filter((b) => b.links >= minLinks)
|
|
95
|
+
.sort((x, y) => y.links - x.links || x.category.localeCompare(y.category))
|
|
96
|
+
.slice(0, limit);
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
function sourceHost(s: Source | string): string | null {
|
|
100
|
+
try {
|
|
101
|
+
return outboundHostKey(new URL(typeof s === 'string' ? s : (s.url ?? '')).hostname);
|
|
102
|
+
} catch {
|
|
103
|
+
return null;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function labelCounts(articles: readonly HubArticle[], labels: Readonly<Record<string, string>>): Map<string, number> {
|
|
108
|
+
const byDomain = new Map(Object.entries(labels).map(([d, label]) => [outboundHostKey(d), label]));
|
|
109
|
+
const domains = [...byDomain.keys()].sort((a, b) => b.length - a.length);
|
|
110
|
+
const counts = new Map<string, number>();
|
|
111
|
+
for (const a of articles) {
|
|
112
|
+
for (const s of a.data.sources ?? []) {
|
|
113
|
+
const host = sourceHost(s);
|
|
114
|
+
const domain = host && domains.find((d) => host === d || host.endsWith(`.${d}`));
|
|
115
|
+
if (!domain) continue;
|
|
116
|
+
const label = byDomain.get(domain)!;
|
|
117
|
+
counts.set(label, (counts.get(label) ?? 0) + 1);
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
return counts;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Labelled primary authorities cited by a hub's `articles`; unlisted hosts are dropped. With `siteArticles`, ranked
|
|
125
|
+
* by how specific each is to this hub (citations here × log(categories / categories citing it)), so an authority every
|
|
126
|
+
* hub cites only fills leftover places; without it, by citation count. Ties fall back to citation count.
|
|
127
|
+
*/
|
|
128
|
+
export function sourceAuthorities(
|
|
129
|
+
articles: readonly HubArticle[],
|
|
130
|
+
labels: Readonly<Record<string, string>>,
|
|
131
|
+
{ limit = 6, siteArticles }: { limit?: number; siteArticles?: readonly HubArticle[] } = {},
|
|
132
|
+
): { label: string; count: number }[] {
|
|
133
|
+
const counts = labelCounts(articles, labels);
|
|
134
|
+
let weight = (_label: string) => 1;
|
|
135
|
+
if (siteArticles) {
|
|
136
|
+
const byCategory = new Map<string, HubArticle[]>();
|
|
137
|
+
for (const a of siteArticles) {
|
|
138
|
+
if (!a.data.category) continue;
|
|
139
|
+
const group = byCategory.get(a.data.category);
|
|
140
|
+
if (group) group.push(a);
|
|
141
|
+
else byCategory.set(a.data.category, [a]);
|
|
142
|
+
}
|
|
143
|
+
const spread = new Map<string, number>();
|
|
144
|
+
for (const group of byCategory.values()) for (const label of labelCounts(group, labels).keys()) spread.set(label, (spread.get(label) ?? 0) + 1);
|
|
145
|
+
const total = Math.max(byCategory.size, 1);
|
|
146
|
+
weight = (label) => Math.log(total / Math.max(spread.get(label) ?? 1, 1));
|
|
147
|
+
}
|
|
148
|
+
return [...counts.entries()]
|
|
149
|
+
.map(([label, count]) => ({ label, count, score: count * weight(label) }))
|
|
150
|
+
.sort((x, y) => y.score - x.score || y.count - x.count || x.label.localeCompare(y.label))
|
|
151
|
+
.slice(0, limit)
|
|
152
|
+
.map(({ label, count }) => ({ label, count }));
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Hub prose links articles as `href="article:<slug>"`, so the site's routes decide the URL; this resolves them. */
|
|
156
|
+
export function resolveArticleLinks(html: string, hrefOf: (slug: string) => string): string {
|
|
157
|
+
return html.replace(/href="article:([^"]+)"/g, (_, slug: string) => `href="${hrefOf(slug)}"`);
|
|
158
|
+
}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { stripMarkdown } from '@sarimarcus/content-sites-core/text';
|
|
2
|
+
import { faqAnchorIds } from '../composed/faq-anchors.ts';
|
|
3
|
+
|
|
4
|
+
export interface HubQuestionSource {
|
|
5
|
+
slug: string;
|
|
6
|
+
faqs?: readonly { question: string }[];
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
export interface HubQuestion {
|
|
10
|
+
/** The article's slug; the site's routes build the URL. */
|
|
11
|
+
slug: string;
|
|
12
|
+
/** Plain text, markdown stripped. */
|
|
13
|
+
question: string;
|
|
14
|
+
/** The FAQ item's id on the article page, without '#'. */
|
|
15
|
+
anchor: string;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
function opener(question: string): string {
|
|
19
|
+
return question.trim().split(/\s+/)[0].toLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Up to `limit` FAQ questions for a topic hub: at most one per article, in input order, and at most `maxPerOpener`
|
|
24
|
+
* sharing an opening word ("How", "What"...) until no article is left that would vary them. Questions over
|
|
25
|
+
* `maxLength` characters are skipped: they render as chips, which the badge-overflow push gate caps at 80.
|
|
26
|
+
*/
|
|
27
|
+
export function hubQuestions(
|
|
28
|
+
articles: readonly HubQuestionSource[],
|
|
29
|
+
{ limit = 6, maxPerOpener = 2, maxLength = 80, exclude = [] as readonly string[] } = {},
|
|
30
|
+
): HubQuestion[] {
|
|
31
|
+
const skip = new Set(exclude);
|
|
32
|
+
const candidates = articles
|
|
33
|
+
.filter((a) => !skip.has(a.slug) && (a.faqs?.length ?? 0) > 0)
|
|
34
|
+
.map((a) => {
|
|
35
|
+
const questions = a.faqs!.map((f) => f.question);
|
|
36
|
+
const anchors = faqAnchorIds(questions);
|
|
37
|
+
const items = questions
|
|
38
|
+
.map((q, i) => ({ question: stripMarkdown(q).trim(), anchor: anchors[i] }))
|
|
39
|
+
.filter((it) => it.question && it.question.length <= maxLength);
|
|
40
|
+
return { slug: a.slug, items };
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
const picked: HubQuestion[] = [];
|
|
44
|
+
const used = new Set<string>();
|
|
45
|
+
const openers = new Map<string, number>();
|
|
46
|
+
const take = (slug: string, item: { question: string; anchor: string }) => {
|
|
47
|
+
picked.push({ slug, ...item });
|
|
48
|
+
used.add(slug);
|
|
49
|
+
const o = opener(item.question);
|
|
50
|
+
openers.set(o, (openers.get(o) ?? 0) + 1);
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
for (const c of candidates) {
|
|
54
|
+
if (picked.length >= limit) break;
|
|
55
|
+
const item = c.items.find((it) => (openers.get(opener(it.question)) ?? 0) < maxPerOpener);
|
|
56
|
+
if (item) take(c.slug, item);
|
|
57
|
+
}
|
|
58
|
+
for (const c of candidates) {
|
|
59
|
+
if (picked.length >= limit) break;
|
|
60
|
+
if (!used.has(c.slug) && c.items[0]) take(c.slug, c.items[0]);
|
|
61
|
+
}
|
|
62
|
+
return picked;
|
|
63
|
+
}
|
package/src/editorial/index.ts
CHANGED
|
@@ -46,6 +46,13 @@ export { default as EraTimelineNav } from './EraTimelineNav.astro';
|
|
|
46
46
|
export { default as PeopleTimeline } from './PeopleTimeline.astro';
|
|
47
47
|
export { layoutPeopleTimeline, footstepLinks, type PeopleTimelineEntry, type PeopleTimelineDot, type PeopleTimelineSegment } from './people-timeline';
|
|
48
48
|
export { monogram } from './monogram';
|
|
49
|
+
export { default as HubQuestions } from './HubQuestions.astro';
|
|
50
|
+
export { hubQuestions, type HubQuestion, type HubQuestionSource } from './hub-questions';
|
|
51
|
+
export { faqAnchorIds } from '../composed/faq-anchors';
|
|
52
|
+
export { default as HubNumbers } from './HubNumbers.astro';
|
|
53
|
+
export { default as HubSources } from './HubSources.astro';
|
|
54
|
+
export { default as HubBridge } from './HubBridge.astro';
|
|
55
|
+
export { statFacts, hubBridge, hubLinkBridge, sourceAuthorities, resolveArticleLinks, type HubArticle, type HubFact } from './hub-blocks';
|
|
49
56
|
export type { AlsoExploreItem } from './AlsoExplore.astro';
|
|
50
57
|
export type { VisitTimingData } from './VisitTiming.astro';
|
|
51
58
|
export { default as AnswerBox } from './interludes/AnswerBox.astro';
|
package/src/internal/labels.ts
CHANGED
|
@@ -66,6 +66,9 @@ export const LABELS = {
|
|
|
66
66
|
nextLabel: (name: string | undefined) => `Next, ${name ?? 'carousel'}`,
|
|
67
67
|
},
|
|
68
68
|
faq: { title: 'Frequently asked questions' },
|
|
69
|
+
hubQuestions: { heading: 'Questions this topic answers' },
|
|
70
|
+
hubNumbers: { heading: (n: number) => (n === 1 ? 'In one number' : `In ${n} numbers`), fromArticle: 'From the article:' },
|
|
71
|
+
hubSources: { heading: 'Sources for this topic', lead: 'Based on primary sources: ' },
|
|
69
72
|
pagination: {
|
|
70
73
|
ariaLabel: 'Pagination',
|
|
71
74
|
previousLabel: 'Previous',
|
|
@@ -81,6 +84,7 @@ export const LABELS = {
|
|
|
81
84
|
alsoExplore: { eyebrow: 'Also explore' },
|
|
82
85
|
articleCategoryNav: { ariaLabel: 'Browse articles by topic', allLabel: 'All' },
|
|
83
86
|
articleFeatureCard: { readLabel: 'Read article', updatedLabel: 'Updated' },
|
|
87
|
+
articleEmbed: { playLabel: 'Play video', privacyNote: 'Loads YouTube when you play' },
|
|
84
88
|
articleCardGrid: { readLabel: 'Read', updatedLabel: 'Updated', minutesSuffix: 'min' },
|
|
85
89
|
articleHubSection: { moreLabel: 'See all' },
|
|
86
90
|
articleTagPage: {
|
|
@@ -322,6 +326,9 @@ export const LABELS_IT: typeof LABELS = {
|
|
|
322
326
|
nextLabel: (name: string | undefined) => `Successivo, ${name ?? 'carosello'}`,
|
|
323
327
|
},
|
|
324
328
|
faq: { title: 'Domande frequenti' },
|
|
329
|
+
hubQuestions: { heading: 'Le domande di questa sezione' },
|
|
330
|
+
hubNumbers: { heading: (n: number) => (n === 1 ? 'In un numero' : `In ${n} numeri`), fromArticle: 'Dall’articolo:' },
|
|
331
|
+
hubSources: { heading: 'Fonti di questa sezione', lead: 'Basato su fonti primarie: ' },
|
|
325
332
|
pagination: {
|
|
326
333
|
ariaLabel: 'Paginazione',
|
|
327
334
|
previousLabel: 'Precedente',
|
|
@@ -337,6 +344,7 @@ export const LABELS_IT: typeof LABELS = {
|
|
|
337
344
|
alsoExplore: { eyebrow: 'Esplora anche' },
|
|
338
345
|
articleCategoryNav: { ariaLabel: 'Sfoglia gli articoli per argomento', allLabel: 'Tutti' },
|
|
339
346
|
articleFeatureCard: { readLabel: 'Leggi l’articolo', updatedLabel: 'Aggiornato' },
|
|
347
|
+
articleEmbed: { playLabel: 'Riproduci il video', privacyNote: 'Carica YouTube quando lo riproduci' },
|
|
340
348
|
articleCardGrid: { readLabel: 'Leggi', updatedLabel: 'Aggiornato', minutesSuffix: 'min' },
|
|
341
349
|
articleHubSection: { moreLabel: 'Vedi tutti' },
|
|
342
350
|
articleTagPage: {
|