@contentrain/astro-kit 0.35.0 → 0.37.0

package/README.md

@@ -32,6 +32,8 @@ They read its design tokens and pass its gates: `astro check` with the
 | `pagination` | WordPress-style `/page/N/` links | none |
 | `breadcrumb` | Ancestors, then the current page, optional JSON-LD | none |
 | `band` | The styled fallback section: heading, lead, image, a grid of items (figure, title, detail, text, points, link) and buttons, in the measured frame | none |
+| `dialog` | A popup the visitor opens: a button and a modal `<dialog>` with text, buttons and a `form` slot; never opens by itself | a few lines, no dependency |
+| `behavior` | A behavior island: a source widget no component carries (slider, tabs, accordion, counter, toggle, filter, in-page dialog, anchor links, image lightbox), kept as its own markup and wired by one vanilla module; static and readable without it | `_shared/behaviors.ts`, no dependency |
 
 Each component lives in `components/<id>/`:
 

package/catalog.json

@@ -446,6 +446,211 @@
         "actions[].style": "actions[].style"
       }
     },
+    {
+      "id": "behavior",
+      "name": "Behavior",
+      "description": "A behavior island: a source widget no kit component carries (slider, tabs, accordion, counter, toggle, filter, in-page dialog, anchor links), kept as the site's own markup and wired by the kit's one small vanilla module. The markup is a rich-text field the writer has run through its island pass (no style, script, form or overlay; no source data-cr-*; ids prefixed); the data-cr-* attributes on the root come from props only. No script, or a refused selector: the island stays as printed, every item in reading order. Only pages with an island load the module.",
+      "category": "content",
+      "uses": [],
+      "shared": [
+        "Section.astro",
+        "behaviors.ts",
+        "measured.ts",
+        "safe-url.ts",
+        "types.ts"
+      ],
+      "variants": {
+        "tone": {
+          "options": [
+            "default",
+            "muted",
+            "inverse",
+            "accent"
+          ],
+          "default": "default",
+          "description": "Section background."
+        }
+      },
+      "props": {
+        "kind": {
+          "type": "select",
+          "required": true,
+          "content": false,
+          "options": [
+            "disclosure",
+            "tablist",
+            "carousel",
+            "dialog",
+            "countup",
+            "toggle",
+            "filter",
+            "anchor",
+            "lightbox"
+          ],
+          "description": "What the module makes of the markup: disclosure (aria-expanded/aria-controls, details), tablist (role=tab, arrow keys), carousel (a scroll-snap track over the items, previous/next), dialog (an opener and its panel as a modal), countup (numbers count up once in view), toggle (aria-pressed shows/hides), filter (data-filter buttons over the items), anchor (in-page links scroll). lightbox (a link to an image file opens the image in a modal)."
+        },
+        "html": {
+          "type": "richtext",
+          "label": "Content",
+          "description": "The widget's markup as the source rendered it, after the writer's island pass. Editable in Studio as HTML."
+        },
+        "items": {
+          "type": "string",
+          "content": false,
+          "description": "The engine's selector for the items inside the island (slides, counters, filtered cards)."
+        },
+        "title": {
+          "type": "string",
+          "content": false,
+          "description": "A tablist's tab selector, when the source's tabs are not role=tab."
+        },
+        "panel": {
+          "type": "string",
+          "content": false,
+          "description": "A tablist's panel selector, in tab order, when the tabs do not name their panels."
+        },
+        "fact": {
+          "type": "string",
+          "content": false,
+          "description": "The source behavior's fact id; the gates find the island by it (data-cr-fact)."
+        },
+        "previousLabel": {
+          "type": "string",
+          "default": "Previous",
+          "content": false,
+          "description": "Carousel button (ui-strings slider.prev)."
+        },
+        "nextLabel": {
+          "type": "string",
+          "default": "Next",
+          "content": false,
+          "description": "Carousel button (ui-strings slider.next)."
+        },
+        "closeLabel": {
+          "type": "string",
+          "default": "Close",
+          "content": false,
+          "description": "Dialog and lightbox close button (ui-strings dialog.close)."
+        },
+        "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."
+            }
+          }
+        }
+      },
+      "slots": {},
+      "js": "vanilla",
+      "dependencies": {},
+      "sources": {},
+      "files": [
+        "Behavior.astro"
+      ]
+    },
     {
       "id": "breadcrumb",
       "name": "Breadcrumb",
@@ -626,6 +831,11 @@
                 "label": "Image description",
                 "description": "What the image shows, for readers who cannot see it; empty when it is decoration."
               },
+              "icon": {
+                "type": "image",
+                "label": "Icon",
+                "description": "A small image above the title (decoration)."
+              },
               "eyebrow": {
                 "type": "string",
                 "label": "Eyebrow",
@@ -791,6 +1001,7 @@
         "items[].linkLabel": "items[].link_label",
         "items[].image": "items[].image",
         "items[].imageAlt": "items[].image_alt",
+        "items[].icon": "items[].icon",
         "items[].eyebrow": "items[].eyebrow"
       }
     },
@@ -1953,9 +2164,27 @@
           "default": false,
           "content": false,
           "description": "Rendered already open, in the flow of the section and not modal: for previews and visual baselines only, never for a page."
