@rustors/react 0.0.0-stage → 0.3.1

package/src/components/OcrDropzone.tsx

@@ -0,0 +1,117 @@
+import {
+  useState,
+  useRef,
+  useCallback,
+  type ReactElement,
+  type DragEvent,
+  type ChangeEvent,
+} from 'react';
+import type { OcrDropzoneProps } from '../types/index.js';
+import { DropzonePrompt } from './DropzonePrompt.js';
+import { DropzonePreview } from './DropzonePreview.js';
+import { useOcr } from '../hooks/useOcr.js';
+
+export function OcrDropzone({
+  onFileSelect,
+  onDetect,
+  autoDetect = false,
+  detectOptions,
+  accept = 'image/png,image/jpeg,image/webp,image/bmp',
+  className,
+  style,
+}: OcrDropzoneProps): ReactElement {
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const [isDragOver, setIsDragOver] = useState(false);
+  const [previewUrl, setPreviewUrl] = useState<string | null>(null);
+
+  const { detect } = useOcr({
+    ...detectOptions,
+    onSuccess: (res) => onDetect?.(res),
+  });
+
+  const handleFile = useCallback(
+    async (file: File) => {
+      onFileSelect?.(file);
+      const url = URL.createObjectURL(file);
+      setPreviewUrl(url);
+
+      if (autoDetect) {
+        await detect(file, detectOptions);
+      }
+    },
+    [autoDetect, detect, detectOptions, onFileSelect]
+  );
+
+  const onDragOver = useCallback((e: DragEvent<HTMLDivElement>) => {
+    e.preventDefault();
+    setIsDragOver(true);
+  }, []);
+
+  const onDragLeave = useCallback(() => {
+    setIsDragOver(false);
+  }, []);
+
+  const onDrop = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      setIsDragOver(false);
+      const files = e.dataTransfer.files;
+      if (files && files.length > 0) {
+        handleFile(files[0]);
+      }
+    },
+    [handleFile]
+  );
+
+  const onInputChange = useCallback(
+    (e: ChangeEvent<HTMLInputElement>) => {
+      const files = e.target.files;
+      if (files && files.length > 0) {
+        handleFile(files[0]);
+      }
+    },
+    [handleFile]
+  );
+
+  const clearSelection = useCallback(() => {
+    if (previewUrl) {
+      URL.revokeObjectURL(previewUrl);
+    }
+    setPreviewUrl(null);
+    if (fileInputRef.current) {
+      fileInputRef.current.value = '';
+    }
+  }, [previewUrl]);
+
+  return (
+    <div
+      className={className}
+      onClick={() => fileInputRef.current?.click()}
+      onDragOver={onDragOver}
+      onDragLeave={onDragLeave}
+      onDrop={onDrop}
+      style={{
+        border: `2px dashed ${isDragOver ? '#3b82f6' : '#d1d5db'}`,
+        borderRadius: '8px',
+        backgroundColor: isDragOver ? '#eff6ff' : '#fafafa',
+        cursor: 'pointer',
+        transition: 'border-color 0.15s ease, background-color 0.15s ease',
+        boxSizing: 'border-box',
+        ...style,
+      }}
+    >
+      <input
+        ref={fileInputRef}
+        type="file"
+        accept={accept}
+        onChange={onInputChange}
+        style={{ display: 'none' }}
+      />
+      {previewUrl ? (
+        <DropzonePreview previewUrl={previewUrl} onClear={clearSelection} />
+      ) : (
+        <DropzonePrompt />
+      )}
+    </div>
+  );
+}

package/src/components/OcrOverlay.tsx

