@blukavantui/community 1.1.0 → 1.2.0

package/src/native-motion.ts

@@ -0,0 +1,188 @@
+/** Private, unpublished O11 1.2 integration. Enhances stable native wrappers; never owns their children. */
+import { createMotionController, type MotionController, type MotionEffect } from './motion/controller.js';
+import { createComponentMotionScope, validateComponentMotion, type ComponentMotionSettings } from './motion/component-settings.js';
+import { motionEffects, motionOrigins, type MotionOrigin } from './motion/effects.js';
+import { createRipple } from './motion/optional.js';
+import { createPressFeedback } from './motion/feedback.js';
+import { createMotionPresence } from './motion/presence.js';
+import { enhanceField } from './web-motion/fields.js';
+import { nativeComponentAdapter } from './native-motion-components.js';
+import { nativeFoundationAdapter } from './native-motion-foundations.js';
+import { observeSurface } from './web-motion/surfaces.js';
+
+export interface NativeMotionOptions {
+  EnableMotion?: boolean;
+  Preference?: 'System' | 'Reduced' | 'Off';
+  UseDefaultDuration?: boolean;
+  DurationMs?: number;
+  Easing?: ComponentMotionSettings['easing'];
+  Effect?: MotionEffect; Origin?: MotionOrigin; Phase?: 'enter'|'exit';
+  ReplayKey?: string;
+  ActivePanel?: string;
+  FocusFallbackId?: string;
+  Ripple?: boolean;
+  Value?: number; Precision?: number; Locale?: string;
+  IsVisible?: boolean; IsActive?: boolean; Paused?: boolean;
+  Once?: boolean; Order?: string; Columns?: number; GapMs?: number;
+  LoopDurationMs?: number; Decoration?: string;
+  RowKeysJson?: string; RowsJson?: string; ColumnsJson?: string; RowKey?: string; Page?: number; PageSize?: number; SortKey?: string; SortDirection?: string; Loading?: boolean;
+  Progress?: number; Label?: string; Variant?: string;
+}
+export type Kind = string;
+export type Adapter = { update(p: NativeMotionOptions): void; capture?(): void; destroy(): void };
+type Owner = { root: HTMLElement; kind: Kind; parent?: Owner; controller?: MotionController; scope?: ReturnType<typeof createComponentMotionScope>; adapter: Adapter; signature: string; priorKind: string | null; options: NativeMotionOptions };
+
+export function nativeMotionSettings(p: NativeMotionOptions): ComponentMotionSettings {
+  const preference = p.Preference ?? 'System';
+  if (!['System', 'Reduced', 'Off'].includes(preference)) throw Error('Preference must be System, Reduced or Off.');
+  if (p.Effect !== undefined && !(motionEffects as readonly string[]).includes(p.Effect) && p.Effect !== 'scale') throw Error('Unknown motion effect.');
+  if (p.UseDefaultDuration === false && p.DurationMs === undefined) throw Error('DurationMs is required when UseDefaultDuration is False.');
+  if(p.Origin!==undefined&&!(p.Origin in motionOrigins))throw Error('Unknown transform origin.');
+  if(p.Phase!==undefined&&!['enter','exit'].includes(p.Phase))throw Error('Unknown motion phase.');
+  return validateComponentMotion({ mode: preference === 'System' ? 'inherit' : preference.toLowerCase() as 'reduced' | 'off',
+    duration: p.UseDefaultDuration === false ? p.DurationMs : undefined, easing: p.Easing });
+}
+
+/** Multiple producer scripts share this registry, never overlapping body controllers. */
+export function createNativeMotionRuntime() {
+  const extensions = new Map<string, (root: HTMLElement, motion: MotionController) => Adapter>();
+  const owners = new Map<string, Owner>();
+  const hosts = new WeakMap<HTMLElement, string>();
+  function actionOwner(id:string) {
+    if(owners.has(id))return owners.get(id);
+    // Consumers can pass the Id of their own Container inside a provider;
+    // they never need access to a producer Block's private widget names.
+    for(let el=document.getElementById(id);el;el=el.parentElement){const owner=owners.get(hosts.get(el)||'');if(owner)return owner;}
+  }
+  function parentOf(root: HTMLElement): Owner | undefined {
+    for (let el = root.parentElement; el; el = el.parentElement) {
+      const owner = owners.get(hosts.get(el) || '');
+      if (owner?.kind === 'provider') return owner;
+    }
+  }
+  function destroy(id: string) {
+    const owner = owners.get(id); if (!owner) return;
+    // Children release their adapters before a screen provider disappears.
+    for (const [childId, child] of owners) if (child.parent === owner) destroy(childId);
+    owner.adapter.destroy(); owner.scope?.destroy(); owner.controller?.destroy();
+    if (owner.priorKind === null) owner.root.removeAttribute('data-blu-native-motion');
+    else owner.root.setAttribute('data-blu-native-motion', owner.priorKind);
+    owners.delete(id); if (hosts.get(owner.root) === id) hosts.delete(owner.root);
+  }
+  function makeAdapter(kind: Kind, root: HTMLElement, motion: MotionController): Adapter {
+    const extension = extensions.get(kind);
+    if(extension) return extension(root, motion);
+    const foundation = nativeFoundationAdapter(kind, root, motion);
+    if(foundation) return foundation;
+    const component = nativeComponentAdapter(kind, root, motion);
+    if(component) return component;
+    if (kind === 'chart') return {update() {},destroy() {}};
+    if (kind === 'modal') {
+      // The original modal owns focus, events and slots. Only its JS-created
+      // surface is enhanced; closing copies are inert, unnamed visual decoration.
+      const surface = observeSurface(root, motion, 'modal');
+      return { update() { surface.sync(); }, capture: surface.capture, destroy: surface.destroy };
+    }
+    if (kind === 'button') {
+      const press = createPressFeedback(root, motion);
+      let ripple: ReturnType<typeof createRipple> | undefined;
+      let busy = root.getAttribute('aria-busy'), face: HTMLElement | null = null;
+      const refresh = () => {
+        const next = root.getAttribute('aria-busy');
+        if (next === busy) return;
+        busy = next; if (face) motion.cancel(face);
+        face = root.querySelector<HTMLElement>('.blu-button-content');
+        // Native If widgets still own the label/spinner. Fade the stable face only.
+        if (face) void motion.play(face, 'fade', { duration: 350 });
+      };
+      const observer = new MutationObserver(refresh);
+      observer.observe(root, { attributes: true, attributeFilter: ['aria-busy'], childList: true, subtree: true });
+      return { update(p) { if(p.Ripple && !ripple) ripple=createRipple(root,motion); else if(!p.Ripple && ripple){ripple.destroy();ripple=undefined;} refresh(); }, destroy() { ripple?.destroy(); observer.disconnect(); if (face) motion.cancel(face); press.destroy(); } };
+    }
+    if (kind === 'field') {
+      let target: HTMLElement | null = null, field: ReturnType<typeof enhanceField> | undefined;
+      return { update() {
+        const next = root.matches('.blu-field') ? root : root.querySelector<HTMLElement>('.blu-field');
+        if (next !== target) { field?.destroy(); target = next; field = target ? enhanceField(target, motion) : undefined; }
+        field?.sync();
+      }, destroy() { field?.destroy(); } };
+    }
+    if (kind === 'workspace') {
+      const panels = Array.from(root.children).filter((el): el is HTMLElement => el instanceof HTMLElement && el.classList.contains('blu-native-workspace-panel'));
+      if (panels.length !== 2) throw Error('WorkspaceTransition requires two stable native panel wrappers.');
+      const presence = panels.map(el => createMotionPresence(el, motion));
+      let active = -1, dead = false, revision = 0;
+      return { update(p) {
+        const next = p.ActivePanel === 'Second' ? 1 : 0;
+        if (next === active) return;
+        const old = active; active = next; const own = ++revision;
+        const fallback = (p.FocusFallbackId ? root.ownerDocument.getElementById(p.FocusFallbackId) : root) || root;
+        if (old < 0) { panels.forEach((panel, i) => { panel.hidden = i !== next; panel.inert = i !== next; }); return; }
+        // Existing values and nodes stay in place; application state already changed.
+        if (panels[old].contains(root.ownerDocument.activeElement)) fallback.focus({ preventScroll: true });
+        if (panels[old].contains(root.ownerDocument.activeElement)) root.focus({ preventScroll: true });
+        const options = { effect: p.Effect || 'fade' as MotionEffect, duration: 650, focusFallback: root };
+        void presence[old].hide(options).then(() => { if (!dead && own === revision) panels[old].inert = true; });
+        void presence[next].show(options);
+      }, destroy() { dead = true; ++revision; presence.forEach(p => p.destroy()); } };
+    }
+    if(!['container','provider'].includes(kind)) throw Error('Unsupported native motion adapter: '+kind);
+    let replay: string | undefined;
+    return { update(p) {
+      if (kind !== 'container' || p.ReplayKey === replay) return;
+      replay = p.ReplayKey;
+      void motion.play(root, p.Effect || 'fade', { duration: 750, origin:p.Origin,phase:p.Phase });
+    }, destroy() { motion.cancel(root); } };
+  }
+  function sync(kind: Kind, hostId: string, p: NativeMotionOptions, ownerId = hostId): string {
+    try {
+      if (!ownerId) throw Error('A stable native motion owner is required.');
+      // These two foundation Blocks own their empty visual slot. Disabling
+      // motion must leave a static icon/progress indicator, not erase it.
+      if(p.EnableMotion!==true&&(kind==='icon'||kind==='loading'))p={...p,EnableMotion:true,Preference:'Off'};
+      if (p.EnableMotion !== true) { destroy(ownerId); return ''; }
+      const settings = nativeMotionSettings(p); // Reject invalid changes before touching the old adapter.
+      const root = document.getElementById(hostId); if (!root) { destroy(ownerId); return 'Native motion host is not rendered yet.'; }
+      const parent = parentOf(root), previous = owners.get(ownerId), occupant = hosts.get(root);
+      if (occupant && occupant !== ownerId) throw Error('Native motion host already has an owner.');
+      if (previous && (previous.root !== root || previous.kind !== kind || previous.parent !== parent)) destroy(ownerId);
+      let owner = owners.get(ownerId);
+      const signature = JSON.stringify(settings);
+      if (!owner) {
+        const controller = parent ? undefined : createMotionController(root, 'system');
+        const base = parent?.scope?.motion || parent?.controller || controller!;
+        // A private controller owns the root attribute; its component scope is destroyed first.
+        const scope = createComponentMotionScope(root, base, settings);
+        const priorKind = root.getAttribute('data-blu-native-motion');
+        root.setAttribute('data-blu-native-motion', kind);
+        try {
+          owner = { root, kind, parent, controller, scope, adapter: makeAdapter(kind, root, scope.motion), signature, priorKind, options: { ...p } };
+          owners.set(ownerId, owner); hosts.set(root, ownerId);
+        } catch (error) { scope.destroy(); controller?.destroy(); if (priorKind === null) root.removeAttribute('data-blu-native-motion'); else root.setAttribute('data-blu-native-motion', priorKind); throw error; }
+      } else if (owner.signature !== signature) { owner.scope!.update(settings); owner.signature = signature; }
+      const preference = settings.mode === 'inherit' ? 'system' : settings.mode || 'system';
+      if (owner.controller && owner.controller.preference !== preference) owner.controller.setPreference(preference);
+      owner.options = { ...p };
+      owner.adapter.update({ ...p, ReplayKey: p.ReplayKey ?? '' });
+      // O11 can ready inner Blocks before their enclosing provider.
+      if (kind === 'provider') for (const [childId, child] of Array.from(owners)) {
+        if (child !== owner && root.contains(child.root) && child.parent !== parentOf(child.root)) sync(child.kind, child.root.id, child.options, childId);
+      }
+      return '';
+    } catch (error) { return error instanceof Error ? error.message : String(error); }
+  }
+  return { version: '1.2.0-local-full', sync, destroy,
+    register(kind: string, build: (root: HTMLElement, motion: MotionController) => Adapter) { if(extensions.has(kind)) return; extensions.set(kind,build); },
+    play(id: string, targetId: string, effect: MotionEffect = 'fade', phase: 'enter'|'exit' = 'enter') { nativeMotionSettings({Effect:effect,Phase:phase});const owner=actionOwner(id),target=document.getElementById(targetId); if(!owner?.scope || !target || !owner.root.contains(target))return Promise.resolve('cancelled'); return owner.scope.motion.play(target,effect,{phase}); },
+    cancel(id: string, targetId: string) { const owner=actionOwner(id),target=document.getElementById(targetId); if(target&&owner?.root.contains(target)) owner.scope?.motion.cancel(target); },
+    setPreference(id:string,preference:NativeMotionOptions['Preference']) {const owner=actionOwner(id);return owner?sync(owner.kind,owner.root.id,{...owner.options,Preference:preference},hosts.get(owner.root)):'Native motion owner is unavailable.';},
+    capture: (id: string) => owners.get(id)?.adapter.capture?.(),
+    /** Read-only counts for lifecycle checks; does not expose application data. */
+    inspect: () => ({ owners: owners.size, kinds: Array.from(owners.values(), o => o.kind) }),
+  };
+}
+
+declare global { interface Window { BluUIMotion12?: ReturnType<typeof createNativeMotionRuntime>; BluUIMotion12Plugins?: Array<(runtime:ReturnType<typeof createNativeMotionRuntime>)=>void> } }
+if (typeof window !== 'undefined' && !window.BluUIMotion12) window.BluUIMotion12 = createNativeMotionRuntime();
+
+if(typeof window!=="undefined"&&window.BluUIMotion12)for(const install of window.BluUIMotion12Plugins?.splice(0)||[])install(window.BluUIMotion12);

