@constela/ui 0.2.0

package/components/badge/badge.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Test suite for Badge component
+ *
+ * @constela/ui Badge component tests following TDD methodology.
+ * These tests verify the Badge component structure, params, and styles.
+ *
+ * Coverage:
+ * - Component structure validation
+ * - Params definition validation
+ * - Style preset validation
+ */
+
+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('Badge Component', () => {
+  let ctx: ComponentTestContext;
+
+  beforeAll(() => {
+    ctx = loadComponentForTesting('badge');
+  });
+
+  // ==================== 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 contain a slot for badge content', () => {
+      expect(hasSlot(ctx.component.view)).toBe(true);
+    });
+
+    it('should have className using StyleExpr with preset badgeStyles', () => {
+      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: 'badgeStyles',
+      });
+    });
+  });
+
+  // ==================== Params Validation Tests ====================
+
+  describe('Params Validation', () => {
+    const expectedParams = ['variant'];
+
+    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);
+      });
+    });
+  });
+
+  // ==================== Style Preset Tests ====================
+
+  describe('Style Preset', () => {
+    it('should have valid style preset structure', () => {
+      const badgeStyles = ctx.styles['badgeStyles'];
+      expect(badgeStyles).toBeDefined();
+      assertValidStylePreset(badgeStyles);
+    });
+
+    it('should have base classes for common badge styles', () => {
+      const badgeStyles = ctx.styles['badgeStyles'];
+      expect(badgeStyles.base).toBeDefined();
+      expect(typeof badgeStyles.base).toBe('string');
+      expect(badgeStyles.base.length).toBeGreaterThan(0);
+    });
+
+    describe('variant options', () => {
+      const variantOptions = ['default', 'secondary', 'destructive', 'outline'];
+
+      it('should have variant variants', () => {
+        const badgeStyles = ctx.styles['badgeStyles'];
+        expect(hasVariants(badgeStyles, ['variant'])).toBe(true);
+      });
+
+      it.each(variantOptions)('should have %s variant option', (option) => {
+        const badgeStyles = ctx.styles['badgeStyles'];
+        expect(hasVariantOptions(badgeStyles, 'variant', [option])).toBe(true);
+      });
+    });
+
+    describe('default variants', () => {
+      it('should have default variant set to default', () => {
+        const badgeStyles = ctx.styles['badgeStyles'];
+        expect(hasDefaultVariants(badgeStyles, { variant: 'default' })).toBe(true);
+      });
+    });
+  });
+
+  // ==================== 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/breadcrumb/breadcrumb.constela.json

@@ -0,0 +1,17 @@
+{
+  "params": {
+    "separator": { "type": "string", "required": false, "default": "/" }
+  },
+  "view": {
+    "kind": "element",
+    "tag": "nav",
+    "props": {
+      "aria-label": { "expr": "lit", "value": "Breadcrumb" },
+      "className": {
+        "expr": "style",
+        "preset": "breadcrumbStyles"
+      }
+    },
+    "children": [{ "kind": "slot" }]
+  }
+}

package/components/breadcrumb/breadcrumb.styles.json

@@ -0,0 +1,5 @@
+{
+  "breadcrumbStyles": {
+    "base": "flex flex-wrap items-center gap-1.5 break-words text-sm text-muted-foreground sm:gap-2.5"
+  }
+}

