@muraldevkit/ui-toolkit 4.61.1 → 4.62.0-dev-3JXS.1

package/dist/components/image/MrlAnimatedImage/MrlAnimatedImage.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import { MrlAnimatedImageProps } from './constants';
+/**
+ * MrlAnimatedImage provides an accessible image component with support
+ * for animated images (GIFs), reduced motion preferences, and proper ARIA attributes.
+ *
+ * Features:
+ * - Automatic `prefers-reduced-motion` detection
+ * - Play/pause controls for animated images
+ * - Live region announcements for state changes
+ * - Proper decorative image handling
+ * - Error state with accessible fallback
+ *
+ * @param props - component props
+ * @returns a MrlAnimatedImage React component.
+ */
+export declare const MrlAnimatedImage: React.ForwardRefExoticComponent<Omit<MrlAnimatedImageProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/dist/components/image/MrlAnimatedImage/constants.d.ts

@@ -0,0 +1,78 @@
+import * as React from 'react';
+export type ImageMotion = 'static' | 'animated';
+export interface MrlAnimatedImageProps extends Omit<React.ComponentPropsWithRef<'figure'>, 'children' | 'onError'> {
+    /**
+     * Image source URL (string path).
+     * Accepts absolute URLs (e.g., "https://example.com/image.jpg") or
+     * relative URLs (e.g., "/images/photo.jpg" or "../assets/image.png").
+     * Works with images from any domain on the internet.
+     */
+    src: string;
+    /**
+     * Alternative text for the image. Required unless decorative={true}
+     */
+    alt?: string;
+    /**
+     * Whether the image is decorative (no alt text needed)
+     * @default false
+     */
+    decorative?: boolean;
+    /**
+     * Image motion type
+     * @default 'static'
+     */
+    motion?: ImageMotion;
+    /**
+     * Static image source for animated images (used when paused).
+     * Accepts absolute or relative URL strings, same format as `src`.
+     * Required when motion="animated"
+     */
+    staticSrc?: string;
+    /**
+     * Caption text to display below the image
+     */
+    caption?: string;
+    /**
+     * Image width (for layout stability)
+     */
+    width?: number | string;
+    /**
+     * Image height (for layout stability)
+     */
+    height?: number | string;
+    /**
+     * Aspect ratio (for layout stability, e.g., "16/9")
+     */
+    aspectRatio?: string;
+    /**
+     * Whether animation should autoplay
+     * @default false
+     */
+    autoplay?: boolean;
+    /**
+     * Whether animation is essential (bypasses reduced motion)
+     * @default false
+     */
+    motionEssential?: boolean;
+    /**
+     * Custom CSS class name
+     */
+    className?: string;
+    /**
+     * A string value used for data-qa attribute
+     */
+    ['data-qa']?: string;
+    /**
+     * Loading behavior
+     * @default 'lazy'
+     */
+    loading?: 'lazy' | 'eager';
+    /**
+     * Callback when image fails to load
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Callback when image loads successfully
+     */
+    onLoad?: () => void;
+}

package/dist/components/image/MrlAnimatedImage/hooks/useAnimationControl.d.ts

@@ -0,0 +1,22 @@
+import { ImageMotion } from '../constants';
+interface UseAnimationControlOptions {
+    autoplay?: boolean;
+    motion: ImageMotion;
+    motionEssential?: boolean;
+}
+interface UseAnimationControlReturn {
+    isPaused: boolean;
+    isPlaying: boolean;
+    shouldDisplayStatic: boolean;
+    toggleAnimation: () => void;
+}
+/**
+ * Hook to manage animation control state including play/pause and reduced motion integration
+ * @param options - Configuration options
+ * @param options.autoplay - Whether animation should autoplay
+ * @param options.motion - Image motion type
+ * @param options.motionEssential - Whether animation is essential (bypasses reduced motion)
+ * @returns Animation control state and functions
+ */
+export declare function useAnimationControl({ autoplay, motion, motionEssential }: UseAnimationControlOptions): UseAnimationControlReturn;
+export {};

package/dist/components/image/MrlAnimatedImage/index.d.ts

@@ -0,0 +1,2 @@
+export { MrlAnimatedImage } from './MrlAnimatedImage';
+export type { MrlAnimatedImageProps, ImageMotion } from './constants';

package/dist/components/image/MrlAnimatedImage/utils.d.ts

@@ -0,0 +1,36 @@
+import { ImageMotion } from './constants';
+/**
+ * Determines the image source to display based on animation state
+ * @param params - Configuration parameters
+ * @param params.motion - Image motion type
+ * @param params.shouldDisplayStatic - Whether to display static image
+ * @param params.src - Primary image source
+ * @param params.staticSrc - Static fallback image source
+ * @returns The image source URL to display
+ */
+export declare function getDisplayedSrc(params: {
+    motion: ImageMotion;
+    shouldDisplayStatic: boolean;
+    src: string;
+    staticSrc?: string;
+}): string;
+/**
+ * Resolves alt text based on decorative flag
+ * @param decorative - Whether the image is decorative
+ * @param alt - Alternative text for the image
+ * @returns Resolved alt text (empty string if decorative)
+ */
+export declare function getResolvedAltText(decorative: boolean, alt?: string): string;
+/**
+ * Generates accessible error message for screen readers
+ * @param decorative - Whether the image is decorative
+ * @param alt - Alternative text for the image
+ * @returns Error message for screen readers
+ */
+export declare function getErrorMessage(decorative: boolean, alt?: string): string;
+/**
+ * Generates play/pause announcement text
+ * @param isPaused - Whether animation is paused
+ * @returns Announcement text for screen readers
+ */
+export declare function getPlayPauseAnnouncement(isPaused: boolean): string;

package/dist/components/image/index.d.ts

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

package/dist/components/index.d.ts

@@ -32,3 +32,4 @@ export * from './rovingTabindex';
 export * from './toolbar';
 export * from './filter';
 export * from './breadcrumb';
+export * from './image';

package/dist/hooks/index.d.ts

@@ -2,3 +2,4 @@ export * from './useCoordinate';
 export * from './useBreakpoint';
 export * from './useElementDimensions';
 export * from './useScrollbarInfo';
+export * from './useReducedMotion';

package/dist/hooks/useImagePreload/index.d.ts

@@ -0,0 +1,26 @@
+interface UseImagePreloadOptions {
+    /** Image source URL to preload */
+    src: string;
+    /** Whether preloading is enabled */
+    enabled?: boolean;
+}
+interface UseImagePreloadReturn {
+    /** Natural dimensions of the preloaded image */
+    dimensions: {
+        height: number | null;
+        width: number | null;
+    };
+    /** Whether the preload failed */
+    hasError: boolean;
+    /** Whether the image is currently loading */
+    isLoading: boolean;
+}
+/**
+ * Hook to preload an image and capture its natural dimensions.
+ * Useful for preventing layout shift when images load.
+ *
+ * @param options - Configuration options
+ * @returns Preload state including dimensions, loading state, and error state
+ */
+export declare function useImagePreload({ src, enabled }: UseImagePreloadOptions): UseImagePreloadReturn;
+export {};

package/dist/hooks/useReducedMotion/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Hook to detect user's reduced motion preference.
+ * Automatically updates when system preference changes.
+ *
+ * @returns {boolean} - true if user prefers reduced motion
+ */
+export declare function useReducedMotion(): boolean;