@moonarc/core 0.1.0

package/src/components/OrbitingCircles.astro

@@ -0,0 +1,119 @@
+---
+/**
+ * OrbitingCircles — the children orbit the centre of their parent and stay
+ * upright. One animation per item: `rotate(a) translate(r) rotate(−a)` from
+ * a to a + 360°, where a is the item's start angle from its index — so the
+ * icon turns around the centre without turning itself, on the compositor,
+ * with no wrapper. The start angles come from :nth-child, the count from
+ * :has(), so nothing is passed twice; `count` overrides when the children
+ * are not the whole ring. Two instances at two radii are two rings;
+ * `reverse` sends one the other way. Fills its positioned parent.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Orbit radius in px. */
+  radius?: number;
+  /** Seconds per revolution. */
+  duration?: number;
+  /** Run counter-clockwise. */
+  reverse?: boolean;
+  /** Draw the orbit line. */
+  path?: boolean;
+  /** Number of items on the ring; default counted from the children (up to 12). */
+  count?: number;
+  /** Item size in px (each child is a square cell of this size). */
+  size?: number;
+  /** Orbit line colour. */
+  color?: string;
+}
+
+const { radius = 100, duration = 20, reverse = false, path = true, count, size = 40, color = 'var(--ma-edge)', class: className, style, ...rest } = Astro.props;
+const inline = [`--ma-orbit-r:${radius}px`, `--ma-orbit-dur:${duration}s`, `--ma-orbit-size:${size}px`, `--ma-orbit-color:${color}`, count ? `--ma-orbit-n:${count}` : '', typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<div class:list={['ma-orbit', className]} data-ma-orbit data-path={path ? '' : undefined} data-reverse={reverse ? '' : undefined} style={inline} {...rest}>
+  <slot />
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-orbit) {
+      position: absolute;
+      left: 50%;
+      top: 50%;
+      width: 0;
+      height: 0;
+      pointer-events: none;
+    }
+    :where(.ma-orbit[data-path])::before {
+      content: '';
+      position: absolute;
+      left: 0;
+      top: 0;
+      width: calc(var(--ma-orbit-r, 100px) * 2);
+      height: calc(var(--ma-orbit-r, 100px) * 2);
+      translate: -50% -50%;
+      border: 1px solid var(--ma-orbit-color, var(--ma-edge));
+      border-radius: 50%;
+    }
+    /* count from the children when not given — the ring with n children matches :has(> :nth-child(n):last-child) */
+    :where(.ma-orbit:has(> :nth-child(1):last-child)) { --ma-orbit-n: 1; }
+    :where(.ma-orbit:has(> :nth-child(2):last-child)) { --ma-orbit-n: 2; }
+    :where(.ma-orbit:has(> :nth-child(3):last-child)) { --ma-orbit-n: 3; }
+    :where(.ma-orbit:has(> :nth-child(4):last-child)) { --ma-orbit-n: 4; }
+    :where(.ma-orbit:has(> :nth-child(5):last-child)) { --ma-orbit-n: 5; }
+    :where(.ma-orbit:has(> :nth-child(6):last-child)) { --ma-orbit-n: 6; }
+    :where(.ma-orbit:has(> :nth-child(7):last-child)) { --ma-orbit-n: 7; }
+    :where(.ma-orbit:has(> :nth-child(8):last-child)) { --ma-orbit-n: 8; }
+    :where(.ma-orbit:has(> :nth-child(9):last-child)) { --ma-orbit-n: 9; }
+    :where(.ma-orbit:has(> :nth-child(10):last-child)) { --ma-orbit-n: 10; }
+    :where(.ma-orbit:has(> :nth-child(11):last-child)) { --ma-orbit-n: 11; }
+    :where(.ma-orbit:has(> :nth-child(12):last-child)) { --ma-orbit-n: 12; }
+    :where(.ma-orbit > :nth-child(1)) { --ma-orbit-i: 0; }
+    :where(.ma-orbit > :nth-child(2)) { --ma-orbit-i: 1; }
+    :where(.ma-orbit > :nth-child(3)) { --ma-orbit-i: 2; }
+    :where(.ma-orbit > :nth-child(4)) { --ma-orbit-i: 3; }
+    :where(.ma-orbit > :nth-child(5)) { --ma-orbit-i: 4; }
+    :where(.ma-orbit > :nth-child(6)) { --ma-orbit-i: 5; }
+    :where(.ma-orbit > :nth-child(7)) { --ma-orbit-i: 6; }
+    :where(.ma-orbit > :nth-child(8)) { --ma-orbit-i: 7; }
+    :where(.ma-orbit > :nth-child(9)) { --ma-orbit-i: 8; }
+    :where(.ma-orbit > :nth-child(10)) { --ma-orbit-i: 9; }
+    :where(.ma-orbit > :nth-child(11)) { --ma-orbit-i: 10; }
+    :where(.ma-orbit > :nth-child(12)) { --ma-orbit-i: 11; }
+    :where(.ma-orbit > *) {
+      position: absolute;
+      left: 0;
+      top: 0;
+      display: grid;
+      place-items: center;
+      width: var(--ma-orbit-size, 40px);
+      height: var(--ma-orbit-size, 40px);
+      margin: calc(var(--ma-orbit-size, 40px) / -2);
+      pointer-events: auto;
+      /* the start angle, from the index and the count */
+      --ma-orbit-a: calc(var(--ma-orbit-i, 0) * 360deg / var(--ma-orbit-n, 1));
+      transform: rotate(var(--ma-orbit-a)) translate(var(--ma-orbit-r, 100px)) rotate(calc(-1 * var(--ma-orbit-a)));
+      will-change: transform;
+      animation: ma-orbit var(--ma-orbit-dur) linear infinite;
+    }
+    :where(.ma-orbit[data-reverse] > *) {
+      animation-direction: reverse;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-orbit > *) {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-orbit {
+    from {
+      transform: rotate(var(--ma-orbit-a)) translate(var(--ma-orbit-r, 100px)) rotate(calc(-1 * var(--ma-orbit-a)));
+    }
+    to {
+      transform: rotate(calc(var(--ma-orbit-a) + 360deg)) translate(var(--ma-orbit-r, 100px)) rotate(calc(-1 * var(--ma-orbit-a) - 360deg));
+    }
+  }
+</style>

package/src/components/OrbitingCircles.meta.ts

@@ -0,0 +1,36 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'OrbitingCircles',
+  slug: 'orbiting-circles',
+  title: 'Orbiting Circles',
+  description: 'The children orbit the centre of their parent and stay upright. One transform animation per item (rotate, translate out, rotate back) from its start angle to a full turn, on the compositor, no wrapper. Start angles come from :nth-child, the count from :has(). Two instances at two radii are two rings; `reverse` sends one the other way. Zero JS.',
+  summary: 'Icons or other elements orbiting a centre point while staying upright, in one ring or several.',
+  category: 'background',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'widely', needs: ['has'], fallback: 'pass `count`; without :has() and without count the items stack at one angle' },
+  readout: '<OrbitingCircles radius={100} duration={20}>',
+  usage: `<div class="relative h-96">\n  <OrbitingCircles radius={110} duration={24}>\n    <Icon name="astro" />\n    <Icon name="tailwind" />\n    <Icon name="vite" />\n    <Icon name="typescript" />\n  </OrbitingCircles>\n  <OrbitingCircles radius={60} duration={16} reverse size={32}>\n    <Icon name="npm" />\n    <Icon name="pnpm" />\n  </OrbitingCircles>\n</div>`,
+  props: [
+    { name: 'radius', type: 'number', default: '100', description: 'Orbit radius in px.' },
+    { name: 'duration', type: 'number', default: '20', description: 'Seconds per revolution.' },
+    { name: 'reverse', type: 'boolean', default: 'false', description: 'Run counter-clockwise.' },
+    { name: 'path', type: 'boolean', default: 'true', description: 'Draw the orbit line.' },
+    { name: 'count', type: 'number', default: 'the number of children', description: 'Items on the ring, when the children are not the whole ring (or for a browser without :has()).' },
+    { name: 'size', type: 'number', default: '40', description: 'Item cell in px; each child is centred in a square of this size.' },
+    { name: 'color', type: 'string', default: 'var(--ma-edge)', description: 'Orbit line colour.' },
+  ],
+  reducedMotion: 'The items rest at their start angles on the ring.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'rotate(a) translate(r) rotate(−a), animated from a to a + 360° on both rotations: the item circles the centre and never turns itself. One animation per item, no counter-rotating wrapper, no JavaScript.',
+    'The start angle is the index over the count; the index is :nth-child, the count is :has(> :nth-child(n):last-child), so a ring of any size up to twelve needs no props at all.',
+    'The whole transform is one property on the compositor; the cell is a fixed square so the icon is centred by layout, not by measurement.',
+    'Linear timing, because it orbits forever.',
+  ],
+  related: ['animated-beam', 'ripple', 'circular-text'],
+  intents: ['orbiting icons', 'icons rotating around logo', 'orbit animation css', 'planets orbit integration logos', 'circular orbit icons astro'],
+  replaces: ['OrbitingCircles (Magic UI)', 'Orbit (Cult UI)'],
+  fixture: { expect: 'class="ma-orbit"' },
+} satisfies ComponentMeta;

