@kolkrabbi/kol-component 0.2.0 → 0.3.0

package/src/molecules/ImageBlock.jsx

@@ -0,0 +1,34 @@
+import Figure from '../atoms/Figure.jsx'
+import Image from './Image.jsx'
+
+/**
+ * ImageBlock — a captioned prose image: the DS Figure shell (optional label,
+ * aspect-locked bordered frame, optional figcaption) wrapping a cover-fit DS
+ * Image. The long-form counterpart to VideoBlock — both compose the same
+ * Figure atom, so the frame chrome lives in one place.
+ *
+ * De-Sanitized: takes a resolved `src` string (no CMS `value` object, no
+ * SanityImage URL builder). Missing `src` degrades to Image's own
+ * AssetPlaceholder rather than rendering an empty frame.
+ *
+ * Label and caption render exactly as authored — no casing transforms.
+ *
+ * @param {string} src      resolved image URL
+ * @param {string} alt      alt text
+ * @param {string} label    small mono label above the frame
+ * @param {string} caption  figcaption below the frame
+ * @param {string} aspect   CSS aspect-ratio for the frame (default '5/3')
+ * @param {string} className extra classes on the <figure>
+ */
+export default function ImageBlock({ src, alt = '', label, caption, aspect = '5/3', className = '' }) {
+  return (
+    <Figure label={label} caption={caption} aspect={aspect} className={className}>
+      <Image
+        src={src}
+        alt={alt}
+        className="object-cover"
+        style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+      />
+    </Figure>
+  )
+}

package/src/molecules/SelectionOverlay.jsx

