@sarimarcus/content-sites-ui 0.41.2 → 0.41.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.41.3 (2026-10-21)
+
+- `editorial`: new `PersonChip` (a Chip link to a historical figure's page, name and life dates), `PersonCard` (an `EntityCard` poster teaser with portrait, dates, role badges and a clamped description) and `PersonPage` (the person page shell: portrait, roles, name, dates with the `EraChip`, short bio, "Read the full story" link to the primary article, places to see and related reading as `RelatedContentGrid`s, a `fallbackSrc` prop for a string `image`, and the era on a `ChronologyTimeline`; slots `breadcrumb`, `before-body`, `after-body`, `tail`). Copy defaults live in `LABELS.personChip`, `personCard` and `personPage`. No change to existing components' markup (SLA-3260).
+- `composed`: new `RelatedContentGrid` (the cards-only responsive grid of `RelatedContent`, no heading, surface or carousel CSS); `RelatedContent` renders it for `layout="grid"` with identical HTML.
+- `primitives`: `Badge` gains `tone="outline"` (bordered, muted fill); the role and expertise pills of `PersonCard`, `PersonPage` and `AuthorCard` share it through an internal `RoleBadge`, with `AuthorCard`'s markup unchanged. `PersonPage` now requires `imageAlt` whenever `image` or `fallbackSrc` is set.
+
 ## 0.41.2 (2026-10-21)
 
 - `editorial`: `ChronologyTimeline`'s era index is now `TableOfContents` (card variant) instead of a row of chips: a collapsed jump list on mobile, a sticky bar once the index scrolls away, and the era in view marked with `data-active` / `aria-current`. The era anchor ids move from the era heading to its `<li>`, so the scrollspy follows the whole era and the sticky bar hides after the last one. Its markup changes on every page that renders the timeline (SLA-3274).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-ui",
-  "version": "0.41.2",
+  "version": "0.41.3",
   "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.41.2"
+    "@sarimarcus/content-sites-core": "0.41.3"
   }
 }

package/src/composed/RelatedContent.astro

@@ -7,6 +7,7 @@ import ArrowLabel from '../primitives/ArrowLabel.astro';
 import SectionDivider from '../primitives/SectionDivider.astro';
 import CardCarousel from './CardCarousel.astro';
 import RelatedContentCard from './RelatedContentCard.astro';
+import RelatedContentGrid from './RelatedContentGrid.astro';
 import type { RelatedItem } from './related';
 
 interface Props {
@@ -61,10 +62,6 @@ const wrapperClass = variant === 'bordered'
     ? ''
     : 'p-6 bg-muted/50 rounded-xl border border-border';
 
-const gridClass = columns === 3
-  ? 'grid gap-4 sm:grid-cols-2 lg:grid-cols-3'
-  : 'grid gap-4 sm:grid-cols-2';
-
 // At `lg` a card fits `columns` per view, so the track stops overflowing and the controls hide. Percentages, not
 // fixed widths: the block usually sits inside a ~700px prose column. Below `lg` cards are wider than a column share
 // so the next one peeks in.
@@ -72,13 +69,9 @@ const cardWidthClass = columns === 3
   ? 'w-[80vw] sm:w-64 lg:w-[calc((100%-2rem)/3)]'
   : 'w-[85vw] sm:w-80 lg:w-[calc((100%-1rem)/2)]';
 
-const pictureSizes = pictureSizesProp ?? (layout === 'carousel'
-  ? (columns === 3
-      ? '(min-width: 1024px) 240px, (min-width: 640px) 256px, 80vw'
-      : '(min-width: 640px) 320px, 85vw')
-  : (columns === 3
-      ? '(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 100vw'
-      : '(min-width: 640px) 50vw, 100vw'));
+const carouselPictureSizes = pictureSizesProp ?? (columns === 3
+  ? '(min-width: 1024px) 240px, (min-width: 640px) 256px, 80vw'
+  : '(min-width: 640px) 320px, 85vw');
 
 // CardCarousel's contract: every direct child of the track is one card with `snap-start shrink-0` and a width.
 const carouselShell = `shrink-0 snap-start ${cardWidthClass}`;
@@ -101,7 +94,7 @@ const carouselShell = `shrink-0 snap-start ${cardWidthClass}`;
           <RelatedContentCard
             item={item}
             shellClass={carouselShell}
-            pictureSizes={pictureSizes}
+            pictureSizes={carouselPictureSizes}
             trackingBlock={trackingBlock}
           />
         ))}
