@contentrain/astro-kit 0.2.0 → 0.3.1

package/README.md

@@ -60,6 +60,19 @@ unchanged:
 - `--spacing-gutter`: the page frame's side padding, which falls back to 1rem
   on phones and 2rem from `md` up.
 
+The theme's type scale and rhythm are not read by components. The site's
+theme applies them to the kit's markers, and only when the site sets them:
+- `--text-heading-1` to `--text-heading-3`: headings inside `main`.
+- `--text-body`: `[data-kit-text]`, the lead and body paragraphs of hero, CTA
+  and card grid.
+- `--text-nav`: the header navigation, `[data-cr-part="nav-header"]`.
+- `--spacing-section`: the distance between two consecutive sections; each
+  `[data-kit-section]` gets half of it as vertical padding, except
+  where `data-kit-spacing="none"`.
+- `data-kit-brand` (the site title in Header and Footer) and `data-kit-tagline`
+  (Footer) take the theme's own sizes: the title from where it sits (body in
+  the header, a heading in the footer), the tagline from its preset.
+
 The full list is in `catalog.json` under `tokens`.
 
 ## API

package/catalog.json

@@ -20,7 +20,12 @@
     "--leading-heading",
     "--radius-control",
     "--radius-image",
-    "--spacing-gutter"
+    "--spacing-gutter",
+    "--text-nav",
+    "--text-heading-1",
+    "--text-heading-2",
+    "--text-heading-3",
+    "--spacing-section"
   ],
   "dependencies": {
     "tailwind-merge": "^3.7.0",
@@ -554,10 +559,11 @@
         "style": {
           "options": [
             "lines",
-            "cards"
+            "cards",
+            "plain"
           ],
           "default": "lines",
-          "description": "lines: rows divided by rules. cards: each question in a rounded box."
+          "description": "lines: rows divided by rules. cards: each question in a rounded box. plain: the browser's own disclosure triangle without rules or boxes (WordPress's details block)."
         },
         "tone": {
           "options": [

package/components/_shared/KitImage.astro

@@ -1,6 +1,17 @@
 ---
-// An image through astro:assets when its size is known — optimized and
-// sized, so the layout never shifts — and a plain lazy <img> when it is not.
+// An image through astro:assets, optimized and sized so the layout never
+// shifts, from either place a site's media lives:
+//
+//  - the repository, under public/ (`/media/2026/01/cover.jpg`): the file is
+//    read at build time and gets a srcset of resized copies;
+//  - a media host the site allows (Contentrain Studio's delivery URLs, in
+//    astro.config `image.remotePatterns`): fetched at build time when its
+//    size is known, and resized the same way.
+//
+// Anything else — a vector, a host the site does not allow, a remote image of
+// unknown size — is a plain lazy <img>: nothing is fetched from a host the
+// site did not name.
+import type { ImageMetadata } from 'astro'
 import { Image } from 'astro:assets'
 import type { ImageInput } from './types'
 
@@ -13,9 +24,25 @@ interface Props {
   priority?: boolean | undefined
 }
 
+// Raster files under public/, loaded only when a page shows one.
+const LOCAL = import.meta.glob<ImageMetadata>('/public/**/*.{avif,gif,jpeg,jpg,png,tif,tiff,webp,AVIF,GIF,JPEG,JPG,PNG,TIF,TIFF,WEBP}', { import: 'default' })
+
 const { image, sizes = '100vw', class: className, priority = false } = Astro.props
 const loading = priority ? 'eager' : 'lazy'
+const fetchpriority = priority ? 'high' : 'auto'
+const path = image.src.startsWith('/') && !image.src.startsWith('//') ? image.src.split(/[?#]/)[0]! : undefined
+// A malformed escape (`%E0%A4%A`) is no file in public/: the image stays a plain <img> rather than failing the build.
+const decoded = (() => { try { return path === undefined ? undefined : decodeURI(path) } catch { return undefined } })()
+const load = decoded === undefined ? undefined : LOCAL[`/public${decoded}`]
+const local = load ? await load() : undefined
+// The stored size (WordPress's chosen size of the file), else the file's own.
+const size = image.width && image.height ? { width: image.width, height: image.height } : {}
+// Candidate widths for the srcset, up to the image's own: the browser picks one by `sizes`.
+const STEPS = [320, 640, 960, 1280, 1600, 1920, 2560]
+const widthsUpTo = (max: number) => [...STEPS.filter(step => step < max), max]
 ---
-{image.width && image.height
-  ? <Image src={image.src} alt={image.alt} width={image.width} height={image.height} sizes={sizes} class={className} loading={loading} fetchpriority={priority ? 'high' : 'auto'} />
-  : <img src={image.src} alt={image.alt} class={className} loading={loading} decoding="async" />}
+{local
+  ? <Image src={local} alt={image.alt} {...size} widths={widthsUpTo(image.width ?? local.width)} sizes={sizes} class={className} loading={loading} fetchpriority={fetchpriority} />
+  : image.width && image.height && path === undefined
+    ? <Image src={image.src} alt={image.alt} width={image.width} height={image.height} widths={widthsUpTo(image.width)} sizes={sizes} class={className} loading={loading} fetchpriority={fetchpriority} />
+    : <img src={image.src} alt={image.alt} width={image.width} height={image.height} class={className} loading={loading} fetchpriority={fetchpriority} decoding="async" />}

package/components/_shared/Section.astro

@@ -38,6 +38,6 @@ interface Props {
 
 const { tone, spacing, width = 'page', as: Tag = 'section', id, class: className, 'aria-labelledby': labelledBy } = Astro.props
 ---
-<Tag id={id} aria-labelledby={labelledBy} class={section({ tone, spacing, class: className })} data-tone={tone ?? 'default'}>
+<Tag id={id} aria-labelledby={labelledBy} class={section({ tone, spacing, class: className })} data-tone={tone ?? 'default'} data-kit-section data-kit-spacing={spacing ?? 'md'}>
   {width === 'none' ? <slot /> : <div class={width === 'prose' ? 'container-prose' : 'container-page'}><slot /></div>}
 </Tag>

package/components/card-grid/CardGrid.astro

@@ -75,7 +75,7 @@ const headingId = title ? `cards-${title.toLowerCase().replace(/[^a-z0-9]+/g, '-
             ? <a href={item.href} class="text-current no-underline after:absolute after:inset-0 after:content-[''] hover:text-accent">{item.title}</a>
             : item.title}
         </CardHeading>
-        {item.text && <p class={text({ class: dim })}>{item.text}</p>}
+        {item.text && <p class={text({ class: dim })} data-kit-text>{item.text}</p>}
       </li>
     ))}
   </ul>

package/components/cta/Cta.astro

@@ -57,7 +57,7 @@ const shown = actions.map(action => (tone === 'accent' && (action.style ?? 'prim
   <div class={s.box()}>
     <div class={s.copy()}>
       <h2 id={headingId} class={s.heading()}>{heading}</h2>
-      {body && <p class={s.body()}>{body}</p>}
+      {body && <p class={s.body()} data-kit-text>{body}</p>}
     </div>
     {shown.length > 0 && <div class={s.actions()}>{shown.map(action => <Button action={action} size="lg" />)}</div>}
   </div>

package/components/faq/Faq.astro

@@ -25,6 +25,8 @@ const faq = tv({
     style: {
       lines: { list: 'divide-y divide-line border-y border-line' },
       cards: { list: 'gap-3', item: 'rounded-card border border-line px-5', summary: 'py-5' },
+      // WordPress's details block: the browser's own disclosure triangle, no rules or box.
+      plain: { list: 'gap-2', summary: 'list-item list-[revert] py-1 text-base [font-weight:inherit] [&::-webkit-details-marker]:inline', marker: 'hidden', answer: 'pt-2 pl-5' },
     },
     tone: { default: {}, muted: { item: 'bg-surface' }, inverse: { answer: 'prose-invert' }, accent: { answer: 'prose-invert' } },
   },
@@ -37,7 +39,7 @@ const faq = tv({
 interface Props {
   items: FaqItem[]
   heading?: string | undefined
-  style?: 'lines' | 'cards' | undefined
+  style?: 'lines' | 'cards' | 'plain' | undefined
   /** One answer open at a time (`<details name>`). */
   exclusive?: boolean | undefined
   /** Open the first answer. */

package/components/faq/fixtures.json

@@ -32,5 +32,9 @@
   {
     "name": "cards-accent",
     "props": { "style": "cards", "tone": "accent", "id": "faq-accent", "items": [{ "question": "How do I cancel my membership?", "answer": "<p>From your account page, at any time.</p>" }] }
+  },
+  {
+    "name": "plain",
+    "props": { "style": "plain", "id": "faq-plain", "items": [{ "question": "Do you accept guest essays?", "answer": "<p>Yes, send a short pitch first.</p>" }, { "question": "How often do you publish?", "answer": "<p>Two or three pieces a month.</p>" }] }
   }
 ]

package/components/faq/meta.json

@@ -6,7 +6,7 @@
   "uses": [],
   "shared": ["Section.astro"],
   "variants": {
-    "style": { "options": ["lines", "cards"], "default": "lines", "description": "lines: rows divided by rules. cards: each question in a rounded box." },
+    "style": { "options": ["lines", "cards", "plain"], "default": "lines", "description": "lines: rows divided by rules. cards: each question in a rounded box. plain: the browser's own disclosure triangle without rules or boxes (WordPress's details block)." },
     "tone": { "options": ["default", "muted", "inverse", "accent"], "default": "default", "description": "Section background." }
   },
   "props": {

package/components/footer/Footer.astro

@@ -48,8 +48,8 @@ const line = copyright ?? `© ${new Date().getFullYear()} ${siteName}`
 <footer class={root()}>
   <div class={inner()} style={layout === 'columns' ? `--footer-columns: ${Math.max(columns.length, 1)}` : undefined}>
     <div class="flex flex-col gap-3">
-      <p class="text-base font-semibold">{siteName}</p>
-      {tagline && <p class={muted()}>{tagline}</p>}
+      <p class="text-base font-semibold" data-kit-brand>{siteName}</p>
+      {tagline && <p class={muted()} data-kit-tagline>{tagline}</p>}
       {layout === 'columns' && <p class:list={[muted(), 'mt-auto pt-6']}>{line}</p>}
     </div>
     {layout === 'columns'

package/components/header/Header.astro

@@ -50,7 +50,7 @@ const { root, inner, brand } = header({ layout, tone, position })
 ---
 <header class={root()}>
   <div class={inner()}>
-    <a href={homeHref} class={brand()} aria-label={showName ? undefined : siteName}>
+    <a href={homeHref} class={brand()} aria-label={showName ? undefined : siteName} data-kit-brand>
       {logo && <KitImage image={logo} priority class="h-8 w-auto" sizes="160px" />}
       {showName && <span>{siteName}</span>}
     </a>

package/components/hero/Hero.astro

@@ -65,7 +65,7 @@ const cover = layout === 'cover' && image
           <div class={s.copy()}>
             {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
             <Heading id={headingId} class={s.heading()}>{heading}</Heading>
-            {lead && <p class={s.lead()}>{lead}</p>}
+            {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>
         </div>
@@ -78,7 +78,7 @@ const cover = layout === 'cover' && image
         <div class={s.copy()}>
           {eyebrow && <p class={s.eyebrow()}>{eyebrow}</p>}
           <Heading id={headingId} class={s.heading()}>{heading}</Heading>
-          {lead && <p class={s.lead()}>{lead}</p>}
+          {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>
         {image && (

package/mapping/gutenberg.json

@@ -215,7 +215,8 @@
       "match": "core/cover",
       "component": "hero",
       "variant": {
-        "layout": "cover"
+        "layout": "cover",
+        "align": "class:is-position-*-left=start|center"
       },
       "props": {
         "heading": "dom:h1,h2",
@@ -233,6 +234,9 @@
     {
       "match": "core/details",
       "component": "faq",
+      "variant": {
+        "style": "plain"
+      },
       "group": "siblings",
       "into": "items",
       "item": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/astro-kit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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.25.0"
+    "@contentrain/types": "1.27.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",