@adukiorg/anza 0.2.0

package/src/core/animations/usage.md

@@ -0,0 +1,301 @@
+# Native Animations Usage Guide
+
+The Native animations layer provides WAAPI (Web Animations API) helpers, easing curves, keyframe templates, stagger groups, scroll-linked animations, and view transitions. All timing values are sourced from CSS motion tokens for consistency.
+
+Import from the animations entry point:
+
+```javascript
+import { animate, stagger, register, scroll, view, timing, keyframes, reduced } from '@adukiorg/anza/animations';
+```
+
+## 1. Basic Animation
+
+Animate a single element with keyframes and timing options:
+
+```javascript
+import { animate, timing } from '@adukiorg/anza/animations';
+
+const animation = animate(
+  element,
+  [
+    { opacity: 0, transform: 'translateY(20px)' },
+    { opacity: 1, transform: 'translateY(0)' }
+  ],
+  timing()
+);
+```
+
+The `timing()` helper defaults to the CSS `--duration-normal` and `--ease-default` tokens:
+
+```javascript
+timing(duration, easing, fill)
+// Defaults: timing('normal', 'default', 'both')
+```
+
+Custom timing:
+
+```javascript
+timing(300, 'ease-out', 'forwards')
+```
+
+## 2. Timing and Easing
+
+### Timing Presets
+
+Use the `Timing` object for named easing curves:
+
+```javascript
+import { Timing } from '@adukiorg/anza/animations';
+
+animate(element, keyframes, {
+  duration: 250,
+  easing: Timing.FAST,      // --ease-out
+  fill: 'both'
+});
+```
+
+Available easing curves:
+
+| Constant | Value | Token |
+|----------|-------|-------|
+| `Timing.EASE` | `ease` | - |
+| `Timing.EASE_IN` | `ease-in` | - |
+| `Timing.EASE_OUT` | `ease-out` | - |
+| `Timing.EASE_IN_OUT` | `ease-in-out` | - |
+| `Timing.LINEAR` | `linear` | - |
+| `Timing.DEFAULT` | `--ease-default` | CSS token |
+| `Timing.SMOOTH` | `--ease-default` | CSS token |
+| `Timing.FAST` | `--ease-out` | CSS token |
+| `Timing.SOFT` | `--ease-in-out` | CSS token |
+| `Timing.BOUNCE` | `--ease-spring` | CSS token |
+| `Timing.SPRING` | `--ease-spring` | CSS token |
+
+### Duration Tokens
+
+Durations are read from CSS `--duration-*` tokens:
+
+```javascript
+import { duration } from '@adukiorg/anza/animations';
+
+const fast = duration('fast');    // --duration-fast (100ms)
+const normal = duration('normal'); // --duration-normal (200ms)
+const slow = duration('slow');    // --duration-slow (300ms)
+```
+
+Fallback values are used when CSS tokens are unavailable (SSR, missing styles).
+
+## 3. Keyframe Templates
+
+Use `keyframes()` for common transition patterns:
+
+```javascript
+import { keyframes, animate } from '@adukiorg/anza/animations';
+
+// Fade in/out
+animate(element, keyframes('fade'), timing());
+
+// Slide (default: Y axis)
+animate(element, keyframes('slide', { axis: 'y', from: '20px' }), timing());
+
+// Scale
+animate(element, keyframes('scale'), timing());
+
+// Zoom
+animate(element, keyframes('zoom'), timing());
+
+// Blur
+animate(element, keyframes('blur'), timing());
+```
+
+Custom keyframe options:
+
+```javascript
+keyframes('fade', { from: 0.5, to: 1 })
+keyframes('slide', { axis: 'x', from: '100px' })
+keyframes('scale', { from: 0.8 })
+```
+
+## 4. Staggered Animations
+
+Animate a group of elements with sequential delays:
+
+```javascript
+import { stagger } from '@adukiorg/anza/animations';
+
+const cards = document.querySelectorAll('.card');
+
+stagger(Array.from(cards), [
+  { opacity: 0, transform: 'translateY(20px)' },
+  { opacity: 1, transform: 'translateY(0)' }
+], {
+  duration: 250,
+  staggerDelay: 60
+});
+```
+
+Returns an array of `Animation` objects for control:
+
+```javascript
+const animations = stagger(elements, keyframes, options);
+animations.forEach(anim => anim.pause());
+```
+
+## 5. Scroll-Linked Animations
+
+Link animations to scroll position:
+
+```javascript
+import { scroll } from '@adukiorg/anza/animations';
+
+const stop = scroll(element, [
+  { transform: 'translateY(0)' },
+  { transform: 'translateY(-50px)' }
+], {
+  range: [0, 1],  // 0-1 scroll progress
+  target: document.documentElement
+});
+```
+
+Call the returned function to clean up:
+
+```javascript
+stop(); // Disconnects ScrollTimeline
+```
+
+## 6. View Transitions
+
+Use the View Transitions API for page navigation animations:
+
+```javascript
+import { view } from '@adukiorg/anza/animations';
+
+view(async () => {
+  // Update DOM here
+  document.body.classList.add('new-page');
+});
+```
+
+Custom transition:
+
+```javascript
+view(async () => {
+  await updateDOM();
+}, {
+  duration: 300,
+  easing: 'ease-out'
+});
+```
+
+## 7. Reduced Motion
+
+Check for user's motion preference:
+
+```javascript
+import { reduced } from '@adukiorg/anza/animations';
+
+if (!reduced()) {
+  animate(element, keyframes('fade'), timing());
+}
+```
+
+The `reduced()` function checks `prefers-reduced-motion: reduce`.
+
+## 8. Token Integration
+
+All timing values are sourced from CSS motion tokens:
+
+```css
+/* src/tokens/primitives/motion.css */
+:root {
+  --duration-instant: 50ms;
+  --duration-fast: 100ms;
+  --duration-normal: 200ms;
+  --duration-slow: 300ms;
+  --duration-slower: 500ms;
+
+  --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-in: cubic-bezier(0.4, 0, 1, 1);
+  --ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --ease-in-out: cubic-bezier(0.4, 0, 0.6, 1);
+  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+  --ease-linear: linear;
+}
+```
+
+JS animations automatically use these values, ensuring CSS and JS animations share one source of truth.
+
+## 9. Animation Control
+
+`animate()` returns a WAAPI `Animation` object:
+
+```javascript
+const anim = animate(element, keyframes, timing());
+
+anim.pause();
+anim.play();
+anim.finish();
+anim.cancel();
+anim.reverse();
+
+anim.finished.then(() => console.log('done'));
+```
+
+## 10. Registered Presets
+
+Common animation presets are pre-registered for convenience:
+
+```javascript
+import { animate } from '@adukiorg/anza/animations';
+
+// Use registered presets by name
+animate(element, 'fade');
+animate(element, 'slide');
+animate(element, 'slide-x');
+animate(element, 'slide-y');
+animate(element, 'scale');
+animate(element, 'zoom');
+animate(element, 'blur');
+```
+
+Available presets:
+- `fade` - Opacity transition
+- `slide` - Y-axis slide
+- `slide-x` - X-axis slide
+- `slide-y` - Y-axis slide
+- `scale` - Scale from 0.95 to 1
+- `zoom` - Scale from 1.1 to 1
+- `blur` - Blur transition
+
+Register custom presets:
+
+```javascript
+import { registry, keyframes, timing } from '@adukiorg/anza/animations';
+
+registry.register('myPreset', keyframes('fade'), timing(300));
+```
+
+## 11. Sequence Helper
+
+Chain animations sequentially, each starting when the previous finishes:
+
+```javascript
+import { sequence } from '@adukiorg/anza/animations';
+
+const { finished } = sequence([
+  [element1, keyframes('fade'), timing()],
+  [element2, keyframes('slide'), timing()],
+  [element3, keyframes('scale'), timing()]
+]);
+
+await finished;
+```
+
+Each step is `[element, animationInput, options?]`. Returns `{ finished }` promise.
+
+## 11. Performance Guidelines
+
+- Use `requestAnimationFrame` for visual updates (handled by WAAPI)
+- Prefer transforms and opacity for GPU-accelerated properties
+- Respect `prefers-reduced-motion` for accessibility
+- Use `stagger()` for list animations instead of manual delays
+- Clean up scroll-linked animations with the returned disposer

