@constela/ui 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Constela Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# @constela/ui
+
+Copy-paste UI components for Constela - a shadcn/ui style component library.
+
+## Overview
+
+This package provides a collection of pre-built, accessible UI components written in Constela JSON DSL. Each component is designed to be copied directly into your project and customized as needed.
+
+## Installation
+
+```bash
+npm install @constela/ui
+```
+
+## Usage
+
+### Copy Component Files
+
+Components are located in the `components/` directory. Copy the component files you need into your project:
+
+```
+components/
+├── button/
+│   ├── button.constela.json      # Component definition
+│   ├── button.styles.json        # Style presets
+│   └── README.md                 # Usage documentation
+├── input/
+├── select/
+└── ...
+```
+
+### Example: Using Button Component
+
+1. Copy `components/button/button.constela.json` to your project
+2. Import styles from `components/button/button.styles.json`
+3. Use the component in your Constela program:
+
+```json
+{
+  "kind": "component",
+  "name": "Button",
+  "props": {
+    "variant": { "expr": "lit", "value": "default" },
+    "size": { "expr": "lit", "value": "default" }
+  },
+  "children": [
+    { "kind": "text", "value": { "expr": "lit", "value": "Click me" } }
+  ]
+}
+```
+
+## Available Components
+
+### Basic (7)
+- **Button** - Clickable button with variants and sizes
+- **Input** - Text input field
+- **Select** - Dropdown select
+- **Checkbox** - Checkbox input
+- **Radio** - Radio button
+- **Switch** - Toggle switch
+- **Textarea** - Multi-line text input
+
+### Feedback (6)
+- **Alert** - Alert messages
+- **Toast** - Toast notifications
+- **Dialog** - Modal dialog
+- **Modal** - Modal overlay
+- **Tooltip** - Hover tooltip
+- **Popover** - Click-triggered popover
+
+### Data Display (5)
+- **Table** - Data table
+- **Card** - Card container
+- **Badge** - Inline badge
+- **Avatar** - User avatar
+- **Skeleton** - Loading placeholder
+
+### Navigation (3)
+- **Tabs** - Tab navigation
+- **Breadcrumb** - Breadcrumb navigation
+- **Pagination** - Page pagination
+
+### Layout (3)
+- **Container** - Max-width container
+- **Grid** - CSS Grid layout
+- **Stack** - Flexbox stack
+
+## Style System
+
+Each component uses the CVA-like style system with:
+
+- **base** - Common styles applied to all variants
+- **variants** - Named variant options (e.g., "variant", "size")
+- **defaultVariants** - Default values when not specified
+
+### Example Style Preset
+
+```json
+{
+  "button": {
+    "base": "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
+    "variants": {
+      "variant": {
+        "default": "bg-primary text-primary-foreground hover:bg-primary/90",
+        "destructive": "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        "outline": "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        "secondary": "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        "ghost": "hover:bg-accent hover:text-accent-foreground",
+        "link": "text-primary underline-offset-4 hover:underline"
+      },
+      "size": {
+        "default": "h-10 px-4 py-2",
+        "sm": "h-9 rounded-md px-3",
+        "lg": "h-11 rounded-md px-8",
+        "icon": "h-10 w-10"
+      }
+    },
+    "defaultVariants": {
+      "variant": "default",
+      "size": "default"
+    }
+  }
+}
+```
+
+## Accessibility
+
+All components include proper ARIA attributes:
+
+- `aria-label` - Descriptive labels
+- `aria-disabled` - Disabled state indication
+- `role` - Semantic roles for interactive elements
+- `aria-live` - Live region announcements
+
+## API Reference
+
+### validateComponent
+
+Validate a Constela component definition:
+
+```typescript
+import { validateComponent } from '@constela/ui';
+
+const result = validateComponent(componentJson);
+if (result.valid) {
+  console.log('Component is valid');
+} else {
+  console.error('Validation errors:', result.errors);
+}
+```
+
+### Component Types
+
+```typescript
+import type { ButtonComponent, InputComponent } from '@constela/ui';
+```
+
+## License
+
+MIT

package/components/alert/alert.constela.json

@@ -0,0 +1,22 @@
+{
+  "params": {
+    "variant": { "type": "string", "required": false },
+    "title": { "type": "string", "required": false }
+  },
+  "view": {
+    "kind": "element",
+    "tag": "div",
+    "props": {
+      "role": { "expr": "lit", "value": "alert" },
+      "aria-live": { "expr": "lit", "value": "assertive" },
+      "className": {
+        "expr": "style",
+        "preset": "alertStyles",
+        "props": {
+          "variant": { "expr": "param", "name": "variant" }
+        }
+      }
+    },
+    "children": [{ "kind": "slot" }]
+  }
+}

package/components/alert/alert.styles.json

