@moonarc/core 0.1.0

package/src/components/AvatarStack.astro

@@ -0,0 +1,205 @@
+---
+/**
+ * AvatarStack — overlapping avatars and a "+2 398", zero JS. A list of
+ * lazy images (or initials where there is no photo) overlapped through a
+ * negative margin, each with a ring in the surface colour so the overlap
+ * reads. Hover the list and the row spreads; hover one and it rises and
+ * its name appears above it — a CSS tooltip, no popover. Avatars are not
+ * focusable: six tab stops for decoration is a keyboard trap, and the
+ * names are in the alt text. With `href` an avatar becomes a link, is
+ * focusable, and shows its name on :focus-visible as well. Touch gets the
+ * still row. The count is formatted at build with Intl (`locale`).
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Person {
+  name: string;
+  /** Photo URL; without one, the initials are drawn. */
+  src?: string;
+  href?: string;
+}
+
+interface Props extends HTMLAttributes<'ul'> {
+  people: Person[];
+  /** Avatars shown; the rest go into the chip. */
+  max?: number;
+  /** Total count; the chip shows count − max. Defaults to people.length. */
+  count?: number;
+  /** Avatar size, any CSS length. */
+  size?: string;
+  /** Intl locale for the chip's number. */
+  locale?: string;
+  /** Screen-reader text of the chip, with `{n}` for the formatted number. */
+  moreLabel?: string;
+  /** Ring colour around each avatar; default the panel token. */
+  ring?: string;
+}
+
+const { people, max = 5, count, size = '2.5rem', locale = 'en', moreLabel = 'and {n} others', ring, class: className, style, ...rest } = Astro.props;
+const shown = people.slice(0, Math.max(1, max));
+const total = count ?? people.length;
+const more = Math.max(0, total - shown.length);
+const moreText = new Intl.NumberFormat(locale).format(more);
+const initials = (name: string) =>
+  name
+    .split(/\s+/)
+    .map((w) => w[0] ?? '')
+    .join('')
+    .slice(0, 2)
+    .toUpperCase();
+const vars = [`--ma-avatars-size:${size}`, ring && `--ma-avatars-ring:${ring}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<ul class:list={['ma-avatars', className]} style={vars} {...rest}>
+  {
+    shown.map((p) => (
+      <li class="ma-avatars__item">
+        {p.href ? (
+          <a href={p.href} class="ma-avatars__face">
+            {p.src ? <img src={p.src} alt={p.name} loading="lazy" decoding="async" /> : <span class="ma-avatars__initials" aria-hidden="true">{initials(p.name)}</span>}
+            {!p.src && <span class="ma-avatars__sr">{p.name}</span>}
+          </a>
+        ) : (
+          <span class="ma-avatars__face">
+            {p.src ? <img src={p.src} alt={p.name} loading="lazy" decoding="async" /> : <span class="ma-avatars__initials" aria-hidden="true">{initials(p.name)}</span>}
+            {!p.src && <span class="ma-avatars__sr">{p.name}</span>}
+          </span>
+        )}
+        <span class="ma-avatars__tip" aria-hidden="true">{p.name}</span>
+      </li>
+    ))
+  }
+  {more > 0 && (
+    <li class="ma-avatars__item ma-avatars__more">
+      <span class="ma-avatars__face" aria-hidden="true">+{moreText}</span>
+      <span class="ma-avatars__sr">{moreLabel.replace('{n}', moreText)}</span>
+    </li>
+  )}
+</ul>
+
+<style is:global>
+  @layer components {
+    :where(.ma-avatars) {
+      --ma-avatars-overlap: calc(var(--ma-avatars-size) * -0.26);
+      display: flex;
+      align-items: center;
+      margin: 0;
+      padding: 0;
+      padding-inline-start: calc(var(--ma-avatars-overlap) * -1);
+      list-style: none;
+      isolation: isolate;
+    }
+    :where(.ma-avatars__item) {
+      position: relative;
+      margin-inline-start: var(--ma-avatars-overlap);
+      transition:
+        margin var(--ma-duration) var(--ma-ease),
+        translate var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-avatars__face) {
+      display: grid;
+      place-items: center;
+      inline-size: var(--ma-avatars-size);
+      block-size: var(--ma-avatars-size);
+      border-radius: 50%;
+      box-shadow: 0 0 0 2px var(--ma-avatars-ring, var(--ma-panel));
+      background: color-mix(in srgb, var(--ma-ink) 10%, var(--ma-panel));
+      color: inherit;
+      overflow: clip;
+      text-decoration: none;
+      font-size: calc(var(--ma-avatars-size) * 0.3);
+      font-weight: 600;
+      letter-spacing: -0.02em;
+    }
+    :where(.ma-avatars__face > img) {
+      inline-size: 100%;
+      block-size: 100%;
+      object-fit: cover;
+    }
+    :where(.ma-avatars__more .ma-avatars__face) {
+      background: var(--ma-ink);
+      color: var(--ma-panel);
+      font-size: calc(var(--ma-avatars-size) * 0.3);
+      font-variant-numeric: tabular-nums;
+      /* a count wider than the circle grows into a pill instead of spilling out of it: +2,398. border-box, so a project
+         without a reset (content-box) still gets a circle for "+3" */
+      box-sizing: border-box;
+      inline-size: auto;
+      min-inline-size: var(--ma-avatars-size);
+      padding-inline: calc(var(--ma-avatars-size) * 0.2);
+      border-radius: calc(var(--ma-avatars-size) / 2);
+    }
+    /* centred on its avatar: left and -50% are the same in both directions, where inset-inline-start would be right: 50%
+       on a right-to-left page and push the name a whole width off */
+    :where(.ma-avatars__tip) {
+      position: absolute;
+      inset-block-end: calc(100% + 0.5em);
+      left: 50%;
+      padding: 0.3em 0.6em;
+      border-radius: 0.4em;
+      background: var(--ma-ink);
+      color: var(--ma-panel);
+      font-size: 0.75rem;
+      line-height: 1.2;
+      white-space: nowrap;
+      translate: -50% var(--ma-travel-hover);
+      opacity: 0;
+      pointer-events: none;
+      transition:
+        opacity var(--ma-duration-fast) var(--ma-ease-out),
+        translate var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    /* a pointer that hovers: the row spreads; the one under it rises and names itself. Touch never sees this. */
+    @media (hover: hover) and (pointer: fine) {
+      :where(.ma-avatars:hover .ma-avatars__item) {
+        margin-inline-start: calc(var(--ma-avatars-size) * 0.08);
+      }
+      :where(.ma-avatars:hover .ma-avatars__item:first-child) {
+        margin-inline-start: var(--ma-avatars-overlap);
+      }
+      :where(.ma-avatars__item:hover) {
+        z-index: 1;
+        translate: 0 calc(var(--ma-travel-hover) * -1);
+      }
+      :where(.ma-avatars__item:hover .ma-avatars__tip) {
+        opacity: 1;
+        translate: -50% 0;
+        transition-duration: var(--ma-duration);
+        transition-timing-function: var(--ma-ease);
+      }
+    }
+    /* a linked avatar reached from the keyboard names itself the same way */
+    :where(.ma-avatars__item:has(.ma-avatars__face:focus-visible)) {
+      z-index: 1;
+      translate: 0 calc(var(--ma-travel-hover) * -1);
+    }
+    :where(.ma-avatars__item:has(.ma-avatars__face:focus-visible) .ma-avatars__tip) {
+      opacity: 1;
+      translate: -50% 0;
+    }
+    :where(.ma-avatars__face:focus-visible) {
+      outline: 2px solid var(--ma-ink);
+      outline-offset: 2px;
+    }
+    :where(.ma-avatars__sr) {
+      position: absolute;
+      inline-size: 1px;
+      block-size: 1px;
+      margin: -1px;
+      padding: 0;
+      overflow: hidden;
+      clip-path: inset(50%);
+      white-space: nowrap;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-avatars__item),
+      :where(.ma-avatars__tip) {
+        transition: none;
+      }
+      :where(.ma-avatars__item:hover),
+      :where(.ma-avatars__item:has(.ma-avatars__face:focus-visible)) {
+        translate: 0 0;
+      }
+    }
+  }
+</style>

package/src/components/AvatarStack.meta.ts

@@ -0,0 +1,37 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'AvatarStack',
+  slug: 'avatar-stack',
+  title: 'Avatar Stack',
+  description: 'A row of overlapping avatars with a count chip such as "+2 398". Lazy images or initials, overlapped by a negative margin with a ring in the surface colour. Hover the row and it spreads; hover one and it rises and its name appears above it in a CSS tooltip. Avatars are not tab stops unless they carry an href; the names live in the alt text and the chip has its own screen-reader line. The count is formatted with Intl at build. Zero JavaScript.',
+  summary: 'Overlapping avatars with a count chip. The row spreads on hover, and each face shows its name in a tooltip.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['hover'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<AvatarStack people={people} max={5} count={2403}>',
+  usage: `---\nconst people = [\n  { name: 'Ari Santoso', src: '/avatars/ari.jpg' },\n  { name: 'Mei Lin', src: '/avatars/mei.jpg' },\n  { name: 'Noor Haddad' },\n  { name: 'Tomás Reyes', href: '/team/tomas/' },\n];\n---\n<AvatarStack people={people} max={4} count={2403} locale="en" />\n<p>Joined by <AvatarStack people={people} max={3} size="1.5rem" /> and the rest of the list.</p>`,
+  props: [
+    { name: 'people', type: '{ name, src?, href? }[]', description: 'Who to show. src is a photo (lazy, async); without one the initials are drawn. href makes the avatar a link and a tab stop.' },
+    { name: 'max', type: 'number', default: '5', description: 'Avatars shown; the rest are the chip.' },
+    { name: 'count', type: 'number', default: 'people.length', description: 'The total; the chip prints count − max.' },
+    { name: 'size', type: 'string', default: "'2.5rem'", description: 'Avatar size; the overlap, the ring and the initials scale with it.' },
+    { name: 'locale', type: 'string', default: "'en'", description: 'Intl.NumberFormat locale for the chip.' },
+    { name: 'moreLabel', type: 'string', default: "'and {n} others'", description: 'What a screen reader gets for the chip; {n} is the formatted number.' },
+    { name: 'ring', type: 'string', description: 'Ring colour; default the panel token. Pass the surface the stack sits on.' },
+  ],
+  reducedMotion: 'The spread happens without a transition and nothing rises; the tooltip still appears.',
+  clientRouter: 'Static; nothing to bind.',
+  craft: [
+    'The overlap is a negative inline margin and the ring is a box-shadow in the surface colour, so the stack reads as a stack on any background. Pass ring to match a card. On hover the margin goes positive and the row opens on the preset curve; the first item keeps its margin so the row does not jump sideways.',
+    'The name is a tooltip inside the item (absolute, above, centred with translate), rising from the hover travel token to zero. It is aria-hidden: the accessible name of each avatar is its alt, and a decorative row is not six tab stops.',
+    'With href an avatar is a real link and reaches the keyboard; :focus-visible then does what hover does, through :has() on the item, so the name shows for a keyboard reader as well.',
+    'The whole hover block is behind (hover: hover) and (pointer: fine): on touch the row is still and no tooltip appears, because a tooltip that opens on tap has no way to close.',
+    'The chip is formatted with Intl.NumberFormat at build time (locale), giving "2,398" or "2 398", and carries its own screen-reader sentence from moreLabel.',
+  ],
+  related: ['team-grid', 'tilt', 'link-preview'],
+  intents: ['avatar stack', 'avatar group', 'overlapping avatars', 'avatar circles hover', 'joined by avatars', 'social proof avatars'],
+  replaces: ['AnimatedTooltip (Aceternity)', 'AvatarCircles (Magic UI)', 'AvatarGroup (shadcn examples)'],
+  fixture: { props: { people: [{ name: 'Fixture content for AvatarStack' }, { name: 'Second Person' }, { name: 'Third Person' }], max: 2, count: 2403 }, expect: 'Fixture content for AvatarStack' },
+} satisfies ComponentMeta;

package/src/components/BarGrow.astro

@@ -0,0 +1,123 @@
+---
+/**
+ * BarGrow — bars grow from the baseline one after another when the chart
+ * scrolls into view. Server-rendered from the data: each bar is a flex
+ * child whose height is its value and whose scale transitions from 0 to 1
+ * on a per-index delay; hovering a bar shows its value. Composes Reveal;
+ * zero script of its own. The accessible name summarises the series.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+import Reveal from './Reveal.astro';
+
+interface Bar {
+  label?: string;
+  value: number;
+}
+
+interface Props extends HTMLAttributes<'div'> {
+  /** The series: numbers, or { label, value }. */
+  data: (number | Bar)[];
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Value that fills the full height. Default: the largest value. */
+  max?: number;
+  /** Chart height, any CSS length. */
+  height?: string;
+  /** Bar colour. */
+  color?: string;
+  /** Grow duration in ms. Unset: the preset's --ma-duration-slow. */
+  duration?: number;
+  /** Delay between bars in ms. Unset: the preset's --ma-stagger. */
+  stagger?: number;
+  /** Accessible name; the summary (min, max, last) is appended. */
+  label?: string;
+  /** Delay in ms before the first bar. */
+  delay?: number;
+  /** Play once and stay. */
+  once?: boolean;
+  /** Fraction visible to trigger. */
+  threshold?: number;
+}
+
+const { data, as = 'div', max, height = '8rem', color = 'var(--chart-1, currentColor)', duration, stagger, label, delay, once, threshold, class: className, style, ...rest } = Astro.props;
+const bars: Bar[] = data.map((d) => (typeof d === 'number' ? { value: d } : d));
+const values = bars.map((b) => b.value);
+const top = max ?? (Math.max(...values, 0) || 1);
+// an empty series is named as one: min and max of nothing are Infinity and -Infinity, and its last value is undefined
+const name = `${label ? `${label}: ` : ''}${bars.length ? `${bars.length} bars, min ${Math.min(...values)}, max ${Math.max(...values)}, last ${values[values.length - 1]}` : 'no data'}`;
+const hasLabels = bars.some((b) => b.label);
+// the bars' delay and index are the chart's own (--ma-bars-delay, --ma-bars-i): read as --ma-delay and --ma-i, the delay
+// was whatever a Reveal or any other element around the chart had set, and it is no longer the name Reveal writes
+const vars = [`--ma-bars-h:${height}`, `--ma-bars-color:${color}`, duration !== undefined && `--ma-bars-dur:${duration}ms`, stagger !== undefined && `--ma-bars-stagger:${stagger}ms`, delay !== undefined && `--ma-bars-delay:${delay}ms`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Reveal as={as} from="none" delay={delay} once={once} threshold={threshold} class={['ma-bars', className].filter(Boolean).join(' ')} role="img" aria-label={name} style={vars} {...rest}>
+  <span class="ma-bars__track" aria-hidden="true">
+    {bars.map((b, i) => <span class="ma-bars__bar" data-value={b.value} style={`--ma-bars-i:${i};--ma-bars-v:${Math.max(0, Math.min(1, b.value / top))}`}></span>)}
+  </span>
+  {hasLabels && <span class="ma-bars__labels" aria-hidden="true">{bars.map((b) => <span class="ma-bars__label">{b.label}</span>)}</span>}
+</Reveal>
+
+<style is:global>
+  @layer components {
+    :where(.ma-bars) {
+      display: block;
+    }
+    :where(.ma-bars__track) {
+      display: flex;
+      align-items: flex-end;
+      gap: 0.3em;
+      height: var(--ma-bars-h, 8rem);
+    }
+    :where(.ma-bars__bar) {
+      position: relative;
+      flex: 1;
+      min-height: 2px;
+      height: calc(var(--ma-bars-v, 0) * 100%);
+      border-radius: 0.2em 0.2em 0 0;
+      background: var(--ma-bars-color, currentColor);
+      transform-origin: 50% 100%;
+      scale: 1 1;
+      transition: scale var(--ma-bars-dur, var(--ma-duration-slow)) var(--ma-ease-out) calc(var(--ma-bars-delay, 0ms) + var(--ma-bars-i, 0) * var(--ma-bars-stagger, var(--ma-stagger)));
+    }
+    /* the value, on hover */
+    :where(.ma-bars__bar)::after {
+      content: attr(data-value);
+      position: absolute;
+      inset: auto 50% 100% auto;
+      translate: 50% 0;
+      margin-bottom: 0.35em;
+      font-size: 0.75em;
+      font-variant-numeric: tabular-nums;
+      white-space: nowrap;
+      opacity: 0;
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-bars__bar:hover)::after {
+      opacity: 1;
+    }
+    :where(.ma-bars__labels) {
+      display: flex;
+      gap: 0.3em;
+      margin-top: 0.5em;
+      font-size: 0.75em;
+      opacity: var(--ma-dim, 0.7);
+    }
+    :where(.ma-bars__label) {
+      flex: 1;
+      text-align: center;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    :where([data-ma-js] .ma-bars:not(.ma-in) .ma-bars__bar) {
+      scale: 1 0;
+      transition: none;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-bars__bar) {
+        transition: none;
+      }
+    }
+  }
+</style>

package/src/components/BarGrow.meta.ts

@@ -0,0 +1,42 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'BarGrow',
+  slug: 'bar-grow',
+  title: 'Bar Grow',
+  description:
+    'A bar chart whose bars grow from the baseline one after another when it scrolls into view; hovering a bar shows its value. Rendered on the server from the data: each bar is a flex child scaled from 0 to 1 on a per-index delay. Composes Reveal; no script of its own. The accessible name summarises the series.',
+  summary: 'A bar chart whose bars grow from the baseline one after another as it scrolls into view, with values on hover.',
+  category: 'data',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<BarGrow data={[…]}>',
+  usage: `<BarGrow data={[12, 18, 15, 22, 30, 28, 41]} label="Commits per day" class="text-action" />\n<BarGrow data={days.map((d) => ({ label: d.name, value: d.n }))} height="6rem" stagger={40} />`,
+  props: [
+    { name: 'data', type: '(number | { label?, value })[]', description: 'The series; objects add a label under the bar.' },
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+    { name: 'max', type: 'number', default: 'largest value', description: 'Value that fills the full height.' },
+    { name: 'height', type: 'string', default: "'8rem'", description: 'Chart height.' },
+    { name: 'color', type: 'string', default: "'var(--chart-1, currentColor)'", description: 'Bar colour: the first chart colour of the theme contract when a theme defines one, else the text colour.' },
+    { name: 'duration', type: 'number', default: 'preset (700)', description: 'Grow duration per bar in ms. Unset, the preset\'s --ma-duration-slow.' },
+    { name: 'stagger', type: 'number', default: 'preset (ui: 60)', description: 'Delay between bars in ms.' },
+    { name: 'label', type: 'string', description: 'Accessible name; "n bars, min, max, last" is appended.' },
+    { name: 'delay', type: 'number', default: '0', description: 'Delay in ms before the chart fades in and the first bar grows. A delay on a Reveal around the chart does not reach the bars: inside one, give the chart the same delay.' },
+    { 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 bars stand at their values at once.',
+  clientRouter: 'Inherits Reveal: rebinds after every navigation.',
+  craft: [
+    'scale on a bottom origin, not height: one compositor property, no layout per frame, and the rounded top stays rounded.',
+    'Left to right on the preset stagger: a chart is read in order, and a stagger that runs with the reading direction is the chart being drawn.',
+    'Ease-out at the slow duration: bars that shoot up and settle read as data arriving; bars that ease in read as loading.',
+    'The value is a data attribute painted by ::after on hover, with no tooltip element per bar and no script.',
+    'role="img" with a summary of the series in the name; the bars are aria-hidden decoration on top of that sentence.',
+  ],
+  related: ['sparkline', 'progress', 'count-up'],
+  intents: ['animated bar chart', 'bars grow on scroll', 'css bar chart animation', 'stagger bars chart', 'tiny bar chart astro'],
+  replaces: ['bar charts (Animata, Preline)', 'Chart.js for a seven-bar chart'],
+  fixture: { props: { data: [3, 5, 4, 8], label: 'Fixture content for BarGrow' }, expect: 'Fixture content for BarGrow' },
+} satisfies ComponentMeta;

package/src/components/BorderBeam.astro

@@ -0,0 +1,75 @@
+---
+/**
+ * BorderBeam — a light travels around the edge of a card, zero JS.
+ *
+ * The element carries a conic gradient whose start angle is a registered
+ * custom property; two masks composited with `exclude` keep only the border
+ * ring. The angle grows, so the beam runs clockwise and the head colour sits
+ * at the leading end. Animating the angle repaints the ring, nothing else.
+ * Absolutely positioned: give the parent `position: relative` and a radius.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Seconds per lap. */
+  duration?: number;
+  /** Length of the beam as a fraction of the perimeter, 0.05–0.5. */
+  length?: number;
+  /** Ring thickness in px. */
+  width?: number;
+  /** Beam colours: head and tail. */
+  colors?: [string, string];
+  /** Start angle in degrees. */
+  from?: number;
+}
+
+const { duration = 6, length = 0.2, width = 1.5, colors = ['oklch(78% 0.16 60)', 'oklch(70% 0.19 300)'], from = 0, class: className, style, ...rest } = Astro.props;
+const span = Math.max(0.05, Math.min(length, 0.5)) * 360;
+const vars = [`--ma-beam-duration:${duration}s`, `--ma-beam-span:${span}deg`, `--ma-beam-width:${width}px`, `--ma-beam-1:${colors[0]}`, `--ma-beam-2:${colors[1]}`, `--ma-beam-from:${from}deg`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div
+  class:list={['ma-beam', className]}
+  aria-hidden="true"
+  style={vars}
+  {...rest}
+>
+</div>
+
+<style is:global>
+  @property --ma-beam-angle {
+    syntax: '<angle>';
+    inherits: false;
+    initial-value: 0deg;
+  }
+
+  @layer components {
+    :where(.ma-beam) {
+      position: absolute;
+      inset: 0;
+      border-radius: inherit;
+      pointer-events: none;
+      padding: var(--ma-beam-width, 1.5px);
+      /* clockwise, so the head is the far end of the span: transparent at the start, the tail colour 60% of the length
+         behind the head, and a hard edge at the head. Without @property the angle falls back to 0 and the beam holds
+         still at `from` (the keyframe then flips it from 0 to a full turn, the same place) */
+      background: conic-gradient(from calc(var(--ma-beam-angle, 0deg) + var(--ma-beam-from, 0deg)), transparent 0deg, var(--ma-beam-2) calc(var(--ma-beam-span, 72deg) * 0.4), var(--ma-beam-1) var(--ma-beam-span, 72deg), transparent var(--ma-beam-span, 72deg));
+      -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;
+      animation: ma-beam var(--ma-beam-duration, 6s) linear infinite;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-beam) {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-beam {
+    to {
+      --ma-beam-angle: 360deg;
+    }
+  }
+</style>

package/src/components/BorderBeam.meta.ts

@@ -0,0 +1,33 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'BorderBeam',
+  slug: 'border-beam',
+  title: 'Border Beam',
+  description: 'A beam of light travels around the edge of a card. A conic gradient behind two composited masks leaves only the ring; the start angle animates as a registered custom property. Pure CSS, inherits the parent radius.',
+  summary: "A beam of light that travels around the edge of a card, following the card's border radius.",
+  category: 'background',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'newly', needs: ['property', 'mask-image'], fallback: 'the beam holds still at its start angle' },
+  readout: '<BorderBeam duration={6}>',
+  usage: `<div class="relative rounded-2xl border p-6">\n  <BorderBeam />\n  <h3>Pro</h3>\n</div>`,
+  props: [
+    { name: 'duration', type: 'number', default: '6', description: 'Seconds per lap. Under 3 reads as a spinner.' },
+    { name: 'length', type: 'number', default: '0.2', description: 'Beam length as a fraction of the perimeter, 0.05–0.5.' },
+    { name: 'width', type: 'number', default: '1.5', description: 'Ring thickness in px.' },
+    { name: 'colors', type: '[string, string]', default: 'amber, violet', description: 'Head and tail colours.' },
+    { name: 'from', type: 'number', default: '0', description: 'Start angle in degrees; offset several cards so they do not sync.' },
+  ],
+  reducedMotion: 'The beam holds still at its start angle (from).',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'The ring is a mask, not a border: the beam can fade along its length and the card underneath keeps its own border.',
+    'Linear timing, because it laps forever.',
+    'The beam runs clockwise and the head colour is its leading end, with a hard edge; the tail colour sits 60% of the length behind it and fades to nothing, like a comet.',
+  ],
+  related: ['spotlight', 'aurora', 'tilt'],
+  intents: ['border beam', 'animated border', 'glowing card border', 'light around card edge', 'moving border gradient'],
+  replaces: ['BorderBeam (Magic UI)', 'MovingBorder (Aceternity)', 'StarBorder (React Bits)'],
+  fixture: { expect: 'class="ma-beam"' },
+} satisfies ComponentMeta;