# 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. Create `tailwind.config.ts`](#3-create-tailwindconfigts)
    - [4. Configure Tailwind and the Nova Plugin in your CSS](#4-configure-tailwind-and-the-nova-plugin-in-your-css)
    - [5. Import Nova Tokens (Spark or Ocean) and register components](#5-import-nova-tokens-spark-or-ocean-and-register-components)
    - [6. Use components in HTML with Tailwind utilities](#6-use-components-in-html-with-tailwind-utilities)
    - [Dark mode](#dark-mode)
  - [Nova Font Pro Integration](#nova-font-pro-integration)

---

## Key Points

- Tailwind CSS is required. Nova’s Tailwind theme and plugin bind 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 Tailwind theme and plugin map Nova’s tokens into Tailwind’s system, and generate utilities that resolve to token-backed CSS variables at runtime.

> Tailwind version
> This guide targets Tailwind v4. While compatible with v3, some features may not work as expected.

### 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:
  - `novaTailwindTheme` wires Nova tokens into Tailwind’s theme scales.
  - The Nova Tailwind plugin emits utilities and variants that read those token 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. Create `tailwind.config.ts`

In your project root:

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

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

### 4. Configure Tailwind and the Nova Plugin in your CSS

Create a global CSS file (e.g., `src/index.css`) and add:

```css
@import 'tailwindcss';

/* Adjust the path to your tailwind.config.ts as needed */
@config "../tailwind.config.ts";
@plugin "@nova-design-system/nova-base/theme/plugin";
@custom-variant dark (&:where(.dark, .dark *));
```

### 5. Import Nova Tokens (Spark or Ocean) and register components

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

```ts
// Import ONE tokens theme so CSS variables exist at runtime
import '@nova-design-system/nova-base/dist/css/spark.css' // or ocean.css
import './index.css'

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

> Do not import `@nova-design-system/nova-base/dist/css/nova-utils.css` when using Tailwind.

### 6. 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>
```

---

## 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.
