@scaleflex/crop 2.0.1

package/dist/react/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-B-csHwK2.cjs");exports.DEFAULT_CONFIG=e.DEFAULT_CONFIG;exports.SfxCrop=e.SfxCrop;exports.createCropController=e.createCropController;exports.mergeConfig=e.mergeConfig;exports.useSfxCrop=e.useSfxCrop;exports.useSfxCropController=e.useSfxCropController;
+//# sourceMappingURL=index.cjs.map

package/dist/react/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * React entry for `@scaleflex/crop/react`.
+ *
+ * Exports:
+ *   - `SfxCrop` — forwardRef component rendering `<sfx-crop>`
+ *   - `useSfxCrop` — hook variant for consumers that render the element manually
+ *   - `SfxCropElement`, `SfxCropProps`, `SfxCropSaveDetail` — types
+ *
+ * The wrapper dynamically imports `../define` on module load so the custom
+ * element auto-registers whenever this module is evaluated in the browser.
+ * SSR-safe: the import is guarded behind a `typeof customElements` check.
+ */
+export { SfxCrop } from './sfx-crop';
+export type { SfxCropProps, SfxCropElement, SfxCropSaveDetail } from './sfx-crop';
+export { useSfxCrop } from './use-sfx-crop';
+export type { UseSfxCropReturn } from './use-sfx-crop';
+export { useSfxCropController } from './use-sfx-crop-controller';
+export type { UseSfxCropControllerOptions, UseSfxCropControllerReturn, CropControllerState, CropControllerActions, CropControllerApi, } from './use-sfx-crop-controller';
+export { createCropController, DEFAULT_CONFIG, mergeConfig } from '../index';
+export type { CropController, CropControllerOptions, CropControllerCallbacks, SfxCropConfig, } from '../index';
+export type { TransformState, TransformParams, CropShapeName, CropShape, CropRect, NormalizedRect, HandlePosition, Point, Size, CropIconOverrides, } from '../core/types';

package/dist/react/index.js

@@ -0,0 +1,10 @@
+import { D as e, S as s, c as C, m as a, u as f, b as p } from "./index-CktjrogS.js";
+export {
+  e as DEFAULT_CONFIG,
+  s as SfxCrop,
+  C as createCropController,
+  a as mergeConfig,
+  f as useSfxCrop,
+  p as useSfxCropController
+};
+//# sourceMappingURL=index.js.map

package/dist/react/sfx-crop.d.ts

@@ -0,0 +1,86 @@
+import { CSSProperties } from 'react';
+import { SfxCropElement } from '../elements/sfx-crop';
+import { CropShapeName, CropRect, TransformState, TransformParams, CropIconOverrides } from '../core/types';
+export type { SfxCropElement };
+export interface SfxCropSaveDetail {
+    blob: Blob;
+    dataURL: string;
+    params: TransformParams;
+}
+export interface SfxCropProps {
+    src?: string;
+    /** `'classic'` (default) or `'fixed'` — see `<sfx-crop>` `variant`. */
+    variant?: 'classic' | 'fixed';
+    cropShape?: CropShapeName;
+    theme?: 'light' | 'dark';
+    initialCrop?: CropRect | null;
+    initialRotation?: number;
+    initialScale?: number;
+    minScale?: number;
+    maxScale?: number;
+    minCropSize?: number;
+    availableShapes?: CropShapeName[];
+    /** Per-slot icon overrides — see `CropIconOverrides` in the core types. */
+    icons?: CropIconOverrides;
+    handleSize?: number;
+    handleColor?: string;
+    borderRadius?: number;
+    overlayColor?: string;
+    outputType?: string;
+    outputQuality?: number;
+    maxOutputWidth?: number;
+    maxOutputHeight?: number;
+    showGrid?: boolean | 'interaction';
+    showToolbar?: boolean;
+    showRotateSlider?: boolean;
+    showZoomSlider?: boolean;
+    showShapeSelector?: boolean;
+    showRotateButton?: boolean;
+    showFlipButton?: boolean;
+    toolbarPosition?: 'top' | 'bottom';
+    showBleedMargin?: boolean;
+    bleedMarginSize?: number;
+    bleedMarginColor?: string;
+    enableAnimations?: boolean;
+    animationSpeed?: number;
+    keyboard?: boolean;
+    pinchZoom?: boolean;
+    wheelZoom?: boolean;
+    onReady?: (detail: {
+        element: SfxCropElement;
+    }) => void;
+    onImageLoad?: (detail: {
+        image: HTMLImageElement;
+    }) => void;
+    onChange?: (state: TransformState) => void;
+    onCropChange?: (crop: CropRect) => void;
+    onSave?: (detail: SfxCropSaveDetail) => void;
+    onCancel?: () => void;
+    onError?: (detail: {
+        error: Error;
+    }) => void;
+    className?: string;
+    style?: CSSProperties;
+    id?: string;
+}
+/**
+ * `<SfxCrop>` — React wrapper around the `<sfx-crop>` custom element.
+ *
+ * Pattern follows `@scaleflex/uploader`'s React wrapper: hand-rolled
+ * `forwardRef` + dynamic `import('../define')` at module load to auto-register
+ * the element, + `useEffect` bridges from CustomEvent to prop callbacks.
+ *
+ * Stale-closure avoidance: the latest props sit in a mutable ref updated on
+ * every render. The event-bridge `useEffect` attaches listeners once and
+ * reads `cbRef.current.on*` at fire time — no re-subscription on re-render.
+ *
+ * Prop sync: runs on every render without a deps array. Operations are
+ * idempotent (Lit compares before assigning), so the cost is a cheap walk
+ * of FORWARDED_PROPS.
+ *
+ * The ref is the bare element. The factory runs after React's commit phase,
+ * so `ref.current` is non-null once a parent component can actually read it.
+ * If you need to access methods before the first commit (e.g. during render),
+ * guard with `ref.current?.method?.()` or wait for `sfx-crop-ready`.
+ */
+export declare const SfxCrop: import('react').ForwardRefExoticComponent<SfxCropProps & import('react').RefAttributes<SfxCropElement>>;

