@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/DashboardCanvas/DashboardCanvasItem.tsx

@@ -0,0 +1,140 @@
+import type {
+  KeyboardEvent as ReactKeyboardEvent,
+  PointerEvent as ReactPointerEvent,
+  ReactNode,
+} from 'react';
+import { useTranslation } from '../../i18n/useTranslation';
+import type { ContainerRef, DashboardPlacement } from './engine';
+import styles from './DashboardCanvas.module.scss';
+
+/** 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 function sortByPosition(items: readonly DashboardPlacement[]): DashboardPlacement[] {
+  return [...items].sort((a, b) => a.y - b.y || a.x - b.x);
+}
+
+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 function DashboardCanvasItem({
+  placement,
+  container,
+  gestures,
+  children,
+}: DashboardCanvasItemProps) {
+  const t = useTranslation();
+  const { id, x, y, w, h } = placement;
+  const {
+    readOnly,
+    movingId,
+    resizingId,
+    pickedId,
+    instructionsId,
+    onMovePointerDown,
+    onResizePointerDown,
+    onItemKeyDown,
+  } = gestures;
+  return (
+    <div
+      className={styles.item}
+      data-dc-item={String(id)}
+      data-dc-drop-preview={movingId === id ? '' : undefined}
+      data-dc-resizing={resizingId === id ? '' : undefined}
+      data-dc-picked={pickedId === id ? '' : undefined}
+      role={readOnly ? undefined : 'button'}
+      tabIndex={readOnly ? undefined : 0}
+      aria-roledescription={readOnly ? undefined : t('dashboardCanvas.itemRole')}
+      aria-describedby={readOnly ? undefined : instructionsId}
+      style={{
+        ['--dc-col' as string]: `${x + 1} / span ${w}`,
+        ['--dc-row' as string]: `${y + 1} / span ${h}`,
+        // Task 5's below-md single-column rule reads this to keep the
+        // item's own height once `--dc-row` stops being consumed.
+        ['--dc-h-span' as string]: `span ${h}`,
+      }}
+      onPointerDown={readOnly ? undefined : (e) => onMovePointerDown(e, placement, container)}
+      onKeyDown={readOnly ? undefined : (e) => onItemKeyDown(e, placement, container)}
+    >
+      {children}
+      {!readOnly && (
+        <>
+          <div
+            className={styles.handleE}
+            data-dc-resize="e"
+            aria-hidden="true"
+            onPointerDown={(e) => onResizePointerDown(e, placement, container, 'e')}
+          />
+          <div
+            className={styles.handleS}
+            data-dc-resize="s"
+            aria-hidden="true"
+            onPointerDown={(e) => onResizePointerDown(e, placement, container, 's')}
+          />
+          <div
+            className={styles.handleSE}
+            data-dc-resize="se"
+            aria-hidden="true"
+            onPointerDown={(e) => onResizePointerDown(e, placement, container, 'se')}
+          />
+        </>
+      )}
+    </div>
+  );
+}

package/src/components/DashboardCanvas/DashboardCanvasSection.tsx

@@ -0,0 +1,174 @@
+import { useCallback } from 'react';
+import type {
+  KeyboardEvent as ReactKeyboardEvent,
+  PointerEvent as ReactPointerEvent,
+  ReactNode,
+} from 'react';
+import { GripVertical } from 'lucide-react';
+import { useTranslation } from '../../i18n/useTranslation';
+import { Accordion } from '../Accordion';
+import { Highlight } from '../Highlight';
+import type { ContainerRef, DashboardSection } from './engine';
+import { DashboardCanvasItem, sortByPosition } from './DashboardCanvasItem';
+import type { CanvasGestures } from './DashboardCanvasItem';
+import styles from './DashboardCanvas.module.scss';
+
+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 function DashboardCanvasSection({
+  section,
+  renderItem,
+  renderSectionHeader,
+  gestures,
+  dragging,
+  dropTarget,
+  onHeaderPointerDown,
+  onHeaderKeyDown,
+  setContainerEl,
+  setBandEl,
+  highlighted,
+  onHighlightDone,
+}: DashboardCanvasSectionProps) {
+  const t = useTranslation();
+  const { id, title, collapsed, items } = section;
+  const containerRef: ContainerRef = { kind: 'section', id };
+  // Collapsed content stays mounted (Accordion's animation needs real height
+  // to animate from/to) but must behave exactly like readOnly: not
+  // draggable, not resizable, not keyboard-editable. `inert` below covers
+  // consumer-rendered content too; this covers our own item chrome/wiring.
+  const itemGestures: CanvasGestures = collapsed ? { ...gestures, readOnly: true } : gestures;
+  // #353: while a move (pointer drag or keyboard pick) is in flight, an empty
+  // expanded body advertises itself as a drop target. When the drag preview
+  // hovers this section the previewed item mounts here, `items` stops being
+  // empty, and the hint yields to the regular drop-preview cell.
+  const showDropHint =
+    !collapsed &&
+    items.length === 0 &&
+    !gestures.readOnly &&
+    (gestures.movingId != null || gestures.pickedId != null);
+
+  const bandRef = useCallback((el: HTMLElement | null) => setBandEl(id, el), [id, setBandEl]);
+
+  return (
+    <Highlight active={highlighted} scrollIntoView onDone={onHighlightDone}>
+      <Accordion.Item
+        value={String(id)}
+        ref={bandRef}
+        data-dc-section={String(id)}
+        data-dragging={dragging ? '' : undefined}
+      >
+        <Accordion.Trigger
+          aria-label={t(
+            collapsed ? 'dashboardCanvas.sectionExpand' : 'dashboardCanvas.sectionCollapse',
+            { title },
+          )}
+          onKeyDown={gestures.readOnly ? undefined : (e) => onHeaderKeyDown(e, id)}
+          actions={
+            <>
+              {renderSectionHeader != null && (
+                <div data-dc-section-actions>{renderSectionHeader(id)}</div>
+              )}
+              {!gestures.readOnly && (
+                <div
+                  className={styles.sectionDragHandle}
+                  data-dc-section-handle
+                  aria-hidden="true"
+                  onPointerDown={(e) => onHeaderPointerDown(e, id)}
+                >
+                  <GripVertical size={14} aria-hidden="true" />
+                </div>
+              )}
+            </>
+          }
+        >
+          {title}
+        </Accordion.Trigger>
+        <Accordion.Content>
+          {/* .sizer: the square-cell measuring box, INSIDE Accordion.Content's
+            body padding — its width is the grid's own width, so the `cqw`
+            row unit stays square in section bodies too (same wrapper as the
+            top-level grid; see DashboardCanvas.tsx). */}
+          <div className={styles.sizer}>
+            <div
+              className={styles.container}
+              data-dc-container={String(id)}
+              data-dc-empty={items.length === 0 ? '' : undefined}
+              data-dc-drop-target={dropTarget ? '' : undefined}
+              inert={collapsed}
+              ref={(el) => setContainerEl(containerRef, el)}
+            >
+              {sortByPosition(items).map((item) => (
+                <DashboardCanvasItem
+                  key={item.id}
+                  placement={item}
+                  container={containerRef}
+                  gestures={itemGestures}
+                >
+                  {renderItem(item.id)}
+                </DashboardCanvasItem>
+              ))}
+              {showDropHint && (
+                <div className={styles.dropHint} data-dc-drop-hint aria-hidden="true">
+                  {t('dashboardCanvas.dropHint')}
+                </div>
+              )}
+            </div>
+          </div>
+        </Accordion.Content>
+      </Accordion.Item>
+    </Highlight>
+  );
+}

