foldkit-mixins-ui 0.3.0 → 0.4.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
@@ -152,6 +152,19 @@ resolved slot arrays
152
152
  The caller never copies Button's internal behavior and never has to know how to
153
153
  merge its handlers/ARIA/structural attributes safely.
154
154
 
155
+ ## Follow the click
156
+
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.
162
+
163
+ Start by adding a class. Then add a non-conflicting attribute if needed.
164
+ 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.
167
+
155
168
  ## What `resolve` does
156
169
 
157
170
  `resolve(attributes, mixins, { input, h })` receives the shaped value the
@@ -254,11 +267,99 @@ adapter.
254
267
  | Dialog | `dialog`, `backdrop`, `panel`, `title`, `description`, `initialFocus`, `closeButton` |
255
268
  | Popover | `button`, `panel`, `backdrop`, `arrow` |
256
269
  | Tooltip | `trigger`, `panel` |
270
+ | HoverIntent | `trigger`, `panel` (open and close delays with intent, for a hover card or a menu) |
257
271
  | Slider | `root`, `track`, `filledTrack`, `thumb`, `label`, `hiddenInput` |
258
272
  | Tabs | `tablist`, `tab`, `panel` |
259
273
  | RadioGroup | `group`, `option`, `label`, `description`, `hiddenInput` |
274
+ | Anchor | a Mount and a Behavior over `@foldkit/ui/anchor`: `Anchor.behavior(Slots)({ floating, config })` positions a floating slot against a button by id |
260
275
  | Calendar | `root`, `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton` |
261
276
 
277
+ ## Recipes
278
+
279
+ The adapters only name slots. `Recipes` gives those slots a look: one
280
+ `Style.recipeFor` per contract (`Button`, `Input`, `Textarea`, `Checkbox`,
281
+ `Switch`, `Dialog`, `Tabs`), built on the tokens of `foldkit-mixins/theme`.
282
+ Select variants, hand the pieces to `Style.forSlots`, and attach the result
283
+ like any other Style:
284
+
285
+ ```ts
286
+ import { Layers, Style } from 'foldkit-mixins'
287
+ import { Theme } from 'foldkit-mixins/theme'
288
+ import { ButtonSlots, Recipes } from 'foldkit-mixins-ui'
289
+
290
+ const DeleteStyle = Style.forSlots(ButtonSlots)(
291
+ Recipes.Button({ tone: 'danger', variant: 'outline', size: 'sm' }),
292
+ )
293
+
294
+ const L = Layers.standard
295
+ const palette = Theme.oklch({ accent: { h: 280, c: 0.15, l: '60%' } })
296
+
297
+ export const sheet = Style.stylesheet(
298
+ L.declare,
299
+ L.in('tokens', Theme.root(Theme.tokens)),
300
+ L.in('theme', Theme.root(palette)),
301
+ DeleteStyle,
302
+ )
303
+ ```
304
+
305
+ `DeleteStyle.mixin` then goes to `Button.resolve` as in the first example.
306
+
307
+ What a recipe assumes and does:
308
+
309
+ - **The page ships the tokens.** Every value is a `var(--fk-…)` reference to
310
+ `Theme.tokens` or a `Theme.oklch` palette, so a scoped theme or a knob
311
+ override restyles every recipe with no new CSS.
312
+ - **Bases sit in `components`, variants in `variants`** of `Layers.standard`,
313
+ so an application's `app` layer overrides both without specificity fights.
314
+ Every declaration is a layered rule and none is inline style, since inline
315
+ style beats every layer and could not be overridden this way:
316
+
317
+ ```ts
318
+ const Red = Style.forSlots(ButtonSlots)(
319
+ { button: Style.self({ background: 'red' }) },
320
+ { layer: L.layer('app') },
321
+ )
322
+ // Style.stylesheet(L.declare, …, DeleteStyle, Red): Red's background wins.
323
+ ```
324
+ - **State comes from the component's own attributes.** Checked, selected, and
325
+ disabled looks read `aria-checked`, `aria-selected`, and `aria-disabled`,
326
+ which `@foldkit/ui` already writes; no `whenInput` is needed.
327
+ - **Tone and variant are independent.** A tone sets a few private custom
328
+ properties that `solid`, `outline`, and `ghost` read.
329
+
330
+ Adjust a recipe with `extend` instead of forking it. Base pieces compose per
331
+ slot, a variant's pieces compose over the shipped ones, and compounds append:
332
+
333
+ ```ts
334
+ const BrandButton = Recipes.Button.extend({
335
+ base: { button: Style.class('brand-button') },
336
+ variants: { size: { lg: { button: Style.class('brand-button-lg') } } },
337
+ })
338
+ ```
339
+
340
+ ## Accessibility patterns
341
+
342
+ Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the
343
+ slots a widget of that kind must publish and what each must expose. The
344
+ catalog lists them with a `tier` (`stateful` for a Submodel, `stateless` for
345
+ a decorated native control), the ARIA `roles` involved, and the platform
346
+ `floor`: what the widget relies on the browser for (`focus-trap`,
347
+ `escape-dismiss`, `top-layer`, `form-submission`, ...), so nothing here
348
+ reimplements it and a reader or an agent can ask.
349
+
350
+ ```ts
351
+ import { A11y } from 'foldkit-mixins'
352
+ import { Patterns } from 'foldkit-mixins-ui'
353
+
354
+ A11y.validate(Patterns.Tabs, MyTabsSlots) // [] when a custom tabs view publishes what tabs need
355
+ Patterns.catalog.find(entry => entry.name === 'dialog')?.floor // ['focus-trap', 'escape-dismiss', ...]
356
+ ```
357
+
358
+ A test iterates the catalog and validates each adapter's own Slots against
359
+ its pattern, so an adapter cannot drift from the contract it claims. The
360
+ patterns are written separately from the Slots, which is what makes the
361
+ check mean something.
362
+
262
363
  ## Why some components cannot be adapted
263
364
 
264
365
  The bridge needs a **consumer-visible attribute bundle**. If a component builds
@@ -270,7 +371,7 @@ They cannot be adapted here without a change to their upstream component API.
270
371
  That is a limitation of the exposed render seam, not of Slot resolution.
271
372
 
272
373
  Other `@foldkit/ui` modules—`Toast`, `FileDrop`, `VirtualList`, `DragAndDrop`,
273
- `Anchor`, `HoverIntent`, and `Animation`—simply do not have adapters here yet.
374
+ and `Animation`—simply do not have adapters here yet.
274
375
  `FileDrop` does expose a render seam, so it is an example that could be added
275
376
  without changing `@foldkit/ui`.
276
377