@kolkrabbi/kol-component 0.186.0 → 0.188.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.186.0",
+  "version": "0.188.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/hooks/colorMath.js

@@ -104,6 +104,37 @@ export function harmonyColors(hue, harmony, { saturation = 100, lightness = 50 }
   return roleOffsets.map((off) => hslToHex(normHue(hue + off), saturation, lightness))
 }
 
+/**
+ * Re-hue an EXISTING palette to a harmony, preserving each slot's own
+ * saturation and lightness.
+ *
+ * `harmonyColors` builds every role at ONE flat S/L, which is right when a
+ * caller has no palette yet and wrong the moment it does: a Light slot and a
+ * Dark slot both come back at 50% lightness, so the palette flattens on the
+ * first drag of the wheel (kol-fxr, `editor-set-is-behind-its-source`
+ * 2026-09-03 — its own wheel emits a hue and re-hues slot by slot, so the
+ * package's `colors` payload was half-ignorable).
+ *
+ * A slot that is `locked`, empty, or has no hex is passed through untouched —
+ * locking a colour is the one instruction a re-hue must not overrule.
+ *
+ * @param {number} hue base hue, 0–360
+ * @param {string|object} harmony harmony id or object
+ * @param {Array<{hex?: string, locked?: boolean}|string|null>} slots the current palette, in role order
+ * @returns {Array} the same shape back, re-hued — strings stay strings, objects keep every other key
+ */
+export function reHueSlots(hue, harmony, slots = []) {
+  const { roleOffsets } = harmonyById(harmony)
+  return slots.map((slot, i) => {
+    const off = roleOffsets[i % roleOffsets.length]
+    const hex = typeof slot === 'string' ? slot : slot?.hex
+    if (!hex || (typeof slot === 'object' && slot?.locked)) return slot
+    const { s, l } = hexToHsl(hex)
+    const next = hslToHex(normHue(hue + off), s, l)
+    return typeof slot === 'string' ? next : { ...slot, hex: next }
+  })
+}
+
 /**
  * Deterministic role colors derived from a base hex (S/L taken from the hex).
  * Convenience wrapper over `harmonyColors` for callers holding a color, not

package/src/molecules/DocsToc.jsx

@@ -1,3 +1,4 @@
+import { useCallback, useEffect, useRef } from 'react'
 import useScrollSpy from '../hooks/useScrollSpy.js'
 
 /**
@@ -12,16 +13,101 @@ import useScrollSpy from '../hooks/useScrollSpy.js'
  * default, smooth-scroll, close a mobile drawer). Labels render verbatim —
  * casing is authored at the call site.
  *
+ * TWO RENDERS, ONE CONTRACT (`variant`, 2026-09-03 — `docstoc-rail-variant`,
+ * kol-client-olina, which built and ran it before filing):
+ *
+ * - **`list`** (default) — the docs-sidebar column. No existing call moves.
+ * - **`rail`** — a fisheye rail pinned to a page edge (Bederson, *Fisheye
+ *   Menus*, UIST 2000). One hairline per heading with its label beside it,
+ *   magnified under the pointer on a gaussian curve, with inert graduations
+ *   between the headings. It reads as a ruler and behaves as a dial.
+ *
+ * WHY THE RAIL IS NOT A STYLESHEET OVER THE LIST — three behaviours a CSS file
+ * over the flat render cannot express:
+ *
+ * 1. **The curve.** Each row's magnitude is `exp(-((focus − centre)/falloff)²)`,
+ *    written to the row as `--m`; every visual derives from it in CSS (scale,
+ *    opacity, rule width), so JS sets ONE number per row and the cascade does
+ *    the rest. Gaussian, not linear: linear leaves the pointer a visible cone
+ *    edge, this has none.
+ * 2. **The lens SNAPS.** It never rests between two marks — it locks to the
+ *    nearest graduation and holds across that mark's whole band, so travelling
+ *    the rail is a run of countable clicks rather than a smear that settles
+ *    nowhere. The filer's test, verbatim: *"think about a lock picking thief,
+ *    he counts the ticks right"*. Snapping to the labelled rows alone was tried
+ *    and rejected — seven coarse stops, and it throws the ruler away. **The
+ *    graduations are the clicks; the labels are where the numbers happen to be
+ *    printed.**
+ * 3. **The graduations.** `minors` inert ticks between each pair of headings,
+ *    carrying the same `--m` — which is what makes the movement read as a lens
+ *    rather than rows blinking, and gives the rail a scale that seven bare
+ *    strokes have none of. They are `aria-hidden`, not links, no tab stop: a
+ *    screen reader wants the headings, not the seventy-seven marks.
+ *
+ * TWO THINGS THAT BIT THE FILER, kept here so they do not bite twice.
+ * `transform` does nothing on a non-replaced INLINE element — the label is a
+ * `<span>` and its scale was silently ignored until `display:inline-block`
+ * (which is why `.kol-toc-label` sets it in the theme). And transitions are OFF
+ * while the pointer drives: the rail carries `data-live` on pointer-enter and
+ * the CSS drops every transition under it, because a 120ms ease on top of a
+ * continuous input lags the cursor and reads as sluggish. They come back on
+ * leave so the wave settles instead of snapping.
+ *
+ * Row centres are measured on ENTER and on resize, never per pointer-move, and
+ * `--m` is written inside one rAF straight to the DOM. Reading geometry in a
+ * move handler is what makes this pattern jank; so is re-rendering React seven
+ * times a frame to animate seven numbers.
+ *
+ * HEADING DISCOVERY STAYS THE CONSUMER'S. `toc` is the contract for both
+ * variants — reading `<section id>` and its `<h2>` out of the DOM is app
+ * knowledge and does not belong in the package.
+ *
  * @param {Array<{id: string, label: string}>} toc  headings to render + observe
+ * @param {'list'|'rail'} variant  render (default 'list' — the docs-sidebar column)
  * @param {Function} onNavigate  (event) => void — optional click handler on every link
  * @param {string}   rootMargin  IntersectionObserver rootMargin passed to the
  *                               spy. Default keeps the ported source's tighter
  *                               top band (useScrollSpy's own default is
  *                               '-30% 0px -60% 0px')
+ * @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 {'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')
+ * @param {string}   className   RAIL: extra classes on the nav — where a consumer puts its own breakpoint (olina hides it under `xl`, where the sidenav is the navigation)
  */
