@kolkrabbi/kol-component 0.164.0 → 0.166.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.164.0",
+  "version": "0.166.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/hooks/useGrabEdge.js

@@ -25,11 +25,26 @@ import gsap from 'gsap'
  * than that leaves the pill where it is, which is what stops it twitching.
  *
  * The element needs the `.kol-rail-grab` class for the drawing (kol-animation.css);
- * this hook only supplies `is-near` and `--kol-rail-grab-y`.
+ * this hook only supplies `is-near` and the travel variable.
+ *
+ * BOTH AXES (BrowsePageRulingsAndSeams, kol-r2b2 2026-09-02). A rail has one
+ * vertical edge; `ColumnBrowser` has a vertical handle per column AND a
+ * horizontal one along its foot, and the user's ruling is that they wear the
+ * same gesture. `axis` says which way the pill TRAVELS, and the near test is
+ * always the other one — a vertical line is approached across x, a horizontal
+ * line across y:
+ *
+ *   axis: 'y'  (default)  vertical edge  · near on x · travels on y · --kol-rail-grab-y
+ *   axis: 'x'             horizontal edge · near on y · travels on x · --kol-rail-grab-x
+ *
+ * The `-y` name is kept as it shipped rather than renamed to something
+ * axis-neutral: it is a published token the rail's CSS reads, and the pair
+ * `-x`/`-y` names two real axes rather than one concept twice.
  *
  * @param {React.RefObject<HTMLElement>} ref  the grab handle
+ * @param {{axis?: 'x'|'y'}} [options]  which way the pill travels (default 'y')
  */
