@puzzle-ui/ui 0.0.0-stage → 0.2.0

package/dist/components/data-display/image/image.types.d.cts

@@ -0,0 +1,154 @@
+import { CSSProperties, ComponentPropsWithRef, ElementType, ReactNode, Ref } from "react";
+/**
+ * Supports regular URLs and static image imports.
+ *
+ * The object shape is compatible with Next.js StaticImageData.
+ */
+type ImageSourceData = {
+  src: string;
+  width: number;
+  height: number;
+  blurDataURL?: string;
+  blurWidth?: number;
+  blurHeight?: number;
+};
+type ImageSource = string | ImageSourceData;
+type ImageFit = NonNullable<CSSProperties["objectFit"]>;
+type ImageRadius = "none" | "sm" | "md" | "lg" | "xl" | "full" | NonNullable<CSSProperties["borderRadius"]>;
+type ImagePlaceholder = "empty" | "blur";
+/**
+ * Additional responsive image sources for the picture element.
+ */
+type ImageSourceSet = {
+  srcSet: string;
+  media?: string;
+  type?: string;
+  sizes?: string;
+};
+type ImageProps = Omit<ComponentPropsWithRef<"img">, "src" | "alt" | "width" | "height" | "className" | "style" | "ref"> & {
+  /**
+   * Image URL or static image import.
+   *
+   * Can be omitted when fallbackSrc or fallback is provided.
+   */
+  src?: ImageSource | null;
+  /**
+   * Alternative text.
+   *
+   * Use an empty string for decorative images.
+   */
+  alt: string;
+  /**
+   * Intrinsic image width in pixels.
+   *
+   * Automatically inferred from static image imports.
+   */
+  width?: number;
+  /**
+   * Intrinsic image height in pixels.
+   *
+   * Automatically inferred from static image imports.
+   */
+  height?: number;
+  /**
+   * Image rendering mode.
+   */
+  fit?: ImageFit;
+  /**
+   * Image alignment within its container.
+   */
+  position?: CSSProperties["objectPosition"];
+  /**
+   * Container aspect ratio.
+   *
+   * When provided, the image fills the resulting container.
+   */
+  aspectRatio?: CSSProperties["aspectRatio"];
+  /**
+   * Makes the image fill its parent container.
+   *
+   * The parent must have a defined size.
+   */
+  fill?: boolean;
+  /**
+   * Border radius of the image container.
+   */
+  radius?: ImageRadius;
+  /**
+   * Alternative image source used when the primary source fails.
+   */
+  fallbackSrc?: ImageSource | null;
+  /**
+   * Custom content displayed when no image can be rendered.
+   */
+  fallback?: ReactNode;
+  /**
+   * Custom loading content displayed above the image.
+   */
+  loadingPlaceholder?: ReactNode;
+  /**
+   * Loading placeholder strategy.
+   *
+   * Blur requires a blurDataURL, either explicitly provided
+   * or included in a static image import.
+   */
+  placeholder?: ImagePlaceholder;
+  /**
+   * Small preview image used by the blur placeholder.
+   */
+  blurDataURL?: string;
+  /**
+   * Additional sources rendered inside a picture element.
+   */
+  sources?: ImageSourceSet[];
+  /**
+   * Framework-specific image component.
+   *
+   * Overrides Theme.components.image for this instance.
+   */
+  component?: ElementType;
+  /**
+   * Additional props forwarded to the configured image component.
+   *
+   * Useful for framework-specific options such as custom loaders.
+   */
+  componentProps?: Record<string, unknown>;
+  /**
+   * Next.js image optimization quality.
+   *
+   * Forwarded to custom image components.
+   */
+  quality?: number;
+  /**
+   * Whether the image should be preloaded.
+   *
+   * Uses React DOM preload for native images and is forwarded
+   * to configured framework components.
+   */
+  preload?: boolean;
+  /**
+   * Disables image optimization in compatible image components.
+   */
+  unoptimized?: boolean;
+  /**
+   * Class applied to the actual image element.
+   */
+  className?: string;
+  /**
+   * Styles applied to the actual image element.
+   */
+  style?: CSSProperties;
+  /**
+   * Class applied to the outer container.
+   */
+  containerClassName?: string;
+  /**
+   * Styles applied to the outer container.
+   */
+  containerStyle?: CSSProperties;
+  /**
+   * Ref to the underlying image element.
+   */
+  ref?: Ref<HTMLImageElement>;
+};
+export type { ImageFit, ImagePlaceholder, ImageProps, ImageRadius, ImageSource, ImageSourceData, ImageSourceSet };

package/dist/components/data-display/image/image.types.d.ts

