@kolkrabbi/kol-component 0.191.0 → 0.192.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.191.0",
+  "version": "0.192.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/organisms/SectionSplit.jsx

@@ -1,4 +1,5 @@
 import SectionText from '../molecules/SectionText.jsx'
+import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
 import { FULL_BLEED } from './sectionBleed.js'
 import { surfaceClass } from '../utilities/sectionSurface.js'
 import useSectionTheme from '../hooks/useSectionTheme.js'
@@ -14,8 +15,19 @@ import { minHeightClass } from './sectionHeights.js'
  *   'right'  media on the right, text on the left — the default
  *   'left'   media first (the old `flip`)
  *   'center' ONE column: text centred, media below
+ *   'top'    ONE column: media ABOVE the text, both centred
+ *   'bottom' ONE column: text above, media below — the explicit name for what
+ *            `center` has always rendered, kept as its own value because
+ *            "centred" says where the column sits and nothing about the order
  * One anatomy, one prop — not a third component.
  *
+ * THE VERTICAL PAIR (section-split-vertical-align, kol-client-hrafn
+ * 2026-09-03). The filer asked what `center` renders when `media` is passed and
+ * could not tell from the source: it STACKS, text first, media below, capped at
+ * 640. So `bottom` already existed under a name that did not say so, and only
+ * `top` was missing. Both are values a page can name now, and `center` keeps
+ * its behaviour exactly, so no existing call moves.
+ *
  * `meta` and `actions` are mutually exclusive by intent (pick one); `actions`
  * is conventionally a row of KOL Buttons. The media column renders only when
  * `media` is passed, and `caption` gates both the gradient veil and the
@@ -59,7 +71,8 @@ import { minHeightClass } from './sectionHeights.js'
  *   than only in `fill`, because a prop that silently does nothing in the default form is a
  *   seam wired to nothing. Unset, each form keeps exactly what it did: `fill` centres,
  *   bounded follows `align` (centred when `align="center"`, else start).
- * @param {'right'|'left'|'center'} [align='right']  media side, or centred single column
+ * @param {'right'|'left'|'center'|'top'|'bottom'} [align='right']  media side, or a centred single column: `top` puts the media above the text, `center` and `bottom` below it
+ * @param {boolean|ReactNode} [placeholder=false]  what stands in when `media` is absent — `true` renders the DS `AssetPlaceholder` at the frame's ratio, a node renders itself. OFF by default: a text-only `SectionSplit` is a real and common call, and injecting a visible box into every one of them estate-wide is not a fix (section-split-vertical-align, kol-client-hrafn 2026-09-03, which asked for the placeholder and gets it opt-in)
  * @param {'full'|'80'|'60'|string} [height='60']  min-height on the family's ladder — full = 100dvh,
  *   80 = 70svh / 80vh, 60 = 50svh / 60vh (default), 40 = 35svh / 40vh; the columns stay vertically centred inside it
  * @param {ReactNode} caption      mono caption + gradient veil over the media
@@ -87,6 +100,7 @@ export default function SectionSplit({
   mediaHover = false,
   mediaClip = true,
   align = 'right',
+  placeholder = false,
   textAlign,
   fill = false,
   height = '60',
@@ -106,8 +120,13 @@ export default function SectionSplit({
     ? { backgroundImage: `url(${bgImage})`, backgroundSize: 'cover', backgroundPosition: 'center' }
     : undefined
   const bleed = fullBleed ? FULL_BLEED : ''
-  const centred = align === 'center'
-  const mediaFirst = align === 'left'
+  /* the three single-column forms — `center` and `bottom` are one layout under
+   * two names, `top` reverses the order */
+  const centred = align === 'center' || align === 'top' || align === 'bottom'
+  /* `order-*` and not DOM order: the grid is one column in every centred form
+   * and below 901px, and the order utilities are what lift the media above the
+   * text for `left` and `top` alike. */
+  const mediaFirst = align === 'left' || align === 'top'
   /* unset = each form's own prior behaviour, so nothing existing moves */
   const fillText = textAlign ?? 'center'
   const boundedText = textAlign ?? (centred ? 'center' : 'start')
@@ -206,7 +225,7 @@ export default function SectionSplit({
             </div>
           )}
         </SectionText>
-        {media && (
+        {(media || placeholder) && (
           /* height = the rung minus the padding; width follows the ratio and
            * caps at the column — the media takes its size from the section,
            * never gives it */
@@ -235,7 +254,9 @@ export default function SectionSplit({
             className={`kol-section-split-visual relative w-full max-w-full justify-self-center rounded-[var(--kol-radius-sm)] min-[901px]:h-[calc(var(--kol-section-h,60vh)_-_2*var(--kol-section-py,4rem))] ${mediaClip ? 'overflow-hidden' : ''} ${mediaHover ? 'is-hoverable' : ''} ${mediaFirst ? 'order-1' : ''} ${centred ? 'max-w-[640px]' : ''}`.replace(/\s+/g, ' ').trim()}
             style={{ aspectRatio: ratio }}
           >
-            {media}
+            {media ?? (placeholder === true
+              ? <AssetPlaceholder className="h-full w-full" />
+              : placeholder)}
             {caption && <div className="kol-section-split-visual-veil" aria-hidden="true" />}
             {caption && <span className="kol-section-split-visual-caption">{caption}</span>}
           </div>