@kolkrabbi/kol-shell 0.59.1 → 0.61.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.59.1",
+  "version": "0.61.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}.",
+  "description": "The application shell",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.js",
@@ -14,16 +14,16 @@
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.229.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
-    "@kolkrabbi/kol-theme": ">=0.156.0",
+    "@kolkrabbi/kol-theme": ">=0.165.0",
     "gsap": "^3.13.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-framework": "^0.46.0",
-    "@kolkrabbi/kol-component": "^0.230.0",
-    "@kolkrabbi/kol-icons": "^0.29.1",
-    "@kolkrabbi/kol-theme": "^0.157.0"
+    "@kolkrabbi/kol-component": "^0.239.0",
+    "@kolkrabbi/kol-framework": "^0.49.0",
+    "@kolkrabbi/kol-icons": "^0.33.0",
+    "@kolkrabbi/kol-theme": "^0.165.0"
   },
   "files": [
     "src",

package/src/AppHub.jsx

@@ -7,7 +7,7 @@ import { ShortcutsOverlay } from '@kolkrabbi/kol-component'
 /* taxonomy-ok: organism — nests AppShell / HubHome / HubSettings / ShortcutsOverlay (relative) */
 
 /**
- * AppHub — Shell + Hub in one call; the app passes its Tool as children (the app anatomy,
+ * AppHub — An app's shell and hub in one. Shell + Hub in one call; the app passes its Tool as children (the app anatomy,
  * `docs/documentation/04-compositions/16-app-anatomy.md`, 2026-09-26).
  *
  * monitor, mirror and fxr each assembled this by hand: the same AppShell props, the same

package/src/AppShell.jsx

@@ -42,6 +42,7 @@ import { TABBAR_H, MastheadContext } from '@kolkrabbi/kol-component'
  * open/close is the consumer's `onNavigate` (kol-mirror's model: navigating to
  * `/settings` while already there returns to the last page), and the theme
  * toggle lives on the settings page, not in the rail (user, 2026-08-28).
+ * @param {boolean} [props.railFade=true]  the rail's list fades out at its foot (`NavRail fade`); `false` opts out
  * @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'|'drawer'|'bar'} props.touch  the touch-primary policy (default 'shell' = the rail regardless):
@@ -130,6 +131,7 @@ export default function AppShell({
   onNavigate,
   iconComponent,
   railComponent: Rail = NavRail,
+  railFade = true,
   railToggleKey,
   touch = 'shell',
   appName,
@@ -370,6 +372,7 @@ export default function AppShell({
           onNavigate={navigate}
           iconComponent={iconComponent}
           drawer={drawer}
+          fade={railFade}
         />
       )}
       {/* THE BACK OF THE BACK — surface-primary, always, in every app; the

package/src/AppStudio.jsx

@@ -6,7 +6,7 @@ import PageShell from './PageShell.jsx'
 /* taxonomy-ok: organism — nests AppHub / CatalogPage / PageShell (relative) + kol-component's PageHeader */
 
 /**
- * AppStudio — the WORKSTATION: the Hub plus a fixed page set (apps review §6c-4, 2026-09-29).
+ * AppStudio — The studio workstation. the WORKSTATION: the Hub plus a fixed page set (apps review §6c-4, 2026-09-29).
  *
  * fxr, mirror and monitor each hand-build the same shape — a landing Catalog, a Library of what the
  * tool makes, a page that composes a new one, the tool itself full-bleed, a page or two of their own,

package/src/CatalogPage.jsx

@@ -7,7 +7,7 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
 /* taxonomy-ok: organism — nests PageShell / PageHeader / WalkthroughPanel (relative) + kol-component's ContentFilters + ContentCard / ContentRow */
 
 /**
- * CatalogPage — the app tier's Home / Library page, shipped once (ShellHomeSystem,
+ * CatalogPage — An app's home or library page. the app tier's Home / Library page, shipped once (ShellHomeSystem,
  * kol-fxr 2026-08-27 — fxr's HomePage / LibraryPage and monitor's HomePage were
  * the same page written three times): `PageHeader` → `ContentFilters` (title ·
  * filter · search, the view strip in the header, LIST / GRID below the divider)

package/src/HubHome.jsx

@@ -5,7 +5,7 @@ import CatalogPage from './CatalogPage.jsx'
 /* taxonomy-ok: organism — nests CatalogPage (relative) + kol-component's Button */
 
 /**
- * HubHome — the Hub's Home: a Catalog under the app's masthead (the Hub, 2026-09-26).
+ * HubHome — A hub's home page. the Hub's Home: a Catalog under the app's masthead (the Hub, 2026-09-26).
  * monitor, mirror and fxr each wrote this page on `CatalogPage` with the same five
  * decisions — the mono masthead, RECENT · SAVED, a walkthrough opened by a button,
  * that button's Close label, a "Get started" last step — and the case of the view
@@ -71,7 +71,7 @@ export default function HubHome({
         <>
           {actions}
           {steps.length > 0 && (
-            <Button variant="grey" size="md" onClick={() => setTouring((t) => !t)}>
+            <Button tone="grey" size="md" onClick={() => setTouring((t) => !t)}>
               {touring ? 'Close' : 'Walkthrough'}
             </Button>
           )}

package/src/HubSettings.jsx

@@ -7,7 +7,7 @@ import SettingsLinks, { SettingsColophon } from './SettingsLinks.jsx'
 /* taxonomy-ok: organism — nests SettingsScaffold / SettingsShortcuts / SettingsLinks (relative) + kol-component's SettingsPanel / SettingsSections */
 
 /**
- * HubSettings — the Hub's Settings page (the Hub, 2026-09-26). monitor, mirror and fxr
+ * HubSettings — A hub's settings page. the Hub's Settings page (the Hub, 2026-09-26). monitor, mirror and fxr
  * each put the same page on `SettingsScaffold`: SETTINGS · ABOUT · REPO with the same
  * three subtitles, the same theme toggle in the masthead, About as the app's prose over
  * the colophon, Repo as a link list, and the keyboard shortcuts from the one array the

package/src/Logomark.jsx

@@ -1,7 +1,7 @@
 import { useState, useEffect } from 'react'
 
 /**
- * Logomark — fetches and INLINES an SVG so currentColor theming works: an
+ * Logomark — An inlined SVG mark. fetches and INLINES an SVG so currentColor theming works: an
  * <img> renders a currentColor mark black in dark mode (invisible). Ported
  * verbatim from the kol-mirror cut (module-level cache; async resolve even on
  * cache hit — sync setState in an effect cascades renders).

package/src/NavRail.jsx

@@ -70,6 +70,10 @@ import Logomark from './Logomark.jsx'
  * @param {boolean} drawer  off-canvas mode: no grab, no drag, no token writes, rows always
  *   labelled, and the rail sizes itself from `--kol-shell-drawer-width` (default 240px).
  *   AppShell sets this from `touch="drawer"` — see ShellRailNoDrawerOnMobile, 2026-08-31.
+ * @param {boolean} [fade=true]  the list fades out at its foot — the workshop rail's fade
+ *   (2026-10-01), here too on the user's word (2026-10-02). The rows sit in their own scroll
+ *   region between the mark and the pinned bottom rows, so a list longer than the window scrolls
+ *   and runs out under the fade instead of being cut by the edge. `false` draws the list plain.
  */
 const RAIL_W = '--kol-shell-rail-width'
 const CLOSED = 48
@@ -277,6 +281,7 @@ export default function NavRail({
   iconComponent,
   hidden = false,
   drawer = false,
+  fade = true,
 }) {
   const railRef = useRef(null)
   const grabRef = useRef(null)
@@ -340,9 +345,12 @@ export default function NavRail({
         </div>
         </Tooltip>
       )}
-      {items.map(row)}
-      {/* the spacer IS the layout */}
-      <div className="flex-1" />
+      {/* THE LIST IS ITS OWN REGION (2026-10-02): it takes the room between the mark and the pinned
+        * bottom rows — what the bare spacer used to hold — scrolls when the rows outrun the window,
+        * and fades at its foot unless `fade={false}`. Same column, same gap, as the rail's own. */}
+      <div className={`kol-shell-rail-list flex min-h-0 w-full flex-1 flex-col items-start gap-2 overflow-y-auto overflow-x-hidden ${fade ? 'kol-shell-rail-list--fade' : ''}`.trim()}>
+        {items.map(row)}
+      </div>
       {/* the rule runs the full rail width, out past the px-2 */}
       {bottomItems.length > 0 && <div className="self-stretch -mx-2 border-t border-fg-08" />}
       {bottomItems.map(row)}

package/src/PageShell.jsx

@@ -1,5 +1,5 @@
 /**
- * PageShell — the page scaffold every shell page re-declared by hand (6 pages
+ * PageShell — The page scaffold of an app. the page scaffold every shell page re-declared by hand (6 pages
  * in monitor, 4 in mirror — the most-duplicated block in both repos).
  *
  * `mode="scroll"` (default): min-height 100vh, natural page scroll.

package/src/PhoneNav.jsx

@@ -4,7 +4,7 @@ import { Button, MobileTabBar } from '@kolkrabbi/kol-component'
 /* taxonomy-ok: molecule — MobileTabBar + a More sheet of Buttons */
 
 /**
- * PhoneNav — the rail, on a phone, as a bottom bar (AppShell `touch="bar"`, apps review
+ * PhoneNav — The rail as a phone tab bar. the rail, on a phone, as a bottom bar (AppShell `touch="bar"`, apps review
  * 2026-09-29). The user: *"what about when there are like 10 pages? … this seems like something
  * shell or hub should account for and ship, but not have per app fixes."*
  *

package/src/SettingsLinks.jsx

@@ -1,5 +1,5 @@
 /**
- * SettingsLinks — the About / Repo link list every app hand-wrote (ShellHomeSystem,
+ * SettingsLinks — The links block of a settings page. the About / Repo link list every app hand-wrote (ShellHomeSystem,
  * kol-fxr 2026-08-27): label `kol-helper-12 text-fg-32` at 72px, the URL as an
  * external link `text-fg-64 hover:text-fg-96 hover:underline`.
  *
@@ -18,7 +18,7 @@ export default function SettingsLinks({ links = [], className = '' }) {
   )
 }
 
-/** SettingsColophon — the "Kolkrabbi Vinnustofa / 2026" foot under a settings scaffold. */
+/** SettingsColophon — The foot of a settings page. the "Kolkrabbi Vinnustofa / 2026" foot under a settings scaffold. */
 export function SettingsColophon({ name = 'Kolkrabbi Vinnustofa', year = new Date().getFullYear(), className = '' }) {
   return (
     <div className={className} style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>

package/src/SettingsScaffold.jsx

@@ -4,7 +4,7 @@ import PageShell from './PageShell.jsx'
 import { PageHeader } from '@kolkrabbi/kol-component'
 
 /**
- * SettingsScaffold — the settings-page idiom both shells re-implemented inline:
+ * SettingsScaffold — The settings page scaffold. the settings-page idiom both shells re-implemented inline:
  * fixed PageShell, a PageHeader masthead, one header row, then a scrolling body.
  * Content is consumer-authored via `renderContent` — sections/rows are content,
  * not markup.

package/src/SettingsShortcuts.jsx

@@ -7,7 +7,7 @@ import { SettingsRow } from '@kolkrabbi/kol-component'
  * baseline row did. */
 
 /**
- * SettingsShortcuts — the keyboard-shortcuts block of a settings page
+ * SettingsShortcuts — The shortcuts block of a settings page. the keyboard-shortcuts block of a settings page
  * (ShellHomeSystem, kol-fxr 2026-08-27): the same `[{ section, items: [{ id,
  * label, combo }] }]` array `ShortcutsOverlay` takes, laid out UP TO six columns ×
  * two sections per column, filled column-first (user, 2026-08-27) — each

package/src/TabStrip.jsx

@@ -1,5 +1,5 @@
 /**
- * TabStrip — the flat text-tab idiom both shells use twice (ContentFilters
+ * TabStrip — A row of text tabs. the flat text-tab idiom both shells use twice (ContentFilters
  * view-mode/layout spans, Settings tabs): `kol-helper-14`, active
  * `text-fg-96`, rest `text-fg-32 hover:text-fg-48`.
  *

package/src/TouchDeviceOverlay.jsx

@@ -17,20 +17,24 @@ export function useTouchPrimary() {
 }
 
 /**
- * TouchDeviceOverlay — "Desktop recommended", once, on a touch-primary device
+ * TouchDeviceOverlay — A desktop-recommended note on touch devices. "Desktop recommended", once, on a touch-primary device
  * (kol-monitor's overlay, promoted 2026-08-27 — ShellHomeSystem; `AppShell
  * touch="overlay"` mounts it). Dismissal is remembered in localStorage.
  *
  * @param {string} appName   the sentence's subject ("Monitor is built for mouse and keyboard…")
  * @param {string} message   override the sentence whole
+ * @param {boolean} force    show it whatever the pointer and whatever was dismissed — for a preview
+ *                           or a settings "show it again"; dismissing a forced note stores nothing
  */
-export default function TouchDeviceOverlay({ appName = 'This app', message }) {
+export default function TouchDeviceOverlay({ appName = 'This app', message, force = false }) {
   const coarse = useTouchPrimary()
   const [dismissed, setDismissed] = useState(() => {
     try { return localStorage.getItem(STORAGE_KEY) === '1' } catch { return false }
   })
-  if (!coarse || dismissed) return null
+  const [closed, setClosed] = useState(false)
+  if (force ? closed : !coarse || dismissed) return null
   const dismiss = () => {
+    if (force) { setClosed(true); return }
     try { localStorage.setItem(STORAGE_KEY, '1') } catch { /* storage blocked */ }
     setDismissed(true)
   }

package/src/WalkthroughPanel.jsx

@@ -2,7 +2,7 @@ import { useState } from 'react'
 import { Button } from '@kolkrabbi/kol-component'
 
 /**
- * WalkthroughPanel — the absolutely-centred stepped intro card (both repos'
+ * WalkthroughPanel — A stepped intro card. the absolutely-centred stepped intro card (both repos'
  * HomePage): chevron Buttons either side, text column + illustration pane.
  *
  * Steps are content: `[{ title, text: [..], illustration?, actions? }]` —
@@ -27,7 +27,7 @@ export default function WalkthroughPanel({ steps = [], iconComponent, onClose })
       maxWidth: 960, width: '100%', zIndex: 10,
     }}>
       <Button
-        variant="grey"
+        tone="grey"
         size="md"
         iconOnly="chevron-left"
         iconComponent={iconComponent}
@@ -76,7 +76,7 @@ export default function WalkthroughPanel({ steps = [], iconComponent, onClose })
       </div>
 
       <Button
-        variant="grey"
+        tone="grey"
         size="md"
         iconOnly="chevron-right"
         iconComponent={iconComponent}