@contentrain/astro-kit 0.1.1 → 0.2.0

package/README.md

@@ -27,6 +27,8 @@ They read its design tokens and pass its gates: `astro check` with the
 | `gallery` | Image grid with a popover lightbox | none |
 | `slider` | Carousel on a scroll-snap row | Embla |
 | `contact-form` | Contentrain Studio form in a section | Studio runtime |
+| `newsletter` | Sign-up posting straight to the list provider (Mailchimp, Kit, MailerLite, Brevo, Buttondown) | none |
+| `embed` | Video, map or player loaded on click; a provider link until then (YouTube via nocookie) | a few lines, no dependency |
 | `pagination` | WordPress-style `/page/N/` links | none |
 | `breadcrumb` | Ancestors, then the current page, optional JSON-LD | none |
 
@@ -45,8 +47,20 @@ Components use colour roles and widths, never raw values. A site defines them
 in `@theme` (the starter already does): `--color-surface`,
 `--color-surface-muted`, `--color-ink`, `--color-ink-muted`, `--color-line`,
 `--color-accent`, `--color-accent-ink`, `--font-sans`, `--container-prose`,
-`--container-page`, `--container-wide` and `--radius-card`. The same list is in
-`catalog.json` under `tokens`.
+`--container-page`, `--container-wide` and `--radius-card`.
+
+A migrated site also carries its theme's type and shape, and components read
+these with a fallback to the kit's own values, so a site without them looks
+unchanged:
+- `--font-weight-heading`: section headings fall back to 700, item titles to 600.
+- `--font-weight-body`, `--text-body`, `--leading-body` and `--leading-heading`:
+  the body and rich-text type. These are in the starter's CSS.
+- `--radius-control`: buttons and form controls.
+- `--radius-image`: images, which fall back to `--radius-card`.
+- `--spacing-gutter`: the page frame's side padding, which falls back to 1rem
+  on phones and 2rem from `md` up.
+
+The full list is in `catalog.json` under `tokens`.
 
 ## API
 
@@ -71,7 +85,10 @@ rulesFor(gutenberg, 'core/cover') // → the rule that turns a cover block into
 builder elements to components, with a source for each prop from a small closed
 set of expressions (see `src/mapping.ts`). They are versioned, and an element
 no rule covers stays rich text (`fallback: "prose"`). When one rule matches an
-element, the outermost match owns its subtree.
+element, the outermost match owns its subtree. `defaults` lists attribute
+values a builder leaves out of its data while they are at their default
+(Elementor saves no `video_type` for a YouTube video); `when.attr` and `attr:`
+read through them (`attrsOf`).
 
 ## Development
 

package/catalog.json

@@ -12,7 +12,15 @@
     "--container-prose",
     "--container-page",
     "--container-wide",
-    "--radius-card"
+    "--radius-card",
+    "--font-weight-heading",
+    "--font-weight-body",
+    "--text-body",
+    "--leading-body",
+    "--leading-heading",
+    "--radius-control",
+    "--radius-image",
+    "--spacing-gutter"
   ],
   "dependencies": {
     "tailwind-merge": "^3.7.0",
@@ -425,6 +433,114 @@
         "Cta.astro"
       ]
     },
