# @mikosoft/dodo — AI Reference (v1.3.0)

Concise reference for AI assistants. Read this file to understand the Dodo framework
without analysing source code. Full docs: http://dodo.mikosoft.info


## What is Dodo

@mikosoft/dodo is a lightweight MVC JavaScript framework for building reactive single-page
applications (SPAs). It has zero external dependencies, requires no build tools or TypeScript,
and uses plain ES6 modules. Supported environments: browsers, browser extensions, Electron,
Cordova/PhoneGap, PWAs.

Key differences from React/Vue/Angular:
- No components — one Controller manages the whole page
- No virtual DOM — updates real DOM via dd-* directive processing
- No JSX/templates — plain HTML files with dd-* attributes
- Reactive model via JavaScript Proxy (not observables or signals)


## Architecture

```
URL change → Router → Controller runs lifecycle hooks → dd-* directives update DOM
```

Two app entry-point classes:

| Class    | File                  | Use case                                  |
|----------|-----------------------|-------------------------------------------|
| App      | core/App.js           | Multi-page SPA with client-side routing   |
| AppOne   | core/AppOne.js        | Single-page, no routing (extensions etc.) |

Supporting classes (inheritance chain, bottom → top):
  Controller → Model → Dd → DdCloners → DdListeners → Auxiliary


## Entry Point Setup

### Multi-page app (App)

```javascript
import { App } from '@mikosoft/dodo';

const app = new App('myApp');
app
  .auth($auth)             // Auth instance → this.$auth in controllers
  .httpClient($httpClient) // HTTP client → this.$httpClient in controllers
  .debug($debugOpts)       // console debug flags
  .fridge($fridge)         // shared object persisting across routes → this.$fridge
  .i18n($i18n)             // translations → used by View.loadI18n(langCode)
  .preflight([fn1, fn2])   // run before every controller __loader()
  .postflight([fn1, fn2])  // run after every controller __postrend()
  .destroyflight(fn)       // run when any controller is destroyed (route change)
  .ssr();                  // dispatches 'ssr-ready' window event after first render

const $routes = [
  ['when',     '/',          HomeCtrl],
  ['when',     '/users/:id', UserCtrl,     { authGuards: ['isLogged'] }],
  ['when',     '/login',     LoginCtrl],
  ['redirect', '/home',      '/'],          // redirect /home → /
  ['do',       [logFn]],                   // run on every route change
  ['notfound', NotfoundCtrl]
];

app.routes($routes).listen();
```

### Single-page app (AppOne)

```javascript
import { AppOne } from '@mikosoft/dodo';
const app = new AppOne('myApp');
app.controller(MyCtrl);
```


## Controller Lifecycle

Every Controller runs hooks in this strict order:

```
__loader(trx) → __init(trx) → __rend(trx) → __postrend(trx)
__destroy() fires when navigating away from the route
```

| Hook           | Purpose                                                       |
|----------------|---------------------------------------------------------------|
| `__loader(trx)` | Load HTML views/partials into the DOM                        |
| `__init(trx)`  | Set initial values on `$model` and controller properties      |
| `__rend(trx)`  | Call `render()` — processes all dd-* directives               |
| `__postrend(trx)` | Run code after render (fetch data, init 3rd-party plugins) |
| `__destroy()`  | Cleanup (remove event listeners, cancel timers)               |

The `trx` (transitional) object:
```javascript
trx.uri     // '/users/42'
trx.params  // { id: '42' }        — route params from '/users/:id'
trx.query   // { sort: 'asc' }     — query string params
trx.pevent  // popstate/pushstate browser event
```

Minimal controller:
```javascript
import { Controller } from '@mikosoft/dodo';

class HomeCtrl extends Controller {
  async __loader(trx) {
    await this.loadView('#main', '/views/home.html');
  }
  async __init(trx) {
    this.$model.title = 'Hello';
    this.$model.users = [];
  }
  async __rend(trx) {
    await this.render();
  }
  async __postrend(trx) {
    const resp = await this.$httpClient.get('/api/users');
    this.$model.users = resp.data; // triggers reactive render('users') automatically
  }
}
export default HomeCtrl;
```


## Reactive Model ($model)

