@wippy-fe/webcomponent-core 0.0.34 → 0.0.36

package/src/base-element.ts

@@ -1,399 +0,0 @@
-import type { ReactiveAdapter } from './reactive-adapter.ts'
-import type { WippyElementConfig } from './types.ts'
-import { addCollection } from '@iconify/vue'
-import { addIcons, define } from '@wippy-fe/proxy'
-import { injectInlineCss, loadHostCss } from './css-loader.ts'
-import { getWippyHost } from './host-scope.ts'
-import { parseProps } from './prop-parser.ts'
-import { ReactiveAdapterImpl } from './reactive-adapter.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 (first connect):
- *   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 reconnect (move-style DOM op: detach → reattach), the shadow root
- * persists across the cycle, so steps 1, 3, 4, 5 (CSS injection +
- * container creation) are skipped to avoid duplicating `<style>` and
- * container `<div>` siblings inside the persistent shadow. The stored
- * container is reused and `onMount` is re-invoked with `isRemount = true`
- * so framework adapters can decide between fresh-mount and remount paths.
- *
- * On error: `onError(error)` → internals state → error → `error` event
- * On disconnect: `onUnmount()` → `unload` event → internals cleared.
- * Note: `disconnectedCallback` does NOT clear the shadow root or the
- * stored container — they're reused on reconnect.
- */
-export abstract class WippyElement<
-  Props = Record<string, unknown>,
-  Events = Record<string, unknown>,
-> extends HTMLElement {
-  private _internals!: ElementInternals
-  private _contentObserver: MutationObserver | null = null
-  /** True after the first successful connectedCallback completes. */
-  private _initialized: boolean = false
-  /** Container div created on first connect; reused on subsequent connects. */
-  private _container: HTMLElement | null = null
-  /**
-   * Opt-in reactive adapter. Lazy-allocated on first `this.reactive`
-   * access, disposed on `disconnectedCallback`, re-allocated on next
-   * access after reconnect. Subclasses that never touch `this.reactive`
-   * pay zero allocation cost — `notifyProps`/`notifyContent` short-circuit
-   * on the null guard.
-   */
-  private _reactive: ReactiveAdapterImpl<Props, Events> | null = null
-  /**
-   * Cached results of the most recent `parseProps` + `validateProps`
-   * pass. Set by `connectedCallback` and `attributeChangedCallback`.
-   * Read by `get reactive()` to avoid re-parsing on lazy allocation —
-   * means `validateProps` only ever runs once per attribute change,
-   * even for consumers that touch `this.reactive` inside `onMount`.
-   */
-  private _lastProps: Props | null = null
-  private _lastErrors: readonly string[] = []
-  private _lastContent: string | null = null
-
-  /**
-   * Phantom field to retain the `Events` type parameter so it shows up in
-   * type errors / `Reflect.get` shape. Adapter typing reads it indirectly
-   * via the generic.
-   * @internal
-   */
-  declare readonly _events: Events
-
-  /**
-   * 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()
-  }
-
-  /**
-   * Panel-scoped `host` wrapper attached by the managed-layout shell's
-   * content resolvers (`ComponentResolver` / `WebComponentPackageLoader`).
-   *
-   * Inside a managed-layout panel, this is a wrapper around the universal
-   * `host` API where context-aware calls (`layout.broadcast / send / on`)
-   * are routed through the panel-bound bus — so `sourcePanelId` is
-   * attributed correctly without postMessage indirection. Layout
-   * mutations and other host methods pass through unchanged.
-   *
-   * `null` outside a managed-layout context (compat shell, chat sidebar,
-   * standalone playground). Subclass code that needs a host in those
-   * cases can fall back to `import { host } from '@wippy-fe/proxy'`.
-   */
-  get host(): ReturnType<typeof getWippyHost> {
-    return getWippyHost(this)
-  }
-
-  /**
-   * 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,
-    }))
-  }
-
-  /**
-   * Opt-in reactive adapter — framework-agnostic. Subscribe to prop
-   * changes, content changes, or emit typed events from a non-Vue
-   * consumer without re-rolling reactivity.
-   *
-   * ```ts
-   * class MyEl extends WippyElement<{ count: number }, { tick: { n: number } }> {
-   *   protected onMount() {
-   *     const ctrl = new AbortController()
-   *     this.reactive.props.subscribe(({ count }) => {
-   *       this.shadowRoot!.querySelector('.n')!.textContent = String(count)
-   *     }, { signal: ctrl.signal, immediate: true })
-   *   }
-   *   tick(n: number) { this.reactive.events.emit('tick', { n }) }
-   * }
-   * ```
-   *
-   * Allocation cost is zero unless this getter is touched. Disposed on
-   * `disconnectedCallback`; a fresh adapter is allocated on the next
-   * access after reconnect.
-   */
-  protected get reactive(): ReactiveAdapter<Props, Events> {
-    if (!this._reactive) {
-      const config = (this.constructor as typeof WippyElement).wippyConfig
-      const hasContent = !!config.contentTemplate
-      // Reuse the cached parse result from the most recent
-      // `connectedCallback` / `attributeChangedCallback` whenever we
-      // have one; otherwise fall back to a fresh parse (this happens
-      // when `reactive` is touched before the element is ever
-      // connected — rare but legal).
-      let props: Props
-      let errors: readonly string[]
-      if (this._lastProps !== null) {
-        props = this._lastProps
-        errors = this._lastErrors
-      }
-      else {
-        const parsed = parseProps(this, config.propsSchema)
-        if (config.validateProps) {
-          parsed.errors.push(...config.validateProps(parsed.props))
-        }
-        props = parsed.props as Props
-        errors = parsed.errors
-        this._lastProps = props
-        this._lastErrors = errors
-      }
-      const content = hasContent
-        ? (this._lastContent ?? this._extractContent(config.contentTemplate!))
-        : null
-      if (hasContent && this._lastContent === null)
-        this._lastContent = content
-      this._reactive = new ReactiveAdapterImpl<Props, Events>(
-        { props, errors, content, hasContent },
-        this.emitEvent.bind(this),
-      )
-    }
-    return this._reactive
-  }
-
-  // ── Lifecycle ──────────────────────────────────────────────
-
-  connectedCallback(): void {
-    this._internals.states.add('loading')
-    try {
-      const config = (this.constructor as typeof WippyElement).wippyConfig
-      const isRemount = this._initialized
-
-      // 1. Shadow DOM (guard against reconnect — attachShadow throws if called twice)
-      const shadow = this.shadowRoot ?? this.attachShadow({ mode: config.shadowMode ?? 'open' })
-
-      let container: HTMLElement
-      if (!isRemount) {
-        // 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
-        container = document.createElement('div')
-        const classes = config.containerClasses ?? []
-        if (classes.length > 0) {
-          container.classList.add(...classes)
-        }
-        shadow.appendChild(container)
-        this._container = container
-
-        // 6. Icons
-        addIcons(addCollection)
-      }
-      else {
-        // Reconnect path — reuse the existing shadow children + container.
-        // Skip CSS/icon/container setup so we don't accumulate duplicate
-        // `<style>` and container `<div>` siblings on every detach/reattach.
-        // The framework adapter decides whether to remount on the existing
-        // container or recreate its app instance.
-        container = this._container!
-      }
-
-      // 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
-      // Cache so a lazy `get reactive()` call from inside `onMount`
-      // doesn't re-parse / re-validate.
-      this._lastProps = typedProps
-      this._lastErrors = errors
-
-      // 7b. Extract children content (if contentTemplate configured)
-      let initialContent: string | null = null
-      if (config.contentTemplate) {
-        initialContent = this._extractContent(config.contentTemplate)
-        this._lastContent = initialContent
-        this._contentObserver = new MutationObserver(() => {
-          const content = this._extractContent(config.contentTemplate!)
-          this._lastContent = content
-          // Fan out to the reactive adapter first so subclass overrides of
-          // `onContentChanged` that read `this.reactive.content.value` see
-          // the new value. No-op when the adapter hasn't been allocated.
-          this._reactive?.notifyContent(content)
-          this.onContentChanged(content)
-        })
-        this._contentObserver.observe(this, {
-          childList: true,
-          characterData: true,
-          subtree: true,
-        })
-      }
-
-      // 8. Framework mount (first time) or remount (reconnect)
-      this.onMount(shadow, container, typedProps, errors, initialContent, isRemount)
-
-      // 9. Ready
-      this._internals.states.delete('loading')
-      this._internals.states.add('ready')
-
-      // First-connect bookkeeping after a clean mount.
-      if (!isRemount) {
-        this._initialized = true
-      }
-
-      // 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()
-    // Drop the reactive adapter so subscribers from this attachment are
-    // cleared and a fresh adapter is allocated on the next `this.reactive`
-    // access (i.e. after reconnect).
-    this._reactive?.dispose()
-    this._reactive = null
-    // Clear cached parse state — `connectedCallback` re-populates on
-    // reconnect; before then, a lazy `get reactive()` access should
-    // re-parse from current attributes (rare path).
-    this._lastProps = null
-    this._lastErrors = []
-    this._lastContent = null
-    // Drop panel-context wires so a detached element held by a
-    // consumer (or re-inserted into a different panel) doesn't carry
-    // stale wires that would silently misattribute. The resolver
-    // re-installs them on the next mount.
-    delete (this as unknown as { __wippyHost?: unknown }).__wippyHost
-    delete (this as unknown as { __wippyHostBus?: unknown }).__wippyHostBus
-  }
-
-  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))
-    }
-    const typedProps = props as Props
-    this._lastProps = typedProps
-    this._lastErrors = errors
-    // Fan out to the reactive adapter BEFORE the legacy hook so subclasses
-    // that override `onPropsChanged` AND read `this.reactive.props.value`
-    // inside it see consistent state. No-op when the adapter hasn't been
-    // lazy-allocated.
-    this._reactive?.notifyProps(typedProps, errors)
-    this.onPropsChanged(typedProps, errors)
-  }
-
-  // ── Hooks ──────────────────────────────────────────────────
-
-  /** Called right after shadow DOM is attached, before CSS or container. */
-  protected onInit(_shadow: ShadowRoot): void {}
-
-  /**
-   * Called after shadow DOM, CSS, and container are ready. Mount your
-   * framework here.
-   *
-   * Invoked on first connect AND on every subsequent reconnect (move-style
-   * DOM op: detach → reattach). On reconnect the same `container` instance
-   * is reused. Adapters that hold a framework app handle should either
-   * detect `isRemount === true` and re-mount on the existing container, or
-   * leave the previous app intact across the detach/reattach cycle.
-   */
-  protected abstract onMount(
-    shadow: ShadowRoot,
-    container: HTMLElement,
-    initialProps: Props,
-    initialErrors: string[],
-    initialContent?: string | null,
-    isRemount?: boolean,
-  ): 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

