@wippy-fe/webcomponent-core 0.0.32 → 0.0.35

package/src/reactive-adapter.test.ts

@@ -1,290 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { ReactiveAdapterImpl } from './reactive-adapter.ts'
-
-// ─────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────
-
-interface TestProps {
-  count: number
-  label: string
-}
-
-interface TestEvents {
-  tick: { n: number }
-  reset: { reason: string }
-}
-
-function makeAdapter(initial?: {
-  props?: TestProps
-  errors?: string[]
-  content?: string | null
-  hasContent?: boolean
-}) {
-  const emit = vi.fn()
-  const adapter = new ReactiveAdapterImpl<TestProps, TestEvents>(
-    {
-      props: initial?.props ?? { count: 0, label: 'init' },
-      errors: initial?.errors ?? [],
-      content: initial?.content ?? null,
-      hasContent: initial?.hasContent ?? false,
-    },
-    emit,
-  )
-  return { adapter, emit }
-}
-
-afterEach(() => {
-  vi.restoreAllMocks()
-})
-
-// ─────────────────────────────────────────────────────────────
-// props subscription
-// ─────────────────────────────────────────────────────────────
-
-describe('reactiveAdapter — props subscription', () => {
-  it('exposes the initial props via `.value` and `.errors`', () => {
-    const { adapter } = makeAdapter({
-      props: { count: 5, label: 'hello' },
-      errors: ['oops'],
-    })
-    expect(adapter.props.value).toEqual({ count: 5, label: 'hello' })
-    expect(adapter.props.errors).toEqual(['oops'])
-  })
-
-  it('fires listeners on notifyProps with new values', () => {
-    const { adapter } = makeAdapter()
-    const listener = vi.fn()
-    adapter.props.subscribe(listener)
-
-    adapter.notifyProps({ count: 1, label: 'one' }, ['e'])
-
-    expect(listener).toHaveBeenCalledTimes(1)
-    expect(listener).toHaveBeenCalledWith({ count: 1, label: 'one' }, ['e'])
-    expect(adapter.props.value).toEqual({ count: 1, label: 'one' })
-    expect(adapter.props.errors).toEqual(['e'])
-  })
-
-  it('returned unsubscribe function stops further callbacks', () => {
-    const { adapter } = makeAdapter()
-    const listener = vi.fn()
-    const unsub = adapter.props.subscribe(listener)
-
-    adapter.notifyProps({ count: 1, label: 'a' }, [])
-    unsub()
-    adapter.notifyProps({ count: 2, label: 'b' }, [])
-
-    expect(listener).toHaveBeenCalledTimes(1)
-  })
-
-  it('abortSignal.abort() cancels the subscription', () => {
-    const { adapter } = makeAdapter()
-    const ctrl = new AbortController()
-    const listener = vi.fn()
-    adapter.props.subscribe(listener, { signal: ctrl.signal })
-
-    adapter.notifyProps({ count: 1, label: 'a' }, [])
-    ctrl.abort()
-    adapter.notifyProps({ count: 2, label: 'b' }, [])
-
-    expect(listener).toHaveBeenCalledTimes(1)
-  })
-
-  it('does NOT subscribe when the signal is already aborted', () => {
-    const { adapter } = makeAdapter()
-    const ctrl = new AbortController()
-    ctrl.abort()
-    const listener = vi.fn()
-    adapter.props.subscribe(listener, { signal: ctrl.signal })
-
-    adapter.notifyProps({ count: 1, label: 'a' }, [])
-
-    expect(listener).not.toHaveBeenCalled()
-  })
-
-  it('options.immediate fires the listener synchronously with current state', () => {
-    const { adapter } = makeAdapter({
-      props: { count: 7, label: 'now' },
-      errors: ['warn'],
-    })
-    const listener = vi.fn()
-    adapter.props.subscribe(listener, { immediate: true })
-
-    expect(listener).toHaveBeenCalledTimes(1)
-    expect(listener).toHaveBeenCalledWith({ count: 7, label: 'now' }, ['warn'])
-  })
-
-  it('multiple subscribers all receive updates; unsubscribing one does not affect others', () => {
-    const { adapter } = makeAdapter()
-    const a = vi.fn()
-    const b = vi.fn()
-    const c = vi.fn()
-    adapter.props.subscribe(a)
-    const unsubB = adapter.props.subscribe(b)
-    adapter.props.subscribe(c)
-
-    adapter.notifyProps({ count: 1, label: 'x' }, [])
-    unsubB()
-    adapter.notifyProps({ count: 2, label: 'y' }, [])
-
-    expect(a).toHaveBeenCalledTimes(2)
-    expect(b).toHaveBeenCalledTimes(1)
-    expect(c).toHaveBeenCalledTimes(2)
-  })
-})
-
-// ─────────────────────────────────────────────────────────────
-// events emitter
-// ─────────────────────────────────────────────────────────────
-
-describe('reactiveAdapter — AbortSignal hygiene', () => {
-  it('manual unsub() removes the abort listener from the signal (no leak)', () => {
-    const { adapter } = makeAdapter()
-    const ctrl = new AbortController()
-    const removeSpy = vi.spyOn(ctrl.signal, 'removeEventListener')
-    const listener = vi.fn()
-    const unsub = adapter.props.subscribe(listener, { signal: ctrl.signal })
-
-    unsub()
-
-    expect(removeSpy).toHaveBeenCalledWith('abort', expect.any(Function))
-  })
-
-  it('does not double-fire when abort fires after manual unsub', () => {
-    const { adapter } = makeAdapter()
-    const ctrl = new AbortController()
-    const listener = vi.fn()
-    const unsub = adapter.props.subscribe(listener, { signal: ctrl.signal })
-
-    unsub()
-    ctrl.abort() // would re-trigger unsub if abort listener weren't removed
-
-    // notifyProps should still find no listeners
-    adapter.notifyProps({ count: 1, label: 'x' }, [])
-    expect(listener).not.toHaveBeenCalled()
-  })
-})
-
-describe('reactiveAdapter — re-entrant notify during immediate fire', () => {
-  it('captures synchronous re-entrant notifyProps from inside immediate callback', () => {
-    const { adapter } = makeAdapter()
-    const seen: Array<{ count: number, label: string }> = []
-    let triggeredOnce = false
-    adapter.props.subscribe((props) => {
-      seen.push(props)
-      // Re-enter notifyProps from inside the listener (simulating a
-      // listener that synchronously triggers an attribute change).
-      if (!triggeredOnce) {
-        triggeredOnce = true
-        adapter.notifyProps({ count: 99, label: 'after-immediate' }, [])
-      }
-    }, { immediate: true })
-
-    // Expected: 1st call = immediate fire with initial state,
-    // 2nd call = synchronous notifyProps from inside listener.
-    // Without the order-swap fix, the 2nd call would be lost.
-    expect(seen).toEqual([
-      { count: 0, label: 'init' },
-      { count: 99, label: 'after-immediate' },
-    ])
-  })
-})
-
-describe('reactiveAdapter — events emitter', () => {
-  it('emit delegates to the provided DOM emit function', () => {
-    const { adapter, emit } = makeAdapter()
-    adapter.events.emit('tick', { n: 42 })
-    expect(emit).toHaveBeenCalledWith('tick', { n: 42 })
-  })
-
-  it('emit becomes a no-op after dispose', () => {
-    const { adapter, emit } = makeAdapter()
-    adapter.dispose()
-    adapter.events.emit('tick', { n: 1 })
-    expect(emit).not.toHaveBeenCalled()
-  })
-})
-
-// ─────────────────────────────────────────────────────────────
-// content subscription
-// ─────────────────────────────────────────────────────────────
-
-describe('reactiveAdapter — content', () => {
-  it('content is null when hasContent is false', () => {
-    const { adapter } = makeAdapter({ hasContent: false })
-    expect(adapter.content).toBeNull()
-  })
-
-  it('content exposes value + subscribe when hasContent is true', () => {
-    const { adapter } = makeAdapter({
-      hasContent: true,
-      content: 'initial-text',
-    })
-    expect(adapter.content?.value).toBe('initial-text')
-  })
-
-  it('fires content listeners on notifyContent', () => {
-    const { adapter } = makeAdapter({ hasContent: true, content: 'a' })
-    const listener = vi.fn()
-    adapter.content!.subscribe(listener)
-
-    adapter.notifyContent('b')
-
-    expect(listener).toHaveBeenCalledWith('b')
-    expect(adapter.content!.value).toBe('b')
-  })
-
-  it('immediate fires for content too', () => {
-    const { adapter } = makeAdapter({ hasContent: true, content: 'preset' })
-    const listener = vi.fn()
-    adapter.content!.subscribe(listener, { immediate: true })
-    expect(listener).toHaveBeenCalledWith('preset')
-  })
-})
-
-// ─────────────────────────────────────────────────────────────
-// dispose
-// ─────────────────────────────────────────────────────────────
-
-describe('reactiveAdapter — dispose', () => {
-  it('notifyProps becomes a no-op after dispose', () => {
-    const { adapter } = makeAdapter()
-    const listener = vi.fn()
-    adapter.props.subscribe(listener)
-
-    adapter.dispose()
-    adapter.notifyProps({ count: 99, label: 'after' }, [])
-
-    expect(listener).not.toHaveBeenCalled()
-  })
-
-  it('notifyContent becomes a no-op after dispose', () => {
-    const { adapter } = makeAdapter({ hasContent: true })
-    const listener = vi.fn()
-    adapter.content!.subscribe(listener)
-
-    adapter.dispose()
-    adapter.notifyContent('after')
-
-    expect(listener).not.toHaveBeenCalled()
-  })
-
-  it('subscribe after dispose returns a no-op unsub and never fires', () => {
-    const { adapter } = makeAdapter()
-    adapter.dispose()
-    const listener = vi.fn()
-    const unsub = adapter.props.subscribe(listener)
-
-    adapter.notifyProps({ count: 1, label: 'a' }, [])
-    expect(listener).not.toHaveBeenCalled()
-    expect(() => unsub()).not.toThrow()
-  })
-
-  it('dispose is idempotent', () => {
-    const { adapter } = makeAdapter()
-    expect(() => {
-      adapter.dispose()
-      adapter.dispose()
-    }).not.toThrow()
-  })
-})

