@contentrain/astro-kit 0.21.1 → 0.23.0

package/catalog.json

@@ -507,7 +507,7 @@
     {
       "id": "contact-form",
       "name": "Contact form",
-      "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. 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.",
+      "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": [
@@ -612,9 +612,10 @@
           "classic/ninja-forms"
         ]
       },
-      "a11y": "Contact details are a description list when every one has a label, a plain list otherwise; links say what they open. The form's labels, errors and focus handling are Studio's form runtime (FormMount). The section is labelled by its heading.",
+      "a11y": "Contact details are a description list when every one has a label, a plain list otherwise; links say what they open. The form's labels, errors and focus handling are Studio's form runtime (FormMount). The section is labelled by its heading. Without a form to show and with no introduction or details, the section is not drawn at all.",
       "files": [
-        "ContactForm.astro"
+        "ContactForm.astro",
+        "contact-form.ts"
       ],
       "contentFields": {
         "heading": "heading",
@@ -1490,6 +1491,31 @@
           "type": "string",
           "description": "The site name's size where the source theme sets its own (a CSS length)."
         },
+        "bordered": {
+          "type": "boolean",
+          "default": true,
+          "description": "The line under the bar on the default tone; false where the source's header draws none."
+        },
+        "brandWeight": {
+          "type": "string",
+          "description": "The site name's weight where the source theme sets its own (a CSS font-weight)."
+        },
+        "brandTracking": {
+          "type": "string",
+          "description": "The site name's letter-spacing where the source theme sets its own (a CSS length, or normal)."
+        },
+        "offsetTop": {
+          "type": "string",
+          "description": "Space above the bar where the source's header has its own (a CSS length)."
+        },
+        "padTop": {
+          "type": "string",
+          "description": "Space inside the bar above its content where the source's header has its own (a CSS length)."
+        },
+        "padBottom": {
+          "type": "string",
+          "description": "Space inside the bar below its content where the source's header has its own (a CSS length)."
+        },
         "linkNav": {
           "type": "boolean",
           "default": false,
@@ -1672,6 +1698,14 @@
           ],
           "default": "full",
           "description": "Layout cover only. full: the image runs the full window width. content: the cover sits in the reading column, as a WordPress cover block that is not alignfull does under the page title."
+        },
+        "headingScale": {
+          "options": [
+            "default",
+            "theme"
+          ],
+          "default": "default",
+          "description": "default: the layout's own type scale. theme: the heading takes the site's size for its level (`--text-heading-1` for the page-opening hero, `-2` otherwise), as the source's own h1 does under a block theme."
         }
       },
       "props": {
@@ -1770,6 +1804,13 @@
           "type": "string",
           "content": false,
           "description": "Anchor id of the section; the heading gets `<id>-title`."
+        },
+        "minHeight": {
+          "type": "integer",
+          "content": false,
+          "min": 100,
+          "max": 2000,
+          "description": "Layout cover only: the cover's own height in pixels, as the source sets it (520); absent, the layout's default."
         }
       },
       "slots": {},
