@eocrm/design-system 0.6.24 → 0.8.0

package/dist/components/DashboardCanvas/DashboardCanvasItem.d.ts

@@ -0,0 +1,51 @@
+import type { KeyboardEvent as ReactKeyboardEvent, PointerEvent as ReactPointerEvent, ReactNode } from 'react';
+import type { ContainerRef, DashboardPlacement } from './engine.js';
+/** Which resize handle a resize gesture started from. */
+export type ResizeEdge = 'e' | 's' | 'se';
+/**
+ * Gesture wiring handed down from DashboardCanvas to every item, top-level or
+ * inside a section. One bag instead of five props so DashboardCanvasSection
+ * forwards it untouched.
+ */
+export interface CanvasGestures {
+    readOnly: boolean;
+    /** Item currently being moved — its cell renders the drop-preview style. */
+    movingId: string | number | null;
+    /** Item currently being resized — its cell renders the resize affordance. */
+    resizingId: string | number | null;
+    /** Item currently keyboard-picked — its cell renders the picked style. */
+    pickedId: string | number | null;
+    /** id of the visually-hidden keyboard instructions block (aria-describedby). */
+    instructionsId: string;
+    onMovePointerDown: (event: ReactPointerEvent<HTMLDivElement>, placement: DashboardPlacement, container: ContainerRef) => void;
+    onResizePointerDown: (event: ReactPointerEvent<HTMLDivElement>, placement: DashboardPlacement, container: ContainerRef, edge: ResizeEdge) => void;
+    onItemKeyDown: (event: ReactKeyboardEvent<HTMLDivElement>, placement: DashboardPlacement, container: ContainerRef) => void;
+}
+/**
+ * Stable (y, then x) render order — matches the engine's own processing
+ * order (`compact`/`placeWithPushDown`/`stackOrder`), so DOM order always
+ * agrees with visual stacking order (load-bearing below the md breakpoint,
+ * Task 5, where DOM order becomes the single-column stack order).
+ */
+export declare function sortByPosition(items: readonly DashboardPlacement[]): DashboardPlacement[];
+interface DashboardCanvasItemProps {
+    placement: DashboardPlacement;
+    container: ContainerRef;
+    gestures: CanvasGestures;
+    children: ReactNode;
+}
+/**
+ * Internal — one grid cell. Stamps the placement as inline custom properties
+ * consumed by `.item` in DashboardCanvas.module.scss (Grid.Item precedent).
+ * `data-dc-item` is a stable hook for tests/consumers' CSS, independent of
+ * the hashed-in-production module class name.
+ *
+ * In edit mode the whole cell is the move-drag surface, and E/S/SE resize
+ * handles overlay the edges. The handles are pointer-only `aria-hidden` divs
+ * (not focusable) — keyboard resize is Shift+arrows on the focused cell, so
+ * exposing the handles to AT would only add noise. The cell itself is the
+ * keyboard editing surface: role=button (named by the widget's own content,
+ * FlowNode precedent) with a localized "widget" roledescription.
+ */
+export declare function DashboardCanvasItem({ placement, container, gestures, children, }: DashboardCanvasItemProps): import("react").JSX.Element;
+export {};

package/dist/components/DashboardCanvas/DashboardCanvasItem.js

