@kolkrabbi/kol-component 0.111.0 → 0.113.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.111.0",
+  "version": "0.113.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/useTilt.js

@@ -13,19 +13,36 @@ import { useMotionValue, useSpring, useTransform } from 'framer-motion'
  *
  * Defaults are the design: tilt ±4°, spring 350/35, perspective 700,
  * rest position center (0.5/0.5).
+ *
+ * `grounded` (ShelfCardTiltWrapsCard, kol-website 2026-08-27 — lifted out of
+ * TiltCardInner so the shelf and the card share ONE feel, no new component):
+ * the "planted at the bottom" tilt — targets snapped to 3 zones, rescaled to
+ * ±2.5°, chased by a lazy spring (250/25/0.6), rotateX clamped to min(0, …) so
+ * it only ever tilts back, pivoting about `center bottom`.
  */
 export default function useTilt({
   magnitude = 4,
   perspective = 700,
   stiffness = 350,
   damping = 35,
+  grounded = false,
 } = {}) {
   const ref = useRef(null)
   const mouseX = useMotionValue(0.5)
   const mouseY = useMotionValue(0.5)
 
-  const rotateX = useSpring(useTransform(mouseY, [0, 1], [magnitude, -magnitude]), { stiffness, damping })
-  const rotateY = useSpring(useTransform(mouseX, [0, 1], [-magnitude, magnitude]), { stiffness, damping })
+  const springX = useSpring(useTransform(mouseY, [0, 1], [magnitude, -magnitude]), { stiffness, damping })
+  const springY = useSpring(useTransform(mouseX, [0, 1], [-magnitude, magnitude]), { stiffness, damping })
+
+  /* the grounded springs always exist (hooks are unconditional) and are only
+   * SELECTED when asked for — a free tilt pays two idle springs, nothing more */
+  const zones = 3
+  const snap = (v) => Math.round(v * zones) / zones
+  const lazy = { stiffness: 250, damping: 25, mass: 0.6 }
+  const lazyX = useSpring(useTransform(springX, (v) => Math.min(0, snap(-v / magnitude) * 2.5)), lazy)
+  const lazyY = useSpring(useTransform(springY, (v) => snap(v / magnitude) * 2.5), lazy)
+  const rotateX = grounded ? lazyX : springX
+  const rotateY = grounded ? lazyY : springY
 
   const onMouseMove = (e) => {
     const rect = ref.current?.getBoundingClientRect()
@@ -41,7 +58,13 @@ export default function useTilt({
 
   return {
     ref,
-    style: { rotateX, rotateY, transformStyle: 'preserve-3d', transformPerspective: perspective },
+    style: {
+      rotateX,
+      rotateY,
+      transformStyle: 'preserve-3d',
+      transformPerspective: perspective,
+      ...(grounded ? { transformOrigin: 'center bottom' } : null),
+    },
     onMouseMove,
     onMouseLeave,
     motionValues: { mouseX, mouseY, rotateX, rotateY },

package/src/index.js

@@ -137,7 +137,7 @@ export { default as LoaderOverlay } from './utilities/LoaderOverlay.jsx'
 export { default as MediaLibrary, MediaLibraryProvider, useMediaLibrary, MediaPicker, MediaBrowser } from './organisms/MediaLibrary.jsx'
 export { default as MediaTileGallery } from './organisms/MediaTileGallery.jsx'
 export { default as MediaViewer } from './organisms/MediaViewer.jsx'
-export { default as SettingsPanel, SettingsSection, SettingsRow, SettingsSwitch, SettingsChoice, SettingsMulti, SettingsChipRow, SettingsFooter } from './organisms/SettingsPanel.jsx'
+export { default as SettingsPanel, LabeledControlSection, SettingsRow, SettingsSwitch, SettingsChoice, SettingsMulti, SettingsChipRow, SettingsFooter } from './organisms/SettingsPanel.jsx'
 export { default as SectionNewsletter } from './organisms/SectionNewsletter.jsx'
 export { default as NewsletterBand } from './organisms/NewsletterBand.jsx'
 export { default as ColumnBrowser } from './organisms/ColumnBrowser.jsx'

package/src/molecules/TiltBento.jsx

@@ -90,12 +90,16 @@ function Media({ src, poster, className }) {
  * @param {ReactNode} description    hover-revealed paragraph
  * @param {string}    href           CTA target; `http*`/`mailto` → new-tab anchor, else same-tab (onNavigate seam)
  * @param {Function}  onNavigate     (event) => void — same-tab CTA click seam (SPA intercept)
- * @param {ReactNode} buttonLabel    CTA label (no default — author it)
+ * @param {ReactNode} buttonLabel    CTA label — NO DEFAULT, BY DESIGN: an `href` with no label is a
+ *                                   call-site bug, not a gap (the retired kol-website fork defaulted
+ *                                   'View Project'; TiltBentoVoiceAndDefaults 2026-08-27)
  * @param {ReactNode} bodyContent    extra content injected into the stack
  * @param {number}    overlayOpacity scrim darkness % over the media, 0 disables (default 60)
  * @param {boolean}   alignRight     right-align the card (ms-auto) vs fill (size-full)
  * @param {boolean}   enableTilt     master tilt switch (default true)
- * @param {string}    titleClassName title classes
+ * @param {string}    titleClassName title classes — the family default is `kol-sans-heading-01
+ *                                   text-absolute-white` (confirmed 2026-08-27; the fork's was
+ *                                   heading-02 uppercase — a consumer wanting that passes it)
  * @param {string}    contentClassName inner content-box classes
  * @param {string}    imageClassName media fit/position classes
  * @param {string}    contentStackClassName stack layout classes
@@ -166,7 +170,10 @@ export default function TiltBento({
           )}
           <div className={contentStackClassName}>
             {title && <h3 className={titleClassName}>{title}</h3>}
-            {subtitle && <p className={`kol-mono-text text-absolute-white ${revealClass}`}>{subtitle}</p>}
+            {/* kol-mono-14 — one rung above the mono-12 description, as the retired
+              * fork drew it (TiltBentoVoiceAndDefaults, kol-website 2026-08-27: this
+              * rode `kol-mono-text`, a class retired from the theme — zero rules emitted) */}
+            {subtitle && <p className={`kol-mono-14 text-absolute-white ${revealClass}`}>{subtitle}</p>}
             {description && <p className={`kol-mono-12 text-absolute-white pb-6 ${revealClass}`}>{description}</p>}
             {bodyContent}
             {href && (

package/src/organisms/ColumnBrowser.jsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from 'react'
+import { Fragment, useEffect, useRef, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
 import KindPreview from '../molecules/KindPreview.jsx'
 import { formatLength } from '../molecules/AudioPreview.jsx'
@@ -27,7 +27,14 @@ import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/me
  * 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".
- * Height is fixed at 528px = 12 rows × 44px (user ruling); columns scroll.
+ * 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.
  *
  * 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
@@ -45,6 +52,11 @@ import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/me
  * @param {Function} formatSize   (bytes) => string
  * @param {Function} partition    (objects, level) => { folders: string[], files: object[] }
  * @param {Function} renderPreview  (file) => ReactNode — replaces the preview column's media frame (the facts stay — Dimensions and Length are read off whatever <img> / <video> / <audio> the node loads); without it images render the organism's <img>, everything else the DS KindPreview
+ * @param {number}   height         controlled height in px (omit for uncontrolled)
+ * @param {number}   defaultHeight  uncontrolled start height (528); min 240
+ * @param {Function} onHeightChange (px) => void — on every drag step; the consumer persists it
+ * @param {number}   columnWidth    every column's start width (260); the preview column starts at 320; min 160
+ * @param {Function} onColumnResize (index, px) => void — the column's index, or `'preview'`
  * @param {string}   className    extra classes on the browser
  */
 
@@ -96,7 +108,7 @@ function Row({ icon, label, active, cursor = false, trailing, onClick, muted = f
   )
 }
 
-function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
+function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview, width }) {
   // Pixel size and length come from the loaded media itself — the bucket stores
   // none. `{ w, h }` off an <img> load, `{ w, h, len }` off a <video>'s and
   // `{ len }` off an <audio>'s loadedmetadata (ColumnBrowserMediaFacts, kol-r2b2
@@ -115,7 +127,7 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
     ['Date', o.uploaded ? new Date(o.uploaded).toISOString().slice(0, 10) : '—'],
   ]
   return (
-    <div className="kol-column-browser-preview w-[320px] shrink-0 overflow-y-auto p-4 flex flex-col gap-4">
+    <div className="kol-column-browser-preview shrink-0 overflow-y-auto p-4 flex flex-col gap-4" style={{ width }}>
       {/* the media frame: an image is the organism's own <img> (it reads the
         * dimensions); anything else is `renderPreview(o)` or the DS KindPreview
         * (video · audio · code · text — SettingsPanelChromeAndColumnPreview,
@@ -158,6 +170,28 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
   )
 }
 
+/* one edge handle: captures the pointer, reports the delta along its axis;
+ * `is-dragging` keeps the wash on while the pointer is captured */
+function ResizeHandle({ axis, onDrag, onEnd }) {
+  const [dragging, setDragging] = useState(false)
+  const start = useRef(null)
+  return (
+    <div
+      className={`kol-column-browser-resize-${axis} ${dragging ? 'is-dragging' : ''}`.trim()}
+      role="separator"
+      aria-orientation={axis === 'x' ? 'vertical' : 'horizontal'}
+      onPointerDown={(e) => { e.preventDefault(); e.currentTarget.setPointerCapture(e.pointerId); start.current = axis === 'x' ? e.clientX : e.clientY; setDragging(true) }}
+      onPointerMove={(e) => { if (start.current == null) return; onDrag((axis === 'x' ? e.clientX : e.clientY) - start.current) }}
+      onPointerUp={(e) => { e.currentTarget.releasePointerCapture(e.pointerId); start.current = null; setDragging(false); onEnd?.() }}
+      onPointerCancel={() => { start.current = null; setDragging(false); onEnd?.() }}
+    />
+  )
+}
+
+const MIN_H = 240
+const MIN_W = 160
+const PREVIEW_W = 320
+
 export default function ColumnBrowser({
   objects = [],
   prefix = '',
@@ -171,8 +205,33 @@ export default function ColumnBrowser({
   formatSize = defaultFormatSize,
   partition = defaultPartition,
   renderPreview,
+  height,
+  defaultHeight = 528,
+  onHeightChange,
+  columnWidth = 260,
+  onColumnResize,
   className = '',
 }) {
+  /* height: controlled-or-uncontrolled like Slider; widths: organism-internal,
+   * by column index (the preview keyed apart), seeded from `columnWidth` */
+  const [ownH, setOwnH] = useState(defaultHeight)
+  const h = height ?? ownH
+  const [widths, setWidths] = useState({})
+  const widthOf = (i) => widths[i] ?? (i === 'preview' ? PREVIEW_W : columnWidth)
+  const dragBase = useRef(null)
+  const resizeCol = (i) => (dx) => {
+    if (dragBase.current == null) dragBase.current = widthOf(i)
+    const w = Math.max(MIN_W, Math.round(dragBase.current + dx))
+    setWidths((prev) => (prev[i] === w ? prev : { ...prev, [i]: w }))
+    onColumnResize?.(i, w)
+  }
+  const resizeH = (dy) => {
+    if (dragBase.current == null) dragBase.current = h
+    const next = Math.max(MIN_H, Math.round(dragBase.current + dy))
+    if (height == null) setOwnH(next)
+    onHeightChange?.(next)
+  }
+  const endDrag = () => { dragBase.current = null }
   const [picked, setPicked] = useState(null)
   /* `onPick` (ColumnBrowserOnPick, kol-r2b2 2026-08-27): the picked file, for
    * a Finder-style breadcrumb — fired whenever it changes; a folder pick or an
@@ -304,19 +363,22 @@ export default function ColumnBrowser({
       ref={rootRef}
       tabIndex={0}
       onKeyDown={onKeyDown}
-      // Fixed height — 12 rows of 44px (user ruling 2026-08-27), so the browser never jumps as columns change; each column scrolls.
-      className={`kol-column-browser flex overflow-x-auto h-[528px] border rounded outline-none ${className}`.trim()}
-      style={{ borderColor: 'var(--kol-oq-08)' }}
+      // 12 rows of 44px by default (user ruling 2026-08-27), so the browser never jumps as columns change; each column scrolls.
+      // The scroll box is the INNER flex row: the bottom handle is absolute on this root, so it spans the visible width, not the scrolled one.
+      className={`kol-column-browser relative border rounded outline-none ${className}`.trim()}
+      style={{ borderColor: 'var(--kol-oq-08)', height: h }}
     >
+      <div className="flex h-full overflow-x-auto">
       {levels.map((level, k) => {
         const { folders, files } = partition(objects.filter((o) => o.key.startsWith(level)), level)
         const next = levels[k + 1]
         const activeFolder = next ? next.slice(level.length) : null
+        const last = k === levels.length - 1 && !shown
         return (
+          <Fragment key={level || '/'}>
           <ul
-            key={level || '/'}
-            className="kol-column-browser-column w-[260px] shrink-0 overflow-y-auto border-r last:border-r-0"
-            style={{ borderColor: 'var(--kol-oq-08)' }}
+            className={`kol-column-browser-column shrink-0 overflow-y-auto ${last ? '' : 'border-r'}`.trim()}
+            style={{ borderColor: 'var(--kol-oq-08)', width: widthOf(k) }}
           >
             {folders.map((f, i) => (
               <Row
@@ -344,9 +406,18 @@ export default function ColumnBrowser({
               <li className="kol-mono-12 text-fg-32 px-4 py-3">empty</li>
             )}
           </ul>
+          <ResizeHandle axis="x" onDrag={resizeCol(k)} onEnd={endDrag} />
+          </Fragment>
         )
       })}
-      {shown && <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} renderPreview={renderPreview} />}
+      {shown && (
+        <>
+          <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} renderPreview={renderPreview} width={widthOf('preview')} />
+          <ResizeHandle axis="x" onDrag={resizeCol('preview')} onEnd={endDrag} />
+        </>
+      )}
+      </div>
+      <ResizeHandle axis="y" onDrag={resizeH} onEnd={endDrag} />
     </div>
   )
 }

package/src/organisms/SettingsPanel.jsx

@@ -130,11 +130,15 @@ export function SettingsSwitch({ on = false, onChange, disabled = false, disable
   )
 }
 
-/** SettingsSection — a section of the panel (SettingsPanelApproved, 2026-08-27):
- *  the EYEBROW (`kol-eyebrow text-fg-80`) standing apart from the rows (gap-3),
- *  the rows in their own stack — `rowGap` 1 for switch rows (24 tall already),
- *  2 for dropdown rows. `divided` = a hairline above (between sections). */
-export function SettingsSection({ label, divided = false, rowGap = 2, children, className = '' }) {
+/** LabeledControlSection — a section of LabeledControls: the EYEBROW
+ *  (`kol-eyebrow text-fg-80`) standing apart from the rows (gap-3), the rows in
+ *  their own stack — `rowGap` 1 for switch rows (24 tall already), 2 for
+ *  dropdown rows. `divided` = a hairline above (between sections).
+ *  Was `SettingsSection` until 2026-08-27 (LabeledControlSection, kol-r2b2 —
+ *  user ruling: it named the place it was first used, not what it is; kol-fxr
+ *  took it for a params rail the same day). RENAMED, NO ALIAS — the render is
+ *  the 0.104.0 locked composition, untouched. */
+export function LabeledControlSection({ label, divided = false, rowGap = 2, children, className = '' }) {
   return (
     <div className={`flex flex-col gap-3 ${divided ? 'kol-section--divided' : ''} ${className}`.replace(/\s+/g, ' ').trim()}>
       {label && <p className="kol-eyebrow text-fg-80">{label}</p>}

package/src/utilities/TiltCard.jsx

@@ -1,4 +1,4 @@
-import { motion, useSpring, useTransform } from 'framer-motion'
+import { motion } from 'framer-motion'
 import useTilt from '../hooks/useTilt.js'
 import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 import useCoarsePointer from '../hooks/useCoarsePointer.js'
@@ -65,36 +65,16 @@ export default function TiltCard({
 }
 
 function TiltCardInner({ src, alt, className, variant, magnitude, perspective, children }) {
-  const tilt = useTilt({ magnitude, perspective })
-  const grounded = variant === 'grounded'
-
-  /* Zone-based tilt: normalize the spring output back to -1..1, snap it to
-   * 3 zones, rescale to ±2.5°, and let a slower lazy spring catch up so the
-   * card lags and settles into quantized angles. rotateX is clamped to
-   * min(0, …) — grounded cards only ever tilt back. */
-  const zones = 3
-  const snap = (v) => Math.round(v * zones) / zones
-  const lazySpring = { stiffness: 250, damping: 25, mass: 0.6 }
-
-  const targetX = useTransform(tilt.motionValues.rotateX, (v) =>
-    grounded ? Math.min(0, snap(-v / magnitude) * 2.5) : v,
-  )
-  const targetY = useTransform(tilt.motionValues.rotateY, (v) =>
-    grounded ? snap(v / magnitude) * 2.5 : v,
-  )
-
-  const lazyRotateX = useSpring(targetX, lazySpring)
-  const lazyRotateY = useSpring(targetY, lazySpring)
-
-  const style = grounded
-    ? { ...tilt.style, rotateX: lazyRotateX, rotateY: lazyRotateY, transformOrigin: 'center bottom' }
-    : tilt.style
+  /* the grounded feel — zones, ±2.5°, the lazy spring, the bottom pivot — lives
+   * in useTilt now (ShelfCardTiltWrapsCard, 2026-08-27), so the shelf's card
+   * wrapper and this frame are one motion, not two copies of eight lines */
+  const tilt = useTilt({ magnitude, perspective, grounded: variant === 'grounded' })
 
   return (
     <motion.div
       ref={tilt.ref}
       className={`relative ${className}`}
-      style={style}
+      style={tilt.style}
       onMouseMove={tilt.onMouseMove}
       onMouseLeave={tilt.onMouseLeave}
     >