@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/utils/animation-utils.js

@@ -0,0 +1,323 @@
+"use strict";
+/**
+ * Animation Utilities
+ *
+ * Phase 1: Helper functions for working with animations
+ * - Animation class building
+ * - Dynamic style generation
+ * - Animation timing calculations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateGradientBorderCSS = generateGradientBorderCSS;
+exports.calculateAnimationDuration = calculateAnimationDuration;
+exports.buildAnimationClass = buildAnimationClass;
+exports.createLinkAnimation = createLinkAnimation;
+exports.shouldSimplifyAnimations = shouldSimplifyAnimations;
+exports.getOptimalAnimationSettings = getOptimalAnimationSettings;
+exports.msToSeconds = msToSeconds;
+exports.secondsToMs = secondsToMs;
+exports.createAnimationCustomProperties = createAnimationCustomProperties;
+exports.supportsAnimations = supportsAnimations;
+exports.prefersReducedMotion = prefersReducedMotion;
+exports.debounce = debounce;
+exports.throttle = throttle;
+exports.requestAnimFrame = requestAnimFrame;
+exports.cancelAnimFrame = cancelAnimFrame;
+exports.measureAnimationFPS = measureAnimationFPS;
+exports.isValidAnimationType = isValidAnimationType;
+exports.isValidBorderAnimationType = isValidBorderAnimationType;
+exports.isValidStatus = isValidStatus;
+/**
+ * Generate dynamic CSS for gradient border animation
+ *
+ * @param colors - Array of gradient colors
+ * @param duration - Animation duration in seconds
+ * @returns CSS string for gradient animation
+ */
+function generateGradientBorderCSS(colors, duration = 3) {
+    if (colors.length < 2) {
+        colors = ['#667eea', '#764ba2']; // Default colors
+    }
+    // Create gradient stops
+    const stops = colors.map((color, index) => {
+        const percentage = (index * 100) / (colors.length - 1);
+        return `${color} ${percentage}%`;
+    }).join(', ');
+    // Duplicate colors to create seamless loop
+    const seamlessStops = [
+        ...colors.map((color, index) => `${color} ${(index * 25)}%`),
+        colors[0] + ' 100%'
+    ].join(', ');
+    return `
+    background: linear-gradient(90deg, ${seamlessStops});
+    background-size: 200% 100%;
+    animation-duration: ${duration}s;
+  `;
+}
+/**
+ * Calculate animation duration based on speed setting
+ *
+ * @param baseSpeed - Base animation speed ('slow' | 'normal' | 'fast')
+ * @param baseDuration - Base duration in seconds (default: 1)
+ * @returns Duration in seconds
+ */
+function calculateAnimationDuration(baseSpeed, baseDuration = 1) {
+    switch (baseSpeed) {
+        case 'slow':
+            return baseDuration * 2;
+        case 'fast':
+            return baseDuration * 0.5;
+        case 'normal':
+        default:
+            return baseDuration;
+    }
+}
+/**
+ * Build animation class string from individual parts
+ *
+ * @param parts - Array of class name parts (filters out empty/undefined)
+ * @returns Space-separated class string
+ */
+function buildAnimationClass(...parts) {
+    return parts.filter(Boolean).join(' ');
+}
+/**
+ * Create link animation configuration
+ *
+ * @param type - Animation type
+ * @param options - Additional options
+ * @returns LinkAnimation object
+ */
+function createLinkAnimation(type, options = {}) {
+    return {
+        type,
+        speed: options.speed || 'normal',
+        direction: options.direction || 'forward',
+        duration: options.duration
+    };
+}
+/**
+ * Check if animation should be simplified for performance
+ *
+ * @param animationCount - Number of currently animating elements
+ * @param performanceThreshold - Threshold for simplification (default: 50)
+ * @returns Whether to simplify animations
+ */
+function shouldSimplifyAnimations(animationCount, performanceThreshold = 50) {
+    return animationCount > performanceThreshold;
+}
+/**
+ * Get optimal animation settings based on browser performance
+ *
+ * @returns Recommended animation settings
+ */
+function getOptimalAnimationSettings() {
+    // Check if we're on a low-end device
+    const isLowEnd = typeof navigator !== 'undefined' &&
+        (navigator.deviceMemory && navigator.deviceMemory < 4) ||
+        (navigator.hardwareConcurrency && navigator.hardwareConcurrency < 4);
+    if (isLowEnd) {
+        return {
+            maxAnimatedEdges: 25,
+            maxAnimatedNodes: 15,
+            preferredAnimationType: 'simple'
+        };
+    }
+    return {
+        maxAnimatedEdges: 100,
+        maxAnimatedNodes: 50,
+        preferredAnimationType: 'complex'
+    };
+}
+/**
+ * Convert animation duration from milliseconds to seconds
+ *
+ * @param milliseconds - Duration in milliseconds
+ * @returns Duration in seconds
+ */
+function msToSeconds(milliseconds) {
+    return milliseconds / 1000;
+}
+/**
+ * Convert animation duration from seconds to milliseconds
+ *
+ * @param seconds - Duration in seconds
+ * @returns Duration in milliseconds
+ */
+function secondsToMs(seconds) {
+    return seconds * 1000;
+}
+/**
+ * Create CSS custom properties object for animation
+ *
+ * @param options - Animation options
+ * @returns Object with CSS custom properties
+ */
+function createAnimationCustomProperties(options) {
+    const props = {};
+    if (options.duration !== undefined) {
+        props['--animation-duration'] = `${options.duration}s`;
+    }
+    if (options.strokeWidth !== undefined) {
+        props['--link-stroke-width'] = `${options.strokeWidth}px`;
+    }
+    if (options.color) {
+        props['--animation-color'] = options.color;
+    }
+    if (options.glowColor) {
+        props['--glow-color'] = options.glowColor;
+    }
+    return props;
+}
+/**
+ * Check if browser supports CSS animations
+ *
+ * @returns Whether CSS animations are supported
+ */
+function supportsAnimations() {
+    if (typeof document === 'undefined') {
+        return false;
+    }
+    const element = document.createElement('div');
+    return 'animation' in element.style ||
+        'webkitAnimation' in element.style ||
+        'mozAnimation' in element.style;
+}
+/**
+ * Check if user prefers reduced motion
+ *
+ * @returns Whether user prefers reduced motion
+ */
+function prefersReducedMotion() {
+    if (typeof window === 'undefined' || !window.matchMedia) {
+        return false;
+    }
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+/**
+ * Debounce function for performance optimization
+ * Useful for animation updates during resize/scroll
+ *
+ * @param func - Function to debounce
+ * @param wait - Wait time in milliseconds
+ * @returns Debounced function
+ */
+function debounce(func, wait) {
+    let timeout = null;
+    return function executedFunction(...args) {
+        const later = () => {
+            timeout = null;
+            func(...args);
+        };
+        if (timeout !== null) {
+            clearTimeout(timeout);
+        }
+        timeout = setTimeout(later, wait);
+    };
+}
+/**
+ * Throttle function for performance optimization
+ * Useful for animation updates during continuous events
+ *
+ * @param func - Function to throttle
+ * @param limit - Time limit in milliseconds
+ * @returns Throttled function
+ */
+function throttle(func, limit) {
+    let inThrottle = false;
+    return function executedFunction(...args) {
+        if (!inThrottle) {
+            func(...args);
+            inThrottle = true;
+            setTimeout(() => inThrottle = false, limit);
+        }
+    };
+}
+/**
+ * Request animation frame wrapper with fallback
+ *
+ * @param callback - Function to call on next frame
+ * @returns Request ID
+ */
+function requestAnimFrame(callback) {
+    if (typeof window === 'undefined') {
+        return setTimeout(callback, 16);
+    }
+    return (window.requestAnimationFrame ||
+        window.webkitRequestAnimationFrame ||
+        window.mozRequestAnimationFrame ||
+        window.oRequestAnimationFrame ||
+        window.msRequestAnimationFrame ||
+        function (cb) { return setTimeout(cb, 16); })(callback);
+}
+/**
+ * Cancel animation frame wrapper with fallback
+ *
+ * @param id - Request ID to cancel
+ */
+function cancelAnimFrame(id) {
+    if (typeof window === 'undefined') {
+        clearTimeout(id);
+        return;
+    }
+    (window.cancelAnimationFrame ||
+        window.webkitCancelAnimationFrame ||
+        window.mozCancelAnimationFrame ||
+        window.oCancelAnimationFrame ||
+        window.msCancelAnimationFrame ||
+        clearTimeout)(id);
+}
+/**
+ * Measure animation FPS (for debugging/performance monitoring)
+ *
+ * @param duration - Duration to measure in milliseconds
+ * @returns Promise that resolves to average FPS
+ */
+function measureAnimationFPS(duration = 1000) {
+    return new Promise((resolve) => {
+        let frames = 0;
+        let lastTime = performance.now();
+        const endTime = lastTime + duration;
+        function countFrame() {
+            frames++;
+            const currentTime = performance.now();
+            if (currentTime < endTime) {
+                requestAnimFrame(countFrame);
+            }
+            else {
+                const elapsed = currentTime - lastTime;
+                const fps = (frames / elapsed) * 1000;
+                resolve(Math.round(fps));
+            }
+        }
+        requestAnimFrame(countFrame);
+    });
+}
+/**
+ * Validate animation type
+ *
+ * @param type - Animation type to validate
+ * @returns Whether the type is valid
+ */
+function isValidAnimationType(type) {
+    return ['marching-ants', 'flow', 'pulse', 'none'].includes(type);
+}
+/**
+ * Validate border animation type
+ *
+ * @param type - Border animation type to validate
+ * @returns Whether the type is valid
+ */
+function isValidBorderAnimationType(type) {
+    return ['gradient', 'pulse', 'breathe', 'shimmer', 'none'].includes(type);
+}
+/**
+ * Validate status type
+ *
+ * @param status - Status to validate
+ * @returns Whether the status is valid
+ */
+function isValidStatus(status) {
+    return ['idle', 'pending', 'running', 'completed', 'error', 'warning'].includes(status);
+}
+//# sourceMappingURL=animation-utils.js.map

package/src/libs/renderer/src/utils/lru-cache.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal Map-based LRU cache.
+ *
+ * A `Map` iterates in insertion order, so the FIRST key is always the
+ * least-recently-used one. On `get`, the entry is re-inserted (moved to the
+ * end) to mark it most-recently-used; on `set`, once the size exceeds the
+ * capacity the oldest entries are evicted from the front.
+ *
+ * This is a drop-in replacement for the subset of the `Map` API the SVG
+ * renderer's vnode cache uses (`get` / `set` / `has` / `delete` / `clear` /
+ * `size`), keeping the renderer free of any runtime dependency on the engine.
+ */
+export declare class LruCache<K, V> {
+    private readonly capacity;
+    private readonly map;
+    constructor(capacity: number);
+    /** Current number of cached entries. */
+    get size(): number;
+    /** Look up a value, marking it most-recently-used. */
+    get(key: K): V | undefined;
+    /** Insert/update a value and evict the oldest entries past capacity. */
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    delete(key: K): boolean;
+    /**
+     * A SNAPSHOT of the current keys, oldest first.
+     *
+     * Snapshot, not the live Map iterator: the only caller (the renderer's
+     * theme-swap invalidation) deletes while it walks, and mutating a Map during
+     * its own iteration is how you skip entries.
+     */
+    keys(): K[];
+    clear(): void;
+}