+        },
+        "trigger": {
+          "type": "select",
+          "options": [
+            "click",
+            "load",
+            "exit",
+            "scroll"
+          ],
+          "content": false,
+          "description": "How the source popup opened. Here it always opens by its button, never by itself; the value stays on the root for the gates and the receipt, which say the change."
+        },
+        "fact": {
+          "type": "string",
+          "content": false,
+          "description": "The source behavior's fact id; the gates find the dialog by it (data-cr-fact)."
         }
       },
-      "slots": {},
+      "slots": {
+        "form": "The popup's form, under its text and buttons: the starter's form (Studio) or its link to the form on WordPress."
+      },
       "js": "vanilla",
       "dependencies": {},
       "sources": {
@@ -2369,6 +2598,7 @@
       "category": "section",
       "uses": [],
       "shared": [
+        "KitImage.astro",
         "Section.astro",
         "measured.ts",
         "safe-url.ts",
@@ -2447,6 +2677,11 @@
                   "chat"
                 ],
                 "description": "The kit icon shown with the icon style; check when absent."
+              },
+              "iconImage": {
+                "type": "image",
+                "label": "Icon image",
+                "description": "The feature's own icon as an image file (the old site's icon, moved as an svg): drawn instead of the named icon; the check style ignores it."
               }
             }
           },
@@ -2614,7 +2849,8 @@
         "items": "items",
         "items[].title": "items[].title",
         "items[].text": "items[].text",
