@sarimarcus/content-sites-ui 0.18.0 → 0.20.0

package/src/editorial/interludes/RelatedCard.astro

@@ -0,0 +1,87 @@
+---
+/**
+ * RelatedCard — an in-article link to another page. `inline`: a ruled "read next" row. `featured`: the mid-article
+ * feature card, image left. The site resolves href, eyebrow and image; an unresolved target should render nothing.
+ */
+import type { ImageMetadata } from 'astro';
+import { Picture } from 'astro:assets';
+import Icon from '../../primitives/Icon.astro';
+
+interface Props {
+  href: string;
+  /** Full eyebrow text, e.g. "Read next · Monument". */
+  eyebrow: string;
+  title: string;
+  description?: string;
+  variant?: 'inline' | 'featured';
+  image?: ImageMetadata;
+  imageAlt?: string;
+  eyebrowClass?: string;
+}
+const { href, eyebrow, title, description, variant = 'inline', image, imageAlt, eyebrowClass } = Astro.props;
+---
+
+{variant === 'inline' ? (
+  <a
+    href={href}
+    class="group not-prose my-8 flex items-center justify-between gap-6 py-4 border-y border-border hover:border-primary/60 focus:outline-none focus-visible:ring-2 focus-visible:ring-primary/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background transition-colors"
+  >
+    <div class="min-w-0 flex-1">
+      <p class={eyebrowClass ?? 'text-xs font-semibold uppercase tracking-[0.16em] text-primary mb-1'}>
+        {eyebrow}
+      </p>
+      <h4 class="text-base sm:text-lg font-semibold font-display text-foreground leading-snug group-hover:text-primary transition-colors">
+        {title}
+      </h4>
+      {description && (
+        <p class="mt-1 text-sm text-muted-foreground leading-relaxed line-clamp-2">{description}</p>
+      )}
+    </div>
+    <Icon
+      name="arrow-right"
+      class="shrink-0 w-5 h-5 text-primary transition-transform motion-safe:group-hover:translate-x-1"
+      aria-hidden="true"
+    />
+  </a>
+) : (
+  <a
+    href={href}
+    class="group not-prose my-8 flex flex-col sm:flex-row overflow-hidden rounded-xl border border-border bg-card hover:border-primary focus:outline-none focus-visible:ring-2 focus-visible:ring-primary/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background transition-colors"
+  >
+    <div class="sm:w-2/5 shrink-0 overflow-hidden bg-muted aspect-video sm:aspect-auto">
+      {image ? (
+        <Picture
+          src={image}
+          alt={imageAlt ?? title}
+          widths={[320, 480]}
+          sizes="(min-width: 640px) 40vw, 100vw"
+          formats={['avif', 'webp']}
+          fallbackFormat="webp"
+          class="w-full h-full object-cover"
+          loading="lazy"
+        />
+      ) : (
+        <div class="w-full h-full min-h-[160px] sm:min-h-full bg-muted" />
+      )}
+    </div>
+
+    <div class="flex flex-col justify-center gap-2 p-5 sm:p-6 min-w-0 flex-1">
+      <p class={eyebrowClass ?? 'text-xs font-medium uppercase tracking-[0.16em] text-primary'}>
+        {eyebrow}
+      </p>
+      <h4 class="text-lg font-semibold font-display text-foreground leading-snug group-hover:text-primary transition-colors">
+        {title}
+      </h4>
+      {description && (
+        <p class="text-sm text-muted-foreground leading-relaxed line-clamp-2">{description}</p>
+      )}
+      <div class="flex justify-end mt-1">
+        <Icon
+          name="arrow-right"
+          class="w-4 h-4 text-primary transition-transform motion-safe:group-hover:translate-x-1"
+          aria-hidden="true"
+        />
+      </div>
+    </div>
+  </a>
+)}

package/src/editorial/interludes/StatFact.astro