@@ -1790,7 +1831,8 @@
       },
       "a11y": "A labelled region (aria-labelledby the heading). One h1 by default; `level: 2` inside pages that already have one. The cover image is decorative when its alt is empty; text sits on an ink scrim for contrast.",
       "files": [
-        "Hero.astro"
+        "Hero.astro",
+        "hero.ts"
       ],
       "contentFields": {
         "heading": "heading",

package/components/contact-form/ContactForm.astro

@@ -4,7 +4,8 @@
 // StudioForm): its fields, spam protection and notifications live in Studio,
 // and submissions arrive there for review — no form plugin, no mail server.
 // Until the site is bound to a Studio project the form renders nothing and the
-// contact details still show. When the owner chose another home for forms at
+// contact details still show — and a section left with its heading alone is not
+// drawn (a heading over a form that is not there). When the owner chose another home for forms at
 // migration (site.config.ts `features.forms`), the same place holds a form
 // that posts to their form service, an address to write to, or a link to the
 // form on WordPress.
@@ -12,6 +13,7 @@ import { tv } from 'tailwind-variants'
 import Section from '../_shared/Section.astro'
 import StudioForm from '../../studio/StudioForm.astro'
 import { formHome } from '../../../lib/features'
+import { contactSectionBare } from './contact-form'
 
 export interface ContactDetail {
   /** What the detail is (Phone, Email); a source's icon list often has none. */
@@ -69,6 +71,7 @@ interface Props {
 const { model, heading, intro, formHeading, details = [], layout, align, tone, id = 'contact' } = Astro.props
 // Nothing to render (Studio not bound yet): a split would leave an empty column — the details stand alone.
 const formShown = formHome(model) !== null
+const bare = contactSectionBare({ formShown, intro, details })
 const s = contact({ layout: formShown ? layout : 'stacked', align, tone })
 const headingId = heading ? `${id}-title` : undefined
 // A description list needs a term for every detail; an icon list carried from the source has values only.
@@ -77,6 +80,7 @@ const LINK = 'underline decoration-line underline-offset-4 hover:decoration-curr
 // One level under the section heading, or the section's heading when there is none.
 const FormHeading = heading ? 'h3' : 'h2'
 ---
+{!bare && (
 <Section tone={tone} spacing="md" id={id} aria-labelledby={headingId}>
   <div class={s.grid()}>
     {(heading || intro || details.length > 0) && (
@@ -116,3 +120,4 @@ const FormHeading = heading ? 'h3' : 'h2'
       : <StudioForm model={model} class={s.form()} />)}
   </div>
 </Section>
+)}

package/components/contact-form/contact-form.ts

@@ -0,0 +1,8 @@
+// When the contact section has nothing to show. Its form is drawn only where a home for it exists (Studio bound, the
+// WordPress page known, a service address that is https); until then the section stands on its heading, introduction
+// and details. A section left with a heading ALONE titles a form that is not there — the page would print "Tell us about
+// your project" over empty space — so it is not drawn at all, and appears with its form once the form has a home.
+
+export function contactSectionBare(input: { formShown: boolean, intro?: string | undefined, details?: readonly unknown[] | undefined }): boolean {
+  return !input.formShown && !input.intro && !(input.details?.length ?? 0)
+}

package/components/contact-form/fixtures.json

@@ -12,9 +12,9 @@
       ]
     }
   },
-  { "name": "stacked-muted", "props": { "model": "contact-submissions", "heading": "Write to us", "layout": "stacked", "tone": "muted", "id": "write" } },
+  { "name": "stacked-muted", "props": { "model": "contact-submissions", "heading": "Write to us", "intro": "We read every message and answer within two working days.", "layout": "stacked", "tone": "muted", "id": "write" } },
   { "name": "stacked-start", "props": { "model": "contact-submissions", "intro": "Tell us what you make and when you want to launch.", "details": [{ "value": "Studio 4, Harbour Lane" }], "layout": "stacked", "align": "start", "id": "start" } },
   { "name": "split-inverse", "props": { "model": "contact-submissions", "heading": "Press", "tone": "inverse", "id": "press", "details": [{ "label": "Press office", "value": "press@northwind.example", "href": "mailto:press@northwind.example" }] } },
-  { "name": "stacked-accent", "props": { "model": "newsletter-requests", "heading": "Request a print copy", "layout": "stacked", "tone": "accent", "id": "print" } },
+  { "name": "stacked-accent", "props": { "model": "newsletter-requests", "heading": "Request a print copy", "intro": "Print copies ship in the first week of each quarter.", "layout": "stacked", "tone": "accent", "id": "print" } },
   { "name": "form-heading", "props": { "model": "contact-submissions", "heading": "Contact", "intro": "Tell us where you are and what you need.", "formHeading": "Tell us about your project", "details": [{ "label": "Address", "value": "12 Harbour Street, Leith" }] } }
 ]

package/components/contact-form/meta.json

@@ -1,7 +1,7 @@
 {
   "id": "contact-form",
   "name": "Contact form",
-  "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. 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.",
+  "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"],
@@ -26,5 +26,5 @@
     "divi": ["divi/et_pb_contact_form"],
     "classic": ["classic/contact-form-7", "classic/wpforms", "classic/gravityforms", "classic/ninja-forms"]
   },
-  "a11y": "Contact details are a description list when every one has a label, a plain list otherwise; links say what they open. The form's labels, errors and focus handling are Studio's form runtime (FormMount). The section is labelled by its heading."
+  "a11y": "Contact details are a description list when every one has a label, a plain list otherwise; links say what they open. The form's labels, errors and focus handling are Studio's form runtime (FormMount). The section is labelled by its heading. Without a form to show and with no introduction or details, the section is not drawn at all."
 }

package/components/header/Header.astro

