@bensitu/image-editor 1.5.2 → 2.1.0

package/dist/types/ui/ui-state.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Disabled-state, aria-state, and toolbar-state helpers used by
+ * {@link ImageEditor}'s `init` and operation handlers. These
+ * helpers share the same `idMap`-driven element-resolution
+ * vocabulary as `dom-bindings.ts` so the orchestrator can speak
+ * one language when wiring or refreshing UI state.
+ *
+ * ## Owned contracts
+ *
+ * - Bound DOM controls live in the orchestrator's
+ *   bindings registry and are addressed by logical {@link ElementKey}.
+ *   These helpers consume the same key vocabulary so toolbar-state updates
+ *   stay aligned with what `dom-bindings.ts` originally bound.
+ * - Toolbar-state mutation must remain a no-op when
+ *   the editor is disposed or when a logical key is unmapped. Each helper
+ *   short-circuits on a missing element ID or missing DOM node so
+ *   post-`dispose` `updateUi`-style calls cannot throw or surprise the
+ *   host page.
+ *
+ * ## Why this lives in its own module
+ *
+ * Splitting low-level DOM state out keeps `image-editor.ts` focused on
+ * toolbar policy while helpers here own native DOM writes such as setting
+ * `disabled` by logical key.
+ *
+ * Like `dom-bindings.ts` and `visibility-state.ts`, this module is imported
+ * by `image-editor.ts` only and is intentionally NOT re-exported from
+ * `src/index.ts`.
+ *
+ * @module
+ */
+import type { ElementIdMap } from '../core/public-types.js';
+/**
+ * Logical element-name keys understood by the editor's `idMap`. Matches the
+ * `ElementKey` alias exported from `dom-bindings.ts` so the orchestrator's
+ * registry and the toolbar-state helpers can be driven from the same
+ * lookup function without crossing the public-types boundary.
+ */
+export type ElementKey = keyof Required<ElementIdMap>;
+/**
+ * Callback used by every helper in this module to translate a logical
+ * {@link ElementKey} to the resolved DOM element ID supplied by the host
+ * page through `idMap`. Returning a falsy value (`null`, `undefined`, or
+ * empty string) means the host omitted that key — helpers MUST treat that
+ * as a no-op rather than a bug.
+ */
+export type ElementIdResolver = (key: ElementKey) => string | null | undefined;
+/**
+ * Set the native `disabled` IDL property on a button-like control resolved
+ * from `key`. Used by the orchestrator's `updateUi` policy: each toolbar
+ * button maps to one logical key, and the policy decides whether the
+ * button is currently usable.
+ *
+ * Behaviour:
+ *
+ * - If `resolveElementId(key)` returns a falsy value, the helper returns
+ *   without touching the DOM (the integrator chose not to wire that
+ *   control).
+ * - If `document.getElementById(id)` returns `null`, the helper returns
+ *   without throwing. A missing node is a partial-DOM scenario, not a
+ *   fatal error.
+ * - Otherwise the resolved element's `disabled` property is set to the
+ *   requested boolean. Using the IDL property (not `setAttribute`)
+ *   keeps the keyboard/click behaviour the
+ *   browser provides "for free" on real `<button>` elements.
+ *
+ * The element is typed as `HTMLButtonElement` because every key in the
+ * documented toolbar set (`zoomInButton`, `applyCropButton`, …) resolves to a
+ * `<button>`. A non-button host element will still receive the `disabled`
+ * assignment via the IDL slot but will not visually reflect it; that is
+ * the integrator's responsibility per the public `idMap` contract.
+ *
+ * @param resolveElementId - Resolver from logical key to DOM element ID.
+ * @param key - Logical toolbar element key.
+ * @param disabled - Target `disabled` value.
+ */
+export declare function setDisabled(resolveElementId: ElementIdResolver, key: ElementKey, disabled: boolean): void;
+/**
+ * Set the `aria-disabled` attribute on the element resolved from `key`.
+ * Useful for non-button toolbar controls (links, custom widgets) that do
+ * not honour the native `disabled` IDL property but still need to expose
+ * disabled state to assistive technology.
+ *
+ * Behaviour mirrors {@link setDisabled}: missing key or missing element
+ * results in a silent no-op. The attribute value is
+ * always the canonical string `'true'` or `'false'` as required by the
+ * ARIA spec — never the empty string and never removed entirely, so a
+ * subsequent toggle is a single `setAttribute` away.
+ *
+ * @param resolveElementId - Resolver from logical key to DOM element ID.
+ * @param key - Logical toolbar element key.
+ * @param disabled - Target `aria-disabled` value.
+ */
+export declare function setAriaDisabled(resolveElementId: ElementIdResolver, key: ElementKey, disabled: boolean): void;
+/**
+ * Toggle a CSS class on the element resolved from `key`. Used for toolbar
+ * state that does not correspond to `disabled` / `aria-disabled` — for
+ * example, marking the active mask in the mask list or flipping a button
+ * into a "pressed" visual style during crop mode.
+ *
+ * The helper delegates to `Element.classList.toggle(className, force)`, so
+ * the caller's `enabled` flag deterministically adds or removes the class
+ * regardless of its current presence. Missing key or missing element is a
+ * silent no-op.
+ *
+ * @param resolveElementId - Resolver from logical key to DOM element ID.
+ * @param key - Logical toolbar element key.
+ * @param className - CSS class name to toggle.
+ * @param enabled - `true` to add the class, `false` to remove it.
+ */
+export declare function setClass(resolveElementId: ElementIdResolver, key: ElementKey, className: string, enabled: boolean): void;
+//# sourceMappingURL=ui-state.d.ts.map

