@kolkrabbi/kol-framework 0.43.0 → 0.45.0

package/kol-framework.css

@@ -63,16 +63,17 @@ body {
   --kol-sidenav-step: var(--kol-spacing-4);    /* keyboard resize increment */
   --kol-sidenav-snap-default: var(--kol-sidenav-step); /* release within this of the default clears the override */
   --kol-sidenav-w-collapsed: 56px;
-  /* The workshop shell's RIGHT rail. EQUAL TO THE LEFT (user ruling
-     2026-08-01) — the two rails frame the same content and a lopsided frame is
-     a frame nobody drew on purpose; it read 14rem against the left's 16rem.
-     Kept as its own token rather than aliased: the right rail can be ruled
-     different later without touching the sidenav.
-     The track is RESERVED whether or not the rail has anything in it — a rail
-     that vanishes on a heading-less page re-flows main, so the same shell
-     renders at two widths. Distinct from --kol-toc-w further down, which is
-     the BRAND layout's rail: same concept, two shells, two numbers. */
-  --kol-shell-toc-w: 16rem;
+  /* THE WORKSHOP SHELL'S RAILS — their own pair, 256px each (showcase
+     refinement 2026-09-28, user: "should they both be the same width? layout
+     feels asymmetrical"). The left rail used to read --kol-sidenav-w, which is
+     the DRAGGABLE app sidenav's ladder (264, 320 from 1536 — useDragResize,
+     NavRail, the labs rail, the deck editor), so the docs shell rendered
+     320 | main | 256: one token, two shells. The workshop rails are not
+     draggable and frame the same content, so they are equal and fixed, in px
+     like every other layout width. Distinct from --kol-toc-w further down,
+     which is the BRAND layout's rail. */
+  --kol-shell-nav-w: 256px;
+  --kol-shell-toc-w: 256px;
   --kol-container-max: 100%;
 
   /* Opacity tokens (--kol-fg-*) + text-role tokens (--kol-text-*) live in
@@ -736,7 +737,7 @@ body {
 .kol-portal-footer a { text-decoration: none; transition: opacity 150ms ease; }
 .kol-portal-footer a:hover { opacity: 0.8; }
 
-/* ───── Back link (structural only; use kol-helper-xs uppercase tracking-widest text-fg-64 on JSX) ───── */
+/* ───── Back link (structural only; PageHero sets its type: kol-helper-12 tracking-widest text-body) ───── */
 
 .kol-back-link {
   display: inline-flex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "KOL app shell — sidenav, layout, theme toggle, footer, heroes + brand color layer. SideNav takes nav data as props so the tree stays app-local.",
   "license": "MIT",
   "type": "module",
@@ -21,8 +21,8 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.181.0",
-    "@kolkrabbi/kol-icons": "^0.25.0"
+    "@kolkrabbi/kol-component": "^0.228.0",
+    "@kolkrabbi/kol-icons": "^0.29.0"
   },
   "files": [
     "src",

package/src/PageLayout.jsx

@@ -117,6 +117,7 @@ export default function PageLayout({ navTree = [], header, footer, defaultTocCon
             data-drawer-open={drawerOpen ? 'true' : undefined}
             data-toc={showToc ? 'true' : undefined}
           >
+            {/* tip-ok: phone-only (md:hidden) — a hover tip never shows on touch; the aria-label names it */}
             <button
               type="button"
               className="kol-sidenav-hamburger md:hidden fixed top-3 left-3 z-30 w-10 h-10 inline-flex items-center justify-center rounded-full bg-surface-primary border border-fg-08 text-emphasis"

package/src/ShellHeader.jsx

@@ -128,12 +128,12 @@ export default function ShellHeader({
             <div className="flex shrink-0 items-center gap-1">
               {actions}
               {showThemeToggle && (
-                <Tooltip label="Toggle theme">
+                <>
                   {/* md at every width (user re-rule 2026-08-09: the whole
                     * header glyph row rides md, full ink — the earlier lg-at-lg+
                     * split is repealed, which also collapsed the two spans). */}
                   <ThemeToggle fill="none" label={false} size="md" />
-                </Tooltip>
+                </>
               )}
               {onMenuClick && (
                 <Tooltip label="Open navigation menu">

package/src/SideNav.jsx

@@ -4,7 +4,7 @@ import { createPortal } from 'react-dom'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { Tooltip } from '@kolkrabbi/kol-component'
 import ThemeToggle from './ThemeToggle'
-import useDragResize from './useDragResize'
+import { useDragResize } from '@kolkrabbi/kol-component'
 
 /**
  * SideNav — the grouped navigation rail.

package/src/ThemeToggle.jsx

@@ -1,4 +1,5 @@
 import { Icon } from '@kolkrabbi/kol-icons'
+import { Tooltip } from '@kolkrabbi/kol-component'
 import { useTheme } from './theme.js'
 
 /**
@@ -88,6 +89,12 @@ export default function ThemeToggle({
    * ink, so the toggle beside a sunken Dropdown matches it; `inverse` aliased. Rules in kol-theme. */
   tone = 'default',
   className = '',
+  /* THE TOGGLE CARRIES ITS OWN TOOLTIP (2026-09-28). It set a native `title`
+   * AND the header wrapped it in a KOL Tooltip, so hovering showed both — the
+   * browser's "Switch to light mode · following your system" under the DS's
+   * "Toggle theme". One tip now, the DS one, with the richer text; `false`
+   * leaves the button bare for a caller that wraps it itself. */
+  tooltip = true,
 }) {
   const { theme, mode, cycle, clear } = useTheme()
   /* six tones (tone-is-the-ground-axis, 2026-09-03); unset inherits the wrapper's */
@@ -149,12 +156,13 @@ export default function ThemeToggle({
     type: 'button',
     onClick,
     'aria-label': `Switch to ${next} mode`,
-    title: `Switch to ${next} mode${resetHint}`,
   }
+  const tip = `Switch to ${next} mode${resetHint}`
+  const wrap = (node) => (tooltip ? <Tooltip label={tip}>{node}</Tooltip> : node)
 
   /* ── DEPRECATED aliases — old chrome verbatim (0.6.x) ── */
   if (variant === 'icon') {
-    return (
+    return wrap(
       <button {...shared} className={`kol-theme-toggle kol-theme-toggle-none kol-btn-${size} kol-btn-icon ${extra}`.trim()}>
         {iconSwap(glyphSolo)}
       </button>
@@ -176,7 +184,7 @@ export default function ThemeToggle({
     const chromeCls = bare
       ? `w-full inline-flex items-center justify-start gap-2 ${barePadY} px-6 ${mono} bg-transparent text-emphasis`
       : 'kol-theme-toggle kol-theme-toggle-subtle kol-btn-md kol-mono-14 w-full justify-start gap-2'
-    return (
+    return wrap(
       <button {...shared} className={`${chromeCls} ${extra}`.trim()}>
         <span className="inline-flex items-center justify-center shrink-0" aria-hidden="true">
           {iconSwap(bare ? glyphWithText : glyphSolo)}
@@ -194,7 +202,7 @@ export default function ThemeToggle({
   if (variant === 'flush') {
     const glyph = label ? glyphWithText : glyphSolo
     const cls = `kol-theme-toggle kol-theme-toggle-flush gap-2 ${mono} ${width} ${extra}`
-    return (
+    return wrap(
       <button {...shared} className={cls.replace(/\s+/g, ' ').trim()}>
         {!iconRight && iconSwap(glyph)}
         {label && <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[next]}</span>}
@@ -209,13 +217,13 @@ export default function ThemeToggle({
   const fillCls = fill === 'none' ? 'kol-theme-toggle-none' : 'kol-theme-toggle-subtle'
   if (!label) {
     // icon-only pins the square box per rung — geometry condition, not a variant
-    return (
+    return wrap(
       <button {...shared} className={`kol-theme-toggle ${fillCls} kol-btn-${size} kol-btn-icon ${width} ${extra}`.replace(/\s+/g, ' ').trim()}>
         {iconSwap(glyphSolo)}
       </button>
     )
   }
-  return (
+  return wrap(
     <button {...shared} className={`kol-theme-toggle ${fillCls} kol-btn-${size} ${mono} gap-2 ${width} ${extra}`.replace(/\s+/g, ' ').trim()}>
       {!iconRight && iconSwap(glyphWithText)}
       <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[next]}</span>

package/src/index.js

@@ -10,7 +10,10 @@
 export { default as PageLayout, default as AppShell } from './PageLayout.jsx'
 export { ShellTocContext, ShellTocCollapsedContext } from './PageLayout.jsx'
 export { default as SideNav } from './SideNav.jsx'
-export { default as useDragResize } from './useDragResize.js'
+/* MOVED to kol-component 2026-09-03 (editor-set-is-behind-its-source): its
+ * EditorShell needs the same rails and cannot import this package. Re-exported
+ * here under the name it has always had — this specifier stays valid. */
+export { useDragResize } from '@kolkrabbi/kol-component'
 export { default as ShellHeader, HEADER_ICON } from './ShellHeader.jsx'
 export { default as ThemeToggle } from './ThemeToggle.jsx'
 export { useTheme, applyTheme, getInitialTheme, THEME_STORAGE_KEY, THEME_BOOT_SCRIPT } from './theme.js'

package/src/useDragResize.js

@@ -1,311 +0,0 @@
-import { useEffect, useMemo, useRef, useState } from 'react'
-/* THE SAME GRAB AS THE SHELL RAIL (OneGrabGestureBothRails, kol-fxr 2026-08-30 —
- * user: *"why dont we use the grab animation and other sidenav settings to be
- * consistent?"*). fxr's /labs shows both rails at once and only the left one
- * woke as the cursor neared it, because each package had built the gesture
- * itself. The hook lives in kol-component, the one package both can reach —
- * kol-shell dropped its framework peer in 0.16.0, so neither could import the
- * other's. */
-import { useGrabEdge } from '@kolkrabbi/kol-component'
-
-/* Grab-edge resize + collapse for SideNav — THE single control since 0.17.0
- * (user build order 2026-08-09, completing the SideNavGrabResize brief: the
- * chip Button is gone in both states; the pill-marked edge does everything).
- * Logic lifted from the hand-tested brand proto (kol-website _tmp
- * useDragResizeProto.js), which forked this hook's 0.16.0 form.
- *
- *  - CLICK TOGGLES expand↔collapse: pointerup with < 3px of travel is a
- *    click, never a resize — drags only start past the slop, so toggle
- *    presses can't jitter the rail.
- *  - DRAG resizes; live width goes to --kol-sidenav-w on :root so the grid,
- *    shell-header brand block and aside follow one number. Dragging under
- *    --kol-sidenav-snap stamps :root[data-sidenav="collapsed"].
- *  - SNAP-TO-DEFAULT: releasing within --kol-sidenav-snap-default of the
- *    stylesheet default clears the override — you land exactly on default,
- *    never 249px or 263px.
- *  - DOUBLE-CLICK RESET IS GONE — it cannot coexist with click-toggle (two
- *    clicks would toggle-toggle-reset). Home keeps the reset; the snap band
- *    covers pointer users.
- *  - Keyboard on the focused separator: arrows resize by --kol-sidenav-step
- *    (ArrowLeft past the snap collapses), Home resets, Enter/Space toggle.
- *  - Width + state survive reload ('kol-sidenav' keeps the consumers'
- *    existing 'collapsed'|'expanded' schema; width under its own key).
- *
- * Every value the gesture needs is a --<token>-* custom property in the
- * consumer's CSS — no literals here except the click slop, which is a
- * gesture constant, not chrome. Missing tokens leave the gesture inert.
- *
- * SIDE-AGNOSTIC since ThreeColumnEditorShell (kol-fxr, 2026-08-15): the name
- * family and the drag direction are both arguments now, so a right-hand
- * inspector rail reuses this gesture — pointer, keyboard, snap, collapse and
- * persistence — instead of reimplementing it. The bullets above describe the
- * DEFAULT ('kol-sidenav', side 'left'), which is byte-identical to 0.17.0. */
-
-const CLICK_SLOP_PX = 3
-
-const root = () => document.documentElement
-
-/* Every name the gesture touches, derived from ONE token (ThreeColumnEditorShell,
- * filed from kol-fxr 2026-08-15). The default token reproduces the hardcoded
- * 0.17.0 names EXACTLY — 'kol-sidenav' → data-sidenav, --kol-sidenav-w,
- * storage 'kol-sidenav'/'kol-sidenav-w' — so SideNav and every existing caller
- * are untouched by this generalisation.
- *
- * The data-attribute drops the `kol-` prefix because that is what the shipped
- * CSS already selects (`:root[data-sidenav="collapsed"]`), not a new scheme. */
-export function buildNames(token) {
-  const base = token.replace(/^kol-/, '')
-  return {
-    stateKey: token,
-    widthKey: `${token}-w`,
-    collapsedAttr: `data-${base}`,
-    draggingAttr: `data-${base}-dragging`,
-    wVar: `--${token}-w`,
-    collapsedVar: `--${token}-w-collapsed`,
-    snapVar: `--${token}-snap`,
-    stepVar: `--${token}-step`,
-    snapDefaultVar: `--${token}-snap-default`,
-  }
-}
-
-/* Resolve a length token to px, or null when it is absent/unparsable. */
-function readVarPx(name) {
-  const raw = getComputedStyle(root()).getPropertyValue(name).trim()
-  const n = parseFloat(raw)
-  if (!raw || Number.isNaN(n)) return null
-  return raw.endsWith('rem') ? n * parseFloat(getComputedStyle(root()).fontSize) : n
-}
-
-/* Imperative DOM writes — pointermove must never re-render the nav tree.
- * React state syncs from the DOM at rest (release / key press / reset). */
-const stampCollapsed = (n, on) => {
-  if (on) root().setAttribute(n.collapsedAttr, 'collapsed')
-  else root().removeAttribute(n.collapsedAttr)
-}
-const writeWidth = (n, px) => {
-  if (px == null) root().style.removeProperty(n.wVar)
-  else root().style.setProperty(n.wVar, `${px}px`)
-}
-const readBack = (n) => {
-  const inline = parseFloat(root().style.getPropertyValue(n.wVar))
-  return {
-    collapsed: root().getAttribute(n.collapsedAttr) === 'collapsed',
-    widthPx: Number.isNaN(inline) ? null : inline,
-  }
-}
-
-/* @param ref      the panel being resized — its measured width seeds the drag
- * @param options  { token, side }
- *   token — the CSS/storage name family. Default 'kol-sidenav' (SideNav).
- *           A right-hand inspector passes its own, e.g. 'kol-rail', so the two
- *           rails never share one :root variable and drag together.
- *   side  — which EDGE the grab handle sits on. 'left' (default) is a rail on
- *           the left of the viewport whose handle is on its right edge, so
- *           rightward drag = wider. 'right' inverts both the pointer sign and
- *           the arrow keys.
- *   persistWidth — remember a dragged WIDTH across sessions. **Default false**
- *           (sidenav-drag-width-outranks-breakpoints, kol-client-olina
- *           2026-09-03; user: *"why would you want that in persistent memory?
- *           and even if you did, shouldnt it be an opt in via prop? off by
- *           default"*).
- *
- *           It used to be unconditional, and the width was replayed on boot as
- *           an INLINE custom property on `:root` — which outranks every
- *           stylesheet rule, so one drag on a laptop killed both shipped rungs
- *           (`--kol-sidenav-w: 264px` and the 320px `min-width:1536px` rule)
- *           permanently, on every machine, with no UI saying so and no selector
- *           a consumer could beat. Measured at 1600×900: a stored 210 rendered
- *           210 and the 1536 rung did nothing. A one-off gesture had become a
- *           permanent global.
- *
- *           Off, a drag still works and lasts the session; the rail follows the
- *           stylesheet and its breakpoints on the next boot. On, the old
- *           behaviour returns for an app that genuinely wants the rail
- *           remembered — and it is still an inline stamp, so an app opting in is
- *           choosing to outrank its own breakpoints. That precedence is worth
- *           inverting, but it is a bigger change than this ticket asked for.
- *
- *           STATE is untouched: collapsed/expanded still persists via
- *           `stateKey`, unconditionally, as it always did. The ticket says the
- *           two are separate questions and only asks about the width. */
-export default function useDragResize(ref, options = {}) {
-  const { token = 'kol-sidenav', side = 'left', defaultCollapsed = false, persistWidth = false } = options
-  /* -1 on a right-hand rail: the same rightward pointer travel that widens a
-   * left rail must NARROW a right one, because its handle faces the canvas. */
-  const dir = side === 'right' ? -1 : 1
-  const names = useMemo(() => buildNames(token), [token])
-
-  /* the handle's own ref, so the shared gesture can find it. Returned in
-   * `grabProps`, so a consumer already spreading those gets the wake, the
-   * travel and the dwell with no change. */
-  const grabRef = useRef(null)
-  useGrabEdge(grabRef)
-  const drag = useRef(null) // { startX, startW, snapPx, maxPx, moved } during a drag
-  const defaultPx = useRef(null)
-  const collapsedPx = useRef(null)
-  const [collapsed, setCollapsed] = useState(false)
-  const [widthPx, setWidthPx] = useState(null) // null = stylesheet default
-
-  const syncAndPersist = () => {
-    const { collapsed: c, widthPx: w } = readBack(names)
-    setCollapsed(c)
-    setWidthPx(w)
-    try {
-      localStorage.setItem(names.stateKey, c ? 'collapsed' : 'expanded')
-      /* width only when asked for; off, the key is not written AND any key a
-       * previous version left behind is cleared, so a consumer that bumps stops
-       * replaying a width it never opted into */
-      if (!persistWidth || w == null) localStorage.removeItem(names.widthKey)
-      else localStorage.setItem(names.widthKey, String(Math.round(w)))
-    } catch { /* storage blocked */ }
-  }
-
-  const toggleCollapsed = () => {
-    const { collapsed: c } = readBack(names)
-    stampCollapsed(names, !c)
-    syncAndPersist()
-  }
-
-  /* Boot: capture the stylesheet defaults BEFORE any inline override lands,
-   * then restore the persisted width/state. */
-  useEffect(() => {
-    defaultPx.current = readVarPx(names.wVar)
-    collapsedPx.current = readVarPx(names.collapsedVar)
-    let w = null
-    let stored = null
-    try {
-      /* off → never read it, and drop a key an earlier version wrote */
-      if (persistWidth) w = parseFloat(localStorage.getItem(names.widthKey)) || null
-      else localStorage.removeItem(names.widthKey)
-      stored = localStorage.getItem(names.stateKey)
-    } catch { /* storage blocked */ }
-    /* nothing stored → the consumer's boot state (RailSideNavPixelParity,
-     * 2026-08-28): an app rail boots collapsed, the brand sidebar boots open;
-     * the first drag or click persists and the default never speaks again */
-    const c = stored ? stored === 'collapsed' : !!defaultCollapsed
-    if (w) { writeWidth(names, w); setWidthPx(w) }
-    if (c) { stampCollapsed(names, true); setCollapsed(true) }
-  }, [names, defaultCollapsed, persistWidth])
-
-  useEffect(() => {
-    const onMove = (e) => {
-      if (!drag.current) return
-      const d = drag.current
-      const dx = e.clientX - d.startX
-      /* Below the slop the pointer is still a CLICK — resizing from the
-       * first pixel would jitter the rail on every toggle press. */
-      if (!d.moved) {
-        if (Math.abs(dx) < CLICK_SLOP_PX) return
-        d.moved = true
-      }
-      const next = d.startW + dx * dir
-      if (next < d.snapPx) {
-        stampCollapsed(names, true)
-      } else {
-        stampCollapsed(names, false)
-        writeWidth(names, Math.min(next, d.maxPx))
-      }
-    }
-    const onUp = () => {
-      if (!drag.current) return
-      const { moved } = drag.current
-      drag.current = null
-      root().removeAttribute(names.draggingAttr)
-      document.body.style.cursor = ''
-      document.body.style.userSelect = ''
-      if (!moved) { toggleCollapsed(); return } // a click, not a drag
-      /* Snap-to-default: release near the stylesheet default clears the
-       * override entirely. */
-      const { collapsed: c, widthPx: w } = readBack(names)
-      const band = readVarPx(names.snapDefaultVar) ?? readVarPx(names.stepVar) ?? 16
-      if (!c && w != null && defaultPx.current != null && Math.abs(w - defaultPx.current) <= band) {
-        writeWidth(names, null)
-      }
-      syncAndPersist()
-    }
-    window.addEventListener('pointermove', onMove)
-    window.addEventListener('pointerup', onUp)
-    return () => {
-      window.removeEventListener('pointermove', onMove)
-      window.removeEventListener('pointerup', onUp)
-    }
-  }, [names, dir])
-
-  const onPointerDown = (e) => {
-    const snapPx = readVarPx(names.snapVar)
-    if (defaultPx.current == null || snapPx == null) return // tokens absent → inert
-    e.preventDefault()
-    drag.current = {
-      startX: e.clientX,
-      startW: ref.current?.getBoundingClientRect().width ?? defaultPx.current,
-      snapPx,
-      /* mirror's ceiling (default × 3), resolved from the token not hardcoded */
-      maxPx: defaultPx.current * 3,
-      moved: false,
-    }
-    /* the grid's grid-template-columns ease would trail the pointer —
-     * kol-framework.css suspends it while this attribute is stamped */
-    root().setAttribute(names.draggingAttr, '')
-    document.body.style.cursor = 'col-resize'
-    document.body.style.userSelect = 'none'
-  }
-
-  const resetToDefault = () => {
-    stampCollapsed(names, false)
-    writeWidth(names, null)
-    syncAndPersist()
-  }
-
-  const onKeyDown = (e) => {
-    const snapPx = readVarPx(names.snapVar)
-    const stepPx = readVarPx(names.stepVar)
-    if (defaultPx.current == null || snapPx == null || stepPx == null) return
-    const { collapsed: c, widthPx: w } = readBack(names)
-    const current = w ?? defaultPx.current
-    /* The arrow that GROWS is the one pointing away from the rail's own edge —
-     * ArrowRight on a left rail, ArrowLeft on a right one. Same inversion the
-     * pointer gets, so keyboard and drag never disagree. */
-    const growKey = dir === 1 ? 'ArrowRight' : 'ArrowLeft'
-    const shrinkKey = dir === 1 ? 'ArrowLeft' : 'ArrowRight'
-    if (e.key === growKey) {
-      e.preventDefault()
-      if (c) stampCollapsed(names, false)
-      else writeWidth(names, Math.min(current + stepPx, defaultPx.current * 3))
-      syncAndPersist()
-    } else if (e.key === shrinkKey) {
-      e.preventDefault()
-      if (c) return
-      const next = current - stepPx
-      if (next < snapPx) stampCollapsed(names, true)
-      else writeWidth(names, next)
-      syncAndPersist()
-    } else if (e.key === 'Home') {
-      e.preventDefault()
-      resetToDefault()
-    } else if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault()
-      toggleCollapsed()
-    }
-  }
-
-  return {
-    collapsed,
-    toggleCollapsed,
-    grabProps: {
-      ref: grabRef,
-      /* the pill is drawn by `.kol-rail-grab` (kol-animation.css) — the hook
-       * only supplies `is-near` and `--kol-rail-grab-y`. A consumer's own
-       * className, spread after this, still wins. */
-      className: 'kol-rail-grab',
-      role: 'separator',
-      'aria-orientation': 'vertical',
-      'aria-label': 'Resize navigation',
-      'aria-valuenow': Math.round(collapsed ? collapsedPx.current : (widthPx ?? defaultPx.current)) || undefined,
-      'aria-valuemin': collapsedPx.current == null ? undefined : Math.round(collapsedPx.current),
-      'aria-valuemax': defaultPx.current == null ? undefined : Math.round(defaultPx.current * 3),
-      tabIndex: 0,
-      onPointerDown,
-      onKeyDown,
-    },
-  }
-}