@@ -121,15 +114,12 @@ const carouselShell = `shrink-0 snap-start ${cardWidthClass}`;
     )}
 
     {layout !== 'carousel' && (
-      <div class={gridClass}>
-        {items.map((item) => (
-          <RelatedContentCard
-            item={item}
-            pictureSizes={pictureSizes}
-            trackingBlock={trackingBlock}
-          />
-        ))}
-      </div>
+      <RelatedContentGrid
+        items={items}
+        columns={columns}
+        pictureSizes={pictureSizesProp}
+        trackingBlock={trackingBlock}
+      />
     )}
   </Wrapper>
 )}

package/src/composed/RelatedContentGrid.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * RelatedContentGrid — related link cards as a responsive grid, with no heading, surface or carousel. `RelatedContent`
+ * renders it for `layout="grid"`; a page that owns its own heading uses it directly.
+ */
+import RelatedContentCard from './RelatedContentCard.astro';
+import type { RelatedItem } from './related';
+
+interface Props {
+  items: readonly RelatedItem[];
+  columns?: 2 | 3;
+  trackingBlock?: string;
+  /** Image `sizes`; the defaults match the column count in a ~700px prose column. */
+  pictureSizes?: string;
+}
+
+const { items, columns = 2, trackingBlock, pictureSizes: pictureSizesProp } = Astro.props;
+
+const gridClass = columns === 3
+  ? 'grid gap-4 sm:grid-cols-2 lg:grid-cols-3'
+  : 'grid gap-4 sm:grid-cols-2';
+
+const pictureSizes = pictureSizesProp ?? (columns === 3
+  ? '(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 100vw'
+  : '(min-width: 640px) 50vw, 100vw');
+---
+
+<div class={gridClass}>
+  {items.map((item) => (
+    <RelatedContentCard item={item} pictureSizes={pictureSizes} trackingBlock={trackingBlock} />
+  ))}
+</div>

package/src/composed/index.ts

@@ -10,4 +10,6 @@ export { default as EntityCard } from './EntityCard.astro';
 export { default as ArrowLinkGrid } from './ArrowLinkGrid.astro';
 // RelatedContent sits here, not in ./editorial: it renders CardCarousel, whose <style> ships to every importer of the barrel.
 export { default as RelatedContent } from './RelatedContent.astro';
-export { default as RelatedContentCard } from './RelatedContentCard.astro';export type { RelatedItem, RelatedTone } from './related';
+export { default as RelatedContentCard } from './RelatedContentCard.astro';
+export { default as RelatedContentGrid } from './RelatedContentGrid.astro';
+export type { RelatedItem, RelatedTone } from './related';

package/src/editorial/AuthorCard.astro

@@ -4,7 +4,7 @@
  * (`href`), a centred polaroid portrait (`polaroid`), or a plain card with a profile link. `roleLabel` is free text
  * whose meaning is the caller's: a job title on one page, "Curated by" on another.
  */
-import Badge from '../primitives/Badge.astro';
+import RoleBadge from './RoleBadge.astro';
 import LinkArrow from '../primitives/LinkArrow.astro';
 import ArrowLabel from '../primitives/ArrowLabel.astro';
 
@@ -79,9 +79,9 @@ const Heading = `h${headingLevel}` as 'h2' | 'h3';
 
       <div class="mt-5 flex flex-wrap gap-2">
         {expertise.map((topic) => (
-          <Badge tone="custom" toneClass="border bg-muted/50 text-foreground" size="md" lines={0} class="border-border">
+          <RoleBadge>
             {topic}
-          </Badge>
+          </RoleBadge>
         ))}
       </div>
 
@@ -123,9 +123,9 @@ const Heading = `h${headingLevel}` as 'h2' | 'h3';
 
         <div class="mt-5 flex flex-wrap justify-center gap-2 lg:justify-start">
           {expertise.map((topic) => (
-            <Badge tone="custom" toneClass="border bg-muted/50 text-foreground" size="md" lines={0} class="border-border">
+            <RoleBadge>
               {topic}
-            </Badge>
+            </RoleBadge>
           ))}
         </div>
 
@@ -159,9 +159,9 @@ const Heading = `h${headingLevel}` as 'h2' | 'h3';
 
     <div class="mt-5 flex flex-wrap gap-2">
       {expertise.map((topic) => (
-        <Badge tone="custom" toneClass="border bg-muted/50 text-foreground" size="md" lines={0} class="border-border">
+        <RoleBadge>
           {topic}
-        </Badge>
+        </RoleBadge>
       ))}
     </div>
 

