@contentrain/astro-kit 0.31.0 → 0.32.0

package/components/stats/Stats.astro

@@ -2,24 +2,47 @@
 // 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',
+    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: {
+      grid: {},
+      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: 'text-3xl md:text-4xl' },
+      lg: {},
+      xl: { value: 'text-5xl md:text-6xl' },
+      display: { value: 'text-6xl md:text-7xl' },
     },
     // 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 +52,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 +60,35 @@ 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, '')
 // 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 +96,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()}>{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()}>{iconOf(item) && <KitImage image={iconOf(item)!} sizes="40px" class={s.icon()} />}{item.prefix}{item.value}{item.suffix}</dd>
         </div>
       ))}
     </dl>

package/components/stats/fixtures.json

@@ -156,5 +156,178 @@
         }
       ]
     }
+  },
+  {
+    "name": "divided-center-md",
+    "props": {
+      "items": [
+        {
+          "value": "12",
+          "label": "Years in business",
+          "suffix": "+"
+        },
+        {
+          "value": "480",
+          "label": "Clients served"
+        },
+        {
+          "value": "99.9",
+          "label": "Uptime",
+          "suffix": "%"
+        }
+      ],
+      "style": "divided",
+      "align": "center",
+      "valueSize": "md"
+    }
+  },
+  {
+    "name": "inline-xl",
+    "props": {
+      "items": [
+        {
+          "value": "12",
+          "label": "Years in business",
+          "suffix": "+"
+        },
+        {
+          "value": "480",
+          "label": "Clients served"
+        },
+        {
+          "value": "99.9",
+          "label": "Uptime",
+          "suffix": "%"
+        }
+      ],
+      "layout": "inline",
+      "valueSize": "xl",
+      "heading": "In numbers"
+    }
+  },
+  {
+    "name": "display-icons",
+    "props": {
+      "items": [
+        {
+          "value": "12",
+          "label": "Years in business",
+          "suffix": "+",
+          "icon": "/kit-fixtures/logo.svg"
+        },
+        {
+          "value": "480",
+          "label": "Clients served",
+          "icon": "/kit-fixtures/logo.svg"
+        },
+        {
+          "value": "99.9",
+          "label": "Uptime",
+          "suffix": "%",
+          "icon": "/kit-fixtures/logo.svg"
+        }
+      ],
+      "valueSize": "display"
+    }
+  },
+  {
+    "name": "five-columns",
+    "props": {
+      "items": [
+        {
+          "value": "12",
+          "label": "Years in business",
+          "suffix": "+"
+        },
+        {
+          "value": "480",
+          "label": "Clients served"
+        },
+        {
+          "value": "99.9",
+          "label": "Uptime",
+          "suffix": "%"
+        },
+        {
+          "value": "7",
+          "label": "Offices"
+        },
+        {
+          "value": "24/7",
+          "label": "Support"
+        }
+      ],
+      "columns": "5"
+    }
+  },
+  {
+    "name": "six-columns",
+    "props": {
+      "items": [
+        {
+          "value": "12",
+          "label": "Years in business",
+          "suffix": "+"
+        },
+        {
+          "value": "480",
+          "label": "Clients served"
+        },
+        {
+          "value": "99.9",
+          "label": "Uptime",
+          "suffix": "%"
+        },
+        {
+          "value": "7",
+          "label": "Offices"
+        },
+        {
+          "value": "24/7",
+          "label": "Support"
+        },
+        {
+          "value": "3",
+          "label": "Awards"
+        }
+      ],
+      "columns": "6"
+    }
+  },
+  {
+    "name": "measured-columns",
+    "props": {
+      "heading": "By the numbers",
+      "intro": "A decade of shipping sites for small teams.",
+      "items": [
+        {
+          "value": "12",
+          "label": "Years in business",
+          "suffix": "+"
+        },
+        {
+          "value": "480",
+          "label": "Clients served"
+        },
+        {
+          "value": "99.9",
+          "label": "Uptime",
+          "suffix": "%"
+        }
+      ],
+      "measured": {
+        "columns": {
+          "390": 1,
+          "768": 2,
+          "1280": 4
+        },
+        "gap": 40,
+        "padY": 96,
+        "bg": {
+          "color": "#0f172a"
+        },
+        "tone": "dark"
+      }
+    }
   }
 ]

package/components/stats/meta.json

