Mixins / foldkit-mixins
Accessibility contracts
const DialogPattern = A11y.pattern({
trigger: { capability: Capability.Interactive, events: [Event.Click] },
content: { capability: Capability.Container },
})
A11y.validate(DialogPattern, DialogSlots)A11y.validate is pure and DOM-independent. It checks the declared contract for missing or hidden
slots, capability mismatches and unpublished events or attributes. An optional requirement
tolerates an absent slot but still checks a present one. It does not certify WCAG compliance.
Three words stay apart here. A slot contract or a provides is declared: the author says so.
A11y.validate, A11y.check and A11y.conform are structural: they say the declarations fit
together. Only a browser test is rendered: it says the behaviour happened on a page. None of
them is WCAG conformance.
Conformance: the rendered check
Conformance from foldkit-mixins/testing is the rendered word. Each scenario takes a harness
and returns its findings as plain data, so a widget and a view assembled from primitives are held
to one behaviour. Conformance.harness({ cdp, userEvent }) is the harness for Vitest's browser
mode: keys from userEvent.keyboard, roles and names from Chromium's own accessibility tree
(which Vitest's locators do not match), read inside its root (the document by default) with each
node's DOM element, and a pointer press as dispatched events. It takes the two from you, so
foldkit-mixins imports no test runner. cdp is the Playwright provider's, so a test file
names it first (/// <reference types="@vitest/browser-playwright" />, which types the session):
import { Conformance } from 'foldkit-mixins/testing'
// import { cdp, userEvent } from 'vitest/browser'
declare const button: HTMLElement
const harness = Conformance.harness({ cdp, userEvent })
const result = await Conformance.listbox(harness, {
name: 'Frequency',
options: ['Hourly', 'Daily', 'Weekly'],
disabled: 'Daily',
orientation: 'horizontal',
direction: 'rtl',
enter: async () => button.focus(), // gives the keyboard to the widget, options drawn
})
console.log(Conformance.failures(result)) // []Conformance.listbox, .checkbox, .tree, .dialog (focus in, Tab contained, Escape, focus
restored, a second dialog opened over the first) and .tabs read what the page did: roles and
names from the accessibility tree, aria-selected, aria-checked and aria-expanded from the
page, focus from document. They read no Model, Slot or obligation. Conformance.server(scenario,
root, expected) is the server half: parse a rendered string and it checks each expected role,
name and attribute. Another runner gives a Conformance.Harness of its own ({ root, press,
accessibility, click }). SlotView.describe(view).conforms lists the patterns a view was conformed to.
Obligations: who does what a pattern asks
A contract that publishes keydown on a list does not navigate it, and one that publishes
aria-selected does not write it. A pattern's slot can also name obligations: things an
attachment must say it does on that slot.
| Obligation | Means | Supplied by |
|---|---|---|
A11y.Navigation | Arrows, Home, and End move among items | ListNavigation, RovingTabindex, TreeNavigation, GridNavigation, SpatialNavigation |
A11y.FocusStrategy | Every item is reachable by keyboard | The five navigation behaviors above; A11y.native |
A11y.Activation | Enter, Space, or click activates item | Selection (unless click: false), Press; A11y.native |
A11y.State(attr) | Attribute written on every render | Selection, Behaviors.ToggleState, Behaviors.Disclosure |
A11y.Name | Element has an accessible name | Behaviors.FieldAssociation; view label (A11y.base) |
Something supplies an obligation in one of four ways: a Behavior slot's provides
(Behavior.slot({ provides: [A11y.Navigation], ... }), as the primitives above declare theirs);
A11y.base({ slot: [...] }), the view's own attributes on the author's word; A11y.native({ slot:
[...] }, { element: 'button' }), what a native element does by itself; and
A11y.delegated({ slot: [...] }, { to, provider }), an obligation met on another slot by an
attached Behavior. The last three are Mixins that contribute nothing, attached with
SlotView.attach. A11y.conform checks the assembled view:
import { ListNavigation, Selection } from 'foldkit-primitives/interaction'
const Listbox = A11y.pattern({
listbox: { capability: Capability.Interactive, obligations: [A11y.Navigation, A11y.Name] },
option: {
capability: Capability.Focusable,
obligations: [A11y.FocusStrategy, A11y.Activation, A11y.State(Attr.AriaSelected)],
},
})
const Options = SlotView.over(ListboxSlots)<FruitInput, FruitMessage>()
const itemsOf = (input: FruitInput) => Behaviors.Collection.of(input.fruit, { id: name => name })
export const FruitList = Options.define((input, slots, h) =>
h.ul(
slots.listbox.attrs([h.AriaLabel('Fruit')]),
input.fruit.map((name, index) => h.li(slots.option.attrs([], { id: name, index }), [name])),
),
).pipe(
Behavior.attach(
ListNavigation.behavior(List, listArgs)(Options)({
container: 'listbox',
item: 'option',
items: itemsOf,
text: (input, index) => input.fruit[index] ?? '',
}),
),
Behavior.attach(Selection.behavior(Sel, selArgs)(Options)({ item: 'option', items: itemsOf })),
SlotView.attach(A11y.base({ listbox: [A11y.Name] })),
A11y.conform(Listbox),
)What each call means:
A11y.patternand the obligation tokens are data. Obligations are compared by name, so twoA11y.State(Attr.AriaSelected)are one.- The view restates nothing
ListNavigationandSelectionsupply. Given the binder, each factory states what it supplies from the slot names it was given ('listbox/navigation','option/focus-strategy'), and a view's type collects them throughpipe. LeaveSelectionout and theconformline is a type error naming'option/activation' | 'option/state:aria-selected', and nothing the steps before it supply. A factory that hands back several Behaviors (Overlay.behaviors) is one step,Behavior.attachAll(list):pipetakes typed steps only, so a spread array is refused. A factory called with bare slots ((slots)<Input, Message>) states nothing, so such a view is judged at run time only. A factory states only what its run time is sure to supply:Selectionstates activation for a literalmodeof'single'or'multiple'with its click on (left out ortrue), and a slot name known only at run time (a union,string) states nothing, throughA11y.ProvidedOn. The type may then refuse a view the run time would pass; call that factory with bare slots and it is judged at run time alone. - At run time
conformrunsA11y.check(pattern, view)once, where the module loads, and throws aDiagnosticErrorfor the first finding (a11y:unsatisfied-obligation, withslotanddetails.obligation;a11y:delegation-unmet, naming the provider), every finding indetails.diagnostics. Run time reads each attachment'smeta, never a type, so a type that claims more than its value supplies still fails here. An assembly whose slot names are not known to the type checker (built from aRecord<string, …>) is judged here alone. conformreturns a new view that remembers the pattern:SlotView.detachandSlotView.replacecheck the view they make again, so detachingListNavigationfromFruitListthrows. The viewconformwas given is unchanged.A11y.conforminspects slot declarations statically without rendering or running Mounts.A11y.checkreturns the same findings as data, andA11y.validatechecks a bare contract.- A page pays for the check only where it conforms: every SlotView carries the record
conformleaves fordetachandreplace(331 bytes minified, 228 brotli), and the module holdingconform,checkand the obligation tokens adds 4.0 kB minified, 1.2 kB brotli, to a page that imports it (measured with esbuild over the source, 2026-11-14).
A Behavior written by hand on the binder states its names from its slots' provides, with no
annotation; this one's type supplies 'clear/activation':
const Clears = Options.behavior(
{
clear: Behavior.slot({
provides: [A11y.Activation],
attributes: ({ h }) => [h.OnClick(FruitMessage.Cleared())],
}),
},
{ name: 'Clears' },
)Behavior.forSlots(slots)<Input, Message>(spec) reads no provides, since TypeScript infers no
type argument once one is given: use the binder. An annotation may forget what a value supplies,
never claim more: a SlotView.SlotView<Slots, Input, Message> written out supplies nothing, so
conform on it is a type error until the annotation names what it supplies (or is dropped), and
typing Options.behavior({}) as supplying 'clear/activation' is refused. A view that
SlotView.detach or SlotView.replace makes supplies nothing at the type level, whichever
attachment it took: names are not in the type, and taking away what one attachment supplied may
leave another supplying it. conform after either is a type error until something is attached
again, and the run-time check, made again for a conformed view, is the judge of the result. A
delegation names only
what its provider supplies on to, and to is one of the provider's slots; both are type
errors otherwise. A pattern without obligations, and a Behavior without provides, behave as
before.
Introspection
The contracts are data:
Slots.describe(contract)andSlot.describe(slot)return serializable metadata;SlotView.describe(view)andSlotView.resolution(view, input)describe an assembled view.Mixin.composecombines mixins;Mixin.make,Mixin.dynamicandMixin.emptybuild them.- diagnostics have stable codes and structured
details, so the same information can feed tests, DevTools, documentation or agent tooling.