package/dist/types/ui/ui-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-state.d.ts","sourceRoot":"","sources":["../../../src/ui/ui-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CACvB,gBAAgB,EAAE,iBAAiB,EACnC,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,OAAO,GAClB,IAAI,CAKN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC3B,gBAAgB,EAAE,iBAAiB,EACnC,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,OAAO,GAClB,IAAI,CAKN;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CACpB,gBAAgB,EAAE,iBAAiB,EACnC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,GACjB,IAAI,CAKN"}

package/dist/types/ui/visibility-state.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Placeholder/canvas-container visibility helper. Owns the
+ * standard-DOM-state transition that the orchestrator's
+ * private `_setPlaceholderVisible` method delegates to.
+ *
+ * ## Owned contracts
+ *
+ * - `setPlaceholderVisible(..., true)` SHALL set the
+ *   placeholder's `hidden` to `false` and `aria-hidden` to `'false'`, and
+ *   SHALL set the canvas container's `hidden` to `true` and `aria-hidden`
+ *   to `'true'`.
+ * - `setPlaceholderVisible(..., false)` SHALL set the
+ *   placeholder's `hidden` to `true` and `aria-hidden` to `'true'`, and
+ *   SHALL set the canvas container's `hidden` to `false` and `aria-hidden`
+ *   to `'false'`.
+ * - This module SHALL NOT add or remove the
+ *   Bootstrap `d-none` class on either element. The host page is free to
+ *   style `[hidden]` however it likes; the editor stays out of utility-class
+ *   territory so it works with or without Bootstrap.
+ * - When `containerElement` is `null`, the
+ *   placeholder's `hidden` and `aria-hidden` SHALL still be updated
+ *   correctly. A missing container is a partial-DOM scenario, not a fatal
+ *   error.
+ *
+ * ## Why this lives in its own module
+ *
+ * The helper uses standard DOM state instead of Bootstrap utility classes so
+ * the editor works with or without a host stylesheet. Keeping the transition
+ * here makes the orchestrator's private method a one-line delegate and keeps
+ * the behavior unit-testable in isolation. This module is imported by
+ * `image-editor.ts` only and is intentionally not re-exported from
+ * `src/index.ts`.
+ *
+ * @module
+ */
+/**
+ * Toggle placeholder/canvas-container visibility using only standard DOM
+ * state. The function is total: it never throws on null inputs and never
+ * touches utility classes.
+ *
+ * Visibility semantics:
+ *
+ * - `show === true` means **show the placeholder** (and therefore hide the
+ *   canvas container). The placeholder is the "no image yet" affordance, so
+ *   showing it implies the live canvas is not the right thing to render.
+ * - `show === false` means **hide the placeholder** (and therefore show the
+ *   canvas container). This is the post-`loadImage` steady state.
+ *
+ * In both branches the function:
+ *
+ * 1. Sets the DOM `hidden` property. Using the
+ *    property — not the attribute — keeps the IDL flag and the reflected
+ *    attribute in sync without an extra `setAttribute` call.
+ * 2. Sets `aria-hidden` to the matching string so assistive technology
+ *    tracks the visual state.
+ * 3. Leaves every other class and inline style untouched. In particular,
+ *    Bootstrap's `d-none` is never added or removed,
+ *    which lets the editor coexist with host pages that use `d-none` for
+ *    their own purposes.
+ *
+ * When `containerElement` is `null` (partial DOM, or a host page that does
+ * not wrap the canvas in a dedicated container), the placeholder side of
+ * the transition still runs to completion. When
+ * `placeholderElement` is `null` the function is a no-op for that side; the
+ * orchestrator's `updatePlaceholderStatus` already early-returns in that
+ * case, but defending here keeps the helper safe to call from any future
+ * code path.
+ *
+ * @param placeholderElement - The placeholder DOM element shown when no image is loaded, or `null`
+ *   when the host page omitted the placeholder slot from the `idMap`.
+ * @param containerElement - The canvas container DOM element wrapping the live `<canvas>`, or
+ *   `null` when no container is available.
+ * @param show - `true` to make the placeholder visible (and hide the canvas container);
+ *   `false` to hide the placeholder (and show the canvas container).
+ */
+export declare function setPlaceholderVisible(placeholderElement: HTMLElement | null, containerElement: HTMLElement | null, show: boolean): void;
+//# sourceMappingURL=visibility-state.d.ts.map

