@blukavantui/community 1.0.1 → 1.2.0

package/src/motion/border-glow.ts

@@ -0,0 +1,41 @@
+import { preserveStyles } from './structure.js';
+
+export interface BorderGlowOptions {
+  /** One slow circuit in milliseconds, 4–60 seconds. Default: 12 seconds. */
+  duration?: number;
+  paused?: boolean;
+}
+const owners = new WeakSet<HTMLElement>();
+function duration(value: number = 12000) {
+  if (!Number.isFinite(value) || value < 4000 || value > 60000) throw Error('Border glow duration must be from 4000 to 60000 ms.');
+  return value;
+}
+/** Decorative, noninteractive border only. CSS honors the motion scope and OS.
+ * Pause automatically while outside the viewport or in a hidden document. */
+export function createBorderGlow(element: HTMLElement, options: BorderGlowOptions = {}) {
+  let time = duration(options.duration), paused = options.paused ?? false, visible = true, dead = false;
+  if (owners.has(element)) throw Error('This element already has a border glow.');
+  const doc = element.ownerDocument, win = doc.defaultView;
+  if (!win || !element.isConnected) throw Error('Mount a border glow on a connected browser element.');
+  const restore = preserveStyles(element, ['position']);
+  if (win.getComputedStyle(element).position === 'static') element.style.position = 'relative';
+  const overlay = doc.createElement('span'), rim = doc.createElement('span'), beam = doc.createElement('span');
+  overlay.className = 'blu-motion-border-glow'; rim.className = 'blu-motion-border-glow__rim';
+  beam.className = 'blu-motion-border-glow__beam'; rim.append(beam);
+  overlay.setAttribute('aria-hidden', 'true'); overlay.inert = true; overlay.append(rim); element.append(overlay); owners.add(element);
+  const sync = () => { overlay.style.setProperty('--blu-glow-duration', time + 'ms'); overlay.dataset.paused = String(paused || !visible || doc.hidden); };
+  const measure = () => overlay.style.setProperty('--blu-glow-size', Math.ceil(Math.hypot(element.offsetWidth + 4, element.offsetHeight + 4)) + 'px');
+  const resize = new ResizeObserver(measure); resize.observe(element); measure();
+  const intersection = typeof IntersectionObserver === 'function' ? new IntersectionObserver(entries => { visible = entries[0].isIntersecting; sync(); }) : null;
+  intersection?.observe(element); doc.addEventListener('visibilitychange', sync); sync();
+  return {
+    element: overlay,
+    update(next: BorderGlowOptions) {
+      if (dead) throw Error('Border glow is destroyed.');
+      if (next.duration !== undefined) time = duration(next.duration);
+      if (next.paused !== undefined) paused = next.paused;
+      sync();
+    },
+    destroy() { if (dead) return; dead = true; resize.disconnect(); intersection?.disconnect(); doc.removeEventListener('visibilitychange', sync); overlay.remove(); restore(); owners.delete(element); },
+  };
+}

package/src/motion/button.ts

