Add doc for esm imports (#71)

* add doc for esm imports

* review

* review

Author: cojhal

sdk/va-report-components/README.md

@@ -13,22 +13,32 @@ Access to a deployment of SAS Visual Analytics 8.4 (or later) is necessary in or
 
 ### NPM
 
-The <a target="_blank" href="https://www.npmjs.com/package/@sassoftware/va-report-components">`@sassoftware/va-report-components`</a> library is published to NPM and can be installed by running the `npm install` command as shown below. `va-report-components` does not support ES6 imports. Therefore, the contents of the `va-report-components/dist` folder must be deployed with your page, and then loaded using a `script` tag.
+The <a target="_blank" href="https://www.npmjs.com/package/@sassoftware/va-report-components">`@sassoftware/va-report-components`</a> library is published to NPM and can be installed by running the `npm install` command as shown below. `va-report-components` can then be loaded with either a `script` tag or with an ES module import.
 
 ```bash
 # From the root directory of your project
 npm install @sassoftware/va-report-components
+```
+
+When using a `script` tag, the contents of the `va-report-components/dist` folder must be deployed with your page.
 
+```bash
 # Copy the contents of the package to an asset folder for deployment
 cp -r ./node_modules/@sassoftware/va-report-components ./sdk-assets
 ```
 
-The library can then be loaded out of the deployed assets folder using a `script` tag.
+The library can then be loaded out of the deployed assets folder.
 
 ```html
 <script async src="./sdk-assets/dist/umd/va-report-components.js"></script>
 ```
 
+If your site is built using a code bundler, it might be more convenient to load the library through ES module imports. See the <a target="_blank" href="https://developer.sas.com/sdk/va/docs/guides/esm/">ES module imports guide</a> for more details.
+
+```js
+import "@sassoftware/va-report-components"
+```
+
 ### CDN (Content Delivery Network)
 
 Accessing the `va-report-components` library from the SAS Developer CDN is easy. It does not require installation or

sdk/va-report-components/documentation/docs/api-reference.md

@@ -33,3 +33,11 @@ assets are loaded. The `vaReportComponents.loaded` event is dispatched once it i
   });
 </script>
 ```
+
+## Loading with imports
+
+When you load the library as an ES module, APIs are available as named imports. See the [ES module imports guide](guides/esm.md) for more information about loading the library as a module.
+
+```ts
+import { connectToServer } from '@sassoftware/va-report-components';
+```

sdk/va-report-components/documentation/docs/api/setFormatterLocale.md

@@ -15,16 +15,30 @@ setFormatterLocale(locale): void
 
 The locale should be specified as a language code and an optional country code. This is the same format that is used by [navigator.language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language)
 
-### Examples
+## Examples
+
+### Script Tag
 
 ```javascript