package/dist/types/ui/visibility-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility-state.d.ts","sourceRoot":"","sources":["../../../src/ui/visibility-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,qBAAqB,CACjC,kBAAkB,EAAE,WAAW,GAAG,IAAI,EACtC,gBAAgB,EAAE,WAAW,GAAG,IAAI,EACpC,IAAI,EAAE,OAAO,GACd,IAAI,CAgBN"}

package/dist/types/utils/canvas-region.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Pure helpers that turn floating-point Fabric.js bounding
+ * rectangles into integer pixel regions and provide the
+ * bounding-box math that mask preservation across crop and
+ * export paths share.
+ *
+ * ## Owned contracts
+ *
+ * - Export regions SHALL include partially covered trailing pixels so
+ *   sub-pixel image bounds do not lose the right or bottom edge.
+ * - Crop regions SHALL exclude trailing partial pixels so crop does not
+ *   grow by a transparent row or column.
+ * - When `applyCrop` runs with
+ *   `preserveMasksAfterCrop === true` and the image has been rotated,
+ *   each mask's new `left` and `top` SHALL be expressed in the cropped
+ *   image's coordinate frame using the rotation angle.
+ * - Across a crop apply, each mask's `angle`,
+ *   `scaleX`, and `scaleY` SHALL be preserved so the visible shape does
+ *   not change size or orientation.
+ *
+ * ## Why a dedicated module
+ *
+ * Region math is shared by export, crop, expand-to-image sizing, and crop
+ * rectangle initialization. Centralizing it prevents one call site from
+ * drifting from the others (for example, applying `Math.floor` instead of
+ * `Math.round`, or forgetting the `width >= 1` floor).
+ *
+ * ## Design notes
+ *
+ * - Region floors are total: any non-finite input collapses to a
+ *   `1×1` region anchored at `(0, 0)` rather than throwing. The export
+ *   and crop pipelines already validate the presence of an
+ *   `originalImage` upstream, so a defensive fallback here keeps the
+ *   `<canvas>.drawImage` call from being passed `NaN` if Fabric ever
+ *   reports a degenerate bounding rect.
+ * - `getObjectBBox` calls `setCoords` before reading the bounding
+ *   rect because Fabric.js v7's `getBoundingRect` returns the cached
+ *   absolute rect; without the refresh a freshly-mutated mask returns
+ *   stale coordinates. Callers that have already refreshed coords pay
+ *   only a single redundant call, which is cheaper than double-tracking
+ *   "is this object's cache fresh?" at every site.
+ * - `clampRegionToCanvas` exists for the crop pipeline, where the crop
+ *   rectangle's bounding rect can briefly exceed the canvas after a
+ *   user drag near the edge; clamping before the `drawImage` keeps the
+ *   blit inside the source canvas.
+ *
+ * ## Non-goals
+ *
+ * - This module does not perform any coordinate transformation between
+ *   pre-crop and post-crop frames; the rotation math for the
+ *   rotated-mask coordinate frame lives in `crop/crop-controller.ts`,
+ *   which uses
+ *   `getObjectBBox` here only as one input to that calculation.
+ * - This module does not mutate the Fabric object passed to
+ *   `getObjectBBox` beyond the `setCoords` refresh required by
+ *   Fabric.js v7's API.
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+/**
+ * A canvas region whose `left` / `top` / `width` / `height` are all
+ * integer pixels suitable for `CanvasRenderingContext2D.drawImage` and
+ * Fabric.js `toDataURL({ left, top, width, height})`.
+ *
+ * Produced by {@link floorRegion} and {@link clampRegionToCanvas}; the
+ * `width` and `height` fields are guaranteed to be at least `1` so
+ * region exports never collapse to a zero-pixel image.
+ */
+export interface IntegerRegion {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface RegionRoundingOptions {
+    /**
+     * When true, `right` / `bottom` are ceiled to include partially covered
+     * trailing pixels. When false, they are floored to exclude them.
+     * @default true
+     */
+    includePartialPixels?: boolean;
+}
+export interface PartialExportEdges {
+    left: boolean;
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+}
+export declare function hasMeaningfulCanvasRegion(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, canvasWidth?: number, canvasHeight?: number): boolean;
+/**
+ * Convert a floating-point rectangle into an {@link IntegerRegion}.
+ *
+ * - `left` / `top` are floored and clamped to `>= 0` so the region
+ *   never starts before the source canvas's top-left corner.
+ * - `right` / `bottom` are ceiled by default to include partially covered
+ *   trailing pixels, or floored when `includePartialPixels` is false.
+ * - `width` / `height` are derived from those integer edges and clamped
+ *   to `>= 1` so no sub-pixel dimensions reach Fabric's region export.
+ * - Non-finite inputs collapse to a `1×1` region at `(0, 0)` rather than
+ *   propagating `NaN` into the canvas pipeline.
+ *
+ * region floor before mask remapping).
+ *
+ * @param rect - The floating-point bounding rect to discretize.
+ * @returns    An {@link IntegerRegion} safe to pass to `drawImage`.
+ */
+export declare function getClampedCanvasRegion(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, canvasWidth?: number, canvasHeight?: number, options?: RegionRoundingOptions): IntegerRegion;
+export declare function floorRegion(rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}): IntegerRegion;
+export declare function hasFractionalCanvasEdge(value: number): boolean;
+export declare function getPartialExportEdges(bounds: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+} | null, angle?: number): PartialExportEdges | null;
+/**
+ * Read a Fabric.js object's absolute bounding rectangle in canvas-pixel
+ * coordinates.
+ *
+ * `setCoords` is called first because Fabric.js v7's
+ * `getBoundingRect` returns the cached absolute rect — the per-frame
+ * cache the canvas already maintains. Without the refresh a freshly
+ * mutated mask returns stale coordinates, which can make rotated masks
+ * drift after crop.
+ *
+ * The returned rect uses floating-point coordinates; callers that need
+ * integer pixel regions should pipe the result through
+ * {@link floorRegion}.
+ *
+ * @param object - The Fabric.js object to measure.
+ * @returns   The absolute bounding rect in canvas pixels.
+ */
+export declare function getObjectBBox(object: FabricNS.FabricObject): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+/**
+ * Clamp an {@link IntegerRegion} so it fits entirely inside a canvas of
+ * `canvasWidth × canvasHeight` pixels.
+ *
+ * - `left` is clamped to `[0, canvasWidth - 1]`.
+ * - `top` is clamped to `[0, canvasHeight - 1]`.
+ * - `width` is clamped so `left + width <= canvasWidth`.
+ * - `height` is clamped so `top + height <= canvasHeight`.
+ *
+ * The function preserves the `width >= 1` / `height >= 1` invariant
+ * established by {@link floorRegion}, which keeps callers from having
+ * to special-case zero-sized regions when the supplied rect lands
+ * entirely outside the canvas.
+ *
+ * canvas before the mask coordinate remap).
+ *
+ * @param region - The integer region to clamp.
+ * @param canvasWidth - The source canvas's pixel width.
+ * @param canvasHeight - The source canvas's pixel height.
+ * @returns            A clamped {@link IntegerRegion}.
+ */
+export declare function clampRegionToCanvas(region: IntegerRegion, canvasWidth: number, canvasHeight: number): IntegerRegion;
+//# sourceMappingURL=canvas-region.d.ts.map