package/src/web-motion/chip-ripple.ts

@@ -0,0 +1,31 @@
+import type {MotionController} from '../motion/controller.js';
+import {createRipple} from '../motion/optional.js';
+
+/** Decorate the selected chip after its real click, even if that click replaces
+ * its button. No synthesized activation or application-state change. */
+export function enhanceChipRipple(root:HTMLElement,motion:MotionController) {
+  let dead=false,revision=0,frame=0,current:ReturnType<typeof createRipple>|undefined;
+  const click=(event:MouseEvent)=>{
+    const source=event.target instanceof Element?event.target.closest<HTMLButtonElement>('.blu-chip__select'):null;
+    if(!source||!root.contains(source)||source.disabled)return;
+    const labels=[...root.querySelectorAll<HTMLButtonElement>('.blu-chip__select')];
+    const label=source.textContent,occurrence=labels.filter(b=>b.textContent===label).indexOf(source);
+    const selected=source.getAttribute('aria-pressed');
+    const point=event.detail?{clientX:event.clientX,clientY:event.clientY}:undefined,own=++revision;
+    // Microtasks can run between capture and the target's click handler.
+    // A frame waits until the component has completed its normal selection.
+    cancelAnimationFrame(frame);frame=requestAnimationFrame(()=>{
+      frame=0;
+      if(dead||own!==revision)return;
+      current?.destroy();current=undefined;
+      const target=source.isConnected?source:[...root.querySelectorAll<HTMLButtonElement>('.blu-chip__select')].filter(b=>b.textContent===label)[occurrence];
+      if(!target||target.disabled||motion.mode!=='full')return;
+      // O11 prevents the browser's default click while still updating selection.
+      // A cancelled activation with no real selection change stays undecorated.
+      if(event.defaultPrevented&&target.getAttribute('aria-pressed')===selected)return;
+      current=createRipple(target,motion,{duration:1000,easing:'ease-out',listen:false});current.play(point);
+    });
+  };
+  root.addEventListener('click',click,true);
+  return {destroy(){if(dead)return;dead=true;++revision;cancelAnimationFrame(frame);root.removeEventListener('click',click,true);current?.destroy();}};
+}

