@sarimarcus/content-sites-ui 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.41.0 (2026-10-20)
+
+- `editorial`: new `EraChip`, a Chip link from an article or monument to its era's section on the chronology page (`eraHref`), rendering nothing without an era; new `ChronologyTimeline`, a vertical rail of a site's eras (heading anchor, range, intro, dated entry rows, related dossiers, compact one-line markers for empty eras), with `groupByEra` and the `TimelineItem` type. No change to existing components' markup (SLA-3251).
+
+## 0.40.0 (2026-10-18)
+
+- No changes; lockstep release with core (SLA-3046).
+
 ## 0.39.0 (2026-10-16)
 
 - `layout`: new `AudienceFilters`, the sr-only `audience:<a>` Pagefind filter spans that `EntityDetailShell` and `EventPage` each wrote inline; both now render it, with identical HTML (SLA-3045).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-ui",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Universal Astro UI components, layout shell and design tokens shared by the content sites.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,6 @@
     "@lucide/astro": "^1.23.0",
     "astro": "^7.0.6",
     "tailwindcss": "^4.1.18",
-    "@sarimarcus/content-sites-core": "0.39.0"
+    "@sarimarcus/content-sites-core": "0.41.0"
   }
 }

package/src/editorial/ChronologyTimeline.astro

@@ -0,0 +1,129 @@
+---
+/**
+ * emptyEra 'hide' (default) collapses an era with no entries to a one-line rail marker that keeps `id={era.anchor}`,
+ * so eraHref() links never dead-end; 'show' renders every era in full.
+ */
+import type { EraDefinition } from '@sarimarcus/content-sites-core/eras';
+import Chip from '../primitives/Chip.astro';
+import LinkArrow from '../primitives/LinkArrow.astro';
+import ResponsivePicture from '../primitives/ResponsivePicture.astro';
+import { LABELS } from '../internal/labels';
+import type { TimelineItem } from './chronology';
+
+interface Props {
+  eras: readonly EraDefinition[];
+  /** Entries keyed by era id, already ordered (see groupByEra). */
+  items: Record<string, readonly TimelineItem[]>;
+  emptyEra?: 'hide' | 'show';
+  /** The jump links above the rail, shown when two or more eras render in full. */
+  index?: boolean;
+  indexLabel?: string;
+  dossiersLabel?: string;
+  emptyLabel?: string;
+  class?: string;
+}
+
+const {
+  eras,
+  items,
+  emptyEra = 'hide',
+  index = true,
+  indexLabel = LABELS.chronologyTimeline.indexLabel,
+  dossiersLabel = LABELS.chronologyTimeline.dossiersLabel,
+  emptyLabel = LABELS.chronologyTimeline.emptyLabel,
+  class: className,
+} = Astro.props;
+
+const ordered = [...eras].sort((a, b) => a.startYear - b.startYear);
+const rows = ordered.map((era) => {
+  const entries = items[era.id] ?? [];
+  return { era, entries, full: entries.length > 0 || emptyEra === 'show' };
+});
+const fullEras = rows.filter((r) => r.full).map((r) => r.era);
+
+if (import.meta.env.DEV) {
+  const known = new Set(eras.map((e) => e.id));
+  const orphans = Object.keys(items).filter((id) => !known.has(id) && items[id].length);
+  if (orphans.length) console.warn(`ChronologyTimeline: entries for unknown era id(s) ${orphans.join(', ')} are not rendered.`);
+}
+
+const thumbSizes = '(min-width: 640px) 128px, 64px';
+---
+
+<div class:list={['w-full', className]} data-chronology>
+  {index && fullEras.length > 1 && (
+    <nav aria-label={indexLabel} class="mb-12 md:mb-16">
+      <ol class="flex flex-wrap gap-2">
+        {fullEras.map((era) => (
+          <li><Chip href={`#${era.anchor}`} tone="outlineQuiet" accent="primary">{era.label}</Chip></li>
+        ))}
+      </ol>
+    </nav>
+  )}
+  <ol class="grid">
+    {rows.map(({ era, entries, full }) => full ? (
+      <li class="group/era grid grid-cols-[1.25rem_minmax(0,1fr)] grid-rows-[auto_auto_1fr] gap-x-4 md:grid-cols-[10rem_1.25rem_minmax(0,1fr)] md:grid-rows-[auto_1fr] md:gap-x-6" data-chronology-era={era.id}>
+        <div class="relative col-start-1 row-span-3 flex justify-center md:col-start-2 md:row-span-2 before:absolute before:inset-y-0 before:left-1/2 before:w-0.5 before:-translate-x-1/2 before:bg-foreground/15 group-first/era:before:top-3 md:group-first/era:before:top-4" aria-hidden="true">
+          <span class="relative mt-3 size-3 rotate-45 bg-primary ring-4 ring-background md:mt-4 md:size-3.5"></span>
+        </div>
+        <h2 id={era.anchor} class="col-start-2 row-start-1 scroll-mt-28 font-display text-3xl leading-tight text-balance text-foreground md:col-start-3 md:text-4xl">{era.label}</h2>
+        <p class="col-start-2 row-start-2 mt-1 font-display text-lg tabular-nums text-secondary md:col-start-1 md:row-start-1 md:row-span-2 md:mt-4 md:self-start md:sticky md:top-28 md:text-right md:text-xl md:leading-snug">{era.rangeLabel}</p>
+        <div class="col-start-2 row-start-3 pb-16 md:col-start-3 md:row-start-2 md:pb-24 group-last/era:pb-0">
+          <p class="mt-4 max-w-measure text-lg leading-relaxed text-foreground">{era.intro}</p>
+          {entries.length > 0 && (
+            <ol class="mt-8 divide-y divide-border border-y border-border">
+              {entries.map((item) => (
+                <li class="group/entry relative flex items-start gap-3 py-5 sm:gap-6">
+                  <div class="min-w-0 flex-1">
+                    <h3 class="text-lg font-semibold leading-snug text-foreground text-pretty">
+                      <a href={item.href} class="rounded-sm transition-colors group-hover/entry:text-primary focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-ring after:absolute after:inset-0">{item.title}</a>
+                    </h3>
+                    <p class="mt-1 flex flex-wrap gap-x-2 gap-y-0.5 text-sm text-muted-foreground">
+                      {item.yearLabel && <span class="tabular-nums font-medium text-foreground">{item.yearLabel}</span>}
+                      {item.yearLabel && <span aria-hidden="true">·</span>}
+                      <span>{item.kind}</span>
+                    </p>
+                    {item.description && (
+                      <p class="mt-2 line-clamp-3 max-w-measure text-base leading-relaxed text-muted-foreground sm:line-clamp-none">{item.description}</p>
+                    )}
+                  </div>
+                  {item.image && (
+                    <div class="w-16 shrink-0 overflow-hidden rounded-md bg-muted aspect-[4/3] sm:w-32">
+                      {typeof item.image === 'string' ? (
+                        <img src={item.image} alt="" width="128" height="96" loading="lazy" decoding="async" class="size-full object-cover" />
+                      ) : (
+                        <ResponsivePicture src={item.image} alt="" sizes={thumbSizes} loading="lazy" decoding="async" class="size-full object-cover" />
+                      )}
+                    </div>
+                  )}
+                </li>
+              ))}
+            </ol>
+          )}
+          {era.dossiers && era.dossiers.length > 0 && (
+            <div class="mt-8">
+              <p id={`${era.anchor}-dossiers`} class="text-sm font-semibold text-foreground">{dossiersLabel}</p>
+              <ul aria-labelledby={`${era.anchor}-dossiers`} class="mt-2 flex flex-wrap gap-x-6">
+                {era.dossiers.map((d) => (
+                  <li><LinkArrow href={d.href} color="secondary" class="min-h-11">{d.label}</LinkArrow></li>
+                ))}
+              </ul>
+            </div>
+          )}
+        </div>
+      </li>
+    ) : (
+      <li class="group/era grid grid-cols-[1.25rem_minmax(0,1fr)] gap-x-4 md:grid-cols-[10rem_1.25rem_minmax(0,1fr)] md:gap-x-6" data-chronology-era={era.id} data-chronology-empty>
+        <div class="relative col-start-1 flex justify-center md:col-start-2 before:absolute before:inset-y-0 before:left-1/2 before:w-0.5 before:-translate-x-1/2 before:bg-foreground/15 group-first/era:before:top-2" aria-hidden="true">
+          <span class="relative mt-2 size-2 rotate-45 border border-muted-foreground bg-background"></span>
+        </div>
+        <p id={era.anchor} class="col-start-2 flex scroll-mt-28 flex-wrap items-baseline gap-x-2 pb-10 text-sm text-muted-foreground md:col-start-3 group-last/era:pb-0">
+          <span class="font-display text-base text-foreground">{era.label}</span>
+          <span aria-hidden="true">·</span>
+          <span class="tabular-nums">{era.rangeLabel}</span>
+          {emptyLabel && (<><span aria-hidden="true">·</span><span>{emptyLabel}</span></>)}
+        </p>
+      </li>
+    ))}
+  </ol>
+</div>

