@myrmidon/gve-snapshot-rendition 0.0.1

package/dist/animation/animation-factory.d.ts

@@ -0,0 +1,49 @@
+import { Logger } from "../core/logger";
+/**
+ * Animation function signature.
+ * Receives gsap instance, target element, and root SVG element.
+ * Returns a Promise that resolves when animation completes.
+ */
+export type AnimationFunction = (gsap: any, targetEl: SVGElement, rootEl: SVGElement) => Promise<void>;
+/**
+ * Factory for creating animation functions from code strings.
+ * This wraps user-provided GSAP animation code into executable functions.
+ */
+export declare class AnimationFactory {
+    private _logger;
+    private _gsap;
+    constructor(gsap: any, logger: Logger);
+    /**
+     * Create an animation function from a code string.
+     *
+     * @param code - The JavaScript code as a string that uses GSAP
+     * @param label - Optional label for debugging
+     * @returns An animation function that returns a Promise
+     */
+    createAnimation(code: string, label?: string): AnimationFunction;
+    /**
+     * Create an animation function from an ID reference.
+     * The ID should exist in the animations catalog.
+     *
+     * @param animationId - The ID of the animation (with or without # prefix)
+     * @param animationsCatalog - The catalog of animations from settings
+     * @param label - Optional label for debugging
+     * @returns An animation function or undefined if not found
+     */
+    createAnimationFromId(animationId: string, animationsCatalog: Record<string, string>, label?: string): AnimationFunction | undefined;
+    /**
+     * Resolve an animation property value to an animation function.
+     * Handles both direct code strings and ID references.
+     *
+     * @param animationValue - Either a code string or an ID reference (starting with #)
+     * @param animationsCatalog - The catalog of animations from settings
+     * @param label - Optional label for debugging
+     * @returns An animation function or undefined
+     */
+    resolveAnimation(animationValue: string | undefined, animationsCatalog: Record<string, string>, label?: string): AnimationFunction | undefined;
+    /**
+     * Create a no-op animation that resolves immediately.
+     * Used when no animation is specified.
+     */
+    createNoOpAnimation(): AnimationFunction;
+}

package/dist/core/color-palette.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Generate a pastel color palette for version tags with maximum visual distinction.
+ * Uses HSL color space to generate evenly distributed, light, pastel colors.
+ */
+export declare class ColorPalette {
+    private colors;
+    /**
+     * Generate a pastel color for a given version tag.
+     * The color generation is idempotent - same version tag always generates the same color.
+     * @param versionTag - Version tag (e.g., "v0", "v1", "v2")
+     * @returns Pastel color as hex string (e.g., "#FFE4E1")
+     */
+    getColor(versionTag: string): string;
+    /**
+     * Extract version number from version tag.
+     * @param versionTag - Version tag like "v0", "v1", etc.
+     * @returns Version number
+     */
+    private extractVersionNumber;
+    /**
+     * Generate a pastel color using HSL color space with golden ratio distribution.
+     * This ensures maximum visual distinction between colors.
+     * @param index - Version index number
+     * @returns Hex color string
+     */
+    private generatePastelColor;
+    /**
+     * Convert HSL to hex color.
+     * @param h - Hue (0-360)
+     * @param s - Saturation (0-100)
+     * @param l - Lightness (0-100)
+     * @returns Hex color string
+     */
+    private hslToHex;
+    /**
+     * Clear all cached colors.
+     */
+    clear(): void;
+}

package/dist/core/gve-snapshot-rendition.d.ts

