@adukiorg/anza 0.2.0

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@adukiorg/anza",
+  "version": "0.2.0",
+  "description": "Anza web platform library — reactive state, networking, offline, animations, custom elements. Zero build step. Pure browser ESM.",
+  "author": "fescii",
+  "license": "MIT",
+  "type": "module",
+  "types": "./types/index.d.ts",
+  "homepage": "https://github.com/aduki-org/anza#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aduki-org/anza.git"
+  },
+  "keywords": [
+    "anza",
+    "esm",
+    "web-components",
+    "reactive",
+    "offline",
+    "animations",
+    "no-build",
+    "shadow-dom"
+  ],
+  "bin": {
+    "anza": "./bin/anza.js",
+    "anza-create": "./bin/create.js"
+  },
+  "files": [
+    "src/",
+    "types/",
+    "importmap.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "bin/"
+  ],
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./api": {
+      "types": "./types/core/api/index.d.ts",
+      "default": "./src/core/api/index.js"
+    },
+    "./state": {
+      "types": "./types/core/state/index.d.ts",
+      "default": "./src/core/state/index.js"
+    },
+    "./events": {
+      "types": "./types/core/events/index.d.ts",
+      "default": "./src/core/events/index.js"
+    },
+    "./router": {
+      "types": "./types/core/router/index.d.ts",
+      "default": "./src/core/router/index.js"
+    },
+    "./storage": {
+      "types": "./types/core/storage/index.d.ts",
+      "default": "./src/core/storage/index.js"
+    },
+    "./offline": {
+      "types": "./types/core/offline/index.d.ts",
+      "default": "./src/core/offline/index.js"
+    },
+    "./animations": {
+      "types": "./types/core/animations/index.d.ts",
+      "default": "./src/core/animations/index.js"
+    },
+    "./workers": {
+      "types": "./types/core/workers/index.d.ts",
+      "default": "./src/core/workers/index.js"
+    },
+    "./security": {
+      "types": "./types/core/security/index.d.ts",
+      "default": "./src/core/security/index.js"
+    },
+    "./platform": {
+      "types": "./types/core/platform/index.d.ts",
+      "default": "./src/core/platform/index.js"
+    },
+    "./ui": {
+      "types": "./types/core/ui/index.d.ts",
+      "default": "./src/core/ui/index.js"
+    },
+    "./elements": {
+      "types": "./types/elements/index.d.ts",
+      "default": "./src/elements/index.js"
+    }
+  },
+  "scripts": {
+    "build:tools": "node ../../scripts/build.js",
+    "test":        "npx @web/test-runner",
+    "serve":       "npx @web/dev-server --port 8080 --node-resolve false",
+    "check":       "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  }
+}

package/src/core/animations/index.js

@@ -0,0 +1,55 @@
+/**
+ * src/core/animations/index.js
+ *
+ * Public animations base entry point.
+ * Combines animation template registries, standard WAAPI triggers, stagger orchestrators,
+ * scroll/view-linked timelines, and standard easing curves.
+ *
+ * Source: doc 03 — Native CSS Architecture §6, doc 12 — Performance §4
+ */
+
+import { registry } from './registry.js';
+import { animate, stagger, sequence } from './play.js';
+import { scroll, view } from './scroll.js';
+import { Timing, timing, keyframes } from './waapi.js';
+import { duration, ease, reduced } from './tokens.js';
+
+export const animations = {
+  /**
+   * Registers a named animation template with keyframes and defaults.
+   */
+  register(name, frames, defaultOpts = {}) {
+    registry.register(name, frames, defaultOpts);
+  },
+
+  animate,
+  stagger,
+  sequence,
+  scroll,
+  view,
+
+  // Exposed easing curves and timing utilities
+  Timing,
+  timing,
+  keyframes,
+
+  // Motion-token accessors (single source of truth with CSS)
+  duration,
+  ease,
+  reduced
+};
+
+export {
+  registry,
+  animate,
+  stagger,
+  sequence,
+  scroll,
+  view,
+  Timing,
+  timing,
+  keyframes,
+  duration,
+  ease,
+  reduced
+};

package/src/core/animations/play.js

