@kolkrabbi/kol-shell 0.48.0 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.48.0",
+  "version": "0.50.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",
@@ -12,7 +12,7 @@
     "./src/*": "./src/*"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.174.0",
+    "@kolkrabbi/kol-component": ">=0.178.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
     "@kolkrabbi/kol-theme": ">=0.138.0",
     "gsap": "^3.13.0",
@@ -20,8 +20,8 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
+    "@kolkrabbi/kol-component": "^0.178.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-component": "^0.177.0",
     "@kolkrabbi/kol-framework": "^0.42.0",
     "@kolkrabbi/kol-theme": "^0.138.0"
   },

package/src/CatalogPage.jsx

@@ -1,5 +1,5 @@
 import { useCallback, useRef, useState } from 'react'
-import { ContentCard, ContentFilters, ContentRow } from '@kolkrabbi/kol-component'
+import { ActionButton, ContentCard, ContentFilters, ContentRow, SizeOrDownload, formatSize } from '@kolkrabbi/kol-component'
 import PageShell from './PageShell.jsx'
 import { PageHeader } from '@kolkrabbi/kol-component'
 import WalkthroughPanel from './WalkthroughPanel.jsx'
@@ -37,6 +37,11 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  * variant's A4, so nothing existing moves. Anything `ContentFilters` takes that the page has no
  * prop for goes through `filtersProps` — `mutuallyExclusiveFilters` was the gap.
  *
