@kolkrabbi/kol-component 0.317.6 → 0.318.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.317.6",
+  "version": "0.318.0",
   "description": "The core component library",
   "license": "MIT",
   "type": "module",

package/src/atoms/Button.jsx

@@ -12,7 +12,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *
  * @param {Object} props
  * @param {ReactNode} props.children - Button content
- * @param {'accent'|'danger'|'nav'|'tab'|'tab-filled'} props.variant - The intent; the GROUND is `tone`. `tab` is the tab chip (2026-10-02): quiet text at rest, a soft filled chip while `pressed`. `tab-filled` (2026-10-29) shows its chip at rest (oq-04), brighter on hover (oq-08) and brightest selected (oq-16). `primary · secondary · outline · ghost · grey · control` are deprecated aliases of tones (2026-10-01, on the retirement ledger): pass `tone` — `secondary` is `tone="inverted"`, `control` is `tone="ghost"`, the rest keep their name. Visual variant. UNSET (the default) inherits the tone of the nearest `kol-tone-*` wrapper, else renders primary; the five ground variants are aliases of `tone`. `danger` is the destructive treatment (--ui-error fill); `nav` is the chrome rung — transparent, oq-64 ink, one step brighter than `ghost`; `control` is an alias for `ghost` (legacy call-sites).
+ * @param {'accent'|'danger'|'nav'|'tab'|'tab-filled'} props.variant - The intent; the GROUND is `tone`. `tab` is the tab chip (2026-10-02): quiet text at rest, a soft filled chip while `pressed`. `tab-filled` (2026-10-29) shows its chip at rest (oq-04), brighter on hover (oq-08) and brightest selected (oq-16). `float` (2026-10-30, FloatingStyleAndSignInDemos — the floating style B) is the shape only: a 44 control (44×44 icon-only), an 18 radius; the ground stays the `tone`'s. A composed float component (AppFloatNav, AccountForm's box) passes it, a consumer never sets it by hand. `primary · secondary · outline · ghost · grey · control` are deprecated aliases of tones (2026-10-01, on the retirement ledger): pass `tone` — `secondary` is `tone="inverted"`, `control` is `tone="ghost"`, the rest keep their name. Visual variant. UNSET (the default) inherits the tone of the nearest `kol-tone-*` wrapper, else renders primary; the five ground variants are aliases of `tone`. `danger` is the destructive treatment (--ui-error fill); `nav` is the chrome rung — transparent, oq-64 ink, one step brighter than `ghost`; `control` is an alias for `ghost` (legacy call-sites).
  * @param {'xs'|'sm'|'md'|'lg'} props.size - Button size (default: 'md'); xs is the panel rung (ControlsXsRung, 2026-09-01) — kol-mono-8 in a 22px shell (20 icon-only), opt-in by prop
  * @param {string} props.iconLeft - Icon name to display on the left
  * @param {string} props.iconRight - Icon name to display on the right
@@ -93,7 +93,7 @@ const Button = ({
     warned.add(variant)
     console.warn(`Button: variant="${variant}" is deprecated — use tone="${VARIANT_TONE[variant]}"`)
   }
-  const KNOWN = ['primary', 'secondary', 'accent', 'outline', 'ghost', 'nav', 'tab', 'tab-filled', 'danger', 'grey']
+  const KNOWN = ['primary', 'secondary', 'accent', 'outline', 'ghost', 'nav', 'tab', 'tab-filled', 'danger', 'grey', 'float']
   const known = !resolvedVariant || KNOWN.includes(resolvedVariant)
   if (!known && import.meta.env.DEV) console.warn(`Button: unknown variant "${resolvedVariant}" — rendering the inherited tone (primary)`)
   const variantClass = resolvedVariant && known ? `kol-btn-${resolvedVariant}` : ''

package/src/atoms/Input.jsx

@@ -11,6 +11,8 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *   variant="outline"          — bordered, transparent bg — THE secondary
  *                                treatment (2026-07-08 chrome law: one
  *                                secondary, always subordinate to filled)
+ *   variant="float"            — the floating style B (2026-10-30): 44 tall, an 18 radius, on the page's ground
+ *                                (surface-primary) inside a float box; AccountForm's box passes it
  *   tone="inverse"             — the dark chip (`fg-ab-24`) for a washed plane
  *                                (ControlToneInverse, 2026-08-27); same prop on ViewToggle · Dropdown
  *   size="xs"                  — the panel rung (ControlsXsRung, 2026-09-01):

package/src/hooks/useScrollSpy.js

@@ -46,13 +46,24 @@ export default function useScrollSpy(ids, { rootMargin = '-30% 0px -60% 0px', ed
       }
     }
 
+    /* NESTED IDS (DocsToc `children`, 2026-10-30): a section that contains its
+     * entries intersects for as long as any of them does, so the innermost
+     * visible element wins, and when an entry leaves while its section is
+     * still in the band the section takes it back. Flat ids never contain one
+     * another, so both rules are inert for them. */
+    const live = new Set()
     const observer = new IntersectionObserver(
       (entries) => {
+        entries.forEach((e) => (e.isIntersecting ? live.add(e.target) : live.delete(e.target)))
         if (edgeLockRef.current) return
-        const visible = entries
-          .filter((e) => e.isIntersecting)
+        const hits = entries.filter((e) => e.isIntersecting)
+        const visible = hits
+          .filter((e) => !hits.some((o) => o !== e && e.target.contains(o.target)))
           .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top)
-        if (visible[0]) setActiveId(visible[0].target.id)
+        if (visible[0]) { setActiveId(visible[0].target.id); return }
+        const left = entries.find((e) => !e.isIntersecting)
+        const owner = left && [...live].find((el) => el.contains(left.target))
+        if (owner) setActiveId(owner.id)
       },
       { root: scroller ?? null, rootMargin, threshold: 0 },
     )

