@kolkrabbi/kol-component 0.34.0 → 0.36.0

package/README.md

@@ -30,3 +30,15 @@ import { Icon } from '@kolkrabbi/kol-icons'
 ```
 
 Atoms (Button, Input, Slider, Toggle\*, …), molecules (Dropdown, Tag, Badge, Modal, Popover, …), primitives (Accordion, Carousel, CodeBlock, Image, …), an organism (Table), graphics, and hooks (`useReveal`, `useScrollSpy`). See the [usage reference](https://github.com/Tor-Grimsson/kol-ds/tree/main/docs/usage) for real examples of each.
+
+### Deep imports — skip the barrel, skip the peers
+
+The barrel (`import { Button } from '@kolkrabbi/kol-component'`) statically imports the whole tree, so building against it requires every organism peer (`framer-motion`, `gsap`, `hls.js`) even if you render none of them — module resolution happens before tree-shaking. Consumers that want a slice import the file directly and only its own chain resolves:
+
+```jsx
+import Button from '@kolkrabbi/kol-component/atoms/Button'
+import Modal from '@kolkrabbi/kol-component/molecules/Modal'
+import useReveal from '@kolkrabbi/kol-component/hooks/useReveal'
+```
+
+Subpaths: `./atoms/*`, `./molecules/*`, `./organisms/*`, `./utilities/*` (`.jsx`) and `./hooks/*` (`.js`). Most files default-export their component; multi-part families (`Modal`, `MenuItem`, `Accordion`) export named — mirror whatever the barrel re-exports. The barrel stays for showcase-style consumers that want everything.

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./atoms/*": "./src/atoms/*.jsx",
+    "./molecules/*": "./src/molecules/*.jsx",
+    "./organisms/*": "./src/organisms/*.jsx",
+    "./utilities/*": "./src/utilities/*.jsx",
+    "./hooks/*": "./src/hooks/*.js"
   },
   "files": [
     "src",

package/src/atoms/ColorSwatch.jsx

@@ -11,10 +11,15 @@
  *   hex             — color string, e.g. '#FF6F00'. Ignored if showTransparent.
  *   selected        — adds active border + ring (border-fg-64 ring-1).
  *   size            — number (px) for fixed-size, 'fill' (w-full aspect-square,
- *                     for grid cells that should stay square), or 'stretch'
- *                     (w-full h-full, for grid cells that stretch to row height).
- *                     Default 24.
+ *                     for grid cells that should stay square), 'stretch'
+ *                     (w-full h-full, for grid cells that stretch to row height),
+ *                     or 'control-sm' (26px — the kol-control-sm row height, so
+ *                     a swatch sits flush beside sm input chrome in a paint bar;
+ *                     ColorSwatchFieldSizing 2026-08-12). Default 24.
  *   radius          — 'sm' (4px, default) | 'tight' (2px) | 'none' | 'full' (circle).
+ *                     Default was 'tight' until 2026-08-12 — flipped to 'sm' per
+ *                     the system radius law (containers are 4px everywhere);
+ *                     square-corner contexts opt out via 'tight'/'none'.
  *   frame           — boolean (default true). When false, no border drawn —
  *                     used by tightly-packed grid layouts.
  *   variant         — 'default' (border-based chrome) |
@@ -41,6 +46,12 @@ const SIZE_CLASSES = {
   stretch: 'w-full h-full',
 }
 
+/* Named px sizes that track the control ladder — inline style, not a
+ * utility class (package chrome never rides arbitrary utilities). */
+const NAMED_PX = {
+  'control-sm': 26, // kol-control-sm outer height — paint-bar swatch flush with sm input chrome
+}
+
 const RADIUS_CLASSES = {
   none:  'rounded-none',
   tight: 'rounded-[var(--kol-radius-xs)]',
@@ -54,7 +65,7 @@ export default function ColorSwatch({
   hex,
   selected = false,
   size = 24,
-  radius = 'tight',
+  radius = 'sm',
   frame = true,
   variant = 'default',
   hoverable = true,
@@ -66,9 +77,10 @@ export default function ColorSwatch({
   ...rest
 }) {
   const interactive = typeof onClick === 'function'
-  const isNamed = typeof size === 'string'
-  const sizeCls   = isNamed ? (SIZE_CLASSES[size] ?? '') : ''
-  const sizeStyle = isNamed ? null : { width: size, height: size }
+  const resolvedSize = NAMED_PX[size] ?? size
+  const isNamed = typeof resolvedSize === 'string'
+  const sizeCls   = isNamed ? (SIZE_CLASSES[resolvedSize] ?? '') : ''
+  const sizeStyle = isNamed ? null : { width: resolvedSize, height: resolvedSize }
 
   const isHalo  = variant === 'halo'
   const radiusCls = RADIUS_CLASSES[radius] ?? RADIUS_CLASSES.sm

package/src/atoms/Input.jsx

@@ -9,6 +9,14 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *                                treatment (2026-07-08 chrome law: one
  *                                secondary, always subordinate to filled)
  *   variant="ghost"            — legacy alias, resolves to outline
+ *   variant="property"         — the Figma property field (PropertyField,
+ *                                2026-08-12): filled chrome, dim `affordance`
+ *                                (letter or icon node) at a 6px gap, the value
+ *                                HUGS its own length (mono ch-width — number-
+ *                                safe, no `size` attr), and `unit` renders
+ *                                IMMEDIATELY after the value (`0°`, `100%`).
+ *                                Shell fills its cell, content left-packed.
+ *                                Width tracks `value` — controlled usage only.
  *
  *   size="sm" / "md" (default) / "lg" — matched padding + type class
  *
@@ -26,6 +34,10 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *     the shell at text-meta. aria-hidden — affordances, not labels.
  *   iconLeft — name of a leading icon rendered inside the shell (e.g.
  *     "search-16"). iconSize overrides the size-derived default.
+ *   slotLeft — arbitrary leading node rendered inside the shell, before
+ *     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.
  *
  * Chrome (bg/border/padding/transition/disabled) comes from .kol-control;
  * Input owns prefix/suffix/icon layout + the inner <input> styling.
@@ -42,6 +54,9 @@ export default function Input({
   chars,
   prefix,
   suffix,
+  slotLeft,
+  affordance,
+  unit,
   iconLeft,
   iconSize = null,
   placeholder,
@@ -61,7 +76,9 @@ export default function Input({
   const resolvedIconSize = iconSize ?? glyphSize(size)
 
   // ghost folds into outline (2026-07-08 chrome law): one secondary treatment.
-  const resolvedVariant = variant === 'ghost' ? 'outline' : variant
+  // property rides the filled chrome — it is a behaviour variant, not new paint.
+  const isProperty = variant === 'property'
+  const resolvedVariant = variant === 'ghost' ? 'outline' : isProperty ? 'filled' : variant
 
   const shellCls = [
     'kol-control',
@@ -69,9 +86,16 @@ export default function Input({
     `kol-control-${size}`,
     SIZE_TYPE[size],
     'cursor-text',
+    isProperty && 'w-full',
     className,
   ].filter(Boolean).join(' ')
 
+  /* Property width: the shell type is mono, so every glyph is exactly 1ch —
+   * `${len}ch` hugs the value with no probe element, and stays number-safe
+   * where the HTML `size` attr is ignored (<input type="number">). +2px keeps
+   * the caret from clipping at the end. Tracks `value` → controlled only. */
+  const propertyLen = Math.max(String(value ?? placeholder ?? '').length, 1)
+
   /* Pin inner input height to the typography token's line-height. Without
    * this the `<input>` renders ~0.5px taller than the equivalent <button>
    * or <label> at the same kol-mono-N — Chromium computes input height
@@ -83,7 +107,7 @@ export default function Input({
   const inputCls = [
     'min-w-0 bg-transparent border-none outline-none text-auto',
     heightCls,
-    !fixedChars && 'flex-1',
+    !fixedChars && !isProperty && 'flex-1',
     /* Balance the dim prefix/suffix visual weight with extra inner padding
      * on the opposite side. Without this the bright value sits closer to
      * the affordance than to the empty edge, reads off-balance. */
@@ -99,6 +123,9 @@ export default function Input({
       style={width ? { width: typeof width === 'number' ? `${width}px` : width } : undefined}
       aria-disabled={disabled || undefined}
     >
+      {slotLeft && (
+        <span className="flex items-center shrink-0 pr-2">{slotLeft}</span>
+      )}
       {iconLeft && (
         <span aria-hidden="true" className="flex items-center text-auto opacity-50 shrink-0 pr-2">
           <Icon name={iconLeft} size={resolvedIconSize} />
@@ -107,6 +134,9 @@ export default function Input({
       {prefix !== undefined && (
         <span aria-hidden="true" className="text-meta pr-1 shrink-0">{prefix}</span>
       )}
+      {affordance !== undefined && (
+        <span aria-hidden="true" className="text-meta pr-1.5 shrink-0 inline-flex items-center">{affordance}</span>
+      )}
       {/* Controlled only when a `value` prop is passed — otherwise stay
         * uncontrolled so prop-less usages (search stubs, quick demos) type
         * normally instead of freezing on a value-without-onChange input.
@@ -121,8 +151,12 @@ export default function Input({
         spellCheck={false}
         size={fixedChars ? chars : undefined}
         className={inputCls}
+        style={isProperty ? { width: `calc(${propertyLen}ch + 2px)` } : undefined}
         {...inputProps}
       />
+      {unit !== undefined && (
+        <span aria-hidden="true" className="text-meta shrink-0">{unit}</span>
+      )}
       {suffix !== undefined && (
         <span aria-hidden="true" className="text-meta pl-1 shrink-0">{suffix}</span>
       )}

package/src/atoms/SegmentedToggle.jsx

@@ -23,9 +23,17 @@
  * the group on the active cell, ←/→ (or ↑/↓) move selection + focus.
  *
  * Props:
- *   value     — current option value
+ *   value     — current option value. `null`/`undefined` = STATELESS mode
+ *               (the segmented state law, 2026-08-12): role `group`, no
+ *               aria-checked, no selected styling — a pure one-shot ACTION
+ *               strip (canvas alignment, transform cluster); onChange is the
+ *               action dispatch.
  *   onChange  — handler (newValue) => void
  *   options   — [{ value, label, ariaLabel? }]
+ *   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
+ *               outline shell; the inset ring marks ONLY the selected cell).
  *   size      — mirrors Button exactly: 'sm' (26px, mono-12, 4/12 pad) |
  *               'md' (default, 32px, mono-14, 6/16 pad) | 'lg' (40px,
  *               mono-16, 8/20 pad). Same cell padding + mono type as the
@@ -34,11 +42,13 @@
  *   ariaLabel — accessible name for the group
  *   className — additional classes on the outer shell
  */
-export default function SegmentedToggle({ value, onChange, options = [], size = 'md', ariaLabel, className = '' }) {
+export default function SegmentedToggle({ value, onChange, options = [], variant = 'default', size = 'md', ariaLabel, className = '' }) {
   const cellType = { sm: 'kol-mono-12', md: 'kol-mono-14', lg: 'kol-mono-16' }[size]
+  const stateless = value == null
   const focusIdx = Math.max(0, options.findIndex((opt) => opt.value === value))
 
   const handleKeyDown = (e) => {
+    if (stateless) return // plain button row — Tab moves focus, arrows do nothing
     const dir = { ArrowLeft: -1, ArrowUp: -1, ArrowRight: 1, ArrowDown: 1 }[e.key]
     if (!dir || !options.length) return
     e.preventDefault()
@@ -49,21 +59,21 @@ export default function SegmentedToggle({ value, onChange, options = [], size =
 
   return (
     <div
-      role="radiogroup"
+      role={stateless ? 'group' : 'radiogroup'}
       aria-label={ariaLabel}
       onKeyDown={handleKeyDown}
-      className={['kol-seg', size !== 'md' && `kol-seg--${size}`, className].filter(Boolean).join(' ')}
+      className={['kol-seg', variant === 'filled' && 'kol-seg--filled', size !== 'md' && `kol-seg--${size}`, className].filter(Boolean).join(' ')}
     >
       {options.map((opt, i) => {
-        const isActive = opt.value === value
+        const isActive = !stateless && opt.value === value
         return (
           <button
             key={opt.value}
             type="button"
-            role="radio"
-            aria-checked={isActive}
+            role={stateless ? undefined : 'radio'}
+            aria-checked={stateless ? undefined : isActive}
             aria-label={opt.ariaLabel}
-            tabIndex={i === focusIdx ? 0 : -1}
+            tabIndex={stateless ? 0 : (i === focusIdx ? 0 : -1)}
             onClick={() => onChange?.(opt.value)}
             className={['kol-seg-cell', cellType, isActive && 'is-active'].filter(Boolean).join(' ')}
           >

package/src/atoms/Textarea.jsx

@@ -15,7 +15,14 @@ import { Icon } from '@kolkrabbi/kol-icons'
  * dominating the panel). Resize is real (2026-07-08): native resize is
  * OFF (Firefox's built-in grip cannot be hidden any other way) and the
  * kol-icon-set-v1 `resize-grip` icon IS the drag handle — corner drag,
- * both axes, min 120×40. One grip, every browser.
+ * min 120×40. One grip, every browser.
+ *
+ * The X-drag is container-clamped (2026-08-12, TextareaResizeClamp): the
+ * width write caps at the parent's content width, so a drag can never
+ * overflow the box the Textarea sits in. `axis` narrows the drag:
+ *   axis="both" (default) — corner drag, clamped
+ *   axis="y"              — height only; rail-mounted textareas have
+ *                           nowhere meaningful to grow on X
  *
  * Controlled OR uncontrolled:
  *   - pass `value` + `onChange` for controlled,
@@ -32,6 +39,7 @@ export default function Textarea({
   variant = 'filled',
   size = 'md',
   rows = 3,
+  axis = 'both',
   placeholder,
   disabled = false,
   className = '',
@@ -72,8 +80,11 @@ export default function Textarea({
         aria-hidden="true"
         className="kol-textarea-resize-icon"
         onPointerDown={(e) => {
-          // The grip IS the resize handle — corner drag, both axes
-          // (min 120×40). Width lands on the shell, height on the textarea.
+          // The grip IS the resize handle — corner drag (min 120×40).
+          // Width lands on the shell, height on the textarea. The width
+          // write is clamped to the parent's content width so an X-drag
+          // can never overflow the container; the 120 floor wins if the
+          // container is narrower than that.
           const shell = e.currentTarget.parentElement
           const ta = shell?.querySelector('textarea')
           if (!shell || !ta) return
@@ -82,8 +93,17 @@ export default function Textarea({
           const startY = e.clientY
           const startW = shell.offsetWidth
           const startH = ta.offsetHeight
+          const parent = shell.parentElement
+          let maxW = Infinity
+          if (parent) {
+            const pcs = getComputedStyle(parent)
+            maxW = parent.clientWidth
+              - parseFloat(pcs.paddingLeft) - parseFloat(pcs.paddingRight)
+          }
           const move = (ev) => {
-            shell.style.width = `${Math.max(startW + ev.clientX - startX, 120)}px`
+            if (axis !== 'y') {
+              shell.style.width = `${Math.max(Math.min(startW + ev.clientX - startX, maxW), 120)}px`
+            }
             ta.style.height = `${Math.max(startH + ev.clientY - startY, 40)}px`
           }
           const up = () => {

package/src/molecules/ColorInputRow.jsx

@@ -127,7 +127,9 @@ export default function ColorInputRow({
     chip(24)
   )
 
-  const labelCls = `kol-helper-12 truncate ${unused ? 'text-meta' : 'text-emphasis'}`
+  /* leading-normal: truncate's overflow clip cuts mono descenders on
+   * kol-helper's 1-em line box (MenuItemDescenderClip sweep, 2026-08-12). */
+  const labelCls = `kol-helper-12 truncate leading-normal ${unused ? 'text-meta' : 'text-emphasis'}`
 
   const hexInput = (
     <Input
@@ -156,7 +158,7 @@ export default function ColorInputRow({
         >
           {swatchCell}
           <span className={labelCls}>{labelVisible ? label : ''}</span>
-          <span className={`kol-helper-10 truncate ${unused ? 'text-subtle' : 'text-meta'}`}>
+          <span className={`kol-helper-10 truncate leading-normal ${unused ? 'text-subtle' : 'text-meta'}`}>
             {tokenName}
           </span>
           {hexInput}

package/src/molecules/FieldRow.jsx

@@ -236,7 +236,8 @@ export default function FieldRow({
       <div className={`kol-mono-12 text-emphasis${type === 'media' ? ' self-start pt-1' : ''}`}>{label}</div>
       <div className="min-w-0">{control}</div>
       {hint != null && (
-        <div className="col-start-2 kol-helper-12 text-meta pt-2 truncate">{hint}</div>
+        /* leading-normal: descender fix (MenuItemDescenderClip sweep, 2026-08-12) */
+        <div className="col-start-2 kol-helper-12 text-meta pt-2 truncate leading-normal">{hint}</div>
       )}
     </div>
   )

package/src/molecules/MenuItem.jsx

@@ -101,7 +101,11 @@ export function MenuDropdownItem({ onClick, disabled, prefix, iconLeft, shortcut
     >
       {prefix && <span className="shrink-0 inline-flex items-center">{prefix}</span>}
       {iconLeft && <span className="shrink-0 w-4 inline-flex items-center justify-center">{iconLeft}</span>}
-      <span className="flex-1 truncate">{children}</span>
+      {/* leading-normal: kol-helper-12 is line-height 1, and truncate's
+        * overflow clip cuts mono descenders on a 1-em line box ("Show grid"
+        * loses its g). The h-8 centered row absorbs the taller line box —
+        * zero layout shift (MenuItemDescenderClip, 2026-08-12). */}
+      <span className="flex-1 truncate leading-normal">{children}</span>
       {shortcut && <span className="kol-helper-10 text-emphasis shrink-0 inline-flex items-center">{shortcut}</span>}
     </button>
   )
@@ -133,7 +137,8 @@ export function MenuDropdownNest({ prefix, iconLeft, label, children }) {
       >
         {prefix && <span className="shrink-0 inline-flex items-center">{prefix}</span>}
         {iconLeft && <span className="shrink-0 w-4 inline-flex items-center justify-center">{iconLeft}</span>}
-        <span className="flex-1 truncate">{label}</span>
+        {/* leading-normal — same descender fix as MenuDropdownItem above. */}
+        <span className="flex-1 truncate leading-normal">{label}</span>
         <Icon
           name="chevron-down"
           size={10}

package/src/molecules/Modal.jsx

@@ -9,6 +9,13 @@ import Input from '../atoms/Input.jsx'
  *   const { prompt, confirm } = useModal()
  *   const name    = await prompt('Name this frame:', 'Untitled')
  *   const proceed = await confirm('Discard unsaved changes?')
+ *   const restore = await confirm('Restore your last canvas?',
+ *                                 { okLabel: 'Restore', cancelLabel: 'New file' })
+ *
+ * Both take an options object — `{ okLabel, cancelLabel }` (prompt: third
+ * arg, after defaultValue) — so the buttons can SAY the outcome; defaults
+ * stay OK / Cancel, existing callers untouched (ModalConfirmLabels,
+ * 2026-08-12). Enter/Escape keep their meanings regardless of labels.
  *
  * Returned promise resolves to:
  *   - prompt  → string (value) on submit, `null` on cancel
@@ -30,12 +37,12 @@ export function ModalProvider({ children }) {
     })
   }, [])
 
-  const prompt = useCallback((title, defaultValue = '') =>
-    new Promise((resolve) => setState({ kind: 'prompt', title, defaultValue, resolve })),
+  const prompt = useCallback((title, defaultValue = '', { okLabel, cancelLabel } = {}) =>
+    new Promise((resolve) => setState({ kind: 'prompt', title, defaultValue, okLabel, cancelLabel, resolve })),
   [])
 
-  const confirm = useCallback((title) =>
-    new Promise((resolve) => setState({ kind: 'confirm', title, resolve })),
+  const confirm = useCallback((title, { okLabel, cancelLabel } = {}) =>
+    new Promise((resolve) => setState({ kind: 'confirm', title, okLabel, cancelLabel, resolve })),
   [])
 
   return (
@@ -85,7 +92,9 @@ function ModalView({ state, closeWith }) {
           maxWidth: '90vw',
         }}
       >
-        <p className="kol-helper-12 text-emphasis">{state.title}</p>
+        {/* kol-mono-12, not helper: dialog copy WRAPS, and helper's
+          * line-height 1 is single-line chrome only (type protocol). */}
+        <p className="kol-mono-12 text-emphasis">{state.title}</p>
         {state.kind === 'prompt' && (
           <Input
             ref={inputRef}
@@ -97,19 +106,28 @@ function ModalView({ state, closeWith }) {
           />
         )}
         <div className="flex gap-2 justify-end">
-          <Button variant="secondary" size="sm" onClick={cancel}>Cancel</Button>
-          <Button variant="primary"   size="sm" onClick={submit}>OK</Button>
+          <Button variant="secondary" size="sm" onClick={cancel}>{state.cancelLabel ?? 'Cancel'}</Button>
+          <Button variant="primary"   size="sm" onClick={submit}>{state.okLabel ?? 'OK'}</Button>
         </div>
       </div>
     </div>
   )
 }
 
+/* Warn once, not per call — the fallback swallowing a missing ModalProvider
+ * silently is how kol-fxr ran months on native window.confirm without
+ * noticing (ModalConfirmLabels, 2026-08-12). */
+let warnedNoProvider = false
+
 export function useModal() {
   const ctx = useContext(ModalCtx)
   if (ctx) return ctx
   /* No-context fallback — falls back to native prompt/confirm so callers
    * don't need to null-check. */
+  if (!warnedNoProvider && typeof console !== 'undefined') {
+    warnedNoProvider = true
+    console.warn('[kol] useModal(): no <ModalProvider> mounted — falling back to native window.prompt/confirm. Custom labels are ignored on the fallback.')
+  }
   return {
     prompt:  async (title, def = '') => {
       if (typeof window === 'undefined') return null

package/src/organisms/RecordManager.jsx

@@ -353,7 +353,7 @@ export default function RecordManager({
             {onPreview && (
               <ToolbarIcon name="play" label="Preview" onClick={() => onPreview(record)} />
             )}
-            {saveState != null && <span className="kol-helper-10 text-meta truncate">{saveState}</span>}
+            {saveState != null && <span className="kol-helper-10 text-meta truncate leading-normal">{saveState}</span>}
             {onPublish && (
               <Button variant="primary" size="sm" onClick={() => onPublish(record)}>
                 {publishLabel}