@@ -0,0 +1,56 @@
+import { node, mountRoot, classes } from '../dom.js';
+import type { ButtonOptions, ButtonEvents, Component } from '../types.js';
+
+/** Draft web API; deliberately separate from the shared native Button until review. */
+export interface MotionButtonOptions extends ButtonOptions {
+  LoadingLabel?: string;
+  SpinnerPosition?: 'Leading' | 'Trailing';
+  /** Reserve space for known result labels to avoid shifting surrounding controls. */
+  ReserveLabels?: string[];
+  /** App-owned completion/failure message, announced outside the busy button. */
+  StatusText?: string;
+}
+export function createMotionButton(host: HTMLElement, initial: MotionButtonOptions, events: ButtonEvents = {}): Component<MotionButtonOptions> {
+  const root = mountRoot(host), button = node('button'), face = node('span', 'blu-motion-button__face');
+  const spinner = node('span', 'blu-button__spinner'), label = node('span'), status = node('span', 'blu-motion-sr-only');
+  let props = { ...initial }, disposed = false;
+  button.type = 'button';
+  spinner.setAttribute('aria-hidden', 'true');
+  status.setAttribute('role', 'status');
+  status.setAttribute('aria-atomic', 'true');
+  face.append(spinner, label);
+  button.append(face);
+  root.append(button, status);
+  button.onclick = event => {
+    if (props.IsLoading || props.IsDisabled) { event.preventDefault(); return; }
+    void events.Click?.(event);
+  };
+  const attr = (name: string, value?: string) => value === undefined ? button.removeAttribute(name) : button.setAttribute(name, value);
+  function update(patch: Partial<MotionButtonOptions>) {
+    if (disposed) throw new Error('Button is destroyed.');
+    props = { ...props, ...patch };
+    const loading = !!props.IsLoading;
+    button.className = classes(`blu-button blu-motion-button blu-button--${(props.Color || 'Primary').toLowerCase()} blu-button--${(props.Variant || 'Filled').toLowerCase()} blu-button--${(props.Size || 'Medium').toLowerCase()}${props.IsFullWidth ? ' blu-button--full' : ''}${loading ? ' blu-button--loading' : ''}`, props.ExtendedClass);
+    button.dataset.spinnerPosition = props.SpinnerPosition || 'Leading';
+    // aria-disabled keeps an in-progress action focusable. The click guard also covers keyboard/programmatic activation.
+    button.disabled = !!props.IsDisabled;
+    attr('aria-disabled', loading || props.IsDisabled ? 'true' : undefined);
+    attr('aria-busy', loading ? 'true' : undefined);
+    attr('aria-label', props.AccessibleLabel ? props.AccessibleLabel + (loading ? ' — ' + (props.LoadingLabel || 'Loading') : '') : undefined);
+    attr('aria-expanded', props.IsExpandable ? String(!!props.IsExpanded) : undefined);
+    attr('aria-controls', props.ControlsId);
+    attr('aria-current', props.IsCurrentPage ? 'page' : undefined);
+    label.textContent = loading ? (props.LoadingLabel || props.Label) : props.Label;
+    spinner.hidden = !loading;
+    for (const old of Array.from(button.querySelectorAll('.blu-motion-button__reserve'))) old.remove();
+    for (const text of new Set([props.Label, props.LoadingLabel || props.Label, ...(props.ReserveLabels || [])])) {
+      const reserve = node('span', 'blu-motion-button__reserve', text);
+      reserve.setAttribute('aria-hidden', 'true');
+      button.append(reserve);
+    }
+    const message = props.StatusText || '';
+    if (status.textContent !== message) status.textContent = message;
+  }
+  update({});
+  return { element: root, update, destroy() { if (disposed) return; disposed = true; button.onclick = null; root.remove(); } };
+}

package/src/motion/component-settings.ts

