@kolkrabbi/kol-component 0.227.0 → 0.228.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.227.0",
+  "version": "0.228.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,8 @@
     "@floating-ui/react": "^0.27.19",
     "embla-carousel-react": "^8.6.0",
     "pdfjs-dist": "^6.3.289",
-    "react-syntax-highlighter": "^16.1.1"
+    "react-syntax-highlighter": "^16.1.1",
+    "@kolkrabbi/kol-markdown": "^0.1.0"
   },
   "peerDependencies": {
     "@kolkrabbi/kol-icons": ">=0.22.0",

package/src/index.js

@@ -116,6 +116,8 @@ export { default as PropertyInput } from './molecules/PropertyInput.jsx'
 export { default as ShapeDropdown } from './molecules/ShapeDropdown.jsx'
 export { default as ShellDrawer } from './molecules/ShellDrawer.jsx'
 export { default as ShellSearchOverlay } from './organisms/ShellSearchOverlay.jsx'
+/* the keymap sheet — moved in from kol-shell 2026-09-28 so the workshop shell and the apps open ONE sheet on S */
+export { default as ShortcutsOverlay } from './organisms/ShortcutsOverlay.jsx'
 export { default as Slider } from './molecules/Slider.jsx'
 export { default as SpecList } from './molecules/SpecList.jsx'
 export { default as SpectrumControls, HueStrip, SBSquare, WheelTriangle } from './organisms/SpectrumControls.jsx'
@@ -188,7 +190,7 @@ export { default as RowMenuButton } from './molecules/RowMenuButton.jsx'
 export { default as DocPage } from './molecules/DocPage.jsx'
 export { default as DocFrontmatter } from './molecules/DocFrontmatter.jsx'
 export { default as ProfileCard } from './molecules/ProfileCard.jsx'
-export { parseFrontmatter, splitFrontmatter, joinFrontmatter } from './utilities/frontmatter.js'
+export { parseFrontmatter, splitFrontmatter, joinFrontmatter } from '@kolkrabbi/kol-markdown'
 export { readDraft, writeDraft, clearDraft, listDrafts, moveDrafts, DRAFTS_EVENT } from './utilities/localDrafts.js'
 export { readCover } from './utilities/id3.js'
 export { kindOf, extOf, isSystemFile, KINDS, KIND_LABEL, DEFAULT_KINDS, isSegment, groupSegments, groupVariants, posterFor, partition } from './utilities/mediaKinds.js'

package/src/molecules/KindPreview.jsx

@@ -7,7 +7,7 @@ import FileIcon from '../atoms/FileIcon.jsx'
 import PdfPage, { PdfDocument } from './PdfPage.jsx'
 import { kindOf as defaultKindOf, extOf as defaultExtOf, KIND_LABEL } from '../utilities/mediaKinds.js'
 import markdownToHtml from '../utilities/markdownToHtml.js'
-import { parseFrontmatter } from '../utilities/frontmatter.js'
+import { parseFrontmatter } from '@kolkrabbi/kol-markdown'
 import DocPage from './DocPage.jsx'
 
 /* taxonomy-ok: molecule — nests the DS media atoms + CodeBlock (relative). */

package/src/organisms/DocumentEditor.jsx

@@ -7,7 +7,7 @@ import ViewToggle from '../atoms/ViewToggle.jsx'
 import QuickLookFrame from '../molecules/QuickLookFrame.jsx'
 import KindPreview from '../molecules/KindPreview.jsx'
 import FullscreenOverlay from '../utilities/FullscreenOverlay.jsx'
-import { splitFrontmatter, joinFrontmatter } from '../utilities/frontmatter.js'
+import { splitFrontmatter, joinFrontmatter } from '@kolkrabbi/kol-markdown'
 import { readDraft, writeDraft, clearDraft } from '../utilities/localDrafts.js'
 
 /**

package/src/organisms/MediaLibraryPages.jsx

@@ -34,7 +34,7 @@ import { useModal } from '../molecules/Modal.jsx'
 import ContentFilters from './ContentFilters.jsx'
 import DocumentEditor from './DocumentEditor.jsx'
 import { listDrafts, moveDrafts, DRAFTS_EVENT } from '../utilities/localDrafts.js'
-import { parseFrontmatter } from '../utilities/frontmatter.js'
+import { parseFrontmatter } from '@kolkrabbi/kol-markdown'
 import ShellSearchOverlay from './ShellSearchOverlay.jsx'
 import ColumnBrowser, { isFileDrag, Preview as ColumnPreview, SelectionPreview } from './ColumnBrowser.jsx'
 import SettingsPanel, { SettingsSwitch, SettingsChoice, SettingsMulti, SettingsFooter } from './SettingsPanel.jsx'

package/src/organisms/ShellSearchOverlay.jsx

@@ -10,7 +10,21 @@ import Tag from '../atoms/Tag.jsx'
  * @param {string} label full row label
  * @param {string} query current query (empty / no match → plain label)
  */
-export function HighlightMatch({ label, query }) {
+export function HighlightMatch({ label, query, ranges }) {
+  /* An engine that already knows where it matched (kol-search's `highlights`)
+   * passes `ranges` — every hit, not just the first slice of the raw query. */
+  if (Array.isArray(ranges)) {
+    if (!ranges.length) return <span>{label}</span>
+    const out = []
+    let at = 0
+    ranges.forEach(([s, e], i) => {
+      if (s > at) out.push(<span key={`t${i}`}>{label.slice(at, s)}</span>)
+      out.push(<span key={`m${i}`} className="text-fg underline decoration-2 underline-offset-[3px]">{label.slice(s, e)}</span>)
+      at = e
+    })
+    if (at < label.length) out.push(<span key="rest">{label.slice(at)}</span>)
+    return <>{out}</>
+  }
   const idx = query ? label.toLowerCase().indexOf(query.toLowerCase()) : -1
   if (idx === -1) return <span>{label}</span>
   return (
@@ -47,6 +61,10 @@ export function HighlightMatch({ label, query }) {
  * @param {Function} onQueryChange (string) => void — input change
  * @param {Function} onSelect      (item) => void — row click / Enter; consumer navigates
  * @param {string}   placeholder   input placeholder
+ * @param {string}   [enterLabel]  what Enter does when no row is picked — shown as
+ *                                 the panel's last line, so Enter is never a surprise
+ *                                 (e.g. `All results for “q”`). Rows may carry
+ *                                 `highlights` ([start, end] ranges) from the engine.
  */
 export default function ShellSearchOverlay({
   open,
@@ -65,6 +83,7 @@ export default function ShellSearchOverlay({
   onQueryChange,
   onSelect,
   placeholder = 'Search…',
+  enterLabel,
 }) {
   const panelRef = useRef(null)
   const listRef = useRef(null)
@@ -210,12 +229,12 @@ export default function ShellSearchOverlay({
                 onClick={() => select(item)}
                 onMouseEnter={() => { setActiveIndex(i); setNavigated(true) }}
                 className={`flex items-center gap-2 px-4 py-1.5 cursor-pointer kol-mono-14 transition-colors ${
-                  i === active ? 'bg-fg-08 text-fg' : 'text-fg-64'
+                  i === active ? 'bg-fg-08 text-fg' : 'text-fg-80'
                 }`}
               >
                 <span className="flex flex-col min-w-0">
                   <span className="truncate">
-                    <HighlightMatch label={item.label} query={query} />
+                    <HighlightMatch label={item.label} query={query} ranges={item.highlights} />
                   </span>
                   {item.hint && (
                     <span className="kol-mono-12 text-fg-48 truncate">{item.hint}</span>
@@ -228,6 +247,12 @@ export default function ShellSearchOverlay({
             ))}
           </ul>
         )}
+        {!expanded && enterLabel && query && (
+          <p className="flex items-center gap-2 border-t border-fg-08 px-4 py-2 kol-helper-12 text-fg-64">
+            <kbd className="kol-helper-12 rounded-[var(--kol-radius-sm)] bg-fg-08 px-1.5 py-0.5 text-fg">↵</kbd>
+            {enterLabel}
+          </p>
+        )}
       </div>
     </div>
   )

package/src/organisms/ShortcutsOverlay.jsx

@@ -0,0 +1,100 @@
+import { useEffect } from 'react'
+import SettingsSections from './SettingsSections.jsx'
+
+/**
+ * ShortcutsOverlay — the keyboard-shortcut sheet: blurred scrim, centred
+ * 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.
+ *
+ * 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 COMPONENT WITH THE SETTINGS PAGE AND THE DRAWER (user, 2026-09-03:
+ * *"align it more to the settings sidebar"* → *"lets normalise a component
+ * they can grab"*). This sheet and `SettingsShortcuts` render the SAME keymap
+ * array and had drifted into two anatomies — a bespoke two-column grid with a
+ * plain `text-fg-32` heading and hand-rolled `<span>` pairs here, against
+ * eyebrow sections over `SettingsRow`s there, down to the combo being `fg-96`
+ * in one and `fg-32` in the other. Both go through `SettingsSections` now, the
+ * same call the settings page and the settings drawer use, so a shortcut reads
+ * identically wherever it is shown and a change to the row lands in all of
+ * them. The FRAME stays each one's own: a scrim and a centred sheet here, a
+ * six-column grid on the page, a right-anchored drawer over the thing you are
+ * looking at.
+ *
+ * `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, 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
+ */
+
+const isSectioned = (list) => Array.isArray(list?.[0]?.items)
+
+/* A shortcut as a settings ROW: the label on the left, the combo as the row's
+ * value. `labelWidth="auto"` makes the label yield and the combo hug — a combo
+ * is one token by nature and must not wrap. */
+const toRow = ({ label, combo, keys }) => ({
+  label,
+  align: 'fill',
+  labelWidth: 'auto',
+  value: <span className="text-fg-32 kol-helper-12 whitespace-nowrap">{combo ?? keys}</span>,
+})
+
+export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
+  useEffect(() => {
+    const onKey = (e) => { if (e.key === 'Escape') onClose?.() }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [onClose])
+
+  const sectioned = isSectioned(shortcuts)
+
+  return (
+    <div
+      onClick={onClose}
+      /* THE scrim (overlay-scrim-outliers, kol-client-olina 2026-09-03; user: "we
+         removed the blur and put just color on the background … we missed this").
+         This drew its own — an 8 % inverse wash plus a 2px blur — after the
+         2026-09-01 no-blur ruling and the one-tint-48 class. */
+      className="fixed inset-0 select-none kol-overlay-scrim"
+      style={{ display: 'grid', placeItems: 'center', zIndex: 'var(--kol-z-modal)' }}
+    >
+      {/* `bg-oq-04`, not `bg-surface-primary` (user, 2026-09-03: *"this is too
+          bright"*). Over a near-black editor canvas the raised page surface
+          reads as a lit slab, and an `fg-16` stroke on top of it was the
+          brightest edge on screen. The OPAQUE ramp is right here: the sheet
+          must not let the canvas through, and `oq-04` is a 4 % lift off the
+          ground rather than a surface from the page's own ladder — so the
+          panel separates from the scrimmed canvas without a stroke. */}
+      <div
+        /* THE SHEET FITS THE WINDOW (editor review #4, 2026-09-27): a long keymap — the design
+         * editor's is six sections — ran past both edges of the viewport with no way to reach the
+         * rest. Capped to the window less a margin, scrolling inside. */
+        className="kol-shortcuts-panel text-fg-64 kol-helper-12 bg-oq-04 flex flex-col gap-6 overflow-y-auto"
+        style={{ padding: 24, borderRadius: 4, maxHeight: 'calc(100dvh - 48px)' }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <SettingsSections
+          sections={sectioned
+            ? shortcuts.map(({ section, items = [] }) => ({ label: section, rowGap: 1, rows: items.map(toRow) }))
+            : [{ rowGap: 1, rows: shortcuts.map(toRow) }]}
+        />
+      </div>
+    </div>
+  )
+}

package/src/utilities/frontmatter.js

@@ -1,76 +0,0 @@
-/**
- * parseFrontmatter — the workshop engine's handrolled YAML-subset parser,
- * verbatim (`packages/workshop/src/engine/frontmatter.js`; DocPageAndKindShowcase,
- * kol-r2b2 2026-08-27): `key: value`, block lists (`  - item`), inline `[a, b]`
- * tags. Keys are lowercased. No gray-matter / js-yaml.
- */
-export function parseFrontmatter(raw) {
-  const metadata = {}
-  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-  if (!match) return metadata
-  const lines = match[1].split(/\r?\n/)
-  for (let i = 0; i < lines.length; i++) {
-    const kv = lines[i].match(/^([A-Za-z][A-Za-z0-9 -]*):\s*(.*)$/)
-    if (!kv) continue
-    const key = kv[1].toLowerCase()
-    const value = kv[2].trim()
-    if (!value) {
-      const items = []
-      while (i + 1 < lines.length && lines[i + 1].match(/^\s+-\s+/)) { i++; items.push(lines[i].replace(/^\s+-\s+/, '').trim()) }
-      metadata[key] = items.length ? items : ''
-    } else {
-      metadata[key] = value
-    }
-  }
-  if (typeof metadata.tags === 'string' && metadata.tags.startsWith('[')) {
-    metadata.tags = metadata.tags.slice(1, -1).split(',').map((t) => t.trim()).filter(Boolean)
-  }
-  return metadata
-}
-
-/**
- * splitFrontmatter / joinFrontmatter — the EDITOR's pair (DocumentEditor, 2026-09-26). Where
- * `parseFrontmatter` reads for display (keys lowercased, lists flattened), these round-trip a file:
- * keys keep their case and their order, a list stays a list, and the body is untouched — so opening
- * and saving a document without touching the form changes nothing but what was edited.
- *
- * `fields` is `[[key, value]]`, value a string or an array of strings.
- */
-const unquote = (v) => {
-  if (v.length > 1 && v.startsWith('"') && v.endsWith('"')) { try { return JSON.parse(v) } catch { return v.slice(1, -1) } }
-  if (v.length > 1 && v.startsWith("'") && v.endsWith("'")) return v.slice(1, -1).replace(/''/g, "'")
-  return v
-}
-
-export function splitFrontmatter(raw = '') {
-  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
-  if (!match) return { has: false, fields: [], body: raw }
-  const fields = []
-  const lines = match[1].split(/\r?\n/)
-  for (let i = 0; i < lines.length; i++) {
-    const kv = lines[i].match(/^([A-Za-z_][\w -]*):\s*(.*)$/)
-    if (!kv) continue
-    let value = kv[2].trim()
-    if (!value) {
-      const items = []
-      while (i + 1 < lines.length && /^\s+-\s+/.test(lines[i + 1])) { i++; items.push(lines[i].replace(/^\s+-\s+/, '').trim()) }
-      value = items.length ? items : ''
-    } else if (value.startsWith('[') && value.endsWith(']')) {
-      value = value.slice(1, -1).split(',').map((t) => unquote(t.trim())).filter(Boolean)
-    } else {
-      value = unquote(value)
-    }
-    fields.push([kv[1], value])
-  }
-  return { has: true, fields, body: raw.slice(match[0].length) }
-}
-
-/* bare when YAML reads it back as the same string; quoted otherwise (a colon, a leading #, quotes) */
-const yamlScalar = (v) => (/^[\w./@+-][\w ./@+,-]*$/.test(v) || v === '' ? v : JSON.stringify(v))
-
-export function joinFrontmatter(fields, body = '') {
-  const rows = fields.filter(([key]) => String(key).trim())
-  if (!rows.length) return body
-  const yaml = rows.map(([key, v]) => (Array.isArray(v) ? `${key}: [${v.map(yamlScalar).join(', ')}]` : `${key}: ${yamlScalar(String(v ?? ''))}`)).join('\n')
-  return `---\n${yaml}\n---\n${body.startsWith('\n') ? body.slice(1) : body}`
-}