package/src/core/animations/waapi.js

@@ -0,0 +1,86 @@
+/**
+ * src/core/animations/waapi.js
+ *
+ * WAAPI Easing Curves and Keyframe Helpers.
+ * Easing curves and durations are sourced from the CSS motion tokens
+ * (`--ease-*`, `--duration-*`) via ./tokens.js, so JS animations and CSS share a
+ * single source of truth. Values fall back to the token defaults when the
+ * document is unavailable.
+ *
+ * Source: doc 03 — Native CSS Architecture §6, doc 12 — Performance §4
+ */
+
+import { duration as durationToken, ease } from './tokens.js';
+
+/**
+ * Named easing curves. CSS keywords are returned verbatim; the curated curves
+ * resolve to the matching `--ease-*` motion token at access time.
+ */
+export const Timing = {
+  EASE: 'ease',
+  EASE_IN: 'ease-in',
+  EASE_OUT: 'ease-out',
+  EASE_IN_OUT: 'ease-in-out',
+  LINEAR: 'linear',
+  get DEFAULT() { return ease('default'); },
+  get SMOOTH() { return ease('default'); },
+  get FAST() { return ease('out'); },
+  get SOFT() { return ease('in-out'); },
+  get BOUNCE() { return ease('spring'); },
+  get SPRING() { return ease('spring'); }
+};
+
+/**
+ * Convenience helper to format WAAPI timing descriptors. Duration defaults to the
+ * `--duration-normal` token; easing defaults to the `--ease-default` token.
+ */
+export function timing(duration = durationToken('normal'), easing = ease('default'), fill = 'both') {
+  return { duration, easing, fill };
+}
+
+/**
+ * Builds keyframe arrays for common transition templates.
+ * Types: fade, slide, scale, zoom, blur.
+ */
+export function keyframes(type, options = {}) {
+  if (type === 'fade') {
+    return [
+      { opacity: options.from ?? 0 },
+      { opacity: options.to ?? 1 }
+    ];
+  }
+
+  if (type === 'slide') {
+    const axis = options.axis ?? 'y';
+    const amount = options.from ?? '20px';
+    const transformFrom = axis === 'x' ? `translateX(${amount})` : `translateY(${amount})`;
+
+    return [
+      { transform: transformFrom, opacity: 0 },
+      { transform: 'translate(0, 0)', opacity: 1 }
+    ];
+  }
+
+  if (type === 'scale') {
+    return [
+      { transform: `scale(${options.from ?? 0.95})`, opacity: 0 },
+      { transform: 'scale(1)', opacity: 1 }
+    ];
+  }
+
+  if (type === 'zoom') {
+    return [
+      { transform: `scale(${options.from ?? 1.1})`, opacity: 0 },
+      { transform: 'scale(1)', opacity: 1 }
+    ];
+  }
+
+  if (type === 'blur') {
+    return [
+      { filter: `blur(${options.from ?? '8px'})`, opacity: 0 },
+      { filter: 'blur(0)', opacity: 1 }
+    ];
+  }
+
+  return [];
+}

