@xeplr/ui-canvas 1.0.1

package/src/geometry.js

@@ -0,0 +1,326 @@
+// Free-canvas geometry — where an item is, and what moving or resizing one
+// does. Pure, so the arithmetic that actually goes wrong is testable without
+// a mouse. No React, no DOM.
+//
+// Moved here from the BI dashboard builder so every canvas — dashboard,
+// workflow, dataset joins, the UI creator — lands on the same rules.
+//
+// Free placement rather than a snap grid WAS a deliberate choice: a board is
+// composed, not filled. The cost is that "roughly aligned" is the natural
+// result of dragging, and a board of nearly-aligned edges looks broken in a
+// way a grid never does.
+//
+// BOTH NOW, and in that order. The grid came back because composing a unit out
+// of five items needs consistent widths and gaps, which free placement makes
+// you achieve by eye every time. It is the FALLBACK though: alignment snapping
+// is tried first and wins, because lining up with the box beside you is a
+// stronger intent than landing on a round number. See GRID below.
+//
+// So the canvas offers ALIGNMENT SNAPPING first — while you drag, an edge or
+// centre that comes within a few pixels of another item's edge or centre
+// jumps to it exactly, and the guide is drawn so you can see why it moved.
+
+// ── FRACTIONAL geometry ───────────────────────────────────────────────
+//
+// An item may store where it sits as a FRACTION of the canvas (0..1) rather
+// than as pixels (units: 'fraction'). A board laid out on a 27-inch screen
+// then still reads on a laptop.
+//
+// The two axes are NOT the same fraction, and the difference is the point.
+//
+//   x and w  are a fraction of the canvas WIDTH — so a board laid out wide
+//            still reads narrow, and nothing hangs off the right edge.
+//   y and h  are a fraction of a PAGE, where one page is the visible height.
+//            y may exceed 1: 1.5 is half a page below the fold.
+//
+// Horizontal space is fixed by the window and vertical space is not — you
+// scroll down, you do not scroll sideways.
+//
+// Dragging still works in PIXELS, because a mouse does. The conversion
+// happens once, when the position is committed.
+
+// An item's floor.
+//
+// What the floor is for is keeping an item SELECTABLE — a box you cannot get
+// hold of cannot be resized back, or deleted. So it is set to the smallest
+// thing you can still reliably grab, and no larger. A caller with smaller
+// things (a one-pixel rule) passes its own via minSizeFor.
+export const MIN_WIDTH = 48
+export const MIN_HEIGHT = 28
+
+/** How close an edge has to come before it snaps. */
+export const SNAP_TOLERANCE = 6
+
+/**
+ * The background grid, in px. A canvas that draws a grid should draw it at
+ * this spacing, so what you see and what you land on are the same.
+ *
+ * ALIGNMENT SNAPPING STILL WINS. The grid is the fallback for an axis that hit
+ * nothing: a grid that overrode alignment would pull an item off the edge it
+ * was just aligned to.
+ */
+export const GRID = 10
+export const DEFAULT_SIZE = { w: 420, h: 300 }
+
+/** The eight handles, as [x, y] multipliers of the box's size. */
+export const RESIZE_HANDLES = [
+  { key: 'nw', x: 0, y: 0 }, { key: 'n', x: 0.5, y: 0 }, { key: 'ne', x: 1, y: 0 },
+  { key: 'w', x: 0, y: 0.5 }, { key: 'e', x: 1, y: 0.5 },
+  { key: 'sw', x: 0, y: 1 }, { key: 's', x: 0.5, y: 1 }, { key: 'se', x: 1, y: 1 }
+]
+
+/** A pixel item's rect, with defaults for anything unset. */
+export function rectOf(item) {
+  return { x: item.x || 0, y: item.y || 0, w: item.w || DEFAULT_SIZE.w, h: item.h || DEFAULT_SIZE.h }
+}
+
+/**
+ * An item's rect in PIXELS whatever it is stored in — the one conversion the
+ * drag, the marquee and the edges all need.
+ *
+ * A fraction item with no measured canvas yet falls back to its raw values:
+ * the same thing the dashboard always did before its canvas was measured.
+ */
+export function pixelRect(item, units, canvas) {
+  return units === 'fraction' && canvas ? toPixels(item, canvas) : rectOf(item)
+}
+
+/** The lines a rect can snap to: both edges and the centre, per axis. */
+function linesOf(rect) {
+  return {
+    x: [rect.x, rect.x + rect.w / 2, rect.x + rect.w],
+    y: [rect.y, rect.y + rect.h / 2, rect.y + rect.h]
+  }
+}
+
+/**
+ * The nearest snap for one axis.
+ *
+ * `candidates` are the moving rect's own lines — so a right edge snapping to
+ * another item's left edge moves the whole box, not just that edge.
+ *
+ * @returns {{ delta, line }|null} delta — add to the origin; line — where to
+ *          draw the guide
+ */
+function nearestSnap(candidates, targets, tolerance) {
+  let best = null
+  for (const c of candidates) {
+    for (const t of targets) {
+      const distance = Math.abs(c.at - t)
+      if (distance > tolerance) continue
+      if (!best || distance < best.distance) best = { distance, delta: t - c.at, line: t }
+    }
+  }
+  return best ? { delta: best.delta, line: best.line } : null
+}
+
+/**
+ * Moves a rect to (x, y), snapping to the others.
+ *
+ * @param others  the rects to snap against — every item except this one
+ * @returns {{ x, y, guides }} guides — [{ axis, at }] for the ones that hit
+ */
+export function moveRect(rect, x, y, others, opts) {
+  const tolerance = opts?.tolerance ?? SNAP_TOLERANCE
+  // Held down, snapping is off: the point of a free canvas is that you can
+  // always overrule it.
+  const free = Boolean(opts?.disableSnap)
+  const moved = { x, y, w: rect.w, h: rect.h }
+  const guides = []
+
+  if (!free && others.length) {
+    const targets = others.map(linesOf)
+    const targetX = targets.flatMap((t) => t.x)
+    const targetY = targets.flatMap((t) => t.y)
+
+    const snapX = nearestSnap(
+      [{ at: moved.x }, { at: moved.x + moved.w / 2 }, { at: moved.x + moved.w }], targetX, tolerance)
+    const snapY = nearestSnap(
+      [{ at: moved.y }, { at: moved.y + moved.h / 2 }, { at: moved.y + moved.h }], targetY, tolerance)
+
+    if (snapX) { moved.x += snapX.delta; guides.push({ axis: 'x', at: snapX.line }) }
+    if (snapY) { moved.y += snapY.delta; guides.push({ axis: 'y', at: snapY.line }) }
+
+    // Only where nothing better was found — see GRID.
+    const grid = opts?.grid ?? GRID
+    if (grid > 0) {
+      if (!snapX) moved.x = Math.round(moved.x / grid) * grid
+      if (!snapY) moved.y = Math.round(moved.y / grid) * grid
+    }
+  }
+
+  // Negative coordinates put an item where no scrollbar can reach it.
+  return { x: Math.max(0, Math.round(moved.x)), y: Math.max(0, Math.round(moved.y)), guides }
+}
+
+/**
+ * Resizes from one handle, keeping the opposite edge fixed.
+ *
+ * Below the minimum the box stops growing INWARD rather than flipping: a box
+ * dragged past its own opposite edge would otherwise invert, and a negative
+ * width is not a shape anything can render.
+ */
+export function resizeRect(rect, handle, dx, dy, opts) {
+  const min = { w: opts?.minWidth ?? MIN_WIDTH, h: opts?.minHeight ?? MIN_HEIGHT }
+  const h = RESIZE_HANDLES.find((k) => k.key === handle)
+  if (!h) return { ...rect }
+
+  let { x, y, w, hgt } = { x: rect.x, y: rect.y, w: rect.w, hgt: rect.h }
+
+  if (h.x === 0) {           // dragging the left edge: the right stays put
+    const right = x + w
+    x = Math.min(x + dx, right - min.w)
+    w = right - x
+  } else if (h.x === 1) {
+    w = Math.max(min.w, w + dx)
+  }
+
+  if (h.y === 0) {           // dragging the top edge: the bottom stays put
+    const bottom = y + hgt
+    y = Math.min(y + dy, bottom - min.h)
+    hgt = bottom - y
+  } else if (h.y === 1) {
+    hgt = Math.max(min.h, hgt + dy)
+  }
+
+  // SNAPPING WHILE RESIZING, and only on the edges actually being dragged.
+  //
+  // A resize holds one edge still by definition — grabbing the right handle
+  // must never shift the left — so only the moving edge is offered as a
+  // candidate. Snapping the fixed one would drag the box sideways while you
+  // were trying to make it wider.
+  const guides = []
+  const others = opts?.others
+  if (others && others.length && !opts?.disableSnap) {
+    const tolerance = opts?.tolerance ?? SNAP_TOLERANCE
+    const targets = others.map(linesOf)
+    const targetX = targets.flatMap((t) => t.x)
+    const targetY = targets.flatMap((t) => t.y)
+
+    if (h.x === 0) {
+      const snap = nearestSnap([{ at: x }], targetX, tolerance)
+      if (snap) { const right = x + w; x += snap.delta; w = right - x; guides.push({ axis: 'x', at: snap.line }) }
+    } else if (h.x === 1) {
+      const snap = nearestSnap([{ at: x + w }], targetX, tolerance)
+      if (snap) { w += snap.delta; guides.push({ axis: 'x', at: snap.line }) }
+    }
+
+    if (h.y === 0) {
+      const snap = nearestSnap([{ at: y }], targetY, tolerance)
+      if (snap) { const bottom = y + hgt; y += snap.delta; hgt = bottom - y; guides.push({ axis: 'y', at: snap.line }) }
+    } else if (h.y === 1) {
+      const snap = nearestSnap([{ at: y + hgt }], targetY, tolerance)
+      if (snap) { hgt += snap.delta; guides.push({ axis: 'y', at: snap.line }) }
+    }
+  }
+
+  return {
+    x: Math.max(0, Math.round(x)),
+    y: Math.max(0, Math.round(y)),
+    w: Math.round(Math.max(min.w, w)),
+    h: Math.round(Math.max(min.h, hgt)),
+    guides
+  }
+}
+
+/**
+ * The canvas has to be at least big enough to hold everything on it.
+ *
+ * @param padding  a number, or { x, y } when the room wanted to the right
+ *                 differs from the room wanted below
+ */
+export function canvasBounds(rects, padding) {
+  const pad = padding ?? 80
+  const padX = typeof pad === 'object' ? pad.x || 0 : pad
+  const padY = typeof pad === 'object' ? pad.y || 0 : pad
+  let width = 0
+  let height = 0
+  for (const item of rects || []) {
+    const r = rectOf(item)
+    width = Math.max(width, r.x + r.w)
+    height = Math.max(height, r.y + r.h)
+  }
+  return { width: width + padX, height: height + padY }
+}
+
+/**
+ * Raises `id` above the rest.
+ *
+ * Renumbered from zero rather than "max + 1" so z never climbs forever — a
+ * board that is rearranged for a year would otherwise carry meaningless
+ * five-digit z values, and their ORDER is the only thing that matters.
+ */
+export function bringToFront(items, id) {
+  const others = (items || []).filter((item) => item.id !== id)
+  const target = (items || []).find((item) => item.id === id)
+  if (!target) return items || []
+  const ordered = [...others].sort((a, b) => (a.z || 0) - (b.z || 0))
+  const renumbered = ordered.map((item, i) => ({ ...item, z: i }))
+  return [...renumbered, { ...target, z: renumbered.length }]
+}
+
+/** Items in paint order — the one on top renders last. */
+export function inStackOrder(items) {
+  return [...(items || [])].sort((a, b) => (a.z || 0) - (b.z || 0))
+}
+
+/** A new item: a bit under half the width, a third of the height. */
+export const DEFAULT_FRACTION = { w: 0.45, h: 0.35 }
+
+/** A pixel rect → fractions of the canvas, clamped to stay on it. */
+export function toFraction(rect, canvas) {
+  const cw = canvas?.width || 1
+  const ch = canvas?.height || 1
+  // Size first: the position clamp below depends on it.
+  const w = clamp01((rect.w || 0) / cw)
+  // An item may be TALLER than one page — a long table is a reasonable thing
+  // to place — so height is not capped at 1 either.
+  const h = Math.max(0, (rect.h || 0) / ch)
+  return {
+    // x + w never exceeds 1, so an item cannot be placed where the canvas
+    // does not reach sideways — which with fractions would be nowhere at all.
+    x: clamp(0, 1 - w, (rect.x || 0) / cw),
+    // NOT clamped to one page. The canvas grows downward to hold whatever is
+    // placed on it.
+    y: Math.max(0, (rect.y || 0) / ch),
+    w, h
+  }
+}
+
+/** Fractions → a pixel rect on the canvas. */
+export function toPixels(fraction, canvas) {
+  const cw = canvas?.width || 0
+  const ch = canvas?.height || 0
+  return {
+    x: Math.round((fraction.x || 0) * cw),
+    y: Math.round((fraction.y || 0) * ch),
+    // An item with no stored size gets a readable default rather than
+    // collapsing to nothing.
+    w: Math.round((fraction.w || DEFAULT_FRACTION.w) * cw),
+    h: Math.round((fraction.h || DEFAULT_FRACTION.h) * ch)
+  }
+}
+
+/**
+ * Every rect the band touches, by id.
+ *
+ * TOUCHES, not encloses. Requiring full containment means a band drawn across
+ * a row of wide cards selects nothing, and the user has to start outside the
+ * board and sweep the lot — which is the behaviour people complain about in
+ * every tool that chooses it.
+ *
+ * @param rects  [{ id, x, y, w, h }] in pixels
+ */
+export function hits(rects, band) {
+  return (rects || []).filter((r) => overlaps(r, band)).map((r) => r.id)
+}
+
+export function overlaps(a, b) {
+  return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y
+}
+
+function clamp01(v) { return clamp(0, 1, v) }
+function clamp(min, max, v) {
+  if (!Number.isFinite(v)) return min
+  return Math.min(max, Math.max(min, v))
+}

