@kolkrabbi/kol-component 0.95.0 → 0.96.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.95.0",
+  "version": "0.96.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.18.0"
+    "@kolkrabbi/kol-icons": "^0.19.0"
   },
   "files": [
     "src",

package/src/index.js

@@ -140,6 +140,7 @@ export { default as MediaViewer } from './organisms/MediaViewer.jsx'
 export { default as SettingsPanel, SettingsRow, SettingsSwitch, SettingsChoice, 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'
 export { default as RecordManager } from './organisms/RecordManager.jsx'
 export { default as SpectrumGrid } from './organisms/SpectrumGrid.jsx'
 export { default as Table } from './organisms/Table.jsx'

package/src/molecules/ContentCard.jsx

@@ -40,7 +40,10 @@ const RATIOS = {
 /* ruled box values per variant, verbatim from the §3 reference cards —
  * paddings in tokens: pad-card-sm 12 · pad-card-md 16 · pad-card-lg 24 */
 const BOX = {
-  default:  { layout: 'stack', border: 'var(--kol-fg-12)', bg: 'var(--kol-fg-02)', pad: 'var(--kol-pad-card-sm)' },
+  /* no border (ColumnBrowser round, user 2026-08-27: "I don't like the border, I feel
+   * like I've said that before" — the ListingCardThumbBorder ruling): the selected
+   * state reads from the checked ToggleCheckbox, not a fg-64 border */
+  default:  { layout: 'stack', border: null, bg: 'var(--kol-fg-02)', pad: 'var(--kol-pad-card-sm)' },
   catalog:  { layout: 'fill-card', border: 'var(--kol-fg-04)', bg: 'var(--kol-fg-04)', pad: 'var(--kol-pad-card-sm) var(--kol-pad-card-md)', plateTop: true, plateBg: 'var(--kol-surface-primary)' },
   /* flip: PrintGridCard's 3D turn on `isFlipped` → `selected` (ContentRowsAndPrintCard, 2026-08-27) */
   print:    { layout: 'fill-card', border: null, bg: 'var(--kol-surface-secondary)', pad: 'var(--kol-pad-card-sm) var(--kol-pad-card-md)', plateTop: true, flip: true },

package/src/molecules/ContentMedia.jsx

@@ -70,8 +70,9 @@ import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
  * @param {ReactNode} children  the real media
  */
 const FIT = {
-  cover:   '[&>img]:h-full [&>img]:w-full [&>img]:object-cover [&>video]:h-full [&>video]:w-full [&>video]:object-cover',
-  natural: '[&>img]:h-full [&>img]:w-full [&>img]:object-contain [&>video]:h-full [&>video]:w-full [&>video]:object-contain',
+  /* a consumer WRAPPER div fills the frame as an img/video does (ColumnBrowser round, 2026-08-27 — kol-r2b2's wrapped thumb fell back to the image's intrinsic size) */
+  cover:   '[&>img]:h-full [&>img]:w-full [&>img]:object-cover [&>video]:h-full [&>video]:w-full [&>video]:object-cover [&>div]:h-full [&>div]:w-full',
+  natural: '[&>img]:h-full [&>img]:w-full [&>img]:object-contain [&>video]:h-full [&>video]:w-full [&>video]:object-contain [&>div]:h-full [&>div]:w-full',
   compact: 'grid place-items-center [&>img]:max-h-[70%] [&>img]:max-w-[70%] [&>img]:object-contain',
 }
 

package/src/organisms/ColumnBrowser.jsx

@@ -0,0 +1,288 @@
+import { useEffect, useRef, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-icons'
+
+/**
+ * ColumnBrowser — Finder-style Miller columns over a flat key space (kol-r2b2's
+ * `src/ColumnBrowser.jsx`, built and ruled there first — user 2026-08-27: "make
+ * it locally first, then ship it" — and shipped verbatim; ticket ColumnBrowser).
+ * The listing surface's FOLDER view: it replaces the folder rows above the
+ * files, it is not a card layout.
+ *
+ * One column per path segment of `prefix`: column 0 is the root level, column
+ * k the contents of the k-th folder on the path. Picking a folder sets the
+ * prefix to it (and so truncates deeper columns); picking a file highlights it
+ * and opens a PREVIEW column on the right — the image and its facts, as Finder
+ * does.
+ *
+ * Keyboard, Finder's: ↑/↓ move within the column (a folder opens its column as
+ * you land on it, a file previews), → steps into the open folder's column,
+ * ← steps back to the parent column. Space = Quick Look: `onQuickLook({ files,
+ * index })` over the column's files; while it is open ↑/↓ step the file off
+ * `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".
+ * Height is fixed at 528px = 12 rows × 44px (user ruling); columns scroll.
+ *
+ * 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
+ * `contentType`), `kindLabel`, `formatSize`, `partition(objects, level)`.
+ *
+ * @param {Array<{key: string, size?: number, uploaded?: string, contentType?: string}>} objects  the flat key space
+ * @param {string}   prefix       the open folder path ('' = root, 'a/b/' = two deep)
+ * @param {Function} onPrefix     (prefix) => void
+ * @param {{files: object[], index: number}|null} quickLook   the open Quick Look, or null
+ * @param {Function} onQuickLook  (quickLook|null) => void — space opens / closes, ↑/↓ step while open
+ * @param {Function} urlOf        (o) => string — the object's public URL for the preview image
+ * @param {Function} kindOf       (o) => 'image' | 'video' | 'audio' | string
+ * @param {Object}   kindLabel    kind → label shown when there is no visual preview
+ * @param {Function} formatSize   (bytes) => string
+ * @param {Function} partition    (objects, level) => { folders: string[], files: object[] }
+ * @param {string}   className    extra classes on the browser
+ */
+
+const defaultKindOf = (o) => {
+  const ct = o.contentType || ''
+  if (ct.startsWith('image/')) return 'image'
+  if (ct.startsWith('video/')) return 'video'
+  if (ct.startsWith('audio/')) return 'audio'
+  return 'file'
+}
+const DEFAULT_KIND_LABEL = { image: 'image', video: 'video', audio: 'audio', file: 'file' }
+const defaultFormatSize = (bytes) => {
+  if (bytes == null) return '—'
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
+  return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`
+}
+/* kol-r2b2's partition: the next path segment is a folder, the rest are files */
+const defaultPartition = (objects, prefix) => {
+  const folderSet = new Set()
+  const files = []
+  for (const o of objects) {
+    const rel = prefix ? o.key.slice(prefix.length) : o.key
+    const slash = rel.indexOf('/')
+    if (slash !== -1) folderSet.add(rel.slice(0, slash + 1))
+    else files.push({ ...o, displayKey: o.displayKey ?? rel })
+  }
+  return { folders: [...folderSet].sort(), files }
+}
+const isImage = (o) => (o.contentType || '').startsWith('image/')
+
+/* kol-icons has no `audio` glyph yet — audio rows wear `file` until it does */
+const COL_ICON = { image: 'image', video: 'video', audio: 'file' }
+
+function Row({ icon, label, active, cursor = false, trailing, onClick, muted = false }) {
+  return (
+    <li
+      /* 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 cursor-pointer transition-colors ${
+        active || cursor ? 'bg-fg-04 text-fg-default' : muted ? 'text-fg-48 hover:bg-fg-04' : 'text-fg-default hover:bg-fg-04'
+      }`}
+      style={{ borderColor: 'var(--kol-oq-08)' }}
+      onClick={onClick}
+    >
+      <span className="w-5 shrink-0 flex items-center justify-center text-fg-48">
+        <Icon name={icon} size={14} />
+      </span>
+      <span className="kol-mono-12 flex-1 truncate">{label}</span>
+      {trailing}
+    </li>
+  )
+}
+
+function Preview({ o, urlOf, kindOf, kindLabel, formatSize }) {
+  // Pixel size comes from the loaded image itself — the bucket stores none.
+  const [dims, setDims] = useState(null)
+  const src = isImage(o) ? urlOf?.(o) : null
+  const facts = [
+    ['Kind', kindLabel[kindOf(o)] || 'file'],
+    ['Type', o.contentType || '—'],
+    ['Size', formatSize(o.size)],
+    ...(src ? [['Dimensions', dims ? `${dims.w} × ${dims.h} px` : '…']] : []),
+    ['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="w-full aspect-square bg-fg-04 rounded flex items-center justify-center overflow-hidden">
+        {src ? (
+          <img
+            src={src}
+            alt=""
+            className="max-w-full max-h-full object-contain"
+            loading="lazy"
+            onLoad={(e) => setDims({ w: e.target.naturalWidth, h: e.target.naturalHeight })}
+          />
+        ) : (
+          <span className="kol-mono-12 text-fg-48">{kindLabel[kindOf(o)] || 'file'}</span>
+        )}
+      </div>
+      <p className="kol-mono-12 text-fg-default break-all">{o.displayKey ?? o.key}</p>
+      <dl className="flex flex-col gap-1">
+        {facts.map(([k, v]) => (
+          <div key={k} className="flex justify-between gap-4 kol-mono-12">
+            <dt className="text-fg-48">{k}</dt>
+            <dd className="text-fg-default text-right break-all">{v}</dd>
+          </div>
+        ))}
+      </dl>
+    </div>
+  )
+}
+
+export default function ColumnBrowser({
+  objects = [],
+  prefix = '',
+  onPrefix = () => {},
+  quickLook = null,
+  onQuickLook,
+  urlOf,
+  kindOf = defaultKindOf,
+  kindLabel = DEFAULT_KIND_LABEL,
+  formatSize = defaultFormatSize,
+  partition = defaultPartition,
+  className = '',
+}) {
+  const [picked, setPicked] = useState(null)
+  // Keyboard cursor: which column, which row. Clicks keep it in sync.
+  const [cursor, setCursor] = useState({ col: 0, idx: 0 })
+  const rootRef = useRef(null)
+
+  const levelsOf = (pfx) => {
+    const out = ['']
+    if (pfx) {
+      const segs = pfx.replace(/\/$/, '').split('/')
+      segs.forEach((_, i) => out.push(segs.slice(0, i + 1).join('/') + '/'))
+    }
+    return out
+  }
+  const itemsAt = (level) => {
+    const { folders, files } = partition(objects.filter((o) => o.key.startsWith(level)), level)
+    return [...folders.map((f) => ({ type: 'folder', name: f })), ...files.map((o) => ({ type: 'file', o }))]
+  }
+  const land = (level, item) => {
+    if (!item) return
+    if (item.type === 'folder') { setPicked(null); onPrefix(level + item.name) }
+    else setPicked(item.o)
+  }
+
+  const onKeyDown = (e) => {
+    // Space = Quick Look over the picked column's files, starting at the picked one.
+    if (e.key === ' ' && picked) {
+      e.preventDefault()
+      const siblings = itemsAt(levelsOf(prefix)[cursor.col] ?? '').filter((it) => it.type === 'file').map((it) => it.o)
+      onQuickLook?.({ files: siblings, index: Math.max(0, siblings.findIndex((o) => o.key === picked.key)) })
+      return
+    }
+    if (!['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(e.key)) return
+    e.preventDefault()
+    const lv = levelsOf(prefix)
+    const col = Math.min(cursor.col, lv.length - 1)
+    const items = itemsAt(lv[col])
+    if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
+      const idx = Math.max(0, Math.min(items.length - 1, cursor.idx + (e.key === 'ArrowDown' ? 1 : -1)))
+      setCursor({ col, idx })
+      land(lv[col], items[idx])
+    } else if (e.key === 'ArrowRight') {
+      // Into the open folder's column, first row.
+      if (lv[col + 1]) {
+        const next = itemsAt(lv[col + 1])
+        setCursor({ col: col + 1, idx: 0 })
+        land(lv[col + 1], next[0])
+      }
+    } else if (col > 0) {
+      // Back to the parent column, on the folder we came out of.
+      const parentItems = itemsAt(lv[col - 1])
+      const opened = lv[col].slice(lv[col - 1].length)
+      const idx = Math.max(0, parentItems.findIndex((it) => it.type === 'folder' && it.name === opened))
+      setCursor({ col: col - 1, idx })
+      setPicked(null)
+      onPrefix(lv[col])
+    }
+  }
+  // While Quick Look is open the overlay holds focus, so the same keys are read
+  // off window: ↑/↓ step the picked file (overlay follows), space closes. The
+  // opening keystroke bubbles from this component and is ignored.
+  useEffect(() => {
+    if (!quickLook) return
+    const onKey = (e) => {
+      if (rootRef.current?.contains(e.target)) return
+      if (e.key === ' ') { e.preventDefault(); onQuickLook?.(null); return }
+      if (e.key !== 'ArrowUp' && e.key !== 'ArrowDown') return
+      e.preventDefault()
+      const lv = levelsOf(prefix)
+      const col = Math.min(cursor.col, lv.length - 1)
+      const items = itemsAt(lv[col])
+      let idx = cursor.idx
+      const step = e.key === 'ArrowDown' ? 1 : -1
+      do { idx += step } while (items[idx] && items[idx].type !== 'file')
+      if (!items[idx]) return
+      setCursor({ col, idx })
+      setPicked(items[idx].o)
+      const siblings = items.filter((it) => it.type === 'file').map((it) => it.o)
+      onQuickLook?.({ files: siblings, index: siblings.findIndex((o) => o.key === items[idx].o.key) })
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  })
+
+  const levels = levelsOf(prefix) // '' → ['']; 'a/b/' → ['', 'a/', 'a/b/']
+  // While Quick Look is open the overlay's index is the truth for the highlight.
+  const shown = quickLook ? quickLook.files[quickLook.index] : picked
+
+  return (
+    <div
+      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)' }}
+    >
+      {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
+        return (
+          <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)' }}
+          >
+            {folders.map((f, i) => (
+              <Row
+                key={f}
+                icon="folder"
+                label={f.replace(/\/$/, '')}
+                active={f === activeFolder}
+                cursor={cursor.col === k && cursor.idx === i}
+                trailing={<Icon name="chevron-right" size={12} className="text-fg-32" />}
+                onClick={() => { setCursor({ col: k, idx: i }); rootRef.current?.focus(); setPicked(null); onPrefix(level + f) }}
+              />
+            ))}
+            {files.map((o, i) => (
+              <Row
+                key={o.key}
+                icon={COL_ICON[kindOf(o)] || 'file'}
+                label={o.displayKey ?? o.key}
+                muted={shown?.key !== o.key}
+                active={shown?.key === o.key}
+                cursor={cursor.col === k && cursor.idx === folders.length + i}
+                onClick={() => { setCursor({ col: k, idx: folders.length + i }); rootRef.current?.focus(); setPicked(o) }}
+              />
+            ))}
+            {folders.length === 0 && files.length === 0 && (
+              <li className="kol-mono-12 text-fg-32 px-4 py-3">empty</li>
+            )}
+          </ul>
+        )
+      })}
+      {shown && <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} />}
+    </div>
+  )
+}