@wippy-fe/webcomponent-core 0.0.6

package/README.md

@@ -0,0 +1,202 @@
+# @wippy-fe/webcomponent-core
+
+Framework-agnostic base class for building Wippy web components. Handles the boilerplate every component needs — shadow DOM, CSS loading, schema-driven prop parsing, ElementInternals state, and lifecycle events — so your subclass only deals with framework-specific mounting.
+
+## What it does
+
+- **Shadow DOM setup** with configurable mode (`open`/`closed`) and container `<div>`
+- **Host CSS inheritance** — loads Wippy platform CSS into the shadow root so the component matches the host theme
+- **Inline CSS injection** — injects component-specific styles from `?inline` imports
+- **Schema-driven prop parsing** — reads `wippy.props` from package.json and auto-converts attributes to typed JS values
+- **ElementInternals** — manages `loading` → `ready` / `error` states
+- **Lifecycle hooks** — `onInit`, `onMount`, `onReady`, `onError`, `onUnmount`, `onPropsChanged`
+- **Lifecycle events** — emits `load`, `unload`, `error` as CustomEvents that cross shadow boundaries
+- **Icon registration** — calls `addIcons(addCollection)` from `@wippy-fe/proxy`
+
+## What it does NOT do
+
+- Any framework setup (Vue, React, Svelte, etc.) — that's for framework-specific packages like `@wippy-fe/webcomponent-vue`
+- Component registration — use `define(import.meta.url, YourElement)` from this package
+- State management — the base class is stateless; your framework layer manages state
+
+## CSS: How Styling Works in Shadow DOM
+
+Shadow DOM blocks style inheritance from the host page. A web component must explicitly bring in any styles it needs. There are two mechanisms:
+
+### Inline CSS (`inlineCss`)
+
+Your component's **own** styles — Tailwind utilities, custom classes, layout rules. Bundled at build time via Vite's `?inline` import and injected **synchronously** into the shadow root before mount.
+
+```ts
+import stylesText from './styles.css?inline'
+
+static get wippyConfig() {
+  return {
+    propsSchema: pkg.wippy.props,
+    inlineCss: stylesText,  // your component's CSS, injected immediately
+  }
+}
+```
+
+Every component with its own stylesheet needs this.
+
+### Host CSS Inheritance (`hostCssKeys`)
+
+Shared **platform CSS** loaded at runtime from the Wippy host into the shadow root. This is how your component inherits the host app's look-and-feel. Loaded **asynchronously** (non-blocking — the component becomes interactive before CSS finishes loading).
+
+| Key | What it provides | When to include |
+|-----|-----------------|-----------------|
+| `fontCssUrl` | Platform font definitions | Almost always — skip only if using fully custom fonts |
+| `themeConfigUrl` | CSS custom properties (color scales, spacing, radii, etc.) matching the host theme | **Recommended for all components.** This is what makes your component look consistent with the host. At dev time, a local `theme-config.css` provides fallback values; at runtime the host injects the real theme. |
+| `primeVueCssUrl` | PrimeVue component classes (`p-button`, `p-input`, etc.) in unstyled mode, styled to match the host | **Include if using any PrimeVue components** (buttons, forms, tables, etc.). Skip only for fully custom UI with zero PrimeVue usage. |
+| `markdownCssUrl` | Styles for rendered markdown blocks | **Include only if rendering markdown.** |
+| `iframeCssUrl` | Scrollbar styling and iframe-related styles | **Recommended for all components** so scrollbars match the host. |
+
+**Choose what your component actually uses:**
+
+```ts
+// Standard component using PrimeVue UI (most common)
+hostCssKeys: ['fontCssUrl', 'themeConfigUrl', 'primeVueCssUrl', 'iframeCssUrl']
+
+// Also renders markdown content
+hostCssKeys: ['fontCssUrl', 'themeConfigUrl', 'primeVueCssUrl', 'markdownCssUrl', 'iframeCssUrl']
+
+// Minimal: just theme variables, no PrimeVue
+hostCssKeys: ['fontCssUrl', 'themeConfigUrl', 'iframeCssUrl']
+
+// Fully self-styled, no host inheritance
+hostCssKeys: []
+```
+
+Default (when omitted): all five keys.
+
+> **Note on dev-time duplication:** Your component's `styles.css` may import `theme-config.css` for local dev (so Tailwind/PostCSS can resolve theme variables). At runtime, the host provides the real theme via `themeConfigUrl`. This duplication is a known trade-off — the host's runtime values take precedence.
+
+## API Reference
+
+### `WippyElement` (abstract class)
+
+Extend this class and implement the hooks you need.
+
+#### Static getters to override
+
+```ts
+static get wippyConfig(): WippyElementConfig
+```
+
+Returns the component configuration. **Must be overridden** — the default returns an empty schema.
+
+```ts
+static get observedAttributes(): string[]
+```
+
+Automatically derived from `wippyConfig.propsSchema.properties` + `extraObservedAttributes`. You rarely need to override this.
+
+#### Lifecycle hooks
+
+All hooks are optional except `onMount` and `onUnmount` (abstract).
+
+| Hook | When it runs | Use case |
+|------|-------------|----------|
+| `onInit(shadow)` | After shadow DOM attached, before CSS/container | Add extra DOM elements, configure shadow root |
+| `onMount(shadow, container, props, errors)` | After CSS, container, icons, and props are ready | **Abstract.** Mount your framework here |
+| `onReady()` | After internals state → `ready`, before `load` event | Post-mount logic, telemetry, deferred setup |
+| `onError(error)` | When `connectedCallback` throws | Custom error reporting (default: `console.error`) |
+| `onUnmount()` | During `disconnectedCallback` | **Abstract.** Tear down framework |
+| `onPropsChanged(props, errors)` | When observed attributes change | Push new values into framework reactivity |
+
+**Full lifecycle order:**
+1. Shadow DOM attached (`open` or `closed`)
+2. `onInit(shadow)`
+3. Inline CSS injected (sync)
+4. Host CSS loading started (async, non-blocking)
+5. Container `<div>` created and appended
+6. Icons registered
+7. Props parsed from attributes
+8. `onMount(shadow, container, props, errors)`
+9. Internals state → `ready`
+10. `onReady()`
+11. `load` event emitted
+
+On error: `onError(error)` → state → `error` → `error` event
+On disconnect: `onUnmount()` → `unload` event → states cleared
+
+#### Utility
+
+```ts
+protected emitEvent(eventName: string, detail?: unknown): void
+```
+
+Dispatches a `CustomEvent` with `bubbles: true, composed: true`.
+
+### `define(importMetaUrl, ComponentClass)`
+
+Re-exported from `@wippy-fe/proxy`. Registers the custom element if the import URL contains a `declare-tag` parameter.
+
+### `parseProps(element, schema)`
+
+Parses all attributes on an element according to a `WippyPropsSchema`. Returns `{ props, errors }`.
+
+### `loadHostCss(shadow, keys?)`
+
+Loads host CSS URLs into a shadow root. Non-blocking (returns a Promise).
+
+### `injectInlineCss(shadow, text)`
+
+Injects a `<style>` element with the given CSS text into the shadow root. Synchronous.
+
+### `attrToCamel(attr)`
+
+Converts kebab-case (`allowed-types`) to camelCase (`allowedTypes`).
+
+## Types
+
+```ts
+interface WippyElementConfig {
+  propsSchema: WippyPropsSchema
+  shadowMode?: 'open' | 'closed'          // default: 'open'
+  hostCssKeys?: HostCssKey[]               // default: font + theme + primeVue + markdown
+  inlineCss?: string
+  containerClasses?: string[]              // default: none
+  extraObservedAttributes?: string[]
+}
+
+interface WippyPropsSchema {
+  type?: string
+  properties: Record<string, WippyPropDefinition>
+}
+
+interface WippyPropDefinition {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object'
+  default?: unknown
+  description?: string
+  items?: { type: string }
+}
+
+type HostCssKey = 'fontCssUrl' | 'themeConfigUrl' | 'primeVueCssUrl' | 'markdownCssUrl' | 'iframeCssUrl'
+```
+
+## Migration from monolithic pattern
+
+**Before** — 170+ lines of boilerplate in every component:
+```ts
+class MyElement extends HTMLElement {
+  // Manual shadow DOM, CSS loading, prop parsing, Vue setup, ...
+}
+```
+
+**After** — extend `WippyElement` (or `WippyVueElement` for Vue components):
+```ts
+class MyElement extends WippyElement {
+  static get wippyConfig() {
+    return {
+      propsSchema: pkg.wippy.props,
+      hostCssKeys: ['fontCssUrl', 'themeConfigUrl', 'primeVueCssUrl', 'iframeCssUrl'],
+      containerClasses: ['h-full'],
+      inlineCss: stylesText,
+    }
+  }
+  onMount(shadow, container, props, errors) { /* framework setup */ }
+  onUnmount() { /* cleanup */ }
+}
+```

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@wippy-fe/webcomponent-core",
+  "version": "0.0.6",
+  "description": "Framework-agnostic base class for Wippy web components — shadow DOM, CSS loading, schema-driven prop parsing, and lifecycle management.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src/",
+    "package.json"
+  ],
+  "peerDependencies": {
+    "@wippy-fe/proxy": "^0.0.6",
+    "@iconify/vue": "^5.0.0"
+  },
+  "license": "UNLICENSED"
+}

