@moonarc/core 0.1.0

package/src/components/SplitFlap.meta.ts

@@ -0,0 +1,39 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'SplitFlap',
+  slug: 'split-flap',
+  title: 'Split Flap',
+  description:
+    'A departures board: every character spins through the alphabet and locks, one cell after another, when the board scrolls into view. Each glyph is a CSS counter on a registered integer that transitions from blank to the letter, and a flap turns once per step. Composes Reveal; no script of its own. The server HTML already reads the final text.',
+  summary: 'A split-flap departures board: each character spins through the alphabet and locks as the board scrolls into view.',
+  category: 'text',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'newly', needs: ['counter-set', 'property', 'counter-style'], fallback: 'the final text, shown at once' },
+  readout: '<SplitFlap text="DEPARTURES">',
+  usage: `<SplitFlap as="h2" text="Departures" class="font-mono" />\n<SplitFlap text="AMS 14:05 ON TIME" step={45} stagger={30} />`,
+  props: [
+    { name: 'text', type: 'string', description: 'The text. Boards are uppercase, so letters are uppercased; A–Z, 0–9 and : . - / + & ? ! are in the set, anything else renders as ?.' },
+    { name: 'as', type: 'HTMLTag', default: "'span'", description: 'Element to render.' },
+    { name: 'step', type: 'number', default: 'preset (ui: 60)', description: 'Milliseconds per character step (one flap). Unset, it follows the preset\'s --ma-stagger; 45–70 reads like a real board.' },
+    { name: 'stagger', type: 'number', default: 'preset (40)', description: 'Milliseconds between neighbouring cells starting. Unset, the preset\'s --ma-stagger-tight.' },
+    { name: 'delay', type: 'number', default: '0', description: 'Delay in ms before the first cell.' },
+    { name: 'once', type: 'boolean', default: 'true', description: 'Play once and stay; false replays on every entry.' },
+    { name: 'threshold', type: 'number', default: '0.2', description: 'Fraction visible to trigger.' },
+  ],
+  reducedMotion: 'The final text appears at once; nothing spins.',
+  clientRouter: 'Inherits Reveal: rebinds after every navigation, so the board replays on a fresh page.',
+  craft: [
+    'The letter is content: counter() on a registered <integer> with a fixed-system @counter-style whose symbols are the charset. Integers interpolate in steps, so a linear transition from 0 to 19 rewrites the glyph nineteen times. The spin is the browser stepping through the alphabet, not a sprite.',
+    'Each cell\'s transition lasts index × step, so A locks first and Z last: cells lock one by one in the order a real board does, and the flap animation runs exactly index times at the same step, so the turn and the letter change stay in sync.',
+    'One flap: the top half turning down over the hinge on an ease-in is what the eye reads; the bottom half stays put. Perspective on the cell keeps the turn from looking like a squash.',
+    'Blank at index 0, so every cell starts empty and the board fills in. The word is legible at the moment the last cell locks, never before.',
+    'A visually hidden span (.ma-sr) carries the string; the cells are aria-hidden and the counters are decoration.',
+    'One cell per grapheme, and the board takes dir="auto" from its own text: the cells are a flex row, which follows the page\'s direction, and on a right-to-left page it spelled the word backwards.',
+  ],
+  related: ['count-up', 'text-scramble', 'typewriter'],
+  intents: ['split flap text', 'departures board animation', 'airport board text', 'flip board letters', 'solari board css'],
+  replaces: ['SplitFlap / FlipText effects (React Bits, Aceternity)', 'split-flap canvas boards'],
+  fixture: { props: { text: 'Fixture content for SplitFlap' }, expect: 'ma-sr">Fixture content for SplitFlap</span>' },
+} satisfies ComponentMeta;

package/src/components/SplitText.astro