@@ -1,52 +0,0 @@
-import type { HostCssKey } from './types.ts'
-import { hostCss, loadCss } from '@wippy-fe/proxy'
-
-const DEFAULT_HOST_CSS_KEYS: HostCssKey[] = [
-  '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
-  // Filter out keys whose URL is missing (e.g. removed CSS like fontCssUrl).
-  // Load each independently so one failure doesn't block the rest.
-  const jobs = cssKeys.map(async (key) => {
-    const url = hostCss[key]
-    if (!url) {
-      console.warn(`[wippy-fe/webcomponent-core] hostCss key "${key}" is undefined — skipping. Remove it from hostCssKeys if the CSS was removed.`)
-      return null
-    }
-    try {
-      return await loadCss(url)
-    }
-    catch (err) {
-      console.warn(`[wippy-fe/webcomponent-core] Failed to load hostCss "${key}" (${url}):`, err)
-      return null
-    }
-  })
-  return Promise.all(jobs).then((cssChunks) => {
-    for (const css of cssChunks) {
-      if (!css)
-        continue
-      const style = document.createElement('style')
-      style.textContent = css
-      style.setAttribute('role', '@wippy-fe/host-css')
-      shadow.appendChild(style)
-    }
-  })
-}
-
-/**
- * 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/host-bus.ts

@@ -1,44 +0,0 @@
-/**
- * Layout bus types shared between `@wippy-fe/webcomponent-core` and
- * `@wippy-fe/webcomponent-vue`. Mirror of the host-side
- * `LayoutBusBound` / `BroadcastEnvelope` shapes; structurally
- * compatible so a host-mounted web component can read its
- * `__wippyHostBus` property without importing host-private types.
- *
- * The host (gen-2-chat managed-layout shell) sets:
- *   - `el.dataset.wippyPanelId` (string)
- *   - `(el as { __wippyHostBus?: LayoutBusBound }).__wippyHostBus`
- * BEFORE the element is appended to the DOM. Web components see them
- * on first `connectedCallback` tick.
- *
- * Outside a managed-layout host, both are absent — read code MUST
- * tolerate `undefined`.
- *
- * The interface bodies live in `@wippy-fe/shared` so the host can
- * import them without dragging in this package's `@wippy-fe/proxy`
- * runtime dependency. Consumers continue to import from
- * `@wippy-fe/webcomponent-core` (this re-export) for backward compat.
- */
-
-import type { LayoutBusBound } from '@wippy-fe/shared'
-
-export type { BroadcastEnvelope, LayoutBusBound } from '@wippy-fe/shared'
-
-/**
- * Read the host bus attached to an element by `ComponentResolver` in
- * the managed-layout host. Returns `null` outside a managed-layout
- * host (or before the element is connected). Stable across element
- * remounts of the same panel — the resolver re-attaches a fresh bus
- * each time.
- */
-export function getWippyHostBus(el: HTMLElement): LayoutBusBound | null {
-  return (el as { __wippyHostBus?: LayoutBusBound }).__wippyHostBus ?? null
-}
-
-/**
- * Read the panelId attribute set by `ComponentResolver`. `null`
- * outside a managed-layout host.
- */
-export function getWippyPanelId(el: HTMLElement): string | null {
-  return el.dataset.wippyPanelId ?? null
-}

