@wippy-fe/webcomponent-core 0.0.34 → 0.0.36

package/dist/index.d.ts

@@ -0,0 +1,452 @@
+import { LayoutBusBound } from '@wippy-fe/shared';
+export { BroadcastEnvelope, LayoutBusBound } from '@wippy-fe/shared';
+export { define } from '@wippy-fe/proxy';
+
+/**
+ * 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).
+ */
+type PropsListener<Props> = (props: Props, errors: readonly string[]) => void;
+type ContentListener = (content: string | null) => void;
+interface SubscribeOptions {
+    /** Cancel the subscription when the signal aborts. */
+    signal?: AbortSignal;
+    /** Fire the listener once synchronously with the current value. */
+    immediate?: boolean;
+}
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+
+/**
+ * JSON-Schema-style property descriptor used for attribute→prop parsing.
+ */
+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 }
+ *   }
+ * }
+ * ```
+ */
+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.
+ */
+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> { ... }
+ * ```
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+declare function getWippyHost<H = unknown>(el: HTMLElement): H | null;
+
+/**
+ * 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.
+ */
+declare abstract class WippyElement<Props = Record<string, unknown>, Events = Record<string, unknown>> extends HTMLElement {
+    private _internals;
+    private _contentObserver;
+    /** True after the first successful connectedCallback completes. */
+    private _initialized;
+    /** Container div created on first connect; reused on subsequent connects. */
+    private _container;
+    /**
+     * 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;
+    /**
+     * 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;
+    private _lastErrors;
+    private _lastContent;
+    /**
+     * 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
+     */
+    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;
+    /**
+     * Derived from the props schema + any `extraObservedAttributes`.
+     */
+    static get observedAttributes(): string[];
+    constructor();
+    /**
+     * 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>;
+    /**
+     * Emit a CustomEvent that bubbles and crosses shadow DOM boundaries.
+     */
+    protected emitEvent(eventName: string, detail?: unknown): void;
+    /**
+     * 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>;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(_name: string, oldVal: string | null, newVal: string | null): void;
+    /** 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;
+    /** 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;
+    /** Called when child `<template>` content changes. Override to update framework state. */
+    protected onContentChanged(_content: string | null): void;
+}
+
+/**
+ * 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.
+ */
+declare function loadHostCss(shadow: ShadowRoot, keys?: HostCssKey[]): Promise<void>;
+/**
+ * Injects inline CSS text into the shadow root.
+ */
+declare function injectInlineCss(shadow: ShadowRoot, text: string): void;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare function getWippyHostBus(el: HTMLElement): LayoutBusBound | null;
+/**
+ * Read the panelId attribute set by `ComponentResolver`. `null`
+ * outside a managed-layout host.
+ */
+declare function getWippyPanelId(el: HTMLElement): string | null;
+
+interface ParseResult {
+    props: Record<string, unknown>;
+    errors: string[];
+}
+/**
+ * Converts a kebab-case attribute name to camelCase.
+ * `allowed-types` → `allowedTypes`
+ */
+declare function attrToCamel(attr: string): string;
+/**
+ * Parses all attributes on an element according to its props schema.
+ * Returns `{ props, errors }` where errors is an array of human-readable messages.
+ */
+declare function parseProps(element: HTMLElement, schema: WippyPropsSchema): ParseResult;
+
+export { type ContentListener, type ContentSubscription, type EventEmitterHandle, type HostCssKey, type ParseResult, type PropsListener, type PropsSubscription, type ReactiveAdapter, type SubscribeOptions, WippyElement, type WippyElementConfig, type WippyPropDefinition, type WippyPropsSchema, attrToCamel, getWippyHost, getWippyHostBus, getWippyPanelId, injectInlineCss, loadHostCss, parseProps };