@vverchonov/web-components 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +142 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# @vverchonov/web-components
|
|
2
|
+
|
|
3
|
+
A library of reusable UI components built with [Lit 3](https://lit.dev/), shipped as standard web components with first-class [React](https://react.dev/) wrappers.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **11 components** — Button, Input, Toggle, Table, Menu, Modal, Tabs, Selector, Dropdown Button, Layout, Form Layout
|
|
8
|
+
- **React wrappers** via `@lit/react` — use every component as a native React element
|
|
9
|
+
- **Dark mode** — automatic (system preference) and manual (`data-theme`)
|
|
10
|
+
- **Fully typed** — written in TypeScript with exported types for every component
|
|
11
|
+
- **Tree-shakeable** — import the entire library or only the components you need
|
|
12
|
+
- **Themeable** — override any design token with CSS custom properties
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install @vverchonov/web-components lit
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### Peer dependencies
|
|
21
|
+
|
|
22
|
+
| Package | Version | Required |
|
|
23
|
+
|---------|---------|----------|
|
|
24
|
+
| `lit` | `^3.0.0` | Yes |
|
|
25
|
+
| `react` | `^18.0.0 \|\| ^19.0.0` | Only for React wrappers |
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
### Vanilla JS / HTML
|
|
30
|
+
|
|
31
|
+
Import the entire library or individual components:
|
|
32
|
+
|
|
33
|
+
```js
|
|
34
|
+
// All components
|
|
35
|
+
import '@vverchonov/web-components'
|
|
36
|
+
|
|
37
|
+
// Single component (tree-shakeable)
|
|
38
|
+
import '@vverchonov/web-components/button'
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Then use the custom element in your markup:
|
|
42
|
+
|
|
43
|
+
```html
|
|
44
|
+
<app-button>Click me</app-button>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### React
|
|
48
|
+
|
|
49
|
+
```jsx
|
|
50
|
+
import { Button } from '@vverchonov/web-components/react/button'
|
|
51
|
+
|
|
52
|
+
function App() {
|
|
53
|
+
return <Button onClick={() => console.log('clicked')}>Click me</Button>
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
You can also import all React wrappers at once:
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
import { Button, Input, Table } from '@vverchonov/web-components/react'
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Components
|
|
64
|
+
|
|
65
|
+
| Tag name | React export | Import path | Description |
|
|
66
|
+
|----------|-------------|-------------|-------------|
|
|
67
|
+
| `app-button` | `Button` | `./button` | Button with optional icon slot |
|
|
68
|
+
| `app-input` | `Input` | `./input` | Text input with validation states and icons |
|
|
69
|
+
| `app-toggle` | `Toggle` | `./toggle` | Boolean switch with optional label |
|
|
70
|
+
| `app-table` | `Table` | `./table` | Data table with sorting, pagination, column toggle |
|
|
71
|
+
| `app-menu` | `Menu` | `./menu` | Sidebar navigation with search and nested items |
|
|
72
|
+
| `app-modal` | `Modal` | `./modal` | Dialog (info, confirm, form variants) with focus trapping |
|
|
73
|
+
| `app-tabs` | `Tabs` | `./tabs` | Tabbed interface with keyboard navigation |
|
|
74
|
+
| `app-selector` | `Selector` | `./selector` | Dropdown selector (single/multi, searchable, grouped) |
|
|
75
|
+
| `app-dropdown-button` | `DropdownButton` | `./dropdown-button` | Dropdown menu button with nested submenus |
|
|
76
|
+
| `app-layout` | `Layout` | `./layouts` | Page layout with sidebar slot |
|
|
77
|
+
| `app-form-layout` | `FormLayout` | `./layouts` | Form shell with multi-step support and column grids |
|
|
78
|
+
|
|
79
|
+
## Theming
|
|
80
|
+
|
|
81
|
+
Design tokens are defined as CSS custom properties in `src/styles/theme.css`. Because they live on `:root`, they inherit through Shadow DOM boundaries.
|
|
82
|
+
|
|
83
|
+
Override any token on `:root` or a parent element:
|
|
84
|
+
|
|
85
|
+
```css
|
|
86
|
+
:root {
|
|
87
|
+
--color-primary: oklch(0.55 0.24 29);
|
|
88
|
+
--radius-button: 0.5rem;
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Dark mode
|
|
93
|
+
|
|
94
|
+
Dark mode activates automatically based on `prefers-color-scheme`. To force a theme manually, set a `data-theme` attribute on `<html>`:
|
|
95
|
+
|
|
96
|
+
```html
|
|
97
|
+
<html data-theme="dark">
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Available values: `"dark"`, `"light"` (overrides system preference), or omit the attribute to follow system preference.
|
|
101
|
+
|
|
102
|
+
### Token categories
|
|
103
|
+
|
|
104
|
+
| Category | Examples |
|
|
105
|
+
|----------|----------|
|
|
106
|
+
| Colors | `--color-primary`, `--color-surface`, `--color-text`, `--color-border` |
|
|
107
|
+
| State | `--color-valid`, `--color-invalid` |
|
|
108
|
+
| Radius | `--radius-button`, `--radius-card`, `--radius-input` |
|
|
109
|
+
| Button | `--button-font-size`, `--button-padding-block`, `--button-icon-gap` |
|
|
110
|
+
| Table | `--table-cell-padding-block`, `--table-header-bg` |
|
|
111
|
+
| Input | `--input-font-size`, `--input-padding-block` |
|
|
112
|
+
| Modal | `--modal-width`, `--modal-padding`, `--modal-backdrop` |
|
|
113
|
+
| Menu | `--menu-width`, `--menu-collapsed-width` |
|
|
114
|
+
| Toggle | `--toggle-track-width`, `--toggle-thumb-size` |
|
|
115
|
+
| Tabs | `--tab-padding-block`, `--tab-indicator-height` |
|
|
116
|
+
| Selector | `--selector-min-height`, `--selector-panel-max-height` |
|
|
117
|
+
|
|
118
|
+
See `src/styles/theme.css` for the full list of tokens and their default values.
|
|
119
|
+
|
|
120
|
+
## Development
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
# Start the dev server (opens a demo page showcasing every component)
|
|
124
|
+
npm run dev
|
|
125
|
+
|
|
126
|
+
# Production library build
|
|
127
|
+
npm run build
|
|
128
|
+
|
|
129
|
+
# Preview the production build
|
|
130
|
+
npm run preview
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Tech stack
|
|
134
|
+
|
|
135
|
+
- [Lit 3](https://lit.dev/) — Web components framework
|
|
136
|
+
- [TypeScript 5.9](https://www.typescriptlang.org/) — Type safety
|
|
137
|
+
- [Vite 8](https://vite.dev/) — Build tool and dev server
|
|
138
|
+
- [Tailwind CSS 4](https://tailwindcss.com/) — Design tokens and utility classes
|
|
139
|
+
|
|
140
|
+
## License
|
|
141
|
+
|
|
142
|
+
MIT
|