@kolkrabbi/kol-component 0.45.0 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",

package/src/atoms/ActionButton.jsx

@@ -0,0 +1,193 @@
+import { useRef, useState, useEffect, useLayoutEffect } from 'react'
+import gsap from 'gsap'
+import { Icon } from '@kolkrabbi/kol-icons'
+import { glyphSize } from '../hooks/glyphLadders.js'
+
+/**
+ * ActionButton — an icon control that CONFIRMS what it did (2026-08-15 user
+ * ruling: *"where is the 'code copied' or whatever message"*).
+ *
+ * The confirm-flip existed exactly once, welded to the clipboard inside
+ * CopyButton: fire, swap `copy`→`check` for 2s, flip the accessible label.
+ * Nothing else could reuse it, so every other in-frame control — download,
+ * select, anything a card puts over its media — had no way to acknowledge a
+ * click at all. This is that behaviour with the clipboard taken out of it;
+ * CopyButton is now a six-line wrapper around it and keeps its own API.
+ *
+ * The swap is ANIMATED, which the original was not — it hard-cut between two
+ * glyphs. framer-motion is already a declared peer of this package (TiltCard),
+ * so nothing new is installed. The curve is the house curve — the numeric twin
+ * of `--kol-ease-house`, since gsap takes an array and cannot read a CSS var.
+ * If the token moves, `HOUSE_EASE` below moves with it by hand; that is the one
+ * place in the DS where the curve is duplicated rather than referenced.
+ *
+ * Chrome is IconFrame's — `kol-icon-frame kol-icon-frame-{variant} -{size}`,
+ * emitted the way Dropdown emits `kol-btn` classes. 05-control-chrome.md:109:
+ * *"Any icon-only control in chrome is IconFrame variant="nav" size="…" —
+ * nothing hand-writes the square (user ruling 2026-08-01)."* This component
+ * hand-wrote one for a day; it does not any more.
+ *
+ * A DIMMED REST IS A VARIANT SWAP, NOT A STATE (same doc). `nav` rests at
+ * oq-64, `ghost` at oq-48, both static — so there is no hover ladder here and
+ * none should be added.
+ *
+ * `plate` is the doc's ONE named exception: an affordance over a PHOTO needs an
+ * opaque plate plus a backdrop blur to stay legible over arbitrary pixels, and
+ * no Button variant covers it. The plate is the discriminator, not a list.
+ *
+ * Positioning stays the parent's job: pass `.kol-frame-control` to sit it in a
+ * card's corner, or nothing to leave it in flow.
+ *
+ * @param {string}   icon         glyph at rest
+ * @param {string}   confirmIcon  glyph while confirming (default 'check')
+ * @param {string}   label        accessible label at rest
+ * @param {string}   confirmLabel accessible label while confirming
+ * @param {Function} onAction     (event) => void | Promise — awaited; the
+ *                                confirm only fires once it resolves
+ * @param {string}   href         renders an <a> instead of a <button>
+ * @param {number}   hold         ms to hold the confirm state (default 2000)
+ * @param {string}   size         sm | md | lg — the pinned square (28/32/36)
+ *                                and its SOLO glyph (16/20/24) move together,
+ *                                resolved from hooks/glyphLadders.js. This was
+ *                                a raw px number and defaulted to 16 in a 32px
+ *                                box: the sm glyph in the md square, which is
+ *                                the exact hand-transcription the ladders file
+ *                                exists to stop.
+ * @param {number}   iconSize     px override for the glyph only — the square
+ *                                never moves with it (2026-07-28 law)
+ * @param {boolean}  toggle       STICKY instead of timed — the on-state holds
+ *                                until clicked again, and `confirmIcon` is the
+ *                                on-glyph (star → star-solid), not a receipt.
+ *                                A confirm says "that happened"; a toggle says
+ *                                "this IS", and the two must not share a timer.
+ * @param {string}   chrome       WHICH control this is. Three separate styles,
+ *                                no shared base — they had one, and every edit
+ *                                to a shared rule moved all of them:
+ *                                  'copy'   .kol-copy-btn      CodeBlock's, untouched
+ *                                  'media'  .kol-media-control boxed, over a photo
+ *                                  'inline' .kol-inline-control bare, inside text
+ */
+const HOUSE_EASE = [0.4, 0, 0.2, 1]
+
+/* long enough that the press is unmistakably a state, short enough that it is
+ * not a mode. The release then plays the full bounce out. */
+const PRESS_HOLD = 1600
+
+const SWAP_MS = 500
+
+const CHROME = {
+  copy: 'kol-copy-btn',
+  media: 'kol-media-control',
+  inline: 'kol-inline-control',
+}
+
+export default function ActionButton({
+  icon,
+  confirmIcon,
+  label,
+  confirmLabel,
+  onAction,
+  href,
+  hold = 2000,
+  size = 'md',
+  iconSize,
+  chrome = 'copy',
+  toggle = false,
+  className = '',
+  ...rest
+}) {
+  const [done, setDone] = useState(false)
+  /* CSS :active lasts exactly as long as the mouse button is down — about 50ms
+   * on a real click — so no duration or curve can make the press read. The
+   * pressed state is HELD here instead, then released to animate out. */
+  const [pressed, setPressed] = useState(false)
+  const timer = useRef(null)
+  const pressTimer = useRef(null)
+
+  /* the timer outlives the click — clear it if the control unmounts mid-hold,
+   * or React warns and the callback fires into a dead component */
+  useEffect(() => () => { clearTimeout(timer.current); clearTimeout(pressTimer.current) }, [])
+
+  const handle = async (event) => {
+    clearTimeout(pressTimer.current)
+    setPressed(true)
+    pressTimer.current = setTimeout(() => setPressed(false), PRESS_HOLD)
+    if (onAction) await onAction(event)
+    clearTimeout(timer.current)
+    if (toggle) {
+      setDone((on) => !on)
+      return
+    }
+    setDone(true)
+    timer.current = setTimeout(() => setDone(false), hold)
+  }
+
+  const aria = (done && confirmLabel) || label
+  const base = CHROME[chrome] ?? CHROME.copy
+  const cls = `${base}${toggle && done ? ` ${base}--on` : ''}${pressed ? ` ${base}--pressed` : ''} ${className}`.trim()
+  const glyphPx = iconSize ?? glyphSize(size, true)
+
+  /* THE SWAP IS A MORPH where the glyphs allow it (user ruling 2026-08-15).
+   * Both glyphs are mounted in one cell; when each side is a single <path>,
+   * MorphSVG tweens the path data so one shape BECOMES the other. Multi-path
+   * glyphs (download is 3, trash is 5) cannot morph 1:1, so they cross over on
+   * the same clock instead — the timing stays identical either way. */
+  const restRef = useRef(null)
+  const onRef = useRef(null)
+  const first = useRef(true)
+
+  /* A CROSSFADE between two real glyphs, not a morph. MorphSVG rewrote the
+   * path `d` in the DOM to tween between shapes — which mutates the icon the
+   * set shipped. If a state needs a different shape, that shape is an icon in
+   * the set (`star` / `star-solid`), not something computed at runtime. */
+  useLayoutEffect(() => {
+    const rest = restRef.current
+    const on = onRef.current
+    /* no confirmIcon = ONE glyph, and the state is carried by the class alone
+     * (a fill, a colour). Nothing to crossfade. */
+    if (!rest || !on) return undefined
+
+    if (first.current) {
+      first.current = false
+      gsap.set(rest, { autoAlpha: 1 })
+      gsap.set(on, { autoAlpha: 0 })
+      return undefined
+    }
+
+    const from = done ? rest : on
+    const to = done ? on : rest
+    const ctx = gsap.context(() => {
+      gsap.to(from, { autoAlpha: 0, duration: SWAP_MS / 1000, ease: 'power1.inOut' })
+      gsap.to(to, { autoAlpha: 1, duration: SWAP_MS / 1000, ease: 'power1.inOut' })
+    })
+    return () => ctx.revert()
+  }, [done])
+
+  const glyph = (
+    <span className="kol-action-glyph relative inline-grid place-items-center" style={{ width: glyphPx, height: glyphPx }}>
+      <span ref={restRef} className="inline-flex" style={{ gridArea: '1 / 1' }}>
+        <Icon name={icon} size={glyphPx} />
+      </span>
+      {confirmIcon && (
+        <span ref={onRef} className="inline-flex" style={{ gridArea: '1 / 1', opacity: 0 }}>
+          <Icon name={confirmIcon} size={glyphPx} />
+        </span>
+      )}
+    </span>
+  )
+
+  /* The element follows the affordance — IconFrame's contract, same reasoning:
+   * a link must be a real <a> for middle-click, focus order and screen readers. */
+  if (href) {
+    return (
+      <a className={cls} href={href} onClick={handle} aria-label={aria} title={aria} {...rest}>
+        {glyph}
+      </a>
+    )
+  }
+  return (
+    <button type="button" className={cls} onClick={handle} aria-label={aria} title={aria} {...rest}>
+      {glyph}
+    </button>
+  )
+}

