# Directives

Directives are a syntax sugar for custom tags that adhere to a specific contract: they receive a `value` and (optional) `var` and return an object of attributes to spread into a tag.

## Details

### Basic Example

<onLongPress/attrs() {
  console.log("hello")
}/>

<button ...attrs>Say Hello</button>

With the syntax sugar, this becomes:

<button #onLongPress() {
  console.log("hello")
}>Say Hello</button>

### Full example

<abc #xyz=foo/>

Desugars to

<xyz/_attrs=foo var() { return _var() }/>
<abc/_var ..._attrs/>

### Bind syntax

The directive desugars before the bind desugars:

<abc #xyz:=foo/>

After the directive desugars:

<xyz/_attrs:=foo 
  ref() { return _ref() }/>
<abc/_ref ..._attrs/>

Then after the bind desugars:

<xyz/_attrs 
  value=foo 
  valueChange(_foo) { foo=_foo } 
  ref() { return _ref() }/>
<abc/_ref ..._attrs/>

### Implementation of a directive

A directive is a tag that

#### Example: `<on-visible>`

export interface Input {
  value: () => void;
  var: () => HTMLElement;
}

<intersection-observer 
  callback(entry) {
    if (entry.intersectionRatio > 0) {
      input.value();
    }
  }
  options={...}
  el=var
/>

## Core usage

### Style & Class

<div #style={ color: "blue" }/>

### [Controllable HTML Elements](https://hackmd.io/2rMF4DMfTAOD8flTUxE9EQ#Controllable-HTML-elements)

<let/name = "Marko"/>
<input #value:=name/>

### [CSS](https://hackmd.io/XEY0MK2ySI2GFrsADhS-vQ)

The `<css>` tag would be a transform, but its use as a directive would follow the same rules as other directives.

<div #css=`font-weight:bold;color:${color}`/>

## Limitations/Downsides

### No arbitrary transforms, can only affect attributes

- No `<div #if=condition>`
- No `<ReactComponent #react/>`

### Custom change handers are awkward

<let/name = "Marko"/>
<input #value=name #valueChange=console.log/>

Can use an intermediate `<let>` 🤮

<let/intermediate value=foo valueChange() { ... }/>
<abc #xyz:=intermediate/>

> Didn't we need this anyway for controllable components? [name=Luke]

### Composition

In some ways this is better than the original proposal, but the directives can kinda leak up the tree

If someone exposes a select like:

MySelect.marko

<select ...input> 
  <option>My Option</option>
</select>

You can then do the following

<MySelect #selectedValue:=xyz/>

### Name conflicts

Many names that would be used for these directives are very likely to conflict with other names:

- `#style` conflicts with the native
- `#class` conflicts with the Marko 5 Inline Class Components
- `value` seems like a very generic name for a tag
- etc.

#### Potential solution

`#style` => `someprefix-style`/`style-attrs`/etc.

### Attribute conflicts

If two directives return the same attribute, implemented as a normal spread, the last one wins, but that's maybe not the best thing? Do we want to have some sort of merging logic? Probably too many edge cases to realistically do that...

#### Example

<div #class={ foo: isFoo } #css=`color:blue;`/>

In this hypothetical example, both `#class` and `#css` would provide a `class` attribute to spread into the `<div>`. With a normal spread, only the `class` from `#css` would be present.

#### Potential solution

Handles space-separated attrs like `class` (would work for `style` too). And event handlers.

function mergeAttr(name, a, b) {
  const aType = typeof a;
  const bType = typeof b;
  if (aType === bType) {
    if (aType === "string") {
      return `${a} ${b}`;
    }
    if (name.startsWith("on") && aType === "function") {
      return function(...args) {
        a(...args);
        b(...args);
      }
    }
  }
  return b;
}

## Alternative Names for the concept

- Hashtags
- Ghost tags 👻
- Attribute tags 😅

## Alternative names for the passed tag variable getter

- `ref`
- `var`
- `for`
- `with`
- `get`

### Would be nice...

In some ways, if hoisting didn't require getter functions.

## Prior Art

- [Svelte Actions](https://svelte.dev/docs/element-directives#use-action)
- [Solid Directives](https://www.solidjs.com/docs/latest/api#use___)