Examples

Usage patterns and examples for @constela/ai

Build-time Component Generation

Generate a component at build time using the data section:

json

{
  "version": "1.0",
  "data": {
    "badge": {
      "type": "ai",
      "provider": "anthropic",
      "prompt": "A notification badge that shows a count",
      "output": "component"
    }
  },
  "view": {
    "kind": "component",
    "name": "badge",
    "props": {
      "count": { "expr": "lit", "value": 5 }
    }
  }
}

The AI generates a component like:

json

{
  "kind": "element",
  "tag": "span",
  "props": {
    "className": { "expr": "lit", "value": "badge" }
  },
  "children": [
    { "kind": "text", "value": { "expr": "param", "name": "count" } }
  ]
}

Build-time Page Generation

Generate a complete page with state and actions:

json

{
  "version": "1.0",
  "data": {
    "profilePage": {
      "type": "ai",
      "provider": "anthropic",
      "prompt": "A user profile page with avatar, name, bio, and edit button",
      "output": "view"
    }
  },
  "view": {
    "kind": "component",
    "name": "profilePage",
    "props": {}
  }
}

Features Grid

Generate a features section:

json

{
  "version": "1.0",
  "data": {
    "features": {
      "type": "ai",
      "provider": "anthropic",
      "prompt": "Create a features grid with 3 items: Fast, Secure, Scalable",
      "output": "component"
    }
  },
  "view": {
    "kind": "element",
    "tag": "section",
    "children": [
      {
        "kind": "element",
        "tag": "h2",
        "children": [
          { "kind": "text", "value": { "expr": "lit", "value": "Features" } }
        ]
      },
      {
        "kind": "component",
        "name": "features",
        "props": {}
      }
    ]
  }
}

Runtime Generation

Generate DSL in response to user input using the generate action step:

json

{
  "version": "1.0",
  "state": {
    "userPrompt": { "type": "string", "initial": "" },
    "generatedComponent": { "type": "object", "initial": {} },
    "isLoading": { "type": "boolean", "initial": false },
    "error": { "type": "string", "initial": "" }
  },
  "actions": [
    {
      "name": "updatePrompt",
      "steps": [
        {
          "do": "set",
          "target": "userPrompt",
          "value": { "expr": "param", "name": "event", "path": "target.value" }
        }
      ]
    },
    {
      "name": "generateComponent",
      "steps": [
        {
          "do": "set",
          "target": "isLoading",
          "value": { "expr": "lit", "value": true }
        },
        {
          "do": "set",
          "target": "error",
          "value": { "expr": "lit", "value": "" }
        },
        {
          "do": "generate",
          "provider": "anthropic",
          "prompt": { "expr": "state", "name": "userPrompt" },
          "output": "component",
          "result": "generatedComponent",
          "onSuccess": [
            {
              "do": "set",
              "target": "isLoading",
              "value": { "expr": "lit", "value": false }
            }
          ],
          "onError": [
            {
              "do": "set",
              "target": "isLoading",
              "value": { "expr": "lit", "value": false }
            },
            {
              "do": "set",
              "target": "error",
              "value": { "expr": "param", "name": "error", "path": "message" }
            }
          ]
        }
      ]
    }
  ],
  "view": {
    "kind": "element",
    "tag": "div",
    "children": [
      {
        "kind": "element",
        "tag": "textarea",
        "props": {
          "value": { "expr": "state", "name": "userPrompt" },
          "onInput": { "event": "input", "action": "updatePrompt" },
          "placeholder": { "expr": "lit", "value": "Describe your component..." }
        }
      },
      {
        "kind": "element",
        "tag": "button",
        "props": {
          "onClick": { "event": "click", "action": "generateComponent" },
          "disabled": { "expr": "state", "name": "isLoading" }
        },
        "children": [
          {
            "kind": "text",
            "value": {
              "expr": "cond",
              "if": { "expr": "state", "name": "isLoading" },
              "then": { "expr": "lit", "value": "Generating..." },
              "else": { "expr": "lit", "value": "Generate" }
            }
          }
        ]
      },
      {
        "kind": "if",
        "condition": { "expr": "state", "name": "error" },
        "then": {
          "kind": "element",
          "tag": "p",
          "props": {
            "className": { "expr": "lit", "value": "error" }
          },
          "children": [
            { "kind": "text", "value": { "expr": "state", "name": "error" } }
          ]
        }
      }
    ]
  }
}

Error Handling in DSL

Handle generation errors using onError:

json

{
  "name": "generateWithErrorHandling",
  "steps": [
    {
      "do": "generate",
      "provider": "anthropic",
      "prompt": { "expr": "state", "name": "userPrompt" },
      "output": "component",
      "result": "generatedComponent",
      "onSuccess": [
        { "do": "set", "target": "success", "value": { "expr": "lit", "value": true } }
      ],
      "onError": [
        { "do": "set", "target": "errorMessage", "value": { "expr": "param", "name": "error", "path": "message" } },
        { "do": "set", "target": "errorCode", "value": { "expr": "param", "name": "error", "path": "code" } }
      ]
    }
  ]
}

Error codes:

PROVIDER_NOT_CONFIGURED - API key not set
RATE_LIMIT_EXCEEDED - API rate limit hit
API_ERROR - Provider API call failed
VALIDATION_ERROR - Generated DSL failed security validation

CLI Analysis

Use the CLI to analyze existing DSL files:

bash

# Analyze for accessibility issues
constela suggest app.json --aspect accessibility

# Analyze for security
constela suggest app.json --aspect security

# Analyze for performance
constela suggest app.json --aspect performance

# Analyze for UX
constela suggest app.json --aspect ux

# Use OpenAI instead of Anthropic
constela suggest app.json --aspect accessibility --provider openai

# JSON output for tooling
constela suggest app.json --aspect accessibility --json