@kolkrabbi/kol-component 0.21.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.21.0",
+  "version": "0.24.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,7 @@
     "@floating-ui/react": "^0.27.19",
     "embla-carousel-react": "^8.6.0",
     "react-syntax-highlighter": "^16.1.1",
-    "@kolkrabbi/kol-icons": "0.8.11"
+    "@kolkrabbi/kol-icons": "0.10.0"
   },
   "peerDependencies": {
     "framer-motion": "^12.0.0",

package/src/atoms/Button.jsx

@@ -11,7 +11,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *
  * @param {Object} props
  * @param {ReactNode} props.children - Button content
- * @param {'primary'|'secondary'|'accent'|'outline'|'ghost'|'danger'|'grey'|'control'} props.variant - Visual variant. `danger` is the destructive treatment (--ui-error fill); `control` is an alias for `ghost` (legacy call-sites).
+ * @param {'primary'|'secondary'|'accent'|'outline'|'ghost'|'nav'|'danger'|'grey'|'control'} props.variant - Visual variant. `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 {'sm'|'md'|'lg'} props.size - Button size (default: 'md')
  * @param {string} props.iconLeft - Icon name to display on the left
  * @param {string} props.iconRight - Icon name to display on the right
@@ -82,6 +82,14 @@ const Button = ({
     ? 'kol-btn-danger'
     : resolvedVariant === 'grey'
     ? 'kol-btn-grey'
+    /* `nav` — transparent box, oq-64 ink (2026-08-01). The class had lived in
+     * the theme since the shell landed with NO component able to emit it, so
+     * every consumer that wanted this exact weight hand-wrote the box instead:
+     * that orphan is the direct cause of the four-container header. It is the
+     * chrome rung — one step brighter than `ghost` at oq-48 — and it is what
+     * `text-fg-64` meant every time a call site typed it. */
+    : resolvedVariant === 'nav'
+    ? 'kol-btn-nav'
     : 'kol-btn-secondary'
 
   // Add size class — pairs the padding rule with its mono type class.

package/src/atoms/IconFrame.jsx

@@ -36,8 +36,27 @@ import { SOLO } from '../hooks/glyphLadders.js'
  * moves with it — that is the 2026-07-28 law, and it only means something if the
  * two are separable.
  *
- * Deliberately absent: `onClick`, `href`, `disabled`, `aria-pressed`, `title`.
- * Wanting any of those means wanting a `Button` with `iconOnly`, not this.
+ * IT TAKES A CLICK (2026-08-01 ruling) — *"you dont use a button… you use the
+ * ICON COMPONENT… it has no interactive states."* This file used to say the
+ * opposite, and called it "the entire point": no `onClick`, no `href`, and
+ * *"wanting any of those means wanting a Button with iconOnly, not this."*
+ *
+ * That was one sentence too strong. Two separate things had been welded
+ * together — **is it clickable** and **does it light up** — and only the second
+ * was ever the point. The shell header proved it: six chrome controls all
+ * needing a click, none wanting a hover wash, so every one of them hand-wrote
+ * its own box and the row ended up on four different containers.
+ *
+ * So `onClick` renders a `<button>`, `href` renders an `<a>`, and neither
+ * gains a state rule. The UA's own button chrome is reset in the theme
+ * (`button.kol-icon-frame, a.kol-icon-frame`) so "no states" is a property of
+ * the CLASS rather than of the tag — which is exactly the correction this
+ * component's own docstring already argued for when it refused to borrow
+ * `kol-btn-*` on a span.
+ *
+ * Still deliberately absent: `disabled` and `aria-pressed`. Both describe a
+ * control that CHANGES appearance with state, which is the line that stays.
+ * Want the wash, the pressed fill or the disabled dim? That is `Button`.
  *
  * @param {string} name       icon name (kol-icons)
  * @param {string} variant    primary|secondary|accent|outline|ghost|nav|grey|danger
@@ -62,18 +81,39 @@ export default function IconFrame({
   size = 'md',
   radius = 'sm',
   iconSize = null,
+  onClick,
+  href,
   className = '',
   ...rest
 }) {
   if (!name) return null
   const radiusCls = radius === 'full' ? ' kol-icon-frame-radius-full' : ''
   const resolvedIconSize = iconSize ?? GLYPH[size] ?? GLYPH.md
+  const cls = `kol-icon-frame kol-icon-frame-${variant} kol-icon-frame-${size}${radiusCls} ${className}`.trim()
+  const glyph = <Icon name={name} size={resolvedIconSize} />
+
+  /* The element follows the affordance, and the CLASS is identical in all three
+   * branches — that is the whole contract. A frame that can be clicked must be
+   * a real button or a real link (keyboard, focus order, middle-click, screen
+   * readers); a frame that cannot must not be either, or it lands in the tab
+   * order announcing itself as something to press. */
+  if (href) {
+    return (
+      <a className={cls} href={href} {...rest}>
+        {glyph}
+      </a>
+    )
+  }
+  if (onClick) {
+    return (
+      <button type="button" className={cls} onClick={onClick} {...rest}>
+        {glyph}
+      </button>
+    )
+  }
   return (
-    <span
-      className={`kol-icon-frame kol-icon-frame-${variant} kol-icon-frame-${size}${radiusCls} ${className}`.trim()}
-      {...rest}
-    >
-      <Icon name={name} size={resolvedIconSize} />
+    <span className={cls} {...rest}>
+      {glyph}
     </span>
   )
 }

package/src/hooks/useScrollSpy.js

@@ -29,8 +29,15 @@ export default function useScrollSpy(ids, { rootMargin = '-30% 0px -60% 0px', ed
       const atTop = top < edgeOffset
       const atBottom = top + viewH >= fullH - edgeOffset * 0.8
       if (atTop) {
+        /* THE FIRST HEADING, not null (user ruling 2026-08-01): *"at any given
+         * time you are at some place in the file, THAT LOCATION SHOULD
+         * HIGHLIGHT"*. The top lock used to clear the active id, so the rail
+         * highlighted nothing at rest — and a page opens at rest, which made
+         * "no active row" the state the reader saw first and most. The bottom
+         * lock has always activated the LAST id; this is that rule, both ends.
+         * You are at the top of the document, so you are in its first section. */
         edgeLockRef.current = 'top'
-        setActiveId(null)
+        setActiveId(ids[0])
       } else if (atBottom) {
         edgeLockRef.current = 'bottom'
         setActiveId(ids[ids.length - 1])

package/src/index.js

@@ -123,6 +123,14 @@ export { Icon } from '@kolkrabbi/kol-icons'
 export { default as Graphic, GRAPHICS } from './graphics/Graphic.jsx'
 export { GRAPHIC_RAW } from './graphics/graphicData.js'
 
+/* The glyph ladders, exported 2026-08-01. They were internal, so anything
+ * OUTSIDE this package that pairs an icon with a label had to hardcode a
+ * number — the shell header's tabs took `size={14}`, foundry's section header
+ * took `20`, and neither could reference the rule it was meant to follow.
+ * Cross-package imports go through the `@kolkrabbi/*` specifier (ARCHITECTURE
+ * §3), so an export is the only way another package can obey the ladder. */
+export { SOLO, ADJACENT, glyphSize } from './hooks/glyphLadders.js'
+
 // hooks
 export { default as usePrefersReducedMotion } from './hooks/usePrefersReducedMotion.js'
 export { default as useReveal } from './hooks/useReveal.js'

package/src/molecules/CodeBlock.jsx

@@ -19,6 +19,14 @@ import { Icon } from '@kolkrabbi/kol-icons'
  *   • Portable Text: `value={{ code, language, filename }}`
  *   • Direct props: `code` / `language` / `filename`
  *   • Children: `<CodeBlock language="js">{'…'}</CodeBlock>`
+ *
+ * `language` falls back to `'text'`, and a `'text'` block draws NO chip — so a
+ * fence that declares nothing renders as an unlabelled slab. That fallback is
+ * kept (a chip reading "text" is worse than none) and the fix is upstream:
+ * every fence declares a language, enforced by `pnpm validate:fences`.
+ *
+ * @param {string} [size='md']  'sm' | 'md' — the box and the type step together.
+ * @param {boolean} [bare]      drop the FRAME; the host owns it. Not a size.
  */
 
 const CheckMarkIcon = () => (
@@ -65,7 +73,13 @@ const syntaxTheme = (foregroundToken = 80) => ({
 /* `bare` (2026-07-30): highlight + chip + copy WITHOUT the framed chrome — for
  * hosts that already own the frame (PreviewCard's Code tab sat a full
  * CodeBlock frame inside the kol-doc-figure border: frame-in-frame). */
-export default function CodeBlock({ children, code: codeProp, language: languageProp, filename: filenameProp, value, bare = false }) {
+/* `size` (2026-08-01, user ruling). The block had no size at all — its padding
+ * and type size sat in `.kol-codeblock` as unnamed constants, so *"its just
+ * whatever its defaulting to"* was literally true and no call site could ask
+ * for anything else. `md` is those exact values, named; `sm` is one step down
+ * on both axes. Size is INDEPENDENT of `bare`: bare removes the frame, size
+ * sets the box, and a bare block still has one. */
+export default function CodeBlock({ children, code: codeProp, language: languageProp, filename: filenameProp, value, bare = false, size = 'md' }) {
   const [copied, setCopied] = useState(false)
 
   const code = String(value?.code ?? codeProp ?? children ?? '')
@@ -84,7 +98,7 @@ export default function CodeBlock({ children, code: codeProp, language: language
 
   return (
     <div className={bare ? '' : 'kol-codeblock-wrapper'}>
-      <div className={`kol-codeblock${bare ? ' kol-codeblock--bare' : ''}`}>
+      <div className={`kol-codeblock kol-codeblock--${size}${bare ? ' kol-codeblock--bare' : ''}`}>
         {(filename || (language && language !== 'text')) && (
           <div className="kol-codeblock-filename">{filename || language}</div>
         )}

package/src/molecules/ShellDrawer.jsx

@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
-import { Icon } from '@kolkrabbi/kol-icons'
+import Button from '../atoms/Button.jsx'
 import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 
 /* taxonomy-ok: nests kol-icons's Icon (a package import the relative-import
@@ -150,14 +150,21 @@ export default function ShellDrawer({
       >
         <div className="mb-6 flex items-center gap-4">
           {header != null && <div className="min-w-0 flex-1">{header}</div>}
-          <button
-            type="button"
+          {/* The box has an owner (2026-08-01). This hand-wrote the icon-button
+            * square and its hover wash; `Button variant="nav"` IS that string.
+            * `iconSize` holds the glyph where it was — the ladder's md rung is
+            * heavier than a drawer close wants, and Button documents iconSize
+            * for exactly the cases the ladder cannot serve. The SQUARE is what
+            * needed an owner, and it now has one. */}
+          <Button
+            variant="nav"
+            size="md"
+            iconOnly="x"
+            iconSize={14}
             onClick={onClose}
             aria-label="Close"
-            className="ml-auto flex h-8 w-8 shrink-0 items-center justify-center rounded-md border-0 bg-transparent cursor-pointer text-fg-64 transition-colors hover:bg-fg-08 hover:text-emphasis"
-          >
-            <Icon name="x" size={14} />
-          </button>
+            className="ml-auto shrink-0"
+          />
         </div>
         <div className="flex-1 overflow-y-auto pr-1" style={{ overflowAnchor: 'none' }}>
           {children}