@@ -0,0 +1,154 @@
+import { CSSProperties, ComponentPropsWithRef, ElementType, ReactNode, Ref } from "react";
+/**
+ * Supports regular URLs and static image imports.
+ *
+ * The object shape is compatible with Next.js StaticImageData.
+ */
+type ImageSourceData = {
+  src: string;
+  width: number;
+  height: number;
+  blurDataURL?: string;
+  blurWidth?: number;
+  blurHeight?: number;
+};
+type ImageSource = string | ImageSourceData;
+type ImageFit = NonNullable<CSSProperties["objectFit"]>;
+type ImageRadius = "none" | "sm" | "md" | "lg" | "xl" | "full" | NonNullable<CSSProperties["borderRadius"]>;
+type ImagePlaceholder = "empty" | "blur";
+/**
+ * Additional responsive image sources for the picture element.
+ */
+type ImageSourceSet = {
+  srcSet: string;
+  media?: string;
+  type?: string;
+  sizes?: string;
+};
+type ImageProps = Omit<ComponentPropsWithRef<"img">, "src" | "alt" | "width" | "height" | "className" | "style" | "ref"> & {
+  /**
+   * Image URL or static image import.
+   *
+   * Can be omitted when fallbackSrc or fallback is provided.
+   */
+  src?: ImageSource | null;
+  /**
+   * Alternative text.
+   *
+   * Use an empty string for decorative images.
+   */
+  alt: string;
+  /**
+   * Intrinsic image width in pixels.
+   *
+   * Automatically inferred from static image imports.
+   */
+  width?: number;
+  /**
+   * Intrinsic image height in pixels.
+   *
+   * Automatically inferred from static image imports.
+   */
+  height?: number;
+  /**
+   * Image rendering mode.
+   */
+  fit?: ImageFit;
+  /**
+   * Image alignment within its container.
+   */
+  position?: CSSProperties["objectPosition"];
+  /**
+   * Container aspect ratio.
+   *
+   * When provided, the image fills the resulting container.
+   */
+  aspectRatio?: CSSProperties["aspectRatio"];
+  /**
+   * Makes the image fill its parent container.
+   *
+   * The parent must have a defined size.
+   */
+  fill?: boolean;
+  /**
+   * Border radius of the image container.
+   */
+  radius?: ImageRadius;
+  /**
+   * Alternative image source used when the primary source fails.
+   */
+  fallbackSrc?: ImageSource | null;
+  /**
+   * Custom content displayed when no image can be rendered.
+   */
+  fallback?: ReactNode;
+  /**
+   * Custom loading content displayed above the image.
+   */
+  loadingPlaceholder?: ReactNode;
+  /**
+   * Loading placeholder strategy.
+   *
+   * Blur requires a blurDataURL, either explicitly provided
+   * or included in a static image import.
+   */
+  placeholder?: ImagePlaceholder;
+  /**
+   * Small preview image used by the blur placeholder.
+   */
+  blurDataURL?: string;
+  /**
+   * Additional sources rendered inside a picture element.
+   */
+  sources?: ImageSourceSet[];
+  /**
+   * Framework-specific image component.
+   *
+   * Overrides Theme.components.image for this instance.
+   */
+  component?: ElementType;
+  /**
+   * Additional props forwarded to the configured image component.
+   *
+   * Useful for framework-specific options such as custom loaders.
+   */
+  componentProps?: Record<string, unknown>;
+  /**
+   * Next.js image optimization quality.
+   *
+   * Forwarded to custom image components.
+   */
+  quality?: number;
+  /**
+   * Whether the image should be preloaded.
+   *
+   * Uses React DOM preload for native images and is forwarded
+   * to configured framework components.
+   */
+  preload?: boolean;
+  /**
+   * Disables image optimization in compatible image components.
+   */
+  unoptimized?: boolean;
+  /**
+   * Class applied to the actual image element.
+   */
+  className?: string;
+  /**
+   * Styles applied to the actual image element.
+   */
+  style?: CSSProperties;
+  /**
+   * Class applied to the outer container.
+   */
+  containerClassName?: string;
+  /**
+   * Styles applied to the outer container.
+   */
+  containerStyle?: CSSProperties;
+  /**
+   * Ref to the underlying image element.
+   */
+  ref?: Ref<HTMLImageElement>;
+};
+export type { ImageFit, ImagePlaceholder, ImageProps, ImageRadius, ImageSource, ImageSourceData, ImageSourceSet };

package/dist/components/data-display/image/image.utils.cjs

@@ -0,0 +1,55 @@
+// src/components/data-display/image/image.utils.ts
+/**
+* Checks whether an image source contains a usable URL.
+*/
+const hasImageSource = (source) => {
+	if (typeof source === "string") return source.trim().length > 0;
+	return typeof source?.src === "string" && source.src.length > 0;
+};
+/**
+* Resolves a source to a regular URL.
+*
+* Static image objects are converted to their `src` property.
+*/
+const getImageSourceUrl = (source) => {
+	if (!hasImageSource(source)) return;
+	return typeof source === "string" ? source : source.src;
+};
+/**
+* Retrieves intrinsic dimensions from static image imports.
+*/
+const getImageDimensions = (source) => {
+	if (typeof source !== "object" || source === null) return;
+	return {
+		width: source.width,
+		height: source.height
+	};
+};
+/**
+* Resolves an explicitly provided or statically imported blur image.
+*/
+const getImageBlurDataURL = (source) => {
+	if (typeof source !== "object" || source === null) return;
+	return source.blurDataURL;
+};
+/**
+* Resolves semantic radius values to Puzzle theme tokens.
+*/
+const resolveImageRadius = (radius) => {
+	if (radius === void 0) return;
+	return {
+		none: "0",
+		sm: "var(--puzzle-radius-sm, 0.25rem)",
+		md: "var(--puzzle-radius-md, 0.5rem)",
+		lg: "var(--puzzle-radius-lg, 0.75rem)",
+		xl: "var(--puzzle-radius-xl, 1rem)",
+		full: "var(--puzzle-radius-full, 9999px)"
+	}[radius] ?? radius;
+};
+exports.getImageBlurDataURL = getImageBlurDataURL;
+exports.getImageDimensions = getImageDimensions;
+exports.getImageSourceUrl = getImageSourceUrl;
+exports.hasImageSource = hasImageSource;
+exports.resolveImageRadius = resolveImageRadius;
+
+//# sourceMappingURL=image.utils.cjs.map

