tiny-essentials 1.29.1 → 1.29.2

package/dist/v1/libs/html/loader/formats/TinyImageLoader.d.mts

@@ -0,0 +1,200 @@
+/**
+ * @fileoverview Concrete loader for images. Exposes cache detection, aspect
+ * ratio helpers, full control over the decode step, and advanced animation parsing.
+ */
+import TinyMediaLoader from '../TinyMediaLoader.mjs';
+export type MediaEarlyDecoder = import('../TinyMediaLoader.mjs').MediaEarlyDecoder;
+export type AnimationFrame = {
+    /**
+     * - The Object URL of the single-frame blob.
+     */
+    url: string;
+    /**
+     * - The unique key used in TinyMediaCache.
+     */
+    cacheKey: string;
+};
+export type AnimationScriptStep = {
+    /**
+     * - Duration of the frame in milliseconds.
+     */
+    delay: number;
+};
+export type ImageLoaderOptions = {
+    /**
+     * - The image source URL.
+     */
+    src?: string;
+    /**
+     * - Maximum time in milliseconds before the load is aborted.
+     */
+    timeout?: number;
+    /**
+     * - The CORS mode applied to the image.
+     */
+    crossOrigin?: string | null;
+    /**
+     * - The decoding hint passed to the browser.
+     */
+    decoding?: 'sync' | 'async' | 'auto';
+    /**
+     * - An existing DOM element to adopt.
+     */
+    element?: HTMLImageElement | null;
+    /**
+     * - Whether to decode the dimensions from the response headers using WebCodecs.
+     */
+    earlyDecode?: boolean;
+    /**
+     * - Whether to show the image progressively while streaming (default true).
+     */
+    progressive?: boolean;
+    /**
+     * - Whether an external `src` change triggers a reload.
+     */
+    autoReload?: boolean;
+    /**
+     * - Whether to download the image through fetch for byte progress.
+     */
+    stream?: boolean;
+    /**
+     * - Whether to perform a HEAD request to fetch HTTP headers before downloading.
+     */
+    useHeadRequest?: boolean;
+    /**
+     * - The request body forwarded to the transport (ignored by `GET`/`HEAD`).
+     */
+    body?: BodyInit;
+    /**
+     * - Whether concurrent loads of the same source share a single download (default true).
+     */
+    mirror?: boolean;
+    /**
+     * - An optional shared memory cache.
+     */
+    cache?: import('../utils/TinyMediaCache.mjs').default | null;
+    /**
+     * - How animated images are handled.
+     */
+    animationControl?: 'none' | 'native' | 'script-only' | 'controlled';
+};
+/**
+ * Loads a single image with full lifecycle and animation control.
+ * @extends {TinyMediaLoader<HTMLImageElement>}
+ */
+declare class TinyImageLoader extends TinyMediaLoader<HTMLImageElement> {
+    #private;
+    /**
+     * Retrieves the tag name used to create the underlying element.
+     * @returns {string} The uppercase tag name, always `'IMG'`.
+     */
+    static get tagName(): string;
+    /**
+     * Creates a new image loader and validates the provided options.
+     * @param {ImageLoaderOptions} [options] - The loader configuration.
+     * @throws {TypeError} If `crossOrigin` is not a string or null.
+     * @throws {TypeError} If `decoding` is not a string.
+     */
+    constructor(options?: ImageLoaderOptions);
+    /**
+     * The underlying `<img>` element.
+     * @returns {HTMLImageElement|null} The current image element, or `null` before the load starts.
+     */
+    get image(): HTMLImageElement | null;
+    /**
+     * Indicates whether the image is downloaded through fetch for byte-level progress.
+     * @returns {boolean} `true` when streaming is enabled, otherwise `false`.
+     */
+    get stream(): boolean;
+    /**
+     * The intrinsic width of the image in pixels.
+     * @returns {number} The intrinsic width in pixels.
+     */
+    get naturalWidth(): number;
+    /**
+     * The intrinsic height of the image in pixels.
+     * @returns {number} The intrinsic height in pixels.
+     */
+    get naturalHeight(): number;
+    /**
+     * The aspect ratio of the image (width / height).
+     * @returns {number} The width divided by the height, or 0 when unknown.
+     */
+    get aspectRatio(): number;
+    /**
+     * Freezes the animation. In native mode, falls back to the static 1st frame blob.
+     * @param {number|null} [frameIndex] - Frame index to freeze on (controlled mode only).
+     */
+    freeze(frameIndex?: number | null): void;
+    /**
+     * Unfreezes and resumes the animation.
+     */
+    unfreeze(): void;
+    /**
+     * Plays the animation (controlled mode only).
+     */
+    play(): void;
+    /**
+     * Pauses the animation (controlled mode only).
+     */
+    pause(): void;
+    /**
+     * Gets or sets the playback speed modifier.
+     * @type {number}
+     */
+    get playbackRate(): number;
+    set playbackRate(value: number);
+    /**
+     * Gets a deep copy of the current animation script or replaces it to modify behavior.
+     * @type {AnimationScriptStep[]}
+     */
+    get animationScript(): AnimationScriptStep[];
+    /**
+     * Replaces the animation script.
+     * @param {AnimationScriptStep[]} script - The new script.
+     * @throws {TypeError} If `script` is not an array of `{ delay: number }`.
+     * @throws {Error} If the loader is not in controlled mode.
+     */
+    set animationScript(script: AnimationScriptStep[]);
+    /**
+     * Resolves the target element, wires the load listeners and decodes the image.
+     * @protected
+     * @returns {Promise<void>} A promise that resolves once the image is decoded and ready.
+     */
+    protected _startLoad(): Promise<void>;
+    /**
+     * Builds the metadata descriptor for the loaded image.
+     * @protected
+     * @returns {import('../TinyMediaLoader.mjs').MediaMetadataDetails} The image metadata details.
+     */
+    protected _getMetadataDetails(): import('../TinyMediaLoader.mjs').MediaMetadataDetails;
+    /**
+     * Aborts the fetch gracefully allowing a retry process to spin up safely on the same element instance without
+     * triggering stale asynchronous cache responses.
+     * @protected
+     * @returns {void}
+     */
+    protected _abort(): void;
+    /**
+     * Releases all acquired animation frames from the cache or revokes their
+     * object URLs. It also stops the playback loop, so a reload never leaves a
+     * timer pointing at a frame that no longer exists.
+     * @protected
+     * @returns {void}
+     */
+    protected _releaseAnimationFrames(): void;
+    /**
+     * Detaches the load handlers, revokes the object URL and clears the source of the image element.
+     * @protected
+     * @returns {void} This method does not return a value.
+     */
+    protected _cleanup(): void;
+    /**
+     * Creates the `<img>` element used by the loader.
+     * @protected
+     * @returns {HTMLImageElement} A new, detached image element.
+     */
+    protected _createElement(): HTMLImageElement;
+}
+export default TinyImageLoader;
+//# sourceMappingURL=TinyImageLoader.d.mts.map

package/dist/v1/libs/html/loader/formats/TinyImageLoader.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyImageLoader.d.mts","sourceRoot":"","sources":["../../../../../../src/v1/libs/html/loader/formats/TinyImageLoader.mjs"],"names":[],"mappings":"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"}