# Social Components

Social components add engagement to pages: threaded comments (authenticated and public/guest), comment counts, an AI-agent chat panel, and sharing controls. The comments components integrate with the table comment system and respect the table's `comment` permission. All accept the shared `props` bag plus `visibility` and `responsive` modules.

```yaml
components:
  - type: comments
    props: { placeholder: 'Add a comment…', limit: 20, sort: newest, paginationStyle: loadMore }
  - type: commentCount
    props: { format: '{count} comments', emptyText: 'No comments yet' }
```

## `comments`

A full comment thread for a record. On a collection page it auto-resolves `$record.id` and `collection.table` for API calls. Displays author name, avatar, content, and relative timestamp; respects the table's `comment` permission (hidden when the user lacks it).

| Property                | Description                                                            |
| ----------------------- | ---------------------------------------------------------------------- |
| `props.placeholder`     | Placeholder text for the comment-form textarea.                        |
| `props.limit`           | Comments loaded per page (default: 20).                                |
| `props.sort`            | Order: `newest` (desc, default) or `oldest` (asc).                     |
| `props.paginationStyle` | `loadMore` (default, a Load More button) or `numbered` (page numbers). |
| `props.showCount`       | Show a comment-count badge (default: `true`).                          |
| `props.emptyText`       | Custom message when no comments exist (default: "No comments yet").    |

The comment form is shown to authenticated users with `comment` permission and hidden from unauthenticated visitors (who instead see a "Sign in to comment" prompt when `comment: authenticated`). Authors can edit/delete their own comments; admins can delete any. Content is limited to 10,000 characters (matching the API).

### Public / guest comments

When the table's comment config enables `guestComments`, the form also accepts guest name and email, and supports moderation, threading, and spam protection:

| Concern         | Behavior                                                                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Guest fields    | Name required (1–100 chars); email required when `guestEmailRequired` (default), validated as an email. Stored with `userId: null`.                                             |
| Threading       | `threading: true` shows a single-level Reply on top-level comments; replies store a `parentId`. `threading: false` (default) is flat.                                           |
| Moderation      | `moderation: true` creates new comments as `pending`; admins approve/reject. `autoApprove.authenticated` / `autoApprove.previouslyApproved` bypass moderation.                  |
| Spam protection | Honeypot field, IP rate limiting (`rateLimitPerIp`, default 5/min → 429), link threshold (`maxLinksBeforeModeration`), and blocked-word auto-reject — all enforced server-side. |

## `commentCount`

A compact comment-count display. On collection pages it auto-resolves `$record.id` and `collection.table`; on dataSource-bound parents it resolves per `$record.id` for each record in a list.

| Property          | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `props.format`    | Count template with a `{count}` placeholder (default: `'{count} comments'`). |
| `props.emptyText` | Display when the count is 0 (default: `'0 comments'`).                       |

The count is read from the comments API pagination metadata and includes only `approved` comments when moderation is on.

## `ai-chat`

An embedded chat panel backed by a configured AI agent. See [Agents](/en/docs/ai-agents) for agent configuration.

| Property           | Description                                 |
| ------------------ | ------------------------------------------- |
| `agent`            | Agent name from `app.agents[]`.             |
| `placeholder`      | Placeholder text for the chat input.        |
| `height`           | Chat container height in pixels.            |
| `showHistory`      | Show previous conversation history on load. |
| `allowAttachments` | Allow file attachments in chat.             |

```yaml
- type: ai-chat
  agent: support-assistant
  height: 480
  placeholder: 'Ask a question…'
  allowAttachments: true
```

## `sharing`

Share controls for the current page or record (social links, copy-link). Sharing surfaces are composed from `link`/`button` components with `navigate` interactions; for copy-to-clipboard behavior see [Interactivity & Scripts](/en/docs/interactivity-scripts).

| Property   | Description                                                                  |
| ---------- | ---------------------------------------------------------------------------- |
| `props`    | HTML attributes and share-target options (e.g. `className`, share URL/text). |
| `children` | Custom share buttons/links.                                                  |

## Related Pages

- [Pages Overview](/en/docs/pages-overview) — collection pages and `$record.*` resolution.
- [Agents](/en/docs/ai-agents) — configure the AI agents that power `ai-chat`.
- [Table Permissions](/en/docs/table-permissions) — the `comment` permission gating comments.
- [Interactivity & Scripts](/en/docs/interactivity-scripts) — clipboard and navigate actions for sharing.
- [Notifications](/en/docs/automation-email-actions) — comment automation triggers.