foldkit-mixins 0.25.0 → 0.26.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 +564 -43
  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 +28 -4
  81. package/dist/style.d.ts.map +1 -1
  82. package/dist/style.js +57 -11
  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)) |
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,59 @@ 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` and a `null` selection work on the result, and
433
+ 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
+ export const Brand = Style.forSlots(ButtonSlots)(AppButton({ tone: 'brand', width: 'full' }))
461
+ export const Accent = Style.forSlots(ButtonSlots)(AppButton())
462
+
463
+ // @ts-expect-error `accent` is the recipe's own: adjust it with `extend`.
464
+ Button.add({ tone: { accent: { button: Style.self({ background: 'navy' }) } } })
465
+ // @ts-expect-error `extend` adds no axis.
466
+ Button.extend({ variants: { width: { full: { button: Style.self({ inlineSize: '100%' }) } } } })
467
+ ```
468
+
469
+ An added axis has no default: `AppButton()` above is the recipe as shipped. Give it one with
470
+ `AppButton.extend({ defaults: { width: 'full' } })`. The values are style pieces like any
471
+ recipe's, so a module that calls `add` is still one the build can
472
+ [ship as data](#style-modules-shipped-as-data).
473
+
396
474
  ### Themes as typed knobs
397
475
 
398
476
  `foldkit-mixins/theme` extends the root `Theme` with the pieces a page ships. A theme is a typed
@@ -494,14 +572,114 @@ is declared, so knobs set below the root change nothing derived from them there:
494
572
  `tokens` an application's own groups beside the shipped ones. The design is in
495
573
  `docs/theme-knobs.md`.
496
574
 
575
+ ### Following another tab
576
+
577
+ `Themes.choose` and `Theme.chooseScheme` write this tab's `localStorage`, and another tab hears
578
+ that as a `storage` event. `themeChanges(themes)` and `schemeChanges()` are Streams of
579
+ what another tab chose, decoded as the head scripts decode it: a name no theme has, a removed key
580
+ and anything else read as the initial theme or `'system'`. The writing tab hears nothing. They are
581
+ named exports, not members of `Themes` or `Theme`, so a page that reads neither ships no storage
582
+ listener. They
583
+ apply nothing, because the Model owns the choice: map each to a Message, and let `update` store
584
+ it and answer with the Command that shows it.
585
+
586
+ ```ts
587
+ import { Schema, Stream } from 'effect'
588
+ import { defineMessageUnion } from 'foldkit/message'
589
+ import * as Subscription from 'foldkit/subscription'
590
+ import { schemeChanges, themeChanges, Themes } from 'foldkit-mixins/theme'
591
+
592
+ const Followed = defineMessageUnion({
593
+ ThemeFollowed: { name: themes.Name },
594
+ SchemeFollowed: { scheme: Schema.Literals(['system', 'light', 'dark']) },
595
+ })
596
+ type Shown = { readonly theme: typeof themes.Name.Type }
597
+
598
+ export const followed = Subscription.make<Shown, typeof Followed.Type>()(() => ({
599
+ theme: Subscription.persistentEntry(
600
+ themeChanges(themes).pipe(Stream.map(name => Followed.ThemeFollowed({ name }))),
601
+ ),
602
+ scheme: Subscription.persistentEntry(
603
+ schemeChanges().pipe(Stream.map(scheme => Followed.SchemeFollowed({ scheme }))),
604
+ ),
605
+ }))
606
+ ```
607
+
608
+ On `ThemeFollowed`, `update` sets the Model's field and returns `Themes.apply(themes, name)`; on
609
+ `SchemeFollowed` it returns `Theme.chooseScheme(scheme)`. Kept knobs have no stream:
610
+ `Theme.chooseKnobs` stores CSS variable declarations, which do not map back to a theme's knobs.
611
+
612
+ ### Switching themes in a page with no style compiler
613
+
614
+ `Themes.make` compiles the themes, so a page built with `foldkit-mixins/vite`'s `modules`, which
615
+ ships no style compiler, cannot import it. The functions that only show, keep and hear a theme
616
+ need no compiled theme: `foldkit-mixins/theme/runtime` exports them (the same functions as
617
+ `Themes.apply`, `Themes.choose`, `Themes.script` and `themeChanges`) over `ThemeNames`, the
618
+ names, the initial name and the root attribute, which a compiled `Themes` already is. A page
619
+ without the compiler declares its own, typed by a type-only import of the compiled set so the
620
+ names cannot drift in type. `foldkit-mixins/theme/knob-data` holds each range knob of
621
+ `Knobs.standard` as plain data, one named export per knob (`shapeDensity` is `{ name: 'shape.density',
622
+ title, variable, unit, min, max, step, default }`; a knob with a light and a dark value is two,
623
+ `accentChromaLight` and `accentChromaDark`), for a panel's sliders. A page keeps only the knobs it
624
+ imports; `knobData`, the same entries by name (`knobData['shape.density']`), is for a panel that
625
+ draws every knob. The file is generated from `Knobs.standard` by
626
+ `pnpm --filter foldkit-mixins generate:knob-data`, and a test fails when it differs.
627
+
628
+ ```ts standalone
629
+ import { Effect, Stream } from 'effect'
630
+ import { shapeDensity } from 'foldkit-mixins/theme/knob-data'
631
+ import {
632
+ applyTheme,
633
+ chooseTheme,
634
+ themeChanges,
635
+ themeScript,
636
+ type ThemeNames,
637
+ } from 'foldkit-mixins/theme/runtime'
638
+
639
+ type Look = 'cobalt' | 'cobaltDense'
640
+ const looks: ThemeNames<Look> = {
641
+ names: ['cobalt', 'cobaltDense'],
642
+ initial: 'cobalt',
643
+ attribute: 'data-theme',
644
+ }
645
+
646
+ // A Command's effects: the Model's field owns the chosen name, these only show it.
647
+ export const show = (name: Look): Effect.Effect<void> => applyTheme(looks, name)
648
+ export const keep = (name: Look): Effect.Effect<void> => chooseTheme(looks, name)
649
+ // A Subscription's stream: another tab's choice, for `update` to store and answer with `show`.
650
+ export const followed: Stream.Stream<Look> = themeChanges(looks)
651
+ // The text of the head `<script>`, which shows the kept theme before the first paint.
652
+ export const head: string = themeScript(looks)
653
+ export const density = shapeDensity
654
+ ```
655
+
656
+ A name that is not one of `names` is a type error at a call. One read from storage, which nothing
657
+ validated, never reaches a call: the head script leaves the initial theme, and `themeChanges`
658
+ emits the initial theme, exactly as for a compiled set. Neither entry imports style code, so
659
+ `modules` accepts a page that imports only these.
660
+
661
+ ### The server's first render of the scheme
662
+
663
+ A server that builds the Model per request reads the browser's hint with
664
+ `schemeOfHint(request.headers.get('sec-ch-prefers-color-scheme'))`, which is
665
+ `Option.some('light' | 'dark')` or `Option.none()`. A browser sends the hint only after a
666
+ response asks for it, so send `COLOR_SCHEME_HINT_HEADERS` on pages: `Accept-CH` opts in,
667
+ `Critical-CH` has the browser retry the first request with the hint, and `Vary` keeps a cache
668
+ from serving one scheme's page to the other. Both are exported from `foldkit-mixins/theme`.
669
+
497
670
  ### What the palette derives
498
671
 
499
672
  `Theme.standard(theme)` holds typed tokens for surfaces, text, outlines, and the accent, secondary,
500
673
  tertiary and feedback families, derived from the theme's knobs. Only the `knob` group holds literals; every other value is a CSS
501
674
  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`,
675
+ the derivation and one knob override recolors everything below it. A derived color takes its hue
676
+ from the palette's hue tokens (`hue.neutral`, `hue.accent`), never from the color it starts from,
677
+ and the palette mixes in OKLab: a grey's hue is powerless, engines read it differently (Chromium
678
+ keeps the hue a grey was written with, others read 0, a red), and an OKLCH mix or added chroma
679
+ carries it into the result. Mix tokens of your own the same way, `color-mix(in oklab, …)`. Each family (`accent`,
503
680
  `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
681
+ lighter in a dark scheme; `hover` and `active` (darker, and `active` more vivid by 0.05 of chroma, at most
682
+ twice its own, so a grey fill stays grey when pressed); `subtle`, a tint of it on the base; `outline`, a
505
683
  line in it that stands off the base; and two text colors named for where they go: `on-fill` is
506
684
  text on that fill (near white on a mid accent), and `ink` is text in the family's color on the
507
685
  base surface, dark enough to read in a light scheme and light enough in a dark one. Colored text
@@ -527,8 +705,18 @@ the surface knobs. Each hue is a knob (`red-h`), and `scale-c` scales every step
527
705
  (`--fk-blue-wash-2`, `ref.blue['6']`). The `popup` group is a menu's
528
706
  panel (`surface`, `ink`, `blur`) and its lit row (`highlight`, `press`, `highlight-ink`):
529
707
  `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.
708
+ as the page's own raised surface (`default`), `inverted` (the other scheme's surface and text) or
709
+ `translucent` over a blur, as shadcn's menu options do. The `selection` group is selected text,
710
+ which `Defaults.body` paints with `:where(*)::selection`: `background` is the accent over whatever
711
+ the text sits on (28% in a light scheme, 40% in a dark one, so the text stays at AA), `ink` is
712
+ `currentColor` so a link or a syntax token keeps its colour, and `fill-background` is the deeper
713
+ accent for text on the accent's own fill, where the tint would be the fill: such a surface sets
714
+ `--fk-selection-background` to it beside its fill. Override like any token,
715
+ `Theme.compose(theme, { selection: { background: 'rebeccapurple' } })`; an application's own
716
+ `::selection` rule wins. A lit row takes its ink from the surface
717
+ it is on: a popup panel sets `--_fk-row-highlight`, `--_fk-row-press` and
718
+ `--_fk-row-highlight-ink` on itself, and a row outside one (an inline Command) reads the `plain-*`
719
+ tokens, the text's own films or the accent.
532
720
  Each is a 0-or-1 knob (`popup-bold`, `popup-invert`) blended by `color-mix`, so an override
533
721
  switches it live. The `state` group is what a state lays over the surface under it, a mix of the
534
722
  element's own text color (`hover`, and `press` at 1.75 of it; `tint` and `tint-hover`, a
@@ -555,7 +743,8 @@ each level is an even step lighter.
555
743
  non-color scales, with `space` and `radius` multiplied by the `density` and `radius-factor` knobs.
556
744
  Its `motion` group is three tiers, `fast`, `moderate` and `slow` (80, 160 and 240ms, for hover and
557
745
  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`,
746
+ `motion` knob. `sheet` and `sheet-exit` time a Sheet's slide: they read the `slow` tier until a theme
747
+ sets them. A duration of something that moves or resizes also multiplies by `knob.travel`,
559
748
  which `Defaults.reset` sets to 0 under `prefers-reduced-motion`: the thing stops travelling, and its
560
749
  fade still plays.
561
750
 
@@ -948,6 +1137,63 @@ the view's input; none owns anything.
948
1137
  press-and-hold repeat and the wheel are not handled: Foldkit's wheel
949
1138
  attribute carries no delta, and a repeat is a timer the Model would own.
950
1139
 
1140
+ ### Keys: one owner for a slot's `keydown`
1141
+
1142
+ The resolver allows one owner of an event on a slot, so a widget's own keys and the keys an
1143
+ application wants to add cannot be two Behaviors on `keydown`. `Behaviors.Keys` is the one owner:
1144
+ a widget's keys are named **routes**, and `Keys.behavior` folds the routes it is given into the
1145
+ slot's single handler. A route says which presses it takes (`Keys.chord('Escape')`,
1146
+ `Keys.printable`, or a `Keys.where` predicate) and what a press means: a Message, or `Keys.focus(id,
1147
+ message)` to also move focus to the element with that id. A route that returns `Option.none()`
1148
+ declines, and the press goes on to the page.
1149
+
1150
+ <!-- docs-check
1151
+ import { Option } from 'effect'
1152
+ -->
1153
+
1154
+ ```ts
1155
+ const SearchSlots = Slots.define({
1156
+ root: Slot.make({ capability: Capability.Container }),
1157
+ input: Slot.make({ capability: Capability.TextInput, events: [Event.Input, Event.KeyDown] }),
1158
+ })
1159
+ type SearchInput = { readonly query: string }
1160
+ const { Keys } = Behaviors
1161
+
1162
+ const clearOnEscape = Keys.route<SearchInput, Message>('ClearOnEscape', {
1163
+ on: [Keys.chord('Escape')],
1164
+ // With nothing to clear the route declines, so Escape reaches the dialog around the field.
1165
+ handle: ({ input }) =>
1166
+ input.query === '' ? Option.none() : Option.some(Message.ChangedValue({ value: '' })),
1167
+ })
1168
+
1169
+ // A widget takes the application's routes beside its own: this is how foldkit-mixins-ui's
1170
+ // Command, SearchField, Tabs, Menubar and others take their `routes` option.
1171
+ const searchKeys = (routes: ReadonlyArray<Behaviors.Keys.Route<SearchInput, Message>> = []) =>
1172
+ Keys.behavior(SearchSlots)<SearchInput, Message>({
1173
+ slot: 'input',
1174
+ routes: [clearOnEscape, ...routes],
1175
+ })
1176
+
1177
+ // The application adds a key without touching the widget:
1178
+ const Submits = searchKeys([
1179
+ Keys.route('Submit', {
1180
+ on: [Keys.chord('Enter')],
1181
+ handle: ({ input }) => Option.some(Message.ChangedValue({ value: input.query.trim() })),
1182
+ }),
1183
+ ])
1184
+ ```
1185
+
1186
+ Two routes that declare the same chord throw `mixins:key-conflict` when the Behavior is defined,
1187
+ naming both, because nothing chains at run time and one press sends at most one Message. Where one
1188
+ 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
1189
+ `key` a press reports, so Shift+a is `Keys.chord('A')`; a name that is neither one character nor a
1190
+ named key (`'Esc'`) throws `mixins:unknown-key` and says what was meant. A handled press is
1191
+ default-prevented, an unhandled one untouched, a key of an IME composition reaches no route, and a
1192
+ held key runs its route on every repeat. A Behavior that writes other attributes on the same slot
1193
+ (a roving tab stop) installs its keys with `Keys.attribute(routes, { slot })` inside its own
1194
+ `attributes`, which is how the primitives expose theirs (`ListNavigation.keys`, `SwipeActions.keys`,
1195
+ `Move.nudge`). A key the application only watches, without owning, is a Subscription
1196
+ (`keyboardEvents` in `foldkit-primitives/events`), not a route.
951
1197
 
