@ankhorage/zora 6.0.0 → 8.0.0

package/src/features/uploader/adapters/inbound/Uploader.tsx

@@ -0,0 +1,438 @@
+import React from 'react';
+
+import { Modal } from '../../../../components/modal';
+import { Progress } from '../../../../components/progress';
+import { FormField } from '../../../../patterns/form-field';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { UploadAsset, UploaderProps, UploadType } from '../../../../types/upload';
+import { Button } from '../../../button/public';
+import { Icon } from '../../../icon/public';
+import { Image } from '../../../image/public';
+import { Box, Stack } from '../../../layout/public';
+import { Text } from '../../../typography/public';
+import { validateUploadAsset } from '../../application/use-cases/validateUploadAsset';
+import { createUploadPicker } from '../../composition/createUploadPicker';
+
+/*** Picks, validates, uploads, previews, and removes one generic file asset. */
+export const Uploader = withZoraThemeScope(UploaderInner);
+
+/*** Owns the interactive state for the generic uploader inbound adapter. */
+function UploaderInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  value = null,
+  onChange,
+  onValueChange,
+  onUploadRequest,
+  onRemoveRequest,
+  onValidationError,
+  uploadState = 'idle',
+  uploadProgress,
+  label = 'File',
+  description,
+  helperText,
+  errorText,
+  type = 'file',
+  accept,
+  maxSizeBytes,
+  required,
+  disabled = false,
+  readOnly = false,
+  validatePicked,
+  onUpload,
+  onRemove,
+  aspectRatio = 1,
+  interactionPolicy,
+}: UploaderProps) {
+  const passive = interactionPolicy === 'passive';
+  const picker = React.useMemo(() => createUploadPicker(), []);
+  const [internalError, setInternalError] = React.useState<string | undefined>();
+  const [internalUploading, setUploading] = React.useState(false);
+  const [internalRemoving, setRemoving] = React.useState(false);
+  const uploading = internalUploading || uploadState === 'uploading';
+  const removing = internalRemoving || uploadState === 'removing';
+  const [progress, setProgress] = React.useState<number | null>(null);
+  const [previewOpen, setPreviewOpen] = React.useState(false);
+  const mountedRef = React.useRef<boolean | null>(null);
+  const resolvedAccept = resolveUploadAccept(type, accept);
+  const actionsDisabled = disabled || readOnly;
+  const effectiveError = errorText ?? internalError;
+  const notifyValue = React.useCallback(
+    (next: UploadAsset | null) => {
+      onChange?.(next);
+      onValueChange?.(next);
+    },
+    [onChange, onValueChange],
+  );
+
+  React.useEffect(() => {
+    mountedRef.current = true;
+
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const isMounted = React.useCallback(() => mountedRef.current === true, []);
+
+  const setProgressSafe = React.useCallback(
+    (next: number | null) => {
+      if (!isMounted()) {
+        return;
+      }
+
+      setProgress(clampProgress(next));
+    },
+    [isMounted],
+  );
+
+  const handlePick = React.useCallback(async () => {
+    if (passive || actionsDisabled || uploading || removing) {
+      return;
+    }
+
+    setInternalError(undefined);
+
+    try {
+      const picked = await picker.pickAsync({ accept: resolvedAccept, type });
+      if (!picked || !isMounted()) {
+        return;
+      }
+
+      const validationError = validateUploadAsset({
+        accept: resolvedAccept,
+        asset: picked,
+        maxSizeBytes,
+        validate: validatePicked,
+      });
+      if (validationError) {
+        setInternalError(validationError);
+        onValidationError?.({ message: validationError });
+        return;
+      }
+
+      notifyValue(picked);
+      onUploadRequest?.({ asset: picked });
+      if (!onUpload) {
+        return;
+      }
+
+      setUploading(true);
+      setProgressSafe(0);
+
+      try {
+        const uploaded = await onUpload(picked, { setProgress: setProgressSafe });
+        if (!isMounted()) {
+          return;
+        }
+
+        notifyValue(uploaded);
+        setUploading(false);
+        setProgress(null);
+      } catch (error) {
+        if (!isMounted()) {
+          return;
+        }
+
+        setInternalError(formatUnknownError(error));
+        setUploading(false);
+        setProgress(null);
+      }
+    } catch (error) {
+      if (isMounted()) {
+        setInternalError(formatUnknownError(error));
+      }
+    }
+  }, [
+    actionsDisabled,
+    isMounted,
+    maxSizeBytes,
+    notifyValue,
+    onUploadRequest,
+    onValidationError,
+    onUpload,
+    passive,
+    picker,
+    removing,
+    resolvedAccept,
+    setProgressSafe,
+    type,
+    uploading,
+    validatePicked,
+  ]);
+
+  const handleRemove = React.useCallback(async () => {
+    if (passive || actionsDisabled || uploading || removing || !value) {
+      return;
+    }
+
+    setInternalError(undefined);
+    if (onRemoveRequest) {
+      onRemoveRequest({ asset: value });
+      return;
+    }
+    if (!onRemove) {
+      notifyValue(null);
+      return;
+    }
+
+    setRemoving(true);
+    try {
+      await onRemove(value);
+      if (isMounted()) {
+        notifyValue(null);
+        setRemoving(false);
+      }
+    } catch (error) {
+      if (isMounted()) {
+        setInternalError(formatUnknownError(error));
+        setRemoving(false);
+      }
+    }
+  }, [
+    actionsDisabled,
+    isMounted,
+    notifyValue,
+    onRemove,
+    onRemoveRequest,
+    passive,
+    removing,
+    uploading,
+    value,
+  ]);
+
+  const canPreviewImage = type === 'image' && resolveRenderableAssetUrl(value) !== null;
+
+  return (
+    <>
+      <FormField
+        description={description}
+        disabled={disabled}
+        errorText={effectiveError}
+        helperText={helperText}
+        interactionPolicy={interactionPolicy}
+        invalid={Boolean(effectiveError)}
+        label={label}
+        readOnly={readOnly}
+        required={required}
+        testID={testID}
+      >
+        <Stack gap="m">
+          <UploadPresentation asset={value} aspectRatio={aspectRatio} type={type} />
+
+          {resolvedAccept || maxSizeBytes ? (
+            <Stack gap="xs">
+              {resolvedAccept ? (
+                <Text emphasis="muted" variant="caption">
+                  Accepted: {resolvedAccept}
+                </Text>
+              ) : null}
+              {maxSizeBytes ? (
+                <Text emphasis="muted" variant="caption">
+                  Max size: {formatBytes(maxSizeBytes)}
+                </Text>
+              ) : null}
+            </Stack>
+          ) : null}
+
+          {uploading ? (
+            <Stack gap="xs">
+              <Text emphasis="muted" variant="caption">
+                Uploading…
+              </Text>
+              {uploadProgress !== undefined || progress !== null ? (
+                <Progress max={1} value={clampProgress(uploadProgress ?? progress) ?? 0} />
+              ) : null}
+            </Stack>
+          ) : null}
+
+          <Stack direction={{ base: 'column', md: 'row' }} gap="s">
+            <Button
+              disabled={actionsDisabled || uploading || removing}
+              interactionPolicy={interactionPolicy}
+              onPress={() => {
+                void handlePick();
+              }}
+            >
+              {value ? 'Replace file' : 'Select file'}
+            </Button>
+
+            {value ? (
+              <Button
+                color="danger"
+                disabled={actionsDisabled || uploading || removing}
+                interactionPolicy={interactionPolicy}
+                loading={removing}
+                variant="outline"
+                onPress={() => {
+                  void handleRemove();
+                }}
+              >
+                Remove
+              </Button>
+            ) : null}
+
+            {canPreviewImage ? (
+              <Button
+                color="neutral"
+                interactionPolicy={interactionPolicy}
+                variant="soft"
+                onPress={() => setPreviewOpen(true)}
+              >
+                Preview
+              </Button>
+            ) : null}
+          </Stack>
+        </Stack>
+      </FormField>
+
+      {canPreviewImage ? (
+        <Modal
+          closeOnBackdrop
+          interactionPolicy={interactionPolicy}
+          onDismiss={() => setPreviewOpen(false)}
+          title="Image preview"
+          visible={previewOpen}
+        >
+          <Stack gap="m">
+            <Image aspectRatio={aspectRatio} fit="contain" source={value} />
+            <Stack direction="row" justify="flex-end">
+              <Button
+                color="neutral"
+                interactionPolicy={interactionPolicy}
+                variant="soft"
+                onPress={() => setPreviewOpen(false)}
+              >
+                Close
+              </Button>
+            </Stack>
+          </Stack>
+        </Modal>
+      ) : null}
+    </>
+  );
+}
+
+/*** Renders image previews or generic file metadata without exposing picker-specific assets. */
+function UploadPresentation({
+  asset,
+  aspectRatio,
+  type,
+}: {
+  asset: UploadAsset | null;
+  aspectRatio: number;
+  type: UploadType;
+}) {
+  if (type === 'image') {
+    return <Image aspectRatio={aspectRatio} source={asset} />;
+  }
+
+  return (
+    <Box borderWidth={1} p="m" radius="m">
+      <Stack direction="row" gap="s">
+        <Icon name={resolveUploadIcon(type)} size={22} />
+        <Stack gap="xs">
+          <Text variant="label" weight="semiBold">
+            {asset?.fileName ?? 'No file selected'}
+          </Text>
+          {asset?.contentType ? (
+            <Text emphasis="muted" variant="caption">
+              {asset.contentType}
+            </Text>
+          ) : null}
+        </Stack>
+      </Stack>
+    </Box>
+  );
+}
+
+/*** Resolves the native picker default while allowing accept to remain the precise restriction. */
+function resolveUploadAccept(type: UploadType, accept: string | undefined): string | undefined {
+  if (accept) {
+    return accept;
+  }
+
+  if (type === 'image') {
+    return 'image/*';
+  }
+
+  if (type === 'video') {
+    return 'video/*';
+  }
+
+  return undefined;
+}
+
+/*** Resolves an upload asset URL when it can be rendered directly. */
+function resolveRenderableAssetUrl(asset: UploadAsset | null): string | null {
+  if (!asset) {
+    return null;
+  }
+
+  switch (asset.kind) {
+    case 'local':
+      return asset.uri;
+    case 'url':
+      return asset.url;
+    case 'storage':
+      return asset.publicUrl ?? null;
+  }
+}
+
+/*** Resolves a generic icon for the selected upload mode. */
+function resolveUploadIcon(
+  type: UploadType,
+): 'attach-outline' | 'document-text-outline' | 'videocam-outline' {
+  switch (type) {
+    case 'video':
+      return 'videocam-outline';
+    case 'document':
+      return 'document-text-outline';
+    case 'file':
+    case 'image':
+      return 'attach-outline';
+  }
+}
+
+/*** Clamps progress callbacks into the normalized 0..1 range. */
+function clampProgress(value: number | null): number | null {
+  if (value === null || !Number.isFinite(value)) {
+    return null;
+  }
+
+  return Math.max(0, Math.min(1, value));
+}
+
+/*** Converts unknown picker/upload failures into user-facing text. */
+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.';
+}
+
+/*** Formats an upload byte limit for concise helper text. */
+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.at(unitIndex) ?? 'B';
+  const rounded = unitIndex === 0 ? Math.round(size) : Math.round(size * 10) / 10;
+  return `${rounded} ${unit}`;
+}