package/dist/components/data-display/image/image.utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.utils.cjs","names":[],"sources":["../../../../src/components/data-display/image/image.utils.ts"],"sourcesContent":["import type { CSSProperties } from \"react\";\nimport type { ImageRadius, ImageSource } from \"./image.types\";\n\n/**\n * Checks whether an image source contains a usable URL.\n */\nconst hasImageSource = (\n  source: ImageSource | null | undefined,\n): source is ImageSource => {\n  if (typeof source === \"string\") {\n    return source.trim().length > 0;\n  }\n\n  return typeof source?.src === \"string\" && source.src.length > 0;\n};\n\n/**\n * Resolves a source to a regular URL.\n *\n * Static image objects are converted to their `src` property.\n */\nconst getImageSourceUrl = (\n  source: ImageSource | null | undefined,\n): string | undefined => {\n  if (!hasImageSource(source)) {\n    return undefined;\n  }\n\n  return typeof source === \"string\" ? source : source.src;\n};\n\n/**\n * Retrieves intrinsic dimensions from static image imports.\n */\nconst getImageDimensions = (source: ImageSource | null | undefined) => {\n  if (typeof source !== \"object\" || source === null) {\n    return undefined;\n  }\n\n  return {\n    width: source.width,\n    height: source.height,\n  };\n};\n\n/**\n * Resolves an explicitly provided or statically imported blur image.\n */\nconst getImageBlurDataURL = (\n  source: ImageSource | null | undefined,\n): string | undefined => {\n  if (typeof source !== \"object\" || source === null) {\n    return undefined;\n  }\n\n  return source.blurDataURL;\n};\n\n/**\n * Resolves semantic radius values to Puzzle theme tokens.\n */\nconst resolveImageRadius = (\n  radius?: ImageRadius,\n): CSSProperties[\"borderRadius\"] => {\n  if (radius === undefined) {\n    return undefined;\n  }\n\n  const radiusTokens: Record<string, string> = {\n    none: \"0\",\n    sm: \"var(--puzzle-radius-sm, 0.25rem)\",\n    md: \"var(--puzzle-radius-md, 0.5rem)\",\n    lg: \"var(--puzzle-radius-lg, 0.75rem)\",\n    xl: \"var(--puzzle-radius-xl, 1rem)\",\n    full: \"var(--puzzle-radius-full, 9999px)\",\n  };\n\n  return radiusTokens[radius] ?? radius;\n};\n\nexport {\n  hasImageSource,\n  getImageSourceUrl,\n  getImageDimensions,\n  getImageBlurDataURL,\n  resolveImageRadius,\n};\n"],"mappings":";;;;AAMA,MAAM,kBACJ,WAC0B;CAC1B,IAAI,OAAO,WAAW,UACpB,OAAO,OAAO,KAAK,CAAC,CAAC,SAAS;CAGhC,OAAO,OAAO,QAAQ,QAAQ,YAAY,OAAO,IAAI,SAAS;AAChE;;;;;;AAOA,MAAM,qBACJ,WACuB;CACvB,IAAI,CAAC,eAAe,MAAM,GACxB;CAGF,OAAO,OAAO,WAAW,WAAW,SAAS,OAAO;AACtD;;;;AAKA,MAAM,sBAAsB,WAA2C;CACrE,IAAI,OAAO,WAAW,YAAY,WAAW,MAC3C;CAGF,OAAO;EACL,OAAO,OAAO;EACd,QAAQ,OAAO;CACjB;AACF;;;;AAKA,MAAM,uBACJ,WACuB;CACvB,IAAI,OAAO,WAAW,YAAY,WAAW,MAC3C;CAGF,OAAO,OAAO;AAChB;;;;AAKA,MAAM,sBACJ,WACkC;CAClC,IAAI,WAAW,KAAA,GACb;CAYF,OAAO;EARL,MAAM;EACN,IAAI;EACJ,IAAI;EACJ,IAAI;EACJ,IAAI;EACJ,MAAM;CAGU,EAAE,WAAW;AACjC"}

package/dist/components/data-display/image/image.utils.js

@@ -0,0 +1,51 @@
+// src/components/data-display/image/image.utils.ts
+/**
+* Checks whether an image source contains a usable URL.
+*/
+const hasImageSource = (source) => {
+	if (typeof source === "string") return source.trim().length > 0;
+	return typeof source?.src === "string" && source.src.length > 0;
+};
+/**
+* Resolves a source to a regular URL.
+*
+* Static image objects are converted to their `src` property.
+*/
+const getImageSourceUrl = (source) => {
+	if (!hasImageSource(source)) return;
+	return typeof source === "string" ? source : source.src;
+};
+/**
+* Retrieves intrinsic dimensions from static image imports.
+*/
+const getImageDimensions = (source) => {
+	if (typeof source !== "object" || source === null) return;
+	return {
+		width: source.width,
+		height: source.height
+	};
+};
+/**
+* Resolves an explicitly provided or statically imported blur image.
+*/
+const getImageBlurDataURL = (source) => {
+	if (typeof source !== "object" || source === null) return;
+	return source.blurDataURL;
+};
+/**
+* Resolves semantic radius values to Puzzle theme tokens.
+*/
+const resolveImageRadius = (radius) => {
+	if (radius === void 0) return;
+	return {
+		none: "0",
+		sm: "var(--puzzle-radius-sm, 0.25rem)",
+		md: "var(--puzzle-radius-md, 0.5rem)",
+		lg: "var(--puzzle-radius-lg, 0.75rem)",
+		xl: "var(--puzzle-radius-xl, 1rem)",
+		full: "var(--puzzle-radius-full, 9999px)"
+	}[radius] ?? radius;
+};
+export { getImageBlurDataURL, getImageDimensions, getImageSourceUrl, hasImageSource, resolveImageRadius };
+
+//# sourceMappingURL=image.utils.js.map