-        "items[].icon": "items[].icon"
+        "items[].icon": "items[].icon",
+        "items[].iconImage": "items[].icon_image"
       }
     },
     {

package/components/_shared/behaviors.ts

@@ -0,0 +1,242 @@
+// Behavior islands: the source site's own markup for a widget no kit component carries (a slider, tabs, an
+// accordion, a counter, a filter, an image lightbox), kept as content and made to work again by this one small module. The markup is
+// the content; the behavior is ours: no source library, no jQuery, nothing the source shipped runs.
+//
+// Each island is a root the Behavior component prints: `data-cr-behavior` names the kind, and the item, title and
+// panel selectors come from the engine (`data-cr-items`, `data-cr-title`, `data-cr-panel`), never from the source
+// (the writer strips every `data-cr-*` the source markup carried before it wraps it). The module reads only ARIA,
+// `details`, `hidden` and those attributes.
+//
+// Rules (t13's PR-E checklist §4): text goes in through `textContent` only, never `innerHTML` or its family; no
+// `eval`, `Function`, `fetch` or `location`; every selector is scoped to its island root and run in try/catch (a
+// selector the browser refuses leaves that island static); `init` is idempotent; anything that fails leaves the
+// island as it was printed: readable, every item in reading order. Reduced motion is honoured.
+
+type Kind = 'disclosure' | 'tablist' | 'carousel' | 'dialog' | 'countup' | 'toggle' | 'filter' | 'anchor' | 'lightbox'
+
+const KINDS: ReadonlySet<string> = new Set<Kind>(['disclosure', 'tablist', 'carousel', 'dialog', 'countup', 'toggle', 'filter', 'anchor', 'lightbox'])
+/** Past this many items an island wires the first ones; the rest stay visible as printed (said on the receipt). */
+const MAX_ITEMS = 50
+
+const reduced = (): boolean => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches
+
+/** Elements under the island root for a selector the engine wrote; nothing (never a throw) for a bad selector. */
+function within(root: HTMLElement, selector: string | undefined): HTMLElement[] {
+  if (!selector) return []
+  try { return [...root.querySelectorAll<HTMLElement>(selector)].slice(0, MAX_ITEMS) }
+  catch { return [] }
+}
+
+/** The element an `aria-controls` / `href="#…"` names, looked up inside the island only (ids are island-prefixed). */
+function target(root: HTMLElement, id: string | null): HTMLElement | null {
+  if (!id) return null
+  try { return root.querySelector<HTMLElement>(`#${CSS.escape(id.replace(/^#/, ''))}`) }
+  catch { return null }
+}
+
+function disclosure(root: HTMLElement): void {
+  for (const button of within(root, 'button[aria-expanded][aria-controls], [role="button"][aria-expanded][aria-controls]')) {
+    const panel = target(root, button.getAttribute('aria-controls'))
+    if (!panel) continue
+    const set = (open: boolean) => { button.setAttribute('aria-expanded', String(open)); panel.hidden = !open }
+    set(button.getAttribute('aria-expanded') === 'true')
+    button.addEventListener('click', () => set(button.getAttribute('aria-expanded') !== 'true'))
+  }
+  // `details`/`summary` already open and close in the browser.
+}
+
+function tablist(root: HTMLElement): void {
+  const tabs = within(root, root.dataset.crTitle ?? '[role="tab"]')
+  const panels = tabs.map(tab => target(root, tab.getAttribute('aria-controls')))
+  const fallback = within(root, root.dataset.crPanel)
+  const panelOf = (i: number): HTMLElement | null => panels[i] ?? fallback[i] ?? null
+  if (tabs.length < 2 || tabs.some((_, i) => !panelOf(i))) return
+  const select = (index: number, focus = false) => {
+    tabs.forEach((tab, i) => {
+      const on = i === index
+      tab.setAttribute('role', 'tab')
+      tab.setAttribute('aria-selected', String(on))
+      tab.tabIndex = on ? 0 : -1
+      panelOf(i)!.hidden = !on
+    })
+    if (focus) tabs[index]!.focus()
+  }
+  const first = Math.max(0, tabs.findIndex(tab => tab.getAttribute('aria-selected') === 'true'))
+  select(first)
+  tabs.forEach((tab, i) => {
+    tab.addEventListener('click', (event) => { event.preventDefault(); select(i) })
+    tab.addEventListener('keydown', (event) => {
+      const step = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 }[event.key]
+      if (step) { event.preventDefault(); select((i + step + tabs.length) % tabs.length, true) }
+      else if (event.key === 'Home') { event.preventDefault(); select(0, true) }
+      else if (event.key === 'End') { event.preventDefault(); select(tabs.length - 1, true) }
+    })
+  })
+}
+
+function control(label: string, onClick: () => void): HTMLButtonElement {
+  const button = document.createElement('button')
+  button.type = 'button'
+  button.textContent = label
+  button.className = 'cr-behavior-control'
+  button.addEventListener('click', onClick)
+  return button
+}
+
+function carousel(root: HTMLElement): void {
+  const items = within(root, root.dataset.crItems)
+  const track = items[0]?.parentElement
+  // Past MAX_ITEMS (or other children in the track) the carousel stays static: never squeeze unwired slides into the row.
+  if (items.length < 2 || !track || !items.every(item => item.parentElement === track) || track.children.length !== items.length) return
+  // A scroll-snap track: the browser moves it (swipe, keys, scroll); the buttons only scroll it. No timer: a slider
+  // that advanced by itself on the old site waits for the visitor here (said on the receipt).
+  Object.assign(track.style, { display: 'flex', overflowX: 'auto', scrollSnapType: 'x mandatory', scrollBehavior: reduced() ? 'auto' : 'smooth' })
+  for (const item of items) Object.assign(item.style, { flex: '0 0 100%', scrollSnapAlign: 'start' })
+  track.setAttribute('tabindex', '0')
+  const go = (step: number) => track.scrollBy({ left: step * track.clientWidth })
+  const bar = document.createElement('div')
+  bar.className = 'cr-behavior-controls'
+  bar.append(control(root.dataset.crPrev ?? 'Previous', () => go(-1)), control(root.dataset.crNext ?? 'Next', () => go(1)))
+  track.after(bar)
+}
+
+function dialog(root: HTMLElement): void {
+  for (const opener of within(root, '[aria-haspopup="dialog"][aria-controls]')) {
+    const content = target(root, opener.getAttribute('aria-controls'))
+    if (!content || content.closest('dialog')) continue
+    const box = document.createElement('dialog')
+    box.className = 'cr-behavior-dialog'
+    content.before(box)
+    box.append(content)
+    content.hidden = false
+    box.append(control(root.dataset.crClose ?? 'Close', () => box.close()))
+    opener.addEventListener('click', (event) => { event.preventDefault(); box.showModal() })
+    box.addEventListener('click', (event) => { if (event.target === box) box.close() })
+  }
+}
+
+/** The first text node under `item` holding a number: the digits a counter shows, beside its icon or suffix spans. */
+function digitsOf(item: HTMLElement): { node: Text, digits: string } | null {
+  const walker = document.createTreeWalker(item, NodeFilter.SHOW_TEXT)
+  for (let node = walker.nextNode() as Text | null; node; node = walker.nextNode() as Text | null) {
+    const match = /\d[\d.,]*/.exec(node.data)
+    if (match) return { node, digits: match[0] }
+  }
+  return null
+}
+
+function countup(root: HTMLElement): void {
+  const items = within(root, root.dataset.crItems)
+  if (reduced() || typeof IntersectionObserver !== 'function') return
+  for (const item of items) {
+    const found = digitsOf(item)
+    if (!found) continue
+    const { node, digits } = found
+    const text = node.data
+    const end = Number(digits.replace(/[.,](?=\d{3}\b)/g, '').replace(',', '.'))
+    if (!Number.isFinite(end) || end <= 0) continue
+    const fraction = digits.split(/[.,]/)[1] ?? ''
+    const decimals = fraction.length > 2 ? 0 : fraction.length
+    const seen = new IntersectionObserver((entries) => {
+      if (!entries.some(e => e.isIntersecting)) return
+      seen.disconnect()
+      const start = performance.now()
+      // Only the digits' own text node changes: an icon, a unit or a suffix span beside it stays as printed.
+      const tick = (now: number) => {
+        const t = Math.min(1, (now - start) / 1200)
+        node.data = text.replace(digits, t < 1 ? (end * t).toFixed(decimals) : digits)
+        if (t < 1) requestAnimationFrame(tick)
+      }
+      requestAnimationFrame(tick)
+    })
+    seen.observe(item)
+  }
+}
+
+function toggle(root: HTMLElement): void {
+  for (const button of within(root, 'button[aria-pressed][aria-controls]')) {
+    const panel = target(root, button.getAttribute('aria-controls'))
+    if (!panel) continue
+    const set = (on: boolean) => { button.setAttribute('aria-pressed', String(on)); panel.hidden = !on }
+    set(button.getAttribute('aria-pressed') === 'true')
+    button.addEventListener('click', () => set(button.getAttribute('aria-pressed') !== 'true'))
+  }
+}
+
+/** What an item is filed under: its classes and its `data-category` / `data-filter` words. */
+const tokens = (el: HTMLElement): string[] => `${el.className} ${el.dataset.category ?? ''} ${el.dataset.filter ?? ''}`.split(/[\s,]+/).filter(Boolean)
+
+function filter(root: HTMLElement): void {
+  const items = within(root, root.dataset.crItems)
+  const buttons = within(root, '[data-filter]')
+  if (!items.length || !buttons.length) return
+  for (const button of buttons) {
+    button.addEventListener('click', (event) => {
+      event.preventDefault()
+      const want = (button.dataset.filter ?? '').replace(/^\./, '')
+      for (const b of buttons) b.setAttribute('aria-pressed', String(b === button))
+      for (const item of items) item.hidden = !(want === '' || want === '*' || want === 'all' || tokens(item).includes(want))
+    })
+  }
+}
+
+function anchor(root: HTMLElement): void {
+  for (const link of within(root, 'a[href^="#"]')) {
+    // The island's own (prefixed) target first; the page's only when the island has none.
+    const id = link.getAttribute('href')!.slice(1)
+    const to = target(root, id) ?? (id ? document.getElementById(id) : null)
+    if (!to) continue
+    link.addEventListener('click', (event) => { event.preventDefault(); to.scrollIntoView({ behavior: reduced() ? 'auto' : 'smooth' }) })
+  }
+}
+
+/** A link to an image file, as a source lightbox wrapped one (`a[href$=.jpg] > img`): http(s) or same-site only. */
+function imageHref(link: HTMLAnchorElement): string | null {
+  let url: URL
+  try { url = new URL(link.getAttribute('href') ?? '', document.baseURI) }
+  catch { return null }
+  return (url.protocol === 'https:' || url.protocol === 'http:') && /\.(?:avif|gif|jpe?g|png|webp)$/i.test(url.pathname) ? url.href : null
+}
+
+function lightbox(root: HTMLElement): void {
+  let box: HTMLDialogElement | null = null
+  let image: HTMLImageElement | null = null
+  for (const link of within(root, 'a[href]') as HTMLAnchorElement[]) {
+    const thumb = link.querySelector('img')
+    const href = thumb ? imageHref(link) : null
+    if (!thumb || !href) continue
+    link.addEventListener('click', (event) => {
+      event.preventDefault()
+      if (!box || !image) {
+        box = document.createElement('dialog')
+        box.className = 'cr-behavior-dialog cr-behavior-lightbox'
+        image = document.createElement('img')
+        box.append(image, control(root.dataset.crClose ?? 'Close', () => box!.close()))
+        box.addEventListener('click', (e) => { if (e.target === box) box!.close() })
+        root.append(box)
+      }
+      image.src = href
+      image.alt = thumb.alt
+      box.showModal()
+    })
+  }
+}
+
+const WIRE: Record<Kind, (root: HTMLElement) => void> = { disclosure, tablist, carousel, dialog, countup, toggle, filter, anchor, lightbox }
+
+/** Wires every island on the page once. Safe to call again (a view transition, a second script copy). */
+export function initBehaviors(scope: ParentNode = document): void {
+  for (const root of scope.querySelectorAll<HTMLElement>('[data-cr-behavior]')) {
+    const kind = root.dataset.crBehavior ?? ''
+    // A root inside another root is not ours: the component prints one root per island, so a nested one came with the
+    // markup (a spoofed island the writer's pass would strip). Never wired, so its selectors never run.
+    if (root.dataset.crReady !== undefined || !KINDS.has(kind) || root.parentElement?.closest('[data-cr-behavior]')) continue
+    try {
+      WIRE[kind as Kind](root)
+      root.dataset.crReady = ''
+    }
+    catch {
+      // Left as printed: the content is all there, it just does not move.
+    }
+  }
+}

