Guides
Composition: data, templates, or both
Write markup when the structure is fixed; pass data when it comes from somewhere else; describe a whole interface as data when an agent or a server produces it.
Which to use
| When | Use |
|---|---|
| The structure is known when you write it | Markup: slots and children |
| A list comes from an API or a CMS | A data property, validated by its model |
| Most entries are data, a few need custom markup | Data plus slots (hybrid) |
| An agent or a server describes the interface | A composition document |
Validate external data
TypeScript types do not check JSON at run time. Data properties publish a model that does, and the same model is a JSON Schema:
import '@oddkin/components/define/side-nav';
import { NavigationItemModel } from '@oddkin/components/models';
const nav = document.querySelector('odd-side-nav');
const result = NavigationItemModel.validate(await (await fetch('/nav.json')).json());
if (result.ok) nav.items = result.value;Replace the array to change entries; never mutate it. The side navigation guide shows data, markup, and hybrid side by side.
Interfaces as data
@oddkin/components/composition validates and renders a composition document: published elements, attributes, and properties only, with actions reported to your handler by name. See Agent tooling and data-composition.md §8.