package/components/breadcrumb/breadcrumb.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Test suite for Breadcrumb component
+ *
+ * @constela/ui Breadcrumb component tests following TDD methodology.
+ * These tests verify the Breadcrumb 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,
+  hasSlot,
+  findPropInView,
+  hasAriaAttribute,
+  type ComponentTestContext,
+} from '../../tests/helpers/test-utils.js';
+
+describe('Breadcrumb Component', () => {
+  let ctx: ComponentTestContext;
+
+  beforeAll(() => {
+    ctx = loadComponentForTesting('breadcrumb');
+  });
+
+  // ==================== Component Structure Tests ====================
+
+  describe('Component Structure', () => {
+    it('should have valid component structure', () => {
+      assertValidComponent(ctx.component);
+    });
+
+    it('should have nav as root element', () => {
+      const rootTag = getRootTag(ctx.component);
+      expect(rootTag).toBe('nav');
+    });
+
+    it('should have aria-label="Breadcrumb" attribute', () => {
+      const ariaLabel = findPropInView(ctx.component.view, 'aria-label');
+      expect(ariaLabel).not.toBeNull();
+      expect(ariaLabel).toMatchObject({
+        expr: 'lit',
+        value: 'Breadcrumb',
+      });
+    });
+
+    it('should contain a slot for breadcrumb items', () => {
+      expect(hasSlot(ctx.component.view)).toBe(true);
+    });
+
+    it('should have className using StyleExpr with preset breadcrumbStyles', () => {
+      const className = findPropInView(ctx.component.view, 'className');
+      expect(className).not.toBeNull();
+      expect(className).toMatchObject({
+        expr: 'style',
+        preset: 'breadcrumbStyles',
+      });
+    });
+  });
+
+  // ==================== Params Validation Tests ====================
+
+  describe('Params Validation', () => {
+    const expectedParams = ['separator'];
+
+    it('should have all expected params', () => {
+      expect(hasParams(ctx.component, expectedParams)).toBe(true);
+    });
+
+    describe('param: separator', () => {
+      it('should be optional', () => {
+        expect(isOptionalParam(ctx.component, 'separator')).toBe(true);
+      });
+
+      it('should have type string', () => {
+        expect(hasParamType(ctx.component, 'separator', 'string')).toBe(true);
+      });
+
+      it('should have default value of "/"', () => {
+        const separatorParam = ctx.component.params?.['separator'];
+        expect(separatorParam).toBeDefined();
+        expect(separatorParam?.default).toBe('/');
+      });
+    });
+  });
+
+  // ==================== Style Preset Tests ====================
+
+  describe('Style Preset', () => {
+    it('should have valid style preset structure', () => {
+      const breadcrumbStyles = ctx.styles['breadcrumbStyles'];
+      expect(breadcrumbStyles).toBeDefined();
+      assertValidStylePreset(breadcrumbStyles);
+    });
+
+    it('should have base classes for common breadcrumb styles', () => {
+      const breadcrumbStyles = ctx.styles['breadcrumbStyles'];
+      expect(breadcrumbStyles.base).toBeDefined();
+      expect(typeof breadcrumbStyles.base).toBe('string');
+      expect(breadcrumbStyles.base.length).toBeGreaterThan(0);
+    });
+
+    it('should include flex layout classes in base', () => {
+      const breadcrumbStyles = ctx.styles['breadcrumbStyles'];
+      expect(breadcrumbStyles.base).toMatch(/flex/);
+    });
+
+    it('should include items-center class in base', () => {
+      const breadcrumbStyles = ctx.styles['breadcrumbStyles'];
+      expect(breadcrumbStyles.base).toMatch(/items-center/);
+    });
+
+    it('should include gap class in base', () => {
+      const breadcrumbStyles = ctx.styles['breadcrumbStyles'];
+      expect(breadcrumbStyles.base).toMatch(/gap/);
+    });
+  });
+
+  // ==================== Accessibility Tests ====================
+
+  describe('Accessibility', () => {
+    it('should have aria-label attribute for screen readers', () => {
+      expect(hasAriaAttribute(ctx.component.view, 'aria-label')).toBe(true);
+    });
+
+    it('should have aria-label value of "Breadcrumb"', () => {
+      const ariaLabel = findPropInView(ctx.component.view, 'aria-label');
+      expect(ariaLabel).toMatchObject({
+        expr: 'lit',
+        value: 'Breadcrumb',
+      });
+    });
+
+    it('should use nav element for semantic navigation', () => {
+      const rootTag = getRootTag(ctx.component);
+      expect(rootTag).toBe('nav');
+    });
+  });
+});

package/components/button/README.md

