@kolkrabbi/kol-component 0.208.0 → 0.210.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.208.0",
-  "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
+  "version": "0.210.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",
   "main": "./src/index.js",
@@ -34,7 +34,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.27.0"
+    "@kolkrabbi/kol-icons": "workspace:^"
   },
   "files": [
     "src",
@@ -56,4 +56,4 @@
     "access": "public"
   },
   "sideEffects": false
-}
+}

package/src/molecules/ContentCard.jsx

@@ -244,6 +244,23 @@ export default function ContentCard({
    * One prop is not done until every derivation reads it. */
   const framed = box.border != null || (bg ?? box.bg) != null
 
+  /* NO COVER IS NOT A MISSING COVER (content-card-needs-no-cover,
+   * kol-client-olina 2026-09-04). `ContentMedia` turns absent children into an
+   * `AssetPlaceholder` on purpose — a card whose image failed must not collapse
+   * into a text blob, and that dashed MISSING plate is the honest answer for a
+   * media library. It is the wrong answer for a markdown note in a database
+   * row, which has no picture and never will: their `/notes` page drew a wall
+   * of dashed frames with nothing misconfigured.
+   *
+   * The card cannot tell the two apart — only the consumer knows whether a
+   * cover is owed — so it is declared, and `media={false}` declares it: no
+   * media slot at all, text takes the full width. `false` rather than a new
+   * prop because it is React's own idiom for "render nothing", and because
+   * `media={false}` today renders an EMPTY framed box, a state nobody can want.
+   * `media={null}` and an omitted `media` keep the placeholder, so every
+   * existing consumer is untouched. */
+  const noMedia = media === false
+
   const textNode = hasPlate ? (
     <div
       className="kol-card-plate relative"
@@ -251,7 +268,7 @@ export default function ContentCard({
         '--kol-plate-pad': padding,
         '--kol-plate-pad-md': box.padMd,
         padding,
-        marginTop: box.layout === 'stack' ? box.mediaGap : undefined,
+        marginTop: box.layout === 'stack' && !noMedia ? box.mediaGap : undefined,
         borderTop: (plateRule ?? box.plateTop) ? '1px solid var(--kol-fg-04)' : undefined,
         background: box.layout === 'drawer' ? 'var(--kol-surface-inverse)' : box.plateBg,
         color: box.layout === 'drawer' ? 'var(--kol-fg-inverse)' : undefined,
@@ -311,11 +328,15 @@ export default function ContentCard({
     box.layout === 'stack' ? (
       <>
         {heroHeader}
-        <div className="relative">
-          <ContentMedia ratio={r} {...mediaProps}>{media}</ContentMedia>
-          {controlNode}
-          {controlStartNode}
-        </div>
+        {/* the frame-corner controls go with the frame — `.kol-frame-control`
+          * positions against the media box, and there is none */}
+        {!noMedia && (
+          <div className="relative">
+            <ContentMedia ratio={r} {...mediaProps}>{media}</ContentMedia>
+            {controlNode}
+            {controlStartNode}
+          </div>
+        )}
         {textNode}
       </>
     ) : box.layout === 'fill-card' ? (
@@ -326,6 +347,7 @@ export default function ContentCard({
           * card gave each half 174 and the prose 126, and one module's specs
           * ran 1177px tall. The 50% half is a `md:` class now, not an inline
           * style — an inline flex-basis has no breakpoint. */}
+        {!noMedia && (
         <div
           className={`flex-1 min-w-0 min-h-0 relative overflow-hidden ${expanded ? 'max-md:flex-none max-md:aspect-[var(--kol-card-ratio)] md:flex-[0_0_50%]' : ''}`}
           style={{ ...(expanded ? { '--kol-card-ratio': r ?? '3 / 2' } : null), ...(doFlip ? { perspective: '1000px' } : null) }}
@@ -344,6 +366,7 @@ export default function ContentCard({
           {controlNode}
           {controlStartNode}
         </div>
+        )}
         {expanded ? (
           <div
             className="flex flex-1 flex-col justify-between overflow-auto"
@@ -355,11 +378,13 @@ export default function ContentCard({
       </>
     ) : box.layout === 'drawer' ? (
       <>
-        <div className="relative h-full">
-          <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
-          {controlNode}
-          {controlStartNode}
-        </div>
+        {!noMedia && (
+          <div className="relative h-full">
+            <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
+            {controlNode}
+            {controlStartNode}
+          </div>
+        )}
         {/* the plate is INVERSE and hidden until hover — `kol-card-drawer` owns
           * the reveal so the transition sits with the rest of the chrome */}
         {textNode && <div className="kol-card-drawer">{textNode}</div>}
@@ -371,11 +396,13 @@ export default function ContentCard({
        * choreography (kol-theme `.kol-card.has-reveal`), the consumer owns the
        * node (what it says and which face it wears are never the family's). */
       <>
-        <div className="kol-card-canvas-media absolute" style={{ inset: 0 }}>
-          <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
-          {controlNode}
-          {controlStartNode}
-        </div>
+        {!noMedia && (
+          <div className="kol-card-canvas-media absolute" style={{ inset: 0 }}>
+            <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
+            {controlNode}
+            {controlStartNode}
+          </div>
+        )}
         {textNode}
         {reveal != null && (
           <div className="kol-card-reveal absolute inset-0 flex items-center justify-center p-8 pointer-events-none" style={{ zIndex: 2 }}>{reveal}</div>

package/src/molecules/ContentRow.jsx

@@ -14,7 +14,8 @@ import ContentText from './ContentText.jsx'
  *                             (`default` is an alias of `file`). `roster` is the pickable
  *                             row: filled tile, no border or divider, a FIXED 56px height the
  *                             content fills, a 40px square thumb and two truncated lines.
- * @param {ReactNode} media     thumb content (omit → placeholder)
+ * @param {ReactNode|false} media  thumb content (omit → placeholder; `false` → no thumb at all — the
+ *                             content HAS no cover, as against one that failed to load)
  * @param {number|'fill'} thumb  thumb edge px — overrides the ruled default; 0 hides; `'fill'` = a square
  *                             the height of the row's content, whatever the rung (WorkListingRowsAndFilters)
  * @param {string}    ratio     thumb aspect-ratio — overrides the ruled default.
@@ -175,7 +176,13 @@ export default function ContentRow({
   const aliased = ALIAS[variantProp] ?? variantProp
   const variant = aliased.startsWith('showcase') && layout ? LAYOUT_KEY[layout] ?? aliased : aliased
   const box = BOX[variant] ?? BOX.file
-  const thumbPx = thumb ?? box.thumb
+  /* `media={false}` — NO COVER, not a missing one (content-card-needs-no-cover,
+   * kol-client-olina 2026-09-04). The row could already hide its thumb with
+   * `thumb={0}`, but that is a SIZE answering a question about MEANING, and a
+   * consumer listing coverless documents should not have to say it two
+   * different ways on the card and the row. `media={false}` reads the same in
+   * both; `thumb` still wins when it is passed explicitly. */
+  const thumbPx = thumb ?? (media === false ? 0 : box.thumb)
   const padY = (paddingY != null ? `${paddingY}px` : String(box.pad)).trim().split(/\s+/)[0]
 
   /* The md: STEP is a custom property, not a Tailwind variant. Tailwind cannot

package/src/molecules/ContentText.jsx

@@ -214,6 +214,21 @@ const GAPS = {
  * because ContentText is exported and a consumer can drive it directly. */
 const ALIAS = { default: 'file', print: 'catalog', work: 'showcase', typeface: 'showcaseCanvas' }
 
+/* dev-only, and warns ONCE per offending prop — a card family renders these by
+ * the hundred in a list and a per-render warning would bury the first one. */
+const warned = new Set()
+function warnUnknownSlots(unknown) {
+  for (const key of Object.keys(unknown)) {
+    if (warned.has(key)) continue
+    warned.add(key)
+    console.warn(
+      `ContentText: "${key}" is not a text slot and was ignored. `
+      + 'Slots: title · body · eyebrow (kicker) · detail · date · size · meta · tags, '
+      + 'each with a matching *Class. This warning is dev-only.',
+    )
+  }
+}
+
 export default function ContentText({
   variant: variantProp = 'file',
   form = 'card',
@@ -222,7 +237,16 @@ export default function ContentText({
   titleClass, bodyClass, eyebrowClass, kickerClass, detailClass, dateClass, sizeClass, metaClass, tagsClass,
   text,
   className = '',
+  ...unknown
 }) {
+  /* AN UNKNOWN SLOT SAYS SO (content-card-needs-no-cover aside, kol-client-olina
+   * 2026-09-04). They passed `summary`, every card rendered EMPTY, and nothing
+   * — build, lint or console — said a word; it cost an hour. A card's text
+   * slots are a closed vocabulary and a typo in one is indistinguishable from
+   * missing data, which is the worst kind of silent failure: the page looks
+   * built and is blank. Dev only, and it names the vocabulary rather than just
+   * the mistake, because "summary is not a slot" does not tell you `body` is. */
+  if (import.meta.env.DEV) warnUnknownSlots(unknown)
   /* `kicker` / `kickerClass` = aliases of `eyebrow` / `eyebrowClass` (2026-08-27) */
   eyebrow = eyebrow ?? kicker
   eyebrowClass = eyebrowClass ?? kickerClass

package/src/molecules/KindPreview.jsx

@@ -28,6 +28,11 @@ import DocPage from './DocPage.jsx'
  * `<img>` so it can read the dimensions). Text fetches cap at `textLimit`.
  *
  * @param {object}   o          the object — `{ key, contentType?, displayKey?, segmentCount? }`
+ * @param {string}   text       content ALREADY IN HAND — skips the fetch and joins the same render
+ *                              path. For a source with no file behind it (a database row). Pass
+ *                              `kind` with it: there is no extension to classify by
+ * @param {string}   kind       classification override — `markdown` · `json` · `yaml` · `code` ·
+ *                              `text` · `image` · `video` · `audio`. Wins over `kindOf(o)`
  * @param {Function} urlOf      (o) => string — the object's public URL (default: `o.url`)
  * @param {string}   poster     a poster URL for HLS (the sibling image)
  * @param {Function} kindOf · extOf   classification seams (defaults: the DS mediaKinds)
@@ -63,13 +68,38 @@ function useTextContent(url, enabled, limit) {
   return { ...result, loading: enabled && result.url !== url }
 }
 
-export default function KindPreview({ o, urlOf = (x) => x.url, poster, kindOf = defaultKindOf, extOf = defaultExtOf, kindLabel = KIND_LABEL, textLimit = TEXT_LIMIT }) {
-  const kind = kindOf(o)
+export default function KindPreview({ o, text: textProp, kind: kindProp, urlOf = (x) => x.url, poster, kindOf = defaultKindOf, extOf = defaultExtOf, kindLabel = KIND_LABEL, textLimit = TEXT_LIMIT }) {
+  /* CONTENT IN HAND, OR A URL TO FETCH (content-card-needs-no-cover,
+   * kol-client-olina 2026-09-04; shape ruled by kol-r2b2, whose component this
+   * is). A markdown note in a D1 row has no file and no URL behind it, so the
+   * fetch has nothing to pull — but the RENDER path is the one this component
+   * already owns, and a second previewer in the estate is what the lobby exists
+   * to prevent.
+   *
+   * `text` sits BESIDE `o`, not inside it: `o` is the media object — key, size,
+   * contentType, uploaded — and that shape is what `kindOf`, `posterFor` and
+   * the resolution-set grouping all read. Prose inside it would make the object
+   * mean two things.
+   *
+   * `kind` is not optional sugar. Classification reads the EXTENSION off the
+   * key, and a database row has no filename, so `text` alone lands on `other`
+   * and renders the right content as the wrong thing — worse than the
+   * placeholder it replaces. The two ship together or the seam half-works for
+   * the only caller that asked. Precedent: `urlOf`, `kindOf`, `kindLabel` and
+   * `partition` are already caller-supplied for the same reason — the DS does
+   * not decide what a consumer's object IS. */
+  const kind = kindProp ?? kindOf(o)
   const url = urlOf(o)
   const ext = extOf(o.key)
   const name = o.displayKey ?? o.key
   const isText = kind === 'text' || kind === 'code' || kind === 'markdown' || kind === 'json' || kind === 'yaml'
-  const { loading, text, error, truncated } = useTextContent(url, isText, textLimit)
+  const fetched = useTextContent(url, isText && textProp == null, textLimit)
+  /* content in hand is never loading and never errors — there is nothing to
+   * wait for. It still honours `textLimit`, so one long note cannot outgrow a
+   * tile the way a fetched one cannot. */
+  const { loading, text, error, truncated } = textProp != null
+    ? { loading: false, error: null, text: String(textProp).slice(0, textLimit), truncated: String(textProp).length > textLimit }
+    : fetched
 
   if (kind === 'playlist') {
     return (

package/src/organisms/ColumnBrowser.jsx

@@ -57,6 +57,7 @@ import { GRAB_COLUMN } from '../utilities/motion.js'
  * @param {Function} kindOf       (o) => 'image' | 'video' | 'audio' | string
  * @param {Object}   kindLabel    kind → label shown when there is no visual preview
  * @param {Function} formatSize   (bytes) => string
+ * @param {Function} formatDate   (isoString) => string — the row/preview date, ISO date-only by default
  * @param {Function} partition    (objects, level) => { folders: string[], files: object[] }
  * @param {Function} renderPreview  (file) => ReactNode — replaces the preview column's media frame (the facts stay — Dimensions and Length are read off whatever <img> / <video> / <audio> the node loads); without it images render the organism's <img>, everything else the DS KindPreview
  * @param {number}   height         controlled height in px (omit for uncontrolled)
@@ -72,6 +73,10 @@ import { GRAB_COLUMN } from '../utilities/motion.js'
  * @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
+ * NOTE, both seams: the key/prefix they receive is the one the browser was GIVEN, verbatim. A
+ * consumer that mounts a virtual root above real storage (multi-bucket browse hands these
+ * `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 {'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
  *
@@ -97,6 +102,54 @@ const defaultFormatSize = (bytes) => {
   if (bytes < 1024 * 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`
   return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`
 }
+
+/* THE STACK'S ROW ORDER — walked, not iterated, and lifted out of the component
+ * so it is reachable by a check (the defect below is invisible to every
+ * structural assertion: the rows are all present and each carries the right
+ * `depth`, they are merely in the wrong ORDER).
+ *
+ * The open folder's children have to land DIRECTLY under its own row. That
+ * adjacency IS inline expand, and inline expand is the whole ruling. A flat
+ * loop over `openPath` appends each level after the one before it, so an open
+ * folder's children surfaced below its last SIBLING and below that level's
+ * files (D1, kol-r2b2 2026-09-04) — which read as an indent bug rather than a
+ * sequence bug, and is how a comment claiming "the loop IS the path" survived.
+ *
+ * @param {object[]} objects   the flat key space
+ * @param {string[]} openPath  the open levels, shallowest first
+ * @param {Function} partition (objects, level) => { folders, files }
+ * @returns {object[]} rows — `folder` | `file` | `empty`, each with its `depth`
+ */
+export function stackRows(objects, openPath, partition) {
+  const rows = []
+  const walk = (depth) => {
+    const level = openPath[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 })
+      if (isOpen) walk(depth + 1)
+    })
+    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 })
+  }
+  walk(0)
+  return rows
+}
+
+/* A ROW SHOWS A DATE, NOT A TIMESTAMP. `2026-06-19T02:00:14.629Z` is storage
+ * answering "when" in its own voice, and it shipped into the stack meta line
+ * because the value arrives as a string and a string renders (D2, kol-r2b2
+ * 2026-09-04). A seam beside `formatSize` for the same reason that one is a
+ * seam: how a date reads is the consumer's call, not the DS's. The default is
+ * ISO-8601 date-only — unambiguous everywhere, which no locale format is.
+ * Anything unparseable comes through verbatim rather than as `Invalid Date`. */
+const defaultFormatDate = (v) => {
+  if (!v) return ''
+  const d = new Date(v)
+  return Number.isNaN(d.getTime()) ? String(v) : d.toISOString().slice(0, 10)
+}
 /* kol-r2b2's partition: the next path segment is a folder, the rest are files */
 const defaultPartition = (objects, prefix) => {
   const folderSet = new Set()
@@ -227,7 +280,7 @@ function Row({
   )
 }
 
-function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview, width }) {
+function Preview({ o, urlOf, kindOf, kindLabel, formatSize, formatDate, renderPreview, width }) {
   // Pixel size and length come from the loaded media itself — the bucket stores
   // none. `{ w, h }` off an <img> load, `{ w, h, len }` off a <video>'s and
   // `{ len }` off an <audio>'s loadedmetadata (ColumnBrowserMediaFacts, kol-r2b2
@@ -243,7 +296,7 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview, width
     ['Size', formatSize(o.size)],
     ...(sized ? [['Dimensions', dims?.w ? `${dims.w} × ${dims.h} px` : '…']] : []),
     ...(timed ? [['Length', dims?.len != null ? formatLength(dims.len) : '…']] : []),
-    ['Date', o.uploaded ? new Date(o.uploaded).toISOString().slice(0, 10) : '—'],
+    ['Date', formatDate(o.uploaded) || '—'],
   ]
   return (
     <div className="kol-column-browser-preview shrink-0 overflow-y-auto p-4 flex flex-col gap-4" style={{ width }}>
@@ -343,6 +396,7 @@ export default function ColumnBrowser({
   kindOf = defaultKindOf,
   kindLabel = DEFAULT_KIND_LABEL,
   formatSize = defaultFormatSize,
+  formatDate = defaultFormatDate,
   partition = defaultPartition,
   renderPreview,
   height,
@@ -563,23 +617,9 @@ export default function ColumnBrowser({
 
     /* 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 rows = stackRows(objects, openPath, partition)
 
-    const metaOf = (o) => [o.size != null && formatSize(o.size), o.uploaded].filter(Boolean).join(' · ')
+    const metaOf = (o) => [o.size != null && formatSize(o.size), formatDate(o.uploaded)].filter(Boolean).join(' · ')
 
     return (
       <div
@@ -741,7 +781,7 @@ export default function ColumnBrowser({
       })}
       {shown && (
         <>
-          <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} renderPreview={renderPreview} width={widthOf('preview')} />
+          <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} formatDate={formatDate} renderPreview={renderPreview} width={widthOf('preview')} />
           <ResizeHandle axis="x" onDrag={resizeCol('preview')} onEnd={endDrag} />
         </>
       )}

package/src/organisms/MediaLibraryPages.jsx

@@ -314,6 +314,17 @@ const profileOf = (objects, rawFiles, systemCount) => ({
 export function MediaLibraryBrowse({
   client, title = 'MEDIA', bucket, onBucketChange, prefix: prefixProp, onPrefix, defaults, settings: settingsProp, onSettingsChange,
   folderTree, headerActions, refreshKey, onOpen, autoFocus = false, settingsFooter, className = '',
+  /* PASS-THROUGHS TO `ColumnBrowser`. A documented prop this page does not
+   * forward is a prop no consumer of the PAGE can reach, which makes the seam
+   * fictional — `thumbnailFor` and `folderMeta` shipped, were announced, and
+   * rendered as if they never existed because this signature ended before them
+   * (ColumnBrowserMobileViews items 10 + 13, kol-r2b2 2026-09-04). Second time
+   * this shape bit: `SettingsPanel` documented a `footer` slot this file
+   * hardcoded past. The rule the sweep leaves behind — WHEN A PROP IS ADDED TO
+   * `ColumnBrowser`, IT IS ADDED HERE IN THE SAME EDIT, unless the page holds a
+   * real opinion about it (it owns `height`, the widths and `partition`, so
+   * those are deliberately absent from this list). */
+  thumbnailFor, folderMeta, formatDate, stackView,
 }) {
   const [ownPrefix, setOwnPrefix] = useState('')
   const prefix = prefixProp ?? ownPrefix
@@ -483,6 +494,10 @@ export function MediaLibraryBrowse({
               kindOf={kindOf}
               kindLabel={KIND_LABEL}
               formatSize={formatSize}
+              formatDate={formatDate}
+              thumbnailFor={thumbnailFor}
+              folderMeta={folderMeta}
+              stackView={stackView}
               renderPreview={(o) => {
                 const real = { ...o, key: o.key.slice(VROOT.length) }
                 if (isImage(real.contentType)) return <ImageFrame src={mediaUrl(real.key)} />