foldkit-mixins 0.25.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/README.md +572 -44
  2. package/dist/a11y.d.ts +127 -1
  3. package/dist/a11y.d.ts.map +1 -1
  4. package/dist/a11y.js +138 -9
  5. package/dist/a11y.js.map +1 -1
  6. package/dist/attr.d.ts +8 -0
  7. package/dist/attr.d.ts.map +1 -1
  8. package/dist/attr.js +19 -11
  9. package/dist/attr.js.map +1 -1
  10. package/dist/behavior.d.ts +40 -7
  11. package/dist/behavior.d.ts.map +1 -1
  12. package/dist/behavior.js +31 -7
  13. package/dist/behavior.js.map +1 -1
  14. package/dist/behaviors/collection.d.ts +3 -1
  15. package/dist/behaviors/collection.d.ts.map +1 -1
  16. package/dist/behaviors/collection.js +14 -16
  17. package/dist/behaviors/collection.js.map +1 -1
  18. package/dist/behaviors/disclosure.d.ts +6 -3
  19. package/dist/behaviors/disclosure.d.ts.map +1 -1
  20. package/dist/behaviors/disclosure.js +17 -10
  21. package/dist/behaviors/disclosure.js.map +1 -1
  22. package/dist/behaviors/field-association.d.ts +6 -3
  23. package/dist/behaviors/field-association.d.ts.map +1 -1
  24. package/dist/behaviors/field-association.js +28 -22
  25. package/dist/behaviors/field-association.js.map +1 -1
  26. package/dist/behaviors/id-selector.d.ts +7 -0
  27. package/dist/behaviors/id-selector.d.ts.map +1 -0
  28. package/dist/behaviors/id-selector.js +10 -0
  29. package/dist/behaviors/id-selector.js.map +1 -0
  30. package/dist/behaviors/index.d.ts +2 -1
  31. package/dist/behaviors/index.js +2 -1
  32. package/dist/behaviors/keys.d.ts +169 -0
  33. package/dist/behaviors/keys.d.ts.map +1 -0
  34. package/dist/behaviors/keys.js +347 -0
  35. package/dist/behaviors/keys.js.map +1 -0
  36. package/dist/behaviors/spin-value.d.ts +15 -3
  37. package/dist/behaviors/spin-value.d.ts.map +1 -1
  38. package/dist/behaviors/spin-value.js +46 -16
  39. package/dist/behaviors/spin-value.js.map +1 -1
  40. package/dist/behaviors/toggle-state.d.ts +7 -4
  41. package/dist/behaviors/toggle-state.d.ts.map +1 -1
  42. package/dist/behaviors/toggle-state.js +14 -7
  43. package/dist/behaviors/toggle-state.js.map +1 -1
  44. package/dist/conformance.d.ts +205 -0
  45. package/dist/conformance.d.ts.map +1 -0
  46. package/dist/conformance.js +582 -0
  47. package/dist/conformance.js.map +1 -0
  48. package/dist/conformed.d.ts +17 -0
  49. package/dist/conformed.d.ts.map +1 -0
  50. package/dist/conformed.js +21 -0
  51. package/dist/conformed.js.map +1 -0
  52. package/dist/defaults.d.ts.map +1 -1
  53. package/dist/defaults.js +1 -1
  54. package/dist/defaults.js.map +1 -1
  55. package/dist/describe.d.ts +91 -0
  56. package/dist/describe.d.ts.map +1 -0
  57. package/dist/describe.js +239 -0
  58. package/dist/describe.js.map +1 -0
  59. package/dist/diagnostics.d.ts +1 -1
  60. package/dist/diagnostics.d.ts.map +1 -1
  61. package/dist/diagnostics.js.map +1 -1
  62. package/dist/index.d.ts +12 -10
  63. package/dist/index.js +6 -5
  64. package/dist/layers.js +1 -1
  65. package/dist/mixin.d.ts +29 -1
  66. package/dist/mixin.d.ts.map +1 -1
  67. package/dist/mixin.js +11 -3
  68. package/dist/mixin.js.map +1 -1
  69. package/dist/pipe.d.ts +26 -1
  70. package/dist/pipe.d.ts.map +1 -1
  71. package/dist/pipe.js.map +1 -1
  72. package/dist/resolver.d.ts +8 -1
  73. package/dist/resolver.d.ts.map +1 -1
  74. package/dist/resolver.js +73 -27
  75. package/dist/resolver.js.map +1 -1
  76. package/dist/slotView.d.ts +83 -5
  77. package/dist/slotView.d.ts.map +1 -1
  78. package/dist/slotView.js +107 -20
  79. package/dist/slotView.js.map +1 -1
  80. package/dist/style.d.ts +36 -5
  81. package/dist/style.d.ts.map +1 -1
  82. package/dist/style.js +61 -12
  83. package/dist/style.js.map +1 -1
  84. package/dist/styleValue.d.ts.map +1 -1
  85. package/dist/styleValue.js +38 -1
  86. package/dist/styleValue.js.map +1 -1
  87. package/dist/testing.d.ts +4 -3
  88. package/dist/testing.d.ts.map +1 -1
  89. package/dist/testing.js +2 -1
  90. package/dist/testing.js.map +1 -1
  91. package/dist/theme/cssMath.d.ts +1 -1
  92. package/dist/theme/cssMath.js +1 -0
  93. package/dist/theme/cssMath.js.map +1 -1
  94. package/dist/theme/gamut.d.ts +19 -1
  95. package/dist/theme/gamut.d.ts.map +1 -1
  96. package/dist/theme/gamut.js +25 -3
  97. package/dist/theme/gamut.js.map +1 -1
  98. package/dist/theme/knob.d.ts +2 -0
  99. package/dist/theme/knob.d.ts.map +1 -1
  100. package/dist/theme/knob.js +1 -0
  101. package/dist/theme/knob.js.map +1 -1
  102. package/dist/theme/knobData.d.ts +1014 -0
  103. package/dist/theme/knobData.d.ts.map +1 -0
  104. package/dist/theme/knobData.js +583 -0
  105. package/dist/theme/knobData.js.map +1 -0
  106. package/dist/theme/knobDataType.d.ts +20 -0
  107. package/dist/theme/knobDataType.d.ts.map +1 -0
  108. package/dist/theme/knobDataType.js +1 -0
  109. package/dist/theme/knobs.d.ts +62 -62
  110. package/dist/theme/knobs.d.ts.map +1 -1
  111. package/dist/theme/knobs.js +61 -61
  112. package/dist/theme/knobs.js.map +1 -1
  113. package/dist/theme/oklch.d.ts +8 -0
  114. package/dist/theme/oklch.d.ts.map +1 -1
  115. package/dist/theme/oklch.js +20 -8
  116. package/dist/theme/oklch.js.map +1 -1
  117. package/dist/theme/raise.d.ts +2 -1
  118. package/dist/theme/raise.d.ts.map +1 -1
  119. package/dist/theme/raise.js +3 -2
  120. package/dist/theme/raise.js.map +1 -1
  121. package/dist/theme/runtime.d.ts +37 -0
  122. package/dist/theme/runtime.d.ts.map +1 -0
  123. package/dist/theme/runtime.js +54 -0
  124. package/dist/theme/runtime.js.map +1 -0
  125. package/dist/theme/scheme.d.ts +26 -1
  126. package/dist/theme/scheme.d.ts.map +1 -1
  127. package/dist/theme/scheme.js +31 -2
  128. package/dist/theme/scheme.js.map +1 -1
  129. package/dist/theme/shadows.d.ts +4 -1
  130. package/dist/theme/shadows.d.ts.map +1 -1
  131. package/dist/theme/shadows.js +8 -5
  132. package/dist/theme/shadows.js.map +1 -1
  133. package/dist/theme/storageChanges.d.ts +9 -0
  134. package/dist/theme/storageChanges.d.ts.map +1 -0
  135. package/dist/theme/storageChanges.js +29 -0
  136. package/dist/theme/storageChanges.js.map +1 -0
  137. package/dist/theme/themes.d.ts +3 -26
  138. package/dist/theme/themes.d.ts.map +1 -1
  139. package/dist/theme/themes.js +3 -32
  140. package/dist/theme/themes.js.map +1 -1
  141. package/dist/theme/tokens.d.ts +2 -0
  142. package/dist/theme/tokens.d.ts.map +1 -1
  143. package/dist/theme/tokens.js +4 -2
  144. package/dist/theme/tokens.js.map +1 -1
  145. package/dist/theme.d.ts +10 -7
  146. package/dist/theme.d.ts.map +1 -1
  147. package/dist/theme.js +7 -7
  148. package/dist/theme.js.map +1 -1
  149. package/dist/vite.d.ts +5 -3
  150. package/dist/vite.d.ts.map +1 -1
  151. package/dist/vite.js +2 -2
  152. package/dist/vite.js.map +1 -1
  153. package/dist/viteFreeze.d.ts +9 -12
  154. package/dist/viteFreeze.d.ts.map +1 -1
  155. package/dist/viteFreeze.js +94 -17
  156. package/dist/viteFreeze.js.map +1 -1
  157. package/package.json +15 -4
