lovince-ui

A component library built on web standards. Drop into any framework — or none at all.

Quick Start

npm install lovince-ui

import 'lovince-ui';

// All <lc-*> tags are now available

<lc-button variant="filled">Get started</lc-button>
<lc-icon name="favorite"></lc-icon>
<lc-card variant="elevated">
  <h3 slot="headline">Hello</h3>
  <p slot="body">Web components.</p>
</lc-card>

Wrap your app in <lc-theme> to enable design tokens:

<lc-theme>
  <lc-button variant="filled">Themed</lc-button>
</lc-theme>

Component Checklist

Legend: ✅ done   🔜 planned   ⬜ not yet started

Actions

| Status | Component | Description | Subpath | |--------|-----------|-------------|---------| | ✅ | <lc-button> | Filled, tonal, outlined, text. Disabled, icon, link support. | lovince-ui/lc-button | | ✅ | <lc-fab> | Floating action button — mini, extended, or default. Surface, primary, secondary, tertiary variants. | lovince-ui/lc-fab | | ✅ | <lc-icon-button> | Round button wrapping an icon. Standard, filled, tonal, outlined. | lovince-ui/lc-icon-button | | ✅ | <lc-split-button> | Split button with dropdown icon. Filled, tonal, outlined variants. | lovince-ui/lc-split-button |

Inputs & Forms

| Status | Component | Description | Subpath | |--------|-----------|-------------|---------| | 🔜 | <lc-input> | Text input with label, helper text, validation states. | lovince-ui/lc-input | | 🔜 | <lc-textarea> | Multi-line text input. | lovince-ui/lc-textarea | | 🔜 | <lc-select> | Native or custom dropdown select. | lovince-ui/lc-select | | 🔜 | <lc-checkbox> | Single checkbox or group. | lovince-ui/lc-checkbox | | 🔜 | <lc-radio> | Radio button group for single selection. | lovince-ui/lc-radio | | 🔜 | <lc-switch> | Toggle switch. | lovince-ui/lc-switch | | 🔜 | <lc-slider> | Range slider, continuous or discrete. | lovince-ui/lc-slider | | 🔜 | <lc-rating> | Star-based rating input. | lovince-ui/lc-rating | | 🔜 | <lc-file-upload> | Drag-and-drop file upload zone. | lovince-ui/lc-file-upload |

Data Display

| Status | Component | Description | Subpath | |--------|-----------|-------------|---------| | ✅ | <lc-icon> | 900+ Material Symbols, colorable, sizable. | lovince-ui/lc-icon | | ✅ | <lc-card> | Elevated, filled, outlined. Media, headline, body, actions slots. | lovince-ui/lc-card | | ✅ | <lc-type-scale> | Full typographic scale showcase. | lovince-ui/lc-type-scale | | ✅ | <lc-avatar> | User avatar with image, initials, or icon fallback. | lovince-ui/lc-avatar | | ✅ | <lc-badge> | Notification dot or count badge. | lovince-ui/lc-badge | | ✅ | <lc-chip> | Chip / pill for filters, tags, status, actions. 7 variants, 4 visual styles, 2 sizes, status colors, avatar. | lovince-ui/lc-chip | | ✅ | <lc-data-table> | Professional data table: 4 densities, 3 visual styles, multi/single select, sort, search, filter, pagination, frozen cols, expandable rows, skeleton loading, responsive card mode. | lovince-ui/lc-data-table | | ✅ | <lc-tree-view> | Expandable tree list. | lovince-ui/lc-tree-view | | 🔜 | <lc-progress> | Linear progress / loading bar. | lovince-ui/lc-progress | | 🔜 | <lc-circular-progress> | Spinning progress indicator. | lovince-ui/lc-circular-progress |

Navigation

| Status | Component | Description | Subpath | |--------|-----------|-------------|---------| | 🔜 | <lc-tabs> | Tab bar with panels. | lovince-ui/lc-tabs | | 🔜 | <lc-breadcrumbs> | Hierarchical breadcrumb navigation. | lovince-ui/lc-breadcrumbs | | 🔜 | <lc-pagination> | Page number navigation. | lovince-ui/lc-pagination | | 🔜 | <lc-stepper> | Multi-step flow indicator. | lovince-ui/lc-stepper | | 🔜 | <lc-nav-drawer> | Side navigation drawer. | lovince-ui/lc-nav-drawer | | 🔜 | <lc-bottom-nav> | Mobile bottom navigation bar. | lovince-ui/lc-bottom-nav |

Overlays

| Status | Component | Description | Subpath | |--------|-----------|-------------|---------| | 🔜 | <lc-dialog> | Modal dialog with backdrop. | lovince-ui/lc-dialog | | 🔜 | <lc-tooltip> | Hover/focus tooltip. | lovince-ui/lc-tooltip | | 🔜 | <lc-popover> | Anchored popover content. | lovince-ui/lc-popover | | 🔜 | <lc-bottom-sheet> | Slide-up panel for mobile. | lovince-ui/lc-bottom-sheet | | 🔜 | <lc-snackbar> | Short-duration notification toast. | lovince-ui/lc-snackbar |