`this.$model` is a JavaScript Proxy defined on the Controller. Assigning any property
automatically triggers a debounced, serialised `render(modelName)`.

```javascript
this.$model.items = [];        // next tick: render('items') fires
this.$model.count = 42;        // next tick: render('count') fires

// Manual full render (called in __rend):
await this.render();

// Manual targeted render (called anywhere after __init):
await this.render('items');    // only re-renders dd-* elements bound to 'items'
```

Render is debounced per property name (rapid successive assignments = one render) and
serialised globally (renders never run in parallel — prevents listener corruption).

`$modeler` — helper methods auto-defined for each $model property:
```javascript
this.$modeler.items.push(newItem);  // push to array, then render('items')
this.$modeler.items.unshift(item);
this.$modeler.items.set(idx, val);
this.$modeler.items.del(idx);
```


## View System

`this.loadView(viewName, viewContent, dest, cssSel, skipHideDirectives)` — injects HTML content
into the element with `dd-view="viewName"`. Called in `__loader()`.

```javascript
async __loader(trx) {
  this.loadView('#main',    mainHtml);
  this.loadView('#sidebar', sidebarHtml);

  // skipHideDirectives: skip hiding + immediately process listed directives.
  // Use for static views whose dd-* expressions don't depend on $model data
  // (e.g. $fridge-based dd-class for active-link highlighting, dd-href navigation links).
  // This prevents the flash where links are hidden until __rend() completes after API calls.
  this.loadView('#sidebar', sidebarHtml, 'inner', '', ['dd-class', 'dd-href']);
}
```

HTML files are plain HTML fragments (no `<html>/<body>` wrapper needed).

`skipHideDirectives` parameter (5th arg, default `[]`): array of directive names to opt out of
the hide-until-render mechanism. Elements matching those directives are inserted visible and the
corresponding processors (`ddClass()`, `ddHref()`, …) are called immediately after inject, before
`__init()` runs. Only safe for expressions that do not depend on `$model` data (e.g. `$fridge`,
static values). `$model`-dependent `dd-class` / `dd-text` etc. on other views are unaffected and
still hide+render on the normal `__rend()` cycle.

`this.loadI18n(langCode)` — injects translation strings from the `$i18n` object into the
view. Translation keys in HTML: `data-i18n="SOME_KEY"`.


## dd-* Directives Reference

Directives are `dd-*` HTML attributes processed during `render()`.

### Value format rules (apply to almost all directives)

```html
dd-text="firstName"                         <!-- controller property -->
dd-text="this.firstName"                    <!-- explicit this -->
dd-text="$model.product.name"               <!-- $model property path -->
dd-text="printTxt('hello')"                 <!-- controller method call -->
dd-text="((a + $model.b) * $fridge.x)"     <!-- expression (wrap in parentheses) -->
dd-text="(a > $model.b ? 'YES' : 'NO')"    <!-- ternary expression -->
```

Supported operators inside expressions: `! !== != === == > >= < <= && ||`

**⚠️ IMPORTANT — No method chaining in dd-* expressions:**
JavaScript method calls chained after an expression (e.g. `.toFixed()`, `.toUpperCase()`,
`.slice()`) are NOT supported in `dd-*` attribute values. The expression parser's `^\(.+\)$`
regex matches to the LAST `)` in the string, not the closing paren of the inner expression,
causing the method name to be treated as an undefined variable and throwing a runtime error.

```html
<!-- ❌ WRONG — causes _solveMath errors -->
<span dd-text="($$plan.price_monthly / 100).toFixed(2)"></span>

<!-- ✅ CORRECT — precompute in the controller, expose as a $model property -->
<!-- In controller: plan.priceDisplay = (plan.price_monthly / 100).toFixed(2) -->
<span dd-text="$$plan.priceDisplay"></span>
```

**Rule: always precompute formatted/transformed values in the controller and bind the
result to a `$model` property (or a computed property on each item). Use dd-* directives
only to READ those properties or to evaluate simple arithmetic / boolean expressions.**

Common modifier available on most directives:
```html
dd-text="company.size --forceRender"   <!-- re-render on ANY $model change, not just 'size' -->
```

---

### Writers

