@moonarc/core 0.1.0

package/src/components/CommandPalette.astro

@@ -0,0 +1,363 @@
+---
+/**
+ * CommandPalette — ⌘K. A native modal <dialog> (the library's Dialog), an
+ * input, and a ranked list; ↑ ↓ move, ↵ follows the link (through the
+ * ClientRouter, if there is one), Escape closes, focus returns to what had
+ * it. Items come from the server (`items`), from a JSON URL fetched once on
+ * the first open (`source`), or both. Ranking is simple and stated: a
+ * prefix of the label beats a prefix of a word beats a substring beats a
+ * keyword, per query token. Results are re-rendered as new elements, so
+ * each arrives through @starting-style on the stagger token — no FLIP.
+ * Without JavaScript the trigger still opens the dialog (invoker) and the
+ * server-rendered items are plain links.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import Dialog from './Dialog.astro';
+
+export interface PaletteItem {
+  label: string;
+  href: string;
+  /** Group heading. */
+  group?: string;
+  /** Right-hand hint (a category, a shortcut, a cost). */
+  hint?: string;
+  /** Extra words the search matches. */
+  keywords?: string[];
+}
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Dialog id; unique per page. */
+  id: string;
+  items?: PaletteItem[];
+  /** URL of a JSON array of items, fetched once on the first open. */
+  source?: string;
+  /** Key for ⌘ / Ctrl + key. */
+  hotkey?: string;
+  placeholder?: string;
+  /** Trigger label. */
+  label?: string;
+  /** Results shown at most. */
+  max?: number;
+  /** Message when nothing matches. */
+  empty?: string;
+  /** The live count under the list; {n} is the number of results. */
+  countLabel?: string;
+  /** Add the inline click handler for browsers without invoker commands. */
+  polyfill?: boolean;
+}
+
+const { id, items = [], source, hotkey = 'k', placeholder = 'Search…', label = 'Search', max = 12, empty = 'Nothing found', countLabel = '{n} found', polyfill = false, class: className, ...rest } = Astro.props;
+const listId = `${id}-list`;
+const groups = new Map<string, PaletteItem[]>();
+for (const it of items) (groups.get(it.group ?? '') ?? groups.set(it.group ?? '', []).get(it.group ?? '')!).push(it);
+let n = 0;
+---
+
+<Dialog id={id} close={false} polyfill={polyfill} class="ma-cmdk__dialog" aria-label={label}>
+  <button slot="trigger" type="button" class="ma-cmdk__trigger" command="show-modal" commandfor={id} aria-label={label}>
+    <svg aria-hidden="true" viewBox="0 0 20 20" width="14" height="14"><circle cx="9" cy="9" r="6" fill="none" stroke="currentColor" stroke-width="1.5" /><path d="M14 14l4 4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg>
+    <span class="ma-cmdk__trigger-label">{label}</span>
+    <kbd class="ma-cmdk__kbd">⌘{hotkey.toUpperCase()}</kbd>
+  </button>
+  <div class:list={['ma-cmdk', className]} data-ma-cmdk data-source={source} data-hotkey={hotkey} data-max={max} data-count={countLabel} {...rest}>
+    <div class="ma-cmdk__field">
+      <svg aria-hidden="true" viewBox="0 0 20 20" width="16" height="16"><circle cx="9" cy="9" r="6" fill="none" stroke="currentColor" stroke-width="1.5" /><path d="M14 14l4 4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg>
+      <input type="search" class="ma-cmdk__input" placeholder={placeholder} aria-label={label} role="combobox" aria-expanded="true" aria-controls={listId} aria-autocomplete="list" autocomplete="off" spellcheck="false" />
+    </div>
+    <ul class="ma-cmdk__list" id={listId} role="listbox" aria-label={label}>
+      {
+        [...groups].map(([g, list]) => (
+          <>
+            {g && <li class="ma-cmdk__group" role="presentation">{g}</li>}
+            {list.map((it) => (
+              <li class="ma-cmdk__item" role="none" style={`--ma-cmdk-i:${Math.min(n, 8)}`} data-l={it.label} data-g={g || undefined} data-d={it.hint} data-k={(it.keywords ?? []).join(' ').toLowerCase() || undefined}>
+                <a href={it.href} tabindex="-1" role="option" id={`${listId}-${n++}`} aria-selected="false">
+                  <span class="ma-cmdk__label">{it.label}</span>
+                  {it.hint && <small class="ma-cmdk__hint">{it.hint}</small>}
+                </a>
+              </li>
+            ))}
+          </>
+        ))
+      }
+    </ul>
+    <p class="ma-cmdk__empty" hidden>{empty}</p>
+    <p class="ma-cmdk__foot"><span><kbd class="ma-cmdk__kbd">↑↓</kbd> move</span><span><kbd class="ma-cmdk__kbd">↵</kbd> open</span><span><kbd class="ma-cmdk__kbd">esc</kbd> close</span><span class="ma-cmdk__count" aria-live="polite"></span></p>
+  </div>
+</Dialog>
+
+<style is:global>
+  @layer components {
+    :where(.ma-cmdk__dialog) {
+      max-width: min(36rem, calc(100vw - 2rem));
+      margin-top: 10vh;
+      margin-bottom: auto;
+    }
+    :where(.ma-cmdk__dialog .ma-dialog__panel) {
+      padding: 0;
+    }
+    :where(.ma-cmdk__trigger) {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.5rem;
+      height: 2.25rem;
+      padding: 0 0.625rem 0 0.75rem;
+      border: 1px solid var(--ma-edge);
+      border-radius: 0.5rem;
+      background: var(--ma-panel);
+      color: inherit;
+      font: inherit;
+      font-size: 0.8125rem;
+      opacity: 0.8;
+      cursor: pointer;
+      transition: opacity var(--ma-duration-fast) var(--ma-ease-out), border-color var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-cmdk__trigger:hover) {
+      opacity: 1;
+      border-color: color-mix(in srgb, var(--ma-ink) 30%, transparent);
+    }
+    :where(.ma-cmdk__trigger:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+    }
+    :where(.ma-cmdk__kbd) {
+      display: inline-grid;
+      place-items: center;
+      min-width: 1.5em;
+      padding: 0.1em 0.35em;
+      border: 1px solid var(--ma-edge);
+      border-bottom-width: 2px;
+      border-radius: 0.3em;
+      font-family: ui-monospace, monospace;
+      font-size: 0.6875rem;
+      line-height: 1.4;
+      opacity: 0.8;
+    }
+    :where(.ma-cmdk__field) {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      padding: 0.875rem 1rem;
+      border-bottom: 1px solid var(--ma-edge);
+      opacity: 0.9;
+    }
+    /* the input's focus ring is the row it sits in: a 2 px line along the bottom (the input itself draws no outline) */
+    :where(.ma-cmdk__field:focus-within) {
+      box-shadow: inset 0 -2px 0 currentColor;
+    }
+    :where(.ma-cmdk__input) {
+      flex: 1;
+      min-width: 0;
+      border: 0;
+      background: none;
+      color: inherit;
+      font: inherit;
+      font-size: 1rem;
+      outline: none;
+    }
+    :where(.ma-cmdk__input::-webkit-search-cancel-button) {
+      display: none;
+    }
+    :where(.ma-cmdk__list) {
+      max-height: min(50vh, 24rem);
+      margin: 0;
+      padding: 0.375rem;
+      overflow: auto;
+      overscroll-behavior: contain;
+      list-style: none;
+    }
+    :where(.ma-cmdk__group) {
+      padding: 0.625rem 0.625rem 0.25rem;
+      font-family: ui-monospace, monospace;
+      font-size: 0.6875rem;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      opacity: var(--ma-dim, 0.7);
+    }
+    /* each result is a new element: it arrives through @starting-style, staggered by its index (capped at nine). The
+       index has the palette's own name: the shared --ma-i inherits, and a row would pass it to anything inside it */
+    :where(.ma-cmdk__item) {
+      opacity: 1;
+      translate: 0 0;
+      transition:
+        opacity var(--ma-duration) var(--ma-ease-out),
+        translate var(--ma-duration) var(--ma-ease);
+      transition-delay: calc(var(--ma-cmdk-i, 0) * var(--ma-stagger-tight));
+    }
+    @starting-style {
+      :where(.ma-cmdk__item) {
+        opacity: 0;
+        translate: 0 var(--ma-travel-hover, 4px);
+      }
+    }
+    :where(.ma-cmdk__item a) {
+      display: flex;
+      align-items: baseline;
+      justify-content: space-between;
+      gap: 1rem;
+      padding: 0.5rem 0.625rem;
+      border-radius: 0.5rem;
+      color: inherit;
+      text-decoration: none;
+      font-size: 0.9375rem;
+      transition: background-color var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-cmdk__item a[aria-selected='true']),
+    :where(.ma-cmdk__item a:hover) {
+      background: color-mix(in srgb, var(--ma-ink) 7%, transparent);
+    }
+    :where(.ma-cmdk__hint) {
+      flex: none;
+      font-family: ui-monospace, monospace;
+      font-size: 0.6875rem;
+      opacity: var(--ma-dim, 0.7);
+      white-space: nowrap;
+    }
+    :where(.ma-cmdk__empty) {
+      margin: 0;
+      padding: 1.5rem 1rem;
+      text-align: center;
+      font-size: 0.875rem;
+      opacity: var(--ma-dim, 0.7);
+    }
+    :where(.ma-cmdk__foot) {
+      display: flex;
+      gap: 1rem;
+      margin: 0;
+      padding: 0.625rem 1rem;
+      border-top: 1px solid var(--ma-edge);
+      font-family: ui-monospace, monospace;
+      font-size: 0.6875rem;
+      opacity: var(--ma-dim, 0.7);
+    }
+    :where(.ma-cmdk__count) {
+      margin-left: auto;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-cmdk__item) {
+        transition: none;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+
+  type Item = { l: string; h: string; g?: string; d?: string; k: string };
+
+  // the index outlives a binding: a palette kept through a swap (transition:persist) is bound again on the same node,
+  // and by then its list holds rendered results, which carry none of the item data
+  const indexes = new WeakMap<HTMLElement, { items: Item[]; loaded: boolean }>();
+
+  onMount<HTMLElement>('[data-ma-cmdk]', (root, { signal }) => {
+    const dialog = root.closest('dialog') as HTMLDialogElement;
+    const input = root.querySelector('input')!;
+    const list = root.querySelector('ul')!;
+    const empty = root.querySelector<HTMLElement>('.ma-cmdk__empty')!;
+    const count = root.querySelector<HTMLElement>('.ma-cmdk__count')!;
+    const max = Number(root.dataset.max) || 12;
+    const esc = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+    const key = root.dataset.hotkey!;
+    // the server-rendered options are the first index; `source` extends it once
+    const ix = indexes.get(root) ?? { items: [...list.querySelectorAll<HTMLElement>('.ma-cmdk__item')].map((o) => ({ l: o.dataset.l!, h: o.querySelector('a')!.getAttribute('href')!, g: o.dataset.g, d: o.dataset.d, k: o.dataset.k ?? '' })), loaded: !root.dataset.source };
+    indexes.set(root, ix);
+    let results: Item[] = [];
+    let active = 0;
+
+    // ↑ ↓ move aria-selected over the rows already there: rendered again, every row would enter again through @starting-style
+    const select = (n: number) => {
+      active = n;
+      const opts = list.querySelectorAll<HTMLElement>('[role="option"]');
+      opts.forEach((o, i) => o.setAttribute('aria-selected', String(i === n)));
+      const sel = opts[n];
+      input.setAttribute('aria-activedescendant', sel?.id ?? '');
+      // keep the selected row inside the list by moving the list's own scroll only: scrollIntoView() scrolls every ancestor,
+      // and a palette rendered off screen (a catalogue tile typing on a timer) would drag the whole page to itself
+      if (sel) {
+        const r = sel.getBoundingClientRect();
+        const l = list.getBoundingClientRect();
+        if (r.top < l.top) list.scrollTop += r.top - l.top;
+        else if (r.bottom > l.bottom) list.scrollTop += r.bottom - l.bottom;
+      }
+    };
+    const render = () => {
+      let g = '';
+      let i = 0;
+      list.innerHTML = results
+        .map((r) => {
+          const head = r.g && r.g !== g ? ((g = r.g), `<li class="ma-cmdk__group" role="presentation">${esc(g)}</li>`) : '';
+          const n = i++;
+          return `${head}<li class="ma-cmdk__item" role="none" style="--ma-cmdk-i:${Math.min(n, 8)}"><a href='${esc(r.h)}' tabindex="-1" role="option" id="${list.id}-${n}"><span class="ma-cmdk__label">${esc(r.l)}</span>${r.d ? `<small class="ma-cmdk__hint">${esc(r.d)}</small>` : ''}</a></li>`;
+        })
+        .join('');
+      empty.hidden = results.length > 0 || !input.value;
+      // the live count says what it counts: a bare "3" is read out as a number and nothing else
+      count.textContent = input.value ? root.dataset.count!.replace('{n}', String(results.length)) : '';
+      select(0);
+    };
+    // prefix of the label > prefix of a word > substring > keyword, per token; every token has to match
+    const score = (it: Item, tokens: string[]) => {
+      const t = it.l.toLowerCase();
+      let s = 0;
+      for (const q of tokens) {
+        const p = t.startsWith(q) ? 4 : t.split(' ').some((w) => w.startsWith(q)) ? 3 : t.includes(q) ? 2 : it.k.includes(q) ? 1 : 0;
+        if (!p) return 0;
+        s += p;
+      }
+      return s;
+    };
+    const search = () => {
+      const tokens = input.value.trim().toLowerCase().split(/\s+/).filter(Boolean);
+      results = ix.items
+        .map((it) => [it, tokens.length ? score(it, tokens) : 1] as const)
+        .filter((x) => x[1])
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, max)
+        .map((x) => x[0]);
+      render();
+    };
+    const open = async () => {
+      if (!dialog.open) dialog.showModal();
+      input.value = '';
+      input.focus();
+      if (!ix.loaded) {
+        ix.loaded = true;
+        try {
+          const more = (await (await fetch(root.dataset.source!, { signal })).json()) as { label: string; href: string; group?: string; hint?: string; keywords?: string[] }[];
+          // an entry without a label or an href (another index's shape) is left out, not ranked into a throw
+          ix.items = [...ix.items, ...more.filter((m) => m.label && m.href).map((m) => ({ l: m.label, h: m.href, g: m.group, d: m.hint, k: (m.keywords ?? []).join(' ').toLowerCase() }))];
+        } catch {
+          // offline, or the binding ended mid-fetch (a swap that keeps the palette): the server list stands, and the next
+          // open tries again, since the index outlives the binding
+          ix.loaded = false;
+        }
+      }
+      search();
+    };
+
+    // every trigger that points at this dialog: the invoker's default is cancelled so the input is focused and the list
+    // refreshed; its key hint says Ctrl where the platform is not Apple's
+    const ctrl = !/Mac|iP/.test(navigator.platform);
+    for (const t of document.querySelectorAll<HTMLElement>(`[commandfor="${dialog.id}"][command="show-modal"]`)) {
+      t.addEventListener('click', (e) => { e.preventDefault(); open(); }, { signal });
+      if (ctrl) t.querySelector('.ma-cmdk__kbd')?.replaceChildren(`Ctrl ${key.toUpperCase()}`);
+    }
+    document.addEventListener('keydown', (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === key) { e.preventDefault(); dialog.open ? dialog.close() : open(); }
+    }, { signal });
+    input.addEventListener('input', search, { signal });
+    input.addEventListener('keydown', (e) => {
+      const n = results.length;
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') { e.preventDefault(); if (n) select((active + (e.key === 'ArrowDown' ? 1 : n - 1)) % n); }
+      else if (e.key === 'Enter') { e.preventDefault(); list.querySelector<HTMLAnchorElement>('a[aria-selected="true"]')?.click(); }
+      // one Escape closes a modal palette: in a search field the first one would only clear the query (Chromium, Firefox)
+      else if (e.key === 'Escape' && dialog.matches(':modal')) { e.preventDefault(); dialog.close(); }
+    }, { signal });
+    // a click on a result follows the link; the dialog closes with the page (or now, on the same page)
+    list.addEventListener('click', (e) => { if ((e.target as Element).closest('a')) dialog.close(); }, { signal });
+    // Safari has no closedby, and the palette has no close button: there, a click on the backdrop (the dialog itself, the
+    // panel fills the rest) closes it, so a phone with no Escape key still has a way out
+    if ((dialog as { closedBy?: string }).closedBy == null) dialog.addEventListener('click', (e) => e.target === dialog && dialog.close(), { signal });
+  });
+</script>

