/**
* QuadrantSync — the pinpoint overlay.
*
* Dev chrome for agreeing on WHICH element is being discussed before anyone
* edits it. Draws a chess-style grid on a named node and emits one sync line —
* `StageModuleGroup @ 1440w · e8 → h7` — that both sides restate. Born from a
* real failure: ten messages to move one button, none of them wrong about CSS,
* all of them about different elements.
*
* The rule that outranks every other: **the grid goes on what the USER named.**
* Never redirected to a child or a parent. The owner is REPORTED, never
* substituted — a grab-handle that moves a whole group lives at group level,
* and quietly re-pointing the grid at a child answers a question nobody asked.
*
* Mark nodes with `data-handle="Name"` on divs that already exist — never a
* wrapper added for the tool's benefit. Optionally `data-source="@kolkrabbi/…"`
* so design-system ownership is a fact at selection time, not a discovery
* mid-edit.
*
* A cell is a FRACTION of the named element, which is why `e8` means the same
* relative place at 1440w and 760w and a pixel offset never does.
*
* Measures and positions over nodes from a fixed layer; it never wraps a node,
* so grid position tracks the RENDERED layout rather than the tree. Renders
* nothing when `enabled` is false — dev-only by default.
*
* @param {Object} props
* @param {HTMLElement} props.root Subtree to hunt handles in (default document.body)
* @param {string} props.attr Attribute naming a node (default 'data-handle')
* @param {string} props.sourceAttr Attribute naming a node's origin (default 'data-source')
* @param {Array} props.bands Breakpoint bands; the live one is READ from the window
* @param {Object} props.defaultDivisions `{ cols, rows }` before `square` is applied
* @param {string} props.initialHandle Handle name to select on mount
* @param {Function} props.onSyncLine (line, parts) => void, fired when the line changes
* @param {string} props.handleColor Grid + outline color for the named node
* @param {string} props.pageColor Grid color for the page reference
* @param {boolean} props.enabled Render at all (default: off in production)
*/
import { useCallback, useEffect, useRef, useState } from 'react'
import { Tooltip } from './Popover.jsx'
/* ── coordinates ─────────────────────────────────────────────────────────
* Pure. No DOM writes. The invariant everything rests on: a cell is a
* fraction of the box, so the same relative point resolves to the same cell
* at any size.
*/
const LETTERS = 'abcdefghijklmnopqrstuvwxyz'
export const MAX_COLS = 26
export const MAX_ROWS = 100
const SQUARE_TOLERANCE = 0.06
const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v))
/** `a1` is TOP-LEFT — screen convention, not chess's bottom-left. */
const cellLabel = (c, r) => LETTERS[c] + (r + 1)
const rectOf = (el) => {
const r = el.getBoundingClientRect()
return { left: r.left, top: r.top, width: r.width, height: r.height, right: r.right, bottom: r.bottom }
}
/** Which cell of `box` holds the viewport point. Out-of-box points clamp. */
function cellAt (box, px, py, cols, rows) {
return {
c: clamp(Math.floor(((px - box.left) / box.width) * cols), 0, cols - 1),
r: clamp(Math.floor(((py - box.top) / box.height) * rows), 0, rows - 1)
}
}
/** An element SPANS cells, it does not sit in one — `c1–f8`, or one label if it fits one cell. */
function spanOf (child, parent, cols, rows) {
const a = cellAt(parent, child.left + 1, child.top + 1, cols, rows)
const b = cellAt(parent, child.right - 1, child.bottom - 1, cols, rows)
const s = cellLabel(a.c, a.r)
const e = cellLabel(b.c, b.r)
return s === e ? s : `${s}–${e}`
}
function cellAspect (box, cols, rows) {
if (!box || !box.width || !box.height) return null
const cw = box.width / cols
const ch = box.height / rows
const ratio = cw / ch
return { cw, ch, ratio, isSquare: Math.abs(ratio - 1) <= SQUARE_TOLERANCE }
}
/**
* Derive the second axis so cells come out square on THIS box.
*
* One-shot on purpose. Recomputing on every reflow would silently change what
* a coordinate means, which is the confusion this whole thing exists to remove.
* After a reflow the cells stretch into rectangles — expected, and fine.
*
* The axis caps can make a naive first pass unusable on an extreme box (a 5.7:1
* strip at 8 columns wants 1.4 rows), so re-anchor on the other axis and derive
* back through the cap.
*/
function squareDivisions (box, cols, rows) {
if (!box || !box.width || !box.height) return { cols, rows }
const ar = box.width / box.height
let c = clamp(cols, 1, MAX_COLS)
let r = Math.round(c / ar)
if (r < 2) {
r = 2
c = clamp(Math.round(r * ar), 1, MAX_COLS)
r = clamp(Math.round(c / ar), 1, MAX_ROWS)
} else if (r > MAX_ROWS) {
r = MAX_ROWS
c = clamp(Math.round(r * ar), 1, MAX_COLS)
r = clamp(Math.round(c / ar), 1, MAX_ROWS)
}
return { cols: c, rows: r }
}
/* ── the tree ─────────────────────────────────────────────────────────── */
/** Nearest ancestor carrying a handle. A REPORT, never a redirect. */
function ownerOf (el, attr) {
let p = el.parentElement
while (p && p !== document.body && !p.hasAttribute(attr)) p = p.parentElement
return p && p.hasAttribute(attr) ? p : null
}
function chainOf (el, attr) {
const names = []
let cur = ownerOf(el, attr)
while (cur) {
names.unshift(cur.getAttribute(attr))
cur = ownerOf(cur, attr)
}
return names
}
/** The owner's layout mode, and which axis it actually makes reachable. */
function layoutOf (el) {
const cs = getComputedStyle(el)
if (cs.display === 'flex' || cs.display === 'inline-flex') {
const column = cs.flexDirection.startsWith('column')
return { mode: `flex ${column ? 'column' : 'row'}`, axis: column ? 'y' : 'x' }
}
if (cs.display === 'grid' || cs.display === 'inline-grid') return { mode: 'grid', axis: 'xy' }
return { mode: cs.display, axis: 'y' }
}
/* A cell says WHERE, never what CSS to change. When a cell is unreachable in
* the owner's mode, saying so is the feature — a diff that cannot work is worse
* than an honest no. */
function reachability (layout) {
if (layout.axis === 'x') return 'Horizontal order reachable; vertical needs align/self.'
if (layout.axis === 'y') return "Vertical order reachable; horizontal needs the owner's layout mode changed."
return 'Both axes reachable via grid placement.'
}
/* ── breakpoint bands: read from the window, never chosen ─────────────── */
export const DEFAULT_BANDS = [
{ name: 'Mobile', min: 0, max: 559 },
{ name: 'Tablet', min: 560, max: 859 },
{ name: 'Laptop', min: 860, max: 1279 },
{ name: 'Desktop', min: 1280, max: Infinity }
]
const bandFor = (w, bands) => bands.find((b) => w >= b.min && w <= b.max) || bands[bands.length - 1]
/* ── the deliverable ──────────────────────────────────────────────────── */
/** `StageModuleGroup @ 1440w · e8 → h7` */
function formatSyncLine (handle, width, from, to) {
let s = `${handle} @ ${width}w`
if (from) {
s += ` · ${from}`
if (to) s += ` → ${to}`
}
return s
}
const IS_PROD = typeof process !== 'undefined' && process.env && process.env.NODE_ENV === 'production'
export default function QuadrantSync ({
root = null,
attr = 'data-handle',
sourceAttr = 'data-source',
bands = DEFAULT_BANDS,
defaultDivisions = { cols: 8, rows: 8 },
initialHandle = '',
onSyncLine,
handleColor = 'var(--kol-accent-primary)',
pageColor = 'var(--kol-fg-40, color-mix(in srgb, var(--kol-surface-on-primary) 40%, transparent))',
enabled = !IS_PROD
}) {
const [handle, setHandle] = useState(null)
const [cols, setCols] = useState(defaultDivisions.cols)
const [rows, setRows] = useState(defaultDivisions.rows)
const [fade, setFade] = useState(0.7)
const [showPage, setShowPage] = useState(false)
const [showHandle, setShowHandle] = useState(true)
const [showLabels, setShowLabels] = useState(true)
const [from, setFrom] = useState(null)
const [to, setTo] = useState(null)
const [settingsOpen, setSettingsOpen] = useState(false)
const [reportOpen, setReportOpen] = useState(false)
const [copied, setCopied] = useState(false)
const [width, setWidth] = useState(0)
const [, setTick] = useState(0)
const rootEl = root || (typeof document !== 'undefined' ? document.body : null)
/* re-measure whenever the world moves — the grid tracks the rendered layout */
useEffect(() => {
if (!enabled || typeof window === 'undefined') return undefined
const bump = () => {
setWidth(window.innerWidth)
setTick((t) => t + 1)
}
bump()
window.addEventListener('resize', bump)
window.addEventListener('scroll', bump, true)
const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(bump) : null
if (ro && rootEl) ro.observe(rootEl)
return () => {
window.removeEventListener('resize', bump)
window.removeEventListener('scroll', bump, true)
if (ro) ro.disconnect()
}
}, [enabled, rootEl])
/* click-to-name */
useEffect(() => {
if (!enabled || !rootEl) return undefined
const onClick = (e) => {
const t = e.target
if (!t || !t.closest || t.closest('[data-quadrant-chrome]')) return
const el = t.closest(`[${attr}]`)
if (!el) return
e.preventDefault()
e.stopPropagation()
setHandle(el)
setFrom(null)
setTo(null)
}
rootEl.addEventListener('click', onClick, true)
return () => rootEl.removeEventListener('click', onClick, true)
}, [enabled, rootEl, attr])
useEffect(() => {
if (!enabled || !initialHandle || handle || typeof document === 'undefined') return
const el = document.querySelector(`[${attr}="${initialHandle}"]`)
if (el) setHandle(el)
}, [enabled, initialHandle, handle, attr])
/* outline the handle and its owner, restoring whatever was there before */
useEffect(() => {
if (!enabled) return undefined
const own = handle ? ownerOf(handle, attr) : null
const prev = []
if (handle) {
prev.push([handle, handle.style.outline, handle.style.outlineOffset])
handle.style.outline = `2px solid ${handleColor}`
handle.style.outlineOffset = '1px'
}
if (own) {
prev.push([own, own.style.outline, own.style.outlineOffset])
own.style.outline = `2px dashed ${pageColor}`
own.style.outlineOffset = '5px'
}
return () => prev.forEach(([el, o, off]) => {
el.style.outline = o
el.style.outlineOffset = off
})
}, [enabled, handle, attr, handleColor, pageColor])
const owner = handle && enabled ? ownerOf(handle, attr) : null
const handleBox = handle && enabled ? rectOf(handle) : null
const rootBox = rootEl && enabled ? rectOf(rootEl) : null
const aspect = cellAspect(handleBox, cols, rows)
const syncLine = handle ? formatSyncLine(handle.getAttribute(attr), width, from, to) : null
useEffect(() => {
if (syncLine && onSyncLine) {
onSyncLine(syncLine, { handle: handle && handle.getAttribute(attr), width, from, to })
}
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [syncLine])
/** First click sets `from`, second sets `to`, third restarts. */
const choose = useCallback((id) => {
if (!from || to) { setFrom(id); setTo(null) } else if (id === from) setTo(null)
else setTo(id)
}, [from, to])
const applySquare = useCallback(() => {
if (!handleBox) return
const next = squareDivisions(handleBox, cols, rows)
setCols(next.cols)
setRows(next.rows)
}, [handleBox, cols, rows])
/* square once per newly-named element, so the grid STARTS square */
const squaredFor = useRef(null)
useEffect(() => {
if (!enabled || !handle) return
if (squaredFor.current === handle) return
squaredFor.current = handle
const next = squareDivisions(rectOf(handle), cols, rows)
setCols(next.cols)
setRows(next.rows)
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [enabled, handle])
if (!enabled || typeof document === 'undefined') return null
const band = bandFor(width, bands)
const untreated = bands.filter((b) => b !== band).map((b) => b.name).join(' · ')
const labelsUsable = showLabels && cols <= 16 && rows <= 16
const anyGrid = showHandle || (showPage && handle !== rootEl)
const layout = owner ? layoutOf(owner) : null
const handleSource = handle ? handle.getAttribute(sourceAttr) || 'local' : null
const ownerSource = owner ? owner.getAttribute(sourceAttr) || 'local' : null
const BAR = 46
const renderGrid = (box, kind) => {
const live = kind === 'handle'
const cells = []
for (let r = 0; r < rows; r += 1) {
for (let c = 0; c < cols; c += 1) {
const id = cellLabel(c, r)
const picked = id === to ? 0.4 : id === from ? 0.22 : 0
cells.push(
)
}
}
return (