@kolkrabbi/kol-component 0.140.0 → 0.142.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.140.0",
+  "version": "0.142.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

@@ -152,6 +152,9 @@ export { parseFrontmatter } from './utilities/frontmatter.js'
 export { readCover } from './utilities/id3.js'
 export { kindOf, extOf, isSystemFile, KINDS, KIND_LABEL, DEFAULT_KINDS, isSegment, groupSegments, groupVariants, posterFor, partition } from './utilities/mediaKinds.js'
 export { nearestRatio, RATIOS } from './utilities/ratios.js'
+/* the grab gesture — shared so kol-shell's NavRail and kol-framework's
+ * useDragResize wear ONE implementation (OneGrabGestureBothRails, 2026-08-30) */
+export { default as useGrabEdge } from './utilities/useGrabEdge.js'
 export { default as markdownToHtml, inlineToHtml } from './utilities/markdownToHtml.js'
 export { default as RecordManager } from './organisms/RecordManager.jsx'
 export { default as SpectrumGrid } from './organisms/SpectrumGrid.jsx'

package/src/molecules/ContentRow.jsx

@@ -87,8 +87,16 @@ const BOX = {
                      * variant NAME — so the two boxes agreed on every number and still disagreed
                      * about the vertical spread. Deriving one box from another while a second map
                      * is keyed by name is the drift the derive was meant to end. */
-                    bg: 'var(--kol-surface-secondary)', frame: 'transparent', frameHover: 'var(--kol-fg-08)',
-                    hover: 'color-mix(in srgb, var(--kol-surface-on-primary) 1%, transparent)' },
+                    /* NO `hover` KEY (TypefaceRowHoverBg, kol-website 2026-08-30, the third
+                     * pass on this row). `showcase` has `frameHover` and no `hover` at all, so a
+                     * work row answers a pointer with a border step alone; this row also washed
+                     * its background and read as a different interaction from every other listing.
+                     *
+                     * The three passes are the lesson: the ask was "make it look like /work" and
+                     * each ticket named only the state someone had looked at — rest colours, then
+                     * the derive's collateral, then this. When a user says make X look like Y,
+                     * diff EVERY state: rest, hover, selected, focus. */
+                    bg: 'var(--kol-surface-secondary)', frame: 'transparent', frameHover: 'var(--kol-fg-08)' },
 }
 
 /* `default` → `file` (user 2026-08-29). The variant was named after being the

package/src/utilities/useGrabEdge.js

@@ -0,0 +1,61 @@
+import { useEffect } from 'react'
+import { GRAB } from './motion.js'
+import gsap from 'gsap'
+
+/**
+ * useGrabEdge — the proximity-wake grab pill, for ANY resizable edge.
+ *
+ * Lifted out of kol-shell's `NavRail` 2026-08-30 (OneGrabGestureBothRails,
+ * kol-fxr — user: *"why dont we use the grab animation and other sidenav
+ * settings to be consistent?"*). fxr's `/labs` renders two rails on one screen,
+ * the shell's on the left and a params rail on the right, and only the left one
+ * came alive as the cursor neared it. Two implementations of one gesture in two
+ * packages, and neither was consumer code, so no consumer could converge them.
+ *
+ * It lives in kol-component because that is the only package BOTH rails can
+ * reach: kol-shell dropped its kol-framework peer in 0.16.0, so shell cannot
+ * import framework's hook and framework cannot import shell's. `gsap` and the
+ * `GRAB` tuning constants were already here.
+ *
+ * WHAT IT DOES. Watches the pointer; within `GRAB.near` of the handle's centre
+ * line it adds `is-near` (hysteresis out at `GRAB.sleep`, so the pill does not
+ * flicker on the boundary) and travels the pill along the edge to meet the
+ * cursor — bipolar from the middle across `GRAB.range` of the height, so it
+ * never rides up under a logomark. `GRAB.stick` is the dwell: a move smaller
+ * 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`.
+ *
+ * @param {React.RefObject<HTMLElement>} ref  the grab handle
+ */
+export default function useGrabEdge(ref) {
+  useEffect(() => {
+    let raf = 0
+    const onMove = ({ clientX, clientY }) => {
+      if (raf) return
+      raf = requestAnimationFrame(() => {
+        raf = 0
+        const h = ref.current
+        if (!h) return
+        const r = h.getBoundingClientRect()
+        const dist = Math.abs(clientX - (r.left + r.width / 2))
+        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)
+        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` }
+        /* 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' })
+        else { gsap.set(h, vars); h.dataset.grabSeeded = '1' }
+      })
+    }
+    window.addEventListener('pointermove', onMove)
+    return () => { window.removeEventListener('pointermove', onMove); cancelAnimationFrame(raf) }
+  }, [ref])
+}