@sarimarcus/content-sites-ui 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.10.0 (2026-09-30)
+
+- New `./composed`: `TableOfContents` (+ `miniLinkClass`, opt-in `hideMiniPastLastSection`), `CardCarousel` (active dot from `--carousel-dot`), `QuickFacts` (link colours as roles, `labelSizeClass`), `FAQ` and `InlineImage` (rendered HTML in, via `TrustedHtml`; markdown stays in the site), `Pagination` (`href(page)` builder). Controllers are bundled modules, initialised once per instance. `./types`: `TrustedHtml`, `trustedHtml()`, `textAsHtml()` (SLA-2732).
+
+## 0.9.1 (2026-09-30)
+
+- No changes; lockstep release with core (SLA-2747).
+
 ## 0.9.0 (2026-09-30)
 
 - No changes; lockstep release with core (SLA-2747).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-ui",
-  "version": "0.9.0",
+  "version": "0.10.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.9.0"
+    "@sarimarcus/content-sites-core": "0.10.0"
   }
 }

package/src/composed/CardCarousel.astro

@@ -0,0 +1,134 @@
+---
+/**
+ * CardCarousel — scroll-snap card strip with prev/next arrows and dots, driven by ./carousel.ts.
+ *
+ * Callers place each card as a direct child of the default slot, carrying `snap-start shrink-0` and a fixed
+ * responsive width, e.g. `<a class="snap-start shrink-0 w-[80vw] sm:w-72">…</a>`.
+ *
+ * The header always renders so the arrows exist even under a caller's own heading; the view-all link shows at every
+ * width, so a capped carousel always offers an onward path (SLA-2368). The active dot takes `--carousel-dot` when the
+ * site defines it (default: the primary role).
+ */
+import Icon from '../primitives/Icon.astro';
+import { deterministicId } from '@sarimarcus/content-sites-core/dom';
+
+interface Props {
+  /** Section heading rendered above the track. */
+  heading?: string;
+  headingTag?: 'h2' | 'h3';
+  /**
+   * Full replacement for the heading's classes (not appended — a merged list
+   * would keep the default `sm:text-3xl` winning at that breakpoint). Use when
+   * a caller needs a quieter heading than the default section scale, e.g. a
+   * subordinate related-content block sitting under a page `h2`.
+   */
+  headingClass?: string;
+  description?: string;
+  /** Anchor id for in-page jump links / scroll-spy. */
+  id?: string;
+  /** Optional "view all" link shown next to the arrows. */
+  viewAllHref?: string;
+  viewAllLabel?: string;
+  /** Accessible label for the scroll region (falls back to the heading). */
+  ariaLabel?: string;
+  class?: string;
+}
+
+const {
+  heading,
+  headingTag = 'h2',
+  headingClass,
+  description,
+  id,
+  viewAllHref,
+  viewAllLabel = 'View all',
+  ariaLabel,
+  class: className,
+} = Astro.props;
+
+const HeadingTag = headingTag;
+
+// Ids must be unique per page AND stable across builds.
+const containerId = deterministicId('cc', Astro.url.pathname, id, ariaLabel ?? heading);
+const trackId = `${containerId}-t`;
+---
+
+<div id={id} data-carousel={containerId} class:list={['scroll-mt-28', className]}>
+  <div class="mb-5 flex items-end justify-between gap-4">
+    <div class="min-w-0 flex-1">
+      {heading && (
+        <HeadingTag class={headingClass ?? 'font-display text-2xl font-medium sm:text-3xl'}>{heading}</HeadingTag>
+      )}
+      {description && (
+        <p class="mt-1 text-sm leading-relaxed text-muted-foreground sm:text-base">{description}</p>
+      )}
+      <slot name="header-note" />
+    </div>
+
+    <div class="flex shrink-0 items-center gap-2">
+      {viewAllHref && (
+        <a
+          href={viewAllHref}
+          class="mr-1 inline-flex items-center gap-1.5 text-sm font-medium text-primary underline decoration-primary/40 underline-offset-2 transition-colors hover:decoration-primary"
+        >
+          {viewAllLabel}
+          <Icon name="arrow-right" class="h-4 w-4" aria-hidden="true" />
+        </a>
+      )}
+      <div data-carousel-arrows class="hidden gap-2">
+        <button
+          data-carousel-prev
+          type="button"
+          aria-label={`Previous, ${ariaLabel ?? heading ?? 'carousel'}`}
+          disabled
+          class="flex h-9 w-9 cursor-pointer items-center justify-center rounded-full border border-border bg-card transition-colors hover:border-primary/40 hover:bg-primary/10 disabled:pointer-events-none disabled:opacity-25"
+        >
+          <Icon name="chevron-left" class="h-4 w-4" aria-hidden="true" />
+        </button>
+        <button
+          data-carousel-next
+          type="button"
+          aria-label={`Next, ${ariaLabel ?? heading ?? 'carousel'}`}
+          class="flex h-9 w-9 cursor-pointer items-center justify-center rounded-full border border-border bg-card transition-colors hover:border-primary/40 hover:bg-primary/10 disabled:pointer-events-none disabled:opacity-25"
+        >
+          <Icon name="chevron-right" class="h-4 w-4" aria-hidden="true" />
+        </button>
+      </div>
+    </div>
+  </div>
+  <div
+    id={trackId}
+    data-carousel-track
+    class="cc-track -mx-4 flex gap-4 overflow-x-auto scroll-px-4 px-4 py-1.5 snap-x snap-mandatory sm:mx-0 sm:scroll-px-0 sm:px-0"
+    aria-label={ariaLabel ?? heading ?? 'Carousel'}
+    role="group"
+    tabindex="0"
+  >
+    <slot />
+  </div>
+  <div data-carousel-dots class="mt-4 hidden justify-center gap-2"></div>
+</div>
+
+<style is:global>
+  /* Hide the scrollbar while keeping the track scrollable/swipable. */
+  .cc-track {
+    -ms-overflow-style: none;
+    scrollbar-width: none;
+  }
+  .cc-track::-webkit-scrollbar {
+    display: none;
+  }
+  /* The track is a keyboard focus stop (tabindex="0", role="group"), so it needs its own visible focus ring. */
+  .cc-track:focus-visible {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
+    border-radius: var(--radius-lg, 8px);
+  }
+</style>
+
+<script>
+  import { initCarousels } from './carousel.ts';
+
+  initCarousels();
+  document.addEventListener('astro:page-load', initCarousels);
+</script>