package/README.md CHANGED
@@ -15,19 +15,11 @@ component and edit its markup.
15
15
  The view keeps its markup, state and Messages. The caller gets a typed customization surface
16
16
  instead of an open-ended bag of props.
17
17
 
18
- ```text
19
- Without a slot contract With a slot contract
20
-
21
- Button Button
22
- ├─ className ├─ root slot
23
- ├─ iconClassName ├─ icon slot
24
- ├─ tooltip └─ label slot
25
- ├─ tracking
26
- ├─ ariaLabelOverride callers attach independently:
27
- ├─ onFocusDecoration ├─ BrandStyle
28
- └─ ... ├─ TooltipBehavior
29
- └─ AnalyticsBehavior
30
- ```
18
+ Without a slot contract, a Button grows a prop for every customization:
19
+ `className`, `iconClassName`, `tooltip`, `tracking`, `ariaLabelOverride`,
20
+ `onFocusDecoration`, and so on. With one, it names its parts (a `root`, an `icon`
21
+ and a `label` slot), and callers attach independently to them: a `BrandStyle`, a
22
+ `TooltipBehavior`, an `AnalyticsBehavior`.
31
23
 
32
24
  This is not a second component system and it is not a state library. A slot ultimately resolves
33
25
  to ordinary Foldkit attributes.
@@ -47,24 +39,37 @@ There are five ideas to learn:
47
39
  `Style` and `Behavior` both compile to a `Mixin`. The resolver combines their contributions and
48
40
  rejects ambiguous ownership instead of silently choosing a winner.
49
41
 
42
+ A Slots contract names the extension points. Style (appearance) and Behavior
43
+ (interaction) attach to them, each compiles to a Mixin, and the resolver turns the
44
+ Mixins into ordinary Foldkit attributes.
45
+
46
+ Styling has a pipeline of its own, read left to right, and each step is checked by the one before:
47
+
50
48
  ```text
51
- Slots contract
52
- │
53
- ┌───────────┴───────────┐
54
- Style Behavior
55
- appearance interaction
56
- │ │
57
- └───────────┬───────────┘
58
- ▼
59
- Mixin
60
- │
61
- ▼
62
- resolver
63
- │
64
- ▼
65
- ordinary Foldkit attributes
49
+ tokens -> ref -> pieces -> slots -> sheet
66
50
  ```
67
51
 
