@kolkrabbi/kol-component 0.203.0 → 0.204.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.203.0",
+  "version": "0.204.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/organisms/ColumnBrowser.jsx

@@ -71,6 +71,10 @@ import { GRAB_COLUMN } from '../utilities/motion.js'
  * @param {Function} onColumnResize (index, px) => void — the column's index, or `'preview'`
  * @param {string}   className    extra classes on the browser
  *
+ * @param {Function} thumbnailFor  (o) => node — the 44px tile's content below the breakpoint; null falls back to the kind glyph. WHERE a thumbnail comes from is the consumer's: R2 and B2 serve originals, so a 44px tile can mean a 2 MB download
+ * @param {Function} folderMeta  (prefix, view) => string — a folder's own meta line (`date · N items` in list, `N items` in grid). A SEAM, not a computation: counting by prefix is O(n) per folder, and a consumer that already holds a folder tree answers it for free
+ * @param {'list'|'grid'} stackView  the mobile view below the breakpoint (default 'list'); `grid` is 3-up tiles, flat — a grid has nowhere to put an inline child list
+ *
  * BELOW `md` (768) THIS IS A DIFFERENT TREE — one full-width inline-expanding
  * list, not columns (`ColumnBrowserStackMode`, kol-r2b2 2026-09-03, user-ruled
  * inline expand over push). `height` / `defaultHeight` / `onHeightChange`,
