@kolkrabbi/kol-shell 0.59.0 → 0.60.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.59.0",
+  "version": "0.60.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",
@@ -20,10 +20,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.229.0",
-    "@kolkrabbi/kol-theme": "^0.156.0",
-    "@kolkrabbi/kol-framework": "^0.45.0",
-    "@kolkrabbi/kol-icons": "^0.29.0"
+    "@kolkrabbi/kol-component": "^0.237.0",
+    "@kolkrabbi/kol-icons": "^0.33.0",
+    "@kolkrabbi/kol-framework": "^0.48.0",
+    "@kolkrabbi/kol-theme": "^0.163.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

@@ -90,7 +90,7 @@ import { TABBAR_H, MastheadContext } from '@kolkrabbi/kol-component'
  *                                        tab switch. Matched on `e.code` (`Digit1`…) because Opt+digit yields
  *                                        `¡ ™ £ ¢` as `e.key` on macOS; ignored while typing in a field; only
  *                                        digits with an item; `preventDefault` on a match. Default off.
- * @param {string}  props.pageWash      a CSS colour painted by `PageShell` OVER the shell's primary back
+ * @param {string}  props.pageWash      a CSS color painted by `PageShell` OVER the shell's primary back
  *                                        (ShellPageWash, kol-monitor 2026-08-27 — user: "the back of the back
  *                                        should be primary — then you can just add transparent on top to step
  *                                        up the lightness"): `'var(--kol-fg-12)'` steps the page a rung lighter

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/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.
@@ -116,7 +116,7 @@ export default function SettingsScaffold({
       {picker}
       {themeToggle}
       {onOpenSettings && (
-        <Tooltip label="Display settings">
+        <Tooltip label="Display">
         <IconFrame
           name="settings-01"
           variant="primary"

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}