package/dist/types/utils/canvas-region.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-region.d.ts","sourceRoot":"","sources":["../../../src/utils/canvas-region.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,QAAQ,CAAC;AAExC;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IAClC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,yBAAyB,CACrC,IAAI,EAAE;IACF,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB,EACD,WAAW,CAAC,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,MAAM,GACtB,OAAO,CAkCT;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAClC,IAAI,EAAE;IACF,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB,EACD,WAAW,CAAC,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE,qBAA0B,GACpC,aAAa,CA4Bf;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB,GAAG,aAAa,CAEhB;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED,wBAAgB,qBAAqB,CACjC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,EAC3E,KAAK,SAAI,GACV,kBAAkB,GAAG,IAAI,CAc3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,YAAY,GAAG;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB,CASA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAC/B,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACrB,aAAa,CASf"}

package/dist/types/utils/dom.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DOM micro-helpers used by sizing and visibility flows.
+ *
+ * Kept intentionally small: the editor depends on a single synchronous
+ * reflow primitive after canvas dimension changes, and exposing it as a
+ * named utility lets layout, visibility, and crop flows share the same
+ * documented contract.
+ */
+/**
+ * Force a synchronous layout reflow on `element`.
+ *
+ * Reading an offset/scroll/clientWidth-like property forces the browser
+ * to flush queued style and layout work on the spot, before any further
+ * script runs. The editor relies on this after `Canvas.setDimensions`
+ * so a container with `overflow: auto` shows or hides scrollbars before
+ * the next paint, instead of waiting for the next frame.
+ *
+ * The read is cast to `void` and isolated in this helper so optimizers
+ * cannot eliminate it as a dead access. The function is a no-op when
+ * `element` is `null` or `undefined`, which keeps callers free of guards in
+ * environments where the container element may not yet be attached.
+ *
+ * @param element - The element whose layout should be flushed. `null` is ignored.
+ */
+export declare function forceReflow(element: HTMLElement | null | undefined): void;
+//# sourceMappingURL=dom.d.ts.map

