@kolkrabbi/kol-component 0.199.0 → 0.201.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.199.0",
+  "version": "0.201.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",

package/src/index.js

@@ -76,6 +76,8 @@ export { default as CropOverlay } from './atoms/CropOverlay.jsx'
 export { default as LayerStack, AddLayerButton, BLEND_MODES } from './organisms/LayerStack.jsx'
 export { TYPE_LABELS, BOOL_OP_LABELS, SHAPE_KIND_LABELS, labelForLayer, rowLabelForLayer, findLayerDeep } from './hooks/layerTree.js'
 export { default as TimelineDock, sampleTrack, TIMELINE_EASINGS } from './organisms/TimelineDock.jsx'
+export { default as CurveEditor, CURVE_KINDS, defaultCurveFor } from './organisms/CurveEditor.jsx'
+export { default as KeyframeEditor, KEYFRAME_EASES, DEFAULT_KEYFRAMES } from './organisms/KeyframeEditor.jsx'
 export { pathD, pathBounds, shiftNode, normalizePath, scalePathNodes, normalizePathRings, rotatePathNodes, dist, nearestSegmentT, splitSegment, smoothNode } from './hooks/pathMath.js'
 
 // molecules
@@ -156,6 +158,9 @@ export { default as MediaLibrary, MediaLibraryProvider, useMediaLibrary, MediaPi
 export { default as MediaTileGallery } from './organisms/MediaTileGallery.jsx'
 export { default as MediaViewer } from './organisms/MediaViewer.jsx'
 export { default as SettingsPanel, LabeledControlSection, SettingsRow, SettingsSwitch, SettingsChoice, SettingsMulti, SettingsChipRow, SettingsFooter } from './organisms/SettingsPanel.jsx'
+/* the settings BODY as data — one call for the page, the drawer and a sheet
+ * (user 2026-09-03: "lets normalise a component they can grab") */
+export { default as SettingsSections } from './organisms/SettingsSections.jsx'
 export { default as SectionNewsletter } from './organisms/SectionNewsletter.jsx'
 export { default as NewsletterBand } from './organisms/NewsletterBand.jsx'
 export { default as ColumnBrowser } from './organisms/ColumnBrowser.jsx'

package/src/organisms/CurveEditor.jsx

@@ -0,0 +1,207 @@
+import Button from '../atoms/Button.jsx'
+import Input from '../atoms/Input.jsx'
+import Dropdown from '../molecules/Dropdown.jsx'
+import LabeledControl from '../molecules/LabeledControl.jsx'
+
+/* The six curve kinds the picker offers. A consumer with more passes `kinds`. */
+export const CURVE_KINDS = [
+  { value: 'epicycle', label: 'Epicycle' },
+  { value: 'polar',    label: 'Polar' },
+  { value: 'param2d',  label: 'Parametric 2D' },
+  { value: 'param3d',  label: 'Parametric 3D' },
+  { value: 'points',   label: 'Points' },
+  { value: 'maurer',   label: 'Maurer rose' },
+]
+
+const TAU = Math.PI * 2
+
+/* Fresh per-kind defaults — the engine's `defaultCustomFor`, kept as the
+ * default so a kind switch has somewhere to land. Injectable via `defaultFor`. */
+export function defaultCurveFor(kind) {
+  switch (kind) {
+    case 'epicycle': return { kind, turns: 2, terms: [{ amp: 1, freq: 1, phase: 0 }] }
+    case 'param2d':  return { kind, range: [0, TAU], x: 'sin(3*t)', y: 'sin(2*t + 0.6)' }
+    case 'param3d':  return { kind, range: [0, 6 * TAU], x: 'cos(t)', y: 'sin(t)', z: '0.3*t' }
+    case 'points':   return { kind, count: 1400, a: 'k*TAU/(PHI*PHI)', r: 'sqrt(k)' }
+    case 'maurer':   return { kind, n: 6, d: 71 }
+    default:         return { kind: 'polar', range: [0, 6 * TAU], r: '3*sin(6*th)' }
+  }
+}
+
+const num = (v, fb) => { const n = Number(v); return Number.isFinite(n) ? n : fb }
+
+/* Draft/commit number — `Input onCommit` IS the idiom since 0.196.0. */
+function NumberField({ value, onCommit, ...rest }) {
+  return <Input type="number" variant="filled" size="sm" {...rest} value={String(value)} onCommit={onCommit} />
+}
+
+/* Draft/commit text input for an expression, mono. A string that does not
+ * validate is STILL committed — the renderer keeps its last good function —
+ * and the field shows the hint until it is fixed. That is what makes live
+ * expression editing bearable; keep it. */
+function ExprField({ label, value, args, validate, onCommit }) {
+  const bad = validate && String(value ?? '').trim() !== '' && !validate(value, args)
+  return (
+    <LabeledControl label={label} hint={bad ? 'doesn’t compile — last good kept' : undefined}>
+      <Input
+        variant="filled" size="sm" className="w-full"
+        style={{ fontFamily: 'var(--kol-font-family-mono, monospace)', fontVariantLigatures: 'none' }}
+        value={value ?? ''}
+        onCommit={(v) => { if (v !== value) onCommit(v) }}
+      />
+    </LabeledControl>
+  )
+}
+
+/* Start/end of the curve's parameter range. */
+function RangeFields({ def, commit }) {
+  const [a, b] = def.range || [0, 1]
+  return (
+    <div className="grid grid-cols-2 gap-2">
+      <LabeledControl label="Start">
+        <NumberField value={a} onCommit={(v) => commit({ range: [num(v, a), b] })} />
+      </LabeledControl>
+      <LabeledControl label="End">
+        <NumberField value={b} onCommit={(v) => commit({ range: [a, num(v, b)] })} />
+      </LabeledControl>
+    </div>
+  )
+}
+
+/* Epicycle = a sum of rotating vectors; each term {amp, freq, phase} is one
+ * vector (add/remove terms = the vector array). */
+function TermsEditor({ def, commit }) {
+  const terms = def.terms || []
+  const setTerm = (i, key, v) => commit({ terms: terms.map((tm, j) => (j === i ? { ...tm, [key]: v } : tm)) })
+  const addTerm = () => commit({ terms: [...terms, { amp: 0.5, freq: 2, phase: 0 }] })
+  const removeTerm = (i) => commit({ terms: terms.filter((_, j) => j !== i) })
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="flex items-center justify-between">
+        <span className="kol-helper-10 text-meta">Vectors</span>
+        <Button variant="primary" size="sm" onClick={addTerm}>Add</Button>
+      </div>
+      <div className="grid grid-cols-[1fr_1fr_1fr_auto] gap-1.5 items-center min-w-0 [&>*]:min-w-0">
+        <span className="kol-helper-10 text-fg-48 text-center">amp</span>
+        <span className="kol-helper-10 text-fg-48 text-center">freq</span>
+        <span className="kol-helper-10 text-fg-48 text-center">phase</span>
+        <span />
+        {terms.map((tm, i) => (
+          <TermRow key={i} term={tm} onSet={(k, v) => setTerm(i, k, v)} onRemove={() => removeTerm(i)} canRemove={terms.length > 1} />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function TermRow({ term, onSet, onRemove, canRemove }) {
+  const cell = (key, fallback) => (
+    <NumberField value={term[key] ?? fallback} onCommit={(v) => onSet(key, num(v, term[key] ?? fallback))} />
+  )
+  return (
+    <>
+      {cell('amp', 1)}
+      {cell('freq', 1)}
+      {cell('phase', 0)}
+      <Button variant="ghost" size="sm" onClick={onRemove} disabled={!canRemove} aria-label="Remove vector">×</Button>
+    </>
+  )
+}
+
+/**
+ * CurveEditor — curve authoring: a kind picker, per-kind ranges and
+ * EXPRESSION fields, and the epicycle term list.
+ *
+ * Lifted from kol-fxr's editor (`compose/inspectors/CurveEditor.jsx`,
+ * `editor-panels-the-held-specs` A4, 2026-09-03) with its two couplings
+ * dropped: the compiler (`loops/math/mathfn`) is the `validate` seam, and the
+ * stock-clip table (`loops/math/curves`) is the `stock` prop.
+ *
+ * FORK-ON-EDIT, kept exactly: while the layer shows a stock clip the editor
+ * displays that clip's definition (`value`), and the FIRST commit forks it —
+ * `onChange` fires with `fork: true` and the extras the fork should seed
+ * (`copies` / `spiral` from the stock clip, unless the caller says they were
+ * already moved). The shared clip table is never mutated; the caller writes
+ * `{ clip: 'custom', custom, ...extras }`. A kind switch replaces the whole
+ * def with that kind's defaults.
+ *
+ * @param {Object} value - The curve def being edited: `{ kind, range?, r?, x?, y?, z?, turns?, terms?, count?, a?, n?, d? }`
+ * @param {Function} onChange - `(nextDef, { fork, extras }) => void` — `fork` is true when this commit leaves a stock clip; `extras` carries what the fork seeds
+ * @param {{label: string, copies?: number, spiral?: number, layerCopies?: number, layerSpiral?: number}} [stock] - Present while the layer still shows a STOCK clip: its label, its authored `copies` / `spiral`, and the layer's current ones so the fork only seeds what the user has not moved. Omit once the curve is custom
+ * @param {Function} [validate] - `(expr, args) => boolean` — the consumer's compiler; omitted, every expression is accepted without a hint
+ * @param {Array<{value: string, label: string}>} [kinds] - The kind picker (default `CURVE_KINDS`)
+ * @param {Function} [defaultFor] - `(kind) => def` for a kind switch (default `defaultCurveFor`)
+ * @param {string} [className] - Extra classes on the editor
+ */
+export default function CurveEditor({ value, onChange, stock = null, validate, kinds = CURVE_KINDS, defaultFor = defaultCurveFor, className = '' }) {
+  const def = value ?? defaultFor('polar')
+  const kind = def.kind || 'polar'
+  const isCustom = stock == null
+
+  /* Any commit forks a stock clip — and seeds the copies/spiral the stock
+   * clip authored, unless the layer already moved them. */
+  const commit = (defPatch) => {
+    const extras = {}
+    if (!isCustom) {
+      if ((stock.layerCopies ?? 1) <= 1 && (stock.copies ?? 0) > 1) extras.copies = stock.copies
+      if (!((stock.layerSpiral ?? 0) > 0) && (stock.spiral ?? 0) > 0) extras.spiral = stock.spiral
+    }
+    onChange?.({ ...def, ...defPatch }, { fork: !isCustom, extras })
+  }
+  const setKind = (k) => {
+    if (k === kind) return
+    onChange?.(defaultFor(k), { fork: !isCustom, extras: {} })
+  }
+
+  return (
+    <div className={`kol-curve-editor flex flex-col gap-3 ${className}`.trim()}>
+      <span className="kol-helper-10 text-meta">Curve</span>
+      <Dropdown size="sm" variant="subtle" className="w-full" options={kinds} value={kind} onChange={setKind} />
+      {!isCustom && (
+        <p className="kol-helper-10 text-meta">Editing “{stock.label}” forks it to a custom curve.</p>
+      )}
+
+      {kind === 'epicycle' && (
+        <>
+          <LabeledControl label="Turns">
+            <NumberField value={def.turns ?? 1} onCommit={(v) => commit({ turns: num(v, def.turns ?? 1) })} />
+          </LabeledControl>
+          <TermsEditor def={def} commit={commit} />
+        </>
+      )}
+
+      {kind === 'polar' && (
+        <>
+          <RangeFields def={def} commit={commit} />
+          <ExprField label="r(th)" value={def.r} args={['th']} validate={validate} onCommit={(v) => commit({ r: v })} />
+        </>
+      )}
+
+      {(kind === 'param2d' || kind === 'param3d') && (
+        <>
+          <RangeFields def={def} commit={commit} />
+          <ExprField label="x(t)" value={def.x} args={['t']} validate={validate} onCommit={(v) => commit({ x: v })} />
+          <ExprField label="y(t)" value={def.y} args={['t']} validate={validate} onCommit={(v) => commit({ y: v })} />
+          {kind === 'param3d' && <ExprField label="z(t)" value={def.z} args={['t']} validate={validate} onCommit={(v) => commit({ z: v })} />}
+        </>
+      )}
+
+      {kind === 'points' && (
+        <>
+          <LabeledControl label="Count">
+            <NumberField value={def.count ?? 1400} onCommit={(v) => commit({ count: Math.max(1, Math.round(num(v, def.count ?? 1400))) })} />
+          </LabeledControl>
+          <ExprField label="a(k)" value={def.a} args={['k']} validate={validate} onCommit={(v) => commit({ a: v })} />
+          <ExprField label="r(k)" value={def.r} args={['k']} validate={validate} onCommit={(v) => commit({ r: v })} />
+        </>
+      )}
+
+      {kind === 'maurer' && (
+        <div className="grid grid-cols-2 gap-2">
+          <LabeledControl label="n"><NumberField value={def.n ?? 6} onCommit={(v) => commit({ n: num(v, def.n ?? 6) })} /></LabeledControl>
+          <LabeledControl label="d°"><NumberField value={def.d ?? 71} onCommit={(v) => commit({ d: num(v, def.d ?? 71) })} /></LabeledControl>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/organisms/KeyframeEditor.jsx

@@ -0,0 +1,136 @@
+import { useState } from 'react'
+import Button from '../atoms/Button.jsx'
+import Dropdown from '../molecules/Dropdown.jsx'
+import LabeledControl from '../molecules/LabeledControl.jsx'
+import Slider from '../molecules/Slider.jsx'
+
+const deg = (r) => Math.round(((r || 0) * 180) / Math.PI)
+const rad = (d) => (d * Math.PI) / 180
+
+/* The engine's easings by name; the curves are the consumer's interpolator's. */
+export const KEYFRAME_EASES = [
+  { value: 'linear', label: 'Linear' },
+  { value: 'in',     label: 'Ease in' },
+  { value: 'out',    label: 'Ease out' },
+  { value: 'inout',  label: 'Ease in-out' },
+]
+
+export const DEFAULT_KEYFRAMES = [
+  { t: 0, rot: [0, 0, 0], pos: [0, 0, 0], scale: 1, ease: 'inout' },
+  { t: 1, rot: [0, Math.PI * 2, 0], pos: [0, 0, 0], scale: 1, ease: 'inout' },
+]
+
+/**
+ * KeyframeEditor — a keyframe list over a pose track, kept sorted by `t`.
+ *
+ *   { t: 0..1, rot: [x, y, z] RADIANS, pos: [x, y, z], scale, ease }
+ *
+ * Rotations are stored in radians (engine-native) and EDITED IN DEGREES here.
+ * Selecting a key pauses the clock and seeks to its `t`, so the live render is
+ * the pose being edited; "Add @ playhead" reads the clock's current `t`.
+ *
+ * Lifted from kol-fxr's editor (`compose/inspectors/KeyframeEditor.jsx`,
+ * `editor-panels-the-held-specs` A5, 2026-09-03) with the transport singleton
+ * and the layer patch path dropped, as the row asked: the track is `keyframes`
+ * + `onChange`, the clock is `t` + `onSeek` + `onPause`. The engine's
+ * cycles arithmetic (a layer's phase runs N loops per transport loop) is the
+ * CONSUMER's — it hands in the layer-local `t` and maps `onSeek`'s local `t`
+ * back to its global playhead. The pose shape stays rot / pos / scale; the
+ * row notes it should be schema-described, and that is a design change
+ * rather than a port, so it is not done here.
+ *
+ * @param {Array<Object>} keyframes - The track; empty falls back to `DEFAULT_KEYFRAMES`
+ * @param {Function} onChange - `(keyframes) => void` — the whole track, sorted
+ * @param {number} t - The clock's current LAYER-LOCAL phase, 0..1 — what "Add @ playhead" stamps
+ * @param {Function} onSeek - `(t) => void` — a key was selected; seek the clock to its local `t`
+ * @param {Function} [onPause] - Called before the seek, so the render holds on the pose
+ * @param {Array<{value: string, label: string}>} [easeOptions] - The Ease menu (default `KEYFRAME_EASES`)
+ * @param {Array<Object>} [defaultKeyframes] - What an empty track shows (default `DEFAULT_KEYFRAMES`)
+ */
+export default function KeyframeEditor({
+  keyframes,
+  onChange,
+  t = 0,
+  onSeek,
+  onPause,
+  easeOptions = KEYFRAME_EASES,
+  defaultKeyframes = DEFAULT_KEYFRAMES,
+}) {
+  const kfs = Array.isArray(keyframes) && keyframes.length ? keyframes : defaultKeyframes
+  const [selected, setSelected] = useState(0)
+  const sel = Math.min(selected, kfs.length - 1)
+  const k = kfs[sel] || { rot: [0, 0, 0], pos: [0, 0, 0], scale: 1 }
+
+  const write = (next) => onChange?.(next)
+
+  const onSelect = (i) => {
+    setSelected(i)
+    onPause?.()
+    onSeek?.(kfs[i].t ?? 0)
+  }
+  const onAdd = () => {
+    const base = kfs[sel] || { rot: [0, 0, 0], pos: [0, 0, 0], scale: 1, ease: 'inout' }
+    const nk = {
+      t: Math.max(0, Math.min(1, t)),
+      rot: [...(base.rot || [0, 0, 0])],
+      pos: [...(base.pos || [0, 0, 0])],
+      scale: base.scale ?? 1,
+      ease: base.ease || 'inout',
+    }
+    const next = [...kfs, nk].sort((a, b) => a.t - b.t)
+    write(next)
+    setSelected(next.indexOf(nk))
+  }
+  const onDelete = () => {
+    if (kfs.length <= 1) return
+    write(kfs.filter((_, i) => i !== sel))
+    setSelected((s) => Math.max(0, s - 1))
+  }
+  const onPatch = (p) => write(kfs.map((kf, i) => (i === sel ? { ...kf, ...p } : kf)))
+
+  const setRot = (axis, d) => { const r = [...(k.rot || [0, 0, 0])]; r[axis] = rad(d); onPatch({ rot: r }) }
+  const setPos = (axis, v) => { const p = [...(k.pos || [0, 0, 0])]; p[axis] = v; onPatch({ pos: p }) }
+
+  const pose = (label, min, max, step, value, onValue) => (
+    <LabeledControl label={label}>
+      <Slider min={min} max={max} step={step} value={value} onChange={onValue} />
+    </LabeledControl>
+  )
+
+  return (
+    <div className="kol-keyframe-editor flex flex-col gap-3">
+      <span className="kol-helper-10 text-meta">Keyframes</span>
+      <div className="flex flex-col gap-1">
+        {kfs.map((kf, i) => (
+          <Button
+            key={i}
+            variant={i === sel ? 'primary' : 'secondary'}
+            size="sm"
+            className="w-full"
+            style={{ justifyContent: 'space-between' }}
+            onClick={() => onSelect(i)}
+          >
+            <span>Key {i + 1}</span>
+            <span className="kol-helper-10 tabular-nums">{Math.round((kf.t ?? 0) * 100)}%</span>
+          </Button>
+        ))}
+      </div>
+      <div className="flex gap-2">
+        <Button variant="primary" size="sm" className="flex-1" onClick={onAdd}>Add @ playhead</Button>
+        <Button variant="ghost" size="sm" title="Delete keyframe" onClick={onDelete} disabled={kfs.length <= 1}>Delete</Button>
+      </div>
+
+      <span className="kol-helper-10 text-meta">Pose</span>
+      {pose('Rotate X', -360, 360, 1, deg(k.rot?.[0]), (v) => setRot(0, v))}
+      {pose('Rotate Y', -360, 360, 1, deg(k.rot?.[1]), (v) => setRot(1, v))}
+      {pose('Rotate Z', -360, 360, 1, deg(k.rot?.[2]), (v) => setRot(2, v))}
+      {pose('Move X', -2, 2, 0.05, k.pos?.[0] || 0, (v) => setPos(0, v))}
+      {pose('Move Y', -2, 2, 0.05, k.pos?.[1] || 0, (v) => setPos(1, v))}
+      {pose('Move Z', -2, 2, 0.05, k.pos?.[2] || 0, (v) => setPos(2, v))}
+      {pose('Scale', 0.2, 2, 0.05, k.scale ?? 1, (v) => onPatch({ scale: v }))}
+      <LabeledControl label="Ease">
+        <Dropdown variant="subtle" size="sm" className="w-full" options={easeOptions} value={k.ease || 'inout'} onChange={(v) => onPatch({ ease: v })} />
+      </LabeledControl>
+    </div>
+  )
+}

package/src/organisms/SettingsSections.jsx

@@ -0,0 +1,63 @@
+import { LabeledControlSection, SettingsRow } from './SettingsPanel.jsx'
+
+/**
+ * SettingsSections — settings rows AS DATA, rendered once.
+ *
+ * The one component a consumer grabs for a settings body (user, 2026-09-03:
+ * *"lets normalise a component they can grab"*). The estate had the PIECES —
+ * `LabeledControlSection` for the eyebrow-headed section, `SettingsRow` for the
+ * 160px label column — and every surface looped over them itself: kol-fxr's
+ * `AppSettingsSections`, the settings page, the drawer, the shortcuts sheet.
+ * Four hand-written loops over one anatomy is how the sheet ended up with a
+ * plain `text-fg-32` heading and `fg-96` combos while the page two clicks away
+ * had eyebrows and `fg-32`.
+ *
+ * THE SECTIONS ARE A VALUE, so one declaration feeds every frame that shows
+ * them — the page, the drawer over what you are looking at, and a sheet:
+ *
+ *   const sections = [
+ *     { label: 'Canvas', rows: [
+ *       { label: 'Default aspect', render: () => <SettingsChoice … /> },
+ *       { label: 'Autoplay',       render: () => <SettingsSwitch … /> },
+ *     ] },
+ *   ]
+ *
+ *   <SettingsPanel open={open} onClose={close}><SettingsSections sections={sections} /></SettingsPanel>
+ *   <SettingsScaffold renderContent={() => <SettingsSections sections={visible} />} />
+ *
+ * A row is `{ label, render, align?, id? }` — `render` returns the control, so
+ * the CONTROL stays the consumer's and this owns only the anatomy. A row may
+ * also carry a plain `value` instead of `render` when the right cell is just
+ * text (a keyboard combo, a version string), which is what lets the shortcuts
+ * sheet and the settings page's shortcut block be the same call.
+ *
+ * `divided` puts the hairline above a section — pass it on EVERY section, the
+ * 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 {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`
+ * @param {string} [className] - Extra classes on the wrapper
+ */
+export default function SettingsSections({ sections = [], divided = false, labelWidth, align, className = '' }) {
+  return (
+    <div className={`kol-settings-sections flex flex-col gap-6 ${className}`.trim()}>
+      {sections.map((sec, i) => (
+        <LabeledControlSection key={sec.label ?? i} label={sec.label} divided={divided} rowGap={sec.rowGap}>
+          {sec.rows.map((row, j) => (
+            <SettingsRow
+              key={row.id ?? row.label ?? j}
+              label={row.label}
+              align={row.align ?? align}
+              labelWidth={row.labelWidth ?? labelWidth}
+            >
+              {row.render ? row.render() : row.value}
+            </SettingsRow>
+          ))}
+        </LabeledControlSection>
+      ))}
+    </div>
+  )
+}