+    {
+      "id": "embed",
+      "name": "Embed",
+      "description": "A video, map or player from another site (YouTube, Vimeo, Google Maps, OpenStreetMap, Spotify, SoundCloud, Calendly, Typeform, Loom, Wistia), loaded only on click: until then a poster link to the provider's page, with no iframe, no third-party request and no cookie (YouTube through youtube-nocookie.com). Unknown providers are never framed; they stay a plain link.",
+      "category": "content",
+      "uses": [],
+      "shared": [
+        "KitImage.astro",
+        "types.ts"
+      ],
+      "variants": {
+        "aspect": {
+          "options": [
+            "auto",
+            "video",
+            "portrait",
+            "square",
+            "map"
+          ],
+          "default": "auto",
+          "description": "auto: 16:9 for videos, 9:16 for YouTube Shorts, 4:3 (16:9 wide) for maps, a fixed strip for audio players. The others force a ratio."
+        },
+        "width": {
+          "options": [
+            "prose",
+            "page"
+          ],
+          "default": "prose",
+          "description": "prose: as wide as the reading column. page: the full page frame."
+        }
+      },
+      "props": {
+        "url": {
+          "type": "url",
+          "description": "A video page (youtube.com/watch, youtu.be, /shorts/, vimeo.com/<id>) or a known provider's embed address (google.com/maps/embed, open.spotify.com/embed, w.soundcloud.com/player, calendly.com, *.typeform.com/to, loom.com/embed, fast.wistia.net/embed)."
+        },
+        "address": {
+          "type": "string",
+          "description": "A place or address shown on a Google map when there is no url (Elementor google_maps address, Divi map address)."
+        },
+        "title": {
+          "type": "string",
+          "description": "What it is: the player's accessible name and the poster's text."
+        },
+        "caption": {
+          "type": "string",
+          "description": "A line under the embed."
+        },
+        "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)."
+        },
+        "id": {
+          "type": "string",
+          "description": "Element id."
+        }
+      },
+      "slots": {},
+      "js": "vanilla",
+      "dependencies": {},
+      "sources": {
+        "gutenberg": [
+          "core/embed"
+        ],
+        "elementor": [
+          "elementor/video",
+          "elementor/google_maps"
+        ],
+        "divi": [
+          "divi/et_pb_video",
+          "divi/et_pb_map"
+        ],
+        "classic": [
+          "classic/youtube",
+          "classic/vimeo",
+          "classic/google-maps"
+        ]
+      },
+      "a11y": "The poster is one link named '<action>: <title>' that opens the provider's page without script. With script, Enter or a click puts the iframe in its place with the title as its accessible name and moves focus into it. Modified clicks (new tab) keep the link behaviour. The play icon is decorative.",
+      "files": [
+        "Embed.astro",
+        "embed.ts"
+      ]
+    },
     {
       "id": "faq",
       "name": "FAQ",
@@ -567,7 +683,11 @@
             "fields": {
               "title": {
                 "type": "string",
-                "required": true
+                "description": "Heading shown above the links; leave out when the source shows none."
+              },
+              "label": {
+                "type": "string",
+                "description": "Accessible name of the column navigation (the menu name); defaults to the title."
               },
               "links": {
                 "type": "array",
@@ -956,6 +1076,14 @@
           ],
           "default": "default",
           "description": "Section background (ignored by cover, which is always light text on the image)."
+        },
+        "align": {
+          "options": [
+            "start",
+            "center"
+          ],
+          "default": "center",
+          "description": "Text position over a cover image (layout cover only): centred, as WordPress covers default to, or at the start edge."
         }
       },
       "props": {
@@ -1131,6 +1259,10 @@
         "id": {
           "type": "string",
           "description": "Unique id when a page renders two navigations."
+        },
+        "part": {
+          "type": "string",
+          "description": "What the navigation is, for checks that find a page's parts (data-cr-part), e.g. \"nav-header\"."
         }
       },
       "slots": {},
@@ -1157,6 +1289,115 @@
         "Nav.astro"
       ]
     },
