@kolkrabbi/kol-shell 0.40.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.40.0",
+  "version": "0.42.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.127.0",
+    "@kolkrabbi/kol-component": ">=0.174.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
     "@kolkrabbi/kol-theme": ">=0.84.0",
     "gsap": "^3.13.0",
@@ -20,10 +20,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.162.0",
+    "@kolkrabbi/kol-component": "^0.176.0",
+    "@kolkrabbi/kol-framework": "^0.40.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-framework": "^0.36.0",
-    "@kolkrabbi/kol-theme": "^0.128.0"
+    "@kolkrabbi/kol-theme": "^0.134.0"
   },
   "files": [
     "src",

package/src/CatalogPage.jsx

@@ -1,6 +1,6 @@
 import { ContentCard, ContentFilters, ContentRow } from '@kolkrabbi/kol-component'
 import PageShell from './PageShell.jsx'
-import PageHeader from './PageHeader.jsx'
+import { PageHeader } from '@kolkrabbi/kol-component'
 import WalkthroughPanel from './WalkthroughPanel.jsx'
 
 /* taxonomy-ok: organism — nests PageShell / PageHeader / WalkthroughPanel (relative) + kol-component's ContentFilters + ContentCard / ContentRow */
@@ -18,7 +18,7 @@ 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 }` is
+ * media, actions, onClick, href, onNavigate, expanded, expandedContent, fit, ratio }` is
  * the whole contract — `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
@@ -27,7 +27,10 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  * instead of reflowing around the expanded card); `fit` (`cover` default | `natural` | `compact`) is the
  * card's media fit, PER CARD because one catalog mixes photographs (cover) and
  * diagrams (natural) — CatalogPageCardFit, kol-monitor: a rack preview wider
- * than the card lost its left rail to `cover`. Anything `ContentFilters` takes that the page has no
+ * than the card lost its left rail to `cover`; `ratio` (catalogpage-card-ratio, kol-client-olina
+ * 2026-09-03) is the card's aspect, PER CARD for the same reason — one page renders the same artwork
+ * at 1:1, 4:5 and 9:16 side by side, and a deck is a 16:9 stage — unset falling through to the
+ * 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 {Object}   header        PageHeader props — `{ title, subtitle, size, voice, eyebrow }`
@@ -131,7 +134,7 @@ export default function CatalogPage({
                 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} />
-                  : <ContentCard key={key} variant="catalog" fit={c.fit ?? 'cover'} 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} />
+                  : <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/NavRail.jsx

@@ -50,7 +50,7 @@ import Logomark from './Logomark.jsx'
  * method sections; on one level they flatten into an icon column built for five
  * destinations and the section names have nowhere to render at all.
  *
- * L2 is NOT a `Button`: the icon-button ladder is sm 28 / md 32 / lg 36 and this
+ * L2 is NOT a `Button`: the icon-button ladder is 22/26/32/40 (2026-09-03) and this
  * rung is 20 — there is nothing below sm, and adding one is a change to that
  * ladder's law, which is the user's call and not this ticket's. The row is
  * written directly and keys `aria-current`, so kol-theme's

package/src/SettingsScaffold.jsx

@@ -1,7 +1,7 @@
 import { useState } from 'react'
 import { ContentFilters, IconFrame } from '@kolkrabbi/kol-component'
 import PageShell from './PageShell.jsx'
-import PageHeader from './PageHeader.jsx'
+import { PageHeader } from '@kolkrabbi/kol-component'
 
 /**
  * SettingsScaffold — the settings-page idiom both shells re-implemented inline:

package/src/index.js

@@ -15,7 +15,9 @@ export { NavHiddenContext, useNavHidden } from './navHidden.js'
 export { SettingsToggleContext, useSettingsToggle } from './settingsToggle.js'
 export { default as NavRail } from './NavRail.jsx'
 export { default as PageShell, PageBleed } from './PageShell.jsx'
-export { default as PageHeader } from './PageHeader.jsx'
+/* PageHeader MOVED to @kolkrabbi/kol-component 2026-09-03 (page-header-one-masthead).
+ * Not re-exported: every kol-shell consumer already has kol-component as a peer,
+ * so the import path changes and nothing else. See docs retirements. */
 /* ContentFilters is NOT exported here — it lives in @kolkrabbi/kol-component,
  * where it always did. This package shipped a recreated duplicate 0.1.0–0.2.0;
  * retired 2026-08-15, quarantined in _tmp/. Import it from kol-component. */

package/src/PageHeader.jsx

@@ -1,109 +0,0 @@
-/**
- * PageHeader — the page's masthead: an optional eyebrow, the title, and a mono
- * subtitle.
- *
- * TWO SCALES, because two things were being called a page header. An app page
- * (monitor's Library, mirror's settings) wears a compact heading; a SITE page
- * (kol-website's /work) opens on the display scale and the difference is not a
- * preference, it is which register you are in. `size` picks:
- *
- *   sm   kol-sans-heading-03  32px — app chrome, a titled panel
- *   md   kol-sans-display-03  36 / 42 / 48px — the default page masthead
- *   lg   kol-sans-display-02  44 / 56 / 64px — a landing or section opener
- *
- * The title used to be `kol-heading-sm`, a retired t-shirt stop with NO rule
- * anywhere in kol-theme, so every page title in every shell app fell through to
- * the browser's default h1 (found 2026-08-15). It was mapped to heading-03,
- * which was still too quiet for a page — hence the scale.
- *
- * `eyebrow` is the small label above the title (kol-website's "USE CASES").
- * It self-hides when unset, so an app page passes nothing and gets nothing.
- *
- * @param {ReactNode} eyebrow   small label above the title
- * @param {ReactNode} title
- * @param {ReactNode} subtitle  mono line under the title
- * @param {string}    size      sm | md | lg (default md)
- * @param {'sans'|'mono'} voice  the title's family (default sans). `mono` = the
- *                    app tier's masthead (PageHeaderMonoTitle, kol-fxr 2026-08-27 —
- *                    user ruling: kol-monitor's JetBrains Mono 32 / 500 is the look):
- *                    kol-mono-heading-03 · kol-mono-display-03 · kol-mono-display-02
- *                    (kol-theme ≥0.67.0). The subtitle stays kol-mono-14.
- * @param {string}    titleClass  replaces the title role whole (the ContentText seam)
- * @param {ReactNode} actions   a control cluster on the SUBTITLE's first baseline — on the title's
- *                    when there is no subtitle (PageHeaderTrailingSlot, kol-website 2026-08-28;
- *                    kol-r2b2's header is the reference: wordmark left, controls right, on the
- *                    line). Without it the consumer wrapped the header in a flex row and got the
- *                    h1's baseline, or re-rendered the subtitle as a bare <p> off copied classes
- *                    with an `!important` on the margin — a DS text role re-implemented outside.
- * @param {string}    subtitleMaxWidth  the lede's measure (e.g. '800px' or '60ch'), a prop
- *                    instead of a consumer selector reaching inside
- * The bottom rhythm is `--kol-page-header-mb` (default 40px): inline, as before, but through a
- * variable a consumer can re-point where an inline literal could only be `!important`-ed.
- */
-const TITLE = {
-  sans: { sm: 'kol-sans-heading-03', md: 'kol-sans-display-03', lg: 'kol-sans-display-02' },
-  mono: { sm: 'kol-mono-heading-03', md: 'kol-mono-display-03', lg: 'kol-mono-display-02' },
-}
-
-export default function PageHeader({ eyebrow, title, subtitle, actions, subtitleMaxWidth, size = 'md', voice = 'sans', titleClass, className = '' }) {
-  const roles = TITLE[voice] ?? TITLE.sans
-  const h1 = <h1 className={`text-fg-96 ${titleClass ?? roles[size] ?? roles.md}`}>{title}</h1>
-  const lede = subtitle && <p className="text-oq-64 kol-mono-14 min-w-0" style={{ marginTop: actions ? undefined : 12, maxWidth: subtitleMaxWidth }}>{subtitle}</p>
-  /* The cluster shares a baseline row with the lede (or the title): flexbox
-     exposes a flex item's FIRST baseline, so putting them in one row is the one
-     way to land on the subtitle's line rather than the h1's.
-     
-     AND IT CONTRIBUTES NO HEIGHT (PageHeaderActionsGrowsBlock, kol-fxr
-     2026-08-28). A flex row takes its tallest child, so a cluster of `sm`
-     controls (28px since kol-theme 0.90.0) against a one-line `kol-mono-14`
-     lede (18px) made the masthead 10px taller — measured, monitor's `/` at 65.2
-     against fxr's `/settings` at 75.2 with identical titles. The masthead is the
-     one block every page of an app shares, so a page with a control cluster sat
-     10px lower than every page without one, with no way to opt out.
-     
-     `h-0` + `self-center` is the fix and it is not a magic number: a zero-height
-     box centred on the row makes the children overflow it symmetrically, so the
-     row's height is the TEXT's and the cluster is free at any rung (the gap is
-     10px at `sm`, 14 at `md` — a constant would have been wrong). Horizontal
-     layout is untouched: the box still takes its width, so `justify-between`
-     holds and a long lede cannot run under the controls. */
-  const cluster = actions && <div className="flex items-center gap-4 shrink-0 h-0 self-center">{actions}</div>
-  return (
-    /* the block owns its own rhythm — margins inline, never in a shared type
-       class, which leaks estate-wide (ShellHeaderFilterRefinements, 2026-08-15) */
-    <header className={`flex flex-col ${className}`.trim()} style={{ marginBottom: 'var(--kol-page-header-mb, 40px)' }}>
-      {eyebrow && (
-        /* HELPER, not mono (user ruling 2026-08-15). An eyebrow is single-line
-           chrome — that is the whole definition of the `kol-helper-*` ramp, and
-           it carries its own tracking, so no inline letter-spacing here.
-           Uppercase, and off `fg-48`: under half the ink read as disabled
-           rather than quiet, and this is a live label, not a footnote. */
-        <p
-          className="text-oq-64 kol-helper-12"
-          style={{ marginBottom: 12, textTransform: 'uppercase' }}
-        >
-          {eyebrow}
-        </p>
-      )}
-      {actions && subtitle ? (
-        <>
-          {h1}
-          <div className="flex items-baseline justify-between gap-6" style={{ marginTop: 12 }}>
-            {lede}
-            {cluster}
-          </div>
-        </>
-      ) : actions ? (
-        <div className="flex items-baseline justify-between gap-6">
-          {h1}
-          {cluster}
-        </div>
-      ) : (
-        <>
-          {h1}
-          {lede}
-        </>
-      )}
-    </header>
-  )
-}