## Overview [#overview]

The annotation system provides building block components for creating custom card layouts. Use these to build issue trackers, flag systems, comment threads, or any specialized annotation display.

## Author Configuration [#author-configuration]

Use `defaultAuthor` to set a fallback author for annotations. This applies to:

* Annotations without an explicit author (display fallback)
* Newly created annotations (assigned at creation time)

If an annotation has its own `author` set, it takes precedence over `defaultAuthor`.

```tsx
// User-created annotations
<Document.Annotatable
  defaultAuthor={{ name: "You" }}
  annotations={annotations}
  onAnnotationCreate={handleCreate}
  onAnnotationUpdate={handleUpdate}
  onAnnotationDelete={handleDelete}
>
```

```tsx
// AI-created annotations (shows Mobius logo)
<Document.Annotatable
  defaultAuthor={{ name: "Mobius" }}
  annotations={annotations}
  onAnnotationCreate={handleCreate}
  onAnnotationUpdate={handleUpdate}
  onAnnotationDelete={handleDelete}
>
```

When the author name is "Mobius" (case-insensitive), the sidebar displays the Mobius logo instead of an avatar. This is useful for distinguishing AI-generated annotations from user annotations.

***

## Building Blocks [#building-blocks]

The following components are building blocks for creating custom annotation card layouts. Use them inside `Document.Annotation.Sidebar.Card` to build issue trackers, flag systems, or other specialized annotation displays.

### Document.Annotation.Sidebar.Card.Root [#documentannotationsidebarcardroot]

A customizable container for card content. Use this when you want full control over the card's inner layout while preserving active/hover state styling.

```tsx
<Document.Annotation.Sidebar.Card annotation={annotation}>
  <Document.Annotation.Sidebar.Card.Root className="p-4 rounded-lg bg-card">
    <Document.Annotation.Sidebar.Card.Number />
    <Document.Annotation.Sidebar.Card.Content />
    <Document.Annotation.Sidebar.Card.Footer>
      <Document.Annotation.Sidebar.Card.Header />
    </Document.Annotation.Sidebar.Card.Footer>
  </Document.Annotation.Sidebar.Card.Root>
</Document.Annotation.Sidebar.Card>
```

#### Props [#props]

| Prop        | Type        | Description             |
| ----------- | ----------- | ----------------------- |
| `className` | `string`    | Additional classes      |
| `children`  | `ReactNode` | Card content (required) |

***

### Document.Annotation.Sidebar.Card.Number [#documentannotationsidebarcardnumber]

A number badge for cards, useful for issue/flag-style cards. Displays the annotation's position in document order by default.

```tsx
// Default - shows position number (e.g., "#1", "#2")
<Document.Annotation.Sidebar.Card.Number />

// Custom number
<Document.Annotation.Sidebar.Card.Number number={42} />

// Custom label
<Document.Annotation.Sidebar.Card.Number label="Issue " />
```

#### Props [#props-1]

| Prop        | Type     | Default | Description                                                                                               |
| ----------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `className` | `string` | -       | Additional classes                                                                                        |
| `number`    | `number` | -       | Custom number to display. If not provided, uses the annotation's position in the sorted list (1-indexed). |
| `label`     | `string` | `"#"`   | Custom label for the number badge.                                                                        |

***

### Document.Annotation.Sidebar.Card.Title [#documentannotationsidebarcardtitle]

A title component for cards. Use this for custom card titles like "Issue", "Flag", etc.

```tsx
<Document.Annotation.Sidebar.Card annotation={annotation}>
  <div className="flex items-center gap-2">
    <Document.Annotation.Sidebar.Card.Number />
    <Document.Annotation.Sidebar.Card.Title>
      Issue
    </Document.Annotation.Sidebar.Card.Title>
  </div>
  <Document.Annotation.Sidebar.Card.Content />
</Document.Annotation.Sidebar.Card>
```

#### Props [#props-2]

| Prop        | Type        | Description        |
| ----------- | ----------- | ------------------ |
| `className` | `string`    | Additional classes |
| `children`  | `ReactNode` | Title content      |

***

### Document.Annotation.Sidebar.Card.Timestamp [#documentannotationsidebarcardtimestamp]