@@ -0,0 +1,100 @@
+import {
+  useState,
+  useRef,
+  useCallback,
+  type ReactElement,
+  type SyntheticEvent,
+} from 'react';
+import type { OcrOverlayProps } from '../types/index.js';
+import { BoundingBox } from './BoundingBox.js';
+import { calculateScale } from '../utils/geometry.js';
+
+export function OcrOverlay({
+  imageSrc,
+  results,
+  naturalWidth: propNaturalWidth,
+  naturalHeight: propNaturalHeight,
+  highlightColor,
+  showTooltips = true,
+  className,
+  style,
+  onItemClick,
+}: OcrOverlayProps): ReactElement {
+  const imgRef = useRef<HTMLImageElement | null>(null);
+  const [renderDims, setRenderDims] = useState<{ width: number; height: number }>({
+    width: 0,
+    height: 0,
+  });
+  const [naturalDims, setNaturalDims] = useState<{ width: number; height: number }>({
+    width: propNaturalWidth || 0,
+    height: propNaturalHeight || 0,
+  });
+
+  const onImageLoad = useCallback((e: SyntheticEvent<HTMLImageElement>) => {
+    const img = e.currentTarget;
+    setNaturalDims({
+      width: img.naturalWidth,
+      height: img.naturalHeight,
+    });
+    setRenderDims({
+      width: img.clientWidth,
+      height: img.clientHeight,
+    });
+  }, []);
+
+  const effectiveNaturalWidth = propNaturalWidth || naturalDims.width;
+  const effectiveNaturalHeight = propNaturalHeight || naturalDims.height;
+
+  const { scaleX, scaleY } = calculateScale(
+    effectiveNaturalWidth,
+    effectiveNaturalHeight,
+    renderDims.width || effectiveNaturalWidth,
+    renderDims.height || effectiveNaturalHeight
+  );
+
+  return (
+    <div
+      className={className}
+      style={{
+        position: 'relative',
+        display: 'inline-block',
+        overflow: 'hidden',
+        ...style,
+      }}
+    >
+      <img
+        ref={imgRef}
+        src={imageSrc}
+        alt="OCR Target"
+        onLoad={onImageLoad}
+        style={{
+          display: 'block',
+          maxWidth: '100%',
+          height: 'auto',
+        }}
+      />
+      <div
+        style={{
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          right: 0,
+          bottom: 0,
+          pointerEvents: 'none',
+        }}
+      >
+        {results.map((item, idx) => (
+          <BoundingBox
+            key={`${item.text}-${idx}`}
+            item={item}
+            scaleX={scaleX}
+            scaleY={scaleY}
+            highlightColor={highlightColor}
+            showTooltip={showTooltips}
+            onClick={onItemClick}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/context/RustoContext.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'react';
+import type { RustoContextValue } from '../types/index.js';
+
+export const RustoContext = createContext<RustoContextValue | null>(null);

package/src/context/RustoProvider.tsx

@@ -0,0 +1,62 @@
+import {
+  useState,
+  useEffect,
+  useCallback,
+  useMemo,
+  type ReactElement,
+} from 'react';
+import type { InitializeConfig } from '@rustors/web';
+import { RustoContext } from './RustoContext.js';
+import { defaultOcrService } from '../services/ocrService.js';
+import type {
+  RustoContextValue,
+  RustoProviderProps,
+  RustoStatus,
+} from '../types/index.js';
+
+export function RustoProvider({
+  children,
+  config,
+  autoInitialize = true,
+}: RustoProviderProps): ReactElement {
+  const [status, setStatus] = useState<RustoStatus>('idle');
+  const [error, setError] = useState<Error | null>(null);
+
+  const initialize = useCallback(
+    async (overrideConfig?: InitializeConfig): Promise<void> => {
+      try {
+        setStatus('initializing');
+        setError(null);
+        await defaultOcrService.init(overrideConfig || config);
+        setStatus('ready');
+      } catch (err) {
+        const errorObj = err instanceof Error ? err : new Error(String(err));
+        setError(errorObj);
+        setStatus('error');
+        throw errorObj;
+      }
+    },
+    [config]
+  );
+
+  useEffect(() => {
+    if (autoInitialize && status === 'idle') {
+      initialize().catch(() => {
+        // Error state already captured in state
+      });
+    }
+  }, [autoInitialize, status, initialize]);
+
+  const value: RustoContextValue = useMemo(
+    () => ({
+      status,
+      isReady: status === 'ready',
+      error,
+      initialize,
+      service: defaultOcrService,
+    }),
+    [status, error, initialize]
+  );
+
+  return <RustoContext.Provider value={value}>{children}</RustoContext.Provider>;
+}

package/src/hooks/useOcr.ts

@@ -0,0 +1,73 @@
+import { useState, useCallback, useContext } from 'react';
+import type {
+  DetectTextOptions,
+  ImageSource,
+  TextResult,
+} from '@rustors/web';
+import { RustoContext } from '../context/RustoContext.js';
+import { defaultOcrService } from '../services/ocrService.js';
+import type { UseOcrOptions, UseOcrReturn } from '../types/index.js';
+
+export function useOcr(options: UseOcrOptions = {}): UseOcrReturn {
+  const context = useContext(RustoContext);
+  const service = context?.service || defaultOcrService;
+
+  const [results, setResults] = useState<TextResult[]>([]);
+  const [spatialText, setSpatialText] = useState<string>('');
+  const [isProcessing, setIsProcessing] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const reset = useCallback(() => {
+    setResults([]);
+    setSpatialText('');
+    setIsProcessing(false);
+    setError(null);
+  }, []);
+
+  const detect = useCallback(
+    async (
+      source: ImageSource,
+      overrideOptions?: DetectTextOptions
+    ): Promise<TextResult[] | string> => {
+      setIsProcessing(true);
+      setError(null);
+
+      const mergedOptions: DetectTextOptions = {
+        ...options,
+        ...overrideOptions,
+      };
+
+      try {
+        const output = await service.detect(source, mergedOptions);
+
+        if (typeof output === 'string') {
+          setSpatialText(output);
+          setResults([]);
+        } else {
+          setResults(output);
+          setSpatialText('');
+        }
+
+        options.onSuccess?.(output);
+        return output;
+      } catch (err) {
+        const errorObj = err instanceof Error ? err : new Error(String(err));
+        setError(errorObj);
+        options.onError?.(errorObj);
+        throw errorObj;
+      } finally {
+        setIsProcessing(false);
+      }
+    },
+    [options, service]
+  );
+
+  return {
+    detect,
+    results,
+    spatialText,
+    isProcessing,
+    error,
+    reset,
+  };
+}

package/src/hooks/useRusto.ts

@@ -0,0 +1,11 @@
+import { useContext } from 'react';
+import { RustoContext } from '../context/RustoContext.js';
+import type { RustoContextValue } from '../types/index.js';
+
+export function useRusto(): RustoContextValue {
+  const context = useContext(RustoContext);
+  if (!context) {
+    throw new Error('useRusto must be used within a RustoProvider.');
+  }
+  return context;
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+// Provider & Context
+export { RustoProvider } from './context/RustoProvider.js';
+export { RustoContext } from './context/RustoContext.js';
+
+// Hooks
+export { useRusto } from './hooks/useRusto.js';
+export { useOcr } from './hooks/useOcr.js';
+
+// Services
+export { OcrService, defaultOcrService } from './services/ocrService.js';
+
+// UI Components
+export { OcrOverlay } from './components/OcrOverlay.js';
+export { BoundingBox } from './components/BoundingBox.js';
+export { OcrDropzone } from './components/OcrDropzone.js';
+export { DropzonePrompt } from './components/DropzonePrompt.js';
+export { DropzonePreview } from './components/DropzonePreview.js';
+
+// Geometry & Formatters
+export { scaleFrame, scaleQuad, calculateScale } from './utils/geometry.js';
+export { resultsToText, resultsToCsv, resultsToJson } from './utils/formatters.js';
+
+// Types
+export * from './types/index.js';
+
+// Re-export common types from @rustors/web
+export type {
+  TextResult,
+  Frame,
+  ImageSource,
+  DetectTextOptions,
+  InitializeConfig,
+  ModelPreset,
+} from '@rustors/web';

package/src/services/ocrService.ts

@@ -0,0 +1,43 @@
+import {
+  WebOcrEngine,
+  type DetectTextOptions,
+  type ImageSource,
+  type InitializeConfig,
+  type TextResult,
+} from '@rustors/web';
+
+export class OcrService {
+  private engine: WebOcrEngine;
+
+  constructor(engineInstance?: WebOcrEngine) {
+    this.engine = engineInstance || new WebOcrEngine();
+  }
+
+  public async init(config?: InitializeConfig): Promise<void> {
+    await this.engine.initialize(config);
+  }
+
+  public isReady(): boolean {
+    return this.engine.isInitialized();
+  }
+
+  public async detect(
+    source: ImageSource,
+    options?: DetectTextOptions
+  ): Promise<TextResult[] | string> {
+    if (!this.engine.isInitialized()) {
+      throw new Error('OCR Service engine is not ready. Call init() first.');
+    }
+    return this.engine.detectText(source, options);
+  }
+
+  public terminate(): void {
+    this.engine.terminate();
+  }
+
+  public getEngine(): WebOcrEngine {
+    return this.engine;
+  }
+}
+
+export const defaultOcrService = new OcrService();

package/src/types/components.ts

@@ -0,0 +1,48 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { TextResult, DetectTextOptions } from '@rustors/web';
+
+export interface BoundingBoxProps {
+  item: TextResult;
+  scaleX: number;
+  scaleY: number;
+  highlightColor?: string;
+  showTooltip?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  onClick?: (item: TextResult) => void;
+}
+
+export interface OcrOverlayProps {
+  imageSrc: string;
+  results: TextResult[];
+  naturalWidth?: number;
+  naturalHeight?: number;
+  highlightColor?: string;
+  showTooltips?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  onItemClick?: (item: TextResult) => void;
+}
+
+export interface DropzonePromptProps {
+  title?: string;
+  subtitle?: string;
+  icon?: ReactNode;
+  className?: string;
+}
+
+export interface DropzonePreviewProps {
+  previewUrl: string;
+  onClear: () => void;
+  className?: string;
+}
+
+export interface OcrDropzoneProps {
+  onFileSelect?: (file: File) => void;
+  onDetect?: (results: TextResult[] | string) => void;
+  autoDetect?: boolean;
+  detectOptions?: DetectTextOptions;
+  accept?: string;
+  className?: string;
+  style?: CSSProperties;
+}

package/src/types/context.ts

@@ -0,0 +1,18 @@
+import type { InitializeConfig } from '@rustors/web';
+import type { OcrService } from '../services/ocrService.js';
+
+export type RustoStatus = 'idle' | 'initializing' | 'ready' | 'error';
+
+export interface RustoContextValue {
+  status: RustoStatus;
+  isReady: boolean;
+  error: Error | null;
+  initialize: (config?: InitializeConfig) => Promise<void>;
+  service: OcrService;
+}
+
+export interface RustoProviderProps {
+  children: React.ReactNode;
+  config?: InitializeConfig;
+  autoInitialize?: boolean;
+}

package/src/types/hooks.ts

@@ -0,0 +1,22 @@
+import type {
+  DetectTextOptions,
+  ImageSource,
+  TextResult,
+} from '@rustors/web';
+
+export interface UseOcrOptions extends DetectTextOptions {
+  onSuccess?: (results: TextResult[] | string) => void;
+  onError?: (error: Error) => void;
+}
+
+export interface UseOcrReturn {
+  detect: (
+    source: ImageSource,
+    overrideOptions?: DetectTextOptions
+  ) => Promise<TextResult[] | string>;
+  results: TextResult[];
+  spatialText: string;
+  isProcessing: boolean;
+  error: Error | null;
+  reset: () => void;
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './context.js';
+export * from './hooks.js';
+export * from './components.js';

package/src/utils/formatters.ts

@@ -0,0 +1,27 @@
+import type { TextResult } from '@rustors/web';
+
+/**
+ * Combines all recognized text tokens into a single text block.
+ */
+export function resultsToText(results: TextResult[]): string {
+  return results.map((r) => r.text).join('\n');
+}
+
+/**
+ * Formats OCR results into standard CSV with bounding box coordinates and scores.
+ */
+export function resultsToCsv(results: TextResult[]): string {
+  const header = 'text,score,left,top,width,height';
+  const rows = results.map((r) => {
+    const escapedText = `"${r.text.replace(/"/g, '""')}"`;
+    return `${escapedText},${r.score.toFixed(4)},${r.frame.left},${r.frame.top},${r.frame.width},${r.frame.height}`;
+  });
+  return [header, ...rows].join('\n');
+}
+
+/**
+ * Pretty formats OCR results as a JSON string.
+ */
+export function resultsToJson(results: TextResult[], indent: number = 2): string {
+  return JSON.stringify(results, null, indent);
+}

package/src/utils/geometry.ts

@@ -0,0 +1,36 @@
+import type { Frame } from '@rustors/web';
+
+export type QuadPoints = [[number, number], [number, number], [number, number], [number, number]];
+
+export function scaleFrame(frame: Frame, scaleX: number, scaleY: number): Frame {
+  return {
+    left: Math.round(frame.left * scaleX * 100) / 100,
+    top: Math.round(frame.top * scaleY * 100) / 100,
+    width: Math.round(frame.width * scaleX * 100) / 100,
+    height: Math.round(frame.height * scaleY * 100) / 100,
+  };
+}
+
+export function scaleQuad(quad: QuadPoints, scaleX: number, scaleY: number): QuadPoints {
+  return [
+    [Math.round(quad[0][0] * scaleX * 100) / 100, Math.round(quad[0][1] * scaleY * 100) / 100],
+    [Math.round(quad[1][0] * scaleX * 100) / 100, Math.round(quad[1][1] * scaleY * 100) / 100],
+    [Math.round(quad[2][0] * scaleX * 100) / 100, Math.round(quad[2][1] * scaleY * 100) / 100],
+    [Math.round(quad[3][0] * scaleX * 100) / 100, Math.round(quad[3][1] * scaleY * 100) / 100],
+  ];
+}
+
+export function calculateScale(
+  naturalWidth: number,
+  naturalHeight: number,
+  renderWidth: number,
+  renderHeight: number
+): { scaleX: number; scaleY: number } {
+  if (naturalWidth <= 0 || naturalHeight <= 0 || renderWidth <= 0 || renderHeight <= 0) {
+    return { scaleX: 1, scaleY: 1 };
+  }
+  return {
+    scaleX: renderWidth / naturalWidth,
+    scaleY: renderHeight / naturalHeight,
+  };
+}