package/src/composed/FAQ.astro

@@ -0,0 +1,71 @@
+---
+/**
+ * FAQ — accordion of questions and answers.
+ *
+ * Items arrive already rendered: a site converts its authored markdown (footnotes included) and passes the result
+ * through trustedHtml(). The package never converts markdown. Structured data is the page template's job:
+ *   <StructuredData schemas={[{ type: 'faqPage', data: { questions: items } }]} />
+ */
+import Icon from '../primitives/Icon.astro';
+import type { TrustedHtml } from '../types/index.ts';
+
+export interface FaqItem {
+  questionHtml: TrustedHtml;
+  answerHtml: TrustedHtml;
+}
+
+interface Props {
+  items: FaqItem[];
+  title?: string;
+  /** Show the info icon before the title (default: true). */
+  icon?: boolean;
+  /** Replaces the title's classes. */
+  headingClass?: string;
+  id?: string;
+  class?: string;
+}
+
+const {
+  items,
+  title = 'Frequently asked questions',
+  icon = true,
+  headingClass = 'text-2xl sm:text-3xl font-normal mb-6 flex items-center gap-3 font-display',
+  id,
+  class: className = '',
+} = Astro.props;
+---
+
+{items.length > 0 && (
+  <section id={id} class:list={[className]} data-pagefind-body>
+    {title && (
+      <h2 class={headingClass}>
+        {icon && <Icon name="info" class="w-7 h-7 text-primary shrink-0" />}
+        {title}
+      </h2>
+    )}
+    <div class="space-y-4">
+      {items.map((item) => (
+        <details class="group p-6 bg-card rounded-xl border border-border hover:border-primary/50 open:border-primary/50 transition-colors" data-faq-track>
+          <summary class="flex items-center justify-between cursor-pointer list-none">
+            <h3 class="text-base font-medium group-hover:text-primary transition-colors pr-4" set:html={item.questionHtml} />
+            <svg
+              class="w-5 h-5 text-muted-foreground group-open:rotate-180 transition-transform duration-200 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="m6 9 6 6 6-6" />
+            </svg>
+          </summary>
+          <div class="mt-4 pt-4 border-t border-border text-muted-foreground leading-relaxed">
+            <div set:html={item.answerHtml} />
+          </div>
+        </details>
+      ))}
+    </div>
+  </section>
+)}

package/src/composed/InlineImage.astro

