@blukavantui/community 1.0.1 → 1.2.0

package/src/motion/optional.ts

@@ -0,0 +1,123 @@
+import type { MotionController, MotionOptions, MotionResult } from './controller.js';
+import { preserveStyles } from './structure.js';
+
+const overlayHosts = new WeakMap<HTMLElement, { count: number; restore(): void }>();
+function overlayFor(host: HTMLElement, className: string) {
+  const win = host.ownerDocument.defaultView;
+  if (!win || !host.isConnected) throw Error('Mount optional motion on a connected element.');
+  let ownership = overlayHosts.get(host);
+  if (!ownership) {
+    ownership = { count: 0, restore: preserveStyles(host, ['position']) }; overlayHosts.set(host, ownership);
+    if (win.getComputedStyle(host).position === 'static') host.style.position = 'relative';
+  }
+  ownership.count++; let released = false;
+  const restore = () => { if (released) return; released = true; if (--ownership!.count === 0) { ownership!.restore(); overlayHosts.delete(host); } };
+  const overlay = host.ownerDocument.createElement('span');
+  overlay.className = className; overlay.setAttribute('aria-hidden', 'true'); overlay.inert = true; host.append(overlay);
+  return { overlay, restore, win };
+}
+const rippleOwners = new WeakSet<HTMLElement>();
+/** Responds to an actual click; never synthesizes activation or changes focus. */
+export function createRipple(element: HTMLElement, motion: MotionController, options: MotionOptions & {listen?:boolean} = {}) {
+  const {listen=true,...timing}=options;
+  if (rippleOwners.has(element)) throw Error('This element already has ripple feedback.');
+  const { overlay, restore } = overlayFor(element, 'blu-motion-ripple');
+  rippleOwners.add(element);
+  let current: HTMLElement | undefined, dead = false;
+  const clear = () => { if (current) { motion.cancel(current); current.remove(); current = undefined; } };
+  // Presentation only: this also supports controls replaced during their click.
+  // It never dispatches a click or changes application state.
+  const play = (point?: {clientX:number;clientY:number}) => {
+    if (dead || !element.isConnected || element.matches(':disabled') || element.getAttribute('aria-disabled') === 'true' || element.closest('[inert]')) return;
+    clear();
+    if (motion.mode !== 'full' || element.closest('.blu-motion-off, [data-blu-motion="off"], [data-blu-motion="reduced"]')) return;
+    const bounds = overlay.getBoundingClientRect(), width = overlay.clientWidth, height = overlay.clientHeight;
+    if (!width || !height || !bounds.width || !bounds.height) return;
+    const x = !point ? width / 2 : Math.min(width, Math.max(0, (point.clientX - bounds.left) * width / bounds.width));
+    const y = !point ? height / 2 : Math.min(height, Math.max(0, (point.clientY - bounds.top) * height / bounds.height));
+    const diameter = Math.hypot(Math.max(x, width - x), Math.max(y, height - y)) * 2;
+    const wave = element.ownerDocument.createElement('span'); wave.className = 'blu-motion-ripple__wave';
+    wave.style.cssText = `width:${diameter}px;height:${diameter}px;left:${x-diameter/2}px;top:${y-diameter/2}px`;
+    overlay.append(wave); current = wave;
+    void motion.animate(wave, [{ transform: 'scale(0)', opacity: .4 }, { transform: 'scale(.8)', opacity: .25, offset: .65 }, { transform: 'scale(1)', opacity: 0 }], { duration: 1000, easing: 'ease-out', ...timing }).finally(() => {
+      wave.remove(); if (current === wave) current = undefined;
+    });
+  };
+  const click = (event: MouseEvent) => { if(!event.defaultPrevented)play(event.detail ? event : undefined); };
+  if(listen)element.addEventListener('click', click);
+  return { element: overlay, play, destroy() { if (dead) return; dead = true; element.removeEventListener('click', click); clear(); overlay.remove(); restore(); rippleOwners.delete(element); } };
+}
+
+export interface ShimmerOptions { duration?: number; paused?: boolean }
+const shimmerOwners = new WeakSet<HTMLElement>();
+/** Attach to a decorative skeleton only. The caller owns busy/status semantics. */
+export function createShimmer(element: HTMLElement, options: ShimmerOptions = {}) {
+  const validate = (value = 1800) => { if (!Number.isFinite(value) || value < 1200 || value > 6000) throw Error('Shimmer duration must be 1200–6000 ms.'); return value; };
+  let duration = validate(options.duration), paused = options.paused ?? false, visible = false, dead = false;
+  if (shimmerOwners.has(element)) throw Error('This element already has a shimmer.');
+  const { overlay, restore, win } = overlayFor(element, 'blu-motion-shimmer');
+  const beam = element.ownerDocument.createElement('span'); beam.className = 'blu-motion-shimmer__beam'; overlay.append(beam);
+  shimmerOwners.add(element);
+  const sync = () => { overlay.style.setProperty('--blu-shimmer-duration', duration + 'ms'); overlay.dataset.paused = String(paused || !visible || element.ownerDocument.hidden); };
+  const observer = win.IntersectionObserver ? new win.IntersectionObserver(entries => { visible = entries[0].isIntersecting; sync(); }) : null;
+  if (observer) observer.observe(element); else visible = true;
+  element.ownerDocument.addEventListener('visibilitychange', sync); sync();
+  return { element: overlay, update(next: ShimmerOptions) {
+    if (dead) throw Error('Shimmer is destroyed.');
+    if (next.duration !== undefined) duration = validate(next.duration);
+    if (next.paused !== undefined) paused = next.paused;
+    sync();
+  }, destroy() { if (dead) return; dead = true; observer?.disconnect(); element.ownerDocument.removeEventListener('visibilitychange', sync); overlay.remove(); restore(); shimmerOwners.delete(element); } };
+}
+
+export type MotionIcon = 'chevron' | 'plus-minus' | 'menu-close' | 'save-check';
+const ns = 'http://www.w3.org/2000/svg';
+/** Owns an empty decorative icon slot only. Labels and aria-expanded/pressed belong to the control. */
+export function createIconTransition(host: HTMLElement, motion: MotionController, kind: MotionIcon, initial = false) {
+  if (!host.isConnected || !host.ownerDocument.defaultView) throw Error('Mount icon motion on a connected element.');
+  if (host.childNodes.length) throw Error('Icon motion requires an empty decorative slot.');
+  if (!['chevron', 'plus-minus', 'menu-close', 'save-check'].includes(kind)) throw Error('Unknown motion icon.');
+  const doc = host.ownerDocument, win = doc.defaultView!;
+  const svg = doc.createElementNS(ns, 'svg'); svg.setAttribute('viewBox', '0 0 24 24'); svg.setAttribute('aria-hidden', 'true'); svg.setAttribute('focusable', 'false'); svg.classList.add('blu-motion-icon');
+  const paths = kind === 'chevron' ? ['M6 9l6 6 6-6'] : kind === 'plus-minus' ? ['M5 12h14', 'M12 5v14'] : kind === 'menu-close' ? ['M4 6h16', 'M4 12h16', 'M4 18h16'] : ['M4 3h13l3 3v15H4z M8 3v6h8V3 M8 21v-7h8v7', 'M5 12l4 4L19 6'];
+  const parts = paths.map(d => { const p = doc.createElementNS(ns, 'path'); p.setAttribute('d', d); p.style.transformOrigin = '12px 12px'; svg.append(p); return p; }); host.append(svg);
+  let active = initial, dead = false;
+  const state = (on: boolean, index: number) => {
+    if (kind === 'chevron') return { transform: `rotate(${on ? 180 : 0}deg)`, opacity: '1' };
+    if (kind === 'plus-minus') return { transform: `rotate(${on && index === 1 ? 90 : 0}deg)`, opacity: on && index === 1 ? '0' : '1' };
+    if (kind === 'menu-close') return { transform: !on ? 'none' : index === 0 ? 'rotate(45deg) translateY(6px)' : index === 2 ? 'rotate(-45deg) translateY(-6px)' : 'scaleX(.5)', opacity: on && index === 1 ? '0' : '1' };
+    return { transform: `scale(${on === (index === 1) ? 1 : .85})`, opacity: on === (index === 1) ? '1' : '0' };
+  };
+  parts.forEach((part, i) => Object.assign(part.style, state(active, i)));
+  return { element: svg, async setActive(next: boolean, options: MotionOptions = {}): Promise<MotionResult> {
+    if (dead) return 'cancelled';
+    if (next === active) return 'finished'; active = next;
+    const results = await Promise.all(parts.map((part, i) => {
+      const css = win.getComputedStyle(part), from = { transform: css.transform, opacity: css.opacity };
+      motion.cancel(part); const to = state(next, i); Object.assign(part.style, to);
+      return motion.animate(part, [from, to], { duration: 450, easing: 'ease-in-out', ...options });
+    }));
+    return results.includes('cancelled') ? 'cancelled' : 'finished';
+  }, destroy() { if (dead) return; dead = true; parts.forEach(part => motion.cancel(part)); svg.remove(); } };
+}
+
+/** Persistent selection decoration; never replaces a focus outline. */
+export function createEmphasis(element: HTMLElement, motion: MotionController, kind: 'underline' | 'border' = 'underline') {
+  if (!['underline', 'border'].includes(kind)) throw Error('Unknown emphasis style.');
+  const { overlay, restore, win } = overlayFor(element, 'blu-motion-emphasis blu-motion-emphasis--' + kind);
+  let target: HTMLElement | SVGElement = overlay, resize: ResizeObserver | undefined;
+  if (kind === 'border') {
+    const svg = element.ownerDocument.createElementNS(ns, 'svg'), rect = element.ownerDocument.createElementNS(ns, 'rect');
+    rect.setAttribute('pathLength', '1'); rect.setAttribute('vector-effect', 'non-scaling-stroke'); svg.append(rect); overlay.append(svg); target = rect;
+    const measure = () => { const { width, height } = overlay.getBoundingClientRect(); svg.setAttribute('viewBox', `0 0 ${width} ${height}`); rect.setAttribute('x', '1'); rect.setAttribute('y', '1'); rect.setAttribute('width', String(Math.max(0, width - 2))); rect.setAttribute('height', String(Math.max(0, height - 2))); rect.setAttribute('rx', win.getComputedStyle(element).borderTopLeftRadius); };
+    resize = new win.ResizeObserver(measure); resize.observe(element); measure(); target.style.strokeDasharray = '1'; target.style.strokeDashoffset = '1';
+  } else target.style.transform = 'scaleX(0)';
+  let active = false, dead = false;
+  return { element: overlay, async setActive(next: boolean, options: MotionOptions = {}): Promise<MotionResult> {
+    if (dead) return 'cancelled';
+    if (active === next) return 'finished'; active = next;
+    const css = win.getComputedStyle(target), property = kind === 'border' ? 'strokeDashoffset' : 'transform', from = css[property];
+    motion.cancel(target); const to = kind === 'border' ? (next ? '0' : '1') : `scaleX(${next ? 1 : 0})`; target.style[property] = to;
+    return motion.animate(target, [{ [property]: from }, { [property]: to }], { duration: 750, easing: 'ease-in-out', ...options });
+  }, destroy() { if (dead) return; dead = true; motion.cancel(target); resize?.disconnect(); overlay.remove(); restore(); } };
+}

