react-native-ensys-camera-x 1.0.7

package/src/NativeDocumentPreviewView.tsx

@@ -0,0 +1,196 @@
+import type { ComponentType, FC } from 'react';
+import {
+  Platform,
+  requireNativeComponent,
+  View,
+  type NativeSyntheticEvent,
+  type ViewProps,
+} from 'react-native';
+
+/**
+ * The renderer families the native in-app document preview supports, all built on standard
+ * Android framework APIs (no third-party preview library):
+ *  - `pdf`   → PdfRenderer pages in a scrolling list (lazy, memory-bounded rasterization)
+ *  - `text`  → plain text in a scrollable native TextView
+ *  - `code`  → structured text (JSON/XML/…) — same renderer with a monospace face
+ *  - `html`  → a locked-down WebView (no JavaScript, no network, navigation blocked)
+ *  - `image` → image-based documents (scans/photos exported as documents), down-sampled decode
+ *  - `ppt`/`pptx` → dedicated PowerPoint extractors + Canvas slide viewer
+ *  - `docx`/`xlsx`/`odt`/`ods`/`rtf`/`csv`/`epub` → native format parsers (OOXML/ODF
+ *    zip+XML structure, RTF control words, CSV records, EPUB spine) that reproduce the
+ *    ORIGINAL geometry — true page size/margins, authored column widths/row heights/merges,
+ *    fonts/sizes/colors/spacing, embedded images — rendered by the same locked WebView engine.
+ */
+export type DocumentPreviewKind =
+  | 'pdf'
+  | 'text'
+  | 'code'
+  | 'html'
+  | 'image'
+  | 'ppt'
+  | 'docx'
+  | 'xlsx'
+  | 'pptx'
+  | 'odt'
+  | 'ods'
+  | 'rtf'
+  | 'csv'
+  | 'epub';
+
+export interface NativeDocumentPreviewViewProps extends ViewProps {
+  /** Document source uri (content:// or file://). */
+  src?: string;
+  /** Which native renderer to use — see {@link getDocumentPreviewKind}. */
+  kind?: DocumentPreviewKind;
+  /**
+   * False while the document's page is off-screen in a paging viewer — pauses expensive work
+   * (PDF page rasterization) exactly like the audio/video cells' `active` gate.
+   */
+  active?: boolean;
+  /** Fired when the document is ready. `pageCount` is > 0 for PDFs, 0 otherwise. */
+  onPreviewLoad?: (event: NativeSyntheticEvent<{ pageCount: number }>) => void;
+  /** Fired when the file can't be rendered — callers should fall back to an info card. */
+  onPreviewError?: (event: NativeSyntheticEvent<{ message: string }>) => void;
+}
+
+// Extension → renderer family. Formats without a parser here (binary-era DOC/PPT/XLS, Apple
+// PAGES, archives, …) return null and get the informational card.
+const EXTENSION_KINDS: Record<string, DocumentPreviewKind> = {
+  pdf: 'pdf',
+  txt: 'text',
+  log: 'text',
+  text: 'text',
+  md: 'text',
+  json: 'code',
+  xml: 'code',
+  tsv: 'code',
+  yaml: 'code',
+  yml: 'code',
+  html: 'html',
+  htm: 'html',
+  xhtml: 'html',
+  jpg: 'image',
+  jpeg: 'image',
+  png: 'image',
+  gif: 'image',
+  webp: 'image',
+  bmp: 'image',
+  heic: 'image',
+  heif: 'image',
+  hif: 'image',
+  avif: 'image',
+  avifs: 'image',
+  // Native office-format parsers — original layout geometry preserved.
+  docx: 'docx',
+  xlsx: 'xlsx',
+  ppt: 'ppt',
+  pptx: 'pptx',
+  pps: 'ppt',
+  ppsx: 'pptx',
+  pot: 'ppt',
+  potx: 'pptx',
+  // Macro-enabled variants are ordinary PresentationML zips. Without these the extension lookup
+  // misses and SAF providers frequently report application/octet-stream, so the MIME fallback
+  // can't rescue them either.
+  pptm: 'pptx',
+  ppsm: 'pptx',
+  potm: 'pptx',
+  odt: 'odt',
+  ods: 'ods',
+  rtf: 'rtf',
+  csv: 'csv',
+  epub: 'epub',
+};
+
+// MIME type → renderer family, used when the file name carries no useful extension.
+const MIME_KINDS: Record<string, DocumentPreviewKind> = {
+  'application/pdf': 'pdf',
+  'application/json': 'code',
+  'application/xml': 'code',
+  'text/xml': 'code',
+  'text/csv': 'csv',
+  'text/comma-separated-values': 'csv',
+  'text/html': 'html',
+  'application/xhtml+xml': 'html',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document':
+    'docx',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':
+    'xlsx',
+  'application/vnd.ms-powerpoint': 'ppt',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation':
+    'pptx',
+  'application/vnd.openxmlformats-officedocument.presentationml.slideshow':
+    'pptx',
+  'application/vnd.openxmlformats-officedocument.presentationml.template':
+    'pptx',
+  'application/powerpoint': 'ppt',
+  'application/mspowerpoint': 'ppt',
+  'application/x-mspowerpoint': 'ppt',
+  'application/x-powerpoint': 'ppt',
+  'application/vnd.ms-powerpoint.presentation.macroenabled.12': 'pptx',
+  'application/vnd.ms-powerpoint.slideshow.macroenabled.12': 'pptx',
+  'application/vnd.oasis.opendocument.text': 'odt',
+  'application/vnd.oasis.opendocument.spreadsheet': 'ods',
+  'application/rtf': 'rtf',
+  'text/rtf': 'rtf',
+  'application/epub+zip': 'epub',
+};
+
+/**
+ * Maps a document's file name / MIME type to the native renderer able to preview it in-app,
+ * or `null` when no parser exists for the format (binary-era DOC/XLS, Apple PAGES,
+ * archives, …) — those should show an informational card instead. The extension wins over the
+ * MIME type because SAF providers frequently report generic types (application/octet-stream)
+ * for files whose names identify them precisely.
+ */
+export function getDocumentPreviewKind(
+  fileName?: string,
+  mimeType?: string
+): DocumentPreviewKind | null {
+  if (fileName) {
+    const dot = fileName.lastIndexOf('.');
+    if (dot >= 0 && dot < fileName.length - 1) {
+      const kind = EXTENSION_KINDS[fileName.slice(dot + 1).toLowerCase()];
+      if (kind) return kind;
+    }
+  }
+  if (mimeType) {
+    const normalized = mimeType.toLowerCase();
+    const direct = MIME_KINDS[normalized];
+    if (direct) return direct;
+    if (normalized.startsWith('text/')) return 'text';
+    if (normalized.startsWith('image/')) return 'image';
+  }
+  return null;
+}
+
+// Native (Android) in-app document preview — PdfRenderer / TextView / locked-down WebView /
+// down-sampled image decode, all standard framework APIs. Resolved lazily and platform-guarded
+// so non-Android targets (or an app without the native view registered) fall back to a plain
+// view, exactly like NativeAudioPlayerView.
+let NativeDocumentComponent: ComponentType<NativeDocumentPreviewViewProps> | null =
+  null;
+if (Platform.OS === 'android') {
+  try {
+    NativeDocumentComponent =
+      requireNativeComponent<NativeDocumentPreviewViewProps>(
+        'CustomDocumentPreview'
+      );
+  } catch {
+    NativeDocumentComponent = null;
+  }
+}
+
+/** True when the native in-app preview is available on this platform/build. */
+export const isNativeDocumentPreviewAvailable = (): boolean =>
+  NativeDocumentComponent !== null;
+
+export const NativeDocumentPreviewView: FC<NativeDocumentPreviewViewProps> = (
+  props
+) => {
+  if (NativeDocumentComponent) {
+    return <NativeDocumentComponent {...props} />;
+  }
+  const { src, kind, active, onPreviewLoad, onPreviewError, ...rest } = props;
+  return <View {...rest} />;
+};

