@ankhorage/zora 1.0.10 → 1.1.0

package/src/patterns/image-preview/types.ts

@@ -0,0 +1,41 @@
+import type React from 'react';
+
+import type { ImageFit } from '../../components/image';
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface ZoraImageMetadata {
+  fileName?: string;
+  sizeBytes?: number;
+  createdAt?: string;
+}
+
+export type ZoraImageAsset =
+  | {
+      kind: 'url';
+      url: string;
+      alt?: string;
+      width?: number;
+      height?: number;
+      contentType?: string;
+      metadata?: ZoraImageMetadata;
+    }
+  | {
+      kind: 'storage';
+      storageId?: string;
+      bucket: string;
+      path: string;
+      publicUrl?: string;
+      alt?: string;
+      width?: number;
+      height?: number;
+      contentType?: string;
+      metadata?: ZoraImageMetadata;
+    };
+
+export interface ImagePreviewProps extends ZoraBaseProps {
+  asset?: ZoraImageAsset | null;
+  aspectRatio?: number;
+  fit?: ImageFit;
+  emptyTitle?: React.ReactNode;
+  emptyDescription?: React.ReactNode;
+}

package/src/patterns/image-upload-field/ImageUploadField.tsx

@@ -0,0 +1,293 @@
+import React from 'react';
+
+import { Button } from '../../components/button';
+import { Modal } from '../../components/modal';
+import { Progress } from '../../components/progress';
+import { Text } from '../../components/text';
+import { Box, Stack } from '../../foundation';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { FormField } from '../form-field';
+import { ImagePreview } from '../image-preview';
+import type { ImageUploadFieldProps } from './types';
+import {
+  createOptimisticAssetFromPicked,
+  formatAcceptHint,
+  formatMaxSizeHint,
+  resolveRenderableUrl,
+  validatePickedImage,
+} from './uploadFlow';
+
+function clampProgress(value: number | null): number | null {
+  if (value === null) return null;
+  if (!Number.isFinite(value)) return null;
+  return Math.max(0, Math.min(1, value));
+}
+
+function formatUnknownError(error: unknown): string {
+  if (error instanceof Error && error.message) return error.message;
+  if (typeof error === 'string' && error.trim().length > 0) return error;
+  return 'Something went wrong.';
+}
+
+function ImageUploadFieldInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  value,
+  onChange,
+  label,
+  description,
+  helperText,
+  errorText,
+  required,
+  disabled = false,
+  readOnly = false,
+  accept,
+  maxSizeBytes,
+  validatePicked,
+  onPick,
+  onUpload,
+  onRemove,
+  aspectRatio = 1,
+  previewTitle = 'Image preview',
+  previewDescription,
+}: ImageUploadFieldProps) {
+  const [internalError, setInternalError] = React.useState<string | undefined>(undefined);
+  const [uploading, setUploading] = React.useState(false);
+  const [removing, setRemoving] = React.useState(false);
+  const [progress, setProgress] = React.useState<number | null>(null);
+  const [previewOpen, setPreviewOpen] = React.useState(false);
+  const isMountedRef = React.useRef(true);
+
+  React.useEffect(() => {
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  const renderableUrl = resolveRenderableUrl(value);
+  const isRenderable = renderableUrl !== null;
+  const actionsDisabled = disabled || readOnly;
+
+  const effectiveError = errorText ?? internalError;
+  const invalid = Boolean(effectiveError);
+
+  const acceptHint = formatAcceptHint(accept);
+  const maxSizeHint = formatMaxSizeHint(maxSizeBytes);
+
+  const setProgressSafe = React.useCallback((next: number | null) => {
+    if (!isMountedRef.current) return;
+    setProgress(clampProgress(next));
+  }, []);
+
+  const clearTransientState = React.useCallback(() => {
+    if (!isMountedRef.current) return;
+    setUploading(false);
+    setRemoving(false);
+    setProgress(null);
+  }, []);
+
+  const handleReplace = React.useCallback(async () => {
+    if (actionsDisabled || uploading || removing) return;
+
+    setInternalError(undefined);
+    let picked;
+    try {
+      picked = await onPick();
+    } catch (error) {
+      if (!isMountedRef.current) return;
+      setInternalError(formatUnknownError(error));
+      return;
+    }
+    if (!picked) return;
+
+    const validationError = validatePickedImage({
+      picked,
+      accept,
+      maxSizeBytes,
+      validatePicked,
+    });
+
+    if (validationError) {
+      setInternalError(validationError);
+      return;
+    }
+
+    if (!onUpload) {
+      onChange(createOptimisticAssetFromPicked(picked));
+      return;
+    }
+
+    const optimisticAsset = createOptimisticAssetFromPicked(picked);
+    onChange(optimisticAsset);
+    setUploading(true);
+    setProgressSafe(0);
+
+    try {
+      const uploaded = await onUpload(picked, { setProgress: setProgressSafe });
+      if (!isMountedRef.current) return;
+      onChange(uploaded);
+      setInternalError(undefined);
+      clearTransientState();
+    } catch (error) {
+      if (!isMountedRef.current) return;
+      setInternalError(formatUnknownError(error));
+      setUploading(false);
+      setProgress(null);
+    }
+  }, [
+    accept,
+    actionsDisabled,
+    clearTransientState,
+    maxSizeBytes,
+    onChange,
+    onPick,
+    onUpload,
+    removing,
+    setProgressSafe,
+    uploading,
+    validatePicked,
+  ]);
+
+  const handleRemove = React.useCallback(async () => {
+    if (actionsDisabled || uploading || removing) return;
+    if (!value) {
+      onChange(null);
+      return;
+    }
+
+    setInternalError(undefined);
+
+    if (!onRemove) {
+      onChange(null);
+      return;
+    }
+
+    setRemoving(true);
+    try {
+      await onRemove(value);
+      if (!isMountedRef.current) return;
+      onChange(null);
+      setRemoving(false);
+    } catch (error) {
+      if (!isMountedRef.current) return;
+      setInternalError(formatUnknownError(error));
+      setRemoving(false);
+    }
+  }, [actionsDisabled, onChange, onRemove, removing, uploading, value]);
+
+  const handlePreview = React.useCallback(() => {
+    if (!isRenderable) return;
+    setPreviewOpen(true);
+  }, [isRenderable]);
+
+  const closePreview = React.useCallback(() => setPreviewOpen(false), []);
+
+  return (
+    <>
+      <FormField
+        description={description}
+        disabled={disabled}
+        errorText={effectiveError}
+        helperText={helperText}
+        invalid={invalid}
+        label={label}
+        readOnly={readOnly}
+        required={required}
+        testID={testID}
+      >
+        <Stack gap="m">
+          <ImagePreview
+            aspectRatio={aspectRatio}
+            asset={value}
+            emptyDescription={actionsDisabled ? 'No image available.' : undefined}
+          />
+
+          {acceptHint || maxSizeHint ? (
+            <Stack gap="xs">
+              {acceptHint ? (
+                <Text tone="muted" variant="caption">
+                  {acceptHint}
+                </Text>
+              ) : null}
+              {maxSizeHint ? (
+                <Text tone="muted" variant="caption">
+                  {maxSizeHint}
+                </Text>
+              ) : null}
+            </Stack>
+          ) : null}
+
+          {uploading ? (
+            <Stack gap="xs">
+              <Text tone="muted" variant="caption">
+                Uploading…
+              </Text>
+              {progress !== null ? <Progress max={1} value={progress} /> : null}
+            </Stack>
+          ) : null}
+
+          <Stack direction={{ base: 'column', md: 'row' }} gap="s">
+            <Button
+              disabled={actionsDisabled || uploading || removing}
+              onPress={() => {
+                void handleReplace();
+              }}
+            >
+              {value ? 'Replace image' : 'Select image'}
+            </Button>
+
+            {value ? (
+              <Button
+                disabled={actionsDisabled || uploading || removing}
+                emphasis="outline"
+                loading={removing}
+                tone="danger"
+                onPress={() => {
+                  void handleRemove();
+                }}
+              >
+                Remove
+              </Button>
+            ) : null}
+
+            {isRenderable ? (
+              <Button disabled={false} emphasis="soft" tone="neutral" onPress={handlePreview}>
+                Preview
+              </Button>
+            ) : null}
+          </Stack>
+
+          {!isRenderable && value?.kind === 'storage' && value.publicUrl === undefined ? (
+            <Box>
+              <Text tone="muted" variant="caption">
+                This image is stored, but no preview URL is available yet.
+              </Text>
+            </Box>
+          ) : null}
+        </Stack>
+      </FormField>
+
+      {isRenderable ? (
+        <Modal
+          closeOnBackdrop
+          description={previewDescription}
+          title={previewTitle}
+          visible={previewOpen}
+          onDismiss={closePreview}
+        >
+          <Stack gap="m">
+            <ImagePreview asset={value} aspectRatio={aspectRatio} />
+            <Stack direction="row" justify="flex-end">
+              <Button emphasis="soft" tone="neutral" onPress={closePreview}>
+                Close
+              </Button>
+            </Stack>
+          </Stack>
+        </Modal>
+      ) : null}
+    </>
+  );
+}
+
+export const ImageUploadField = withZoraThemeScope(ImageUploadFieldInner);

package/src/patterns/image-upload-field/index.ts

@@ -0,0 +1,2 @@
+export { ImageUploadField } from './ImageUploadField';
+export type { ImageUploadFieldProps, ImageUploadProgressContext, ZoraPickedImage } from './types';

package/src/patterns/image-upload-field/types.ts

@@ -0,0 +1,41 @@
+import type React from 'react';
+
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+import type { ZoraImageAsset } from '../image-preview';
+
+export interface ZoraPickedImage {
+  uri: string;
+  fileName?: string;
+  sizeBytes?: number;
+  contentType?: string;
+  width?: number;
+  height?: number;
+}
+
+export interface ImageUploadProgressContext {
+  setProgress: (progress: number | null) => void;
+}
+
+export interface ImageUploadFieldProps extends ZoraBaseProps {
+  value: ZoraImageAsset | null;
+  onChange: (next: ZoraImageAsset | null) => void;
+  label: React.ReactNode;
+  description?: React.ReactNode;
+  helperText?: React.ReactNode;
+  errorText?: React.ReactNode;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  accept?: string;
+  maxSizeBytes?: number;
+  validatePicked?: (picked: ZoraPickedImage) => string | undefined;
+  onPick: () => Promise<ZoraPickedImage | null>;
+  onUpload?: (
+    picked: ZoraPickedImage,
+    context: ImageUploadProgressContext,
+  ) => Promise<ZoraImageAsset>;
+  onRemove?: (current: ZoraImageAsset) => void | Promise<void>;
+  aspectRatio?: number;
+  previewTitle?: React.ReactNode;
+  previewDescription?: React.ReactNode;
+}

package/src/patterns/image-upload-field/uploadFlow.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraPickedImage } from './types';
+import {
+  createOptimisticAssetFromPicked,
+  formatAcceptHint,
+  formatMaxSizeHint,
+  isAccepted,
+  resolveRenderableUrl,
+  validatePickedImage,
+} from './uploadFlow';
+
+describe('uploadFlow', () => {
+  test('formatAcceptHint returns null for empty input', () => {
+    expect(formatAcceptHint(undefined)).toBeNull();
+    expect(formatAcceptHint('')).toBeNull();
+    expect(formatAcceptHint('   ')).toBeNull();
+  });
+
+  test('formatMaxSizeHint returns null for invalid sizes', () => {
+    expect(formatMaxSizeHint(undefined)).toBeNull();
+    expect(formatMaxSizeHint(0)).toBeNull();
+    expect(formatMaxSizeHint(-5)).toBeNull();
+  });
+
+  test('isAccepted supports wildcard image/* matching', () => {
+    expect(isAccepted({ accept: 'image/*', contentType: 'image/png', fileName: undefined })).toBe(
+      true,
+    );
+    expect(
+      isAccepted({ accept: 'image/*', contentType: 'application/json', fileName: undefined }),
+    ).toBe(false);
+  });
+
+  test('isAccepted supports exact MIME matching', () => {
+    expect(isAccepted({ accept: 'image/png', contentType: 'image/png', fileName: undefined })).toBe(
+      true,
+    );
+    expect(
+      isAccepted({ accept: 'image/png', contentType: 'image/jpeg', fileName: undefined }),
+    ).toBe(false);
+  });
+
+  test('isAccepted supports extension matching', () => {
+    expect(isAccepted({ accept: '.png', contentType: undefined, fileName: 'photo.png' })).toBe(
+      true,
+    );
+    expect(isAccepted({ accept: '.png', contentType: undefined, fileName: 'photo.jpg' })).toBe(
+      false,
+    );
+  });
+
+  test('isAccepted does not block when it cannot validate', () => {
+    expect(isAccepted({ accept: 'image/*', contentType: undefined, fileName: undefined })).toBe(
+      true,
+    );
+  });
+
+  test('validatePickedImage rejects by accept when metadata allows checking', () => {
+    const picked: ZoraPickedImage = { uri: 'file://a', contentType: 'application/json' };
+    expect(
+      validatePickedImage({
+        picked,
+        accept: 'image/*',
+        maxSizeBytes: undefined,
+        validatePicked: undefined,
+      }),
+    ).toContain('File type not accepted');
+  });
+
+  test('validatePickedImage rejects oversize files when sizeBytes is present', () => {
+    const picked: ZoraPickedImage = { uri: 'file://a', sizeBytes: 2_000, contentType: 'image/png' };
+    const error = validatePickedImage({
+      picked,
+      accept: 'image/*',
+      maxSizeBytes: 1_000,
+      validatePicked: undefined,
+    });
+    expect(error).toContain('File is too large');
+  });
+
+  test('validatePickedImage allows oversize when sizeBytes is missing', () => {
+    const picked: ZoraPickedImage = { uri: 'file://a', contentType: 'image/png' };
+    expect(
+      validatePickedImage({
+        picked,
+        accept: 'image/*',
+        maxSizeBytes: 1_000,
+        validatePicked: undefined,
+      }),
+    ).toBeUndefined();
+  });
+
+  test('createOptimisticAssetFromPicked maps uri and metadata correctly', () => {
+    const picked: ZoraPickedImage = {
+      uri: 'file://picked',
+      fileName: 'picked.png',
+      sizeBytes: 123,
+      contentType: 'image/png',
+    };
+    const asset = createOptimisticAssetFromPicked(picked);
+    expect(asset.kind).toBe('url');
+    expect(asset.url).toBe('file://picked');
+    expect(asset.contentType).toBe('image/png');
+    expect(asset.metadata?.fileName).toBe('picked.png');
+    expect(asset.metadata?.sizeBytes).toBe(123);
+  });
+
+  test('resolveRenderableUrl renders url assets directly and storage only with publicUrl', () => {
+    expect(resolveRenderableUrl(null)).toBeNull();
+    expect(resolveRenderableUrl({ kind: 'url', url: 'https://x' })).toBe('https://x');
+    expect(resolveRenderableUrl({ kind: 'storage', bucket: 'b', path: 'p' })).toBeNull();
+    expect(
+      resolveRenderableUrl({ kind: 'storage', bucket: 'b', path: 'p', publicUrl: 'https://y' }),
+    ).toBe('https://y');
+  });
+});

package/src/patterns/image-upload-field/uploadFlow.ts

@@ -0,0 +1,145 @@
+import type { ZoraImageAsset } from '../image-preview';
+import type { ZoraPickedImage } from './types';
+
+function parseAccept(accept: string | undefined): readonly string[] {
+  if (!accept) return [];
+
+  return accept
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function matchesAcceptToken({
+  token,
+  contentType,
+  fileName,
+}: {
+  token: string;
+  contentType: string | undefined;
+  fileName: string | undefined;
+}): boolean | null {
+  const normalizedToken = token.toLowerCase();
+  const normalizedContentType = contentType?.toLowerCase();
+  const normalizedFileName = fileName?.toLowerCase();
+
+  if (normalizedToken.startsWith('.')) {
+    if (!normalizedFileName) return null;
+    return normalizedFileName.endsWith(normalizedToken);
+  }
+
+  if (normalizedToken.endsWith('/*')) {
+    if (!normalizedContentType) return null;
+    const prefix = normalizedToken.slice(0, Math.max(0, normalizedToken.length - 1));
+    return normalizedContentType.startsWith(prefix);
+  }
+
+  if (!normalizedContentType) return null;
+  return normalizedContentType === normalizedToken;
+}
+
+export function isAccepted({
+  accept,
+  contentType,
+  fileName,
+}: {
+  accept: string | undefined;
+  contentType: string | undefined;
+  fileName: string | undefined;
+}): boolean {
+  const tokens = parseAccept(accept);
+  if (tokens.length === 0) return true;
+
+  let hadSignal = false;
+
+  for (const token of tokens) {
+    const matches = matchesAcceptToken({ token, contentType, fileName });
+    if (matches === null) {
+      continue;
+    }
+
+    hadSignal = true;
+    if (matches) return true;
+  }
+
+  // If we cannot validate due to missing metadata, do not block.
+  return !hadSignal;
+}
+
+function formatBytes(value: number): string {
+  if (!Number.isFinite(value) || value <= 0) return '0 B';
+
+  const units = ['B', 'KB', 'MB', 'GB'] as const;
+  let size = value;
+  let unitIndex = 0;
+
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex += 1;
+  }
+
+  const unit = units[unitIndex] ?? 'B';
+  const rounded = unitIndex === 0 ? Math.round(size) : Math.round(size * 10) / 10;
+  return `${rounded} ${unit}`;
+}
+
+export function formatAcceptHint(accept: string | undefined): string | null {
+  const tokens = parseAccept(accept);
+  if (tokens.length === 0) return null;
+  return `Accepted: ${tokens.join(', ')}`;
+}
+
+export function formatMaxSizeHint(maxSizeBytes: number | undefined): string | null {
+  if (maxSizeBytes === undefined) return null;
+  if (!Number.isFinite(maxSizeBytes) || maxSizeBytes <= 0) return null;
+  return `Max size: ${formatBytes(maxSizeBytes)}`;
+}
+
+export function createOptimisticAssetFromPicked(picked: ZoraPickedImage): ZoraImageAsset {
+  return {
+    kind: 'url',
+    url: picked.uri,
+    width: picked.width,
+    height: picked.height,
+    contentType: picked.contentType,
+    metadata: {
+      fileName: picked.fileName,
+      sizeBytes: picked.sizeBytes,
+    },
+  };
+}
+
+export function resolveRenderableUrl(asset: ZoraImageAsset | null): string | null {
+  if (!asset) return null;
+  if (asset.kind === 'url') return asset.url;
+  return asset.publicUrl ?? null;
+}
+
+export function validatePickedImage({
+  picked,
+  accept,
+  maxSizeBytes,
+  validatePicked,
+}: {
+  picked: ZoraPickedImage;
+  accept: string | undefined;
+  maxSizeBytes: number | undefined;
+  validatePicked: ((picked: ZoraPickedImage) => string | undefined) | undefined;
+}): string | undefined {
+  if (!isAccepted({ accept, contentType: picked.contentType, fileName: picked.fileName })) {
+    return accept ? `File type not accepted. Expected ${accept}.` : 'File type not accepted.';
+  }
+
+  if (
+    maxSizeBytes !== undefined &&
+    Number.isFinite(maxSizeBytes) &&
+    maxSizeBytes > 0 &&
+    picked.sizeBytes !== undefined &&
+    Number.isFinite(picked.sizeBytes) &&
+    picked.sizeBytes > maxSizeBytes
+  ) {
+    return `File is too large (${formatBytes(picked.sizeBytes)}). Max ${formatBytes(maxSizeBytes)}.`;
+  }
+
+  return validatePicked?.(picked);
+}

package/src/showcaseCoverage.test.ts

@@ -34,6 +34,7 @@ const REQUIRED_SHOWCASE_COVERAGE = {
     'Heading',
     'Icon',
     'IconButton',
+    'Image',
     'Input',
     'MediaCard',
     'MetricCard',
@@ -88,6 +89,8 @@ const REQUIRED_SHOWCASE_COVERAGE = {
     'ListRow',
     'ListSection',
     'InspectorField',
+    'ImagePreview',
+    'ImageUploadField',
     'Notice',
     'Panel',
     'ResponsivePanel',