package/src/motion/photo.ts

@@ -0,0 +1,19 @@
+import type { MotionController, MotionResult } from './controller.js';
+import { preserveStyles, type TransitionOptions } from './structure.js';
+/** A persistent crop change inside an overflow-hidden frame; does not fade the photo away. */
+export function createPhotoZoom(image: HTMLImageElement, motion: MotionController, maximum = 1.2) {
+  if (!Number.isFinite(maximum) || maximum < 1 || maximum > 2) throw new Error('Photo zoom must be between 1 and 2.');
+  const restore = preserveStyles(image, ['transform', 'transform-origin']);
+  let revision = 0, destroyed = false;
+  image.style.transformOrigin = 'center';
+  return {
+    async setZoomed(zoomed: boolean, options: TransitionOptions = {}): Promise<MotionResult> {
+      if (destroyed) return 'cancelled';
+      const own = ++revision, from = image.ownerDocument.defaultView!.getComputedStyle(image).transform;
+      motion.cancel(image); image.style.transform = `scale(${zoomed ? maximum : 1})`;
+      await motion.animate(image, [{ transform: from }, { transform: image.style.transform }], { duration: 1000, easing: 'ease-in-out', ...options });
+      return !destroyed && own === revision ? 'finished' : 'cancelled';
+    },
+    destroy() { if (destroyed) return; destroyed = true; ++revision; motion.cancel(image); restore(); },
+  };
+}

