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 +102 -1
- package/dist/index.d.mts +501 -24
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +812 -14
- package/dist/index.mjs.map +1 -1
- package/package.json +11 -10
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
|
-
|
|
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
|
|