package/dist/react/use-sfx-crop-controller.d.ts

@@ -0,0 +1,74 @@
+import { CropController } from '../core/crop-controller';
+import { SfxCropConfig, TransformState, TransformParams, CropRect, CropShapeName } from '../core/types';
+/**
+ * Headless options for {@link useSfxCropController}. Most fields mirror the
+ * built-in element's attributes, minus UI toggles that are irrelevant when
+ * the consumer provides their own UI.
+ */
+export type UseSfxCropControllerOptions = Partial<SfxCropConfig>;
+/** Reactive snapshot exposed by the hook. */
+export interface CropControllerState {
+    /** Current editor transform (rotation, flip, scale, pan, crop). */
+    state: TransformState;
+    cropRect: CropRect;
+    cropShape: CropShapeName;
+    scale: number;
+    rotation: number;
+    loading: boolean;
+    error: string | null;
+    /** `true` once the editor has a decoded image and the render loop is live. */
+    ready: boolean;
+}
+/** Imperative actions — stable identity across renders. */
+export interface CropControllerActions {
+    loadImage(src: string): Promise<void>;
+    rotateLeft(): void;
+    flipHorizontal(): void;
+    setRotation(deg: number): void;
+    setScale(scale: number): void;
+    setCropShape(shape: CropShapeName): void;
+    setCropRect(rect: CropRect): void;
+    reset(): void;
+}
+/** Export / query surface — stable identity across renders. */
+export interface CropControllerApi {
+    toCanvas(): HTMLCanvasElement | null;
+    toBlob(type?: string, quality?: number): Promise<Blob | null>;
+    toDataURL(type?: string, quality?: number): string | null;
+    toTransformParams(): TransformParams | null;
+    /** Underlying controller handle (null until both refs are attached). */
+    getController(): CropController | null;
+}
+export interface UseSfxCropControllerReturn extends CropControllerState {
+    /** Attach to your `<canvas>` node. */
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    /** Attach to a sizing box (e.g. a `<div>` with `max-width`/`max-height`). */
+    containerRef: React.RefObject<HTMLElement | null>;
+    actions: CropControllerActions;
+    api: CropControllerApi;
+}
+/**
+ * Headless React hook — wraps {@link createCropController} so a consumer can
+ * drop a `<canvas>` + sizing container anywhere in their tree and wire up
+ * their own UI (their design-system buttons, sliders, modals, etc.). The
+ * hook never mounts `<sfx-crop>`; there is no Lit, no shadow DOM, no
+ * built-in toolbar.
+ *
+ * Usage:
+ * ```tsx
+ * const { canvasRef, containerRef, state, actions, api } = useSfxCropController({
+ *   src: '/photo.jpg',
+ *   cropShape: '16:9',
+ * });
+ *
+ * return (
+ *   <div ref={containerRef} style={{ maxWidth: 1200, maxHeight: 640 }}>
+ *     <canvas ref={canvasRef} style={{ width: '100%', height: '100%' }} />
+ *     <button onClick={actions.rotateLeft}>Rotate</button>
+ *     <input type="range" min={0.5} max={5} step={0.01}
+ *            value={state.scale} onChange={(e) => actions.setScale(+e.target.value)} />
+ *   </div>
+ * );
+ * ```
+ */
+export declare function useSfxCropController(options?: UseSfxCropControllerOptions): UseSfxCropControllerReturn;

