@octane-xplat/image-crop 0.0.1 → 0.10.0

package/src/geometry.ts

@@ -0,0 +1,163 @@
+import type {
+	Crop,
+	CropConstraints,
+	CropHandle,
+	ImageFrame,
+	PercentCrop,
+	PixelCrop,
+	Size,
+} from './props'
+
+const positive = (n: number) => (Number.isFinite(n) && n > 0 ? n : 0)
+const finite = (n: number) => (Number.isFinite(n) ? n : 0)
+const clamp = (n: number, low: number, high: number) =>
+	Math.min(Math.max(n, Math.min(low, high)), high)
+
+/** Displayed image rectangle inside a centered contain-fit viewport. */
+export function containFrame(view: Size, natural: Size): ImageFrame {
+	const scale =
+		natural.width > 0 && natural.height > 0
+			? Math.min(positive(view.width) / natural.width, positive(view.height) / natural.height)
+			: 0
+
+	const width = positive(natural.width * scale),
+		height = positive(natural.height * scale)
+
+	return {
+		x: (positive(view.width) - width) / 2,
+		y: (positive(view.height) - height) / 2,
+		width,
+		height,
+	}
+}
+
+export function convertToPixelCrop(crop: Crop, size: Size): PixelCrop {
+	const sx = crop.unit === '%' ? positive(size.width) / 100 : 1
+	const sy = crop.unit === '%' ? positive(size.height) / 100 : 1
+	return {
+		unit: 'px',
+		x: finite(crop.x) * sx,
+		y: finite(crop.y) * sy,
+		width: positive(crop.width) * sx,
+		height: positive(crop.height) * sy,
+	}
+}
+
+export function convertToPercentCrop(crop: Crop, size: Size): PercentCrop {
+	const p = convertToPixelCrop(crop, size)
+	return {
+		unit: '%',
+		x: size.width > 0 ? (p.x / size.width) * 100 : 0,
+		y: size.height > 0 ? (p.y / size.height) * 100 : 0,
+		width: size.width > 0 ? (p.width / size.width) * 100 : 0,
+		height: size.height > 0 ? (p.height / size.height) * 100 : 0,
+	}
+}
+
+/** Convert displayed-image coordinates to natural pixels for a separate pixel exporter. */
+export function toNaturalCrop(crop: Crop, displayed: Size, natural: Size): PixelCrop {
+	const p = convertToPercentCrop(crop, displayed)
+	return convertToPixelCrop(p, natural)
+}
+
+export function fromNaturalCrop(crop: PixelCrop, natural: Size, displayed: Size): PixelCrop {
+	return convertToPixelCrop(convertToPercentCrop(crop, natural), displayed)
+}
+
+/** Clamp external controlled input. Impossible minimums yield to bounds/maxima. */
+export function constrainCrop(crop: Crop, size: Size, limits: CropConstraints = {}): PixelCrop {
+	const p = convertToPixelCrop(crop, size)
+	const maxW = Math.min(
+		positive(size.width),
+		limits.maxWidth === undefined ? Infinity : positive(limits.maxWidth),
+	)
+
+	const maxH = Math.min(
+		positive(size.height),
+		limits.maxHeight === undefined ? Infinity : positive(limits.maxHeight),
+	)
+
+	let width = clamp(p.width, positive(limits.minWidth ?? 0), maxW)
+	let height = clamp(p.height, positive(limits.minHeight ?? 0), maxH)
+	const aspect = positive(limits.aspect ?? 0)
+	if (aspect) {
+		width = clamp(
+			width,
+			Math.max(positive(limits.minWidth ?? 0), positive(limits.minHeight ?? 0) * aspect),
+			Math.min(maxW, maxH * aspect),
+		)
+
+		height = width / aspect
+	}
+
+	return {
+		unit: 'px',
+		x: clamp(p.x, 0, positive(size.width) - width),
+		y: clamp(p.y, 0, positive(size.height) - height),
+		width,
+		height,
+	}
+}
+
+/** Resize from a frozen gesture origin using cumulative view-space deltas. */
+export function dragCrop(
+	start: Crop,
+	handle: CropHandle,
+	dx: number,
+	dy: number,
+	size: Size,
+	limits: CropConstraints = {},
+): PixelCrop {
+	const p = constrainCrop(start, size, limits)
+	dx = finite(dx)
+	dy = finite(dy)
+	if (handle === 'move') {
+		return {
+			...p,
+			x: clamp(p.x + dx, 0, size.width - p.width),
+			y: clamp(p.y + dy, 0, size.height - p.height),
+		}
+	}
+
+	const west = handle.includes('w'),
+		east = handle.includes('e')
+
+	const north = handle.includes('n'),
+		south = handle.includes('s')
+
+	// Corners anchor their opposite corner; side handles anchor the opposite
+	// edge midpoint under aspect lock, so the other axis expands symmetrically.
+	const ax = west ? p.x + p.width : east ? p.x : p.x + p.width / 2
+	const ay = north ? p.y + p.height : south ? p.y : p.y + p.height / 2
+	const boundW = west ? ax : east ? size.width - ax : 2 * Math.min(ax, size.width - ax)
+	const boundH = north ? ay : south ? size.height - ay : 2 * Math.min(ay, size.height - ay)
+	const maxW = Math.min(boundW, limits.maxWidth ?? Infinity)
+	const maxH = Math.min(boundH, limits.maxHeight ?? Infinity)
+	let width = p.width + (west ? -dx : east ? dx : 0)
+	let height = p.height + (north ? -dy : south ? dy : 0)
+	const aspect = positive(limits.aspect ?? 0)
+	if (aspect) {
+		if ((!west && !east) || ((north || south) && Math.abs(dy * aspect) > Math.abs(dx))) {
+			width = height * aspect
+		}
+
+		width = clamp(
+			width,
+			Math.max(positive(limits.minWidth ?? 0), positive(limits.minHeight ?? 0) * aspect),
+			Math.max(0, Math.min(maxW, maxH * aspect)),
+		)
+
+		height = width / aspect
+	} else {
+		width = clamp(width, positive(limits.minWidth ?? 0), Math.max(0, maxW))
+		height = clamp(height, positive(limits.minHeight ?? 0), Math.max(0, maxH))
+	}
+
+	return {
+		unit: 'px',
+		x: west ? ax - width : east ? ax : ax - width / 2,
+		y: north ? ay - height : south ? ay : ay - height / 2,
+		width,
+		height,
+	}
+}