@@ -0,0 +1,71 @@
+'use client';
+import { useTranslation } from "../../i18n/useTranslation.js";
+import DashboardCanvas_module_default from "./DashboardCanvas.module.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+// src/components/DashboardCanvas/DashboardCanvasItem.tsx
+/**
+* Stable (y, then x) render order — matches the engine's own processing
+* order (`compact`/`placeWithPushDown`/`stackOrder`), so DOM order always
+* agrees with visual stacking order (load-bearing below the md breakpoint,
+* Task 5, where DOM order becomes the single-column stack order).
+*/
+function sortByPosition(items) {
+	return [...items].sort((a, b) => a.y - b.y || a.x - b.x);
+}
+/**
+* Internal — one grid cell. Stamps the placement as inline custom properties
+* consumed by `.item` in DashboardCanvas.module.scss (Grid.Item precedent).
+* `data-dc-item` is a stable hook for tests/consumers' CSS, independent of
+* the hashed-in-production module class name.
+*
+* In edit mode the whole cell is the move-drag surface, and E/S/SE resize
+* handles overlay the edges. The handles are pointer-only `aria-hidden` divs
+* (not focusable) — keyboard resize is Shift+arrows on the focused cell, so
+* exposing the handles to AT would only add noise. The cell itself is the
+* keyboard editing surface: role=button (named by the widget's own content,
+* FlowNode precedent) with a localized "widget" roledescription.
+*/
+function DashboardCanvasItem({ placement, container, gestures, children }) {
+	const t = useTranslation();
+	const { id, x, y, w, h } = placement;
+	const { readOnly, movingId, resizingId, pickedId, instructionsId, onMovePointerDown, onResizePointerDown, onItemKeyDown } = gestures;
+	return /* @__PURE__ */ jsxs("div", {
+		className: DashboardCanvas_module_default.item,
+		"data-dc-item": String(id),
+		"data-dc-drop-preview": movingId === id ? "" : void 0,
+		"data-dc-resizing": resizingId === id ? "" : void 0,
+		"data-dc-picked": pickedId === id ? "" : void 0,
+		role: readOnly ? void 0 : "button",
+		tabIndex: readOnly ? void 0 : 0,
+		"aria-roledescription": readOnly ? void 0 : t("dashboardCanvas.itemRole"),
+		"aria-describedby": readOnly ? void 0 : instructionsId,
+		style: {
+			["--dc-col"]: `${x + 1} / span ${w}`,
+			["--dc-row"]: `${y + 1} / span ${h}`,
+			["--dc-h-span"]: `span ${h}`
+		},
+		onPointerDown: readOnly ? void 0 : (e) => onMovePointerDown(e, placement, container),
+		onKeyDown: readOnly ? void 0 : (e) => onItemKeyDown(e, placement, container),
+		children: [children, !readOnly && /* @__PURE__ */ jsxs(Fragment, { children: [
+			/* @__PURE__ */ jsx("div", {
+				className: DashboardCanvas_module_default.handleE,
+				"data-dc-resize": "e",
+				"aria-hidden": "true",
+				onPointerDown: (e) => onResizePointerDown(e, placement, container, "e")
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: DashboardCanvas_module_default.handleS,
+				"data-dc-resize": "s",
+				"aria-hidden": "true",
+				onPointerDown: (e) => onResizePointerDown(e, placement, container, "s")
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: DashboardCanvas_module_default.handleSE,
+				"data-dc-resize": "se",
+				"aria-hidden": "true",
+				onPointerDown: (e) => onResizePointerDown(e, placement, container, "se")
+			})
+		] })]
+	});
+}
+export { DashboardCanvasItem, sortByPosition };

package/dist/components/DashboardCanvas/DashboardCanvasSection.d.ts

