@sarimarcus/content-sites-ui 0.57.1 → 0.58.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.58.0 (2026-11-05)
6
+
7
+ Opt-in editorial article head (SLA-3889). Defaults keep today's markup: `render-diff` against 0.57.1 is byte-identical for `ArticlePage` (no hero and the default head), `ContentHero` `rail` and `TableOfContents` `card` and `plain`.
8
+
9
+ - `ArticlePage`: `headVariant` (`standard` default | `editorial`). `editorial` is a Verge-style reading layout: the `rail` hero (byline and share in a left rail, category chip, headline, deck, photo with caption), a "back" link replacing the breadcrumb below `sm`, the lede without its left rule and with the drop cap on, near-black `text-lg sm:text-xl` body paragraphs, and the section list in a sticky side column from 1360px (below that the card ToC stays). New `categoryChip` (`{ label, href? }`) and `rail` slot (extra rail content under the byline); `article.imageCaption` is the photo caption. The headline scale reads `--article-title-size`, `--article-title-size-sm` and `--article-title-size-lg` (defaults 1.875, 2.5 and 3rem).
10
+ - `ContentHero`: `caption` slot (`rail` only, rendered under the photo as `data-hero-caption`), `titleClass`, `mediaClass` and `compact` (`rail` only: replace the headline size classes, replace the photo's aspect-ratio classes, tighter vertical rhythm).
11
+ - `TableOfContents`: `variant="margin"`, a vertical list of section links (`data-section-link`, so the scroll-spy marks the section in view) with no mini bar and no mobile disclosure.
12
+
5
13
  ## 0.57.1 (2026-11-05)
6
14
 
7
15
  Theming hooks and opt-in variants for the editorial listing, author and article pages (SLA-3887). Defaults keep today's markup apart from the hooks and fixes listed under "Output changes".
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sarimarcus/content-sites-ui",
3
- "version": "0.57.1",
3
+ "version": "0.58.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.57.1"
54
+ "@sarimarcus/content-sites-core": "0.58.0"
55
55
  }
56
56
  }
@@ -26,7 +26,8 @@ interface Props {
26
26
  eyebrowClass?: string;
27
27
  /** Extra classes on the header block (e.g. `max-md:hidden` for a desktop-only heading). */
28
28
  headerClass?: string;
29
- variant?: 'card' | 'plain';
29
+ /** `margin`: a vertical list of section links with no mini bar or mobile disclosure, for a sticky side column. */
30
+ variant?: 'card' | 'plain' | 'margin';
30
31
  showHeader?: boolean;
31
32
  navClass?: string;
32
33
  linkClass?: string;
@@ -102,7 +103,22 @@ const showMini = variant === 'card';
102
103
  </div>
103
104
  )}
104
105
 
105
- <section
106
+ {variant === 'margin' ? (
107
+ <section data-toc data-toc-section-selector={sectionSelector} class:list={[className]}>
108
+ {eyebrow && <p class:list={['mb-3 text-xs font-medium uppercase tracking-[0.2em]', eyebrowClass]}>{eyebrow}</p>}
109
+ <nav aria-label={ariaLabel} class:list={['flex flex-col border-l border-border', navClassName]}>
110
+ {items.map((item) => (
111
+ <a
112
+ href={item.href}
113
+ data-section-link={resolveSectionId(item)}
114
+ class:list={['-ml-px border-l-2 border-transparent py-1.5 pl-4 pr-2 text-sm leading-snug text-muted-foreground transition-colors hover:text-foreground data-[active=true]:border-primary data-[active=true]:font-medium data-[active=true]:text-foreground', linkClassName]}
115
+ >
116
+ {item.label}
117
+ </a>
118
+ ))}
119
+ </nav>
120
+ </section>
121
+ ) : (<section
106
122
  data-toc
107
123
  data-toc-section-selector={sectionSelector}
108
124
  {...(showMini ? { 'data-toc-main': '' } : {})}
@@ -153,7 +169,7 @@ const showMini = variant === 'card';
153
169
  </Chip>
154
170
  ))}