package/components/behavior/Behavior.astro

@@ -0,0 +1,71 @@
+---
+// A behavior island: a widget of the source site that no kit component carries (a slider, tabs, an accordion, a
+// counter, a filter), kept as the site's own markup and made to work again by the kit's one small module
+// (`_shared/behaviors.ts`). The markup is content, a rich-text field the writer already ran through the island
+// pass (no style element, no script, no form, no overlay, no `data-cr-*` of its own, ids prefixed); the behavior
+// is ours. The `data-cr-*` attributes on the root are the only ones on the page, and they come from these props.
+//
+// With no script, or a selector the browser refuses, the island stays as printed: every item in reading order,
+// nothing hidden. Only a page that has an island loads the module (Astro bundles a component's script once, for the
+// pages that use it).
+import Section from '../_shared/Section.astro'
+import type { MeasuredStyle } from '../_shared/types'
+
+interface Props {
+  /** What the module makes of it. */
+  kind: 'disclosure' | 'tablist' | 'carousel' | 'dialog' | 'countup' | 'toggle' | 'filter' | 'anchor' | 'lightbox'
+  /** The island's markup (rendered HTML of a richtext field, after the writer's island pass). */
+  html?: string | undefined
+  /** The engine's selectors inside the island: the items (slides, counters, filtered cards), a tab's title, a panel. */
+  items?: string | undefined
+  title?: string | undefined
+  panel?: string | undefined
+  /** The source behavior's fact id: the gates find this element by it (`data-cr-fact`). */
+  fact?: string | undefined
+  /** Button labels the module writes (ui-strings slider.prev / slider.next / dialog.close). */
+  previousLabel?: string | undefined
+  nextLabel?: string | undefined
+  closeLabel?: string | undefined
+  tone?: 'default' | 'muted' | 'inverse' | 'accent' | undefined
+  /** The source section's measured style (`MeasuredStyle`). */
+  measured?: MeasuredStyle | undefined
+}
+
+const { kind, html, items, title, panel, fact, previousLabel, nextLabel, closeLabel, tone, measured } = Astro.props
+// Selectors and ids go into attributes only, never into markup or a script; an empty one is left out.
+const attr = (value: string | undefined): string | undefined => (value && value.length <= 300 ? value : undefined)
+const factId = fact && /^[\w:.-]{1,120}$/.test(fact) ? fact : undefined
+---
+{html && (
+  <Section tone={tone} measured={measured}>
+    <div
+      class="cr-behavior"
+      data-cr-behavior={kind}
+      data-cr-items={attr(items)}
+      data-cr-title={attr(title)}
+      data-cr-panel={attr(panel)}
+      data-cr-fact={factId}
+      data-cr-prev={previousLabel}
+      data-cr-next={nextLabel}
+      data-cr-close={closeLabel}
+      set:html={html}
+    />
+  </Section>
+)}
+
+<script>
+  import { initBehaviors } from '../_shared/behaviors'
+
+  initBehaviors()
+  // With Astro's client router a page arrives without a reload: wire its islands too (ready roots are skipped).
+  document.addEventListener('astro:page-load', () => initBehaviors())
+</script>
+
+<style is:global>
+  .cr-behavior-controls { display: flex; gap: 0.5rem; justify-content: center; margin-block-start: 1rem; }
+  .cr-behavior-control { cursor: pointer; border: 1px solid currentColor; border-radius: var(--radius-control, 0.375rem); padding: 0.375rem 0.875rem; background: transparent; }
+  .cr-behavior-control:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px; }
+  .cr-behavior-dialog { margin: auto; max-width: min(92vw, 40rem); max-height: 85dvh; border: 1px solid var(--color-line); border-radius: var(--radius-card, 0.75rem); padding: 1.5rem; }
+  .cr-behavior-dialog::backdrop { background: rgb(0 0 0 / 0.5); }
+  .cr-behavior-lightbox img { display: block; max-width: 100%; max-height: 75dvh; margin-inline: auto; }
+</style>