@@ -0,0 +1,14 @@
+{
+  "alertStyles": {
+    "base": "relative w-full rounded-lg border p-4 [&>svg~*]:pl-7 [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground",
+    "variants": {
+      "variant": {
+        "default": "bg-background text-foreground",
+        "destructive": "border-destructive/50 text-destructive dark:border-destructive [&>svg]:text-destructive"
+      }
+    },
+    "defaultVariants": {
+      "variant": "default"
+    }
+  }
+}

package/components/alert/alert.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Test suite for Alert component
+ *
+ * @constela/ui Alert component tests following TDD methodology.
+ * These tests verify the Alert component structure, params, styles, and accessibility.
+ *
+ * Coverage:
+ * - Component structure validation
+ * - Params definition validation
+ * - Style preset validation
+ * - Accessibility attributes
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  loadComponentForTesting,
+  assertValidComponent,
+  assertValidStylePreset,
+  hasParams,
+  isOptionalParam,
+  hasParamType,
+  getRootTag,
+  hasVariants,
+  hasVariantOptions,
+  hasDefaultVariants,
+  hasSlot,
+  findPropInView,
+  hasRole,
+  type ComponentTestContext,
+} from '../../tests/helpers/test-utils.js';
+
+describe('Alert Component', () => {
+  let ctx: ComponentTestContext;
+
+  beforeAll(() => {
+    ctx = loadComponentForTesting('alert');
+  });
+
+  // ==================== Component Structure Tests ====================
+
+  describe('Component Structure', () => {
+    it('should have valid component structure', () => {
+      assertValidComponent(ctx.component);
+    });
+
+    it('should have div as root element', () => {
+      const rootTag = getRootTag(ctx.component);
+      expect(rootTag).toBe('div');
+    });
+
+    it('should have role="alert" attribute', () => {
+      expect(hasRole(ctx.component.view, 'alert')).toBe(true);
+    });
+
+    it('should contain a slot for alert content', () => {
+      expect(hasSlot(ctx.component.view)).toBe(true);
+    });
+
+    it('should have className using StyleExpr', () => {
+      const className = findPropInView(ctx.component.view, 'className');
+      expect(className).not.toBeNull();
+      // StyleExpr should have expr: 'style' and preset reference
+      expect(className).toMatchObject({
+        expr: 'style',
+        preset: 'alertStyles',
+      });
+    });
+  });
+
+  // ==================== Params Validation Tests ====================
+
+  describe('Params Validation', () => {
+    const expectedParams = ['variant', 'title'];
+
+    it('should have all expected params', () => {
+      expect(hasParams(ctx.component, expectedParams)).toBe(true);
+    });
+
+    describe('param: variant', () => {
+      it('should be optional', () => {
+        expect(isOptionalParam(ctx.component, 'variant')).toBe(true);
+      });
+
+      it('should have type string', () => {
+        expect(hasParamType(ctx.component, 'variant', 'string')).toBe(true);
+      });
+    });
+
+    describe('param: title', () => {
+      it('should be optional', () => {
+        expect(isOptionalParam(ctx.component, 'title')).toBe(true);
+      });
+
+      it('should have type string', () => {
+        expect(hasParamType(ctx.component, 'title', 'string')).toBe(true);
+      });
+    });
+  });
+
+  // ==================== Style Preset Tests ====================
+
+  describe('Style Preset', () => {
+    it('should have valid style preset structure', () => {
+      const alertStyles = ctx.styles['alertStyles'];
+      expect(alertStyles).toBeDefined();
+      assertValidStylePreset(alertStyles);
+    });
+
+    it('should have base classes', () => {
+      const alertStyles = ctx.styles['alertStyles'];
+      expect(alertStyles.base).toBeDefined();
+      expect(typeof alertStyles.base).toBe('string');
+      expect(alertStyles.base.length).toBeGreaterThan(0);
+    });
+
+    describe('variant options', () => {
+      const variantOptions = ['default', 'destructive'];
+
+      it('should have variant variants', () => {
+        const alertStyles = ctx.styles['alertStyles'];
+        expect(hasVariants(alertStyles, ['variant'])).toBe(true);
+      });
+
+      it.each(variantOptions)('should have %s variant option', (option) => {
+        const alertStyles = ctx.styles['alertStyles'];
+        expect(hasVariantOptions(alertStyles, 'variant', [option])).toBe(true);
+      });
+    });
+
+    describe('default variants', () => {
+      it('should have default variant set to default', () => {
+        const alertStyles = ctx.styles['alertStyles'];
+        expect(hasDefaultVariants(alertStyles, { variant: 'default' })).toBe(true);
+      });
+    });
+  });
+
+  // ==================== Accessibility Tests ====================
+
+  describe('Accessibility', () => {
+    it('should have role="alert" for screen readers', () => {
+      const role = findPropInView(ctx.component.view, 'role');
+      expect(role).not.toBeNull();
+      expect(role).toMatchObject({
+        expr: 'lit',
+        value: 'alert',
+      });
+    });
+
+    it('should have aria-live="assertive" for important alerts', () => {
+      const ariaLive = findPropInView(ctx.component.view, 'aria-live');
+      expect(ariaLive).not.toBeNull();
+      expect(ariaLive).toMatchObject({
+        expr: 'lit',
+        value: 'assertive',
+      });
+    });
+  });
+
+  // ==================== View Props Tests ====================
+
+  describe('View Props', () => {
+    it('should pass variant to StyleExpr', () => {
+      const className = findPropInView(ctx.component.view, 'className');
+      expect(className).toMatchObject({
+        expr: 'style',
+        props: expect.objectContaining({
+          variant: expect.objectContaining({ expr: 'param', name: 'variant' }),
+        }),
+      });
+    });
+  });
+});

