@kolkrabbi/kol-component 0.1.2 → 0.3.0

package/src/molecules/FramedMediaBand.jsx

@@ -0,0 +1,56 @@
+import Image from './Image'
+
+/**
+ * FramedMediaBand — full-width media breather band: a centered, aspect-locked
+ * frame (bordered surface-secondary panel, rounded) holding one object-cover
+ * image. Extracted from the foundry TypefacePage, where it sat inlined 5x
+ * verbatim between content sections. The double radius (`rounded` panel,
+ * `rounded-[4px]` image) is intentional — the image nests inside the border.
+ *
+ * Presentational — the caller passes finished `src`/`srcSet` strings; any
+ * CDN size-ladder generation stays at the call site. `media` swaps an
+ * arbitrary node into the frame in place of the Image (video, canvas); it
+ * should self-size with `w-full h-full`.
+ *
+ * @param {string}    src         image src (a finished URL, no ladder logic here)
+ * @param {string}    srcSet      responsive srcSet, precomputed by the caller
+ * @param {string}    sizes       img sizes attr
+ * @param {string}    alt         alt text, authored at the call site
+ * @param {ReactNode} media       replaces the Image inside the frame
+ * @param {ReactNode} caption     optional caption line under the frame
+ * @param {string}    aspectRatio frame aspect ratio, CSS value (e.g. '2/1')
+ * @param {string}    maxWidth    frame max-width class
+ * @param {string}    className   section-level extras (e.g. 'mt-12')
+ */
+export default function FramedMediaBand({
+  src,
+  srcSet,
+  sizes = '(max-width: 1400px) 100vw, 1400px',
+  alt = '',
+  media,
+  caption,
+  aspectRatio = '2/1',
+  maxWidth = 'max-w-[1400px]',
+  className = '',
+}) {
+  return (
+    <section className={`w-full overflow-hidden py-16 ${className}`.trim()}>
+      <div className={`${maxWidth} mx-auto`}>
+        <div style={{ aspectRatio }}>
+          <div className="w-full h-full bg-surface-secondary rounded border border-fg-08">
+            {media ?? (
+              <Image
+                src={src}
+                srcSet={srcSet}
+                sizes={sizes}
+                alt={alt}
+                className="w-full h-full object-cover rounded-[4px]"
+              />
+            )}
+          </div>
+        </div>
+        {caption && <p className="kol-mono-12 text-fg-48 mt-3">{caption}</p>}
+      </div>
+    </section>
+  )
+}

package/src/{primitives → molecules}/Image.jsx

@@ -6,7 +6,7 @@
  * visible at its intended size (aspect-ratio preserved).
  */
 import { useState } from 'react'