package/dist/components/data-display/image/image.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.utils.js","names":[],"sources":["../../../../src/components/data-display/image/image.utils.ts"],"sourcesContent":["import type { CSSProperties } from \"react\";\nimport type { ImageRadius, ImageSource } from \"./image.types\";\n\n/**\n * Checks whether an image source contains a usable URL.\n */\nconst hasImageSource = (\n  source: ImageSource | null | undefined,\n): source is ImageSource => {\n  if (typeof source === \"string\") {\n    return source.trim().length > 0;\n  }\n\n  return typeof source?.src === \"string\" && source.src.length > 0;\n};\n\n/**\n * Resolves a source to a regular URL.\n *\n * Static image objects are converted to their `src` property.\n */\nconst getImageSourceUrl = (\n  source: ImageSource | null | undefined,\n): string | undefined => {\n  if (!hasImageSource(source)) {\n    return undefined;\n  }\n\n  return typeof source === \"string\" ? source : source.src;\n};\n\n/**\n * Retrieves intrinsic dimensions from static image imports.\n */\nconst getImageDimensions = (source: ImageSource | null | undefined) => {\n  if (typeof source !== \"object\" || source === null) {\n    return undefined;\n  }\n\n  return {\n    width: source.width,\n    height: source.height,\n  };\n};\n\n/**\n * Resolves an explicitly provided or statically imported blur image.\n */\nconst getImageBlurDataURL = (\n  source: ImageSource | null | undefined,\n): string | undefined => {\n  if (typeof source !== \"object\" || source === null) {\n    return undefined;\n  }\n\n  return source.blurDataURL;\n};\n\n/**\n * Resolves semantic radius values to Puzzle theme tokens.\n */\nconst resolveImageRadius = (\n  radius?: ImageRadius,\n): CSSProperties[\"borderRadius\"] => {\n  if (radius === undefined) {\n    return undefined;\n  }\n\n  const radiusTokens: Record<string, string> = {\n    none: \"0\",\n    sm: \"var(--puzzle-radius-sm, 0.25rem)\",\n    md: \"var(--puzzle-radius-md, 0.5rem)\",\n    lg: \"var(--puzzle-radius-lg, 0.75rem)\",\n    xl: \"var(--puzzle-radius-xl, 1rem)\",\n    full: \"var(--puzzle-radius-full, 9999px)\",\n  };\n\n  return radiusTokens[radius] ?? radius;\n};\n\nexport {\n  hasImageSource,\n  getImageSourceUrl,\n  getImageDimensions,\n  getImageBlurDataURL,\n  resolveImageRadius,\n};\n"],"mappings":";;;;AAMA,MAAM,kBACJ,WAC0B;CAC1B,IAAI,OAAO,WAAW,UACpB,OAAO,OAAO,KAAK,CAAC,CAAC,SAAS;CAGhC,OAAO,OAAO,QAAQ,QAAQ,YAAY,OAAO,IAAI,SAAS;AAChE;;;;;;AAOA,MAAM,qBACJ,WACuB;CACvB,IAAI,CAAC,eAAe,MAAM,GACxB;CAGF,OAAO,OAAO,WAAW,WAAW,SAAS,OAAO;AACtD;;;;AAKA,MAAM,sBAAsB,WAA2C;CACrE,IAAI,OAAO,WAAW,YAAY,WAAW,MAC3C;CAGF,OAAO;EACL,OAAO,OAAO;EACd,QAAQ,OAAO;CACjB;AACF;;;;AAKA,MAAM,uBACJ,WACuB;CACvB,IAAI,OAAO,WAAW,YAAY,WAAW,MAC3C;CAGF,OAAO,OAAO;AAChB;;;;AAKA,MAAM,sBACJ,WACkC;CAClC,IAAI,WAAW,KAAA,GACb;CAYF,OAAO;EARL,MAAM;EACN,IAAI;EACJ,IAAI;EACJ,IAAI;EACJ,IAAI;EACJ,MAAM;CAGU,EAAE,WAAW;AACjC"}

package/dist/components/data-display/image/index.cjs