155
171
  </nav>
156
- </section>
172
+ </section>)}
157
173
 
158
174
  <script>
159
175
  import { initTableOfContents } from './toc.ts';
@@ -23,6 +23,7 @@ import InlineImage from '../composed/InlineImage.astro';
23
23
  import RelatedContent from '../composed/RelatedContent.astro';
24
24
  import type { RelatedItem } from '../composed/related';
25
25
  import Chip from '../primitives/Chip.astro';
26
+ import Badge from '../primitives/Badge.astro';
26
27
  import { trustedHtml } from '../types';
27
28
  import { getLabels } from '../internal/labels';
28
29
  import ArticleKeyFacts from './ArticleKeyFacts.astro';
@@ -67,6 +68,8 @@ export interface ArticlePageData {
67
68
  intro: string;
68
69
  imageAlt: string;
69
70
  imageTitle?: string;
71
+ /** One line under the hero photo (inline markdown); shown by `headVariant="editorial"`. */
72
+ imageCaption?: string;
70
73
  author?: string;
71
74
  datePublished?: string;
72
75
  dateModified?: string;
@@ -107,6 +110,16 @@ interface Props {
107
110
  /** Article head: the photo-behind-title `overlay` (default), a solid `split` band, or a `rail` of byline and share beside the headline. */
108
111
  heroVariant?: 'overlay' | 'split' | 'rail';
109
112
  heroMediaShape?: 'rect' | 'circle';
113
+ /**
114
+ * `editorial`: a Verge-style reading layout. A rail head (category chip, headline, deck and photo with caption; byline
115
+ * and share in the left rail), a "← back" link replacing the breadcrumb on mobile, a larger near-black body with the
116
+ * drop cap on, and the section list in a sticky side column from 1360px. Implies the `rail` hero, which needs a hero
117
+ * image: without one the page falls back to the plain no-hero head and `categoryChip` and the caption do not render.
118
+ * The default `standard` changes nothing.
119
+ */
120
+ headVariant?: 'standard' | 'editorial';
121
+ /** `editorial`: the chip above the headline, a link when `href` is set. */
122
+ categoryChip?: { label: string; href?: string };
110
123
  /** Replaces the breadcrumb band's classes; keep its top padding to clear the fixed header. */
111
124
  breadcrumbBandClass?: string;
112
125
  /** Enable decorative drop-cap on the lede paragraph when it starts with a letter/quote. */
@@ -174,6 +187,8 @@ const {
174
187
  showDates = true,
175
188
  heroVariant = 'overlay',
176
189
  heroMediaShape = 'rect',
190
+ headVariant = 'standard',
191
+ categoryChip,
177
192
  breadcrumbBandClass,
178
193
  dropCap = false,
179
194
  emitAudienceFacets = false,
@@ -195,13 +210,26 @@ const {
195
210
  relatedProps = {},
196
211
  backLink = null,
197
212
  } = Astro.props;
198
- const railHead = heroVariant === 'rail' && !!heroImage;
213
+ const editorial = headVariant === 'editorial';
214
+ const railHead = (heroVariant === 'rail' || editorial) && !!heroImage;
199
215
 
200
216
  const l = getLabels(locale).articlePage;
201
217
  const sourcesLen = article.sources?.length ?? 0;
202
218
  const md = (text: string) => trustedHtml(renderInlineMarkdown(text, basePath, sourcesLen));
203
219
  const introHtml = parseMarkdownInline(article.intro, basePath, sourcesLen);
204
- const hasDropCap = dropCap && /^["'«“‘]?[A-Za-zÀ-ÖØ-öø-ÿ]/.test(article.intro.trimStart());
220
+ const hasDropCap = (dropCap || editorial) && /^["'«“‘]?[A-Za-zÀ-ÖØ-öø-ÿ]/.test(article.intro.trimStart());
221
+ const ledeClass = editorial
222
+ ? 'article-lede text-foreground mb-8 font-normal'
223
+ : 'article-lede text-foreground/90 mb-8 font-normal border-l-2 border-primary/40 pl-5';
224
+ const paragraphClass = editorial
225
+ ? 'text-lg sm:text-xl text-foreground leading-[1.65] mb-5'
226
+ : 'text-base text-muted-foreground leading-relaxed mb-4';
227
+ const subParagraphClass = editorial
228
+ ? 'text-lg sm:text-xl text-foreground leading-[1.65] mb-4'
229
+ : 'text-base text-muted-foreground leading-relaxed mb-3';
230
+ const headTitleClass =
231
+ 'text-[length:var(--article-title-size,1.875rem)] sm:text-[length:var(--article-title-size-sm,2.5rem)] lg:text-[length:var(--article-title-size-lg,3rem)] text-balance';
232
+ const headMediaClass = 'aspect-[16/9]';
205
233
 
206
234
  const tocItems = article.sections.map((s) => ({
207
235
  label: s.heading,
@@ -306,9 +334,19 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
306
334
  <span class="sr-only" data-pagefind-filter={`audience:${a}`}>{a}</span>
307
335
  ))}
308
336
 
337
+ {editorial && backLink ? (
338
+ <BreadcrumbBand class={breadcrumbBandClass}>
339
+ <a href={backLink.href} data-article-back class="inline-flex items-center gap-2 py-1 text-sm font-medium text-muted-foreground hover:text-primary sm:hidden">
340
+ <span aria-hidden="true">&larr;</span>
341
+ <span>{backLink.label ?? l.allArticlesLabel}</span>
342
+ </a>
343
+ <div class="hidden sm:block"><Breadcrumb items={breadcrumbs} {...breadcrumbProps} /></div>
344
+ </BreadcrumbBand>
345
+ ) : (
309
346
  <BreadcrumbBand class={breadcrumbBandClass}>
310
347
  <Breadcrumb items={breadcrumbs} {...breadcrumbProps} />
311
348
  </BreadcrumbBand>
349
+ )}
312
350
 
313
351
  {heroImage ? (
314
352
  railHead ? (
@@ -320,7 +358,18 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
320
358
  imageTitle={article.imageTitle}
321
359
  variant="rail"
322
360
  mediaShape={heroMediaShape}
361
+ titleClass={editorial ? headTitleClass : undefined}
362
+ mediaClass={editorial ? headMediaClass : undefined}
363
+ compact={editorial}
323
364
  >
365
+ {editorial && categoryChip && (
366
+ <Fragment slot="badges">{categoryChip.href ? (
367
+ <Chip href={categoryChip.href} size="sm" tone="outlineQuiet">{categoryChip.label}</Chip>
368
+ ) : (
369
+ <Badge tone="primary" size="sm" lines={1}>{categoryChip.label}</Badge>
370
+ )}</Fragment>
371
+ )}
372
+ {editorial && article.imageCaption && <Fragment slot="caption" set:html={md(article.imageCaption)} />}
324
373
  <Fragment slot="info"><ArticleMetadata
325
374
  author={author}
326
375
  datePublished={article.datePublished}
@@ -330,7 +379,7 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
330
379
  showDates={showDates}
331
380
  era={era}
332
381
  eraBasePath={eraBasePath}
333
- /></Fragment>
382
+ /><slot name="rail" /></Fragment>
334
383
  <Fragment slot="actions">{showShareButtons && shareUrl && showShareTop && <ShareButtons url={shareUrl} title={article.title} locale={locale} />}</Fragment>
335
384
  </ContentHero>
336
385
  ) : (
@@ -359,7 +408,7 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
359
408
  )}
360
409
 
361
410
  <main>
362
- <Container size="measure" class="py-10 sm:py-14">
411
+ <Container size="measure" class={editorial ? 'relative pt-6 pb-10 sm:pt-8 sm:pb-14' : 'py-10 sm:py-14'}>
363
412
  {!railHead && <ArticleMetadata
364
413
  author={author}
365
414
  datePublished={article.datePublished}
@@ -380,7 +429,7 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
380
429
  <slot name="after-byline" />
381
430
 
382
431
  <div
383
- class="article-lede text-foreground/90 mb-8 font-normal border-l-2 border-primary/40 pl-5"
432
+ class={ledeClass}
384
433
  data-dropcap={hasDropCap ? '' : undefined}
385
434
  set:html={introHtml}
386
435
  />
@@ -396,9 +445,15 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
396
445
  )}
397
446
 
398
447
  {showToc && (
399
- <div class="mb-10" data-pagefind-ignore>
448
+ <Fragment><div class={editorial ? 'mb-10 min-[1360px]:hidden' : 'mb-10'} data-pagefind-ignore>
400
449
  <TableOfContents items={tocItems} eyebrow={l.tocEyebrow} headerClass="max-md:hidden" {...tocProps} />
401
- </div>
450
+ </div>{editorial && (
451
+ <aside class="absolute left-full top-0 bottom-0 ml-10 hidden w-52 min-[1360px]:block" data-article-toc-margin data-pagefind-ignore>
452
+ <div class="sticky top-28">
453
+ <TableOfContents variant="margin" items={tocItems} eyebrow={l.tocEyebrow} ariaLabel={l.tocEyebrow} />
454
+ </div>
455
+ </aside>
456
+ )}</Fragment>
402
457
  )}
403
458
 
404
459
  <div class={proseClass}>
@@ -416,7 +471,7 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
416
471
  </h2>
417
472
  {blocks.map((block) => {
418
473
  if (block.kind === 'paragraph') {
419
- return <div class="text-base text-muted-foreground leading-relaxed mb-4" set:html={block.html} />;
474
+ return <div class={paragraphClass} set:html={block.html} />;
420
475
  }
421
476
  if (block.kind === 'interlude') {
422
477
  return (
@@ -466,7 +521,7 @@ const resolvedRelatedTitle = relatedProps.title ?? l.relatedTitle;
466
521
  {sub.heading}
467
522
  </h3>
468
523
  {sub.paragraphs.map((pHtml) => (
469
- <div class="text-base text-muted-foreground leading-relaxed mb-3" set:html={pHtml} />
524
+ <div class={subParagraphClass} set:html={pHtml} />
470
525
  ))}
471
526
  </div>
472
527
  ))}
@@ -33,6 +33,12 @@ interface Props {
33
33
  variant?: 'overlay' | 'split' | 'rail';
34
34
  mediaShape?: 'rect' | 'circle';
35
35
  minHeight?: 'short' | 'medium' | 'tall';
36
+ /** `rail` only: replaces the headline's size classes (a site's own scale). */
37
+ titleClass?: string;
38
+ /** `rail` only: replaces the photo's aspect-ratio classes. */
39
+ mediaClass?: string;
40
+ /** `rail` only: tighter vertical rhythm, so the headline fits the first mobile screen. */
41
+ compact?: boolean;
36
42
  class?: string;
37
43
  }
38
44
 
@@ -51,6 +57,9 @@ const {
51
57
  variant = 'overlay',
52
58
  mediaShape = 'rect',
53
59
  minHeight = 'medium',
60
+ titleClass,
61
+ mediaClass,
62
+ compact = false,
54
63
  class: className,
55
64
  } = Astro.props;
56
65
 
@@ -79,8 +88,8 @@ const gradientClass = themeGradients[theme] || themeGradients.dark;
79
88
  const heightClass = heightClasses[minHeight] || heightClasses.medium;
80
89
 
81
90
  const slotHtml = async (name: string) => (Astro.slots.has(name) ? (await Astro.slots.render(name)).trim() : '');
82
- const [badges, subtitle, info, actions, decoration] = await Promise.all(
83
- ['badges', 'subtitle', 'info', 'actions', 'decoration'].map(slotHtml),
91
+ const [badges, subtitle, info, actions, decoration, caption] = await Promise.all(
92
+ ['badges', 'subtitle', 'info', 'actions', 'decoration', 'caption'].map(slotHtml),
84
93
  );
85
94
  ---
86
95
 
@@ -181,7 +190,7 @@ const [badges, subtitle, info, actions, decoration] = await Promise.all(
181
190
 
182
191
  {variant !== 'overlay' && (
183
192
  <section data-hero data-hero-variant={variant} class:list={['relative overflow-hidden', variant === 'split' ? 'bg-overlay text-overlay-foreground' : 'bg-background text-foreground', className]}>
184
- <div class="mx-auto max-w-shell px-4 sm:px-6 lg:px-8 py-10 lg:py-14">
193
+ <div class:list={['mx-auto max-w-shell px-4 sm:px-6 lg:px-8', variant === 'rail' && compact ? 'py-6 lg:py-10' : 'py-10 lg:py-14']}>
185
194
  <div class:list={['grid gap-8 lg:gap-12 items-center', variant === 'split' ? 'lg:grid-cols-[1fr_minmax(0,26rem)]' : 'lg:grid-cols-[15rem_1fr] lg:items-start']}>
186
195
  {variant === 'rail' && (info || actions) && (
187
196
  <div class="order-2 lg:order-1 flex flex-col gap-4 lg:border-r lg:border-border lg:pr-8" data-hero-rail>
@@ -191,7 +200,7 @@ const [badges, subtitle, info, actions, decoration] = await Promise.all(
191
200
  )}
192
201
  <div class:list={['min-w-0', variant === 'rail' && 'order-1 lg:order-2']}>
193
202
  {badges && <div class="flex flex-wrap gap-2 mb-4" set:html={badges} />}
194
- <h1 data-hero-title class="font-display font-medium leading-[1.02] mb-4 text-[2rem] sm:text-5xl lg:text-6xl text-balance">{title}</h1>
203
+ <h1 data-hero-title class:list={['font-display font-medium leading-[1.02] mb-4', variant === 'rail' && titleClass ? titleClass : 'text-[2rem] sm:text-5xl lg:text-6xl text-balance']}>{title}</h1>
195
204
  {subtitle && <div class="mb-4" set:html={subtitle} />}
196
205
  {description && <p class="text-lg leading-relaxed max-w-deck opacity-85">{description}</p>}
197
206
  {variant === 'split' && info && <div class="mt-6 flex flex-wrap gap-3" set:html={info} />}
@@ -214,7 +223,7 @@ const [badges, subtitle, info, actions, decoration] = await Promise.all(
214
223
  )}
215
224
  </div>
216
225
  {variant === 'rail' && image && (
217
- <div data-hero-media class:list={['mt-10 aspect-[16/9] lg:aspect-[21/9] overflow-hidden bg-muted', mediaShape === 'circle' && 'rounded-[2rem]']}>
226
+ <Fragment><div data-hero-media class:list={[compact ? 'mt-6 lg:mt-8' : 'mt-10', mediaClass ?? 'aspect-[16/9] lg:aspect-[21/9]', 'overflow-hidden bg-muted', mediaShape === 'circle' && 'rounded-[2rem]']}>
218
227
  <ResponsivePicture
219
228
  src={image}
220
229
  alt={imageAlt}
@@ -226,7 +235,7 @@ const [badges, subtitle, info, actions, decoration] = await Promise.all(
226
235
  loading="eager"
227
236
  fetchpriority="high"
228
237
  />
229
- </div>
238
+ </div>{caption && <p data-hero-caption class="mt-3 text-sm leading-snug text-muted-foreground" set:html={caption} />}</Fragment>
230
239
  )}
231
240
  </div>
232
241
  </section>