50:I[314491,["/_next/static/immutable/chunks/3arlv5bvukoo2.js","/_next/static/immutable/chunks/39v64hmfyo-sr.js","/_next/static/immutable/chunks/2nvof3-29tvc3.js","/_next/static/immutable/chunks/3tjobt77z_9dj.js","/_next/static/immutable/chunks/04j_o97cgxn2x.js","/_next/static/immutable/chunks/3upr08c9vtj8w.js","/_next/static/immutable/chunks/1ww0328si-u8x.js","/_next/static/immutable/chunks/11mfl5ymqld9-.js","/_next/static/immutable/chunks/2xxcqy6ppds3l.js","/_next/static/immutable/chunks/3j06ow7w40nxu.js","/_next/static/immutable/chunks/31nn7jwsjvqii.js","/_next/static/immutable/chunks/43_s7jweyypoh.js","/_next/static/immutable/chunks/0p6vao205o1jc.js","/_next/static/immutable/chunks/1_kyvgkyokw92.js","/_next/static/immutable/chunks/1lo-zn37dolb5.js","/_next/static/immutable/chunks/1v8k6yxw1rg0u.js"],"FilesView"] 51:T4bb7,"use client"; /** * @author: @dorianbaffier * @description: Scroll Index * @version: 1.0.0 * @date: 2026-10-15 * @license: MIT * @website: https://kokonutui.com * @github: https://github.com/kokonut-labs/kokonutui */ import { type KeyboardEvent, type ReactNode, useEffect, useRef, useState, } from "react"; import { cn } from "@/lib/utils"; export interface ScrollIndexProps { /** The content to index. Defaults to a sample article. */ children?: ReactNode; /** Which headings get a tick. */ selector?: string; /** * `self`: the component scrolls its own box (default). * `window`: the page scrolls and the rail sticks beside the content. */ scroller?: "self" | "window"; className?: string; } interface Section { el: HTMLElement; text: string; level: number; /** Scroll position that brings the heading to the top. */ at: number; /** Where its tick sits on the rail, 0 to 1. */ pos: number; } // The rail is this tall at most, in px; ticks sit at the scroll position of // their heading, so long sections leave long gaps. const RAIL = 280; // Headings land this far below the top edge when jumped to. const OFFSET = 16; // Ticks swell near the pointer like a dock: peak width and reach, in px. const SWELL = 1.6; const REACH = 26; // A drag let go this close to a tick (after its momentum) settles on it. const SNAP = 18; // How long the flashed section name stays up after scrolling into it. const FLASH = 900; function easeInOut(t: number) { return t < 0.5 ? 8 * t ** 4 : 1 - (-2 * t + 2) ** 4 / 2; } export default function ScrollIndex({ children, selector = "h2, h3", scroller = "self", className, }: ScrollIndexProps) { const boxRef = useRef(null); const contentRef = useRef(null); const railRef = useRef(null); const headRef = useRef(null); const labelRef = useRef(null); const tickRefs = useRef<(HTMLButtonElement | null)[]>([]); const [sections, setSections] = useState< { text: string; level: number; pos: number }[] >([]); // The effect below reads and writes these without re-rendering. const api = useRef<{ jump: (index: number) => void; show: (i: number) => void; }>({ jump: () => undefined, show: () => undefined }); useEffect(() => { const box = boxRef.current; const content = contentRef.current; const rail = railRef.current; const head = headRef.current; const label = labelRef.current; if (!(box && content && rail && head && label)) { return; } const usesWindow = scroller === "window"; const reduceMotion = window.matchMedia( "(prefers-reduced-motion: reduce)" ).matches; let list: Section[] = []; let start = 0; let end = 1; let active = -1; let height = RAIL; let raf = 0; let tween = 0; let flashTimer = 0; let painted = false; let hover: number | null = null; let drag: { id: number; moved: boolean; y: number; t: number; v: number; } | null = null; const swell: number[] = []; const getScroll = () => (usesWindow ? window.scrollY : box.scrollTop); const setScroll = (value: number) => { if (usesWindow) { window.scrollTo(0, value); } else { box.scrollTop = value; } }; const measure = () => { const scroll = getScroll(); if (usesWindow) { const top = content.getBoundingClientRect().top + scroll; start = Math.max(top - OFFSET, 0); end = Math.max( top + content.offsetHeight - window.innerHeight, start + 1 ); } else { start = 0; end = Math.max(box.scrollHeight - box.clientHeight, 1); } const origin = usesWindow ? 0 : box.getBoundingClientRect().top - scroll; list = Array.from(content.querySelectorAll(selector)).map( (el) => { const at = Math.min( Math.max( el.getBoundingClientRect().top + scroll - origin - OFFSET, start ), end ); return { el, text: el.textContent?.trim() ?? "", level: Number(el.tagName.slice(1)) || 2, at, pos: (at - start) / (end - start), }; } ); height = rail.clientHeight || RAIL; setSections(list.map(({ text, level, pos }) => ({ text, level, pos }))); }; const fraction = () => Math.min(Math.max((getScroll() - start) / (end - start), 0), 1); const nearest = (y: number) => { let best = -1; let distance = Number.POSITIVE_INFINITY; list.forEach((s, i) => { const d = Math.abs(s.pos * height - y); if (d < distance) { distance = d; best = i; } }); return { index: best, distance }; }; const placeLabel = (index: number, visible: boolean) => { const section = list[index]; if (!section) { label.style.opacity = "0"; return; } if (label.textContent !== section.text) { label.textContent = section.text; } label.style.transform = `translate3d(0, ${(section.pos * height).toFixed(1)}px, 0) translateY(-50%)`; label.style.opacity = visible ? "1" : "0"; }; /** Section the reader is in: the last heading at or above the top. */ const current = () => { const scroll = getScroll() + 1; let index = -1; for (let i = 0; i < list.length; i++) { if (list[i].at <= scroll) { index = i; } } return index; }; const paint = () => { raf = 0; head.style.transform = `translate3d(0, ${(fraction() * height).toFixed(1)}px, 0)`; const now = current(); if (now !== active) { active = now; tickRefs.current.forEach((tick, i) => { if (tick) { tick.dataset.passed = i <= active ? "true" : "false"; } }); // Scrolling into a new section names it briefly. if (painted && hover === null && !drag && active >= 0) { placeLabel(active, true); window.clearTimeout(flashTimer); flashTimer = window.setTimeout(() => { if (hover === null && !drag) { label.style.opacity = "0"; } }, FLASH); } } // Ticks ease toward their swell, so the magnification follows the // pointer smoothly instead of jumping. let moving = false; tickRefs.current.forEach((tick, i) => { if (!tick) { return; } const y = (list[i]?.pos ?? 0) * height; const target = hover === null || reduceMotion ? 1 : 1 + SWELL * Math.exp(-((hover - y) ** 2) / (2 * REACH * REACH)); const value = (swell[i] ?? 1) + (target - (swell[i] ?? 1)) * 0.35; swell[i] = Math.abs(value - target) < 0.005 ? target : value; moving ||= swell[i] !== target; tick.style.setProperty("--swell", swell[i].toFixed(3)); }); painted = true; if (moving) { schedule(); } }; function schedule() { if (!raf) { raf = requestAnimationFrame(paint); } } const stopTween = () => { cancelAnimationFrame(tween); tween = 0; }; const scrollTo = (target: number) => { stopTween(); const from = getScroll(); const to = Math.min(Math.max(target, 0), usesWindow ? 1e9 : end); if (reduceMotion || Math.abs(to - from) < 2) { setScroll(to); return; } const duration = Math.min( Math.max(260 + Math.abs(to - from) * 0.12, 300), 650 ); const begin = performance.now(); const step = (now: number) => { const t = Math.min((now - begin) / duration, 1); setScroll(from + (to - from) * easeInOut(t)); tween = t < 1 ? requestAnimationFrame(step) : 0; }; tween = requestAnimationFrame(step); }; api.current = { jump: (index) => { const section = list[index]; if (section) { scrollTo(section.at); } }, show: (index) => { hover = (list[index]?.pos ?? 0) * height; placeLabel(index, true); schedule(); }, }; const railY = (event: PointerEvent) => Math.min( Math.max(event.clientY - rail.getBoundingClientRect().top, 0), height ); const scrub = (y: number) => setScroll(start + (y / height) * (end - start)); const onDown = (event: PointerEvent) => { if (drag || event.button !== 0) { return; } event.preventDefault(); rail.setPointerCapture(event.pointerId); stopTween(); const y = railY(event); drag = { id: event.pointerId, moved: false, y, t: event.timeStamp, v: 0 }; hover = y; rail.dataset.dragging = ""; placeLabel(nearest(y).index, true); schedule(); }; const onMove = (event: PointerEvent) => { const y = railY(event); if (drag && event.pointerId === drag.id) { const dt = Math.max(event.timeStamp - drag.t, 1); drag.v = drag.v * 0.4 + ((y - drag.y) / dt) * 0.6; drag.moved ||= Math.abs(y - drag.y) > 3; drag.y = y; drag.t = event.timeStamp; if (drag.moved) { // Dragging the rail scrubs the page under it. scrub(y); } } else if (event.pointerType !== "mouse") { return; } hover = y; placeLabel(nearest(y).index, true); schedule(); }; const onUp = (event: PointerEvent) => { if (!drag || event.pointerId !== drag.id) { return; } const { moved, y, v } = drag; drag = null; delete rail.dataset.dragging; if (event.pointerType !== "mouse") { hover = null; placeLabel(-1, false); } // Where the flick was heading, then the tick nearest that. const projected = moved ? y + v * 120 : y; const hit = nearest(projected); if (hit.index >= 0 && (!moved || hit.distance < SNAP)) { api.current.jump(hit.index); } schedule(); }; const onLeave = () => { if (drag) { return; } hover = null; placeLabel(-1, false); schedule(); }; const scrollTarget: HTMLElement | Window = usesWindow ? window : box; const onScroll = () => schedule(); // Any scroll input of the reader's own cancels a jump in progress. const onInput = () => stopTween(); measure(); paint(); const resize = new ResizeObserver(() => { measure(); schedule(); }); resize.observe(content); resize.observe(box); scrollTarget.addEventListener("scroll", onScroll, { passive: true }); scrollTarget.addEventListener("wheel", onInput, { passive: true }); scrollTarget.addEventListener("touchstart", onInput, { passive: true }); rail.addEventListener("pointerdown", onDown); rail.addEventListener("pointermove", onMove); rail.addEventListener("pointerup", onUp); rail.addEventListener("pointercancel", onUp); rail.addEventListener("pointerleave", onLeave); return () => { cancelAnimationFrame(raf); stopTween(); window.clearTimeout(flashTimer); resize.disconnect(); scrollTarget.removeEventListener("scroll", onScroll); scrollTarget.removeEventListener("wheel", onInput); scrollTarget.removeEventListener("touchstart", onInput); rail.removeEventListener("pointerdown", onDown); rail.removeEventListener("pointermove", onMove); rail.removeEventListener("pointerup", onUp); rail.removeEventListener("pointercancel", onUp); rail.removeEventListener("pointerleave", onLeave); }; }, [selector, scroller]); const onTickKey = (index: number, event: KeyboardEvent) => { if (event.key !== "ArrowDown" && event.key !== "ArrowUp") { return; } event.preventDefault(); const next = Math.min( Math.max(index + (event.key === "ArrowDown" ? 1 : -1), 0), sections.length - 1 ); tickRefs.current[next]?.focus(); }; const self = scroller === "self"; return (