package/src/features/uploader/adapters/outbound/pickDocumentOrFileAsync.ts

@@ -0,0 +1,50 @@
+import * as DocumentPicker from 'expo-document-picker';
+
+import type { UploadAsset } from '../../../../types/upload';
+import type { UploadPickerInput } from '../../application/ports/outbound/UploadPickerPort';
+
+/*** Picks one document through Expo DocumentPicker and maps it to the ZORA upload contract. */
+export async function pickDocumentOrFileAsync(
+  input: UploadPickerInput,
+): Promise<UploadAsset | null> {
+  const result = await DocumentPicker.getDocumentAsync({
+    copyToCacheDirectory: true,
+    multiple: false,
+    type: resolveDocumentMimeTypes(input.accept),
+  });
+
+  if (result.canceled) {
+    return null;
+  }
+
+  const asset = result.assets.at(0);
+  if (!asset) {
+    return null;
+  }
+
+  return {
+    kind: 'local',
+    uri: asset.uri,
+    fileName: asset.name,
+    sizeBytes: asset.size,
+    contentType: asset.mimeType,
+  };
+}
+
+/*** Maps browser-style accept MIME entries into Expo DocumentPicker's type option. */
+function resolveDocumentMimeTypes(accept: string | undefined): string | string[] {
+  if (!accept) {
+    return '*/*';
+  }
+
+  const mimeTypes = accept
+    .split(',')
+    .map((token) => token.trim())
+    .filter((token) => token.includes('/'));
+
+  if (mimeTypes.length === 0) {
+    return '*/*';
+  }
+
+  return mimeTypes.length === 1 ? (mimeTypes.at(0) ?? '*/*') : mimeTypes;
+}

