@kolkrabbi/kol-component 0.223.0 → 0.225.0

package/src/organisms/SettingsPanel.jsx

@@ -171,7 +171,11 @@ export function LabeledControlSection({ label, divided = false, rowGap = 2, chil
  *  rebuilt this same Dropdown in a local `ChoiceRow`, which is the exact
  *  duplication this component exists to prevent. A component that wraps another
  *  has to forward the wrapped one's seams or it becomes a wall. */
-export function SettingsChoice({ options = [], value, onChange, ariaLabel, tone = 'default', size = 'sm', variant = 'primary', className = '' }) {
+/* `variant` UNSET by default (the Hub review, 2026-09-26): a forced `primary` blocked the
+ * tone of a `kol-tone-*` wrapper, so a sunken settings page drew a light well in every row
+ * unless the row said `tone="sunken"` itself. Unset, Dropdown takes the wrapper's tone and
+ * falls back to primary — the same render wherever there is no wrapper. */
+export function SettingsChoice({ options = [], value, onChange, ariaLabel, tone = 'default', size = 'sm', variant, className = '' }) {
   const opts = options.map((o) => (o != null && typeof o === 'object' ? o : { value: o, label: String(o) }))
   return <Dropdown size={size} variant={variant} tone={tone} value={value} onChange={onChange} options={opts} className={`w-full ${className}`.trim()} aria-label={ariaLabel} />
 }

package/src/organisms/SettingsSections.jsx

@@ -35,7 +35,7 @@ import { LabeledControlSection, SettingsRow } from './SettingsPanel.jsx'
  * first included: the rule is `.kol-section--divided + .kol-section--divided`,
  * so the first draws nothing and skipping it just costs the next its line.
  *
- * @param {Array<{label?: string, rows: Array<{label: ReactNode, render?: Function, value?: ReactNode, align?: string, labelWidth?: number|'auto', id?: string}>, rowGap?: number}>} sections - The settings body, in order
+ * @param {Array<{label?: string, rows: Array<{label: ReactNode, render?: Function, value?: ReactNode, hint?: string, align?: string, labelWidth?: number|'auto', id?: string}>, rowGap?: number}>} sections - The settings body, in order (`hint` → SettingsRow's hint)
  * @param {boolean} [divided=false] - Hairline above each section
  * @param {number|'auto'} [labelWidth] - Default label column for every row — `'auto'` makes the label yield and the control hug, which is what a narrow column or a nowrap value needs
  * @param {string} [align] - Default row alignment passed to `SettingsRow`
@@ -50,6 +50,7 @@ export default function SettingsSections({ sections = [], divided = false, label
             <SettingsRow
               key={row.id ?? row.label ?? j}
               label={row.label}
+              hint={row.hint}
               align={row.align ?? align}
               labelWidth={row.labelWidth ?? labelWidth}
             >

package/src/organisms/SpectrumGrid.jsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react'
 import ColorSwatch from '../atoms/ColorSwatch.jsx'
 import { resolveCssVar, resolveCssColor, isLight } from '../hooks/cssVar.js'
+import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
  * SpectrumGrid — matrix view of the whole ramp system: rows = ramps, columns =
@@ -63,10 +64,9 @@ export default function SpectrumGrid({ ramps, stops = DEFAULT_STOPS, brandAnchor
             const textColor = isLight(color) ? '#000' : '#fff'
             const brand = isBrandAnchor(ramp, stop)
             return (
+              <Tooltip key={stop} label={`${ramp}-${stop}  ${hex}${brand ? '  · brand anchor' : ''}`} asChild>
               <div
-                key={stop}
                 className="relative aspect-[5/3] rounded overflow-hidden transition-transform hover:scale-[1.04]"
-                title={`${ramp}-${stop}  ${hex}${brand ? '  · brand anchor' : ''}`}
               >
                 <ColorSwatch hex={`var(--${ramp}-${stop})`} size="stretch" radius="none" frame={false} className="absolute inset-0" />
                 <div className="pointer-events-none absolute inset-0 px-2 py-1.5" style={{ color: textColor }}>
@@ -81,6 +81,7 @@ export default function SpectrumGrid({ ramps, stops = DEFAULT_STOPS, brandAnchor
                   )}
                 </div>
               </div>
+              </Tooltip>
             )
           })}
         </div>

package/src/organisms/TimelineDock.jsx

@@ -1,6 +1,7 @@
 import { useRef, useState } from 'react'
 import Input from '../atoms/Input.jsx'
 import Dropdown from '../molecules/Dropdown.jsx'
+import { Tooltip } from '../utilities/Popover.jsx'
 
 /* The six easings the key editor offers. The CURVES stay the consumer's
  * (its interpolator resolves the name); this is the menu, not the math. */
@@ -123,9 +124,11 @@ function TrackRow({ track, t, selected, setSelected, writeKeys }) {
 
   return (
     <div className="flex items-center gap-3">
-      <span className="kol-helper-10 text-meta truncate shrink-0 text-right" style={{ width: 120 }} title={track.label}>
+      <Tooltip label={track.label} asChild>
+      <span className="kol-helper-10 text-meta truncate shrink-0 text-right" style={{ width: 120 }}>
         {track.label}
       </span>
+      </Tooltip>
       <div
         ref={laneRef}
         className="relative flex-1 h-5 rounded cursor-copy"
@@ -136,13 +139,12 @@ function TrackRow({ track, t, selected, setSelected, writeKeys }) {
         {track.keys.map((k, i) => {
           const kt = drag.current?.index === i ? drag.current.t : k.t
           return (
+            <Tooltip key={i} label={`t=${kt.toFixed(2)} v=${typeof k.v === 'number' ? Math.round(k.v * 100) / 100 : k.v} (alt-click deletes)`} asChild>
             <span
-              key={i}
               data-diamond=""
               onPointerDown={onDiamondPointerDown(i)}
               onPointerMove={onDiamondPointerMove(i)}
               onPointerUp={onDiamondPointerUp(i)}
-              title={`t=${kt.toFixed(2)} v=${typeof k.v === 'number' ? Math.round(k.v * 100) / 100 : k.v} (alt-click deletes)`}
               className="absolute top-1/2 cursor-grab"
               style={{
                 left: `${kt * 100}%`,
@@ -152,6 +154,7 @@ function TrackRow({ track, t, selected, setSelected, writeKeys }) {
                 borderRadius: 1.5,
               }}
             />
+            </Tooltip>
           )
         })}
       </div>

package/src/organisms/ToolPalette.jsx

@@ -2,6 +2,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
 import Button from '../atoms/Button.jsx'
 import Divider from '../atoms/Divider.jsx'
 import SplitToolButton from '../molecules/SplitToolButton.jsx'
+import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
  * ToolPalette — the editor's tool bar as one row (kol-fxr `shell/panels/ToolPalette.jsx`,
@@ -45,7 +46,6 @@ const ToolPalette = ({
   <div className={`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" />
-      const tip = it.shortcut ? `${it.label} (${it.shortcut})` : it.label
       if (it.kind === 'split') {
         const variants = (it.variants ?? []).map((v) => (v.action && !it.action ? { ...v, onSelect: () => onAction?.(v.id) } : v))
         const run = (id) => (it.action ? onAction : onSelect)?.(id)
@@ -58,10 +58,13 @@ const ToolPalette = ({
       }
       const isTool = it.kind === 'tool'
       return (
-        <Button key={it.id} variant="ghost" size={size} quiet iconOnly={it.icon} iconComponent={iconComponent}
+        /* the DS tooltip carries the key as its own chip (the native-title sweep, 2026-09-26) */
+        <Tooltip key={it.id} label={it.label} shortcut={it.shortcut}>
+        <Button variant="ghost" size={size} quiet iconOnly={it.icon} iconComponent={iconComponent}
           pressed={isTool ? activeId === it.id : undefined} disabled={it.disabled}
-          aria-label={it.label} title={tip}
+          aria-label={it.label}
           onClick={(e) => { (isTool ? onSelect : onAction)?.(it.id); blur(e) }} />
+        </Tooltip>
       )
     })}
   </div>

package/src/utilities/Popover.jsx

@@ -1,5 +1,5 @@
-import { createContext, useContext, useState } from 'react'
-import { toneClass } from './tone.js'
+import { cloneElement, createContext, isValidElement, useContext, useLayoutEffect, useState, version as reactVersion } from 'react'
+import { toneClass, TONE_VARS } from './tone.js'
 import {
   useFloating,
   autoUpdate,
@@ -136,13 +136,29 @@ export function usePopover({
  * — the innermost wins, as the native `title` it replaced behaved. */
 const TooltipNest = createContext(null)
 
-export function Tooltip({
+/* `asChild` (the native-title sweep, 2026-09-26): the tooltip attaches to its one child element
+ * instead of wrapping it in a span — for a trigger whose box IS the layout (a grid cell, a rail row,
+ * an absolutely placed handle), where an inline-flex wrapper would move it. The child must be an
+ * element that takes a ref: an intrinsic tag always does; a component only if it forwards one
+ * (React 18 needs forwardRef), so Button / IconFrame keep the wrapper. Its own ref and handlers are
+ * kept — the reference props merge over the child's. */
+const childRefOf = (el) => ('ref' in (el.props ?? {}) ? el.props.ref : reactVersion.startsWith('18') ? el.ref : undefined)
+
+export function Tooltip(props) {
+  /* no label → no tooltip: several call sites pass an optional hint, and an empty panel is worse
+   * than none. A separate component so the hooks below never run conditionally. */
+  if (props.label == null || props.label === '') return props.children
+  return <TooltipOn {...props} />
+}
+
+function TooltipOn({
   label,
   shortcut,
   placement = 'bottom',
   offset = 6,
   children,
   triggerClassName = 'inline-flex',
+  asChild = false,
 }) {
   const [open, setOpen] = useState(false)
   const [covered, setCovered] = useState(false)
@@ -158,22 +174,56 @@ export function Tooltip({
     focus: true,
   })
 
+  /* THE TONE OF WHERE IT IS (user, 2026-09-26: "tooltip should probably use same tone as dropdowns
+   * and buttons"). The panel is portalled to body, outside the `kol-tone-*` wrapper that tones the
+   * controls around the trigger — Dropdown's problem, solved the same way: on open, copy the
+   * trigger's RESOLVED `--kol-tone-*` onto the panel. No tone in effect = nothing copied, and the
+   * tooltip keeps its own surface. */
+  const [ambient, setAmbient] = useState(null)
+  const shown = open && !covered
+  useLayoutEffect(() => {
+    const ref = popover.refs.reference.current
+    /* the SURROUNDINGS' tone, not the trigger's own: an `asChild` trigger can be a variant button
+     * (`kol-btn-ghost` carries its own `--kol-tone-*`), so read its parent; the wrapper span has no
+     * variant and inherits the ambient values as it is */
+    const el = asChild ? ref?.parentElement : ref
+    if (!shown || !(el instanceof Element)) return
+    const cs = getComputedStyle(el)
+    const vars = {}
+    for (const v of TONE_VARS) { const val = cs.getPropertyValue(v).trim(); if (val) vars[v] = val }
+    setAmbient(vars)
+  }, [shown]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  const child = asChild && isValidElement(children) ? children : null
+  const childRef = child ? childRefOf(child) : undefined
+  const setRef = (node) => {
+    popover.refs.setReference(node)
+    if (typeof childRef === 'function') childRef(node)
+    else if (childRef) childRef.current = node
+  }
   return (
     <>
-      <span
-        ref={popover.refs.setReference}
-        {...popover.getReferenceProps()}
-        className={triggerClassName}
-      >
-        <TooltipNest.Provider value={setCovered}>{children}</TooltipNest.Provider>
-      </span>
+      {child ? (
+        <TooltipNest.Provider value={setCovered}>
+          {cloneElement(child, { ...popover.getReferenceProps(child.props), ref: setRef })}
+        </TooltipNest.Provider>
+      ) : (
+        <span
+          ref={popover.refs.setReference}
+          {...popover.getReferenceProps()}
+          className={triggerClassName}
+        >
+          <TooltipNest.Provider value={setCovered}>{children}</TooltipNest.Provider>
+        </span>
+      )}
       <PopoverPanel
         popover={popover}
         focus={false}
         panel={false}
         className="kol-tooltip"
+        style={ambient ?? undefined}
       >
-        <span className="text-emphasis">{label}</span>
+        <span>{label}</span>
         {shortcut && <span className="kol-tooltip-key">{shortcut}</span>}
       </PopoverPanel>
     </>

package/src/utilities/QuadrantSync.jsx

@@ -38,6 +38,7 @@
  */
 
 import { useCallback, useEffect, useRef, useState } from 'react'
+import { Tooltip } from './Popover.jsx'
 
 /* ── coordinates ─────────────────────────────────────────────────────────
  * Pure. No DOM writes. The invariant everything rests on: a cell is a
@@ -442,14 +443,15 @@ export default function QuadrantSync ({
                   className="kol-mono-12 text-fg-96 bg-fg-04 border border-fg-16"
                   style={{ width: 52, padding: '5px 6px', textAlign: 'center', borderRadius: 4 }}
                 />
+                <Tooltip label="Set divisions so cells come out square at the current size" asChild>
                 <button
                   type="button" onClick={applySquare}
-                  title="Set divisions so cells come out square at the current size"
                   className="kol-helper-10 text-fg-96 border border-fg-16"
                   style={{ marginLeft: 'auto', padding: '5px 9px', borderRadius: 4, background: 'transparent', cursor: 'pointer' }}
                 >
                   square
                 </button>
+                </Tooltip>
               </div>
               {aspect && (
                 <div className="kol-mono-10 text-fg-48" style={{ marginTop: 6 }}>

package/src/utilities/frontmatter.js

@@ -27,3 +27,50 @@ export function parseFrontmatter(raw) {
   }
   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}`
+}

package/src/utilities/localDrafts.js

@@ -0,0 +1,50 @@
+/**
+ * localDrafts — a text file's unsaved edit, in BROWSER memory (media D1 plan v2, user ruling
+ * 2026-09-26: "draft saves can rely on browser memory … only what's needed goes to D1"). A draft is
+ * work in progress on one device; the database holds what must outlive the device. So the DS keeps
+ * drafts itself, keyed by bucket + file key, and no client needs a draft verb.
+ *
+ * Every write announces itself on `window` (`kol-media-drafts`), so a list elsewhere on the page
+ * (a Home shelf, the "unsaved draft" mark) re-reads without prop drilling. Storage can be missing
+ * or full (private mode, a quota) — every call degrades to "no draft", never to a throw.
+ */
+const PREFIX = 'kol-media-draft:'
+const EVENT = 'kol-media-drafts'
+const store = () => { try { return globalThis.localStorage ?? null } catch { return null } }
+const k = (bucket, key) => `${PREFIX}${bucket ?? ''}:${key}`
+const announce = () => { try { globalThis.dispatchEvent?.(new Event(EVENT)) } catch { /* no window */ } }
+
+export const DRAFTS_EVENT = EVENT
+
+/** `{ text, at }` (at = epoch ms) or null */
+export function readDraft(bucket, key) {
+  try { const raw = store()?.getItem(k(bucket, key)); return raw ? JSON.parse(raw) : null } catch { return null }
+}
+export function writeDraft(bucket, key, text) {
+  try { store()?.setItem(k(bucket, key), JSON.stringify({ text, at: Date.now() })); announce() } catch { /* quota */ }
+}
+export function clearDraft(bucket, key) {
+  try { store()?.removeItem(k(bucket, key)); announce() } catch { /* nothing to clear */ }
+}
+/** every draft in a bucket, newest first — `[{ key, at, size }]` */
+export function listDrafts(bucket) {
+  const s = store()
+  if (!s) return []
+  const head = k(bucket, '')
+  const out = []
+  for (let i = 0; i < s.length; i++) {
+    const name = s.key(i)
+    if (!name?.startsWith(head)) continue
+    try { const d = JSON.parse(s.getItem(name)); out.push({ key: name.slice(head.length), at: d.at, size: d.text?.length ?? 0 }) } catch { /* a foreign value */ }
+  }
+  return out.sort((a, b) => b.at - a.at)
+}
+/** a file or a folder moved: its drafts follow (a folder is a path ending in `/`) */
+export function moveDrafts(bucket, from, to) {
+  const moved = listDrafts(bucket).filter((d) => d.key === from || (from.endsWith('/') && d.key.startsWith(from)))
+  for (const d of moved) {
+    const draft = readDraft(bucket, d.key)
+    try { store()?.removeItem(k(bucket, d.key)); store()?.setItem(k(bucket, to + d.key.slice(from.length)), JSON.stringify(draft)) } catch { /* quota */ }
+  }
+  if (moved.length) announce()
+}