package/src/base-element.ts

@@ -0,0 +1,212 @@
+import { addIcons, define } from '@wippy-fe/proxy'
+import { addCollection } from '@iconify/vue'
+import { loadHostCss, injectInlineCss } from './css-loader.ts'
+import { parseProps } from './prop-parser.ts'
+import type { WippyElementConfig } from './types.ts'
+
+/**
+ * Abstract base class for Wippy web components.
+ *
+ * Generic over `Props` — the parsed prop object type. This types `onMount`,
+ * `onPropsChanged`, and `validateProps`. Defaults to `Record<string, unknown>`.
+ *
+ * Lifecycle order:
+ *   1. shadow DOM attached
+ *   2. `onInit(shadow)` — hook for early shadow DOM customization
+ *   3. inline CSS injected
+ *   4. host CSS loading started (async, non-blocking)
+ *   5. container div created and appended
+ *   6. icons registered
+ *   7. props parsed from attributes + custom validation
+ *   8. `onMount(shadow, container, props, errors)` — framework setup
+ *   9. internals state → ready
+ *  10. `onReady()` — post-mount hook
+ *  11. `load` event emitted
+ *
+ * On error: `onError(error)` → internals state → error → `error` event
+ * On disconnect: `onUnmount()` → `unload` event → internals cleared
+ */
+export abstract class WippyElement<Props = Record<string, unknown>> extends HTMLElement {
+  private _internals!: ElementInternals
+  private _contentObserver: MutationObserver | null = null
+
+  /**
+   * Override to provide the component's configuration.
+   * Must be static because `observedAttributes` reads it before construction.
+   *
+   * Specify the generic to get typed `validateProps`:
+   * ```ts
+   * static get wippyConfig(): WippyElementConfig<MyProps> { ... }
+   * ```
+   */
+  static get wippyConfig(): WippyElementConfig {
+    return { propsSchema: { properties: {} } }
+  }
+
+  /**
+   * Derived from the props schema + any `extraObservedAttributes`.
+   */
+  static get observedAttributes(): string[] {
+    const config = this.wippyConfig
+    const schemaAttrs = Object.keys(config.propsSchema.properties)
+    const extra = config.extraObservedAttributes ?? []
+    return [...schemaAttrs, ...extra]
+  }
+
+  constructor() {
+    super()
+    this._internals = this.attachInternals()
+  }
+
+  /**
+   * Emit a CustomEvent that bubbles and crosses shadow DOM boundaries.
+   */
+  protected emitEvent(eventName: string, detail?: unknown): void {
+    this.dispatchEvent(new CustomEvent(eventName, {
+      bubbles: true,
+      composed: true,
+      detail,
+    }))
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────
+
+  connectedCallback(): void {
+    this._internals.states.add('loading')
+    try {
+      const config = (this.constructor as typeof WippyElement).wippyConfig
+
+      // 1. Shadow DOM (guard against reconnect — attachShadow throws if called twice)
+      const shadow = this.shadowRoot ?? this.attachShadow({ mode: config.shadowMode ?? 'open' })
+
+      // 2. Early hook — customize shadow before CSS/container
+      this.onInit(shadow)
+
+      // 3. Inline CSS
+      if (config.inlineCss) {
+        injectInlineCss(shadow, config.inlineCss)
+      }
+
+      // 4. Host CSS (async, non-blocking)
+      if (config.hostCssKeys === undefined || config.hostCssKeys.length > 0) {
+        loadHostCss(shadow, config.hostCssKeys)
+      }
+
+      // 5. Container
+      const container = document.createElement('div')
+      const classes = config.containerClasses ?? []
+      if (classes.length > 0) {
+        container.classList.add(...classes)
+      }
+      shadow.appendChild(container)
+
+      // 6. Icons
+      addIcons(addCollection)
+
+      // 7. Parse initial props + custom validation
+      const { props, errors } = parseProps(this, config.propsSchema)
+      if (config.validateProps) {
+        errors.push(...config.validateProps(props))
+      }
+      const typedProps = props as Props
+
+      // 7b. Extract children content (if contentTemplate configured)
+      let initialContent: string | null = null
+      if (config.contentTemplate) {
+        initialContent = this._extractContent(config.contentTemplate)
+        this._contentObserver = new MutationObserver(() => {
+          const content = this._extractContent(config.contentTemplate!)
+          this.onContentChanged(content)
+        })
+        this._contentObserver.observe(this, {
+          childList: true,
+          characterData: true,
+          subtree: true,
+        })
+      }
+
+      // 8. Framework mount
+      this.onMount(shadow, container, typedProps, errors, initialContent)
+
+      // 9. Ready
+      this._internals.states.delete('loading')
+      this._internals.states.add('ready')
+
+      // 10. Post-mount hook
+      this.onReady()
+
+      // 11. Emit load
+      this.emitEvent('load')
+    } catch (error) {
+      this.onError(error)
+      this._internals.states.delete('loading')
+      this._internals.states.add('error')
+      this.emitEvent('error', {
+        message: error instanceof Error ? error.message : String(error),
+        error,
+      })
+    }
+  }
+
+  disconnectedCallback(): void {
+    if (this._contentObserver) {
+      this._contentObserver.disconnect()
+      this._contentObserver = null
+    }
+    this.onUnmount()
+    this.emitEvent('unload')
+    this._internals.states.clear()
+  }
+
+  attributeChangedCallback(_name: string, oldVal: string | null, newVal: string | null): void {
+    if (oldVal === newVal) return
+    const config = (this.constructor as typeof WippyElement).wippyConfig
+    const { props, errors } = parseProps(this, config.propsSchema)
+    if (config.validateProps) {
+      errors.push(...config.validateProps(props))
+    }
+    this.onPropsChanged(props as Props, errors)
+  }
+
+  // ── Hooks ──────────────────────────────────────────────────
+
+  /** Called right after shadow DOM is attached, before CSS or container. */
+  protected onInit(_shadow: ShadowRoot): void {}
+
+  /** Called once after shadow DOM, CSS, and container are ready. Mount your framework here. */
+  protected abstract onMount(
+    shadow: ShadowRoot,
+    container: HTMLElement,
+    initialProps: Props,
+    initialErrors: string[],
+    initialContent?: string | null,
+  ): void
+
+  /** Called after internals state is set to ready, before the `load` event. */
+  protected onReady(): void {}
+
+  /** Called when connectedCallback throws. Default logs to console. */
+  protected onError(error: unknown): void {
+    console.error(`${this.constructor.name} initialization failed:`, error)
+  }
+
+  /** Called during disconnectedCallback — clean up framework resources. */
+  protected abstract onUnmount(): void
+
+  /** Called when observed attributes change. Override to update framework state. */
+  protected onPropsChanged(_props: Props, _errors: string[]): void {}
+
+  /**
+   * Extract text from a child `<template data-type="...">` element.
+   * Uses `.content.textContent` since `<template>` stores content in a DocumentFragment.
+   */
+  private _extractContent(dataType: string): string | null {
+    const tpl = this.querySelector(`template[data-type="${dataType}"]`) as HTMLTemplateElement | null
+    return tpl?.content.textContent?.trim() ?? null
+  }
+
+  /** Called when child `<template>` content changes. Override to update framework state. */
+  protected onContentChanged(_content: string | null): void {}
+}
+
+export { define }

package/src/css-loader.ts

@@ -0,0 +1,39 @@
+import { hostCss, loadCss } from '@wippy-fe/proxy'
+import type { HostCssKey } from './types.ts'
+
+const DEFAULT_HOST_CSS_KEYS: HostCssKey[] = [
+  'fontCssUrl',
+  'themeConfigUrl',
+  'primeVueCssUrl',
+  'markdownCssUrl',
+  'iframeCssUrl',
+]
+
+/**
+ * Loads host CSS URLs into the shadow root as `<style>` elements.
+ * Non-blocking — returns a promise but the component doesn't need to await it.
+ */
+export function loadHostCss(shadow: ShadowRoot, keys?: HostCssKey[]): Promise<void> {
+  const cssKeys = keys ?? DEFAULT_HOST_CSS_KEYS
+  return Promise.all(
+    cssKeys.map((key) => loadCss(hostCss[key])),
+  ).then((cssChunks) => {
+    for (const css of cssChunks) {
+      const style = document.createElement('style')
+      style.textContent = css
+      style.setAttribute('role', '@wippy/host-css')
+      shadow.appendChild(style)
+    }
+  }).catch((err) => {
+    console.warn('Failed to load host CSS:', err)
+  })
+}
+
+/**
+ * Injects inline CSS text into the shadow root.
+ */
+export function injectInlineCss(shadow: ShadowRoot, text: string): void {
+  const style = document.createElement('style')
+  style.textContent = text
+  shadow.appendChild(style)
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { WippyElement, define } from './base-element.ts'
+export { loadHostCss, injectInlineCss } from './css-loader.ts'
+export { parseProps, attrToCamel } from './prop-parser.ts'
+export type {
+  WippyElementConfig,
+  WippyPropsSchema,
+  WippyPropDefinition,
+  HostCssKey,
+} from './types.ts'
+export type { ParseResult } from './prop-parser.ts'

package/src/prop-parser.ts

@@ -0,0 +1,87 @@
+import type { WippyPropsSchema, WippyPropDefinition } from './types.ts'
+
+export interface ParseResult {
+  props: Record<string, unknown>
+  errors: string[]
+}
+
+/**
+ * Converts a kebab-case attribute name to camelCase.
+ * `allowed-types` → `allowedTypes`
+ */
+export function attrToCamel(attr: string): string {
+  return attr.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())
+}
+
+/**
+ * Parses a single attribute value according to its schema definition.
+ */
+function parseValue(attr: string, raw: string, def: WippyPropDefinition): { value: unknown; error?: string } {
+  switch (def.type) {
+    case 'string':
+      return { value: raw }
+
+    case 'number': {
+      const n = parseFloat(raw)
+      if (isNaN(n)) return { value: undefined, error: `Invalid ${attr}: expected a number` }
+      return { value: n }
+    }
+
+    case 'integer': {
+      const n = parseInt(raw, 10)
+      if (isNaN(n)) return { value: undefined, error: `Invalid ${attr}: expected an integer` }
+      return { value: n }
+    }
+
+    case 'boolean':
+      // Presence of the attribute means true (HTML convention), explicit "false" means false
+      return { value: raw !== 'false' }
+
+    case 'array':
+    case 'object': {
+      try {
+        const parsed = JSON.parse(raw)
+        if (def.type === 'array' && !Array.isArray(parsed)) {
+          return { value: undefined, error: `Invalid ${attr}: expected a JSON array` }
+        }
+        return { value: parsed }
+      } catch {
+        return { value: undefined, error: `Invalid ${attr}: must be valid JSON` }
+      }
+    }
+
+    default:
+      return { value: raw }
+  }
+}
+
+/**
+ * Parses all attributes on an element according to its props schema.
+ * Returns `{ props, errors }` where errors is an array of human-readable messages.
+ */
+export function parseProps(element: HTMLElement, schema: WippyPropsSchema): ParseResult {
+  const props: Record<string, unknown> = {}
+  const errors: string[] = []
+
+  for (const [attr, def] of Object.entries(schema.properties)) {
+    const raw = element.getAttribute(attr)
+    const camel = attrToCamel(attr)
+
+    if (raw === null) {
+      // Attribute not set — use default if available
+      if (def.default !== undefined) {
+        props[camel] = def.default
+      }
+      continue
+    }
+
+    const result = parseValue(attr, raw, def)
+    if (result.error) {
+      errors.push(result.error)
+    } else {
+      props[camel] = result.value
+    }
+  }
+
+  return { props, errors }
+}

package/src/types.ts

@@ -0,0 +1,131 @@
+/**
+ * JSON-Schema-style property descriptor used for attribute→prop parsing.
+ */
+export interface WippyPropDefinition {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object'
+  default?: unknown
+  description?: string
+  items?: { type: string }
+}
+
+/**
+ * JSON-Schema-style props block — matches the `wippy.props` field in package.json.
+ *
+ * Example:
+ * ```json
+ * {
+ *   "type": "object",
+ *   "properties": {
+ *     "allowed-types": { "type": "array", "items": { "type": "string" } },
+ *     "max-file-size": { "type": "number", "default": 104857600 }
+ *   }
+ * }
+ * ```
+ */
+export interface WippyPropsSchema {
+  type?: string
+  properties: Record<string, WippyPropDefinition>
+}
+
+/**
+ * Keys that map to CSS URLs exposed by `@wippy-fe/proxy`'s `hostCss` object.
+ * Pass a subset to `hostCssKeys` in config to load only what you need.
+ */
+export type HostCssKey = 'fontCssUrl' | 'themeConfigUrl' | 'primeVueCssUrl' | 'markdownCssUrl' | 'iframeCssUrl'
+
+/**
+ * Configuration object returned by `static get wippyConfig()`.
+ *
+ * Generic over `Props` so that `validateProps` receives the typed prop object.
+ * Use `WippyElementConfig<MyProps>` as the return type of your static getter
+ * to get typed validation:
+ *
+ * ```ts
+ * static get wippyConfig(): WippyElementConfig<MyProps> { ... }
+ * ```
+ */
+export interface WippyElementConfig<Props = Record<string, unknown>> {
+  /** JSON-schema props block (usually from package.json `wippy.props`). */
+  propsSchema: WippyPropsSchema
+  /** Shadow DOM mode. Defaults to `'open'`. */
+  shadowMode?: 'open' | 'closed'
+  /**
+   * Host CSS to inherit from the Wippy platform into this component's shadow DOM.
+   *
+   * Shadow DOM blocks style inheritance, so platform styles (theme variables, fonts,
+   * UI framework classes, etc.) must be explicitly loaded into each component's shadow root.
+   * The host app provides these CSS assets at runtime via `@wippy-fe/proxy`.
+   *
+   * Available keys:
+   * - `fontCssUrl` — Platform font definitions. Include unless using fully custom fonts.
+   * - `themeConfigUrl` — CSS custom properties (color scales, spacing, etc.) matching the
+   *    host theme. **Recommended for all components** — gives your component the same look
+   *    as the host app. At dev time, a local copy (`theme-config.css`) provides fallback
+   *    values; at runtime, the host injects the real theme.
+   * - `primeVueCssUrl` — PrimeVue component classes (p-button, p-input, etc.) in unstyled
+   *    mode, matching the host's appearance. **Include if using any PrimeVue components**
+   *    (buttons, forms, tables, etc.). Skip only for fully custom UI with no PrimeVue.
+   * - `markdownCssUrl` — Styles for rendered markdown blocks. **Include only if your
+   *    component renders markdown content.**
+   * - `iframeCssUrl` — Scrollbar styling and iframe-related styles. **Recommended for all
+   *    components** so scrollbars look identical to the host app.
+   *
+   * Pass `[]` to skip host CSS entirely (fully self-styled component).
+   * Defaults to `['fontCssUrl', 'themeConfigUrl', 'primeVueCssUrl', 'markdownCssUrl', 'iframeCssUrl']`.
+   */
+  hostCssKeys?: HostCssKey[]
+  /**
+   * Component-specific CSS text to inject into the shadow root (synchronous).
+   *
+   * Typically from a Vite `?inline` import of your component's stylesheet.
+   * This is your component's own styling — Tailwind utilities, custom classes, etc.
+   * Unlike `hostCssKeys` which loads platform CSS at runtime, this is bundled at build time.
+   */
+  inlineCss?: string
+  /**
+   * Custom prop validation that runs after type parsing.
+   *
+   * Receives the already type-coerced props from the schema parser.
+   * Return an array of error messages for any invalid values, or an empty array if all valid.
+   * Errors are merged with any type-parsing errors and emitted as `invalid` events.
+   *
+   * Use this for domain-specific checks the JSON schema can't express:
+   * - Value ranges (`max-file-size` must be positive)
+   * - Array item types (`allowed-types` must be an array of strings)
+   * - Cross-prop constraints (if X is set, Y must also be set)
+   *
+   * Example:
+   * ```ts
+   * validateProps: (props) => {
+   *   const errors: string[] = []
+   *   if (typeof props.maxFileSize === 'number' && props.maxFileSize < 0) {
+   *     errors.push('max-file-size must be a positive number')
+   *   }
+   *   return errors
+   * }
+   * ```
+   */
+  validateProps?: (props: Props) => string[]
+  /** CSS classes to add to the container div. Defaults to none. */
+  containerClasses?: string[]
+  /** Additional attribute names to observe beyond those in the props schema. */
+  extraObservedAttributes?: string[]
+  /**
+   * If set, reads text content from a child `<template data-type="...">` element.
+   * The value is the type to match, e.g. `'text/vnd.mermaid'`.
+   * Content is extracted once on mount and updated via MutationObserver.
+   * Props take priority over children content.
+   *
+   * Usage:
+   * ```html
+   * <example-mermaid>
+   *   <template data-type="text/vnd.mermaid">graph TD; A --> B</template>
+   * </example-mermaid>
+   * ```
+   *
+   * Uses `<template>` instead of `<script>` because Vue templates strip script tags.
+   * The native `<template>` element is inert (not rendered) and works in both
+   * raw HTML and Vue SFC templates.
+   */
+  contentTemplate?: string
+}