@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

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"); });`

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
ConstraintInput	The input to a drag-and-drop constraint evaluation. Passed as a single object so the constraint surface can grow across the v0.3 milestone (drop-target kind here in #11; ancestor chain and group options in #12/#13) without churning call sites.
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.
ResolvedTarget	The outcome of resolving a drop destination at a point in the DOM. A `ResolvedTarget` unifies the destination concerns introduced across the v0.3 “Spatial Intelligence” milestone: explicit drop targets (#11), nesting depth (#12), and group scoping (#13). In v0.2-equivalent flat layouts the forward-looking fields collapse to their trivial values — `container` is the root, `depth` is `0`, `group` is `null`, and `ancestors` is empty. Remarks Resolution is pure and side-effect free. The returned object describes where a drop would land; it does not mutate the DOM.
WorldMutatedPayload	Payload for the `mosaic:world:mutated` event (#15).

Type Aliases

Type Alias	Description
TargetKind	Whether a resolved target is a draggable node acting as a drop target, or an element declared explicitly as a drop destination.

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.

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. Applies MosaicJS’s built-in, deterministic constraints to a proposed drag-and-drop interaction. A drop is permitted when the target is the dragged element itself (a no-op self-drop), when it matches `selectors.node`, or — when configured — when it matches `selectors.dropTarget`. A target matching neither is rejected with reason `"invalid-target"`. When `selectors.group` is configured, a drop whose target resolves to a different group than the dragged node’s own is rejected with reason `"group-boundary"` unless `crossGroupDrag` is set (#13). When `container`/`depth` are supplied (#12), a drop that would nest the dragged node inside itself or one of its own descendants is rejected with reason `"circular-nesting"`, and a drop exceeding `maxNestingDepth` is rejected with reason `"nesting-depth-exceeded"`. Remarks Constraint evaluation is synchronous and side-effect free. This function covers MosaicJS’s built-in constraints only. As of v0.4, custom user-defined constraints are also supported — see MosaicOptions.constraints — and are evaluated by `DragController` after this function’s built-in checks pass, using the exact same ConstraintInput shape, so a user constraint has an identical signature and calling convention to this one.
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.
resolveGroup	Resolves the nearest group-container ancestor of an element, bounded by the Mosaic root. Populates ResolvedTarget.group (#13). Returns `null` when `selectors.group` is not configured, or when no ancestor matches it before reaching `root`.
resolveTarget	Resolves the innermost valid drop destination at a position in the DOM. Walks upward from `from` to the nearest element matching the node — or, when configured, drop-target — selector, scoped to `root`. Returns `null` when no valid destination exists, or when the only match is the active node itself (a node is never a drop destination for its own drag).
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.