@@ -134,13 +138,39 @@ const COL_ICON = { image: 'image', video: 'video', audio: 'file', playlist: 'vid
  * path indents until the name has no room. */
 const INDENT_CAP = 3
 
-function Row({ icon, label, active, cursor = false, trailing, onClick, muted = false, indent = 0, meta }) {
+/* THE FOUR-ZONE ROW (ColumnBrowserMobileViews §1, kol-r2b2 2026-09-03) is the
+ * `zones` form. The first stack build inherited the DS Table's `12px 16px` with
+ * a 14px glyph in a 20px slot, and the user's read was *"kinda underwhelming…
+ * did you even look at the refs?"* — correctly, and the fault was the spec's.
+ * iOS Files and Dropbox both draw four:
+ *
+ *   1 · disclosure  14px, FOLDERS ONLY, its own tap target — tapping it
+ *                   expands in place, tapping the row opens. Without the split
+ *                   there is no way to peek into a folder without leaving the
+ *                   one you are in
+ *   2 · icon        44×44 at radius 5 — a folder glyph, or a real THUMBNAIL
+ *   3 · text        name, then meta beneath
+ *   4 · trailing    20px, the row's own affordance
+ *
+ * Row height follows zone 2: 60px, not the table padding. The divider starts at
+ * zone 3's left edge, not the row's — both references.
+ *
+ * `zones`, `thumb`, `onDisclose`, `disclosed`, `indent` and `meta` are all inert
+ * without the stack: the columns pass none, so a desktop row is byte-identical
+ * to what it was. */
+function Row({
+  icon, label, active, cursor = false, trailing, onClick, muted = false,
+  indent = 0, meta, zones = false, thumb, onDisclose, disclosed,
+}) {
   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. */
+       * 12px 16px padding, mono 12, an oq-08 hairline between rows, none after the last.
+       * The `zones` row sets its own 60px instead — a 44px thumbnail in a
+       * 12px-padded row is three times too airy. */
       /* `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 cursor-pointer transition-colors${
+      className={`kol-column-browser-row flex items-center gap-2 cursor-pointer transition-colors${
+        zones ? ' kol-column-browser-row--zones px-4' : ' px-4 py-3'}${
         active ? ' is-selected' : ''}${cursor ? ' is-cursor' : ''} ${
         active || cursor || !muted ? 'text-fg-default' : 'text-fg-48'
       }`}
@@ -150,12 +180,39 @@ function Row({ icon, label, active, cursor = false, trailing, onClick, muted = f
        * scrollers does not */
       style={indent ? { paddingLeft: `calc(var(--kol-spacing-4) + ${indent} * var(--kol-spacing-5))` } : undefined}
     >
-      <span className="w-5 shrink-0 flex items-center justify-center text-fg-48">
-        <Icon name={icon} size={14} />
-      </span>
+      {/* ZONE 1 — disclosure, its own tap target. A bare span holds the column
+          for files so every icon in the list lands on one x. */}
+      {zones && (onDisclose ? (
+        <button
+          type="button"
+          onClick={(e) => { e.stopPropagation(); onDisclose() }}
+          aria-expanded={!!disclosed}
+          aria-label={disclosed ? 'Collapse folder' : 'Expand folder'}
+          className="kol-column-browser-disclose shrink-0 inline-flex items-center justify-center"
+          style={{ width: 14, alignSelf: 'stretch', color: 'var(--kol-accent-primary)' }}
+        >
+          <Icon name={disclosed ? 'chevron-down' : 'chevron-right'} size={12} />
+        </button>
+      ) : (
+        <span aria-hidden="true" className="shrink-0" style={{ width: 14 }} />
+      ))}
+
+      {/* ZONE 2 — the icon box, or the thumbnail the consumer supplies */}
+      {zones ? (
+        <span
+          className="kol-column-browser-thumb shrink-0 inline-flex items-center justify-center overflow-hidden"
+          style={{ width: 44, height: 44, borderRadius: 5, background: thumb ? 'var(--kol-oq-04)' : 'transparent' }}
+        >
+          {thumb ?? <Icon name={icon} size={20} className="text-fg-48" />}
+        </span>
+      ) : (
+        <span className="w-5 shrink-0 flex items-center justify-center text-fg-48">
+          <Icon name={icon} size={14} />
+        </span>
+      )}
+
+      {/* ZONE 3 — name over meta */}
       {meta ? (
-        /* size · date under the name — there is no preview column at this
-         * width to carry the facts (ColumnBrowserStackMode item 5) */
         <span className="flex-1 min-w-0 flex flex-col gap-0.5">
           <span className="kol-mono-12 truncate">{label}</span>
           <span className="kol-helper-10 text-fg-48 truncate">{meta}</span>
@@ -163,7 +220,9 @@ function Row({ icon, label, active, cursor = false, trailing, onClick, muted = f
       ) : (
         <span className="kol-mono-12 flex-1 truncate">{label}</span>
       )}
-      {trailing}
+
+      {/* ZONE 4 */}
+      {zones ? <span className="shrink-0 inline-flex justify-end" style={{ width: 20 }}>{trailing}</span> : trailing}
     </li>
   )
 }
@@ -292,6 +351,27 @@ export default function ColumnBrowser({
   columnWidth = 260,
   columnWidths,
   onColumnResize,
+  /* THE TWO SEAMS THE MOBILE TICKET'S RULINGS POINT AT (ColumnBrowserMobileViews,
+   * kol-r2b2 2026-09-03). Both are questions the DS must not answer for a
+   * consumer, so neither is computed here:
+   *
+   * `thumbnailFor(o)` — a node for the 44px box, or null for the kind glyph.
+   *   WHERE a thumbnail comes from is the consumer's and it is not free: R2 and
+   *   B2 serve originals, so a 44px tile can mean downloading a 2 MB JPEG. That
+   *   repo's own mitigations (lazy originals, a resolution-set that picks the
+   *   smallest variant) and whether to buy image resizing are its calls.
+   *
+   * `folderMeta(prefix)` — the folder's own meta line, `date · N items` in the
+   *   references. Counting `objects` by prefix is O(n) per folder against a
+   *   3443-object bucket, and that repo already passes a baked folder tree
+   *   carrying files and bytes. A seam, not a computation — the ticket says so
+   *   and it is right. */
+  thumbnailFor,
+  folderMeta,
+  /* `list` (default) or `grid` below the breakpoint — item 14. 3-up, and for a
+   * media bucket the thumbnail IS the tile, so it carries counts and sizes
+   * rather than dates (§2). Above the breakpoint the columns are unaffected. */
+  stackView = 'list',
   autoFocus = false,
   className = '',
 }) {
@@ -525,6 +605,41 @@ export default function ColumnBrowser({
             </span>
           </button>
         )}
+        {stackView === 'grid' ? (
+          /* THE GRID (item 14). Flat — one level at a time, no inline expand:
+             a grid of tiles has nowhere to put a child list, which is why both
+             references drop disclosure in this view and navigate by tap. */
+          <div className="kol-column-browser-grid flex-1 overflow-y-auto">
+            {rows.filter((r) => r.kind !== 'empty').map((r) => {
+              const isFolder = r.kind === 'folder'
+              const o = r.o
+              return (
+                <button
+                  key={r.key}
+                  type="button"
+                  className={`kol-column-browser-tile${!isFolder && shown?.key === o.key ? ' is-selected' : ''}`}
+                  onClick={() => {
+                    if (isFolder) { onPrefix(r.level + r.name); return }
+                    const files = itemsAt(r.level ?? '').filter((it) => it.type === 'file').map((it) => it.o)
+                    pick(o)
+                    onQuickLook?.({ files: files.length ? files : [o], index: Math.max(0, files.findIndex((f) => f.key === o.key)) })
+                  }}
+                >
+                  <span className="kol-column-browser-tile-box">
+                    {isFolder
+                      ? <Icon name="folder" size={28} className="text-fg-48" />
+                      : (thumbnailFor?.(o) ?? <Icon name={COL_ICON[kindOf(o)] || 'file'} size={28} className="text-fg-48" />)}
+                  </span>
+                  <span className="kol-mono-12 truncate">{isFolder ? r.name.replace(/\/$/, '') : (o.displayKey ?? o.key)}</span>
+                  {/* counts for a folder, size for a file — never dates (§2) */}
+                  <span className="kol-helper-10 text-fg-48 truncate">
+                    {isFolder ? folderMeta?.(r.level + r.name, 'grid') : (o.size != null ? formatSize(o.size) : '')}
+                  </span>
+                </button>
+              )
+            })}
+          </div>
+        ) : (
         <ul className="kol-column-browser-column flex-1 overflow-y-auto">
           {rows.map((r) =>
             r.kind === 'empty' ? (
@@ -532,20 +647,25 @@ export default function ColumnBrowser({
             ) : r.kind === 'folder' ? (
               <Row
                 key={r.key}
+                zones
                 icon="folder"
                 label={r.name.replace(/\/$/, '')}
                 indent={r.depth}
                 active={r.open}
-                trailing={<Icon name={r.open ? 'chevron-down' : 'chevron-right'} size={12} className="text-fg-32" />}
-                /* the same chevron opens and collapses — tapping the open
-                 * folder returns to its parent level, which is the whole
-                 * inline-expand gesture */
-                onClick={() => onPrefix(r.open ? r.level : r.level + r.name)}
+                meta={folderMeta?.(r.level + r.name)}
+                /* DISCLOSURE IS ITS OWN TARGET (item 11): the chevron expands
+                 * in place, the ROW opens the folder. One control doing both is
+                 * what left no way to peek without leaving where you are. */
+                disclosed={r.open}
+                onDisclose={() => onPrefix(r.open ? r.level : r.level + r.name)}
+                onClick={() => onPrefix(r.level + r.name)}
               />
             ) : (
               <Row
                 key={r.key}
+                zones
                 icon={COL_ICON[kindOf(r.o)] || 'file'}
+                thumb={thumbnailFor?.(r.o)}
                 label={r.o.displayKey ?? r.o.key}
                 indent={r.depth}
                 meta={metaOf(r.o)}
@@ -563,6 +683,7 @@ export default function ColumnBrowser({
             ),
           )}
         </ul>
+        )}
       </div>
     )
   }