@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/DashboardCanvas/DashboardCanvas.module.scss

@@ -0,0 +1,360 @@
+@use './DashboardCanvas.tokens' as tokens;
+@use '../../styles/mixins' as *;
+@use '../_internal/collapse' as bp;
+
+// Root stacks its own children — the top-level container grid, then one band
+// per section, top to bottom. This is the component's own internal
+// composition (Stack/Cluster precedent), not layout imposed on a parent.
+// ALWAYS a size container (unconditional, unlike Grid's opt-in
+// `collapseBelow`) — the below-breakpoint single-column stack (bottom of
+// this file) depends on it. NAMED, because each grid also sits inside an
+// unnamed `.sizer` container (square cells, below): the stack step rules
+// must keep querying the CANVAS width, and a bare `@container` would
+// resolve against the nearer sizer instead. See DashboardCanvas.tsx's JSDoc
+// ❌ anti-pattern paragraph for the intrinsic-sizing caveat this carries.
+.canvas {
+  // Relative only as the anchor for the internal drag ghost (Rule 4's
+  // sanctioned internal-child-anchor use).
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: var(--dashboard-canvas-gap);
+  container: dashboard-canvas / inline-size;
+}
+
+// Square-cell measuring box around every container grid (top level and each
+// section body). `cqw` in `--dashboard-canvas-row` must equal the GRID's own
+// width — an element can't resolve cq units against itself, and the canvas
+// root is wrong for section bodies (Accordion.Content's padding shrinks
+// them) — so each grid gets this zero-styling wrapper as its nearest size
+// container.
+.sizer {
+  container-type: inline-size;
+}
+
+// Edit-mode drag surfaces: whole item bodies and section headers start drags,
+// so the browser must not claim their touch gestures (Sortable precedent).
+// Narrow width disables editing exactly like readOnly (DashboardCanvas.tsx's
+// `editingEnabled` gate) — excluded here too so the cursor doesn't lie.
+.canvas:not([data-readonly], [data-narrow]) .item {
+  touch-action: none;
+  cursor: grab;
+}
+
+// Edit-mode snap grid (#356): dots on BOTH cell-edge lattices per axis —
+// cell STARTS (k·pitch) and cell ENDS ((k+1)·pitch − gap) — so all four
+// corners of a snapped widget land exactly on dots. Horizontal pitch is
+// fr-based — a column's outer edge repeats every (100% + gap) / N (N
+// columns, N-1 gaps between them: container width = N·colWidth + (N-1)·gap,
+// and colWidth + gap is exactly that expression / N). Vertical pitch is the
+// row unit + gap. One tile therefore holds FOUR dots (start/end × both
+// axes), and the whole field is shifted by −gap/2 (background-position) so
+// every dot center sits half a gap inside its tile — full circles, never
+// clipped on tile seams (`circle at 0 0` used to quarter-clip every dot).
+// Within a tile, cell start = gap/2 and cell end = 100% − gap/2.
+@function dc-dot($x, $y) {
+  @return radial-gradient(
+    circle at #{$x} #{$y},
+    var(--dashboard-canvas-dot-color) var(--dashboard-canvas-dot-size),
+    transparent var(--dashboard-canvas-dot-size)
+  );
+}
+
+.canvas:not([data-readonly], [data-narrow]) .container {
+  $start: calc(var(--dashboard-canvas-gap) / 2);
+  $end: calc(100% - var(--dashboard-canvas-gap) / 2);
+
+  background-image:
+    dc-dot($start, $start), dc-dot($end, $start), dc-dot($start, $end), dc-dot($end, $end);
+  background-position: calc(var(--dashboard-canvas-gap) / -2) calc(var(--dashboard-canvas-gap) / -2);
+  background-size: calc((100% + var(--dashboard-canvas-gap)) / var(--dc-cols, 24))
+    calc(var(--dc-row-unit) + var(--dashboard-canvas-gap));
+}
+
+.canvas[data-dragging] {
+  cursor: grabbing;
+  user-select: none;
+}
+
+// #696: while a move-drag is active, pad the hovered drop-target container by
+// the dragged item's height so there is always room to drop below the last
+// row. Only that container: padding every one would shift the bands below it
+// out from under the pointer. The padding is
+// h x (row + gap), one gap more than the item's own height. The dot
+// background paints on the padding box, so the strip stays dotted.
+.canvas[data-dragging]:not([data-readonly], [data-narrow]) .container[data-dc-drop-target] {
+  padding-block-end: calc(
+    var(--dc-trailing-rows, 0) * (var(--dc-row-unit) + var(--dashboard-canvas-gap))
+  );
+}
+
+// One container grid — used for both the top-level items and each section's
+// body. `--dc-cols` is stamped inline on the canvas root (24 by default) and
+// inherits down. Below-breakpoint re-templating to a single column: see the
+// `@container dashboard-canvas` step blocks at the bottom of this file.
+// `--dc-row-unit` (private): the resolved row unit — the consumer-overridable
+// `--dashboard-canvas-row` token when set, else the SQUARE default: one
+// column's width, i.e. the grid's own width (100cqw via the `.sizer`
+// wrapper) minus the (N-1) gaps, split into N columns. Declared HERE, not in
+// tokens.scss's :root, because var() substitution happens at the declaring
+// element and `--dc-cols` only exists inside a canvas.
+.container {
+  --dc-row-unit: var(
+    --dashboard-canvas-row,
+    calc((100cqw - (var(--dc-cols, 24) - 1) * var(--dashboard-canvas-gap)) / var(--dc-cols, 24))
+  );
+
+  display: grid;
+  grid-template-columns: repeat(var(--dc-cols, 24), minmax(0, 1fr));
+  grid-auto-rows: var(--dc-row-unit);
+  gap: var(--dashboard-canvas-gap);
+}
+
+// #353: an EMPTY container has no rows, so its rect collapses to zero height
+// and the pointer hit-test can never land in it — an empty, expanded body
+// keeps droppable height while editing is on: one row unit, floored at
+// --space-12 (a square row shrinks with width; ~18px is too thin a target
+// and too short for the drop-hint text). Any pointer y in the strip
+// resolves to some cell and the engine compacts the drop to y 0. `[inert]`
+// excludes collapsed section bodies (never drop targets, and their Accordion
+// collapse must still animate to zero); the readOnly/narrow gate matches the
+// other edit-only affordances, so view mode shows no blank strips.
+// `position: relative` is the internal anchor for `.dropHint` (Rule 4's
+// sanctioned use), which fills the whole strip independent of row geometry.
+.canvas:not([data-readonly], [data-narrow]) .container[data-dc-empty]:not([inert]) {
+  position: relative;
+  min-height: max(var(--dc-row-unit), var(--space-12));
+}
+
+// #353 drop affordance: rendered by DashboardCanvasSection inside an empty
+// body only while a move (drag or keyboard pick) is in flight.
+.dropHint {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: var(--border-width) dashed var(--dashboard-canvas-drop-preview-border);
+  border-radius: var(--radius-md);
+  color: var(--dashboard-canvas-handle-fg);
+  font-size: var(--font-size-sm);
+}
+
+// Item placement — the value is resolved in DashboardCanvasItem.tsx and
+// injected as inline custom properties (Grid.Item precedent: per-cell
+// placement is this layout family's own prop, not consumer layout). The cell
+// itself is a bare positioned box (#344) — no background/border/radius/
+// shadow of its own; that's whatever `renderItem` returns (typically a
+// `<Card>`). Only gesture-state affordances below get their own chrome.
+.item {
+  // stylelint-disable-next-line property-disallowed-list -- DashboardCanvasItem's sanctioned job: per-cell grid placement (Grid.Item precedent), not consumer layout (Rule 4 exemption)
+  grid-column: var(--dc-col, auto);
+  // stylelint-disable-next-line property-disallowed-list -- see grid-column comment above
+  grid-row: var(--dc-row, auto);
+  position: relative; // anchor for the internal resize handles
+  overflow: auto;
+}
+
+// The dragged item's cell renders the snapped drop preview — the ghost
+// carries the content, so the cell shows only the highlighted slot. Its own
+// full border (the idle `.item` has none to inherit from).
+.item[data-dc-drop-preview] {
+  background: var(--dashboard-canvas-drop-preview-bg);
+  border: var(--border-width) dashed var(--dashboard-canvas-drop-preview-border);
+
+  > * {
+    visibility: hidden;
+  }
+}
+
+.item[data-dc-resizing] {
+  border: var(--border-width) solid var(--dashboard-canvas-drop-preview-border);
+}
+
+// Keyboard editing: the cell itself is the focusable editing surface.
+// Inset so the ring stays inside the cell's own bounds — with no
+// background/border of its own to sit against, an outer ring would visually
+// bleed into the grid gap and read as belonging to the neighboring cell.
+// `.item` is also `overflow: auto`, so an outset ring would be clipped by the
+// cell itself on top of that.
+// What the inset band covers (the mixin's own requirement at an inset call
+// site): the outermost 2px of the cell. Base `.item` has no border there, so
+// normally nothing. While `[data-dc-picked]` or `[data-dc-resizing]` is set the
+// cell carries a 1px `--dashboard-canvas-drop-preview-border`, and a picked
+// cell IS the focused one — so the ring paints over that border for the
+// duration of a keyboard move. Acceptable: the ring is the stronger of the two
+// markers and the picked state is also carried by `--dashboard-canvas-item-
+// shadow-dragging`, which sits outside the band.
+.item:focus-visible {
+  @include focus-ring(var(--color-accent), $offset: calc(-1 * var(--ring-offset)));
+}
+
+// A keyboard-picked item travels with the engine preview — mark it like an
+// armed drag (content stays visible; there is no ghost on the keyboard path).
+.item[data-dc-picked] {
+  border: var(--border-width) solid var(--dashboard-canvas-drop-preview-border);
+  box-shadow: var(--dashboard-canvas-item-shadow-dragging);
+}
+
+// Cursor-following drag ghost: the moved item's content at its original px
+// size, translated per pointermove in canvas-relative coordinates. No
+// background/border of its own — the content it carries (`renderItem`'s
+// output) supplies that; the shadow is the "lifted, mid-drag" cue.
+.ghost {
+  position: absolute;
+  top: 0;
+  left: 0;
+  overflow: hidden;
+  pointer-events: none;
+  opacity: var(--dashboard-canvas-ghost-opacity);
+  box-shadow: var(--dashboard-canvas-item-shadow-dragging);
+}
+
+// Resize handles — pointer-only edge/corner corridors (keyboard resize is
+// Task 4). 24px hit targets (WCAG 2.5.8, FlowCanvas token precedent); the
+// only visible affordance is the cursor plus the SE corner glyph on hover.
+.handleE,
+.handleS,
+.handleSE {
+  position: absolute;
+  touch-action: none;
+}
+
+.handleE {
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: var(--dashboard-canvas-handle-hit);
+  cursor: ew-resize;
+}
+
+.handleS {
+  right: 0;
+  bottom: 0;
+  left: 0;
+  height: var(--dashboard-canvas-handle-hit);
+  cursor: ns-resize;
+}
+
+.handleSE {
+  right: 0;
+  bottom: 0;
+  width: var(--dashboard-canvas-handle-hit);
+  height: var(--dashboard-canvas-handle-hit);
+  cursor: nwse-resize;
+}
+
+.handleSE::after {
+  content: '';
+  position: absolute;
+  right: var(--space-1);
+  bottom: var(--space-1);
+  width: var(--space-2);
+  height: var(--space-2);
+  border-right: var(--border-width-emphasis) solid var(--dashboard-canvas-handle-fg);
+  border-bottom: var(--border-width-emphasis) solid var(--dashboard-canvas-handle-fg);
+  border-bottom-right-radius: var(--radius-sm);
+  visibility: hidden;
+}
+
+.item:hover .handleSE::after {
+  visibility: visible;
+}
+
+// Live insertion indicator between section bands during a band-reorder drag.
+.bandIndicator {
+  height: var(--space-1);
+  border-radius: var(--radius-full);
+  background: var(--dashboard-canvas-drop-indicator);
+}
+
+// Section bands are `<Accordion>` Items now (#344) — header/chevron/panel
+// chrome + the open↔close animation come from Accordion's own CSS.
+
+// Band-reorder grip: a dedicated handle in the Trigger's `actions` slot
+// (DashboardCanvasSection's remarks explain why it can't just be "grab the
+// header" once the header IS the toggle button). It's the ONLY pointer
+// affordance for band reorder, so it gets the same 24px hit corridor as the
+// resize handles (WCAG 2.5.8) even though the glyph itself is smaller.
+// Pointer-only; not rendered at all in readOnly (no `:not([data-readonly])`
+// gate needed here — DashboardCanvasSection omits the element outright).
+.sectionDragHandle {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--dashboard-canvas-handle-hit);
+  height: var(--dashboard-canvas-handle-hit);
+  color: var(--dashboard-canvas-handle-fg);
+  touch-action: none;
+  cursor: grab;
+}
+
+// Keyboard instructions + live announcement region.
+.srOnly {
+  @include visually-hidden;
+}
+
+// --- below-breakpoint single-column stacking ---------------------------
+// Below the `stackBelow` breakpoint (`_internal/collapse.scss` constants —
+// kept in sync by hand with DashboardCanvas.tsx's STACK_GATE_PX, the same
+// JS/CSS pairing the editing gate uses), every container grid re-templates
+// to one column and each item spans the full row at its own height. One
+// step block per breakpoint, gated by the stamped `.stackXx` class (#318
+// per-breakpoint pattern). Queries are NAMED (`dashboard-canvas`): the
+// matched elements' nearest container is the unnamed `.sizer` (square
+// cells), and the stack must key off the canvas width, which is also what
+// the JS gate observes.
+// The row unit switches to the fixed stacked token: the square `cqw` unit
+// would collapse to ~1/24 of the width once items span the full row.
+// DOM order is ALREADY (container band order, y, x) —
+// DashboardCanvasItem.tsx's `sortByPosition`, load-bearing exactly for this
+// — so the correct (section, y, x) stack order falls out for free; no JS
+// re-render needed for the reflow itself, only for the editing gate
+// (DashboardCanvas.tsx's `isNarrow`/`editingEnabled`).
+// Specificity: the base `.item` rule above (`grid-column: var(--dc-col, auto);
+// grid-row: var(--dc-row, auto);`) is one class = (0,1,0). `.canvas.stackXx
+// .item` below is three classes = (0,3,0), which beats it unconditionally —
+// no reliance on this file's own source order surviving bundling (#318
+// precedent; same reasoning as Grid's `.collapsible.collapseXx` double
+// class). Same math for the `.container` rules.
+@mixin stacked-container {
+  grid-template-columns: repeat(1, minmax(0, 1fr));
+  grid-auto-rows: var(--dashboard-canvas-row-stacked);
+}
+
+@mixin stacked-item {
+  // stylelint-disable-next-line property-disallowed-list -- below-breakpoint override is DashboardCanvas's own placement mechanism, same sanction as the base .item rule above
+  grid-column: 1 / -1;
+  // stylelint-disable-next-line property-disallowed-list -- see grid-column comment above
+  grid-row: var(--dc-h-span, auto);
+}
+
+@container dashboard-canvas (max-width: #{bp.$collapse-sm}) {
+  .canvas.stackSm .container {
+    @include stacked-container;
+  }
+
+  .canvas.stackSm .item {
+    @include stacked-item;
+  }
+}
+
+@container dashboard-canvas (max-width: #{bp.$collapse-md}) {
+  .canvas.stackMd .container {
+    @include stacked-container;
+  }
+
+  .canvas.stackMd .item {
+    @include stacked-item;
+  }
+}
+
+@container dashboard-canvas (max-width: #{bp.$collapse-lg}) {
+  .canvas.stackLg .container {
+    @include stacked-container;
+  }
+
+  .canvas.stackLg .item {
+    @include stacked-item;
+  }
+}

