@sarimarcus/content-sites-ui 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.14.0 (2026-10-01)
+
+- New `./seo`: `JsonLd` (safe JSON-LD renderer: escapes `</script`, `<!--` and U+2028/9), `OgImageMeta`, `Breadcrumb` (chevron or star separator, tap targets, copy as props), `ArticleMetadata` (resolved author in, no byline without one) and `AuthoritativeSources` (domain labels and outbound classification as props; competitor sources unlinked, affiliates `rel="noopener sponsored"`; optional disambiguation of domain-derived labels shared by different URLs). `scrollbar-hide` utility in `tailwind.css` (SLA-2737).
+
 ## 0.13.0 (2026-10-01)
 
 - New `./editorial`: `EditorialGuidePage` (breadcrumb band, hero and body slots; owns the Pagefind markers, `pagefindType`, `breadcrumbIgnore`) and `EventPage` (back link, rendered body as `TrustedHtml`, highlights, practical information, price, official website and tags as props; `breadcrumb`, `hero`, `after-body`, `after-details` and `tail` slots), plus `BeforeYouGo` and `NumberedStep`. `./layout`: `BreadcrumbBand` (SLA-2819).

package/package.json

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

package/src/seo/ArticleMetadata.astro

@@ -0,0 +1,144 @@
+---
+/**
+ * ArticleMetadata — byline and freshness dates (E-E-A-T).
+ *
+ * The author arrives resolved: the site looks the name up in its authors collection and passes the profile URL,
+ * the optimised portrait (or a photo URL) and the credentials. No author renders no byline and no avatar; a site
+ * that wants a brand byline passes it as an author.
+ *
+ * Dates: most callers pass a date-only value (only articles carry a real HH:MM), so a time is printed only when the
+ * input has one, in `timeZone`; a date-only value always prints its UTC calendar day. "Updated" leads when the two
+ * dates fall on different calendar days, since recency is what a reader and a crawler look for.
+ *
+ * The `\n`-prefixed labels and `bylineLead` reproduce the text nodes the sites' templates compile to, so adoption
+ * changes no byte.
+ */
+import { Image } from 'astro:assets';
+import type { ArticleAuthor } from './types';
+
+interface Props {
+  author?: ArticleAuthor | null;
+  datePublished?: string;
+  dateModified?: string;
+  /** Time zone for a value that carries a time. */
+  timeZone?: string;
+  locale?: string;
+  writtenByLabel?: string;
+  /** Portrait alt text, followed by the author's name. */
+  portraitLabel?: string;
+  updatedLabel?: string;
+  publishedLabel?: string;
+  ariaLabel?: string;
+  /** Classes of the round placeholder shown when the author has no portrait. */
+  placeholderClass?: string;
+  updatedIconClass?: string;
+  /** Whitespace compatibility only: 'grouped' compiles to the markup of a template that wraps the byline in a Fragment. */
+  bylineWhitespace?: 'flat' | 'grouped';
+}
+
+const {
+  author,
+  datePublished,
+  dateModified,
+  timeZone = 'UTC',
+  locale = 'en-GB',
+  writtenByLabel = 'Written by',
+  portraitLabel = 'Portrait of',
+  updatedLabel = 'Updated',
+  publishedLabel = 'Published',
+  ariaLabel = 'Article information',
+  placeholderClass = 'bg-gradient-to-br from-primary/20 to-accent/20',
+  updatedIconClass = 'text-primary',
+  bylineWhitespace = 'flat',
+} = Astro.props;
+
+function formatDate(dateStr: string | undefined): string {
+  if (!dateStr) return '';
+
+  const date = new Date(dateStr);
+  return dateStr.includes('T')
+    ? date.toLocaleString(locale, {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        hour: '2-digit',
+        minute: '2-digit',
+        timeZone,
+      })
+    : date.toLocaleDateString(locale, {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+        timeZone: 'UTC',
+      });
+}
+
+const publishedFormatted = formatDate(datePublished);
+const modifiedFormatted = formatDate(dateModified);
+const showModified = !!dateModified && (!datePublished || dateModified.slice(0, 10) !== datePublished.slice(0, 10));
+
+const name = author?.name;
+const portraitAlt = `${portraitLabel} ${name}`;
+const credentials = author?.credentials ?? null;
+const grouped = bylineWhitespace === 'grouped';
+const bylineLead = author ? (grouped ? '  ' : ' ') : (grouped ? '' : ' ');
+---
+
+<address class="not-italic mb-5" role="contentinfo" aria-label={ariaLabel}>
+  <div class="flex items-start gap-3">
+    {author && (author.image ? (
+      <Image
+        src={author.image}
+        alt={portraitAlt}
+        width={96}
+        height={96}
+        class="w-12 h-12 rounded-full object-cover bg-muted shrink-0 mt-0.5"
+        loading="lazy"
+        decoding="async"
+      />
+    ) : author.photoUrl ? (
+      <img
+        src={author.photoUrl}
+        alt={portraitAlt}
+        width="48"
+        height="48"
+        class="w-12 h-12 rounded-full object-cover bg-muted shrink-0 mt-0.5"
+        loading="lazy"
+        decoding="async"
+      />
+    ) : (
+      <div class:list={['w-12 h-12 rounded-full', placeholderClass, 'shrink-0 mt-0.5']} aria-hidden="true" />
+    ))}
+
+    {/* name, credentials, dates */}
+    <div class="min-w-0">{bylineLead}{author && <div class="text-xs text-muted-foreground mb-0.5">{writtenByLabel}</div>}
+      {author && (author.href ? (
+        <a href={author.href} rel="author" class="font-semibold text-foreground hover:text-primary transition-colors hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary">
+          {name}
+        </a>
+      ) : (
+        <span class="font-semibold text-foreground">{name}</span>
+      ))}
+      {author && credentials && (
+        <p class="mt-1 text-sm text-muted-foreground leading-snug line-clamp-2">{credentials}</p>
+      )}
+      {/* freshness first */}
+      <div class="mt-2 flex flex-wrap items-center gap-x-3 gap-y-1 text-xs text-muted-foreground">
+        {showModified && modifiedFormatted ? (
+          <span class="inline-flex items-center gap-1.5 text-sm font-medium text-foreground">
+            <svg class:list={['w-3.5 h-3.5 shrink-0', updatedIconClass]} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+              <polyline points="23 4 23 10 17 10" />
+              <path d="M20.49 15a9 9 0 1 1-2.12-9.36L23 10" />
+            </svg>{`\n${updatedLabel}`} <time datetime={dateModified}>{modifiedFormatted}</time>
+          </span>
+        ) : publishedFormatted && (
+          <span class="text-sm font-medium text-foreground">{`\n${publishedLabel}`} <time datetime={datePublished}>{publishedFormatted}</time>
+          </span>
+        )}
+        {showModified && publishedFormatted && (
+          <span>{publishedLabel} <time datetime={datePublished}>{publishedFormatted}</time></span>
+        )}
+      </div>
+    </div>
+  </div>
+</address>

