# 🎨 Beam Styles

SCSS modules and component styles for the Beam Design System. This package provides modular, reusable styles that can be imported directly into your components or applications.

## 🔖 Table of Contents

1. [📋 Overview](#overview)
2. [💻 Installation](#installation)
3. [🛠️ Usage](#usage)
4. [📁 Package Structure](#package-structure)
5. [📦 CSS Modules](#css-modules)
6. [🎯 When to Use](#when-to-use)

## Overview

`@viasat/beam-styles` contains:

- **Component SCSS Modules** - Scoped styles for all Beam components
- **Utility Mixins** - Helper mixins for common styling patterns
- **CSS Variables** - Component-specific CSS custom properties
- **Design Tokens** - SCSS variables for spacing, animation, and constants

## Installation

```bash
npm install @viasat/beam-styles
```

> **Note**: This package is typically installed automatically as a dependency of `@viasat/beam-react` or for direct SCSS imports in custom implementations.

## Usage

### Component Styles

Import component SCSS modules directly:

```scss
@use '@viasat/beam-styles/components/button.module';
@use '@viasat/beam-styles/components/card.module';
@use '@viasat/beam-styles/components/alert.module';
```

### Utility Mixins

Access helpful mixins and functions:

```scss
@use '@viasat/beam-styles/utils/mixins';
@use '@viasat/beam-styles/utils/helpers';
@use '@viasat/beam-styles/utils/spacing';
```

### CSS Variables

Import component-specific CSS variables:

```scss
@use '@viasat/beam-styles/components/button.vars';
@use '@viasat/beam-styles/components/icon.vars';
```

### Complete Import

Import all component and utility styles:

```scss
@use '@viasat/beam-styles/all';
```

## Package Structure

```
@viasat/beam-styles/
├── components/              # Component SCSS modules
│   ├── button.module.scss
│   ├── button.vars.scss    # Component CSS variables
│   ├── card.module.scss
│   ├── alert.module.scss
│   └── ...
└── utils/                   # Utility styles
    ├── animation.scss
    ├── constants.scss
    ├── cursors.scss
    ├── globals.scss
    ├── helpers.scss
    ├── mixins.scss
    ├── spacing.scss
    └── tokens.scss
```

## CSS Modules

All component styles use CSS Modules with local scope by default:

```scss
// button.module.scss
.bm-button {
  // Base button styles
}

.bm-button--accent-filled {
  // Appearance/kind modifier styles
}

.bm-button--sm {
  // Size modifier styles
}
```

When imported in JavaScript/TypeScript:

```tsx
import styles from '@viasat/beam-styles/components/button.module.scss';

<button className={styles['bm-button']} />;
```

## Compiled CSS

Pre-compiled CSS is also available:

- `styles.css` - Full compiled CSS
- `styles.min.css` - Minified version
- `styles.css.map` - Source map

## Direct CSS Import

For non-SCSS projects:

```ts
import '@viasat/beam-styles/styles.css';
// Or for minified
import '@viasat/beam-styles/styles.min.css';
```

## When to Use

This package is intended for:

- ✅ Custom Beam implementations
- ✅ Direct SCSS imports in React/Vue/Angular apps
- ✅ Building custom components with Beam styling
- ✅ Theming and style customization

This package is **not needed** if you're using `@viasat/beam-react` or `@viasat/beam-web-components` components directly (styles are already included).

## Bundler Configuration

When importing SCSS files directly from `@viasat/beam-styles`, you'll need to configure your bundler to resolve `@viasat/beam-*` path aliases. This is required because Beam's SCSS files use internal imports like `@viasat/beam-tokens/components/Alert`.

### Vite

Configure the Sass preprocessor in your `vite.config.ts`:

```ts
import { defineConfig } from 'vite';
import * as path from 'path';
import { pathToFileURL } from 'node:url';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        importers: [
          {
            findFileUrl(url: string): URL | null {
              if (url.startsWith('@viasat/beam-tokens/')) {
                const relativePath = url.replace('@viasat/beam-tokens/', '');
                return pathToFileURL(
                  path.resolve(
                    'node_modules/@viasat/beam-tokens/src/lib',
                    relativePath,
                  ),
                ) as URL;
              }
              return null;
            },
          },
        ],
      },
    },
  },
});
```

### Webpack

Configure `sass-loader` in your Webpack config:

```js
// webpack.config.js
const path = require('path');
const { pathToFileURL } = require('node:url');

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              api: 'modern-compiler',
              sassOptions: {
                importers: [
                  {
                    findFileUrl(url) {
                      if (url.startsWith('@viasat/beam-tokens/')) {
                        const relativePath = url.replace('@viasat/beam-tokens/', '');
                        return pathToFileURL(
                          path.resolve(
                            __dirname,
                            'node_modules/@viasat/beam-tokens/src/lib',
                            relativePath,
                          ),
                        );
                      }
                      return null;
                    },
                  },
                ],
              },
            },
          },
        ],
      },
    ],
  },
};
```

### Next.js

For Next.js projects, add the Sass configuration to `next.config.js`:

```js
// next.config.js
const path = require('path');
const { pathToFileURL } = require('node:url');

/** @type {import('next').NextConfig} */
const nextConfig = {
  sassOptions: {
    api: 'modern-compiler',
    importers: [
      {
        findFileUrl(url) {
          if (url.startsWith('@viasat/beam-tokens/')) {
            const relativePath = url.replace('@viasat/beam-tokens/', '');
            return pathToFileURL(
              path.resolve(
                process.cwd(),
                'node_modules/@viasat/beam-tokens/src/lib',
                relativePath,
              ),
            );
          }
          return null;
        },
      },
    ],
  },
};

module.exports = nextConfig;
```

> **Note**: If you're only using pre-compiled CSS (`@viasat/beam-styles/styles.css`) or the `@viasat/beam-react` components directly, no bundler configuration is needed.

## Dependencies

- Requires a SASS/SCSS compiler (e.g., `sass`, `dart-sass`)
- Works with any CSS Modules implementation
- Bundler configuration required for direct SCSS imports (see above)

## License

MIT © Viasat