@wippy-fe/webcomponent-vue

Vue 3 integration layer for Wippy web components. Extends @wippy-fe/webcomponent-core with reactive props, Pinia state management, and Vue provider injection.

What it does

• Vue app lifecycle — creates and mounts a Vue 3 app inside the shadow DOM container
• Reactive props — attribute changes flow through a Vue ref() that components can inject()
• Pinia — automatically installed on every Vue app instance
• Provider injection — exposes props, errors, and an event emitter via Vue's provide/inject
• Plugin support — install additional Vue plugins via vueConfig.plugins
• Custom providers — hook into the Vue app before mount via vueConfig.providers

What it does NOT do

• DOM setup, CSS loading, or prop parsing — that's handled by @wippy-fe/webcomponent-core (see its README for CSS guide)
• Component registration — use define(import.meta.url, YourElement) (re-exported from core)
• Any React/Svelte/etc. integration — this package is Vue-only

Quick Start

import { WippyVueElement, define } from '@wippy-fe/webcomponent-vue'
import MyApp from './app/my-app.vue'
import stylesText from './styles.css?inline'
import pkg from '../package.json'

class MyElement extends WippyVueElement {
  static get wippyConfig() {
    return {
      propsSchema: pkg.wippy.props,
      hostCssKeys: ['themeConfigUrl', 'primeVueCssUrl', 'iframeCssUrl'],
      containerClasses: ['h-full'],
      inlineCss: stylesText,
    }
  }

  static get vueConfig() {
    return {
      rootComponent: MyApp,
    }
  }
}

export async function webComponent() {
  return MyElement
}

define(import.meta.url, MyElement)

API Reference

WippyVueElement (abstract class)

Extends WippyElement from @wippy-fe/webcomponent-core.

Static getters to override

static get wippyConfig(): WippyElementConfig  // from core — see core README for full options
static get vueConfig(): WippyVueElementConfig

WippyVueElementConfig

interface WippyVueElementConfig {
  /** The root Vue component to mount. */
  rootComponent: Component

  /** Additional Vue plugins to install (beyond Pinia). */
  plugins?: Array<{ install: (app: App) => void }>

  /** Extra providers to inject. Called after standard providers are set up. */
  providers?: (app: App, element: WippyVueElement) => void
}

Lifecycle hooks

WippyVueElement implements onMount and onUnmount from the base class. Prop / content changes are propagated to the Vue refs via a subscription on the core's this.reactive adapter (set up in onMount, torn down via AbortSignal in onUnmount). You don't need — and should not — override onPropsChanged / onContentChanged; the bridge handles them. You can still override the other hooks from WippyElement:

| Hook | Available? | Notes | |------|-----------|-------| | onInit(shadow) | Override freely | Runs before CSS/container | | onMount(...) | Implemented by WippyVueElement | Do not override — use vueConfig instead. Sets up Pinia, Vue app, providers, and bridges core's reactive adapter → Vue refs. | | onReady() | Override freely | Runs after Vue app is mounted and state is ready | | onError(error) | Override freely | Custom error handling | | onUnmount() | Implemented by WippyVueElement | Do not override. Aborts the core-adapter bridge subscription, then unmounts the Vue app. | | onPropsChanged(...) | Inherited from WippyElement (no-op) | Propagation happens via the reactive-adapter bridge instead. Overriding here works but is redundant for ref updates; reach for this.reactive.props.subscribe(...) if you need a custom hook. | | onContentChanged(...) | Inherited from WippyElement (no-op) | Same — propagated via the bridge. |

Provider Symbols

Import these in your Vue components to access injected values:

import { EVENT_PROVIDER, PROPS_PROVIDER, PROPS_ERROR_PROVIDER } from '@wippy-fe/webcomponent-vue'

// In setup()
const props = inject(PROPS_PROVIDER)!        // Ref<Record<string, unknown>>
const errors = inject(PROPS_ERROR_PROVIDER)!  // Ref<string[]>
const emit = inject(EVENT_PROVIDER)!          // (event: string, detail?) => void

| Symbol | Type | Description | |--------|------|-------------| | EVENT_PROVIDER | (event: string, detail?) => void | Emits CustomEvents from the host element | | PROPS_PROVIDER | Ref<Record<string, unknown>> | Reactive parsed props from attributes | | PROPS_ERROR_PROVIDER | Ref<string[]> | Reactive list of prop parsing errors |

Re-exports from core

For convenience, this package re-exports everything from @wippy-fe/webcomponent-core:

• WippyElement, define
• WippyElementConfig, WippyPropsSchema, WippyPropDefinition, HostCssKey, ParseResult

Adding Plugins

static get vueConfig() {
  return {
    rootComponent: MyApp,
    plugins: [createI18n({ /* ... */ })],
  }
}

Custom Providers

import { MY_SERVICE } from './services'

static get vueConfig() {
  return {
    rootComponent: MyApp,
    providers(app, element) {
      app.provide(MY_SERVICE, new MyService(element))
    },
  }
}

Migration from monolithic pattern

Before — every component duplicates ~170 lines:

class MyElement extends HTMLElement {
  private vueApp: App | null = null
  private props: Ref<...> = ref({})
  // ... shadow DOM, CSS loading, prop parsing, Vue setup, events ...
}

After — ~20 lines:

class MyElement extends WippyVueElement {
  static get wippyConfig() {
    return {
      propsSchema: pkg.wippy.props,
      hostCssKeys: ['themeConfigUrl', 'primeVueCssUrl', 'iframeCssUrl'],
      containerClasses: ['h-full'],
      inlineCss: stylesText,
    }
  }
  static get vueConfig() {
    return { rootComponent: MyApp }
  }
}

All the boilerplate (shadow DOM, CSS, prop parsing, Vue lifecycle, Pinia, providers) is handled by the base classes.

Host-owned logical visibility

Use useHostVisibility() inside a WippyVueElement to read the host's logical activity without coupling to CSS or viewport visibility:

const hostVisible = useHostVisibility() // Ref<boolean | null>
watch(hostVisible, (next, previous) => {
  if (previous === false && next === true)
    refreshRetainedData()
})

null means the element is unmanaged. The ref is seeded before the Vue app mounts, then updates without reparenting or remounting the custom element. The initial value is not a transition; components own cancellation and stale-response handling for any retained-data refresh.

Use useHostVisibilityRefresh(task) when a direct WC already has one ordinary initial load and should repeat that task only after false -> true. It runs task once from Vue's onMounted, returns the same visibility ref, and leaves sync or async failures in Vue error handling. It serializes an in-flight load and coalesces any number of intervening reveals into one trailing refresh. It never reloads the browser.

The callback still owns cancellation when the component unmounts and stale response handling when the same data can be loaded through another path. Put every remote dataset loaded by the ordinary mounted task in this callback, but keep local UI state, subscriptions, and non-idempotent realtime setup outside it.