@@ -0,0 +1,53 @@
+import type { KeyboardEvent as ReactKeyboardEvent, PointerEvent as ReactPointerEvent, ReactNode } from 'react';
+import type { ContainerRef, DashboardSection } from './engine.js';
+import type { CanvasGestures } from './DashboardCanvasItem.js';
+interface DashboardCanvasSectionProps {
+    section: DashboardSection;
+    renderItem: (id: string | number) => ReactNode;
+    renderSectionHeader?: (id: string | number) => ReactNode;
+    gestures: CanvasGestures;
+    /** True while this band is being pointer-reordered (styling hook). */
+    dragging: boolean;
+    /** True while a move-drag hovers this body grid (it alone gets trailing drop space). */
+    dropTarget: boolean;
+    /** Band-reorder drag zone: the dedicated grip handle only (see remarks below). */
+    onHeaderPointerDown: (event: ReactPointerEvent<HTMLDivElement>, sectionId: string | number) => void;
+    /** Keyboard band reorder: Shift+ArrowUp/Down while the trigger button has focus. */
+    onHeaderKeyDown: (event: ReactKeyboardEvent<HTMLButtonElement>, sectionId: string | number) => void;
+    /** Registers the body grid in the cross-container drop-target registry. */
+    setContainerEl: (cref: ContainerRef, el: HTMLElement | null) => void;
+    /** Registers the band root for reorder insertion-index hit-testing. */
+    setBandEl: (id: string | number, el: HTMLElement | null) => void;
+    /** True while this band is the consumer's `highlightedSectionId`. */
+    highlighted: boolean;
+    onHighlightDone?: () => void;
+}
+/**
+ * Internal — one full-width collapsible band, composed from the DS
+ * `Accordion` for its header/chevron/panel look and open↔close animation:
+ * `Accordion.Item` is the band root, `Accordion.Trigger` the title + chevron
+ * (its accessible name is overridden with the toggle's full i18n'd label),
+ * `Accordion.Content` the animated body. Open state is driven entirely by
+ * `section.collapsed` from the parent's shared `<Accordion type="multiple">` —
+ * this component never toggles itself.
+ *
+ * `Accordion.Content` never unmounts its body (its collapse is a CSS height
+ * animation, not a DOM removal), unlike the pre-Accordion custom header this
+ * replaces. Two things that invariant used to buy for free are now explicit:
+ * `inert` on the body while `collapsed` removes it (and anything the
+ * consumer's `renderItem` puts inside it) from focus and the accessibility
+ * tree, and `DashboardCanvas.tsx` filters collapsed containers out of both
+ * the pointer drop-target hit-test and the keyboard container order.
+ *
+ * Band drag-reorder gets its own explicit grip handle (`GripVertical`, same
+ * icon `Sortable.Handle` uses) instead of "grab anywhere in the header": the
+ * Accordion trigger button spans the header's full width by construction
+ * (the title lives inside it, for a single accessible name), so there's no
+ * separate row surface left to grab without either doubling the toggle as a
+ * drag source or reaching into Accordion's private layout. The handle rides
+ * in `Accordion.Trigger`'s `actions` slot alongside `renderSectionHeader`
+ * extras — both are outside the toggle button by Accordion's own contract,
+ * so neither ever starts nor is mistaken for a collapse click.
+ */
+export declare function DashboardCanvasSection({ section, renderItem, renderSectionHeader, gestures, dragging, dropTarget, onHeaderPointerDown, onHeaderKeyDown, setContainerEl, setBandEl, highlighted, onHighlightDone, }: DashboardCanvasSectionProps): import("react").JSX.Element;
+export {};

package/dist/components/DashboardCanvas/DashboardCanvasSection.js

