ferst-core 0.7.2 → 0.7.5

package/components/recipes/Document.astro

@@ -0,0 +1,157 @@
+---
+/**
+ * Document — a policy or legal text as ONE block. Sections are numbered automatically,
+ * a contents list links to each (beside the text, sticky, on wide screens), and an
+ * optional "last updated" line sits at the top. Section bodies take prose formatting
+ * (links, bold, lists); `items` add a list. Print-friendly: the contents list is
+ * dropped on paper.
+ */
+import { proseParts } from '../../lib/prose';
+import { inlineMarkdown } from '../../lib/inline-markdown';
+import { longDate } from '../../lib/documents';
+import { pageSlugs, uniqueSlug } from '../../lib/slug';
+
+interface Section { title: string; body?: string; items?: string[] }
+interface Props {
+  intro?: string;
+  updated?: string;
+  numbered?: boolean;
+  toc?: boolean;
+  sections: Section[];
+}
+const { intro, updated, numbered = true, toc = true, sections = [] } = Astro.props;
+const updatedLabel = longDate(updated);
+const showToc = toc && sections.length > 1;
+// Readable anchors that survive renumbering (#payment); #clause-N stays on the heading.
+const used = pageSlugs(Astro.locals);
+const ids = sections.map((s) => uniqueSlug(s.title, used));
+---
+
+<section class="b-doc" data-toc={showToc ? 'true' : undefined}>
+  {showToc && (
+    <nav class="b-doc__toc" aria-label="Contents">
+      <p class="b-doc__toc-title">Contents</p>
+      <ol>
+        {sections.map((s, i) => (
+          <li><a href={`#${ids[i]}`}>{numbered && <span class="b-doc__toc-num">{i + 1}.</span>} {s.title}</a></li>
+        ))}
+      </ol>
+    </nav>
+  )}
+  <div class="b-doc__body">
+    {updatedLabel && <p class="b-doc__updated">Last updated {updatedLabel}</p>}
+    {intro && <p class="b-doc__intro" set:html={inlineMarkdown(intro)} />}
+    {sections.map((s, i) => (
+      <section class="b-doc__clause" id={ids[i]}>
+        <h2 id={`clause-${i + 1}`}>{numbered && <span class="b-doc__num">{i + 1}.</span>} {s.title}</h2>
+        {proseParts(s.body).map((part) =>
+          part.kind === 'p' ? <p set:html={part.html} />
+          : part.kind === 'ul' ? <ul>{part.items.map((x) => <li set:html={x} />)}</ul>
+          : <ol>{part.items.map((x) => <li set:html={x} />)}</ol>
+        )}
+        {s.items && s.items.length > 0 && <ul>{s.items.map((x) => <li set:html={inlineMarkdown(x)} />)}</ul>}
+      </section>
+    ))}
+  </div>
+</section>
+
+<style>
+  .b-doc {
+    display: grid;
+    gap: 2rem;
+    width: 100%;
+    max-width: 64rem;
+  }
+  @media (min-width: 64em) {
+    .b-doc[data-toc] {
+      grid-template-columns: 15rem minmax(0, 1fr);
+      align-items: start;
+    }
+    .b-doc__toc {
+      position: sticky;
+      top: 6rem;
+    }
+  }
+  .b-doc__toc {
+    border: var(--card-border);
+    border-radius: var(--radius);
+    background: var(--bg-surface);
+    padding: 1rem 1.1rem;
+  }
+  .b-doc__toc-title {
+    margin: 0 0 0.5rem;
+    font-size: 0.75rem;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--muted);
+  }
+  .b-doc__toc ol {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: grid;
+    gap: 0.35rem;
+    font-size: 0.9375rem;
+  }
+  .b-doc__toc a {
+    color: var(--fg);
+    text-decoration: none;
+  }
+  .b-doc__toc a:hover {
+    color: var(--gold);
+    text-decoration: underline;
+  }
+  .b-doc__toc-num {
+    color: var(--muted);
+    font-variant-numeric: tabular-nums;
+  }
+  .b-doc__body {
+    max-width: var(--max);
+    display: flex;
+    flex-direction: column;
+    gap: 1.75rem;
+  }
+  .b-doc__updated {
+    margin: 0;
+    font-size: 0.875rem;
+    color: var(--muted);
+  }
+  .b-doc__intro {
+    margin: 0;
+    font-size: 1.125rem;
+    line-height: 1.6;
+    color: var(--muted);
+  }
+  .b-doc__clause {
+    scroll-margin-top: 6rem;
+  }
+  .b-doc__clause h2 {
+    scroll-margin-top: 6rem;
+    margin: 0 0 0.6rem;
+    font-size: 1.25rem;
+  }
+  .b-doc__num {
+    color: var(--gold);
+    font-variant-numeric: tabular-nums;
+  }
+  .b-doc__clause p,
+  .b-doc__clause ul,
+  .b-doc__clause ol {
+    margin: 0 0 0.75rem;
+    line-height: 1.7;
+  }
+  .b-doc__clause ul,
+  .b-doc__clause ol {
+    padding-inline-start: 1.4em;
+  }
+  .b-doc__clause :global(a) {
+    color: var(--accent);
+    text-decoration: underline;
+    text-underline-offset: 0.15em;
+  }
+  @media print {
+    .b-doc__toc { display: none; }
+    .b-doc[data-toc] { grid-template-columns: 1fr; }
+  }
+</style>