package/src/host-scope.test.ts

@@ -1,19 +0,0 @@
-/**
- * @vitest-environment jsdom
- */
-import { describe, expect, it } from 'vitest'
-import { getWippyHost } from './host-scope.ts'
-
-describe('getWippyHost', () => {
-  it('returns the wrapper attached as __wippyHost', () => {
-    const el = document.createElement('div')
-    const fake = { layout: { broadcast: () => {} } }
-    ;(el as unknown as { __wippyHost: unknown }).__wippyHost = fake
-    expect(getWippyHost(el)).toBe(fake)
-  })
-
-  it('returns null when no wrapper attached', () => {
-    const el = document.createElement('div')
-    expect(getWippyHost(el)).toBeNull()
-  })
-})

package/src/host-scope.ts

@@ -1,28 +0,0 @@
-/**
- * Element-attached host wrapper reader for web components mounted as
- * `kind: 'component'` panels in the gen-2-chat managed-layout shell.
- *
- * The host stamps a panel-scoped wrapper as `__wippyHost` on each
- * element BEFORE it is appended to the DOM (see the host's
- * `panel-context-wires.ts` and `host-scope.ts`). Consumer web
- * components read it back via `getWippyHost(this)` in
- * `connectedCallback` and onwards.
- *
- * The wrapper is **constructed by the host** — this package only
- * exposes the reader. Outside a managed-layout host (raw mounts,
- * compat shells, tests without the connector) the property is absent
- * and `getWippyHost` returns `null`.
- */
-
-/**
- * Read the panel-scoped host wrapper attached to an element by the
- * managed-layout shell's content resolvers. Returns `null` outside a
- * managed-layout host (or before the element is connected).
- *
- * Subclass authors of `WippyElement` / `WippyVueElement` access this
- * via `this.host` / `useHost()` and rarely need to call this directly.
- * The helper is exposed for raw `HTMLElement` consumers.
- */
-export function getWippyHost<H = unknown>(el: HTMLElement): H | null {
-  return ((el as unknown) as { __wippyHost?: H }).__wippyHost ?? null
-}

