Merge pull request #28 from jacksleight/v3

Author: jacksleight

.gitignore

@@ -3,4 +3,5 @@ composer.lock
 vendor
 node_modules
 .phpunit.result.cache
-vite.hot
+vite.hot
+.phpunit.cache/test-results

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 3.0.0 (2024-09-03)
+
+This release introduces some significant changes to the terminology and variables used in mutators, however there are only two very small breaking changes, please read [upgrade guide](https://jacksleight.dev/docs/bard-mutator/upgrade-2-0-to-3-0) for more information.
+
+- [new] Mutators are now known as plugins
+- [new] Class based plugins for easier organisation and reuse
+- [new] Scoped plugins that can be enabled per-field
+- [new] New helpers and metadata for advanced data manipulation
+- Easier setup with no custom editor class binding
+- Better indexing of parent and sibling items
+- More flexible type name handling
+- Statamic 5.0+ is now required
+
 ## 2.3.1 (2024-05-07)
 
 - Statamic 5 support

README.md

@@ -30,9 +30,9 @@ Mutator::html('link', function ($value) {
 use Illuminate\Support\Str;
 use JackSleight\StatamicBardMutator\Facades\Mutator;
 
-Mutator::html('heading', function ($value, $data) {
-    if ($data->attrs->level === 2) {
-        $value[1]['id'] = Str::slug(collect($data->content)->implode('text', ''));
+Mutator::html('heading', function ($value, $item) {
+    if ($item->attrs->level === 2) {
+        $value[1]['id'] = Str::slug(collect($item->content)->implode('text', ''));
     }
     return $value;
 });

composer.json

@@ -22,12 +22,12 @@
         }
     },
     "require": {
-        "statamic/cms": "^3.4|^4.0|^5.0"
+        "statamic/cms": "^5.0"
     },
     "require-dev": {
-        "nunomaduro/collision": "^6.2",
-        "orchestra/testbench": "^7.5",
-        "pestphp/pest": "^1.0"
+        "nunomaduro/collision": "^8.1",
+        "orchestra/testbench": "^9.2",
+        "pestphp/pest": "^2.0"
     },
     "config": {
         "allow-plugins": {

docs/data-formats.md

@@ -1,17 +1,17 @@
 ---
-title: Data Formats
+title: Formats
 order: 7
 ---
 
-# Data Formats
+# Formats
 
 [TOC]
 
 ---
 
-## Node Data
+## Nodes
 
-Nodes mostly map to block elements in the rendered HTML. They're used for things like paragraphs, headings and lists. Node data looks like this:
+Nodes mostly map to block elements in the rendered HTML. They're used for things like paragraphs, headings and lists. Nodes  look like this:
 
 ```yaml
 -
@@ -35,7 +35,7 @@ Each node is an object with the following properties:
 
 ---
 
-## Mark Data
+## Marks
 
 Marks mostly map to inline elements in the rendered HTML. They're used for things like links, bold, and italic text. Marks are not nested in the same way they are in HTML. Instead they're applied to a node in a flat list. For example, a bold link is a text node with marks that look like this:
 

docs/examples.md

@@ -41,9 +41,9 @@ Mutator::html('link', function ($value) {
 ```php
 use JackSleight\StatamicBardMutator\Facades\Mutator;
 
-Mutator::html('heading', function ($value, $data) {
-    if ($data->attrs->level === 2) {
-        $value[1]['id'] = str_slug(collect($data->content)->implode('text', ''));
+Mutator::html('heading', function ($value, $item) {
+    if ($item->attrs->level === 2) {
+        $value[1]['id'] = str_slug(collect($item->content)->implode('text', ''));
     }
     return $value;
 });
@@ -68,8 +68,8 @@ Mutator::html('table', function ($value) {
 ```php
 use JackSleight\StatamicBardMutator\Facades\Mutator;
 
-Mutator::html('listItem', function ($value, $meta) {
-    if ($meta['parent']->type === 'bulletList') {
+Mutator::html('listItem', function ($value, $info) {
+    if ($info->parent->type === 'bulletList') {
         $value[2] = ['span', [], 0];
     }
     return $value;
@@ -108,8 +108,8 @@ Mutator::html('image', function ($value) {
 ```php
 use JackSleight\StatamicBardMutator\Facades\Mutator;
 
-Mutator::html('paragraph', function ($value, $meta) {
-    if (($meta['parent']->type ?? null) === 'listItem') {
+Mutator::html('paragraph', function ($value, $info) {
+    if (($info->parent->type ?? null) === 'listItem') {
         return null;
     }
     return $value;
@@ -121,8 +121,8 @@ Mutator::html('paragraph', function ($value, $meta) {
 ```php
 use JackSleight\StatamicBardMutator\Facades\Mutator;
 
-Mutator::html('paragraph', function ($value, $data) {
-    if (($data->content[0]->type ?? null) === 'image') {
+Mutator::html('paragraph', function ($value, $item) {
+    if (($item->content[0]->type ?? null) === 'image') {
         return null;
     }
     return $value;
@@ -134,8 +134,8 @@ Mutator::html('paragraph', function ($value, $data) {
 ```php
 use JackSleight\StatamicBardMutator\Facades\Mutator;
 
-Mutator::html('heading', function ($value, $data) {
-    $slug = str_slug(collect($data->content)->implode('text', ''));
+Mutator::html('heading', function ($value, $item) {
+    $slug = str_slug(collect($item->content)->implode('text', ''));
     $value[2] = ['a', [
         'id' => $slug,
         'href' => '#'.$slug,
@@ -145,6 +145,21 @@ Mutator::html('heading', function ($value, $data) {
 });
 ```
 
+### Obfuscate email address link values
+
+```php
+use JackSleight\StatamicBardMutator\Facades\Mutator;
+
+Mutator::html('link', function ($value, $item) use (&$obfuscated) {
+    if (Str::startsWith($item->attrs->href, 'mailto:')) {
+        $obfuscated = Statamic::modify(Str::after($item->attrs->href, 'mailto:'))->obfuscateEmail();
+        $value[1]['href'] = 'mailto:'.$obfuscated;
+    }
+
+    return $value;
+});
+```
+
 ## Data Mutators
 
 ### Add permalink anchors before all heading text
@@ -153,15 +168,29 @@ Mutator::html('heading', function ($value, $data) {
 use JackSleight\StatamicBardMutator\Facades\Mutator;
 use JackSleight\StatamicBardMutator\Support\Data;
 
-Mutator::data('heading', function ($data) {
-    $slug = str_slug(collect($data->content)->implode('text', ''));
+Mutator::data('heading', function ($item) {
+    $slug = str_slug(collect($item->content)->implode('text', ''));
     array_unshift(
-        $data->content,
+        $item->content,
         Data::html('<a id="'.$slug.'" href="#'.$slug.'">#</a>')
     );
 });
 ```
 
+### Convert blockquotes to figures with figcaptions
+
+```php
+use JackSleight\StatamicBardMutator\Facades\Mutator;
+use JackSleight\StatamicBardMutator\Support\Data;
+
+Mutator::data('blockquote', function ($data) {
+    Data::morph($data, Data::html('figure', ['class' => 'quote'], [
+        Data::clone($data, content: collect($data->content)->slice(0, -1)->values()->all()),
+        Data::html('figcaption', [], [collect($data->content)->last()]),
+    ]));
+});
+```
+
 Check out the modifier [example below](examples#using-with-the-bard-modifiers) to see how you could use these in a table of contents.
 
 ## Using with the Bard modifiers

docs/helpers.md

@@ -25,6 +25,18 @@ Creates a new mark object.
 
 Creates a new text node object.
 
-### `Data::html($html)`
+### `Data::html($html|$tag, $attrs = [], $content = [])`
 
-Creates a new HTML node object.
+Creates a new HTML node object.
+
+### `Data::apply($item, ...$properties)`
+
+Apply new properties to an existing node/mark.
+
+### `Data::clone($item, ...$properties)`
+
+Clone an existing node/mark and optionally apply new properties to it.
+
+### `Data::morph($item, $into)`
+
+Morph an existing node/mark into a different node/mark.

docs/index.md

@@ -11,11 +11,11 @@ This Statamic addon allows you to modify the data and tags rendered by the Bard
 
 This is how Tiptap (the magic behind Bard's content format and rendering) handles the rendering process, and how Bard Mutator interacts with that process:
 
-1. The raw content is stored as a ProseMirror document in your entries, these documents consist of [nodes and marks](data-formats)
+1. The raw content is stored as a ProseMirror document in your entries, these documents consist of [nodes and marks](formats)
 2. Statamic's augmentation process passes this data to the Tiptap renderer
-3. **Bard Mutator's [data mutators](mutators#data-mutators) jump in here, allowing you to modify the raw data**
-4. Tiptap converts the raw node and mark data to their standard [tag values](data-formats#html-values)
-5. **Bard Mutator's [HTML mutators](mutators#html-mutators) jump in here, allowing you to modify the tag values**
+3. **Bard Mutator's [data plugins](plugins#data-plugins) jump in here, allowing you to modify the raw data**
+4. Tiptap converts the raw node and mark data to their standard [tag values](formats#html-values)
+5. **Bard Mutator's [HTML plugins](plugins#html-plugins) jump in here, allowing you to modify the tag values**
 6. Tiptap renders the tag values to an HTML string
 
 ## Compatibility

docs/installation.md

@@ -9,17 +9,4 @@ You can search for this addon in the `Tools > Addons` section of the Statamic co
 
 ```bash
 composer require jacksleight/statamic-bard-mutator
-```
-
-## Enabling Advanced Features
-
-Advanced features such as [data mutators](mutators#data-mutators) and [metadata](mutators#metadata) require deeper access to Tiptap's rendering process, which isn't avaliable by default. Bard Mutator includes an extended Tiptap Editor class that makes this access possible. To enable these features simply bind the Bard Mutator Editor class in your app service providers `register()` method:
-
-```php
-$this->app->bind(
-    \Tiptap\Editor::class,
-    \JackSleight\StatamicBardMutator\Editor::class
-);
-```
-
-If you don't want to use those features you don't need to do this, all other features work without it.
+```