package/components/behavior/fixtures.json

@@ -0,0 +1,54 @@
+[
+  {
+    "name": "carousel",
+    "props": {
+      "kind": "carousel",
+      "items": ".slide",
+      "fact": "interactive:fx1",
+      "html": "<div class=\"slides\"><div class=\"slide\"><h2>First</h2><p>One of three slides.</p></div><div class=\"slide\"><h2>Second</h2><p>Two of three.</p></div><div class=\"slide\"><h2>Third</h2><p>Three of three.</p></div></div>"
+    }
+  },
+  {
+    "name": "tablist",
+    "props": {
+      "kind": "tablist",
+      "fact": "interactive:fx2",
+      "html": "<div role=\"tablist\"><button role=\"tab\" aria-controls=\"cr-fx2-a\" aria-selected=\"true\">Plans</button><button role=\"tab\" aria-controls=\"cr-fx2-b\">Support</button></div><div id=\"cr-fx2-a\"><p>Every plan includes hosting.</p></div><div id=\"cr-fx2-b\"><p>Support answers within a day.</p></div>"
+    }
+  },
+  {
+    "name": "disclosure",
+    "props": {
+      "kind": "disclosure",
+      "fact": "interactive:fx3",
+      "tone": "muted",
+      "html": "<h2><button aria-expanded=\"false\" aria-controls=\"cr-fx3-a\">Do you ship abroad?</button></h2><div id=\"cr-fx3-a\"><p>Yes, to the whole of Europe.</p></div><details><summary>Can I return an order?</summary><p>Within 30 days.</p></details>"
+    }
+  },
+  {
+    "name": "nested-spoof",
+    "props": {
+      "kind": "disclosure",
+      "fact": "interactive:fx4",
+      "html": "<h2><button aria-expanded=\"true\" aria-controls=\"cr-fx4-a\">Opening hours</button></h2><div id=\"cr-fx4-a\"><p>Monday to Friday.</p><div data-cr-behavior=\"carousel\" data-cr-items=\"body *\"><p>A spoofed inner root: never wired, printed as text.</p></div></div>"
+    }
+  },
+  {
+    "name": "disclosure-inverse",
+    "props": {
+      "kind": "disclosure",
+      "fact": "interactive:fx3",
+      "tone": "inverse",
+      "html": "<h2><button aria-expanded=\"false\" aria-controls=\"cr-fx3-a\">Do you ship abroad?</button></h2><div id=\"cr-fx3-a\"><p>Yes, to the whole of Europe.</p></div><details><summary>Can I return an order?</summary><p>Within 30 days.</p></details>"
+    }
+  },
+  {
+    "name": "disclosure-accent",
+    "props": {
+      "kind": "disclosure",
+      "fact": "interactive:fx3",
+      "tone": "accent",
+      "html": "<h2><button aria-expanded=\"false\" aria-controls=\"cr-fx3-a\">Do you ship abroad?</button></h2><div id=\"cr-fx3-a\"><p>Yes, to the whole of Europe.</p></div><details><summary>Can I return an order?</summary><p>Within 30 days.</p></details>"
+    }
+  }
+]

