@salesforce/experimental-mfe-lwc-shell 2.2.0

package/README.md

@@ -0,0 +1,27 @@
+# @salesforce/experimental-mfe-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 via `trackdirtystate` event
+- Framework-agnostic — extends `HTMLElement` directly
+
+## Documentation
+
+| Document | Description |
+|---|---|
+| [Web Component API](./docs/LWC_SHELL_WEB_COMPONENT_API.md) | Full specification of the `<lwc-shell>` web component — attributes, properties, methods, events, and sandbox security. |
+| [LWC Wrapper Guide](./docs/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. |
+| [Dirty State Flow](./docs/DIRTY_STATE_FLOW.md) | How MFE widgets track unsaved changes via `trackdirtystate` and how the shell relays it to the host platform. |
+| [PostMessage Security](./docs/POSTMESSAGE_SECURITY.md) | Security model for `postMessage` communication between the shell and the embedded iframe. |
+
+## Package Contents
+
+| Path | Purpose |
+|---|---|
+| `src/InternalHostLwcShell.ts` | Core web component implementation (`<lwc-shell>` custom element). |
+| `scripts/vendor-build.mjs` | CLI tool (`lwc-shell-vendor-build`) that copies the built ESM bundle as a vendor-prefixed LWC component. |

package/dist/InternalHostLwcShell.d.ts

@@ -0,0 +1,98 @@
+/**
+ * InternalHostLwcShell
+ *
+ * A standard Web Component (custom element) that embeds an iframe-based widget
+ * with bridge communication, sandbox management, and fullscreen support.
+ *
+ * Registered as `<lwc-shell>`.
+ *
+ * Dirty-state tracking is handled via a simple `trackdirtystate`
+ * custom-event flow: the embedded widget dispatches `trackdirtystate`
+ * with `{ isDirty, instanceId, label }`, and this shell re-dispatches
+ * the event for the host LWC to observe.
+ *
+ * **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 `productRegistration` demo for a full recipe.
+ */
+export declare class InternalHostLwcShell extends HTMLElement {
+    private _shadow;
+    private _iframe;
+    private _container;
+    private _currentState;
+    private _readinessTimeout;
+    private _isFullscreen;
+    private _preFullscreenHeight;
+    private _lastThemeData;
+    private _lastPayloadData;
+    private _bridgeReady;
+    private _shellInstanceId;
+    private _hasSentTheme;
+    private _hasSentData;
+    private _src;
+    private _srcdoc;
+    private _sandbox;
+    private _title;
+    private _view;
+    private _debugEnabled;
+    private _pendingGraphQLCount;
+    private static readonly MAX_CONCURRENT_GRAPHQL;
+    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);
+    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 _handleResize;
+    private _handleWidgetReady;
+    private _handleFullscreenRequest;
+    private _enterFullscreen;
+    private _exitFullscreen;
+    private _handleBridgeReady;
+    private _handleBridgeError;
+    private _handleGraphQLRequest;
+    private _handleContainerClick;
+    private _applySandbox;
+    private _computeSandboxTokens;
+    private _updateIframeSrc;
+    private _handleIframeLoad;
+    private _handleIframeError;
+    private _postToIframe;
+    private _collectDataAttributes;
+    private _sendInitialTheme;
+    private _sendInitialData;
+}
+//# sourceMappingURL=InternalHostLwcShell.d.ts.map

package/dist/graphqlHandler.d.ts

@@ -0,0 +1,5 @@
+export declare function executeGraphQL(query: string, variables?: Record<string, any>): Promise<{
+    data: unknown;
+    errors?: unknown[];
+}>;
+//# sourceMappingURL=graphqlHandler.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @salesforce/experimental-mfe-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