🗑️ Replace type Text with TextSpan

The type `Text` had a recursive definition that included an array of
itself (`Text[]`). This created an unnecessary complex type that may
even cause problems for the type checker. It also allowed for the
unintended edge case of nested arrays (e.g. `[['foo']]`).

This commit and introduces a new, simpler type `TextSpan` that combines
a `text` property with optional style properties. The `text` property
also accepts nested `TextSpan` arrays. This results in a clearer and
almost identical interface except for the irregular edge case of nested
arrays.

The type `Text` is marked as deprecated.

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+TODO Text to TextSpan
+
 ## [0.5.5] - Unreleased
 
 ### Deprecated
@@ -8,6 +10,8 @@
 - `BlockAttrs` in favor of `BlockProps`.
 - `InfoAttrs` in favor of `InfoProps`.
 - `CustomInfoAttrs` in favor of `CustomInfoProps`.
+- `Text` in favor of `TextSpan`. This rules out nested arrays such as
+  `[['foo']]` as value for the `text` property in `TextBlock`.
 
 ## [0.5.4] - 2024-02-25
 

README.md

@@ -36,7 +36,7 @@ const pdfData = await makePdf({
   content: [
     // Blocks can contain text and text properties
     { text: 'Lorem ipsum', fontStyle: 'italic', textAlign: 'center', fontSize: 24 },
-    // Text can also be an array of text ranges with different properties
+    // Text can also be an array of text spans with different properties
     {
       text: [
         'dolor sit amet, consectetur adipiscing elit ',

examples/src/text.js

@@ -28,7 +28,7 @@ const def = {
     },
     {
       text: [
-        // ... or an array of strings and objects.
+        // ... or an array of strings and text spans.
         'Text objects can be used to apply individual styles, like ',
         { text: 'font size', fontSize: 18 },
         ', ',

src/api/layout.ts

@@ -1,6 +1,6 @@
 import type { Shape } from './graphics.ts';
 import type { BoxLengths, Length } from './sizes.ts';
-import type { TextProps } from './text.ts';
+import type { Text, TextProps, TextSpan } from './text.ts';
 
 export type Block = TextBlock | ImageBlock | ColumnsBlock | RowsBlock | EmptyBlock;
 
@@ -9,9 +9,10 @@ export type Block = TextBlock | ImageBlock | ColumnsBlock | RowsBlock | EmptyBlo
  */
 export type TextBlock = {
   /**
-   * Text to display in this block.
+   * Text to display in this block. Nested text spans can be used to
+   * apply different text properties to different parts of the text.
    */
-  text: Text;
+  text: string | TextSpan | (string | TextSpan)[] | Text;
 
   /**
    * Controls whether a page break may occur inside the block.

src/api/text.ts

@@ -1,10 +1,16 @@
 import type { Color } from './colors.ts';
 
 /**
- * A piece of inline text. A list can be used to apply different styles
- * to individual ranges of a text.
+ * Deprecated. Use `TextSpan` instead.
  */
-export type Text = string | ({ text: Text } & TextProps) | Text[];
+export type Text = string | TextSpan | TextSpan[];
+
+/**
+ * A span of text with optional text properties. Nested spans can be
+ * used to apply different text properties to different parts of a
+ * text.
+ */
+export type TextSpan = { text: string | TextSpan | (string | TextSpan)[] } & TextProps;
 
 /**
  * The font weight is an integer between 0 and 1000. The keywords