@@ -0,0 +1,18 @@
+---
+import type { TrustedHtml } from '../../types';
+
+interface Props {
+  figure: TrustedHtml;
+  caption: TrustedHtml;
+}
+const { figure, caption } = Astro.props;
+---
+
+<figure class="my-16 sm:my-20 text-center">
+  <span class="block mx-auto h-px w-12 bg-primary/40 mb-6" aria-hidden="true"></span>
+  <p
+    class="font-display text-5xl sm:text-6xl text-primary leading-none tracking-[-0.03em] tabular-nums"
+    set:html={figure}
+  />
+  <figcaption class="mt-5 text-sm leading-relaxed text-muted-foreground max-w-md mx-auto" set:html={caption} />
+</figure>

package/src/editorial/interludes/Timeline.astro

@@ -0,0 +1,34 @@
+---
+import type { TrustedHtml } from '../../types';
+
+interface TimelineEvent {
+  date: string;
+  label: TrustedHtml;
+  description?: TrustedHtml;
+}
+interface Props {
+  events: TimelineEvent[];
+  /** Figcaption, e.g. "Timeline". */
+  label: string;
+}
+const { events, label } = Astro.props;
+---
+
+<figure class="my-8 p-6 sm:p-7 rounded-lg bg-card border border-border">
+  <figcaption class="text-xs font-semibold uppercase tracking-[0.18em] text-secondary mb-5">{label}</figcaption>
+  <ol class="space-y-4">
+    {events.map((event) => (
+      <li class="grid grid-cols-[5rem_1fr] sm:grid-cols-[7rem_1fr] gap-x-4 gap-y-1">
+        <span class="text-sm font-semibold font-display text-secondary tabular-nums leading-snug pt-0.5">
+          {event.date}
+        </span>
+        <div>
+          <p class="text-sm sm:text-base font-semibold text-foreground leading-snug" set:html={event.label} />
+          {event.description && (
+            <p class="mt-1 text-sm text-muted-foreground leading-relaxed" set:html={event.description} />
+          )}
+        </div>
+      </li>
+    ))}
+  </ol>
+</figure>

package/src/editorial/interludes/Tldr.astro

@@ -0,0 +1,40 @@
+---
+/**
+ * Tldr — end-of-section summary: a prose paragraph (`content`) or a "key takeaways" list (`bullets`).
+ * An authored `title` wins over the shape's label.
+ */
+import type { TrustedHtml } from '../../types';
+
+interface Props {
+  content?: TrustedHtml;
+  bullets?: TrustedHtml[];
+  title?: string;
+  /** Heading for the bullets shape, e.g. "Key takeaways". */
+  bulletsLabel: string;
+  /** Heading for the prose shape, e.g. "In short". */
+  proseLabel: string;
+}
+const { content, bullets = [], title, bulletsLabel, proseLabel } = Astro.props;
+const hasBullets = bullets.length > 0;
+const heading = title ?? (hasBullets ? bulletsLabel : proseLabel);
+---
+
+<aside class="my-8 p-5 sm:p-6 rounded-lg bg-muted border border-border">
+  <p class="inline-block text-xs font-semibold uppercase tracking-[0.18em] text-muted-foreground mb-3 pb-1 border-b border-accent">
+    {heading}
+  </p>
+  {hasBullets ? (
+    /* list-none + an absolute dot: the aside sits inside .article-body, whose `ul` rule would add its own
+       padding and marker. */
+    <ul class="m-0 list-none space-y-2.5 p-0">
+      {bullets.map((b) => (
+        <li class="relative pl-6 text-sm sm:text-base leading-relaxed text-foreground">
+          <span class="absolute left-0 top-[0.62em] block h-1.5 w-1.5 rounded-full bg-primary" aria-hidden="true"></span>
+          <span set:html={b} />
+        </li>
+      ))}
+    </ul>
+  ) : (
+    <p class="text-sm sm:text-base leading-relaxed text-foreground" set:html={content} />
+  )}
+</aside>

package/src/editorial/interludes/types.ts