**dd-text** — sets `textContent` (HTML tags are NOT interpreted)
```html
<p dd-text="$model.product.name"></p>
<p dd-text="$model.product.description --pipe:slice(0, 55)"></p>
<p dd-text="printTxt('some string')"></p>
<p dd-text="(a > $model.b ? 'YES' : 'NO')"></p>
```
Modifier: `--pipe:stringMethod()` — applies any String method (slice, replace, toUpperCase…)

**dd-html** — sets `innerHTML` (HTML tags ARE interpreted)
```html
<div dd-html="$model.richContent"></div>
<div dd-html="printHtml('<b>bold</b>')"></div>
```

---

### Form value directives

**dd-value** — sets form element value (one-way: model → view)
```html
<input type="text"   dd-value="$model.product">
<input type="number" dd-value="(x > a ? 3 : 5)">
<textarea            dd-value="$model.description"></textarea>
<select              dd-value="$model.car">...</select>
```

**dd-model** — two-way binding: model → view AND view → model (fires on `input` event, triggers `render`)
```html
<input dd-model="$model.product.name">
<input dd-model="$model.product.price --convertType">
```
Modifier: `--convertType` — auto-converts string input to Number/Boolean/Object.

**dd-set** — one-way: view → controller property on `input` event, does NOT trigger `render`
```html
<input   dd-set="myPet">
<select  dd-set="$model.age --convertType">
<select  dd-set="$model.user[{{this.id}}]">   <!-- mustache interpolation in path -->
```

---

### Text attribute directives

**dd-label** — sets `label` attribute
```html
<label dd-label="$model.fieldName"></label>
```

**dd-placeholder** — sets `placeholder` attribute
```html
<input dd-placeholder="$model.hint">
```

**dd-title** — sets `title` attribute
```html
<span dd-title="$model.tooltip"></span>
```

**dd-data** — sets `data-*` attributes
```html
<div dd-data="$model.userId --data-id"></div>
```

---

### Conditionals

**dd-if / dd-elseif / dd-else** — removes/inserts element from DOM
```html
<b dd-if="condition('if')">2</b>
<b dd-elseif="condition('elseif')">5</b>
<b dd-else>not 2, not 5</b>

<div dd-if="($model.a !== 'something')">...</div>
<div dd-if="(!!$model.companies[0].opened)">...</div>
```
`dd-else` takes no value. Siblings must be adjacent elements.

**dd-visible** — toggles `visibility: visible|hidden` (element stays in DOM)
```html
<div dd-visible="$model.isActive">...</div>
<div dd-visible="($model.a !== 'something')">...</div>
```

---

### Loops (Cloner Directives)

`dd-each` goes on **the element being repeated**, not on a parent container.
Declare template variables with `--alias,key`. Inside the loop:
- `{{alias}}` / `{{key}}` — mustache syntax for text content and HTML
- `$$alias` — double-dollar prefix to reference the current item inside other `dd-*` attribute values
- `$model` inside the loop still refers to the **controller's reactive model**, NOT the loop item

**dd-each** — iterate array
```html
dd-each="myArr --val,key"
dd-each="$model.myArr --val,key"
dd-each="this.$model.myArr --val,key"
dd-each="getItems() --val,key"
```

**dd-each2** — nested loop inside `dd-each` (MUST use `$$` prefix for sub-array)
```html
<div dd-each="$model.users --user,i">
  <b>{{user.name}}</b>
  <span dd-each2="$$user.addresses --addr,j">{{addr.city}}</span>
</div>
```

**dd-entries** — iterate object key-value pairs
```html
<tr dd-entries="$model.config --key,val">
  <td>{{key}}</td>
  <td>{{val}}</td>
</tr>
```

**dd-repeat** — clone element N times
```html
dd-repeat="$model.myNumber"
dd-repeat="multiply(5)"
dd-repeat="(this.myNumber + 1)"
```

**dd-each full example:**

Controller — `src/controllers/UsersCtrl.js`:
```javascript
import { Controller } from '@mikosoft/dodo';

class UsersCtrl extends Controller {
  async __loader(trx) {
    await this.loadView('#main', '/src/views/pages/users.html');
  }
  async __init(trx) {
    this.$model.users = [];
  }
  async __rend(trx) {
    await this.render();
  }
  async __postrend(trx) {
    const resp = await this.$httpClient.get('/api/users');
    this.$model.users = resp.data; // triggers render('users') automatically
  }
  deleteUser(key) {
    this.$model.users = this.$model.users.filter((u, i) => i !== key);
  }
}
export default UsersCtrl;
```

