foldkit-mixins-ui 0.4.0 → 0.6.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 CHANGED
@@ -116,14 +116,7 @@ const saveButton = (h: HtmlBuilder<Message>) =>
116
116
  UiButton.view(
117
117
  {
118
118
  onClick: Message.Saved({}),
119
- toView: attributes => {
120
- const slots = Button.resolve(attributes, [SaveStyle.mixin], {
121
- input: undefined,
122
- h,
123
- })
124
-
125
- return h.button(slots.button, ['Save'])
126
- },
119
+ toView: Button.toView([SaveStyle.mixin], { h }, ({ button }) => h.button(button, ['Save'])),
127
120
  },
128
121
  h,
129
122
  )
@@ -132,7 +125,7 @@ const saveButton = (h: HtmlBuilder<Message>) =>
132
125
  The important line is:
133
126
 
134
127
  ```ts
135
- Button.resolve(attributes, [SaveStyle.mixin], { input, h })
128
+ toView: Button.toView(mixins, { h }, draw)
136
129
  ```
137
130
 
138
131
  Conceptually:
@@ -143,10 +136,10 @@ attributes from @foldkit/ui
143
136
  Style / Behavior mixins
144
137
  |
145
138
  v
146
- Button.resolve(...)
139
+ Button.toView(...)
147
140
  |
148
141
  v