package/src/web-motion/choice-ripple.ts

@@ -0,0 +1,30 @@
+import type {MotionController,MotionOptions} from '../motion/controller.js';
+import {createRipple} from '../motion/optional.js';
+
+/** One decorative pulse per native activation. Label clicks, Space and radio
+ * arrow changes keep the original input, focus, value and change events. */
+export function enhanceChoiceRipple(root:HTMLElement,motion:MotionController,timing:MotionOptions={}) {
+  let dead=false,frame=0,current:ReturnType<typeof createRipple>|undefined;
+  const activate=(event:Event)=>{
+    const input=event.target;
+    if(!(input instanceof HTMLInputElement)||!input.matches('.blu-choice__input')||input.disabled||input.getAttribute('aria-readonly')==='true')return;
+    const name=input.name,value=input.value,type=input.type;
+    const matches=()=>[...root.querySelectorAll<HTMLInputElement>('.blu-choice__input')].filter(el=>el.name===name&&el.value===value&&el.type===type);
+    const occurrence=matches().indexOf(input),checked=input.checked;
+    cancelAnimationFrame(frame);frame=requestAnimationFrame(()=>{
+      frame=0;if(dead||event.defaultPrevented||motion.mode!=='full')return;
+      // Native parameter synchronization can replace a RadioGroup's inputs.
+      // Resolve only the same choice with its already-committed checked state.
+      const target=root.contains(input)?input:matches()[occurrence];
+      if(!target||target.disabled||target.getAttribute('aria-readonly')==='true'||target.checked!==checked)return;
+      const mark=target.nextElementSibling as HTMLElement|null;
+      if(!mark?.classList.contains('blu-choice__mark'))return;
+      current?.destroy();current=createRipple(mark,motion,{duration:1000,easing:'ease-out',...timing,listen:false});
+      current.element.classList.add('blu-motion-choice-ripple');current.play();
+    });
+  };
+  // Capture identity before application handlers can replace the input. The
+  // decorative work still waits until the event and native state commit finish.
+  root.addEventListener('click',activate,true);root.addEventListener('change',activate,true);
+  return {destroy(){if(dead)return;dead=true;cancelAnimationFrame(frame);root.removeEventListener('click',activate,true);root.removeEventListener('change',activate,true);current?.destroy();}};
+}

package/src/web-motion/content.ts

