feat(page): properties with empty values (#260)

Closes #257

CHANGELOG.md

@@ -6,23 +6,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Page properties with empty values (#260)
+
 ## [v1.9.0] 2023-06-15
 
-## Added
+### Added
 - Caption on image block and file objects (#250)
 
-## Fixed
+### Fixed
 - Do not update CreatedBy prop on pages (#251)
 
 ## [v1.8.1] 2023-06-12
 
-## Fixed
+### Fixed
 - Rich Text mention creation (#241)
 - Possible null pointer on RichText (#246)
 - Change rich text URL
 - Only send to API file name when set (#234)
 
-## Build
+### Build
 - Bump phpunit/phpunit from 10.1.2 to 10.1.3 (#227)
 - Bump guzzlehttp/guzzle from 7.5.1 to 7.6.1 (#226)
 - Bump php-http/discovery from 1.18.0 to 1.18.1 (#228)
@@ -32,10 +35,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Bump vite from 3.1.3 to 3.2.7 in /docs (#236)
 - Bump phpunit/phpunit from 10.1.3 to 10.2.2 (#244)
 
-## Test
+### Test
 - Fix file-related tests (#245)
 
-## Chore
+### Chore
 - Add sponsors to README (#237)
 
 ## [v1.8.0] 2023-05-09

src/Pages/Properties/Date.php

@@ -39,6 +39,13 @@ public static function createRange(DateTimeImmutable $start, DateTimeImmutable $
         return new self($property, CommonDate::createRange($start, $end));
     }
 
+    public static function createEmpty(): self
+    {
+        $metadata = PropertyMetadata::create("", PropertyType::Date);
+
+        return new self($metadata, null);
+    }
+
     public static function fromArray(array $array): self
     {
         /** @psalm-var DateJson $array */
@@ -79,6 +86,11 @@ public function removeEnd(): self
         return new self($this->metadata, $this->date?->removeEnd());
     }
 
+    public function clear(): self
+    {
+        return new self($this->metadata, null);
+    }
+
     public function start(): DateTimeImmutable|null
     {
         return $this->date?->start;

src/Pages/Properties/Email.php

@@ -26,6 +26,13 @@ public static function create(string $email): self
         return new self($property, $email);
     }
 
+    public static function createEmpty(): self
+    {
+        $property = PropertyMetadata::create("", PropertyType::Email);
+
+        return new self($property, null);
+    }
+
     public static function fromArray(array $array): self
     {
         /** @psalm-var EmailJson $array */
@@ -56,6 +63,11 @@ public function changeEmail(string $email): self
         return new self($this->metadata, $email);
     }
 
+    public function clear(): self
+    {
+        return new self($this->metadata, null);
+    }
+
     public function isEmpty(): bool
     {
         return $this->email === null;

src/Pages/Properties/Number.php

@@ -2,8 +2,6 @@
 
 namespace Notion\Pages\Properties;
 
-use Notion\Common\RichText;
-
 /**
  * @psalm-type NumberJson = array{
  *      id: string,
@@ -28,6 +26,13 @@ public static function create(int|float $number): self
         return new self($property, $number);
     }
 
+    public static function createEmpty(): self
+    {
+        $property = PropertyMetadata::create("", PropertyType::Number);
+
+        return new self($property, null);
+    }
+
     public static function fromArray(array $array): self
     {
         /** @psalm-var NumberJson $array */
@@ -58,6 +63,11 @@ public function changeNumber(int|float $number): self
         return new self($this->metadata, $number);
     }
 
+    public function clear(): self
+    {
+        return new self($this->metadata, null);
+    }
+
     public function isEmpty(): bool
     {
         return $this->number === null;

src/Pages/Properties/PhoneNumber.php

@@ -26,6 +26,13 @@ public static function create(string $phone): self
         return new self($property, $phone);
     }
 
+    public static function createEmpty(): self
+    {
+        $property = PropertyMetadata::create("", PropertyType::PhoneNumber);
+
+        return new self($property, null);
+    }
+
     public static function fromArray(array $array): self
     {
         /** @psalm-var PhoneNumberJson $array */
@@ -56,6 +63,11 @@ public function changePhone(string $phone): self
         return new self($this->metadata, $phone);
     }
 
+    public function clear(): self
+    {
+        return new self($this->metadata, null);
+    }
+
     public function isEmpty(): bool
     {
         return $this->phone === null;

src/Pages/Properties/PropertyCollection.php

@@ -5,9 +5,11 @@
 /** @psalm-immutable */
 final class PropertyCollection
 {
-    /** @param array<string, PropertyInterface> $properties */
+    /**
+     * @param array<string, PropertyInterface> $properties
+     */
     private function __construct(
-        private readonly array $properties
+        private readonly array $properties,
     ) {
     }
 

src/Pages/Properties/RichTextProperty.php

@@ -39,6 +39,13 @@ public static function fromString(string $text): self
         return new self($metadata, $texts);
     }
 
+    public static function createEmpty(): self
+    {
+        $metadata = PropertyMetadata::create("", PropertyType::RichText);
+
+        return new self($metadata, []);
+    }
+
     public static function fromArray(array $array): self
     {
         /** @psalm-var RichTextPropertyMetadataJson $array */
@@ -74,6 +81,16 @@ public function changeText(RichText ...$texts): self
         return new self($this->metadata, $texts);
     }
 
+    public function clear(): self
+    {
+        return new self($this->metadata, []);
+    }
+
+    public function isEmpty(): bool
+    {
+        return count($this->text) === 0;
+    }
+
     public function toString(): string
     {
         $string = "";

src/Pages/Properties/Select.php

@@ -44,6 +44,13 @@ public static function fromOption(SelectOption $option): self
         return new self($metadata, $option);
     }
 
+    public static function createEmpty(): self
+    {
+        $metadata = PropertyMetadata::create("", PropertyType::Select);
+
+        return new self($metadata, null);
+    }
+
     public static function fromArray(array $array): self
     {
         /** @psalm-var SelectJson $array */
@@ -72,6 +79,11 @@ public function changeOption(SelectOption $option): self
         return new self($this->metadata, $option);
     }
 
+    public function clear(): self
+    {
+        return new self($this->metadata, null);
+    }
+
     public function isEmpty(): bool
     {
         return $this->option === null;

src/Pages/Properties/Url.php

@@ -26,6 +26,13 @@ public static function create(string $url): self
         return new self($metadata, $url);
     }
 
+    public static function createEmpty(): self
+    {
+        $metadata = PropertyMetadata::create("", PropertyType::Url);
+
+        return new self($metadata, null);
+    }
+
     public static function fromArray(array $array): self
     {
         /** @psalm-var UrlJson $array */
@@ -56,6 +63,11 @@ public function changeUrl(string $url): self
         return new self($this->metadata, $url);
     }
 
+    public function clear(): self
+    {
+        return new self($this->metadata, null);
+    }
+
     public function isEmpty(): bool
     {
         return $this->url === null;

tests/Unit/Pages/Properties/DateTest.php

@@ -34,6 +34,13 @@ public function test_create_range(): void
         $this->assertEquals($end, $date->end());
     }
 
+    public function test_create_empty(): void
+    {
+        $date = Date::createEmpty();
+
+        $this->assertTrue($date->isEmpty());
+    }
+
     public function test_change_start(): void
     {
         $newStart = new DateTimeImmutable("2021-01-01");
@@ -65,6 +72,15 @@ public function test_remove_end(): void
         $this->assertFalse($date->isRange());
     }
 
+    public function test_clear(): void
+    {
+        $someday = new DateTimeImmutable("2021-01-01");
+
+        $date = Date::create($someday)->clear();
+
+        $this->assertTrue($date->isEmpty());
+    }
+
     public function test_array_conversion(): void
     {
         $array = [

tests/Unit/Pages/Properties/EmailTest.php

@@ -17,13 +17,27 @@ public function test_create(): void
         $this->assertEquals("[email protected]", $email->email);
     }
 
+    public function test_create_empty(): void
+    {
+        $email = Email::createEmpty();
+
+        $this->assertTrue($email->isEmpty());
+    }
+
     public function test_change_email(): void
     {
         $email = Email::create("[email protected]")->changeEmail("[email protected]");
 
         $this->assertEquals("[email protected]", $email->email);
     }
 
+    public function test_clear(): void
+    {
+        $email = Email::create("[email protected]")->clear();
+
+        $this->assertTrue($email->isEmpty());
+    }
+
     public function test_array_conversion(): void
     {
         $array = [

tests/Unit/Pages/Properties/NumberTest.php

@@ -12,11 +12,18 @@ class NumberTest extends TestCase
 {
     public function test_create(): void
     {
-        $text = Number::create(123);
+        $number = Number::create(123);
 
-        $this->assertEquals(123, $text->number);
-        $this->assertEquals("", $text->metadata()->id);
-        $this->assertEquals(PropertyType::Number, $text->metadata()->type);
+        $this->assertEquals(123, $number->number);
+        $this->assertEquals("", $number->metadata()->id);
+        $this->assertEquals(PropertyType::Number, $number->metadata()->type);
+    }
+
+    public function test_create_empty(): void
+    {
+        $number = Number::createEmpty();
+
+        $this->assertTrue($number->isEmpty());
     }
 
     public function test_array_conversion(): void
@@ -27,17 +34,24 @@ public function test_array_conversion(): void
             "number" => 123,
         ];
 
-        $text = Number::fromArray($array);
+        $number = Number::fromArray($array);
         $fromFactory = PropertyFactory::fromArray($array);
 
-        $this->assertEquals($array, $text->toArray());
+        $this->assertEquals($array, $number->toArray());
         $this->assertEquals($array, $fromFactory->toArray());
     }
 
     public function test_change_value(): void
     {
-        $text = Number::create(123)->changeNumber(0.25);
-        $this->assertEquals(0.25, $text->number);
+        $number = Number::create(123)->changeNumber(0.25);
+        $this->assertEquals(0.25, $number->number);
+    }
+
+    public function test_clear(): void
+    {
+        $number = Number::create(123)->clear();
+
+        $this->assertTrue($number->isEmpty());
     }
 
     public function test_is_empty(): void
@@ -48,8 +62,8 @@ public function test_is_empty(): void
             "number" => null,
         ];
 
-        $text = Number::fromArray($array);
+        $number = Number::fromArray($array);
 
-        $this->assertTrue($text->isEmpty());
+        $this->assertTrue($number->isEmpty());
     }
 }