@whittakertech/mosaic

Enumerations

Enumeration	Description
MosaicState	Represents the current interaction lifecycle state of a MosaicJS instance. States are mutually exclusive and transition deterministically.

Classes

Class

Description

Mosaic

Mosaic is the public controller for an event-driven drag-and-drop system. It manages: Pointer lifecycle DOM snapshotting and rollback Deterministic state transitions Event emission for external observers Consumers should: Instantiate Mosaic with root element Call initialize() Listen for mosaic:* events Direct state manipulation is intentionally restricted. Example const mosaic = new Mosaic({ root: document.querySelector("#list"), selectors: { node: ".item" } }); mosaic.initialize(); window.addEventListener("mosaic:mutation:confirmed", () => { console.log("Order updated"); });

Interfaces

Interface	Description
ConstraintResult	The result of evaluating a drag-and-drop constraint. A ConstraintResult represents a deterministic decision about whether a proposed drop operation is allowed. Remarks Constraint evaluation in MosaicJS is synchronous, pure, and side-effect free. A rejected result will trigger rollback behavior if a snapshot is present. Consumers should treat reason as diagnostic metadata only.
CSSClassContract	Defines the semantic CSS class contract used by MosaicJS. Each property represents a stable, meaning-based styling hook that may be applied during the drag lifecycle. Remarks MosaicJS does not impose visual styles. These class names are intended to integrate with external design systems or utility frameworks.
DragContext	Immutable context object describing the current drag operation. A DragContext provides a stable, serializable view of MosaicJS’s internal drag state at a specific moment in time. It is passed to lifecycle hooks and emitted with relevant events to allow external systems to observe drag behavior safely. Remarks A DragContext is read-only and frozen at creation time. It represents a snapshot of state, not a live reference. Consumers must not attempt to mutate or persist this object. The shape of DragContext is considered part of MosaicJS’s stable public API.
DragLifecycleHooks	Lifecycle hooks for observing MosaicJS drag behavior. Each hook is invoked at a specific point in the drag lifecycle and receives an immutable drag context. Remarks Hooks are invoked in strict alignment with the internal deterministic state machine. Invoking a hook in an unexpected state will throw an error.
MosaicOptions	Configuration options used to construct a Mosaic instance. MosaicOptions define the DOM scope, selector semantics, styling hooks, and lifecycle observation points for a Mosaic drag session. Remarks Options are read once at construction time. Changing values after initialization has no effect.
MosaicSnapshot	A structural snapshot of the DOM captured at drag start. Snapshots allow MosaicJS to restore the DOM to a known-good state when a drop operation is rejected. Remarks Snapshots capture node identity, parent relationships, and ordering. They do not clone DOM nodes or capture visual state.

Variables

Variable	Description
DEFAULT_CSS_CLASS_CONTRACT	The default semantic CSS class contract used by MosaicJS. This object defines the canonical set of CSS class names applied during the drag lifecycle when no user overrides are provided. Remarks MosaicJS does not ship with visual styles. These class names are intended to be consumed by external design systems, utility frameworks, or application stylesheets. Consumers may override individual entries via MosaicOptions.cssClasses.
DRAG_HOOK_STATES	Mapping of drag lifecycle hooks to their required Mosaic state. This object defines the invariant relationship between each lifecycle hook and the internal drag state in which it may fire. Remarks This mapping is used to validate hook invocation at runtime. If a hook is invoked while the Mosaic instance is in an unexpected state, an error will be thrown. This object is intentionally static and non-extensible.
MOSAIC_TRANSITIONS	The complete set of valid state transitions for MosaicJS. This object defines the deterministic finite state machine governing the drag lifecycle. Remarks This map is intentionally static and non-extensible. All state transitions must be explicit, observable, and testable.

Functions

Function	Description
buildDragContext	Constructs an immutable DragContext from internal drag state. This function is used by MosaicJS to create the context object passed to lifecycle hooks and emitted with drag-related events. Remarks The returned object is frozen and must not be mutated. The context represents a snapshot in time, not a live reference. While exported as part of the public API, this function is primarily intended for internal use and advanced tooling.
canTransition	Determines whether a transition between two lifecycle states is valid. This function enforces MosaicJS’s deterministic state machine. Remarks Invalid transitions are rejected by Mosaic.setState and emit a mosaic:error event.
checkConstraints	Evaluates whether a drop operation is permitted. This function applies MosaicJS’s built-in, deterministic constraints to a proposed drag-and-drop interaction. Remarks Constraint evaluation is synchronous and side-effect free. Custom or user-defined constraints are not supported in v0.2.
createSnapshot	Captures a structural snapshot of the current DOM state. The snapshot is used to guarantee rollback safety if a drop operation is rejected. Remarks Snapshots are captured automatically by MosaicJS at drag start. Manual usage is intended for advanced or diagnostic scenarios.
emit	Emits a MosaicJS lifecycle event. Events are dispatched on the global window object and are intended for observation by external systems. Remarks Event emission is synchronous. MosaicJS does not catch or suppress listener errors.
restoreSnapshot	Restores the DOM to a previously captured snapshot state. This function reorders existing DOM nodes to match the snapshot. Remarks If the snapshot is invalid or incomplete, restoration is a no-op. This function does not recreate or remove DOM nodes.