@@ -0,0 +1,160 @@
+---
+import { Picture } from 'astro:assets';
+import type { ImageMetadata } from 'astro';
+import type { TrustedHtml } from '../types/index.ts';
+
+interface Props {
+  /** Imported image (ImageMetadata from Astro asset pipeline) */
+  src: ImageMetadata;
+  /** Accessible alt text describing the image content */
+  alt: string;
+  /**
+   * Caption below the image, already rendered by the site (inline markdown, footnote markers) — it sits inside a
+   * <p>, so it must be inline HTML.
+   */
+  captionHtml?: TrustedHtml;
+  /** The caption as plain text: the accessible name of a linked image never carries HTML. */
+  captionText?: string;
+  /** Secondary caption line below the main caption */
+  subtitle?: string;
+  /** Attribution / photographer credit (hidden by default, opt-in) */
+  attribution?: string;
+  /** Show the attribution line. Default: false */
+  showAttribution?: boolean;
+  /**
+   * Layout variant:
+   * - 'full' (default): full-width image breaking the prose flow
+   * - 'left': floats left, text wraps right
+   * - 'right': floats right, text wraps left
+   */
+  layout?: 'full' | 'left' | 'right';
+  /**
+   * Image height preset (only used with layout='full'):
+   * - 'tall': h-64 / sm:h-80 / lg:h-96
+   * - 'medium' (default): h-56 / sm:h-72 / lg:h-80
+   * - 'auto': uses aspectRatio instead of fixed height
+   */
+  size?: 'tall' | 'medium' | 'auto';
+  /**
+   * CSS aspect-ratio value. Only used when size='auto'.
+   * @default '16/9'
+   */
+  aspectRatio?: string;
+  /** Optional URL to wrap the image in a link */
+  href?: string;
+  /** Image formats for the <picture> sources (default: avif + webp). */
+  formats?: ('avif' | 'webp')[];
+  /** Additional CSS classes on the outer figure element */
+  class?: string;
+}
+
+const {
+  src,
+  alt,
+  captionHtml,
+  captionText,
+  subtitle,
+  attribution,
+  showAttribution = false,
+  layout = 'full',
+  size = 'medium',
+  aspectRatio = '16/9',
+  href,
+  formats = ['avif', 'webp'],
+  class: className,
+} = Astro.props;
+
+const hasCaption = captionHtml || subtitle;
+const hasAttribution = showAttribution && attribution;
+
+const sizeClasses: Record<string, string> = {
+  tall: 'h-64 sm:h-80 lg:h-96',
+  medium: 'h-56 sm:h-72 lg:h-80',
+  auto: '',
+};
+
+const imageHeightClass = sizeClasses[size] || sizeClasses.medium;
+const useAspectRatio = size === 'auto';
+
+// Float layout classes
+const layoutClasses: Record<string, string> = {
+  full: 'w-full mb-8',
+  left: 'sm:float-left sm:w-1/2 sm:mr-6 mb-4 sm:mb-2',
+  right: 'sm:float-right sm:w-1/2 sm:ml-6 mb-4 sm:mb-2',
+};
+
+// Float images use auto size and a smaller aspect ratio
+const isFloat = layout === 'left' || layout === 'right';
+const effectiveAspectRatio = isFloat ? '4/3' : aspectRatio;
+const effectiveHeightClass = isFloat ? '' : imageHeightClass;
+const effectiveUseAspectRatio = isFloat ? true : useAspectRatio;
+
+// Filter widths to not exceed the source image width
+const defaultWidths = isFloat ? [400, 640] : [640, 960, 1280];
+const fitting = src.width ? defaultWidths.filter((w) => w <= src.width) : defaultWidths;
+const widths = fitting.length ? fitting : [src.width];
+
+const sizes = isFloat
+  ? '(max-width: 640px) 100vw, 50vw'
+  : '(max-width: 1024px) 100vw, 1024px';
+---
+
+<figure
+  class:list={[
+    'relative overflow-hidden rounded-2xl border border-border/50',
+    layoutClasses[layout],
+    className,
+  ]}
+>
+  {href ? (
+    <a href={href} class="block group" aria-label={captionText || alt}>
+      <Picture
+        src={src}
+        alt={alt}
+        widths={widths}
+        sizes={sizes}
+        formats={formats}
+        fallbackFormat="webp"
+        pictureAttributes={{ class: 'block w-full h-full' }}
+        class:list={[
+          'w-full object-cover transition-transform duration-500 group-hover:scale-[1.03]',
+          effectiveUseAspectRatio ? '' : effectiveHeightClass,
+        ]}
+        style={effectiveUseAspectRatio ? `aspect-ratio: ${effectiveAspectRatio}` : undefined}
+        loading="lazy"
+        decoding="async"
+      />
+    </a>
+  ) : (
+    <Picture
+      src={src}
+      alt={alt}
+      widths={widths}
+      sizes={sizes}
+      formats={formats}
+      fallbackFormat="webp"
+      pictureAttributes={{ class: 'block w-full h-full' }}
+      class:list={[
+        'w-full object-cover',
+        effectiveUseAspectRatio ? '' : effectiveHeightClass,
+      ]}
+      style={effectiveUseAspectRatio ? `aspect-ratio: ${effectiveAspectRatio}` : undefined}
+      loading="lazy"
+      decoding="async"
+    />
+  )}
+
+  {(hasCaption || hasAttribution) && (
+    <figcaption class="px-4 py-3 bg-muted/30">
+      {captionHtml && (
+        <p class="text-sm font-medium text-foreground/80 font-display" set:html={captionHtml} />
+      )}
+      {subtitle && (
+        <p class="text-xs text-muted-foreground mt-0.5">{subtitle}</p>
+      )}
+      {hasAttribution && (
+        <p class="text-xs text-muted-foreground/60 mt-1">{attribution}</p>
+      )}
+    </figcaption>
+  )}
+</figure>

package/src/composed/Pagination.astro

@@ -0,0 +1,96 @@
+---
+/**
+ * Pagination — accessible page navigation for paginated listings. Renders nothing when there is only one page.
+ * The site supplies the page → URL mapping, so the listing pages, their rel=prev/next head links and this component
+ * all agree on URLs.
+ */
+import Icon from '../primitives/Icon.astro';
+
+interface Props {
+  currentPage: number;
+  totalPages: number;
+  /** URL of a page number (base path included). */
+  href: (page: number) => string;
+}
+
+const { currentPage, totalPages, href } = Astro.props;
+
+const prevPage = currentPage > 1 ? currentPage - 1 : null;
+const nextPage = currentPage < totalPages ? currentPage + 1 : null;
+
+// Windowed page list: always first + last, plus current and its neighbours,
+// with gaps collapsed to an ellipsis. Keeps the control compact as articles grow.
+type Item = number | 'ellipsis';
+function buildItems(current: number, total: number): Item[] {
+  const wanted = new Set<number>([1, total, current, current - 1, current + 1]);
+  const visible = [...wanted].filter((p) => p >= 1 && p <= total).sort((a, b) => a - b);
+  const items: Item[] = [];
+  let prev = 0;
+  for (const p of visible) {
+    if (p - prev > 1) items.push('ellipsis');
+    items.push(p);
+    prev = p;
+  }
+  return items;
+}
+const items = buildItems(currentPage, totalPages);
+
+const linkBase =
+  'inline-flex items-center justify-center gap-1 h-11 rounded-lg border border-border text-sm font-medium text-foreground transition-colors hover:border-primary hover:text-primary focus:outline-none focus:ring-2 focus:ring-primary/50';
+const numberBase = `${linkBase} w-11`;
+const edgeBase = `${linkBase} px-3`;
+---
+
+{totalPages > 1 && (
+  <nav aria-label="Pagination" class="mt-14 flex items-center justify-center gap-2 flex-wrap">
+    {prevPage ? (
+      <a href={href(prevPage)} rel="prev" aria-label={`Go to page ${prevPage}`} class={edgeBase}>
+        <Icon name="arrow-left" class="w-3.5 h-3.5" />
+        <span>Previous</span>
+      </a>
+    ) : (
+      <span aria-hidden="true" class={`${edgeBase} opacity-40 cursor-default pointer-events-none`}>
+        <Icon name="arrow-left" class="w-3.5 h-3.5" />
+        <span>Previous</span>
+      </span>
+    )}
+
+    <div class="overflow-x-auto min-w-0">
+      <ul class="flex items-center gap-1.5">
+        {items.map((item) =>
+          item === 'ellipsis' ? (
+            <li aria-hidden="true" class="w-11 text-center text-sm text-muted-foreground">…</li>
+          ) : item === currentPage ? (
+            <li>
+              <span
+                aria-current="page"
+                aria-label={`Page ${item}, current page`}
+                class={`${numberBase} border-primary bg-primary text-white hover:text-white`}
+              >
+                {item}
+              </span>
+            </li>
+          ) : (
+            <li>
+              <a href={href(item)} aria-label={`Go to page ${item}`} class={numberBase}>
+                {item}
+              </a>
+            </li>
+          )
+        )}
+      </ul>
+    </div>
+
+    {nextPage ? (
+      <a href={href(nextPage)} rel="next" aria-label={`Go to page ${nextPage}`} class={edgeBase}>
+        <span>Next</span>
+        <Icon name="arrow-right" class="w-3.5 h-3.5" />
+      </a>
+    ) : (
+      <span aria-hidden="true" class={`${edgeBase} opacity-40 cursor-default pointer-events-none`}>
+        <span>Next</span>
+        <Icon name="arrow-right" class="w-3.5 h-3.5" />
+      </span>
+    )}
+  </nav>
+)}

