docs: document new conditionals, improve documentation structure

Author: julian-farbcode

docs/.vitepress/config.mts

@@ -46,6 +46,12 @@ export default defineConfig({
                     { text: 'Extending States', link: '/extending-states' },
                     { text: 'State Sharing', link: '/state-sharing' },
                 ]
+            },
+            {
+                text: 'Reference',
+                items: [
+                    { text: 'Available Conditional Methods', link: '/reference/conditional-methods' },
+                ]
             }
         ],
 

docs/pages/basic-usage.md

@@ -84,45 +84,6 @@ You can also use the string representation of states instead of enum cases:
 'name' => $this->unlessState('minimal', $this->full_name),
 ```
 
-## Available Conditional Methods
-
-The package provides several methods to conditionally include attributes:
-
-### `whenState`
-
-Include a value only when the current state matches the specified state:
-
-```php
-'email' => $this->whenState(State::Full, $this->email),
-'admin_notes' => $this->whenState(State::Full, $this->admin_notes, 'N/A'),
-```
-
-### `unlessState`
-
-Include a value unless the current state matches the specified state:
-
-```php
-'public_info' => $this->unlessState(State::Minimal, $this->public_information),
-```
-
-### `whenStateIn`
-
-Include a value when the current state is one of the specified states:
-
-```php
-'detailed_info' => $this->whenStateIn([State::Full, State::Table], [
-    'department' => $this->department,
-    'position' => $this->position,
-]),
-```
-
-### `unlessStateIn`
-
-Include a value unless the current state is one of the specified states:
-
-```php
-'sensitive_data' => $this->unlessStateIn([State::Minimal, State::Table], $this->sensitive_info),
-```
 
 ### Magic Conditionals
 
@@ -133,6 +94,8 @@ You can also use magic methods with for cleaner syntax:
 'name' => $this->unlessStateMinimal($this->full_name),
 ```
 
+For a full list of available conditional methods, see the [Available Conditional Methods](reference/conditional-methods.md) reference.
+
 ### Manual State Access
 
 If you need more complex logic than inline conditionals, you can access the resource's current state directly using the `getState()` method:

docs/pages/reference/conditional-methods.md

@@ -0,0 +1,110 @@
+# Available Conditional Methods
+
+The package provides several methods to conditionally include attributes in Stateful Resources.
+
+[[toc]]
+
+### `whenState`
+
+Include a value only when the current state matches the specified state:
+
+> 🪄 Magic method available
+
+```php
+'email' => $this->whenState(State::Full, $this->email),
+// or
+'email' => $this->whenStateFull($this->email),
+```
+
+### `unlessState`
+
+Include a value unless the current state matches the specified state:
+
+> 🪄 Magic method available
+
+```php
+'public_info' => $this->unlessState(State::Minimal, $this->public_information),
+// or
+'public_info' => $this->unlessStateMinimal($this->public_information),
+```
+
+### `whenStateIn`
+
+Include a value when the current state is one of the specified states:
+
+> No magic method available
+
+```php
+'detailed_info' => $this->whenStateIn([State::Full, State::Table], [
+    'department' => $this->department,
+    'position' => $this->position,
+]),
+```
+
+### `unlessStateIn`
+
+Include a value unless the current state is one of the specified states:
+
+> No magic method available
+
+```php
+'sensitive_data' => $this->unlessStateIn([State::Minimal, State::Table], $this->sensitive_info),
+```
+
+### `mergeWhenState`
+
+Merge an array of attributes when the current state matches the specified state:
+
+> 🪄 Magic method available
+
+```php
+$attributes = $this->mergeWhenState(State::Full, [
+    'email' => $this->email,
+    'phone' => $this->phone,
+]);
+// or
+$attributes = $this->mergeWhenStateFull([
+    'email' => $this->email,
+    'phone' => $this->phone,
+]);
+```
+
+### `mergeUnlessState`
+Merge an array of attributes unless the current state matches the specified state:
+
+> 🪄 Magic method available
+
+```php
+$attributes = $this->mergeUnlessState(State::Minimal, [
+    'email' => $this->email,
+    'phone' => $this->phone,
+]);
+// or
+$attributes = $this->mergeUnlessStateMinimal([
+    'email' => $this->email,
+    'phone' => $this->phone,
+]);
+```
+
+### `mergeWhenStateIn`
+Merge an array of attributes when the current state is one of the specified states:
+
+> No magic method available
+
+```php
+$attributes = $this->mergeWhenStateIn([State::Full, State::Table], [
+    'email' => $this->email,
+    'phone' => $this->phone,
+]);
+```
+### `mergeUnlessStateIn`
+Merge an array of attributes unless the current state is one of the specified states:
+
+> No magic method available
+
+```php
+$attributes = $this->mergeUnlessStateIn([State::Minimal, State::Table], [
+    'email' => $this->email,
+    'phone' => $this->phone,
+]);
+```