@@ -0,0 +1,147 @@
+import { motionEasings } from './effects.js';
+import type { MotionEasing } from './effects.js';
+import type { MotionController, MotionMode, MotionOptions, MotionTarget } from './controller.js';
+
+/** Local 1.2 component contract. Omitted values inherit collection defaults. */
+export interface ComponentMotionSettings {
+  mode?: 'inherit' | 'reduced' | 'off';
+  /** Override finite component transitions. Does not change spinner speed. Zero is instant. */
+  duration?: number;
+  easing?: MotionEasing;
+}
+export interface ComponentMotionHandle {
+  /** Replace this component's overrides; omit settings to inherit again. */
+  setMotion(settings?: ComponentMotionSettings): void;
+}
+export function validateComponentMotion(settings: ComponentMotionSettings): ComponentMotionSettings {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw Error('Motion settings must be an object.');
+  if (settings.mode !== undefined && !['inherit', 'reduced', 'off'].includes(settings.mode)) throw Error('Unknown component motion mode.');
+  if (settings.duration !== undefined && (!Number.isFinite(settings.duration) || settings.duration < 0 || settings.duration > 2000)) throw Error('Motion duration must be between 0 and 2000 ms.');
+  if (settings.easing !== undefined && !Object.hasOwn(motionEasings, settings.easing)) throw Error('Unknown motion easing.');
+  return Object.fromEntries(Object.entries(settings).filter(([key, value]) => ['mode', 'duration', 'easing'].includes(key) && value !== undefined));
+}
+
+/** Shared presentation state for WAAPI adapters and chart engines. */
+export function createComponentMotionState(root: HTMLElement, parent: { readonly mode: MotionMode }, initial: ComponentMotionSettings = {}) {
+  let settings = validateComponentMotion(initial), dead = false;
+  const previousMode = root.getAttribute('data-blu-motion');
+  const properties = ['--blu-component-motion-duration', '--blu-component-motion-ease'];
+  const originalStyles = properties.map(name => [name, root.style.getPropertyValue(name), root.style.getPropertyPriority(name)]);
+  function mode(): MotionMode {
+    if (parent.mode === 'off' || root.closest('.blu-motion-off,[data-blu-motion="off"]')) return 'off';
+    return parent.mode === 'reduced' || root.closest('[data-blu-motion="reduced"]') ? 'reduced' : 'full';
+  }
+  function apply() {
+    if (previousMode === 'off' || settings.mode === 'off') root.setAttribute('data-blu-motion', 'off');
+    else if (previousMode === 'reduced' || settings.mode === 'reduced') root.setAttribute('data-blu-motion', 'reduced');
+    else if (previousMode === null) root.removeAttribute('data-blu-motion');
+    else root.setAttribute('data-blu-motion', previousMode);
+    for (const [name, value, priority] of originalStyles) {
+      const next = name.endsWith('duration') ? settings.duration === undefined ? undefined : settings.duration + 'ms' : settings.easing ? motionEasings[settings.easing] : undefined;
+      if (next !== undefined) root.style.setProperty(name, next);
+      else if (value) root.style.setProperty(name, value, priority);
+      else root.style.removeProperty(name);
+    }
+  }
+  function resolveOptions(options: MotionOptions = {}): MotionOptions {
+    const duration = options.duration === 0 ? 0 : settings.duration ?? options.duration ?? 450;
+    return { ...options, duration: mode() === 'off' ? 0 : mode() === 'reduced' ? Math.min(duration, 200) : duration,
+      easing: settings.easing ?? options.easing, delay: mode() === 'full' ? options.delay : 0 };
+  }
+  apply();
+  return {
+    mode, resolveOptions, get settings() { return { ...settings }; },
+    update(next: ComponentMotionSettings) { if (dead) throw Error('Component motion is destroyed.'); settings = validateComponentMotion(next); apply(); },
+    destroy() {
+      if (dead) return; dead = true;
+      if (previousMode === null) root.removeAttribute('data-blu-motion'); else root.setAttribute('data-blu-motion', previousMode);
+      for (const [name, value, priority] of originalStyles) { if (value) root.style.setProperty(name, value, priority); else root.style.removeProperty(name); }
+    },
+  };
+}
+
+/** Minimal controller contract also usable from a native lifecycle adapter. */
+export interface TransitionMotion {
+  readonly mode: MotionMode;
+  animate(target: MotionTarget, frames: Keyframe[], options: { duration: number; easing?: MotionEasing }, reduced?: 'fade' | 'instant'): Promise<unknown>;
+  cancel(target: MotionTarget): void;
+}
+export function createTransitionMotionScope(root: HTMLElement, parent: TransitionMotion, initial: ComponentMotionSettings = {}) {
+  const state = createComponentMotionState(root, parent, initial), active = new Map<MotionTarget, object>();
+  let dead = false;
+  function settle() {
+    for (const target of active.keys()) parent.cancel(target); active.clear();
+    for (const animation of root.getAnimations({subtree:true})) {
+      if (typeof CSSTransition !== 'undefined' && animation instanceof CSSTransition) animation.cancel();
+    }
+  }
+  const motion: TransitionMotion = {
+    get mode() { return state.mode(); },
+    animate(target, frames, options, reduced = 'instant') {
+      if (dead) return Promise.resolve('cancelled');
+      if (state.mode() === 'off' || (state.mode() === 'reduced' && reduced === 'instant')) { parent.cancel(target); return Promise.resolve('finished'); }
+      const token = {}; active.set(target, token);
+      const safe = state.mode() === 'reduced' ? frames.map(f => ({opacity:f.opacity,offset:f.offset})) : frames;
+      try { return parent.animate(target, safe, state.resolveOptions(options) as {duration:number;easing?:MotionEasing}, reduced).finally(() => { if (active.get(target) === token) active.delete(target); }); }
+      catch (error) { if (active.get(target) === token) active.delete(target); throw error; }
+    },
+    cancel(target) { parent.cancel(target); active.delete(target); },
+  };
+  return {
+    motion,
+    update(next: ComponentMotionSettings) { if (dead) throw Error('Component motion is destroyed.'); const valid = validateComponentMotion(next); settle(); state.update(valid); },
+    destroy() { if (dead) return; dead = true; settle(); state.destroy(); },
+  };
+}
+
+/** An owned view of a shared controller, including portal exit decorations.
+ * No second system-preference listener or component event interception is needed.
+ */
+export function createComponentMotionScope(root: HTMLElement, parent: MotionController, initial: ComponentMotionSettings = {}) {
+  let destroyed = false;
+  const state = createComponentMotionState(root, parent, initial);
+  const { mode, resolveOptions } = state;
+  const active = new Map<MotionTarget, object>();
+  function cancelAll() {
+    for (const target of active.keys()) parent.cancel(target); active.clear();
+    // Settle finite CSS feedback too, without cancelling a real loading spinner.
+    for (const animation of root.getAnimations({ subtree: true })) {
+      if (typeof CSSTransition !== 'undefined' && animation instanceof CSSTransition) animation.cancel();
+    }
+  }
+  function run(target: MotionTarget, task: () => ReturnType<MotionController['play']>) {
+    if (destroyed) return Promise.resolve('cancelled' as const);
+    const token = {}; active.set(target, token);
+    try { return task().finally(() => { if (active.get(target) === token) active.delete(target); }); }
+    catch (error) { if (active.get(target) === token) active.delete(target); throw error; }
+  }
+  const motion: MotionController = {
+    get mode() { return mode(); }, get preference() { return mode() === 'off' ? 'off' : mode() === 'reduced' ? 'reduced' : parent.preference; },
+    setPreference(preference) { update({ ...state.settings, mode: preference === 'system' ? 'inherit' : preference }); },
+    resolveOptions,
+    play(target, effect, options) {
+      return run(target, () => parent.play(target, mode() === 'reduced' ? 'fade' : effect, resolveOptions(options)));
+    },
+    animate(target, frames, options, reduced = 'instant') {
+      return run(target, () => {
+        if (mode() === 'off' || (mode() === 'reduced' && reduced === 'instant')) { parent.cancel(target); return Promise.resolve('finished'); }
+        // Reduced exit fades retain captured opacity; no transform/filter/geometry.
+        const safeFrames = mode() === 'reduced' ? frames.map(frame => ({ opacity: frame.opacity, offset: frame.offset })) : frames;
+        return parent.animate(target, safeFrames, resolveOptions(options), reduced);
+      });
+    },
+    tween(target, from, to, render, options) {
+      return run(target, () => parent.tween(target, from, to, render, { ...resolveOptions(options), ...(mode() !== 'full' ? { duration: 0 } : {}) }));
+    },
+    cancel(target) { parent.cancel(target); active.delete(target); },
+    destroy() {
+      if (destroyed) return; destroyed = true; cancelAll();
+      state.destroy();
+    },
+  };
+  function update(next: ComponentMotionSettings) {
+    if (destroyed) throw Error('Component motion is destroyed.');
+    const valid = validateComponentMotion(next); cancelAll(); state.update(valid);
+  }
+  return { motion, update, destroy: () => motion.destroy() };
+}

