@kolkrabbi/kol-component 0.165.0 → 0.166.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.165.0",
+  "version": "0.166.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/hooks/useGrabEdge.js

@@ -25,11 +25,26 @@ import gsap from 'gsap'
  * than that leaves the pill where it is, which is what stops it twitching.
  *
  * The element needs the `.kol-rail-grab` class for the drawing (kol-animation.css);
- * this hook only supplies `is-near` and `--kol-rail-grab-y`.
+ * this hook only supplies `is-near` and the travel variable.
+ *
+ * BOTH AXES (BrowsePageRulingsAndSeams, kol-r2b2 2026-09-02). A rail has one
+ * vertical edge; `ColumnBrowser` has a vertical handle per column AND a
+ * horizontal one along its foot, and the user's ruling is that they wear the
+ * same gesture. `axis` says which way the pill TRAVELS, and the near test is
+ * always the other one — a vertical line is approached across x, a horizontal
+ * line across y:
+ *
+ *   axis: 'y'  (default)  vertical edge  · near on x · travels on y · --kol-rail-grab-y
+ *   axis: 'x'             horizontal edge · near on y · travels on x · --kol-rail-grab-x
+ *
+ * The `-y` name is kept as it shipped rather than renamed to something
+ * axis-neutral: it is a published token the rail's CSS reads, and the pair
+ * `-x`/`-y` names two real axes rather than one concept twice.
  *
  * @param {React.RefObject<HTMLElement>} ref  the grab handle
+ * @param {{axis?: 'x'|'y'}} [options]  which way the pill travels (default 'y')
  */