package/src/features/uploader/adapters/outbound/pickImageOrVideoAsync.ts

@@ -0,0 +1,30 @@
+import * as ImagePicker from 'expo-image-picker';
+
+import type { UploadAsset } from '../../../../types/upload';
+import type { UploadPickerInput } from '../../application/ports/outbound/UploadPickerPort';
+
+/*** Picks one image or video through Expo ImagePicker and maps it to the ZORA upload contract. */
+export async function pickImageOrVideoAsync(input: UploadPickerInput): Promise<UploadAsset | null> {
+  const result = await ImagePicker.launchImageLibraryAsync({
+    mediaTypes: input.type === 'video' ? ['videos'] : ['images'],
+  });
+
+  if (result.canceled) {
+    return null;
+  }
+
+  const asset = result.assets.at(0);
+  if (!asset) {
+    return null;
+  }
+
+  return {
+    kind: 'local',
+    uri: asset.uri,
+    fileName: asset.fileName ?? undefined,
+    sizeBytes: asset.fileSize,
+    contentType: asset.mimeType ?? undefined,
+    width: asset.width > 0 ? asset.width : undefined,
+    height: asset.height > 0 ? asset.height : undefined,
+  };
+}

package/src/features/uploader/application/ports/outbound/UploadPickerPort.ts