View — `src/views/pages/users.html`:
```html
<ul>
  <li dd-each="$model.users --user,key" dd-class="$$user.cssClass --add">
    <span>{{key}}.</span>
    <strong>{{user.name}}</strong>
    <em>{{user.email}}</em>
    <button dd-click="deleteUser({{key}})">Delete</button>
  </li>
</ul>
```

**dd-each with `<option>` pre-selection:**
```html
<select dd-set="$model.selected_country">
  <option dd-each="countries --country,key --selected:0" value="{{country}}">{{country}}</option>
</select>
```
`--selected:N` pre-selects the Nth option (0-based index).

---

### HTML Attribute Managers

**dd-class** — add/remove/toggle CSS classes
```html
<div dd-class="myKlass --add">...</div>       <!-- add classes (default) -->
<div dd-class="myKlass --remove">...</div>    <!-- remove classes -->
<div dd-class="myKlass --toggle">...</div>    <!-- toggle classes -->
<div dd-class="myKlass --replace">...</div>   <!-- clear all, then add -->
<div dd-class="myArrange --arrange">...</div> <!-- object: {add:[...], remove:[...], toggle:[...]} -->
<div dd-class="(isActive ? ['text-red','fw-bold'] : 'text-green')">...</div>
```
Value is a property holding a string or array of class names, a method call, or an expression.

**dd-style** — set inline styles
```html
<div dd-style="myStyle">...</div>           <!-- property: {'font-size':'25px','color':'red'} -->
<div dd-style="myStyle --replace">...</div> <!-- clear style first, then apply -->
<div dd-style="($model.x > b ? {color:'green'} : {color:'red'})">...</div>
```

**dd-disabled** — set/remove `disabled` attribute
```html
<button dd-disabled="isActive">...</button>
<button dd-disabled="(!$model.x)">...</button>
<button dd-disabled="($fridge.a > $model.b)">...</button>
```

**dd-readonly** — set/remove `readonly` attribute
```html
<input dd-readonly="$model.locked">
```

**dd-required** — set/remove `required` attribute
```html
<input dd-required="$model.mandatory">
```

**dd-checked** — set checkbox/radio checked state
```html
<input type="checkbox" dd-checked="selectedCheckboxes">  <!-- array of values -->
<input type="radio"    dd-checked="selectedRadio">        <!-- single string value -->
```

**dd-selected** — set select option selected state
```html
<select dd-selected="selectedProduct">...</select>
<select dd-selected="selectedProducts --multiple">...</select>  <!-- multi-select: array -->
```

**dd-src** — set `src` attribute
```html
<img dd-src="$model.imageURL">
<img dd-src="$model.imageURL --https://via.placeholder.com/130">  <!-- fallback src -->
```

**dd-attr** — set any HTML attribute
```html
<a dd-attr="$model.myURL --href">Link</a>
<a dd-attr="setUrl() --href">Link</a>
```
Modifier `--attributeName` specifies which attribute to set.

**dd-min / dd-max** — set `min` / `max` attributes
```html
<input dd-min="$model.minVal">
<input dd-max="$model.maxVal">
```

---

### Event Listeners

Special parameters available inside event directive values:
- `$element` — the DOM element the directive is on
- `$event` — the native DOM event object

**dd-click**
```html
<button dd-click="myFunc()">Click me</button>
<button dd-click="(alert('hello'))">Alert</button>
<button dd-click="myFunc() --preventDefault">No default</button>
```

**dd-enter** — fires on Enter key
```html
<input dd-enter="myFunc()">
<input dd-enter="(alert('txt')) --preventDefault">
```

**dd-keyup** — fires on keyup with optional key and debounce modifiers
```html
<input dd-keyup="myFunc()">
<input dd-keyup="myFunc() --enter">              <!-- only on Enter key -->
<input dd-keyup="myFunc() --delay:500">          <!-- debounced 500ms -->
<input dd-keyup="myFunc() --enter --delay:1000"> <!-- both modifiers -->
```