package/src/editorial/EraChip.astro

@@ -0,0 +1,44 @@
+---
+/**
+ * EraChip — links an item to its historical era on the site's chronology hub. Placed beside the byline by the site;
+ * renders nothing when the item has no era. Visible text is `label · rangeLabel`, which must stay within the Chip
+ * 80-char ceiling (validate-badge-overflow.mjs). `basePath` falls back to core `eraHref`'s default.
+ */
+import type { EraDefinition } from '@sarimarcus/content-sites-core/eras';
+import { eraHref } from '@sarimarcus/content-sites-core/eras';
+import Chip from '../primitives/Chip.astro';
+import { LABELS } from '../internal/labels';
+
+interface Props {
+  era?: EraDefinition;
+  basePath?: string;
+  /** Accessible name; keep the visible label and range in it. */
+  ariaLabel?: (era: EraDefinition) => string;
+  icon?: string;
+  class?: string;
+}
+
+const {
+  era,
+  basePath,
+  ariaLabel = (e: EraDefinition) => LABELS.eraChip.ariaLabel(e.label, e.rangeLabel),
+  icon = 'history',
+  class: className,
+}: Props = Astro.props;
+---
+
+{era && (
+  <Chip
+    as="a"
+    href={eraHref(era, basePath)}
+    size="md"
+    tone="tint"
+    accent="primary"
+    icon={icon}
+    data-era={era.id}
+    aria-label={ariaLabel(era)}
+    class={className}
+  >
+    {era.label}<span aria-hidden="true">·</span><span class="whitespace-nowrap tabular-nums">{era.rangeLabel}</span>
+  </Chip>
+)}