package/src/hooks/usePlaceholders.js

@@ -0,0 +1,72 @@
+import { useCallback, useEffect, useState } from 'react'
+
+/**
+ * usePlaceholders — the ONE gate for placeholder / empty-state prose
+ * (GatedEmptyState, filed from kol-fxr 2026-08-15).
+ *
+ * The ticket's ruling, and the reason this is one concept rather than three:
+ * the filing repo had invented "helper text" vs "empty state" vs "hint" as
+ * separate ideas, and that is precisely what let the prose creep back — each
+ * kind had its own home and none had an off switch. There is one kind here,
+ * it is called a placeholder, and it is OFF until asked for.
+ *
+ * WHAT THE DS OWNS: the preference, its persistence, and the `.kol-placeholder`
+ * suppression rule in kol-utilities.css.
+ * WHAT THE CONSUMER OWNS: the keybind. A design system that grabs a global
+ * key collides with every app that already used it — kol-fxr's own `H` is
+ * already `toggle-visibility` in its editor keymap, which is exactly the
+ * collision the DS must not ship. Call `toggle` from whatever key you like.
+ *
+ * The hiding is CSS, not a render branch, so it covers a consumer's OWN prose
+ * the moment they put `.kol-placeholder` on it — not just <EmptyState gated>.
+ * One rule, no re-render, nothing to thread through a tree.
+ */
+
+const STORAGE_KEY = 'kol-placeholders'
+const ATTR = 'data-kol-placeholders'
+
+const root = () => document.documentElement
+
+/* Module-level subscribers: a settings checkbox and a keybind are usually two
+ * different components calling this hook, and per-component useState would let
+ * them disagree about a preference there is only one of. The CSS never
+ * desyncs (it reads the attribute), but the reported `shown` would. */
+const listeners = new Set()
+
+function read() {
+  try {
+    return localStorage.getItem(STORAGE_KEY) === 'on'
+  } catch {
+    return false // storage blocked → stay off, which is the default anyway
+  }
+}
+
+function write(on) {
+  if (on) root().setAttribute(ATTR, '')
+  else root().removeAttribute(ATTR)
+  try {
+    localStorage.setItem(STORAGE_KEY, on ? 'on' : 'off')
+  } catch { /* storage blocked — the attribute still holds for this session */ }
+  listeners.forEach((fn) => fn(on))
+}
+
+export default function usePlaceholders() {
+  const [shown, setShown] = useState(false)
+
+  /* Boot from storage and stamp the attribute. Default OFF is the ruling, so
+   * an absent key and a blocked localStorage both land on the same answer. */
+  useEffect(() => {
+    const on = read()
+    if (on) root().setAttribute(ATTR, '')
+    setShown(on)
+    listeners.add(setShown)
+    return () => listeners.delete(setShown)
+  }, [])
+
+  /* Read-then-flip off storage rather than state: a keybind handler bound once
+   * would otherwise close over the first render's value and toggle from stale. */
+  const toggle = useCallback(() => write(!read()), [])
+  const set = useCallback((on) => write(!!on), [])
+
+  return { shown, toggle, setShown: set }
+}

