@ryhrm-gz/xincodo-lib/skills/building-and-parsing-body/references/builder-signatures.md

Utilities for working with Xincodo body documents.

# Builder Signatures

Import builders from the package root.

```ts
import { createBody, paragraph, heading, text } from "@ryhrm-gz/xincodo-lib";
```

## Body and Rich Text

```ts
createBody(content: BodyBlock[]): Body
text(value: string, options?: { annotations?: TextAnnotations; link?: TextLink }): TextInline
lineBreak(): LineBreakInline
richText(...content: (string | BodyRichText)[]): BodyRichText[]
```

## Rich Text Blocks

These accept strings and inline objects. If the last argument is an options
object without a `type` field, it is treated as options.

```ts
paragraph(...content: RichTextInput[]): TextBlock
paragraph(...contentAndOptions: [...RichTextInput[], TextBlockOptions]): TextBlock

heading(level: 1 | 2 | 3 | 4, ...content: RichTextInput[]): HeadingBlock
heading(level: 1 | 2 | 3 | 4, ...contentAndOptions: [...RichTextInput[], BlockBuilderOptions]): HeadingBlock

callout(...content: RichTextInput[]): CalloutBlock
callout(...contentAndOptions: [...RichTextInput[], CalloutOptions]): CalloutBlock

quote(...content: RichTextInput[]): QuoteBlock
quote(...contentAndOptions: [...RichTextInput[], TextBlockOptions]): QuoteBlock
```

## Lists

```ts
listItem(...content: RichTextInput[]): ListItem
listItem(...contentAndOptions: [...RichTextInput[], ListItemOptions]): ListItem

toggleListItem(...content: RichTextInput[]): ToggleListItem
toggleListItem(...contentAndOptions: [...RichTextInput[], ToggleListItemOptions]): ToggleListItem

bulletedList(items: ListItem[], options?: BlockBuilderOptions): BulletedListBlock
numberedList(items: ListItem[], options?: BlockBuilderOptions & { start?: number }): NumberedListBlock
toggleList(items: ToggleListItem[], options?: BlockBuilderOptions): ToggleListBlock
```

## Tables and Media

```ts
tableCell(...content: RichTextInput[]): TableCell
tableRow(cells: TableCell[]): TableRow
table(rows: TableRow[], options?: TableOptions): TableBlock

pageLink(page: PageReference, options?: PageLinkOptions): PageLinkBlock
image(source: ImageSource, options?: ImageOptions): ImageBlock
galleryImage(source: ImageSource, options?: GalleryImageOptions): GalleryImage
gallery(images: GalleryImage[], options?: GalleryOptions): GalleryBlock
divider(options?: BlockBuilderOptions): DividerBlock
```

## Options Pattern

Options are only detected when the last argument is an object without a `type`
field. If you pass a rich text inline object last, it remains content.

```ts
import { paragraph, text } from "@ryhrm-gz/xincodo-lib";

const block = paragraph("Intro ", text("link", { link: { href: "https://example.com" } }), {
  id: "intro",
});
```