package/src/index.js

@@ -0,0 +1,29 @@
+// @xeplr/ui-canvas — one canvas for every xeplr builder.
+//
+// Three ways in, per the xeplr-ui-* convention:
+//   1. <XeplrCanvas> as-is
+//   2. the controller hooks with your own design (the BI dashboard does this)
+//   3. the model alone — '@xeplr/ui-canvas/geometry' and '/edges' have no
+//      React, so they run in node tests too
+
+// Model
+export {
+  MIN_WIDTH, MIN_HEIGHT, SNAP_TOLERANCE, GRID, DEFAULT_SIZE, DEFAULT_FRACTION, RESIZE_HANDLES,
+  rectOf, pixelRect, moveRect, resizeRect, canvasBounds, bringToFront, inStackOrder,
+  toFraction, toPixels, hits, overlaps
+} from './geometry.js'
+export { anchorOf, bezierPath, midpoint, edgeEnds } from './edges.js'
+export { createFrameStore } from './frameStore.js'
+export { validateCanvasProps } from './validateCanvas.js'
+
+// Controllers
+export { useCanvasDrag, ITEM_ID_ATTR } from './useCanvasDrag.js'
+export { useMarquee, SWEEPING_CLASS } from './useMarquee.js'
+export { useCanvasSize } from './useCanvasSize.js'
+export { useCanvasController, DEFAULT_FEATURES } from './useCanvasController.js'
+
+// Designs
+export { CanvasSample, DragGuides, MarqueeBox, ResizeHandles, EdgeLayer } from './designs/index.js'
+
+// Ready-made
+export { XeplrCanvas } from './pages.jsx'

