@contentrain/astro-kit 0.31.0 → 0.33.0

package/components/split/fixtures.json

@@ -2,5 +2,12 @@
   { "name": "end-default", "props": { "eyebrow": "Our studio", "heading": "Small team, careful work", "body": "We have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.", "actions": [{ "label": "Meet the team", "href": "/team/" }, { "label": "Our process", "href": "/process/", "style": "ghost" }], "image": { "src": "/kit-fixtures/photo-2.svg", "alt": "The studio's workshop", "width": 1200, "height": 800 } } },
   { "name": "start-muted", "props": { "imageSide": "start", "tone": "muted", "heading": "Content you can edit", "body": "Pages live as structured content in your own repository, editable in [Contentrain Studio](/studio/).", "image": { "src": "/kit-fixtures/photo-3.svg", "alt": "", "width": 1200, "height": 800 } } },
   { "name": "center-inverse", "props": { "align": "center", "tone": "inverse", "heading": "Fast by default", "body": "Static HTML and one stylesheet.", "actions": [{ "label": "See the numbers", "href": "/performance/" }], "image": { "src": "/kit-fixtures/photo-4.svg", "alt": "", "width": 1200, "height": 800 } } },
-  { "name": "accent", "props": { "tone": "accent", "eyebrow": "New", "heading": "Now with search", "body": "Every page is indexed at build time.", "image": { "src": "/kit-fixtures/photo-5.svg", "alt": "", "width": 1200, "height": 800 } } }
+  { "name": "accent", "props": { "tone": "accent", "eyebrow": "New", "heading": "Now with search", "body": "Every page is indexed at build time.", "image": { "src": "/kit-fixtures/photo-5.svg", "alt": "", "width": 1200, "height": 800 } } },
+  { "name": "ratio-5-7-cover-square", "props": { "heading": "Small team, careful work", "body": "We have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.", "ratio": "5:7", "imageFit": "cover", "imageShape": "none", "image": { "src": "/kit-fixtures/photo-1.svg", "alt": "The studio's workshop", "width": 1200, "height": 800 } } },
+  { "name": "ratio-7-5-start-features", "props": { "heading": "Why teams choose us", "body": "We have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.", "ratio": "7:5", "imageSide": "start", "features": [{ "title": "Fast", "text": "Static pages, one stylesheet.", "icon": "bolt" }, { "title": "Safe", "text": "Your repository stays yours.", "icon": "shield" }, { "title": "Editable", "text": "Change copy without a developer.", "icon": "chat" }], "featureStyle": "icon", "image": { "src": "/kit-fixtures/photo-2.svg", "alt": "The studio's workshop", "width": 1200, "height": 800 }, "tone": "muted" } },
+  { "name": "circle-media-first", "props": { "heading": "Meet the founder", "body": "We have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.", "imageShape": "circle", "stackOrder": "media-first", "image": { "src": "/kit-fixtures/photo-3.svg", "alt": "The studio's workshop", "width": 1200, "height": 800 } } },
+  { "name": "bleed-edge-end", "props": { "heading": "A wider picture", "body": "We have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.", "imageBleed": "edge", "image": { "src": "/kit-fixtures/photo-4.svg", "alt": "The studio's workshop", "width": 1200, "height": 800 }, "tone": "brand" } },
+  { "name": "bleed-edge-start-none", "props": { "heading": "From the other side", "body": "We have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.", "imageBleed": "edge", "imageSide": "start", "image": { "src": "/kit-fixtures/photo-5.svg", "alt": "The studio's workshop", "width": 1200, "height": 800 }, "tone": "none" } },
+  { "name": "video-sticky-check", "props": { "heading": "See how it works", "headingLevel": 3, "mediaKind": "video", "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "playLabel": "Play video", "sticky": true, "body": "We have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.\n\nWe have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.\n\nWe have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.", "features": [{ "title": "Fast", "text": "Static pages, one stylesheet.", "icon": "bolt" }, { "title": "Safe", "text": "Your repository stays yours.", "icon": "shield" }], "image": { "src": "/kit-fixtures/photo-6.svg", "alt": "The studio's workshop", "width": 1200, "height": 800 } } },
+  { "name": "measured-frame", "props": { "eyebrow": "Our studio", "heading": "Small team, careful work", "body": "We have built websites for independent publishers since 2012.\n\nEvery project gets **one** designer and one engineer from start to launch.", "actions": [{ "label": "Meet the team", "href": "/team/" }, { "label": "Our process", "href": "/process/", "style": "ghost" }], "image": { "src": "/kit-fixtures/photo-2.svg", "alt": "The studio's workshop", "width": 1200, "height": 800 }, "measured": { "containerPx": 1000, "padY": 80, "bg": { "color": "#eef2ff" }, "tone": "light" } } }
 ]

package/components/split/meta.json

@@ -3,12 +3,16 @@
   "name": "Split",
   "description": "An image beside a block of text — eyebrow, heading, a markdown body and buttons — on either side, stacked on phones. The media-and-text section of a landing page (Gutenberg media-text, a two-column Elementor container with an image, Divi's image + text row).",
   "category": "section",
-  "uses": [],
+  "uses": [
+    "embed",
+    "feature-list"
+  ],
   "shared": [
     "Button.astro",
     "KitImage.astro",
     "Section.astro",
     "measured.ts",
+    "safe-url.ts",
     "types.ts"
   ],
   "variants": {
@@ -20,6 +24,64 @@
       "default": "end",
       "description": "Which side the image takes on wide screens: start (left in left-to-right text) or end. Phones always show it after the text."
     },
+    "ratio": {
+      "options": [
+        "1:1",
+        "5:7",
+        "7:5"
+      ],
+      "default": "1:1",
+      "description": "The text column's share against the image's: equal, text 5 to image 7, or text 7 to image 5."
+    },
+    "imageFit": {
+      "options": [
+        "contain",
+        "cover"
+      ],
+      "default": "contain",
+      "description": "contain: the image at its own proportions. cover: it fills the column's height."
+    },
+    "imageShape": {
+      "options": [
+        "none",
+        "rounded",
+        "circle"
+      ],
+      "default": "rounded",
+      "description": "The image's corners: square, the theme's rounding, or a circle."
+    },
+    "imageBleed": {
+      "options": [
+        "none",
+        "edge"
+      ],
+      "default": "none",
+      "description": "edge: the image runs on to the edge of the screen on its side (wide screens)."
+    },
+    "mediaKind": {
+      "options": [
+        "image",
+        "video"
+      ],
+      "default": "image",
+      "description": "image: the picture. video: the picture is the poster of a video that loads only when played."
+    },
+    "featureStyle": {
+      "options": [
+        "check",
+        "icon"
+      ],
+      "default": "check",
+      "description": "The marks of the points under the text: a check, or each point's own icon."
+    },
+    "stackOrder": {
+      "options": [
+        "text-first",
+        "media-first"
+      ],
+      "default": "text-first",
+      "description": "On a phone: the text first, or the picture first."
+    },
     "align": {
       "options": [
         "start",
@@ -33,10 +95,12 @@
         "default",
         "muted",
         "inverse",
-        "accent"
+        "accent",
+        "brand",
+        "none"
       ],
       "default": "default",
-      "description": "Section background."
+      "description": "Section background (brand: the site's brand colour; none: the page's own)."
     }
   },
   "props": {
@@ -46,6 +110,12 @@
       "required": true,
       "description": "The section heading."
     },
