@kolkrabbi/kol-framework 0.38.0 → 0.40.0

package/README.md

@@ -26,17 +26,17 @@ chrome above the theme's type layer and the same package renders differently
 per consumer.
 
 ```jsx
-import { AppShell } from '@kolkrabbi/kol-framework'
-import { NAV_TREE, getActivePage } from './sidebars.config'
+import { PageLayout } from '@kolkrabbi/kol-framework'
+import { NAV_TREE } from './sidebars.config'
 
-<AppShell navTree={NAV_TREE} getActivePage={getActivePage} />
+<PageLayout navTree={NAV_TREE} pageWash="var(--kol-fg-02)" />
 ```
 
-Exports: `AppShell`, `SideNav`, `ThemeToggle`, `Layout`, `PageSection`, `PortalFooter`, `ScrollToTop`, `BrandHero`, `SubPageHero`.
+Exports: `PageLayout` (alias `AppShell`), `SideNav`, `ThemeToggle`, `Layout`, `PageHero` (aliases `BrandHero`, `SubPageHero`), `PageSection`, `PortalFooter`, `ScrollToTop`.
 
 ## Tailwind v4 consumers
 
-Tailwind skips `node_modules` when scanning, so add this next to the imports above — otherwise the shell's layout utilities never generate and the AppShell grid collapses:
+Tailwind skips `node_modules` when scanning, so add this next to the imports above — otherwise the shell's layout utilities never generate and the PageLayout grid collapses:
 
 ```css
 @source "../node_modules/@kolkrabbi/kol-framework/src";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "KOL app shell — sidenav, layout, theme toggle, footer, heroes + brand color layer. SideNav takes nav data as props so the tree stays app-local.",
   "license": "MIT",
   "type": "module",
@@ -13,15 +13,15 @@
     "./kol-brand-color.css": "./kol-brand-color.css"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.70.0",
+    "@kolkrabbi/kol-component": ">=0.176.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
-    "@kolkrabbi/kol-theme": ">=0.133.0",
+    "@kolkrabbi/kol-theme": ">=0.134.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.175.0",
+    "@kolkrabbi/kol-component": "^0.176.0",
     "@kolkrabbi/kol-icons": "^0.25.0"
   },
   "files": [

package/src/PageHero.jsx

@@ -0,0 +1,59 @@
+import { Link } from 'react-router-dom'
+import { SectionText } from '@kolkrabbi/kol-component'
+
+/**
+ * PageHero — the page's opening band: label · title · lede, with an optional
+ * mark beside the text and an optional back link above it.
+ *
+ * ONE HERO (page-family-is-not-a-set, kol-client-olina 2026-09-03; user, on
+ * the brand kit: *"why do 3 of 4 prefix PAGE if they are a set?"*). `BrandHero`
+ * and `SubPageHero` were the same core with one optional slot each — a `mark`
+ * on one, a back link on the other — under two prefixes, and each hand-stacked
+ * its own label / title / lede. Both names alias this; the retirements ledger
+ * carries them.
+ *
+ * COMPOSES `SectionText`, the page tier's base, the way `PageHeader` does. The
+ * voices are `BrandHero`'s verbatim — `.kol-prose-label` · `.kol-prose-display`
+ * · `.kol-prose-lede` (kol-theme's section-head trio, each carrying its own
+ * bottom margin, so the block's `gap` is 0 and the rhythm is the classes').
+ * `SubPageHero` had no package consumer, so its private voices did not survive
+ * the merge; its back link did, class-for-class.
+ *
+ * @param {string}    id         section id (default `hero`) — the sidenav's scroll-spy anchor
+ * @param {string}    backTo     route for the back link; unset renders no link
+ * @param {ReactNode} backLabel  the back link's text
+ * @param {ReactNode} label      eyebrow above the title
+ * @param {ReactNode} title      the h1
+ * @param {ReactNode} lede       standfirst under the title, measured at 60ch
+ * @param {ReactNode} mark       a node beside the text column (a logo); the text sits right of it
+ * @param {string}    className  extra classes on the section
+ */
+export default function PageHero({ id = 'hero', backTo, backLabel, label, title, lede, mark, className = '' }) {
+  return (
+    <section id={id} className={`kol-page-hero ${className}`.trim()}>
+      {backTo && (
+        <Link
+          to={backTo}
+          className="kol-back-link kol-helper-12 tracking-widest text-body hover:text-emphasis no-underline"
+        >
+          {backLabel}
+        </Link>
+      )}
+      <div className="flex items-center gap-12 flex-wrap">
+        {mark}
+        <div className="flex-1 min-w-[280px]">
+          <SectionText
+            eyebrow={label}
+            eyebrowClass="kol-prose-label"
+            headline={title}
+            headlineAs="h1"
+            headlineClass="kol-prose-display"
+            body={lede}
+            bodyClass="kol-prose-lede max-w-[60ch]"
+            gap="gap-0"
+          />
+        </div>
+      </div>
+    </section>
+  )
+}

package/src/{AppShell.jsx → PageLayout.jsx}

@@ -21,7 +21,43 @@ export const ShellTocCollapsedContext = createContext(null)
 /* `sideNav` — every SideNav prop AppShell does not own, spread onto the rail
  * (sidenav-rail-hairline, 2026-08-26): `background`, `hairline`, `isActive`,
  * `onNavigate` … the next rail option needs no AppShell release. */
-export default function AppShell({ navTree = [], getActivePage: _getActivePage, header, footer, defaultTocContent, sideNav }) {
+/**
+ * PageLayout — the brand-book page layout: the `.kol-brand-layout` grid with
+ * the sidenav in its first track, the page plane in the second, the mobile
+ * drawer + hamburger, the modal provider and the optional TOC rail.
+ *
+ * WAS `AppShell` (page-family-is-not-a-set, kol-client-olina 2026-09-03). The
+ * ticket asked for a `PageLayout` to ship beside the fifteen `.kol-brand-layout`
+ * rules kol-framework already owned — every consumer `BrandLayout.jsx` in the
+ * estate is a copy of this file's markup. The component existed; the name did
+ * not say so, and it collided with kol-shell's `AppShell` (the 48px app rail).
+ * Renamed, `AppShell` aliased on the retirements ledger, and the two things the
+ * forks carried that it lacked folded in:
+ *
+ *   pageWash  the plane's wash over the primary back — the SAME prop and
+ *             variable as kol-shell's `AppShell` (`--kol-shell-page-wash`; there
+ *             `PageShell` paints it, here the plane does), so a brand page and a
+ *             monitor / mirror / fxr page step their lightness with one name
+ *             (user 2026-08-27). A translucent `fg-*` over `surface-primary`,
+ *             never an opaque swap. Unset = the plane IS the back.
+ *   bare      the plane and the outlet only — no grid, no rail, no drawer. The
+ *             forks' `?embed=1` branch, for iframing a page into another site.
+ *
+ * THE BACK IS `surface-primary` (BrandLayout's line, user rulings 2026-08-24 →
+ * 08-27): the rail sits on it, the plane wears the wash. It was
+ * `surface-tertiary` here (appshell-content-surface, kol-studio 2026-08-26) —
+ * one component takes one model, and kol-studio passes its wash.
+ *
+ * @param {Array}     navTree            the sidenav's tree (see SideNav)
+ * @param {Function}  getActivePage      accepted, inert since 2026-08-09
+ * @param {ReactNode} header             above the outlet on the plane
+ * @param {ReactNode} footer             below the outlet on the plane
+ * @param {ReactNode} defaultTocContent  the TOC rail's content when no page registers one
+ * @param {object}    sideNav            every SideNav prop this layout does not own, spread onto the rail
+ * @param {string}    pageWash           the plane's wash, a CSS colour (e.g. `'var(--kol-fg-02)'`)
+ * @param {boolean}   bare               plane + outlet only (default false)
+ */
+export default function PageLayout({ navTree = [], getActivePage: _getActivePage, header, footer, defaultTocContent, sideNav, pageWash, bare = false }) {
   const [drawerOpen, setDrawerOpen] = useState(false)
   const [tocContent, setTocContent] = useState(null)
   const [tocCollapsed, setTocCollapsed] = useState(false)
@@ -39,17 +75,36 @@ export default function AppShell({ navTree = [], getActivePage: _getActivePage,
   const effectiveTocContent = tocContent ?? defaultTocContent
   const showToc = Boolean(effectiveTocContent) && !tocCollapsed
 
+  /* the plane paints the wash; the var lives on the plane so any child that
+     reads it resolves the same value (BrandLayout, verbatim) */
+  const plane = {
+    '--kol-shell-page-wash': pageWash,
+    background: 'var(--kol-shell-page-wash, var(--kol-surface-primary))',
+  }
+
+  if (bare) {
+    return (
+      <ModalProvider>
+        <ShellTocContext.Provider value={setTocContent}>
+          <ShellTocCollapsedContext.Provider value={setTocCollapsed}>
+            <div className="min-h-dvh min-w-0" style={plane}>
+              <Outlet />
+            </div>
+          </ShellTocCollapsedContext.Provider>
+        </ShellTocContext.Provider>
+      </ModalProvider>
+    )
+  }
+
   return (
     <ModalProvider>
       <ShellTocContext.Provider value={setTocContent}>
         <ShellTocCollapsedContext.Provider value={setTocCollapsed}>
           <div
-            /* the PAGE is surface-tertiary, the rail surface-primary — the brand
-             * split (appshell-content-surface, kol-studio 2026-08-26, user:
-             * "sidenav primary, site tertiary, like brand"). BrandLayout's own
-             * line, verbatim; the fork dropped it on 2026-08-09 and every
-             * AppShell app rendered one flat colour. */
-            className="kol-brand-layout bg-surface-tertiary min-h-dvh"
+            /* TWO surfaces: the BACK is surface-primary, the rail sits on it,
+             * and the PLANE wears `pageWash` over it (BrandLayout's line,
+             * 2026-08-24 → 08-27). */
+            className="kol-brand-layout bg-surface-primary min-h-dvh"
             data-drawer-open={drawerOpen ? 'true' : undefined}
             data-toc={showToc ? 'true' : undefined}
           >
@@ -70,7 +125,7 @@ export default function AppShell({ navTree = [], getActivePage: _getActivePage,
             />
 
             <SideNav navTree={navTree} drawerOpen={drawerOpen} onCloseDrawer={() => setDrawerOpen(false)} {...sideNav} />
-            <div className="min-w-0">
+            <div className="min-w-0" style={plane}>
               {header}
               <Outlet />
               {footer}

package/src/PageSection.jsx

@@ -1,5 +1,10 @@
-import { Divider } from '@kolkrabbi/kol-component'
+import { Divider, SectionText } from '@kolkrabbi/kol-component'
 
+/* The chapter section of the brand-book page kit — `PageHero` · `PageSection`
+ * · `PageLayout`. Its head COMPOSES `SectionText` (page-family-is-not-a-set,
+ * 2026-09-03) instead of hand-stacking label / title / lede: the voices are the
+ * same `.kol-prose-*` trio as before, passed as the base's seams, and each class
+ * carries its own bottom margin, so the block's gap is 0 and nothing moved. */
 export default function PageSection({ id, label, title, body, children, className = '', fullbleed = false, divider = false }) {
   const hasHead = label || title || body
   const cls = [
@@ -16,9 +21,16 @@ export default function PageSection({ id, label, title, body, children, classNam
          * exactly the panel token; `720px` was an improvised near-miss and
          * becomes the column token — 768px, so section heads widen by 48px. */
         <header className={fullbleed ? 'max-w-[var(--kol-content-panel)]' : 'max-w-[var(--kol-content-column)]'}>
-          {label && <p  className="kol-prose-label">{label}</p>}
-          {title && <h2 className="kol-prose-title">{title}</h2>}
-          {body  && <p  className="kol-prose-lede">{body}</p>}
+          <SectionText
+            eyebrow={label}
+            eyebrowClass="kol-prose-label"
+            headline={title}
+            headlineAs="h2"
+            headlineClass="kol-prose-title"
+            body={body}
+            bodyClass="kol-prose-lede"
+            gap="gap-0"
+          />
         </header>
       )}
       {children}

package/src/ThemeToggle.jsx

@@ -90,7 +90,9 @@ export default function ThemeToggle({
   className = '',
 }) {
   const { theme, mode, cycle, clear } = useTheme()
-  const extra = `${tone === 'sunken' || tone === 'inverse' ? 'kol-tone-sunken' : ''} ${className}`.trim()
+  /* six tones (tone-is-the-ground-axis, 2026-09-03); unset inherits the wrapper's */
+  const TONE_CLASS = { primary: 'kol-tone-primary', secondary: 'kol-tone-secondary', outline: 'kol-tone-outline', ghost: 'kol-tone-ghost', grey: 'kol-tone-grey', sunken: 'kol-tone-sunken', inverse: 'kol-tone-sunken' }
+  const extra = `${TONE_CLASS[tone] ?? ''} ${className}`.trim()
 
   /* Label and slot follow the RESOLVED theme, not the stored choice: when the
    * page is unset, what the user is looking at is the OS's answer, and the

package/src/index.js

@@ -1,14 +1,14 @@
 /**
  * @kol/framework — shared KOL app shell.
  *
- * Site chrome (sidenav, layout, theme toggle, footer, heroes) consumed across
+ * Site chrome (sidenav, page layout, theme toggle, footer, the page kit) consumed across
  * apps. SideNav takes its nav data as props (navTree) so the tree stays
  * app-local. CSS lives in src/styles: kol-framework.css
  * and kol-brand-color.css.
  */
 
-export { default as AppShell } from './AppShell.jsx'
-export { ShellTocContext, ShellTocCollapsedContext } from './AppShell.jsx'
+export { default as PageLayout, default as AppShell } from './PageLayout.jsx'
+export { ShellTocContext, ShellTocCollapsedContext } from './PageLayout.jsx'
 export { default as SideNav } from './SideNav.jsx'
 export { default as useDragResize } from './useDragResize.js'
 export { default as ShellHeader, HEADER_ICON } from './ShellHeader.jsx'
@@ -18,5 +18,4 @@ export { default as Layout } from './Layout.jsx'
 export { default as PageSection } from './PageSection.jsx'
 export { default as PortalFooter } from './PortalFooter.jsx'
 export { default as ScrollToTop } from './ScrollToTop.jsx'
-export { default as BrandHero } from './BrandHero.jsx'
-export { default as SubPageHero } from './SubPageHero.jsx'
+export { default as PageHero, default as BrandHero, default as SubPageHero } from './PageHero.jsx'

package/src/BrandHero.jsx

@@ -1,14 +0,0 @@
-export default function BrandHero({ id = 'hero', label, title, lede, mark }) {
-  return (
-    <section id={id} className="kol-page-hero">
-      {label && <p className="kol-prose-label">{label}</p>}
-      <div className="flex items-center gap-12 flex-wrap">
-        {mark}
-        <div className="flex-1 min-w-[280px]">
-          <h1 className="kol-prose-display">{title}</h1>
-          {lede && <p className="kol-prose-lede max-w-[60ch]">{lede}</p>}
-        </div>
-      </div>
-    </section>
-  )
-}

package/src/SubPageHero.jsx

@@ -1,27 +0,0 @@
-import { Link } from 'react-router-dom'
-
-export default function SubPageHero({ backTo, backLabel, label, title, lede }) {
-  return (
-    <section className="kol-page-hero" id="hero">
-      {backTo && (
-        <Link
-          to={backTo}
-          className="kol-back-link kol-helper-12 tracking-widest text-body hover:text-emphasis no-underline"
-        >
-          {backLabel}
-        </Link>
-      )}
-      {label && (
-        <p className="kol-helper-12 tracking-widest text-meta m-0 mb-4">
-          {label}
-        </p>
-      )}
-      <div className="flex-1 min-w-[280px]">
-        <h1 className="kol-sans-display-01 text-auto m-0 mb-6">{title}</h1>
-        {lede && (
-          <p className="kol-sans-body-01 text-body m-0 max-w-[60ch]">{lede}</p>
-        )}
-      </div>
-    </section>
-  )
-}