package/src/reactive-adapter.ts

@@ -1,220 +0,0 @@
-/**
- * Opt-in reactive adapter for `WippyElement`.
- *
- * Framework-agnostic primitive that lets non-Vue consumers subscribe to
- * prop / content updates and emit typed events on a web component without
- * pulling Vue (or any other reactivity library) into the core bundle.
- *
- * Access via `this.reactive` on a `WippyElement` subclass — the getter is
- * lazy, so subclasses that never touch it pay zero allocation cost. See
- * `base-element.ts:get reactive` for the bridge into the lifecycle.
- *
- * The `notifyProps` / `notifyContent` methods are package-visible: the
- * base element calls them from `attributeChangedCallback` and the content
- * MutationObserver callback respectively. They are NOT part of the public
- * API consumers should reach for.
- *
- * Cleanup: `dispose()` runs from `disconnectedCallback`. All listener
- * sets are cleared; subsequent notifyProps/notifyContent are no-ops; the
- * `events.emit` becomes a no-op too. A fresh adapter is allocated on the
- * next `this.reactive` access (i.e. after reconnect).
- */
-
-export type PropsListener<Props> = (props: Props, errors: readonly string[]) => void
-export type ContentListener = (content: string | null) => void
-
-export interface SubscribeOptions {
-  /** Cancel the subscription when the signal aborts. */
-  signal?: AbortSignal
-  /** Fire the listener once synchronously with the current value. */
-  immediate?: boolean
-}
-
-export interface PropsSubscription<Props> {
-  /** Current parsed props. Always reflects the latest state. */
-  readonly value: Props
-  /** Current validation/parse errors. */
-  readonly errors: readonly string[]
-  /**
-   * Register a listener that fires whenever props change. Returns an
-   * unsubscribe function. Pass `options.signal` for AbortSignal-driven
-   * cleanup (e.g. tied to an element's lifetime). Pass
-   * `options.immediate: true` to fire once synchronously with the current
-   * value — useful when the subscriber is set up mid-flight.
-   *
-   * Note: `notifyProps` runs BEFORE the subclass `onPropsChanged()` hook.
-   * A subscriber added from inside `onPropsChanged()` therefore does NOT
-   * receive the currently-firing change — only the next one. Use
-   * `{ immediate: true }` to also see the current value.
-   */
-  subscribe: (listener: PropsListener<Props>, options?: SubscribeOptions) => () => void
-}
-
-export interface ContentSubscription {
-  /** Current `<template>` content text, or `null` if not set. */
-  readonly value: string | null
-  /** See `PropsSubscription.subscribe` for the same ordering caveat. */
-  subscribe: (listener: ContentListener, options?: SubscribeOptions) => () => void
-}
-
-export interface EventEmitterHandle<Events> {
-  /**
-   * Dispatch a typed `CustomEvent` (bubbles + composed, identical
-   * semantics to the protected `emitEvent` helper). The key is constrained
-   * to `keyof Events & string`, so consumers narrow `Events` to get
-   * autocomplete + payload-type checks.
-   *
-   * No-op after the adapter is disposed (i.e. after the element is
-   * detached). The element is the only event target — subscribers on
-   * the element itself receive the event.
-   */
-  emit: <K extends keyof Events & string>(event: K, detail: Events[K]) => void
-}
-
-export interface ReactiveAdapter<Props, Events> {
-  props: PropsSubscription<Props>
-  events: EventEmitterHandle<Events>
-  /**
-   * Present only when the element's `wippyConfig.contentTemplate` is set;
-   * `null` otherwise. Avoids fake `.value === null` semantics for elements
-   * that don't track children content.
-   */
-  content: ContentSubscription | null
-}
-
-/**
- * Concrete implementation used by `WippyElement`. The `notify*` methods
- * are intentionally exposed (not private) so the base-element can call
- * them; consumers should never reach for them.
- *
- * @internal
- */
-export class ReactiveAdapterImpl<Props, Events> implements ReactiveAdapter<Props, Events> {
-  private _props: Props
-  private _errors: readonly string[]
-  private _content: string | null
-  private _propsListeners = new Set<PropsListener<Props>>()
-  private _contentListeners = new Set<ContentListener>()
-  private _disposed = false
-  private _emitToDom: (eventName: string, detail?: unknown) => void
-
-  readonly props: PropsSubscription<Props>
-  readonly events: EventEmitterHandle<Events>
-  readonly content: ContentSubscription | null
-
-  constructor(
-    initial: {
-      props: Props
-      errors: readonly string[]
-      content: string | null
-      hasContent: boolean
-    },
-    emitToDom: (eventName: string, detail?: unknown) => void,
-  ) {
-    this._props = initial.props
-    this._errors = initial.errors
-    this._content = initial.content
-    this._emitToDom = emitToDom
-
-    // Each getter / closure below runs with the surrounding object literal
-    // as `this`, not the class instance — so we have to capture the
-    // instance explicitly here.
-    // eslint-disable-next-line ts/no-this-alias
-    const self = this
-
-    this.props = {
-      get value() {
-        return self._props
-      },
-      get errors() {
-        return self._errors
-      },
-      subscribe(listener, options) {
-        return self._subscribeProps(listener, options)
-      },
-    }
-
-    this.events = {
-      emit(event, detail) {
-        if (self._disposed)
-          return
-        self._emitToDom(event as string, detail)
-      },
-    }
-
-    this.content = initial.hasContent
-      ? {
-          get value() {
-            return self._content
-          },
-          subscribe(listener, options) {
-            return self._subscribeContent(listener, options)
-          },
-        }
-      : null
-  }
-
-  /** @internal */
-  notifyProps(props: Props, errors: readonly string[]): void {
-    if (this._disposed)
-      return
-    this._props = props
-    this._errors = errors
-    for (const listener of this._propsListeners)
-      listener(props, errors)
-  }
-
-  /** @internal */
-  notifyContent(content: string | null): void {
-    if (this._disposed)
-      return
-    this._content = content
-    for (const listener of this._contentListeners)
-      listener(content)
-  }
-
-  /** @internal */
-  dispose(): void {
-    if (this._disposed)
-      return
-    this._disposed = true
-    this._propsListeners.clear()
-    this._contentListeners.clear()
-  }
-
-  private _subscribeProps(listener: PropsListener<Props>, options?: SubscribeOptions): () => void {
-    if (this._disposed || options?.signal?.aborted)
-      return () => {}
-    // Add to the set BEFORE firing `immediate` so a re-entrant
-    // `notifyProps` triggered from inside the immediate callback can
-    // find this listener and fire it for the synchronous change too.
-    this._propsListeners.add(listener)
-    if (options?.immediate)
-      listener(this._props, this._errors)
-    const unsub = () => {
-      this._propsListeners.delete(listener)
-      // Manual unsub must also detach the abort listener — otherwise it
-      // accumulates on long-lived signals (e.g. an AbortController kept
-      // around for the element's whole lifetime that fans out to many
-      // subscriptions). `{ once: true }` only auto-removes when 'abort'
-      // actually fires.
-      options?.signal?.removeEventListener('abort', unsub)
-    }
-    options?.signal?.addEventListener('abort', unsub, { once: true })
-    return unsub
-  }
-
-  private _subscribeContent(listener: ContentListener, options?: SubscribeOptions): () => void {
-    if (this._disposed || options?.signal?.aborted)
-      return () => {}
-    this._contentListeners.add(listener)
-    if (options?.immediate)
-      listener(this._content)
-    const unsub = () => {
-      this._contentListeners.delete(listener)
-      options?.signal?.removeEventListener('abort', unsub)
-    }
-    options?.signal?.addEventListener('abort', unsub, { once: true })
-    return unsub
-  }
-}

package/src/types.ts

@@ -1,130 +0,0 @@
-/**
- * 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 = '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:
-   * - `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 `['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
-}