@wcomp/elementum 0.0.0-stage → 0.2.0
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/LICENSE +21 -0
- package/README.md +282 -2
- package/custom-elements.json +3613 -0
- package/mcp/server.js +593 -0
- package/package.json +77 -4
- package/skills/elementum-break-ui/CATALOG.md +11 -0
- package/skills/elementum-break-ui/SKILL.md +16 -0
- package/skills/elementum-mobile/SKILL.md +18 -0
- package/skills/elementum-motion/SKILL.md +18 -0
- package/skills/elementum-motion/STANDARDS.md +15 -0
- package/skills/elementum-penpot/SKILL.md +45 -0
- package/skills/elementum-ui/CATALOG.md +14 -0
- package/skills/elementum-ui/SKILL.md +21 -0
- package/src/ag-ui.js +474 -0
- package/src/behaviors/index.js +760 -0
- package/src/components/el-accordion.js +201 -0
- package/src/components/el-alert-dialog.js +186 -0
- package/src/components/el-alert.js +254 -0
- package/src/components/el-aspect-ratio.js +73 -0
- package/src/components/el-autocomplete.js +775 -0
- package/src/components/el-avatar.js +271 -0
- package/src/components/el-badge.js +131 -0
- package/src/components/el-border-beam.js +135 -0
- package/src/components/el-breadcrumb.js +203 -0
- package/src/components/el-button.js +231 -0
- package/src/components/el-calendar.js +436 -0
- package/src/components/el-callout.js +158 -0
- package/src/components/el-card.js +298 -0
- package/src/components/el-carousel.js +308 -0
- package/src/components/el-chart.js +632 -0
- package/src/components/el-checkbox-card.js +221 -0
- package/src/components/el-checkbox.js +208 -0
- package/src/components/el-chip.js +276 -0
- package/src/components/el-code-block.js +230 -0
- package/src/components/el-collapsible.js +124 -0
- package/src/components/el-command.js +556 -0
- package/src/components/el-context-menu.js +328 -0
- package/src/components/el-data-list.js +210 -0
- package/src/components/el-datepicker.js +192 -0
- package/src/components/el-dialog.js +272 -0
- package/src/components/el-diff-viewer.js +441 -0
- package/src/components/el-drawer.js +782 -0
- package/src/components/el-dropdown.js +182 -0
- package/src/components/el-dropzone.js +242 -0
- package/src/components/el-empty-state.js +130 -0
- package/src/components/el-field.js +394 -0
- package/src/components/el-form.js +185 -0
- package/src/components/el-input.js +229 -0
- package/src/components/el-inset.js +90 -0
- package/src/components/el-insight-card.js +263 -0
- package/src/components/el-kbd.js +151 -0
- package/src/components/el-menubar.js +254 -0
- package/src/components/el-meter.js +183 -0
- package/src/components/el-navbar.js +294 -0
- package/src/components/el-navigation-menu.js +327 -0
- package/src/components/el-number-field.js +510 -0
- package/src/components/el-number-flow.js +164 -0
- package/src/components/el-otp-input.js +266 -0
- package/src/components/el-pagination.js +231 -0
- package/src/components/el-popover.js +288 -0
- package/src/components/el-preview-card.js +202 -0
- package/src/components/el-progress.js +179 -0
- package/src/components/el-prompt-input.js +383 -0
- package/src/components/el-radio-card.js +360 -0
- package/src/components/el-radio.js +257 -0
- package/src/components/el-rating.js +165 -0
- package/src/components/el-reasoning-card.js +293 -0
- package/src/components/el-resizable.js +324 -0
- package/src/components/el-router.js +305 -0
- package/src/components/el-scroll-area.js +150 -0
- package/src/components/el-segmented-control.js +282 -0
- package/src/components/el-select.js +220 -0
- package/src/components/el-separator.js +85 -0
- package/src/components/el-sidebar.js +386 -0
- package/src/components/el-skeleton.js +156 -0
- package/src/components/el-slider.js +351 -0
- package/src/components/el-sources.js +288 -0
- package/src/components/el-spinner.js +159 -0
- package/src/components/el-streaming-text.js +199 -0
- package/src/components/el-switch.js +221 -0
- package/src/components/el-table.js +397 -0
- package/src/components/el-tabs.js +235 -0
- package/src/components/el-task-list.js +230 -0
- package/src/components/el-textarea.js +175 -0
- package/src/components/el-theme-switch.js +120 -0
- package/src/components/el-timeline.js +254 -0
- package/src/components/el-toast.js +778 -0
- package/src/components/el-toggle.js +311 -0
- package/src/components/el-tool-call.js +386 -0
- package/src/components/el-toolbar.js +183 -0
- package/src/components/el-tooltip.js +172 -0
- package/src/components/el-tree-view.js +261 -0
- package/src/components/el-visually-hidden.js +32 -0
- package/src/elementum.js +504 -0
- package/src/index.d.ts +1093 -0
- package/src/index.js +112 -0
- package/src/signal.js +215 -0
- package/src/ssr.js +136 -0
- package/src/template.js +321 -0
- package/src/tokens.css +416 -0
- package/tokens/figma-tokens.json +69 -0
- package/tokens/penpot-tokens.json +98 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 wcomp / Elementum Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,283 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @wcomp/elementum
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/pinguxx/Elementum/actions/workflows/ci.yml)
|
|
4
|
+

