MosaicOptions

Interface: 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.

Properties

bubbleConstraints?

optional bubbleConstraints: boolean;

Defined in: mosaic.ts:128

Enables bubble-up constraint evaluation (#12).

Remarks

Default false: a rejected drop stays rejected. When true, a rejection at the innermost resolved target is retried against each ancestor in ResolvedTarget.ancestors (innermost-first) until one is allowed, or the chain is exhausted — the drop then lands on that ancestor rather than the original target.

constraints?

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

Defined in: mosaic.ts:187

User-defined drop constraints, evaluated in order after MosaicJS’s own built-in constraints (#20).

Parameters

input

ConstraintInput

Returns

ConstraintResult

Remarks

Default [] — no effect when omitted. Each function receives the exact same ConstraintInput object the built-in checkConstraints() call for that drop received (same object, same fields — dragged, target, kind, selectors, sourceGroup, targetGroup, crossGroupDrag, container, depth, maxNestingDepth), so a user constraint has the identical signature and calling convention as a built-in one and can be tested/composed the same way.

Evaluation order: built-in constraints (including a bubble-up retry against ancestors, when MosaicOptions.bubbleConstraints is enabled) run first — a built-in rejection short-circuits before any user constraint runs at all. User constraints then run in array order and stop at the first rejection; a later constraint never runs once an earlier one (built-in or user) has rejected the drop.

crossContainerConstraints?

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

Defined in: mosaic.ts:213

User-defined cross-container constraints, evaluated last on a cross-container drop (#160/RM-21.4) — after the target (peer) instance’s own built-in constraints and its own MosaicOptions.constraints have already passed.

Parameters

input

ConstraintInput

Returns

ConstraintResult

Remarks

Default [] — no effect when omitted, and never evaluated at all for a same-instance drop. Uses the exact same (input: ConstraintInput) => ConstraintResult signature RM-20 already established for MosaicOptions.constraints — no new calling convention. input carries sourceInstanceId/ targetInstanceId for a cross-container evaluation (omitted for a same-instance one).

Evaluated against the target (peer) instance’s own array — the instance whose DOM is receiving the drop is the one whose rules govern whether it accepts the incoming node, mirroring how its own built-in/user constraints are also evaluated using its own selectors/maxNestingDepth/etc. rather than the dragging instance’s. The origin instance’s own crossContainerConstraints (if any) are not consulted for a drop it initiates — only for a drop it receives from a peer.

crossGroupDrag?

optional crossGroupDrag: boolean;

Defined in: mosaic.ts:106

Enables cross-group dragging when selectors.group is configured.

Remarks

Default false: dropping a node outside its originating group is rejected with reason "group-boundary". When true, nodes may move between groups — the snapshot/rollback system restores original group membership on a rejected drop like any other reparenting.

Has no effect when selectors.group is not configured.

cssClasses?

optional cssClasses: Partial<CSSClassContract>;

Defined in: mosaic.ts:93

Optional overrides for the default CSS class contract.

Unspecified entries fall back to MosaicJS defaults.

debug?

optional debug: boolean;

Defined in: mosaic.ts:147

Enables development diagnostics for invalid state transitions (#19).

Remarks

Default false. When true, an invalid transition additionally logs a structured console.warn with the same information as the mosaic:error event payload (from, to, validTransitions, timestamp). No console output in the default/production mode.

dragLifecycleHooks?

optional dragLifecycleHooks: DragLifecycleHooks;

Defined in: mosaic.ts:136

Optional lifecycle hooks for observing drag behavior.

Hooks are invoked in strict alignment with the internal deterministic state machine.

maxNestingDepth?

optional maxNestingDepth: number;

Defined in: mosaic.ts:116

Caps how deeply a node may be nested via explicit drop targets (#12).

Remarks

Default undefined (unlimited). depth is the number of drop-target/node ancestors above the resolved target — 0 is root-level. Drops exceeding the limit are rejected with reason "nesting-depth-exceeded".

root

root: HTMLElement;

Defined in: mosaic.ts:27

The root DOM element managed by MosaicJS.

All draggable nodes must exist within this element.

selectors

selectors: object;

Defined in: mosaic.ts:33

Selector configuration used to identify draggable elements and related structural roles.

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.

worldTolerance?

optional worldTolerance: boolean;

Defined in: mosaic.ts:164

Enables tolerance for external DOM mutations during an active drag (#15).

Remarks

Default false — zero MutationObserver overhead, identical to prior behavior. When true, structural mutations to participating nodes (additions, removals, or reordering matching selectors.node) that occur outside MosaicJS’s own drag handling — e.g. a framework re-render, a websocket-driven list update — are detected during Dragging. On detection, the DOM is re-snapshotted so rollback restores to the last known-good state rather than the stale drag-start state, and mosaic:world:mutated is emitted. Attribute changes are always benign and ignored. Has no effect outside the active drag lifecycle.