package/dist/types/utils/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../../src/utils/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAMzE"}

package/dist/types/utils/file.d.ts

@@ -0,0 +1,80 @@
+/**
+ * File-input helpers used by the editor's file-input flow.
+ *
+ * These helpers cover three concerns:
+ *
+ * - Determining whether a `File` selected through the upload control is a
+ *   supported image, including the extension fallback when `file.type` is
+ *   empty (some operating systems and browsers report an empty MIME type
+ *   for known extensions).
+ * - Reading the file as a base64 data URL so the result can be routed
+ *   through the existing transactional `loadImage` pipeline (and therefore
+ *   inherit its rollback behavior on decode/Fabric/timeout failure).
+ * - Resetting the file input value after every attempt so selecting the
+ *   same file again triggers a fresh `change` event.
+ *
+ * The helpers do not call `loadImage` themselves; the orchestrator wires
+ * them into the file-input change handler. That keeps the public
+ * `loadImage` API unchanged beyond `LoadImageOptions`.
+ */
+/**
+ * Supported image extensions and the MIME type each one resolves to.
+ *
+ * Supported file extensions: `png`, `jpg`/`jpeg`, `webp`, `gif`, `bmp`.
+ * GIF and BMP are accepted as static raster input for canvas editing. GIF
+ * animation and GIF/BMP source-format preservation are not retained; exports
+ * are emitted through the editor's JPEG, PNG, or WebP export options.
+ *
+ * Keys are lowercase extensions without the leading `.`.
+ */
+export declare const SUPPORTED_IMAGE_EXTENSIONS: Record<string, string>;
+export declare const SUPPORTED_IMAGE_MIME_TYPES: Set<string>;
+/**
+ * Determine whether a `File` is a supported image and return its resolved
+ * MIME type, or `null` when it should be rejected.
+ *
+ * Resolution order:
+ *
+ * 1. If `file.type` is one of the supported image MIME types, return it
+ *    verbatim.
+ * 2. If `file.type` is empty, infer the MIME type from the file
+ *    extension via {@link SUPPORTED_IMAGE_EXTENSIONS}. This covers the
+ *    case where a browser or OS reports `''` for files with a known
+ *    extension.
+ * 3. Otherwise, return `null` so the caller can skip the load without
+ *    mutating editor state.
+ *
+ * @param file - File selected via the upload control.
+ * @returns The resolved MIME type, or `null` when the file is not a
+ *          supported image.
+ */
+export declare function inferImageMimeType(file: File): string | null;
+/**
+ * Read a `File` as a base64 data URL using `FileReader`.
+ *
+ * The returned data URL is suitable for the transactional `loadImage`
+ * pipeline: on failure the editor's existing
+ * rollback bundle restores placeholder visibility, scroll, overflow,
+ * `originalImage`, `lastSnapshot`, and the canvas JSON snapshot.
+ *
+ * @param file - File to read.
+ * @returns A promise that resolves to the data URL string, or rejects when
+ *          the underlying `FileReader` errors out or returns a non-string
+ *          result.
+ */
+export declare function readFileAsDataUrl(file: File): Promise<string>;
+/**
+ * Reset a file input element's value so selecting the same file again
+ * triggers a fresh `change` event.
+ *
+ * Some browsers reject programmatic assignment to `input.value` on
+ * security grounds; the assignment is wrapped in a `try`/`catch` so the
+ * caller never has to special-case those environments. A `null` input is
+ * a no-op so callers can pass the result of `document.getElementById`
+ * without an extra null check.
+ *
+ * @param input - File input element, or `null` when the element is not
+ *              present in the DOM.
+ */
+export declare function resetFileInput(input: HTMLInputElement | null): void;
+//# sourceMappingURL=file.d.ts.map

