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.
| Declaration | Meaning | Assignable |
|---|---|---|
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.
Navigation
Written in a page's or layout's script, imported from @duolith/client:
| Call | Meaning |
|---|---|
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.duofile inpages/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.duois 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
.duofile incomponents/. It is never a route; only files inpages/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.duoand 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 butpages/;behaviours/is the convention. Every file inbehaviours/is checked, whether or not anything imports it. - E0177 refuses a behaviour file in
pages/, one spelt.behavior.duoor.behavior.ts, andname.behaviour.duobesidename.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"orimport {} from ...): import the behaviours by name; and a value import or re-export of a behaviour file from any.ts,.mtsor.ctsfile 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,derivedoreffect(imported from@duolith/client) or another behaviour (imported, or declared in the same file) at its top level. The build knowsstateby what it resolves to, so a local function namedstateis 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, anasyncor 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, soprops(),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'scalendarbehaviour, andduolith add DatePickercopies that behaviour into the app'sbehaviours/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 asbody.openorbody["open"], assigned asbody.open = false, bound asbind:checked={body.open}, called asbody.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): readbody.openwhere it is used, destructure the call itself, or writederived(() => 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 })followsnameas 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.