@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.
Files changed (102) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +282 -2
  3. package/custom-elements.json +3613 -0
  4. package/mcp/server.js +593 -0
  5. package/package.json +77 -4
  6. package/skills/elementum-break-ui/CATALOG.md +11 -0
  7. package/skills/elementum-break-ui/SKILL.md +16 -0
  8. package/skills/elementum-mobile/SKILL.md +18 -0
  9. package/skills/elementum-motion/SKILL.md +18 -0
  10. package/skills/elementum-motion/STANDARDS.md +15 -0
  11. package/skills/elementum-penpot/SKILL.md +45 -0
  12. package/skills/elementum-ui/CATALOG.md +14 -0
  13. package/skills/elementum-ui/SKILL.md +21 -0
  14. package/src/ag-ui.js +474 -0
  15. package/src/behaviors/index.js +760 -0
  16. package/src/components/el-accordion.js +201 -0
  17. package/src/components/el-alert-dialog.js +186 -0
  18. package/src/components/el-alert.js +254 -0
  19. package/src/components/el-aspect-ratio.js +73 -0
  20. package/src/components/el-autocomplete.js +775 -0
  21. package/src/components/el-avatar.js +271 -0
  22. package/src/components/el-badge.js +131 -0
  23. package/src/components/el-border-beam.js +135 -0
  24. package/src/components/el-breadcrumb.js +203 -0
  25. package/src/components/el-button.js +231 -0
  26. package/src/components/el-calendar.js +436 -0
  27. package/src/components/el-callout.js +158 -0
  28. package/src/components/el-card.js +298 -0
  29. package/src/components/el-carousel.js +308 -0
  30. package/src/components/el-chart.js +632 -0
  31. package/src/components/el-checkbox-card.js +221 -0
  32. package/src/components/el-checkbox.js +208 -0
  33. package/src/components/el-chip.js +276 -0
  34. package/src/components/el-code-block.js +230 -0
  35. package/src/components/el-collapsible.js +124 -0
  36. package/src/components/el-command.js +556 -0
  37. package/src/components/el-context-menu.js +328 -0
  38. package/src/components/el-data-list.js +210 -0
  39. package/src/components/el-datepicker.js +192 -0
  40. package/src/components/el-dialog.js +272 -0
  41. package/src/components/el-diff-viewer.js +441 -0
  42. package/src/components/el-drawer.js +782 -0
  43. package/src/components/el-dropdown.js +182 -0
  44. package/src/components/el-dropzone.js +242 -0
  45. package/src/components/el-empty-state.js +130 -0
  46. package/src/components/el-field.js +394 -0
  47. package/src/components/el-form.js +185 -0
  48. package/src/components/el-input.js +229 -0
  49. package/src/components/el-inset.js +90 -0
  50. package/src/components/el-insight-card.js +263 -0
  51. package/src/components/el-kbd.js +151 -0
  52. package/src/components/el-menubar.js +254 -0
  53. package/src/components/el-meter.js +183 -0
  54. package/src/components/el-navbar.js +294 -0
  55. package/src/components/el-navigation-menu.js +327 -0
  56. package/src/components/el-number-field.js +510 -0
  57. package/src/components/el-number-flow.js +164 -0
  58. package/src/components/el-otp-input.js +266 -0
  59. package/src/components/el-pagination.js +231 -0
  60. package/src/components/el-popover.js +288 -0
  61. package/src/components/el-preview-card.js +202 -0
  62. package/src/components/el-progress.js +179 -0
  63. package/src/components/el-prompt-input.js +383 -0
  64. package/src/components/el-radio-card.js +360 -0
  65. package/src/components/el-radio.js +257 -0
  66. package/src/components/el-rating.js +165 -0
  67. package/src/components/el-reasoning-card.js +293 -0
  68. package/src/components/el-resizable.js +324 -0
  69. package/src/components/el-router.js +305 -0
  70. package/src/components/el-scroll-area.js +150 -0
  71. package/src/components/el-segmented-control.js +282 -0
  72. package/src/components/el-select.js +220 -0
  73. package/src/components/el-separator.js +85 -0
  74. package/src/components/el-sidebar.js +386 -0
  75. package/src/components/el-skeleton.js +156 -0
  76. package/src/components/el-slider.js +351 -0
  77. package/src/components/el-sources.js +288 -0
  78. package/src/components/el-spinner.js +159 -0
  79. package/src/components/el-streaming-text.js +199 -0
  80. package/src/components/el-switch.js +221 -0
  81. package/src/components/el-table.js +397 -0
  82. package/src/components/el-tabs.js +235 -0
  83. package/src/components/el-task-list.js +230 -0
  84. package/src/components/el-textarea.js +175 -0
  85. package/src/components/el-theme-switch.js +120 -0
  86. package/src/components/el-timeline.js +254 -0
  87. package/src/components/el-toast.js +778 -0
  88. package/src/components/el-toggle.js +311 -0
  89. package/src/components/el-tool-call.js +386 -0
  90. package/src/components/el-toolbar.js +183 -0
  91. package/src/components/el-tooltip.js +172 -0
  92. package/src/components/el-tree-view.js +261 -0
  93. package/src/components/el-visually-hidden.js +32 -0
  94. package/src/elementum.js +504 -0
  95. package/src/index.d.ts +1093 -0
  96. package/src/index.js +112 -0
  97. package/src/signal.js +215 -0
  98. package/src/ssr.js +136 -0
  99. package/src/template.js +321 -0
  100. package/src/tokens.css +416 -0
  101. package/tokens/figma-tokens.json +69 -0
  102. package/tokens/penpot-tokens.json +98 -0