|
|
5
|
+

|
|
6
|
+

|
|
7
|
+
|
|
8
|
+
> **Elementum** (*Latin*: /e.leˈmen.tum/) — **An AI-native, framework-independent UI engineering platform** built on standard Custom Elements, fine-grained micro-signals, W3C DTCG tokens, Declarative Shadow DOM SSR, and MCP/AG-UI tooling.
|
|
9
|
+
>
|
|
10
|
+
> **Live Showcase:** https://elementum-sage.vercel.app/ · **Catalog (109 elements):** https://elementum-sage.vercel.app/examples/index.html · **AG-UI Demo:** https://elementum-sage.vercel.app/examples/ag-ui.html · **Live DSD SSR:** https://elementum-sage.vercel.app/ssr
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 🧪 Verification & Browser Matrix (Beta — `v0.2.0`)
|
|
15
|
+
|
|
16
|
+
Every architectural claim in Elementum is backed by automated verification in CI:
|
|
17
|
+
|
|
18
|
+
| Verification Layer | Tooling | Scope |
|
|
19
|
+
| :--- | :--- | :--- |
|
|
20
|
+
| **Core Signals & Fuzzing** | `node:test` (`test/signal-torture.test.js`) | Cycle detection, stale-dep cleanup, AbortSignal disposal, 100-graph randomized DAG fuzzer |
|
|
21
|
+
| **Unit & Contract Suite** | `node:test` + `happy-dom` (Node 20/22/24, Ubuntu & Windows) | **208+ tests**, **≥ 95% line coverage**, automated Source-vs-Catalog Diff (`npm run catalog:diff`) |
|
|
22
|
+
| **Real Browser E2E** | Playwright (`npm run test:e2e`) — Chromium, Firefox, WebKit | Native `<dialog>` focus restoration, `ElementInternals` `<form>` submit/reset, mobile `375px` overflow, AG-UI SSE |
|
|
23
|
+
| **Declarative Shadow DOM SSR** | Playwright (`/?hydrate=0` Zero-JS & `/?hydrate=1` Hydrated) | Native `<template shadowrootmode="open">` attachment with JS disabled + clean client hydration |
|
|
24
|
+
| **Accessibility** | `@axe-core/playwright` (WCAG 2.2 AA ruleset) + MCP `lint_accessibility` | Automated real-browser `axe-core` checks on Home, AG-UI, and SSR pages |
|
|
25
|
+
| **Security & MCP Hardening** | `test/security.test.js` | XSS escaping in `template.js` & `ssr.js`, URL sanitization, prototype-pollution guards, 128 KB MCP payload cap |
|
|
26
|
+
| **Performance Benchmarks** | `npm run bench` (`tools/benchmark.js`) | 10,000 signal updates in ~7 ms · 1,000 DSD SSR renders in ~15 ms · 1,000 DOM mounts in ~60 ms |
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## ⚡ Quick Start
|
|
31
|
+
|
|
32
|
+
Elementum runs directly in any modern browser without Webpack, Vite, or Babel.
|
|
33
|
+
|
|
34
|
+
```html
|
|
35
|
+
<!DOCTYPE html>
|
|
36
|
+
<html lang="en">
|
|
37
|
+
<head>
|
|
38
|
+
<!-- 1. Include Design Tokens -->
|
|
39
|
+
<link rel="stylesheet" href="https://unpkg.com/@wcomp/elementum/tokens.css" />
|
|
40
|
+
|
|
41
|
+
<!-- 2. Import Component Library -->
|
|
42
|
+
<script type="module" src="https://unpkg.com/@wcomp/elementum"></script>
|
|
43
|
+
</head>
|
|
44
|
+
<body>
|
|
45
|
+
<!-- Native Form with Form-Associated Custom Elements -->
|
|
46
|
+
<form id="my-form">
|
|
47
|
+
<el-input name="username" placeholder="Enter username...">
|
|
48
|
+
<span slot="prefix">👤</span>
|
|
49
|
+
</el-input>
|
|
50
|
+
|
|
51
|
+
<el-select name="role" value="member">
|
|
52
|
+
<option value="member">Team Member</option>
|
|
53
|
+
<option value="admin">Administrator</option>
|
|
54
|
+
</el-select>
|
|
55
|
+
|
|
56
|
+
<el-button type="submit" variant="primary">Save Changes</el-button>
|
|
57
|
+
</form>
|
|
58
|
+
</body>
|
|
59
|
+
</html>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## 💡 Core Principles
|
|
65
|
+
|
|
66
|
+
`Elementum` is inspired by minimalist libraries like `uce`, modernizing the developer experience with standard browser primitives:
|
|
67
|
+
- **Shadow DOM by default** with automatic Constructable Stylesheet adoption (`new CSSStyleSheet()`).
|
|
68
|
+
- **Fine-grained micro-signals** (`signal`, `computed`, `effect`): state updates mutate **only the exact bound DOM text or attribute node**—the component never re-renders, preserving child component state and input focus.
|
|
69
|
+
- **Form-Associated Custom Elements (FACE)**: `static formAssociated = true` enables native `<form>` submission, reset, and validation via `ElementInternals`.
|
|
70
|
+
- **Zero build requirement**: Plain ES modules (`<script type="module">`), no Babel, decorators, or compile step needed. Runs in SSR / Node.js cleanly.
|
|
71
|
+
- **Light & Dark Mode**: Built-in CSS custom property theme tokens with automatic `prefers-color-scheme` and `<el-theme-switch>`.
|
|
72
|
+
- **Leak-free lifecycle**: Automatically tracks and tears down event listeners and signal subscriptions via `this.signal` (`AbortSignal`).
|
|
73
|
+
- **WCAG 2.2 AA Compliant**: Built-in 24x24px minimum target sizes, high-contrast `:focus-visible` rings, dialog focus preservation, and HTML5 Constraint Validation API (`ElementInternals.setValidity`).
|
|
74
|
+
- **Figma 1:1 Parity**: Direct mapping to Figma Component Variants and Figma Variables.
|
|
75
|
+
- **AI Agent & MCP Ready**: Generates standard W3C `custom-elements.json` and includes a built-in MCP server for coding agents.
|
|
76
|
+
- **CI/CD & Automation**: GitHub Actions multi-OS / multi-Node matrix test runner and Dependabot automated dependency updates.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Component Catalog
|
|
81
|
+
|
|
82
|
+
| Component | Tag Name | Description |
|
|
83
|
+
| :--- | :--- | :--- |
|
|
84
|
+
| **Button** | `<el-button>` | 1:1 Figma variant parity (`primary`, `secondary`, `danger`, `ghost`, sizes `sm`/`md`/`lg`). |
|
|
85
|
+
| **Badge** | `<el-badge>` | Status indicator pill (`default`, `success`, `danger`). |
|
|
86
|
+
| **Input** | `<el-input>` | Form-associated input with `prefix` and `suffix` icon slots. |
|
|
87
|
+
| **Dropdown** | `<el-dropdown>` | Popover container with light-dismiss (closes on outside click or <kbd>Esc</kbd>). |
|
|
88
|
+
| **Calendar** | `<el-calendar>` | Standalone 42-day accessible month grid with traversal. |
|
|
89
|
+
| **Datepicker** | `<el-datepicker>` | Form-associated composite datepicker combining input, dropdown, calendar, and quick actions. |
|
|
90
|
+
| **Dialog / Modal** | `<el-dialog>` | Native `<dialog>` modal with backdrop blur, overscroll containment, and light-dismiss. |
|
|
91
|
+
| **Tabs** | `<el-tabs>`, `<el-tab>` | W3C accessible tablist with keyboard arrow navigation. |
|
|
92
|
+
| **Select** | `<el-select>` | Form-associated custom dropdown selection. |
|
|
93
|
+
| **Switch** | `<el-switch>` | Form-associated toggle switch with keyboard navigation (<kbd>Space</kbd>/<kbd>Enter</kbd>). |
|
|
94
|
+
| **Tooltip** | `<el-tooltip>` | Lightweight tooltip bubble with top/bottom/left/right placement. |
|
|
95
|
+
| **Accordion** | `<el-accordion>`, `<el-accordion-item>` | W3C accessible disclosure accordion supporting single or multi-expand. |
|
|
96
|
+
| **Table** | `<el-table>` | Signal-driven data grid with column sorting and multi-row selection. |
|
|
97
|
+
| **Theme Switch** | `<el-theme-switch>` | Toggles between Light ☀️ and Dark 🌙 mode with `localStorage` persistence. |
|
|
98
|
+
| **Toast** | `<el-toaster>` | Viewport overlay for programmatic notifications (`toast.success()`, `toast.error()`). |
|
|
99
|
+
| **Progress** | `<el-progress>` | Determinate & indeterminate animated progress bar (`role="progressbar"`). |
|
|
100
|
+
| **Spinner** | `<el-spinner>` | Accessible SVG loading spinner (`role="status"`). |
|
|
101
|
+
| **Avatar** | `<el-avatar>`, `<el-avatar-group>` | User avatar with image fallback, automatic initials, and status dot. |
|
|
102
|
+
| **Drawer** | `<el-drawer>` | Slide-over drawer overlay (`left`, `right`, `top`, `bottom`) with focus trap. |
|
|
103
|
+
| **Segmented** | `<el-segmented-control>` | Form-associated pill switcher with keyboard arrow navigation. |
|
|
104
|
+
| **Pagination** | `<el-pagination>` | Accessible numeric page navigation with ellipsis windowing and `pagechange` events. |
|
|
105
|
+
| **Chip / Pill** | `<el-chip>` | Interactive tag with `selectable` and `removable` dismiss modes (`role="button"`). |
|
|
106
|
+
| **Autocomplete** | `<el-autocomplete>` | Form-associated combobox supporting single or multiselect (`multiple`) with inline chips, remote URL debouncing, and ARIA 1.2 / WCAG 2.2 accessibility. |
|
|
107
|
+
| **Number Flow** | `<el-number-flow>` | Smooth vertical rolling odometer number reels (*NumberFlow* style) with physical easing and reduced-motion fallback. |
|
|
108
|
+
| **OTP Input** | `<el-otp-input>` | Form-associated segmented PIN / verification code input with auto-advance, backspace retreat, and paste splitting. |
|
|
109
|
+
| **Command Palette** | `<el-command>` | Accessible keyboard-first command menu (*cmdk* style) with <kbd>⌘K</kbd> / <kbd>Ctrl+K</kbd> shortcut, fuzzy search, and group headers. |
|
|
110
|
+
| **Prompt Input** | `<el-prompt-input>` | Beautiful UI-style auto-expanding AI prompt composer with action bar slots, model chips, and Enter-to-submit handling. |
|
|
111
|
+
| **Reasoning Card** | `<el-reasoning-card>` | Collapsible AI thought disclosure with active breathing pulse dot, elapsed duration timer, and smooth accordion expansion. |
|
|
112
|
+
| **Border Beam** | `<el-border-beam>` | Hardware-accelerated luminous gradient ray traveling around container perimeters (Magic UI style). |
|
|
113
|
+
| **Streaming Text** | `<el-streaming-text>` | Organic token-by-token streaming typewriter text with customizable cadence, blinking cursor, and completion events. |
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Interactive Examples & Showcase
|
|
118
|
+
|
|
119
|
+
- **[examples/ledgerflow.html](examples/ledgerflow.html)**: **LedgerFlow (Penpot → MCP Generated App)**: End-to-end fintech dashboard designed in **[Penpot](https://design.penpot.app/?screen=viewer&file-id=42288968-6e5e-808d-8008-f77162b618ca&page-id=d8ded059-05ee-80c0-8008-f774c97dd053§ion=interactions&index=0&share-id=8218fc5e-f68d-4bab-8fd7-283dd92586e8)** and compiled via `npm run penpot:generate` into 15 validated Elementum Web Components (`<el-number-flow>`, `<el-chart>`, `<el-meter>`, `<el-drawer>`, `<el-dialog>`, `<el-toaster>`).
|
|
120
|
+
- **[examples/references.html](file:///c:/dev/Elementum/examples/references.html)**: **Reference Hub (Anti-AI Slop)**: Real-world patterns reconstructed from curated galleries (SaaS Pricing with rolling odometers & border beams, Linear-style command menu, and segmented PIN auth).
|
|
121
|
+
- **[examples/agent-studio.html](file:///c:/dev/Elementum/examples/agent-studio.html)**: **AI Agent Studio & Command Center** demonstrating `<el-command>` (⌘K), `<el-prompt-input>`, `<el-reasoning-card>`, `<el-number-flow>` live token odometer, `<el-otp-input>` security key authorization, and `<el-border-beam>`.
|
|
122
|
+
- **[index.html](file:///c:/dev/Elementum/index.html)**: Interactive landing portal directing to the applications. Run `npx serve .` to launch locally.
|
|
123
|
+
- **[examples/app.html](file:///c:/dev/Elementum/examples/app.html)**: Complete **Skyline Travel** booking dashboard demonstrating native form validation, confirmation modal dialogs, toast notifications, tabs, and theme toggling.
|
|
124
|
+
- **[examples/index.html](file:///c:/dev/Elementum/examples/index.html)**: Component showcase with standalone controls and live signal-reactive counter.
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Design Engineering & Agent Guides
|
|
129
|
+
|
|
130
|
+
### Installable Agent Skills (`npx skills add`)
|
|
131
|
+
Install Elementum's modular AI coding skills directly into Antigravity, Claude Code, Cursor, or Gemini CLI:
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
npx skills@latest add pinguxx/Elementum
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Included skills under [`skills/`](skills/):
|
|
138
|
+
- **`elementum-ui`**: Composing Elementum's 105 Web Components, signals, FACE forms, and AG-UI streams.
|
|
139
|
+
- **`elementum-motion`**: Shadow DOM motion physics, sub-300ms `ease-out`, origin-aware overlays, and reduced-motion standards.
|
|
140
|
+
- **`elementum-break-ui`**: Adversarial stress-testing checklist (320px mobile, dark mode hover contrast, keyboard-only, extreme content).
|
|
141
|
+
- **`elementum-mobile`**: Mobile-native CSS standards (`touch-action`, `100dvh`, safe areas, `overscroll-behavior`, iOS 16px input zoom prevention).
|
|
142
|
+
- **`elementum-penpot`**: Two-way Penpot MCP design system sync and Penpot-to-Elementum app codegen.
|
|
143
|
+
|
|
144
|
+
- **[docs/penpot-workflow.md](file:///c:/dev/Elementum/docs/penpot-workflow.md)**: Free & open-source design token workflow with Penpot (W3C DTCG JSON) and automated compilation.
|
|
145
|
+
- **[docs/agent-craft-guide.md](file:///c:/dev/Elementum/docs/agent-craft-guide.md)**: Guide and system prompt rules for AI coding agents to banish generic AI look and adhere to high-craft standards.
|
|
146
|
+
- **[docs/theming.md](file:///c:/dev/Elementum/docs/theming.md)**: Complete design tokens, CSS custom properties, and `::part()` customization guide.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Framework Integration
|
|
151
|
+
|
|
152
|
+
`@wcomp/elementum` works natively in vanilla HTML, React 19, Vue 3, Svelte 5, and Next.js. See **[docs/framework-integration.md](file:///c:/dev/Elementum/docs/framework-integration.md)** for complete setup instructions and TypeScript configuration.
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Project Structure
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
Elementum/
|
|
160
|
+
├── .github/
|
|
161
|
+
│ ├── dependabot.yml # Automated weekly dependencies & actions updates
|
|
162
|
+
│ └── workflows/
|
|
163
|
+
│ └── ci.yml # Multi-node, multi-OS CI test workflow
|
|
164
|
+
├── docs/
|
|
165
|
+
│ └── framework-integration.md # React 19, Vue 3, Svelte 5, and Next.js guide
|
|
166
|
+
├── src/
|
|
167
|
+
│ ├── signal.js # Micro-signals (~80 lines: signal, computed, effect)
|
|
168
|
+
│ ├── template.js # Tagged template engine (html, css, surgical DOM parts)
|
|
169
|
+
│ ├── elementum.js # Base class with Shadow DOM, styles, and formAssociated
|
|
170
|
+
│ ├── tokens.css # Light & Dark CSS custom properties from Figma
|
|
171
|
+
│ ├── index.js # Public library exports
|
|
172
|
+
│ ├── index.d.ts # Complete TypeScript ambient definitions
|
|
173
|
+
│ └── components/
|
|
174
|
+
│ ├── el-button.js # Reference button matching Figma variants
|
|
175
|
+
│ ├── el-badge.js # Reference badge component
|
|
176
|
+
│ ├── el-input.js # Form-associated input
|
|
177
|
+
│ ├── el-dropdown.js # Light-dismiss dropdown overlay
|
|
178
|
+
│ ├── el-calendar.js # Standalone calendar grid
|
|
179
|
+
│ ├── el-datepicker.js # Composite datepicker
|
|
180
|
+
│ ├── el-dialog.js # Native modal dialog with backdrop containment
|
|
181
|
+
│ ├── el-tabs.js # Accessible W3C tabs with keyboard navigation
|
|
182
|
+
│ ├── el-select.js # Form-associated custom select
|
|
183
|
+
│ ├── el-switch.js # Form-associated toggle switch
|
|
184
|
+
│ ├── el-tooltip.js # Accessible anchored tooltip
|
|
185
|
+
│ ├── el-accordion.js # Accessible disclosure accordion
|
|
186
|
+
│ ├── el-table.js # Reactive data table with sorting and selection
|
|
187
|
+
│ ├── el-toast.js # Programmatic toast notification system
|
|
188
|
+
│ ├── el-theme-switch.js # Light / Dark mode toggle
|
|
189
|
+
│ ├── el-progress.js # Determinate & indeterminate progress bar
|
|
190
|
+
│ ├── el-spinner.js # Animated accessible SVG spinner
|
|
191
|
+
│ ├── el-avatar.js # User avatar & avatar group with fallback
|
|
192
|
+
│ ├── el-drawer.js # Accessible slide-over drawer overlay
|
|
193
|
+
│ ├── el-segmented-control.js # Form-associated pill switcher
|
|
194
|
+
│ ├── el-pagination.js # Accessible numeric pagination controls
|
|
195
|
+
│ ├── el-chip.js # Interactive filter chips & pills
|
|
196
|
+
│ └── el-autocomplete.js # Form-associated combobox & remote search
|
|
197
|
+
├── tools/
|
|
198
|
+
│ ├── sync-tokens.js # CLI to compile penpot/figma DTCG tokens into tokens.css
|
|
199
|
+
│ ├── sync-penpot-mcp.js # CLI to generate tokens, colors & 105 components in Penpot via MCP
|
|
200
|
+
│ └── create-component.js # CLI to scaffold new components (npm run create)
|
|
201
|
+
├── custom-elements.json # W3C Custom Elements Manifest (for agents & Storybook)
|
|
202
|
+
├── AGENT_GUIDE.md # Instructions for AI coding agents & developers
|
|
203
|
+
├── docs/
|
|
204
|
+
│ ├── theming.md # Design tokens and ::part() customization guide
|
|
205
|
+
│ └── framework-integration.md # React, Vue, Svelte, Angular integration
|
|
206
|
+
├── examples/
|
|
207
|
+
│ ├── app.html # Full travel booking mini-app
|
|
208
|
+
│ └── index.html # Component showcase
|
|
209
|
+
├── index.html # Live documentation and demo portal
|
|
210
|
+
├── mcp/
|
|
211
|
+
│ └── server.js # Model Context Protocol server for AI coding agents
|
|
212
|
+
└── test/ # Node.js automated test runner suite
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## 🎨 Theming & Accessibility (WCAG 2.2)
|
|
218
|
+
|
|
219
|
+
- **Theming Guide**: See [docs/theming.md](docs/theming.md) for the full catalog of design tokens and exposed CSS ::part() selectors.
|
|
220
|
+
- **Agent Guide**: See [AGENT_GUIDE.md](AGENT_GUIDE.md) for guidelines on building, testing, and reviewing Elementum components.
|
|
221
|
+
- **Framework Integration**: See [docs/framework-integration.md](docs/framework-integration.md) for React, Vue, Svelte, and Angular setup.
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## 🚀 Declarative Shadow DOM (DSD) SSR
|
|
226
|
+
|
|
227
|
+
Elementum includes built-in server-side rendering support emitting standard `<template shadowrootmode="open">` for zero-CLS first paint in Next.js, Nuxt, Astro, and Node.js:
|
|
228
|
+
|
|
229
|
+
```javascript
|
|
230
|
+
import { renderComponentToDSD } from '@wcomp/elementum/ssr';
|
|
231
|
+
import { ElButton } from '@wcomp/elementum';
|
|
232
|
+
|
|
233
|
+
// Outputs HTML with Declarative Shadow DOM and encapsulated styles
|
|
234
|
+
const html = renderComponentToDSD('el-button', ElButton, { variant: 'primary' }, 'Submit');
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Run the live zero-dependency Node.js SSR server (`?hydrate=0` for pure Zero-JS DSD, `?hydrate=1` for progressive hydration) or view the pre-rendered snapshot [`examples/ssr-demo.html`](examples/ssr-demo.html):
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
npm run ssr
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
## Penpot & Figma Design System Sync
|
|
246
|
+
|
|
247
|
+
### Code → Penpot (MCP Server Sync)
|
|
248
|
+
Generate all **54 W3C DTCG tokens** (Core, Light, Dark sets), **28 library colors**, and **105 Master Components** (across 8 categories) directly inside an open **[Penpot](https://design.penpot.app)** file connected via the Penpot MCP Plugin:
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
npm run penpot:mcp -- --url "https://design.penpot.app/mcp/stream?userToken=<YOUR_TOKEN>"
|
|
252
|
+
# Or via environment variable:
|
|
253
|
+
PENPOT_MCP_URL="https://design.penpot.app/mcp/stream?userToken=<YOUR_TOKEN>" npm run penpot:mcp
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
### Penpot / Figma → Code (Token Compiler)
|
|
257
|
+
Synchronize exported W3C DTCG tokens from `tokens/penpot-tokens.json` (or `tokens/figma-tokens.json`) into `src/tokens.css`:
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
npm run tokens:sync tokens/penpot-tokens.json
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
See **[docs/penpot-workflow.md](docs/penpot-workflow.md)** for full setup instructions, CLI flags (`--url`, `--token`, `--dry-run`), and Penpot MCP security notes.
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
## Agent MCP Server
|
|
268
|
+
|
|
269
|
+
Run the built-in MCP server for AI coding agents:
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
node mcp/server.js
|
|
273
|
+
# Or via package bin
|
|
274
|
+
npx elementum-mcp
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Exposed tools:
|
|
278
|
+
- `list_components`: Lists all components in Elementum
|
|
279
|
+
- `get_component_doc`: Retrieves attributes, slots, events, and CSS parts
|
|
280
|
+
- `list_tokens`: Queries design tokens by category (color, spacing, radius)
|
|
281
|
+
- `generate_snippet`: Generates valid HTML markup matching Figma variants
|
|
282
|
+
- `scaffold_component`: Scaffolds standard boilerplate code for new components
|
|
283
|
+
- `validate_accessibility`: Audits component markup against WCAG 2.2 rules
|