@kolkrabbi/kol-component 0.174.0 → 0.175.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.174.0",
+  "version": "0.175.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/molecules/PageHeader.jsx

@@ -1,3 +1,4 @@
+import SectionText from './SectionText.jsx'
 /**
  * PageHeader — the page's masthead: an optional eyebrow, the title, and a
  * sub-line.
@@ -64,6 +65,8 @@
  * The bottom rhythm is `--kol-page-header-mb` (default 40px): inline, as before, but through a
  * variable a consumer can re-point where an inline literal could only be `!important`-ed.
  */
+/* the title role per size and voice — the one thing PageHeader knows that the
+ * base does not, because the base's ladder is the SECTION scale */
 const TITLE = {
   sans: { sm: 'kol-sans-heading-03', md: 'kol-sans-display-03', lg: 'kol-sans-display-02' },
   mono: { sm: 'kol-mono-heading-03', md: 'kol-mono-display-03', lg: 'kol-mono-display-02' },
@@ -73,63 +76,29 @@ const LEDE = { app: 'kol-mono-14', site: 'kol-sans-body-01' }
 
 export default function PageHeader({ eyebrow, title, subtitle, actions, subtitleMaxWidth, size = 'md', voice = 'sans', register = 'app', titleClass, className = '' }) {
   const roles = TITLE[voice] ?? TITLE.sans
-  const h1 = <h1 className={`text-fg-96 ${titleClass ?? roles[size] ?? roles.md}`}>{title}</h1>
-  const lede = subtitle && <p className={`text-oq-64 ${LEDE[register] ?? LEDE.app} min-w-0`} style={{ marginTop: actions ? undefined : 12, maxWidth: subtitleMaxWidth }}>{subtitle}</p>
-  /* The cluster shares a baseline row with the lede (or the title): flexbox
-     exposes a flex item's FIRST baseline, so putting them in one row is the one
-     way to land on the subtitle's line rather than the h1's.
-     
-     AND IT CONTRIBUTES NO HEIGHT (PageHeaderActionsGrowsBlock, kol-fxr
-     2026-08-28). A flex row takes its tallest child, so a cluster of `sm`
-     controls (28px since kol-theme 0.90.0) against a one-line `kol-mono-14`
-     lede (18px) made the masthead 10px taller — measured, monitor's `/` at 65.2
-     against fxr's `/settings` at 75.2 with identical titles. The masthead is the
-     one block every page of an app shares, so a page with a control cluster sat
-     10px lower than every page without one, with no way to opt out.
-     
-     `h-0` + `self-center` is the fix and it is not a magic number: a zero-height
-     box centred on the row makes the children overflow it symmetrically, so the
-     row's height is the TEXT's and the cluster is free at any rung (the gap is
-     10px at `sm`, 14 at `md` — a constant would have been wrong). Horizontal
-     layout is untouched: the box still takes its width, so `justify-between`
-     holds and a long lede cannot run under the controls. */
-  const cluster = actions && <div className="flex items-center gap-4 shrink-0 h-0 self-center">{actions}</div>
   return (
     /* the block owns its own rhythm — margins inline, never in a shared type
        class, which leaks estate-wide (ShellHeaderFilterRefinements, 2026-08-15) */
-    <header className={`flex flex-col ${className}`.trim()} style={{ marginBottom: 'var(--kol-page-header-mb, 40px)' }}>
-      {eyebrow && (
-        /* HELPER, not mono (user ruling 2026-08-15). An eyebrow is single-line
-           chrome — that is the whole definition of the `kol-helper-*` ramp, and
-           it carries its own tracking, so no inline letter-spacing here.
-           Uppercase, and off `fg-48`: under half the ink read as disabled
-           rather than quiet, and this is a live label, not a footnote. */
-        <p
-          className="text-oq-64 kol-helper-12"
-          style={{ marginBottom: 12, textTransform: 'uppercase' }}
-        >
-          {eyebrow}
-        </p>
-      )}
-      {actions && subtitle ? (
-        <>
-          {h1}
-          <div className="flex items-baseline justify-between gap-6" style={{ marginTop: 12 }}>
-            {lede}
-            {cluster}
-          </div>
-        </>
-      ) : actions ? (
-        <div className="flex items-baseline justify-between gap-6">
-          {h1}
-          {cluster}
-        </div>
-      ) : (
-        <>
-          {h1}
-          {lede}
-        </>
-      )}
-    </header>
+    <SectionText
+      eyebrow={eyebrow}
+      headline={title}
+      headlineAs="h1"
+      headlineClass={`text-fg-96 ${titleClass ?? roles[size] ?? roles.md}`}
+      body={subtitle}
+      bodyClass={`text-oq-64 ${LEDE[register] ?? LEDE.app} min-w-0`}
+      actions={actions}
+      actionsPlacement="inline"
+      actionsClass="flex items-center gap-4"
+      /* HELPER, not mono (user ruling 2026-08-15). An eyebrow is single-line
+         chrome — the whole definition of the `kol-helper-*` ramp — and it
+         carries its own tracking, so no inline letter-spacing. Off `oq-64`:
+         under half the ink read as disabled rather than quiet, and this is a
+         live label, not a footnote. */
+      eyebrowClass="kol-helper-12 text-oq-64"
+      gap="gap-3"
+      slotStyle={{ body: { maxWidth: subtitleMaxWidth } }}
+      className={className}
+      style={{ marginBottom: 'var(--kol-page-header-mb, 40px)' }}
+    />
   )
 }

package/src/molecules/SectionText.jsx

@@ -71,24 +71,59 @@ export default function SectionText({
   labelClass,
   bodyClass = 'kol-section-text-body',
   actionsClass = 'flex flex-wrap gap-4',
+  /* ACTIONS ON THE BODY'S BASELINE (page-header-one-masthead, 2026-09-03).
+   * Default `below` is the section stack every organism renders. `inline` puts
+   * the cluster in ONE flex row with the body, which is the only way to land it
+   * on the body's first baseline rather than the headline's — flexbox exposes a
+   * flex item's first baseline, so they have to share a row.
+   *
+   * The cluster contributes NO HEIGHT there: a flex row takes its tallest
+   * child, so `sm` controls (26px) against a one-line `kol-mono-14` (18px) made
+   * the block 10px taller — measured across two apps, and the masthead is the
+   * one block every page shares, so a page with a control cluster sat lower
+   * than one without. `h-0 self-center` makes the children overflow a
+   * zero-height box symmetrically; the row's height is the TEXT's, at any rung.
+   * Horizontal layout is untouched, so a long body cannot run under the
+   * controls (PageHeaderTrailingSlot / PageHeaderActionsGrowsBlock, carried in
+   * from `PageHeader` when it became a composition of this base). */
+  actionsPlacement = 'below',
   slotClass = {},
   slotStyle = {},
   className = '',
+  /* the ROOT's own style — a composition that owns its rhythm needs it
+     (PageHeader's `--kol-page-header-mb`). `slotStyle` reaches the slots; this
+     was the one box it could not reach. */
+  style,
 }) {
   /* `label` / `labelClass` / slot key `label` = aliases of `eyebrow` (2026-08-27) */
   const eb = eyebrow ?? label
   const ebClass = eyebrowClass ?? labelClass ?? 'kol-helper-12 text-meta'
   const cls = (base, slot) => `${base} ${slotClass[slot] ?? (slot === 'eyebrow' ? slotClass.label : undefined) ?? ''}`.trim()
   const alignCls = align === 'center' ? 'items-center text-center' : 'items-start text-left'
+  const inlineActions = actionsPlacement === 'inline' && !!actions && !!body
+  const bodyNode = body && (typeof body === 'string'
+    ? <p className={cls(bodyClass, 'body')} style={slotStyle.body}>{body}</p>
+    : <div className={cls(bodyClass, 'body')} style={slotStyle.body}>{body}</div>)
+  const cluster = actions && (
+    <div className={cls(`${actionsClass} shrink-0 h-0 self-center`, 'actions')} style={slotStyle.actions}>{actions}</div>
+  )
   return (
-    <div className={`kol-section-text flex flex-col ${gap} ${alignCls} ${className}`.replace(/\s+/g, ' ').trim()}>
+    <div className={`kol-section-text flex flex-col ${gap} ${alignCls} ${className}`.replace(/\s+/g, ' ').trim()} style={style}>
       {/* `kol-section-text-eyebrow` = uppercase by ROLE (kol-theme ≥0.55.0);
         * `labelClass` is the voice riding beside it */}
       {eb && <span className={cls(`kol-section-text-eyebrow ${ebClass}`, 'eyebrow')} style={slotStyle.eyebrow ?? slotStyle.label}>{eb}</span>}
       {headline && <Headline className={cls(`kol-section-text-headline ${headlineClass ?? (HEADLINE_ROLE[headlineSize] ?? HEADLINE_ROLE['heading-02'])}${headlineCase === 'upper' ? ' kol-section-text-caps' : ''}`, 'headline')} style={slotStyle.headline}>{headline}</Headline>}
-      {body && (typeof body === 'string' ? <p className={cls(bodyClass, 'body')} style={slotStyle.body}>{body}</p> : <div className={cls(bodyClass, 'body')} style={slotStyle.body}>{body}</div>)}
+      {bodyNode && (inlineActions
+        ? (
+          <div className="flex items-baseline justify-between gap-6">
+            {bodyNode}
+            {cluster}
+          </div>
+        )
+        : bodyNode)}
       {children}
-      {actions && <div className={cls(actionsClass, 'actions')} style={slotStyle.actions}>{actions}</div>}
+      {/* inline with no body → the cluster shares the HEADLINE's row instead */}
+      {actions && !inlineActions && <div className={cls(actionsClass, 'actions')} style={slotStyle.actions}>{actions}</div>}
     </div>
   )
 }