@pithyjs/ui-kit 0.1.0-beta.0

package/dist/atoms/content/icon/icon.scss

@@ -0,0 +1,66 @@
+/// Icon component styles
+/// Accessible inline icon wrapper sized by design-system iconography tokens.
+/// Uses currentColor inheritance — zero raw values.
+///
+/// @group atoms/content
+
+@use '@pithyjs/design-system/iconography/_generated/tokens' as icon-tokens;
+@use '../mixins' as content;
+
+// ============================================
+// Base wrapper — inline icon container
+// ============================================
+
+.ui-icon {
+  // Inline-flex keeps icon inline with text while centering SVG content
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  // Shrink-to-fit — default md size (overridden by u-icon-* utilities)
+  inline-size: icon-tokens.icon-size-var(md);
+  block-size: icon-tokens.icon-size-var(md);
+  // Inherit parent text color by default
+  color: currentColor;
+  // Ensure SVG children fill the container
+  line-height: 0;
+  // Clip overflow — fixed-size box should not leak content beyond its bounds
+  overflow: hidden;
+  // Prevent icon from shrinking in flex layouts
+  flex-shrink: 0;
+  // Optical alignment with adjacent text
+  vertical-align: middle;
+
+  // SVG children should fill the icon container.
+  // No fill/stroke override — SVGs control their own rendering:
+  //   Solid icons:   use fill="currentColor" (or inherit from parent color)
+  //   Outline icons: use fill="none" stroke="currentColor"
+  // This avoids CSS fill overriding SVG presentation attributes.
+  > svg {
+    inline-size: 100%;
+    block-size: 100%;
+  }
+}
+
+// ============================================
+// Size variants (from --icon-size-* tokens)
+// ============================================
+
+@each $level, $_value in icon-tokens.$size-tokens {
+  .u-icon-#{$level} {
+    inline-size: icon-tokens.icon-size-var($level);
+    block-size: icon-tokens.icon-size-var($level);
+  }
+}
+
+// ============================================
+// Color scheme (maps data-color to --color-* tokens)
+// ============================================
+
+@include content.color-scheme('.ui-icon');
+
+// ============================================
+// High Contrast (forced-colors + increased contrast)
+// ============================================
+
+@include content.forced-colors('.ui-icon');
+@include content.high-contrast('.ui-icon');

package/dist/atoms/content/icon/resolveIconSvg.d.ts

@@ -0,0 +1,21 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.icon-resolve",
+  "title": "Icon Sprite SVG Resolution",
+  "category": "runtime"
+}
+*/
+export interface ResolvedIcon {
+    /** The SVG element to append */
+    svg: SVGSVGElement;
+    /** Whether this is a missing-icon placeholder */
+    missing: boolean;
+}
+/**
+ * Try to resolve `name` from the icon sprite registry.
+ *
+ * @returns A resolved icon with `svg` and `missing` flag, or `null` if no name was provided.
+ */
+/** @codexApi {"parent":"pithy.ui-kit.icon-resolve","name":"resolveIconSvg","stability":"stable","signature":"(name: string | undefined) => ResolvedIcon | null"} */
+export declare function resolveIconSvg(name: string | undefined): ResolvedIcon | null;
+//# sourceMappingURL=resolveIconSvg.d.ts.map

package/dist/atoms/content/icon/resolveIconSvg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveIconSvg.d.ts","sourceRoot":"","sources":["../../../../src/atoms/content/icon/resolveIconSvg.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAiBF,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,GAAG,EAAE,aAAa,CAAC;IACnB,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,oKAAoK;AACpK,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,IAAI,CA2B5E"}

package/dist/atoms/content/icon/resolveIconSvg.js

