Mixins / foldkit-mixins

Accessibility contracts

ts
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):

ts
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.

ObligationMeansSupplied by
A11y.NavigationArrows, Home, and End move among itemsListNavigation, RovingTabindex, TreeNavigation, GridNavigation, SpatialNavigation
A11y.FocusStrategyEvery item is reachable by keyboardThe five navigation behaviors above; A11y.native
A11y.ActivationEnter, Space, or click activates itemSelection (unless click: false), Press; A11y.native
A11y.State(attr)Attribute written on every renderSelection, Behaviors.ToggleState, Behaviors.Disclosure
A11y.NameElement has an accessible nameBehaviors.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:

ts
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.pattern and the obligation tokens are data. Obligations are compared by name, so two A11y.State(Attr.AriaSelected) are one.
  • The view restates nothing ListNavigation and Selection supply. 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 through pipe. Leave Selection out and the conform line 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): pipe takes 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: Selection states activation for a literal mode of 'single' or 'multiple' with its click on (left out or true), and a slot name known only at run time (a union, string) states nothing, through A11y.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 conform runs A11y.check(pattern, view) once, where the module loads, and throws a DiagnosticError for the first finding (a11y:unsatisfied-obligation, with slot and details.obligation; a11y:delegation-unmet, naming the provider), every finding in details.diagnostics. Run time reads each attachment's meta, 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 a Record<string, …>) is judged here alone.
  • conform returns a new view that remembers the pattern: SlotView.detach and SlotView.replace check the view they make again, so detaching ListNavigation from FruitList throws. The view conform was given is unchanged.
  • A11y.conform inspects slot declarations statically without rendering or running Mounts. A11y.check returns the same findings as data, and A11y.validate checks a bare contract.
  • A page pays for the check only where it conforms: every SlotView carries the record conform leaves for detach and replace (331 bytes minified, 228 brotli), and the module holding conform, check and 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':

ts
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) and Slot.describe(slot) return serializable metadata; SlotView.describe(view) and SlotView.resolution(view, input) describe an assembled view.
  • Mixin.compose combines mixins; Mixin.make, Mixin.dynamic and Mixin.empty build them.
  • diagnostics have stable codes and structured details, so the same information can feed tests, DevTools, documentation or agent tooling.