@@ -0,0 +1,318 @@
+import { CharChainResult } from "../models";
+import { GveRenditionSettings } from "../settings/settings";
+/**
+ * Relative position for elements (hints and additional text) with respect to the RBR.
+ * Specifies how the EBR (Element Bounding Rectangle) aligns with the RBR (Reference Bounding Rectangle).
+ */
+export type RelativePosition = "n" | "ne" | "e" | "se" | "s" | "sw" | "w" | "nw" | "inw" | "ine" | "isw" | "ise" | "o";
+/**
+ * GVE Snapshot Rendition Web Component.
+ * Renders interactive text transformations from snapshot model data.
+ */
+export declare class GveSnapshotRendition extends HTMLElement {
+    private _settings;
+    private _data?;
+    private _versionTag?;
+    private _logger;
+    private _animationEngine?;
+    private _boundsCache;
+    private _spreadingEngine;
+    private _textRenderer?;
+    private _hintRenderer?;
+    private _featureResolver;
+    private _shadow;
+    private _rootSvg?;
+    private _container?;
+    private _toolbar?;
+    private _versionTextArea?;
+    private _detailsArea?;
+    private _versionsListArea?;
+    private _hilites?;
+    private _panZoomInstance?;
+    private _keyboardHandler?;
+    private _baseNodes;
+    private _versionPalette;
+    private _slideshowTimerId;
+    private _currentVersion;
+    private _currentVersionIndex;
+    private _autoForwardEnabled;
+    private _autoForwardTimerId;
+    constructor();
+    /**
+     * Observed attributes for the web component.
+     */
+    static get observedAttributes(): string[];
+    /**
+     * Called when component is added to the DOM.
+     */
+    connectedCallback(): void;
+    /**
+     * Called when component is removed from the DOM.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Called when observed attributes change.
+     */
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    /**
+     * Settings property (bindable).
+     */
+    get settings(): GveRenditionSettings;
+    set settings(value: GveRenditionSettings);
+    /**
+     * Data property (bindable).
+     */
+    get data(): CharChainResult | undefined;
+    set data(value: CharChainResult | undefined);
+    /**
+     * Version tag property (bindable).
+     */
+    get versionTag(): string | undefined;
+    set versionTag(value: string | undefined);
+    /**
+     * Initialize GSAP when available.
+     */
+    private initializeGsap;
+    /**
+     * Process data to prepare for rendering.
+     */
+    private processData;
+    /**
+     * Render the component UI.
+     */
+    private render;
+    /**
+     * Render content (base text only - starts at v0).
+     * Use goToVersionIndex() to navigate to specific versions.
+     */
+    private renderContent;
+    /**
+     * Initialize pan/zoom functionality on the SVG element.
+     * Enables mouse wheel zoom, click-and-drag pan, with configurable limits.
+     */
+    private initializePanZoom;
+    /**
+     * Process operations to render text transformations.
+     * Processes operations in order, rendering hints and additional text.
+     */
+    private processOperations;
+    /**
+     * Process a single operation step.
+     */
+    private processOperation;
+    /**
+     * Internal operation processing (called with pan/zoom disabled).
+     */
+    private processOperationInternal;
+    /**
+     * Get reference nodes for an operation using node IDs from trace features.
+     * Reference nodes are the nodes affected by the operation.
+     *
+     * According to the snapshot model, deleted nodes are not included in subsequent
+     * versions' taggedNodes. To find a deleted node, we must search backwards through
+     * previous versions until we find it.
+     *
+     * @param nodeIds - Array of node IDs from step.refNodeIds (extracted from trace features)
+     * @param inputTag - The input version tag to look for nodes (e.g., "v11")
+     * @returns Array of CharNode objects matching the IDs
+     */
+    private getReferenceNodes;
+    /**
+     * Find a node by ID, searching backwards through versions if needed.
+     * This handles the case where a node was deleted in a previous version but
+     * is still referenced by a later operation (e.g., to add a hint to a deleted node).
+     *
+     * Searches backwards from the specified version to v0. Since v0 is now normalized
+     * and added to taggedNodes during data processing, no special handling is needed.
+     *
+     * @param nodeId - The node ID to find
+     * @param startTag - The version tag to start searching from (e.g., "v11")
+     * @returns The node if found, undefined otherwise
+     */
+    private findNodeById;
+    /**
+     * Get nodes added by a specific operation.
+     * These are nodes with opid feature matching the operation ID.
+     *
+     * @param operationId - The operation ID to match
+     * @param outputTag - The output version tag (e.g., "v3") where the nodes were added
+     * @returns Array of nodes added by this operation
+     */
+    private getAddedNodes;
+    /**
+     * Render hints for an operation.
+     */
+    private renderHints;
+    /**
+     * Navigate to a specific version index (0 = base text, 1+ = after operations).
+     * Uses accumulation model: forward adds elements, backward removes them.
+     */
+    private goToVersionIndex;
+    /**
+     * Update the version text area with the current version's text.
+     * @param versionIndex - The version index (0 = base text)
+     */
+    private updateVersionText;
+    /**
+     * Update the details area with the current version's information.
+     * @param versionIndex - The version index (0 = base text)
+     */
+    private updateDetailsArea;
+    /**
+     * Set up hover listeners on all text elements to update details area.
+     */
+    private setupTextElementHoverListeners;
+    /**
+     * Handle hover over a text element.
+     */
+    private handleTextElementHover;
+    /**
+     * Handle leaving a text element.
+     */
+    private handleTextElementLeave;
+    /**
+     * Navigate forward by processing operations one by one.
+     * Each operation adds hints and/or text that persist for all future versions.
+     */
+    private navigateForward;
+    /**
+     * Navigate backward by removing elements added in later versions.
+     * Reverses operations from current down to target.
+     */
+    private navigateBackward;
+    /**
+     * Remove all elements belonging to a specific version.
+     * Optionally fades them out before removal based on settings.
+     */
+    private removeVersionElements;
+    /**
+     * Extract char offsets from first operation if it's an annotate.
+     */
+    private extractCharOffsets;
+    /**
+     * Zoom in by configured step amount.
+     */
+    zoomIn(): void;
+    /**
+     * Zoom out by configured step amount.
+     */
+    zoomOut(): void;
+    /**
+     * Reset zoom to 100% and center pan.
+     */
+    resetZoom(): void;
+    /**
+     * Set zoom to specific level (1.0 = 100%).
+     */
+    setZoom(zoomLevel: number): void;
+    /**
+     * Get current zoom level.
+     */
+    getZoom(): number;
+    /**
+     * Update toolbar with current zoom level.
+     */
+    private updateToolbarZoom;
+    /**
+     * Handle toolbar navigation actions.
+     */
+    private handleToolbarNavigation;
+    /**
+     * Navigate to previous staged version.
+     */
+    private goToPrevStagedVersion;
+    /**
+     * Navigate to next staged version.
+     */
+    private goToNextStagedVersion;
+    /**
+     * Handle toolbar slideshow actions.
+     */
+    private handleToolbarSlideshow;
+    /**
+     * Handle toolbar display actions.
+     */
+    private handleToolbarDisplay;
+    /**
+     * Fit SVG to view (center and zoom to fit all content).
+     */
+    private fitToView;
+    /**
+     * Download SVG as a file.
+     */
+    private downloadSVG;
+    /**
+     * Start slideshow mode.
+     */
+    private startSlideshow;
+    /**
+     * Stop slideshow mode.
+     */
+    private stopSlideshow;
+    /**
+     * Advance slideshow by one frame.
+     */
+    private slideshowAdvance;
+    /**
+     * Check if the current version belongs to a group and trigger auto-forward if needed.
+     * Auto-forward continues to the next version after a delay, as long as operations
+     * share the same groupId.
+     *
+     * @param versionIndex - The current version index (just navigated to)
+     */
+    private checkAndTriggerAutoForward;
+    /**
+     * Stop any pending auto-forward timer.
+     */
+    private stopAutoForward;
+    /**
+     * Toggle auto-forward on group feature.
+     * @param enabled - Whether to enable auto-forward
+     */
+    setAutoForwardEnabled(enabled: boolean): void;
+    /**
+     * Get current auto-forward enabled state.
+     */
+    getAutoForwardEnabled(): boolean;
+    /**
+     * Setup keyboard shortcuts for navigation and zoom.
+     * Shortcuts:
+     * - ArrowLeft/ArrowRight: Previous/Next version
+     * - Home/End: First/Last version
+     * - 0-9: Jump to version 0-9
+     * - +/-: Zoom in/out
+     */
+    private setupKeyboardShortcuts;
+    /**
+     * Get the SVG element where content should be appended.
+     * When pan/zoom is active, returns the transformed viewport group.
+     * When pan/zoom is inactive, returns the root SVG.
+     *
+     * CRITICAL: svg-pan-zoom wraps content in a <g> element. New elements
+     * must be added to this group, not the root SVG, or they won't transform.
+     */
+    private getSvgContainer;
+    /**
+     * Temporarily disable pan/zoom for rendering operations.
+     * CRITICAL: Disables user input but preserves viewport transform.
+     */
+    private disablePanZoom;
+    /**
+     * Re-enable pan/zoom after rendering operations complete.
+     */
+    private enablePanZoom;
+    /**
+     * Navigate to a specific version by tag.
+     * @param versionTag - Version tag (e.g., "v0", "v1")
+     */
+    private navigateToVersion;
+    /**
+     * Toggle hilites for a specific version.
+     * @param versionTag - Version tag to hilite, or null to clear hilites
+     */
+    private toggleHilites;
+    /**
+     * Get component styles.
+     */
+    private getStyles;
+}

package/dist/core/logger.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Logger utility for diagnostic output.
+ * Logging is controlled by the debug setting in component settings.
+ */
+export declare class Logger {
+    private _enabled;
+    private _prefix;
+    constructor(prefix?: string, enabled?: boolean);
+    /**
+     * Enable or disable logging.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Log an informational message.
+     */
+    info(message: string, ...args: any[]): void;
+    /**
+     * Log a warning message.
+     */
+    warn(message: string, ...args: any[]): void;
+    /**
+     * Log an error message (always logged, regardless of debug setting).
+     */
+    error(message: string, ...args: any[]): void;
+    /**
+     * Log a debug message with detailed context.
+     */
+    debug(category: string, message: string, data?: any): void;
+    /**
+     * Time a block of code execution.
+     */
+    time(label: string): void;
+    /**
+     * End timing a block of code.
+     */
+    timeEnd(label: string): void;
+}