package/components/behavior/meta.json

@@ -0,0 +1,202 @@
+{
+  "id": "behavior",
+  "name": "Behavior",
+  "description": "A behavior island: a source widget no kit component carries (slider, tabs, accordion, counter, toggle, filter, in-page dialog, anchor links), kept as the site's own markup and wired by the kit's one small vanilla module. The markup is a rich-text field the writer has run through its island pass (no style, script, form or overlay; no source data-cr-*; ids prefixed); the data-cr-* attributes on the root come from props only. No script, or a refused selector: the island stays as printed, every item in reading order. Only pages with an island load the module.",
+  "category": "content",
+  "uses": [],
+  "shared": [
+    "Section.astro",
+    "behaviors.ts",
+    "measured.ts",
+    "safe-url.ts",
+    "types.ts"
+  ],
+  "variants": {
+    "tone": {
+      "options": [
+        "default",
+        "muted",
+        "inverse",
+        "accent"
+      ],
+      "default": "default",
+      "description": "Section background."
+    }
+  },
+  "props": {
+    "kind": {
+      "type": "select",
+      "required": true,
+      "content": false,
+      "options": [
+        "disclosure",
+        "tablist",
+        "carousel",
+        "dialog",
+        "countup",
+        "toggle",
+        "filter",
+        "anchor",
+        "lightbox"
+      ],
+      "description": "What the module makes of the markup: disclosure (aria-expanded/aria-controls, details), tablist (role=tab, arrow keys), carousel (a scroll-snap track over the items, previous/next), dialog (an opener and its panel as a modal), countup (numbers count up once in view), toggle (aria-pressed shows/hides), filter (data-filter buttons over the items), anchor (in-page links scroll). lightbox (a link to an image file opens the image in a modal)."
+    },
+    "html": {
+      "type": "richtext",
+      "label": "Content",
+      "description": "The widget's markup as the source rendered it, after the writer's island pass. Editable in Studio as HTML."
+    },
+    "items": {
+      "type": "string",
+      "content": false,
+      "description": "The engine's selector for the items inside the island (slides, counters, filtered cards)."
+    },
+    "title": {
+      "type": "string",
+      "content": false,
+      "description": "A tablist's tab selector, when the source's tabs are not role=tab."
+    },
+    "panel": {
+      "type": "string",
+      "content": false,
+      "description": "A tablist's panel selector, in tab order, when the tabs do not name their panels."
+    },
+    "fact": {
+      "type": "string",
+      "content": false,
+      "description": "The source behavior's fact id; the gates find the island by it (data-cr-fact)."
+    },
+    "previousLabel": {
+      "type": "string",
+      "default": "Previous",
+      "content": false,
+      "description": "Carousel button (ui-strings slider.prev)."
+    },
+    "nextLabel": {
+      "type": "string",
+      "default": "Next",
+      "content": false,
+      "description": "Carousel button (ui-strings slider.next)."
+    },
+    "closeLabel": {
+      "type": "string",
+      "default": "Close",
+      "content": false,
+      "description": "Dialog and lightbox close button (ui-strings dialog.close)."
+    },
+    "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."
+        }
+      }
+    }
+  },
+  "slots": {},
+  "js": "vanilla",
+  "dependencies": {},
+  "sources": {}
+}

package/components/card-grid/CardGrid.astro

@@ -42,6 +42,8 @@ interface Item {
   /** The image's address (or, until 0.7, an `ImageInput`). */
   image?: ImageSource | undefined
   imageAlt?: string | undefined
+  /** A small image (an icon) above the title: decoration, so it has no alt (an icon box's svg, a feature's mark). */
+  icon?: string | undefined
   eyebrow?: string | undefined
 }
 
