@ozsarman/clarityjs 0.6.0

package/src/transitions.js

@@ -0,0 +1,438 @@
+/**
+ * Clarity.js — Transition & Animation System
+ *
+ * Vue 3-compatible transition primitives built on Web Animations API + CSS classes.
+ *
+ * ─── CSS Class Transitions ───────────────────────────────────────────────────
+ *
+ *   <Transition name="fade">
+ *     <when cond={show}><div>Hello</div></when>
+ *   </Transition>
+ *
+ * Applied classes (matching Vue's convention):
+ *   Enter: fade-enter-from → fade-enter-active → (remove -from, keep -active) → fade-enter-to
+ *            → done (remove all)
+ *   Leave: fade-leave-from → fade-leave-active → fade-leave-to → done (remove element)
+ *
+ * ─── JS Hook Transitions ─────────────────────────────────────────────────────
+ *
+ *   <Transition
+ *     onBeforeEnter={el => el.style.opacity = 0}
+ *     onEnter={(el, done) => el.animate([{opacity:0},{opacity:1}], 300).onfinish = done}
+ *     onLeave={(el, done) => el.animate([{opacity:1},{opacity:0}], 300).onfinish = done}
+ *   >
+ *     ...
+ *   </Transition>
+ *
+ * ─── TransitionGroup ─────────────────────────────────────────────────────────
+ *
+ *   Wraps a list and animates items entering/leaving.
+ *   Supports FLIP animations for reordering.
+ *
+ *   <TransitionGroup name="list" tag="ul">
+ *     <list items={todos}>
+ *       <li key={item.id}>{ item.text }</li>
+ *     </list>
+ *   </TransitionGroup>
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+// ─── Transition ───────────────────────────────────────────────────────────────
+
+/**
+ * Wraps a single conditional child with enter/leave transitions.
+ *
+ * @param {object} options
+ * @param {string}   [options.name='v']          — CSS class prefix
+ * @param {boolean}  [options.appear=false]       — animate on initial render
+ * @param {string}   [options.enterFromClass]     — override generated class
+ * @param {string}   [options.enterActiveClass]
+ * @param {string}   [options.enterToClass]
+ * @param {string}   [options.leaveFromClass]
+ * @param {string}   [options.leaveActiveClass]
+ * @param {string}   [options.leaveToClass]
+ * @param {Function} [options.onBeforeEnter]      — (el) => void
+ * @param {Function} [options.onEnter]            — (el, done) => void
+ * @param {Function} [options.onAfterEnter]       — (el) => void
+ * @param {Function} [options.onBeforeLeave]      — (el) => void
+ * @param {Function} [options.onLeave]            — (el, done) => void
+ * @param {Function} [options.onAfterLeave]       — (el) => void
+ * @param {Function | Node} options.children      — Child factory or node
+ * @returns {Element}
+ */
+export function Transition({
+  name            = 'v',
+  appear          = false,
+  enterFromClass,
+  enterActiveClass,
+  enterToClass,
+  leaveFromClass,
+  leaveActiveClass,
+  leaveToClass,
+  onBeforeEnter,
+  onEnter,
+  onAfterEnter,
+  onEnterCancelled,
+  onBeforeLeave,
+  onLeave,
+  onAfterLeave,
+  onLeaveCancelled,
+  children,
+} = {}) {
+  const classes = {
+    enterFrom:   enterFromClass   ?? `${name}-enter-from`,
+    enterActive: enterActiveClass ?? `${name}-enter-active`,
+    enterTo:     enterToClass     ?? `${name}-enter-to`,
+    leaveFrom:   leaveFromClass   ?? `${name}-leave-from`,
+    leaveActive: leaveActiveClass ?? `${name}-leave-active`,
+    leaveTo:     leaveToClass     ?? `${name}-leave-to`,
+  };
+
+  // Wrapper is invisible — we only need it as a mount point
+  const wrapper = document.createElement('div');
+  wrapper.setAttribute('data-clarity-transition', name);
+  wrapper.style.cssText = 'display:contents'; // transparent layout
+
+  // Render child
+  let currentEl = null;
+  const child   = typeof children === 'function' ? children() : children;
+
+  if (child instanceof Node) {
+    currentEl = child;
+    wrapper.appendChild(child);
+    if (appear) {
+      _nextTick(() => _enter(currentEl, classes, { onBeforeEnter, onEnter, onAfterEnter }));
+    }
+  }
+
+  // Expose API so parent can trigger transitions
+  wrapper._transitionEnter = (el) => {
+    currentEl = el;
+    wrapper.innerHTML = '';
+    wrapper.appendChild(el);
+    _enter(el, classes, { onBeforeEnter, onEnter, onAfterEnter });
+  };
+
+  wrapper._transitionLeave = (el, callback) => {
+    _leave(el, classes, {
+      onBeforeLeave,
+      onLeave,
+      onAfterLeave,
+      onLeaveCancelled,
+      callback,
+    });
+  };
+
+  return wrapper;
+}
+
+// ─── TransitionGroup ──────────────────────────────────────────────────────────
+
+/**
+ * Animate a list of children entering, leaving, and moving (FLIP).
+ *
+ * @param {object} options
+ * @param {string}   [options.name='v']   — CSS class prefix
+ * @param {string}   [options.tag='div']  — Wrapper element tag
+ * @param {Function} options.children     — Returns array of keyed nodes
+ * @param {boolean}  [options.moveClass]  — Class applied during FLIP move
+ * @returns {Element}
+ */
+export function TransitionGroup({
+  name      = 'v',
+  tag       = 'div',
+  children,
+  moveClass,
+} = {}) {
+  const classes = {
+    enterFrom:   `${name}-enter-from`,
+    enterActive: `${name}-enter-active`,
+    enterTo:     `${name}-enter-to`,
+    leaveFrom:   `${name}-leave-from`,
+    leaveActive: `${name}-leave-active`,
+    leaveTo:     `${name}-leave-to`,
+    move:        moveClass ?? `${name}-move`,
+  };
+
+  const wrapper = document.createElement(tag);
+  wrapper.setAttribute('data-clarity-transition-group', name);
+
+  // Initial render (no animation)
+  const initial = typeof children === 'function' ? children() : (children ?? []);
+  const _nodeMap = new Map(); // key → node
+
+  const initNodes = Array.isArray(initial) ? initial.flat() : [initial];
+  for (const node of initNodes) {
+    if (node instanceof Node) {
+      const key = node.dataset?.key ?? node.__key ?? wrapper.children.length;
+      _nodeMap.set(key, node);
+      wrapper.appendChild(node);
+    }
+  }
+
+  /**
+   * Update the list — call with new nodes to animate insertions/removals.
+   * @param {Node[]} newNodes
+   */
+  wrapper.update = function(newNodes) {
+    const incoming = new Map();
+    for (const node of newNodes.flat()) {
+      if (!(node instanceof Node)) continue;
+      const key = node.dataset?.key ?? node.__key ?? String(Math.random());
+      incoming.set(key, node);
+    }
+
+    // ── FLIP: record old positions ───────────────────────────────────────────
+    const oldPositions = new Map();
+    for (const [key, node] of _nodeMap) {
+      if (node.isConnected) {
+        oldPositions.set(key, node.getBoundingClientRect());
+      }
+    }
+
+    // ── Remove nodes no longer in list ───────────────────────────────────────
+    for (const [key, node] of _nodeMap) {
+      if (!incoming.has(key)) {
+        _nodeMap.delete(key);
+        _leave(node, classes, {
+          callback: () => node.parentNode?.removeChild(node),
+        });
+      }
+    }
+
+    // ── Insert new nodes ─────────────────────────────────────────────────────
+    let ref = null;
+    for (const [key, node] of incoming) {
+      if (!_nodeMap.has(key)) {
+        _nodeMap.set(key, node);
+        wrapper.insertBefore(node, ref);
+        _enter(node, classes, {});
+      }
+      ref = node.nextSibling;
+    }
+
+    // ── Reorder existing nodes ────────────────────────────────────────────────
+    let insertRef = null;
+    for (const [key, node] of [...incoming].reverse()) {
+      if (_nodeMap.has(key)) {
+        if (node.nextSibling !== insertRef) {
+          wrapper.insertBefore(node, insertRef);
+        }
+        insertRef = node;
+      }
+    }
+
+    // ── FLIP: apply move transitions ─────────────────────────────────────────
+    _nextTick(() => {
+      for (const [key, node] of _nodeMap) {
+        const old = oldPositions.get(key);
+        if (!old || !node.isConnected) continue;
+        const now = node.getBoundingClientRect();
+        const dx  = old.left - now.left;
+        const dy  = old.top  - now.top;
+        if (Math.abs(dx) < 1 && Math.abs(dy) < 1) continue;
+
+        // Apply inverse transform, then animate to zero
+        node.style.transform = `translate(${dx}px, ${dy}px)`;
+        node.style.transition = 'none';
+        _nextTick(() => {
+          node.classList.add(classes.move);
+          node.style.transform   = '';
+          node.style.transition  = '';
+          _onTransitionEnd(node, () => {
+            node.classList.remove(classes.move);
+          });
+        });
+      }
+    });
+  };
+
+  return wrapper;
+}
+
+// ─── Internal animation helpers ───────────────────────────────────────────────
+
+/**
+ * Run the enter transition sequence on an element.
+ */
+function _enter(el, classes, hooks = {}) {
+  if (!el || !el.classList) return;
+
+  const { onBeforeEnter, onEnter, onAfterEnter } = hooks;
+
+  // 1. Add enter-from + enter-active before paint
+  el.classList.add(classes.enterFrom, classes.enterActive);
+  onBeforeEnter?.(el);
+
+  _nextTick(() => {
+    // 2. Remove enter-from, add enter-to (triggers CSS transition)
+    el.classList.remove(classes.enterFrom);
+    el.classList.add(classes.enterTo);
+
+    if (typeof onEnter === 'function') {
+      // JS hook mode — caller calls done() when animation is finished
+      const done = () => _finishEnter(el, classes, onAfterEnter);
+      onEnter(el, done);
+    } else {
+      // CSS mode — wait for transition/animation to finish
+      _onTransitionEnd(el, () => _finishEnter(el, classes, onAfterEnter));
+    }
+  });
+}
+
+function _finishEnter(el, classes, onAfterEnter) {
+  el.classList.remove(classes.enterActive, classes.enterTo);
+  onAfterEnter?.(el);
+}
+
+/**
+ * Run the leave transition sequence on an element.
+ */
+function _leave(el, classes, hooks = {}) {
+  if (!el || !el.classList) {
+    hooks.callback?.();
+    return;
+  }
+
+  const { onBeforeLeave, onLeave, onAfterLeave, onLeaveCancelled, callback } = hooks;
+
+  el.classList.add(classes.leaveFrom, classes.leaveActive);
+  onBeforeLeave?.(el);
+
+  _nextTick(() => {
+    el.classList.remove(classes.leaveFrom);
+    el.classList.add(classes.leaveTo);
+
+    if (typeof onLeave === 'function') {
+      const done = () => _finishLeave(el, classes, onAfterLeave, callback);
+      onLeave(el, done);
+    } else {
+      _onTransitionEnd(el, () => _finishLeave(el, classes, onAfterLeave, callback));
+    }
+  });
+}
+
+function _finishLeave(el, classes, onAfterLeave, callback) {
+  el.classList.remove(classes.leaveActive, classes.leaveTo);
+  onAfterLeave?.(el);
+  callback?.();
+}
+
+/**
+ * Wait for the CSS transition or animation to complete on an element.
+ * Falls back to a 1-frame timeout if no transition is detected.
+ */
+function _onTransitionEnd(el, callback) {
+  // Check if there is actually a transition/animation to wait for
+  const style    = window.getComputedStyle(el);
+  const duration = parseFloat(style.transitionDuration ?? '0') ||
+                   parseFloat(style.animationDuration   ?? '0');
+
+  if (duration > 0) {
+    const handler = () => {
+      el.removeEventListener('transitionend', handler);
+      el.removeEventListener('animationend',  handler);
+      callback();
+    };
+    el.addEventListener('transitionend', handler, { once: true });
+    el.addEventListener('animationend',  handler, { once: true });
+  } else {
+    // No CSS transition — call immediately after paint
+    requestAnimationFrame(callback);
+  }
+}
+
+function _nextTick(fn) {
+  // Two rAFs ensure browser has painted before we apply the "to" class
+  requestAnimationFrame(() => requestAnimationFrame(fn));
+}
+
+// ─── useTransition ────────────────────────────────────────────────────────────
+
+/**
+ * Programmatic transition hook — use when you need to trigger enter/leave
+ * transitions imperatively (e.g. from a store action).
+ *
+ * @param {object} options  — same as Transition props
+ * @returns {{ enter: (el) => void, leave: (el, callback?) => void, classes: object }}
+ */
+export function useTransition(options = {}) {
+  const name = options.name ?? 'v';
+  const classes = {
+    enterFrom:   options.enterFromClass   ?? `${name}-enter-from`,
+    enterActive: options.enterActiveClass ?? `${name}-enter-active`,
+    enterTo:     options.enterToClass     ?? `${name}-enter-to`,
+    leaveFrom:   options.leaveFromClass   ?? `${name}-leave-from`,
+    leaveActive: options.leaveActiveClass ?? `${name}-leave-active`,
+    leaveTo:     options.leaveToClass     ?? `${name}-leave-to`,
+  };
+
+  return {
+    classes,
+    enter: (el)           => _enter(el, classes, options),
+    leave: (el, callback) => _leave(el, classes, { ...options, callback }),
+  };
+}
+
+// ─── Built-in transition presets (CSS-in-JS) ─────────────────────────────────
+
+/**
+ * Inject built-in transition preset styles into the document head.
+ * Called once during app init if you want the presets available globally.
+ *
+ * Available presets: 'fade', 'slide-up', 'slide-down', 'scale', 'slide-right', 'slide-left'
+ *
+ * @param {string[]} [presets]  — which presets to inject (default: all)
+ */
+export function injectTransitionStyles(presets) {
+  if (typeof document === 'undefined') return;
+
+  const CSS = _buildPresetCSS(presets);
+  const existing = document.querySelector('[data-clarity-transitions]');
+  if (existing) return; // already injected
+
+  const style = document.createElement('style');
+  style.setAttribute('data-clarity-transitions', '');
+  style.textContent = CSS;
+  document.head.appendChild(style);
+}
+
+function _buildPresetCSS(names) {
+  const all = {
+    fade: `
+      .v-enter-active, .v-leave-active { transition: opacity 0.25s ease; }
+      .v-enter-from,   .v-leave-to     { opacity: 0; }
+      .fade-enter-active, .fade-leave-active { transition: opacity 0.25s ease; }
+      .fade-enter-from,   .fade-leave-to     { opacity: 0; }
+    `,
+    'slide-up': `
+      .slide-up-enter-active, .slide-up-leave-active { transition: opacity 0.3s ease, transform 0.3s ease; }
+      .slide-up-enter-from    { opacity: 0; transform: translateY(12px); }
+      .slide-up-leave-to      { opacity: 0; transform: translateY(-12px); }
+    `,
+    'slide-down': `
+      .slide-down-enter-active, .slide-down-leave-active { transition: opacity 0.3s ease, transform 0.3s ease; }
+      .slide-down-enter-from    { opacity: 0; transform: translateY(-12px); }
+      .slide-down-leave-to      { opacity: 0; transform: translateY(12px); }
+    `,
+    'slide-right': `
+      .slide-right-enter-active, .slide-right-leave-active { transition: opacity 0.3s ease, transform 0.3s ease; }
+      .slide-right-enter-from    { opacity: 0; transform: translateX(-16px); }
+      .slide-right-leave-to      { opacity: 0; transform: translateX(16px); }
+    `,
+    'slide-left': `
+      .slide-left-enter-active, .slide-left-leave-active { transition: opacity 0.3s ease, transform 0.3s ease; }
+      .slide-left-enter-from    { opacity: 0; transform: translateX(16px); }
+      .slide-left-leave-to      { opacity: 0; transform: translateX(-16px); }
+    `,
+    scale: `
+      .scale-enter-active, .scale-leave-active { transition: opacity 0.2s ease, transform 0.2s ease; }
+      .scale-enter-from    { opacity: 0; transform: scale(0.95); }
+      .scale-leave-to      { opacity: 0; transform: scale(0.95); }
+    `,
+  };
+
+  const keys = names ?? Object.keys(all);
+  return keys.map(k => all[k] ?? '').join('\n');
+}