package/src/motion/presence.ts

@@ -0,0 +1,44 @@
+import type { MotionController, MotionEffect, MotionOptions, MotionResult } from './controller.js';
+
+export interface PresenceOptions extends Omit<MotionOptions, 'phase'> {
+  effect?: MotionEffect;
+  /** Required when hiding an element that currently contains keyboard focus. */
+  focusFallback?: HTMLElement;
+}
+/** Owns hidden/inert for a mounted element. Use for panels, cards and menus; no router dependency. */
+export function createMotionPresence(element: HTMLElement, motion: MotionController) {
+  const originalHidden = element.hidden, originalInert = element.inert;
+  let revision = 0, destroyed = false;
+  return {
+    async show(options: PresenceOptions = {}): Promise<MotionResult> {
+      if (destroyed) return 'cancelled';
+      const own = ++revision;
+      motion.cancel(element);
+      element.hidden = false;
+      element.inert = originalInert;
+      await motion.play(element, options.effect || 'fade', { ...options, phase: 'enter' });
+      return !destroyed && revision === own ? 'finished' : 'cancelled';
+    },
+    async hide(options: PresenceOptions = {}): Promise<MotionResult> {
+      if (destroyed) return 'cancelled';
+      if (element.contains(element.ownerDocument.activeElement)) {
+        const fallback = options.focusFallback;
+        if (!fallback?.isConnected || element.contains(fallback)) throw new Error('Provide a connected focusFallback outside the closing element.');
+        fallback.focus({ preventScroll: true });
+        if (element.contains(element.ownerDocument.activeElement)) throw new Error('focusFallback must be focusable.');
+      }
+      const own = ++revision;
+      motion.cancel(element);
+      element.inert = true;
+      if (!element.hidden) await motion.play(element, options.effect || 'fade', { ...options, phase: 'exit' });
+      if (destroyed || revision !== own) return 'cancelled';
+      element.hidden = true;
+      return 'finished';
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true; ++revision; motion.cancel(element);
+      element.hidden = originalHidden; element.inert = originalInert;
+    },
+  };
+}

package/src/motion/scene.ts

