@moonarc/core 0.1.0

package/src/components/Drawer.astro

@@ -0,0 +1,196 @@
+---
+/**
+ * Drawer — a bottom sheet you can drag closed.
+ *
+ * A native <dialog> for the top layer, focus and Escape; the invoker
+ * command opens it and @starting-style / allow-discrete animate it. The
+ * script adds one thing CSS cannot: the sheet follows the finger, and on
+ * release either springs back (preset curve) or leaves — by distance or
+ * by velocity — with the transition interrupted mid-flight if you grab it.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'dialog'> {
+  /** Dialog id; the trigger points at it. */
+  id: string;
+  /** Trigger label; or use the `trigger` slot. */
+  label?: string;
+  /** Sheet height, any CSS length. */
+  height?: string;
+  /** Fraction of the height that must be dragged to dismiss. */
+  threshold?: number;
+  /** Add the inline click handler for browsers without invoker commands. */
+  polyfill?: boolean;
+}
+
+const { id, label = 'Open', height = 'auto', threshold = 0.35, polyfill = false, class: className, style, ...rest } = Astro.props;
+const inline = [`--ma-drawer-h:${height}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+const triggerAttrs = { command: 'show-modal', commandfor: id };
+const dialogAttrs = { closedby: 'any' as const };
+---
+
+{Astro.slots.has('trigger') ? <slot name="trigger" /> : <button type="button" class="ma-drawer__trigger" {...triggerAttrs}>{label}</button>}
+<dialog id={id} class:list={['ma-drawer', className]} data-ma-drawer data-threshold={threshold} style={inline} {...dialogAttrs} {...rest}>
+  <div class="ma-drawer__sheet">
+    <div class="ma-drawer__handle" aria-hidden="true"></div>
+    <div class="ma-drawer__body">
+      <slot />
+    </div>
+  </div>
+</dialog>
+{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-drawer) {
+      inset: auto 0 0;
+      margin: 0 auto;
+      width: 100%;
+      max-width: 40rem;
+      max-height: 90dvh;
+      height: var(--ma-drawer-h, auto);
+      border: 0;
+      padding: 0;
+      background: transparent;
+      color: inherit;
+      overflow: visible;
+      /* --ma-drag: live pointer offset written by the script */
+      translate: 0 var(--ma-drag, 0px);
+      transition:
+        translate var(--ma-duration-fast) var(--ma-ease-in),
+        display var(--ma-duration-fast) allow-discrete,
+        overlay var(--ma-duration-fast) allow-discrete;
+    }
+    :where(.ma-drawer:not([open])) {
+      translate: 0 100%;
+    }
+    :where(.ma-drawer[open]) {
+      transition-duration: var(--ma-duration);
+      transition-timing-function: var(--ma-ease-drawer);
+    }
+    :where(.ma-drawer[data-dragging]) {
+      transition: none;
+    }
+    @starting-style {
+      :where(.ma-drawer[open]) {
+        translate: 0 100%;
+      }
+    }
+    :where(.ma-drawer)::backdrop {
+      background: var(--ma-scrim);
+      opacity: 0;
+      transition:
+        opacity var(--ma-duration-fast) var(--ma-ease-out),
+        display var(--ma-duration-fast) allow-discrete,
+        overlay var(--ma-duration-fast) allow-discrete;
+    }
+    :where(.ma-drawer[open])::backdrop {
+      opacity: 1;
+      transition-duration: var(--ma-duration);
+    }
+    @starting-style {
+      :where(.ma-drawer[open])::backdrop {
+        opacity: 0;
+      }
+    }
+    :where(.ma-drawer__sheet) {
+      display: grid;
+      grid-template-rows: auto 1fr;
+      max-height: 90dvh;
+      border-radius: 1.25rem 1.25rem 0 0;
+      background: var(--ma-panel);
+      border: 1px solid var(--ma-edge);
+      border-bottom: 0;
+      box-shadow: 0 -24px 64px -32px rgb(0 0 0 / 0.5);
+      touch-action: none;
+    }
+    :where(.ma-drawer__handle) {
+      width: 2.5rem;
+      height: 0.3rem;
+      margin: 0.75rem auto 0.25rem;
+      border-radius: 999px;
+      background: var(--ma-edge);
+      cursor: grab;
+    }
+    :where(.ma-drawer__body) {
+      padding: 1rem 1.5rem 1.5rem;
+      overflow: auto;
+      touch-action: pan-y;
+    }
+    :where(.ma-drawer__trigger) {
+      cursor: pointer;
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-drawer),
+      :where(.ma-drawer[open]),
+      :where(.ma-drawer)::backdrop {
+        transition-duration: var(--ma-duration-fast);
+        transition-timing-function: linear;
+      }
+    }
+  }
+</style>
+
+<script>
+  import { onMount } from '../lib/runtime';
+
+  onMount<HTMLDialogElement>('[data-ma-drawer]', (dialog, { signal }) => {
+    const sheet = dialog.querySelector<HTMLElement>('.ma-drawer__sheet');
+    const body = dialog.querySelector<HTMLElement>('.ma-drawer__body');
+    if (!sheet || !body) return;
+    const threshold = Number(dialog.dataset.threshold ?? 0.35);
+    let startY = 0;
+    let lastY = 0;
+    let lastT = 0;
+    let v = 0;
+    // 0 idle, 1 pressed, 2 dragging
+    let state = 0;
+
+    sheet.addEventListener(
+      'pointerdown',
+      (e) => {
+        // a scrolled body scrolls; only a body at the top hands the gesture to the sheet
+        if (body.contains(e.target as Node) && body.scrollTop > 0) return;
+        state = 1;
+        startY = lastY = e.clientY;
+        lastT = e.timeStamp;
+        v = 0;
+      },
+      { signal },
+    );
+    sheet.addEventListener(
+      'pointermove',
+      (e) => {
+        if (!state) return;
+        const dy = Math.max(0, e.clientY - startY);
+        // a press is a click until it travels 6 px: only then does the sheet take the pointer, so a button, a link or a
+        // checkbox inside keeps its click (captured on pointerdown, the click went to the sheet)
+        if (state < 2) {
+          if (dy < 6) return;
+          state = 2;
+          dialog.dataset.dragging = '';
+          sheet.setPointerCapture(e.pointerId);
+        }
+        const dt = e.timeStamp - lastT || 1;
+        v = (e.clientY - lastY) / dt; // px per ms, positive = downward
+        lastY = e.clientY;
+        lastT = e.timeStamp;
+        dialog.style.setProperty('--ma-drag', `${dy}px`);
+      },
+      { signal },
+    );
+    const release = (e: PointerEvent) => {
+      const was = state;
+      state = 0;
+      if (was < 2) return;
+      delete dialog.dataset.dragging;
+      const dy = Math.max(0, e.clientY - startY);
+      const h = dialog.getBoundingClientRect().height || 1;
+      dialog.style.removeProperty('--ma-drag');
+      if (dy / h > threshold || v > 0.6) dialog.close();
+    };
+    // on the dialog: a press let go over the backdrop before it became a drag ends there, uncaptured
+    dialog.addEventListener('pointerup', release, { signal });
+    dialog.addEventListener('pointercancel', release, { signal });
+  });
+</script>

package/src/components/Drawer.meta.ts

@@ -0,0 +1,35 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'Drawer',
+  slug: 'drawer',
+  title: 'Drawer',
+  description: 'A bottom sheet that slides up over a scrim and can be dragged closed: it follows the finger, and on release springs back or leaves depending on distance and velocity, interruptible mid-flight. A native <dialog> does the top layer, focus and Escape; the script is only the gesture.',
+  summary: 'A bottom sheet that slides up and can be dragged closed. On release it springs back or leaves, by distance and speed.',
+  category: 'ui',
+  tier: 'C',
+  trigger: ['click', 'pointer'],
+  support: { baseline: 'newly', needs: ['command', 'starting-style', 'allow-discrete', 'dialog'], fallback: 'without invoker commands the trigger needs polyfill; without closedby (Safari) a tap on the scrim does nothing, and the drag and Escape still close the sheet' },
+  readout: '<Drawer threshold={0.35}>',
+  usage: `<Drawer id="filters" label="Filters" height="60dvh">\n  <h2>Filters</h2>\n  <p>Drag down to dismiss.</p>\n</Drawer>`,
+  props: [
+    { name: 'id', type: 'string', description: 'Dialog id; the trigger points at it.' },
+    { name: 'label', type: 'string', default: "'Open'", description: 'Trigger label. Use the trigger slot for custom markup (give it command="show-modal" commandfor={id}).' },
+    { name: 'height', type: 'string', default: "'auto'", description: 'Sheet height, up to 90 dvh.' },
+    { name: 'threshold', type: 'number', default: '0.35', description: 'Fraction of the height that must be dragged to dismiss; a fast flick dismisses regardless.' },
+    { name: 'polyfill', type: 'boolean', default: 'false', description: 'Inline a click handler (403 B raw) for browsers without invoker commands. Document-level: one per page is enough.' },
+  ],
+  reducedMotion: 'Opens and closes with a 150 ms linear slide; dragging still works because it is direct manipulation.',
+  clientRouter: 'Bound through the shared runtime; pointer listeners are aborted before the swap and a sheet open during navigation closes with the page.',
+  craft: [
+    'While dragging, transition: none, so the sheet stays under the finger. On release the transition returns, so the spring-back is the drawer curve.',
+    'Two ways out: 35% of the height, or 0.6 px/ms. A short fast flick should close; a long slow drag that stops short should not.',
+    'The body scrolls; the sheet only takes the gesture when the body is at its top, so scrolling content never accidentally dismisses.',
+    'A press becomes a drag after 6 px of travel, and only then does the sheet capture the pointer: until then it is a click, so a button, a link or a checkbox inside the sheet works with a mouse, a pen or a finger.',
+    'Exit is ease-in at the fast duration: things leaving accelerate away.',
+  ],
+  related: ['dialog', 'popover', 'toast'],
+  intents: ['bottom sheet', 'drawer', 'draggable sheet', 'swipe to dismiss', 'mobile drawer astro', 'vaul alternative'],
+  replaces: ['Vaul', 'Drawer (shadcn)', 'react-spring-bottom-sheet'],
+  fixture: { props: { id: 'ma-fixture-drawer', label: 'Fixture content for Drawer' }, expect: 'Fixture content for Drawer' },
+} satisfies ComponentMeta;

package/src/components/DynamicIsland.astro

@@ -0,0 +1,122 @@
+---
+/**
+ * DynamicIsland — a black pill that changes shape with its state, zero
+ * JS. `auto → auto` never animates, so every state declares its size:
+ * `states: [{ name, width, height, radius }]` in rem. The active state is
+ * `data-state` on the element — set by the prop or by your script — and
+ * because the names come from props, one small inline style block is
+ * rendered per instance (an id from a hash of the states) that maps each name to its
+ * three lengths and shows the matching child. Width, height and radius
+ * transition on the preset spring; the old content blurs and fades on the
+ * fast token, the new one arrives after it. Children carry `data-state`;
+ * the first state is the default.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+interface State {
+  name: string;
+  /** rem */
+  width: number;
+  /** rem */
+  height: number;
+  /** rem; default half the height (a pill). */
+  radius?: number;
+}
+
+interface Props extends HTMLAttributes<'div'> {
+  states: State[];
+  /** Active state; default the first. */
+  state?: string;
+  /** Element id — deterministic from the states when omitted; pass one for two identical islands on a page. */
+  id?: string;
+  /** Announce content changes (aria-live="polite" on the body). */
+  live?: boolean;
+  /** Island colour; the island is black by nature, not the ink token. */
+  color?: string;
+  textColor?: string;
+}
+
+const { states, state, id, live = false, color, textColor, class: className, style, ...rest } = Astro.props;
+const first = states[0] ?? { name: 'idle', width: 7.5, height: 2.25 };
+// djb2 over the states: the same states give the same id on every build, so a visual test is stable
+const hash = (s: string) => {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+  return h.toString(36);
+};
+const islandId = id ?? `ma-island-${hash(JSON.stringify(states))}`;
+const active = states.some((s) => s.name === state) ? state! : first.name;
+const vars = [color && `--ma-di-bg:${color}`, textColor && `--ma-di-fg:${textColor}`, typeof style === 'string' ? style : ''].filter(Boolean).join(';');
+// both come from props and are printed into CSS: the id as an identifier (CSS.escape's rules: an id may start with a
+// digit or hold punctuation, and `#2fa` alone is not a selector), each name as a quoted string. `<` is escaped in both,
+// so no value can close the style element it is printed in.
+const hex = (c: string) => `\\${c.codePointAt(0)!.toString(16)} `;
+const ident = (v: string) => v.replace(/^-?\d|[\0-\x1f\x7f]|[^\w\u0080-\uffff-]/g, (c) => (c.length > 1 ? c[0] + hex(c[1]!) : /[\d\0-\x1f\x7f]/.test(c) ? hex(c) : `\\${c}`));
+const str = (v: string) => `"${v.replace(/["\\]/g, '\\$&').replace(/[\n\r\f<]/g, hex)}"`;
+const sel = `#${ident(islandId)}`;
+const rule = (s: State) => {
+  const r = s.radius ?? s.height / 2;
+  const n = str(s.name);
+  return `${sel}[data-state=${n}]{--ma-di-w:${s.width}rem;--ma-di-h:${s.height}rem;--ma-di-r:${r}rem}${sel}[data-state=${n}]>.ma-island__body>[data-state=${n}]{opacity:1;filter:none;scale:1;pointer-events:auto;transition-delay:var(--ma-duration-fast)}`;
+};
+const css = states.map(rule).join('');
+---
+
+<style is:global>
+  @layer components {
+    :where(.ma-island) {
+      --ma-di-w: 7.5rem;
+      --ma-di-h: 2.25rem;
+      --ma-di-r: 1.125rem;
+      display: grid;
+      place-items: stretch;
+      inline-size: var(--ma-di-w);
+      block-size: var(--ma-di-h);
+      border-radius: var(--ma-di-r);
+      background: var(--ma-di-bg, #0a0a0b);
+      color: var(--ma-di-fg, #fff);
+      overflow: clip;
+      box-shadow: 0 8px 30px -12px rgb(0 0 0 / 0.6);
+      transition:
+        inline-size var(--ma-duration) var(--ma-ease),
+        block-size var(--ma-duration) var(--ma-ease),
+        border-radius var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-island__body) {
+      display: grid;
+      inline-size: 100%;
+      block-size: 100%;
+      min-inline-size: 0;
+      min-block-size: 0;
+    }
+    /* every state's content sits in the same cell; the active one is picked by the instance's own rules */
+    :where(.ma-island__body > [data-state]) {
+      grid-area: 1 / 1;
+      display: flex;
+      align-items: center;
+      gap: 0.6em;
+      min-inline-size: 0;
+      opacity: 0;
+      filter: blur(4px);
+      scale: 0.92;
+      pointer-events: none;
+      transition:
+        opacity var(--ma-duration-fast) var(--ma-ease-out),
+        filter var(--ma-duration-fast) var(--ma-ease-out),
+        scale var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    @media (prefers-reduced-motion: reduce) {
+      :where(.ma-island),
+      :where(.ma-island__body > [data-state]) {
+        transition: none;
+        filter: none;
+        scale: 1;
+      }
+    }
+  }
+</style>
+
+<div class:list={['ma-island', className]} id={islandId} data-state={active} style={vars || undefined} {...rest}>
+  <div class="ma-island__body" aria-live={live ? 'polite' : undefined}><slot /></div>
+</div>
+<style is:inline set:html={css}></style>

package/src/components/DynamicIsland.meta.ts

@@ -0,0 +1,35 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'DynamicIsland',
+  slug: 'dynamic-island',
+  title: 'Dynamic Island',
+  description: 'A black pill that changes shape with its state. auto → auto never animates, so every state declares its width, height and radius in rem; the active one is data-state on the element, set by your script, and a small style block rendered per instance maps each name to its lengths and shows the matching child. The shape transitions on the preset spring; the old content blurs out on the fast token and the new one arrives after it. Zero JavaScript.',
+  summary: "A black pill that changes shape with its state, like the iPhone's Dynamic Island, blurring its content out and in.",
+  category: 'ui',
+  tier: 'A',
+  trigger: ['click'],
+  support: { baseline: 'widely', needs: [] },
+  readout: '<DynamicIsland states={states} state="music">',
+  usage: `---\nconst states = [\n  { name: 'idle', width: 7.5, height: 2.25 },\n  { name: 'music', width: 15, height: 3.5 },\n  { name: 'call', width: 14, height: 3.25 },\n  { name: 'timer', width: 11, height: 5, radius: 1.5 },\n];\n---\n<DynamicIsland id="island" states={states} state="idle" live>\n  <span data-state="idle"><i class="dot" /></span>\n  <span data-state="music"><img src="/art.jpg" alt="" /> Now playing · Orbit</span>\n  <span data-state="call">Ari · 00:42</span>\n  <span data-state="timer">12:00</span>\n</DynamicIsland>\n\n<script>\n  // your code drives it: one attribute\n  document.getElementById('island').dataset.state = 'music';\n</script>`,
+  props: [
+    { name: 'states', type: '{ name, width, height, radius? }[]', description: 'Every state and its size in rem; radius defaults to half the height. The first is the default.' },
+    { name: 'state', type: 'string', default: 'states[0].name', description: 'The active state, as data-state on the element.' },
+    { name: 'id', type: 'string', default: 'a hash of the states', description: 'Element id and the selector of the per-instance rules, escaped for CSS (an id may start with a digit). Deterministic when omitted; pass one when two identical islands share a page.' },
+    { name: 'live', type: 'boolean', default: 'false', description: 'aria-live="polite" on the body, so a state change is announced.' },
+    { name: 'color', type: 'string', default: "'#0a0a0b'", description: 'Island colour; black by default, independent of the ink token.' },
+    { name: 'textColor', type: 'string', default: "'#fff'", description: 'Content colour.' },
+  ],
+  reducedMotion: 'The shape and the content change at once, no spring, no blur.',
+  clientRouter: 'Static; the state attribute is on the element and goes with the page. The per-instance style block is part of the page HTML and swaps with it.',
+  craft: [
+    'Sizes are declared because they must be: a box that animates from one auto size to another needs a script to measure both, and this one has none. Each state is three lengths, and the transition between them is on the preset spring: lively overshoots, ui settles.',
+    'The names come from props, so the stylesheet cannot know them: the component renders one small style block per instance, keyed by an id hashed from the states, with one rule per state for the lengths and one for the child that shows. It is CSS, printed in the readout.',
+    'Content per state is one default slot with data-state children, because a dynamic slot name inside a map() fails at prerender (7B). Children stack in one grid cell; the inactive ones are blurred, scaled down and transparent, and the active one waits one fast token so the old is gone before it arrives.',
+    'The island stays black in both themes: it is an object on the screen, not a panel of the page. color and textColor override it.',
+  ],
+  related: ['stateful-button', 'phone-frame', 'toast'],
+  intents: ['dynamic island', 'morphing pill notification', 'island state animation', 'pill that changes shape', 'live activity pill', 'expanding notification pill'],
+  replaces: ['DynamicIsland (Cult UI)', 'Dynamic Island (Kokonut UI)', 'Toolbar Dynamic (Motion Primitives)'],
+  fixture: { props: { id: 'ma-fixture-island', states: [{ name: 'idle', width: 7.5, height: 2.25 }, { name: 'wide', width: 14, height: 3.5 }] }, slot: '<span data-state="idle">Fixture content for DynamicIsland</span><span data-state="wide">Wide</span>', expect: 'Fixture content for DynamicIsland' },
+} satisfies ComponentMeta;

package/src/components/FileTree.astro

@@ -0,0 +1,207 @@
+---
+/**
+ * FileTree — a project tree of folders that open with an animated height,
+ * zero JS.
+ *
+ * Folders are native <details>: the click, the keyboard and the open state
+ * are the browser's; the height animates through ::details-content laid
+ * out as a grid whose only row goes 0fr → 1fr (the Accordion technique),
+ * the chevron turns and the folder glyph opens. `open` lists the paths to
+ * start open; `highlight` the files to light up ("this is the one you
+ * change"). Semantics are nested lists — role="tree" is not claimed because
+ * arrow-key navigation is not provided. Renders itself for each level.
+ */
+import type { HTMLAttributes } from 'astro/types';
+
+export interface Node {
+  name: string;
+  children?: Node[];
+  /** Light this row up. */
+  highlight?: boolean;
+  /** Start open (folders); also settable through the `open` prop by path. */
+  open?: boolean;
+}
+
+interface Props extends HTMLAttributes<'div'> {
+  tree: Node[];
+  /** Paths to start open, e.g. ['src', 'src/pages']. */
+  open?: string[];
+  /** Paths to light up, e.g. ['src/pages/index.astro']. */
+  highlight?: string[];
+  /** Accessible name of the tree. */
+  label?: string;
+  /** Internal: the path of this level. */
+  path?: string;
+  /** Internal: nested level. */
+  nested?: boolean;
+}
+
+const { tree, open = [], highlight = [], label = 'Files', path = '', nested = false, class: className, ...rest } = Astro.props;
+const join = (a: string, b: string) => (a ? `${a}/${b}` : b);
+const Level = Astro.self;
+---
+
+{
+  nested ? (
+    <ul class="ma-ftree__list">
+      {tree.map((n) => {
+        const p = join(path, n.name);
+        return n.children ? (
+          <li class="ma-ftree__folder">
+            <details class="ma-ftree__details" open={n.open || open.includes(p)}>
+              <summary class="ma-ftree__row" data-highlight={n.highlight || highlight.includes(p) ? '' : undefined}>
+                <svg class="ma-ftree__chevron" aria-hidden="true" viewBox="0 0 16 16" width="12" height="12"><path d="M6 4l4 4-4 4" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" /></svg>
+                <svg class="ma-ftree__glyph" aria-hidden="true" viewBox="0 0 20 20" width="16" height="16">
+                  <path class="ma-ftree__folder-back" d="M2 5.5A1.5 1.5 0 0 1 3.5 4h4l2 2h7A1.5 1.5 0 0 1 18 7.5v7A1.5 1.5 0 0 1 16.5 16h-13A1.5 1.5 0 0 1 2 14.5z" fill="currentColor" opacity="0.35" />
+                  <path class="ma-ftree__folder-flap" d="M2 8.5h16v6A1.5 1.5 0 0 1 16.5 16h-13A1.5 1.5 0 0 1 2 14.5z" fill="currentColor" />
+                </svg>
+                <span class="ma-ftree__name">{n.name}</span>
+              </summary>
+              <div class="ma-ftree__body">
+                <Level tree={n.children} open={open} highlight={highlight} path={p} nested />
+              </div>
+            </details>
+          </li>
+        ) : (
+          <li class="ma-ftree__file">
+            <span class="ma-ftree__row" data-highlight={n.highlight || highlight.includes(p) ? '' : undefined}>
+              <svg class="ma-ftree__glyph" aria-hidden="true" viewBox="0 0 20 20" width="16" height="16"><path d="M5 2h7l4 4v11a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V3a1 1 0 0 1 1-1z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round" /><path d="M12 2v4h4" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round" /></svg>
+              <span class="ma-ftree__name">{n.name}</span>
+            </span>
+          </li>
+        );
+      })}
+    </ul>
+  ) : (
+    <div class:list={['ma-ftree', className]} role="group" aria-label={label} {...rest}>
+      <Level tree={tree} open={open} highlight={highlight} path={path} nested />
+    </div>
+  )
+}
+
+<style is:global>
+  @layer components {
+    :where(.ma-ftree) {
+      font-family: ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+      font-size: 0.8125rem;
+      line-height: 1.4;
+    }
+    :where(.ma-ftree__list) {
+      margin: 0;
+      padding: 0;
+      list-style: none;
+    }
+    /* nested levels indent behind a guide line */
+    :where(.ma-ftree__list .ma-ftree__list) {
+      margin-inline-start: 0.8rem;
+      padding-inline-start: 0.7rem;
+      border-inline-start: 1px solid var(--ma-edge);
+    }
+    :where(.ma-ftree__row) {
+      position: relative;
+      display: flex;
+      align-items: center;
+      gap: 0.4rem;
+      padding: 0.25rem 0.5rem;
+      border-radius: 0.375rem;
+      color: inherit;
+      transition: background-color var(--ma-duration-fast) var(--ma-ease-out);
+    }
+    :where(.ma-ftree__file .ma-ftree__row) {
+      padding-inline-start: 1.55rem;
+    }
+    :where(summary.ma-ftree__row) {
+      cursor: pointer;
+      list-style: none;
+      font-weight: 500;
+    }
+    :where(summary.ma-ftree__row)::-webkit-details-marker {
+      display: none;
+    }
+    :where(summary.ma-ftree__row:hover) {
+      background: color-mix(in srgb, var(--ma-ink) 6%, transparent);
+    }
+    :where(summary.ma-ftree__row:focus-visible) {
+      outline: 2px solid currentColor;
+      outline-offset: -2px;
+    }
+    :where(.ma-ftree__glyph) {
+      flex: none;
+      opacity: 0.75;
+    }
+    :where(.ma-ftree__chevron) {
+      flex: none;
+      opacity: 0.55;
+      transition: rotate var(--ma-duration) var(--ma-ease);
+    }
+    /* right to left the closed chevron points left, into the line it starts (a half turn of a symmetric glyph), and the
+       open rule below turns it the other way to point down. [dir] and not :dir(): Chrome has :dir() only from 120, and a
+       build that targets an older Chrome rewrites it into a guess from lang, which a page that sets only dir never
+       matches. An ltr island one level inside an rtl page is set back */
+    :where([dir='rtl'] .ma-ftree__chevron, .ma-ftree[dir='rtl'] .ma-ftree__chevron) {
+      rotate: 180deg;
+    }
+    :where([dir='rtl'] [dir='ltr'] .ma-ftree__chevron, [dir='rtl'] .ma-ftree[dir='ltr'] .ma-ftree__chevron) {
+      rotate: none;
+    }
+    :where(.ma-ftree__details[open] > .ma-ftree__row .ma-ftree__chevron) {
+      rotate: 90deg;
+    }
+    /* the folder opens: the flap tips down from its bottom edge */
+    :where(.ma-ftree__folder-flap) {
+      transform-box: fill-box;
+      transform-origin: 50% 100%;
+      transition: transform var(--ma-duration) var(--ma-ease);
+    }
+    :where(.ma-ftree__details[open] > .ma-ftree__row .ma-ftree__folder-flap) {
+      transform: skewX(-16deg) scaleY(0.82);
+    }
+    /* the animated part: the content box is a grid whose only row interpolates 0fr → 1fr */
+    :where(.ma-ftree__details)::details-content {
+      display: grid;
+      grid-template-rows: 0fr;
+      transition:
+        grid-template-rows var(--ma-duration) var(--ma-ease),
+        content-visibility var(--ma-duration) allow-discrete;
+    }
+    :where(.ma-ftree__details[open])::details-content {
+      grid-template-rows: 1fr;
+    }
+    :where(.ma-ftree__body) {
+      min-height: 0;
+      overflow: clip;
+    }
+    /* the highlighted row: a tint and a dot in the accent, default the ink */
+    :where(.ma-ftree__row[data-highlight]) {
+      background: color-mix(in srgb, var(--ma-ftree-accent, var(--ma-ink)) 10%, transparent);
+      color: var(--ma-ftree-accent, inherit);
+      font-weight: 600;
+    }
+    :where(.ma-ftree__row[data-highlight])::after {
+      content: '';
+      position: absolute;
+      top: 50%;
+      inset-inline-end: 0.6rem;
+      width: 6px;
+      height: 6px;
+      border-radius: 999px;
+      background: var(--ma-ftree-accent, currentColor);
+      translate: 0 -50%;
+    }
+    /* ::details-content in a rule of its own: in an engine that does not know it, a selector list that names it is
+       dropped whole, and the chevron, the flap and the rows kept their transitions under reduced motion. The minifier merges
+       neighbouring rules with the same declarations back into one list, so this one sits behind a feature test */
+    @media (prefers-reduced-motion: reduce) {
+      @supports selector(::details-content) {
+        :where(.ma-ftree__details)::details-content {
+          transition: none;
+        }
+      }
+      :where(.ma-ftree__chevron),
+      :where(.ma-ftree__folder-flap),
+      :where(.ma-ftree__row) {
+        transition: none;
+      }
+    }
+  }
+</style>

package/src/components/FileTree.meta.ts

@@ -0,0 +1,34 @@
+import type { ComponentMeta } from '../lib/meta';
+
+export default {
+  name: 'FileTree',
+  slug: 'file-tree',
+  title: 'File Tree',
+  description: 'A project tree whose folders open with an animated height, a turning chevron and a folder glyph that tips open; rows can be lit up to say "this is the file you change". Zero JavaScript: folders are native <details> and the height is ::details-content laid out as a grid row from 0fr to 1fr, the Accordion technique nested as deep as the tree goes.',
+  summary: 'A project file tree whose folders open with an animated height, with rows you can highlight.',
+  category: 'ui',
+  tier: 'A',
+  trigger: ['click'],
+  support: { baseline: 'newly', needs: ['details-content', 'grid-rows-animation'], fallback: 'folders open at once' },
+  readout: '<FileTree open={["src"]}>',
+  usage: `<FileTree\n  open={['src', 'src/components']}\n  highlight={['src/components/Reveal.astro']}\n  tree={[\n    { name: 'src', children: [\n      { name: 'components', children: [{ name: 'Reveal.astro' }, { name: 'Marquee.astro' }] },\n      { name: 'pages', children: [{ name: 'index.astro' }] },\n    ] },\n    { name: 'astro.config.mjs' },\n    { name: 'package.json' },\n  ]}\n/>`,
+  props: [
+    { name: 'tree', type: '{ name: string; children?: Node[]; highlight?: boolean; open?: boolean }[]', description: 'The tree; a node with children is a folder.' },
+    { name: 'open', type: 'string[]', default: '[]', description: 'Paths that start open, joined with "/" (src/pages).' },
+    { name: 'highlight', type: 'string[]', default: '[]', description: 'Paths to light up.' },
+    { name: 'label', type: 'string', default: "'Files'", description: 'Accessible name of the tree.' },
+  ],
+  reducedMotion: 'Folders open at once; the chevron and the flap jump.',
+  clientRouter: 'Native; nothing to rebind. The open state lives in the details elements and resets with the page.',
+  craft: [
+    'Native <details> per folder: click, Enter, Space, and the open attribute are the browser\'s, at every depth.',
+    'The height comes from ::details-content as a grid row interpolating 0fr → 1fr. Nothing is measured, and nested folders animate independently because each has its own row.',
+    'The folder glyph is two paths; the flap skews and shortens from its bottom edge when open, so the icon tells the state without a second icon set.',
+    'Nested lists sit behind a hairline guide, indented by one row, so depth reads at a glance in a docs sidebar. Indents, the guide and the highlight dot are logical properties, and under a dir="rtl" ancestor the closed chevron points left and turns the other way to open, so a right-to-left page gets the tree the other way round. The selector reads the attribute because Chrome has :dir() only from 120, and a build that targets an older Chrome rewrites it into a guess from lang, which a page that sets only dir never matches.',
+    'The semantics are nested lists and a group label. role="tree" is not claimed because the arrow-key navigation the role promises is not provided.',
+  ],
+  related: ['accordion', 'code-tabs', 'docs-shell'],
+  intents: ['file tree', 'project structure tree', 'animated folder tree', 'directory tree astro', 'docs file explorer', 'nested details accordion'],
+  replaces: ['FileTree (Magic UI)', 'Tree (shadcn / Radix)', 'FileTree (Fumadocs)'],
+  fixture: { props: { open: ['src'], tree: [{ name: 'src', children: [{ name: 'Fixture content for FileTree' }] }, { name: 'package.json' }] }, expect: 'Fixture content for FileTree' },
+} satisfies ComponentMeta;