package/src/index.macos.ts

@@ -0,0 +1,12 @@
+export { ImageCrop } from './ImageCrop'
+export {
+	containFrame,
+	constrainCrop,
+	convertToPixelCrop,
+	convertToPercentCrop,
+	toNaturalCrop,
+	fromNaturalCrop,
+	dragCrop,
+} from './geometry'
+
+export type * from './props'

package/src/index.ts

@@ -0,0 +1,12 @@
+export { ImageCrop } from './ImageCrop'
+export {
+	containFrame,
+	constrainCrop,
+	convertToPixelCrop,
+	convertToPercentCrop,
+	toNaturalCrop,
+	fromNaturalCrop,
+	dragCrop,
+} from './geometry'
+
+export type * from './props'

package/src/index.web.ts

@@ -0,0 +1,12 @@
+export { ImageCrop } from './ImageCrop'
+export {
+	containFrame,
+	constrainCrop,
+	convertToPixelCrop,
+	convertToPercentCrop,
+	toNaturalCrop,
+	fromNaturalCrop,
+	dragCrop,
+} from './geometry'
+
+export type * from './props'

package/src/props.ts

@@ -0,0 +1,57 @@
+export interface Crop {
+	x: number
+	y: number
+	width: number
+	height: number
+	unit: 'px' | '%'
+}
+
+export interface PixelCrop extends Crop {
+	unit: 'px'
+}
+
+export interface PercentCrop extends Crop {
+	unit: '%'
+}
+
+export interface Size {
+	width: number
+	height: number
+}
+
+export interface ImageFrame extends Size {
+	x: number
+	y: number
+}
+
+export type CropHandle = 'move' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw'
+export interface CropConstraints {
+	/** Fixed width / height ratio in displayed coordinates. */
+	aspect?: number
+	/** Minimum displayed width in pixels / DIPs, including for percentage crops. */
+	minWidth?: number
+	/** Minimum displayed height in pixels / DIPs, including for percentage crops. */
+	minHeight?: number
+	maxWidth?: number
+	maxHeight?: number
+}
+
+export interface ImageCropProps extends CropConstraints {
+	src: string
+	alt?: string
+	/** Natural image dimensions; must match the decoded, oriented source. */
+	imageWidth: number
+	imageHeight: number
+	/** Controlled crop relative to the contained image, excluding letterboxing. */
+	crop: Crop
+	/** Update crop with either argument; both describe the same selection. */
+	onChange: (pixelCrop: PixelCrop, percentCrop: PercentCrop) => void
+	/** Called once on gesture end; cancellation does not complete. */
+	onComplete?: (pixelCrop: PixelCrop, percentCrop: PercentCrop) => void
+	disabled?: boolean
+	ruleOfThirds?: boolean
+	/** Frame dimensions in CSS pixels / native DIPs. */
+	width: number
+	height: number
+	id?: string
+}

