@moonarc/core 0.1.0

package/src/components/StickyBanner.astro

@@ -0,0 +1,168 @@
+---
+/**
+ * StickyBanner — an announcement ribbon that sticks to the top and folds
+ * away when dismissed, zero JS.
+ *
+ * The ribbon is a non-modal <dialog open>, so the close button is a form
+ * with method="dialog" — every browser closes it, no script. The wrapper
+ * is a grid whose only row goes 1fr → 0fr when :has() sees the dialog
+ * closed, and the ribbon slides up as it leaves through allow-discrete, so
+ * the page below moves up on the preset curve rather than jumping.
+ * Without `remember` it comes back on the next page; `remember` inlines
+ * ~290 B that read localStorage before paint (no flash) and write it on
+ * close, marked data-astro-rerun so ClientRouter runs it on every page.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Dialog id and, with remember, the storage key. */
+  id: string;
+  /** Show the close button. */
+  dismissible?: boolean;
+  /** Remember a dismissal in localStorage (ma-banner:<id>) and never render it again — an inline script, measured on the readout. */
+  remember?: boolean;
+  /** Optional call to action. */
+  href?: string;
+  cta?: string;
+  /** Ribbon colours; default ink on panel text. */
+  color?: string;
+  textColor?: string;
+  /** Accessible name. */
+  label?: string;
+  /** Accessible name of the close button. */
+  dismissLabel?: string;
+}
+
+const { id, dismissible = true, remember = false, href, cta = 'Learn more', color, textColor, label = 'Announcement', dismissLabel = 'Dismiss', class: className, style, ...rest } = Astro.props;
+const vars = [color && `--ma-banner-bg:${color}`, textColor && `--ma-banner-fg:${textColor}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+/** Runs where it is rendered, before the next paint: a remembered dismissal closes the dialog and skips the fold; every close is stored. */
+const REMEMBER = `(function(){var s=document.currentScript,w=s.previousElementSibling,d=w.querySelector('dialog'),K='ma-banner:'+d.id;try{if(localStorage.getItem(K)){w.setAttribute('data-gone','');d.close()}}catch(e){}d.addEventListener('close',function(){try{localStorage.setItem(K,'1')}catch(e){}})})()`;
+---
+
+<div class:list={['ma-banner', className]} style={vars || undefined} {...rest}>
+  <dialog open id={id} class="ma-banner__dialog" aria-label={label}>
+    <div class="ma-banner__inner">
+      <p class="ma-banner__text"><slot /></p>
+      {href && <a class="ma-banner__cta" href={href}>{cta} <span aria-hidden="true">→</span></a>}
+      {dismissible && (
+        <form method="dialog" class="ma-banner__close">
+          <button type="submit" aria-label={dismissLabel}>
+            <svg aria-hidden="true" viewBox="0 0 16 16" width="14" height="14"><path d="M4 4l8 8M12 4l-8 8" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg>
+          </button>
+        </form>
+      )}
+    </div>
+  </dialog>
+</div>
+{/* data-astro-rerun: ClientRouter skips an inline script whose text the page it leaves already ran, and this one is the
+    same on every page, so without it the next page rendered the ribbon open again */}
+{remember && <script is:inline data-astro-rerun set:html={REMEMBER} />}
+
+<style is:global>
+  @layer components {
+    /* the wrapper is the sticky element and the fold: one grid row from 1fr to 0fr */
+    :where(.ma-banner) {
+      position: sticky;
+      top: 0;
+      z-index: 30;
+      display: grid;
+      grid-template-rows: 1fr;
+      transition: grid-template-rows var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-banner:has(.ma-banner__dialog:not([open]))) {
+      grid-template-rows: 0fr;
+    }
+    :where(.ma-banner[data-gone]) {
+      transition: none;
+    }
+    :where(.ma-banner__dialog) {
+      position: static;
+      width: 100%;
+      max-width: none;
+      min-height: 0;
+      margin: 0;
+      padding: 0;
+      border: 0;
+      background: none;
+      color: inherit;
+      overflow: clip;
+      opacity: 1;
+      translate: 0 0;
+      transition:
+        opacity var(--ma-duration-fast) var(--ma-ease-out),
+        translate var(--ma-duration) var(--ma-ease-in),
+        display var(--ma-duration) allow-discrete;
+    }
+    :where(.ma-banner__dialog:not([open])) {
+      opacity: 0;
+      translate: 0 -100%;
+    }
+    :where(.ma-banner__inner) {
+      position: relative;
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      justify-content: center;
+      gap: 0.25rem 1rem;
+      padding: 0.625rem 3rem;
+      background: var(--ma-banner-bg, var(--ma-ink));
+      color: var(--ma-banner-fg, var(--ma-panel));
+      font-size: 0.875rem;
+      line-height: 1.4;
+      text-align: center;
+    }
+    :where(.ma-banner__text) {
+      margin: 0;
+    }
+    :where(.ma-banner__cta) {
+      color: inherit;
+      font-weight: 600;
+      text-decoration: underline;
+      text-decoration-color: color-mix(in srgb, currentColor 40%, transparent);
+      text-underline-offset: 0.2em;
+      white-space: nowrap;
+      transition: text-decoration-color var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-banner__cta:hover) {
+      text-decoration-color: currentColor;
+    }
+    :where(.ma-banner__close) {
+      position: absolute;
+      top: 50%;
+      right: 0.75rem;
+      translate: 0 -50%;
+    }
+    :where(.ma-banner__close button) {
+      display: grid;
+      place-items: center;
+      width: 1.75rem;
+      height: 1.75rem;
+      border: 0;
+      border-radius: 999px;
+      background: none;
+      color: inherit;
+      cursor: pointer;
+      opacity: 0.7;
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out), background-color var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-banner__close button:hover) {
+      opacity: 1;
+      background: color-mix(in srgb, currentColor 14%, transparent);
+    }
+    :where(.ma-banner__close button:focus-visible),
+    :where(.ma-banner__cta:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-banner),
+      :where(.ma-banner__dialog) {
+        transition-duration: var(--ma-duration-fast);
+        transition-timing-function: linear;
+      }
+      :where(.ma-banner__dialog:not([open])) {
+        translate: 0 0;
+      }
+    }
+  }
+</style>

package/src/components/StickyBanner.meta.ts

@@ -0,0 +1,45 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'StickyBanner',
+  slug: 'sticky-banner',
+  title: 'Sticky Banner',
+  description: 'An announcement ribbon that sticks to the top of the page and folds away when dismissed, the content below sliding up on the preset curve. Zero JavaScript: a non-modal dialog closed by a form with method="dialog", a grid row that :has() collapses, and an exit through allow-discrete. remember inlines 286 B raw that keep it closed across pages.',
+  summary: 'An announcement banner that sticks to the top and folds away when dismissed, the page sliding up after it.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['load', 'click'],
+  support: { baseline: 'newly', needs: ['dialog', 'has', 'allow-discrete', 'grid-rows-animation'], fallback: 'without allow-discrete the ribbon disappears at once; the row still folds on :has()' },
+  readout: '<StickyBanner id="launch" remember>',
+  usage: `<StickyBanner id="launch" href="/changelog/" cta="See what shipped">\n  <strong>New</strong>: dark mode for every chart.\n</StickyBanner>\n\n<!-- stays dismissed on the next visit -->\n<StickyBanner id="launch" remember>…</StickyBanner>`,
+  props: [
+    { name: 'id', type: 'string', description: 'Dialog id; with remember, the localStorage key is ma-banner:<id>. Change it for a new announcement.' },
+    { name: 'dismissible', type: 'boolean', default: 'true', description: 'Render the close button.' },
+    { name: 'remember', type: 'boolean', default: 'false', description: 'Keep a dismissal in localStorage and never render the ribbon again on this browser: an inline script of 286 B raw (measured from the string that is inlined) that runs where the banner is, before paint, so nothing flashes.' },
+    { name: 'href', type: 'string', description: 'A call-to-action link.' },
+    { name: 'cta', type: 'string', default: "'Learn more'", description: 'Its label.' },
+    { name: 'color', type: 'string', description: 'Ribbon colour; default the ink token.' },
+    { name: 'textColor', type: 'string', description: 'Text colour; default the panel token.' },
+    { name: 'label', type: 'string', default: "'Announcement'", description: 'Accessible name of the dialog.' },
+    { name: 'dismissLabel', type: 'string', default: "'Dismiss'", description: 'Accessible name of the close button, for a page in another language. The arrow after the call to action is decorative and hidden from screen readers.' },
+  ],
+  reducedMotion: 'The row folds in 150 ms without the slide.',
+  clientRouter: 'Native; nothing to rebind. Without remember every page renders the ribbon again; with it the inline script closes it before paint on every page. The script carries data-astro-rerun: ClientRouter skips an inline script whose text it has already run, and this one is the same on every page.',
+  craft: [
+    'A non-modal <dialog open> gives a close button for free (a form with method="dialog") and a state (the open attribute) that CSS can read with :has(). No class, no script.',
+    'The fold is the Accordion trick turned around: the wrapper is a grid whose row goes from 1fr to 0fr, so the page below slides up on the preset curve instead of jumping when the ribbon leaves.',
+    'The ribbon itself slides up and fades on the exit curve while its display transitions with allow-discrete, so it is still there to be animated.',
+    'remember is the only case that needs a script and it is inline on purpose: it has to run before the first paint of the page it is on, like ThemeScript, and it is 286 B raw, measured from the same string that is inlined.',
+    'Sticky at z-index 30 sits under a site header at 40 and over content: the ribbon belongs to the page, not the chrome.',
+  ],
+  related: ['dialog', 'nav-bar', 'toast'],
+  intents: ['announcement banner', 'sticky top banner dismissible', 'promo bar', 'cookie bar without javascript', 'site notice ribbon', 'banner that remembers dismissal'],
+  replaces: ['Banner (Aceternity)', 'AnnouncementBar (Tailwind Plus)', 'Alert dismissible (shadcn / Radix)'],
+  fixture: {
+    props: { id: 'ma-fixture-banner' },
+    slot: 'Fixture content for StickyBanner',
+    expect: 'Fixture content for StickyBanner',
+    // a page in another language: its word reaches the close button's name
+    variants: { dismissLabel: { props: { dismissLabel: 'Schließen' }, expect: 'aria-label="Schließen"' } },
+  },
+} satisfies ComponentMeta;

package/src/components/StickyReveal.astro

@@ -0,0 +1,256 @@
+---
+/**
+ * StickyReveal — steps on the left scroll by, one visual on the right
+ * stays put and changes with them. Zero JS: each step names its own view
+ * timeline, the visuals are stacked in one sticky grid cell, and each
+ * visual's opacity and travel are bound to its step's timeline through
+ * timeline-scope on the container. Where scroll timelines are missing, or
+ * below the layout's width, the steps and visuals interleave in one column
+ * (display: contents + order), so every step still meets its own visual.
+ * Text steps are props; visuals are named slots, visual-1 … visual-8.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Step {
+  title: string;
+  /** Plain text or HTML. */
+  body?: string;
+}
+
+interface Props extends HTMLAttributes<'div'> {
+  steps: Step[];
+  /** Sticky offset from the top of the scrollport. */
+  top?: string;
+  /** Height of each step's slot and of the sticky visual. */
+  height?: string;
+  /** `auto`: two columns from 40rem of container width; `sticky`: always two columns; `stack`: always one. */
+  layout?: 'auto' | 'sticky' | 'stack';
+}
+
+const { steps, top = '10vh', height = '70vh', layout = 'auto', class: className, style, ...rest } = Astro.props;
+const list = steps.slice(0, 8);
+const vars = [`--ma-sticky-top:${top}`, `--ma-sticky-h:${height}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-sticky', className]} data-layout={layout} style={vars} {...rest}>
+  <div class="ma-sticky__steps">
+    {list.map((s, i) => (
+      <div class="ma-sticky__step" style={`--ma-sticky-i:${i + 1}`}>
+        <h3 class="ma-sticky__title">{s.title}</h3>
+        {s.body && <p class="ma-sticky__body" set:html={s.body} />}
+      </div>
+    ))}
+  </div>
+  <div class="ma-sticky__visuals">
+    {list.map((_, i) => (
+      <div class="ma-sticky__visual" style={`--ma-sticky-i:${i + 1}`}>
+        <slot name={`visual-${i + 1}`} />
+      </div>
+    ))}
+  </div>
+</div>
+
+<style is:global>
+  @layer components {
+    /* The two tracks are declared on the root in every layout. An element never answers its own container query, so a
+       layout="auto" root that switched its own columns at 40rem queried whatever container sat above it (none, as a
+       rule) and never went to two columns; the rules below only switch its children, which do see it. */
+    :where(.ma-sticky) {
+      container-type: inline-size;
+      display: grid;
+      grid-template-columns: minmax(0, 2fr) minmax(0, 3fr);
+      gap: 1.5rem;
+      timeline-scope: --ma-sticky-1, --ma-sticky-2, --ma-sticky-3, --ma-sticky-4, --ma-sticky-5, --ma-sticky-6, --ma-sticky-7, --ma-sticky-8;
+    }
+    /* stack: steps and visuals interleave through order across both tracks; the columns are display: contents */
+    :where(.ma-sticky__steps),
+    :where(.ma-sticky__visuals) {
+      display: contents;
+    }
+    :where(.ma-sticky__step) {
+      grid-column: 1 / -1;
+      order: calc(var(--ma-sticky-i, 1) * 2 - 1);
+    }
+    :where(.ma-sticky__visual) {
+      grid-column: 1 / -1;
+      order: calc(var(--ma-sticky-i, 1) * 2);
+      min-height: 12rem;
+    }
+    :where(.ma-sticky__title) {
+      margin: 0;
+      font-size: 1.375em;
+      font-weight: 600;
+      letter-spacing: -0.02em;
+      line-height: 1.2;
+    }
+    :where(.ma-sticky__body) {
+      margin: 0.5em 0 0;
+      opacity: 0.7;
+    }
+    :where(.ma-sticky__visual > :first-child) {
+      width: 100%;
+      height: 100%;
+    }
+
+    /* sticky: two columns, visuals stacked in one sticky cell, each bound to its step's passage */
+    @supports (animation-timeline: view()) and (timeline-scope: --a) {
+      @container (min-width: 40rem) {
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__steps),
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visuals) {
+          display: grid;
+          align-self: start;
+        }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__step) {
+          order: 0;
+          min-height: var(--ma-sticky-h, 70vh);
+          display: grid;
+          align-content: center;
+          animation: ma-sticky-step linear both;
+          animation-range: cover 0% cover 100%;
+        }
+        :where(html) :where(.ma-sticky[data-layout='auto'] .ma-sticky__step) {
+          animation-timeline: view();
+        }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__step:nth-child(1)) { view-timeline-name: --ma-sticky-1; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__step:nth-child(2)) { view-timeline-name: --ma-sticky-2; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__step:nth-child(3)) { view-timeline-name: --ma-sticky-3; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__step:nth-child(4)) { view-timeline-name: --ma-sticky-4; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__step:nth-child(5)) { view-timeline-name: --ma-sticky-5; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__step:nth-child(6)) { view-timeline-name: --ma-sticky-6; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__step:nth-child(7)) { view-timeline-name: --ma-sticky-7; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__step:nth-child(8)) { view-timeline-name: --ma-sticky-8; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visuals) {
+          position: sticky;
+          top: var(--ma-sticky-top, 10vh);
+          height: var(--ma-sticky-h, 70vh);
+        }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual) {
+          order: 0;
+          grid-area: 1 / 1;
+          min-height: 0;
+          animation: ma-sticky-visual linear both;
+          animation-range: cover 0% cover 100%;
+        }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:first-child) { animation-name: ma-sticky-visual-first; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:last-child) { animation-name: ma-sticky-visual-last; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:only-child) { animation-name: none; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:nth-child(1)) { animation-timeline: --ma-sticky-1; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:nth-child(2)) { animation-timeline: --ma-sticky-2; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:nth-child(3)) { animation-timeline: --ma-sticky-3; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:nth-child(4)) { animation-timeline: --ma-sticky-4; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:nth-child(5)) { animation-timeline: --ma-sticky-5; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:nth-child(6)) { animation-timeline: --ma-sticky-6; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:nth-child(7)) { animation-timeline: --ma-sticky-7; }
+        :where(.ma-sticky[data-layout='auto'] .ma-sticky__visual:nth-child(8)) { animation-timeline: --ma-sticky-8; }
+      }
+      /* forced: the same rules without the width condition */
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__steps),
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visuals) {
+        display: grid;
+        align-self: start;
+      }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step) {
+        order: 0;
+        min-height: var(--ma-sticky-h, 70vh);
+        display: grid;
+        align-content: center;
+        animation: ma-sticky-step linear both;
+        animation-range: cover 0% cover 100%;
+      }
+      :where(html) :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step) {
+        animation-timeline: view();
+      }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step:nth-child(1)) { view-timeline-name: --ma-sticky-1; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step:nth-child(2)) { view-timeline-name: --ma-sticky-2; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step:nth-child(3)) { view-timeline-name: --ma-sticky-3; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step:nth-child(4)) { view-timeline-name: --ma-sticky-4; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step:nth-child(5)) { view-timeline-name: --ma-sticky-5; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step:nth-child(6)) { view-timeline-name: --ma-sticky-6; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step:nth-child(7)) { view-timeline-name: --ma-sticky-7; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__step:nth-child(8)) { view-timeline-name: --ma-sticky-8; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visuals) {
+        position: sticky;
+        top: var(--ma-sticky-top, 10vh);
+        height: var(--ma-sticky-h, 70vh);
+      }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual) {
+        order: 0;
+        grid-area: 1 / 1;
+        min-height: 0;
+        animation: ma-sticky-visual linear both;
+        animation-range: cover 0% cover 100%;
+      }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:first-child) { animation-name: ma-sticky-visual-first; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:last-child) { animation-name: ma-sticky-visual-last; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:only-child) { animation-name: none; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:nth-child(1)) { animation-timeline: --ma-sticky-1; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:nth-child(2)) { animation-timeline: --ma-sticky-2; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:nth-child(3)) { animation-timeline: --ma-sticky-3; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:nth-child(4)) { animation-timeline: --ma-sticky-4; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:nth-child(5)) { animation-timeline: --ma-sticky-5; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:nth-child(6)) { animation-timeline: --ma-sticky-6; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:nth-child(7)) { animation-timeline: --ma-sticky-7; }
+      :where(.ma-sticky[data-layout='sticky'] .ma-sticky__visual:nth-child(8)) { animation-timeline: --ma-sticky-8; }
+    }
+    /* Reduced motion: the visuals still hand over with their steps, in place (no travel), and the step text stays at
+       full strength. A stepped cut used to share its keyframes with the steps, so every step but the current one was
+       invisible, and it left scroll positions where no visual showed at all. */
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-sticky) {
+        --ma-travel-section: 0px;
+      }
+      :where(.ma-sticky__step) {
+        animation: none;
+      }
+    }
+  }
+
+  /* the visual of the step in the middle of the scrollport is the one that shows */
+  @keyframes ma-sticky-visual {
+    0% {
+      opacity: 0;
+      translate: 0 var(--ma-travel-section);
+    }
+    30%,
+    70% {
+      opacity: 1;
+      translate: 0 0;
+    }
+    100% {
+      opacity: 0;
+      translate: 0 calc(-1 * var(--ma-travel-section));
+    }
+  }
+  @keyframes ma-sticky-visual-first {
+    0%,
+    70% {
+      opacity: 1;
+      translate: 0 0;
+    }
+    100% {
+      opacity: 0;
+      translate: 0 calc(-1 * var(--ma-travel-section));
+    }
+  }
+  @keyframes ma-sticky-visual-last {
+    0% {
+      opacity: 0;
+      translate: 0 var(--ma-travel-section);
+    }
+    30%,
+    100% {
+      opacity: 1;
+      translate: 0 0;
+    }
+  }
+  @keyframes ma-sticky-step {
+    0%,
+    100% {
+      opacity: 0.35;
+    }
+    35%,
+    65% {
+      opacity: 1;
+    }
+  }
+</style>

