foldkit-mixins 0.3.0 → 0.5.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 +459 -10
- package/dist/app.d.mts +46 -0
- package/dist/app.d.mts.map +1 -0
- package/dist/app.mjs +45 -0
- package/dist/app.mjs.map +1 -0
- package/dist/core-Bxj0UQDF.mjs +53 -0
- package/dist/core-Bxj0UQDF.mjs.map +1 -0
- package/dist/core-CUw_n1Nd.d.mts +40 -0
- package/dist/core-CUw_n1Nd.d.mts.map +1 -0
- package/dist/defaults.d.mts +31 -0
- package/dist/defaults.d.mts.map +1 -0
- package/dist/defaults.mjs +75 -0
- package/dist/defaults.mjs.map +1 -0
- package/dist/foundations.d.mts +30 -0
- package/dist/foundations.d.mts.map +1 -0
- package/dist/foundations.mjs +71 -0
- package/dist/foundations.mjs.map +1 -0
- package/dist/index.d.mts +137 -536
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +261 -1017
- package/dist/index.mjs.map +1 -1
- package/dist/layers-B31M0tDi.mjs +193 -0
- package/dist/layers-B31M0tDi.mjs.map +1 -0
- package/dist/layers.d.mts +47 -0
- package/dist/layers.d.mts.map +1 -0
- package/dist/layers.mjs +2 -0
- package/dist/layout.d.mts +114 -0
- package/dist/layout.d.mts.map +1 -0
- package/dist/layout.mjs +154 -0
- package/dist/layout.mjs.map +1 -0
- package/dist/oklch-BxvCD0oi.d.mts +135 -0
- package/dist/oklch-BxvCD0oi.d.mts.map +1 -0
- package/dist/prose.d.mts +30 -0
- package/dist/prose.d.mts.map +1 -0
- package/dist/prose.mjs +61 -0
- package/dist/prose.mjs.map +1 -0
- package/dist/root-C1u12YMD.mjs +37 -0
- package/dist/root-C1u12YMD.mjs.map +1 -0
- package/dist/root-xyWS6geK.d.mts +25 -0
- package/dist/root-xyWS6geK.d.mts.map +1 -0
- package/dist/slotItem-D6_m6IqP.d.mts +18 -0
- package/dist/slotItem-D6_m6IqP.d.mts.map +1 -0
- package/dist/slotMark-Rdsjb7XI.mjs +135 -0
- package/dist/slotMark-Rdsjb7XI.mjs.map +1 -0
- package/dist/slotView-BtIF2pHo.d.mts +476 -0
- package/dist/slotView-BtIF2pHo.d.mts.map +1 -0
- package/dist/style-CKjLee4e.mjs +1266 -0
- package/dist/style-CKjLee4e.mjs.map +1 -0
- package/dist/style-CtCqaL0l.d.mts +182 -0
- package/dist/style-CtCqaL0l.d.mts.map +1 -0
- package/dist/styleValue-BavTe9MZ.d.mts +72 -0
- package/dist/styleValue-BavTe9MZ.d.mts.map +1 -0
- package/dist/styleValue-_G9jwb17.mjs +248 -0
- package/dist/styleValue-_G9jwb17.mjs.map +1 -0
- package/dist/testing.d.mts +30 -0
- package/dist/testing.d.mts.map +1 -0
- package/dist/testing.mjs +167 -0
- package/dist/testing.mjs.map +1 -0
- package/dist/theme.d.mts +193 -0
- package/dist/theme.d.mts.map +1 -0
- package/dist/theme.mjs +146 -0
- package/dist/theme.mjs.map +1 -0
- package/dist/tokens-BR_qxDR7.d.mts +91 -0
- package/dist/tokens-BR_qxDR7.d.mts.map +1 -0
- package/dist/tokens-DteBJVN-.mjs +117 -0
- package/dist/tokens-DteBJVN-.mjs.map +1 -0
- package/dist/utilities.d.mts +73 -0
- package/dist/utilities.d.mts.map +1 -0
- package/dist/utilities.mjs +90 -0
- package/dist/utilities.mjs.map +1 -0
- package/package.json +59 -7
package/README.md
CHANGED
|
@@ -102,6 +102,11 @@ pnpm add foldkit-mixins
|
|
|
102
102
|
`foldkit` and `effect` are peer dependencies. `foldkit-mixins-surface` bridges a Surface
|
|
103
103
|
projection, and `foldkit-mixins-ui` adapts `@foldkit/ui` components.
|
|
104
104
|
|
|
105
|
+
The design-system pieces are subpaths, so an application that only attaches classes pays for
|
|
106
|
+
none of them: `foldkit-mixins/layers`, `/theme`, `/layout`, `/defaults`, `/prose`, `/utilities`
|
|
107
|
+
and `/app` (see
|
|
108
|
+
[styleImprovements-DESIGN.md](../../docs/design/styleImprovements-DESIGN.md)).
|
|
109
|
+
|
|
105
110
|
## Quick start
|
|
106
111
|
|
|
107
112
|
The component author publishes the extension points. Style and Behavior can then be authored
|
|
@@ -161,20 +166,49 @@ const Field = SlotView.forMessages<Message>()
|
|
|
161
166
|
Base attributes, event Messages and any `ChildAttribute` survive. The caller did not copy the
|
|
162
167
|
markup or add a `validationBehavior` prop to the component.
|
|
163
168
|
|
|
169
|
+
### Render it and interpret the result
|
|
170
|
+
|
|
171
|
+
`Field` is a view function. From a parent view with a compatible builder, call
|
|
172
|
+
`Field({ value: model.value, invalid: model.invalid }, h)`. The input's value
|
|
173
|
+
comes from the parent; typing emits `ChangedValue`; the parent update must
|
|
174
|
+
store that value before the next render. Mixins owns none of that state.
|
|
175
|
+
|
|
176
|
+
In this example, `FieldStyle` supplies classes and a grid layout, while
|
|
177
|
+
`Validation` supplies `aria-invalid`. The input's `OnInput` remains owned by
|
|
178
|
+
the base view. Adding another `OnInput` attachment is a conflict, not a way to
|
|
179
|
+
chain a second application update. Compose the action in the existing Message
|
|
180
|
+
handler instead.
|
|
181
|
+
|
|
182
|
+
A Style's compiled rules (`Style.pseudo`, `Style.media`, a layer) arrive with
|
|
183
|
+
the Slot that draws them. In a browser, the first time a Slot draws a class,
|
|
184
|
+
its CSS is appended to one `<style data-foldkit-styles>` element, in the
|
|
185
|
+
microtask after the draw and before the browser paints. The element is made
|
|
186
|
+
only when there is something to add, and declares the standard layer order
|
|
187
|
+
first unless a sheet on the page already declares one, which it leaves alone.
|
|
188
|
+
Classes a stylesheet already on the page carries are left out, so
|
|
189
|
+
installing `Style.stylesheet(...)` yourself (for the first paint, or on the
|
|
190
|
+
server) never duplicates them. Outside a browser nothing is injected: a server
|
|
191
|
+
puts `Style.usedIn(html)`, the CSS of every compiled class the page's markup
|
|
192
|
+
uses, in the page's head (with `foldkit-ssr`, through its `head` option).
|
|
193
|
+
|
|
164
194
|
## What the resolver guarantees
|
|
165
195
|
|
|
166
196
|
Attachments are not concatenated and left to renderer order. The resolver applies explicit rules:
|
|
167
197
|
|
|
168
198
|
- classes are additive and deduplicated into one `Class`;
|
|
169
|
-
- inline styles merge per property,
|
|
199
|
+
- inline styles from Style pieces merge per property, later attachments winning, over the
|
|
200
|
+
view's base; a property a Behavior sets (through `h.Style` in its attributes) has exactly one
|
|
201
|
+
owner, so a Style piece, the base, or a second Behavior setting the same property is an error;
|
|
170
202
|
- an event or scalar attribute has exactly one owner — a second owner is an error;
|
|
171
203
|
- a `ChildAttribute` (a Submodel's published handler) is preserved by identity;
|
|
172
204
|
- `Key` and `InnerHTML` are structural and cannot be overridden;
|
|
173
205
|
- multiple mount contributions compose into exactly one `OnMount`.
|
|
174
206
|
|
|
175
207
|
Conflicts throw `Diagnostics.DiagnosticError` with stable codes such as
|
|
176
|
-
`mixins:event-conflict` and `mixins:protected-attribute`, so tests,
|
|
177
|
-
all speak the same diagnostic language.
|
|
208
|
+
`mixins:event-conflict`, `mixins:style-property-conflict` and `mixins:protected-attribute`, so tests,
|
|
209
|
+
DevTools and editor tooling can all speak the same diagnostic language. The style rule exists
|
|
210
|
+
because a positioning Behavior that writes `top` and a Style that also sets `top` would otherwise
|
|
211
|
+
fight silently, last writer winning.
|
|
178
212
|
|
|
179
213
|
## Slots: the public contract
|
|
180
214
|
|
|
@@ -209,6 +243,21 @@ Names come from the keys passed to `Slots.define`; they are never repeated insid
|
|
|
209
243
|
|
|
210
244
|
Style is pure data. It never touches the DOM.
|
|
211
245
|
|
|
246
|
+
Every piece takes `Declarations`: camelCase CSS properties (typed by
|
|
247
|
+
[`csstype`](https://github.com/frenic/csstype)) and custom properties, each a
|
|
248
|
+
string. A misspelled or kebab-case property in an object literal is a type
|
|
249
|
+
error; the compiler writes the kebab-case name. Values are not checked, so
|
|
250
|
+
`var(...)` and `light-dark(...)` pass through.
|
|
251
|
+
|
|
252
|
+
Wherever a slot's piece is taken (`forSlots`, `slots`, `forCapability`, a
|
|
253
|
+
`recipeFor` definition) and in `compose`, `when`, `whenInput` and `perItem`, a
|
|
254
|
+
piece may also be written short: a declarations object means
|
|
255
|
+
`Style.self(declarations)`, a list means `Style.compose(...list)`, and `{}` is
|
|
256
|
+
`Style.empty`. So `[Style.class('card'), { padding: '1rem' }]` is
|
|
257
|
+
`Style.compose(Style.class('card'), Style.self({ padding: '1rem' }))`. A
|
|
258
|
+
`StyleValue` carries a brand, so a declarations object is never mistaken for
|
|
259
|
+
one.
|
|
260
|
+
|
|
212
261
|
| Primitive | Meaning |
|
|
213
262
|
| --- | --- |
|
|
214
263
|
| `Style.class(...)` | class tokens |
|
|
@@ -216,10 +265,20 @@ Style is pure data. It never touches the DOM.
|
|
|
216
265
|
| `Style.compose(...)` | concatenate classes; later declarations win per property |
|
|
217
266
|
| `Style.when(condition, piece)` | a boolean known at authoring time |
|
|
218
267
|
| `Style.whenInput(predicate, piece)` | a condition read from the view input at render time |
|
|
219
|
-
| `Style.recipe({ base, variants, defaults, compound })` | returns `selection => StyleValue
|
|
220
|
-
| `Style.
|
|
268
|
+
| `Style.recipe({ base, variants, defaults, compound })` | one slot: returns `selection => StyleValue`; every field is optional, so a recipe may be only its base |
|
|
269
|
+
| `Style.recipeFor(Slots)({ base, variants, defaults, compound })` | every slot: returns `selection => StylePieces`; `null` unsets a defaulted axis; `.extend(patch)` merges per slot and refuses a slot the contract lacks |
|
|
270
|
+
| `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 |
|
|
271
|
+
| `Style.forCapability(Slots)(capability, piece)` | one piece for every public slot whose capability satisfies it |
|
|
272
|
+
| `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)) |
|
|
273
|
+
| `Style.install(css)` | in a browser, one `<style>` in the head holding `css`, unless one already holds exactly that text; returns the element |
|
|
274
|
+
| `Style.self` / `pseudo` / `media` / `supports` / `container` / `nest` | rule-based appearance; `self` is a rule on the element's own class (`&{…}`), for declarations a layer must hold |
|
|
221
275
|
| `Style.keyframes` / `global` | class-independent CSS |
|
|
222
|
-
| `Theme.define` / `
|
|
276
|
+
| `Theme.define` / `Theme.ref(theme)` / `variables` | typed tokens; every token as a typed `var(--fk-group-name)` reference (`Theme.ref(theme).surface.base`), built once per theme; the tokens as inline custom properties |
|
|
277
|
+
| `Theme.lightDark(light, dark)` / `Theme.compose(base, over)` | a token that follows the color scheme with CSS `light-dark()`; themes merged at definition time |
|
|
278
|
+
| `Theme.root(theme, { omit?, colorScheme? })` / `Theme.scoped(theme, selector, overrides)` | from `foldkit-mixins/theme`: tokens as `:root` custom properties, or as overrides under a selector; unlayered global pieces for `Style.stylesheet` |
|
|
279
|
+
| `Theme.tokens` / `Theme.oklch(knobs)` / `Theme.breakpointWidths(theme)` | from `foldkit-mixins/theme`: the shipped spacing, type, radius, motion, border and breakpoint scales; a whole palette derived from an accent and a few knobs; the breakpoints as pixel widths for `foldkit-primitives/media` |
|
|
280
|
+
| `Layers.define(names)` / `Layers.standard` | cascade layers as a value: `names`, `declare` (the `@layer …;` statement as a global piece), `in(name, piece)` (a piece's unlayered rules and global CSS inside that layer; what is already layered keeps its layer; a piece wholly in another layer is `style:relayered`) and `layer(name)` (the placement `Style.forSlots(S)(pieces, { layer })` takes, so a slot style is compiled in that layer). A name outside the order is a type error. `standard` is `reset, tokens, theme, defaults, components, layouts, variants, utilities, app`; also under `foldkit-mixins/layers` |
|
|
281
|
+
| `Style.stylesheet(...)` | one `<style>` block from `NamedStyle`s and bare `StyleValue`s: the layer order hoisted first (two different orders is `style:conflicting-layer-order`), then global chunks, then scoped classes, deduplicated. Once an order is declared, a rule outside it is `style:unlayered-rule`, since it would beat every layer; keyframes, font faces and `@property` pass |
|
|
223
282
|
|
|
224
283
|
Rule-based Style compiles to one deterministic class (an FNV-1a hash of canonical rule text) plus
|
|
225
284
|
CSS as data:
|
|
@@ -237,15 +296,234 @@ CardStyle.css
|
|
|
237
296
|
Style.stylesheet(FieldStyle, CardStyle)
|
|
238
297
|
```
|
|
239
298
|
|
|
240
|
-
Equal rules share a class, so server and client derive the same class and CSS.
|
|
241
|
-
`Style.whenInput`
|
|
242
|
-
|
|
299
|
+
Equal rules share a class, so server and client derive the same class and CSS. A rule piece
|
|
300
|
+
inside `Style.whenInput` compiles to its class like any other; the class is static and only its
|
|
301
|
+
presence follows the input, and its CSS is in `Style.stylesheet` whether or not the condition
|
|
302
|
+
ever holds. Drawn, it is injected like any other class.
|
|
303
|
+
|
|
304
|
+
Beyond `self`, `pseudo`, `media`, `supports`, `container` and `nest`, the rule pieces are:
|
|
305
|
+
|
|
306
|
+
- `Style.states({ open: { opacity: '1' } })` compiles to `&[data-state="open"]`, for Behaviors that
|
|
307
|
+
write `data-state`; `whenInput` when the view knows, `states` when the DOM does;
|
|
308
|
+
- `Style.responsive(breakpoints, { md: { display: 'flex' } })`, named breakpoints from the record
|
|
309
|
+
you pass, so a misspelled one is a type error; a breakpoint is a media query or a whole at-rule,
|
|
310
|
+
such as `'@container page (min-width: 48rem)'`;
|
|
311
|
+
- `Style.at('@container builder (max-width: 40rem)', Style.pseudo('[data-open="false"]', { … }))`
|
|
312
|
+
puts a piece's rules inside an at-rule, where no one constructor does; a class, a piece chosen
|
|
313
|
+
when drawn, global CSS or a rule already inside an at-rule throws there;
|
|
314
|
+
- `Style.enter({ opacity: '0' })`, a `@starting-style` rule the element animates from, with
|
|
315
|
+
`Style.allowDiscrete` when `display` takes part;
|
|
316
|
+
- `Style.vars({ '--gap': '1rem' })` and `Style.viewTransitionName('hero')`, declarations;
|
|
317
|
+
- `Style.grid({ areas: [['header', 'header'], ['nav', 'main']], columns, rows, gap })`, a grid
|
|
318
|
+
template with typed areas: `.style` for the container and `.area('main')` for a child, where
|
|
319
|
+
a name the template lacks is a type error and a ragged template raises
|
|
320
|
+
`mixins:ragged-grid-areas`. Both are rules, not inline declarations, so a later layer can
|
|
321
|
+
override the template;
|
|
322
|
+
- `Selector.attr`, `not`, `is`, `child`, `descendant`, `sibling`, `siblings` build the selector
|
|
323
|
+
strings `pseudo` and `nest` take. Each takes a selector list: every top-level selector is
|
|
324
|
+
scoped to the class (`:is(a, b)` is not split), and a selector that writes `&` places the class
|
|
325
|
+
itself (`nest('[data-open] &')`).
|
|
326
|
+
|
|
327
|
+
### Theme from a few knobs
|
|
328
|
+
|
|
329
|
+
`foldkit-mixins/theme` extends the root `Theme` with the pieces a page ships. `Theme.oklch` takes
|
|
330
|
+
an accent color and a few knobs (hue shifts, surface saturation and contrast, a contrast factor,
|
|
331
|
+
feedback hues) and returns typed tokens for surfaces, text, outlines, and the accent, secondary,
|
|
332
|
+
tertiary and feedback families. Only the `knob` group holds literals; every other value is a CSS
|
|
333
|
+
expression over other tokens (`oklch(from …)`, `color-mix()`, `light-dark()`), so the browser does
|
|
334
|
+
the derivation and one knob override recolors everything below it. Each family (`accent`,
|
|
335
|
+
`secondary`, `tertiary`, `success`, `warning`, `error`, `info`) has a fill, `default`, and two
|
|
336
|
+
text colors named for where they go: `on-fill` is text on that fill (near white on a mid accent),
|
|
337
|
+
and `ink` is text in the family's color on the base surface, dark enough to read in a light scheme
|
|
338
|
+
and light enough in a dark one. Colored text is `ink`, never `default`. `Theme.tokens` is the
|
|
339
|
+
non-color scales, with `space` and `radius` multiplied by the `density` and `radius-factor` knobs.
|
|
340
|
+
|
|
341
|
+
A theme reaches the page as pieces, and the page chooses the layers:
|
|
342
|
+
|
|
343
|
+
```ts
|
|
344
|
+
import { Layers, Slot, Slots, Capability, Style } from 'foldkit-mixins'
|
|
345
|
+
import { Theme } from 'foldkit-mixins/theme'
|
|
346
|
+
|
|
347
|
+
const L = Layers.standard
|
|
348
|
+
const theme = Theme.compose(Theme.tokens, Theme.oklch({ accent: { h: 280, c: 0.15, l: '60%' } }))
|
|
349
|
+
const t = Theme.ref(theme) // t.surface.base is 'var(--fk-surface-base)'; a missing name is a type error
|
|
350
|
+
|
|
351
|
+
const PageSlots = Slots.define({ root: Slot.make({ capability: Capability.Container }) })
|
|
352
|
+
// Born in the app layer: the view attaches this same value, so its classes are the sheet's.
|
|
353
|
+
const PageStyle = Style.forSlots(PageSlots)(
|
|
354
|
+
{ root: Style.self({ background: t.surface.base, color: t.text.default }) },
|
|
355
|
+
{ layer: L.layer('app') },
|
|
356
|
+
)
|
|
357
|
+
|
|
358
|
+
export const sheet = Style.stylesheet(
|
|
359
|
+
L.declare,
|
|
360
|
+
L.in('tokens', Theme.root(Theme.tokens)),
|
|
361
|
+
L.in('theme', Theme.root(theme, { omit: Theme.tokens })),
|
|
362
|
+
L.in('theme', Theme.scoped(theme, ':root[data-theme="ocean"]', { knob: { 'accent-h': '215' } })),
|
|
363
|
+
PageStyle,
|
|
364
|
+
)
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
Once the sheet declares an order, every rule in it must sit in one of its layers: an unlayered
|
|
368
|
+
rule would beat all of them, `app` included, so `Style.stylesheet` refuses it with
|
|
369
|
+
`style:unlayered-rule`. A slot style takes its layer when it is compiled, with the `layer`
|
|
370
|
+
option; a layout or recipe it composes keeps the layer it was already given. `L.in` takes only
|
|
371
|
+
bare pieces: a layer is part of a rule's identity, so layering a finished style would copy it
|
|
372
|
+
under new class names that no view attaches.
|
|
373
|
+
|
|
374
|
+
`omit` leaves out the tokens another theme already declared, so the scales go out once in
|
|
375
|
+
`tokens` and the palette once in `theme`. Which theme is active is a Model fact: the view writes
|
|
376
|
+
`data-theme` on the root, and `Theme.scoped` only says what the value means. A scheme the user
|
|
377
|
+
picks works the same way with a `data-color-scheme` selector and a `color-scheme` override; a
|
|
378
|
+
scheme the browser picks needs nothing, because the `light-dark()` values follow it. The palette
|
|
379
|
+
needs relative color syntax and `light-dark()` (Chrome 123, Firefox 128, Safari 17.5).
|
|
380
|
+
|
|
381
|
+
`Style.responsive(Theme.tokens.breakpoint, { md: { … } })` and
|
|
382
|
+
`Theme.breakpointWidths(Theme.tokens)` (for the `Breakpoints` bundle) name the same breakpoints;
|
|
383
|
+
a query that is not a plain `min-width` raises `theme:unparseable-breakpoint`.
|
|
384
|
+
`Theme.inContainer('page', Theme.tokens.breakpoint)` is the same breakpoints measured on the
|
|
385
|
+
container named `page` rather than the window: an editor's preview frame, narrow in a wide
|
|
386
|
+
window, then draws a look as a narrow screen would. An element must be that container
|
|
387
|
+
(`containerType: 'inline-size', containerName: 'page'`).
|
|
388
|
+
|
|
389
|
+
### Layout
|
|
390
|
+
|
|
391
|
+
`foldkit-mixins/layout` ships the common arrangements as pieces: `Layout.stack`, `cluster`,
|
|
392
|
+
`split`, `sidebar`, `switcher`, `reel`, `center`, `frame`, `pad`, and `autoGrid`, plus
|
|
393
|
+
`Layout.intrinsic` (a stack child that keeps its own width) and `Layout.aside` (the sidebar
|
|
394
|
+
child). Each compiles to rule text that is the same for every caller and reads `--fk-l-*`
|
|
395
|
+
variables with token fallbacks; the options only write those variables inline, so ten stacks
|
|
396
|
+
with ten gaps are one rule and ten inline declarations. The pieces are unlayered; put them in
|
|
397
|
+
`layouts`:
|
|
398
|
+
|
|
399
|
+
```ts
|
|
400
|
+
import { Layers, Style } from 'foldkit-mixins'
|
|
401
|
+
import { Layout } from 'foldkit-mixins/layout'
|
|
402
|
+
|
|
403
|
+
const L = Layers.standard
|
|
404
|
+
|
|
405
|
+
const CardStyle = Style.forSlots(CardSlots)({
|
|
406
|
+
root: L.in('layouts', Layout.stack({ gap: 'var(--fk-space-sm)' })),
|
|
407
|
+
actions: L.in('layouts', Layout.cluster({ justify: 'end' })),
|
|
408
|
+
})
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
`split` adapts to its container by default (`container-type: inline-size` and a `@container`
|
|
412
|
+
query); `{ contain: false }` uses `@media` on the viewport instead. Its breakpoint and
|
|
413
|
+
`stack`'s `split` index are in the rule text, because a query cannot read a variable, so each
|
|
414
|
+
distinct value is its own class. `sidebar` and `switcher` are flex math and need no query.
|
|
415
|
+
|
|
416
|
+
### Defaults and prose
|
|
417
|
+
|
|
418
|
+
`foldkit-mixins/defaults` is the baseline plain HTML gets before any slot is styled: `Defaults.reset`
|
|
419
|
+
(box model, media, form-control fonts, reduced motion) and `body`, `headings`, `links`, `code`,
|
|
420
|
+
`controls`, composed as `Defaults.all` (everything except `reset`). Each is element-selector CSS
|
|
421
|
+
under `:where()` over `--fk-*` tokens with a fallback, so a class rule always beats it and it reads
|
|
422
|
+
with or without a theme. Headings are `text-overt` unless a container sets `--fk-heading`: a band
|
|
423
|
+
drawn in its own color writes `Style.vars({ '--fk-heading': 'currentColor' })` and the headings
|
|
424
|
+
inside take its color, with no rule on the heading. `foldkit-mixins-ui`'s unfilled buttons read
|
|
425
|
+
`--fk-ink` the same way. `foldkit-mixins/prose` is the longform contract: `Prose.style({ measure?,
|
|
426
|
+
leading?, rhythm? })` is one class for every caller (the rhythm between unlike elements: heading to
|
|
427
|
+
paragraph, list to paragraph, around figures) whose options are `--fk-prose-*` variables on the
|
|
428
|
+
element. Its measure and line height are a rule reading those variables, so a later layer can
|
|
429
|
+
override them. Both are unlayered; the page places them:
|
|
430
|
+
|
|
431
|
+
```ts
|
|
432
|
+
import { Layers, Style } from 'foldkit-mixins'
|
|
433
|
+
import { Defaults } from 'foldkit-mixins/defaults'
|
|
434
|
+
import { Prose } from 'foldkit-mixins/prose'
|
|
435
|
+
|
|
436
|
+
const L = Layers.standard
|
|
437
|
+
const Article = Style.forSlots(ArticleSlots)({ body: L.in('components', Prose.style({ measure: '60ch' })) })
|
|
438
|
+
|
|
439
|
+
export const sheet = Style.stylesheet(
|
|
440
|
+
L.declare,
|
|
441
|
+
L.in('reset', Defaults.reset),
|
|
442
|
+
L.in('defaults', Defaults.all),
|
|
443
|
+
Article,
|
|
444
|
+
)
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
### An application's own look
|
|
448
|
+
|
|
449
|
+
Everything above serves two kinds of author. A component or design system **publishes** a
|
|
450
|
+
contract (`ButtonSlots`) that others style with `Style.forSlots`. An application mostly styles
|
|
451
|
+
**its own** markup: Slots nobody else attaches to, one theme, one layer, one page sheet. For
|
|
452
|
+
that case the contract, the style and the setup can each be written once:
|
|
453
|
+
|
|
454
|
+
| You are... | Use |
|
|
455
|
+
| --- | --- |
|
|
456
|
+
| styling a contract someone published | `Style.forSlots(ButtonSlots)(pieces, options)` |
|
|
457
|
+
| declaring your own Slots and their look | `Style.slots(pieces, options)` |
|
|
458
|
+
| fixing theme, `app` layer and page sheet for one application | `AppStyle.make` from `foldkit-mixins/app` |
|
|
459
|
+
| writing a token-backed declaration in a word | `Utilities` from `foldkit-mixins/utilities` |
|
|
460
|
+
|
|
461
|
+
```ts
|
|
462
|
+
import { Event, Style, SlotView } from 'foldkit-mixins'
|
|
463
|
+
import { AppStyle } from 'foldkit-mixins/app'
|
|
464
|
+
import { Theme } from 'foldkit-mixins/theme'
|
|
465
|
+
import { Utilities as U } from 'foldkit-mixins/utilities'
|
|
466
|
+
|
|
467
|
+
// The theme over Theme.tokens, its references, the app layer and the page sheet.
|
|
468
|
+
const { t, slots, forSlots, stylesheet } = AppStyle.make({
|
|
469
|
+
palette: Theme.oklch({ accent: { h: 260, c: 0.21, l: '62%' } }),
|
|
470
|
+
colorScheme: 'light',
|
|
471
|
+
})
|
|
472
|
+
|
|
473
|
+
// Each key is a Container slot with that piece; Style.slot gives a slot options.
|
|
474
|
+
export const Page = slots({
|
|
475
|
+
root: [U.p('lg'), U.bg('surface.base')],
|
|
476
|
+
count: [U.textCenter, U.font('bold'), { fontSize: '3.75rem', color: t.text.default }],
|
|
477
|
+
form: Style.slot({ events: [Event.Submit] }, [U.flex, U.gap('sm')]),
|
|
478
|
+
})
|
|
479
|
+
|
|
480
|
+
export const Counter = SlotView.forMessages<never>()
|
|
481
|
+
.define(Page.slots, (count: number, slots, h) =>
|
|
482
|
+
h.main(slots.root.attrs(), [h.p(slots.count.attrs(), [String(count)])]),
|
|
483
|
+
)
|
|
484
|
+
.pipe(Style.attach(Page.style))
|
|
485
|
+
|
|
486
|
+
// In the browser entry, before the application runs:
|
|
487
|
+
Style.install(stylesheet)
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
A published contract takes the same layer through the kit's `forSlots`, as
|
|
491
|
+
`forSlots(ButtonSlots)(Recipes.Button())` with `foldkit-mixins-ui`.
|
|
492
|
+
|
|
493
|
+
What each call does, and does not do:
|
|
494
|
+
|
|
495
|
+
- `AppStyle.make` computes, once: `theme` is `Theme.compose(Theme.tokens, palette)`, `t` is
|
|
496
|
+
`Theme.ref(theme)`, `L` is `Layers.standard`, and `stylesheet` is the text of the layer order,
|
|
497
|
+
`Defaults.reset`, the tokens, the palette and `Defaults.body` (plus any `global` pieces, in the
|
|
498
|
+
`defaults` layer). It installs nothing and owns no state; a scheme or theme the user picks is
|
|
499
|
+
still a Model fact (see [Theme from a few knobs](#theme-from-a-few-knobs)).
|
|
500
|
+
- `slots(pieces)` is `Style.slots(pieces, { layer: L.layer('app') })`, and `forSlots` is
|
|
501
|
+
`Style.forSlots` with the same layer: the options take a `name`, never a layer. Both
|
|
502
|
+
compile once, where they are defined.
|
|
503
|
+
- `Style.slots` returns `{ slots, style }`: `slots` is the contract (`Slots.define` of a
|
|
504
|
+
`Container` per key, or the `Style.slot` options, which default to `Container` too and are
|
|
505
|
+
never `hidden`), and `style` the `NamedStyle` a view attaches. A slot with no look takes `{}`.
|
|
506
|
+
The view still decides the markup; the contract only names what it may draw.
|
|
507
|
+
- `Style.install(stylesheet)` is the one call that touches the DOM. The sheet holds no slot
|
|
508
|
+
class: a Slot's CSS is injected when it first draws.
|
|
509
|
+
|
|
510
|
+
`Utilities` are one-idea pieces whose steps are the shipped scales' token names, so an invalid
|
|
511
|
+
step is a type error and the value still follows the `density` knob and theme overrides:
|
|
512
|
+
`p`, `px`, `py`, `m`, `mx`, `my`, `gap` (a `space` step or `'0'`; margins also `'auto'`), `text`
|
|
513
|
+
(`size`), `font` (`weight`), `leading`, `rounded` (`radius`), `color` and `bg` (a `Theme.oklch`
|
|
514
|
+
color as `'group.name'`), `items` and `justify` (`'between'` is `space-between`), and the
|
|
515
|
+
constants `flex`, `column`, `grid`, `block`, `hidden`, `wFull`, `textCenter`, `uppercase`,
|
|
516
|
+
`truncate`, `pointer` and `selectNone`. Each is a `Style.self` rule, unlayered, so it takes the
|
|
517
|
+
layer of the style it is composed into, and a plain declaration after it wins per property. A
|
|
518
|
+
value off the scale is a plain declaration (`{ fontSize: '3.75rem' }`); a color outside
|
|
519
|
+
`Theme.oklch`'s groups is read through `t`.
|
|
243
520
|
|
|
244
521
|
## Behavior: reusable element-level interaction
|
|
245
522
|
|
|
246
523
|
A Behavior is a reusable bundle of element-level interaction that does **not** own application
|
|
247
524
|
state. Its attributes are built while resolving from the view's `input` and `h`, so it can only
|
|
248
|
-
emit Messages from the view's own Message universe.
|
|
525
|
+
emit Messages from the view's own Message universe. Like an agent capability,
|
|
526
|
+
a Behavior points one way — toward a Message — and never gets a Model setter.
|
|
249
527
|
|
|
250
528
|
```ts
|
|
251
529
|
const Focus = Behavior.forSlots(FieldSlots)<FieldInput, Message>({
|
|
@@ -261,6 +539,73 @@ const Focus = Behavior.forSlots(FieldSlots)<FieldInput, Message>({
|
|
|
261
539
|
`Event.Click` cannot attach to a slot that did not publish click. Multiple mount contributions
|
|
262
540
|
compose into one `OnMount` per element.
|
|
263
541
|
|
|
542
|
+
A slot rendered once per item (rows, tabs, options) tells the Behavior which repetition it is
|
|
543
|
+
resolving through the second argument of `attrs`:
|
|
544
|
+
|
|
545
|
+
```ts
|
|
546
|
+
h.ul(slots.list.attrs(), items.map((item, index) =>
|
|
547
|
+
h.li(slots.row.attrs([h.Key(item.id)], { index, id: item.id, count: items.length }), [item.label]),
|
|
548
|
+
))
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
The Behavior receives it as `item` (`{ index, id?, count? }`) in `attributes` and as the second
|
|
552
|
+
argument of `mount`, so one Behavior can write `tabindex="0"` on the current row and `-1` on the
|
|
553
|
+
rest, or `aria-posinset` and `aria-setsize` on each. Without an item argument, `item` is
|
|
554
|
+
`undefined` and the Behavior decorates the slot as a single element.
|
|
555
|
+
|
|
556
|
+
### Ready-made Behaviors
|
|
557
|
+
|
|
558
|
+
`Behaviors` holds Behaviors that own no state. The first is `Collection`: describe the parent's
|
|
559
|
+
array once, and a view and the Behaviors on it agree about identity, order, and disabled items.
|
|
560
|
+
|
|
561
|
+
```ts
|
|
562
|
+
import { Behaviors } from 'foldkit-mixins'
|
|
563
|
+
|
|
564
|
+
const items = Behaviors.Collection.of(input.tools, {
|
|
565
|
+
id: tool => tool.id,
|
|
566
|
+
disabled: tool => tool.disabled,
|
|
567
|
+
}) // ids, size, at, indexOf, isDisabled, enabled, slotItem
|
|
568
|
+
|
|
569
|
+
const Ids = Behaviors.Collection.behavior(ToolbarSlots)<ToolbarInput, Message>({
|
|
570
|
+
item: 'tool',
|
|
571
|
+
items: input => Behaviors.Collection.of(input.tools, { id: tool => tool.id }),
|
|
572
|
+
posInSet: true,
|
|
573
|
+
})
|
|
574
|
+
|
|
575
|
+
// in the view: slots.tool.attrs([h.Key(tool.id)], items.slotItem(index))
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
`of` is pure and refuses two items with one id (`mixins:duplicate-item-id`), since an id is what
|
|
579
|
+
`aria-activedescendant` and `aria-controls` rely on. The Behavior writes `id`, `aria-disabled`,
|
|
580
|
+
and with `posInSet` `aria-posinset` and `aria-setsize`, reading the item context the view passes;
|
|
581
|
+
it contributes nothing to a slot resolved without one. Behaviors that need state, such as a
|
|
582
|
+
roving tab stop or a press, live in `foldkit-primitives` as a Bundle plus its Behavior.
|
|
583
|
+
|
|
584
|
+
Four more stateless Behaviors say a parent's state in ARIA, so a custom view
|
|
585
|
+
gets it right without hand-writing it. Each takes slot names and functions of
|
|
586
|
+
the view's input; none owns anything.
|
|
587
|
+
|
|
588
|
+
- `Behaviors.Disclosure.behavior(Slots)<Input, Message>({ trigger, content, open, id })`
|
|
589
|
+
writes `aria-expanded` and `aria-controls` on the trigger, `id` and `hidden`
|
|
590
|
+
on the content. The floor is `<details>`.
|
|
591
|
+
- `Behaviors.ToggleState.behavior(Slots)({ control, state, as: 'checked' | 'pressed' })`
|
|
592
|
+
writes `aria-checked` (checkbox, switch, radio, option) or `aria-pressed` (a
|
|
593
|
+
toggle button) from a `boolean | 'mixed'`.
|
|
594
|
+
- `Behaviors.FieldAssociation.behavior(Slots)({ control, label, description?, error?, id, invalid?, required? })`
|
|
595
|
+
derives `<id>`, `<id>-label`, `<id>-description`, `<id>-error` from one base
|
|
596
|
+
id (`FieldAssociation.ids(id)` for a view that renders them itself) and
|
|
597
|
+
writes `id`, `for`, `aria-labelledby`, `aria-describedby` (the error joins
|
|
598
|
+
while `invalid`), `aria-invalid`, `aria-required`. Derived, not minted, so a
|
|
599
|
+
resumed page and a test agree.
|
|
600
|
+
- `Behaviors.SpinValue.behavior(Slots)({ control, value, onChange, min?, max?, step?, page?, text? })`
|
|
601
|
+
writes the `spinbutton` role and `aria-value*`, and steps the parent's number
|
|
602
|
+
with ArrowUp and ArrowDown by `step`, PageUp and PageDown by `page` (default
|
|
603
|
+
ten steps), Home and End to the bounds, clamped and default-prevented;
|
|
604
|
+
`SpinValue.spin(value, key, modifiers, bounds)` is the pure step. A
|
|
605
|
+
press-and-hold repeat and the wheel are not handled: Foldkit's wheel
|
|
606
|
+
attribute carries no delta, and a repeat is a timer the Model would own.
|
|
607
|
+
|
|
608
|
+
|
|
264
609
|
## SlotView
|
|
265
610
|
|
|
266
611
|
`SlotView.define(slots, render)` is a pure view that publishes slots. Attach with
|
|
@@ -279,6 +624,72 @@ For per-item groups such as tabs, options or calendar cells, use
|
|
|
279
624
|
`SlotView.buildersFor(slots, mixins, { input, h })` and map the items yourself. One contribution
|
|
280
625
|
then applies to every item while each item's base attributes retain their own event ownership.
|
|
281
626
|
|
|
627
|
+
### Parts: redraw only what changed
|
|
628
|
+
|
|
629
|
+
A SlotView runs whole on every change to its input. A larger view can be cut
|
|
630
|
+
into parts, each declaring the input keys it reads and given only those. A part
|
|
631
|
+
runs again only when one of those values changed by identity; otherwise
|
|
632
|
+
Foldkit reuses its last drawing without diffing it.
|
|
633
|
+
|
|
634
|
+
```ts
|
|
635
|
+
type Input = { readonly title: string; readonly count: number }
|
|
636
|
+
const Parts = SlotView.parts(PanelSlots)<Input, Message>()
|
|
637
|
+
|
|
638
|
+
const Title = Parts.part('Title', { reads: ['title'] }, (input, slots, h) =>
|
|
639
|
+
h.h2(slots.title.attrs(), [input.title]),
|
|
640
|
+
)
|
|
641
|
+
const Count = Parts.part('Count', { reads: ['count'] }, (input, slots, h) =>
|
|
642
|
+
h.p(slots.count.attrs(), [String(input.count)]),
|
|
643
|
+
)
|
|
644
|
+
const Panel = Parts.assemble((input, slots, h, draw) =>
|
|
645
|
+
h.section(slots.root.attrs(), [draw(Title), draw(Count)]),
|
|
646
|
+
)
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
`input.count` inside `Title` does not compile, so a part cannot read a value it
|
|
650
|
+
is not redrawn for. `Panel` is an ordinary SlotView: Styles and Behaviors attach
|
|
651
|
+
to it and reach every part's Slots.
|
|
652
|
+
|
|
653
|
+
- **A part's own Behaviors** go in its `behaviors` option, declared over the
|
|
654
|
+
part's selection (`Pick<Input, 'count'>`), and are resolved against it.
|
|
655
|
+
- **A Mixin attached to the whole view that reads the input** (a Behavior's
|
|
656
|
+
`attributes`, `Style.whenInput`) is resolved against the whole input, so the
|
|
657
|
+
parts it reaches are drawn again on every change: correct, not cached. Static
|
|
658
|
+
Styles cost nothing.
|
|
659
|
+
- **Memoizing needs a running application.** Drawn inert (a test, a server's
|
|
660
|
+
first pass), every part is drawn afresh.
|
|
661
|
+
|
|
662
|
+
A Slot drawn once per item can memoize each item, in a part or any SlotView:
|
|
663
|
+
|
|
664
|
+
```ts
|
|
665
|
+
const drawRow = (
|
|
666
|
+
slots: SlotView.SlotBuilders<typeof ListSlots, Message>,
|
|
667
|
+
h: HtmlBuilder<Message>,
|
|
668
|
+
{ index, text }: { readonly index: number; readonly text: string },
|
|
669
|
+
) => h.li(slots.row.attrs([h.Key(text)], { index, id: text }), [text])
|
|
670
|
+
|
|
671
|
+
const Rows = ListParts.part('Rows', { reads: ['rows'] }, (input, slots, h) =>
|
|
672
|
+
h.ul(
|
|
673
|
+
slots.root.attrs(),
|
|
674
|
+
input.rows.map((text, index) => slots.row.lazy({ index, id: text }, drawRow, { index, text })),
|
|
675
|
+
),
|
|
676
|
+
)
|
|
677
|
+
```
|
|
678
|
+
|
|
679
|
+
An item is drawn again only when one of its arguments changed by identity, or
|
|
680
|
+
when a Mixin gave the Slots it used something different for it (a static Style
|
|
681
|
+
by identity, so two views apart only by a Style draw their rows apart). A Behavior
|
|
682
|
+
that works out a roving tab stop from the whole list redraws the row the stop
|
|
683
|
+
left and the row it reached, and no other. `drawRow` reads only its arguments,
|
|
684
|
+
so define it once, not per render. A Mixin that gives an item a handler made per
|
|
685
|
+
render, and an item drawing that holds another, are drawn every time: correct,
|
|
686
|
+
not cached.
|
|
687
|
+
Items are remembered by key for the life of the page, as Foldkit's keyed memo
|
|
688
|
+
is, so key by something bounded (a node id), not by something that keeps
|
|
689
|
+
changing (a search's results). The memo is one per drawing function: two views
|
|
690
|
+
drawing the same key with one `drawRow` share it, and each misses whenever
|
|
691
|
+
what it gives the row differs from the other's. Drawn inert, nothing is kept.
|
|
692
|
+
|
|
282
693
|
## With `foldkit-surface`
|
|
283
694
|
|
|
284
695
|
Mixins do not require Surface, but the two fit naturally: Surface says **what a feature may
|
|
@@ -353,6 +764,44 @@ Attributes.find(input, 'Class')?.value // 'field-input'
|
|
|
353
764
|
Attributes.find(input, 'AriaInvalid')?.value // true
|
|
354
765
|
```
|
|
355
766
|
|
|
767
|
+
What a whole view draws is read with `Inert` from `foldkit-mixins/testing`: `Inert.all`,
|
|
768
|
+
`children`, `byTag`, `byRole`, `byLabel` (by `aria-label`, a `<label for>`, or the innermost
|
|
769
|
+
element with that text), `text`, `value` (an attribute or a property, whichever the builder
|
|
770
|
+
wrote, so `title` and `value` need no special case), `classes`, `style` and `pressed` (an
|
|
771
|
+
`Option`, none for a button that is not a toggle).
|
|
772
|
+
|
|
773
|
+
```ts
|
|
774
|
+
import { Inert } from 'foldkit-mixins/testing'
|
|
775
|
+
|
|
776
|
+
const root = Probe({ value: 'Ada', invalid: false }, SlotView.inertBuilder<Message>())
|
|
777
|
+
Inert.value(Inert.byTag(root, 'input')[0], 'value') // 'Ada'
|
|
778
|
+
```
|
|
779
|
+
|
|
780
|
+
`Inert.draw(view, input)` draws a SlotView with every element a Slot draws marked with the
|
|
781
|
+
Slot's name, however deeply its views nest; a view drawn for real is never marked. It draws
|
|
782
|
+
under a Foldkit Scene's render frame, so a view that embeds a Submodel with `h.submodel`
|
|
783
|
+
(every `@foldkit/ui` component page) draws whole, `childAttributes` included; nothing is
|
|
784
|
+
dispatched, and no Command or Mount it declares runs or is checked. On that tree,
|
|
785
|
+
`Inert.bySlot(root, 'input')` finds a Slot's elements, `Inert.unslotted(root, { inside })` lists
|
|
786
|
+
every element no Slot drew (skipping what a Slot named in `inside` holds, such as a canvas drawing
|
|
787
|
+
the application's page), and `Inert.fixedInline(root, { inside })` every inline declaration that
|
|
788
|
+
is not a custom property. A package view's test expects both lists to be empty.
|
|
789
|
+
|
|
790
|
+
`Inert.css(nodes)` is the compiled CSS behind the nodes' classes, and
|
|
791
|
+
`Inert.missingTokens(root, stylesheet)` lists the `--fk-*` tokens the drawn Styles read with no
|
|
792
|
+
fallback that nothing defines (not the sheet, not a drawn rule, not an inline style), each of
|
|
793
|
+
which makes its declaration invalid in a browser. The two checks every application view test
|
|
794
|
+
repeats are then:
|
|
795
|
+
|
|
796
|
+
```ts
|
|
797
|
+
const tree = Inert.draw(Counter, 0)
|
|
798
|
+
expect(Inert.unslotted(tree)).toEqual([])
|
|
799
|
+
expect(Inert.missingTokens(tree, stylesheet)).toEqual([])
|
|
800
|
+
```
|
|
801
|
+
|
|
802
|
+
A tree whose Styles read no token passes the second vacuously; assert that
|
|
803
|
+
`Inert.css(Inert.all(tree))` contains `var(--fk-` where that would be a mistake.
|
|
804
|
+
|
|
356
805
|
## `@foldkit/ui`
|
|
357
806
|
|
|
358
807
|
`foldkit-mixins-ui` adapts `@foldkit/ui` components that expose attribute bundles or a consumer
|
package/dist/app.d.mts
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { o as StyleValue } from "./styleValue-BavTe9MZ.mjs";
|
|
2
|
+
import { standard } from "./layers.mjs";
|
|
3
|
+
import { a as NamedStyle, c as StyleOptions, l as StylePieces, n as Declared, r as DeclaredPieces } from "./style-CtCqaL0l.mjs";
|
|
4
|
+
import { a as compose, r as ThemeTokens, t as Refs } from "./core-CUw_n1Nd.mjs";
|
|
5
|
+
import { n as RootOptions } from "./root-xyWS6geK.mjs";
|
|
6
|
+
import { t as Tokens } from "./tokens-BR_qxDR7.mjs";
|
|
7
|
+
//#region src/app.d.ts
|
|
8
|
+
export interface AppStyleOptions<Palette extends ThemeTokens> {
|
|
9
|
+
/** The application's own tokens, usually `Theme.oklch(…)`, laid over `Theme.tokens`. */
|
|
10
|
+
readonly palette: Palette;
|
|
11
|
+
/** The page's `color-scheme`; `'light'` keeps a light page light in a dark browser. Default `'light dark'`. */
|
|
12
|
+
readonly colorScheme?: NonNullable<RootOptions['colorScheme']>;
|
|
13
|
+
/**
|
|
14
|
+
* More page-wide pieces after `Defaults.body`, such as `Defaults.headings`,
|
|
15
|
+
* keyframes or a font face, placed in the `defaults` layer.
|
|
16
|
+
*/
|
|
17
|
+
readonly global?: ReadonlyArray<StyleValue>;
|
|
18
|
+
}
|
|
19
|
+
/** A style's options with its layer fixed to the application's. */
|
|
20
|
+
export type AppStyleOptionsFor = Omit<StyleOptions, 'layer'>;
|
|
21
|
+
export interface AppStyle<Palette extends ThemeTokens> {
|
|
22
|
+
/** `Theme.tokens` with the palette over it. */
|
|
23
|
+
readonly theme: ReturnType<typeof compose<Tokens, Palette>>;
|
|
24
|
+
/** Every token of `theme` as a typed `var(--fk-…)` reference. */
|
|
25
|
+
readonly t: Refs<ReturnType<typeof compose<Tokens, Palette>>>;
|
|
26
|
+
/** The layer order the stylesheet declares, for placing a layout or recipe (`L.in('layouts', …)`). */
|
|
27
|
+
readonly L: typeof standard;
|
|
28
|
+
/** `Style.slots` in the `app` layer: the application's own Slots, declared by their style. */
|
|
29
|
+
readonly slots: <S>(pieces: DeclaredPieces<S>, options?: AppStyleOptionsFor) => Declared<S>;
|
|
30
|
+
/** `Style.forSlots` in the `app` layer: a published contract (`ButtonSlots`) styled for this application. */
|
|
31
|
+
readonly forSlots: <Slots>(contract: Slots) => (pieces: StylePieces<Slots>, options?: AppStyleOptionsFor) => NamedStyle<Slots>;
|
|
32
|
+
/** The page sheet: the layer order, reset, tokens, palette, `Defaults.body` and `global`. */
|
|
33
|
+
readonly stylesheet: string;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* The application's theme, layer and page stylesheet:
|
|
37
|
+
* `const { t, slots, stylesheet } = AppStyle.make({ palette: Theme.oklch({ … }) })`.
|
|
38
|
+
* Slot styles are no longer in the stylesheet: a Slot injects its classes' CSS
|
|
39
|
+
* when it first draws them.
|
|
40
|
+
*/
|
|
41
|
+
export declare const make: <Palette extends ThemeTokens>(options: AppStyleOptions<Palette>) => AppStyle<Palette>;
|
|
42
|
+
export declare const AppStyle: {
|
|
43
|
+
readonly make: <Palette extends ThemeTokens>(options: AppStyleOptions<Palette>) => AppStyle<Palette>;
|
|
44
|
+
};
|
|
45
|
+
//#endregion
|
|
46
|
+
//# sourceMappingURL=app.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"app.d.mts","names":[],"sources":["../src/app.ts"],"mappings":";;;;;;;iBAwBiB,gBAAgB,gBAAgB;;WAEtC,SAAS;;WAET,cAAc,YAAY;;;;;WAK1B,SAAS,cAAc;;;YAItB,qBAAqB,KAAK;iBAErB,SAAS,gBAAgB;;WAE/B,OAAO,kBAAkB,QAAc,QAAQ;;WAE/C,GAAG,KAAK,kBAAkB,QAAc,QAAQ;;WAEhD,UAAU;;WAEV,QAAQ,GAAG,QAAQ,eAAe,IAAI,UAAU,uBAAuB,SAAS;;WAEhF,WAAW,OAClB,UAAU,WACN,QAAQ,YAAY,QAAQ,UAAU,uBAAuB,WAAW;;WAErE;;;;;;;;qBAWE,OAAQ,gBAAgB,aACnC,SAAS,gBAAgB,aACxB,SAAS;qBAuBC;WAzBQ,OAAA,gBAAgB,aAAW,SACrC,gBAAgB,aACxB,SAAS"}
|
package/dist/app.mjs
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { i as stylesheet, n as forSlots, r as slots } from "./style-CKjLee4e.mjs";
|
|
2
|
+
import { i as compose } from "./styleValue-_G9jwb17.mjs";
|
|
3
|
+
import { r as standard } from "./layers-B31M0tDi.mjs";
|
|
4
|
+
import { o as ref, r as compose$1 } from "./core-Bxj0UQDF.mjs";
|
|
5
|
+
import { t as root } from "./root-C1u12YMD.mjs";
|
|
6
|
+
import { r as tokens } from "./tokens-DteBJVN-.mjs";
|
|
7
|
+
import { body, reset } from "./defaults.mjs";
|
|
8
|
+
//#region src/app.ts
|
|
9
|
+
/**
|
|
10
|
+
* `foldkit-mixins/app`: an application's style setup, fixed once. Every
|
|
11
|
+
* application on the standard layers writes the same preamble: a theme over
|
|
12
|
+
* `Theme.tokens`, its references, the `app` layer passed to each style, and a
|
|
13
|
+
* page stylesheet of the layer order, the reset, the tokens, the palette and
|
|
14
|
+
* the body defaults. `AppStyle.make` is that preamble as a value.
|
|
15
|
+
*/
|
|
16
|
+
const app = standard.layer("app");
|
|
17
|
+
/**
|
|
18
|
+
* The application's theme, layer and page stylesheet:
|
|
19
|
+
* `const { t, slots, stylesheet } = AppStyle.make({ palette: Theme.oklch({ … }) })`.
|
|
20
|
+
* Slot styles are no longer in the stylesheet: a Slot injects its classes' CSS
|
|
21
|
+
* when it first draws them.
|
|
22
|
+
*/
|
|
23
|
+
const make = (options) => {
|
|
24
|
+
const theme = compose$1(tokens, options.palette);
|
|
25
|
+
const scheme = options.colorScheme === void 0 ? {} : { colorScheme: options.colorScheme };
|
|
26
|
+
return Object.freeze({
|
|
27
|
+
theme,
|
|
28
|
+
t: ref(theme),
|
|
29
|
+
L: standard,
|
|
30
|
+
slots: (pieces, styleOptions) => slots(pieces, {
|
|
31
|
+
...styleOptions,
|
|
32
|
+
layer: app
|
|
33
|
+
}),
|
|
34
|
+
forSlots: (contract) => (pieces, styleOptions) => forSlots(contract)(pieces, {
|
|
35
|
+
...styleOptions,
|
|
36
|
+
layer: app
|
|
37
|
+
}),
|
|
38
|
+
stylesheet: stylesheet(standard.declare, standard.in("reset", reset), standard.in("tokens", root(tokens, scheme)), standard.in("theme", root(options.palette, scheme)), standard.in("defaults", compose(body, ...options.global ?? [])))
|
|
39
|
+
});
|
|
40
|
+
};
|
|
41
|
+
const AppStyle = { make };
|
|
42
|
+
//#endregion
|
|
43
|
+
export { AppStyle, make };
|
|
44
|
+
|
|
45
|
+
//# sourceMappingURL=app.mjs.map
|
package/dist/app.mjs.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"app.mjs","names":["composeThemes"],"sources":["../src/app.ts"],"sourcesContent":["/**\n * `foldkit-mixins/app`: an application's style setup, fixed once. Every\n * application on the standard layers writes the same preamble: a theme over\n * `Theme.tokens`, its references, the `app` layer passed to each style, and a\n * page stylesheet of the layer order, the reset, the tokens, the palette and\n * the body defaults. `AppStyle.make` is that preamble as a value.\n */\nimport { body, reset } from './defaults.js'\nimport { standard } from './layers.js'\nimport {\n forSlots,\n slots,\n stylesheet,\n type Declared,\n type DeclaredPieces,\n type NamedStyle,\n type StyleOptions,\n type StylePieces,\n} from './style.js'\nimport { compose, type StyleValue } from './styleValue.js'\nimport { compose as composeThemes, ref, type Refs, type ThemeTokens } from './theme/core.js'\nimport { root, type RootOptions } from './theme/root.js'\nimport { tokens, type Tokens } from './theme/tokens.js'\n\nexport interface AppStyleOptions<Palette extends ThemeTokens> {\n /** The application's own tokens, usually `Theme.oklch(…)`, laid over `Theme.tokens`. */\n readonly palette: Palette\n /** The page's `color-scheme`; `'light'` keeps a light page light in a dark browser. Default `'light dark'`. */\n readonly colorScheme?: NonNullable<RootOptions['colorScheme']>\n /**\n * More page-wide pieces after `Defaults.body`, such as `Defaults.headings`,\n * keyframes or a font face, placed in the `defaults` layer.\n */\n readonly global?: ReadonlyArray<StyleValue>\n}\n\n/** A style's options with its layer fixed to the application's. */\nexport type AppStyleOptionsFor = Omit<StyleOptions, 'layer'>\n\nexport interface AppStyle<Palette extends ThemeTokens> {\n /** `Theme.tokens` with the palette over it. */\n readonly theme: ReturnType<typeof composeThemes<Tokens, Palette>>\n /** Every token of `theme` as a typed `var(--fk-…)` reference. */\n readonly t: Refs<ReturnType<typeof composeThemes<Tokens, Palette>>>\n /** The layer order the stylesheet declares, for placing a layout or recipe (`L.in('layouts', …)`). */\n readonly L: typeof standard\n /** `Style.slots` in the `app` layer: the application's own Slots, declared by their style. */\n readonly slots: <S>(pieces: DeclaredPieces<S>, options?: AppStyleOptionsFor) => Declared<S>\n /** `Style.forSlots` in the `app` layer: a published contract (`ButtonSlots`) styled for this application. */\n readonly forSlots: <Slots>(\n contract: Slots,\n ) => (pieces: StylePieces<Slots>, options?: AppStyleOptionsFor) => NamedStyle<Slots>\n /** The page sheet: the layer order, reset, tokens, palette, `Defaults.body` and `global`. */\n readonly stylesheet: string\n}\n\nconst app = standard.layer('app')\n\n/**\n * The application's theme, layer and page stylesheet:\n * `const { t, slots, stylesheet } = AppStyle.make({ palette: Theme.oklch({ … }) })`.\n * Slot styles are no longer in the stylesheet: a Slot injects its classes' CSS\n * when it first draws them.\n */\nexport const make = <Palette extends ThemeTokens>(\n options: AppStyleOptions<Palette>,\n): AppStyle<Palette> => {\n const theme = composeThemes(tokens, options.palette)\n const scheme = options.colorScheme === undefined ? {} : { colorScheme: options.colorScheme }\n return Object.freeze({\n theme,\n t: ref(theme),\n L: standard,\n slots: <S>(pieces: DeclaredPieces<S>, styleOptions?: AppStyleOptionsFor) =>\n slots(pieces, { ...styleOptions, layer: app }),\n forSlots:\n <Slots>(contract: Slots) =>\n (pieces: StylePieces<Slots>, styleOptions?: AppStyleOptionsFor) =>\n forSlots(contract)(pieces, { ...styleOptions, layer: app }),\n stylesheet: stylesheet(\n standard.declare,\n standard.in('reset', reset),\n standard.in('tokens', root(tokens, scheme)),\n standard.in('theme', root(options.palette, scheme)),\n standard.in('defaults', compose(body, ...(options.global ?? []))),\n ),\n })\n}\n\nexport const AppStyle = { make } as const\n"],"mappings":";;;;;;;;;;;;;;;AAwDA,MAAM,MAAM,SAAS,MAAM,KAAK;;;;;;;AAQhC,MAAa,QACX,YACsB;CACtB,MAAM,QAAQA,UAAc,QAAQ,QAAQ,OAAO;CACnD,MAAM,SAAS,QAAQ,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa,QAAQ,YAAY;CAC3F,OAAO,OAAO,OAAO;EACnB;EACA,GAAG,IAAI,KAAK;EACZ,GAAG;EACH,QAAW,QAA2B,iBACpC,MAAM,QAAQ;GAAE,GAAG;GAAc,OAAO;EAAI,CAAC;EAC/C,WACU,cACP,QAA4B,iBAC3B,SAAS,QAAQ,CAAC,CAAC,QAAQ;GAAE,GAAG;GAAc,OAAO;EAAI,CAAC;EAC9D,YAAY,WACV,SAAS,SACT,SAAS,GAAG,SAAS,KAAK,GAC1B,SAAS,GAAG,UAAU,KAAK,QAAQ,MAAM,CAAC,GAC1C,SAAS,GAAG,SAAS,KAAK,QAAQ,SAAS,MAAM,CAAC,GAClD,SAAS,GAAG,YAAY,QAAQ,MAAM,GAAI,QAAQ,UAAU,CAAC,CAAE,CAAC,CAClE;CACF,CAAC;AACH;AAEA,MAAa,WAAW,EAAE,KAAK"}
|