Duolith docs

0015. Components are files in components/, imported explicitly, with props declared in the script

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval as part of Specification v0
  • Planning item: D20 (explicit imports)

Context

The glossary defines a component as "a reusable file with markup, used by name inside a page". Pages need to pass values (props) and markup (children) into one, props given as expressions must stay live, a component's styles must not leak, and only pages may be routes.

Decision

  • A component is a .duo file under **components/** (subfolders allowed). It has the same three parts as a page. Files there are never routes; importing a file from pages/ is diagnostic E0117.
  • A page or component imports it explicitly in its script, as D20 recommends: import Card from "../components/Card.duo". The markup uses the imported name: <Card title="x" count={n}>children</Card>. Element names starting with a capital letter are components; one that is not imported is E0110, and an import that names no component file is E0111.
  • A component declares its props once, at the top of its script: let { title, count = 0 } = props<{ title: string; count?: number }>(); A prop is required when it has no default and its type does not mark it ? (inline type, or a type/interface declared in the same script). Unknown props are E0112, missing required props E0113, assigning to a prop E0114, props() in a page or not unpacked E0116. The compiler replaces the declaration: each use of a prop reads what the page passes at that moment, so props passed as expressions stay live, and defaults are computed once, when first needed. Functions are passed as props for events, such as onChange={(on) => (notifications = on)}.
  • Passed children appear where the component writes **<slot />**. They belong to the placing file: they use its state and expressions. <slot /> in a page is E0115.
  • Each placed copy runs the component's script once, so each has its own state. A component's script cannot export (E0118).
  • Styles in a component's <style> and its utility classes carry the component's own scope, so a page's .card and a component's .card never meet. On the web all component styles go into one stylesheet, _duolith/components.css, linked by pages that place components.
  • In the IR: ComponentIr { name, path, scope, props, view } (the view has the screen's shape), IrNode::Component { name, path, component, properties, bindings, children }, IrNode::Slot, and ScreenIr::components lists the resolved imports.

Alternatives considered

OptionWhy not
Components found by file name, no importD20: explicit imports type-check as plain TypeScript and agents get them right first time
Props as attributes declared in front matter YAMLA second language for something TypeScript already describes, with no types in the editor
export let title (Svelte 4)Overloads export, and props would look writable
Named <piece> sections nowThe glossary reserves "piece" for parts; one default slot covers the examples. Named slots can come later, likely under the word piece
Inline component styles into each pageRepeats CSS on every page that places the component

Consequences

The glossary lists "slot" as a word to avoid (in favour of "piece", for kit parts). This record proposes keeping <slot /> for a component's children and either adding it to the glossary or renaming it before Specification v0 is approved; that needs Mik's decision. Components that place themselves, directly or through others, are not detected yet and would recurse at runtime.