@kolkrabbi/kol-component 0.201.0 → 0.203.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.201.0",
+  "version": "0.203.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/index.js

@@ -130,6 +130,10 @@ export { default as TabsRow } from './molecules/TabsRow.jsx'
  * 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'
+/* The rulers and the guides, public since 2026-09-03 (rulers-and-guides-are-private):
+ * they measure the RENDERED rect, so they work over a CSS-zoomed stage with no
+ * PanZoomViewport anywhere — which is their second consumer on day one. */
+export { CanvasRuler, CanvasGuides, useFrameGeom, niceStep, ticksFor } 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

@@ -617,14 +617,13 @@ export function PanZoomViewport({
         {guides && setGuides && (
           <CanvasGuides
             containerRef={containerRef}
-            view={view}
             guides={guides}
             setGuides={setGuides}
             interactive={guidesInteractive && !spaceHeld}
           />
         )}
 
-        {showRulers && <CanvasRuler containerRef={containerRef} view={view} disabled={spaceHeld} />}
+        {showRulers && <CanvasRuler containerRef={containerRef} disabled={spaceHeld} />}
 
         {/* Zoom % + fps — matching chips. Zoom (click resets to 100% /
             centered) first, fps to its right, shown while `f` toggles it. */}
@@ -659,14 +658,14 @@ const RULER_STEPS = [1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 50
 
 /* Smallest 1-2-5 virtual step whose on-screen spacing clears `target` px, so
  * labels never crowd regardless of zoom. */
-function niceStep(pxPer, target = 80) {
+export function niceStep(pxPer, target = 80) {
   for (const s of RULER_STEPS) if (s * pxPer >= target) return s
   return RULER_STEPS[RULER_STEPS.length - 1]
 }
 
 /* Virtual ticks visible across [0, spanScreen], given where virtual-0 sits on
  * screen (originScreen) and the screen-px-per-virtual-px scale. */
-function ticksFor(originScreen, pxPer, spanScreen, step) {
+export function ticksFor(originScreen, pxPer, spanScreen, step) {
   const vMin = (0 - originScreen) / pxPer
   const vMax = (spanScreen - originScreen) / pxPer
   const first = Math.ceil(vMin / step) * step
@@ -675,6 +674,30 @@ function ticksFor(originScreen, pxPer, spanScreen, step) {
   return out
 }
 
+/**
+ * useFrameGeom — the geometry the rulers and the guides both read.
+ *
+ * PUBLIC SINCE 2026-09-03 (`rulers-and-guides-are-private`, kol-fxr), with
+ * `CanvasRuler`, `CanvasGuides`, `niceStep` and `ticksFor`. They were module
+ * -private inside `PanZoomViewport` and **they were never tied to it**: this
+ * hook locates `[data-canvas-frame]` and reads its `getBoundingClientRect()`
+ * against the container, so it measures the RENDERED RESULT and every
+ * transform is already folded in. The filer measured it rather than asserting
+ * it — CSS `zoom: 0.5` and `transform: scale(0.5)` on a 1920 element both
+ * report a 960 rect, so `pxPer` is identical and no branch is needed. A
+ * consumer with a CSS-zoomed stage and no pan-zoom viewport at all (a 1920×1080
+ * slide editor, its second consumer on day one) gets rulers by rendering these
+ * two layers over a container that holds a `[data-canvas-frame]`.
+ *
+ * `view` is GONE rather than generalised: it never entered the math, and the
+ * effect it keyed on already runs a rAF settle-loop that re-measures until the
+ * rect is stable for two frames, plus a `ResizeObserver` on the container. Any
+ * change is caught by the rect comparison whatever caused it.
+ *
+ * @param {React.RefObject<HTMLElement>} containerRef - The box the layers are positioned in; must contain a `[data-canvas-frame]`
+ * @param {number} [virtualWidth=CANVAS_VIRTUAL_W] - The frame's width in VIRTUAL px — what `pxPer` divides by, and the vertical guide clamp
+ * @returns {{left, top, pxPer, vh, cw, ch}|null} frame offsets, screen-px per virtual px, the frame's virtual height, the container's size
+ */
 /* Frame geometry inside the viewport — locates the tagged
  * `[data-canvas-frame]` and reads its on-screen rect (which already folds in
  * the letterbox, fit-scale, and the pan/zoom transform) relative to the
@@ -683,7 +706,7 @@ function ticksFor(originScreen, pxPer, spanScreen, step) {
  * horizontal guides). Re-measures on every `view` change and on container
  * resize. Shared by CanvasRuler and CanvasGuides so ruler labels and guide
  * lines can never disagree. */
-function useFrameGeom(containerRef, view) {
+export function useFrameGeom(containerRef, virtualWidth = CANVAS_VIRTUAL_W) {
   const [geom, setGeom] = useState(null)
 
   const measure = useCallback(() => {
@@ -693,7 +716,7 @@ function useFrameGeom(containerRef, view) {
     const crect = el.getBoundingClientRect()
     if (!frame || crect.width === 0) { setGeom(null); return }
     const frect = frame.getBoundingClientRect()
-    const pxPer = frect.width / CANVAS_VIRTUAL_W
+    const pxPer = frect.width / virtualWidth
     setGeom({
       left:  frect.left - crect.left,
       top:   frect.top  - crect.top,
@@ -702,7 +725,7 @@ function useFrameGeom(containerRef, view) {
       cw:    crect.width,
       ch:    crect.height,
     })
-  }, [containerRef])
+  }, [containerRef, virtualWidth])
 
   /* A zoom that ANIMATES its transform (a consumer's eased step-zoom) would
    * have a single measure read the pre-animation rect, and the labels would
@@ -730,7 +753,7 @@ function useFrameGeom(containerRef, view) {
     }
     raf = requestAnimationFrame(tick)
     return () => cancelAnimationFrame(raf)
-  }, [measure, view, containerRef])
+  }, [measure, containerRef])
 
   useEffect(() => {
     const el = containerRef.current
@@ -752,9 +775,16 @@ function useFrameGeom(containerRef, view) {
  * `kol:zoom-at`) — CanvasGuides owns the guide drag, and the positions live in
  * the consumer's state. Canvases without a guides layer no-op. `disabled`
  * (Space-held pan) lets the pointerdown bubble to the pan handler instead.
+ *
+ * The two layers do not import each other — that event is the whole seam, so a
+ * consumer may render either alone.
+ *
+ * @param {React.RefObject<HTMLElement>} containerRef - The positioned box the bars sit in
+ * @param {number} [virtualWidth=CANVAS_VIRTUAL_W] - The frame's virtual width, forwarded to `useFrameGeom`
+ * @param {boolean} [disabled=false] - Let a pointerdown bubble instead of starting a guide (a pan gesture is holding the surface)
  */
-function CanvasRuler({ containerRef, view, disabled = false }) {
-  const geom = useFrameGeom(containerRef, view)
+export function CanvasRuler({ containerRef, virtualWidth = CANVAS_VIRTUAL_W, disabled = false }) {
+  const geom = useFrameGeom(containerRef, virtualWidth)
 
   const startGuideDrag = (axis) => (e) => {
     if (disabled || e.button !== 0) return
@@ -863,9 +893,15 @@ function GuideLine({ axis, screenPos, interactive, onGrab }) {
  * Drags use window-level POINTER events — the ruler cancels its pointerdown,
  * which suppresses the whole compatibility mouse-event stream for the
  * interaction, so mousemove/mouseup would never fire.
+ *
+ * @param {React.RefObject<HTMLElement>} containerRef - The positioned box the lines span
+ * @param {number} [virtualWidth=CANVAS_VIRTUAL_W] - The frame's virtual width — also the vertical guides' clamp
+ * @param {{h: number[], v: number[]}} guides - Positions in VIRTUAL px; the consumer's state
+ * @param {Function} setGuides - Updater, called with the next `{h, v}`
+ * @param {boolean} interactive - Allow grab and create; false renders the lines inert
  */
-function CanvasGuides({ containerRef, view, guides, setGuides, interactive }) {
-  const geom = useFrameGeom(containerRef, view)
+export function CanvasGuides({ containerRef, virtualWidth = CANVAS_VIRTUAL_W, guides, setGuides, interactive }) {
+  const geom = useFrameGeom(containerRef, virtualWidth)
   /* Ref mirror so the drag listeners read fresh geometry without rebinding. */
   const geomRef = useRef(null)
   geomRef.current = geom
@@ -908,7 +944,7 @@ function CanvasGuides({ containerRef, view, guides, setGuides, interactive }) {
     const onUp = (e) => {
       const pos = posFrom(e)
       const { axis, index } = guideDrag
-      const max = axis === 'h' ? Math.round(geomRef.current?.vh ?? 0) : CANVAS_VIRTUAL_W
+      const max = axis === 'h' ? Math.round(geomRef.current?.vh ?? 0) : virtualWidth
       setGuides((g) => {
         const arr = [...g[axis]]
         if (pos < 0) {
@@ -928,7 +964,7 @@ function CanvasGuides({ containerRef, view, guides, setGuides, interactive }) {
       window.removeEventListener('pointermove', onMove)
       window.removeEventListener('pointerup', onUp)
     }
-  }, [guideDrag, toVirtual, setGuides])
+  }, [guideDrag, toVirtual, setGuides, virtualWidth])
 
   if (!geom || geom.pxPer <= 0) return null
   const screenFor = (axis, pos) =>