Duolith docs

Behaviours

A behaviour is script written once and used from any page's, layout's or component's script: a search box with a debounce, a form step, a timer, something that opens and closes. It holds state, derived values and effects like a component's script does, but it has no markup, so two components that look nothing alike can share it (decision 0152). The rules are in [spec/language/script-and-components.md](../../spec/language/script-and-components.md#behaviours).

Writing one

Put it in behaviours/, named <name>.behaviour.ts:

// behaviours/disclosure.behaviour.ts
import { derived, state } from "@duolith/client";

export function disclosure(input: { open: boolean }) {
  let open = state(input.open);
  let action = derived(() => (open ? "Hide" : "Show"));

  function toggle() {
    open = !open;
  }

  return { open, action, toggle };
}

Or write the same script as <name>.behaviour.duo, between --- lines and with nothing after them. Choose .ts when you want the file to open as plain TypeScript in any tool, and .duo to keep it in the same language as the rest of the project. One name cannot be both.

The script is written as a component's is: assign open = !open, never open.value. A behaviour:

  • is a function declaration, exported by name (export function, or export { disclosure as toggle }), not an arrow, async or a generator;
  • takes one input, a plain parameter with its type, reads it where it uses it, and never writes it, through another name either;
  • ends with one return { ... } of its own names, so the build knows which are state and which are derived;
  • makes its state inside the function, never at the top of the file;
  • imports state, derived and effect from @duolith/client under their own names.

Other exported functions, types and constants in the file are plain helpers, imported and called like any. A behaviour may call another behaviour, imported or from its own file, and a behaviour file may re-export one from another: export { disclosure as toggle } from "./disclosure.behaviour.ts".

Using one

Import it by name, with the file's whole name, and call it at the top of the script. Each call has its own state.

components/Faq.duo
---
import { props } from "@duolith/client";
import { disclosure } from "../behaviours/disclosure.behaviour.ts";

let { question, answer } = props<{ question: string; answer: string }>();
let { open, action, toggle } = disclosure({ open: false });
---

<view class="gap-1 py-2">
  <button label={`${action} the answer`} on:press={toggle}>
    <text>{action}</text>
  </button>
  <show when={open}>
    <text>{answer}</text>
  </show>
</view>

Destructured names keep their kind: open is state, so it can be assigned and bound with bind:, and action is derived, so assigning it is E0109. A name may be renamed or given a default, let { open: shown = true } = .... Or keep the result as one object, and use its names through it:

let body = disclosure({ open: true });
...
<button label={body.action} on:press={body.toggle} />
<show when={body.open}><slot /></show>

body.action = "x" is E0109 too, and TypeScript shows it as read-only. The object may be passed on whole, to a function or a component's prop. Do not copy one of its values into a variable at the top of the script, let open = body.open, spread it, { ...body }, or unpack it again, let { open } = body: each reads the values once, and the copy stops following them (E0178). Read body.open where it is used, destructure the call itself, or write derived(() => body.open).

Live inputs

An object literal argument stays live, like a prop: each property follows what it reads. Here left follows name as it is typed:

---
import { state } from "@duolith/client";
import { characterCount } from "../behaviours/character-count.behaviour.duo";

let name = state("");
let { left, tooLong } = characterCount({ text: name, limit: 24 });
---
<input label="Name" bind:value={name} />
<text class:text-danger={tooLong}>{left} characters left</text>

The input must be written in the call: characterCount(options) would read options once, so it is E0179. When a behaviour wants to decide when to read a value, or to pass it arguments, it declares that input as a function type, and the caller passes a function. TypeScript checks which one a call passes.

What the build refuses

CodeWhen
E0171A behaviour is called in a condition, a loop, a handler or a nested function, where it would make new state each time
E0172A .behaviour.duo file has markup or a style block
E0173A behaviour's result is not one return { ... } of its own names
E0174A behaviour writes its input (directly, deeper, or through another name), unpacks it at the top, or its input is not a plain parameter
E0175A behaviour file uses props(), guard(), a component, or makes state outside its functions
E0176Behaviour files import each other in a cycle
E0177A behaviour file is in pages/, spelt .behavior, written in both forms, missing, imported by default or with no names, or imported from a .ts file the build does not compile
E0178A returned value is copied once: into a variable, by spreading the result or unpacking it again at the top, or by unpacking deeper than the returned names
E0179A behaviour's input is not one object written in the call
E0180A behaviour is an arrow or function expression, async, a generator, has a second parameter or is a default export, or state is imported under another name

duolith explain <code> says more about each. Working example: examples/components, where Card and Faq share disclosure and the page counts characters with characterCount.