@kolkrabbi/kol-component 0.1.2 → 0.3.0

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/{atoms → molecules}/Slider.jsx

@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useState } from 'react'
-import Input from './Input.jsx'
+import Input from '../atoms/Input.jsx'
 
 /**
  * Slider — range slider with label and an editable value readout.

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 />}
+    </>
+  )
+}