-export default function DocsToc({ toc, onNavigate, rootMargin = '-80px 0px -80% 0px', root = null }) {
+export default function DocsToc({
+  toc,
+  variant = 'list',
+  onNavigate,
+  rootMargin = '-80px 0px -80% 0px',
+  root = null,
+  minors = 10,
+  falloff = 14,
+  position = 'right',
+  minSections = 2,
+  ariaLabel = 'On this page',
+  className = '',
+}) {
   const activeId = useScrollSpy(toc.map((item) => item.id), { rootMargin, root })
 
+  if (variant === 'rail') {
+    return (
+      <TocRail
+        toc={toc}
+        activeId={activeId}
+        onNavigate={onNavigate}
+        minors={minors}
+        falloff={falloff}
+        position={position}
+        minSections={minSections}
+        ariaLabel={ariaLabel}
+        className={className}
+      />
+    )
+  }
+
   return (
     <nav>
       <ul className="shell-nav-items">
@@ -52,3 +138,114 @@ export default function DocsToc({ toc, onNavigate, rootMargin = '-80px 0px -80%
     </nav>
   )
 }
+
+/* TocRail — the fisheye render. A sibling component rather than a branch inside
+ * the default export, because it owns refs, three pointer handlers and an
+ * effect that the list has no use for; hooks that only ever run for one variant
+ * 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 }) {
+  const navRef = useRef(null)
+  const centresRef = useRef([])
+  const frameRef = useRef(0)
+
+  /* Row centres in viewport coords. Measured on enter and on resize — the rail
+   * is fixed and its rows do not move while the pointer is inside it. EVERY
+   * child is a detent: labels and graduations alike. */
+  const measure = useCallback(() => {
+    const nav = navRef.current
+    if (!nav) return
+    centresRef.current = [...nav.children].map((el) => {
+      const r = el.getBoundingClientRect()
+      return r.top + r.height / 2
+    })
+  }, [])
+
+  const paint = useCallback((y) => {
+    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. */
+    const marks = centresRef.current
+    const focus = y == null || !marks.length
+      ? null
+      : marks.reduce((best, c) => (Math.abs(c - y) < Math.abs(best - y) ? c : best), marks[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])
+
+  const onMove = useCallback((e) => {
+    /* Reduced motion: the curve is the animation, so there is nothing to damp —
+     * the lens simply does not run, and the theme's reduced-motion block gives
+     * every row its resting size. */
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return
+    const y = e.clientY
+    cancelAnimationFrame(frameRef.current)
+    frameRef.current = requestAnimationFrame(() => paint(y))
+  }, [paint])
+
+  const onLeave = useCallback(() => {
+    cancelAnimationFrame(frameRef.current)
+    frameRef.current = requestAnimationFrame(() => paint(null))
+  }, [paint])
+
+  useEffect(() => {
+    paint(null)
+    window.addEventListener('resize', measure)
+    return () => {
+      window.removeEventListener('resize', measure)
+      cancelAnimationFrame(frameRef.current)
+    }
+  }, [measure, paint, toc])
+
+  if (toc.length < minSections) return null
+
+  return (
+    <nav
+      ref={navRef}
+      aria-label={ariaLabel}
+      data-position={position}
+      onPointerEnter={(e) => { measure(); e.currentTarget.dataset.live = '' }}
+      onPointerMove={onMove}
+      onPointerLeave={(e) => { delete e.currentTarget.dataset.live; onLeave() }}
+      className={`kol-toc kol-toc--${position} ${className}`.trim()}
+    >
+      {toc.flatMap(({ id, label }, i) => {
+        const active = id === activeId
+        const row = (
+          <a
+            key={id}
+            href={`#${id}`}
+            onClick={onNavigate}
+            aria-current={active ? 'true' : undefined}
+            data-major=""
+            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>
+            <span aria-hidden="true" className="kol-toc-rule" />
+          </a>
+        )
+        /* No graduations after the last heading — a ruler ends on a mark. */
+        if (i === toc.length - 1) return [row]
+        return [row, ...Array.from({ length: minors }, (_, k) => (
+          <span key={`${id}-tick-${k}`} aria-hidden="true" className="kol-toc-row kol-toc-tick">
+            <span className="kol-toc-rule" />
+          </span>
+        ))]
+      })}
+    </nav>
+  )
+}

package/src/molecules/Dropdown.jsx

@@ -3,7 +3,7 @@ import { toneClass, TONE_VARS } from '../utilities/tone.js'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { MenuDropdownItem } from './MenuItem.jsx'
 import { PopoverPanel, usePopover } from '../utilities/Popover.jsx'
-import { indicatorSize } from '../hooks/glyphLadders.js'
+import { glyphSize, indicatorSize } from '../hooks/glyphLadders.js'
 
 /**
  * Dropdown — trigger IS button chrome (2026-07-08 chrome law).
@@ -77,6 +77,18 @@ const Dropdown = ({
    * while a row is hovered would otherwise leave the consumer previewing
    * forever. It never fires while closed — a closed dropdown has no rows. */
   onOptionHover,
+  /* ICON-ONLY TRIGGER — an icon name, or a pre-rendered node dropped in where
+   * the glyph goes. The trigger becomes the pinned square (`kol-btn-icon`) at
+   * the current size, with no label, no ghost widths and no caret; the panel
+   * still sizes to its own rows rather than the trigger. This is what a tool
+   * rail needs, and its absence is why kol-fxr's ToolPalette hand-rolls a
+   * trigger out of `PopoverPanel` + `usePopover` at a bespoke 36/22 instead of
+   * importing anything (`editor-set-is-behind-its-source`, 2026-09-03). */
+  iconOnly,
+  /* A mark drawn INSIDE the trigger box, over the glyph — the tool-palette
+   * corner fold is the case. Kept a slot rather than a boolean so the square
+   * has one implementation and the drawing stays the caller's. */
+  triggerAdornment,
   defaultOpen = false,
   className = ''
 }) => {
@@ -163,6 +175,12 @@ const Dropdown = ({
     `kol-btn-${resolvedSize}`,
     SIZE_TYPE[resolvedSize],
     'kol-dd-trigger',
+    /* ICON-ONLY: the pinned square from Button's own class, so a tool-rail
+     * dropdown is the same box as the icon button beside it at every rung
+     * (editor-set-is-behind-its-source, kol-fxr 2026-09-03 — its ToolPalette
+     * hand-rolls a trigger out of PopoverPanel + usePopover precisely because
+     * this mode did not exist). No label, no ghost widths, no caret. */
+    iconOnly && 'kol-btn-icon kol-dd-trigger--icon',
     isOpen && 'kol-dd-trigger--open',
     /* the dark chip on a washed plane; the panel continues it (ControlToneInverse, 2026-08-27) */
     toneClass(tone),
@@ -179,20 +197,33 @@ const Dropdown = ({
         aria-expanded={isOpen}
         data-state={isOpen ? 'open' : 'closed'}
       >
-        {/* every option's label rides along hidden so the trigger is as wide
-          * as its widest value — the panel matches the trigger's width, so
-          * trigger and list stay one piece at every selection */}
-        <span className="kol-dd-label">
-          <span>{currentOption?.label}</span>
-          {options.map((option) => (
-            <span key={option.value} className="kol-dd-ghost" aria-hidden="true">
-              {option.label}
+        {iconOnly ? (
+          /* the glyph comes from the SOLO ladder — an icon alone in a pinned
+           * square — never from a call-site number */
+          typeof iconOnly === 'string'
+            ? <Icon name={iconOnly} size={glyphSize(resolvedSize, true)} />
+            : iconOnly
+        ) : (
+          <>
+            {/* every option's label rides along hidden so the trigger is as wide
+              * as its widest value — the panel matches the trigger's width, so
+              * trigger and list stay one piece at every selection */}
+            <span className="kol-dd-label">
+              <span>{currentOption?.label}</span>
+              {options.map((option) => (
+                <span key={option.value} className="kol-dd-ghost" aria-hidden="true">
+                  {option.label}
+                </span>
+              ))}
             </span>
-          ))}
-        </span>
-        {/* chrome lives in .kol-dd-caret (trailing edge + open-state flip) —
-          * keyed off the trigger's data-state, no inline styles */}
-        <Icon name="chevron-down" size={indicatorSize(resolvedSize)} className="kol-dd-caret" />
+            {/* chrome lives in .kol-dd-caret (trailing edge + open-state flip) —
+              * keyed off the trigger's data-state, no inline styles */}
+            <Icon name="chevron-down" size={indicatorSize(resolvedSize)} className="kol-dd-caret" />
+          </>
+        )}
+        {/* a consumer's own trigger mark — the tool-palette corner fold rides
+            here so the square keeps ONE implementation */}
+        {triggerAdornment}
       </button>
 
       <PopoverPanel

package/src/molecules/PaletteHarmonyWheel.jsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from 'react'
-import { HARMONIES, harmonyById, harmonyColors, normHue } from '../hooks/colorMath.js'
+import { HARMONIES, harmonyById, harmonyColors, normHue, reHueSlots } from '../hooks/colorMath.js'
 
 /* taxonomy-ok: a pure-canvas hue + harmony picker in the SpectrumControls
  * color-picker family. It nests no KOL component — its only import is the
@@ -20,6 +20,16 @@ import { HARMONIES, harmonyById, harmonyColors, normHue } from '../hooks/colorMa
  * arrow keys. `colors` is one hex per role offset of the active harmony
  * (see colorMath.harmonyColors), matching the satellite markers 1:1.
  *
+ * PASS `slots` IF YOU ALREADY HAVE A PALETTE (2026-09-03,
+ * `editor-set-is-behind-its-source`). Without it, `colors` is built at ONE
+ * flat `saturation`/`lightness`, so a Light role and a Dark role both come
+ * back at 50% — the palette flattens on the first drag, and kol-fxr's editor
+ * had to ignore half the payload because its own wheel re-hues slot by slot.
+ * With `slots`, every entry keeps its own S/L and only its hue moves, and a
+ * `locked` or empty slot is passed through untouched. `onHueChange(hue)` is
+ * the same seam with no payload at all, for a caller that owns the derivation
+ * outright — which is what fxr's wheel emits.
+ *
  * The ring hues, marker outlines and handle halo are literal color math
  * (hsl / #FFFFFF / rgba) on purpose — a spectrum is not themeable, and the
  * markers sit on fully-saturated ring hues, not on the surface (same
@@ -31,7 +41,9 @@ import { HARMONIES, harmonyById, harmonyColors, normHue } from '../hooks/colorMa
  * @param {number}        saturation  base saturation for emitted colors, 0–100 (default 100)
  * @param {number}        lightness   base lightness for emitted colors, 0–100 (default 50)
  * @param {Array}         harmonies   injectable scheme table (default HARMONIES)
+ * @param {Array}         slots       the CURRENT palette in role order (`{hex, locked}` objects or plain hex strings). Given, `colors` re-hues these — each slot keeps its own S/L, locked and empty entries pass through — instead of generating flat ones
  * @param {Function}      onChange    ({ hue, colors }) => void
+ * @param {Function}      onHueChange (hue) => void — the payload-free seam, for a caller that derives its own colours
  */
 
 /* Marker outline — white for contrast against the fully-saturated ring hues
@@ -44,8 +56,10 @@ export default function PaletteHarmonyWheel({
   harmony = 'analogous',
   saturation = 100,
   lightness = 50,
+  slots,
   harmonies = HARMONIES,
   onChange,
+  onHueChange,
 }) {
   const canvasRef   = useRef(null)
   const draggingRef = useRef(false)
@@ -58,10 +72,18 @@ export default function PaletteHarmonyWheel({
   )
 
   /* Emit next hue + its harmony colors. Held in a ref so the pointer/key
-   * handlers stay stable while always seeing the latest props. */
+   * handlers stay stable while always seeing the latest props.
+   *
+   * With `slots`, the colours are the CALLER'S palette re-hued — each slot
+   * keeping its own saturation and lightness — rather than a fresh flat set.
+   * Both fire, so a caller can take the hue and ignore the colours. */
   emitRef.current = (nextHue) => {
     const h = normHue(nextHue)
-    onChange?.({ hue: h, colors: harmonyColors(h, active, { saturation, lightness }) })
+    const colors = slots?.length
+      ? reHueSlots(h, active, slots)
+      : harmonyColors(h, active, { saturation, lightness })
+    onChange?.({ hue: h, colors })
+    onHueChange?.(h)
   }
 
   const outerR = size / 2 - 8