@kolkrabbi/kol-component 0.131.0 → 0.133.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.131.0",
+  "version": "0.133.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/atoms/RotaryDial.jsx

@@ -30,6 +30,7 @@ const snapTo = (v, min, max, step) => {
  * @param {number}   size        dial px size (default 80); derives ring + disc radii
  * @param {boolean}  disabled    blocks drag + keyboard and dims the control (default false)
  * @param {Function} formatValue optional readout formatter (value: number) => string; default `${value}%`
+ * @param {number}   defaultValue alt-click the dial resets to this (falls back to `min`) — Slider carries the same gesture
  */
 export default function RotaryDial({
   label,
@@ -41,6 +42,7 @@ export default function RotaryDial({
   size = 80,
   disabled = false,
   formatValue,
+  defaultValue,
 }) {
   const [isDragging, setIsDragging] = useState(false)
   const [localValue, setLocalValue] = useState(value) // visual buffer — updates every move
@@ -102,6 +104,21 @@ export default function RotaryDial({
     onChange?.(next)
   }
 
+  /* alt-click resets — the same gesture Slider carries (SliderDualThumbAndPlayhead,
+   * 2026-08-30). The two components share one value-control contract, and a
+   * reset that worked on the fader but not the knob would split it. Handled on
+   * pointer-down BEFORE the drag starts, so an alt-click never also nudges. */
+  const handlePointerDownOrReset = (e) => {
+    if (e.altKey) {
+      e.preventDefault()
+      const next = defaultValue ?? min
+      setLocalValue(next)
+      onChange?.(next)
+      return
+    }
+    handlePointerDown(e)
+  }
+
   const outerRadius = size / 2
   const innerRadius = (size * 0.7) / 2
   const strokeWidth = 2
@@ -124,7 +141,7 @@ export default function RotaryDial({
           transform: `rotate(${angle}deg)`,
           willChange: isDragging ? 'transform' : 'auto',
         }}
-        onPointerDown={disabled ? undefined : handlePointerDown}
+        onPointerDown={disabled ? undefined : handlePointerDownOrReset}
         onKeyDown={disabled ? undefined : handleKeyDown}
       >
         <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} style={{ overflow: 'visible' }}>

package/src/index.js

@@ -82,8 +82,6 @@ export { default as Dropdown } from './molecules/Dropdown.jsx'
 export { default as FieldRow, StatusChip } from './molecules/FieldRow.jsx'
 export { default as FramedMediaBand } from './organisms/FramedMediaBand.jsx'
 export { default as Image } from './atoms/Image.jsx'
-export { default as MediaCard } from './molecules/MediaCard.jsx'
-export { default as MediaRow } from './molecules/MediaRow.jsx'
 
 /* content-card system (2026-08-15) — the ruled card/row family:
  * docs/documentation/03-components/06-content-card-system.md */

package/src/molecules/Slider.jsx

@@ -1,22 +1,26 @@
-import { useEffect, useId, useMemo, useState } from 'react'
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
 import Input from '../atoms/Input.jsx'
 
 /**
- * Slider — range slider with label and an editable value readout. The LINEAR
- * VARIANT of RotaryDial (atoms/RotaryDial.jsx): both implement the shared
- * value-control contract — `value` / `min` / `max` / `step` /
- * `onChange(next: number)` / `label` / `size` / `disabled` / `formatValue`.
+ * Slider — range slider with label and a value readout. The LINEAR VARIANT of
+ * RotaryDial (atoms/RotaryDial.jsx): both implement the shared value-control
+ * contract — `value` / `min` / `max` / `step` / `onChange(next: number)` /
+ * `label` / `size` / `disabled` / `formatValue` / `defaultValue`.
  * Controlled; onChange always fires with the plain number.
  *
- * One bare inline row: label · track · editable readout. (Bordered
- * `default` and chip `subtle` variants retired 2026-07-08 — minimal is
- * the only slider.)
+ * One bare inline row: label · track · readout. (Bordered `default` and chip
+ * `subtle` variants retired 2026-07-08 — minimal is the only single slider.)
  *
- * The value readout is an editable <Input> (type a value, commit on
- * blur / Enter, revert on Escape) — a Slider-only extra; RotaryDial's
- * readout is display-only (atoms nest no KOL component). Track color is
- * exposed as the `--kol-slider-track` CSS variable on `.slider-black`;
- * override per-instance via style={{ '--kol-slider-track': '...' }}.
+ * Track color is exposed as the `--kol-slider-track` CSS variable on
+ * `.slider-black`; override per-instance via
+ * style={{ '--kol-slider-track': '...' }}.
+ *
+ * DUAL + PLAYHEAD (SliderDualThumbAndPlayhead, kol-mirror 2026-08-30):
+ * `variant="dual"` stacks two native ranges on one rail for an in/out pair,
+ * with an optional draggable playhead. Built because mirror was maintaining a
+ * verbatim copy of this component's CSS at 10 call sites to get it — 8 of which
+ * needed nothing else. The clamp lives HERE, not in the consumer: an in-thumb
+ * that can cross its out-thumb is a bug every caller would re-fix.
  *
  * @param {Object} props
  * @param {string} props.label - Slider label text
@@ -31,6 +35,15 @@ import Input from '../atoms/Input.jsx'
  * @param {string} props.className - Additional wrapper classes
  * @param {number} props.displayWidth - Width of the value readout, in characters (default: 6)
  * @param {string} props.fontSize - Font size for label/value (e.g., '11px')
+ * @param {number} props.defaultValue - alt-click the control resets to this (falls back to `min`). Same contract on RotaryDial
+ * @param {'input'|'value'|'none'} props.readout - `input` (default) an editable Input · `value` a plain right-aligned span, RotaryDial's own display-only readout · `none`
+ * @param {'minimal'|'dual'} props.variant - `dual` = two thumbs on one rail
+ * @param {number} props.value2 - dual only — the out value
+ * @param {Function} props.onChange2 - dual only — (next: number) => void for the out thumb
+ * @param {string} props.label1 - dual only — replaces the formatted in value above the rail
+ * @param {string} props.label2 - dual only — replaces the formatted out value
+ * @param {number|null} props.playhead - dual only — marker position in min…max; null renders nothing and attaches no listeners
+ * @param {Function} props.onPlayheadChange - dual only — (next: number) => void; omit and the marker is not draggable and the rail does not seek
  */
 const Slider = ({
   label,
@@ -45,6 +58,15 @@ const Slider = ({
   className = '',
   displayWidth = 6,
   fontSize,
+  defaultValue,
+  readout = 'input',
+  variant = 'minimal',
+  value2,
+  onChange2,
+  label1,
+  label2,
+  playhead = null,
+  onPlayheadChange,
 }) => {
   /* Label ↔ input pairing — the <label> is a sibling of the range input, so
    * without an htmlFor/id pair the visible label confers no accessible name. */
@@ -64,13 +86,16 @@ const Slider = ({
     return decimalPart ? decimalPart.length : 2
   }, [formatValue, step])
 
-  const displayValue = useMemo(() => {
-    if (formatValue) return String(formatValue(value))
-    if (decimals && decimals > 0) {
-      return Number(value).toFixed(decimals)
-    }
-    return String(Math.round(value))
-  }, [decimals, formatValue, value])
+  const fmt = useCallback(
+    (v) => {
+      if (formatValue) return String(formatValue(v))
+      if (decimals && decimals > 0) return Number(v).toFixed(decimals)
+      return String(Math.round(v))
+    },
+    [decimals, formatValue],
+  )
+
+  const displayValue = useMemo(() => fmt(value), [fmt, value])
 
   /* Editable readout — local string state lets the user type intermediate
    * values (e.g. "-" while entering a negative) without clamping mid-keystroke.
@@ -79,6 +104,39 @@ const Slider = ({
   const [editing, setEditing] = useState(false)
   useEffect(() => { if (!editing) setDraft(displayValue) }, [displayValue, editing])
 
+  /* EVERY hook runs before the dual branch returns. The prior art in kol-mirror
+   * called useMemo *after* its early return, so hook order changed with the
+   * variant — it survived only because no call site switched variant at
+   * runtime. Not carried. */
+  const trackRef = useRef(null)
+
+  const seekTo = useCallback(
+    (clientX) => {
+      const el = trackRef.current
+      if (!onPlayheadChange || !el) return
+      const rect = el.getBoundingClientRect()
+      const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width))
+      onPlayheadChange(min + ratio * (max - min))
+    },
+    [min, max, onPlayheadChange],
+  )
+
+  const handlePlayheadDrag = useCallback(
+    (e) => {
+      if (!onPlayheadChange) return
+      e.preventDefault()
+      seekTo(e.clientX)
+      const onMove = (me) => seekTo(me.clientX)
+      const onUp = () => {
+        window.removeEventListener('pointermove', onMove)
+        window.removeEventListener('pointerup', onUp)
+      }
+      window.addEventListener('pointermove', onMove)
+      window.addEventListener('pointerup', onUp)
+    },
+    [onPlayheadChange, seekTo],
+  )
+
   const commit = () => {
     setEditing(false)
     const parsed = Number(draft)
@@ -96,8 +154,84 @@ const Slider = ({
     if (e.key === 'Escape') { setDraft(displayValue); setEditing(false); e.currentTarget.blur() }
   }
 
+  /* alt-click anywhere on the control resets — RotaryDial carries the same
+   * gesture, so a reset that worked on the knob and not the fader would be the
+   * shared value-control contract splitting again. */
+  const onAltReset = (e) => {
+    if (!e.altKey || !onChange || disabled) return
+    e.preventDefault()
+    onChange(defaultValue ?? min)
+  }
+
+  if (variant === 'dual') {
+    const v1 = value ?? min
+    const v2 = value2 ?? max
+    const showLabels = label1 != null || label2 != null
+    const ratio = max > min ? (playhead - min) / (max - min) : 0
+    return (
+      <div className={`control-slider gap-3 shadow-none ${className}`}>
+        {label && (
+          <label
+            className={`kol-helper-12 whitespace-nowrap shrink-0 w-fit ${disabled ? 'opacity-50' : ''}`}
+            style={fontSize ? { fontSize } : undefined}
+          >
+            {label}
+          </label>
+        )}
+        <div className="flex-1">
+          {showLabels && (
+            <div
+              className="kol-helper-12 text-fg-32 flex items-center justify-between"
+              style={{ marginBottom: '-2px' }}
+            >
+              <span>{label1 ?? fmt(v1)}</span>
+              <span>{label2 ?? fmt(v2)}</span>
+            </div>
+          )}
+          <div
+            ref={trackRef}
+            className="kol-slider-dual"
+            style={onPlayheadChange ? { cursor: 'pointer' } : undefined}
+            /* the whole rail seeks, not just the marker — hunting a 3px target
+             * to scrub is the thing that makes a playhead feel broken */
+            onPointerDown={(e) => { if (e.target === e.currentTarget) seekTo(e.clientX) }}
+          >
+            <div className="kol-slider-dual-rail" />
+            {playhead != null && max > min && (
+              <div
+                className="kol-slider-dual-playhead"
+                /* half a thumb in from each end, so the marker lines up with
+                 * where a thumb CENTRE can actually reach */
+                style={{ left: `calc(6px + (100% - 12px) * ${ratio})` }}
+                onPointerDown={handlePlayheadDrag}
+              />
+            )}
+            <input
+              type="range"
+              min={min} max={max} step={step} value={v1}
+              disabled={disabled}
+              aria-label={label1 ?? 'In'}
+              onChange={(e) => onChange?.(Math.min(Number(e.target.value), v2))}
+              className="kol-slider-range kol-slider-range--in"
+              style={{ zIndex: 1 }}
+            />
+            <input
+              type="range"
+              min={min} max={max} step={step} value={v2}
+              disabled={disabled}
+              aria-label={label2 ?? 'Out'}
+              onChange={(e) => onChange2?.(Math.max(Number(e.target.value), v1))}
+              className="kol-slider-range kol-slider-range--out"
+              style={{ zIndex: 2 }}
+            />
+          </div>
+        </div>
+      </div>
+    )
+  }
+
   return (
-    <div className={`control-slider gap-3 shadow-none ${className}`}>
+    <div className={`control-slider gap-3 shadow-none ${className}`} onClick={onAltReset}>
       {label && (
         <label
           htmlFor={sliderId}
@@ -119,20 +253,33 @@ const Slider = ({
         className={`slider-black cursor-pointer disabled:cursor-default disabled:opacity-50 ${size ? 'flex-none' : 'flex-1 w-full'}`}
         style={size ? { width: size } : undefined}
       />
-      <Input
-        type="text"
-        inputMode="decimal"
-        variant="filled"
-        size="sm"
-        chars={displayWidth}
-        value={draft}
-        disabled={disabled}
-        onFocus={(e) => { setEditing(true); e.target.select() }}
-        onChange={(e) => setDraft(e.target.value)}
-        onBlur={commit}
-        onKeyDown={onKeyDown}
-        inputClassName="text-center"
-      />
+      {readout === 'input' && (
+        <Input
+          type="text"
+          inputMode="decimal"
+          variant="filled"
+          size="sm"
+          chars={displayWidth}
+          value={draft}
+          disabled={disabled}
+          onFocus={(e) => { setEditing(true); e.target.select() }}
+          onChange={(e) => setDraft(e.target.value)}
+          onBlur={commit}
+          onKeyDown={onKeyDown}
+          inputClassName="text-center"
+        />
+      )}
+      {/* `value` is RotaryDial's readout, not a second design — a mixer running
+       * ~23 faders in a 24px row cannot afford an input chip on every one, and
+       * that is why the easy call sites could not move. */}
+      {readout === 'value' && (
+        <span
+          className={`kol-helper-12 shrink-0 w-fit text-right ${disabled ? 'opacity-50' : ''}`}
+          style={fontSize ? { fontSize } : undefined}
+        >
+          {displayValue}
+        </span>
+      )}
     </div>
   )
 }

package/src/molecules/MediaCard.jsx

@@ -1,103 +0,0 @@
-import { Icon } from '@kolkrabbi/kol-icons'
-
-/* taxonomy-ok: nests kol-icons's Icon (a package import the relative-import
- * check can't see) plus the same-file SelectIndicator. */
-
-/**
- * @deprecated 2026-08-26 — absorbed by `ContentCard variant="default"` in @kolkrabbi/kol-component
- * (the Content Set, 2026-08-15). Step 1 of the retirement wave: this export
- * stays and renders unchanged until the next major, then it is removed.
- * Consumers: swap on your next bump. Map + row-by-row diff:
- * docs/documentation/03-components/06-content-card-system.md.
- *
- * SelectIndicator — passive square check indicator for multi-select rows and
- * cards. `on` = checked. Deliberately NOT ToggleCheckbox: that is a labeled
- * form control with a real <input>, which double-fires inside a click-target
- * card and misleads assistive tech — here the CARD is the toggle, this is
- * only its visual state. Inline CSS vars because `bg-fg-default` isn't a
- * generated Tailwind utility; the checked fill reads from
- * `--kol-surface-on-primary` (solid fg, theme-correct).
- *
- * Shared by MediaCard and MediaRow; not exported from the package barrel.
- */
-export function SelectIndicator({ on = false }) {
-  return (
-    <span
-      className="w-4 h-4 shrink-0 rounded-sm border flex items-center justify-center transition-colors"
-      style={
-        on
-          ? { background: 'var(--kol-surface-on-primary)', borderColor: 'var(--kol-surface-on-primary)' }
-          : { background: 'var(--kol-fg-ab-16, rgba(0,0,0,0.15))', borderColor: 'var(--kol-fg-ab-48, rgba(0,0,0,0.4))' }
-      }
-      aria-hidden="true"
-    >
-      {on && <Icon name="check" size={11} style={{ color: 'var(--kol-surface-primary)' }} />}
-    </span>
-  )
-}
-
-/**
- * MediaCard — grid tile for one media object: square thumbnail with a
- * top-right download overlay (or a top-left select checkbox in select mode),
- * then name / meta / actions stacked below. The grid-view counterpart to
- * MediaRow (same slot contract).
- *
- * Presentational — the parent supplies rendered slots; no media loading,
- * fetch, or rename logic lives here. Grid track sizing belongs to the parent
- * list; the card just fills its cell.
- *
- * @param {ReactNode} thumb        square thumbnail (image/video/placeholder)
- * @param {ReactNode} name         name cell (plain text or an inline editor)
- * @param {string}    meta         one-line secondary text (e.g. "1.2 MB · 2026-06-19")
- * @param {ReactNode} actions      row of action buttons (hidden in select mode)
- * @param {string}    downloadHref href for the overlay download button (omit to hide)
- * @param {boolean}   selectMode   selection mode on → checkbox replaces download, whole card toggles
- * @param {boolean}   selected     this card is selected (stronger border + checked box)
- * @param {Function}  onSelect     (event) => void — card click in select mode; gets shiftKey for range
- */
-export default function MediaCard({
-  thumb,
-  name,
-  meta,
-  actions,
-  downloadHref,
-  selectMode = false,
-  selected = false,
-  onSelect,
-}) {
-  return (
-    <li
-      onClick={selectMode ? onSelect : undefined}
-      className={`flex flex-col rounded overflow-hidden border bg-fg-02 ${selectMode ? 'cursor-pointer select-none' : ''}`}
-      style={{ borderColor: selected ? 'var(--kol-fg-64)' : 'var(--kol-fg-12)' }}
-    >
-      <div className="aspect-square relative">
-        {thumb}
-        {selectMode ? (
-          <span
-            className="kol-frame-control kol-frame-control--top-left rounded p-1"
-            style={{ background: 'var(--kol-fg-ab-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
-          >
-            <SelectIndicator on={selected} />
-          </span>
-        ) : downloadHref ? (
-          <a
-            href={downloadHref}
-            aria-label="Download"
-            title="Download"
-            className="kol-frame-control inline-flex items-center justify-center w-8 h-8 rounded text-emphasis hover:bg-fg-ab-24 transition-colors"
-            style={{ background: 'var(--kol-fg-ab-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
-            onClick={(e) => e.stopPropagation()}
-          >
-            <Icon name="download" size={16} />
-          </a>
-        ) : null}
-      </div>
-      <div className="p-3 flex flex-col gap-2">
-        {name}
-        <p className="kol-mono-12 text-fg-48">{meta}</p>
-        {!selectMode && actions}
-      </div>
-    </li>
-  )
-}

package/src/molecules/MediaRow.jsx

@@ -1,55 +0,0 @@
-import { SelectIndicator } from './MediaCard.jsx'
-
-/**
- * @deprecated 2026-08-26 — absorbed by `ContentRow variant="default"` in @kolkrabbi/kol-component
- * (the Content Set, 2026-08-15). Step 1 of the retirement wave: this export
- * stays and renders unchanged until the next major, then it is removed.
- * Consumers: swap on your next bump. Map + row-by-row diff:
- * docs/documentation/03-components/06-content-card-system.md.
- *
- * MediaRow — list row for one media object: optional select checkbox, small
- * thumbnail, name (flex), fixed-width date + size columns, then actions.
- * The list-view counterpart to MediaCard (same slot contract).
- *
- * Presentational — the parent supplies rendered slots; interaction outside
- * select mode lives in the thumb / name / actions slots. Column widths are
- * consumer-tunable via `dateWidth` / `sizeWidth`.
- *
- * @param {ReactNode} thumb       small thumbnail (48px square)
- * @param {ReactNode} name        name cell (plain text or an inline editor)
- * @param {string}    date        right-aligned date column
- * @param {string}    size        right-aligned size column
- * @param {ReactNode} actions     row of action buttons (hidden in select mode)
- * @param {string}    dateWidth   Tailwind width class for the date column
- * @param {string}    sizeWidth   Tailwind width class for the size column
- * @param {boolean}   selectMode  selection mode on → checkbox shown, whole row toggles, actions hidden
- * @param {boolean}   selected    this row is selected (highlight + checked box)
- * @param {Function}  onSelect    (event) => void — row click in select mode; gets shiftKey for range
- */
-export default function MediaRow({
-  thumb,
-  name,
-  date,
-  size,
-  actions,
-  dateWidth = 'w-24',
-  sizeWidth = 'w-20',
-  selectMode = false,
-  selected = false,
-  onSelect,
-}) {
-  return (
-    <li
-      onClick={selectMode ? onSelect : undefined}
-      className={`flex items-center gap-3 py-2 border-b ${selectMode ? 'cursor-pointer select-none' : ''} ${selected ? 'bg-fg-08' : ''}`}
-      style={{ borderColor: 'var(--kol-fg-08)' }}
-    >
-      {selectMode && <SelectIndicator on={selected} />}
-      <div className="w-12 h-12 shrink-0 rounded overflow-hidden">{thumb}</div>
-      <div className="flex-1 min-w-0">{name}</div>
-      <p className={`kol-mono-12 text-fg-32 shrink-0 text-right ${dateWidth}`}>{date}</p>
-      <p className={`kol-mono-12 text-fg-48 shrink-0 text-right ${sizeWidth}`}>{size}</p>
-      {!selectMode && <div className="shrink-0">{actions}</div>}
-    </li>
-  )
-}