- Some more work done on documentation and fixed some code at PHP 8 level

docs/00-intro.md

@@ -5,3 +5,123 @@ Welcome to the `picea-ui` documentation.
 This quick documentation will guide you through the use of the form system, every available
 UI elements and how to add customs one and individual components.
  
+Mostly everything you need to build and process form is available in this package.
+
+The first part is most input callable as a widget :
+
+```
+{% ui.text "fullname", "John Doe" %}
+```
+
+Current input support is :
+```php
+- Input (string $source, array $attributes = [], array $options = []) 
+- Checkbox (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Color (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Date (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Datetime (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Email (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- File (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Hidden (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Image (string $source, array $attributes = [], array $options = []) 
+- Numeric (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Password (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Radio (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Range (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Search (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Select (string $name, array $list, mixed $value = null, array $attributes = [], bool $strictComparison = true)
+- Tel (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Text (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Textarea (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Time (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Url (string $name, mixed $value = null, array $attributes = [], array $options = [])
+- Week (string $name, mixed $value = null, array $attributes = [], array $options = [])
+```
+
+**[PICEA]** So, using this code:
+
+```html
+{% ui.form.post "user.save", current_url() %}
+    <div class="field fullname">
+        <label>Full name</label>
+        {% ui.text "fullname", $user->fullname, [ 'required' => 'required' ] %}
+    </div>
+    
+    <div class="field email">
+        <label>Email address</label>
+        {% ui.text "email", $user->email %}
+    </div>
+
+    <div class="field job">
+        <label>Have a job</label>
+        <label>{% ui.radio "job", 'yes', [], [ 'value' => $entity->job ] %} Yes</label>
+        <label>{% ui.radio "job", 'no', [], [ 'value' => $entity->job ] %} No</label>
+    </div>
+    
+    <div class="field role">
+        <label>Role</label>
+        {% ui.select "role", [ 'user' => "User", 'moderator' => "Moderator", 'admin' => "Admin" ], $user->role, [ 'required' => 'required' ] %}
+    </div>
+
+    <button type="submit">Save</button>
+{% ui.endform %}
+```
+
+**[HTML]** Would render as such:
+
+```html
+<form class="ui-form" method="post" action="http://127.0.0.1/" enctype="multipart/form-data">
+    <input class="ui-hidden" type="hidden" name="picea-ui-form[user.save]" value="617fb40f1999db63fbd0b4f680a77750">
+    
+    <div class="field fullname">
+        <label>Full name</label>
+        <input class="ui-text" type="text" value="" name="fullname" required="required">        
+    </div>
+
+    <div class="field email">
+        <label>Email address</label>
+        <input class="ui-text" type="text" value="" name="email">        
+    </div>
+
+    <div class="field job">
+        <label>Have a job</label>
+        <label><input class="ui-radio" type="radio" value="yes" name="job"> Yes</label>
+        <label><input class="ui-radio" type="radio" value="no" name="job"> No</label>
+    </div>
+
+    <div class="field role">
+        <label>Role</label>
+        <select class="ui-select" name="role" required="required">
+            <option value="user">User</option>
+            <option value="moderator">Moderator</option>
+            <option value="admin">Admin</option>
+        </select>        
+    </div>
+
+    <button type="submit">Save</button>
+</form>
+```
+
+## Use your forms in controller
+
+Forms can be used to handle how your data is handled, from loading (get) to processing (post).
+
+The process is as simple as defining a Form, implementing FormInterface :
+
+```php
+interface FormInterface
+{
+    public function initialize(FormContextInterface $context) : void;
+
+    public function validate(FormContextInterface $context) : bool;
+    
+    public function execute(FormContextInterface $context);
+}
+```
+
+`initialize` is called directly on `form()` method call. 
+
+`validate` will be called if the request's method is either `post`, `put`, `patch` or `delete`, which implies **adding** / **editing** / **deleting**.
+
+`execute` will finally launch only if `validate` returns `true`. This is usually where you want to **save** / **destroy** your entities.
+