@kolkrabbi/kol-shell 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -20,10 +20,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-framework": "^0.20.1",
-    "@kolkrabbi/kol-icons": "^0.17.0",
-    "@kolkrabbi/kol-theme": "^0.42.2",
-    "@kolkrabbi/kol-component": "^0.43.0"
+    "@kolkrabbi/kol-component": "^0.46.0",
+    "@kolkrabbi/kol-framework": "^0.22.0",
+    "@kolkrabbi/kol-theme": "^0.43.1",
+    "@kolkrabbi/kol-icons": "^0.17.0"
   },
   "files": [
     "src",

package/src/ShortcutsOverlay.jsx

@@ -2,15 +2,50 @@ import { useEffect } from 'react'
 
 /**
  * ShortcutsOverlay — the keyboard-shortcut sheet: blurred scrim, centred
- * panel, one flat 2-col grid (label · keys), Esc / backdrop-click close.
+ * panel, a 2-col grid (label · keys), Esc / backdrop-click close.
  * Ported from the shared cut (mirror's, "copied from kol-monitor").
  *
  * `shortcuts` is a prop — feed the SAME array your settings page renders
  * (both repos hand-maintained the list twice and both pairs drifted).
  * Stacks at `--kol-z-modal`, above the rail's sticky tier.
  *
- * @param {Array} props.shortcuts - `[{ label, keys }]`
+ * TWO FORMS, DETECTED ON SHAPE (ShortcutsOverlaySections, kol-fxr 2026-08-15):
+ *
+ *   flat       `[{ label, keys }]`                  — one grid, as shipped
+ *   sectioned  `[{ section, items: [{label,keys}] }]` — headings between groups
+ *
+ * The flat form renders EXACTLY as it did before, so no existing caller moves.
+ * The sectioned form exists because a real keymap is grouped — kol-fxr's is
+ * Edit · Selection · Layer · Tools · View, and its `shortcutsBySection()`
+ * already emits this shape — and flattening it to adopt this component would
+ * have lost the grouping. That consumer kept a 99-line local overlay instead,
+ * which is the duplication this component exists to end.
+ *
+ * ONE GRID, NOT NESTED ONES. The headings span both columns
+ * (`gridColumn: 1 / -1`) so every `keys` cell in the sheet stays on the same
+ * axis — nesting a grid per section would let each group compute its own
+ * column width and the keys would stagger down the panel.
+ *
+ * `keys` is a DISPLAY STRING and is never bound — this component shows a
+ * 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 {Function} props.onClose
  */
+
+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 }) {
+  return (
+    <span className="contents">
+      <span>{label}</span><span className="text-fg-96">{keys}</span>
+    </span>
+  )
+}
+
 export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
   useEffect(() => {
     const onKey = (e) => { if (e.key === 'Escape') onClose?.() }
@@ -18,6 +53,8 @@ export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
     return () => window.removeEventListener('keydown', onKey)
   }, [onClose])
 
+  const sectioned = isSectioned(shortcuts)
+
   return (
     <div
       onClick={onClose}
@@ -25,11 +62,23 @@ export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
       style={{ display: 'grid', placeItems: 'center', backdropFilter: 'blur(2px)', zIndex: 'var(--kol-z-modal)' }}
     >
       <div className="text-fg-64 kol-helper-12 bg-surface-primary border border-fg-16" style={{ display: 'grid', gridTemplateColumns: 'auto auto', gap: '10px 62px', padding: 24, borderRadius: 4 }}>
-        {shortcuts.map(({ label, keys }) => (
-          <span key={label} className="contents">
-            <span>{label}</span><span className="text-fg-96">{keys}</span>
-          </span>
-        ))}
+        {sectioned
+          ? shortcuts.map(({ section, items = [] }, i) => (
+            <span key={section} className="contents">
+              <span
+                className="text-fg-32"
+                style={{ gridColumn: '1 / -1', marginTop: i === 0 ? 0 : 14 }}
+              >
+                {section}
+              </span>
+              {items.map(({ label, keys }) => (
+                <Row key={`${section}:${label}`} label={label} keys={keys} />
+              ))}
+            </span>
+          ))
+          : shortcuts.map(({ label, keys }) => (
+            <Row key={label} label={label} keys={keys} />
+          ))}
       </div>
     </div>
   )

