@kolkrabbi/kol-component 0.2.0 → 0.3.0

package/src/organisms/ScrollDriftGallery.jsx

@@ -0,0 +1,214 @@
+import { useEffect, useMemo, useRef } from 'react'
+import { gsap } from 'gsap'
+import { ScrollTrigger } from 'gsap/ScrollTrigger'
+import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
+
+gsap.registerPlugin(ScrollTrigger)
+
+const DEFAULT_BG_KEYFRAMES = [
+  { backgroundColor: '#000000', duration: 0 },
+  { backgroundColor: '#0a0a08', duration: 0.15 },
+  { backgroundColor: '#1a1812', duration: 0.3 },
+  { backgroundColor: '#f5f0e8', duration: 0.5 }, // warm cream
+  { backgroundColor: '#e8df00', duration: 0.7 }, // acid yellow
+  { backgroundColor: '#c8ff00', duration: 0.85 }, // electric chartreuse
+  { backgroundColor: '#0a0a0a', duration: 1 }, // back to black
+]
+
+// Deterministic per-index layout — depends only on index + count, so it
+// survives without any per-item data.
+function layoutFor(index, cardSpacing) {
+  const seed = (index * 7 + 3) % 24
+  const row = index % 3
+  const baseY = [8, 35, 62][row] // top / middle / bottom (vh %)
+  const y = baseY + ((seed % 7) - 3) * 3 // ± jitter
+  const scale = [0.7, 1, 0.85, 1.15, 0.75, 0.95, 1.1, 0.8][index % 8]
+  const rotation = ((seed % 5) - 2) * 1.5 // -3..+3 deg
+  const parallaxSpeed = [0.6, 0.8, 1, 1.2, 0.7, 0.9, 1.1, 0.85][index % 8]
+  const x = index * cardSpacing + (seed % 3) * 60 // horizontal slot + jitter
+  const width = scale > 1 ? 400 : scale > 0.85 ? 340 : 280
+  return { x, y, scale, rotation, parallaxSpeed, width, index }
+}
+
+/**
+ * ScrollDriftGallery — a pinned hero where vertical scroll scrubs a horizontal
+ * track ("The Drift"): the section pins and page-scroll drives (1) the track
+ * sideways, (2) each floating card at its own parallax speed, (3) a keyframed
+ * background-color journey, (4) a slow-parallax vertical title, and (5) a
+ * bottom progress bar. Card geometry (y-row, scale, rotation, x-slot, width) is
+ * derived deterministically from index + count; content is a `renderCard` slot.
+ *
+ * Requires GSAP ScrollTrigger (registered here). All tweens live in a
+ * gsap.context reverted on cleanup, with invalidateOnRefresh + function-based
+ * end/x so pin distance and travel recompute on resize. On
+ * `prefers-reduced-motion` the rig is skipped entirely and the cards render in
+ * a plain horizontally-scrollable row.
+ *
+ * @param {any[]}    items       cards; drives layout count + totalWidth
+ * @param {(item:any,meta:{scale,rotation,width,index})=>ReactNode} renderCard card slot
+ * @param {Function} onCardClick (item, index) => void — click on a card
+ * @param {number}   totalWidth  scroll/scrub distance (default items.length*cardSpacing + 800)
+ * @param {ReactNode} title      giant vertical wordmark (content — author case at call site)
+ * @param {ReactNode} intro      opening breathing-space slot
+ * @param {ReactNode} outro      end-CTA slot
+ * @param {Array<{backgroundColor,duration}>} bgKeyframes background-color journey (fractional durations 0→1)
+ * @param {number}   cardSpacing horizontal slot pitch, px (default 520)
+ */
+export default function ScrollDriftGallery({
+  items = [],
+  renderCard,
+  onCardClick,
+  totalWidth,
+  title,
+  intro,
+  outro,
+  bgKeyframes = DEFAULT_BG_KEYFRAMES,
+  cardSpacing = 520,
+}) {
+  const bgRef = useRef(null)
+  const containerRef = useRef(null)
+  const horizontalRef = useRef(null)
+  const titleRef = useRef(null)
+  const reducedMotion = usePrefersReducedMotion()
+
+  const layout = useMemo(
+    () => items.map((_, i) => layoutFor(i, cardSpacing)),
+    [items, cardSpacing],
+  )
+  const resolvedTotalWidth = totalWidth ?? items.length * cardSpacing + 800
+
+  useEffect(() => {
+    if (reducedMotion) return undefined
+
+    const ctx = gsap.context(() => {
+      const trigger = {
+        trigger: containerRef.current,
+        start: 'top top',
+        end: () => `+=${resolvedTotalWidth}`,
+      }
+
+      // (1) Pin + horizontal scrub.
+      gsap.to(horizontalRef.current, {
+        x: () => -(resolvedTotalWidth - window.innerWidth),
+        ease: 'none',
+        scrollTrigger: { ...trigger, scrub: 1, pin: true, anticipatePin: 1, invalidateOnRefresh: true },
+      })
+
+      // (2) Background-color journey.
+      gsap.to(bgRef.current, { scrollTrigger: { ...trigger, scrub: true }, keyframes: bgKeyframes })
+
+      // (3) Title slow-parallax (0.3× the track).
+      gsap.to(titleRef.current, {
+        x: () => -(resolvedTotalWidth - window.innerWidth) * 0.3,
+        ease: 'none',
+        scrollTrigger: { ...trigger, scrub: 1 },
+      })
+
+      // (4) Per-card parallax.
+      const cards = horizontalRef.current?.querySelectorAll('[data-drift-card]')
+      cards?.forEach((card, i) => {
+        const meta = layout[i]
+        if (!meta) return
+        gsap.to(card, {
+          x: (meta.parallaxSpeed - 1) * 300,
+          ease: 'none',
+          scrollTrigger: { ...trigger, scrub: 1 },
+        })
+      })
+
+      // (5) Progress bar.
+      const bar = containerRef.current?.querySelector('[data-drift-progress]')
+      if (bar) gsap.to(bar, { width: '100%', ease: 'none', scrollTrigger: { ...trigger, scrub: true } })
+    }, containerRef)
+
+    return () => ctx.revert()
+  }, [layout, resolvedTotalWidth, bgKeyframes, reducedMotion])
+
+  // Reduced-motion fallback: plain horizontal scroll, no pin, no gsap.
+  if (reducedMotion) {
+    return (
+      <div style={{ backgroundColor: bgKeyframes[bgKeyframes.length - 1]?.backgroundColor || '#0a0a0a' }}>
+        <section className="relative overflow-hidden py-16">
+          {title != null && (
+            <div className="px-6 pb-8" style={{ writingMode: 'horizontal-tb' }}>
+              <span className="text-[12vw] font-bold tracking-[-0.04em] leading-none opacity-[0.06]">{title}</span>
+            </div>
+          )}
+          <div className="flex items-center gap-8 overflow-x-auto px-6 pb-6">
+            {intro != null && <div className="flex-shrink-0">{intro}</div>}
+            {items.map((item, i) => {
+              const meta = layout[i]
+              return (
+                <div
+                  key={i}
+                  className="flex-shrink-0 cursor-pointer"
+                  style={{ width: `${meta.width}px` }}
+                  onClick={() => onCardClick?.(item, i)}
+                >
+                  {renderCard?.(item, meta)}
+                </div>
+              )
+            })}
+            {outro != null && <div className="flex-shrink-0">{outro}</div>}
+          </div>
+        </section>
+      </div>
+    )
+  }
+
+  return (
+    <div ref={bgRef} style={{ backgroundColor: bgKeyframes[0]?.backgroundColor || '#000000' }} className="transition-colors duration-0">
+      <section ref={containerRef} className="relative h-screen overflow-hidden">
+        {/* Vertical title — pinned, slow parallax */}
+        {title != null && (
+          <div
+            ref={titleRef}
+            className="absolute left-8 top-0 h-full flex items-center z-10 pointer-events-none select-none"
+            style={{ writingMode: 'vertical-rl', textOrientation: 'mixed' }}
+          >
+            <span className="text-[20vw] font-bold tracking-[-0.04em] leading-none opacity-[0.06] mix-blend-difference">{title}</span>
+          </div>
+        )}
+
+        {/* Horizontal track */}
+        <div ref={horizontalRef} className="absolute top-0 left-0 h-full flex items-start" style={{ width: `${resolvedTotalWidth}px` }}>
+          {/* Opening breathing space */}
+          {intro != null && (
+            <div className="flex-shrink-0 w-[50vw] h-full flex items-center justify-center">{intro}</div>
+          )}
+
+          {/* Floating cards */}
+          {layout.map((meta, i) => (
+            <div
+              key={i}
+              data-drift-card
+              className="absolute cursor-pointer group"
+              style={{
+                left: `${meta.x + 600}px`, // offset past the opening space
+                top: `${meta.y}%`,
+                width: `${meta.width}px`,
+                transform: `rotate(${meta.rotation}deg) scale(${meta.scale})`,
+                transformOrigin: 'center center',
+              }}
+              onClick={() => onCardClick?.(items[i], i)}
+            >
+              {renderCard?.(items[i], meta)}
+            </div>
+          ))}
+
+          {/* End CTA */}
+          {outro != null && (
+            <div className="absolute top-1/2 -translate-y-1/2 text-center" style={{ left: `${resolvedTotalWidth - 500}px` }}>
+              {outro}
+            </div>
+          )}
+        </div>
+
+        {/* Progress bar */}
+        <div className="absolute bottom-0 left-0 right-0 h-px bg-fg-08">
+          <div data-drift-progress className="h-full bg-accent-primary" style={{ width: '0%' }} />
+        </div>
+      </section>
+    </div>
+  )
+}

