Added docs for locals

Author: blokku-chan

content/reference.md

@@ -7,18 +7,23 @@ Imba compiles to JavaScript. In the context of APIs you can think of it like Typ
 The global `imba` object contains functions, constants and classes that are included with Imba. Imba also extends the built-in `Element` with certain properties. All items that are imba-specific are marked with a ★ symbol throughout the documentation.
 
 ### Properties
+
 <api-list>imba.own.variables</api-list>
 
 ### Functions
+
 <api-list>imba.own.functions</api-list>
 
 ### Decorators
+
 <api-list>imba.own.decorators</api-list>
 
 ### Interfaces
+
 <api-list>imba.own.interfaces</api-list>
 
 ## Global interfaces
+
 <api-list>own.interfaces</api-list>
 
 # /docs/css/properties/display
@@ -28,9 +33,11 @@ The display CSS property sets whether an element is treated as a block or inline
 Formally, the display property sets an element's inner and outer display types. The outer type sets an element's participation in flow layout; the inner type sets the layout of children. Some values of display are fully defined in their own individual specifications; for example the detail of what happens when display: flex is declared is defined in the CSS Flexible Box Model specification.
 
 ## Values
+
 <api-list>css.display.all.cssvalues ^[^-]</api-list>
 
 # /docs/css/properties/align-items
+
 <api-list>css.align-items.all.cssvalues ^[^-]</api-list>
 
 # /docs/css/values/timing-function
@@ -70,7 +77,44 @@ def load
 
 # /api/imba/locals
 
-Documentation coming
+`locals` is an instance of a JavaScript Proxy object that provides a convenient and efficient way to interact with the global `localStorage`. It wraps around a `Storage` instance, which in turn wraps around the `localStorage` object.
+
+### Usage
+
+#### Getting a Property
+
+You can get a property from `locals` by simply accessing it like `imba.locals.prop`. This will call the getItem method of the Storage class, which retrieves the value from the `localStorage` (if it exists), or from the cache if it's already been retrieved before.
+
+```imba
+let value = imba.locals.prop
+```
+
+#### Setting a Property
+
+You can set a property on `locals` by simply assigning a value to it like `imba.locals.prop = value`. This will call the `setItem` method of the `Storage` class, which stores the value in the `localStorage` and also updates the cache.
+
+```imba
+imba.locals.prop = 'value'
+```
+
+#### Deleting a Property
+
+You can delete a property from `locals` by using the `delete` keyword like `delete locals.prop`. This will call the `deleteProperty` method of the `Storage` class, which removes the value from the `localStorage` and also deletes it from the cache.
+
+```imba
+delete imba.locals.prop
+```
+
+### Applying a Function
+
+You can create a separate namespace or a sub-storage within your `localStorage` by calling it like imba.locals(name). This will call the `apply` method of the `Storage` class, which returns a child Proxy object associated with the given name.
+
+Here's an example of how you can use this feature:
+
+```imba
+let child = imba.locals('childName')
+child.prop = 'value'
+```
 
 # /api/imba/session
 
@@ -80,16 +124,16 @@ Documentation coming
 
 In addition to the default [built in colors](/docs/css/values/color), `hue0`,`hue1`,`...`,`hue9` refers to the color scale set by the `hue` property. Setting `hue:amber` in css, will make `hue2` refer to `amber2` inside all elements that are affected by this style. The `hue(n)` color values supports an alpha value with the forward-slash syntax like `hue4/40`
 
-
-
 ### Syntax
+
 ```imba
 <div[hue:violet color:hue4]>
 ```
 
 ### Usage
 
 Let's say you have a button component with some basic styles:
+
 ```imba
 # [preview=md]
 import 'util/styles'
@@ -105,6 +149,7 @@ tag Button
 
 imba.mount do <Button> "Button"
 ```
+
 This is all fine, but what if you want to also have a red button, and a green button? Duplicating all the styles involving colors is impractical, especially if you change the design of the button later. With `hue`, we can replace `blue2` with `hue2`, `blue8/70` with `hue8/70` and so on. Then we can set the color scale using the `hue` property.
 
 ```imba
@@ -117,7 +162,7 @@ tag Button
         text-shadow:0px 1px hue8/70
         bg:hue5 @hover:hue6
         bd:1px solid hue6
-        
+
     <self> <span> <slot>
 
 imba.mount do <>
@@ -138,12 +183,15 @@ This is some documentation for the parent!
 # /api/Element/data
 
 ### Syntax
+
 ```imba
 <element data=value>
 ```
+
 ## Usage
 
 The default convention in imba is to use the data property on elements to pass in the state/data they are supposed to represent. In this example we pass in the movie object through the data property:
+
 ```imba
 tag movie-item
     # using references to data
@@ -153,8 +201,7 @@ tag movie-item
     <movie-item data=movie>
 ```
 
-
-However, __there is nothing special about the data property__, besides it being declared for all elements. It is just a plain property. If you prefer to use more descriptive properties you are free to do so:
+However, **there is nothing special about the data property**, besides it being declared for all elements. It is just a plain property. If you prefer to use more descriptive properties you are free to do so:
 
 ```imba
 tag movie-item
@@ -202,16 +249,19 @@ tag movie-item
 ### Overriding
 
 If you want to do something when setting data, you can easily create a setter and getter:
+
 ```imba
 tag movie-item
     set data value
         #data = value
         console.log "movie was set",value
-        
+
     get data
         #data
 ```
+
 The memoized dom works in such a way that the setter will only be triggered when the value actually changes. If you set the property manually outside of rendering, the setter will be called every time, even if the value has not changed:
+
 ```imba
 tag app
     <self>
@@ -220,18 +270,22 @@ tag app
             <movie-item data=movie @click=($card.data = movie)>
         <movie-card$card>
 ```
+
 In this case, the movie-item data setter will only be called when their `data` actually changes, even if we render the list a million times. But if you click a movie-item 10 times, the `movie-card.data` property will be set 10 times. This is only really a challenge if you do something computationally expensive in the `data` setter itself. In that case you can just check if something has changed:
+
 ```imba
 tag movie-card
     set data value
         if #data != value
             #data = value
             # ... load more info about the movie?
-        
+
     get data
         #data
 ```
+
 Since Imba embraces the concepts of memoization we have the `=?` operator that is shorthand for the pattern above.
+
 ```imba
 if item.propname =? value
     # item.propname is now set to value,
@@ -304,6 +358,7 @@ let length = 100px
 let progress = 87%
 let dynamic = (window.innerWidth)px
 ```
+
 Dimensions are numbers with a unit attached to it. They are compiled and treated as regular strings. When dealing with styles it is nice to be able to write `offset = (point.x)px` instead of `offset = "{point.x}px"`.
 
 Time-based units `ms`, `s`, and `fps` are compiled to millisecond-based numbers.