@contentrain/astro-kit 0.46.2 → 0.47.0

package/catalog.json

@@ -105,6 +105,7 @@
         "KitImage.astro",
         "Lines.astro",
         "Section.astro",
+        "card-image.ts",
         "image-widths.ts",
         "instance-id.ts",
         "measured.ts",
@@ -790,6 +791,7 @@
       "shared": [
         "KitImage.astro",
         "Section.astro",
+        "card-image.ts",
         "image-widths.ts",
         "image.ts",
         "instance-id.ts",
@@ -2401,6 +2403,16 @@
           "type": "string",
           "description": "Poster action for a map or widget (ui-strings embed.show)."
         },
+        "schema": {
+          "type": "boolean",
+          "default": true,
+          "content": false,
+          "description": "A VideoObject (JSON-LD) for a video with a title: name, caption as description, page and embed url, the local poster or the YouTube still as thumbnail (a URL in the data, not a request). On by default; a video with no title, a map or a player prints none. false: none."
+        },
+        "uploaded": {
+          "type": "string",
+          "description": "The video's upload date (ISO 8601), printed as uploadDate only when the source states it."
+        },
         "id": {
           "type": "string",
           "description": "Element id."
@@ -2443,6 +2455,7 @@
         "instance-id.ts",
         "measured.ts",
         "muted.ts",
+        "once-per-page.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -2547,9 +2560,9 @@
         },
         "schema": {
           "type": "boolean",
-          "default": false,
+          "default": true,
           "content": false,
-          "description": "Emit FAQPage JSON-LD built from these items. Use on at most one FAQ per page, and only when the page is really a FAQ."
+          "description": "FAQPage JSON-LD built from the answered items. On by default; only the first FAQ on a page that has an answered question prints it. false: none (questions that are not the page's own FAQ)."
         },
         "measured": {
           "type": "object",
@@ -5015,6 +5028,7 @@
       "uses": [],
       "shared": [
         "KitImage.astro",
+        "card-image.ts",
         "image-widths.ts",
         "safe-url.ts",
         "types.ts"
@@ -7824,6 +7838,7 @@
       "shared": [
         "KitImage.astro",
         "Section.astro",
+        "card-image.ts",
         "image-widths.ts",
         "image.ts",
         "instance-id.ts",

package/components/_shared/card-image.ts

@@ -0,0 +1,13 @@
+import type { ImageInput } from './types'
+
+const spoken = (text: string): string => text.replace(/\s+/g, ' ').trim().replace(/[.:;!]+$/, '').toLowerCase()
+
+/**
+ * A card's image beside its title link: when the title's link covers the card (a stretched link) and the image's text
+ * only repeats the title, the image is drawn with an empty text, so a screen reader says the title once. The content
+ * keeps its text (Studio, image search); an image outside such a card, or with words of its own, is drawn as written.
+ */
+export function cardImage(image: ImageInput | undefined, title: string | undefined, linked: boolean): ImageInput | undefined {
+  if (!image || !linked || !image.alt || !title || spoken(image.alt) !== spoken(title)) return image
+  return { ...image, alt: '' }
+}

package/components/_shared/once-per-page.ts

@@ -0,0 +1,17 @@
+// Something a page states once, whichever component prints it: the first FAQ on a page carries the page's FAQPage, a
+// second one would state a second FAQPage for the same page. Taken in the order the page renders its components, the
+// same on every build (`page` = `Astro.locals`, as in instance-id.ts).
+
+const claimed = new WeakMap<object, Set<string>>()
+
+/** True for the first caller on this page that claims `what`, false for every later one. */
+export function firstOnPage(page: object, what: string): boolean {
+  let taken = claimed.get(page)
+  if (!taken) {
+    taken = new Set()
+    claimed.set(page, taken)
+  }
+  if (taken.has(what)) return false
+  taken.add(what)
+  return true
+}

package/components/band/Band.astro

@@ -12,6 +12,7 @@ import type { ActionInput, ImageInput, MeasuredStyle } from '../_shared/types'
 import { safeHref } from '../_shared/safe-url'
 import { instanceId } from '../_shared/instance-id'
 import { muted } from '../_shared/muted'
+import { cardImage } from '../_shared/card-image'
 
 const band = tv({
   slots: {
@@ -134,7 +135,7 @@ const hasCopy = Boolean(heading || eyebrow || lead || actions.length)
       <ul class={s.list({ class: measuredGrid(measured) })}>
         {items.map(item => (
           <li class={s.item()}>
-            {item.media && <div class={s.itemMedia()}><KitImage image={{ src: item.media, alt: item.mediaAlt ?? '' }} sizes="(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 100vw" class="aspect-[3/2] w-full object-cover" /></div>}
+            {item.media && <div class={s.itemMedia()}><KitImage image={cardImage({ src: item.media, alt: item.mediaAlt ?? '' }, item.title, !!item.href && !item.linkLabel)!} sizes="(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 100vw" class="aspect-[3/2] w-full object-cover" /></div>}
             {item.icon && <KitImage image={{ src: item.icon, alt: '' }} class="h-10 w-10 object-contain" />}
             {item.value && <p class={s.itemValue()}>{item.value}</p>}
             {item.title && (

package/components/band/meta.json

@@ -9,6 +9,7 @@
     "KitImage.astro",
     "Lines.astro",
     "Section.astro",
+    "card-image.ts",
     "image-widths.ts",
     "instance-id.ts",
     "measured.ts",

package/components/card-grid/CardGrid.astro

@@ -7,6 +7,7 @@ import Section, { type Tone } from '../_shared/Section.astro'
 import { instanceId } from '../_shared/instance-id'
 import { measuredGrid } from '../_shared/measured'
 import type { MeasuredStyle } from '../_shared/types'
+import { cardImage } from '../_shared/card-image'
 import { imageOf, type ImageSource } from '../_shared/image'
 import { safeHref } from '../_shared/safe-url'
 import { muted, mutedReset } from '../_shared/muted'
@@ -130,7 +131,7 @@ const number = (i: number) => String(i + 1).padStart(2, '0')
           {item.text ? <p class={r.text()} data-kit-text>{item.text}</p> : <span aria-hidden="true" />}
           {(imageOf(item.image, item.imageAlt) || (item.href && item.linkLabel)) && (
             <div class={r.end({ class: imageOf(item.image, item.imageAlt) ? 'md:self-start' : undefined })}>
-              {imageOf(item.image, item.imageAlt) && <div class={r.media()}><KitImage image={imageOf(item.image, item.imageAlt)!} sizes="(min-width: 768px) 12rem, 100vw" class="aspect-[3/2] w-full object-cover" /></div>}
+              {imageOf(item.image, item.imageAlt) && <div class={r.media()}><KitImage image={cardImage(imageOf(item.image, item.imageAlt), item.title, !!item.href && !item.linkLabel)!} sizes="(min-width: 768px) 12rem, 100vw" class="aspect-[3/2] w-full object-cover" /></div>}
               {item.href && item.linkLabel && <a href={safeHref(item.href)} class={r.link()}>{item.linkLabel}</a>}
             </div>
           )}
@@ -141,7 +142,7 @@ const number = (i: number) => String(i + 1).padStart(2, '0')
     <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>}
+          {imageOf(item.image, item.imageAlt) && <div class={media()}><KitImage image={cardImage(imageOf(item.image, item.imageAlt), item.title, !!item.href && !item.linkLabel)!} 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>}
           {item.icon && <KitImage image={{ src: item.icon, alt: '' }} class="h-10 w-10 object-contain" />}
           {item.eyebrow && <p class="text-sm font-medium text-accent-text">{item.eyebrow}</p>}
           <CardHeading class={cardTitle()}>

package/components/card-grid/meta.json

@@ -7,6 +7,7 @@
   "shared": [
     "KitImage.astro",
     "Section.astro",
+    "card-image.ts",
     "image-widths.ts",
     "image.ts",
     "instance-id.ts",

package/components/embed/Embed.astro

@@ -49,10 +49,14 @@ interface Props {
   showLabel?: string | undefined
   aspect?: 'auto' | 'video' | 'portrait' | 'square' | 'map' | undefined
   width?: 'prose' | 'page' | undefined
+  /** VideoObject structured data (JSON-LD) for a video with a name (`title` or `caption`); on by default, `false`: none. */
+  schema?: boolean | undefined
+  /** When the video was published (ISO date), for the VideoObject's uploadDate; left out when unknown. */
+  uploaded?: string | undefined
   id?: string | undefined
 }
 
-const { url, address, title, caption, poster, playLabel = 'Play', showLabel = 'Show', aspect = 'auto', width, id } = Astro.props
+const { url, address, title, caption, poster, playLabel = 'Play', showLabel = 'Show', aspect = 'auto', width, schema = true, uploaded, id } = Astro.props
 const target = (url ? embedTarget(url) : null) ?? (address && !url ? mapTarget(address) : null)
 const shape = aspect !== 'auto' ? aspect : target?.portrait ? 'portrait' : target?.kind === 'map' ? 'map' : 'video'
 // A player strip (Spotify, SoundCloud) has a fixed height, not a ratio.
@@ -61,6 +65,22 @@ const s = embed({ aspect: strip ? 'auto' : shape, width })
 const action = target && (target.kind === 'video' || target.kind === 'audio') ? playLabel : showLabel
 const name = title ?? caption ?? ''
 const linkUrl = url && /^https?:\/\//i.test(url) ? url : undefined
+// VideoObject states only what the embed knows: its name, its page and player, a poster (the site's own, else the
+// provider's still for a YouTube video: a URL in data, never fetched by the visitor) and an upload date when given.
+const youtubeId = target?.provider === 'youtube' ? /(?:[?&]v=|\/shorts\/)([\w-]{11})/.exec(target.href)?.[1] : undefined
+const thumbnail = poster?.src ? new URL(poster.src, Astro.site ?? Astro.url).href : youtubeId ? `https://i.ytimg.com/vi/${youtubeId}/hqdefault.jpg` : undefined
+const structured = schema && target?.kind === 'video' && name
+  ? JSON.stringify({
+      '@context': 'https://schema.org',
+      '@type': 'VideoObject',
+      name,
+      ...(caption && caption !== name ? { description: caption } : {}),
+      url: target.href,
+      embedUrl: target.src.split('?')[0],
+      ...(thumbnail ? { thumbnailUrl: thumbnail } : {}),
+      ...(uploaded ? { uploadDate: uploaded } : {}),
+    }).replace(/</g, '\\u003c')
+  : null
 ---
 {target
   ? (
@@ -77,6 +97,7 @@ const linkUrl = url && /^https?:\/\//i.test(url) ? url : undefined
         </a>
       </div>
       {caption && <figcaption class={s.caption()}>{caption}</figcaption>}
+      {structured && <script type="application/ld+json" set:html={structured}></script>}
     </figure>
   )
   : linkUrl && (

package/components/embed/meta.json

@@ -17,6 +17,8 @@
     "poster": { "type": "object", "fields": { "src": { "type": "image", "required": true }, "alt": { "type": "string", "required": true }, "width": { "type": "integer" }, "height": { "type": "integer" } }, "description": "Local poster image (an ImageInput; its alt is not used, the link names the embed). Without one the poster is a plain dark panel. Never a provider thumbnail URL: that would be a third-party request before the click." },
     "playLabel": { "type": "string", "description": "Poster action for a video or audio player (ui-strings embed.play)." },
     "showLabel": { "type": "string", "description": "Poster action for a map or widget (ui-strings embed.show)." },
+    "schema": { "type": "boolean", "default": true, "content": false, "description": "A VideoObject (JSON-LD) for a video with a title: name, caption as description, page and embed url, the local poster or the YouTube still as thumbnail (a URL in the data, not a request). On by default; a video with no title, a map or a player prints none. false: none." },
+    "uploaded": { "type": "string", "description": "The video's upload date (ISO 8601), printed as uploadDate only when the source states it." },
     "id": { "type": "string", "description": "Element id." }
   },
   "slots": {},

package/components/faq/Faq.astro

@@ -1,13 +1,14 @@
 ---
 // Questions and answers as native disclosure widgets (<details>) — no script.
-// `exclusive` groups them by name, so opening one closes the others. With
-// `schema`, the page also carries FAQPage structured data for search engines
-// and AI answers.
+// `exclusive` groups them by name, so opening one closes the others. The first
+// FAQ on a page with an answered question also carries the page's FAQPage
+// structured data for search engines and AI answers (`schema={false}`: none).
 import { tv } from 'tailwind-variants'
 import Section from '../_shared/Section.astro'
 import { measuredColumns } from '../_shared/measured'
 import type { MeasuredStyle } from '../_shared/types'
 import { instanceId } from '../_shared/instance-id'
+import { firstOnPage } from '../_shared/once-per-page'
 import { muted } from '../_shared/muted'
 
 export interface FaqItem {
@@ -78,7 +79,7 @@ interface Props {
   exclusive?: boolean | undefined
   /** Open the first answer. */
   openFirst?: boolean | undefined
-  /** Add FAQPage structured data (JSON-LD). Once per page. */
+  /** FAQPage structured data (JSON-LD) from the answered questions; on by default, printed by the first FAQ on the page only. */
   schema?: boolean | undefined
   tone?: 'default' | 'muted' | 'inverse' | 'accent' | 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. */
@@ -88,7 +89,7 @@ interface Props {
   entry?: string | undefined
 }
 
-const { items, heading, intro, layout, columns, icon, numbered = false, style, questionStyle, exclusive = false, openFirst = false, schema = false, tone, measured, id: givenId } = Astro.props
+const { items, heading, intro, layout, columns, icon, numbered = false, style, questionStyle, exclusive = false, openFirst = false, schema = true, tone, measured, id: givenId } = Astro.props
 // Two on one page never share an id: their labels and controls would point into each other.
 const id = instanceId(Astro.locals, givenId, 'faq')
 const s = faq({ layout, columns, icon, numbered, style, questionStyle: style === 'plain' ? 'heading' : questionStyle, tone })
@@ -105,9 +106,10 @@ const plain = (html: string) => html.replace(/<[^>]*>/g, ' ').replace(/&(?:nbsp|
 const MEDIA = /<(?:img|picture|video|audio|iframe|svg|embed|object|canvas)\b/i
 const answered = items.map(item => plain(item.answer) !== '' || MEDIA.test(item.answer))
 const firstAnswered = answered.indexOf(true)
-// FAQPage needs each question's acceptedAnswer text, so a question without one is left out of it.
+// FAQPage needs each question's acceptedAnswer text, so a question without one is left out of it. One per page: a FAQ
+// with nothing to state does not take the page's turn.
 const withText = items.filter(item => plain(item.answer) !== '')
-const structured = schema && withText.length > 0
+const structured = schema && withText.length > 0 && firstOnPage(Astro.locals, 'faq-page')
   ? JSON.stringify({
       '@context': 'https://schema.org',
       '@type': 'FAQPage',

package/components/faq/meta.json

@@ -4,7 +4,7 @@
   "description": "Questions and answers as native <details> disclosures (no script), in lines or cards; optionally one open at a time, and optionally with FAQPage structured data for search engines and AI answers.",
   "category": "section",
   "uses": [],
-  "shared": ["Section.astro", "instance-id.ts", "measured.ts", "muted.ts", "safe-url.ts", "types.ts"],
+  "shared": ["Section.astro", "instance-id.ts", "measured.ts", "muted.ts", "once-per-page.ts", "safe-url.ts", "types.ts"],
   "variants": {
     "layout": { "options": ["single", "split"], "default": "single", "description": "single: the heading above one column. split: the heading and introduction stay in a left column beside the list; stacks on a phone." },
     "columns": { "options": ["1", "2"], "default": "1", "description": "Columns of questions on wide screens." },
@@ -19,7 +19,7 @@
     "intro": { "type": "text", "label": "Introduction", "description": "A sentence under the heading." },
     "exclusive": { "type": "boolean", "default": false, "content": false, "description": "One answer open at a time (Elementor accordion, Divi accordion). Off for toggles." },
     "openFirst": { "type": "boolean", "default": false, "content": false, "description": "The first answer starts open (Divi open_toggle, Elementor active item 1)." },
-    "schema": { "type": "boolean", "default": false, "content": false, "description": "Emit FAQPage JSON-LD built from these items. Use on at most one FAQ per page, and only when the page is really a FAQ." },
+    "schema": { "type": "boolean", "default": true, "content": false, "description": "FAQPage JSON-LD built from the answered items. On by default; only the first FAQ on a page that has an answered question prints it. false: none (questions that are not the page's own FAQ)." },
     "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." } } },
     "entry": { "type": "string", "content": false, "description": "The page entry this section is built from, without its locale (services-0): printed as data-kit-entry, the hook a design layer styles this one section by. Absent, none is printed." },
     "id": { "type": "string", "content": false, "description": "Section id; also the exclusive group's name." },

package/components/post-card/PostCard.astro

@@ -8,6 +8,7 @@ import { tv } from 'tailwind-variants'
 import KitImage from '../_shared/KitImage.astro'
 import type { ImageInput, LinkInput } from '../_shared/types'
 import { safeHref } from '../_shared/safe-url'
+import { cardImage } from '../_shared/card-image'
 
 const card = tv({
   slots: {
@@ -82,7 +83,7 @@ const Heading = `h${headingLevel}` as 'h2' | 'h3'
 <article class={slots.root()}>
   {image && layout !== 'minimal' && (
     <div class={slots.media()}>
-      <KitImage image={image} sizes={sizes ?? (layout === 'horizontal' ? '256px' : '(min-width: 1024px) 360px, 100vw')} class:list={['w-full object-cover transition duration-300 group-hover:scale-[1.02]', !imageStyle && 'aspect-[16/9]']} style={imageStyle} />
+      <KitImage image={cardImage(image, title, !!href)!} sizes={sizes ?? (layout === 'horizontal' ? '256px' : '(min-width: 1024px) 360px, 100vw')} class:list={['w-full object-cover transition duration-300 group-hover:scale-[1.02]', !imageStyle && 'aspect-[16/9]']} style={imageStyle} />
     </div>
   )}
   <div class={slots.body()}>

package/components/post-card/meta.json

@@ -4,7 +4,7 @@
   "description": "One post in a list (index, archive, related posts): image, category, date, title, excerpt, author. The whole card links to the post.",
   "category": "content",
   "uses": [],
-  "shared": ["KitImage.astro", "image-widths.ts", "safe-url.ts", "types.ts"],
+  "shared": ["KitImage.astro", "card-image.ts", "image-widths.ts", "safe-url.ts", "types.ts"],
   "variants": {
     "layout": { "options": ["vertical", "horizontal", "minimal"], "default": "vertical", "description": "Image on top, image beside the text, or text only with a divider." },
     "surface": { "options": ["plain", "card"], "default": "plain", "description": "plain: no surface. card: its own background (--color-card), radius and shadow (--shadow-card), the text padded (--spacing-card) and the image flush at the edge, as theme cards are drawn on a tinted page." },

package/components/team/Team.astro

@@ -7,6 +7,7 @@ import Section from '../_shared/Section.astro'
 import { instanceId } from '../_shared/instance-id'
 import { measuredGrid } from '../_shared/measured'
 import type { MeasuredStyle } from '../_shared/types'
+import { cardImage } from '../_shared/card-image'
 import { imageOf, type ImageSource } from '../_shared/image'
 import { profile } from './team'
 import { safeHref } from '../_shared/safe-url'
@@ -109,7 +110,7 @@ const NameHeading = heading ? 'h3' : 'h2'
       {items.map(member => (
         <li class={s.member()}>
           {/* The portrait's text defaults to the name: a photo of a named person is not decoration. */}
-          {imageOf(member.image, member.imageAlt ?? member.name) && <div class={`${s.portrait()} kit-portrait`}><KitImage image={imageOf(member.image, member.imageAlt ?? member.name)!} sizes="(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw" class="aspect-square w-full object-cover" /></div>}
+          {imageOf(member.image, member.imageAlt ?? member.name) && <div class={`${s.portrait()} kit-portrait`}><KitImage image={cardImage(imageOf(member.image, member.imageAlt ?? member.name), member.name, !!member.href)!} sizes="(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw" class="aspect-square w-full object-cover" /></div>}
           <NameHeading class={s.name()}>
             {member.href
               ? <a href={safeHref(member.href)} class="text-current no-underline after:absolute after:inset-0 after:content-[''] hover:text-accent-text">{member.name}</a>

package/components/team/meta.json

@@ -7,6 +7,7 @@
   "shared": [
     "KitImage.astro",
     "Section.astro",
+    "card-image.ts",
     "image-widths.ts",
     "image.ts",
     "instance-id.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/astro-kit",
-  "version": "0.46.2",
+  "version": "0.47.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",