package/src/composed/QuickFacts.astro

@@ -0,0 +1,148 @@
+---
+/**
+ * QuickFacts — reusable key-value facts block for content pages.
+ *
+ * Usage:
+ *   <QuickFacts
+ *     title="Practical information"
+ *     items={[
+ *       { icon: 'clock', label: 'Opening hours', value: '9am – 7pm' },
+ *       { icon: 'ticket', label: 'Admission', value: '€10' },
+ *       { icon: 'map-pin', label: 'Address', value: 'Calle Torrijos, 10', href: 'https://maps.google.com/...', hrefLabel: 'View on Google Maps', hrefExternal: true, span: 2 },
+ *     ]}
+ *     links={[
+ *       { href: 'https://...', label: 'Google Maps', icon: 'map-pin', color: 'secondary' },
+ *     ]}
+ *   >
+ *     <Map slot="after" ... />
+ *   </QuickFacts>
+ *
+ * The optional `after` slot renders between the facts and the action links, so a site can place a map there without
+ * the package importing it. The card, slot included, renders only when `items` is non-empty.
+ */
+
+import Icon from '../primitives/Icon.astro';
+
+interface QuickFactItem {
+  icon: string;
+  label: string;
+  value: string;
+  href?: string;
+  hrefLabel?: string;
+  hrefExternal?: boolean;
+  span?: 2;
+}
+
+interface ActionLink {
+  href: string;
+  label: string;
+  icon: string;
+  color: 'primary' | 'secondary' | 'accent';
+}
+
+interface Props {
+  title?: string;
+  items: QuickFactItem[];
+  variant?: 'card' | 'muted';
+  columns?: 2 | 3 | 4;
+  links?: ActionLink[];
+  headingLevel?: 'h2' | 'h3' | 'h4';
+  /** Replaces the fact labels' size class. */
+  labelSizeClass?: string;
+  class?: string;
+}
+
+const {
+  title,
+  items,
+  variant = 'muted',
+  columns = 2,
+  links,
+  headingLevel = 'h2',
+  labelSizeClass = 'text-[0.8125rem]',
+  class: className = '',
+} = Astro.props;
+
+const Heading = headingLevel;
+
+const containerClass = variant === 'card'
+  ? 'p-6 lg:p-8 bg-card rounded-2xl border border-accent/20'
+  : 'p-6 bg-primary/5 rounded-xl border border-primary/15';
+
+const gridClass = columns === 4
+  ? 'grid sm:grid-cols-2 lg:grid-cols-4 gap-6'
+  : columns === 3
+    ? 'grid sm:grid-cols-2 lg:grid-cols-3 gap-6'
+    : 'grid gap-x-8 gap-y-6 sm:grid-cols-2';
+
+const titleClass = 'text-2xl font-display font-semibold text-foreground mb-6 leading-tight';
+
+const labelClass = `${labelSizeClass} uppercase tracking-wider text-muted-foreground mb-1.5 leading-none`;
+
+const valueClass = variant === 'card'
+  ? 'text-lg font-medium text-foreground leading-snug'
+  : 'text-base font-medium text-foreground leading-snug';
+
+const linkColorMap: Record<string, { bg: string; hover: string; text: string }> = {
+  secondary: { bg: 'bg-secondary/10', hover: 'hover:bg-secondary/20', text: 'text-secondary' },
+  primary: { bg: 'bg-primary/10', hover: 'hover:bg-primary/20', text: 'text-primary' },
+  accent: { bg: 'bg-accent/10', hover: 'hover:bg-accent/20', text: 'text-accent-strong' },
+};
+---
+
+{items.length > 0 && (
+  <div class:list={[containerClass, className]} data-pagefind-ignore>
+    {title && <Heading class={titleClass}>{title}</Heading>}
+
+    <dl class={gridClass}>
+      {items.map((item) => (
+        <div class:list={['min-w-0', item.span === 2 && 'sm:col-span-2']}>
+          <dt class={`${labelClass} flex items-center gap-1.5`}>
+            <Icon name={item.icon} class="w-3.5 h-3.5 text-primary/60" />
+            {item.label}
+          </dt>
+          <dd class={`${valueClass} tabular-nums break-words`}>
+            {item.value}
+            {item.href && (
+              <a
+                href={item.href}
+                target={item.hrefExternal ? '_blank' : undefined}
+                rel={item.hrefExternal ? 'noopener noreferrer' : undefined}
+                class="inline-flex items-center gap-1 text-primary underline decoration-primary/40 hover:text-primary-strong hover:decoration-primary transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary rounded-sm ml-2 text-sm"
+              >
+                {item.hrefLabel || item.href}
+                {item.hrefExternal && <Icon name="external-link" class="w-3.5 h-3.5 shrink-0" />}
+              </a>
+            )}
+          </dd>
+        </div>
+      ))}
+    </dl>
+
+    {/* has('after') is true when the slot is passed, even if it renders nothing: empty:hidden collapses the gap, and
+        the slot stays on one line because :empty does not match a whitespace text node. */}
+    {Astro.slots.has('after') && (
+      <div class="mt-6 empty:hidden"><slot name="after" /></div>
+    )}
+
+    {links && links.length > 0 && (
+      <div class="mt-6 pt-6 border-t border-border flex flex-wrap gap-3">
+        {links.map((link) => {
+          const colors = linkColorMap[link.color] || linkColorMap.secondary;
+          return (
+            <a
+              href={link.href}
+              target="_blank"
+              rel="noopener noreferrer"
+              class={`inline-flex items-center gap-2 px-4 py-2.5 ${colors.bg} ${colors.hover} ${colors.text} rounded-lg transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary`}
+            >
+              <Icon name={link.icon} class="w-5 h-5" />
+              <span class="text-sm font-medium">{link.label}</span>
+              <Icon name="external-link" class="w-4 h-4" />
+            </a>
+          );
+        })}
+      </div>
+    )}
+  </div>
+)}