package/src/motion/controller.ts

@@ -0,0 +1,191 @@
+import { motionTiming } from './tokens.js';
+/** Web-only 1.2 development API. No global listeners are installed at import time. */
+import { motionEasings, motionFrames, motionOrigins } from './effects.js';
+import type { MotionEffect, MotionPhase, MotionEasing, MotionOrigin } from './effects.js';
+export type { MotionEffect, MotionPhase, MotionEasing } from './effects.js';
+export type MotionPreference = 'system' | 'reduced' | 'off';
+export type MotionMode = 'full' | 'reduced' | 'off';
+export type MotionResult = 'finished' | 'cancelled';
+export type MotionTarget = HTMLElement | SVGElement;
+export interface MotionOptions {
+  phase?: MotionPhase;
+  duration?: number;
+  delay?: number;
+  easing?: MotionEasing;
+  /** Scale/rotation anchor. Does not move or position the target itself. */
+  origin?: MotionOrigin;
+}
+export interface MotionController {
+  readonly mode: MotionMode;
+  readonly preference: MotionPreference;
+  setPreference(preference: MotionPreference): void;
+  /** Component-scoped timing resolver, used by bounded visual-cleanup deadlines. */
+  resolveOptions?(options?: MotionOptions): MotionOptions;
+  play(element: HTMLElement, effect?: MotionEffect, options?: MotionOptions): Promise<MotionResult>;
+  /** Custom frames use instant reduced motion unless a fade is explicitly requested. */
+  animate(element: MotionTarget, frames: Keyframe[], options?: MotionOptions, reduced?: 'instant' | 'fade'): Promise<MotionResult>;
+  /** Numeric interpolation shares cancellation and preference handling with other effects. */
+  tween(element: MotionTarget, from: number, to: number, render: (value: number) => void, options?: MotionOptions): Promise<MotionResult>;
+  cancel(element: MotionTarget): void;
+  destroy(): void;
+}
+
+const owners = new WeakSet<HTMLElement>();
+export function resolveMotionMode(preference: MotionPreference, systemReduced: boolean): MotionMode {
+  return preference === 'off' ? 'off' : preference === 'reduced' || systemReduced ? 'reduced' : 'full';
+}
+export function boundedTime(value: number | undefined, fallback: number, maximum = 2000): number {
+  return value !== undefined && Number.isFinite(value) ? Math.min(maximum, Math.max(0, value)) : fallback;
+}
+function cssMilliseconds(value: string, fallback: number) {
+  const match = /^([\d.]+)(ms|s)$/.exec(value.trim());
+  return match ? boundedTime(Number(match[1]) * (match[2] === 's' ? 1000 : 1), fallback) : fallback;
+}
+
+export function createMotionController(scope: HTMLElement, initial: MotionPreference = 'system'): MotionController {
+  if (!['system', 'reduced', 'off'].includes(initial)) throw new Error('Unknown motion preference.');
+  if (owners.has(scope)) throw new Error('This scope already has a motion controller.');
+  const win = scope.ownerDocument.defaultView;
+  if (!win) throw new Error('A browser document is required.');
+  const media = win.matchMedia('(prefers-reduced-motion: reduce)');
+  const previous = scope.getAttribute('data-blu-motion');
+  const active = new Map<MotionTarget, { cancel(): void }>();
+  let preference = initial, disposed = false;
+  const mode = () => resolveMotionMode(preference, media.matches);
+  function refresh() {
+    scope.setAttribute('data-blu-motion', mode());
+    // A preference change takes effect immediately, even during an exit.
+    for (const task of Array.from(active.values())) task.cancel();
+  }
+  owners.add(scope);
+  media.addEventListener('change', refresh);
+  refresh();
+  function allowed(element: MotionTarget) {
+    if (!scope.contains(element)) throw new Error('Motion target must be inside its controller scope.');
+    return mode() === 'full' && !element.closest?.('[data-blu-motion="off"], [data-blu-motion="reduced"], .blu-motion-off');
+  }
+  const controller: MotionController = {
+    get mode() { return mode(); },
+    get preference() { return preference; },
+    setPreference(value) {
+      if (disposed) throw new Error('Motion controller is destroyed.');
+      if (!['system', 'reduced', 'off'].includes(value)) throw new Error('Unknown motion preference.');
+      preference = value;
+      refresh();
+    },
+    cancel(element) { active.get(element)?.cancel(); },
+    animate(element, frames, options = {}, reduced = 'instant') {
+      if (disposed) return Promise.resolve('cancelled');
+      const full = allowed(element);
+      active.get(element)?.cancel();
+      if (!full) {
+        if (reduced === 'fade' && mode() !== 'off' && !element.closest('.blu-motion-off, [data-blu-motion="off"]')) {
+          return controller.play(element as HTMLElement, 'fade', { ...options, duration: Math.min(options.duration ?? 200, 200), delay: 0 });
+        }
+        return Promise.resolve('finished');
+      }
+      const duration = boundedTime(options.duration, motionTiming.normal);
+      if (!duration || !element.animate) return Promise.resolve('finished');
+      return new Promise<MotionResult>((resolve) => {
+        const animation = element.animate(frames, { duration, delay: boundedTime(options.delay, 0, 500), easing: motionEasings[options.easing || 'standard'], fill: 'both' });
+        let settled = false;
+        const task = { cancel: () => finish('cancelled') };
+        function finish(result: MotionResult) {
+          if (settled) return;
+          settled = true;
+          if (active.get(element) === task) active.delete(element);
+          animation.cancel(); resolve(result);
+        }
+        active.set(element, task);
+        animation.finished.then(() => finish('finished'), () => finish('cancelled'));
+      });
+    },
+    tween(element, from, to, render, options = {}) {
+      if (!Number.isFinite(from) || !Number.isFinite(to)) throw new Error('Numeric motion requires finite values.');
+      if (disposed) return Promise.resolve('cancelled');
+      const full = allowed(element);
+      active.get(element)?.cancel();
+      const duration = boundedTime(options.duration, motionTiming.normal), delay = boundedTime(options.delay, 0, 500);
+      if (!full || !duration || !win.requestAnimationFrame) { render(to); return Promise.resolve('finished'); }
+      return new Promise<MotionResult>((resolve, reject) => {
+        let frame = 0, start: number | undefined, settled = false;
+        const task = { cancel: () => finish('cancelled') };
+        function finish(result: MotionResult) {
+          if (settled) return;
+          settled = true; win!.cancelAnimationFrame(frame);
+          if (active.get(element) === task) active.delete(element);
+          resolve(result);
+        }
+        function tick(now: number) {
+          if (settled) return;
+          start ??= now;
+          const progress = Math.min(1, Math.max(0, (now - start - delay) / duration));
+          try { render(progress === 1 ? to : from + (to - from) * easeProgress(progress, options.easing || 'standard')); }
+          catch (error) { settled = true; active.delete(element); reject(error); return; }
+          if (progress === 1) finish('finished'); else frame = win!.requestAnimationFrame(tick);
+        }
+        active.set(element, task); frame = win.requestAnimationFrame(tick);
+      });
+    },
+    play(element, effect = 'fade', options = {}) {
+      if (disposed) return Promise.resolve('cancelled');
+      if (!scope.contains(element)) throw new Error('Motion target must be inside its controller scope.');
+      active.get(element)?.cancel();
+      if (mode() === 'off' || element.closest?.('.blu-motion-off, [data-blu-motion="off"]') || !element.animate) return Promise.resolve('finished');
+      const reduced = mode() === 'reduced' || !!element.closest?.('[data-blu-motion="reduced"]');
+      const css = win.getComputedStyle(element);
+      const requestedDuration = boundedTime(options.duration, cssMilliseconds(css.getPropertyValue('--blu-motion-duration'), motionTiming.normal));
+      const duration = reduced ? Math.min(requestedDuration || (options.duration === 0 ? 0 : 200), 200) : requestedDuration;
+      if (!duration) return Promise.resolve('finished');
+      const distance = css.getPropertyValue('--blu-motion-distance').trim() || '12px';
+      // Reduced motion uses a short opacity change, never spatial movement.
+      const frames = motionFrames(reduced ? 'fade' : effect, options.phase, distance);
+      if (!reduced && options.origin) {
+        if (!(options.origin in motionOrigins)) throw new Error('Unknown motion origin.');
+        for (const frame of frames) frame.transformOrigin = motionOrigins[options.origin];
+      }
+      const easing = options.easing ? motionEasings[options.easing] : css.getPropertyValue('--blu-motion-ease').trim() || motionEasings.standard;
+      if (!easing) throw new Error('Unknown motion easing.');
+      return new Promise<MotionResult>((resolve) => {
+        let settled = false;
+        const animation = element.animate(frames, {
+          duration, delay: reduced ? 0 : boundedTime(options.delay, 0, 500),
+          easing: reduced ? motionEasings['ease-out'] : easing,
+          fill: 'both',
+        });
+        const task = { cancel: () => finish('cancelled') };
+        function finish(result: MotionResult) {
+          if (settled) return;
+          settled = true;
+          if (active.get(element) === task) active.delete(element);
+          animation.cancel(); // Never leave fill styles or detached animations behind.
+          resolve(result);
+        }
+        active.set(element, task);
+        animation.finished.then(() => finish('finished'), () => finish('cancelled'));
+      });
+    },
+    destroy() {
+      if (disposed) return;
+      disposed = true;
+      media.removeEventListener('change', refresh);
+      for (const task of Array.from(active.values())) task.cancel();
+      if (previous === null) scope.removeAttribute('data-blu-motion');
+      else scope.setAttribute('data-blu-motion', previous);
+      owners.delete(scope);
+    },
+  };
+  return controller;
+}
+
+/** Solve cubic-bezier x before sampling y, so numeric motion matches CSS timing. */
+export function easeProgress(progress: number, easing: MotionEasing): number {
+  if (progress <= 0) return 0;
+  if (progress >= 1) return 1;
+  if (easing === 'linear') return progress;
+  const [x1, y1, x2, y2] = motionEasings[easing].match(/[\d.]+/g)!.map(Number);
+  const curve = (t: number, a: number, b: number) => 3 * (1-t) ** 2 * t * a + 3 * (1-t) * t * t * b + t ** 3;
+  let low = 0, high = 1;
+  for (let i = 0; i < 20; i++) { const mid = (low + high) / 2; if (curve(mid, x1, x2) < progress) low = mid; else high = mid; }
+  return curve((low + high) / 2, y1, y2);
+}