@@ -0,0 +1,111 @@
+/**
+ * src/core/animations/play.js
+ *
+ * WAAPI Execution Engine.
+ * Wraps browser element.animate(), providing automatic AbortSignal-gated memory-safe
+ * cancel cleanups, template resolution, and multi-element stagger calculations.
+ *
+ * Source: doc 12 — Performance §4, doc 14 — Memory Management §5
+ */
+
+import { registry } from './registry.js';
+
+/**
+ * Animates a single element, resolving templates and binding AbortSignal cleanups.
+ */
+export function animate(el, animationInput, options = {}) {
+  let keyframes;
+  let defaultOpts = {};
+
+  // Resolve template from the registry if name string is provided
+  if (typeof animationInput === 'string') {
+    const config = registry.get(animationInput);
+    if (!config) {
+      throw new Error(`Animation template "${animationInput}" not found in registry`);
+    }
+    keyframes = config.keyframes;
+    defaultOpts = config.options;
+  } else {
+    keyframes = animationInput;
+  }
+
+  const finalOpts = { ...defaultOpts, ...options };
+  const anim = el.animate(keyframes, finalOpts);
+
+  // Secure against memory leaks: cancel active animation when AbortSignal fires
+  if (options.signal) {
+    const handleAbort = () => {
+      try {
+        anim.cancel();
+      } catch {}
+    };
+
+    options.signal.addEventListener('abort', handleAbort);
+    anim.addEventListener('finish', () => {
+      options.signal.removeEventListener('abort', handleAbort);
+    });
+  }
+
+  return anim;
+}
+
+/**
+ * Animates a sequence of elements with staggered delays.
+ */
+export function stagger(elements, animationInput, options = {}) {
+  const step = options.staggerDelay ?? 60; // default 60ms stagger steps
+  const list = Array.from(elements);
+
+  const animations = list.map((el, i) => {
+    const itemOpts = {
+      ...options,
+      delay: (options.delay ?? 0) + i * step
+    };
+    return animate(el, animationInput, itemOpts);
+  });
+
+  return {
+    animations,
+    /**
+     * Instantly aborts all active staggered animations in this group.
+     */
+    cancel() {
+      for (const anim of animations) {
+        try {
+          anim.cancel();
+        } catch {}
+      }
+    },
+    /**
+     * Instantly skips all animations to their end state.
+     */
+    finish() {
+      for (const anim of animations) {
+        try {
+          anim.finish();
+        } catch {}
+      }
+    },
+    /**
+     * Aggregate promise resolving when all staggered animations settle.
+     */
+    finished: Promise.all(animations.map((anim) => anim.finished))
+  };
+}
+
+/**
+ * Runs animation steps one after another, each starting when the previous one
+ * finishes. Each step is `[el, animationInput, options?]`.
+ *
+ * Returns `{ finished }` resolving when the whole sequence completes.
+ */
+export function sequence(steps) {
+  const finished = (async () => {
+    for (const [el, input, options] of steps) {
+      const anim = animate(el, input, options ?? {});
+      await anim.finished;
+    }
+  })();
+
+  return { finished };
+}

package/src/core/animations/registry.js

@@ -0,0 +1,54 @@
+/**
+ * src/core/animations/registry.js
+ *
+ * Animation Registry.
+ * A centralized store to register, lookup, and manage reusable WAAPI keyframe
+ * configurations and timing options.
+ *
+ * Source: doc 03 — Native CSS Architecture §6, doc 12 — Performance §4
+ */
+
+import { keyframes, timing } from './waapi.js';
+
+export class AnimationRegistry {
+  #store = new Map();
+
+  /**
+   * Registers a named animation template with keyframes and default timing options.
+   */
+  register(name, keyframes, defaultOptions = {}) {
+    this.#store.set(name, { keyframes, options: defaultOptions });
+  }
+
+  /**
+   * Retrieves a registered animation configuration.
+   */
+  get(name) {
+    return this.#store.get(name) || null;
+  }
+
+  /**
+   * Evicts an animation template from the registry.
+   */
+  delete(name) {
+    return this.#store.delete(name);
+  }
+
+  /**
+   * Flushes all stored animation templates.
+   */
+  clear() {
+    this.#store.clear();
+  }
+}
+
+export const registry = new AnimationRegistry();
+
+// Register common presets
+registry.register('fade', keyframes('fade'), timing());
+registry.register('slide', keyframes('slide'), timing());
+registry.register('slide-x', keyframes('slide', { axis: 'x' }), timing());
+registry.register('slide-y', keyframes('slide', { axis: 'y' }), timing());
+registry.register('scale', keyframes('scale'), timing());
+registry.register('zoom', keyframes('zoom'), timing());
+registry.register('blur', keyframes('blur'), timing());