**dd-change** — fires on form element change
```html
<select dd-change="myFunc()"></select>
```

**dd-evt** — any DOM event(s), chainable with `&&`
```html
<span dd-evt="runFn($element, $event, 'red') --mouseenter && runFn($element, $event, 'green') --mouseleave">
  Hover me
</span>
```

**dd-outclick** — fires when clicking outside the element
```html
<div dd-outclick="closeDropdown()">...</div>
```

**dd-intersect** — fires when element enters viewport (IntersectionObserver)
```html
<img dd-intersect="lazyLoad()" data-src="/img/photo.jpg" src="/img/placeholder.jpg">
```

**dd-swipe** — fires on touch swipe with optional direction filter
```html
<div dd-swipe="onSwipe($event)">...</div>            <!-- any direction -->
<div dd-swipe="prev() --left">...</div>              <!-- left swipe only -->
<div dd-swipe="next() --right">...</div>             <!-- right swipe only -->
```
Direction modifiers: `--left`, `--right`, `--up`, `--down`

**dd-href** — client-side navigation, no page reload
```html
<a href="/about"  dd-href>About</a>          <!-- uses href attribute value -->
<a href="" dd-href="/about">About</a>        <!-- value overrides href -->
```

---

### DOM Utilities

**dd-elem** — exposes DOM element as `this.$elem.<name>` in the controller
```html
<canvas dd-elem="chart"></canvas>
<!-- controller: this.$elem.chart → the <canvas> DOM element -->
```

**dd-setinitial** — reads element's current value into a controller property on route load (prerender, before `__init`)
```html
<input value="bread"  dd-setinitial="product">
<input value="1971"   dd-setinitial="year --convertType">
<select               dd-setinitial="$model.lang">
```
Modifier: `--convertType` — auto-converts string to Number/Boolean/Object.

---

### Visibility Helpers (`-hide` suffix)

Any directive attribute can have `-hide` appended to hide the element until rendering
is complete (prevents flash of unrendered content):
```html
<ul dd-each-hide="users">...</ul>
<p  dd-text-hide="$model.title"></p>
```
DoDo injects `[dd-*-hide] { display: none !important; }` via a `<style>` tag at startup.


## Real-World Patterns & Examples

### View loading — import HTML as raw string (Vite/bundler)
```javascript
import navbar from '/views/inc/navbar.html?raw';
import home   from '/views/pages/home/home.html?raw';

async __loader(trx) {
  this.loadView('#navbar', navbar);   // raw HTML string
  this.loadView('#main',   home);
}
```
`loadView` accepts either a raw HTML string (bundler import) or a URL string (fetch).

### Page meta helpers (available in __loader)
```javascript
this.setTitle('Page Title');
this.setDescription('Meta description');
this.setKeywords('dodo, spa, js');
this.setLang('en');
```

### Controller with full lifecycle
```javascript
import { Controller, corelib } from '@mikosoft/dodo';
import navbar from '/views/inc/navbar.html?raw';
import page   from '/views/pages/users.html?raw';

export default class UsersCtrl extends Controller {
  constructor(app) {
    super();
  }
  async __loader(trx) {
    this.setTitle('Users');
    this.loadView('#navbar', navbar);
    this.loadView('#main', page);
  }
  async __init(trx) {
    this.$model.users = [];
    this.selectedId = null;
  }
  async __rend(trx) {
    await this.render();
  }
  async __postrend(trx) {
    const resp = await this.$httpClient.askJSON('/api/users', 'GET');
    this.$model.users = resp.data;
  }
  async __destroy() {
    this.unloadCSS(['/css/users.css']);
  }
  selectUser(id) {
    this.selectedId = id;
    this.$model.users = this.$model.users; // force re-render
  }
}
```

### $modeler API (correct method names)
```javascript
this.$modeler.use('pets').setValue('cat');        // set scalar value
this.$modeler.use('pets').getValue();             // get current value
this.$modeler.use('pets').getValue('x.y.z');      // get at nested path
this.$modeler.use('pets').setValue(2015, 'x.y.z'); // set at nested path
this.$modeler.use('pets').delValue('x.y.z');      // delete nested key
this.$modeler.use('pets').mpush('rabbit');         // array push + render
this.$modeler.use('pets').mpop();                  // array pop + render
this.$modeler.use('pets').munshift('fish');        // array unshift + render
this.$modeler.use('pets').mshift();                // array shift + render
```