-window.addEventListener("vaReportComponents.loaded", function () {
+window.addEventListener("vaReportComponents.loaded", function() {
   vaReportComponents.setFormatterLocale("fr");
 });
 ```
 
 ```javascript
-window.addEventListener("vaReportComponents.loaded", function () {
+window.addEventListener("vaReportComponents.loaded", function() {
   vaReportComponents.setFormatterLocale("fr-CA");
 });
 ```
+
+### ESM
+
+```javascript
+import { setFormatterLocale } from "@sassoftware/va-report-components";
+setFormatterLocale("fr");
+```
+
+```javascript
+import { setFormatterLocale } from "@sassoftware/va-report-components";
+setFormatterLocale("fr-CA");
+```

sdk/va-report-components/documentation/docs/api/setLoadingTheme.md

@@ -9,7 +9,6 @@ setLoadingTheme(options): void
 
 `setLoadingTheme` allows the user to set the theme of the sdk before a report loads. You might want to set the theme for the initial loading state to match the website that the SAS Visual Analytic SDK is embedded in. You also might want to set the loading theme to be consistent with the report that will be loaded.
 
-
 `setLoadingTheme` only affects the initial loading and logon states. It does not affect the report theme once a report has been loaded.
 
 ## Arguments
@@ -18,33 +17,50 @@ setLoadingTheme(options): void
 
 When you select `'light'`, `'dark'`, or `'high-contrast'`, then the loading theme is based on one of the built-in themes.
 
-
 Alternatively, you can specify theme values. The following optional properties are supported:
 
 - `baseTheme: 'light' | 'dark'`: The base theme that is used for loading the theme values. The theme values are used when no defaults are provided. For example, if backgroundColor is not specified and the baseTheme is light, then the backgoundColor will be white since that is the theme's background color. **default**:`light`
 
 You can further customize the loading style with additional style properties. Some examples are provided below to show you how certain options affect the theme. The following style overrides are available:
+
 - `primary: string`: The logon button background and loading indicator.
 - `backgroundColor: string`
 - `textColor: string`
 - `textColorInverse: string` The button text color for the logon state.
 - `fontFamily: string`
 
+## Examples
 
-### Examples
+### Script Tag
 
 ```javascript
-  window.addEventListener('vaReportComponents.loaded', function() {
-    vaReportComponents.setLoadingTheme('dark');
-  });
+window.addEventListener("vaReportComponents.loaded", function() {
+  vaReportComponents.setLoadingTheme("dark");
+});
 ```
 
 ```javascript
-  window.addEventListener('vaReportComponents.loaded', function() {
-    vaReportComponents.setLoadingTheme({
-      baseTheme: 'dark',
-      primary: '#FFA500',
-      fontFamily: 'Gothic',
-    });
+window.addEventListener("vaReportComponents.loaded", function() {
+  vaReportComponents.setLoadingTheme({
+    baseTheme: "dark",
+    primary: "#FFA500",
+    fontFamily: "Gothic",
   });
-```
+});
+```
+
+### ESM
+
+```javascript
+import { setLoadingTheme } from "@sassoftware/va-report-components";
+setLoadingTheme("dark");
+```
+
+```javascript
+import { setLoadingTheme } from "@sassoftware/va-report-components";
+setLoadingTheme({
+  baseTheme: "dark",
+  primary: "#FFA500",
+  fontFamily: "Gothic",
+});
+```

sdk/va-report-components/documentation/docs/api/setLocale.md

@@ -15,16 +15,30 @@ setLocale(locale): void
 
 The locale should be specified as a language code and an optional country code. This is the same format that is used by [navigator.language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language)
 
-### Examples
+## Examples
+
+### Script Tag
 
 ```javascript
-window.addEventListener("vaReportComponents.loaded", function () {
+window.addEventListener("vaReportComponents.loaded", function() {
   vaReportComponents.setLocale("fr");
 });
 ```
 
 ```javascript
-window.addEventListener("vaReportComponents.loaded", function () {
+window.addEventListener("vaReportComponents.loaded", function() {
   vaReportComponents.setLocale("fr-CA");
 });
 ```
+
+### ESM
+
+```javascript
+import { setLocale } from "@sassoftware/va-report-components";
+setLocale("fr");
+```
+
+```javascript
+import { setLocale } from "@sassoftware/va-report-components";
+setLocale("fr-CA");
+```

sdk/va-report-components/documentation/docs/getting-started.md

@@ -11,22 +11,32 @@ You can embed entire reports with the `<sas-report>` custom HTML element, embed
 
 ### NPM
 
-The <a target="_blank" href="https://www.npmjs.com/package/@sassoftware/va-report-components">`@sassoftware/va-report-components`</a> library is published to NPM and can be installed by running the `npm install` command as shown below. `va-report-components` does not support ES6 imports. Therefore, the contents of the `va-report-components/dist` folder must be deployed with your page, and then loaded using a `script` tag.
+The <a target="_blank" href="https://www.npmjs.com/package/@sassoftware/va-report-components">`@sassoftware/va-report-components`</a> library is published to NPM and can be installed by running the `npm install` command as shown below. `va-report-components` can then be loaded with either a `script` tag or with an ES module import.
 
 ```bash
 # From the root directory of your project
 npm install @sassoftware/va-report-components
+```
+
+When using a `script` tag, the contents of the `va-report-components/dist` folder must be deployed with your page.
 
+```bash
 # Copy the contents of the package to an asset folder for deployment
 cp -r ./node_modules/@sassoftware/va-report-components ./sdk-assets
 ```
 
-The library can then be loaded out of the deployed assets folder using a `script` tag.
+The library can then be loaded out of the deployed assets folder.
 
 ```html
 <script async src="./sdk-assets/dist/umd/va-report-components.js"></script>
 ```
 
+If your site is built using a code bundler, it might be more convenient to load the library through ES module imports. See the [ES module guide](guides/esm.md) for more details.
+
+```js
+import "@sassoftware/va-report-components"
+```
+
 ### CDN (Content Delivery Network)
 
 Accessing the `va-report-components` library from the SAS Developer CDN is easy. It does not require installation or

sdk/va-report-components/documentation/docs/guides/esm.md

@@ -0,0 +1,129 @@
+---
+id: esm
+title: ES Module Imports
+---
+
+Sites built using a code bundler may choose to load `@sassoftware/va-report-components` with ES module imports. When loaded this way, the APIs are available as named imports.
+
+[SASReportElement](api/SASReportElement.md) and the other custom elements are defined through side effects, so care must be taken to ensure `@sassoftware/va-report-components` is included at runtime. One way to do this is by adding a side effect import in the build's entry point or in the modules where `va-report-components` is used.
+
+```js
+import "@sassoftware/va-report-components";
+```
+
+A side effect import might not be necessary if the code uses an imported API directly.
+
+```js
+import { SASReportElement } from "@sassoftware/va-report-components";
+const report = new SASReportElement();
+document.body.appendChild(report);
+```
+
+For TypeScript applications, type imports are insufficent for ensuring that `va-report-components` will be included in the build.
+
+```ts
+// Type imports are NOT included at runtime
+import type { SASReportElement } from "@sassoftware/va-report-components";
+// This report will not load unless va-report-components is imported elsewhere
+const report = document.getElementById("my-report") as SASReportElement;
+```
+
+## Usage notes
+
+### Webpack
+
+#### Configuration
+
+`va-report-components` contains CSS files that might not work as intended when processed by webpack loaders. If your build uses loaders such as style-loader or css-loader, you should exclude `va-report-components`.
+
+```js
+// webpack.config.js
+export default {
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        use: ["style-loader", "css-loader"],
+        exclude: /va-report-components/,
+      },
+    ],
+  },
+};
+```
+
+#### SAS Report Packages
+
+If your site hosts [exported SAS Report Packages](guides/export-report-package.md) alongside your webpack build, they can be referenced relative to `__webpack_public_path__`.
+
+```js
+import { SASReportElement } from "@sassoftware/va-report-components";
+const report = new SASReportElement();
+report.packageUri = `${__webpack_public_path__}reports/ExampleReport.sasreportpkg`;
+```
+
+### Vite
+
+#### Configuration
+
+`va-report-components` references some assets with the `new URL("...", import.meta.url)` syntax, a feature not yet fully supported in Vite dev builds. In order to load `va-report-components` in Vite dev builds, `@sassoftware/va-report-components` must be excluded from `optimizeDeps` in the Vite config. Then, all CommonJS modules imported by the package, both directly and indirectly, must be re-included.
+
+```ts
+// vite.config.js
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ["@sassoftware/va-report-components"],
+    include: [
+      "@tanstack/react-query",
+      "classnames",
+      "handlebars",
+      "hoist-non-react-statics",
+      "prop-types",
+      "react-dom",
+      "react-fast-compare",
+      "react-redux",
+      "void-elements",
+      "warning",
+    ],
+  },
+});
+```
+
+Known CommonJS dependencies are listed above, but the actual list can vary between applications. When a module needs to be added to the list, a message is logged in the browser console. Here is an example:
+
+```text
+SyntaxError: The requested module '/node_modules/prop-types/index.js?v=4776a820' does not provide an export named 'default'
+```
+
+Production builds are not affected by this issue.
+
+#### SAS Report Packages
+
+If you include [exported SAS Report Packages](guides/export-report-package.md) in your Vite project's
+`public` directory, the packages can be referenced relative to `import.meta.env.BASE_URL`.
+
+```js
+import { SASReportElement } from "@sassoftware/va-report-components";
+const report = new SASReportElement();
+report.packageUri = `${import.meta.env.BASE_URL}reports/ExampleReport.sasreportpkg`;
+```
+
+### React
+
+Custom elements such as `sas-report` can be rendered in React, but the `class` prop should be used rather than `className`.
+
+```jsx
+import '@sassoftware/va-report-components';
+
+export const MyComponent(props) {
+  return (
+    <sas-report
+      class="my-class"
+      authenticationType="guest"
+      url="http://my-viya-server.com"
+      reportUri="/reports/reports/c3c6befb-3981-4c9e-b011-7dc11dec5e37"
+    ></sas-report>
+  )
+}
+```
+
+For more information, see [Custom HTML elements](https://react.dev/reference/react-dom/components#custom-html-elements) in the React documentation.

sdk/va-report-components/documentation/website/sidebars.json

@@ -1,7 +1,12 @@
 {
   "docs": {
     "Introduction": ["getting-started"],
-    "Guides": ["guides/viya-setup", "guides/export-report-package", "guides/data-driven-content"],
+    "Guides": [
+      "guides/viya-setup",
+      "guides/export-report-package",
+      "guides/data-driven-content",
+      "guides/esm"
+    ],
     "API Reference": [
       "api-reference",
       "api/SASReportElement",