package/dist/react/use-sfx-crop.d.ts

@@ -0,0 +1,31 @@
+import { SfxCropElement } from '../elements/sfx-crop';
+import { CropRect, CropShapeName, TransformState, TransformParams } from '../core/types';
+export interface UseSfxCropReturn {
+    /** Attach this ref to your `<sfx-crop ref={ref}>` (or the React `SfxCrop`). */
+    ref: React.RefObject<SfxCropElement | null>;
+    /** Fires after the editor has loaded the image and the renderer is live. */
+    ready: boolean;
+    loadImage(src: string): Promise<void>;
+    rotateLeft(): void;
+    flipHorizontal(): void;
+    setRotation(deg: number): void;
+    setScale(scale: number): void;
+    setCropShape(shape: CropShapeName): void;
+    setCropRect(rect: CropRect): void;
+    getCropRect(): CropRect | null;
+    getTransformState(): TransformState | null;
+    reset(): void;
+    toCanvas(): HTMLCanvasElement | null;
+    toBlob(type?: string, quality?: number): Promise<Blob | null>;
+    toDataURL(type?: string, quality?: number): string | null;
+    toTransformParams(): TransformParams | null;
+    save(type?: string, quality?: number): Promise<void>;
+    cancel(): void;
+}
+/**
+ * Hook variant of the React wrapper — returns a ref to bind plus stable
+ * callables for imperative operations. Prefer the `<SfxCrop>` component for
+ * declarative usage; reach for this hook when you need to render the element
+ * yourself or share imperative access across multiple components.
+ */
+export declare function useSfxCrop(): UseSfxCropReturn;

package/dist/styles/shared.css.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Design tokens — sourced from the @scaleflex/ui-tw kit
+ * (packages/ui/src/styles/variables.css). Color values are exact OKLCH
+ * copies of the kit's --background / --foreground / --primary / etc., so
+ * a page that theme-embeds both <sfx-crop> and the ui-tw components
+ * shares a single palette. Override any token from light DOM, e.g.
+ * `<sfx-crop style="--sfx-cr-primary:oklch(0.6 0.18 280)">`.
+ *
+ * Light is the default; `theme="dark"` mirrors the kit's `:root.dark`.
+ * Tokens cascade through shadow boundaries via CSS custom-property
+ * inheritance, so sub-elements never redeclare them.
+ */
+export declare const designTokens: import('lit').CSSResult;
+export declare const baseStyles: import('lit').CSSResult;
+export declare const spinKeyframes: import('lit').CSSResult;
+export declare const toolbarEnterKeyframes: import('lit').CSSResult;
+export declare const zoomEnterKeyframes: import('lit').CSSResult;
+export declare const modalInKeyframes: import('lit').CSSResult;
+/** Shared slider-thumb styling used by zoom + rotate inputs. */
+export declare const sliderThumbStyles: import('lit').CSSResult;

package/dist/transforms/constrain.d.ts

