ferst-core 0.1.0 → 0.2.1

package/components/blocks/Section.astro

@@ -0,0 +1,52 @@
+---
+/**
+ * A layout container: a full-width band with an optional background and a
+ * width-constrained inner column, holding child blocks (rendered recursively
+ * through BlockRenderer). The first composition primitive — how leaf blocks
+ * become a laid-out page.
+ */
+import BlockRenderer from '../BlockRenderer.astro';
+
+interface Props {
+  background?: 'none' | 'muted' | 'accent';
+  width?: 'normal' | 'wide' | 'full';
+  blocks?: any[];
+}
+const { background = 'none', width = 'normal', blocks = [] } = Astro.props;
+---
+
+<section class="b-section" data-bg={background}>
+  <div class="b-section__inner" data-width={width}>
+    <BlockRenderer blocks={blocks} />
+  </div>
+</section>
+
+<style>
+  .b-section {
+    width: 100%;
+  }
+  .b-section[data-bg='muted'] {
+    background: var(--bg-section);
+  }
+  .b-section[data-bg='accent'] {
+    background: var(--gold-light);
+  }
+  .b-section__inner {
+    margin-inline: auto;
+    padding-inline: 1rem;
+    padding-block: 2.5rem;
+  }
+  .b-section__inner[data-width='normal'] {
+    max-width: var(--max);
+  }
+  .b-section__inner[data-width='wide'] {
+    max-width: 72rem;
+  }
+  .b-section__inner[data-width='full'] {
+    max-width: none;
+  }
+  /* vertical rhythm between direct child blocks */
+  .b-section__inner > :global(* + *) {
+    margin-block-start: 1.5rem;
+  }
+</style>

package/components/blocks/Spacer.astro

@@ -0,0 +1,20 @@
+---
+interface Props {
+  size?: 'sm' | 'md' | 'lg';
+}
+const { size = 'md' } = Astro.props;
+---
+
+<div class="b-spacer" data-size={size} aria-hidden="true"></div>
+
+<style>
+  .b-spacer[data-size='sm'] {
+    height: 1rem;
+  }
+  .b-spacer[data-size='md'] {
+    height: 2rem;
+  }
+  .b-spacer[data-size='lg'] {
+    height: 4rem;
+  }
+</style>

package/components/blocks/Stack.astro

@@ -0,0 +1,30 @@
+---
+/** A layout container: stacks child blocks vertically with a consistent gap. */
+import BlockRenderer from '../BlockRenderer.astro';
+
+interface Props {
+  gap?: 'sm' | 'md' | 'lg';
+  blocks?: any[];
+}
+const { gap = 'md', blocks = [] } = Astro.props;
+---
+
+<div class="b-stack" data-gap={gap}>
+  <BlockRenderer blocks={blocks} />
+</div>
+
+<style>
+  .b-stack {
+    display: flex;
+    flex-direction: column;
+  }
+  .b-stack[data-gap='sm'] {
+    gap: 0.75rem;
+  }
+  .b-stack[data-gap='md'] {
+    gap: 1.5rem;
+  }
+  .b-stack[data-gap='lg'] {
+    gap: 3rem;
+  }
+</style>

package/components/blocks/Stat.astro

@@ -0,0 +1,30 @@
+---
+interface Props {
+  value: string;
+  label: string;
+}
+const { value, label } = Astro.props;
+---
+
+<div class="b-stat">
+  <div class="b-stat__value">{value}</div>
+  <div class="b-stat__label">{label}</div>
+</div>
+
+<style>
+  .b-stat {
+    text-align: center;
+  }
+  .b-stat__value {
+    font-family: var(--font-heading);
+    font-weight: 700;
+    font-size: 2.5rem;
+    line-height: 1;
+    color: var(--gold);
+  }
+  .b-stat__label {
+    margin-top: 0.5rem;
+    color: var(--muted);
+    font-size: 0.9375rem;
+  }
+</style>

