@kolkrabbi/kol-component 0.190.0 → 0.191.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.190.0",
+  "version": "0.191.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/molecules/DocsToc.jsx

@@ -72,6 +72,7 @@ import useScrollSpy from '../hooks/useScrollSpy.js'
  * @param {Element}  root        IntersectionObserver root passed to the spy
  * @param {number}   minors      RAIL: graduations between one heading and the next — the dial's resolution, so literally how many clicks a heading is worth (default 10)
  * @param {number}   falloff     RAIL: the gaussian's sigma in px, measured against the TICK pitch not the label pitch — at 10 graduations of 3px a section spans ~52px, so 14 crosses four or five clicks. Widen it and the whole column swells together, which is a column getting bigger rather than a lens moving over it (default 14)
+ * @param {'tick'|'label'|'off'} snap  RAIL: what the lens locks to — `tick` (default) is the safecracker dial, locking to the nearest graduation and holding across its band; `label` locks to headings only, which is the ONLY sensible detent at `minors={0}`; `off` lets the lens follow the pointer continuously, which is the honest fisheye and reads better on a long rail with no graduations
  * @param {'left'|'right'} position  RAIL: which edge it pins to (default 'right')
  * @param {number}   minSections RAIL: render nothing under this many headings — an index of one is noise (default 2)
  * @param {string}   ariaLabel   RAIL: the nav's accessible name (default 'On this page')
@@ -85,6 +86,7 @@ export default function DocsToc({
   root = null,
   minors = 10,
   falloff = 14,
+  snap = 'tick',
   position = 'right',
   minSections = 2,
   ariaLabel = 'On this page',
@@ -100,6 +102,7 @@ export default function DocsToc({
         onNavigate={onNavigate}
         minors={minors}
         falloff={falloff}
+        snap={snap}
         position={position}
         minSections={minSections}
         ariaLabel={ariaLabel}
@@ -145,7 +148,7 @@ export default function DocsToc({
  * do not belong in the other's render path.
  *
  * The magnitudes go to the DOM as `--m`, never to state — see the header. */
-function TocRail({ toc, activeId, onNavigate, minors, falloff, position, minSections, ariaLabel, className }) {
+function TocRail({ toc, activeId, onNavigate, minors, falloff, snap, position, minSections, ariaLabel, className }) {
   const navRef = useRef(null)
   const centresRef = useRef([])
   const frameRef = useRef(0)
@@ -166,19 +169,38 @@ function TocRail({ toc, activeId, onNavigate, minors, falloff, position, minSect
     const nav = navRef.current
     if (!nav) return
 
-    /* DETENT, on EVERY graduation — the safecracker's dial. The lens locks to
-     * the nearest mark and holds across that mark's whole band, so dragging
-     * down the rail is a run of discrete clicks rather than a smear. */
+    /* THE DETENT. `tick` is the safecracker's dial — the lens locks to the
+     * nearest mark and holds across its whole band, so dragging down the rail
+     * is a run of discrete clicks rather than a smear. The three modes differ
+     * only in WHICH array is snapped against, which is why this is a prop and
+     * not three components (`docstoc-rail-tracking-and-snap-prop`, 2026-09-04):
+     *
+     *   tick   every graduation — the default, right for an index you aim with
+     *   label  the headings only — coarse at 10 minors, and the ONLY sensible
+     *          detent at `minors={0}`, which the component already allows: no
+     *          ticks plus a tick-snap is `label` by accident rather than choice
+     *   off    no snap at all — the honest fisheye, and better on a long rail
+     *          with many headings and no graduations
+     *
+     * Majors are every (minors + 1)th child, because the render interleaves
+     * one heading with `minors` ticks and stops after the last heading. */
     const marks = centresRef.current
-    const focus = y == null || !marks.length
+    const targets = snap === 'off'
       ? null
-      : marks.reduce((best, c) => (Math.abs(c - y) < Math.abs(best - y) ? c : best), marks[0])
+      : snap === 'label'
+        ? marks.filter((_, i) => i % (minors + 1) === 0)
+        : marks
+    const focus = y == null
+      ? null
+      : !targets?.length
+        ? y
+        : targets.reduce((best, c) => (Math.abs(c - y) < Math.abs(best - y) ? c : best), targets[0])
 
     marks.forEach((c, i) => {
       const m = focus == null ? 0 : Math.exp(-(((focus - c) / falloff) ** 2))
       nav.children[i]?.style.setProperty('--m', m.toFixed(3))
     })
-  }, [falloff])
+  }, [falloff, snap, minors])
 
   const onMove = useCallback((e) => {
     /* Reduced motion: the curve is the animation, so there is nothing to damp —
@@ -228,13 +250,28 @@ function TocRail({ toc, activeId, onNavigate, minors, falloff, position, minSect
             data-active={active ? '' : undefined}
             className="kol-toc-row"
           >
-            {/* ONE rail voice (validate:rails R1). The filer's fork ran
-              * `kol-helper-12`, which is a second row ramp inside a rail and
-              * exactly what that gate exists to stop — the rung is the rail's,
-              * and the fisheye scales FROM it rather than replacing it. If 14
-              * proves too heavy under the lens, that is a change to the rail
-              * law and belongs in the docs before it belongs here. */}
-            <span className="kol-toc-label kol-mono-14 text-meta">{label}</span>
+            {/* `kol-helper-12`, and it is the FAULT LINE that says so, not
+              * taste (01-foundations/03-typography: *"can this string ever
+              * wrap? No (structurally single-line) → helper"*). This label is
+              * `white-space: nowrap` — a graduation on a ruler, which is the
+              * helper family's own listed use.
+              *
+              * The line-height is the functional half. `kol-mono-14` carries
+              * 18px leading on a 14px label: 4px this string never uses, and
+              * THIS component measures its rows — `measure()` reads
+              * `getBoundingClientRect()` on every child to place the detents,
+              * so leading inflates each row box and moves the label's centre
+              * off its own tick. A ramp built for wrapping text is the wrong
+              * tool for a mark on a ruler.
+              *
+              * It shipped as `kol-mono-14` in 0.188.0 because validate:rails
+              * R1 tested the class PREFIX rather than the rung's purpose and I
+              * took the gate's word over the type law. The filer had specified
+              * helper-12 deliberately (user: *"its a bit big and tight and
+              * bold"*, and then *"I just dont get the point of me desiging for
+              * the design be ignored?!"*). R1 now carries the exemption with
+              * this reason — see `docstoc-rail-tracking-and-snap-prop`. */}
+            <span className="kol-toc-label kol-helper-12 text-meta">{label}</span>
             <span aria-hidden="true" className="kol-toc-rule" />
           </a>
         )