# 🎨 Beam Web Component Beam web components is a library of web components for the Beam Design System. These components are built using [Lit](https://lit.dev/) (a web components library created by Google) and are designed to be used in any web project. 🌎 Our library includes support for various formats and stacks to suit different needs, such as: **Frameworks** - **Vanilla JS support**: Incorporate our components in Vanilla JS projects, providing a versatile and adaptable solution for your project. - **Angular support**: Utilize our components in Angular projects, ensuring compatibility with your existing stack.

**Importing** - **Importing from NPM**: Easily import and utilize our package directly from NPM, ensuring a seamless integration into your project. - **Importing locally**: Download and use our package locally, providing a flexible and customizable approach for your project. ## 🔖 Table of Contents 1. [âŦ‡ī¸ Installation](#âŦ‡ī¸-installation) - [đŸ“Ļ NPM Installation](#-npm) - [đŸ’ģ Local Installation (Without npm)](#-local-installation-without-npm) 2. [🧠 VS Code IntelliSense Setup](#-vs-code-intellisense-setup) 3. [🛠ī¸ Usage](#usage) 4. [📚 Documentation](#documentation) ## âŦ‡ī¸ Installation ### đŸ“Ļ NPM The easiest and most straightforward way to install `@viasat/beam-web-components` is via NPM. #### 1. Install the package ```bash npm install @viasat/beam-web-components ``` ```bash yarn add @viasat/beam-web-components ``` ```bash pnpm add @viasat/beam-web-components ``` #### 2. Import and use the components > ℹī¸ Import the fonts and tokens at the root of your application and import each component per page to ensure bundlers like webpack and rollup can optimally code split and tree shake the components. ```ts // index.js import '@viasat/beam-tokens/styles.css'; import '@viasat/beam-fonts/styles.css'; // my-page.js import '@viasat/beam-web-components/Alert'; ```
### đŸ’ģ Local Installation (Without npm) For airgapped (no internet access) environments or when you need to vendor the files directly without a package manager, you can use the pre-bundled web components build. > ⚠ī¸ **Note**: This approach is for special scenarios only. If you have npm/artifactory access, use the [NPM installation method](#-npm) instead - it's simpler and handles dependencies automatically. #### 1. Download the bundled package Contact your Beam administrator or download directly from npm registry: ```bash npm pack @viasat/beam-web-components ``` This downloads the package as `beam-web-components-[VERSION].tgz`. The bundled version includes all dependencies (lit, floating-ui, etc.) pre-compiled into the output. #### 2. Extract web-components to your project ```bash mkdir -p vendor/@viasat/beam-web-components tar -xvf beam-web-components-[VERSION].tgz -C vendor/@viasat/beam-web-components/ --strip-components=1 ``` The bundled components are in the `local/` directory. #### 3. Download and extract tokens and fonts ```bash # Download and extract tokens npm pack @viasat/beam-tokens mkdir -p vendor/@viasat/beam-tokens tar -xvf beam-tokens-[VERSION].tgz -C vendor/@viasat/beam-tokens/ --strip-components=1 # Download and extract fonts npm pack @viasat/beam-fonts mkdir -p vendor/@viasat/beam-fonts tar -xvf beam-fonts-[VERSION].tgz -C vendor/@viasat/beam-fonts/ --strip-components=1 ``` **Expected Directory Structure:** ``` vendor/ └── @viasat/ ├── beam-web-components/ │ ├── local/ # Bundled components (use these) │ │ ├── Alert/ │ │ │ └── Alert.js │ │ ├── Button/ │ │ ├── Badge/ │ │ ├── chunks/ # Shared code chunks │ │ └── ... │ └── package.json ├── tokens/ │ └── tokens.css # Design tokens CSS └── fonts/ └── styles.css # Font styles ``` #### 4. Use in your HTML ```html My Web Page ``` #### Dependencies The bundled local build includes all JavaScript dependencies pre-compiled: **Bundled Dependencies** (included in the local build): - ✅ `lit` - Web components framework - ✅ `@lit/context` - Context API for Lit - ✅ `@floating-ui/dom` & `@floating-ui/utils` - Positioning utilities - ✅ `clsx` - Class name utility - ✅ `@viasat/beam-shared`, `@viasat/beam-styles`, `@viasat/beam-icons` - Beam internal packages **Required Packages** (must be downloaded separately - see step 3): - `@viasat/beam-tokens` - Design tokens (CSS variables) - `@viasat/beam-fonts` - Typography assets ## 🧠 VS Code IntelliSense Setup Enable intelligent autocomplete in VS Code for Beam web components, including component names, attributes, and their valid values. ### 1. Configure VS Code Settings Add the custom data files to your workspace settings (`.vscode/settings.json`): **For NPM installations:** ```json { "html.customData": [ "node_modules/@viasat/beam-web-components/vscode.html-custom-data.json" ], "css.customData": [ "node_modules/@viasat/beam-web-components/vscode.css-custom-data.json" ] } ``` **For local/vendored installations:** ```json { "html.customData": [ "vendor/@viasat/beam-web-components/vscode.html-custom-data.json" ], "css.customData": [ "vendor/@viasat/beam-web-components/vscode.css-custom-data.json" ] } ``` ### 2. Reload VS Code Reload your VS Code window to activate IntelliSense: - Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) - Type "Reload Window" and press Enter ### What You Get **Component Autocomplete:** - Type ` Button Text ``` ### Component Events Listen for custom events using standard DOM event listeners: ```javascript import '@viasat/beam-web-components/Alert'; const alert = document.querySelector('bm-alert'); alert.addEventListener('bm-dismiss', event => { console.log('Alert was dismissed'); }); ``` ### Component Slots Many components support content slots for flexible composition: ```html
Custom Alert Header

