@wippy-fe/webcomponent-vue 0.0.6

package/README.md

@@ -0,0 +1,173 @@
+# @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
+
+```ts
+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: ['fontCssUrl', '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
+
+```ts
+static get wippyConfig(): WippyElementConfig  // from core — see core README for full options
+static get vueConfig(): WippyVueElementConfig
+```
+
+#### `WippyVueElementConfig`
+
+```ts
+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`, `onUnmount`, and `onPropsChanged` from the base class. 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 |
+| `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 |
+| `onPropsChanged(...)` | Implemented by WippyVueElement | Updates reactive refs automatically |
+
+### Provider Symbols
+
+Import these in your Vue components to access injected values:
+
+```ts
+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
+
+```ts
+static get vueConfig() {
+  return {
+    rootComponent: MyApp,
+    plugins: [createI18n({ /* ... */ })],
+  }
+}
+```
+
+## Custom Providers
+
+```ts
+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:
+```ts
+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:
+```ts
+class MyElement extends WippyVueElement {
+  static get wippyConfig() {
+    return {
+      propsSchema: pkg.wippy.props,
+      hostCssKeys: ['fontCssUrl', '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.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@wippy-fe/webcomponent-vue",
+  "version": "0.0.6",
+  "description": "Vue 3 integration layer for Wippy web components — extends @wippy-fe/webcomponent-core with reactive props, Pinia, and provider injection.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src/",
+    "package.json"
+  ],
+  "dependencies": {
+    "@wippy-fe/webcomponent-core": "^0.0.6"
+  },
+  "peerDependencies": {
+    "@wippy-fe/proxy": "^0.0.6",
+    "@iconify/vue": "^5.0.0",
+    "pinia": "^2.1.0",
+    "vue": "^3.5.0"
+  },
+  "license": "UNLICENSED"
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+// Vue layer
+export { WippyVueElement } from './vue-element.ts'
+export type { WippyVueElementConfig } from './vue-element.ts'
+
+// Providers: base symbols, composables, and createProviders utility
+export {
+  EVENT_PROVIDER, PROPS_PROVIDER, PROPS_ERROR_PROVIDER, CONTENT_PROVIDER,
+  useProps, useEvents, usePropsErrors, useContent,
+  createProviders,
+} from './providers.ts'
+export type { TypedProviders } from './providers.ts'
+
+// Re-export core for convenience
+export { WippyElement, define } from '@wippy-fe/webcomponent-core'
+export type {
+  WippyElementConfig,
+  WippyPropsSchema,
+  WippyPropDefinition,
+  HostCssKey,
+  ParseResult,
+} from '@wippy-fe/webcomponent-core'

package/src/providers.ts

@@ -0,0 +1,116 @@
+import type { InjectionKey, Ref } from 'vue'
+import { inject } from 'vue'
+
+// ── Base injection keys (untyped) ────────────────────────────
+
+/** Injection key for the event emitter function. */
+export const EVENT_PROVIDER = Symbol('wippy:emit') as InjectionKey<
+  (event: string, detail?: unknown) => void
+>
+
+/** Injection key for the reactive props ref. */
+export const PROPS_PROVIDER = Symbol('wippy:props') as InjectionKey<Ref<Record<string, unknown>>>
+
+/** Injection key for the reactive props error ref. */
+export const PROPS_ERROR_PROVIDER = Symbol('wippy:props_error') as InjectionKey<Ref<string[]>>
+
+/** Injection key for reactive content from child <template data-type="..."> elements. */
+export const CONTENT_PROVIDER = Symbol('wippy:content') as InjectionKey<Ref<string | null>>
+
+// ── Composables (typed) ──────────────────────────────────────
+
+/**
+ * Inject the reactive props ref, typed to your component's props interface.
+ *
+ * Must be called inside a Vue component's `setup()` that lives within a `WippyVueElement`.
+ *
+ * ```ts
+ * const props = useProps<ComponentProps>()
+ * // props is Ref<ComponentProps>
+ * console.log(props.value.maxFileSize)
+ * ```
+ */
+export function useProps<Props>(): Ref<Props> {
+  const props = inject(PROPS_PROVIDER)
+  if (!props) throw new Error('useProps() must be called inside a WippyVueElement')
+  return props as unknown as Ref<Props>
+}
+
+/**
+ * Inject the typed event emitter, constrained to your component's event map.
+ *
+ * Must be called inside a Vue component's `setup()` that lives within a `WippyVueElement`.
+ *
+ * ```ts
+ * const emit = useEvents<Events>()
+ * emit('upload-complete', { fileId: '123', status: 'done' }) // fully typed
+ * ```
+ */
+export function useEvents<Events>(): <K extends keyof Events>(event: K, detail: Events[K]) => void {
+  const emit = inject(EVENT_PROVIDER)
+  if (!emit) throw new Error('useEvents() must be called inside a WippyVueElement')
+  return emit as unknown as <K extends keyof Events>(event: K, detail: Events[K]) => void
+}
+
+/**
+ * Inject the reactive prop validation errors ref.
+ *
+ * Must be called inside a Vue component's `setup()` that lives within a `WippyVueElement`.
+ *
+ * ```ts
+ * const errors = usePropsErrors()
+ * // errors is Ref<string[]>
+ * ```
+ */
+export function usePropsErrors(): Ref<string[]> {
+  const errors = inject(PROPS_ERROR_PROVIDER)
+  if (!errors) throw new Error('usePropsErrors() must be called inside a WippyVueElement')
+  return errors
+}
+
+/**
+ * Inject the reactive content ref (from child `<template data-type="...">` elements).
+ *
+ * Must be called inside a Vue component's `setup()` within a `WippyVueElement`
+ * that has `contentTemplate` configured.
+ *
+ * ```ts
+ * const content = useContent()
+ * // content is Ref<string | null>
+ * ```
+ */
+export function useContent(): Ref<string | null> {
+  const content = inject(CONTENT_PROVIDER)
+  if (!content) throw new Error('useContent() must be called inside a WippyVueElement with contentTemplate configured')
+  return content
+}
+
+// ── createProviders (typed injection keys) ───────────────────
+
+/**
+ * Typed provider keys for a specific component.
+ */
+export interface TypedProviders<Props, Events> {
+  EVENT_PROVIDER: InjectionKey<<K extends keyof Events>(event: K, detail: Events[K]) => void>
+  PROPS_PROVIDER: InjectionKey<Ref<Props>>
+  PROPS_ERROR_PROVIDER: InjectionKey<Ref<string[]>>
+}
+
+/**
+ * Creates typed provider injection keys for a specific component.
+ *
+ * Use this if you prefer raw `inject(KEY)` over the composable helpers.
+ * Returns the same Symbol instances with narrowed types.
+ *
+ * ```ts
+ * export const { EVENT_PROVIDER, PROPS_PROVIDER, PROPS_ERROR_PROVIDER } =
+ *   createProviders<ComponentProps, Events>()
+ * ```
+ */
+export function createProviders<Props, Events = Record<string, unknown>>(): TypedProviders<Props, Events> {
+  return {
+    EVENT_PROVIDER: EVENT_PROVIDER as unknown as TypedProviders<Props, Events>['EVENT_PROVIDER'],
+    PROPS_PROVIDER: PROPS_PROVIDER as unknown as TypedProviders<Props, Events>['PROPS_PROVIDER'],
+    PROPS_ERROR_PROVIDER,
+  }
+}

package/src/vue-element.ts

@@ -0,0 +1,128 @@
+import type { App, Component, Ref } from 'vue'
+import { WippyElement } from '@wippy-fe/webcomponent-core'
+import { createPinia } from 'pinia'
+import { createApp, ref } from 'vue'
+import { EVENT_PROVIDER, PROPS_PROVIDER, PROPS_ERROR_PROVIDER, CONTENT_PROVIDER } from './providers.ts'
+
+/**
+ * Vue-specific configuration returned by `static get vueConfig()`.
+ */
+export interface WippyVueElementConfig {
+  /** The root Vue component to mount. */
+  rootComponent: Component
+  /** Additional Vue plugins to install (beyond Pinia which is always installed). */
+  plugins?: Array<{ install: (app: App) => void }>
+  /** Extra providers to inject into the Vue app. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  providers?: (app: App, element: WippyVueElement<any, any>) => void
+}
+
+/**
+ * Vue 3 integration for Wippy web components.
+ *
+ * Generic over `Props` (parsed prop object type) and `Events` (event map).
+ * These flow through to typed hooks, reactive refs, and composable helpers.
+ *
+ * Usage:
+ * ```ts
+ * class MyElement extends WippyVueElement<MyProps, MyEvents> {
+ *   static get wippyConfig(): WippyElementConfig<MyProps> {
+ *     return { propsSchema: pkg.wippy.props, inlineCss: stylesText }
+ *   }
+ *   static get vueConfig() {
+ *     return { rootComponent: MyApp }
+ *   }
+ * }
+ * ```
+ *
+ * In Vue components, use the typed composable helpers:
+ * ```ts
+ * const props = useProps<MyProps>()
+ * const emit = useEvents<MyEvents>()
+ * const errors = usePropsErrors()
+ * ```
+ */
+export abstract class WippyVueElement<
+  Props = Record<string, unknown>,
+  Events = Record<string, unknown>,
+> extends WippyElement<Props> {
+  private _vueApp: App<Element> | null = null
+  private _propsRef: Ref<Props> = ref({}) as Ref<Props>
+  private _errorsRef: Ref<string[]> = ref([])
+  private _contentRef: Ref<string | null> = ref(null)
+
+  /** @internal Phantom field to retain the Events type parameter. */
+  declare readonly _events: Events
+
+  /**
+   * Override to provide Vue-specific configuration.
+   */
+  static get vueConfig(): WippyVueElementConfig {
+    throw new Error('WippyVueElement subclass must override static get vueConfig()')
+  }
+
+  protected onMount(
+    _shadow: ShadowRoot,
+    container: HTMLElement,
+    initialProps: Props,
+    initialErrors: string[],
+    initialContent?: string | null,
+  ): void {
+    const vueConfig = (this.constructor as typeof WippyVueElement).vueConfig
+
+    // 1. Set reactive state
+    this._propsRef.value = initialProps
+    this._errorsRef.value = initialErrors
+    this._contentRef.value = initialContent ?? null
+
+    // Emit initial errors as invalid events
+    for (const error of initialErrors) {
+      this.emitEvent('invalid', { message: error })
+    }
+
+    // 2. Create Vue app
+    this._vueApp = createApp(vueConfig.rootComponent)
+    this._vueApp.use(createPinia())
+
+    // 3. Install extra plugins
+    if (vueConfig.plugins) {
+      for (const plugin of vueConfig.plugins) {
+        this._vueApp.use(plugin)
+      }
+    }
+
+    // 4. Provide standard injection keys
+    this._vueApp.provide(PROPS_PROVIDER, this._propsRef as Ref<Record<string, unknown>>)
+    this._vueApp.provide(PROPS_ERROR_PROVIDER, this._errorsRef)
+    this._vueApp.provide(EVENT_PROVIDER, this.emitEvent.bind(this))
+    this._vueApp.provide(CONTENT_PROVIDER, this._contentRef)
+
+    // 5. Custom providers
+    if (vueConfig.providers) {
+      vueConfig.providers(this._vueApp, this)
+    }
+
+    // 6. Mount
+    this._vueApp.mount(container)
+  }
+
+  protected onUnmount(): void {
+    if (this._vueApp) {
+      this._vueApp.unmount()
+      this._vueApp = null
+    }
+  }
+
+  protected onPropsChanged(props: Props, errors: string[]): void {
+    this._propsRef.value = props
+    this._errorsRef.value = errors
+
+    for (const error of errors) {
+      this.emitEvent('invalid', { message: error })
+    }
+  }
+
+  protected onContentChanged(content: string | null): void {
+    this._contentRef.value = content
+  }
+}