@kolkrabbi/kol-component 0.192.0 → 0.194.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.192.0",
+  "version": "0.194.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/molecules/Dropdown.jsx

@@ -77,6 +77,11 @@ const Dropdown = ({
    * while a row is hovered would otherwise leave the consumer previewing
    * forever. It never fires while closed — a closed dropdown has no rows. */
   onOptionHover,
+  /* OPTIONS may carry more than `{ value, label }`: `icon` puts a glyph in the
+   * row's line box (ADJACENT ladder — it sits beside a label), and `shortcut`
+   * prints on every row that is NOT the current one, the tick taking that slot
+   * when it is. Both were added for the tool-palette idiom and are general —
+   * a menu of tools and a menu of anything else want the same two columns. */
   /* ICON-ONLY TRIGGER — an icon name, or a pre-rendered node dropped in where
    * the glyph goes. The trigger becomes the pinned square (`kol-btn-icon`) at
    * the current size, with no label, no ghost widths and no caret; the panel
@@ -259,8 +264,25 @@ const Dropdown = ({
                 onPointerEnter={onOptionHover ? () => reportHover(option.value) : undefined}
                 onPointerLeave={onOptionHover ? () => reportHover(null) : undefined}
                 onClick={() => handleSelect(option)}
-                shortcut={isActive ? <Icon name="check" size={resolvedSize === 'xs' ? indicatorSize('xs') : 11} /> : undefined}
+                /* The active row's mark is the CHECK, always — it is what says
+                 * which value is current, and nothing may take that slot from
+                 * it. An option's own `shortcut` shows on the rows that are
+                 * not current, which is the tool-palette idiom: the keystroke
+                 * that would arm this variant, replaced by the tick once it
+                 * is armed (editor-set-is-behind-its-source, 2026-09-03). */
+                shortcut={
+                  isActive
+                    ? <Icon name="check" size={resolvedSize === 'xs' ? indicatorSize('xs') : 11} />
+                    : option.shortcut
+                }
               >
+                {/* an option's leading glyph — the ADJACENT ladder, because it
+                  * sits in a line box beside a label, never the solo rung */}
+                {option.icon && (
+                  <span className="shrink-0 inline-flex items-center" style={{ marginRight: 'var(--kol-spacing-2)' }}>
+                    <Icon name={option.icon} size={glyphSize(resolvedSize)} />
+                  </span>
+                )}
                 {option.label}
               </MenuDropdownItem>
             )

package/src/molecules/SplitToolButton.jsx

@@ -30,6 +30,22 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  * For a text-trigger single-select use `Dropdown`; for the two-button
  * action-half + chevron-half split use `ShapeDropdown`.
  *
+ * WHY THIS IS STILL ITS OWN COMPONENT, after `Dropdown` grew the icon-only
+ * square trigger it was asked to (2026-09-03, `editor-set-is-behind-its-
+ * source`). The ticket's premise — *"it hand-rolls a `<button>` re-emitting
+ * Button's classes"* — is gone: since 0.182.0 this wears
+ * `kol-btn-icon kol-btn-{size}`, the same class output at the same rungs, so
+ * there is no second implementation of the box left to collapse. What remains
+ * is ONE behaviour Dropdown does not have and should not grow for one caller:
+ * a click on the trigger both ARMS the last-picked variant and opens the menu,
+ * so a tool is selected and re-pickable in one gesture. Dropdown is a
+ * controlled select — its trigger opens, it does not choose — and giving it an
+ * `onTriggerClick` seam to serve this would be a seam for exactly one consumer.
+ * Two components, one class output, one popover utility, one glyph ladder: the
+ * duplication the ticket named is closed, and the difference that is left is
+ * real. What DID move to Dropdown is the part that generalises — per-option
+ * `icon` and `shortcut` rows, which any menu wants.
+ *
  * @param {Object} props
  * @param {{id: string, label: string, icon: string, shortcut?: string}[]} props.variants - Variants: menu rows + trigger glyph
  * @param {string} props.value - Active variant id (controlled)

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}