@kolkrabbi/kol-workshop 0.32.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "private": false,
   "description": "KOL workshop/docs system — a handrolled markdown engine, search, tag system (incl. a d3 tag graph), docs viewer, and docs shell. Sits above @kolkrabbi/kol-{theme,icons,component,framework}; content is consumer-injected (the package never globs docs).",
   "license": "MIT",
@@ -13,9 +13,9 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
-    "@kolkrabbi/kol-brand": "^0.1.3",
+    "@kolkrabbi/kol-search": "^0.2.0",
     "@kolkrabbi/kol-markdown": "^0.1.2",
-    "@kolkrabbi/kol-search": "^0.2.0"
+    "@kolkrabbi/kol-brand": "^0.1.3"
   },
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.228.0",
@@ -27,10 +27,10 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.230.0",
     "@kolkrabbi/kol-icons": "^0.30.0",
-    "@kolkrabbi/kol-theme": "^0.158.0",
-    "@kolkrabbi/kol-framework": "^0.47.0"
+    "@kolkrabbi/kol-framework": "^0.48.0",
+    "@kolkrabbi/kol-theme": "^0.159.0",
+    "@kolkrabbi/kol-component": "^0.230.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -14,4 +14,6 @@ export * from './tags/index.js'
 export * from './exhibit/index.js'
 export * from './compositions/index.js'
 export * from './search/index.js'
+/* retiring — ContentRow replaces it (retirement ledger, 2026-09-30) */
+export { default as ResultRow } from './search/ResultRow.jsx'
 export * from './engine/index.js'

package/src/search/ResultRow.jsx

@@ -1,33 +1,28 @@
-import { Link } from 'react-router-dom'
-
 /**
- * ResultRow — one search result: a title, a meta line, an optional description, the whole row a
- * link (2026-09-30, open questions Round 2 — the user: *"I like both, is this a component? if it
- * is I would just have it available as variants … underline is more appealing currently"*).
- *
- * Two variants, each a complete pair — the wash needs its x padding, the underline must not have
- * one (Round 1: x padding without a wash was drawn wrong):
- *   `underline` (default) — no ground; the title underlines and the row inks up on hover
- *   `wash`                — x padding and a ground wash on hover
- *
- * @param {string}    to           the route the row opens
- * @param {ReactNode} title        the result's name (a highlighted node is fine)
- * @param {string}    [meta]       kind · category · space · date
- * @param {ReactNode} [description]
- * @param {'underline'|'wash'} [variant='underline']
+ * @deprecated — use kol-component's `ContentRow` (variant `article`, `media={false}`). ResultRow was
+ * minted 2026-09-30 for the search page while the design system already shipped its row; it
+ * forwards to ContentRow and drops at 30 days on the retirement ledger. `variant` is ignored.
  */
-const VARIANTS = {
-  underline: { row: 'group flex flex-col gap-1 py-3 opacity-80 hover:opacity-100 focus-visible:opacity-100', title: 'group-hover:underline underline-offset-4' },
-  wash: { row: 'flex flex-col gap-1 px-3 py-3 hover:bg-fg-04', title: '' },
-}
 