@@ -0,0 +1,10 @@
+import type { UploadAsset, UploadType } from '../../../../../types/upload';
+
+export interface UploadPickerInput {
+  type: UploadType;
+  accept?: string;
+}
+
+export interface UploadPickerPort {
+  pickAsync: (input: UploadPickerInput) => Promise<UploadAsset | null>;
+}

package/src/features/uploader/application/use-cases/pickUploadAssetAsync.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { UploadPickerPort } from '../ports/outbound/UploadPickerPort';
+import { pickUploadAssetAsync } from './pickUploadAssetAsync';
+
+describe('pickUploadAssetAsync', () => {
+  test('routes image and video selection to the media picker', async () => {
+    const calls: string[] = [];
+    const mediaPicker: UploadPickerPort = {
+      pickAsync: (input) => {
+        calls.push(`media:${input.type}`);
+        return Promise.resolve(null);
+      },
+    };
+    const documentPicker: UploadPickerPort = {
+      pickAsync: (input) => {
+        calls.push(`document:${input.type}`);
+        return Promise.resolve(null);
+      },
+    };
+
+    await pickUploadAssetAsync({ type: 'image' }, mediaPicker, documentPicker);
+    await pickUploadAssetAsync({ type: 'video' }, mediaPicker, documentPicker);
+
+    expect(calls).toEqual(['media:image', 'media:video']);
+  });
+
+  test('routes document and generic file selection to the document picker', async () => {
+    const calls: string[] = [];
+    const mediaPicker: UploadPickerPort = {
+      pickAsync: (input) => {
+        calls.push(`media:${input.type}`);
+        return Promise.resolve(null);
+      },
+    };
+    const documentPicker: UploadPickerPort = {
+      pickAsync: (input) => {
+        calls.push(`document:${input.type}`);
+        return Promise.resolve(null);
+      },
+    };
+
+    await pickUploadAssetAsync({ type: 'document' }, mediaPicker, documentPicker);
+    await pickUploadAssetAsync({ type: 'file' }, mediaPicker, documentPicker);
+
+    expect(calls).toEqual(['document:document', 'document:file']);
+  });
+});

package/src/features/uploader/application/use-cases/pickUploadAssetAsync.ts

@@ -0,0 +1,14 @@
+import type { UploadAsset } from '../../../../types/upload';
+import type { UploadPickerInput, UploadPickerPort } from '../ports/outbound/UploadPickerPort';
+
+/*** Selects the appropriate picker capability for the requested upload type. */
+export async function pickUploadAssetAsync(
+  input: UploadPickerInput,
+  imageOrVideoPicker: UploadPickerPort,
+  documentOrFilePicker: UploadPickerPort,
+): Promise<UploadAsset | null> {
+  const picker =
+    input.type === 'image' || input.type === 'video' ? imageOrVideoPicker : documentOrFilePicker;
+
+  return picker.pickAsync(input);
+}

package/src/features/uploader/application/use-cases/validateUploadAsset.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test';
+
+import { validateUploadAsset } from './validateUploadAsset';
+
+const IMAGE_ASSET = {
+  kind: 'local',
+  uri: 'file://photo.png',
+  fileName: 'photo.png',
+  contentType: 'image/png',
+  sizeBytes: 2_000,
+} as const;
+
+describe('validateUploadAsset', () => {
+  test('accepts wildcard MIME types', () => {
+    expect(validateUploadAsset({ accept: 'image/*', asset: IMAGE_ASSET })).toBeUndefined();
+  });
+
+  test('rejects a mismatched MIME type', () => {
+    expect(validateUploadAsset({ accept: 'application/json', asset: IMAGE_ASSET })).toContain(
+      'File type not accepted',
+    );
+  });
+
+  test('accepts matching file extensions', () => {
+    expect(validateUploadAsset({ accept: '.png', asset: IMAGE_ASSET })).toBeUndefined();
+  });
+
+  test('does not reject when the asset lacks metadata needed for validation', () => {
+    expect(
+      validateUploadAsset({
+        accept: 'image/*',
+        asset: { kind: 'local', uri: 'file://unknown' },
+      }),
+    ).toBeUndefined();
+  });
+
+  test('rejects assets above the configured size', () => {
+    expect(validateUploadAsset({ asset: IMAGE_ASSET, maxSizeBytes: 1_000 })).toContain(
+      'File is too large',
+    );
+  });
+
+  test('runs caller validation after built-in validation', () => {
+    expect(
+      validateUploadAsset({
+        asset: IMAGE_ASSET,
+        validate: () => 'Consumer validation failed.',
+      }),
+    ).toBe('Consumer validation failed.');
+  });
+});