@kolkrabbi/kol-component 0.21.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.21.0",
+  "version": "0.25.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -24,7 +24,7 @@
     "@floating-ui/react": "^0.27.19",
     "embla-carousel-react": "^8.6.0",
     "react-syntax-highlighter": "^16.1.1",
-    "@kolkrabbi/kol-icons": "0.8.11"
+    "@kolkrabbi/kol-icons": "0.10.0"
   },
   "peerDependencies": {
     "framer-motion": "^12.0.0",

package/src/atoms/Button.jsx

@@ -11,7 +11,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *
  * @param {Object} props
  * @param {ReactNode} props.children - Button content
- * @param {'primary'|'secondary'|'accent'|'outline'|'ghost'|'danger'|'grey'|'control'} props.variant - Visual variant. `danger` is the destructive treatment (--ui-error fill); `control` is an alias for `ghost` (legacy call-sites).
+ * @param {'primary'|'secondary'|'accent'|'outline'|'ghost'|'nav'|'danger'|'grey'|'control'} props.variant - Visual variant. `danger` is the destructive treatment (--ui-error fill); `nav` is the chrome rung — transparent, oq-64 ink, one step brighter than `ghost`; `control` is an alias for `ghost` (legacy call-sites).
  * @param {'sm'|'md'|'lg'} props.size - Button size (default: 'md')
  * @param {string} props.iconLeft - Icon name to display on the left
  * @param {string} props.iconRight - Icon name to display on the right
@@ -82,6 +82,14 @@ const Button = ({
     ? 'kol-btn-danger'
     : resolvedVariant === 'grey'
     ? 'kol-btn-grey'
+    /* `nav` — transparent box, oq-64 ink (2026-08-01). The class had lived in
+     * the theme since the shell landed with NO component able to emit it, so
+     * every consumer that wanted this exact weight hand-wrote the box instead:
+     * that orphan is the direct cause of the four-container header. It is the
+     * chrome rung — one step brighter than `ghost` at oq-48 — and it is what
+     * `text-fg-64` meant every time a call site typed it. */
+    : resolvedVariant === 'nav'
+    ? 'kol-btn-nav'
     : 'kol-btn-secondary'
 
   // Add size class — pairs the padding rule with its mono type class.

package/src/atoms/IconFrame.jsx

@@ -36,8 +36,27 @@ import { SOLO } from '../hooks/glyphLadders.js'
  * moves with it — that is the 2026-07-28 law, and it only means something if the
  * two are separable.
  *
- * Deliberately absent: `onClick`, `href`, `disabled`, `aria-pressed`, `title`.
- * Wanting any of those means wanting a `Button` with `iconOnly`, not this.
+ * IT TAKES A CLICK (2026-08-01 ruling) — *"you dont use a button… you use the
+ * ICON COMPONENT… it has no interactive states."* This file used to say the
+ * opposite, and called it "the entire point": no `onClick`, no `href`, and
+ * *"wanting any of those means wanting a Button with iconOnly, not this."*
+ *
+ * That was one sentence too strong. Two separate things had been welded
+ * together — **is it clickable** and **does it light up** — and only the second
+ * was ever the point. The shell header proved it: six chrome controls all
+ * needing a click, none wanting a hover wash, so every one of them hand-wrote
+ * its own box and the row ended up on four different containers.
+ *
+ * So `onClick` renders a `<button>`, `href` renders an `<a>`, and neither
+ * gains a state rule. The UA's own button chrome is reset in the theme
+ * (`button.kol-icon-frame, a.kol-icon-frame`) so "no states" is a property of
+ * the CLASS rather than of the tag — which is exactly the correction this
+ * component's own docstring already argued for when it refused to borrow
+ * `kol-btn-*` on a span.
+ *
+ * Still deliberately absent: `disabled` and `aria-pressed`. Both describe a
+ * control that CHANGES appearance with state, which is the line that stays.
+ * Want the wash, the pressed fill or the disabled dim? That is `Button`.
  *
  * @param {string} name       icon name (kol-icons)
  * @param {string} variant    primary|secondary|accent|outline|ghost|nav|grey|danger
@@ -62,18 +81,39 @@ export default function IconFrame({
   size = 'md',
   radius = 'sm',
   iconSize = null,
+  onClick,
+  href,
   className = '',
   ...rest
 }) {
   if (!name) return null
   const radiusCls = radius === 'full' ? ' kol-icon-frame-radius-full' : ''
   const resolvedIconSize = iconSize ?? GLYPH[size] ?? GLYPH.md
+  const cls = `kol-icon-frame kol-icon-frame-${variant} kol-icon-frame-${size}${radiusCls} ${className}`.trim()
+  const glyph = <Icon name={name} size={resolvedIconSize} />
+
+  /* The element follows the affordance, and the CLASS is identical in all three
+   * branches — that is the whole contract. A frame that can be clicked must be
+   * a real button or a real link (keyboard, focus order, middle-click, screen
+   * readers); a frame that cannot must not be either, or it lands in the tab
+   * order announcing itself as something to press. */
+  if (href) {
+    return (
+      <a className={cls} href={href} {...rest}>
+        {glyph}
+      </a>
+    )
+  }
+  if (onClick) {
+    return (
+      <button type="button" className={cls} onClick={onClick} {...rest}>
+        {glyph}
+      </button>
+    )
+  }
   return (
-    <span
-      className={`kol-icon-frame kol-icon-frame-${variant} kol-icon-frame-${size}${radiusCls} ${className}`.trim()}
-      {...rest}
-    >
-      <Icon name={name} size={resolvedIconSize} />
+    <span className={cls} {...rest}>
+      {glyph}
     </span>
   )
 }

package/src/hooks/useScrollSpy.js

@@ -29,8 +29,15 @@ export default function useScrollSpy(ids, { rootMargin = '-30% 0px -60% 0px', ed
       const atTop = top < edgeOffset
       const atBottom = top + viewH >= fullH - edgeOffset * 0.8
       if (atTop) {
+        /* THE FIRST HEADING, not null (user ruling 2026-08-01): *"at any given
+         * time you are at some place in the file, THAT LOCATION SHOULD
+         * HIGHLIGHT"*. The top lock used to clear the active id, so the rail
+         * highlighted nothing at rest — and a page opens at rest, which made
+         * "no active row" the state the reader saw first and most. The bottom
+         * lock has always activated the LAST id; this is that rule, both ends.
+         * You are at the top of the document, so you are in its first section. */
         edgeLockRef.current = 'top'
-        setActiveId(null)
+        setActiveId(ids[0])
       } else if (atBottom) {
         edgeLockRef.current = 'bottom'
         setActiveId(ids[ids.length - 1])

package/src/index.js

@@ -71,6 +71,7 @@ export { default as ColorInputRow } from './molecules/ColorInputRow.jsx'
 export { default as ColorRamp } from './molecules/ColorRamp.jsx'
 export { default as ColorSwatch } from './molecules/ColorSwatch.jsx'
 export { default as Dropdown } from './molecules/Dropdown.jsx'
+export { default as FieldRow, StatusChip } from './molecules/FieldRow.jsx'
 export { default as FramedMediaBand } from './molecules/FramedMediaBand.jsx'
 export { default as Image } from './molecules/Image.jsx'
 export { default as MediaCard } from './molecules/MediaCard.jsx'
@@ -113,6 +114,7 @@ export { default as MediaLibrary, MediaLibraryProvider, useMediaLibrary, MediaPi
 export { default as MediaTileGallery } from './organisms/MediaTileGallery.jsx'
 export { default as MediaViewer } from './organisms/MediaViewer.jsx'
 export { default as NewsletterBand } from './organisms/NewsletterBand.jsx'
+export { default as RecordManager } from './organisms/RecordManager.jsx'
 export { default as SpectrumGrid } from './organisms/SpectrumGrid.jsx'
 export { default as Table } from './organisms/Table.jsx'
 
@@ -123,6 +125,14 @@ export { Icon } from '@kolkrabbi/kol-icons'
 export { default as Graphic, GRAPHICS } from './graphics/Graphic.jsx'
 export { GRAPHIC_RAW } from './graphics/graphicData.js'
 
+/* The glyph ladders, exported 2026-08-01. They were internal, so anything
+ * OUTSIDE this package that pairs an icon with a label had to hardcode a
+ * number — the shell header's tabs took `size={14}`, foundry's section header
+ * took `20`, and neither could reference the rule it was meant to follow.
+ * Cross-package imports go through the `@kolkrabbi/*` specifier (ARCHITECTURE
+ * §3), so an export is the only way another package can obey the ladder. */
+export { SOLO, ADJACENT, glyphSize } from './hooks/glyphLadders.js'
+
 // hooks
 export { default as usePrefersReducedMotion } from './hooks/usePrefersReducedMotion.js'
 export { default as useReveal } from './hooks/useReveal.js'

package/src/molecules/CodeBlock.jsx

@@ -19,6 +19,14 @@ import { Icon } from '@kolkrabbi/kol-icons'
  *   • Portable Text: `value={{ code, language, filename }}`
  *   • Direct props: `code` / `language` / `filename`
  *   • Children: `<CodeBlock language="js">{'…'}</CodeBlock>`
+ *
+ * `language` falls back to `'text'`, and a `'text'` block draws NO chip — so a
+ * fence that declares nothing renders as an unlabelled slab. That fallback is
+ * kept (a chip reading "text" is worse than none) and the fix is upstream:
+ * every fence declares a language, enforced by `pnpm validate:fences`.
+ *
+ * @param {string} [size='md']  'sm' | 'md' — the box and the type step together.
+ * @param {boolean} [bare]      drop the FRAME; the host owns it. Not a size.
  */
 
 const CheckMarkIcon = () => (
@@ -65,7 +73,13 @@ const syntaxTheme = (foregroundToken = 80) => ({
 /* `bare` (2026-07-30): highlight + chip + copy WITHOUT the framed chrome — for
  * hosts that already own the frame (PreviewCard's Code tab sat a full
  * CodeBlock frame inside the kol-doc-figure border: frame-in-frame). */
-export default function CodeBlock({ children, code: codeProp, language: languageProp, filename: filenameProp, value, bare = false }) {
+/* `size` (2026-08-01, user ruling). The block had no size at all — its padding
+ * and type size sat in `.kol-codeblock` as unnamed constants, so *"its just
+ * whatever its defaulting to"* was literally true and no call site could ask
+ * for anything else. `md` is those exact values, named; `sm` is one step down
+ * on both axes. Size is INDEPENDENT of `bare`: bare removes the frame, size
+ * sets the box, and a bare block still has one. */
+export default function CodeBlock({ children, code: codeProp, language: languageProp, filename: filenameProp, value, bare = false, size = 'md' }) {
   const [copied, setCopied] = useState(false)
 
   const code = String(value?.code ?? codeProp ?? children ?? '')
@@ -84,7 +98,7 @@ export default function CodeBlock({ children, code: codeProp, language: language
 
   return (
     <div className={bare ? '' : 'kol-codeblock-wrapper'}>
-      <div className={`kol-codeblock${bare ? ' kol-codeblock--bare' : ''}`}>
+      <div className={`kol-codeblock kol-codeblock--${size}${bare ? ' kol-codeblock--bare' : ''}`}>
         {(filename || (language && language !== 'text')) && (
           <div className="kol-codeblock-filename">{filename || language}</div>
         )}

package/src/molecules/FieldRow.jsx

@@ -0,0 +1,145 @@
+import { useState } from 'react'
+import Input from '../atoms/Input'
+import Tag from '../atoms/Tag'
+import Button from '../atoms/Button'
+import { usePopover, PopoverPanel } from '../atoms/Popover'
+import Dropdown from './Dropdown'
+
+/**
+ * FieldRow — one labeled field row in a record surface (lobby: RecordManager).
+ * Label column left, control right; `type` picks the control:
+ *
+ *   text   → Input, with an optional hint line under it (the slug's derived URL)
+ *   status → StatusChip — interactive Tag opening a listbox in place
+ *   select → Dropdown
+ *   media  → thumbnail + hover-reveal remove ×; empty state offers onPick
+ *   file   → filename as a removable Tag (chip taxonomy: interactive → Tag);
+ *            empty state offers onPick
+ *
+ * All labels, option strings and values are authored at the call site — this
+ * component bakes no copy and transforms no casing. Media/file `value` is
+ * whatever object the consumer's picker returns; FieldRow reads only
+ * `.thumb`/`.url` for the image and `.name` for the token, and hands the whole
+ * object back through onChange untouched.
+ */
+
+/* StatusChip — the interactive status control ("Live ▾" in the reference).
+ * Chip taxonomy (Tag source, 2026-07-30): interactive → Tag, never Pill. The
+ * menu is usePopover/PopoverPanel — the same primitive Dropdown builds on —
+ * with click handled by the Tag itself (click: false here) so the chip stays
+ * the only trigger. Shared by FieldRow and RecordManager's status column. */
+export function StatusChip({ value, options = [], onChange, size = 'sm' }) {
+  const [open, setOpen] = useState(false)
+  const popover = usePopover({
+    open,
+    onOpenChange: setOpen,
+    placement: 'bottom-start',
+    click: false,
+    role: 'listbox',
+  })
+  return (
+    <>
+      <span ref={popover.refs.setReference} {...popover.getReferenceProps()} className="inline-flex">
+        <Tag variant="primary" size={size} hash={false} active={open} onClick={() => setOpen((o) => !o)}>
+          {value}
+        </Tag>
+      </span>
+      <PopoverPanel popover={popover}>
+        <ul className="flex flex-col p-1 m-0 list-none">
+          {options.map((opt) => {
+            const label = typeof opt === 'object' ? opt.label : opt
+            const val = typeof opt === 'object' ? opt.value : opt
+            return (
+              <li key={val}>
+                <button
+                  type="button"
+                  role="option"
+                  aria-selected={val === value}
+                  className={`kol-helper-12 w-full text-left px-3 py-2 bg-transparent border-0 cursor-pointer rounded-sm hover:bg-fg-08 ${val === value ? 'text-emphasis' : 'text-body'}`}
+                  onClick={() => {
+                    onChange?.(val)
+                    setOpen(false)
+                  }}
+                >
+                  {label}
+                </button>
+              </li>
+            )
+          })}
+        </ul>
+      </PopoverPanel>
+    </>
+  )
+}
+
+/* Media/file thumbnail — same small fixed-aspect rounded treatment as
+ * MediaRow's thumb cell. */
+const THUMB_CLS = 'h-10 w-14 rounded object-cover bg-fg-04'
+
+export default function FieldRow({
+  label,
+  type = 'text',
+  value,
+  onChange,
+  options = [],
+  hint,
+  onPick,
+  placeholder,
+  disabled = false,
+}) {
+  const empty = onPick ? (
+    <Button variant="nav" size="sm" iconOnly="plus" iconSize={12} onClick={onPick} aria-label={label} disabled={disabled} />
+  ) : (
+    <span className="kol-helper-10 text-meta">—</span>
+  )
+
+  let control = null
+  if (type === 'text') {
+    control = (
+      <Input
+        value={value ?? ''}
+        onChange={(e) => onChange?.(e?.target ? e.target.value : e)}
+        placeholder={placeholder}
+        disabled={disabled}
+        className="w-full"
+      />
+    )
+  } else if (type === 'status') {
+    control = <StatusChip value={value} options={options} onChange={onChange} />
+  } else if (type === 'select') {
+    control = <Dropdown options={options} value={value} onChange={onChange} />
+  } else if (type === 'media') {
+    control = value ? (
+      <span className="group relative inline-flex">
+        <img src={value.thumb ?? value.url} alt={value.name ?? ''} className={THUMB_CLS} />
+        {onChange && (
+          <Button
+            variant="nav"
+            size="sm"
+            iconOnly="x"
+            iconSize={10}
+            aria-label={label}
+            className="absolute -top-2 -right-2 opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
+            onClick={() => onChange(null)}
+          />
+        )}
+      </span>
+    ) : empty
+  } else if (type === 'file') {
+    control = value ? (
+      <Tag variant="secondary" size="sm" hash={false} onRemove={onChange ? () => onChange(null) : undefined}>
+        {value.name ?? value}
+      </Tag>
+    ) : empty
+  }
+
+  return (
+    <div className="grid grid-cols-[minmax(0,10rem)_minmax(0,1fr)] items-center gap-x-6 py-3 border-b border-fg-08">
+      <div className="kol-mono-12 text-body">{label}</div>
+      <div className="min-w-0">{control}</div>
+      {hint != null && (
+        <div className="col-start-2 kol-helper-10 text-meta pt-1 truncate">{hint}</div>
+      )}
+    </div>
+  )
+}

package/src/molecules/ShellDrawer.jsx

@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
-import { Icon } from '@kolkrabbi/kol-icons'
+import Button from '../atoms/Button.jsx'
 import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 
 /* taxonomy-ok: nests kol-icons's Icon (a package import the relative-import
@@ -150,14 +150,21 @@ export default function ShellDrawer({
       >
         <div className="mb-6 flex items-center gap-4">
           {header != null && <div className="min-w-0 flex-1">{header}</div>}
-          <button
-            type="button"
+          {/* The box has an owner (2026-08-01). This hand-wrote the icon-button
+            * square and its hover wash; `Button variant="nav"` IS that string.
+            * `iconSize` holds the glyph where it was — the ladder's md rung is
+            * heavier than a drawer close wants, and Button documents iconSize
+            * for exactly the cases the ladder cannot serve. The SQUARE is what
+            * needed an owner, and it now has one. */}
+          <Button
+            variant="nav"
+            size="md"
+            iconOnly="x"
+            iconSize={14}
             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="x" size={14} />
-          </button>
+            className="ml-auto shrink-0"
+          />
         </div>
         <div className="flex-1 overflow-y-auto pr-1" style={{ overflowAnchor: 'none' }}>
           {children}

package/src/organisms/RecordManager.jsx

@@ -0,0 +1,334 @@
+import { useMemo, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { Icon } from '@kolkrabbi/kol-icons'
+import Button from '../atoms/Button'
+import SearchInput from '../atoms/SearchInput'
+import ToggleCheckbox from '../atoms/ToggleCheckbox'
+import ShellDrawer from '../molecules/ShellDrawer'
+import Dropdown from '../molecules/Dropdown'
+import FieldRow, { StatusChip } from '../molecules/FieldRow'
+import Table from './Table'
+import MediaLibrary from './MediaLibrary'
+
+/**
+ * RecordManager — full-screen CMS record surface (lobby: RecordManager,
+ * reference: Framer CMS). A reorderable record table plus a slide-over detail
+ * panel of FieldRows.
+ *
+ * Composes existing DS only: Table (with rowClassName), ShellDrawer as the
+ * slide-over, FieldRow/StatusChip for the panel, MediaLibrary variant="modal"
+ * as the media picker (client INJECTED via `mediaClient`, never imported —
+ * ARCHITECTURE §3), ToggleCheckbox for row selection, SearchInput/Button for
+ * the toolbar.
+ *
+ * Columns use Table's contract (accessor/header/render/sortable…), plus an
+ * optional `type` this organism resolves before handing them down:
+ *   'title'  → truncating cell + hover-reveal open affordance (opens the panel)
+ *   'status' → StatusChip; column carries `options` + `onStatusChange(row, v)`
+ *   'select' → Dropdown;   column carries `options` + `onSelectChange(row, v)`
+ *   'thumb'  → small fixed-aspect thumbnail (row[accessor] = {thumb|url, name})
+ *
+ * Reorder is a ~50-line pointer sort (the brief's call: util before any
+ * dependency): pointerdown on the ⠿ handle, row rects measured once, live
+ * over-index on pointermove, onReorder(from, to) on release. The floating
+ * "Reorder row N" label rides the existing .kol-tooltip chrome. Handles render
+ * only when onReorder is passed.
+ *
+ * Fields follow FieldRow's contract: {key, label, type, options?, accept?,
+ * placeholder?, hint? (value or fn(record))}. The open record's values come
+ * from `value` (falling back to the row object); edits bubble through
+ * onChange(key, next) — data is consumer-owned, this surface never fetches.
+ */
+export default function RecordManager({
+  columns = [],
+  rows = [],
+  onReorder,
+  onSelectRow,
+  fields = [],
+  value,
+  onChange,
+  onAdd,
+  onSortToggle,
+  onFilterToggle,
+  query,
+  onQueryChange,
+  searchPlaceholder,
+  onSelectionChange,
+  saveState,
+  onPublish,
+  publishLabel = 'Publish',
+  onPreview,
+  onOverflow,
+  mediaClient,
+  reorderLabel = (n) => `Reorder row ${n}`,
+  className = '',
+}) {
+  const wrapRef = useRef(null)
+  const dragRef = useRef(null)
+  const [drag, setDrag] = useState(null) // { from, over, x, y } during a drag
+  const [active, setActive] = useState(null)
+  const [picker, setPicker] = useState(null) // the field being picked for
+  const [selected, setSelected] = useState(() => new Set())
+
+  const rowId = (row, i) => row.id ?? i
+
+  const openRecord = (row) => {
+    setActive(row)
+    onSelectRow?.(row)
+  }
+
+  const updateSelection = (next) => {
+    setSelected(next)
+    onSelectionChange?.([...next])
+  }
+
+  /* ── pointer sort ─────────────────────────────────────────────────────── */
+  const startDrag = (e, from) => {
+    if (!onReorder) return
+    e.preventDefault()
+    const rowEls = wrapRef.current?.querySelectorAll('.kol-table-row')
+    if (!rowEls?.length) return
+    const rects = [...rowEls].map((el) => el.getBoundingClientRect())
+    const move = (ev) => {
+      const hit = rects.findIndex((r) => ev.clientY < r.bottom)
+      const over = hit === -1 ? rects.length - 1 : hit
+      dragRef.current = { from, over, x: ev.clientX, y: ev.clientY }
+      setDrag(dragRef.current)
+    }
+    const up = () => {
+      window.removeEventListener('pointermove', move)
+      window.removeEventListener('pointerup', up)
+      document.body.style.cursor = ''
+      document.body.style.userSelect = ''
+      const d = dragRef.current
+      dragRef.current = null
+      setDrag(null)
+      if (d && d.over !== d.from) onReorder(d.from, d.over)
+    }
+    window.addEventListener('pointermove', move)
+    window.addEventListener('pointerup', up)
+    document.body.style.cursor = 'grabbing'
+    document.body.style.userSelect = 'none'
+    dragRef.current = { from, over: from, x: e.clientX, y: e.clientY }
+    setDrag(dragRef.current)
+  }
+
+  /* ── columns: resolve types, prepend handle + checkbox ────────────────── */
+  const builtColumns = useMemo(() => {
+    const resolved = columns.map((col) => {
+      if (col.type === 'title') {
+        return {
+          ...col,
+          render: (row) => (
+            <span className="inline-flex items-center gap-2 min-w-0 max-w-full">
+              <span className="truncate text-emphasis">{col.render ? col.render(row) : row[col.accessor]}</span>
+              <Button
+                variant="nav"
+                size="sm"
+                iconOnly="maximize"
+                iconSize={12}
+                aria-label={typeof col.header === 'string' ? col.header : 'Open'}
+                className="shrink-0 opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
+                onClick={() => openRecord(row)}
+              />
+            </span>
+          ),
+        }
+      }
+      if (col.type === 'status') {
+        return {
+          ...col,
+          render: (row) => (
+            <StatusChip
+              value={row[col.accessor]}
+              options={col.options ?? []}
+              onChange={(next) => col.onStatusChange?.(row, next)}
+            />
+          ),
+        }
+      }
+      if (col.type === 'select') {
+        return {
+          ...col,
+          render: (row) => (
+            <Dropdown
+              options={col.options ?? []}
+              value={row[col.accessor]}
+              onChange={(next) => col.onSelectChange?.(row, next)}
+            />
+          ),
+        }
+      }
+      if (col.type === 'thumb') {
+        return {
+          ...col,
+          render: (row) => {
+            const media = row[col.accessor]
+            return media ? (
+              <img src={media.thumb ?? media.url} alt={media.name ?? ''} className="h-10 w-14 rounded object-cover bg-fg-04" />
+            ) : (
+              <span className="kol-helper-10 text-meta">—</span>
+            )
+          },
+        }
+      }
+      return col
+    })
+
+    const prefix = []
+    if (onReorder) {
+      prefix.push({
+        accessor: '__handle',
+        header: '',
+        className: 'kol-table-cell-text w-8',
+        render: (row) => {
+          const i = rows.indexOf(row)
+          return (
+            <button
+              type="button"
+              aria-label={reorderLabel(i + 1)}
+              className="cursor-grab touch-none bg-transparent border-0 p-0 text-meta hover:text-emphasis opacity-0 group-hover:opacity-100 focus-visible:opacity-100"
+              onPointerDown={(e) => startDrag(e, i)}
+            >
+              <Icon name="resize-grip" size={14} />
+            </button>
+          )
+        },
+      })
+    }
+    prefix.push({
+      accessor: '__select',
+      header: (
+        <ToggleCheckbox
+          checked={rows.length > 0 && selected.size === rows.length}
+          onChange={() =>
+            updateSelection(selected.size === rows.length ? new Set() : new Set(rows.map(rowId)))
+          }
+        />
+      ),
+      className: 'kol-table-cell-text w-8',
+      render: (row) => {
+        const id = rowId(row, rows.indexOf(row))
+        return (
+          <ToggleCheckbox
+            checked={selected.has(id)}
+            onChange={() => {
+              const next = new Set(selected)
+              next.has(id) ? next.delete(id) : next.add(id)
+              updateSelection(next)
+            }}
+          />
+        )
+      },
+    })
+    return [...prefix, ...resolved]
+  }, [columns, rows, selected, onReorder, drag]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  const record = value ?? active
+  const hasToolbar = onAdd || onSortToggle || onFilterToggle || onQueryChange
+
+  return (
+    <div ref={wrapRef} className={`flex flex-col min-w-0 ${className}`}>
+      {hasToolbar && (
+        <div className="flex items-center gap-1 pb-3">
+          {onAdd && <Button variant="nav" size="md" iconOnly="plus" iconSize={14} onClick={onAdd} aria-label="Add" />}
+          {onSortToggle && <Button variant="nav" size="md" iconOnly="swap" iconSize={14} onClick={onSortToggle} aria-label="Sort" />}
+          {onFilterToggle && <Button variant="nav" size="md" iconOnly="filter" iconSize={14} onClick={onFilterToggle} aria-label="Filter" />}
+          {onQueryChange && (
+            <SearchInput
+              value={query ?? ''}
+              onChange={(e) => onQueryChange(e?.target ? e.target.value : e)}
+              placeholder={searchPlaceholder}
+              size="sm"
+              className="ml-2"
+            />
+          )}
+        </div>
+      )}
+
+      <Table
+        columns={builtColumns}
+        rows={rows}
+        width="column"
+        rowClassName={(row, i) =>
+          `group${drag && i === drag.from ? ' opacity-40' : ''}${
+            drag && i === drag.over && drag.over !== drag.from ? ' bg-fg-04' : ''
+          }`
+        }
+      />
+
+      {/* floating reorder label — the existing .kol-tooltip chrome, ridden
+        * imperatively (hover machinery doesn't fit a drag) */}
+      {drag &&
+        createPortal(
+          <div className="kol-tooltip fixed" style={{ left: drag.x + 12, top: drag.y + 12 }}>
+            {reorderLabel(drag.from + 1)}
+          </div>,
+          document.body,
+        )}
+
+      {/* detail panel — ShellDrawer owns the slide-over chrome AND the close ×;
+        * this header carries only the record actions (reference: … ▶ save-state
+        * Publish). aria-label defaults follow ShellDrawer's own precedent. */}
+      <ShellDrawer
+        open={!!active}
+        onClose={() => setActive(null)}
+        side="right"
+        width="min(37.5rem, 92vw)"
+        header={
+          <div className="flex items-center gap-2 min-w-0">
+            {onOverflow && (
+              <Button variant="nav" size="md" iconOnly="more" iconSize={14} onClick={() => onOverflow(record)} aria-label="More" />
+            )}
+            {onPreview && (
+              <Button variant="nav" size="md" iconOnly="play" iconSize={14} onClick={() => onPreview(record)} aria-label="Preview" />
+            )}
+            {saveState != null && <span className="kol-helper-10 text-meta ml-auto truncate">{saveState}</span>}
+            {onPublish && (
+              <Button variant="primary" size="sm" className={saveState == null ? 'ml-auto' : ''} onClick={() => onPublish(record)}>
+                {publishLabel}
+              </Button>
+            )}
+          </div>
+        }
+      >
+        {record && (
+          <div className="flex flex-col">
+            {fields.map((f) => (
+              <FieldRow
+                key={f.key}
+                label={f.label}
+                type={f.type}
+                options={f.options}
+                placeholder={f.placeholder}
+                hint={typeof f.hint === 'function' ? f.hint(record) : f.hint}
+                value={record[f.key]}
+                onChange={(next) => onChange?.(f.key, next)}
+                onPick={
+                  (f.type === 'media' || f.type === 'file') && mediaClient ? () => setPicker(f) : undefined
+                }
+                disabled={f.disabled}
+              />
+            ))}
+          </div>
+        )}
+      </ShellDrawer>
+
+      {/* media picker — the EXISTING MediaLibrary organism, modal variant;
+        * client injected, never imported (§3). accept comes from the field. */}
+      {picker && mediaClient && (
+        <MediaLibrary
+          variant="modal"
+          open
+          client={mediaClient}
+          accept={picker.accept ?? 'all'}
+          onClose={() => setPicker(null)}
+          onSelect={(asset) => {
+            onChange?.(picker.key, asset)
+            setPicker(null)
+          }}
+        />
+      )}
+    </div>
+  )
+}

package/src/organisms/Table.jsx

@@ -32,7 +32,7 @@ const WIDTHS = {
   column: '',
 }
 
-const Table = ({ caption, columns, rows, variant = 'default', className = '', width = 'panel' }) => {
+const Table = ({ caption, columns, rows, variant = 'default', className = '', width = 'panel', rowClassName }) => {
   const [sort, setSort] = useState({ key: null, dir: null })
 
   const cycle = (key) =>
@@ -92,7 +92,7 @@ const Table = ({ caption, columns, rows, variant = 'default', className = '', wi
       </thead>
       <tbody>
         {sorted.map((row, rowIndex) => (
-          <tr key={row.id ?? row.token ?? rowIndex} className="kol-table-row">
+          <tr key={row.id ?? row.token ?? rowIndex} className={`kol-table-row${rowClassName ? ` ${rowClassName(row, rowIndex)}` : ''}`}>
             {columns.map((column) => (
               <td key={column.accessor} className={(typeof column.className === 'function' ? column.className(row) : column.className) ?? 'kol-table-cell-text'} style={column.style}>
                 {column.render ? column.render(row) : row[column.accessor] ?? '—'}