@moonarc/core 0.1.0

package/src/components/Reveal.astro

@@ -0,0 +1,292 @@
+---
+/**
+ * Reveal — scroll-triggered entrance that survives <ClientRouter />.
+ *
+ * Play once and stay (or replay), per-child stagger, scroll-linked scrub with
+ * a real fallback, a reduced-motion branch that keeps the fade and drops the
+ * travel, and server HTML that is fully readable when JS never runs.
+ *
+ * Content is hidden only under html[data-ma-js] (set before paint by the
+ * integration), never in the server HTML itself.
+ *
+ * Curve, duration, travel and stagger default to the active preset
+ * (--ma-ease, --ma-duration, --ma-travel-enter, --ma-stagger); a prop sets a
+ * component-local property (--ma-r-*) that wins over the preset. The delay
+ * and the per-child index are --ma-r-delay and --ma-r-i: as bare --ma-delay
+ * and --ma-i they were inherited from any other component that set them.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+type From = 'bottom' | 'top' | 'left' | 'right' | 'clip' | 'none';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Where the element travels from; `clip` wipes it open from the bottom edge, fully painted; `none` fades only. */
+  from?: From;
+  /** Travel distance in px. Unset, the preset's --ma-travel-enter, from whichever side. */
+  distance?: number;
+  /** Scale to grow from, e.g. 0.96. */
+  scale?: number;
+  /** Blur in px to sharpen from. */
+  blur?: number;
+  /** Duration in ms. */
+  duration?: number;
+  /** Delay in ms before the reveal starts. */
+  delay?: number;
+  /** Any CSS easing. */
+  easing?: string;
+  /** Interval in ms between direct children; `true` takes the preset's --ma-stagger. When set, the children animate and the wrapper does not. */
+  stagger?: number | boolean;
+  /** Play once and stay. `false` re-plays every time the element enters. */
+  once?: boolean;
+  /** Fraction of the element that must be visible to trigger, 0–1; for an element taller than the viewport, that fraction of the viewport's height. */
+  threshold?: number;
+  /** IntersectionObserver rootMargin. */
+  rootMargin?: string;
+  /** Scroll-linked: progress follows the element's entry instead of triggering once. Ignores stagger. */
+  scrub?: boolean;
+}
+
+const {
+  as: Tag = 'div',
+  from = 'bottom',
+  distance,
+  scale,
+  blur,
+  duration,
+  delay,
+  easing,
+  stagger,
+  once = true,
+  threshold,
+  rootMargin,
+  scrub = false,
+  class: className,
+  style,
+  ...rest
+} = Astro.props;
+
+// Only non-default values become inline custom properties; defaults live in the CSS. An unset distance is the preset's
+// travel from any side: it used to follow the preset from the bottom only (the CSS default) and be pinned at 24 px from
+// the top, the left and the right.
+const vars: string[] = [];
+const travel = distance === undefined ? 'var(--ma-travel-enter, 24px)' : `${distance}px`;
+if (from === 'left' || from === 'right') vars.push(`--ma-dx:${from === 'left' ? `calc(-1 * ${travel})` : travel}`, '--ma-dy:0px');
+else if (from === 'top') vars.push(`--ma-dy:calc(-1 * ${travel})`);
+else if (from !== 'bottom') vars.push('--ma-dy:0px');
+else if (distance !== undefined) vars.push(`--ma-dy:${travel}`);
+if (scale !== undefined && scale !== 1) vars.push(`--ma-scale:${scale}`);
+if (blur) vars.push(`--ma-blur:${blur}px`);
+if (duration !== undefined) vars.push(`--ma-r-dur:${duration}ms`);
+if (delay) vars.push(`--ma-r-delay:${delay}ms`);
+if (easing) vars.push(`--ma-r-ease:${easing}`);
+// `stagger` alone (true) leaves the interval to the preset's --ma-stagger; it used to print --ma-r-stagger:truems
+if (typeof stagger === 'number' && stagger) vars.push(`--ma-r-stagger:${stagger}ms`);
+if (typeof style === 'string' && style) vars.push(style);
+---
+
+<Tag
+  class:list={['ma-reveal', className]}
+  data-ma-reveal
+  data-once={once ? undefined : 'false'}
+  data-stagger={stagger ? '' : undefined}
+  data-scrub={scrub ? '' : undefined}
+  data-from={from === 'clip' ? 'clip' : undefined}
+  data-threshold={threshold}
+  data-root-margin={rootMargin}
+  style={vars.length ? vars.join(';') : undefined}
+  {...rest}
+>
+  <slot />
+</Tag>
+
+<style is:global>
+  @layer components {
+    /* Hidden state — gated on html[data-ma-js] so server HTML stays readable. */
+    :where([data-ma-js] .ma-reveal:not([data-stagger]):not([data-scrub]):not(.ma-in)),
+    :where([data-ma-js] .ma-reveal[data-stagger]:not([data-scrub]):not(.ma-in) > *) {
+      opacity: 0;
+      translate: var(--ma-dx, 0px) var(--ma-dy, var(--ma-travel-enter, 24px));
+      scale: var(--ma-scale, 1);
+      filter: blur(var(--ma-blur, 0px));
+    }
+
+    :where(.ma-reveal:not([data-stagger]):not([data-scrub])),
+    :where(.ma-reveal[data-stagger]:not([data-scrub]) > *) {
+      transition-property: opacity, translate, scale, filter, mask-size;
+      transition-duration: var(--ma-r-dur, var(--ma-duration, 450ms));
+      transition-timing-function: var(--ma-r-ease, var(--ma-ease, ease-out));
+      transition-delay: var(--ma-r-delay, 0ms);
+    }
+    :where(.ma-reveal[data-stagger]:not([data-scrub]) > *) {
+      transition-delay: calc(var(--ma-r-delay, 0ms) + var(--ma-r-i, 0) * var(--ma-r-stagger, var(--ma-stagger, 60ms)));
+    }
+    /* from="clip": the element is fully painted and wipes open from the bottom — no fade, no travel. A mask, not
+       clip-path, on purpose: Chromium's IntersectionObserver applies the target's own clip-path, so an element
+       clipped to nothing never intersects and would never reveal. The mask is not part of the intersection. */
+    :where(.ma-reveal[data-from='clip']:not([data-stagger]):not([data-scrub])),
+    :where(.ma-reveal[data-from='clip'][data-stagger]:not([data-scrub]) > *) {
+      mask-image: linear-gradient(#000 0 0);
+      mask-repeat: no-repeat;
+      mask-position: 0 100%;
+      mask-size: 100% 100%;
+    }
+    :where([data-ma-js] .ma-reveal[data-from='clip']:not([data-stagger]):not([data-scrub]):not(.ma-in)),
+    :where([data-ma-js] .ma-reveal[data-from='clip'][data-stagger]:not([data-scrub]):not(.ma-in) > *) {
+      opacity: 1;
+      translate: 0 0;
+      mask-size: 100% 0%;
+    }
+    /* Leaving (once=false): out fast, no stagger — symmetry would read as a wait. */
+    :where(.ma-reveal[data-leaving]),
+    :where(.ma-reveal[data-leaving] > *) {
+      transition-duration: var(--ma-duration-fast);
+      transition-delay: 0ms;
+    }
+
+    /* Scrub: scroll-linked in browsers with view timelines … */
+    @supports (animation-timeline: view()) {
+      :where([data-ma-js] .ma-reveal[data-scrub]) {
+        animation: ma-reveal linear both;
+      }
+      /* Separate rule with a different (equivalent) selector on purpose:
+         lightningcss folds animation-timeline into the `animation` shorthand,
+         and browsers reject that declaration because the shorthand cannot set
+         a timeline. Keeping the selectors distinct prevents the merge. */
+      :where([data-ma-js]) :where(.ma-reveal[data-scrub]) {
+        animation-timeline: view();
+        animation-range: var(--ma-range, entry 0% entry 100%);
+      }
+    }
+    /* … and driven by a scroll listener writing --ma-p everywhere else: a raw ratio, clamped here to 0–1. */
+    :where([data-ma-js] .ma-reveal[data-scrub][data-ma-fallback]) {
+      opacity: clamp(0, var(--ma-p, 1), 1);
+      translate: calc(var(--ma-dx, 0px) * (1 - clamp(0, var(--ma-p, 1), 1))) calc(var(--ma-dy, var(--ma-travel-enter, 24px)) * (1 - clamp(0, var(--ma-p, 1), 1)));
+      transition: opacity 120ms linear, translate 120ms linear;
+    }
+
+    /* Reduced motion: keep the fade, drop the travel. Declared, not overridden
+       through the custom properties, because inline style would win. */
+    @media (prefers-reduced-motion: reduce) {
+      :where([data-ma-js] .ma-reveal:not(.ma-in)),
+      :where([data-ma-js] .ma-reveal[data-stagger]:not(.ma-in) > *) {
+        translate: 0 0;
+        scale: 1;
+        filter: none;
+      }
+      /* clip becomes the fade everything else gets */
+      :where([data-ma-js] .ma-reveal[data-from='clip']:not(.ma-in)),
+      :where([data-ma-js] .ma-reveal[data-from='clip'][data-stagger]:not(.ma-in) > *) {
+        mask-size: 100% 100%;
+        opacity: 0;
+      }
+      :where(.ma-reveal),
+      :where(.ma-reveal > *) {
+        transition-duration: var(--ma-duration-fast);
+        transition-delay: 0ms;
+      }
+      :where([data-ma-js] .ma-reveal[data-scrub]) {
+        animation: none;
+        opacity: 1;
+        translate: 0 0;
+      }
+    }
+
+    /* Print: the end state, with no transition into it. Switching to print media is a style change like any other, so
+       a transition ran from the hidden state and the page printed at its first frame (opacity 0). */
+    @media print {
+      :where(.ma-reveal),
+      :where(.ma-reveal > *) {
+        opacity: 1;
+        translate: none;
+        scale: none;
+        filter: none;
+        mask-image: none;
+        animation: none;
+        transition: none;
+      }
+    }
+  }
+
+  @keyframes ma-reveal {
+    from {
+      opacity: 0;
+      translate: var(--ma-dx, 0px) var(--ma-dy, var(--ma-travel-enter, 24px));
+      scale: var(--ma-scale, 1);
+    }
+    to {
+      opacity: 1;
+      translate: 0 0;
+      scale: 1;
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+
+  const NATIVE_SCRUB = typeof CSS !== 'undefined' && CSS.supports('animation-timeline: view()');
+
+  onMount<HTMLElement>('[data-ma-reveal]', (el, { signal }) => {
+    const targets = el.hasAttribute('data-stagger') ? (Array.from(el.children) as HTMLElement[]) : [el];
+    if (targets.length > 1) targets.forEach((t, i) => t.style.setProperty('--ma-r-i', String(i)));
+
+    if (el.hasAttribute('data-scrub')) {
+      if (NATIVE_SCRUB) return;
+      el.dataset.maFallback = '';
+      // The entry range view() measures: 0 while the top is below the viewport, 1 once the element has come in by its
+      // own height or the viewport's, whichever is less, and 1 from then on (the CSS clamps the ratio to that range).
+      // The intersection ratio this used to read never reached 1 for an element taller than the viewport, and fell
+      // again as the element left at the top. Capture hears a scroller inside the page as well.
+      const set = () => {
+        const r = el.getBoundingClientRect();
+        el.style.setProperty('--ma-p', `${(innerHeight - r.top) / Math.min(r.height, innerHeight)}`);
+      };
+      set();
+      for (const type of ['scroll', 'resize']) addEventListener(type, set, { signal, capture: true });
+      return;
+    }
+
+    const once = el.dataset.once !== 'false';
+    const done = () => once && el.classList.contains('ma-in');
+    // will-change is a loan: taken when the reveal starts, repaid when the last target settles. Any property settles
+    // it, since from="clip" moves mask-size and never opacity; an empty staggered group has no last target to wait for.
+    const will = (v: string) => targets.forEach((t) => (t.style.willChange = v));
+    // Revealed already and played once: an element persisted across a swap keeps its state, and repays a loan the swap
+    // cut off before its transition ended. Observed again, it was hidden as soon as it was off screen and replayed on
+    // the way back.
+    if (done()) return will('');
+    targets.at(-1)?.addEventListener('transitionend', () => will(''), { signal });
+
+    // `threshold` is a share of the element, and a group taller than the screen may never show that share: eight cards
+    // stacked on a phone are 3 000 px, and 20 % of them is more than a 568 px screen holds, so they never appeared.
+    // Every observer's first entry says how tall the element is against the viewport; past it, the share becomes that
+    // fraction of the viewport's own height and the observer is set again. A resize starts over.
+    const share = Number(el.dataset.threshold ?? 0.2);
+    let io: IntersectionObserver;
+    const watch = (threshold = share) => {
+      io?.disconnect();
+      io = new IntersectionObserver(
+        ([e]) => {
+          const fit = Math.min(share, (share * innerHeight) / e!.boundingClientRect.height);
+          if (fit < threshold) return watch(fit);
+          if (e!.isIntersecting) {
+            will('translate, opacity');
+            delete el.dataset.leaving;
+            el.classList.add('ma-in');
+            if (once) io.disconnect();
+          } else if (el.classList.contains('ma-in')) {
+            el.dataset.leaving = '';
+            el.classList.remove('ma-in');
+          }
+        },
+        { threshold, rootMargin: el.dataset.rootMargin ?? '0px 0px -10% 0px' },
+      );
+      io.observe(el);
+    };
+    watch();
+    addEventListener('resize', () => done() || watch(), { signal });
+    signal.addEventListener('abort', () => io.disconnect());
+  });
+</script>

package/src/components/Reveal.meta.ts

@@ -0,0 +1,48 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Reveal',
+  slug: 'reveal',
+  title: 'Scroll Reveal',
+  description:
+    'Entrance on scroll that plays once and stays, staggers its children, scrubs with the scroll position when asked, honours reduced motion, and keeps working after every ClientRouter navigation. Server HTML stays readable without JavaScript.',
+  summary: 'A scroll reveal animation that plays once, staggers children, can scrub with the scroll, and survives ClientRouter.',
+  category: 'scroll',
+  tier: 'B',
+  trigger: ['scroll'],
+  support: { baseline: 'widely', needs: [], fallback: 'scrub uses animation-timeline: view() where it exists and, everywhere else, a scroll listener that measures the same entry range; from="clip" wipes with mask-size (Chrome 120, Firefox 53, Safari 15.4) and simply appears before that' },
+  readout: '<Reveal stagger={60}>',
+  usage: `<Reveal from="bottom" distance={24}>\n  <h2>Appears once, stays.</h2>\n</Reveal>\n\n<Reveal as="ul" stagger={60}>\n  <li>one</li><li>two</li><li>three</li>\n</Reveal>\n\n<Reveal from="clip">\n  <img src="/cover.jpg" alt="" />\n</Reveal>`,
+  props: [
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+    { name: 'from', type: "'bottom' | 'top' | 'left' | 'right' | 'clip' | 'none'", default: "'bottom'", description: 'Where the element travels from. clip wipes the element open from its bottom edge (fully painted, no fade, no travel); none fades only.' },
+    { name: 'distance', type: 'number', default: 'preset (ui: 24)', description: 'Travel distance in px. Unset, it follows the preset\'s --ma-travel-enter from whichever side it travels; set, it pins this instance.' },
+    { name: 'scale', type: 'number', description: 'Scale to grow from, e.g. 0.96. Never below 0.9.' },
+    { name: 'blur', type: 'number', description: 'Blur in px to sharpen from. Costly on large elements; keep under 8.' },
+    { name: 'duration', type: 'number', default: 'preset (ui: 450)', description: 'Duration in ms. Unset, it follows the active preset (data-ma-preset).' },
+    { name: 'delay', type: 'number', default: '0', description: 'Delay in ms.' },
+    { name: 'easing', type: 'string', default: 'preset curve', description: 'Any CSS easing. Unset, it is the preset\'s sampled spring.' },
+    { name: 'stagger', type: 'number | true', description: 'Interval in ms between direct children; the preset\'s --ma-stagger when set without a value. When set, the children animate instead of the wrapper. 30–80 ms reads well.' },
+    { name: 'once', type: 'boolean', default: 'true', description: 'Play once and stay. false re-plays on every entry, leaving quickly and without stagger.' },
+    { name: 'threshold', type: 'number', default: '0.2', description: "Fraction of the element that must be visible to trigger; for an element taller than the viewport, that fraction of the viewport's height." },
+    { name: 'rootMargin', type: 'string', default: "'0px 0px -10% 0px'", description: 'IntersectionObserver rootMargin; the default waits until the element is 10% into the viewport.' },
+    { name: 'scrub', type: 'boolean', default: 'false', description: 'Scroll-linked: progress follows entry into the viewport. Uses animation-timeline: view() where supported; elsewhere a scroll listener measures the same entry range, so a tall element still reaches full and stays full as it leaves.' },
+  ],
+  reducedMotion: 'Keeps a fast opacity fade, drops translate, scale, blur and stagger. Scrub becomes static.',
+  clientRouter:
+    'Binds through the shared runtime: every instance on the new page is observed after each navigation, observers are disconnected before the swap, and the html[data-ma-js] gate is restored so nothing flashes. A once-reveal persisted across the swap (transition:persist) keeps its revealed state instead of being observed again.',
+  craft: [
+    'Curve, duration, travel and stagger resolve from the active preset, so one attribute on <html> retunes every reveal on the page; a prop pins one instance.',
+    '24 px of travel is visible without reading as a slide; scale never below 0.9.',
+    'Stagger 30–80 ms; cap the group: ten items at 60 ms is 600 ms of waiting.',
+    'Leaving (once=false) is fast and unstaggered so re-entry never fights the reader.',
+    'Hidden state is gated on html[data-ma-js]; without JS the server HTML is the end state.',
+    'from="clip" is a wipe, not a fade: the element is painted in full and a mask grows from its bottom edge to full height on the same preset curve. An image or a card appears as if uncovered. It is a mask rather than clip-path because Chromium\'s IntersectionObserver applies the target\'s clip-path: an element clipped to nothing never intersects, so it would never reveal.',
+  ],
+  related: ['split-text', 'marquee'],
+  intents: ['scroll reveal', 'fade in on scroll', 'animate on scroll', 'AOS alternative', 'stagger children on scroll', 'scroll-linked reveal', 'view transitions safe reveal'],
+  replaces: ['AOS', 'AnimatedContent (React Bits)', 'FadeContent (React Bits)', 'ScrollReveal (React Bits)', 'BlurText (React Bits)', 'motion.div whileInView'],
+  // stagger alone takes the preset's interval (it printed --ma-r-stagger:truems), and from="top" with no distance
+  // travels the preset's distance (it was pinned at -24px)
+  fixture: { props: { from: 'top', stagger: true }, slot: '<p>Fixture content for Reveal</p>', expect: 'data-stagger style="--ma-dy:calc(-1 * var(--ma-travel-enter, 24px))" class="ma-reveal"' },
+} satisfies ComponentMeta;

package/src/components/Ripple.astro

@@ -0,0 +1,94 @@
+---
+/**
+ * Ripple — rings expand from a point and fade, one after another. Zero JS:
+ * each ring is an element scaling and fading on its own delay, so the set
+ * reads as a continuous pulse. Fills its positioned parent.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Number of rings in flight. */
+  count?: number;
+  /** Seconds a ring takes to expand and fade. */
+  duration?: number;
+  /** Ring colour. */
+  color?: string;
+  /** Final diameter as a fraction of the box's width, capped at the nearest container's inline size. */
+  size?: number;
+  /** Origin, x then y as in background-position: lengths, percentages or keywords; one value centres the other axis. */
+  origin?: string;
+  /** Ring thickness in px. */
+  width?: number;
+}
+
+const { count = 4, duration = 4, color = 'currentColor', size = 1.4, origin = '50% 50%', width = 1, class: className, style, ...rest } = Astro.props;
+const n = Math.max(1, Math.min(count, 8));
+// origin → one left and one top. Written into the inset shorthand it was top and right (inset is top right bottom left),
+// so the default 50% 50% put the rings' centre half a ring left of the box's. Split at the top level (a calc() keeps its
+// spaces), keywords to percentages, and "top left" read as y x, as background-position reads it.
+const parts: string[] = [];
+let depth = 0;
+let part = '';
+for (const ch of origin.trim()) {
+  if (ch === '(') depth++;
+  else if (ch === ')') depth--;
+  if (depth === 0 && /\s/.test(ch)) {
+    if (part) parts.push(part);
+    part = '';
+  } else part += ch;
+}
+if (part) parts.push(part);
+let [x = 'center', y = 'center'] = parts;
+if (/^(top|bottom)$/.test(x) || /^(left|right)$/.test(y)) [x, y] = [y, x];
+const KEYWORD: Record<string, string> = { left: '0%', top: '0%', center: '50%', right: '100%', bottom: '100%' };
+const vars = [`--ma-rp-n:${n};--ma-rp-dur:${duration}s;--ma-rp-color:${color};--ma-rp-size:${size};--ma-rp-x:${KEYWORD[x] ?? x};--ma-rp-y:${KEYWORD[y] ?? y};--ma-rp-w:${width}px`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-ripple', className]} aria-hidden="true" style={vars} {...rest}>
+  {Array.from({ length: n }, (_, i) => <i style={`--ma-rp-i:${i}`}></i>)}
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-ripple) {
+      position: absolute;
+      inset: 0;
+      overflow: hidden;
+      pointer-events: none;
+      contain: strict;
+    }
+    :where(.ma-ripple > i) {
+      position: absolute;
+      left: var(--ma-rp-x, 50%);
+      top: var(--ma-rp-y, 50%);
+      width: calc(min(100%, 100cqi) * var(--ma-rp-size, 1.4));
+      aspect-ratio: 1;
+      border: var(--ma-rp-w, 1px) solid var(--ma-rp-color, currentColor);
+      border-radius: 50%;
+      translate: -50% -50%;
+      opacity: 0;
+      scale: 0;
+      will-change: scale, opacity;
+      animation: ma-ripple var(--ma-rp-dur, 4s) var(--ma-ease-out) infinite;
+      animation-delay: calc(var(--ma-rp-i, 0) * var(--ma-rp-dur, 4s) / var(--ma-rp-n, 4));
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-ripple > i) {
+        animation: none;
+        opacity: 0.25;
+        scale: calc(0.3 + var(--ma-rp-i, 0) * 0.2);
+      }
+    }
+  }
+
+  @keyframes ma-ripple {
+    0% {
+      opacity: 0.6;
+      scale: 0;
+    }
+    100% {
+      opacity: 0;
+      scale: 1;
+    }
+  }
+</style>