package/components/recipes/FeatureCards.astro

@@ -1,111 +1,112 @@
----
-/**
- * FeatureCards — a Level-2 recipe: an optional section header over a responsive
- * grid of cards, each with an optional icon, a title, text, and an optional
- * link. Composes the Card, Icon, Heading and Button primitives.
- */
-import Heading from '../blocks/Heading.astro';
-import Card from '../Card.astro';
-import Icon from '../Icon.astro';
-import Button from '../Button.astro';
-import { isIconKey } from '../../lib/icons';
-
-interface Props {
-  title?: string;
-  intro?: string;
-  columns?: 2 | 3 | 4;
-  cards?: { icon?: string; title: string; text?: string; href?: string }[];
-}
-const { title, intro, columns = 3, cards = [] } = Astro.props;
-// Never reserve more columns than there are cards (a lone card in a 3-col grid
-// would strand two empty cells); `data-single` centres a solitary card.
-const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3 | 4;
----
-
-<section class="b-feature-cards">
-  {(title || intro) && (
-    <div class="b-feature-cards__head">
-      {title && <Heading text={title} level={2} align="center" />}
-      {intro && <p class="b-feature-cards__intro">{intro}</p>}
-    </div>
-  )}
-  <div class="b-feature-cards__grid" data-cols={cols} data-single={cards.length === 1 ? 'true' : undefined}>
-    {cards.map((card) => (
-      <Card>
-        {card.icon && isIconKey(card.icon) && (
-          <span class="b-feature-cards__icon"><Icon name={card.icon} size={28} /></span>
-        )}
-        <h3 class="b-feature-cards__title">{card.title}</h3>
-        {card.text && <p class="b-feature-cards__text">{card.text}</p>}
-        {card.href && (
-          <span class="b-feature-cards__cta">
-            <Button href={card.href} variant="secondary" size="sm">Learn more</Button>
-          </span>
-        )}
-      </Card>
-    ))}
-  </div>
-</section>
-
-<style>
-  .b-feature-cards {
-    display: flex;
-    flex-direction: column;
-    gap: 2rem;
-    max-width: 72rem;
-    margin-inline: auto;
-    padding-inline: 1rem;
-  }
-  .b-feature-cards__head {
-    max-width: var(--max);
-    margin-inline: auto;
-    text-align: center;
-    display: flex;
-    flex-direction: column;
-    gap: 0.75rem;
-  }
-  .b-feature-cards__intro {
-    margin: 0;
-    color: var(--muted);
-    font-size: 1.0625rem;
-    line-height: 1.6;
-  }
-  .b-feature-cards__grid {
-    display: grid;
-    grid-template-columns: 1fr; /* mobile-first */
-    gap: 1.5rem;
-  }
-  @media (min-width: 48em) {
-    .b-feature-cards__grid[data-cols='2'] { grid-template-columns: repeat(2, 1fr); }
-    .b-feature-cards__grid[data-cols='3'] { grid-template-columns: repeat(3, 1fr); }
-    .b-feature-cards__grid[data-cols='4'] { grid-template-columns: repeat(2, 1fr); }
-  }
-  /* A solitary card is a centred feature, not a full-width slab. */
-  .b-feature-cards__grid[data-single] { max-width: 26rem; margin-inline: auto;
-  }
-  @media (min-width: 64em) {
-    .b-feature-cards__grid[data-cols='4'] { grid-template-columns: repeat(4, 1fr); }
-  }
-  .b-feature-cards__icon {
-    color: var(--gold);
-    margin-bottom: 0.5rem;
-    display: inline-flex;
-  }
-  .b-feature-cards__title {
-    margin: 0 0 0.5rem;
-    font-size: 1.125rem;
-    color: var(--fg);
-  }
-  .b-feature-cards__text {
-    margin: 0;
-    color: var(--muted);
-    line-height: 1.6;
-  }
-  /* Push the CTA to the bottom so a row of cards aligns its buttons regardless
-     of how much text each card has. Cards are equal height already (grid items
-     stretch), and Card is a flex column — margin-top:auto does the rest. */
-  .b-feature-cards__cta {
-    margin-top: auto;
-    padding-top: 1rem;
-  }
-</style>
+---
+/**
+ * FeatureCards — a Level-2 recipe: an optional section header over a responsive
+ * grid of cards, each with an optional icon, a title, text, and an optional
+ * link. Composes the Card, Icon, Heading and Button primitives.
+ */
+import Heading from '../blocks/Heading.astro';
+import Card from '../Card.astro';
+import Icon from '../Icon.astro';
+import Button from '../Button.astro';
+import { isIconKey } from '../../lib/icons';
+
+import { inlineMarkdown } from '../../lib/inline-markdown';
+interface Props {
+  title?: string;
+  intro?: string;
+  columns?: 2 | 3 | 4;
+  cards?: { icon?: string; title: string; text?: string; href?: string }[];
+}
+const { title, intro, columns = 3, cards = [] } = Astro.props;
+// Never reserve more columns than there are cards (a lone card in a 3-col grid
+// would strand two empty cells); `data-single` centres a solitary card.
+const cols = Math.min(columns, Math.max(cards.length, 1)) as 1 | 2 | 3 | 4;
+---
+
+<section class="b-feature-cards">
+  {(title || intro) && (
+    <div class="b-feature-cards__head">
+      {title && <Heading text={title} level={2} align="center" />}
+      {intro && <p class="b-feature-cards__intro" set:html={inlineMarkdown(intro)} />}
+    </div>
+  )}
+  <div class="b-feature-cards__grid" data-cols={cols} data-single={cards.length === 1 ? 'true' : undefined}>
+    {cards.map((card) => (
+      <Card>
+        {card.icon && isIconKey(card.icon) && (
+          <span class="b-feature-cards__icon"><Icon name={card.icon} size={28} /></span>
+        )}
+        <h3 class="b-feature-cards__title">{card.title}</h3>
+        {card.text && <p class="b-feature-cards__text" set:html={inlineMarkdown(card.text)} />}
+        {card.href && (
+          <span class="b-feature-cards__cta">
+            <Button href={card.href} variant="secondary" size="sm">Learn more</Button>
+          </span>
+        )}
+      </Card>
+    ))}
+  </div>
+</section>
+
+<style>
+  .b-feature-cards {
+    display: flex;
+    flex-direction: column;
+    gap: 2rem;
+    max-width: 72rem;
+    margin-inline: auto;
+    padding-inline: 1rem;
+  }
+  .b-feature-cards__head {
+    max-width: var(--max);
+    margin-inline: auto;
+    text-align: center;
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+  }
+  .b-feature-cards__intro {
+    margin: 0;
+    color: var(--muted);
+    font-size: 1.0625rem;
+    line-height: 1.6;
+  }
+  .b-feature-cards__grid {
+    display: grid;
+    grid-template-columns: 1fr; /* mobile-first */
+    gap: 1.5rem;
+  }
+  @media (min-width: 48em) {
+    .b-feature-cards__grid[data-cols='2'] { grid-template-columns: repeat(2, 1fr); }
+    .b-feature-cards__grid[data-cols='3'] { grid-template-columns: repeat(3, 1fr); }
+    .b-feature-cards__grid[data-cols='4'] { grid-template-columns: repeat(2, 1fr); }
+  }
+  /* A solitary card is a centred feature, not a full-width slab. */
+  .b-feature-cards__grid[data-single] { max-width: 26rem; margin-inline: auto;
+  }
+  @media (min-width: 64em) {
+    .b-feature-cards__grid[data-cols='4'] { grid-template-columns: repeat(4, 1fr); }
+  }
+  .b-feature-cards__icon {
+    color: var(--gold);
+    margin-bottom: 0.5rem;
+    display: inline-flex;
+  }
+  .b-feature-cards__title {
+    margin: 0 0 0.5rem;
+    font-size: 1.125rem;
+    color: var(--fg);
+  }
+  .b-feature-cards__text {
+    margin: 0;
+    color: var(--muted);
+    line-height: 1.6;
+  }
+  /* Push the CTA to the bottom so a row of cards aligns its buttons regardless
+     of how much text each card has. Cards are equal height already (grid items
+     stretch), and Card is a flex column — margin-top:auto does the rest. */
+  .b-feature-cards__cta {
+    margin-top: auto;
+    padding-top: 1rem;
+  }
+</style>

