@kolkrabbi/kol-component 0.41.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.41.0",
+  "version": "0.43.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/AudioPlayer.jsx

@@ -0,0 +1,51 @@
+/**
+ * AudioPlayer — the interactive audio atom: one native <audio> with the UA's
+ * own control strip, and an optional label line above it.
+ *
+ * WHY IT EXISTS. Audio was the one media kind the design system had nothing for,
+ * so every consumer hand-rolled a bare `<audio controls>` and inherited whatever
+ * the browser painted. The MediaLibrary widening (kol-component 0.39.0) made
+ * audio objects arrive — 116 sound files in `kol-vault-media` alone — and left
+ * minting this as the open taxonomy call; this is that call made: an ATOM,
+ * beside HlsVideo.
+ *
+ * THE CONTRAST WITH HlsVideo, which is the thing to read before touching either.
+ * Same tier, same shape — one native media element, all layout via `className`,
+ * no composition — and **inverted intent**. HlsVideo is deliberately inert:
+ * `pointer-events: none`, `controls={false}`, plus the hardening set (no PiP, no
+ * download, no fullscreen, no remote playback, no context menu). It is
+ * decorative. This atom exists **to be operated**, so none of that hardening
+ * crosses over, and `controls` is not a prop — an audio player without controls
+ * is not a variant, it is a different component.
+ *
+ * The native strip is UA-painted and not themeable past `color-scheme`. Do not
+ * reach for pseudo-element hacks; a branded transport would be a separate
+ * `AudioTransport` molecule built on this atom.
+ *
+ * Layout is the call site's: the padding, the centring and the width that lived
+ * in the consumer source are all call-site concerns and none of them are baked
+ * in here.
+ *
+ * @param {string} src        audio URL; renders nothing when absent (the guard
+ *                            style the other media atoms use)
+ * @param {string} [label]    line above the player; the element is omitted entirely
+ *                            when absent. Authored casing — no text-transform
+ * @param {'none'|'metadata'|'auto'} [preload='metadata']  native preload hint
+ * @param {string} [className] all layout/sizing (consumer-supplied)
+ */
+export default function AudioPlayer({
+  src,
+  label,
+  preload = 'metadata',
+  className = '',
+  ...props
+}) {
+  if (!src) return null
+
+  return (
+    <figure className={`kol-audio-player flex flex-col gap-3 ${className}`.trim()}>
+      {label && <figcaption className="kol-mono-12 text-fg-48">{label}</figcaption>}
+      <audio src={src} preload={preload} controls className="w-full" {...props} />
+    </figure>
+  )
+}

package/src/index.js

@@ -33,6 +33,10 @@ export { default as ExitPreview } from './utilities/ExitPreview.jsx'
 export { default as Figure } from './atoms/Figure.jsx'
 export { default as FullscreenOverlay } from './utilities/FullscreenOverlay.jsx'
 export { default as HlsVideo } from './atoms/HlsVideo.jsx'
+/* AudioPlayer — HlsVideo's opposite number: same tier and shape, inverted
+ * intent (built to be operated, not decorative). See its header before editing
+ * either one. */
+export { default as AudioPlayer } from './atoms/AudioPlayer.jsx'
 export { default as Input } from './atoms/Input.jsx'
 export { default as Label } from './atoms/Label.jsx'
 export { default as LabeledControl } from './molecules/LabeledControl.jsx'

package/src/organisms/FeatureSplit.jsx

@@ -16,12 +16,37 @@
  * `text-transform: uppercase` was dropped per KOL casing rules; author those
  * strings in their final case at the call site.
  *
+ * THE SECTION ANATOMY, ONCE (SectionSplit ruling, 2026-08-15). The brief asked
+ * for a new `SectionSplit` — media slot beside kicker/heading/body/actions,
+ * with a flip — and named eleven hand-built kol-website sections as evidence.
+ * That is this component: the anatomy already shipped here, and a second one
+ * beside it would be the very duplication the brief exists to end. It grew the
+ * three things it genuinely lacked instead — `flip`, `titleSize`, `mediaAspect`.
+ *
+ * ON THREADING PER-SITE TYPE CLASSES — the brief's named "core design
+ * question". The answer is that you do not thread one: a consumer picks a ROLE
+ * (`titleSize`), and the component emits exactly one type class for the
+ * heading. Passing `kol-sans-heading-01` in alongside `.kol-feature-split-pull`
+ * would put two equal-specificity rules on one element and let sheet load order
+ * decide the winner — the failure ARCHITECTURE §5 records, and the 2026-07-30
+ * law that a component's type lives in its own rule. `columnClassName` and
+ * friends remain, for LAYOUT.
+ *
  * @param {ReactNode} kicker          mono eyebrow above the title (accent color)
  * @param {ReactNode} title           display pull headline; `<em>` renders as the italic accent
