Improved usability of outside parser context.

Author: petercv

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to this project will be documented in this file.
 
+## v1.3.1 - 2025-08-24
+- Improved usability of `AttributedStringBuilder` outside parser context.
+
 ## v1.3 - 2025-08-23
 - Added `replace` and `replaceMatches` methods to `AttributedString` for replacing substrings and regex matches within
   attributed (sub-)strings.

src/MarkupKit/Core/Parsers/Traits/ParsePhrasingNodeGroup.php

@@ -22,7 +22,7 @@ protected function createStringBuilderForFlowNode(
         DOMElement|DOMText $node,
         Context $context
     ): AttributedStringBuilder {
-        return new AttributedStringBuilder();
+        return new AttributedStringBuilder(preserveWhitespace: false, trimWhitespaceAroundAttachments: false);
     }
 
     /**

src/MarkupKit/Core/String/AbstractAttributedElement.php

@@ -6,9 +6,15 @@
 
 abstract readonly class AbstractAttributedElement implements AttributedElement
 {
+    public AttributeContainer $attributes;
+
+    /**
+     * @param AttributeContainer|array<int, Attribute> $attributes
+     */
     public function __construct(
-        public AttributeContainer $attributes = new AttributeContainer()
+        AttributeContainer|array $attributes = []
     ) {
+        $this->attributes = $attributes instanceof AttributeContainer ? $attributes : new AttributeContainer($attributes);
     }
 
     public function withAttribute(Attribute $attribute): static

src/MarkupKit/Core/String/AttributedStringBuilder.php

@@ -14,7 +14,7 @@ class AttributedStringBuilder
      * @param bool $trimWhitespaceAroundAttachments Whether to trim whitespace around attachments.
      */
     public function __construct(
-        public readonly bool $preserveWhitespace = false,
+        public readonly bool $preserveWhitespace = true,
         public readonly bool $trimWhitespaceAroundAttachments = false
     ) {
     }
@@ -104,7 +104,10 @@ private function normalizeTrailingSpace(): array
         return $elements;
     }
 
-    public function appendString(string $string, AttributeContainer $attributes): void
+    /**
+     * @param AttributeContainer|array<int, Attribute> $attributes
+     */
+    public function appendString(string $string, AttributeContainer|array $attributes = []): void
     {
         $string = $this->normalizeSpace($string, end($this->elements) ?: null);
         if (strlen($string) === 0) {
@@ -114,7 +117,10 @@ public function appendString(string $string, AttributeContainer $attributes): vo
         $this->elements[] = new AttributedSubstring($string, $attributes);
     }
 
-    public function appendLineBreak(AttributeContainer $attributes): void
+    /**
+     * @param AttributeContainer|array<int, Attribute> $attributes
+     */
+    public function appendLineBreak(AttributeContainer|array $attributes = []): void
     {
         $this->elements[] = new AttributedSubstring("\n", $attributes);
     }

src/MarkupKit/Core/String/AttributedSubstring.php

@@ -9,9 +9,12 @@
 {
     use OptimizeElements;
 
+    /**
+     * @param AttributeContainer|array<int, Attribute> $attributes
+     */
     public function __construct(
         public string $string,
-        AttributeContainer $attributes
+        AttributeContainer|array $attributes = []
     ) {
         parent::__construct($attributes);
     }

src/MarkupKit/Standard/String/ImageAttachment.php

@@ -10,11 +10,14 @@
 
 final readonly class ImageAttachment extends Attachment implements HtmlElement, MarkdownElement
 {
+    /**
+     * @param AttributeContainer|array<int, Attribute> $attributes
+     */
     public function __construct(
         public string $src,
         public ?string $alt,
         public ?string $title,
-        AttributeContainer $attributes
+        AttributeContainer|array $attributes
     ) {
         parent::__construct($attributes);
     }