# LMVZ Component Library

[![Built With Stencil](https://img.shields.io/badge/-Built%20With%20Stencil-16161d.svg?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDE5LjIuMSwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCA1MTIgNTEyOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI%2BCjxzdHlsZSB0eXBlPSJ0ZXh0L2NzcyI%2BCgkuc3Qwe2ZpbGw6I0ZGRkZGRkY7fQo8L3N0eWxlPgo8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNDI0LjcsMzczLjljMCwzNy42LTU1LjEsNjguNi05Mi43LDY4LjZIMTgwLjRjLTM3LjksMC05Mi43LTMwLjctOTIuNy02OC42di0zLjZoMzM2LjlWMzczLjl6Ii8+CjxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik00MjQuNywyOTIuMUgxODAuNGMtMzcuNiwwLTkyLjctMzEtOTIuNy02OC42di0zLjZIMzMyYzM3LjYsMCw5Mi43LDMxLDkyLjcsNjguNlYyOTIuMXoiLz4KPHBhdGggY2xhc3M9InN0MCIgZD0iTTQyNC43LDE0MS43SDg3Ljd2LTMuNmMwLTM3LjYsNTQuOC02OC42LDkyLjctNjguNkgzMzJjMzcuOSwwLDkyLjcsMzAuNyw5Mi43LDY4LjZWMTQxLjd6Ii8+Cjwvc3ZnPgo%3D&colorA=16161d&style=flat-square)](https://stenciljs.com)

Web components for the LMVZ Design System.

## About

This package uses **Stencil** to create web components for browser-native usage and to generate integration artifacts consumed by sibling framework packages.

Please also read the Integration chapter of the Design Guide.

## Installation

```bash
npm i @lmvz-ds/components
```

> [!TIP]
> If you are building an Angular application, prefer the `@lmvz-ds/angular` wrapper package.

> [!TIP]
> Our @lmvz-ds/aria-validation sibling is only used for YOUR development mode, and thus, optional.

## Usage

Import individual components when you only need a subset:

```ts
import '@lmvz-ds/components/lmvz-button';
import '@lmvz-ds/components/lmvz-icon';
```

Register all components globally via the loader when that is a better fit for your app shell:

```ts
import { defineCustomElements } from '@lmvz-ds/components/loader';

defineCustomElements(window);
```

If your app has no own build/bundling process, directly import from the CDN (unpkg.com) using `<script type="module" href="[cdnurl]">`.

The package also exposes a /hydrate entry for server-side rendering workflows.

### Icons

The `<lmvz-icon>` component requires an icon provider to be registered before use. See [@lmvz-ds/icons](https://www.npmjs.com/package/@lmvz-ds/icons) for setup instructions and available provider modes.

### Runtime ARIA Validation (Opt-in)

ARIA validation is disabled by default and can be enabled on demand for development-time accessibility checks:

```ts
import { enableAriaValidation } from '@lmvz-ds/components';

enableAriaValidation();
```

This import enables validation globally for all LMVZ components, independent of integration mode.

To disable it again at runtime:

```ts
import { disableAriaValidation } from '@lmvz-ds/components';

disableAriaValidation();
```

### Example

Import and register the component module before using its custom element:

```tsx
import { defineCustomElement as defineButtonElement } '@lmvz-ds/components/lmvz-button';

defineButtonElement();

function App() {
  return (
    <>
      <div>
        <lmvz-button variant="primary"></lmvz-button>
      </div>
    </>
  );
}

export default App;
```

LMVZ component styles do not style native HTML elements outside the components. Import a theme, and any additional global style bundles you need, from `@lmvz-ds/styles` separately.

## Advanced Usage

### Reactive Controllers

LMVZ components use a lightweight reactive controller pattern for composing accessibility and interaction features. For detailed documentation on:
- Using reactive controllers in custom components
- How built-in controllers (element activation, directional focus, ARIA validation, radio grouping) work
- Building your own controllers

See [Reactive Controllers](./docs/reactive-controllers.md).

## Contributing

Contributor onboarding for local development, builds, testing, and authoring guidelines is in `DEVELOPMENT.md`.