TEMS Components v2

Lit-based web components library for the TEMS (Trusted European Media data Space) ecosystem. Modern rewrite with enhanced Orbit integration, reactive state management, and improved developer experience.

Table of Contents

1. Key Features
2. Components
3. Installation
4. Quick Start
5. Development
6. Documentation
7. License

Key Features

Modern Stack

• Lit 3.x: Latest reactive web components framework
• TypeScript: Strict mode with full type safety
• Biome.js: Fast linting and formatting with zero config
• Vite: Lightning-fast HMR and optimized builds

Orbit Integration

• Data Fetching: Built-in reactive data fetching via @lit/task
• Routing: Seamless integration with Orbit routing framework
• Caching: Keyword-based cache invalidation
• Subscriptions: Automatic component lifecycle management

Internationalization

• @lit/localize: Runtime locale switching
• XLIFF Format: Standard localization workflow
• Reactive Updates: Components automatically update on locale change

Component Architecture

• ComponentObjectHandler: Single resource display (no data fetching)
• ComponentObjectsHandler: Array/collection display (no data fetching)
• OrbitComponent: Full Orbit integration with data fetching, routing, caching

Components

Catalog Components

| Component | Description | Base Class | |-----------|-------------|------------| | tems-catalog | Catalog browser with filtering | OrbitComponent | | tems-catalog-data-holder | Catalog data management | OrbitComponent | | tems-catalog-filter-holder | Filtering and search UI | ComponentObjectsHandler |

Card Components

| Component | Description | Base Class | |-----------|-------------|------------| | tems-card-catalog | Catalog item card view | ComponentObjectHandler | | tems-card-service | Service details card | ComponentObjectHandler |

Media Components

| Component | Description | Base Class | |-----------|-------------|------------| | tems-mediatrendexplorer | Media trend visualization | OrbitComponent | | tems-mediatrendexplorer-content | Media trend content display | ComponentObjectsHandler |

Utility Components

| Component | Description | Base Class | |-----------|-------------|------------| | tems-notification | Notification center | OrbitComponent | | tems-modal | Modal dialog | ComponentObjectHandler | | tems-organisation-approval | Organization approval workflow | OrbitComponent | | tems-index-search | Index-based search | ComponentObjectsHandler |

Installation

npm install @startinblox/solid-tems

Quick Start

Import Components

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

Using Catalog Component

<tems-catalog
  data-src="http://example.com/catalog/"
  route="catalog"
  header="Service Catalog">
</tems-catalog>

Using Card Component

<tems-card-service
  .object=${serviceObject}
  data-src="${serviceObject['@id']}">
</tems-card-service>

Using Notification Component

<tems-notification
  data-src="http://example.com/notifications/"
  route="notifications">
</tems-notification>

Using Media Trend Explorer

<tems-mediatrendexplorer
  data-src="http://example.com/media-trends/"
  route="media-trends">
</tems-mediatrendexplorer>

Development

Watch Mode (Hot Reload)

npm run watch

Run Tests (Cypress)

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

Storybook

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

Build for Production

npm run build           # Includes lit-localize build

Linting & Formatting

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

Localization

Extract translatable strings:

npm run locale:extract

Build localization:

npm run locale:build

Change locale at runtime:

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

Documentation

For Developers

• AGENTS.md: Complete development guidelines and coding standards
• Stories/: Storybook stories for each component

Component Conventions

Naming:

• Web component elements: kebab-case with solid- or tems- prefix (e.g., tems-card-service)
• Class names: PascalCase (e.g., TemsCardService)
• Properties: kebab-case in HTML, camelCase in JS
• Private methods: underscore prefix (_navigate, _getProxyValue)

Lit Decorators:

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

Component Patterns:

@customElement("solid-xyz")
@localized()
export class XyzComponent extends utils.OrbitComponent {
  static styles = css`${unsafeCSS(ComponentStyle)}`;

  @property({ attribute: "data-src", reflect: true, type: String })
  dataSrc?: string;

  @state()
  private ready = false;

  render() {
    return this.gatekeeper() || html`<div>${content}</div>`;
  }
}

OrbitComponent Patterns:

• Define cherryPickedProperties: PropertiesPicker[] = [{ key, value, expand?, cast? }]
• Use await this._getProxyValue(url, recursive, targetProperties) to fetch data
• Always call this.gatekeeper() at start of render() to check route/data readiness
• Use Task from @lit/task for async operations

Import Paths

Use configured aliases:

import { TemsCardService } from '@components/cards/tems-card-service';
import { TemsCatalog } from '@components/catalog/tems-catalog';
import * as utils from '@helpers';

Shared Utilities

• utils.formatDate(date, options) - Date formatting
• utils.sort(array, property, order) - Array sorting
• utils.setupCacheInvalidation(component, { keywords }) - Cache invalidation
• utils.setupComponentSubscriptions({ component, defaultRoute, ignoreRouter }) - Orbit subscriptions
• utils.requestNavigation(route, resource["@id"]) - Navigation helper

Contributing

This project uses:

• Conventional Commits for semantic versioning
• GitLab CI for automated releases
• semantic-release for version management

Branches: master (stable), beta, alpha (pre-release)

License

MIT

TEMS Project - Co-funded by the European Union