package/components/avatar/avatar.constela.json

@@ -0,0 +1,32 @@
+{
+  "params": {
+    "src": { "type": "string", "required": false },
+    "alt": { "type": "string", "required": false },
+    "fallback": { "type": "string", "required": false },
+    "size": { "type": "string", "required": false }
+  },
+  "view": {
+    "kind": "element",
+    "tag": "div",
+    "props": {
+      "className": {
+        "expr": "style",
+        "preset": "avatarStyles",
+        "props": {
+          "size": { "expr": "param", "name": "size" }
+        }
+      }
+    },
+    "children": [
+      {
+        "kind": "element",
+        "tag": "img",
+        "props": {
+          "src": { "expr": "param", "name": "src" },
+          "alt": { "expr": "param", "name": "alt" },
+          "className": { "expr": "lit", "value": "aspect-square h-full w-full" }
+        }
+      }
+    ]
+  }
+}

package/components/avatar/avatar.styles.json

@@ -0,0 +1,15 @@
+{
+  "avatarStyles": {
+    "base": "relative flex shrink-0 overflow-hidden rounded-full",
+    "variants": {
+      "size": {
+        "default": "h-10 w-10",
+        "sm": "h-8 w-8",
+        "lg": "h-14 w-14"
+      }
+    },
+    "defaultVariants": {
+      "size": "default"
+    }
+  }
+}

