Duolith docs

Script declarations and components (Specification v0 draft)

Elements, attributes, events and control flow are defined in elements.yaml. This file defines what a file's script declares for its markup, and component files. Decisions: 0013, 0014, 0015, 0028, 0029, 0031, 0033.

Reactive declarations

Written at the top level of a page's or component's script. After the declaration the name is used like any variable: no .value.

DeclarationMeaningAssignable
let count = state(0)A state value. Assigning it updates every view that shows it.Yes
let total = derived(() => price * quantity)Computed from state and other derived values, and recomputed when they change.No (E0109)
let { title, count = 0 } = props<{ title: string; count?: number }>()A component's props (components only, E0116).No (E0114)
let signedIn = state(false, { shared: "signed-in" })Shared state: one value for every screen that declares the name signed-in, for as long as the app runs. The first declaration's initial value is used.Yes
let { id, path, query } = route()The screen's route: the parameters its file name declares (E0146 for any other name), its path and its query. Fixed for the screen in a page; follows the screen in front in a layout.No

state, derived, props and bindable are imported from @duolith/client. A prop whose default is bindable(...), as in let { value = bindable("") } = props<{ value?: string }>(), is a bindable prop: the component may assign it and bind it (decision 0029). state, derived, props and route are imported from @duolith/client.

Written in a page's or layout's script, imported from @duolith/client:

CallMeaning
guard(() => condition || "/sign-in")At the script's top level only. Asked before the screen is shown, while it is in front whenever the state it read changes, and when back shows it again. A string redirects there (replacing the screen, same site only); a truthy value allows the screen; false, null or undefined shows not-found. A layout's guard covers every screen inside it.
navigate(href)Pushes the screen for href. Only http: and https: addresses are followed; another site opens with a full page load.
navigate(href, { replace: true })Replaces this screen, so back skips it. Same site only.
back()Pops to the previous screen of the visit, or, when there is none, goes one level up the path.

A page's script runs once for each screen of it, so it cannot export (E0147).

Layouts

  • A _layout.duo file in pages/ or a folder of it wraps every screen in its folder and the folders below; nested layouts sit inside their parent folder's.
  • It shows the screen inside it where it writes <slot /> (E0145 if it never does). <slot /> is for components and layouts only (E0115).
  • It stays mounted, with its state, while the screens inside it change.
  • pages/_not-found.duo is the screen for a path no page serves, shown inside the root layout. Other file names starting with _ are reserved (E0144).

Two-way binding

bind:value={name} (on input) and bind:checked={name} (on toggle) show the state variable name and assign it when the user changes the field. name must be a state variable of the same file, or a bindable prop of the component (E0108).

On a placed component, bind:value={name} binds the component's bindable prop value to the state name: the prop shows the state, and the component's writes assign it. Without a binding, the component's writes stay its own.

Components

  • A component is a .duo file in components/. It is never a route; only files in pages/ are.
  • A file imports a component in its script, relative to itself: import Card from "../components/Card.duo" (E0111 if there is no such component, E0117 if it is a page).
  • Markup places it by the imported name, which starts with a capital letter: <Card title="Hello" count={n}>children</Card> (E0110 if not imported).
  • Attributes are props. Text values are fixed; expressions stay live. A prop written with no value is true. Only declared props are accepted (E0112), and every required prop must be passed (E0113). A prop is required when it has no default and its type does not mark it optional.
  • The component shows the children it is given where it writes <slot /> (E0115 outside a component, E0119 with children). The children use the placing file's state.
  • A component may also write named slots, <slot name="leading" />. The placing file fills one with <piece name="leading">...</piece> directly inside the component (E0126 elsewhere, E0127 for a name the component does not show); children outside any piece go to <slot />.
  • Kit parts are imported by name: import { Button, ListRow } from "@duolith/kit" (E0123 for a name that is not a part). They are components like any other.
  • Each placed copy runs the component's script once and has its own state. A component's script cannot export (E0118).
  • A component's style block and utilities are scoped to the component.

Behaviours