@@ -0,0 +1,103 @@
+import type { MotionController, MotionResult } from './controller.js';
+import { preserveStyles, type TransitionOptions } from './structure.js';
+
+function sharedNodes(root: HTMLElement) {
+  const nodes = new Map<string, HTMLElement>();
+  for (const node of Array.from(root.querySelectorAll<HTMLElement>('[data-shared-key]'))) {
+    const key = node.dataset.sharedKey!;
+    if (!key || nodes.has(key)) throw new Error('Shared elements need unique, nonempty data-shared-key values per view.');
+    if (node.matches('button, input, select, textarea, a, [tabindex], [contenteditable], canvas, video, iframe') || node.querySelector('button, input, select, textarea, a, [tabindex], [contenteditable], canvas, video, iframe, [data-shared-key]')) throw new Error('Shared elements must be decorative text, image or SVG wrappers, without interactive or nested shared content.');
+    nodes.set(key, node);
+  }
+  return nodes;
+}
+
+/** Crossfade real views concurrently; optional decorative shared elements connect matching views. */
+function createSceneTransition(host: HTMLElement, motion: MotionController, shared: boolean) {
+  let revision = 0, destroyed = false, stop = () => {};
+  let activeVisuals = new Map<string, HTMLElement>();
+  return {
+    async show(next: HTMLElement, options: TransitionOptions = {}): Promise<MotionResult> {
+      if (destroyed) return 'cancelled';
+      if (next.parentNode || next === host || next.contains(host)) throw new Error('Provide a detached next view.');
+      // Validate before changing the current view or cancelling a successful pending transition.
+      const nextShared = shared ? sharedNodes(next) : new Map<string, HTMLElement>();
+      const own = ++revision, interruptedRects = new Map(Array.from(activeVisuals, ([key, visual]) => [key, visual.getBoundingClientRect()])); stop();
+      options = { duration: 280, ...options };
+      const old = host.firstElementChild as HTMLElement | null;
+      const oldShared = shared && old ? sharedNodes(old) : new Map<string, HTMLElement>();
+      const initialRects = new Map(Array.from(oldShared, ([key, node]) => [key, interruptedRects.get(key) || node.getBoundingClientRect()]));
+      const focused = host.ownerDocument.activeElement as HTMLElement | null, focusInside = !!old?.contains(focused);
+      const focusKey = focused?.dataset.focusKey, top = host.scrollTop, left = host.scrollLeft;
+      const restoreHost = preserveStyles(host, ['display', 'position', 'isolation', 'box-sizing', 'align-items']);
+      const restoreNext = preserveStyles(next, ['grid-area', 'min-width']);
+      const restoreOld = old ? preserveStyles(old, ['grid-area', 'min-width']) : () => {};
+      const oldInert = old?.inert, oldAria = old?.getAttribute('aria-hidden');
+      const oldHeight = host.getBoundingClientRect().height;
+      const targets: (HTMLElement | SVGElement)[] = [host, next]; if (old) targets.push(old);
+      const restoreVisuals: (() => void)[] = [], overlays: HTMLElement[] = [];
+      let cleaned = false;
+      const finish = () => {
+        if (cleaned) return; cleaned = true;
+        for (const target of targets) motion.cancel(target);
+        for (const overlay of overlays) overlay.remove();
+        activeVisuals.clear();
+        for (const restore of restoreVisuals) restore();
+        old?.remove(); restoreOld(); restoreNext(); restoreHost();
+        if (old) { old.inert = oldInert!; if (oldAria === null) old.removeAttribute('aria-hidden'); else old.setAttribute('aria-hidden', oldAria!); }
+      };
+      stop = finish;
+      try {
+        host.style.display = 'grid'; host.style.alignItems = 'start'; host.style.position = 'relative'; host.style.isolation = 'isolate'; host.style.boxSizing = 'border-box';
+        next.style.gridArea = '1 / 1'; next.style.minWidth = '0';
+        if (old) { old.style.gridArea = '1 / 1'; old.style.minWidth = '0'; }
+        host.append(next);
+        // Only the incoming view is interactive/announced. External navigation retains focus.
+        if (focusInside) {
+          const match = focusKey ? Array.from(next.querySelectorAll<HTMLElement>('[data-focus-key]')).find(node => node.dataset.focusKey === focusKey) : null;
+          const destination = match || next.querySelector<HTMLElement>('[data-view-heading]') || next;
+          const originalTabindex = destination.getAttribute('tabindex');
+          if (!match) destination.tabIndex = -1;
+          destination.focus({ preventScroll: true });
+          if (!match) { if (originalTabindex === null) destination.removeAttribute('tabindex'); else destination.setAttribute('tabindex', originalTabindex); }
+        }
+        if (old) { old.inert = true; old.setAttribute('aria-hidden', 'true'); }
+        host.scrollTop = top; host.scrollLeft = left;
+        const pending: Promise<MotionResult>[] = [];
+        const hostRect = host.getBoundingClientRect();
+        for (const [key, incoming] of nextShared) {
+          const outgoing = oldShared.get(key), first = initialRects.get(key), last = incoming.getBoundingClientRect();
+          if (!outgoing || !first?.width || !first.height || !last.width || !last.height || motion.mode !== 'full') continue;
+          // The clone is strictly presentational: no IDs, focus targets or event listeners.
+          const clone = outgoing.cloneNode(true) as HTMLElement;
+          for (const node of [clone, ...Array.from(clone.querySelectorAll<HTMLElement>('*'))]) {
+            node.removeAttribute('id'); node.removeAttribute('name'); node.removeAttribute('data-shared-key');
+          }
+          clone.inert = true; clone.setAttribute('aria-hidden', 'true'); clone.setAttribute('data-motion-overlay', '');
+          clone.style.cssText += `;position:absolute;pointer-events:none;margin:0;left:${first.left-hostRect.left+host.scrollLeft-host.clientLeft}px;top:${first.top-hostRect.top+host.scrollTop-host.clientTop}px;width:${first.width}px;height:${first.height}px;box-sizing:border-box;transform-origin:top left;z-index:10;`;
+          host.append(clone); overlays.push(clone); targets.push(clone); activeVisuals.set(key, clone);
+          for (const node of [outgoing, incoming]) { restoreVisuals.push(preserveStyles(node, ['visibility'])); node.style.visibility = 'hidden'; }
+          const style = host.ownerDocument.defaultView!.getComputedStyle(incoming);
+          pending.push(motion.animate(clone, [
+            { transform: 'none', width: first.width + 'px', height: first.height + 'px', borderRadius: host.ownerDocument.defaultView!.getComputedStyle(outgoing).borderRadius },
+            { transform: `translate(${last.left-first.left}px, ${last.top-first.top}px)`, width: last.width + 'px', height: last.height + 'px', borderRadius: style.borderRadius },
+          ], { easing: 'ease-in-out', ...options }));
+        }
+        // Both animations start in the same turn: this is an overlapping crossfade, not fade-out then fade-in.
+        if (old) pending.push(motion.play(old, 'fade', { ...options, phase: 'exit' }));
+        pending.push(motion.play(next, 'fade', { ...options, phase: 'enter' }));
+        // Reserve the incoming view's actual height, including host padding/borders.
+        if (old) {
+          const css = host.ownerDocument.defaultView!.getComputedStyle(host);
+          const chrome = parseFloat(css.paddingTop) + parseFloat(css.paddingBottom) + parseFloat(css.borderTopWidth) + parseFloat(css.borderBottomWidth);
+          pending.push(motion.animate(host, [{ height: oldHeight + 'px' }, { height: next.getBoundingClientRect().height + chrome + 'px' }], options));
+        }
+        await Promise.all(pending);
+      } finally { if (revision === own) { finish(); stop = () => {}; } }
+      return !destroyed && revision === own ? 'finished' : 'cancelled';
+    },
+    destroy() { if (destroyed) return; destroyed = true; ++revision; stop(); stop = () => {}; },
+  };
+}
+export function createCrossfade(host: HTMLElement, motion: MotionController) { return createSceneTransition(host, motion, false); }
+export function createSharedElementTransition(host: HTMLElement, motion: MotionController) { return createSceneTransition(host, motion, true); }

