Add a new simplified image front matter schema

Author: emmadesilva

packages/framework/resources/views/components/post/image.blade.php

@@ -6,6 +6,10 @@
 <figure aria-label="Cover image" itemprop="image" itemscope itemtype="https://schema.org/ImageObject" role="doc-cover">
     <img src="{{ $image->getSource() }}" alt="{{ $image->getAltText() ?? '' }}" title="{{ $image->getTitleText() ?? '' }}" itemprop="image" class="mb-0">
     <figcaption aria-label="Image caption" itemprop="caption">
+        @if($image->hasCaption())
+            <span>{{ $image->getCaption() }}</span>
+        @endif
+
         @if($image->hasAuthorName())
             <span>Image by</span>
             <span itemprop="creator" itemscope="" itemtype="https://schema.org/Person">

packages/framework/src/Framework/Factories/FeaturedImageFactory.php

@@ -28,23 +28,25 @@ class FeaturedImageFactory extends Concerns\PageDataFactory implements FeaturedI
     protected readonly ?string $copyrightText;
     protected readonly ?string $licenseName;
     protected readonly ?string $licenseUrl;
+    protected readonly ?string $caption;
 
     public function __construct(
         private readonly FrontMatter $matter,
         private readonly ?string $filePath = null,
     ) {
         $this->source = $this->makeSource();
-        $this->altText = $this->getStringMatter('image.altText');
+        $this->altText = $this->getStringMatter('image.altText') ?? $this->getStringMatter('image.alt');
         $this->titleText = $this->getStringMatter('image.titleText');
         $this->authorName = $this->getStringMatter('image.authorName');
         $this->authorUrl = $this->getStringMatter('image.authorUrl');
         $this->copyrightText = $this->getStringMatter('image.copyright');
         $this->licenseName = $this->getStringMatter('image.licenseName');
         $this->licenseUrl = $this->getStringMatter('image.licenseUrl');
+        $this->caption = $this->getStringMatter('image.caption');
     }
 
     /**
-     * @return array{source: string, altText: string|null, titleText: string|null, authorName: string|null, authorUrl: string|null, copyrightText: string|null, licenseName: string|null, licenseUrl: string|null}
+     * @return array{source: string, altText: string|null, titleText: string|null, authorName: string|null, authorUrl: string|null, copyrightText: string|null, licenseName: string|null, licenseUrl: string|null, caption: string|null}
      */
     public function toArray(): array
     {
@@ -57,6 +59,7 @@ public function toArray(): array
             'copyrightText' => $this->copyrightText,
             'licenseName' => $this->licenseName,
             'licenseUrl' => $this->licenseUrl,
+            'caption' => $this->caption,
         ];
     }
 

packages/framework/src/Framework/Features/Blogging/Models/FeaturedImage.php

@@ -58,7 +58,8 @@ public function __construct(
         protected readonly ?string $authorUrl = null,
         protected readonly ?string $licenseName = null,
         protected readonly ?string $licenseUrl = null,
-        protected readonly ?string $copyrightText = null
+        protected readonly ?string $copyrightText = null,
+        protected readonly ?string $caption = null
     ) {
         $this->type = Hyperlinks::isRemote($source) ? self::TYPE_REMOTE : self::TYPE_LOCAL;
         $this->source = $this->setSource($source);
@@ -127,6 +128,10 @@ public function getMetadataArray(): array
             $metadata['name'] = $this->getTitleText();
         }
 
+        if ($this->hasCaption()) {
+            $metadata['caption'] = $this->getCaption();
+        }
+
         $metadata['url'] = $this->getSource();
         $metadata['contentUrl'] = $this->getSource();
 
@@ -135,7 +140,7 @@ public function getMetadataArray(): array
 
     public function getAltText(): ?string
     {
-        return $this->altText;
+        return $this->altText ?? $this->caption;
     }
 
     public function getTitleText(): ?string
@@ -168,6 +173,11 @@ public function getLicenseUrl(): ?string
         return $this->licenseUrl;
     }
 
+    public function getCaption(): ?string
+    {
+        return $this->caption;
+    }
+
     public function hasAltText(): bool
     {
         return $this->has('altText');
@@ -203,6 +213,11 @@ public function hasLicenseUrl(): bool
         return $this->has('licenseUrl');
     }
 
