npm - @kolkrabbi/kol-component - Versions diffs - 0.80.0 → 0.81.0 - Mend

@kolkrabbi/kol-component 0.80.0 → 0.81.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/package.json +1 -1
package/src/hooks/useSectionTheme.js +61 -0
package/src/organisms/SectionCards.jsx +8 -1
package/src/organisms/SectionHero.jsx +48 -4
package/src/organisms/SectionSplit.jsx +9 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.80.0",
+  "version": "0.81.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/hooks/useSectionTheme.js ADDED Viewed

@@ -0,0 +1,61 @@
+import { useEffect, useRef, useState } from 'react'
+/**
+ * useSectionTheme — the `theme` prop of the section organisms (SectionThemeInverse,
+ * kol-website 2026-08-27).
+ *
+ *   undefined  inherit — nothing stamped
+ *   'light' | 'dark'  pinned — the section carries `data-theme`, and the theme's
+ *              subtree scopes (kol-theme ≥0.52.0: surfaces, fg ramp, roles, oq,
+ *              borders all re-resolve on a stamped element) do the rest
+ *   'inverse'  the PAIRED theme of the nearest live one — a light page gets a
+ *              dark section, a dark page a light one — and it follows the
+ *              toggle: an observer on <html> and the system-scheme query re-read
+ *              the live theme, so the section flips with the page.
+ *
+ * Resolved in JS rather than CSS on purpose: the theme scopes already exist,
+ * so stamping the RIGHT one is 20 lines; expressing "the other one" in CSS
+ * means a twin of every surface token in every theme block and no nesting.
+ * Here nesting works — an inverse inside an inverse reads the stamped
+ * ancestor and flips back.
+ *
+ * Every token resolves on the stamped element, so Buttons, Pills, the glass
+ * panel — anything reading `--kol-*` — flip for free. No inverse classes.
+ *
+ * @returns [ref, resolvedTheme]  put `ref` on the section root and stamp
+ *   `data-theme={resolvedTheme}` (undefined stamps nothing)
+ */
+const htmlTheme = () => {
+  if (typeof document === 'undefined') return 'light'
+  const root = document.documentElement
+  const stamped = root.dataset.theme || (root.classList.contains('dark') ? 'dark' : root.classList.contains('light') ? 'light' : null)
+  if (stamped) return stamped
+  return window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+const nearestTheme = (el) => {
+  const scope = el?.parentElement?.closest('[data-theme], .dark, .light')
+  if (scope && scope !== document.documentElement) {
+    return scope.dataset.theme || (scope.classList.contains('dark') ? 'dark' : 'light')
+  }
+  return htmlTheme()
+}
+export default function useSectionTheme(theme) {
+  const ref = useRef(null)
+  const [live, setLive] = useState(htmlTheme)
+  useEffect(() => {
+    if (theme !== 'inverse') return undefined
+    const read = () => setLive(nearestTheme(ref.current))
+    read()
+    const mo = new MutationObserver(read)
+    mo.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme', 'class'] })
+    const mq = window.matchMedia?.('(prefers-color-scheme: dark)')
+    mq?.addEventListener('change', read)
+    return () => { mo.disconnect(); mq?.removeEventListener('change', read) }
+  }, [theme])
+  const resolved = theme === 'inverse' ? (live === 'dark' ? 'light' : 'dark') : theme
+  return [ref, resolved]
+}

package/src/organisms/SectionCards.jsx CHANGED Viewed

@@ -1,5 +1,6 @@
 import SectionCardItem from '../molecules/SectionCardItem.jsx'
 import SectionText, { HEADLINE_ROLE } from '../molecules/SectionText.jsx'
+import useSectionTheme from '../hooks/useSectionTheme.js'
 /**
  * SectionCards — the "N-up feature cards" band: a `SectionText` header over a
@@ -13,6 +14,10 @@ import SectionText, { HEADLINE_ROLE } from '../molecules/SectionText.jsx'
  * nodes. Card links are plain anchors; pass `onNavigate` to intercept same-tab
  * navigations in an SPA. The label is uppercase by role; the rest as authored.
  *
+ * @param {'inverse'|'light'|'dark'} theme  the section's theme scope (SectionThemeInverse, 2026-08-27):
+ *   `inverse` = the paired theme of the nearest live one, following the toggle;
+ *   `light` / `dark` pinned; omit to inherit. Stamps `data-theme` on the root and
+ *   paints its surface — every token inside resolves to the other theme's.
  * @param {{title, icon, visual, description, href, backgroundColor, imageAspectRatio}[]} features
  * @param {ReactNode} label · headline · body   the header (heading-03 + mono lede by default)
  * @param {ReactNode} actions               centred action row under the cards
@@ -23,6 +28,7 @@ import SectionText, { HEADLINE_ROLE } from '../molecules/SectionText.jsx'
  * @param {string}    sectionClassName · wrapperClassName · cardsWrapperClassName · actionsClassName · headerClassName · headerTextWidthClass  layout seams
  */
 export default function SectionCards({
+  theme,
   features = [],
   label,
   headline,
@@ -45,8 +51,9 @@ export default function SectionCards({
   headerClassName = 'w-full pt-[224px]',
   headerTextWidthClass = 'w-full md:w-[30%]',
 }) {
+  const [themeRef, themeStamp] = useSectionTheme(theme)
   return (
-    <section className={`w-full ${sectionClassName}`.trim()}>
+    <section ref={themeRef} data-theme={themeStamp} className={`w-full ${theme ? 'bg-surface-primary' : ''} ${sectionClassName}`.replace(/\s+/g, ' ').trim()}>
       <div className={wrapperClassName}>
         {(label || headline || body) && (
           <SectionText

package/src/organisms/SectionHero.jsx CHANGED Viewed

@@ -6,6 +6,7 @@ import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
 import ContentMedia from '../molecules/ContentMedia.jsx'
 import SectionText from '../molecules/SectionText.jsx'
 import FeaturedCarousel from './FeaturedCarousel.jsx'
+import useSectionTheme from '../hooks/useSectionTheme.js'
 /* Height presets (SectionHeroRound2, user ruling 2026-08-26): three tiers in
  * viewport units, each with a phone value the DS picks. `full` sits UNDER a
@@ -22,6 +23,20 @@ const HEIGHTS = {
   md: 'h-[320px] md:h-[440px]',
 }
+/* The SPLIT variant's presets as LITERALS (SectionHeroSplitHeight, kol-website
+ * 2026-08-26). 0.76.0 rewrote HEIGHTS to min-h-* at runtime — a string no
+ * source file carries, so Tailwind's scanner never emitted it and every
+ * split preset was dead: the Studio hero rendered its text column's 175px.
+ * A class Tailwind cannot see is not a class. */
+const SPLIT_HEIGHTS = {
+  full: 'min-h-dvh',
+  80: 'min-h-[70svh] md:min-h-[80vh]',
+  60: 'min-h-[50svh] md:min-h-[60vh]',
+  screen: 'min-h-dvh',
+  lg: 'min-h-dvh',
+  md: 'min-h-[50svh] md:min-h-[60vh]',
+}
 /**
  * Background layer: a media descriptor becomes a cover-fit Image / HlsVideo /
  * inert <video> (`.kol-full-bleed-hero-media` pins it absolute + object-cover
@@ -95,6 +110,10 @@ function MediaLayer({ media }) {
  * glass panel per slide, autoplay, prev/next); and NO media renders the
  * composed text on the surface with no glass panel — the text-only hero.
  *
+ * @param {'inverse'|'light'|'dark'} theme  the section's theme scope (SectionThemeInverse, 2026-08-27):
+ *   `inverse` = the paired theme of the nearest live one, following the toggle;
+ *   `light` / `dark` pinned; omit to inherit. Stamps `data-theme` on the root and
+ *   paints its surface — every token inside resolves to the other theme's.
  * @param {'media'|'split'} variant
  * @param {ReactNode|{src, kind, poster, srcSet, alt}|Array} media  background (media) / the half (split) / an ARRAY of slides → carousel
  * @param {number}    overlayOpacity 0–100 surface-primary scrim over the media (default 0)
@@ -125,6 +144,7 @@ function MediaLayer({ media }) {
  */
 export default function SectionHero({
   variant = 'media',
+  theme,
   fullBleed = false,
   media,
   overlayOpacity = 0,
@@ -163,6 +183,9 @@ export default function SectionHero({
   align = 'center',
   className = '',
 }) {
+  const [themeRef, themeStamp] = useSectionTheme(theme)
+  const themed = theme ? 'bg-surface-primary' : ''
   if (variant === 'split') {
     const mediaFirst = align !== 'right'
     const bleed = fullBleed ? 'w-screen ml-[calc(50%-50vw)]' : 'w-full'
@@ -172,8 +195,10 @@ export default function SectionHero({
         ? <ContentMedia ratio={null} radius={false} fit="cover" className="h-full">{media}</ContentMedia>
         : <MediaLayer media={media} />
     return (
-      <section className={`kol-section-hero-split grid grid-cols-1 md:grid-cols-2 ${(HEIGHTS[height === 'lg' ? 'full' : height] || height).replace(/\bh-/g, 'min-h-')} ${bleed} ${className}`.replace(/\s+/g, ' ').trim()}>
-        <div className={`relative min-h-[50vh] overflow-hidden md:min-h-0 ${mediaFirst ? '' : 'md:order-2'}`.trim()}>{mediaNode}</div>
+      <section ref={themeRef} data-theme={themeStamp} className={`kol-section-hero-split grid grid-cols-1 md:grid-cols-2 ${themed} ${SPLIT_HEIGHTS[height] || height} ${bleed} ${className}`.replace(/\s+/g, ' ').trim()}>
+        {/* the half sizes itself off the grid row (`h-full min-h-0`) so an
+          * absolute media node — the descriptor's cover-fit img — fills it */}
+        <div className={`relative h-full min-h-[50vh] overflow-hidden md:min-h-0 ${mediaFirst ? '' : 'md:order-2'}`.trim()}>{mediaNode}</div>
         <div className={`flex items-center justify-center p-10 ${mediaFirst ? '' : 'md:order-1'}`.trim()}>
           {/* BARE — the molecule's own voice; `headlineCase="upper"` is the
             * split hero's one trait, a role on SectionText (SectionHeroNoOverrides) */}
@@ -218,6 +243,24 @@ export default function SectionHero({
   if (Array.isArray(media)) {
     const items = media.map((s) => (s.media ? s : { ...s, media: { src: s.src, kind: s.kind, poster: s.poster, srcSet: s.srcSet, alt: s.alt } }))
     return withFoot(
+      theme ? (
+        <div ref={themeRef} data-theme={themeStamp} className={themed}>
+          <FeaturedCarousel
+            items={items}
+            fullWidth
+            rounded={false}
+            showHeader={false}
+            height={heightCls}
+            autoPlay={autoPlay}
+            autoPlayInterval={autoPlayInterval}
+            navPosition={navPosition}
+            {...Object.fromEntries(Object.entries({ renderTitle, ctaLabel, onNavigate, showTitle, showDescription, showCta, titleClassName, descriptionClassName, options }).filter(([, v]) => v !== undefined))}
+            className={`kol-section-hero-carousel ${fullBleed ? 'w-screen ml-[calc(50%-50vw)]' : ''} ${className}`.replace(/\s+/g, ' ').trim()}
+          >
+            {children}
+          </FeaturedCarousel>
+        </div>
+      ) : (
       <FeaturedCarousel
         items={items}
         fullWidth
@@ -231,7 +274,8 @@ export default function SectionHero({
         className={`kol-section-hero-carousel ${fullBleed ? 'w-screen ml-[calc(50%-50vw)]' : ''} ${className}`.replace(/\s+/g, ' ').trim()}
       >
         {children}
-      </FeaturedCarousel>,
+      </FeaturedCarousel>
+      ),
     )
   }
@@ -268,7 +312,7 @@ export default function SectionHero({
   const justifyCls = justify === 'end' ? 'items-end pb-32 sm:pb-40 lg:pb-48 xl:pb-56' : 'items-center'
   return withFoot(
-    <section className={`kol-full-bleed-hero relative isolate w-full overflow-hidden ${heightCls} ${fullBleed ? 'w-screen ml-[calc(50%-50vw)]' : ''} ${className}`.replace(/\s+/g, ' ').trim()}>
+    <section ref={themeRef} data-theme={themeStamp} className={`kol-full-bleed-hero relative isolate w-full overflow-hidden ${themed} ${heightCls} ${fullBleed ? 'w-screen ml-[calc(50%-50vw)]' : ''} ${className}`.replace(/\s+/g, ' ').trim()}>
       <MediaLayer media={media} />
       {overlayOpacity > 0 && (
         <div

package/src/organisms/SectionSplit.jsx CHANGED Viewed

@@ -1,4 +1,5 @@
 import SectionText from '../molecules/SectionText.jsx'
+import useSectionTheme from '../hooks/useSectionTheme.js'
 /**
  * SectionSplit — the media-and-text split section, on `SectionText` (the
@@ -17,6 +18,10 @@ import SectionText from '../molecules/SectionText.jsx'
  * `media` is passed, and `caption` gates both the gradient veil and the
  * caption element. The label is uppercase by role; the rest renders as authored.
  *
+ * @param {'inverse'|'light'|'dark'} theme  the section's theme scope (SectionThemeInverse, 2026-08-27):
+ *   `inverse` = the paired theme of the nearest live one, following the toggle;
+ *   `light` / `dark` pinned; omit to inherit. Stamps `data-theme` on the root and
+ *   paints its surface — every token inside resolves to the other theme's.
  * @param {ReactNode} label        mono eyebrow above the headline (accent)
  * @param {ReactNode} headline     display pull; `<em>` renders as the italic accent
  * @param {string}    [headlineSize='pull']  which type ROLE the heading wears
@@ -40,6 +45,7 @@ import SectionText from '../molecules/SectionText.jsx'
  * @param {string}    className · innerClassName · columnClassName  layout seams
  */
 export default function SectionSplit({
+  theme,
   label,
   headline,
   headlineSize = 'pull',
@@ -61,6 +67,7 @@ export default function SectionSplit({
   innerClassName = '',
   columnClassName = '',
 }) {
+  const [themeRef, themeStamp] = useSectionTheme(theme)
   const sectionStyle = bgImage
     ? { backgroundImage: `url(${bgImage})`, backgroundSize: 'cover', backgroundPosition: 'center' }
     : undefined
@@ -72,6 +79,8 @@ export default function SectionSplit({
     : 'grid grid-cols-1 min-[901px]:grid-cols-2 items-center gap-[clamp(48px,6vw,96px)]'
   return (
     <section
+      ref={themeRef}
+      data-theme={themeStamp}
       className={`kol-section-split px-5 py-16 md:px-8 md:py-24 lg:px-14 lg:py-32 ${bleed} ${className}`.replace(/\s+/g, ' ').trim()}
       style={sectionStyle}
     >