package/src/composed/TableOfContents.astro

@@ -0,0 +1,156 @@
+---
+// Section jump pills in two rails (a mobile <details> list and a desktop pill row), plus, for the card variant, a
+// sticky mini bar that appears once the main ToC has scrolled away. The controller marks the pill of the section in
+// view (data-active + aria-current).
+//
+// The header renders only when something fills it: `title` defaults to '', and an unconditional <h2> shipped an
+// empty heading on every caller that omits one (SLA-2340); `mb-2` sits behind `title` so an eyebrow-only header does
+// not double the gap.
+import Chip from '../primitives/Chip.astro';
+
+interface TableOfContentsItem {
+  label: string;
+  href: string;
+  sectionId?: string;
+}
+
+interface Props {
+  title?: string;
+  items: TableOfContentsItem[];
+  /** Defaults to the title, else 'Table of contents'. */
+  ariaLabel?: string;
+  eyebrow?: string;
+  description?: string;
+  class?: string;
+  eyebrowClass?: string;
+  variant?: 'card' | 'plain';
+  showHeader?: boolean;
+  navClass?: string;
+  linkClass?: string;
+  sectionSelector?: string;
+  /** Extra classes on the sticky mini bar's pills. */
+  miniLinkClass?: string;
+  /** Hide the mini bar once the reader has scrolled past the last section it links to. */
+  hideMiniPastLastSection?: boolean;
+}
+
+const {
+  title = '',
+  items,
+  ariaLabel = title || 'Table of contents',
+  eyebrow,
+  description,
+  class: className = '',
+  eyebrowClass = 'text-primary',
+  variant = 'card',
+  showHeader = true,
+  navClass: navClassName = '',
+  linkClass: linkClassName = '',
+  sectionSelector = '[data-guide-section], section[id]',
+  miniLinkClass = '',
+  hideMiniPastLastSection = false,
+} = Astro.props;
+
+const resolveSectionId = (item: TableOfContentsItem) =>
+  item.sectionId ?? (item.href.startsWith('#') ? item.href.slice(1) : undefined);
+
+const rootClass = variant === 'card' ? 'rounded-2xl border border-border bg-card p-6 lg:p-8' : '';
+const defaultNavClass =
+  variant === 'card' ? 'flex gap-2 overflow-x-auto pb-2 md:flex-wrap md:pb-0' : 'flex gap-2 overflow-x-auto';
+// Card variant sits on a bg-card ancestor, so its idle pill needs the muted fill to read as a
+// control; plain variant already sits on bg-card, so it uses the plain outline tone instead.
+const mainTone = variant === 'card' ? 'outlineMuted' : 'outline';
+
+const showMini = variant === 'card';
+---
+
+{showMini && (
+  <div
+    data-toc-mini
+    data-toc
+    data-toc-section-selector={sectionSelector}
+    class="fixed top-16 left-0 right-0 z-40 translate-y-[-100%] opacity-0 pointer-events-none transition-[transform,opacity] duration-300 ease-out bg-background/95 backdrop-blur-sm border-b border-border shadow-sm"
+    aria-hidden="true"
+  >
+    <div class="mx-auto max-w-shell px-4 sm:px-6 lg:px-8 py-2.5">
+      <nav class="flex gap-2 overflow-x-auto scrollbar-hide" aria-label={`${ariaLabel} (sticky)`}>
+        {items.map((item) => (
+          <Chip
+            href={item.href}
+            data-section-link={resolveSectionId(item)}
+            active={false}
+            size="sm"
+            tone="outlineMuted"
+            accent="primary"
+            hover={false}
+            class:list={['shrink-0', miniLinkClass]}
+          >
+            {item.label}
+          </Chip>
+        ))}
+      </nav>
+    </div>
+  </div>
+)}
+
+<section
+  data-toc
+  data-toc-section-selector={sectionSelector}
+  {...(showMini ? { 'data-toc-main': '' } : {})}
+  {...(showMini && hideMiniPastLastSection ? { 'data-toc-hide-past-last': '' } : {})}
+  class:list={[rootClass, className]}
+>
+  {showHeader && (title || eyebrow || description) && (
+    <div class="mb-5 flex flex-col gap-3 lg:flex-row lg:items-end lg:justify-between">
+      <div>
+        {eyebrow && (
+          <p class:list={['text-sm font-medium uppercase tracking-[0.2em]', title ? 'mb-2' : '', eyebrowClass]}>{eyebrow}</p>
+        )}
+        {title && <h2 class="text-2xl font-semibold font-display">{title}</h2>}
+      </div>
+      {description && <p class="max-w-deck text-sm text-muted-foreground">{description}</p>}
+    </div>
+  )}
+
+  <details class="group md:hidden">
+    <summary class="flex min-h-11 cursor-pointer list-none items-center justify-between rounded-lg border border-border bg-muted/40 px-4 py-2.5 text-sm font-medium text-foreground marker:content-none">
+      Jump to a section
+      <span class="text-primary transition-transform group-open:rotate-180" aria-hidden="true">⌄</span>
+    </summary>
+    <nav class="mt-3 grid gap-2" aria-label={ariaLabel}>
+      {items.map((item) => (
+        <a
+          href={item.href}
+          data-section-link={resolveSectionId(item)}
+          class="rounded-lg border border-border px-3 py-2.5 text-sm text-foreground transition-colors hover:border-primary/40 hover:text-primary"
+        >
+          {item.label}
+        </a>
+      ))}
+    </nav>
+  </details>
+
+  <nav class:list={['hidden md:flex', defaultNavClass, navClassName]} aria-label={ariaLabel}>
+    {items.map((item) => (
+      <Chip
+        href={item.href}
+        data-section-link={resolveSectionId(item)}
+        active={false}
+        size="md"
+        tone={mainTone}
+        accent="primary"
+        hover={false}
+        class:list={['shrink-0', linkClassName]}
+      >
+        {item.label}
+      </Chip>
+    ))}
+  </nav>
+</section>
+
+<script>
+  import { initTableOfContents } from './toc.ts';
+
+  initTableOfContents();
+  document.addEventListener('astro:page-load', initTableOfContents);
+</script>

