- Added documentation, fixed some bugs and optimized some parts of the source code while doing the doc.

docs/00-intro.md

@@ -0,0 +1,7 @@
+# Picea UI
+
+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.
+ 

docs/10-ui-checkbox.md

@@ -0,0 +1,13 @@
+# `ui.checkbox` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.radio` component, which itself extends `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-checkbox"` 
+- `'type' => "checkbox"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-checkbox" type="checkbox" value="$value" name="$name">
+```

docs/10-ui-color.md

@@ -0,0 +1,13 @@
+# `ui.color` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-color"` 
+- `'type' => "color"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-color" type="color" value="$value" name="$name">
+```

docs/10-ui-date.md

@@ -0,0 +1,13 @@
+# `ui.date` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-date"` 
+- `'type' => "date"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-date" type="date" value="$value" name="$name">
+```

docs/10-ui-datetime.md

@@ -0,0 +1,13 @@
+# `ui.datetime` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-datetime"` 
+- `'type' => "datetime-local"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-datetime" type="datetime-local" value="$value" name="$name">
+```

docs/10-ui-email.md

@@ -0,0 +1,13 @@
+# `ui.email` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-email"` 
+- `'type' => "email"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-email" type="email" value="" name="">
+```

docs/10-ui-file.md

@@ -0,0 +1,13 @@
+# `ui.file` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-file"` 
+- `'type' => "file"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-file" type="file" value="" name="">
+```

docs/10-ui-form.md

@@ -0,0 +1,18 @@
+# `ui.form` / `ui.form.get` / `ui.form.post` (string $method = "get", string $name = "", string $action = "", array $attributes = [])
+
+A version exists also for unsupported methods (as of HTML5) on forms `ui.form.put` / `ui.form.patch` / `ui.form.delete`, which
+could find a use within a Javascript environment.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-form"` 
+- `'enctype' => "multipart/form-data"`
+- `'method' => "get|post|put|patch|delete"`
+
+and will typically be rendered such as :
+
+```html
+<form class="ui-form" enctype="multipart/form-data" action="$action" method="$method">
+    <input class="ui-hidden" type="hidden" name="picea-ui-form[$name]" value="{ random md5 hash }">
+</form>
+```

docs/10-ui-hidden.md

@@ -0,0 +1,13 @@
+# `ui.hidden` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-hidden"` 
+- `'type' => "hidden"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-hidden" type="hidden" value="" name="">
+```

docs/10-ui-image.md

@@ -0,0 +1,12 @@
+# `ui.image` (string $source, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-image"` 
+
+and will typically be rendered such as :
+```html
+<img class="ui-image" src="$source">
+```

docs/10-ui-input.md

@@ -0,0 +1,13 @@
+# `ui.input` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+This is small
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-input"`
+
+and will typically be rendered such as :
+
+```html
+<input class="ui-input" type="input" value="$value" name="$name">
+```

docs/10-ui-numeric.md

@@ -0,0 +1,13 @@
+# `ui.numeric` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-numeric"` 
+- `'type' => "numeric"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-numeric" type="numeric" value="$value" name="$name">
+```

docs/10-ui-password.md

@@ -0,0 +1,13 @@
+# `ui.password` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-password"` 
+- `'type' => "password"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-password" type="password" value="$value" name="$name">
+```

docs/10-ui-radio.md

@@ -0,0 +1,13 @@
+# `ui.radio` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-radio"` 
+- `'type' => "radio"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-radio" type="radio" value="$value" name="$name">
+```

docs/10-ui-range.md

@@ -0,0 +1,13 @@
+# `ui.range` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-range"` 
+- `'type' => "range"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-range" type="range" value="$value" name="$name">
+```

docs/10-ui-search.md

@@ -0,0 +1,13 @@
+# `ui.search` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-search"` 
+- `'type' => "search"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-search" type="search" value="$value" name="$name">
+```

docs/10-ui-select.md

@@ -0,0 +1,13 @@
+# `ui.select` (string $name, array $list, $value = null, array $attributes = [], bool $strictComparison = true)
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-select"` 
+- `'type' => "select"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-select" type="select" value="$value" name="$name">
+```

docs/10-ui-tel.md

@@ -0,0 +1,13 @@
+# `ui.tel` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-tel"` 
+- `'type' => "tel"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-tel" type="tel" value="$value" name="$name">
+```

docs/10-ui-text.md

@@ -0,0 +1,13 @@
+# `ui.text` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-text"` 
+- `'type' => "text"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-text" type="text" value="$value" name="$name">
+```

docs/10-ui-textarea.md

@@ -0,0 +1,12 @@
+# `ui.textarea` / `ui.textarea.raw` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`. This extension also comes with a raw modifier which skips the escaping.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-textarea"`
+
+and will typically be rendered such as :
+```html
+<textarea class="ui-textarea" name="$name">$value</textarea>
+```