+    {
+      "id": "newsletter",
+      "name": "Newsletter sign-up",
+      "description": "A newsletter sign-up that posts straight to the list provider's hosted form endpoint (Mailchimp, Kit, MailerLite, Brevo, Buttondown): a plain HTML form with no script and no server of ours. The provider shows its own confirmation page. The action must be the named provider's endpoint (exact host and path; `other`: https off the site's origin), otherwise nothing renders. WordPress-side sign-up plugins (MC4WP, Divi signup, Jetpack) post through the site and are not mapped here: the plan lists them for review.",
+      "category": "section",
+      "uses": [],
+      "shared": [
+        "Section.astro"
+      ],
+      "variants": {
+        "layout": {
+          "options": [
+            "inline",
+            "stacked"
+          ],
+          "default": "inline",
+          "description": "inline: copy beside the form on wide screens. stacked: one centred column."
+        },
+        "tone": {
+          "options": [
+            "default",
+            "muted",
+            "inverse",
+            "accent"
+          ],
+          "default": "muted",
+          "description": "Section background."
+        }
+      },
+      "props": {
+        "action": {
+          "type": "url",
+          "required": true,
+          "description": "The provider's hosted form endpoint (Mailchimp *.list-manage.com/subscribe/post, Kit app.kit.com/forms/<n>/subscriptions, MailerLite assets.mailerlite.com/jsonp/<n>/forms/<n>/subscribe, Brevo *.sibforms.com/serve/, Buttondown buttondown.com/api/emails/embed-subscribe/). At migration the engine reads it from the source form element (`dom:form@action`) into the section's content, where it stays editable in Studio; it never passes through the fact pack or a model."
+        },
+        "provider": {
+          "type": "select",
+          "options": [
+            "mailchimp",
+            "kit",
+            "mailerlite",
+            "brevo",
+            "buttondown",
+            "other"
+          ],
+          "default": "mailchimp",
+          "description": "Names the fields the endpoint expects (Mailchimp EMAIL/FNAME + its bot-trap field, Kit email_address, MailerLite fields[email], Brevo EMAIL, Buttondown email)."
+        },
+        "emailName": {
+          "type": "string",
+          "description": "Field name for the address when the provider is other or names it differently."
+        },
+        "askName": {
+          "type": "boolean",
+          "default": false,
+          "description": "Ask for a first name too, when the provider takes one (the source form had a name field)."
+        },
+        "heading": {
+          "type": "string",
+          "description": "Section heading."
+        },
+        "intro": {
+          "type": "text",
+          "description": "A line or two about the newsletter."
+        },
+        "note": {
+          "type": "string",
+          "description": "Small print under the form (privacy, frequency)."
+        },
+        "emailLabel": {
+          "type": "string",
+          "description": "ui-strings newsletter.email."
+        },
+        "nameLabel": {
+          "type": "string",
+          "description": "ui-strings newsletter.name."
+        },
+        "submitLabel": {
+          "type": "string",
+          "description": "ui-strings newsletter.submit."
+        },
+        "newTab": {
+          "type": "boolean",
+          "default": true,
+          "description": "Open the provider's confirmation page in a new tab (the reader keeps the site)."
+        },
+        "id": {
+          "type": "string",
+          "description": "Section id, unique per page (two sign-ups on one page need two ids): the heading gets `<id>-title`, the inputs `<id>-email`/`<id>-name`."
+        }
+      },
+      "slots": {},
+      "js": "none",
+      "dependencies": {},
+      "sources": {
+        "classic": [
+          "classic/mailchimp",
+          "classic/kit",
+          "classic/mailerlite",
+          "classic/brevo",
+          "classic/buttondown"
+        ]
+      },
+      "a11y": "Every input has a visible label and the address field is type=email, required, with autocomplete=email, so the browser validates it and announces errors without script. The form is named by the section heading (or the submit label). Mailchimp's bot-trap field is aria-hidden, off screen and out of the tab order.",
+      "files": [
+        "Newsletter.astro",
+        "newsletter.ts"
+      ]
+    },
     {
       "id": "pagination",
       "name": "Pagination",

package/components/_shared/Button.astro

@@ -5,7 +5,7 @@ import { tv } from 'tailwind-variants'
 import type { ActionInput } from './types'
 
 const button = tv({
-  base: 'inline-flex items-center justify-center gap-2 rounded-md font-medium no-underline transition-colors focus-visible:outline-2 focus-visible:outline-offset-2',
+  base: 'inline-flex items-center justify-center gap-2 rounded-[var(--radius-control,var(--radius-md))] font-medium no-underline transition-colors focus-visible:outline-2 focus-visible:outline-offset-2',
   variants: {
     style: {
       primary: 'bg-accent text-accent-ink hover:bg-ink hover:text-surface',

package/components/breadcrumb/Breadcrumb.astro

@@ -42,7 +42,7 @@ const jsonLd = schema
   }).replace(/</g, '\\u003c')
   : undefined
 ---
-<nav aria-label={label}>
+<nav aria-label={label} data-cr-part="breadcrumb">
   <ol class={slots.list()}>
     {items.map(item => (
       <li class="flex items-center gap-2">

package/components/card-grid/CardGrid.astro

@@ -10,8 +10,8 @@ const grid = tv({
   slots: {
     list: 'grid items-start gap-6 md:gap-8',
     card: 'group relative flex flex-col gap-3 rounded-[var(--radius-card)]',
-    media: 'overflow-hidden rounded-[var(--radius-card)]',
-    title: 'text-lg leading-snug font-semibold text-balance',
+    media: 'overflow-hidden rounded-[var(--radius-image,var(--radius-card))]',
+    title: 'text-lg leading-snug [font-weight:var(--font-weight-heading,600)] text-balance',
     text: 'opacity-80',
   },
   variants: {
@@ -61,7 +61,7 @@ const headingId = title ? `cards-${title.toLowerCase().replace(/[^a-z0-9]+/g, '-
 <Section 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-bold tracking-tight text-balance md:text-4xl">{title}</Heading>}
+      {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>
   )}

package/components/contact-form/ContactForm.astro

@@ -21,7 +21,7 @@ const contact = tv({
   slots: {
     grid: 'grid gap-10',
     copy: 'flex flex-col gap-4',
-    heading: 'text-2xl font-bold tracking-tight text-balance md:text-3xl',
+    heading: 'text-2xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-3xl',
     intro: 'max-w-xl text-pretty opacity-85',
     details: 'mt-2 flex flex-col gap-4',
     term: 'text-sm font-semibold opacity-75',

package/components/cta/Cta.astro

@@ -10,7 +10,7 @@ const cta = tv({
   slots: {
     box: 'flex flex-col gap-6',
     copy: 'flex flex-col gap-3',
-    heading: 'text-2xl font-bold tracking-tight text-balance md:text-3xl',
+    heading: 'text-2xl [font-weight:var(--font-weight-heading,700)] tracking-tight text-balance md:text-3xl',
     body: 'max-w-2xl text-pretty opacity-85',
     actions: 'flex flex-wrap gap-3',
   },

package/components/embed/Embed.astro

@@ -0,0 +1,104 @@
+---
+// A video, map or player from another site, loaded only when the reader asks
+// for it. Until then it is a link to the provider's page drawn as a poster:
+// no iframe, no third-party request, no cookie (YouTube plays from
+// youtube-nocookie.com). A small script turns the click into the player in
+// place; without it the link simply opens the provider. Unknown providers are
+// never framed — they stay a plain link.
+import { tv } from 'tailwind-variants'
+import KitImage from '../_shared/KitImage.astro'
+import type { ImageInput } from '../_shared/types'
+import { embedTarget, mapTarget } from './embed'
+
+const embed = tv({
+  slots: {
+    root: 'mx-auto my-8 w-full',
+    frame: 'relative overflow-hidden rounded-card bg-ink text-surface',
+    facade: 'group absolute inset-0 flex items-end justify-start no-underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent',
+    poster: 'absolute inset-0 h-full w-full object-cover opacity-80 transition-opacity group-hover:opacity-65',
+    play: 'absolute top-1/2 left-1/2 grid size-16 -translate-x-1/2 -translate-y-1/2 place-items-center rounded-full bg-accent text-accent-ink shadow-lg transition-transform group-hover:scale-105 group-focus-visible:scale-105',
+    label: 'relative m-0 w-full bg-gradient-to-t from-ink/90 to-transparent px-4 pt-10 pb-3 text-sm font-semibold text-balance text-surface md:px-5 md:pb-4 md:text-base',
+    caption: 'mt-2 text-sm text-ink-muted',
+  },
+  variants: {
+    aspect: {
+      auto: {},
+      video: { frame: 'aspect-video' },
+      portrait: { root: 'max-w-sm', frame: 'aspect-[9/16]' },
+      square: { root: 'max-w-xl', frame: 'aspect-square' },
+      map: { frame: 'aspect-[4/3] md:aspect-[16/9]' },
+    },
+    width: { prose: { root: 'max-w-(--container-prose)' }, page: {} },
+  },
+  defaultVariants: { aspect: 'auto', width: 'prose' },
+})
+
+interface Props {
+  /** A video page (YouTube, Vimeo) or a known provider's embed address (Google Maps embed, Spotify, SoundCloud, Calendly, Typeform, Loom, Wistia). */
+  url?: string | undefined
+  /** A place or address to show on a Google map, when there is no `url`. */
+  address?: string | undefined
+  /** What it is ("Studio tour", "Our office"): the iframe's accessible name and the poster's text. */
+  title?: string | undefined
+  caption?: string | undefined
+  /** Local poster image; without one the poster is a plain dark panel. */
+  poster?: ImageInput | undefined
+  /** Poster action for a video or player (ui-strings embed.play). */
+  playLabel?: string | undefined
+  /** Poster action for a map or widget (ui-strings embed.show). */
+  showLabel?: string | undefined
+  aspect?: 'auto' | 'video' | 'portrait' | 'square' | 'map' | undefined
+  width?: 'prose' | 'page' | undefined
+  id?: string | undefined
+}
+
+const { url, address, title, caption, poster, playLabel = 'Play', showLabel = 'Show', aspect = 'auto', width, 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.
+const strip = aspect === 'auto' && target?.kind === 'audio'
+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
+---
+{target
+  ? (
+    <figure id={id} class={s.root()} data-kit-embed>
+      <div class={s.frame({ class: strip ? 'h-[166px]' : undefined })}>
+        <a href={target.href} class={s.facade()} data-embed-src={target.src} data-embed-title={name || target.provider} aria-label={name ? `${action}: ${name}` : action} rel="noopener">
+          {poster && <KitImage image={{ ...poster, alt: '' }} sizes="(min-width: 768px) 48rem, 100vw" class={s.poster()} />}
+          <span class={s.play()} aria-hidden="true">
+            {target.kind === 'map'
+              ? <svg viewBox="0 0 24 24" class="size-7" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 21s-7-6.2-7-11.5a7 7 0 1 1 14 0C19 14.8 12 21 12 21Z" /><circle cx="12" cy="9.5" r="2.5" /></svg>
+              : <svg viewBox="0 0 24 24" class="ms-1 size-7" fill="currentColor"><path d="M7 4.5v15a.5.5 0 0 0 .77.42l11.5-7.5a.5.5 0 0 0 0-.84L7.77 4.08A.5.5 0 0 0 7 4.5Z" /></svg>}
+          </span>
+          <span class={s.label()} aria-hidden="true">{name ? `${action}: ${name}` : action}</span>
+        </a>
+      </div>
+      {caption && <figcaption class={s.caption()}>{caption}</figcaption>}
+    </figure>
+  )
+  : linkUrl && (
+    <p id={id} class={s.root()}><a href={linkUrl} rel="noopener" class="underline decoration-line underline-offset-4 hover:decoration-current">{name || linkUrl}</a></p>
+  )}
+
+<script>
+  // Click (or Enter) on the poster: the player replaces it, focused, so keyboard and screen-reader users land in it.
+  // A modified click (new tab, new window) keeps the link's own behaviour.
+  document.addEventListener('click', (event) => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+    const link = (event.target as Element | null)?.closest<HTMLAnchorElement>('[data-kit-embed] a[data-embed-src]')
+    if (!link?.dataset.embedSrc) return
+    event.preventDefault()
+    const frame = document.createElement('iframe')
+    frame.src = link.dataset.embedSrc
+    frame.title = link.dataset.embedTitle ?? ''
+    frame.allow = 'autoplay; encrypted-media; picture-in-picture; fullscreen; clipboard-write'
+    frame.allowFullscreen = true
+    frame.referrerPolicy = 'strict-origin-when-cross-origin'
+    frame.className = 'absolute inset-0 h-full w-full border-0'
+    link.replaceWith(frame)
+    frame.focus()
+  })
+</script>

package/components/embed/embed.ts

@@ -0,0 +1,106 @@
+// What an embed URL becomes: the player/map address the iframe loads after a
+// click, the page a plain link opens without JavaScript, and the provider.
+// Only known providers get an iframe; anything else stays a link, so a page
+// can never frame an arbitrary address that came in with the content.
+
+export type EmbedProvider = 'youtube' | 'vimeo' | 'google-maps' | 'openstreetmap' | 'spotify' | 'soundcloud' | 'calendly' | 'typeform' | 'loom' | 'wistia'
+
+export interface EmbedTarget {
+  provider: EmbedProvider
+  /** Loaded into the iframe on activation (autoplays where the provider allows it: the click was the consent). */
+  src: string
+  /** Opened by the plain link: the provider's own page. */
+  href: string
+  kind: 'video' | 'map' | 'audio' | 'widget'
+  /** YouTube Shorts and other vertical players. */
+  portrait?: boolean
+}
+
+const https = (value: string): URL | null => {
+  try {
+    const url = new URL(value.trim())
+    return url.protocol === 'https:' || url.protocol === 'http:' ? url : null
+  }
+  catch { return null }
+}
+
+const YOUTUBE_ID = /^[\w-]{11}$/
+/** `t=1m30s`, `t=90`, `start=90` → seconds. */
+const seconds = (value: string | null): number => {
+  if (!value) return 0
+  if (/^\d+$/.test(value)) return Number(value)
+  const m = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/.exec(value)
+  return m ? Number(m[1] ?? 0) * 3600 + Number(m[2] ?? 0) * 60 + Number(m[3] ?? 0) : 0
+}
+
+function youtube(url: URL): EmbedTarget | null {
+  const host = url.hostname.replace(/^(?:www|m)\./, '')
+  let id: string | null = null
+  let portrait = false
+  if (host === 'youtu.be') id = url.pathname.slice(1).split('/')[0] ?? null
+  else if (host === 'youtube.com' || host === 'youtube-nocookie.com') {
+    const [first, second] = url.pathname.split('/').filter(Boolean)
+    if (first === 'watch') id = url.searchParams.get('v')
+    else if (first === 'embed' || first === 'live' || first === 'v') id = second ?? null
+    else if (first === 'shorts') { id = second ?? null; portrait = true }
+  }
+  if (!id || !YOUTUBE_ID.test(id)) return null
+  const start = seconds(url.searchParams.get('t') ?? url.searchParams.get('start'))
+  const query = new URLSearchParams({ autoplay: '1', rel: '0' })
+  if (start) query.set('start', String(start))
+  return {
+    provider: 'youtube',
+    kind: 'video',
+    src: `https://www.youtube-nocookie.com/embed/${id}?${query}`,
+    href: portrait ? `https://www.youtube.com/shorts/${id}` : `https://www.youtube.com/watch?v=${id}${start ? `&t=${start}s` : ''}`,
+    ...(portrait ? { portrait } : {}),
+  }
+}
+
+function vimeo(url: URL): EmbedTarget | null {
+  const host = url.hostname.replace(/^www\./, '')
+  if (host !== 'vimeo.com' && host !== 'player.vimeo.com') return null
+  const parts = url.pathname.split('/').filter(Boolean)
+  const at = parts[0] === 'video' ? 1 : parts.findIndex(p => /^\d+$/.test(p))
+  const id = parts[at]
+  if (!id || !/^\d+$/.test(id)) return null
+  // Unlisted videos carry a hash: `vimeo.com/123/abcdef` or `?h=abcdef`.
+  const hash = url.searchParams.get('h') ?? (parts[at + 1] && /^[\da-f]+$/i.test(parts[at + 1]!) ? parts[at + 1]! : null)
+  const query = new URLSearchParams({ autoplay: '1', dnt: '1' })
+  if (hash) query.set('h', hash)
+  return { provider: 'vimeo', kind: 'video', src: `https://player.vimeo.com/video/${id}?${query}`, href: `https://vimeo.com/${id}${hash ? `/${hash}` : ''}` }
+}
+
+const GOOGLE = new Set(['www.google.com', 'google.com'])
+
+/** Framed as given: the host is known to serve an embeddable page at that address. */
+const FRAMED: Array<[EmbedProvider, EmbedTarget['kind'], (url: URL) => boolean]> = [
+  // Exact hosts only: a pattern over Google's country domains also admits look-alikes (`google.com.evil.example`).
+  ['google-maps', 'map', u => (GOOGLE.has(u.hostname) && u.pathname.startsWith('/maps/embed')) || (u.hostname === 'maps.google.com' && u.searchParams.get('output') === 'embed')],
+  ['openstreetmap', 'map', u => u.hostname === 'www.openstreetmap.org' && u.pathname === '/export/embed.html'],
+  ['spotify', 'audio', u => u.hostname === 'open.spotify.com' && u.pathname.startsWith('/embed/')],
+  ['soundcloud', 'audio', u => u.hostname === 'w.soundcloud.com' && u.pathname.startsWith('/player')],
+  ['calendly', 'widget', u => u.hostname === 'calendly.com'],
+  ['typeform', 'widget', u => /^[\w-]+\.typeform\.com$/.test(u.hostname) && u.pathname.startsWith('/to/')],
+  ['loom', 'video', u => /^(?:www\.)?loom\.com$/.test(u.hostname) && u.pathname.startsWith('/embed/')],
+  ['wistia', 'video', u => u.hostname === 'fast.wistia.net' && u.pathname.startsWith('/embed/')],
+]
+
+/** A video page or player URL, or a known provider's embed address. `null` = not embeddable. */
+export function embedTarget(value: string): EmbedTarget | null {
+  const url = https(value)
+  if (!url) return null
+  const found = youtube(url) ?? vimeo(url)
+  if (found) return found
+  url.protocol = 'https:'
+  for (const [provider, kind, test] of FRAMED) if (test(url)) return { provider, kind, src: url.href, href: url.href }
+  return null
+}
+
+/** A Google map of a place or address (what Elementor's and Divi's map widgets store). */
+export function mapTarget(address: string): EmbedTarget | null {
+  const q = address.trim()
+  if (!q) return null
+  const query = encodeURIComponent(q)
+  return { provider: 'google-maps', kind: 'map', src: `https://www.google.com/maps?q=${query}&output=embed`, href: `https://www.google.com/maps/search/?api=1&query=${query}` }
+}

package/components/embed/fixtures.json

@@ -0,0 +1,34 @@
+[
+  {
+    "name": "youtube-poster",
+    "props": { "url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ&t=1m5s", "title": "A walk through the new studio", "caption": "Filmed in spring, four minutes.", "poster": { "src": "/kit-fixtures/photo-2.svg", "alt": "", "width": 1200, "height": 800 } }
+  },
+  {
+    "name": "vimeo-plain-page",
+    "props": { "url": "https://vimeo.com/76979871", "title": "The making of the journal", "width": "page", "aspect": "video" }
+  },
+  {
+    "name": "shorts-auto-portrait",
+    "props": { "url": "https://youtube.com/shorts/aqz-KE-bpKQ", "title": "One-minute tip" }
+  },
+  {
+    "name": "forced-square",
+    "props": { "url": "https://youtu.be/aqz-KE-bpKQ", "title": "Square cut", "aspect": "square" }
+  },
+  {
+    "name": "forced-portrait",
+    "props": { "url": "https://youtu.be/aqz-KE-bpKQ", "title": "Vertical cut", "aspect": "portrait" }
+  },
+  {
+    "name": "map-address",
+    "props": { "address": "Rua Augusta 100, Lisbon", "title": "Our office", "showLabel": "Show map", "aspect": "map" }
+  },
+  {
+    "name": "spotify-strip",
+    "props": { "url": "https://open.spotify.com/embed/episode/7makk4oTQel546B0PZlDM5", "title": "Episode 12 — Slow travel" }
+  },
+  {
+    "name": "unknown-provider-link",
+    "props": { "url": "https://example.com/widget/42", "title": "Booking calendar" }
+  }
+]