package/src/composed/carousel.ts

@@ -0,0 +1,116 @@
+// CardCarousel's controller. One module per page, however many carousels it holds: each instance is found by its
+// data attributes and initialised once (data-carousel-ready), so a re-run after astro:page-load is a no-op.
+
+const ACTIVE = 'var(--carousel-dot, var(--color-primary))';
+const INACTIVE = 'rgba(120,120,130,0.35)';
+const EDGE_SLOP = 4;
+
+function initCarousel(section: HTMLElement): void {
+  const track = section.querySelector<HTMLElement>('[data-carousel-track]');
+  if (!track) return;
+  const cards = Array.from(track.children) as HTMLElement[];
+  if (cards.length === 0) return;
+
+  const arrowsWrap = section.querySelector<HTMLElement>('[data-carousel-arrows]');
+  const prevBtn = section.querySelector<HTMLButtonElement>('[data-carousel-prev]');
+  const nextBtn = section.querySelector<HTMLButtonElement>('[data-carousel-next]');
+  const dotsWrap = section.querySelector<HTMLElement>('[data-carousel-dots]');
+  let currentIndex = 0;
+
+  const dots: HTMLButtonElement[] = [];
+  if (dotsWrap) {
+    cards.forEach((_, i) => {
+      const dot = document.createElement('button');
+      dot.type = 'button';
+      dot.setAttribute('aria-label', `Go to item ${i + 1}`);
+      dot.style.cssText =
+        'height:0.375rem;border-radius:9999px;transition:all 0.2s;border:0;cursor:pointer;padding:0;' +
+        (i === 0 ? `width:1rem;background:${ACTIVE};` : `width:0.375rem;background:${INACTIVE};`);
+      dot.addEventListener('click', () => scrollToIndex(i));
+      dotsWrap.appendChild(dot);
+      dots.push(dot);
+    });
+  }
+
+  const isScrollable = () => track.scrollWidth - track.clientWidth > EDGE_SLOP;
+
+  function updateUI(idx: number, atLeft?: number): void {
+    const left = typeof atLeft === 'number' ? atLeft : track!.scrollLeft;
+    const startEdge = left <= EDGE_SLOP;
+    const endEdge = left >= track!.scrollWidth - track!.clientWidth - EDGE_SLOP;
+    // currentIndex is the LEFTMOST VISIBLE card, which is what prev/next step from. Pinning it to the last card at
+    // max scroll made `prev` dead for the first N-1 clicks.
+    currentIndex = Math.max(0, Math.min(idx, cards.length - 1));
+    // Disabled state comes from the scroll position, not the card index: with several cards per view the track hits
+    // max scroll while currentIndex is still mid-list.
+    if (prevBtn) prevBtn.disabled = startEdge;
+    if (nextBtn) nextBtn.disabled = endEdge;
+    // At the extremes the dot shows the first or last card, otherwise the trailing dots could never light up.
+    const dotIndex = endEdge ? cards.length - 1 : startEdge ? 0 : currentIndex;
+    dots.forEach((dot, i) => {
+      const active = i === dotIndex;
+      dot.style.width = active ? '1rem' : '0.375rem';
+      dot.style.background = active ? ACTIVE : INACTIVE;
+    });
+  }
+
+  const reduceMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+
+  // Scroll the TRACK, not via scrollIntoView, which also scrolls the document and jerks the page vertically.
+  function scrollToIndex(idx: number): void {
+    idx = Math.max(0, Math.min(idx, cards.length - 1));
+    const delta = cards[idx].getBoundingClientRect().left - track!.getBoundingClientRect().left;
+    const target = Math.max(0, Math.min(track!.scrollLeft + delta, track!.scrollWidth - track!.clientWidth));
+    track!.scrollTo({ left: target, behavior: reduceMotion ? 'auto' : 'smooth' });
+    // A smooth scroll has not moved scrollLeft yet, so the controls follow where the track is GOING.
+    updateUI(idx, target);
+  }
+
+  let raf = 0;
+  track.addEventListener('scroll', () => {
+    cancelAnimationFrame(raf);
+    raf = requestAnimationFrame(() => {
+      const trackLeft = track.getBoundingClientRect().left;
+      let closest = 0;
+      let min = Infinity;
+      cards.forEach((card, i) => {
+        const d = Math.abs(card.getBoundingClientRect().left - trackLeft);
+        if (d < min) { min = d; closest = i; }
+      });
+      updateUI(closest);
+    });
+  }, { passive: true });
+
+  prevBtn?.addEventListener('click', () => scrollToIndex(currentIndex - 1));
+  nextBtn?.addEventListener('click', () => scrollToIndex(currentIndex + 1));
+
+  // Controls show only when the track overflows; re-checked whenever the track resizes.
+  function syncControls(): void {
+    const show = isScrollable();
+    arrowsWrap?.classList.toggle('hidden', !show);
+    arrowsWrap?.classList.toggle('flex', show);
+    dotsWrap?.classList.toggle('hidden', !show);
+    dotsWrap?.classList.toggle('flex', show);
+  }
+
+  if ('ResizeObserver' in window) {
+    new ResizeObserver(syncControls).observe(track);
+  } else {
+    let resizeRaf = 0;
+    window.addEventListener('resize', () => {
+      cancelAnimationFrame(resizeRaf);
+      resizeRaf = requestAnimationFrame(syncControls);
+    }, { passive: true });
+    window.addEventListener('load', syncControls, { once: true });
+  }
+
+  syncControls();
+  updateUI(0);
+}
+
+export function initCarousels(): void {
+  document.querySelectorAll<HTMLElement>('[data-carousel]:not([data-carousel-ready])').forEach((section) => {
+    section.setAttribute('data-carousel-ready', '');
+    initCarousel(section);
+  });
+}