@@ -20,13 +20,15 @@ const header = tv({
       'brand-left': { inner: 'justify-start [&>nav]:ms-10' },
     },
     tone: {
-      default: { root: 'border-b border-line bg-surface text-ink' },
+      default: { root: 'bg-surface text-ink' },
       inverse: { root: 'bg-ink text-surface' },
       transparent: { root: 'absolute inset-x-0 top-0 bg-transparent text-surface' },
     },
     position: { static: {}, sticky: { root: 'sticky top-0' } },
+    bordered: { true: {}, false: {} },
   },
-  defaultVariants: { layout: 'split', tone: 'default', position: 'static' },
+  compoundVariants: [{ tone: 'default', bordered: true, class: { root: 'border-b border-line' } }],
+  defaultVariants: { layout: 'split', tone: 'default', position: 'static', bordered: true },
 })
 
 interface Props {
@@ -35,6 +37,15 @@ interface Props {
   tagline?: string | undefined
   /** The site name's size, where the source theme sets its own (a CSS length). */
   brandSize?: string | undefined
+  /** The line under the bar on the default tone; `false` where the source's header draws none. */
+  bordered?: boolean | undefined
+  /** The site name's weight and letter-spacing, where the source theme sets its own (CSS values). */
+  brandWeight?: string | undefined
+  brandTracking?: string | undefined
+  /** Space above the bar, and inside it above and below the content, where the source's header has its own (CSS lengths). */
+  offsetTop?: string | undefined
+  padTop?: string | undefined
+  padBottom?: string | undefined
   /** The navigation in the site's link colour, as themes that colour every link do (Hello Elementor). */
   linkNav?: boolean | undefined
   logo?: ImageInput | undefined
@@ -51,17 +62,20 @@ interface Props {
   position?: 'static' | 'sticky' | undefined
 }
 
-const { siteName, tagline, brandSize, linkNav, logo, showName = true, homeHref = '/', items, action, navLabel, menuLabel, closeLabel, layout, tone, position } = Astro.props
-const { root, inner, brand } = header({ layout, tone, position })
+const { siteName, tagline, brandSize, brandWeight, brandTracking, bordered, offsetTop, padTop, padBottom, linkNav, logo, showName = true, homeHref = '/', items, action, navLabel, menuLabel, closeLabel, layout, tone, position } = Astro.props
+const { root, inner, brand } = header({ layout, tone, position, bordered })
+const rootStyle = offsetTop ? `margin-top: ${offsetTop}` : undefined
+const innerStyle = [padTop && `padding-top: ${padTop}`, padBottom && `padding-bottom: ${padBottom}`].filter(Boolean).join('; ') || undefined
+const brandStyle = [brandSize && `font-size: ${brandSize}`, brandWeight && `font-weight: ${brandWeight}`, brandTracking && `letter-spacing: ${brandTracking}`].filter(Boolean).join('; ') || undefined
 // A tagline under the name keeps its line on a phone, as themes print it: the navigation wraps below.
 const wrap = tagline ? 'flex-wrap md:flex-nowrap' : undefined
 ---
-<header class={root()}>
-  <div class={inner({ class: wrap })}>
+<header class={root()} style={rootStyle}>
+  <div class={inner({ class: wrap })} style={innerStyle}>
     {tagline
       ? (
         <div class="flex min-w-0 basis-full flex-col gap-1 md:basis-auto">
-          <a href={homeHref} class={brand()} aria-label={showName ? undefined : siteName} style={brandSize ? `font-size: ${brandSize}` : undefined} data-kit-brand>
+          <a href={homeHref} class={brand()} aria-label={showName ? undefined : siteName} style={brandStyle} data-kit-brand>
             {logo && <KitImage image={logo} priority class="h-8 w-auto" sizes="160px" />}
             {showName && <span>{siteName}</span>}
           </a>
@@ -69,7 +83,7 @@ const wrap = tagline ? 'flex-wrap md:flex-nowrap' : undefined
         </div>
       )
       : (
-        <a href={homeHref} class={brand()} aria-label={showName ? undefined : siteName} style={brandSize ? `font-size: ${brandSize}` : undefined} data-kit-brand>
+        <a href={homeHref} class={brand()} aria-label={showName ? undefined : siteName} style={brandStyle} data-kit-brand>
           {logo && <KitImage image={logo} priority class="h-8 w-auto" sizes="160px" />}
           {showName && <span>{siteName}</span>}
         </a>

package/components/header/meta.json

@@ -14,6 +14,12 @@
     "siteName": { "type": "string", "required": true, "description": "Site title (site.title)." },
     "tagline": { "type": "string", "description": "A line under the site name, as themes that print the tagline in the header do (site.tagline)." },
     "brandSize": { "type": "string", "description": "The site name's size where the source theme sets its own (a CSS length)." },
+    "bordered": { "type": "boolean", "default": true, "description": "The line under the bar on the default tone; false where the source's header draws none." },
+    "brandWeight": { "type": "string", "description": "The site name's weight where the source theme sets its own (a CSS font-weight)." },
+    "brandTracking": { "type": "string", "description": "The site name's letter-spacing where the source theme sets its own (a CSS length, or normal)." },
+    "offsetTop": { "type": "string", "description": "Space above the bar where the source's header has its own (a CSS length)." },
+    "padTop": { "type": "string", "description": "Space inside the bar above its content where the source's header has its own (a CSS length)." },
+    "padBottom": { "type": "string", "description": "Space inside the bar below its content where the source's header has its own (a CSS length)." },
     "linkNav": { "type": "boolean", "default": false, "description": "The navigation in the site's link colour, as themes that colour every link do." },
     "logo": { "type": "object", "fields": { "src": { "type": "image", "required": true }, "alt": { "type": "string", "required": true }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "description": "Logo image (site.logo)." },
     "showName": { "type": "boolean", "default": true, "description": "Show the site name next to the logo." },

package/components/hero/Hero.astro

@@ -6,6 +6,7 @@ import Button from '../_shared/Button.astro'
 import KitImage from '../_shared/KitImage.astro'
 import Section from '../_shared/Section.astro'
 import type { ActionInput, ImageInput } from '../_shared/types'
+import { coverHeight as heightOf, headingStyle as styleOf } from './hero'
 
 const hero = tv({
   slots: {
@@ -36,6 +37,8 @@ const hero = tv({
     // How wide a cover runs: the full window, or the reading column — a WordPress cover block that is not
     // alignfull sits in the content column, the page title above it.
     width: { full: {}, content: {} },
+    // The heading's size: the layout's own scale, or the site's size for its level (set inline, see ./hero).
+    headingScale: { default: {}, theme: {} },
   },
   compoundVariants: [
     // After the layout's own heights, so a boxed cover keeps WordPress's 430px default.
@@ -45,7 +48,7 @@ const hero = tv({
     { leadAlign: 'start', class: { lead: 'mx-0 max-w-none self-stretch text-start' } },
     { actionsAlign: 'start', class: { actions: 'justify-start self-stretch' } },
   ],
-  defaultVariants: { layout: 'split', tone: 'default', align: 'center', leadAlign: 'inherit', actionsAlign: 'inherit', width: 'full' },
+  defaultVariants: { layout: 'split', tone: 'default', align: 'center', leadAlign: 'inherit', actionsAlign: 'inherit', width: 'full', headingScale: 'default' },
 })
 
 interface Props {
@@ -67,13 +70,20 @@ interface Props {
   width?: 'full' | 'content' | undefined
   tone?: 'default' | 'muted' | 'inverse' | 'accent' | undefined
   id?: string | undefined
+  /** A cover's own height in pixels, as the source sets it (`520`); absent, the layout's default. Layout cover only. */
+  minHeight?: number | undefined
+  /** `theme`: the heading takes the site's size for its level (the source's own `h1` size), not the layout's scale. */
+  headingScale?: 'default' | 'theme' | undefined
 }
 
-const { heading, level = 1, eyebrow, lead, actions = [], image, layout = 'split', align, leadAlign, actionsAlign, width = 'full', tone, id } = Astro.props
-const s = hero({ layout, align, leadAlign, actionsAlign, width, tone })
+
+const { heading, level = 1, eyebrow, lead, actions = [], image, layout = 'split', align, leadAlign, actionsAlign, width = 'full', tone, id, minHeight, headingScale } = Astro.props
+const s = hero({ layout, align, leadAlign, actionsAlign, width, tone, headingScale })
 const Heading = level === 1 ? 'h1' : 'h2'
 const headingId = id ? `${id}-title` : undefined
 const cover = layout === 'cover' && image
+const coverHeight = cover ? heightOf(minHeight) : undefined
+const headingStyle = styleOf(headingScale, level)
 ---
 {cover && width === 'content'
   ? (
@@ -82,10 +92,10 @@ const cover = layout === 'cover' && image
         <KitImage image={image} priority sizes="(min-width: 768px) 46rem, 100vw" class="absolute inset-0 -z-10 h-full w-full object-cover" />
         <div class="absolute inset-0 -z-10 bg-ink/60" aria-hidden="true" />
         <div class="px-6 py-10 md:px-10">
-          <div class={s.grid()}>
+          <div class={s.grid()} style={coverHeight ? `min-height: ${coverHeight}` : undefined}>
             <div class={s.copy()}>
               {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
-              <Heading id={headingId} class={s.heading()}>{heading}</Heading>
+              <Heading id={headingId} class={s.heading()} style={headingStyle}>{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>
@@ -100,10 +110,10 @@ const cover = layout === 'cover' && image
       <KitImage image={image} priority sizes="100vw" class="absolute inset-0 -z-10 h-full w-full object-cover" />
       <div class="absolute inset-0 -z-10 bg-ink/60" aria-hidden="true" />
       <div class="container-page py-16 md:py-28">
-        <div class={s.grid()}>
+        <div class={s.grid()} style={coverHeight ? `min-height: ${coverHeight}` : undefined}>
           <div class={s.copy()}>
             {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
-            <Heading id={headingId} class={s.heading()}>{heading}</Heading>
+            <Heading id={headingId} class={s.heading()} style={headingStyle}>{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>
@@ -117,7 +127,7 @@ const cover = layout === 'cover' && image
       <div class={s.grid({ class: image ? undefined : 'md:grid-cols-1' })}>
         <div class={s.copy()}>
           {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
-          <Heading id={headingId} class={s.heading()}>{heading}</Heading>
+          <Heading id={headingId} class={s.heading()} style={headingStyle}>{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>

package/components/hero/fixtures.json

@@ -167,5 +167,29 @@
       "level": 2,
       "actionsAlign": "start"
     }
+  },
+  {
+    "name": "cover-content-theme-size",
+    "props": {
+      "heading": "Independent cinema, a neighbourhood hall",
+      "lead": "A hundred and twenty seats, fresh popcorn.",
+      "layout": "cover",
+      "actions": [
+        {
+          "label": "This week's programme",
+          "href": "/programme/"
+        }
+      ],
+      "image": {
+        "src": "/kit-fixtures/photo-1.svg",
+        "alt": "",
+        "width": 1600,
+        "height": 900
+      },
+      "width": "content",
+      "level": 2,
+      "minHeight": 520,
+      "headingScale": "theme"
+    }
   }
 ]

package/components/hero/hero.ts

@@ -0,0 +1,9 @@
+// A cover's height reaches the style attribute only as a whole number of pixels: a value from a plan is data, not CSS.
+export const coverHeight = (value: number | undefined): string | undefined => (Number.isInteger(value) && value! >= 100 && value! <= 2000 ? `${value}px` : undefined)
+
+/**
+ * `theme`: the heading's size is the site's for its level, the one the source's own `h1`/`h2` has (`--text-heading-1`,
+ * fluid where the theme's is); the layout's scale is the fallback while the site declares none.
+ */
+export const headingStyle = (scale: 'default' | 'theme' | undefined, level: 1 | 2): string | undefined =>
+  scale === 'theme' ? `font-size: var(--text-heading-${level}, var(--text-5xl)); line-height: var(--leading-heading, 1.2)` : undefined

package/components/hero/meta.json

@@ -61,6 +61,14 @@
       ],
       "default": "full",
       "description": "Layout cover only. full: the image runs the full window width. content: the cover sits in the reading column, as a WordPress cover block that is not alignfull does under the page title."
+    },
+    "headingScale": {
+      "options": [
+        "default",
+        "theme"
+      ],
+      "default": "default",
+      "description": "default: the layout's own type scale. theme: the heading takes the site's size for its level (`--text-heading-1` for the page-opening hero, `-2` otherwise), as the source's own h1 does under a block theme."
     }
   },
   "props": {
@@ -159,6 +167,13 @@
       "type": "string",
       "content": false,
       "description": "Anchor id of the section; the heading gets `<id>-title`."
+    },
+    "minHeight": {
+      "type": "integer",
+      "content": false,
+      "min": 100,
+      "max": 2000,
+      "description": "Layout cover only: the cover's own height in pixels, as the source sets it (520); absent, the layout's default."
     }
   },
   "slots": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/astro-kit",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "license": "MIT",
   "description": "Copy-in Astro components for Contentrain sites (shadcn model): typed props, tailwind-variants, zero JavaScript by default — with a machine-readable catalog",
   "type": "module",
@@ -42,7 +42,7 @@
     "mapping"
   ],
   "dependencies": {
-    "@contentrain/types": "1.40.0"
+    "@contentrain/types": "1.42.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",