A behaviour is script written once and called from any file's script (decision 0152).

  • A behaviour file is named <name>.behaviour.duo and holds one script block and nothing else: no markup, <style> or slot (E0172). It may instead be <name>.behaviour.ts, the same script without the --- lines, under the same rules. It may sit in any folder but pages/; behaviours/ is the convention. Every file in behaviours/ is checked, whether or not anything imports it.
  • E0177 refuses a behaviour file in pages/, one spelt .behavior.duo or .behavior.ts, and name.behaviour.duo beside name.behaviour.ts, in any folder of the project; an import of a file that is not there; a default or namespace import, and an import that names nothing (import "../behaviours/counter.behaviour.ts" or import {} from ...): import the behaviours by name; and a value import or re-export of a behaviour file from any .ts, .mts or .cts file of the project the build does not compile, such as a Node script, whether or not a page reaches it.
  • A behaviour is an exported function declaration whose body calls state, derived or effect (imported from @duolith/client) or another behaviour (imported, or declared in the same file) at its top level. The build knows state by what it resolves to, so a local function named state is not one, and importing it under another name (import { state as s }) is refused (E0180). Its script is written as a component's is: the same rewrites, so never .value. Other exported functions, types and constants are plain helpers, imported and called like any.
  • A behaviour is exported by name: export function counter(...), export { counter as tally }, or re-exported from another behaviour file, export { counter as tally } from "./counter.behaviour.ts". A function that makes state written as an arrow or function expression, an async or generator behaviour, a second parameter and a default export are refused (E0180). A behaviour may call another behaviour of its own file, exported or not.
  • A behaviour ends with one return { ... } of its own names (E0173): return { open, action, toggle }. A name it returns keeps its kind for the caller: a state may be assigned and bound, a derived value is only read (E0109), anything else is passed as it is. A behaviour may return nothing.
  • Its input is one parameter, written as a plain name (input) with its type, read where it is used and never written (E0174): not assigned, not through another name for it (const same = input; same.step = 2), not deeper (input.range.from = x), and not unpacked at the top of the body (let { start } = input), which would read each value once. A behaviour has no markup and is not a screen, so props(), guard(), a component or kit import, and state, derived values, effects or behaviour calls outside its functions are refused in a behaviour file (E0175), in every declarator of a statement. Behaviour files may import each other, but not in a cycle (E0176).
  • A file imports a behaviour by name, by the file's whole name: import { disclosure } from "../behaviours/disclosure.behaviour.ts". A type reference, typeof disclosure, is not a call. The kit's own parts share behaviours the same way: DatePicker and DateRangePicker both call the kit's calendar behaviour, and duolith add DatePicker copies that behaviour into the app's behaviours/ with the part.
  • A behaviour is called only at the top level of a script or of another behaviour, never in a condition, a loop, a handler or a nested function, where it would make new state each time (E0171). Each call has its own state, owned by the calling file for as long as it is shown.
  • What it returns can be destructured, let { open, toggle } = disclosure({ open: false }), with renames, defaults and a rest name (let { open: shown = true, ...rest } = ...), or kept as one object, let body = disclosure({ open: true }), read as body.open or body["open"], assigned as body.open = false, bound as bind:checked={body.open}, called as body.toggle() and passed on whole, with the same checks: assigning a returned derived value through the object is E0109 too, and TypeScript sees it as read-only. An unpacked name reads through the result where it is used, so it stays live. Unpacking deeper than the returned names (let { inner: { count } } = ..., an array pattern or a computed key) and, at the top of a script, copying a returned state or derived value into a variable (let open = body.open), spreading the object ({ ...body }) or unpacking it again (let { open } = body) read the values once and stop following them (E0178): read body.open where it is used, destructure the call itself, or write derived(() => body.open).
  • The argument is one object literal, and each property's whole expression stays live, as a prop does: characterCount({ text: name, limit: 24 }) follows name as it changes. An input passed as a variable (counter(options)), spread into the object or followed by more arguments is read once, and is refused (E0179). An input the behaviour wants to call declares a function type, and the caller passes a function; TypeScript checks which.
  • A value import from a behaviour file is not E0356: the build compiles the behaviour file into a module beside the pages and components that use it.
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 };
}

Example

components/Card.duo
---
import { props } from "@duolith/client";
let { title, subtitle } = props<{ title: string; subtitle?: string }>();
---
<view class="gap-3 p-4 rounded-lg bg-surface border">
  <text class="text-heading">{title}</text>
  <show when={subtitle}><text class="text-caption text-muted">{subtitle}</text></show>
  <slot />
</view>

Working examples: examples/control-flow, examples/components and examples/navigation.