@lightning-out/lwc-shell 2.2.0-rc.0

package/README.md

@@ -0,0 +1,27 @@
+# @lightning-out/lwc-shell
+
+A **custom web component** (`<lwc-shell>`) that renders a sandboxed `<iframe>` to embed Micro-Frontend (MFE) applications inside Salesforce Lightning pages, Experience sites, and other LWC-enabled surfaces.
+
+## Key Capabilities
+
+- Sandboxed `<iframe>` rendering inside a closed Shadow DOM
+- Cross-origin communication with embedded MFE apps via `postMessage` bridge
+- Configurable sandbox tokens, fullscreen mode, automatic resize, and theme forwarding
+- Dirty-state tracking with unsaved-changes confirmation modal
+- Framework-agnostic — extends `HTMLElement` directly
+
+## Documentation
+
+| Document | Description |
+|---|---|
+| [LWC_SHELL_WEB_COMPONENT_API.md](./LWC_SHELL_WEB_COMPONENT_API.md) | Full specification of the `<lwc-shell>` web component — attributes, properties, methods, events, and sandbox security. |
+| [LWC_SHELL_WRAPPER_GUIDE.md](./LWC_SHELL_WRAPPER_GUIDE.md) | Step-by-step guide to writing an LWC wrapper, from setup and vendor build through to deployment, with a complete code recipe. |
+
+## Package Contents
+
+| Path | Purpose |
+|---|---|
+| `src/InternalHostLwcShell.ts` | Core web component implementation (`<lwc-shell>` custom element). |
+| `src/utils/` | Shared utilities — symbol keys, dirty-state contract, GUID generator. |
+| `src/lwc/` | Source LWC components (e.g. `dirtyStateModal`) that are vendored into consumer projects. |
+| `scripts/vendor-build.js` | CLI tool (`lwc-shell-vendor-build`) that copies built artifacts as vendor-prefixed LWC components. |

package/dist/InternalHostLwcShell.d.ts

@@ -0,0 +1,137 @@
+/**
+ * InternalHostLwcShell
+ *
+ * A standard Web Component (custom element) that embeds an iframe-based widget
+ * with bridge communication, sandbox management, fullscreen support, and
+ * dirty-state tracking.
+ *
+ * Registered as `<lwc-shell>`.
+ *
+ * Ported from the LWC `widgetContainerLo` component (formerly known as
+ * WidgetContainer) — all Lightning Web Component framework dependencies have
+ * been removed so this can run as a plain custom element inside any LWC host.
+ *
+ * **How customers use this:**
+ * 1. The build produces `dist/index.esm.js` which bundles this class.
+ * 2. Customers copy that file into their SFDX project as an LWC entity
+ *    (e.g. `c/lwcShell`) and deploy it to their Salesforce org.
+ * 3. A wrapper LWC imports `'c/lwcShell'` and creates `<lwc-shell>`
+ *    imperatively via `document.createElement('lwc-shell')`.
+ *
+ * See the README and the `productRegistrationWidgetLo` demo for a full recipe.
+ */
+import { DoCloseConfirmation, Guid } from "./utils";
+interface DirtyStateModalButton {
+    buttonKey: string;
+    buttonLabel: string;
+    buttonVariant?: string;
+}
+interface DirtyStateModalFields {
+    label?: string;
+    description?: string;
+    buttons?: DirtyStateModalButton[];
+}
+/**
+ * Represents a LightningModal-style class with a static `.open()` method.
+ */
+interface DirtyStateModalClass {
+    open(config: {
+        modalFields?: DirtyStateModalFields;
+        size?: string;
+    }): Promise<string | undefined>;
+}
+export declare class InternalHostLwcShell extends HTMLElement {
+    private _shadow;
+    private _iframe;
+    private _container;
+    private _currentState;
+    private _hasExplicitResize;
+    private _readinessTimeout;
+    private _isFullscreen;
+    private _lastThemeData;
+    private _lastPayloadData;
+    private _bridgeReady;
+    private _hasSentTheme;
+    private _hasSentData;
+    private _src;
+    private _srcdoc;
+    private _sandbox;
+    private _title;
+    private _view;
+    private _dirtyComponentGuid;
+    private _beforeUnloadHandler;
+    private _dirtyStateModal;
+    private _pendingDirtyActions;
+    private _debugEnabled;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void;
+    get src(): string | null;
+    set src(v: string | null);
+    get srcdoc(): string | null;
+    set srcdoc(v: string | null);
+    get sandbox(): string | null;
+    set sandbox(v: string | null);
+    get title(): string;
+    set title(v: string | null);
+    get view(): string | null;
+    set view(v: string | null);
+    /**
+     * Controls debug logging. Toggle via:
+     * - HTML attribute: `<lwc-shell debug>`
+     * - Programmatically: `shell.debug = true`
+     */
+    get debug(): boolean;
+    set debug(v: boolean);
+    get _SelfManagedDirtyComponent(): Readonly<{
+        DoCloseConfirmation: typeof DoCloseConfirmation;
+        Guid: typeof Guid;
+    }>;
+    /**
+     * The LightningModal class used to show the unsaved-changes confirmation.
+     * Wrapper LWC sets this via: `shell.dirtyStateModal = DirtyStateModal;`
+     * where `DirtyStateModal` is the class imported from `'c/dirtyStateModal'`.
+     */
+    get dirtyStateModal(): DirtyStateModalClass | null;
+    set dirtyStateModal(v: DirtyStateModalClass | null);
+    updateData(newData: Record<string, unknown>): void;
+    refreshTheme(): void;
+    private get _isFullView();
+    private get _frameClass();
+    private _log;
+    private _renderInitial;
+    private _updateContainerState;
+    private _updateTitle;
+    private _updateViewDOM;
+    private _setState;
+    private _setupMessageListener;
+    private _handleMessage;
+    private _dispatchSelfManagedDirtyEvent;
+    private _toggleBeforeUnload;
+    private _handleDirtyStateDetected;
+    private _handleDirtyStateReset;
+    private _handleDirtyStateModalStatus;
+    private _handleResize;
+    private _handleWidgetReady;
+    private _handleFullscreenRequest;
+    private _enterFullscreen;
+    private _exitFullscreen;
+    private _handleBridgeReady;
+    private _handleBridgeError;
+    private _handleContainerClick;
+    private _applySandbox;
+    private _computeSandboxTokens;
+    private _updateIframeSrc;
+    private _handleIframeLoad;
+    private _handleIframeError;
+    private _postToIframe;
+    private _collectDataAttributes;
+    private _sendInitialTheme;
+    private _sendInitialData;
+    [Guid]: string;
+    [DoCloseConfirmation](): Promise<"SUCCESS" | "CANCEL" | "ERROR">;
+}
+export {};
+//# sourceMappingURL=InternalHostLwcShell.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @lightning-out/lwc-shell — Public entry point.
+ *
+ * Importing this module auto-registers the `<lwc-shell>` custom element
+ * via `customElements.define`. The bundled output (`dist/index.esm.js`) is
+ * what customers copy into their SFDX project as an LWC entity so the custom
+ * element is available at runtime on the Salesforce org.
+ *
+ * See the package README for the full integration guide.
+ */
+export { InternalHostLwcShell } from "./InternalHostLwcShell";
+export { InternalHostLwcShell as default } from "./InternalHostLwcShell";
+//# sourceMappingURL=index.d.ts.map