@@ -79,6 +81,7 @@ const headingId = title ? `cards-${title.toLowerCase().replace(/[^a-z0-9]+/g, '-
     {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>}
+        {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()}>
           {item.href && !item.linkLabel

package/components/card-grid/fixtures.json

@@ -4,5 +4,6 @@
   { "name": "four-elevated-inverse", "props": { "columns": "4", "style": "elevated", "tone": "inverse", "headingLevel": 3, "title": "Team", "items": [{ "title": "Mira Kovač", "text": "Editor", "image": { "src": "/kit-fixtures/avatar-1.svg", "alt": "Mira Kovač", "width": 96, "height": 96 } }, { "title": "Jon Ade", "text": "Engineer", "image": { "src": "/kit-fixtures/avatar-2.svg", "alt": "Jon Ade", "width": 96, "height": 96 } }, { "title": "Lea Park", "text": "Designer", "image": { "src": "/kit-fixtures/avatar-3.svg", "alt": "Lea Park", "width": 96, "height": 96 } }, { "title": "Sam Ortiz", "text": "Producer" }] } },
   { "name": "accent", "props": { "tone": "accent", "columns": "3", "items": [{ "title": "Fast", "text": "Static HTML, one stylesheet." }, { "title": "Editable", "text": "Content in Contentrain Studio." }, { "title": "Kept", "text": "Every address survives." }] } },
   {"name": "measured-columns", "props": {"title": "Services", "measured": {"containerPx": 1140, "padY": 80, "columns": {"390": 1, "768": 2, "1280": 4}, "gap": 30, "radius": 4, "bg": {"color": "#f4f1ea"}}, "items": [{"title": "Audits", "text": "Where a site loses readers."}, {"title": "Builds", "text": "Static and fast."}, {"title": "Hosting", "text": "Managed for you."}, {"title": "Care", "text": "Kept up to date."}]}},
+  {"name": "icon-boxes", "props": {"columns": "3", "align": "center", "items": [{"title": "Design", "text": "Layouts built around your products.", "icon": "/kit-fixtures/icon-1.svg"}, {"title": "Build", "text": "Fast pages that stay fast.", "icon": "/kit-fixtures/icon-1.svg"}, {"title": "Grow", "text": "Monthly reports you can read in five minutes.", "icon": "/kit-fixtures/icon-1.svg"}]}},
   {"name": "link-labels", "props": {"columns": "4", "align": "center", "items": [{"title": "Kasko", "href": "/urunlerimiz/kasko/", "linkLabel": "Teklif Al"}, {"title": "Trafik Sigortası", "href": "/urunlerimiz/trafik-sigortasi/", "linkLabel": "Teklif Al"}, {"title": "Konut Sigortası", "href": "/urunlerimiz/konut-sigortasi/", "linkLabel": "Teklif Al"}, {"title": "Tamamlayıcı Sağlık"}]}}
 ]

package/components/card-grid/meta.json

@@ -99,6 +99,11 @@
             "label": "Image description",
             "description": "What the image shows, for readers who cannot see it; empty when it is decoration."
           },
+          "icon": {
+            "type": "image",
+            "label": "Icon",
+            "description": "A small image above the title (decoration)."
+          },
           "eyebrow": {
             "type": "string",
             "label": "Eyebrow",

package/components/dialog/Dialog.astro

@@ -1,6 +1,6 @@
 ---
-// A popup, as a dialog the visitor opens: a button in a section of the page and a modal <dialog> with a heading, text
-// and buttons. Replaces Elementor popups and Popup Maker overlays. Never opens by itself (no timers, no exit intent):
+// A popup, as a dialog the visitor opens: a button in a section of the page and a modal <dialog> with a heading, text,
+// buttons and, in its `form` slot, the popup's form. Replaces Elementor popups and Popup Maker overlays. Never opens by itself (no timers, no exit intent):
 // content that a source popup showed on load or on scroll is reachable from the button instead, and sits in the HTML
 // for crawlers. The section is the kit's (Section: tone, spacing, measured style), like every other section.
 //
@@ -62,9 +62,17 @@ interface Props {
   measured?: MeasuredStyle | undefined
   /** Rendered already open, in the flow of the section and not modal: for previews and visual baselines only, never for a page. */
   open?: boolean | undefined
+  /**
+   * How the source popup opened (`load`, `exit`, `scroll`: by itself; `click`: by its trigger). Here it always opens by
+   * the button, never by itself; the value is kept on the root for the gates and the receipt, which say the change.
+   */
+  trigger?: 'click' | 'load' | 'exit' | 'scroll' | undefined
+  /** The source behavior's fact id: the gates find the dialog by it (`data-cr-fact`). */
+  fact?: string | undefined
 }
 
-const { id: givenId = 'dialog', triggerLabel, heading, html, actions = [], closeLabel = 'Close', triggerStyle, size, align: given, tone, measured, open = false } = Astro.props
+const { id: givenId = 'dialog', triggerLabel, heading, html, actions = [], closeLabel = 'Close', triggerStyle, size, align: given, tone, measured, open = false, trigger, fact } = Astro.props
+const factId = fact && /^[\w:.-]{1,120}$/.test(fact) ? fact : undefined
 // The id goes into attributes and into the scripting-off style sheet, so it is a plain token or the default.
 const id = /^[A-Za-z][\w-]*$/.test(givenId) ? givenId : 'dialog'
 const align = given ?? measured?.align
@@ -80,7 +88,7 @@ const invoker = { command: 'show-modal', commandfor: id }
 const noscript = `<style>[data-kit-dialog="${id}"]>[data-kit-dialog-open],#${id} form[method=dialog]{display:none}#${id}:not([open]){display:block;position:static;margin:0;width:100%;max-width:none;max-height:none;box-shadow:none}</style>`
 ---
 <Section measured={measured} tone={tone} spacing="md" id={`${id}-section`}>
-  <div class={s.root()} data-kit-dialog={id}>
+  <div class={s.root()} data-kit-dialog={id} data-kit-trigger={trigger} data-cr-fact={factId}>
     <noscript set:html={noscript} />
     <button type="button" class={s.trigger()} data-kit-dialog-open aria-haspopup="dialog" {...invoker}>{triggerLabel}</button>
     <dialog id={id} class={s.box()} open={open || undefined} aria-labelledby={heading ? headingId : undefined} aria-label={heading ? undefined : triggerLabel}>