package/src/NativeMediaThumbnailView.tsx

@@ -0,0 +1,167 @@
+import type { FC } from 'react';
+import {
+  Image,
+  View,
+  type ImageStyle,
+  type StyleProp,
+  type ViewProps,
+  type ViewStyle,
+} from 'react-native';
+import type { CameraAsset } from './types';
+import {
+  resolveNativeComponent,
+  toImageSourceUri,
+} from './nativeComponentSupport';
+import { NativeAnimatedImageView } from './NativeAnimatedImageView';
+import { isGifAsset, requiresNativeImageDecoder } from './utils';
+
+export interface NativeMediaThumbnailViewProps
+  extends Omit<ViewProps, 'style'> {
+  /** The media's own URI (`content://`, `file://` or a plain path). */
+  src?: string;
+  /**
+   * `video` extracts a frame; anything else is decoded as a still. Both the JS (`photo`) and
+   * database (`image`) spellings mean the same thing.
+   */
+  mediaType?: CameraAsset['type'] | 'image';
+  /** Cached copy of the file, read in preference to the URI while it exists on disk. */
+  cachePath?: string;
+  /** A video's user-selected cover frame; overrides frame extraction when present. */
+  coverUri?: string;
+  /** Format hints — decide decodability (HEIF/AVIF) and alpha handling. */
+  mimeType?: string;
+  fileName?: string;
+  /** How the frame is scaled into the tile. Defaults to `cover`. */
+  resizeMode?: 'contain' | 'cover';
+  /**
+   * Decode target in pixels. Defaults to the tile's own measured size, which is what a list
+   * row wants — set it only to force a sharper (or cheaper) bitmap.
+   */
+  thumbnailSize?: number;
+  /**
+   * Typed as an image style rather than a view style: the native view and the `<Image>`
+   * fallback both render image content.
+   */
+  style?: StyleProp<ImageStyle>;
+}
+
+// Native thumbnail view (Android). A JS <Image> cannot produce a thumbnail for a video at all —
+// there is no frame to read without an extractor — and needs platform decoders for HEIF/AVIF, so
+// list rows for those were left blank. The native view runs the library's own ThumbnailLoader
+// (cover frame → extracted video frame → resolver thumbnail → downsampled decode, LRU cached).
+const NativeMediaThumbnailComponent =
+  resolveNativeComponent<NativeMediaThumbnailViewProps>('CustomMediaThumbnail');
+
+/** True when native thumbnail decoding is available on this platform/build. */
+export const isNativeMediaThumbnailAvailable = (): boolean =>
+  NativeMediaThumbnailComponent !== null;
+
+/**
+ * The best thumbnail JS alone can draw for this media.
+ *
+ * Reached whenever the native view is not in the binary — a host app built before it existed,
+ * or a non-Android target. A still image is fully renderable here: `<Image>` decodes JPEG, PNG,
+ * WebP, GIF and BMP, and {@link NativeAnimatedImageView} covers the containers Fresco cannot
+ * (HEIF/AVIF) plus animated GIFs, held on a single frame because a list tile wants a still.
+ *
+ * A video is the one case JS genuinely cannot serve: without a cover frame there is nothing to
+ * decode, so the tile holds its space instead of pointing an `<Image>` at an MP4 and logging a
+ * Fresco failure for every row on screen.
+ */
+const MediaThumbnailFallback: FC<NativeMediaThumbnailViewProps> = (props) => {
+  const source = props.coverUri ?? props.src;
+  const uri = toImageSourceUri(source);
+  const isVideoWithoutCover =
+    props.mediaType === 'video' && !props.coverUri;
+
+  if (!uri || isVideoWithoutCover) {
+    // Size/rounding live on the style either component receives.
+    return (
+      <View
+        style={props.style as StyleProp<ViewStyle>}
+        testID={props.testID}
+      />
+    );
+  }
+
+  const descriptor = {
+    mimeType: props.mimeType,
+    fileName: props.fileName,
+    uri: source,
+  };
+
+  if (isGifAsset(descriptor) || requiresNativeImageDecoder(descriptor)) {
+    return (
+      <NativeAnimatedImageView
+        src={uri}
+        style={props.style}
+        testID={props.testID}
+        resizeMode={props.resizeMode ?? 'cover'}
+        // A tile is a still: decode the frame, never animate it behind a scrolling list.
+        active={false}
+      />
+    );
+  }
+
+  return (
+    <Image
+      style={props.style}
+      testID={props.testID}
+      source={{ uri }}
+      resizeMode={props.resizeMode ?? 'cover'}
+      // Decode to the tile's size rather than the file's full resolution: a 12MP still decoded
+      // whole is ~48MB of bitmap for a ~56px row. No-op on iOS.
+      resizeMethod="resize"
+    />
+  );
+};
+
+/**
+ * Renders a media file's own thumbnail — an extracted frame for a video, the decoded image for
+ * a still — through the native decoder where the build has it and through
+ * {@link MediaThumbnailFallback} where it does not. Either way the underlying file is only ever
+ * read.
+ */
+export const NativeMediaThumbnailView: FC<NativeMediaThumbnailViewProps> = (
+  props
+) => {
+  if (NativeMediaThumbnailComponent) {
+    return <NativeMediaThumbnailComponent {...props} />;
+  }
+  return <MediaThumbnailFallback {...props} />;
+};
+
+export interface MediaThumbnailProps {
+  /** The asset to render a thumbnail for. */
+  asset: CameraAsset;
+  style?: StyleProp<ImageStyle>;
+  resizeMode?: 'contain' | 'cover';
+  thumbnailSize?: number;
+  testID?: string;
+}
+
+/**
+ * Convenience wrapper that feeds a whole {@link CameraAsset} to {@link NativeMediaThumbnailView},
+ * so a list row does not have to know which of the asset's fields drive the decode.
+ */
+export const MediaThumbnail: FC<MediaThumbnailProps> = ({
+  asset,
+  style,
+  resizeMode = 'cover',
+  thumbnailSize,
+  testID,
+}) => (
+  <NativeMediaThumbnailView
+    // documentUri is the published copy; uri is where the file actually is for a capture.
+    src={asset.uri || asset.documentUri}
+    mediaType={asset.type}
+    cachePath={asset.cachePath}
+    coverUri={asset.coverUri}
+    mimeType={asset.mimeType}
+    fileName={asset.fileName}
+    style={style}
+    resizeMode={resizeMode}
+    thumbnailSize={thumbnailSize}
+    testID={testID}
+  />
+);