package/src/editorial/chronology.ts

@@ -0,0 +1,45 @@
+import type { ImageMetadata } from 'astro';
+
+/** One entry on a ChronologyTimeline era. `kind` and `yearLabel` are site copy, rendered verbatim. */
+export interface TimelineItem {
+  title: string;
+  href: string;
+  kind: string;
+  yearLabel?: string;
+  description?: string;
+  /** Decorative (alt=""): the row's title link names the entry. */
+  image?: ImageMetadata | string;
+}
+
+/**
+ * Groups entries by era id and orders each group by year (entries without a year last), then by title. Entries whose
+ * era is undefined are dropped. The input is not mutated.
+ */
+export function groupByEra<T>(
+  entries: readonly T[],
+  getEra: (entry: T) => string | undefined,
+  getYear: (entry: T) => number | undefined,
+  getTitle: (entry: T) => string = (entry) => {
+    const e = entry as { title?: unknown; data?: { title?: unknown; name?: unknown } };
+    return String(e?.title ?? e?.data?.title ?? e?.data?.name ?? '');
+  },
+): Record<string, T[]> {
+  const groups: Record<string, T[]> = {};
+  for (const entry of entries) {
+    const era = getEra(entry);
+    if (!era) continue;
+    (groups[era] ??= []).push(entry);
+  }
+  for (const list of Object.values(groups)) {
+    list.sort((a, b) => {
+      const ya = getYear(a), yb = getYear(b);
+      if (ya !== yb) {
+        if (ya === undefined) return 1;
+        if (yb === undefined) return -1;
+        return ya - yb;
+      }
+      return getTitle(a).localeCompare(getTitle(b), 'en');
+    });
+  }
+  return groups;
+}

package/src/editorial/index.ts

@@ -21,8 +21,11 @@ export type { AuthorSummary, ArticleSummary, KeyFact, ArticleCategoryLink, Artic
 export { default as InsiderTips } from './InsiderTips.astro';
 export type { InsiderTip, InsiderTipAuthor, InsiderTipKinds, InsiderTipTone } from './types';
 export { default as AuthorStrip } from './AuthorStrip.astro';
+export { default as EraChip } from './EraChip.astro';
 export { default as AlsoExplore } from './AlsoExplore.astro';
 export { default as VisitTiming } from './VisitTiming.astro';
+export { default as ChronologyTimeline } from './ChronologyTimeline.astro';
+export { groupByEra, type TimelineItem } from './chronology';
 export type { AlsoExploreItem } from './AlsoExplore.astro';
 export type { VisitTimingData } from './VisitTiming.astro';
 export { default as AnswerBox } from './interludes/AnswerBox.astro';

package/src/internal/labels.ts

@@ -72,6 +72,7 @@ export const LABELS = {
   alsoExplore: { eyebrow: 'Also explore' },
   articleCategoryNav: { ariaLabel: 'Browse articles by topic', allLabel: 'All' },
   articleFeatureCard: { readLabel: 'Read article', updatedLabel: 'Updated' },
+  eraChip: { ariaLabel: (label: string, range: string) => `${label}, ${range}: see this era on the chronology` },
   articleTopicPager: {
     heading: (topic: string) => `Next in ${topic}`,
     newerLabel: 'Newer',
@@ -99,4 +100,9 @@ export const LABELS = {
     newTabLabel: '(opens in a new tab)',
   },
   breadcrumb: { homeLabel: 'Home', ariaLabel: 'Breadcrumb navigation' },
+  chronologyTimeline: {
+    indexLabel: 'Eras',
+    dossiersLabel: 'Go deeper',
+    emptyLabel: '',
+  },
 };