@@ -0,0 +1,176 @@
+"use client";
+const require_image_utils = require("./image.utils.cjs");
+const require_use_image_state = require("./use-image-state.cjs");
+;/* empty css            */
+let _puzzle_ui_core = require("@puzzle-ui/core");
+let react = require("react");
+let _puzzle_ui_theme_components_context = require("@puzzle-ui/theme/components-context");
+let react_jsx_runtime = require("react/jsx-runtime");
+let react_dom = require("react-dom");
+// src/components/data-display/image/index.tsx
+const Image = ({ src, alt, width, height, fit = "cover", position = "center", aspectRatio, fill = false, radius, fallbackSrc, fallback, loadingPlaceholder, placeholder = "empty", blurDataURL, sources, component, componentProps, quality, preload = false, unoptimized, className, style, containerClassName, containerStyle, loading, fetchPriority, decoding, srcSet, sizes, crossOrigin, referrerPolicy, ref, onLoad, onError, ...rest }) => {
+	const configuredImage = (0, _puzzle_ui_theme_components_context.useThemeComponents)()?.image;
+	const Component = component ?? configuredImage ?? "img";
+	const isNativeImage = Component === "img";
+	const { activeSource, usingFallback, status, markLoaded, markError } = require_use_image_state.useImageState(src, fallbackSrc);
+	const hasActiveSource = require_image_utils.hasImageSource(activeSource);
+	const sourceUrl = require_image_utils.getImageSourceUrl(activeSource);
+	const sourceDimensions = require_image_utils.getImageDimensions(activeSource);
+	const resolvedWidth = width ?? sourceDimensions?.width;
+	const resolvedHeight = height ?? sourceDimensions?.height;
+	const resolvedBlurDataURL = blurDataURL ?? require_image_utils.getImageBlurDataURL(activeSource);
+	const imageRef = (0, react.useRef)(null);
+	/**
+	* Assigns the image element to both the internal and external refs.
+	*/
+	const setImageRef = (0, react.useCallback)((node) => {
+		imageRef.current = node;
+		if (typeof ref === "function") ref(node);
+		else if (ref) ref.current = node;
+	}, [ref]);
+	/**
+	* Handles successful image loading.
+	*/
+	const handleLoad = (0, react.useCallback)((event) => {
+		markLoaded();
+		onLoad?.(event);
+	}, [markLoaded, onLoad]);
+	/**
+	* Handles image loading failures.
+	*/
+	const handleError = (0, react.useCallback)((event) => {
+		markError();
+		onError?.(event);
+	}, [markError, onError]);
+	/**
+	* Handles images that were loaded before React attached its listeners.
+	*
+	* This is particularly useful for cached images during hydration.
+	*/
+	(0, react.useEffect)(() => {
+		const image = imageRef.current;
+		if (!image || !image.complete) return;
+		if (image.naturalWidth > 0) markLoaded();
+	}, [activeSource, markLoaded]);
+	/**
+	* Preloads native images using React DOM.
+	*
+	* Framework image components handle their own preload behavior.
+	*/
+	if (preload && isNativeImage && sourceUrl) (0, react_dom.preload)(sourceUrl, {
+		as: "image",
+		crossOrigin,
+		fetchPriority: fetchPriority ?? "high",
+		imageSrcSet: srcSet,
+		imageSizes: sizes,
+		referrerPolicy
+	});
+	const mediaStyle = {
+		...fill || aspectRatio ? {
+			width: "100%",
+			height: "100%"
+		} : {},
+		...fill ? {
+			position: "absolute",
+			inset: 0
+		} : {},
+		objectFit: fit,
+		objectPosition: position,
+		...style
+	};
+	const wrapperStyle = {
+		...aspectRatio ? {
+			aspectRatio,
+			width: "100%"
+		} : {},
+		...fill ? {
+			position: "relative",
+			display: "block",
+			width: "100%",
+			...aspectRatio ? {} : { height: "100%" }
+		} : {},
+		...radius ? { borderRadius: require_image_utils.resolveImageRadius(radius) } : {},
+		...containerStyle
+	};
+	const isLoading = hasActiveSource && status === "loading";
+	const shouldShowFallback = fallback !== void 0 && (!hasActiveSource || status === "error");
+	if (!hasActiveSource && !shouldShowFallback) return null;
+	const renderedSource = isNativeImage ? sourceUrl : activeSource;
+	/**
+	* Framework-specific props are only forwarded to custom components.
+	* This prevents invalid attributes from leaking onto native img tags.
+	*/
+	const imageElement = (0, react.createElement)(Component, {
+		...!isNativeImage ? componentProps : {},
+		...rest,
+		key: usingFallback ? "fallback" : "source",
+		ref: setImageRef,
+		src: renderedSource,
+		alt,
+		width: resolvedWidth,
+		height: resolvedHeight,
+		loading,
+		fetchPriority,
+		decoding,
+		crossOrigin,
+		referrerPolicy,
+		srcSet,
+		sizes,
+		className: (0, _puzzle_ui_core.cn)("puzzle-image__media", className),
+		style: mediaStyle,
+		onLoad: handleLoad,
+		onError: handleError,
+		...fill && !isNativeImage ? { fill: true } : {},
+		...preload && !isNativeImage ? { preload: true } : {},
+		...quality !== void 0 && !isNativeImage ? { quality } : {},
+		...unoptimized !== void 0 && !isNativeImage ? { unoptimized } : {},
+		...!isNativeImage && placeholder === "blur" && resolvedBlurDataURL ? {
+			placeholder: "blur",
+			blurDataURL: resolvedBlurDataURL
+		} : {}
+	});
+	/**
+	* Picture sources allow art direction and responsive source selection.
+	*/
+	const media = sources?.length ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("picture", {
+		className: "puzzle-image__picture",
+		children: [sources.map((source, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("source", {
+			srcSet: source.srcSet,
+			media: source.media,
+			type: source.type,
+			sizes: source.sizes
+		}, `${source.srcSet}-${index}`)), imageElement]
+	}) : imageElement;
+	const showLoadingPlaceholder = isLoading && loadingPlaceholder !== void 0;
+	const showBlurPlaceholder = isLoading && !loadingPlaceholder && isNativeImage && placeholder === "blur" && Boolean(resolvedBlurDataURL);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: (0, _puzzle_ui_core.cn)("puzzle-image", containerClassName),
+		style: wrapperStyle,
+		"data-status": hasActiveSource ? status : "empty",
+		"data-image-fill": fill ? "true" : void 0,
+		"data-image-ratio": aspectRatio ? "true" : void 0,
+		children: [
+			showBlurPlaceholder ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
+				className: "puzzle-image__blur",
+				src: resolvedBlurDataURL,
+				alt: "",
+				"aria-hidden": "true"
+			}) : null,
+			showLoadingPlaceholder ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "puzzle-image__placeholder",
+				"aria-hidden": "true",
+				children: loadingPlaceholder
+			}) : null,
+			shouldShowFallback ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "puzzle-image__fallback",
+				role: alt ? "img" : void 0,
+				"aria-label": alt || void 0,
+				"aria-hidden": alt ? void 0 : true,
+				children: fallback
+			}) : media
+		]
+	});
+};
+exports.Image = Image;
+
+//# sourceMappingURL=index.cjs.map

