@kolkrabbi/kol-component 0.187.0 → 0.189.0

package/package.json

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

@@ -41,8 +41,22 @@ import { usePopover, PopoverPanel } from '../utilities/Popover'
  *                     entry.value on a palette pick
  *   label           — row label (kol-helper-12); also prefixes aria-labels
  *   hideLabel       — suppress the visible label (aria keeps it)
- *   refs            — [{ value, label, hex }] pre-resolved palette entries →
- *                     popover mode
+ *   refs            — [{ value, label, hex? }] palette entries → popover mode.
+ *                     `hex` may be omitted when `resolveRef` is supplied
+ *   resolveRef      — (value) => hex — the RESOLVER SEAM. Without it, every
+ *                     entry must arrive pre-resolved and a `palette:accent`
+ *                     value cannot be shown at all: the swatch has no hex and
+ *                     the subtitle prints the raw ref. With it, a consumer
+ *                     keeps its own palette and this row renders live against
+ *                     it (editor-set-is-behind-its-source, kol-fxr 2026-09-03 —
+ *                     its ColorField takes `palette` and calls `resolveColor`)
+ *   autoValue       — the THEME state's value, typically a `var(--kol-*)`
+ *                     token that flips with light/dark. Set, the popover
+ *                     offers a Theme button; unset, it does not — a field with
+ *                     no auto value has no theme to fall back to
+ *   size            — control rung for the hex input, 'xs'|'sm'|'md'|'lg'
+ *                     (default 'sm'). A rail renders a dozen of these and the
+ *                     rung is the rail's decision, not each row's
  *   locked          — lock overlay pinned visible, aria-pressed on the swatch
  *   onToggleLock    — () => void — swatch click toggles the lock
  *   tokenName       — resolved token readout (kol-helper-10) → grid mode