package/src/motion/screen.ts

@@ -0,0 +1,15 @@
+import type {MotionController, MotionResult} from './controller.js';
+/** Enhance an already-rendered container. The host owns visibility, DOM and navigation. */
+export function createScreenMotion(scope:HTMLElement,motion:MotionController){
+  const seen=new WeakMap<HTMLElement,string>(),active=new Map<HTMLElement,number>();let dead=false,revision=0;
+  return {
+    enter(element:HTMLElement,key:string):Promise<MotionResult>{
+      if(dead)return Promise.resolve('cancelled');
+      if(!scope.contains(element))throw Error('Screen content must be inside its scope.');
+      if(seen.get(element)===key)return Promise.resolve('finished');
+      seen.set(element,key);const token=++revision;active.set(element,token);
+      return motion.animate(element,[{opacity:0,translate:'0px 12px'},{opacity:1,translate:'0px 0px'}],{duration:650,easing:'ease-out'},'fade').finally(()=>{if(active.get(element)===token)active.delete(element);});
+    },
+    destroy(){if(dead)return;dead=true;for(const el of active.keys())motion.cancel(el);active.clear();}
+  };
+}

package/src/motion/scroll-reveal.ts

@@ -0,0 +1,49 @@
+import type { MotionController, MotionEffect, MotionOptions } from './controller.js';
+export interface ScrollRevealOptions extends Omit<MotionOptions, 'phase'> {
+  effect?: MotionEffect;
+  once?: boolean;
+  threshold?: number;
+  root?: Element | Document | null;
+  rootMargin?: string;
+  onReveal?: (element: HTMLElement) => void;
+}
+
+/** Progressive enhancement: nothing is hidden before the observer runs or when JS is unavailable. */
+export function createScrollReveal(targets: Iterable<HTMLElement>, motion: MotionController, options: ScrollRevealOptions = {}) {
+  const elements = Array.from(new Set(targets));
+  const win = elements[0]?.ownerDocument.defaultView;
+  const inView = new Set<HTMLElement>(), played = new Set<HTMLElement>();
+  const pending = new Map<HTMLElement, object>();
+  let destroyed = false;
+  const threshold = Number.isFinite(options.threshold) ? Math.min(1, Math.max(0, options.threshold!)) : .15;
+  const once = options.once !== false;
+  const Observer = win?.IntersectionObserver;
+  // Unsupported/SSR documents keep their complete content without scroll-event polling.
+  const observer = Observer ? new Observer(entries => {
+    if (destroyed) return;
+    for (const entry of entries) {
+      const element = entry.target as HTMLElement;
+      const visible = entry.isIntersecting && entry.intersectionRatio >= threshold;
+      if (!visible) { inView.delete(element); continue; }
+      if (!element.isConnected || inView.has(element) || (once && played.has(element))) continue;
+      inView.add(element); played.add(element);
+      if (once) observer!.unobserve(element);
+      const token = {};
+      pending.set(element, token);
+      // A callback can update UI/counters without controlling visibility or triggering another reveal.
+      const effect = motion.play(element, options.effect || 'fade', { ...options, phase: 'enter' });
+      options.onReveal?.(element);
+      void effect.finally(() => { if (pending.get(element) === token) pending.delete(element); });
+    }
+  }, { root: options.root || null, rootMargin: options.rootMargin || '0px', threshold }) : null;
+  for (const element of elements) observer?.observe(element);
+  return {
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      observer?.disconnect();
+      for (const element of pending.keys()) motion.cancel(element);
+      pending.clear(); inView.clear(); played.clear();
+    },
+  };
+}

package/src/motion/settings-group.ts