@@ -0,0 +1,74 @@
+import type {MotionController} from '../motion/controller.js';
+import {observeSurface} from './surfaces.js';
+import {preserveStyles} from '../motion/structure.js';
+export type ContentMotionKind = 'profile-card'|'video-lightbox'|'video-player'|'collection-layout'|'cascader'|'transfer'|'chip'|'tree-select'|'timeline'|'skeleton'|'media-image'|'tour'|'notification-center';
+/** DOM-only enhancement: the original component still owns data, focus and media playback. */
+export function enhanceContentMotion(root:HTMLElement,motion:MotionController,kind:ContentMotionKind,options:{timelineKeys?:()=>string[]}={}) {
+  let dead=false,frame=0,serial=0;
+  const active=new Map<HTMLElement,number>(),identities=new WeakMap<Element,string>();
+  const identity=(el:Element)=>{let id=identities.get(el);if(!id){id='node-'+ ++serial;identities.set(el,id);}return id;};
+  const run=(el:HTMLElement,frames:Keyframe[],duration=650,fade=false)=>{const token=++serial;active.set(el,token);void motion.animate(el,frames,{duration,easing:'ease-in-out'},fade?'fade':'instant').finally(()=>{if(active.get(el)===token)active.delete(el);});};
+  type Item={el:HTMLElement;rect:DOMRect;signature:string};
+  function read(){
+    const origin=root.getBoundingClientRect();
+    const entries: [string,Item][]=[];
+    const add=(selector:string,key:(el:HTMLElement,i:number)=>string,signature:(el:HTMLElement)=>string=()=> '')=>{
+      [...root.querySelectorAll<HTMLElement>(selector)].slice(0,40).forEach((el,i)=>{const r=el.getBoundingClientRect(),shift=active.has(el)?getComputedStyle(el).translate.split(/\s+/).map(Number.parseFloat):[],rect=new DOMRect(r.left-origin.left-(shift[0]||0),r.top-origin.top-(shift[1]||0),r.width,r.height);if(rect.width&&rect.height&&!el.closest('[hidden]'))entries.push([key(el,i),{el,rect,signature:signature(el)}]);});
+    };
+    if(kind==='collection-layout')add('.blu-collection-layout__item',identity);
+    if(kind==='timeline')add('.blu-timeline__item',(el,i)=>options.timelineKeys?.()[i]||el.querySelector('h3')?.textContent||identity(el));
+    if(kind==='transfer')add('.blu-transfer__row',el=>el.dataset.key||el.querySelector('.blu-transfer__label')?.textContent||identity(el));
+    if(kind==='chip')add('.blu-chip',el=>el.querySelector('.blu-chip__select,.blu-chip__label')?.textContent||identity(el),el=>String(el.classList.contains('blu-chip--selected')));
+    if(kind==='tree-select')add('.blu-tree-select__item[data-key] > .blu-tree-select__row',el=>el.parentElement!.dataset.key!);
+    if(kind==='cascader')add('.blu-cascader__column',(_,i)=>'column-'+i,el=>el.textContent||'');
+    if(kind==='tour')add('.blu-tour__panel',()=> 'tour-step',el=>el.textContent||'');
+    if(kind==='notification-center'){add('.blu-notification-center__list',()=> 'inbox',el=>el.textContent||'');add('.blu-notification-center__item',el=>el.querySelector('[data-focus]')?.getAttribute('data-focus')||identity(el),el=>el.className);}
+    if(kind==='skeleton')add('[aria-busy]',()=> 'loading-content',el=>el.getAttribute('aria-busy')||'');
+    const unique=new Map<string,Item>(),duplicates=new Set<string>();
+    for(const [key,item] of entries){if(unique.has(key))duplicates.add(key);unique.set(key,item);}
+    for(const key of duplicates)unique.delete(key); // Ambiguous labels never identify moving records.
+    return unique;
+  }
+  let before=read();
+  const capture=()=>{if(!frame)before=read();};
+  function reconcile(){frame=0;if(dead)return;const after=read();
+    for(const [key,item] of after){const old=before.get(key);if(!old){run(item.el,[{opacity:0},{opacity:1}],450,true);continue;}
+      const x=old.rect.left-item.rect.left,y=old.rect.top-item.rect.top;
+      if(kind!=='tour'&&(Math.abs(x)>1||Math.abs(y)>1))run(item.el,[{translate:`${x}px ${y}px`},{translate:'0px 0px'}]);
+      else if(old.signature!==item.signature)run(item.el,[{opacity:.55},{opacity:1}],450,true);
+    }
+    for(const el of active.keys())if(!root.contains(el)){motion.cancel(el);active.delete(el);}
+    before=after;
+  }
+  const observer=new MutationObserver(()=>{if(!frame)frame=requestAnimationFrame(reconcile);});
+  observer.observe(root,{childList:true,subtree:true,attributes:true,attributeFilter:['hidden','class','aria-selected','aria-checked','style']});
+  for(const event of ['click','change','input','keydown','pointerdown'])root.addEventListener(event,capture,true);
+  const previousKind=root.getAttribute('data-blu-content-motion');root.setAttribute('data-blu-content-motion',kind);
+  const surface=kind==='cascader'||kind==='tree-select'?observeSurface(root,motion,kind):undefined;
+  // Media/profile dialogs retain the real content on close. It is already paused
+  // by the component, inert and inaccessible during the short cosmetic fade.
+  const layers=new Map<HTMLElement,{open:boolean;revision:number;restore:()=>void}>();
+  function overlay(){for(const layer of root.querySelectorAll<HTMLElement>('.blu-overlay,.blu-tour')){
+    // Nested components own their own dialogs. Otherwise a collection and its
+    // profile card both snapshot temporary exit styles and restore display:flex
+    // after the hidden dialog finishes closing.
+    if(layer.closest('[data-blu-content-motion]')!==root)continue;
+    let state=layers.get(layer);if(!state){state={open:false,revision:0,restore:()=>{}};layers.set(layer,state);}
+    const open=!layer.hidden;if(open===state.open)continue;state.open=open;const revision=++state.revision;state.restore();motion.cancel(layer);
+    if(open){void motion.play(layer,'fade',{duration:450});continue;}
+    if(motion.mode==='off')continue;
+    const restore=preserveStyles(layer,['display','pointer-events']),inert=layer.inert,aria=layer.getAttribute('aria-hidden');
+    let timer:ReturnType<typeof setTimeout>|undefined;
+    state.restore=()=>{clearTimeout(timer);restore();layer.inert=inert;if(aria===null)layer.removeAttribute('aria-hidden');else layer.setAttribute('aria-hidden',aria);};
+    layer.inert=true;layer.setAttribute('aria-hidden','true');layer.style.setProperty('display','flex','important');layer.style.pointerEvents='none';
+    const finish=()=>{if(!dead&&state!.revision===revision){state!.restore();state!.restore=()=>{};}};
+    timer=setTimeout(finish,(motion.resolveOptions?.({duration:450}).duration??450)+100);
+    void motion.animate(layer,[{opacity:1},{opacity:0}],{duration:450,easing:'ease-in-out'},'fade').finally(finish);
+  }}
+  const overlayObserver=new MutationObserver(overlay);
+  if(['profile-card','video-lightbox','collection-layout','media-image','tour'].includes(kind)){overlayObserver.observe(root,{subtree:true,childList:true,attributes:true,attributeFilter:['hidden']});overlay();}
+  // Playback is never delayed or restarted; only the pause/notice presentation fades.
+  const mediaFeedback=(event:Event)=>{const video=event.target as HTMLVideoElement;if(video.tagName!=='VIDEO')return;queueMicrotask(()=>{if(dead||!root.contains(video))return;const player=video.closest('.blu-video-player');const glass=player?.querySelector<HTMLElement>('.blu-video-player__pause-glass');const feedback=video.paused&&glass&&!glass.hidden&&getComputedStyle(glass).display!=='none'?glass:player?.querySelector<HTMLElement>('.blu-video-player__primary');if(feedback)run(feedback,[{opacity:.4},{opacity:1}],450,true);});};
+  for(const event of ['play','pause','waiting','loadeddata'])root.addEventListener(event,mediaFeedback,true);
+  return {capture,destroy(){if(dead)return;dead=true;observer.disconnect();overlayObserver.disconnect();cancelAnimationFrame(frame);surface?.destroy();for(const [el,state] of layers){state.revision++;state.restore();motion.cancel(el);}for(const el of active.keys())motion.cancel(el);active.clear();for(const event of ['click','change','input','keydown','pointerdown'])root.removeEventListener(event,capture,true);if(previousKind===null)root.removeAttribute('data-blu-content-motion');else root.setAttribute('data-blu-content-motion',previousKind);for(const event of ['play','pause','waiting','loadeddata'])root.removeEventListener(event,mediaFeedback,true);}};
+}

