✨Introduce API to create blocks

This commit introduces functions to create blocks more conveniently. The
functions `text()` and `image()` can be used to create blocks that
contain text or images. The functions `columns()` and `rows()` can be
used to create blocks that contain other blocks.

Using these functions enables better suggestions in the editor. Since
they return objects with a specific type, less type annotations are
required in the code.

For example, the following line of code

```ts
const block: Block = {
  rows: [
    { text: 'Hello World!', { fontWeight: 'bold' } },
    { image: 'liberty.jpg', height: 55, imageAlign: 'left' },
  ],
  margin: { x: 75, y: 10 },
};
```

can now be replaced with:

```ts
const block = rows(
  [
    text('Hello World!', { fontWeight: 'bold' }),
    image('liberty.jpg', { height: 55, imageAlign: 'left' }),
  ],
  { margin: { x: 75, y: 10 } },
);
```

CHANGELOG.md

@@ -12,6 +12,9 @@ Minimum requirements bumped to Node 20 and npm 10.
 - The function `span()` to create text spans with less code and better
  tool support.
 
+- The functions `text()`, `image()`, `rows()`, and `columns()` to create
+ blocks with less code and better tool support.
+
 ### Deprecated
 
 - `TextAttrs` in favor of `TextProps`.

src/api/layout.ts

@@ -23,6 +23,21 @@ export type TextBlock = {
 } & TextProps &
  BlockProps;
 
+/**
+ * Creates a text block. The text can contain nested text spans to apply
+ * different text properties to different parts of the text. Use
+ * `span()` to create text spans.
+ *
+ * @param text The text to display in this block.
+ * @param props Optional properties for the block.
+ */
+export function text(
+ text: string | TextSpan | (string | TextSpan)[],
+ props?: Omit<TextBlock, 'text'>,
+): TextBlock {
+ return { ...props, text };
+}
+
 /**
  * A block that contains an image.
  */
@@ -49,6 +64,16 @@ export type ImageBlock = {
  imageAlign?: Alignment;
 } & BlockProps;
 
+/**
+ * Creates a block that contains an image.
+ *
+ * @param image The name or path of an image to display in this block.
+ * @param props Optional properties for the block.
+ */
+export function image(image: string, props?: Omit<ImageBlock, 'image'>): ImageBlock {
+ return { ...props, image };
+}
+
 /**
  * A block that contains other blocks arranged horizontally.
  */
@@ -60,6 +85,16 @@ export type ColumnsBlock = {
 } & TextProps &
  BlockProps;
 
+/**
+ * Creates a block that contains other blocks arranged horizontally.
+ *
+ * @param columns Content blocks to arrange horizontally.
+ * @param props Optional properties for the block.
+ */
+export function columns(columns: Block[], props?: Omit<ColumnsBlock, 'columns'>): ColumnsBlock {
+ return { ...props, columns };
+}
+
 /**
  * A block that contains other blocks arranged vertically.
  */
@@ -83,6 +118,16 @@ export type RowsBlock = {
 } & TextProps &
  BlockProps;
 
+/**
+ * Creates a block that contains other blocks arranged vertically.
+ *
+ * @param rows Content blocks to arrange vertically.
+ * @param props Optional properties for the block.
+ */
+export function rows(rows: Block[], props?: Omit<RowsBlock, 'rows'>): RowsBlock {
+ return { ...props, rows };
+}
+
 /**
  * A block that doesn't contain any content. It can be used to include
  * graphics.