Renamed Formatter to Md and improved test coverage

Author: jeremeamia

src/Blocks/Virtual/CodeBlock.php

@@ -5,7 +5,7 @@
 namespace SlackPhp\BlockKit\Blocks\Virtual;
 
 use SlackPhp\BlockKit\Blocks\{Context, Section};
-use SlackPhp\BlockKit\Kit;
+use SlackPhp\BlockKit\Md;
 
 class CodeBlock extends VirtualBlock
 {
@@ -36,7 +36,7 @@ public function caption(string $caption): self
 
     public function code(string $code): self
     {
-        $code = Kit::formatter()->codeBlock($code);
+        $code = Md::new()->codeBlock($code);
         $this->append(new Section($code));
 
         return $this;

src/Kit.php

@@ -542,6 +542,11 @@ public static function twoColumnTable(
     #endregion
 
     #region Other tools and helpers
+    public static function md(): Md
+    {
+        return new Md();
+    }
+
     /**
      * @param array<string, mixed> $data
      */
@@ -550,11 +555,6 @@ public static function privateMetadata(array $data = []): PrivateMetadata
         return new PrivateMetadata($data);
     }
 
-    public static function formatter(): Formatter
-    {
-        return new Formatter();
-    }
-
     public static function preview(Surfaces\Surface $surface): string
     {
         return Previewer::new()->preview($surface);

src/Formatter.php src/Md.phpsrc/Formatter.php renamed to src/Md.php

@@ -17,14 +17,16 @@
 use function time;
 
 /**
- * Formatter consists of text formatting helpers to support the use of Slack's Mrkdwn format in messages, modals, etc.
+ * Md consists of text formatting helpers to support the use of Slack's Mrkdwn format in messages, modals, etc.
  *
  * Some characters ("<", ">", "&") should be escaped when they are not a part of formatting that requires those
  * characters. The formatting helpers in this class automatically escape input in situations where the text is place
  * within angle brackets, such as with dates and links.
  */
-final class Formatter
+final class Md
 {
+    private static ?self $instance = null;
+
     public const DATE = '{date}';
     public const DATE_LONG = '{date_long}';
     public const DATE_LONG_PRETTY = '{date_long_pretty}';
@@ -37,7 +39,7 @@ final class Formatter
 
     public static function new(): self
     {
-        return new self();
+        return (self::$instance ??= new self());
     }
 
     /**
@@ -72,7 +74,7 @@ public function sub(string $text, array $values): string
         return strtr($text, $replacements);
     }
 
-    //region Helpers for @here, @channel, and @everyone mentions.
+    #region Helpers for @here, @channel, and @everyone mentions.
     public function atChannel(): string
     {
         return '<!channel>';
@@ -87,9 +89,9 @@ public function atHere(): string
     {
         return '<!here>';
     }
-    //endregion
+    #endregion
 
-    //region Helpers for mentioning/linking specific channels, users, or user groups.
+    #region Helpers for mentioning/linking specific channels, users, or user groups.
     public function channel(string $id): string
     {
         return "<#{$id}>";
@@ -104,9 +106,9 @@ public function userGroup(string $id): string
     {
         return "<!subteam^{$id}>";
     }
-    //endregion
+    #endregion
 
-    //region Helpers for basic text formatting (B/I/S) and links.
+    #region Helpers for basic text formatting (B/I/S) and links.
     public function bold(string $text): string
     {
         return "*{$text}*";
@@ -129,43 +131,39 @@ public function strike(string $text): string
 
     public function link(string $url, ?string $text = null): string
     {
-        return isset($text) ? "<{$this->escape($url)}|{$this->escape($text)}>" : "<{$this->escape($url)}>";
+        return isset($text) ? "<{$url}|{$this->escape($text)}>" : "<{$url}>";
     }
 
     public function emailLink(string $email, ?string $text = null): string
     {
         return $this->link("mailto:{$email}", $text);
     }
-    //endregion
+    #endregion
 
-    //region Helpers for multi-line content blocks like lists and quotes.
+    #region Helpers for multi-line content blocks like lists and quotes.
     /**
      * @param array<string>|string $lines
-     * @return string
      */
     public function blockQuote(array|string $lines): string
     {
         return $this->lines($this->explode($lines), '> ', false);
     }
 
+    public function codeBlock(string $text): string
+    {
+        return "```\n{$this->escape($text)}\n```";
+    }
+
     /**
      * @param array<string>|string $items
-     * @param string $bullet
-     * @return string
      */
     public function bulletedList(array|string $items, string $bullet = '•'): string
     {
         return $this->lines($this->explode($items), "{$bullet} ");
     }
 
-    public function codeBlock(string $text): string
-    {
-        return "```\n{$this->escape($text)}\n```";
-    }
-
     /**
      * @param array<string>|string $items
-     * @return string
      */
     public function numberedList(array|string $items): string
     {
@@ -182,9 +180,6 @@ public function numberedList(array|string $items): string
      * Optionally applies a prefix to each line. You can use a closure if the prefix varies per line.
      *
      * @param array<string> $lines
-     * @param string|callable|null $prefix
-     * @param bool $filter
-     * @return string
      */
     public function lines(array $lines, string|callable|null $prefix = null, bool $filter = true): string
     {
@@ -194,10 +189,8 @@ public function lines(array $lines, string|callable|null $prefix = null, bool $f
             };
         }
 
-        if (is_callable($prefix)) {
+        if (!is_null($prefix)) {
             $lines = array_map($prefix, $lines);
-        } elseif (!is_null($prefix)) {
-            throw new Exception('Formatter::lines given invalid prefix argument');
         }
 
         if ($filter) {
@@ -208,17 +201,16 @@ public function lines(array $lines, string|callable|null $prefix = null, bool $f
 
         return implode("\n", $lines) . "\n";
     }
-    //endregion
+    #endregion
 
-    //region Helpers for formatting dates and times.
+    #region Helpers for formatting dates and times.
     /**
      * Formats a timestamp as a date in mrkdwn.
      *
      * @param int|null $timestamp Timestamp to format. Defaults to now.
      * @param string $format Format name supported by Slack. Defaults to "{date}".
      * @param string|null $fallback Fallback text for old Slack clients. Defaults to an ISO-formatted timestamp.
      * @param string|null $link URL, if the date is to act as a link.
-     * @return string
      * @see https://api.slack.com/reference/surfaces/formatting#date-formatting
      */
     public function date(
@@ -243,7 +235,6 @@ public function date(
      * @param string $format Format name supported by Slack. Defaults to "{time}".
      * @param string|null $fallback Fallback text for old Slack clients. Defaults to an ISO-formatted timestamp.
      * @param string|null $link URL, if the time is to act as a link.
-     * @return string
      */
     public function time(
         ?int $timestamp = null,
@@ -253,7 +244,7 @@ public function time(
     ): string {
         return $this->date($timestamp, $format, $fallback, $link);
     }
-    //endregion
+    #endregion
 
     /**
      * Ensures the provided items are an array.
@@ -265,12 +256,10 @@ public function time(
      */
     private function explode(array|string $items): array
     {
-        if (is_string($items)) {
-            return explode("\n", $items);
-        } elseif (is_array($items)) {
+        if (is_array($items)) {
             return $items;
         }
 
-        throw new Exception('Formatter::explode given invalid items argument');
+        return explode("\n", $items);
     }
 }

tests/Functional/CreateTest.php

@@ -161,7 +161,7 @@ public function testThatAllKitComponentMethodsReturnComponents(): void
             'fieldsFromMap',
             'fieldsFromPairs',
             'privateMetadata',
-            'formatter',
+            'md',
             'preview',
             'hydrate',
         ];

tests/MdTest.php

@@ -0,0 +1,82 @@
+<?php
+
+namespace SlackPhp\BlockKit\Tests;
+
+use SlackPhp\BlockKit\Md;
+
+/**
+ * @covers \SlackPhp\BlockKit\Md
+ */
+class MdTest extends TestCase
+{
+    public function testCanDoSimpleTextFormatting(): void
+    {
+        $f = Md::new();
+        $this->assertEquals('*hello*', $f->bold('hello'));
+        $this->assertEquals('_hello_', $f->italic('hello'));
+        $this->assertEquals('~hello~', $f->strike('hello'));
+        $this->assertEquals('`hello`', $f->code('hello'));
+    }
+
+    public function testCanDoEntityReferenceFormatting(): void
+    {
+        $f = Md::new();
+        $this->assertEquals('<!channel>', $f->atChannel());
+        $this->assertEquals('<!everyone>', $f->atEveryone());
+        $this->assertEquals('<!here>', $f->atHere());
+        $this->assertEquals('<#C01>', $f->channel('C01'));
+        $this->assertEquals('<@U01>', $f->user('U01'));
+        $this->assertEquals('<!subteam^G01>', $f->userGroup('G01'));
+    }
+
+    public function testCanInterpolateAndEscapeText(): void
+    {
+        $f = Md::new();
+        $text = $f->escape($f->sub('There is {name} & John.', ['name' => 'Jim']));
+        $this->assertEquals('There is Jim &amp; John.', $text);
+    }
+
+    public function testCanFormatLinks(): void
+    {
+        $f = Md::new();
+        $this->assertEquals(
+            '<https://slack.com|slack website>',
+            $f->link('https://slack.com', 'slack website'),
+        );
+        $this->assertEquals(
+            '<https://slack.com|&lt;slack&amp;website&gt;>',
+            $f->link('https://slack.com', '<slack&website>'),
+        );
+        $this->assertEquals(
+            '<mailto:noreply@slack.com|email slack>',
+            $f->emailLink('noreply@slack.com', 'email slack'),
+        );
+    }
+
+    public function testCanDoComplexFormatting(): void
+    {
+        $f = Md::new();
+        $this->assertEquals(
+            "> hello\n> world\n",
+            $f->blockQuote("hello\nworld"),
+        );
+        $this->assertEquals(
+            "```\necho \"hello\";\n```",
+            $f->codeBlock('echo "hello";'),
+        );
+        $this->assertEquals(
+            "• a\n• b\n• c\n",
+            $f->bulletedList(['a', 'b', 'c']),
+        );
+        $this->assertEquals(
+            "1. a\n2. b\n3. c\n",
+            $f->numberedList(['a', 'b', 'c']),
+        );
+
+        $time = time();
+        $this->assertEquals(
+            "<!date^{$time}^{time}^http:/slack.com|foo>",
+            $f->time($time, fallback: 'foo', link: 'http:/slack.com'),
+        );
+    }
+}

tests/TypeTest.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace SlackPhp\BlockKit\Tests;
+
+use SlackPhp\BlockKit\Blocks\Section;
+use SlackPhp\BlockKit\{Exception, Kit, Type};
+use Throwable;
+
+/**
+ * @covers \SlackPhp\BlockKit\Type
+ */
+class TypeTest extends TestCase
+{
+    public function testCanMapDefinedElementClassToADefinedType(): void
+    {
+        $this->assertEquals(Type::SECTION, Type::fromClass(Section::class));
+    }
+
+    public function testThrowsErrorIfMappingClassesNotRegisteredInTypeMaps(): void
+    {
+        $this->expectException(Exception::class);
+        Type::fromClass(Kit::class);
+    }
+
+    public function testCanMapDefinedElementTypeToADefinedClass(): void
+    {
+        $this->assertEquals(Section::class, Type::SECTION->toClass());
+    }
+
+    public function testThrowsErrorIfMappingTypesNotRegisteredInTypeMaps(): void
+    {
+        $this->expectException(Throwable::class);
+        Type::fromValue('shoe');
+    }
+}