package/src/web-motion/data-rows.ts

@@ -0,0 +1,106 @@
+import type { MotionController } from '../motion/controller.js';
+
+export interface MotionRow { key: string; element: HTMLElement; cells: HTMLElement[]; cellKeys: string[]; }
+interface Snapshot { row: MotionRow; top: number; left: number; width: number; height: number; text: string[]; widths: number[]; }
+/** Presentation only. Data, selection, sorting, paging and keyboard handling stay with the component. */
+export function enhanceDataRows(root: HTMLElement, motion: MotionController, read: () => MotionRow[]) {
+  let disposed = false, frame = 0, settle = 0, generation = 0, scrollUntil = 0, unsupportedRows = false;
+  const owned = new Set<HTMLElement>(), exits = new Map<string, { element: HTMLElement; timer: ReturnType<typeof setTimeout> }>();
+  const previousPosition = root.style.position;
+  if (getComputedStyle(root).position === 'static') root.style.position = 'relative';
+  const layer = document.createElement('div'); layer.className = 'blu-data-motion-exits'; layer.inert = true; layer.setAttribute('aria-hidden', 'true');
+  root.append(layer);
+  function snapshot() {
+    const rows = read();
+    const origin = root.getBoundingClientRect();
+    // Bound work to rendered rows. Never enumerate an entire virtual data set.
+    unsupportedRows = rows.length > 80 || new Set(rows.map(row => row.key)).size !== rows.length;
+    if (unsupportedRows) return new Map<string, Snapshot>();
+    return new Map(rows.map(row => {
+      const r = row.element.getBoundingClientRect();
+      // Read layout coordinates, excluding our in-flight visual translation.
+      const translate = owned.has(row.element) ? getComputedStyle(row.element).translate.split(/\s+/).map(Number.parseFloat) : [];
+      return [row.key, { row, top: r.top-origin.top-(translate[1]||0), left: r.left-origin.left-(translate[0]||0), width: r.width, height: r.height,
+        text: row.cells.map(cell => cell.textContent || ''), widths: row.cells.map(cell => cell.getBoundingClientRect().width) }];
+    }));
+  }
+  let before = snapshot();
+  function animate(el: HTMLElement, frames: Keyframe[], duration: number, fade = false) {
+    owned.add(el);
+    void motion.animate(el, frames, { duration, easing: 'ease-in-out' }, fade ? 'fade' : 'instant').then(() => { if (!el.getAnimations().length) owned.delete(el); });
+  }
+  function clearExits() {
+    for (const { element, timer } of exits.values()) { clearTimeout(timer); motion.cancel(element); owned.delete(element); element.remove(); }
+    exits.clear();
+  }
+  function capture() {
+    if (disposed) return;
+    if (frame) { cancelAnimationFrame(frame); frame = 0; reconcile(); }
+    before = snapshot();
+  }
+  function reconcile() {
+    if (disposed) return;
+    frame = 0;
+    const current = snapshot();
+    // Grid engines make additional style/scrollbar updates after sorting. Those
+    // must not cancel an entrance or reorder that is already playing.
+    const unchanged = current.size===before.size && [...current].every(([key,item])=>{
+      const old=before.get(key);return old && old.row.element===item.row.element && Math.abs(old.top-item.top)<1 && Math.abs(old.left-item.left)<1 && old.width===item.width && old.height===item.height && old.text.join('\u0000')===item.text.join('\u0000');
+    });
+    if(unchanged)return;
+    const revision = ++generation;
+    clearTimeout(settle); clearExits();
+    for (const el of owned) { motion.cancel(el); } owned.clear();
+    if (unsupportedRows || performance.now() < scrollUntil) { before = current; return; }
+    const bounds = root.getBoundingClientRect();
+    // Large page changes use a quiet entrance instead of dozens of crossing rows.
+    const modest = current.size <= 30 && before.size <= 30;
+    for (const [key, entry] of current) {
+      const old = before.get(key), el = entry.row.element;
+      if (!old) animate(el, [{ opacity: 0 }, { opacity: 1 }], 450, true);
+      else {
+        const dy = old.top - entry.top;
+        if (modest && Math.abs(dy) > 1 && Math.abs(dy) < bounds.height) {
+          // Individual translate composes with the grid engine's own transform.
+          animate(el, [{ translate: `0 ${dy}px` }, { translate: '0 0' }], 650);
+        }
+        entry.row.cells.forEach((cell, index) => {
+          const previousIndex = old.row.cellKeys.indexOf(entry.row.cellKeys[index]);
+          if (previousIndex >= 0 && old.text[previousIndex] !== entry.text[index]) {
+            const resting = getComputedStyle(cell).backgroundColor;
+            animate(cell, [{ backgroundColor: resting }, { backgroundColor: 'rgba(105, 88, 240, .18)', offset: .35 }, { backgroundColor: resting }], 1400);
+          }
+        });
+      }
+    }
+    if (modest && motion.mode !== 'off') for (const [key, old] of before) {
+      if (current.has(key) || !old.width || old.top + old.height < 0 || old.top > bounds.height) continue;
+      // Text-only decoration: no copied IDs, controls, handlers or live regions.
+      const ghost = document.createElement('div'); ghost.className = 'blu-data-motion-exit';
+      ghost.style.cssText = `left:${old.left}px;top:${old.top}px;width:${old.width}px;height:${old.height}px;grid-template-columns:${old.widths.map(w => w+'px').join(' ')};`;
+      for (const text of old.text) { const cell = document.createElement('span'); cell.textContent = text; ghost.append(cell); }
+      layer.append(ghost);
+      const remove = () => { if (exits.get(key)?.element !== ghost) return; clearTimeout(exits.get(key)!.timer); motion.cancel(ghost); owned.delete(ghost); ghost.remove(); exits.delete(key); };
+      exits.set(key, { element: ghost, timer: setTimeout(remove, (motion.resolveOptions?.({duration:450}).duration ?? 450) + 250) }); owned.add(ghost);
+      void motion.play(ghost, 'fade', { phase: 'exit', duration: 450, easing: 'ease-in-out' }).then(remove);
+    }
+    before = current;
+    settle = window.setTimeout(() => { if (!disposed && generation === revision) before = snapshot(); }, (motion.resolveOptions?.({duration:650}).duration ?? 650) + 50);
+  }
+  function changed(records: MutationRecord[]) {
+    if (records.every(r => layer.contains(r.target) || r.target === layer)) return;
+    if (!frame) frame = requestAnimationFrame(reconcile);
+  }
+  const observer = new MutationObserver(changed);
+  observer.observe(root, { subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ['row-index', 'row-id', 'style'] });
+  // Capture the current visual positions before the existing click handler rerenders.
+  root.addEventListener('click', capture, true);
+  const scrollPositions = new WeakMap<Element, string>();
+  for(const el of [root,...root.querySelectorAll('*')])scrollPositions.set(el,`${el.scrollLeft},${el.scrollTop}`);
+  const scrolling = (event:Event) => { const el=event.target;if(!(el instanceof Element))return;const position=`${el.scrollLeft},${el.scrollTop}`,previous=scrollPositions.get(el)||'0,0';scrollPositions.set(el,position);if(previous===position)return;scrollUntil = performance.now() + 150; if (frame) cancelAnimationFrame(frame); frame = 0; clearExits(); for (const el of owned) motion.cancel(el); owned.clear(); before = snapshot(); };
+  root.addEventListener('scroll', scrolling, true);
+  return {
+    capture,
+    destroy() { if (disposed) return; disposed = true; observer.disconnect(); cancelAnimationFrame(frame); clearTimeout(settle); clearExits(); for (const el of owned) motion.cancel(el); owned.clear(); root.removeEventListener('click', capture, true); root.removeEventListener('scroll', scrolling, true); layer.remove(); root.style.position = previousPosition; },
+  };
+}