package/src/components/CommandPalette.meta.ts

@@ -0,0 +1,40 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'CommandPalette',
+  slug: 'command-palette',
+  title: 'Command Palette',
+  description: 'A ⌘K command palette: a native modal dialog with an input and a ranked list of links. ↑ ↓ move, ↵ follows the link through the ClientRouter, Escape closes and focus returns to where it was; results are re-rendered and each arrives through @starting-style on the stagger token. Items come from the server, from a JSON URL fetched once on the first open, or both. Without JavaScript the invoker still opens the dialog and the server-rendered items are plain links.',
+  summary: 'A ⌘K command palette in a native dialog: type to filter, arrow keys to move, Enter to go, Escape to close.',
+  category: 'ui',
+  tier: 'C',
+  trigger: ['click'],
+  support: { baseline: 'newly', needs: ['dialog', 'command', 'starting-style'], fallback: 'without invoker commands the trigger is the script\'s (or polyfill\'s); without @starting-style results appear at once; without closedby (Safari) the script closes it on a tap on the backdrop' },
+  readout: '<CommandPalette hotkey="k">',
+  usage: `<CommandPalette\n  id="palette"\n  items={[\n    { label: 'Installation', href: '/docs/installation/', group: 'Docs', hint: '5 min' },\n    { label: 'Scroll Reveal', href: '/components/reveal/', group: 'Components', hint: 'scroll', keywords: ['aos', 'fade in'] },\n  ]}\n  source="/palette.json"\n/>\n\n<!-- any button on the page can open it -->\n<button type="button" command="show-modal" commandfor="palette">Search</button>`,
+  props: [
+    { name: 'id', type: 'string', description: 'Dialog id; every button with commandfor={id} opens it.' },
+    { name: 'items', type: '{ label: string; href: string; group?: string; hint?: string; keywords?: string[] }[]', default: '[]', description: 'Server-rendered items: the first index, and the list without JavaScript.' },
+    { name: 'source', type: 'string', description: 'URL of a JSON array in the same shape, fetched on the first open and merged (a fetch that failed is tried again on the next open); an entry without a label or an href is left out.' },
+    { name: 'hotkey', type: 'string', default: "'k'", description: '⌘ / Ctrl + this key toggles the palette. The trigger shows ⌘ on Apple platforms and Ctrl elsewhere.' },
+    { name: 'placeholder', type: 'string', default: "'Search…'", description: 'Input placeholder.' },
+    { name: 'label', type: 'string', default: "'Search'", description: 'Trigger label and the accessible name of the input and the list.' },
+    { name: 'max', type: 'number', default: '12', description: 'Results shown at most.' },
+    { name: 'empty', type: 'string', default: "'Nothing found'", description: 'Shown when a query matches nothing.' },
+    { name: 'countLabel', type: 'string', default: "'{n} found'", description: 'The result count under the list, a polite live region; {n} is the number.' },
+    { name: 'polyfill', type: 'boolean', default: 'false', description: 'Inline the invoker click handler (403 B raw) for browsers without command / commandfor.' },
+  ],
+  reducedMotion: 'Results appear without the stagger; the dialog itself cross-fades in 150 ms.',
+  clientRouter: 'Bound through the shared runtime; the document hotkey listener is aborted before the swap. ↵ clicks the link, so the router handles the navigation and the dialog closes with the page. A palette kept with transition:persist keeps its index (and the fetched source) across the rebind.',
+  craft: [
+    'A native modal dialog does the focus trap and the focus return; the script owns the search, the keyboard on the list and the fetch, and closes on the first Escape (a search field would spend it clearing the query) and on a tap on the backdrop, which Safari\'s dialog does not do without closedby.',
+    'The ranking is four levels and stated on the page: a prefix of the label, a prefix of a word, a substring, a keyword. It is applied per token, and every token is required. The order is predictable, which suits a list of a hundred links.',
+    'Results are new elements every time, so @starting-style gives each one an entrance delayed by its index on the tight stagger, capped at nine so a long list never waits. There is no FLIP and no measured position. ↑ ↓ only move aria-selected over the rows already there, so the selection moves and nothing enters again.',
+    'aria-activedescendant on the combobox input, options with ids, aria-selected on one: the screen reader follows the arrow keys without the focus leaving the input.',
+    'The trigger is a real invoker: without the script the dialog still opens and the server-rendered items are links. The script cancels the invoker\'s default only to focus the input and refresh the list.',
+  ],
+  related: ['dialog', 'file-tree', 'docs-shell'],
+  intents: ['command palette', 'cmd k search', 'keyboard search dialog', 'spotlight search astro', 'site search modal', 'command menu'],
+  replaces: ['Command (shadcn / cmdk)', 'CommandPalette (Motion Primitives)', 'kbar', 'Search modal (Tailwind Plus)'],
+  fixture: { props: { id: 'ma-fixture-cmdk', items: [{ label: 'Fixture content for CommandPalette', href: '/', group: 'Pages' }, { label: 'Two', href: '/two/' }] }, expect: 'Fixture content for CommandPalette' },
+} satisfies ComponentMeta;