@@ -58,6 +72,9 @@ export default function ColorInputRow({
   label,
   hideLabel = false,
   refs,
+  resolveRef,
+  autoValue,
+  size = 'sm',
   locked = false,
   onToggleLock,
   tokenName,
@@ -67,25 +84,52 @@ export default function ColorInputRow({
   className = '',
 }) {
   const hasRefs = Array.isArray(refs) && refs.length > 0
-  const isLockToggle = !hasRefs && typeof onToggleLock === 'function'
+  /* The popover carries the ref grid AND the quick states, so a field with no
+   * palette but an `autoValue` still gets one — that is the whole Theme/None
+   * affordance and it has nowhere else to live. */
+  const hasPopover = hasRefs || autoValue != null
+  const isLockToggle = !hasPopover && typeof onToggleLock === 'function'
   const isGrid = tokenName != null
   const labelVisible = label != null && !hideLabel
 
-  /* Display resolution: when the current value is a refs entry, the swatch and
-   * input show the entry's pre-resolved hex; otherwise value IS the hex. */
+  /* A value is one of FOUR kinds, and the row has to tell them apart before it
+   * can render anything: a literal hex, a palette REF the consumer resolves, a
+   * themed `var(--kol-*)` token that flips with light/dark, or null — None.
+   * The first port only understood the first and the last. */
+  const isVar = typeof value === 'string' && value.startsWith('var(')
+  const isNone = value == null
+
+  /* Display resolution: a refs entry shows its own hex, `resolveRef` resolves
+   * anything else the consumer owns (a `palette:` ref, a token), and a bare
+   * hex IS the value. `hex` on the entry still wins, so a pre-resolved list
+   * needs no resolver and nothing existing moves. */
+  const resolve = (v) => {
+    if (v == null) return null
+    const entry = hasRefs ? refs.find((r) => r.value === v) : undefined
+    return entry?.hex ?? resolveRef?.(v) ?? (typeof v === 'string' && v.startsWith('#') ? v : null)
+  }
   const activeRef = hasRefs ? refs.find((r) => r.value === value) : undefined
-  const displayHex = activeRef?.hex ?? value ?? null
-  const digits = (displayHex ?? '').replace(/^#/, '').toUpperCase()
-  const showTransparent = unused || displayHex == null
-  const subtitle = displayHex == null ? 'None' : (activeRef?.label ?? '#' + digits)
+  const displayHex = resolve(value)
+  /* A themed token renders LIVE in the swatch but has no meaningful hex to
+   * print, so the field shows its placeholder rather than a resolved literal
+   * the user cannot have typed. */
+  const digits = isVar || isNone ? '' : (displayHex ?? '').replace(/^#/, '').toUpperCase()
+  const showTransparent = unused || (isNone && !isVar)
+  const subtitle = isNone
+    ? 'None'
+    : isVar
+      ? 'Theme'
+      : (activeRef?.label ?? (displayHex ? '#' + digits : String(value)))
 
   const [open, setOpen] = useState(false)
   const popover = usePopover({ open, onOpenChange: setOpen, placement: 'bottom-start', offset: 4 })
 
-  const chip = (size) => (
+  const chip = (swatchSize) => (
     <ColorSwatch
-      hex={showTransparent ? null : displayHex}
-      size={size}
+      /* a themed token goes STRAIGHT to the swatch — `var(--kol-x)` is a live
+       * paint, and resolving it to a literal would freeze it out of the theme */
+      hex={showTransparent ? null : (isVar ? value : displayHex)}
+      size={swatchSize}
       showTransparent={showTransparent}
       transparentTone={transparentTone}
       hoverable={false}
@@ -95,7 +139,7 @@ export default function ColorInputRow({
   /* Swatch cell — popover trigger (refs), lock toggle (onToggleLock), or a
    * plain preview chip. The lock overlay is a SIBLING of the swatch: inside
    * it, ColorSwatch's overflow-hidden radius clip would cut the glyph off. */
-  const swatchCell = hasRefs ? (
+  const swatchCell = hasPopover ? (
     <button
       type="button"
       ref={popover.refs.setReference}
@@ -134,10 +178,11 @@ export default function ColorInputRow({
   const hexInput = (
     <Input
       variant="filled"
-      size="sm"
+      size={size}
       prefix="#"
       chars={6}
       maxLength={6}
+      placeholder={isVar ? 'auto' : '–'}
       value={digits}
       onChange={(e) => onChange?.('#' + e.target.value.replace(/^#/, '').toUpperCase())}
       disabled={disabled}
@@ -170,28 +215,63 @@ export default function ColorInputRow({
           {hexInput}
         </div>
       )}
-      {hasRefs && (
+      {hasPopover && (
         <PopoverPanel
           popover={popover}
           panel={false}
           focus={false}
-          className="bg-surface-secondary border border-fg-08 rounded p-2 shadow-lg"
+          className="bg-surface-secondary border border-fg-08 rounded p-2 flex flex-col gap-2 shadow-lg"
           style={{ minWidth: 200 }}
         >
-          <div className="grid grid-cols-6 gap-1">
-            {refs.map((entry) => (
+          {hasRefs && (
+            <div className="grid grid-cols-6 gap-1">
+              {refs.map((entry) => (
+                <ColorSwatch
+                  key={entry.value}
+                  hex={entry.hex ?? resolveRef?.(entry.value) ?? null}
+                  size="fill"
+                  selected={entry.value === value}
+                  title={entry.label}
+                  onClick={() => {
+                    onChange?.(entry.value)
+                    setOpen(false)
+                  }}
+                />
+              ))}
+            </div>
+          )}
+          {/* QUICK STATES. Theme (the auto value — a token that flips with
+              light/dark) is offered only where the field HAS one; None is
+              always available, because clearing a colour is not a palette
+              decision. Both were dropped in the first port, which is what left
+              `value == null` renderable but unreachable. */}
+          <div className="flex items-center gap-2">
+            {autoValue != null && (
+              <button
+                type="button"
+                onClick={() => { onChange?.(autoValue); setOpen(false) }}
+                aria-pressed={isVar}
+                className="flex items-center gap-1.5 kol-helper-12 text-fg-64 rounded px-1.5 h-6 border border-fg-08"
+              >
+                <ColorSwatch hex={resolve(autoValue) ?? autoValue} size={14} hoverable={false} />
+                Theme
+              </button>
+            )}
+            <button
+              type="button"
+              onClick={() => { onChange?.(null); setOpen(false) }}
+              aria-pressed={isNone}
+              className="flex items-center gap-1.5 kol-helper-12 text-fg-64 rounded px-1.5 h-6 border border-fg-08"
+            >
               <ColorSwatch
-                key={entry.value}
-                hex={entry.hex}
-                size="fill"
-                selected={entry.value === value}
-                title={entry.label}
-                onClick={() => {
-                  onChange?.(entry.value)
-                  setOpen(false)
-                }}
+                hex="#FFFFFF"
+                size={14}
+                showTransparent
+                transparentTone={transparentTone}
+                hoverable={false}
               />
-            ))}
+              None
+            </button>
           </div>
         </PopoverPanel>
       )}

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