-export default function ResultRow({ to, title, meta, description, variant = 'underline' }) {
-  const v = VARIANTS[variant] ?? VARIANTS.underline
+import { useNavigate } from 'react-router-dom'
+import { ContentRow } from '@kolkrabbi/kol-component'
+
+/**
+ * @deprecated — use kol-component's `ContentRow` (variant `article`, `media={false}`). ResultRow was
+ * minted 2026-09-30 for the search page while the design system already shipped its row; it
+ * forwards to ContentRow and drops at 30 days on the retirement ledger. `variant` is ignored.
+ */
+export default function ResultRow({ to, title, meta, description }) {
+  const navigate = useNavigate()
   return (
-    <Link to={to} className={v.row}>
-      <span className={`kol-doc-body text-emphasis ${v.title}`.trim()}>{title}</span>
-      {meta && <span className="kol-helper-12 text-subtle">{meta}</span>}
-      {description && <span className="kol-doc-body">{description}</span>}
-    </Link>
+    <ContentRow
+      variant="article"
+      media={false}
+      href={to}
+      onNavigate={(e) => { e.preventDefault(); navigate(to) }}
+      eyebrow={meta}
+      title={title}
+      body={description}
+    />
   )
 }

package/src/search/SearchPage.jsx

@@ -1,7 +1,6 @@
 import { Fragment, useMemo } from 'react'
-import { useSearchParams } from 'react-router-dom'
-import { Button, EmptyState, Input, Pill } from '@kolkrabbi/kol-component'
-import ResultRow from './ResultRow.jsx'
+import { useNavigate, useSearchParams } from 'react-router-dom'
+import { Button, ContentRow, EmptyState, Input, Pill } from '@kolkrabbi/kol-component'
 import { createIndex, search, parseQuery } from '@kolkrabbi/kol-search'
 import { DocHeader, DocSection } from '../docs/DocKit.jsx'
 
@@ -45,7 +44,8 @@ const readToken = (t) => (t.kind === 'term'
     ? `${t.field} ${t.value}`
     : `${t.negate ? 'not ' : ''}${t.field === 'tags' ? 'tag' : t.field}: ${t.value}${t.via === 'smart' ? ' (from the word)' : ''}`)
 
-export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_FACETS, limit = 60, rowVariant = 'underline' }) {
+export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_FACETS, limit = 60 }) {
+  const navigate = useNavigate()
   const [params, setParams] = useSearchParams()
   const q = params.get('q') ?? ''
   const index = useMemo(() => createIndex(items), [items])
@@ -125,12 +125,16 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
           <ol className="flex flex-col">
             {out.results.map((r) => (
               <li key={r.item.id} className="border-t border-fg-08 first:border-t-0">
-                <ResultRow
-                  to={r.item.href}
-                  variant={rowVariant}
+                {/* THE SHIPPED ROW (2026-09-30): kol-component's ContentRow, the row form of the
+                  * content-card system — not a row minted here. Article form, no cover. */}
+                <ContentRow
+                  variant="article"
+                  media={false}
+                  href={r.item.href}
+                  onNavigate={(e) => { e.preventDefault(); navigate(r.item.href) }}
+                  eyebrow={[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
                   title={<Highlight text={r.item.title} ranges={r.highlights.title} />}
-                  meta={[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
-                  description={r.item.description}
+                  body={r.item.description}
                 />
               </li>
             ))}

package/src/search/index.js

@@ -1,2 +1 @@
 export { default as SearchPage } from './SearchPage.jsx'
-export { default as ResultRow } from './ResultRow.jsx'

package/src/shell/ShellLayout.jsx

@@ -2,7 +2,7 @@ import { createContext, useContext, useMemo, useRef, useState, useEffect, Suspen
 import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom'
 import { ShellHeader } from '@kolkrabbi/kol-framework'
 import ShellSidebar, { RAIL_FOLD_EVENT } from './ShellSidebar.jsx'
-import { IconFrame, ShellDrawer, ShellSearchOverlay, ShortcutsOverlay, SettingsSections, SettingsSwitch, Tooltip } from '@kolkrabbi/kol-component'
+import { IconFrame, ShellDrawer, ShellSearchOverlay, ShortcutsOverlay, SettingsPanel, SettingsSections, SettingsSwitch, Tooltip, useDragResize } from '@kolkrabbi/kol-component'
 import { createIndex, search } from '@kolkrabbi/kol-search'
 import { useTagMode } from '../tags/TagModeContext.jsx'
 import TagModeOverlay from '../tags/TagModeOverlay.jsx'
@@ -79,37 +79,27 @@ export const SHELL_SCROLL_ROOT = '#shell-scroll'
  * overflow (`.shell-rail`, kol-components-workshop.css): exactly one region
  * tall, a seam toward the page, the chrome inset inside the seam.
  * overflow-x-hidden (2026-07-30): long tree rows must not scroll sideways. */
-/* RESIZABLE RAILS (2026-09-30, the names audit; Round 3 Q3 — decided on the recommendation, the
- * user asleep, for review). A 6px grab strip on the edge facing the page: drag to set the width
- * (200–420, remembered), double-click to reset to the shell's 256. The width is the shell's own
- * token, `--kol-shell-nav-w` / `--kol-shell-toc-w`, set on the shell root, so the grid tracks and
- * the rail's own box follow it. */
-const RAIL_MIN = 200
-const RAIL_MAX = 420
-const RailGrip = ({ side, width, onChange }) => {
-  const start = (e) => {
-    e.preventDefault()
-    const x0 = e.clientX
-    const w0 = width
-    const move = (m) => onChange(Math.round(Math.min(RAIL_MAX, Math.max(RAIL_MIN, w0 + (side === 'end' ? m.clientX - x0 : x0 - m.clientX)))))
-    const up = () => { window.removeEventListener('pointermove', move); window.removeEventListener('pointerup', up) }
-    window.addEventListener('pointermove', move)
-    window.addEventListener('pointerup', up)
-  }
-  return (
-    <div
-      role="separator"
-      aria-orientation="vertical"
-      aria-label="Resize rail"
-      onPointerDown={start}
-      onDoubleClick={() => onChange(null)}
-      className={`absolute top-0 hidden h-full w-1.5 cursor-col-resize hover:bg-oq-08 lg:block ${side === 'end' ? 'right-0' : 'left-0'}`}
-    />
-  )
+/* RESIZABLE RAILS (2026-09-30) — THE DS GESTURE, not a local one: `useDragResize` (the grab edge
+ * SideNav and EditorShell wear — drag resizes, a click or a drag under the snap collapses, arrows
+ * step, release near the default snaps back) and the `.kol-rail-grab` pill. Each rail has its own
+ * token family (`kol-shell-nav` · `kol-shell-toc`, tokens in kol-framework.css) so the two never
+ * drag together; width lasts the session (persistWidth off, the 2026-09-03 ruling). A collapse
+ * from the grab is the shell's own "hide the rail" — the same state `[` / `]` toggle. */
+const useRailGrab = (token, side, hide) => {
+  const ref = useRef(null)
+  const { collapsed, toggleCollapsed, grabProps } = useDragResize(ref, { token, side })
+  useEffect(() => {
+    if (!collapsed) return
+    hide()
+    toggleCollapsed() // un-stamp the hook's collapse — the shell's own state now holds it
+    document.documentElement.style.removeProperty(`--${token}-w`) // it returns at the stylesheet width
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [collapsed])
+  return { ref, grab: <div {...grabProps} className={`kol-rail-grab kol-rail-grab--${side} hidden lg:block`} /> }
 }
 
-const NavColumn = ({ children, grip }) => (
-  <aside aria-label="Navigation" className="shell-rail shell-rail--nav shell-sidebar-sticky hidden lg:block pt-6 md:pt-6 lg:pt-8 pb-8">
+const NavColumn = ({ children, grip, railRef }) => (
+  <aside ref={railRef} aria-label="Navigation" className="shell-rail shell-rail--nav shell-sidebar-sticky hidden lg:block pt-6 md:pt-6 lg:pt-8 pb-8">
     {children}
     {grip}
   </aside>
@@ -148,8 +138,8 @@ const MainColumn = ({ children, fullHeight, width = 'canvas', padStart, padEnd }
 /* `xl`, not `lg` — the grid only declares a third column at xl (gridCols
  * below). The breakpoint here and the one in gridCols are one decision and
  * must not be stated twice differently. */
-const TocColumn = ({ children, grip }) => (
-  <aside aria-label="Table of contents" className="shell-rail shell-rail--toc shell-sidebar-sticky hidden xl:block pt-6 md:pt-6 lg:pt-8 pb-8">
+const TocColumn = ({ children, grip, railRef }) => (
+  <aside ref={railRef} aria-label="Table of contents" className="shell-rail shell-rail--toc shell-sidebar-sticky hidden xl:block pt-6 md:pt-6 lg:pt-8 pb-8">
     {grip}
     {/* The width is the grid track (--kol-shell-toc-w). An empty rail still
       * holds its column (user ruling 2026-08-01): a rail that disappears
@@ -195,11 +185,10 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   const [prefs, setPrefs] = useState(readSettings)
   const setPref = (key, value) => setPrefs((p) => { const next = { ...p, [key]: value }; writeSettings(next); return next })
   const [navCollapsed, setNavCollapsed] = useState(() => readSettings().navHidden === true)
-  /* rail widths — null = the shell's token; a number is the viewer's own (remembered) */
-  const [navW, setNavW] = useState(() => readSettings().navW ?? null)
-  const [tocW, setTocW] = useState(() => readSettings().tocW ?? null)
-  const setRailW = (key, set) => (w) => { set(w); writeSettings({ ...readSettings(), [key]: w }) }
+
   const [tocCollapsed, setTocCollapsed] = useState(() => readSettings().tocHidden === true)
+  const navGrab = useRailGrab('kol-shell-nav', 'left', () => { setNavCollapsed(true); writeSettings({ ...readSettings(), navHidden: true }) })
+  const tocGrab = useRailGrab('kol-shell-toc', 'right', () => { setTocCollapsed(true); writeSettings({ ...readSettings(), tocHidden: true }) })
   const [isSettingsOpen, setIsSettingsOpen] = useState(false)
   /* ONE QUERY (user ruling 2026-08-01). The palette's text used to live here
    * while tags lived in TagModeContext — two states, and therefore two
@@ -465,10 +454,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
         <ShellContentWidthContext.Provider value={setContentWidth}>
         <ShellTocCollapsedContext.Provider value={setTocCollapsed}>
         <ShellNavCollapsedContext.Provider value={setNavCollapsed}>
-        <div
-          className="fixed inset-0 flex flex-col bg-surface-primary text-auto"
-          style={{ ...(navW ? { '--kol-shell-nav-w': `${navW}px` } : {}), ...(tocW ? { '--kol-shell-toc-w': `${tocW}px` } : {}) }}
-        >
+        <div className="fixed inset-0 flex flex-col bg-surface-primary text-auto">
           <ShellHeader
             brand={brand}
             nav={navItems}
@@ -503,7 +489,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
           >
               <div className={`shell-content-grid grid ${gridCols}`} data-layout={layoutType} style={{ paddingInline: 'var(--kol-pad-chrome-x)' }}>
                   {showNav && (
-                    <NavColumn grip={<RailGrip side="end" width={navW ?? 256} onChange={setRailW('navW', setNavW)} />}>
+                    <NavColumn railRef={navGrab.ref} grip={navGrab.grab}>
                       {renderSidebar ? renderSidebar({ activeRoute }) : <ShellSidebar routes={routes} basePath={basePath} />}
                     </NavColumn>
                   )}
@@ -521,7 +507,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
                     * the grid's third track so main keeps one width across
                     * every route (user ruling 2026-08-01). */}
                   {showToc && (
-                    <TocColumn grip={<RailGrip side="start" width={tocW ?? 256} onChange={setRailW('tocW', setTocW)} />}>
+                    <TocColumn railRef={tocGrab.ref} grip={tocGrab.grab}>
                       {effectiveTocContent}
                     </TocColumn>
                   )}
@@ -588,13 +574,12 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
             * settings page or settings sidebar … to offload some functional
             * settings, search settings, sidenav settings"). A right drawer over
             * the page, the same rows the apps' settings use (SettingsSections). */}
-          <ShellDrawer open={isSettingsOpen} onClose={() => setIsSettingsOpen(false)} side="right" width={360}>
-            {/* the drawer draws its own close — no second one here */}
-            <div className="flex flex-col gap-6 p-6">
-              <span className="kol-doc-eyebrow">Settings</span>
-              <SettingsSections sections={settingsSections} labelWidth="auto" />
-            </div>
-          </ShellDrawer>
+          {/* THE APPROVED DRAWER (2026-09-30): kol-component's `SettingsPanel` — the composition locked
+            * 2026-08-27 that media's Display settings and Trash already wear: title header, divided
+            * sections. This was a hand-built ShellDrawer + eyebrow + undivided sections. */}
+          <SettingsPanel open={isSettingsOpen} variant="drawer" title="Settings" onClose={() => setIsSettingsOpen(false)}>
+            <SettingsSections sections={settingsSections} divided />
+          </SettingsPanel>
         </div>
         </ShellNavCollapsedContext.Provider>
         </ShellTocCollapsedContext.Provider>