package/dist/types/utils/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../../src/utils/file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAO7D,CAAC;AAEF,eAAO,MAAM,0BAA0B,aAAqD,CAAC;AAE7F;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAO5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAOnE"}

package/dist/types/utils/number.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Pure helpers used by `mask/mask-factory.ts` to turn the
+ * flexible `MaskNumericProp` and `PolygonPoint` inputs of
+ * {@link MaskConfig} into concrete numbers and `{ x, y }`
+ * points before a Fabric.js shape is constructed.
+ *
+ * ## Owned contracts
+ *
+ * - `MaskConfig` percentage values supplied for
+ *   `left`, `width`, `rx`, or `radius` SHALL resolve against the canvas
+ *   pixel **width** (axis `'x'`).
+ * - `MaskConfig` percentage values supplied for
+ *   `top`, `height`, or `ry` SHALL resolve against the canvas pixel
+ *   **height** (axis `'y'`).
+ * - A `MaskNumericProp` provided as a function
+ *   SHALL be invoked with `(canvas, ResolvedOptions)` and the returned
+ *   number used directly.
+ * - Polygon point items SHALL be accepted in
+ *   either `{ x, y }` object form or `[x, y]` tuple form and coerced to
+ *   numeric `{ x, y }` internally.
+ *
+ * ## Why a dedicated module
+ *
+ * `resolveNumeric` is axis-aware so horizontal values resolve against
+ * canvas width and vertical values resolve against canvas height.
+ * `coercePoint` lives next to it because both helpers are pure functions
+ * consumed by the same mask-factory pipeline.
+ *
+ * ## Design notes
+ *
+ * - `resolveNumeric` is total: any input that is not a number, a finite
+ *   percentage string, or a function falls through to `fallback` rather
+ *   than throwing.
+ * - Percentages are floored (`Math.floor`) to keep rendered placement
+ *   deterministic across canvas resizes.
+ * - The helper does NOT clamp the result against canvas bounds; callers
+ *   are responsible for any subsequent clamping (the mask factory may
+ *   expand the canvas to accommodate larger placements in expand layout mode).
+ *
+ * ## Non-goals
+ *
+ * - This module does not validate that the supplied `axis` matches the
+ *   field being resolved. Routing each `MaskConfig` field to the correct
+ *   axis is the mask factory's responsibility.
+ * - This module does not coerce or round the output of factory functions
+ *   (`(canvas, options) => number`); their return value is used verbatim
+ *   so consumers retain full control over sub-pixel placement.
+ *
+ * @module
+ */
+import type * as FabricNS from 'fabric';
+import type { MaskNumericProp, PolygonPoint, ResolvedOptions } from '../core/public-types.js';
+/**
+ * Axis selector used by {@link resolveNumeric} to decide which canvas
+ * dimension a percentage value resolves against.
+ *
+ * - `'x'` → `canvas.getWidth`
+ * - `'y'` → `canvas.getHeight`
+ */
+export type Axis = 'x' | 'y';
+/**
+ * Resolve a {@link MaskNumericProp} into a concrete pixel number.
+ *
+ * Resolution rules (in order):
+ * 1. If `val` is a `number`, return it unchanged.
+ * 2. If `val` is a function, invoke it as `val(canvas, options)` and
+ *    return the result.
+ * 3. If `val` is a string ending in `'%'`, parse the leading number,
+ *    multiply by `canvas.getWidth` (axis `'x'`) or
+ *    `canvas.getHeight` (axis `'y'`), floor the product, and return
+ *    it. Strings that do not parse to a
+ *    finite number fall through to `fallback`.
+ * 4. Anything else (including `undefined`, `null`, non-percent strings,
+ *    booleans, etc.) returns `fallback`.
+ *
+ * @example
+ * ```ts
+ * // 50% of an 800px-wide canvas:
+ * resolveNumeric('50%', 'x', 0, canvas, options); // → 400
+ *
+ * // Function form receives the live canvas and ResolvedOptions:
+ * resolveNumeric(
+ *   (canvas) => canvas.getWidth() - 20,
+ *   'x',
+ *   0,
+ *   canvas,
+ *   options,
+ * ); // → canvas.getWidth() - 20
+ *
+ * // Unrecognized input falls back:
+ * resolveNumeric(undefined, 'x', 10, canvas, options); // → 10
+ * ```
+ *
+ * @param val - The flexible mask numeric property to resolve.
+ * @param axis - Which canvas dimension a percentage resolves against.
+ * @param fallback - Value returned when `val` cannot be resolved.
+ * @param canvas - Live Fabric.js canvas; only `getWidth`/`getHeight`
+ *                 are read here, but the entire canvas is forwarded to
+ *                 factory functions.
+ * @param options - Fully-resolved editor options forwarded to factory
+ *                 functions.
+ *
+ * @returns The resolved pixel number, or `fallback` when no rule applies.
+ */
+export declare function resolveNumeric(val: MaskNumericProp | undefined, axis: Axis, fallback: number, canvas: FabricNS.Canvas, options: ResolvedOptions): number;
+/**
+ * Coerce a {@link PolygonPoint} into the canonical `{ x, y }` numeric
+ * shape used by Fabric.js polygon construction.
+ *
+ * Both input forms are accepted so callers may write polygon points in
+ * whichever style is most ergonomic at the call site:
+ *
+ * ```ts
+ * coercePoint({ x: 10, y: 20 }); // → { x: 10, y: 20 }
+ * coercePoint([10, 20]); // → { x: 10, y: 20 }
+ * ```
+ *
+ * Values are coerced via `Number(...)` so string-encoded coordinates
+ * (e.g. coming straight from a JSON payload) round-trip correctly. Any
+ * value that fails to coerce becomes `NaN`, matching the rest of the
+ * mask pipeline's tolerant input handling — callers that need stricter
+ * validation should perform it before constructing the polygon.
+ *
+ * @param pt - A polygon vertex in object or tuple form.
+ * @returns An `{ x, y }` numeric point.
+ */
+export declare function coercePoint(pt: PolygonPoint): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=number.d.ts.map

package/dist/types/utils/number.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.d.ts","sourceRoot":"","sources":["../../../src/utils/number.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,KAAK,QAAQ,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE9F;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG,GAAG,GAAG,GAAG,CAAC;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,cAAc,CAC1B,GAAG,EAAE,eAAe,GAAG,SAAS,EAChC,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,QAAQ,CAAC,MAAM,EACvB,OAAO,EAAE,eAAe,GACzB,MAAM,CAgBR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAKtE"}