package/src/index.js

@@ -22,7 +22,8 @@ export { default as AssetPlaceholder } from './utilities/AssetPlaceholder.jsx'
 export { default as Avatar } from './atoms/Avatar.jsx'
 export { default as Badge } from './atoms/Badge.jsx'
 export { default as Button } from './atoms/Button.jsx'
-export { default as CopyButton } from './atoms/CopyButton.jsx'
+export { default as ActionButton } from './atoms/ActionButton.jsx'
+export { default as CopyButton } from './molecules/CopyButton.jsx'
 export { default as CurveOverlay } from './atoms/CurveOverlay.jsx'
 export { default as Divider } from './atoms/Divider.jsx'
 export { default as DocsToc } from './molecules/DocsToc.jsx'
@@ -79,6 +80,15 @@ export { default as FramedMediaBand } from './organisms/FramedMediaBand.jsx'
 export { default as Image } from './atoms/Image.jsx'
 export { default as MediaCard } from './molecules/MediaCard.jsx'
 export { default as MediaRow } from './molecules/MediaRow.jsx'
+
+/* content-card system (2026-08-15) — the ruled card/row family:
+ * docs/documentation/03-components/06-content-card-system.md */
+export { default as ContentText } from './molecules/ContentText.jsx'
+export { default as ContentMedia } from './molecules/ContentMedia.jsx'
+export { default as ContentCard } from './molecules/ContentCard.jsx'
+export { default as ContentRow } from './molecules/ContentRow.jsx'
+export { default as ContentItem } from './molecules/ContentItem.jsx'
+export { default as ContentCollection } from './organisms/ContentCollection.jsx'
 export { MenuItem, MenuDropdownItem, MenuDropdownDivider, MenuDropdownNest } from './molecules/MenuItem.jsx'
 export { MenuPopover } from './molecules/MenuPopover.jsx'
 export { ModalProvider, useModal } from './molecules/Modal.jsx'