package/src/molecules/DocsToc.jsx

@@ -58,11 +58,22 @@ import useScrollSpy from '../hooks/useScrollSpy.js'
  * move handler is what makes this pattern jank; so is re-rendering React seven
  * times a frame to animate seven numbers.
  *
+ * SECTIONED RAIL (`children`, DocsTocRailChildren, kol-atlas 2026-10-30 — the
+ * type-scale page wanted each section's ticks to BE its styles). An entry may
+ * carry `children: [{ id, label }]`; under it the gap is one tick per child
+ * instead of `minors` inert graduations, so the rail's height follows the
+ * content. A child tick is today's graduation at rest — 3px, no label — but it
+ * is a real link (tab stop, not aria-hidden), its label appears only near the
+ * lens's peak (a steeper curve than the section labels, because at a 3px pitch
+ * the section curve would print five labels on top of one another), and the
+ * spy observes its id: the active child takes the active ink and its section
+ * stays lit as the parent. No `children`, no change.
+ *
  * 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 {Array<{id: string, label: string, children?: Array<{id: string, label: string}>}>} toc  headings to render + observe; RAIL: `children` are the section's entries, one tick each in place of `minors`
  * @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
@@ -92,13 +103,20 @@ export default function DocsToc({
   ariaLabel = 'On this page',
   className = '',
 }) {
-  const activeId = useScrollSpy(toc.map((item) => item.id), { rootMargin, root })
+  /* Children are observed too, in document order; the active SECTION is the
+   * active id itself or the entry that owns it. */
+  const activeId = useScrollSpy(
+    toc.flatMap((item) => [item.id, ...(item.children ?? []).map((c) => c.id)]),
+    { rootMargin, root },
+  )
+  const activeSection = toc.find((item) => item.id === activeId || item.children?.some((c) => c.id === activeId))?.id
 
   if (variant === 'rail') {
     return (
       <TocRail
         toc={toc}
         activeId={activeId}
+        activeSection={activeSection}
         onNavigate={onNavigate}
         minors={minors}
         falloff={falloff}
@@ -131,7 +149,7 @@ export default function DocsToc({
                * Layout, color, hover and focus live in `.shell-nav-item` now;
                * active is the shared `is-active` marker, not `text-emphasis`
                * typed at one call site. Matches RailRow exactly. */
-              className={`shell-nav-item kol-mono-14${activeId === item.id ? ' is-active' : ''}`}
+              className={`shell-nav-item kol-mono-14${activeSection === item.id ? ' is-active' : ''}`}
             >
               {item.label}
             </a>
@@ -148,7 +166,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, snap, position, minSections, ariaLabel, className }) {
+function TocRail({ toc, activeId, activeSection, onNavigate, minors, falloff, snap, position, minSections, ariaLabel, className }) {
   const navRef = useRef(null)
   const centresRef = useRef([])
   const frameRef = useRef(0)
@@ -182,13 +200,14 @@ function TocRail({ toc, activeId, onNavigate, minors, falloff, snap, position, m
      *   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. */
+     * The labelled marks are the rail's links — headings and, under a
+     * sectioned entry, its children — read off the DOM so the count no longer
+     * has to be every (minors + 1)th row. */
     const marks = centresRef.current
     const targets = snap === 'off'
       ? null
       : snap === 'label'
-        ? marks.filter((_, i) => i % (minors + 1) === 0)
+        ? marks.filter((_, i) => nav.children[i]?.tagName === 'A')
         : marks
     const focus = y == null
       ? null
@@ -200,7 +219,7 @@ function TocRail({ toc, activeId, onNavigate, minors, falloff, snap, position, m
       const m = focus == null ? 0 : Math.exp(-(((focus - c) / falloff) ** 2))
       nav.children[i]?.style.setProperty('--m', m.toFixed(3))
     })
-  }, [falloff, snap, minors])
+  }, [falloff, snap])
 
   const onMove = useCallback((e) => {
     /* Reduced motion: the curve is the animation, so there is nothing to damp —
@@ -238,8 +257,8 @@ function TocRail({ toc, activeId, onNavigate, minors, falloff, snap, position, m
       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
+      {toc.flatMap(({ id, label, children }, i) => {
+        const active = id === activeSection
         const row = (
           <a
             key={id}
@@ -275,6 +294,26 @@ function TocRail({ toc, activeId, onNavigate, minors, falloff, snap, position, m
             <span aria-hidden="true" className="kol-toc-rule" />
           </a>
         )
+        /* A sectioned entry's gap is its children, one tick each — a link with
+         * its label, not an inert graduation. */
+        if (children?.length) {
+          return [row, ...children.map((c) => {
+            const on = c.id === activeId
+            return (
+              <a
+                key={c.id}
+                href={`#${c.id}`}
+                onClick={onNavigate}
+                aria-current={on ? 'true' : undefined}
+                data-active={on ? '' : undefined}
+                className="kol-toc-row kol-toc-tick kol-toc-child"
+              >
+                <span className="kol-toc-label kol-helper-10 text-meta">{c.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) => (

package/src/molecules/TabsRow.jsx

@@ -4,6 +4,7 @@ import CloseButton from '../atoms/CloseButton.jsx'
 import Button from '../atoms/Button.jsx'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { RAIL_ROW } from '../hooks/railRow.js'
+import { Tooltip } from '../utilities/Popover.jsx'
 
 /* taxonomy-ok: nests kol-icons's Icon */
 
@@ -59,7 +60,8 @@ import { RAIL_ROW } from '../hooks/railRow.js'
  *                                 that component shoudl probablyget its own variant"*): the pill on a DESK — shown from md up, hidden
  *                                 below (the phone has its own nav), placed at the content's bottom-left, 64 in from the rail's edge
  *                                 (`--kol-shell-rail-width`) and 64 up, not centred
- * @param {boolean} [shadow=false]  a drop shadow — for a pill that floats over content (the transport), not the nav
+ * @param {boolean} [shadow=false]  the KOL float shadow (`--kol-shadow-float`) — for a pill that floats over content (the transport,
+ *                                 a nav over a clashing canvas). Every pill slot names itself on hover in the KOL `Tooltip`
  * @param {'fill'|'circle'} [active='fill']  the lit slot: `fill` its whole 56 slot (today), `circle` a 44×44 1:1 circle
  * @param {boolean} [foldable=false]  a sideways swipe (> 40px) folds the pill into a 28×72 edge tab; a tap restores it
  * @param {boolean} [folded] · {Function} [onFoldChange]  the folded state, controlled (else the pill holds it)
@@ -207,7 +209,8 @@ function StackedTabs({ tabs, value, onChange, placement, shape = 'bar', collapse
         background: 'var(--kol-surface-secondary)',
         /* without the hairline the 1px it took stays, transparent, so the slots never move */
         border: `1px solid ${border ? 'var(--kol-oq-08)' : 'transparent'}`,
-        boxShadow: shadow ? '0 8px 40px rgba(0, 0, 0, 0.45)' : undefined,
+        /* the KOL float shadow (kol-theme `--kol-shadow-float`, FloatingStyleAndSignInDemos 2026-10-30) — was a local 40px blur */
+        boxShadow: shadow ? 'var(--kol-shadow-float)' : undefined,
         transition: `width ${COLLAPSE_MS}ms ease`,
         ...swipeProps.style,
       } : phone ? {
@@ -224,7 +227,9 @@ function StackedTabs({ tabs, value, onChange, placement, shape = 'bar', collapse
       {tabs.map((t) => {
         const active = t.selected ?? t.id === value
         const circle = pill && activeShape === 'circle'
-        return (
+        /* THE NAME ON HOVER IS THE KOL TOOLTIP (AppFloatNav, kol-fxr 2026-10-30 — the Round 3 board), on the pill's far side
+         * from its edge; a thumb never hovers, so the phone is unchanged */
+        const slot = (
           <button
             key={t.id}
             type="button"
@@ -246,6 +251,7 @@ function StackedTabs({ tabs, value, onChange, placement, shape = 'bar', collapse
             {!phone && <span className="kol-helper-10 truncate max-w-full px-1">{t.label}</span>}
           </button>
         )
+        return pill ? <Tooltip key={t.id} label={t.label} placement={top ? 'bottom' : 'top'} offset={10} asChild>{slot}</Tooltip> : slot
       })}
       </div>
       {phone && (