package/src/motion/effects.ts

@@ -0,0 +1,75 @@
+/** Shared preset definitions: used by the controller and the CSS generator. */
+export const motionEffects = [
+  'fade', 'slide-up', 'slide-down', 'slide-left', 'slide-right',
+  'zoom-in', 'zoom-out', 'rotate-left', 'rotate-right', 'flip-x', 'flip-y', 'pop', 'bounce',
+  'wipe-up', 'wipe-down', 'wipe-left', 'wipe-right',
+  'circle-reveal', 'blur-clear',
+] as const;
+export const motionOrigins = {
+  center: '50% 50%', top: '50% 0%', bottom: '50% 100%', left: '0% 50%', right: '100% 50%',
+  'top-left': '0% 0%', 'top-right': '100% 0%', 'bottom-left': '0% 100%', 'bottom-right': '100% 100%',
+} as const;
+export type MotionOrigin = keyof typeof motionOrigins;
+export type MotionPreset = typeof motionEffects[number];
+export type MotionEffect = MotionPreset | 'scale';
+export type MotionPhase = 'enter' | 'exit';
+export const motionEasings = {
+  standard: 'cubic-bezier(.2,.8,.2,1)',
+  'ease-in': 'cubic-bezier(.42,0,1,1)',
+  'ease-out': 'cubic-bezier(0,0,.58,1)',
+  'ease-in-out': 'cubic-bezier(.42,0,.58,1)',
+  linear: 'linear',
+  spring: 'cubic-bezier(.34,1.25,.64,1)',
+} as const;
+export type MotionEasing = keyof typeof motionEasings;
+
+/** Names describe movement: slide-left enters from the right and exits toward the left. */
+export function motionFrames(effect: MotionEffect, phase: MotionPhase = 'enter', distance = '12px'): Keyframe[] {
+  const exit = phase === 'exit';
+  const signed = (negative: boolean) => negative ? `calc(-1 * ${distance})` : distance;
+  const spatial: Record<string, string> = {
+    'slide-up': `translateY(${signed(exit)})`,
+    'slide-down': `translateY(${signed(!exit)})`,
+    'slide-left': `translateX(${signed(exit)})`,
+    'slide-right': `translateX(${signed(!exit)})`,
+    'zoom-in': `scale(${exit ? '1.08' : '.92'})`,
+    'zoom-out': `scale(${exit ? '.92' : '1.08'})`,
+    scale: `scale(${exit ? '1.03' : '.97'})`, // Legacy draft effect remains supported.
+    'rotate-left': `rotate(${exit ? '-8' : '8'}deg) scale(.97)`,
+    'rotate-right': `rotate(${exit ? '8' : '-8'}deg) scale(.97)`,
+    'flip-x': `perspective(600px) rotateX(${exit ? '-30' : '30'}deg)`,
+    'flip-y': `perspective(600px) rotateY(${exit ? '-30' : '30'}deg)`,
+  };
+  if (effect === 'fade') return exit ? [{ opacity: 1 }, { opacity: 0 }] : [{ opacity: 0 }, { opacity: 1 }];
+  if (effect === 'circle-reveal' || effect === 'blur-clear') {
+    const edge = effect === 'circle-reveal' ? { opacity: 0, clipPath: 'circle(0% at 50% 50%)' } : { opacity: 0, filter: 'blur(6px)' };
+    const rest = effect === 'circle-reveal' ? { opacity: 1, clipPath: 'circle(72% at 50% 50%)' } : { opacity: 1, filter: 'blur(0px)' };
+    return exit ? [rest, edge] : [edge, rest];
+  }
+  if (effect.startsWith('wipe-')) {
+    const edges: Record<string, [string, string]> = {
+      'wipe-up': ['inset(100% 0 0 0)', 'inset(0 0 100% 0)'],
+      'wipe-down': ['inset(0 0 100% 0)', 'inset(100% 0 0 0)'],
+      'wipe-left': ['inset(0 0 0 100%)', 'inset(0 100% 0 0)'],
+      'wipe-right': ['inset(0 100% 0 0)', 'inset(0 0 0 100%)'],
+    };
+    const rest = { opacity: 1, clipPath: 'inset(0 0 0 0)' };
+    return exit ? [rest, { opacity: 0, clipPath: edges[effect][1] }] : [{ opacity: 0, clipPath: edges[effect][0] }, rest];
+  }
+  if (effect === 'pop') return exit
+    ? [{ opacity: 1, transform: 'scale(1)' }, { opacity: 1, transform: 'scale(1.025)', offset: .25 }, { opacity: 0, transform: 'scale(.9)' }]
+    : [{ opacity: 0, transform: 'scale(.9)' }, { opacity: 1, transform: 'scale(1.025)', offset: .72 }, { opacity: 1, transform: 'scale(1)' }];
+  if (effect === 'bounce') return exit
+    ? [{ opacity: 1, transform: 'translateY(0)' }, { opacity: 1, transform: 'translateY(-3px)', offset: .25 }, { opacity: 0, transform: `translateY(${distance})` }]
+    : [{ opacity: 0, transform: `translateY(${distance})` }, { opacity: 1, transform: 'translateY(-3px)', offset: .72 }, { opacity: 1, transform: 'translateY(0)' }];
+  if (!(effect in spatial)) throw new Error('Unknown motion effect.');
+  const edge = { opacity: 0, transform: spatial[effect] }, rest = { opacity: 1, transform: 'none' };
+  return exit ? [rest, edge] : [edge, rest];
+}
+
+export function motionClass(effect: MotionPreset, phase: MotionPhase = 'enter') {
+  return `blu-motion-${phase}-${effect}`;
+}
+export function motionEasingClass(easing: MotionEasing) {
+  return `blu-motion-${easing.startsWith('ease-') ? easing : 'ease-' + easing}`;
+}