@@ -0,0 +1,36 @@
+import type { InterludeType } from '@sarimarcus/content-sites-core/interludes';
+import type { TrustedHtml } from '../../types';
+
+/** One authored interlude as the content layer returns it. String fields are markdown until `renderInline` runs. */
+export type InterludeData =
+  | { type: 'quote'; variant: 'pull' | 'external'; content: string; attribution?: { name: string; role?: string } }
+  | { type: 'stat-fact'; figure: string; caption: string }
+  | { type: 'evidence-context'; finding: string; basis: string; boundary: string }
+  | { type: 'tldr'; content?: string; bullets?: string[]; title?: string }
+  | { type: 'answer-box'; question: string; answer: string }
+  | { type: 'field-note'; content: string }
+  | { type: 'caution'; variant: 'tip' | 'warning' | 'info'; title?: string; content: string }
+  | { type: 'checklist'; title: string; items: string[] }
+  | { type: 'did-you-know'; content: string }
+  | { type: 'timeline'; events: Array<{ date: string; label: string; description?: string }> }
+  | { type: 'comparison-table'; headers: string[]; rows: string[][] }
+  /** Entity interludes: the site resolves the target and renders RelatedCard itself. */
+  | { type: 'related-card' | 'monument-feature' | 'article-feature' };
+
+// Fails to compile when core's union gains or loses a tag this type does not mirror.
+type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+const mirrorsCore: Same<InterludeData['type'], InterludeType> = true;
+void mirrorsCore;
+
+/** Every string the interludes print. */
+export interface InterludeLabels {
+  answerBox: string;
+  evidence: { title: string; finding: string; basis: string; boundary: string };
+  fieldNote: string;
+  timeline: string;
+  tldr: { bullets: string; prose: string };
+  didYouKnow: string;
+}
+
+/** The site's inline markdown renderer: links resolved against its base path, footnote markers bounded. */
+export type RenderInline = (markdown: string) => TrustedHtml;

package/src/editorial/types.ts

@@ -0,0 +1,68 @@
+import type { ImageMetadata } from 'astro';
+import type { TrustedHtml } from '../types';
+import type { SourceInput } from '../seo/types';
+
+/** A person as listed on author strips and cards. The byline shape is ui/seo `ArticleAuthor`. */
+export interface AuthorSummary {
+  name: string;
+  /** Profile URL, base path already applied. */
+  href: string;
+  /** Optimised portrait, or a public URL with the base path applied. */
+  image?: ImageMetadata | string;
+}
+
+/** One article as a card or grid entry. Dates arrive formatted, so the package never picks a time zone. */
+export interface ArticleSummary {
+  href: string;
+  title: string;
+  description: string;
+  author?: string;
+  image?: ImageMetadata;
+  imageAlt?: string;
+  /** ISO value for `<time datetime>`: dateModified when `updated`, else datePublished. */
+  dateTime?: string;
+  dateLabel?: string;
+  updated?: boolean;
+  /** Pre-composed reading-time text, e.g. "6 min read". */
+  readingLabel?: string;
+}
+
+/** A key-fact tile. `detailHtml` is parsed by the site, so footnote markers resolve. */
+export interface KeyFact {
+  figure: string;
+  label: string;
+  detailHtml?: TrustedHtml;
+}
+
+export type SourceItem = SourceInput;
+
+/** One category chip in an article topic nav. */
+export interface ArticleCategoryLink {
+  href: string;
+  label: string;
+  icon?: string;
+  count: number;
+  active: boolean;
+}
+
+export type InsiderTipTone = 'primary' | 'accent' | 'secondary' | 'muted';
+
+/** Site-defined tip kinds: the key stored in content, its badge label and its tone. */
+export type InsiderTipKinds = Record<string, { label: string; tone: InsiderTipTone }>;
+
+export interface InsiderTip {
+  kind: string;
+  title: string;
+  bodyHtml: TrustedHtml;
+}
+
+export interface InsiderTipAuthor {
+  name: string;
+  href?: string;
+  /** Portrait URL, base path already applied. */
+  photoSrc?: string;
+  portraitAlt: string;
+  /** Pre-joined expertise line. */
+  expertise?: string;
+  credentials?: string;
+}