# Imba Documentation

> Complete documentation for the Imba programming language (v2.0.0-alpha.253), generated from https://imba.io. Imba is a friendly, full-stack language for the web that compiles to fast JavaScript, with DOM elements and scoped CSS built into the language.

Notes: Imba uses tabs for indentation. Code blocks are Imba unless tagged otherwise. Each section below lists its canonical URL — append .md to any of them for that page as markdown.

---

Source: https://imba.io/docs

# Language

Imba isn't a framework, it's a full language with zero friction
JavaScript interoperability that also ships with built in UI support.
You can use it for the same things you'd use JavaScript or Python for,
and you may find that Imba's syntax alone is enough to justify its use
for scripting.

<doc-pages></doc-pages>

---

Source: https://imba.io/docs/introduction

# Introduction

> **Tip:** Try Imba instantly in your browser with our [playground](https://imba.io/try/examples/apps/playground/app.imba).

## Getting Started

You can create a new Imba project with:

```sh
npm create imba@latest
```

Imba's [VSCode extension](https://marketplace.visualstudio.com/items?itemName=scrimba.vsimba) is highly recommended. It gives you full-featured tooling when using Imba, including autocomplete for css shortcuts.

If you have any questions or run into any issues, don't hesitate to reach out on [Discord](https://discord.gg/mkcbkRw) or [Github](https://github.com/imba/imba). There is also a free, interactive [Imba course](https://scrimba.com/learn/imba) on Scrimba, and additional content on the official Imba [YouTube channel](https://www.youtube.com/@imbajs/videos).

#### It’s just Javascript

A good way to think of Imba is, “It’s just JavaScript.” Imba compiles directly to readable JavaScript. This means that every native type with all of their methods, properties and behaviour are the exact same. So, strings are just strings, arrays are just arrays, and so on. If you'd like to manually compile an Imba file yourself, you can use the `imbac` command.

#### How do I do X with Imba?

One of the most common beginner questions is, "How do I do X with Imba?" the answer is usually "However you'd do it with Javascript", whether that means using a Javascript built-in method, or a library, you can generally do it the same way with Imba. The big exception to this is anything to do with custom components, HTML tags or CSS styles which usually do have an Imba-specific approach.

## Intro to Imba Syntax

[Watch "Intro to Imba Syntax" from the Imba course](https://scrimba.com/learn/imba/intro-to-imba-syntax-cpwyK7Tz)

Imba syntax is familiar and often the same as JavaScript. In the below example you can see between Imba and the compiled Javascript output of that Imba code. You'll notice the only difference is the semicolon in the Javascript.

```imba
console.log("Hello World")
# console.log("Hello World");
```

Imba wouldn't be very interesting if all it did was remove semicolons. Let's look at an instance where Imba departs further from Javascript. In Imba, you can optionally leave off the parentheses in a function call. Notice that the compiled output is still the same.

```imba
console.log "Hello World"
# console.log("Hello World");
```

Imba also supports convenient string interpolation syntax. You can interpolate any variable within a string by simply surrounding it in curly brackets. Again, the compiled Javascript output is shown in a comment below.

```imba
const name = "Imba"
# const name = "Imba";

console.log "Hello {name}"
# console.log("Hello " + name);
```

Here's a few more examples, with the compiled Javascript output shown below:

```imba
let number = 42
# let number = 42;

const myList = [1, 2, 3]
# const myList = [1, 2, 3];

const myBool = true
# const myBool = true;

const alsoBool = yes # Optionally write booleans as yes and no.
# const alsoBool = true;

const object = { name: 'Imba', type: 'language' }
# const object = { name: 'Imba', type: 'language' };

const alsoObject = name: 'Imba', type: 'language' # Optionally omit curly brackets.
# const alsoObject = { name: 'Imba', type: 'language' };

const indentedObject = # Optionally skip the commas for indented objects
    name: 'Imba'
    version: 2.0
    repository: 'https://github.com/imba/imba'
    inspiration: ['ruby', 'python', 'react', 'coffeescript']
# const indentedObject = { name: 'Imba', version: 2.0, repository: 'https://github.com/imba/imba', inspiration: ['ruby','python','react','coffeescript'] };
```

Imba also has a few of its own types which are not part of Javascript.

```imba
const duration = 150ms # compiles to: 150
const longerDuration = 42s # compiles to: (42 * 1000)

const element = <div.large.header> "Welcome"
# The compiled output of this line consists of highly-optimized memoized DOM code which is not easily human readable
```

## Conditionals

Imba is a whitespace-sensitive language. That means Imba determines the nesting of your code by looking at its indentation level. A basic if statement can be written like this:

```imba
if amount > max
    console.log "too much!"
```

Notice that parentheses are not required around the condition, and that the body is indented one level.

An else can be added like this:

```imba
if amount > max
    console.log "too much!"
else
    console.log "good amount"
```

Else if statements can be written as `else if` or using imba's shortened `elif`:

```imba
if amount > max
    console.log "too much!"
elif amount === max
    console.log "just right"
else
    console.log "add more"
```

Imba also supports trailing conditionals which can lead to very pleasant, readable code. Simply place the condition after a line of code.

```imba
console.log "too much!" if amount > max
```

Imba also supports an `unless` keyword which negates the condition. It can be used anywhere `if` is used.

```imba
console.log "limit exceeded" unless amount < max
```

The `&&` and `||` from Javascript can be somewhat cryptic. Imba additionally supports `and` and `or` for doing comparisons.

```imba
if (cameraMalfunction or trunkMalfunction) and (partInStock)
    doRepair()
else
    askCustomerToWait()
```

The ternary operator from Javascript is supported, but you can also use an `if`/`then`/`else` form which can be more readable.

```imba
# Ternary:
console.log amount > max ? 'too much' : 'not enough'

# Single line if/then/else:
console.log if amount > max then 'too much' else 'not enough'
```

## Functions

_Note: Differences between functions and arrow functions are covered in the [functions overview](https://imba.io/docs/functions)._

[Watch the interactive tutorial on functions in the Imba course](https://scrimba.com/learn/imba/functions-cJLGEQCB)

Imba uses the shorter `def` instead of the `function` keyword. `do` instead of `() => {}`. These are faster to write, read, and recognize at a glance.

```imba
def func(a, b)
    return a * b

def alsoFunc(a, b)
    a * b # Implicit return

const smallerFunc = do(a, b) a * b # Implicit return on one line
```

## Strings

```imba
const single = 'single quotes'
const double = "double quotes"
const interpolation = "string has {double}"
const template = `current version is {indentedObject.version}` # Interpolating using the object above.
```

Imba uses `{}` for string interpolation while JavaScript uses `${}`. If you want interpolated strings with literal curly-braces, remember to escape them with `\`. Other than that, the String type is identical to String in JavaScript. See documentation at [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String).

Regular string literals can be written over multiple lines, but line breaks are ignored.

```imba
const multipleLines = 'one
 two three'
console.log multipleLines
```

If you need a string that spans several lines and includes line breaks, use a sequence of characters surrounded by `'''` or `"""`.

```imba
const lineBreaks = '''
This string is written
over multiple lines
'''
console.log lineBreaks
```

Multiline strings preserves indentation, but only relative to the least indented line.

```imba
const stringIndentation = '''
    First level is ignored
        This is indented
    Not indented
    '''
```

Tagged templates let you parse template literals with a function in the same way [JavaScript does](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals).

```imba
const person = 'Mike'
const age = 28

def myTag(strings, personExp, ageExp)
    const str0 = strings[0] # "That "
    const str1 = strings[1] # " is a "
    const str2 = strings[2] # "."

    const ageStr = (ageExp > 99) ? 'centenarian' : 'youngster'

    # We can even return a string built using a template literal
    "{str0}{personExp}{str1}{ageStr}{str2}"

const output = myTag`That {person} is a {age}.`

console.log output
```

## Arrays

Arrays work the same way as in JavaScript. In Imba you can also declare them over multiple lines, where the value of each line represents an entry in the array. Commas are optional when array elements are separated by line breaks.

```imba
const withCommas = [
    'one',
    'two',
    'three',
    'four',
]

const withoutCommas = [
    'one'
    'two'
    'three'
    'four'
]

console.log withCommas, withoutCommas
```

## Objects

Objects work the same way as in JavaScript. As with the arrays above, commas are optional when separated by line breaks. Curly braces are optional when the separating colon makes it clear what the keys and values are.

```imba
const object = { a: 'foo', b: 42, c: {} }
const person =
    name: 'Bob Smith'
    age: 32
    gender: 'male'

# Curly braces are optional as the keys and values are clear:
def logObject(object)
    console.log "Logging:", object

logObject(name: 'Rincewind', profession: 'Wizzard')
```

An array of objects can be separated with dashes:

```imba
let todos = [
	title:'one'
	completed:yes
	-
	title:'two'
	completed:no
]
console.log todos
```

Object properties can be set dynamically by wrapping a variable with `[]`.

```imba
const field = 'age'
const person = {
    [field]: 32 # this property name is set dynamically using a variable
    name: 'Bob Smith'
}
console.log person.age
```

Properties work the same way as in JavaScript. They can be accessed and assigned using the `.` operator. The `const` keyword prevents re-assignment, but internals can still be modified.

```imba
const person = { name: 'Bob Smith', age: 32, gender: 'male' }
person.name
person.age = 33

console.log person.age
```

Keys work the same way as in JavaScript.

```imba
const person = { name: 'Bob Smith', age: 32, gender: 'male' }

person['name']
person['age'] = 33

console.log person.age
```

Destructuring (as defined in ES6) works the same way as in JavaScript.

_Note: Destructuring and skipping curly braces can get confusing. It is not recommended to combine these two features, as it makes the code hard to understand, and easy to cause bugs._

```imba
const a = 'foo'
const b = 42
const c = {}
const object = { a, b, c }

console.log object
```

## Methods

Parenthesis can be skipped, even when setting default values.

```imba
def withArgument param
	console.log param

withArgument 42

def withDefaultValue name = 'Imba'
	console.log name

withDefaultValue()
```

Objects can be destructured and given default values as in Javascript

```imba
def buildCharacter name, { title, desc = 'indescribable' }
	"{name}, {title}, {desc}"

console.log buildCharacter('Rincewind', {title: 'Wizzard'})
```

## Classes

_Note: More details about classes are in the [class overview](https://imba.io/docs/classes)._

[Watch the interactive tutorial on classes in the Imba course](https://scrimba.com/learn/imba/classes-cbVveMS4)

Classes in Imba can do the same things as classes in JavaScript, but have several additional features making them easier to use.

```imba
class Todo
	# Properties are member variables:
	title
	completed = no
	due = null

	# Methods are instance level functions:
	def complete
		completed = yes

	# Getters:
	get overdue
		due and due < new Date

	# Static methods are class level functions:
	static def createTodos titles
		titles.map do(title)
			new Todo(title: title)

const todo = new Todo title: 'Read introduction'

console.log todo
```

Instance level methods are called on the object made from the class.

```imba
class Todo
	title
	completed = no
	due = null
	def complete
		completed = yes
	get overdue
		due and due < new Date
	static def createTodos titles
		titles.map do(title)
			new Todo(title: title)
const myTodo = new Todo title: 'Learn Imba'
myTodo.complete()
console.log myTodo
```

Class level methods are called directly on the class.

```imba
class Todo
	title
	completed = no
	due = null
	def complete
		completed = yes
	get overdue
		due and due < new Date
	static def createTodos titles
		titles.map do(title)
			new Todo(title: title)
const newTodos = Todo.createTodos ['Learn Imba', 'Eat breakfast']
console.log newTodos
```

## Loops & Iteration

[Watch the interactive tutorial on loops in the Imba course](https://scrimba.com/learn/imba/loops-co2eb439ab71581a6ad3f0ea1)

Loops in Imba have more useful features than in JavaScript, making it easier to loop over object properties.

[Iterables](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) can be looped over with `for ... of ...`.

```imba
class Todo
	title
	completed = no
	due = null
	def complete
		completed = yes
	get overdue
		due and due < new Date
	static def createTodos titles
		titles.map do(title)
			new Todo(title: title)
const newTodos = Todo.createTodos ['Learn Imba', 'Eat breakfast']
console.log newTodos
for todo, index of newTodos
    console.log "{todo.title} at position {index}"
```

To loop over keys and values in an object automatically, use the `own` keyword for the object.

```imba
const object =
    hello: 'world'
    learning: 'imba'
    answer: 42

for own key, value of object
    console.log "{key}: {value}"
```

Looping within tags works the same way.

[Watch the interactive tutorial on looping within tags in the Imba course](https://scrimba.com/learn/imba/loops-inside-tags-co59443e78abc774ac34f72f4)

## Regular Expressions

Regular expressions work as in JavaScript, with the additional benefit of whitespace and comments in multi line regexes.

```imba
const literal = /ab+c/i
const regex = new RegExp('ab+c', 'i')
const multiline = ///
    ab+ # allows comments and whitespace
    c
///
```

## Ranges

Ranges use three dots within brackets `[0 ... 10]`, counting up until the upper number. This makes it easy to use with `myArray.length` without having to write `myArray.length - 1`.

```imba
const items = []
for i in [1 ... 5]
    items.push(i)

console.log items
```

## Elements

The web is native to Imba, so elements are "first class citizens" just like other native types.

```imba
global css ul inset:0 d:flex fld:column mx:auto jc:center w:25% list-style-type:disc
    li w:100%
const list = <ul title="reminders">
    <li> "Remember milk"
    <li> "Greet visitor"
imba.mount list
```

CSS classes are set with dots, and can be both dynamically interpolated and conditionally set. This lets you use logic inside elements, keeping the code short and simple.

```imba
const state = 'open'
const condition = no

<div.panel.large> "With classes"
<div.state-{state}> "Dynamic class name"
<div.hidden=condition> "Conditionally hidden"
<div.panel.state-{state} .hidden=condition> "Dynamic and conditional"
```

Handlers work the same way.

```imba
global css .panel inset:10px rd:lg d:flex ja:center bgc:amber1
	cursor:pointer user-select:none
const handler = do(event)
    console.log "Panel clicked!"

imba.mount <div.panel @click.prevent=handler> "Panel"
```

## Components

[Watch the interactive tutorial on tags in the Imba course](https://scrimba.com/learn/imba/tags-co83d4e259d958441d6c9b8e7)

Tags are compiled down to _extremely optimized_ native [web components](https://developer.mozilla.org/en-US/docs/Web/Web_Components). By default, `data` is the name used to pass values into a tag. Using `data` is simple, but declaring each prop and its type is usually better.

```imba
# Importing a todos array from another Imba file called "data.imba":
import { todos } from './data'

# Declaring a web component without specifying props:
tag todo-item
    <self .completed=data.completed>
        <input bind=data.completed type='checkbox'>
        <span.title> data.title
        <button @click.stop.emit('remove')> 'x'

# Using the todo-item inside another web component:
tag todo-app
    <self> for todo in todos
        <todo-item data=todo>

# Rendering the todo-app with the imported todos array:
imba.mount <todo-app data=todos>
```

## Styles

[Watch the interactive tutorial on inline styles in the Imba course](https://scrimba.com/learn/imba/inline-styles-coe2d48f9a05c7b17e6fb46f7)

In normal HTML you can set inline styles on an element with `style="display: flex;"`. Using classes is often recommended, as keeping track of these inline styles can be slow, brittle, and difficult to work with.

In Imba, inline styles are much more powerful. Keeping elements, styles and logic close together can often be simpler, faster to write, and easier to read.

```imba
<div[display:flex flex-direction:row color:blue]>
<div[opacity:0.5 @hover:1]> # Conditional styles based on pseudostates.
<div[padding:3rem @lg:5rem @print:0]> # Conditional styles based on media queries.
```

### Shorthands

[Watch the interactive tutorial on shorthands in the Imba course](https://scrimba.com/learn/imba/style-property-shorthands-co55547d5954f4b8576d0f730)

Single letter variable names are often considered to be an anti-pattern. Seeing the name `c`, what does it mean? `columns`? `content`? `color`? Reading code with unclear naming costs time and effort.

`c` is shorthand for `color`. But will that always be the case? Could it ever change, and mean `columns` or `content` instead?

```imba
<div[c:blue]>
```

**CSS keywords don't change. Imba shorthands don't change.**

Stability and consistency builds trust. Let's learn one more: `bg` is shorthand for `background`. Knowing both `bg` and `c`, what does the shorthand `bgc` "look like"? `background-color`!

Imba shorthands are bound directly to CSS, and remain stable. This makes Imba shorthands quick to read, write, and understand at a glance. `d` will always mean `display`, `p` will always mean `padding`, `m` will always mean `margin`, and so on.

```imba
<div[display:flex flex-direction:row color:blue]> # Regular keywords
<div[d:flex fld:row c:blue]> # Shorthand keywords
```

Imba developers often say these shorthand names become as familiar and natural as CSS itself, but faster. The Imba tooling gives you the full keyword on hover, and will even suggest the shorthand if you hover the regular CSS keyword.

### Scoping styles

[Watch the interactive tutorial on scoping styles in the Imba course](https://scrimba.com/learn/imba/scoped-styles-co50f4384944f5102c6e6d8ca)

Inline styles apply to the element itself, and everything within it. Changing the scope lets you apply styles to subtrees, components, tags, the entire file, or even globally.

```imba
# Set `global` at the top level to style all <p> elements.
global css p fs:15px

# Set at the top level to style every <p> element in the file.
css p color:blue7 fw:500

tag todo-app
    # Set at the todo-app level to style everything within the tag.
    css .item color:gray8 bg@hover:gray1
    css .item.done color:green8 text-decoration:line-through

    <self> for todo in todos
        <div.item .done=todo.completed> <span> todo.title
```

Styling can also be nested inside tag trees, and be conditionally included.

```imba
tag todo-app
    <self>
        if user.loggedIn # Styling can be conditional.
            css .header bg:green2

        <div.header>
            css .tab # Scoped to the <div.header> only.
                l:flex mx:2 py:1 fw:500
                c:teal6 @hover:teal7 @active:teal9
            <a.tab href='https://github.com/imba/imba'> "GitHub"
            <a.tab href='https://discord.gg/mkcbkRw'> "Chat"

        <div.footer>
            # Not in the <div.header> scope, so the .tab styling is not applied.
            <a.tab href='https://github.com/imba/imba.io'> "Documentation"
```

## Comments

Single-line comments in Imba are any text following `# ` on the same line. The space is required.

```imba
# This is a comment
const name = "imba" # my favorite language
```

Multiline comments are opened and closed with `###`.

```imba
###
This color is my favorite
I need several lines to really
emphasize this fact.
###
const color = "blue"
```

## Types

Type annotations in Imba are compiled to [JSDoc](https://jsdoc.app) comments and are used for intelligent auto-completions and analysis in [Visual Studio Code](https://code.visualstudio.com/).

```imba
const item\string = window.title
```

Annotations are extra useful to create "contracts" between parts of your code. It is faster to understand and re-use tags when their props are annotated, for example.

Annotating is inferred automatically when the value is assigned during declaration.

```imba
def multiply a\number, b\number
    a * b

# Rewriting the todo-tag with annotated props makes it easier to understand and use.
tag todo-item
    completed = no
    title\string

    <self .completed=completed>
        <input bind=completed type='checkbox'>
        <span.title> title
        <button @click.stop.emit('remove')> 'x'
```

Types can also be imported from other `.imba`,`.js`,`.ts`, and `.d.ts` files, if you only want to annotate your code. If we need the actual User class, for example to create a new user with `user = new User()`, then we would need to do a regular import.

```imba
# Only the type is imported:
import type { User } from './models'

tag user-card
    # The User is annotated here, so we only need the type:
    user\User

    <self>
        # We know what kind of object a User is now:
        <p> user.name
        <img src=user.profile alt="Profile picture">
```

---

Source: https://imba.io/docs/basic-syntax/variables

# Variables

Variables are declared using the `let` and `const` keywords. `let` variables can be changed through reassignment, while `const` variables are readonly after the initial declaration. Unlike javascript, multiple declarations per line is not allowed.

```imba
# readonly constant
const one = 123

# single declaration
let a = 123

# array destructuring
let [e,f,...rest] = [1,2,3,4,5]

# object destructuring
let {g,h,data:i} = {g:1,h:2,data:3}

# in conditionals
if let user = array.find(do $1 isa Person)
	yes
```

> **Tip:** In all the examples throughout this documentation you can hover over an identifier to highlight all references to the variable. Identifiers resolving to variables have a different color than identifiers resolving as implicit accessors of self.

## Implicit Self

Any identifier starting with a lowercase letter or `$` that is not previously declared will be treated as an accessor on `self`. This is a crucial concept to understand, especially when coming from JavaScript, where any undeclared variable implicitly refers to the global scope.

```imba
let declared = yes
declared # => yes
undeclared # => the same as this.undeclared
```

As you can see from the examples in this documentation, implicit accessors and resolved variables are highlighted with different colors. This type of semantic highlighting is also supported in the [vscode tooling](https://marketplace.visualstudio.com/items?itemName=scrimba.vsimba).

```imba
const scale = 1

class Rectangle
    def check forced
        forced # found variable named arg - no implicit self
        scale # resolves to variable declared in root
        width # implicit self (no variable named width)
        self.width # explicit self
```

If this concept feels strange and unknown, feel free to explicitly use `self.` as you would in js.

> **Tip:** Uppercased identifiers are not treated as accessors. So `Array`, `Map`, or `SomeIdentifier` will always resolve the same way they do in JavaScript.

Variables are _not_ hoisted in Imba. This means that a reference to a variable before its declaration will behave is if there is no declaration - and instead be an implicit access on self.

```imba
def method
	data # not in scope - same as self.data
	let data = {a:1,b:2}
	data # in scope
```

## Global variables

In addition to identifiers starting with an uppercase letter, there are a few global variables that are always resolved.

<api-list>imba.Globals.own.properties</api-list>
<api-list>imba.Globals.own.methods</api-list>

These identifiers will **not** use implicit self, since they are resolved as global variables. This means that if you have an object with a property `window` or a method named `setTimeout`, you will need to use `self.` when referencing them.

```imba
class Loader
    window

    def setup
        window # Ooops, reference to the global window
        self.window # Pheew, reference to Loader.window
```

## Block Scopes

`if`, `elif`, `else`, `do`, `for`,`while`,`until`,`switch`,`do` create block scopes. This means that any variable declared in the indented code inside these statements are only available within that scope.

```imba
# global scope
let x = 1
if true
	# block scope
	let y = 2
y # not a variable in scope
```

## This vs Self

If you come from js, `this` will be a well-known concept. While `this` still exists, working exactly like its js counterpart, `self` is what you should use in imba. It is a very common pattern in js to need to refer to an outer scope when dealing with callbacks, event listeners and more.

```javascript
setup(){
	var self = this;
	[1,2,3].map(function(){
		self.doSomething();
	})
}
```

This is essentially what `self` does under the hood. In imba, `self` is bound to the closest _selfish_ scope. Besides the root scope of a file, only the scopes of `def`, `get` and `set` are selfish.

```imba
class Item
	def setup
		# selfish scope
		[1,2,3].map do |val|
			# selfless scope
			self # the Item
			this # the array
```

If this looks confusing, fear not – `this` is something you will practically never see or use in imba codebases.

---

Source: https://imba.io/docs/basic-syntax/identifiers

# Identifiers

In imba, identifiers are case-sensitive and can contain Unicode letters, `$`, `_`, `-`, and digits (`0-9`), but may *not* start with a digit. 

An identifier can end with `?` to make it a predicate identifier, thus helping make clear that the value should resolve to a boolean `get empty? do !array.length`. See [Predicate filters](#identifiers-predicate-identifiers)

`$0 .. $n` are reserved identifiers used as shorthands for function arguments with $0 refering to the set of arguments. See [Identifiers with special meanings](#identifiers-identifiers-with-special-meanings)

## Dashed Identifiers
Dashes inside identifiers are perfectly valid in Imba and is often preferred for readability and that it allows to easily skip to each segment of the identifier.

```imba
let my-dashed-var = yes
let object = {dashed-key: 1, other-key: 2}

class Item
    full-name\string

    def rename new-name
        full-name = new-name
```

The only caveat to look out for is that the subtraction operator has to be spaced:
```imba
let number = 100
let wrong = number-items.length # wrong!
let right = number - items.length # right!
```

> **Tip:** Dashes in identifiers are converted to the greek symbol Ksi `Ξ` when compiled to js.

## Predicate Identifiers

Imba also allows `?` at the end of identifiers for methods, properties, and variables. These are called predicate identifiers and should always represent boolean values. They are used to represent a checkable state and provides improved readability over other approaches like predicate prefixes like `isEmpty`.

```imba
tag sized-list
    items = []
    size = 10

    get empty?
        !items.length
```

Using these types of identifiers is entirely optional, and may feel weird initially.

> **Tip:** In JavaScript, optional chaining uses the `?.` operator. For optional chaining in Imba, use `..` like `object..some..key`

## Meta Properties

Identifiers that start with with one or more `#` are called meta properties in Imba. Meta properties are implemented as [symbols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol). They do not show up on an Object using `for in`, `for of`, `Object.getOwnPropertyNames` or `Object.keys`, and they will never conflict with string-based / plain properties on your classes & instances.

```imba
const user = {name: 'Jane', #clearance: 'high'}
user.name # => Jane
user.#clearance # => high
JSON.stringify(user) # => {"name": "Jane"}
```

These properties are especially useful for adding metadata (hence the name) to objects without risking collisions or altering the `public` appearance of the objects. They are used extensively in the imba runtime itself, to extend Element and other core interfaces without fear of conflicts with JS frameworks and libraries.

To access the symbol of a meta property you can call `Symbol.for("#mymetaprop")`.

```imba
const user = {name: 'Jane', #clearance: 'high'}
user.#clearance # => high
user[Symbol.for('#clearance')] # => high
```

## Argument Identifiers

Identifiers `$0`, `$1`, `$2` and so forth are not valid variable names – as they refer to the nth argument in the current function. `$0` is an alias for `arguments` from js, and refers to all the arguments passed into a function.

```imba
# $(n) is a shorter way to reference known arguments
['a','b','c','d'].map do $1.toUpperCase!
['a','b','c','d'].map do(item) item.toUpperCase!
```

## Global Identifiers

Identifiers starting with an uppercase letter are global-first,
meaning that they will not be implicitly scoped.
See [implicit self](https://imba.io/docs/basic-syntax/variables#implicit-self)
for more information.

## Reserved Identifiers

There are a few identifiers that are reserved as keywords in certain contexts. `get`, `set` and `attr` are perfectly valid to use as variables, arguments, and properties, but in class definitions they have a special meaning. Essentially all reserved keywords can still be used as properties.

```imba
a.import
a['import']
a = { import: 'test' }
```

---

Source: https://imba.io/docs/basic-syntax/operators

# Operators

## Arithmethic Operators

### +

```imba
1 + 2 # 3
```

### -

```imba
3 - 1 # 2
```

### /

```imba
6 / 3 # 2
```

### \*

```imba
3 * 2 # 6
```

### %

```imba
5 % 2 # 1
```

### \*\*

```imba
2 ** 3 # 8
```

### -

```imba
-i # Unary negation
```

### +

```imba
+i # Unary plus
```

## Logical Operators

### &&

```imba
null && 10 # null
0 && 10 # 0
1 && 10 # 10
'' && 'str' # ''
```

The logical AND operator is true if all of its operands are true. The operator returns the value of the last truthy operand.

### and

```imba
null and 10 # null
1 and 10 # 10
```

Alias for `&&` operator

### ||

```imba
null || 10 # 10
0 || 10 # 10
1 || 10 # 1
```

The logical OR operator is true if one or more of its operands is true. The operator returns the value of the first truthy operand.

### or

```imba
null or 10 # 10
0 or 10 # 10
1 or 10 # 1
```

Alias for `||` operator

### ??

```imba
null ?? 10 # 10
0 ?? 10 # 0
'' ?? 'str' # ''
```

The nullish coalescing operator `??` is a logical operator that returns its right-hand side operand when its left-hand side operand is `null` or `undefined`, and otherwise returns its left-hand side operand.

### !

```imba
let a = true
!a # false
!10 # false
!0 # true
```

## Comparison Operators

### ==

```imba
x == y # Equality
```

### !=

```imba
x != y # Inequality
```

### ===

```imba
x === y # Strict equality
```

### is

```imba
x is y # Loose equality (==), with support for custom matchers
```

> `is` compiles to `x == y`, with a fallback that lets the right-hand value customize matching by implementing a `Symbol.for('#matcher')` method. Use `===` if you need strict equality.

### !==

```imba
x !== y # Strict inequality
```

### isnt

```imba
x isnt y # Negation of is - loose inequality
```

> `isnt` is the negation of `is`, so it also uses loose equality. Use `!==` if you need strict inequality.

### >

```imba
x > y # Greater than
```

### >=

```imba
x >= y # Greater than or equal
```

### <

```imba
x < y # Less than
```

### <=

```imba
x <= y # Less than or equal
```

### isa

```imba
honda isa Car #
```

The `isa` operator tests whether the prototype property of a constructor appears anywhere in the prototype chain of an object. Alias for the javascript [instanceof](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) operator.

If the right hand side is a string, `isa` will check `typeof` instead:

```imba
let s = 'hello'
typeof s is 'string' # true
s isa 'string' # true
```

It can also check against multiple types at once:

```imba
7 isa ('string' or 'number') # true
```

### !isa

```imba
princess !isa Car
```

### typeof

```imba
typeof item
```

## Assignment Operators

### =

```imba
a = b
```

### ||=

```imba
a ||= b # If falsy assignment
```

### &&=

```imba
a &&= b # If truthy assignment
```

### ??=

```imba
a ??= b # If null assignment
```

### +=

```imba
a += b # Addition assignment
```

### -=

```imba
a -= b # Decrement assignment
```

### \*=

```imba
a *= b # Multiplication assignment
```

### /=

```imba
a /= b # Division assignment
```

### %=

```imba
a %= b # Remainder assignment
```

### \*\*=

```imba
a **= b # Exponential assignment
```

### ++

```imba
a++ # Increment assignment, returns original value
```

### --

```imba
a-- # Decrement assignment, returns original value
```

### ++

```imba
++a # Increment assignment, returns incremented value
```

### --

```imba
--a # Decrement assignment, returns decremented value
```

### =?

```imba
let object = {}
let input = 200
if object.value =? input
    yes
```

Regular assignment that returns true or false depending on whether the left-hand was changed or not. More concise way of doing:
```imba
let object = {}
let input = 200
if object.value != input
    object.value = input
    yes
```
The reassignment may seem unnecessary at first, but since memoization is an oft-used pattern in Imba, this is a very convenient addition.

## Bitwise Operators

### &

```imba
a & b # Bitwise AND
```

### !&

```imba
a !& b # Bitwise NOT AND
```

> Essentially the same as `(a & b) == 0`

### |

```imba
a | b # Bitwise OR
```

### ^

```imba
a ^ b # Bitwise XOR
```

### ~

```imba
~ a # Bitwise NOT
```

### <<

```imba
a << b # Left shift
```

### >>

```imba
a >> b # Sign-propagating right shift
```

### >>>

```imba
a >>> b # Zero-fill right shift
```

### <<=

```imba
a <<= 1 # Left shift assignment
```

### >>=

```imba
a >>= 1 # Right shift assignment
```

### >>>=

```imba
a >>>= 1 # Unsigned right shift assignment
```

### &=

```imba
a &= 1 # Bitwise AND assignment
```

### |=

```imba
a |= 1 # Bitwise OR assignment
```

### ~=

```imba
a ~= 1 # Bitwise NOT assignment (unassignment)
```

### ^=

```imba
a ^= 1 # Bitwise XOR assignment
```

### |=?

```imba
const STATES = {LOADED: 2}
let data = {state: 0}

if data.state |=? STATES.LOADED
    yes
```

Bitwise OR assignment that returns true only if the bit(s) was not previously set. Essentially a concise way to do

```imba
const STATES = {LOADED: 2}
let data = {state: 0}

if (data.state & STATES.LOADED) == 0
    data.state |= STATES.LOADED
    # do something here...
```

### ~=?

```imba
const STATES = {LOADED: 2}
let data = {state: 2}

if data.state ~=? STATES.LOADED
    # the loaded bit was set - now cleared
```

Bitwise unassignment that unsets the right-hand bits from left-hand value and returns true / false depending on whether this actually changed the left-side or not. Essentially a concise way to do

```imba
const STATES = {LOADED: 2}
let data = {state: 2}

if (data.state & STATES.LOADED) != 0
    data.state = data.state & ~STATES.LOADED
    # do something here...
```

### ^=?

```imba
const STATES = {MUTED: 4}
let data = {state: 0}

if data.state ^=? STATES.MUTED
    # the muted bit was toggled on
else
    # the muted bit was toggled off
```

Bitwise XOR (toggle) assignment that flips the right-hand bits on the left-hand value, and returns true if the bits ended up set, false if they ended up cleared. A concise way to express toggling:

```imba
const STATES = {MUTED: 4}
let data = {state: 0}

data.state = data.state ^ STATES.MUTED
if (data.state & STATES.MUTED) != 0
    # the muted bit was toggled on
else
    # the muted bit was toggled off
```

## Optional chaining

Imba uses `..` for [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining). If the optional reference is nullish it will return undefined.

```imba
let object = {one: {value: 1}}
console.log object..two..value
# undefined
console.log object.two.value
# TypeError: Cannot read property 'value' of undefined
```

## Keywords

### delete

```imba
let object = {one: 1, two: 2}
delete object.one
```

### class

```imba
class Game
	turn
	tiles
	moves
	winner

	def constructor
		moves = []
		tiles = new Array(9)
		turn = 0
```

### switch

```imba
switch status
    when "completed"
        console.log "This project has been completed"
    when "archived"
        console.log "This project has been archived"
    else
        console.log "This project is active"
```

### for

```imba
for num in [1,2,3]
	num * 2
```

```imba
for item in items
	<li> item.name
```

```imba
for item, i in items
	<li> "{i+1}: {item.name}"
```

### get

```imba
class Item
    price = 100
    taxRate = 20

    get totalPrice
        price * (1 + taxRate / 100)

    def render
        <self>
            <input bind=price>
            <input bind=taxRate>
            <p> "Total: {totalPrice}" # 120

```

### set

```imba
class Item
    set name value
        console.log "The name has been set to", value
```

### def

```imba
  def multiply a, b
    a * b

  # default values
  def method name = 'imba'
    console.log param

  # destructuring parameters
  def method name, {title, desc = 'no description'}
    console.log name,title,desc
```

### attr

```imba
<form attr:id="product-form">
```

### tag

```imba
# Define a new global tag component
tag page-header
  ...
```

```imba
# Define a new local tag component
tag Header
  ...
```

### if

```imba
  if condition
	  console.log 'yes!'
```

### elif
```imba
if expr > 10
	console.log 'over 10'
elif expr > 5
	console.log 'over 5'
elif expr
	console.log 'not falsy'
```

### else

```imba
if condition
	console.log 'yes!'
else
	console.log 'no!'
```

### try

```imba
def fetch
    # adding a try without a catch block will silently swallow an erro
    try
      const result = await axios.get('my-api.com')
```

### catch

```imba
  def fetch
    try
      const result = await axios.get('my-api.com')
    catch e
      console.error "There was an error", e
```

### continue

```imba
let res = for num in [1,2,3,4,5]
	continue if num == 3
	num * 2
console.log res # [2,4,8,10]
```

```imba
# continue with an argument acts like early return within Array#map
let res = for num in [1,2,3,4,5]
	continue -1 if num == 3
	num * 2
# res => [2,4,-1,8,10]
```

### break

```imba
let res = for num in [1,2,3,4,5]
	break if num == 3
	num * 2
# res => [2,4]
```

```imba
# When supplying an argument to break
# this value will be added to the resulting array
let res = for num in [1,2,3,4,5]
	break -1 if num == 3
	num * 2
```

### return

```imba
 # In Imba the last statement is returned automatically
 def add a, b
   a + b
```

```imba
# But it can be useful for returning other values or early
def add a, b
  return 0 unless a && b
  a + b
```

---

Source: https://imba.io/docs/basic-syntax/functions

# Functions

When we talk about functions in Imba, we refer to anonymous / inline functions declared with the `do` keywords. See methods.

## Defining functions

```imba
# defining a function
const square = do(num) num * num

# inside an object
const util =
    upcase: do(str) str.toUpperCase!
    downcase: do(str) str.toLowerCase!
```

Function scopes are selfless, meaning that `self` inside their function bodies will refer to the closest lexical _selfish_ scope. See more about this in the section on Scoping.

### Default parameters

```imba
const multiply = do(a, b = 1)
    a * b
```

### Rest parameters

```imba
def add num, ...rest
    for item in rest
        num += item
    return num

add 1,2,3,4,5
```

### Destructuring parameters

```imba
def draw {size = 'big', coords = {x:0, y:0}, radius = 25}
	console.log size,coords,radius

draw coords:{x: 18, y:30}, radius:30
```

## Calling functions

Defining a function does not execute it. Defining it simply names the function and specifies what to do when the function is called. Accessing a function does not execute it either. If an object has a property `transform`, `object.transform` merely references that function.

When you call a function with arguments, parenthesis are optional.

```imba
# the following expressions are equivalent
console.log('hello')
console.log 'hello'
```

If you want to call a function without arguments, you have two options. Either with an empty pair of parenthesis, or with a `!`, which we call _bang invocation_ in Imba.

```imba
# the following expressions are equivalent
Math.random()
Math.random!
```

### Callbacks

Many functions expect another function as an argument. These are often referred to as callbacks. To take a classic example, `Array.map` creates a new array populated with the results of calling a provided function on every element.

Since this is a common pattern, inline anonymous functions can be passed in

```imba
[1,2,3].map do(item)
    item * 2 # [2,4,6]
```

The convention is usually to take the callback as the last argument, but not always.

```imba
setTimeout((do
    console.log 'waited!'
    [1,2,3].reduce((do(sum,value)
        sum + value
    ),0)
),1500) # looks pretty messy
```

When functions expect callbacks as their first (or not-last) argument, you can use `&` as a placeholder for the callback. The `&` is simply a reference to the callback that is supplied at the end of the invocation.

```imba
setTimeout(&,1500) do
    console.log 'waited!'
    [1,2,3].reduce(&,0) do(sum, value)
        sum + value
```

### Positional Arguments

You can refer to positional arguments from within functions with `$n` if you don't want to explicitly name them.

```imba
[1,2,3,4,5].filter do $1 > 3
```

## Amperfuncs

Tiny functions that just look something up or check a condition on their argument are incredibly common. Inspired by Ruby, Imba has an even shorter syntax for these — we call them _amperfuncs_. Inside an expression, `&` generates an inline function, where `&` refers to the first argument of that function:

```imba
const people = [
	{name: 'Joe', age: 28}
	{name: 'Jane', age: 32}
	{name: 'Pete', age: 15}
]

people.map(&.name) # ['Joe','Jane','Pete']
people.filter(&.age > 18) # [{name: 'Joe'...}, ...]
```

So `&.name` compiles to `do(v) v.name`. The three callbacks below are equivalent — each style a bit shorter than the previous:

```imba
people.map do(person) person.name
people.map do $1.name
people.map(&.name)
```

The generated function is not limited to a single property lookup. The body extends to the whole surrounding expression — property chains, method calls, comparisons and logical operators are all included, and every `&` in the expression refers to the same argument:

```imba
people.map(&.name.toUpperCase!) # ['JOE','JANE','PETE']
people.find(&.age == 32) # {name: 'Jane', age: 32}
people.filter(&.age > 18 and &.age < 30) # [{name: 'Joe'...}]

const nums = [1,2,3,4,5]
nums.filter(& > 2) # [3,4,5]
nums.filter(& % 2 == 0) # [2,4]
nums.filter(& in [2,3]) # [2,3]
[1,'a',2].filter(& isa 'number') # [1,2]
```

Amperfuncs are plain functions, so you can also assign them to variables and pass them around:

```imba
const getName = &.name
getName(people[1]) # 'Jane'
```

They may also reference variables from the surrounding scope:

```imba
def adults people, limit = 18
    people.filter(&.age >= limit)
```

> When an amperfunc only references its own argument, Imba hoists the generated function and reuses a single instance — `people.map(&.name)` does not allocate a new closure on every call. This also gives the function a stable identity, which plays nicely with Imba's memoized rendering.

Amperfuncs are meant for concise lookups and predicates, not general computation. Arithmetic like `& + 1` or `& * 2` is not supported — use `do $1 + 1` for those. And since `&` always refers to the first argument, reach for `do` with named or positional parameters when you need more than one.

Also note that a lone `&` in an argument list — like `setTimeout(&,1500) do ...` — is the [callback placeholder](#calling-functions-callbacks) described earlier, not an amperfunc. The `&` only generates a function when it is followed by `.` or an operator.

---

Source: https://imba.io/docs/basic-syntax/control-flow

# Control Flow

## For-In Loops

For in is the basic syntax for looping through arrays and any other object that has a `length` property and allows accessing their members through `object[index]`. This includes `Array`, `NodeList`, `DOMTokenList`, `String` and more. It was created before `for of` iterables became standard in ES2015, but is still a practical alternative to using `for of` in many cases. Imba `for in` is not to be confused with `for in` [in javascript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...in).

```imba
for num in [1,2,3]
    num * 2
```

### Index parameter

If you include a second parameter in the source it will automatically refer to the index of the current iteration.

```imba
for num,index in [1,2,3]
    console.log num * index
# => [1,4,9]
```

### Stepping with `by`

To step through an iterable in fixed-size chunks, use `by`

```imba
# go through every other element
for num in [1,2,3] by 2
    num * 2
```

### Filtering with `when`

You can include a condition using the `when` clause. This will make sure the iteration only executes for members that match said condition.

```imba
# go through every other element
for num,i in [1,2,3] when i % 2
    console.log num
```

### For-In with ranges

```imba
# from 0 up to (including) 3
for num in [0 .. 3]
    num
# => [0,1,2,3]
```

```imba
# from 0 up to (excluding) 3
for num in [0 ... 3]
    num
# => [0,1,2]
```

> Ranges **must include spaces** around `..` and `...`

### For-In with non-arrays

When Imba cannot infer that an object is an array during compilation it will behind the scenes look for a `toIterable` method on the object before looping. This way one can make any type of object easily support being iterated using a `for in` loop.

```imba
class LabelString
    def constructor label
        label = label

    def toIterable
        console.log 'called toIterable'
        label.split(',')

let labels = new LabelString 'idea,proposal,duplicate'

for label in labels
    console.log label.toUpperCase!
```

## For-Of Loops

The for...of statement creates a loop iterating over iterable objects, including: built-in String, Array, array-like objects (e.g., arguments or NodeList), TypedArray, Map, Set, and user-defined iterables. This maps directly to `for of` [in javascript](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of) with a few convenient additions.

### Iterating over an `Array`

```imba
let iterable = [10,20,30]
for value of iterable
    console.log value
```

### Iterating over a `String`

```imba
let iterable = 'imba'
for value of iterable
    console.log value
```

### Iterating over a `TypedArray`

```imba
let iterable = new Uint8Array([0x00,0xff])
for value of iterable
    console.log value
```

### Iterating over a `Map`

```imba
let iterable = new Map([['a',1],['b',2],['c',3]])
for entry of iterable
    console.log entry

# destructuring
for [key,value] of iterable
    console.log value
```

### Iterating over a `Set`

```imba
let iterable = new Set([1, 1, 2, 2, 3, 3])
for value of iterable
    console.log value
```

### Iterating over the arguments object

```imba
def fn
    for arg of arguments
        arg * 2
console.log fn(1,2,3) # => [2,4,6]
```

### Iterating with index parameter

In Imba you can supply a second parameter to `for ... of`. This will be populated with the current iteration number (starting at 0), just like the second argument in `Array#map` and `Array#forEach`.

```imba
let iterable = new Map([['a',1],['b',2],['c',3]])
for entry,idx of iterable
    console.log entry,idx
for [key,value],idx of iterable
    console.log key,value,idx
```

### For-Own-Of

A pretty common need is to loop through the key-value pairs of objects. The default recommended way to do this in JavaScript is:

```javascript
let obj = { a: 1, b: 2, c: 3 };
for (const [key, value] of Object.entries(obj)) {
	console.log(`${key}: ${value}`);
}
```

Since this is a common pattern - Imba has specific support for this using `for own ... of`. This statement creates a loop iterating over key-value pairs of objects.

```imba
let obj = {a: 1, b: 2, c: 3}
for own key,value of obj
    console.log "{key} is {value}"
```

## While Loops

Executes repeatedly as long as condition is truthy.

```imba
let ary = [1,2,3]
while let item = ary.pop!
    console.log item
```

## Until Loops

Executes repeatedly **until** condition is truthy.

```imba
let ary = [1,2,3]
until ary.length == 0
    console.log ary.pop!
```

## Continue

`continue` is supported in all loop types (`for in`, `for of` and `for own of`)

```imba
let res = for num in [1,2,3,4,5]
    continue if num == 3
    num * 2
console.log res # [2,4,8,10]
```

```imba
let res = for num in [1,2,3,4,5]
    break if num == 3
    num * 2
# => [2,4]
```

### Continue with value

When supplying an argument to continue, this value will be added to the resulting array, essentially like an early return would do in an `Array#map` function.

```imba
let res = for num in [1,2,3,4,5]
    continue -1 if num == 3
    num * 2
# continue with an argument acts like early return within Array#map
# => [2,4,-1,8,10]
```

## Break

`break` is supported in all loop types (`for in`, `for of` and `for own of`)

```imba
let res = for num in [1,2,3,4,5]
    break if num == 3
    num * 2
# => [2,4]
```

### Break with value

You can also supply an argument to break. When supplying an argument to break, this value will be added to the resulting array. This is especially useful when you want to return until some condition is met, but also want to include the item at which condition was met.

```imba
let res = for num in [1,2,3,4,5]
    break -1 if num == 3
    num * 2
```

## Conditionals

### If

The if statement executes the indented code if a specified condition is truthy.

```imba
# indented
if condition
    console.log 'yes!'
```

### Unless

The unless statement executes the indented code if a specified condition is _not_ truthy.

```imba
unless condition
    console.log 'condition was not truthy'
```

> The unless statement executes the indented code if a specified condition is _not_ truthy.

### Else

If the condition is falsy, code inside the connected else block will execute.

```imba
if condition
    console.log 'yes!'
else
    console.log 'no!'
```

### Chaining conditionals

To conveniently chain multiple conditionals, use `elif`. No `elif` or `else` statements will be executed after the first truthy condition.

```imba
if expr > 10
    console.log 'over 10'
elif expr > 5
    console.log 'over 5'
elif expr
    console.log 'not falsy'
```

### Trailing condition

If & unless can also be used at the end of a single line expression

```imba
console.log 'yes' if condition
console.log 'no' unless condition
```

### Ternary operator

The [Ternary operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator) is a useful way to write compact if / else statements.

```imba
condition ? console.log('yes!') : console.log('no!')
```

## Switch

```imba
switch value
    when 10
        yes
    when 5
        no
    else
        throw 'nope'
```

## Await

Imba supports the `await` keyword, which compiles directly to async/await in JavaScript. The only difference is that you do not need to mark your functions as async. Any function that contains an await will automatically be compiled to an async function.

```imba await.imba
def load url
    let res = await window.fetch url
    return res.json

let data = await load "/some/url"
```

#### Without await using promises
```imba
def load url
    window.fetch(url).then do(res)
        return res.json

load("/some/url").then do(data)
    # do something with data
```

## Error Handling

For error handling you can throw exceptions using the `throw` statement and handle them using the `try` and `catch` statements. Adding a `try` without a `catch` block will silently swallow the error.

```imba app.imba
def run
    # adding a try without a catch block will silently swallow an error
    let test = try JSON.parse('{not valid json}')
    return test # undefined - the parse error was swallowed
console.log run! # undefined
```

```imba
def parse input
    try
        return JSON.parse input
    catch e
        console.error "Invalid json passed to parser: ", e.message

parse('<invalid json, error here we come!>')
```
> Invalid json passed to parser:  Unexpected token < in JSON at position 0

---

Source: https://imba.io/docs/basic-syntax/classes

# Classes

Classes are general-purpose, flexible constructs that become the building blocks of your program's code. You define properties and methods to add functionality to your classes using the same syntax you use to define constants, variables, and functions. Classes in Imba are compiled directly to native [JavaScript Classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).

## Defining Classes

```imba
class Rect
    # custom constructor
    constructor w,h
        width = w
        height = h

    # class method
    def expand hor,ver = hor
        width += hor
        height += ver

    # getter
    get area
        width * height

    # setter
    set area size
        width = height = Math.sqrt size
```

## Creating Instances

The `new` keyword will let you create an instance of your class. This instance inherits properties and methods from its class.

```imba
let fido = new Dog
```

## Class Constructors

Use the `constructor` keyword to declare a custom constructor method for your class. This method will be executed whenever an instance of the class is created (using the `new` keyword).

```imba
class Rect
    constructor w,h
        width = w
        height = h
    # ...
```

## Instance Methods

You can add methods to your class instances using the `def` keyword, followed by the method name and optional arguments.

```imba
class Rect
    def expand hor,ver = hor
        width += hor
        height += ver
```

## Class Fields

Instance fields exist on every created instance of a class. By declaring a field, you can ensure the field is always present, and the class definition is more self-documenting. See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Public_class_fields) for more details.

```imba
class Rect
	width = 10
	height = 10
```

> instances of Rect will always be initialized with width and height set to 10.

The scope after `=` in a class field refers to the instance itself, so class fields can also reference other properties and methods.

```imba
class Rect
	width = 10
	height = 10
	area = width * height

console.log (new Rect).area # 100
```

## Computed Properties

You can add computed properties to your class instances using the `get` keyword followed by the name of the property. The `get` syntax binds an object property to a function that will be called when that property is looked up

```imba
class Rect
    get area
        width * height
```

Using `set` you can define a function that will be called when there is an attempt to set that property.

```imba
class Rect
    set sides value
        width = value
        height = value
```

You can define setters which are to be called whenever there is an attempt to set that property.

## Lazy Getters

Any getter is bound only when first accessed. A lazy getter will in addition only determine its value the first time it is accessed and from then on return the initial value which can be memoized. This is done with a falsy assignment `||=`.

```imba
class Component
    # The symbol #ref is only set the first time Component.ref is accessed
    get ref
        #ref ||= utils.uuid! 
```

## Computed Names

You can define methods, getters and setters with computed names using `[]`.

```imba
let method = 'items'
let getter = 'title'

class Todo
    get [getter]
        data[getter]

    def [method]
        console.log "called method {method}"

let todo = new Todo
todo.items! # called method items
todo.title
```

## Meta Properties

Upcoming versions of JavaScript has support for "private fields" using the `#` prefix for properties. Imba has a similar syntax that serves a similar purpose. See [Meta Properties]. Meta properties can be used in classes for method, fields, and other properties.

Meta properties are implemented as symbols, They do not show up on an Object using `for in`, `for of`, `Object.getOwnPropertyNames` or `Object.keys`, and they will never conflict with string-based / plain properties on your classes & instances. These are useful for a wide variety of things and are used extensively in the imba runtime itself.

You may often find yourself defining setters because you want to do something when a property is set. The problem is that a property with a setter cannot also store an actual value with the same name. The idiomatic way to store underlying values in setters is to use a meta property with the same name:

```imba
class Todo
    set title value
        # do something here
        #title = value

    get title
        #title
```

This is also useful if you want to declare memoized / lazy fields, where the value of the field should not be initialized until the first time it is accessed.

```imba
class Component
    get ref
        #ref ||= utils.uuid!
```

Let's say we want to add a `#ref` property to _all objects_ - that returns a unique id for every object. As in the example above, we only want to create the id if/when it is accessed. We don't want to pollute every object with a visible textual `ref` property that may interfere with other code and libraries, so we use a meta property for this.

```imba
const map = new WeakMap

extend class Object
    get #ref
        map.set(self,utils.uuid!) unless map.has(self)
        return map.get(self)
```

The above approach of using a WeakMap to store the actual metadata is common, and even the way Babel and other transpilers usually implement private fields today. But weakmaps are quite slow and clunky. Remember that meta properties start with one _or more_ `#` characters. The convention in Imba is to always prepend an additional `#` for each nested level of indirectness. So, instead we would extend Object like this:

```imba
extend class Object
    get #ref
        ##ref ||= utils.uuid!
```

Now you will be able to access `#ref` on _all_ objects.

```imba
const object = {}
object.#ref # '... uuid ...'
# Even built in objects now have this property
window.#ref
```

### Extending native types

You can also use meta properties for methods and class fields. Since they are not enumerable, and won't collide with native methods from JavaScript it is great if you want to extend native prototypes. Imba adds a bunch of methods to the native Node / Element classes in your browser, but to be sure that it does not interact with other libraries, these methods are implemented using meta properties.

```imba
extend class Node
    def #append node
        # setup some listeners etc
        appendChild(node)
```

In your own projects you could even add functionality to _all_ objects without worry using meta properties.

```imba
const map = new WeakMap

extend class Object
    get #ref
        map.set(self,Symbol()) unless map.has(self)
        return map.get(self)

# Now you will be able to access `.#ref` on _all_ objects,
# and get a unique symbol back every time.
const object = {}
object.#ref # Symbol()
```

### Private or not?

Unlike in js, these properties are not strictly private. You can access them from outside just like other properties. So if a class has a method called `#synchronize`, you _can_ call it from outside by `instance.#synchronize!`. At the same time, meta properties are usually used for "internals".

## Static Properties

Methods, fields and computed properties can also be defined on the class itself, as opposed to its instances, by including the `static` keyword before each declaration.

```imba
class Rect
	static size = 50
	size = 100
console.log Rect.size # 50
console.log (new Rect).size # 100
```

```imba
class Rect
	static def build side
		let item = new self
		item.width = item.height = side
		return item

Rect.build(10)
```

## Class Inheritance

An important feature of Classes is the ability to inherit from other classes. For example, a Dog is also an Animal, so it makes sense to inherit the properties of an Animal so that if we ever update the Animal class, the Dog's class will also be updated. It will also help us keep our code light.

```imba
class Animal
	constructor name
		name = name

    def move distance = 0
        console.log "Animal moved {distance} meters."

    def speak
        console.log "{name} makes a noise."

class Dog < Animal
    def speak
        console.log "{name} barks."

let dog = new Dog 'Mitzie'
dog.move 10 # Animal moved 10 meters.
dog.speak! # Mitzie barks.
```

An inherited class will inherit all methods and functionality from the parent class.

If the heritor class accesses any variables or functions on self in its constructor, the constructor must first call `super`.

```imba
class Animal
	constructor name
		name = name

class Dog < Animal
    constructor name, breed
        super # calls Animal constructor with the same arguments (name, breed).
        # super(name) # This would be an explit way to achieve the same effect
        breed = breed

let dog = new Dog 'Mitzie', 'Pug'
console.log dog.name
dog.speak! # Mitzie barks.
```

### Using `super`

##### super

```imba
class Designer < Person
	def greet greeting
        console.log 'will greet'
		super # same as super.greet(...arguments)
```

Lone `super` is treated in a special way. It is always equivalent to calling the same method in super class, passing along the arguments from the current method.

##### super ( arguments )

```imba
class Designer < Person
	def greet greeting
		super "Hey {greeting}" # same as super.greet
```

##### super.property

```imba
class Animal
	constructor name
		name = name

    def move distance = 0
        console.log "Animal moved {distance} meters."

    def speak
        console.log "{name} makes a noise."

class Dog < Animal
    def speak
        console.log "{name} barks."

    def move distance = 0
        super.speak! # call the Animal#speak method directly!
        console.log "{name} ran {distance} meters."

let dog = new Dog 'Mitzie'
dog.move 10 # Mitzie makes a noise. Mitzie ran 10 meters.
```

## Mixins

Classes can only inherit from a single superclass, but you will often want to share behaviour between classes that don't belong in the same hierarchy. Mixins solve this. A mixin is declared with the `mixin` keyword and looks just like a class — it can contain methods, getters, setters, and fields:

```imba
mixin Walks
	def walk
		"walking"

mixin Swims
	def swim
		"swimming"
```

To include a mixin, add an `isa` declaration in the class body. A class can include any number of mixins:

```imba
class Duck
	isa Walks
	isa Swims

let duck = new Duck
duck.walk! # 'walking'
duck.swim! # 'swimming'
```

The `isa` operator recognises mixins as well, so you can check whether an object includes a mixin the same way you would check for a class:

```imba
duck isa Walks # true
duck isa Duck # true
```

Mixins work for tags as well:

```imba
mixin Draggable
	def startDrag e
		# ...

tag draggable-box
	isa Draggable
```

### How mixins are applied

When a class includes mixins, Imba inserts a hidden intermediate class between the class and its superclass, and copies the mixin members onto it. Understanding this makes the behaviour easy to predict:

- Members defined in the class itself always override mixin members.
- If several mixins define the same member, the last `isa` declaration wins.
- `super` behaves as if the mixin members were defined on a superclass.

```imba
mixin Greeter
	def greet
		"hello"

class Base
	def greet
		"base"

class Person < Base
	isa Greeter

	def greet
		"{super} world" # resolves to Greeter#greet, not Base#greet

let person = new Person
person.greet! # 'hello world'
```

Since `Person` includes the `Greeter` mixin, `super` inside `greet` finds the mixin's implementation first — the real superclass `Base` sits behind the mixins in the chain.

### Fields in mixins

Fields declared in a mixin are initialized on every instance of the including class, just as if they had been declared in the class itself:

```imba
mixin Identifiable
	uuid = Math.random!

class Order
	isa Identifiable

(new Order).uuid # 0.1017...
```

A mixin cannot contribute a custom `constructor` — it is ignored when the mixin is applied. Use field declarations for per-instance setup instead.

### Mixins inheriting from mixins

A mixin can inherit from another mixin. Including it automatically brings in the whole chain:

```imba
mixin Walks
	def walk
		"walking"

mixin Runs < Walks
	def run
		"running"

class Athlete
	isa Runs # includes Walks as well

let athlete = new Athlete
athlete.walk! # 'walking'
athlete isa Walks # true
```

Mixins can also include other mixins with `isa` declarations in their body, just like classes.

### Mixins with a class superclass

A mixin may declare a regular class as its superclass. This constrains where it can be used — only classes that already inherit from that superclass may include it. In return, the mixin can safely use methods and properties from that superclass:

```imba
class Vehicle
	def start
		"vroom"

mixin Turbo < Vehicle
	def boost
		"{start!}!!!"

class Car < Vehicle
	isa Turbo # ok - Car inherits from Vehicle

(new Car).boost! # 'vroom!!!'
```

Trying to include such a mixin in a class that does not inherit from `Vehicle` will throw an error.

## Reopening Classes

Any class can be reopened later using `extend class` — adding new methods, getters, and setters to a class that has already been defined. This works for your own classes, classes imported from libraries, and even native classes:

```imba
class Model
	def save
		console.log 'saving'

# somewhere else - possibly in a different file
extend class Model
	def fetch
		console.log 'fetching'

let model = new Model
model.fetch! # 'fetching'
```

Reopening patches the class itself, so all instances — including ones created before the extension — get the new members immediately. This is how Imba adds functionality to native `Element` and `Node` classes in the browser. When extending native or third-party classes, it is a good idea to use [meta properties](#meta-properties) to avoid colliding with other code.

Tags can be reopened the same way with `extend tag`. Extending the lowercase `element` tag makes members available on _all_ elements:

```imba
extend tag element
	get appState
		globalAppState
```

### Overriding with super

When you redefine an existing method, getter, or setter in a class extension, `super` refers to the implementation you are replacing — whether it came from the class itself or from its superclass chain:

```imba
class Logger
	def log msg
		console.log msg

extend class Logger
	def log msg
		super "[log] {msg}" # calls the original implementation

let logger = new Logger
logger.log 'hello' # '[log] hello'
```

This makes class extensions a powerful way to wrap or instrument existing behaviour without touching the original definition.

### Dynamic extensions

`extend class` also accepts a class stored in a variable, and members can have computed names. This makes it possible to write utilities that patch classes at runtime:

```imba
class Item
	def one
		1

def patch cls, key, value
	extend class cls
		def [key]
			super + value

let item = new Item
patch(Item,'one',10)
item.one! # 11
```

### Limitations

Class extensions can only add instance-level members — methods, getters, and setters. `static` members are not supported, and fields with initial values are not allowed, since no constructor runs for instances that already exist. If you need per-instance state in an extension, use a lazy getter with a meta property instead:

```imba
extend class Model
	get items
		#items ||= []
```

### Reopening mixins

Mixins can be reopened too, using `extend mixin`. New members propagate to every class that already includes the mixin — even to existing instances:

```imba
mixin Logger
	def log msg
		console.log msg

class Model
	isa Logger

let model = new Model

extend mixin Logger
	def warn msg
		console.warn msg

model.warn 'watch out!' # works - Model picked up the new method
```

You can also add mixins to an already defined class by reopening it:

```imba
mixin Serializer
	def serialize
		JSON.stringify(self)

class Model
	name = 'model'

extend class Model
	isa Serializer

(new Model).serialize! # '{"name":"model"}'
```

---

Source: https://imba.io/docs/field-descriptors

# Fields

Besides [decorators](https://imba.io/docs/decorators) for methods, Imba has a related syntax for fields. A field declared with a *descriptor* hands complete control over how that property is stored, read, and written to an object that you define:

```imba
class Person
	name @string
	age @number(min: 0, max: 150) = 30
	email @string.trim.lowercase
```

There is nothing special about `@string` and `@number` here — they are not built into the language. They resolve to regular methods (or classes) that you define yourself, making this a fully customizable way to create extensible field types at the language level. Frameworks use this to build rich, self-describing models where a single line like `owner @ref(User)` can imply validation, persistence, indexing and more.

## Defining a descriptor

When you declare `age @number`, the `age` property compiles into a getter/setter pair backed by a *descriptor* — an object created the first time the field is accessed. Every read of the property goes through the descriptor's `$get` method, and every write goes through `$set`.

The descriptor is produced by a *factory* — a method named `@number` looked up on the instance itself. Define it in the class, a superclass, or a mixin:

```imba
class Model
	def @number options = {}
		const min = options.min ?? -Infinity
		const max = options.max ?? Infinity
		{
			$set: do(value, target, key)
				target[key] = Math.min(Math.max(value, min), max)
			$get: do(target, key)
				target[key]
		}

class Person < Model
	age @number(min: 0, max: 150)

let person = new Person
person.age = 200
console.log person.age # 150
person.age = -20
console.log person.age # 0
```

Since factories are resolved dynamically through the prototype chain, any class in the hierarchy can add new field types, and subclasses can override the ones they inherit. This is the core of the extensibility.

The arguments to `$get` and `$set` are:

- `value` — the value being assigned (only for `$set`)
- `target` — the object instance the field belongs to
- `key` — a unique symbol for this field. Use `target[key]` as the backing storage — it will never collide with other properties.
- `name` — the name of the field as a string (`'age'`)

## Descriptor lifecycle and caching

The descriptor is created lazily on first access, then passed to the runtime which by default caches it on the class prototype. This means **one descriptor object is shared by all instances of the class** — treat it as per-field configuration, not per-instance state. Per-instance data belongs on `target[key]`.

A descriptor can customize this by implementing `$accessor`:

- `$accessor(target, key, name, slot, context)` — called once when the descriptor is first used. `context` is the class prototype and `slot` is the symbol used for caching. Whatever `$accessor` returns is used as the actual accessor. Assign `context[slot] = self` to cache it like the default does, or skip caching to create fresh state per use.
- If the descriptor has no `$init` method, the runtime assigns `$init = $set` — `$init` is used instead of `$set` when a field value is applied during object initialization.

## Arguments and chained modifiers

Arguments in the declaration are passed to the factory:

```imba
age @number(min: 0, max: 150)
```

Descriptors can also be configured with a chain of modifiers after the factory name:

```imba
email @string.trim.lowercase
nick @string.max(20)
```

Each modifier in the chain configures the descriptor object after it is created. For every `.part`:

- If the descriptor has a *method* with that name, it is called with the supplied arguments — `desc.max(20)`.
- Otherwise the name is set as a plain *property* — `desc.trim = yes`, or `desc.max = 20` when an argument is given.

So the chain above is roughly equivalent to:

```imba
let desc = self.αstring! # created via def @string
desc.trim isa Function ? desc.trim! : (desc.trim = yes)
desc.max isa Function ? desc.max(20) : (desc.max = 20)
```

This lets simple descriptors treat modifiers as flags while more advanced ones expose a fluent configuration API — the declaration site looks the same either way.

## Default values

A field with a descriptor can still declare a default value:

```imba
role @string = "member"
retries @number = 3
```

The default is *not* assigned directly. Instead the compiler attaches it to the descriptor as `desc.default` — a function returning the value. When the default is a literal, the raw value is also available as `desc.default.literal`. Your descriptor decides when and how to apply it:

```imba
class Model
	def @string
		{
			$set: do(value, target, key)
				value = String(value)
				value = value.trim! if this.trim
				value = value.toLowerCase! if this.lowercase
				value = value.slice(0, this.max) if this.max
				target[key] = value
			$get: do(target, key)
				let value = target[key]
				if value === undefined and this.default
					value = this.default!
				value
		}

class User < Model
	email @string.trim.lowercase
	nick @string.max(3)
	role @string = "member"

let user = new User
user.email = "  Jane@Example.COM "
console.log user.email # jane@example.com
user.nick = "Roberta"
console.log user.nick # Rob
console.log user.role # member
```

Note that inside `$get` and `$set`, `this` refers to the descriptor object itself — which is how the example above can check the `trim`, `lowercase` and `max` settings from the modifier chain.

## Block callbacks

A field declaration can end with a `do` block. The function is attached to the descriptor as `desc.callback`:

```imba
class Order
	total @memo do
		items.reduce(&, 0) do(sum, item) sum + item.price
```

This is how computed / memoized field types receive the function to evaluate — the descriptor decides when to invoke it and how to cache the result.

## Descriptors as classes

If the descriptor name resolves in the lexical scope — a module-level definition or an import — it is instantiated with `new` instead of being looked up as a method. That means a class works directly as a descriptor factory, giving each field its own instance:

```imba
class @logged
	def $set value, target, key, name
		console.log "setting {name} to {value}"
		target[key] = value
	def $get target, key
		target[key]

class Doc
	title @logged
	body @logged

let doc = new Doc
doc.title = "Hello" # setting title to Hello
console.log doc.title # Hello
```

Descriptor factories can be exported and imported like any other identifier:

```imba
import {@prop} from 'imba'

class Person
	name @prop
```

Imba ships with an `Accessor` class (the class behind `@prop`) that implements the protocol with sensible defaults, including a `watch` method for observing changes — it is a convenient base class for your own descriptors:

```imba
import {Accessor} from 'imba'

class @tracked < Accessor
	def $set value, target, key, name
		console.log "{name} changed"
		super
```

## Other details

- Field descriptors work in `tag` declarations exactly like in classes.
- `static` fields support descriptors too — the descriptor is cached on the class itself rather than the prototype.
- An arbitrary expression can be used as a descriptor with `@(expression)` — the expression is evaluated (once, lazily) and its result is used directly as the descriptor object.

## Use cases

Field descriptors move behavior that would otherwise be scattered across getters, setters, and constructors into small reusable objects with a name. Some patterns they are particularly good at:

### Validation and normalization

Since every write goes through `$set`, rules like clamping, trimming, and coercion live in one place and apply everywhere the field is assigned — the examples earlier on this page ([clamped numbers](#defining-a-descriptor), [normalized strings](#default-values)) are variations of this pattern. The assigning code never needs to know the rules exist.

### Self-describing models

This is the pattern frameworks build ORMs and schemas on. Define the field vocabulary once in a base class, and every model declares its shape in a few readable lines:

```imba
class Issue < Model
	title @string.required
	status @enum('open', 'closed') = 'open'
	owner @ref(User).index
	comments @children(Comment)
	created @timestamp
```

None of these are built into Imba — they are methods on `Model`. Each declaration can carry everything the framework needs to know about the field: how to validate it, how to persist it (down to the database column type), whether to index it, how relations resolve, even which form control to render for it. All of that metadata lives on the descriptor object where the framework can read it back — the model describes itself.

### Computed fields

With [block callbacks](#block-callbacks), a descriptor receives a function and full control over when to call it — enabling memoized or computed fields where the descriptor decides how results are cached and invalidated.

### Custom storage

Nothing forces a descriptor to store values on the instance. `$get` and `$set` can read and write anywhere — `localStorage`, a `WeakMap`, a server. Here is a settings object whose fields transparently persist across page loads:

```imba
class Settings
	def @setting
		{
			$set: do(value, target, key, name)
				window.localStorage.setItem("settings:{name}", JSON.stringify(value))
			$get: do(target, key, name)
				let raw = window.localStorage.getItem("settings:{name}")
				raw !== null ? JSON.parse(raw) : (this.default and this.default!)
		}

	theme @setting = 'light'
	volume @setting = 8

let settings = new Settings
console.log settings.theme # light - or dark if you ran this before!
settings.theme = 'dark'
console.log settings.theme # dark
```

### Change tracking

A descriptor sees every write, making it a natural hook for dirty-tracking, undo journals, syncing to a server, or notifying interested parties:

```imba
class Model
	def @tracked
		{
			$set: do(value, target, key, name)
				let prev = target[key]
				target[key] = value
				target.fieldDidChange(name, value, prev) if value != prev and target.fieldDidChange
			$get: do(target, key)
				target[key]
		}

class Todo < Model
	title @tracked
	done @tracked

	def fieldDidChange name, value, prev
		console.log "{name}: {prev} -> {value}"

let todo = new Todo
todo.title = "Write docs"
todo.done = yes
```

## Relation to decorators

Both features share the `@name` syntax but do different jobs: [decorators](https://imba.io/docs/decorators) wrap or replace an already-defined *method* by transforming its property descriptor at class-definition time, while field descriptors define how a *field* behaves by routing every read and write through an object you construct. A decorator runs once when the class is set up; a field descriptor participates in every access.

---

Source: https://imba.io/docs/decorators

# Decorators

Decorators are special functions which can alter the functionality of a method call by replacing or wrapping it with some other code. Decorators do this by modifying a property (usually a method) with a new [descriptor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty#description) at runtime.

Imba includes some built-in decorators such as [@observable](https://imba.io/docs/observable), `@lazy` and `@bound`. These are available without any imports. This page teaches you how to build your own.

Decorators apply to *methods* (and getters/setters). For the related `@`-syntax on fields — like `age @number(min: 0)` — see [Fields](https://imba.io/docs/field-descriptors).

The following example defines a decorators which replaces decorated function, to display a message.

```imba
# Defining a contrived 'silence' decorator:
def @silence target, name, descriptor
	descriptor.value = do
		console.log "'{name}' was called, but it is being silenced."
	return descriptor

# Using the 'silence' decorator
class Person
	@silence def sayHi
		console.log("Hello, I hope I'm not silenced!")

const someone = new Person()
someone.sayHi!
```

Skip to [Technical Details](#technical-details).

## Guide to Understanding

Let's walk through why and how decorators work with an example.

Imagine you have a method which returns the result of a calculation like this:

```imba
class EasyMath
	def multiply
		return 5 * 3
```

You later realize you want to log the result of that calculation for debugging purposes, now you need to assign the calculation to a variable, then you can log the value, then return it.

```imba
class EasyMath
	def multiply
		console.log "Running the multiply method"
		const result = 5 * 3
		console.log(result)
		return result

new EasyMath().multiply!
```

We can make a convenient, reusable decorator that automatically logs the return value, instead of having to modify the function with additional code.

Here's how we can define such a decorator:

```imba
def @logResult target, name, descriptor

	# The original method is stored in descriptor.value
	const originalMethod = descriptor.value

	# We'll overwrite the value with a new function
	descriptor.value = do(...originalArguments)

		# call the original method
		let result = originalMethod(...originalArguments)

		# do the custom logging
		console.log
			"Calling {name}({originalArguments.join(', ')}) returned {result}"

	return descriptor
```

And here's how to use it:

```imba
def @logResult target, name, descriptor

	# The original method is stored in descriptor.value
	const originalMethod = descriptor.value

	# We'll overwrite the value with a new function
	descriptor.value = do(...originalArguments)

		# call the original method
		let result = originalMethod(...originalArguments)

		# do the logging (this is the additional functionality added by the decorator)
		console.log "Calling {name}({originalArguments.join(', ')}) returned {result}"

	return descriptor
class EasyMath
	@logResult def multiply a, b
		return a * b

	@logResult def quadruple n do n * 4

const myMath = new EasyMath()
myMath.multiply(3,5)
myMath.quadruple(10)
```

Now that the `@logResult` decorator function is defined, you are able to add `@logResult` in front of any method definition to make use of the decorator.

## Decorator Parameters

The parameters of a decorator are as follows:

#### Target

Target is the class constructor's prototype. It's not often needed.

#### Name

`name`, (sometimes called `key`), is the name of the property being decorated. In the example below, the `name` sent to the `@bar` decorator would be the string `"baz"`.

```imba
class Foo
	@bar def baz
		return 'baz!'
```

#### Descriptor

The descriptor value for this property. You can read an overview of descriptors here: [descriptors on mdn](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty#description).

In JavaScript, when you write:

```imba
obj[key] = value
```

You could say that `obj` has a _property_ named `key`.
However, it is not as simple as just a new key mapping to a value.
There is some additional metadata associated with this property which is called the descriptor.

The descriptor is an object which indicates whether the property is enumerable or not,
writeable or not, etc.

The main descriptor properties we use are:

-   `descriptor.value` for functions.
-   `descriptor.get` for getters.
-   `descriptor.set` for setters.

In this example, the `descriptor.value` sent to the `@bar` decorator would be the `baz` function itself.

```imba
class Foo
	@bar def baz
		return 'baz!'
```

#### Return value

The return value is a new descriptor.
If the return value is null, the original descriptor is used,
side effects included.

```imba
def @log target, name, desc
	desc.value = do
		console.log "This will log."
	return null

class Test
	@log def main
		console.log "In main."

let test = new Test!
test.main()
```

For clarity,
notice that the following code will log twice even though we're
not calling any functions because the decorated properties are
replaced at runtime:

```imba
def @example target, name, desc
	console.log "This will be logged once for each decorated property at runtime."

class Test
	@example def main
		return
	@example def test
		return
```

## Technical Details

#### Placement

You can place decorators either above a property or before a property as demonstrated in the next example.

```imba
class Foo
	@bar
	def first
		console.log "this works"

	@bar def second
		console.log "This works too!"
```

#### Decorator Arguments

Arguments can be passed to the decorator and are bound as `this` in the decorator.

```imba
def @example
	# arguments are available as 'this'
	console.log this

class Test
	@example(1, 2, 3) def main do return
```

#### Multiple decorators

Multiple decorators can be used on a single method. They are applied starting with the decorator closest to the method — in the example below, `@three` runs first and `@one` last, each receiving the descriptor returned by the previous one.

```imba
class Test
	@one @two @three def foo
		console.log "Called foo."

	@one
	@two
	def bar
		console.log "Called bar."

```

#### Implicit returns

Imba implicitly returns the last statement in a function,
so even though side effects can be used to modify the
descriptor, if the last statement is `desc.value = do ...`,
the `do` function will be implicitly returned.

Be sure to explicitly return the `desc` value if that is your intention.

#### Execution context

You might be wondering why we need to use
[apply](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply)
instead of just calling the function directly:

```imba
const result = prev.apply(this, args)
```

That has to do with the execution context of the function.
It's an odd topic, but if you look at the output of this example:

```imba
def @log target, name, desc
	let prev = desc.value
	desc.value = do
		console.log "`this` in @log: {this}"
		prev!
	desc

class Test
	@log def one
		console.log "`this` in one: {this}"

	def two
		console.log "`this` in two: {this}"

let test = new Test!
test.one!
test.two!
```

You'll notice that even though it seems like we're calling
`one` and `two` in the same manner,
since `one` is being called inside of this function:

```imba
	desc.value = do
		console.log "In @log: {this}"
		prev!
```

It loses its execution context. More on `this` can be found on [mdn](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/this).

#### Implementation

For those interested, this is a slightly simplified
version of how decorators work behind the scenes.
In the real compiled output the `decorate` call happens
inside a static initializer block on the class,
but the effect is the same:

```imba
# inserted at compile time
def decorate decorator,target,key
	let desc = Object.getOwnPropertyDescriptor target,key
	let new_desc = decorator(target,key,desc) or desc
	new_desc and Object.defineProperty target,key,new_desc

def log target,key,desc
	desc.value = do
		console.log "Called {key}."
	return

class Test

	# inserted at compile time
	static def init
		decorate log.bind(["args"]),this.prototype,'main'

	def main
		console.log "Original."

# inserted at compile time
Test.init!

new Test!.main!
```

---

Source: https://imba.io/docs/basic-syntax/modules

# Modules

## Syntax

```imba
import defaultExport from "module-name"
import * as name from "module-name"
import { export1 } from "module-name"
import { export1 as alias1 } from "module-name"
import { export1 , export2 } from "module-name"
import { foo , bar } from "module-name"
import { export1 , export2 as alias2 , [...] } from "module-name"
import defaultExport, { export1 [ , [...] ] } from "module-name"
import defaultExport, * as name from "module-name"
import "module-name"
```

## Examples

### Import default

```imba
import DefaultExport from './source'
```

### Import members

```imba
import {capitalize,camelize} from './util'
```

### Import members with alias

```imba app.imba
import {capitalize as upcase,camelize} from './util'
```

```imba util.imba
export def capitalize
    return 123

export def camelize
    return 123
```

### Import an entire module's contents

```imba main.imba
import * as utils from './util'
console.log utils.ping!, utils.pong!
```

```imba util.imba
export def ping
    return 123

export def pong
    return 123
```

### Import a single export from a module

```imba app.imba
import {myExport} from './util'
console.log myExport!
```

```imba util.imba
export def myExport
    return 123
```

### Importing web components

Web components are not explicitly imported by name. As long as the files
where your components are imported somewhere in your project they will
be available everywhere.

```imba app.imba
import './controls'

imba.mount do <div[pos:absolute inset:0 d:flex ja:center]>
    <my-component>
    <app-avatar>
```

```imba controls.imba
# no need to export this - it is globally available
# as long as the file is imported somewhere in your project
tag my-component
    <self[d:inline-block p:2]> "Custom component"

tag app-avatar
    <self[d:inline-block]> "Avatar"
```

### Importing a custom element

```imba app.imba
import {MyElement} from './element'

imba.mount do <div> <MyElement>
```

```imba element.imba
export tag MyElement
    <self[d:inline-block p:2]> "Custom element here"
```

### Importing styles

Global styles that you want included in your project must be imported somewhere.

```imba app.imba
import './styles'

imba.mount do <div>
    <p> "Globally styled"
```

```imba styles.imba
global css
    p color:blue5
```

---

Source: https://imba.io/ui

# UI

In addition to scripting capabilities, Imba ships with extremely
powerful support for custom elements, first class CSS and event
handling chains, routing, and more.

<doc-pages></doc-pages>

---

Source: https://imba.io/docs/tags

# Elements

In Imba, DOM elements are a first-class part of the language. Imba does not use a virtual DOM, instead it compiles declarative tag trees into an extremely efficient [memoized dom](https://medium.com/free-code-camp/the-virtual-dom-is-slow-meet-the-memoized-dom-bb19f546cc52), which is orders of magnitude faster than virtual DOM approaches, yet conceptually simpler.

## Constructing Elements

```imba
let div = <div#main.note.sticky title='Welcome'> 'Hello'
```

The code above creates an actual HTMLDivElement. It will be helpful to understand what happens behind the scenes when creating an element using the literal syntax. Imba breaks up each part of the node, and applies them one after the other. The code above roughly compiles to:

```imba
let div = document.createElement('div') # create div
div.id = 'main' # set id
div.classList.add('note') # add .note
div.classList.add('sticky') # add .sticky
div.title = 'Welcome' # set title
div.textContent = 'Hello' # set textContent
```

## Setting Classes

You can add classes to your elements by adding one or more identifiers preceded by `.`

```imba
# add note and editorial classes
<div.note.editorial> "Hello"
```

Set a class only when a certain condition is met can be done using `.class=condition`.

```imba
<div.note.editorial .resolved=data.isResolved> "Hello"
```

To add dynamic classes based on data use `{}` for interpolation inside class names:

```imba
let marks = 'rounded important'
let state = 'done'
let color = 'blue'
<div.item .{marks} .{state} .bg-{color}-200> "Hello"
```

These interpolated classes can also be toggled by a condition:

```imba
<div.item .theme-{user.theme}=app.loggedIn> "Hello"
```

Classes are set and updated in an optimised way which means that updating the raw `el.className` or `el.classList` directly will yield unexpected results. When you want to add and remove classes directly from the elements outside of rendering trees you need to use `el.flags` which works just like [Element.classList](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList).

```imba
# add example for el.flags here
```

## Setting Properties

As you've already seen you can add properties to the elements just like you would in HTML. You can set arbitrary properties on the elements. Just remember that you are setting properties, **not attributes**. They are for the most part mapped 1-to-1, but attributes like `tabindex` must be set using the `tabIndex` property.

```imba
<div lang="en" title=data.title tabIndex=0> "Hello"
```

In addition to all the regular properties supported in the JS DOM, Imba introduces a few special properties that are useful to know about:

<api-list>Element.own.setters.custom</api-list>

## Setting Attributes

By default you are setting properties on elements, NOT attributes. The reason `<div title='Hello'>` works is that Element.title is defined as an IDL property that proxies to `setAttribute('title',...)`. So setting `somename` on an element won't automatically show up as attributes on the element. To set raw custom attributes you can use the html namespace prefix:

```imba
<div somename='hello'> # sets property on div
<div html:someproperty='hello'> # sets html attribute on div
```
You can also declare attributes on your components using the `attr` keyword.
```imba
tag app-panel
    attr desc
```
Then you can use `desc` as any other standard IDL property.
```imba
<app-panel desc="Some description">
```

## Adding Inline Styles
See [Styling Documentation](https://imba.io/docs/css) for in-depth documentation about styling, both via selectors and inline on elements.

```imba
<div[color:red bg:blue padding:8px]> "Hello"
```

Just like classes, styles can be conditionally applied

```imba
<div[color:red bg:blue] [display:none]=app.loggedIn> "Hello"
```

## Adding Event Listeners

We can use `<tag @event=expression>` to listen to DOM events and run `expression` when they’re triggered. See [Events Documentation](https://imba.io/docs/events).

```imba
let counter = 0
<button @click=(counter++)> "Increment to {counter + 1}"
```

## Rendering Children

Indentation is significant in Imba, and tags follow the same principles. We never explicitly close our tags. Instead, tags are closed implicitly by indentation. So, to add children to an element you simply indent them below:

```imba
<div> <ul>
	<li> <span> 'one'
	<li> <span> 'two'
	<li> <span> 'three'
```

Tags can also be included inside string interpolations, so that templates like this:

```imba
<div>
    "This is "
    <b> "very"
    " important"
```

Can be written like on a single line

```imba
<div> "This is {<b> "very"} important"
```

Also, if you explicitly close your elements using `/>` at the end, you can add multiple elements after one another without problem:

```imba
<label> <input type='checkbox'/> 'Dark Mode'
```

## Conditionals & Loops

There isn't really a difference between templating syntax and other code in Imba. Tag trees are just code, so logic and control flow statements work as you would expect. To render dynamic lists of items you simply write a `for` loop where you want the children to be:

```imba
<div>
    if items
        <h1> "List of items:"
        <ul> for item in items
            <li> <span> item
    else
        <span> "No items found"
```

You can use break, continue and other control flow concepts as well:

```imba
# ~preview=xl
import {movies} from 'imdb'

css .heading c:blue7 fs:xs fw:bold p:2 bc:gray3 bbw:1 pos:sticky t:0 bg:white
css .item mx:2 d:flex px:2 py:3 bc:gray2 bbw:1 bg.hover:gray1
css .title px:1 t:truncate
css .number rd:3 px:2 bg:blue2 mr:1 fs:xs c:blue7 d:grid pc:center

imba.mount do <div.list> for movie,i in movies
    if i % 10 == 0
        # Add a heading for every 10th item
        <div.heading> "{i + 1} to {i + 10}"
    <div.item>
        <span.number> i + 1
        <span.title> movie.title
    # break out of the loop early
    break if movie.title == 'The Usual Suspects'
```

## Dynamic Element Type

The first part of your tag literal should be the node name. So, to create a section you write `<section>`, for a list item you write `<li>` and so forth. You can use `{}` interpolation in the node name to spawn custom tags:

```imba
# ~preview
import 'util/styles'
let data = {type: 'button', label: 'Hello'}
imba.mount do
    <div.group>
        <section> "A section"
        <{data.type}> data.label
```

If you create an element without a node name it will always be created as a `div`.

## Fragments

Fragments allow grouping elements together in a parent tag, without actually adding the parent tag to the DOM. Fragments can be created using empty tag literals `<>`.

```imba fragment.imba
tag app-dialog
	def render
		<self>
			<header> "Dialog header"
			<.body> body!

	def body
		<> # Returns all elements without any wrapping element
			<h3> "Body text"
			<p> "With some adjecent content"

	# Because imba returns the last statement
    # this function would only return the <p> element
	def bad-body
		<h3> "Body text"
		<p> "With some adjecent content"

```

---

Source: https://imba.io/docs/tags/mounting

# Mounting Elements

The fact that tag literals generate real dom nodes means that we can add/remove/modify the dom in an imperative way. In theory.

#####

```imba
import 'util/styles'

let array = ["First","Second"]

let view = <main>
    <button @click=array.push('More')> 'Add'
    <ul.list> for item in array
        <li> item

# view is a real native DOM element
document.body.appendChild view
```

Even though we rendered a dynamic list of items, it won't update if new items are added to the array or if members of the array change. Clicking the button will actually add items, but our view is clearly not keeping up. What to do?

### imba.mount

To make the tag tree update when our data changes, we need to add pass the tree to `imba.mount`.

#####

```imba
import 'util/styles'

let array = ["First","Second"]

imba.mount do
    <main>
        <button @click=array.push('More')> 'Add'
        <ul.list> for item in array
            <li> item
```

Now you will see that when you click the button, our view instantly updates to reflect the new state. How does this happen without a virtual dom? The array is not being tracked in a special way (it is just a plain array), and we are only dealing with real dom elements, which are only changed and updated when there is real need for it. Imba uses a technique we call `memoized dom`, and you can read more about how it works [here](https://medium.com/free-code-camp/the-virtual-dom-is-slow-meet-the-memoized-dom-bb19f546cc52). Here is a more advanced example with more dynamic data and even dynamic inline styles:

#####

```imba
import 'util/styles'

css div pos:absolute d:block inset:0 p:4
css mark pos:absolute
css li d:inline-block px:1 m:1 rd:2 fs:xs bg:gray1 @hover:blue2

let x = 20
let y = 20
let title = "Hey"

imba.mount do
    <main @mousemove=(x=e.x,y=e.y)>
        <input bind=title>
        <label> "Mouse is at {x} {y}"
        <mark[x:{x} y:{y} rotate:{x / 360}]> "Item"
        <ul> for nr in [0 ... y]
            <li> nr % 12 and nr or title
```

By default Imba will **render your whole application whenever anything _may_ have changed**. Imba isn't tracking anything. This sounds insane right? Isn't there a reason for all the incredibly complex state management libraries and patterns that track updates and wraps your data in proxies and all that? As long as you have mounted your root element using `imba.mount` you usually don't need to think more about it.

### imba.commit

The default approach of Imba is to re-render the mounted application after every handled DOM event. If a handler is asynchronous (using await or returning a promise), Imba will also re-render after the promise is finished. Practically all state changes in applications happen as a result of some user interaction.

In the few occasions where you need to manually make sure views are updated, you should call `imba.commit`. It schedules an update for the next animation frame, and things will only be rerendered once even if you call `imba.commit` a thousand times. It returns a promise that resolves after the actual updates are completed, which is practical when you need to ensure that the view is in sync before doing something.

##### commit from websocket

```imba
socket.addEventListener('message',imba.commit)
```

Calling `imba.commit` after every message from socket will ensure that your views are up-to-date when your state changes as a result of some socket message.

##### commit after fetching data

```imba
def load
    let res = await window.fetch("/items")
    state.items = await res.json!
    imba.commit!
```

---

Source: https://imba.io/docs/tags/data-binding

# Data Binding

## Form Input Bindings

## Examples

##### text

```imba
# ~preview=md
import 'util/styles'

let message = "Hello"

imba.mount do <section>
	<input type='text' bind=message>
	<label> "Message is {message}"
```

##### textarea

```imba
# ~preview=md
import 'util/styles'

let tweet = ''

imba.mount do <section>
	<textarea bind=tweet placeholder="What's on your mind...">
	<label> "Written {tweet.length} characters"
```

##### range

```imba
# ~preview=md
import 'util/styles'

let point = {r:0, x:0}

imba.mount do <section[gap:2]>
    <input type='range' bind=point.x>
    <input type='range' bind=point.r>
    <label[js:center w:40px rotate:{point.r}deg x:{point.x}]> "{point.x},{point.r}"
```

##### number

```imba
# ~preview
import 'util/styles'

let a=1
let b=2

imba.mount do <div.group>
    <input type='number' min=0 max=100 bind=a/> " + "
    <input type='number' min=0 max=100 bind=b/> " = "
    <samp> "{a + b}"
```

##### checkbox

```imba
import 'util/styles'
let bool=no

imba.mount do <section>
    <label>
        <input[mr:1] type='checkbox' bind=bool />
        <span> "Enabled: {bool}"
```

##### checkbox with array

```imba
import {genres} from 'imdb'
import 'util/styles'

css div d:flex flf:row wrap pi:center jc:flex-start

let options = ['React','Vue','Imba','Svelte','Ember']
let interests = []

imba.mount do <section>
    <div> for option in options
        <label[mr:2]>
            <input type='checkbox' bind=interests value=option/>
            <span[pl:1]> option
    <label> "Interested in {interests.join(', ')}"
```

##### radio

```imba
import {genres} from 'imdb'
import 'util/styles'

css div d:flex flf:row wrap pi:center jc:flex-start

let options = ['React','Vue','Imba','Svelte','Ember']
let interest = 'Imba'

imba.mount do <section>
    <div> for option in options
        <label[mr:2]>
            <input type='radio' bind=interest value=option/>
            <span[pl:1]> option
    <label> "Interested in {interest}"
```

##### select

```imba
import {genres} from 'imdb'
import 'util/styles'

css div d:flex flf:row wrap pi:center jc:flex-start

let options = ['React','Vue','Imba','Svelte','Ember']
let focus = 'Imba'

imba.mount do <section>
    <select bind=focus> for item in options
        <option value=item> item
    <label> "Focused on {focus}"
```

##### multiselect

```imba
import {genres} from 'imdb'
import 'util/styles'

css div d:flex flf:row wrap pi:center jc:flex-start

import {projects} from 'util/data'

let choices = []

imba.mount do <section>
    <select multiple bind=choices> for item in projects
        <option value=item> item.name
    <label> "Interested in"
    <div> for item in choices
        <div[color:{item.color}]> item.name
```

##### button

```imba
import {genres} from 'imdb'
import 'util/styles'

let state = 'one'
css button.checked bxs:inset bg:gray2 o:0.6

imba.mount do <section>
    <div.group>
        <button bind=state value='one'> "one"
        <button bind=state value='two'> "two"
    <label> "State is {state}"
```

Buttons bound to data behave just like checkboxes. A `checked` class indicates when their value matches the bound data. Clicking a button multiple times will toggle just like a checkbox.

##### custom elements

```imba
import 'util/styles'

let options = {
    width: 12
    height: 12
    title: 'Something'
}

tag Field
    get type
        typeof data == 'number' ? 'range' : 'text'

    <self[d:flex js:stretch]>
        <label[w:80px]> <slot> 'Field'
        <input[flex:1] type=type bind=data>

imba.mount do <section>
    <Field bind=options.title> 'Title'
    <Field bind=options.width> 'Width'
    <Field bind=options.height> 'Height'
    <label> "{options.title} is {options.width}x{options.height}"
```

##### combination

```imba
import {genres} from 'imdb'
import 'util/styles'

css div d:flex flf:row wrap pi:center jc:flex-start

let people = [{name: 'Jane Doe', interests: ['Imba']}]
let person = people[0]

def addPerson
    person = {name: 'John',interests:[]}
    people.push(person)

def addInterest e
    person.interests.push e.target.value
    e.target.value = ''

imba.mount do <main>
    <header>
        <select bind=person>  for item in people
            <option value=item> item.name
        <button[ml:2] @click=addPerson> 'Add'
    <article>
        <label[ta:left]> "Editing {person.name}:"
        <input bind=person.name placeholder="Name...">
        <input placeholder="Add interest..." @keyup.enter.prevent=addInterest>
        <div.tags> for item in person.interests
            <button[mr:1].chip bind=person.interests value=item> item
```

---

Source: https://imba.io/docs/components

# Components

Components are reusable elements with functionality and children
attached to them. Components are _just like regular classes_ and use
all the same syntax to declare properties, methods, getters and
setters. To create a component, use the keyword `tag` followed by a
component name.

```imba app.imba
tag Box
	css pos:relative d:flex ja:center
		rd:md bg:hue3 c:gray9/70
		w:24 h:10 m:1 px:4 fs:sm cursor:grab
	x = 0
	y = 0
	<self[x:{x}px y:{y}px] @touch.moved.sync(self)> <slot> "box"

tag app
	<self[inset:0 d:hcc]>
		<Box[hue:blue]> 'One'
		<Box[hue:sky]> 'Two'
		<Box[hue:indigo]> 'Three'
		<Box[hue:purple]> 'Four'

imba.mount <app>
```

### Local Components

If a component's name begins with an uppercase letter, it will be
defined as a local component. This means that it will act just like a
web component, but will not be registered globally, and must be
explicitly exported and imported from other files to be used in your
project.

```imba
export tag Box
	<self>
		...
```

### Global Components

If a component's name begins with a lowercase letter, it will be
compiled directly to a native
[Web Component](https://developer.mozilla.org/en-US/docs/Web/Web_Components).
These components are registered globally and are available anywhere in
your project as long as the file has been imported at least once.

Global component names must contain a dash, so it is common to
prefix them with `app-`.

```imba
tag app-box
	<self>
		...
```

## Named Elements

It can be useful to keep references to certain child elements inside a
component. This can be done using `<node$reference>` syntax.

```imba
import 'util/styles'

tag app-panel
    <self.group>
        <button @click=($name.value += 'Hi')> "Write"
        <input$name type='text'>

imba.mount <app-panel>
```

In the code above, `$name` is available everywhere inside `app-panel`
component, but also from outside the app-panel as a property of the
component.

---

Source: https://imba.io/docs/components/slots

# Component Slots

## Using Slots

Sometimes you want to allow taking in elements from the outside and render them somewhere inside the tree of your component. `<slot>` is a placeholder for the content being passed in from the outside.

### Default Slot

```imba
tag app-option
    <self>
        <input type="checkbox">
        <label> <slot>

imba.mount do <app-option>
    <b> "Option name"
    <span> "Description for this option"
```

### Placeholder Content

Anything inside the `<slot>` will be shown if no content is supplied from outside.

```imba
import 'util/styles'
css body d:flex
css app-option d:hcl
css app-example d:vts

tag app-option
    <self>
        <input type="checkbox">
        <label> <slot> "Default label"

tag app-example
    <self>
        <app-option>
        <app-option> <span> "Custom label"

imba.mount <app-example>
```

### Named Slots

You can also add named slots using `<slot name=...>` and render into them using `<el slot=slotname>` in the outer rendering.

```imba
# ~preview
import 'util/styles'
css body d:flex

css app-panel d:hsl
    aside p:1 bg:gray3
    main p:1 fs:md fl:1

tag app-panel
    <self.panel>
        <aside.left> <slot name="sidebar"> "Sidebar"
        <main> <slot> <p> "Default Body"
        <aside.right> <slot name="Detail"> "Right"

imba.mount do <app-panel>
    <div slot="sidebar"> "Stuff!"
    <div> "Something in main slot"
    <div> "More in main slot"

```

---

Source: https://imba.io/docs/components/lifecycle

# Component Lifecycle

## Lifecycle Hooks

These methods are meant to be defined in your components. In most cases you will only define a `render` method, and possibly `awaken` if you want to do some additional initialization when the element is first attached to the document.

<api-list>imba.Component.own.methods.#lifecycle</api-list>

## Lifecycle States

Components also has a bunch of getters that you can call to inspect where in the lifecycle a component is

<api-list>imba.Component.own.getters</api-list>

---

Source: https://imba.io/docs/components/teleports

# Teleports

The `<teleport>` is a special kind of element that allows you to add event handlers and content to a different element.

## The Global Tag

You can use the special `<global>` tag within your elements for two main purposes:

#### 1. Global Event Handlers

If your element needs to attach a global event handler, do it on the `<global>` tag. This is useful for things like keyboard shortcuts, or listening for mouse events that happen outside of the element. Event listeners on the `<global>` tag will be removed when the element is unmounted.

There is an event modifier called `outside` that can be used in conjunction with mouse events on the global tag. This will limit the event to firing when it happens outside of the element. It's demonstrated below.

```imba
import 'util/styles'

tag my-menu
	css .menu-container shadow:0 0 0 1px black/10, lg rd:5px mt:5px o:0 ml:10px of:hidden tween:all 300ms ease
		.menu-item p:5px 10px bdb:1px solid cooler2 @last:none bgc:white @hover: blue5 c:gray8 @hover:white cursor:pointer

	showMenu = false

	<self>

		<global
			@click.outside=(showMenu = false)
			@keydown=(showMenu = false if e.key === 'Escape')
		>

		<div[d:flex]>
			<button @click=(showMenu = !showMenu)> "Toggle Menu"
			<div.menu-container [opacity:1]=showMenu>
				<div.menu-item> "Click Outside"
				<div.menu-item> "Or Press Escape"

imba.mount <my-menu>
```

#### 2. Appending to Body

Content nested within the `<global>` tag will be appended to the document's `<body>`. You can think of it like a slot, or portal. This can be useful for things such as modal windows with should appear above everything else.

When your element unmounts, content added to `<global>` will also be unmounted.

```imba
import 'util/styles'

tag my-menu

	css .modal-window zi:10 c:white pos:absolute t:50% l:50% x:-50% y:-50% bgc:black/70 p:30px rd:10px

	showModal = false

	<self>
		<button @click=(showModal = !showModal)> "Toggle Modal"
		<global>
			if showModal
				<div.modal-window @click=(showModal = false)>
					<h1> "This is appended to the body tag"

imba.mount <my-menu>
```

---

Source: https://imba.io/docs/events

# Events

Imba has a special syntax for defining complex event handlers with very little code. You can listen to any DOM event by simply declaring `<div @eventname=handler>` on your elements.

```imba
<div @click.stop.cooldown=console.log('hey')> 'Click me'
```

In addition to supporting all the native DOM events, and arbitrary custom events, Imba includes several convenient custom events to simplify important aspects of developing web applications:

<api-list>ImbaEvents.own.events.custom</api-list>

### Further reading

<doc-pages></doc-pages>

---

Source: https://imba.io/docs/events/handling

# Event Handling

We can use `<tag @event=expression>` to listen to DOM events and run `expression` when they’re triggered.

```imba
let counter = 0
<button @click=(counter++)> "Increment to {counter + 1}"
```

It is important to understand how these event handlers are treated. Imba is created to maximize readability and remove clutter. If you set the value to something that looks like a regular method call, this call (and its arguments) will only be called when the event is actually triggered.

```imba
<div @click=console.log('hey')> 'Will log hey'
```

In the example above, the console.log will only be called when clicking the element. If you just supply a reference to some function, Imba will call that handler, with the event as the only argument.

```imba
<div @click=console.log> 'Will log the event'
```

Inside of these lazy handlers you can also refer to the event itself as `e`.

```imba
let x = 0
<button @click=console.log(e.type,e.x,e.y)> "Click"
<button @mousemove=(x = e.x)> "Mouse at {x}"
```

Remember that the expression will be called as is, so you never need to bind functions to their context and/or arguments.

```imba
import {todos} from './data.imba'

const handler = console.log.bind(console)

<ul> for item,i in todos
	<li @click=handler(e.type,item,i)> item.title
```

## Adding Modifiers

Inspired by vue.js, Imba supports event modifiers. More often than not, event handlers are simple functions that do some benign thing with the incoming event (stopPropagation, preventDefault etc), and then continues on with the actual logic. By using modifiers directly where we bind to an event, our handlers can be pure logic without any knowledge of the event that triggered them.

```imba
# Call preventDefault on submit event before handling
<form @submit.prevent=handler>
# Handle only if condition is true
<button @click.if(condition)=handler>
# Handle scroll events once every 500ms at most
<section @scroll.throttle(500ms)=handler>
```

These modifiers can be chained:

```imba
<div @click.ctrl.stop=handler>
```

## Listening to global events

---

Source: https://imba.io/docs/events/modifiers

# Event Modifiers

### Shared Modifiers

<api-list>Event.own.modifiers</api-list>

### Keyboard Modifiers

<api-list>KeyboardEvent.own.modifiers</api-list>

### Mouse Modifiers

<api-list>MouseEvent.own.modifiers</api-list>

### Pointer Modifiers

<api-list>PointerEvent.own.modifiers</api-list>

### Touch Modifiers

<api-list>imba.Touch.own.methods</api-list>

### Custom Modifiers

You can create your own event modifiers by extending the event classes. Any method named with an `@` prefix becomes available as a modifier on that kind of event:

```imba
extend class Event
    def @confirm msg = 'Are you sure?'
        return global.window.confirm(msg)

tag app-root
    count = 0
    <self[d:block p:3]>
        <button[p:1 px:2 rd:md bg:red2 @hover:red3] @click.confirm('Delete this item?')=count++> "Delete"
        <div[mt:2 c:gray6]> "Deleted {count} items"
imba.mount do <app-root>
```

Inside the modifier, `self` is the event itself — so you have direct access to `target`, `preventDefault`, and everything else on the event. Arguments you pass at the call site (`@click.confirm('Delete this item?')`) arrive as regular parameters.

Modifiers run in order as steps in the handler chain, and the return value decides what happens next:

- Return `false` to stop the chain — the remaining modifiers and the handler will not run.
- Return a promise and the chain pauses until it resolves, just like the built-in `@wait` and `@debounce` modifiers. If it resolves to `false`, the chain stops.
- Any other value lets the chain continue.

This makes async guards trivial:

```imba
extend class Event
    # pause the chain while saving - stop unless it succeeded
    def @save
        let res = await global.fetch('/save', method: 'POST')
        return res.ok

tag app-form
    <self>
        <button @click.save.flag('saved')> "Save"
```

Custom modifiers can be negated with `!` just like the built-in ones — `@click.!confirm('...')` continues only when the modifier returns a falsy value.

#### Scoping modifiers to an event type

Extend a specific event interface to make a modifier available only for those events:

```imba
extend class KeyboardEvent
    # only continue if the pressed key is a digit
    def @digit
        return /^[0-9]$/.test(key)

tag app-fields
    <self>
        <input @keydown.digit.log('typed a digit')>
```

---

Source: https://imba.io/docs/events/hotkeys

# Hotkeys

To make it easier to add consistent shortcuts throughout your apps, Imba includes a custom [@hotkey](api) event. Behind the scenes it uses the [mousetrap.js](https://craig.is/killing/mice) library.

### Syntax

```imba
# supply the key combo in the @hotkey(arguments)
<div @hotkey('ctrl+shift+k')=handler>

# gmail style sequences
<div @hotkey('g i')=handler>

# hotkey without a handler defaults to click
<div @hotkey('mod+n') @click=clickHandler>

# hotkey without a handler on a form field will focus
<input @hotkey('s') placeholder="Search...">

# multiple hotkeys
<input @hotkey('mod+k|s')>

# capture all hotkeys
<div @hotkey('*').global>
```

### Usage

For multiple elements with the same hotkey - the ones later in the dom will be called first - and always stop there unless the handlers have set the `.passive` modifier.

```imba
<div @hotkey('f').passive.log('not called')>
<div @hotkey('f').log('called next - stops here')>
<div @hotkey('f').passive.log('called first')>
```

Hotkeys are only active when / if they are present in the dom. This makes it very easy to conditionally enable certain hotkeys in a declarative manner.

```imba
tag App
    <self>
        if let item = state.selection
            <div[d:none]
                @hotkey('del')=deleteItem(item)
                @hotkey('enter')=editItem(item)
                @hotkey('esc')=(state.selection = null)
            >
```
In the example above we add a hidden div to the dom if there is a selItem, and add three hotkey handlers to this element. So, whenever `state.selection` is set, pressing `enter` will trigger the `editItem(item)` handler.

For hotkey groups and disabling/enable all hotkeys within a certain dom tree see the [Element.hotkeys](https://imba.io/api/Element/hotkeys) property.

### Hotkey Interface

<api-list>imba.HotkeyEvent.own</api-list>

---

Source: https://imba.io/docs/events/reference

# Event Reference

### Event Interfaces

<api-grid>Event.inheritors</api-grid>

### Non-standard Events

<api-list>ImbaEvents.own.events.custom</api-list>

### [Mouse](https://imba.io/api/MouseEvent) Events

<api-list>MouseEvent.own.events</api-list>

### [Pointer](https://imba.io/api/PointerEvent) Events

<api-list>PointerEvent.own.events</api-list>

### [Keyboard](https://imba.io/api/KeyboardEvent) Events

<api-list>KeyboardEvent.own.events</api-list>

### [Drag & Drop](https://imba.io/api/DragEvent) Events

<api-list>DragEvent.own.events</api-list>

---

Source: https://imba.io/guides/rendering

# Declarative Rendering

The virtual DOM was a fantastic innovation. It brought about a much more productive way of writing web applications by allowing us to write our views in a declarative manner. Declarative rendering is only possible if the process of re-rendering is fast enough. To do this, virtual DOMs essentially render a lightweight representation of your view, compares it to the previous lightweight representation, and only *patch* the real DOM with the changes.

This process is still quite slow, and to work around these inherent challenges we've resorted to complex state management frameworks that carefully track the changing data, making sure that only specific views need to re-render. Even with this in place, rendering complex lists and very dynamic views can often become sluggish. What if we could get better performance in a world where the data layer and view layer don’t really know or care about each other?

Imba introduces a *revolutionary* new way of reconciling your dom which is orders of magnitudes faster than existing virtual DOM approaches. Understanding the basic concepts is invaluable to get a deep understanding of how to make things with Imba.

## How it Works

DOM nodes in Imba are *not* virtual, they are in fact real elements:

```imba
let el = <div.large title="Item">
console.log el # HTMLDivElement
console.log el.outerHTML # <div class='large' title='Item'>
```

Let's look at a simple component and go through the generated code line by line. 

```imba
let number = 1
let bool = false

tag App
	<self .ready=bool>
		<h1.header> "Number is {number}"

```

The component above will roughly compile to something like the following. Feel free to skip this part if it seems hard to understand, but please get back to it. Once you get a deep understand the simple yet powerful way Imba does rendering it will make you a much more powerful developer.

```js
/*
This is handcrafted pseudocode – the real imba output is
more optimised and compact, making it a little harder to
understand.
*/
let number = 1;
let bool = false;

class App extends HTMLImbaElement {
	render(){
		var $ = (this.cache || this.cache = {});
		
		// toggle the class name on the App element - based on
		// value of bool, and cache the valua for later checks
		if($.val != bool) this.classList.toggle('ready',$.val = bool)

		if(!$.rendered){
			$.h1 = this.appendChild('h1') // add h1 and cache element
			$.h1.className = "header"; // only on first render
			$.h1.insertText("Number is "); // only on first render
			$.t1 = h1.insertText(number); // add text and cache textnode
		} else {
			// has been rendered previously, not much to do!
			$.t1.textContent = number; // update the text of the textnode
		}		
		$.rendered = true; // mark App as rendered
		// nothing is returned from render
	}
};
```

Try to read this code, and figure out what will happen the first time `app.render()` is called, and what will happen the second time.

In a framework like react, the idea is that the render method creates a virtual dom tree *and returns it*. Every time you call render it will generate a new tree. This tree will be taken by the dom reconciler to compare to some previously cached version, create a diff, and patch the real DOM with the changes.

In Imba, calling render will *actually* create and then later modify the *real* DOM elements to make sure they appear the way you have declared. So after the first render, calling render on the `App` element above will only run a minimal number of instructions. The result is that re-rendering in Imba is so fast that you can literally render your whole application, from root, regularly.

### Basic example

```imba main.imba
global css body d:flex ja:center
let number = 1
tag App
	<self>
		<h1.header> "Number is {number}"

document.body.appendChild <App>
```

Here we created an `<App>` element and added it to the body. As you can see, it prints the text as it should, but if the number changes, it will still read "Number is 1" in the DOM. Now let's add some methods to see if we can re-render:

```imba main.imba
# [footer] [preview=md]
global css body d:flex ja:center
let number = 1
tag App
	<self>
		<h1.header> "Number is {number}"

let el = <App>
document.body.appendChild el

export def update
	number = Math.random!
	el.render! # call render manually
export const actionzs = {
	"number += 1": do
		number += 1
		console.log "incremented number to {number}"
	"el.render()": do el.render!
}
```

As you can see, whenever we call `render` on the element it makes sure to update the dom if anything has changed. Also, when render is called on an element, all the custom children will also be re-rendered:

```imba main.imba
# [footer] [preview=lg]
global css body d:flex ja:center
tag Item
	css d:block px:1 m:1 bg:blue2 fs:sm rd:md
	<self> "Changes on every render: {Math.random!}"
		
tag App
	<self>
		<Item>
		<Item>

document.body.appendChild let el = <App>
export const actions = {
	"el.render": do el.render!
}
```

## Automatic rendering

Calling render manually on your elements is cumbersome and doesn't really scale. Instead, imba automatically calls render on your mounted elements whenever an event has been triggered *and* handled by a listener. The only thing you need to do is to add your root element using `imba.mount` instead of `document.body.appendChild`.

```imba
import 'util/styles'

css div pos:absolute d:block inset:0 p:4
css mark pos:absolute
css li d:inline-block px:1 m:1 rd:2 fs:xs bg:gray1 @hover:blue2
let x = 20
let y = 20
let title = "Hey"
# mount our elements via imba.mount
imba.mount do
    <main @mousemove=(x=e.x,y=e.y)>
        <input bind=title>
        <label> "Mouse is at {x} {y}"
        <mark[x:{x} y:{y} rotate:{x / 360}]> "Item"
        <ul> for nr in [0 ... y]
            <li> nr % 12 and nr or title
```
Move your mouse around and see how everything updates instantly. This is just a tiny preview of how fast and powerful the declarative rendering in Imba is. Because we listen to a `@mousemove` event, Imba will automatically call render on the mounted element.

## Manual rendering

The default approach of Imba is to re-render the mounted application after every handled DOM event. If a handler is asynchronous (using await or returning a promise), Imba will also re-render after the promise is finished. Practically all state changes in applications happen as a result of some user interaction.

In the few occasions where you need to manually make sure views are updated, you can call `imba.commit`. This is also what the event handlers are using under the hood. It schedules an update for the next animation frame. It returns a promise that resolves after the actual updates are completed, which is practical when you need to ensure that the view is in sync before doing something. Things will only be rerendered once even if you call `imba.commit` a thousand times.

Manually calling `imba.commit` is usually only needed when dealing with receiving data asynchronously (not as a result of a user interaction / event). So, if you receive data via a websocket, the only thing you need to make your whole application magically stay in sync with your data is to call imba.commit whenever you receive data from your socket.

```imba
websocket.addEventListener('message',imba.commit)
```

Or, if you fetch some data via window.fetch, and it doesnt happen asynchronously as part of an event handler, just make sure to call `imba.commit` afterwards:

```imba
def load
    let res = await window.fetch("/items")
    state.items = await res.json!
    imba.commit!
```

## Custom scheduling

Let's say you have a clock, or some other element that needs to re-render at specific intervals, or more often than the rest of your app. Remember, the only thing that really happens when we render is that `.render()` is called on elements. So, manually you could add an interval to specific elements:

```imba
import 'util/styles'
tag Clock
    css d:block p:2 bd:1px solid gray4 m:2 ta:center
    def mount   do #interval = setInterval(render.bind(self),1000)
    def unmount do clearInterval(#interval)
    def render  do <self> <span> (new Date).toLocaleString!

imba.mount do
    <div @click.log('clicked')>
        <span> "Rendered on click {Math.random!}"
        <Clock>
```
As you can see, the clock is actually updating every second. It is a little cumbersome to setup and teardown the intervals though, and since this is a pretty common pattern, Imba has a better way to do this, using the `autorender` property.

```imba
import 'util/styles'
tag Clock
    css d:block p:2 bd:1px solid gray4 m:2 ta:center
    <self> <span> (new Date).toLocaleString!

imba.mount do
    <div @click.log('clicked')>
        <span> "Rendered on click {Math.random!}"
        <Clock autorender=1s>
```

Let's create some proper clocks, and show a few autorender values:

```imba
import 'util/styles'
global css body d:block
tag app-clock
	utc
	
	def render
		let ts = Date.now! / 60000 + utc * 60
		<self.clock>
			<div.dial.h[rotate:{ts / 720}]> <i>
			<div.dial.m[rotate:{ts / 60}]> <i>
			<div.dial.s[rotate:{ts}]> <i/> <b>

imba.mount do
    <div.clocks>
        <app-clock autorender=1s title='New York' utc=-5>
        <app-clock autorender=500ms title='San Fran' utc=-8>
        <app-clock autorender=10fps title='London' utc=0>
        <app-clock autorender=60fps title='Tokyo' utc=9>
```

---

Source: https://imba.io/docs/css

# Styles

First things first – you are free to use external stylesheets like you've always done. Still, aiming to be the friendliest full-stack language we have included styling as a core part of the language. We've also extended the functionality of css to make common patterns friendlier, and to make it easier to keep a consistent design language across your whole project. Our approach to styling is inspired by [Tailwind](https://tailwindcss.com), so we recommend reading about [their philosophy](https://tailwindcss.com/docs/utility-first).

```imba
css .btn
	display: block
	background: #b2f5ea
	padding-left: 4px
	padding-right: 4px

css .btn@hover
	background: #81e6d9
```
As you can see from the snippet above, the syntax of styles in imba are very similar to css, just without braces and semi-colon. At the same time, Imba includes powerful shorthands and [style modifiers](https://imba.io/docs/css/modifiers) to allow the css above to be written like:

```imba
css .btn d:block px:1 bg:teal2 bg@hover:teal3
```

## Further reading

<doc-pages></doc-pages>

---

Source: https://imba.io/docs/css/syntax

# Style Syntax

## Selectors

```imba
css .btn
    position: relative
    display: block
    background: #b2f5ea
    padding-left: 4px
    padding-right: 4px

css .btn@hover
    background: #81e6d9
```

Styles are declared using the `css` keyword. Besides using indentation instead of `{}`, making `;` optional, and using `@pseudo` instead of `:pseudo` it looks like regular css. Line breaks are also optional. The following few snippets might look messy at first glance, but bear with us.

```imba
css .btn
    display:block background:#b2f5ea padding-left:4px padding-right:4px
css .btn@hover
    background: #81e6d9
```

We firmly believe that less code is better code, so we have strived to make the styling syntax as concise yet readable as possible. There is a case to be made against short variable names in programming, but css properties are never-changing. Imba provides intuitive abbreviations for oft-used css properties, as well as additional properties covering common usecases:

```imba
css .btn
    d:block pl:4px pr:4px bg:#b2f5ea
css .btn@hover
    bg:#81e6d9
```

We also want to make it easy to follow a consistent design system throughout your project while not enforcing a predefined look and feel. Imba provides default (but configurable) colors, fonts, size units and more to help enforce consistency:

```imba
css .btn
    d:block px:1 bg:teal2
css .btn@hover
    bg:teal3
```

Rules can also be written on a single line

```imba
css .btn d:block px:1 bg:teal2
css .btn@hover bg:teal3
```

There are also some patterns that come up again and again in css. Changing a few properties on `hover` or other states, or setting certain dimensions for specific screen sizes etc. Imba got you covered with property modifiers that we will get into later. But to round up, the first block of css here would usually be written like this in Imba:

```imba
css .btn d:block px:1 bg:teal2 bg@hover:teal3
```

This conciseness comes especially handy when declaring inline styles, which we will come back to later.

### Nested Selectors

Styles can also be nested. Everything before the first property on new lines are treated as nested selectors.

```imba
css .card
    display: block
    background: gray1
    .title color:blue6 # matches .card .title
    h2.desc color:gray6 # matches .card h2.title
    # to scope in on current item use &
    &.large padding:16px # matches .card.large
```

### Global Selectors

A problem with CSS is that often end up with tons of globally competing styles spread around numerous files. Changing some styles in one place might affect some seemingly unrelated elements. In Imba it is really easy to declare styles that should only apply to certain parts of your application.

By default, any style rules declared at the top level of your file using `css selector ...` will only apply to the elements declared inside that file. The `button` style above will only affect literal `button` tags rendered **in the same file**. This means that you can declare styles like this in your file without having to worry about affecting styles in other parts of your application, or even inside nested components that are defined in other files, but used here.

```imba
css button
    position: relative
    display: block
    background: #b2f5ea

# rest of file ...
```

If you prefix your css declaration with the `global` keyword - the styles will apply globally, and in this example affect all `button` elements in your application. The styles will be included as long as they are required somewhere.

```imba
global css button
    position: relative
    display: block
    background: #b2f5ea

# rest of file ...
```

## Modifier Syntax

```imba
# in selectors
css button@hover
    bg:blue
# in properties
css button
    bg@hover:blue
# after properties
css button
    bg:white @hover:whitesmoke @focus:blue
```

### Pseudo-classes

Pseudo-classes (`:hover`, `:active`, ...) from css are supported using an `@` instead of the leading `:`. So the css selector `div:hover` is written as `div@hover` in Imba. In Imba you can also use pseudo-classes directly on properties:

```imba
css div
    opacity:0.9
    opacity@hover:1
```
If you add a `@pseudoclass:value` on the same line as a regular property, it will set the value of the last property, with the pseudo-class applied:

```imba
css div opacity:0.8 @hover:0.9 @focus:1
```
In addition to the default pseudo-classes from css, Imba supports several convenient additions like `@focin` — see the [modifiers reference](https://imba.io/docs/css/modifiers).

### Pseudo-elements

Pseudo-elements (`::marker`, `::selection`, ...) are supported with the same syntax as in css.

```imba
css li::marker c:blue4
```

### Class Modifiers

Classes can also be used as modifiers:

```imba
css button c:white bg.primary:blue
# is the same as
css button c:white
    .primary bg:blue
```

### Custom Breakpoints

You can set your own custom pixel breakpoints by specifying any number you want after the `@` or `@!` symbols.
`@` for min-width, and `@!` for max-width.

```imba
css div@700 display:block # -> @media (min-width: 700px)
css div@!650 display:none # -> @media (max-width: 650px)
css div width:100% @700:80% @1300:1200px
```

## Scoped Styles

If you declare style rules inside `tag` definitions, all the styles will magically only apply to elements inside of this component.

```imba
# ~preview=lg
# these are global -- applies to everything in project
tag app-card
    css fs:sm rd:md d:vts bg:teal1 c:teal7
    css .header bg:teal2/50 p:3
    css .body p:3

    <self>
        <.header> "Card Header"
        <.body> <p> "Card Paragraph"

tag app-root
    # local styles does not leak into app-card
    css .header bg:green3 p:4 fw:600

    <self>
        <.header> "App Header"
        <app-card>
        <app-card>
imba.mount do <app-root[d:grid gap:4 p:4]>
```

Any style you declare in a tag declaration will only ever affect the literal tags inside the declaration. You don't need to worry about affecting styles of deeply nested elements that might share the same class names. This is very practical, and allows us to safely use short and descriptive class names like `header`, `footer`, `body`, `content` etc, and use them for styling.

### Inherited styles

Scoped styles are also inherited when extending components, which makes it very powerful.

```imba
# ~preview=lg
import 'util/styles'
# these are global -- applies to everything in project
css @root ta:center
tag base-item
    css d:block m:2 p:3 bg:gray2
    css h1 fs:lg fw:600 c:purple7
    <self>
        <h1> "Heading"
        <p> <slot> "Description"

tag pink-item < base-item
    css bg:pink2
    css h1 c:pink7

tag custom-item < pink-item
    <self>
        <h1> "Heading"
        <p[fw:bold]> <slot> "Description"
        <div> "Show more..."

imba.mount do <div>
    <base-item> "Base item"
    <pink-item> "Pink item"
    <custom-item> "Custom item"
```

### Deep Selectors

```imba
# ~preview=lg
tag app-item
    <self> <p> "Normal"

tag app-root
    css p fw:600
    <self>
        <div> <p> "Bold"
        <div innerHTML='<p>Normal<p>'>
        <div> <app-item>

imba.mount do <app-root[d:grid gap:4 p:4]>
```

As you can see in the example above, the literal `<p>` inside `app-root` is styled by the scoped rule, while the `<p>` inside the nested `<app-item>`, and the `<p>` generated via innerHTML are _not_ styled. There are some cases where you don't want this strict scoping though. Imagine a component that renders markdown or really need to override styles for nested components.

The `>>>` operator _escapes_ the literal confines of the tag.

```imba
# ~preview=lg
# these are global -- applies to everything in project
tag app-item
    <self> <p> "Not bold"
tag app-root
    css div p fw:600
    css div >>> p c:blue6

    <self>
        <div> <p> "Literal"
        <div> <app-item>
        <div innerHTML='<p>Generated<p>'>
imba.mount do <app-root[d:grid gap:4 p:4]>
```

The `>>` operator styles immediate children, just like the `>` operator, but it also targets non-literal immediate children.

```imba
# ~preview=lg
# these are global -- applies to everything in project
tag app-item
    <self> <p> "Nested Paragraph"
tag app-root
    css div p fw:600
    css div >> p c:blue6

    <self>
        <div> <p> "Literal"
        <div> <app-item>
        <div innerHTML='<p>Generated<p>'>
imba.mount do <app-root[d:grid gap:4 p:4]>
```

## Inline Styles

You can add inline styles on any element using `[style-properties]` syntax. Think of this as an inlined anonymous class with a bunch of css properties. Instead of coming up with an arbitrary class name and adding styles somewhere else, you can simply add them to elements directly:

```imba
<div[position:relative display:flex flex-direction:row padding:2rem]>
```

This might look like regular inline styles, but with abbreviations and modifiers they become much more powerful and expressive:

```imba
# More padding on large screens:
<div[pos:relative d:flex fld:row p:2 @lg:3]>
# Darker background color on hover:
<button[bg:gray2 @hover:gray3]> "Click me"
# Set text color when input is focused:
<input[color@focus:blue7]>
```

Since inline styles are essentially anonymous classes, they can also be applied conditionally:

```imba
# line-through and lighter color if item is done
<div[p:2 color:green9] [td:s c:gray4]=item.done>
```

#### Interpolation

##### Specifying units

When you want to interpolate values with units you can include units after `{expr}` like `{expr}px`,`{expr}%` etc.

```imba
# ~preview
css div p:2 m:2 overflow:hidden min-width:80px

let ptr = {x:0, y:0}
imba.mount do
    <section[d:block pos:absolute inset:0] @pointermove=(ptr = e)>
        <div[bg:indigo2 w:{20 + ptr.x / 5}%]> "% width"
        <div[bg:green2 w:{ptr.x}px]> "px width"

```

##### Tip! Set properties directly

You can definitely use interpolated values with css variables as well, but it is best to interpolate them directly at the value where you want to use it. This way Imba can include the correct default unit if none is provided and more.

## Layout Shorthands

Imba adds non-standard values for the `display` (`d`) property that set up a complete flex layout with a single value. The values follow a 3-character pattern: `d:{v|h}{t|c|b|s}{l|c|r|s}`.

- The first character sets the direction — `v` for a vertical (column) layout, `h` for a horizontal (row) layout.
- The second character sets the vertical alignment — `t`op, `c`enter, `b`ottom or `s`tretch.
- The third character sets the horizontal alignment — `l`eft, `c`enter, `r`ight or `s`tretch.

It sounds a bit complicated, but it is intuitive once you get a feel for it. To center content on both axes you can use `d:vcc` or `d:hcc`. To pin content to the top left, `d:vtl` or `d:htl`. The `s` value stretches content on the cross axis, and distributes it with `space-between` along the main axis.

```imba
css .demo bg:teal2 c:teal8 m:1 p:1 rd:sm
css section d:block h:auto p:1
	div h:80px bd:1px dashed gray4 rd:md mb:2
imba.mount do
	<section>
		<div[d:hcc]> # horizontal, centered both ways
			<span.demo> "one"
			<span.demo> "two"
		<div[d:htl]> # horizontal, top left
			<span.demo> "one"
			<span.demo> "two"
		<div[d:hcs]> # horizontal, space-between
			<span.demo> "one"
			<span.demo> "two"
```

There are also two grid shorthands — `d:vgrid` (grid with auto-flow row) and `d:hgrid` (grid with auto-flow column and `1fr` auto-columns).

## CSS Variables

Variables can be set and accessed like in regular css
```imba
css div --varname:100px width:var(--varname)
```
For convenience, variables can also be accessed and set with a `$` prefix
```imba
css div $varname:100px width:$varname
```

## Interpolation

It is possible to interpolate dynamic values into styles. This happens efficiently at runtime using css variables behind the scenes. This allows you to even write dynamic styles in a declarative manner. **Interpolation is only supported in inline styles, and style blocks nested inside tags.**

```imba
# ~preview
css div pos:absolute p:3 t:2 l:2
css section d:block pos:absolute inset:0 user-select:none

let ptr = {x:0, y:0}
let num = 0
imba.mount do
    <section @pointermove=(ptr = e) @click=(num++)>
        <div[bg:teal2 x:{ptr.x} y:{ptr.y} rotate:{ptr.x / 360}]> "Full"
        <div[bg:purple2 x:{ptr.x / 2} y:{ptr.y / 2} rotate:{num / 45}]> "Half"

```

## Custom Units

You can define your own unit that can be used for styling and calculations. The unit can have modifiers like break points and you can use the units in the same way as other css units. The syntax to define a custom unit is `<measure><name>: <value>` e.g. `1col: calc(100vw / 12)`.

```imba custom-unit.imba
global css @root
    1pad: 25px
    1col: calc(100vw / 12)

tag app-dialog
    css 
        # span 12 columns by default,
        # 6 colums at >768px viewports
        # and 3 columns on >1280px viewports.
        width:12col @md:6col @lg:3col
        p: 1pad
```

## Keyframes

Keyframes are declared with `css @keyframes name` syntax. They work just like keyframes in css.

```imba
# to declare an anim available everywhere - use global
global css @keyframes blink
	0% c:white
	100% c:blue

# non-global animations are only available in the file
css @keyframes blink
	0% c:white
	100% c:blue
```

### Overriding animations in selector

One improvement over standard css is that you can define keyframes inside other selectors, and thereby override default animations of the same name.

```imba
# We have a global blink animation
global css @keyframes blink
	0% c:white
	100% c:blue
# animate all links on hover
global css a
	d:block bg:gray2 rd:md m:2 p:2
	@hover animation: blink 2s

# Override blink animation just inside #header .item
css #header a
	@keyframes blink
		from opacity:0
		to opacity:1

imba.mount do <div[pos:absolute inset:0 d:flex ja:center]>
	<a> "changing color"
	<div#header> <a> "fading"
```

---

Source: https://imba.io/docs/css/properties

# Style Properties

Imba supports all regular css properties. For a full reference on all css properties we recommend visiting the MDN docs. There are some custom properties and shorthands added in Imba that are very valuable. There is also a configurable design system (inspired by Tailwind) built in. Among other things, this features non-standard values for `display`, `box-shadow`, `border-radius` and `transition-timing-function`, as well as `color` palettes. The custom `hue` property is especially useful.

## Standard CSS Properties

<api-grid>css.own.properties.native</api-grid>

## Non-standard Properties

<api-grid>css.own.properties.custom</api-grid>

---

Source: https://imba.io/docs/css/modifiers

# Style Modifiers

Modifiers are css [pseudo-classes](https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-classes) with superpowers. They can be used in selectors wherever you would normally use a pseudo-class. All css pseudo-classes are available as modifiers, but Imba offers additional modifiers to make responsive styling easy, as well as a ton of other convenient modifiers you can read about further down. See the [guide](https://imba.io/docs/css/syntax#modifier-syntax) for additional details.

### Reference

<api-list>css.own.modifiers</api-list>

### Breakpoints

You can set your own custom pixel breakpoints by specifying any number you want after the `@` or `@!` symbols.
`@` for min-width, and `@!` for max-width.

```imba
css div@700 display:block # -> @media (min-width: 700px)
css div@!650 display:none # -> @media (max-width: 650px)
css div width:100% @700:80% @1300:1200px
```

---

Source: https://imba.io/docs/css/units

# Custom Units

Imba supports all the regular css units like `px`, `em`, `rem`, `vw` and friends — but it also lets you declare your *own* units, and change their value anywhere in the cascade.

You might have heard about `rem` (root em) units in css. The benefit of using rems is that you can resize your whole interface by changing a single font-size on the html element. Custom units take this idea further: they are arbitrary rem-like units that you name yourself, and that can be overridden inside any selector, class, media query or component. A design token you can multiply.

## Declaring Units

The syntax for declaring a unit is `1name: value` — read it as "one *name* equals *value*":

```imba
global css @root
    1fh: 24px # a unit named fh (field height)
    1gu: 8px # a unit named gu (grid unit)
    1col: calc(100vw / 12) # units can be any expression
```

Unit names can only contain letters (`a`-`z`). Once declared, use the unit anywhere a css value is expected, with any multiplier — fractions and negative numbers included:

```imba
css .field
    height:1fh
    padding:0.5gu
    margin-top:-0.25fh
    width:calc(100% - 2gu) # works inside calc too
```

> If a unit is used but never declared anywhere, the property will be dropped by the browser — so make sure your units are declared, typically at `@root`.

## Overriding Units

This is where custom units become really powerful. Since they are backed by plain css variables, they cascade — you can override them per selector, per class, and per media query:

```imba
global css @root
    1space:14px .dense:8px
    @lg 1space:18px .dense:12px
```

Now `1space` defaults to `14px`. Inside any element with a `.dense` class it becomes `8px`. On viewports wider than 1024px (the `@lg` modifier) both values scale up. Every single style written in terms of `space` — paddings, margins, gaps, sizes, multiples and fractions alike — follows along automatically.

```imba
global css @root
    1gu:10px
    .dense 1gu:5px

tag app-root
    css .box bg:indigo2 c:indigo8 rd:md p:1gu mt:0.5gu
    css button p:1gu rd:md bg:gray2 @hover:gray3

    <self[d:block p:1gu]>
        <button @click=flags.toggle('dense')> "Toggle density"
        <.box> "One"
        <.box> "Two"
imba.mount do <app-root>
```

Notice that toggling a single class rescales everything measured in `gu` — no extra rules needed.

## Local Units

Units don't have to be global. They can be declared at any level of your tree — inside components, selectors, even in inline styles — and only apply within that scope:

```imba
tag app-dashboard
    css self
        # sidebar width - wider on large screens
        1sbw:200px @lg:260px

    <self>
        <aside[w:1sbw]>
        <main[ml:0.5sbw pl:0.5sbw]>
```

Declaring units near where they are used keeps related measurements in one place — change `1sbw` once and the sidebar, margins and paddings all stay in sync.

## Not Just Lengths

Units aren't limited to lengths. Any value with a magnitude works — durations, for instance:

```imba
global css @root
    1beat:200ms

css .modal transition:opacity 1beat
css .drawer transition:transform 2beat
```

All your animations now share a common rhythm, and slowing the whole interface down is a one-line change.

## Dynamic Values

Custom units also work with interpolated values in inline styles. The multiplication happens efficiently at runtime via css variables:

```imba
let rows = 3
tag app-root
    css self 1fh:24px
    css .box bg:teal2 c:teal8 rd:md mt:2 d:grid ja:center

    <self[d:block p:2]>
        <input type='range' min=1 max=5 bind=rows>
        <.box[h:{rows}fh]> "{rows}fh tall"
imba.mount do <app-root>
```

## Built-in Units

Imba ships with a few units out of the box:

**`u`** — the base size unit, where `1u` is `4px`. This one is static — it is resolved to plain pixels at compile time and cannot be overridden. `4u` compiles straight to `16px`.

**`lh`** — the current line-height. Whenever you set `line-height` (including via the `fs:md/1.5` shorthand), Imba also records it as the `lh` unit, so `0.5lh` always means half the current line-height. Great for vertical rhythm.

**`rg`** and **`cg`** — the current row-gap and column-gap. Setting `gap` (or `rg`/`cg` individually) declares them, so children can size themselves relative to the gaps of their container:

```imba
css .grid
    d:grid g:4
    .spacer h:1rg # exactly one row-gap tall
```

## Under the Hood

Custom units are implemented as css variables with a `--u_` prefix.

```imba
global css @root
    1space:12px
    hr my:0.5space
```

Compiles to:

```css
:root {
    --u_space: 12px;
}
:root hr {
    margin-top: calc(var(--u_space,1space) * 0.5);
    margin-bottom: calc(var(--u_space,1space) * 0.5);
}
```

A declaration `1space:12px` becomes `--u_space:12px`, and a usage like `0.5space` becomes `calc(var(--u_space,1space) * 0.5)`. Since these are ordinary css variables, they inherit and cascade exactly like you'd expect — which is what makes overriding per selector, class and breakpoint work.

Note the `1space` fallback inside `var()`: any unit Imba doesn't recognize compiles this way, so newer css units that Imba is unaware of still work as-is — while remaining possible to override like any custom unit.

Standard css units (`px`, `em`, `rem`, `%`, `s`, `ms`, `deg`, `fr` and the rest) are passed through untouched and cannot be redefined — the same goes for the built-in `u` unit.

---

Source: https://imba.io/docs/css/colors

# Colors

[demo](https://imba.io/examples/css/colors.imba?preview=styles)

The color CSS data-type represents a color in the sRGB color space. Colors can be defined in all the same ways as in plain css. In addition, imba as built-in support for named colors hand-crafted by the great people behind [Tailwind](https://tailwindcss.com). All named colors come in 10 different shades, named from `color0` up to `color9`. You can hover over each color below to see their name:

<doc-colors></doc-colors>

Just like other colors like `#7A4ACF`, `hsl(120,90%,45%)`, `rgba(120,255,176)`, these named colors can be used anywhere in your styles where a color value is expected.

---

Source: https://imba.io/guides/transitions

# Transitions & Animation

> **Tip:** This is considered an [experimental](https://imba.io/experimental) feature.

Imba has support for transitioning when elements are added to and removed from
the document. If you set an `ease` attribute on a tag, ie. `<my-element ease>`,
imba makes it possible to easily style the enter-state and exit-state of the
element and its children, as well as the timing and easing of this transition.

Imba does not ship with any prebuilt transitions. This might change in a later
version, but the idea is that the syntax for styling is powerful enough to
easily create your own transitions.

```imba
# ~preview=md
import 'util/styles'

css label d:hcc us:none
css input mx:1

tag App
    alerted = no
    <self @click=(alerted = !alerted)>
        if alerted
            <div.alert> "Important message"
let app = imba.mount <App.clickable>
```

In the above example, we attach the `<div>` to the dom only when `alerted` is true. In many cases you may want to smoothly transition the element in and out instead of abruptly removing it. To do this in imba, we simply add an `ease` property to the `<div>` in question.

```imba
# ~preview=md
# css div p:2 m:2 overflow:hidden min-width:80px
import 'util/styles'
tag App
    alerted = no
    <self @click=(alerted = !alerted)>
        if alerted
            <div.alert[opacity@off:0] ease> "Important message"
let app = imba.mount <App.clickable>
```

Now that we have declared that this element should ease, we use the `@off` style modifier to specify the appearance of the element when it is detached from the dom. In this case, we set that the opacity should be set to 0. Imba will transition to/from `@off` state smoothly, but all easings and durations can be customized. Imba takes care of keeping the element attached to the dom until all transitions have finished.

If you want separate transitions depending on whether the element is being attached or detached, you can use the `@in` and `@out` modifiers:

```imba
# ~preview=md
# css div p:2 m:2 overflow:hidden min-width:80px
import 'util/styles'

tag App
    alerted = no
    <self @click=(alerted = !alerted)>
        if alerted
            <div.alert[y@in:100px y@out:-100px] ease> "In from below, out above!"
let app = imba.mount <App.clickable>
```
Now you can see that it comes in from the left, but leaves to the right. If the element is re-attached while exiting or detached while still entering, the transition will gracefully revert. You can see this by clicking the checkbox rapidly.

You can easily transition nested elements inside the eased element as well.

```imba
# ~preview=md
# css div p:2 m:2 overflow:hidden min-width:80px
import 'util/styles'
tag App
    alerted = no
    <self @click=(alerted = !alerted)>
        if alerted
            <div.alert[o@off:0 y@off:100px ease:1s] ease>
                <div[scale@off:0]> "Important message"
let app = imba.mount <App.clickable>
```

Click to see the inner div scale during the transition. Also note that we did set the duration of the transition using the `ease` style property. You can specify the ease duration and timing function for each element, and also specify them individually for transforms, opacity and colors. See properties.

---

Source: https://imba.io/guides

# Apps & Tooling

<doc-pages></doc-pages>

---

Source: https://imba.io/docs/router

# Router

Imba comes with a built-in router that works on both the client and
server. It requires no setup and simply introduces the
[route](api://Element.route) and [route-to](api://Element.route-to)
properties on elements.

```imba
# [preview=md] [titlebar] [route=/home]
tag app
	<self>

		<nav[d:hcc g:4 c:blue6]>
			<a route-to='/home'> 'Home'
			<a route-to='/about'> 'About'

		<[d:hcc h:100%]>

			<div route='/home'>
				'Home page.'

			<div route='/about'>
				'About page.'

imba.mount <app>
```

Elements with the `route` property will display when the provided
route matches the contents of the address bar.

`route-to` essentially works like `href`,
except it:
- Enables nested routes.
- Automatically adds an `active` class to the element whenever the
	route it links to is matching.

### Exact Routes

Any route that ends with `/` will be treated as an exact route.

```imba
# [preview=md] [titlebar] [route=/home]
tag app
	<self>

		<nav[d:hcc g:4 c:blue6]>
			<a route-to='/home'> 'Home'
			<a route-to='/home/test'> 'Test'

		<[d:hcc h:100%]>

			<div route='/home/'>
				'Home page.'

imba.mount <app>
```

Notice how the `Test` path doesn't go to the home page because
the home page route ends in a slash (`/home/`).

### Wildcard Routes

Any route that ends with `*` will be treated as a catch-all for that
path. Let's fix the previous example:

```imba
# [preview=md] [titlebar] [route=/home]
tag app
	<self>

		<nav[d:hcc g:4 c:blue6]>
			<a route-to='/home'> 'Home'
			<a route-to='/home/test'> 'Test'

		<[d:hcc h:100%]>

			<div route='/home/*'>
				'Home page.'

imba.mount <app>
```

We can use this to create a fallback route with `route='/*'` that will
match all routes.

> **Tip:** For the time being, routes that don't end in a slash will also be
considered wildcard routes. That means that `/home/*` and `/home` are
the same.

## Nested Routes

Routes that do not start with `/` will be treated as nested routes,
and resolve relative to the closest parent route. This works for both
`route` and `route-to`.

```imba
# [preview=md] [titlebar] [route=/home]
tag app
	<self>

		<[d:hcc h:100%]>

			<div route='/home'>
				css d:vcc

				<a route-to='nested'> 'Nested'
					css c:blue6

				'Home page.'

				<div route='nested'>
					'Nested page.'

imba.mount <app>
```

## Dynamic Routes

To map a url pattern to a component, you can use dynamic segments in
your routes. A dynamic segment starts with `:`. So the pattern
`/user/:id` with match `/user/1`, `/user/2` etc.

```imba
# [preview=md] [titlebar] [route=/user/1]
tag User
	<self>
		route.params.id

tag app
	<self>

		<nav[d:hcc g:4 c:blue6]>
			<a route-to="/user/1"> "User 1"
			<a route-to="/user/2"> "User 2"

		<[d:hcc h:100%]>

			<User route="/user/:id">

imba.mount <app>
```

You can also have multiple dynamic segments in a route, like
`/user/:user-id/post/:post-id`. All segments map to corresponding
fields in `route.params`. When using nested routes, even the params
from parent routes will be available in `route.params`.

## Route Precedence

Route ordering matters. In the following example, because the route
`/*` is the first route and matches all routes, the only page that
will be shown is the fallback page, no matter the route.

```imba
# [preview=md] [titlebar] [route=/home]
tag app
	<self>

		<nav[d:hcc g:4 c:blue6]>
			<a route-to='/home'> 'Home'
			<a route-to='/about'> 'About'

		<[d:hcc h:100%]>

			<div route='/*'>
				'Fallback route.'

			<div route='/home'>
				'Home page.'

			<div route='/about'>
				'About page.'

imba.mount <app>
```

Route precedence also applies to dynamic routes:

```imba
# [preview=md] [titlebar] [route=/items]
tag app
	<self>

		<nav[d:hcc g:4 c:blue6]>
			<a route-to='/items'> 'Items'
			<a route-to='/items/new'> 'New'
			<a route-to='/items/some-id'> 'ID'

		<[d:hcc h:100%]>

			<div route='/items/'>
				'Home page.'

			<div route='/items/new'>
				'New page.'

			<div route='/items/:id'>
				'ID page.'

imba.mount <app>
```

Notice how the `/items/new` route interferes with `/items/:id`.

## Loading Data

If you want to do something when the params change you can define a
`routed` method on your component. This will be called whenever the
route changes, and supply the new params, and a state object that is
unique for each matched route, but consistent over time (ie. when
navigating back to a previously matched set of params).

If you load anything asynchronously inside `routed` (using `await`),
the component will delay rendering until `routed` has finished.

A nice feature of the imba router is that the `params` of any
particular route match are constant. Matching `/genre/:id` with the
url `/genre/action` will always return the same `params` object!
This is useful for memoizing data etc.

In addition to this, `route.state` will always return an object that
is unique *per match*, but consistent over time. This is very useful
for caching data for a `component <--> matching-route` combination.

```imba app.imba
# [preview=md] [titlebar] [route=/genre/drama]
import 'util/styles'
import {genres} from 'imdb'

tag Genre

    def routed params, state
        console.log 'routed',params
        data = state.genre ||= await genres.fetch(params.id)

    <self[d:vts o@suspended:0.4]>
        <div> "{data.title} has {data.movies.length} movies in top 250"

tag app
    <self.app>
        <nav> for item in genres.top
            <a route-to="/genre/{item.id}"> item.title
        <Genre.page route="/genre/:id">

imba.mount <app>
```

As you can see in the example above, we cache data in the `state`
object supplied to `routed`. This will make sure you don't refetch the
data when you click on a genre you've seen before.

## Additional Information

The router for your application is always available via
[imba.router](api://imba.router).

---

Source: https://imba.io/docs/assets

# Importing Assets

Images, stylesheets and other assets are an important part of any web application. These things are integrated right into imba without any need for external bundlers like webpack or rollup. 

## Importing stylesheets

Even though you can style all of your app using the imba css syntax you might want to import external stylesheets as well. Import these just like you would import any other file.

```imba app.imba
import './assets/normalize.css'

tag App
	# ...
```

In the example above, the content of the normalize.css file will automagically be imported and bundled alongside your other styles.

You can also import the css generated by imba via a non-standard `src` attribute on the `style` element. This is especially useful for ssr applications where you don't want to ship your rendering code to the client, but obviously want the styles:

```imba server.imba
import {App} from './app'
app.get(/.*/) do(req,res)
	res.send String <html>
		<head>
			<title> "Application"
			<style src='./app'>
		<body> <App>
```

```imba app.imba
global css
	body bg:gray2 # ...

export tag App
	<self>
		<div[fw:bold]> "Welcome"
```

## Importing images

Any relative url reference you have in your styles will be extracted, hashed, and included with your bundled code.

```imba app.imba
tag App
	<self> <div[ bg:url(./logo.png) ]>
```

Also, relative src attributes on `<img>` elements will automatically be handled as assets

```imba app.imba
tag App
	<self> <img src='./logo.png'>
```

If you want to reference and use these images from your code as well, you can import them:

```imba app.imba
import logo from './logo.png'

tag App
	<self> <img src=logo>
```

These imported assets even have valuable metadata added to them:

```imba app.imba
import logo from './logo.png'

logo.url # the unique hashed url for this image
logo.size # size of assets - in bytes
logo.hash # unique hash of the contents of the asset
logo.body # the actual contents of the asset - only available on server
logo.width # width of the imported image
logo.height # height of the imported image

tag App
	<self> <img src=logo width=logo.width>
```

You can also use the dynamic import syntax for assets:

```imba app.imba
const states = {
	open: import('./icons/alert-circle.svg')
	closed: import('./icons/check-circle.svg')
	archived: import('./icons/package.svg')
}

<div> for issue in issues
	<div>
		<img.icon src=states[issue.state]>
		<span> issue.title
```

You can even interpolate these dynamic asset imports in css:

```imba app.imba
const states = {
	open: import('./icons/alert-circle.svg')
	closed: import('./icons/check-circle.svg')
	archived: import('./icons/package.svg')
}

<div> for issue in issues
	<div>
		<.icon[ bg:{states[issue.state]} ]>
		<.title> issue.title
```

## Importing svgs

SVGs can be imported and used just like other image assets described in the previous section. It does include some nice additional things though. You can use SVG images via css and the img-tag, but they really shine when you inline them in your html. Ie, if you want to use SVG images for icons you have to inline them to be able to change their color, stroke-width etc.

So, Imba adds a non-standard `src` attribute to `svg` elements, that magically inlines the actual content of the svg directly in your html.

```imba app.imba
<div>
	# the package.svg will now be inlined in this tag
	<svg src='./icons/package.svg'>
```

This also allows us to style the contents directly:

```imba app.imba
<div>
	# change color on hover
	<svg[c:gray6 @hover:blue7] src='./icons/package.svg'>
	# override stroke-width 
	<svg[stroke-width:4px] src='./icons/check.svg'>
```

## Importing scripts

Imba will analyze the `src` attribute of `script` elements and automatically package these files for you. So a typical project with server *and* client code will follow this pattern:

```imba server.imba
# some express server ...
app.on(/.*/) do(req,res)
	res.send String <html>
		<head>
			<title> "Gobias Industries"
		<body>
			<script type="module" src="./client">
```

```imba client.imba
# some client code here
```

When you run `imba server.imba` in the above example, imba will discover the reference to client.imba and create a bundle for the `client.imba` entrypoint. Using [esbuild](https://esbuild.github.io/) in the background, bundling is so fast that it literally happens every time you start your server – *there is no need for a separate build step*.

## Importing workers

Imba aims for zero-configuration bundling even with large projects. You can import scripts as separate assets via a special import syntax.

```imba app.imba

const script = import.worker './compiler'
# script is now an asset reference to the bundled compiler entrypoint.
script.url # reference to the unique/hashed url of this script
script.body # node only - actual contents of the bundle

const worker = new Worker(script.url)
```

To showcase how flexible and useful this is – on imba.io we are using a serviceworker to run examples. Serviceworkers need to be served from the directory / scope you want them to control, and their url need to be static. The asset urls generated by imba are usually hashed *and* put inside a special `__assets__` folder:

```imba app.imba
const sw = import.worker './sw/service'
sw.url # /__assets__/sw/worker.JNA7FI8P.js
```
This url changes whenever the content changes and is nested inside an `/__assets__/...` prefix, both of which can be challenging for a serviceworker. So, our solution was to create a static route in our server, and just serve the asset directly:

```imba app.imba
app.get('/sw.js') do(req,res)
	const asset = import.worker('./sw/service')
	res.send asset.body
```

## Custom imports

The `import.worker` syntax shown in the previous section is not a special syntax just for workers. In fact, the `import.anything(...)` is a general way to import something using a specific configuration. You can create such configurations in your `imbaconfig.json`. Imba comes with a few presets:

```imba presets.imba
export const presets = 
	node:
		platform: 'node'
		format: 'cjs'
		sourcemap: true
		target: ['node12.19.0']
		external: ['dependencies','!imba']
		
	web:
		platform: 'browser'
		target: ['es2020','chrome58','firefox57','safari11','edge16']
		sourcemap: true
		format: 'esm'
		
	iife:
		extends: 'web'
		format: 'iife'
		
	client:
		extends: 'web'
		splitting: true
		
	worker:
		format: 'esm'
		platform: 'worker'
		splitting: false

```

Most of the properties map directly to [esbuild options](https://esbuild.github.io/api/#simple-options), with some additions for imba specific things. Configuration options will be explained in more detail before final 2.0 release. In most projects you will not need to think about or tweak these configs.

## Future plans

### Glob imports

We are working on smart glob imports for a future release.

```imba app.imba
import icons from './feather/*.svg'

# contains all matching assets:
icons.check
icons.circle
...
```

This will also work directly in src paths, like:

```imba app.imba
<div> for issue in issues
	<div>
		<svg src="./icons/{issue.state}.svg">
		<div.title> issue.title
```

### Importing wasm

Will be part of a future release.

---

Source: https://imba.io/cli

# Command Line

> ! Run `npm -g install imba@latest` to get access to the CLI. Imba requires Node v20.19 or later.

Once installed, you have access to the `imba` command, which can execute scripts, serve files for development, and build projects for production. If you are starting from templates you might never be exposed to the underlying cli, and instead use commands like `npm run build` etc. But imba is a very capable language for writing everything from small scripts to large fullstack applications.

## imba _&#91;options&#93; script &#91;arguments&#93;_

The `imba` command is globally available and can be thought of as `node` on steroids. Just like you run your node scripts with `node script.js`, you run your imba scripts with `imba script.imba`. Behind the scenes Imba uses esbuild to compile _and_ resolve all the dependencies when running. If a `.env` file exists in your project root it is picked up automatically.

-   `-w, --watch`

    Watch for changes, rerunning the specified command when any related file changes. If you are fiddling with a script and want to rerun it after changes, all you need is `imba -w myscript.imba`.

-   `-d, --development`

    Use defaults for development: no minification, sourcemaps, watching with HMR, and `NODE_ENV="development"`.

-   `-p, --production`

    Use defaults for production: minified output, no sourcemaps, no HMR.

-   `-m, --minify`

    Enable minification of js and css files. Enabled by default for `imba build` and `--production`.

-   `-M, --no-minify`

    Disable minification. This is useful for configurations where minification is enabled by default, like for `imba build`.

-   `-s, --sourcemap`

    Include sourcemaps. Enabled by default unless building for production.

-   `-S, --no-sourcemap`

    Disable sourcemaps. This is useful for configurations where sourcemaps are enabled by default, like for `imba serve`.

-   `-f, --force`

    Disregard previously cached imba compilations and other optimizations and make sure all files are compiled now. Should only be needed for debugging.

-   `-v, --verbose`

    Increase log verbosity. Repeat to increase further — `-v` is equivalent to `--loglevel info`, `-vv` to `--loglevel debug`.

-   `--loglevel [level]`

    Set the log level explicitly: `debug`, `info`, `success`, `warning`, `error` or `silent`.

-   `-o, --outdir [dir]`

    Directory to output files. Defaults to `dist` for `imba build`; other commands write to a temporary directory.

-   `-k, --keep`

    Keep existing files in the output directory instead of clearing it.

-   `--base [prefix]`

    If you are deploying your project under a nested public path, specify the `base` option and all asset paths will be rewritten accordingly. Defaults to `/`.

-   `--assets-dir [dir]`

    Directory (relative to the output directory) where generated assets are written. Defaults to `assets`.

-   `--web`

    Build/run the script for clients. If you run an imba file with the `--web` argument it will automatically generate an accompanying html file and serve it up for your browser.

-   `--esm`

    Output ES module files. Since Imba bundles and resolves dependencies using esbuild this will not be needed in most cases.

-   `--bundle`

    Try to bundle all external dependencies into the output instead of resolving them from `node_modules` at runtime.

-   `--br`

    Also compress generated assets with brotli.

-   `-i, --instances [n]`

    If you specify n > 1, imba will run the script as a cluster and spawn _n_ instances. In development mode it will gracefully reload instances when the code has changed. Not applicable for `build`.

-   `--fork`

    Run instances as plain forks instead of a node cluster.

-   `--inspect`

    Start node with the inspector enabled so you can attach a debugger.

-   `--skipReloadingFor [glob]`

    While watching, skip reloading server code when files matching these globs change.

## imba build _&#91;options&#93; script_

The `imba build` command takes care of building your project for production. It builds an imba/js/html entrypoint and all of its dependencies, with production defaults (minified, no sourcemaps) unless overridden. In addition to the shared options above, `imba build` takes the following options:

-   `--platform [platform]`

    Platform for the entry. Defaults to `browser`.

## imba serve _&#91;options&#93; entry.imba | entry.html_

Convenience command for quickly serving up a script or an html page with an accompanying dev server with HMR and automatic reloading — equivalent to running an entry with `--web --watch`. Unless you specify a port it will pick a free port between 3000 and 3100.

-   `--port [port]`

    Specify the port to listen on.

-   `--host [host]`

    Specify the host to bind to. Pass `--host` without a value to bind to `0.0.0.0`.

-   `-i, --instances [n]`

    Run the server as a cluster with _n_ instances.

## npm create imba _&#91;options&#93; &#91;name&#93;_

Creates a new Imba project from a template. This is not part of the `imba` command itself — the scaffolder lives in the standalone [create-imba](https://www.npmjs.com/package/create-imba) package, run with `npm create imba@latest` (or `pnpm create imba` / `bun create imba` / `npx create-imba`). Run it without arguments for an interactive setup, or pass a project name (use `.` for the current directory).

-   `-t, --template [template]`

    Use a specific template instead of selecting one interactively: `default` (client only application), `express` (full stack application), `module` (a module usable from any JavaScript project) or `cli` (a CLI tool ready for npm publishing).

-   `-y, --yes`

    Say yes to any confirmation prompts.

-   `--fast`

    Generate a random project name, choose the default response for all prompts, and only print out the resulting directory name — useful for shell scripts.

## imba fmt _&#91;options&#93; &#91;formatters...&#93;_

Removes extra whitespace, debug logs, and commented logs from `**/*.imba` in your project.

-   `-f, --force`

    Format without checking git status first.

## imba info

Prints helpful information about your imba installation and environment.

---

Source: https://imba.io/guides/deployment

# Deployment

Imba runs on the server and the client.
See the relevant guide for deploying depending on your use case.

<doc-pages></doc-pages>

---

Source: https://imba.io/guides/deployment/static

# Static Deployment

In recent years, hosting static websites has become completely
free and relatively easy. With a host such as [Cloudflare
Pages](https://pages.cloudflare.com/), not only is hosting free,
but setting up a single page application requires zero
configuration due to their [helpful
defaults](https://developers.cloudflare.com/pages/platform/serving-pages/#single-page-application-spa-rendering).
These providers do have some
[limits](https://developers.cloudflare.com/pages/platform/limits/),
such as 500 builds per month maximum with a free plan, but most
of us aren't deploying our applications 16.67 times a day.

## Building

Build your project for production with `imba build` (see the
[CLI documentation](https://imba.io/cli)). The bundled output is written to
the `dist` directory by default - this is the directory you point
your static host at.

## FAQ

- `npm run dev` works, but when I deploy to a host the router doesn't work.

	Static HTTP servers like NGINX and Apache typically serve
	actual HTML files. In this situation, when a request is made to
	the server for `/home`, the server will look for a `/home.html`
	file to serve to the client. When the user navigates to
	`/about`, the server will look for an actual `/about.html`
	file.

	In a single page application with client side routing, however,
	we only have an `index.html` file that references our
	JavaScript which decides what to render based on the URL. As
	such, we want to route all requests to our `/index.html` file.

	If you're getting 404 errors when using Imba router, it is
	likely that your server is not routing all requests to your
	`/index.html` file. You can either switch to a host that
	supports this by default or look into configuring your server
	to route all requests to `/index.html`. For example, you could
	try adding the following block to your `nginx.conf`:

	```imba
	location / {
		try_files $uri /index.html;
	}
	```

---

Source: https://imba.io/guides/deployment/full_stack

# Full Stack Deployment

On the server, the recommended way is to use [Express](https://expressjs.com/), but anything in the JavaScript ecosystem is available to you.

There's a whole world of advice about how to structure Express applications, how to run Node.js in production, and keeping a website stable. From our experience of using Imba in production at [Scrimba](https://scrimba.com), we recommend using [PM2](https://github.com/Unitech/pm2). 

The [PM2 quick start](https://pm2.keymetrics.io/docs/usage/quick-start/) is a great way to get familiar with PM2. To keep this production Imba guide complete, we'll repeat some of that here. Always look to PM2's own documentation for the most up to date details.

Starting an Imba application with PM2 is as simple as `pm2 start app.js`, but we need to build the application first. Optionally, we can use a `ecosystem.config.js` file to configure PM2, for example using multiple processes, and where to write the server logs.

## Preparing the server

Setting up an entire server is beyond the scope of this guide. This is exactly the kind of thing you'll want to set up: [How To Set Up a Node.js Application for Production on Ubuntu 20.04](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-20-04)

If you've followed that guide, the server is ready to go with Node.js!

If not, you'll need to at least install and set up the following so you can run a Node.js script on your server:

- [Node.js and NPM](https://nodejs.org/). Imba requires Node v20.19 or later - we recommend the current LTS release.
- [PM2](https://pm2.keymetrics.io/). We strongly recommend using a process manager for Node, and PM2 is great.
- [nginx](https://nginx.org/en/docs/).

## Preparing your project for production

Although you can run Imba code directly with `imba your-imba-file.imba`, we strongly recommend building the files for production and using PM2 to run them.

The [Full stack starter](https://github.com/imba/imba-base-template) already comes with these settings configured, but if you're setting your project up by hand, you will need:

- A `ecosystem.config.js` file to configure PM2 to run the way you want: [Example ecosystem.config.js file](https://github.com/imba/imba-base-template/blob/main/ecosystem.config.js).
- A command to build the application for production mode: Add `"build": "imba build --production server.imba"` to your `package.json`.
- A way to start your application **the first time**: Add `"start": "pm2 start ecosystem.config.js --env=production"` to your `package.json`.
- A way to reload your application when the code has been updated: Add `"reload": "npm run build && pm2 reload ecosystem.config.js"` to your `package.json`.

Now you have a `package.json` file that has at least these scripts:

```json
  "scripts": {
    "dev": "imba -wMS src/server.imba",
    "build": "imba build --production src/server.imba",
    "reload": "npm run build && pm2 reload ecosystem.config.js",
    "start": "pm2 start ecosystem.config.js",
  }
```

And an `ecosystem.config.js` file that looks like this:

```js
module.exports = {
  apps : [{
    name   : "imba-base-template",
    script: "./dist/src/server.loader.js",
  }]
}
```

With this set up, you're ready to start your application: 

1. Upload your code to your server, for example using [GitHub Actions](https://docs.github.com/en/actions).
2. Run `npm install` in your project.
3. Run `npm run build` to build your application.
4. Run `npm start` to start up PM2 for the first time. If you get a `command not found` error, make sure you've installed PM2 globally on your server with `npm i -g pm2`.
5. All done! From now on, whenever you update the code of your project, you can run `npm run reload` to build your application again, and have PM2 use the new version of the code.

Congratulations on setting up your Imba application! You can now inspect your application with `pm2 logs` and update it with `npm run reload`.

---

Source: https://imba.io/other

# Reference

<doc-pages></doc-pages>

---

Source: https://imba.io/experimental

# Experimental

The following features of Imba are considered experimental. These
features do not affect the stability of Imba's core scripting and UI
building features, which remain in production use by multiple
companies, namely [Scrimba](https://scrimba.com). However, expect that
these experimental features are subject to syntax changes and
sometimes removal in favor of better features, and also potential
bugs.

<doc-pages></doc-pages>

---

Source: https://imba.io/docs/observable

# Observable

> **Tip:** This is considered an [experimental](https://imba.io/experimental) feature.

### TLDR

Imba provides MobX-like reactivity implemented as decorators.

- Properties decorated with `@observable` will be marked as
	observable, changing the way they interact with other
	properties as follows:

- Methods decorated with `@autorun` will be automatically invoked
	when any observable properties used by them change.

- Getters decorated with `@computed` will have their value cached
	on first use and will only recompute when any observable
	properties used by them change.

See the following guide for a holistic explanation of
`@observable` or jump to [reference information](#reference).

### Guide

In Imba, it's important to keep in mind that
[commit](https://imba.io/api/imba/commit) is called after every handled event.
This means that state changes which occur inside of event
handlers will be reflected in the next render. We can apply this
knowledge to implement a simplistic search:

#### The Inefficient Approach

```imba
css body d:flex fld:column jc:start ai:center p:5
css input bg:blue0 mb:1 rd:2 outline:none p:1 3 bd:1px solid blue3
	caret-color:blue4 bxs:sm bg@focus:blue1 transition:background 300ms
css div bg:gray1 rd:2 p:1 3 bdb:1px solid gray2 c:gray6 mb:1 bxs:xs
let query = ""
let words = ["apple", "orange", "strawberry"]
tag app
	<self>
		<input bind=query> # bind implicitly handles input events
		for word in words.filter(do $1.includes(query))
			<div> word
imba.mount <app>
```

There are some problems with this first approach:

- `words` is being filtered on every single render, even though
	it only needs to be updated when our query actually changes.

	If you were to implement everything this way, with multiple
	computation-heavy methods running on every render in multiple
	nested components, eventually your app would start to feel
	slow.

- Semantically, `words` being filtered has nothing to do with
	`render`. Regardless of performance, it doesn't really make
	sense for the filtering logic to live in the render method,
	since the two are not related.

We can implement a less wasteful pattern manually:

#### The Manual Approach

```imba
css body d:flex fld:column jc:start ai:center p:5
css input bg:blue0 mb:1 rd:2 outline:none p:1 3 bd:1px solid blue3
	caret-color:blue4 bxs:sm bg@focus:blue1 transition:background 300ms
css div bg:gray1 rd:2 p:1 3 bdb:1px solid gray2 c:gray6 mb:1 bxs:xs
let query = ""
let words = ["apple", "orange", "strawberry"]
let filtered_words = words
tag app
	def search
		filtered_words = words.filter do $1.includes(query)
	<self>
		<input bind=query @input=search>
		for word in filtered_words
			<div> word
imba.mount <app>
```

Now we are only filtering every time our `query` changes. This
addresses the issues listed above; it is now more efficient and
more semantic.

However, with our new approach there are some new problems:

- In situations where multiple sources can modify `query`, we
	have to manually call `search` after every modification or else
	`filtered_words` will be out of sync.

- We are forced to use an event listener (`@input`), a method
	(`search`), and an extra variable (`filtered_words`).

We can address some of these issues with `@autorun` and
`@observable`:

#### The Autorun Approach

```imba
css body d:flex fld:column jc:start ai:center p:5
css input bg:blue0 mb:1 rd:2 outline:none p:1 3 bd:1px solid blue3
	caret-color:blue4 bxs:sm bg@focus:blue1 transition:background 300ms
css div bg:gray1 rd:2 p:1 3 bdb:1px solid gray2 c:gray6 mb:1 bxs:xs
let words = ["apple", "orange", "strawberry"]
let filtered_words = words
tag app
	@observable query = ""
	@autorun def search
		filtered_words = words.filter do $1.includes(query)
	<self>
		<input bind=query>
		for word in filtered_words
			<div> word
imba.mount <app>
```

A method decorated with `@autorun` will be reactively invoked
whenever any `@observable` properties used by it change.

This example effectively works the same as the manual approach,
except now if we modify `query` from some other part of the code,
we don't have to remember to call search manually, which is
especially helpful when the code becomes more complex and
interrelated. We also don't need `@input` anymore.

For example, if the search bar were to double as an input to add
new entries upon clicking a button, typically we'd want to clear
the input after adding a new entry. In doing so, we'd have to
*remember* to call `search` after clearing `query`. If we forget,
our app may not behave the way we want, or it may even lead to
erroneous behavior in more complex situations.

#### Adding Words

```imba
css body d:flex fld:column jc:start ai:center p:5
css input bg:blue0 mb:1 rd:2 outline:none p:1 3 bd:1px solid blue3
	caret-color:blue4 bxs:sm bg@focus:blue1 transition:background 300ms
css div bg:gray1 rd:2 p:1 3 bdb:1px solid gray2 c:gray6 mb:1 bxs:xs
css button px:2 cursor:pointer c:blue5 outline:none c@active:gray4
let words = ["apple", "orange", "strawberry"]
let filtered_words = words
tag app
	@observable query = ""
	@autorun def search
		filtered_words = words.filter do $1.includes(query)
	def add_word
		words.push(query) if query
		query = ""
	<self>
		<input bind=query @keydown.enter=add_word>
		<button @click=add_word> "ADD"
		for word in filtered_words
			<div> word
imba.mount <app>
```

Notice how we don't have to call `search` after `query = ""`, we
can just change `query` freely and `search` gets invoked
automagically. When there are many different methods that can
change `query`, this becomes quite convenient.

It's also worth noting that if clearing `query` every time
`words` is changed were also part of our specification, we could
easily implement that with `@observable` and `@autorun` as well.
Feel free to try that out as an exercise!

#### The Computed Approach

`@autorun` is nice for calling functions, but in this example we
really only need a value, the computed array. If we want to get a
*value* rather than call a function, we can use `@computed`.
Let's simplify our running example a bit:

```imba
css body d:flex fld:column jc:start ai:center p:5
css input bg:blue0 mb:1 rd:2 outline:none p:1 3 bd:1px solid blue3
	caret-color:blue4 bxs:sm bg@focus:blue1 transition:background 300ms
css div bg:gray1 rd:2 p:1 3 bdb:1px solid gray2 c:gray6 mb:1 bxs:xs
let words = ["apple", "orange", "strawberry"]
tag app
	@observable query = ""
	@computed get filtered_words
		words.filter do $1.includes(query)
	<self>
		<input bind=query>
		for word in filtered_words
			<div> word
imba.mount <app>
```

A getter decorated with `@computed` will be cached on first use
and will only be recomputed whenever any `@observable` properties
used by it change.

Notice how our `search` method and `filtered_words` variable
have been merged into one getter.

### Reference

#### @autorun

- Methods decorated with `@autorun` will be automatically invoked
	when any observable properties used by them change.
- Autorun in classes:
	- Will run immediately after instantiation.
	- Does not call `imba.commit` automatically.
- Autorun in tags:
	- Will run immediately after mount.
	- Automatically dispose on unmount.
- `@autorun` also accepts modifiers passed as an object, currently:
	- `@autorun(delay: 100ms)` will debounce invocations by the
		specified amount of time.

#### @computed

- Getters decorated with `@computed` will have their value cached
	on first use and will only recompute when any observable
	properties used by them change.

#### @lazy

- Getters decorated with `@lazy` will only be evaluated once and
	then return the resulting value forever after.

#### @action

- Methods prefixed with `@action` can update multiple observables
	without causing multiple `@autorun` calls or `@computed` cache
	invalidations.

#### Differences from MobX

- Imba doesn't do comparisons on the output of `@computed` values
	since rendering is already memoized.
- Since Imba integrates MobX at the language-level it supports
	features that are not possible in plain JS, currently:
	- Observable subclasses.
	- Autorunning methods that automatically dispose.

#### Misc

- These features are tree-shaken out of your built imba projects
	when they are not used.

---

Source: https://imba.io/undocumented

# Undocumented

> **Tip:** Many of these are considered to be [experimental](https://imba.io/experimental) features.

Imba is moving extremely quickly and documenting every feature
becomes challenging. We intend to continually revise the
documentation as much as possible, but instead of not documenting
features *at all* until we have time, it's better to at least
expose them to power users who want to learn as much as possible
at the cost of reading something slightly less structured and
polished as the rest of the docs.

This also serves as a list of things that need to be documented
more formally, which is better than having all of them in our
personal notes. Contributions are highly appreciated, especially:

- Polishing any of these examples or creating your own examples.
- Moving examples to a relevant location on the documentation.
- Coming up with proper names for ambiguous features.

If you have questions about any of these, don't hesitate to reach
out on [Discord](https://discord.gg/mkcbkRw).

## Awaits

You can await desired changes to observable properties with `imba.awaits`,
which takes a callback that will be called every time the property is changed until the callback returns a truthy value.

```imba
let user = new class User
	@observable first_name = 'first'

setTimeout(&,100ms) do
	user.first_name = 'updated'

setTimeout(&,200ms) do
	user.first_name = 'again'

await imba.awaits do
	console.log user.first_name
	user.first_name is 'updated'
```

## No Hashing

The bundler currently always hashes output filenames (e.g. `assets/client.VYSTTIWZ.js`).
There is no supported option for disabling hashing at the moment. The generated
`dist/manifest.json` maps source entrypoints to their hashed output paths if you
need to reference the files from outside the project.

## General code events

In Imba you can emit and listen to events without needing the DOM:

```imba
imba.emit 'hello'
imba.listen 'hello'
```

## Emitting events on elements

`Element` is extended with an `emit` function.

```imba
some_element.emit('event_name')
```

## Circles

```imba
rd:full
```

compiles to

```imba
border-radius:9999px
```

## Platform Imports

If you name a file `os.node.imba` and another `os.imba` and import `os` it will import the one for the relevant platform.

## Generic Media Queries

```imba
@media(hover: hover)
```

## .env

Imba will automatically traverse up the file tree starting from
**the dirname of the file you ran with imba** in search for a `.env` file.
The contents will be accessable from `process.env`.

The `.env` file has the following syntax:

```imba
S3_BUCKET="YOURS3BUCKET"
SECRET_KEY="YOURSECRETKEYGOESHERE"
```

Accessing these variables in an imba file is as simple as `process.env.S3_BUCKET`. No configuration necessary.

Note that, unlike the dotenv library, Imba will not use the cwd to search for the `.env` file,
but rather the dirname of the file you ran.

## `arguments` shorthand

In line with `$1`, `$2`, etc. positional params, `$0` refers to [the arguments object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments#arguments_is_an_array-like_object).

## Spread Shorthand
```imba
let x = [1, 2, 3]
console.log(*x)
console.log(...x)
```

## Letting Branch Results

This is a common pattern:

```imba
def example
	let obj
	try
		obj = JSON.parse("this will error")
	catch e
		obj = {}
	console.log obj

example!
```

Instead we can do:

```imba
def example
	let obj =
		try
			JSON.parse("this will error")
		catch e
			{}
	console.log obj

example!
```

Or with less lines:

```imba
def example
	let obj =
		try JSON.parse("this will error")
		catch e {}
	console.log obj

example!
```

Or in one line:

```imba
def example
	let obj = try JSON.parse("this will error") catch e {}
	console.log obj

example!
```

Or without a catch:

```imba
def example
	let obj = try JSON.parse("this will error")
	console.log obj

example!
```

This can also be done with if/else statements.

## Platform

```imba
if $node$
	'Node'
if $browser$
	'Browser'
if $worker$
	'Worker'
if $web$
	'Web'
```

## Dataset Props

```imba
tag app
	def mount
		dataset.payload = "test" # sets the `data-payload` attribute on <app>
```

## Cooldown Flag

The cooldown event modifier will flag the `cooldown` class on the target element.

```imba
<button @click.cooldown(1s)=handler>
	css @.cooldown bg:blue
	"On click, will flash blue and not be clickable for 1s"
```

## Resize CSS Modifier

The `css` modifier for the `@resize` event will set the units `elw` and `elh` on the element on resize:

```imba
tag app
	<self @resize.css>
		css s:50px bg:rose4
```

If you inspect `<app>`:

```css
    --u_elw: 50;
    --u_elh: 50;
```

You can use them in css as units:

```imba
css w:1elw h:1elh
```

You can also pass in custom element names:

```imba
tag app
	<self @resize.css(1sectionwidth,1sectionheight)>
		css s:50px bg:rose4
```

Results in:

```css
    --u_sectionwidth: 50;
    --u_sectionheight: 50;
```

## Class Constructors

You can pass an object to class constructors to set instance properties:

```imba
global.L = console.log

class Note
	content = 'hello'

let note = new Note({content:'world'})

L note

let obj = JSON.parse(JSON.stringify(note))

L new Note(obj)
```

## Custom Events

```imba
global.L = console.log

tag app-button < button

	def on$click mods, context, handler, o
		L "self", self
		L "mods", mods
		L "context", context
		L "handler", handler
		L "o", o
		self.addEventListener('click',handler,o)

tag app

	<self>
		<app-button @click.log('clicked')> "log"

imba.mount <app>
```

`o` refers to `options`/`useCapture`: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#parameters

## Autorun Reactions

```imba
@observable one = ''
@observable two = ''
@autorun def my-function stop-observing
	one
	stop-observing! if stop-observing
	two # this will not trigger this autorun function even though it is observable
```

## Autorun Order

Autorun functions will run in the order they are declared.

## `def` In Objects

If you want to add a function to an object, you don't have to do:

```imba
let obj =
	add: do(a, b)
		a + b
```

You can just use the normal `def` syntax:

```imba
let obj =
	def add a, b
		a+ b
```

## Accessors

Imba allows you to delegate an object as the accessor for a field. Accessors
must conform to an interface. Namely, they must have a `$get`
method and a `$set` method.

```imba
class Uppercase

	def $set value, target, key
		target[key] = value

	def $get target, key
		target[key].toUpperCase!

let upcase = new Uppercase

class User
	name as upcase

let user = new User
user.name = "sindre"
console.log user.name
# SINDRE
```

Here, we are essentially delegating the `upcase` object as the
manager for getting and setting `name`.

## CSS value aliases

We've started to implement some value aliases, such as `pos:abs` and `pos:rel`. One caveat is that these shorthands can't be interpolated since
they're determined at compile time.

## CSS variables and durations

You can't use css variables to dynamically assign durations, you can either use custom units (`1animtime:10s`) or an interpolated value (`ease:{10}s`).

## Semantic Div Naming

Because Imba's css is so quick to write and flexible, the majority of the time it makes sense
to put css directly under elements as opposed to making a class or separate stylesheet:

```imba
tag app
	<self>
		<div>
			css bg:blue
```

But then everything that's not a custom element ends up being named `div`.
So you might put a semantic class name there that doesn't actually have any styles:

```imba
tag app
	<self>
		<.blue-thing>
			css bg:blue
```

It's nice because it's much easier to see what a certain layout is by reading an actual name.
The issue with this is that you have to worry about `.blue-thing` being defined somewhere else.

At Scrimba we've adopted the convention of using `%`:

```imba
tag app
	<self>
		<%blue-thing>
			css bg:blue
```

## PWAs With Imba

Imba's bundler has built-in support for importing service workers - see
[importing workers](https://imba.io/docs/assets#importing-workers) for how to bundle and
reference a service worker script with `import.worker`. Registering the worker
and choosing a caching strategy is up to you (there is no automatic
PWA/offline-caching plugin like Vite's `vite-plugin-pwa` - Vite support has
been removed from Imba).

## Any @ Selector Gets Collapsed

```imba
css @hover @focus @checked
```

The above essentially gets compiled to

```imba
css @hover@focus@checked
```

The same with `@.collapsed @.show-more`

If you want to nest them you'd do

```imba
css @hover
	*@focus
```

This is usually what you want with psuedo selectors.

## Super

In any inheritor class or tag, calling `super!` will call the inherited object's function.

```imba
tag modal
	def test
		console.log "hello"
		
tag my-modal < modal
	def test
		super!
		console.log "hello again"
```

Writing `super` without `()` or `!` will essentially call the super function with `...args`

You can also call other functions by using `super`:

```imba
super.setup!
```

## Swallowing all hotkeys

If, for example, you have a modal, and want to prevent all hotkeys:

```imba
@hotkey('*').global
```

## Specific Parent Selector

You can select a specific parent up the chain:

```imba
css ^.collapsed # if the direct parent has class .collapsed
css ^^^.collapsed # if the parent's parent's parent has class .collapsed
```

This is most useful for pseudo states:

```imba
css c^@hover:blue
```

## Parent Selector

This will apply opacity 0 if the `.collapsed` class is found *anywhere*
in the parent heirarchy chain, all the way to root.

```imba
css o..collapsed:0
```

## Color Precision

```imba
css c:blue4
css c:blue440
css c:blue450
css c:blue465
css c:blue5
```

## Tip: Globals & console.log

Writing `console.log` all the time feels quite verbose.
You might fancy writing `global.L = console.log` in your main/shared file.
This way you expose `L` to your entire app and can just do:

```imba
L "hello"
```

instead of

```imba
console.log "hello"
```

We use a capital name because lowercase names in Imba imply `self`.

## Font Size

```imba
fs:md-
```

## CSS Color Variables

```imba
css #site-bg:gray85
css bg:#site-bg
```

## &. and @.

If the current element has class `.blue`:
```imba
css &.blue bg:blue
```

If parent element has class use existing rich selector:
```imba
css @.blue bg:blue
```

## Error events

```imba
@error.trap
```

## Style flags

```imba
global css .dark bg:black c:white

tag app
	def mount
		self.flags.add('dark')
	<self> 'manual flags'

imba.mount <app>
```

## Adjusting HSL

```imba
css bg:blue3-3
```

## Class.inherited hook

Imba provides a way of interacting with a class when it is declared as the parent of another class. If your parent class has a static `inherited` method, it will be called with the subclass as an argument whenever some class inherits from it.

```imba
class Base
	static def inherited subclass
		console.log 'was inherited by',subclass

class User < Base

# => was inherited by [User]
```

## Define min/max width/height with shorthand

This is in undocumented because it is _very likely_ be removed for the final release. Currently it is possible to declare both min and max width/height with `>val` and `<val` in css props.

```imba
css div w:100px <80vw # width:100px max-width:80vw
css div h:80% >100px # height:80% min-height:100px
```

## Custom css modifiers

When you use an undefined `@modifier` in styles, it defaults to check for a `mod-nameofmodifier` class on the root element. So it is easy to use / add your own.

```imba
if state.user
	document.flags.add('mod-logged-in')

css div
	# you can use the @logged-in modifier anywhere in your app
	# it is true when html.mod-logged-in matches
	d:block @logged-in:none
```

Let's say you have a PWA and want specific styles when the app is opened outside of browser:
```imba
# set mod-standalone if we match that displayMode
document.flags.toggle('mod-standalone',
	window.matchMedia('(display-mode: standalone)').matches
)

global css body
	# different background when opening in standalone mode
	bg:white @standalone:gray
```

Add a modifier whenever a certain element is opened

```imba
tag base-page
	get ref do nodeName.toLowerCase!
	def mount do document.flags.add("mod-{ref}")
	def mount do document.flags.remove("mod-{ref}")

tag home-page < base-page
tag about-page < base-page

# Whenever a page is mounted the tag-name of the page
# can be used as a modifier globally in your styles
global css
	body hue:blue @home-page:indigo
	header d:hsl @home-page:none

```

## Preventing multiple events

```imba
@click.cooldown.confirm
```

If you don't provide a time for the cooldown, it will not allow any more events through until the promise of the callback has finished.