@kolkrabbi/kol-component 0.141.0 → 0.143.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.141.0",
+  "version": "0.143.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/ContentCard.jsx

@@ -58,9 +58,19 @@ const BOX = {
   /* typeface's card is a FIXED 500px tall specimen board, not a ratio — the
    * shipped item is `h-[500px]`, and a ratio re-crops the glyph at every
    * column width, which is the one thing a specimen must not do. */
-  /* REST COLOURS ONLY (TypefaceCardRestSkin, kol-website 2026-08-30): `border`
-   * and `bg` are showcase's, so a typeface card sits on the same rest skin as a
-   * work card. `layout`, `pad`, `height`, the RATIO, REVEAL_BG, MEDIA and every
+  /* REST COLOURS ONLY, TAKEN FROM THE ROW (TypefaceCardRestSkinFix, kol-website
+   * 2026-08-30). Filled surface, no outline — `ContentRow`'s showcase pair.
+   *
+   * 0.140.0 copied `BOX.showcase` from THIS map instead, because it is the
+   * entry sitting next to this one. That was wrong: `showcase`'s CARD is a
+   * `drawer` — outlined and unfilled — and the ask was to match the ROW, which
+   * is filled with no outline. Every /foundry grid card shipped as an outlined
+   * empty box, the opposite of the rows beside it.
+   *
+   * "Make the card look like the row" means READ THE ROW'S BOX. The two maps
+   * share variant names and not treatments.
+   *
+   * `layout`, `pad`, `height`, the RATIO, REVEAL_BG, MEDIA and every
    * hover treatment are untouched and deliberately different.
    *
    * NOT derived with a spread. The row's version of this ask was resolved that
@@ -68,7 +78,7 @@ const BOX = {
    * it is keyed by variant NAME — a second ticket to undo. `RATIO`, `REVEAL_BG`
    * and `MEDIA` here are separate name-keyed maps too; a spread cannot reach
    * them either. Two values, set by hand. */
-  showcaseCanvas: { layout: 'canvas', border: 'var(--kol-fg-04)', bg: null, pad: 'var(--kol-pad-card-lg)', height: 500 },
+  showcaseCanvas: { layout: 'canvas', border: 'transparent', bg: 'var(--kol-surface-secondary)', pad: 'var(--kol-pad-card-lg)', height: 500 },
 }
 
 /* HOVER is a bg STEP on the opaque tier, per 05-control-chrome.md's state model

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])
+}