@contentrain/astro-kit 0.46.3 → 0.47.0

package/catalog.json

@@ -2403,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."
@@ -2445,6 +2455,7 @@
         "instance-id.ts",
         "measured.ts",
         "muted.ts",
+        "once-per-page.ts",
         "safe-url.ts",
         "types.ts"
       ],
@@ -2549,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",

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/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/package.json

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