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
.duofile under **components/** (subfolders allowed). It has the same three parts as a page. Files there are never routes; importing a file frompages/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 atype/interfacedeclared 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 asonChange={(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.cardand a component's.cardnever 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, andScreenIr::componentslists the resolved imports.
Alternatives considered
| Option | Why not |
|---|---|
| Components found by file name, no import | D20: explicit imports type-check as plain TypeScript and agents get them right first time |
| Props as attributes declared in front matter YAML | A 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 now | The 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 page | Repeats 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.