@yoamigo.com/core 0.1.10 → 0.1.12

package/dist/index.d.ts

@@ -106,4 +106,393 @@ interface SafeHtmlProps {
  */
 declare function SafeHtml({ content, className, mode }: SafeHtmlProps): react_jsx_runtime.JSX.Element;
 
-export { type ContentStoreContextType, type ContentStoreMode, ContentStoreProvider, type ImageFieldValue, SafeHtml, type SafeHtmlProps, YaImage, type YaImageProps, YaText, type YaTextProps, serializeImageValue, useContentStore };
+/**
+ * Animation state for a single field
+ */
+interface AnimationState {
+    fieldId: string;
+    status: 'pending' | 'animating' | 'complete';
+    startTime: number;
+    duration: number;
+    onComplete?: () => void;
+}
+/**
+ * Configuration for queuing an animation
+ */
+interface AnimationConfig {
+    duration: number;
+    onStart?: () => void;
+    onComplete?: () => void;
+}
+/**
+ * AI Edit Context value
+ */
+interface AIEditContextValue {
+    /**
+     * Queue an animation for a field.
+     * If the field is already animating, the existing animation is cancelled.
+     */
+    queueAnimation: (fieldId: string, config: AnimationConfig) => void;
+    /**
+     * Cancel an animation for a field.
+     */
+    cancelAnimation: (fieldId: string) => void;
+    /**
+     * Check if a field is currently animating.
+     */
+    isAnimating: (fieldId: string) => boolean;
+    /**
+     * Get the animation state for a field.
+     */
+    getAnimationState: (fieldId: string) => AnimationState | undefined;
+    /**
+     * Register a listener for animation state changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe: (fieldId: string, listener: () => void) => () => void;
+    /**
+     * Mark an animation as complete.
+     */
+    completeAnimation: (fieldId: string) => void;
+}
+/**
+ * Hook to access the AI Edit context.
+ * Must be used within an AIEditProvider.
+ */
+declare function useAIEditContext(): AIEditContextValue;
+/**
+ * Optional hook that returns null if not in provider.
+ * Useful for components that work both inside and outside the provider.
+ */
+declare function useAIEditContextOptional(): AIEditContextValue | null;
+interface AIEditProviderProps {
+    children: ReactNode;
+    /**
+     * Stagger delay between multiple simultaneous animations (ms)
+     * Default: 100ms
+     */
+    staggerDelay?: number;
+}
+/**
+ * AI Edit Provider
+ *
+ * Wrap your app with this to enable AI edit animations.
+ * Should be placed above ContentStoreProvider.
+ */
+declare function AIEditProvider({ children, staggerDelay }: AIEditProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Text Diffing Utilities for AI Edit Animations
+ *
+ * Computes the difference between two text strings to enable
+ * character-by-character typing animations.
+ */
+interface TextDiff {
+    /** Type of diff - 'simple' for plain text, 'complex' for HTML */
+    type: 'simple' | 'complex';
+    /** Characters/content to remove */
+    deletions: string;
+    /** Characters/content to add */
+    additions: string;
+    /** Unchanged text at the start */
+    commonPrefix: string;
+    /** Unchanged text at the end */
+    commonSuffix: string;
+    /** Original old text */
+    oldText: string;
+    /** Original new text */
+    newText: string;
+}
+/**
+ * Check if a string contains HTML tags
+ */
+declare function containsHtml(text: string): boolean;
+/**
+ * Strip HTML tags from a string, preserving text content
+ */
+declare function stripHtml(html: string): string;
+/**
+ * Compute the difference between two text strings.
+ *
+ * For simple text (no HTML), returns character-level diff.
+ * For HTML content, returns the full old/new for crossfade animation.
+ *
+ * @example
+ * ```ts
+ * const diff = computeTextDiff("Hello World", "Hello Universe")
+ * // diff.commonPrefix = "Hello "
+ * // diff.deletions = "World"
+ * // diff.additions = "Universe"
+ * // diff.commonSuffix = ""
+ * ```
+ */
+declare function computeTextDiff(oldText: string, newText: string): TextDiff;
+/**
+ * Build an intermediate string during a typing animation.
+ *
+ * @param diff - The computed text diff
+ * @param deleteProgress - Progress through deletion (0-1)
+ * @param typeProgress - Progress through typing (0-1)
+ * @returns The intermediate string to display
+ */
+declare function buildIntermediateText(diff: TextDiff, deleteProgress: number, typeProgress: number): string;
+/**
+ * Calculate animation timings based on text length.
+ *
+ * Uses adaptive timing:
+ * - Base: 50ms per character
+ * - Scales down for longer texts to stay under maxDuration
+ *
+ * @param diff - The computed text diff
+ * @param options - Timing options
+ * @returns Delete duration and type duration in ms
+ */
+declare function calculateAnimationTiming(diff: TextDiff, options?: {
+    charDelay?: number;
+    maxDuration?: number;
+}): {
+    deleteDuration: number;
+    typeDuration: number;
+};
+
+/**
+ * Animation Strategies for AI Edit Visualizations
+ *
+ * Pluggable strategies that define how different content types animate.
+ * Each strategy implements the AnimationStrategy interface.
+ */
+
+/**
+ * Generic animation strategy interface.
+ * Implement this for custom content types.
+ */
+interface AnimationStrategy<T> {
+    /** Strategy name for debugging */
+    name: string;
+    /**
+     * Check if this strategy can animate between two values.
+     * Return false if the change is too complex or values are identical.
+     */
+    canAnimate: (oldValue: T, newValue: T) => boolean;
+    /**
+     * Compute animation metadata from old and new values.
+     * This is called once at animation start.
+     */
+    prepare: (oldValue: T, newValue: T) => AnimationMetadata<T>;
+    /**
+     * Interpolate between old and new value at a given progress.
+     *
+     * @param metadata - Precomputed animation metadata
+     * @param progress - Animation progress from 0 to 1
+     * @returns The interpolated value to display
+     */
+    interpolate: (metadata: AnimationMetadata<T>, progress: number) => T;
+}
+/**
+ * Metadata computed once at animation start.
+ * Strategies can extend this with their own data.
+ */
+interface AnimationMetadata<T> {
+    oldValue: T;
+    newValue: T;
+    /** Total animation duration in ms */
+    duration: number;
+    /** Strategy-specific data */
+    data?: unknown;
+}
+/**
+ * Text animation metadata with diff information
+ */
+interface TextAnimationMetadata extends AnimationMetadata<string> {
+    data: {
+        diff: TextDiff;
+        deleteDuration: number;
+        typeDuration: number;
+    };
+}
+/**
+ * Text Typing Strategy
+ *
+ * Animates text changes character-by-character:
+ * 1. Delete phase: Remove old characters one by one
+ * 2. Type phase: Add new characters one by one
+ *
+ * For HTML content, falls back to quick crossfade.
+ */
+declare const textTypingStrategy: AnimationStrategy<string>;
+/**
+ * Image value type for image animations
+ */
+interface ImageValue {
+    src: string;
+    alt?: string;
+    objectFit?: string;
+    objectPosition?: string;
+    focalPoint?: {
+        x: number;
+        y: number;
+    };
+}
+declare const imageCrossfadeStrategy: AnimationStrategy<ImageValue>;
+/**
+ * Link value type for link animations
+ */
+interface LinkValue {
+    text: string;
+    href: string;
+}
+/**
+ * Link Transition Strategy
+ *
+ * Animates link changes with text morphing and href highlight.
+ */
+declare const linkTransitionStrategy: AnimationStrategy<LinkValue>;
+/**
+ * Get cursor position for text typing animation.
+ * Returns null if no cursor should be shown.
+ */
+declare function getTextCursorPosition(metadata: TextAnimationMetadata, progress: number): number | null;
+
+/**
+ * useAIEditAnimation - Generic Animation Hook
+ *
+ * Component-agnostic hook that any editable component can use
+ * to animate content changes with AI edit visualization.
+ */
+
+/**
+ * Animation phase
+ */
+type AnimationPhase = 'idle' | 'animating' | 'complete';
+/**
+ * Result returned by useAIEditAnimation
+ */
+interface AnimationResult<T> {
+    /** Current value to render (may be mid-animation) */
+    displayValue: T;
+    /** True if animation is in progress */
+    isAnimating: boolean;
+    /** Current animation phase */
+    phase: AnimationPhase;
+    /** Animation progress from 0 to 1 */
+    progress: number;
+    /** Cancel the current animation */
+    cancel: () => void;
+    /** Props to spread on the wrapper element */
+    wrapperProps: {
+        className: string;
+        'data-ai-editing': boolean;
+    };
+}
+/**
+ * Options for useAIEditAnimation
+ */
+interface AnimationOptions<T> {
+    /** Whether animation is enabled (default: true) */
+    enabled?: boolean;
+    /** Animation strategy to use */
+    strategy: AnimationStrategy<T>;
+    /** Maximum animation duration in ms (default: 2000) */
+    maxDuration?: number;
+    /** Callback when animation starts */
+    onStart?: () => void;
+    /** Callback when animation completes */
+    onComplete?: () => void;
+}
+/**
+ * Generic animation hook for AI edit visualizations.
+ *
+ * @param fieldId - Unique identifier for this field
+ * @param value - Current value from content store
+ * @param options - Animation options including strategy
+ * @returns Animation result with display value and state
+ *
+ * @example
+ * ```tsx
+ * const { displayValue, isAnimating, wrapperProps } = useAIEditAnimation(
+ *   'hero.title',
+ *   content,
+ *   { strategy: textTypingStrategy }
+ * )
+ *
+ * return (
+ *   <div {...wrapperProps}>
+ *     {displayValue}
+ *   </div>
+ * )
+ * ```
+ */
+declare function useAIEditAnimation<T>(fieldId: string, value: T, options: AnimationOptions<T>): AnimationResult<T>;
+
+/**
+ * useAnimatedText - Text-specific Animation Hook
+ *
+ * Convenience wrapper around useAIEditAnimation for text content.
+ * Provides typing animation with cursor position tracking.
+ */
+
+/**
+ * Result returned by useAnimatedText
+ */
+interface AnimatedTextResult {
+    /** Current text content to display (may be mid-animation) */
+    displayContent: string;
+    /** True if animation is in progress */
+    isAnimating: boolean;
+    /** Current animation phase */
+    phase: AnimationPhase;
+    /** Animation progress from 0 to 1 */
+    progress: number;
+    /** Cursor position in characters, or null if no cursor */
+    cursorPosition: number | null;
+    /** CSS class name for wrapper (ya-ai-editing, ya-ai-complete, or empty) */
+    wrapperClassName: string;
+    /** Cancel the current animation */
+    cancel: () => void;
+}
+/**
+ * Options for useAnimatedText
+ */
+interface AnimatedTextOptions {
+    /** Whether animation is enabled (default: true) */
+    enabled?: boolean;
+    /** Delay per character in ms (default: 50) */
+    charDelay?: number;
+    /** Maximum animation duration in ms (default: 2000) */
+    maxDuration?: number;
+    /** Callback when animation starts */
+    onStart?: () => void;
+    /** Callback when animation completes */
+    onComplete?: () => void;
+}
+/**
+ * Text-specific animation hook for AI edit visualizations.
+ *
+ * Provides character-by-character typing animation with cursor tracking.
+ *
+ * @param fieldId - Unique identifier for this field
+ * @param content - Current text content from content store
+ * @param options - Animation options
+ * @returns Animation result with display content, cursor position, and state
+ *
+ * @example
+ * ```tsx
+ * const { displayContent, isAnimating, cursorPosition, wrapperClassName } = useAnimatedText(
+ *   'hero.title',
+ *   content,
+ *   { enabled: mode === 'inline-edit' && !isEditing }
+ * )
+ *
+ * return (
+ *   <div className={wrapperClassName}>
+ *     <SafeHtml content={displayContent} />
+ *     {isAnimating && cursorPosition !== null && (
+ *       <span className="ya-typing-cursor" />
+ *     )}
+ *   </div>
+ * )
+ * ```
+ */
+declare function useAnimatedText(fieldId: string, content: string, options?: AnimatedTextOptions): AnimatedTextResult;
+
+export { type AIEditContextValue, AIEditProvider, type AnimatedTextOptions, type AnimatedTextResult, type AnimationConfig, type AnimationMetadata, type AnimationOptions, type AnimationPhase, type AnimationResult, type AnimationState, type AnimationStrategy, type ContentStoreContextType, type ContentStoreMode, ContentStoreProvider, type ImageFieldValue, type ImageValue, type LinkValue, SafeHtml, type SafeHtmlProps, type TextAnimationMetadata, type TextDiff, YaImage, type YaImageProps, YaText, type YaTextProps, buildIntermediateText, calculateAnimationTiming, computeTextDiff, containsHtml, getTextCursorPosition, imageCrossfadeStrategy, linkTransitionStrategy, serializeImageValue, stripHtml, textTypingStrategy, useAIEditAnimation, useAIEditContext, useAIEditContextOptional, useAnimatedText, useContentStore };