package/src/pages.jsx

@@ -0,0 +1,48 @@
+import { useCanvasController } from './useCanvasController.js'
+import { validateCanvasProps } from './validateCanvas.js'
+import { CanvasSample } from './designs/index.js'
+
+/**
+ * The ready-made canvas: controller + design.
+ *
+ * One component, every capability; a builder switches on what it needs.
+ *
+ *   dashboard / UI creator   features={{ resize: true, marquee: true }}
+ *   workflow / dataset       edges={[...]}  (drag and snap are on by default)
+ *
+ * @prop items            [{ id, x, y, w, h, z?, groupId? }]
+ * @prop units            'px' (default) | 'fraction'
+ * @prop features         { drag, resize, snap, grid, marquee } — see DEFAULT_FEATURES
+ * @prop selection        ids (array or Set) — controlled; omit to let the canvas own it
+ * @prop onSelectionChange(Set)
+ * @prop onItemChange     (id, patch) — on drop, in the item's own units
+ * @prop onItemClick      (id, event) — a press that never became a drag
+ * @prop onRaise          (id) — on grab
+ * @prop renderItem       (item, { selected }) → node — REQUIRED
+ * @prop minSizeFor       (item) → { minWidth, minHeight }
+ * @prop edges            [{ id, from, to | toOffset, fromPort?, toPort?, variant?, className? }]
+ * @prop getAnchor        (item, port, 'from'|'to', rect) → { x, y } — for port edges
+ * @prop renderEdgeLabel  (edge, { from, to, mid }) → node — absolutely positioned by you
+ * @prop edgeMinOffset    minimum sideways reach of an edge's curve, px (default 60)
+ * @prop padding          room beyond the furthest item: number or { x, y }
+ * @prop minWidth, minHeight  the smallest the inner canvas gets
+ * @prop underlay, overlay    extra layers under the edges / over everything
+ * @prop className, style     on the scrolling wrapper
+ */
+export function XeplrCanvas(props) {
+  validateCanvasProps(props)
+  const ctrl = useCanvasController(props)
+  return (
+    <CanvasSample
+      ctrl={ctrl}
+      renderItem={props.renderItem}
+      getAnchor={props.getAnchor}
+      renderEdgeLabel={props.renderEdgeLabel}
+      edgeMinOffset={props.edgeMinOffset}
+      underlay={props.underlay}
+      overlay={props.overlay}
+      className={props.className}
+      style={props.style}
+    />
+  )
+}