package/dist/components/data-display/image/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["useThemeComponents","useImageState","hasImageSource","getImageSourceUrl","getImageDimensions","getImageBlurDataURL","useRef","useCallback","resolveImageRadius","createElement","cn"],"sources":["../../../../src/components/data-display/image/index.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createElement,\n  useCallback,\n  useEffect,\n  useRef,\n  type CSSProperties,\n  type ElementType,\n  type RefCallback,\n} from \"react\";\n\nimport { preload as preloadImage } from \"react-dom\";\n\nimport { cn } from \"@puzzle-ui/core\";\nimport { useThemeComponents } from \"@puzzle-ui/theme/components-context\";\n\nimport type { ImageProps } from \"./image.types\";\n\nimport {\n  getImageBlurDataURL,\n  getImageDimensions,\n  getImageSourceUrl,\n  hasImageSource,\n  resolveImageRadius,\n} from \"./image.utils\";\n\nimport { useImageState } from \"./use-image-state\";\n\nimport \"./image.css\";\n\nconst Image = ({\n  src,\n  alt,\n  width,\n  height,\n  fit = \"cover\",\n  position = \"center\",\n  aspectRatio,\n  fill = false,\n  radius,\n  fallbackSrc,\n  fallback,\n  loadingPlaceholder,\n  placeholder = \"empty\",\n  blurDataURL,\n  sources,\n  component,\n  componentProps,\n  quality,\n  preload = false,\n  unoptimized,\n  className,\n  style,\n  containerClassName,\n  containerStyle,\n  loading,\n  fetchPriority,\n  decoding,\n  srcSet,\n  sizes,\n  crossOrigin,\n  referrerPolicy,\n  ref,\n  onLoad,\n  onError,\n  ...rest\n}: ImageProps) => {\n  const configuredImage = useThemeComponents()?.image;\n\n  const Component: ElementType = component ?? configuredImage ?? \"img\";\n\n  const isNativeImage = Component === \"img\";\n\n  const { activeSource, usingFallback, status, markLoaded, markError } =\n    useImageState(src, fallbackSrc);\n\n  const hasActiveSource = hasImageSource(activeSource);\n\n  const sourceUrl = getImageSourceUrl(activeSource);\n\n  const sourceDimensions = getImageDimensions(activeSource);\n\n  const resolvedWidth = width ?? sourceDimensions?.width;\n  const resolvedHeight = height ?? sourceDimensions?.height;\n\n  const resolvedBlurDataURL = blurDataURL ?? getImageBlurDataURL(activeSource);\n\n  const imageRef = useRef<HTMLImageElement | null>(null);\n\n  /**\n   * Assigns the image element to both the internal and external refs.\n   */\n  const setImageRef = useCallback<RefCallback<HTMLImageElement>>(\n    (node) => {\n      imageRef.current = node;\n\n      if (typeof ref === \"function\") {\n        ref(node);\n      } else if (ref) {\n        ref.current = node;\n      }\n    },\n    [ref],\n  );\n\n  /**\n   * Handles successful image loading.\n   */\n  const handleLoad: NonNullable<ImageProps[\"onLoad\"]> = useCallback(\n    (event) => {\n      markLoaded();\n      onLoad?.(event);\n    },\n    [markLoaded, onLoad],\n  );\n\n  /**\n   * Handles image loading failures.\n   */\n  const handleError: NonNullable<ImageProps[\"onError\"]> = useCallback(\n    (event) => {\n      markError();\n      onError?.(event);\n    },\n    [markError, onError],\n  );\n\n  /**\n   * Handles images that were loaded before React attached its listeners.\n   *\n   * This is particularly useful for cached images during hydration.\n   */\n  useEffect(() => {\n    const image = imageRef.current;\n\n    if (!image || !image.complete) {\n      return;\n    }\n\n    if (image.naturalWidth > 0) {\n      markLoaded();\n    }\n  }, [activeSource, markLoaded]);\n\n  /**\n   * Preloads native images using React DOM.\n   *\n   * Framework image components handle their own preload behavior.\n   */\n  if (preload && isNativeImage && sourceUrl) {\n    preloadImage(sourceUrl, {\n      as: \"image\",\n      crossOrigin,\n      fetchPriority: fetchPriority ?? \"high\",\n      imageSrcSet: srcSet,\n      imageSizes: sizes,\n      referrerPolicy,\n    });\n  }\n\n  const mediaStyle: CSSProperties = {\n    ...(fill || aspectRatio\n      ? {\n          width: \"100%\",\n          height: \"100%\",\n        }\n      : {}),\n    ...(fill\n      ? {\n          position: \"absolute\",\n          inset: 0,\n        }\n      : {}),\n    objectFit: fit,\n    objectPosition: position,\n    ...style,\n  };\n\n  const wrapperStyle: CSSProperties = {\n    ...(aspectRatio\n      ? {\n          aspectRatio,\n          width: \"100%\",\n        }\n      : {}),\n    ...(fill\n      ? {\n          position: \"relative\",\n          display: \"block\",\n          width: \"100%\",\n          ...(aspectRatio ? {} : { height: \"100%\" }),\n        }\n      : {}),\n    ...(radius\n      ? {\n          borderRadius: resolveImageRadius(radius),\n        }\n      : {}),\n    ...containerStyle,\n  };\n\n  const isLoading = hasActiveSource && status === \"loading\";\n\n  const shouldShowFallback =\n    fallback !== undefined && (!hasActiveSource || status === \"error\");\n\n  if (!hasActiveSource && !shouldShowFallback) {\n    return null;\n  }\n\n  const renderedSource = isNativeImage ? sourceUrl : activeSource;\n\n  /**\n   * Framework-specific props are only forwarded to custom components.\n   * This prevents invalid attributes from leaking onto native img tags.\n   */\n  const imageElement = createElement(Component, {\n    ...(!isNativeImage ? componentProps : {}),\n    ...rest,\n    key: usingFallback ? \"fallback\" : \"source\",\n    ref: setImageRef,\n    src: renderedSource,\n    alt,\n    width: resolvedWidth,\n    height: resolvedHeight,\n    loading,\n    fetchPriority,\n    decoding,\n    crossOrigin,\n    referrerPolicy,\n    srcSet,\n    sizes,\n    className: cn(\"puzzle-image__media\", className),\n    style: mediaStyle,\n    onLoad: handleLoad,\n    onError: handleError,\n    ...(fill && !isNativeImage ? { fill: true } : {}),\n    ...(preload && !isNativeImage ? { preload: true } : {}),\n    ...(quality !== undefined && !isNativeImage ? { quality } : {}),\n    ...(unoptimized !== undefined && !isNativeImage ? { unoptimized } : {}),\n    ...(!isNativeImage && placeholder === \"blur\" && resolvedBlurDataURL\n      ? {\n          placeholder: \"blur\",\n          blurDataURL: resolvedBlurDataURL,\n        }\n      : {}),\n  } as never);\n\n  /**\n   * Picture sources allow art direction and responsive source selection.\n   */\n  const media = sources?.length ? (\n    <picture className=\"puzzle-image__picture\">\n      {sources.map((source, index) => (\n        <source\n          key={`${source.srcSet}-${index}`}\n          srcSet={source.srcSet}\n          media={source.media}\n          type={source.type}\n          sizes={source.sizes}\n        />\n      ))}\n      {imageElement}\n    </picture>\n  ) : (\n    imageElement\n  );\n\n  const showLoadingPlaceholder = isLoading && loadingPlaceholder !== undefined;\n\n  const showBlurPlaceholder =\n    isLoading &&\n    !loadingPlaceholder &&\n    isNativeImage &&\n    placeholder === \"blur\" &&\n    Boolean(resolvedBlurDataURL);\n\n  return (\n    <div\n      className={cn(\"puzzle-image\", containerClassName)}\n      style={wrapperStyle}\n      data-status={hasActiveSource ? status : \"empty\"}\n      data-image-fill={fill ? \"true\" : undefined}\n      data-image-ratio={aspectRatio ? \"true\" : undefined}\n    >\n      {showBlurPlaceholder ? (\n        <img\n          className=\"puzzle-image__blur\"\n          src={resolvedBlurDataURL}\n          alt=\"\"\n          aria-hidden=\"true\"\n        />\n      ) : null}\n\n      {showLoadingPlaceholder ? (\n        <div className=\"puzzle-image__placeholder\" aria-hidden=\"true\">\n          {loadingPlaceholder}\n        </div>\n      ) : null}\n\n      {shouldShowFallback ? (\n        <div\n          className=\"puzzle-image__fallback\"\n          role={alt ? \"img\" : undefined}\n          aria-label={alt || undefined}\n          aria-hidden={alt ? undefined : true}\n        >\n          {fallback}\n        </div>\n      ) : (\n        media\n      )}\n    </div>\n  );\n};\n\nexport { Image, type ImageProps };\n\nexport type {\n  ImageSource,\n  ImageSourceData,\n  ImageSourceSet,\n  ImageFit,\n  ImageRadius,\n  ImagePlaceholder,\n} from \"./image.types\";\n"],"mappings":";;;;;;;;;;AA+BA,MAAM,SAAS,EACb,KACA,KACA,OACA,QACA,MAAM,SACN,WAAW,UACX,aACA,OAAO,OACP,QACA,aACA,UACA,oBACA,cAAc,SACd,aACA,SACA,WACA,gBACA,SACA,UAAU,OACV,aACA,WACA,OACA,oBACA,gBACA,SACA,eACA,UACA,QACA,OACA,aACA,gBACA,KACA,QACA,SACA,GAAG,WACa;CAChB,MAAM,mBAAA,GAAkBA,oCAAAA,mBAAAA,CAAmB,CAAC,EAAE;CAE9C,MAAM,YAAyB,aAAa,mBAAmB;CAE/D,MAAM,gBAAgB,cAAc;CAEpC,MAAM,EAAE,cAAc,eAAe,QAAQ,YAAY,cACvDC,wBAAAA,cAAc,KAAK,WAAW;CAEhC,MAAM,kBAAkBC,oBAAAA,eAAe,YAAY;CAEnD,MAAM,YAAYC,oBAAAA,kBAAkB,YAAY;CAEhD,MAAM,mBAAmBC,oBAAAA,mBAAmB,YAAY;CAExD,MAAM,gBAAgB,SAAS,kBAAkB;CACjD,MAAM,iBAAiB,UAAU,kBAAkB;CAEnD,MAAM,sBAAsB,eAAeC,oBAAAA,oBAAoB,YAAY;CAE3E,MAAM,YAAA,GAAWC,MAAAA,OAAAA,CAAgC,IAAI;;;;CAKrD,MAAM,eAAA,GAAcC,MAAAA,YAAAA,EACjB,SAAS;EACR,SAAS,UAAU;EAEnB,IAAI,OAAO,QAAQ,YACjB,IAAI,IAAI;OACH,IAAI,KACT,IAAI,UAAU;CAElB,GACA,CAAC,GAAG,CACN;;;;CAKA,MAAM,cAAA,GAAgDA,MAAAA,YAAAA,EACnD,UAAU;EACT,WAAW;EACX,SAAS,KAAK;CAChB,GACA,CAAC,YAAY,MAAM,CACrB;;;;CAKA,MAAM,eAAA,GAAkDA,MAAAA,YAAAA,EACrD,UAAU;EACT,UAAU;EACV,UAAU,KAAK;CACjB,GACA,CAAC,WAAW,OAAO,CACrB;;;;;;CAOA,CAAA,GAAA,MAAA,UAAA,OAAgB;EACd,MAAM,QAAQ,SAAS;EAEvB,IAAI,CAAC,SAAS,CAAC,MAAM,UACnB;EAGF,IAAI,MAAM,eAAe,GACvB,WAAW;CAEf,GAAG,CAAC,cAAc,UAAU,CAAC;;;;;;CAO7B,IAAI,WAAW,iBAAiB,WAC9B,CAAA,GAAA,UAAA,QAAA,CAAa,WAAW;EACtB,IAAI;EACJ;EACA,eAAe,iBAAiB;EAChC,aAAa;EACb,YAAY;EACZ;CACF,CAAC;CAGH,MAAM,aAA4B;EAChC,GAAI,QAAQ,cACR;GACE,OAAO;GACP,QAAQ;EACV,IACA,CAAC;EACL,GAAI,OACA;GACE,UAAU;GACV,OAAO;EACT,IACA,CAAC;EACL,WAAW;EACX,gBAAgB;EAChB,GAAG;CACL;CAEA,MAAM,eAA8B;EAClC,GAAI,cACA;GACE;GACA,OAAO;EACT,IACA,CAAC;EACL,GAAI,OACA;GACE,UAAU;GACV,SAAS;GACT,OAAO;GACP,GAAI,cAAc,CAAC,IAAI,EAAE,QAAQ,OAAO;EAC1C,IACA,CAAC;EACL,GAAI,SACA,EACE,cAAcC,oBAAAA,mBAAmB,MAAM,EACzC,IACA,CAAC;EACL,GAAG;CACL;CAEA,MAAM,YAAY,mBAAmB,WAAW;CAEhD,MAAM,qBACJ,aAAa,KAAA,MAAc,CAAC,mBAAmB,WAAW;CAE5D,IAAI,CAAC,mBAAmB,CAAC,oBACvB,OAAO;CAGT,MAAM,iBAAiB,gBAAgB,YAAY;;;;;CAMnD,MAAM,gBAAA,GAAeC,MAAAA,cAAAA,CAAc,WAAW;EAC5C,GAAI,CAAC,gBAAgB,iBAAiB,CAAC;EACvC,GAAG;EACH,KAAK,gBAAgB,aAAa;EAClC,KAAK;EACL,KAAK;EACL;EACA,OAAO;EACP,QAAQ;EACR;EACA;EACA;EACA;EACA;EACA;EACA;EACA,YAAA,GAAWC,gBAAAA,GAAAA,CAAG,uBAAuB,SAAS;EAC9C,OAAO;EACP,QAAQ;EACR,SAAS;EACT,GAAI,QAAQ,CAAC,gBAAgB,EAAE,MAAM,KAAK,IAAI,CAAC;EAC/C,GAAI,WAAW,CAAC,gBAAgB,EAAE,SAAS,KAAK,IAAI,CAAC;EACrD,GAAI,YAAY,KAAA,KAAa,CAAC,gBAAgB,EAAE,QAAQ,IAAI,CAAC;EAC7D,GAAI,gBAAgB,KAAA,KAAa,CAAC,gBAAgB,EAAE,YAAY,IAAI,CAAC;EACrE,GAAI,CAAC,iBAAiB,gBAAgB,UAAU,sBAC5C;GACE,aAAa;GACb,aAAa;EACf,IACA,CAAC;CACP,CAAU;;;;CAKV,MAAM,QAAQ,SAAS,SACrB,iBAAA,GAAA,kBAAA,KAAA,CAAC,WAAD;EAAS,WAAU;EAAnB,UAAA,CACG,QAAQ,KAAK,QAAQ,UACpB,iBAAA,GAAA,kBAAA,IAAA,CAAC,UAAD;GAEE,QAAQ,OAAO;GACf,OAAO,OAAO;GACd,MAAM,OAAO;GACb,OAAO,OAAO;EACf,GALM,GAAG,OAAO,OAAO,GAAG,OAK1B,CACF,GACA,YACM;CAET,CAAA,IAAA;CAGF,MAAM,yBAAyB,aAAa,uBAAuB,KAAA;CAEnE,MAAM,sBACJ,aACA,CAAC,sBACD,iBACA,gBAAgB,UAChB,QAAQ,mBAAmB;CAE7B,OACE,iBAAA,GAAA,kBAAA,KAAA,CAAC,OAAD;EACE,YAAA,GAAWA,gBAAAA,GAAAA,CAAG,gBAAgB,kBAAkB;EAChD,OAAO;EACP,eAAa,kBAAkB,SAAS;EACxC,mBAAiB,OAAO,SAAS,KAAA;EACjC,oBAAkB,cAAc,SAAS,KAAA;EAL3C,UAAA;GAOG,sBACC,iBAAA,GAAA,kBAAA,IAAA,CAAC,OAAD;IACE,WAAU;IACV,KAAK;IACL,KAAI;IACJ,eAAY;GACb,CAAA,IACC;GAEH,yBACC,iBAAA,GAAA,kBAAA,IAAA,CAAC,OAAD;IAAK,WAAU;IAA4B,eAAY;IACpD,UAAA;GACE,CAAA,IACH;GAEH,qBACC,iBAAA,GAAA,kBAAA,IAAA,CAAC,OAAD;IACE,WAAU;IACV,MAAM,MAAM,QAAQ,KAAA;IACpB,cAAY,OAAO,KAAA;IACnB,eAAa,MAAM,KAAA,IAAY;IAE9B,UAAA;GACE,CAAA,IAEL;EAEC;;AAET"}

