npm package: @startinblox/solid-tems-ui
Description: Startin'blox Boilerplate
Author: startinblox
Latest version: 1.2.0

<img src="https://cdn.startinblox.com/tems/cofund.png" width="300" />

# TEMS UI Components

[![npm](https://img.shields.io/npm/v/@startinblox/solid-tems-ui)](https://www.npmjs.com/package/@startinblox/solid-tems-ui)
[![stable](https://img.shields.io/gitlab/v/tag/components%2Fsolid-tems-ui?gitlab_url=https%3A%2F%2Fgit.startinblox.com&sort=semver&label=stable)](https://git.startinblox.com/components/solid-tems-ui/)
[![latest](https://img.shields.io/gitlab/v/tag/components/solid-tems-ui?gitlab_url=https%3A%2F%2Fgit.startinblox.com&label=latest)](https://git.startinblox.com/components/solid-tems-ui/)

Lit-based web component design system for the TEMS (Trusted European Media data Space) ecosystem. Provides a complete set of accessible, responsive UI components with built-in internationalization support.

## Table of Contents

1. [Key Features](#key-features)
2. [Components](#components)
3. [Installation](#installation)
4. [Quick Start](#quick-start)
5. [Development](#development)
6. [Documentation](#documentation)
7. [License](#license)

## Key Features

### **Design System**

- **Complete Component Library**: Forms, layout, navigation, and display components
- **Consistent Styling**: SCSS-based theming with CSS variables for customization
- **Icon Support**: Integration with Iconify for 20+ icon sets (Fluent, Tabler, Heroicons, etc.)
- **Typography**: Multiple font families (Inter, Montserrat, Open Sans) via @fontsource

### **Internationalization**

- **Built-in i18n**: Powered by `@lit/localize` for runtime locale switching
- **XLIFF Format**: Standard localization workflow with extract/build tools
- **Reactive Updates**: Components automatically update when locale changes

## Components

### Form Components

| Component | Description | Attributes |
| ----------- | ------------- | ------------ |
| `tems-input` | Text input field with validation | `placeholder`, `required`, `type` |
| `tems-textarea` | Multi-line text input | `rows`, `placeholder` |
| `tems-checkbox` | Checkbox control | `checked`, `label` |
| `tems-toggle` | Toggle switch control | `checked`, `label` |
| `tems-datepicker` | Date selection picker | `value`, `min`, `max` |
| `tems-dropdown` | Dropdown menu | `items`, `selected` |
| `tems-slider` | Range slider control | `min`, `max`, `step`, `value` |
| `tems-label` | Form label with accessibility | `for`, `required` |

### Layout Components

| Component | Description | Usage |
| ----------- | ------------- | ------- |
| `tems-header` | Application header | Top navigation bar |
| `tems-sidebar` | Collapsible sidebar | Side navigation menu |
| `tems-viewport` | Main content area | Application container |
| `tems-division` | Section divider | Visual separator |

### Navigation Components

| Component | Description |
| ----------- | ------------- |
| `tems-breadcrumb` | Breadcrumb navigation |
| `tems-breadcrumb-item` | Individual breadcrumb link |
| `tems-tab-item` | Tab navigation item |
| `tems-sidebar-item` | Sidebar navigation item |
| `tems-sidebar-section` | Sidebar section grouping |

### Display Components

| Component | Description |
| ----------- | ------------- |
| `tems-badge` | Status or count badge |
| `tems-tag` | Categorization tag |
| `tems-avatar` | User avatar with initials/image |
| `tems-profile-card` | User profile display card |
| `tems-button` | Action button with variants |

### Search & Filter Components

| Component | Description |
| ----------- | ------------- |
| `tems-search-bar` | Search input with active filters |
| `tems-filter-sidebar` | Collapsible filter panel |
| `tems-filter-item` | Individual filter control |
| `tems-vertical-accordion` | Collapsible accordion sections |
| `tems-active-tags` | Display active filter tags |

## Installation

```bash
npm install @startinblox/solid-tems-ui
```

## Quick Start

### Import Components

```html
<script type="module">
  import '@startinblox/solid-tems-ui';
</script>
```

### Using Form Components

```html
<form>
  <tems-label for="name" required>Name</tems-label>
  <tems-input id="name" placeholder="Enter your name" required></tems-input>

  <tems-label for="email">Email</tems-label>
  <tems-input id="email" type="email" placeholder="Enter your email"></tems-input>

  <tems-checkbox label="I agree to the terms"></tems-checkbox>

  <tems-button type="submit">Submit</tems-button>
</form>
```

### Using Layout Components

```html
<tems-header></tems-header>

<div style="display: flex;">
  <tems-sidebar>
    <tems-sidebar-section>
      <tems-sidebar-item>Dashboard</tems-sidebar-item>
      <tems-sidebar-item>Settings</tems-sidebar-item>
    </tems-sidebar-section>
  </tems-sidebar>

  <tems-viewport>
    <tems-breadcrumb>
      <tems-breadcrumb-item href="/">Home</tems-breadcrumb-item>
      <tems-breadcrumb-item href="/catalog">Catalog</tems-breadcrumb-item>
    </tems-breadcrumb>

    <!-- Main content -->
  </tems-viewport>
</div>
```

### Using Dropdown

```html
<tems-dropdown label="Select option">
  <tems-dropdown-item value="option1">Option 1</tems-dropdown-item>
  <tems-dropdown-item value="option2">Option 2</tems-dropdown-item>
  <tems-dropdown-item value="option3">Option 3</tems-dropdown-item>
</tems-dropdown>
```

### Using Search Bar with Filters

```html
<tems-search-bar></tems-search-bar>

<tems-filter-sidebar>
  <tems-vertical-accordion>
    <tems-filter-item label="Category">
      <tems-checkbox label="Category 1"></tems-checkbox>
      <tems-checkbox label="Category 2"></tems-checkbox>
    </tems-filter-item>

    <tems-filter-item label="Date Range">
      <tems-datepicker></tems-datepicker>
    </tems-filter-item>
  </tems-vertical-accordion>
</tems-filter-sidebar>
```

## Development

### Watch Mode (Hot Reload)

```bash
npm run watch
```

### Run Tests (Cypress)

```bash
npm run cy:run          # Headless
npm run cy:open         # Interactive UI
```

### Storybook

```bash
npm run storybook       # Start dev server (port 6006)
npm run build-storybook # Build static Storybook
```

### Build for Production

```bash
npm run build           # Includes lit-localize build
```

### Linting & Formatting

```bash
npx biome check .                    # Check for issues
npx biome check . --write            # Auto-fix and format
```

### Localization

Extract translatable strings:

```bash
npm run locale:extract
```

Build localization:

```bash
npm run locale:build
```

Change locale at runtime:

```javascript
window.setLocale("fr");  // Switch to French
window.getLocale();      // Get current locale
```

## Documentation

### For Developers

- **[AGENTS.md](AGENTS.md)**: Development guidelines and coding standards
- **[Stories/](stories/)**: Storybook stories for each component

### Component Conventions

**Naming**:

- Web component elements: kebab-case (e.g., `tems-button`)
- Class names: PascalCase (e.g., `TemsButton`)
- Properties: kebab-case in HTML, camelCase in JS

**Lit Decorators**:

- `@customElement("element-name")` - Define web component
- `@property({ attribute: "data-src", reflect: true })` - Public attributes
- `@state()` - Private reactive state
- `@localized()` - For i18n components

**Styling**:
Import SCSS inline: `import ComponentStyle from "@styles/component.scss?inline";`

### Import Paths

Use configured aliases:

```typescript
import { TemsButton } from '@components/buttons/tems-button';
import { TemsInput } from '@components/forms/tems-input';
```

## License

[MIT](LICENSE)

---

**TEMS Project** - Co-funded by the European Union
<img src="https://cdn.startinblox.com/tems/cofund.png" width="200" />