package/src/web-motion/fields.ts

@@ -0,0 +1,52 @@
+import type { MotionController } from '../motion/controller.js';
+import { createPressFeedback } from '../motion/feedback.js';
+
+/** Adds feedback to existing controls without replacing inputs or intercepting native events. */
+export function enhanceField(root: HTMLElement, motion: MotionController) {
+  const previous = root.getAttribute('data-blu-component-motion'); root.setAttribute('data-blu-component-motion', 'field');
+  let destroyed = false, revision = 0, errorText = '', signature = '', height = root.getBoundingClientRect().height;
+  const buttons = new Map<HTMLButtonElement, ReturnType<typeof createPressFeedback>>();
+  const originalOverflow = root.style.overflow;
+  let nudgeTarget: HTMLElement | null = null;
+  function sync(initial = false) {
+    if (destroyed) return;
+    for (const [button, press] of buttons) if (!root.contains(button)) { press.destroy(); buttons.delete(button); }
+    for (const button of Array.from(root.querySelectorAll<HTMLButtonElement>('.blu-text__action'))) if (!buttons.has(button)) buttons.set(button, createPressFeedback(button, motion));
+    const error = root.querySelector<HTMLElement>('.blu-field__error'), next = error && !error.hidden ? error.textContent || '' : '';
+    const nextSignature = [root.textContent, next, root.querySelector('textarea')?.style.height].join('|');
+    if (!initial && nextSignature === signature) return;
+    signature = nextSignature;
+    const from = root.getBoundingClientRect().height;
+    motion.cancel(root); root.style.overflow = originalOverflow;
+    const to = root.getBoundingClientRect().height, own = ++revision;
+    if (!initial && height > 0 && to > 0 && Math.abs(height - to) > 1) {
+      root.style.overflow = 'visible';
+      void motion.animate(root, [{ height: from === to ? height + 'px' : from + 'px' }, { height: to + 'px' }], { duration: 280, easing: 'ease-in-out' }).finally(() => { if (!destroyed && own === revision) root.style.overflow = originalOverflow; });
+    }
+    height = to;
+    if (!initial && next && !errorText && error) {
+      void motion.play(error, 'fade', { duration: 350 });
+      nudgeTarget = root.querySelector<HTMLElement>('.blu-text, .blu-textarea, .blu-select__trigger, .blu-radio-group, .blu-choice');
+      if (nudgeTarget) void motion.animate(nudgeTarget, [
+        { transform: 'translateX(0)' }, { transform: 'translateX(-3px)', offset: .22 },
+        { transform: 'translateX(2px)', offset: .5 }, { transform: 'translateX(-1px)', offset: .75 },
+        { transform: 'translateX(0)' },
+      ], { duration: 550, easing: 'ease-in-out' });
+    }
+    if (!next && nudgeTarget) { motion.cancel(nudgeTarget); nudgeTarget = null; }
+    if (!next && error) motion.cancel(error);
+    errorText = next;
+  }
+  sync(true);
+  const observer = new MutationObserver(records => {
+    if (records.some(record => record.type === 'childList' || record.attributeName !== 'style' || (record.target as Element).matches('textarea'))) sync();
+  });
+  observer.observe(root, { subtree: true, childList: true, attributes: true, attributeFilter: ['hidden', 'aria-invalid', 'data-invalid', 'disabled', 'style'] });
+  return { sync: () => sync(), destroy() {
+    if (destroyed) return; destroyed = true; ++revision; observer.disconnect();
+    motion.cancel(root); root.style.overflow = originalOverflow; if (nudgeTarget) motion.cancel(nudgeTarget);
+    const error = root.querySelector<HTMLElement>('.blu-field__error'); if (error) motion.cancel(error);
+    for (const press of buttons.values()) press.destroy(); buttons.clear();
+    if (previous === null) root.removeAttribute('data-blu-component-motion'); else root.setAttribute('data-blu-component-motion', previous);
+  } };
+}

