Merge branch 'main' into develop

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [3.0.1] - 2024-10-13
+
+- Add GraphQL type descriptions
+
+## [3.0.0] - 2024-10-13
+
+- Add GraphQL subfields for `type`, `hash` and `uri`
+- Breaking change only when using GraphQL
+
 ## [2.1.1] - 2024-07-23
 
 - Reduce addon style specificity
@@ -42,6 +51,9 @@
 
 - Initial release
 
+[3.0.1]: https://github.com/daun/statamic-placeholders/releases/tag/3.0.1
+[3.0.0]: https://github.com/daun/statamic-placeholders/releases/tag/3.0.0
+[2.1.1]: https://github.com/daun/statamic-placeholders/releases/tag/2.1.1
 [2.1.0]: https://github.com/daun/statamic-placeholders/releases/tag/2.1.0
 [2.0.5]: https://github.com/daun/statamic-placeholders/releases/tag/2.0.5
 [2.0.4]: https://github.com/daun/statamic-placeholders/releases/tag/2.0.4

DOCUMENTATION.md

@@ -207,6 +207,41 @@ Inside an Antlers template, you can use the `placeholder:*` tags with urls as we
 {{ placeholder:uri url="https://i.vimeocdn.com/video/158115405_640.jpg" }}
 ```
 
+## GraphQL
+
+Placeholder fields can be queried via GraphQL. Each field provides three subfields for the `type` of
+placeholder, the placeholder `hash` and the ready-to-use image data `uri`.
+
+You can query the data uri directly to insert into each image src attribute, adding around 1-2KB of
+payload for each image. That's fine in most cases, but when you're dealing with hundreds of images
+you might want to only fetch the much smaller placeholder `hash` and generate the image data uri on
+the frontend to save on bandwith. You'll need to integrate the official npm packages
+[thumbhash](https://www.npmjs.com/package/thumbhash) or [blurhash](https://www.npmjs.com/package/blurhash)
+yourself in that case.
+
+### Query placeholder data uri
+
+```graphql
+... on Asset_Assets {
+  alt
+  lqip {
+    uri
+  }
+}
+```
+
+### Query placeholder hash
+
+```graphql
+... on Asset_Assets {
+  alt
+  lqip {
+    type
+    hash
+  }
+}
+```
+
 ## Queueing
 
 If your site is configured to use queues, the placeholders will also be generated asynchronously

src/Fieldtypes/PlaceholderFieldtype.php

@@ -4,10 +4,12 @@
 
 use Daun\StatamicPlaceholders\Data\AssetPlaceholder;
 use Daun\StatamicPlaceholders\Facades\Placeholders;
+use Daun\StatamicPlaceholders\GraphQL\AssetPlaceholderType;
 use Daun\StatamicPlaceholders\Jobs\GeneratePlaceholderJob;
 use Daun\StatamicPlaceholders\Support\PlaceholderField;
 use Illuminate\Support\Number;
 use Statamic\Assets\Asset;
+use Statamic\Facades\GraphQL;
 use Statamic\Fields\Fieldtype;
 
 class PlaceholderFieldtype extends Fieldtype
@@ -113,4 +115,14 @@ public function augment($value)
             return $value;
         }
     }
+
+    public function toGqlType()
+    {
+        return GraphQL::type(AssetPlaceholderType::NAME);
+    }
+
+    public function addGqlTypes()
+    {
+        GraphQL::addType(AssetPlaceholderType::class);
+    }
 }

src/GraphQL/AssetPlaceholderType.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Daun\StatamicPlaceholders\GraphQL;
+
+use Daun\StatamicPlaceholders\Data\AssetPlaceholder;
+use Statamic\Facades\GraphQL;
+
+class AssetPlaceholderType extends \Rebing\GraphQL\Support\Type
+{
+    const NAME = 'AssetPlaceholder';
+
+    protected $attributes = [
+        'name' => self::NAME,
+        'description' => 'Low-quality image placeholder (LQIP)',
+    ];
+
+    public function fields(): array
+    {
+        return [
+            'type' => [
+                'type' => GraphQL::string(),
+                'resolve' => fn (AssetPlaceholder $item) => $item->augmentedValue('type'),
+                'description' => 'Type of placeholder used, e.g. thumbhash or blurhash',
+            ],
+            'hash' => [
+                'type' => GraphQL::string(),
+                'resolve' => fn (AssetPlaceholder $item) => $item->augmentedValue('hash'),
+                'description' => 'Short textual representation of the image',
+            ],
+            'uri' => [
+                'type' => GraphQL::string(),
+                'resolve' => fn (AssetPlaceholder $item) => $item->augmentedValue('uri'),
+                'description' => 'Ready-to-use data URI of the placeholder image',
+            ],
+        ];
+    }
+}