@moonarc/core 0.1.0

package/src/components/StaggerMenu.astro

@@ -0,0 +1,301 @@
+---
+/**
+ * StaggerMenu — a burger that opens a full-screen (or top, or side) menu
+ * whose items arrive one after another, zero JS.
+ *
+ * The menu is a native modal <dialog> opened by the invoker command, so the
+ * focus trap, Escape, the backdrop click and the focus returning to the
+ * burger are the browser's. Each item transitions in from the enter travel
+ * with a delay of index × stagger through @starting-style; on close the
+ * delays reverse and display/overlay wait through allow-discrete for the
+ * last item to leave. The burger and the close button are AnimatedIcons:
+ * the X starts as three lines and folds as the menu opens. A link to a place
+ * on the same page carries a one-line onclick that closes the menu, or the
+ * page would scroll to it behind the open modal.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import AnimatedIcons from './AnimatedIcons.astro';
+
+interface Item {
+  href: string;
+  label: string;
+}
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Dialog id; unique per page. */
+  id: string;
+  items: Item[];
+  /** full: covers the viewport · top: a sheet from the top · right: a panel from the right. */
+  side?: 'full' | 'top' | 'right';
+  /** href of the current page (aria-current). */
+  current?: string;
+  /** Accessible name of the trigger and the dialog. */
+  label?: string;
+  /** Menu colours; default ink on panel text. */
+  color?: string;
+  textColor?: string;
+  /** Add the inline click handler for browsers without invoker commands. */
+  polyfill?: boolean;
+}
+
+const { id, items, side = 'full', current, label = 'Menu', color, textColor, polyfill = false, class: className, style, ...rest } = Astro.props;
+const vars = [`--ma-smenu-n:${items.length}`, color && `--ma-smenu-bg:${color}`, textColor && `--ma-smenu-fg:${textColor}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+const triggerAttrs = { command: 'show-modal', commandfor: id };
+const pad = (n: number) => String(n).padStart(2, '0');
+// a link to a place on this page (a hash on the current path) never unloads it, so nothing would close the modal. An href
+// URL() cannot parse is rendered as given, as before, and is not one of those.
+const here = (href: string) => {
+  try {
+    const u = new URL(href, Astro.url);
+    return !!u.hash && u.pathname === Astro.url.pathname && u.search === Astro.url.search;
+  } catch {
+    return false;
+  }
+};
+---
+
+<div class:list={['ma-smenu', className]} data-side={side} style={vars} {...rest}>
+  <button type="button" class="ma-smenu__trigger" aria-haspopup="dialog" aria-label={label} {...triggerAttrs}>
+    <AnimatedIcons icon="menu" size="1.25em" />
+  </button>
+  <dialog id={id} class="ma-smenu__dialog" closedby="any" aria-label={label}>
+    <form method="dialog" class="ma-smenu__close">
+      <button type="submit" aria-label="Close menu">
+        <AnimatedIcons icon="menu" state="on" size="1.25em" />
+      </button>
+    </form>
+    <nav class="ma-smenu__nav" aria-label={label}>
+      <ul class="ma-smenu__list">
+        {
+          items.map((it, i) => (
+            <li class="ma-smenu__item" style={`--ma-i:${i}`}>
+              <a href={it.href} class="ma-smenu__link" aria-current={it.href === current ? 'page' : undefined} onclick={here(it.href) ? "this.closest('dialog').close()" : undefined}>
+                <span class="ma-smenu__index" aria-hidden="true">{pad(i + 1)}</span>
+                <span class="ma-smenu__label">{it.label}</span>
+              </a>
+            </li>
+          ))
+        }
+      </ul>
+    </nav>
+    {Astro.slots.has('default') && <div class="ma-smenu__foot"><slot /></div>}
+  </dialog>
+</div>
+{polyfill && <script is:inline>window.__maCmd||(window.__maCmd=1,document.addEventListener('click',function(e){if('command'in HTMLButtonElement.prototype||e.defaultPrevented)return;var b=e.target.closest('[commandfor]');if(!b)return;var d=document.getElementById(b.getAttribute('commandfor'));if(!d)return;var c=b.getAttribute('command');c==='show-modal'?d.showModal():c==='close'?d.close():c==='toggle-popover'?d.togglePopover():0}))</script>}
+
+<style is:global>
+  @layer components {
+    :where(.ma-smenu) {
+      /* the exit has to wait for the last item: the panel's display transition is duration + n × stagger */
+      --ma-smenu-total: calc(var(--ma-duration) + var(--ma-smenu-n, 4) * var(--ma-stagger));
+      display: inline-block;
+    }
+    :where(.ma-smenu__trigger),
+    :where(.ma-smenu__close button) {
+      display: grid;
+      place-items: center;
+      width: 2.5rem;
+      height: 2.5rem;
+      border: 1px solid var(--ma-edge);
+      border-radius: 999px;
+      background: var(--ma-panel);
+      color: inherit;
+      cursor: pointer;
+      transition: background-color var(--ma-duration-fast) var(--ma-ease-out), scale var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-smenu__trigger:hover),
+    :where(.ma-smenu__close button:hover) {
+      scale: 1.06;
+    }
+    :where(.ma-smenu__trigger:focus-visible),
+    :where(.ma-smenu__close button:focus-visible),
+    :where(.ma-smenu__link:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 3px;
+    }
+    /* the panel */
+    :where(.ma-smenu__dialog) {
+      position: fixed;
+      inset: 0;
+      margin: 0;
+      width: 100%;
+      height: 100%;
+      max-width: none;
+      max-height: none;
+      padding: clamp(1.5rem, 6vw, 4rem);
+      border: 0;
+      background: var(--ma-smenu-bg, var(--ma-ink));
+      color: var(--ma-smenu-fg, var(--ma-panel));
+      overflow: auto;
+      opacity: 0;
+      translate: 0 var(--ma-travel-enter, 24px);
+      transition:
+        opacity var(--ma-duration) var(--ma-ease-in) calc(var(--ma-smenu-n, 4) * var(--ma-stagger)),
+        translate var(--ma-duration) var(--ma-ease-in) calc(var(--ma-smenu-n, 4) * var(--ma-stagger)),
+        display var(--ma-smenu-total) allow-discrete,
+        overlay var(--ma-smenu-total) allow-discrete;
+    }
+    :where(.ma-smenu__dialog[open]) {
+      opacity: 1;
+      translate: 0 0;
+      transition-delay: 0s;
+      transition-timing-function: var(--ma-ease);
+    }
+    @starting-style {
+      :where(.ma-smenu__dialog[open]) {
+        opacity: 0;
+        translate: 0 var(--ma-travel-enter, 24px);
+      }
+    }
+    :where(.ma-smenu[data-side='top'] .ma-smenu__dialog) {
+      height: auto;
+      max-height: 90dvh;
+      inset: 0 0 auto 0;
+      border-radius: 0 0 1.5rem 1.5rem;
+      translate: 0 calc(var(--ma-travel-enter, 24px) * -1);
+    }
+    :where(.ma-smenu[data-side='right'] .ma-smenu__dialog) {
+      width: min(26rem, 100%);
+      inset: 0 0 0 auto;
+      translate: var(--ma-travel-enter, 24px) 0;
+    }
+    :where(.ma-smenu[data-side='top'] .ma-smenu__dialog[open]),
+    :where(.ma-smenu[data-side='right'] .ma-smenu__dialog[open]) {
+      translate: 0 0;
+    }
+    @starting-style {
+      :where(.ma-smenu[data-side='top'] .ma-smenu__dialog[open]) {
+        translate: 0 calc(var(--ma-travel-enter, 24px) * -1);
+      }
+      :where(.ma-smenu[data-side='right'] .ma-smenu__dialog[open]) {
+        translate: var(--ma-travel-enter, 24px) 0;
+      }
+    }
+    :where(.ma-smenu__dialog)::backdrop {
+      background: var(--ma-scrim);
+      opacity: 0;
+      transition:
+        opacity var(--ma-duration) var(--ma-ease-out),
+        display var(--ma-smenu-total) allow-discrete,
+        overlay var(--ma-smenu-total) allow-discrete;
+    }
+    :where(.ma-smenu__dialog[open])::backdrop {
+      opacity: 1;
+    }
+    @starting-style {
+      :where(.ma-smenu__dialog[open])::backdrop {
+        opacity: 0;
+      }
+    }
+    :where(.ma-smenu__close) {
+      position: absolute;
+      inset-block-start: 1.25rem;
+      inset-inline-end: 1.25rem;
+    }
+    /* the X starts as the burger and folds as the panel arrives */
+    @starting-style {
+      :where(.ma-smenu__dialog[open] .ma-smenu__close .ma-icon__a),
+      :where(.ma-smenu__dialog[open] .ma-smenu__close .ma-icon__c) {
+        translate: 0 0;
+        rotate: 0deg;
+      }
+      :where(.ma-smenu__dialog[open] .ma-smenu__close .ma-icon__b) {
+        scale: 1 1;
+        opacity: 1;
+      }
+    }
+    :where(.ma-smenu__nav) {
+      display: grid;
+      align-content: center;
+      min-height: 100%;
+    }
+    :where(.ma-smenu[data-side='top'] .ma-smenu__nav),
+    :where(.ma-smenu[data-side='right'] .ma-smenu__nav) {
+      min-height: 0;
+      padding-top: 2.5rem;
+    }
+    :where(.ma-smenu__list) {
+      display: grid;
+      gap: 0.25em;
+      margin: 0;
+      padding: 0;
+      list-style: none;
+    }
+    /* the items: in order on open, reversed on close, each on the stagger token */
+    :where(.ma-smenu__item) {
+      opacity: 0;
+      translate: 0 var(--ma-travel-enter, 24px);
+      transition:
+        opacity var(--ma-duration) var(--ma-ease-out),
+        translate var(--ma-duration) var(--ma-ease);
+      transition-delay: calc((var(--ma-smenu-n, 4) - 1 - var(--ma-i, 0)) * var(--ma-stagger));
+    }
+    :where(.ma-smenu__dialog[open] .ma-smenu__item) {
+      opacity: 1;
+      translate: 0 0;
+      transition-delay: calc(var(--ma-i, 0) * var(--ma-stagger) + var(--ma-duration-fast));
+    }
+    @starting-style {
+      :where(.ma-smenu__dialog[open] .ma-smenu__item) {
+        opacity: 0;
+        translate: 0 var(--ma-travel-enter, 24px);
+      }
+    }
+    :where(.ma-smenu__link) {
+      display: flex;
+      align-items: baseline;
+      gap: 0.75em;
+      padding: 0.15em 0;
+      color: inherit;
+      text-decoration: none;
+      font-size: clamp(2rem, 7vw, 4.5rem);
+      font-weight: 700;
+      letter-spacing: -0.03em;
+      line-height: 1.05;
+      opacity: 0.85;
+      transition:
+        opacity var(--ma-duration-fast) var(--ma-ease-out),
+        translate var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-smenu[data-side='top'] .ma-smenu__link),
+    :where(.ma-smenu[data-side='right'] .ma-smenu__link) {
+      font-size: clamp(1.5rem, 4vw, 2.25rem);
+    }
+    :where(.ma-smenu__link:hover),
+    :where(.ma-smenu__link[aria-current='page']) {
+      opacity: 1;
+      translate: 0.25em 0;
+    }
+    :where(.ma-smenu__index) {
+      font-family: ui-monospace, monospace;
+      font-size: 0.75rem;
+      font-weight: 400;
+      letter-spacing: 0.1em;
+      opacity: var(--ma-dim, 0.7);
+    }
+    :where(.ma-smenu__foot) {
+      margin-top: 2rem;
+      font-size: 0.875rem;
+      opacity: 0.7;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-smenu__dialog),
+      :where(.ma-smenu__dialog[open]),
+      :where(.ma-smenu__item),
+      :where(.ma-smenu__dialog[open] .ma-smenu__item) {
+        translate: 0 0;
+        transition-duration: var(--ma-duration-fast);
+        transition-delay: 0s;
+        transition-timing-function: linear;
+      }
+      :where(.ma-smenu) {
+        --ma-smenu-total: var(--ma-duration-fast);
+      }
+      :where(.ma-smenu__link),
+      :where(.ma-smenu__trigger),
+      :where(.ma-smenu__close button) {
+        transition: none;
+      }
+    }
+  }
+</style>

package/src/components/StaggerMenu.meta.ts

@@ -0,0 +1,39 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'StaggerMenu',
+  slug: 'stagger-menu',
+  title: 'Stagger Menu',
+  description: 'A burger that opens a full-screen menu (or a top sheet, or a side panel) whose items arrive one after another and leave in reverse. No script: a native modal dialog opened by the invoker command (focus trap, Escape, backdrop click and the focus returning to the burger are the browser\'s), and each item is a @starting-style transition delayed by its index on the stagger token. A link to a place on the same page carries a one-line onclick that closes the menu.',
+  summary: 'A full-screen menu from a burger button, its items arriving one after another and leaving in reverse.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['click'],
+  support: { baseline: 'newly', needs: ['command', 'starting-style', 'allow-discrete', 'dialog'], fallback: 'without invoker commands the burger needs polyfill (an inline handler of 403 B raw); without @starting-style the menu opens without the stagger; without closedby (Safari) a backdrop click does nothing, and Escape and the close button still close it' },
+  readout: '<StaggerMenu side="full">',
+  usage: `<StaggerMenu\n  id="menu"\n  items={[\n    { href: '/', label: 'Home' },\n    { href: '/work/', label: 'Work' },\n    { href: '/studio/', label: 'Studio' },\n    { href: '/contact/', label: 'Contact' },\n  ]}\n  current="/work/"\n>\n  <p>hello@studio.example · Jakarta</p>\n</StaggerMenu>`,
+  props: [
+    { name: 'id', type: 'string', description: 'Dialog id; unique per page.' },
+    { name: 'items', type: '{ href: string; label: string }[]', description: 'The links, numbered in order. A link to a place on the current page (#…) closes the menu when followed, through an onclick of 30 B raw rendered on that link only.' },
+    { name: 'side', type: "'full' | 'top' | 'right'", default: "'full'", description: 'full covers the viewport with big type; top is a sheet from the top edge; right a panel from the right.' },
+    { name: 'current', type: 'string', description: 'href of the current page (aria-current="page").' },
+    { name: 'label', type: 'string', default: "'Menu'", description: 'Accessible name of the burger and the dialog.' },
+    { name: 'color', type: 'string', description: 'Panel colour; default the ink token.' },
+    { name: 'textColor', type: 'string', description: 'Text colour; default the panel token.' },
+    { name: 'polyfill', type: 'boolean', default: 'false', description: 'Inline the invoker click handler (403 B raw) for browsers without command / commandfor (Safari < 26.2, Firefox < 144); without it the burger opens nothing there.' },
+  ],
+  reducedMotion: 'The panel and every item cross-fade together in 150 ms; no travel, no stagger.',
+  clientRouter: 'Native; nothing to rebind. Following a link to another page closes the menu with the page; mark the new page with current. A link to a place on the same page closes it through its onclick.',
+  craft: [
+    'A modal <dialog> is the cheapest focus trap there is: Escape, the backdrop click (closedby="any", Chrome and Firefox) and the focus returning to the burger cost nothing and cannot drift from the platform.',
+    'A link to #section on the same page never unloads it, so the modal would stay over the section it scrolled to. Those links, found at build by comparing the href with the page\'s own URL, carry onclick="this.closest(\'dialog\').close()"; the menu folds away while the page scrolls.',
+    'Each item\'s delay is index × the stagger token on the way in and (n − 1 − index) × stagger on the way out, so the menu folds back the way it unfolded; the panel\'s own fade waits n × stagger so it never leaves before its last item.',
+    'display and overlay transition with allow-discrete for duration + n × stagger: the top layer holds the panel exactly as long as the exit takes.',
+    'The X is an AnimatedIcons menu in its "on" state whose paths start in the burger shape through @starting-style, so opening reads as the burger folding into the X even though the two are different elements.',
+    'Big type is the whole design of a fullscreen menu: clamp(2rem, 7vw, 4.5rem), tight tracking, an index in mono at half opacity. The top and right sides step it down.',
+  ],
+  related: ['dialog', 'animated-icons', 'drawer', 'text-roll'],
+  intents: ['fullscreen menu', 'staggered menu items', 'burger menu overlay', 'hamburger menu animation astro', 'menu items animate in one by one', 'mobile nav overlay'],
+  replaces: ['StaggerMenu (React Bits)', 'FullscreenMenu (Hover.dev)', 'Sheet (shadcn / Radix)', 'AnimatePresence menu (Framer Motion)'],
+  fixture: { props: { id: 'ma-fixture-smenu', items: [{ href: '/', label: 'Fixture content for StaggerMenu' }, { href: '/two/', label: 'Two' }] }, expect: 'Fixture content for StaggerMenu' },
+} satisfies ComponentMeta;

package/src/components/StatefulButton.astro

@@ -0,0 +1,148 @@
+---
+/**
+ * StatefulButton — one button, four faces: idle, pending (a spinner),
+ * done (a check that draws itself), error. Zero JS of its own: the state is
+ * `data-state` on the button — set by the `state` prop, by your own script,
+ * or inherited from its form: `data-pending` shows the pending face, and
+ * `data-state` done, exists or error the matching one (exists shows done),
+ * which is what @moonarc/core/form writes. The faces sit in one row; the inactive ones are clipped to zero
+ * width and the active one opens to a bound derived from its label length
+ * (the RotatingText `fluid` technique), so the button's width follows the
+ * label on the preset's spring with nothing measured. Inactive faces are
+ * visibility: hidden, so the button is named by the face that shows. The
+ * button is not a live region: the announcement is the form's role="status"
+ * (which the form lib requires) or the caller's. The `pending` state renders
+ * aria-disabled, not disabled, so the focus stays on the button; neither it
+ * nor a form's `data-pending` can stop a submit (no script here), so the
+ * handler that sets them ignores submits meanwhile.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import Spinner from './Spinner.astro';
+import AnimatedIcons from './AnimatedIcons.astro';
+
+type State = 'idle' | 'pending' | 'done' | 'error';
+
+interface Props extends HTMLAttributes<'button'> {
+  /** Current face. */
+  state?: State;
+  /** Face labels. The default slot, when given, replaces the idle label. */
+  labels?: Partial<Record<State, string>>;
+  type?: 'button' | 'submit' | 'reset';
+}
+
+const { state = 'idle', labels = {}, type = 'submit', class: className, style, ...rest } = Astro.props;
+const text: Record<State, string> = { idle: labels.idle ?? 'Submit', pending: labels.pending ?? 'Sending', done: labels.done ?? 'Done', error: labels.error ?? 'Try again' };
+const hasSlot = Astro.slots.has('default');
+// the open width bound per face: 0.62em per character + the icon and its gap — above any Latin label, never far above it.
+// A wide character (CJK, Hangul, kana, full-width forms, emoji) is a full em: at 0.62em "送信中" was cut to its first two.
+const WIDE = /[\u1100-\u115f\u2e80-\u303e\u3041-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]|\p{Extended_Pictographic}|[\u{20000}-\u{3fffd}]/u;
+const bound = (label: string, icon: boolean) => `calc(${[...label].reduce((w, c) => w + (WIDE.test(c) ? 1 : 0.62), 0).toFixed(2)}em + ${icon ? '1.6em' : '0em'})`;
+---
+
+<button class:list={['ma-stateful', className]} type={type} data-state={state} aria-disabled={state === 'pending' ? 'true' : undefined} style={style} {...rest}>
+  <span class="ma-stateful__face" data-face="idle" style={`--ma-stateful-w:${hasSlot ? 'none' : bound(text.idle, false)}`}>{hasSlot ? <slot /> : text.idle}</span>
+  <span class="ma-stateful__face" data-face="pending" style={`--ma-stateful-w:${bound(text.pending, true)}`}><Spinner size={16} width={2} label="" /><span>{text.pending}</span></span>
+  <span class="ma-stateful__face" data-face="done" style={`--ma-stateful-w:${bound(text.done, true)}`}><AnimatedIcons icon="check" state="on" /><span>{text.done}</span></span>
+  <span class="ma-stateful__face" data-face="error" style={`--ma-stateful-w:${bound(text.error, true)}`}><AnimatedIcons icon="plus" state="on" /><span>{text.error}</span></span>
+</button>
+
+<style is:global>
+  @layer components {
+    :where(.ma-stateful) {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: 0.65em 1.2em;
+      border: 1px solid var(--ma-edge);
+      border-radius: var(--ma-stateful-radius, var(--ma-radius-md, 0.6em));
+      background: var(--ma-ink);
+      color: var(--ma-panel);
+      font: inherit;
+      font-weight: 500;
+      line-height: 1.2;
+      white-space: nowrap;
+      cursor: pointer;
+      transition:
+        background-color var(--ma-duration-fast) var(--ma-ease-out),
+        opacity var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-stateful[aria-disabled='true']) {
+      cursor: progress;
+    }
+    :where(.ma-stateful:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: 3px;
+    }
+    /* inactive faces leave the accessibility tree (the CopyButton rule), so the button is named by the one that shows.
+       visibility transitions with the fade on ease-out: an arriving face counts at
+       once, a leaving one until it has faded; an overshooting preset curve would flip it mid-fade */
+    :where(.ma-stateful__face) {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.5em;
+      max-width: 0;
+      opacity: 0;
+      visibility: hidden;
+      overflow: clip;
+      translate: 0 var(--ma-travel-hover);
+      transition:
+        max-width var(--ma-duration) var(--ma-ease),
+        opacity var(--ma-duration) var(--ma-ease),
+        translate var(--ma-duration) var(--ma-ease),
+        visibility var(--ma-duration) var(--ma-ease-out);
+    }
+    :where(.ma-stateful__face > *) {
+      flex: none;
+    }
+    :where(.ma-stateful[data-state='idle'] [data-face='idle']),
+    :where(.ma-stateful[data-state='pending'] [data-face='pending']),
+    :where(.ma-stateful[data-state='done'] [data-face='done']),
+    :where(.ma-stateful[data-state='error'] [data-face='error']) {
+      max-width: var(--ma-stateful-w, none);
+      opacity: 1;
+      visibility: visible;
+      translate: 0 0;
+    }
+    /* a form that says where it is: the button follows, whatever its own state says. data-pending shows the pending face,
+       data-state done, exists or error the matching one (exists is done: the address was already in), the attributes the
+       form lib writes. pointer-events stops the mouse only; Enter and Space still submit, so the handler that sets
+       data-pending ignores submits while it is there (the form lib does) */
+    :where(form:is([data-pending], [data-state='done'], [data-state='exists'], [data-state='error']) .ma-stateful [data-face]) {
+      max-width: 0;
+      opacity: 0;
+      visibility: hidden;
+    }
+    :where(form[data-pending] .ma-stateful [data-face='pending']),
+    :where(form:is([data-state='done'], [data-state='exists']):not([data-pending]) .ma-stateful [data-face='done']),
+    :where(form[data-state='error']:not([data-pending]) .ma-stateful [data-face='error']) {
+      max-width: var(--ma-stateful-w, none);
+      opacity: 1;
+      visibility: visible;
+      translate: 0 0;
+    }
+    :where(form[data-pending] .ma-stateful) {
+      pointer-events: none;
+    }
+    /* the state tints are hooks: on a coloured ground a caller points --ma-stateful-done / --ma-stateful-error at a colour
+       its label keeps 4.5 : 1 on (the words carry the state either way) */
+    :where(.ma-stateful[data-state='done']) {
+      background: var(--ma-stateful-done, color-mix(in srgb, var(--ma-ink) 88%, #7cc67c));
+    }
+    :where(.ma-stateful[data-state='error']) {
+      background: var(--ma-stateful-error, color-mix(in srgb, var(--ma-ink) 84%, #e0563f));
+    }
+    /* after the button's own: the form's state wins, as it does for the faces */
+    :where(form:is([data-state='done'], [data-state='exists']) .ma-stateful) {
+      background: var(--ma-stateful-done, color-mix(in srgb, var(--ma-ink) 88%, #7cc67c));
+    }
+    :where(form[data-state='error'] .ma-stateful) {
+      background: var(--ma-stateful-error, color-mix(in srgb, var(--ma-ink) 84%, #e0563f));
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-stateful__face) {
+        transition: none;
+        translate: 0 0;
+      }
+    }
+  }
+</style>

package/src/components/StatefulButton.meta.ts

@@ -0,0 +1,35 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'StatefulButton',
+  slug: 'stateful-button',
+  title: 'Stateful Button',
+  description: 'One submit button with four faces (idle, pending with a spinner, done with a check that draws itself, error) and a width that follows the label. The state is data-state on the button, set by the prop, by your script, or inherited from its form: data-pending and data-state done, exists or error, the attributes @moonarc/core/form writes. The faces are clipped to a bound derived from the label, so nothing is measured, and only the face that shows is in the accessibility tree. Zero JavaScript of its own.',
+  summary: 'A submit button with idle, pending, done and error states, a spinner and a check, its width following the label.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['click'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<StatefulButton state="pending">',
+  usage: `<form data-signup>\n  <input type="email" name="email" required />\n  <StatefulButton labels={{ idle: 'Subscribe', pending: 'Sending', done: 'You are in', error: 'Try again' }} />\n  <p role="status"></p>\n</form>\n\n<script>\n  const form = document.querySelector('[data-signup]');\n  form.addEventListener('submit', async (e) => {\n    e.preventDefault();\n    // data-pending cannot stop Enter or Space from sending again, so a second submit is ignored here\n    if (form.hasAttribute('data-pending')) return;\n    form.dataset.pending = '';\n    delete form.dataset.state;\n    let ok = false;\n    try {\n      ok = (await fetch('/api/subscribe', { method: 'POST', body: new FormData(form) })).ok;\n    } catch {}\n    delete form.dataset.pending;\n    form.dataset.state = ok ? 'done' : 'error';\n    // the button is not a live region: say it in the form's role="status"\n    form.querySelector('[role="status"]').textContent = ok ? 'You are in.' : 'That did not go through. Try again.';\n  });\n</script>`,
+  props: [
+    { name: 'state', type: "'idle' | 'pending' | 'done' | 'error'", default: "'idle'", description: 'Current face. The pending state renders aria-disabled="true", not disabled, so the focus stays on the button; a data-state your script writes later changes the face only, so write aria-disabled with it. Inside a form, the form\'s data-pending and data-state win.' },
+    { name: 'labels', type: 'Partial<Record<State, string>>', default: 'Submit / Sending / Done / Try again', description: 'Face labels. The default slot replaces the idle label.' },
+    { name: 'type', type: "'button' | 'submit' | 'reset'", default: "'submit'", description: 'Button type.' },
+  ],
+  reducedMotion: 'Faces switch at once; the spinner slows and the check is simply drawn.',
+  clientRouter: 'CSS-only; the state attribute is on the element and goes with the page.',
+  craft: [
+    'Width follows the label without measuring: each face opens to a max-width derived from its characters plus the icon, a bound just above the label, so the transition ends where the text ends. This is the RotatingText fluid technique. interpolate-size would not have helped: auto → auto never transitions.',
+    'A form that says data-pending, or data-state done, exists or error, wins over the button\'s own state, so a form bound with @moonarc/core/form drives the faces with no code (exists shows the done face). The mouse cannot press it while the form is pending. Enter in a field and Space on the button still submit, because CSS cannot disable a button, so the handler that sets data-pending returns early while it is there, as the form lib and the usage do.',
+    'Pending is aria-disabled, not disabled: a disabled button loses the focus the moment it is pressed (Chromium sends it to the body), and a keyboard reader would have to find the form again.',
+    'The spinner is the library\'s Spinner and the check is AnimatedIcons, so the three motions share one preset.',
+    'Inactive faces are visibility: hidden, which takes them out of the accessibility tree, so the button is named by the face that shows. It is not a live region: a live button would announce its own name each time a face arrives, on top of the form\'s role="status" that says the same thing in a sentence. visibility transitions with the fade on ease-out: an arriving face counts at once, a leaving one until it has faded.',
+    'The tints and the corner are hooks: --ma-stateful-done and --ma-stateful-error for a coloured ground where the label must keep 4.5 : 1, --ma-stateful-radius over the theme\'s --ma-radius-md.',
+    'The width bound counts 0.62 em per Latin character and a full em for a wide one (CJK, Hangul, kana, full-width forms, emoji), so a Japanese or Korean label opens to its whole length.',
+  ],
+  related: ['spinner', 'animated-icons', 'copy-button'],
+  intents: ['loading button', 'submit button with spinner', 'button success state', 'stateful button', 'button that shows sending and done'],
+  replaces: ['StatefulButton (Aceternity)', 'LoadingButton (shadcn examples)'],
+  fixture: { props: { labels: { idle: 'Fixture content for StatefulButton' } }, expect: 'Fixture content for StatefulButton' },
+} satisfies ComponentMeta;