@kolkrabbi/kol-component 0.40.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.40.0",
+  "version": "0.42.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/index.js

@@ -100,6 +100,10 @@ export { default as GalleryCarousel } from './organisms/GalleryCarousel.jsx'
 export { default as AsciiCursor } from './utilities/AsciiCursor.jsx'
 export { default as BentoCard } from './molecules/BentoCard.jsx'
 export { default as Carousel } from './molecules/Carousel.jsx'
+/* EmblaNav — THE prev/next pair. Exported so a consumer building its own embla
+ * stage reaches for it instead of re-typing the button markup, which is how the
+ * three in-package copies (and kol-website's CarouselNavigation) happened. */
+export { default as EmblaNav } from './molecules/EmblaNav.jsx'
 export { default as ContentFilters } from './organisms/ContentFilters.jsx'
 export { default as CtaGlobal } from './organisms/CtaGlobal.jsx'
 export { default as ErrorBoundary } from './utilities/ErrorBoundary.jsx'

package/src/molecules/Carousel.jsx

@@ -1,5 +1,6 @@
 import { Children, useCallback, useEffect, useState } from 'react'
 import useEmblaCarousel from 'embla-carousel-react'
+import EmblaNav from './EmblaNav.jsx'
 
 export default function Carousel({ children, options = { align: 'start', loop: false, dragFree: true, containScroll: 'trimSnaps' }, className = '' }) {
   const [emblaRef, emblaApi] = useEmblaCarousel(options)
@@ -29,22 +30,12 @@ export default function Carousel({ children, options = { align: 'start', loop: f
           ))}
         </div>
       </div>
-      <div className="kol-embla-controls">
-        <button
-          type="button"
-          className="kol-embla-btn border border-fg-16 hover:border-fg-32 text-auto"
-          aria-label="Previous"
-          onClick={() => emblaApi?.scrollPrev()}
-          disabled={!canPrev}
-        >‹</button>
-        <button
-          type="button"
-          className="kol-embla-btn border border-fg-16 hover:border-fg-32 text-auto"
-          aria-label="Next"
-          onClick={() => emblaApi?.scrollNext()}
-          disabled={!canNext}
-        >›</button>
-      </div>
+      <EmblaNav
+        onPrev={() => emblaApi?.scrollPrev()}
+        onNext={() => emblaApi?.scrollNext()}
+        canPrev={canPrev}
+        canNext={canNext}
+      />
     </div>
   )
 }

package/src/molecules/EmblaNav.jsx

@@ -0,0 +1,51 @@
+import { Icon } from '@kolkrabbi/kol-icons'
+
+/**
+ * EmblaNav — THE prev/next pair for an embla carousel.
+ *
+ * WHY IT EXISTS. Three components hand-wrote the same
+ * `.kol-embla-btn border border-fg-16 hover:border-fg-32 text-auto` string with
+ * their own aria labels, and two of them used the literal text glyphs `‹` and
+ * `›` as the arrows — in a design system that ships a chevron icon set. The
+ * FeaturedCarousel reconciliation (2026-08-15) found the consumer's fork had
+ * built its own `CarouselNavigation` for precisely that reason: it wanted real
+ * icons. Rather than fold that file in beside three copies of the markup, the
+ * markup became one component. Same failure RailSection fixed for rails — a
+ * class is vocabulary, not grammar.
+ *
+ * MediaViewer keeps its own chips deliberately: they are absolutely positioned
+ * over an inverse-tier scrim, which is a different control, not this one.
+ *
+ * @param {Function} onPrev · @param {Function} onNext
+ * @param {boolean}  [canPrev=true] · @param {boolean} [canNext=true]  disabled state
+ * @param {number}   [size=16]      chevron size
+ * @param {'stack'|'inline'} [placement='stack']  `inline` drops the top gap and
+ *   the end-alignment for a header row; `stack` sits under the viewport
+ * @param {string}   [prevLabel='Previous'] · @param {string} [nextLabel='Next']
+ */
+export default function EmblaNav({
+  onPrev,
+  onNext,
+  canPrev = true,
+  canNext = true,
+  size = 16,
+  placement = 'stack',
+  prevLabel = 'Previous',
+  nextLabel = 'Next',
+  className = '',
+}) {
+  const btn = 'kol-embla-btn border border-fg-16 hover:border-fg-32 text-auto'
+
+  return (
+    <div
+      className={`kol-embla-controls ${placement === 'inline' ? 'is-inline' : ''} ${className}`.trim()}
+    >
+      <button type="button" className={btn} aria-label={prevLabel} onClick={onPrev} disabled={!canPrev}>
+        <Icon name="chevron-left" size={size} />
+      </button>
+      <button type="button" className={btn} aria-label={nextLabel} onClick={onNext} disabled={!canNext}>
+        <Icon name="chevron-right" size={size} />
+      </button>
+    </div>
+  )
+}

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>}