### dd-click — multiple methods, special args, nested property call
```html
<!-- run two methods with one click (semicolon separated) -->
<button dd-click="save(); notify()">Save</button>

<!-- $element = the DOM element itself -->
<button dd-click="makeRed($element)">Color</button>

<!-- $value = current input value -->
<input dd-click="search($value)">

<!-- call a nested method defined as a controller property -->
<button dd-click="print.inConsole.makeRed($element)">Log</button>

<!-- pass controller property as argument -->
<button dd-click="processAll(this.products)">Process</button>

<!-- regex literal as argument -->
<button dd-click="validate(/^[a-z]+$/)">Validate</button>
```

### dd-each with dd-if inside
```html
<table>
  <tr dd-each="$model.companies --val,key">
    <td>{{val.name}}</td>
    <td dd-if="compareSize({{val.size}})">{{val.size}}</td>
    <td dd-else>Less than 50</td>
  </tr>
</table>
```

### dd-each with dd-html (generate cell HTML from method)
```html
<table>
  <tr dd-each="cars --car,key" dd-html="tableCells({{key}})"></tr>
</table>
```
```javascript
tableCells(key) {
  const car = this.cars[key];
  return `<td>${car.name}</td><td>${car.year}</td>`;
}
```

### dd-each generating <option> elements
```html
<select name="myAuto">
  <option value=""></option>
  <option dd-each="$model.autos --val,key" value="{{val.id}}">{{val.name}}</option>
</select>
```

### dd-view — sub-view placeholder
```html
<!-- in main view -->
<div dd-view="#main-part">PLACEHOLDER</div>
```
```javascript
// in __loader
this.loadView('#main-part', part, 'inner');  // 3rd arg: load mode
```

### dd-form — Form library integration
```html
<form dd-form="testForm">
  <input type="text"     name="fullName">
  <input type="number"   name="age">
  <select name="country">...</select>
  <select name="family" multiple>...</select>
  <input type="checkbox" name="jobs" value="IT">
  <input type="radio"    name="pet"  value="cat">
  <textarea name="desc"></textarea>
</form>
```
```javascript
this.testForm = new corelib.Form('testForm');

this.testForm.setControl('fullName', 'John Doe');
this.testForm.getControl('fullName');             // → 'John Doe'
this.testForm.delControl('fullName');

this.testForm.setControls({ fullName: 'Ana', age: 25 });
this.testForm.getAllControls();                   // → { fullName, age, ... }
this.testForm.delAllControls();

// dot notation for nested field names
this.testForm.setControl('fruit.seller.name', 'Joe Ltd');
```

### HTTPClient — askJSON shorthand
```javascript
const resp = await this.$httpClient.askJSON('/api/users', 'GET');
const resp = await this.$httpClient.askJSON('/api/users', 'POST', { name: 'Ana' });
```

### Auth configuration
```javascript
import { corelib } from '@mikosoft/dodo';

const $auth = new corelib.Auth({
  apiLogin:        'http://localhost:8001/api/users/login',
  afterGoodLogin:  '/dashboard/{loggedUserRole}',  // {loggedUserRole} is substituted
  afterBadLogin:   '/login',
  afterLogout:     '/login'
});

// bind guards before passing to route options
const autoLogin = $auth.autoLogin.bind($auth);
const isLogged  = $auth.isLogged.bind($auth);
const hasRole   = $auth.hasRole.bind($auth);

// in routes:
['when', '/dashboard', DashCtrl, { authGuards: [isLogged, hasRole] }]
['when', '/login',     LoginCtrl, { authGuards: [autoLogin] }]
```

### HTTPClient configuration
```javascript
import { corelib } from '@mikosoft/dodo';

const $httpClient = new corelib.HTTPClient({
  encodeURI:    true,
  timeout:      21000,
  responseType: '',
  retry:        0,
  retryDelay:   1300,
  maxRedirects: 0,
  headers: {
    'authorization': '',
    'accept':        '*/*',
    'content-type':  'text/html; charset=UTF-8'
  }
});
```