package/src/organisms/SpectrumGrid.jsx

@@ -0,0 +1,90 @@
+import { useEffect, useState } from 'react'
+import ColorSwatch from '../molecules/ColorSwatch.jsx'
+import { resolveCssVar, resolveCssColor, isLight } from '../hooks/cssVar.js'
+
+/**
+ * SpectrumGrid — matrix view of the whole ramp system: rows = ramps, columns =
+ * stops (50 → 900). Each cell is a ColorSwatch tile with the stop number and
+ * hex printed over it (text color contrast-corrected via isLight), so the whole
+ * palette is scannable in one grid.
+ *
+ * Values resolve live from CSS custom properties at mount — the inline
+ * getComputedStyle fork the source carried is replaced by the shared
+ * resolveCssVar (declared value → printed hex) + resolveCssColor (computed rgb →
+ * fed to isLight, robust to var() chains / color-mix). Edit a ramp in the theme
+ * and the grid follows on next mount.
+ *
+ * @param {string[]} ramps         rows; each resolves `--{ramp}-{stop}`
+ * @param {number[]} stops         columns (default 50…900)
+ * @param {Array<{ramp:string, stop:number}>} brandAnchors  cells that get the anchor dot
+ */
+
+const DEFAULT_STOPS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900]
+
+export default function SpectrumGrid({ ramps, stops = DEFAULT_STOPS, brandAnchors = [] }) {
+  const [resolved, setResolved] = useState(null)
+
+  useEffect(() => {
+    const out = {}
+    for (const ramp of ramps) {
+      out[ramp] = {}
+      for (const stop of stops) {
+        const token = `--${ramp}-${stop}`
+        out[ramp][stop] = { label: resolveCssVar(token), color: resolveCssColor(`var(${token})`) }
+      }
+    }
+    setResolved(out)
+  }, [ramps, stops])
+
+  if (!resolved) return <div className="kol-spectrum-grid w-full min-h-[120px]" aria-busy="true" />
+
+  const isBrandAnchor = (ramp, stop) => brandAnchors.some((a) => a.ramp === ramp && a.stop === stop)
+
+  return (
+    <div
+      className="kol-spectrum-grid grid w-full"
+      style={{
+        gridTemplateColumns: `var(--kol-sg-label-w, 100px) repeat(${stops.length}, minmax(0, 1fr))`,
+        gap: 'var(--kol-sg-gap, 4px)',
+      }}
+    >
+      <div className="contents">
+        <span aria-hidden="true" />
+        {stops.map((s) => (
+          <span key={s} className="kol-helper-12 text-fg-48 self-end pb-1">{s}</span>
+        ))}
+      </div>
+      {ramps.map((ramp) => (
+        <div key={ramp} className="contents">
+          <span className="kol-helper-12 text-emphasis self-center pr-2">{ramp}</span>
+          {stops.map((stop) => {
+            const { label, color } = resolved[ramp][stop]
+            const hex = label || color
+            const textColor = isLight(color) ? '#000' : '#fff'
+            const brand = isBrandAnchor(ramp, stop)
+            return (
+              <div
+                key={stop}
+                className="relative aspect-[5/3] rounded overflow-hidden transition-transform hover:scale-[1.04]"
+                title={`${ramp}-${stop}  ${hex}${brand ? '  · brand anchor' : ''}`}
+              >
+                <ColorSwatch hex={`var(--${ramp}-${stop})`} size="stretch" radius="none" frame={false} className="absolute inset-0" />
+                <div className="pointer-events-none absolute inset-0 px-2 py-1.5" style={{ color: textColor }}>
+                  <span className="kol-helper-12 font-bold block">{stop}</span>
+                  <span className="kol-helper-10 opacity-[.78] absolute bottom-1.5 left-2 max-[900px]:hidden">{hex}</span>
+                  {brand && (
+                    <span
+                      className="absolute top-1.5 right-2 w-2.5 h-2.5 rounded-full opacity-[.85]"
+                      style={{ background: 'currentColor' }}
+                      aria-hidden="true"
+                    />
+                  )}
+                </div>
+              </div>
+            )
+          })}
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/organisms/StackHero.jsx

@@ -0,0 +1,83 @@
+import FullBleedHero from './FullBleedHero.jsx'
+import Image from '../molecules/Image.jsx'
+
+/** Per-variant spacing presets — the only delta between StackHero and the
+ *  folded-in StackHeroTall (taller viewport + deeper bottom padding). */
+const VARIANTS = {
+  default: { height: 'min-h-[80vh]', padBottom: 'pb-12' },
+  tall: { height: 'min-h-[90vh]', padBottom: 'pb-32 sm:pb-40 lg:pb-48' },
+}
+
+/**
+ * StackHero — full-bleed image hero with a bottom-anchored, centered title +
+ * description under a bottom-up scrim. Built ON the DS FullBleedHero: the
+ * background Image plus a tokenized gradient scrim are handed in as the hero's
+ * media node, and the copy rides in the content slot pinned to the bottom.
+ * `StackHeroTall` is folded in as `variant="tall"` — a spacing preset, not a
+ * second file.
+ *
+ * De-branded: no CDN `src`/`srcSet` defaults, no brand-copy title/description
+ * defaults, no dead `aspectRatio` prop. The scrim reads `--kol-surface-primary`
+ * (theme-aware) instead of the hardcoded dark hex, and `objectFit`/
+ * `objectPosition` are inline styles (no JIT-invisible dynamic class). The app
+ * `reveal` entrance utility is dropped. Title/description authored as-is.
+ *
+ * @param {string} title           heading text
+ * @param {string} description     sub text
+ * @param {string} src             background image src
+ * @param {string} srcSet          responsive srcSet
+ * @param {string} sizes           `sizes` attribute (default '100vw')
+ * @param {string} alt             alt text
+ * @param {string} objectFit       CSS object-fit for the image (default 'cover')
+ * @param {string} objectPosition  CSS object-position for the image (default 'center')
+ * @param {'default'|'tall'} variant  spacing preset (default 'default')
+ * @param {string} className       extra classes on the hero section
+ */
+export default function StackHero({
+  title,
+  description,
+  src,
+  srcSet,
+  sizes = '100vw',
+  alt = '',
+  objectFit = 'cover',
+  objectPosition = 'center',
+  variant = 'default',
+  className = '',
+}) {
+  const { height, padBottom } = VARIANTS[variant] ?? VARIANTS.default
+
+  const media = (
+    <>
+      <Image
+        src={src}
+        srcSet={srcSet}
+        sizes={sizes}
+        alt={alt}
+        loading="eager"
+        className="kol-full-bleed-hero-media"
+        style={{ objectFit, objectPosition }}
+      />
+      <div
+        aria-hidden="true"
+        className="absolute inset-0 pointer-events-none"
+        style={{ background: 'linear-gradient(to top, var(--kol-surface-primary) 0%, transparent 100%)' }}
+      />
+    </>
+  )
+
+  return (
+    <FullBleedHero
+      media={media}
+      height={height}
+      align="center"
+      className={className}
+      panel={
+        <div className={`self-end w-full max-w-[520px] lg:max-w-[30%] text-center mx-auto lg:mx-0 flex flex-col gap-1 ${padBottom}`}>
+          <h1 className="kol-prose-display text-center">{title}</h1>
+          <p className="kol-mono-14 text-center text-fg-80">{description}</p>
+        </div>
+      }
+    />
+  )
+}

package/src/organisms/WorkCard.jsx

@@ -0,0 +1,120 @@
+import { useEffect, useState } from 'react'
+import TiltCard from '../atoms/TiltCard.jsx'
+import AssetPlaceholder from '../atoms/AssetPlaceholder.jsx'
+
+/* Ragged-skyline heights, chosen by `index % 3` — a shelf of these reads as an
+ * uneven horizon. Overridable via the `heights` prop. */
+const HEIGHTS = ['h-[408px] md:h-[560px]', 'h-[372px] md:h-[520px]', 'h-[336px] md:h-[480px]']
+const EASE = 'cubic-bezier(0.16, 1, 0.3, 1)'
+const TYPE_LABELS = { client: 'Client', collection: 'Collection', typeface: 'Typeface', tool: 'Tool', system: 'System' }
+
+/**
+ * WorkCard — the grid/shelf project tile for a `/work` listing: a fixed-size
+ * media card (the DS **TiltCard** in its `grounded` variant) with a
+ * hover-revealed bottom drawer carrying the project title + a meta line
+ * (client-or-type · year). The whole card is an anchor to the project detail;
+ * it preloads its own thumbnail and plays a staggered rise-and-untilt entrance
+ * keyed off its `index` in the shelf.
+ *
+ * Composes TiltCard (owns the `<img>` + pointer tilt); this organism adds the
+ * entrance choreography, the caption drawer, and the link. Router-agnostic:
+ * renders a plain `<a href>` plus an `onNavigate(href, event)` seam — call
+ * `preventDefault` inside it for SPA navigation. Flat project props (no Sanity):
+ * the meta line is composed internally so callers pass raw fields.
+ *
+ * Text casing: no text-transform (KOL rule) — the source's presentational
+ * `uppercase` is dropped; `title`, `client`, `year` render verbatim as authored.
+ *
+ * @param {string}          title       overlay heading (display type)
+ * @param {string}          thumbnail   image URL (preloaded, passed to TiltCard `src`); AssetPlaceholder shows when absent
+ * @param {string}          href        link target
+ * @param {string}          client      first meta segment; falls back to the type label
+ * @param {string}          type        'client'|'collection'|'typeface'|'tool'|'system' — mapped via TYPE_LABELS when no client
+ * @param {string|number}   year        second meta segment
+ * @param {number}          index       drives stagger height + entrance timing (default 0)
+ * @param {number}          perspective CSS perspective in px on fine pointers (default 800)
+ * @param {string[]}        heights     override the ragged-height ramp (chosen by index % heights.length)
+ * @param {Function}        onNavigate  (href, event) => void — anchor click seam for SPA routing
+ */
+export default function WorkCard({
+  title,
+  thumbnail,
+  href,
+  client,
+  type,
+  year,
+  index = 0,
+  perspective = 800,
+  heights = HEIGHTS,
+  onNavigate,
+}) {
+  const [ready, setReady] = useState(false)
+  // Evaluated once at mount (SSR-safe): drop perspective on coarse/small screens.
+  const [isMobile] = useState(
+    () => typeof window !== 'undefined' && window.matchMedia('(max-width: 767px)').matches,
+  )
+
+  useEffect(() => {
+    if (!thumbnail) {
+      setReady(true)
+      return
+    }
+    let cancelled = false
+    const img = new window.Image()
+    const done = () => { if (!cancelled) setReady(true) }
+    img.onload = done
+    img.onerror = done
+    img.src = thumbnail
+    return () => { cancelled = true }
+  }, [thumbnail])
+
+  const height = heights[index % heights.length]
+  const meta = [client || TYPE_LABELS[type] || type, year].filter(Boolean).join(' · ')
+
+  const drawer = (
+    <div className="absolute inset-x-0 bottom-0 z-10 p-4 md:p-6 bg-surface-inverse opacity-0 group-hover:opacity-100 transition-opacity duration-300">
+      <p className="kol-sans-display-02 text-fg-inverse leading-tight">{title}</p>
+      {meta && (
+        <p className="kol-mono-12 text-fg-inverse opacity-60 tracking-widest mt-2">{meta}</p>
+      )}
+    </div>
+  )
+
+  return (
+    <a
+      href={href}
+      onClick={onNavigate ? (e) => onNavigate(href, e) : undefined}
+      className={`flex-none w-[280px] md:w-[400px] ${height} group`}
+      style={isMobile ? undefined : { perspective }}
+    >
+      <div
+        className="w-full h-full"
+        style={{
+          transformOrigin: 'bottom center',
+          opacity: ready ? 1 : 0,
+          transform: ready
+            ? 'rotateX(0deg) translateY(0px)'
+            : `rotateX(${20 + (index % 3) * 8}deg) translateY(${30 + (index % 4) * 10}px)`,
+          transition: `opacity ${0.7 + (index % 3) * 0.15}s ${EASE} ${index * 0.07}s, transform ${0.7 + (index % 3) * 0.15}s ${EASE} ${index * 0.07}s`,
+        }}
+      >
+        {thumbnail ? (
+          <TiltCard
+            src={thumbnail}
+            alt={title}
+            variant="grounded"
+            perspective={perspective}
+            className="w-full h-full rounded-[4px] border border-fg-04"
+          >
+            {drawer}
+          </TiltCard>
+        ) : (
+          <div className="relative w-full h-full rounded-[4px] border border-fg-04 overflow-hidden">
+            <AssetPlaceholder category="work" name={title} aspectRatio="auto" className="w-full h-full" />
+            {drawer}
+          </div>
+        )}
+      </div>
+    </a>
+  )
+}

package/src/organisms/WorkViewToggle.jsx

@@ -0,0 +1,170 @@
+import { useEffect, useRef, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-loader'
+
+/* taxonomy-ok: composites a segmented toggle + an inline search into one
+ * space-trading control (organism); nests kol-loader's Icon (infrastructure). */
+
+const CUBIC_EASE = 'cubic-bezier(0.16, 1, 0.3, 1)'
+/* The pill uses a springier overshoot ease, distinct from CUBIC_EASE. */
+const PILL_EASE = 'cubic-bezier(0.34, 1.2, 0.64, 1)'
+
+/**
+ * WorkViewToggle — the `/work` header control: a pill-shaped segmented
+ * **Shelf ⟷ List** view switch with a sliding-pill highlight, beside an
+ * expandable inline search. Resting: the two-option toggle + a collapsed
+ * search icon-button. Opening search collapses the toggle to zero width (fades
+ * out) and expands the field to full width, revealing a round close button on
+ * the left — the three siblings trade horizontal space via animated
+ * width/margin/opacity.
+ *
+ * Its own component, not a variant of DS ViewToggle / SegmentedToggle: the
+ * animated sliding pill, the expanding active-option icon, and the embedded
+ * search choreography are materially different. All animated numerics are
+ * inline `style` (width/left/margin/opacity + the two eases).
+ *
+ * Controlled seam replacing the app's WorkViewContext: `view`/`onView` +
+ * `query`/`onQuery`. `searchOpen` is internal state (open on the search icon,
+ * close on the × / Escape); closing clears the controlled query via
+ * `onQuery('')`. No router, no context.
+ *
+ * Text casing: labels are authored data (`shelfLabel`/`listLabel`), no
+ * text-transform.
+ *
+ * @param {string}   view        'shelf' | 'list' — active view; positions the pill + swaps icon/color
+ * @param {Function} onView      (mode) => void — fires on Shelf/List click
+ * @param {string}   query       controlled search value (default '')
+ * @param {Function} onQuery     (value) => void — fires on input change; called with '' on close
+ * @param {string}   shelfLabel  first option label (default 'Shelf')
+ * @param {string}   listLabel   second option label (default 'List')
+ * @param {string}   shelfIcon   first option icon name (default 'library')
+ * @param {string}   listIcon    second option icon name (default 'list')
+ * @param {string}   placeholder search input placeholder (default '')
+ * @param {string}   className   extra classes on the root
+ */
+export default function WorkViewToggle({
+  view = 'shelf',
+  onView,
+  query = '',
+  onQuery,
+  shelfLabel = 'Shelf',
+  listLabel = 'List',
+  shelfIcon = 'library',
+  listIcon = 'list',
+  placeholder = '',
+  className = '',
+}) {
+  const [open, setOpen] = useState(false)
+  const inputRef = useRef(null)
+
+  useEffect(() => {
+    if (open) inputRef.current?.focus()
+  }, [open])
+
+  const closeSearch = () => {
+    setOpen(false)
+    onQuery?.('')
+  }
+
+  const isShelf = view === 'shelf'
+  const isList = view === 'list'
+
+  const collapse = `width 600ms ${CUBIC_EASE}, margin 600ms ${CUBIC_EASE}, opacity 300ms ${CUBIC_EASE}`
+  const inactiveColor = 'color-mix(in srgb, var(--kol-surface-on-primary) 80%, transparent)'
+
+  const optionIcon = (name, on) => (
+    <span
+      className="inline-flex overflow-hidden flex-shrink-0"
+      style={{ width: on ? 20 : 0, marginRight: on ? 8 : 0, opacity: on ? 1 : 0, transition: collapse }}
+    >
+      <Icon name={name} size={20} />
+    </span>
+  )
+
+  return (
+    <div className={`flex items-center ${className}`.trim()}>
+      {/* Close button — appears when search is open */}
+      <span
+        className="inline-flex overflow-hidden flex-shrink-0"
+        style={{ width: open ? 36 : 0, marginRight: open ? 12 : 0, opacity: open ? 1 : 0, transition: collapse }}
+      >
+        <button
+          type="button"
+          className="flex items-center justify-center w-9 h-9 rounded-full bg-fg-96 transition-colors hover:bg-fg-88"
+          style={{ color: 'var(--kol-surface-primary)' }}
+          onClick={closeSearch}
+          aria-label="Close search"
+        >
+          <Icon name="cross" size={20} />
+        </button>
+      </span>
+
+      {/* Toggle — collapses when search is open */}
+      <div
+        className="relative flex items-center rounded-full bg-fg-04 h-9 overflow-hidden"
+        style={{ width: open ? 0 : 176, marginRight: open ? 0 : 12, opacity: open ? 0 : 1, transition: collapse }}
+      >
+        <div
+          className="absolute top-0 h-9 rounded-full bg-fg-96"
+          style={{ width: 96, left: isShelf ? 0 : 80, transition: `left 600ms ${PILL_EASE}` }}
+        />
+
+        <button
+          type="button"
+          className="relative z-10 flex items-center justify-center rounded-full h-9 kol-helper-14 transition-colors duration-300"
+          style={{
+            width: 96,
+            letterSpacing: 0,
+            color: isShelf ? 'var(--kol-surface-primary)' : inactiveColor,
+            paddingRight: isShelf ? undefined : 8,
+          }}
+          onClick={() => onView?.('shelf')}
+          aria-pressed={isShelf}
+        >
+          {optionIcon(shelfIcon, isShelf)}
+          {shelfLabel}
+        </button>
+        <button
+          type="button"
+          className="relative z-10 flex items-center justify-center rounded-full h-9 -ml-4 kol-helper-14 transition-colors duration-300"
+          style={{
+            width: 96,
+            letterSpacing: 0,
+            color: isList ? 'var(--kol-surface-primary)' : inactiveColor,
+            paddingLeft: isList ? undefined : 8,
+          }}
+          onClick={() => onView?.('list')}
+          aria-pressed={isList}
+        >
+          {optionIcon(listIcon, isList)}
+          {listLabel}
+        </button>
+      </div>
+
+      {/* Search — icon button expands to a search field */}
+      <div
+        className="flex items-center bg-fg-04 rounded-full h-9"
+        style={{ width: open ? 280 : 36, transition: `width 600ms ${CUBIC_EASE}` }}
+      >
+        <button
+          type="button"
+          className={`flex items-center justify-center w-9 h-9 rounded-full text-auto flex-shrink-0 border border-transparent ${open ? '' : 'transition-colors hover:border-fg-12'}`}
+          onClick={() => !open && setOpen(true)}
+          aria-label="Search projects"
+        >
+          <Icon name="search" size={16} className="text-fg-80" />
+        </button>
+        {open && (
+          <input
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(e) => onQuery?.(e.target.value)}
+            placeholder={placeholder}
+            className="bg-transparent outline-none kol-helper-14 flex-1 text-fg-80 caret-current pr-4 min-w-0"
+            onKeyDown={(e) => { if (e.key === 'Escape') closeSearch() }}
+          />
+        )}
+      </div>
+    </div>
+  )
+}