@@ -0,0 +1,28 @@
+import { validateComponentMotion, type ComponentMotionSettings } from './component-settings.js';
+
+/** Settings only: factories keep ownership of their components and business state. */
+export function createMotionSettingsGroup(initial: ComponentMotionSettings = {}) {
+  let defaults = validateComponentMotion(initial);
+  const members = new Set<() => void>();
+  return {
+    get settings() { return { ...defaults }; },
+    configure(next: ComponentMotionSettings = {}) {
+      defaults = validateComponentMotion(next);
+      for (const apply of members) apply();
+    },
+    bind(update: (settings: ComponentMotionSettings) => void) {
+      let overrides: ComponentMotionSettings = {}, dead = false;
+      const apply = () => update({ ...defaults, ...overrides });
+      members.add(apply);
+      return {
+        setMotion(next: ComponentMotionSettings = {}) {
+          if (dead) throw Error('Component motion is destroyed.');
+          const valid = validateComponentMotion(next);
+          if (valid.mode === 'inherit') delete valid.mode;
+          overrides = valid; apply();
+        },
+        destroy() { dead = true; members.delete(apply); },
+      };
+    },
+  };
+}

package/src/motion/stagger.ts

@@ -0,0 +1,26 @@
+import type { MotionController, MotionEffect, MotionOptions, MotionResult } from './controller.js';
+import { boundedTime } from './controller.js';
+export type StaggerOrder = 'forward' | 'reverse' | 'center' | 'rows' | 'columns';
+export interface StaggerOptions extends MotionOptions {
+  gap?: number;
+  order?: StaggerOrder;
+  /** Used for row/column sequences. Supply the current rendered column count. */
+  columns?: number;
+}
+
+/** Logical ranks only: never reorder the DOM or change reading/tab order. */
+export function staggerRanks(count: number, order: StaggerOrder = 'forward', columns = 1): number[] {
+  if (!Number.isInteger(count) || count < 0) throw Error('Stagger count must be a nonnegative integer.');
+  if (!['forward', 'reverse', 'center', 'rows', 'columns'].includes(order)) throw Error('Unknown stagger order.');
+  if (!Number.isInteger(columns) || columns < 1) throw Error('Stagger columns must be a positive integer.');
+  return Array.from({ length: count }, (_, i) => order === 'reverse' ? count - 1 - i
+    : order === 'center' ? Math.floor(Math.abs(i - (count - 1) / 2))
+    : order === 'rows' ? Math.floor(i / columns) : order === 'columns' ? i % columns : i);
+}
+
+/** A bounded entrance/exit sequence. Reduced/Off modes suppress delays in the controller. */
+export function playStagger(motion: MotionController, elements: Iterable<HTMLElement>, effect: MotionEffect = 'fade', options: StaggerOptions = {}): Promise<MotionResult[]> {
+  const gap = boundedTime(options.gap, 45, 150), base = boundedTime(options.delay, 0, 500);
+  const targets = Array.from(elements), ranks = staggerRanks(targets.length, options.order, options.columns);
+  return Promise.all(targets.map((element, index) => motion.play(element, effect, { ...options, delay: Math.min(500, base + ranks[index] * gap) })));
+}

package/src/motion/structure.ts