package/src/useCanvasController.js

@@ -0,0 +1,181 @@
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { GRID, canvasBounds, inStackOrder, pixelRect, toFraction } from './geometry.js'
+import { useCanvasDrag } from './useCanvasDrag.js'
+import { useMarquee } from './useMarquee.js'
+import { useCanvasSize } from './useCanvasSize.js'
+
+// The ready-made canvas's controller: features, selection and the gestures,
+// wired together. No JSX — XeplrCanvas (pages.jsx) hands this to a design.
+//
+// A builder with a selection model of its own (the BI dashboard: groups you
+// click into, a property drawer) uses useCanvasDrag / useMarquee directly
+// instead, and keeps its own. This is the version for a builder that just
+// wants a canvas.
+
+export const DEFAULT_FEATURES = {
+  drag: true,
+  resize: false,
+  snap: true,
+  grid: GRID,
+  marquee: false
+}
+
+/** Below this, a press on an item is a click and not a drag. */
+const CLICK_THRESHOLD = 4
+
+export function useCanvasController(props) {
+  const {
+    items, units = 'px', features, edges, selection,
+    onItemClick, onRaise, minSizeFor,
+    padding, minWidth = 0, minHeight = 0
+  } = props
+  // onItemChange and onSelectionChange are read through propsRef below, so a
+  // new inline handler from the caller never rebuilds the gestures.
+
+  const f = useMemo(() => ({ ...DEFAULT_FEATURES, ...features }), [features])
+  const fraction = units === 'fraction'
+
+  // Measured only for a fractional canvas, where a page IS the visible size.
+  const [measured, measureRef] = useCanvasSize()
+  const canvas = fraction ? measured : null
+  const canvasRef = useRef(canvas); canvasRef.current = canvas
+  const rootRef = useRef(null)
+
+  // SELECTION — controlled when `selection` is passed, owned here otherwise.
+  const [ownSelection, setOwnSelection] = useState(() => new Set())
+  const selected = useMemo(
+    () => (selection ? new Set(selection) : ownSelection),
+    [selection, ownSelection]
+  )
+  // Read through refs by the handlers, so they stay stable.
+  const selectedRef = useRef(selected); selectedRef.current = selected
+  const itemsRef = useRef(items); itemsRef.current = items
+  const propsRef = useRef(props); propsRef.current = props
+
+  const setSelected = useCallback((next) => {
+    if (!propsRef.current.selection) setOwnSelection(next)
+    propsRef.current.onSelectionChange?.(next)
+  }, [])
+
+  // A GROUP IS ONE THING: touching any member takes the whole group.
+  const withGroups = useCallback((ids) => {
+    const all = itemsRef.current
+    const picked = new Set()
+    ids.forEach((id) => {
+      const item = all.find((x) => x.id === id)
+      if (item?.groupId) all.filter((x) => x.groupId === item.groupId).forEach((x) => picked.add(x.id))
+      else picked.add(id)
+    })
+    return picked
+  }, [])
+
+  // Pixels in, the item's own units out.
+  const commit = useCallback((id, patch) => {
+    const { onItemChange: write, units: u } = propsRef.current
+    if (!write) return
+    if (u !== 'fraction') return write(id, patch)
+    const current = itemsRef.current.find((w) => w.id === id)
+    if (!current || !canvasRef.current) return write(id, patch)
+    write(id, toFraction({ ...pixelRect(current, 'fraction', canvasRef.current), ...patch }, canvasRef.current))
+  }, [])
+
+  const drag = useCanvasDrag({
+    items,
+    units,
+    canvas,
+    rootRef,
+    onUpdate: commit,
+    onRaise,
+    onClick: onItemClick,
+    minSizeFor,
+    snap: f.snap,
+    grid: f.grid,
+    clickThreshold: CLICK_THRESHOLD
+  })
+  const dragRef = useRef(drag); dragRef.current = drag
+
+  const marquee = useMarquee({
+    items,
+    units,
+    canvas,
+    canvasElRef: rootRef,
+    onSelect: useCallback((ids, additive) => {
+      const picked = withGroups(ids)
+      if (!additive) return setSelected(picked)
+      const next = new Set(selectedRef.current)
+      picked.forEach((id) => next.add(id))
+      setSelected(next)
+    }, [withGroups, setSelected]),
+    onClear: useCallback(() => {
+      if (selectedRef.current.size) setSelected(new Set())
+    }, [setSelected])
+  })
+
+  // PRESS ON AN ITEM. Modifier toggles it in the selection; otherwise it
+  // drags — the whole selection when the item is part of one, else the item
+  // (and its group) alone.
+  const onItemMouseDown = useCallback((e, id) => {
+    if (e.button !== 0) return
+    const modifier = e.ctrlKey || e.metaKey || e.shiftKey
+    const members = [...withGroups([id])]
+    const current = selectedRef.current
+
+    if (modifier) {
+      const next = new Set(current)
+      const allIn = members.every((m) => next.has(m))
+      members.forEach((m) => (allIn ? next.delete(m) : next.add(m)))
+      setSelected(next)
+      return
+    }
+
+    const ids = current.has(id) && current.size > 1 ? [...current] : members
+    const same = ids.length === current.size && ids.every((x) => current.has(x))
+    if (!same) setSelected(new Set(ids))
+    if (propsRef.current.features?.drag === false) return
+    dragRef.current.startDrag(e, ids)
+  }, [withGroups, setSelected])
+
+  const onResizeStart = useCallback((e, id, handle) => {
+    dragRef.current.startResize(e, id, handle)
+  }, [])
+
+  // Pixel rects, by id — what the items and edges are drawn from.
+  const rectById = useMemo(() => {
+    const map = {}
+    items.forEach((item) => { map[item.id] = pixelRect(item, units, canvas) })
+    return map
+  }, [items, units, canvas])
+
+  const itemById = useMemo(() => {
+    const map = {}
+    items.forEach((item) => { map[item.id] = item })
+    return map
+  }, [items])
+
+  // How big the inner canvas is: enough for everything on it, never less
+  // than the minimum. A fractional canvas is at least one page.
+  const size = useMemo(() => {
+    const bounds = canvasBounds(Object.values(rectById), padding)
+    if (fraction) {
+      return { width: '100%', height: Math.max(canvas ? canvas.height : 0, bounds.height, minHeight) }
+    }
+    return { width: Math.max(minWidth, bounds.width), height: Math.max(minHeight, bounds.height) }
+  }, [rectById, padding, fraction, canvas, minWidth, minHeight])
+
+  return {
+    rootRef,
+    measureRef,
+    features: f,
+    stacked: useMemo(() => inStackOrder(items), [items]),
+    rectById,
+    itemById,
+    edges: edges || [],
+    selected,
+    size,
+    guideStore: drag.guideStore,
+    marqueeStore: marquee.marqueeStore,
+    onCanvasMouseDown: f.marquee ? marquee.onMouseDown : undefined,
+    onItemMouseDown,
+    onResizeStart
+  }
+}