@kolkrabbi/kol-component 0.166.0 → 0.167.0

package/package.json

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

@@ -41,10 +41,33 @@ import gsap from 'gsap'
  * 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
- * @param {{axis?: 'x'|'y'}} [options]  which way the pill travels (default 'y')
+ * 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, { axis = 'y' } = {}) {
+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 }) => {
@@ -58,25 +81,25 @@ export default function useGrabEdge(ref, { 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)
+        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 span */
+        /* 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 - GRAB.range)) / 2
+        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)) < GRAB.stick) return
+        if (h.dataset.grabSeeded && Math.abs(along - Number(h.dataset.grabTarget)) < stick) return
         h.dataset.grabTarget = String(along)
         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, axis])
+  }, [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

@@ -4,6 +4,7 @@ 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
@@ -211,12 +212,17 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview, 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. */
+ * 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' })
+  useGrabEdge(ref, { axis: axis === 'x' ? 'y' : 'x', ...GRAB_COLUMN })
   return (
     <div
       ref={ref}

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 },
+}