package/src/NativeSvgIcon.tsx

@@ -0,0 +1,46 @@
+import type { FC, ReactElement } from 'react';
+import type {
+  ColorValue,
+  StyleProp,
+  ViewProps,
+  ViewStyle,
+} from 'react-native';
+import { resolveNativeComponent } from './nativeComponentSupport';
+
+export interface NativeSvgIconProps extends Omit<ViewProps, 'style'> {
+  /** Inline SVG markup to draw. */
+  svg: string;
+  /**
+   * Optional tint. Recolours `currentColor` (and any un-parseable colour) in the
+   * markup; explicit colours in the SVG are left untouched.
+   */
+  tintColor?: ColorValue;
+  style?: StyleProp<ViewStyle>;
+}
+
+// Native SVG icon view (Android). ReactNative's own <Image> cannot decode an
+// `<svg>` data URI on Android (Fresco ships no SVG decoder), so inline-`svg`
+// icon customizations are drawn by the library's own bundled SvgDrawable parser
+// through this view — no react-native-svg, no third-party dependency.
+const NativeSvgIconComponent =
+  resolveNativeComponent<NativeSvgIconProps>('CameraSvgIcon');
+
+/** True when the bundled native SVG renderer is available on this platform/build. */
+export const isNativeSvgIconAvailable = (): boolean =>
+  NativeSvgIconComponent !== null;
+
+/**
+ * Draws inline SVG markup with the bundled native renderer when it is available,
+ * and otherwise renders [fallback] — the plugin's built-in default icon. This is
+ * how an inline-`svg` customization stays safe on a platform with no native half
+ * (iOS/web) or against an older linked binary: it silently shows the default
+ * artwork rather than a blank box.
+ */
+export const NativeSvgIcon: FC<
+  NativeSvgIconProps & { fallback: ReactElement }
+> = ({ fallback, ...props }) => {
+  if (NativeSvgIconComponent) {
+    return <NativeSvgIconComponent {...props} />;
+  }
+  return fallback;
+};

