@salesforce/vite-plugin-lwc-ui-bundle 1.130.0

package/docs/chat-wrapper-guide.md

@@ -0,0 +1,134 @@
+# Chat Wrapper Authoring Guide
+
+## Purpose
+
+Use this guide to add a chat-aware wrapper around an existing LWC component without
+changing the component internals.
+
+The wrapper reads tool output from ChatGPT/MCP, maps it into stable component props,
+and renders the existing component.
+
+## Architecture
+
+- **Wrapper (chat-aware):** reads tool output and reacts to updates.
+- **Mapper (shape-normalizer):** converts tool output variants into one prop contract.
+- **Core component (unchanged):** consumes `@api` props as if running in normal app code.
+
+Keep this rule: business UI stays in the core component, chat glue stays in wrapper/mapper.
+
+## Files and Responsibilities
+
+- `sf/lwc/bcx/chatContextAdapter/chatContextAdapter.js`
+  - `accessToolOutput()` for initial state.
+  - `subscribeToolOutput(listener)` for live updates.
+- `sf/lwc/bcx/<component>ChatMapper/<component>ChatMapper.js`
+  - Converts raw tool output into a strict prop object or `null`.
+- `sf/lwc/bcx/<component>ChatWrapper/<component>ChatWrapper.js`
+  - Calls mapper, stores mapped state, renders waiting/ready UI.
+- `sf/lwc/bcx/<component>ChatWrapper/<component>ChatWrapper.html`
+  - Renders loading state, waiting state, and wrapped component.
+- `src/app/bootstrap.js`
+  - Chooses which wrapper to mount at startup.
+
+## Step-by-Step: Create a New Wrapper
+
+### 1) Define the target prop contract
+
+Write down exactly what props the core component needs. Example (`recordDetail`):
+
+- `data`
+- `recordId`
+- `fieldMetadata`
+- `layout`
+- `picklistValues`
+- `changedFields`
+- `expandable`
+
+The mapper should always output this shape (or `null`).
+
+### 2) Implement mapper first
+
+Mapper requirements:
+
+- Accept both wrapped and raw shapes (`structuredContent`, raw object, nested aliases).
+- Normalize key aliases (`recordDetail` vs `record_detail`, etc).
+- Unwrap transport wrappers (`properties`, `oneOf*`) if present.
+- Return `null` when required data is missing (do not throw for bad payloads).
+- Keep pure and side-effect free.
+
+### 3) Implement wrapper component
+
+Wrapper behavior:
+
+- On `connectedCallback`, read initial output with `accessToolOutput()`.
+- Subscribe with `subscribeToolOutput()` for updates.
+- Call mapper and update tracked state.
+- Render:
+  - loading text while initializing,
+  - waiting text when mapping fails or no data,
+  - wrapped component when mapping succeeds.
+
+### 4) Keep fallback behavior explicit
+
+Current pattern is **no local sample-data fallback** inside chat wrappers.
+
+If tool output is absent, show waiting state and do not render partial UI.
+
+### 5) Add logs while debugging, remove noise after validation
+
+Temporary logs in wrapper are useful when validating event delivery/mapping.
+Keep logs concise and prefixed per wrapper.
+
+## RecordDetail Reference (Current)
+
+`recordDetail` currently supports:
+
+- `toolOutput.structuredContent.recordDetail`
+- `toolOutput.structuredContent.record_detail`
+- compatible direct structured/raw payload shapes
+
+Key mapping in `recordDetail` wrapper:
+
+- `data` -> `data`
+- `recordId` -> `record-id`
+- `fieldMetadata` -> `field-metadata`
+- `layout` -> `layout`
+- `picklistValues` -> `picklist-values`
+- `changedFields` -> `changed-fields`
+- `expandable` -> `expandable`
+
+## Manual Component Swap in `bootstrap.js`
+
+This branch uses one bootstrap path and mounts one wrapper directly.
+
+To test `recordList` wrapper instead of `recordDetail`, replace the import + tag in
+`src/app/bootstrap.js` with:
+
+```js
+const { default: RecordListChatWrapper } =
+  await import("../../sf/lwc/bcx/recordListChatWrapper/recordListChatWrapper.js");
+const wrapper = createElement("bcx-record-list-chat-wrapper", {
+  is: RecordListChatWrapper,
+});
+mountNode.appendChild(wrapper);
+```
+
+To switch back to `recordDetail`, restore:
+
+```js
+const { default: RecordDetailChatWrapper } =
+  await import("../../sf/lwc/bcx/recordDetailChatWrapper/recordDetailChatWrapper.js");
+const wrapper = createElement("bcx-record-detail-chat-wrapper", {
+  is: RecordDetailChatWrapper,
+});
+mountNode.appendChild(wrapper);
+```
+
+## Validation Checklist for Any New Wrapper
+
+- Mapper returns stable shape for valid payloads.
+- Mapper returns `null` for invalid/incomplete payloads.
+- Wrapper updates on `openai:set_globals`.
+- Waiting state shown when no tool output exists.
+- Wrapped component renders with mapped props when data exists.
+- `npm run build` succeeds after wrapper swap in `bootstrap.js`.