package/src/web-motion/navigation.ts

@@ -0,0 +1,62 @@
+import type { MotionController } from '../motion/controller.js';
+import { preserveStyles } from '../motion/structure.js';
+
+/** The existing Sidebar/Pagination still owns navigation, focus and events.
+ * This marker only follows aria-current; it never intercepts links or history. */
+export function enhanceNavigation(root: HTMLElement, motion: MotionController, kind: 'sidebar' | 'pagination' | 'tabs') {
+  const win = root.ownerDocument.defaultView!, restore = preserveStyles(root, ['position']);
+  const originalKind = root.getAttribute('data-blu-navigation-motion'); root.setAttribute('data-blu-navigation-motion', kind);
+  const marker = root.ownerDocument.createElement('span');
+  marker.className = 'blu-motion-navigation-marker'; marker.dataset.kind = kind;
+  marker.setAttribute('aria-hidden', 'true'); marker.hidden = true;
+  root.style.position = 'relative'; root.append(marker);
+  let current: HTMLElement | null = null, key = '', geometry = '', dead = false, moving = false, generation = 0;
+  let range: HTMLElement | null = null, rangeText = '';
+  const stop = () => { ++generation; moving = false; motion.cancel(marker); };
+  function place(animate = true) {
+    if (dead) return;
+    // Sidebar renders replace its children, so keep our decoration outside that render.
+    if (!root.contains(marker)) root.append(marker);
+    const next = root.querySelector<HTMLElement>(kind === 'tabs' ? '[role=tab][aria-selected=true]' : '[aria-current="page"]')
+      || (kind === 'pagination' ? root.querySelector<HTMLElement>('.blu-pagination__current') : null);
+    if (current !== next) { if (current) resize.unobserve(current); current = next; if (current) resize.observe(current); }
+    if (!next || !next.getClientRects().length) { if (!marker.hidden) marker.hidden = true; key = ''; geometry = ''; stop(); return; }
+    const nextKey = next.dataset.navigationKey || next.getAttribute('aria-label') || next.textContent || '';
+    const from = marker.hidden ? null : marker.getBoundingClientRect();
+    const parent = root.getBoundingClientRect(), target = next.getBoundingClientRect();
+    const x = target.left - parent.left + root.scrollLeft - root.clientLeft;
+    const y = target.top - parent.top + root.scrollTop - root.clientTop;
+    const nextGeometry = [x, y, target.width, target.height].join(',');
+    if (nextGeometry === geometry && nextKey === key && !marker.hidden) return;
+    // A page-size chooser can finish its layout after the selected page changes.
+    // Continue from the visible position instead of cancelling that transition.
+    const continueMove = moving, changed = key !== nextKey;
+    stop(); if (marker.hidden) marker.hidden = false;
+    Object.assign(marker.style, {
+      left: (x + (kind === 'tabs' ? 6 : 0)) + 'px',
+      top: (y + (kind === 'sidebar' ? 8 : kind === 'tabs' ? target.height - 3 : 0)) + 'px',
+      width: (kind === 'sidebar' ? 3 : kind === 'tabs' ? Math.max(1, target.width - 12) : target.width) + 'px',
+      height: (kind === 'sidebar' ? Math.max(1, target.height - 16) : kind === 'tabs' ? 3 : target.height) + 'px',
+    });
+    if ((animate && changed || continueMove) && from) {
+      const to = marker.getBoundingClientRect();
+      const own = ++generation; moving = true;
+      void motion.animate(marker, [{ transform: `translate(${from.left-to.left}px,${from.top-to.top}px) scale(${from.width/to.width},${from.height/to.height})` }, { transform: 'none' }], { duration: kind === 'pagination' ? 750 : 450, easing: 'ease-in-out' }).finally(() => { if (own === generation) moving = false; });
+    }
+    if (kind === 'pagination') {
+      const nextRange = root.querySelector<HTMLElement>('.blu-pagination__range');
+      if (range !== nextRange && range) motion.cancel(range);
+      const text = nextRange?.textContent || '';
+      if (animate && rangeText && text !== rangeText && nextRange) void motion.animate(nextRange, [{ opacity: .35 }, { opacity: 1 }], { duration: 750, easing: 'ease-in-out' }, 'fade');
+      range = nextRange; rangeText = text;
+    }
+    key = nextKey; geometry = nextGeometry;
+  }
+  const resize = new ResizeObserver(() => place(false));
+  const observer = new MutationObserver(() => place());
+  const onScroll = () => { stop(); place(false); };
+  place(false); resize.observe(root);
+  observer.observe(root, { subtree: true, childList: true, attributes: true, attributeFilter: ['aria-current', 'aria-selected', 'hidden'] });
+  root.addEventListener('scroll', onScroll, true); win.addEventListener('resize', onScroll);
+  return { destroy() { if (dead) return; dead = true; observer.disconnect(); resize.disconnect(); stop(); if(range)motion.cancel(range); marker.remove(); restore(); if (originalKind === null) root.removeAttribute('data-blu-navigation-motion'); else root.setAttribute('data-blu-navigation-motion', originalKind); root.removeEventListener('scroll', onScroll, true); win.removeEventListener('resize', onScroll); } };
+}