package/src/motion/feedback.ts

@@ -0,0 +1,41 @@
+import type { MotionController, MotionOptions } from './controller.js';
+
+export function playFeedback(element: HTMLElement, motion: MotionController, effect: 'highlight' | 'nudge', options: MotionOptions = {}) {
+  const css = element.ownerDocument.defaultView!.getComputedStyle(element), rest = css.transform;
+  return effect === 'highlight'
+    ? motion.animate(element, [{ boxShadow: css.boxShadow }, { boxShadow: '0 0 0 4px var(--blu-motion-highlight, #7770ed40)', offset: .45 }, { boxShadow: css.boxShadow }], { duration: 1400, easing: 'ease-in-out', ...options })
+    : motion.animate(element, [{ transform: rest }, { transform: `translateX(-3px) ${rest === 'none' ? '' : rest}`, offset: .25 }, { transform: `translateX(3px) ${rest === 'none' ? '' : rest}`, offset: .6 }, { transform: rest }], { duration: 280, ...options });
+}
+
+/** Decorative feedback only: does not call click, prevent native activation, or alter button state. */
+export function createPressFeedback(element: HTMLElement, motion: MotionController) {
+  const original = element.getAttribute('data-blu-pressed'), hadClass = element.classList.contains('blu-motion-press');
+  const win = element.ownerDocument.defaultView!;
+  let pressed = false, destroyed = false, pointer: number | null = null, key: string | null = null;
+  element.classList.add('blu-motion-press');
+  function set(next: boolean) {
+    if (destroyed || next === pressed) return;
+    if (next && (element.matches(':disabled') || element.getAttribute('aria-disabled') === 'true' || element.closest('[inert]'))) return;
+    const from = win.getComputedStyle(element).transform;
+    motion.cancel(element); pressed = next;
+    element.setAttribute('data-blu-pressed', String(next));
+    const to = win.getComputedStyle(element).transform;
+    void motion.animate(element, [{ transform: from }, { transform: to }], { duration: 280, easing: 'ease-out' });
+  }
+  const down = (event: PointerEvent) => { if (event.button === 0 && event.isPrimary) { pointer = event.pointerId; set(true); } };
+  const up = (event: PointerEvent) => { if (event.pointerId === pointer) { pointer = null; if (!key) set(false); } };
+  const keydown = (event: KeyboardEvent) => { if (!event.repeat && [' ', 'Enter'].includes(event.key)) { key = event.key; set(true); } };
+  const keyup = (event: KeyboardEvent) => { if (event.key === key) { key = null; if (pointer === null) set(false); } };
+  const reset = () => { pointer = null; key = null; set(false); };
+  element.addEventListener('pointerdown', down); win.addEventListener('pointerup', up); win.addEventListener('pointercancel', up);
+  element.addEventListener('keydown', keydown); win.addEventListener('keyup', keyup);
+  element.addEventListener('blur', reset); win.addEventListener('blur', reset);
+  return { destroy() {
+    if (destroyed) return; destroyed = true; motion.cancel(element);
+    element.removeEventListener('pointerdown', down); win.removeEventListener('pointerup', up); win.removeEventListener('pointercancel', up);
+    element.removeEventListener('keydown', keydown); win.removeEventListener('keyup', keyup);
+    element.removeEventListener('blur', reset); win.removeEventListener('blur', reset);
+    if (!hadClass) element.classList.remove('blu-motion-press');
+    if (original === null) element.removeAttribute('data-blu-pressed'); else element.setAttribute('data-blu-pressed', original);
+  } };
+}