@@ -0,0 +1,102 @@
+'use client';
+import { useTranslation } from "../../i18n/useTranslation.js";
+import { Accordion } from "../Accordion/Accordion.js";
+import { Highlight } from "../Highlight/Highlight.js";
+import { DashboardCanvasItem, sortByPosition } from "./DashboardCanvasItem.js";
+import DashboardCanvas_module_default from "./DashboardCanvas.module.js";
+import { useCallback } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { GripVertical } from "lucide-react";
+// src/components/DashboardCanvas/DashboardCanvasSection.tsx
+/**
+* Internal — one full-width collapsible band, composed from the DS
+* `Accordion` for its header/chevron/panel look and open↔close animation:
+* `Accordion.Item` is the band root, `Accordion.Trigger` the title + chevron
+* (its accessible name is overridden with the toggle's full i18n'd label),
+* `Accordion.Content` the animated body. Open state is driven entirely by
+* `section.collapsed` from the parent's shared `<Accordion type="multiple">` —
+* this component never toggles itself.
+*
+* `Accordion.Content` never unmounts its body (its collapse is a CSS height
+* animation, not a DOM removal), unlike the pre-Accordion custom header this
+* replaces. Two things that invariant used to buy for free are now explicit:
+* `inert` on the body while `collapsed` removes it (and anything the
+* consumer's `renderItem` puts inside it) from focus and the accessibility
+* tree, and `DashboardCanvas.tsx` filters collapsed containers out of both
+* the pointer drop-target hit-test and the keyboard container order.
+*
+* Band drag-reorder gets its own explicit grip handle (`GripVertical`, same
+* icon `Sortable.Handle` uses) instead of "grab anywhere in the header": the
+* Accordion trigger button spans the header's full width by construction
+* (the title lives inside it, for a single accessible name), so there's no
+* separate row surface left to grab without either doubling the toggle as a
+* drag source or reaching into Accordion's private layout. The handle rides
+* in `Accordion.Trigger`'s `actions` slot alongside `renderSectionHeader`
+* extras — both are outside the toggle button by Accordion's own contract,
+* so neither ever starts nor is mistaken for a collapse click.
+*/
+function DashboardCanvasSection({ section, renderItem, renderSectionHeader, gestures, dragging, dropTarget, onHeaderPointerDown, onHeaderKeyDown, setContainerEl, setBandEl, highlighted, onHighlightDone }) {
+	const t = useTranslation();
+	const { id, title, collapsed, items } = section;
+	const containerRef = {
+		kind: "section",
+		id
+	};
+	const itemGestures = collapsed ? {
+		...gestures,
+		readOnly: true
+	} : gestures;
+	const showDropHint = !collapsed && items.length === 0 && !gestures.readOnly && (gestures.movingId != null || gestures.pickedId != null);
+	const bandRef = useCallback((el) => setBandEl(id, el), [id, setBandEl]);
+	return /* @__PURE__ */ jsx(Highlight, {
+		active: highlighted,
+		scrollIntoView: true,
+		onDone: onHighlightDone,
+		children: /* @__PURE__ */ jsxs(Accordion.Item, {
+			value: String(id),
+			ref: bandRef,
+			"data-dc-section": String(id),
+			"data-dragging": dragging ? "" : void 0,
+			children: [/* @__PURE__ */ jsx(Accordion.Trigger, {
+				"aria-label": t(collapsed ? "dashboardCanvas.sectionExpand" : "dashboardCanvas.sectionCollapse", { title }),
+				onKeyDown: gestures.readOnly ? void 0 : (e) => onHeaderKeyDown(e, id),
+				actions: /* @__PURE__ */ jsxs(Fragment$1, { children: [renderSectionHeader != null && /* @__PURE__ */ jsx("div", {
+					"data-dc-section-actions": true,
+					children: renderSectionHeader(id)
+				}), !gestures.readOnly && /* @__PURE__ */ jsx("div", {
+					className: DashboardCanvas_module_default.sectionDragHandle,
+					"data-dc-section-handle": true,
+					"aria-hidden": "true",
+					onPointerDown: (e) => onHeaderPointerDown(e, id),
+					children: /* @__PURE__ */ jsx(GripVertical, {
+						size: 14,
+						"aria-hidden": "true"
+					})
+				})] }),
+				children: title
+			}), /* @__PURE__ */ jsx(Accordion.Content, { children: /* @__PURE__ */ jsx("div", {
+				className: DashboardCanvas_module_default.sizer,
+				children: /* @__PURE__ */ jsxs("div", {
+					className: DashboardCanvas_module_default.container,
+					"data-dc-container": String(id),
+					"data-dc-empty": items.length === 0 ? "" : void 0,
+					"data-dc-drop-target": dropTarget ? "" : void 0,
+					inert: collapsed,
+					ref: (el) => setContainerEl(containerRef, el),
+					children: [sortByPosition(items).map((item) => /* @__PURE__ */ jsx(DashboardCanvasItem, {
+						placement: item,
+						container: containerRef,
+						gestures: itemGestures,
+						children: renderItem(item.id)
+					}, item.id)), showDropHint && /* @__PURE__ */ jsx("div", {
+						className: DashboardCanvas_module_default.dropHint,
+						"data-dc-drop-hint": true,
+						"aria-hidden": "true",
+						children: t("dashboardCanvas.dropHint")
+					})]
+				})
+			}) })]
+		})
+	});
+}
+export { DashboardCanvasSection };