package/src/components/DashboardCanvas/engine.ts

@@ -0,0 +1,363 @@
+/**
+ * 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 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 function clampPlacement(
+  p: DashboardPlacement,
+  c: DashboardItemConstraints | undefined,
+  columns: number = DASHBOARD_COLUMNS,
+): DashboardPlacement {
+  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 !== undefined) 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. */
+export function collides(a: DashboardPlacement, b: DashboardPlacement): boolean {
+  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: readonly DashboardPlacement[]): DashboardPlacement[] {
+  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: readonly DashboardPlacement[],
+  obstacles: DashboardPlacement[],
+  fromCurrentY = false,
+): Map<string | number, DashboardPlacement> {
+  const placed = [...obstacles];
+  const settled = new Map<string | number, DashboardPlacement>();
+  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; // just below the collider; y strictly grows, so this terminates
+    }
+    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.
+ */
+export function compact(items: DashboardPlacement[]): DashboardPlacement[] {
+  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.
+ */
+export function placeWithPushDown(
+  items: DashboardPlacement[],
+  moved: DashboardPlacement,
+): DashboardPlacement[] {
+  const rest = items.filter((item) => item.id !== moved.id);
+  const pushed = settle(rest, [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: DashboardCanvasValue,
+  ref: ContainerRef,
+): DashboardPlacement[] | undefined {
+  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: DashboardCanvasValue,
+  ref: ContainerRef,
+  items: DashboardPlacement[],
+): DashboardCanvasValue {
+  if (ref.kind === 'top') return { ...value, items };
+  return {
+    ...value,
+    sections: value.sections.map((section) =>
+      section.id === ref.id ? { ...section, items } : section,
+    ),
+  };
+}
+
+function sameContainer(a: ContainerRef, b: ContainerRef): boolean {
+  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: readonly DashboardPlacement[],
+  b: readonly DashboardPlacement[],
+): boolean {
+  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).
+ */
+export function applyMove(
+  value: DashboardCanvasValue,
+  from: ContainerRef,
+  to: ContainerRef,
+  id: string | number,
+  x: number,
+  y: number,
+  columns: number = DASHBOARD_COLUMNS,
+): DashboardCanvasValue {
+  const source = containerItems(value, from);
+  const item = source?.find((candidate) => candidate.id === id);
+  if (!source || !item || containerItems(value, to) === undefined) return value;
+  const dropped = clampPlacement({ ...item, x, y }, undefined, 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).
+ */
+export function applyResize(
+  value: DashboardCanvasValue,
+  container: ContainerRef,
+  id: string | number,
+  w: number,
+  h: number,
+  c?: DashboardItemConstraints,
+  columns: number = DASHBOARD_COLUMNS,
+): DashboardCanvasValue {
+  const items = containerItems(value, container);
+  const item = items?.find((candidate) => candidate.id === id);
+  if (!items || !item) return value;
+  // Outermost floor: an invalid controlled x >= columns must not yield w <= 0.
+  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 !== undefined) 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). */
+export function toggleSection(
+  value: DashboardCanvasValue,
+  sectionId: string | number,
+): DashboardCanvasValue {
+  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. */
+export function reorderSection(
+  value: DashboardCanvasValue,
+  sectionId: string | number,
+  toIndex: number,
+): DashboardCanvasValue {
+  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 };
+}
+
+/**
+ * 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 function stackOrder(
+  value: DashboardCanvasValue,
+): { container: ContainerRef; id: string | number }[] {
+  const out: { container: ContainerRef; id: string | number }[] = [];
+  for (const item of sortByPosition(value.items)) {
+    out.push({ container: { kind: 'top' }, id: item.id });
+  }
+  for (const section of value.sections) {
+    for (const item of sortByPosition(section.items)) {
+      out.push({ container: { kind: 'section', id: section.id }, id: item.id });
+    }
+  }
+  return out;
+}
+
+/**
+ * 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 function cellFromPoint(
+  px: number,
+  py: number,
+  containerRect: DOMRect,
+  colWidth: number,
+  rowHeight: number,
+  gap: number,
+  columns: number = DASHBOARD_COLUMNS,
+): { x: number; y: number } {
+  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`.
+ */
+export function insertionCell(
+  items: readonly DashboardPlacement[],
+  id: string | number,
+  w: number,
+  px: number,
+  py: number,
+  fallback: { x: number; y: number },
+  columns: number = DASHBOARD_COLUMNS,
+): { x: number; y: number } {
+  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). */
+export function clampGhost(
+  left: number,
+  top: number,
+  w: number,
+  h: number,
+  boundsW: number,
+  boundsH: number,
+): { left: number; top: number } {
+  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)),
+  };
+}

package/src/components/DashboardCanvas/index.ts

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