@contentrain/astro-kit 0.30.0 → 0.31.0

package/components/_shared/Section.astro

@@ -3,6 +3,8 @@
 // section component renders inside one, so sections stack evenly whatever
 // their order.
 import { tv } from 'tailwind-variants'
+import { measuredFrame } from './measured'
+import type { MeasuredStyle } from './types'
 
 const section = tv({
   base: '',
@@ -39,10 +41,23 @@ interface Props {
   id?: string | undefined
   class?: string | undefined
   'aria-labelledby'?: string | undefined
+  /** The source section's measured style (`MeasuredStyle`): frame width, padding, fill, image, columns, gap. Wins over `tone`. */
+  measured?: MeasuredStyle | undefined
 }
 
-const { tone, spacing, width = 'page', as: Tag = 'section', id, class: className, 'aria-labelledby': labelledBy } = Astro.props
+const { tone: given, spacing, width = 'page', as: Tag = 'section', id, class: className, 'aria-labelledby': labelledBy, measured } = Astro.props
+const m = measuredFrame(measured)
+// A measured fill is the section's own colour, its text set by the measured tone; a tone alone picks the kit's band.
+const tone = m.color ? 'none' : m.tone === 'dark' ? 'inverse' : m.tone === 'light' ? 'default' : given
+const text = m.color ? (m.tone === 'dark' ? 'text-surface [--color-accent-text:var(--color-accent-text-inverse)]' : 'text-ink') : undefined
+const layered = m.image || m.overlay ? 'relative isolate overflow-hidden' : undefined
+const style = [m.color && `background-color: ${m.color}`, m.style].filter(Boolean).join('; ') || undefined
+// The reading column reads its own width token.
+const frameStyle = width === 'prose' ? m.frameStyle?.replace('--container-page:', '--container-prose:') : m.frameStyle
+const dataTone = m.color ? (m.tone === 'dark' ? 'inverse' : 'default') : tone ?? 'default'
 ---
-<Tag id={id} aria-labelledby={labelledBy} class={section({ tone, spacing, class: className })} data-tone={tone ?? 'default'} data-kit-section data-kit-spacing={spacing ?? 'md'}>
-  {width === 'none' ? <slot /> : <div class={width === 'prose' ? 'container-prose' : 'container-page'}><slot /></div>}
+<Tag id={id} aria-labelledby={labelledBy} class={section({ tone, spacing, class: [text, layered, className].filter(Boolean).join(' ') || undefined })} style={style} data-tone={dataTone} data-kit-section data-kit-spacing={spacing ?? 'md'} data-kit-measured={measured ? '' : undefined}>
+  {m.image && <img src={m.image.src} alt="" loading="lazy" decoding="async" class="absolute inset-0 -z-10 h-full w-full" style={`object-fit: ${m.image.fit}${m.image.position ? `; object-position: ${m.image.position}` : ''}`} />}
+  {m.overlay && <div class="absolute inset-0 -z-10" style={`background: ${m.overlay}`} aria-hidden="true" />}
+  {width === 'none' ? <slot /> : <div class={width === 'prose' ? 'container-prose' : 'container-page'} style={frameStyle}><slot /></div>}
 </Tag>

package/components/_shared/measured.ts

@@ -0,0 +1,142 @@
+// A section's measured style (`MeasuredStyle`) as CSS the kit can trust. The values come from a page the
+// migration measured: data, not CSS. Each one is checked against a small grammar and dropped when it does not
+// fit, so nothing but a number, a colour or a known keyword reaches a style attribute.
+import type { MeasuredStyle, MeasuredWidth } from './types'
+
+const clamp = (value: unknown, min: number, max: number): number | undefined =>
+  typeof value === 'number' && Number.isFinite(value) && value >= min && value <= max ? Math.round(value) : undefined
+
+const HEX = /^#(?:[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/i
+const FUNCTIONAL = /^(?:rgba?|hsla?)\(\s*[\d.]+%?(?:\s*[,\s]\s*[\d.]+%?){2}(?:\s*[,/]\s*[\d.]+%?)?\s*\)$/i
+const NAMED = /^(?:transparent|white|black)$/i
+
+/** A colour the source wrote as hex, rgb(a) or hsl(a) (or transparent / white / black); anything else is dropped. */
+const colorOf = (value: unknown): string | undefined =>
+  typeof value === 'string' && (HEX.test(value.trim()) || FUNCTIONAL.test(value.trim()) || NAMED.test(value.trim())) ? value.trim() : undefined
+
+/** Whether a colour is dark enough to need light text (relative luminance under 0.4); unknown for named and hsl colours. */
+const isDark = (color: string): boolean | undefined => {
+  const hex = HEX.test(color) ? color.slice(1) : undefined
+  const channels = hex
+    ? (hex.length <= 4 ? hex.slice(0, 3).split('').map(digit => Number.parseInt(digit + digit, 16)) : [0, 2, 4].map(i => Number.parseInt(hex.slice(i, i + 2), 16)))
+    : /^rgba?\(/i.test(color) ? color.match(/[\d.]+%?/g)!.slice(0, 3).map(v => (v.endsWith('%') ? Number.parseFloat(v) * 2.55 : Number.parseFloat(v))) : undefined
+  if (!channels) return /^black$/i.test(color) ? true : /^white$/i.test(color) ? false : undefined
+  const [r, g, b] = channels.map(v => { const c = v / 255; return c <= 0.039_28 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4 })
+  return 0.2126 * r! + 0.7152 * g! + 0.0722 * b! < 0.4
+}
+
+const STOP = /^(.+?)(?:\s+\d{1,3}(?:\.\d+)?%){0,2}$/
+const DIRECTION = /^(?:\d{1,3}(?:\.\d+)?deg|to (?:top|bottom|left|right)(?: (?:top|bottom|left|right))?|circle|ellipse)$/
+/** Splits at commas outside parentheses: `rgba(0, 0, 0, .5) 0%, #000` → two stops. */
+const topLevel = (inner: string): string[] => {
+  const parts: string[] = []
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < inner.length; i++) {
+    if (inner[i] === '(') depth++
+    else if (inner[i] === ')') depth--
+    else if (inner[i] === ',' && depth === 0) { parts.push(inner.slice(start, i).trim()); start = i + 1 }
+    if (depth < 0) return []
+  }
+  return depth === 0 ? [...parts, inner.slice(start).trim()] : []
+}
+/** An overlay: a colour, or a linear/radial gradient whose every stop is a colour (with up to two percentages). */
+const overlayOf = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') return undefined
+  const text = value.trim()
+  const gradient = /^(linear|radial)-gradient\((.*)\)$/i.exec(text)
+  if (!gradient) return colorOf(text)
+  const parts = topLevel(gradient[2]!)
+  if (parts.length < 2) return undefined
+  const [first, ...rest] = DIRECTION.test(parts[0]!) ? parts : ['', ...parts]
+  const stops = first ? rest : parts
+  return stops.length >= 2 && stops.every(stop => colorOf(STOP.exec(stop)?.[1]) !== undefined) ? text : undefined
+}
+
+/** An image address: http(s) or root-relative, with nothing that could close a quote or a url(). */
+const imageOf = (value: unknown): string | undefined =>
+  typeof value === 'string' && /^(?:https?:\/\/|\/(?!\/))/i.test(value) && !/["'()<>\\\s]/.test(value) ? value : undefined
+
+const KEYWORD = /^(?:center|top|bottom|left|right)$/
+const PERCENT = /^\d{1,3}(?:\.\d+)?%$/
+/** `object-position` from the source's background position: up to two keywords or percentages. */
+const positionOf = (value: unknown): string | undefined => {
+  if (typeof value !== 'string') return undefined
+  const parts = value.trim().toLowerCase().split(/\s+/)
+  return parts.length <= 2 && parts.every(part => KEYWORD.test(part) || PERCENT.test(part)) ? parts.join(' ') : undefined
+}
+
+/** `object-fit` from the source's background size. */
+const fitOf = (value: unknown): 'cover' | 'contain' | 'none' | undefined =>
+  value === 'cover' || value === 'contain' ? value : value === 'auto' ? 'none' : undefined
+
+/** Columns at each measured width, every width filled: 390 ?? 1; 768 ?? min(2, 1280) ?? 390; 1280 ?? 768 ?? 390. */
+const columnsFor = (columns: MeasuredStyle['columns']): Record<MeasuredWidth, number> | undefined => {
+  if (!columns) return undefined
+  const at = (width: MeasuredWidth) => clamp(columns[width], 1, 6)
+  const [narrow, mid, wide] = [at(390), at(768), at(1280)]
+  if (narrow === undefined && mid === undefined && wide === undefined) return undefined
+  const phone = narrow ?? 1
+  const tablet = mid ?? (wide === undefined ? phone : Math.min(2, wide))
+  return { 390: phone, 768: tablet, 1280: wide ?? mid ?? phone }
+}
+
+/** What Section draws from a measured style. Empty (`{}`) when there is nothing to draw. */
+export interface MeasuredFrame {
+  /** Inline style on the section element: custom properties and the section's own box. */
+  style?: string | undefined
+  /** Inline style on the frame: its width (`--container-page`; Section renames it for the reading column) and gutter. */
+  frameStyle?: string | undefined
+  /** The section's text colour, from what the band's text is set for. */
+  tone?: 'light' | 'dark' | undefined
+  /** The section's own background colour (it then draws no tone fill). */
+  color?: string | undefined
+  image?: { src: string, fit?: 'cover' | 'contain' | 'none' | undefined, position?: string | undefined } | undefined
+  /** A colour or gradient over the image (or over the fill); it is drawn as a layer's `background`. */
+  overlay?: string | undefined
+}
+
+export function measuredFrame(measured: MeasuredStyle | undefined): MeasuredFrame {
+  if (!measured) return {}
+  const own: string[] = []
+  const frame: string[] = []
+  const container = clamp(measured.containerPx, 240, 2560)
+  const padY = clamp(measured.padY, 0, 400)
+  const padX = clamp(measured.padX, 0, 200)
+  const gap = clamp(measured.gap, 0, 200)
+  const radius = clamp(measured.radius, 0, 200)
+  const minHeight = clamp(measured.minHeight, 0, 2000)
+  const columns = columnsFor(measured.columns)
+  if (columns) own.push(`--kit-cols-390: ${columns[390]}`, `--kit-cols-768: ${columns[768]}`, `--kit-cols-1280: ${columns[1280]}`)
+  if (gap !== undefined) own.push(`--kit-gap: ${gap}px`)
+  if (radius !== undefined) own.push(`--radius-card: ${radius}px`)
+  if (padY !== undefined) own.push(`padding-block: ${padY}px`)
+  if (minHeight) own.push(`min-height: ${minHeight}px`)
+  // The frame's width without its gutter, as `container-page` takes it; the gutter is the side padding.
+  if (container !== undefined) frame.push(`--container-page: ${container}px`)
+  if (padX !== undefined) frame.push(`--spacing-gutter: ${padX}px`)
+  const color = colorOf(measured.bg?.color)
+  const src = imageOf(measured.bg?.image)
+  // The text's tone as measured; with a fill and no tone, the fill's own lightness decides.
+  const given = measured.tone === 'light' || measured.tone === 'dark' ? measured.tone : undefined
+  const tone = given ?? (color === undefined ? undefined : isDark(color) ? 'dark' : 'light')
+  return {
+    style: own.length ? own.join('; ') : undefined,
+    frameStyle: frame.length ? frame.join('; ') : undefined,
+    tone,
+    color,
+    image: src ? { src, fit: fitOf(measured.bg?.size) ?? 'cover', position: positionOf(measured.bg?.position) } : undefined,
+    overlay: overlayOf(measured.bg?.overlay),
+  }
+}
+
+/**
+ * A list's grid at the measured columns and gap, or `undefined` to keep the component's own variant. The class
+ * names are written out in full so Tailwind finds them; Section sets the custom properties they read.
+ */
+export function measuredGrid(measured: MeasuredStyle | undefined): string | undefined {
+  if (!measured) return undefined
+  const columns = columnsFor(measured.columns) ? 'grid-cols-[repeat(var(--kit-cols-390),minmax(0,1fr))] md:grid-cols-[repeat(var(--kit-cols-768),minmax(0,1fr))] lg:grid-cols-[repeat(var(--kit-cols-1280),minmax(0,1fr))]' : ''
+  const gap = clamp(measured.gap, 0, 200) !== undefined ? 'gap-[var(--kit-gap)] md:gap-[var(--kit-gap)]' : ''
+  return [columns, gap].filter(Boolean).join(' ') || undefined
+}

package/components/_shared/types.ts

@@ -25,3 +25,43 @@ export interface ActionInput extends LinkInput {
 export interface NavItem extends LinkInput {
   children?: NavItem[] | undefined
 }
+
+/** The widths a migration measures a page at: phone, tablet, desktop (the kit's base, `md` and `lg`). */
+export type MeasuredWidth = 390 | 768 | 1280
+
+/**
+ * A section's style as measured on the source page (`MeasuredStyle` in `@contentrain/types`, same fields). Absent,
+ * a section takes the site's tokens; present, it wins over the tone and column variants. Values are pixels; Section
+ * checks each one and drops what is not a number, a colour or a known keyword.
+ */
+export interface MeasuredStyle {
+  /** The frame's content width. */
+  containerPx?: number | undefined
+  /** The section's top and bottom padding. */
+  padY?: number | undefined
+  /** The frame's side padding (the gutter). */
+  padX?: number | undefined
+  bg?: {
+    /** Hex, rgb(a) or hsl(a). */
+    color?: string | undefined
+    /** http(s) or root-relative address; drawn as an image behind the content. */
+    image?: string | undefined
+    /** A colour or a linear/radial gradient laid over the image (or the fill). */
+    overlay?: string | undefined
+    /** `cover`, `contain` or `auto`; anything else draws as `cover`. */
+    size?: string | undefined
+    /** One or two of center/top/bottom/left/right or percentages. */
+    position?: string | undefined
+  } | undefined
+  /** Item columns per measured width; a missing width follows the narrower one. */
+  columns?: Partial<Record<MeasuredWidth, number>> | undefined
+  /** The gap between items. */
+  gap?: number | undefined
+  /** What the section's text is set for: `dark` is light text on a dark band. */
+  tone?: 'light' | 'dark' | undefined
+  /** Where the heading and lead sit across the frame; a component with its own `align` reads it when that is not set. */
+  align?: 'start' | 'center' | 'end' | undefined
+  /** Card and item corner radius. */
+  radius?: number | undefined
+  minHeight?: number | undefined
+}

package/components/band/Band.astro

@@ -0,0 +1,132 @@
+---
+// A section the migration has no closer component for: a band with an optional heading, lead, image, a grid of
+// items and buttons. It draws whatever a measured source section holds, so an unrecognised section still reads as
+// one of the site's sections and never as bare text.
+import { tv } from 'tailwind-variants'
+import Button from '../_shared/Button.astro'
+import KitImage from '../_shared/KitImage.astro'
+import Section, { type Tone } from '../_shared/Section.astro'
+import { measuredGrid } from '../_shared/measured'
+import type { ActionInput, ImageInput, MeasuredStyle } from '../_shared/types'
+
+const band = tv({
+  slots: {
+    grid: 'grid gap-10',
+    copy: 'flex max-w-3xl flex-col gap-4',
+    eyebrow: 'text-sm font-semibold tracking-wide text-accent-text uppercase',
+    heading: 'text-3xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-4xl',
+    lead: 'text-lg text-pretty opacity-85',
+    media: 'overflow-hidden rounded-[var(--radius-image,var(--radius-card))]',
+    list: 'grid items-start gap-6 md:gap-8',
+    item: 'relative flex flex-col gap-3 rounded-[var(--radius-card)]',
+    itemMedia: 'overflow-hidden rounded-[var(--radius-image,var(--radius-card))]',
+    itemTitle: 'text-lg leading-snug [font-weight:var(--font-weight-heading,600)] text-balance',
+    itemValue: 'text-4xl [font-weight:var(--font-weight-heading,700)] tracking-tight',
+    itemMeta: 'text-sm opacity-75',
+    itemText: 'opacity-80',
+    itemPoints: 'flex list-disc flex-col gap-1 ps-5 opacity-80',
+    actions: 'flex flex-wrap gap-3',
+  },
+  variants: {
+    // stack: everything in one column. split: the copy beside the image on wide screens.
+    layout: { stack: {}, split: { grid: 'md:grid-cols-2 md:items-center' } },
+    columns: {
+      '1': {},
+      '2': { list: 'sm:grid-cols-2' },
+      '3': { list: 'sm:grid-cols-2 md:grid-cols-3' },
+      '4': { list: 'sm:grid-cols-2 lg:grid-cols-4' },
+    },
+    align: {
+      start: {},
+      center: { copy: 'mx-auto items-center text-center', actions: 'justify-center', item: 'items-center text-center' },
+    },
+    // Accent backgrounds have the least contrast headroom: text on them is never dimmed.
+    tone: { default: {}, muted: {}, inverse: {}, accent: { lead: 'opacity-100', itemText: 'opacity-100', itemMeta: 'opacity-100', itemPoints: 'opacity-100', eyebrow: 'text-current' } },
+  },
+  defaultVariants: { layout: 'stack', columns: '3', align: 'start', tone: 'default' },
+})
+
+interface Item {
+  /** A figure drawn large above the title (a stat, a price). */
+  value?: string | undefined
+  title?: string | undefined
+  /** A short line under the title (a role, a date, a period). */
+  meta?: string | undefined
+  text?: string | undefined
+  href?: string | undefined
+  /** The link's own text, shown under the item; without it the whole item is the link. */
+  linkLabel?: string | undefined
+  /** The item's image address. */
+  media?: string | undefined
+  mediaAlt?: string | undefined
+  /** A small image (an icon) above the title. */
+  icon?: string | undefined
+  /** A short list under the text (features, facts). */
+  points?: string[] | undefined
+}
+
+interface Props {
+  heading?: string | undefined
+  eyebrow?: string | undefined
+  lead?: string | undefined
+  media?: ImageInput | undefined
+  items?: Item[] | undefined
+  actions?: ActionInput[] | undefined
+  /** Heading level of the section heading; item titles are one level below, or at this level when there is none. */
+  headingLevel?: 2 | 3 | undefined
+  layout?: 'stack' | 'split' | undefined
+  columns?: '1' | '2' | '3' | '4' | undefined
+  align?: 'start' | 'center' | undefined
+  tone?: Tone | undefined
+  measured?: MeasuredStyle | undefined
+  id?: string | undefined
+}
+
+const { heading, eyebrow, lead, media, items = [], actions = [], headingLevel = 2, layout, columns, align, tone, measured, id } = Astro.props
+// The measured alignment when none is given (`end` has no band layout: it reads as `start`).
+const aligned = align ?? (measured?.align === 'center' ? 'center' : undefined)
+const s = band({ layout: media ? layout : 'stack', columns, align: aligned, tone })
+const Heading = `h${headingLevel}` as 'h2' | 'h3'
+const ItemHeading = `h${heading ? headingLevel + 1 : headingLevel}` as 'h2' | 'h3' | 'h4'
+const headingId = heading ? (id ? `${id}-title` : `band-${heading.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`) : undefined
+const hasCopy = Boolean(heading || eyebrow || lead || actions.length)
+---
+<Section tone={tone} id={id} aria-labelledby={headingId} measured={measured}>
+  <div class="flex flex-col gap-10">
+    {(hasCopy || media) && (
+      <div class={s.grid()}>
+        {hasCopy && (
+          <div class={s.copy()}>
+            {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
+            {heading && <Heading id={headingId} class={s.heading()}>{heading}</Heading>}
+            {lead && <p class={s.lead()} data-kit-text>{lead}</p>}
+            {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} size="lg" />)}</div>}
+          </div>
+        )}
+        {media && <div class={s.media()}><KitImage image={media} sizes={layout === 'split' ? '(min-width: 768px) 50vw, 100vw' : '100vw'} class="h-auto w-full object-cover" /></div>}
+      </div>
+    )}
+    {items.length > 0 && (
+      <ul class={s.list({ class: measuredGrid(measured) })}>
+        {items.map(item => (
+          <li class={s.item()}>
+            {item.media && <div class={s.itemMedia()}><KitImage image={{ src: item.media, alt: item.mediaAlt ?? '' }} sizes="(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 100vw" class="aspect-[3/2] w-full object-cover" /></div>}
+            {item.icon && <KitImage image={{ src: item.icon, alt: '' }} class="h-10 w-10 object-contain" />}
+            {item.value && <p class={s.itemValue()}>{item.value}</p>}
+            {item.title && (
+              <ItemHeading class={s.itemTitle()}>
+                {item.href && !item.linkLabel
+                  ? <a href={item.href} class="text-current no-underline after:absolute after:inset-0 after:content-[''] hover:text-accent-text">{item.title}</a>
+                  : item.title}
+              </ItemHeading>
+            )}
+            {item.meta && <p class={s.itemMeta()}>{item.meta}</p>}
+            {item.text && <p class={s.itemText()} data-kit-text>{item.text}</p>}
+            {item.points && item.points.length > 0 && <ul class={s.itemPoints()}>{item.points.map(point => <li>{point}</li>)}</ul>}
+            {item.href && item.linkLabel && <a href={item.href} class="font-medium text-accent-text underline-offset-4 hover:underline">{item.linkLabel}</a>}
+          </li>
+        ))}
+      </ul>
+    )}
+  </div>
+</Section>

package/components/band/fixtures.json

@@ -0,0 +1,8 @@
+[
+  {"name": "plain", "props": {"heading": "What we do", "lead": "Three things, done carefully.", "items": [{"title": "Design", "text": "Tokens and components."}, {"title": "Migration", "text": "Every address kept."}, {"title": "Speed", "text": "Static and fast."}], "tone": "inverse"}},
+  {"name": "split-actions", "props": {"layout": "split", "eyebrow": "About", "heading": "A studio of six", "lead": "We build sites people keep editing.", "media": {"src": "/kit-fixtures/photo-1.svg", "alt": "", "width": 1200, "height": 800}, "actions": [{"label": "Contact us", "href": "/contact/"}], "tone": "accent"}},
+  {"name": "measured-dark-fill", "props": {"heading": "Our numbers", "align": "center", "measured": {"containerPx": 1140, "padY": 96, "padX": 24, "bg": {"color": "#0f172a"}, "columns": {"390": 1, "768": 2, "1280": 4}, "gap": 32, "radius": 8}, "items": [{"title": "12", "text": "years"}, {"title": "340", "text": "sites"}, {"title": "9", "text": "countries"}, {"title": "1", "text": "team"}], "columns": "4"}},
+  {"name": "measured-image-overlay", "props": {"heading": "Visit the farm", "lead": "Open every weekend.", "actions": [{"label": "Plan a visit", "href": "/visit/"}], "measured": {"padY": 120, "minHeight": 480, "tone": "dark", "bg": {"image": "/kit-fixtures/photo-2.svg", "overlay": "rgba(0, 0, 0, 0.55)", "size": "cover", "position": "center"}}, "columns": "1"}},
+  {"name": "items-links", "props": {"heading": "Services", "columns": "2", "tone": "muted", "items": [{"title": "Audits", "text": "Where a site loses readers.", "href": "/audits/", "linkLabel": "Read more", "media": "/kit-fixtures/photo-3.svg"}, {"title": "Hosting", "text": "Static hosting, managed.", "href": "/hosting/", "icon": "/kit-fixtures/logo.svg"}]}},
+  {"name": "values-points", "props": {"heading": "Plans", "columns": "3", "items": [{"value": "$9", "title": "Starter", "meta": "per month", "points": ["One site", "Email support"]}, {"value": "$29", "title": "Team", "meta": "per month", "points": ["Five sites", "Shared components"], "href": "/pricing/team/", "linkLabel": "Choose Team"}, {"value": "250+", "title": "Sites moved", "text": "Since 2019."}]}}
+]