@@ -0,0 +1,75 @@
+import type { MotionController, MotionOptions, MotionResult } from './controller.js';
+
+export type TransitionOptions = Omit<MotionOptions, 'phase'>;
+/** Save only owned declarations, preserving unrelated inline styles and priorities. */
+export function preserveStyles(element: HTMLElement | SVGElement, properties: string[]) {
+  const values = properties.map(key => [key, element.style.getPropertyValue(key), element.style.getPropertyPriority(key)]);
+  return () => { for (const [key, value, priority] of values) { if (value) element.style.setProperty(key, value, priority); else element.style.removeProperty(key); } };
+}
+export function moveFocusOut(element: HTMLElement, fallback?: HTMLElement) {
+  if (!element.contains(element.ownerDocument.activeElement)) return;
+  if (!fallback?.isConnected || element.contains(fallback)) throw new Error('Provide a connected focusFallback outside the closing element.');
+  fallback.focus({ preventScroll: true });
+  if (element.contains(element.ownerDocument.activeElement)) throw new Error('focusFallback must be focusable.');
+}
+
+/** Animate an unpadded outer wrapper; put padding/borders in its child. Handles auto dimensions. */
+export function createSizeTransition(element: HTMLElement, motion: MotionController, axis: 'height' | 'width' = 'height') {
+  const original = { hidden: element.hidden, inert: element.inert };
+  let revision = 0, destroyed = false, release = () => {};
+  async function run(open: boolean, change: (() => void) | undefined, options: TransitionOptions & { focusFallback?: HTMLElement }): Promise<MotionResult> {
+    if (destroyed) return 'cancelled';
+    if (!open) moveFocusOut(element, options.focusFallback);
+    const from = element.hidden ? 0 : element.getBoundingClientRect()[axis], own = ++revision;
+    motion.cancel(element); release();
+    element.hidden = false; element.inert = open ? original.inert : true;
+    change?.();
+    const to = open ? element.getBoundingClientRect()[axis] : 0;
+    const restoreOuter = preserveStyles(element, ['overflow', 'box-sizing', 'will-change', axis]);
+    // A horizontal reveal clips a stable inner layout instead of rewrapping text every frame.
+    const child = axis === 'width' ? element.firstElementChild as HTMLElement | null : null;
+    const restoreChild = child ? preserveStyles(child, ['width', 'min-width', 'max-width', 'box-sizing']) : () => {};
+    if (child) { const width = child.getBoundingClientRect().width; child.style.boxSizing = 'border-box'; child.style.width = width + 'px'; child.style.minWidth = width + 'px'; child.style.maxWidth = width + 'px'; }
+    const restore = () => { restoreChild(); restoreOuter(); }; release = restore;
+    element.style.overflow = 'hidden'; element.style.boxSizing = 'border-box'; element.style.willChange = axis;
+    element.style[axis] = to + 'px';
+    try { await motion.animate(element, [{ [axis]: from + 'px' }, { [axis]: to + 'px' }], { duration: 450, easing: 'ease-in-out', ...options }); }
+    finally { if (revision === own) { restore(); release = () => {}; } }
+    if (destroyed || revision !== own) return 'cancelled';
+    element.hidden = !open;
+    return 'finished';
+  }
+  return {
+    setOpen(open: boolean, options: TransitionOptions & { focusFallback?: HTMLElement } = {}) { return run(open, undefined, options); },
+    resize(change: () => void, options: TransitionOptions = {}) { return run(true, change, options); },
+    destroy() { if (destroyed) return; destroyed = true; ++revision; motion.cancel(element); release(); element.hidden = original.hidden; element.inert = original.inert; },
+  };
+}
+
+/** FLIP movement for retained DOM nodes. The caller owns data changes and removed nodes. */
+export function createLayoutTransition(container: HTMLElement, motion: MotionController) {
+  let revision = 0, destroyed = false;
+  const active = new Set<HTMLElement>();
+  return {
+    async update(elements: HTMLElement[], change: () => void, options: TransitionOptions = {}): Promise<MotionResult> {
+      if (destroyed) return 'cancelled';
+      if (elements.some(el => !container.contains(el))) throw new Error('Layout targets must belong to the container.');
+      const own = ++revision, before = new Map(elements.map(el => [el, el.getBoundingClientRect()]));
+      const focused = container.ownerDocument.activeElement as HTMLElement | null;
+      for (const el of active) motion.cancel(el); active.clear();
+      change();
+      if (focused?.isConnected && container.contains(focused) && focused !== container.ownerDocument.activeElement) focused.focus({ preventScroll: true });
+      const pending = elements.filter(el => container.contains(el)).map(el => {
+        const first = before.get(el)!, last = el.getBoundingClientRect(), x = first.left - last.left, y = first.top - last.top;
+        if (Math.abs(x) < .5 && Math.abs(y) < .5) return Promise.resolve();
+        const rest = el.ownerDocument.defaultView!.getComputedStyle(el).transform;
+        active.add(el);
+        return motion.animate(el, [{ transform: `translate(${x}px, ${y}px) ${rest === 'none' ? '' : rest}` }, { transform: rest }], options);
+      });
+      await Promise.all(pending);
+      if (destroyed || revision !== own) return 'cancelled';
+      active.clear(); return 'finished';
+    },
+    destroy() { destroyed = true; ++revision; for (const el of active) motion.cancel(el); active.clear(); },
+  };
+}

package/src/motion/tabs.ts

