@kolkrabbi/kol-component 0.165.0 → 0.167.0

package/package.json

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

@@ -47,7 +47,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *                                confirm only fires once it resolves
  * @param {string}   href         renders an <a> instead of a <button>
  * @param {number}   hold         ms to hold the confirm state (default 2000)
- * @param {string}   size         sm | md | lg — the pinned square (28/32/36)
+ * @param {string}   size         xs | sm | md | lg — the pinned square (22/26/32/40)
  *                                and its SOLO glyph (16/20/24) move together,
  *                                resolved from hooks/glyphLadders.js. This was
  *                                a raw px number and defaulted to 16 in a 32px

package/src/atoms/IconFrame.jsx

@@ -28,7 +28,7 @@ import { toneClass } from '../utilities/tone.js'
  * no per-theme props.
  *
  * `size` moves the square and the glyph together on the solo-glyph ladder
- * (16/20/24 against the pinned squares 28/32/36) — that pairing is the DEFAULT,
+ * (16/20/24 against the pinned squares 22/26/32/40) — that pairing is the DEFAULT,
  * and it is what every call site should take. `iconSize` unbinds the glyph for
  * the cases the ladder cannot serve, exactly as it does on `Button` and `Input`:
  * a `radius="full"` frame reads heavier than the square it was tuned against (a

package/src/atoms/SegmentedToggle.jsx

@@ -37,7 +37,7 @@
  *               'tonal' (filled tiles, but the clicked cell marks itself by
  *               TONE — surface-tertiary fill, no ring; 2026-08-12).
  *               Every variant renders at the SAME pinned button-ladder
- *               height (26/32/40) — icon or text, the box never moves.
+ *               height (22/26/32/40) — icon or text, the box never moves.
  *   size      — mirrors Button exactly: 'sm' (26px, mono-12, 4/12 pad) |
  *               'md' (default, 32px, mono-14, 6/16 pad) | 'lg' (40px,
  *               mono-16, 8/20 pad). Same cell padding + mono type as the

package/src/hooks/glyphLadders.js

@@ -7,12 +7,12 @@
  *
  * The ladders split on ONE question: is there a label beside the glyph?
  *
- *   SOLO      an icon alone in a pinned square (28/32/36) — takes the room
+ *   SOLO      an icon alone in a pinned square (22/26/32/40) — takes the room
  *   ADJACENT  an icon inside a rung's line box, beside a label
  *
  * Stated in the DS before this file existed — ThemeToggle.jsx:40 ("solo
  * 16/20/24, the pinned-square pairing") and IconFrame.jsx ("the solo-glyph
- * ladder against the pinned squares 28/32/36"). This file is where they stop
+ * ladder against the pinned squares"). This file is where they stop
  * being transcribed.
  *
  * Why it exists: the same two ladders were re-typed in four places
@@ -23,7 +23,7 @@
  * carrying a label) and nothing connected the two.
  */
 
-/** Icon alone in a pinned square. Pairs with squares 28 · 32 · 36. */
+/** Icon alone in a pinned square. Pairs with squares 22 · 26 · 32 · 40. */
 export const SOLO = { xs: 12, sm: 16, md: 20, lg: 24 }
 
 /** Icon beside a label, inside the rung's line box. */

package/src/hooks/useGrabEdge.js

@@ -25,11 +25,49 @@ 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.
+ *
+ * TUNING IS PER-EDGE (BrowsePageRulingsAndSeams, 2026-09-02 — user: *"its a bit
+ * different, its not like the sidenav"*). The rail's dwell-and-throw is its own
+ * ruling, not a house constant every edge inherits: `ColumnBrowser`'s handles
+ * were ruled on their own feel in kol-r2b2 — a longer chase and a much smaller
+ * retarget threshold, so the pill tracks the pointer closely instead of landing
+ * and holding. `GRAB` stays the default, so the rail does not move.
  *
  * @param {React.RefObject<HTMLElement>} ref  the grab handle
+ * EVERY tuning key the constants carry is an option, so a whole set spreads in
+ * (`useGrabEdge(ref, { axis, ...GRAB_COLUMN })`) with nothing silently dropped
+ * — a key the hook did not read would be a seam wired to nothing.
+ *
+ * @param {{axis?: 'x'|'y', near?: number, sleep?: number, travel?: object, stick?: number, range?: number}} [options]
+ *        `axis` — which way the pill travels (default 'y').
+ *        `near` / `sleep` — wake and sleep distance from the line, the hysteresis pair.
+ *        `travel` — the gsap chase (default `GRAB.travel`).
+ *        `stick` — px the pointer must move before the pill re-targets (default `GRAB.stick`).
+ *        `range` — the travel band as a fraction of the edge (default `GRAB.range`).
  */
-export default function useGrabEdge(ref) {
+export default function useGrabEdge(ref, {
+  axis = 'y',
+  near: nearAt = GRAB.near,
+  sleep = GRAB.sleep,
+  travel = GRAB.travel,
+  stick = GRAB.stick,
+  range = GRAB.range,
+} = {}) {
   useEffect(() => {
     let raf = 0
     const onMove = ({ clientX, clientY }) => {
@@ -39,23 +77,29 @@ 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 near = dist <= GRAB.near || (h.classList.contains('is-near') && dist <= GRAB.sleep)
+        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 <= nearAt || (h.classList.contains('is-near') && dist <= 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
+        /* the travel band: bipolar from the middle, `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 - range)) / 2
+        const along = Math.min(Math.max(point - start, edge), span - edge)
+        if (h.dataset.grabSeeded && Math.abs(along - Number(h.dataset.grabTarget)) < 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' })
+        if (h.dataset.grabSeeded) gsap.to(h, { ...vars, ...travel, overwrite: 'auto' })
         else { gsap.set(h, vars); h.dataset.grabSeeded = '1' }
       })
     }
     window.addEventListener('pointermove', onMove)
     return () => { window.removeEventListener('pointermove', onMove); cancelAnimationFrame(raf) }
-  }, [ref])
+  }, [ref, axis, nearAt, sleep, travel, stick, range])
 }

package/src/molecules/SearchInput.jsx

@@ -103,7 +103,7 @@ export default function SearchInput({
     if (expanding && isOpen) inputRef.current?.focus()
   }, [expanding, isOpen])
 
-  /* the pinned squares, 05-control-chrome.md — sm 28 · md 32 · lg 36 */
+  /* the pinned squares, 01-foundations/09-sizes.md — 22 · 26 · 32 · 40 */
   const square = { sm: 28, md: 32, lg: 36 }[size] ?? 32
   /* THE OPEN FIELD'S HEIGHT IS ITS OWN KNOB, defaulting to the square.
    *
@@ -154,7 +154,7 @@ export default function SearchInput({
            collapsed pill rendered as a filled circle next to a bare glyph and
            the pair looked like two different kinds of control. */
         /* THE SQUARE FOLLOWS THE LADDER, and it follows `size` like every other
-           control: sm 28 · md 32 · lg 36 (hooks/glyphLadders.js). This was a
+           control: 22 · 26 · 32 · 40 (01-foundations/09-sizes.md). This was a
            hardcoded 36 — the LG square — so an expanding search sat beside a
            `kol-btn-md` filter button at two different sizes. */
         className={`kol-expand flex items-center rounded-full ${isOpen ? (toneClass(tone) ? 'kol-tone-sunken' : 'bg-fg-04') : ''} ${className}`.trim()}

package/src/molecules/ShellDrawer.jsx

@@ -198,18 +198,17 @@ export default function ShellDrawer({
             </button>
           )}
           {header != null && <div className="min-w-0 flex-1">{header}</div>}
-          {/* The box has an owner (2026-08-01). This hand-wrote the icon-button
-            * square and its hover wash; `Button variant="nav"` IS that string.
-            * `iconSize` holds the glyph where it was — the ladder's md rung is
-            * heavier than a drawer close wants, and Button documents iconSize
-            * for exactly the cases the ladder cannot serve. The SQUARE is what
-            * needed an owner, and it now has one. */}
+          {/* A NORMAL ICON BUTTON (user 2026-09-02: *"it should just be like a
+            * normal button with a close icon, its not new?"*). It carried
+            * `iconSize={14}` — kept in 2026-08-01 to preserve the glyph size the
+            * hand-rolled button before it happened to have — so the box sat at
+            * the md rung's 32px around a glyph six under it, and it read as an
+            * oversized empty square. No override: the rung sets both. */}
           {closeSide !== 'start' && (
             <Button
               variant="nav"
               size="md"
               iconOnly="x"
-              iconSize={14}
               onClick={onClose}
               aria-label="Close"
               className="ml-auto shrink-0"

package/src/organisms/ColumnBrowser.jsx

@@ -3,6 +3,8 @@ 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'
+import { GRAB_COLUMN } from '../utilities/motion.js'
 
 /**
  * ColumnBrowser — Finder-style Miller columns over a flat key space (kol-r2b2's
@@ -24,17 +26,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 +199,33 @@ 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.
+ *
+ * `GRAB_COLUMN`, not the rail's `GRAB` (user 2026-09-02: *"its not like the
+ * sidenav. the handles are different from the sidenav"*) — a 2.8s chase and a
+ * 30px retarget, so the pill tracks the pointer instead of landing and holding
+ * on the rail's 90px dwell. */
 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', ...GRAB_COLUMN })
   return (
     <div
+      ref={ref}
       className={`kol-column-browser-resize-${axis} ${dragging ? 'is-dragging' : ''}`.trim()}
       role="separator"
       aria-orientation={axis === 'x' ? 'vertical' : 'horizontal'}

package/src/utilities/motion.js

@@ -86,3 +86,29 @@ export const GRAB = {
   snap: { duration: 0.5, ease: EASE.outGsap },
   slop: 3,
 }
+
+/* THE COLUMN BROWSER'S HANDLES ARE NOT THE RAIL'S (BrowsePageRulingsAndSeams,
+ * kol-r2b2 2026-09-02 — user: *"its a bit different, its not like the sidenav.
+ * the handles are different from the sidenav"*). Same gesture, its own feel,
+ * ruled in kol-r2b2 and running there since 2026-08-28:
+ *
+ *   travel   2.8s, not 1.1 — a long, unhurried chase
+ *   stick    30px, not 90 — a much smaller retarget threshold, so the pill
+ *            TRACKS the pointer down the edge instead of landing and holding.
+ *            The dwell that fixed the rail's four-mark grid is not what these
+ *            want; the deadband exists only so a slow drag does not nudge the
+ *            target every frame — and it is measured against the last TARGET,
+ *            not the animated value, because mid-flight the live value is still
+ *            travelling.
+ *   range    1 — no bipolar band. The rail chokes its travel so the pill never
+ *            rides up beside the logomark; there is nothing at these edges to
+ *            avoid, and the CSS `clamp()` at 2.25rem already stops it flush.
+ *
+ * `near` / `sleep` are shared — proximity is proximity. The FADE curve differs
+ * too and lives with the rule (kol-theme's kol-components-molecules.css). */
+export const GRAB_COLUMN = {
+  ...GRAB,
+  stick: 30,
+  range: 1,
+  travel: { duration: 2.8, ease: EASE.outGsap },
+}