@kolkrabbi/kol-component 0.226.0 → 0.228.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.226.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",
@@ -35,7 +36,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.28.0"
+    "@kolkrabbi/kol-icons": "^0.29.0"
   },
   "files": [
     "src",

package/src/atoms/Input.jsx

@@ -56,6 +56,9 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *     iconLeft/prefix — the paint-bar anatomy ([swatch] FFFFFF is ONE
  *     container, not two boxes; ColorSwatchFieldSizing 2026-08-12). The
  *     consumer owns the node's sizing; the shell's padding frames it.
+ *   slotRight — its trailing mirror: an interactive node inside the shell, after the unit /
+ *     suffix — a combo field's chevron (the design editor's type size, 2026-09-27: the chevron
+ *     sat OUTSIDE the field as a second control). Not aria-hidden: it is a control.
  *
  * Chrome (bg/border/padding/transition/disabled) comes from .kol-control;
  * Input owns prefix/suffix/icon layout + the inner <input> styling.
@@ -75,6 +78,7 @@ export default function Input({
   prefix,
   suffix,
   slotLeft,
+  slotRight,
   affordance,
   unit,
   iconLeft,
@@ -217,6 +221,9 @@ export default function Input({
       {suffix !== undefined && (
         <span aria-hidden="true" className="text-meta pl-1 shrink-0">{suffix}</span>
       )}
+      {slotRight && (
+        <span className="flex items-center shrink-0 pl-1 ml-auto">{slotRight}</span>
+      )}
     </label>
   )
 }

package/src/atoms/SegmentedToggle.jsx

@@ -29,7 +29,8 @@
  *               strip (canvas alignment, transform cluster); onChange is the
  *               action dispatch.
  *   onChange  — handler (newValue) => void
- *   options   — [{ value, label, ariaLabel? }]
+ *   options   — [{ value, label, ariaLabel?, tooltip? }] — a cell whose label is not a string
+ *               (a glyph) shows its `ariaLabel` as a KOL Tooltip; `tooltip` overrides it
  *   variant   — 'default' (shipped chrome: shared outer stroke + dividers,
  *               filled active cell) | 'filled' (the state law's tiles: every
  *               cell a surface-secondary tile with 1px transparent gaps, NO
@@ -53,6 +54,7 @@
  *   className — additional classes on the outer shell
  */
 import { toneClass } from '../utilities/tone.js'
+import { Tooltip } from '../utilities/Popover.jsx'
 
 export default function SegmentedToggle({ value, onChange, options = [], variant = 'default', size = 'md', tone = 'default', ariaLabel, className = '' }) {
   const cellType = { xs: 'kol-mono-8', sm: 'kol-mono-12', md: 'kol-mono-14', lg: 'kol-mono-16' }[size]
@@ -86,8 +88,8 @@ export default function SegmentedToggle({ value, onChange, options = [], variant
       {options.map((opt, i) => {
         const isActive = !stateless && opt.value === value
         return (
+          <Tooltip key={opt.value} asChild label={opt.tooltip ?? (typeof opt.label === 'string' ? null : opt.ariaLabel)}>
           <button
-            key={opt.value}
             type="button"
             role={stateless ? undefined : 'radio'}
             aria-checked={stateless ? undefined : isActive}
@@ -98,6 +100,7 @@ export default function SegmentedToggle({ value, onChange, options = [], variant
           >
             {opt.label}
           </button>
+          </Tooltip>
         )
       })}
     </div>

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/InspectorSection.jsx

@@ -18,12 +18,31 @@
  * declaring it — that is the upgrade path if a consumer ever needs the stack
  * to vary the rule per-gap. One prop is a smaller API than a new component.
  *
+ * `pane` (editor inspector rebuild, 2026-09-27 — user: "why are we not sectioning off the panes?
+ * saying 'this is type' 'this is transform'"): the Affinity panel shape instead of a labelled form
+ * group — a titled header strip, a padded body, and a FULL-WIDTH rule between panes. Mount panes
+ * in a container with no horizontal padding; each pane pads itself, so its rule runs edge to edge.
+ *
  * @param {ReactNode} label    the group's name
  * @param {ReactNode} actions  controls on the label's row, right-aligned
  * @param {boolean}   divided  a hairline between divided siblings
+ * @param {boolean}   pane     the panel shape: header strip + body, full-width rules between panes
  * @param {string}    className
  */
-export default function InspectorSection({ label, actions = null, children, divided = false, className = '' }) {
+export default function InspectorSection({ label, actions = null, children, divided = false, pane = false, className = '' }) {
+  if (pane) {
+    return (
+      <section className={`kol-inspector-pane ${className}`.trim()}>
+        {(label || actions) && (
+          <header className="kol-inspector-pane-head">
+            {label && <h3 className="kol-inspector-pane-title">{label}</h3>}
+            {actions}
+          </header>
+        )}
+        <div className="kol-inspector-pane-body">{children}</div>
+      </section>
+    )
+  }
   return (
     <div className={`flex flex-col gap-2${divided ? ' kol-section--divided' : ''} ${className}`}>
       {/* `actions` — controls on the label's row, right-aligned (Figma's eye / plus on Fill and

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/molecules/SplitToolButton.jsx

@@ -140,7 +140,7 @@ const SplitToolButton = ({
         popover={popover}
         panel={false}
         focus={false}
-        className="w-max bg-surface-secondary border border-fg-08 rounded shadow-lg"
+        className="w-max bg-surface-secondary border border-oq-08 rounded shadow-lg"
       >
         {variants.map((variant) => {
           const isActive = active && variant.id === value

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/organisms/ToolPalette.jsx

@@ -43,7 +43,7 @@ const ToolPalette = ({
   iconComponent = Icon,
   className = '',
 }) => (
-  <div className={`flex items-center gap-1 min-w-0 overflow-x-auto ${className}`.trim()}>
+  <div className={`kol-tool-palette flex items-center gap-1 min-w-0 overflow-x-auto ${className}`.trim()}>
     {items.map((it, i) => {
       if (it.kind === 'divider') return <Divider key={`d${i}`} variant="vertical" height={20} className="mx-1.5 shrink-0" />
       if (it.kind === 'split') {

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}`
-}