package/src/libs/renderer/src/utils/lru-cache.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LruCache = void 0;
+/**
+ * Minimal Map-based LRU cache.
+ *
+ * A `Map` iterates in insertion order, so the FIRST key is always the
+ * least-recently-used one. On `get`, the entry is re-inserted (moved to the
+ * end) to mark it most-recently-used; on `set`, once the size exceeds the
+ * capacity the oldest entries are evicted from the front.
+ *
+ * This is a drop-in replacement for the subset of the `Map` API the SVG
+ * renderer's vnode cache uses (`get` / `set` / `has` / `delete` / `clear` /
+ * `size`), keeping the renderer free of any runtime dependency on the engine.
+ */
+class LruCache {
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.map = new Map();
+    }
+    /** Current number of cached entries. */
+    get size() {
+        return this.map.size;
+    }
+    /** Look up a value, marking it most-recently-used. */
+    get(key) {
+        if (!this.map.has(key)) {
+            return undefined;
+        }
+        // Re-insert to move the entry to the most-recently-used position.
+        const value = this.map.get(key);
+        this.map.delete(key);
+        this.map.set(key, value);
+        return value;
+    }
+    /** Insert/update a value and evict the oldest entries past capacity. */
+    set(key, value) {
+        // Delete first so an update also refreshes recency (moves to the end).
+        if (this.map.has(key)) {
+            this.map.delete(key);
+        }
+        this.map.set(key, value);
+        // Evict least-recently-used entries (front of the Map) past capacity.
+        while (this.map.size > this.capacity) {
+            const oldest = this.map.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.map.delete(oldest);
+        }
+    }
+    has(key) {
+        return this.map.has(key);
+    }
+    delete(key) {
+        return this.map.delete(key);
+    }
+    /**
+     * A SNAPSHOT of the current keys, oldest first.
+     *
+     * Snapshot, not the live Map iterator: the only caller (the renderer's
+     * theme-swap invalidation) deletes while it walks, and mutating a Map during
+     * its own iteration is how you skip entries.
+     */
+    keys() {
+        return Array.from(this.map.keys());
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+exports.LruCache = LruCache;
+//# sourceMappingURL=lru-cache.js.map

package/src/libs/renderer/src/viewport/index.d.ts

@@ -0,0 +1 @@
+export * from './viewport-controller';

package/src/libs/renderer/src/viewport/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// Framework-agnostic camera: screen↔world, zoom clamping, pan, viewBox convention.
+tslib_1.__exportStar(require("./viewport-controller"), exports);
+//# sourceMappingURL=index.js.map

package/src/libs/renderer/src/viewport/viewport-controller.d.ts

@@ -0,0 +1,198 @@
+import type { Rectangle } from '../types/geometry.types';
+/**
+ * A point in world space. Declared structurally (rather than imported from
+ * `@grafloria/engine`) so the viewport module stays dependency-free: camera math
+ * needs no diagram model. Structurally identical to `Point` from `@grafloria/engine`,
+ * so the two interoperate without conversion.
+ */
+export interface ViewportPoint {
+    x: number;
+    y: number;
+}
+/**
+ * The subset of `DOMRect` the camera actually needs. Any `getBoundingClientRect()`
+ * result satisfies it; tests can pass a plain object. Keeping it structural is
+ * what lets this class run in Node with no DOM.
+ */
+export interface CanvasRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Immutable snapshot of the camera. */
+export interface ViewportState {
+    viewport: Rectangle;
+    zoom: number;
+}
+export interface ViewportControllerOptions {
+    /**
+     * Camera rectangle. `x`/`y` are WORLD coordinates; `width`/`height` are the
+     * canvas's CSS-PIXEL dimensions (see the coordinate contract below).
+     */
+    viewport?: Rectangle;
+    zoom?: number;
+    /** Default 0.1 — matches `DiagramCanvasComponent.minZoom`. */
+    minZoom?: number;
+    /** Default 3.0 — matches `DiagramCanvasComponent.maxZoom`. */
+    maxZoom?: number;
+    /** Additive step applied per wheel notch. Default 0.1. */
+    zoomSensitivity?: number;
+}
+export type ViewportChangeListener = (state: ViewportState) => void;
+/** Remove a previously registered listener. */
+export type Unsubscribe = () => void;
+/**
+ * ViewportController — the framework-agnostic camera.
+ *
+ * This is the piece every framework wrapper otherwise re-implements (and gets
+ * subtly wrong): screen↔world conversion, zoom clamping, pan accumulation, and
+ * the `viewBox` convention that the SVG renderer and the hit-tester MUST agree
+ * on. Owning it here means a React/Vue/web-component host inherits pixel-exact
+ * hit-testing for free.
+ *
+ * Like {@link InteractionController} it answers **"what is the camera now?"** and
+ * never **"who should re-render?"** — hosts subscribe via {@link onChange} and
+ * translate that into their own render trigger (`markForCheck`, `setState`, …).
+ * It has zero framework imports, zero engine imports, and no DOM dependency:
+ * callers hand it a plain {@link CanvasRect}, not an element.
+ *
+ * ## The coordinate contract
+ *
+ * `viewport.x/y` are WORLD coordinates. `viewport.width/height` are the canvas's
+ * **CSS-pixel** size — NOT a world-space span. The world span actually shown is
+ * derived by dividing by `zoom`, which is exactly what {@link getViewBox} does:
+ *
+ * ```text
+ *   center      = (viewport.x + w/2, viewport.y + h/2)      // zoom is centre-preserving
+ *   viewBox.w/h = (w / zoom, h / zoom)                      // higher zoom ⇒ less world visible
+ *   viewBox.x/y = center − viewBox.w/h / 2
+ * ```
+ *
+ * This is the identical formula `SVGRenderer.render()` applies to the viewport
+ * it is handed (`libs/renderer/src/svg/svg-renderer.ts`, "Apply zoom to viewBox"),
+ * and the one {@link clientToWorld} inverts. Because both sides derive from the
+ * same {@link getViewBox}, screen→world round-trips exactly at any zoom — see
+ * the round-trip tests in `viewport-controller.spec.ts`.
+ *
+ * ⚠️ Feed {@link getRenderViewport} — not a pre-scaled rectangle — to
+ * `IRenderer.render(viewport, zoom)`. Dividing width/height by `zoom` *before*
+ * calling `render()` makes the renderer divide by `zoom` a second time, applying
+ * zoom quadratically and desynchronising the picture from the hit-tester at any
+ * zoom ≠ 1. (`DiagramCanvasComponent.calculateActualViewport()` currently does
+ * exactly that; the fix belongs to the zoom card and is why this convention now
+ * lives in one place.)
+ */
+export declare class ViewportController {
+    protected viewport: Rectangle;
+    protected zoom: number;
+    protected readonly minZoom: number;
+    protected readonly maxZoom: number;
+    protected readonly zoomSensitivity: number;
+    private readonly listeners;
+    constructor(options?: ViewportControllerOptions);
+    getViewport(): Rectangle;
+    getZoom(): number;
+    getState(): ViewportState;
+    /** Replace the camera rectangle wholesale. */
+    setViewport(viewport: Rectangle): void;
+    /**
+     * Track the canvas element's pixel size. Call on mount and on resize: the
+     * width/height of the camera rect must stay equal to the canvas's CSS-pixel
+     * size for {@link clientToWorld} to be the true inverse of the rendered
+     * `viewBox` (see the coordinate contract).
+     */
+    setCanvasSize(width: number, height: number): void;
+    /** Convenience form of {@link setCanvasSize} taking a `getBoundingClientRect()`. */
+    syncCanvasSize(rect: CanvasRect): void;
+    /** Clamp to `[minZoom, maxZoom]`. Non-finite input falls back to the current zoom. */
+    clampZoom(zoom: number): number;
+    /** Set zoom (centre-preserving), clamped. Returns the zoom actually applied. */
+    setZoom(zoom: number): number;
+    /**
+     * Additive zoom step, clamped — the convention the Angular canvas's wheel
+     * handler uses (`zoom + delta`, not `zoom * factor`). Returns the applied zoom.
+     */
+    zoomBy(delta: number): number;
+    /**
+     * Apply one wheel notch. Mirrors `DiagramCanvasComponent.onWheel`: scrolling
+     * DOWN (`deltaY > 0`) zooms OUT by `zoomSensitivity`, scrolling up zooms in.
+     */
+    zoomByWheel(deltaY: number): number;
+    /**
+     * Cursor-anchored zoom: change zoom while keeping the world point currently
+     * under `(clientX, clientY)` pinned to that same screen pixel. This is the
+     * standard "zoom towards the pointer" behaviour; the plain {@link setZoom} /
+     * {@link zoomByWheel} pair is centre-anchored instead.
+     *
+     * Returns the zoom actually applied (clamped).
+     */
+    zoomAtPoint(zoom: number, clientX: number, clientY: number, rect: CanvasRect): number;
+    /** Translate the camera by a WORLD-space delta. */
+    pan(dx: number, dy: number): void;
+    /**
+     * Translate the camera by a SCREEN-space (pixel) drag delta, converting to
+     * world units by dividing by zoom.
+     *
+     * Sign convention matches the canvas's middle-drag handler: pass
+     * `(lastClientX - clientX, lastClientY - clientY)`, i.e. dragging the pointer
+     * RIGHT moves the camera LEFT, so the content appears to follow the cursor.
+     */
+    panByScreenDelta(dxPx: number, dyPx: number): void;
+    /**
+     * The world-space rectangle actually visible — centre-preserving zoom applied
+     * to the camera rect. Identical to the `viewBox` `SVGRenderer` emits, and the
+     * basis of {@link clientToWorld}.
+     */
+    getViewBox(): Rectangle;
+    /** The `viewBox` attribute string: `"x y width height"`. */
+    getViewBoxString(): string;
+    /**
+     * The rectangle to hand to `IRenderer.render(viewport, zoom)` alongside
+     * {@link getZoom}. The renderer applies the zoom itself, so this is the raw
+     * camera rect — do NOT pre-divide it by zoom (see the class docs).
+     */
+    getRenderViewport(): Rectangle;
+    /**
+     * CSS transform that keeps an HTML overlay layer registered with the SVG
+     * layer in the hybrid renderer: `translate(...) scale(zoom)`.
+     *
+     * MUST be driven off the same {@link getViewBox} the SVG viewBox and
+     * {@link worldToClient} use — NOT the raw `viewport.x/y`. Since the camera
+     * rect's width/height became CANVAS PIXELS (see setCanvasSize), the visible
+     * world box is the pixel rect expanded around its centre by 1/zoom; the SVG
+     * renderer applies exactly that expansion (svg-renderer.ts `viewBoxX =
+     * centerX - width/zoom/2`). Using the raw `viewport.x` here omitted the
+     * `width*(1-zoom)/2` centring term, so the HTML custom-node layer drifted
+     * from the SVG at any zoom != 1 — invisible until a custom-node dashboard was
+     * framed with fitToBounds. Routing through getViewBox() makes a host at world
+     * W land at the identical pixel worldToClient(W) reports. Identical at zoom 1.
+     */
+    getHtmlLayerTransform(): string;
+    /**
+     * Convert a client/screen point (e.g. `event.clientX/Y`) into world space.
+     * Exact inverse of {@link worldToClient} at any zoom.
+     */
+    clientToWorld(clientX: number, clientY: number, rect: CanvasRect): ViewportPoint;
+    /**
+     * Convert a world point into client/screen coordinates — for positioning
+     * overlays, toolbars and tooltips over the canvas. Exact inverse of
+     * {@link clientToWorld}.
+     */
+    worldToClient(worldX: number, worldY: number, rect: CanvasRect): ViewportPoint;
+    /**
+     * Frame `bounds` (a world-space content rectangle): pick the largest clamped
+     * zoom at which it fits inside the canvas with `padding` CSS pixels of margin
+     * on every side, and centre it. A zero-area canvas or bounds is a no-op.
+     *
+     * Returns the zoom actually applied.
+     */
+    fitToBounds(bounds: Rectangle, padding?: number, options?: {
+        maxZoom?: number;
+    }): number;
+    /** Subscribe to camera changes. Returns an unsubscribe function. */
+    onChange(listener: ViewportChangeListener): Unsubscribe;
+    /** Drop all subscribers. */
+    dispose(): void;
+    protected emit(): void;
+}