docs/10-ui-time.md

@@ -0,0 +1,13 @@
+# `ui.time` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-time"` 
+- `'type' => "time"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-time" type="time" value="$value" name="$name">
+```

docs/10-ui-url.md

@@ -0,0 +1,13 @@
+# `ui.url` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-url"` 
+- `'type' => "url"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-url" type="url" value="$value" name="$name">
+```

docs/10-ui-week.md

@@ -0,0 +1,13 @@
+# `ui.week` (string $name, mixed $value = null, array $attributes = [], array $options = [])
+
+Built on top of `ui.input`.
+
+The following attributes are assigned by this extension :
+
+- `'class' => "ui-week"` 
+- `'type' => "week"`
+
+and will typically be rendered such as :
+```html
+<input class="ui-week" type="week" value="$value" name="$name">
+```

docs/20-method-form.md

@@ -0,0 +1,107 @@
+# `form`(FormInterface $form, ? FormContext $formContext = null) : FormHandler
+
+The `form()` method will process a form in three steps :
+
+1. `initialize(FormContextInterface $context)` is first called on form processing.
+2. `validate(FormContextInterface $context) : bool` will execute on POST. If you define a name to the form, it will match the one found in the POST (`picea-ui-form[$context->name]`) ; if the form is not the target, it will be skipped. Also, if an error si found within the message list, the method will return `false`.
+3. `execute(FormContextInterface $context)` is the last method to run, which is usually where you save your entity and finilize your messages. The return value is accessible from the `formHandler` which `form()` returns.
+
+**[PHP]** So, using this code:
+
+in */app/controller/user.php*
+```php
+form(new \MyApp\Form\User\Create());
+```
+
+*/app/form/create.php*
+```php
+<?php
+
+namespace MyProject\Form;
+
+use MyProject\{ Lib, Entity };
+use Picea\Ui\Method\{ FormContextInterface, Message\ErrorMessage };
+
+use Psr\Http\Message\ServerRequestInterface;
+
+use function MyProject\View\{ lang };
+
+class Create implements \Picea\Ui\Method\FormInterface {
+
+    public function initialize(FormContextInterface $context) : void
+    {
+        $this->user = new Entity\User();
+        
+        # $context->{varname} will be populated by $_POST data.
+        $this->user = (string) $context->fullname;
+    }
+
+    public function validate(FormContextInterface $context) : bool
+    {
+        if ( strlen($this->user) < 3 ) {
+            # This won't allow `execute` to run because of the error message.
+            $context->pushMessage(Lib\Message::generateError(
+                lang("form.error.provide_fullName")
+            ));
+        }
+    
+        return $context->valid();
+    }
+
+    public function execute(FormContextInterface $context) : void
+    {    
+        # Saving a new user here
+        Entity\User::repository()->save($this->user);
+        
+        $context->pushMessage(Lib\Message::generateSuccess(
+            lang("form.save")
+        ));
+    }
+}
+```
+
+which implements this interface :
+
+```php
+interface FormInterface
+{
+    public function initialize(FormContextInterface $context) : void;
+
+    public function validate(FormContextInterface $context) : bool;
+    
+    public function execute(FormContextInterface $context);
+}
+```
+
+Would yield the same result such as:
+```php
+true
+true
+```
+
+Trying to access either variable before `execute` is called will return `null`.
+
+## `FormContext` object
+
+`__construct(ServerRequestInterface $request, ? string $formName = null)`
+
+Creating a form context manually allows to define the formName, which is essential if you want to use the
+Cross-Scripting Request Forgery (CSRF).
+
+It is populated with either $_POST or request's body which is json_decode. A property called `files` is also populated from PSR's `$request->getUploadedFiles()`.
+
+It's `valid() : bool` method called into a form `validate()` function is first checking every message which were pushed into, using `pushMessage(FormMessage $message)`, and returns false if an error message is found in the list.
+
+### Retrieve a form execution status / value
+
+There is two ways to get the execution status (from the `execute` return value):
+
+```php
+$formContext = new \Picea\Ui\Method\FormContext($request, 'form.user_create');
+$form = form(new \MyProject\Form\User\Create(), $formContext);
+
+if ($formContext->formExecuted) {
+    echo $form->executionStatus;
+    echo $formContext->formExecutionStatus;
+}
+```

docs/30-component-popup.md

@@ -0,0 +1,8 @@
+# `ui.popup` (string $name, array $variables = [], array $options = [])
+
+The following attributes are assigned by this extension :
+
+and will typically be rendered such as (directly inside an opening tag) :
+```html
+ui-popup='{ "name":$name,"vars":{$variables},"options":{$options} }'
+```