@moonarc/core 0.1.0

package/src/components/Probe.astro

@@ -0,0 +1,84 @@
+---
+/**
+ * @internal Phase 0 packaging fixture — not part of the catalogue, and not in
+ * the registry or the docs. Exported as `@moonarc/core/internal/Probe` only
+ * because tests/consumer imports it from a real install and the site's
+ * /playground page shows the runtime's counters on it.
+ *
+ * Exercises every assumption the library rests on, so tests/consumer can
+ * verify them from a real node_modules install:
+ *   - a prop becomes a CSS custom property set inline
+ *   - global, layered styles wrapped in :where() (consumer classes must win)
+ *   - `class` and ...rest are forwarded to the root element
+ *   - a colour comes from a base.css token (three-state theme)
+ *   - the shared runtime binds every instance, survives ClientRouter
+ *     navigation, and never double-binds
+ *   - a prefers-reduced-motion branch exists
+ * Kept after Reveal (Phase 2) arrived: Reveal is catalogue, and the checks
+ * above want a fixture that never changes for product reasons.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Hover transition length in ms. */
+  duration?: number;
+}
+
+const { duration = 300, class: className, style, ...rest } = Astro.props;
+const inlineStyle = [`--ma-probe-duration:${duration}ms`, typeof style === 'string' ? style : '']
+  .filter(Boolean)
+  .join(';');
+---
+
+<div class:list={['ma-probe', className]} data-ma-probe style={inlineStyle} {...rest}>
+  <slot />
+</div>
+
+<style is:global>
+  /*
+   * Global on purpose. Astro's scoping prepends [data-astro-cid] *outside*
+   * :where(), which raises specificity to (0,1,0); the .ma- namespace already
+   * gives isolation, and the `components` layer + :where() give zero weight so
+   * consumer utilities and plain classes always win.
+   */
+  @layer components {
+    :where(.ma-probe) {
+      display: block;
+      padding: 1rem 1.25rem;
+      border: 1px solid var(--ma-edge);
+      border-radius: 0.75rem;
+      transform: translateY(0);
+      transition: transform var(--ma-probe-duration) var(--ma-ease-out);
+    }
+    :where(.ma-probe.is-active) {
+      transform: translateY(-2px);
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-probe) {
+        transition-duration: 0.01ms;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount, onPage } from '../lib/runtime';
+
+  // Test instrumentation: tests/consumer reads window.__maProbe after navigation.
+  type Stats = { setups: number; teardowns: number; bound: number };
+  const w = window as unknown as { __maProbe?: Stats };
+  const stats: Stats = (w.__maProbe ??= { setups: 0, teardowns: 0, bound: 0 });
+
+  onPage(() => {
+    stats.setups++;
+    return () => {
+      stats.teardowns++;
+    };
+  });
+
+  onMount<HTMLElement>('[data-ma-probe]', (el, { signal }) => {
+    el.dataset.maBound = String(++stats.bound);
+    el.addEventListener('pointerenter', () => el.classList.add('is-active'), { signal });
+    el.addEventListener('pointerleave', () => el.classList.remove('is-active'), { signal });
+  });
+</script>

package/src/components/Progress.astro

@@ -0,0 +1,165 @@
+---
+/**
+ * Progress — a bar that fills to its value when it scrolls into view, with
+ * the number counting alongside; or a ring, with the number in the middle.
+ * No script of its own: Reveal is the trigger, CountUp the number; the bar
+ * is one translate transition and the ring one dash offset, both on the
+ * active preset's curve. The server HTML already shows the final state.
+ */
+import type { HTMLAttributes } from 'astro/types';
+import Reveal from './Reveal.astro';
+import CountUp from './CountUp.astro';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Value, 0–max. */
+  value: number;
+  /** Maximum. */
+  max?: number;
+  /** Visible label before the number. */
+  label?: string;
+  /** Show the number. */
+  showValue?: boolean;
+  /** Suffix after the number. */
+  suffix?: string;
+  /** Duration in ms. */
+  duration?: number;
+  /** Bar thickness, any CSS length. */
+  height?: string;
+  /** Fill colour. */
+  color?: string;
+  /** A bar, or a ring with the number in the middle. */
+  shape?: 'bar' | 'ring';
+  /** Ring diameter, any CSS length. */
+  size?: string;
+}
+
+const { value, max = 100, label, showValue = true, suffix = '%', duration = 1400, height = '0.5rem', color = 'currentColor', shape = 'bar', size = '6rem', class: className, style, ...rest } = Astro.props;
+const pct = Math.max(0, Math.min(100, (value / max) * 100));
+const ring = shape === 'ring';
+// the caller's style joins the variables: passed on through {...rest} it replaced them, and the bar stayed empty
+const vars = [`--ma-prog:${pct / 100};--ma-prog-dur:${duration}ms;--ma-prog-h:${height};--ma-prog-color:${color}${ring ? `;--ma-prog-size:${size}` : ''}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+---
+
+<Reveal
+  as="div"
+  from="none"
+  duration={300}
+  class={['ma-progress', ring && 'ma-progress--ring', className].filter(Boolean).join(' ')}
+  role="progressbar"
+  aria-valuenow={value}
+  aria-valuemin={0}
+  aria-valuemax={max}
+  aria-label={label}
+  style={vars}
+  {...rest}
+>
+  {ring ? (
+    <>
+      <span class="ma-progress__ring">
+        <svg viewBox="0 0 100 100" aria-hidden="true">
+          <circle class="ma-progress__ring-track" cx="50" cy="50" r="44" />
+          <circle class="ma-progress__ring-fill" cx="50" cy="50" r="44" pathLength="1" />
+        </svg>
+        {showValue && <span class="ma-progress__center"><CountUp to={value} suffix={suffix} duration={duration} decimals={Number.isInteger(value) ? 0 : 1} class="ma-progress__value" /></span>}
+      </span>
+      {label && <span class="ma-progress__label">{label}</span>}
+    </>
+  ) : (
+    <>
+      {(label || showValue) && (
+        <div class="ma-progress__head">
+          {label && <span class="ma-progress__label">{label}</span>}
+          {showValue && <CountUp to={value} suffix={suffix} duration={duration} decimals={Number.isInteger(value) ? 0 : 1} class="ma-progress__value" />}
+        </div>
+      )}
+      <span class="ma-progress__track"><span class="ma-progress__fill"></span></span>
+    </>
+  )}
+</Reveal>
+
+<style is:global>
+  @layer components {
+    :where(.ma-progress__head) {
+      display: flex;
+      justify-content: space-between;
+      gap: 1rem;
+      margin-bottom: 0.5rem;
+      font-size: 0.875rem;
+    }
+    :where(.ma-progress__value) {
+      font-variant-numeric: tabular-nums;
+    }
+    :where(.ma-progress__track) {
+      display: block;
+      height: var(--ma-prog-h, 0.5rem);
+      border-radius: 999px;
+      background: var(--ma-edge);
+      overflow: hidden;
+    }
+    /* the fill is a full-length rounded bar slid in from the left, clipped by the track: its end stays a half circle at
+       any value, where a horizontal scale squashed it flat towards zero */
+    :where(.ma-progress__fill) {
+      display: block;
+      height: 100%;
+      border-radius: inherit;
+      background: var(--ma-prog-color, currentColor);
+      translate: calc((var(--ma-prog, 0) - 1) * 100%) 0;
+      transition: translate var(--ma-prog-dur, 1400ms) var(--ma-ease-out);
+    }
+    :where([data-ma-js] .ma-progress:not(.ma-in) .ma-progress__fill) {
+      translate: -100% 0;
+      transition: none;
+    }
+    /* ring: one dash offset on a normalised circle, the number in the middle */
+    :where(.ma-progress--ring) {
+      display: inline-grid;
+      justify-items: center;
+      gap: 0.5rem;
+    }
+    :where(.ma-progress__ring) {
+      position: relative;
+      display: grid;
+      place-items: center;
+      width: var(--ma-prog-size, 6rem);
+      height: var(--ma-prog-size, 6rem);
+    }
+    :where(.ma-progress__ring > svg) {
+      grid-area: 1 / 1;
+      width: 100%;
+      height: 100%;
+      rotate: -90deg;
+    }
+    :where(.ma-progress__ring-track),
+    :where(.ma-progress__ring-fill) {
+      fill: none;
+      stroke-width: 8;
+    }
+    :where(.ma-progress__ring-track) {
+      stroke: var(--ma-edge);
+    }
+    :where(.ma-progress__ring-fill) {
+      stroke: var(--ma-prog-color, currentColor);
+      stroke-linecap: round;
+      stroke-dasharray: 1;
+      /* × 1px: Firefox rejects a unitless calc() here; with pathLength="1" a px is a path unit */
+      stroke-dashoffset: calc((1 - var(--ma-prog, 0)) * 1px);
+      transition: stroke-dashoffset var(--ma-prog-dur, 1400ms) var(--ma-ease-out);
+    }
+    :where([data-ma-js] .ma-progress:not(.ma-in) .ma-progress__ring-fill) {
+      stroke-dashoffset: 1;
+      transition: none;
+    }
+    :where(.ma-progress__center) {
+      grid-area: 1 / 1;
+      font-size: calc(var(--ma-prog-size, 6rem) / 4.5);
+      font-weight: 600;
+      letter-spacing: -0.02em;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-progress__fill),
+      :where(.ma-progress__ring-fill) {
+        transition: none;
+      }
+    }
+  }
+</style>

package/src/components/Progress.meta.ts

@@ -0,0 +1,40 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Progress',
+  slug: 'progress',
+  title: 'Progress',
+  description: 'A bar that fills to its value when it scrolls into view, with the number counting up beside it, or a ring with the number in the middle. No script of its own: Reveal is the trigger and CountUp the number; the fill is one translate transition, the ring one dash offset. The server HTML already shows the final state.',
+  summary: 'A progress bar or ring that fills to its value when it scrolls into view, with the number counting up beside it.',
+  category: 'loading',
+  tier: 'A',
+  trigger: ['scroll'],
+  support: { baseline: 'newly', needs: ['property', 'counter-style'], fallback: 'the bar fills; the number appears without counting' },
+  readout: '<Progress value={62}>',
+  usage: `<Progress value={62} label="Profile complete" />\n<Progress value={3.2} max={5} suffix=" GB" label="Storage used" />\n<Progress value={78} shape="ring" size="7rem" label="Goal reached" />`,
+  props: [
+    { name: 'value', type: 'number', description: 'Value, 0–max.' },
+    { name: 'max', type: 'number', default: '100', description: 'Maximum.' },
+    { name: 'label', type: 'string', description: 'Label before the number; also the accessible name.' },
+    { name: 'showValue', type: 'boolean', default: 'true', description: 'Show the counting number.' },
+    { name: 'suffix', type: 'string', default: "'%'", description: 'Suffix after the number.' },
+    { name: 'duration', type: 'number', default: '1400', description: 'Duration in ms, shared by the fill and the count.' },
+    { name: 'height', type: 'string', default: "'0.5rem'", description: 'Bar thickness.' },
+    { name: 'color', type: 'string', default: "'currentColor'", description: 'Fill colour.' },
+    { name: 'shape', type: "'bar' | 'ring'", default: "'bar'", description: 'A bar, or an SVG ring that fills clockwise from the top with the number in the middle.' },
+    { name: 'size', type: 'string', default: "'6rem'", description: 'Ring diameter.' },
+  ],
+  reducedMotion: 'The bar is full at its value and the number is shown; nothing animates.',
+  clientRouter: 'Inherits Reveal: rebinds after every navigation.',
+  craft: [
+    'A progressbar needs a name: label is the visible one; without it, pass aria-label or aria-labelledby, or aria-hidden="true" when the same number already sits beside the bar as text (a table cell, a stat).',
+    'Fill and count share one duration and both ease out, so the number lands the instant the bar stops.',
+    'The fill is a full-length rounded bar that translate slides in from the left, clipped by the track: one compositor property, and its end stays a half circle at any value. A horizontal scale would squash that end towards flat as the value nears zero.',
+    'role="progressbar" with aria-valuenow; the bar is static information to assistive tech, the motion is for the eye.',
+    'The ring is a circle with pathLength="1", so the fill is one dash offset from 1 to 1 − value whatever the diameter; it starts at twelve o\'clock (rotate: −90°) and the number sits in the same grid cell.',
+  ],
+  related: ['count-up', 'skeleton', 'spinner'],
+  intents: ['progress bar', 'animated progress bar on scroll', 'skill bar', 'percentage bar animation'],
+  replaces: ['Progress (shadcn)', 'animated skill bars'],
+  fixture: { props: { value: 62, label: 'Fixture content for Progress' }, expect: 'Fixture content for Progress' },
+} satisfies ComponentMeta;

package/src/components/ProgressiveBlur.astro

@@ -0,0 +1,95 @@
+---
+/**
+ * ProgressiveBlur — an edge that blurs what scrolls under it, more the
+ * closer it gets. `layers` absolutely positioned bands, each with a
+ * backdrop blur twice the previous one's and a mask that keeps it to its
+ * own slice of the edge, so the blur ramps instead of stepping. Nothing
+ * animates; the content moving under it is the motion. Without
+ * backdrop-filter the edge fades to a colour instead. Sits on the given
+ * edge of its positioned parent: put it beside the scroller, in a shared
+ * positioned wrapper, since inside the scroller it would scroll away.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** Which edge the blur sits on. */
+  direction?: 'top' | 'bottom' | 'left' | 'right';
+  /** Bands; more is smoother and dearer to paint. */
+  layers?: number;
+  /** Blur of the outermost band in px. */
+  strength?: number;
+  /** Depth of the blurred edge, any CSS length. */
+  size?: string;
+  /** Colour the edge fades to where backdrop-filter is missing (and, faintly, on top of the blur). */
+  color?: string;
+}
+
+const { direction = 'bottom', layers = 5, strength = 12, size = '6rem', color = 'var(--ma-panel)', class: className, style, ...rest } = Astro.props;
+const n = Math.max(2, Math.min(8, Math.round(layers)));
+const inline = [`--ma-pblur-n:${n}`, `--ma-pblur-strength:${strength}px`, `--ma-pblur-size:${size}`, `--ma-pblur-color:${color}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+// each band: blur = strength / 2^(n-1-i); mask keeps it between (i-1)/n and (i+1)/n of the depth, solid in the middle
+const bands = Array.from({ length: n }, (_, i) => ({ i, blur: strength / 2 ** (n - 1 - i), a: Math.max(0, ((i - 1) / n) * 100), b: (i / n) * 100, c: Math.min(100, ((i + 1) / n) * 100) }));
+---
+
+<div class:list={['ma-pblur', className]} aria-hidden="true" data-direction={direction} style={inline} {...rest}>
+  {bands.map((b) => <i style={`--ma-pblur-b:${b.blur}px;--ma-pblur-m0:${b.a}%;--ma-pblur-m1:${b.b}%;--ma-pblur-m2:${b.c}%`}></i>)}
+</div>
+
+<style is:global>
+  @layer components {
+    :where(.ma-pblur) {
+      position: absolute;
+      inset: auto 0 0;
+      height: var(--ma-pblur-size, 6rem);
+      pointer-events: none;
+      /* the mask runs from the inside edge (0 %) to the outside edge (100 %) */
+      --ma-pblur-to: to bottom;
+    }
+    :where(.ma-pblur[data-direction='top']) {
+      inset: 0 0 auto;
+      --ma-pblur-to: to top;
+    }
+    :where(.ma-pblur[data-direction='left']) {
+      inset: 0 auto 0 0;
+      width: var(--ma-pblur-size, 6rem);
+      height: auto;
+      --ma-pblur-to: to left;
+    }
+    :where(.ma-pblur[data-direction='right']) {
+      inset: 0 0 0 auto;
+      width: var(--ma-pblur-size, 6rem);
+      height: auto;
+      --ma-pblur-to: to right;
+    }
+    :where(.ma-pblur > i) {
+      position: absolute;
+      inset: 0;
+      -webkit-backdrop-filter: blur(var(--ma-pblur-b));
+      backdrop-filter: blur(var(--ma-pblur-b));
+      -webkit-mask-image: linear-gradient(var(--ma-pblur-to), transparent var(--ma-pblur-m0), #000 var(--ma-pblur-m1), #000 var(--ma-pblur-m2), transparent calc(var(--ma-pblur-m2) + (var(--ma-pblur-m2) - var(--ma-pblur-m1))));
+      mask-image: linear-gradient(var(--ma-pblur-to), transparent var(--ma-pblur-m0), #000 var(--ma-pblur-m1), #000 var(--ma-pblur-m2), transparent calc(var(--ma-pblur-m2) + (var(--ma-pblur-m2) - var(--ma-pblur-m1))));
+    }
+    /* the last band also tints toward the colour so the edge lands on the panel instead of a blurred cut */
+    :where(.ma-pblur > i:last-child) {
+      background: linear-gradient(var(--ma-pblur-to), transparent, color-mix(in srgb, var(--ma-pblur-color, var(--ma-panel)) 60%, transparent));
+    }
+    /* no backdrop-filter: one gradient to the colour */
+    @supports not (backdrop-filter: blur(1px)) {
+      :where(.ma-pblur > i) {
+        display: none;
+      }
+      :where(.ma-pblur > i:last-child) {
+        display: block;
+        mask-image: none;
+        -webkit-mask-image: none;
+        background: linear-gradient(var(--ma-pblur-to), transparent, var(--ma-pblur-color, var(--ma-panel)));
+      }
+    }
+    /* nothing moves here; the branch is the same edge — stated so the audit sees it */
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-pblur) {
+        pointer-events: none;
+      }
+    }
+  }
+</style>

package/src/components/ProgressiveBlur.meta.ts

@@ -0,0 +1,36 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'ProgressiveBlur',
+  slug: 'progressive-blur',
+  title: 'Progressive Blur',
+  description: 'An edge that blurs what scrolls under it, more the closer it gets: a few bands, each with a backdrop blur twice the last and a mask that keeps it to its own slice, so the blur ramps instead of stepping. Nothing animates: the content moving beneath is the motion. Without backdrop-filter the edge fades to a colour. Zero JS.',
+  summary: 'A progressive blur at an edge: content that scrolls under it blurs more the closer it gets.',
+  category: 'background',
+  tier: 'A',
+  trigger: ['always'],
+  support: { baseline: 'widely', needs: ['backdrop-filter', 'mask-image'], fallback: 'a gradient to the panel colour instead of a blur' },
+  readout: '<ProgressiveBlur direction="bottom" layers={5}>',
+  usage: `<!-- the blur is a sibling of the scroller, inside a positioned wrapper: inside the scroller it would scroll away -->\n<div class="relative">\n  <div class="h-80 overflow-y-auto">\n    <ul>…</ul>\n  </div>\n  <ProgressiveBlur direction="bottom" size="5rem" />\n</div>`,
+  props: [
+    { name: 'direction', type: "'top' | 'bottom' | 'left' | 'right'", default: "'bottom'", description: 'Which edge the blur sits on.' },
+    { name: 'layers', type: 'number', default: '5', description: 'Bands, 2–8; more is smoother and costs more paint, because each band is a backdrop pass.' },
+    { name: 'strength', type: 'number', default: '12', description: 'Blur of the outermost band in px; each band inward is half.' },
+    { name: 'size', type: 'string', default: "'6rem'", description: 'Depth of the blurred edge, any CSS length.' },
+    { name: 'color', type: 'string', default: 'var(--ma-panel)', description: 'The colour the edge lands on: a faint tint over the last band, the whole fade where backdrop-filter is missing.' },
+  ],
+  reducedMotion: 'Unchanged. The component has no motion; what moves is the page.',
+  clientRouter: 'CSS-only; nothing to rebind.',
+  craft: [
+    'Blur doubles per band (strength / 2ⁿ inward): a linear ramp of blur radii looks stepped because the eye reads blur logarithmically.',
+    'Each band\'s mask overlaps its neighbours by one slice, so the transitions between blur radii are cross-fades rather than seams.',
+    'Five bands by default: measured on the catalogue, more bands raised paint cost without a visible gain at 12 px.',
+    'The last band also tints toward the panel colour so the edge lands on the surface instead of a blurred cut; the no-backdrop fallback is that same gradient at full strength.',
+    'pointer-events: none, so the content under the edge stays scrollable and clickable.',
+    'It is absolutely positioned on its parent, so it goes beside the scroller, not in it: an absolute child of a scroll container scrolls with the content and the edge would leave with the first rows.',
+  ],
+  related: ['marquee', 'footer-reveal', 'skeleton'],
+  intents: ['progressive blur edge', 'gradient blur bottom of list', 'blurred fade scroll edge', 'apple style progressive blur', 'backdrop blur gradient css'],
+  replaces: ['ProgressiveBlur (Magic UI)', 'ProgressiveBlur (Motion Primitives)'],
+  fixture: { expect: 'class="ma-pblur"' },
+} satisfies ComponentMeta;