package/src/components/OtpInput.astro

@@ -0,0 +1,215 @@
+---
+/**
+ * OtpInput — a one-time code in cells, zero JS. **One** native input, not
+ * one per digit: paste, SMS autofill (`autocomplete="one-time-code"`),
+ * screen readers and Backspace all work only in the single-input pattern.
+ * The cells are server-rendered boxes under the input; a monospace font with
+ * tabular figures, a letter-spacing of one cell minus one character and a
+ * matching start padding put every glyph in the middle of its cell, and the
+ * caret lands at the front of the next one. The wrapper clips the trailing
+ * spacing so no seventh cell appears; the focus ring is drawn on the wrapper
+ * through :focus-within so it is never clipped. Full and valid → the check
+ * draws itself; `:user-invalid` tints the cells only after the reader has
+ * been there. Every attribute you pass goes to the input. The field is
+ * left to right on any page, since the glyphs have to meet their cells. A
+ * code pasted with spaces or dashes ("123 456") is cut at `length`
+ * characters: stripping them needs a script, and this component has none.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends Omit<HTMLAttributes<'input'>, 'type' | 'size' | 'maxlength' | 'pattern' | 'inputmode'> {
+  /** Number of characters. */
+  length?: number;
+  /** Digits only (numeric keyboard, \d pattern) or letters and digits. */
+  charset?: 'numeric' | 'alphanumeric';
+  name?: string;
+  /** Visible label, rendered as <label for>. Without it, pass aria-label. */
+  label?: string;
+  /** Placeholder glyph per cell; the attribute is what :placeholder-shown reads, so it is always set. */
+  placeholder?: string;
+  /** Cell width, any CSS length; the height and the font follow. */
+  cell?: string;
+  /** Gap between cells. */
+  gap?: string;
+  /** The input's id and the label's for. Unset, unique per render. */
+  id?: string;
+}
+
+const { length = 6, charset = 'numeric', name = 'code', label, placeholder, cell = '2.5rem', gap = '0.5rem', id, class: className, style, ...rest } = Astro.props;
+const n = Math.max(1, Math.min(12, Math.round(length)));
+// unique per render, not per name: a sign-in form and a dialog can both carry a field named "code" (the VanishInput rule)
+const inputId = id ?? `ma-otp-${name}-${Math.random().toString(36).slice(2, 7)}`;
+const pattern = charset === 'numeric' ? `\\d{${n}}` : `[A-Za-z0-9]{${n}}`;
+const vars = [`--ma-otp-n:${n}`, `--ma-otp-cell:${cell}`, `--ma-otp-gap:${gap}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+const ph = placeholder ?? '•'.repeat(n);
+---
+
+{label && <label class="ma-otp__label" for={inputId}>{label}</label>}
+<span class:list={['ma-otp', className]} style={vars}>
+  <span class="ma-otp__field">
+  <span class="ma-otp__cells" aria-hidden="true">{Array.from({ length: n }).map(() => <i></i>)}</span>
+  <input
+    id={inputId}
+    class="ma-otp__input"
+    type="text"
+    name={name}
+    inputmode={charset === 'numeric' ? 'numeric' : 'text'}
+    autocomplete="one-time-code"
+    autocapitalize="off"
+    autocorrect="off"
+    spellcheck="false"
+    maxlength={n}
+    pattern={pattern}
+    placeholder={ph}
+    {...rest}
+  />
+  </span>
+  <svg class="ma-otp__check" viewBox="0 0 24 24" aria-hidden="true"><path d="M5 12.5l4.5 4.5L19 7" pathLength="1" /></svg>
+</span>
+
+<style is:global>
+  @layer components {
+    :where(.ma-otp) {
+      --ma-otp-font: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+      --ma-otp-h: calc(var(--ma-otp-cell) * 1.2);
+      position: relative;
+      display: inline-block;
+      vertical-align: middle;
+    }
+    :where(.ma-otp__field) {
+      /* the cells and the glyphs meet only left to right: on a right-to-left page the text would start at the far end,
+         one letter-spacing off every cell. A code is read in Latin order there too */
+      direction: ltr;
+      display: inline-grid;
+      /* the input's trailing letter-spacing would add a phantom cell: the box is exactly n cells and n − 1 gaps */
+      inline-size: calc(var(--ma-otp-n) * var(--ma-otp-cell) + (var(--ma-otp-n) - 1) * var(--ma-otp-gap));
+      block-size: var(--ma-otp-h);
+      border-radius: 0.5em;
+      overflow: clip;
+      vertical-align: middle;
+    }
+    :where(.ma-otp__label) {
+      display: block;
+      margin-block-end: 0.5em;
+      font-size: 0.875em;
+    }
+    :where(.ma-otp__cells) {
+      grid-area: 1 / 1;
+      display: flex;
+      gap: var(--ma-otp-gap);
+      pointer-events: none;
+    }
+    :where(.ma-otp__cells > i) {
+      flex: none;
+      inline-size: var(--ma-otp-cell);
+      block-size: 100%;
+      border: 1px solid var(--ma-edge);
+      border-radius: 0.45em;
+      background: var(--ma-panel);
+      transition:
+        border-color var(--ma-duration-fast) var(--ma-ease-out),
+        background-color var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-otp__input) {
+      /* the field: transparent over the cells; every glyph sits in the middle of its cell through spacing alone. One cell
+         wider than the box, which clips it: with the last character typed, the caret sits past the box's end, and an input
+         exactly as wide scrolled to show it, which moved every digit off its cell and the first out of sight */
+      grid-area: 1 / 1;
+      inline-size: calc(100% + var(--ma-otp-cell));
+      block-size: 100%;
+      margin: 0;
+      padding: 0 0 0 calc((var(--ma-otp-cell) - 1ch) / 2);
+      border: 0;
+      background: transparent;
+      color: inherit;
+      font: 500 calc(var(--ma-otp-cell) * 0.5) / 1 var(--ma-otp-font);
+      font-variant-numeric: tabular-nums;
+      letter-spacing: calc(var(--ma-otp-cell) + var(--ma-otp-gap) - 1ch);
+      text-transform: uppercase;
+      caret-color: var(--ma-ink);
+      outline: none;
+      appearance: none;
+      -webkit-appearance: none;
+    }
+    :where(.ma-otp__input)::placeholder {
+      color: color-mix(in srgb, var(--ma-ink) 28%, transparent);
+      opacity: 1;
+    }
+    :where(.ma-otp__input:disabled) {
+      cursor: not-allowed;
+      opacity: 0.6;
+    }
+    :where(.ma-otp__input:read-only) {
+      caret-color: transparent;
+    }
+    /* focus: on the field's box, outside the clip; one cell at a time is not known without a script */
+    :where(.ma-otp__field:focus-within) {
+      outline: 2px solid var(--ma-ink);
+      outline-offset: 3px;
+    }
+    :where(.ma-otp:has(.ma-otp__input:focus) .ma-otp__cells > i) {
+      border-color: color-mix(in srgb, var(--ma-ink) 45%, transparent);
+    }
+    /* full and valid: the cells go ink-edged and the check draws */
+    :where(.ma-otp:has(.ma-otp__input:valid:not(:placeholder-shown)) .ma-otp__cells > i) {
+      border-color: var(--ma-ink);
+    }
+    /* the red is a hook: on a coloured ground a caller points --ma-otp-invalid at a red that keeps 3 : 1 there */
+    :where(.ma-otp:has(.ma-otp__input:user-invalid) .ma-otp__cells > i) {
+      border-color: var(--ma-otp-invalid, #e0563f);
+      background: color-mix(in srgb, var(--ma-otp-invalid, #e0563f) 8%, var(--ma-panel));
+    }
+    :where(.ma-otp:has(.ma-otp__input:disabled) .ma-otp__cells > i),
+    :where(.ma-otp:has(.ma-otp__input:disabled) .ma-otp__cells > i) {
+      transition: none;
+      background: color-mix(in srgb, var(--ma-ink) 6%, var(--ma-panel));
+    }
+    /* the check: beside the field, never over the last digit */
+    :where(.ma-otp__check) {
+      position: absolute;
+      inset-block-start: 50%;
+      inset-inline-start: 100%;
+      inline-size: calc(var(--ma-otp-cell) * 0.55);
+      block-size: calc(var(--ma-otp-cell) * 0.55);
+      margin-inline-start: calc(var(--ma-otp-gap) * 1.2);
+      translate: 0 -50%;
+      fill: none;
+      stroke: var(--ma-ink);
+      stroke-width: 2.5;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+      pointer-events: none;
+      opacity: 0;
+    }
+    :where(.ma-otp__check path) {
+      stroke-dasharray: 1;
+      stroke-dashoffset: 1;
+      transition: stroke-dashoffset var(--ma-duration-fast) var(--ma-ease-in);
+    }
+    :where(.ma-otp:has(.ma-otp__input:valid:not(:placeholder-shown)) .ma-otp__check) {
+      opacity: 1;
+    }
+    :where(.ma-otp:has(.ma-otp__input:valid:not(:placeholder-shown)) .ma-otp__check path) {
+      stroke-dashoffset: 0;
+      transition: stroke-dashoffset var(--ma-duration) var(--ma-ease);
+    }
+    @media (forced-colors: active) {
+      :where(.ma-otp__cells > i) {
+        border-color: ButtonText;
+        background: Canvas;
+      }
+      :where(.ma-otp:has(.ma-otp__input:valid:not(:placeholder-shown)) .ma-otp__cells > i) {
+        border-color: Highlight;
+      }
+      :where(.ma-otp__check) {
+        stroke: Highlight;
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-otp__cells > i),
+      :where(.ma-otp__check path) {
+        transition: none;
+      }
+    }
+  }
+</style>

package/src/components/OtpInput.meta.ts

@@ -0,0 +1,42 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'OtpInput',
+  slug: 'otp-input',
+  title: 'OTP Input',
+  description: 'A one-time code in cells, from one native input. Paste, SMS autofill, screen readers and Backspace only work in the single-input pattern, so the cells are drawn under the field and a monospace font with a computed letter-spacing puts each glyph in the middle of its cell. Full and valid, the check draws itself; :user-invalid tints the cells only after the reader has been there. Zero JavaScript.',
+  summary: 'A one-time code input drawn as cells over one native field, so paste, SMS autofill and screen readers work.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['click'],
+  support: { baseline: 'widely', needs: ['has', 'user-invalid'], fallback: 'without :has() the cells keep their resting border and the check never shows; the input itself is unchanged' },
+  readout: '<OtpInput length={6} name="code" required>',
+  usage: `<form method="post" action="/verify">\n  <OtpInput length={6} name="code" label="Enter the code we sent" required />\n  <button type="submit">Verify</button>\n</form>\n\n<!-- letters and digits, four cells -->\n<OtpInput length={4} charset="alphanumeric" name="invite" aria-label="Invite code" />`,
+  props: [
+    { name: 'length', type: 'number', default: '6', description: 'Number of cells (1–12); maxlength and the pattern follow.' },
+    { name: 'charset', type: "'numeric' | 'alphanumeric'", default: "'numeric'", description: 'Digits only (numeric keyboard on phones, \\d pattern), or letters and digits.' },
+    { name: 'name', type: 'string', default: "'code'", description: 'Form field name; the whole code is one value.' },
+    { name: 'label', type: 'string', description: 'Visible label as <label for>. Without it, pass aria-label.' },
+    { name: 'placeholder', type: 'string', default: "'•' × length", description: 'One glyph per cell. Always set: :placeholder-shown is what tells an empty field from a full one.' },
+    { name: 'cell', type: 'string', default: "'2.5rem'", description: 'Cell width; the height (× 1.2) and the font size (× 0.5) follow.' },
+    { name: 'gap', type: 'string', default: "'0.5rem'", description: 'Space between cells.' },
+    { name: 'id', type: 'string', default: 'unique per render', description: 'The input\'s id, and the label\'s for. Unset, ma-otp- with the name and a random suffix, so two fields of the same name on one page never share an id. Yours wins.' },
+    { name: '--ma-otp-invalid', type: 'CSS colour (custom property)', default: '#e0563f', description: 'The border and tint of the cells once the reader has left the field invalid (:user-invalid). Set it in a rule or style on the component or any ancestor that knows its ground: a red that keeps 3 : 1 against it (WCAG 1.4.11).' },
+  ],
+  reducedMotion: 'The cells change border at once and the check appears without drawing.',
+  clientRouter: 'A native input; nothing to bind. The browser keeps a typed value through a navigation only where it keeps any form value.',
+  craft: [
+    'One input, not six. Six inputs need a script to move focus, split a paste, accept an SMS autofill and make Backspace step back, and they still confuse a screen reader. One field with autocomplete="one-time-code" gets all of that from the browser.',
+    'The cells are rendered boxes under a transparent field. In a monospace font every glyph advances 1ch, so a letter-spacing of cell + gap − 1ch and a start padding of (cell − 1ch) / 2 centre each character in its cell, and the caret sits at the front of the next one. Nothing is measured.',
+    'The spacing after the last glyph would draw a seventh cell: the field is exactly n cells wide and clips it, the focus ring is drawn on the field\'s box through :focus-within so the clip never cuts it, and the check sits beside the field, never over the last digit.',
+    'Full and valid is :valid:not(:placeholder-shown). That is why the placeholder attribute is always present: without it an empty, non-required field is :valid and the check would be lit from the start.',
+    'The error tint uses :user-invalid, so the cells are never red before the reader has typed or submitted. required and pattern do the validating; the browser shows the message.',
+    'The active-cell highlight is not built: it needs the value length, which is a script. Listed as a proposal.',
+    'A code pasted with spaces or dashes ("123 456", "123-456") is cut at length characters by maxlength, and the pattern then refuses it: removing separators needs a script. SMS autofill and a copied code without separators fill the field whole.',
+    'The field is direction: ltr on every page, so on a right-to-left page the glyphs still start in the first cell; the label and the check follow the page\'s direction.',
+  ],
+  related: ['check-draw', 'stateful-button', 'number-flow'],
+  intents: ['otp input', 'one time code input', 'verification code boxes', 'pin input', 'sms code input', '6 digit code input css'],
+  replaces: ['InputOTP (shadcn)', 'OTPInput (Motion Primitives)', 'react-otp-input'],
+  fixture: { props: { name: 'ma-fixture', label: 'Fixture content for OtpInput' }, expect: 'Fixture content for OtpInput' },
+} satisfies ComponentMeta;

package/src/components/PageTransition.astro

@@ -0,0 +1,121 @@
+---
+/**
+ * PageTransition — the page-level motion Astro's <ClientRouter /> makes
+ * possible and nothing else on the web can do this cheaply: wrap a region,
+ * give it a name, and it animates between pages. Zero JS of its own; the
+ * router is Astro's. Presets are keyframes in this file, resolved through
+ * the active preset's curve and duration, so page motion matches the rest.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+import type { TransitionAnimationValue, TransitionDirectionalAnimations } from 'astro';
+import { fade, slide } from 'astro:transitions';
+
+type Preset = 'fade' | 'slide' | 'rise' | 'zoom' | 'wipe' | 'scope' | 'morph' | 'none';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** transition:name — the same name on both pages pairs the elements. */
+  name?: string;
+  /** How the region enters and leaves. `morph` is the shared-element morph the browser draws itself. */
+  preset?: Preset;
+  /** Element to render. */
+  as?: HTMLTag;
+}
+
+const { name, preset = 'rise', as: Tag = 'div', class: className, ...rest } = Astro.props;
+
+const own = (kind: 'rise' | 'zoom' | 'wipe' | 'scope'): TransitionDirectionalAnimations => {
+  // scope: the old page stays in view, sinking and dimming for the whole entrance, so its exit runs on the entrance duration
+  const out = { name: `ma-vt-${kind}-out`, duration: kind === 'scope' ? 'var(--ma-duration)' : 'var(--ma-duration-fast)', easing: 'var(--ma-ease-out)', fillMode: 'both' as const };
+  const inn = { name: `ma-vt-${kind}-in`, duration: 'var(--ma-duration)', easing: 'var(--ma-ease)', fillMode: 'both' as const };
+  return { forwards: { old: out, new: inn }, backwards: { old: { ...out, name: `ma-vt-${kind}-in`, direction: 'reverse' as const }, new: { ...inn, name: `ma-vt-${kind}-out`, direction: 'reverse' as const } } };
+};
+
+const animate: TransitionAnimationValue =
+  preset === 'fade' ? fade({ duration: 'var(--ma-duration)' }) : preset === 'slide' ? slide({ duration: 'var(--ma-duration)' }) : preset === 'morph' ? 'initial' : preset === 'none' ? 'none' : own(preset);
+---
+
+{
+  name ? (
+    <Tag class:list={['ma-page', className]} transition:name={name} transition:animate={animate} {...rest}>
+      <slot />
+    </Tag>
+  ) : (
+    <Tag class:list={['ma-page', className]} transition:animate={animate} {...rest}>
+      <slot />
+    </Tag>
+  )
+}
+
+<style is:global>
+  @layer components {
+    :where(.ma-page) {
+      display: block;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      /* Astro's router already drops view-transition animations under reduced motion. */
+      :where(.ma-page) {
+        animation: none;
+      }
+    }
+  }
+
+  @keyframes ma-vt-rise-in {
+    from {
+      opacity: 0;
+      translate: 0 var(--ma-travel-section, 48px);
+    }
+  }
+  @keyframes ma-vt-rise-out {
+    to {
+      opacity: 0;
+      translate: 0 calc(var(--ma-travel-section, 48px) * -0.5);
+    }
+  }
+  @keyframes ma-vt-zoom-in {
+    from {
+      opacity: 0;
+      scale: 0.96;
+    }
+  }
+  @keyframes ma-vt-zoom-out {
+    to {
+      opacity: 0;
+      scale: 1.03;
+    }
+  }
+  @keyframes ma-vt-wipe-in {
+    from {
+      clip-path: inset(0 100% 0 0);
+    }
+    to {
+      clip-path: inset(0 0 0 0);
+    }
+  }
+  @keyframes ma-vt-wipe-out {
+    from {
+      clip-path: inset(0 0 0 0);
+    }
+    to {
+      clip-path: inset(0 0 0 100%);
+    }
+  }
+  /* scope: the old page sinks and dims behind, the new one rises as a sheet in front */
+  @keyframes ma-vt-scope-in {
+    from {
+      translate: 0 100%;
+    }
+    to {
+      translate: 0 0;
+    }
+  }
+  @keyframes ma-vt-scope-out {
+    from {
+      scale: 1;
+      opacity: 1;
+    }
+    to {
+      scale: 0.92;
+      opacity: 0.35;
+    }
+  }
+</style>

package/src/components/PageTransition.meta.ts

@@ -0,0 +1,33 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'PageTransition',
+  slug: 'page-transition',
+  title: 'Page Transition',
+  description: 'Animates a named region between pages: rise, zoom, wipe, scope, fade, slide, or the browser\'s own shared-element morph. Zero JavaScript of its own: Astro\'s <ClientRouter /> drives view transitions, and the presets are keyframes on the active motion preset\'s curve.',
+  summary: "Page transition animations for Astro's router: rise, zoom, wipe, fade, slide, or the browser's shared-element morph.",
+  category: 'transition',
+  tier: 'A',
+  trigger: ['click'],
+  support: { baseline: 'newly', needs: ['view-transitions'], fallback: 'an instant swap between pages' },
+  readout: '<PageTransition name="hero" preset="rise">',
+  usage: `---\n// both pages, same name\n---\n<PageTransition name="hero" preset="rise">\n  <h1>Page one</h1>\n</PageTransition>\n\n<PageTransition name="cover" preset="morph">\n  <img src="/cover.jpg" alt="" />\n</PageTransition>\n\n<PageTransition name="main" preset="scope">\n  <main>…</main>\n</PageTransition>`,
+  props: [
+    { name: 'name', type: 'string', description: 'transition:name. The same name on two pages pairs the regions; omit it to animate a region on its own.' },
+    { name: 'preset', type: "'rise' | 'zoom' | 'wipe' | 'scope' | 'fade' | 'slide' | 'morph' | 'none'", default: "'rise'", description: 'Entrance and exit. scope sinks and dims the old page behind while the new one rises in front, like a sheet; morph lets the browser interpolate size and position between the two pages\' elements.' },
+    { name: 'as', type: 'HTMLTag', default: "'div'", description: 'Element to render.' },
+  ],
+  reducedMotion: 'Astro\'s router skips view-transition animations; the swap is instant.',
+  clientRouter: 'This is the ClientRouter. Without it the wrapper is inert and pages load normally.',
+  craft: [
+    'Exit at --ma-duration-fast on ease-out, entrance at --ma-duration on the preset spring: the old page gets out of the way before the new one arrives.',
+    'Backwards navigation plays the same keyframes reversed, so back feels like undo.',
+    'rise travels --ma-travel-section (48 px): page-level motion needs more distance than component-level motion to register.',
+    'morph is a shared-element transition: the browser interpolates the paired region\'s size and position between the two pages, so no script measures layout.',
+    'scope keeps the old page in view for the whole entrance (it sinks to 92% and dims to a third behind the arriving sheet), so the exit runs on the entrance duration instead of the fast one; that is the depth cue. Backwards, the sheet drops and the page behind comes back up.',
+  ],
+  related: ['reveal', 'split-text'],
+  intents: ['page transition', 'view transitions astro', 'animate between pages', 'shared element transition', 'transition:name preset', 'route transition'],
+  replaces: ['framer-motion AnimatePresence page transitions', 'Barba.js', 'Swup'],
+  fixture: { expect: 'Fixture content for PageTransition' },
+} satisfies ComponentMeta;