Feedback

| Status | Component | Description | Subpath | |--------|-----------|-------------|---------| | 🔜 | <lc-alert> | Inline alert / banner with severity. | lovince-ui/lc-alert | | 🔜 | <lc-skeleton> | Content placeholder / shimmer. | lovince-ui/lc-skeleton | | 🔜 | <lc-spinner> | Configurable loading spinner. | lovince-ui/lc-spinner |

Layout

| Status | Component | Description | Subpath | |--------|-----------|-------------|---------| | ✅ | <lc-theme> | Wrapper that injects design tokens, toggles dark mode. | lovince-ui/lc-theme | | ✅ | <lc-code-block> | Syntax-highlighted code with copy button. | lovince-ui/lc-code-block | | ✅ | <lc-prop-table> | API documentation tables. | lovince-ui/lc-prop-table | | ✅ | <lc-doc-section> | Preview + code + API table composer. | lovince-ui/lc-doc-section | | ✅ | <lc-divider> | Horizontal or vertical divider. Inset support. | lovince-ui/lc-divider | | ✅ | <lc-container> | Responsive max-width container. sm/md/lg/xl/full sizes. | lovince-ui/lc-container |

Utilities

| Status | Component | Description | Subpath | |--------|-----------|-------------|---------| | 🔜 | <lc-portal> | Teleport content to another DOM location. | lovince-ui/lc-portal | | 🔜 | <lc-lazy> | Lazy-load content when scrolled into view. | lovince-ui/lc-lazy |

Creating a New Component

# Interactive prompt
bash scripts/new-component.sh

# Or pass the tag name directly
bash scripts/new-component.sh lc-input

The script:

1. Creates the component directory with index.ts, lc-{name}.ts, lc-{name}.styles.ts
2. Adds the barrel export to src/components/index.ts
3. Adds the subpath export + sideEffects entry to package.json
4. Appends the checklist entry to this README (set to 🔜)
5. Creates a playground section file at apps/playground/src/sections/{name}.ts
6. Registers the section in playground's nav.ts and main.ts

Existing Components

| Tag | Class | Description | |-----|-------|-------------| | <lc-button> | LcButton | Filled, tonal, outlined, text. Disabled, icon, link support. | | <lc-card> | LcCard | Elevated, filled, outlined. Media, headline, body, actions. | | <lc-icon> | LcIcon | 900+ Material Symbols, colorable, sizable. | | <lc-theme> | LcTheme | Wrapper that injects design tokens, toggles dark mode. | | <lc-code-block> | LcCodeBlock | Syntax-highlighted code with copy button. | | <lc-prop-table> | LcPropTable | API documentation tables (props, slots, parts, events). | | <lc-doc-section> | LcDocSection | Composes preview + code + API tables into doc sections. | | <lc-type-scale> | LcTypeScale | Full typographic scale showcase. |

Tree-Shaking

Importing the barrel registers every component. For smaller bundles, import only what you use:

import 'lovince-ui/lc-button';
import 'lovince-ui/lc-icon';

Each subpath import registers exactly one component (plus its dependencies). Your bundler tree-shakes the rest.

Theming

Wrap your app in <lc-theme> to activate design tokens:

<lc-theme theme="light">
  <!-- light mode -->
</lc-theme>

<lc-theme theme="dark">
  <!-- dark mode -->
</lc-theme>

Toggle programmatically:

document.querySelector('lc-theme').theme = 'dark';

CSS Custom Properties

Every component exposes its key colors and typography via CSS custom properties. Override at any level:

<lc-button variant="filled"
  style="--lovince-primary: #E53935; --lovince-on-primary: #fff;">
  Custom Color
</lc-button>

CSS Parts

Target internal elements with ::part():

lc-button::part(button) {
  font-weight: 800;
  text-transform: uppercase;
}

lc-card::part(container) {
  border-radius: 24px;
  background: linear-gradient(135deg, #667eea, #764ba2);
}

Events

Native DOM events bubble through the shadow DOM. Listen like any element:

document.querySelector('lc-button')
  .addEventListener('click', () => console.log('clicked'));

Custom Icons

Register additional icons beyond the built-in set:

import { registerIcon } from 'lovince-ui';

registerIcon('my-icon', {
  viewBox: '0 0 24 24',
  paths: ['M12 2L2 7l10 5 10-5-10-5z'],
});

<lc-icon name="my-icon"></lc-icon>

Framework Usage

Web components work in any framework. No wrappers or adapters needed.

React — set props as attributes, listen with onClick:

import 'lovince-ui/lc-button';

function App() {
  return <lc-button variant="filled" onClick={() => alert('Hi!')}>Hello</lc-button>;
}

Vue / Svelte / Angular / plain HTML — use the tags directly.

Development

bun install
cd packages/lovince-ui
bun run build     # tsc → dist/
bun run dev       # watch mode

Run the playground:

cd apps/playground
bun run dev

License

MIT