package/src/organisms/FeaturedCarousel.jsx

@@ -2,6 +2,7 @@ import { isValidElement, useCallback, useEffect, useState } from 'react'
 import useEmblaCarousel from 'embla-carousel-react'
 import Image from '../atoms/Image.jsx'
 import HlsVideo from '../atoms/HlsVideo.jsx'
+import EmblaNav from '../molecules/EmblaNav.jsx'
 import OverlayGlassPanel from '../utilities/OverlayGlassPanel.jsx'
 
 /**
@@ -85,17 +86,42 @@ function SlideMedia({ media, onEnded, onTimeUpdate }) {
  * CTA is a plain anchor styled with the DS button classes plus an `onNavigate`
  * seam (router-agnostic — call `preventDefault` inside it for SPA nav).
  *
- * @param {Array}    items            slides: `{ media: { src, kind: 'image'|'video', poster, srcSet, alt }, title, description, href, ctaLabel, titleClassName }`
+ * RECONCILED 2026-08-15 against kol-website's fork (231L vs 259L, 458 diff
+ * lines). They were never a fork — two different engines. The fork ran
+ * framer-motion `AnimatePresence` over an index, which means **no drag at all**;
+ * this one runs embla, so the canon call went to the engine here, and with it
+ * the `{ media }` descriptor, OverlayGlassPanel, and the progress ring. Five
+ * capabilities crossed the other way — `children`, `fullWidth`, `rounded`, the
+ * `show*` visibility toggles and `subtitle` — plus the header nav placement.
+ * Deliberately NOT carried: the foundry title coupling (a size ramp keyed on
+ * the literal strings 'Málrómur'/'Tröllatunga' and a per-typeface inline
+ * `fontFamily`), `kol-label-mono-xs` (a deleted legacy family), and the hidden
+ * block that eagerly preloaded every slide image — embla plus `loading="eager"`
+ * on the visible slide covers that without fetching a whole gallery up front.
+ *
+ * @param {Array}    items            slides: `{ media: { src, kind: 'image'|'video', poster, srcSet, alt }, title, subtitle, description, href, ctaLabel, titleClassName, descriptionClassName, showTitle, showDescription, showCta }`
  * @param {string}   sectionLabel     header label (default 'Featured')
  * @param {string}   ctaLabel         default CTA copy; per-item `ctaLabel` overrides (default 'Learn more')
  * @param {string}   height           slide-frame height class (default 'h-[440px] md:h-[640px]')
  * @param {Function} renderTitle      custom title renderer `(item) => ReactNode`; wins over the default
  * @param {string}   titleClassName   default title class; per-item `titleClassName` overrides
+ * @param {string}   descriptionClassName default description class; per-item overrides
  * @param {boolean}  showHeader       show the label + `n / total` counter bar (default true)
+ * @param {boolean}  showTitle        global title visibility; per-item `showTitle` overrides (default true)
+ * @param {boolean}  showDescription  global description visibility; per-item overrides (default true)
+ * @param {boolean}  showCta          global CTA visibility; per-item `showCta` overrides (default true)
+ * @param {boolean}  fullWidth        drop the section's own vertical padding — the
+ *                                    slide frame spans its container (default false)
+ * @param {boolean}  rounded          frame border + radius (default true)
+ * @param {'stack'|'header'} navPosition  prev/next under the viewport, or in the
+ *                                    header row beside the counter (default 'stack')
  * @param {boolean}  autoPlay         auto-advance: timer for image slides, `ended` for video slides (default false)
  * @param {number}   autoPlayInterval image-slide timer in ms (default 5000)
  * @param {Function} onNavigate       `(href, event) => void` CTA click seam for SPA routing
  * @param {Object}   options          embla options passthrough (default `{ align: 'center', loop: true }`)
+ * @param {node}     children         a STATIC overlay pinned over the stage — it does
+ *                                    not travel with the slides (pointer-events pass
+ *                                    through except on the child itself)
  * @param {string}   className        extra classes on the section
  */
 export default function FeaturedCarousel({
@@ -105,11 +131,19 @@ export default function FeaturedCarousel({
   height = 'h-[440px] md:h-[640px]',
   renderTitle,
   titleClassName = '',
+  descriptionClassName = '',
   showHeader = true,
+  showTitle = true,
+  showDescription = true,
+  showCta = true,
+  fullWidth = false,
+  rounded = true,
+  navPosition = 'stack',
   autoPlay = false,
   autoPlayInterval = 5000,
   onNavigate,
   options = { align: 'center', loop: true },
+  children,
   className = '',
 }) {
   const [emblaRef, emblaApi] = useEmblaCarousel(options)
@@ -175,17 +209,32 @@ export default function FeaturedCarousel({
 
   const showProgress = autoPlay && items.length > 1
 
+  const nav = (
+    <EmblaNav
+      onPrev={() => emblaApi?.scrollPrev()}
+      onNext={() => emblaApi?.scrollNext()}
+      canPrev={canPrev}
+      canNext={canNext}
+      placement={navPosition === 'header' ? 'inline' : 'stack'}
+      prevLabel="Previous slide"
+      nextLabel="Next slide"
+    />
+  )
+
   return (
     <section
-      className={`kol-featured-carousel w-full ${className}`.trim()}
+      className={`kol-featured-carousel w-full ${fullWidth ? '' : 'py-16'} ${className}`.trim()}
       onMouseEnter={autoPlay ? () => setPaused(true) : undefined}
       onMouseLeave={autoPlay ? () => setPaused(false) : undefined}
     >
       {showHeader && (
-        <div className="mb-6 flex items-center gap-4">
-          {/* migrated off the deleted legacy kol-label-* family — label renders as authored */}
-          <span className="kol-helper-12 text-auto">{sectionLabel}</span>
-          <span className="kol-mono-12 text-fg-64">{selectedIndex + 1} / {items.length}</span>
+        <div className="mb-6 flex items-center justify-between gap-4">
+          <div className="flex items-center gap-4">
+            {/* migrated off the deleted legacy kol-label-* family — label renders as authored */}
+            <span className="kol-helper-12 text-auto">{sectionLabel}</span>
+            <span className="kol-mono-12 text-fg-64">{selectedIndex + 1} / {items.length}</span>
+          </div>
+          {navPosition === 'header' && nav}
         </div>
       )}
 
@@ -206,7 +255,9 @@ export default function FeaturedCarousel({
                 const active = i === selectedIndex
                 return (
                   <div key={i} className="kol-embla-slide">
-                    <div className={`relative overflow-hidden rounded border border-fg-08 bg-surface-secondary ${height}`}>
+                    <div
+                      className={`relative overflow-hidden bg-surface-secondary ${rounded ? 'rounded border border-fg-08' : ''} ${height}`.replace(/\s+/g, ' ')}
+                    >
                       <SlideMedia
                         media={item.media}
                         onEnded={autoPlay && items.length > 1 && active ? advance : undefined}
@@ -214,11 +265,18 @@ export default function FeaturedCarousel({
                       />
                       <div className="relative z-10 flex h-full w-full items-center justify-center p-6">
                         <OverlayGlassPanel maxWidth="max-w-[600px]">
-                          {renderTitleNode(item)}
-                          {item.description && (
-                            <p className="kol-mono-12 text-auto max-w-[600px]">{item.description}</p>
+                          {(item.showTitle ?? showTitle) && renderTitleNode(item)}
+                          {item.subtitle && (
+                            <span className="kol-mono-10 text-fg-64">{item.subtitle}</span>
                           )}
-                          {item.href && (
+                          {(item.showDescription ?? showDescription) && item.description && (
+                            <p
+                              className={`kol-mono-12 text-auto max-w-[600px] ${item.descriptionClassName || descriptionClassName}`.trim()}
+                            >
+                              {item.description}
+                            </p>
+                          )}
+                          {(item.showCta ?? showCta) && item.href && (
                             <a
                               href={item.href}
                               onClick={onNavigate ? (e) => onNavigate(item.href, e) : undefined}
@@ -235,24 +293,18 @@ export default function FeaturedCarousel({
               })}
             </div>
           </div>
-        </div>
 
-        <div className="kol-embla-controls">
-          <button
-            type="button"
-            className="kol-embla-btn border border-fg-16 hover:border-fg-32 text-auto"
-            aria-label="Previous"
-            onClick={() => emblaApi?.scrollPrev()}
-            disabled={!canPrev}
-          >‹</button>
-          <button
-            type="button"
-            className="kol-embla-btn border border-fg-16 hover:border-fg-32 text-auto"
-            aria-label="Next"
-            onClick={() => emblaApi?.scrollNext()}
-            disabled={!canNext}
-          >›</button>
+          {/* Pinned over the stage, OUTSIDE the viewport — a caption or badge
+            * that must not travel with the slides. Clicks pass through except
+            * on the child itself. */}
+          {children && (
+            <div className="pointer-events-none absolute inset-0 z-20 overflow-hidden">
+              <div className="pointer-events-auto w-full">{children}</div>
+            </div>
+          )}
         </div>
+
+        {navPosition !== 'header' && nav}
       </div>
     </section>
   )