@kolkrabbi/kol-component 0.184.0 → 0.185.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.184.0",
+  "version": "0.185.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",

package/src/atoms/SelectionOverlay.jsx

@@ -1,3 +1,6 @@
+import { useContext } from 'react'
+import { CanvasZoomContext } from '../hooks/canvasZoom.js'
+
 /* taxonomy-ok: presentational transform-chrome overlay. It nests no KOL
  * component (pure inline-styled squares + label), so by the letter of the
  * molecule test it reads as an atom — but the lobby spec places it as a
@@ -7,23 +10,40 @@
 /**
  * SelectionOverlay — pure transform chrome for a selected box.
  *
- * Renders a dashed outline, 8 named resize handles, and a `W × H` dimension
- * label, all positioned in the **same 1080-virtual coordinate space** the
- * target lives in (pairs with Canvas's scale layer — place it as a sibling of
- * the box inside the same scale layer). Each handle carries a
- * `data-handle="NW|N|NE|E|SE|S|SW|W"` attribute so a parent's pointer router
- * can start the right resize mode. No interaction logic of its own — the drag
- * math lives in the consumer, which reads `e.target.dataset.handle`.
+ * Renders a dashed outline, 8 named resize handles, a rotate handle and a
+ * `W × H` dimension label, all positioned in the **same 1080-virtual
+ * coordinate space** the target lives in (pairs with Canvas's scale layer —
+ * place it as a sibling of the box inside the same scale layer). Each handle
+ * carries a `data-handle="NW|N|NE|E|SE|S|SW|W|ROT"` attribute so a parent's
+ * pointer router can start the right drag mode. No interaction logic of its
+ * own — the drag math lives in the consumer, which reads
+ * `e.target.dataset.handle`.
  *
- * Ported from the brand editor with the `layer` model reduced to a flat `box`
+ * Ported from kol-fxr's editor with the `layer` model reduced to a flat `box`
  * (per lobby spec): renders nothing when there's no positional box.
  *
- * @param {{x:number,y:number,w:number,h:number}} box  virtual-coord position + size; null/x==null → renders nothing
+ * ZOOM COMPENSATION IS THE POINT (restored 2026-09-03,
+ * `editor-set-is-behind-its-source`). The chrome renders in virtual px INSIDE
+ * the canvas's zoomed transform, so every screen-constant dimension — handle
+ * size, outline width, the rotate handle's offset, the label — divides by the
+ * live zoom from `CanvasZoomContext`. The first port hardcoded `1px` / `10px`
+ * / `marginTop: 6`, so at 3× the handles drew 30px and the label ballooned;
+ * kol-fxr measured it and reverted the adoption. Outside a `PanZoomViewport`
+ * the context is 1 and every division is a no-op, so a static canvas is
+ * unaffected.
+ *
+ * The label also counter-SCALES rather than just re-sizing: `scale(1/zoom)`
+ * with a top-left origin keeps its padding, radius and letter-spacing
+ * screen-constant too, which a font-size alone does not.
+ *
+ * @param {{x:number,y:number,w:number,h:number,rotation?:number}} box  virtual-coord position + size; null/x==null → renders nothing. `rotation` in degrees turns the chrome with the box about its centre
  * @param {boolean}  showHandles  render the 8 resize handles (default true)
+ * @param {boolean}  showRotate   render the rotate handle (default: follows `showHandles`) — independent because a path hides the resize handles, node-edit owning their geometry, and still rotates
  * @param {boolean}  showLabel    render the `W × H` dimension label (default true)
- * @param {number}   handleSize   handle square size in virtual px (default 10)
+ * @param {number}   handleSize   handle square size in virtual px BEFORE zoom compensation (default 10)
  * @param {string}   accentColor  outline + handle + label color (default var(--kol-accent-primary))
  * @param {Function} labelFormatter (box) => string — dimension readout (default `${round(w)} × ${round(h)}`)
+ * @param {string}   rotateTitle  tooltip on the rotate handle (default 'Rotate')
  */
 const HANDLE_DIRS = [
   { dir: 'NW', cursor: 'nwse-resize', x: 0,    y: 0    },
@@ -36,17 +56,35 @@ const HANDLE_DIRS = [
   { dir: 'W',  cursor: 'ew-resize',   x: 0,    y: 0.5  },
 ]
 
+/* The rotate handle's float above the top edge, in virtual px before zoom
+ * compensation — fxr's number. */
+const ROTATE_OFFSET = 22
+
 export default function SelectionOverlay({
   box,
   showHandles = true,
+  showRotate,
   showLabel = true,
   handleSize = 10,
   accentColor = 'var(--kol-accent-primary)',
   labelFormatter = (b) => `${Math.round(b.w)} × ${Math.round(b.h)}`,
+  rotateTitle = 'Rotate',
 }) {
+  /* Chrome renders in virtual px inside the zoomed transform — divide by zoom
+   * so handles / outline / label stay screen-constant at any zoom. 1 outside a
+   * PanZoomViewport, which makes every division below a no-op. */
+  const zoom = useContext(CanvasZoomContext)
+
   if (!box || box.x == null) return null  /* no positional box → no chrome */
 
   const { x, y, w, h } = box
+  const size = handleSize / zoom
+  const hairline = 1 / zoom
+  const rotate = showRotate ?? showHandles
+  /* `rotation` may arrive as a BINDING OBJECT on an animated prop; chrome uses
+   * the base 0 rather than throwing on `${{…}}deg` — editing chrome over
+   * animated transforms is a consumer-side v1 limitation, and fxr's guard. */
+  const rot = typeof box.rotation === 'number' ? box.rotation : 0
 
   return (
     <div
@@ -54,6 +92,9 @@ export default function SelectionOverlay({
         position: 'absolute',
         left: x, top: y,
         width: w, height: h,
+        /* the chrome rotates WITH the box (centre origin) so the wireframe and
+         * the handles hug the actually-rendered box, not its unrotated slot */
+        transform: rot ? `rotate(${rot}deg)` : undefined,
         pointerEvents: 'none',
         zIndex: 100,
       }}
@@ -61,22 +102,43 @@ export default function SelectionOverlay({
       <div
         style={{
           position: 'absolute', inset: 0,
-          outline: `1px dashed ${accentColor}`,
+          outline: `${hairline}px dashed ${accentColor}`,
           outlineOffset: 0,
         }}
       />
+      {/* rotate handle — a circle floating above the top edge; a drag rotates
+        * the box about its centre. Independent of the resize handles: a path
+        * hides those (node-edit owns their geometry) and still rotates. */}
+      {rotate && (
+        <div
+          data-handle="ROT"
+          title={rotateTitle}
+          style={{
+            position: 'absolute',
+            left: `calc(50% - ${size / 2}px)`,
+            top: -(ROTATE_OFFSET / zoom),
+            width: size,
+            height: size,
+            borderRadius: '50%',
+            background: 'white',
+            border: `${hairline}px solid ${accentColor}`,
+            cursor: 'grab',
+            pointerEvents: 'auto',
+          }}
+        />
+      )}
       {showHandles && HANDLE_DIRS.map(({ dir, cursor, x: hx, y: hy }) => (
         <div
           key={dir}
           data-handle={dir}
           style={{
             position: 'absolute',
-            left:   `calc(${hx * 100}% - ${handleSize / 2}px)`,
-            top:    `calc(${hy * 100}% - ${handleSize / 2}px)`,
-            width:  handleSize,
-            height: handleSize,
+            left:   `calc(${hx * 100}% - ${size / 2}px)`,
+            top:    `calc(${hy * 100}% - ${size / 2}px)`,
+            width:  size,
+            height: size,
             background: 'white',
-            border: `1px solid ${accentColor}`,
+            border: `${hairline}px solid ${accentColor}`,
             cursor,
             pointerEvents: 'auto',
           }}
@@ -88,7 +150,11 @@ export default function SelectionOverlay({
             position: 'absolute',
             left: 0,
             top: '100%',
-            marginTop: 6,
+            marginTop: 6 / zoom,
+            /* counter-scale, not just a smaller font: padding, radius and
+             * tracking have to stay screen-constant too */
+            transform: `scale(${1 / zoom})`,
+            transformOrigin: 'top left',
             fontFamily: 'var(--kol-font-family-mono)',
             fontSize: 10,
             letterSpacing: '0.04em',

package/src/hooks/canvasZoom.js

@@ -0,0 +1,19 @@
+import { createContext } from 'react'
+
+/**
+ * CanvasZoomContext — the canvas viewport's live zoom factor.
+ *
+ * Lives in `src/hooks` rather than beside `Canvas` because BOTH tiers need it:
+ * the organism publishes it (`PanZoomViewport`) and the atoms consume it
+ * (`SelectionOverlay` divides every screen-constant dimension by it). An atom
+ * importing `../organisms/Canvas.jsx` is an upward import and the taxonomy
+ * gate is right to refuse it — so the shared value moves down to the tier
+ * neither side owns, the same reason `glyphLadders.js` sits here.
+ *
+ * Defaults to 1, so a consumer reads it unconditionally and a canvas without a
+ * pan-zoom viewport turns every `/ zoom` into a no-op.
+ *
+ * `@kolkrabbi/kol-component` exports it from the barrel as `CanvasZoomContext`,
+ * and `Canvas.jsx` re-exports it under the same name it always had.
+ */
+export const CanvasZoomContext = createContext(1)

package/src/index.js

@@ -111,7 +111,11 @@ export { default as TabsRow } from './molecules/TabsRow.jsx'
 /* monorepo sets (P6–P10) — organism members. Foundry members live in the
    standalone @kolkrabbi/kol-foundry package (with the type-specimen kit +
    live-font effects moved there 2026-07-09) — never re-exported here. */
-export { default as Canvas, CanvasFrame, PanViewport, CANVAS_VIRTUAL_W, DEFAULT_ASPECTS, CANVAS_DEFAULTS } from './organisms/Canvas.jsx'
+/* `CanvasZoomContext` and `PanZoomViewport` are the load-bearing pair for an
+ * editor: the viewport publishes the zoom, every piece of editing chrome reads
+ * it. Absent from this barrel until 0.185.0, which is why the first port of
+ * this set could not keep its chrome screen-constant. */
+export { default as Canvas, CanvasFrame, PanViewport, PanZoomViewport, CanvasZoomContext, useFps, CANVAS_VIRTUAL_W, DEFAULT_ASPECTS, CANVAS_DEFAULTS } from './organisms/Canvas.jsx'
 export { default as EditorShell } from './utilities/EditorShell.jsx'
 export { default as GalleryCarousel } from './organisms/GalleryCarousel.jsx'
 export { default as AsciiCursor } from './utilities/AsciiCursor.jsx'

package/src/organisms/Canvas.jsx

@@ -1,4 +1,5 @@
-import { createContext, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { CanvasZoomContext } from '../hooks/canvasZoom.js'
 
 /**
  * Canvas — the editor's aspect-ratio stage.
@@ -31,11 +32,13 @@ import { createContext, useCallback, useEffect, useLayoutEffect, useRef, useStat
  * pan-only viewport is not this component, it is a third of it.
  */
 
-/* Current viewport zoom factor — consumed by editing chrome (selection
- * handles, path nodes) to render at a screen-constant size by dividing their
- * virtual-px dimensions by the zoom. Defaults to 1 for canvases without a
- * PanZoomViewport, so a consumer can read it unconditionally. */
-export const CanvasZoomContext = createContext(1)
+/* The viewport's live zoom factor — editing chrome divides its virtual-px
+ * dimensions by it to stay screen-constant. Defined in `hooks/canvasZoom.js`
+ * because the atoms consume it and an atom may not import an organism (the
+ * taxonomy gate, correctly); re-exported here under the name it has always
+ * had, so `import { CanvasZoomContext } from '@kolkrabbi/kol-component'` and
+ * every existing deep import keep working. */
+export { CanvasZoomContext }
 
 /* Fixed virtual canvas width — children render in this pixel space and the
  * outer rect scales to fit the viewport via CSS transform. Height is derived