package/components/recipes/Accordion.astro

@@ -0,0 +1,84 @@
+---
+/** Accordion — a Level-2 recipe: an optional heading over expand/collapse rows
+ *  (title + body). Generic sibling of FAQ (which is question/answer-flavoured).
+ *  Native <details>/<summary> — accessible, interactive, zero JavaScript. */
+import Heading from '../blocks/Heading.astro';
+
+interface Props {
+  title?: string;
+  items?: { heading: string; body: string }[];
+}
+const { title, items = [] } = Astro.props;
+---
+
+<section class="b-accordion">
+  {title && <Heading text={title} level={2} align="center" />}
+  <div class="b-accordion__list">
+    {items.map((item) => (
+      <details class="b-accordion__item">
+        <summary class="b-accordion__head">{item.heading}</summary>
+        <div class="b-accordion__body"><p>{item.body}</p></div>
+      </details>
+    ))}
+  </div>
+</section>
+
+<style>
+  .b-accordion {
+    display: flex;
+    flex-direction: column;
+    gap: 1.5rem;
+    padding-inline: 1rem;
+  }
+  .b-accordion__list {
+    max-width: var(--max);
+    margin-inline: auto;
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
+  .b-accordion__item {
+    border: var(--card-border);
+    border-radius: var(--radius-sm);
+    padding: 0.25rem 1rem;
+    background: var(--bg-surface);
+  }
+  .b-accordion__head {
+    cursor: pointer;
+    font-weight: 600;
+    color: var(--fg);
+    padding: 0.85rem 0;
+    list-style: none;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem;
+  }
+  .b-accordion__head::-webkit-details-marker {
+    display: none;
+  }
+  .b-accordion__head::after {
+    content: '+';
+    color: var(--gold);
+    font-weight: 700;
+    font-size: 1.25rem;
+    line-height: 1;
+    transition: transform 0.2s ease;
+  }
+  .b-accordion__item[open] .b-accordion__head::after {
+    content: '\2013'; /* en dash */
+  }
+  .b-accordion__head:focus-visible {
+    outline: 2px solid var(--gold);
+    outline-offset: 2px;
+  }
+  .b-accordion__body {
+    padding: 0 0 0.9rem;
+    color: var(--muted);
+    line-height: 1.6;
+  }
+  .b-accordion__body p {
+    margin: 0;
+  }
+</style>

package/components/recipes/Announcement.astro

@@ -0,0 +1,74 @@
+---
+/** Announcement — a Level-2 recipe: a thin full-width bar (message + optional
+ *  link), optionally dismissible. Dismissal persists per `id` in localStorage,
+ *  so a returning visitor doesn't see a bar they've closed. */
+interface Props {
+  text: string;
+  link?: { label: string; href: string };
+  tone?: 'accent' | 'neutral';
+  dismissible?: boolean;
+  id?: string;
+}
+const { text, link, tone = 'accent', dismissible = true, id = 'default' } = Astro.props;
+const key = `ferst-dismissed-${id}`;
+---
+
+<aside class="b-announce" data-tone={tone} data-key={key} role="region" aria-label="Announcement">
+  <p class="b-announce__text">
+    {text}
+    {link && <a class="b-announce__link" href={link.href}>{link.label} &rarr;</a>}
+  </p>
+  {dismissible && (
+    <button type="button" class="b-announce__close" aria-label="Dismiss announcement">&times;</button>
+  )}
+</aside>
+
+<style>
+  .b-announce {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 1rem;
+    padding: 0.6rem 1.25rem;
+    font-size: 0.9rem;
+    text-align: center;
+  }
+  .b-announce[data-tone='accent'] { background: var(--gold); color: var(--text-light); }
+  .b-announce[data-tone='neutral'] { background: var(--bg-section); color: var(--fg); }
+  .b-announce__text { margin: 0; line-height: 1.4; }
+  .b-announce__link {
+    color: inherit;
+    font-weight: 700;
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    white-space: nowrap;
+  }
+  .b-announce[data-tone='neutral'] .b-announce__link { color: var(--gold); }
+  .b-announce__close {
+    appearance: none;
+    background: none;
+    border: none;
+    color: inherit;
+    font-size: 1.4rem;
+    line-height: 1;
+    cursor: pointer;
+    padding: 0 0.25rem;
+    opacity: 0.85;
+    flex-shrink: 0;
+  }
+  .b-announce__close:hover { opacity: 1; }
+  .b-announce__close:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
+</style>
+
+<script>
+  document.querySelectorAll<HTMLElement>('.b-announce').forEach((bar) => {
+    const key = bar.dataset.key;
+    if (key) {
+      try { if (localStorage.getItem(key) === '1') { bar.remove(); return; } } catch (_) {}
+    }
+    bar.querySelector('.b-announce__close')?.addEventListener('click', () => {
+      bar.remove();
+      if (key) { try { localStorage.setItem(key, '1'); } catch (_) {} }
+    });
+  });
+</script>

package/components/recipes/Banner.astro

@@ -0,0 +1,134 @@
+---
+/**
+ * Banner — a Level-2 recipe: a full-bleed feature band with a fixed/parallax
+ * background image, a legibility scrim, and a floating "shaded" content card
+ * over it. Composes Heading + Button.
+ *
+ * Parallax is pure CSS (`background-attachment: fixed`) — no JS, GPU-composited.
+ * It's auto-disabled on touch/coarse pointers (where `fixed` is janky or ignored,
+ * e.g. iOS) and under `prefers-reduced-motion`, both falling back to a clean
+ * `scroll` background. The card uses the surface tokens (radius, shadow) so it
+ * matches every other surface, and a backdrop blur for the "shaded glass" look.
+ */
+import Heading from '../blocks/Heading.astro';
+import Button from '../Button.astro';
+
+interface Props {
+  image: string;
+  eyebrow?: string;
+  title: string;
+  text?: string;
+  cta?: { label: string; href: string };
+  overlay?: number;
+  align?: 'start' | 'center' | 'end';
+  parallax?: boolean;
+}
+const { image, eyebrow, title, text, cta, overlay = 50, align = 'start', parallax = true } = Astro.props;
+const scrim = overlay / 100;
+---
+
+<section
+  class="b-banner"
+  data-align={align}
+  data-parallax={parallax ? 'true' : 'false'}
+  style={`--banner-image: url('${image}'); --banner-scrim: ${scrim};`}
+>
+  <div class="b-banner__scrim" aria-hidden="true"></div>
+  <div class="b-banner__card">
+    {eyebrow && <p class="b-banner__eyebrow">{eyebrow}</p>}
+    <Heading text={title} level={2} align="start" />
+    {text && <p class="b-banner__text">{text}</p>}
+    {cta && (
+      <div class="b-banner__cta">
+        <Button href={cta.href} variant="cta">{cta.label}</Button>
+      </div>
+    )}
+  </div>
+</section>
+
+<style>
+  .b-banner {
+    position: relative;
+    isolation: isolate;
+    display: grid;
+    padding: clamp(3rem, 9vw, 7rem) clamp(1.25rem, 5vw, 4rem);
+    min-height: min(60vh, 34rem);
+    border-radius: var(--radius);
+    overflow: hidden;
+    background-image: var(--banner-image);
+    background-size: cover;
+    background-position: center;
+    background-repeat: no-repeat;
+  }
+  /* Parallax: pin the image to the viewport so it slides under the content.
+     Only on fine pointers with motion allowed — `fixed` is ignored/janky on
+     touch (iOS) and unwelcome under reduced-motion. */
+  @media (hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference) {
+    .b-banner[data-parallax='true'] {
+      background-attachment: fixed;
+    }
+  }
+
+  .b-banner[data-align='start'] { justify-items: start; }
+  .b-banner[data-align='center'] { justify-items: center; text-align: center; }
+  .b-banner[data-align='end'] { justify-items: end; }
+
+  .b-banner__scrim {
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    background: linear-gradient(to top, rgba(8, 10, 18, calc(var(--banner-scrim) + 0.2)), rgba(8, 10, 18, var(--banner-scrim)));
+  }
+
+  /* The floating "shaded glass" card. */
+  .b-banner__card {
+    max-width: 34rem;
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+    padding: clamp(1.5rem, 3vw, 2.25rem);
+    border-radius: var(--radius);
+    background: color-mix(in srgb, var(--bg-surface) 82%, transparent);
+    border: var(--card-border);
+    box-shadow: var(--shadow-lg);
+    -webkit-backdrop-filter: blur(10px);
+    backdrop-filter: blur(10px);
+    color: var(--fg);
+  }
+  .b-banner__eyebrow {
+    margin: 0;
+    text-transform: uppercase;
+    letter-spacing: 0.12em;
+    font-size: 0.8125rem;
+    font-weight: 700;
+    color: var(--gold);
+  }
+  .b-banner__text {
+    margin: 0;
+    color: var(--muted);
+    line-height: 1.65;
+  }
+  .b-banner__cta {
+    margin-top: 0.25rem;
+  }
+
+  /* Multi-layer parallax: the background is pinned (fixed), and the card itself
+     drifts at a different rate as the banner scrolls through view — two layers,
+     two speeds. Native scroll-timeline, so no JS; off under reduced-motion or
+     where unsupported (the card just sits still). Transforming the card is safe:
+     it's not an ancestor of the fixed background. */
+  @media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: view()) {
+      .b-banner__card {
+        animation: b-banner-drift linear both;
+        animation-timeline: view();
+        animation-range: cover;
+        will-change: transform;
+      }
+      @keyframes b-banner-drift {
+        from { transform: translateY(48px); }
+        to { transform: translateY(-48px); }
+      }
+    }
+  }
+</style>