package/src/ResponsivePreviewContainer.tsx

@@ -0,0 +1,227 @@
+import React, { useMemo, useEffect, useState } from 'react';
+import {
+  View,
+  StyleSheet,
+  Dimensions,
+  type DisplayMetrics,
+} from 'react-native';
+import { useCameraTheme } from './theme';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Single source of truth for WhatsApp-like camera preview dimensions.
+// Aspect ratio ≈ 720:1165 (≈ 9:14.6 ≈ 0.618) – matches WhatsApp's camera preview.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** WhatsApp-like camera preview aspect ratio (720:1165 ≈ 9:14.6 ≈ 0.618) */
+export const WHATSAPP_ASPECT_RATIO = 720 / 1165;
+
+/**
+ * Portrait 9:16 aspect ratio used for the media editing / preview canvas.
+ *
+ * After capture the user is taken to the editing preview, which always presents
+ * a portrait (9:16) canvas regardless of the captured media's own orientation.
+ * A landscape photo is scaled and centered (letterboxed) inside this canvas with
+ * its aspect ratio preserved — no rotation, stretching, distortion, or cropping.
+ * This single constant is the source of truth for that canvas so the on-screen
+ * preview matches the final exported / sent image exactly.
+ */
+export const PORTRAIT_PREVIEW_ASPECT_RATIO = 9 / 16;
+
+/**
+ * Responsive preview geometry — the single source of truth. Every value is
+ * also exposed through `theme.components.responsivePreviewContainer` so host
+ * apps can re-tune them without touching this file.
+ */
+export interface PreviewDimensionConfig {
+  /** Fraction of screen width used for the preview container. */
+  widthRatio: number;
+  /** Maximum preview width in logical pixels (matches WhatsApp on tablets). */
+  maxWidth: number;
+  /** Maximum fraction of screen height the preview may occupy. */
+  maxHeightRatio: number;
+}
+
+/** Default geometry — the stock, WhatsApp-like responsive sizing. */
+export const DEFAULT_PREVIEW_DIMENSION_CONFIG: PreviewDimensionConfig = {
+  widthRatio: 0.96,
+  maxWidth: 720,
+  maxHeightRatio: 0.92,
+};
+
+// ── Pure calculation helpers (no React dependency) ───────────────────────────
+
+/** Compute preview dimensions from raw screen values */
+export function calcPreviewDimensions(
+  screenW: number,
+  screenH: number,
+  config: PreviewDimensionConfig = DEFAULT_PREVIEW_DIMENSION_CONFIG
+) {
+  const width = Math.min(screenW * config.widthRatio, config.maxWidth);
+  const height = Math.min(
+    screenH * config.maxHeightRatio,
+    width / WHATSAPP_ASPECT_RATIO
+  );
+  return { width, height, aspectRatio: WHATSAPP_ASPECT_RATIO };
+}
+
+/**
+ * Compute portrait 9:16 canvas dimensions from raw screen values.
+ *
+ * The canvas is fitted (contain) inside the available screen area so the whole
+ * 9:16 frame is always visible: it takes the largest 9:16 box that fits within
+ * both the width and height budget. The returned dimensions therefore always
+ * satisfy `width / height === PORTRAIT_PREVIEW_ASPECT_RATIO`, guaranteeing that
+ * the preview shown on screen is the exact same shape as the exported/sent image.
+ */
+export function calcPortraitPreviewDimensions(
+  screenW: number,
+  screenH: number,
+  config: PreviewDimensionConfig = DEFAULT_PREVIEW_DIMENSION_CONFIG
+) {
+  // Start from the width budget, then clamp by the height budget so the fixed
+  // 9:16 ratio is preserved no matter the screen orientation.
+  let width = Math.min(screenW * config.widthRatio, config.maxWidth);
+  let height = width / PORTRAIT_PREVIEW_ASPECT_RATIO;
+
+  const maxHeight = screenH * config.maxHeightRatio;
+  if (height > maxHeight) {
+    height = maxHeight;
+    width = height * PORTRAIT_PREVIEW_ASPECT_RATIO;
+  }
+
+  return { width, height, aspectRatio: PORTRAIT_PREVIEW_ASPECT_RATIO };
+}
+
+// ── Static exports (computed once at import-time for lightweight consumers) ─
+
+const _initial = Dimensions.get('window');
+export const PREVIEW_WIDTH = calcPreviewDimensions(
+  _initial.width,
+  _initial.height
+).width;
+export const PREVIEW_HEIGHT = calcPreviewDimensions(
+  _initial.width,
+  _initial.height
+).height;
+
+// ── Reactive hook (recomputes on orientation / dimension changes) ─────────────
+
+/**
+ * Returns responsive preview dimensions that update on screen size changes.
+ * Use this inside components instead of the static PREVIEW_WIDTH/PREVIEW_HEIGHT
+ * exports to ensure correctness after rotation or window resize.
+ */
+export function usePreviewDimensions(
+  config: PreviewDimensionConfig = DEFAULT_PREVIEW_DIMENSION_CONFIG
+) {
+  const [dims, setDims] = useState(() => Dimensions.get('window'));
+
+  useEffect(() => {
+    const sub = Dimensions.addEventListener(
+      'change',
+      ({ window }: { window: DisplayMetrics }) => {
+        setDims(window);
+      }
+    );
+    return () => sub.remove();
+  }, []);
+
+  return useMemo(
+    () => calcPreviewDimensions(dims.width, dims.height, config),
+    [dims, config]
+  );
+}
+
+/**
+ * Returns responsive portrait 9:16 canvas dimensions that update on screen size
+ * changes. Use this for the editing / preview canvas so a captured landscape
+ * image is scaled and centered inside a fixed portrait frame, and the preview
+ * matches the final exported / sent image exactly.
+ */
+export function usePortraitPreviewDimensions(
+  config: PreviewDimensionConfig = DEFAULT_PREVIEW_DIMENSION_CONFIG
+) {
+  const [dims, setDims] = useState(() => Dimensions.get('window'));
+
+  useEffect(() => {
+    const sub = Dimensions.addEventListener(
+      'change',
+      ({ window }: { window: DisplayMetrics }) => {
+        setDims(window);
+      }
+    );
+    return () => sub.remove();
+  }, []);
+
+  return useMemo(
+    () => calcPortraitPreviewDimensions(dims.width, dims.height, config),
+    [dims, config]
+  );
+}
+
+// ── Component ────────────────────────────────────────────────────────────────
+
+interface ResponsivePreviewContainerProps {
+  children: React.ReactNode;
+  /** Optional extra styles merged after the container styles */
+  style?: any;
+  /** Explicit width to use instead of calculated width */
+  width?: number;
+  /** Explicit height to use instead of calculated height */
+  height?: number;
+}
+
+/**
+ * A fixed-aspect-ratio container that matches WhatsApp's camera preview area.
+ *
+ * Usage:
+ *   <ResponsivePreviewContainer>
+ *     <Image source={…} style={{ width: '100%', height: '100%', resizeMode: 'contain' }} />
+ *   </ResponsivePreviewContainer>
+ */
+export const ResponsivePreviewContainer: React.FC<
+  ResponsivePreviewContainerProps
+> = ({ children, style, width: explicitWidth, height: explicitHeight }) => {
+  // React hooks must be called unconditionally, so we still call it,
+  // but explicit dimensions (when provided) take precedence below.
+  const theme = useCameraTheme();
+  const rpcTheme = theme.components.responsivePreviewContainer;
+  const previewConfig = useMemo(
+    () => ({
+      widthRatio: rpcTheme.widthRatio,
+      maxWidth: rpcTheme.maxWidth,
+      maxHeightRatio: rpcTheme.maxHeightRatio,
+    }),
+    [rpcTheme.widthRatio, rpcTheme.maxWidth, rpcTheme.maxHeightRatio]
+  );
+  const dims = usePreviewDimensions(previewConfig);
+
+  const finalWidth = explicitWidth ?? dims.width;
+  const finalHeight = explicitHeight ?? dims.height;
+
+  return (
+    <View
+      style={[
+        styles.container,
+        {
+          width: finalWidth,
+          height: finalHeight,
+          borderRadius: theme.components.responsivePreviewContainer.borderRadius,
+          backgroundColor: theme.components.responsivePreviewContainer.background,
+        },
+        style,
+      ]}
+    >
+      {children}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    overflow: 'hidden',
+    alignSelf: 'center',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+});