package/src/components/Ripple.meta.ts

@@ -0,0 +1,34 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Ripple',
+  slug: 'ripple',
+  title: 'Ripple',
+  description: 'Rings expand from a point and fade, one after another, like a pulse. Each ring is an element scaling and fading on its own delay; pure CSS, compositor only. Fills its positioned parent.',
+  summary: 'Rings that expand from a point and fade one after another, like a pulse.',
+  category: 'background',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<Ripple count={4}>',
+  usage: `<div class="relative grid h-64 place-items-center">\n  <Ripple color="var(--accent)" />\n  <button class="relative rounded-full bg-fg px-5 py-3 text-bg">Live</button>\n</div>`,
+  props: [
+    { name: 'count', type: 'number', default: '4', description: 'Rings in flight, 1–8; evenly spaced over the duration.' },
+    { name: 'duration', type: 'number', default: '4', description: 'Seconds a ring takes to expand and fade.' },
+    { name: 'color', type: 'string', default: "'currentColor'", description: 'Ring colour.' },
+    { name: 'size', type: 'number', default: '1.4', description: 'Final diameter as a fraction of the box\'s width (the positioned parent it fills), capped at the nearest container\'s inline size.' },
+    { name: 'origin', type: 'string', default: "'50% 50%'", description: 'Where the rings start, x then y as in background-position: lengths, percentages or the keywords left, center, right, top and bottom ("top left" works too); one value centres the other axis. The centre of every ring sits on this point.' },
+    { name: 'width', type: 'number', default: '1', description: 'Ring thickness in px.' },
+  ],
+  reducedMotion: 'Four static concentric rings at a quarter opacity.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'Ease-out: a ring slows as it grows, like water. Linear rings look like radar.',
+    'Delays are duration / count, so the pulse is even and the last ring hands off to the first.',
+    'Opacity starts at 0.6, never 1: rings are texture behind content, not a subject.',
+  ],
+  related: ['dot-pattern', 'aurora', 'spinner'],
+  intents: ['ripple effect', 'pulsing rings', 'radar pulse background', 'concentric circles animation'],
+  replaces: ['Ripple (Magic UI)', 'pulse rings (custom CSS)'],
+  fixture: { expect: 'class="ma-ripple"' },
+} satisfies ComponentMeta;