package/src/TabStrip.jsx

@@ -8,25 +8,22 @@
  * want GRID). `tracked` adds the 1px letter-spacing the view-mode strips
  * carried.
  *
- * `value` takes a **Set** for a multi-select strip (ContentFilters' filter
- * values, ruled 2026-08-15 to wear this exact idiom rather than Tag chips) or
- * a scalar for the single-select tabs. One ink recipe, both behaviours — the
- * alternative was a second copy of the active/rest classes, which is how the
- * two shipped shells drifted in the first place.
+ * SINGLE-SELECT ONLY. A `Set` form for multi-select was added 2026-08-15 so the
+ * retired ContentFilters fork could render filter values through this — and
+ * removed the same day with it. A multi-select, handler-carrying, active/rest
+ * chip is a `Tag`; building a second one here under another name in another
+ * package is exactly the duplication kol-shell exists to end.
  *
  * @param {Array} props.options  `[{ value, label }]`
- * @param {Set|*} props.value    Set → multi-select · scalar → single-select
  */
 export default function TabStrip({ options = [], value, onChange, size = 14, tracked = false, className = 'gap-6', style }) {
-  const isOn = (opt) => (value instanceof Set ? value.has(opt.value) : value === opt.value)
-
   return (
     <div className={`flex items-center ${className}`.trim()} style={style}>
       {options.map((opt) => (
         <span
           key={opt.value}
           onClick={() => onChange?.(opt.value)}
-          className={`kol-helper-${size} cursor-pointer select-none ${isOn(opt) ? 'text-fg-96' : 'text-fg-32 hover:text-fg-48'}`}
+          className={`kol-helper-${size} cursor-pointer select-none ${value === opt.value ? 'text-fg-96' : 'text-fg-32 hover:text-fg-48'}`}
           style={tracked ? { letterSpacing: 1 } : undefined}
         >
           {opt.label}

package/src/index.js

@@ -14,7 +14,9 @@ export { NavHiddenContext, useNavHidden } from './navHidden.js'
 export { default as NavRail } from './NavRail.jsx'
 export { default as PageShell, PageBleed } from './PageShell.jsx'
 export { default as PageHeader } from './PageHeader.jsx'
-export { default as ContentFilters } from './ContentFilters.jsx'
+/* ContentFilters is NOT exported here — it lives in @kolkrabbi/kol-component,
+ * where it always did. This package shipped a recreated duplicate 0.1.0–0.2.0;
+ * retired 2026-08-15, quarantined in _tmp/. Import it from kol-component. */
 export { default as TabStrip } from './TabStrip.jsx'
 export { default as GridCard } from './GridCard.jsx'
 export { default as SettingsScaffold, SettingsSection, LabelRow } from './SettingsScaffold.jsx'

package/src/ContentFilters.jsx

@@ -1,320 +0,0 @@
-import { Fragment, useState, useMemo, useRef, useEffect } from 'react'
-import { Divider } from '@kolkrabbi/kol-component'
-import { Icon } from '@kolkrabbi/kol-icons'
-import TabStrip from './TabStrip.jsx'
-
-/**
- * ContentFilters — the catalog organism: header row (title + count), a
- * toggled filter-chip panel, the expanding pill search, view-mode/layout
- * strips (TabStrip), and a render-prop for the filtered items.
- *
- * Recreated from the mirror cut (the newer of the two shipped copies) with
- * the shipped defects fixed: the dead ViewToggle import dropped (both repos
- * carried it), `text-transform: uppercase` on the strips dropped (no
- * auto-casing law — author labels in the case they should render; the 1px
- * tracking stays via TabStrip `tracked`), and mirror's `bg-container-secondary`
- * hover (a class no theme CSS defines) → `bg-fg-04`.
- *
- * Grid geometry law (documented default, both source repos, both pages):
- * grid = `repeat(6, 1fr)` gap 24 · list = `repeat(4, 1fr)` gap 8.
- *
- * @param {Array} props.items - Items to filter
- * @param {string} props.title - Section title
- * @param {number} props.totalCount - Count before filtering
- * @param {Array} props.filterGroups - `[{ label, key, values }]`
- * @param {Function} props.renderItem - `(filteredItems, viewMode, layout) => node`
- * @param {Array} props.viewModeOptions - `[{ value, label }]` for the view strip
- * @param {Array} props.mutuallyExclusiveFilters - filter keys that self-clear
- * @param {Array} props.customFilterKeys - keys renderItem handles, not this organism
- * @param {ElementType} props.iconComponent - icon seam (defaults to DS Icon; needs `filter` + `search`)
- * @param {Function} props.renderFilterValue - `(value, isActive, toggle) => node`, one filter value
- * @param {string} props.labelClassName - REPLACES the group label's class (never stacks)
- *
- * **The two rendering seams (0.2.0).** How a filter value and a group label look
- * is the consumer's call, not this organism's. Three publishes in one day went
- * into re-ruling that here — outlined pills vs bare strip items vs chips — none
- * of which is a design-system question: it is what a given app's filter bar
- * should look like. `renderFilterValue` and `labelClassName` end that class of
- * change without a publish.
- *
- * `labelClassName` REPLACES rather than stacks, per the 2026-07-30 law: two
- * equal-specificity type classes on one element are decided by sheet order, so
- * a stacked seam produces different renders in different consumers with no
- * version difference. Same contract as ListingCard's `titleClassName`.
- *
- * Defaults reproduce 0.1.3 exactly — a bump moves nothing.
- */
-const ContentFilters = ({
-  items,
-  title,
-  totalCount,
-  filterGroups = [],
-  renderItem,
-  viewModeOptions,
-  viewMode: viewModeProp,
-  onViewModeChange,
-  defaultViewMode = 'list',
-  layoutOptions,
-  defaultLayout = 'grid',
-  onFilterChange,
-  mutuallyExclusiveFilters = [],
-  customFilterKeys = [],
-  searchKeys = ['label', 'name', 'title', 'type'],
-  headerActions,
-  showCountOnlyWhenFiltering = false,
-  iconComponent,
-  renderFilterValue,
-  labelClassName,
-}) => {
-  const [activeFilters, setActiveFilters] = useState(new Set())
-  const [isExpanded, setIsExpanded] = useState(false)
-  const [internalViewMode, setInternalViewMode] = useState(defaultViewMode)
-  const viewMode = viewModeProp !== undefined ? viewModeProp : internalViewMode
-  const [layout, setLayout] = useState(defaultLayout)
-  const [searchOpen, setSearchOpen] = useState(false)
-  const [searchText, setSearchText] = useState('')
-  const searchRef = useRef(null)
-  const IconSeam = iconComponent || Icon
-
-  useEffect(() => {
-    if (searchOpen && searchRef.current) searchRef.current.focus()
-  }, [searchOpen])
-
-  const toggleFilter = (filterType, value) => {
-    const newFilters = new Set(activeFilters)
-    const filterKey = `${filterType}:${value}`
-
-    if (newFilters.has(filterKey)) {
-      newFilters.delete(filterKey)
-    } else {
-      if (mutuallyExclusiveFilters.includes(filterType)) {
-        Array.from(newFilters).forEach(existingFilter => {
-          if (existingFilter.startsWith(`${filterType}:`)) {
-            newFilters.delete(existingFilter)
-          }
-        })
-      }
-      newFilters.add(filterKey)
-    }
-
-    setActiveFilters(newFilters)
-    if (onFilterChange) {
-      onFilterChange(newFilters, viewMode)
-    }
-  }
-
-  const clearAllFilters = () => {
-    setActiveFilters(new Set())
-    if (onFilterChange) {
-      onFilterChange(new Set(), viewMode)
-    }
-  }
-
-  const handleViewModeChange = (mode) => {
-    if (onViewModeChange) onViewModeChange(mode)
-    else setInternalViewMode(mode)
-    if (onFilterChange) {
-      onFilterChange(activeFilters, mode)
-    }
-  }
-
-  const filteredItems = useMemo(() => {
-    let result = items
-
-    if (searchText) {
-      const q = searchText.toLowerCase()
-      result = result.filter(item =>
-        searchKeys.some(key => {
-          const val = item[key]
-          return val && String(val).toLowerCase().includes(q)
-        })
-      )
-    }
-
-    if (activeFilters.size === 0) return result
-
-    return result.filter((item) => {
-      let matches = true
-      activeFilters.forEach((filter) => {
-        const [filterType, value] = filter.split(':')
-        if (customFilterKeys.includes(filterType)) return
-
-        const itemValue = item[filterType]
-        if (Array.isArray(itemValue)) {
-          if (!itemValue.includes(value)) matches = false
-        } else {
-          if (itemValue !== value) matches = false
-        }
-      })
-      return matches
-    })
-  }, [items, activeFilters, customFilterKeys, searchText, searchKeys])
-
-  // A group is a COLUMN: label on top, values beneath it (user ruling
-  // 2026-08-15). How a value and a label RENDER is the consumer's — three
-  // publishes in one day went into re-deciding that here, which is the defect
-  // the seams below end. Defaults are 0.1.3 exactly, so nothing moves on bump.
-  const renderFilterGroup = (group) => {
-    const prefix = `${group.key}:`
-    const selected = new Set(
-      Array.from(activeFilters)
-        .filter((f) => f.startsWith(prefix))
-        .map((f) => f.slice(prefix.length))
-    )
-
-    return (
-      <div key={group.key} className="flex flex-col gap-3">
-        <h4
-          className={labelClassName || 'kol-helper-12 text-fg-32'}
-          style={labelClassName ? undefined : { letterSpacing: 1 }}
-        >
-          {group.label}
-        </h4>
-        {renderFilterValue ? (
-          <div className="flex flex-wrap items-center gap-4">
-            {group.values.map((v) => (
-              <Fragment key={v}>
-                {renderFilterValue(v, selected.has(v), () => toggleFilter(group.key, v))}
-              </Fragment>
-            ))}
-          </div>
-        ) : (
-          <TabStrip
-            options={group.values.map((v) => ({ value: v, label: v }))}
-            value={selected}
-            onChange={(v) => toggleFilter(group.key, v)}
-            size={12}
-            tracked
-            className="gap-4 flex-wrap"
-          />
-        )}
-      </div>
-    )
-  }
-
-  return (
-    <div className="w-full" style={{ display: 'flex', flexDirection: 'column', flex: 1 }}>
-      {/* Header with filter toggle + expanding search */}
-      <div className="flex items-center justify-between mb-4">
-        <div className="flex items-center gap-6">
-          <h2 className="kol-helper-14">{title}</h2>
-          <div className="flex items-center gap-1">
-            <button
-              onClick={() => setIsExpanded(!isExpanded)}
-              className="p-2 hover:bg-fg-04 rounded-sm transition-colors leading-none"
-              aria-label="Toggle filters"
-            >
-              <IconSeam name="filter" size={16} />
-            </button>
-            <div
-              className="flex items-center rounded-full cursor-pointer"
-              style={{
-                height: 28,
-                width: searchOpen ? 200 : 28,
-                background: searchOpen ? 'var(--kol-fg-04, rgba(255,255,255,0.04))' : 'transparent',
-                transition: 'width 600ms cubic-bezier(0.16, 1, 0.3, 1), background 400ms cubic-bezier(0.16, 1, 0.3, 1)',
-                overflow: 'hidden',
-              }}
-              onClick={() => {
-                if (searchOpen) { setSearchOpen(false); setSearchText('') }
-                else setSearchOpen(true)
-              }}
-            >
-              <span
-                className="flex items-center justify-center flex-shrink-0"
-                style={{
-                  width: 28, height: 28,
-                  opacity: searchOpen ? 0 : 1,
-                  transition: 'opacity 300ms cubic-bezier(0.16, 1, 0.3, 1)',
-                  position: searchOpen ? 'absolute' : 'relative',
-                }}
-              >
-                <IconSeam name="search" size={16} />
-              </span>
-              {searchOpen && (
-                <input
-                  ref={searchRef}
-                  type="text"
-                  value={searchText}
-                  onChange={e => setSearchText(e.target.value)}
-                  onClick={e => e.stopPropagation()}
-                  placeholder=""
-                  className="bg-transparent outline-none kol-helper-12 flex-1 text-fg-80 caret-current px-4"
-                  onBlur={() => { if (!searchText) { setSearchOpen(false) } }}
-                  onKeyDown={e => { if (e.key === 'Escape') { setSearchOpen(false); setSearchText('') } }}
-                />
-              )}
-            </div>
-            {headerActions}
-          </div>
-          {activeFilters.size > 0 && (
-            <span
-              className="kol-helper-12 text-fg-48 cursor-pointer select-none group flex items-center gap-2"
-              onClick={(e) => { e.stopPropagation(); clearAllFilters() }}
-            >
-              <span className="underline">({activeFilters.size}) {activeFilters.size === 1 ? 'filter' : 'filters'} active</span>
-              <span className="hidden group-hover:inline text-fg-64">×</span>
-            </span>
-          )}
-        </div>
-
-        <div className="flex items-center gap-8">
-          {(!showCountOnlyWhenFiltering || isExpanded || searchOpen || activeFilters.size > 0) && (
-            <span className="kol-helper-14 text-fg-64">
-              {filteredItems.length} of {totalCount}
-            </span>
-          )}
-          {viewModeOptions && (
-            <TabStrip options={viewModeOptions} value={viewMode} onChange={handleViewModeChange} tracked />
-          )}
-        </div>
-      </div>
-
-      <Divider className="mb-4" />
-
-      {/* BELOW the divider: filter groups as left-aligned COLUMNS (only while
-          the filter toggle is open), layout strip RIGHT and ALWAYS visible.
-          `items-start` is load-bearing — it pins the strip to the label row, so
-          the strip and the group labels read as one line and the values hang
-          beneath. 0.1.1 read "at the divider level" as the header row above the
-          divider; the strip never belongs in the header
-          (ShellHeaderFilterRefinements, 2026-08-15). */}
-      {(layoutOptions || isExpanded) && (
-        <div className="flex items-start justify-between gap-16 mb-4">
-          <div className="flex items-start gap-16">
-            {isExpanded && filterGroups.map((group) => renderFilterGroup(group))}
-            {isExpanded && activeFilters.size > 0 && (
-              // Strip rest recipe, not its own ink — this button shares the line
-              // with the labels and values, and that line carries exactly TWO
-              // ink states (user ruling 2026-08-15: "we are not maintaining 3
-              // opacity states for one line in a component").
-              <button
-                onClick={clearAllFilters}
-                className="kol-helper-12 transition-colors underline text-fg-32 hover:text-fg-48"
-              >
-                Clear all ({activeFilters.size})
-              </button>
-            )}
-          </div>
-          {layoutOptions && (
-            <TabStrip
-              options={layoutOptions}
-              value={layout}
-              onChange={setLayout}
-              size={12}
-              tracked
-              className="gap-4"
-            />
-          )}
-        </div>
-      )}
-
-      {/* Render filtered items */}
-      <div className="mt-8" style={{ display: 'flex', flexDirection: 'column', flex: 1 }}>
-        {renderItem(filteredItems, viewMode, layout)}
-      </div>
-    </div>
-  )
-}
-
-export default ContentFilters