@kolkrabbi/kol-shell 0.46.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "private": false,
   "description": "KOL application shell — fixed 48px NavRail + AppShell layout root, PageShell/PageHeader scaffolds, ContentFilters catalog organism, GridCard, SettingsScaffold, WalkthroughPanel, ShortcutsOverlay. App chrome (kol-framework owns site chrome). Nav items, content, shortcuts and settings are consumer-injected. Sits above @kolkrabbi/kol-{theme,component,framework}.",
   "license": "MIT",

package/src/CatalogPage.jsx

@@ -18,8 +18,11 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  *
  * Semantics are the consumer's: what RECENT / SAVED mean, what an item is,
  * what a click does. `toCard(item, { view, layout })` → `{ key, title, detail,
- * media, actions, onClick, href, onNavigate, expanded, expandedContent, fit, ratio }` is
- * the whole contract — `expanded` / `expandedContent` reach `ContentCard catalog`'s
+ * …every prop ContentCard / ContentRow takes }` — `title`, `detail`, `media`,
+ * `actions`, `onClick`, `href`, `onNavigate`, `expanded`, `expandedContent`, `fit`,
+ * `ratio`, `date`, `size`, `meta`, `tags`, `selected`, `variant`, … — is the whole
+ * contract: the return is SPREAD onto the card or the row (user ruling 2026-09-03,
+ * a composition forwards the whole contract of what it composes) — `expanded` / `expandedContent` reach `ContentCard catalog`'s
  * 2×2 cell (ShellHomeSystemMonitorGaps, kol-monitor 2026-08-27) — and the page
  * HIDES the cell's three neighbours itself (CatalogPageMonitorParity: the
  * consumer never sees the filtered row order, so it cannot; monitor's
@@ -50,7 +53,10 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  *                                 framework container — the site tier, so a brand book adopting this page keeps its geometry
  * @param {ReactNode} trailingActions  the header's RIGHT slot (ContentFilters' — MediaLibrary's SELECT / FLAT); never empty beside the divider
  * @param {number}    minColumn      the grid track's floor in px (default 160); a shelf of three decks passes 280 — the six-track ceiling still applies
- * @param {'catalog'|'file'} rowVariant  the list row (default `catalog`, the 36px no-thumb row); `file` = the 48px thumb row, for a catalog whose grid shows a cover
+ * @param {string}    cardVariant    the grid card's variant, per page (default `catalog`); `toCard` may return `variant` per card
+ * @param {'catalog'|'file'} rowVariant  the list row (default `catalog`, the 36px no-thumb row); `file` = the 48px thumb row, for a catalog whose grid shows a cover —
+ *                                 its slots (`date` · `size` · `meta` · `selected`) come from `toCard` like everything else
+ * @param {'grid'|'stack'} listLayout   the list's container (default `grid`, rows four across — monitor's ruling); `stack` = one row per line
  * @param {ElementType} iconComponent  icon renderer seam for ContentFilters
  * @param {boolean}  showCountOnlyWhenFiltering  (default true)
  * @param {Object}   filtersProps  spread onto ContentFilters last — e.g. `{ mutuallyExclusiveFilters: ['category', 'u_label'] }`
@@ -103,6 +109,13 @@ export default function CatalogPage({
      passes `file`: the 48px thumb row, so the list shows the same cover small
      (kol-client-olina 2026-09-03; user, on the bare row: "ugly ugly ugly"). */
   rowVariant = 'catalog',
+  /* the GRID card's variant, per page; `toCard` may return `variant` per card */
+  cardVariant = 'catalog',
+  /* the LIST's container. `grid` (default) is monitor's ruling — rows four across
+     on a 240 floor, gap 8 (the documented `repeat(4, 1fr)`). `stack` is one row per
+     line, which is what a list of files is (MediaLibrary stacks); olina's deck list
+     rendered three 300px rows side by side (user: "why is it tiny?"). */
+  listLayout = 'grid',
   iconComponent,
   showCountOnlyWhenFiltering = true,
   filtersProps,
@@ -151,14 +164,25 @@ export default function CatalogPage({
             /* the catalog grid is a CLASS (`.kol-catalog-grid`, kol-theme ≥0.137.0) so the
              * filter row's first group can read the track count it renders; `minColumn`
              * reaches it as `--kol-catalog-min` on the page (set on PageShell above) */
-            <div className={layout === 'list' ? undefined : 'kol-catalog-grid'} style={layout === 'list' ? { display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(min(100%, max(240px, calc((100% - 3 * 8px) / 4))), 1fr))', gap: 8 } : undefined}>
+            <div className={layout === 'list' ? undefined : 'kol-catalog-grid'} style={layout === 'list' ? (listLayout === 'stack' ? { display: 'flex', flexDirection: 'column', gap: 8 } : { display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(min(100%, max(240px, calc((100% - 3 * 8px) / 4))), 1fr))', gap: 8 }) : undefined}>
               {rows.map((item, i) => {
                 if (hidden.has(i)) return null
                 const c = cards[i]
                 const key = c.key ?? item.key ?? item.id ?? item.name ?? i
+                /* A COMPOSITION FORWARDS THE WHOLE CONTRACT OF WHAT IT COMPOSES (user
+                 * 2026-09-03: "why wouldn't we as standard practice ALLOW VARIANT CHANGE
+                 * EVERY TIME WE USE THOSE CONTENT CARDS?"). Five tickets on this file in
+                 * one day were the same defect — a key missing from `toCard` because no
+                 * prior consumer had needed it: `ratio`, `trailingActions`, `rowVariant`,
+                 * `date` / `size`, the list container. So `toCard`'s return is SPREAD
+                 * onto the card and the row: every prop either takes is reachable per
+                 * card, today and for props not written yet; `variant` per card beats
+                 * the page's `cardVariant` / `rowVariant`; `fit` keeps its `cover`
+                 * default. `key` is React's and is lifted out first. */
+                const { key: _key, ...forwarded } = c
                 return layout === 'list'
-                  ? <ContentRow key={key} variant={rowVariant} media={c.media} ratio={c.ratio} title={c.title} detail={c.detail} actions={c.actions} onClick={c.onClick} href={c.href} onNavigate={c.onNavigate} />
-                  : <ContentCard key={key} variant="catalog" fit={c.fit ?? 'cover'} ratio={c.ratio} title={c.title} detail={c.detail} media={c.media} actions={c.actions} onClick={c.onClick} href={c.href} onNavigate={c.onNavigate} expanded={c.expanded} expandedContent={c.expandedContent} />
+                  ? <ContentRow key={key} {...forwarded} variant={c.variant ?? rowVariant} />
+                  : <ContentCard key={key} {...forwarded} variant={c.variant ?? cardVariant} fit={c.fit ?? 'cover'} />
               })}
             </div>
             )