-import AssetPlaceholder from './AssetPlaceholder'
+import AssetPlaceholder from '../atoms/AssetPlaceholder'
 
 export default function Image({
   src,

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/MediaCard.jsx

@@ -0,0 +1,97 @@
+import { Icon } from '@kolkrabbi/kol-loader'
+
+/* taxonomy-ok: nests kol-loader's Icon (a package import the relative-import
+ * check can't see) plus the same-file SelectIndicator. */
+
+/**
+ * SelectIndicator — passive square check indicator for multi-select rows and
+ * cards. `on` = checked. Deliberately NOT ToggleCheckbox: that is a labeled
+ * form control with a real <input>, which double-fires inside a click-target
+ * card and misleads assistive tech — here the CARD is the toggle, this is
+ * only its visual state. Inline CSS vars because `bg-fg-default` isn't a
+ * generated Tailwind utility; the checked fill reads from
+ * `--kol-surface-on-primary` (solid fg, theme-correct).
+ *
+ * Shared by MediaCard and MediaRow; not exported from the package barrel.
+ */
+export function SelectIndicator({ on = false }) {
+  return (
+    <span
+      className="w-4 h-4 shrink-0 rounded-sm border flex items-center justify-center transition-colors"
+      style={
+        on
+          ? { background: 'var(--kol-surface-on-primary)', borderColor: 'var(--kol-surface-on-primary)' }
+          : { background: 'var(--kol-fg-absolute-16, rgba(0,0,0,0.15))', borderColor: 'var(--kol-fg-absolute-48, rgba(0,0,0,0.4))' }
+      }
+      aria-hidden="true"
+    >
+      {on && <Icon name="check" size={11} style={{ color: 'var(--kol-surface-primary)' }} />}
+    </span>
+  )
+}
+
+/**
+ * MediaCard — grid tile for one media object: square thumbnail with a
+ * top-right download overlay (or a top-left select checkbox in select mode),
+ * then name / meta / actions stacked below. The grid-view counterpart to
+ * MediaRow (same slot contract).
+ *
+ * Presentational — the parent supplies rendered slots; no media loading,
+ * fetch, or rename logic lives here. Grid track sizing belongs to the parent
+ * list; the card just fills its cell.
+ *
+ * @param {ReactNode} thumb        square thumbnail (image/video/placeholder)
+ * @param {ReactNode} name         name cell (plain text or an inline editor)
+ * @param {string}    meta         one-line secondary text (e.g. "1.2 MB · 2026-06-19")
+ * @param {ReactNode} actions      row of action buttons (hidden in select mode)
+ * @param {string}    downloadHref href for the overlay download button (omit to hide)
+ * @param {boolean}   selectMode   selection mode on → checkbox replaces download, whole card toggles
+ * @param {boolean}   selected     this card is selected (stronger border + checked box)
+ * @param {Function}  onSelect     (event) => void — card click in select mode; gets shiftKey for range
+ */
+export default function MediaCard({
+  thumb,
+  name,
+  meta,
+  actions,
+  downloadHref,
+  selectMode = false,
+  selected = false,
+  onSelect,
+}) {
+  return (
+    <li
+      onClick={selectMode ? onSelect : undefined}
+      className={`flex flex-col rounded overflow-hidden border bg-fg-02 ${selectMode ? 'cursor-pointer select-none' : ''}`}
+      style={{ borderColor: selected ? 'var(--kol-fg-64)' : 'var(--kol-fg-12)' }}
+    >
+      <div className="aspect-square relative">
+        {thumb}
+        {selectMode ? (
+          <span
+            className="absolute top-3 left-3 rounded p-1"
+            style={{ background: 'var(--kol-fg-absolute-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
+          >
+            <SelectIndicator on={selected} />
+          </span>
+        ) : downloadHref ? (
+          <a
+            href={downloadHref}
+            aria-label="Download"
+            title="Download"
+            className="absolute top-3 right-3 inline-flex items-center justify-center w-8 h-8 rounded text-emphasis hover:bg-fg-absolute-24 transition-colors"
+            style={{ background: 'var(--kol-fg-absolute-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
+            onClick={(e) => e.stopPropagation()}
+          >
+            <Icon name="download" size={16} />
+          </a>
+        ) : null}
+      </div>
+      <div className="p-3 flex flex-col gap-2">
+        {name}
+        <p className="kol-mono-12 text-fg-48">{meta}</p>
+        {!selectMode && actions}
+      </div>
+    </li>
+  )
+}

package/src/molecules/MediaRow.jsx

@@ -0,0 +1,49 @@
+import { SelectIndicator } from './MediaCard.jsx'
+
+/**
+ * MediaRow — list row for one media object: optional select checkbox, small
+ * thumbnail, name (flex), fixed-width date + size columns, then actions.
+ * The list-view counterpart to MediaCard (same slot contract).
+ *
+ * Presentational — the parent supplies rendered slots; interaction outside
+ * select mode lives in the thumb / name / actions slots. Column widths are
+ * consumer-tunable via `dateWidth` / `sizeWidth`.
+ *
+ * @param {ReactNode} thumb       small thumbnail (48px square)
+ * @param {ReactNode} name        name cell (plain text or an inline editor)
+ * @param {string}    date        right-aligned date column
+ * @param {string}    size        right-aligned size column
+ * @param {ReactNode} actions     row of action buttons (hidden in select mode)
+ * @param {string}    dateWidth   Tailwind width class for the date column
+ * @param {string}    sizeWidth   Tailwind width class for the size column
+ * @param {boolean}   selectMode  selection mode on → checkbox shown, whole row toggles, actions hidden
+ * @param {boolean}   selected    this row is selected (highlight + checked box)
+ * @param {Function}  onSelect    (event) => void — row click in select mode; gets shiftKey for range
+ */
+export default function MediaRow({
+  thumb,
+  name,
+  date,
+  size,
+  actions,
+  dateWidth = 'w-24',
+  sizeWidth = 'w-20',
+  selectMode = false,
+  selected = false,
+  onSelect,
+}) {
+  return (
+    <li
+      onClick={selectMode ? onSelect : undefined}
+      className={`flex items-center gap-3 py-2 border-b ${selectMode ? 'cursor-pointer select-none' : ''} ${selected ? 'bg-fg-08' : ''}`}
+      style={{ borderColor: 'var(--kol-fg-08)' }}
+    >
+      {selectMode && <SelectIndicator on={selected} />}
+      <div className="w-12 h-12 shrink-0 rounded overflow-hidden">{thumb}</div>
+      <div className="flex-1 min-w-0">{name}</div>
+      <p className={`kol-mono-12 text-fg-32 shrink-0 text-right ${dateWidth}`}>{date}</p>
+      <p className={`kol-mono-12 text-fg-48 shrink-0 text-right ${sizeWidth}`}>{size}</p>
+      {!selectMode && <div className="shrink-0">{actions}</div>}
+    </li>
+  )
+}

package/src/molecules/MenuItem.jsx

@@ -1,6 +1,6 @@
 import { useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-loader'
-import { PopoverPanel, usePopover } from './Popover.jsx'
+import { PopoverPanel, usePopover } from '../atoms/Popover.jsx'
 
 /**
  * MenuItem — top-level menu entry. Trigger button + popover panel.
@@ -26,8 +26,9 @@ export function MenuItem({
   panelClassName = '',
   panelStyle,
   buttonClassName = '',
+  defaultOpen = false,
 }) {
-  const [open, setOpen] = useState(false)
+  const [open, setOpen] = useState(defaultOpen)
   const popover = usePopover({
     open,
     onOpenChange: setOpen,

package/src/molecules/MenuPopover.jsx

@@ -1,103 +1,18 @@
-import { useEffect, useRef, useState } from 'react'
+import { MenuItem as MenuTrigger } from './MenuItem.jsx'
 
 /**
- * MenuPopover — generic action-menu / popover primitive.
+ * MenuPopover — DEPRECATED alias of MenuItem (2026-07-02 menu-family
+ * unification).
  *
- *   <MenuPopover label="File">
- *     <MenuItem onClick={…}>Save</MenuItem>
- *     <MenuItem onClick={…}>Export…</MenuItem>
- *   </MenuPopover>
- *
- * Opens on click, closes on outside-click + Escape, anchors to the trigger
- * via getBoundingClientRect + position:fixed so it escapes overflow:auto
- * clipping. Pass `panelClassName` to size the panel (e.g. wider for
- * Templates).
- *
- * For value-list selection (single value, active state) use `Dropdown`
- * instead — this primitive is for action menus / popover panels that
- * hold arbitrary children.
+ * The two triggers had an identical API (label, children incl. ({ close })
+ * render-prop, align, panelClassName, panelStyle, buttonClassName,
+ * defaultOpen) and did the same job — MenuPopover with hand-rolled
+ * fixed positioning, MenuItem on floating-ui (portal, auto-flip, focus
+ * management). One implementation now: MenuItem. This alias keeps existing
+ * call-sites working; migrate imports to MenuItem. Removal in the next major.
  */
-export function MenuPopover({
-  label,
-  children,
-  align = 'start',
-  panelClassName = '',
-  panelStyle,
-  buttonClassName = '',
-}) {
-  const [open, setOpen] = useState(false)
-  const wrapRef   = useRef(null)
-  const buttonRef = useRef(null)
-  const [panelPos, setPanelPos] = useState(null)
-
-  useEffect(() => {
-    if (!open) return
-    const onDown = (e) => {
-      if (!wrapRef.current?.contains(e.target)) setOpen(false)
-    }
-    const onKey = (e) => { if (e.key === 'Escape') setOpen(false) }
-    document.addEventListener('mousedown', onDown)
-    document.addEventListener('keydown',   onKey)
-    return () => {
-      document.removeEventListener('mousedown', onDown)
-      document.removeEventListener('keydown',   onKey)
-    }
-  }, [open])
-
-  useEffect(() => {
-    if (!open) { setPanelPos(null); return }
-    const update = () => {
-      const rect = buttonRef.current?.getBoundingClientRect()
-      if (!rect) return
-      setPanelPos({ top: rect.bottom + 4, left: rect.left, right: rect.right })
-    }
-    update()
-    window.addEventListener('resize', update)
-    window.addEventListener('scroll', update, true)
-    return () => {
-      window.removeEventListener('resize', update)
-      window.removeEventListener('scroll', update, true)
-    }
-  }, [open])
-
-  const close = () => setOpen(false)
-
-  const positioned = panelPos && (
-    align === 'end'
-      ? { top: panelPos.top, right: window.innerWidth - panelPos.right }
-      : { top: panelPos.top, left: panelPos.left }
-  )
-
-  return (
-    <div ref={wrapRef} className="relative inline-block">
-      <button
-        ref={buttonRef}
-        type="button"
-        onClick={() => setOpen((v) => !v)}
-        aria-haspopup="menu"
-        aria-expanded={open}
-        className={`kol-helper-12 px-3 h-8 inline-flex items-center gap-1 rounded text-meta hover:text-emphasis transition-colors ${buttonClassName}`}
-      >
-        <span>{label}</span>
-        <svg width="10" height="10" viewBox="0 0 12 12" aria-hidden="true">
-          <path d="m3 5 3 3 3-3" stroke="currentColor" strokeWidth="1.25" strokeLinecap="round" strokeLinejoin="round" fill="none" />
-        </svg>
-      </button>
-      {open && positioned && (
-        <div
-          role="menu"
-          className={`fixed z-[1000] bg-surface-primary border border-fg-08 rounded shadow-lg ${panelClassName}`}
-          style={{ ...positioned, ...panelStyle }}
-          onClick={(e) => {
-            /* close on item click — items inside fire their handler then bubble. */
-            if (e.target.closest('[data-menu-item]')) close()
-          }}
-        >
-          {typeof children === 'function' ? children({ close }) : children}
-        </div>
-      )}
-    </div>
-  )
+export function MenuPopover(props) {
+  return <MenuTrigger {...props} />
 }
 
 /**

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