@kolkrabbi/kol-component 0.193.0 → 0.195.0

package/package.json

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

@@ -0,0 +1,36 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * useMediaQuery — subscribe to a media query, SSR-safe.
+ *
+ * The general form of `useCoarsePointer` and `usePrefersReducedMotion`, which
+ * are each this hook with one query frozen in. It exists because a STRUCTURAL
+ * responsive fork cannot be a stylesheet: `ColumnBrowser` renders Miller
+ * columns on a desktop and a single inline-expanding list on a phone
+ * (`ColumnBrowserStackMode`, kol-r2b2 2026-09-03), and those are different
+ * TREES, not one tree with different padding. A component that only needs
+ * different sizes still uses Tailwind's breakpoints — reach for this when the
+ * markup itself has to change.
+ *
+ * Returns false during SSR and on the first client render if the query cannot
+ * be evaluated, so a server render and its hydration agree.
+ *
+ * @param {string} query a media query, e.g. '(max-width: 767px)'
+ * @returns {boolean} whether it currently matches
+ */
+export default function useMediaQuery(query) {
+  const [matches, setMatches] = useState(
+    () => typeof window !== 'undefined' && window.matchMedia(query).matches,
+  )
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const mq = window.matchMedia(query)
+    const onChange = () => setMatches(mq.matches)
+    setMatches(mq.matches)
+    mq.addEventListener('change', onChange)
+    return () => mq.removeEventListener('change', onChange)
+  }, [query])
+
+  return matches
+}

package/src/index.js

@@ -193,6 +193,10 @@ export { default as useCoarsePointer } from './hooks/useCoarsePointer.js'
 export { default as useInViewAttention } from './hooks/useInViewAttention.js'
 export { default as useAxisAnimation } from './hooks/useAxisAnimation.js'
 export { useEyedropper, pickFromCanvasElement } from './hooks/useEyedropper.js'
+/* The general form of `useCoarsePointer` / `usePrefersReducedMotion` — for a
+ * STRUCTURAL responsive fork, where the markup itself changes and a stylesheet
+ * cannot express it (ColumnBrowserStackMode, 2026-09-03). Sizes stay Tailwind's. */
+export { default as useMediaQuery } from './hooks/useMediaQuery.js'
 /* The rail gesture's other half. It lived in kol-framework until 2026-09-03 and
  * moved here for the same reason `useGrabEdge` did: kol-component's own
  * `EditorShell` needs resizable rails and cannot import framework. framework

package/src/organisms/ColumnBrowser.jsx

@@ -4,6 +4,7 @@ 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'
+import useMediaQuery from '../hooks/useMediaQuery.js'
 import { GRAB_COLUMN } from '../utilities/motion.js'
 
 /**
@@ -69,6 +70,17 @@ import { GRAB_COLUMN } from '../utilities/motion.js'
  *                                  any column it does not name falls back to the drag state, then `columnWidth`
  * @param {Function} onColumnResize (index, px) => void — the column's index, or `'preview'`
  * @param {string}   className    extra classes on the browser
+ *
+ * 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`,
+ * `columnWidth` / `columnWidths` / `onColumnResize` and the resize handles are
+ * all DESKTOP-ONLY and inert there: a stored height is a value someone dragged
+ * on a desktop, and the list takes the viewport instead. A file tap fires
+ * `onQuickLook` rather than opening the preview column, so the consumer's
+ * existing full-screen inspector is the phone's preview. Everything else —
+ * `prefix`/`onPrefix`, `onPick`, the seams, the keyboard on a device that has
+ * one — is unchanged.
  */
 
 /* the DS kinds (mediaKinds — kol-r2b2's classification, promoted 2026-08-27) */