package/src/components/DashboardCanvas/DashboardCanvas.tokens.scss

@@ -0,0 +1,48 @@
+// DashboardCanvas.tokens.scss — component-scoped tokens for <DashboardCanvas>.
+// Every token defaults to a primitive so the resolved values match the
+// global theme; consumers retheme by overriding these custom properties.
+:root {
+  // Grid geometry. `--dashboard-canvas-row` (the row unit) deliberately has
+  // NO :root default: its built-in default makes cells SQUARE by deriving
+  // one column's width from `--dc-cols` (stamped inline on the canvas root),
+  // and a var() inside a :root declaration would substitute AT :root — where
+  // `--dc-cols` doesn't exist — instead of at the grid. The square calc
+  // therefore lives on `.container` in DashboardCanvas.module.scss
+  // (`--dc-row-unit`), with `--dashboard-canvas-row` consulted first — override
+  // it anywhere (e.g. `--dashboard-canvas-row: 48px` at :root) for
+  // fixed-height, non-square rows.
+
+  // Row unit for the below-`stackBelow` single-column stack, where items
+  // span the full row and the square unit above would collapse to ~1/24 of
+  // the width. The pre-#350 fixed default ("~48px + gap", --space-12).
+  --dashboard-canvas-row-stacked: var(--space-12);
+  --dashboard-canvas-gap: var(--space-3);
+
+  // Items are chrome-less bare cells (#344) — background/border/radius/shadow
+  // belong to whatever `renderItem` returns (typically a `<Card>`), not the
+  // cell. Only gesture-state surfaces below are the canvas's own to style.
+
+  // Drag ghost + snapped drop-preview + resize/pick surfaces — the item's
+  // OWN chrome-less idle state carries none of these; they're gesture
+  // affordances, not idle chrome.
+  --dashboard-canvas-ghost-opacity: 0.6;
+  --dashboard-canvas-item-shadow-dragging: var(--shadow-lg);
+  --dashboard-canvas-drop-preview-bg: var(--color-accent-bg-subtle);
+  --dashboard-canvas-drop-preview-border: var(--color-accent);
+
+  // Resize handles: 24px pointer corridor (WCAG 2.5.8) + hover glyph color.
+  --dashboard-canvas-handle-hit: var(--space-6);
+  --dashboard-canvas-handle-fg: var(--color-fg-subtle);
+
+  // Band-reorder insertion indicator. The section grip handle reuses
+  // --dashboard-canvas-handle-fg above (same "drag affordance glyph" role).
+  --dashboard-canvas-drop-indicator: var(--color-accent);
+
+  // Edit-mode snap-grid dots (#344) — one dot per cell corner, hidden in
+  // readOnly/narrow (DashboardCanvas.module.scss's `:not([data-readonly],
+  // [data-narrow])` gate, same one the drag cursor uses). #354: 1px
+  // dots were invisible at 100% zoom, so the size is 1.5px; the color is the
+  // subtler-but-visible border-strong (fg-subtle was too loud).
+  --dashboard-canvas-dot-color: var(--color-border-strong);
+  --dashboard-canvas-dot-size: 1.5px;
+}