@kolkrabbi/kol-shell 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.5.0",
+  "version": "0.6.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,7 +20,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.52.0",
+    "@kolkrabbi/kol-component": "^0.53.0",
     "@kolkrabbi/kol-framework": "^0.22.0",
     "@kolkrabbi/kol-icons": "^0.17.0",
     "@kolkrabbi/kol-theme": "^0.46.1"

package/src/PageHeader.jsx

@@ -1,22 +1,47 @@
 /**
- * PageHeader — page title + mono subtitle. The mirror cut (subtitle
- * `kol-mono-14`, the newer voice) wins over monitor's `kol-text-sm`; override
- * via a wrapper if a consumer needs otherwise. Takes title/subtitle as values
- * so tab-driven headers (Settings) stop re-implementing the markup inline.
+ * PageHeader — the page's masthead: an optional eyebrow, the title, and a mono
+ * subtitle.
  *
- * The title was `kol-heading-sm` — a RETIRED t-shirt stop with NO RULE anywhere
- * in kol-theme, so every page title in every shell app has been falling through
- * to the browser's default h1 with no DS type on it at all (found 2026-08-15).
- * Mapped to the numeric scale at `kol-sans-heading-03` (32px), the same way the
- * dead `kol-mono-sm` and `kol-helper-lg` stops were mapped.
+ * 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)
  */
-export default function PageHeader({ title, subtitle }) {
+const TITLE = {
+  sm: 'kol-sans-heading-03',
+  md: 'kol-sans-display-03',
+  lg: 'kol-sans-display-02',
+}
+
+export default function PageHeader({ eyebrow, title, subtitle, size = 'md', className = '' }) {
   return (
-    <>
-      {/* gap inline, never in the type class — margin in a shared type class
-          leaks estate-wide (ShellHeaderFilterRefinements, 2026-08-15) */}
-      <h1 className="text-fg-96 kol-sans-heading-03" style={{ marginBottom: 8 }}>{title}</h1>
-      <p className="text-fg-48 kol-mono-14" style={{ marginBottom: 40 }}>{subtitle}</p>
-    </>
+    /* 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 }}>
+      {eyebrow && (
+        <p className="text-fg-48 kol-mono-12" style={{ marginBottom: 12 }}>{eyebrow}</p>
+      )}
+      <h1 className={`text-fg-96 ${TITLE[size] ?? TITLE.md}`}>{title}</h1>
+      {subtitle && (
+        <p className="text-fg-48 kol-mono-14" style={{ marginTop: 12 }}>{subtitle}</p>
+      )}
+    </header>
   )
 }