@breadstone/mosaik-elements-foundation 0.0.215 → 0.0.217

package/Controls/Controllers/DragResizeController.d.ts

@@ -0,0 +1,419 @@
+import type { LitElement, ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * The resize handle direction.
+ *
+ * @public
+ */
+export type DragResizeHandle = 'side' | 'bottom' | 'corner' | null;
+/**
+ * The resize mode.
+ *
+ * @public
+ */
+export type DragResizeMode = 'immediate' | 'deferred';
+/**
+ * A position with x and y coordinates.
+ *
+ * @public
+ */
+export interface IDragResizePosition {
+    x: number;
+    y: number;
+}
+/**
+ * Dimensions with width and height.
+ *
+ * @public
+ */
+export interface IDragResizeDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * The state tracked during a resize operation.
+ *
+ * @public
+ */
+export interface IDragResizeState {
+    /**
+     * The initial bounding rect of the element when the resize started.
+     */
+    initial: DOMRect;
+    /**
+     * The current bounding rect of the element.
+     */
+    current: DOMRect;
+    /**
+     * The initial pointer position when resize started.
+     */
+    startPointer: IDragResizePosition;
+    /**
+     * The current pointer position.
+     */
+    currentPointer: IDragResizePosition;
+    /**
+     * The delta from start position.
+     */
+    delta: IDragResizePosition;
+    /**
+     * The current dimensions of the resize.
+     */
+    dimensions: IDragResizeDimensions;
+    /**
+     * The resize handle being used.
+     */
+    handle: DragResizeHandle;
+    /**
+     * The ghost element used in deferred mode.
+     */
+    ghost: HTMLElement | null;
+}
+/**
+ * Parameters passed to resize callbacks.
+ *
+ * @public
+ */
+export interface IDragResizeCallbackParameters {
+    /**
+     * The pointer event that triggered the callback.
+     */
+    event: PointerEvent;
+    /**
+     * The current resize state.
+     */
+    state: IDragResizeState;
+}
+/**
+ * Callback type for resize events.
+ *
+ * @public
+ */
+export type DragResizeCallback = (parameters: IDragResizeCallbackParameters) => unknown;
+/**
+ * Callback type for resize cancel events.
+ *
+ * @public
+ */
+export type DragResizeCancelCallback = (state: IDragResizeState) => unknown;
+/**
+ * Skip callback type.
+ *
+ * @public
+ */
+export type DragResizeSkipCallback = (event: PointerEvent) => boolean;
+/**
+ * Handle match callback type.
+ *
+ * @public
+ */
+export type DragResizeHandleMatchCallback = (element: HTMLElement) => DragResizeHandle;
+/**
+ * Ghost factory callback type.
+ *
+ * @public
+ */
+export type DragResizeGhostCallback = () => HTMLElement;
+/**
+ * Snap calculation callback type.
+ *
+ * @public
+ */
+export type DragResizeSnapCallback = (dimensions: IDragResizeDimensions, delta: IDragResizePosition, handle: DragResizeHandle) => IDragResizeDimensions;
+/**
+ * Configuration options for the DragResizeController.
+ *
+ * @public
+ */
+export interface IDragResizeControllerConfiguration {
+    /**
+     * Whether the resize feature is enabled.
+     *
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * The mode of the resize operation.
+     * - `immediate`: The element itself is resized during the operation.
+     * - `deferred`: A ghost element is created and resized; the original stays unchanged until completion.
+     *
+     * @defaultValue 'deferred'
+     */
+    mode?: DragResizeMode;
+    /**
+     * Minimum width for the resize operation in pixels.
+     *
+     * @defaultValue 50
+     */
+    minWidth?: number;
+    /**
+     * Minimum height for the resize operation in pixels.
+     *
+     * @defaultValue 50
+     */
+    minHeight?: number;
+    /**
+     * Maximum width for the resize operation in pixels.
+     *
+     * @defaultValue Infinity
+     */
+    maxWidth?: number;
+    /**
+     * Maximum height for the resize operation in pixels.
+     *
+     * @defaultValue Infinity
+     */
+    maxHeight?: number;
+    /**
+     * Guard function invoked during the `start` callback.
+     * Returning a truthy value will prevent the resize operation from starting.
+     */
+    skip?: DragResizeSkipCallback;
+    /**
+     * Function to match resize handles.
+     * Called for elements to determine which resize handle was activated.
+     */
+    matchHandle?: DragResizeHandleMatchCallback;
+    /**
+     * Factory function to create a custom ghost element in deferred mode.
+     */
+    ghost?: DragResizeGhostCallback;
+    /**
+     * Function to calculate snapped dimensions during resize.
+     * Used for grid-based snapping or other custom dimension calculations.
+     */
+    snap?: DragResizeSnapCallback;
+    /**
+     * Callback invoked at the beginning of a resize operation.
+     * Return `false` to cancel the resize.
+     */
+    start?: DragResizeCallback;
+    /**
+     * Callback invoked while resizing the element.
+     */
+    resize?: DragResizeCallback;
+    /**
+     * Callback invoked when the resize operation completes.
+     */
+    end?: DragResizeCallback;
+    /**
+     * Callback invoked when a resize is cancelled (e.g., by pressing Escape).
+     */
+    cancel?: DragResizeCancelCallback;
+}
+/**
+ * A drag-to-resize controller implementing a ReactiveController pattern.
+ *
+ * This controller manages pointer events to enable resize functionality
+ * on Lit elements via drag handles. It supports both immediate and deferred resize modes.
+ *
+ * @example
+ * ```typescript
+ * class MyElement extends LitElement {
+ *     private readonly _dragResizeController = addDragResizeController(this, {
+ *         matchHandle: (element) => {
+ *             if (element.classList.contains('resize-side')) return 'side';
+ *             if (element.classList.contains('resize-bottom')) return 'bottom';
+ *             if (element.classList.contains('resize-corner')) return 'corner';
+ *             return null;
+ *         },
+ *         ghost: () => this._createResizeGhost(),
+ *         start: (params) => this._handleResizeStart(params),
+ *         resize: (params) => this._handleResize(params),
+ *         end: (params) => this._handleResizeEnd(params),
+ *         cancel: (state) => this._handleResizeCancel(state),
+ *     });
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class DragResizeController implements ReactiveController {
+    private readonly _host;
+    private readonly _options;
+    private _abortController;
+    private _state;
+    private _pointerId;
+    private _hasPointerCapture;
+    private _ghost;
+    private _captureElement;
+    /**
+     * Constructs a new instance of the `DragResizeController` class.
+     *
+     * @param host - The host element.
+     * @param options - The configuration options.
+     *
+     * @public
+     */
+    constructor(host: ReactiveControllerHost & LitElement, options?: IDragResizeControllerConfiguration);
+    /**
+     * Whether the resize controller is enabled.
+     *
+     * @public
+     * @readonly
+     */
+    get enabled(): boolean;
+    /**
+     * Whether a resize operation is currently in progress.
+     *
+     * @public
+     * @readonly
+     */
+    get isResizing(): boolean;
+    /**
+     * Whether the current resize mode is deferred.
+     *
+     * @private
+     * @readonly
+     */
+    private get _isDeferred();
+    /**
+     * The element being resized.
+     * When in deferred mode this returns a reference to the resize ghost element,
+     * otherwise it is the host element.
+     *
+     * @private
+     * @readonly
+     */
+    private get _resizeItem();
+    /**
+     * The current state parameters for callbacks.
+     *
+     * @private
+     * @readonly
+     */
+    private get _stateParameters();
+    /**
+     * Updates the resize controller configuration.
+     *
+     * @param options - The new configuration options.
+     *
+     * @public
+     */
+    set(options?: IDragResizeControllerConfiguration): void;
+    /**
+     * Stops any resize operation and cleans up state, event listeners, and elements.
+     *
+     * @public
+     */
+    dispose(): void;
+    /**
+     * Handles pointer down events.
+     *
+     * @param event - The pointer event.
+     *
+     * @private
+     */
+    private _handlePointerDown;
+    /**
+     * Handles pointer move events.
+     *
+     * @param event - The pointer event.
+     *
+     * @private
+     */
+    private _handlePointerMove;
+    /**
+     * Handles pointer end events.
+     *
+     * @param event - The pointer event.
+     *
+     * @private
+     */
+    private _handlePointerEnd;
+    /**
+     * Handles cancel events (Escape key).
+     *
+     * @param event - The keyboard event.
+     *
+     * @private
+     */
+    private _handleCancel;
+    /**
+     * Sets up the cancel key listener.
+     *
+     * @param enabled - Whether to enable the listener.
+     *
+     * @private
+     */
+    private _setResizeCancelListener;
+    /**
+     * Sets the initial resize state.
+     *
+     * @param event - The pointer event.
+     * @param handle - The resize handle.
+     *
+     * @private
+     */
+    private _setInitialState;
+    /**
+     * Sets the resize state (captures pointer, applies styles).
+     *
+     * @param enabled - Whether resize is active.
+     *
+     * @private
+     */
+    private _setResizeState;
+    /**
+     * Updates the position state based on the current pointer position.
+     *
+     * @param event - The pointer event.
+     *
+     * @private
+     */
+    private _updatePosition;
+    /**
+     * Updates the dimensions based on the current resize state.
+     *
+     * @private
+     */
+    private _updateDimensions;
+    /**
+     * Applies the dimensions to the element.
+     *
+     * @param element - The element to resize.
+     *
+     * @private
+     */
+    private _applyDimensions;
+    /**
+     * Matches the resize handle from the event.
+     *
+     * @param event - The pointer event.
+     * @returns The matched handle or null.
+     *
+     * @private
+     */
+    private _matchHandle;
+    /**
+     * Creates the resize ghost element.
+     *
+     * @private
+     */
+    private _createResizeGhost;
+    /**
+     * Removes the resize ghost element.
+     *
+     * @private
+     */
+    private _removeGhost;
+    /**
+     * Checks whether the resize should be skipped.
+     *
+     * @param event - The pointer event.
+     * @returns True if the resize should be skipped.
+     *
+     * @private
+     */
+    private _shouldSkip;
+}
+/**
+ * Adds a drag-to-resize controller to the given host.
+ *
+ * @param host - The host element.
+ * @param options - The configuration options.
+ * @returns The drag resize controller instance.
+ *
+ * @public
+ */
+export declare function addDragResizeController(host: ReactiveControllerHost & LitElement, options?: IDragResizeControllerConfiguration): DragResizeController;
+//# sourceMappingURL=DragResizeController.d.ts.map

package/Controls/Controllers/DragResizeController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DragResizeController.d.ts","sourceRoot":"","sources":["../../../src/Controls/Controllers/DragResizeController.ts"],"names":[],"mappings":"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"}