chore(docs): updating superstyle docs

docs/29.superstyle.md

@@ -13,9 +13,32 @@ The only exception to this rule (no pun intended), is the `content` rule, which
 
 ## Usage
 
-Create a handlebars file, for example under _src/api/view.hbs_, in that file declare a style tag with the attribute `is="super"` and start writing your css
+First of al create a route handler and serve your superstyle document.
+
+```php
+<?php
+// src/api/get.php
+use function CatPaw\Superstyle\superstyle;
+use function CatPaw\Core\asFilename;
+
+return function(){
+ return
+ superstyle(asFileName(__DIR__, 'view.hbs'))
+ ->setProperty('label', 'Click me!')
+ ->render();
+};
+```
+
+
+
+Then create the `view.hbs` file.
+
+> [!NOTE]
+> Yes, it's a Handlebars file, but not exactly!\
+> More on this in the next sub section.
 
 ```hbs
+<!-- src/api/view.hbs -->
 <style is="super">
  main {
  font-family: 'Courier New', Courier, monospace;
@@ -27,61 +50,86 @@ Create a handlebars file, for example under _src/api/view.hbs_, in that file dec
  display: grid;
  background: #000000;
 
- {{#each items}}
- button {
- content: "{{.}}";
- border: 0;
- font-size: 1.3rem;
- justify-self: center;
- align-self: center;
- background: rgb(234, 40, 5);
- color: rgb(233, 166, 155);
- border-radius: 3rem;
- padding: 1rem;
- cursor: pointer;
- box-shadow: 0;
- transition: 200ms transform;
-
- &:hover {
- transform: scale(1.1);
- }
+ button {
+ content: "{{label}}";
+ border: 0;
+ font-size: 1.3rem;
+ justify-self: center;
+ align-self: center;
+ background: rgb(234, 40, 5);
+ color: rgb(233, 166, 155);
+ border-radius: 3rem;
+ padding: 1rem;
+ cursor: pointer;
+ box-shadow: 0;
+ transition: 200ms transform;
+
+ &:hover {
+ transform: scale(1.1);
+ }
 
- &:active {
- box-shadow: 0;
- transform: scale(0.9);
- }
+ &:active {
+ box-shadow: 0;
+ transform: scale(0.9);
  }
- {{/each}}
+ }
  }
 </style>
 ```
-The style sheet must always declare a `main` element which will contain your application.
 
-Then create your route handler, for example in _src/api/get.php_
+Note the ` is="super"` attribute on the style tag, that is required.
 
-```php
-<?php
-use function CatPaw\Superstyle\superstyle;
-use function CatPaw\Core\asFilename;
+The style sheet itself must always declare a `main` element which will contain your application.
 
-return function(){
- return
- superstyle(asFileName(__DIR__, 'view.hbs'))
- ->setProperty('items', [
- "item-1",
- "item-2",
- "item-3",
- "item-4",
- ])
- ->render();
-};
-```
+Any selector inside your `main` selector will be treated as a document node declaration.
+This means that any selector within `main` is declaring specific instances of the given tag name.
+If a selector doesn't specify a tag name, the tag name will default to `div`.
 
-The _\$fileName_ is not required to be absolute, however your application's _cwd_ (current working directory) is always at the root of the project, so passing _"./view.hbs"_ as _\$fileName_ won't work, unless you change your application's _cwd_ to _\_\_DIR___.
+> [!NOTE]
+> The _\$fileName_ is not required to be absolute, however your application's _cwd_ (current working directory) is always at the root of the project, so passing _"./view.hbs"_ as _\$fileName_ won't work, unless you change your application's _cwd_ to _\_\_DIR___.\
+> \
+> For that reason, the code above is using _asFileName()_ to properly join _\_\_DIR___ and _"view.hbs"_ into an absolute path.
 
-For that reason, the code above is using _asFileName()_ to properly join _\_\_DIR___ and _"view.hbs"_ into an absolute path.
 
 The final output should looks something like this
 
-![Peek 2024-05-05 04-04](https://github.com/tncrazvan/catpaw/assets/6891346/f9a9bc2c-af0c-4b0d-9f5f-63ed07915ec3)
 
+## JavaScript
+
+You can execute javascript code on your page as long as you write it in a `script` tag.
+
+```html
+<style is="super">
+ main {}
+</style>
+<script>
+ console.log("hello world")
+</script>
+```
+
+This document will log `hello world` to the console whenever it loads.
+
+## Handlebars
+
+As you might have noticed we're using [Handlebars](https://handlebarsjs.com/) files.
+Superstyle is currently using Handlebars for rendering dynamic documents.
+
+> [!NOTE]
+> There are plans to support more template systems in the future, such as Twig.
+
+## Compilation
+
+Templates are compiled into php functions and cached immediately the first time they render.
+
+These php cached functions are saved into a `.tmp/handlebars` directory by default.
+
+You can overwrite this location on the _HandlebarsService_
+
+```php
+<?php
+use CatPaw\Web\Services\HandlebarsService;
+
+function main(HandlebarsService $handlebars){
+ $handlebars->withTemporaryDirectory('your/custom/tmp')
+}
+```