@kolkrabbi/kol-component 0.146.0 → 0.148.0

package/package.json

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

@@ -32,6 +32,10 @@ import { Icon } from '@kolkrabbi/kol-icons'
  * @param {string}    href             link target; `http*`/`mailto` → new tab, else plain same-tab anchor
  * @param {Function}  onNavigate       (event) => void — click seam on the same-tab anchor (SPA intercept)
  * @param {'auto'|'9/6'|'10/6'|'16/9'|'1/1'} imageAspectRatio  aspect class on the visual middle
+ * @param {number}    zoom  hover zoom scale for THIS card's visual (default 1.03, the shipped value).
+ *   Per-feature because the right amount belongs to the artwork, not the component: 3% is correct on
+ *   a dense photographic visual and invisible on sparse line-art, and one set can hold both
+ *   (CardFeatureZoomScale, kol-website 2026-08-31).
  * @param {string}    imagePosition    `<img>` object-position
  */
 export default function SectionCardItem({
@@ -43,6 +47,7 @@ export default function SectionCardItem({
   href,
   onNavigate,
   imageAspectRatio = 'auto',
+  zoom,
   imagePosition = 'center',
   className = '',
   style,
@@ -89,9 +94,10 @@ export default function SectionCardItem({
         {icon && <Icon name={icon} size={16} className="shrink-0" />}
       </div>
 
-      {/* kol-card-feature-visual: zooms 1.03 on card hover (chrome in
-        * kol-theme — CardFeatureHoverZoom 2026-08-12); all three visual
-        * forms ride the same wrapper, reduced-motion opts out. */}
+      {/* kol-card-feature-visual: zooms on card hover (chrome in kol-theme —
+        * CardFeatureHoverZoom 2026-08-12); all three visual forms ride the same
+        * wrapper, reduced-motion opts out. The AMOUNT is `zoom`, published as
+        * `--kol-card-feature-zoom` and defaulting to the shipped 1.03. */}
       <div className={`kol-card-feature-visual w-full flex-auto flex items-center justify-center overflow-hidden ${aspectClass}`.trim()}>
         {visual ? (
           typeof visual === 'string' ? (
@@ -130,6 +136,10 @@ export default function SectionCardItem({
     </>
   )
 
+  /* the card publishes the amount; the theme rule reads it with 1.03 as the
+   * fallback, so a card that sets nothing renders exactly as it always did */
+  const rootStyle = zoom != null ? { ...style, '--kol-card-feature-zoom': zoom } : style
+
   const baseClasses = textOnly
     ? `kol-card-feature kol-card-feature--text w-full flex-1 min-h-[180px] p-4 md:p-5 lg:p-6 gap-2 ${bg} rounded border border-fg-08 flex flex-col justify-between items-start overflow-hidden ${className}`
     : `kol-card-feature w-full flex-1 h-[304px] md:h-72 p-4 md:p-6 gap-4 ${bg} rounded border border-fg-08 flex flex-col justify-between items-start overflow-hidden ${className}`.trim()
@@ -142,7 +152,7 @@ export default function SectionCardItem({
         <a
           href={href}
           className={`${baseClasses} hover:border-fg-32 transition-colors duration-300`}
-          style={style}
+          style={rootStyle}
           target="_blank"
           rel="noreferrer noopener"
         >
@@ -156,12 +166,12 @@ export default function SectionCardItem({
         href={href}
         onClick={onNavigate}
         className={`${baseClasses} hover:border-fg-24 transition-colors duration-300`}
-        style={style}
+        style={rootStyle}
       >
         {content}
       </a>
     )
   }
 
-  return <div className={baseClasses} style={style}>{content}</div>
+  return <div className={baseClasses} style={rootStyle}>{content}</div>
 }

package/src/organisms/ContentCollection.jsx

@@ -40,7 +40,21 @@ import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
  * a class built at runtime is never emitted.
  *
  * @param {string}  form     'grid' | 'list'
- * @param {string}  min      grid track minimum, card form (default 320px)
+ * @param {string}  min      grid track minimum, card form (default 320px) — the FLUID wall's floor
+ * @param {string}  minCol   the floor a `cols` track may not go under. DEFAULTS TO `min` (320px), so
+ *                           the count path and the fluid path share one ruled minimum and raising
+ *                           `min` raises both (ContentCollectionMinColumnWidth, kol-chess
+ *                           2026-08-31). `cols` is a CEILING now, not a command: the wall takes up
+ *                           to N columns and drops one rather than let a track go under this.
+ *
+ *                           WHY NOT A HIGHER DEFAULT. The filer measured a roster row clipping on
+ *                           7 of 10 rows at 324 and 3 of 10 at 373, which argues for ~360 — but that
+ *                           is a number about a ROW two truncated lines tall, and this floor governs
+ *                           every kind. 320 is the width this DS has already ruled as the narrowest
+ *                           acceptable track and lived with; applying it to the `cols` path is
+ *                           carrying an existing ruling across, where 360 would be a new estate-wide
+ *                           law made from one page's evidence. A wall whose content needs more says
+ *                           so: `minCol="360px"`.
  * @param {number|object} cols  OPT-IN column count, grid form. A number: 1 below
  *                           md, N from md (1–6). A map per breakpoint
  *                           (`{ md: 3, xl: 4 }` — sm · md · lg · xl · 2xl): 1
@@ -59,23 +73,34 @@ import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
  * @param {boolean} stagger  enter animation on/off (reduced motion wins)
  */
 /* literal per rung × count — a class built at runtime is never emitted */
+/* THE COUNT IS A CEILING NOW, NOT A COMMAND (ContentCollectionMinColumnWidth,
+ * kol-chess 2026-08-31). `cols` used to emit `grid-cols-N` and take N columns
+ * whatever they measured, which is how a WIDER screen came to clip MORE text:
+ * kol-chess's roster ran 1 column at 350 on a phone and 2 columns at 324 at
+ * 768 — narrower tracks on a bigger viewport, 7 rows of 10 clipping at both.
+ *
+ * So the rungs publish a VARIABLE instead of a track list, and one static
+ * template below turns it into "at most N, and never narrower than the floor".
+ * Literal class strings, as before — a class built at runtime is never emitted
+ * by Tailwind's scanner, and arbitrary-property utilities are no exception. */
 const COLS_AT = {
-  sm:  { 1: 'sm:grid-cols-1',  2: 'sm:grid-cols-2',  3: 'sm:grid-cols-3',  4: 'sm:grid-cols-4',  5: 'sm:grid-cols-5',  6: 'sm:grid-cols-6' },
-  md:  { 1: 'md:grid-cols-1',  2: 'md:grid-cols-2',  3: 'md:grid-cols-3',  4: 'md:grid-cols-4',  5: 'md:grid-cols-5',  6: 'md:grid-cols-6' },
-  lg:  { 1: 'lg:grid-cols-1',  2: 'lg:grid-cols-2',  3: 'lg:grid-cols-3',  4: 'lg:grid-cols-4',  5: 'lg:grid-cols-5',  6: 'lg:grid-cols-6' },
-  xl:  { 1: 'xl:grid-cols-1',  2: 'xl:grid-cols-2',  3: 'xl:grid-cols-3',  4: 'xl:grid-cols-4',  5: 'xl:grid-cols-5',  6: 'xl:grid-cols-6' },
-  '2xl': { 1: '2xl:grid-cols-1', 2: '2xl:grid-cols-2', 3: '2xl:grid-cols-3', 4: '2xl:grid-cols-4', 5: '2xl:grid-cols-5', 6: '2xl:grid-cols-6' },
+  sm:  { 1: 'sm:[--kol-wall-cols:1]',  2: 'sm:[--kol-wall-cols:2]',  3: 'sm:[--kol-wall-cols:3]',  4: 'sm:[--kol-wall-cols:4]',  5: 'sm:[--kol-wall-cols:5]',  6: 'sm:[--kol-wall-cols:6]' },
+  md:  { 1: 'md:[--kol-wall-cols:1]',  2: 'md:[--kol-wall-cols:2]',  3: 'md:[--kol-wall-cols:3]',  4: 'md:[--kol-wall-cols:4]',  5: 'md:[--kol-wall-cols:5]',  6: 'md:[--kol-wall-cols:6]' },
+  lg:  { 1: 'lg:[--kol-wall-cols:1]',  2: 'lg:[--kol-wall-cols:2]',  3: 'lg:[--kol-wall-cols:3]',  4: 'lg:[--kol-wall-cols:4]',  5: 'lg:[--kol-wall-cols:5]',  6: 'lg:[--kol-wall-cols:6]' },
+  xl:  { 1: 'xl:[--kol-wall-cols:1]',  2: 'xl:[--kol-wall-cols:2]',  3: 'xl:[--kol-wall-cols:3]',  4: 'xl:[--kol-wall-cols:4]',  5: 'xl:[--kol-wall-cols:5]',  6: 'xl:[--kol-wall-cols:6]' },
+  '2xl': { 1: '2xl:[--kol-wall-cols:1]', 2: '2xl:[--kol-wall-cols:2]', 3: '2xl:[--kol-wall-cols:3]', 4: '2xl:[--kol-wall-cols:4]', 5: '2xl:[--kol-wall-cols:5]', 6: '2xl:[--kol-wall-cols:6]' },
 }
 const colsClasses = (cols) => {
   const map = typeof cols === 'number' ? { md: cols } : cols
   if (!map || typeof map !== 'object') return ''
   const rungs = Object.keys(COLS_AT).map((bp) => COLS_AT[bp][map[bp]]).filter(Boolean)
-  return rungs.length ? ['grid-cols-1', ...rungs].join(' ') : ''
+  return rungs.length ? ['[--kol-wall-cols:1]', ...rungs].join(' ') : ''
 }
 
 export default function ContentCollection({
   form = 'grid',
   min = '320px',
+  minCol,
   cols,
   listMin,
   gap,
@@ -103,9 +128,18 @@ export default function ContentCollection({
          * wall is one, so a row inside it steps on the wall's own width */
         containerType: 'inline-size',
         display: 'grid',
-        /* with `cols` the classes carry the tracks — an inline template would outrank them */
+        /* the classes no longer carry tracks — they set `--kol-wall-cols` and this
+         * ONE static template reads it, so the count and the floor cannot disagree */
         gridTemplateColumns: colsCls
-          ? undefined
+          /* AT MOST N, AND NEVER NARROWER THAN THE FLOOR. `auto-fill` counts the
+           * tracks; the track size is the LARGER of the floor and an even 1/N
+           * share, so the wall takes N columns while they fit and drops one the
+           * moment a share would go under the floor. `min(100%, …)` is the guard
+           * that keeps a single narrow container from overflowing — without it a
+           * 350px phone gets one 360px track and a horizontal scrollbar.
+           * All of it is CSS: no measurement, no observer, and it works inside
+           * the container query this wall already establishes. */
+          ? `repeat(auto-fill, minmax(min(100%, max(${minCol ?? min}, calc((100% - (var(--kol-wall-cols, 1) - 1) * ${g}) / var(--kol-wall-cols, 1)))), 1fr))`
           : form === 'list'
             /* minmax(0, 1fr), never a bare 1fr (= minmax(auto, 1fr)): a truncated
            * nowrap line handed its min-content width to the track and a /work row

package/src/organisms/SectionCards.jsx

@@ -22,7 +22,10 @@ import { minHeightClass } from './sectionHeights.js'
  *   paints its surface — every token inside resolves to the other theme's.
  * @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; content stays vertically centred inside it
- * @param {{title, icon, visual, description, href, backgroundColor, imageAspectRatio}[]} features
+ * @param {{title, icon, visual, description, href, backgroundColor, imageAspectRatio, zoom}[]} features
+ *   `zoom` is the per-card hover scale (default 1.03) — the right amount belongs to the ARTWORK,
+ *   not the component: 3% reads correctly on a dense photographic visual and is invisible on sparse
+ *   line-art, and one set can hold both (CardFeatureZoomScale, kol-website 2026-08-31).
  * @param {ReactNode} eyebrow (alias label) · headline · body   the header (heading-03 + mono lede by default)
  * @param {ReactNode} actions               centred action row under the cards
  * @param {Function}  onNavigate            (event, feature) => void
@@ -97,6 +100,7 @@ export default function SectionCards({
                 href={feature.href}
                 backgroundColor={feature.backgroundColor}
                 imageAspectRatio={feature.imageAspectRatio}
+                zoom={feature.zoom}
                 onNavigate={onNavigate ? (event) => onNavigate(event, feature) : undefined}
                 className={itemClassName}
                 style={typeof itemStyle === 'function' ? itemStyle(index) : itemStyle}

package/src/organisms/SectionNewsletter.jsx

@@ -51,6 +51,13 @@ import { minHeightClass } from './sectionHeights.js'
  *   Button (SectionNewsletterControlSize, kol-website 2026-08-31). The pair was hardcoded md with no
  *   seam, so a page that sets `size="lg"` on every other call-site button could not match it here and
  *   the newsletter read visibly smaller directly beneath them. Default is today's md — nothing moves.
+ * @param {boolean}   [fullBleed=false]  the FILL breaks the page gutter while the content keeps it
+ *   (SectionNewsletterFullBleed, kol-website 2026-08-31). This card is a filled surface inside
+ *   `.kol-page`, so the gutter clipped its background and left strips of page down both sides of the
+ *   colour. Fill and content padding are the same box, so a consumer could not bleed one without
+ *   dragging the other out with it. The breakout literal is SectionHero's, character for character —
+ *   two organisms in one family must not invent two ways to leave a gutter. The section's own
+ *   `px-5 sm:px-8` then re-insets the content, so only the fill moves.
  * @param {string}    className    extra classes on the section
  * @param {'primary'|'secondary'|'tertiary'|'inverse'|'auto'|'none'|string} background  the section's surface
  *   (SectionBackgroundProp, 2026-08-27) — a named surface, `none`, or a raw utility / token string; default = what it painted before
@@ -58,6 +65,7 @@ import { minHeightClass } from './sectionHeights.js'
 export default function SectionNewsletter({
   height = '40',
   controlSize = 'md',
+  fullBleed = false,
   theme,
   background,
   eyebrow,
@@ -118,7 +126,7 @@ export default function SectionNewsletter({
         * boundary and read as breaking out of it. `px-5` is a floor the band owns.
         * Desktop does not move — the measure caps below the padded width, so the
         * inner block still centres at 80px from the band edge. */
-        className={`kol-section-newsletter w-full flex flex-col justify-center px-5 sm:px-8 py-24 ${surfaceClass(background, theme ? 'primary' : 'none')} ${theme ? 'text-auto' : ''} ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}
+        className={`kol-section-newsletter ${fullBleed ? 'w-screen ml-[calc(50%-50vw)]' : 'w-full'} flex flex-col justify-center px-5 sm:px-8 py-24 ${surfaceClass(background, theme ? 'primary' : 'none')} ${theme ? 'text-auto' : ''} ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}
     >
       {/* the family's ONE cap — the shell's --kol-container-max ladder — and
         * inside it the lede's MEASURE on a wrapper (SectionNewsletterForm,

package/src/utilities/ButtonGroup.jsx

@@ -10,7 +10,9 @@
  *
  * @param {'left'|'center'|'right'} align horizontal alignment + container layout mode (default 'center')
  * @param {string}    title     optional heading rendered above the group, authored at the call site
- * @param {string}    className extra container classes (appended)
+ * @param {string}    className extra container classes (appended) — note this lands on the OUTER
+ *   container, not the flex row that carries the gap; the gap is responsive by default (8 stacked,
+ *   16 as a row) rather than reachable, so there is nothing to reach for.
  * @param {ReactNode} children  the Buttons
  */
 
@@ -32,7 +34,16 @@ export default function ButtonGroup({ align = 'center', title, className = '', c
       {title && <h3 className="kol-sans-heading-05 text-emphasis mb-6">{title}</h3>}
       <div
         className={[
-          'flex flex-col gap-4 sm:flex-row sm:items-center',
+          /* THE GAP IS TWO JOBS, NOT ONE (ButtonGroupResponsiveGap, kol-website
+           * 2026-08-31). The group changes axis at `sm`, so a single `gap-4` was
+           * doing horizontal separation between two side-by-side buttons AND
+           * vertical separation between two full-width stacked ones. Those do not
+           * want the same number: 16 reads too open stacked (user: "16 is way too
+           * big, at least lets see 8 or 12"), and 8 is what looks right on device.
+           * A responsive default rather than a prop — the stacked case IS the
+           * narrow viewport, so the value is pickable once instead of per
+           * consumer. The row keeps today's 16 and nothing moves at `sm` and up. */
+          'flex flex-col gap-2 sm:flex-row sm:gap-4 sm:items-center',
           JUSTIFY[align] || JUSTIFY.center,
         ].join(' ')}
       >