@kolkrabbi/kol-component 0.2.0 → 0.3.0

package/src/molecules/SwatchControls.jsx

@@ -0,0 +1,217 @@
+import { useEffect, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-loader'
+import ColorSwatch from './ColorSwatch.jsx'
+
+/* taxonomy-ok: the default composed control nests the same-file SwatchStack
+ * and EyedropPick (KOL named exports the relative-import check can't see);
+ * both collapse the source's internal FramedSwatch onto the sibling molecule
+ * ColorSwatch (a same-tier relative import). */
+
+/*
+ * SwatchControls — the Photoshop-style top row of the colour panel, in two
+ * hand-tuned pieces plus the composed row. Hand-tuned visuals (fixed pixel
+ * slots, the overlap-by-DOM-order trick, the double-ring halo, the red-slash
+ * "none" marker). DO NOT refactor pieces to atoms — the look is intentional
+ * and matches the Ref design; promote each piece WHOLE.
+ *
+ *   <SwatchControls ... />                                     (default export)
+ *     — SwatchStack + EyedropPick laid out in a row.
+ *
+ *   <SwatchStack fillColor strokeColor activePaint onSwap onClear />
+ *     — overlapping fill + stroke paint chips (fill upper-left, stroke
+ *       lower-right) with a swap arrow and a "set to none" marker. `activePaint`
+ *       flips which chip renders SECOND, so the active paint wins the overlap.
+ *       No z-index, no transform — DOM order alone stacks them.
+ *
+ *   <EyedropPick sampleColor onPick disabled />
+ *     — eyedropper icon button + a small sample chip of the sampled colour.
+ *       The button is feature-gated: it is hidden entirely when the browser
+ *       EyeDropper API is unavailable, and `disabled` dims it when supported
+ *       but unusable. The actual EyeDropper call + canvas sampling live at the
+ *       call site behind `onPick`.
+ *
+ * The paint chips and the sample chip collapse onto ColorSwatch's `halo`
+ * variant (`variant="halo"` supplies the exact tuned `0 0 0 1px #000,
+ * 0 0 0 2px #505050` double-ring); the source's redundant FramedSwatch is
+ * dropped. The swap / eyedrop glyphs route through the DS Icon.
+ */
+
+/* Fixed chip slots inside the 44×44 stack — identical in both variants; only
+ * the render order changes. Positions live on absolutely-placed wrappers so
+ * ColorSwatch keeps its own `relative` root (its box-shadow halo needs it). */
+const FILL_SLOT   = 'left-[5px] top-[6px]'
+const STROKE_SLOT = 'left-[15px] top-[16px]'
+
+/* One 22px paint chip: a halo ColorSwatch pinned to its slot. Click → onSwap
+ * (either chip signals swap intent; the app decides fill↔active). */
+function PaintChip({ id, label, color, slot, onSwap }) {
+  return (
+    <span className={`absolute ${slot}`}>
+      <ColorSwatch
+        hex={color}
+        size={22}
+        radius="full"
+        variant="halo"
+        hoverable={false}
+        onClick={onSwap}
+        data-id={id}
+        aria-label={label}
+      />
+    </span>
+  )
+}
+
+/**
+ * SwatchStack — the overlapping fill + stroke paint chips. `activePaint`
+ * selects which chip renders second (topmost in the overlap) purely via DOM
+ * order — no z-index, no transform. Clicking either chip, or the swap arrow,
+ * fires `onSwap`; the slash-circle marker fires `onClear`.
+ *
+ * @param {string}   fillColor    fill chip background (css color). Default '#FFFFFF'
+ * @param {string}   strokeColor  stroke chip background (css color). Default '#000000'
+ * @param {'fill'|'stroke'} activePaint  which chip paints on top. Default 'fill'
+ * @param {Function} onSwap       () => void — either chip or the swap arrow
+ * @param {Function} onClear      () => void — the "set to none" marker
+ */
+export function SwatchStack({
+  fillColor = '#FFFFFF',
+  strokeColor = '#000000',
+  activePaint = 'fill',
+  onSwap,
+  onClear,
+}) {
+  const fill   = <PaintChip key="fill"   id="fill"   label="Fill color"   color={fillColor}   slot={FILL_SLOT}   onSwap={onSwap} />
+  const stroke = <PaintChip key="stroke" id="stroke" label="Stroke color" color={strokeColor} slot={STROKE_SLOT} onSwap={onSwap} />
+
+  /* Active paint is rendered SECOND so it paints on top in the overlap. */
+  const chips = activePaint === 'fill' ? [stroke, fill] : [fill, stroke]
+
+  return (
+    <div className="relative shrink-0 w-11 h-11">
+      {chips}
+      <SwapButton onSwap={onSwap} />
+      <NoneMarker onClear={onClear} />
+    </div>
+  )
+}
+
+/**
+ * EyedropPick — eyedropper icon button + a sample chip of the sampled colour.
+ * The button is hidden when the browser EyeDropper API is unavailable (no
+ * affordance for an action that can't run); when supported but unusable pass
+ * `disabled` to dim it. `onPick` is the app seam where EyeDropper + canvas
+ * sampling run.
+ *
+ * @param {string}   sampleColor  sample chip background (css color)
+ * @param {Function} onPick       () => void — eyedropper button click
+ * @param {boolean}  disabled     dim + disable the button (default false)
+ */
+export function EyedropPick({ sampleColor, onPick, disabled = false }) {
+  const supported = useEyeDropperSupported()
+
+  return (
+    <div className="flex items-start gap-1 shrink-0">
+      {supported && (
+        <button
+          type="button"
+          onClick={onPick}
+          disabled={disabled}
+          aria-label="Eyedropper"
+          title="Pick a color from the canvas"
+          className="inline-flex cursor-pointer text-fg hover:opacity-80 disabled:opacity-40 disabled:cursor-not-allowed"
+        >
+          <Icon name="eyedrop" size={24} />
+        </button>
+      )}
+      <ColorSwatch
+        hex={sampleColor}
+        size={16}
+        radius="full"
+        variant="halo"
+        title="Sampled color"
+        className="mt-1"
+      />
+    </div>
+  )
+}
+
+/* ────────── Internal helpers (not exported) ────────── */
+
+/* EyeDropper support, resolved after mount so SSR / first paint stays stable
+ * (starts false, flips true only where the API exists). */
+function useEyeDropperSupported() {
+  const [supported, setSupported] = useState(false)
+  useEffect(() => {
+    setSupported(typeof window !== 'undefined' && 'EyeDropper' in window)
+  }, [])
+  return supported
+}
+
+/* Swap arrow, pinned top-right of the stack. Same intent as clicking a chip. */
+function SwapButton({ onSwap }) {
+  return (
+    <button
+      type="button"
+      onClick={onSwap}
+      aria-label="Swap colors"
+      className="absolute left-[28px] top-0 inline-flex cursor-pointer text-fg hover:opacity-80"
+    >
+      <Icon name="swap" size={16} />
+    </button>
+  )
+}
+
+/* "Set to none" marker, pinned bottom-left of the stack. The red diagonal
+ * slash + token ring live in `.kol-swatch-none-marker` (chrome the JSX can't
+ * express — a two-stop gradient over a themed box-shadow ring). */
+function NoneMarker({ onClear }) {
+  return (
+    <button
+      type="button"
+      onClick={onClear}
+      aria-label="Clear color"
+      className="kol-swatch-none-marker absolute left-[1px] top-[32px] w-2.5 h-2.5 rounded-full overflow-hidden cursor-pointer"
+    />
+  )
+}
+
+/**
+ * SwatchControls — the composed colour-panel top row: SwatchStack (fill /
+ * stroke paint chips + swap + none) alongside EyedropPick (eyedropper +
+ * sample chip). Fully controlled and store-free; the app owns the swap, clear,
+ * and pick handlers.
+ *
+ * @param {string}   fillColor      fill chip background (css color)
+ * @param {string}   strokeColor    stroke chip background (css color)
+ * @param {'fill'|'stroke'} activePaint  which chip paints on top. Default 'fill'
+ * @param {Function} onSwap         () => void — swap fill ↔ active
+ * @param {Function} onClear        () => void — set active paint to none
+ * @param {string}   sampleColor    eyedropper sample chip background (css color)
+ * @param {Function} onPick         () => void — invoke EyeDropper at the call site
+ * @param {boolean}  eyedropDisabled  dim + disable the eyedropper button
+ * @param {string}   className      extra classes on the row wrapper
+ */
+export default function SwatchControls({
+  fillColor,
+  strokeColor,
+  activePaint = 'fill',
+  onSwap,
+  onClear,
+  sampleColor,
+  onPick,
+  eyedropDisabled = false,
+  className = '',
+}) {
+  return (
+    <div className={`flex items-start gap-3 ${className}`}>
+      <SwatchStack
+        fillColor={fillColor}
+        strokeColor={strokeColor}
+        activePaint={activePaint}
+        onSwap={onSwap}
+        onClear={onClear}
+      />
+      <EyedropPick sampleColor={sampleColor} onPick={onPick} disabled={eyedropDisabled} />
+    </div>
+  )
+}

package/src/molecules/TabsRow.jsx

@@ -0,0 +1,87 @@
+import { useRef } from 'react'
+import { Icon } from '@kolkrabbi/kol-loader'
+
+/* taxonomy-ok: nests kol-loader's Icon */
+
+/**
+ * TabsRow — labeled underline tab strip: text tabs where the active tab gets
+ * a 2px bottom underline and emphasis color; inactive tabs are muted and
+ * brighten on hover. Optional leading close button and trailing minimise
+ * chevron render only when their handlers are passed — no outer chrome, the
+ * consumer wraps it. Controlled: the parent owns `value`.
+ *
+ * Real tablist semantics: `role="tablist"`/`role="tab"` + `aria-selected`,
+ * roving tabindex, ArrowLeft/ArrowRight move focus and activate (wrapping).
+ * Labels render verbatim from `tabs` — no text-transform.
+ *
+ * @param {Array}    tabs       [{ id, label }] — tab items, authored at the call site
+ * @param {string}   value      id of the active tab (controlled)
+ * @param {Function} onChange   (id) => void — fires on tab click or arrow-key move
+ * @param {Function} onClose    () => void — show + wire the leading close button
+ * @param {Function} onMinimise () => void — show + wire the trailing minimise chevron
+ */
+export default function TabsRow({ tabs = [], value, onChange, onClose, onMinimise }) {
+  const listRef = useRef(null)
+  const activeIdx = tabs.findIndex((t) => t.id === value)
+
+  const onKeyDown = (e) => {
+    if ((e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') || !tabs.length) return
+    e.preventDefault()
+    const dir = e.key === 'ArrowRight' ? 1 : -1
+    const next = ((activeIdx === -1 ? 0 : activeIdx) + dir + tabs.length) % tabs.length
+    onChange?.(tabs[next].id)
+    listRef.current?.querySelectorAll('[role="tab"]')[next]?.focus()
+  }
+
+  return (
+    <div className="flex items-stretch gap-4 px-3 h-10">
+      {onClose && (
+        <button
+          type="button"
+          onClick={onClose}
+          aria-label="Close"
+          className="text-meta hover:text-emphasis self-center"
+          style={{ lineHeight: 0 }}
+        >
+          <Icon name="close" size={12} />
+        </button>
+      )}
+
+      <div ref={listRef} role="tablist" onKeyDown={onKeyDown} className="flex items-stretch gap-4">
+        {tabs.map((t, i) => {
+          const isActive = t.id === value
+          return (
+            <button
+              key={t.id}
+              type="button"
+              role="tab"
+              aria-selected={isActive}
+              tabIndex={isActive || (activeIdx === -1 && i === 0) ? 0 : -1}
+              onClick={() => onChange?.(t.id)}
+              className={[
+                'kol-mono-12 flex items-center cursor-pointer border-b-2',
+                isActive
+                  ? 'text-emphasis border-fg'
+                  : 'text-meta hover:text-emphasis border-transparent',
+              ].join(' ')}
+            >
+              {t.label}
+            </button>
+          )
+        })}
+      </div>
+
+      {onMinimise && (
+        <button
+          type="button"
+          onClick={onMinimise}
+          aria-label="Minimise"
+          className="ml-auto text-meta hover:text-emphasis self-center"
+          style={{ lineHeight: 0 }}
+        >
+          <Icon name="chevron-down" size={12} />
+        </button>
+      )}
+    </div>
+  )
+}

package/src/molecules/VideoBlock.jsx

@@ -0,0 +1,86 @@
+import Figure from '../atoms/Figure.jsx'
+
+/**
+ * getEmbedUrl — turn a YouTube/Vimeo share URL into its embeddable player URL.
+ * Kept verbatim from the source; it is the only real logic in this block.
+ * Returns null for anything it can't parse (→ the file player is used).
+ */
+export function getEmbedUrl(url) {
+  if (!url) return null
+  const ytMatch = url.match(/(?:youtube\.com\/watch\?v=|youtu\.be\/)([\w-]+)/)
+  if (ytMatch) return `https://www.youtube.com/embed/${ytMatch[1]}`
+  const vimeoMatch = url.match(/vimeo\.com\/(\d+)/)
+  if (vimeoMatch) return `https://player.vimeo.com/video/${vimeoMatch[1]}`
+  return null
+}
+
+/**
+ * VideoBlock — a captioned prose video: the DS Figure shell (optional label,
+ * aspect-locked bordered frame, optional figcaption) wrapping either an
+ * <iframe> embed (YouTube/Vimeo, auto-parsed from `url`) or a native <video>
+ * file player. Embed wins when `url` parses; otherwise the `file` player runs.
+ * The long-form sibling of ImageBlock — both compose the same Figure atom.
+ *
+ * De-Sanitized: flat props, no CMS `value` object. Renders nothing when
+ * neither an embed nor a file source resolves. Label/caption authored as-is.
+ *
+ * @param {string}  url      YouTube/Vimeo share URL → iframe embed
+ * @param {string}  file     direct video file URL → native <video>
+ * @param {string}  poster   poster image for the file player
+ * @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 {boolean} autoplay autoplay the file player (forces muted)
+ * @param {boolean} muted    mute the file player (forced true when autoplay)
+ * @param {boolean} controls show file-player controls (default true)
+ * @param {boolean} loop     loop file playback
+ * @param {string}  className extra classes on the <figure>
+ */
+export default function VideoBlock({
+  url,
+  file,
+  poster,
+  label,
+  caption,
+  aspect = '5/3',
+  autoplay = false,
+  muted = false,
+  controls = true,
+  loop = false,
+  className = '',
+}) {
+  const embedSrc = getEmbedUrl(url)
+  if (!embedSrc && !file) return null
+
+  const isMuted = autoplay ? true : muted
+
+  return (
+    <Figure label={label} caption={caption} aspect={aspect} className={className}>
+      {embedSrc ? (
+        <iframe
+          src={embedSrc}
+          title={label || caption || 'Embedded video'}
+          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+          allowFullScreen
+          className="w-full h-full"
+          style={{ border: 0 }}
+        />
+      ) : (
+        <video
+          src={file}
+          poster={poster}
+          controls={controls}
+          controlsList="nodownload noplaybackrate noremoteplayback"
+          autoPlay={autoplay}
+          loop={loop}
+          muted={isMuted}
+          disablePictureInPicture
+          disableRemotePlayback
+          playsInline
+          className="w-full h-full object-cover"
+          style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+        />
+      )}
+    </Figure>
+  )
+}

package/src/molecules/WorkListItem.jsx

@@ -0,0 +1,83 @@
+import Image from './Image.jsx'
+import Tag from '../atoms/Tag.jsx'
+
+/**
+ * WorkListItem — the list/row view of a `/work` project: the row twin of
+ * WorkCard. A horizontal card — a small square thumbnail on the left, then a
+ * content column split into a header row (title + tag chips on the left, type +
+ * year right-aligned) above a large display preview line (the project
+ * description). Hover raises a border; `active` persists that treatment for the
+ * last-hovered row so a parent list can mark one active.
+ *
+ * Shares WorkCard's flat project bag so a `/work` view can toggle grid ⇄ list
+ * as a render swap, not a data reshape. The whole row is an anchor (`href`) —
+ * the source row was not a link (its parent list owned navigation); as the
+ * list-view counterpart to WorkCard it is the click target itself. Thumbnail
+ * routes through DS Image (graceful missing-asset fallback); tags render as DS
+ * Tag chips. Router-agnostic via `onNavigate(href, event)`.
+ *
+ * Text casing: no text-transform (KOL rule) — the source's `uppercase` title
+ * and `capitalize` type are dropped; strings render verbatim as authored.
+ *
+ * @param {string}        title        header title
+ * @param {string}        thumbnail    thumbnail URL; the block is omitted when absent
+ * @param {string[]}      tags         rendered as Tag chips under the title
+ * @param {string}        type         right-column label
+ * @param {string|number} year         right-column, below type
+ * @param {string}        description  large display preview line
+ * @param {string}        href         row navigation target
+ * @param {boolean}       active       persist the hover treatment (last-hovered row)
+ * @param {Function}      onMouseEnter hover callback (parent tracks the active row)
+ * @param {Function}      onNavigate   (href, event) => void — anchor click seam for SPA routing
+ */
+export default function WorkListItem({
+  title,
+  thumbnail,
+  tags,
+  type,
+  year,
+  description,
+  href,
+  active = false,
+  onMouseEnter,
+  onNavigate,
+}) {
+  return (
+    <a
+      href={href}
+      onClick={onNavigate ? (e) => onNavigate(href, e) : undefined}
+      onMouseEnter={onMouseEnter}
+      className={`self-stretch min-h-24 md:min-h-40 p-4 md:p-6 rounded flex items-stretch gap-4 md:gap-6 mb-4 md:mb-6 overflow-hidden cursor-pointer transition-all duration-300 bg-surface-secondary border ${active ? 'border-fg-16' : 'border-transparent hover:border-fg-16'}`}
+    >
+      {thumbnail && (
+        <div className="shrink-0 w-16 h-16 md:w-28 md:h-28 rounded-[2px] overflow-hidden border border-fg-08">
+          <Image src={thumbnail} alt={title} category="work" name={title} className="w-full h-full object-cover" />
+        </div>
+      )}
+
+      <div className="flex flex-col justify-between min-w-0 flex-1 gap-3 md:gap-4">
+        <div className="flex justify-between items-start md:items-center gap-4">
+          <div className="flex flex-col gap-1 md:gap-2 min-w-0">
+            <div className="kol-mono-14 truncate">{title}</div>
+            {tags?.length > 0 && (
+              <div className="flex flex-wrap gap-1.5">
+                {tags.map((t) => (
+                  <Tag key={t} size="sm" variant="naked" hash={false}>{t}</Tag>
+                ))}
+              </div>
+            )}
+          </div>
+
+          <div className="flex flex-col items-end gap-1 md:gap-2 shrink-0">
+            <span className="kol-mono-12 md:kol-mono-14">{type}</span>
+            <span className="kol-mono-12 text-fg-64">{year}</span>
+          </div>
+        </div>
+
+        <p className="kol-sans-heading-03 text-auto leading-tight whitespace-nowrap overflow-hidden text-ellipsis">
+          {description}
+        </p>
+      </div>
+    </a>
+  )
+}

package/src/molecules/foundry/SpecimenSectionHeader.jsx

@@ -0,0 +1,89 @@
+import { Icon } from '@kolkrabbi/kol-loader'
+import Dropdown from '../Dropdown.jsx'
+import Divider from '../../atoms/Divider.jsx'
+
+/* taxonomy-ok: nests DS Dropdown + Divider (relative imports) plus kol-loader's
+ * Icon (a package import the relative-import check can't see). */
+
+/**
+ * SpecimenSectionHeader — the shared header every type-specimen section mounts
+ * under. A title (with an optional inline icon) on the left, up to two
+ * controlled dropdowns (weight + style/axis) on the right, and a horizontal
+ * divider beneath. It is the connective tissue that makes the foundry sections
+ * read as one system, so it is built before the sections that consume it.
+ *
+ * Fully controlled and data-free: it holds no font data, only label/badge text,
+ * an icon name, and the two dropdowns' value/onChange pairs supplied by the
+ * parent section. Promoted from the monorepo's route-local `FoundrySection`;
+ * the `Foundry*` name was a route artifact, this name describes the role.
+ *
+ * Title source forks: `label` wins, else `badgeText`. `size` swaps the title
+ * type stop (`sm` → kol-mono-12, else kol-mono-16). Each dropdown is
+ * independently gated; the weight dropdown also requires a non-empty
+ * `weightOptions`.
+ *
+ * Text casing: title and option labels render verbatim as authored — no
+ * text-transform. Author "Roman" / "Italic" / "Character Set" in intended case.
+ *
+ * @param {Object} props
+ * @param {string} props.label - Title text (takes precedence over badgeText).
+ * @param {string} props.badgeText - Fallback title when label is unset.
+ * @param {string} props.icon - KOL Icon name shown after the title; omit to hide.
+ * @param {'sm'|'lg'} props.size - Title type stop (default 'lg').
+ * @param {string} props.selectedStyle - Controlled value of the style/axis dropdown.
+ * @param {Function} props.onStyleChange - Style dropdown change handler.
+ * @param {boolean} props.showDropdown - Render the style/axis dropdown (default true).
+ * @param {Array<{label,value}>} props.styleOptions - Style dropdown options (default Roman/Italic).
+ * @param {string} props.selectedWeight - Controlled value of the weight dropdown.
+ * @param {Function} props.onWeightChange - Weight dropdown change handler.
+ * @param {boolean} props.showWeightDropdown - Gate the weight dropdown (default true; also needs options).
+ * @param {Array<{label,value}>} props.weightOptions - Weight dropdown options (default []).
+ */
+const SpecimenSectionHeader = ({
+  label,
+  badgeText,
+  icon,
+  size = 'lg',
+  selectedStyle,
+  onStyleChange,
+  showDropdown = true,
+  styleOptions = [
+    { label: 'Roman', value: 'roman' },
+    { label: 'Italic', value: 'italic' },
+  ],
+  selectedWeight,
+  onWeightChange,
+  showWeightDropdown = true,
+  weightOptions = [],
+}) => {
+  const title = label || badgeText
+  // kol-mono-text-lg / kol-mono-sm-regular don't exist in the DS theme; the
+  // nearest mono stops are kol-mono-16 (lg) and kol-mono-12 (sm).
+  const titleClass = size === 'sm' ? 'kol-mono-12' : 'kol-mono-16'
+
+  return (
+    <div className="flex flex-col gap-[13px]">
+      <div className="w-full flex flex-row justify-between items-end gap-4">
+        {/* Left: title + optional icon */}
+        <div className="flex items-center gap-3 md:gap-4">
+          <span className={titleClass}>{title}</span>
+          {icon && <Icon name={icon} size={20} />}
+        </div>
+
+        {/* Right: controlled dropdowns */}
+        <div className="flex items-center gap-4">
+          {showWeightDropdown && weightOptions.length > 0 && (
+            <Dropdown options={weightOptions} value={selectedWeight} onChange={onWeightChange} />
+          )}
+          {showDropdown && (
+            <Dropdown options={styleOptions} value={selectedStyle} onChange={onStyleChange} />
+          )}
+        </div>
+      </div>
+
+      <Divider variant="horizontal" />
+    </div>
+  )
+}
+
+export default SpecimenSectionHeader

package/src/organisms/ArticleHeader.jsx

@@ -0,0 +1,95 @@
+import Pill from '../atoms/Pill.jsx'
+import Avatar from '../atoms/Avatar.jsx'
+import Image from '../molecules/Image.jsx'
+
+/**
+ * ArticleHeader — long-form article masthead: a row of tag Pills, a display
+ * title, an author cluster (DS Avatar + name + role), a `date • readingTime`
+ * meta line, an optional excerpt, and an optional hero image. Pure
+ * presentational composition of a flat prop bag.
+ *
+ * De-Sanitized: the four embedded Sanity image-URL builders and the
+ * `resolveImageUrl` unpacker are gone — `heroImage` is a plain resolved src
+ * string handed straight to DS Image (which owns its own missing-asset
+ * fallback). The author avatar is the DS Avatar atom (initials), not a
+ * hand-rolled `<img>` — so `authorInitial` replaces the Sanity `authorImage`.
+ * The app `reveal` entrance utility is dropped.
+ *
+ * Name and meta render uppercase via a presentational class only — strings are
+ * authored as-is at the call site, no JS casing.
+ *
+ * @param {string[]} tags         Pill labels; row hidden when empty
+ * @param {string}   title        display title
+ * @param {string}   authorName   author name (rendered uppercase via class)
+ * @param {string}   authorTitle  author role/title line
+ * @param {string}   authorInitial avatar glyph; defaults to authorName's first char
+ * @param {string}   date         publication date text
+ * @param {string}   readingTime  reading-time text (prefixed `• ` in the meta line)
+ * @param {string}   excerpt      lede paragraph; block hidden when falsy
+ * @param {string}   heroImage    resolved hero image src (omit → no hero block)
+ * @param {string}   className    extra classes on the <header>
+ */
+export default function ArticleHeader({
+  tags = [],
+  title,
+  authorName,
+  authorTitle,
+  authorInitial,
+  date,
+  readingTime,
+  excerpt,
+  heroImage,
+  className = '',
+}) {
+  const initial = authorInitial ?? (authorName ? authorName.trim().charAt(0) : '')
+
+  return (
+    <header className={`pb-12 ${className}`.trim()}>
+      <div className="max-w-[1400px] mx-auto flex flex-col">
+        {tags.length > 0 && (
+          <div className="flex flex-wrap items-center gap-2 pb-6">
+            {tags.map((tag, i) => (
+              <Pill key={i} variant="inverse" size="md">{tag}</Pill>
+            ))}
+          </div>
+        )}
+
+        <div className="flex flex-col gap-6">
+          <h1 className="kol-prose-title text-balance">{title}</h1>
+
+          <div className="flex flex-wrap items-center gap-6 text-fg-64 pb-3">
+            <div className="flex items-center gap-4">
+              <Avatar initial={initial} size="lg" />
+              <div className="flex flex-col">
+                <span className="kol-helper-12 uppercase text-fg-48">{authorName}</span>
+                <span className="kol-mono-12 text-fg-64">{authorTitle}</span>
+              </div>
+            </div>
+            <div className="flex items-center gap-3 kol-helper-12 uppercase text-fg-48">
+              <span>{date}</span>
+              {readingTime && <span>• {readingTime}</span>}
+            </div>
+          </div>
+
+          {excerpt && (
+            <div className="pb-4 w-full lg:w-[80%]">
+              <p className="kol-mono-14 text-fg-64">{excerpt}</p>
+            </div>
+          )}
+
+          {heroImage && (
+            <div className="rounded overflow-hidden border border-fg-08">
+              <Image
+                src={heroImage}
+                alt=""
+                loading="eager"
+                className="object-cover"
+                style={{ width: '100%', aspectRatio: '4/2', objectFit: 'cover' }}
+              />
+            </div>
+          )}
+        </div>
+      </div>
+    </header>
+  )
+}