@invisibleloop/pulse 0.12.2 → 0.14.1

package/src/ui/image-pair.js

@@ -0,0 +1,72 @@
+/**
+ * Pulse UI — Image Pair
+ *
+ * Two images side by side — no text. A pure editorial layout used in fashion,
+ * portfolio, and magazine contexts to present photography at full scale.
+ * Both images share the same aspect ratio and fill equal columns.
+ *
+ * For image + text layouts, use the media() component instead.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.leftSrc       - Left image URL
+ * @param {string}  opts.leftAlt       - Left image alt text
+ * @param {string}  opts.rightSrc      - Right image URL
+ * @param {string}  opts.rightAlt      - Right image alt text
+ * @param {string}  opts.ratio         - CSS aspect-ratio for both images (default: '3/4')
+ * @param {'none'|'sm'|'md'} opts.gap  - Gap between images (default: 'none')
+ * @param {string}  opts.label         - Optional aria-label for the section
+ * @param {string}  opts.leftLabel     - Link label below left image (e.g. 'Craftmanship')
+ * @param {string}  opts.leftHref      - href for left link
+ * @param {string}  opts.rightLabel    - Link label below right image (e.g. 'Store')
+ * @param {string}  opts.rightHref     - href for right link
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const GAPS = new Set(['none', 'sm', 'md'])
+
+export function imagePair({
+  leftSrc    = '',
+  leftAlt    = '',
+  rightSrc   = '',
+  rightAlt   = '',
+  ratio      = '3/4',
+  gap        = 'none',
+  label      = '',
+  leftLabel  = '',
+  leftHref   = '#',
+  rightLabel = '',
+  rightHref  = '#',
+  class: cls = '',
+} = {}) {
+  if (!GAPS.has(gap)) gap = 'none'
+
+  const classes = [
+    'ui-image-pair',
+    gap !== 'none' && `ui-image-pair--gap-${gap}`,
+    (leftLabel || rightLabel) && 'ui-image-pair--captioned',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const labelAttr = label ? ` aria-label="${e(label)}"` : ''
+  const cropStyle = ratio ? ` style="aspect-ratio:${e(ratio)}"` : ''
+
+  const leftCaption  = leftLabel  ? `<a href="${e(leftHref)}"  class="ui-image-pair-link">${e(leftLabel)} →</a>`  : ''
+  const rightCaption = rightLabel ? `<a href="${e(rightHref)}" class="ui-image-pair-link">${e(rightLabel)} →</a>` : ''
+
+  return `<div class="${e(classes)}"${labelAttr}>
+  <div class="ui-image-pair-col">
+    <div class="ui-image-pair-crop"${cropStyle}>
+      <img src="${e(leftSrc)}" alt="${e(leftAlt)}" loading="lazy" decoding="async">
+    </div>
+    ${leftCaption}
+  </div>
+  <div class="ui-image-pair-col">
+    <div class="ui-image-pair-crop"${cropStyle}>
+      <img src="${e(rightSrc)}" alt="${e(rightAlt)}" loading="lazy" decoding="async">
+    </div>
+    ${rightCaption}
+  </div>
+</div>`
+}

package/src/ui/index.js

@@ -67,9 +67,29 @@ export { fileUpload }  from './fileupload.js'
 export { breadcrumbs } from './breadcrumbs.js'
 export { stepper }     from './stepper.js'
 export { uiImage }     from './uiimage.js'
+export { gallery }       from './gallery.js'
+export { photoCard }     from './photo-card.js'
+export { productCard }   from './product-card.js'
+export { editorialHero } from './editorial-hero.js'
+export { imagePair }     from './image-pair.js'
+export { brandStatement } from './brand-statement.js'
+export { marquee }     from './marquee.js'
+export { serviceCard } from './service-card.js'
+export { contactRow }  from './contact-row.js'
+export { trustList }   from './trust-list.js'
+export { topStrip }    from './top-strip.js'
+export { statGrid }    from './stat-grid.js'
+export { decorate }    from './decorate.js'
 export { pullquote }   from './pullquote.js'
 export { prose }       from './prose.js'
 export { heading }     from './heading.js'
+
+// Editorial components
+export { entryList }      from './entry-list.js'
+export { displayHeading } from './display-heading.js'
+export { sectionLabel }   from './section-label.js'
+export { dropCap }        from './drop-cap.js'
+export { colophon }       from './colophon.js'
 export { list }        from './list.js'
 export {
   iconArrowLeft, iconArrowRight, iconArrowUp, iconArrowDown,

package/src/ui/input.js

@@ -43,6 +43,7 @@ export function input({
   const wrapClasses = ['ui-field', error ? 'ui-field--error' : '', cls].filter(Boolean).join(' ')
 
   const attrsStr = Object.entries(attrs)
+    .filter(([, v]) => v !== undefined)
     .map(([k, v]) => ` ${e(k)}="${e(String(v))}"`)
     .join('')
 

package/src/ui/marquee.js

@@ -0,0 +1,48 @@
+/**
+ * Pulse UI — Marquee
+ *
+ * CSS-only infinite scrolling strip. Ideal for logo clouds, trust badges,
+ * press mentions, or tag lists. No JavaScript — pure CSS animation.
+ *
+ * @param {object}  opts
+ * @param {string[]} opts.items    - Array of raw HTML strings (logos, badges, text)
+ * @param {number}  opts.speed     - Duration in seconds for one full loop (default: 30)
+ * @param {'sm'|'md'|'lg'} opts.gap - Gap between items (default: 'lg')
+ * @param {'left'|'right'} opts.direction - Scroll direction (default: 'left')
+ * @param {boolean} opts.pause     - Pause animation on hover (default: true)
+ * @param {boolean} opts.fade      - Fade edges with gradient mask (default: true)
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+const GAPS = new Set(['sm', 'md', 'lg'])
+
+export function marquee({
+  items     = [],
+  speed     = 30,
+  gap       = 'lg',
+  direction = 'left',
+  pause     = true,
+  fade      = true,
+  class: cls = '',
+} = {}) {
+  if (!GAPS.has(gap)) gap = 'lg'
+  const safeSpeed = Math.max(5, parseFloat(speed) || 30)
+  const dir       = direction === 'right' ? 'reverse' : 'normal'
+
+  const classes = [
+    'ui-marquee',
+    gap !== 'lg' && `ui-marquee--gap-${gap}`,
+    pause       && 'ui-marquee--pause',
+    fade        && 'ui-marquee--fade',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  // Items are duplicated so the loop is seamless
+  const itemsHtml = items.map(item => `<li class="ui-marquee-item">${item}</li>`).join('')
+
+  return `<div class="${e(classes)}" style="--marquee-speed:${safeSpeed}s;--marquee-dir:${dir}" aria-hidden="true">
+  <ul class="ui-marquee-track">${itemsHtml}${itemsHtml}</ul>
+</div>`
+}

package/src/ui/nav.js

@@ -20,7 +20,8 @@
  * @param {object}  opts
  * @param {string}  opts.logo       - Raw HTML slot — SVG, img, or text
  * @param {string}  opts.logoHref   - Logo link destination (default: '/')
- * @param {Array<{label:string, href?:string, mega?:Array}>} opts.links
+ * @param {Array<{label:string, href?:string, current?:boolean, mega?:Array}>} opts.links
+ * @param {Array<{label:string, href?:string}>} opts.utilityLinks - Secondary links pushed to the far right
  * @param {string}  opts.action     - Raw HTML slot — typically a button()
  * @param {boolean} opts.sticky     - Position sticky with backdrop blur
  * @param {'right'|'left'} opts.burgerAlign - Mobile burger position (default: 'right')
@@ -63,7 +64,8 @@ function renderLink(link, navId, idx) {
     ${megaPanel(link.mega, panelId)}
   </div>`
   }
-  return `<a href="${e(link.href || '')}" class="ui-nav-link">${e(link.label || '')}</a>`
+  const current = link.current ? ' aria-current="page"' : ''
+  return `<a href="${e(link.href || '')}" class="ui-nav-link"${current}>${e(link.label || '')}</a>`
 }
 
 function renderMobileLink(link) {
@@ -71,13 +73,15 @@ function renderMobileLink(link) {
     const items = link.mega.flatMap(col => col.items || [])
     return `<p class="ui-nav-mobile-section">${e(link.label || '')}</p>` + items.map(item => megaItem(item)).join('')
   }
-  return `<a href="${e(link.href || '')}" class="ui-nav-link">${e(link.label || '')}</a>`
+  const current = link.current ? ' aria-current="page"' : ''
+  return `<a href="${e(link.href || '')}" class="ui-nav-link"${current}>${e(link.label || '')}</a>`
 }
 
 export function nav({
   logo          = '',
   logoHref      = '/',
   links         = [],
+  utilityLinks  = [],
   action        = '',
   sticky        = false,
   burgerAlign   = 'right',
@@ -89,29 +93,35 @@ export function nav({
   const classes = ['ui-nav', sticky && 'ui-nav--sticky', burgerAlign === 'left' && 'ui-nav--burger-left', cls].filter(Boolean).join(' ')
   const styles  = [
     background && `background:${background.replace(/"/g, "'")}`,
-    color      && `color:${color.replace(/"/g, "'")};--ui-muted:${color.replace(/"/g, "'")}`,
+    color      && `color:${color.replace(/"/g, "'")};--ui-text:${color.replace(/"/g, "'")};--ui-muted:${color.replace(/"/g, "'")}`,
   ].filter(Boolean).join(';')
   const bgStyle = styles ? ` style="${styles}"` : ''
 
   const linksHtml       = links.map((l, i) => renderLink(l, id, i)).join('')
-  const mobileLinksHtml = links.map(renderMobileLink).join('')
+  const utilityHtml     = utilityLinks.map(l => `<a href="${e(l.href || '')}" class="ui-nav-link"${l.current ? ' aria-current="page"' : ''}>${e(l.label || '')}</a>`).join('')
+  const mobileLinksHtml = [...links, ...utilityLinks].map(renderMobileLink).join('')
 
-  const burgerHtml = links.length ? `
+  const burgerHtml = (links.length || utilityLinks.length) ? `
   <button class="ui-nav-burger" type="button" aria-label="Toggle menu" aria-expanded="false" aria-controls="${id}-mobile">
     ${iconMenu({ size: 20, class: 'ui-nav-burger-open' })}
     ${iconX({ size: 20, class: 'ui-nav-burger-close' })}
   </button>` : ''
 
-  const mobileMenuHtml = links.length ? `
+  const mobileMenuHtml = (links.length || utilityLinks.length) ? `
   <div class="ui-nav-mobile" id="${id}-mobile" aria-label="Mobile navigation">
     <nav>${mobileLinksHtml}</nav>
   </div>` : ''
 
+  const navContent = [
+    links.length        && `<nav class="ui-nav-links" aria-label="Site navigation">${linksHtml}</nav>`,
+    utilityLinks.length && `<nav class="ui-nav-links ui-nav-utility" aria-label="Utility navigation">${utilityHtml}</nav>`,
+    action              && `<div class="ui-nav-action">${action}</div>`,
+  ].filter(Boolean).join('')
+
   return `<header class="${e(classes)}"${bgStyle}>
   <div class="ui-nav-inner">
     <a href="${e(logoHref)}" class="ui-nav-logo">${logo}</a>
-    ${links.length ? `<nav class="ui-nav-links" aria-label="Site navigation">${linksHtml}</nav>` : ''}
-    ${action ? `<div class="ui-nav-action">${action}</div>` : ''}${burgerHtml}
+    ${navContent}${burgerHtml}
   </div>${mobileMenuHtml}
 </header>`
 }

package/src/ui/phone-frame.js

@@ -5,13 +5,14 @@
  * Renders the phone body, dynamic island, side buttons, and home indicator.
  * No images — pure CSS/HTML.
  *
- * @param {object} opts
- * @param {string} opts.content  - HTML to render inside the screen area
- * @param {string} opts.class
+ * @param {object}  opts
+ * @param {string}  opts.content  - HTML to render inside the screen area
+ * @param {boolean} opts.animate  - enable gentle 3-D tilt on mouse hover (default: false)
+ * @param {string}  opts.class
  */
 