package/docs/user-guide.md

@@ -0,0 +1,377 @@
+# User Guide: Compiling LWC Components into a Static Bundle
+
+This guide walks through using `@salesforce/vite-plugin-lwc-ui-bundle` to compile
+your existing LWC components into a single self-contained `dist/index.html` —
+no server required, opens directly in a browser.
+
+---
+
+## Prerequisites
+
+- Node.js >= 20.0.0
+- Your LWC components already exist in a Salesforce DX project
+
+---
+
+## Project Structure
+
+The example project `my-lwc-app` uses the standard Salesforce DX flat structure:
+
+```
+my-lwc-app/
+├── force-app/main/default/lwc/
+│   ├── helloApp/                   ← component directly, no namespace folder
+│   │   ├── helloApp.js
+│   │   ├── helloApp.html
+│   │   └── helloApp.js-meta.xml
+│   └── helloMessage/
+│       ├── helloMessage.js
+│       ├── helloMessage.html
+│       └── helloMessage.js-meta.xml
+├── src/
+│   └── bootstrap.js                ← mounts root component
+├── index.html                      ← entry point
+├── vite.config.js                  ← plugin config
+└── package.json
+```
+
+Use `namespace: 'c'` in `vite.config.js` to tell the plugin to treat this flat
+structure as namespace `c` — components are then importable as `'c/helloApp'`.
+
+---
+
+## Step 1: Add Files
+
+### `package.json`
+
+```json
+{
+  "name": "my-lwc-app",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@lwc/rollup-plugin": "^9.0.0",
+    "@salesforce/vite-plugin-lwc-ui-bundle": "^1.0.0",
+    "vite": "^7.0.0",
+    "vite-plugin-singlefile": "^2.3.0"
+  },
+  "dependencies": {
+    "@salesforce-ux/design-system": "^2.29.1",
+    "lightning-base-components": "^1.28.17-alpha",
+    "lwc": "^9.0.0"
+  }
+}
+```
+
+### `vite.config.js`
+
+```js
+import { defineConfig } from "vite";
+import lwcVitePlugin from "@salesforce/vite-plugin-lwc-ui-bundle";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+export default defineConfig({
+  build: {
+    target: "esnext", // required for top-level await in bootstrap.js
+  },
+  plugins: [
+    lwcVitePlugin({
+      modules: {
+        // Flat DX structure: specify { path, namespace } per directory
+        // Use a plain string if your dir already has namespace sub-folders
+        dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }],
+
+        // Include if your components use lightning/* base components
+        npm: ["lightning-base-components"],
+      },
+    }),
+    viteSingleFile(), // inlines everything into a single index.html
+  ],
+});
+```
+
+### `index.html`
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>My LWC App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script>
+      globalThis.lwcRuntimeFlags = { DISABLE_SYNTHETIC_SHADOW: true };
+    </script>
+    <script type="module" src="/src/bootstrap.js"></script>
+  </body>
+</html>
+```
+
+### `src/bootstrap.js`
+
+```js
+import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
+import "@lwc/synthetic-shadow";
+import { createElement } from "lwc";
+
+// Import your root component using its LWC specifier: <namespace>/<componentName>
+import App from "c/helloApp";
+
+// Mount it — tag name is the kebab-case version of the specifier
+const el = createElement("c-hello-app", { is: App });
+document.getElementById("app").appendChild(el);
+```
+
+---
+
+## Step 2: Install Dependencies
+
+```bash
+npm install
+```
+
+---
+
+## Step 3: Build
+
+```bash
+npm run build
+```
+
+Output: `dist/index.html` — a single file with all JS and CSS inlined.
+
+---
+
+## Step 4: Test
+
+**Option A — Open directly in browser:**
+
+```bash
+open dist/index.html
+```
+
+**Option B — Dev server with live reload:**
+
+```bash
+npm run dev
+# Open http://localhost:5173
+```
+
+**Option C — Preview the production build:**
+
+```bash
+npm run preview
+# Open http://localhost:4173
+```
+
+---
+
+## Component Namespace Convention
+
+The plugin supports two directory structures:
+
+### Flat DX structure (standard Salesforce DX)
+
+```
+force-app/main/default/lwc/
+  helloApp/
+    helloApp.js
+```
+
+Use `{ path, namespace }` per directory to specify the namespace:
+
+```js
+modules: {
+  dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }];
+}
+```
+
+| Directory           | LWC Specifier      | HTML Tag          |
+| ------------------- | ------------------ | ----------------- |
+| `lwc/helloApp/`     | `'c/helloApp'`     | `c-hello-app`     |
+| `lwc/helloMessage/` | `'c/helloMessage'` | `c-hello-message` |
+
+### Namespaced structure
+
+```
+modules/
+  records/
+    accountOutputName/
+      accountOutputName.js
+```
+
+Omit `namespace` — the sub-directory name is used as the namespace:
+
+```js
+modules: {
+  dirs: ["modules"];
+}
+```
+
+| Directory                            | LWC Specifier                 | HTML Tag                      |
+| ------------------------------------ | ----------------------------- | ----------------------------- |
+| `modules/records/accountOutputName/` | `'records/accountOutputName'` | `records-account-output-name` |
+
+---
+
+## Common Errors
+
+### `Rollup failed to resolve import "lightning/button"`
+
+Your component uses a Lightning Base Component. Add to `vite.config.js`:
+
+```js
+modules: {
+  npm: ["lightning-base-components"];
+}
+```
+
+### `[scoped-module-providers] Unhandled import: @salesforce/label/...`
+
+Expected — the plugin returns the label key as display text by default.
+To provide real label values:
+
+```js
+import { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  providers: [builtins.label({ "c.Save": "Save", "c.Cancel": "Cancel" })],
+});
+```
+
+### Component renders but looks unstyled
+
+Add SLDS import to `src/bootstrap.js`:
+
+```js
+import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
+```
+
+### `[scoped-module-providers] Unhandled import: @salesforce/user/Id`
+
+Expected warning — `@salesforce/user/*` imports return `undefined` by default.
+To provide real values (e.g. current user ID), add the user provider:
+
+```js
+import { builtins } from "@salesforce/vite-plugin-lwc-ui-bundle";
+
+lwcVitePlugin({
+  providers: [
+    builtins.user({ Id: "005xx000001X8AAAA" }), // optional: override user fields
+  ],
+});
+```
+
+### `Top-level await is not available in the configured target environment`
+
+Your `bootstrap.js` uses top-level `await` (required when initialising the Data
+SDK). Add `target: 'esnext'` to the build config:
+
+```js
+export default defineConfig({
+  build: { target: "esnext" },
+  plugins: [...],
+});
+```
+
+### `Rollup failed to resolve import "force/someModule"`
+
+Core-only module — add a stub:
+
+```js
+// stubs/someModule.js
+export const someExport = () => {};
+```
+
+```js
+// vite.config.js
+lwcVitePlugin({ stubs: { "force/someModule": "./stubs/someModule.js" } });
+```
+
+---
+
+## Connecting to a Real Salesforce Org (lwcProxy)
+
+By default the plugin runs fully off-platform with mock data. To connect your
+components to a real Salesforce org in local dev — enabling `lightning/graphql`
+to execute real queries — add `lwcProxy()` alongside `lwcVitePlugin()`.
+
+### Prerequisites
+
+- Salesforce CLI installed and an org connected: `sf org display`
+- Additional packages: `@salesforce/sdk-data` and `@salesforce/ui-bundle`
+
+```bash
+npm install @salesforce/sdk-data @salesforce/ui-bundle
+```
+
+### 1. Add lwcProxy to vite.config.js
+
+```js
+import { defineConfig } from "vite";
+import lwcVitePlugin, { lwcProxy } from "@salesforce/vite-plugin-lwc-ui-bundle";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+export default defineConfig({
+  build: {
+    target: "esnext", // required for top-level await in bootstrap.js
+  },
+  plugins: [
+    lwcProxy(), // auto-reads sf CLI default org credentials
+    // lwcProxy({ orgAlias: "my-org", debug: true })  // explicit org + verbose logging
+    lwcVitePlugin({
+      modules: {
+        dirs: [{ path: "force-app/main/default/lwc", namespace: "c" }],
+      },
+    }),
+    viteSingleFile(),
+  ],
+});
+```
+
+### 2. Initialise the Data SDK in bootstrap.js
+
+The SDK must be initialised before any component that uses `lightning/graphql`
+mounts. Use a top-level `await` import to guarantee ordering:
+
+```js
+import "@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.css";
+import "@lwc/synthetic-shadow";
+import { createElement } from "lwc";
+
+// Initialise the Data SDK — lwcProxy() handles /services/* on the Vite dev server
+import { createDataSDK } from "@salesforce/sdk-data";
+try {
+  globalThis.__sfdc_sdk__ = await createDataSDK({
+    uiBundle: { basePath: "/" },
+  });
+} catch (_err) {
+  globalThis.__sfdc_sdk__ = {};
+}
+
+import App from "c/helloApp";
+const el = createElement("c-hello-app", { is: App });
+document.getElementById("app").appendChild(el);
+```
+
+### 3. Run the dev server
+
+```bash
+npm run dev
+# Terminal shows: [lwc-proxy] Connected to https://your-org.my.salesforce.com
+# Open http://localhost:5173
+```
+
+Components using `lightning/graphql` will now execute real GraphQL queries
+against your org. The proxy intercepts `/services/*` calls inside the Vite dev
+server — no separate proxy process needed.
+
+> **Note:** The `basePath: '/'` setting works for `npm run dev` only. For
+> production builds (`dist/index.html`), a standalone proxy server is required.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@salesforce/vite-plugin-lwc-ui-bundle",
+  "version": "1.130.0",
+  "description": "Vite plugin for compiling LWC components into static bundles for off-platform and MCP use",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "author": "Salesforce",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/salesforce-experience-platform-emu/webapps",
+    "directory": "packages/vite-plugin-lwc-ui-bundle"
+  },
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "lwc",
+    "lightning-web-components",
+    "salesforce",
+    "mcp",
+    "agentic",
+    "off-platform",
+    "compiler"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "import": "./dist/providers/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "rm -rf dist",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "peerDependencies": {
+    "@lwc/rollup-plugin": "^9.0.0",
+    "@salesforce/sdk-chat": "^1.123.0",
+    "@salesforce/ui-bundle": "^1.123.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@salesforce/ui-bundle": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@salesforce/sdk-chat": "^1.130.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.6"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}