package/types/generated/.tsrx-typegen-manifest.json

@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "files": [
+    "Gesture.d.ts",
+    "Gesture.macos.d.ts",
+    "Gesture.web.d.ts",
+    "Guide.d.ts",
+    "Guide.macos.d.ts",
+    "Guide.web.d.ts",
+    "ImageCrop.d.ts",
+    "Source.d.ts",
+    "Source.macos.d.ts",
+    "Source.web.d.ts",
+    "geometry.d.ts",
+    "index.d.ts",
+    "index.macos.d.ts",
+    "index.web.d.ts",
+    "props.d.ts"
+  ]
+}

package/types/generated/Gesture.d.ts

@@ -0,0 +1,2 @@
+import type { ViewProps } from '@octane-xplat/ui';
+export declare function Gesture(props: ViewProps): unknown;

package/types/generated/Gesture.macos.d.ts

@@ -0,0 +1,2 @@
+import type { ViewProps } from '@octane-xplat/ui';
+export declare function Gesture(props: ViewProps): unknown;

package/types/generated/Gesture.web.d.ts

@@ -0,0 +1,2 @@
+import type { ViewProps } from '@octane-xplat/ui';
+export declare function Gesture(props: ViewProps): import("octane/jsx-runtime").JSX.Element;

package/types/generated/Guide.d.ts

@@ -0,0 +1,2 @@
+import type { ViewProps } from '@octane-xplat/ui';
+export declare function Guide(props: ViewProps): unknown;

package/types/generated/Guide.macos.d.ts

@@ -0,0 +1,2 @@
+import type { ViewProps } from '@octane-xplat/ui';
+export declare function Guide(props: ViewProps): unknown;

package/types/generated/Guide.web.d.ts

@@ -0,0 +1,2 @@
+import type { ViewProps } from '@octane-xplat/ui';
+export declare function Guide(props: ViewProps): import("octane/jsx-runtime").JSX.Element;

package/types/generated/ImageCrop.d.ts

@@ -0,0 +1,3 @@
+import type { ImageCropProps } from './props.js';
+/**  Inline controlled selection. View.onPan delegates to the UI usePan leaves. */
+export declare function ImageCrop(props: ImageCropProps): import("octane/jsx-runtime").JSX.Element;

package/types/generated/Source.d.ts

@@ -0,0 +1,2 @@
+import type { ImageCropProps } from './props.js';
+export declare function Source(props: Pick<ImageCropProps, 'src' | 'alt' | 'width' | 'height'>): unknown;

package/types/generated/Source.macos.d.ts

@@ -0,0 +1,2 @@
+import type { ImageCropProps } from './props.js';
+export declare function Source(props: Pick<ImageCropProps, 'src' | 'alt' | 'width' | 'height'>): unknown;

package/types/generated/Source.web.d.ts