package/src/core/animations/scroll.js

@@ -0,0 +1,50 @@
+/**
+ * src/core/animations/scroll.js
+ *
+ * Scroll-Driven Animations Wrapper.
+ * Exposes native browser ScrollTimeline and ViewTimeline constructors for scroll-linked animations,
+ * with standard static fallback descriptors for unsupported engines.
+ *
+ * Source: doc 03 — Native CSS Architecture §6, doc 12 — Performance §4
+ */
+
+/**
+ * Creates a ScrollTimeline instance or returns a fallback descriptor.
+ */
+export function scroll(options = {}) {
+  if (typeof ScrollTimeline !== 'undefined') {
+    try {
+      return new ScrollTimeline(options);
+    } catch (err) {
+      console.warn('ScrollTimeline constructor failed:', err);
+    }
+  }
+
+  // Resilient descriptor fallback for older browser runtimes
+  return {
+    source: options.source ?? (typeof document !== 'undefined' ? document.documentElement : null),
+    axis: options.axis ?? 'block',
+    unsupported: true
+  };
+}
+
+/**
+ * Creates a ViewTimeline instance or returns a fallback descriptor.
+ */
+export function view(options = {}) {
+  if (typeof ViewTimeline !== 'undefined') {
+    try {
+      return new ViewTimeline(options);
+    } catch (err) {
+      console.warn('ViewTimeline constructor failed:', err);
+    }
+  }
+
+  // Resilient descriptor fallback for older browser runtimes
+  return {
+    subject: options.subject ?? null,
+    axis: options.axis ?? 'block',
+    inset: options.inset ?? '0px',
+    unsupported: true
+  };
+}

package/src/core/animations/tokens.js

@@ -0,0 +1,58 @@
+/**
+ * src/core/animations/tokens.js
+ *
+ * Single source of truth bridge: reads the CSS motion tokens
+ * (`--duration-*`, `--ease-*` from src/tokens/primitives/motion.css) at runtime
+ * so the WAAPI engine and the stylesheet share the same values. Falls back to
+ * the token defaults when the document or a token is unavailable (e.g. SSR).
+ */
+
+const FALLBACK = {
+  duration: { instant: 50, fast: 100, normal: 200, slow: 300, slower: 500 },
+  ease: {
+    default: 'cubic-bezier(0.4, 0, 0.2, 1)',
+    in: 'cubic-bezier(0.4, 0, 1, 1)',
+    out: 'cubic-bezier(0, 0, 0.2, 1)',
+    'in-out': 'cubic-bezier(0.4, 0, 0.6, 1)',
+    spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+    linear: 'linear'
+  }
+};
+
+function root() {
+  if (typeof document === 'undefined' || !document.documentElement) return null;
+  return getComputedStyle(document.documentElement);
+}
+
+function parseMs(value) {
+  if (!value) return null;
+  const v = value.trim();
+  if (v.endsWith('ms')) return parseFloat(v);
+  if (v.endsWith('s')) return parseFloat(v) * 1000;
+  const n = parseFloat(v);
+  return Number.isNaN(n) ? null : n;
+}
+
+/** Resolve a duration token (ms). `name` is one of the --duration-* suffixes. */
+export function duration(name = 'normal') {
+  const fallback = FALLBACK.duration[name] ?? FALLBACK.duration.normal;
+  const styles = root();
+  if (!styles) return fallback;
+  return parseMs(styles.getPropertyValue(`--duration-${name}`)) ?? fallback;
+}
+
+/** Resolve an easing token. `name` is one of the --ease-* suffixes. */
+export function ease(name = 'default') {
+  const fallback = FALLBACK.ease[name] ?? FALLBACK.ease.default;
+  const styles = root();
+  if (!styles) return fallback;
+  const value = styles.getPropertyValue(`--ease-${name}`).trim();
+  return value || fallback;
+}
+
+/** True when the user prefers reduced motion. */
+export function reduced() {
+  return typeof window !== 'undefined'
+    && typeof window.matchMedia === 'function'
+    && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}