952
1198
  ## SlotView
953
1199
 
@@ -963,6 +1209,85 @@ infers it from an explicit `h: HtmlBuilder<Message>` annotation. Without one, `M
963
1209
  `Behavior.attach` uses the behavior's `Input` as the attached view's `Input`, so declare a
964
1210
  behavior over the view's input type, not merely the subset of fields it happens to read.
965
1211
 
1212
+ ### Naming the slots, input and Messages once: `SlotView.over`
1213
+
1214
+ A Behavior is made before the view it meets, so `Behavior.forSlots(S)<Input, Message>` names
1215
+ both types again for every Behavior. `SlotView.over(S)<Input, Message>()` names them once and
1216
+ hands back `define`, `behavior` and `parts` with all three fixed, so nothing passed to them is
1217
+ annotated:
1218
+
1219
+ ```ts
1220
+ const Fields = SlotView.over(FieldSlots)<FieldInput, Message>()
1221
+
1222
+ const Validates = Fields.behavior(
1223
+ { input: { attributes: ({ input, h }) => [h.AriaInvalid(input.invalid)] } },
1224
+ { name: 'Validates' },
1225
+ )
1226
+ const BoundField = Fields.define((input, slots, h) =>
1227
+ h.label(slots.root.attrs(), [
1228
+ h.input(
1229
+ slots.input.attrs([
1230
+ h.Value(input.value),
1231
+ h.OnInput(value => Message.ChangedValue({ value })),
1232
+ ]),
1233
+ ),
1234
+ ]),
1235
+ ).pipe(Behavior.attach(Validates))
1236
+ ```
1237
+
1238
+ `Fields.define` is `SlotView.define`, `Fields.behavior` is `Behavior.forSlots` and
1239
+ `Fields.parts` is `SlotView.parts`: the binder makes no new kind of value and holds no state. A
1240
+ Behavior from a binder over another Message universe is still refused at `Behavior.attach`.
1241
+ `foldkit-mixins-surface`'s `SurfaceView.over(surface, slots)` is the same binder with both types
1242
+ read from the Surface. A factory that takes slots can take a binder in their place, telling the
1243
+ two apart with `SlotView.isBound`.
1244
+
1245
+ ### What a view remembers of its attachments
1246
+
1247
+ Each attachment keeps its name, and a Style or Behavior also its `meta`: its kind and, per slot,
1248
+ what it requires, what it supplies (its `provides`, see [Obligations](#obligations-who-does-what-a-pattern-asks))
1249
+ and whether it reads the input. A Mixin made with `Mixin.make` or
1250
+ `Mixin.dynamic` carries none; `Mixin.compose` records its parts in order. A name addresses an
1251
+ attachment:
1252
+
1253
+ ```ts
1254
+ const Unchecked = BoundField.pipe(SlotView.detach('Validates'))
1255
+ const Checked = Unchecked.pipe(Behavior.attach(Validates))
1256
+ const Swapped = Checked.pipe(SlotView.replace('Validates', Validates.mixin))
1257
+ ```
1258
+
1259
+ `detach` and `replace` return a new view, `replace` keeping the attachment's place in the
1260
+ resolution order. Each throws `mixins:unknown-attachment` for a name the view does not hold and
1261
+ `mixins:ambiguous-attachment` for one it holds twice, so name a Behavior you mean to address
1262
+ (an unnamed one is called `Behavior`).
1263
+
1264
+ ### Describing a view, and what one input resolves to
1265
+
1266
+ `SlotView.describe(view)` is the view as data: its slots, and each attachment in order with, per
1267
+ slot, what it requires, what it supplies and the classes and Mounts it contributes. It needs no
1268
+ input and calls no contribution; one that is a function of the input reads `'unknown'`. It
1269
+ reads the view value, so a view you attach to or detach from has a description of its own and
1270
+ the first one's does not change. A `JSON.parse(JSON.stringify(description))` equals it, and
1271
+ `SlotView.toMarkdown(description)` prints it.
1272
+
1273
+ ```ts
1274
+ const description = SlotView.describe(Checked)
1275
+ // description.attachments[0]: { order, name, kind, slots: { input: { requires, provides, contributes } } }
1276
+ const markdown = SlotView.toMarkdown(description)
1277
+ ```
1278
+
1279
+ `SlotView.resolution(view, input)` evaluates every contribution for one input and reports, per
1280
+ slot, the class tokens, style property names, attribute names, event names and Mount names, each
1281
+ with the attachment that gave it. It reports no attribute value, style value or Mount args, since
1282
+ any of them may be the input's (a password in `Value`); class tokens are reported as given, so a
1283
+ class built from input text surfaces it. It builds handlers with the inert builder
1284
+ and calls none, runs no Mount, and returns a conflict as a finding where `resolve` would throw.
1285
+ It does not draw the view, so a clash with the view's own base attributes is not reported.
1286
+ Attribute and event names are as the resolver compares them (lower case, no hyphens).
1287
+
1288
+ `findings` also warn (`severity: 'warning'`) of an unnamed attachment and of two with one name,
1289
+ which `detach` and `replace` cannot address.
1290
+
966
1291
  For per-item groups such as tabs, options or calendar cells, use
967
1292
  `SlotView.buildersFor(slots, mixins, { input, h })` and map the items yourself. One contribution
968
1293
  then applies to every item while each item's base attributes retain their own event ownership.
@@ -994,7 +1319,10 @@ is not redrawn for. `Panel` is an ordinary SlotView: Styles and Behaviors attach
994
1319
  to it and reach every part's Slots.
995
1320
 
996
1321
  - **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.
1322
+ part's selection (`Pick<Input, 'count'>`), and are resolved against it. A part
1323
+ is found only by drawing it, so `A11y.conform` reads none of its Behaviors'
1324
+ obligations, at the type level or at run time: attach a Behavior that must
1325
+ count to the assembly, and the finding says so when it is put on a part.
998
1326
  - **A Mixin attached to the whole view that reads the input** (a Behavior's
999
1327
  `attributes`, `Style.whenInput`) is resolved against the whole input, so the
1000
1328
  parts it reaches are drawn again on every change: correct, not cached. Static
@@ -1120,11 +1448,196 @@ A11y.validate(DialogPattern, DialogSlots)
1120
1448
  slots, capability mismatches and unpublished events or attributes. An optional requirement
1121
1449
  tolerates an absent slot but still checks a present one. It does **not** certify WCAG compliance.
1122
1450
 
1451
+ Three words stay apart here. A slot contract or a `provides` is **declared**: the author says so.
1452
+ `A11y.validate`, `A11y.check` and `A11y.conform` are **structural**: they say the declarations fit
1453
+ together. Only a browser test is **rendered**: it says the behaviour happened on a page. None of
1454
+ them is WCAG conformance.
1455
+
1456
+ ### Conformance: the rendered check
1457
+
1458
+ `Conformance` from `foldkit-mixins/testing` is the rendered word. Each scenario takes a harness
1459
+ and returns its findings as plain data, so a widget and a view assembled from primitives are held
1460
+ to one behaviour. `Conformance.harness({ cdp, userEvent })` is the harness for Vitest's browser
1461
+ mode: keys from `userEvent.keyboard`, roles and names from Chromium's own accessibility tree
1462
+ (which Vitest's locators do not match), read inside its root (the document by default) with each
1463
+ node's DOM element, and a pointer press as dispatched events. It takes the two from you, so
1464
+ `foldkit-mixins` imports no test runner. `cdp` is the Playwright provider's, so a test file
1465
+ names it first (`/// <reference types="@vitest/browser-playwright" />`, which types the session):
1466
+
1467
+ <!-- docs-check
1468
+ declare const cdp: Conformance.BrowserTools['cdp']
1469
+ declare const userEvent: Conformance.BrowserTools['userEvent']
1470
+ -->
1471
+
1472
+ ```ts
1473
+ import { Conformance } from 'foldkit-mixins/testing'
1474
+ // import { cdp, userEvent } from 'vitest/browser'
1475
+
1476
+ declare const button: HTMLElement
1477
+
1478
+ const harness = Conformance.harness({ cdp, userEvent })
1479
+ const result = await Conformance.listbox(harness, {
1480
+ name: 'Frequency',
1481
+ options: ['Hourly', 'Daily', 'Weekly'],
1482
+ disabled: 'Daily',
1483
+ orientation: 'horizontal',
1484
+ direction: 'rtl',
1485
+ enter: async () => button.focus(), // gives the keyboard to the widget, options drawn
1486
+ })
1487
+ console.log(Conformance.failures(result)) // []
1488
+ ```
1489
+
1490
+ `Conformance.listbox`, `.checkbox`, `.tree`, `.dialog` (focus in, Tab contained, Escape, focus
1491
+ restored, a second dialog opened over the first) and `.tabs` read what the page did: roles and
1492
+ names from the accessibility tree, `aria-selected`, `aria-checked` and `aria-expanded` from the
1493
+ page, focus from `document`. They read no Model, Slot or obligation. `Conformance.server(scenario,
1494
+ root, expected)` is the server half: parse a rendered string and it checks each expected role,
1495
+ name and attribute. Another runner gives a `Conformance.Harness` of its own (`{ root, press,
1496
+ accessibility, click }`). `SlotView.describe(view).conforms` lists the patterns a view was conformed to.
1497
+
1498
+ ### Obligations: who does what a pattern asks
1499
+
1500
+ A contract that publishes `keydown` on a list does not navigate it, and one that publishes
1501
+ `aria-selected` does not write it. A pattern's slot can also name **obligations**: things an
1502
+ attachment must say it does on that slot.
1503
+
1504
+ | Obligation | Means | Supplied by |
1505
+ | --- | --- | --- |
1506
+ | `A11y.Navigation` | arrows, Home and End move among the items | `ListNavigation`, `RovingTabindex`, `TreeNavigation`, `GridNavigation`, `SpatialNavigation` (container slot) |
1507
+ | `A11y.FocusStrategy` | each item is reachable: a roving stop, `aria-activedescendant`, or a native control | the same five (item slot); `A11y.native` |
1508
+ | `A11y.Activation` | Enter, Space or a press activates it | `Selection` (unless `click: false`), `Press`; `A11y.native` |
1509
+ | `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`) |
1510
+ | `A11y.Name` | the element has an accessible name | `Behaviors.FieldAssociation`; the view's own label, as `A11y.base` |
1511
+
1512
+ Something supplies an obligation in one of four ways: a Behavior slot's `provides`
1513
+ (`Behavior.slot({ provides: [A11y.Navigation], ... })`, as the primitives above declare theirs);
1514
+ `A11y.base({ slot: [...] })`, the view's own attributes on the author's word; `A11y.native({ slot:
1515
+ [...] }, { element: 'button' })`, what a native element does by itself; and
1516
+ `A11y.delegated({ slot: [...] }, { to, provider })`, an obligation met on another slot by an
1517
+ attached Behavior. The last three are Mixins that contribute nothing, attached with
1518
+ `SlotView.attach`. `A11y.conform` checks the assembled view:
1519
+
1520
+ <!-- docs-check
1521
+ import { Bundle } from 'foldkit-bundle'
1522
+ const List = Bundle.declare(ListNavigation.bundle, 'list')
1523
+ const Sel = Bundle.declare(Selection.bundle, 'selection')
1524
+ const FruitMessage = defineMessageUnion({ ...List.cases, ...Sel.cases, Cleared: {} })
1525
+ type FruitMessage = typeof FruitMessage.Type
1526
+ interface FruitInput {
1527
+ readonly list: ListNavigation.Model
1528
+ readonly selection: Selection.Model
1529
+ readonly fruit: ReadonlyArray<string>
1530
+ }
1531
+ const ListboxSlots = Slots.define({
1532
+ listbox: Slot.make({ capability: Capability.Interactive, events: [Event.KeyDown] }),
1533
+ option: Slot.make({ capability: Capability.Focusable, attributes: [Attr.AriaSelected] }),
1534
+ clear: Slot.make({ capability: Capability.Interactive, events: [Event.Click] }),
1535
+ })
1536
+ const listArgs = { orientation: 'vertical', loop: true, virtual: false, timeoutMs: 500, page: 10 } as const
1537
+ const selArgs = { mode: 'single', allowEmpty: false } as const
1538
+ -->
1539
+
1540
+ ```ts
1541
+ import { ListNavigation, Selection } from 'foldkit-primitives/interaction'
1542
+
1543
+ const Listbox = A11y.pattern({
1544
+ listbox: { capability: Capability.Interactive, obligations: [A11y.Navigation, A11y.Name] },
1545
+ option: {
1546
+ capability: Capability.Focusable,
1547
+ obligations: [A11y.FocusStrategy, A11y.Activation, A11y.State(Attr.AriaSelected)],
1548
+ },
1549
+ })
1550
+
1551
+ const Options = SlotView.over(ListboxSlots)<FruitInput, FruitMessage>()
1552
+ const itemsOf = (input: FruitInput) => Behaviors.Collection.of(input.fruit, { id: name => name })
1553
+
1554
+ export const FruitList = Options.define((input, slots, h) =>
1555
+ h.ul(
1556
+ slots.listbox.attrs([h.AriaLabel('Fruit')]),
1557
+ input.fruit.map((name, index) => h.li(slots.option.attrs([], { id: name, index }), [name])),
1558
+ ),
1559
+ ).pipe(
1560
+ Behavior.attach(
1561
+ ListNavigation.behavior(List, listArgs)(Options)({
1562
+ container: 'listbox',
1563
+ item: 'option',
1564
+ items: itemsOf,
1565
+ text: (input, index) => input.fruit[index] ?? '',
1566
+ }),
1567
+ ),
1568
+ Behavior.attach(Selection.behavior(Sel, selArgs)(Options)({ item: 'option', items: itemsOf })),
1569
+ SlotView.attach(A11y.base({ listbox: [A11y.Name] })),
1570
+ A11y.conform(Listbox),
1571
+ )
1572
+ ```
1573
+
1574
+ What each call means:
1575
+
1576
+ - `A11y.pattern` and the obligation tokens are data. Obligations are compared by name, so two
1577
+ `A11y.State(Attr.AriaSelected)` are one.
1578
+ - The view restates nothing `ListNavigation` and `Selection` supply. Given the binder, each
1579
+ factory states what it supplies from the slot names it was given (`'listbox/navigation'`,
1580
+ `'option/focus-strategy'`), and a view's type collects them through `pipe`. Leave `Selection`
1581
+ out and the `conform` line is a type error naming `'option/activation' |
1582
+ 'option/state:aria-selected'`, and nothing the steps before it supply. A factory that hands
1583
+ back several Behaviors (`Overlay.behaviors`) is one step, `Behavior.attachAll(list)`: `pipe`
1584
+ takes typed steps only, so a spread array is refused. A factory called with bare slots (`(slots)<Input, Message>`)
1585
+ states nothing, so such a view is judged at run time only. A factory states only what its run
1586
+ time is sure to supply: `Selection` states activation for a literal `mode` of `'single'` or
1587
+ `'multiple'` with its click on (left out or `true`), and a slot name known only at run time (a
1588
+ union, `string`) states nothing, through `A11y.ProvidedOn`. The type may then refuse a view the
1589
+ run time would pass; call that factory with bare slots and it is judged at run time alone.
1590
+ - At run time `conform` runs `A11y.check(pattern, view)` once, where the module loads, and throws
1591
+ a `DiagnosticError` for the first finding (`a11y:unsatisfied-obligation`, with `slot` and
1592
+ `details.obligation`; `a11y:delegation-unmet`, naming the provider), every finding in
1593
+ `details.diagnostics`. Run time reads each attachment's `meta`, never a type, so a type that
1594
+ claims more than its value supplies still fails here. An assembly whose slot names are not known
1595
+ to the type checker (built from a `Record<string, …>`) is judged here alone.
1596
+ - `conform` returns a new view that remembers the pattern: `SlotView.detach` and
1597
+ `SlotView.replace` check the view they make again, so detaching `ListNavigation` from
1598
+ `FruitList` throws. The view `conform` was given is unchanged.
1599
+ - It reads no input, runs no Mount and draws nothing. `A11y.check` returns the same findings as
1600
+ data, and `A11y.validate` stays the check of a bare contract.
1601
+ - A page pays for the check only where it conforms: every SlotView carries the record `conform`
1602
+ leaves for `detach` and `replace` (331 bytes minified, 228 brotli), and the module holding
1603
+ `conform`, `check` and the obligation tokens adds 4.0 kB minified, 1.2 kB brotli, to a page
1604
+ that imports it (measured with esbuild over the source, 2026-11-14).
1605
+
1606
+ A Behavior written by hand on the binder states its names from its slots' `provides`, with no
1607
+ annotation; this one's type supplies `'clear/activation'`:
1608
+
1609
+ ```ts
1610
+ const Clears = Options.behavior(
1611
+ {
1612
+ clear: Behavior.slot({
1613
+ provides: [A11y.Activation],
1614
+ attributes: ({ h }) => [h.OnClick(FruitMessage.Cleared())],
1615
+ }),
1616
+ },
1617
+ { name: 'Clears' },
1618
+ )
1619
+ ```
1620
+
1621
+ `Behavior.forSlots(slots)<Input, Message>(spec)` reads no `provides`, since TypeScript infers no
1622
+ type argument once one is given: use the binder. An annotation may forget what a value supplies,
1623
+ never claim more: a `SlotView.SlotView<Slots, Input, Message>` written out supplies nothing, so
1624
+ `conform` on it is a type error until the annotation names what it supplies (or is dropped), and
1625
+ typing `Options.behavior({})` as supplying `'clear/activation'` is refused. A view that
1626
+ `SlotView.detach` or `SlotView.replace` makes supplies nothing at the type level, whichever
1627
+ attachment it took: names are not in the type, and taking away what one attachment supplied may
1628
+ leave another supplying it. `conform` after either is a type error until something is attached
1629
+ again, and the run-time check, made again for a conformed view, is the judge of the result. A
1630
+ delegation names only
1631
+ what its `provider` supplies on `to`, and `to` is one of the provider's slots; both are type
1632
+ errors otherwise. A pattern without obligations, and a Behavior without `provides`, behave as
1633
+ before.
1634
+
1123
1635
  ## Introspection