@@ -0,0 +1,73 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.icon-resolve",
+  "title": "Icon Sprite SVG Resolution",
+  "category": "runtime"
+}
+*/
+/**
+ * Resolve an icon name to an SVG element from the sprite registry.
+ *
+ * Returns a ready-to-append `<svg>` element:
+ * - Found → `<svg><use href="sprite#name"/></svg>`
+ * - Not found → placeholder (dashed circle + "?") with DEV warning
+ * - No name → `null`
+ */
+// Relative import to avoid self-referencing package alias (@pithyjs/ui-kit/icons).
+// Maps to: packages/ui-kit/src/icons/index.ts
+import { lookupIcon } from '../../../icons';
+const SVG_NS = 'http://www.w3.org/2000/svg';
+/**
+ * Try to resolve `name` from the icon sprite registry.
+ *
+ * @returns A resolved icon with `svg` and `missing` flag, or `null` if no name was provided.
+ */
+/** @codexApi {"parent":"pithy.ui-kit.icon-resolve","name":"resolveIconSvg","stability":"stable","signature":"(name: string | undefined) => ResolvedIcon | null"} */
+export function resolveIconSvg(name) {
+    const trimmed = name?.trim();
+    if (!trimmed)
+        return null;
+    const result = lookupIcon(trimmed);
+    if (result) {
+        const svg = document.createElementNS(SVG_NS, 'svg');
+        svg.setAttribute('aria-hidden', 'true');
+        if (result.viewBox) {
+            svg.setAttribute('viewBox', result.viewBox);
+        }
+        const use = document.createElementNS(SVG_NS, 'use');
+        use.setAttribute('href', result.href);
+        svg.appendChild(use);
+        return { svg, missing: false };
+    }
+    // Missing icon — placeholder: dashed circle + "?"
+    if (import.meta.env?.DEV) {
+        console.warn(`[<Icon>] name="${name}" not found in icon registry and no children provided. ` +
+            `Either register a sprite with registerIconSprite() or pass inline SVG as children.`);
+    }
+    return { svg: createMissingIconSvg(), missing: true };
+}
+function createMissingIconSvg() {
+    const svg = document.createElementNS(SVG_NS, 'svg');
+    svg.setAttribute('aria-hidden', 'true');
+    svg.setAttribute('viewBox', '0 0 24 24');
+    svg.setAttribute('fill', 'none');
+    svg.setAttribute('stroke', 'currentColor');
+    svg.setAttribute('stroke-width', '1.5');
+    const circle = document.createElementNS(SVG_NS, 'circle');
+    circle.setAttribute('cx', '12');
+    circle.setAttribute('cy', '12');
+    circle.setAttribute('r', '10');
+    circle.setAttribute('stroke-dasharray', '4 3');
+    svg.appendChild(circle);
+    const text = document.createElementNS(SVG_NS, 'text');
+    text.setAttribute('x', '12');
+    text.setAttribute('y', '16');
+    text.setAttribute('text-anchor', 'middle');
+    text.setAttribute('fill', 'currentColor');
+    text.setAttribute('stroke', 'none');
+    text.setAttribute('font-size', '12');
+    text.textContent = '?';
+    svg.appendChild(text);
+    return svg;
+}
+//# sourceMappingURL=resolveIconSvg.js.map

package/dist/atoms/content/icon/resolveIconSvg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveIconSvg.js","sourceRoot":"","sources":["../../../../src/atoms/content/icon/resolveIconSvg.ts"],"names":[],"mappings":"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"}

package/dist/atoms/content/image/Image.d.ts

