# Nova Web Components (Vanilla)

Use Nova’s native Web Components directly in plain HTML/TypeScript without a framework. This package exposes the same UI components used across all Nova wrappers, ready to drop into any site or app.

- [Nova Web Components (Vanilla)](#nova-web-components-vanilla)
  - [Key Points](#key-points)
  - [Installation](#installation)
  - [Setting up Tailwind](#setting-up-tailwind)
    - [About Tailwind and the Nova Plugin](#about-tailwind-and-the-nova-plugin)
    - [1. Install Tailwind CSS](#1-install-tailwind-css)
    - [2. Configure Vite](#2-configure-vite)
    - [3. Configure Tailwind and Nova in your CSS](#3-configure-tailwind-and-nova-in-your-css)
    - [4. Register components](#4-register-components)
    - [5. Use components in HTML with Tailwind utilities](#5-use-components-in-html-with-tailwind-utilities)
    - [Dark mode](#dark-mode)
    - [Deprecated JavaScript configuration](#deprecated-javascript-configuration)
  - [Nova Font Pro Integration](#nova-font-pro-integration)

---

## Key Points

- Tailwind CSS is required. Nova’s CSS-only Tailwind plugin binds Nova design tokens to Tailwind’s utilities for consistent, token-driven styling.
- Do not import `nova-utils.css` when using Tailwind. The Tailwind pipeline produces a smaller, optimized bundle and richer utilities.
- Import exactly one token CSS file (`spark.css` or `ocean.css`) so the underlying CSS variables exist at runtime.

---

## Installation

Install the required packages:

```bash
npm install @nova-design-system/nova-webcomponents @nova-design-system/nova-base
```

or

```bash
yarn add @nova-design-system/nova-webcomponents @nova-design-system/nova-base
```

> In some cases, you might experience SSL certificate issues when working on Developers' VM. As documented in the [Developers' setup guide](https://wiki.eliagroup.eu/spaces/EAing/pages/89296007/2.3.3.10+Developer+Setup#id-2.3.3.10DeveloperSetup-NPMconfig), you need to turn off the SSL certificate verification:
>
> ```bash
> npm config set strict-ssl false
> ```

---

## Setting up Tailwind

Nova Web Components rely on Tailwind for all of the utility classes. The Nova CSS plugin maps Nova’s tokens into Tailwind’s system and generates utilities that resolve to token-backed CSS variables at runtime.

> Tailwind version
> This guide targets Tailwind v4.

### About Tailwind and the Nova Plugin

- What is Tailwind? A utility‑first CSS framework with low‑level, composable classes (flex, grid, spacing, color, typography) to quickly build UIs.
- Nova Tokens: Nova ships design tokens as CSS variables (Spark/Ocean themes) for colors, spacing, typography, radii, shadows, etc.
- Integration: `@nova-design-system/nova-base/theme/plugin.css` wires Nova tokens into Tailwind’s theme scales and emits utilities and variants that read those variables at runtime.
- Why import tokens CSS? Import one of `spark.css` or `ocean.css` so the CSS variables exist. Tailwind utilities produced by the Nova plugin reference these variables.

### 1. Install Tailwind CSS

**This example uses Vite**, but there are multiple ways to set up Tailwind with your project. See the [Tailwind documentation](https://tailwindcss.com/docs/installation) for more information.

```bash
npm install -D tailwindcss @tailwindcss/vite
```

> Tip: Install the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) VS Code extension for autocomplete on Tailwind and Nova tokens.

### 2. Configure Vite

`vite.config.ts`:

```ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})
```

### 3. Configure Tailwind and Nova in your CSS

Create a global CSS file (for example, `src/index.css`) and import Tailwind, the CSS-only Nova plugin, and exactly one token theme:

```css
@import 'tailwindcss';
@import '@nova-design-system/nova-base/theme/plugin.css';
@import '@nova-design-system/nova-base/dist/css/spark.css';
/* Or import ocean.css instead of spark.css. */
```

No `tailwind.config` file, `@config`, `@plugin`, or separate JavaScript theme import is required. Do not combine `theme/plugin.css` with `nova-utils.css`.

### 4. Register components

Create `src/setup.ts` (or `main.ts`):

```ts
import './index.css'

// Register Nova Web Components
import { defineCustomElements } from '@nova-design-system/nova-webcomponents/loader'
defineCustomElements()
```

### 5. Use components in HTML with Tailwind utilities

`index.html`:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0"
    />
    <title>Nova Web Components</title>
    <script type="module" src="/src/setup.ts"></script>
  </head>
  <body class="min-h-screen flex items-center justify-center bg-background text-foreground">
    <!-- Layout with Tailwind utilities; styling flows into nv-* hosts (no shadow) -->
    <div class="flex flex-col items-center gap-4 p-6 rounded-md shadow-sm">
      <h1 class="text-2xl font-semibold">Nova Button</h1>
      <nv-button id="counter" danger>Click me</nv-button>
    </div>

    <script type="module">
      const button = document.getElementById('counter');
      let count = 0;
      button.addEventListener('click', () => {
        count += 1;
        button.textContent = `Count is ${count}`;
      });
    </script>
  </body>
</html>
```

- Use Tailwind utilities to create layouts (e.g., `flex`, `grid`, `gap-*`, `p-*`, `m-*`).
- Apply utilities directly to `nv-*` elements and surrounding/ slotted content to customize spacing and appearance.
- Consolidate repeated class patterns with Tailwind’s `@apply` in your own CSS utilities when useful.

### Dark mode

Enable dark mode by adding the `dark` class on the `body` (or a root container):

```html
<body class="dark">
  <!-- content -->
</body>
```

### Deprecated JavaScript configuration

The JavaScript theme and plugin remain available for backward compatibility. Do not combine this setup with `theme/plugin.css`.

`tailwind.config.ts`:

```ts
import type { Config } from 'tailwindcss'
import { novaTailwindTheme } from '@nova-design-system/nova-base/theme'

export default {
  theme: novaTailwindTheme,
} satisfies Config
```

`src/index.css`:

```css
@import 'tailwindcss';
@import '@nova-design-system/nova-base/dist/css/spark.css';

@config '../tailwind.config.ts';
@plugin '@nova-design-system/nova-base/theme/plugin';
@custom-variant dark (&:where(.dark, .dark *));
```

---

## Nova Font Pro Integration

> [!WARNING]
> Nova Fonts is a protected asset and is not included in the Nova Base package. You need to include the Nova Fonts CSS file in your project.
> To get the Nova Fonts URL, **please contact us via Teams** or get the URL in the Nova Design System [internal wiki](https://dev.azure.com/elia-digitization/Nova/_wiki/wikis/Nova.wiki/30245/Nova-Font-Pro).

Once you have the URL, integrate it using one of the following:

- Import in global CSS (recommended):
  ```css
  /* e.g., in src/index.css */
  @import url('contact-us-for-URL/nova-fonts-pro.css');
  ```

- Link in HTML:
  ```html
  <link rel="stylesheet" href="contact-us-for-URL/nova-fonts-pro.css" />
  ```

The `nova-fonts-pro.css` file includes font-face definitions and a `body { font-family: ... }` rule to apply fonts across your application.