@kolkrabbi/kol-shell 0.13.2 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.13.2",
+  "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",
@@ -13,17 +13,17 @@
   },
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.108.0",
-    "@kolkrabbi/kol-framework": ">=0.33.0",
+    "@kolkrabbi/kol-framework": ">=0.34.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
     "@kolkrabbi/kol-theme": ">=0.80.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.118.3",
+    "@kolkrabbi/kol-component": "^0.121.1",
     "@kolkrabbi/kol-icons": "^0.24.0",
-    "@kolkrabbi/kol-framework": "^0.33.0",
-    "@kolkrabbi/kol-theme": "^0.80.0"
+    "@kolkrabbi/kol-framework": "^0.35.0",
+    "@kolkrabbi/kol-theme": "^0.83.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -31,7 +31,11 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  * @param {string} props.currentPath   the router's current pathname
  * @param {Function} props.onNavigate  `(path) => void`
  * @param {ElementType} props.iconComponent  icon renderer seam (see Button)
- * @param {boolean} props.themeToggle  render the ThemeToggle above bottomItems (default true)
+ * @param {Object}  props.settings     `{ icon, path, label }` — Settings as a DISCLOSURE in the pinned bottom
+ *                                        row (RailSettingsDisclosure, 2026-08-28): click opens a panel above the
+ *                                        row with the theme toggle and the settings page as a row; click again,
+ *                                        Escape or any navigation closes it. Turns the rail's theme slot off.
+ * @param {boolean} props.themeToggle  render the ThemeToggle above bottomItems (default true; false when `settings` is given)
  * @param {string}  props.railToggleKey  a key that toggles the rail (e.g. '\\') — ignored while typing in a field;
  *                                        the rail comes back on every `currentPath` change (ShellHomeSystem, 2026-08-27)
  * @param {'shell'|'bare'|'overlay'} props.touch  the touch-primary policy (default 'shell' = the rail regardless):
@@ -62,6 +66,7 @@ export default function AppShell({
   currentPath,
   onNavigate,
   iconComponent,
+  settings,
   themeToggle,
   railToggleKey,
   touch = 'shell',
@@ -130,7 +135,8 @@ export default function AppShell({
           currentPath={currentPath}
           onNavigate={onNavigate}
           iconComponent={iconComponent}
-          themeToggle={themeToggle}
+          settings={settings}
+          themeToggle={themeToggle ?? !settings}
         />
       )}
       {/* THE BACK OF THE BACK — surface-primary, always, in every app; the

package/src/NavRail.jsx

@@ -1,4 +1,5 @@
-import { SideNav } from '@kolkrabbi/kol-framework'
+import { SideNav, ThemeToggle } from '@kolkrabbi/kol-framework'
+import { Icon } from '@kolkrabbi/kol-icons'
 import Logomark from './Logomark.jsx'
 
 /**
@@ -21,6 +22,17 @@ import Logomark from './Logomark.jsx'
  * 0.13.0's footer placement: "why did you move the logo from top to bottom?
  * … I've never seen that before so you are the first"). Its `title` is the
  * label beside the mark in the open rail; collapsed, the mark alone.
+ *
+ * `settings` — SETTINGS IS A DISCLOSURE, NOT A ROUTE (RailSettingsDisclosure,
+ * kol-fxr 2026-08-28 — user: "put the settings where the logo is, and logo
+ * back on top" · "sidebar setting should open close on click and click again"
+ * · "put the theme toggle in the settings and out of the sidebar" · "we make
+ * it work here then ship it"): `{ icon, path, label }` renders the gear as the
+ * pinned bottom row — a SideNav panel leaf, same pixel as the route row it
+ * replaces — whose panel holds the theme toggle (`icon` collapsed /
+ * `hop-bare` expanded, the slot's two variants) and the Settings page as a
+ * row. The rail's standing theme slot is off when `settings` is given; the
+ * toggle exists in the disclosure and on the settings page only.
  */
 export default function NavRail({
   items = [],
@@ -29,17 +41,43 @@ export default function NavRail({
   currentPath = '',
   onNavigate,
   iconComponent,
-  themeToggle = true,
+  settings,
+  themeToggle = !settings,
   hidden = false,
 }) {
   if (hidden) return null
   const node = (item) => ({ id: item.path, label: item.label, icon: item.icon, to: item.path })
+  const Glyph = iconComponent ?? Icon
+  const settingsLeaf = settings && {
+    id: settings.path,
+    label: settings.label,
+    icon: settings.icon,
+    panel: ({ collapsed, close }) => (
+      <>
+        <div className="kol-sidenav-theme-slot flex">
+          <ThemeToggle variant={collapsed ? 'icon' : 'hop-bare'} size="md" />
+        </div>
+        <button
+          type="button"
+          className="kol-sidenav-hop kol-helper-12 text-strong hover:text-emphasis bg-transparent border-0 cursor-pointer text-left"
+          onClick={() => { close(); onNavigate?.(settings.path) }}
+          title={settings.label}
+          aria-label={settings.label}
+        >
+          <span className="kol-sidenav-hop-icon inline-flex items-center justify-center w-5 h-5 shrink-0" aria-hidden="true">
+            <Glyph name="arrow-right" size={16} />
+          </span>
+          <span className="kol-sidenav-hop-label flex-1 min-w-0 truncate">{settings.label}</span>
+        </button>
+      </>
+    ),
+  }
   /* the shell's route match: '/' exact, anything else by prefix */
   const isActive = (to) => (to === '/' ? currentPath === '/' : currentPath.startsWith(to))
   return (
     <SideNav
       navTree={items.map(node)}
-      bottomItems={bottomItems.map(node)}
+      bottomItems={[...bottomItems.map(node), ...(settingsLeaf ? [settingsLeaf] : [])]}
       currentPath={currentPath}
       isActive={isActive}
       onNavigate={(e, to) => onNavigate?.(to)}

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>
   )