@@ -0,0 +1,81 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.image",
+  "title": "<Image> Content Component",
+  "category": "feature"
+}
+*/
+import type { ReactiveText } from '../../../shared/clickable';
+import { type ImageFit, type ImageLoading, type ImageDecoding, type ImageFetchPriority, type ImageSizing } from '../../../shared/image';
+import { type RadiusLevel } from '@pithyjs/design-system/radius';
+/** @codexApi {"parent":"pithy.ui-kit.image","name":"ImageSource","stability":"stable","signature":"interface ImageSource"} */
+/**
+ * A single `<source>` entry for `<picture>` multi-format rendering.
+ * Each source must have at least one of `src` or `srcset`.
+ *
+ * Note: the root-level `ImageProps.src` is always required for the fallback
+ * `<img>` element. These sources only add `<source>` alternatives inside
+ * `<picture>` — they do not replace the root `src`.
+ */
+export interface ImageSource {
+    /** Image URL — required if `srcset` is not provided */
+    src?: string;
+    /** MIME type (e.g. "image/avif", "image/webp") */
+    type?: string;
+    /** Media condition (e.g. "(min-width: 768px)") */
+    media?: string;
+    /** Srcset descriptor (e.g. "img.avif 1x, img.avif 2x" or "img-400.avif 400w") */
+    srcset?: string;
+}
+/** @codexApi {"parent":"pithy.ui-kit.image","name":"ImageProps","stability":"stable","signature":"interface ImageProps"} */
+export interface ImageProps {
+    /** Image source URL — static string or signal/computed accessor. Required. */
+    src: ReactiveText;
+    /** Alt text for accessibility — static or signal. REQUIRED. Use "" only for purely decorative images. */
+    alt: ReactiveText;
+    /** Intrinsic width in pixels — prevents layout shift (CLS) */
+    width?: number;
+    /** Intrinsic height in pixels — prevents layout shift (CLS) */
+    height?: number;
+    /** Loading strategy (default: "lazy") */
+    loading?: ImageLoading;
+    /** Decoding strategy (default: "async") */
+    decoding?: ImageDecoding;
+    /** Fetch priority hint — use "high" for LCP images (default: "auto") */
+    fetchPriority?: ImageFetchPriority;
+    /** Aspect ratio — preset string ("16/9") or custom CSS value ("4 / 3") */
+    aspectRatio?: string;
+    /** Object-fit — how the image fills its container (default: "cover") */
+    fit?: ImageFit;
+    /** Width behaviour — "auto" (intrinsic, capped at 100%) or "fill" (100% of container). Default: "auto". */
+    sizing?: ImageSizing;
+    /** Responsive sizes attribute (e.g. "(max-width: 600px) 100vw, 50vw") */
+    sizes?: string;
+    /** Srcset for responsive resolution switching (e.g. "img-400.jpg 400w, img-800.jpg 800w") */
+    srcset?: string;
+    /** Additional <source> elements for <picture> — enables AVIF/WebP with fallback */
+    sources?: ImageSource[];
+    /** Border radius — design system RadiusLevel or true for "md" (default: none) */
+    rounded?: boolean | RadiusLevel;
+}
+/**
+ * Accessible, optimized image component.
+ *
+ * Mobile-first with lazy loading and async decoding by default.
+ * Enforces `alt` text for accessibility. Use `width`/`height` to eliminate
+ * layout shift (CLS = 0). Supports `<picture>` with multiple `<source>`
+ * elements for format negotiation (AVIF, WebP, fallback).
+ *
+ * @example
+ * ```html
+ * <Image src="'/photo.jpg'" alt="'A sunset'" width="800" height="600" />
+ * <Image src="'/hero.jpg'" alt="'Hero'" aspectRatio="'16/9'" fit="'cover'" loading="'eager'" fetchPriority="'high'" />
+ * <Image src="'/avatar.jpg'" alt="'User'" width="100" height="100" rounded="'xl'" />
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.image","name":"Image","stability":"stable","signature":"(props: ImageProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export declare function Image(props: ImageProps): {
+    el: HTMLElement | DocumentFragment;
+    destroy: () => void;
+};
+//# sourceMappingURL=Image.d.ts.map

package/dist/atoms/content/image/Image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Image.d.ts","sourceRoot":"","sources":["../../../../src/atoms/content/image/Image.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAKF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAOL,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAIhF,8HAA8H;AAC9H;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,4HAA4H;AAC5H,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,GAAG,EAAE,YAAY,CAAC;IAClB,yGAAyG;IACzG,GAAG,EAAE,YAAY,CAAC;IAClB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,wEAAwE;IACxE,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,2GAA2G;IAC3G,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,qLAAqL;AACrL,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG;IACxC,EAAE,EAAE,WAAW,GAAG,gBAAgB,CAAC;IACnC,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAkVA"}

package/dist/atoms/content/image/Image.js

@@ -0,0 +1,293 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.image",
+  "title": "<Image> Content Component",
+  "category": "feature"
+}
+*/
+import { renderChildren } from '@pithyjs/core';
+import { captureSlot } from '../../../shared/slots';
+import { effect } from '@pithyjs/signals';
+import { IMAGE_FIT_VALUES, IMAGE_LOADING_VALUES, IMAGE_DECODING_VALUES, IMAGE_FETCH_PRIORITY_VALUES, IMAGE_SIZING_VALUES, ASPECT_RATIO_PRESETS, } from '../../../shared/image';
+import { RADIUS_LEVELS } from '@pithyjs/design-system/radius';
+/**
+ * Accessible, optimized image component.
+ *
+ * Mobile-first with lazy loading and async decoding by default.
+ * Enforces `alt` text for accessibility. Use `width`/`height` to eliminate
+ * layout shift (CLS = 0). Supports `<picture>` with multiple `<source>`
+ * elements for format negotiation (AVIF, WebP, fallback).
+ *
+ * @example
+ * ```html
+ * <Image src="'/photo.jpg'" alt="'A sunset'" width="800" height="600" />
+ * <Image src="'/hero.jpg'" alt="'Hero'" aspectRatio="'16/9'" fit="'cover'" loading="'eager'" fetchPriority="'high'" />
+ * <Image src="'/avatar.jpg'" alt="'User'" width="100" height="100" rounded="'xl'" />
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.image","name":"Image","stability":"stable","signature":"(props: ImageProps) => { el: HTMLElement | DocumentFragment; destroy: () => void }"} */
+export function Image(props) {
+    const { src: srcProp, alt: altProp, width, height, loading: rawLoading = 'lazy', decoding: rawDecoding = 'async', fetchPriority: rawFetchPriority = 'auto', aspectRatio: rawAspectRatio, fit: rawFit = 'cover', sizing: rawSizing = 'auto', sizes, srcset, sources, rounded, } = props;
+    const isSrcFn = typeof srcProp === 'function';
+    const isAltFn = typeof altProp === 'function';
+    const readSrc = () => isSrcFn
+        ? srcProp()
+        : srcProp;
+    const readAlt = () => isAltFn
+        ? altProp()
+        : altProp;
+    const staticSrc = isSrcFn ? undefined : readSrc();
+    const staticAlt = isAltFn ? undefined : readAlt();
+    // -- Validation -----------------------------------------------------------
+    const hasSrc = typeof staticSrc === 'string' && staticSrc.trim().length > 0;
+    // Whitespace-only alt is treated as missing (warned in DEV); intentionally
+    // empty alt ("") is allowed and marks the image as decorative.
+    const isValidAlt = (v) => typeof v === 'string' && (v === '' || v.trim().length > 0);
+    const hasAlt = isValidAlt(staticAlt);
+    const validLoading = IMAGE_LOADING_VALUES.includes(rawLoading);
+    const validDecoding = IMAGE_DECODING_VALUES.includes(rawDecoding);
+    const validFetchPriority = IMAGE_FETCH_PRIORITY_VALUES.includes(rawFetchPriority);
+    const validFit = IMAGE_FIT_VALUES.includes(rawFit);
+    const sizing = IMAGE_SIZING_VALUES.includes(rawSizing)
+        ? rawSizing
+        : 'auto';
+    // Sanitize width/height: must be finite positive integers (at least 1px)
+    const validWidth = width != null && Number.isFinite(width) && width > 0
+        ? Math.max(1, Math.round(width))
+        : undefined;
+    const validHeight = height != null && Number.isFinite(height) && height > 0
+        ? Math.max(1, Math.round(height))
+        : undefined;
+    // Validate rounded prop
+    const validRounded = rounded === true
+        ? 'md'
+        : typeof rounded === 'string' &&
+            RADIUS_LEVELS.includes(rounded)
+            ? rounded
+            : undefined;
+    if (import.meta.env?.DEV) {
+        if (!isSrcFn && !hasSrc) {
+            console.warn(`[<Image>] Missing or empty "src" prop. An image source is required.`);
+        }
+        if (!isAltFn && !hasAlt) {
+            console.warn(`[<Image>] Missing "alt" prop. All images MUST have alt text for accessibility. Use alt="" only for purely decorative images.`);
+        }
+        if (!validLoading) {
+            const valid = IMAGE_LOADING_VALUES.join(', ');
+            console.warn(`[<Image>] Invalid loading: "${rawLoading}". Expected one of: ${valid}. Falling back to "lazy".`);
+        }
+        if (!validDecoding) {
+            const valid = IMAGE_DECODING_VALUES.join(', ');
+            console.warn(`[<Image>] Invalid decoding: "${rawDecoding}". Expected one of: ${valid}. Falling back to "async".`);
+        }
+        if (!validFetchPriority) {
+            const valid = IMAGE_FETCH_PRIORITY_VALUES.join(', ');
+            console.warn(`[<Image>] Invalid fetchPriority: "${rawFetchPriority}". Expected one of: ${valid}. Falling back to "auto".`);
+        }
+        if (!validFit) {
+            const valid = IMAGE_FIT_VALUES.join(', ');
+            console.warn(`[<Image>] Invalid fit: "${rawFit}". Expected one of: ${valid}. Falling back to "cover".`);
+        }
+        if (rawLoading === 'lazy' && rawFetchPriority === 'high') {
+            console.warn(`[<Image>] loading="lazy" with fetchPriority="high" is contradictory. For LCP images, use loading="eager" with fetchPriority="high".`);
+        }
+        if (width == null || height == null) {
+            console.warn(`[<Image>] Missing width/height. Provide both to prevent layout shift (CLS). The browser needs intrinsic dimensions to reserve space before the image loads.`);
+        }
+        if (width != null && (!Number.isFinite(width) || width <= 0)) {
+            console.warn(`[<Image>] Invalid width: ${width}. Expected a finite positive number. Ignoring.`);
+        }
+        if (height != null && (!Number.isFinite(height) || height <= 0)) {
+            console.warn(`[<Image>] Invalid height: ${height}. Expected a finite positive number. Ignoring.`);
+        }
+        if (rounded != null &&
+            rounded !== true &&
+            rounded !== false &&
+            !validRounded) {
+            const valid = RADIUS_LEVELS.join(', ');
+            console.warn(`[<Image>] Invalid rounded: "${rounded}". Expected true or one of: ${valid}. Ignoring.`);
+        }
+        if (sources != null && !Array.isArray(sources)) {
+            console.warn(`[<Image>] Invalid "sources" prop: expected an array of ImageSource objects. Falling back to plain <img>.`);
+        }
+        if (Array.isArray(sources) &&
+            sources.some(s => s == null ||
+                typeof s !== 'object' ||
+                ((typeof s.src !== 'string' || s.src.trim().length === 0) &&
+                    (typeof s.srcset !== 'string' || s.srcset.trim().length === 0)))) {
+            console.warn(`[<Image>] Some entries in "sources" are invalid: each source must be an object with a non-empty "src" or "srcset" string.`);
+        }
+    }
+    const loading = validLoading ? rawLoading : 'lazy';
+    const decoding = validDecoding ? rawDecoding : 'async';
+    const fetchPriority = validFetchPriority ? rawFetchPriority : 'auto';
+    const fit = validFit ? rawFit : 'cover';
+    // Resolve aspect ratio (preset or custom CSS value)
+    const aspectRatio = rawAspectRatio
+        ? ASPECT_RATIO_PRESETS[rawAspectRatio] || rawAspectRatio
+        : undefined;
+    // -- Determine rendering mode: <picture> or plain <img> -------------------
+    const usePicture = Array.isArray(sources) && sources.length > 0;
+    // -- Build wrapper element ------------------------------------------------
+    const el = document.createElement('div');
+    el.classList.add('ui-image');
+    if (sizing === 'fill') {
+        el.dataset.sizing = 'fill';
+    }
+    // Aspect ratio container
+    if (aspectRatio) {
+        el.style.aspectRatio = aspectRatio;
+        el.classList.add('ui-image-aspect-ratio');
+    }
+    // Rounded corners — maps to design system u-radius-* utilities
+    if (validRounded) {
+        el.classList.add(`u-radius-${validRounded}`);
+    }
+    // Width/height on wrapper to reserve space (CLS prevention)
+    if (validWidth != null && !aspectRatio) {
+        el.style.maxInlineSize = `${validWidth}px`;
+    }
+    // -- Build image content or empty placeholder -----------------------------
+    // Applied separately so buildImageContent doesn't subscribe its caller to alt.
+    const applyAlt = (target, value) => {
+        if (isValidAlt(value)) {
+            target.alt = value;
+            if (value === '')
+                target.setAttribute('role', 'none');
+            else
+                target.removeAttribute('role');
+        }
+        else {
+            target.removeAttribute('alt');
+            target.removeAttribute('role');
+        }
+    };
+    const buildImageContent = (src) => {
+        const newImg = document.createElement('img');
+        newImg.classList.add('ui-image-img');
+        newImg.src = src;
+        newImg.loading = loading;
+        newImg.decoding = decoding;
+        if (fetchPriority !== 'auto') {
+            newImg.setAttribute('fetchpriority', fetchPriority);
+        }
+        if (validWidth != null)
+            newImg.width = validWidth;
+        if (validHeight != null)
+            newImg.height = validHeight;
+        if (fit)
+            newImg.style.objectFit = fit;
+        if (typeof sizes === 'string') {
+            const trimmedSizes = sizes.trim();
+            if (trimmedSizes.length > 0)
+                newImg.sizes = trimmedSizes;
+        }
+        if (typeof srcset === 'string') {
+            const trimmedSrcset = srcset.trim();
+            if (trimmedSrcset.length > 0)
+                newImg.srcset = trimmedSrcset;
+        }
+        const pictureSources = usePicture ? sources : [];
+        if (pictureSources.length === 0)
+            return { root: newImg, img: newImg };
+        const picture = document.createElement('picture');
+        picture.classList.add('ui-image-picture');
+        for (const source of pictureSources) {
+            const trimmedSrc = typeof source?.src === 'string' ? source.src.trim() : '';
+            const trimmedSrcset = typeof source?.srcset === 'string' ? source.srcset.trim() : '';
+            if (source == null ||
+                typeof source !== 'object' ||
+                (!trimmedSrc && !trimmedSrcset)) {
+                continue;
+            }
+            const sourceEl = document.createElement('source');
+            sourceEl.srcset = trimmedSrcset || trimmedSrc;
+            if (typeof source.type === 'string') {
+                const trimmedType = source.type.trim();
+                if (trimmedType)
+                    sourceEl.type = trimmedType;
+            }
+            if (typeof source.media === 'string') {
+                const trimmedMedia = source.media.trim();
+                if (trimmedMedia)
+                    sourceEl.media = trimmedMedia;
+            }
+            if (typeof sizes === 'string') {
+                const trimmedSizes = sizes.trim();
+                if (trimmedSizes.length > 0)
+                    sourceEl.sizes = trimmedSizes;
+            }
+            picture.appendChild(sourceEl);
+        }
+        if (picture.childElementCount === 0)
+            return { root: newImg, img: newImg };
+        picture.appendChild(newImg);
+        return { root: picture, img: newImg };
+    };
+    let img;
+    let contentRoot;
+    if (hasSrc) {
+        const built = buildImageContent(staticSrc.trim());
+        contentRoot = built.root;
+        img = built.img;
+        if (!isAltFn)
+            applyAlt(img, staticAlt);
+        el.appendChild(contentRoot);
+    }
+    else {
+        // No valid src — render an empty placeholder to avoid a spurious
+        // network request (setting img.src="" resolves to the document URL).
+        el.classList.add('ui-image-empty');
+    }
+    // Content projection (for overlay content like captions). Anchored after the
+    // image so reactive remounts can insertBefore() to preserve DOM order.
+    const { el: childFragment, destroy } = renderChildren();
+    captureSlot(el, 'default');
+    const childAnchor = document.createComment('');
+    el.appendChild(childAnchor);
+    el.appendChild(childFragment);
+    // Reactive src — handles empty ↔ non-empty transitions by mounting/unmounting
+    // the <img>/<picture>. Static-string src never changes, so we skip the effect.
+    const cleanupSrcEffect = isSrcFn
+        ? effect(() => {
+            const next = readSrc();
+            const trimmed = typeof next === 'string' ? next.trim() : '';
+            if (trimmed.length > 0) {
+                if (img) {
+                    img.src = trimmed;
+                }
+                else {
+                    const built = buildImageContent(trimmed);
+                    contentRoot = built.root;
+                    img = built.img;
+                    applyAlt(img, isAltFn ? readAlt() : staticAlt);
+                    el.classList.remove('ui-image-empty');
+                    el.insertBefore(contentRoot, childAnchor);
+                }
+            }
+            else if (contentRoot) {
+                contentRoot.remove();
+                contentRoot = undefined;
+                img = undefined;
+                el.classList.add('ui-image-empty');
+            }
+        })
+        : undefined;
+    const cleanupAltEffect = isAltFn
+        ? effect(() => {
+            const next = readAlt();
+            if (img)
+                applyAlt(img, next);
+        })
+        : undefined;
+    return {
+        el,
+        destroy: () => {
+            cleanupSrcEffect?.();
+            cleanupAltEffect?.();
+            destroy();
+            el.replaceChildren();
+        },
+    };
+}
+//# sourceMappingURL=Image.js.map

