Quick updates on docs, since Livewire v3 a lot of thing changed 😬 (#97)

* quick updates on docs, since Livewire v3 a lot of thing changed
* more details
* Update docs/livewire.md

Co-authored-by: qwerty287 <[email protected]>

Author: ildyria

docs/livewire.md

@@ -1,21 +1,21 @@
 ## A brief introduction to Livewire
 
-We first give a short intuition of how Livewire, the framework of the new front-end, works.
+We first give a short intuition of how [Livewire](https://livewire.laravel.com/docs/quickstart), the framework of the new front-end, works.
 
 ### Livewire and Controllers
 
 The Laravel framework on which Lychee is based provides two options regarding how a request may be routed:
 
 - the request is directed to a controller below `app/Http/Controllers`
-- the request is directed to a Livewire component below `app/Http/Livewire`
+- the request is directed to a Livewire component below `app/Livewire/Components`
 
 In the first case, a controller returns a JSON object or an HTML page rendered from a blade template.
 In the second case (Livewire), only a block of HTML built from a blade template will be returned.
 
 From a very high level, Livewire makes use of two folders:
 
-- `app/Http/Livewire` which hosts the components and their inner logic.
-- `resources/views/components` which hosts the HTML layout of the components.
+- `app/Livewire/Components` which hosts the components and their inner logic.
+- `resources/views/{components|livewire}` which hosts the HTML layout of the components.
 
 So far one could say there is not much difference with a normal request life cycle. Where Livewire starts to shine is in the ability to call the methods of the component directly _from HTML_. Instead of having to use a JavaScript hook, make an AJAX call, parse the result, and update the layout accordingly, the user/programmer can directly interact with the designated component and Livewire takes care of the request and rendering.
 
@@ -37,7 +37,7 @@ Laravel then calls the `render()` method and returns the corresponding view.
 ```php
 public function render()
 {
-	return view('components.molecules.album');
+	return view('components.gallery.album');
 }
 
 ```
@@ -57,9 +57,9 @@ One could say that the Livewire components are just Laravel components on steroi
 
 In order to call Livewire, the following syntax is used:
 ```html
-<livewire:sidebar.album :album="$this->album" />
+<livewire:pages.gallery.album :album="$this->album" />
 ```
-This will call the Livewire component located at `app/Http/Livewire/Sidebar/Album.php`.  
+This will call the Livewire component located at `app/Livewire/Components/Pages/Gallery/Album.php`.  
 As opposed to their Laravel counterparts, it is not possible to use the constructor to read the attributes.
 For this reason a method `mount()` has been added:
 ```php
@@ -72,16 +72,16 @@ Then the `render()` function is used in order to retrieve the respective HTML se
 ```php
 public function render()
 {
-	return view('livewire.sidebar.album');
+	return view('livewire.pages.gallery.album');
 }
 ```
 
 #### Calling methods
 
 Where Livewire becomes interesting is in its ability to call PHP functions directly from user-land.
 Methods of the component can be callable by using additional HTML attributes.
-For example in `resources/views/livewire/components/modules/album.php` the attribute `wire:click="login"`
-will call the `login()` method of the component `app/Http/Livewire/Header.php`
+For example in `resources/views/livewire/pages/gallery/albums.php` the attribute `wire:click="login"`
+will call the `login()` method of the component `app/Livewire/Pages/Gallery/Album.php`
 ```html
 <a wire:click="login" class="button">
 	<x-icons.iconic icon='account-login' />
@@ -100,80 +100,41 @@ This method will then execute and trigger a re-rendering of the component.
 In addition to calling a method of a component,
 it is also possible to trigger actions in other components.
 As a matter of fact, in the specific case of the `login()` method,
-we are emitting an event which will trigger the opening of the `app/Http/Livewire/Components/Modal.php` component with a login form:
+we are emitting an event which will trigger the opening of the `app/Livewire/Components/Base/Modal.php` component with a login form:
 ```php
 protected function login()
 {
 	$form = 'forms.login';
 	$params = [];
-	$this->emitTo('components.modal', 'openModal', $form, $params);
+	$this->dispatch('openModal', $form, $params)->to(Modal::class);
 }
 ```
 `Modal.php` contains the following code:
 ```php
 class Modal extends Openable
 {
-	protected $listeners = [
-		'openModal',
-		// ...
-	];
-
+	#[On('openModal')]
 	public function openModal(string $type, array $params = [])
 	{
 		//...
 	}
 ```
-The protected variable `$listeners` informs the component which events it needs to react to.
-In this specific case `openModal()` method has two arguments which are provided by the `$this->emitTo('componentName', 'eventName', $arg1, $arg2);`
+The attribute `#[On('event-name')]` informs the component which events it needs to react to.
+In this specific case `openModal()` method has two arguments which are provided by the `$this->dispatch('eventName', $arg1, $arg2);`
 
 With these tools at hand, we are now able to understand a bit better the structure of the Livewire front-end.
 
 ## Lychee Livewire Front-end
 
-A high-level view is presented in the following picture (at the time of writing, open full image for better view).
-
-<!-- [![](img/Livewire Class Diagram.jpg)](img/Livewire Class Diagram.jpg) -->
-[![](img/Livewire-component-diagram.png)](img/Livewire-component-diagram.png)
-
-For now the entry point is always `app/Http/Livewire/Pages/Fullpage.php`.
-The path of the code is the following:
-
-1. Calls `app/Http/Livewire/Pages/Fullpage.php`
-2. Loads:
-	- the `Top` level,
-	- or the requested `Album` and children,
-	- or the requested `Album` and requested `Photo`
-3. Renders `resources/views/livewire/pages/fullpage.blade.php`
-4. Calls:
-	-  `app/Http/Livewire/Component/Header.php`
-	- and one of the `$module`
-		- `app/Http/Livewire/Modules/Albums.php`  
-		- or `app/Http/Livewire/Modules/Album.php`  
-		and `app/Http/Livewire/Components/Sidebar.php`
-		- or `app/Http/Livewire/Modules/Photo.php`  
-		and `app/Http/Livewire/Components/Sidebar.php`
-5. Renders `resources/views/livewire/components/header.blade.php`
-	and calls the header layout corresponding to the current module selected:
-	- `resources/views/livewire/components/modules/albums.php`
-	- or `resources/views/livewire/components/modules/album.php`
-	- or `resources/views/livewire/components/modules/photo.php`
-6. Renders the module selected; in the case of 
-	`app/Http/Livewire/Modules/Photo.php` we also call the
-	`app/Http/Livewire/Components/PhotoOverlay.php`
-7. Renders the sidebar `app/Http/Livewire/Components/Sidebar.php`
-	which calls:
-	- `app/Http/Livewire/Sidebar/Album.php`
-	- or `app/Http/Livewire/Sidebar/Photo.php`
-8. At this point, you pretty much have the full picture...
-
-In summary:
-
-1. Load FullPage
-2. Load Header
-3. Load Module
-4. Load Sidebar
-
-Each step is basically bouncing between the PHP and the blade part.
+Since Livewire v3, the front-end uses a layout which is significantly close to a normal website.
+We make use of `navigate`. Read more [here](https://livewire.laravel.com/docs/navigate)
+
+Each page is now located in `App/Livewire/Components/Page` with the exception of the different gallery views which are in
+`App/Livewire/Components/Page/Gallery`.
+
+This makes use of a unified layout provided in `resources/views/components/layouts/app.blade.php`.
+
+**More info to come.**
 
 ## Pitfalls & Wireable
 
@@ -187,3 +148,12 @@ Do note that by default, the dehydration uses the `toArray()` method. As a resul
 For this reason Livewire proposes the interface `Wireable` which requires two methods: `toLivewire()` and `static fromLivewire($value)`.
 The former will return the serialized version of the object and the latter will rebuild the object from the serialized version.
 
+Another option is to use Synthesizers. Examples which take care of AbstractAlbums and Photos are in `App/Livewire/Synth`;
+
+## Front-end reactivity
+
+While Livewire provides decent interaction, sometimes we do not need round trips to the server to change the displayed data.
+For this reason we use [Alpine.js](https://alpinejs.dev/start-here) which is bundled with Livewire.
+
+Alpine provides convenient tools to improve reactivity such as `x-on`, `x-bind`, `x-data`, `x-show`, `x-init`, `x-cloak`.
+We advise the reader to familiarize themselves with those as they are also used in the frontend.