package/src/core/api/cache.js

@@ -0,0 +1,120 @@
+/**
+ * src/core/api/cache.js
+ *
+ * Direct Cache API integration on the main thread.
+ * Implements three standard caching strategies:
+ * 1. cache-first: Shell & static assets cache.
+ * 2. network-first: Dynamic API data fallback.
+ * 3. stale-while-revalidate: High-performance near-instant timelines/feeds.
+ *
+ * Source: doc 11 — Networking §6
+ */
+
+import { cache as apiCache } from './caches/index.js';
+
+const CACHE_NAME = 'platform-api-cache';
+
+/**
+ * Handles request caching using declared strategies and TTL controls.
+ */
+export async function handle(descriptor, executeFetch) {
+  const { cache: strategy, url, method = 'GET' } = descriptor;
+
+  // Caching is strictly limited to GET requests and when Cache API is present
+  if (method !== 'GET' || typeof caches === 'undefined') {
+    return executeFetch(descriptor);
+  }
+
+  // Check for fine-grained TTL / Expiry options
+  const ttl = descriptor.expiry || descriptor.ttl || (strategy && typeof strategy === 'object' ? strategy.expiry || strategy.ttl : null);
+
+  if (ttl) {
+    const cached = await apiCache.get(url);
+    if (cached) return cached;
+
+    const response = await executeFetch(descriptor);
+    if (response.ok) {
+      await apiCache.set(url, response.clone(), ttl);
+    }
+    return response;
+  }
+
+  // Fallback to legacy string-based strategies if cache strategy is specified
+  if (!strategy || typeof strategy !== 'string') {
+    return executeFetch(descriptor);
+  }
+
+  const storage = await caches.open(CACHE_NAME);
+
+  if (strategy === 'cache-first') {
+    const cached = await storage.match(url);
+    if (cached) return cached;
+
+    const response = await executeFetch(descriptor);
+    if (response.ok) {
+      await storage.put(url, response.clone());
+    }
+    return response;
+  }
+
+  if (strategy === 'network-first') {
+    try {
+      const response = await executeFetch(descriptor);
+      if (response.ok) {
+        await storage.put(url, response.clone());
+      }
+      return response;
+    } catch (err) {
+      const cached = await storage.match(url);
+      if (cached) return cached;
+      throw err; // propagates the normalized error if no cache is present
+    }
+  }
+
+  if (strategy === 'stale-while-revalidate') {
+    const cached = await storage.match(url);
+
+    const revalidate = async () => {
+      try {
+        const response = await executeFetch(descriptor);
+        if (response.ok) {
+          await storage.put(url, response.clone());
+          // Broadcast to the system that state cache has updated
+          globalThis.dispatchEvent(
+            new CustomEvent('cache:updated', {
+              detail: { url, status: 'updated' }
+            })
+          );
+        }
+      } catch (err) {
+        console.warn(`Background revalidation failed for ${url}:`, err);
+      }
+    };
+
+    if (cached) {
+      // Trigger background revalidation asynchronously
+      revalidate();
+      return cached;
+    }
+
+    const response = await executeFetch(descriptor);
+    if (response.ok) {
+      await storage.put(url, response.clone());
+    }
+    return response;
+  }
+
+  return executeFetch(descriptor);
+}
+
+/**
+ * Clears specific entry or entire API cache store.
+ */
+export async function invalidate(url) {
+  if (url) {
+    await apiCache.delete(url);
+  } else {
+    await apiCache.clear();
+  }
+}
+