package/components/avatar/avatar.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Test suite for Avatar component
+ *
+ * @constela/ui Avatar component tests following TDD methodology.
+ * These tests verify the Avatar component structure, params, styles, and accessibility.
+ *
+ * Coverage:
+ * - Component structure validation
+ * - Params definition validation
+ * - Style preset validation
+ * - Accessibility attributes (alt for image)
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  loadComponentForTesting,
+  assertValidComponent,
+  assertValidStylePreset,
+  hasParams,
+  isOptionalParam,
+  hasParamType,
+  getRootTag,
+  hasVariants,
+  hasVariantOptions,
+  hasDefaultVariants,
+  hasSlot,
+  findPropInView,
+  type ComponentTestContext,
+} from '../../tests/helpers/test-utils.js';
+
+describe('Avatar Component', () => {
+  let ctx: ComponentTestContext;
+
+  beforeAll(() => {
+    ctx = loadComponentForTesting('avatar');
+  });
+
+  // ==================== Component Structure Tests ====================
+
+  describe('Component Structure', () => {
+    it('should have valid component structure', () => {
+      assertValidComponent(ctx.component);
+    });
+
+    it('should have div as root element (container)', () => {
+      const rootTag = getRootTag(ctx.component);
+      expect(rootTag).toBe('div');
+    });
+
+    it('should NOT contain a slot (avatar displays image or fallback)', () => {
+      expect(hasSlot(ctx.component.view)).toBe(false);
+    });
+
+    it('should have className using StyleExpr with avatarStyles preset', () => {
+      const className = findPropInView(ctx.component.view, 'className');
+      expect(className).not.toBeNull();
+      // StyleExpr should have expr: 'style' and preset reference
+      expect(className).toMatchObject({
+        expr: 'style',
+        preset: 'avatarStyles',
+      });
+    });
+  });
+
+  // ==================== Params Validation Tests ====================
+
+  describe('Params Validation', () => {
+    const expectedParams = ['src', 'alt', 'fallback', 'size'];
+
+    it('should have all expected params', () => {
+      expect(hasParams(ctx.component, expectedParams)).toBe(true);
+    });
+
+    describe('param: src', () => {
+      it('should be optional', () => {
+        expect(isOptionalParam(ctx.component, 'src')).toBe(true);
+      });
+
+      it('should have type string', () => {
+        expect(hasParamType(ctx.component, 'src', 'string')).toBe(true);
+      });
+    });
+
+    describe('param: alt', () => {
+      it('should be optional', () => {
+        expect(isOptionalParam(ctx.component, 'alt')).toBe(true);
+      });
+
+      it('should have type string', () => {
+        expect(hasParamType(ctx.component, 'alt', 'string')).toBe(true);
+      });
+    });
+
+    describe('param: fallback', () => {
+      it('should be optional', () => {
+        expect(isOptionalParam(ctx.component, 'fallback')).toBe(true);
+      });
+
+      it('should have type string', () => {
+        expect(hasParamType(ctx.component, 'fallback', 'string')).toBe(true);
+      });
+    });
+
+    describe('param: size', () => {
+      it('should be optional', () => {
+        expect(isOptionalParam(ctx.component, 'size')).toBe(true);
+      });
+
+      it('should have type string', () => {
+        expect(hasParamType(ctx.component, 'size', 'string')).toBe(true);
+      });
+    });
+  });
+
+  // ==================== Style Preset Tests ====================
+
+  describe('Style Preset', () => {
+    it('should have valid style preset structure', () => {
+      const avatarStyles = ctx.styles['avatarStyles'];
+      expect(avatarStyles).toBeDefined();
+      assertValidStylePreset(avatarStyles);
+    });
+
+    it('should have base classes', () => {
+      const avatarStyles = ctx.styles['avatarStyles'];
+      expect(avatarStyles.base).toBeDefined();
+      expect(typeof avatarStyles.base).toBe('string');
+      expect(avatarStyles.base.length).toBeGreaterThan(0);
+    });
+
+    it('should include avatar-specific base classes', () => {
+      const avatarStyles = ctx.styles['avatarStyles'];
+      // Avatar should have relative, rounded-full, overflow-hidden
+      expect(avatarStyles.base).toContain('relative');
+      expect(avatarStyles.base).toContain('rounded-full');
+      expect(avatarStyles.base).toContain('overflow-hidden');
+    });
+
+    describe('size options', () => {
+      const sizeOptions = ['default', 'sm', 'lg'];
+
+      it('should have size variants', () => {
+        const avatarStyles = ctx.styles['avatarStyles'];
+        expect(hasVariants(avatarStyles, ['size'])).toBe(true);
+      });
+
+      it.each(sizeOptions)('should have %s size option', (option) => {
+        const avatarStyles = ctx.styles['avatarStyles'];
+        expect(hasVariantOptions(avatarStyles, 'size', [option])).toBe(true);
+      });
+    });
+
+    describe('default variants', () => {
+      it('should have default size set to default', () => {
+        const avatarStyles = ctx.styles['avatarStyles'];
+        expect(hasDefaultVariants(avatarStyles, { size: 'default' })).toBe(true);
+      });
+    });
+  });
+
+  // ==================== Accessibility Tests ====================
+
+  describe('Accessibility', () => {
+    it('should support alt attribute for image', () => {
+      const alt = findPropInView(ctx.component.view, 'alt');
+      expect(alt).not.toBeNull();
+      // Should reference the alt param
+      expect(alt).toMatchObject({
+        expr: 'param',
+        name: 'alt',
+      });
+    });
+  });
+
+  // ==================== View Props Tests ====================
+
+  describe('View Props', () => {
+    it('should pass size to StyleExpr', () => {
+      const className = findPropInView(ctx.component.view, 'className');
+      expect(className).toMatchObject({
+        expr: 'style',
+        props: expect.objectContaining({
+          size: expect.objectContaining({ expr: 'param', name: 'size' }),
+        }),
+      });
+    });
+
+    it('should pass src to image element', () => {
+      const src = findPropInView(ctx.component.view, 'src');
+      expect(src).not.toBeNull();
+      expect(src).toMatchObject({
+        expr: 'param',
+        name: 'src',
+      });
+    });
+  });
+});

package/components/badge/badge.constela.json

@@ -0,0 +1,19 @@
+{
+  "params": {
+    "variant": { "type": "string", "required": false }
+  },
+  "view": {
+    "kind": "element",
+    "tag": "div",
+    "props": {
+      "className": {
+        "expr": "style",
+        "preset": "badgeStyles",
+        "props": {
+          "variant": { "expr": "param", "name": "variant" }
+        }
+      }
+    },
+    "children": [{ "kind": "slot" }]
+  }
+}

package/components/badge/badge.styles.json

@@ -0,0 +1,16 @@
+{
+  "badgeStyles": {
+    "base": "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2",
+    "variants": {
+      "variant": {
+        "default": "border-transparent bg-primary text-primary-foreground hover:bg-primary/80",
+        "secondary": "border-transparent bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        "destructive": "border-transparent bg-destructive text-destructive-foreground hover:bg-destructive/80",
+        "outline": "text-foreground"
+      }
+    },
+    "defaultVariants": {
+      "variant": "default"
+    }
+  }
+}