package/dist/components/data-display/image/index.d.cts

@@ -0,0 +1,3 @@
+import { ImageFit, ImagePlaceholder, ImageProps, ImageRadius, ImageSource, ImageSourceData, ImageSourceSet } from "./image.types.cjs";
+declare const Image: ({ src, alt, width, height, fit, position, aspectRatio, fill, radius, fallbackSrc, fallback, loadingPlaceholder, placeholder, blurDataURL, sources, component, componentProps, quality, preload, unoptimized, className, style, containerClassName, containerStyle, loading, fetchPriority, decoding, srcSet, sizes, crossOrigin, referrerPolicy, ref, onLoad, onError, ...rest }: ImageProps) => import("react").JSX.Element | null;
+export { Image, type ImageFit, type ImagePlaceholder, type ImageProps, type ImageRadius, type ImageSource, type ImageSourceData, type ImageSourceSet };

package/dist/components/data-display/image/index.d.ts

@@ -0,0 +1,3 @@
+import { ImageFit, ImagePlaceholder, ImageProps, ImageRadius, ImageSource, ImageSourceData, ImageSourceSet } from "./image.types.js";
+declare const Image: ({ src, alt, width, height, fit, position, aspectRatio, fill, radius, fallbackSrc, fallback, loadingPlaceholder, placeholder, blurDataURL, sources, component, componentProps, quality, preload, unoptimized, className, style, containerClassName, containerStyle, loading, fetchPriority, decoding, srcSet, sizes, crossOrigin, referrerPolicy, ref, onLoad, onError, ...rest }: ImageProps) => import("react").JSX.Element | null;
+export { Image, type ImageFit, type ImagePlaceholder, type ImageProps, type ImageRadius, type ImageSource, type ImageSourceData, type ImageSourceSet };