package/src/core/api/caches/glob.js

@@ -0,0 +1,24 @@
+/**
+ * src/core/api/caches/glob.js
+ *
+ * Converts a simple glob pattern into a regular expression for namespace-based clearing.
+ *
+ * Source: doc 11 — Networking §6, core/api/plan.md
+ */
+
+/**
+ * Translates a glob pattern (e.g., "/user/*") into a RegExp object.
+ * Supports standard * wildcards.
+ *
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+export function globToRegex(pattern) {
+  // Escape standard regex special characters
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  
+  // Replace * with .* to permit wildcard matching
+  const wildcarded = escaped.replace(/\*/g, '.*');
+  
+  return new RegExp(`^${wildcarded}$`);
+}

package/src/core/api/caches/index.js

@@ -0,0 +1,118 @@
+/**
+ * src/core/api/caches/index.js
+ *
+ * Unified Cache API wrapper for the dynamic API client.
+ * Implements granular TTL/expiry controls and glob namespace invalidation patterns.
+ *
+ * Source: doc 11 — Networking §6, core/api/plan.md
+ */
+
+import { globToRegex } from './glob.js';
+
+const CACHE_NAME = 'platform-api-cache';
+
+export class ApiCache {
+  constructor(name = CACHE_NAME) {
+    this.name = name;
+  }
+
+  /**
+   * Opens the underlying cache store.
+   *
+   * @returns {Promise<Cache>}
+   */
+  open() {
+    return caches.open(this.name);
+  }
+
+  /**
+   * Retrieves an item from the cache store.
+   * Evicts the record and returns null if the entry has expired.
+   *
+   * @param {string|Request} request
+   * @returns {Promise<Response|null>}
+   */
+  async get(request) {
+    if (typeof caches === 'undefined') return null;
+    
+    const store = await this.open();
+    const req = typeof request === 'string' ? new Request(request) : request;
+    const cached = await store.match(req);
+
+    if (!cached) return null;
+
+    const expiresAt = cached.headers.get('x-expires-at');
+    if (expiresAt && Date.now() > Number(expiresAt)) {
+      await store.delete(req);
+      return null;
+    }
+
+    return cached.clone();
+  }
+
+  /**
+   * Caches a Response with a designated TTL.
+   *
+   * @param {string|Request} request
+   * @param {Response} response
+   * @param {number} ttlMs
+   * @returns {Promise<void>}
+   */
+  async set(request, response, ttlMs) {
+    if (typeof caches === 'undefined') return;
+
+    const store = await this.open();
+    const req = typeof request === 'string' ? new Request(request) : request;
+    const headers = new Headers(response.headers);
+    
+    if (ttlMs) {
+      headers.set('x-expires-at', String(Date.now() + ttlMs));
+    }
+
+    const cloned = new Response(response.body ? response.clone().body : null, {
+      status: response.status,
+      statusText: response.statusText,
+      headers
+    });
+
+    await store.put(req, cloned);
+  }
+
+  /**
+   * Removes cached entries matching the provided url or glob pattern.
+   *
+   * @param {string} pattern
+   * @returns {Promise<void>}
+   */
+  async delete(pattern) {
+    if (typeof caches === 'undefined') return;
+
+    const store = await this.open();
+
+    if (pattern.includes('*')) {
+      const regex = globToRegex(pattern);
+      const keys = await store.keys();
+      
+      for (const req of keys) {
+        const urlObj = new URL(req.url);
+        if (regex.test(req.url) || regex.test(urlObj.pathname)) {
+          await store.delete(req);
+        }
+      }
+    } else {
+      await store.delete(pattern);
+    }
+  }
+
+  /**
+   * Completely purges the entire API cache store.
+   *
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    if (typeof caches === 'undefined') return;
+    await caches.delete(this.name);
+  }
+}
+
+export const cache = new ApiCache();