@@ -0,0 +1,68 @@
+import { CropRect, CropShapeName, TransformState } from '../core/types';
+/**
+ * Parse a free-form aspect-ratio string like `"16:9"`, `"7:2"`, or `"11:8"`
+ * into a numeric ratio. Supports positive integers or decimals. Returns
+ * `null` if the input isn't a valid W:H pair — consumers can then treat it
+ * as a named shape (`'free'`, `'square'`, …) or reject it.
+ */
+export declare function parseRatio(name: string): number | null;
+/**
+ * Get the numeric aspect ratio for a crop shape. Handles the named shapes
+ * (`free`, `square`, `circle`, `rounded-rect`) and every built-in preset
+ * (`"16:9"`, etc.), plus any other `"W:H"` string a consumer passes in.
+ * Returns `null` for free-form (no ratio constraint).
+ */
+export declare function getAspectRatio(shape: CropShapeName | string): number | null;
+/** Clamp crop rect to stay within [0,1] image bounds. Spec section 8.3. */
+export declare function clampCropToImage(crop: CropRect): CropRect;
+/** Enforce aspect ratio on crop rect during resize. Spec section 8.3. */
+export declare function enforceAspectRatio(crop: CropRect, ratio: number | null, handle: string, imageWidth: number, imageHeight: number, minSize: number): CropRect;
+export declare function enforceMinSize(crop: CropRect, minSize: number, imageWidth: number, imageHeight: number): CropRect;
+/** Compute minimum scale needed to cover the crop area at a given rotation. */
+export declare function computeMinScale(imageWidth: number, imageHeight: number, canvasWidth: number, canvasHeight: number, rotation: number): number;
+/**
+ * Cover constraint: keep the photo fully covering a target frame so the crop
+ * never exports transparent gaps. Returns the `scale` / `panX` / `panY` to use
+ * plus the (capped) minimum scale below which coverage breaks.
+ *
+ * The frame is given in container CSS px and may be **off-centre** (the classic
+ * movable crop rect) or the whole editor box (the fixed variant). The photo is
+ * always drawn centred in the container; pan is stored in container CSS px
+ * relative to the image centre, and the live draw places the image centre at
+ * `scale * pan` px from the container centre (see `image-layer.ts` —
+ * translate(center)→scale→translate(pan)). The math works in CSS px and divides
+ * the slack by `scale`.
+ *
+ * `drawW0` / `drawH0` are the photo's draw size **at scale 1** in container px —
+ * the caller passes the model that matches the actual render: cover-fit
+ * (`computeCoverDraw`) in the fixed variant, or the stretched container box
+ * (`w × h`) in classic. This keeps the clamp aligned with what's drawn even
+ * when the editor box aspect diverges from the image aspect.
+ *
+ * Fine tilt (`state.rotation`) inflates the frame to its axis-aligned bounding
+ * box (conservative). Flip is a no-op (mirrors about the centre).
+ *
+ * `maxScale` caps the cover floor: if covering the frame would need more zoom
+ * than the consumer allows, the floor is pinned to `maxScale` (so the returned
+ * `minScale ≤ maxScale` and the renderer's scale bounds never invert — at the
+ * cost of a residual gap, which is an unavoidable min/max-scale conflict).
+ */
+export declare function clampCoverPanScale(state: TransformState, containerW: number, containerH: number, frame: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, drawW0: number, drawH0: number, maxScale: number): {
+    scale: number;
+    panX: number;
+    panY: number;
+    minScale: number;
+};
+/** Snap rotation near 0 within threshold. */
+export declare function snapRotation(degrees: number, threshold?: number): number;
+/** Constrain scale to range. */
+export declare function constrainScale(scale: number, minScale: number, maxScale: number): number;
+/** @deprecated Use clampCropToImage instead */
+export declare const constrainCropBounds: typeof clampCropToImage;
+/** @deprecated Use enforceAspectRatio instead */
+export declare const constrainAspectRatio: typeof enforceAspectRatio;

package/dist/transforms/matrix.d.ts

@@ -0,0 +1,23 @@
+import { TransformState, Size, Point } from '../core/types';
+/** 2D affine transform matrix [a, b, c, d, e, f] (same layout as canvas). */
+export type Matrix2D = [number, number, number, number, number, number];
+export declare function identityMatrix(): Matrix2D;
+export declare function multiplyMatrices(a: Matrix2D, b: Matrix2D): Matrix2D;
+export declare function translateMatrix(tx: number, ty: number): Matrix2D;
+export declare function scaleMatrix(sx: number, sy: number): Matrix2D;
+export declare function rotateMatrix(degrees: number): Matrix2D;
+/** @internal Build matrix as 6-element tuple. */
+export declare function buildMatrix2D(canvasCx: number, canvasCy: number, rotation90: number, rotationFine: number, flipH: number, scale: number, panX: number, panY: number): Matrix2D;
+/** Apply matrix to a point. */
+export declare function transformPoint(m: Matrix2D, x: number, y: number): {
+    x: number;
+    y: number;
+};
+/** Invert a 2D affine matrix. */
+export declare function invertMatrix(m: Matrix2D): Matrix2D;
+/** Build the full image transform matrix. Spec section 8.2. */
+export declare function buildTransformMatrix(state: TransformState, canvasSize: Size, _imageSize: Size): DOMMatrix;
+/** Convert a point from image space to canvas space. Spec section 8.2. */
+export declare function imageToCanvas(point: Point, matrix: DOMMatrix): Point;
+/** Convert a point from canvas space to image space. Spec section 8.2. */
+export declare function canvasToImage(point: Point, matrix: DOMMatrix): Point;