@@ -115,7 +127,14 @@ const COL_ICON = { image: 'image', video: 'video', audio: 'file', playlist: 'vid
  * changes it breaks every rule hanging off it silently (twice already in kol-r2b2). It also lets the
  * theme say the user's ruling — "ONLY one selected state can exist, not TWO": the selected row in
  * the deepest column that holds one is full strength, every column on the way there is the trail. */
-function Row({ icon, label, active, cursor = false, trailing, onClick, muted = false }) {
+/* `indent` and `meta` serve the STACK mode and are inert without it: the
+ * columns pass neither, so a desktop row is byte-identical to what it was. */
+/* Three levels of indent, then the list re-bases and the back control takes
+ * over — the user's cap (ColumnBrowserStackMode, 2026-09-03): a deep bucket
+ * 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 }) {
   return (
     <li
       /* Row metrics are the DS Table's (kol-components-organisms.css .kol-table-cell-*):
@@ -126,11 +145,24 @@ function Row({ icon, label, active, cursor = false, trailing, onClick, muted = f
         active || cursor || !muted ? 'text-fg-default' : 'text-fg-48'
       }`}
       onClick={onClick}
+      /* the indent is a PADDING, not a nested list: one flat <ul> keeps the
+       * rows one scroll box and one keyboard sequence, which a tree of nested
+       * 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>
-      <span className="kol-mono-12 flex-1 truncate">{label}</span>
+      {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>
+        </span>
+      ) : (
+        <span className="kol-mono-12 flex-1 truncate">{label}</span>
+      )}
       {trailing}
     </li>
   )
@@ -413,6 +445,128 @@ export default function ColumnBrowser({
   // While Quick Look is open the overlay's index is the truth for the highlight.
   const shown = quickLook ? quickLook.files[quickLook.index] : picked
 
+  /* ── THE STACK MODE (ColumnBrowserStackMode, kol-r2b2 2026-09-03) ─────────
+   *
+   * Miller columns put hierarchy on the X AXIS, and a phone has no width to
+   * spend on it: at 390 two 260px columns plus a gutter overflow, the inner row
+   * scrolls with nothing to say so, and a horizontal scroll inside a vertical
+   * page is a gesture nobody goes looking for. Measured on a live site, in a
+   * different repo running these same organisms — the layout ported and carried
+   * the missing mobile story with it, which is what makes this the DS's.
+   *
+   * THE RULING IS INLINE EXPAND, not push-and-back (user, 2026-09-03). iOS
+   * Files and Dropbox arrived at one-level-at-a-time independently and differ
+   * only on the descent; push discards the very thing this organism exists for
+   * — a parent that stays put while you look at its child — and leaves a
+   * generic file list any component could render. Inline expand keeps the idea
+   * and moves it from two axes onto one.
+   *
+   * CAPPED AT THREE LEVELS, then it pushes: a deep bucket path indents until
+   * the name has no room. Past the cap the list re-bases on a deeper folder and
+   * the back control NAMES the parent it returns to — a bare chevron does not
+   * say where it goes.
+   *
+   * This is a different TREE, not the same tree restyled, which is why it forks
+   * in JS on a media query rather than in the stylesheet. The breakpoint is
+   * `md` (768) — the one `ContentFilters` already uses, so a page has one
+   * responsive story and not two. */
+  const stack = useMediaQuery('(max-width: 767px)')
+
+  if (stack) {
+    /* Re-base so the deepest open level is at most INDENT_CAP below the base:
+     * everything above scrolls out of the list and is reached by the back
+     * control instead. */
+    const baseIdx = Math.max(0, levels.length - 1 - INDENT_CAP)
+    const base = levels[baseIdx]
+    const parent = baseIdx > 0 ? levels[baseIdx - 1] : null
+    const openPath = levels.slice(baseIdx)
+
+    /* One flat row list, walked down the open path: each level's items, with
+     * the open folder's children spliced in directly under it. */
+    const rows = []
+    openPath.forEach((level, depth) => {
+      const { folders, files } = partition(objects.filter((o) => o.key.startsWith(level)), level)
+      const openFolder = openPath[depth + 1]?.slice(level.length) ?? null
+      folders.forEach((f) => {
+        const isOpen = f === openFolder
+        rows.push({
+          kind: 'folder', key: level + f, level, name: f, depth, open: isOpen,
+        })
+        /* the open folder's own children are pushed by the next iteration —
+         * nothing recursive here, the loop IS the path */
+      })
+      files.forEach((o) => rows.push({ kind: 'file', key: o.key, o, depth, level }))
+      if (!folders.length && !files.length) rows.push({ kind: 'empty', key: level + '·empty', depth })
+    })
+
+    const metaOf = (o) => [o.size != null && formatSize(o.size), o.uploaded].filter(Boolean).join(' · ')
+
+    return (
+      <div
+        className={`kol-column-browser kol-column-browser--stack flex flex-col border rounded ${className}`.trim()}
+        /* THE VIEWPORT IS THE HEIGHT (item 4). `height` is a value someone
+         * dragged on a desktop; applied literally to a phone it painted a
+         * black void the length of the viewport under two near-empty columns.
+         * A desktop drag is not a phone measurement, so below the breakpoint
+         * the stored one is ignored outright rather than clamped. */
+        style={{ borderColor: 'var(--kol-oq-08)' }}
+      >
+        {parent != null && (
+          <button
+            type="button"
+            onClick={() => onPrefix(parent)}
+            className="kol-column-browser-back flex items-center gap-2 px-4 py-3 border-b text-fg-default"
+            style={{ borderColor: 'var(--kol-oq-08)' }}
+          >
+            <Icon name="chevron-left" size={14} className="text-fg-48" />
+            {/* NAMES THE PARENT (item 2) — the folder it returns to, not '‹' */}
+            <span className="kol-mono-12 truncate">
+              {parent === '' ? 'All files' : parent.replace(/\/$/, '').split('/').pop()}
+            </span>
+          </button>
+        )}
+        <ul className="kol-column-browser-column flex-1 overflow-y-auto">
+          {rows.map((r) =>
+            r.kind === 'empty' ? (
+              <li key={r.key} className="kol-mono-12 text-fg-32 px-4 py-3">empty</li>
+            ) : r.kind === 'folder' ? (
+              <Row
+                key={r.key}
+                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)}
+              />
+            ) : (
+              <Row
+                key={r.key}
+                icon={COL_ICON[kindOf(r.o)] || 'file'}
+                label={r.o.displayKey ?? r.o.key}
+                indent={r.depth}
+                meta={metaOf(r.o)}
+                active={shown?.key === r.o.key}
+                /* A FILE IS A PUSH, NOT A PREVIEW PANE (item 6): there is no
+                 * column for the preview to sit beside at this width, so the
+                 * tap opens the full-screen inspector the consumer already
+                 * renders for Quick Look. */
+                onClick={() => {
+                  const files = itemsAt(r.level ?? '').filter((it) => it.type === 'file').map((it) => it.o)
+                  pick(r.o)
+                  onQuickLook?.({ files: files.length ? files : [r.o], index: Math.max(0, files.findIndex((f) => f.key === r.o.key)) })
+                }}
+              />
+            ),
+          )}
+        </ul>
+      </div>
+    )
+  }
+
   return (
     <div
       ref={rootRef}

package/src/organisms/MediaLibraryPages.jsx

@@ -357,9 +357,37 @@ export function MediaLibraryBrowse({
         onSettings={() => setSettingsOpen(true)} />
 
       <div className="flex flex-col gap-3">
-        {/* Breadcrumb (uppercase, active segment at full ink) · folder-view toggle */}
+        {/* Breadcrumb (uppercase, active segment at full ink) · folder-view toggle
+          *
+          * AT 390 THIS ROW FAILED (ColumnBrowserStackMode items 3 + 7, kol-r2b2
+          * 2026-09-03, measured on a live site): breadcrumb, the folder-view
+          * toggle and the ROW·COLUMN pair share one `justify-between` line with
+          * no wrap or collapse rule, so the crumbs wrapped to two lines and
+          * `COLUMN` was cut off. Below `md` the crumb becomes ONE middle-elided
+          * path line and the toggles collapse into the settings drawer — where
+          * both already live, so nothing new was minted to hold them. Both
+          * references (iOS Files, Dropbox) put these behind a `···` too. */}
         <div className="flex items-center justify-between gap-4">
-          <div className="flex items-center gap-2 kol-mono-12">
+          {/* the elided line — first segment, an ellipsis for anything between,
+            * and the current one. Below `md` only. */}
+          <div className="flex md:hidden items-center gap-2 kol-mono-12 min-w-0">
+            <button className={crumbCls(appRoot)} onClick={() => { setAppRoot(true); setPickedFile(null); setPrefix('') }}>{ROOT}</button>
+            {!appRoot && bucketMeta.id && crumbs.length > 1 && (
+              <><span className="text-oq-32">/</span><span className="text-oq-32">…</span></>
+            )}
+            {!appRoot && bucketMeta.id && (
+              <span className="flex items-center gap-2 min-w-0">
+                <span className="text-oq-32">/</span>
+                <button
+                  className={`${crumbCls(true)} truncate`}
+                  onClick={() => setPrefix(crumbs.length ? crumbs.join('/') + '/' : '')}
+                >
+                  {(crumbs[crumbs.length - 1] ?? label).toUpperCase()}
+                </button>
+              </span>
+            )}
+          </div>
+          <div className="hidden md:flex items-center gap-2 kol-mono-12">
             <button className={crumbCls(appRoot)} onClick={() => { setAppRoot(true); setPickedFile(null); setPrefix('') }}>{ROOT}</button>
             {!appRoot && bucketMeta.id && (
               <span className="flex items-center gap-2">
@@ -381,7 +409,10 @@ export function MediaLibraryBrowse({
               <span className="flex items-center gap-2"><span className="text-oq-32">/</span><span className="text-oq-96">{pickedFile.key.slice(prefix.length).toUpperCase()}</span></span>
             )}
           </div>
-          <div className="flex items-center gap-6">
+          {/* the control cluster is desktop-only — below `md` these two toggles
+            * are the same setting the drawer already carries, and nothing in
+            * this row survives 390 */}
+          <div className="hidden md:flex items-center gap-6">
             <ViewToggle viewMode={folderView} onViewChange={(v) => setSettings({ ...settings, folderView: v })} variant="icon" options={FOLDER_VIEW_OPTIONS} />
             <Divider variant="vertical" />
             <div className="flex items-center gap-4">