@@ -0,0 +1,108 @@
+/* taxonomy-ok: presentational transform-chrome overlay. It nests no KOL
+ * component (pure inline-styled squares + label), so by the letter of the
+ * molecule test it reads as an atom — but the lobby spec places it as a
+ * molecule: a reusable compound bounding-box/handles primitive that pairs with
+ * the Canvas scale layer, not a base atom. Kept here per that spec. */
+
+/**
+ * SelectionOverlay — pure transform chrome for a selected box.
+ *
+ * Renders a dashed outline, 8 named resize handles, and a `W × H` dimension
+ * label, all positioned in the **same 1080-virtual coordinate space** the
+ * target lives in (pairs with Canvas's scale layer — place it as a sibling of
+ * the box inside the same scale layer). Each handle carries a
+ * `data-handle="NW|N|NE|E|SE|S|SW|W"` attribute so a parent's pointer router
+ * can start the right resize mode. No interaction logic of its own — the drag
+ * math lives in the consumer, which reads `e.target.dataset.handle`.
+ *
+ * Ported from the brand editor with the `layer` model reduced to a flat `box`
+ * (per lobby spec): renders nothing when there's no positional box.
+ *
+ * @param {{x:number,y:number,w:number,h:number}} box  virtual-coord position + size; null/x==null → renders nothing
+ * @param {boolean}  showHandles  render the 8 resize handles (default true)
+ * @param {boolean}  showLabel    render the `W × H` dimension label (default true)
+ * @param {number}   handleSize   handle square size in virtual px (default 10)
+ * @param {string}   accentColor  outline + handle + label color (default var(--kol-accent-primary))
+ * @param {Function} labelFormatter (box) => string — dimension readout (default `${round(w)} × ${round(h)}`)
+ */
+const HANDLE_DIRS = [
+  { dir: 'NW', cursor: 'nwse-resize', x: 0,    y: 0    },
+  { dir: 'N',  cursor: 'ns-resize',   x: 0.5,  y: 0    },
+  { dir: 'NE', cursor: 'nesw-resize', x: 1,    y: 0    },
+  { dir: 'E',  cursor: 'ew-resize',   x: 1,    y: 0.5  },
+  { dir: 'SE', cursor: 'nwse-resize', x: 1,    y: 1    },
+  { dir: 'S',  cursor: 'ns-resize',   x: 0.5,  y: 1    },
+  { dir: 'SW', cursor: 'nesw-resize', x: 0,    y: 1    },
+  { dir: 'W',  cursor: 'ew-resize',   x: 0,    y: 0.5  },
+]
+
+export default function SelectionOverlay({
+  box,
+  showHandles = true,
+  showLabel = true,
+  handleSize = 10,
+  accentColor = 'var(--kol-accent-primary)',
+  labelFormatter = (b) => `${Math.round(b.w)} × ${Math.round(b.h)}`,
+}) {
+  if (!box || box.x == null) return null  /* no positional box → no chrome */
+
+  const { x, y, w, h } = box
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: x, top: y,
+        width: w, height: h,
+        pointerEvents: 'none',
+        zIndex: 100,
+      }}
+    >
+      <div
+        style={{
+          position: 'absolute', inset: 0,
+          outline: `1px dashed ${accentColor}`,
+          outlineOffset: 0,
+        }}
+      />
+      {showHandles && HANDLE_DIRS.map(({ dir, cursor, x: hx, y: hy }) => (
+        <div
+          key={dir}
+          data-handle={dir}
+          style={{
+            position: 'absolute',
+            left:   `calc(${hx * 100}% - ${handleSize / 2}px)`,
+            top:    `calc(${hy * 100}% - ${handleSize / 2}px)`,
+            width:  handleSize,
+            height: handleSize,
+            background: 'white',
+            border: `1px solid ${accentColor}`,
+            cursor,
+            pointerEvents: 'auto',
+          }}
+        />
+      ))}
+      {showLabel && (
+        <span
+          style={{
+            position: 'absolute',
+            left: 0,
+            top: '100%',
+            marginTop: 6,
+            fontFamily: 'var(--kol-font-family-mono)',
+            fontSize: 10,
+            letterSpacing: '0.04em',
+            color: accentColor,
+            background: 'rgba(0,0,0,0.6)',
+            padding: '2px 6px',
+            borderRadius: 2,
+            whiteSpace: 'nowrap',
+            pointerEvents: 'none',
+          }}
+        >
+          {labelFormatter(box)}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/molecules/ShapeDropdown.jsx

@@ -0,0 +1,92 @@
+import { useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-loader'
+import Button from '../atoms/Button.jsx'
+import { PopoverPanel, usePopover } from '../atoms/Popover.jsx'
+import { MenuDropdownItem } from './MenuItem.jsx'
+
+/**
+ * ShapeDropdown — split icon-button + variant-menu molecule (the tool-palette
+ * idiom: Select · Text · [Shape ▾] · Pattern). The main button reflects the
+ * current variant and fires `onAction` with its id; the chevron half opens a
+ * menu of all variants — picking one fires `onChange` and closes.
+ *
+ * Composed from Button (both trigger halves), usePopover/PopoverPanel (menu
+ * positioning, dismiss, portal) and MenuDropdownItem (rows — same rows as the
+ * Dropdown molecule, ✓ marks the active variant).
+ *
+ * For single-value list selection with a text trigger use `Dropdown`; this is
+ * for tool bars where the trigger is itself an action.
+ *
+ * @param {Object} props
+ * @param {{id: string, label: string, icon?: string}[]} props.options - Variants: menu rows + trigger glyph. `icon` optional — the trigger falls back to the label.
+ * @param {string} props.value - Active variant id (controlled)
+ * @param {Function} props.onChange - Fires with the picked variant id (menu selection)
+ * @param {Function} props.onAction - Fires with the current variant id (main-button click)
+ * @param {string} props.className - Additional classes on the wrapper
+ */
+const ShapeDropdown = ({ options = [], value, onChange, onAction, className = '' }) => {
+  const [open, setOpen] = useState(false)
+  const popover = usePopover({
+    open,
+    onOpenChange: setOpen,
+    placement: 'bottom-start',
+    offset: 4,
+    role: 'menu',
+  })
+
+  const current = options.find((option) => option.id === value) || options[0]
+
+  const handleSelect = (option) => {
+    onChange?.(option.id)
+    setOpen(false)
+  }
+
+  return (
+    <div className={`inline-flex items-center ${className}`.trim()}>
+      {current?.icon ? (
+        <Button
+          variant="ghost"
+          size="sm"
+          quiet
+          iconOnly={current.icon}
+          aria-label={current.label}
+          title={current.label}
+          onClick={() => onAction?.(current.id)}
+        />
+      ) : (
+        <Button variant="ghost" size="sm" quiet onClick={() => onAction?.(current?.id)}>
+          {current?.label}
+        </Button>
+      )}
+      {/* Button doesn't forward refs — anchor the popover on a span wrapper,
+       * same pattern as Tooltip in atoms/Popover.jsx. Clicks on the inner
+       * button bubble to the span, where useClick toggles the menu. */}
+      <span
+        ref={popover.refs.setReference}
+        {...popover.getReferenceProps()}
+        className="inline-flex"
+      >
+        <Button variant="ghost" size="sm" quiet iconOnly="chevron-down" iconSize={10} aria-label="Variants" />
+      </span>
+      <PopoverPanel
+        popover={popover}
+        panel={false}
+        focus={false}
+        className="bg-surface-secondary border border-fg-08 rounded shadow-lg"
+      >
+        {options.map((option) => (
+          <MenuDropdownItem
+            key={option.id}
+            onClick={() => handleSelect(option)}
+            iconLeft={option.icon ? <Icon name={option.icon} size={14} /> : undefined}
+            shortcut={option.id === current?.id ? <Icon name="check" size={11} /> : undefined}
+          >
+            {option.label}
+          </MenuDropdownItem>
+        ))}
+      </PopoverPanel>
+    </div>
+  )
+}
+
+export default ShapeDropdown

package/src/molecules/ShellDrawer.jsx

@@ -0,0 +1,169 @@
+import { useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { Icon } from '@kolkrabbi/kol-loader'
+import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
+
+/* taxonomy-ok: nests kol-loader's Icon (a package import the relative-import
+ * check can't see). */
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+/**
+ * ShellDrawer — THE edge drawer: a portalled panel that slides in from the
+ * left or right viewport edge over a dimming backdrop. Distinct from Modal
+ * (centered prompt/confirm) and FullscreenOverlay (fills the whole viewport,
+ * not an edge sheet). Escape, backdrop click and the built-in close button
+ * all call `onClose`; body scroll locks while open; focus moves into the
+ * panel on open, is trapped there, and returns to the opener on close.
+ *
+ * The slide transition is gated on prefers-reduced-motion: reduced users get
+ * an instant mount/unmount with no transform animation.
+ *
+ * Presentational shell — the parent owns the open state and supplies the
+ * header slot and body; no navigation or routing logic lives here.
+ *
+ * @param {boolean}       open      drawer visible (drives slide in/out)
+ * @param {Function}      onClose   close request (Esc / backdrop / close button)
+ * @param {string}        side      'left' | 'right' — edge the panel slides from
+ * @param {number|string} width     panel width (px number or CSS length); omit for full-width sheet
+ * @param {ReactNode}     header    header-row content beside the close button (replaces the source's baked-in wordmark)
+ * @param {ReactNode}     children  scrollable panel body
+ * @param {string}        className extra classes on the panel
+ */
+export default function ShellDrawer({
+  open,
+  onClose,
+  side = 'left',
+  width,
+  header,
+  children,
+  className = '',
+}) {
+  const reduced = usePrefersReducedMotion()
+  const panelRef = useRef(null)
+
+  /* Mount/slide state machine: `present` keeps the portal mounted through
+   * the exit slide; `shown` drives the transform/opacity classes. Reduced
+   * motion collapses both onto `open` — instant show/hide, no transform. */
+  const [present, setPresent] = useState(open)
+  const [shown, setShown] = useState(open)
+
+  useEffect(() => {
+    if (reduced) {
+      setPresent(open)
+      setShown(open)
+      return undefined
+    }
+    if (open) {
+      setPresent(true)
+      // double rAF: let the off-screen position paint before sliding in
+      let raf2
+      const raf1 = requestAnimationFrame(() => {
+        raf2 = requestAnimationFrame(() => setShown(true))
+      })
+      return () => {
+        cancelAnimationFrame(raf1)
+        if (raf2) cancelAnimationFrame(raf2)
+      }
+    }
+    setShown(false)
+    const t = setTimeout(() => setPresent(false), 200) // matches duration-200
+    return () => clearTimeout(t)
+  }, [open, reduced])
+
+  // Escape closes; Tab is trapped inside the panel while open
+  useEffect(() => {
+    if (!open) return undefined
+    const onKey = (e) => {
+      if (e.key === 'Escape') {
+        onClose?.()
+        return
+      }
+      if (e.key !== 'Tab') return
+      const panel = panelRef.current
+      if (!panel) return
+      const nodes = panel.querySelectorAll(FOCUSABLE)
+      if (!nodes.length) {
+        e.preventDefault()
+        panel.focus()
+        return
+      }
+      const first = nodes[0]
+      const last = nodes[nodes.length - 1]
+      const active = document.activeElement
+      if (!panel.contains(active)) {
+        e.preventDefault()
+        first.focus()
+      } else if (e.shiftKey && (active === first || active === panel)) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault()
+        first.focus()
+      }
+    }
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  }, [open, onClose])
+
+  /* Body scroll-lock + focus in/out. Gated on `present` too so the panel
+   * exists before we focus it (it mounts one commit after `open` flips). */
+  useEffect(() => {
+    if (!(open && present)) return undefined
+    const prevOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    const prevFocus = document.activeElement
+    panelRef.current?.focus()
+    return () => {
+      document.body.style.overflow = prevOverflow
+      if (prevFocus instanceof HTMLElement) prevFocus.focus()
+    }
+  }, [open, present])
+
+  if (!present || typeof document === 'undefined') return null
+
+  const slideOut = side === 'right' ? 'translate-x-full' : '-translate-x-full'
+  const motionPanel = reduced
+    ? ''
+    : `transition-transform duration-200 ease-out ${shown ? 'translate-x-0' : slideOut}`
+  const motionBackdrop = reduced
+    ? ''
+    : `transition-opacity duration-200 ease-out ${shown ? 'opacity-100' : 'opacity-0'}`
+
+  return createPortal(
+    <>
+      <div
+        className={`fixed inset-0 z-[100] bg-black/50 ${motionBackdrop}`}
+        onClick={onClose}
+        aria-hidden="true"
+      />
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        tabIndex={-1}
+        className={`fixed inset-y-0 z-[200] flex max-w-full flex-col bg-surface-primary px-4 py-4 shadow-2xl outline-none md:px-5 lg:px-6 ${
+          side === 'right' ? 'right-0 border-l' : 'left-0 border-r'
+        } border-fg-08 ${width == null ? 'w-full' : ''} ${motionPanel} ${className}`}
+        style={width != null ? { width: typeof width === 'number' ? `${width}px` : width } : undefined}
+      >
+        <div className="mb-6 flex items-center gap-4">
+          {header != null && <div className="min-w-0 flex-1">{header}</div>}
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close"
+            className="ml-auto flex h-8 w-8 shrink-0 items-center justify-center rounded-md border-0 bg-transparent cursor-pointer text-fg-64 transition-colors hover:bg-fg-08 hover:text-emphasis"
+          >
+            <Icon name="close" size={14} />
+          </button>
+        </div>
+        <div className="flex-1 overflow-y-auto pr-1" style={{ overflowAnchor: 'none' }}>
+          {children}
+        </div>
+      </div>
+    </>,
+    document.body,
+  )
+}

package/src/molecules/ShellSearchOverlay.jsx

@@ -0,0 +1,177 @@
+import { useEffect, useId, useRef, useState } from 'react'
+import SearchInput from '../atoms/SearchInput.jsx'
+
+/**
+ * HighlightMatch — default row renderer: underlines the first
+ * case-insensitive `query` slice inside `label` at full ink. Exported for
+ * consumers building their own rows; not in the package barrel.
+ *
+ * @param {string} label full row label
+ * @param {string} query current query (empty / no match → plain label)
+ */
+export function HighlightMatch({ label, query }) {
+  const idx = query ? label.toLowerCase().indexOf(query.toLowerCase()) : -1
+  if (idx === -1) return <span>{label}</span>
+  return (
+    <>
+      <span>{label.slice(0, idx)}</span>
+      <span className="text-fg underline decoration-2 underline-offset-[3px]">
+        {label.slice(idx, idx + query.length)}
+      </span>
+      <span>{label.slice(idx + query.length)}</span>
+    </>
+  )
+}
+
+/**
+ * ShellSearchOverlay — the ⌘K command palette: fullscreen dim + centered
+ * panel, a bare SearchInput on top, result rows beneath (HighlightMatch
+ * label, dim hint line, right-aligned group label). Distinct from Modal
+ * (prompt/confirm only) — this is the search/command primitive.
+ *
+ * Content-agnostic: the consumer filters and passes `results`; selection
+ * emits `onSelect(item)` (no navigation here — ported off react-router).
+ * The ⌘K binding itself lives in the shell's key handler, not here.
+ *
+ * Keyboard: ArrowUp/ArrowDown rove the active row (mouse hover roves too),
+ * Enter selects it (index starts at 0 → Enter-selects-first preserved),
+ * Escape closes. Focus trap: focus moves into the input on open, returns to
+ * the opener on close, and Tab is pinned — rows are combobox options driven
+ * via aria-activedescendant, never tab stops.
+ *
+ * @param {boolean}  open          mount/unmount the overlay
+ * @param {Function} onClose       () => void — backdrop click, Escape, post-select
+ * @param {Array}    results       pre-filtered rows: { id, label, group?, hint? }
+ * @param {string}   query         controlled query (drives the highlight slice)
+ * @param {Function} onQueryChange (string) => void — input change
+ * @param {Function} onSelect      (item) => void — row click / Enter; consumer navigates
+ * @param {string}   placeholder   input placeholder
+ */
+export default function ShellSearchOverlay({
+  open,
+  onClose,
+  results = [],
+  query = '',
+  onQueryChange,
+  onSelect,
+  placeholder = 'Search…',
+}) {
+  const panelRef = useRef(null)
+  const listRef = useRef(null)
+  const listId = useId()
+  const [activeIndex, setActiveIndex] = useState(0)
+  const active = results.length > 0 ? Math.min(activeIndex, results.length - 1) : -1
+
+  /* Focus in on open, restore the opener on close. querySelector instead of
+   * a ref through SearchInput — ref-as-prop needs React 19 and the package
+   * peer range still allows 18. */
+  useEffect(() => {
+    if (!open) return undefined
+    const prev = document.activeElement
+    panelRef.current?.querySelector('input')?.focus()
+    return () => { if (prev instanceof HTMLElement) prev.focus() }
+  }, [open])
+
+  /* Roving row resets to the top on every query change / reopen. */
+  useEffect(() => { setActiveIndex(0) }, [query, open])
+
+  /* Keep the active row visible inside the scrolling list. */
+  useEffect(() => {
+    if (active < 0) return
+    listRef.current?.children[active]?.scrollIntoView({ block: 'nearest' })
+  }, [active])
+
+  if (!open) return null
+
+  const select = (item) => {
+    onSelect?.(item)
+    onClose?.()
+  }
+
+  const optionId = (item) => `${listId}-${item.id}`
+
+  const handleKeyDown = (e) => {
+    if (e.key === 'Escape') {
+      e.preventDefault()
+      onClose?.()
+    } else if (e.key === 'ArrowDown') {
+      e.preventDefault()
+      setActiveIndex((i) => Math.min(i + 1, results.length - 1))
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      setActiveIndex((i) => Math.max(i - 1, 0))
+    } else if (e.key === 'Enter' && active >= 0) {
+      e.preventDefault()
+      select(results[active])
+    } else if (e.key === 'Tab') {
+      /* Focus trap — the input is the palette's only tab stop. */
+      e.preventDefault()
+    }
+  }
+
+  return (
+    <div className="fixed inset-0 z-[300] flex items-start justify-center pt-[20vh]">
+      <div
+        className="absolute inset-0 bg-black/60 backdrop-blur-[1px]"
+        onClick={onClose}
+        aria-hidden="true"
+      />
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label="Search"
+        className="relative w-full max-w-lg mx-4 overflow-hidden bg-surface-primary border border-fg-08 rounded-[var(--kol-radius-2xl)] shadow-[0_20px_60px_rgba(0,0,0,0.4)]"
+      >
+        <SearchInput
+          bare
+          value={query}
+          onChange={(e) => onQueryChange?.(e.target.value)}
+          placeholder={placeholder}
+          onKeyDown={handleKeyDown}
+          role="combobox"
+          aria-expanded={results.length > 0}
+          aria-controls={listId}
+          aria-activedescendant={active >= 0 ? optionId(results[active]) : undefined}
+        />
+
+        {results.length > 0 && (
+          <ul
+            ref={listRef}
+            id={listId}
+            role="listbox"
+            className="border-t border-fg-08 max-h-80 overflow-y-auto py-1"
+          >
+            {results.map((item, i) => (
+              <li
+                key={item.id}
+                id={optionId(item)}
+                role="option"
+                aria-selected={i === active}
+                /* preventDefault keeps focus in the input through the click */
+                onMouseDown={(e) => e.preventDefault()}
+                onClick={() => select(item)}
+                onMouseEnter={() => setActiveIndex(i)}
+                className={`flex items-center gap-2 px-4 py-1.5 cursor-pointer kol-mono-14 transition-colors ${
+                  i === active ? 'bg-fg-08 text-fg' : 'text-fg-64'
+                }`}
+              >
+                <span className="flex flex-col min-w-0">
+                  <span className="truncate">
+                    <HighlightMatch label={item.label} query={query} />
+                  </span>
+                  {item.hint && (
+                    <span className="kol-mono-12 text-fg-48 truncate">{item.hint}</span>
+                  )}
+                </span>
+                {item.group && (
+                  <span className="ml-auto shrink-0 kol-helper-10 text-fg-48">{item.group}</span>
+                )}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/molecules/SpecList.jsx

@@ -0,0 +1,30 @@
+import Divider from '../atoms/Divider.jsx'
+
+/**
+ * SpecList — compact definition list of [label | value] rows: label left and
+ * muted, value right-aligned one tone brighter, Divider-separated between
+ * rows (never after the last). Data-agnostic "key facts" strip — the caller
+ * formats values before passing (e.g. "Limited (30)", "A3, A2, A1").
+ *
+ * @param {Array<{label: string, value: ReactNode}>} items rows, keyed by label
+ * @param {boolean} framed wrap the list in leading + trailing Divider
+ */
+export default function SpecList({ items = [], framed = false }) {
+  return (
+    <>
+      {framed && <Divider />}
+      <dl className="py-3">
+        {items.map((item, index) => (
+          <div key={item.label}>
+            <div className="flex items-center justify-between gap-6 py-3">
+              <dt className="kol-helper-12 text-fg-48 whitespace-nowrap">{item.label}</dt>
+              <dd className="kol-mono-12 text-right text-fg-64">{item.value}</dd>
+            </div>
+            {index < items.length - 1 && <Divider />}
+          </div>
+        ))}
+      </dl>
+      {framed && <Divider />}
+    </>
+  )
+}