@@ -148,6 +158,7 @@ export { default as useTilt } from './hooks/useTilt.js'
 export { default as useCoarsePointer } from './hooks/useCoarsePointer.js'
 export { default as useAxisAnimation } from './hooks/useAxisAnimation.js'
 export { useEyedropper, pickFromCanvasElement } from './hooks/useEyedropper.js'
+export { default as usePlaceholders } from './hooks/usePlaceholders.js'
 export { resolveCssVar, resolveCssColor, isLight } from './hooks/cssVar.js'
 
 // color math (support module — HSL/hex conversion + harmony generation)

package/src/molecules/CodeBlock.jsx

@@ -1,6 +1,6 @@
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter'
 import { oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism'
-import CopyButton from '../atoms/CopyButton.jsx'
+import CopyButton from './CopyButton.jsx'
 
 /**
  * CodeBlock — REPLICATED from the elder reference
@@ -105,7 +105,7 @@ export default function CodeBlock({ children, code: codeProp, language: language
         >
           {code}
         </SyntaxHighlighter>
-        <CopyButton text={code} className="kol-codeblock-copy" />
+        <CopyButton text={code} className="kol-frame-control" />
       </div>
     </div>
   )

package/src/molecules/ContentCard.jsx

@@ -0,0 +1,250 @@
+import ContentMedia from './ContentMedia.jsx'
+import ContentText from './ContentText.jsx'
+
+/**
+ * ContentCard — the card form of the content-card system. Variants differ in
+ * text composition, media ratio, and the RULED box structure, all defaulted
+ * from the live review (06-content-card-system.md §2/§3):
+ *
+ *   stack      media (own ratio) on top, text plate below  — default · article · work
+ *   fill-card  the CARD is the ratio frame; media fills the remainder above
+ *              the plate — catalog · print (the A4 cards)
+ *   canvas     the card is the ratio frame; media fills it absolutely and the
+ *              text plate floats on top — typeface (details over specimen)
+ *
+ * Padding spells the TOKENS (--kol-pad-card-{sm,md,lg} = 12/16/24), never a
+ * literal. Passing `pad` overrides the plate padding with one token step
+ * (named `pad`, not `size` — `size` is the ruled TEXT slot). Image-only cards
+ * (print) pass no text slots and render no plate. Exotic chrome (drawers,
+ * keylines, specimens) is consumer content through `media`.
+ */
+
+/* ruled defaults — defaults, not hardcodes; `ratio` stays overridable while
+ * the A4 question is open (06-content-card-system.md §4). */
+const RATIOS = {
+  default: '1 / 1',
+  catalog: '1 / 1.41421',
+  print: '1 / 1.41421',
+  article: '16 / 9',
+  work: '3 / 4',
+  typeface: '1 / 1.41421',
+}
+
+/* ruled box values per variant, verbatim from the §3 reference cards —
+ * paddings in tokens: pad-card-sm 12 · pad-card-md 16 · pad-card-lg 24 */
+const BOX = {
+  default:  { layout: 'stack', border: 'var(--kol-fg-12)', bg: 'var(--kol-fg-02)', pad: 'var(--kol-pad-card-sm)' },
+  catalog:  { layout: 'fill-card', border: 'var(--kol-fg-04)', bg: 'var(--kol-fg-04)', pad: 'var(--kol-pad-card-sm) var(--kol-pad-card-md)', plateTop: true, plateBg: 'var(--kol-surface-primary)' },
+  print:    { layout: 'fill-card', border: null, bg: 'var(--kol-surface-secondary)', pad: 'var(--kol-pad-card-sm) var(--kol-pad-card-md)', plateTop: true },
+  article:  { layout: 'stack', border: null, bg: null, pad: '0', mediaGap: 'var(--kol-spacing-4)' },
+  /* work is a DRAWER: image-only at rest, and on hover a light plate rises
+   * over the bottom of the artwork carrying the title + meta. This is the
+   * shipped WorkCard and it was wrong to reject it as "hiding the title" — a
+   * work shelf is a wall of images by design, and the caption is the reveal. */
+  work:     { layout: 'drawer', border: 'var(--kol-fg-04)', bg: null, pad: 'var(--kol-pad-card-md)', padMd: 'var(--kol-pad-card-lg)' },
+  /* typeface's card is a FIXED 500px tall specimen board, not a ratio — the
+   * shipped item is `h-[500px]`, and a ratio re-crops the glyph at every
+   * column width, which is the one thing a specimen must not do. */
+  typeface: { layout: 'canvas', border: 'var(--kol-fg-08)', bg: 'var(--kol-surface-primary)', pad: 'var(--kol-pad-card-lg)', height: 500 },
+}
+
+/* HOVER is a bg STEP on the opaque tier, per 05-control-chrome.md's state model
+ * — "interactive fills mix ink into the surface via the oq-* tier, never a
+ * translucent fg-* wash", because a translucent fill over an image reads as the
+ * control vanishing. article is the exception the shipped card already set: it
+ * has no surface of its own to step, so it dims its title instead. */
+const HOVER = {
+  default:  'var(--kol-oq-04)',
+  catalog:  'var(--kol-surface-tertiary)',
+  print:    'var(--kol-oq-04)',
+  article:  null,
+  work:     null,
+  typeface: 'var(--kol-surface-inverse)',
+}
+
+/* per-variant media treatment. `ring` sits OVER the artwork, `frame` UNDER it —
+ * see ContentMedia. print rings because an A4 print on a light page has no edge
+ * of its own; article frames because its media is a 16/9 thumbnail that rarely
+ * fills its box. */
+const MEDIA = {
+  print:   { ring: true },
+  /* ListingCard's card media steps its border on hover — fg-08 → fg-16 */
+  article: { frame: true, borderHover: true },
+}
+
+export default function ContentCard({
+  variant = 'default',
+  pad,
+  media,
+  ratio,
+  fit,
+  frame,
+  ring,
+  control,
+  actions,
+  selected = false,
+  onClick,
+  href,
+  onNavigate,
+  className = '',
+  ...text
+}) {
+  const box = BOX[variant] ?? BOX.default
+  const r = ratio ?? RATIOS[variant]
+  const padding = pad ? `var(--kol-pad-card-${pad})` : box.pad
+  /* image-only cards (print) pass no text slots — the empty plate must not render */
+  const hasText = ['title', 'body', 'kicker', 'detail', 'date', 'size', 'meta', 'tags'].some((k) => text[k] != null)
+  /* `actions` sit IN THE TEXT PLATE, bottom-right (user ruling 2026-08-15:
+   * *"space in text bottom right"*). Not stacked under the copy in their own
+   * row — that grew the card — and not on the media, which was my call to make
+   * and wasn't. The plate is one flex row: text takes the width, actions hold
+   * the trailing edge, both bottom-aligned so the buttons sit on the last line
+   * of copy rather than floating beside the title. */
+  const hasPlate = hasText || actions != null
+  const framed = box.border != null || box.bg != null
+
+  const textNode = hasPlate ? (
+    <div
+      className="kol-card-plate relative"
+      style={{
+        '--kol-plate-pad': padding,
+        '--kol-plate-pad-md': box.padMd,
+        padding,
+        marginTop: box.layout === 'stack' ? box.mediaGap : undefined,
+        borderTop: box.plateTop ? '1px solid var(--kol-fg-04)' : undefined,
+        background: box.layout === 'drawer' ? 'var(--kol-surface-inverse)' : box.plateBg,
+        color: box.layout === 'drawer' ? 'var(--kol-fg-inverse)' : undefined,
+        position: 'relative',
+        zIndex: box.layout === 'canvas' ? 1 : undefined,
+      }}
+    >
+      {hasText && <ContentText variant={variant} form="card" {...text} />}
+      {/* ABSOLUTE, not a flex sibling: the plate's height moves with the title
+        * and the meta, so a laid-out stack would stretch or drift with it. The
+        * inset reads the SAME pad token the plate uses, so the icons sit the
+        * same distance from the top and right edges as the copy does. */}
+      {actions && (
+        <div
+          className="absolute flex"
+          style={{ top: padding, bottom: padding, right: padding }}
+        >
+          {actions}
+        </div>
+      )}
+    </div>
+  ) : null
+
+  /* The CARD clips its own corners when it is framed, so the media must not
+   * round again — two radii on one edge is the visible double-round (user
+   * ruling 2026-08-15). Unframed variants (`article`) have nothing clipping
+   * them, so their media keeps its radius. The ROW is untouched: it does not
+   * clip, so ContentRow's thumb rounds as before. */
+  const mediaRadius = !framed
+  const mediaProps = {
+    radius: mediaRadius,
+    fit: fit ?? MEDIA[variant]?.fit,
+    frame: frame ?? MEDIA[variant]?.frame ?? false,
+    ring: ring ?? MEDIA[variant]?.ring ?? false,
+    borderHover: MEDIA[variant]?.borderHover ?? false,
+  }
+
+  /* `control` — the in-frame control slot (user ruling 2026-08-15). One node,
+   * placed in the media frame's corner by `.kol-frame-control` (kol-theme).
+   * The CARD owns WHERE, the consumer owns WHAT: CopyButton, IconFrame with an
+   * href, a select indicator — the card knows none of them by name. This is
+   * what MediaCard hardcodes as a download link plus a select checkbox, and
+   * the reason its media library could not migrate onto ContentCard. */
+  const controlNode = control ? <div className="kol-frame-control">{control}</div> : null
+
+
+  const body =
+    box.layout === 'stack' ? (
+      <>
+        <div className="relative">
+          <ContentMedia ratio={r} {...mediaProps}>{media}</ContentMedia>
+          {controlNode}
+        </div>
+        {textNode}
+      </>
+    ) : box.layout === 'fill-card' ? (
+      <>
+        <div className="flex-1 min-w-0 relative overflow-hidden">
+          <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
+          {controlNode}
+        </div>
+        {textNode}
+      </>
+    ) : box.layout === 'drawer' ? (
+      <>
+        <div className="relative h-full">
+          <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
+          {controlNode}
+        </div>
+        {/* the plate is INVERSE and hidden until hover — `kol-card-drawer` owns
+          * the reveal so the transition sits with the rest of the chrome */}
+        {textNode && <div className="kol-card-drawer">{textNode}</div>}
+      </>
+    ) : (
+      /* canvas — media fills the frame, plate floats on top */
+      <>
+        <div className="absolute" style={{ inset: 0 }}>
+          <ContentMedia ratio={null} {...mediaProps}>{media}</ContentMedia>
+          {controlNode}
+        </div>
+        {textNode}
+      </>
+    )
+
+  /* THE ROOT FOLLOWS THE AFFORDANCE. A card that navigates must be a real <a>:
+   * middle-click, cmd-click, focus order, "copy link address" and every screen
+   * reader's link list all come from the tag, and none of them can be added
+   * back with a click handler. `onNavigate` is the SPA seam — call it, and if
+   * it does not preventDefault the browser follows the href, so the card works
+   * with or without a router.
+   *
+   * A card with only onClick stays an <article> but becomes operable: a div you
+   * can click and cannot focus is the single most common a11y regression in a
+   * card family, and it is what every shipped variant here had. */
+  const nav = (event) => {
+    if (onNavigate) onNavigate(event, href)
+    if (onClick) onClick(event)
+  }
+  const interactive = href || onClick
+  const hoverBg = HOVER[variant]
+
+  const common = {
+    className: `kol-card group flex flex-col ${box.layout === 'drawer' ? 'relative overflow-hidden rounded-[var(--kol-radius-sm)]' : ''} ${framed ? 'overflow-hidden rounded-[var(--kol-radius-sm)]' : ''} ${box.border ? 'border' : ''} ${box.layout === 'canvas' ? 'relative' : ''} ${interactive ? 'cursor-pointer select-none' : ''} ${hoverBg && interactive ? 'kol-content-hover' : ''} ${className}`.trim(),
+    style: {
+      /* same reason as ContentRow: rest colours are PROPERTIES, because an
+       * inline background/borderColor outranks the hover class and the step
+       * would never render. */
+      '--kol-card-bg': box.bg ?? undefined,
+      '--kol-card-border': box.border ? (selected ? 'var(--kol-fg-64)' : box.border) : undefined,
+      '--kol-content-hover-bg': hoverBg ?? undefined,
+      aspectRatio: box.height ? undefined : (box.layout !== 'stack' ? r : undefined),
+      height: box.height,
+    },
+  }
+
+  if (href) {
+    return <a href={href} onClick={nav} {...common}>{body}</a>
+  }
+  if (onClick) {
+    return (
+      <article
+        onClick={onClick}
+        role="button"
+        tabIndex={0}
+        onKeyDown={(e) => {
+          if (e.key !== 'Enter' && e.key !== ' ') return
+          e.preventDefault()
+          onClick(e)
+        }}
+        {...common}
+      >
+        {body}
+      </article>
+    )
+  }
+  return <article {...common}>{body}</article>
+}

package/src/molecules/ContentItem.jsx

@@ -0,0 +1,14 @@
+import ContentCard from './ContentCard.jsx'
+import ContentRow from './ContentRow.jsx'
+
+/**
+ * ContentItem — the form switch the estate hand-wrote nine times
+ * (`layout === 'list' ? row : card`). One prop picks the form; everything
+ * else passes through to ContentCard / ContentRow unchanged, so a listing
+ * under a LIST/GRID toggle is one component with one prop flipped.
+ *
+ * @param {string} form  'card' | 'row'
+ */
+export default function ContentItem({ form = 'card', ...rest }) {
+  return form === 'row' ? <ContentRow {...rest} /> : <ContentCard {...rest} />
+}