package/src/composed/index.ts

@@ -1,2 +1,7 @@
-// Public surface of @sarimarcus/content-sites-ui/composed. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-ui/composed.
+export { default as TableOfContents } from './TableOfContents.astro';
+export { default as CardCarousel } from './CardCarousel.astro';
+export { default as QuickFacts } from './QuickFacts.astro';
+export { default as FAQ } from './FAQ.astro';
+export { default as InlineImage } from './InlineImage.astro';
+export { default as Pagination } from './Pagination.astro';

package/src/composed/toc.ts

@@ -0,0 +1,105 @@
+// TableOfContents' controller: marks the pill of the section in view on every ToC of the page, and shows each card
+// ToC's sticky mini bar once the main ToC has scrolled away. Re-running it (astro:page-load) disconnects the previous
+// observers first, so it is idempotent however many ToCs the page holds.
+
+let cleanup: (() => void) | null = null;
+
+function setMiniVisible(mini: Element, visible: boolean): void {
+  mini.classList.toggle('translate-y-[-100%]', !visible);
+  mini.classList.toggle('opacity-0', !visible);
+  mini.classList.toggle('pointer-events-none', !visible);
+  mini.classList.toggle('translate-y-0', visible);
+  mini.classList.toggle('opacity-100', visible);
+  mini.classList.toggle('pointer-events-auto', visible);
+  mini.setAttribute('aria-hidden', visible ? 'false' : 'true');
+  document.dispatchEvent(new CustomEvent('toc:mini-visibility-change', { detail: { visible } }));
+}
+
+const linksOf = (root: Element) => Array.from(root.querySelectorAll<HTMLElement>('[data-section-link]'));
+
+export function initTableOfContents(): void {
+  cleanup?.();
+  const observers: IntersectionObserver[] = [];
+
+  const groups = new Map<string, Element[]>();
+  for (const root of document.querySelectorAll('[data-toc]')) {
+    if (linksOf(root).length === 0) continue;
+    const selector = root.getAttribute('data-toc-section-selector') || '[data-guide-section]';
+    if (!groups.has(selector)) groups.set(selector, []);
+    groups.get(selector)!.push(root);
+  }
+
+  groups.forEach((roots, sectionSelector) => {
+    // Observe ONLY sections a pill points at: the default selector's `section[id]` half also matches unrelated page
+    // furniture (a runtime-injected cookie-consent section), which would otherwise blank every pill (SLA-2340).
+    const linkIds = new Set<string>();
+    roots.forEach((root) => linksOf(root).forEach((link) => link.dataset.sectionLink && linkIds.add(link.dataset.sectionLink)));
+    const sections = Array.from(document.querySelectorAll<HTMLElement>(sectionSelector))
+      .filter((s) => s.id && (linkIds.size === 0 || linkIds.has(s.id)));
+    if (sections.length === 0) return;
+
+    const firstSectionId = sections[0].id;
+    let activeSectionId = '';
+    const setActiveSection = (sectionId: string) => {
+      if (!sectionId || activeSectionId === sectionId) return;
+      activeSectionId = sectionId;
+      roots.forEach((root) => {
+        linksOf(root).forEach((link) => {
+          const isActive = link.dataset.sectionLink === sectionId;
+          link.dataset.active = isActive ? 'true' : 'false';
+          if (isActive) {
+            link.setAttribute('aria-current', 'location');
+            if (root.hasAttribute('data-toc-mini')) link.scrollIntoView({ behavior: 'smooth', block: 'nearest', inline: 'nearest' });
+          } else {
+            link.removeAttribute('aria-current');
+          }
+        });
+      });
+      document.dispatchEvent(new CustomEvent('toc:active-section-change', { detail: { firstSectionId, sectionId, sectionSelector } }));
+    };
+
+    const intersecting = new Set<Element>();
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach((e) => (e.isIntersecting ? intersecting.add(e.target) : intersecting.delete(e.target)));
+      if (intersecting.size === 0) return;
+      const top = sections.find((s) => intersecting.has(s));
+      if (top) setActiveSection(top.id);
+    }, { rootMargin: '-22% 0px -55% 0px', threshold: [0, 0.1, 0.25, 0.45, 0.7] });
+    sections.forEach((s) => observer.observe(s));
+    observers.push(observer);
+  });
+
+  for (const mainToc of document.querySelectorAll('[data-toc-main]')) {
+    const mini = mainToc.previousElementSibling;
+    if (!mini?.hasAttribute('data-toc-mini')) continue;
+    let mainAbove = false;
+    let pastLast = false;
+    const apply = () => setMiniVisible(mini, mainAbove && !pastLast);
+
+    // Visible only once the main ToC has scrolled FULLY above the viewport: !isIntersecting alone is also true
+    // before the reader has reached it, which fired the mini bar on page load.
+    const miniObserver = new IntersectionObserver((entries) => {
+      mainAbove = entries[0].boundingClientRect.bottom < 0;
+      apply();
+    }, { threshold: 0 });
+    miniObserver.observe(mainToc);
+    observers.push(miniObserver);
+
+    if (mainToc.hasAttribute('data-toc-hide-past-last')) {
+      const selector = mainToc.getAttribute('data-toc-section-selector') || '[data-guide-section]';
+      const linked = new Set(linksOf(mainToc).map((l) => l.dataset.sectionLink));
+      const sections = Array.from(document.querySelectorAll(selector)).filter((s) => s.id && (linked.size === 0 || linked.has(s.id)));
+      const last = sections[sections.length - 1];
+      if (last) {
+        const lastObserver = new IntersectionObserver((entries) => {
+          pastLast = entries[0].boundingClientRect.bottom < 0;
+          apply();
+        }, { threshold: 0 });
+        lastObserver.observe(last);
+        observers.push(lastObserver);
+      }
+    }
+  }
+
+  cleanup = () => observers.forEach((o) => o.disconnect());
+}

