ferst-core 0.1.0 → 0.2.0

package/components/blocks/Badge.astro

@@ -0,0 +1,29 @@
+---
+interface Props {
+  text: string;
+  tone?: 'neutral' | 'accent';
+}
+const { text, tone = 'accent' } = Astro.props;
+---
+
+<span class="b-badge" data-tone={tone}>{text}</span>
+
+<style>
+  .b-badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    font-weight: 600;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    padding: 0.2rem 0.6rem;
+    border-radius: 999px;
+  }
+  .b-badge[data-tone='accent'] {
+    color: var(--gold);
+    background: var(--gold-light);
+  }
+  .b-badge[data-tone='neutral'] {
+    color: var(--muted);
+    background: var(--bg-section);
+  }
+</style>

package/components/blocks/ButtonBlock.astro

@@ -0,0 +1,13 @@
+---
+/** Block wrapper over the shared Button primitive (single source). */
+import Button from '../Button.astro';
+
+interface Props {
+  label: string;
+  href: string;
+  variant?: 'primary' | 'secondary';
+}
+const { label, href, variant = 'primary' } = Astro.props;
+---
+
+<Button href={href} variant={variant}>{label}</Button>

package/components/blocks/Divider.astro

@@ -0,0 +1,12 @@
+---
+---
+
+<hr class="b-divider" />
+
+<style>
+  .b-divider {
+    border: 0;
+    border-top: 1px solid var(--border);
+    margin: 0;
+  }
+</style>

package/components/blocks/Grid.astro

@@ -0,0 +1,48 @@
+---
+/** A layout container: places child blocks in a responsive N-column grid
+ *  (one column on mobile, N from tablet up). */
+import BlockRenderer from '../BlockRenderer.astro';
+
+interface Props {
+  columns?: 2 | 3 | 4;
+  gap?: 'sm' | 'md' | 'lg';
+  blocks?: any[];
+}
+const { columns = 2, gap = 'md', blocks = [] } = Astro.props;
+---
+
+<div class="b-grid" data-cols={columns} data-gap={gap}>
+  <BlockRenderer blocks={blocks} />
+</div>
+
+<style>
+  .b-grid {
+    display: grid;
+    grid-template-columns: 1fr; /* mobile-first: single column */
+  }
+  .b-grid[data-gap='sm'] {
+    gap: 0.75rem;
+  }
+  .b-grid[data-gap='md'] {
+    gap: 1.5rem;
+  }
+  .b-grid[data-gap='lg'] {
+    gap: 3rem;
+  }
+  @media (min-width: 48em) {
+    .b-grid[data-cols='2'] {
+      grid-template-columns: repeat(2, 1fr);
+    }
+    .b-grid[data-cols='3'] {
+      grid-template-columns: repeat(3, 1fr);
+    }
+    .b-grid[data-cols='4'] {
+      grid-template-columns: repeat(2, 1fr);
+    }
+  }
+  @media (min-width: 64em) {
+    .b-grid[data-cols='4'] {
+      grid-template-columns: repeat(4, 1fr);
+    }
+  }
+</style>

package/components/blocks/Heading.astro

@@ -0,0 +1,42 @@
+---
+interface Props {
+  text: string;
+  level?: number;
+  align?: 'start' | 'center' | 'end';
+  gradient?: boolean;
+}
+const { text, level = 2, align = 'start', gradient = false } = Astro.props;
+const Tag = `h${level}` as unknown as keyof HTMLElementTagNameMap;
+---
+
+<Tag class="b-heading" data-align={align} data-gradient={gradient ? 'true' : 'false'}>{text}</Tag>
+
+<style>
+  /* A heading owns its own alignment via the `align` prop — it never depends on
+     an ancestor rule. (Base no longer force-centres headings, so a recipe that
+     asks for `start` really is left-aligned, and `center` really is centred,
+     wherever the block is placed — including AI-authored block JSON.) */
+  .b-heading {
+    color: var(--fg);
+    margin: 0;
+    text-wrap: balance;
+    line-height: 1.2;
+    text-align: start;
+  }
+  .b-heading[data-align='center'] {
+    text-align: center;
+  }
+  .b-heading[data-align='end'] {
+    text-align: end;
+  }
+  /* Gradient text — only clip to text where supported, so it never renders as
+     invisible/transparent on older browsers (it stays solid ink there). */
+  @supports ((-webkit-background-clip: text) or (background-clip: text)) {
+    .b-heading[data-gradient='true'] {
+      background-image: linear-gradient(120deg, var(--gold), var(--accent-2, var(--gold)));
+      -webkit-background-clip: text;
+      background-clip: text;
+      color: transparent;
+    }
+  }
+</style>