package/src/components/StickyReveal.meta.ts

@@ -0,0 +1,33 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'StickyReveal',
+  slug: 'sticky-reveal',
+  title: 'Sticky Reveal',
+  description: 'Steps on the left scroll by; one visual on the right stays put and changes with them. Each step names its own view timeline, the visuals are stacked in a sticky cell, and each visual\'s opacity and travel are bound to its step through timeline-scope. Without scroll timelines, or in a narrow container, the steps and visuals interleave in one column so every step still meets its own visual. Zero JavaScript.',
+  summary: 'Scroll steps beside one sticky visual that changes with each step, falling back to one column when narrow.',
+  category: 'scroll',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'limited', needs: ['scroll-timeline', 'timeline-scope'], fallback: 'one column: each step followed by its own visual (Firefox, and every browser below 40 rem of container width)' },
+  readout: '<StickyReveal steps={[…]} top="10vh">',
+  usage: `<StickyReveal steps={[{ title: 'Write', body: 'One component, one file.' }, { title: 'Measure', body: 'Every byte from a real build.' }, { title: 'Ship', body: 'Nothing to hydrate.' }]}>\n  <img slot="visual-1" src="/write.png" alt="" />\n  <img slot="visual-2" src="/measure.png" alt="" />\n  <img slot="visual-3" src="/ship.png" alt="" />\n</StickyReveal>`,
+  props: [
+    { name: 'steps', type: '{ title: string; body?: string }[]', description: 'Up to eight steps; body may be HTML.' },
+    { name: 'top', type: 'string', default: "'10vh'", description: 'Sticky offset from the top of the scrollport.' },
+    { name: 'height', type: 'string', default: "'70vh'", description: 'Height of each step\'s slot and of the sticky visual.' },
+    { name: 'layout', type: "'auto' | 'sticky' | 'stack'", default: "'auto'", description: 'auto: two columns from 40 rem of container width; sticky: always; stack: never.' },
+  ],
+  reducedMotion: 'The visuals still hand over with their steps, crossfading in place with no travel, and the step text no longer dims.',
+  clientRouter: 'CSS-only; the timelines are recomputed with the new page.',
+  craft: [
+    'timeline-scope on the container lets a visual read a sibling column\'s timeline: the visual for step 3 is literally animated by step 3\'s passage, so they can never drift apart.',
+    'A visual is fully on from 30 % to 70 % of its step\'s cover range and hands over in the outer 30 %s; the first and last visuals hold at the ends so the section never starts or ends empty.',
+    'The stacked fallback is not "the first visual only": display: contents on both columns and an order per item interleave the DOM into step, visual, step, visual, which is what a phone should show anyway.',
+    'The width switch is a container query, not a media query, so a StickyReveal in a sidebar stacks while one across the page sticks. The component is its own container, and an element never answers its own query, so the two tracks are declared on it in every layout and only its children switch.',
+  ],
+  related: ['card-stack', 'scroll-scrub', 'horizontal-scroll'],
+  intents: ['sticky scroll reveal', 'scroll steps with sticky image', 'features scroll with changing image', 'sticky scroll section', 'scrollytelling astro'],
+  replaces: ['StickyScrollReveal (Aceternity)', 'sticky scroll section (Tailwind Plus)', 'ScrollStack (React Bits)'],
+  fixture: { props: { steps: [{ title: 'Fixture content for StickyReveal' }, { title: 'Two' }] }, expect: 'Fixture content for StickyReveal' },
+} satisfies ComponentMeta;