-export default function useGrabEdge(ref) {
+export default function useGrabEdge(ref, { axis = 'y' } = {}) {
   useEffect(() => {
     let raf = 0
     const onMove = ({ clientX, clientY }) => {
@@ -39,16 +54,22 @@ export default function useGrabEdge(ref) {
         const h = ref.current
         if (!h) return
         const r = h.getBoundingClientRect()
-        const dist = Math.abs(clientX - (r.left + r.width / 2))
+        const vertical = axis === 'y'
+        /* the near test is ACROSS the line, the travel ALONG it */
+        const across = vertical ? clientX - (r.left + r.width / 2) : clientY - (r.top + r.height / 2)
+        const dist = Math.abs(across)
         const near = dist <= GRAB.near || (h.classList.contains('is-near') && dist <= GRAB.sleep)
         h.classList.toggle('is-near', near)
         if (!near) return
-        /* the travel band: bipolar from the middle, GRAB.range of the height */
-        const edge = (r.height * (1 - GRAB.range)) / 2
-        const along = Math.min(Math.max(clientY - r.top, edge), r.height - edge)
+        /* the travel band: bipolar from the middle, GRAB.range of the span */
+        const span = vertical ? r.height : r.width
+        const start = vertical ? r.top : r.left
+        const point = vertical ? clientY : clientX
+        const edge = (span * (1 - GRAB.range)) / 2
+        const along = Math.min(Math.max(point - start, edge), span - edge)
         if (h.dataset.grabSeeded && Math.abs(along - Number(h.dataset.grabTarget)) < GRAB.stick) return
         h.dataset.grabTarget = String(along)
-        const vars = { '--kol-rail-grab-y': `${along}px` }
+        const vars = { [vertical ? '--kol-rail-grab-y' : '--kol-rail-grab-x']: `${along}px` }
         /* the CSS fallback is 50%, a percentage — nothing to tween from, so the
          * first sighting sets and every move after tweens */
         if (h.dataset.grabSeeded) gsap.to(h, { ...vars, ...GRAB.travel, overwrite: 'auto' })
@@ -57,5 +78,5 @@ export default function useGrabEdge(ref) {
     }
     window.addEventListener('pointermove', onMove)
     return () => { window.removeEventListener('pointermove', onMove); cancelAnimationFrame(raf) }
-  }, [ref])
+  }, [ref, axis])
 }

package/src/organisms/ColumnBrowser.jsx

@@ -3,6 +3,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
 import KindPreview from '../molecules/KindPreview.jsx'
 import { formatLength } from '../molecules/AudioPreview.jsx'
 import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/mediaKinds.js'
+import useGrabEdge from '../hooks/useGrabEdge.js'
 
 /**
  * ColumnBrowser — Finder-style Miller columns over a flat key space (kol-r2b2's
@@ -24,17 +25,21 @@ import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/me
  * `window` (the overlay holds focus) and space closes — the opening keystroke
  * bubbles from here and is ignored.
  *
- * Rows wear the DS Table's cell metrics (12px 16px, mono 12, an oq-08 hairline
- * between rows, none after the last). Selected and cursor rows draw the HOVER
- * fill (`bg-fg-04`) — user ruling: "make hover state the selected state".
+ * Rows wear the DS Table's cell metrics (12px 16px, mono 12) with NO divider —
+ * the row is a rounded pill on a constant 4px inset, so selecting never shifts
+ * the layout (BrowsePageRulingsAndSeams, 2026-09-02). ONE fill on screen and it
+ * means selected: hover and the bare keyboard cursor paint nothing, the trail is
+ * `fg-02` and the deepest column holding a selection is `fg-04`.
  * Height defaults to 528px = 12 rows × 44px (user ruling); columns scroll. Both
  * the height and every column's width are DRAGGABLE, Finder-style
  * (ColumnBrowserResize, kol-r2b2 2026-08-27 — user: "column height drag yes and
  * individual column width drag" · "that should be a set in ds"): a strip along
  * the browser's bottom edge (`row-resize`) and one on each column's right edge
  * (`col-resize`, the border already there is the visual — the strip is the hit
- * area, invisible at rest, `fg-08` on hover / while dragging). Pointer events
- * with `setPointerCapture`, no library; native CSS `resize:` was rejected.
+ * area). Each strip carries the estate's GRAB PILL: hidden at rest, woken by
+ * pointer PROXIMITY (`useGrabEdge`, the rail's hook) and travelling along the
+ * line to meet the cursor. Pointer events with `setPointerCapture`, no library;
+ * native CSS `resize:` was rejected.
  *
  * The app-owned bits are SEAMS with working defaults: `urlOf(o)` (the preview
  * image — no URL, no image), `kindOf(o)` (image / video / audio / file from
@@ -94,11 +99,15 @@ const COL_ICON = { image: 'image', video: 'video', audio: 'file', playlist: 'vid
 
 /* ColumnBrowserChromeCorrections (kol-r2b2 2026-08-28, four user rulings measured live on admin.):
  * every column keeps its right edge, the last included — without it the browser reads as an
- * open-sided container when the columns do not fill the box (Finder closes it); a column's ONLY
- * row keeps its bottom hairline (`only:`) — its last row is also its first, and a missing
- * hairline beside neighbours that show one reads as a defect; and ONE ink for folders and files
- * — the `bg-fg-04` fill alone marks selection ("why is folder full opacity but not files?").
- * `muted` stays a prop for other callers; the file rows no longer pass it.
+ * open-sided container when the columns do not fill the box (Finder closes it); and ONE ink for
+ * folders and files — the fill alone marks selection ("why is folder full opacity but not
+ * files?"). `muted` stays a prop for other callers; the file rows no longer pass it.
+ * NO ROW DIVIDERS (BrowsePageRulingsAndSeams, kol-r2b2 2026-09-02): the `border-b last:border-b-0
+ * only:border-b` utilities and their inline `borderColor` are gone. The row is a PILL now — a
+ * constant 4px inset on every row so selecting never shifts the layout, radius-sm on the fill —
+ * and a hairline under a rounded pill draws the box the pill is trying not to be. The shape lives
+ * in kol-components-molecules.css with the fill, not as utilities racing it (ARCHITECTURE §5);
+ * this supersedes the `only:` hairline half of the 08-28 corrections, by the same repo's ruling.
  * STATE CLASSES (ColumnBrowserSeams, kol-r2b2 2026-08-28): `is-selected` / `is-cursor` on the row,
  * and the fill LIVES IN THE THEME now (kol-components-molecules.css) instead of a `bg-fg-04`
  * utility — the only hook a consumer had for "selected" was that utility, and a restyle that
@@ -111,11 +120,10 @@ function Row({ icon, label, active, cursor = false, trailing, onClick, muted = f
       /* Row metrics are the DS Table's (kol-components-organisms.css .kol-table-cell-*):
        * 12px 16px padding, mono 12, an oq-08 hairline between rows, none after the last. */
       /* `cursor` = the keyboard row, drawn with the hover fill so ↑/↓ always shows where you are. */
-      className={`kol-column-browser-row flex items-center gap-2 px-4 py-3 border-b last:border-b-0 only:border-b cursor-pointer transition-colors${
+      className={`kol-column-browser-row flex items-center gap-2 px-4 py-3 cursor-pointer transition-colors${
         active ? ' is-selected' : ''}${cursor ? ' is-cursor' : ''} ${
         active || cursor || !muted ? 'text-fg-default' : 'text-fg-48'
       }`}
-      style={{ borderColor: 'var(--kol-oq-08)' }}
       onClick={onClick}
     >
       <span className="w-5 shrink-0 flex items-center justify-center text-fg-48">
@@ -190,12 +198,28 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview, width
 }
 
 /* one edge handle: captures the pointer, reports the delta along its axis;
- * `is-dragging` keeps the wash on while the pointer is captured */
+ * `is-dragging` keeps the pill lit while the pointer is captured.
+ *
+ * THE PILL FOLLOWS THE POINTER (BrowsePageRulingsAndSeams, kol-r2b2 2026-09-02,
+ * user ruling). It used to sit dead centre and wake on :hover — the theme's own
+ * comment said pointer-following "was built and rejected", while the SAME
+ * gesture had shipped on the rail's grab edge the same day and has run in
+ * kol-r2b2 since. `useGrabEdge` is that implementation; this is the second
+ * consumer of it, which is why the hook grew an `axis` rather than a fork.
+ *
+ * The handle's axis is named for what it RESIZES — `x` drags the column's width
+ * — and the pill on it travels the other way, down the vertical edge. So the
+ * `x` handle takes `axis: 'y'` and the `y` handle `axis: 'x'`: the hook's axis
+ * is the pill's travel, not the drag. Getting this pair backwards is the one
+ * easy mistake here. */
 function ResizeHandle({ axis, onDrag, onEnd }) {
   const [dragging, setDragging] = useState(false)
   const start = useRef(null)
+  const ref = useRef(null)
+  useGrabEdge(ref, { axis: axis === 'x' ? 'y' : 'x' })
   return (
     <div
+      ref={ref}
       className={`kol-column-browser-resize-${axis} ${dragging ? 'is-dragging' : ''}`.trim()}
       role="separator"
       aria-orientation={axis === 'x' ? 'vertical' : 'horizontal'}

package/src/organisms/MediaLibraryPages.jsx

@@ -223,13 +223,13 @@ function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl, downl
 /* Display settings for the ACTIVE bucket — kol-r2b2's drawer wiring on the DS
  * organism (the composition the user locked 2026-08-27). Every control sets a
  * default, never a gate. */
-function MediaSettings({ bucketMeta, settings, onChange, onReset, onClose, profile }) {
+function MediaSettings({ bucketMeta, settings, onChange, onReset, onClose, profile, settingsFooter }) {
   const set = (patch) => onChange({ ...settings, ...patch })
   const toggleKind = (k) => set({ kinds: settings.kinds.includes(k) ? settings.kinds.filter((x) => x !== k) : [...settings.kinds, k] })
   const noVariants = profile.variantSets === 0
   const noSegments = profile.segments === 0
   return (
-    <SettingsPanel variant="drawer" title="Display settings" onClose={onClose} footer={<SettingsFooter onReset={onReset} />}>
+    <SettingsPanel variant="drawer" title="Display settings" onClose={onClose} footer={<SettingsFooter onReset={onReset}>{settingsFooter}</SettingsFooter>}>
       <LabeledControlSection label="Structure" rowGap={1} divided>
         <SettingsRow label="Columns" hint="Finder-style columns instead of folder rows">
           <SettingsSwitch label="Columns" on={(settings.folderView ?? 'rows') === 'columns'} onChange={(v) => set({ folderView: v ? 'columns' : 'rows' })} />
@@ -299,7 +299,7 @@ const profileOf = (objects, rawFiles, systemCount) => ({
 /* ══ BROWSE — folder / files ═══════════════════════════════════════════════ */
 export function MediaLibraryBrowse({
   client, title = 'MEDIA', bucket, onBucketChange, prefix: prefixProp, onPrefix, defaults, settings: settingsProp, onSettingsChange,
-  folderTree, headerActions, refreshKey, onOpen, autoFocus = false, className = '',
+  folderTree, headerActions, refreshKey, onOpen, autoFocus = false, settingsFooter, className = '',
 }) {
   const [ownPrefix, setOwnPrefix] = useState('')
   const prefix = prefixProp ?? ownPrefix
@@ -399,7 +399,7 @@ export function MediaLibraryBrowse({
             onNext={() => setQuickLook((q) => ({ ...q, index: (q.index + 1) % q.files.length }))} />
         )}
         {settingsOpen && (
-          <MediaSettings bucketMeta={bucketMeta} settings={settings} profile={profile} onChange={setSettings} onReset={() => setSettings(null)} onClose={() => setSettingsOpen(false)} />
+          <MediaSettings bucketMeta={bucketMeta} settings={settings} profile={profile} onChange={setSettings} onReset={() => setSettings(null)} onClose={() => setSettingsOpen(false)} settingsFooter={settingsFooter} />
         )}
 
         {folderView === 'columns' ? (
@@ -468,7 +468,7 @@ export function MediaLibraryBrowse({
 /* ══ LIBRARY — the content-filters wall ═══════════════════════════════════ */
 export function MediaLibraryLibrary({
   client, title = 'MEDIA', bucket, onBucketChange, prefix = '', defaults, settings: settingsProp, onSettingsChange,
-  headerActions, refreshKey, header = true, stats = true, className = '',
+  headerActions, refreshKey, header = true, stats = true, settingsFooter, className = '',
 }) {
   const [ownBucket, setOwnBucket] = useState(bucket)
   const bucketId = bucket ?? ownBucket
@@ -633,7 +633,7 @@ export function MediaLibraryLibrary({
           onBucket={(v) => { if (v === 'all') return; if (bucket == null) setOwnBucket(v); onBucketChange?.(v) }} onSettings={() => setSettingsOpen(true)} />
       )}
       {settingsOpen && (
-        <MediaSettings bucketMeta={bucketMeta} settings={settings} profile={profile} onChange={setSettings} onReset={() => setSettings(null)} onClose={() => setSettingsOpen(false)} />
+        <MediaSettings bucketMeta={bucketMeta} settings={settings} profile={profile} onChange={setSettings} onReset={() => setSettings(null)} onClose={() => setSettingsOpen(false)} settingsFooter={settingsFooter} />
       )}
 
       {/* `stats={false}` (ColumnBrowserSeams, kol-r2b2 2026-08-28) — beside `header={false}`: a browse

package/src/organisms/SettingsPanel.jsx

@@ -238,12 +238,23 @@ export function SettingsChipRow({ options = [], selected = [], onToggle, allChip
 
 /** SettingsFooter — a Divider, then one `IconFrame refresh` (primary · sm) at the
  *  right = reset to defaults (SettingsPanelApproved, 2026-08-27). No status word,
- *  no text button. `customised` is accepted for compatibility and unused. */
-export function SettingsFooter({ onReset, resetLabel = 'Reset to defaults' }) {
+ *  no text button. `customised` is accepted for compatibility and unused.
+ *
+ *  `children` ride the SAME row, before reset (BrowsePageRulingsAndSeams,
+ *  kol-r2b2 2026-09-02): a consumer wanting one more control in that footer had
+ *  no way in, so kol-r2b2 ran a `MutationObserver` on `document.body` watching
+ *  for `[aria-label="Reset to defaults"]` and portalled a theme chip into its
+ *  parent — a copy string in a `querySelector`, watching the whole document, to
+ *  place one button. The slot is the seam that ends it.
+ *
+ *  `gap-2` on the row (user 2026-08-28): `flex justify-end` with no gap is right
+ *  for one control and wrong for two — the chip and the reset icon touched. */
+export function SettingsFooter({ onReset, resetLabel = 'Reset to defaults', children }) {
   return (
     <div className="flex flex-col gap-4">
       <Divider />
-      <div className="flex justify-end">
+      <div className="flex justify-end items-center gap-2">
+        {children}
         {onReset && <IconFrame name="refresh" variant="primary" size="sm" onClick={onReset} title={resetLabel} aria-label={resetLabel} />}
       </div>
     </div>