@@ -0,0 +1,164 @@
+# Button
+
+A customizable button component with multiple variants and sizes.
+
+## Usage
+
+Copy `button.constela.json` and `button.styles.json` to your project's components directory.
+
+### Basic Usage
+
+```json
+{
+  "kind": "component",
+  "name": "Button",
+  "children": [
+    { "kind": "text", "value": { "expr": "lit", "value": "Click me" } }
+  ]
+}
+```
+
+### With Variants
+
+```json
+{
+  "kind": "component",
+  "name": "Button",
+  "props": {
+    "variant": { "expr": "lit", "value": "destructive" }
+  },
+  "children": [
+    { "kind": "text", "value": { "expr": "lit", "value": "Delete" } }
+  ]
+}
+```
+
+### With Size
+
+```json
+{
+  "kind": "component",
+  "name": "Button",
+  "props": {
+    "size": { "expr": "lit", "value": "lg" }
+  },
+  "children": [
+    { "kind": "text", "value": { "expr": "lit", "value": "Large Button" } }
+  ]
+}
+```
+
+### Disabled State
+
+```json
+{
+  "kind": "component",
+  "name": "Button",
+  "props": {
+    "disabled": { "expr": "lit", "value": true }
+  },
+  "children": [
+    { "kind": "text", "value": { "expr": "lit", "value": "Disabled" } }
+  ]
+}
+```
+
+### With ARIA Label
+
+```json
+{
+  "kind": "component",
+  "name": "Button",
+  "props": {
+    "ariaLabel": { "expr": "lit", "value": "Close dialog" },
+    "variant": { "expr": "lit", "value": "ghost" },
+    "size": { "expr": "lit", "value": "icon" }
+  },
+  "children": [
+    { "kind": "text", "value": { "expr": "lit", "value": "X" } }
+  ]
+}
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `variant` | string | No | `"default"` | Button style variant |
+| `size` | string | No | `"default"` | Button size |
+| `disabled` | boolean | No | `false` | Whether the button is disabled |
+| `type` | string | No | - | HTML button type attribute (browser default: `"submit"`) |
+| `ariaLabel` | string | No | - | ARIA label for accessibility |
+
+## Variants
+
+| Variant | Description |
+|---------|-------------|
+| `default` | Primary button style with solid background |
+| `destructive` | Red/danger button for destructive actions |
+| `outline` | Button with border and transparent background |
+| `secondary` | Secondary button with muted background |
+| `ghost` | Minimal button with no background until hover |
+| `link` | Text-only button styled as a link |
+
+## Sizes
+
+| Size | Description |
+|------|-------------|
+| `default` | Standard button size (h-10) |
+| `sm` | Small button (h-9) |
+| `lg` | Large button (h-11) |
+| `icon` | Square icon button (h-10 w-10) |
+
+## Accessibility
+
+- Uses semantic `<button>` element
+- Supports `aria-label` for screen readers
+- Disabled state is properly communicated via `disabled` attribute
+- Focus ring visible on keyboard navigation
+- Disabled buttons have reduced opacity
+
+## Customization
+
+### Modifying Styles
+
+Edit `button.styles.json` to customize the appearance:
+
+```json
+{
+  "buttonStyles": {
+    "base": "your-base-classes",
+    "variants": {
+      "variant": {
+        "custom": "your-custom-variant-classes"
+      }
+    }
+  }
+}
+```
+
+### Adding New Variants
+
+1. Add the variant to `button.styles.json`:
+
+```json
+{
+  "variants": {
+    "variant": {
+      "success": "bg-green-500 text-white hover:bg-green-600"
+    }
+  }
+}
+```
+
+2. Use it in your component:
+
+```json
+{
+  "kind": "component",
+  "name": "Button",
+  "props": {
+    "variant": { "expr": "lit", "value": "success" }
+  }
+}
+```

package/components/button/button.constela.json

@@ -0,0 +1,27 @@
+{
+  "params": {
+    "variant": { "type": "string", "required": false },
+    "size": { "type": "string", "required": false },
+    "disabled": { "type": "boolean", "required": false },
+    "type": { "type": "string", "required": false },
+    "ariaLabel": { "type": "string", "required": false }
+  },
+  "view": {
+    "kind": "element",
+    "tag": "button",
+    "props": {
+      "className": {
+        "expr": "style",
+        "preset": "buttonStyles",
+        "props": {
+          "variant": { "expr": "param", "name": "variant" },
+          "size": { "expr": "param", "name": "size" }
+        }
+      },
+      "disabled": { "expr": "param", "name": "disabled" },
+      "type": { "expr": "param", "name": "type" },
+      "aria-label": { "expr": "param", "name": "ariaLabel" }
+    },
+    "children": [{ "kind": "slot" }]
+  }
+}

package/components/button/button.styles.json

@@ -0,0 +1,25 @@
+{
+  "buttonStyles": {
+    "base": "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-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"
+    }
+  }
+}