Mosaic

@whittakertech/mosaic / Mosaic

Class: Mosaic

Defined in: mosaic.ts:248

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:

1. Instantiate Mosaic with root element
2. Call initialize()
3. 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");
});

Constructors

Constructor

new Mosaic(options): Mosaic;

Defined in: mosaic.ts:321

Parameters

options

MosaicOptions

Returns

Mosaic

Properties

bubbleConstraints

readonly bubbleConstraints: boolean;

Defined in: mosaic.ts:255

---

constraints

readonly constraints: readonly (input) => ConstraintResult[];

Defined in: mosaic.ts:274

User-defined drop constraints, evaluated after built-in constraints (#20). See MosaicOptions.constraints.

---

crossContainerConstraints

readonly crossContainerConstraints: readonly (input) => ConstraintResult[];

Defined in: mosaic.ts:282

User-defined cross-container constraints (#160/RM-21.4). See MosaicOptions.crossContainerConstraints.

---

crossGroupDrag

readonly crossGroupDrag: boolean;

Defined in: mosaic.ts:253

---

cssClasses

cssClasses: CSSClassContract;

Defined in: mosaic.ts:251

---

maxNestingDepth?

readonly optional maxNestingDepth: number;

Defined in: mosaic.ts:254

---

mosaicInstanceId

readonly mosaicInstanceId: string;

Defined in: mosaic.ts:268

Uniquely identifies this Mosaic instance across the page (#18).

Remarks

Generated once at construction via crypto.randomUUID() — distinct from Mosaic.root’s DOM id (mosaicRootId in DragContext), which is not guaranteed unique. Consumers observing multiple Mosaic instances on the same page should filter hook/event payloads by this field.

---

root

root: HTMLElement;

Defined in: mosaic.ts:249

---

selectors

selectors: object;

Defined in: mosaic.ts:250

children?

optional children: string;

Optional selector identifying child elements within a draggable node.

Remarks

This selector is intended for structural clarity and future extensibility. It is not required for basic drag-and-drop behavior.

dropTarget?

optional dropTarget: string;

Optional selector identifying explicit drop destinations.

Remarks

When provided, elements matching this selector become valid drop targets in addition to draggable nodes, and are distinguished from nodes via the targetType field on hover events and the dropTarget CSS class.

When omitted, v0.2 behavior is preserved — draggable nodes are the only valid drop targets.

group?

optional group: string;

Optional selector identifying logical grouping elements.

Remarks

When provided, group-container elements scope drag behavior: a node dragged within its group reorders only among siblings in that group, and drops outside the group are rejected (reason "group-boundary") unless MosaicOptions.crossGroupDrag is enabled.

handle?

optional handle: string;

Optional selector identifying a drag handle within a node.

Remarks

When provided, pointerdown only initiates a drag when its target matches (or is a descendant of) an element matching this selector within the node — the handle may be nested at any depth. A pointerdown elsewhere on the node is ignored.

When omitted, the entire node remains draggable (v0.2 behavior).

node

node: string;

Selector matching draggable nodes.

This selector defines which elements participate in drag operations.

---

snapshot

snapshot: MosaicSnapshot | null = null;

Defined in: mosaic.ts:252

---

worldTolerance

readonly worldTolerance: boolean;

Defined in: mosaic.ts:256

Methods

confirm()

confirm(constraintsEvaluated?): void;

Defined in: mosaic.ts:483

Confirms the current mutation.

This clears the active snapshot and finalizes the drag operation. Called automatically after constraints allow a drop.

Parameters

constraintsEvaluated?

number

Count of constraint evaluations (built-in

• bubble-up retries + user constraints) performed to reach this confirmation (#22). Forwarded by DragController; callers outside the drag lifecycle may omit it.

Emits mosaic:mutation:confirmed. When constraintsEvaluated is provided, the payload is { constraintsEvaluated }; when omitted, the event carries no payload at all (preserves the exact pre-#22 emission for direct/manual confirm() calls).

Returns

void

---

destroy()

destroy(): void;

Defined in: mosaic.ts:540

Tears down the Mosaic instance and removes all event listeners.

After calling destroy(), the instance is inert and should be discarded. Emits mosaic:destroy.

Returns

void

Remarks

Also unlinks this instance from every peer it was linked to and removes it from the instance registry (#157/RM-21.1, AC6/AC7) — no dangling registry entries survive teardown, and the registry itself does not hold a reference to a destroyed instance.

---

getLinkedPeers()

getLinkedPeers(): Mosaic[];

Defined in: mosaic.ts:405

Returns the live Mosaic instances currently linked as peers to this one (#158/RM-21.2), resolved from Mosaic.instancesById.

Returns

Mosaic[]

Remarks

Consumed by DragController.pointerMove’s cross-peer resolution fallback (#158) — probing every linked peer’s root/selectors when this instance’s own resolution finds nothing under the pointer. Order is insertion order of Mosaic.link() calls, not otherwise meaningful.

---

getState()

getState(): MosaicState;

Defined in: mosaic.ts:561

Returns

MosaicState

---

initialize()

initialize(): void;

Defined in: mosaic.ts:457

Initializes the Mosaic instance.

This attaches all required pointer event listeners and enables drag-and-drop behavior on the root element.

Must be called exactly once before user interaction. Emits the mosaic:init event.

Returns

void

---

isLinkedTo()

isLinkedTo(other): boolean;

Defined in: mosaic.ts:390

Instance-method convenience wrapper for Mosaic.arePeers (#157/RM-21.1) — lets cross-container code ask mosaic.isLinkedTo(other) without reaching into static registry state directly.

Parameters

other

Mosaic

Returns

boolean

---

reject()

reject(result?): void;

Defined in: mosaic.ts:510

Rejects the current mutation and restores the previous DOM state.

If no snapshot exists, this method is a no-op.

Parameters

result?

ConstraintResult

The ConstraintResult that caused the rejection (#22) — the built-in or user constraint’s own result, reason and metadata included. Forwarded by DragController; callers outside the drag lifecycle may omit it.

Emits mosaic:mutation:rejected and mosaic:rollback. When result is provided, mosaic:mutation:rejected’s payload is the full ConstraintResult object; when omitted, the event carries no payload at all (preserves the exact pre-#22 emission for direct/manual reject() calls).

Returns

void

---

setState()

setState(
   next,
   meta?,
   groupId?,
   dropTargetId?): boolean;

Defined in: mosaic.ts:592

Attempts to transition the Mosaic instance to a new lifecycle state.

State transitions are validated against the internal deterministic state machine. Invalid transitions are rejected.

Parameters

next

MosaicState

The target state

meta?

unknown

Optional metadata forwarded with the state event

groupId?

Identifier of the active group (#13), or null when ungrouped. Forwarded by DragController at each transition; callers outside the drag lifecycle may omit it.

string | null

dropTargetId?

Identifier of the currently-hovered/resolved target (#16), or null when none. Forwarded by DragController at each transition, mirroring DragContext.dropTargetId’s naming; callers outside the drag lifecycle may omit it.

string | null

Returns

boolean

true if the transition was applied, false otherwise

Emits:

• mosaic:state on success
• mosaic:error on invalid transition — payload includes from, to, validTransitions (the states actually reachable from from, per MOSAIC_TRANSITIONS), and timestamp (#19). When MosaicOptions.debug is enabled, the same information is also logged via console.warn.

---

arePeers()

static arePeers(a, b): boolean;

Defined in: mosaic.ts:379

Whether a and b are currently linked peers (#157/RM-21.1).

Parameters

a

Mosaic

b

Mosaic

Returns

boolean

Remarks

Returns false for any pair that was never linked, or that has since been unlinked/torn down — this is the default-reject baseline RM-21.4’s “unlinked instances reject cross-instance drops by default” behavior checks against.

---

findInstanceContaining()

static findInstanceContaining(element): Mosaic | undefined;

Defined in: mosaic.ts:432

Finds the live Mosaic instance whose root contains element, if any (#160/RM-21.4).

Parameters

element

Element

Returns

Mosaic | undefined

Remarks

Iterates every live instance (via Mosaic.instancesById), not just this instance’s own linked peers — used specifically to detect a drop resolved onto some other, unrelated (and possibly unlinked) instance’s DOM, which by definition isn’t in any instance’s own peer set and so getLinkedPeers() alone can never find it. Distinguishes “the pointer released over another Mosaic instance’s territory entirely” from “the pointer released over ordinary page chrome unrelated to any Mosaic instance.”

---

link()

static link(a, b): void;

Defined in: mosaic.ts:351

Registers a and b as peer Mosaic instances (#157/RM-21.1).

Parameters

a

Mosaic

b

Mosaic

Returns

void

Remarks

Symmetric — linking A→B also links B→A; there is no directional link concept. Idempotent — linking an already-linked pair is a no-op. Linking an instance to itself is a no-op (a self-peer relationship is meaningless and would only complicate Mosaic.unlink/ Mosaic.destroy bookkeeping for no benefit).

---

unlink()

static unlink(a, b): void;

Defined in: mosaic.ts:365

Removes the peer relationship between a and b (#157/RM-21.1).

Parameters

a

Mosaic

b

Mosaic

Returns

void

Remarks

Symmetric — removes both directions. A no-op if the pair was never linked.