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.
- package/README.md +564 -43
- package/dist/a11y.d.ts +127 -1
- package/dist/a11y.d.ts.map +1 -1
- package/dist/a11y.js +138 -9
- package/dist/a11y.js.map +1 -1
- package/dist/attr.d.ts +8 -0
- package/dist/attr.d.ts.map +1 -1
- package/dist/attr.js +19 -11
- package/dist/attr.js.map +1 -1
- package/dist/behavior.d.ts +40 -7
- package/dist/behavior.d.ts.map +1 -1
- package/dist/behavior.js +31 -7
- package/dist/behavior.js.map +1 -1
- package/dist/behaviors/collection.d.ts +3 -1
- package/dist/behaviors/collection.d.ts.map +1 -1
- package/dist/behaviors/collection.js +14 -16
- package/dist/behaviors/collection.js.map +1 -1
- package/dist/behaviors/disclosure.d.ts +6 -3
- package/dist/behaviors/disclosure.d.ts.map +1 -1
- package/dist/behaviors/disclosure.js +17 -10
- package/dist/behaviors/disclosure.js.map +1 -1
- package/dist/behaviors/field-association.d.ts +6 -3
- package/dist/behaviors/field-association.d.ts.map +1 -1
- package/dist/behaviors/field-association.js +28 -22
- package/dist/behaviors/field-association.js.map +1 -1
- package/dist/behaviors/id-selector.d.ts +7 -0
- package/dist/behaviors/id-selector.d.ts.map +1 -0
- package/dist/behaviors/id-selector.js +10 -0
- package/dist/behaviors/id-selector.js.map +1 -0
- package/dist/behaviors/index.d.ts +2 -1
- package/dist/behaviors/index.js +2 -1
- package/dist/behaviors/keys.d.ts +169 -0
- package/dist/behaviors/keys.d.ts.map +1 -0
- package/dist/behaviors/keys.js +347 -0
- package/dist/behaviors/keys.js.map +1 -0
- package/dist/behaviors/spin-value.d.ts +15 -3
- package/dist/behaviors/spin-value.d.ts.map +1 -1
- package/dist/behaviors/spin-value.js +46 -16
- package/dist/behaviors/spin-value.js.map +1 -1
- package/dist/behaviors/toggle-state.d.ts +7 -4
- package/dist/behaviors/toggle-state.d.ts.map +1 -1
- package/dist/behaviors/toggle-state.js +14 -7
- package/dist/behaviors/toggle-state.js.map +1 -1
- package/dist/conformance.d.ts +205 -0
- package/dist/conformance.d.ts.map +1 -0
- package/dist/conformance.js +582 -0
- package/dist/conformance.js.map +1 -0
- package/dist/conformed.d.ts +17 -0
- package/dist/conformed.d.ts.map +1 -0
- package/dist/conformed.js +21 -0
- package/dist/conformed.js.map +1 -0
- package/dist/defaults.d.ts.map +1 -1
- package/dist/defaults.js +1 -1
- package/dist/defaults.js.map +1 -1
- package/dist/describe.d.ts +91 -0
- package/dist/describe.d.ts.map +1 -0
- package/dist/describe.js +239 -0
- package/dist/describe.js.map +1 -0
- package/dist/diagnostics.d.ts +1 -1
- package/dist/diagnostics.d.ts.map +1 -1
- package/dist/diagnostics.js.map +1 -1
- package/dist/index.d.ts +12 -10
- package/dist/index.js +6 -5
- package/dist/layers.js +1 -1
- package/dist/mixin.d.ts +29 -1
- package/dist/mixin.d.ts.map +1 -1
- package/dist/mixin.js +11 -3
- package/dist/mixin.js.map +1 -1
- package/dist/pipe.d.ts +26 -1
- package/dist/pipe.d.ts.map +1 -1
- package/dist/pipe.js.map +1 -1
- package/dist/resolver.d.ts +8 -1
- package/dist/resolver.d.ts.map +1 -1
- package/dist/resolver.js +73 -27
- package/dist/resolver.js.map +1 -1
- package/dist/slotView.d.ts +83 -5
- package/dist/slotView.d.ts.map +1 -1
- package/dist/slotView.js +107 -20
- package/dist/slotView.js.map +1 -1
- package/dist/style.d.ts +28 -4
- package/dist/style.d.ts.map +1 -1
- package/dist/style.js +57 -11
- package/dist/style.js.map +1 -1
- package/dist/styleValue.d.ts.map +1 -1
- package/dist/styleValue.js +38 -1
- package/dist/styleValue.js.map +1 -1
- package/dist/testing.d.ts +4 -3
- package/dist/testing.d.ts.map +1 -1
- package/dist/testing.js +2 -1
- package/dist/testing.js.map +1 -1
- package/dist/theme/cssMath.d.ts +1 -1
- package/dist/theme/cssMath.js +1 -0
- package/dist/theme/cssMath.js.map +1 -1
- package/dist/theme/gamut.d.ts +19 -1
- package/dist/theme/gamut.d.ts.map +1 -1
- package/dist/theme/gamut.js +25 -3
- package/dist/theme/gamut.js.map +1 -1
- package/dist/theme/knob.d.ts +2 -0
- package/dist/theme/knob.d.ts.map +1 -1
- package/dist/theme/knob.js +1 -0
- package/dist/theme/knob.js.map +1 -1
- package/dist/theme/knobData.d.ts +1014 -0
- package/dist/theme/knobData.d.ts.map +1 -0
- package/dist/theme/knobData.js +583 -0
- package/dist/theme/knobData.js.map +1 -0
- package/dist/theme/knobDataType.d.ts +20 -0
- package/dist/theme/knobDataType.d.ts.map +1 -0
- package/dist/theme/knobDataType.js +1 -0
- package/dist/theme/knobs.d.ts +62 -62
- package/dist/theme/knobs.d.ts.map +1 -1
- package/dist/theme/knobs.js +61 -61
- package/dist/theme/knobs.js.map +1 -1
- package/dist/theme/oklch.d.ts +8 -0
- package/dist/theme/oklch.d.ts.map +1 -1
- package/dist/theme/oklch.js +20 -8
- package/dist/theme/oklch.js.map +1 -1
- package/dist/theme/raise.d.ts +2 -1
- package/dist/theme/raise.d.ts.map +1 -1
- package/dist/theme/raise.js +3 -2
- package/dist/theme/raise.js.map +1 -1
- package/dist/theme/runtime.d.ts +37 -0
- package/dist/theme/runtime.d.ts.map +1 -0
- package/dist/theme/runtime.js +54 -0
- package/dist/theme/runtime.js.map +1 -0
- package/dist/theme/scheme.d.ts +26 -1
- package/dist/theme/scheme.d.ts.map +1 -1
- package/dist/theme/scheme.js +31 -2
- package/dist/theme/scheme.js.map +1 -1
- package/dist/theme/shadows.d.ts +4 -1
- package/dist/theme/shadows.d.ts.map +1 -1
- package/dist/theme/shadows.js +8 -5
- package/dist/theme/shadows.js.map +1 -1
- package/dist/theme/storageChanges.d.ts +9 -0
- package/dist/theme/storageChanges.d.ts.map +1 -0
- package/dist/theme/storageChanges.js +29 -0
- package/dist/theme/storageChanges.js.map +1 -0
- package/dist/theme/themes.d.ts +3 -26
- package/dist/theme/themes.d.ts.map +1 -1
- package/dist/theme/themes.js +3 -32
- package/dist/theme/themes.js.map +1 -1
- package/dist/theme/tokens.d.ts +2 -0
- package/dist/theme/tokens.d.ts.map +1 -1
- package/dist/theme/tokens.js +4 -2
- package/dist/theme/tokens.js.map +1 -1
- package/dist/theme.d.ts +10 -7
- package/dist/theme.d.ts.map +1 -1
- package/dist/theme.js +7 -7
- package/dist/theme.js.map +1 -1
- package/dist/vite.d.ts +5 -3
- package/dist/vite.d.ts.map +1 -1
- package/dist/vite.js +2 -2
- package/dist/vite.js.map +1 -1
- package/dist/viteFreeze.d.ts +9 -12
- package/dist/viteFreeze.d.ts.map +1 -1
- package/dist/viteFreeze.js +94 -17
- package/dist/viteFreeze.js.map +1 -1
- 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
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
1324
|
-
|
|
1325
|
-
|
|
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`
|