@@ -5,27 +5,58 @@
   "category": "section",
   "uses": [],
   "shared": [
+    "KitImage.astro",
     "Section.astro",
+    "image.ts",
     "measured.ts",
     "types.ts"
   ],
   "variants": {
+    "layout": {
+      "options": [
+        "grid",
+        "inline"
+      ],
+      "default": "grid",
+      "description": "grid: figures in columns. inline: one line that wraps, for two to four short figures."
+    },
     "columns": {
       "options": [
         "2",
         "3",
-        "4"
+        "4",
+        "5",
+        "6"
       ],
       "default": "3",
-      "description": "Figures per row on wide screens; two on phones."
+      "description": "Figures per row on wide screens (grid layout); two on phones."
     },
     "style": {
       "options": [
         "plain",
-        "card"
+        "card",
+        "divided"
       ],
       "default": "plain",
-      "description": "plain: figures on the section background. card: each figure in its own box."
+      "description": "plain: figures on the section background. card: each figure in its own box. divided: hairlines between the figures (across on a wide screen, above each on a phone), no box; for a single row."
+    },
+    "align": {
+      "options": [
+        "start",
+        "center"
+      ],
+      "default": "start",
+      "description": "Alignment of each figure and its label."
+    },
+    "valueSize": {
+      "options": [
+        "md",
+        "lg",
+        "xl",
+        "display"
+      ],
+      "default": "lg",
+      "description": "The figure's size: md, lg, xl or a display-size number."
     },
     "tone": {
       "options": [
@@ -94,11 +125,126 @@
             "type": "string",
             "label": "Suffix",
             "description": "Printed after the figure (`+`, `%`, `k`)."
+          },
+          "icon": {
+            "type": "image",
+            "label": "Icon",
+            "description": "A small picture above the figure; decorative."
           }
         }
       },
       "description": "The figures, in order (Elementor counter, Divi number counter, a Gutenberg columns row of big numbers)."
     },
+    "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,

package/components/steps/Steps.astro

@@ -1,10 +1,13 @@
 ---
 // How it works: an ordered sequence of steps, each a title and a line of
 // text, optionally with an image — as a vertical list or a row across the
-// page, numbered or plain.
+// page, numbered or plain. `kind="timeline"` is the dated variant: a date per
+// item on a vertical rail, optionally alternating left and right of it.
 import { tv } from 'tailwind-variants'
 import KitImage from '../_shared/KitImage.astro'
 import Section from '../_shared/Section.astro'
