@kolkrabbi/kol-shell 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.14.0",
+  "version": "0.15.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",
@@ -20,10 +20,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.119.0",
-    "@kolkrabbi/kol-framework": "^0.34.0",
+    "@kolkrabbi/kol-component": "^0.121.1",
     "@kolkrabbi/kol-icons": "^0.24.0",
-    "@kolkrabbi/kol-theme": "^0.81.0"
+    "@kolkrabbi/kol-framework": "^0.35.0",
+    "@kolkrabbi/kol-theme": "^0.83.0"
   },
   "files": [
     "src",

package/src/PageHeader.jsx

@@ -29,18 +29,34 @@
  *                    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, size = 'md', voice = 'sans', titleClass, className = '' }) {
+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 */
+  const cluster = actions && <div className="flex items-center gap-4 shrink-0">{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: 40 }}>
+    <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
@@ -54,9 +70,24 @@ export default function PageHeader({ eyebrow, title, subtitle, size = 'md', voic
           {eyebrow}
         </p>
       )}
-      <h1 className={`text-fg-96 ${titleClass ?? roles[size] ?? roles.md}`}>{title}</h1>
-      {subtitle && (
-        <p className="text-oq-64 kol-mono-14" style={{ marginTop: 12 }}>{subtitle}</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>
   )