### dd-set with dd-evt (when dd-click fires before dd-set)
```html
<!-- dd-click fires BEFORE dd-set, so use dd-evt --input to read the updated value -->
<input dd-set="myProp" dd-evt="printInConsole() --input">
```

### dd-setinitial with dd-model (capture initial HTML value into $model)
```html
<input type="text" value="Saša" dd-model="$model.name" dd-setinitial="$model.name">
<select dd-model="$model.country" dd-setinitial="$model.country">
  <option value="HR" selected>Croatia</option>
  <option value="US">USA</option>
</select>
```


## Built-in Libraries

Import from corelib:
```javascript
import { corelib } from '@mikosoft/dodo';
const { Auth, HTTPClient, HTTPClientFetch, Form, Cookie,
        BrowserStorage, Paginator, eventEmitter, navig, util, ApiCall } = corelib;
```

### Auth (`core/lib/Auth.js`)
JWT authentication with cookie storage, auto-login on page refresh, and role-based route
guards. Inject into the app with `app.auth($auth)` → available as `this.$auth` in all controllers.

```javascript
await this.$auth.login(credentials);
await this.$auth.logout();
this.$auth.getLoggedUserInfo();       // decoded JWT payload
this.$auth.getJWTtoken();             // raw JWT string
```

Route guard options (passed in route definition):
```javascript
['when', '/dashboard', DashCtrl, { authGuards: ['autoLogin', 'isLogged', 'hasRole'] }]
```

### HTTPClient / HTTPClientFetch (`core/lib/HTTPClient.js`, `HTTPClientFetch.js`)
Two HTTP clients — XMLHttpRequest-based and Fetch API-based. Inject via `app.httpClient($httpClient)`.

```javascript
const resp = await this.$httpClient.get('/api/users', { headers: {...} });
const resp = await this.$httpClient.post('/api/users', body, { headers: {...} });
await this.$httpClient.put('/api/users/1', body);
await this.$httpClient.delete('/api/users/1');
await this.$httpClient.patch('/api/users/1', patch);
```
Features: retry logic, timeouts, request/response interceptors, custom headers.

### ApiCall (`core/lib/ApiCall.js`)
Higher-level abstraction over HTTPClient for structured API calls.

### Form (`core/lib/Form.js`)
Read/write all HTML form control types (text, checkbox, radio, select, file) to/from `$model`.
Handles type conversion and optional validation.

### Cookie (`core/lib/Cookie.js`)
```javascript
Cookie.set('name', value, { expires: 7, secure: true, domain: '.example.com', sameSite: 'Strict' });
Cookie.get('name');
Cookie.delete('name');
```

### BrowserStorage (`core/lib/BrowserStorage.js`)
Simple wrappers around `localStorage` and `sessionStorage`.

### EventEmitter (`core/lib/EventEmitter.js`)
Pub/sub bus for decoupled communication between controllers:
```javascript
eventEmitter.emit('user:loggedIn', userData);
eventEmitter.on('user:loggedIn', handler);
eventEmitter.off('user:loggedIn', handler);
```

### Paginator (`core/lib/Paginator.js`)
Calculates page ranges, total pages, and navigation state for paginated data.

### navig (`core/lib/navig.js`)
```javascript
navig.goto('/dashboard');
navig.goto('/search', { q: 'hello' });   // appends query string
navig.getCurrentURI();                   // '/dashboard?tab=stats'
```

### util (`core/lib/util.js`)
General-purpose helpers: type checking (`util.isObj`, `util.isArr`, ...), deep object clone,
string manipulation, `util.sleep(ms)`.


## Debug Options

`core/conf/$debugOpts.js` defines boolean flags that enable console output per subsystem:

```javascript
const $debugOpts = {
  exeRoute: false,      // router matching
  render: false,        // render() calls
  ddEach: false,        // dd-each processing
  ddClick: false,       // dd-click listener attachment
  // ... one flag per directive and subsystem
};
app.debug($debugOpts);
```

Set any flag to `true` to see detailed console logs for that subsystem.


## Controller Constants (available as `this.*` in every controller)

