> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Components Overview

> Components are the fundamental building blocks of Metabind, defining reusable UI elements

# Components

Components are the fundamental building blocks of Metabind, defining reusable elements that can be used to create and render content across multiple platforms. Components can be **view components** that define reusable UI elements or **layout components** that define the structure for entire content types.

## Component Types

<CardGroup cols={2}>
  <Card title="View Components" icon="eye">
    Standard UI components for displaying content. Examples: `ProductCard`, `ArticleParagraph`, `HeroImage`
  </Card>

  <Card title="Layout Components" icon="table-columns">
    Define structure for entire content types. Examples: `ArticleLayout`, `ProductPageLayout`
  </Card>
</CardGroup>

## Key Concepts

| Concept               | Description                                                   |
| --------------------- | ------------------------------------------------------------- |
| **Collections**       | Organizational groups for components in the CMS UI            |
| **Status Management** | Components maintain draft and published status                |
| **Version Control**   | Versions are created when components are included in packages |
| **Asset Binding**     | Components can have bound assets included in packages         |
| **Schema Generation** | JSON Schema auto-generated from `properties()` function       |

## Component Object

### Fields

| Field                      | Type      | Description                                             |
| -------------------------- | --------- | ------------------------------------------------------- |
| `id`                       | string    | Unique identifier (UUID)                                |
| `name`                     | string    | Display name (unique within project)                    |
| `title`                    | string    | Display title extracted from `metadata()` function      |
| `description`              | string    | Markdown description from `metadata()` function         |
| `collectionId`             | string    | Parent collection ID (null for root collection)         |
| `version`                  | number    | Version number (set when published in a package)        |
| `lastPublishedVersion`     | number    | Last published version (null if never published)        |
| `type`                     | string    | Component type (`view` or `layout`)                     |
| `status`                   | string    | Status (`draft`, `modified`, `published`, or `deleted`) |
| `content`                  | string    | Component source code (TypeScript)                      |
| `compiled`                 | string    | Auto-generated JavaScript (read-only)                   |
| `schema`                   | object    | JSON Schema from `properties()` function                |
| `metadata`                 | object    | Additional metadata                                     |
| `metadata.author`          | string    | Creator of the component                                |
| `metadata.tags`            | string\[] | Component tags                                          |
| `metadata.packageVersions` | string\[] | Package versions containing this component              |
| `createdAt`                | string    | Creation timestamp (ISO format)                         |
| `updatedAt`                | string    | Last update timestamp (ISO format)                      |

### Example View Component

```json theme={null}
{
  "id": "c123",
  "name": "ProductCard",
  "title": "Product Card",
  "description": "Product display card with image, title, and pricing.",
  "collectionId": "coll123",
  "version": null,
  "lastPublishedVersion": null,
  "type": "view",
  "status": "draft",
  "content": "const metadata = () => ({ title: 'Product Card' });\nconst properties = () => ({ title: PropertyString({...}) });\nconst body = (props: ComponentProps) => { return VStack([...]) };",
  "compiled": "const metadata = () => ({ title: 'Product Card' });\nconst properties = () => ({ title: PropertyString({...}) });\nconst body = (props) => { return VStack([...]) };",
  "schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string", "description": "Product name" },
      "price": { "type": "number", "minimum": 0 }
    },
    "required": ["title", "price"]
  },
  "metadata": {
    "author": "jane.doe@metabind.ai",
    "tags": ["product", "card"]
  },
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z"
}
```

### Example Layout Component

```json theme={null}
{
  "id": "c124",
  "name": "ArticleLayout",
  "title": "Article Layout",
  "description": "Standard article layout with header, body, and metadata.",
  "collectionId": "coll123",
  "version": 2,
  "lastPublishedVersion": 2,
  "type": "layout",
  "status": "published",
  "content": "const body = (props: ComponentProps, children: Component[]) => { return VStack([Header(props), ...children]) };",
  "schema": {
    "type": "object",
    "properties": {
      "heroImage": { "type": "string", "format": "uri" },
      "author": { "type": "string" }
    }
  },
  "metadata": {
    "author": "jane.doe@metabind.ai",
    "tags": ["layout", "article"],
    "packageVersions": ["1.0.0", "1.1.0", "2.0.0"]
  },
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z"
}
```

## TypeScript and Compilation

When a component is saved, the TypeScript code in the `content` field is automatically compiled to JavaScript and stored in the `compiled` field.

```typescript theme={null}
// TypeScript source (content field)
const body = (props: ComponentProps, children: Component[]) => {
  return VStack({ spacing: 12 }, [
    Text(props.title).font('headline'),
    props.description ? Text(props.description) : null
  ]);
};

// Compiled JavaScript (compiled field - read-only)
const body = (props, children) => {
  return VStack({ spacing: 12 }, [
    Text(props.title).font('headline'),
    props.description ? Text(props.description) : null
  ]);
};
```

## Schema Generation

Components with a `properties()` function automatically have their schema extracted:

```javascript theme={null}
// Component properties definition
const properties = () => ({
  title: PropertyString({
    title: 'Title',
    description: 'Main heading text',
    validation: { required: true, maxLength: 100 }
  }),
  price: PropertyNumber({
    title: 'Price',
    validation: { min: 0, max: 10000 }
  })
});

// Generated schema (stored in component.schema)
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Main heading text",
      "maxLength": 100
    },
    "price": {
      "type": "number",
      "minimum": 0,
      "maximum": 10000
    }
  },
  "required": ["title"]
}
```

## Base URL

All component endpoints use this base path:

```
/app/v1/organizations/:organizationId/projects/:projectId/components
```