package/src/editorial/PersonCard.astro

@@ -0,0 +1,74 @@
+---
+/**
+ * PersonCard — a historical figure's teaser card on EntityCard's poster frame: portrait, name, life dates, role
+ * labels and a clamped description. Every string arrives as a prop (roles are the site's display labels); `ctaLabel`
+ * falls back to LABELS. Without `image` or `fallbackSrc` the image block stays an empty placeholder.
+ */
+import type { ImageMetadata } from 'astro';
+import EntityCard from '../composed/EntityCard.astro';
+import RoleBadge from './RoleBadge.astro';
+import ArrowLabel from '../primitives/ArrowLabel.astro';
+import { LABELS } from '../internal/labels';
+
+interface Props {
+  href: string;
+  name: string;
+  image?: ImageMetadata;
+  fallbackSrc?: string;
+  imageAlt: string;
+  /** Life dates as displayed, e.g. core `formatLifeDates`. */
+  dates?: string;
+  roles?: readonly string[];
+  description?: string;
+  ctaLabel?: string;
+  headingLevel?: 2 | 3;
+  index?: number;
+  eager?: number;
+  sizes?: string;
+  class?: string;
+}
+
+const {
+  href,
+  name,
+  image,
+  fallbackSrc,
+  imageAlt,
+  dates,
+  roles = [],
+  description,
+  ctaLabel = LABELS.personCard.cta,
+  headingLevel = 3,
+  index,
+  eager,
+  sizes,
+  class: className,
+} = Astro.props;
+
+const Heading = `h${headingLevel}` as 'h2' | 'h3';
+---
+
+<EntityCard
+  href={href}
+  variant="poster"
+  image={image}
+  fallbackSrc={fallbackSrc}
+  imageAlt={imageAlt}
+  index={index}
+  eager={eager}
+  sizes={sizes}
+  footerJustify="end"
+  class={className}
+>
+  <Heading class="text-xl font-display font-semibold text-foreground">{name}</Heading>
+  {dates && <p class="mt-1 text-sm tabular-nums text-muted-foreground">{dates}</p>}
+  {roles.length > 0 && (
+    <div class="mt-3 flex flex-wrap gap-2">
+      {roles.map((role) => (
+        <RoleBadge>{role}</RoleBadge>
+      ))}
+    </div>
+  )}
+  {description && <p class="mt-3 text-sm leading-relaxed text-muted-foreground line-clamp-3">{description}</p>}
+  <ArrowLabel slot="footer-cta" class="text-sm font-medium text-primary">{ctaLabel}</ArrowLabel>
+</EntityCard>

package/src/editorial/PersonChip.astro

@@ -0,0 +1,44 @@
+---
+/**
+ * PersonChip — links an item to a historical figure's page. Visible text is `name` and, when given, the life `dates`
+ * (core `formatLifeDates`), within the Chip 80-char ceiling (validate-badge-overflow.mjs). Renders nothing without
+ * a name or an href.
+ */
+import Chip from '../primitives/Chip.astro';
+import { LABELS } from '../internal/labels';
+
+interface Props {
+  name?: string;
+  href?: string;
+  dates?: string;
+  /** Accessible name; keep the visible name and dates in it. */
+  ariaLabel?: (name: string, dates?: string) => string;
+  icon?: string;
+  class?: string;
+}
+
+const {
+  name,
+  href,
+  dates,
+  ariaLabel = LABELS.personChip.ariaLabel,
+  icon = 'user',
+  class: className,
+}: Props = Astro.props;
+---
+
+{name && href && (
+  <Chip
+    as="a"
+    href={href}
+    size="md"
+    tone="tint"
+    accent="primary"
+    icon={icon}
+    data-person-chip
+    aria-label={ariaLabel(name, dates)}
+    class={className}
+  >
+    {name}{dates && (<><span aria-hidden="true">·</span><span class="whitespace-nowrap tabular-nums">{dates}</span></>)}
+  </Chip>
+)}

package/src/editorial/PersonPage.astro