package/src/index.ts

@@ -1,22 +0,0 @@
-export { define, WippyElement } from './base-element.ts'
-export { injectInlineCss, loadHostCss } from './css-loader.ts'
-export { getWippyHostBus, getWippyPanelId } from './host-bus.ts'
-export type { BroadcastEnvelope, LayoutBusBound } from './host-bus.ts'
-export { getWippyHost } from './host-scope.ts'
-export { attrToCamel, parseProps } from './prop-parser.ts'
-export type { ParseResult } from './prop-parser.ts'
-export type {
-  ContentListener,
-  ContentSubscription,
-  EventEmitterHandle,
-  PropsListener,
-  PropsSubscription,
-  ReactiveAdapter,
-  SubscribeOptions,
-} from './reactive-adapter.ts'
-export type {
-  HostCssKey,
-  WippyElementConfig,
-  WippyPropDefinition,
-  WippyPropsSchema,
-} from './types.ts'

package/src/prop-parser.ts

@@ -1,91 +0,0 @@
-import type { WippyPropDefinition, WippyPropsSchema } 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 = Number.parseFloat(raw)
-      if (Number.isNaN(n))
-        return { value: undefined, error: `Invalid ${attr}: expected a number` }
-      return { value: n }
-    }
-
-    case 'integer': {
-      const n = Number.parseInt(raw, 10)
-      if (Number.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 }
-}