1124
1636
 
1125
1637
  The contracts are data:
1126
1638
 
1127
- - `Slots.describe(contract)` and `Slot.describe(slot)` return serializable metadata.
1639
+ - `Slots.describe(contract)` and `Slot.describe(slot)` return serializable metadata;
1640
+ `SlotView.describe(view)` and `SlotView.resolution(view, input)` describe an assembled view.
1128
1641
  - `Mixin.compose` combines mixins; `Mixin.make`, `Mixin.dynamic` and `Mixin.empty` build them.
1129
1642
  - diagnostics have stable codes and structured `details`, so the same information can feed tests,
1130
1643
  DevTools, documentation or agent tooling.
@@ -1319,10 +1832,18 @@ styles({ sheet: '/src/server/sheet.ts', modules: ['/src/client/style.ts'] })
1319
1832
  a `Style.slots` declaration keeps its `slots` contract and its `style`. Its
1320
1833
  other fields (`pieces`, `css`, `rules`) throw when read. A string, or an
1321
1834
  object of strings such as `t`, ships as it is.
1835
+ - **`Style.whenInput` keeps its predicate as an import.** The classes of each
1836
+ condition are compiled at build; the page keeps only the choice among them,
1837
+ a call to your predicate. So the predicate must be a named import from a
1838
+ module that is not listed (`import { pressed } from './predicates.js'`), and
1839
+ the frozen module imports it again by the same specifier. A condition
1840
+ nested in a condition works the same way.
1322
1841
  - **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.
1842
+ `AppStyle`, a bare `Slots.define` contract), a `Style.whenInput` whose
1843
+ predicate is written in place or imported from a listed module, and any
1844
+ `Style.perItem`: a per-item piece compiles its classes when it is drawn, so
1845
+ it needs the compiler the page no longer has. The error names the module and
1846
+ the export. Keep such a module at run time by leaving it off the list.
1326
1847
  - **Attach with `SlotView`.** A module that imports `Style` keeps the compiler
1327
1848
  in the page, so attach a frozen style with `SlotView.attach(Page.style.mixin)`
1328
1849
  rather than `Style.attach(Page.style)`, and keep the `AppStyle` (its `slots`