package/src/components/StrokeDraw.astro

@@ -0,0 +1,110 @@
+---
+/**
+ * StrokeDraw — the outline of a headline draws itself, then the fill comes
+ * in. -webkit-text-stroke cannot be drawn as a stroke, so the text is an
+ * SVG <text>, one <tspan> per character, each stroked with a dash longer
+ * than any glyph's outline and offset to zero on a per-index delay; the
+ * fill fades in once the stroke has landed. pathLength is not defined for
+ * <text> in any engine, so the dash is em-based. Composes Reveal for the
+ * trigger; zero script of its own. The server HTML holds the final text.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+import Reveal from './Reveal.astro';
+
+interface Props extends HTMLAttributes<'span'> {
+  /** The text — one line. */
+  text: string;
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Stroke width, relative to a 100-unit font size (2 ≈ 2% of the cap height). */
+  width?: number;
+  /** Dash length per glyph in em; the outline of any glyph must fit inside it. */
+  dash?: number;
+  /** Stroke colour. */
+  color?: string;
+  /** Fill after the stroke. false leaves the outline. */
+  fill?: boolean;
+  /** Draw duration per glyph in ms. Unset: the preset's --ma-duration-slow. */
+  duration?: number;
+  /** Delay between neighbouring glyphs in ms. Unset: the preset's --ma-stagger. */
+  step?: number;
+  /** Delay in ms before the first glyph. */
+  delay?: number;
+  /** Play once and stay. */
+  once?: boolean;
+  /** Fraction visible to trigger. */
+  threshold?: number;
+}
+
+const { text, as = 'span', width = 2, dash = 5, color = 'currentColor', fill = true, duration, step, delay, once, threshold, class: className, style, ...rest } = Astro.props;
+
+// Advance widths in em, rough Inter metrics: enough to size the viewBox; textLength then justifies the spacing.
+const advance = (c: string) => (c === ' ' ? 0.28 : /[ilj.,'!|:;]/.test(c) ? 0.3 : /[frt1I\[\]()]/.test(c) ? 0.38 : /[mwMW]/.test(c) ? 0.9 : /[A-Z0-9]/.test(c) ? 0.68 : 0.56);
+const FS = 100;
+// one tspan per grapheme, not per code point: a combining accent in a tspan of its own is drawn apart from its letter
+const chars = Array.from(new Intl.Segmenter().segment(text), (g) => g.segment);
+const w = Math.round(chars.reduce((n, c) => n + advance(c), 0) * FS);
+const h = Math.round(FS * 1.25);
+const vars = [`--ma-stroke-w:${width}`, `--ma-stroke-dash:${dash}em`, `--ma-stroke-color:${color}`, !fill && '--ma-stroke-fill:transparent', duration !== undefined && `--ma-stroke-dur:${duration}ms`, step !== undefined && `--ma-stroke-step:${step}ms`, typeof style === 'string' ? style : '']
+  .filter(Boolean)
+  .join(';');
+---
+
+<Reveal as={as} from="none" delay={delay} once={once} threshold={threshold} class={['ma-stroke', className].filter(Boolean).join(' ')} style={vars} {...rest}>
+  <svg class="ma-stroke__svg" viewBox={`0 0 ${w} ${h}`} aria-hidden="true">
+    <text x="0" y={FS} font-size={FS} textLength={w} lengthAdjust="spacing">{chars.map((c, i) => <tspan class="ma-stroke__glyph" style={`--ma-i:${i}`}>{c}</tspan>)}</text>
+  </svg>
+  <span class="ma-sr">{text}</span>
+</Reveal>
+
+<style is:global>
+  @layer components {
+    :where(.ma-stroke) {
+      display: block;
+    }
+    /* direction: ltr. The line is laid out on the server from x = 0 with textLength, which is a left-to-right layout;
+       under a right-to-left page the text started at 0 and ran off the left edge (or reordered its punctuation). */
+    :where(.ma-stroke__svg) {
+      display: block;
+      width: 100%;
+      height: auto;
+      overflow: visible;
+      direction: ltr;
+      font-family: inherit;
+      font-weight: inherit;
+      letter-spacing: inherit;
+    }
+    :where(.ma-stroke__glyph) {
+      fill: var(--ma-stroke-fill, currentColor);
+      stroke: var(--ma-stroke-color, currentColor);
+      stroke-width: var(--ma-stroke-w, 2);
+      stroke-linejoin: round;
+      stroke-linecap: round;
+      paint-order: stroke;
+      stroke-dasharray: var(--ma-stroke-dash, 5em);
+      stroke-dashoffset: 0;
+      transition:
+        stroke-dashoffset var(--ma-stroke-dur, var(--ma-duration-slow)) var(--ma-ease-out) calc(var(--ma-r-delay, 0ms) + var(--ma-i, 0) * var(--ma-stroke-step, var(--ma-stagger))),
+        fill var(--ma-duration) var(--ma-ease-out) calc(var(--ma-r-delay, 0ms) + var(--ma-i, 0) * var(--ma-stroke-step, var(--ma-stagger)) + var(--ma-stroke-dur, var(--ma-duration-slow)));
+    }
+    /* Under the JS gate the outlines start undrawn and unfilled; Reveal's .ma-in lets the transitions run. */
+    :where([data-ma-js] .ma-stroke:not(.ma-in) .ma-stroke__glyph) {
+      stroke-dashoffset: var(--ma-stroke-dash, 5em);
+      fill: transparent;
+      transition: none;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-stroke__glyph) {
+        transition: none;
+      }
+    }
+    /* Print: drawn and filled. A headline printed before it scrolled into view was an empty box. */
+    @media print {
+      :where(.ma-stroke .ma-stroke__glyph) {
+        stroke-dashoffset: 0;
+        fill: var(--ma-stroke-fill, currentColor);
+        transition: none;
+      }
+    }
+  }
+</style>

package/src/components/StrokeDraw.meta.ts

@@ -0,0 +1,43 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'StrokeDraw',
+  slug: 'stroke-draw',
+  title: 'Stroke Draw',
+  description:
+    'A headline\'s outline draws itself glyph by glyph when it scrolls into view, then the fill comes in. SVG text with one stroked <tspan> per character, a dash longer than any outline offset to zero on a per-index delay. Composes Reveal; no script of its own. The server HTML holds the finished text.',
+  summary: 'A headline whose outline draws itself letter by letter as it scrolls into view, then fills.',
+  category: 'text',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<StrokeDraw text="Draw.">',
+  usage: `<StrokeDraw as="h1" text="Measured." class="text-6xl font-bold" />\n<StrokeDraw text="Outline only" fill={false} width={3} color="var(--ma-ink)" />`,
+  props: [
+    { name: 'text', type: 'string', description: 'The text, one line. Its width follows the container; the viewBox is sized from rough glyph advances and textLength justifies the spacing.' },
+    { name: 'as', type: 'HTMLTag', default: "'span'", description: 'Element to render.' },
+    { name: 'width', type: 'number', default: '2', description: 'Stroke width relative to a 100-unit font size. 1.5–3 reads as a pen; more reads as a marker.' },
+    { name: 'dash', type: 'number', default: '5', description: 'Dash length per glyph in em. Every glyph outline must fit inside it (Inter\'s run 2 to 4.5 em), and a glyph draws faster the shorter its outline is relative to the dash.' },
+    { name: 'color', type: 'string', default: "'currentColor'", description: 'Stroke colour.' },
+    { name: 'fill', type: 'boolean', default: 'true', description: 'Fill after the stroke lands; false leaves the outline.' },
+    { name: 'duration', type: 'number', default: 'preset (700)', description: 'Draw duration per glyph in ms. Unset, the preset\'s --ma-duration-slow.' },
+    { name: 'step', type: 'number', default: 'preset (ui: 60)', description: 'Delay between neighbouring glyphs in ms.' },
+    { name: 'delay', type: 'number', default: '0', description: 'Delay before the first glyph.' },
+    { name: 'once', type: 'boolean', default: 'true', description: 'Play once and stay.' },
+    { name: 'threshold', type: 'number', default: '0.2', description: 'Fraction visible to trigger.' },
+  ],
+  reducedMotion: 'The text appears drawn and filled at once.',
+  clientRouter: 'Inherits Reveal: rebinds after every navigation.',
+  craft: [
+    'pathLength does not apply to <text> in any engine (SVG 2 defines it for shapes), so the dash cannot be normalised to 1; it is 5 em per glyph instead, an upper bound on any Latin outline, and every glyph finishes inside the same duration.',
+    'One <tspan> per character (a grapheme, so a letter with a combining accent is drawn whole) with its own delay: the headline is written, not revealed. A single dash on the whole <text> would draw every letter at once.',
+    'Fill waits for the stroke: the transition on fill is delayed by the draw duration, so ink arrives after the pen.',
+    'paint-order: stroke keeps the stroke under the fill, so the finished letter is the plain glyph with no bold outline.',
+    'The <svg> is sized by its viewBox and fills the container width; nothing is measured on the client and the text scales like a headline should.',
+    'The line is laid out left to right from x = 0 whatever the page\'s direction: textLength fits it from there, and under dir="rtl" it ran off the left edge with its full stop in front.',
+  ],
+  related: ['split-text', 'typewriter', 'progress'],
+  intents: ['text stroke animation', 'draw text outline svg', 'handwritten headline animation', 'svg text stroke dashoffset', 'outline text draw on scroll'],
+  replaces: ['TextPressure / stroke text effects (React Bits)', 'SVG stroke text with GSAP DrawSVG'],
+  fixture: { props: { text: 'Fixture content for StrokeDraw' }, expect: 'ma-sr">Fixture content for StrokeDraw</span>' },
+} satisfies ComponentMeta;