package/dist/transforms/transform-state.d.ts

@@ -0,0 +1,12 @@
+import { TransformState, CropRect, CropShapeName, HandlePosition } from '../core/types';
+export declare function createInitialState(cropShape?: CropShapeName, imageWidth?: number, imageHeight?: number): TransformState;
+export declare function applyRotateLeft(state: TransformState): TransformState;
+export declare function applyFlipH(state: TransformState): TransformState;
+export declare function applyFlipV(state: TransformState): TransformState;
+export declare function applyRotation(state: TransformState, degrees: number): TransformState;
+export declare function applyScale(state: TransformState, scale: number, minScale: number, maxScale: number): TransformState;
+export declare function applyCropMove(state: TransformState, cropRect: CropRect): TransformState;
+export declare function applyShapeChange(state: TransformState, shape: CropShapeName, imageWidth?: number, imageHeight?: number): TransformState;
+export declare function applyPan(state: TransformState, dx: number, dy: number): TransformState;
+/** Pure crop resize — spec section 8.1. dx/dy in normalized [0,1] space. */
+export declare function applyCropResize(state: TransformState, handle: HandlePosition, dx: number, dy: number, cropShape?: CropShapeName, minCropSize?: number, imageWidth?: number, imageHeight?: number): TransformState;

package/dist/utils/events.d.ts

@@ -0,0 +1,16 @@
+type EventHandler = (...args: any[]) => void;
+export declare class EventEmitter {
+    private listeners;
+    private onceMap;
+    on(event: string, handler: EventHandler): void;
+    off(event: string, handler: EventHandler): void;
+    emit(event: string, ...args: any[]): void;
+    once(event: string, handler: EventHandler): void;
+    removeAllListeners(): void;
+}
+export declare function addListener(el: EventTarget, event: string, handler: EventListenerOrEventListenerObject, options?: AddEventListenerOptions): () => void;
+export type ThrottledFunction<T extends (...args: any[]) => void> = T & {
+    cancel(): void;
+};
+export declare function throttle<T extends (...args: any[]) => void>(fn: T, ms: number): ThrottledFunction<T>;
+export {};

package/dist/utils/math.d.ts

@@ -0,0 +1,12 @@
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function lerp(a: number, b: number, t: number): number;
+export declare function degreesToRadians(degrees: number): number;
+export declare function radiansToDegrees(radians: number): number;
+export declare function distance(x1: number, y1: number, x2: number, y2: number): number;
+export declare function normalizeAngle(degrees: number): number;
+/** Spring interpolation — returns new current value moving toward target. */
+export declare function spring(current: number, target: number, velocity: {
+    v: number;
+}, stiffness: number, damping: number, dt: number): number;
+/** Check if a point is inside a rotated rectangle. */
+export declare function pointInRotatedRect(px: number, py: number, cx: number, cy: number, w: number, h: number, angle: number): boolean;

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@scaleflex/crop",
+  "version": "2.0.1",
+  "description": "Interactive image crop tool with rotation, flip, zoom and shape selection — Scaleflex Web Component",
+  "license": "MIT",
+  "author": "Scaleflex",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "import": "./dist/define.js",
+      "require": "./dist/define.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "dist/define.js",
+    "dist/define.cjs",
+    "src/define.ts"
+  ],
+  "scripts": {
+    "dev": "vite --config config/vite.demo.config.ts",
+    "build": "npm run build:bundle && npm run build:react",
+    "build:bundle": "vite build --config config/vite.config.ts",
+    "build:react": "vite build --config config/vite.react.config.ts",
+    "build:demo": "vite build --config config/vite.demo.config.ts",
+    "build:cdn": "vite build --config config/vite.cdn.config.ts",
+    "release": "node scripts/release-cdn.mjs plugin",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/ tests/ --ext .ts,.tsx",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "lit": "^3.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-react-hooks": "^4.6.2",
+    "jsdom": "^25.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.0.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "crop",
+    "image",
+    "editor",
+    "canvas",
+    "rotation",
+    "flip",
+    "zoom",
+    "cloudimage",
+    "scaleflex",
+    "web-component",
+    "lit",
+    "react"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scaleflex/image-crop.git"
+  },
+  "bugs": {
+    "url": "https://github.com/scaleflex/image-crop/issues"
+  },
+  "homepage": "https://scaleflex.github.io/image-crop/"
+}