package/dist/atoms/content/image/Image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Image.js","sourceRoot":"","sources":["../../../../src/atoms/content/image/Image.ts"],"names":[],"mappings":"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"}

package/dist/atoms/content/image/image.scss

@@ -0,0 +1,77 @@
+/// Image component styles
+/// Optimized, accessible image rendering with CLS prevention.
+/// Uses design system tokens -- zero raw values.
+///
+/// @group atoms/content
+
+@use '@pithyjs/design-system/a11y/styles/mixins' as a11y;
+
+// ============================================
+// Base wrapper — reserves space, prevents CLS
+// ============================================
+
+.ui-image {
+  // Block element by default for layout control
+  display: block;
+  position: relative;
+  // Prevent overflow from rounded corners or aspect ratio
+  overflow: hidden;
+  // Logical max-width: never exceed container
+  max-inline-size: 100%;
+  // Intrinsic sizing: shrink-to-fit by default
+  inline-size: fit-content;
+
+  &[data-sizing='fill'] {
+    inline-size: 100%;
+  }
+}
+
+// ============================================
+// <img> element — fills the container
+// ============================================
+
+.ui-image-img {
+  // Fill the wrapper completely
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+}
+
+// When aspect ratio is set on the wrapper, img fills it
+.ui-image-aspect-ratio .ui-image-img {
+  // Ensure image fills the entire aspect ratio box
+  object-fit: cover;
+  block-size: 100%;
+}
+
+// ============================================
+// <picture> element — transparent wrapper
+// ============================================
+
+.ui-image-picture {
+  display: contents;
+}
+
+// ============================================
+// High Contrast (forced-colors)
+// ============================================
+
+@include a11y.forced-colors {
+  // In high contrast mode, ensure images remain visible.
+  // Add a thin border so users know an image is present.
+  .ui-image {
+    border: var(--border-width-hairline) solid CanvasText;
+  }
+}
+
+// ============================================
+// Reduced motion — pause CSS animations on images
+// ============================================
+
+@include a11y.motion-reduced {
+  .ui-image-img {
+    // Pause any CSS animations applied to the <img> when reduced motion is requested
+    // Note: this does not stop GIF/APNG playback; it only affects CSS-driven animations
+    animation-play-state: paused;
+  }
+}