+ * @param {'catalog'|'shelf'} preset  the whole page as one word (default `catalog` = today's defaults). `shelf` = a
+ *                                 shelf of slide decks: capped · 3 tracks on a 280 floor · `slide` card and row · stacked
+ *                                 list · `kol-tone-secondary` on the root · the All / Recent view strip; `toCard` returns
+ *                                 the deck's fields and handlers — `title date bytes count cover href onNavigate onDownload
+ *                                 onFavourite onDelete favourited` — and the page renders the slots. Explicit props win.
  * @param {Object}   header        PageHeader props — `{ title, subtitle, size, voice, eyebrow }`
  * @param {Array}    items         the objects `ContentFilters` filters and searches
  * @param {Function} toCard        (item, { view, layout }) => card props (see above)
@@ -53,7 +58,8 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  *                                 `bleed` (default) fills the window — the app tier; `capped` centres on the
  *                                 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 {number}    minColumn      the grid track's floor in px (default 160) — a minimum, never a count
+ * @param {number}    maxColumns     the grid's ceiling (default 6, the ruling); a three-deck shelf passes 3 and the tracks share the width
  * @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
@@ -81,18 +87,64 @@ function computeHiddenSet(items, expandedIdx) {
   return hiddenSet
 }
 
+/* PRESETS — a whole page frozen as one word (slide-variant-and-shelf-preset,
+ * kol-client-olina 2026-09-03; user, after building /slide-deck by hand through
+ * eleven props: "this is a look I DO NOT want to do this again… this is a
+ * layout SET" · "freeze this so I can use AS IS again"). `catalog` is today's
+ * defaults, byte-identical. `shelf` is olina's /slide-deck as it stood, every
+ * value read off the render. An explicit prop always wins over its preset. */
+const PRESETS = {
+  catalog: {},
+  shelf: {
+    width: 'capped', maxColumns: 3, minColumn: 280,
+    cardVariant: 'slide', rowVariant: 'slide', listLayout: 'stack',
+    /* one word tones every control on the page (tone-is-the-ground-axis) */
+    className: 'kol-tone-secondary',
+    /* the header's right slot is the view strip — ContentFilters' own idiom */
+    views: [{ value: 'all', label: 'All' }, { value: 'recent', label: 'Recent' }], defaultView: 'all',
+  },
+}
+const stop = (e) => { e.preventDefault(); e.stopPropagation() }
+/* the shelf's DATA → the slide variant's slots, the media admin's idiom
+ * (MediaLibraryPages:704) verbatim from olina's /slide-deck: download is the
+ * control ON the image (chrome="media"), the plate carries star (toggle) and
+ * trash (confirm) in a column, the row carries download · star · trash inline;
+ * the size cell is SizeOrDownload; `count` is the slide count. A slot the
+ * consumer supplies itself is left alone. The consumer writes no JSX for
+ * actions — that is the point of the preset. */
+function toSlideCard(c, { layout }) {
+  const { bytes, count, cover, favourited, onDownload, onFavourite, onDelete, downloadHref, ...rest } = c
+  const list = layout === 'list'
+  return {
+    ...rest,
+    media: rest.media ?? (cover ? <img src={cover} alt="" loading="lazy" /> : null),
+    size: rest.size ?? (bytes != null ? <SizeOrDownload href={downloadHref ?? '#'}>{formatSize(bytes)}</SizeOrDownload> : undefined),
+    meta: rest.meta ?? (count ? `${count} slides` : undefined),
+    control: rest.control ?? (!list && onDownload ? <ActionButton chrome="media" icon="download" confirmIcon="check" label="Download" confirmLabel="Downloaded" onAction={onDownload} /> : undefined),
+    actions: rest.actions ?? ((onFavourite || onDelete || (list && onDownload)) ? (
+      <div className={list ? 'flex items-center gap-2' : 'flex h-full flex-col items-center justify-between'} onClick={stop}>
+        {list && onDownload && <ActionButton chrome="inline" size="sm" icon="download" label="Download" onAction={onDownload} />}
+        {onFavourite && <ActionButton chrome="inline" size="sm" icon={favourited ? 'star-solid' : 'star'} label="Favourite" toggle onAction={onFavourite} />}
+        {onDelete && <ActionButton chrome="inline" size="sm" icon="trash" confirmIcon="check" label="Delete" confirmLabel="Deleted" onAction={onDelete} />}
+      </div>
+    ) : undefined),
+  }
+}
+
 export default function CatalogPage({
+  /* FIRST, so every default below can read it */
+  preset = 'catalog',
   header,
-  width = 'bleed',
+  width = PRESETS[preset]?.width ?? 'bleed',
   items = [],
   toCard,
   filtersTitle,
   filterGroups,
   searchKeys = ['title', 'name'],
-  views,
+  views = PRESETS[preset]?.views,
   view,
   onViewChange,
-  defaultView,
+  defaultView = PRESETS[preset]?.defaultView,
   layouts = LAYOUTS,
   defaultLayout = 'grid',
   walkthrough,
@@ -103,20 +155,24 @@ export default function CatalogPage({
   trailingActions,
   /* the grid track's floor. 160 is a 26-tile catalog's; a shelf of three decks
      wants ~280 so the cards read at all. A ceiling of 6 tracks still applies. */
-  minColumn = 160,
+  minColumn = PRESETS[preset]?.minColumn ?? 160,
+  /* the ceiling — the six-column ruling is a MAXIMUM; a three-deck shelf says 3
+     (kol-client-olina 2026-09-03; user: "why are the cards so small? they could
+     use 2 columns each" — raising the floor to force it was backwards) */
+  maxColumns = PRESETS[preset]?.maxColumns ?? 6,
   /* the LIST row's variant. `catalog` (default) is the 36px GridCard row — title
      and detail on one line, no thumb — which is what every app-tier list was
      ruled on (CatalogPageMonitorParity). A catalog whose grid shows a cover
      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',
+  rowVariant = PRESETS[preset]?.rowVariant ?? 'catalog',
   /* the GRID card's variant, per page; `toCard` may return `variant` per card */
-  cardVariant = 'catalog',
+  cardVariant = PRESETS[preset]?.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',
+  listLayout = PRESETS[preset]?.listLayout ?? 'grid',
   iconComponent,
   showCountOnlyWhenFiltering = true,
   filtersProps,
@@ -142,15 +198,15 @@ export default function CatalogPage({
     observer.current?.disconnect()
     observer.current = null
     if (!el) return
-    const measure = (W) => setCols((c) => { const n = Math.max(1, Math.min(6, Math.floor((W + 24) / (minColumn + 24)))); return c === n ? c : n })
+    const measure = (W) => setCols((c) => { const n = Math.max(1, Math.min(maxColumns, Math.floor((W + 24) / (minColumn + 24)))); return c === n ? c : n })
     measure(el.getBoundingClientRect().width)
     const ro = new ResizeObserver(([entry]) => measure(entry.contentRect.width))
     ro.observe(el)
     observer.current = ro
-  }, [minColumn])
+  }, [minColumn, maxColumns])
 
   return (
-    <PageShell width={width} className={className} style={{ overflow: 'hidden', '--kol-catalog-n': cols ?? undefined, ...style }}>
+    <PageShell width={width} className={`${PRESETS[preset]?.className ?? ''} ${className}`.trim()} style={{ overflow: 'hidden', '--kol-catalog-n': cols ?? undefined, ...style }}>
       {header && <PageHeader {...header} />}
       <div style={{ flex: 1, position: 'relative' }}>
         {open && <WalkthroughPanel steps={walkthrough.steps} iconComponent={walkthrough.iconComponent} />}
@@ -171,7 +227,7 @@ export default function CatalogPage({
           defaultLayout={defaultLayout}
           renderItem={(rows, viewMode, layout) => {
             if (open) return null
-            const cards = rows.map((item) => toCard ? toCard(item, { view: viewMode, layout }) : { title: item.title ?? item.name, detail: item.detail })
+            const cards = rows.map((item) => { const c = toCard ? toCard(item, { view: viewMode, layout }) : { title: item.title ?? item.name, detail: item.detail }; return preset === 'shelf' ? toSlideCard(c, { layout }) : c })
             const hidden = layout === 'list' ? new Set() : computeHiddenSet(rows, cards.findIndex((c) => c.expanded))
             /* COLS IS A CEILING, NOT A COMMAND (CatalogPageMobileColumns,
               * kol-monitor 2026-09-01) — the third home of the defect