-export default function useGrabEdge(ref) {
+export default function useGrabEdge(ref, { axis = 'y' } = {}) {
   useEffect(() => {
     let raf = 0
     const onMove = ({ clientX, clientY }) => {
@@ -39,16 +54,22 @@ export default function useGrabEdge(ref) {
         const h = ref.current
         if (!h) return
         const r = h.getBoundingClientRect()
-        const dist = Math.abs(clientX - (r.left + r.width / 2))
+        const vertical = axis === 'y'
+        /* the near test is ACROSS the line, the travel ALONG it */
+        const across = vertical ? clientX - (r.left + r.width / 2) : clientY - (r.top + r.height / 2)
+        const dist = Math.abs(across)
         const near = dist <= GRAB.near || (h.classList.contains('is-near') && dist <= GRAB.sleep)
         h.classList.toggle('is-near', near)
         if (!near) return
-        /* the travel band: bipolar from the middle, GRAB.range of the height */
-        const edge = (r.height * (1 - GRAB.range)) / 2
-        const along = Math.min(Math.max(clientY - r.top, edge), r.height - edge)
+        /* the travel band: bipolar from the middle, GRAB.range of the span */
+        const span = vertical ? r.height : r.width
+        const start = vertical ? r.top : r.left
+        const point = vertical ? clientY : clientX
+        const edge = (span * (1 - GRAB.range)) / 2
+        const along = Math.min(Math.max(point - start, edge), span - edge)
         if (h.dataset.grabSeeded && Math.abs(along - Number(h.dataset.grabTarget)) < GRAB.stick) return
         h.dataset.grabTarget = String(along)
-        const vars = { '--kol-rail-grab-y': `${along}px` }
+        const vars = { [vertical ? '--kol-rail-grab-y' : '--kol-rail-grab-x']: `${along}px` }
         /* the CSS fallback is 50%, a percentage — nothing to tween from, so the
          * first sighting sets and every move after tweens */
         if (h.dataset.grabSeeded) gsap.to(h, { ...vars, ...GRAB.travel, overwrite: 'auto' })
@@ -57,5 +78,5 @@ export default function useGrabEdge(ref) {
     }
     window.addEventListener('pointermove', onMove)
     return () => { window.removeEventListener('pointermove', onMove); cancelAnimationFrame(raf) }
-  }, [ref])
+  }, [ref, axis])
 }

package/src/organisms/ColumnBrowser.jsx

@@ -3,6 +3,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
 import KindPreview from '../molecules/KindPreview.jsx'
 import { formatLength } from '../molecules/AudioPreview.jsx'
 import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/mediaKinds.js'
+import useGrabEdge from '../hooks/useGrabEdge.js'
 
 /**
  * ColumnBrowser — Finder-style Miller columns over a flat key space (kol-r2b2's
@@ -24,17 +25,21 @@ import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/me
  * `window` (the overlay holds focus) and space closes — the opening keystroke
  * bubbles from here and is ignored.
  *
- * Rows wear the DS Table's cell metrics (12px 16px, mono 12, an oq-08 hairline
- * between rows, none after the last). Selected and cursor rows draw the HOVER
- * fill (`bg-fg-04`) — user ruling: "make hover state the selected state".
+ * Rows wear the DS Table's cell metrics (12px 16px, mono 12) with NO divider —
+ * the row is a rounded pill on a constant 4px inset, so selecting never shifts
+ * the layout (BrowsePageRulingsAndSeams, 2026-09-02). ONE fill on screen and it
+ * means selected: hover and the bare keyboard cursor paint nothing, the trail is
+ * `fg-02` and the deepest column holding a selection is `fg-04`.
  * Height defaults to 528px = 12 rows × 44px (user ruling); columns scroll. Both
  * the height and every column's width are DRAGGABLE, Finder-style
  * (ColumnBrowserResize, kol-r2b2 2026-08-27 — user: "column height drag yes and
  * individual column width drag" · "that should be a set in ds"): a strip along
  * the browser's bottom edge (`row-resize`) and one on each column's right edge
  * (`col-resize`, the border already there is the visual — the strip is the hit
- * area, invisible at rest, `fg-08` on hover / while dragging). Pointer events
- * with `setPointerCapture`, no library; native CSS `resize:` was rejected.
+ * area). Each strip carries the estate's GRAB PILL: hidden at rest, woken by
+ * pointer PROXIMITY (`useGrabEdge`, the rail's hook) and travelling along the
+ * line to meet the cursor. Pointer events with `setPointerCapture`, no library;
+ * native CSS `resize:` was rejected.
  *
  * The app-owned bits are SEAMS with working defaults: `urlOf(o)` (the preview
  * image — no URL, no image), `kindOf(o)` (image / video / audio / file from
@@ -193,12 +198,28 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview, width
 }
 
 /* one edge handle: captures the pointer, reports the delta along its axis;
- * `is-dragging` keeps the wash on while the pointer is captured */
+ * `is-dragging` keeps the pill lit while the pointer is captured.
+ *
+ * THE PILL FOLLOWS THE POINTER (BrowsePageRulingsAndSeams, kol-r2b2 2026-09-02,
+ * user ruling). It used to sit dead centre and wake on :hover — the theme's own
+ * comment said pointer-following "was built and rejected", while the SAME
+ * gesture had shipped on the rail's grab edge the same day and has run in
+ * kol-r2b2 since. `useGrabEdge` is that implementation; this is the second
+ * consumer of it, which is why the hook grew an `axis` rather than a fork.
+ *
+ * The handle's axis is named for what it RESIZES — `x` drags the column's width
+ * — and the pill on it travels the other way, down the vertical edge. So the
+ * `x` handle takes `axis: 'y'` and the `y` handle `axis: 'x'`: the hook's axis
+ * is the pill's travel, not the drag. Getting this pair backwards is the one
+ * easy mistake here. */
 function ResizeHandle({ axis, onDrag, onEnd }) {
   const [dragging, setDragging] = useState(false)
   const start = useRef(null)
+  const ref = useRef(null)
+  useGrabEdge(ref, { axis: axis === 'x' ? 'y' : 'x' })
   return (
     <div
+      ref={ref}
       className={`kol-column-browser-resize-${axis} ${dragging ? 'is-dragging' : ''}`.trim()}
       role="separator"
       aria-orientation={axis === 'x' ? 'vertical' : 'horizontal'}