package/components/blocks/ImageBlock.astro

@@ -0,0 +1,80 @@
+---
+/**
+ * A basic image block with a small set of CANONICAL framing options — corners
+ * (none / soft / round), a drop shadow, an outline stroke, an aspect ratio, and
+ * an optional soft scroll-in reveal. These are clear, named choices the AI or a
+ * client picks from (not free-form CSS); corners/shadow/stroke read the global
+ * surface tokens, so images stay consistent with every other surface.
+ * The build-time optimisation pipeline (docs/IMAGE-PIPELINE.md) is a later
+ * upgrade — the schema stays the same.
+ */
+interface Props {
+  src: string;
+  alt?: string;
+  caption?: string;
+  radius?: 'none' | 'soft' | 'round';
+  shadow?: boolean;
+  border?: boolean;
+  ratio?: 'auto' | 'square' | '4/3' | '3/2' | '16/9' | '21/9';
+  reveal?: boolean;
+}
+const { src, alt = '', caption, radius = 'soft', shadow = false, border = false, ratio = 'auto', reveal = false } = Astro.props;
+const ratioValue = ratio === 'auto' ? null : ratio === 'square' ? '1 / 1' : ratio.replace('/', ' / ');
+---
+
+<figure
+  class="b-image"
+  data-radius={radius}
+  data-shadow={shadow ? 'true' : 'false'}
+  data-border={border ? 'true' : 'false'}
+  data-reveal={reveal ? 'true' : 'false'}
+>
+  <img
+    src={src}
+    alt={alt}
+    loading="lazy"
+    decoding="async"
+    style={ratioValue ? `aspect-ratio: ${ratioValue}` : undefined}
+  />
+  {caption && <figcaption>{caption}</figcaption>}
+</figure>
+
+<style>
+  .b-image { margin: 0; }
+  .b-image img {
+    display: block;
+    width: 100%;
+    height: auto;
+    object-fit: cover; /* only bites when an aspect-ratio is set */
+  }
+  /* Corners */
+  .b-image[data-radius='none'] img { border-radius: 0; }
+  .b-image[data-radius='soft'] img { border-radius: var(--radius); }
+  .b-image[data-radius='round'] img { border-radius: var(--radius-pill); }
+  /* Drop shadow + outline stroke, from the global surface tokens */
+  .b-image[data-shadow='true'] img { box-shadow: var(--shadow-md); }
+  .b-image[data-border='true'] img { border: var(--card-border); }
+
+  .b-image figcaption {
+    color: var(--muted);
+    font-size: 0.875rem;
+    margin-top: 0.5rem;
+    text-align: center;
+  }
+
+  /* Soft scroll-in reveal — native scroll-driven, so no JS/observer. Fully
+     visible where unsupported or under reduced-motion. */
+  @keyframes b-image-reveal {
+    from { clip-path: inset(42% 0 42% 0); opacity: 0.35; }
+    to { clip-path: inset(0 0 0 0); opacity: 1; }
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: view()) {
+      .b-image[data-reveal='true'] img {
+        animation: b-image-reveal linear both;
+        animation-timeline: view();
+        animation-range: entry 5% cover 35%;
+      }
+    }
+  }
+</style>