This is custom alert content using slots.

You can add any HTML content here!

 ``` ### Tree-shaking & Optimization Import only the components you need for optimal bundle size: ```js // ✅ Recommended: Import individual components import '@viasat/beam-web-components/Alert'; import '@viasat/beam-web-components/Button'; // ⚠ī¸ Avoid: Importing the entire library loads ALL components import '@viasat/beam-web-components'; ``` ### Framework Integration #### Angular ```typescript // In your component import '@viasat/beam-web-components/Button'; // In your template Angular Button ``` > ℹī¸ For advanced Angular integration including wrappers, two-way binding, and best practices, see the [Angular Guide](https://web-components.beam.viasat.com/?path=/docs/concepts-angular--docs). ### Theming Apply themes using CSS classes on your root element: ```html
Light Theme Button
Dark Theme Button
Blue Accent Button
``` > ℹī¸ For advanced theming documentation and use cases, see the [Theming Guide](https://web-components.beam.viasat.com/?path=/docs/concepts-theming--docs). ### Accessibility All components are built with accessibility in mind: - **ARIA Support** - Proper ARIA labels and roles - **Keyboard Navigation** - Full keyboard support - **Screen Reader Support** - Semantic markup and announcements - **Focus Management** - Proper focus handling and trapping ## Documentation ### Storybook Explore our comprehensive component library with live examples and API documentation: **📖 [Beam Web Components Storybook](https://web-components.beam.viasat.com/)** #### Component API Each component includes: - **Props Documentation** - Complete TypeScript definitions - **Usage Examples** - Common patterns and configurations - **Accessibility Notes** - ARIA labels, keyboard navigation, screen reader support - **Theming Options** - Available variants and customization points ### Additional Resources - **Design Tokens** - [@viasat/beam-tokens](https://www.npmjs.com/package/@viasat/beam-tokens) - **Icon Library** - [@viasat/beam-icons](https://www.npmjs.com/package/@viasat/beam-icons) - **Typography** - [@viasat/beam-fonts](https://www.npmjs.com/package/@viasat/beam-fonts)