@@ -0,0 +1,167 @@
+---
+/**
+ * PersonPage — the shell and shared body of a historical figure's page. The route keeps paths, data, SEO and schema
+ * (core `historicalPersonSchema`), renders markdown to `bioHtml`, and wraps this template in the site Layout. Order:
+ * portrait and roles, name, life dates with the era chip, the short bio, "Read the full story" to the person's
+ * primary article, places to see and related reading (`RelatedContentGrid`, not `RelatedContent`: the person page
+ * owns its headings and `RelatedContent` carries the carousel CSS), then the era on a ChronologyTimeline. Every string
+ * is a prop or a LABELS default; a block with no data renders nothing. Slots:
+ *   breadcrumb  — the site Breadcrumb, in the band under the header.
+ *   before-body — site blocks between the header and the bio.
+ *   after-body  — site blocks after the bio and the full-story link.
+ *   tail        — full-width blocks after the column.
+ */
+import type { ImageMetadata } from 'astro';
+import type { EraDefinition } from '@sarimarcus/content-sites-core/eras';
+import Container from '../layout/Container.astro';
+import BreadcrumbBand from '../layout/BreadcrumbBand.astro';
+import RoleBadge from './RoleBadge.astro';
+import LinkArrow from '../primitives/LinkArrow.astro';
+import ResponsivePicture from '../primitives/ResponsivePicture.astro';
+import RelatedContentGrid from '../composed/RelatedContentGrid.astro';
+import type { RelatedItem } from '../composed/related';
+import type { TrustedHtml } from '../types';
+import EraChip from './EraChip.astro';
+import ChronologyTimeline from './ChronologyTimeline.astro';
+import type { TimelineItem } from './chronology';
+import { LABELS } from '../internal/labels';
+
+type PersonImage =
+  | { image?: undefined; fallbackSrc?: undefined; imageAlt?: string }
+  | {
+      image: ImageMetadata;
+      /** Plain path when the collection stores `image` as a string (no asset import). */
+      fallbackSrc?: string;
+      imageAlt: string;
+    }
+  | { image?: ImageMetadata; fallbackSrc: string; imageAlt: string };
+
+type Props = PersonImage & {
+  name: string;
+  /** Life dates as displayed, e.g. core `formatLifeDates`. */
+  dates?: string;
+  /** Role labels as displayed. */
+  roles?: readonly string[];
+  era?: EraDefinition;
+  eraBasePath?: string;
+  bioHtml: TrustedHtml;
+  /** Prose modifiers after `prose`. */
+  proseClass?: string;
+  /** The person's primary article; `label` falls back to LABELS. */
+  fullStory?: { href: string; label?: string };
+  places?: readonly RelatedItem[];
+  placesHeading?: string;
+  readMore?: readonly RelatedItem[];
+  readMoreHeading?: string;
+  /** The era in context: pass the person's era only, or the whole chronology. */
+  timeline?: { eras: readonly EraDefinition[]; items: Record<string, readonly TimelineItem[]>; heading?: string };
+  pagefindType?: string;
+};
+
+const {
+  name,
+  dates,
+  roles = [],
+  image,
+  fallbackSrc,
+  imageAlt,
+  era,
+  eraBasePath,
+  bioHtml,
+  proseClass = 'prose-lg',
+  fullStory,
+  places = [],
+  placesHeading = LABELS.personPage.placesHeading,
+  readMore = [],
+  readMoreHeading = LABELS.personPage.readMoreHeading,
+  timeline,
+  pagefindType = 'person',
+} = Astro.props;
+
+const timelineHeading = timeline?.heading ?? LABELS.personPage.timelineHeading;
+const hasTimeline = timeline && Object.values(timeline.items).some((list) => list.length > 0);
+---
+
+<BreadcrumbBand>
+  <slot name="breadcrumb" />
+</BreadcrumbBand>
+
+<main class="pt-6 pb-12 lg:pt-8 lg:pb-20" data-person-page>
+  <div data-pagefind-body data-pagefind-meta={`type:${pagefindType}`}>
+    <Container size="measure">
+      <header class="flex flex-col gap-6 sm:flex-row sm:items-start">
+        {(image || fallbackSrc) && (
+          <div class="w-40 shrink-0 overflow-hidden rounded-xl bg-muted aspect-[4/5] sm:w-48">
+            {image ? (
+              <ResponsivePicture
+                src={image}
+                alt={imageAlt}
+                sizes="(min-width: 640px) 192px, 160px"
+                loading="eager"
+                fetchpriority="high"
+                decoding="async"
+                class="size-full object-cover"
+              />
+            ) : (
+              <img
+                src={fallbackSrc}
+                alt={imageAlt}
+                loading="eager"
+                fetchpriority="high"
+                decoding="async"
+                class="size-full object-cover"
+              />
+            )}
+          </div>
+        )}
+        <div class="min-w-0">
+          {roles.length > 0 && (
+            <div class="mb-3 flex flex-wrap gap-2">
+              {roles.map((role) => (
+                <RoleBadge>{role}</RoleBadge>
+              ))}
+            </div>
+          )}
+          <h1 class="font-display text-4xl leading-tight text-balance text-foreground">{name}</h1>
+          {(dates || era) && (
+            <div class="mt-3 flex flex-wrap items-center gap-x-4 gap-y-2">
+              {dates && <p class="font-display text-xl tabular-nums text-secondary" data-person-dates>{dates}</p>}
+              <EraChip era={era} basePath={eraBasePath} />
+            </div>
+          )}
+        </div>
+      </header>
+
+      <slot name="before-body" />
+
+      <div class={`prose ${proseClass} mt-10 max-w-none`} data-person-bio set:html={bioHtml} />
+
+      {fullStory && (
+        <p class="mt-6">
+          <LinkArrow href={fullStory.href} size="base">{fullStory.label ?? LABELS.personPage.readFullStory}</LinkArrow>
+        </p>
+      )}
+
+      <slot name="after-body" />
+
+      {[
+        { id: 'places', heading: placesHeading, items: places },
+        { id: 'read-more', heading: readMoreHeading, items: readMore },
+      ].map((group) => group.items.length > 0 && (
+        <section class="mt-12" aria-labelledby={`person-${group.id}`} data-person-section={group.id}>
+          <h2 id={`person-${group.id}`} class="mb-6 text-2xl font-display font-semibold text-foreground">{group.heading}</h2>
+          <RelatedContentGrid items={group.items} />
+        </section>
+      ))}
+    </Container>
+  </div>
+
+  {timeline && hasTimeline && (
+    <Container size="content" class="mt-16">
+      <h2 class="mb-8 font-display text-2xl font-semibold text-foreground">{timelineHeading}</h2>
+      <ChronologyTimeline eras={timeline.eras} items={timeline.items} index={false} />
+    </Container>
+  )}
+
+  <slot name="tail" />
+</main>

