@kolkrabbi/kol-component 0.209.0 → 0.210.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.209.0",
+  "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",

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

@@ -73,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
  *