@kolkrabbi/kol-component 0.190.0 → 0.192.0

package/package.json

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

package/src/organisms/SectionSplit.jsx

@@ -1,4 +1,5 @@
 import SectionText from '../molecules/SectionText.jsx'
+import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
 import { FULL_BLEED } from './sectionBleed.js'
 import { surfaceClass } from '../utilities/sectionSurface.js'
 import useSectionTheme from '../hooks/useSectionTheme.js'
@@ -14,8 +15,19 @@ import { minHeightClass } from './sectionHeights.js'
  *   'right'  media on the right, text on the left — the default
  *   'left'   media first (the old `flip`)
  *   'center' ONE column: text centred, media below
+ *   'top'    ONE column: media ABOVE the text, both centred
+ *   'bottom' ONE column: text above, media below — the explicit name for what
+ *            `center` has always rendered, kept as its own value because
+ *            "centred" says where the column sits and nothing about the order
  * One anatomy, one prop — not a third component.
  *
+ * THE VERTICAL PAIR (section-split-vertical-align, kol-client-hrafn
+ * 2026-09-03). The filer asked what `center` renders when `media` is passed and
+ * could not tell from the source: it STACKS, text first, media below, capped at
+ * 640. So `bottom` already existed under a name that did not say so, and only
+ * `top` was missing. Both are values a page can name now, and `center` keeps
+ * its behaviour exactly, so no existing call moves.
+ *
  * `meta` and `actions` are mutually exclusive by intent (pick one); `actions`
  * is conventionally a row of KOL Buttons. The media column renders only when
  * `media` is passed, and `caption` gates both the gradient veil and the
@@ -59,7 +71,8 @@ import { minHeightClass } from './sectionHeights.js'
  *   than only in `fill`, because a prop that silently does nothing in the default form is a
  *   seam wired to nothing. Unset, each form keeps exactly what it did: `fill` centres,
  *   bounded follows `align` (centred when `align="center"`, else start).
- * @param {'right'|'left'|'center'} [align='right']  media side, or centred single column
+ * @param {'right'|'left'|'center'|'top'|'bottom'} [align='right']  media side, or a centred single column: `top` puts the media above the text, `center` and `bottom` below it
+ * @param {boolean|ReactNode} [placeholder=false]  what stands in when `media` is absent — `true` renders the DS `AssetPlaceholder` at the frame's ratio, a node renders itself. OFF by default: a text-only `SectionSplit` is a real and common call, and injecting a visible box into every one of them estate-wide is not a fix (section-split-vertical-align, kol-client-hrafn 2026-09-03, which asked for the placeholder and gets it opt-in)
  * @param {'full'|'80'|'60'|string} [height='60']  min-height on the family's ladder — full = 100dvh,
  *   80 = 70svh / 80vh, 60 = 50svh / 60vh (default), 40 = 35svh / 40vh; the columns stay vertically centred inside it
  * @param {ReactNode} caption      mono caption + gradient veil over the media
@@ -87,6 +100,7 @@ export default function SectionSplit({
   mediaHover = false,
   mediaClip = true,
   align = 'right',
+  placeholder = false,
   textAlign,
   fill = false,
   height = '60',
@@ -106,8 +120,13 @@ export default function SectionSplit({
     ? { backgroundImage: `url(${bgImage})`, backgroundSize: 'cover', backgroundPosition: 'center' }
     : undefined
   const bleed = fullBleed ? FULL_BLEED : ''
-  const centred = align === 'center'
-  const mediaFirst = align === 'left'
+  /* the three single-column forms — `center` and `bottom` are one layout under
+   * two names, `top` reverses the order */
+  const centred = align === 'center' || align === 'top' || align === 'bottom'
+  /* `order-*` and not DOM order: the grid is one column in every centred form
+   * and below 901px, and the order utilities are what lift the media above the
+   * text for `left` and `top` alike. */
+  const mediaFirst = align === 'left' || align === 'top'
   /* unset = each form's own prior behaviour, so nothing existing moves */
   const fillText = textAlign ?? 'center'
   const boundedText = textAlign ?? (centred ? 'center' : 'start')
@@ -206,7 +225,7 @@ export default function SectionSplit({
             </div>
           )}
         </SectionText>
-        {media && (
+        {(media || placeholder) && (
           /* height = the rung minus the padding; width follows the ratio and
            * caps at the column — the media takes its size from the section,
            * never gives it */
@@ -235,7 +254,9 @@ export default function SectionSplit({
             className={`kol-section-split-visual relative w-full max-w-full justify-self-center rounded-[var(--kol-radius-sm)] min-[901px]:h-[calc(var(--kol-section-h,60vh)_-_2*var(--kol-section-py,4rem))] ${mediaClip ? 'overflow-hidden' : ''} ${mediaHover ? 'is-hoverable' : ''} ${mediaFirst ? 'order-1' : ''} ${centred ? 'max-w-[640px]' : ''}`.replace(/\s+/g, ' ').trim()}
             style={{ aspectRatio: ratio }}
           >
-            {media}
+            {media ?? (placeholder === true
+              ? <AssetPlaceholder className="h-full w-full" />
+              : placeholder)}
             {caption && <div className="kol-section-split-visual-veil" aria-hidden="true" />}
             {caption && <span className="kol-section-split-visual-caption">{caption}</span>}
           </div>