package/src/components/Parallax.astro

@@ -0,0 +1,69 @@
+---
+/**
+ * Parallax — an element drifts at its own speed as it crosses the viewport.
+ *
+ * animation-timeline: view() binds a translate to the element's own passage
+ * through the scrollport, so the drift is exact, never lags, and costs no
+ * scroll listener. Browsers without scroll timelines show it in place.
+ */
+import type { HTMLAttributes, HTMLTag } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Element to render. */
+  as?: HTMLTag;
+  /** Drift as a fraction of the viewport, −1…1. Negative moves against the scroll. */
+  speed?: number;
+  /** Axis of travel. */
+  axis?: 'y' | 'x';
+}
+
+const { as: Tag = 'div', speed = 0.3, axis = 'y', class: className, style, ...rest } = Astro.props;
+const inline = [`--ma-px-speed:${speed}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Tag class:list={['ma-parallax', className]} data-axis={axis === 'x' ? 'x' : undefined} style={inline} {...rest}>
+  <slot />
+</Tag>
+
+<style is:global>
+  @layer components {
+    @supports (animation-timeline: view()) {
+      :where(.ma-parallax) {
+        will-change: translate;
+        animation: ma-parallax-y linear both;
+      }
+      :where(.ma-parallax[data-axis='x']) {
+        animation-name: ma-parallax-x;
+      }
+      /* Separate rule on purpose: lightningcss folds animation-timeline into
+         the shorthand, which browsers reject. Distinct selector text keeps them apart. */
+      :where(html) :where(.ma-parallax) {
+        animation-timeline: view();
+        animation-range: cover 0% cover 100%;
+      }
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-parallax) {
+        animation: none;
+        will-change: auto;
+      }
+    }
+  }
+
+  @keyframes ma-parallax-y {
+    from {
+      translate: 0 calc(var(--ma-px-speed, 0.3) * 50vh);
+    }
+    to {
+      translate: 0 calc(var(--ma-px-speed, 0.3) * -50vh);
+    }
+  }
+  @keyframes ma-parallax-x {
+    from {
+      translate: calc(var(--ma-px-speed, 0.3) * 50vw) 0;
+    }
+    to {
+      translate: calc(var(--ma-px-speed, 0.3) * -50vw) 0;
+    }
+  }
+</style>