package/src/layout/Container.astro

@@ -1,8 +1,8 @@
 ---
-// GENERATED by scripts/width-tokens/sync.mjs (factory root) — DO NOT EDIT.
+// GENERATED by scripts/platform/ui-widths.mjs (factory root) — DO NOT EDIT.
 //
-// Canonical widths live in scripts/width-tokens/tokens.json (SLA-2421); the tokens themselves ship
-// as @sarimarcus/content-sites-ui/widths.css. The sync --check gate rejects drift.
+// Canonical widths live in packages/ui/width-tokens.json (SLA-2421); the tokens themselves ship
+// as @sarimarcus/content-sites-ui/widths.css. The ui-widths --check gate rejects drift.
 //
 // `size` names a width token. Container is the sanctioned way to build a centred rail
 // with the standard gutter. Two token names are deliberately NOT sizes here:

package/src/styles/widths.css

@@ -1,4 +1,4 @@
-/* GENERATED by scripts/width-tokens/sync.mjs from scripts/width-tokens/tokens.json — DO NOT EDIT.
+/* GENERATED by scripts/platform/ui-widths.mjs from packages/ui/width-tokens.json — DO NOT EDIT.
    A site imports it where its width region used to be, so the theme variables keep their order. */
 @theme {
   --container-shell:        80rem;  /* 1280 — was max-w-7xl */

package/src/types/index.ts

@@ -1,2 +1,17 @@
-// Public surface of @sarimarcus/content-sites-ui/types. Components land here from SLA-2742 on.
-export {};
+// Public surface of @sarimarcus/content-sites-ui/types.
+
+declare const trusted: unique symbol;
+
+/**
+ * HTML a site has already rendered from its own authored content (markdown, footnotes). Package components never
+ * convert markdown themselves; a string crosses the package boundary as HTML only through trustedHtml().
+ */
+export type TrustedHtml = string & { readonly [trusted]: true };
+
+/** Mark site-rendered HTML as safe to inject with set:html. */
+export const trustedHtml = (html: string): TrustedHtml => html as TrustedHtml;
+
+const ESCAPES: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+/** Plain text as HTML, escaped the way Astro escapes an `{expression}`. */
+export const textAsHtml = (text: string): TrustedHtml => text.replace(/[&<>"']/g, (c) => ESCAPES[c]) as TrustedHtml;