149
- resolved slot arrays
142
+ draw(resolved slot arrays)
150
143
  ```
151
144
 
152
145
  The caller never copies Button's internal behavior and never has to know how to
@@ -154,16 +147,126 @@ merge its handlers/ARIA/structural attributes safely.
154
147
 
155
148
  ## Follow the click
156
149
 
157
- `UiButton.view` supplies the component's base attributes, including the click
158
- Message. `Button.resolve` merges the style into those attributes; `h.button`
159
- puts the result on the actual element. Clicking emits `Saved` to the parent
160
- update. The name `Saved` is just the example's Message name—it does not mean
161
- this adapter wrote anything to storage.
150
+ `UiButton.view` builds the component's base attributes, including the click
151
+ Message, and calls `toView` with them. `Button.toView` applies the style to
152
+ those attributes and hands the result to `draw`, which puts it on the actual
153
+ element with `h.button`. Clicking emits `Saved` to the parent update. The name
154
+ `Saved` is just the example's Message name—it does not mean this adapter wrote
155
+ anything to storage.
156
+
157
+ `toView` performs no I/O and holds nothing: it is a pure function from the
158
+ component's bundles to your markup, run on every render.
162
159
 
163
160
  Start by adding a class. Then add a non-conflicting attribute if needed.
164
161
  Do not install another `OnClick` to intercept the component: the resolver
165
- rejects competing event owners. Keep the original component's attributes in
166
- the call to `resolve`, including its child attributes and accessibility state.
162
+ rejects competing event owners. Put every resolved bundle on its element,
163
+ adding your own attributes beside it where you need them:
164
+
165
+ ```ts
166
+ import * as UiInput from '@foldkit/ui/input'
167
+ import { Input, InputSlots } from 'foldkit-mixins-ui'
168
+
169
+ const ZipStyle = Style.forSlots(InputSlots)({ input: Style.class('zip') })
170
+
171
+ const zipInput = (h: HtmlBuilder<Message>) =>
172
+ UiInput.view(
173
+ {
174
+ id: 'zip',
175
+ toView: Input.toView([ZipStyle.mixin], { h }, ({ input }) =>
176
+ h.input([...input, h.Autocomplete('off')]),
177
+ ),
178
+ },
179
+ h,
180
+ )
181
+ ```
182
+
183
+ ## `toView` and `resolve`
184
+
185
+ Every component adapter (all but Anchor, which is a Behavior) has both:
186
+
187
+ ```text
188
+ Adapter.toView(mixins, { h, input? }, draw) -> the component's toView
189
+ Adapter.resolve(attributes, mixins, { h, input? }) -> the resolved bundles
190
+ ```
191
+
192
+ `toView` is `resolve` placed where the component calls back, and is the normal
193
+ path. It fits a stateless component's `view` and a Submodel's `viewInputs`
194
+ alike. The Message type comes from `h`, and a Submodel's value type (a
195
+ RadioGroup's or Tabs' `Value`) from where the `toView` goes, so neither needs
196
+ writing out.
197
+
198
+ A button drawn as a button needs no `draw` at all. `Button.view` takes the
199
+ label, a style, and `@foldkit/ui`'s own config:
200
+
201
+ ```ts
202
+ import { Button } from 'foldkit-mixins-ui'
203
+
204
+ const saveButton = (disabled: boolean, h: HtmlBuilder<Message>) =>
205
+ Button.view(
206
+ {
207
+ label: 'Save',
208
+ style: SaveStyle,
209
+ type: 'submit',
210
+ disabled,
211
+ onClick: Message.Saved(),
212
+ },
213
+ h,
214
+ )
215
+ ```
216
+
217
+ An input or a textarea places its own bundles, so its `view` takes a `draw`.
218
+ `Input.view` and `Textarea.view` take the value and Messages, a style, and
219
+ `@foldkit/ui`'s own config (`type` and `placeholder`, `rows` for a textarea):
220
+
221
+ ```ts
222
+ import { Input } from 'foldkit-mixins-ui'
223
+
224
+ const emailField = (value: string, h: HtmlBuilder<Message>) =>
225
+ Input.view(
226
+ {
227
+ id: 'email',
228
+ value,
229
+ onInput: value => Message.TypedEmail({ value }),
230
+ type: 'email',
231
+ placeholder: 'you@example.com',
232
+ style: FieldStyle,
233
+ draw: ({ input, label }, h) => h.div([], [h.label(label, ['Email']), h.input(input)]),
234
+ },
235
+ h,
236
+ )
237
+ ```
238
+
239
+ `Input.field` and `Textarea.field` draw a whole field from a
240
+ `FieldValidation.Field`: the value, its first error or checking mark as the
241
+ description, and `aria-invalid` where the field is invalid. `changed` maps the
242
+ typed value to a Message; `label` is the text over the control; and `draw`
243
+ places the resolved `label`, `control`, and `description` bundles (the default
244
+ stacks them):
245
+
246
+ ```ts
247
+ import { Input } from 'foldkit-mixins-ui'
248
+
249
+ const titleField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message>) =>
250
+ Input.field(
251
+ { id: 'title', label: 'Title', field, changed: value => Message.TypedTitle({ value }) },
252
+ h,
253
+ )
254
+ ```
255
+
256
+ `resolve` is the seam underneath, for bundles already in hand: a view that
257
+ receives a Tabs `render` as its input, or a Calendar whose Mixins read the
258
+ mode it is showing, which is only known once the attributes arrive:
259
+ ```ts
260
+ import type { CalendarAttributes } from '@foldkit/ui/calendar'
261
+ import { Calendar, CalendarSlots } from 'foldkit-mixins-ui'
262
+
263
+ const CalendarStyle = Style.forSlots(CalendarSlots)({
264
+ root: Style.whenInput<CalendarAttributes['_tag']>(mode => mode === 'Years', Style.class('years')),
265
+ })
266
+
267
+ const resolveCalendar = (attributes: CalendarAttributes, h: HtmlBuilder<Message>) =>
268
+ Calendar.resolve(attributes, [CalendarStyle.mixin], { input: attributes._tag, h })
269
+ ```
167
270
 
168
271
  ## What `resolve` does
169
272
 
@@ -188,11 +291,21 @@ For richer components, non-slot values pass through untouched. Values such as
188
291
  data rather than becoming Mixins slots.
189
292
 
190
293
  `input` is whatever attached Style/Behavior callbacks are allowed to read. In a
191
- feature view that is often the Surface's projected Model; for purely static
192
- styling it can be `undefined`.
193
-
194
- Every adapter is available as both a component namespace (`Button.resolve`,
195
- `Button.ButtonSlots`) and flat Slot exports such as `ButtonSlots`.
294
+ feature view that is often the Surface's projected Model; leave it out when no
295
+ attached Mixin reads one.
296
+
297
+ What `resolve` returns (and `draw` receives) has a name for each adapter:
298
+ `ResolvedButton<Message>`, `ResolvedInput<Message>`, `ResolvedDialog<Message>`,
299
+ `ResolvedRadioGroup<Value, Message>` and `ResolvedRadioOption<Value, Message>`,
300
+ `ResolvedTabs<Value, Message>`, `ResolvedCalendar<Message>`, and so on, so a
301
+ helper that draws part of a component can be typed without `ReturnType`.
302
+ `ResolvedTextarea`'s `textarea` bundle is typed for `h.textarea`, which refuses
303
+ `InnerHTML`; the resolver refuses an `InnerHTML` from any Mixin, so no cast is
304
+ needed.
305
+
306
+ Every adapter is available as both a component namespace (`Button.toView`,
307
+ `Button.resolve`, `Button.ButtonSlots`) and flat Slot exports such as
308
+ `ButtonSlots`.
196
309
 
197
310
  ## What the resolver protects
198
311
 
@@ -278,7 +391,7 @@ adapter.
278
391
 
279
392
  The adapters only name slots. `Recipes` gives those slots a look: one
280
393
  `Style.recipeFor` per contract (`Button`, `Input`, `Textarea`, `Checkbox`,
281
- `Switch`, `Dialog`, `Tabs`), built on the tokens of `foldkit-mixins/theme`.
394
+ `Switch`, `Dialog`, `Tabs`, `Segmented`), built on the tokens of `foldkit-mixins/theme`.
282
395
  Select variants, hand the pieces to `Style.forSlots`, and attach the result
283
396
  like any other Style:
284
397
 
@@ -302,7 +415,7 @@ export const sheet = Style.stylesheet(
302
415
  )
303
416
  ```
