@kolkrabbi/kol-shell 0.7.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.7.2",
+  "version": "0.9.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",
@@ -12,18 +12,18 @@
     "./src/*": "./src/*"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.38.0",
+    "@kolkrabbi/kol-component": ">=0.99.0",
     "@kolkrabbi/kol-framework": ">=0.20.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
-    "@kolkrabbi/kol-theme": ">=0.67.0",
+    "@kolkrabbi/kol-theme": ">=0.68.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.98.0",
-    "@kolkrabbi/kol-framework": "^0.27.1",
-    "@kolkrabbi/kol-icons": "^0.19.0",
-    "@kolkrabbi/kol-theme": "^0.67.0"
+    "@kolkrabbi/kol-framework": "^0.28.0",
+    "@kolkrabbi/kol-icons": "^0.20.0",
+    "@kolkrabbi/kol-component": "^0.106.0",
+    "@kolkrabbi/kol-theme": "^0.71.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -1,6 +1,7 @@
-import { useState } from 'react'
+import { useEffect, useState } from 'react'
 import NavRail from './NavRail.jsx'
 import { NavHiddenContext } from './navHidden.js'
+import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
 
 /**
  * AppShell — layout root: fixed NavRail + content offset by the rail width.
@@ -18,6 +19,13 @@ import { NavHiddenContext } from './navHidden.js'
  * @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 {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):
+ *                                        `bare` renders the children with NO shell on a coarse-pointer device unless
+ *                                        localStorage `kol-desktop` is '1' (fxr's gate); `overlay` keeps the shell and
+ *                                        mounts TouchDeviceOverlay once (monitor's)
+ * @param {string}  props.appName       TouchDeviceOverlay's subject
  */
 export default function AppShell({
   items,
@@ -27,12 +35,39 @@ export default function AppShell({
   onNavigate,
   iconComponent,
   themeToggle,
+  railToggleKey,
+  touch = 'shell',
+  appName,
   children,
 }) {
   const [navHidden, setNavHidden] = useState(false)
+  const coarse = useTouchPrimary()
+
+  /* the rail comes back on every route change */
+  useEffect(() => { setNavHidden(false) }, [currentPath])
+  /* one key toggles the rail — never while typing in a field */
+  useEffect(() => {
+    if (!railToggleKey) return undefined
+    const onKey = (e) => {
+      if (e.key !== railToggleKey || e.metaKey || e.ctrlKey || e.altKey) return
+      const t = e.target
+      if (t?.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t?.tagName)) return
+      e.preventDefault()
+      setNavHidden((h) => !h)
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [railToggleKey])
+
+  let wantsDesktop = false
+  try { wantsDesktop = typeof localStorage !== 'undefined' && localStorage.getItem('kol-desktop') === '1' } catch { /* storage blocked */ }
+  if (touch === 'bare' && coarse && !wantsDesktop) return <div className="kol-app-shell contents">{children}</div>
 
   return (
     <NavHiddenContext.Provider value={{ navHidden, setNavHidden }}>
+      {/* `kol-app-shell` = the app tier: neutral ::selection (kol-theme) */}
+      <div className="kol-app-shell contents">
+      {touch === 'overlay' && <TouchDeviceOverlay appName={appName} />}
       {!navHidden && (
         <NavRail
           items={items}
@@ -47,6 +82,7 @@ export default function AppShell({
       <div style={{ marginLeft: navHidden ? 0 : 'var(--kol-shell-rail-width)' }}>
         {children}
       </div>
+      </div>
     </NavHiddenContext.Provider>
   )
 }

package/src/CatalogPage.jsx

@@ -0,0 +1,108 @@
+import { ContentCard, ContentFilters, ContentRow } from '@kolkrabbi/kol-component'
+import PageShell from './PageShell.jsx'
+import PageHeader from './PageHeader.jsx'
+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,
+ * 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)
+ * → the catalog grid — cards `repeat(6, 1fr)` gap 24, rows `repeat(4, 1fr)` gap
+ * 8, `ContentCard` / `ContentRow variant="catalog"` — → the bottom action row
+ * (`marginTop: 48`, `alignSelf: flex-start`, gap 12). The walkthrough panel
+ * sits over the catalog while `walkthrough.open`; the strip hides and the grid
+ * yields, as both apps do.
+ *
+ * Semantics are the consumer's: what RECENT / SAVED mean, what an item is,
+ * what a click does. `toCard(item, { view, layout })` → `{ key, title, detail,
+ * media, actions, onClick, href, onNavigate, expanded, expandedContent }` is the
+ * whole contract — `expanded` / `expandedContent` reach `ContentCard catalog`'s
+ * 2×2 cell (ShellHomeSystemMonitorGaps, kol-monitor 2026-08-27; neighbour-hiding
+ * stays the consumer's). Anything `ContentFilters` takes that the page has no
+ * prop for goes through `filtersProps` — `mutuallyExclusiveFilters` was the gap.
+ *
+ * @param {Object}   header        PageHeader props — `{ title, subtitle, size, voice, eyebrow }`
+ * @param {Array}    items         the objects `ContentFilters` filters and searches
+ * @param {Function} toCard        (item, { view, layout }) => card props (see above)
+ * @param {string}   filtersTitle  ContentFilters' title (e.g. "All Chromes")
+ * @param {Array}    filterGroups  ContentFilters' `[{ label, key, values }]`
+ * @param {string[]} searchKeys    fields the search reads (default `['title', 'name']`)
+ * @param {Array}    views         the header strip `[{ value, label }]` (RECENT / SAVED); omit for none
+ * @param {string}   view · onViewChange   controlled view; or `defaultView`
+ * @param {Array}    layouts       LIST / GRID (default both)
+ * @param {string}   defaultLayout 'grid' (default) | 'list'
+ * @param {{steps: Array, open: boolean, iconComponent?: ElementType}} walkthrough  the panel over the catalog
+ * @param {ReactNode} actions      the bottom row's buttons
+ * @param {ElementType} iconComponent  icon renderer seam for ContentFilters
+ * @param {boolean}  showCountOnlyWhenFiltering  (default true)
+ * @param {Object}   filtersProps  spread onto ContentFilters last — e.g. `{ mutuallyExclusiveFilters: ['category', 'u_label'] }`
+ */
+const LAYOUTS = [
+  { value: 'list', label: 'LIST' },
+  { value: 'grid', label: 'GRID' },
+]
+
+export default function CatalogPage({
+  header,
+  items = [],
+  toCard,
+  filtersTitle,
+  filterGroups,
+  searchKeys = ['title', 'name'],
+  views,
+  view,
+  onViewChange,
+  defaultView,
+  layouts = LAYOUTS,
+  defaultLayout = 'grid',
+  walkthrough,
+  actions,
+  iconComponent,
+  showCountOnlyWhenFiltering = true,
+  filtersProps,
+  children,
+  className = '',
+  style,
+}) {
+  const open = walkthrough?.open === true
+  return (
+    <PageShell className={className} style={{ overflow: 'hidden', ...style }}>
+      {header && <PageHeader {...header} />}
+      <div style={{ flex: 1, position: 'relative' }}>
+        {open && <WalkthroughPanel steps={walkthrough.steps} iconComponent={walkthrough.iconComponent} />}
+        <ContentFilters
+          items={items}
+          title={filtersTitle}
+          totalCount={items.length}
+          filterGroups={filterGroups}
+          searchKeys={searchKeys}
+          showCountOnlyWhenFiltering={showCountOnlyWhenFiltering}
+          iconComponent={iconComponent}
+          viewModeOptions={views}
+          viewMode={view}
+          onViewModeChange={onViewChange}
+          defaultViewMode={defaultView}
+          layoutOptions={open ? undefined : layouts}
+          defaultLayout={defaultLayout}
+          renderItem={(rows, viewMode, layout) => open ? null : (
+            <div style={{ display: 'grid', gridTemplateColumns: layout === 'list' ? 'repeat(4, 1fr)' : 'repeat(6, 1fr)', gap: layout === 'list' ? 8 : 24 }}>
+              {rows.map((item, i) => {
+                const c = toCard ? toCard(item, { view: viewMode, layout }) : { title: item.title ?? item.name, detail: item.detail }
+                const key = c.key ?? item.key ?? item.id ?? item.name ?? i
+                return layout === 'list'
+                  ? <ContentRow key={key} variant="catalog" title={c.title} detail={c.detail} actions={c.actions} onClick={c.onClick} href={c.href} onNavigate={c.onNavigate} />
+                  : <ContentCard key={key} variant="catalog" fit="cover" title={c.title} detail={c.detail} media={c.media} actions={c.actions} onClick={c.onClick} href={c.href} onNavigate={c.onNavigate} expanded={c.expanded} expandedContent={c.expandedContent} />
+              })}
+            </div>
+          )}
+          {...filtersProps}
+        />
+      </div>
+      {children}
+      {actions && <div style={{ display: 'flex', gap: 12, marginTop: 48, alignSelf: 'flex-start' }}>{actions}</div>}
+    </PageShell>
+  )
+}

package/src/SettingsLinks.jsx

@@ -0,0 +1,29 @@
+/**
+ * SettingsLinks — 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`.
+ *
+ * @param {Array} links  `[{ label, url, text? }]` — `text` shows instead of the URL
+ */
+export default function SettingsLinks({ links = [], className = '' }) {
+  return (
+    <div className={className} style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+      {links.map(({ label, url, text }) => (
+        <div key={label} style={{ display: 'flex', gap: 12, alignItems: 'baseline' }}>
+          <span className="text-fg-32 kol-helper-12" style={{ width: 72, flexShrink: 0 }}>{label}</span>
+          <a href={url} target="_blank" rel="noopener noreferrer" className="text-fg-64 kol-helper-12 hover:text-fg-96 hover:underline">{text ?? url}</a>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+/** SettingsColophon — 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 }}>
+      <span className="text-fg-32 kol-helper-12">{name}</span>
+      <span className="text-fg-32 kol-helper-12">{year}</span>
+    </div>
+  )
+}

package/src/SettingsShortcuts.jsx

@@ -0,0 +1,26 @@
+import { LabelRow } from './SettingsScaffold.jsx'
+
+/**
+ * SettingsShortcuts — 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 six columns ×
+ * two sections per column, filled column-first (user, 2026-08-27) — each
+ * section an eyebrow (`kol-eyebrow`, strong ink) over LabelRows.
+ *
+ * @param {Array}    sections    `[{ section, items: [{ id, label, combo }] }]`
+ * @param {Function} comboLabel  (combo) => string (default: the combo as given)
+ */
+export default function SettingsShortcuts({ sections = [], comboLabel = (c) => c, className = '' }) {
+  return (
+    <div className={`grid grid-cols-6 grid-rows-2 grid-flow-col gap-x-12 gap-y-6 ${className}`.trim()}>
+      {sections.map(({ section, items }) => (
+        <div key={section} style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+          <span className="kol-eyebrow text-strong mb-2">{section}</span>
+          {items.map((k) => (
+            <LabelRow key={k.id ?? k.label} label={k.label}>{comboLabel(k.combo)}</LabelRow>
+          ))}
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/ShortcutsOverlay.jsx

@@ -30,7 +30,7 @@ import { useEffect } from 'react'
  * keymap, it does not own one. Formatting a combo (⌘⇧Z) is the consumer's,
  * next to wherever the binding actually lives.
  *
- * @param {Array} props.shortcuts - `[{ label, keys }]` or `[{ section, items }]`
+ * @param {Array} props.shortcuts - `[{ label, combo }]` or `[{ section, items: [{ id, label, combo }] }]` — the same array `SettingsShortcuts` takes (ShellHomeSystemMonitorGaps, kol-monitor 2026-08-27: the overlay read `keys` while the settings block read `combo`; `combo` is the name, `keys` is tolerated for a release)
  * @param {Function} props.onClose
  */
 
@@ -38,10 +38,10 @@ const isSectioned = (list) => Array.isArray(list?.[0]?.items)
 
 /* One row of the shared grid. `contents` keeps the pair on the parent grid
  * rather than making the wrapper a cell of its own. */
-function Row({ label, keys }) {
+function Row({ label, combo, keys }) {
   return (
     <span className="contents">
-      <span>{label}</span><span className="text-fg-96">{keys}</span>
+      <span>{label}</span><span className="text-fg-96">{combo ?? keys}</span>
     </span>
   )
 }
@@ -71,13 +71,13 @@ export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
               >
                 {section}
               </span>
-              {items.map(({ label, keys }) => (
-                <Row key={`${section}:${label}`} label={label} keys={keys} />
+              {items.map(({ label, combo, keys }) => (
+                <Row key={`${section}:${label}`} label={label} combo={combo} keys={keys} />
               ))}
             </span>
           ))
-          : shortcuts.map(({ label, keys }) => (
-            <Row key={label} label={label} keys={keys} />
+          : shortcuts.map(({ label, combo, keys }) => (
+            <Row key={label} label={label} combo={combo} keys={keys} />
           ))}
       </div>
     </div>

package/src/TouchDeviceOverlay.jsx

@@ -0,0 +1,50 @@
+import { useEffect, useState } from 'react'
+
+const STORAGE_KEY = 'kol-touch-warning-dismissed'
+
+/** useTouchPrimary — true on a coarse-pointer device (live). */
+export function useTouchPrimary() {
+  const [coarse, setCoarse] = useState(false)
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return undefined
+    const mq = window.matchMedia('(pointer: coarse)')
+    const update = () => setCoarse(mq.matches)
+    update()
+    mq.addEventListener?.('change', update)
+    return () => mq.removeEventListener?.('change', update)
+  }, [])
+  return coarse
+}
+
+/**
+ * TouchDeviceOverlay — "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
+ */
+export default function TouchDeviceOverlay({ appName = 'This app', message }) {
+  const coarse = useTouchPrimary()
+  const [dismissed, setDismissed] = useState(() => {
+    try { return localStorage.getItem(STORAGE_KEY) === '1' } catch { return false }
+  })
+  if (!coarse || dismissed) return null
+  const dismiss = () => {
+    try { localStorage.setItem(STORAGE_KEY, '1') } catch { /* storage blocked */ }
+    setDismissed(true)
+  }
+  return (
+    <div className="fixed inset-0 select-none bg-fg-inverse-08" style={{ display: 'grid', placeItems: 'center', backdropFilter: 'blur(2px)', zIndex: 100 }}>
+      <div className="bg-surface-primary border border-oq-08" style={{ width: 360, borderRadius: 4, padding: '20px 20px 16px', display: 'flex', flexDirection: 'column', gap: 12 }}>
+        <div className="kol-helper-14 text-fg-96">Desktop recommended</div>
+        <div className="kol-mono-12 text-fg-64">
+          {message ?? `${appName} is built for mouse and keyboard — drag, tweak and use keyboard shortcuts. Touch input isn't supported yet.`}
+        </div>
+        <button type="button" onClick={dismiss} className="kol-helper-12 text-fg-96 bg-fg-08 border border-oq-08 cursor-pointer" style={{ padding: '8px 12px', borderRadius: 4, marginTop: 4, alignSelf: 'flex-end' }}>
+          Continue anyway
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/index.js

@@ -23,3 +23,8 @@ export { default as SettingsScaffold, SettingsSection, LabelRow } from './Settin
 export { default as WalkthroughPanel } from './WalkthroughPanel.jsx'
 export { default as ShortcutsOverlay } from './ShortcutsOverlay.jsx'
 export { default as Logomark } from './Logomark.jsx'
+// the app tier, shipped once (ShellHomeSystem, kol-fxr 2026-08-27)
+export { default as CatalogPage } from './CatalogPage.jsx'
+export { default as SettingsShortcuts } from './SettingsShortcuts.jsx'
+export { default as SettingsLinks, SettingsColophon } from './SettingsLinks.jsx'
+export { default as TouchDeviceOverlay, useTouchPrimary } from './TouchDeviceOverlay.jsx'