@lwrjs/everywhere 0.8.0-alpha.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/LICENSE +10 -0
  2. package/README.md +282 -0
  3. package/build/assets/amd/lwr-everywhere-debug.js +1344 -0
  4. package/build/assets/amd/lwr-everywhere-min.js +1 -0
  5. package/build/assets/amd/lwr-everywhere.js +1344 -0
  6. package/build/assets/core/lwr-everywhere-debug.js +1344 -0
  7. package/build/assets/core/lwr-everywhere-min.js +1 -0
  8. package/build/assets/core/lwr-everywhere.js +1344 -0
  9. package/build/assets/esm/lwr-everywhere-debug.js +58 -0
  10. package/build/assets/esm/lwr-everywhere-min.js +1 -0
  11. package/build/assets/esm/lwr-everywhere.js +58 -0
  12. package/build/es/amd-client.d.ts +6 -0
  13. package/build/es/amd-client.js +39 -0
  14. package/build/es/esm-client.d.ts +3 -0
  15. package/build/es/esm-client.js +13 -0
  16. package/build/es/generate.d.ts +7 -0
  17. package/build/es/generate.js +127 -0
  18. package/build/es/index.d.ts +13 -0
  19. package/build/es/index.js +36 -0
  20. package/build/es/utils.d.ts +22 -0
  21. package/build/es/utils.js +40 -0
  22. package/build/modules/lwr/everywhere/everywhere.js +37 -0
  23. package/build/modules/lwr/everywhereAmd/everywhereAmd.js +61 -0
  24. package/build/modules/lwr/everywhereEsm/everywhereEsm.js +16 -0
  25. package/build/modules/lwr/host/host.html +5 -0
  26. package/build/modules/lwr/host/host.js +127 -0
  27. package/build/modules/lwr/vault/vault.js +10 -0
  28. package/package.cjs +9 -0
  29. package/package.json +67 -0