package/mcp/server.js ADDED
@@ -0,0 +1,593 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Elementum Design System MCP Server
4
+ * Exposes component schemas, tokens, and markup generation tools to AI coding agents.
5
+ */
6
+
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
9
+ import { fileURLToPath } from 'node:url';
10
+ import readline from 'node:readline';
11
+
12
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
13
+ const rootDir = path.resolve(__dirname, '..');
14
+
15
+ // Load Custom Elements Manifest and Figma Tokens
16
+ const manifestPath = path.join(rootDir, 'custom-elements.json');
17
+ const tokensPath = path.join(rootDir, 'tokens', 'figma-tokens.json');
18
+ const pkgPath = path.join(rootDir, 'package.json');
19
+
20
+ const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
21
+ const tokens = JSON.parse(fs.readFileSync(tokensPath, 'utf8'));
22
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
23
+
24
+ const MAX_PAYLOAD_BYTES = 128 * 1024;
25
+ const SAFE_TAG_RE = /^[a-z][a-z0-9]*-[a-z0-9-]+$/;
26
+ const SAFE_CLASS_RE = /^[A-Z][A-Za-z0-9_]*$/;
27
+ const SAFE_ATTR_RE = /^[a-z][a-z0-9-]*$/;
28
+ const GLOBAL_HTML_ATTRS = new Set([
29
+ 'id', 'class', 'style', 'slot', 'part', 'title', 'lang', 'dir', 'hidden',
30
+ 'tabindex', 'role', 'draggable', 'contenteditable', 'spellcheck', 'translate',
31
+ 'unstyled', 'name', 'value', 'disabled', 'required', 'readonly', 'autofocus',
32
+ ]);
33
+
34
+ function escapeAttr(val) {
35
+ return String(val ?? '')
36
+ .replace(/&/g, '&')
37
+ .replace(/"/g, '"')
38
+ .replace(/</g, '&lt;')
39
+ .replace(/>/g, '&gt;');
40
+ }
41
+
42
+ function escapeText(val) {
43
+ return String(val ?? '')
44
+ .replace(/&/g, '&amp;')
45
+ .replace(/</g, '&lt;')
46
+ .replace(/>/g, '&gt;');
47
+ }
48
+
49
+ const allDeclarations = manifest.modules.flatMap((m) =>
50
+ (m.declarations || []).map((d) => ({ ...d, modulePath: m.path }))
51
+ );
52
+ const declByTag = new Map(allDeclarations.map((d) => [d.tagName, d]));
53
+
54
+ const TOOLS = [
55
+ {
56
+ name: 'list_components',
57
+ description: 'Lists all available Web Components in the Elementum Design System.',
58
+ inputSchema: {
59
+ type: 'object',
60
+ properties: {},
61
+ },
62
+ },
63
+ {
64
+ name: 'get_component_doc',
65
+ description: 'Retrieves attributes, slots, events, and CSS parts for an Elementum component.',
66
+ inputSchema: {
67
+ type: 'object',
68
+ properties: {
69
+ tag: {
70
+ type: 'string',
71
+ description: 'The custom element tag name, e.g. "el-button" or "el-badge"',
72
+ },
73
+ },
74
+ required: ['tag'],
75
+ },
76
+ },
77
+ {
78
+ name: 'list_tokens',
79
+ description: 'Lists Figma design tokens (colors, spacing, radii) for the design system.',
80
+ inputSchema: {
81
+ type: 'object',
82
+ properties: {
83
+ category: {
84
+ type: 'string',
85
+ enum: ['color', 'spacing', 'radius', 'all'],
86
+ description: 'Token category to filter by.',
87
+ },
88
+ },
89
+ },
90
+ },
91
+ {
92
+ name: 'generate_snippet',
93
+ description: 'Generates valid Elementum Web Component HTML markup matching Figma variants.',
94
+ inputSchema: {
95
+ type: 'object',
96
+ properties: {
97
+ tag: { type: 'string', description: 'Component tag, e.g. "el-button"' },
98
+ variant: { type: 'string', description: 'Visual variant, e.g. "primary", "secondary", "danger"' },
99
+ size: { type: 'string', description: 'Size variant, e.g. "sm", "md", "lg"' },
100
+ label: { type: 'string', description: 'Content text for the default slot' },
101
+ disabled: { type: 'boolean', description: 'Whether the element is disabled' },
102
+ },
103
+ required: ['tag'],
104
+ },
105
+ },
106
+ {
107
+ name: 'scaffold_component',
108
+ description: 'Scaffolds standard boilerplate JavaScript code for a new Elementum Web Component adhering to design system standards.',
109
+ inputSchema: {
110
+ type: 'object',
111
+ properties: {
112
+ tag: { type: 'string', description: 'Component tag, e.g. "el-card"' },
113
+ name: { type: 'string', description: 'Component class name, e.g. "ElCard"' },
114
+ description: { type: 'string', description: 'Component description' },
115
+ formAssociated: { type: 'boolean', description: 'Whether the component associates with forms' },
116
+ attributes: {
117
+ type: 'array',
118
+ items: { type: 'string' },
119
+ description: 'Observed attributes, e.g. ["variant", "disabled"]',
120
+ },
121
+ },
122
+ required: ['tag'],
123
+ },
124
+ },
125
+ {
126
+ name: 'lint_accessibility',
127
+ description: 'Static HTML accessibility linter for common WCAG 2.2 labeling and attribute issues (not a substitute for real-browser axe-core auditing).',
128
+ inputSchema: {
129
+ type: 'object',
130
+ properties: {
131
+ markup: { type: 'string', description: 'HTML markup snippet to inspect' },
132
+ },
133
+ required: ['markup'],
134
+ },
135
+ },
136
+ {
137
+ name: 'validate_accessibility',
138
+ description: 'Alias for lint_accessibility: static HTML accessibility linter for common WCAG 2.2 labeling issues.',
139
+ inputSchema: {
140
+ type: 'object',
141
+ properties: {
142
+ markup: { type: 'string', description: 'HTML markup snippet to inspect' },
143
+ },
144
+ required: ['markup'],
145
+ },
146
+ },
147
+ {
148
+ name: 'suggest_component',
149
+ description: 'Recommends Elementum Web Components that best match a UI requirement or natural-language query.',
150
+ inputSchema: {
151
+ type: 'object',
152
+ properties: {
153
+ query: { type: 'string', description: 'UI requirement, e.g. "date picker", "code diff", "command palette"' },
154
+ limit: { type: 'number', description: 'Maximum results to return (default 5)' },
155
+ },
156
+ required: ['query'],
157
+ },
158
+ },
159
+ {
160
+ name: 'validate_component_usage',
161
+ description: 'Validates <el-*> tags and attributes in an HTML snippet against the live Custom Elements Manifest to catch hallucinated tags or props.',
162
+ inputSchema: {
163
+ type: 'object',
164
+ properties: {
165
+ markup: { type: 'string', description: 'HTML snippet containing <el-*> components' },
166
+ },
167
+ required: ['markup'],
168
+ },
169
+ },
170
+ {
171
+ name: 'get_component_maturity',
172
+ description: 'Returns machine-readable package version, component count, stability tier, and browser/testing verification metadata.',
173
+ inputSchema: {
174
+ type: 'object',
175
+ properties: {},
176
+ },
177
+ },
178
+ ];
179
+
180
+ export function handleToolCall(name, rawArgs) {
181
+ const args = rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {};
182
+
183
+ if (name === 'list_components') {
184
+ const list = allDeclarations.map((d) => ({
185
+ tag: d.tagName,
186
+ name: d.name,
187
+ description: d.description,
188
+ }));
189
+ return { count: list.length, components: list };
190
+ }
191
+
192
+ if (name === 'get_component_doc') {
193
+ const tag = typeof args.tag === 'string' ? args.tag.trim().toLowerCase() : '';
194
+ const match = declByTag.get(tag);
195
+
196
+ if (!match) {
197
+ return { error: `Component <${tag || 'unknown'}> not found in manifest.` };
198
+ }
199
+ return match;
200
+ }
201
+
202
+ if (name === 'list_tokens') {
203
+ const category = typeof args.category === 'string' ? args.category : 'all';
204
+ if (category === 'all') {
205
+ return tokens;
206
+ }
207
+ return tokens[category] || { error: `Category '${category}' not found.` };
208
+ }
209
+
210
+ if (name === 'generate_snippet') {
211
+ const tag = typeof args.tag === 'string' ? args.tag.trim().toLowerCase() : '';
212
+ if (!SAFE_TAG_RE.test(tag)) {
213
+ return { error: `Invalid custom element tag name: '${tag}'. Expected lowercase kebab-case with hyphen.` };
214
+ }
215
+ const { variant, size, label, disabled } = args;
216
+ const attrs = [];
217
+ if (variant !== undefined && variant !== '') attrs.push(`variant="${escapeAttr(variant)}"`);
218
+ if (size !== undefined && size !== '') attrs.push(`size="${escapeAttr(size)}"`);
219
+ if (disabled) attrs.push('disabled');
220
+
221
+ const attrStr = attrs.length > 0 ? ' ' + attrs.join(' ') : '';
222
+ const content = escapeText(label || '');
223
+ return {
224
+ snippet: `<${tag}${attrStr}>${content}</${tag}>`,
225
+ };
226
+ }
227
+
228
+ if (name === 'scaffold_component') {
229
+ const tag = typeof args.tag === 'string' ? args.tag.trim().toLowerCase() : '';
230
+ if (!SAFE_TAG_RE.test(tag)) {
231
+ return { error: `Invalid custom element tag name: '${tag}'. Expected lowercase kebab-case with hyphen.` };
232
+ }
233
+ const derivedName = tag
234
+ .split('-')
235
+ .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
236
+ .join('');
237
+ const className = typeof args.name === 'string' && SAFE_CLASS_RE.test(args.name) ? args.name : derivedName;
238
+ const formAssociated = !!args.formAssociated;
239
+ const rawAttrs = Array.isArray(args.attributes) ? args.attributes : ['disabled', 'size'];
240
+ const attrs = rawAttrs.filter((a) => typeof a === 'string' && SAFE_ATTR_RE.test(a));
241
+ const observed = attrs.map((a) => `'${a}'`).join(', ');
242
+
243
+ const signalDefs = attrs
244
+ .map((a) => {
245
+ if (a === 'disabled') return ` disabled = signal(false);`;
246
+ if (a === 'size') return ` size = signal('md'); // 'sm' | 'md' | 'lg'`;
247
+ return ` ${a} = signal('');`;
248
+ })
249
+ .join('\n');
250
+
251
+ const formAssocCode = formAssociated ? ` static formAssociated = true;\n` : '';
252
+ const formCallbacks = formAssociated
253
+ ? `
254
+ connected() {
255
+ this.setFormValue(this.value?.value || '');
256
+ this.validate?.();
257
+ }
258
+
259
+ formReset() {
260
+ this.value.value = this.getAttribute('value') || '';
261
+ this.setFormValue(this.value.value);
262
+ this.validate?.();
263
+ }
264
+
265
+ validate() {
266
+ this.setValidity({});
267
+ return true;
268
+ }
269
+ `
270
+ : '';
271
+
272
+ const code = `import { Elementum } from '../elementum.js';
273
+ import { html, css } from '../template.js';
274
+ import { signal } from '../signal.js';
275
+
276
+ /**
277
+ * ${args.description || `${className} component`}
278
+ */
279
+ export class ${className} extends Elementum {
280
+ ${formAssocCode} static observedAttributes = [${observed}];
281
+
282
+ ${signalDefs}
283
+ ${formCallbacks}
284
+ static styles = css\`
285
+ :host {
286
+ display: inline-block;
287
+ box-sizing: border-box;
288
+ font-family: var(--el-font-sans, system-ui, sans-serif);
289
+ }
290
+
291
+ :host(:focus-visible) {
292
+ outline: 2px solid var(--el-color-primary, #2563eb);
293
+ outline-offset: 2px;
294
+ }
295
+
296
+ .container {
297
+ display: flex;
298
+ align-items: center;
299
+ padding: var(--el-spacing-sm, 8px) var(--el-spacing-md, 16px);
300
+ border-radius: var(--el-radius-md, 8px);
301
+ background: var(--el-surface-card, #ffffff);
302
+ border: 1px solid var(--el-surface-border, #e5e7eb);
303
+ }
304
+ \`;
305
+
306
+ render() {
307
+ return html\`
308
+ <div class="container" part="container">
309
+ <slot></slot>
310
+ </div>
311
+ \`;
312
+ }
313
+ }
314
+
315
+ if (typeof customElements !== 'undefined' && !customElements.get('${tag}')) {
316
+ customElements.define('${tag}', ${className});
317
+ }
318
+ `;
319
+ return {
320
+ tag,
321
+ className,
322
+ code,
323
+ };
324
+ }
325
+
326
+ if (name === 'validate_accessibility' || name === 'lint_accessibility') {
327
+ const markup = typeof args.markup === 'string' ? args.markup : '';
328
+ const violations = [];
329
+ const warnings = [];
330
+ const passed = [];
331
+
332
+ // WCAG 4.1.2: Form elements must have accessible labels
333
+ const inputMatches = markup.match(/<el-input[^>]*>/gi) || [];
334
+ for (const match of inputMatches) {
335
+ const hasAriaLabel = /aria-label=/i.test(match);
336
+ const hasAriaLabelledby = /aria-labelledby=/i.test(match);
337
+ const hasId = /id=["']([^"']+)["']/i.test(match);
338
+ if (!hasAriaLabel && !hasAriaLabelledby && !hasId) {
339
+ violations.push({
340
+ criterion: 'WCAG 4.1.2 (Name, Role, Value)',
341
+ element: match,
342
+ message:
343
+ '<el-input> is missing an accessible name. Provide an aria-label, aria-labelledby, or an id associated with a <label for="...">.',
344
+ });
345
+ } else {
346
+ passed.push({
347
+ criterion: 'WCAG 4.1.2',
348
+ message: '<el-input> has accessible label attributes.',
349
+ });
350
+ }
351
+ }
352
+
353
+ // WCAG 4.1.2 / 1.1.1: Icon buttons or buttons with missing label
354
+ const buttonMatches = markup.match(/<el-button[^>]*>([\s\S]*?)<\/el-button>/gi) || [];
355
+ for (const match of buttonMatches) {
356
+ const tagOpen = match.match(/<el-button[^>]*>/i)?.[0] || '';
357
+ const textContent = match.replace(/<[^>]+>/g, '').trim();
358
+ const hasAriaLabel = /aria-label=/i.test(tagOpen);
359
+ if (!textContent && !hasAriaLabel) {
360
+ violations.push({
361
+ criterion: 'WCAG 1.1.1 (Non-text Content) / WCAG 4.1.2 (Name, Role, Value)',
362
+ element: tagOpen,
363
+ message: '<el-button> has no text content and is missing an aria-label.',
364
+ });
365
+ } else {
366
+ passed.push({
367
+ criterion: 'WCAG 4.1.2',
368
+ message: '<el-button> has accessible text or aria-label.',
369
+ });
370
+ }
371
+ }
372
+
373
+ // WCAG 1.1.1: Image without alt
374
+ const imgMatches = markup.match(/<img[^>]*>/gi) || [];
375
+ for (const match of imgMatches) {
376
+ if (!/alt=/i.test(match)) {
377
+ violations.push({
378
+ criterion: 'WCAG 1.1.1 (Non-text Content)',
379
+ element: match,
380
+ message: '<img> is missing an alt attribute. Provide descriptive alt text or alt="" for decorative images.',
381
+ });
382
+ }
383
+ }
384
+
385
+ // WCAG 2.5.8: Target Size Minimum (24x24px) / Text size
386
+ if (/font-size:\s*([0-9]+)px/i.test(markup)) {
387
+ const sizeMatch = markup.match(/font-size:\s*([0-9]+)px/i);
388
+ if (sizeMatch && Number(sizeMatch[1]) < 12) {
389
+ warnings.push({
390
+ criterion: 'WCAG 1.4.4 (Resize text)',
391
+ message: `Text size ${sizeMatch[1]}px may be too small for readability. Recommend >= 12px.`,
392
+ });
393
+ }
394
+ }
395
+
396
+ // WCAG 3.3.1: Error identification
397
+ if (
398
+ /aria-invalid="true"/i.test(markup) &&
399
+ !/aria-describedby=/i.test(markup) &&
400
+ !/aria-errormessage=/i.test(markup)
401
+ ) {
402
+ warnings.push({
403
+ criterion: 'WCAG 3.3.1 (Error Identification)',
404
+ message:
405
+ 'Element has aria-invalid="true" but lacks aria-describedby or aria-errormessage linking to the validation error explanation.',
406
+ });
407
+ }
408
+
409
+ return {
410
+ scope: 'static-html-lint',
411
+ disclaimer:
412
+ 'Static HTML lint only — run `npm run test:e2e` (@axe-core/playwright) in real browsers for full WCAG 2.2 AA auditing.',
413
+ valid: violations.length === 0,
414
+ violationsCount: violations.length,
415
+ warningsCount: warnings.length,
416
+ violations,
417
+ warnings,
418
+ passed,
419
+ };
420
+ }
421
+
422
+ if (name === 'suggest_component') {
423
+ const query = typeof args.query === 'string' ? args.query.trim().toLowerCase() : '';
424
+ if (!query) return { suggestions: [] };
425
+ const limit = Math.max(1, Math.min(20, Number(args.limit) || 5));
426
+ const terms = query.split(/\s+/).filter(Boolean);
427
+
428
+ const scored = allDeclarations
429
+ .map((d) => {
430
+ const hay = `${d.tagName} ${d.name} ${d.description || ''} ${(d.attributes || []).map((a) => a.name).join(' ')}`.toLowerCase();
431
+ let score = 0;
432
+ for (const t of terms) {
433
+ if (d.tagName.includes(t)) score += 4;
434
+ if ((d.name || '').toLowerCase().includes(t)) score += 3;
435
+ if (hay.includes(t)) score += 1;
436
+ }
437
+ return { tag: d.tagName, name: d.name, description: d.description || '', score };
438
+ })
439
+ .filter((s) => s.score > 0)
440
+ .sort((a, b) => b.score - a.score)
441
+ .slice(0, limit);
442
+
443
+ return { query, suggestions: scored };
444
+ }
445
+
446
+ if (name === 'validate_component_usage') {
447
+ const markup = typeof args.markup === 'string' ? args.markup : '';
448
+ const issues = [];
449
+ const checkedTags = [];
450
+
451
+ for (const match of markup.matchAll(/<(el-[a-z0-9-]+)([^>]*)>/gi)) {
452
+ const tag = match[1].toLowerCase();
453
+ const attrChunk = match[2] || '';
454
+ checkedTags.push(tag);
455
+ const decl = declByTag.get(tag);
456
+ if (!decl) {
457
+ issues.push({ severity: 'error', tag, message: `Unknown Elementum tag <${tag}> (not in custom-elements.json).` });
458
+ continue;
459
+ }
460
+ const allowed = new Set((decl.attributes || []).map((a) => a.name));
461
+ for (const attrMatch of attrChunk.matchAll(/\s([a-zA-Z_:][a-zA-Z0-9_.:-]*)(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+))?/g)) {
462
+ const attr = attrMatch[1].toLowerCase();
463
+ if (
464
+ allowed.has(attr) ||
465
+ GLOBAL_HTML_ATTRS.has(attr) ||
466
+ attr.startsWith('aria-') ||
467
+ attr.startsWith('data-') ||
468
+ attr.startsWith('on')
469
+ ) {
470
+ continue;
471
+ }
472
+ issues.push({
473
+ severity: 'warning',
474
+ tag,
475
+ attribute: attr,
476
+ message: `Attribute "${attr}" is not declared on <${tag}>. Allowed: ${[...allowed].join(', ') || '(none)'}.`,
477
+ });
478
+ }
479
+ }
480
+
481
+ return {
482
+ valid: issues.filter((i) => i.severity === 'error').length === 0,
483
+ checkedCount: checkedTags.length,
484
+ issues,
485
+ };
486
+ }
487
+
488
+ if (name === 'get_component_maturity') {
489
+ return {
490
+ package: pkg.name,
491
+ version: pkg.version,
492
+ maturity: 'beta',
493
+ componentCount: allDeclarations.length,
494
+ zeroRuntimeDependencies: !pkg.dependencies || Object.keys(pkg.dependencies).length === 0,
495
+ testing: {
496
+ unitRunner: 'node:test + happy-dom',
497
+ browserE2E: 'playwright (Chromium, Firefox, WebKit) + @axe-core/playwright',
498
+ },
499
+ subpathExports: Object.keys(pkg.exports || {}),
500
+ };
501
+ }
502
+
503
+ throw new Error(`Unknown tool: ${name}`);
504
+ }
505
+
506
+ export function handleJsonRpcLine(line) {
507
+ if (typeof line !== 'string' || !line.trim()) return null;
508
+ if (Buffer.byteLength(line, 'utf8') > MAX_PAYLOAD_BYTES) {
509
+ return {
510
+ jsonrpc: '2.0',
511
+ id: null,
512
+ error: { code: -32600, message: `Payload exceeds maximum size of ${MAX_PAYLOAD_BYTES} bytes.` },
513
+ };
514
+ }
515
+
516
+ try {
517
+ const request = JSON.parse(line);
518
+ if (!request || typeof request !== 'object') {
519
+ return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid JSON-RPC request object.' } };
520
+ }
521
+
522
+ if (request.method === 'tools/list') {
523
+ return {
524
+ jsonrpc: '2.0',
525
+ id: request.id ?? null,
526
+ result: { tools: TOOLS },
527
+ };
528
+ }
529
+
530
+ if (request.method === 'tools/call') {
531
+ const params = request.params && typeof request.params === 'object' ? request.params : {};
532
+ const result = handleToolCall(params.name, params.arguments);
533
+ return {
534
+ jsonrpc: '2.0',
535
+ id: request.id ?? null,
536
+ result: {
537
+ content: [
538
+ {
539
+ type: 'text',
540
+ text: JSON.stringify(result, null, 2),
541
+ },
542
+ ],
543
+ },
544
+ };
545
+ }
546
+
547
+ if (request.method === 'initialize') {
548
+ return {
549
+ jsonrpc: '2.0',
550
+ id: request.id ?? null,
551
+ result: {
552
+ protocolVersion: '2024-11-05',
553
+ capabilities: { tools: {} },
554
+ serverInfo: {
555
+ name: 'elementum-design-system-mcp',
556
+ version: pkg.version,
557
+ },
558
+ },
559
+ };
560
+ }
561
+
562
+ return {
563
+ jsonrpc: '2.0',
564
+ id: request.id ?? null,
565
+ error: { code: -32601, message: `Method not found: ${request.method}` },
566
+ };
567
+ } catch (err) {
568
+ return {
569
+ jsonrpc: '2.0',
570
+ id: null,
571
+ error: { code: -32603, message: err.message },
572
+ };
573
+ }
574
+ }
575
+
576
+ // Start JSON-RPC stdio loop only when executed directly as CLI
577
+ const isDirectRun =
578
+ process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
579
+
580
+ if (isDirectRun) {
581
+ const rl = readline.createInterface({
582
+ input: process.stdin,
583
+ output: process.stdout,
584
+ terminal: false,
585
+ });
586
+
587
+ rl.on('line', (line) => {
588
+ const response = handleJsonRpcLine(line);
589
+ if (response) {
590
+ process.stdout.write(JSON.stringify(response) + '\n');
591
+ }
592
+ });
593
+ }
package/package.json CHANGED
@@ -1,6 +1,79 @@
1
1
  {
2
2
  "name": "@wcomp/elementum",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Ultra-lightweight, signal-driven, frameworkless Web Components for modern design systems",
5
+ "type": "module",
6
+ "main": "./src/index.js",
7
+ "types": "./src/index.d.ts",
8
+ "bin": {
9
+ "elementum-mcp": "./mcp/server.js"
10
+ },
11
+ "publishConfig": {
12
+ "access": "public"
13
+ },
14
+ "files": [
15
+ "src",
16
+ "custom-elements.json",
17
+ "tokens",
18
+ "mcp",
19
+ "skills",
20
+ "LICENSE",
21
+ "README.md"
22
+ ],
23
+ "exports": {
24
+ ".": {
25
+ "types": "./src/index.d.ts",
26
+ "default": "./src/index.js"
27
+ },
28
+ "./ssr": "./src/ssr.js",
29
+ "./ag-ui": "./src/ag-ui.js",
30
+ "./behaviors": "./src/behaviors/index.js",
31
+ "./tokens.css": "./src/tokens.css",
32
+ "./custom-elements.json": "./custom-elements.json",
33
+ "./components/*": "./src/components/*.js"
34
+ },
35
+ "homepage": "https://elementum-sage.vercel.app/",
36
+ "repository": {
37
+ "type": "git",
38
+ "url": "git+https://github.com/pinguxx/Elementum.git"
39
+ },
40
+ "bugs": {
41
+ "url": "https://github.com/pinguxx/Elementum/issues"
42
+ },
43
+ "scripts": {
44
+ "test": "node --test --experimental-test-coverage",
45
+ "test:e2e": "playwright test",
46
+ "bench": "node tools/benchmark.js",
47
+ "serve": "node tools/serve.js",
48
+ "serve:proxy": "node tools/serve.js --proxy",
49
+ "ssr": "node examples/ssr-server.js",
50
+ "ssr:static": "node examples/ssr-server.js --static examples/ssr-demo.html",
51
+ "mcp": "node mcp/server.js",
52
+ "create": "node tools/create-component.js",
53
+ "tokens:sync": "node tools/sync-tokens.js",
54
+ "catalog:diff": "node tools/audit-catalog-diff.js",
55
+ "penpot:mcp": "node tools/sync-penpot-mcp.js",
56
+ "penpot:design-app": "node tools/design-ledgerflow-penpot.js",
57
+ "penpot:generate": "node tools/penpot-to-elementum.js"
58
+ },
59
+ "keywords": [
60
+ "web-components",
61
+ "custom-elements",
62
+ "signals",
63
+ "shadow-dom",
64
+ "declarative-shadow-dom",
65
+ "ssr",
66
+ "design-system",
67
+ "figma",
68
+ "penpot",
69
+ "mcp",
70
+ "ai-ui"
71
+ ],
72
+ "author": "wcomp",
73
+ "license": "MIT",
74
+ "devDependencies": {
75
+ "@axe-core/playwright": "^4.14.0",
76
+ "@playwright/test": "^1.65.1",
77
+ "happy-dom": "^21.0.4"
78
+ }
79
+ }
@@ -0,0 +1,11 @@
1
+ # Break-UI Failure Vector Checklist
2
+
3
+ | Vector | What to Try | Expected Resilience |
4
+ | :--- | :--- | :--- |
5
+ | **320px Mobile** | Narrow viewport on navbar, tables, segmented controls, dialogs | Zero horizontal body scroll; navbar collapses cleanly; tables scroll internally. |
6
+ | **Dark Mode Hover** | Hover secondary, ghost, and canvas-toggle buttons in dark mode | High-contrast text and surface tokens remain legible (never white-on-light-gray). |
7
+ | **Long Unbroken Text** | Pass 100-char label into `<el-button>`, `<el-chip>`, `<el-badge>`, `<el-card>` | Graceful truncation or wrapping without breaking sibling alignment. |
8
+ | **Empty / Null Data** | Pass `data="[]"`, `options=""`, or omit slotted children | Renders fallback `label` attribute or `<el-empty-state>` without throwing. |
9
+ | **Keyboard Only** | Operate `<el-command>`, `<el-tabs>`, `<el-dropdown>`, `<el-select>`, `<el-dialog>` with keyboard | Full arrow navigation, Enter/Space activation, Escape close, and focus restoration. |
10
+ | **Form Reset** | Mutate `<el-input>`, `<el-switch>`, `<el-select>`, `<el-slider>` then call `form.reset()` | Restores initial HTML default attributes cleanly via `formReset()`. |
11
+ | **Mount / Unmount Churn** | Append and remove component 20× in a loop | Zero memory/listener leaks (`this.signal` `AbortController` cleans up all listeners). |