@kolkrabbi/kol-shell 0.42.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.42.0",
+  "version": "0.44.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",
@@ -14,16 +14,16 @@
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.174.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
-    "@kolkrabbi/kol-theme": ">=0.84.0",
+    "@kolkrabbi/kol-theme": ">=0.136.0",
     "gsap": "^3.13.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
     "@kolkrabbi/kol-component": "^0.176.0",
-    "@kolkrabbi/kol-framework": "^0.40.0",
+    "@kolkrabbi/kol-framework": "^0.41.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-theme": "^0.134.0"
+    "@kolkrabbi/kol-theme": "^0.136.0"
   },
   "files": [
     "src",

package/src/CatalogPage.jsx

@@ -45,6 +45,11 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  * @param {string}   defaultLayout 'grid' (default) | 'list'
  * @param {{steps: Array, open: boolean, iconComponent?: ElementType}} walkthrough  the panel over the catalog
  * @param {ReactNode} actions      the bottom row's buttons
+ * @param {'bleed'|'capped'} width   the page's TIER, forwarded to PageShell (two-page-scaffolds-one-job, 2026-09-03):
+ *                                 `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 {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'] }`
@@ -70,6 +75,7 @@ function computeHiddenSet(items, expandedIdx) {
 
 export default function CatalogPage({
   header,
+  width = 'bleed',
   items = [],
   toCard,
   filtersTitle,
@@ -83,6 +89,13 @@ export default function CatalogPage({
   defaultLayout = 'grid',
   walkthrough,
   actions,
+  /* the header's RIGHT slot — where MediaLibrary puts SELECT / FLAT. CatalogPage
+     shipped with no way to fill it, so every catalog page rendered an empty slot
+     beside the divider (kol-client-olina 2026-09-03, on /slide-deck). */
+  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,
   iconComponent,
   showCountOnlyWhenFiltering = true,
   filtersProps,
@@ -92,7 +105,7 @@ export default function CatalogPage({
 }) {
   const open = walkthrough?.open === true
   return (
-    <PageShell className={className} style={{ overflow: 'hidden', ...style }}>
+    <PageShell width={width} className={className} style={{ overflow: 'hidden', ...style }}>
       {header && <PageHeader {...header} />}
       <div style={{ flex: 1, position: 'relative' }}>
         {open && <WalkthroughPanel steps={walkthrough.steps} iconComponent={walkthrough.iconComponent} />}
@@ -105,6 +118,7 @@ export default function CatalogPage({
           showCountOnlyWhenFiltering={showCountOnlyWhenFiltering}
           iconComponent={iconComponent}
           viewModeOptions={views}
+          trailingActions={trailingActions}
           viewMode={view}
           onViewModeChange={onViewChange}
           defaultViewMode={defaultView}
@@ -127,13 +141,13 @@ export default function CatalogPage({
               * six-column ruling — below the ceiling the hide-set is
               * desktop-only geometry. */
             return (
-            <div style={{ display: 'grid', gridTemplateColumns: layout === 'list' ? 'repeat(auto-fill, minmax(min(100%, max(240px, calc((100% - 3 * 8px) / 4))), 1fr))' : 'repeat(auto-fill, minmax(min(100%, max(160px, calc((100% - 5 * 24px) / 6))), 1fr))', gap: layout === 'list' ? 8 : 24 }}>
+            <div style={{ display: 'grid', gridTemplateColumns: layout === 'list' ? 'repeat(auto-fill, minmax(min(100%, max(240px, calc((100% - 3 * 8px) / 4))), 1fr))' : `repeat(auto-fill, minmax(min(100%, max(${minColumn}px, calc((100% - 5 * 24px) / 6))), 1fr))`, gap: layout === 'list' ? 8 : 24 }}>
               {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
                 return layout === 'list'
-                  ? <ContentRow key={key} variant="catalog" title={c.title} detail={c.detail} actions={c.actions} onClick={c.onClick} href={c.href} onNavigate={c.onNavigate} />
+                  ? <ContentRow key={key} variant="catalog" 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} />
               })}
             </div>

package/src/PageShell.jsx

@@ -6,8 +6,19 @@
  * `mode="fixed"`: height 100vh, overflow hidden — pair with a `flex:1
  * overflow:auto` body (the settings idiom; SettingsScaffold does this).
  *
- * Gutter is `--kol-shell-page-pad` (kol-theme). `PageBleed` breaks it for
- * full-width embeds (monitor's rack bleed).
+ * Gutter is `--kol-shell-page-pad` (kol-theme) — since theme 0.135.0 an alias
+ * of `--kol-pad-section-x`, the ONE page-content ladder every `.kol-page`
+ * wears (two-page-scaffolds-one-job, kol-client-olina 2026-09-03: two ladders
+ * for one job agreed only at 48). `PageBleed` breaks it for full-width embeds
+ * (monitor's rack bleed).
+ *
+ * THE GEOMETRY IS A CLASS — `.kol-shell-page` (+ `--fixed`, `--capped`), in
+ * kol-components-shell.css — so a consumer has a selector to reach; inline is
+ * the `style` prop only. `width` is the TIER: `bleed` (default) fills the
+ * window, the app tier; `capped` takes the framework container ladder and
+ * centres, the site tier — the one real difference between this and a
+ * `.kol-page`, and a prop so a site adopting the shipped catalog page does
+ * not silently get app geometry.
  *
  * `scrollbar-gutter: stable` on both modes (PageShellScrollbarGutter,
  * kol-monitor 2026-08-28 — user: "Create is the odd one out"). A page's content
@@ -39,40 +50,31 @@
  * `AppShell pageWash`, a transparent wash over the shell's primary back —
  * the lightness steps up and the structure stays visible, which an opaque
  * surface swap would hide. The ink stays `text-auto` (surface-on-primary).
+ * ONE OWNER PER PIXEL (2026-09-03): the variable means what is LEFT to paint.
+ * kol-shell's `AppShell` hands the wash down for this to paint; kol-framework's
+ * `PageLayout` paints it on its own plane and hands down `transparent`, so a
+ * PageShell inside it does not paint it again (it used to — two 0.02 layers).
+ *
+ * @param {'scroll'|'fixed'} mode   scroll (default) | fixed — see above
+ * @param {'bleed'|'capped'} width  bleed (default, the app tier) | capped (the site tier — `--kol-container-max`, centred)
+ * @param {string}  className
+ * @param {object}  style           inline — the one thing that stays inline
  */
-export default function PageShell({ mode = 'scroll', className = '', style, children }) {
-  const modeStyle =
-    mode === 'fixed'
-      ? { height: '100vh', overflow: 'hidden' }
-      : { minHeight: '100vh' }
+export default function PageShell({ mode = 'scroll', width = 'bleed', className = '', style, children }) {
   return (
     <div
-      className={`text-auto ${className}`.trim()}
-      style={{
-        background: 'var(--kol-shell-page-wash, var(--kol-surface-primary))',
-        padding: 'var(--kol-shell-page-pad)',
-        scrollbarGutter: 'stable',
-        display: 'flex',
-        flexDirection: 'column',
-        ...modeStyle,
-        ...style,
-      }}
+      className={`kol-shell-page${mode === 'fixed' ? ' kol-shell-page--fixed' : ''}${width === 'capped' ? ' kol-shell-page--capped' : ''} text-auto ${className}`.trim()}
+      style={style}
     >
       {children}
     </div>
   )
 }
 
-/** Full-bleed slot — cancels PageShell's horizontal gutter. */
+/** Full-bleed slot — cancels PageShell's horizontal gutter (`.kol-shell-page-bleed`). */
 export function PageBleed({ style, children }) {
   return (
-    <div
-      style={{
-        marginLeft: 'calc(var(--kol-shell-page-pad) * -1)',
-        marginRight: 'calc(var(--kol-shell-page-pad) * -1)',
-        ...style,
-      }}
-    >
+    <div className="kol-shell-page-bleed" style={style}>
       {children}
     </div>
   )