Mixins / Authoring components
Building filter chips, step by step
Suppose you need a row of filter chips: arrows move focus between chips, Space and Enter toggle selection, Delete removes a chip with an exit fade, and a button removes all selected chips.
1. Slots, a style, and a view
Start with a group of toggle buttons whose selected IDs live in your Model:
import { Schema } from 'effect'
import { defineMessageUnion } from 'foldkit/message'
import { modifyFields } from 'foldkit/struct'
import { Capability, Event, Slot, Slots, SlotView, Style } from 'foldkit-mixins'
import { Theme } from 'foldkit-mixins/theme'
const Chip = Schema.Struct({ id: Schema.String, label: Schema.String })
const Model = Schema.Struct({ chips: Schema.Array(Chip), picked: Schema.Array(Schema.String) })
type Model = typeof Model.Type
const Message = defineMessageUnion({ Toggled: { id: Schema.String } })
type Message = typeof Message.Type
const update = (model: Model, message: Message) =>
Message.match(message, {
Toggled: ({ id }) => ({
model: modifyFields(model, {
picked: picked =>
picked.includes(id) ? picked.filter(each => each !== id) : [...picked, id],
}),
}),
})
const ChipSlots = Slots.define({
group: Slot.make({ capability: Capability.Container }),
chip: Slot.make({ capability: Capability.Interactive, events: [Event.Click] }),
})
const t = Theme.ref(Theme.standard())
const ChipStyle = Style.forSlots(ChipSlots)(
{
group: Style.self({ display: 'flex', flexWrap: 'wrap', gap: t.space.xs }),
chip: Style.compose(
Style.self({
borderRadius: t.radius.full,
paddingInline: t.space.sm,
backgroundColor: 'transparent',
}),
Style.states({ true: { backgroundColor: t.accent.default } }, 'aria-pressed'),
),
},
{ name: 'ChipStyle' },
)
const Chips = SlotView.over(ChipSlots)<Model, Message>()
export const ToggleChips = Chips.define((model, slots, h) =>
h.div(
slots.group.attrs([h.Role('group'), h.AriaLabel('Filters')]),
model.chips.map(chip =>
h.button(
slots.chip.attrs([
h.Key(chip.id),
h.Type('button'),
h.AriaPressed(String(model.picked.includes(chip.id))),
h.OnClick(Message.Toggled({ id: chip.id })),
]),
[chip.label],
),
),
),
).pipe(Style.attach(ChipStyle))Slots.definedeclares the component anatomy (chippublishesEvent.Clickso Behaviors can rely on it).Theme.ref(Theme.standard())emits CSS custom property references (var(--fk-space-xs)) checked against the theme schema.Style.states(..., 'aria-pressed')matches DOM state (&[aria-pressed="true"]); input-only conditions useStyle.whenInput.slots.chip.attrsgives the view sole ownership ofOnClick; attaching a second click handler fails loudly at render time.
Native buttons give basic keyboard support, but every chip is a separate tab stop. Turning the row into a listbox with roving arrow navigation and animated exits brings in placed primitive Bundles.
2. State: Model fields and placed Bundles
Keep domain data (chips) in your Model, and place ListNavigation, Selection, and per-chip Presence Bundles for interaction state:
import { Match, Option, Schema } from 'effect'
import { defineMessageUnion } from 'foldkit/message'
import { modifyFields } from 'foldkit/struct'
import * as Update from 'foldkit/update'
import { Bundle, Link } from 'foldkit-bundle'
import { ListNavigation, Presence, Selection } from 'foldkit-primitives/interaction'
import { PresenceMessage } from 'foldkit-primitives/motion'
export const Chip = Schema.Struct({ id: Schema.String, label: Schema.String })
export type Chip = typeof Chip.Type
export const Nav = Bundle.declare(ListNavigation.bundle, 'nav')
export const Picks = Bundle.declare(Selection.bundle, 'picks')
export const GotPresence = Link.keyedWrapper('GotPresence', PresenceMessage)
export const navArgs = {
orientation: 'horizontal',
loop: true,
virtual: false,
timeoutMs: 500,
page: 5,
} as const
export const pickArgs = { mode: 'multiple', allowEmpty: true } as const
export const Model = Schema.Struct({
...Nav.fields,
...Picks.fields,
id: Schema.String,
chips: Schema.Array(Chip),
presence: Schema.Record(Schema.String, Presence.bundle.Model),
})
export type Model = typeof Model.Type
export const Message = defineMessageUnion({
...Nav.cases,
...Picks.cases,
...GotPresence.cases,
Removed: { id: Schema.String },
RemovedPicked: {},
})
export type Message = typeof Message.Type
export const chipId = (model: Pick<Model, 'id'>, chip: Chip): string => `${model.id}-${chip.id}`
export const phaseOf = (model: Pick<Model, 'presence'>, id: string): Presence.Phase => {
const placed = Object.hasOwn(model.presence, id) ? model.presence[id] : undefined
if (placed === undefined) throw new Error(`chip ${id} is drawn with no Presence placed`)
return placed.phase
}
const Parent = Bundle.parent({ Model, Message })
const Picked = Parent.at(Picks, { args: pickArgs })
const Exits = Presence.bundle.each(Link.collection<Model>()('presence', GotPresence), {
args: { durationMs: 150 },
onMessage: (_message: PresenceMessage, id: string) => (model: Model) =>
phaseOf(model, id) === 'hidden'
? Picked.helpers.replace(model.picks.selected.filter(each => each !== id))(
modifyFields(model, {
chips: chips => chips.filter(chip => chipId(model, chip) !== id),
presence: presence =>
Object.fromEntries(Object.entries(presence).filter(([key]) => key !== id)),
}),
)
: { model },
})
export const assembly = Bundle.assemble<Model, Message>()([
Parent.at(Nav, { args: navArgs }),
Picked,
Exits,
])
const hideAll = (model: Model, ids: ReadonlyArray<string>) =>
Update.combine(
model,
ids
.filter(id => Object.hasOwn(model.presence, id) && phaseOf(model, id) === 'shown')
.map(id => Exits.helpers.hide(id)),
)
export const update = assembly.update((model, message) =>
Match.valueTags(message, {
Removed: ({ id }) => hideAll(model, [id]),
RemovedPicked: () => hideAll(model, model.picks.selected),
}),
)Bundle.declareandParent.at/.each: Spread each primitive's fields and message cases into your parentModelandMessage, then letassembly.updateroute child messages automatically.- Helpers over direct mutation: The parent updates
picksandpresenceviaPicked.helpers.replaceandExits.helpers.hideso each primitive runs its own transitions and timers (Update.combinemerges their commands). - Identity on no-op: Unchanged branches return the original
modelreference so Foldkit skips unnecessary redraws.
See Bundle versus Submodel for how Bundles compare with hand-wired Submodels.
3. Interaction: primitive Behaviors and key routes
Wire ListNavigation.behavior, Selection.behavior, and a Keys.behavior onto a SlotView:
import { Attr, Behaviors, Capability, Event, Slot, Slots, SlotView } from 'foldkit-mixins'
const { Keys } = Behaviors
export const ChipSlots = Slots.define({
root: Slot.make({ capability: Capability.Container }),
list: Slot.make({ capability: Capability.Container, events: [Event.KeyDown] }),
chip: Slot.make({
capability: Capability.Focusable,
events: [Event.KeyDown],
attributes: [Attr.AriaSelected],
}),
remove: Slot.make({ capability: Capability.Interactive, events: [Event.Click] }),
})
const Filter = SlotView.over(ChipSlots)<Model, Message>()
const chipsByModel = new WeakMap<Model, Behaviors.Collection.Items<Chip>>()
export const itemsOf = (model: Model): Behaviors.Collection.Items<Chip> => {
const known = chipsByModel.get(model)
if (known !== undefined) return known
const items = Behaviors.Collection.of(model.chips, {
id: chip => chipId(model, chip),
disabled: chip => phaseOf(model, chipId(model, chip)) !== 'shown',
})
chipsByModel.set(model, items)
return items
}
const Navigates = ListNavigation.behavior(Nav, navArgs)(Filter)({
container: 'list',
item: 'chip',
items: itemsOf,
text: (model, index) => model.chips[index]?.label ?? '',
})
const Picking = Selection.behavior(Picks, pickArgs)(Filter)({
container: 'list',
item: 'chip',
items: itemsOf,
})
const Ids = Behaviors.Collection.behavior(Filter)({ item: 'chip', items: itemsOf })
export type Route = Behaviors.Keys.Route<Model, Message>
const toggles = Keys.route<Model, Message>('Toggle', {
on: [Keys.chord('Enter'), Keys.chord(' ')],
handle: ({ key, input, item }) =>
item?.id === undefined || (key === ' ' && input.nav.query !== '')
? Option.none()
: Option.some(Picks.wrapper.make(Selection.Message.Activated({ id: item.id }))),
})
const removes = Keys.route<Model, Message>('Remove', {
on: [Keys.chord('Delete'), Keys.chord('Backspace')],
handle: ({ item }) =>
item?.id === undefined ? Option.none() : Option.some(Message.Removed({ id: item.id })),
})
export const chipKeys = (routes: ReadonlyArray<Route> = []) =>
Keys.behavior(Filter)({ slot: 'chip', name: 'ChipKeys', routes: [toggles, removes, ...routes] })
export const chipView = (label: string) =>
Filter.define((model, slots, h) =>
h.div(slots.root.attrs(), [
h.ul(
slots.list.attrs([h.Role('listbox'), h.AriaLabel(label)]),
model.chips.map((chip, index) =>
h.li(
slots.chip.attrs([h.Key(chipId(model, chip)), h.Role('option')], {
index,
id: chipId(model, chip),
}),
[chip.label],
),
),
),
...(model.picks.selected.length === 0
? []
: [
h.button(slots.remove.attrs([h.Type('button'), h.OnClick(Message.RemovedPicked())]), [
'Remove picked',
]),
]),
]),
)SlotView.over(ChipSlots)binds slot names, input type, and Message type so misspelled slots fail at compile time.Behaviors.Collection.ofcomputes item IDs and disabled states once perModel(memoized viaWeakMap).- One
keydownowner viaKeys.behavior: Adding a duplicate chord inroutesthrowsmixins:key-conflict(or resolves explicitly withKeys.first). ReturningOption.none()preserves native key behavior and lets keys bubble to list navigation.
4. Focus recovery and exit animations
Attach Presence.behavior to apply inert and data-presence during exits, and FocusRecovery.behavior so focus moves to the next or previous chip when the focused chip leaves:
import { FocusRecovery } from 'foldkit-primitives/interaction'
const Leaves = Presence.behavior(Filter)({
content: 'chip',
phase: (model, item) => phaseOf(model, item?.id ?? ''),
})
const Recovers = FocusRecovery.behavior(Filter)({
owner: 'root',
parts: { chip: ['next', 'previous'], remove: ['stop'] },
})Presence.behavioraddsdata-presence="hiding"for CSS transitions andinerton exiting items so focus and clicks skip them.FocusRecovery.behaviorinstalls oneMountonrootthat moves focus alongpartswhen a focused element becomesinertor disappears, leaving focus alone if moved elsewhere.
For programmatic focus triggered by a Message (such as focusing a newly opened editor), issue a Focus Command from update (see examples/authoring). For overlays, use Overlay.nonModal or Dialog.focusReturn. Because FocusRecovery emits no Message, reusable widgets make it opt-in (like recoveryPart on Alert) or use a Command so Scene tests can settle cleanly.
5. Recipes, axes, states, and CSS layers
Define appearance with Style.recipeFor, placing base rules in components and axis choices in variants from Layers.standard:
import { Layers, Style, type StyleValue } from 'foldkit-mixins'
import { Theme } from 'foldkit-mixins/theme'
const t = Theme.ref(Theme.standard())
const base = (...pieces: ReadonlyArray<StyleValue>) =>
Layers.standard.in('components', Style.compose(...pieces))
const pick = (...pieces: ReadonlyArray<StyleValue>) =>
Layers.standard.in('variants', Style.compose(...pieces))
const picked = Style.states(
{
true: {
backgroundColor: t.accent.default,
borderColor: t.accent.default,
color: t.accent['on-fill'],
},
},
'aria-selected',
)
export const ChipRecipe = Style.recipeFor(ChipSlots)({
base: {
root: base(Style.self({ display: 'grid', gap: t.space.xs, justifyItems: 'start' })),
list: base(
Style.self({
display: 'flex',
flexWrap: 'wrap',
gap: t.space.xs,
margin: '0',
padding: '0',
listStyle: 'none',
}),
),
chip: base(
Style.self({
borderRadius: t.radius.full,
borderWidth: t.border.thin,
borderStyle: 'solid',
cursor: 'pointer',
userSelect: 'none',
transitionProperty: 'opacity',
transitionDuration: t.motion.fast,
}),
Style.pseudo(':focus-visible', {
outline: `${t.border.thick} solid ${t.outline.focus}`,
outlineOffset: '2px',
}),
Style.pseudo('[data-presence="hiding"]', { opacity: '0' }),
),
},
variants: {
size: {
sm: { chip: pick(Style.self({ paddingBlock: t.space['3xs'], paddingInline: t.space.xs })) },
md: { chip: pick(Style.self({ paddingBlock: t.space['2xs'], paddingInline: t.space.sm })) },
},
look: {
outline: {
chip: pick(
Style.self({
backgroundColor: 'transparent',
borderColor: t.outline.default,
color: t.text.default,
}),
picked,
),
},
soft: {
chip: pick(
Style.self({
backgroundColor: t.state.tint,
borderColor: 'transparent',
color: t.text.default,
}),
picked,
),
},
},
},
defaults: { size: 'md', look: 'outline' },
})
export const ChipStyle = Style.forSlots(ChipSlots)(ChipRecipe(), { name: 'ChipStyle' })
export const SoftSmallChips = Style.forSlots(ChipSlots)(ChipRecipe({ size: 'sm', look: 'soft' }), {
name: 'SoftSmallChips',
})Remember two cascade rules in Layers.standard (reset, tokens, theme, defaults, components, layouts, variants, utilities, app):
- Place state rules beside the variants that set the same properties:
pickedsetsbackgroundColor, whichlookvariants also set invariants. Placingpickedinvariantsalongside each look ensures it wins over the variant's default fill. - Extend rather than fork: Adjust a shipped look with
ChipRecipe.extend(...), and render the final page stylesheet withStyle.stylesheet(...)(seefoldkit-mixins). ReserveStyle.inlinefor dynamic values that must override theapplayer.
6. Accessibility patterns and obligations
Declare required roles, states, and interactions with A11y.pattern and verify with A11y.conform:
import { A11y, Behavior, type NamedStyle } from 'foldkit-mixins'
export const ChipPattern = A11y.pattern({
list: { capability: Capability.Container, obligations: [A11y.Navigation, A11y.Name] },
chip: {
capability: Capability.Focusable,
obligations: [A11y.FocusStrategy, A11y.Activation, A11y.State(Attr.AriaSelected)],
},
})
export interface ChipFilterOptions {
readonly label: string
readonly routes?: ReadonlyArray<Route>
readonly style?: NamedStyle<typeof ChipSlots>
}
export const chipFilter = (options: ChipFilterOptions) =>
chipView(options.label).pipe(
Behavior.attach(Navigates),
Behavior.attach(Picking),
Behavior.attach(chipKeys(options.routes)),
Behavior.attach(Ids),
Behavior.attach(Leaves),
Behavior.attach(Recovers),
SlotView.attach(A11y.base({ list: [A11y.Name] })),
Style.attach(options.style ?? ChipStyle),
A11y.conform(ChipPattern),
)
export const escapeClears = Keys.route<Model, Message>('ClearPicks', {
on: [Keys.chord('Escape')],
handle: ({ input }) =>
input.picks.selected.length === 0
? Option.none()
: Option.some(Picks.wrapper.make(Selection.Message.Cleared())),
})
export const FilterChips = chipFilter({ label: 'Filters', routes: [escapeClears] })Omitting Picking triggers both a compile-time type error naming 'chip/activation' | 'chip/state:aria-selected' and a runtime a11y:unsatisfied-obligation error. Because A11y.conform verifies structural declarations, verify live keyboard focus and accessibility-tree roles in a browser test next.
7. Testing update logic, types, browser focus, and SSR
Match each guarantee to the test environment that can observe it:
Pure update transitions and no-op identity:
import { expect, test } from 'vitest'
test('a removed chip leaves before it goes, and a stale Hidden keeps it', () => {
const start = initialOf('f', CHIPS).model
const leaving = update(start, Message.Removed({ id: 'f-mine' })).model
expect(leaving.presence['f-mine']?.phase).toBe('hiding')
const stale = update(leaving, GotPresence.make('f-mine', PresenceMessage.Hidden({ generation: 0 })))
expect(stale.model.chips).toHaveLength(2)
expect(update(start, Message.Removed({ id: 'elsewhere' })).model).toBe(start)
})Type-level contract checks (*.test-d.ts):
import { defineMessageUnion } from 'foldkit/message'
const Foreign = defineMessageUnion({ SentElsewhere: {} })
export const foreignRoute = chipFilter({
label: 'Filters',
routes: [
// @ts-expect-error a page route cannot send a Message the filter does not
Keys.route('Elsewhere', {
on: [Keys.chord('x')],
handle: () => Option.some(Foreign.SentElsewhere()),
}),
],
})Browser focus and keyboard conformance: Wait for pending animation frames (Frames.track().settle()) between rapid key presses so DOM state reflects the latest draw:
import { vi } from 'vitest'
import { Frames } from 'foldkit-mixins/testing'
test('Delete hands focus to the next chip at once', async () => {
const frames = Frames.track()
const container = document.createElement('div')
container.id = 'host'
document.body.append(container)
const filter = mountFilter(container, 'f')
await vi.waitFor(() => expect(document.getElementById('f-open')).not.toBeNull())
document.getElementById('f-open')!.focus()
await frames.settle()
await userEvent.keyboard('{Delete}')
await vi.waitFor(() => expect(document.activeElement?.id).toBe('f-mine'))
filter.dispose()
frames.dispose()
})Run Conformance.listbox in the same browser test to verify accessibility roles and keyboard behavior against Chromium's accessibility tree:
import { Conformance } from 'foldkit-mixins/testing'
test('the filter conforms to the listbox scenario', async () => {
const result = await Conformance.listbox(Conformance.harness({ cdp, userEvent }), {
name: 'Filters',
options: ['Open', 'Mine'],
orientation: 'horizontal',
enter: async () => document.getElementById('f-open')?.focus(),
})
expect(Conformance.failures(result)).toEqual([])
})Server-rendered markup: Render to HTML, parse with DOMParser, and assert Conformance.server passes before client scripts load:
import { Effect } from 'effect'
import { injectIntoTemplate, renderToString } from 'foldkit/experimental/server'
test('a served filter is a named listbox with its chips', async () => {
const served = await Effect.runPromise(
renderToString(
{
init: () => initialOf('f', CHIPS),
view: (model: Model, h: HtmlBuilder<Message>) => ({ title: 'Served', body: FilterChips(model, h) }),
},
{ buildId: 'b' },
),
)
const page = new DOMParser().parseFromString(
injectIntoTemplate('<!doctype html><html><head><title></title></head><body></body></html>', served),
'text/html',
)
const found = Conformance.server('listbox', page.body, [
{ role: 'listbox', name: 'Filters', attributes: { 'aria-multiselectable': 'true' } },
{ role: 'option', name: 'Open', attributes: { 'aria-selected': 'false', tabindex: '0' } },
])
expect(Conformance.failures(found)).toEqual([])
})