+    public function hasCaption(): bool
+    {
+        return $this->has('caption');
+    }
+
     protected function has(string $property): bool
     {
         return $this->$property !== null;

packages/framework/src/Markdown/Contracts/FrontMatter/SubSchemas/FeaturedImageSchema.php

@@ -14,8 +14,10 @@ interface FeaturedImageSchema extends BlogPostSchema
 {
     public const FEATURED_IMAGE_SCHEMA = [
         'source' => 'string', // Name of a file in _media/ or a remote URL (required)
-        'altText' => 'string', // The alt text (important for accessibility) // todo: Support alt, description
-        'titleText' => 'string', // The title text (hover tooltip & metadata) // todo: Support title, caption
+        'altText' => 'string', // The alt text (important for accessibility)
+        'alt' => 'string',     // Alternative to altText (simplified schema)
+        'titleText' => 'string', // The title text (hover tooltip & metadata)
+        'caption' => 'string', // The caption text (simplified schema)
         'licenseName' => 'string', // The name of the license (e.g. "CC BY 4.0")
         'licenseUrl' => 'string', // The URL of the license (e.g. "https://creativecommons.org/licenses/by/4.0/")
         'authorName' => 'string', // The name of the author/photographer of the image (e.g. "John Doe", Wikimedia Commons)

packages/framework/tests/Feature/FeaturedImageFactoryTest.php

@@ -47,6 +47,7 @@ public function testWithDataFromSchema()
             'copyrightText' => 'copyright',
             'licenseName' => 'license',
             'licenseUrl' => 'licenseUrl',
+            'caption' => null,
         ];
 
         $factory = new FeaturedImageFactory(new FrontMatter($array));
@@ -146,6 +147,43 @@ public function testImagePathsWithCacheBusting()
         $this->assertSourceIsSame('media/foo?v=00000000', ['image' => ['source' => '_media/foo']]);
     }
 
+    public function testSupportsSimplifiedImageSchema()
+    {
+        $array = [
+            'image' => [
+                'source' => 'source',
+                'alt' => 'Alternative text',
+                'caption' => 'Static website from GitHub Readme',
+            ],
+        ];
+
+        $factory = new FeaturedImageFactory(new FrontMatter($array));
+        $image = FeaturedImageFactory::make(new FrontMatter($array));
+
+        $this->assertSame('source', $factory->toArray()['source']);
+        $this->assertSame('Alternative text', $factory->toArray()['altText']);
+        $this->assertSame('Static website from GitHub Readme', $factory->toArray()['caption']);
+
+        $this->assertSame('Alternative text', $image->getAltText());
+        $this->assertSame('Static website from GitHub Readme', $image->getCaption());
+    }
+
+    public function testFallsBackToCaptionWhenAltIsMissing()
+    {
+        $array = [
+            'image' => [
+                'source' => 'source',
+                'caption' => 'This caption should be used as alt text',
+            ],
+        ];
+
+        $image = FeaturedImageFactory::make(new FrontMatter($array));
+
+        $this->assertFalse($image->hasAltText());
+        $this->assertSame('This caption should be used as alt text', $image->getAltText());
+        $this->assertSame('This caption should be used as alt text', $image->getCaption());
+    }
+
     protected function makeFromArray(array $matter): FeaturedImage
     {
         return FeaturedImageFactory::make(new FrontMatter($matter));

packages/framework/tests/Feature/FeaturedImageTest.php

@@ -41,6 +41,15 @@ public function testGetMetadataArray()
             'contentUrl' => 'media/source',
         ], (new FilledImage)->getMetadataArray());
 
+        // Test with caption
+        $this->assertSame([
+            'text' => 'alt',
+            'name' => 'title',
+            'caption' => 'This is a caption',
+            'url' => 'media/source',
+            'contentUrl' => 'media/source',
+        ], (new FeaturedImage('source', 'alt', 'title', null, null, null, null, null, 'This is a caption'))->getMetadataArray());
+
         $this->assertSame([
             'url' => 'media/source',
             'contentUrl' => 'media/source',

packages/framework/tests/Unit/SchemaContractsTest.php

@@ -69,7 +69,9 @@ public function testSchemasAreNotAccidentallyChanged()
         $this->assertSame([
             'source' => 'string',
             'altText' => 'string',
+            'alt' => 'string',
             'titleText' => 'string',
+            'caption' => 'string',
             'licenseName' => 'string',
             'licenseUrl' => 'string',
             'authorName' => 'string',

packages/framework/tests/Unit/Views/FeaturedImageViewTest.php

@@ -273,6 +273,51 @@ public function testImagePathNormalization()
         $this->assertStringContainsString('src="custom_media/bar.png"', $component);
     }
 
+    public function testCaptionIsRenderedWhenPresent()
+    {
+        $component = $this->renderComponent([
+            'image.source' => 'foo.jpg',
+            'image.caption' => 'This is a caption for the image',
+            'image.altText' => 'Alt text for the image',
+        ]);
+
+        $this->assertStringContainsString('This is a caption for the image', $component);
+        $this->assertStringContainsString('alt="Alt text for the image"', $component);
+    }
+
+    public function testAltTextFallsBackToCaptionWhenMissing()
+    {
+        $component = $this->renderComponent([
+            'image.source' => 'foo.jpg',
+            'image.caption' => 'This caption is used as alt text',
+        ]);
+
+        $this->assertStringContainsString('This caption is used as alt text', $component);
+        $this->assertStringContainsString('alt="This caption is used as alt text"', $component);
+    }
+
+    public function testSupportsSimplifiedImageSchema()
+    {
+        $this->file('_media/simple.jpg', 'test content');
+
+        $image = new FeaturedImage(
+            'simple.jpg',
+            null, // altText
+            null, // titleText
+            null, // authorName
+            null, // authorUrl
+            null, // licenseName
+            null, // licenseUrl
+            null, // copyrightText
+            'Static website from GitHub Readme' // caption
+        );
+
+        $component = $this->renderComponent($image);
+
+        $this->assertStringContainsString('Static website from GitHub Readme', $component);
+        $this->assertStringContainsString('alt="Static website from GitHub Readme"', $component);
+    }
+
     protected function stripHtml(string $string): string
     {
         return trim($this->stripWhitespace(strip_tags($string)), "\t ");