+    "headingLevel": {
+      "type": "integer",
+      "default": 2,
+      "content": false,
+      "description": "The heading's level: 2 under the page title; 3 or 4 when the section sits inside another."
+    },
     "eyebrow": {
       "type": "string",
       "label": "Eyebrow",
@@ -121,10 +191,162 @@
       },
       "description": "The image beside the text. Width and height, when known, let the site reserve its space."
     },
+    "features": {
+      "type": "array",
+      "label": "Points",
+      "items": {
+        "type": "object",
+        "fields": {
+          "title": {
+            "type": "string",
+            "label": "Title",
+            "required": true,
+            "description": "The point, in a few words."
+          },
+          "text": {
+            "type": "string",
+            "label": "Text",
+            "description": "A line about it."
+          },
+          "icon": {
+            "type": "string",
+            "label": "Icon",
+            "description": "A kit icon name (check, star, bolt, shield, heart, globe, clock, chat)."
+          }
+        }
+      },
+      "description": "Short points under the text (an Elementor icon list or icon box, a Gutenberg list), each with a title and a line."
+    },
+    "videoUrl": {
+      "type": "url",
+      "label": "Video",
+      "description": "A video page (YouTube, Vimeo); the image is its poster and nothing loads from the provider until it is played."
+    },
+    "playLabel": {
+      "type": "string",
+      "content": false,
+      "description": "The play button's text (ui-strings embed.play)."
+    },
+    "measured": {
+      "type": "object",
+      "content": false,
+      "description": "The source section's measured style (MeasuredStyle): frame width, padding, fill, image, columns per width, gap, text tone, radius, minimum height — all in pixels. Absent, the site's tokens; present, it wins over tone and columns. Values that are not a number, a colour or a known keyword are dropped.",
+      "fields": {
+        "containerPx": {
+          "type": "integer",
+          "min": 0,
+          "max": 2560,
+          "description": "The frame's content width."
+        },
+        "padY": {
+          "type": "integer",
+          "min": 0,
+          "max": 400,
+          "description": "Top and bottom padding."
+        },
+        "padX": {
+          "type": "integer",
+          "min": 0,
+          "max": 200,
+          "description": "The frame's side padding (gutter)."
+        },
+        "bg": {
+          "type": "object",
+          "description": "The section's background.",
+          "fields": {
+            "color": {
+              "type": "string",
+              "description": "Fill colour: hex, rgb(a) or hsl(a)."
+            },
+            "image": {
+              "type": "string",
+              "description": "Background image address (http(s) or root-relative), drawn behind the content."
+            },
+            "overlay": {
+              "type": "string",
+              "description": "Colour or linear/radial gradient laid over the image or the fill."
+            },
+            "size": {
+              "type": "string",
+              "description": "cover, contain or auto; anything else draws as cover."
+            },
+            "position": {
+              "type": "string",
+              "description": "One or two of center/top/bottom/left/right or percentages."
+            }
+          }
+        },
+        "columns": {
+          "type": "object",
+          "description": "Item columns at 390 (base), 768 (md) and 1280 (lg) px; a missing width follows the narrower one.",
+          "fields": {
+            "390": {
+              "type": "integer",
+              "min": 1,
+              "max": 6,
+              "description": "Phone."
+            },
+            "768": {
+              "type": "integer",
+              "min": 1,
+              "max": 6,
+              "description": "Tablet."
+            },
+            "1280": {
+              "type": "integer",
+              "min": 1,
+              "max": 6,
+              "description": "Desktop."
+            }
+          }
+        },
+        "gap": {
+          "type": "integer",
+          "min": 0,
+          "max": 200,
+          "description": "Gap between items."
+        },
+        "tone": {
+          "type": "select",
+          "options": [
+            "light",
+            "dark"
+          ],
+          "description": "What the text is set for: dark = light text on a dark band. Without it, a fill's own lightness decides."
+        },
+        "align": {
+          "type": "select",
+          "options": [
+            "start",
+            "center",
+            "end"
+          ],
+          "description": "Where the heading and lead sit; read by a component whose own align is not set."
+        },
+        "radius": {
+          "type": "integer",
+          "min": 0,
+          "max": 200,
+          "description": "Card and item corner radius."
+        },
+        "minHeight": {
+          "type": "integer",
+          "min": 0,
+          "max": 2000,
+          "description": "The section's minimum height."
+        }
+      }
+    },
     "id": {
       "type": "string",
       "content": false,
       "description": "Anchor id of the section; the heading gets `<id>-title`."
+    },
+    "sticky": {
+      "type": "boolean",
+      "default": false,
+      "content": false,
+      "description": "The picture stays in view while a long text scrolls past it (wide screens)."
     }
   },
   "slots": {},