| Property        | Source             | Description                                   |
|-----------------|--------------------|-----------------------------------------------|
| `this.$model`   | Model.js           | Reactive data proxy                           |
| `this.$modeler` | Model.js           | Array/object mutation helpers                 |
| `this.$dd`      | Dd.js              | Internal directive registry & listener list   |
| `this.$elem`    | Dd.js              | DOM elements captured by `dd-elem`            |
| `this.$fridge`  | App.fridge()       | Shared data across all controllers            |
| `this.$httpClient` | App.httpClient() | HTTP client instance                         |
| `this.$auth`    | App.auth()         | Auth instance                                 |
| `this.$debugOpts` | App.debug()      | Debug flags                                   |
| `this.$appName` | App constructor    | App name string                               |


## Known Issues

### Method chaining after expressions causes _solveMath errors

**Status:** By design (parser limitation)

Using JavaScript method calls (`.toFixed()`, `.toUpperCase()`, `.slice()`, etc.) chained
onto the end of a `(expression)` in any `dd-*` directive causes three console errors:

```
_solveMath Error:: The <fieldName> has undefined value.
_solveMath Error:: The toFixed has undefined value.
Error: Invalid character in expression
```

**Why:** `_solveBase` detects `^\(.+\)$` (starts with `(`, ends with `)`) and strips the
outer parens. When the attribute is `($$plan.price_monthly / 100).toFixed(2)`, the LAST `)` is
the one in `toFixed(2)`, so stripping gives `plans[0].price_monthly / 100).toFixed(2`.
`_solveMath` then tokenises this with the regex `/[a-zA-Z_$][a-zA-Z0-9_$\.]*/g`, which stops
at `[` brackets, leaving `price_monthly` and `toFixed` as bare undefined identifiers.

**Fix — always precompute in the controller:**
```javascript
// controller
this.$model.plans = plans.map(p => ({
  ...p,
  priceDisplay: (p.price_monthly / 100).toFixed(2),
}));
```
```html
<!-- view -->
<span dd-text="$$plan.priceDisplay"></span>
```

---

### Promise.all() inside `__init()` causes broken rendering

**Status:** Unresolved

Using `Promise.all()`, `Promise.race()`, `Promise.allSettled()`, or `Promise.any()` in
`__init()` can leave orphaned promises. If one branch rejects, `Promise.all` rejects early,
`__init()` returns, `__initFinished = true` is set — but surviving in-flight promises
continue running. When they later resolve and set `$model.x`, they trigger `render('x')`
out of sequence, corrupting the DOM/listener state. No error is thrown.

**Workaround — always use sequential awaits in `__init()`:**
```javascript
// BAD — do not do this:
async __init(trx) {
  await Promise.all([this.loadNetworks(), this.loadUsers()]);
}

// GOOD:
async __init(trx) {
  await this.loadNetworks();
  await this.loadUsers();
}
```

If parallel fetching is needed for performance, move it to `__postrend()` where
`__initFinished` is already `true` and the render queue handles sequencing correctly.


## File Map

```
core/
  index.js              — main export: { App, AppOne, Controller, Model, View, corelib }
  App.js                — multi-page SPA class
  AppOne.js             — single-page app class
  mvc/
    Controller.js       — lifecycle hooks, render(), _doRender()
    Model.js            — $model Proxy, $modeler helpers
    View.js             — loadView(), loadI18n()
    Dd.js               — non-cloner directive processors, $dd/$elem init
    DdCloners.js        — dd-each, dd-each2, dd-entries, dd-repeat
    DdListeners.js      — dd-click, dd-href, dd-model, dd-set, dd-change, dd-keyup,
                          dd-enter, dd-evt, dd-outclick, dd-intersect, dd-swipe
    Auxiliary.js        — _debug(), utility helpers
  misc/
    Router.js           — route matching, trx building, middleware chain
  lib/
    Auth.js
    HTTPClient.js
    HTTPClientFetch.js
    ApiCall.js
    Form.js
    Cookie.js
    BrowserStorage.js
    EventEmitter.js
    Paginator.js
    navig.js
    stringTypeConvert.js
    util.js
    index.js            — exports all lib as `corelib`
  conf/
    $debugOpts.js       — debug flag defaults
```