@@ -0,0 +1,105 @@
+import type { MotionController, MotionResult } from './controller.js';
+import { preserveStyles } from './structure.js';
+import { enhanceNavigation } from '../web-motion/navigation.js';
+
+export interface MotionTab { key: string; tab: HTMLButtonElement; panel: HTMLElement }
+export interface MotionTabsOptions {
+  /** Automatic selects with arrows. Manual selects with Enter/Space. */
+  activation?: 'automatic' | 'manual';
+  orientation?: 'horizontal' | 'vertical';
+  onChange?: (key: string) => void;
+}
+
+/** Local web helper for app-owned tabs. Panels remain mounted, preserving input state.
+ * Supply unique tab/panel IDs, a labelled tablist and one shared panel container. */
+export function createMotionTabs(tablist: HTMLElement, items: MotionTab[], motion: MotionController, options: MotionTabsOptions = {}) {
+  const host = items[0]?.panel.parentElement;
+  if (!items.length || !host || new Set(items.map(i => i.key)).size !== items.length || items.some(i => !i.key || !i.tab.id || !i.panel.id || !tablist.contains(i.tab) || i.panel.parentElement !== host)) throw Error('Tabs need unique keys, tab/panel IDs and a shared panel container.');
+  if (new Set(items.flatMap(i => [i.tab.id, i.panel.id])).size !== items.length * 2) throw Error('Tab and panel IDs must be unique.');
+  const enabled = (i: MotionTab) => !i.tab.disabled && i.tab.getAttribute('aria-disabled') !== 'true';
+  let selected = items.find(i => enabled(i) && i.tab.getAttribute('aria-selected') === 'true') || items.find(enabled);
+  if (!selected) throw Error('Tabs require an enabled tab.');
+  let dead = false, revision = 0, release = () => {};
+  const win = host.ownerDocument.defaultView!;
+  const attributes = (el: HTMLElement, keys: string[]) => {
+    const saved = keys.map(k => [k, el.getAttribute(k)]);
+    return () => { for (const [key, value] of saved) { if (value === null) el.removeAttribute(key!); else el.setAttribute(key!, value!); } };
+  };
+  const restores = [attributes(tablist, ['role', 'aria-orientation'])];
+  tablist.setAttribute('role', 'tablist'); tablist.setAttribute('aria-orientation', options.orientation || 'horizontal');
+  for (const item of items) {
+    restores.push(attributes(item.tab, ['role', 'aria-controls', 'aria-selected', 'tabindex', 'type']), attributes(item.panel, ['role', 'aria-labelledby', 'aria-hidden', 'hidden', 'inert', 'tabindex']));
+    item.tab.type = 'button'; item.tab.setAttribute('role', 'tab'); item.tab.setAttribute('aria-controls', item.panel.id);
+    item.panel.setAttribute('role', 'tabpanel'); item.panel.setAttribute('aria-labelledby', item.tab.id); item.panel.tabIndex = 0;
+  }
+  function semantics() {
+    for (const item of items) {
+      const active = item === selected;
+      item.tab.setAttribute('aria-selected', String(active)); item.tab.tabIndex = active ? 0 : -1;
+      item.panel.inert = !active; item.panel.setAttribute('aria-hidden', String(!active));
+    }
+  }
+  semantics(); for (const item of items) item.panel.hidden = item !== selected;
+  const indicator = enhanceNavigation(tablist, motion, 'tabs');
+  async function select(key: string): Promise<MotionResult> {
+    const next = items.find(i => i.key === key);
+    if (dead || !next || !enabled(next)) return 'cancelled';
+    if (next === selected) { semantics(); return 'finished'; }
+    const own = ++revision, old = selected!;
+    const height = host!.getBoundingClientRect().height;
+    const from = win.getComputedStyle(old.panel).opacity;
+    const incoming = next.panel.hidden ? '0' : win.getComputedStyle(next.panel).opacity;
+    release(); selected = next;
+    if (items.some(i => i !== next && i.panel.contains(host!.ownerDocument.activeElement))) next.tab.focus({ preventScroll: true });
+    semantics();
+    for (const item of items) item.panel.hidden = item !== next && item !== old;
+    const restoreHost = preserveStyles(host!, ['position', 'height', 'overflow', 'box-sizing']);
+    const restoreOld = preserveStyles(old.panel, ['position', 'inset', 'width', 'box-sizing']);
+    let cleaned = false;
+    const finish = () => {
+      if (cleaned) return; cleaned = true;
+      motion.cancel(host!); motion.cancel(old.panel); motion.cancel(next.panel);
+      restoreOld(); restoreHost(); for (const item of items) item.panel.hidden = item !== selected;
+    };
+    release = finish;
+    try {
+      host!.style.position = 'relative'; host!.style.overflow = 'hidden'; host!.style.boxSizing = 'border-box';
+      old.panel.style.position = 'absolute'; old.panel.style.inset = '0 auto auto 0'; old.panel.style.width = '100%'; old.panel.style.boxSizing = 'border-box';
+      const targetHeight = host!.getBoundingClientRect().height;
+      host!.style.height = targetHeight + 'px';
+      const tasks = [
+        motion.animate(old.panel, [{ opacity: from }, { opacity: 0 }], { duration: 450, phase: 'exit', easing: 'ease-in-out' }, 'fade'),
+        motion.animate(next.panel, [{ opacity: incoming }, { opacity: 1 }], { duration: 450, easing: 'ease-in-out' }, 'fade'),
+        motion.animate(host!, [{ height: height + 'px' }, { height: targetHeight + 'px' }], { duration: 450, easing: 'ease-in-out' }),
+      ];
+      options.onChange?.(key);
+      await Promise.all(tasks);
+    } finally { if (revision === own) { finish(); release = () => {}; } }
+    return !dead && revision === own ? 'finished' : 'cancelled';
+  }
+  const click = (event: MouseEvent) => {
+    const item = items.find(i => i.tab.contains(event.target as Node));
+    if (item && enabled(item)) { item.tab.focus({ preventScroll: true }); void select(item.key); }
+  };
+  const keyboard = (event: KeyboardEvent) => {
+    const current = items.find(i => i.tab === event.target); if (!current) return;
+    const available = items.filter(enabled), index = available.indexOf(current);
+    const vertical = options.orientation === 'vertical', rtl = win.getComputedStyle(tablist).direction === 'rtl';
+    const back = vertical ? 'ArrowUp' : rtl ? 'ArrowRight' : 'ArrowLeft', forward = vertical ? 'ArrowDown' : rtl ? 'ArrowLeft' : 'ArrowRight';
+    let next: MotionTab | undefined;
+    if (event.key === back) next = available[(index - 1 + available.length) % available.length];
+    if (event.key === forward) next = available[(index + 1) % available.length];
+    if (event.key === 'Home') next = available[0];
+    if (event.key === 'End') next = available.at(-1);
+    if (next) {
+      event.preventDefault(); for (const item of items) item.tab.tabIndex = item === next ? 0 : -1;
+      next.tab.focus(); if (options.activation !== 'manual') void select(next.key);
+    }
+  };
+  tablist.addEventListener('click', click); tablist.addEventListener('keydown', keyboard);
+  return { get activeKey() { return selected!.key; }, select, destroy() {
+    if (dead) return; dead = true; ++revision; release(); indicator.destroy();
+    tablist.removeEventListener('click', click); tablist.removeEventListener('keydown', keyboard);
+    for (const restore of restores.reverse()) restore();
+  } };
+}

package/src/motion/tokens.ts

@@ -0,0 +1,2 @@
+/** Shared opt-in defaults in milliseconds. Explicit zero remains instant. */
+export const motionTiming = Object.freeze({ fast: 280, normal: 450, slow: 750, layout: 650, highlight: 1400, reduced: 200, maxDuration: 2000, maxDelay: 500 });