npm package: @heux/framework
Description: Premium Web Component library built with Lit. 90+ components, dual theme engine, framework-agnostic.
Author: Juan Herruzo
Latest version: 1.0.1

# Heux

[![npm version](https://img.shields.io/npm/v/heux.svg?style=flat-square)](https://www.npmjs.com/package/heux)
[![CI](https://img.shields.io/github/actions/workflow/status/herruzo99/heux/ci.yml?branch=main&label=CI&style=flat-square)](https://github.com/herruzo99/heux/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![Lit](https://img.shields.io/badge/built%20with-Lit-324fff.svg?style=flat-square)](https://lit.dev)

> A modern, premium Web Component library built with [Lit](https://lit.dev/).  
> 90+ components. Framework-agnostic. Dual theme engine. Zero lock-in.

**[Live Demo →](https://herruzo99.github.io/heux/)**

---

## Features

- **90+ components** — buttons, forms, data tables, overlays, navigation, charts, and more
- **Dual theme system** — independent layout themes (spatial) and design themes (colors/modes)
- **Framework agnostic** — works with React, Vue, Angular, Svelte, or plain HTML
- **Tree-shakeable** — import the whole library or just the components you need
- **TypeScript** — full `.d.ts` declarations for every component and utility
- **Accessible** — ARIA roles, keyboard navigation, `prefers-reduced-motion` support throughout

---

## Scaffold a new project

```bash
npm create heux@latest
```

Prompts for a project name and template, then scaffolds a Vite project ready to run.

| Template  | Stack                                |
| --------- | ------------------------------------ |
| `vanilla` | Plain HTML + JS                      |
| `lit`     | Custom elements with `ThemedElement` |
| `react`   | React 19 + TypeScript                |
| `vue`     | Vue 3 + TypeScript                   |
| `svelte`  | Svelte 5                             |

---

## Installation (existing project)

```bash
npm install heux lit
```

> Heux externalizes `lit` as a peer dependency — you supply it, preventing duplicate instances.

---

## Quick Start

### Import everything (simplest)

```js
import '@heux/framework'; // registers all 90+ components
import 'heux/app-shell'; // app shell only
import 'heux/button'; // single component (tree-shaking)
```

### Theming

```js
// Option A: static CSS import
import 'heux/themes/midnight-dark.css';

// Option B: programmatic (supports system preference, live switching)
import { themeRegistry } from '@heux/framework';
themeRegistry.setLayout('prism-glass');
```

```html
<theme-manager-component theme="midnight" mode="dark"></theme-manager-component>
```

### Use in HTML

```html
<ui-button variant="primary">Save</ui-button>
<ui-input label="Email" type="email"></ui-input>
<ui-modal>
  <h2 slot="header">Hello</h2>
  <p>Modal content</p>
</ui-modal>
```

---

## Framework Integration

<details>
<summary><strong>React</strong></summary>

```tsx
// main.tsx
import '@heux/framework';

function App() {
  return (
    <div>
      <ui-button variant="primary" onClick={() => console.log('clicked')}>
        Click me
      </ui-button>
    </div>
  );
}
```

For full TypeScript prop types in JSX, add to your `tsconfig.json`:

```json
{ "compilerOptions": { "customConditions": ["browser"] } }
```

</details>

<details>
<summary><strong>Vue</strong></summary>

```ts
// main.ts
import '@heux/framework';

// vite.config.ts — tell Vue to skip custom elements
export default defineConfig({
  plugins: [
    vue({ template: { compilerOptions: { isCustomElement: tag => tag.startsWith('ui-') } } })
  ]
});
```

```vue
<template>
  <ui-button variant="primary" @click="handleClick">Click me</ui-button>
</template>
```

</details>

<details>
<summary><strong>Svelte</strong></summary>

```ts
// app.ts
import '@heux/framework';
```

```svelte
<ui-button variant="primary" on:click={handleClick}>Click me</ui-button>
```

</details>

<details>
<summary><strong>Angular</strong></summary>

```ts
// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@heux/framework';

@NgModule({ schemas: [CUSTOM_ELEMENTS_SCHEMA] })
export class AppModule {}
```

</details>

---

## Component Catalog

| Category       | Components                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Base**       | `ui-button` `ui-badge` `ui-chip` `ui-icon` `ui-avatar` `ui-kbd` `ui-code` `ui-divider` `ui-highlight` `ui-progress` `ui-skeleton` `ui-spinner` `ui-copy-button`                                                                                                                                                                                                                                                                                |
| **Forms**      | `ui-input` `ui-textarea` `ui-checkbox` `ui-radio` `ui-radio-group` `ui-toggle` `ui-switch-group` `ui-selector` `ui-multi-select` `ui-range` `ui-slider` `ui-rating` `ui-tag-input` `ui-number-input` `ui-search-input` `ui-date-picker` `ui-time-picker` `ui-time-range` `ui-calendar` `ui-color-picker` `ui-file-drop` `ui-mention-input` `ui-tree-select` `ui-password-strength` `ui-rich-text` `ui-form` `ui-form-group` `ui-avatar-editor` |
| **Data**       | `ui-card` `ui-stat` `ui-data-table` `ui-data-list` `ui-data-tree` `ui-accordion` `ui-carousel` `ui-timeline` `ui-image` `ui-empty-state` `ui-pagination` `ui-virtual-scroll` `ui-infinite-scroll` `ui-marquee` `ui-pager-dots`                                                                                                                                                                                                                 |
| **Navigation** | `ui-tabs` `ui-breadcrumb` `ui-stepper` `ui-segmented-control` `ui-fab` `ui-hotkey`                                                                                                                                                                                                                                                                                                                                                             |
| **Overlays**   | `ui-modal` `ui-drawer` `ui-toast` `ui-tooltip` `ui-popover` `ui-popup` `ui-dropdown` `ui-context-menu` `ui-alert` `ui-confirm` `ui-notification-bell`                                                                                                                                                                                                                                                                                          |
| **Layout**     | `ui-split-pane` `scaffold` `toolbar` `sidebar-nav` `view-header` `folder-tree` `hx-layer`                                                                                                                                                                                                                                                                                                                                                      |
| **Prefabs**    | `command-palette` `date-range-picker` `theme-picker` `loading-screen` `login-card` `search-bar` `activity-feed` `dynamic-background` `shell-preset`                                                                                                                                                                                                                                                                                            |
| **Shell**      | `app-shell-component` `theme-manager-component`                                                                                                                                                                                                                                                                                                                                                                                                |

---

## App Shell

For full-scale applications, Heux provides a highly configurable layout shell:

```js
import 'heux/app-shell';

const shell = document.createElement('app-shell-component');
shell.config = {
  activeLayoutId: 'prism-glass',
  globalNavWidth: '220px',
  topBarHeight: '56px',
  allowResizing: true
};
shell.slots = {
  globalNav: html`<sidebar-nav .items=${navItems}></sidebar-nav>`,
  topBar: html`<toolbar></toolbar>`,
  main: html`<div>Your content</div>`
};
document.body.appendChild(shell);
```

---

## Utilities

```js
import {
  themeRegistry, // layout theme management
  breakpointRegistry, // reactive viewport observer
  hotkeyRegistry, // keyboard shortcut management
  i18nRegistry, // locale / translations
  animationRegistry, // animation presets
  overlayManager, // z-index / overlay stack
  Persistence, // localStorage/sessionStorage wrapper
  StateMachine, // finite state machine
  SpringController, // spring physics animations
  ContextProvider // Lit context API
} from '@heux/framework';
```

---

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).

```bash
git clone https://github.com/herruzo99/heux.git
cd heux
npm install
npm run dev      # start dev server
npm run test     # run tests
npm run build    # build library
```

---

## License

MIT © [Juan Herruzo](https://github.com/herruzo99)