{children ?? }

{sections.map((section, index) => ( ))} {/* Where the reader is, between ticks too. */}

); } function SampleArticle() { const p = "mt-3 text-[15px] text-zinc-600 leading-relaxed dark:text-zinc-400"; const h2 = "mt-12 font-semibold text-xl text-zinc-900 tracking-tight first:mt-0 dark:text-zinc-100"; const h3 = "mt-8 font-medium text-base text-zinc-900 dark:text-zinc-100"; return (

Field notes · 8 min read

Building a component library

A component library is a promise: that the next screen will be faster to build than the last, and that it will feel like the same product. These notes cover what we learned keeping that promise for two years.

Most of it is about saying no. Every prop is a decision someone else has to make, and every variant is a screen that drifts.

Principles

Three rules settled most arguments before they started. Write them down early, and point to them often.

Restraint

Ship the smallest component that solves the problem in front of you. A button with four sizes is easier to live with than one with nine, and nobody has ever asked for the fifth.

Motion with a purpose

Animation explains where something came from and where it went. Anything else is decoration, and decoration ages quickly. Keep interface motion under 300 ms and let people interrupt it.

Tokens

Tokens are the vocabulary. Color, type, spacing and radius live in one place, so a rebrand is a pull request rather than a quarter.

Color

Name colors by job, not by hue. A surface, a border and a muted label survive a palette change; a gray-150 never does.

Type

Two families and five sizes cover nearly everything. Line height is part of the size, never a separate choice.

Components

Build from the inside out: primitives first, then the pieces that compose them. A dialog is a portal, a focus trap and a surface before it is ever a confirmation box.

Keep the API close to the platform. If it behaves like a button, it is a button element, with every attribute a button takes.

Accessibility

Keyboard first. If a component can't be used without a mouse, it is not finished. Test with a screen reader before review, not after launch, and treat reduced motion as a real setting.

Shipping

Release small and often. A changelog people actually read is worth more than a migration guide nobody finds.

Every release gets a short note: what changed, why, and what to do about it, in that order.

What's next

Theming per product, a token pipeline that feeds design and code from the same file, and fewer components, not more.

Thanks for reading. Drag the rail on the right to move through these notes, or hover it to see where each section starts.

); } 4f:["$","div",null,{"className":"mt-3 flex min-h-0 min-w-0 flex-1 flex-col gap-3","children":[null,["$","$L50",null,{"files":[{"path":"/components/kokonutui/scroll-index.tsx","content":"$51","type":"registry:component","target":"components/kokonutui/scroll-index.tsx"}],"className":"h-[70svh] min-h-80"}]]}]