@kolkrabbi/kol-component 0.2.0 → 0.4.0

package/src/atoms/ProsePreview.jsx

@@ -0,0 +1,53 @@
+/**
+ * ProsePreview — a full rich-text specimen: one `.kol-prose` block exercising
+ * every long-form element — H1–H4 ladder, section lede, body paragraph,
+ * blockquote, indented passage, code block, pullout, and unordered/ordered
+ * lists — so the KOL prose stylesheet can be reviewed end-to-end in one view.
+ * The "long-form" member of the type-specimen kit.
+ *
+ * Fixed structure; only the text slots vary. All element styling comes from
+ * the prose stylesheet (kol-typography.css) plus the kit's
+ * `.kol-prose-indented` / `.kol-prose-pullout` chrome — none lives here.
+ *
+ * @param {string} h1        trailing text of the H1 (rendered as `H1 — {h1}`)
+ * @param {string} paragraph body paragraph text
+ * @param {string} code      contents of the <pre><code> block
+ * @param {string} pullout   trailing text of the pullout (rendered as `Pullout — {pullout}`)
+ * @param {string} quote     blockquote text
+ */
+export default function ProsePreview({ h1, paragraph, code, pullout, quote = 'Above as below — justice is a starfield.' }) {
+  return (
+    <div className="kol-prose">
+      <h1>H1 — {h1}</h1>
+      <h2>H2 — Section title</h2>
+      <h3>H3 — Subsection</h3>
+      <h4>H4 — Block title</h4>
+      <p className="kol-sans-body-01 text-strong mb-6">
+        Section lede — a larger paragraph used to introduce a section and
+        establish tone before the body copy begins.
+      </p>
+      <p>{paragraph}</p>
+      <blockquote><p>{quote}</p></blockquote>
+      <div className="kol-prose-indented">
+        <p>
+          Indented passage. Used for tangential copy, contextual notes, or
+          nested argument that supports the main line.
+        </p>
+      </div>
+      <pre className="bg-fg-04 border border-fg-08"><code>{code}</code></pre>
+      <p className="kol-prose-pullout kol-helper-12 tracking-widest text-body">
+        Pullout — {pullout}
+      </p>
+      <ul>
+        <li>Unordered list — item one</li>
+        <li>Item two</li>
+        <li>Item three</li>
+      </ul>
+      <ol>
+        <li>Ordered list — item one</li>
+        <li>Item two</li>
+        <li>Item three</li>
+      </ol>
+    </div>
+  )
+}

package/src/atoms/QuantityInput.jsx

@@ -1,9 +1,31 @@
 import { useEffect, useState } from 'react'
 