package/dist/components/DashboardCanvas/engine.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Pure geometry engine for DashboardCanvas: snap-grid placement (24 columns
+ * by default; every bounds-aware op takes a trailing `columns`) with
+ * Datadog-style push-down collision and vertical compaction. No React, no DOM
+ * mutation — every function is deterministic and returns fresh objects,
+ * never mutating its inputs.
+ */
+/** One placed item: grid units within its container. */
+export interface DashboardPlacement {
+    id: string | number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A full-width collapsible band with its own sub-grid of items. */
+export interface DashboardSection {
+    id: string | number;
+    title: string;
+    collapsed: boolean;
+    items: DashboardPlacement[];
+}
+/** Controlled value. Section array order = band order; top-level items render above the first section. */
+export interface DashboardCanvasValue {
+    items: DashboardPlacement[];
+    sections: DashboardSection[];
+}
+/** Per-item size constraints, by item id. */
+export interface DashboardItemConstraints {
+    minW?: number;
+    minH?: number;
+    maxH?: number;
+}
+/** Identifies a placement container: the top-level canvas or one section's sub-grid. */
+export type ContainerRef = {
+    kind: 'top';
+} | {
+    kind: 'section';
+    id: string | number;
+};
+/** Default column count of a container grid (`DashboardCanvas`'s `columns` default). */
+export declare const DASHBOARD_COLUMNS = 24;
+/**
+ * Clamps a placement into the grid: `w`/`h` at least 1 (and `minW`/`minH` when
+ * set), `h` capped at `maxH`, `w` capped at `columns`, then `x` pulled back so
+ * `x + w <= columns` and `x`/`y` floored at 0.
+ */
+export declare function clampPlacement(p: DashboardPlacement, c: DashboardItemConstraints | undefined, columns?: number): DashboardPlacement;
+/** True when the two rects overlap; rects that merely touch edges do NOT collide. */
+export declare function collides(a: DashboardPlacement, b: DashboardPlacement): boolean;
+/**
+ * Pulls every item up to the lowest free y at its own x-span. Stable (y, then
+ * x) processing; never changes x; also resolves any pre-existing overlaps
+ * deterministically (later item in processing order lands below). Output
+ * preserves the input array order.
+ */
+export declare function compact(items: DashboardPlacement[]): DashboardPlacement[];
+/**
+ * Datadog push-down drop: `moved` claims its dropped cell for collision
+ * resolution — colliding items are pushed down just enough (chains
+ * recursively), never sideways — and then the WHOLE layout, `moved` included,
+ * compacts vertically, so no placement ever floats over free space. When the
+ * drop is collision-free this equals `compact([...others, moved])`. An
+ * existing item with `moved.id` is replaced in place; otherwise `moved` is
+ * appended.
+ */
+export declare function placeWithPushDown(items: DashboardPlacement[], moved: DashboardPlacement): DashboardPlacement[];
+/**
+ * Moves an item to cell (x, y) of the `to` container (which may equal `from`).
+ * The source compacts after removal; the item is push-down-placed in the
+ * target with its coordinates clamped to the grid. Unknown item, missing
+ * target container, or a same-container move that resolves to the current
+ * layout returns the value unchanged (same reference).
+ */
+export declare function applyMove(value: DashboardCanvasValue, from: ContainerRef, to: ContainerRef, id: string | number, x: number, y: number, columns?: number): DashboardCanvasValue;
+/**
+ * Resizes an item in place (`x` is kept, `y` moves only through the shared
+ * vertical compaction): `w`/`h` are clamped by the constraints and by the
+ * columns remaining right of `x`, then the layout resettles around it —
+ * growing pushes neighbors down, shrinking lets them compact back up.
+ * Unknown item, or a resize whose clamped dimensions resolve to the current
+ * layout, returns the value unchanged (same reference).
+ */
+export declare function applyResize(value: DashboardCanvasValue, container: ContainerRef, id: string | number, w: number, h: number, c?: DashboardItemConstraints, columns?: number): DashboardCanvasValue;
+/** Flips one section's `collapsed` flag; everything else is untouched (same refs). */
+export declare function toggleSection(value: DashboardCanvasValue, sectionId: string | number): DashboardCanvasValue;
+/** Moves a section band to `toIndex` (clamped into range). Unknown id or no-op index returns the value unchanged. */
+export declare function reorderSection(value: DashboardCanvasValue, sectionId: string | number, toIndex: number): DashboardCanvasValue;
+/**
+ * Flattened below-`md` stacking order: top-level items first, then each
+ * section's items in band order; within a container by (y, then x). Collapsed
+ * sections are included — the renderer decides whether to show their bodies.
+ */
+export declare function stackOrder(value: DashboardCanvasValue): {
+    container: ContainerRef;
+    id: string | number;
+}[];
+/**
+ * Snaps a viewport point to a grid cell of the container: each cell owns its
+ * trailing gap, x is clamped to [0, columns - 1], y is floored at 0 but
+ * unbounded above (the grid grows downward). Zero/negative cell sizes (jsdom)
+ * yield cell 0.
+ */
+export declare function cellFromPoint(px: number, py: number, containerRect: DOMRect, colWidth: number, rowHeight: number, gap: number, columns?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Where a drop lands when the pointer is over another item: the hovered
+ * item's upper half inserts the dragged item before it (at its `y`), the
+ * lower half after it (below its bottom), so stacked widgets reorder instead
+ * of snapping to the ghost's origin cell. x follows the ghost (`fallback.x`)
+ * clamped inside the hovered item's column span when the dragged item fits in
+ * it, otherwise it aligns to the hovered item's left edge (kept on-grid). `px`/`py` are the pointer in
+ * fractional cell units relative to the container. Callers pass the ORIGINAL
+ * pre-drag `items`, never the live preview — a preview reflows the hovered
+ * item and would flip the half under a stationary pointer (oscillation).
+ * Over empty cells or the dragged item itself, returns `fallback`.
+ */
+export declare function insertionCell(items: readonly DashboardPlacement[], id: string | number, w: number, px: number, py: number, fallback: {
+    x: number;
+    y: number;
+}, columns?: number): {
+    x: number;
+    y: number;
+};
+/** Clamps a ghost's top-left into `[0, bounds - size]` per axis (never negative). */
+export declare function clampGhost(left: number, top: number, w: number, h: number, boundsW: number, boundsH: number): {
+    left: number;
+    top: number;
+};

package/dist/components/DashboardCanvas/engine.js

@@ -0,0 +1,232 @@
+// src/components/DashboardCanvas/engine.ts
+/** Default column count of a container grid (`DashboardCanvas`'s `columns` default). */
+var DASHBOARD_COLUMNS = 24;
+/**
+* Clamps a placement into the grid: `w`/`h` at least 1 (and `minW`/`minH` when
+* set), `h` capped at `maxH`, `w` capped at `columns`, then `x` pulled back so
+* `x + w <= columns` and `x`/`y` floored at 0.
+*/
+function clampPlacement(p, c, columns = 24) {
+	const w = Math.min(Math.max(p.w, c?.minW ?? 1, 1), columns);
+	let h = Math.max(p.h, c?.minH ?? 1, 1);
+	if (c?.maxH !== void 0) h = Math.max(Math.min(h, c.maxH), 1);
+	const x = Math.min(Math.max(p.x, 0), columns - w);
+	const y = Math.max(p.y, 0);
+	return {
+		...p,
+		x,
+		y,
+		w,
+		h
+	};
+}
+/** True when the two rects overlap; rects that merely touch edges do NOT collide. */
+function collides(a, b) {
+	return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+}
+/** Stable (y, then x) processing order; ties keep input order (Array.sort is stable). */
+function sortByPosition(items) {
+	return [...items].sort((a, b) => a.y - b.y || a.x - b.x);
+}
+/**
+* Core packing pass: settles `items` (in stable (y, x) order) each to the
+* lowest collision-free y at its own x-span, treating `obstacles` as fixed.
+* With `fromCurrentY`, an item never rises — it only moves down when it
+* collides (the push-down phase); without it, items drop to the lowest free y
+* (the compaction phase). Returns new placements keyed by id.
+*/
+function settle(items, obstacles, fromCurrentY = false) {
+	const placed = [...obstacles];
+	const settled = /* @__PURE__ */ new Map();
+	for (const item of sortByPosition(items)) {
+		let y = fromCurrentY ? item.y : 0;
+		for (;;) {
+			const probe = {
+				...item,
+				y
+			};
+			const hit = placed.find((other) => collides(probe, other));
+			if (!hit) break;
+			y = hit.y + hit.h;
+		}
+		const next = {
+			...item,
+			y
+		};
+		placed.push(next);
+		settled.set(item.id, next);
+	}
+	return settled;
+}
+/**
+* Pulls every item up to the lowest free y at its own x-span. Stable (y, then
+* x) processing; never changes x; also resolves any pre-existing overlaps
+* deterministically (later item in processing order lands below). Output
+* preserves the input array order.
+*/
+function compact(items) {
+	const settled = settle(items, []);
+	return items.map((item) => settled.get(item.id));
+}
+/**
+* Datadog push-down drop: `moved` claims its dropped cell for collision
+* resolution — colliding items are pushed down just enough (chains
+* recursively), never sideways — and then the WHOLE layout, `moved` included,
+* compacts vertically, so no placement ever floats over free space. When the
+* drop is collision-free this equals `compact([...others, moved])`. An
+* existing item with `moved.id` is replaced in place; otherwise `moved` is
+* appended.
+*/
+function placeWithPushDown(items, moved) {
+	const pushed = settle(items.filter((item) => item.id !== moved.id), [moved], true);
+	const intermediate = items.map((item) => item.id === moved.id ? { ...moved } : pushed.get(item.id));
+	if (!items.some((item) => item.id === moved.id)) intermediate.push({ ...moved });
+	return compact(intermediate);
+}
+/** Item ids must be unique per container; duplicate ids produce undefined layouts. */
+function containerItems(value, ref) {
+	if (ref.kind === "top") return value.items;
+	return value.sections.find((section) => section.id === ref.id)?.items;
+}
+/** Item ids must be unique per container; duplicate ids produce undefined layouts. */
+function withContainerItems(value, ref, items) {
+	if (ref.kind === "top") return {
+		...value,
+		items
+	};
+	return {
+		...value,
+		sections: value.sections.map((section) => section.id === ref.id ? {
+			...section,
+			items
+		} : section)
+	};
+}
+function sameContainer(a, b) {
+	return a.kind === "top" ? b.kind === "top" : b.kind === "section" && a.id === b.id;
+}
+/**
+* Index-wise placement equality — lets `applyMove`/`applyResize` return their
+* input by reference when a gesture resolves to the current layout, so
+* callers can gate commits on `next !== value` alone.
+*/
+function samePlacements(a, b) {
+	return a.length === b.length && a.every((p, i) => {
+		const q = b[i];
+		return p.id === q.id && p.x === q.x && p.y === q.y && p.w === q.w && p.h === q.h;
+	});
+}
+/**
+* Moves an item to cell (x, y) of the `to` container (which may equal `from`).
+* The source compacts after removal; the item is push-down-placed in the
+* target with its coordinates clamped to the grid. Unknown item, missing
+* target container, or a same-container move that resolves to the current
+* layout returns the value unchanged (same reference).
+*/
+function applyMove(value, from, to, id, x, y, columns = 24) {
+	const source = containerItems(value, from);
+	const item = source?.find((candidate) => candidate.id === id);
+	if (!source || !item || containerItems(value, to) === void 0) return value;
+	const dropped = clampPlacement({
+		...item,
+		x,
+		y
+	}, void 0, columns);
+	if (sameContainer(from, to)) {
+		const placed = placeWithPushDown(source, dropped);
+		return samePlacements(source, placed) ? value : withContainerItems(value, from, placed);
+	}
+	const removed = withContainerItems(value, from, compact(source.filter((candidate) => candidate.id !== id)));
+	return withContainerItems(removed, to, placeWithPushDown(containerItems(removed, to), dropped));
+}
+/**
+* Resizes an item in place (`x` is kept, `y` moves only through the shared
+* vertical compaction): `w`/`h` are clamped by the constraints and by the
+* columns remaining right of `x`, then the layout resettles around it —
+* growing pushes neighbors down, shrinking lets them compact back up.
+* Unknown item, or a resize whose clamped dimensions resolve to the current
+* layout, returns the value unchanged (same reference).
+*/
+function applyResize(value, container, id, w, h, c, columns = 24) {
+	const items = containerItems(value, container);
+	const item = items?.find((candidate) => candidate.id === id);
+	if (!items || !item) return value;
+	const nextW = Math.max(1, Math.min(Math.max(w, c?.minW ?? 1), columns - item.x));
+	let nextH = Math.max(h, c?.minH ?? 1, 1);
+	if (c?.maxH !== void 0) nextH = Math.max(Math.min(nextH, c.maxH), 1);
+	const placed = placeWithPushDown(items, {
+		...item,
+		w: nextW,
+		h: nextH
+	});
+	return samePlacements(items, placed) ? value : withContainerItems(value, container, placed);
+}
+/** Flips one section's `collapsed` flag; everything else is untouched (same refs). */
+function toggleSection(value, sectionId) {
+	if (!value.sections.some((section) => section.id === sectionId)) return value;
+	return {
+		...value,
+		sections: value.sections.map((section) => section.id === sectionId ? {
+			...section,
+			collapsed: !section.collapsed
+		} : section)
+	};
+}
+/** Moves a section band to `toIndex` (clamped into range). Unknown id or no-op index returns the value unchanged. */
+function reorderSection(value, sectionId, toIndex) {
+	const fromIndex = value.sections.findIndex((section) => section.id === sectionId);
+	if (fromIndex === -1) return value;
+	const target = Math.min(Math.max(toIndex, 0), value.sections.length - 1);
+	if (target === fromIndex) return value;
+	const sections = [...value.sections];
+	const [moved] = sections.splice(fromIndex, 1);
+	sections.splice(target, 0, moved);
+	return {
+		...value,
+		sections
+	};
+}
+/**
+* Snaps a viewport point to a grid cell of the container: each cell owns its
+* trailing gap, x is clamped to [0, columns - 1], y is floored at 0 but
+* unbounded above (the grid grows downward). Zero/negative cell sizes (jsdom)
+* yield cell 0.
+*/
+function cellFromPoint(px, py, containerRect, colWidth, rowHeight, gap, columns = 24) {
+	const colPitch = colWidth + gap;
+	const rowPitch = rowHeight + gap;
+	const rawX = colPitch > 0 ? Math.floor((px - containerRect.left) / colPitch) : 0;
+	const rawY = rowPitch > 0 ? Math.floor((py - containerRect.top) / rowPitch) : 0;
+	return {
+		x: Math.min(Math.max(rawX, 0), columns - 1),
+		y: Math.max(rawY, 0)
+	};
+}
+/**
+* Where a drop lands when the pointer is over another item: the hovered
+* item's upper half inserts the dragged item before it (at its `y`), the
+* lower half after it (below its bottom), so stacked widgets reorder instead
+* of snapping to the ghost's origin cell. x follows the ghost (`fallback.x`)
+* clamped inside the hovered item's column span when the dragged item fits in
+* it, otherwise it aligns to the hovered item's left edge (kept on-grid). `px`/`py` are the pointer in
+* fractional cell units relative to the container. Callers pass the ORIGINAL
+* pre-drag `items`, never the live preview — a preview reflows the hovered
+* item and would flip the half under a stationary pointer (oscillation).
+* Over empty cells or the dragged item itself, returns `fallback`.
+*/
+function insertionCell(items, id, w, px, py, fallback, columns = 24) {
+	const t = items.find((i) => i.id !== id && i.x <= px && px < i.x + i.w && i.y <= py && py < i.y + i.h);
+	if (!t) return fallback;
+	return {
+		x: w <= t.w ? Math.min(Math.max(fallback.x, t.x), t.x + t.w - w) : Math.max(0, Math.min(t.x, columns - w)),
+		y: py < t.y + t.h / 2 ? t.y : t.y + t.h
+	};
+}
+/** Clamps a ghost's top-left into `[0, bounds - size]` per axis (never negative). */
+function clampGhost(left, top, w, h, boundsW, boundsH) {
+	return {
+		left: Math.min(Math.max(left, 0), Math.max(0, boundsW - w)),
+		top: Math.min(Math.max(top, 0), Math.max(0, boundsH - h))
+	};
+}
+export { DASHBOARD_COLUMNS, applyMove, applyResize, cellFromPoint, clampGhost, clampPlacement, collides, compact, insertionCell, placeWithPushDown, reorderSection, toggleSection };

package/dist/components/DashboardCanvas/index.d.ts

@@ -0,0 +1,4 @@
+export { DashboardCanvas } from './DashboardCanvas.js';
+export type { DashboardCanvasProps, DashboardCanvasConstraintsProp } from './DashboardCanvas.js';
+export { DASHBOARD_COLUMNS } from './engine.js';
+export type { DashboardPlacement, DashboardSection, DashboardCanvasValue, DashboardItemConstraints, } from './engine.js';