@contentrain/astro-kit 0.29.4 → 0.31.0

package/components/band/meta.json

@@ -0,0 +1,323 @@
+{
+  "id": "band",
+  "name": "Band",
+  "description": "The styled fallback section: an optional heading, lead, image, a grid of items and buttons, in the section's measured frame and fill. Used where no closer component fits (an unrecognised or low-confidence section), so it still reads as a designed section, never bare text.",
+  "category": "section",
+  "uses": [],
+  "shared": [
+    "Button.astro",
+    "KitImage.astro",
+    "Section.astro",
+    "measured.ts",
+    "types.ts"
+  ],
+  "variants": {
+    "layout": {
+      "options": [
+        "stack",
+        "split"
+      ],
+      "default": "stack",
+      "description": "stack: one column. split: the copy beside the image on wide screens (only with an image)."
+    },
+    "columns": {
+      "options": [
+        "1",
+        "2",
+        "3",
+        "4"
+      ],
+      "default": "3",
+      "description": "Item columns on wide screens when nothing is measured; one on phones, two on tablets."
+    },
+    "align": {
+      "options": [
+        "start",
+        "center"
+      ],
+      "default": "start",
+      "description": "Alignment of the copy and the items."
+    },
+    "tone": {
+      "options": [
+        "default",
+        "muted",
+        "inverse",
+        "accent"
+      ],
+      "default": "default",
+      "description": "Section background when nothing is measured."
+    }
+  },
+  "props": {
+    "heading": {
+      "type": "string",
+      "label": "Heading",
+      "description": "Section heading."
+    },
+    "eyebrow": {
+      "type": "string",
+      "label": "Eyebrow",
+      "description": "Short line above the heading."
+    },
+    "lead": {
+      "type": "text",
+      "label": "Lead",
+      "description": "Paragraph under the heading."
+    },
+    "media": {
+      "type": "object",
+      "label": "Image",
+      "fields": {
+        "src": {
+          "type": "image",
+          "label": "Image",
+          "required": true,
+          "description": "The image file."
+        },
+        "alt": {
+          "type": "string",
+          "label": "Image description",
+          "description": "What the image shows, for readers who cannot see it; empty when it is decoration."
+        },
+        "width": {
+          "type": "integer",
+          "label": "Width",
+          "description": "Width in pixels, as uploaded."
+        },
+        "height": {
+          "type": "integer",
+          "label": "Height",
+          "description": "Height in pixels, as uploaded."
+        }
+      },
+      "description": "The section's image, under or beside the copy."
+    },
+    "items": {
+      "type": "array",
+      "label": "Items",
+      "items": {
+        "type": "object",
+        "fields": {
+          "value": {
+            "type": "string",
+            "label": "Figure",
+            "description": "A figure drawn large above the title (a stat with its prefix or suffix, a price)."
+          },
+          "title": {
+            "type": "string",
+            "label": "Title",
+            "description": "The item heading."
+          },
+          "meta": {
+            "type": "string",
+            "label": "Detail",
+            "description": "A short line under the title (a role, a date, a period)."
+          },
+          "text": {
+            "type": "text",
+            "label": "Text",
+            "description": "A sentence or two under the title."
+          },
+          "href": {
+            "type": "url",
+            "label": "Link",
+            "description": "Where the item goes; without a link text the whole item is the link."
+          },
+          "linkLabel": {
+            "type": "string",
+            "label": "Link text",
+            "description": "The link's own text, shown under the item."
+          },
+          "media": {
+            "type": "image",
+            "label": "Image",
+            "description": "Image on top of the item."
+          },
+          "mediaAlt": {
+            "type": "string",
+            "label": "Image description",
+            "description": "What the image shows, for readers who cannot see it; empty when it is decoration."
+          },
+          "icon": {
+            "type": "image",
+            "label": "Icon",
+            "description": "A small image above the title (decoration)."
+          },
+          "points": {
+            "type": "array",
+            "label": "Points",
+            "items": "string",
+            "description": "A short list under the text (features, facts)."
+          }
+        }
+      },
+      "description": "Items in a grid (cards, features, logos), in order."
+    },
+    "actions": {
+      "type": "array",
+      "label": "Buttons",
+      "items": {
+        "type": "object",
+        "fields": {
+          "label": {
+            "type": "string",
+            "label": "Label",
+            "required": true,
+            "description": "The button text."
+          },
+          "href": {
+            "type": "url",
+            "label": "Link",
+            "required": true,
+            "description": "Where the button goes: a page on this site or a full address."
+          },
+          "newTab": {
+            "type": "boolean",
+            "label": "Open in a new tab",
+            "description": "Open the link in a new tab (an external site the reader should not leave for)."
+          },
+          "style": {
+            "type": "select",
+            "label": "Style",
+            "options": [
+              "primary",
+              "secondary",
+              "ghost"
+            ],
+            "description": "primary for the main action, secondary or ghost for the ones beside it."
+          }
+        }
+      },
+      "description": "Buttons, in order."
+    },
+    "headingLevel": {
+      "type": "integer",
+      "min": 2,
+      "max": 3,
+      "default": 2,
+      "content": false,
+      "description": "Level of the section heading; item titles are one below, or at this level when there is no heading."
+    },
+    "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`."
+    }
+  },
+  "slots": {},
+  "js": "none",
+  "dependencies": {},
+  "sources": {},
+  "a11y": "A labelled region (aria-labelledby its heading) when it has one. Item titles sit one level under the heading. An item with a link and no link text is clickable as a whole through its title's link; icons are decoration (alt=\"\")."
+}