package/src/editorial/RoleBadge.astro

@@ -0,0 +1,6 @@
+---
+// The outlined label for a role or an area of expertise (person and author cards, person page).
+import Badge from '../primitives/Badge.astro';
+---
+
+<Badge tone="outline" size="md" lines={0}><slot /></Badge>

package/src/editorial/index.ts

@@ -22,6 +22,9 @@ 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 PersonChip } from './PersonChip.astro';
+export { default as PersonCard } from './PersonCard.astro';
+export { default as PersonPage } from './PersonPage.astro';
 export { default as AlsoExplore } from './AlsoExplore.astro';
 export { default as VisitTiming } from './VisitTiming.astro';
 export { default as ChronologyTimeline } from './ChronologyTimeline.astro';

package/src/internal/labels.ts

@@ -73,6 +73,14 @@ export const LABELS = {
   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` },
+  personChip: { ariaLabel: (name: string, dates?: string) => `${name}${dates ? `, ${dates}` : ''}: read their profile` },
+  personCard: { cta: 'Read the profile' },
+  personPage: {
+    readFullStory: 'Read the full story',
+    placesHeading: 'Places to see',
+    readMoreHeading: 'Read more',
+    timelineHeading: 'In their time',
+  },
   articleTopicPager: {
     heading: (topic: string) => `Next in ${topic}`,
     newerLabel: 'Newer',

package/src/primitives/Badge.astro

@@ -31,7 +31,7 @@ import { PILL_BASE } from './pillRecipe';
 // Extends the span attributes so call sites can pass id / aria-* / data-* / slot through.
 interface Props extends Omit<HTMLAttributes<'span'>, 'class'> {
   /** Preset color. Use `custom` + `toneClass` for runtime category/type color maps. */
-  tone?: BrandTone | 'neutral' | 'onImage' | 'custom';
+  tone?: BrandTone | 'neutral' | 'outline' | 'onImage' | 'custom';
   /** Color classes for tone="custom" (e.g. typeColors[type]). */
   toneClass?: string;
   size?: 'sm' | 'md' | 'lg';
@@ -72,6 +72,7 @@ const tones = {
   secondary: 'bg-secondary text-secondary-foreground',
   accent: 'bg-accent-tint text-accent-emphasis',
   neutral: 'bg-muted text-muted-foreground',
+  outline: 'border bg-muted/50 text-foreground border-border',
   onImage: 'bg-badge-on-image text-badge-on-image-foreground backdrop-blur-sm',
   custom: '',
 } as const;