+import { measuredGrid } from '../_shared/measured'
+import type { MeasuredStyle } from '../_shared/types'
 import { imageOf, type ImageSource } from '../_shared/image'
 
 const steps = tv({
@@ -14,6 +17,7 @@ const steps = tv({
     intro: 'text-lg opacity-80',
     list: 'grid gap-8 [counter-reset:kit-step]',
     step: 'flex gap-4 [counter-increment:kit-step]',
+    date: 'text-sm font-semibold tabular-nums text-accent-text',
     body: 'flex flex-col gap-2',
     badge: 'shrink-0',
     media: 'mb-2 overflow-hidden rounded-[var(--radius-image,var(--radius-card))]',
@@ -24,7 +28,14 @@ const steps = tv({
     layout: {
       list: { list: 'max-w-3xl' },
       row: { list: 'sm:grid-cols-2 lg:auto-cols-fr lg:grid-flow-col lg:grid-cols-none', step: 'flex-col' },
+      // One rail on the inline-start side (the item's own side is the rail's, mirrored in RTL by the logical `ps-`/`border-s`).
+      rail: { list: 'max-w-3xl gap-0', step: 'relative border-s-2 border-line pb-8 ps-6 last:pb-0' },
+      // Items alternate either side of a centre rail from `md`; the DOM stays chronological, one rail on the start side on phones.
+      alternate: { list: 'gap-0 md:grid-cols-2', step: 'relative border-s-2 border-line pb-8 ps-6 md:[&:nth-child(even)]:col-start-2 md:[&:nth-child(odd)]:col-start-1 md:[&:nth-child(odd)]:border-s-0 md:[&:nth-child(odd)]:border-e-2 md:[&:nth-child(odd)]:pe-6 md:[&:nth-child(odd)]:ps-0 md:[&:nth-child(odd)]:text-end md:[&:nth-child(odd)]:flex-row-reverse md:[&:nth-child(even)]:-ms-px md:[&:nth-child(odd)]:after:start-auto md:[&:nth-child(odd)]:after:-end-[7px]' },
     },
+    // What sits on the rail: the number, a plain dot, or the date (the timeline's own marker). The number marker is `style`'s.
+    marker: { number: {}, dot: { step: 'before:hidden after:absolute after:top-1.5 after:-start-[7px] after:size-3 after:rounded-full after:bg-accent after:content-[""]' } },
+    connector: { none: {}, line: {}, dashed: { step: 'border-dashed' } },
     // The number is drawn from a CSS counter, so the list stays one <ol> a screen reader counts itself. A number the
     // source wrote (`01`) is the page's text and is shown as written, hidden from the screen reader that already counts.
     style: {
@@ -35,7 +46,7 @@ const steps = tv({
       plain: { step: 'border-s-2 border-accent ps-4', badge: 'font-semibold tabular-nums' },
     },
   },
-  defaultVariants: { layout: 'list', style: 'numbered' },
+  defaultVariants: { layout: 'list', marker: 'number', connector: 'line', style: 'numbered' },
 })
 
 interface Step {
@@ -43,6 +54,10 @@ interface Step {
   number?: string | undefined
   title: string
   text: string
+  /** A timeline's date as the source writes it (`2019`, `Mar 2021`); `datetime` only when it parses as an ISO date or year. */
+  date?: string | undefined
+  /** Marks the latest item: a visually hidden "Current" is added for readers. */
+  current?: boolean | undefined
   /** The image's address. */
   image?: ImageSource | undefined
   imageAlt?: string | undefined
@@ -52,30 +67,43 @@ interface Props {
   heading?: string | undefined
   intro?: string | undefined
   items: Step[]
-  layout?: 'list' | 'row' | undefined
+  /** `steps` numbers a sequence; `timeline` carries a date per item (the rail layouts below). */
+  kind?: 'steps' | 'timeline' | undefined
+  layout?: 'list' | 'row' | 'rail' | 'alternate' | undefined
+  marker?: 'number' | 'dot' | undefined
+  connector?: 'none' | 'line' | 'dashed' | undefined
+  currentLabel?: string | undefined
   style?: 'numbered' | 'plain' | 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, layout, style, id } = Astro.props
-const s = steps({ layout, style })
+const { heading, intro, items, kind = 'steps', layout: givenLayout, marker, connector, currentLabel = 'Current', style, measured, id } = Astro.props
+// A timeline defaults to the rail layout and, without numbers, to the plain dot marker.
+const layout = givenLayout ?? (kind === 'timeline' ? 'rail' : 'list')
+const s = steps({ layout, marker: marker ?? (kind === 'timeline' ? 'dot' : 'number'), connector, style })
+// A bare year or an ISO date is machine-readable; anything else ("Spring 2021") stays text.
+const isoDate = (date: string) => /^\d{4}(-\d{2}(-\d{2})?)?$/.test(date.trim()) ? date.trim() : undefined
 const headingId = heading && id ? `${id}-title` : undefined
 // One level under the section heading, or the section's heading when there is none.
 const StepHeading = heading ? 'h3' : 'h2'
 ---
 {items.length > 0 && (
-  <Section id={id} aria-labelledby={headingId}>
+  <Section measured={measured} id={id} aria-labelledby={headingId}>
     {(heading || intro) && (
       <header class={s.header()}>
         {heading && <h2 id={headingId} class={s.heading()}>{heading}</h2>}
         {intro && <p class={s.intro()} data-kit-text>{intro}</p>}
       </header>
     )}
-    <ol class={s.list()}>
+    <ol class={s.list({ class: layout === 'row' ? measuredGrid(measured) : undefined })}>
       {items.map(step => (
-        <li class={s.step({ class: step.number ? 'before:hidden' : undefined })}>
+        <li class={s.step({ class: step.number || kind === 'timeline' ? 'before:hidden' : undefined })} aria-current={step.current ? 'step' : undefined}>
           {step.number && <span class={s.badge()} aria-hidden="true">{step.number}</span>}
           <div class={s.body()}>
+            {kind === 'timeline' && step.date && (isoDate(step.date) ? <time class={s.date()} datetime={isoDate(step.date)}>{step.date}</time> : <p class={s.date()}>{step.date}</p>)}
+            {step.current && <span class="sr-only">{currentLabel}</span>}
             {imageOf(step.image, step.imageAlt) && <div class={s.media()}><KitImage image={imageOf(step.image, step.imageAlt)!} sizes="(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw" class="aspect-[3/2] w-full object-cover" /></div>}
             <StepHeading class={s.title()}>{step.title}</StepHeading>
             <p class={s.text()} data-kit-text>{step.text}</p>