@kolkrabbi/kol-component 0.242.0 → 0.244.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.242.0",
+  "version": "0.244.0",
   "description": "The core component library",
   "license": "MIT",
   "type": "module",
@@ -26,8 +26,8 @@
     "embla-carousel-react": "^8.6.0",
     "pdfjs-dist": "^6.3.289",
     "react-syntax-highlighter": "^16.1.1",
-    "@kolkrabbi/kol-markdown": "^0.1.3",
-    "@kolkrabbi/kol-search": "^0.3.0"
+    "@kolkrabbi/kol-search": "^0.3.0",
+    "@kolkrabbi/kol-markdown": "^0.1.3"
   },
   "peerDependencies": {
     "@kolkrabbi/kol-icons": ">=0.22.0",

package/src/molecules/ContextMenu.jsx

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useState } from 'react'
 import { usePopover, PopoverPanel } from '../utilities/Popover.jsx'
+import { pushLayer, popLayer } from '../utilities/layerStack.js'
 
 /**
  * ContextMenu — a right-click menu, anchored at the pointer.
@@ -63,6 +64,13 @@ export function useContextMenu() {
 }
 
 export default function ContextMenu({ menu, children, className = '' }) {
+  /* ONE ESCAPE, ONE LEVEL (kol-fxr 2026-10-08: a menu opened inside a FullscreenOverlay took the
+   * dialog with it). Open, the menu is the top layer, so the overlay under it ignores that Escape. */
+  useEffect(() => {
+    if (!menu.open) return undefined
+    const layer = pushLayer()
+    return () => popLayer(layer)
+  }, [menu.open])
   if (!menu.open) return null
   return (
     /* `focus={false}` — FloatingFocusManager reads attributes off the reference,

package/src/organisms/ColumnBrowser.jsx

@@ -87,6 +87,7 @@ import { GRAB_COLUMN } from '../utilities/motion.js'
  * `KOL-R2B2/<label>/…`) must strip its own prefix before it can look anything up or build a URL —
  * the browser has no idea which part of a path is yours (kol-r2b2 2026-09-04).
  * @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 {boolean} tapSelects  below the breakpoint a file tap selects only, no Quick Look (a picker)
  * @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
@@ -187,7 +188,7 @@ const defaultPartition = (objects, prefix) => {
     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 })
+    else files.push({ ...o, displayKey: o.displayKey ?? o.displayName ?? rel })
   }
   return { folders: [...folderSet].sort(), files }
 }
@@ -573,6 +574,9 @@ export default function ColumnBrowser({
    * 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',
+  /* `tapSelects` — below the breakpoint a file tap SELECTS and opens nothing (kol-fxr 2026-10-08: a
+   * picker's tap must pick, and Quick Look covered the host's Open button). Off: a tap opens Quick Look. */
+  tapSelects = false,
   autoFocus = false,
   className = '',
 }) {
@@ -899,6 +903,7 @@ export default function ColumnBrowser({
                     if (isFolder) { onPrefix(r.level + r.name); return }
                     const files = itemsAt(r.level ?? '').filter((it) => it.type === 'file').map((it) => it.o)
                     pick(o)
+                    if (tapSelects) return
                     onQuickLook?.({ files: files.length ? files : [o], index: Math.max(0, files.findIndex((f) => f.key === o.key)) })
                   }}
                 >
@@ -966,6 +971,7 @@ export default function ColumnBrowser({
                 onClick={() => {
                   const files = itemsAt(r.level ?? '').filter((it) => it.type === 'file').map((it) => it.o)
                   pick(r.o)
+                  if (tapSelects) return
                   onQuickLook?.({ files: files.length ? files : [r.o], index: Math.max(0, files.findIndex((f) => f.key === r.o.key)) })
                 }}
               />

package/src/organisms/MediaLibraryPages.jsx

@@ -247,7 +247,10 @@ function useBucketLibrary({ client, bucket, defaults, settings: controlled, onSe
   const mediaUrl = (key) => client?.mediaUrl?.(key, bucketId ?? undefined) ?? key
   const downloadUrl = (key) => client?.downloadUrl?.(key, bucketId ?? undefined) ?? mediaUrl(key)
   const writable = !!bucketMeta.writable && !!(client?.deleteObject || client?.renameObject)
-  return { buckets, bucketMeta, bucketId, settings, setSettings, objects, setObjects, folderInfo, setFolderInfo, reload, error, ready, mediaUrl, downloadUrl, writable }
+  /* A CLIENT WITH NO `mediaUrl` HAS NO URLS (kol-fxr 2026-10-08: a stored preset is not a fetchable
+   * object) — Copy URL, Download and Quick Look's fetch all go, as write verbs go without a writer. */
+  const hasUrl = typeof client?.mediaUrl === 'function'
+  return { buckets, bucketMeta, bucketId, settings, setSettings, objects, setObjects, folderInfo, setFolderInfo, reload, error, ready, mediaUrl, downloadUrl, writable, hasUrl }
 }
 
 /* ── shared pieces, kol-r2b2's ─────────────────────────────────────────────── */
@@ -440,7 +443,7 @@ function FileRow({ o, onClick, onDoubleClick, depth = 0, formatDate, thumb, cols
           {/* a file with no thumbnail draws its glyph at the FOLDER's size — one icon column (user 2026-09-25) */}
           {thumb ?? <Icon name={kindOf(o) === 'image' ? 'image' : 'file'} size={glyphSize(size)} />}
         </span>
-        <span className={`kol-item-name min-w-0 truncate${selected ? '' : ' text-fg-default'}`}>{o.displayKey ?? o.key.split('/').pop()}</span>
+        <span className={`kol-item-name min-w-0 truncate${selected ? '' : ' text-fg-default'}`}>{o.displayKey ?? o.displayName ?? o.key.split('/').pop()}</span>
       </span>
       <span className="flex-1" />
       {cols && <>
@@ -588,7 +591,7 @@ function FileEditorHost({ o, client, bucket, onClose, onSaved, assets }) {
     return () => { live = false }
   }, [o.key]) // eslint-disable-line react-hooks/exhaustive-deps
   return (
-    <DocumentEditor name={o.displayKey ?? o.key.split('/').pop()} kind={editKindOf(o)} text={text}
+    <DocumentEditor name={o.displayKey ?? o.displayName ?? o.key.split('/').pop()} kind={editKindOf(o)} text={text}
       savedAt={o.uploaded ? Date.parse(o.uploaded) : 0} draft={{ bucket, key: o.key }} assets={assets}
       onSave={async (next) => { const r = await client.writeText(o.key, next, bucket); onSaved?.(o.key, r, next) }}
       onClose={onClose} />
@@ -622,7 +625,7 @@ function FileEditorHost({ o, client, bucket, onClose, onSaved, assets }) {
  * @param {boolean} showNav - ‹ › and n / N in the header (default on); off when not paging a selection
  * @param {Function} onEdit - `(file) => void` — an Edit action in the header for a text file (markdown · json · yaml · text · code); absent, no Edit
  */
-export function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl, downloadUrl, keySet, showNav = true, onEdit }) {
+export function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl, downloadUrl, keySet, showNav = true, onEdit, hasUrl = true }) {
   const o = files[index]
   const [dims, setDims] = useState(null)
   /* the window's size survives paging — Finder keeps it — so it lives here, not in the frame,
@@ -646,7 +649,7 @@ export function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl
     shownDims?.len && formatLength(shownDims.len),
   ].filter(Boolean).join(' · ')
   const frame = {
-    title: o.displayKey ?? o.key.split('/').pop(),
+    title: o.displayKey ?? o.displayName ?? o.key.split('/').pop(),
     meta: facts,
     onClose,
     /* ‹ › and n / N only when the window pages a SELECTION (user 2026-09-23: *"I only selected one
@@ -666,17 +669,26 @@ export function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl
             <Button variant="nav" size="sm" iconOnly="edit" onClick={() => onEdit(o)} aria-label="Edit" />
           </Tooltip>
         )}
-        <CopyAction label="Copy URL" text={mediaUrl(o.key)} />
-        <Tooltip label="Download">
-          <Button variant="nav" size="sm" iconOnly="download" href={downloadUrl(o.key)} download={o.key.split('/').pop()} aria-label="Download" />
-        </Tooltip>
+        {hasUrl && (
+          <>
+            <CopyAction label="Copy URL" text={mediaUrl(o.key)} />
+            <Tooltip label="Download">
+              <Button variant="nav" size="sm" iconOnly="download" href={downloadUrl(o.key)} download={o.key.split('/').pop()} aria-label="Download" />
+            </Tooltip>
+          </>
+        )}
       </span>
     ),
   }
   return (
     /* QUICK LOOK DIMS, it does not black out — you keep the list you came from in view */
     <FullscreenOverlay open onClose={onClose} closeButton={false} scrim>
-      {isImage(o.contentType) ? (
+      {!hasUrl ? (
+        /* nothing to fetch, so nothing to draw — said, not spun on (kol-fxr 2026-10-08) */
+        <QuickLookFrame {...frame}>
+          <p className="kol-helper-12 text-meta p-8">No preview</p>
+        </QuickLookFrame>
+      ) : isImage(o.contentType) ? (
         <QuickLookFrame {...frame}>
           {/* A VECTOR HAS NO PIXEL SIZE (user 2026-09-24: a 32px logo.svg opened as a 32px window). It
             * is drawn in a 640 box — the window's max if that is smaller — and contained in it. */}
@@ -1081,6 +1093,10 @@ export function MediaLibraryBrowse({
    * browse surface inside the modal card needs the selection for its Use button). Keys are
    * bucket-relative. Absent, nothing. */
   onPickFile,
+  /* `searchPlaceholder` — the search field's words; a store that is not a bucket names itself (kol-fxr 2026-10-08) */
+  searchPlaceholder = 'Search this bucket',
+  /* `o.displayName` on a listed object is its LABEL in every view, Quick Look and search (kol-fxr
+   * 2026-10-08: names not unique, so the key is an id). Absent, the label is the key, as before. */
 }) {
   const [ownPrefix, setOwnPrefix] = useState('')
   const prefix = prefixProp ?? ownPrefix
@@ -1089,7 +1105,11 @@ export function MediaLibraryBrowse({
   const [ownBucket, setOwnBucket] = useState(bucket)
   const bucketId = bucket ?? ownBucket
   const lib = useBucketLibrary({ client, bucket: bucketId, defaults, settings: settingsProp, onSettingsChange, refreshKey })
-  const { buckets, bucketMeta, settings, setSettings, objects, error, mediaUrl, downloadUrl, writable } = lib
+  const { buckets, bucketMeta, settings, setSettings, objects, error, mediaUrl, downloadUrl, hasUrl } = lib
+  /* `fileActions` GIVEN IS A WRITER (kol-fxr 2026-10-08): the consumer brings its own verbs, so the
+   * client need not carry a `deleteObject` stub to be treated as writable. The bucket still has to
+   * say it is writable. */
+  const writable = lib.writable || (!!fileActions && !!bucketMeta.writable)
   const switchBucket = (id, pfx = '') => { if (bucket == null) setOwnBucket(id); onBucketChange?.(id); setPrefix(pfx) }
   const [settingsOpen, setSettingsOpen] = useState(false)
   const [trashOpen, setTrashOpen] = useState(false)
@@ -1945,7 +1965,7 @@ export function MediaLibraryBrowse({
    * settings the wall always had. */
   const wallKinds = new Set(settings.kinds ?? SETTINGS_BASE.kinds)
   const wallSource = settings.flat
-    ? scoped.map((o) => ({ ...o, displayKey: prefix ? o.key.slice(prefix.length) : o.key }))
+    ? scoped.map((o) => ({ ...o, displayKey: o.displayName ?? (prefix ? o.key.slice(prefix.length) : o.key) }))
     : dirFiles
   const wallVisible = wallKinds.has('system') ? wallSource : wallSource.filter((o) => !isSystemFile(o.key))
   const wallGrouped = settings.groupVariants ? groupVariants(wallVisible) : wallVisible
@@ -1958,7 +1978,7 @@ export function MediaLibraryBrowse({
    * bar at `brand/og/` and `logos`, `original`, `projects` vanished with no filter set). The
    * columns draw every level up to the root, so a list scoped to `prefix` cut every sibling path
    * the moment the bar mounted. */
-  const filterItems = isWall ? wallFiles : sortedObjects.filter((o) => !isSystemFile(o.key)).map((o) => ({ ...o, kind: kindOf(o), poster: posterFor(o.key, keySet), displayKey: o.key }))
+  const filterItems = isWall ? wallFiles : sortedObjects.filter((o) => !isSystemFile(o.key)).map((o) => ({ ...o, kind: kindOf(o), poster: posterFor(o.key, keySet), displayKey: o.displayName ?? o.key }))
   const filterKinds = [...new Set(filterItems.map((o) => o.kind))].sort()
   const filterTags = [...new Set(filterItems.flatMap((o) => o.tags ?? []))].sort()
   /* favourites as a one-chip group: ContentFilters matches a value, so a starred file carries one */
@@ -2006,6 +2026,7 @@ export function MediaLibraryBrowse({
               <ColumnBrowser
                 autoFocus={autoFocus}
                 className={atTitleRoot ? 'is-root' : ''}
+                tapSelects={!!onPickFile}
                 height={colH}
                 onHeightChange={onColH}
                 rowSize={rowSize}
@@ -2266,7 +2287,7 @@ export function MediaLibraryBrowse({
    * that means the top hit. Arrow-then-Enter and a click go through `onSelect`, same jump. */
   const searchResults = rankMedia(objects, searchQuery, { limit: 50 }).map((o) => ({
     id: o.key,
-    label: o.key.split('/').pop(),
+    label: o.displayName ?? o.key.split('/').pop(),
     hint: o.key.slice(0, o.key.lastIndexOf('/') + 1) || 'the bucket root',
     group: KIND_LABEL[kindOf(o)] || 'File',
   }))
@@ -2302,7 +2323,7 @@ export function MediaLibraryBrowse({
     if ((q.kinds ?? []).length && !q.kinds.includes(kindOf(o))) return false
     if (q.text && !filterMedia([o], q.text).length) return false
     return true
-  }).map((o) => ({ ...o, kind: kindOf(o), poster: posterFor(o.key, keySet), displayKey: o.key })) : null
+  }).map((o) => ({ ...o, kind: kindOf(o), poster: posterFor(o.key, keySet), displayKey: o.displayName ?? o.key })) : null
   /* A TYPED QUERY IS A RESULTS LIST (user 2026-09-30, reversing "a flat results list nobody asked
    * for"): pruning the tree to matching paths hid the files one level down and read as "search only
    * finds folders". While the bar holds a query, the tree views show every hit flat, each with its
@@ -2433,7 +2454,7 @@ export function MediaLibraryBrowse({
             value={query}
             onChange={(e) => setQuery(e.target.value ?? '')}
             onClear={() => setQuery('')}
-            placeholder="Search this bucket"
+            placeholder={searchPlaceholder}
             size="sm"
             className="flex-1 min-w-0"
           />
@@ -2497,7 +2518,7 @@ export function MediaLibraryBrowse({
             onClose={() => { setSearchOpen(false); setSearchQuery('') }}
             query={searchQuery}
             onQueryChange={setSearchQuery}
-            placeholder="Search this bucket"
+            placeholder={searchPlaceholder}
             results={searchResults}
             onExpand={() => searchResults[0] && jumpTo(searchResults[0].id)}
             onSelect={(item) => (item.run ? item.run() : jumpTo(item.id))}
@@ -2514,7 +2535,7 @@ export function MediaLibraryBrowse({
           </FullscreenOverlay>
         )}
         {quickLook && (
-          <MediaInspector files={quickLook.files} index={quickLook.index} onClose={closeQuickLook} mediaUrl={mediaUrl} downloadUrl={downloadUrl} keySet={keySet} showNav={rowSelection.size > 1}
+          <MediaInspector files={quickLook.files} index={quickLook.index} onClose={closeQuickLook} mediaUrl={mediaUrl} downloadUrl={downloadUrl} hasUrl={hasUrl} keySet={keySet} showNav={rowSelection.size > 1}
             onEdit={canEdit ? (f) => { closeQuickLook(); openEditor(f) } : undefined}
             onPrev={() => stepQuickLook(-1)} onNext={() => stepQuickLook(1)} />
         )}
@@ -2637,7 +2658,7 @@ export function MediaLibraryBrowse({
                     {fa.move && (
                       <MenuDropdownItem iconLeft={<Icon name="arrow-right" size={14} />} onClick={() => doBatch(many, 'move', 'Move')}>Move {many.length} to…</MenuDropdownItem>
                     )}
-                    {many.every((p) => !p.endsWith('/')) && (
+                    {hasUrl && many.every((p) => !p.endsWith('/')) && (
                       <>
                         <MenuDropdownItem iconLeft={<Icon name="copy" size={14} />} onClick={() => doCopyUrl(many)}>Copy {many.length} URLs</MenuDropdownItem>
                         <MenuDropdownItem iconLeft={<Icon name="download" size={14} />} onClick={() => doDownload(many)}>Download {many.length}</MenuDropdownItem>
@@ -2651,8 +2672,17 @@ export function MediaLibraryBrowse({
                   </>
                 )
               }
+              const qlFile = onPickFile && target.type === 'file' ? objects.find((o) => o.key === target.path) : null
               return (
                 <>
+                  {/* A PICKER'S TAP SELECTS (`tapSelects`), so Quick Look needs a door of its own on a
+                    * phone — the menu (kol-fxr 2026-10-08). Only with `onPickFile`; others are unchanged. */}
+                  {qlFile && (
+                    <>
+                      <MenuDropdownItem iconLeft={<Icon name="eye-on" size={14} />} onClick={() => openQuickLook({ files: [qlFile], index: 0 })}>Quick Look</MenuDropdownItem>
+                      <MenuDropdownDivider />
+                    </>
+                  )}
                   {fa.createFolder && (
                     <MenuDropdownItem iconLeft={<Icon name="folder" size={14} />} onClick={() => doCreateFolder(isFolder ? target.path : (isLevel ? target.path : prefix))}>
                       New folder{isFolder ? ` in ${target.path.replace(/\/$/, '').split('/').pop()}` : ''}
@@ -2685,10 +2715,10 @@ export function MediaLibraryBrowse({
                       seam a file goes through, so what a folder URL means is the consumer's call
                       (a CDN prefix, a listing, a signed path) and never this page's guess. No
                       Download: a folder is not an object to fetch. */}
-                  {!isLevel && (
+                  {hasUrl && !isLevel && (
                     <MenuDropdownItem iconLeft={<Icon name="copy" size={14} />} onClick={() => doCopyUrl([target.path])}>Copy URL</MenuDropdownItem>
                   )}
-                  {target.type === 'file' && (
+                  {hasUrl && target.type === 'file' && (
                     <MenuDropdownItem iconLeft={<Icon name="download" size={14} />} onClick={() => doDownload([target.path])}>Download</MenuDropdownItem>
                   )}
                   {!isLevel && canTag && (
@@ -2971,7 +3001,7 @@ export function MediaLibraryLibrary({
 
   const scoped = prefix ? objects.filter((o) => o.key.startsWith(prefix)) : objects
   const { files: dirFiles } = partition(scoped, prefix)
-  const flatFiles = scoped.map((o) => ({ ...o, displayKey: prefix ? o.key.slice(prefix.length) : o.key }))
+  const flatFiles = scoped.map((o) => ({ ...o, displayKey: o.displayName ?? (prefix ? o.key.slice(prefix.length) : o.key) }))
   const levelFiles = flat ? flatFiles : dirFiles
   const systemCount = levelFiles.filter((o) => isSystemFile(o.key)).length
   const visibleFiles = kinds.has('system') ? levelFiles : levelFiles.filter((o) => !isSystemFile(o.key))

package/src/utilities/mediaKinds.js

@@ -127,7 +127,7 @@ export function groupVariants(files) {
   for (const [base, list] of groups) {
     if (list.length < 2) { out.push(list[0]); continue }
     list.sort((a, b) => a.width - b.width)
-    out.push({ ...list[0], displayKey: base, variants: list, totalSize: list.reduce((n, f) => n + (f.size || 0), 0) })
+    out.push({ ...list[0], displayKey: list[0].displayName ?? base, variants: list, totalSize: list.reduce((n, f) => n + (f.size || 0), 0) })
   }
   return out
 }
@@ -140,7 +140,7 @@ export function partition(objects, prefix) {
     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: rel })
+    else files.push({ ...o, displayKey: o.displayName ?? rel })
   }
   return { folders: [...folderSet].sort(), files }
 }

package/src/utilities/mediaSearch.js

@@ -16,7 +16,7 @@ import { kindOf } from './mediaKinds.js'
 
 const toItem = (o, nameOf) => ({
   id: o.key,
-  title: nameOf ? nameOf(o) : o.key.slice(o.key.lastIndexOf('/') + 1) || o.key,
+  title: nameOf ? nameOf(o) : o.displayName ?? (o.key.slice(o.key.lastIndexOf('/') + 1) || o.key),
   keywords: [o.key],
   tags: o.tags ?? [],
   kind: o.kind ?? kindOf(o),