+/**
+ * QuantityInput — a compact integer quantity picker with two control layouts.
+ *
+ *   controls="chevron" (default) — value with a stacked up/down chevron pair
+ *                                  on the right, inside a full-width field.
+ *   controls="split"             — a − value + pill (minus and plus flank the
+ *                                  value). The former `QuantityStepper`.
+ *
+ * Display-only value (not a text-editable input) — for an editable number
+ * field with bump chevrons use `Stepper`. Size auto-adapts to the viewport
+ * (sm < 768 ≤ md < 1024 ≤ lg) unless `size` pins it. Controlled: `value` +
+ * `(next) => onChange`, clamped to [min, max].
+ *
+ * @param {number}   value     current quantity (default 1)
+ * @param {Function} onChange  (next) => void
+ * @param {number}   min       lower bound (default 1)
+ * @param {number}   max       upper bound (default 99)
+ * @param {string}   controls  'chevron' (default) | 'split'
+ * @param {string}   size      'sm' | 'md' | 'lg' — pins the responsive size
+ * @param {string}   className extra classes on the root
+ */
+
 const SIZE_MAP = {
   sm: { fontSize: 11, paddingY: 12, paddingX: 24, radius: 20, icon: 10 },
   md: { fontSize: 12, paddingY: 14, paddingX: 24, radius: 22, icon: 12 },
-  lg: { fontSize: 14, paddingY: 16, paddingX: 24, radius: 24, icon: 14 }
+  lg: { fontSize: 14, paddingY: 16, paddingX: 24, radius: 24, icon: 14 },
 }
 
 const QuantityInput = ({
@@ -11,33 +33,21 @@ const QuantityInput = ({
   onChange,
   min = 1,
   max = 99,
+  controls = 'chevron',
   size,
-  className = ''
+  className = '',
 }) => {
   const [resolvedSize, setResolvedSize] = useState('md')
   const [componentWidth, setComponentWidth] = useState('180px')
 
   useEffect(() => {
     const determineSize = () => {
-      if (size) {
-        setResolvedSize(size)
-        return
-      }
-
-      if (typeof window === 'undefined') {
-        setResolvedSize('md')
-        return
-      }
-
-      if (window.innerWidth >= 1024) {
-        setResolvedSize('lg')
-      } else if (window.innerWidth >= 768) {
-        setResolvedSize('md')
-      } else {
-        setResolvedSize('sm')
-      }
+      if (size) { setResolvedSize(size); return }
+      if (typeof window === 'undefined') { setResolvedSize('md'); return }
+      if (window.innerWidth >= 1024) setResolvedSize('lg')
+      else if (window.innerWidth >= 768) setResolvedSize('md')
+      else setResolvedSize('sm')
     }
-
     determineSize()
     window.addEventListener('resize', determineSize)
     return () => window.removeEventListener('resize', determineSize)
@@ -46,14 +56,9 @@ const QuantityInput = ({
   useEffect(() => {
     const updateWidth = () => {
       if (typeof window === 'undefined') return
-
-      if (window.innerWidth >= 1024) {
-        setComponentWidth('180px')
-      } else if (window.innerWidth >= 768) {
-        setComponentWidth('140px')
-      } else {
-        setComponentWidth('100px')
-      }
+      if (window.innerWidth >= 1024) setComponentWidth('180px')
+      else if (window.innerWidth >= 768) setComponentWidth('140px')
+      else setComponentWidth('100px')
     }
     updateWidth()
     window.addEventListener('resize', updateWidth)
@@ -61,108 +66,65 @@ const QuantityInput = ({
   }, [])
 
   const metrics = SIZE_MAP[resolvedSize] || SIZE_MAP.md
+  const increment = () => { if (value < max) onChange?.(value + 1) }
+  const decrement = () => { if (value > min) onChange?.(value - 1) }
 
-  const increment = () => {
-    if (value < max) onChange?.(value + 1)
-  }
-
-  const decrement = () => {
-    if (value > min) onChange?.(value - 1)
+  /* controls="split" — the − value + pill (formerly QuantityStepper). */
+  if (controls === 'split') {
+    const btn = (disabled) => ({
+      padding: `${metrics.paddingY}px 12px`,
+      display: 'flex', alignItems: 'center', justifyContent: 'center',
+      backgroundColor: 'transparent', border: 'none',
+      color: 'var(--kol-surface-on-primary)',
+      cursor: disabled ? 'not-allowed' : 'pointer',
+      opacity: disabled ? 0.3 : 1,
+      transition: 'opacity 0.15s',
+      fontFamily: 'var(--kol-font-family-mono)',
+      fontSize: `${metrics.fontSize}px`, lineHeight: '120%',
+    })
+    return (
+      <div
+        className={`flex items-center justify-center ${className}`}
+        style={{
+          width: componentWidth, minWidth: componentWidth,
+          border: '1px solid var(--kol-border-default)',
+          borderRadius: `${metrics.radius}px`,
+          backgroundColor: 'var(--kol-surface-primary)',
+        }}
+      >
+        <button type="button" onClick={decrement} disabled={value <= min} style={btn(value <= min)} aria-label="Decrease quantity">−</button>
+        <span style={{ minWidth: '24px', textAlign: 'center', color: 'var(--kol-surface-on-primary)', fontFamily: 'var(--kol-font-family-mono)', fontSize: `${metrics.fontSize}px`, lineHeight: '120%' }}>{value}</span>
+        <button type="button" onClick={increment} disabled={value >= max} style={btn(value >= max)} aria-label="Increase quantity">+</button>
+      </div>
+    )
   }
 
+  /* controls="chevron" (default) — value + stacked chevron pair on the right. */
   return (
-    <div
-      className={`relative block ${className}`}
-    >
-      {/* Border wrapper - EXPLICIT 42.5px height */}
+    <div className={`relative block ${className}`}>
       <div
         className="w-full flex items-center"
         style={{
-          position: 'relative',
-          height: '42.5px',
+          position: 'relative', height: '42.5px',
           border: '1px solid var(--kol-border-default)',
           borderRadius: `${metrics.radius}px`,
           backgroundColor: 'var(--kol-surface-primary)',
           color: 'var(--kol-surface-on-primary)',
-          paddingLeft: `${metrics.paddingX}px`,
-          paddingRight: `${metrics.paddingX}px`,
-          fontSize: `${metrics.fontSize}px`,
-          lineHeight: '120%',
-          fontFamily: 'var(--kol-font-family-mono)',
-          boxSizing: 'border-box'
+          paddingLeft: `${metrics.paddingX}px`, paddingRight: `${metrics.paddingX}px`,
+          fontSize: `${metrics.fontSize}px`, lineHeight: '120%',
+          fontFamily: 'var(--kol-font-family-mono)', boxSizing: 'border-box',
         }}
       >
         <span>{value}</span>
-
-        {/* Chevrons - absolute, OUTSIDE the padded content */}
-        <div
-          style={{
-            position: 'absolute',
-            right: `${metrics.paddingX}px`,
-            top: '50%',
-            transform: 'translateY(-50%)',
-            display: 'flex',
-            flexDirection: 'column'
-          }}
-        >
-          <button
-            type="button"
-            onClick={increment}
-            disabled={value >= max}
-            style={{
-              backgroundColor: 'transparent',
-              border: 'none',
-              padding: '0',
-              cursor: value >= max ? 'not-allowed' : 'pointer',
-              opacity: value >= max ? 0.3 : 1,
-              lineHeight: 0,
-              display: 'block'
-            }}
-            aria-label="Increase quantity"
-          >
-            <svg
-              width={metrics.icon}
-              height={metrics.icon}
-              viewBox="0 0 12 12"
-              fill="none"
-            >
-              <path
-                d="m3 7 3-3 3 3"
-                stroke="currentColor"
-                strokeWidth="1.25"
-                strokeLinecap="round"
-                strokeLinejoin="round"
-              />
+        <div style={{ position: 'absolute', right: `${metrics.paddingX}px`, top: '50%', transform: 'translateY(-50%)', display: 'flex', flexDirection: 'column' }}>
+          <button type="button" onClick={increment} disabled={value >= max} style={{ backgroundColor: 'transparent', border: 'none', padding: '0', cursor: value >= max ? 'not-allowed' : 'pointer', opacity: value >= max ? 0.3 : 1, lineHeight: 0, display: 'block' }} aria-label="Increase quantity">
+            <svg width={metrics.icon} height={metrics.icon} viewBox="0 0 12 12" fill="none">
+              <path d="m3 7 3-3 3 3" stroke="currentColor" strokeWidth="1.25" strokeLinecap="round" strokeLinejoin="round" />
             </svg>
           </button>
-          <button
-            type="button"
-            onClick={decrement}
-            disabled={value <= min}
-            style={{
-              backgroundColor: 'transparent',
-              border: 'none',
-              padding: '0',
-              cursor: value <= min ? 'not-allowed' : 'pointer',
-              opacity: value <= min ? 0.3 : 1,
-              lineHeight: 0,
-              display: 'block'
-            }}
-            aria-label="Decrease quantity"
-          >
-            <svg
-              width={metrics.icon}
-              height={metrics.icon}
-              viewBox="0 0 12 12"
-              fill="none"
-            >
-              <path
-                d="m3 5 3 3 3-3"
-                stroke="currentColor"
-                strokeWidth="1.25"
-                strokeLinecap="round"
-                strokeLinejoin="round"
-              />
+          <button type="button" onClick={decrement} disabled={value <= min} style={{ backgroundColor: 'transparent', border: 'none', padding: '0', cursor: value <= min ? 'not-allowed' : 'pointer', opacity: value <= min ? 0.3 : 1, lineHeight: 0, display: 'block' }} aria-label="Decrease quantity">
+            <svg width={metrics.icon} height={metrics.icon} viewBox="0 0 12 12" fill="none">
+              <path d="m3 5 3 3 3-3" stroke="currentColor" strokeWidth="1.25" strokeLinecap="round" strokeLinejoin="round" />
             </svg>
           </button>
         </div>

package/src/atoms/RotaryDial.jsx

@@ -0,0 +1,150 @@
+import { useEffect, useRef, useState } from 'react'
+
+/** Clamp to min–max, snapped to the nearest step from min. */
+const snapTo = (v, min, max, step) => {
+  const stepped = min + Math.round((v - min) / step) * step
+  return Math.max(min, Math.min(max, stepped))
+}
+
+/**
+ * RotaryDial — drag-to-set rotary knob numeric input. Vertical pointer drag
+ * rotates the whole dial over a 270° sweep (−135° to +135°) mapped onto
+ * min–max; a full sweep is ~200px of drag, movement measured absolute from
+ * drag start. Controlled (`value`/`onChange`) with a local visual buffer so
+ * rotation stays smooth while parent updates are RAF-throttled; the final
+ * value fires on release. Focus + arrow keys step the value
+ * (role="slider" with aria-valuemin/max/now). The label and `%` readout
+ * rows render only when `label` is set; label text renders as authored.
+ *
+ * @param {string}   label    text under the dial; also gates the label + readout rows
+ * @param {number}   value    controlled value within min–max
+ * @param {Function} onChange (next: number) => void — RAF-throttled while dragging, final on release
+ * @param {number}   min      minimum value (default 0)
+ * @param {number}   max      maximum value (default 100)
+ * @param {number}   step     drag snap / arrow-key increment (default 1)
+ * @param {number}   size     dial px size (default 80); derives ring + disc radii
+ */
+export default function RotaryDial({
+  label,
+  value = 0,
+  onChange,
+  min = 0,
+  max = 100,
+  step = 1,
+  size = 80,
+}) {
+  const [isDragging, setIsDragging] = useState(false)
+  const [localValue, setLocalValue] = useState(value) // visual buffer — updates every move
+  const dragRef = useRef({ startY: 0, startValue: 0 })
+  const rafRef = useRef(null)
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+
+  // External updates land whenever a drag isn't in progress
+  useEffect(() => {
+    if (!isDragging) setLocalValue(value)
+  }, [value, isDragging])
+
+  useEffect(() => {
+    if (!isDragging) return
+    let current = dragRef.current.startValue
+    const handleMove = (e) => {
+      // absolute delta from drag start; full min→max sweep ≈ 200px
+      const deltaY = dragRef.current.startY - e.clientY
+      current = snapTo(dragRef.current.startValue + deltaY * ((max - min) / 200), min, max, step)
+      setLocalValue(current)
+      if (!rafRef.current) {
+        rafRef.current = requestAnimationFrame(() => {
+          onChangeRef.current?.(current)
+          rafRef.current = null
+        })
+      }
+    }
+    const handleUp = () => {
+      setIsDragging(false)
+      if (rafRef.current) {
+        cancelAnimationFrame(rafRef.current)
+        rafRef.current = null
+      }
+      onChangeRef.current?.(current)
+    }
+    window.addEventListener('pointermove', handleMove)
+    window.addEventListener('pointerup', handleUp)
+    window.addEventListener('pointercancel', handleUp)
+    return () => {
+      window.removeEventListener('pointermove', handleMove)
+      window.removeEventListener('pointerup', handleUp)
+      window.removeEventListener('pointercancel', handleUp)
+    }
+  }, [isDragging, min, max, step])
+
+  const handlePointerDown = (e) => {
+    setIsDragging(true)
+    dragRef.current = { startY: e.clientY, startValue: localValue }
+  }
+
+  const handleKeyDown = (e) => {
+    let next = null
+    if (e.key === 'ArrowUp' || e.key === 'ArrowRight') next = snapTo(localValue + step, min, max, step)
+    else if (e.key === 'ArrowDown' || e.key === 'ArrowLeft') next = snapTo(localValue - step, min, max, step)
+    if (next === null) return
+    e.preventDefault()
+    setLocalValue(next)
+    onChange?.(next)
+  }
+
+  const outerRadius = size / 2
+  const innerRadius = (size * 0.7) / 2
+  const strokeWidth = 2
+  const angle = -135 + ((localValue - min) / (max - min || 1)) * 270
+
+  return (
+    <div className="flex flex-col items-center gap-2">
+      <div
+        role="slider"
+        tabIndex={0}
+        aria-label={label}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-valuenow={localValue}
+        className="relative cursor-pointer select-none touch-none"
+        style={{
+          width: size,
+          height: size,
+          transform: `rotate(${angle}deg)`,
+          willChange: isDragging ? 'transform' : 'auto',
+        }}
+        onPointerDown={handlePointerDown}
+        onKeyDown={handleKeyDown}
+      >
+        <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} style={{ overflow: 'visible' }}>
+          {/* outer dashed tick ring */}
+          <circle
+            cx={outerRadius}
+            cy={outerRadius}
+            r={outerRadius - strokeWidth}
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={strokeWidth}
+            strokeDasharray="4 4"
+            className="text-fg-24"
+          />
+          {/* inner solid disc */}
+          <circle cx={outerRadius} cy={outerRadius} r={innerRadius} fill="currentColor" className="text-fg-96" />
+          {/* pointer notch — reads as a cut into the disc */}
+          <line
+            x1={outerRadius}
+            y1={outerRadius}
+            x2={outerRadius}
+            y2={outerRadius - innerRadius + 4}
+            stroke="var(--kol-surface-primary)"
+            strokeWidth={2}
+            strokeLinecap="round"
+          />
+        </svg>
+      </div>
+      {label && <div className="kol-helper-12 text-fg-64">{label}</div>}
+      {label && <div className="kol-helper-12 text-fg-96">{value}%</div>}
+    </div>
+  )
+}

package/src/atoms/SearchInput.jsx

@@ -0,0 +1,108 @@
+import { Icon } from '@kolkrabbi/kol-loader'
+
+/**
+ * SearchInput — controlled search field on the .kol-control shell. The
+ * search-flavored sibling of Input (same variant/size chrome + inner-input
+ * treatment), standalone because atoms can't nest atoms. Leading search
+ * icon, then two mutually exclusive trailing affordances: a caller-authored
+ * shortcut kbd chip while the value is empty, a clear × while it isn't.
+ *
+ * Always controlled (`value` defaults to ''). Controlled + no onChange =
+ * deliberate display-only → readOnly, same convention as Input. Extra props
+ * (onKeyDown, autoFocus, role, aria-*) spread onto the inner <input> —
+ * ShellSearchOverlay drives its combobox wiring through that seam.
+ *
+ * `type="search"` for semantics (searchbox role, mobile "search" enter key);
+ * the native WebKit cancel button is hidden so the × stays the only clear
+ * affordance.
+ *
+ * @param {string}   value        controlled value
+ * @param {Function} onChange     (event) => void — input change
+ * @param {string}   placeholder  placeholder text
+ * @param {Function} onClear      () => void — trailing × click; × renders only when set and value is non-empty
+ * @param {string}   shortcutHint caller-authored kbd chip (e.g. "⌘K"); shown while the value is empty
+ * @param {Function} onFocus      (event) => void — input focus
+ * @param {string}   size         'sm' | 'md' — kol-control size + matched mono type class
+ * @param {string}   variant      'filled' | 'ghost' | 'outline' — kol-control variant, same chrome as Input (ignored when bare)
+ * @param {boolean}  bare         borderless inline field for overlay panels (full width, no shell chrome; keeps icon/clear/chip slots)
+ * @param {string}   className    extra classes on the shell
+ */
+
+const SIZE_TYPE = { sm: 'kol-mono-12', md: 'kol-mono-14' }
+const ICON_SIZE = { sm: 14, md: 14 }
+
+export default function SearchInput({
+  value = '',
+  onChange,
+  placeholder = 'Search…',
+  onClear,
+  shortcutHint,
+  onFocus,
+  size = 'md',
+  variant = 'filled',
+  bare = false,
+  className = '',
+  ...inputProps
+}) {
+  const shellCls = [
+    bare
+      ? 'flex w-full gap-2.5 px-4 py-3'
+      : `kol-control kol-control--${variant} kol-control-${size} gap-2`,
+    'items-center cursor-text',
+    SIZE_TYPE[size],
+    className,
+  ].filter(Boolean).join(' ')
+
+  /* Same height pin as Input: Chromium sizes an <input> from font metrics,
+   * not CSS line-height, so without this the shell lands ~0.5px tall.
+   * h-4 / h-[18px] match the kol-mono-12 / -14 line-heights. */
+  const heightCls = size === 'sm' ? 'h-4' : 'h-[18px]'
+
+  const inputCls = [
+    'min-w-0 flex-1 bg-transparent border-none outline-none text-auto',
+    'appearance-none [&::-webkit-search-cancel-button]:hidden',
+    heightCls,
+  ].join(' ')
+
+  return (
+    <label className={shellCls}>
+      <span
+        aria-hidden="true"
+        className={`flex items-center shrink-0 ${bare ? 'text-fg-48' : 'text-auto opacity-50'}`}
+      >
+        <Icon name="search" size={ICON_SIZE[size] ?? 14} />
+      </span>
+      <input
+        type="search"
+        value={value ?? ''}
+        onChange={onChange}
+        readOnly={!onChange || undefined}
+        onFocus={onFocus}
+        placeholder={placeholder}
+        spellCheck={false}
+        className={inputCls}
+        {...inputProps}
+      />
+      {onClear && value ? (
+        <button
+          type="button"
+          aria-label="Clear"
+          /* preventDefault on mousedown keeps focus in the input across the clear */
+          onMouseDown={(e) => e.preventDefault()}
+          onClick={onClear}
+          className="inline-flex items-center justify-center shrink-0 cursor-pointer text-fg-48 hover:text-fg-96 transition-colors"
+        >
+          <Icon name="x" size={12} />
+        </button>
+      ) : shortcutHint ? (
+        /* aria-hidden — affordance, not a label (same stance as Input's prefix/suffix) */
+        <kbd
+          aria-hidden="true"
+          className="inline-flex items-center justify-center shrink-0 h-4 min-w-4 px-1 rounded-[3px] bg-fg-08 kol-helper-10 text-fg-48"
+        >
+          {shortcutHint}
+        </kbd>
+      ) : null}
+    </label>
+  )
+}