52
+ `Theme.tokens` are the only values; `Theme.ref` reads them by name; a Style piece is built from the
53
+ refs; `Style.forSlots` puts pieces on a Slot; `Style.stylesheet` collects the rules into the
54
+ layers a page installs. [Style](#style-appearance-as-data) and
55
+ [Themes](#themes-as-typed-knobs) cover it.
56
+
57
+ ### Where to look
58
+
59
+ | You want to | Read |
60
+ | --- | --- |
61
+ | Make a view customizable | [Quick start](#quick-start), [Slots](#slots-the-public-contract) |
62
+ | Restyle a view, or install a theme | [Style](#style-appearance-as-data), [Themes as typed knobs](#themes-as-typed-knobs) |
63
+ | Add behavior to an element | [Behavior](#behavior-reusable-element-level-interaction) |
64
+ | Let an application add a key to a widget | [Keys](#keys-one-owner-for-a-slots-keydown): the widget takes `routes`, and a clash is `mixins:key-conflict` |
65
+ | Declare and check who provides an accessibility obligation | [Obligations](#obligations-who-does-what-a-pattern-asks): `provides`, `A11y.base`, `A11y.native`, `A11y.delegated`, `A11y.conform` |
66
+ | Run the conformance scenarios over a widget | [Conformance](#conformance-the-rendered-check): `Conformance.listbox`, `.tree`, `.dialog`, `.tabs`, `.checkbox`, `.server` |
67
+ | See what a view's attachments do | [Describing a view](#describing-a-view-and-what-one-input-resolves-to): `SlotView.describe`, `SlotView.resolution` |
68
+ | Redraw only what changed | [Parts](#parts-redraw-only-what-changed), [Regions](#regions-redraw-by-the-model-paths-read) |
69
+ | Test a view, or render it with no runtime | [Testing and static output](#testing-and-static-output) |
70
+
71
+ To build a component of your own from Slots, primitives and a recipe, one concept at a time, follow [Authoring components](../../docs/authoring-components.md).
72
+
68
73
  ## Why not just `className` and props?
69
74
 
70
75
  A class name says only "append this string." A slot is a **typed public customization point**.
@@ -104,7 +109,8 @@ projection, and `foldkit-mixins-ui` adapts `@foldkit/ui` components.
104
109
 
105
110
  The design-system pieces are subpaths, so an application that only attaches classes pays for
106
111
  none of them: `foldkit-mixins/layers`, `/theme`, `/layout`, `/defaults`, `/prose`, `/utilities`
107
- and `/app`.
112
+ and `/app`. `foldkit-mixins/testing` holds `Conformance`, and `/foundations` the first-paint
113
+ rules.
108
114
 
109
115
  ## Quick start
110
116
 
@@ -214,11 +220,15 @@ Attachments are not concatenated and left to renderer order. The resolver applie
214
220
  `insetInlineEnd`), and `translate`, `rotate` or `scale` beside `transform`;
215
221
  - `Key`, `InnerHTML` and a `Prop` that replaces the children are structural and cannot be
216
222
  overridden;
217
- - multiple mount contributions compose into exactly one `OnMount`.
223
+ - multiple mount contributions compose into exactly one `OnMount`, a Mount inside a
224
+ `ChildAttribute` (a Submodel's) included; that one still sends through its own boundary.
218
225
 
219
226
  Conflicts throw `Diagnostics.DiagnosticError` with stable codes such as
220
227
  `mixins:event-conflict`, `mixins:style-property-conflict` and `mixins:protected-attribute`, so tests,
221
- DevTools and editor tooling can all speak the same diagnostic language. The style rule exists
228
+ DevTools and editor tooling can all speak the same diagnostic language. A conflict between two
229
+ owners (an event, an attribute, a style property, a Mount name) names both contributors in its
230
+ message and in `details.contributors`: each attachment by its name, and `the view` for the base
231
+ attributes the render passed. The style rule exists
222
232
  because a positioning Behavior that writes `top` and a Style that also sets `top` would otherwise
223
233
  fight silently, last writer winning.
224
234
  A theme refuses its values the same way: `Theme.make` with a value out of a knob's range throws
@@ -274,7 +284,10 @@ Slot.make({
274
284
  `Base → Collection`. A behavior that requires `Interactive` may attach to a `TextInput`.
275
285
  Extend it with `Capability.make(name, { extends })`.
276
286
  - **Event** and **Attr** are branded metadata tokens. `Event.make` and `Attr.make` add custom ones;
277
- declaring them does not install handlers.
287
+ declaring them does not install handlers. `Attr` ships `Role`, `AriaLabel`, `AriaDescribedby`,
288
+ `AriaExpanded`, `AriaSelected`, `AriaInvalid`, `AriaPressed`, `AriaChecked`, `AriaDisabled`,
289
+ `Disabled` and `Value`, and `AriaSort`, `AriaLabelledby`, `AriaControls`, `AriaReadonly`,
290
+ `AriaRequired`, `AriaCurrent` and `AriaValuenow`, for a slot to declare what it writes.
278
291
  - **Requirement** tokens name platform needs such as `Keyboard`, `Pointer` and `Clipboard` for
279
292
  tooling to inspect.
280
293
  - `hidden` reserves an internal extension point: public Style and Behavior specs do not even offer
@@ -311,7 +324,7 @@ one.
311
324
  | `Style.when(condition, piece)` | a boolean known at authoring time |
312
325
  | `Style.whenInput(predicate, piece)` | a condition read from the view input at render time |
313
326
  | `Style.recipe({ base, variants, defaults, compound })` | one slot: returns `selection => StyleValue`; every field is optional, so a recipe may be only its base |
314
- | `Style.recipeFor(Slots)({ base, variants, defaults, compound })` | every slot: returns `selection => RecipePieces`, in which every `base` slot is present and a variant's slot may be absent; `null` unsets a defaulted axis, which is how a recipe makes a piece optional; `.extend(patch)` composes per slot, removes nothing, and refuses a slot the contract lacks |
327
+ | `Style.recipeFor(Slots)({ base, variants, defaults, compound })` | every slot: returns `selection => RecipePieces`, in which every `base` slot is present and a variant's slot may be absent; `null` unsets a defaulted axis, which is how a recipe makes a piece optional; `.extend(patch)` composes per slot, removes nothing, and refuses a slot the contract lacks; `.add(more)` gives it an axis or a value it lacks ([A look a shipped recipe lacks](#a-look-a-shipped-recipe-lacks)); `.style(selection?, options?)` is `Style.forSlots(Slots)(recipe(selection), options)` in one call, the `NamedStyle` a view's `style` takes |
315
328
  | `Style.perItem(item => piece)` / `Style.stagger({ stepMs })` | a piece from the item the slot is rendered for (`attrs(base, item)`); stagger writes `--fk-index` inline and the `calc` delay as a rule |
316
329
  | `Style.forCapability(Slots)(capability, piece)` | one piece for every public slot whose capability satisfies it |
317
330
  | `Style.slots(pieces, options?)` / `Style.slot(slotOptions, piece)` | an application's own Slots declared by their style: `{ slots, style }` (see [An application's own look](#an-applications-own-look)) |
@@ -370,6 +383,18 @@ round) is refused when the style is defined, with
370
383
  it, so clearing `borderColor` also cleared the color `border` set, and the
371
384
  element kept a `currentColor` border after the state ended.
372
385
 
386
+ An inline declaration beats every rule, layers included, so a conditional rule for the same
387
+ property in the same composition never applies: `Style.compose(Style.inline({ padding: '1.75rem' }),
388
+ Style.media('(max-width: 30rem)', { padding: '1rem' }))` is refused when composed, with
389
+ `mixins:dead-conditional-rule` naming the property, the condition and the fix, which is to put the
390
+ base in `Style.self`. It is a development-time check, like `mixins:inline-shorthand-conflict`
391
+ beside it: Vite folds `import.meta.env.DEV` away in a production build, so neither check nor its
392
+ text reaches a page (a build without Vite's `import.meta.env` skips them too). A media, pseudo, nest, container, supports or `states` rule, and a rule inside
393
+ `whenInput`, counts, as does a shorthand against its longhand (`padding` and `paddingInline`, either
394
+ way round); a rule marked `!important` beats inline and passes. An inline declaration that exists
395
+ only when the view chooses it or per item is not known when the style is defined, and two Styles
396
+ attached to one slot meet only as classes and inline text, so neither is checked.
397
+
373
398
  Beyond `self`, `pseudo`, `media`, `supports`, `container` and `nest`, the rule pieces are:
374
399
 
375
400
  - `Style.states({ open: { opacity: '1' } })` compiles to `&[data-state="open"]`, for Behaviors that
@@ -393,6 +418,62 @@ Beyond `self`, `pseudo`, `media`, `supports`, `container` and `nest`, the rule p
393
418
  scoped to the class (`:is(a, b)` is not split), and a selector that writes `&` places the class
394
419
  itself (`nest('[data-open] &')`).
395
420
 
421
+ ### A look a shipped recipe lacks
422
+
423
+ A recipe from a design system has the axes and values its author chose. An application changes
424
+ it in two ways, and neither forks it:
425
+
426
+ - `.extend(patch)` adjusts what the recipe **has**: more pieces on its base or on one of its
427
+ values, another default, another compound. An axis or a value the recipe lacks is a type
428
+ error there, so a misspelt axis cannot become a new one.
429
+ - `.add(more)` gives it what it **lacks**: a value on an axis it has, or a new axis. A value
430
+ the axis already has is refused, in the type and with `mixins:recipe-value-exists`.
431
+
432
+ Both return a recipe, so `.extend`, `.add`, `.style` and a `null` selection work on the
433
+ result, and neither changes the recipe it was called on.
434
+
435
+ ```ts standalone
436
+ import { Capability, Slot, Slots, Style } from 'foldkit-mixins'
437
+
438
+ const ButtonSlots = Slots.define({
439
+ button: Slot.make({ capability: Capability.Interactive }),
440
+ })
441
+
442
+ // What a design system ships.
443
+ const Button = Style.recipeFor(ButtonSlots)({
444
+ base: { button: Style.self({ borderRadius: '6px' }) },
445
+ variants: {
446
+ tone: {
447
+ accent: { button: Style.self({ background: 'royalblue', color: 'white' }) },
448
+ neutral: { button: Style.self({ background: 'gainsboro' }) },
449
+ },
450
+ },
451
+ defaults: { tone: 'accent' },
452
+ })
453
+
454
+ // What an application adds: a tone the recipe has no word for, and a new axis.
455
+ const AppButton = Button.add({
456
+ tone: { brand: { button: Style.self({ background: 'rebeccapurple', color: 'white' }) } },
457
+ width: { full: { button: Style.self({ inlineSize: '100%' }) } },
458
+ })
459
+
460
+ // `.style` selects and makes the view's Style in one call; `.style()` is the defaults.
461
+ export const Brand = AppButton.style({ tone: 'brand', width: 'full' })
462
+ export const Accent = AppButton.style()
463
+ // The same in two calls, for when the pieces are composed first.
464
+ export const Spelled = Style.forSlots(ButtonSlots)(AppButton({ tone: 'brand', width: 'full' }))
465
+
466
+ // @ts-expect-error `accent` is the recipe's own: adjust it with `extend`.
467
+ Button.add({ tone: { accent: { button: Style.self({ background: 'navy' }) } } })
468
+ // @ts-expect-error `extend` adds no axis.
469
+ Button.extend({ variants: { width: { full: { button: Style.self({ inlineSize: '100%' }) } } } })
470
+ ```
471
+
472
+ An added axis has no default: `AppButton()` above is the recipe as shipped. Give it one with
473
+ `AppButton.extend({ defaults: { width: 'full' } })`. The values are style pieces like any
474
+ recipe's, so a module that calls `add` is still one the build can
475
+ [ship as data](#style-modules-shipped-as-data).
476
+
396
477
  ### Themes as typed knobs
397
478
 
398
479
  `foldkit-mixins/theme` extends the root `Theme` with the pieces a page ships. A theme is a typed
@@ -494,14 +575,114 @@ is declared, so knobs set below the root change nothing derived from them there:
494
575
  `tokens` an application's own groups beside the shipped ones. The design is in
495
576
  `docs/theme-knobs.md`.
496
577
 
578
+ ### Following another tab
579
+
580
+ `Themes.choose` and `Theme.chooseScheme` write this tab's `localStorage`, and another tab hears
581
+ that as a `storage` event. `themeChanges(themes)` and `schemeChanges()` are Streams of
582
+ what another tab chose, decoded as the head scripts decode it: a name no theme has, a removed key
583
+ and anything else read as the initial theme or `'system'`. The writing tab hears nothing. They are
584
+ named exports, not members of `Themes` or `Theme`, so a page that reads neither ships no storage
585
+ listener. They
586
+ apply nothing, because the Model owns the choice: map each to a Message, and let `update` store
587
+ it and answer with the Command that shows it.
588
+
589
+ ```ts
590
+ import { Schema, Stream } from 'effect'
591
+ import { defineMessageUnion } from 'foldkit/message'
592
+ import * as Subscription from 'foldkit/subscription'
593
+ import { schemeChanges, themeChanges, Themes } from 'foldkit-mixins/theme'
594
+
595
+ const Followed = defineMessageUnion({
596
+ ThemeFollowed: { name: themes.Name },
597
+ SchemeFollowed: { scheme: Schema.Literals(['system', 'light', 'dark']) },
598
+ })
599
+ type Shown = { readonly theme: typeof themes.Name.Type }
600
+
601
+ export const followed = Subscription.make<Shown, typeof Followed.Type>()(() => ({
602
+ theme: Subscription.persistentEntry(
603
+ themeChanges(themes).pipe(Stream.map(name => Followed.ThemeFollowed({ name }))),
604
+ ),
605
+ scheme: Subscription.persistentEntry(
606
+ schemeChanges().pipe(Stream.map(scheme => Followed.SchemeFollowed({ scheme }))),
607
+ ),
608
+ }))
609
+ ```
610
+
611
+ On `ThemeFollowed`, `update` sets the Model's field and returns `Themes.apply(themes, name)`; on
612
+ `SchemeFollowed` it returns `Theme.chooseScheme(scheme)`. Kept knobs have no stream:
613
+ `Theme.chooseKnobs` stores CSS variable declarations, which do not map back to a theme's knobs.
614
+
615
+ ### Switching themes in a page with no style compiler
616
+
617
+ `Themes.make` compiles the themes, so a page built with `foldkit-mixins/vite`'s `modules`, which
618
+ ships no style compiler, cannot import it. The functions that only show, keep and hear a theme
619
+ need no compiled theme: `foldkit-mixins/theme/runtime` exports them (the same functions as
620
+ `Themes.apply`, `Themes.choose`, `Themes.script` and `themeChanges`) over `ThemeNames`, the
621
+ names, the initial name and the root attribute, which a compiled `Themes` already is. A page
622
+ without the compiler declares its own, typed by a type-only import of the compiled set so the
623
+ names cannot drift in type. `foldkit-mixins/theme/knob-data` holds each range knob of
624
+ `Knobs.standard` as plain data, one named export per knob (`shapeDensity` is `{ name: 'shape.density',
625
+ title, variable, unit, min, max, step, default }`; a knob with a light and a dark value is two,
626
+ `accentChromaLight` and `accentChromaDark`), for a panel's sliders. A page keeps only the knobs it
627
+ imports; `knobData`, the same entries by name (`knobData['shape.density']`), is for a panel that
628
+ draws every knob. The file is generated from `Knobs.standard` by
629
+ `pnpm --filter foldkit-mixins generate:knob-data`, and a test fails when it differs.
630
+
631
+ ```ts standalone
632
+ import { Effect, Stream } from 'effect'
633
+ import { shapeDensity } from 'foldkit-mixins/theme/knob-data'
634
+ import {
635
+ applyTheme,
636
+ chooseTheme,
637
+ themeChanges,
638
+ themeScript,
639
+ type ThemeNames,
640
+ } from 'foldkit-mixins/theme/runtime'
641
+
642
+ type Look = 'cobalt' | 'cobaltDense'
643
+ const looks: ThemeNames<Look> = {
644
+ names: ['cobalt', 'cobaltDense'],
645
+ initial: 'cobalt',
646
+ attribute: 'data-theme',
647
+ }
648
+
649
+ // A Command's effects: the Model's field owns the chosen name, these only show it.
650
+ export const show = (name: Look): Effect.Effect<void> => applyTheme(looks, name)
651
+ export const keep = (name: Look): Effect.Effect<void> => chooseTheme(looks, name)
652
+ // A Subscription's stream: another tab's choice, for `update` to store and answer with `show`.
653
+ export const followed: Stream.Stream<Look> = themeChanges(looks)
654
+ // The text of the head `<script>`, which shows the kept theme before the first paint.
655
+ export const head: string = themeScript(looks)
656
+ export const density = shapeDensity
657
+ ```
658
+
659
+ A name that is not one of `names` is a type error at a call. One read from storage, which nothing
660
+ validated, never reaches a call: the head script leaves the initial theme, and `themeChanges`
661
+ emits the initial theme, exactly as for a compiled set. Neither entry imports style code, so
662
+ `modules` accepts a page that imports only these.
663
+
664
+ ### The server's first render of the scheme
665
+
666
+ A server that builds the Model per request reads the browser's hint with
667
+ `schemeOfHint(request.headers.get('sec-ch-prefers-color-scheme'))`, which is
668
+ `Option.some('light' | 'dark')` or `Option.none()`. A browser sends the hint only after a
669
+ response asks for it, so send `COLOR_SCHEME_HINT_HEADERS` on pages: `Accept-CH` opts in,
670
+ `Critical-CH` has the browser retry the first request with the hint, and `Vary` keeps a cache
671
+ from serving one scheme's page to the other. Both are exported from `foldkit-mixins/theme`.
672
+
497
673
  ### What the palette derives
498
674
 
499
675
  `Theme.standard(theme)` holds typed tokens for surfaces, text, outlines, and the accent, secondary,
500
676
  tertiary and feedback families, derived from the theme's knobs. Only the `knob` group holds literals; every other value is a CSS
501
677
  expression over other tokens (`oklch(from …)`, `color-mix()`, `light-dark()`), so the browser does
502
- the derivation and one knob override recolors everything below it. Each family (`accent`,
678
+ the derivation and one knob override recolors everything below it. A derived color takes its hue
679
+ from the palette's hue tokens (`hue.neutral`, `hue.accent`), never from the color it starts from,
680
+ and the palette mixes in OKLab: a grey's hue is powerless, engines read it differently (Chromium
681
+ keeps the hue a grey was written with, others read 0, a red), and an OKLCH mix or added chroma
682
+ carries it into the result. Mix tokens of your own the same way, `color-mix(in oklab, …)`. Each family (`accent`,
503
683
  `secondary`, `tertiary`, `success`, `warning`, `error`, `info`) is one shape: a fill, `default`,
504
- lighter in a dark scheme; `hover` and `active`; `subtle`, a tint of it on the base; `outline`, a
684
+ lighter in a dark scheme; `hover` and `active` (darker, and `active` more vivid by 0.05 of chroma, at most
685
+ twice its own, so a grey fill stays grey when pressed); `subtle`, a tint of it on the base; `outline`, a
505
686
  line in it that stands off the base; and two text colors named for where they go: `on-fill` is
506
687
  text on that fill (near white on a mid accent), and `ink` is text in the family's color on the
507
688
  base surface, dark enough to read in a light scheme and light enough in a dark one. Colored text
@@ -527,8 +708,18 @@ the surface knobs. Each hue is a knob (`red-h`), and `scale-c` scales every step
527
708
  (`--fk-blue-wash-2`, `ref.blue['6']`). The `popup` group is a menu's
528
709
  panel (`surface`, `ink`, `blur`) and its lit row (`highlight`, `press`, `highlight-ink`):
529
710
  `menu.highlight: 'bold'` lights the row in the accent's fill, and `menu.panel` draws the panel
530
- `inverted` (the other scheme's surface and text) or `translucent` over a blur, as shadcn's menu
531
- options do.
711
+ as the page's own raised surface (`default`), `inverted` (the other scheme's surface and text) or
712
+ `translucent` over a blur, as shadcn's menu options do. The `selection` group is selected text,
713
+ which `Defaults.body` paints with `:where(*)::selection`: `background` is the accent over whatever
714
+ the text sits on (28% in a light scheme, 40% in a dark one, so the text stays at AA), `ink` is
715
+ `currentColor` so a link or a syntax token keeps its colour, and `fill-background` is the deeper
716
+ accent for text on the accent's own fill, where the tint would be the fill: such a surface sets
717
+ `--fk-selection-background` to it beside its fill. Override like any token,
718
+ `Theme.compose(theme, { selection: { background: 'rebeccapurple' } })`; an application's own
719
+ `::selection` rule wins. A lit row takes its ink from the surface
720
+ it is on: a popup panel sets `--_fk-row-highlight`, `--_fk-row-press` and
721
+ `--_fk-row-highlight-ink` on itself, and a row outside one (an inline Command) reads the `plain-*`
722
+ tokens, the text's own films or the accent.
532
723
  Each is a 0-or-1 knob (`popup-bold`, `popup-invert`) blended by `color-mix`, so an override
533
724
  switches it live. The `state` group is what a state lays over the surface under it, a mix of the
534
725
  element's own text color (`hover`, and `press` at 1.75 of it; `tint` and `tint-hover`, a
@@ -555,7 +746,8 @@ each level is an even step lighter.
555
746
  non-color scales, with `space` and `radius` multiplied by the `density` and `radius-factor` knobs.
556
747
  Its `motion` group is three tiers, `fast`, `moderate` and `slow` (80, 160 and 240ms, for hover and
557
748
  fades, popups and tabs, dialogs), each with a quicker `-exit` for dismissals, all multiplied by the
558
- `motion` knob. A duration of something that moves or resizes also multiplies by `knob.travel`,
749
+ `motion` knob. `sheet` and `sheet-exit` time a Sheet's slide: they read the `slow` tier until a theme
750
+ sets them. A duration of something that moves or resizes also multiplies by `knob.travel`,
559
751
  which `Defaults.reset` sets to 0 under `prefers-reduced-motion`: the thing stops travelling, and its
560
752
  fade still plays.
561
753
 
@@ -723,6 +915,7 @@ that case the contract, the style and the setup can each be written once:
723
915
  | You are... | Use |
724
916
  | --- | --- |
725
917
  | styling a contract someone published | `Style.forSlots(ButtonSlots)(pieces, options)` |
918
+ | taking a published recipe's look as it ships | `Recipes.Button.style(selection, options)` |
726
919
  | declaring your own Slots and their look | `Style.slots(pieces, options)` |
727
920
  | fixing theme, `app` layer and page sheet for one application | `AppStyle.make` from `foldkit-mixins/app` |
728
921
  | writing a token-backed declaration in a word | `Utilities` from `foldkit-mixins/utilities` |
@@ -757,7 +950,10 @@ Style.install(stylesheet)
757
950
  ```
758
951
 
759
952
  A published contract takes the same layer through the kit's `forSlots`, as
760
- `forSlots(ButtonSlots)(Recipes.Button())` with `foldkit-mixins-ui`.
953
+ `forSlots(ButtonSlots)(Recipes.Button())` with `foldkit-mixins-ui`, and a recipe's `.style`
954
+ takes it as an option: `Recipes.Button.style({}, { layer: L.layer('app') })`, with `L` from
955
+ `AppStyle.make`. The shipped pieces keep their `components` and `variants` layers either way;
956
+ the layer places what the application's own `.extend` added with none.
761
957
 
762
958
  What each call does, and does not do:
763
959
 
@@ -948,6 +1144,63 @@ the view's input; none owns anything.
948
1144
  press-and-hold repeat and the wheel are not handled: Foldkit's wheel
949
1145
  attribute carries no delta, and a repeat is a timer the Model would own.
950
1146
 
1147
+ ### Keys: one owner for a slot's `keydown`
1148
+
1149
+ The resolver allows one owner of an event on a slot, so a widget's own keys and the keys an
1150
+ application wants to add cannot be two Behaviors on `keydown`. `Behaviors.Keys` is the one owner:
1151
+ a widget's keys are named **routes**, and `Keys.behavior` folds the routes it is given into the
1152
+ slot's single handler. A route says which presses it takes (`Keys.chord('Escape')`,
1153
+ `Keys.printable`, or a `Keys.where` predicate) and what a press means: a Message, or `Keys.focus(id,
1154
+ message)` to also move focus to the element with that id. A route that returns `Option.none()`
1155
+ declines, and the press goes on to the page.
1156
+
1157
+ <!-- docs-check
1158
+ import { Option } from 'effect'
1159
+ -->
1160
+
1161
+ ```ts
1162
+ const SearchSlots = Slots.define({
1163
+ root: Slot.make({ capability: Capability.Container }),
1164
+ input: Slot.make({ capability: Capability.TextInput, events: [Event.Input, Event.KeyDown] }),
1165
+ })
1166
+ type SearchInput = { readonly query: string }
1167
+ const { Keys } = Behaviors
1168
+
1169
+ const clearOnEscape = Keys.route<SearchInput, Message>('ClearOnEscape', {
1170
+ on: [Keys.chord('Escape')],
1171
+ // With nothing to clear the route declines, so Escape reaches the dialog around the field.
1172
+ handle: ({ input }) =>
1173
+ input.query === '' ? Option.none() : Option.some(Message.ChangedValue({ value: '' })),
1174
+ })
1175
+
1176
+ // A widget takes the application's routes beside its own: this is how foldkit-mixins-ui's
1177
+ // Command, SearchField, Tabs, Menubar and others take their `routes` option.
1178
+ const searchKeys = (routes: ReadonlyArray<Behaviors.Keys.Route<SearchInput, Message>> = []) =>
1179
+ Keys.behavior(SearchSlots)<SearchInput, Message>({
1180
+ slot: 'input',
1181
+ routes: [clearOnEscape, ...routes],
1182
+ })
1183
+
1184
+ // The application adds a key without touching the widget:
1185
+ const Submits = searchKeys([
1186
+ Keys.route('Submit', {
1187
+ on: [Keys.chord('Enter')],
1188
+ handle: ({ input }) => Option.some(Message.ChangedValue({ value: input.query.trim() })),
1189
+ }),
1190
+ ])
1191
+ ```
1192
+
1193
+ Two routes that declare the same chord throw `mixins:key-conflict` when the Behavior is defined,
1194
+ naming both, because nothing chains at run time and one press sends at most one Message. Where one
1195
+ must win, `Keys.first(a, b)` asks `a` and falls to `b` only if `a` declines. To see a clash without drawing and catching, `Keys.conflict(routes, Option.some('input'))` returns the same diagnostic as an `Option` (`Option.none()` when no two routes declare one press), and takes the slot name only to say it in the message. A chord matches the
1196
+ `key` a press reports, so Shift+a is `Keys.chord('A')`; a name that is neither one character nor a
1197
+ named key (`'Esc'`) throws `mixins:unknown-key` and says what was meant. A handled press is
1198
+ default-prevented, an unhandled one untouched, a key of an IME composition reaches no route, and a
1199
+ held key runs its route on every repeat. A Behavior that writes other attributes on the same slot
1200
+ (a roving tab stop) installs its keys with `Keys.attribute(routes, { slot })` inside its own
1201
+ `attributes`, which is how the primitives expose theirs (`ListNavigation.keys`, `SwipeActions.keys`,
1202
+ `Move.nudge`). A key the application only watches, without owning, is a Subscription
1203
+ (`keyboardEvents` in `foldkit-primitives/events`), not a route.
951
1204
 
952
1205
  ## SlotView
953
1206
 
@@ -963,6 +1216,85 @@ infers it from an explicit `h: HtmlBuilder<Message>` annotation. Without one, `M
963
1216
  `Behavior.attach` uses the behavior's `Input` as the attached view's `Input`, so declare a
964
1217
  behavior over the view's input type, not merely the subset of fields it happens to read.
965
1218
 
1219
+ ### Naming the slots, input and Messages once: `SlotView.over`
1220
+
1221
+ A Behavior is made before the view it meets, so `Behavior.forSlots(S)<Input, Message>` names
1222
+ both types again for every Behavior. `SlotView.over(S)<Input, Message>()` names them once and
1223
+ hands back `define`, `behavior` and `parts` with all three fixed, so nothing passed to them is
1224
+ annotated:
1225
+
1226
+ ```ts
1227
+ const Fields = SlotView.over(FieldSlots)<FieldInput, Message>()
1228
+
1229
+ const Validates = Fields.behavior(
1230
+ { input: { attributes: ({ input, h }) => [h.AriaInvalid(input.invalid)] } },
1231
+ { name: 'Validates' },
1232
+ )
1233
+ const BoundField = Fields.define((input, slots, h) =>
1234
+ h.label(slots.root.attrs(), [
1235
+ h.input(
1236
+ slots.input.attrs([
1237
+ h.Value(input.value),
1238
+ h.OnInput(value => Message.ChangedValue({ value })),
1239
+ ]),
1240
+ ),
1241
+ ]),
1242
+ ).pipe(Behavior.attach(Validates))
1243
+ ```
1244
+
1245
+ `Fields.define` is `SlotView.define`, `Fields.behavior` is `Behavior.forSlots` and
1246
+ `Fields.parts` is `SlotView.parts`: the binder makes no new kind of value and holds no state. A
1247
+ Behavior from a binder over another Message universe is still refused at `Behavior.attach`.
1248
+ `foldkit-mixins-surface`'s `SurfaceView.over(surface, slots)` is the same binder with both types
1249
+ read from the Surface. A factory that takes slots can take a binder in their place, telling the
1250
+ two apart with `SlotView.isBound`.
1251
+
1252
+ ### What a view remembers of its attachments
1253
+
1254
+ Each attachment keeps its name, and a Style or Behavior also its `meta`: its kind and, per slot,
1255
+ what it requires, what it supplies (its `provides`, see [Obligations](#obligations-who-does-what-a-pattern-asks))
1256
+ and whether it reads the input. A Mixin made with `Mixin.make` or
1257
+ `Mixin.dynamic` carries none; `Mixin.compose` records its parts in order. A name addresses an
1258
+ attachment:
1259
+
1260
+ ```ts
1261
+ const Unchecked = BoundField.pipe(SlotView.detach('Validates'))
1262
+ const Checked = Unchecked.pipe(Behavior.attach(Validates))
1263
+ const Swapped = Checked.pipe(SlotView.replace('Validates', Validates.mixin))
1264
+ ```
1265
+
1266
+ `detach` and `replace` return a new view, `replace` keeping the attachment's place in the
1267
+ resolution order. Each throws `mixins:unknown-attachment` for a name the view does not hold and
1268
+ `mixins:ambiguous-attachment` for one it holds twice, so name a Behavior you mean to address
1269
+ (an unnamed one is called `Behavior`).
1270
+
1271
+ ### Describing a view, and what one input resolves to
1272
+
1273
+ `SlotView.describe(view)` is the view as data: its slots, and each attachment in order with, per
1274
+ slot, what it requires, what it supplies and the classes and Mounts it contributes. It needs no
1275
+ input and calls no contribution; one that is a function of the input reads `'unknown'`. It
1276
+ reads the view value, so a view you attach to or detach from has a description of its own and
1277
+ the first one's does not change. A `JSON.parse(JSON.stringify(description))` equals it, and
1278
+ `SlotView.toMarkdown(description)` prints it.
1279
+
1280
+ ```ts
1281
+ const description = SlotView.describe(Checked)
1282
+ // description.attachments[0]: { order, name, kind, slots: { input: { requires, provides, contributes } } }
1283
+ const markdown = SlotView.toMarkdown(description)
1284
+ ```
1285
+
1286
+ `SlotView.resolution(view, input)` evaluates every contribution for one input and reports, per
1287
+ slot, the class tokens, style property names, attribute names, event names and Mount names, each
1288
+ with the attachment that gave it. It reports no attribute value, style value or Mount args, since
1289
+ any of them may be the input's (a password in `Value`); class tokens are reported as given, so a
1290
+ class built from input text surfaces it. It builds handlers with the inert builder
1291
+ and calls none, runs no Mount, and returns a conflict as a finding where `resolve` would throw.
1292
+ It does not draw the view, so a clash with the view's own base attributes is not reported.
1293
+ Attribute and event names are as the resolver compares them (lower case, no hyphens).
1294
+
1295
+ `findings` also warn (`severity: 'warning'`) of an unnamed attachment and of two with one name,
1296
+ which `detach` and `replace` cannot address.
1297
+
966
1298
  For per-item groups such as tabs, options or calendar cells, use
967
1299
  `SlotView.buildersFor(slots, mixins, { input, h })` and map the items yourself. One contribution
968
1300
  then applies to every item while each item's base attributes retain their own event ownership.
@@ -994,7 +1326,10 @@ is not redrawn for. `Panel` is an ordinary SlotView: Styles and Behaviors attach
994
1326
  to it and reach every part's Slots.
995
1327
 
996
1328
  - **A part's own Behaviors** go in its `behaviors` option, declared over the
997
- part's selection (`Pick<Input, 'count'>`), and are resolved against it.
1329
+ part's selection (`Pick<Input, 'count'>`), and are resolved against it. A part
1330
+ is found only by drawing it, so `A11y.conform` reads none of its Behaviors'
1331
+ obligations, at the type level or at run time: attach a Behavior that must
1332
+ count to the assembly, and the finding says so when it is put on a part.
998
1333
  - **A Mixin attached to the whole view that reads the input** (a Behavior's
999
1334
  `attributes`, `Style.whenInput`) is resolved against the whole input, so the
1000
1335
  parts it reaches are drawn again on every change: correct, not cached. Static
@@ -1120,11 +1455,196 @@ A11y.validate(DialogPattern, DialogSlots)
1120
1455
  slots, capability mismatches and unpublished events or attributes. An optional requirement
1121
1456
  tolerates an absent slot but still checks a present one. It does **not** certify WCAG compliance.
1122
1457
 
1458
+ Three words stay apart here. A slot contract or a `provides` is **declared**: the author says so.
1459
+ `A11y.validate`, `A11y.check` and `A11y.conform` are **structural**: they say the declarations fit
1460
+ together. Only a browser test is **rendered**: it says the behaviour happened on a page. None of
1461
+ them is WCAG conformance.
1462
+
1463
+ ### Conformance: the rendered check
1464
+
1465
+ `Conformance` from `foldkit-mixins/testing` is the rendered word. Each scenario takes a harness
1466
+ and returns its findings as plain data, so a widget and a view assembled from primitives are held
1467
+ to one behaviour. `Conformance.harness({ cdp, userEvent })` is the harness for Vitest's browser
1468
+ mode: keys from `userEvent.keyboard`, roles and names from Chromium's own accessibility tree
1469
+ (which Vitest's locators do not match), read inside its root (the document by default) with each
1470
+ node's DOM element, and a pointer press as dispatched events. It takes the two from you, so
1471
+ `foldkit-mixins` imports no test runner. `cdp` is the Playwright provider's, so a test file
1472
+ names it first (`/// <reference types="@vitest/browser-playwright" />`, which types the session):
1473
+
1474
+ <!-- docs-check
1475
+ declare const cdp: Conformance.BrowserTools['cdp']
1476
+ declare const userEvent: Conformance.BrowserTools['userEvent']
1477
+ -->
1478
+
1479
+ ```ts
1480
+ import { Conformance } from 'foldkit-mixins/testing'
1481
+ // import { cdp, userEvent } from 'vitest/browser'
1482
+
1483
+ declare const button: HTMLElement
1484
+
1485
+ const harness = Conformance.harness({ cdp, userEvent })
1486
+ const result = await Conformance.listbox(harness, {
1487
+ name: 'Frequency',
1488
+ options: ['Hourly', 'Daily', 'Weekly'],
1489
+ disabled: 'Daily',
1490
+ orientation: 'horizontal',
1491
+ direction: 'rtl',
1492
+ enter: async () => button.focus(), // gives the keyboard to the widget, options drawn
1493
+ })
1494
+ console.log(Conformance.failures(result)) // []
1495
+ ```
1496
+
1497
+ `Conformance.listbox`, `.checkbox`, `.tree`, `.dialog` (focus in, Tab contained, Escape, focus
1498
+ restored, a second dialog opened over the first) and `.tabs` read what the page did: roles and
1499
+ names from the accessibility tree, `aria-selected`, `aria-checked` and `aria-expanded` from the
1500
+ page, focus from `document`. They read no Model, Slot or obligation. `Conformance.server(scenario,
1501
+ root, expected)` is the server half: parse a rendered string and it checks each expected role,
1502
+ name and attribute. Another runner gives a `Conformance.Harness` of its own (`{ root, press,
1503
+ accessibility, click }`). `SlotView.describe(view).conforms` lists the patterns a view was conformed to.
1504
+
1505
+ ### Obligations: who does what a pattern asks
1506
+
1507
+ A contract that publishes `keydown` on a list does not navigate it, and one that publishes
1508
+ `aria-selected` does not write it. A pattern's slot can also name **obligations**: things an
1509
+ attachment must say it does on that slot.
1510
+
1511
+ | Obligation | Means | Supplied by |
1512
+ | --- | --- | --- |
1513
+ | `A11y.Navigation` | arrows, Home and End move among the items | `ListNavigation`, `RovingTabindex`, `TreeNavigation`, `GridNavigation`, `SpatialNavigation` (container slot) |
1514
+ | `A11y.FocusStrategy` | each item is reachable: a roving stop, `aria-activedescendant`, or a native control | the same five (item slot); `A11y.native` |
1515
+ | `A11y.Activation` | Enter, Space or a press activates it | `Selection` (unless `click: false`), `Press`; `A11y.native` |
1516
+ | `A11y.State(attr)` | the attribute is written with a value on every draw | `Selection` (`aria-selected`), `Behaviors.ToggleState` (`aria-checked` or `aria-pressed`), `Behaviors.Disclosure` (`aria-expanded`) |
1517
+ | `A11y.Name` | the element has an accessible name | `Behaviors.FieldAssociation`; the view's own label, as `A11y.base` |
1518
+
1519
+ Something supplies an obligation in one of four ways: a Behavior slot's `provides`
1520
+ (`Behavior.slot({ provides: [A11y.Navigation], ... })`, as the primitives above declare theirs);
1521
+ `A11y.base({ slot: [...] })`, the view's own attributes on the author's word; `A11y.native({ slot:
1522
+ [...] }, { element: 'button' })`, what a native element does by itself; and
1523
+ `A11y.delegated({ slot: [...] }, { to, provider })`, an obligation met on another slot by an
1524
+ attached Behavior. The last three are Mixins that contribute nothing, attached with
1525
+ `SlotView.attach`. `A11y.conform` checks the assembled view:
1526
+
1527
+ <!-- docs-check
1528
+ import { Bundle } from 'foldkit-bundle'
1529
+ const List = Bundle.declare(ListNavigation.bundle, 'list')
1530
+ const Sel = Bundle.declare(Selection.bundle, 'selection')
1531
+ const FruitMessage = defineMessageUnion({ ...List.cases, ...Sel.cases, Cleared: {} })
1532
+ type FruitMessage = typeof FruitMessage.Type
1533
+ interface FruitInput {
1534
+ readonly list: ListNavigation.Model
1535
+ readonly selection: Selection.Model
1536
+ readonly fruit: ReadonlyArray<string>
1537
+ }
1538
+ const ListboxSlots = Slots.define({
1539
+ listbox: Slot.make({ capability: Capability.Interactive, events: [Event.KeyDown] }),
1540
+ option: Slot.make({ capability: Capability.Focusable, attributes: [Attr.AriaSelected] }),
1541
+ clear: Slot.make({ capability: Capability.Interactive, events: [Event.Click] }),
1542
+ })
1543
+ const listArgs = { orientation: 'vertical', loop: true, virtual: false, timeoutMs: 500, page: 10 } as const
1544
+ const selArgs = { mode: 'single', allowEmpty: false } as const
1545
+ -->
1546
+
1547
+ ```ts
1548
+ import { ListNavigation, Selection } from 'foldkit-primitives/interaction'
1549
+
1550
+ const Listbox = A11y.pattern({
1551
+ listbox: { capability: Capability.Interactive, obligations: [A11y.Navigation, A11y.Name] },
1552
+ option: {
1553
+ capability: Capability.Focusable,
1554
+ obligations: [A11y.FocusStrategy, A11y.Activation, A11y.State(Attr.AriaSelected)],
1555
+ },
1556
+ })
1557
+
1558
+ const Options = SlotView.over(ListboxSlots)<FruitInput, FruitMessage>()
1559
+ const itemsOf = (input: FruitInput) => Behaviors.Collection.of(input.fruit, { id: name => name })
1560
+
1561
+ export const FruitList = Options.define((input, slots, h) =>
1562
+ h.ul(
1563
+ slots.listbox.attrs([h.AriaLabel('Fruit')]),
1564
+ input.fruit.map((name, index) => h.li(slots.option.attrs([], { id: name, index }), [name])),
1565
+ ),
1566
+ ).pipe(
1567
+ Behavior.attach(
1568
+ ListNavigation.behavior(List, listArgs)(Options)({
1569
+ container: 'listbox',
1570
+ item: 'option',
1571
+ items: itemsOf,
1572
+ text: (input, index) => input.fruit[index] ?? '',
1573
+ }),
1574
+ ),
1575
+ Behavior.attach(Selection.behavior(Sel, selArgs)(Options)({ item: 'option', items: itemsOf })),
1576
+ SlotView.attach(A11y.base({ listbox: [A11y.Name] })),
1577
+ A11y.conform(Listbox),
1578
+ )
1579
+ ```
1580
+
1581
+ What each call means:
1582
+
1583
+ - `A11y.pattern` and the obligation tokens are data. Obligations are compared by name, so two
1584
+ `A11y.State(Attr.AriaSelected)` are one.
1585
+ - The view restates nothing `ListNavigation` and `Selection` supply. Given the binder, each
1586
+ factory states what it supplies from the slot names it was given (`'listbox/navigation'`,
1587
+ `'option/focus-strategy'`), and a view's type collects them through `pipe`. Leave `Selection`
1588
+ out and the `conform` line is a type error naming `'option/activation' |
1589
+ 'option/state:aria-selected'`, and nothing the steps before it supply. A factory that hands
1590
+ back several Behaviors (`Overlay.behaviors`) is one step, `Behavior.attachAll(list)`: `pipe`
1591
+ takes typed steps only, so a spread array is refused. A factory called with bare slots (`(slots)<Input, Message>`)
1592
+ states nothing, so such a view is judged at run time only. A factory states only what its run
1593
+ time is sure to supply: `Selection` states activation for a literal `mode` of `'single'` or
1594
+ `'multiple'` with its click on (left out or `true`), and a slot name known only at run time (a
1595
+ union, `string`) states nothing, through `A11y.ProvidedOn`. The type may then refuse a view the
1596
+ run time would pass; call that factory with bare slots and it is judged at run time alone.
1597
+ - At run time `conform` runs `A11y.check(pattern, view)` once, where the module loads, and throws
1598
+ a `DiagnosticError` for the first finding (`a11y:unsatisfied-obligation`, with `slot` and
1599
+ `details.obligation`; `a11y:delegation-unmet`, naming the provider), every finding in
1600
+ `details.diagnostics`. Run time reads each attachment's `meta`, never a type, so a type that
1601
+ claims more than its value supplies still fails here. An assembly whose slot names are not known
1602
+ to the type checker (built from a `Record<string, …>`) is judged here alone.
1603
+ - `conform` returns a new view that remembers the pattern: `SlotView.detach` and
1604
+ `SlotView.replace` check the view they make again, so detaching `ListNavigation` from
1605
+ `FruitList` throws. The view `conform` was given is unchanged.
1606
+ - It reads no input, runs no Mount and draws nothing. `A11y.check` returns the same findings as
1607
+ data, and `A11y.validate` stays the check of a bare contract.
1608
+ - A page pays for the check only where it conforms: every SlotView carries the record `conform`
1609
+ leaves for `detach` and `replace` (331 bytes minified, 228 brotli), and the module holding
1610
+ `conform`, `check` and the obligation tokens adds 4.0 kB minified, 1.2 kB brotli, to a page
1611
+ that imports it (measured with esbuild over the source, 2026-11-14).
1612
+
1613
+ A Behavior written by hand on the binder states its names from its slots' `provides`, with no
1614
+ annotation; this one's type supplies `'clear/activation'`:
1615
+
1616
+ ```ts
1617
+ const Clears = Options.behavior(
1618
+ {
1619
+ clear: Behavior.slot({
1620
+ provides: [A11y.Activation],
1621
+ attributes: ({ h }) => [h.OnClick(FruitMessage.Cleared())],
1622
+ }),
1623
+ },
1624
+ { name: 'Clears' },
1625
+ )
1626
+ ```
1627
+
1628
+ `Behavior.forSlots(slots)<Input, Message>(spec)` reads no `provides`, since TypeScript infers no
1629
+ type argument once one is given: use the binder. An annotation may forget what a value supplies,
1630
+ never claim more: a `SlotView.SlotView<Slots, Input, Message>` written out supplies nothing, so
1631
+ `conform` on it is a type error until the annotation names what it supplies (or is dropped), and
1632
+ typing `Options.behavior({})` as supplying `'clear/activation'` is refused. A view that
1633
+ `SlotView.detach` or `SlotView.replace` makes supplies nothing at the type level, whichever
1634
+ attachment it took: names are not in the type, and taking away what one attachment supplied may
1635
+ leave another supplying it. `conform` after either is a type error until something is attached
1636
+ again, and the run-time check, made again for a conformed view, is the judge of the result. A
1637
+ delegation names only
1638
+ what its `provider` supplies on `to`, and `to` is one of the provider's slots; both are type
1639
+ errors otherwise. A pattern without obligations, and a Behavior without `provides`, behave as
1640
+ before.
1641
+
1123
1642
  ## Introspection
1124
1643
 
1125
1644
  The contracts are data:
1126
1645
 
1127
- - `Slots.describe(contract)` and `Slot.describe(slot)` return serializable metadata.
1646
+ - `Slots.describe(contract)` and `Slot.describe(slot)` return serializable metadata;
1647
+ `SlotView.describe(view)` and `SlotView.resolution(view, input)` describe an assembled view.
1128
1648
  - `Mixin.compose` combines mixins; `Mixin.make`, `Mixin.dynamic` and `Mixin.empty` build them.
1129
1649
  - diagnostics have stable codes and structured `details`, so the same information can feed tests,
1130
1650
  DevTools, documentation or agent tooling.
@@ -1319,10 +1839,18 @@ styles({ sheet: '/src/server/sheet.ts', modules: ['/src/client/style.ts'] })
1319
1839
  a `Style.slots` declaration keeps its `slots` contract and its `style`. Its
1320
1840
  other fields (`pieces`, `css`, `rules`) throw when read. A string, or an
1321
1841
  object of strings such as `t`, ships as it is.
1842
+ - **`Style.whenInput` keeps its predicate as an import.** The classes of each
1843
+ condition are compiled at build; the page keeps only the choice among them,
1844
+ a call to your predicate. So the predicate must be a named import from a
1845
+ module that is not listed (`import { pressed } from './predicates.js'`), and
1846
+ the frozen module imports it again by the same specifier. A condition
1847
+ nested in a condition works the same way.
1322
1848
  - **What fails the build.** An export that is anything else (a function, an
1323
- `AppStyle`), and a Style using `Style.whenInput` or `Style.perItem`, which
1324
- choose classes at run time. The error names the module and the export. Keep
1325
- such a module at run time by leaving it off the list.
1849
+ `AppStyle`, a bare `Slots.define` contract), a `Style.whenInput` whose
1850
+ predicate is written in place or imported from a listed module, and any
1851
+ `Style.perItem`: a per-item piece compiles its classes when it is drawn, so
1852
+ it needs the compiler the page no longer has. The error names the module and
1853
+ the export. Keep such a module at run time by leaving it off the list.
1326
1854
  - **Attach with `SlotView`.** A module that imports `Style` keeps the compiler
1327
1855
  in the page, so attach a frozen style with `SlotView.attach(Page.style.mixin)`
1328
1856
  rather than `Style.attach(Page.style)`, and keep the `AppStyle` (its `slots`