package/LICENSE ADDED
@@ -0,0 +1,10 @@
1
+ MIT LICENSE
2
+
3
+ Copyright (c) 2020, Salesforce.com, Inc.
4
+ All rights reserved.
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
7
+
8
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
9
+
10
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,282 @@
1
+ # LWR Everywhere
2
+
3
+ - [Displaying components](#displaying-components)
4
+ - [1. Add a container to the HTML](#1-add-a-container-to-the-html)
5
+ - [2. Import the LWR Everywhere Module](#2-import-the-lwr-everywhere-module)
6
+ - [3. Authenticate](#3-authenticate)
7
+ - [4. Display a component](#4-display-a-component)
8
+ - [Interactivity](#interactivity)
9
+ - [Update component properties](#update-component-properties)
10
+ - [Client-side Navigation](#client-side-navigation)
11
+ - [UI API Adapters](#ui-api-adapters)
12
+ - [Connected App setup](#connected-app-setup)
13
+ - [Build your own LWR Everywhere module](#build-your-own-lwr-everywhere-module)
14
+ - [API reference](#api-reference)
15
+ - [Client APIs](#client-apis)
16
+ - [`authenticate`](#authenticate)
17
+ - [`createComponent`](#createcomponent)
18
+ - [Server APIs](#server-apis)
19
+ - [`generate`](#generate)
20
+
21
+ LWR Everywhere allows you to embed [Lightning web components](https://developer.salesforce.com/docs/component-library/documentation/lwc) into your web page or app using just a few lines of code. LWR Everywhere is powered by the Lightning Web Stack, which provides:
22
+
23
+ - full use of the [Lightning Web Components](https://developer.salesforce.com/docs/component-library/documentation/en/lwc) framework
24
+ - out-of-the-box security with [Lightning Web Security](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/security_lwsec_intro)
25
+ - support for the [Salesforce Lightning Design System (SLDS)](https://www.lightningdesignsystem.com/getting-started/)
26
+ - [UI API adapter](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.reference_ui_api) integration
27
+
28
+ ## Displaying components
29
+
30
+ This section goes through the steps to display a Lightning web component on your website. No special tools or setup needed!
31
+
32
+ ### 1. Add a container to the HTML
33
+
34
+ First, open the HTML page you want to edit. Add an empty `<div>` tag anywhere within the `<body>` to mark where you want to display a Lightning web component. For example:
35
+
36
+ ```html
37
+ <!-- ... existing HTML ... -->
38
+ <div id="embed-stats"></div>
39
+ <!-- ... existing HTML ... -->
40
+ ```
41
+
42
+ This `<div>` has a unique `id` attribute. This allows us to find it later so we can embed a component in it.
43
+
44
+ ### 2. Import the LWR Everywhere Module
45
+
46
+ Add a [JavaScript module script](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#applying_the_module_to_your_html) to the HTML page. For example:
47
+
48
+ ```html
49
+ <script type="module" src="lwre.js"></script>
50
+ ```
51
+
52
+ Import the `authenticate` and `createComponent` APIs from the **LWR Everywhere module**. For example:
53
+
54
+ ```js
55
+ // lwre.js
56
+ // Import the LWR Everywhere module
57
+ import { authenticate, createComponent } from 'https://lwr-server.com/resource/path/lwr-everywhere.js';
58
+ ```
59
+
60
+ > **Tip**: Use a minified version of the LWR Everywhere module by importing `lwr-everywhere-min.js` and a debug version with `lwr-everywhere-debug.js`.
61
+
62
+ ### 3. Authenticate
63
+
64
+ In order to access components from your Salesforce org, you must be authenticated. LWR Everywhere doesn’t handle authentication, so you must provide it with a Salesforce authentication token and instance URL. For example:
65
+
66
+ ```js
67
+ // lwre.js
68
+ import { authenticate, createComponent } from 'https://lwr-server.com/resource/path/lwr-everywhere.js';
69
+
70
+ const { access_token, instance_url } = getAuthData(); // you write this logic
71
+ authenticate({ access_token, instance_url });
72
+ ```
73
+
74
+ > **Note**: The authentication data is obtained from an [OAuth flow](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_flows.htm&type=5) into your [Connected App](#connected-app-setup).
75
+
76
+ ### 4. Display a component
77
+
78
+ After authenticating, embed a Lightning web component on your website. For example:
79
+
80
+ ```js
81
+ // lwre.js
82
+ import { authenticate, createComponent } from 'https://lwr-server.com/resource/path/lwr-everywhere.js';
83
+
84
+ const { access_token, instance_url } = getAuthData();
85
+ authenticate({ access_token, instance_url });
86
+
87
+ createComponent('my/stats', 'embed-stats', { category: 'cats', darkMode: true });
88
+ ```
89
+
90
+ And that's it!
91
+
92
+ This one line of code displays the "my/stats" component in the `<div>` we created in [the first step](#1-add-a-container-to-the-html), and passes in some [public properties](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.reactivity_public) (`category` and `darkMode`).
93
+
94
+ > **Tip**: Check out the API reference for [`authenticate`](#authenticate) and [`createComponent`](#createcomponent).
95
+
96
+ ## Interactivity
97
+
98
+ After creating a component, you can interact with it.
99
+
100
+ ### Update component properties
101
+
102
+ Update a component's [public properties](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.reactivity_public) to add reactivity. For example:
103
+
104
+ ```js
105
+ const container = document.querySelector('#counter-container');
106
+ const counter = createComponent('my/counter', container, { count: 6 });
107
+ // ... time passes ...
108
+ counter.properties = { count: 9 };
109
+ ```
110
+
111
+ ### Client-side Navigation
112
+
113
+ If the embedded component uses the [LWR Client-side Router](https://github.com/salesforce-experience-platform/lwr-recipes/blob/main/doc/navigation.md), turn on the `navigation` setting. Then you can navigate programmatically and subscribe to navigation events and errors. For example:
114
+
115
+ ```js
116
+ import { createComponent } from 'https://lwr-server.com/resource/path/lwr-everywhere.js';
117
+ const cmp = createComponent('my/cmp', 'container', { mode: 'compact' }, { navigation: true });
118
+
119
+ // Navigate by updating the current page reference
120
+ cmp.pageReference = { type: 'standard__namedPage', attributes: { pageName: 'home' } };
121
+
122
+ // Subscribe to navigation events and errors
123
+ cmp.addEventListener('navigate', ({ detail }) => {
124
+ console.log('Navigated to page reference:', detail);
125
+ });
126
+ cmp.addEventListener('navigationerror', ({ detail: { code, message } }) => {
127
+ console.error(`Navigation error: ${code} - ${message}`);
128
+ });
129
+ ```
130
+
131
+ ### UI API Adapters
132
+
133
+ > **Important**: This feature is currently under construction!
134
+
135
+ LWR Everywhere supports the [UI API adapters](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.reference_ui_api). For example, this code shows an embedded component requesting a list of Opportunities from a Salesforce org via the [`getListInfoByName` wire](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.reference_get_list_ui):
136
+
137
+ ```ts
138
+ import { LightningElement, wire } from 'lwc';
139
+ import { getListInfoByName } from 'lightning/uiListApi';
140
+
141
+ export default class MyData extends LightningElement {
142
+ opportunities = [];
143
+ @wire(getListInfoByName, {
144
+ objectApiName: 'Opportunity',
145
+ listViewApiName: 'AllOpportunities',
146
+ })
147
+ listView({ error, data }): void {
148
+ if (data) {
149
+ this.opportunities = data.records.records;
150
+ } else if (error) {
151
+ console.error(`Failed to fetch Opportunities: ${error.body.message}`);
152
+ }
153
+ }
154
+ }
155
+ ```
156
+
157
+ ## Connected App setup
158
+
159
+ To enable authentication with LWR Everywhere, follow these steps to set up a secure Connected App:
160
+
161
+ 1. Create a Connected App with OAuth Settings using these [instructions](https://help.salesforce.com/articleView?id=sf.connected_app_create_api_integration.htm&type=5) and:
162
+ 1. **If** a client-side authentication flow is being used, set the "Callback URL" to the URL of the HTML page (e.g. `"https://my-website.com/page"`)
163
+ 1. Make a note of the "Consumer Key" and "Consumer Secret" (if applicable)
164
+ 1. Under _Setup_ -> _Manage Connected Apps_, click "Edit" for the app and set "Permitted Users" to "Admin approved users are pre-authorized" and "Save"
165
+ 1. Approve Profiles for Connected App access:
166
+ 1. Go to _Setup_ -> _Profiles_
167
+ 1. Select the desired Profile and click "Assigned Connected Apps"
168
+ 1. Add the Connected App to the "Enabled Connected Apps" list and click "Save"
169
+ 1. Enabled CORS for the website, **if** a client-side authentication flow is being used:
170
+ 1. Go to _Setup_ -> _CORS_
171
+ 1. Add a new "Allowed Origin" for the website (e.g. `"https://my-website.com"`)
172
+ 1. Setup a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
173
+ 1. Add a `script-src` CSP to the web page containing the Connected App origin, and `'unsafe-eval'` to support [Lightning Web Security](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/security_lwsec_intro). For example:
174
+ ```html
175
+ <meta
176
+ http-equiv="Content-Security-Policy"
177
+ content="script-src 'unsafe-eval' https://connected-app-server.com"
178
+ />
179
+ ```
180
+
181
+ ## Build your own LWR Everywhere module
182
+
183
+ For the majority of use cases, you simply import the [LWR Everywhere Module](#2-import-the-lwr-everywhere-module) from your Salesforce org. However, you can also generate your own **custom** LWR Everywhere module and host it yourself. For example:
184
+
185
+ ```js
186
+ // Import my custom LWR Everywhere module
187
+ import { authenticate, createComponent } from './static/my-lwr-everywhere.js';
188
+ ```
189
+
190
+ Use the `generate()` API from the `@lwrjs/everywhere/generate` server module to build the file. For example:
191
+
192
+ ```js
193
+ // my-package/scripts/generate-client-runtime.mjs
194
+ import { generate } from '@lwrjs/everywhere/generate';
195
+
196
+ generate({
197
+ format: 'amd', // this is the only required option
198
+ server: 'https://lwr-server.com',
199
+ apiVersion: 'v57.0',
200
+ apiPrefix: '/lwr',
201
+ locale: 'fr',
202
+ bundle: false,
203
+ debug: true,
204
+ minify: true,
205
+ outFile: 'static-site/public/lwrEverywhere.js',
206
+ })
207
+ .then(() => {
208
+ console.log('>> successfully built the LWR Everywhere module');
209
+ process.exit(0);
210
+ })
211
+ .catch((e) => {
212
+ console.error('>> ERROR generating the LWR Everywhere module:', e);
213
+ process.exit(1);
214
+ });
215
+ ```
216
+
217
+ > **Tip**: Check out the API reference for [`generate`](#generate).
218
+
219
+ ## API reference
220
+
221
+ ### Client APIs
222
+
223
+ Import these functions from the [LWR Everywhere Module](#2-import-the-lwr-everywhere-module).
224
+
225
+ #### `authenticate`
226
+
227
+ ```ts
228
+ interface AuthData {
229
+ access_token: string;
230
+ instance_url: string;
231
+ }
232
+ type AuthenticateFunction = (authData?: AuthData) => void;
233
+ ```
234
+
235
+ #### `createComponent`
236
+
237
+ ```ts
238
+ type CreateComponentFunction = (
239
+ specifier: string, // component specifier: "namespace/name" OR versioned: "namespace/name/v/2.0"
240
+ nodeId: string | HTMLElement, // either a DOM node or its id
241
+ properties: Record<string, any>, // default: {}
242
+ config: { navigation: boolean }, // default { navigation: false }
243
+ ) => Promise<EverywhereComponent>;
244
+
245
+ interface EverywhereComponent extends Element {
246
+ properties: Record<string, any>; // update a component's public properties
247
+ pageReference?: PageReference; // update the current page reference in the LWR Router
248
+ }
249
+
250
+ interface PageReference {
251
+ type: string;
252
+ attributes?: Record<string, string | null>;
253
+ state?: Record<string, string | null>;
254
+ }
255
+ ```
256
+
257
+ ### Server APIs
258
+
259
+ Import these functions from `@lwrjs/everywhere/generate`.
260
+
261
+ #### `generate`
262
+
263
+ ```ts
264
+ interface GenerationOptions {
265
+ // Required options
266
+ format: 'esm' | 'amd'; // format for component code, LWR-S only supports 'amd'
267
+
268
+ // Optional
269
+ server?: string; // LWR server origin, default: import.meta.url
270
+ apiVersion?: string; // LWR API version (eg: 'v57.0'), default: '1'
271
+ apiPrefix?: string; // LWR API prefix (eg: '/lwr'), default: ''
272
+ locale?: string; // default: LWR server default locale
273
+ bundle?: boolean; // bundle the component code if true, default: true
274
+ debug?: boolean; // use debug mode if true, default: false
275
+
276
+ // File options, relative paths appended to the CWD
277
+ minify?: boolean; // minify the module code if true, default: false
278
+ outFile?: string; // the module output file path, default: '__lwr_client__/lwr-everywhere.js'
279
+ }
280
+
281
+ type GenerateFunction = (options: GenerationOptions) => Promise<void>;
282
+ ```