@kolkrabbi/kol-component 0.88.0 → 0.90.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.88.0",
+  "version": "0.90.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

@@ -135,6 +135,7 @@ export { default as MediaLibrary, MediaLibraryProvider, useMediaLibrary, MediaPi
 export { default as MediaTileGallery } from './organisms/MediaTileGallery.jsx'
 export { default as MediaViewer } from './organisms/MediaViewer.jsx'
 export { default as SettingsPanel, SettingsRow, SettingsSwitch, SettingsChoice, SettingsChipRow, SettingsFooter } from './organisms/SettingsPanel.jsx'
+export { default as SectionNewsletter } from './organisms/SectionNewsletter.jsx'
 export { default as NewsletterBand } from './organisms/NewsletterBand.jsx'
 export { default as RecordManager } from './organisms/RecordManager.jsx'
 export { default as SpectrumGrid } from './organisms/SpectrumGrid.jsx'

package/src/organisms/ContentCollection.jsx

@@ -41,8 +41,13 @@ import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
  *
  * @param {string}  form     'grid' | 'list'
  * @param {string}  min      grid track minimum, card form (default 320px)
- * @param {number}  cols     OPT-IN column count, grid form: 1 below md, N from
- *                           md (2–6). Wins over `min`; the list form ignores it
+ * @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
+ *                           below the first rung, each rung's count from there
+ *                           (ContentCollectionColsResponsive, 2026-08-27 —
+ *                           user: "can we make it 4 in the biggest breakpoint?").
+ *                           Wins over `min`; the list form ignores it
  * @param {string}  listMin  OPT-IN: makes the list multi-column too, for a dense
  *                           file-browser cut. Unset = one full-width column
  * @param {number}  gap      px between items. UNSET reads the token for the
@@ -53,13 +58,19 @@ import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
  *                           nine call sites. Pass a number only to differ
  * @param {boolean} stagger  enter animation on/off (reduced motion wins)
  */
-const COLS = {
-  1: 'grid-cols-1',
-  2: 'grid-cols-1 md:grid-cols-2',
-  3: 'grid-cols-1 md:grid-cols-3',
-  4: 'grid-cols-1 md:grid-cols-4',
-  5: 'grid-cols-1 md:grid-cols-5',
-  6: 'grid-cols-1 md:grid-cols-6',
+/* literal per rung × count — a class built at runtime is never emitted */
+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' },
+}
+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(' ') : ''
 }
 
 export default function ContentCollection({
@@ -81,7 +92,7 @@ export default function ContentCollection({
     ? `${gap}px`
     : `var(--kol-gap-wall-${form === 'list' ? 'list' : 'grid'})`
 
-  const colsCls = form !== 'list' && COLS[cols] ? COLS[cols] : ''
+  const colsCls = form !== 'list' ? colsClasses(cols) : ''
   return (
     <ul
       key={form}

package/src/organisms/NewsletterBand.jsx

@@ -1,122 +1,12 @@
-import { useId, useState } from 'react'
-import Input from '../atoms/Input.jsx'
-import Button from '../atoms/Button.jsx'
+import SectionNewsletter from './SectionNewsletter.jsx'
 
 /**
- * NewsletterBand — centered newsletter-subscribe band: heading + lede over an
- * email Input + submit Button, with an inline success/error status line under
- * the form. The closing subscribe section on marketing pages.
- *
- * Owns only the local form state — the email value and idle / submitting /
- * success / error, driven by the promise returned from `onSubmit(email)`.
- * No fetch lives here: the consumer's handler posts wherever it wants;
- * resolve → success (field clears), reject → error (logged). An empty submit
- * errors immediately without calling the handler, and the submit Button
- * disables while the promise is pending. Native `type="email"` validation
- * still gates malformed addresses before the handler runs.
- *
- * A11y: the Input carries aria-required and, on error, aria-describedby
- * pointing at the error line; the success line is role=status
- * aria-live=polite, the error line role=alert aria-live=assertive. Field and
- * error ids are useId-generated (or `inputId`) so multiple bands mount
- * without collisions.
- *
- * @param {ReactNode} title        heading (kol-sans-display-01)
- * @param {ReactNode} description  lede under the heading (kol-mono-14)
- * @param {string}    placeholder  email Input placeholder
- * @param {ReactNode} submitLabel  submit Button label (also its accessible name)
- * @param {Function}  onSubmit     (email) => Promise|void — resolve = success, reject = error
- * @param {ReactNode} successCopy  success status line
- * @param {ReactNode} errorCopy    error status line
- * @param {string}    id           anchor id on the section (e.g. "signup")
- * @param {string}    inputId      id override for the email input (default useId-generated)
- * @param {string}    className    extra classes on the section
+ * @deprecated 2026-08-27 — `NewsletterBand` is `SectionNewsletter` under its
+ * old name: the newsletter joined the section family (SectionNewsletter,
+ * kol-website). `title` → `headline`, `description` → `body`; everything else
+ * passes through. On the retirement ledger (04-retirements.md) — dropped when
+ * no repo imports it.
  */
-export default function NewsletterBand({
-  title,
-  description,
-  placeholder,
-  submitLabel,
-  onSubmit,
-  successCopy = 'Thanks for subscribing!',
-  errorCopy = 'Please enter a valid email address.',
-  id,
-  inputId,
-  className = '',
-}) {
-  const [email, setEmail] = useState('')
-  const [status, setStatus] = useState('idle') // 'idle' | 'submitting' | 'success' | 'error'
-
-  const autoId = useId()
-  const emailId = inputId ?? `${autoId}email`
-  const errorId = `${emailId}-error`
-
-  const handleSubmit = async (e) => {
-    e.preventDefault()
-
-    if (!email) {
-      setStatus('error')
-      return
-    }
-    if (!onSubmit) return
-
-    setStatus('submitting')
-    try {
-      await onSubmit(email)
-      setStatus('success')
-      setEmail('')
-    } catch (error) {
-      console.error('Newsletter signup error:', error)
-      setStatus('error')
-    }
-  }
-
-  return (
-    <section
-      id={id}
-      className={`w-full flex flex-col items-center justify-center text-center ${className}`.trim()}
-    >
-      <div className="max-w-[1400px] mx-auto py-24">
-        <h2 className="kol-sans-display-01 mb-6">{title}</h2>
-
-        <p className="kol-mono-14 text-auto mb-12 mx-auto max-w-[64rem]">{description}</p>
-
-        <form
-          onSubmit={handleSubmit}
-          className="flex flex-col gap-4 mb-16 sm:flex-row sm:items-center sm:justify-center sm:gap-3"
-        >
-          <Input
-            id={emailId}
-            type="email"
-            placeholder={placeholder}
-            value={email}
-            onChange={(e) => setEmail(e.target.value)}
-            size="md"
-            aria-required="true"
-            aria-describedby={status === 'error' ? errorId : undefined}
-            className="w-full sm:max-w-[400px] md:max-w-[520px]"
-          />
-          <Button
-            type="submit"
-            variant="primary"
-            disabled={status === 'submitting'}
-            className="w-full sm:w-auto"
-          >
-            {submitLabel}
-          </Button>
-        </form>
-
-        {status === 'success' && (
-          <p className="kol-mono-14 text-auto opacity-80" role="status" aria-live="polite">
-            {successCopy}
-          </p>
-        )}
-        {status === 'error' && (
-          <p id={errorId} className="kol-mono-14 text-auto opacity-80" role="alert" aria-live="assertive">
-            {errorCopy}
-          </p>
-        )}
-      </div>
-    </section>
-  )
+export default function NewsletterBand({ title, description, ...rest }) {
+  return <SectionNewsletter headline={title} body={description} {...rest} />
 }

package/src/organisms/SectionNewsletter.jsx

@@ -0,0 +1,153 @@
+import { useId, useState } from 'react'
+import Input from '../atoms/Input.jsx'
+import Button from '../atoms/Button.jsx'
+import SectionText from '../molecules/SectionText.jsx'
+import useSectionTheme from '../hooks/useSectionTheme.js'
+import { minHeightClass } from './sectionHeights.js'
+
+/**
+ * SectionNewsletter — the newsletter card of the section family
+ * (SectionNewsletter, kol-website 2026-08-27 — user: the newsletter as a card
+ * in the family, same ladder, same cap, content centred on y, not its own
+ * thing). `SectionText` (label · headline · body, centred) with the email
+ * form in its children slot: an email Input + submit Button and an inline
+ * success / error status line. `NewsletterBand` is the deprecated alias
+ * (`title` → `headline`, `description` → `body`).
+ *
+ * Owns only the local form state — the email value and idle / submitting /
+ * success / error, driven by the promise returned from `onSubmit(email)`.
+ * No fetch lives here: the consumer's handler posts wherever it wants;
+ * resolve → success (field clears), reject → error (logged). An empty submit
+ * errors immediately without calling the handler, and the submit Button
+ * disables while the promise is pending. Native `type="email"` validation
+ * still gates malformed addresses before the handler runs.
+ *
+ * A11y: the Input carries aria-required and, on error, aria-describedby
+ * pointing at the error line; the success line is role=status
+ * aria-live=polite, the error line role=alert aria-live=assertive. Field and
+ * error ids are useId-generated (or `inputId`) so multiple sections mount
+ * without collisions.
+ *
+ * @param {'full'|'80'|'60'|'40'|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 {'inverse'|'light'|'dark'} theme  the paired theme of whatever is live, or a pinned one — stamped on the section
+ * @param {ReactNode} label        eyebrow above the headline (uppercase by role)
+ * @param {ReactNode} headline     heading (display-01 by default; `headlineSize` picks another role)
+ * @param {string}    headlineSize SectionText role (default 'display-01')
+ * @param {ReactNode} body         lede under the heading
+ * @param {string}    placeholder  email Input placeholder
+ * @param {ReactNode} submitLabel  submit Button label (also its accessible name)
+ * @param {Function}  onSubmit     (email) => Promise|void — resolve = success, reject = error
+ * @param {ReactNode} successCopy  success status line
+ * @param {ReactNode} errorCopy    error status line
+ * @param {string}    id           anchor id on the section (e.g. "signup")
+ * @param {string}    inputId      id override for the email input (default useId-generated)
+ * @param {object}    slotClass · slotStyle   per-slot class / style on the SectionText (reveal seam)
+ * @param {string}    className    extra classes on the section
+ */
+export default function SectionNewsletter({
+  height = '60',
+  theme,
+  label,
+  headline,
+  headlineSize = 'display-01',
+  body,
+  placeholder,
+  submitLabel,
+  onSubmit,
+  successCopy = 'Thanks for subscribing!',
+  errorCopy = 'Please enter a valid email address.',
+  id,
+  inputId,
+  slotClass,
+  slotStyle,
+  className = '',
+}) {
+  const [email, setEmail] = useState('')
+  const [status, setStatus] = useState('idle') // 'idle' | 'submitting' | 'success' | 'error'
+  const [themeRef, themeStamp] = useSectionTheme(theme)
+
+  const autoId = useId()
+  const emailId = inputId ?? `${autoId}email`
+  const errorId = `${emailId}-error`
+
+  const handleSubmit = async (e) => {
+    e.preventDefault()
+
+    if (!email) {
+      setStatus('error')
+      return
+    }
+    if (!onSubmit) return
+
+    setStatus('submitting')
+    try {
+      await onSubmit(email)
+      setStatus('success')
+      setEmail('')
+    } catch (error) {
+      console.error('Newsletter signup error:', error)
+      setStatus('error')
+    }
+  }
+
+  return (
+    <section
+      id={id}
+      ref={themeRef}
+      data-theme={themeStamp}
+      className={`kol-section-newsletter w-full flex flex-col justify-center py-24 ${theme ? 'bg-surface-primary text-auto' : ''} ${minHeightClass(height)} ${className}`.replace(/\s+/g, ' ').trim()}
+    >
+      {/* the family's ONE cap — the shell's --kol-container-max ladder */}
+      <div className="w-full max-w-[var(--kol-container-max,var(--kol-content-shell,1800px))] mx-auto text-center">
+        <SectionText
+          align="center"
+          label={label}
+          headline={headline}
+          headlineSize={headlineSize}
+          body={body}
+          bodyClass="kol-mono-14 text-auto mx-auto max-w-[64rem]"
+          gap="gap-6"
+          slotClass={slotClass}
+          slotStyle={slotStyle}
+        >
+          <form
+            onSubmit={handleSubmit}
+            className="flex flex-col gap-4 pt-6 sm:flex-row sm:items-center sm:justify-center sm:gap-3"
+          >
+            <Input
+              id={emailId}
+              type="email"
+              placeholder={placeholder}
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              size="md"
+              aria-required="true"
+              aria-describedby={status === 'error' ? errorId : undefined}
+              className="w-full sm:max-w-[400px] md:max-w-[520px]"
+            />
+            <Button
+              type="submit"
+              variant="primary"
+              disabled={status === 'submitting'}
+              className="w-full sm:w-auto"
+            >
+              {submitLabel}
+            </Button>
+          </form>
+
+          {status === 'success' && (
+            <p className="kol-mono-14 text-auto opacity-80 pt-4" role="status" aria-live="polite">
+              {successCopy}
+            </p>
+          )}
+          {status === 'error' && (
+            <p id={errorId} className="kol-mono-14 text-auto opacity-80 pt-4" role="alert" aria-live="assertive">
+              {errorCopy}
+            </p>
+          )}
+        </SectionText>
+      </div>
+    </section>
+  )
+}