Displays when the annotation was created. Uses a relative time format by default (e.g., "just now", "5m ago", "2d ago").

```tsx
// Default relative time format
<Document.Annotation.Sidebar.Card.Timestamp />

// Custom format
<Document.Annotation.Sidebar.Card.Timestamp
  format={(ts) => new Date(ts).toLocaleDateString()}
/>

// ISO format
<Document.Annotation.Sidebar.Card.Timestamp
  format={(ts) => new Date(ts).toISOString()}
/>
```

#### Props [#props-3]

| Prop        | Type                            | Description                                                                      |
| ----------- | ------------------------------- | -------------------------------------------------------------------------------- |
| `className` | `string`                        | Additional classes                                                               |
| `format`    | `(timestamp: number) => string` | Custom format function. Receives the `createdAt` timestamp and returns a string. |

***

### Document.Annotation.Sidebar.Card.Footer [#documentannotationsidebarcardfooter]

A footer container for cards. Use this to place content (like author info, timestamps, or actions) at the bottom of a card.

```tsx
<Document.Annotation.Sidebar.Card annotation={annotation}>
  <Document.Annotation.Sidebar.Card.Citation />
  <Document.Annotation.Sidebar.Card.Textarea />
  <Document.Annotation.Sidebar.Card.Footer>
    <Document.Annotation.Sidebar.Card.Header />
    <Document.Annotation.Sidebar.Card.Timestamp />
  </Document.Annotation.Sidebar.Card.Footer>
</Document.Annotation.Sidebar.Card>
```

#### Props [#props-4]

| Prop        | Type        | Description        |
| ----------- | ----------- | ------------------ |
| `className` | `string`    | Additional classes |
| `children`  | `ReactNode` | Footer content     |

***

### Document.Annotation.Sidebar.Card.Actions [#documentannotationsidebarcardactions]

A container for custom action buttons on cards. By default, shows on hover. Use `alwaysVisible` to show actions always.

```tsx
// Default - shows on hover
<Document.Annotation.Sidebar.Card annotation={annotation}>
  <Document.Annotation.Sidebar.Card.Actions>
    <button onClick={handleEdit}>Edit</button>
    <button onClick={handleResolve}>Resolve</button>
  </Document.Annotation.Sidebar.Card.Actions>
  <Document.Annotation.Sidebar.Card.Content />
</Document.Annotation.Sidebar.Card>

// Always visible
<Document.Annotation.Sidebar.Card.Actions alwaysVisible>
  <Button size="sm" variant="ghost">Mark Complete</Button>
</Document.Annotation.Sidebar.Card.Actions>
```

#### Props [#props-5]

| Prop            | Type        | Default | Description                                                                      |
| --------------- | ----------- | ------- | -------------------------------------------------------------------------------- |
| `className`     | `string`    | -       | Additional classes                                                               |
| `children`      | `ReactNode` | -       | Action buttons                                                                   |
| `alwaysVisible` | `boolean`   | `false` | When true, actions are always visible. When false, actions only appear on hover. |

***

## Examples [#examples]

### Default [#default]

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="DefaultCardExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    <Document.Annotation.Sidebar.Card annotation={annotation} />
    ```
  </Tab>
</Tabs>

### Custom Styling [#custom-styling]

Use `className` to override the container styling and custom children for the content:

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="FlagCardExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    <Document.Annotation.Sidebar.Card
      annotation={annotation}
      className="rounded-lg border-l-4 border-amber-500 bg-amber-50 dark:bg-amber-950/30"
    >
      <div className="mb-2 flex items-center gap-2">
        <Flag className="h-4 w-4 text-amber-600" />
        <Document.Annotation.Sidebar.Card.Title>
          Flagged for Review
        </Document.Annotation.Sidebar.Card.Title>
      </div>
      <Document.Annotation.Sidebar.Card.Citation className="text-sm" />
      <Document.Annotation.Sidebar.Card.Footer className="flex justify-between text-xs text-muted-foreground">
        <Document.Annotation.Sidebar.Card.Header />
        <Document.Annotation.Sidebar.Card.Timestamp />
      </Document.Annotation.Sidebar.Card.Footer>
    </Document.Annotation.Sidebar.Card>
    ```
  </Tab>
</Tabs>