304
417
 
305
- `DeleteStyle.mixin` then goes to `Button.resolve` as in the first example.
418
+ `DeleteStyle.mixin` then goes to `Button.toView` as in the first example.
306
419
 
307
420
  What a recipe assumes and does:
308
421
 
@@ -325,7 +438,14 @@ What a recipe assumes and does:
325
438
  disabled looks read `aria-checked`, `aria-selected`, and `aria-disabled`,
326
439
  which `@foldkit/ui` already writes; no `whenInput` is needed.
327
440
  - **Tone and variant are independent.** A tone sets a few private custom
328
- properties that `solid`, `outline`, and `ghost` read.
441
+ properties that `solid`, `outline`, and `ghost` read — except `primary`,
442
+ which is ink by definition, and `icon`, which fixes its own square geometry
443
+ (combine it with `size: null`, since a density would un-square it).
444
+ - **On a colored band, unfilled buttons take the band's color.** `outline` and
445
+ `ghost` draw their text in the tone's ink, which reads on the page's surface
446
+ and not on a band of the accent. A band sets
447
+ `Style.vars({ '--fk-ink': 'currentColor' })`, beside `--fk-heading` for its
448
+ headings, and their text is the band's.
329
449
 
330
450
  Adjust a recipe with `extend` instead of forking it. Base pieces compose per
331
451
  slot, a variant's pieces compose over the shipped ones, and compounds append:
@@ -337,6 +457,64 @@ const BrandButton = Recipes.Button.extend({
337
457
  })
338
458
  ```
339
459
 
460
+ `Recipes.Badge` is a function rather than a variant selection: one style serves
461
+ badges in every state, so every tone is present at once and there is no axis
462
+ to select. It takes the attribute carrying the value and the value-to-tone
463
+ map; values the map leaves out keep the base pill:
464
+
465
+ ```ts
466
+ const EntryStyle = Style.forSlots(EntrySlots)(
467
+ {
468
+ badge: Recipes.Badge({
469
+ attribute: 'data-state',
470
+ tones: { Published: 'success', Changed: 'warning' },
471
+ }).badge,
472
+ },
473
+ )
474
+ ```
475
+
476
+ Like the variant recipes it reads `Theme.tokens` and `Theme.oklch` tokens and
477
+ keeps the base in `components` with each tone in `variants`.
478
+
479
+ `Recipes.Segmented` is a tray of toggle buttons where pressing selects — plain
480
+ buttons, not `Tabs` (the group is `role="group"`, each option `aria-pressed`).
481
+ The pressed option rises from the tray: that rule lives on the group, so icon
482
+ tiles take the group piece alone. `tray` is a muted tray or a plain row (which
483
+ sets no `display`: the Builder owns its narrow tabs' visibility); `size` is
484
+ text density:
485
+
486
+ ```ts
487
+ const SegmentedStyle = Style.forSlots(SegmentedSlots)(
488
+ {
489
+ group: Recipes.Segmented({ tray: 'plain', size: 'sm' }).group ?? Style.empty,
490
+ option: Recipes.Segmented({ tray: 'plain', size: 'sm' }).option ?? Style.empty,
491
+ },
492
+ { layer: L.layer('app') },
493
+ )
494
+ ```
495
+
496
+ ## Mechanisms
497
+
498
+ `Touch` and `Icons` are style mechanisms, not components: no slots, no views.
499
+ Compose them into your own slots. `Touch.target` floors one control at 44px
500
+ where the pointer is coarse; `Touch.targets` floors every boxed control a
501
+ region draws. `Icons.glyph(size)` draws the icon in `--icon` before the
502
+ element's words, and `Icons.byAttribute(attribute, icons)` sets `--icon` from
503
+ an attribute's value, where `icons` maps each value to its resolved `url(…)`:
504
+
505
+ ```ts
506
+ const TileStyle = Style.forSlots(TileSlots)(
507
+ {
508
+ tile: Style.compose(
509
+ Touch.target,
510
+ Icons.glyph('1rem'),
511
+ Icons.byAttribute('data-block', { Hero: iconUrl('hero') }),
512
+ ),
513
+ },
514
+ { layer: L.layer('app') },
515
+ )
516
+ ```
517
+
340
518
  ## Accessibility patterns
341
519
 
342
520
  Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the