@kolkrabbi/kol-component 0.212.0 → 0.214.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.212.0",
+  "version": "0.214.0",
   "description": "KOL design-system components \u2014 atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",

package/src/index.js

@@ -143,6 +143,7 @@ export { default as Carousel } from './molecules/Carousel.jsx'
  * stage reaches for it instead of re-typing the button markup, which is how the
  * three in-package copies (and kol-website's CarouselNavigation) happened. */
 export { default as EmblaNav } from './molecules/EmblaNav.jsx'
+export { default as MobileTabBar, TABBAR_H } from './molecules/MobileTabBar.jsx'
 export { default as ContentFilters } from './organisms/ContentFilters.jsx'
 export { default as PageHeader } from './molecules/PageHeader.jsx'
 export { default as ErrorBoundary } from './utilities/ErrorBoundary.jsx'

package/src/molecules/MenuItem.jsx

@@ -27,6 +27,12 @@ export function MenuItem({
   panelStyle,
   buttonClassName = '',
   defaultOpen = false,
+  /* THE CARET IS NOT ALWAYS RIGHT. The trigger draws `label ▾`, which is the
+   * shape of a named menu — File, Sort. An ICON trigger (`···`, a gear) is
+   * already complete and a caret beside it reads as a second glyph rather than
+   * an affordance; neither reference draws one (ColumnBrowserMobileViews item
+   * 15, kol-r2b2 2026-09-04). Default keeps every existing call-site. */
+  caret = true,
 }) {
   const [open, setOpen] = useState(defaultOpen)
   const popover = usePopover({
@@ -48,11 +54,13 @@ export function MenuItem({
         className={`kol-helper-12 px-3 h-8 inline-flex items-center gap-2 rounded text-body hover:text-emphasis transition-colors ${buttonClassName}`}
       >
         <span>{label}</span>
-        <Icon
-          name="chevron-down"
-          size={10}
-          style={{ transform: open ? 'rotate(180deg)' : 'rotate(0deg)', transition: 'transform 200ms' }}
-        />
+        {caret && (
+          <Icon
+            name="chevron-down"
+            size={10}
+            style={{ transform: open ? 'rotate(180deg)' : 'rotate(0deg)', transition: 'transform 200ms' }}
+          />
+        )}
       </button>
       {/* w-max: floats size to CONTENT, never to the containing block —
         * same family law as ShapeDropdown's panel (2026-08-09 review). */}

package/src/molecules/MobileTabBar.jsx

@@ -0,0 +1,67 @@
+import { Icon } from '@kolkrabbi/kol-icons'
+
+/**
+ * MobileTabBar — the floating bottom tab pill, below `md` only.
+ *
+ * Both references end the same way: neither iOS Files nor Dropbox stacks two
+ * full-height surfaces on a phone. Each floats a pill at the bottom and gives
+ * every surface a tab — Files `Recents · Shared · Browse`, Dropbox `Home ·
+ * Files · Photos · Account` (ColumnBrowserMobileViews §5, kol-r2b2, user-ruled
+ * 2026-09-03). It is what answers the question `ColumnBrowserStackMode` left
+ * open: the library wall does NOT stay stacked under the browser.
+ *
+ * WHAT A TAB MEANS IS THE CONSUMER'S. This ships the pill — the shape, the
+ * float, the states, the breakpoint — and takes a list. A repo whose surfaces
+ * are routes wires it to its router; one whose surfaces are variants swaps a
+ * variant. The DS deciding that a media library has exactly three surfaces
+ * called Browse, Files and Kinds is the kind of guess that makes an organism
+ * un-reusable.
+ *
+ * FLOATS, not a layout row: it sits over the list on `position: fixed` so the
+ * list scrolls under it, which is what both references do. The consumer owes
+ * the list bottom padding — `--kol-tabbar-h` is published for exactly that, so
+ * nobody hardcodes 56.
+ *
+ * @param {Array<{value: string, label: string, icon?: string}>} tabs
+ * @param {string}   value      the active tab
+ * @param {Function} onChange   (value) => void
+ * @param {string}   className  extra classes on the pill
+ */
+
+export const TABBAR_H = 56
+
+export default function MobileTabBar({ tabs = [], value, onChange, className = '' }) {
+  if (tabs.length === 0) return null
+  return (
+    <nav
+      className={`kol-mobile-tabbar md:hidden fixed inset-x-0 bottom-0 z-[var(--kol-z-sticky)] flex items-stretch ${className}`.trim()}
+      style={{
+        height: TABBAR_H,
+        /* the pill's own ground, not the page's — it floats OVER content, so a
+         * transparent bar would show rows sliding through the labels */
+        background: 'var(--kol-surface-primary)',
+        borderTop: '1px solid var(--kol-oq-08)',
+        paddingBottom: 'env(safe-area-inset-bottom, 0px)',
+      }}
+      aria-label="Sections"
+    >
+      {tabs.map((t) => {
+        const active = t.value === value
+        return (
+          <button
+            key={t.value}
+            type="button"
+            onClick={() => onChange?.(t.value)}
+            aria-current={active ? 'page' : undefined}
+            className="flex-1 min-w-0 flex flex-col items-center justify-center gap-1 cursor-pointer"
+            style={{ background: 'transparent', border: 'none', color: active ? 'var(--kol-fg-default)' : 'var(--kol-fg-48)' }}
+          >
+            {t.icon && <Icon name={t.icon} size={18} />}
+            {/* helper is single-line chrome, which a tab label always is */}
+            <span className="kol-helper-10 truncate max-w-full px-1">{t.label}</span>
+          </button>
+        )
+      })}
+    </nav>
+  )
+}

package/src/organisms/MediaLibraryPages.jsx

@@ -13,6 +13,9 @@ import Dropdown from '../molecules/Dropdown.jsx'
 import ContentCard from '../molecules/ContentCard.jsx'
 import ContentRow from '../molecules/ContentRow.jsx'
 import SortControls from '../molecules/SortControls.jsx'
+import SearchInput from '../molecules/SearchInput.jsx'
+import MobileTabBar, { TABBAR_H } from '../molecules/MobileTabBar.jsx'
+import { MenuItem, MenuDropdownItem, MenuDropdownDivider } from '../molecules/MenuItem.jsx'
 import KindPreview from '../molecules/KindPreview.jsx'
 import AudioSheet from '../molecules/AudioSheet.jsx'
 import VideoSheet from '../molecules/VideoSheet.jsx'
@@ -81,6 +84,13 @@ const FOLDER_VIEW_OPTIONS = [
   { value: 'rows', label: 'Rows', icon: 'view-list' },
   { value: 'columns', label: 'Columns', icon: 'columns' },
 ]
+/* the stack view the `···` switches (item 15) — the same two ColumnBrowser
+ * carries below `md`, named as the references name them */
+const STACK_VIEW_OPTIONS = [
+  { value: 'list', label: 'List' },
+  { value: 'grid', label: 'Icons' },
+]
+
 const SORT_OPTIONS = [
   { value: 'name', label: 'Name' },
   { value: 'date', label: 'Date' },
@@ -328,6 +338,33 @@ const profileOf = (objects, rawFiles, systemCount) => ({
 })
 
 /* ══ BROWSE — folder / files ═══════════════════════════════════════════════ */
+/* THE `···`'s SORT, pure and module-level so it is reachable by a check
+ * (ColumnBrowserMobileViews item 15). Sorting was desktop-only chrome until
+ * now — item 7 of the previous ticket hid the control cluster below `md` and
+ * put nothing in its place, so on a phone sort could not be reached at all.
+ *
+ * NAME IS THE TIEBREAK IN EVERY MODE. Two files of equal size, or a bucket
+ * whose objects carry no `uploaded`, otherwise come back in whatever order the
+ * comparator happened to walk — a list that reshuffles between renders for no
+ * reason the user did anything to cause. The tiebreak is deliberately NOT
+ * reversed by `sortDir`: descending by size still reads A before B inside a
+ * tie, which is what every file manager does. */
+function sortObjects(objects, sortBy = 'name', sortDir = 'asc') {
+  const nameOf = (o) => o.key.slice(o.key.lastIndexOf('/') + 1).toLowerCase()
+  const val = {
+    name: nameOf,
+    date: (o) => o.uploaded ?? '',
+    size: (o) => o.size ?? 0,
+    kind: (o) => String(kindOf(o)),
+  }[sortBy] ?? nameOf
+  const dir = sortDir === 'desc' ? -1 : 1
+  return [...objects].sort((m, n) => {
+    const x = val(m), y = val(n)
+    if (x === y) return nameOf(m) < nameOf(n) ? -1 : 1
+    return (x < y ? -1 : 1) * dir
+  })
+}
+
 export function MediaLibraryBrowse({
   client, title = 'MEDIA', bucket, onBucketChange, prefix: prefixProp, onPrefix, defaults, settings: settingsProp, onSettingsChange,
   folderTree, headerActions, refreshKey, onOpen, autoFocus = false, settingsFooter, className = '',
@@ -342,6 +379,10 @@ export function MediaLibraryBrowse({
    * real opinion about it (it owns `height`, the widths and `partition`, so
    * those are deliberately absent from this list). */
   thumbnailFor, folderMeta, formatDate, stackView,
+  /* THE TAB PILL'S LIST (ColumnBrowserMobileViews item 16). What a tab MEANS is
+   * the consumer's — a repo whose surfaces are routes wires its router here.
+   * No tabs, no pill, and the page is exactly what it was. */
+  tabs, activeTab, onTabChange,
 }) {
   const [ownPrefix, setOwnPrefix] = useState('')
   const prefix = prefixProp ?? ownPrefix
@@ -357,8 +398,25 @@ export function MediaLibraryBrowse({
   const [quickLook, setQuickLook] = useState(null)
   const columnsRef = useRef(null)
   const { folderView = 'columns', flat } = settings
+  /* PINNED SEARCH + `···` (item 15), below `md` only. Item 7 of the previous
+   * ticket hid the desktop control cluster and put nothing in its place, so
+   * SORT became unreachable on a phone; both references carry exactly these two
+   * controls above the list. Search is page state, not a setting — a query is
+   * something you are doing, not something you have configured. */
+  const [query, setQuery] = useState('')
+
+  /* Search filters the KEY SPACE, so the tree still navigates: a path survives
+   * when a file under it matches and ColumnBrowser's own partition does the
+   * rest. One view, rather than a flat results list nobody asked for. Sort
+   * orders the files the way the wall already sorts its own. */
+  const q = query.trim().toLowerCase()
+  const searched = useMemo(() => (q ? objects.filter((o) => o.key.toLowerCase().includes(q)) : objects), [objects, q])
+  const sortedObjects = useMemo(
+    () => sortObjects(searched, settings.sortBy, settings.sortDir),
+    [searched, settings.sortBy, settings.sortDir],
+  )
 
-  const scoped = prefix ? objects.filter((o) => o.key.startsWith(prefix)) : objects
+  const scoped = prefix ? sortedObjects.filter((o) => o.key.startsWith(prefix)) : sortedObjects
   const { folders, files: dirFiles } = partition(scoped, prefix)
   const keySet = new Set(objects.map((o) => o.key))
   const levelFiles = flat ? scoped.map((o) => ({ ...o, displayKey: prefix ? o.key.slice(prefix.length) : o.key })) : dirFiles
@@ -474,6 +532,66 @@ export function MediaLibraryBrowse({
           </div>
         </div>
 
+        {/* PINNED ABOVE THE LIST, below `md` (item 15). Search sits here and not
+            inside the ContentFilters wall, because the wall is a DIFFERENT
+            SURFACE — on a phone it is a tab away, so a control living in it is
+            a control you cannot reach from the thing you are searching. */}
+        <div className="flex md:hidden items-center gap-2">
+          <SearchInput
+            value={query}
+            onChange={(e) => setQuery(e.target.value ?? '')}
+            onClear={() => setQuery('')}
+            placeholder="Search this bucket"
+            size="sm"
+            className="flex-1 min-w-0"
+          />
+          {/* `···` — view mode and sort, the two the desktop cluster carries and
+              item 7 left with nowhere to go. `caret={false}`: an icon trigger is
+              already complete, and neither reference draws a chevron on it. */}
+          <MenuItem
+            label={<Icon name="more" size={16} />}
+            caret={false}
+            align="end"
+            buttonClassName="shrink-0 px-2"
+          >
+            {({ close }) => (
+              <div className="py-1 w-[200px]">
+                {STACK_VIEW_OPTIONS.map((opt) => (
+                  <MenuDropdownItem
+                    key={opt.value}
+                    onClick={() => { setSettings({ ...settings, stackView: opt.value }); close() }}
+                    shortcut={(settings.stackView ?? 'list') === opt.value ? <Icon name="check" size={11} /> : undefined}
+                  >
+                    {opt.label}
+                  </MenuDropdownItem>
+                ))}
+                <MenuDropdownDivider />
+                {SORT_OPTIONS.map((opt) => (
+                  <MenuDropdownItem
+                    key={opt.value}
+                    /* tapping the ACTIVE key flips the direction, which is how
+                       both references let you reverse without a second control */
+                    onClick={() => {
+                      const same = (settings.sortBy ?? 'name') === opt.value
+                      setSettings({
+                        ...settings,
+                        sortBy: opt.value,
+                        sortDir: same && settings.sortDir !== 'desc' ? 'desc' : 'asc',
+                      })
+                      close()
+                    }}
+                    shortcut={(settings.sortBy ?? 'name') === opt.value
+                      ? <Icon name={settings.sortDir === 'desc' ? 'arrow-up' : 'arrow-down'} size={11} />
+                      : undefined}
+                  >
+                    {opt.label}
+                  </MenuDropdownItem>
+                ))}
+              </div>
+            )}
+          </MenuItem>
+        </div>
+
         {quickLook && (
           <MediaInspector files={quickLook.files} index={quickLook.index} onClose={() => setQuickLook(null)} mediaUrl={mediaUrl} downloadUrl={downloadUrl} keySet={keySet}
             onPrev={() => setQuickLook((q) => ({ ...q, index: (q.index - 1 + q.files.length) % q.files.length }))}
@@ -492,7 +610,7 @@ export function MediaLibraryBrowse({
               onHeightChange={(px) => setSettings({ ...settings, columnHeight: px })}
               columnWidths={settings.columnWidths}
               onColumnResize={(i, px) => setSettings({ ...settings, columnWidths: { ...(settings.columnWidths ?? {}), [i]: px } })}
-              objects={objects.filter((o) => !isSystemFile(o.key)).map((o) => ({ ...o, key: `${VROOT}${o.key}` }))}
+              objects={sortedObjects.filter((o) => !isSystemFile(o.key)).map((o) => ({ ...o, key: `${VROOT}${o.key}` }))}
               prefix={single ? prefix : (appRoot ? `${ROOT}/` : `${VROOT}${prefix}`)}
               onPrefix={(v) => {
                 /* single: the browser's path IS the bucket path, no segment to strip */
@@ -514,7 +632,9 @@ export function MediaLibraryBrowse({
               formatDate={formatDate}
               thumbnailFor={thumbnailFor}
               folderMeta={folderMeta}
-              stackView={stackView}
+              /* the PROP wins when a consumer passes one; otherwise the `···`
+                 owns it through settings (item 15) */
+              stackView={stackView ?? settings.stackView ?? 'list'}
               renderPreview={(o) => {
                 const real = { ...o, key: o.key.slice(VROOT.length) }
                 if (isImage(real.contentType)) return <ImageFrame src={mediaUrl(real.key)} />
@@ -549,6 +669,24 @@ export function MediaLibraryBrowse({
           </p>
         )}
         {void onOpen}
+
+        {/* THE TAB PILL (item 16) — floats over the list, so the list owes it
+            room or its last row sits under the bar forever.
+            THE SPACER GOES LAST, AND THAT IS THE WHOLE POINT
+            (TabBarSpacerAboveTheList, kol-r2b2 2026-09-04). `MobileTabBar` is
+            `fixed`, so where it sits in the tree is irrelevant — the SPACER is
+            in NORMAL FLOW, so its position is everything. Rendered before the
+            list it failed twice at once: a 56px hole punched into the gap under
+            the pinned search, and the last row still running 99px under the
+            bar. The comment above named the failure it was meant to prevent and
+            the block sat in the wrong place anyway. Below `md` only; above it
+            the 2026-08-26 one-view ruling stands. */}
+        {tabs?.length > 0 && (
+          <>
+            <div className="md:hidden" aria-hidden="true" style={{ height: TABBAR_H }} />
+            <MobileTabBar tabs={tabs} value={activeTab} onChange={onTabChange} />
+          </>
+        )}
       </div>
     </div>
   )
@@ -558,6 +696,9 @@ export function MediaLibraryBrowse({
 export function MediaLibraryLibrary({
   client, title = 'MEDIA', bucket, onBucketChange, prefix = '', defaults, settings: settingsProp, onSettingsChange,
   headerActions, refreshKey, header = true, stats = true, settingsFooter, className = '',
+  /* the same pill the browse page takes — the wall is one of the surfaces it
+     switches between, so it has to carry it too (item 16) */
+  tabs, activeTab, onTabChange,
 }) {
   const [ownBucket, setOwnBucket] = useState(bucket)
   const bucketId = bucket ?? ownBucket
@@ -798,6 +939,15 @@ export function MediaLibraryLibrary({
           )
         }}
       />
+
+      {/* the pill again — the wall is one of the surfaces it switches, so it
+          carries the same bar and owes it the same room (item 16) */}
+      {tabs?.length > 0 && (
+        <>
+          <div className="md:hidden" aria-hidden="true" style={{ height: TABBAR_H }} />
+          <MobileTabBar tabs={tabs} value={activeTab} onChange={onTabChange} />
+        </>
+      )}
     </div>
   )
 }

package/src/utilities/FullscreenOverlay.jsx

@@ -18,7 +18,26 @@ import CloseButton from './CloseButton.jsx'
 const FOCUSABLE =
   'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
 
-export default function FullscreenOverlay({ open, onClose, closeButton = true, children }) {
+export default function FullscreenOverlay({
+  open, onClose, closeButton = true,
+  /* WHERE FOCUS LANDS ON OPEN. The sheet takes it by default, which is right
+   * for a browser and wrong for a sheet opened to be TYPED IN: a child's
+   * `autoFocus` cannot win, because child effects run BEFORE the parent's and
+   * this one moves focus afterwards — so the field focuses and is immediately
+   * robbed, with nothing in either file looking wrong (kol-fxr measured it on
+   * design-editor 0.10.0: Save As routed into the dialog correctly and focus
+   * sat on `.kol-overlay-sheet`). Pass a ref to the node that should hold it.
+   * A ref that is empty on mount falls back to the sheet, so a conditional
+   * field cannot leave the overlay unfocused.
+   *
+   * The ref may point at the control ITSELF or at a WRAPPER around it — the
+   * first focusable descendant is taken. That is deliberate: a DS input is a
+   * component, not a DOM node, and whether it forwards a ref is a detail no
+   * caller should have to know to put focus in it. A plain `<div ref>` always
+   * works. */
+  initialFocus,
+  children,
+}) {
   const sheetRef = useRef(null)
 
   /* Escape closes; Tab is TRAPPED in the sheet (SettingsPanel, 2026-08-26 —
@@ -45,13 +64,19 @@ export default function FullscreenOverlay({ open, onClose, closeButton = true, c
     const prev = document.body.style.overflow
     document.body.style.overflow = 'hidden'
     const prevFocus = document.activeElement
-    sheetRef.current?.focus()
+    const wanted = initialFocus?.current
+    const target = wanted
+      ? (typeof wanted.focus === 'function' && wanted.matches?.(FOCUSABLE)
+          ? wanted
+          : wanted.querySelector?.(FOCUSABLE) ?? wanted)
+      : sheetRef.current
+    target?.focus?.()
     return () => {
       document.removeEventListener('keydown', onKey)
       document.body.style.overflow = prev
       if (prevFocus instanceof HTMLElement) prevFocus.focus()
     }
-  }, [open, onClose])
+  }, [open, onClose, initialFocus])
 
   if (!open) return null