@@ -141,7 +363,7 @@
       "divi/et_pb_image"
     ]
   },
-  "a11y": "The section is labelled by its heading. The image is a separate figure in reading order after the text; an empty description marks a decorative one.",
+  "a11y": "The section is labelled by its heading. The image is a separate figure in reading order after the text; an empty description marks a decorative one. With stackOrder media-first the picture comes first on a phone by CSS order only: the DOM and so the reading order stay text first, which is right when the picture is decoration; give the picture an empty description then.",
   "pattern": {
     "summary": "image beside heading + text",
     "signals": [

package/components/stats/Stats.astro

@@ -2,24 +2,56 @@
 // A row of figures, each with a short label, under an optional heading and
 // intro. Figures are static text: no counting animation.
 import { tv } from 'tailwind-variants'
+import KitImage from '../_shared/KitImage.astro'
 import Section, { type Tone } from '../_shared/Section.astro'
+import { imageOf, type ImageSource } from '../_shared/image'
+import { measuredGrid } from '../_shared/measured'
+import type { MeasuredStyle } from '../_shared/types'
 
 const stats = tv({
   slots: {
     list: 'grid grid-cols-2 gap-6 md:gap-8',
     item: 'flex gap-1',
-    value: 'text-4xl [font-weight:var(--font-weight-heading,700)] tracking-tight tabular-nums md:text-5xl',
+    // nowrap keeps a figure with its prefix and suffix ("99.9%" never splits into "99.9" / "%").
+    // The size is one pair of variables (valueSize sets them): --stat-max below md, --stat-max-md from md. Its line
+    // height comes with valueSize too: a font-size class merged in later would drop one set here.
+    value: 'text-[length:var(--stat-max,2.25rem)] [font-weight:var(--font-weight-heading,700)] tracking-tight tabular-nums whitespace-nowrap [--stat-max-md:3rem] md:text-[length:var(--stat-max-md)]',
+    icon: 'mb-3 block size-10 object-contain',
     label: 'text-sm opacity-80',
   },
   variants: {
+    // grid: figures in columns. inline: one line that wraps, for two to four short figures.
+    layout: {
+      // Each cell is a size container; a figure is no wider than the cell: its size is capped by 100cqi over its
+      // character count (--stat-chars, about 0.66em a character), so a long one ("1.250+", "€12.5M") in four columns at
+      // tablet width shrinks to fit the card, and a short one keeps the size valueSize gives it.
+      grid: {
+        item: '[container-type:inline-size] min-w-0',
+        value: 'text-[length:min(var(--stat-max,2.25rem),max(1.25rem,calc(100cqi_/_(var(--stat-chars,1)_*_0.66))))] md:text-[length:min(var(--stat-max-md),max(1.25rem,calc(100cqi_/_(var(--stat-chars,1)_*_0.66))))]',
+      },
+      inline: { list: 'flex flex-wrap gap-x-12 gap-y-6 md:gap-x-16' },
+    },
     columns: {
       '2': { list: 'md:grid-cols-2' },
       '3': { list: 'md:grid-cols-3' },
       '4': { list: 'md:grid-cols-4' },
+      '5': { list: 'md:grid-cols-3 lg:grid-cols-5' },
+      '6': { list: 'md:grid-cols-3 lg:grid-cols-6' },
     },
     style: {
       plain: {},
       card: { item: 'rounded-[var(--radius-card)] bg-surface p-6 text-ink ring-1 ring-line/60' },
+      // Hairlines between the figures, none before the first, no box: across on a wide screen, above each on a phone.
+      // Meant for a single row (figures no more than the columns); a wrapped row starts with a line.
+      divided: { item: 'border-t border-line pt-6 first:border-t-0 first:pt-0 md:border-t-0 md:pt-0 md:border-s md:ps-6 md:first:border-s-0 md:first:ps-0' },
+    },
+    align: { start: {}, center: { item: 'items-center text-center', icon: 'mx-auto' } },
+    // The figure's size: md, lg (the default), xl, or a display number.
+    valueSize: {
+      md: { value: '[--stat-max:1.875rem] [--stat-max-md:2.25rem] leading-[1.2] md:leading-[1.1112]' },
+      lg: { value: 'leading-[1.1112] md:leading-none' },
+      xl: { value: '[--stat-max:3rem] [--stat-max-md:3.75rem] leading-none' },
+      display: { value: '[--stat-max:3.75rem] [--stat-max-md:4.5rem] leading-none' },
     },
     // accent/accent-ink is only ~5:1 — dimming text on it drops it under 4.5:1 (WCAG 1.4.3).
     tone: { default: {}, muted: {}, inverse: {}, accent: { label: 'opacity-100' } },
@@ -29,7 +61,7 @@ const stats = tv({
     // Elementor counter names itself first). The figure is drawn on top either way.
     order: { 'label-first': { item: 'flex-col-reverse' }, 'value-first': { item: 'flex-col' } },
   },
-  defaultVariants: { columns: '3', style: 'plain', tone: 'default', labelSize: 'sm', order: 'label-first' },
+  defaultVariants: { layout: 'grid', columns: '3', style: 'plain', align: 'start', valueSize: 'lg', tone: 'default', labelSize: 'sm', order: 'label-first' },
 })
 
 interface Item {
@@ -37,26 +69,37 @@ interface Item {
   label: string
   prefix?: string | undefined
   suffix?: string | undefined
+  /** A small picture above the figure (its address); decorative, so it carries no text. */
+  icon?: ImageSource | undefined
 }
 
 interface Props {
   heading?: string | undefined
   intro?: string | undefined
   items: Item[]
-  columns?: '2' | '3' | '4' | undefined
-  style?: 'plain' | 'card' | undefined
+  layout?: 'grid' | 'inline' | undefined
+  columns?: '2' | '3' | '4' | '5' | '6' | undefined
+  style?: 'plain' | 'card' | 'divided' | undefined
+  align?: 'start' | 'center' | undefined
+  valueSize?: 'md' | 'lg' | 'xl' | 'display' | undefined
   labelSize?: 'sm' | 'base' | 'lg' | undefined
   order?: 'label-first' | 'value-first' | undefined
   tone?: Tone | undefined
+  /** The source section's measured style (`MeasuredStyle`): frame, padding, fill, background image, columns per width, gap. Absent, the site's tokens; present, it wins over tone and columns. */
+  measured?: MeasuredStyle | undefined
   id?: string | undefined
 }
 
-const { heading, intro, items, columns, style, labelSize, order, tone, id } = Astro.props
-const s = stats({ columns, style, labelSize, order, tone })
+const { heading, intro, items, layout, columns, style, align, valueSize, labelSize, order, tone, measured, id } = Astro.props
+const s = stats({ layout, columns, style, align, valueSize, labelSize, order, tone })
+const grid = (layout ?? 'grid') === 'grid' ? measuredGrid(measured) : undefined
 const headingId = heading && id ? `${id}-title` : undefined
+const iconOf = (item: Item) => imageOf(item.icon, '')
+// The figure's width in characters, for the size it may take in a narrow cell.
+const widthOf = (item: Item) => `--stat-chars:${(item.prefix ?? '').length + item.value.length + (item.suffix ?? '').length}`
 // A <dl> names its term first, so figure-first is a plain list, read in the order it is drawn (WCAG 1.3.2).
 ---
-<Section tone={tone} id={id} aria-labelledby={headingId}>
+<Section measured={measured} tone={tone} id={id} aria-labelledby={headingId}>
   {(heading || intro) && (
     <header class="mb-10 flex max-w-2xl flex-col gap-3">
       {heading && <h2 id={headingId} class="text-3xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-4xl">{heading}</h2>}
@@ -64,20 +107,20 @@ const headingId = heading && id ? `${id}-title` : undefined
     </header>
   )}
   {order === 'value-first' ? (
-    <ul class={s.list()} role="list">
+    <ul class={s.list({ class: grid })} role="list">
       {items.map(item => (
         <li class={s.item()}>
-          <p class={s.value()}>{item.prefix}{item.value}{item.suffix}</p>
+          <p class={s.value()} style={widthOf(item)}>{iconOf(item) && <KitImage image={iconOf(item)!} sizes="40px" class={s.icon()} />}{item.prefix}{item.value}{item.suffix}</p>
           <p class={s.label()}>{item.label}</p>
         </li>
       ))}
     </ul>
   ) : (
-    <dl class={s.list()}>
+    <dl class={s.list({ class: grid })}>
       {items.map(item => (
         <div class={s.item()}>
           <dt class={s.label()}>{item.label}</dt>
-          <dd class={s.value()}>{item.prefix}{item.value}{item.suffix}</dd>
+          <dd class={s.value()} style={widthOf(item)}>{iconOf(item) && <KitImage image={iconOf(item)!} sizes="40px" class={s.icon()} />}{item.prefix}{item.value}{item.suffix}</dd>
         </div>
       ))}
     </dl>