@moonarc/core 0.1.0

package/src/components/Toast.astro

@@ -0,0 +1,184 @@
+---
+/**
+ * Toast — notifications that stack, push each other up, and expand on hover.
+ *
+ * One region per page. Anything on the page raises a toast by dispatching
+ * `ma:toast` on document (or calling toast() from @moonarc/core/toast).
+ * Enter is @starting-style, exit is a data attribute plus removal after the
+ * transition; the stack offset is one custom property per toast, read by
+ * CSS. The region is the live region; timers pause while it is hovered or
+ * focused, and while the tab is hidden.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Corner. */
+  position?: 'bottom-right' | 'bottom-left' | 'bottom-center' | 'top-right' | 'top-left' | 'top-center';
+  /** Default lifetime in ms. */
+  duration?: number;
+  /** Toasts visible at once; older ones collapse behind. */
+  visible?: number;
+}
+
+const { position = 'bottom-right', duration = 4000, visible = 3, class: className, ...rest } = Astro.props;
+const [side, align] = position.split('-') as ['top' | 'bottom', 'left' | 'right' | 'center'];
+---
+
+<div class:list={['ma-toaster', className]} data-ma-toaster data-side={side} data-align={align} data-duration={duration} data-visible={visible} role="region" aria-label="Notifications" aria-live="polite" {...rest}>
+  <slot />
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-toaster) {
+      position: fixed;
+      z-index: 60;
+      display: grid;
+      gap: 0.5rem;
+      width: min(22rem, calc(100vw - 2rem));
+      margin: 1rem;
+      pointer-events: none;
+    }
+    :where(.ma-toaster[data-side='bottom']) {
+      bottom: 0;
+      align-content: end;
+    }
+    :where(.ma-toaster[data-side='top']) {
+      top: 0;
+      align-content: start;
+    }
+    :where(.ma-toaster[data-align='right']) {
+      right: 0;
+    }
+    :where(.ma-toaster[data-align='left']) {
+      left: 0;
+    }
+    :where(.ma-toaster[data-align='center']) {
+      left: 50%;
+      translate: -50% 0;
+    }
+    :where(.ma-toast) {
+      grid-area: 1 / 1;
+      pointer-events: auto;
+      border: 1px solid var(--ma-edge);
+      border-radius: 0.75rem;
+      padding: 0.75rem 1rem;
+      background: var(--ma-panel);
+      color: inherit;
+      box-shadow: 0 12px 32px -16px rgb(0 0 0 / 0.35);
+      font-size: 0.875rem;
+      line-height: 1.4;
+      /* --ma-i: 0 for the newest, counting back; written by the script */
+      transform-origin: 50% 100%;
+      translate: 0 calc(var(--ma-i, 0) * -0.75rem);
+      scale: calc(1 - var(--ma-i, 0) * 0.05);
+      opacity: calc(1 - var(--ma-i, 0) * 0.15);
+      transition:
+        translate var(--ma-duration) var(--ma-ease),
+        scale var(--ma-duration) var(--ma-ease),
+        opacity var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-toaster[data-side='top'] .ma-toast) {
+      transform-origin: 50% 0;
+      translate: 0 calc(var(--ma-i, 0) * 0.75rem);
+    }
+    :where(.ma-toast:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+    }
+    :where(.ma-toast[data-hidden]) {
+      opacity: 0;
+      pointer-events: none;
+    }
+    /* hovered: the stack opens into a list */
+    :where(.ma-toaster:hover .ma-toast),
+    :where(.ma-toaster:focus-within .ma-toast) {
+      grid-area: auto;
+      translate: 0 0;
+      scale: 1;
+      opacity: 1;
+    }
+    @starting-style {
+      :where(.ma-toast) {
+        translate: 0 var(--ma-travel-enter, 24px);
+        opacity: 0;
+      }
+    }
+    :where(.ma-toaster[data-side='top'] .ma-toast[data-leaving]),
+    :where(.ma-toast[data-leaving]) {
+      opacity: 0;
+      scale: 0.96;
+      transition-duration: var(--ma-duration-fast);
+      transition-timing-function: var(--ma-ease-in);
+    }
+    :where(.ma-toast__title) {
+      font-weight: 600;
+    }
+    :where(.ma-toast__desc) {
+      opacity: 0.7;
+      margin-top: 0.125rem;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      /* a fade in place: only opacity transitions, so the entrance never slides and the stack's offsets change at once */
+      :where(.ma-toast) {
+        transition: opacity var(--ma-duration-fast) linear;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+
+  type Detail = { title: string; description?: string; duration?: number };
+
+  onMount<HTMLElement>('[data-ma-toaster]', (region, { signal }) => {
+    const life = Number(region.dataset.duration ?? 4000);
+    const visible = Number(region.dataset.visible ?? 3);
+    const fast = 200;
+    // the clock stops while a toast is being read (the pointer over the region, the focus in it) and while the tab is hidden
+    const held = () => document.hidden || region.matches(':hover, :focus-within');
+
+    const restack = () => {
+      const items = [...region.querySelectorAll<HTMLElement>('.ma-toast:not([data-leaving])')].reverse();
+      items.forEach((t, i) => {
+        t.style.setProperty('--ma-i', String(i));
+        if (i >= visible) t.dataset.hidden = '';
+        else delete t.dataset.hidden;
+      });
+    };
+    const dismiss = (t: HTMLElement) => {
+      t.dataset.leaving = '';
+      restack();
+      setTimeout(() => t.remove(), fast);
+    };
+    const show = ({ title, description, duration }: Detail) => {
+      const t = document.createElement('div');
+      t.className = 'ma-toast';
+      // no role="status" of its own: a live region inserted with its text already in it is often not read, so the region,
+      // live since the page loaded, is the one announcing. Tab reaches the toast, and the focus holds it like the pointer.
+      t.tabIndex = 0;
+      t.innerHTML = `<div class="ma-toast__title"></div>${description ? '<div class="ma-toast__desc"></div>' : ''}`;
+      t.querySelector('.ma-toast__title')!.textContent = title;
+      if (description) t.querySelector('.ma-toast__desc')!.textContent = description;
+      region.append(t);
+      restack();
+      let left = duration ?? life;
+      let last = performance.now();
+      const tick = () => {
+        if (!t.isConnected) return;
+        const now = performance.now();
+        // one tick counts 250 ms at most: a longer gap is time the page did not run (timers stopped in a hidden tab, as
+        // WebKit on iOS does, or throttled to one a minute), and counting it would drop the toast the moment you are back
+        if (!held()) left -= Math.min(now - last, 250);
+        last = now;
+        if (left <= 0) dismiss(t);
+        else setTimeout(tick, 100);
+      };
+      setTimeout(tick, 100);
+      t.addEventListener('click', () => dismiss(t), { signal });
+    };
+
+    document.addEventListener('ma:toast', ((e: CustomEvent<Detail>) => show(e.detail)) as EventListener, { signal });
+  });
+</script>

package/src/components/Toast.meta.ts

@@ -0,0 +1,33 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Toast',
+  slug: 'toast',
+  title: 'Toast',
+  description: 'Notifications that slide in, stack behind each other, push up as new ones arrive, and expand into a list on hover. Raise one from anywhere with toast() or a DOM event; timers pause while the stack is hovered or focused and while the tab is hidden, and the region is a polite live region. The stack geometry is CSS reading one custom property per toast.',
+  summary: 'Toast notifications that slide in, stack, and expand into a list on hover, raised from anywhere with toast().',
+  category: 'ui',
+  tier: 'C',
+  trigger: ['click', 'hover'],
+  support: { baseline: 'newly', needs: ['starting-style'], fallback: 'toasts appear without the entrance' },
+  readout: "toast({ title: 'Saved' })",
+  usage: `---\n// once, in the layout\n---\n<Toast position="bottom-right" duration={4000} />\n\n<script>\n  import { toast } from '@moonarc/core/toast';\n  document.querySelector('#save')?.addEventListener('click', () => toast({ title: 'Saved', description: 'Just now.' }));\n</script>`,
+  props: [
+    { name: 'position', type: "'bottom-right' | 'bottom-left' | 'bottom-center' | 'top-right' | 'top-left' | 'top-center'", default: "'bottom-right'", description: 'Corner.' },
+    { name: 'duration', type: 'number', default: '4000', description: 'Default lifetime in ms; a toast can override it.' },
+    { name: 'visible', type: 'number', default: '3', description: 'Toasts visible at once; older ones collapse behind, and all show on hover.' },
+  ],
+  reducedMotion: 'Toasts fade in and out in place: only opacity transitions, so nothing slides, and the stack\'s offsets change at once.',
+  clientRouter: 'The region is bound through the shared runtime; toasts belong to the page they were raised on.',
+  craft: [
+    'Stacked toasts share one grid cell; each is offset and scaled by its index, so the stack is three CSS expressions and no measuring.',
+    'On hover the grid-area returns to auto and the stack becomes a list: the same elements, a different layout, one transition.',
+    'The clock stops while the pointer is over the region, while the focus is in it (Tab reaches every toast) and while the tab is hidden, so nothing disappears while you read it or while you are away.',
+    'The region is the live region (aria-live="polite"), on the page from the first paint; a toast adds its text to it. A new element with role="status" and its text already inside is often not announced at all.',
+    'Exit is a data attribute for 200 ms, then removal: the element leaves the DOM only after the eye has seen it go.',
+  ],
+  related: ['dialog', 'drawer', 'popover'],
+  intents: ['toast notification', 'sonner alternative', 'stacked toasts', 'notification stack', 'toast astro'],
+  replaces: ['Sonner', 'react-hot-toast', 'Toast (shadcn)'],
+  fixture: { slot: '<div class="ma-toast">Fixture content for Toast</div>', expect: 'Fixture content for Toast' },
+} satisfies ComponentMeta;

package/src/components/TracingBeam.astro

@@ -0,0 +1,113 @@
+---
+/**
+ * TracingBeam — a line beside an article fills as it is read, a dot at its
+ * head. Zero JS: one registered percentage animates on the article's own
+ * view() timeline over its `contain` range, and both the fill's height and
+ * the head's position read that one value. Without scroll timelines, and
+ * under reduced motion, the line is full and still. Correct for an article
+ * shorter than the viewport too: the range then runs from fully visible at
+ * the bottom to fully visible at the top.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  as?: HTMLTag;
+  /** Beam colour. */
+  color?: string;
+  /** Gutter the line lives in, any CSS length. */
+  offset?: string;
+  /** Line width in px. */
+  width?: number;
+  /** animation-range on the article's view timeline. */
+  range?: string;
+}
+
+const { as: Tag = 'div', color = 'var(--ma-ink)', offset = '2.5rem', width = 2, range = 'contain 0% contain 100%', class: className, style, ...rest } = Astro.props;
+const vars = [`--ma-trace-c:${color}`, `--ma-trace-gutter:${offset}`, `--ma-trace-w:${width}px`, `--ma-trace-range:${range}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-trace', className]} style={vars} {...rest}>
+  <div class="ma-trace__rail" aria-hidden="true">
+    <span class="ma-trace__line"></span>
+    <span class="ma-trace__fill"></span>
+    <span class="ma-trace__head"></span>
+  </div>
+  <div class="ma-trace__body"><slot /></div>
+</Tag>
+
+<style is:global>
+  @property --ma-trace-p {
+    syntax: '<percentage>';
+    inherits: true;
+    initial-value: 100%;
+  }
+
+  @layer components {
+    :where(.ma-trace) {
+      position: relative;
+      display: grid;
+      grid-template-columns: var(--ma-trace-gutter, 2.5rem) minmax(0, 1fr);
+    }
+    :where(.ma-trace__rail) {
+      position: relative;
+      grid-column: 1;
+      grid-row: 1;
+    }
+    :where(.ma-trace__body) {
+      grid-column: 2;
+      grid-row: 1;
+      min-width: 0;
+    }
+    :where(.ma-trace__line),
+    :where(.ma-trace__fill) {
+      position: absolute;
+      top: 0;
+      left: calc(50% - var(--ma-trace-w, 2px) / 2);
+      width: var(--ma-trace-w, 2px);
+      border-radius: 999px;
+    }
+    :where(.ma-trace__line) {
+      height: 100%;
+      background: var(--ma-edge);
+    }
+    :where(.ma-trace__fill) {
+      height: var(--ma-trace-p, 100%);
+      background: linear-gradient(to bottom, color-mix(in srgb, var(--ma-trace-c, var(--ma-ink)) 35%, transparent), var(--ma-trace-c, var(--ma-ink)));
+    }
+    :where(.ma-trace__head) {
+      position: absolute;
+      top: var(--ma-trace-p, 100%);
+      left: 50%;
+      width: calc(var(--ma-trace-w, 2px) * 5);
+      height: calc(var(--ma-trace-w, 2px) * 5);
+      translate: -50% -50%;
+      border-radius: 50%;
+      background: var(--ma-trace-c, var(--ma-ink));
+      box-shadow: 0 0 0 calc(var(--ma-trace-w, 2px) * 2) color-mix(in srgb, var(--ma-trace-c, var(--ma-ink)) 22%, transparent);
+    }
+    @supports (animation-timeline: view()) {
+      :where(.ma-trace) {
+        animation: ma-trace linear both;
+        animation-range: var(--ma-trace-range, contain 0% contain 100%);
+      }
+      /* the timeline in its own rule, so a minifier cannot fold it into the shorthand */
+      :where(html) :where(.ma-trace) {
+        animation-timeline: view();
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-trace) {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-trace {
+    from {
+      --ma-trace-p: 0%;
+    }
+    to {
+      --ma-trace-p: 100%;
+    }
+  }
+</style>

package/src/components/TracingBeam.meta.ts

@@ -0,0 +1,34 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'TracingBeam',
+  slug: 'tracing-beam',
+  title: 'Tracing Beam',
+  description: 'A line beside an article fills as it is read, with a dot at its head. One registered percentage animates on the article\'s own view() timeline, and both the fill\'s height and the head\'s position read that value. Without scroll timelines the line is full and still. Correct for an article shorter than the viewport too. Zero JavaScript.',
+  summary: 'A tracing beam beside an article: a line that fills as you read, with a dot at its head.',
+  category: 'scroll',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'limited', needs: ['scroll-timeline', 'property'], fallback: 'a full, static line with the dot at its end (Firefox)' },
+  readout: '<TracingBeam color="var(--action)">',
+  usage: `<TracingBeam color="var(--ma-ink)" offset="2.5rem">\n  <article class="prose">\n    <h1>…</h1>\n  </article>\n</TracingBeam>`,
+  props: [
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+    { name: 'color', type: 'string', default: 'var(--ma-ink)', description: 'Beam colour.' },
+    { name: 'offset', type: 'string', default: "'2.5rem'", description: 'Width of the gutter the line lives in.' },
+    { name: 'width', type: 'number', default: '2', description: 'Line width in px; the head is five times it.' },
+    { name: 'range', type: 'string', default: "'contain 0% contain 100%'", description: 'animation-range on the article\'s view timeline.' },
+  ],
+  reducedMotion: 'A full line, the dot at its end; nothing tracks the scroll.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'One animated value, two readers: the fill\'s height and the head\'s top are both var(--ma-trace-p), so they cannot fall out of step and the head never needs the rail\'s height.',
+    'The contain range means 0 % when the article\'s top reaches the top of the viewport and 100 % when its bottom reaches the bottom. The line is the part of the article you have scrolled past. For a short article the same range runs from fully visible at the bottom to fully visible at the top.',
+    'The fill is a gradient from 35 % to full colour, so the beam reads as light travelling down, not a progress bar.',
+    'The property inherits and its initial value is 100 %, so a browser without scroll timelines shows a finished line, never an empty one.',
+  ],
+  related: ['scroll-progress', 'reading-toc', 'reveal'],
+  intents: ['tracing beam', 'article progress line', 'scroll progress beside content', 'vertical reading progress', 'beam follows scroll'],
+  replaces: ['TracingBeam (Aceternity)', 'scroll progress line (Motion Primitives)'],
+  fixture: { slot: 'Fixture content for TracingBeam', expect: 'Fixture content for TracingBeam' },
+} satisfies ComponentMeta;

package/src/components/Typewriter.astro

@@ -0,0 +1,124 @@
+---
+/**
+ * Typewriter — per-character typing in any font, zero JS.
+ *
+ * Each character is a span whose `display` animates from none to inline on
+ * its own delay, so the caret at the end of the text sits after the last
+ * visible character without measuring anything. Browsers that cannot animate
+ * `display` still type through the `font-size` beside it (below); reduced
+ * motion shows the text immediately.
+ *
+ * The `font-size` beside `display` in the keyframes, and the `linear` timing,
+ * are what make the reveal arrive: a *stepped* keyframe that lands more than a
+ * second after the document starts never reaches layout in WebKit 26.6 — the
+ * character keeps a computed `display: inline` and is never given a box. An
+ * interpolated one does. Measured in all three engines by
+ * `tests/site/_probe-typewriter.mjs`; the record is docs/typewriter-webkit.md.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'span'> {
+  /** The text to type. */
+  text: string;
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Milliseconds per character. */
+  speed?: number;
+  /** Delay before the first character, ms. */
+  delay?: number;
+  /** Show the caret. */
+  cursor?: boolean;
+}
+
+const { text, as: Tag = 'span', speed = 55, delay = 0, cursor = true, class: className, style, ...rest } = Astro.props;
+
+// Words are inline-block so lines break between words, not inside one (only a
+// word longer than the line breaks); the trailing space belongs to the word so
+// it types as one keystroke. A character is a grapheme, not a code point: an
+// emoji with a skin tone or a letter with a combining accent types as one.
+const words: string[] = text.split(/(?<=\s)/);
+const graphemes = (s: string) => Array.from(new Intl.Segmenter().segment(s), (g) => g.segment);
+let index = 0;
+const total = graphemes(text).length;
+const vars = [`--ma-type-n:${total}`, `--ma-speed:${speed}ms`, delay ? `--ma-type-delay:${delay}ms` : '', typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+// dir="auto" below: the words are inline-blocks, which bidi orders by the page's direction, so Latin text on a
+// right-to-left page typed its words back to front. The element takes its direction from its own text instead.
+---
+
+<Tag
+  class:list={['ma-type', className]}
+  data-cursor={cursor ? '' : undefined}
+  dir="auto"
+  style={vars}
+  {...rest}
+>
+  {
+    words.map((word) => (
+      <span class="ma-type__word" aria-hidden="true">
+        {graphemes(word).map((ch) => (
+          <span class="ma-type__char" style={`--ma-i:${index++}`}>
+            {ch}
+          </span>
+        ))}
+      </span>
+    ))
+  }
+  <span class="ma-sr">{text}</span>
+</Tag>
+
+<style is:global>
+  @layer components {
+    /* a word is an inline-block as wide as its text, so it moves to the next line whole; only a word longer than the
+       line itself (a URL, a package path on a phone) breaks inside, where nowrap used to run it out of its box */
+    :where(.ma-type__word) {
+      display: inline-block;
+      overflow-wrap: anywhere;
+    }
+    :where(.ma-type__char) {
+      white-space: pre;
+      animation: ma-type-char 1ms linear both;
+      animation-delay: calc(var(--ma-type-delay, 0ms) + var(--ma-i) * var(--ma-speed, 55ms));
+    }
+    /* the caret rides on the last word, not after it: a word is an inline-block, and a caret beside one could wrap to a
+       line of its own on a narrow screen; inside the word's nowrap box it stays with the last character */
+    :where(.ma-type[data-cursor] > .ma-type__word:nth-last-child(2))::after {
+      content: '';
+      display: inline-block;
+      width: 0.08em;
+      min-width: 1.5px;
+      height: 1em;
+      margin-inline-start: 0.08em;
+      vertical-align: -0.12em;
+      background: currentColor;
+      /* solid while typing, blinking once idle */
+      animation: ma-type-blink 1s step-end infinite;
+      animation-delay: calc(var(--ma-type-delay, 0ms) + var(--ma-type-n) * var(--ma-speed, 55ms));
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-type__char) {
+        animation: none;
+      }
+      :where(.ma-type[data-cursor] > .ma-type__word:nth-last-child(2))::after {
+        animation: none;
+      }
+    }
+  }
+
+  /* font-size rides along so the reveal is interpolated, not stepped: a stepped one is
+     dropped after the document's first second in WebKit (see the component's comment) */
+  @keyframes ma-type-char {
+    from {
+      display: none;
+      font-size: 0;
+    }
+    to {
+      display: inline;
+      font-size: 1em;
+    }
+  }
+  @keyframes ma-type-blink {
+    50% {
+      opacity: 0;
+    }
+  }
+</style>

package/src/components/Typewriter.meta.ts

@@ -0,0 +1,39 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Typewriter',
+  slug: 'typewriter',
+  title: 'Typewriter',
+  description:
+    'Types a string one character at a time in any font, with a caret that stays solid while typing and blinks once idle. Pure CSS: every character is a span whose display animates on its own delay.',
+  summary: 'A typewriter text effect: characters appear one at a time, with a caret that blinks once typing stops.',
+  category: 'text',
+  tier: 'A',
+  trigger: ['load'],
+  support: { baseline: 'limited', needs: ['display-animation'], fallback: 'every character still types in turn, held at zero size by the font-size in the same keyframes until then (Firefox)' },
+  readout: '<Typewriter speed={45}>',
+  usage: `<Typewriter text="npx astro add moonarc" speed={55} />`,
+  props: [
+    { name: 'text', type: 'string', description: 'The text to type.' },
+    { name: 'as', type: 'HTMLTag', default: "'span'", description: 'Element to render.' },
+    { name: 'speed', type: 'number', default: '55', description: 'Milliseconds per character. 40–70 reads as typing; below 30 reads as printing.' },
+    { name: 'delay', type: 'number', default: '0', description: 'Delay before the first character, ms.' },
+    { name: 'cursor', type: 'boolean', default: 'true', description: 'Show the caret.' },
+  ],
+  reducedMotion: 'The full text is shown immediately and the caret does not blink.',
+  clientRouter: 'CSS-only; every navigation renders fresh elements whose animations start on their own.',
+  craft: [
+    'Per-character display animation means proportional fonts type correctly; width-based tricks only work in monospace.',
+    'The reveal is timed linear so the engine interpolates it. A stepped keyframe landing more than 1 000 ms into a page reaches computed style but never layout in WebKit 26.6, and the character keeps display: inline with no box.',
+    'Words are inline-block so a line breaks between words while typing; only a word longer than the line itself (a URL on a phone) breaks inside, where it would otherwise run out of its box.',
+    'The caret is solid during typing and blinks only once idle, like a real terminal.',
+    'A visually hidden span (.ma-sr) carries the whole string; the characters are aria-hidden.',
+    'Browsers that cannot animate display still type: the font-size in the same keyframes holds each character at zero size until its turn.',
+    'A character is a grapheme (Intl.Segmenter), so an emoji with a skin tone or a letter with a combining accent types as one keystroke. The element takes dir="auto", so Latin text on a right-to-left page still types left to right.',
+  ],
+  related: ['rotating-text', 'split-text'],
+  intents: ['typewriter effect', 'typing animation', 'type text one character at a time', 'terminal typing effect astro'],
+  replaces: ['TextType (React Bits)', 'astro-typewriter', 'typed.js for single strings'],
+  // an emoji with a skin tone is one keystroke (a grapheme): 32 characters to type, where code points made it 33
+  fixture: { props: { text: 'Fixture content for Typewriter 👍🏽' }, expect: 'style="--ma-type-n:32;--ma-speed:55ms"' },
+} satisfies ComponentMeta;

package/src/components/UnderlineHover.astro

@@ -0,0 +1,61 @@
+---
+/**
+ * UnderlineHover — the line enters from the left and leaves to the right.
+ * One background gradient: its size grows on hover while anchored left,
+ * and shrinks on leave while anchored right, so the exit runs the same
+ * direction as the entrance. Works on the element or from the link or
+ * button around it. Zero JS.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'span'> {
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Line thickness, any CSS length. */
+  thickness?: string;
+  /** Gap between the text and the line. */
+  offset?: string;
+  /** Line colour. */
+  color?: string;
+}
+
+const { as: Tag = 'span', thickness = '0.08em', offset = '0.12em', color = 'currentColor', class: className, style, ...rest } = Astro.props;
+const vars = [`--ma-underline-w:${thickness}`, `--ma-underline-offset:${offset}`, `--ma-underline-color:${color}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-underline', className]} style={vars} {...rest}><slot /></Tag>
+
+<style is:global>
+  @layer components {
+    :where(.ma-underline) {
+      text-decoration: none;
+      padding-bottom: var(--ma-underline-offset, 0.12em);
+      background-image: linear-gradient(var(--ma-underline-color, currentColor), var(--ma-underline-color, currentColor));
+      background-repeat: no-repeat;
+      background-size: 0% var(--ma-underline-w, 0.08em);
+      background-position: 100% 100%;
+      -webkit-box-decoration-break: clone;
+      box-decoration-break: clone;
+      transition: background-size var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    @media (hover: hover) {
+      :where(.ma-underline:hover),
+      :where(:is(a, button):hover .ma-underline) {
+        background-size: 100% var(--ma-underline-w, 0.08em);
+        background-position: 0% 100%;
+        transition-duration: var(--ma-duration);
+        transition-timing-function: var(--ma-ease);
+      }
+    }
+    :where(.ma-underline:focus-visible),
+    :where(:is(a, button):focus-visible .ma-underline) {
+      background-size: 100% var(--ma-underline-w, 0.08em);
+      background-position: 0% 100%;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-underline) {
+        transition: none;
+      }
+    }
+  }
+</style>

package/src/components/UnderlineHover.meta.ts

@@ -0,0 +1,34 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'UnderlineHover',
+  slug: 'underline-hover',
+  title: 'Underline Hover',
+  description:
+    'A link underline that enters from the left on hover and leaves to the right, so the exit continues the entrance instead of rewinding it. One background gradient, no pseudo-element, wraps across lines. Pure CSS; triggered by the link around it.',
+  summary: 'An animated link underline that enters from the left on hover and leaves to the right, across wrapped lines.',
+  category: 'text',
+  tier: 'A',
+  trigger: ['hover'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<UnderlineHover thickness="0.08em">',
+  usage: `<a href="/docs/"><UnderlineHover>Read the docs</UnderlineHover></a>\n<UnderlineHover as="a" href="/pro/" thickness="2px" color="var(--ma-ink)">Pro</UnderlineHover>`,
+  props: [
+    { name: 'as', type: 'HTMLTag', default: "'span'", description: 'Element to render. Use a or wrap it in one.' },
+    { name: 'thickness', type: 'string', default: "'0.08em'", description: 'Line thickness.' },
+    { name: 'offset', type: 'string', default: "'0.12em'", description: 'Gap between the text and the line.' },
+    { name: 'color', type: 'string', default: "'currentColor'", description: 'Line colour.' },
+  ],
+  reducedMotion: 'The line appears and disappears without sliding.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'Enter left, leave right: background-position flips instantly between the two states and only background-size transitions, so the line grows from the left and, on leave, shrinks toward the right: one direction of travel, like a pen that keeps going.',
+    'Entrance on the preset spring at the full duration, exit at the fast duration on ease-out: the acknowledgement lingers, the release gets out of the way.',
+    'A gradient on the element itself, not a pseudo-element, so box-decoration-break: clone paints the line on every wrapped line of a multi-line link.',
+    'Hover is read from the containing link or button, so the whole target counts; focus-visible draws the line for keyboard users.',
+  ],
+  related: ['text-roll', 'bubble-text', 'highlight-marker'],
+  intents: ['underline hover animation', 'link underline slide in', 'animated underline css', 'underline left to right hover', 'nav link underline effect'],
+  replaces: ['underline hover effects (Animata, uiverse)', 'Framer Motion layout underlines'],
+  fixture: { expect: 'Fixture content for UnderlineHover' },
+} satisfies ComponentMeta;