@nice2dev/ui-graphics 1.0.0

package/dist/types/photo/faceDetection.d.ts

@@ -0,0 +1,103 @@
+/**
+ * faceDetection — Face detection for auto-crop and photo analysis
+ *
+ * Provides face detection using:
+ * 1. Pure JS skin-tone + edge detection heuristics (fast, no deps)
+ * 2. Optional face-api.js integration (accurate, requires loading models)
+ *
+ * Features:
+ * - Face region detection
+ * - Face count estimation
+ * - Auto-crop suggestions
+ * - Face landmarks (with face-api.js)
+ * - Expression detection (with face-api.js)
+ */
+export interface FaceRegion {
+    /** Bounding box */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Detection confidence (0-1) */
+    confidence: number;
+    /** Face landmarks (if available) */
+    landmarks?: FaceLandmarks;
+    /** Estimated expression (if available) */
+    expression?: FaceExpression;
+}
+export interface FaceLandmarks {
+    leftEye: {
+        x: number;
+        y: number;
+    };
+    rightEye: {
+        x: number;
+        y: number;
+    };
+    nose: {
+        x: number;
+        y: number;
+    };
+    mouthLeft: {
+        x: number;
+        y: number;
+    };
+    mouthRight: {
+        x: number;
+        y: number;
+    };
+    jawOutline?: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+export type FaceExpression = 'neutral' | 'happy' | 'sad' | 'angry' | 'fearful' | 'disgusted' | 'surprised';
+export interface FaceDetectionOptions {
+    /** Minimum face size (relative to image, 0-1) */
+    minFaceSize: number;
+    /** Maximum number of faces to detect */
+    maxFaces: number;
+    /** Detection quality */
+    quality: 'fast' | 'accurate';
+    /** Include landmarks detection */
+    detectLandmarks: boolean;
+    /** Include expression detection */
+    detectExpressions: boolean;
+}
+export interface FaceDetectionResult {
+    /** Detected faces */
+    faces: FaceRegion[];
+    /** Processing time in ms */
+    processingTimeMs: number;
+    /** Detection method used */
+    method: 'heuristic' | 'neural';
+}
+export interface AutoCropSuggestion {
+    /** Suggested crop rectangle */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Aspect ratio used */
+    aspectRatio: number;
+    /** Crop type */
+    type: 'portrait' | 'headshot' | 'group' | 'full';
+}
+export declare const DEFAULT_DETECTION_OPTIONS: FaceDetectionOptions;
+/**
+ * Generate auto-crop suggestion based on detected faces
+ */
+export declare function generateAutoCropSuggestion(faces: FaceRegion[], imageWidth: number, imageHeight: number, targetAspectRatio?: number): AutoCropSuggestion | null;
+/**
+ * Generate multiple crop suggestions for common aspect ratios
+ */
+export declare function generateMultipleCropSuggestions(faces: FaceRegion[], imageWidth: number, imageHeight: number): AutoCropSuggestion[];
+/**
+ * Detect faces in an image
+ */
+export declare function detectFaces(imageData: ImageData, options?: Partial<FaceDetectionOptions>): Promise<FaceDetectionResult>;
+/**
+ * Quick face detection (always uses heuristic for speed)
+ */
+export declare function detectFacesFast(imageData: ImageData, maxFaces?: number): FaceRegion[];
+export default detectFaces;

package/dist/types/photo/index.d.ts

@@ -0,0 +1,17 @@
+export { default as PhotoEditor } from './PhotoEditor';
+export { usePhotoEditor } from './usePhotoEditor';
+export type * from './photoEditorTypes';
+export * from './photoFilters';
+export * from './photoOverlays';
+export * from './photoSelection';
+export * from './photoEditorActions';
+export { applyStyleTransfer, generateStylePreviews, downscaleForPreview, upscaleFromPreview, STYLE_PRESETS, DEFAULT_STYLE_OPTIONS, type StylePreset, type StyleTransferOptions, } from './aiStyleTransfer';
+export { StyleTransferPanel } from './StyleTransferPanel';
+export { loadRawFile, extractMetadata, extractPreview, isRawFile, detectFormatFromExtension, detectFormatFromHeader, RAW_EXTENSIONS, ALL_RAW_EXTENSIONS, DEFAULT_RAW_OPTIONS, type RawFormat, type RawMetadata, type RawProcessingOptions, type RawLoadResult } from './rawFileSupport';
+export { RawFilePanel } from './RawFilePanel';
+export { detectFaces, detectFacesFast, generateAutoCropSuggestion, type FaceRegion, type FaceDetectionOptions, type AutoCropSuggestion } from './faceDetection';
+export { FaceDetectionPanel } from './FaceDetectionPanel';
+export { applyPerspectiveTransform, computePerspectiveTransform, detectDocumentEdges, createRectQuad, getQuadBounds, isPointInQuad, getNearestCorner, moveQuadCorner, getQuadArea, identityMatrix, multiplyMatrices, invertMatrix, transformPoint, PERSPECTIVE_PRESETS, type Quad, type Matrix3x3, type PerspectiveSettings, type CornerHandle, type PerspectivePreset, type UsePerspectiveCorrectionOptions, } from './perspectiveCorrection';
+export { PerspectiveCorrectionPanel } from './PerspectiveCorrectionPanel';
+export * from './batchProcessing';
+export { BatchProcessingPanel } from './BatchProcessingPanel';

package/dist/types/photo/perspectiveCorrection.d.ts

@@ -0,0 +1,134 @@
+/**
+ * perspectiveCorrection.ts
+ * Perspective correction and transformation utilities for PhotoEditor
+ */
+/** 2D Point */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** Quad defined by four corners */
+export interface Quad {
+    topLeft: Point;
+    topRight: Point;
+    bottomRight: Point;
+    bottomLeft: Point;
+}
+/** 3x3 Transformation matrix */
+export type Matrix3x3 = [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+    number
+];
+/** Perspective correction settings */
+export interface PerspectiveSettings {
+    /** Source quad corners */
+    sourceQuad: Quad;
+    /** Target quad corners (usually rectangle) */
+    targetQuad: Quad;
+    /** Interpolation method */
+    interpolation: 'nearest' | 'bilinear' | 'bicubic';
+    /** Maintain aspect ratio */
+    maintainAspect: boolean;
+    /** Output width */
+    outputWidth: number;
+    /** Output height */
+    outputHeight: number;
+}
+/** Corner handle being dragged */
+export type CornerHandle = 'topLeft' | 'topRight' | 'bottomRight' | 'bottomLeft';
+/** Preset perspective correction */
+export interface PerspectivePreset {
+    name: string;
+    description: string;
+    sourceQuad: Quad;
+}
+/**
+ * Create identity matrix
+ */
+export declare function identityMatrix(): Matrix3x3;
+/**
+ * Multiply two 3x3 matrices
+ */
+export declare function multiplyMatrices(a: Matrix3x3, b: Matrix3x3): Matrix3x3;
+/**
+ * Invert 3x3 matrix
+ */
+export declare function invertMatrix(m: Matrix3x3): Matrix3x3 | null;
+/**
+ * Transform point using matrix
+ */
+export declare function transformPoint(p: Point, m: Matrix3x3): Point;
+/**
+ * Calculate perspective transformation matrix from quad to quad
+ */
+export declare function computePerspectiveTransform(src: Quad, dst: Quad): Matrix3x3;
+/**
+ * Apply perspective transform to image data
+ */
+export declare function applyPerspectiveTransform(sourceData: ImageData, settings: PerspectiveSettings): ImageData;
+/**
+ * Create rectangle quad
+ */
+export declare function createRectQuad(x: number, y: number, width: number, height: number): Quad;
+/**
+ * Calculate bounding box of quad
+ */
+export declare function getQuadBounds(quad: Quad): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Check if point is inside quad
+ */
+export declare function isPointInQuad(point: Point, quad: Quad): boolean;
+/**
+ * Get nearest corner handle to point
+ */
+export declare function getNearestCorner(point: Point, quad: Quad, threshold?: number): CornerHandle | null;
+/**
+ * Move corner of quad
+ */
+export declare function moveQuadCorner(quad: Quad, corner: CornerHandle, newPos: Point): Quad;
+/**
+ * Calculate quad area
+ */
+export declare function getQuadArea(quad: Quad): number;
+/**
+ * Detect document/paper edges in image
+ * Returns suggested quad corners
+ */
+export declare function detectDocumentEdges(imageData: ImageData, options?: {
+    edgeThreshold?: number;
+    minArea?: number;
+}): Quad | null;
+/**
+ * Perspective correction presets
+ */
+export declare const PERSPECTIVE_PRESETS: PerspectivePreset[];
+export interface UsePerspectiveCorrectionOptions {
+    imageWidth: number;
+    imageHeight: number;
+}
+export declare function usePerspectiveCorrection(options: UsePerspectiveCorrectionOptions): {
+    sourceQuad: Quad;
+    setSourceQuad: import("react").Dispatch<import("react").SetStateAction<Quad>>;
+    interpolation: "nearest" | "bilinear" | "bicubic";
+    setInterpolation: import("react").Dispatch<import("react").SetStateAction<"nearest" | "bilinear" | "bicubic">>;
+    maintainAspect: boolean;
+    setMaintainAspect: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    activeCorner: CornerHandle | null;
+    setActiveCorner: import("react").Dispatch<import("react").SetStateAction<CornerHandle | null>>;
+    resetQuad: () => void;
+    moveCorner: (corner: CornerHandle, newPos: Point) => void;
+    applyPreset: (preset: PerspectivePreset) => void;
+    getSettings: () => PerspectiveSettings;
+};

package/dist/types/photo/photoEditorActions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * photoEditorActions.ts — Pure helper functions for photo export, download,
+ * clipboard copy, and native share in PhotoEditor.
+ */
+import { type AdjustmentValues, type FilterParams } from "./photoFilters";
+import { type Overlay } from "./photoOverlays";
+export interface ExportParams {
+    image: HTMLImageElement;
+    selectedFilter: string;
+    filterParams: FilterParams;
+    filterIntensity: number;
+    adjustments: AdjustmentValues;
+    cropRect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    rotation: number;
+    flipH: boolean;
+    flipV: boolean;
+    overlays: Overlay[];
+}
+/**
+ * Render the current editor state to a JPEG Blob for export.
+ */
+export declare function getExportBlob(params: ExportParams): Promise<Blob | null>;
+/**
+ * Trigger a browser download of the given Blob as "photo-edited.jpg".
+ */
+export declare function handleDownloadBlob(blob: Blob): void;
+/**
+ * Copy the current editor output to clipboard as PNG.
+ */
+export declare function handleCopyImageToClipboard(params: ExportParams): Promise<void>;
+/**
+ * Use the Web Share API to share the exported image.
+ * Falls back to download if sharing is not supported.
+ */
+export declare function handleNativeShare(blob: Blob): Promise<void>;

package/dist/types/photo/photoEditorTypes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * photoEditorTypes.ts — Shared types and constants for PhotoEditor.
+ */
+import type { AdjustmentValues } from "./photoFilters";
+export interface PhotoEditorProps {
+    /** Image source — File, Blob, or URL string */
+    src: File | Blob | string;
+    /** Player colour accent */
+    playerColor?: string;
+    /** Called with the edited File (+ serialised editor state) when user clicks Save */
+    onSave: (file: File, editorStateJson?: string) => void;
+    /** Called when user cancels editing */
+    onCancel: () => void;
+    /** Previously stored editor-state JSON to restore (if re-editing) */
+    initialState?: string | null;
+}
+export type EditorTab = "filters" | "adjust" | "crop" | "transform" | "stickers" | "text" | "shapes" | "draw";
+export type FilterCategory = "all" | "color" | "light" | "vintage" | "artistic" | "fun";
+export declare const TAB_DEFS: {
+    key: EditorTab;
+    icon: string;
+    label: string;
+}[];
+export declare const ASPECT_RATIOS: {
+    label: string;
+    value: number | null;
+}[];
+export declare const ADJUSTMENT_SLIDERS: {
+    key: keyof AdjustmentValues;
+    label: string;
+    min: number;
+    max: number;
+    icon: string;
+}[];

package/dist/types/photo/photoFilters.d.ts

@@ -0,0 +1,55 @@
+/**
+ * photoFilters.ts — Canvas-based photo filter engine.
+ *
+ * Pure functions that operate on ImageData pixel arrays.
+ * Each filter takes ImageData + optional params and returns a new ImageData.
+ * Composable via `applyFilterChain`.
+ */
+export interface FilterParams {
+    /** Intensity 0..1 (default 1 = full effect) */
+    intensity?: number;
+    [key: string]: unknown;
+}
+export interface FilterDefinition {
+    id: string;
+    name: string;
+    /** Category for UI grouping */
+    category: 'color' | 'light' | 'artistic' | 'vintage' | 'fun' | 'adjustment';
+    /** Emoji icon for quick visual */
+    icon: string;
+    /** Apply filter to pixel data */
+    apply: (data: ImageData, params?: FilterParams) => ImageData;
+    /** Default params */
+    defaults?: FilterParams;
+}
+export interface AdjustmentValues {
+    brightness: number;
+    contrast: number;
+    saturation: number;
+    temperature: number;
+    tint: number;
+    exposure: number;
+    highlights: number;
+    shadows: number;
+    sharpness: number;
+    vignette: number;
+    grain: number;
+    blur: number;
+}
+export declare const DEFAULT_ADJUSTMENTS: AdjustmentValues;
+export declare function applyVignette(ctx: CanvasRenderingContext2D, w: number, h: number, amount: number): void;
+export declare function applyGrain(ctx: CanvasRenderingContext2D, w: number, h: number, amount: number): void;
+export declare const PHOTO_FILTERS: FilterDefinition[];
+/** Get filter by ID */
+export declare function getFilter(id: string): FilterDefinition | undefined;
+/** Apply adjustments to ImageData */
+export declare function applyAdjustments(data: ImageData, adj: Partial<AdjustmentValues>): ImageData;
+/** Full pipeline: filter + adjustments → canvas, then vignette & grain via context */
+export declare function renderToCanvas(canvas: HTMLCanvasElement, sourceImage: HTMLImageElement, filterId: string, filterParams: FilterParams, adjustments: Partial<AdjustmentValues>, cropRect?: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | null, rotation?: number, flipH?: boolean, flipV?: boolean): void;
+/** Export canvas as File (for upload) */
+export declare function canvasToFile(canvas: HTMLCanvasElement, filename?: string, quality?: number): Promise<File>;

package/dist/types/photo/photoOverlays.d.ts

@@ -0,0 +1,126 @@
+/**
+ * photoOverlays.ts — Overlay / layer engine for PhotoEditor.
+ *
+ * Handles emojis, text, shapes, freehand drawing strokes, and decorative frames
+ * as positioned layers on top of the base (filtered) image.
+ *
+ * All positions use **fractional coordinates** (0 … 1) relative to the rendered
+ * canvas so overlays survive crop / resize changes.
+ */
+import type { AdjustmentValues } from "./photoFilters";
+export type OverlayType = "emoji" | "text" | "shape" | "drawing" | "frame";
+export interface BaseOverlay {
+    id: string;
+    type: OverlayType;
+    /** Centre X as fraction of canvas width  (0 … 1) */
+    x: number;
+    /** Centre Y as fraction of canvas height (0 … 1) */
+    y: number;
+    scaleX: number;
+    scaleY: number;
+    /** Degrees */
+    rotation: number;
+    /** 0 … 1 */
+    opacity: number;
+}
+export interface EmojiOverlay extends BaseOverlay {
+    type: "emoji";
+    emoji: string;
+    /** Base font size in px (before scale) */
+    fontSize: number;
+}
+export interface TextOverlay extends BaseOverlay {
+    type: "text";
+    text: string;
+    fontFamily: string;
+    fontSize: number;
+    color: string;
+    bold: boolean;
+    italic: boolean;
+    outlineColor: string | null;
+    outlineWidth: number;
+    shadow: string | null;
+    background: string | null;
+    backgroundPadding: number;
+}
+export type ShapeKind = "rect" | "circle" | "triangle" | "star" | "heart" | "arrow" | "diamond" | "hexagon" | "cross" | "lightning";
+export interface ShapeOverlay extends BaseOverlay {
+    type: "shape";
+    shapeKind: ShapeKind;
+    /** Base width / height in px */
+    width: number;
+    height: number;
+    fillColor: string | null;
+    strokeColor: string;
+    strokeWidth: number;
+}
+export interface DrawingStroke {
+    /** Array of [x, y] fractions (0 … 1) */
+    points: [number, number][];
+    color: string;
+    width: number;
+    opacity: number;
+}
+export interface DrawingOverlay extends BaseOverlay {
+    type: "drawing";
+    strokes: DrawingStroke[];
+}
+export type FrameStyleId = "simple" | "double" | "rounded" | "polaroid" | "film" | "vintage" | "ornate" | "shadow" | "neon" | "torn";
+export interface FrameOverlay extends BaseOverlay {
+    type: "frame";
+    frameStyle: FrameStyleId;
+    color: string;
+    /** Border thickness as fraction of min(w,h) */
+    thickness: number;
+}
+export type Overlay = EmojiOverlay | TextOverlay | ShapeOverlay | DrawingOverlay | FrameOverlay;
+export interface EmojiCategory {
+    id: string;
+    label: string;
+    icon: string;
+    emojis: string[];
+}
+export declare const EMOJI_CATALOG: EmojiCategory[];
+export interface ShapeDef {
+    id: ShapeKind;
+    label: string;
+    icon: string;
+}
+export declare const SHAPE_CATALOG: ShapeDef[];
+export interface FrameStyleDef {
+    id: FrameStyleId;
+    label: string;
+    icon: string;
+}
+export declare const FRAME_CATALOG: FrameStyleDef[];
+export declare function generateOverlayId(): string;
+/** Render all overlays to a canvas context. */
+export declare function renderAllOverlays(ctx: CanvasRenderingContext2D, overlays: Overlay[], w: number, h: number): void;
+export declare function renderLiveStroke(ctx: CanvasRenderingContext2D, points: [number, number][], color: string, width: number, canvasW: number, canvasH: number): void;
+/**
+ * Returns `true` when the point (px, py) in canvas-fraction space
+ * hits the bounding box of the overlay (ignoring rotation).
+ */
+export declare function hitTestOverlay(ov: Overlay, px: number, py: number, _w: number, _h: number): boolean;
+export declare function createEmojiOverlay(emoji: string, canvasW: number, canvasH: number): EmojiOverlay;
+export declare function createTextOverlay(text?: string): TextOverlay;
+export declare function createShapeOverlay(kind: ShapeKind): ShapeOverlay;
+export declare function createDrawingOverlay(): DrawingOverlay;
+export declare function createFrameOverlay(style: FrameStyleId, color?: string): FrameOverlay;
+export interface PhotoEditorState {
+    filter: string;
+    filterIntensity: number;
+    adjustments: AdjustmentValues;
+    rotation: number;
+    flipH: boolean;
+    flipV: boolean;
+    cropRect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    overlays: Overlay[];
+}
+export declare function serializeEditorState(state: PhotoEditorState): string;
+export declare function deserializeEditorState(json: string): PhotoEditorState | null;

package/dist/types/photo/photoSelection.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Smart selection tools for PhotoEditor
+ * Implements magic wand, lasso selection, and healing brush
+ */
+export interface SelectionMask {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export type SelectionMode = 'replace' | 'add' | 'subtract' | 'intersect';
+export declare function createEmptyMask(width: number, height: number): SelectionMask;
+export declare function createFullMask(width: number, height: number): SelectionMask;
+export declare function invertMask(mask: SelectionMask): SelectionMask;
+export declare function combineMasks(maskA: SelectionMask, maskB: SelectionMask, mode: SelectionMode): SelectionMask;
+export declare function featherMask(mask: SelectionMask, radius: number): SelectionMask;
+export interface MagicWandOptions {
+    tolerance: number;
+    contiguous: boolean;
+    antiAlias: boolean;
+    feather: number;
+}
+export declare function magicWandSelect(imageData: ImageData, startX: number, startY: number, options?: Partial<MagicWandOptions>): SelectionMask;
+export interface LassoOptions {
+    feather: number;
+    antiAlias: boolean;
+}
+export declare function lassoSelect(width: number, height: number, points: Point[], options?: Partial<LassoOptions>): SelectionMask;
+/** Magnetic lasso - snaps to edges in image */
+export declare function magneticLassoPoint(imageData: ImageData, x: number, y: number, searchRadius?: number): Point;
+export interface ColorRangeOptions {
+    fuzziness: number;
+    feather: number;
+}
+export declare function selectColorRange(imageData: ImageData, targetColor: {
+    r: number;
+    g: number;
+    b: number;
+}, options?: Partial<ColorRangeOptions>): SelectionMask;
+export interface HealingBrushOptions {
+    radius: number;
+    hardness: number;
+    opacity: number;
+    mode: 'heal' | 'clone';
+}
+/** Apply healing brush at destination using source area */
+export declare function applyHealingBrush(imageData: ImageData, srcX: number, srcY: number, dstX: number, dstY: number, options?: Partial<HealingBrushOptions>): ImageData;
+/** Simple content-aware fill using surrounding pixels */
+export declare function contentAwareFill(imageData: ImageData, mask: SelectionMask): ImageData;
+/** Render marching ants selection outline */
+export declare function renderSelectionOutline(ctx: CanvasRenderingContext2D, mask: SelectionMask, offset?: number): void;
+/** Apply mask as alpha to ImageData */
+export declare function applyMaskToImageData(imageData: ImageData, mask: SelectionMask, invert?: boolean): ImageData;