package/src/components/RotatingText.astro

@@ -0,0 +1,170 @@
+---
+/**
+ * RotatingText — cycles through words in place, zero JS.
+ *
+ * Every custom property is namespaced (--ma-rotate-*): @property is global,
+ * and a short name registered by one component as non-inherited breaks any
+ * other component that reads the same name through inheritance.
+ *
+ * Words stack in one grid cell so the box is always as wide as the widest
+ * word; each word runs the same keyframes offset by its index. The travel is a
+ * registered custom property (--ma-rotate-y) so reduced motion can neutralise it with
+ * one declaration and keep the crossfade.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'span'> {
+  /** Words to cycle through, 2–8. A single word stays in place. */
+  words: string[];
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Time each word is shown, ms (includes its entrance). */
+  period?: number;
+  /** The box follows the current word's width, so the sentence around it shifts smoothly instead of being sized to the widest word. */
+  fluid?: boolean;
+}
+
+const { words, as: Tag = 'span', period = 2200, fluid = false, class: className, style, ...rest } = Astro.props;
+const list: string[] = words.slice(0, 8);
+const n = Math.max(list.length, 2);
+const inline = [`--ma-rotate-n:${n}`, `--ma-rotate-period:${period}ms`, `--ma-rotate-anim:ma-rotate-${n}`, fluid && `--ma-rotate-anim-w:ma-rotate-fluid-${n}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-rotate', className]} data-fluid={fluid ? '' : undefined} style={inline} {...rest}>
+  {list.map((word, i) => <span class="ma-rotate__word" aria-hidden="true" style={`--ma-rotate-i:${i}${fluid ? `;--ma-rotate-len:${[...word].length}` : ''}`}>{word}</span>)}
+  <span class="ma-sr">{list.join(', ')}</span>
+</Tag>
+
+<style is:global>
+  @property --ma-rotate-y {
+    syntax: '<length-percentage>';
+    inherits: false;
+    initial-value: 0%;
+  }
+
+  @layer components {
+    :where(.ma-rotate) {
+      display: inline-grid;
+      overflow: clip;
+      vertical-align: bottom;
+    }
+    :where(.ma-rotate__word) {
+      grid-area: 1 / 1;
+      translate: 0 var(--ma-rotate-y);
+      opacity: 0;
+      animation: var(--ma-rotate-anim) calc(var(--ma-rotate-n) * var(--ma-rotate-period)) linear infinite;
+      animation-delay: calc(var(--ma-rotate-i) * var(--ma-rotate-period));
+      will-change: translate, opacity;
+    }
+    /* fluid: a second animation caps each word's max-width — 0 while it is away, its bound while it is the word — so the cell
+       (the widest contribution) moves from one word's width to the next instead of sitting at the widest of them all */
+    :where(.ma-rotate[data-fluid] .ma-rotate__word) {
+      white-space: nowrap;
+      --ma-rotate-w: calc(var(--ma-rotate-len, 8) * 0.75em);
+      animation-name: var(--ma-rotate-anim), var(--ma-rotate-anim-w);
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-rotate__word) {
+        translate: 0 0;
+        will-change: auto;
+      }
+      :where(.ma-rotate[data-fluid] .ma-rotate__word) {
+        animation-name: var(--ma-rotate-anim);
+        max-width: none;
+      }
+    }
+    /* One word (the first child and the one before .ma-sr) has nothing to rotate to: it stays, reduced motion or not.
+       It used to run the two-word cycle against an empty slot and was gone for almost half of every turn. */
+    :where(.ma-rotate__word:first-child:nth-last-child(2)) {
+      opacity: 1;
+      translate: none;
+      animation: none;
+      will-change: auto;
+    }
+  }
+
+  @keyframes ma-rotate-2 {
+    0% { --ma-rotate-y: 110%; opacity: 0; animation-timing-function: cubic-bezier(0.23, 1, 0.32, 1); }
+    9.00% { --ma-rotate-y: 0%; opacity: 1; }
+    50.00% { --ma-rotate-y: 0%; opacity: 1; animation-timing-function: cubic-bezier(0.5, 0, 0.75, 0); }
+    59.00% { --ma-rotate-y: -110%; opacity: 0; }
+    100% { --ma-rotate-y: -110%; opacity: 0; }
+  }
+  @keyframes ma-rotate-3 {
+    0% { --ma-rotate-y: 110%; opacity: 0; animation-timing-function: cubic-bezier(0.23, 1, 0.32, 1); }
+    6.00% { --ma-rotate-y: 0%; opacity: 1; }
+    33.33% { --ma-rotate-y: 0%; opacity: 1; animation-timing-function: cubic-bezier(0.5, 0, 0.75, 0); }
+    39.33% { --ma-rotate-y: -110%; opacity: 0; }
+    100% { --ma-rotate-y: -110%; opacity: 0; }
+  }
+  @keyframes ma-rotate-4 {
+    0% { --ma-rotate-y: 110%; opacity: 0; animation-timing-function: cubic-bezier(0.23, 1, 0.32, 1); }
+    4.50% { --ma-rotate-y: 0%; opacity: 1; }
+    25.00% { --ma-rotate-y: 0%; opacity: 1; animation-timing-function: cubic-bezier(0.5, 0, 0.75, 0); }
+    29.50% { --ma-rotate-y: -110%; opacity: 0; }
+    100% { --ma-rotate-y: -110%; opacity: 0; }
+  }
+  @keyframes ma-rotate-5 {
+    0% { --ma-rotate-y: 110%; opacity: 0; animation-timing-function: cubic-bezier(0.23, 1, 0.32, 1); }
+    3.60% { --ma-rotate-y: 0%; opacity: 1; }
+    20.00% { --ma-rotate-y: 0%; opacity: 1; animation-timing-function: cubic-bezier(0.5, 0, 0.75, 0); }
+    23.60% { --ma-rotate-y: -110%; opacity: 0; }
+    100% { --ma-rotate-y: -110%; opacity: 0; }
+  }
+  @keyframes ma-rotate-6 {
+    0% { --ma-rotate-y: 110%; opacity: 0; animation-timing-function: cubic-bezier(0.23, 1, 0.32, 1); }
+    3.00% { --ma-rotate-y: 0%; opacity: 1; }
+    16.67% { --ma-rotate-y: 0%; opacity: 1; animation-timing-function: cubic-bezier(0.5, 0, 0.75, 0); }
+    19.67% { --ma-rotate-y: -110%; opacity: 0; }
+    100% { --ma-rotate-y: -110%; opacity: 0; }
+  }
+  @keyframes ma-rotate-7 {
+    0% { --ma-rotate-y: 110%; opacity: 0; animation-timing-function: cubic-bezier(0.23, 1, 0.32, 1); }
+    2.57% { --ma-rotate-y: 0%; opacity: 1; }
+    14.29% { --ma-rotate-y: 0%; opacity: 1; animation-timing-function: cubic-bezier(0.5, 0, 0.75, 0); }
+    16.86% { --ma-rotate-y: -110%; opacity: 0; }
+    100% { --ma-rotate-y: -110%; opacity: 0; }
+  }
+  @keyframes ma-rotate-fluid-2 {
+    0% { max-width: 0; }
+    9%, 59% { max-width: var(--ma-rotate-w); }
+    62%, 100% { max-width: 0; }
+  }
+  @keyframes ma-rotate-fluid-3 {
+    0% { max-width: 0; }
+    6%, 39.33% { max-width: var(--ma-rotate-w); }
+    41.33%, 100% { max-width: 0; }
+  }
+  @keyframes ma-rotate-fluid-4 {
+    0% { max-width: 0; }
+    4.5%, 29.5% { max-width: var(--ma-rotate-w); }
+    31%, 100% { max-width: 0; }
+  }
+  @keyframes ma-rotate-fluid-5 {
+    0% { max-width: 0; }
+    3.6%, 23.6% { max-width: var(--ma-rotate-w); }
+    24.8%, 100% { max-width: 0; }
+  }
+  @keyframes ma-rotate-fluid-6 {
+    0% { max-width: 0; }
+    3%, 19.67% { max-width: var(--ma-rotate-w); }
+    20.67%, 100% { max-width: 0; }
+  }
+  @keyframes ma-rotate-fluid-7 {
+    0% { max-width: 0; }
+    2.57%, 16.86% { max-width: var(--ma-rotate-w); }
+    17.71%, 100% { max-width: 0; }
+  }
+  @keyframes ma-rotate-fluid-8 {
+    0% { max-width: 0; }
+    2.25%, 14.75% { max-width: var(--ma-rotate-w); }
+    15.5%, 100% { max-width: 0; }
+  }
+  @keyframes ma-rotate-8 {
+    0% { --ma-rotate-y: 110%; opacity: 0; animation-timing-function: cubic-bezier(0.23, 1, 0.32, 1); }
+    2.25% { --ma-rotate-y: 0%; opacity: 1; }
+    12.50% { --ma-rotate-y: 0%; opacity: 1; animation-timing-function: cubic-bezier(0.5, 0, 0.75, 0); }
+    14.75% { --ma-rotate-y: -110%; opacity: 0; }
+    100% { --ma-rotate-y: -110%; opacity: 0; }
+  }
+</style>