-export function phoneFrame({ content = '', class: cls = '' } = {}) {
-  const classes = ['ui-phone', cls].filter(Boolean).join(' ')
+export function phoneFrame({ content = '', animate = false, class: cls = '' } = {}) {
+  const classes = ['ui-phone', animate && 'ui-phone--tilt', cls].filter(Boolean).join(' ')
 
   return `<div class="${classes}" role="img" aria-label="Phone screen preview">
   <!-- Left buttons: volume up, volume down, mute -->

package/src/ui/photo-card.js

@@ -0,0 +1,44 @@
+/**
+ * Pulse UI — PhotoCard
+ *
+ * Polaroid-style photo card with optional caption and CSS tilt.
+ * Ideal for "meet the team", testimonial portraits, or lifestyle photography.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.src      - Image source URL
+ * @param {string}  opts.alt      - Alt text
+ * @param {string}  opts.caption  - Caption text below the photo
+ * @param {number}  opts.tilt     - CSS rotate degrees, e.g. 2 or -1.5. 0 = no tilt (default)
+ * @param {boolean} opts.rounded  - Adds corner radius to the image (default: false = square crop)
+ * @param {string}  opts.ratio    - CSS aspect-ratio for the image crop (default: '4/3')
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function photoCard({
+  src     = '',
+  alt     = '',
+  caption = '',
+  tilt    = 0,
+  rounded = false,
+  ratio   = '4/3',
+  class: cls = '',
+} = {}) {
+  const safeTilt = parseFloat(tilt) || 0
+  const classes  = [
+    'ui-photo-card',
+    rounded && 'ui-photo-card--rounded',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const tiltStyle = safeTilt ? ` style="--photo-tilt:${safeTilt}deg"` : ''
+  const cropStyle = ratio ? ` style="aspect-ratio:${e(ratio)}"` : ''
+
+  return `<figure class="${e(classes)}"${tiltStyle}>
+  <div class="ui-photo-card-crop"${cropStyle}>
+    <img src="${e(src)}" alt="${e(alt)}" class="ui-photo-card-img" loading="lazy" decoding="async">
+  </div>
+  ${caption ? `<figcaption class="ui-photo-card-caption">${e(caption)}</figcaption>` : ''}
+</figure>`
+}

package/src/ui/product-card.js

@@ -0,0 +1,65 @@
+/**
+ * Pulse UI — Product Card
+ *
+ * Full-bleed editorial product card — the image IS the card. The product
+ * name (and optional price) overlays at the bottom on hover. Designed for
+ * fashion/e-commerce grids where photography is the primary communication.
+ *
+ * Unlike photoCard (polaroid frame + caption always visible), this card is
+ * frameless: the image fills 100% of the card, and metadata is revealed on
+ * hover via a gradient overlay.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.src          - Image source URL
+ * @param {string}  opts.alt          - Alt text
+ * @param {string}  opts.name         - Product name
+ * @param {string}  opts.price        - Optional price string
+ * @param {string}  opts.href         - Link destination (default: '#')
+ * @param {string}  opts.badge        - Short badge text ("NEW", "SALE", "−20%")
+ * @param {'left'|'right'} opts.badgeAlign - Badge corner (default: 'left')
+ * @param {string}  opts.ratio        - CSS aspect-ratio (default: '4/5')
+ * @param {'overlay'|'below'} opts.layout - 'overlay' (hover reveal) or 'below' (caption under image)
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function productCard({
+  src        = '',
+  alt        = '',
+  name       = '',
+  price      = '',
+  href       = '#',
+  badge      = '',
+  badgeAlign = 'left',
+  ratio      = '4/5',
+  layout     = 'overlay',
+  class: cls = '',
+} = {}) {
+  const classes = [
+    'ui-product-card',
+    badgeAlign === 'right' && 'ui-product-card--badge-right',
+    layout === 'below' && 'ui-product-card--below',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const cropStyle = ratio ? ` style="aspect-ratio:${e(ratio)}"` : ''
+
+  const namePrice = name ? (layout === 'below'
+    ? `<div class="ui-product-card-caption">
+    <p class="ui-product-card-name">${e(name)}</p>
+    ${price ? `<p class="ui-product-card-price">${e(price)}</p>` : ''}
+  </div>`
+    : `<div class="ui-product-card-overlay" aria-hidden="true">
+    <p class="ui-product-card-name">${e(name)}</p>
+    ${price ? `<p class="ui-product-card-price">${e(price)}</p>` : ''}
+  </div>`) : ''
+
+  return `<a href="${e(href)}" class="${e(classes)}">
+  <div class="ui-product-card-crop"${cropStyle}>
+    <img src="${e(src)}" alt="${e(alt)}" class="ui-product-card-img" loading="lazy" decoding="async">
+  </div>
+  ${badge ? `<span class="ui-product-card-badge">${e(badge)}</span>` : ''}
+  ${namePrice}
+</a>`
+}

package/src/ui/pullquote.js

@@ -1,12 +1,18 @@
 /**
  * Pulse UI — Pullquote
  *
- * Styled blockquote with accent left border and optional attribution.
+ * Styled blockquote with optional attribution.
+ *
+ * Two variants:
+ *  - Default: left accent border — for inline editorial quotes in prose or sidebars
+ *  - 'editorial': centred large italic serif, no border — for brand voice statements
+ *    in fashion, luxury, or magazine contexts
  *
  * @param {object} opts
  * @param {string} opts.quote  - The quote text
  * @param {string} opts.cite   - Attribution (name, role, etc.)
  * @param {'md'|'lg'} opts.size - Size variant (default: 'md')
+ * @param {'default'|'editorial'} opts.variant - Visual style (default: 'default')
  * @param {string} opts.class
  */
 
@@ -16,10 +22,15 @@ export function pullquote({
   quote      = '',
   cite       = '',
   size       = 'md',
+  variant    = 'default',
   class: cls = '',
 } = {}) {
-  const sizeClass   = size === 'lg' ? 'ui-pullquote--lg' : ''
-  const figClasses  = ['ui-pullquote', sizeClass, cls].filter(Boolean).join(' ')
+  const figClasses  = [
+    'ui-pullquote',
+    size === 'lg'           && 'ui-pullquote--lg',
+    variant === 'editorial' && 'ui-pullquote--editorial',
+    cls,
+  ].filter(Boolean).join(' ')
 
   const citeHtml = cite
     ? `<figcaption class="ui-pullquote-cite">${e(cite)}</figcaption>`

package/src/ui/search.js

@@ -48,6 +48,7 @@ export function search({
     : ''
 
   const attrsStr = Object.entries(attrs)
+    .filter(([, v]) => v !== undefined)
     .map(([k, v]) => ` ${e(k)}="${e(String(v))}"`)
     .join('')
 

package/src/ui/section-label.js

@@ -0,0 +1,38 @@
+/**
+ * Pulse UI — Section Label
+ *
+ * Eyebrow + heading + horizontal rule. The editorial equivalent of feature().
+ * For: chapter openings, section dividers, content blocks.
+ *
+ * @param {object} opts
+ * @param {string} opts.eyebrow - Small label above heading
+ * @param {string} opts.heading - Main heading text
+ * @param {number} opts.level - Heading level 1–6 (default 2)
+ * @param {boolean} opts.rule - Show horizontal rule after heading (default true)
+ * @param {'left'|'center'} opts.align - Text alignment (default 'left')
+ * @param {string} opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function sectionLabel({
+  eyebrow    = '',
+  heading    = '',
+  level      = 2,
+  rule       = true,
+  align      = 'left',
+  class: cls = '',
+} = {}) {
+  const tag = `h${Math.min(Math.max(Math.floor(level), 1), 6)}`
+  const classes = [
+    'ui-section-label',
+    align === 'center' && 'ui-section-label--center',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  return `<div class="${e(classes)}">
+  ${eyebrow ? `<p class="ui-section-label-eyebrow">${e(eyebrow)}</p>` : ''}
+  ${heading ? `<${tag} class="ui-section-label-heading">${e(heading)}</${tag}>` : ''}
+  ${rule ? '<hr class="ui-section-label-rule" aria-hidden="true">' : ''}
+</div>`
+}

package/src/ui/section.js

@@ -21,7 +21,7 @@
 
 import { escHtml as e } from '../html.js'
 
-const VARIANTS = new Set(['default', 'alt', 'dark'])
+const VARIANTS = new Set(['default', 'alt', 'dark', 'diagonal', 'paper', 'spotlight'])
 const PADDINGS = new Set(['sm', 'md', 'lg'])
 const GAPS     = new Set(['none', 'sm', 'md', 'lg'])
 

package/src/ui/service-card.js

@@ -0,0 +1,47 @@
+/**
+ * Pulse UI — ServiceCard
+ *
+ * A bordered, left-aligned tile with icon, title, and description.
+ * The most common pattern for trades/services grids — an unboxed, centred
+ * feature() is the wrong tool for these; serviceCard() is built for it.
+ *
+ * Use inside a grid() or css grid for multi-column layouts.
+ *
+ * @param {object}  opts
+ * @param {string}  opts.icon        - Raw HTML slot — SVG icon displayed in an accent-tinted box
+ * @param {string}  opts.title
+ * @param {number}  opts.level       - Heading level 1–6 (default 3)
+ * @param {string}  opts.description
+ * @param {string}  opts.href        - When set, wraps the card in an <a> making it fully clickable
+ * @param {string}  opts.class
+ */
+
+import { escHtml as e } from '../html.js'
+
+export function serviceCard({
+  icon        = '',
+  title       = '',
+  level       = 3,
+  description = '',
+  href        = '',
+  class: cls  = '',
+} = {}) {
+  const tag = `h${Math.min(Math.max(Math.floor(level), 1), 6)}`
+  const linked = Boolean(href)
+  const classes = [
+    'ui-service-card',
+    linked && 'ui-service-card--linked',
+    cls,
+  ].filter(Boolean).join(' ')
+
+  const inner = `
+  ${icon        ? `<div class="ui-service-card-icon" aria-hidden="true">${icon}</div>` : ''}
+  ${title       ? `<${tag} class="ui-service-card-title">${e(title)}</${tag}>` : ''}
+  ${description ? `<p class="ui-service-card-desc">${e(description)}</p>` : ''}
+`
+
+  if (linked) {
+    return `<a href="${e(href)}" class="${e(classes)}">${inner}</a>`
+  }
+  return `<div class="${e(classes)}">${inner}</div>`
+}

package/src/ui/stat-grid.js

@@ -0,0 +1,40 @@
+/**
+ * Pulse UI — StatGrid
+ *
+ * A grid of stat tiles with optional coloured panel background.
+ * Use when you need multiple stat() tiles arranged together — e.g. a 2×2
+ * "at a glance" panel inside a hero or section.
+ *
+ * Each item is passed directly to stat(). The grid handles layout.
+ *
+ * @param {object}   opts
+ * @param {Array}    opts.stats      - Array of stat() option objects (label, value, change, trend, size, suffix)
+ * @param {number}   opts.columns    - Number of grid columns (default: 2)
+ * @param {string}   opts.background - CSS background value (e.g. 'var(--ui-surface-raised)')
+ * @param {string}   opts.color      - Foreground/text colour override
+ * @param {string}   opts.class
+ */
+
+import { stat }       from './stat.js'
+import { escHtml as e } from '../html.js'
+
+export function statGrid({
+  stats      = [],
+  columns    = 2,
+  background = '',
+  color      = '',
+  class: cls = '',
+} = {}) {
+  const classes = ['ui-stat-grid', cls].filter(Boolean).join(' ')
+
+  const styles = [
+    `--stat-cols:${Number(columns) || 2}`,
+    background && `background:${background.replace(/"/g, "'")}`,
+    color      && `color:${color.replace(/"/g, "'")}`,
+  ].filter(Boolean).join(';')
+  const styleAttr = styles ? ` style="${styles}"` : ''
+
+  const tilesHtml = stats.map(s => stat(s)).join('')
+
+  return `<div class="${e(classes)}"${styleAttr}>${tilesHtml}</div>`
+}

package/src/ui/stat.js

@@ -8,6 +8,11 @@
  * @param {string} opts.value   - Formatted value string (e.g. "2.4k", "98%")
  * @param {string} opts.change  - Change label (e.g. "+12%", "−3")
  * @param {'up'|'down'|'neutral'} opts.trend
+ * @param {string} opts.suffix  - Raw HTML slot appended after the value — use for icons, ratings, units
+ * @param {'sm'|'md'|'lg'} opts.size
+ *   - 'sm'  — compact, for dense grids
+ *   - 'md'  — default
+ *   - 'lg'  — hero-scale, for top-of-page KPIs
  * @param {boolean} opts.center - Centre-align all text
  * @param {string} opts.class
  */
@@ -16,6 +21,7 @@ import { escHtml as e } from '../html.js'
 import { iconTrendingUp, iconTrendingDown, iconMinus } from './icons.js'
 
 const TRENDS = new Set(['up', 'down', 'neutral'])
+const SIZES  = new Set(['sm', 'md', 'lg'])
 
 const TREND_ICONS = {
   up:      iconTrendingUp({ size: 13 }),
@@ -30,12 +36,20 @@ export function stat({
   value      = '',
   change     = '',
   trend      = 'neutral',
+  suffix     = '',
+  size       = 'md',
   center     = false,
   class: cls = '',
 } = {}) {
   if (!TRENDS.has(trend)) trend = 'neutral'
+  if (!SIZES.has(size))   size  = 'md'
 
-  const classes = ['ui-stat', center && 'ui-stat--center', cls].filter(Boolean).join(' ')
+  const classes = [
+    'ui-stat',
+    size !== 'md'  ? `ui-stat--${size}` : '',
+    center         ? 'ui-stat--center'  : '',
+    cls,
+  ].filter(Boolean).join(' ')
 
   const changeHtml = change
     ? `<p class="ui-stat-change ui-stat-change--${e(trend)}">
@@ -46,7 +60,7 @@ export function stat({
 
   return `<div class="${e(classes)}">
   <p class="ui-stat-label">${e(label)}</p>
-  <p class="ui-stat-value">${e(value)}</p>
+  <p class="ui-stat-value">${e(value)}${suffix ? `<span class="ui-stat-suffix" aria-hidden="true">${suffix}</span>` : ''}</p>
   ${changeHtml}
 </div>`
 }

package/src/ui/testimonial.js

@@ -4,11 +4,12 @@
  * A customer quote with optional star rating, avatar, and attribution.
  *
  * @param {object} opts
- * @param {string} opts.quote   - The testimonial text
- * @param {string} opts.name    - Author full name
- * @param {string} opts.role    - Author role/company (e.g. "CEO at Acme")
- * @param {string} opts.src     - Avatar image URL; falls back to initials when omitted
- * @param {number} opts.rating  - Star rating 1–5; omit to hide stars
+ * @param {string} opts.quote    - The testimonial text
+ * @param {string} opts.name     - Author full name
+ * @param {string} opts.role     - Author role/company (e.g. "CEO at Acme")
+ * @param {string} opts.src      - Avatar image URL; falls back to initials when omitted
+ * @param {string} opts.initials - Override auto-derived initials (useful for names containing & or unusual characters)
+ * @param {number} opts.rating   - Star rating 1–5; omit to hide stars
  * @param {string} opts.class
  */
 
@@ -19,6 +20,7 @@ export function testimonial({
   name       = '',
   role       = '',
   src        = '',
+  initials:  initialsOverride = '',
   rating     = 0,
   class: cls = '',
 } = {}) {
@@ -28,7 +30,16 @@ export function testimonial({
     ? `<p class="ui-testimonial-rating" aria-label="${Math.round(rating)} out of 5 stars">${'★'.repeat(Math.min(5, Math.max(1, Math.round(rating))))}</p>`
     : ''
 
-  const initials = name.split(' ').map(w => w[0]).join('').slice(0, 2).toUpperCase()
+  // Filter to letter chars only so names like "Tomás & Ren Okabe" produce "TR" not "T&"
+  const derivedInitials = name
+    .split(/\s+/)
+    .map(w => w.replace(/[^a-zA-ZÀ-ÿ]/g, ''))
+    .filter(Boolean)
+    .map(w => w[0])
+    .join('')
+    .slice(0, 2)
+    .toUpperCase()
+  const initials = initialsOverride || derivedInitials
 
   const avatarHtml = src
     ? `<img src="${e(src)}" alt="${e(name)}" class="ui-testimonial-avatar" loading="lazy" width="40" height="40">`

package/src/ui/textarea.js

@@ -42,6 +42,7 @@ export function textarea({
   const wrapClasses = ['ui-field', error ? 'ui-field--error' : '', cls].filter(Boolean).join(' ')
 
   const attrsStr = Object.entries(attrs)
+    .filter(([, v]) => v !== undefined)
     .map(([k, v]) => ` ${e(k)}="${e(String(v))}"`)
     .join('')