Mixins / foldkit-mixins
How slots, styles, and behaviors fit together
There are five building blocks:
| Concept | Meaning |
|---|---|
| Slot | A named extension point in a view: root, input, label, trigger. |
| Slots | The contract listing which extension points exist and what each permits. |
| Style | Appearance attached to a slot: classes, inline declarations, and CSS rules. |
| Behavior | Element-level interaction attached to a slot (attributes and optional Mount). |
| SlotView | A pure Foldkit view that renders slots and resolves attached mixins. |
Style and Behavior both compile to a Mixin. The resolver combines their contributions and throws a diagnostic on ambiguous ownership instead of silently choosing a winner.
Styling follows a left-to-right pipeline where each step is type-checked by the one before it:
tokens -> ref -> pieces -> slots -> sheetTheme.tokens holds the shipped values; Theme.ref reads them by name; a Style piece is built from the refs; Style.forSlots puts pieces on a Slot; and Style.stylesheet collects rules into cascade layers (Style and Themes as typed knobs).
Where to find each topic
| You want to | Read |
|---|---|
| Make a view customizable | Quick start, Slots |
| Restyle a view or install a theme | Style, Themes as typed knobs |
| Add behavior to an element | Behavior |
| Add a key route to a widget | Keys (routes, mixins:key-conflict) |
| Declare and check accessibility rules | Obligations (A11y.conform) |
| Run rendered pattern checks | Conformance (Conformance) |
| Inspect what a view's attachments do | Describing a view |
| Redraw only what changed | Parts, Regions |
| Test a view or emit static CSS | Testing and static output |
To build a component of your own from Slots, primitives and a recipe, one concept at a time, follow Authoring components.
Why not just className and props?
A class name says only "append this string." A slot is a typed public customization point. It can say:
- this point is a text input rather than an arbitrary element;
- it publishes
inputbut notclick; - callers may set
aria-invalidbut may not replace the structuralrole; - this point is internal and cannot be targeted publicly;
- two independent behaviors may not both own the same event.
That matters once a design system, a feature, accessibility logic and product-specific behavior all need to customize the same view without knowing about each other.
When to attach mixins vs use model state
Use mixins when a view should be restyled or decorated where it is used, not only where it is defined, and you want those customizations checked.
Typical examples are a design system styling a feature component, a tooltip attached by a caller,
analytics on an existing action, ARIA decoration, a focus trap, a ResizeObserver, keyboard
behavior, or a reusable visual recipe.
Keep widget state (open/selected/value) in a Foldkit Model or Submodel: transitions belong in update, network calls run as Message → Command, and element-scoped DOM effects belong in a Mount. If a Behavior seems to need state, promote that state to a Submodel.