@ccheever/exact-renderer 0.1.0

package/src/image-source.ts

@@ -0,0 +1,554 @@
+import { thumbHashToDataURL } from 'thumbhash';
+
+import { isAssetRef } from '@exact/core/assets-fonts-state';
+
+import type {
+  ColorSchemeImageSource,
+  ImageColorScheme,
+  ImageCandidate,
+  ImageLoading,
+  ImagePlaceholder,
+  ImageSource,
+} from './types.js';
+
+const DEFAULT_PLACEHOLDER_COLOR = '#e5e7eb';
+
+export interface DOMResolvedImageSource {
+  readonly pictureSources: ReadonlyArray<{
+    readonly srcSet: string;
+    readonly type?: string;
+  }>;
+  readonly src?: string;
+  readonly srcSet?: string;
+  readonly themeSources?: {
+    readonly light?: string;
+    readonly dark?: string;
+    readonly fallback?: string;
+  };
+}
+
+export interface DOMResolvedImagePlaceholder {
+  readonly backgroundColor?: string;
+  readonly backgroundImage?: string;
+}
+
+export interface ImageWarningInput {
+  readonly alt?: string;
+  readonly decorative?: boolean;
+  readonly source?: ImageSource;
+  readonly testID?: string;
+}
+
+const warnedMissingAlt = new Set<string>();
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object';
+}
+
+function hasNonEmptyStringProperty<Key extends string>(
+  value: unknown,
+  key: Key,
+): value is Record<Key, string> & Record<string, unknown> {
+  return isRecord(value) && typeof value[key] === 'string' && value[key].length > 0;
+}
+
+function getDevicePixelRatio(): number {
+  const value = (globalThis as typeof globalThis & { devicePixelRatio?: unknown }).devicePixelRatio;
+  if (typeof value === 'number' && isFinite(value) && value > 0) {
+    return value;
+  }
+
+  const windowValue = (
+    globalThis as typeof globalThis & { window?: { devicePixelRatio?: unknown } }
+  ).window?.devicePixelRatio;
+  if (typeof windowValue === 'number' && isFinite(windowValue) && windowValue > 0) {
+    return windowValue;
+  }
+
+  const exact = (globalThis as { exact?: { screenScale?: unknown } }).exact;
+  return typeof exact?.screenScale === 'number' && isFinite(exact.screenScale) && exact.screenScale > 0
+    ? exact.screenScale
+    : 1;
+}
+
+function isImageCandidate(value: unknown): value is ImageCandidate {
+  return isRecord(value) && typeof value.uri === 'string' && value.uri.length > 0;
+}
+
+function isImageCandidateArray(source: unknown): source is readonly ImageCandidate[] {
+  return Array.isArray(source) && source.length > 0 && source.every(isImageCandidate);
+}
+
+function isThumbhashSource(source: unknown): source is { thumbhash: string } {
+  return hasNonEmptyStringProperty(source, 'thumbhash');
+}
+
+function isUriSource(
+  source: unknown,
+): source is { uri: string; headers?: Record<string, string>; cacheKey?: string } {
+  return hasNonEmptyStringProperty(source, 'uri');
+}
+
+export function isColorSchemeImageSource(source: unknown): source is ColorSchemeImageSource {
+  if (!isRecord(source) || isUriSource(source) || isThumbhashSource(source)) {
+    return false;
+  }
+
+  return (
+    'light' in source ||
+    'dark' in source ||
+    'fallback' in source
+  );
+}
+
+function describeImageSource(source: ImageSource | undefined): string {
+  if (source == null) {
+    return 'unknown';
+  }
+
+  if (typeof source === 'string') {
+    return source;
+  }
+
+  if (typeof source === 'number') {
+    return `numeric:${source}`;
+  }
+
+  if (isAssetRef(source)) {
+    return source.url;
+  }
+
+  if (isImageCandidateArray(source)) {
+    return source.map((candidate) => candidate.uri).join('|');
+  }
+
+  if (isColorSchemeImageSource(source)) {
+    return [
+      source.light ? `light:${describeImageSource(source.light)}` : '',
+      source.dark ? `dark:${describeImageSource(source.dark)}` : '',
+      source.fallback ? `fallback:${describeImageSource(source.fallback)}` : '',
+    ].filter(Boolean).join('|') || 'color-scheme';
+  }
+
+  if (isThumbhashSource(source)) {
+    return 'thumbhash';
+  }
+
+  if (isUriSource(source)) {
+    return source.uri;
+  }
+
+  return 'unknown';
+}
+
+function formatSrcSetDescriptor(candidate: ImageCandidate): string {
+  if (typeof candidate.width === 'number' && isFinite(candidate.width) && candidate.width > 0) {
+    return `${candidate.width}w`;
+  }
+
+  if (
+    typeof candidate.pixelDensity === 'number' &&
+    isFinite(candidate.pixelDensity) &&
+    candidate.pixelDensity > 0
+  ) {
+    return `${candidate.pixelDensity}x`;
+  }
+
+  return '';
+}
+
+function buildSrcSet(candidates: readonly ImageCandidate[]): string {
+  return candidates
+    .map((candidate) => {
+      const descriptor = formatSrcSetDescriptor(candidate);
+      return descriptor.length > 0 ? `${candidate.uri} ${descriptor}` : candidate.uri;
+    })
+    .join(', ');
+}
+
+function formatPreferenceScore(type: string | undefined): number {
+  switch ((type ?? '').toLowerCase()) {
+    case 'image/avif':
+      return 0;
+    case 'image/webp':
+      return 1;
+    case 'image/png':
+      return 2;
+    case 'image/jpeg':
+    case 'image/jpg':
+      return 3;
+    default:
+      return 4;
+  }
+}
+
+/** True when every candidate declares `width` and none declare `pixelDensity` (width-bucket lists). */
+function isWidthBucketCandidateList(candidates: readonly ImageCandidate[]): boolean {
+  if (candidates.length === 0) {
+    return false;
+  }
+
+  for (const candidate of candidates) {
+    if (typeof candidate.pixelDensity === 'number' && isFinite(candidate.pixelDensity)) {
+      return false;
+    }
+
+    if (!(typeof candidate.width === 'number' && isFinite(candidate.width) && candidate.width > 0)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Rough content width in CSS points for responsive image picks on native (full-width column heuristic).
+ */
+function estimateViewportContentWidthPoints(): number {
+  const exact = (globalThis as { exact?: { screenWidth?: number } }).exact;
+  if (typeof exact?.screenWidth === 'number' && isFinite(exact.screenWidth) && exact.screenWidth > 0) {
+    return Math.max(120, exact.screenWidth - 96);
+  }
+
+  return 390;
+}
+
+/**
+ * Pick the smallest variant whose pixel width still covers the requested decode width, else the largest.
+ */
+function pickBestWidthBucketCandidate(
+  candidates: readonly ImageCandidate[],
+  targetPixelWidth: number,
+): ImageCandidate {
+  const sorted = [...candidates].sort((a, b) => (a.width ?? 0) - (b.width ?? 0));
+  for (const c of sorted) {
+    const w = c.width ?? 0;
+    if (w >= targetPixelWidth) {
+      return c;
+    }
+  }
+
+  return sorted[sorted.length - 1] ?? candidates[0];
+}
+
+function pickBestImageCandidate(
+  candidates: readonly ImageCandidate[],
+  pixelRatio: number = getDevicePixelRatio(),
+): ImageCandidate {
+  if (isWidthBucketCandidateList(candidates)) {
+    const targetPx = Math.ceil(estimateViewportContentWidthPoints() * pixelRatio);
+    return pickBestWidthBucketCandidate(candidates, targetPx);
+  }
+
+  let best = candidates[0];
+  let bestScore = Number.POSITIVE_INFINITY;
+
+  for (const candidate of candidates) {
+    const density = typeof candidate.pixelDensity === 'number' && isFinite(candidate.pixelDensity)
+      ? candidate.pixelDensity
+      : 1;
+    const densityScore = Math.abs(density - pixelRatio);
+    const typeScore = formatPreferenceScore(candidate.type);
+    const widthScore =
+      typeof candidate.width === 'number' && isFinite(candidate.width)
+        ? -candidate.width / 100000
+        : 0;
+    const score = densityScore * 10 + typeScore + widthScore;
+
+    if (score < bestScore) {
+      best = candidate;
+      bestScore = score;
+    }
+  }
+
+  return best;
+}
+
+function decodeThumbHashBase64ToBytes(encoded: string): Uint8Array {
+  const normalized = encoded.trim();
+  if (normalized.length === 0) {
+    throw new Error('empty thumbhash');
+  }
+
+  if (typeof Buffer !== 'undefined') {
+    return Uint8Array.from(Buffer.from(normalized, 'base64'));
+  }
+
+  const binary = atob(normalized);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    out[i] = binary.charCodeAt(i);
+  }
+  return out;
+}
+
+/** Decodes a standard base64-encoded ThumbHash string to a PNG data URL (web / SSR). */
+export function thumbhashStringToDataUrl(hash: string): string | undefined {
+  try {
+    return thumbHashToDataURL(decodeThumbHashBase64ToBytes(hash));
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveUrlLikeImageSource(source: ImageSource): string | undefined {
+  if (typeof source === 'string' && source.length > 0) {
+    return source;
+  }
+
+  if (isAssetRef(source)) {
+    return source.url;
+  }
+
+  if (isUriSource(source)) {
+    return source.uri;
+  }
+
+  return undefined;
+}
+
+export function getRuntimeImageColorScheme(): ImageColorScheme {
+  const documentValue = readDocumentColorScheme();
+  if (documentValue) {
+    return documentValue;
+  }
+
+  const themeValue = readExactThemeColorScheme();
+  if (themeValue) {
+    return themeValue;
+  }
+
+  return 'light';
+}
+
+function readDocumentColorScheme(): ImageColorScheme | undefined {
+  const doc = (globalThis as { document?: { documentElement?: { getAttribute?: (name: string) => string | null } } }).document;
+  const root = doc?.documentElement;
+  if (!root || typeof root.getAttribute !== 'function') {
+    return undefined;
+  }
+
+  for (const attr of ['data-exact-color-scheme', 'data-blog-appearance']) {
+    const value = root.getAttribute(attr);
+    if (value === 'light' || value === 'dark') {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+function readExactThemeColorScheme(): ImageColorScheme | undefined {
+  const state = (globalThis as {
+    __exactExperienceRegistryState?: {
+      theme?: {
+        scheme?: unknown;
+      } | null;
+    };
+  }).__exactExperienceRegistryState;
+  const scheme = state?.theme?.scheme;
+  return scheme === 'light' || scheme === 'dark' ? scheme : undefined;
+}
+
+export function resolveThemeAwareImageSource(
+  source: ImageSource | undefined,
+  scheme: ImageColorScheme = getRuntimeImageColorScheme(),
+): ImageSource | undefined {
+  if (!isColorSchemeImageSource(source)) {
+    return source;
+  }
+
+  const selected = source[scheme] ?? source.fallback ?? source.light ?? source.dark;
+  return resolveThemeAwareImageSource(selected, scheme);
+}
+
+export function resolveImageSourceForNative(
+  source: ImageSource | undefined,
+  scheme: ImageColorScheme = getRuntimeImageColorScheme(),
+): string | undefined {
+  if (source == null) {
+    return undefined;
+  }
+
+  if (isColorSchemeImageSource(source)) {
+    return resolveImageSourceForNative(resolveThemeAwareImageSource(source, scheme), scheme);
+  }
+
+  if (typeof source === 'number') {
+    if (process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test') {
+      console.warn('[Exact] Numeric image sources are not supported. Use asset(...) instead.');
+    }
+    return undefined;
+  }
+
+  if (isImageCandidateArray(source)) {
+    return resolveImageSourceForNative(pickBestImageCandidate(source), scheme);
+  }
+
+  if (isThumbhashSource(source)) {
+    return thumbhashStringToDataUrl(source.thumbhash);
+  }
+
+  return resolveUrlLikeImageSource(source);
+}
+
+export function resolveImagePlaceholderForNative(
+  placeholder: ImagePlaceholder | undefined,
+): string | undefined {
+  if (placeholder == null) {
+    return undefined;
+  }
+
+  if (hasNonEmptyStringProperty(placeholder, 'color')) {
+    return `color:${placeholder.color}`;
+  }
+
+  return resolveImageSourceForNative(placeholder as ImageSource);
+}
+
+export function resolveImageSourceForDOM(
+  source: ImageSource | undefined,
+  scheme: ImageColorScheme = getRuntimeImageColorScheme(),
+): DOMResolvedImageSource | undefined {
+  if (source == null || typeof source === 'number') {
+    return undefined;
+  }
+
+  if (isColorSchemeImageSource(source)) {
+    const selected = resolveThemeAwareImageSource(source, scheme);
+    const resolved = resolveImageSourceForDOM(selected, scheme);
+    const light = source.light ? resolveImageSourceForNative(source.light, 'light') : undefined;
+    const dark = source.dark ? resolveImageSourceForNative(source.dark, 'dark') : undefined;
+    const fallback = source.fallback ? resolveImageSourceForNative(source.fallback, scheme) : undefined;
+    if (!resolved) {
+      return undefined;
+    }
+    return {
+      ...resolved,
+      themeSources: {
+        ...(light ? { light } : {}),
+        ...(dark ? { dark } : {}),
+        ...(fallback ? { fallback } : {}),
+      },
+    };
+  }
+
+  if (isThumbhashSource(source)) {
+    const dataUrl = thumbhashStringToDataUrl(source.thumbhash);
+    if (dataUrl == null || dataUrl.length === 0) {
+      return undefined;
+    }
+
+    return {
+      pictureSources: [],
+      src: dataUrl,
+    };
+  }
+
+  if (isImageCandidateArray(source)) {
+    const groupedByType = new Map<string, ImageCandidate[]>();
+    const fallbackCandidates: ImageCandidate[] = [];
+
+    for (const candidate of source) {
+      if (typeof candidate.type === 'string' && candidate.type.length > 0) {
+        const existing = groupedByType.get(candidate.type) ?? [];
+        existing.push(candidate);
+        groupedByType.set(candidate.type, existing);
+      } else {
+        fallbackCandidates.push(candidate);
+      }
+    }
+
+    const pictureSources = Array.from(groupedByType.entries())
+      .sort(([typeA], [typeB]) => formatPreferenceScore(typeA) - formatPreferenceScore(typeB))
+      .map(([type, candidates]) => ({
+        type,
+        srcSet: buildSrcSet(candidates),
+      }));
+    const fallback = fallbackCandidates.length > 0 ? fallbackCandidates : source;
+
+    return {
+      pictureSources,
+      src: pickBestImageCandidate(source).uri,
+      srcSet: fallback.length > 1 ? buildSrcSet(fallback) : undefined,
+    };
+  }
+
+  const src = resolveUrlLikeImageSource(source);
+  if (!src) {
+    return undefined;
+  }
+
+  return {
+    pictureSources: [],
+    src,
+  };
+}
+
+export function resolveImagePlaceholderForDOM(
+  placeholder: ImagePlaceholder | undefined,
+): DOMResolvedImagePlaceholder | undefined {
+  if (placeholder == null) {
+    return undefined;
+  }
+
+  if (hasNonEmptyStringProperty(placeholder, 'color')) {
+    return {
+      backgroundColor: placeholder.color,
+    };
+  }
+
+  if (isThumbhashSource(placeholder)) {
+    const dataUrl = thumbhashStringToDataUrl(placeholder.thumbhash);
+    if (dataUrl != null && dataUrl.length > 0) {
+      return {
+        backgroundImage: `url("${dataUrl.replace(/"/g, '\\"')}")`,
+      };
+    }
+
+    return {
+      backgroundColor: DEFAULT_PLACEHOLDER_COLOR,
+    };
+  }
+
+  const resolved = resolveImageSourceForDOM(placeholder as ImageSource);
+  if (!resolved?.src) {
+    return undefined;
+  }
+
+  return {
+    backgroundImage: `url("${resolved.src.replace(/"/g, '\\"')}")`,
+  };
+}
+
+export function normalizeImageLoading(loading: ImageLoading | undefined): 'eager' | 'lazy' | undefined {
+  if (loading === 'eager' || loading === 'lazy') {
+    return loading;
+  }
+
+  return undefined;
+}
+
+export function warnIfImageMissingAlt({
+  alt,
+  decorative,
+  source,
+  testID,
+}: ImageWarningInput): void {
+  if (
+    process.env.NODE_ENV === 'production' ||
+    process.env.NODE_ENV === 'test' ||
+    decorative ||
+    alt !== undefined
+  ) {
+    return;
+  }
+
+  const signature = `${testID ?? 'no-testid'}:${describeImageSource(source)}`;
+  if (warnedMissingAlt.has(signature)) {
+    return;
+  }
+
+  warnedMissingAlt.add(signature);
+  console.warn('[Exact] <Image> is missing alt text. Provide alt="..." or set decorative.');
+}