package/src/seo/AuthoritativeSources.astro

@@ -0,0 +1,190 @@
+---
+/**
+ * AuthoritativeSources — numbered, anchored references (E-E-A-T). Each item carries id="fn-{n}" so an inline `[^n]`
+ * footnote link jumps to it (validate-footnote-render relies on that), and the inline script opens the list when the
+ * page loads on, or navigates to, a `#fn-n` hash.
+ *
+ * A source is a URL string, labelled from `domainLabels` (by host, without `www.`) or else by its host, or an object
+ * { url, name?, description?, quote? }: `description` is a curated blurb, `quote` the verbatim cited sentence.
+ *
+ * Link policy (Rule 38), from `domainClass` (host → class, or a function of the URL): a competitor renders its label
+ * unlinked (the item stays, so footnote numbers hold), an affiliate link carries rel="noopener sponsored", any other
+ * rel="noopener".
+ *
+ * `disambiguate` suffixes domain-derived labels shared by different URLs with a fragment of their URL path
+ * ("Host — Prices"), so two pages of one domain stay distinguishable. Explicit names, repeat citations of one URL and
+ * domain-root URLs keep their label.
+ */
+import type { SourceInput, DomainClassifier } from './types';
+
+interface Props {
+  sources: SourceInput[];
+  title?: string;
+  class?: string;
+  eyebrow?: string;
+  eyebrowClass?: string;
+  domainLabels?: Record<string, string>;
+  domainClass?: DomainClassifier;
+  disambiguate?: boolean;
+  disambiguationSeparator?: string;
+  /** Follows the count: "12 references". */
+  countLabel?: string;
+  showLabel?: string;
+  hideLabel?: string;
+  newTabLabel?: string;
+  /** Size class of the Show/Hide toggle labels. */
+  toggleSizeClass?: string;
+}
+
+const {
+  sources,
+  title = 'Sources',
+  class: className = '',
+  eyebrow = 'Further reading',
+  eyebrowClass = 'text-xs font-semibold uppercase tracking-[0.18em] text-primary',
+  domainLabels = {},
+  domainClass = {},
+  disambiguate = false,
+  disambiguationSeparator = ' — ',
+  countLabel = 'references',
+  showLabel = 'Show',
+  hideLabel = 'Hide',
+  newTabLabel = '(opens in a new tab)',
+  toggleSizeClass = 'text-sm',
+} = Astro.props;
+
+if (!sources || sources.length === 0) return null;
+
+const hostKey = (host: string) => host.toLowerCase().replace(/^www\./, '');
+const classMap = typeof domainClass === 'function'
+  ? null
+  : new Map(Object.entries(domainClass).map(([d, c]) => [hostKey(d), c]));
+
+function classify(url: string): string {
+  if (typeof domainClass === 'function') return domainClass(url);
+  try {
+    return classMap?.get(hostKey(new URL(url).hostname)) ?? 'other';
+  } catch {
+    return 'other';
+  }
+}
+
+function domainLabel(url: string): string {
+  try {
+    const h = new URL(url).hostname.replace(/^www\./, '');
+    return domainLabels[h] ?? h;
+  } catch {
+    return url;
+  }
+}
+
+function humanizeSlug(slug: string): string {
+  const cleaned = slug
+    .replace(/\.(html?|php|aspx?)$/i, '')
+    .replace(/[-_]+/g, ' ')
+    .trim();
+  if (!cleaned) return '';
+  return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
+
+function pathFragment(url: string): string | null {
+  try {
+    const segments = new URL(url).pathname.split('/').filter(Boolean);
+    if (segments.length === 0) return null;
+    const humanized = humanizeSlug(decodeURIComponent(segments[segments.length - 1]));
+    return humanized || null;
+  } catch {
+    return null;
+  }
+}
+
+const normalized: { name: string; url: string; description?: string; quote?: string; linkRel: string | null; fromDomain: boolean }[] = sources.map((s) => {
+  const entry =
+    typeof s === 'string'
+      ? { name: domainLabel(s), url: s, fromDomain: true }
+      : { url: s.url, name: s.name ?? domainLabel(s.url), description: s.description, quote: s.quote, fromDomain: !s.name };
+  const cls = classify(entry.url);
+  return {
+    ...entry,
+    linkRel: cls === 'competitor' ? null : cls === 'affiliate' ? 'noopener sponsored' : 'noopener',
+  };
+});
+
+if (disambiguate) {
+  const urlsByName = new Map<string, Set<string>>();
+  for (const n of normalized) if (n.fromDomain) urlsByName.set(n.name, (urlsByName.get(n.name) ?? new Set()).add(n.url));
+  for (const n of normalized) {
+    if (n.fromDomain && (urlsByName.get(n.name)?.size ?? 0) > 1) {
+      const frag = pathFragment(n.url);
+      if (frag) n.name = `${n.name}${disambiguationSeparator}${frag}`;
+    }
+  }
+}
+---
+
+<section class:list={["mt-12 pt-8 border-t border-border", className]} aria-labelledby="sources-heading">
+  <p class:list={[eyebrowClass, 'mb-2']}>{eyebrow}</p>
+  <h2 id="sources-heading" class="text-xl sm:text-2xl font-normal font-display text-foreground mb-3 tracking-tight">{title}</h2>
+  <details data-sources class="group">
+    <summary class="flex min-h-11 cursor-pointer list-none items-center justify-between gap-4 rounded-lg border border-border bg-muted/30 px-4 py-2.5 text-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary marker:content-none">
+      <span class="text-muted-foreground">{normalized.length} {countLabel}</span>
+      <span class:list={[toggleSizeClass, 'font-medium text-primary group-open:hidden']}>{showLabel}</span>
+      <span class:list={['hidden', toggleSizeClass, 'font-medium text-primary group-open:inline']}>{hideLabel}</span>
+    </summary>
+
+  <ol class="mt-5 space-y-2 list-none" role="list">
+    {normalized.map((source, i) => (
+      <li
+        id={`fn-${i + 1}`}
+        class="flex items-baseline gap-3 p-3 bg-muted/30 rounded-lg border border-border hover:border-primary/50 transition-colors scroll-mt-28"
+      >
+        <span class="font-mono text-sm text-primary min-w-[2rem] shrink-0 select-none" aria-hidden="true">
+          [{i + 1}]
+        </span>
+        <div class="flex-1 min-w-0">
+          {source.linkRel === null ? (
+            <span class="inline-flex items-baseline gap-1.5 font-medium text-sm text-foreground break-words">
+              <span>{source.name}</span>
+            </span>
+          ) : (
+            <a
+              href={source.url}
+              target="_blank"
+              rel={source.linkRel}
+              class="inline-flex items-baseline gap-1.5 font-medium text-sm text-foreground hover:text-primary transition-colors break-words"
+            >
+              <span>{source.name}</span>
+              <svg class="w-3.5 h-3.5 self-center text-muted-foreground shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <path d="M7 7h10v10" />
+                <path d="M7 17 17 7" />
+              </svg>
+              <span class="sr-only">{newTabLabel}</span>
+            </a>
+          )}
+          {source.description && (
+            <p class="text-sm text-muted-foreground mt-1 leading-relaxed">{source.description}</p>
+          )}
+          {source.quote && (
+            <p class="text-sm text-muted-foreground mt-1.5 leading-relaxed italic border-l-2 border-primary/30 pl-3">
+              &ldquo;{source.quote}&rdquo;
+            </p>
+          )}
+        </div>
+      </li>
+    ))}
+  </ol>
+  </details>
+</section>
+
+<script is:inline>
+  (() => {
+    const revealSource = () => {
+      if (!/^#fn-\d+$/.test(location.hash)) return;
+      const target = document.querySelector(location.hash);
+      const details = target?.closest('[data-sources]');
+      if (details) details.open = true;
+    };
+    revealSource();
+    addEventListener('hashchange', revealSource);
+  })();
+</script>

package/src/seo/Breadcrumb.astro

@@ -0,0 +1,80 @@
+---
+/**
+ * Breadcrumb — the visual trail, Home first. Renders no JSON-LD: the BreadcrumbList is the structured-data adapter's.
+ *
+ * Single line, always: the trail scrolls horizontally instead of wrapping, so a deep trail never pushes the page
+ * content down on mobile. `tapTargets`: py-1/-my-1 extends each link's hit area 4px beyond its row without moving
+ * layout; the nav's own py-1/-my-1 mirrors it so the overflow container never clips that hit area (28px meets
+ * WCAG 2.5.8 AA). `separator="star"` draws a filled star that fades with depth.
+ *
+ * `navLead` reproduces the text node the sites' templates emit before the list (two spaces with tap targets, one
+ * without), so adopting the package changes no byte.
+ */
+import { url } from '@sarimarcus/content-sites-core/url';
+import Icon from '../primitives/Icon.astro';
+import type { BreadcrumbItem } from './types';
+
+interface Props {
+  items: BreadcrumbItem[];
+  compactMobile?: boolean;
+  textColorClass?: string;
+  linkColorClass?: string;
+  separatorColorClass?: string;
+  separator?: 'chevron' | 'star';
+  tapTargets?: boolean;
+  homeLabel?: string;
+  homeHref?: string;
+  ariaLabel?: string;
+  basePath?: string;
+}
+
+const {
+  items,
+  textColorClass = 'text-muted-foreground',
+  linkColorClass = 'hover:text-primary',
+  separatorColorClass = 'text-border',
+  compactMobile = false,
+  separator = 'chevron',
+  tapTargets = true,
+  homeLabel = 'Home',
+  homeHref = '/',
+  ariaLabel = 'Breadcrumb navigation',
+  basePath = '/',
+} = Astro.props;
+
+const breadcrumbs = [
+  { name: homeLabel, url: homeHref },
+  ...items,
+];
+const navLead = tapTargets ? '  ' : ' ';
+---
+
+<nav aria-label={ariaLabel} class:list={[tapTargets ? 'text-sm py-1 -my-1 px-1 -mx-1' : 'text-sm', compactMobile ? 'overflow-hidden sm:overflow-x-auto' : 'overflow-x-auto scrollbar-hide', textColorClass]}>{navLead}<ol class:list={[tapTargets ? 'flex flex-nowrap items-center gap-x-1.5 whitespace-nowrap' : 'flex flex-nowrap items-center gap-1.5 whitespace-nowrap']}>
+    {breadcrumbs.map((item, index) => (
+      <li class:list={['flex items-center gap-1.5', compactMobile && index === breadcrumbs.length - 1 ? 'min-w-0 sm:shrink-0' : 'shrink-0']}>
+        {index > 0 && (separator === 'star' ? (
+          <Icon
+            name="star"
+            filled
+            class:list={['w-2.5 h-2.5 shrink-0', separatorColorClass]}
+            style={`opacity: ${Math.max(0.4, 1 - (index - 1) * 0.15)}`}
+          />
+        ) : (
+          <svg class:list={['w-3.5 h-3.5 shrink-0', separatorColorClass]} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <path d="m9 18 6-6-6-6"/>
+          </svg>
+        ))}
+        {item.url && index < breadcrumbs.length - 1 ? (
+          <a
+            href={url(item.url, basePath)}
+            class:list={[tapTargets ? 'inline-flex items-center py-1 -my-1 px-1 -mx-1 transition-colors' : 'transition-colors', linkColorClass]}
+          >
+            {item.name}
+          </a>
+        ) : (
+          <span class:list={['font-medium', compactMobile && index === breadcrumbs.length - 1 ? 'truncate sm:overflow-visible' : '']}>{item.name}</span>
+        )}
+      </li>
+    ))}
+  </ol>
+</nav>

package/src/seo/JsonLd.astro

@@ -0,0 +1,20 @@
+---
+/**
+ * JsonLd — renders structured data as one <script type="application/ld+json">.
+ *
+ * Output is JSON.stringify(data) with the minimal escaping that keeps the block inside its script element while
+ * staying valid JSON: `</script` (any case) → `<\/script`, `<!--` → `<\u0021--`, U+2028/U+2029 → `\u2028`/`\u2029`.
+ * Any other input renders byte-identical to `set:html={JSON.stringify(data)}`. Values may carry markup (an FAQ answer
+ * with a link), so `<` is deliberately left as is.
+ */
+import { escapeJsonLd } from './jsonLd';
+
+interface Props {
+  data: object | object[];
+}
+
+const { data } = Astro.props;
+const json = escapeJsonLd(JSON.stringify(data));
+---
+
+<script type="application/ld+json" set:html={json} />

package/src/seo/OgImageMeta.astro

@@ -0,0 +1,29 @@
+---
+/**
+ * OgImageMeta — Open Graph and Twitter image tags. A relative `image` (or the default) is made absolute against
+ * `siteUrl` + `baseUrl`; an `http…` image passes through. The 1200×675 default matches the OG generator
+ * (scripts/og-images/generate.mjs).
+ */
+interface Props {
+  image?: string;
+  alt: string;
+  siteUrl: string;
+  baseUrl: string;
+  defaultImage?: string;
+  width?: number;
+  height?: number;
+}
+
+const { image, alt, siteUrl, baseUrl, defaultImage = '/og-default.jpg', width = 1200, height = 675 } = Astro.props;
+const ogImagePath = image ?? defaultImage;
+const absoluteOgImage = ogImagePath.startsWith('http')
+  ? ogImagePath
+  : `${siteUrl}${baseUrl}${ogImagePath}`;
+---
+
+<meta property="og:image" content={absoluteOgImage} />
+<meta property="og:image:alt" content={alt} />
+<meta property="og:image:width" content={String(width)} />
+<meta property="og:image:height" content={String(height)} />
+<meta name="twitter:image" content={absoluteOgImage} />
+<meta name="twitter:image:alt" content={alt} />

package/src/seo/index.ts

@@ -1,2 +1,8 @@
-// Public surface of @sarimarcus/content-sites-ui/seo. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-ui/seo.
+export { default as JsonLd } from './JsonLd.astro';
+export { default as OgImageMeta } from './OgImageMeta.astro';
+export { default as Breadcrumb } from './Breadcrumb.astro';
+export { default as ArticleMetadata } from './ArticleMetadata.astro';
+export { default as AuthoritativeSources } from './AuthoritativeSources.astro';
+export { escapeJsonLd } from './jsonLd';
+export type { BreadcrumbItem, ArticleAuthor, SourceInput, DomainClassifier } from './types';

package/src/seo/jsonLd.ts

@@ -0,0 +1,11 @@
+/**
+ * Keep serialised JSON inside a <script> element without changing what it parses to. Every match sits inside a JSON
+ * string (none of these sequences can occur outside one), where `\/`, `\u0021` and `\u2028` are valid escapes.
+ */
+export function escapeJsonLd(json: string): string {
+  return json
+    .replace(/<\/(script)/gi, '<\\/$1')
+    .replace(/<!--/g, '<\\u0021--')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}

package/src/seo/types.ts

@@ -0,0 +1,20 @@
+import type { ImageMetadata } from 'astro';
+
+export interface BreadcrumbItem {
+  name: string;
+  url?: string;
+}
+
+/** An author already resolved by the site: profile URL, optimised portrait or photo URL, credentials. */
+export interface ArticleAuthor {
+  name: string;
+  href?: string | null;
+  image?: ImageMetadata | null;
+  photoUrl?: string | null;
+  credentials?: string | null;
+}
+
+export type SourceInput = string | { name?: string; url: string; description?: string; quote?: string };
+
+/** Host → outbound class (`competitor`, `affiliate`, …), or a function of the URL. */
+export type DomainClassifier = Record<string, string> | ((url: string) => string);

package/src/styles/tailwind.css

@@ -1,3 +1,12 @@
 /* Tailwind v4 skips node_modules during class detection. Consumers @import this file so the
    package's own templates are scanned: @import "@sarimarcus/content-sites-ui/tailwind.css"; */
 @source "..";
+
+/* Horizontal scrollers that keep scrolling but draw no scrollbar (Breadcrumb, TableOfContents). */
+@utility scrollbar-hide {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}