package/components/card-grid/CardGrid.astro

@@ -4,6 +4,8 @@
 import { tv } from 'tailwind-variants'
 import KitImage from '../_shared/KitImage.astro'
 import Section, { type Tone } from '../_shared/Section.astro'
+import { measuredGrid } from '../_shared/measured'
+import type { MeasuredStyle } from '../_shared/types'
 import { imageOf, type ImageSource } from '../_shared/image'
 
 const grid = tv({
@@ -50,9 +52,11 @@ interface Props {
   style?: 'plain' | 'bordered' | 'elevated' | undefined
   align?: 'start' | 'center' | 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
 }
 
-const { title, intro, items, headingLevel = 2, columns, style, align, tone } = Astro.props
+const { title, intro, items, headingLevel = 2, columns, style, align, tone, measured } = Astro.props
 const { list, card, media, title: cardTitle, text } = grid({ columns, style, align })
 // Accent backgrounds have the least contrast headroom: text on them is never dimmed.
 const dim = tone === 'accent' ? 'opacity-100' : undefined
@@ -61,14 +65,14 @@ const Heading = `h${headingLevel}` as 'h2' | 'h3'
 const CardHeading = `h${title ? headingLevel + 1 : headingLevel}` as 'h2' | 'h3' | 'h4'
 const headingId = title ? `cards-${title.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : undefined
 ---
-<Section tone={tone} aria-labelledby={headingId}>
+<Section measured={measured} tone={tone} aria-labelledby={headingId}>
   {(title || intro) && (
     <header class:list={['mb-10 flex max-w-2xl flex-col gap-3', align === 'center' && 'mx-auto items-center text-center']}>
       {title && <Heading id={headingId} class="text-3xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-4xl">{title}</Heading>}
       {intro && <p class:list={['text-lg', tone === 'accent' ? undefined : 'opacity-80']}>{intro}</p>}
     </header>
   )}
-  <ul class={list()}>
+  <ul class={list({ class: measuredGrid(measured) })}>
     {items.map(item => (
       <li class={card()}>
         {imageOf(item.image, item.imageAlt) && <div class={media()}><KitImage image={imageOf(item.image, item.imageAlt)!} sizes="(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 100vw" class="aspect-[3/2] w-full object-cover transition duration-300 group-hover:scale-[1.02]" /></div>}

package/components/card-grid/fixtures.json

@@ -2,5 +2,6 @@
   { "name": "three-plain", "props": { "title": "What we do", "intro": "Three things, done carefully.", "items": [{ "title": "Design systems", "text": "Tokens, components and documentation your team keeps using.", "href": "/services/design/", "image": { "src": "/kit-fixtures/photo-1.svg", "alt": "", "width": 1200, "height": 800 } }, { "title": "Migrations", "text": "WordPress to Astro without losing an address or a ranking.", "href": "/services/migrations/", "image": { "src": "/kit-fixtures/photo-2.svg", "alt": "", "width": 1200, "height": 800 } }, { "title": "Performance", "text": "Measured, budgeted and kept fast after launch.", "href": "/services/performance/", "image": { "src": "/kit-fixtures/photo-3.svg", "alt": "", "width": 1200, "height": 800 } }] } },
   { "name": "two-bordered-center", "props": { "columns": "2", "style": "bordered", "align": "center", "tone": "muted", "title": "Plans", "items": [{ "eyebrow": "Starter", "title": "One site", "text": "Everything you need for a single site." }, { "eyebrow": "Team", "title": "Many sites", "text": "Shared components across a portfolio." }] } },
   { "name": "four-elevated-inverse", "props": { "columns": "4", "style": "elevated", "tone": "inverse", "headingLevel": 3, "title": "Team", "items": [{ "title": "Mira Kovač", "text": "Editor", "image": { "src": "/kit-fixtures/avatar-1.svg", "alt": "Mira Kovač", "width": 96, "height": 96 } }, { "title": "Jon Ade", "text": "Engineer", "image": { "src": "/kit-fixtures/avatar-2.svg", "alt": "Jon Ade", "width": 96, "height": 96 } }, { "title": "Lea Park", "text": "Designer", "image": { "src": "/kit-fixtures/avatar-3.svg", "alt": "Lea Park", "width": 96, "height": 96 } }, { "title": "Sam Ortiz", "text": "Producer" }] } },
-  { "name": "accent", "props": { "tone": "accent", "columns": "3", "items": [{ "title": "Fast", "text": "Static HTML, one stylesheet." }, { "title": "Editable", "text": "Content in Contentrain Studio." }, { "title": "Kept", "text": "Every address survives." }] } }
+  { "name": "accent", "props": { "tone": "accent", "columns": "3", "items": [{ "title": "Fast", "text": "Static HTML, one stylesheet." }, { "title": "Editable", "text": "Content in Contentrain Studio." }, { "title": "Kept", "text": "Every address survives." }] } },
+  {"name": "measured-columns", "props": {"title": "Services", "measured": {"containerPx": 1140, "padY": 80, "columns": {"390": 1, "768": 2, "1280": 4}, "gap": 30, "radius": 4, "bg": {"color": "#f4f1ea"}}, "items": [{"title": "Audits", "text": "Where a site loses readers."}, {"title": "Builds", "text": "Static and fast."}, {"title": "Hosting", "text": "Managed for you."}, {"title": "Care", "text": "Kept up to date."}]}}
 ]

package/components/card-grid/meta.json

@@ -8,6 +8,7 @@
     "KitImage.astro",
     "Section.astro",
     "image.ts",
+    "measured.ts",
     "types.ts"
   ],
   "variants": {
@@ -108,6 +109,116 @@
       "default": 2,
       "content": false,
       "description": "Level of the section heading; card titles are one below, or at this level when there is no title."
+    },
+    "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."
+        }
+      }
     }
   },
   "slots": {},

package/components/contact-details/ContactDetails.astro

@@ -5,6 +5,8 @@
 // widgets that list the same things by hand.
 import { tv } from 'tailwind-variants'
 import Section from '../_shared/Section.astro'
+import { measuredGrid } from '../_shared/measured'
+import type { MeasuredStyle } from '../_shared/types'
 
 const details = tv({
   slots: {
@@ -40,12 +42,15 @@ interface Props {
   mapLabel?: string | undefined
   layout?: 'list' | 'columns' | undefined
   id?: string | 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
 }
 
 const {
   heading, email, phone, address, hours, mapUrl,
   emailLabel = 'Email', phoneLabel = 'Phone', addressLabel = 'Address', hoursLabel = 'Opening hours', mapLabel = 'View on the map',
   layout, id = 'contact-details',
+  measured,
 } = Astro.props
 const s = details({ layout })
 const headingId = heading ? `${id}-title` : undefined
@@ -54,9 +59,9 @@ const tel = phone ? `tel:${phone.replace(/[^\d+]/g, '')}` : undefined
 const shown = Boolean(email || phone || address || hours || mapUrl)
 ---
 {shown && (
-  <Section spacing="md" id={id} aria-labelledby={headingId}>
+  <Section measured={measured} spacing="md" id={id} aria-labelledby={headingId}>
     {heading && <h2 id={headingId} class={s.heading()}>{heading}</h2>}
-    <dl class={s.list()}>
+    <dl class={s.list({ class: measuredGrid(measured) })}>
       {email && <div><dt class={s.term()}>{emailLabel}</dt><dd class={s.value()}><a href={`mailto:${email}`} class={s.link()}>{email}</a></dd></div>}
       {phone && <div><dt class={s.term()}>{phoneLabel}</dt><dd class={s.value()}><a href={tel} class={s.link()}>{phone}</a></dd></div>}
       {(address || mapUrl) && (

package/components/contact-details/meta.json

@@ -5,7 +5,9 @@
   "category": "section",
   "uses": [],
   "shared": [
-    "Section.astro"
+    "Section.astro",
+    "measured.ts",
+    "types.ts"
   ],
   "variants": {
     "layout": {
@@ -82,6 +84,116 @@
       "type": "string",
       "content": false,
       "description": "Section id; the heading gets `<id>-title`."
+    },
+    "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."
+        }
+      }
     }
   },
   "slots": {},

package/components/contact-form/meta.json

@@ -4,7 +4,7 @@
   "description": "The contact section: heading, introduction, contact details (email, phone, address) and a Contentrain Studio form — fields, spam protection and notifications set in Studio, submissions reviewed there. Replaces form plugins; renders the details alone until the site is bound to a Studio project (a section left with only its heading is not drawn: the heading would title a form that is not there). When the owner chose another home at migration (site.config.ts `features.forms`) the form posts to their form service, or the section shows an address to write to or a link to the form on WordPress.",
   "category": "section",
   "uses": [],
-  "shared": ["Section.astro"],
+  "shared": ["Section.astro", "measured.ts", "types.ts"],
   "variants": {
     "layout": { "options": ["split", "stacked"], "default": "split", "description": "split: details beside the form on wide screens. stacked: one column (see align)." },
     "align": { "options": ["center", "start"], "default": "center", "description": "Stacked only, and the details alone before a Studio form. center: one centred column at a reading width. start: the section's whole column from the start edge, as a page builder's container whose text sets no alignment." },