package/src/motion/loading.ts

@@ -0,0 +1,40 @@
+import { node, mountRoot } from '../dom.js';
+import type { Component } from '../types.js';
+export interface LoadingIndicatorOptions {
+  Label: string;
+  Variant?: 'Spinner' | 'Dots' | 'Bar';
+  /** Real completion percentage, 0–100. Omit when the amount of work is unknown. */
+  Progress?: number;
+}
+export function normalizeProgress(value: number | undefined): number | undefined {
+  return value !== undefined && Number.isFinite(value) ? Math.min(100, Math.max(0, value)) : undefined;
+}
+export function createLoadingIndicator(host: HTMLElement, initial: LoadingIndicatorOptions): Component<LoadingIndicatorOptions> {
+  const root = mountRoot(host), label = node('span'), visual = node('span', 'blu-loading__visual'), progress = node('progress'), bar = node('span', 'blu-loading__bar');
+  let props = { ...initial }, disposed = false;
+  root.className = 'blu-loading';
+  label.id = root.id + '-label';
+  visual.setAttribute('aria-hidden', 'true');
+  for (let i = 0; i < 3; i++) visual.append(node('i'));
+  progress.max = 100;
+  progress.setAttribute('aria-labelledby', label.id);
+  bar.setAttribute('role', 'progressbar');
+  bar.setAttribute('aria-labelledby', label.id);
+  root.append(visual, progress, bar, label);
+  function update(patch: Partial<LoadingIndicatorOptions>) {
+    if (disposed) throw new Error('Loading indicator is destroyed.');
+    props = { ...props, ...patch };
+    const value = normalizeProgress(props.Progress), isBar = value !== undefined || props.Variant === 'Bar';
+    root.dataset.variant = isBar ? 'Bar' : props.Variant || 'Spinner';
+    label.textContent = props.Label;
+    visual.hidden = isBar;
+    progress.hidden = value === undefined;
+    bar.hidden = !isBar || value !== undefined;
+    if (isBar) { root.removeAttribute('role'); root.removeAttribute('aria-labelledby'); }
+    else { root.setAttribute('role', 'status'); root.setAttribute('aria-labelledby', label.id); }
+    if (value === undefined) progress.removeAttribute('value');
+    else progress.value = value;
+  }
+  update({});
+  return { element: root, update, destroy() { if (disposed) return; disposed = true; root.remove(); } };
+}