package/components/blocks/List.astro

@@ -0,0 +1,78 @@
+---
+/** List — a leaf primitive: a bulleted, numbered, or checked list of lines.
+ *  `check` uses the shared check icon in the brand accent. Token-driven. */
+import Icon from '../Icon.astro';
+
+interface Props {
+  style?: 'bullet' | 'number' | 'check';
+  items?: string[];
+}
+const { style = 'bullet', items = [] } = Astro.props;
+const Tag = style === 'number' ? 'ol' : 'ul';
+---
+
+<Tag class:list={['b-list', `b-list--${style}`]}>
+  {items.map((item) => (
+    <li class="b-list__item">
+      {style === 'check' && <span class="b-list__mark" aria-hidden="true"><Icon name="check" size={18} /></span>}
+      <span>{item}</span>
+    </li>
+  ))}
+</Tag>
+
+<style>
+  .b-list {
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 0.6rem;
+    color: var(--muted);
+    line-height: 1.6;
+  }
+  .b-list__item {
+    display: flex;
+    gap: 0.6rem;
+    align-items: flex-start;
+  }
+  /* bullet + number keep native markers, but as flex items we render our own */
+  .b-list--bullet {
+    list-style: none;
+  }
+  .b-list--bullet .b-list__item::before {
+    content: '';
+    flex-shrink: 0;
+    width: 0.45rem;
+    height: 0.45rem;
+    margin-top: 0.6rem;
+    border-radius: 999px;
+    background: var(--gold);
+  }
+  .b-list--number {
+    list-style: none;
+    counter-reset: b-list;
+  }
+  .b-list--number .b-list__item {
+    counter-increment: b-list;
+  }
+  .b-list--number .b-list__item::before {
+    content: counter(b-list);
+    flex-shrink: 0;
+    min-width: 1.5rem;
+    height: 1.5rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 999px;
+    background: var(--gold-light);
+    color: var(--gold);
+    font-size: 0.8125rem;
+    font-weight: 700;
+  }
+  .b-list__mark {
+    flex-shrink: 0;
+    display: inline-flex;
+    color: var(--gold);
+    margin-top: 0.15rem;
+  }
+</style>

package/components/blocks/Prose.astro

@@ -0,0 +1,29 @@
+---
+interface Props {
+  text: string;
+}
+const { text } = Astro.props;
+// Blank lines separate paragraphs. (Markdown rendering upgrades this later.)
+const paragraphs = text
+  .split(/\n\s*\n/)
+  .map((p) => p.trim())
+  .filter(Boolean);
+---
+
+<div class="b-prose">
+  {paragraphs.map((p) => <p>{p}</p>)}
+</div>
+
+<style>
+  .b-prose {
+    color: var(--fg);
+  }
+  .b-prose p {
+    margin: 0 0 1rem;
+    line-height: 1.7;
+    max-width: var(--max);
+  }
+  .b-prose p:last-child {
+    margin-bottom: 0;
+  }
+</style>

package/components/blocks/Quote.astro

@@ -0,0 +1,32 @@
+---
+interface Props {
+  text: string;
+  cite?: string;
+}
+const { text, cite } = Astro.props;
+---
+
+<figure class="b-quote">
+  <blockquote>{text}</blockquote>
+  {cite && <figcaption>— {cite}</figcaption>}
+</figure>
+
+<style>
+  .b-quote {
+    margin: 0;
+    border-inline-start: 3px solid var(--gold);
+    padding-inline-start: 1rem;
+  }
+  .b-quote blockquote {
+    margin: 0;
+    color: var(--fg);
+    font-style: italic;
+    font-size: 1.125rem;
+    line-height: 1.6;
+  }
+  .b-quote figcaption {
+    color: var(--muted);
+    margin-top: 0.5rem;
+    font-size: 0.9375rem;
+  }
+</style>

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>