@@ -0,0 +1,2 @@
+import type { ImageCropProps } from './props.js';
+export declare function Source(props: Pick<ImageCropProps, 'src' | 'alt' | 'width' | 'height'>): import("octane/jsx-runtime").JSX.Element;

package/types/generated/geometry.d.ts

@@ -0,0 +1,12 @@
+import type { Crop, CropConstraints, CropHandle, ImageFrame, PercentCrop, PixelCrop, Size } from './props.js';
+/** Displayed image rectangle inside a centered contain-fit viewport. */
+export declare function containFrame(view: Size, natural: Size): ImageFrame;
+export declare function convertToPixelCrop(crop: Crop, size: Size): PixelCrop;
+export declare function convertToPercentCrop(crop: Crop, size: Size): PercentCrop;
+/** Convert displayed-image coordinates to natural pixels for a separate pixel exporter. */
+export declare function toNaturalCrop(crop: Crop, displayed: Size, natural: Size): PixelCrop;
+export declare function fromNaturalCrop(crop: PixelCrop, natural: Size, displayed: Size): PixelCrop;
+/** Clamp external controlled input. Impossible minimums yield to bounds/maxima. */
+export declare function constrainCrop(crop: Crop, size: Size, limits?: CropConstraints): PixelCrop;
+/** Resize from a frozen gesture origin using cumulative view-space deltas. */
+export declare function dragCrop(start: Crop, handle: CropHandle, dx: number, dy: number, size: Size, limits?: CropConstraints): PixelCrop;

package/types/generated/index.d.ts

@@ -0,0 +1,3 @@
+export { ImageCrop } from './ImageCrop.js';
+export { containFrame, constrainCrop, convertToPixelCrop, convertToPercentCrop, toNaturalCrop, fromNaturalCrop, dragCrop, } from './geometry.js';
+export type * from './props.js';

package/types/generated/index.macos.d.ts

@@ -0,0 +1,3 @@
+export { ImageCrop } from './ImageCrop.js';
+export { containFrame, constrainCrop, convertToPixelCrop, convertToPercentCrop, toNaturalCrop, fromNaturalCrop, dragCrop, } from './geometry.js';
+export type * from './props.js';

package/types/generated/index.web.d.ts

@@ -0,0 +1,3 @@
+export { ImageCrop } from './ImageCrop.js';
+export { containFrame, constrainCrop, convertToPixelCrop, convertToPercentCrop, toNaturalCrop, fromNaturalCrop, dragCrop, } from './geometry.js';
+export type * from './props.js';

package/types/generated/props.d.ts

@@ -0,0 +1,51 @@
+export interface Crop {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    unit: 'px' | '%';
+}
+export interface PixelCrop extends Crop {
+    unit: 'px';
+}
+export interface PercentCrop extends Crop {
+    unit: '%';
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface ImageFrame extends Size {
+    x: number;
+    y: number;
+}
+export type CropHandle = 'move' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
+export interface CropConstraints {
+    /** Fixed width / height ratio in displayed coordinates. */
+    aspect?: number;
+    /** Minimum displayed width in pixels / DIPs, including for percentage crops. */
+    minWidth?: number;
+    /** Minimum displayed height in pixels / DIPs, including for percentage crops. */
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+}
+export interface ImageCropProps extends CropConstraints {
+    src: string;
+    alt?: string;
+    /** Natural image dimensions; must match the decoded, oriented source. */
+    imageWidth: number;
+    imageHeight: number;
+    /** Controlled crop relative to the contained image, excluding letterboxing. */
+    crop: Crop;
+    /** Update crop with either argument; both describe the same selection. */
+    onChange: (pixelCrop: PixelCrop, percentCrop: PercentCrop) => void;
+    /** Called once on gesture end; cancellation does not complete. */
+    onComplete?: (pixelCrop: PixelCrop, percentCrop: PercentCrop) => void;
+    disabled?: boolean;
+    ruleOfThirds?: boolean;
+    /** Frame dimensions in CSS pixels / native DIPs. */
+    width: number;
+    height: number;
+    id?: string;
+}