package/components/recipes/Bento.astro

@@ -0,0 +1,138 @@
+---
+/** Bento — a Level-2 recipe: an asymmetric grid where each card picks a `size`
+ *  (sm / wide / tall / lg) and a `variant` look (surface / filled / gradient /
+ *  image). Dense auto-flow packs them like a Japanese bento box. Composes Icon;
+ *  radius/stroke/shadow come from the global surface tokens. */
+import Heading from '../blocks/Heading.astro';
+import Icon from '../Icon.astro';
+import { isIconKey } from '../../lib/icons';
+
+interface Item {
+  size?: 'sm' | 'wide' | 'tall' | 'lg';
+  variant?: 'surface' | 'filled' | 'gradient' | 'image';
+  icon?: string;
+  eyebrow?: string;
+  title: string;
+  text?: string;
+  href?: string;
+  image?: { src: string; alt?: string };
+}
+interface Props {
+  title?: string;
+  intro?: string;
+  items?: Item[];
+}
+const { title, intro, items = [] } = Astro.props;
+---
+
+<section class="b-bento">
+  {(title || intro) && (
+    <div class="b-bento__head">
+      {title && <Heading text={title} level={2} align="center" />}
+      {intro && <p class="b-bento__intro">{intro}</p>}
+    </div>
+  )}
+  <div class="b-bento__grid">
+    {items.map((item) => {
+      const Tag = item.href ? 'a' : 'div';
+      const style = item.variant === 'image' && item.image ? `--bento-image: url('${item.image.src}')` : undefined;
+      return (
+        <Tag class="b-bento__item" data-size={item.size ?? 'sm'} data-variant={item.variant ?? 'surface'} href={item.href} style={style}>
+          {item.icon && isIconKey(item.icon) && (
+            <span class="b-bento__icon"><Icon name={item.icon} size={24} /></span>
+          )}
+          {item.eyebrow && <span class="b-bento__eyebrow">{item.eyebrow}</span>}
+          <h3 class="b-bento__title">{item.title}</h3>
+          {item.text && <p class="b-bento__text">{item.text}</p>}
+        </Tag>
+      );
+    })}
+  </div>
+</section>
+
+<style>
+  .b-bento {
+    display: flex;
+    flex-direction: column;
+    gap: 2rem;
+    max-width: 72rem;
+    margin-inline: auto;
+    padding-inline: 1rem;
+  }
+  .b-bento__head {
+    max-width: var(--max);
+    margin-inline: auto;
+    text-align: center;
+    display: flex;
+    flex-direction: column;
+    gap: 0.75rem;
+  }
+  .b-bento__intro { margin: 0; color: var(--muted); line-height: 1.6; }
+  .b-bento__grid {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 1rem;
+  }
+  @media (min-width: 48em) {
+    .b-bento__grid {
+      grid-template-columns: repeat(2, 1fr);
+      grid-auto-rows: minmax(11rem, auto);
+      grid-auto-flow: dense;
+    }
+    .b-bento__item[data-size='wide'] { grid-column: span 2; }
+    .b-bento__item[data-size='tall'] { grid-row: span 2; }
+    .b-bento__item[data-size='lg'] { grid-column: span 2; grid-row: span 2; }
+  }
+  @media (min-width: 64em) {
+    .b-bento__grid { grid-template-columns: repeat(4, 1fr); }
+  }
+
+  .b-bento__item {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    gap: 0.4rem;
+    padding: 1.5rem;
+    border-radius: var(--radius);
+    overflow: hidden;
+    isolation: isolate;
+    text-decoration: none;
+    color: var(--fg);
+    transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease;
+  }
+  .b-bento__item[data-variant='surface'] { background: var(--bg-surface); border: var(--card-border); box-shadow: var(--shadow-md); }
+  .b-bento__item[data-variant='filled'] { background: var(--gold-light); }
+  .b-bento__item[data-variant='gradient'] { background: linear-gradient(135deg, var(--gold), var(--accent-2, var(--gold))); color: var(--text-light); }
+  .b-bento__item[data-variant='image'] { color: #fff; justify-content: flex-end; min-height: 11rem; }
+  .b-bento__item[data-variant='image']::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    background-image: linear-gradient(to top, rgba(8,10,18,0.82), rgba(8,10,18,0.15)), var(--bento-image);
+    background-size: cover;
+    background-position: center;
+  }
+  a.b-bento__item:hover { transform: translateY(-3px); }
+  a.b-bento__item[data-variant='surface']:hover { box-shadow: var(--shadow-lg); }
+  a.b-bento__item:focus-visible { outline: 2px solid var(--gold); outline-offset: 2px; }
+  @media (prefers-reduced-motion: reduce) { .b-bento__item { transition: none; } a.b-bento__item:hover { transform: none; } }
+
+  .b-bento__icon { display: inline-flex; color: var(--gold); }
+  .b-bento__item[data-variant='gradient'] .b-bento__icon,
+  .b-bento__item[data-variant='image'] .b-bento__icon { color: currentColor; }
+  .b-bento__eyebrow {
+    font-size: 0.72rem;
+    font-weight: 700;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--gold);
+  }
+  .b-bento__item[data-variant='gradient'] .b-bento__eyebrow,
+  .b-bento__item[data-variant='image'] .b-bento__eyebrow { color: currentColor; opacity: 0.85; }
+  .b-bento__title { margin: 0; font-size: 1.15rem; color: inherit; }
+  .b-bento__text { margin: 0; line-height: 1.55; color: var(--muted); }
+  .b-bento__item[data-variant='gradient'] .b-bento__text,
+  .b-bento__item[data-variant='image'] .b-bento__text,
+  .b-bento__item[data-variant='filled'] .b-bento__text { color: inherit; opacity: 0.92; }
+</style>