package/src/components/Confetti.astro

@@ -0,0 +1,143 @@
+---
+/**
+ * Confetti — a burst of paper on load, on a click or on an `ma:confetti`
+ * event, then nothing: the canvas exists only while pieces are falling and is
+ * removed after the last one. The physics (gravity, drag, launch speed,
+ * spread, flutter) are custom properties this stylesheet declares on :root,
+ * one set per preset, so a snappy page bursts harder than a gentle one; the
+ * script reads them and never carries a constant of its own. Colours are the
+ * element's computed `color` and four border colours, so tokens go through
+ * CSS on .ma-confetti; `colors` takes literal ones only, because the canvas
+ * does not resolve var(). trigger="event" fires on `ma:confetti` dispatched on
+ * document (detail.target empty or this element), and on a
+ * `data-ma-confetti-fire` attribute already present when it binds, so the
+ * script asking for a burst may run before or after this one. `confetti()`
+ * from '@moonarc/core/confetti' is the same burst from your own handler.
+ * Nothing fires under reduced motion.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'span'> {
+  /**
+   * load: once, when the element is mounted (a persisted element does not burst again) · click: every click on `for`
+   * (or on the parent when `for` is not given) · event: every `ma:confetti` on document whose `detail.target` is empty
+   * or this element, plus once at bind when the element carries `data-ma-confetti-fire` (removed as it fires).
+   */
+  trigger?: 'load' | 'click' | 'event';
+  /** Selector of the element whose clicks fire (click) and whose centre the burst starts from (every trigger). */
+  for?: string;
+  /** Pieces per burst. */
+  count?: number;
+  /** Literal colours (hex, rgb(), oklch()); var() is not resolved by the canvas — for tokens use CSS on .ma-confetti (`color` and the four `border-*-color`). Default: those five. */
+  colors?: string[];
+  /** Launch point in viewport px; default the centre of `for` (or of the clicked parent), the viewport centre on load or event without `for`. */
+  origin?: { x: number; y: number };
+  /** Launch direction in degrees, 0 = up, 90 = right. */
+  angle?: number;
+  /** Launch cone in degrees; default the preset token. */
+  spread?: number;
+}
+
+const { trigger = 'click', for: target, count = 120, colors, origin, angle = 0, spread, class: className, ...rest } = Astro.props;
+---
+
+<span
+  class:list={['ma-confetti', className]}
+  data-ma-confetti
+  data-trigger={trigger}
+  data-for={target}
+  data-count={count}
+  data-colors={colors?.join('|')}
+  data-origin={origin ? `${origin.x},${origin.y}` : undefined}
+  data-angle={angle}
+  data-spread={spread}
+  hidden
+  {...rest}
+></span>
+
+<style is:global>
+  @layer components {
+    /* physics per preset: px per frame at 60 fps; the script reads these on :root */
+    :where(:root) {
+      --ma-confetti-gravity: 0.22;
+      --ma-confetti-drag: 0.985;
+      --ma-confetti-velocity: 14;
+      --ma-confetti-spread: 70;
+      --ma-confetti-flutter: 0.12;
+    }
+    :where([data-ma-preset='snap']) {
+      --ma-confetti-velocity: 18;
+      --ma-confetti-drag: 0.975;
+      --ma-confetti-spread: 50;
+    }
+    :where([data-ma-preset='lively']) {
+      --ma-confetti-velocity: 17;
+      --ma-confetti-spread: 90;
+      --ma-confetti-flutter: 0.18;
+    }
+    :where([data-ma-preset='gentle']),
+    :where([data-ma-preset='ambient']) {
+      --ma-confetti-velocity: 11;
+      --ma-confetti-gravity: 0.16;
+      --ma-confetti-drag: 0.99;
+    }
+    /* the default palette: five colours the script reads from this element's computed style; override them with CSS (var() included), not through `colors` */
+    :where(.ma-confetti) {
+      color: #f5a524;
+      border: 0 solid;
+      border-top-color: #e4572e;
+      border-right-color: #3a9a5b;
+      border-bottom-color: #4c7dff;
+      border-left-color: #c94ad3;
+    }
+    /* nothing fires under reduced motion (the script checks); stated here so the audit sees the branch */
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-confetti) {
+        display: none;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+  import { colors } from '../lib/canvas';
+  import { confetti } from '../lib/confetti';
+
+  onMount<HTMLElement>('[data-ma-confetti]', (el, { signal }) => {
+    const d = el.dataset;
+    // every trigger is armed whatever the motion setting: confetti() reads reduced motion at the moment of the burst and
+    // drops it, so a click after the reader turns motion back on bursts (bound only when motion was allowed, it never did)
+    const fire = (from?: Element | null) => {
+      const o = d.origin?.split(',').map(Number);
+      let origin = o ? { x: o[0]!, y: o[1]! } : undefined;
+      if (!origin && from) {
+        const r = from.getBoundingClientRect();
+        origin = { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+      }
+      confetti({ count: Number(d.count) || 120, colors: d.colors ? d.colors.split('|') : colors(el), origin, angle: Number(d.angle) || 0, spread: d.spread ? Number(d.spread) : undefined });
+    };
+    const fromFor = () => fire(d.for ? document.querySelector(d.for) : null);
+    // load is once per element: one kept across a swap by transition:persist is bound again after it, and must not burst again
+    if (d.trigger === 'load') {
+      if (!('maConfettiDone' in d)) fromFor();
+      d.maConfettiDone = '';
+      return;
+    }
+    if (d.trigger === 'event') {
+      // A request made before this script ran is the attribute, one made after is the event; a caller that does both in
+      // one task (set the attribute, dispatch) gets one burst whichever script runs first. Firing clears the attribute.
+      const go = () => {
+        delete d.maConfettiFire;
+        fromFor();
+      };
+      if ('maConfettiFire' in d) go();
+      document.addEventListener('ma:confetti', ((e: CustomEvent<{ target?: Element | null } | null>) => {
+        if (!e.detail?.target || e.detail.target === el) go();
+      }) as EventListener, { signal });
+      return;
+    }
+    const target = d.for ? document.querySelector(d.for) : el.parentElement;
+    target?.addEventListener('click', () => fire(target), { signal });
+  });
+</script>

package/src/components/Confetti.meta.ts

@@ -0,0 +1,40 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Confetti',
+  slug: 'confetti',
+  title: 'Confetti',
+  description: 'Fires a burst of paper confetti on load, on a click or on an ma:confetti event. One fixed canvas exists only while pieces are falling. Gravity, drag, launch speed and spread are custom properties declared per preset in the stylesheet: the script reads them and carries no constant. Also callable as confetti() from your own handler. Never fires under reduced motion.',
+  summary: 'A burst of paper confetti on load, on a click, or from your own code with confetti(), never under reduced motion.',
+  category: 'pointer',
+  tier: 'C',
+  trigger: ['load', 'click'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<Confetti trigger="click" for="#celebrate">',
+  usage: `<button id="celebrate" type="button">Celebrate</button>\n<Confetti trigger="click" for="#celebrate" />\n\n<!-- tokens are CSS on the element; the canvas cannot resolve var() in \`colors\` -->\n<Confetti trigger="click" for="#celebrate" style="color: var(--primary, #4c7dff); border-color: var(--chart-1, #e4572e) var(--chart-2, #3a9a5b) var(--chart-3, #f5a524) var(--chart-4, #c94ad3)" />\n\n<!-- from any script, without importing the lib; the attribute covers a script that runs before the component binds -->\n<Confetti trigger="event" id="party" />\n<script>\n  const party = document.getElementById('party');\n  party.setAttribute('data-ma-confetti-fire', '');\n  document.dispatchEvent(new CustomEvent('ma:confetti', { detail: { target: party } }));\n</script>\n\n<!-- or the function itself -->\n<script>\n  import { confetti } from '@moonarc/core/confetti';\n  form.addEventListener('submit', () => confetti({ count: 200 }));\n</script>`,
+  props: [
+    { name: 'trigger', type: "'load' | 'click' | 'event'", default: "'click'", description: 'load: once when mounted, once per element (one kept across a navigation by transition:persist does not burst again) · click: on every click of `for`, or of the parent when `for` is not given · event: on every `ma:confetti` dispatched on document whose `detail.target` is empty or this element, and once at bind when the element carries `data-ma-confetti-fire` (removed as it fires). A script that may run before the component sets the attribute and dispatches in the same task: whichever runs first, one burst.' },
+    { name: 'for', type: 'string', description: 'Selector of the element whose clicks fire (click); on every trigger the burst starts from its centre.' },
+    { name: 'count', type: 'number', default: '120', description: 'Pieces per burst.' },
+    { name: 'colors', type: 'string[]', default: 'five accents from the stylesheet', description: 'Literal colours (hex, rgb(), oklch()), cycled through; var() is not resolved by the canvas. For tokens, use CSS on .ma-confetti: its computed `color` and `border-top/right/bottom/left-color` are the five the default reads.' },
+    { name: 'origin', type: '{ x, y }', description: 'Launch point in viewport px; default the centre of `for` (or of the clicked parent), the viewport centre on load or event without `for`.' },
+    { name: 'angle', type: 'number', default: '0', description: 'Launch direction in degrees: 0 up, 90 right.' },
+    { name: 'spread', type: 'number', default: 'the preset token', description: 'Launch cone in degrees; the token is 70, narrower on snap, wider on lively.' },
+  ],
+  reducedMotion: 'Nothing fires on load, on click or on an event, and a `data-ma-confetti-fire` request is discarded. The burst itself reads the setting live and every trigger stays armed, so the site\'s motion switch applies to the next one in both directions, without a reload.',
+  clientRouter: 'Bound through the shared runtime, the ma:confetti listener included (one per element, removed on swap); a burst in flight is dropped with its canvas before the swap, and the next page starts clean.',
+  craft: [
+    'The canvas is created on the first piece and removed after the last one lands: a page with a confetti button costs a hidden span until it is pressed.',
+    'The physics live in CSS as custom properties per preset (snap launches harder and stops sooner, ambient floats) so the burst has the page\'s character; the script only reads numbers.',
+    'Pieces are paper rectangles that rotate and flutter (a cosine on their height); drag on the velocity gives the arc its shoulder.',
+    'Bursts share one canvas and one frame loop; the loop sleeps in a hidden tab like every canvas in the library.',
+    'confetti() is exported like toast(): the component is the declarative wiring, the function is the act.',
+    'trigger="event" is the ma:toast pattern for code that should not import the lib, made independent of script order: a request made before the component binds is an attribute it consumes, one made after is the event, and firing clears the attribute, so set-then-dispatch bursts once.',
+    'Colours are read from the element\'s computed style, like every canvas in the library: fillStyle does not resolve var(), so a token passed through `colors` paints black, while the same token on `color` or a border colour arrives resolved and follows the theme.',
+  ],
+  related: ['toast', 'stateful-button', 'particles'],
+  intents: ['confetti on click', 'celebration animation', 'confetti burst success', 'party popper button', 'confetti astro without canvas-confetti', 'confetti after form submit', 'trigger confetti from javascript event'],
+  replaces: ['Confetti (Magic UI)', 'canvas-confetti', 'react-confetti'],
+  // event: the attribute in the server HTML, the order a thank-you page produces when its script runs first
+  fixture: { props: { trigger: 'click' }, expect: 'class="ma-confetti"', variants: { event: { props: { trigger: 'event', 'data-ma-confetti-fire': '' }, expect: 'data-trigger="event"' } } },
+} satisfies ComponentMeta;