package/src/web-motion/notifications.ts

@@ -0,0 +1,67 @@
+import type { MotionController } from '../motion/controller.js';
+
+/** Observe the existing message stack. Its runtime still owns timers, pause on
+ * hover/focus, announcements and dismissal. Exits are decorative, inert copies. */
+export function enhanceNotifications(root: HTMLElement, motion: MotionController) {
+  const previous = root.getAttribute('data-blu-component-motion'); root.setAttribute('data-blu-component-motion', 'notifications');
+  const cards = new Map<HTMLElement, { rect: DOMRect; opacity: string }>(), ghosts = new Set<HTMLElement>();
+  let dead = false, frame = 0, generation = 0;
+  const win = root.ownerDocument.defaultView!;
+  // Some engines emit focusin/out but do not support onfocusin/out properties.
+  // Forward only in those engines; the existing handlers own the timer state.
+  type FocusCard = HTMLElement & { onfocusin?: (event: FocusEvent) => void; onfocusout?: (event: FocusEvent) => void };
+  const forwardFocus = (event: FocusEvent) => {
+    const card = (event.target as Element).closest<FocusCard>('.blu-notifications > .blu-notification');
+    if (!card || !root.contains(card)) return;
+    if (event.type === 'focusin') card.onfocusin?.call(card, event); else card.onfocusout?.call(card, event);
+  };
+  const bridgeIn = !('onfocusin' in root), bridgeOut = !('onfocusout' in root);
+  if (bridgeIn) root.addEventListener('focusin', forwardFocus);
+  if (bridgeOut) root.addEventListener('focusout', forwardFocus);
+  const measure = () => { for (const [card, state] of cards) if (card.isConnected) { state.rect = card.getBoundingClientRect(); state.opacity = win.getComputedStyle(card).opacity; } };
+  const resize = new ResizeObserver(measure);
+  function exit(card: HTMLElement, state: { rect: DOMRect; opacity: string }) {
+    if (!state.rect.width || motion.mode === 'off' || root.closest('.blu-motion-off,[data-blu-motion=off]')) return;
+    const copy = card.cloneNode(true) as HTMLElement;
+    for (const el of [copy, ...copy.querySelectorAll<HTMLElement>('*')]) {
+      for (const attr of ['id','name','role','aria-live','aria-labelledby','aria-describedby','aria-controls','tabindex','autofocus']) el.removeAttribute(attr);
+    }
+    copy.dataset.bluExitVisual = 'notification'; copy.inert = true; copy.setAttribute('aria-hidden', 'true');
+    const rect = state.rect;
+    Object.assign(copy.style, { position: 'fixed', left: rect.left + 'px', top: rect.top + 'px', width: rect.width + 'px', height: rect.height + 'px', boxSizing: 'border-box', margin: '0', zIndex: '1300', pointerEvents: 'none', animation: 'none', opacity: state.opacity });
+    root.append(copy); ghosts.add(copy);
+    void motion.animate(copy, [{ opacity: state.opacity }, { opacity: 0 }], { phase: 'exit', duration: 450, easing: 'ease-in-out' }, 'fade').then(() => { copy.remove(); ghosts.delete(copy); });
+  }
+  function sync() {
+    if (dead) return;
+    const current = Array.from(root.querySelectorAll<HTMLElement>('.blu-notifications > .blu-notification'));
+    if (current.length === cards.size && current.every(card => cards.has(card))) return;
+    const own = ++generation; win.cancelAnimationFrame(frame);
+    const tasks: Promise<unknown>[] = [];
+    for (const [card, state] of cards) if (!current.includes(card)) { motion.cancel(card); resize.unobserve(card); cards.delete(card); exit(card, state); }
+    for (const card of current) {
+      const before = cards.get(card); motion.cancel(card);
+      const rect = card.getBoundingClientRect();
+      cards.set(card, { rect, opacity: win.getComputedStyle(card).opacity }); resize.observe(card);
+      if (!before) tasks.push(motion.play(card, 'slide-up', { duration: 450, easing: 'ease-out' }));
+      else {
+        const x = before.rect.left - rect.left, y = before.rect.top - rect.top;
+        if (Math.abs(x) > .5 || Math.abs(y) > .5 || Number(before.opacity) < .99) tasks.push(motion.animate(card, [{ transform: `translate(${x}px,${y}px)`, opacity: before.opacity }, { transform: 'none', opacity: 1 }], { duration: 450, easing: 'ease-in-out' }));
+      }
+    }
+    const track = () => { if (dead || own !== generation) return; measure(); frame = win.requestAnimationFrame(track); };
+    frame = win.requestAnimationFrame(track);
+    void Promise.all(tasks).then(() => { if (!dead && own === generation) { win.cancelAnimationFrame(frame); measure(); } });
+  }
+  const observer = new MutationObserver(sync); observer.observe(root, { childList: true, subtree: true }); sync();
+  win.addEventListener('resize', measure); win.addEventListener('scroll', measure, true);
+  return { destroy() {
+    if (dead) return; dead = true; ++generation; observer.disconnect(); resize.disconnect(); win.cancelAnimationFrame(frame);
+    win.removeEventListener('resize', measure); win.removeEventListener('scroll', measure, true);
+    if (bridgeIn) root.removeEventListener('focusin', forwardFocus);
+    if (bridgeOut) root.removeEventListener('focusout', forwardFocus);
+    for (const card of cards.keys()) motion.cancel(card); cards.clear();
+    for (const ghost of ghosts) { motion.cancel(ghost); ghost.remove(); } ghosts.clear();
+    if (previous === null) root.removeAttribute('data-blu-component-motion'); else root.setAttribute('data-blu-component-motion', previous);
+  } };
+}