@@ -88,6 +96,8 @@ const noscript = `<style>[data-kit-dialog="${id}"]>[data-kit-dialog-open],#${id}
         {heading && <h2 id={headingId} class={s.heading()}>{heading}</h2>}
         {html && <Prose html={html} searchable={false} />}
         {actions.length > 0 && <div class={s.actions()}>{actions.map(action => <Button action={action} />)}</div>}
+        {/* The popup's form (a source popup often held the contact or newsletter form): the starter's form, or its link to the form on WordPress. */}
+        {Astro.slots.has('form') && <div data-kit-dialog-form><slot name="form" /></div>}
       </div>
       <form method="dialog">
         <button type="submit" class={s.close()} aria-label={closeLabel}>

package/components/dialog/meta.json

@@ -235,9 +235,27 @@
       "default": false,
       "content": false,
       "description": "Rendered already open, in the flow of the section and not modal: for previews and visual baselines only, never for a page."
+    },
+    "trigger": {
+      "type": "select",
+      "options": [
+        "click",
+        "load",
+        "exit",
+        "scroll"
+      ],
+      "content": false,
+      "description": "How the source popup opened. Here it always opens by its button, never by itself; the value stays on the root for the gates and the receipt, which say the change."
+    },
+    "fact": {
+      "type": "string",
+      "content": false,
+      "description": "The source behavior's fact id; the gates find the dialog by it (data-cr-fact)."
     }
   },
-  "slots": {},
+  "slots": {
+    "form": "The popup's form, under its text and buttons: the starter's form (Studio) or its link to the form on WordPress."
+  },
   "js": "vanilla",
   "dependencies": {},
   "sources": {

package/components/feature-list/FeatureList.astro

@@ -2,6 +2,7 @@
 // A list of short features — a title and a line of text each — marked with
 // the feature's icon or a shared check, under an optional heading and intro.
 import { tv } from 'tailwind-variants'
+import KitImage from '../_shared/KitImage.astro'
 import Section, { type Tone } from '../_shared/Section.astro'
 import { measuredGrid } from '../_shared/measured'
 import type { MeasuredStyle } from '../_shared/types'
@@ -51,6 +52,8 @@ interface Item {
   text?: string | undefined
   /** A kit icon name (check, star, bolt, shield, heart, globe, clock, chat). */
   icon?: string | undefined
+  /** The feature's own icon as an image file (a site's svg): drawn instead of the named icon, except by `check`. */
+  iconImage?: string | undefined
 }
 
 interface Props {
@@ -74,6 +77,8 @@ const { heading, intro, items, columns, style = 'icon', tone, bare = false, titl
 const s = list({ columns, style, tone, bare })
 const headingId = heading && id ? `${id}-title` : undefined
 const pathOf = (item: Item) => (style !== 'check' && item.icon && icons[item.icon]) || icons.check
+// The feature's own image icon, where the style shows each feature's own mark.
+const imageOf = (item: Item) => (style !== 'check' && item.iconImage) || undefined
 // A plain list's items are not headings; otherwise one level under the section heading, or the section's when there is none.
 const Title = style === 'list' ? 'span' : bare ? `h${titleLevel}` as 'h3' : heading ? 'h3' : 'h2'
 ---
@@ -83,7 +88,9 @@ const Title = style === 'list' ? 'span' : bare ? `h${titleLevel}` as 'h3' : head
       {items.map(item => (
         <li class={s.item()}>
           <span class={s.mark()} aria-hidden="true">
-            <svg viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d={pathOf(item)} /></svg>
+            {imageOf(item)
+              ? <KitImage image={{ src: imageOf(item)!, alt: '' }} class="size-5 object-contain" />
+              : <svg viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d={pathOf(item)} /></svg>}
           </span>
           <div>
             <Title class={s.title()}>{item.title}</Title>
@@ -105,7 +112,9 @@ const Title = style === 'list' ? 'span' : bare ? `h${titleLevel}` as 'h3' : head
     {items.map(item => (
       <li class={s.item()}>
         <span class={s.mark()} aria-hidden="true">
-          <svg viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d={pathOf(item)} /></svg>
+          {imageOf(item)
+            ? <KitImage image={{ src: imageOf(item)!, alt: '' }} class="size-5 object-contain" />
+            : <svg viewBox="0 0 24 24" class="size-5" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d={pathOf(item)} /></svg>}
         </span>
         <div>
           <Title class={s.title()}>{item.title}</Title>

package/components/feature-list/fixtures.json

@@ -151,5 +151,6 @@
       "style": "list"
     }
   },
+  {"name": "list-icon-images", "props": {"heading": "In the package", "style": "list", "items": [{"title": "A design built around your products", "iconImage": "/kit-fixtures/icon-1.svg"}, {"title": "Checkout with cards and wallets", "iconImage": "/kit-fixtures/icon-1.svg"}, {"title": "Thirty days of launch support", "icon": "chat"}]}},
   {"name": "measured-gap", "props": {"heading": "Why us", "measured": {"columns": {"390": 1, "768": 2, "1280": 3}, "gap": 16}, "items": [{"title": "Fast", "text": "Static HTML."}, {"title": "Kept", "text": "Every address survives."}, {"title": "Editable", "text": "Content in Studio."}]}}
 ]

package/components/feature-list/meta.json

@@ -5,6 +5,7 @@
   "category": "section",
   "uses": [],
   "shared": [
+    "KitImage.astro",
     "Section.astro",
     "measured.ts",
     "safe-url.ts",
@@ -83,6 +84,11 @@
               "chat"
             ],
             "description": "The kit icon shown with the icon style; check when absent."
+          },
+          "iconImage": {
+            "type": "image",
+            "label": "Icon image",
+            "description": "The feature's own icon as an image file (the old site's icon, moved as an svg): drawn instead of the named icon; the check style ignores it."
           }
         }
       },

package/package.json

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