+ * @param {'pull'|'display-01'|'display-02'|'display-03'|'heading-01'|'heading-02'|'heading-03'|'heading-04'|'heading-05'} [titleSize='pull']
+ *   which type ROLE the heading wears — one class, never stacked
  * @param {ReactNode} body            lede paragraph
  * @param {{num: ReactNode, label: string}[]} meta  stats strip (mutually exclusive with `ctas`)
  * @param {ReactNode} ctas            button row (mutually exclusive with `meta`)
- * @param {ReactNode} media           image/video for the visual column; omit to hide it
+ * @param {ReactNode} media           image/video/interactive node for the visual
+ *   column; omit for the text-only section (the /CONNECT band shape)
+ * @param {string}    [mediaAspect='4/5'] aspect ratio of the media frame
+ * @param {boolean}   [mediaHover=false]  zoom the media on frame hover — the same
+ *   1.03 / 300ms / reduced-motion-safe treatment CardFeatureItem uses, so the
+ *   estate has one motion vocabulary instead of a per-section re-decision
+ * @param {boolean}   [flip=false]    media first, text second — the order swaps at
+ *   both widths, so the stacked layout leads with the media too
  * @param {ReactNode} caption         mono caption + gradient veil over the media
  * @param {string}    bgImage         URL for an inline cover background on the section
  * @param {boolean}   fullBleed       span the full viewport width (100vw breakout)
@@ -29,13 +54,29 @@
  * @param {string}    innerClassName  extra classes on the grid wrapper
  * @param {string}    columnClassName extra classes on the text column
  */
+const TITLE_ROLE = {
+  pull: 'kol-feature-split-pull',
+  'display-01': 'kol-sans-display-01',
+  'display-02': 'kol-sans-display-02',
+  'display-03': 'kol-sans-display-03',
+  'heading-01': 'kol-sans-heading-01',
+  'heading-02': 'kol-sans-heading-02',
+  'heading-03': 'kol-sans-heading-03',
+  'heading-04': 'kol-sans-heading-04',
+  'heading-05': 'kol-sans-heading-05',
+}
+
 export default function FeatureSplit({
   kicker,
   title,
+  titleSize = 'pull',
   body,
   meta,
   ctas,
   media,
+  mediaAspect = '4/5',
+  mediaHover = false,
+  flip = false,
   caption,
   bgImage,
   fullBleed = false,
@@ -53,9 +94,14 @@ export default function FeatureSplit({
       style={sectionStyle}
     >
       <div className={`max-w-[1200px] mx-auto grid grid-cols-1 min-[901px]:grid-cols-2 items-center gap-[clamp(48px,6vw,96px)] ${innerClassName}`.trim()}>
-        <div className={`flex flex-col gap-4 max-w-[640px] ${columnClassName}`.trim()}>
+        {/* `order` rather than `flex-row-reverse`: the grid is one column below
+          * 901px, and DOM order is what decides the stack there. Reversing a row
+          * would flip the wide layout and leave the narrow one text-first. */}
+        <div
+          className={`flex flex-col gap-4 max-w-[640px] ${flip ? 'order-2' : ''} ${columnClassName}`.replace(/\s+/g, ' ').trim()}
+        >
           {kicker && <span className="kol-feature-split-kicker">{kicker}</span>}
-          {title && <h1 className="kol-feature-split-pull">{title}</h1>}
+          {title && <h1 className={TITLE_ROLE[titleSize] ?? TITLE_ROLE.pull}>{title}</h1>}
           {body && <p className="kol-feature-split-body">{body}</p>}
           {meta && meta.length > 0 && (
             <div className="kol-feature-split-meta flex flex-wrap gap-y-7 gap-x-12 pt-4">
@@ -70,7 +116,10 @@ export default function FeatureSplit({
           {ctas && <div className="flex flex-wrap gap-4 pt-2">{ctas}</div>}
         </div>
         {media && (
-          <div className="kol-feature-split-visual relative aspect-[4/5] rounded-[var(--kol-radius-sm)] overflow-hidden">
+          <div
+            className={`kol-feature-split-visual relative rounded-[var(--kol-radius-sm)] overflow-hidden ${mediaHover ? 'is-hoverable' : ''} ${flip ? 'order-1' : ''}`.replace(/\s+/g, ' ').trim()}
+            style={{ aspectRatio: mediaAspect }}
+          >
             {media}
             {caption && <div className="kol-feature-split-visual-veil" aria-hidden="true" />}
             {caption && <span className="kol-feature-split-visual-caption">{caption}</span>}