package/components/recipes/Hero.astro

@@ -24,9 +24,10 @@ interface Props {
   media?: { image?: string; images?: string[]; video?: string; poster?: string; overlay?: number; link?: string; linkLabel?: string };
   layout?: 'centered' | 'split' | 'media';
   size?: 'standard' | 'tall' | 'screen';
+  parallax?: boolean;
   background?: 'none' | 'mesh';
 }
-const { eyebrow, title, subtitle, cta, image, media, layout = 'centered', size = 'standard', background = 'none' } = Astro.props;
+const { eyebrow, title, subtitle, cta, image, media, layout = 'centered', size = 'standard', parallax = false, background = 'none' } = Astro.props;
 // A YouTube / Vimeo link plays as an embedded background (after consent); anything else
 // in `video` is a file for a native <video>.
 const embed = media?.video ? backgroundEmbed(media.video) : null;
@@ -53,6 +54,7 @@ const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
   data-bg={isMesh ? 'mesh' : undefined}
   data-motion={motion}
   data-linked={bgLink ? 'true' : undefined}
+  data-parallax={isMedia && parallax ? 'true' : undefined}
   style={isMedia ? `--hero-overlay: ${overlay}; ${bgImage}` : undefined}
 >
   {isMedia && (
@@ -102,6 +104,7 @@ const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
   // Moving hero backgrounds: pause button, reduced-motion, the slideshow timer, and an
   // embedded (YouTube / Vimeo) background that loads only once the visitor consents.
   import { hasConsent, onConsentChange } from '../../lib/consent-client';
+  import { playerStarted } from '../../lib/video';
   const SLIDE_MS = 6000;
   const reduce = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
   for (const hero of document.querySelectorAll<HTMLElement>('.b-hero[data-motion]')) {
@@ -126,7 +129,18 @@ const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
       player.tabIndex = -1;
       player.setAttribute('aria-hidden', 'true');
       player.allow = 'autoplay; encrypted-media; picture-in-picture';
-      player.addEventListener('load', () => window.setTimeout(() => embedSlot.classList.add('is-on'), 600));
+      // Keep the poster up until the player says it is PLAYING, then cross-fade: no black,
+      // loading player on screen. Ask it to report (YouTube 'listening' / Vimeo listener).
+      const provider = embedSlot.dataset.provider!;
+      const origin = new URL(player.src).origin;
+      window.addEventListener('message', (e) => {
+        if (e.origin !== origin || e.source !== player!.contentWindow) return;
+        if (playerStarted(provider, e.data)) embedSlot.classList.add('is-on');
+      });
+      player.addEventListener('load', () => {
+        const hello = provider === 'Vimeo' ? { method: 'addEventListener', value: 'play' } : { event: 'listening', id: 1, channel: 'widget' };
+        player!.contentWindow?.postMessage(JSON.stringify(hello), origin);
+      });
       embedSlot.appendChild(player);
       if (button) button.hidden = false;
       sync();
@@ -162,11 +176,40 @@ const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
     document.addEventListener('visibilitychange', sync);
     new IntersectionObserver(([e]) => { visible = e.isIntersecting; sync(); }).observe(hero);
     if (embedSlot) {
-      if (hasConsent()) loadPlayer();
-      onConsentChange((allowed) => { if (allowed) loadPlayer(); });
+      // Warm the connection the moment it's allowed, so the video starts sooner.
+      const preconnect = () => {
+        const href = new URL(embedSlot.dataset.embedUrl!).origin;
+        if (document.querySelector(`link[rel="preconnect"][href="${href}"]`)) return;
+        const l = document.createElement('link');
+        l.rel = 'preconnect';
+        l.href = href;
+        document.head.appendChild(l);
+      };
+      if (hasConsent()) { preconnect(); loadPlayer(); }
+      onConsentChange((allowed) => { if (allowed) { preconnect(); loadPlayer(); } });
     }
     sync();
   }
+  // Parallax: the background drifts more slowly than the page. Transform-based, so it works
+  // for an image, slides, a <video> or an embedded player alike. Off on touch devices
+  // (coarse pointers) and under reduced motion; only runs while the hero is on screen.
+  const fine = window.matchMedia('(pointer: fine)').matches;
+  for (const hero of document.querySelectorAll<HTMLElement>('.b-hero[data-parallax]')) {
+    const bg = hero.querySelector<HTMLElement>('.b-hero__bg');
+    if (!bg || reduce || !fine) continue;
+    hero.classList.add('is-parallax');
+    let ticking = false;
+    let onScreen = true;
+    const move = () => {
+      ticking = false;
+      const top = hero.getBoundingClientRect().top;
+      bg.style.transform = `translate3d(0, ${Math.round(Math.max(0, -top) * 0.35)}px, 0)`;
+    };
+    const queue = () => { if (onScreen && !ticking) { ticking = true; requestAnimationFrame(move); } };
+    new IntersectionObserver(([e]) => { onScreen = e.isIntersecting; if (onScreen) queue(); }).observe(hero);
+    window.addEventListener('scroll', queue, { passive: true });
+    move();
+  }
 </script>
 
 <style>
@@ -283,6 +326,11 @@ const bgImage = isMedia && stillSrc ? `--hero-image: url('${stillSrc}')` : '';
     background-position: center;
     background-color: var(--bg-section);
   }
+  /* Parallax: give the background room to drift without uncovering an edge. */
+  .b-hero.is-parallax .b-hero__bg {
+    inset: 0 0 -35% 0;
+    will-change: transform;
+  }
   .b-hero__bg video {
     width: 100%;
     height: 100%;

package/components/recipes/LinkRow.astro

@@ -0,0 +1,91 @@
+---
+/**
+ * LinkRow — a titled row of links as tappable pills (phone, email, web), each with the
+ * icon its link implies (lib/links), plus an optional intro and footnote. For a contact
+ * who doesn't need a whole contact card: "Vocations — phone · email · website".
+ */
+import Heading from '../blocks/Heading.astro';
+import Icon from '../Icon.astro';
+import { linkIcon } from '../../lib/links';
+import { inlineMarkdown } from '../../lib/inline-markdown';
+
+interface Props {
+  title?: string;
+  intro?: string;
+  links: Array<{ label: string; href: string }>;
+  note?: string;
+}
+const { title, intro, links = [], note } = Astro.props;
+const external = (href: string) => /^https?:\/\//i.test(href);
+---
+
+<section class="b-linkrow">
+  {title && <Heading text={title} level={3} />}
+  {intro && <p class="b-linkrow__intro" set:html={inlineMarkdown(intro)} />}
+  <ul class="b-linkrow__links">
+    {links.map((l) => (
+      <li>
+        <a class="b-linkrow__pill" href={l.href} target={external(l.href) ? '_blank' : undefined} rel={external(l.href) ? 'noopener' : undefined}>
+          <Icon name={linkIcon(l.href)} size={18} />
+          <span>{l.label}</span>
+        </a>
+      </li>
+    ))}
+  </ul>
+  {note && <p class="b-linkrow__note" set:html={inlineMarkdown(note)} />}
+</section>
+
+<style>
+  .b-linkrow {
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+    max-width: var(--max);
+  }
+  :global([data-content-align='center']) .b-linkrow {
+    margin-inline: auto;
+    align-items: center;
+    text-align: center;
+  }
+  .b-linkrow__intro,
+  .b-linkrow__note {
+    margin: 0;
+    color: var(--muted);
+    line-height: 1.6;
+  }
+  .b-linkrow__note {
+    font-size: 0.9375rem;
+  }
+  .b-linkrow__links {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+  }
+  .b-linkrow__pill {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.55rem 1rem;
+    border-radius: 999px;
+    border: var(--card-border);
+    background: var(--bg-surface);
+    color: var(--fg);
+    font-weight: 600;
+    text-decoration: none;
+    overflow-wrap: anywhere;
+  }
+  .b-linkrow__pill :global(svg) {
+    color: var(--gold);
+    flex: none;
+  }
+  .b-linkrow__pill:hover {
+    background: var(--bg-section);
+  }
+  .b-linkrow__pill:focus-visible {
+    outline: 2px solid var(--gold);
+    outline-offset: 2px;
+  }
+</style>