# Bubble API reference

> Exports of @gramforge/bubble.

Source: https://gramforge.n.yatsyk.com/docs/bubble/jsdoc

## Functions

### entitiesToHtml

Render a validated {@link BubblePayload}'s `text`/`entities` to a
Telegram-look HTML string. `payload.imageUrl` (caption payloads) is not
consumed here — rendering the image reference is `<TelegramBubble>`'s job.

```ts
entitiesToHtml(payload: BubblePayload): string
```

### TelegramBubble

Render a `BubblePayload` as an outgoing- or incoming-direction chat bubble.

```ts
TelegramBubble(props: TelegramBubbleProps): JSX.Element
```

## Types

### BubblePayload

Either preview payload shape `entitiesToHtml`/`TelegramBubble` accept.

```ts
type BubblePayload = BubbleEntityPayload | BubbleCaptionPayload
```

### DeliveryStatus

The outgoing-bubble send/read-receipt tick state — a discriminated union,
matched exhaustively via `ts-pattern` so every state renders a distinct
affordance (never "nothing happened").

```ts
type DeliveryStatus = | { readonly kind: "sending" }
  | { readonly kind: "sent" }
  | { readonly kind: "delivered" }
  | { readonly kind: "read" }
  | { readonly kind: "failed"; readonly reason: string }
```

### TelegramBubbleProps

`<TelegramBubble>` props. `direction` discriminates the whole prop set:
`delivery` exists only for `"outgoing"` (no dead/always-undefined prop for
the `"incoming"` variant, which never shows a read receipt).

```ts
type TelegramBubbleProps = | {
      readonly direction: "outgoing";
      readonly payload: BubblePayload;
      readonly timestamp: Date;
      readonly delivery: DeliveryStatus;
    }
  | {
      readonly direction: "incoming";
      readonly payload: BubblePayload;
      readonly timestamp: Date;
    }
```

## Interfaces

### BubbleCaptionPayload

A captioned image: an `imageUrl` to display plus caption text/entities.

```ts
interface BubbleCaptionPayload
```

- `kind: "caption"`
- `text: string`
- `entities: readonly MessageEntity[]`
- `imageUrl: string`

### BubbleEntityPayload

A plain text message: rendered text plus its formatting entities.

```ts
interface BubbleEntityPayload
```

- `kind: "message"`
- `text: string`
- `entities: readonly MessageEntity[]`

## Constants

### BubbleCaptionPayloadSchema

Validates a {@link BubbleCaptionPayload} (≤1024 UTF-16 code units — the Bot API caption limit).

```ts
const BubbleCaptionPayloadSchema: z.ZodType<BubbleCaptionPayload, z.ZodTypeDef, BubbleCaptionPayload>
```

### BubbleEntityPayloadSchema

Validates a {@link BubbleEntityPayload} (≤4096 UTF-16 code units — the Bot API message limit).

```ts
const BubbleEntityPayloadSchema: z.ZodType<BubbleEntityPayload, z.ZodTypeDef, BubbleEntityPayload>
```

### BubblePayloadSchema

Validates either {@link BubblePayload} variant, dispatching on `kind`.

```ts
const BubblePayloadSchema: z.ZodType<BubblePayload, z.ZodTypeDef, BubblePayload>
```