@@ -0,0 +1,208 @@
+---
+/**
+ * SplitText — split on the server, reveal on scroll, one string to a reader.
+ *
+ * Composes Reveal: the parts are direct children with a per-child stagger, so
+ * it inherits once-and-stay, reduced motion and ClientRouter safety, and ships
+ * no script of its own. A visually hidden copy (.ma-sr) + aria-hidden parts keep it
+ * one string for assistive tech instead of a stream of letters.
+ *
+ * `mask` wraps every part in a clipped box it rises out of, so the text is
+ * uncovered from its own baseline instead of fading up. `scrub` binds each
+ * word's opacity to the block's view() timeline — words light up as you read
+ * down the page — and is simply full where scroll timelines do not exist.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+import Reveal from './Reveal.astro';
+
+interface Props extends HTMLAttributes<'span'> {
+  /** The text to split. Use `\n` for explicit lines in `by="line"`. */
+  text: string;
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Split unit. */
+  by?: 'word' | 'char' | 'line';
+  /** Stagger between parts in ms. Defaults: word 40, char 25, line 90. */
+  step?: number;
+  /** Cap on the total stagger in ms; the step shrinks to fit long text. */
+  maxTotal?: number;
+  /** Per-part duration in ms. */
+  duration?: number;
+  /** Where parts travel from. */
+  from?: 'bottom' | 'top' | 'none';
+  /** Travel distance in px. */
+  distance?: number;
+  /** Blur in px to sharpen from. */
+  blur?: number;
+  /** Delay in ms before the first part. */
+  delay?: number;
+  /** Any CSS easing. */
+  easing?: string;
+  /** Play once and stay. */
+  once?: boolean;
+  /** Fraction visible to trigger. */
+  threshold?: number;
+  /** IntersectionObserver rootMargin. */
+  rootMargin?: string;
+  /** Each part rises from behind a clip of its own line instead of fading up. */
+  mask?: boolean;
+  /** Scroll-linked: words brighten from dim to full as the block moves through the viewport (animation-timeline: view()). Without scroll timelines every word is full. */
+  scrub?: boolean;
+  /** Resting opacity of an unread word in scrub mode, 0–1. */
+  dim?: number;
+}
+
+const {
+  text,
+  as = 'span',
+  by = 'word',
+  step,
+  maxTotal = 600,
+  duration = 500,
+  from = 'bottom',
+  distance = 12,
+  blur,
+  delay,
+  easing,
+  once,
+  threshold,
+  rootMargin,
+  mask = false,
+  scrub = false,
+  dim = 0.25,
+  class: className,
+  style,
+  ...rest
+} = Astro.props;
+
+// a character is a grapheme, not a code point: an emoji with a skin tone or a letter with a combining accent is one part
+const parts: string[] = by === 'char' ? Array.from(new Intl.Segmenter().segment(text), (g) => g.segment) : by === 'line' ? text.split('\n') : text.split(/(\s+)/).filter(Boolean);
+const animated = parts.filter((p) => !/^\s+$/.test(p)).length;
+const defaultStep = by === 'char' ? 25 : by === 'line' ? 90 : 40;
+// Cap the total: forty words at 40 ms is 1.6 s, which is a wait, not an entrance.
+const interval = Math.max(1, Math.min(step ?? defaultStep, animated > 1 ? maxTotal / (animated - 1) : maxTotal));
+// scrub: each word owns a slice of the block's cover range, 20% → 60%, with a little overlap
+const scrubVars = scrub ? `--ma-split-n:${animated};--ma-split-k:${(40 / Math.max(animated, 1)).toFixed(3)}%;--ma-split-dim:${dim}` : '';
+const inline = [scrubVars, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+let index = 0;
+// dir="auto" for words and characters: the parts are inline-blocks, which bidi orders by the page's direction, so Latin
+// text on a right-to-left page came out back to front. Lines are blocks of plain text and keep the page's direction.
+---
+
+<Reveal
+  as={as}
+  stagger={scrub ? undefined : interval}
+  duration={duration}
+  from={mask || scrub ? 'none' : from}
+  distance={distance}
+  blur={mask || scrub ? undefined : blur}
+  delay={delay}
+  easing={easing}
+  once={once}
+  threshold={scrub ? 0 : threshold}
+  rootMargin={scrub ? '0px 0px 0px 0px' : rootMargin}
+  class={['ma-split', `ma-split--${by}`, mask && 'ma-split--mask', mask && from === 'top' && 'ma-split--top', scrub && 'ma-split--scrub', className].filter(Boolean).join(' ')}
+  dir={by === 'line' ? undefined : 'auto'}
+  style={inline || undefined}
+  {...rest}
+>
+  {parts.map((part) =>
+    /^\s+$/.test(part) ? (
+      ' '
+    ) : mask ? (
+      <span class="ma-split__mask">
+        <span class="ma-split__part" aria-hidden="true">{part}</span>
+      </span>
+    ) : (
+      <span class="ma-split__part" aria-hidden="true" style={scrub ? `--ma-split-i:${index++}` : undefined}>{part}</span>
+    ),
+  )}
+  <span class="ma-sr">{text}</span>
+</Reveal>
+
+<style is:global>
+  @layer components {
+    /* break-spaces, not pre: both keep a part's text exactly as written, but pre also forbade wrapping, so a word
+       wider than its line ran out of it whatever overflow-wrap the host set; now overflow-wrap: anywhere breaks it */
+    :where(.ma-split__part) {
+      display: inline-block;
+      white-space: break-spaces;
+    }
+    /* a line is the author's line, not the screen's: one longer than the column wraps inside its own block instead of
+       running out of it (white-space: pre kept a two-word line from ever breaking on a phone) */
+    :where(.ma-split--line > .ma-split__part),
+    :where(.ma-split--line > .ma-split__mask),
+    :where(.ma-split--line > .ma-split__mask > .ma-split__part) {
+      display: block;
+      white-space: pre-wrap;
+    }
+    /* mask: the wrapper is Reveal's staggered child (it only fades, from="none"); the part rises inside its clip */
+    :where(.ma-split__mask) {
+      display: inline-block;
+      clip-path: inset(0 0 0 0);
+      white-space: break-spaces;
+    }
+    /* the rise keeps the timing of the wrapper's fade: Reveal's delay on the root and its index on the wrapper */
+    :where(.ma-split--mask .ma-split__part) {
+      translate: 0 0;
+      transition: translate var(--ma-r-dur, var(--ma-duration)) var(--ma-r-ease, var(--ma-ease)) calc(var(--ma-r-delay, 0ms) + var(--ma-r-i, 0) * var(--ma-r-stagger, var(--ma-stagger)));
+    }
+    :where([data-ma-js] .ma-split--mask:not(.ma-in) .ma-split__part) {
+      translate: 0 110%;
+    }
+    :where([data-ma-js] .ma-split--top:not(.ma-in) .ma-split__part) {
+      translate: 0 -110%;
+    }
+    :where(.ma-split--mask[data-leaving] .ma-split__part) {
+      transition-duration: var(--ma-duration-fast);
+      transition-delay: 0ms;
+    }
+    /* scrub: every word owns a slice of the block's own view timeline; nothing here runs where view() does not exist */
+    @supports (animation-timeline: view()) {
+      :where(.ma-split--scrub) {
+        view-timeline-name: --ma-split;
+      }
+      :where(.ma-split--scrub .ma-split__part) {
+        animation: ma-split-lit linear both;
+      }
+      /* separate rule on purpose — lightningcss would fold animation-timeline into the shorthand, which browsers reject */
+      :where(.ma-split--scrub) :where(.ma-split__part) {
+        animation-timeline: --ma-split;
+        animation-range: cover calc(20% + var(--ma-split-i, 0) * var(--ma-split-k, 10%)) cover calc(28% + (var(--ma-split-i, 0) + 1) * var(--ma-split-k, 10%));
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      /* Reveal already drops its travel; the masked parts drop theirs and the scrub reads full. */
+      :where([data-ma-js] .ma-split--mask:not(.ma-in) .ma-split__part) {
+        translate: 0 0;
+      }
+      :where(.ma-split--mask .ma-split__part) {
+        transition-duration: var(--ma-duration-fast);
+        transition-delay: 0ms;
+      }
+      :where(.ma-split--scrub .ma-split__part) {
+        animation: none;
+      }
+    }
+    /* Print: Reveal shows the parts; the masked ones also come out from under their clip, and the scrub reads full. A
+       masked line printed before it scrolled into view was blank. */
+    @media print {
+      :where(.ma-split--mask .ma-split__part) {
+        translate: none;
+        transition: none;
+      }
+      :where(.ma-split--scrub .ma-split__part) {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-split-lit {
+    from {
+      opacity: var(--ma-split-dim, 0.25);
+    }
+    to {
+      opacity: 1;
+    }
+  }
+</style>

package/src/components/SplitText.meta.ts

@@ -0,0 +1,50 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'SplitText',
+  slug: 'split-text',
+  title: 'Split Text',
+  description:
+    'Splits a string into words, characters or lines on the server and reveals them with a capped stagger when they scroll into view. One string to screen readers, zero script of its own.',
+  summary: 'Split text animation: words, characters or lines split on the server and revealed with a stagger on scroll.',
+  category: 'text',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'widely', needs: [], fallback: 'scrub uses animation-timeline: view() (Chrome 115, Safari 26); elsewhere every word is full' },
+  readout: '<SplitText step={45}>',
+  usage: `<SplitText as="h1" text="Split on the server, revealed on scroll." />\n<SplitText by="char" text="letter by letter" step={25} />\n<SplitText as="h2" text="Rises from behind its own line." mask />\n<SplitText as="p" text="Words light up as you read down the page…" scrub />`,
+  props: [
+    { name: 'text', type: 'string', description: 'The text to split. Use \\n for explicit lines with by="line".' },
+    { name: 'as', type: 'HTMLTag', default: "'span'", description: 'Element to render.' },
+    { name: 'by', type: "'word' | 'char' | 'line'", default: "'word'", description: 'Split unit.' },
+    { name: 'step', type: 'number', description: 'Stagger between parts in ms. Defaults: word 40, char 25, line 90.' },
+    { name: 'maxTotal', type: 'number', default: '600', description: 'Cap on the total stagger in ms; the step shrinks to fit long text.' },
+    { name: 'duration', type: 'number', default: '500', description: 'Per-part duration in ms.' },
+    { name: 'from', type: "'bottom' | 'top' | 'none'", default: "'bottom'", description: 'Where parts travel from.' },
+    { name: 'distance', type: 'number', default: '12', description: 'Travel distance in px.' },
+    { name: 'blur', type: 'number', description: 'Blur in px to sharpen from.' },
+    { name: 'delay', type: 'number', default: '0', description: 'Delay before the first part, ms.' },
+    { name: 'easing', type: 'string', default: 'preset curve', description: 'Any CSS easing for each part. Unset, the preset\'s sampled spring.' },
+    { name: 'once', type: 'boolean', default: 'true', description: 'Play once and stay.' },
+    { name: 'threshold', type: 'number', default: '0.2', description: 'Fraction visible to trigger.' },
+    { name: 'rootMargin', type: 'string', default: "'0px 0px -10% 0px'", description: 'IntersectionObserver rootMargin, passed to Reveal; the default waits until the text is 10% into the viewport. scrub ignores it.' },
+    { name: 'mask', type: 'boolean', default: 'false', description: 'Each part is uncovered as it rises from behind a clip of its own line. from="top" drops it in instead.' },
+    { name: 'scrub', type: 'boolean', default: 'false', description: 'Scroll-linked: words brighten from dim to full, in order, as the block moves through the viewport, on its own view() timeline. Where scroll timelines do not exist every word is full.' },
+    { name: 'dim', type: 'number', default: '0.25', description: 'Resting opacity of an unread word in scrub mode.' },
+  ],
+  reducedMotion: 'Inherits Reveal: fast opacity fade, no travel, no stagger.',
+  clientRouter: 'Inherits Reveal: rebinds through the shared runtime after every navigation.',
+  craft: [
+    'Split on the server so the HTML already contains every word; nothing is measured or re-flowed on the client.',
+    'by="char" splits graphemes (Intl.Segmenter): an emoji with a skin tone or a letter with a combining accent is one part. Words and characters are inline-blocks, which bidi orders by the direction around them, so the element takes dir="auto" and Latin text on a right-to-left page still reads left to right.',
+    'Stagger 40 ms per word, 25 per character, capped at 600 ms total: long text shrinks the step rather than lengthening the wait.',
+    'The text once, in a visually hidden span (.ma-sr), and aria-hidden parts: one string for assistive tech, whatever element it renders as. Not aria-label on the wrapper: a span, div or p may not be named that way (ARIA 1.2), and screen readers skip it there.',
+    'Composes Reveal instead of re-implementing the observer; costs nothing on a page that already has one.',
+    'mask clips each part to its own line box (clip-path on an inline-block, which keeps the baseline where overflow would move it) and translates the part by 110% inside it: the word is uncovered from the baseline, the way type is set.',
+    'scrub gives every word a slice of the block\'s cover range (20% to 60%, word n from 20% + n·k) on one named view timeline, so a paragraph reads itself in as you scroll and rewinds when you scroll back. No IntersectionObserver fallback on purpose: full words are the honest state where the timeline is missing.',
+  ],
+  related: ['reveal', 'typewriter', 'rotating-text'],
+  intents: ['split text animation', 'animate words on scroll', 'staggered text reveal', 'character reveal', 'text animation astro'],
+  replaces: ['SplitText (React Bits)', 'BlurText (React Bits)', 'TextReveal (Magic UI)', 'GSAP SplitText for entrances'],
+  fixture: { props: { text: 'Fixture content for SplitText' }, expect: 'ma-sr">Fixture content for SplitText</span>' },
+} satisfies ComponentMeta;

package/src/components/Spotlight.astro

@@ -0,0 +1,92 @@
+---
+/**
+ * Spotlight — a soft radial light follows the cursor over a surface.
+ *
+ * One pointermove listener writes the cursor position into two custom
+ * properties; the light is a pseudo-element gradient positioned by them and
+ * faded in by :hover. Nothing is measured on move except the box, and the
+ * listener is bound through the runtime so it survives navigation.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Radius of the light in px. */
+  radius?: number;
+  /** Light colour. */
+  color?: string;
+  /** Strength, 0–1. */
+  opacity?: number;
+  /** Where the light lives: the surface, or only the card's edge (a ring the same width as `border`). */
+  target?: 'surface' | 'border';
+  /** Ring width in px for target="border". */
+  border?: number;
+}
+
+const { as: Tag = 'div', radius = 240, color = 'var(--ma-glow)', opacity = 1, target = 'surface', border = 1, class: className, style, ...rest } = Astro.props;
+const inline = [`--ma-spot-r:${radius}px`, `--ma-spot-c:${color}`, `--ma-spot-o:${opacity}`, target === 'border' && `--ma-spot-w:${border}px`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-spot', className]} data-ma-spot data-target={target === 'border' ? 'border' : undefined} style={inline} {...rest}>
+  <slot />
+</Tag>
+
+<style is:global>
+  @layer components {
+    :where(.ma-spot) {
+      position: relative;
+      overflow: hidden;
+    }
+    :where(.ma-spot)::before {
+      content: '';
+      position: absolute;
+      inset: 0;
+      pointer-events: none;
+      background: radial-gradient(var(--ma-spot-r, 240px) circle at var(--ma-spot-x, 50%) var(--ma-spot-y, 50%), var(--ma-spot-c, var(--ma-glow)), transparent 70%);
+      opacity: 0;
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    /* border: the same gradient, kept to a ring by two masks composited with exclude (BorderBeam's ring), over the card's own border */
+    :where(.ma-spot[data-target='border'])::before {
+      inset: calc(-1 * var(--ma-spot-w, 1px));
+      padding: var(--ma-spot-w, 1px);
+      border-radius: inherit;
+      -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+      -webkit-mask-composite: xor;
+      mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+      mask-composite: exclude;
+    }
+    :where(.ma-spot[data-target='border']) {
+      overflow: visible;
+    }
+    @media (hover: hover) {
+      :where(.ma-spot:hover)::before {
+        opacity: var(--ma-spot-o, 1);
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-spot)::before {
+        transition: none;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+
+  onMount<HTMLElement>('[data-ma-spot]', (el, { signal }) => {
+    el.addEventListener(
+      'pointermove',
+      (e) => {
+        // the rect is in screen pixels, the gradient in the element's own: under a scaled ancestor they differ (a pointer
+        // over the element means it has a size, so the ratio is defined)
+        const r = el.getBoundingClientRect();
+        el.style.setProperty('--ma-spot-x', `${((e.clientX - r.left) * el.offsetWidth) / r.width}px`);
+        el.style.setProperty('--ma-spot-y', `${((e.clientY - r.top) * el.offsetHeight) / r.height}px`);
+      },
+      { signal, passive: true },
+    );
+  });
+</script>

package/src/components/Spotlight.meta.ts

@@ -0,0 +1,34 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Spotlight',
+  slug: 'spotlight',
+  title: 'Spotlight',
+  description: 'A soft radial light follows the cursor over a card and fades in only while hovered. One pointermove listener writes two custom properties; the light itself is a CSS gradient. Bound through the shared runtime, so it survives navigation.',
+  summary: 'A spotlight card effect: a soft light follows the cursor over a card and fades in only on hover.',
+  category: 'pointer',
+  tier: 'B',
+  trigger: ['pointer', 'hover'],
+  support: { baseline: 'widely', needs: ['mask-composite'] },
+  readout: '<Spotlight radius={240}>',
+  usage: `<Spotlight class="rounded-2xl border p-8">\n  <h3>Hover me</h3>\n</Spotlight>\n<Spotlight target="border" color="var(--action)" radius={160} class="rounded-2xl border p-8">\n  <h3>The light stays on the edge</h3>\n</Spotlight>`,
+  props: [
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+    { name: 'radius', type: 'number', default: '240', description: 'Radius of the light in px.' },
+    { name: 'color', type: 'string', default: 'var(--ma-glow)', description: 'Light colour; the token is theme-aware.' },
+    { name: 'opacity', type: 'number', default: '1', description: 'Strength while hovered, 0–1.' },
+    { name: 'target', type: "'surface' | 'border'", default: "'surface'", description: 'Where the light lives: across the surface, or only on the card\'s edge as a ring that follows the cursor (Magic Card). The same two custom properties drive both; the ring is BorderBeam\'s two-mask trick, zero extra bytes.' },
+    { name: 'border', type: 'number', default: '1', description: 'Ring width in px for target="border"; match the card\'s border.' },
+  ],
+  reducedMotion: 'The light still follows the cursor (direct manipulation, not motion) but no longer fades in and out.',
+  clientRouter: 'Bound through the shared runtime: listeners are attached to every instance after each navigation and aborted before the swap.',
+  craft: [
+    'The gradient is positioned by custom properties, so the move handler sets two values and never touches layout.',
+    'Fade-in is gated on (hover: hover): on touch there is no cursor to follow, so the light stays off rather than sticking where a finger was.',
+    'passive listener; getBoundingClientRect is the only read, once per move.',
+  ],
+  related: ['tilt', 'cursor-grid', 'border-beam'],
+  intents: ['spotlight card', 'cursor light effect', 'hover glow follows mouse', 'radial gradient follows cursor', 'spotlight hover astro'],
+  replaces: ['SpotlightCard (React Bits)', 'MagicCard (Magic UI)', 'CardSpotlight (Aceternity)'],
+  fixture: { expect: 'class="ma-spot"' },
+} satisfies ComponentMeta;