@umber-style/core 0.0.0 → 0.1.0-alpha.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.
@@ -0,0 +1,617 @@
1
+ import * as CSS from "csstype";
2
+ /**
3
+ * The result of `alpha()` for a colour that is neither fully opaque nor fully transparent. The
4
+ * serializer writes it as two declarations when it is the whole value of a property: `fallback` first,
5
+ * then `value`. As text (`String(x)`, a template literal) it is `value` alone.
6
+ */
7
+ export interface AlphaColor {
8
+ /** The colour at the opacity as rgba() when the colour is a literal the engine can read, else the colour itself. */
9
+ readonly fallback: string;
10
+ /** The color-mix() value. */
11
+ readonly value: string;
12
+ }
13
+ /** Whether `value` was made by `alpha()` as a mix: a plain string is a color, not a fallback pair. */
14
+ export declare function isAlphaColor(value: unknown): value is AlphaColor;
15
+ /**
16
+ * `color` at `opacity` as `rgba(r, g, b, a)`, when `color` is a literal that can be read (`#rgb`, `#rgba`,
17
+ * `#rrggbb`, `#rrggbbaa`, `rgb()` or `rgba()` with numbers; its own alpha is multiplied), else undefined.
18
+ */
19
+ export declare function toRgba(color: string, opacity: number): string | undefined;
20
+ /** Throws what `alpha()` throws: a `TypeError` for a color that is not a string or an opacity that is not a number, a `RangeError` for an opacity outside 0 to 1 or NaN. */
21
+ export declare function assertAlphaInput(color: unknown, opacity: unknown): void;
22
+ /**
23
+ * `color` at `opacity` (0 to 1). Between 0 and 1 the result is an `AlphaColor`: written as a fallback
24
+ * (`rgba()` for a literal colour, else the colour itself) followed by `color-mix(in srgb, <color> <n>%,
25
+ * transparent)`, which works with var(--x) colors. 1 returns `color` and 0 returns `transparent`. A
26
+ * fallback is only written when the result is the whole value of a property; in a longer string
27
+ * (`1px solid ${alpha(c, 0.5)}`) it is the color-mix() form alone. Throws a `TypeError` for a color
28
+ * that is not a string or an opacity that is not a number, a `RangeError` for an opacity outside 0 to 1.
29
+ */
30
+ export declare function alpha(color: string, opacity: number): AlphaColor | string;
31
+ /** A property's value: what the CSS typings allow, or a list of those (fallbacks, tried in order), or nothing. */
32
+ type WebValue<V> = V | readonly V[] | null | undefined | false;
33
+ /** `V` without the "any other string" member that the CSS typings add to a keyword list. */
34
+ type Keywords<V> = V extends string ? (string extends V ? never : V) : V;
35
+ type DisplayOutside = CSS.DataType.DisplayOutside;
36
+ type DisplayInside = CSS.DataType.DisplayInside;
37
+ /**
38
+ * `display`: the keywords, and the two- and three-keyword forms (`block flex`, `block flow list-item`).
39
+ * It is the one property whose misspelling is caught, because its grammar is a closed set of keywords.
40
+ */
41
+ type DisplayValue = Keywords<CSS.Property.Display> | `${DisplayOutside} ${DisplayInside}` | `${DisplayInside} ${DisplayOutside}` | `${DisplayOutside} list-item` | `list-item ${DisplayOutside}` | `${DisplayOutside} ${DisplayInside} list-item`;
42
+ type CssProperties = CSS.Properties<string | number>;
43
+ /** The properties whose value is a color, and so also take the result of `alpha()`. */
44
+ type ColorProperty = 'accentColor' | 'background' | 'backgroundColor' | 'borderBlockColor' | 'borderBlockEndColor' | 'borderBlockStartColor' | 'borderBottomColor' | 'borderColor' | 'borderInlineColor' | 'borderInlineEndColor' | 'borderInlineStartColor' | 'borderLeftColor' | 'borderRightColor' | 'borderTopColor' | 'caretColor' | 'color' | 'columnRuleColor' | 'fill' | 'floodColor' | 'lightingColor' | 'outlineColor' | 'stopColor' | 'stroke' | 'textDecorationColor' | 'textEmphasisColor';
45
+ /** Every CSS property, by its camelCase name, with its value type; a color property also takes `alpha()`. */
46
+ export type WebProperties = { [K in keyof CssProperties]?: K extends 'display' ? WebValue<DisplayValue> : WebValue<NonNullable<CssProperties[K]> | (K extends ColorProperty ? AlphaColor : never)>; };
47
+ /** What a nested key holds: a style of its own, or nothing (so `isOpen && { ... }` works). */
48
+ export type WebNested = WebStyleObject | null | undefined | false;
49
+ /**
50
+ * A style for the web: any CSS property, a custom property (`--name`), `label`, and nested styles under
51
+ * a selector (a key with `&`, or one that starts with `:`) or an at-rule (a key that starts with `@`).
52
+ * Any other key is an error in an object literal.
53
+ */
54
+ export type WebStyleObject = WebProperties & {
55
+ /** Part of the class name, for a readable class in the developer tools. */
56
+ label?: string;
57
+ [key: `--${string}`]: string | number | AlphaColor | null | undefined | false;
58
+ [key: `${string}&${string}`]: WebNested;
59
+ [key: `:${string}`]: WebNested;
60
+ [key: `@${string}`]: WebNested;
61
+ };
62
+ /** A key that holds a nested style: a selector with `&`, one that starts with `:`, or an at-rule. */
63
+ export type NestedKey = `${string}&${string}` | `:${string}` | `@${string}`;
64
+ /**
65
+ * `{ [key]: style }` typed so that it can be spread into a web style. A key that is computed in an
66
+ * object literal has the type `string`, and the web style type rejects it (its custom property
67
+ * signature takes no style); the key here keeps its template literal type, and `style` is checked as a
68
+ * style of its own: `{ ...at(`@media (width >= ${breakpoint})`, { gap: 16 }) }`.
69
+ */
70
+ export declare function at<K extends NestedKey>(key: K, style: WebNested): Record<K, WebNested>;
71
+ /** The two color schemes that a condition can name. */
72
+ export type SchemeName = 'light' | 'dark';
73
+ /** The key of a style that applies when the nearest theme is the one with this theme class: `@theme <themeClass>`. */
74
+ export type ThemeKey = `@theme ${string}`;
75
+ /** The key of a style that applies when the nearest color scheme is this one: `@scheme dark`. */
76
+ export type SchemeKey = `@scheme ${SchemeName}`;
77
+ /** What a condition key stands for. */
78
+ export type Condition = {
79
+ readonly kind: 'theme';
80
+ readonly id: string;
81
+ } | {
82
+ readonly kind: 'scheme';
83
+ readonly scheme: SchemeName;
84
+ };
85
+ /** The names a scope is written with: the prefix of the cache, and whether `@scope` is used. */
86
+ export interface Scoping {
87
+ /** The prefix of the cache; the marker classes start with it. */
88
+ readonly prefix: string;
89
+ /** Whether a conditional rule is written with `@scope`. Without it, a plain descendant selector. */
90
+ readonly hasScope: boolean;
91
+ }
92
+ /** The scoping of a cache that gave none: the default prefix, with `@scope`. */
93
+ export declare const DEFAULT_SCOPING: Scoping;
94
+ /** The key for "the nearest theme is the one of this theme class". */
95
+ export declare function createThemeKey(themeClass: string): ThemeKey;
96
+ /** The key for "the nearest color scheme is this one". */
97
+ export declare function createSchemeKey(scheme: SchemeName): SchemeKey;
98
+ /** The condition a style key stands for, or undefined for any other key. */
99
+ export declare function readCondition(key: string): Condition | undefined;
100
+ /** The class that every element with a theme carries, so that it can be a scope limit. */
101
+ export declare function getBoundaryClass(prefix: string): string;
102
+ /** The class of an element whose theme has a color scheme of its own. */
103
+ export declare function getSchemeClass(prefix: string, scheme: SchemeName): string;
104
+ /**
105
+ * The class string of a theme: its theme class, the boundary marker, and, when its color scheme is
106
+ * `light` or `dark`, the scheme marker. `light dark` and no scheme have no scheme marker.
107
+ */
108
+ export declare function createThemeClassName(prefix: string, id: string, colorScheme?: string): string;
109
+ /**
110
+ * `rules` for the elements below the elements that match `start`, down to but not into the elements
111
+ * that match `limits`: `@scope (start) to (limits){rules}`. A limit is relative to the scope root, so
112
+ * the root is never cut off by its own marker (checked in a browser: `to (.x)` and `to (:scope .x)` agree).
113
+ */
114
+ export declare function createScopeRule(start: string, limits: string, rules: readonly string[]): string;
115
+ /** The selector that matches an element with no scheme marker on it or above it. Its specificity is 0. */
116
+ export declare function createNoSchemeGuard(prefix: string): string;
117
+ export type StyleValue = string | number | AlphaColor | null | undefined | false | readonly (string | number | AlphaColor)[] | StyleObject;
118
+ export interface StyleObject {
119
+ [key: string]: StyleValue;
120
+ }
121
+ /** Merges style objects left to right; a later key wins and moves to the end; nested objects merge the same way. */
122
+ export declare function mergeStyles(styles: readonly StyleObject[]): StyleObject;
123
+ /**
124
+ * The flat CSS rules of `style` for `selector`; without `hasColorFallbacks` an `alpha()` result is
125
+ * written as its mix alone. A `when()` or `whenScheme()` key becomes a scoped rule, written as
126
+ * `scoping` says.
127
+ */
128
+ export declare function compileRules(selector: string, style: StyleObject, hasColorFallbacks?: boolean, scoping?: Scoping): string[];
129
+ /** The label of `style` (its `label` key), or ''. */
130
+ export declare function readLabel(style: StyleObject): string;
131
+ /** The two ways an entry is used: on its own (a plain element, `apply`), or given to a styled component through `style`. */
132
+ export type EntryRole = 'components' | 'overrides';
133
+ /** What a cache gives an entry that it made: the style, and the class of each role, written on first use. */
134
+ export interface EntrySource {
135
+ /** The style of the entry, merged. */
136
+ readonly style: StyleObject;
137
+ /** The class name for `role`; its rule is written, once, the first time it is asked for. */
138
+ use(role: EntryRole): string;
139
+ }
140
+ /** One style of a sheet: it carries the class name that the cache made for it, and nothing else. */
141
+ export interface SheetEntry {
142
+ /** The class name of the entry used on its own. Reading it writes its rule, if that was not written yet. */
143
+ readonly className: string;
144
+ }
145
+ /**
146
+ * Makes the entry of a class name: a frozen object that `isSheetEntry` knows and that prints as the
147
+ * class name. Its one enumerable key is a custom property named after the class, with the value `null`,
148
+ * so that a framework that merges the style objects of an array (Vue does) keeps every entry, and
149
+ * `flattenStyle` finds them by the key. Both frameworks skip a `null` style value on a plain element, on
150
+ * the client and on the server, so an entry given to a plain element renders no style attribute. With a
151
+ * `source` (a cache made it) the class name is read through it, so that the rule is written when the entry
152
+ * is used, not when it is made; without one the entry is just the name.
153
+ */
154
+ export declare function createSheetEntry(className: string, source?: EntrySource): SheetEntry;
155
+ /** Whether `value` was made by `createSheetEntry`: a class name is a plain string, a style object has no brand. */
156
+ export declare function isSheetEntry(value: unknown): value is SheetEntry;
157
+ /** What a cache gave `entry` to make its classes, or undefined for an entry that is only a name. */
158
+ export declare function readEntrySource(entry: SheetEntry): EntrySource | undefined;
159
+ /**
160
+ * What a `style` prop holds, as a flat list in order, for the cache to merge into one class: sheet
161
+ * entries and plain style objects, with arrays flattened and what is empty dropped. An object in which a
162
+ * framework merged entries and plain keys (Vue does) is split back into its entries, then the rest; an
163
+ * entry is looked up by its class name with `findEntry` (a cache's `findEntry`), else it is only the name.
164
+ * A string is an error: a text style cannot be merged into a class.
165
+ */
166
+ export declare function flattenStyle(style: unknown, findEntry?: (className: string) => SheetEntry | undefined): (SheetEntry | WebStyleObject)[];
167
+ export interface CacheOptions {
168
+ /** First part of every class name. Default 'css'. Must match /^[a-z][a-z0-9-]*$/ or createCache throws. */
169
+ prefix?: string;
170
+ /** Appended to every class name. Default ''. */
171
+ suffix?: string;
172
+ /** Whether a style's label is part of its class name. Default true. */
173
+ hasLabels?: boolean;
174
+ /** Whether every rule goes into a cascade layer (`<prefix>-theme`, `-global`, `-components`, `-overrides`). Default true. */
175
+ hasLayers?: boolean;
176
+ /**
177
+ * Whether a theme class declares only the variables that rules refer to (and those marked with
178
+ * `markUsed`), appending more as rules come in. Default true. Without it, a theme class declares every token.
179
+ */
180
+ hasPruning?: boolean;
181
+ /**
182
+ * Whether a property whose value is `alpha()` gets two declarations, the fallback first (rgba() for a
183
+ * literal colour, else the colour itself) and then the color-mix() value, for a browser without
184
+ * color-mix(). Default true. Without it only the color-mix() value is written.
185
+ */
186
+ hasColorFallbacks?: boolean;
187
+ /**
188
+ * Whether a style written with `when()` or `whenScheme()` is scoped with `@scope`, so that it follows the
189
+ * nearest theme. Default true. Without it the rule is the plain descendant form `:where(.theme) .class`,
190
+ * which also matches below a nested theme, and so is wrong for nested themes. A browser without `@scope`
191
+ * drops the scoped rules and keeps the rest.
192
+ */
193
+ hasScope?: boolean;
194
+ /**
195
+ * Whether a styled component's style list is split by position into a base class (the plain objects
196
+ * before the first function, made once) and a props class (the rest, made for each render), both in the
197
+ * `components` layer. Default true. Without it the whole list is one class, as before. The cache only
198
+ * holds the option; the engine's `createStyler` reads it.
199
+ */
200
+ hasBaseClass?: boolean;
201
+ /**
202
+ * Whether the cache checks the page while it runs in a browser, and warns once for each problem found
203
+ * (an engine class that has no rule, a variable that has no value): `findMissingStyles`, throttled,
204
+ * after the first render and when rules are inserted. Default: on in development (`process.env.NODE_ENV`
205
+ * is not `production`), off in production, and off where there is no `document`.
206
+ */
207
+ hasDevChecks?: boolean;
208
+ /** A short text that stands for the token options (modes, raw and length keys, registered tokens), for the stamp that the server writes and the browser compares. The engine gives it; '' when none. */
209
+ tokenSignature?: string;
210
+ /** Where rules go. Default: a DOM sheet when `document` exists, otherwise an in-memory one. */
211
+ sheet?: Sheet;
212
+ }
213
+ /** What `extractPage` is told besides the classes of the page. */
214
+ export interface PageExtractOptions {
215
+ /** Theme classes to include although no element has them (the themes the page offers for switching). */
216
+ themes?: Iterable<string>;
217
+ /** Keys of the `<style href precedence>` elements that the document carries already: their rules are left out. */
218
+ carried?: ReadonlySet<string>;
219
+ }
220
+ export interface Sheet {
221
+ insert(rule: string): void;
222
+ /** Every rule inserted so far, in order. */
223
+ readonly rules: readonly string[];
224
+ /** Replaces the rule inserted at `index` of `rules`; a sheet that cannot (a browser one) has none, and the cache appends instead. */
225
+ replace?(index: number, rule: string): void;
226
+ }
227
+ /** The cascade layers of a cache, from the lowest priority to the highest. */
228
+ export declare const RULE_LAYERS: readonly ['theme', 'global', 'components', 'overrides'];
229
+ export type RuleLayer = (typeof RULE_LAYERS)[number];
230
+ /** The layers that a class can be made in: the styles of a component, and what is given to it from outside. */
231
+ export type ClassLayer = 'components' | 'overrides';
232
+ export type ClassValue = WebStyleObject | SheetEntry | string | null | undefined | false;
233
+ /** How `cssWith` makes a class, beyond what is in it. */
234
+ export interface ClassOptions {
235
+ /** The layer of the class. Default `components`. */
236
+ layer?: ClassLayer;
237
+ /** A label for the class; it wins over the labels of the values. */
238
+ label?: string;
239
+ /**
240
+ * A class of this cache that is written before this one, and that this one is only used with (the base
241
+ * class of a component, for its props class). It is part of the name, so that the same styles after two
242
+ * different classes are two classes, each written after its own; and a sheet entry is merged in, never
243
+ * used as it is, because its own class may have been written before `after`.
244
+ */
245
+ after?: string;
246
+ }
247
+ export interface Cache {
248
+ readonly prefix: string;
249
+ /** Whether rules go into cascade layers. */
250
+ readonly hasLayers: boolean;
251
+ /** The statement that declares the layers in order, `@layer <prefix>-theme,...;`, or '' without layers. It is the first rule of the sheet. */
252
+ readonly layerOrder: string;
253
+ /** The style object of each class this cache made, by class name. */
254
+ readonly registered: ReadonlyMap<string, StyleObject>;
255
+ /**
256
+ * One class for all of `values`: style objects, and class names this cache made (resolved back
257
+ * to their styles), merged left to right so the last wins. Other class names pass through in
258
+ * front of it. Returns '' when there is nothing. The class is in the `components` layer.
259
+ */
260
+ css(...values: ClassValue[]): string;
261
+ /** `css`, with the layer of the class given: `overrides` for what a component is given from outside. */
262
+ cssIn(layer: ClassLayer, ...values: ClassValue[]): string;
263
+ /**
264
+ * `cssIn` with more to say about the class (see `ClassOptions`). When `values` is exactly one sheet
265
+ * entry (and class names that are not the cache's) and there is no `after`, no class is made: the class
266
+ * of the entry for that layer is used, and written if it was not.
267
+ */
268
+ cssWith(options: ClassOptions, ...values: ClassValue[]): string;
269
+ /** The entry of a style: its class names are worked out now and their rules are written when the entry is first used, in the layer of how it is used. */
270
+ createEntry(style: WebStyleObject): SheetEntry;
271
+ /** The entry that `createEntry` made, by the class name it has when used on its own, for a framework that merged entries into one object. */
272
+ findEntry(className: string): SheetEntry | undefined;
273
+ /** Whether a component's styles are split into a base class and a props class. */
274
+ readonly hasBaseClass: boolean;
275
+ /**
276
+ * Inserts `rules` once under `id`; returns whether it inserted them. With a `layer` (and layers on)
277
+ * each rule is wrapped in it. Without one the rules are written as they are, outside every layer:
278
+ * the place of an at-rule that is not a layer's to hold, such as `@property`.
279
+ */
280
+ insertOnce(id: string, rules: readonly string[], layer?: RuleLayer): boolean;
281
+ /** The rules this cache inserted under `id` (a class name), or none: for a style element that a server component renders. */
282
+ getRules(id: string): readonly string[];
283
+ /** Whether conditional rules are written with `@scope`. */
284
+ readonly hasScope: boolean;
285
+ /** Whether theme classes declare only the variables in use. */
286
+ readonly hasPruning: boolean;
287
+ /** The names of the variables that rules refer to, or that were marked: the only ones a pruned theme class declares. It only grows. */
288
+ readonly usedVariables: ReadonlySet<string>;
289
+ /** Marks variables as used, plus those that the values of themes refer to, and declares them in every theme class that has them. Does nothing without pruning. */
290
+ markUsed(names: Iterable<string>): void;
291
+ /**
292
+ * Registers a theme class: `declarations` are all its variables, `colorScheme` is set by its rule.
293
+ * Only the used variables are written, more when they become used; the class itself always exists.
294
+ * Does nothing for a class that is already there.
295
+ */
296
+ insertTheme(className: string, declarations: Readonly<Record<string, string>>, colorScheme?: string): void;
297
+ /**
298
+ * Gives the cache the `@property` rule of each registered variable, by variable name (`createTokens`
299
+ * makes them), replacing those it had. A rule is written once, outside every layer, when its variable
300
+ * is first used (at once for a variable that is used already, or when there is no pruning); a rule
301
+ * that is the same as a written one, or that a server render sent, is not written again.
302
+ */
303
+ registerProperties(rules: Readonly<Record<string, string>>): void;
304
+ /** `getRules` with every declaration of a theme class, used or not, after the `@property` rules of the registered variables it declares: for a style element that is sent before the rules that use the class. */
305
+ getFullRules(id: string): readonly string[];
306
+ /** The CSS inserted so far and the ids it covers (class names, then the used variables): all of the cache, whatever page asked for it. See `extractPage` for one page. */
307
+ extract(): {
308
+ css: string;
309
+ ids: string[];
310
+ };
311
+ /**
312
+ * The CSS that one page needs, decided from the class names it holds and not from what the cache holds:
313
+ * the layer order statement; the `@property` rules of the variables in use; each theme class (of the
314
+ * page, and `options.themes`) with only the variables the page's rules use (all that they refer to,
315
+ * through the values of the themes too, and the variables marked with `markUsed`) and its color-scheme;
316
+ * and the rules of the classes, in an order that depends on the classes only: a props class after its
317
+ * base class, the rest by name. Names the cache made no rules for are ignored. It reads the cache and
318
+ * changes nothing, so pages rendered at once, or in any order, get the same CSS.
319
+ */
320
+ extractPage(classNames: Iterable<string>, options?: PageExtractOptions): {
321
+ css: string;
322
+ ids: string[];
323
+ };
324
+ /** The options that change the CSS or the class names, as a short text: the server stamps it on its style output and the browser compares it with its own. */
325
+ readonly fingerprint: string;
326
+ }
327
+ /** A sheet that keeps its rules in memory, for a server render or a test. */
328
+ export declare function createMemorySheet(): Sheet;
329
+ /** A sheet in the style element marked `data-style="<key>"`, which it creates when there is none. */
330
+ export declare function createDomSheet(key: string, container?: Node): Sheet;
331
+ /** Makes a cache: it turns styles into classes and inserts each class's rules once. */
332
+ export declare function createCache(options?: CacheOptions): Cache;
333
+ /** A value of arithmetic on tokens: a CSS value (a reference such as `var(--space-2)`, a length) or a number. */
334
+ export type Operand = string | number;
335
+ /** `value` times `factor`: a number for numbers, otherwise a CSS value that the browser computes. */
336
+ export declare function multiply(value: number, factor: number): number;
337
+ export declare function multiply(value: Operand, factor: number): Operand;
338
+ /** `value` divided by `divisor`; a `divisor` of 0 throws a `RangeError`. */
339
+ export declare function divide(value: number, divisor: number): number;
340
+ export declare function divide(value: Operand, divisor: number): Operand;
341
+ /** The sum of `values`; a number next to a string is a length in px. */
342
+ export declare function add(...values: number[]): number;
343
+ export declare function add(...values: Operand[]): Operand;
344
+ /** `value` minus each of `values`; a number next to a string is a length in px. */
345
+ export declare function subtract(value: number, ...values: number[]): number;
346
+ export declare function subtract(value: Operand, ...values: Operand[]): Operand;
347
+ /** `value` times -1: a negative margin from a token. */
348
+ export declare function negate(value: number): number;
349
+ export declare function negate(value: Operand): Operand;
350
+ /** The syntax of a registered custom property, which gives its variable a type so that it can be animated. */
351
+ type RegisteredSyntax = '<color>' | '<length>' | '<number>' | '<percentage>' | '<length-percentage>' | '<angle>' | '<time>' | '*';
352
+ /** How a token is written: a variable, the real value in the rules, a variable with a fallback, or a real value that is never written. */
353
+ export type TokenMode = 'variable' | 'inline' | 'reference' | 'raw';
354
+ export interface TokenOptions {
355
+ /** Put before every variable name, e.g. 'ds' gives --ds-palette-primary. */
356
+ prefix?: string;
357
+ /** Top-level theme keys that stay real values and get no variable: the same as mode `raw`. Default ['breakpoints', 'components']. */
358
+ rawKeys?: readonly string[];
359
+ /** Top-level theme keys whose numbers are lengths, declared with px. Default ['space', 'sizes', 'radii', 'fontSizes', 'borderWidths']. */
360
+ lengthKeys?: readonly string[];
361
+ /**
362
+ * The mode of a token, by dotted theme path ('zIndex', 'transitions.duration', 'palette.primary').
363
+ * The most specific path wins, and an entry beats `rawKeys`. Default mode: `variable`.
364
+ */
365
+ modes?: Readonly<Record<string, TokenMode>>;
366
+ /**
367
+ * The tokens that are registered custom properties (an `@property` rule), by dotted theme path, found
368
+ * like `modes` (the most specific path wins; a top-level key registers everything under it). `true`
369
+ * infers the syntax from the base theme value, otherwise it is one of the syntaxes. A registered
370
+ * variable has a type, so a `transition` on it animates a theme switch. Only variable and reference
371
+ * tokens have a variable to register.
372
+ */
373
+ registered?: Readonly<Record<string, RegisteredSyntax | true>>;
374
+ }
375
+ export type DeepPartial<T> = T extends ((...args: never[]) => unknown) ? T : T extends object ? { [K in keyof T]?: DeepPartial<T[K]>; } : T;
376
+ export interface Tokens<T> {
377
+ /** The theme's shape, with var(--name) in place of each variable token, var(--name, value) for a reference, and the real value for the rest. */
378
+ refs: T;
379
+ /** The variable declarations of `theme`, which may be a partial theme: only the variable and reference tokens it has. */
380
+ declare(theme: DeepPartial<T>): Record<string, string>;
381
+ /** The shape of `realTheme` like `refs`: the same references (a fallback is the base value), the real values of `realTheme` for the rest. */
382
+ createView(realTheme: T): T;
383
+ /** The names of the variables of the base theme under these dotted paths (a top-level key or a deeper path). */
384
+ findNames(paths: readonly string[]): string[];
385
+ /** The `@property` rule of each registered variable of the base theme, by variable name. */
386
+ registrations: Readonly<Record<string, string>>;
387
+ }
388
+ /** Turns a theme into variable references and the declarations that give them values. */
389
+ export declare function createTokens<T extends object>(theme: T, options?: TokenOptions): Tokens<T>;
390
+ export interface EngineOptions extends TokenOptions {
391
+ /** First part of every class name and variable name. Default 'css'. */
392
+ prefix?: string;
393
+ /** Appended to every class name. */
394
+ suffix?: string;
395
+ /** Whether a style's label is part of its class name. */
396
+ hasLabels?: boolean;
397
+ /** Whether every rule goes into a cascade layer. Default true. */
398
+ hasLayers?: boolean;
399
+ /** Whether an `alpha()` value is written as a fallback and then the color-mix() value. Default true; used when the engine makes its cache. */
400
+ hasColorFallbacks?: boolean;
401
+ /** Whether a `when()` or `whenScheme()` style is scoped with `@scope`. Default true; used when the engine makes its cache. Without it the rule is a plain descendant selector, which is wrong for nested themes. */
402
+ hasScope?: boolean;
403
+ /** Whether a theme class declares only the variables that rules refer to. Default true; used when the engine makes its cache. */
404
+ hasPruning?: boolean;
405
+ /** Whether a component's styles are split by position into a base class (made once) and a props class (made for each render). Default true; used when the engine makes its cache. */
406
+ hasBaseClass?: boolean;
407
+ /** Whether the cache checks the page in the browser and warns once for each problem found (`findMissingStyles`). Default: on in development (`process.env.NODE_ENV` is `development`), off otherwise; used when the engine makes its cache. */
408
+ hasDevChecks?: boolean;
409
+ /** Theme paths (dotted, or top-level keys) whose variables are always declared, for code outside the engine that reads them. */
410
+ alwaysDeclare?: readonly string[];
411
+ /** The cache to use; one is made when not given. */
412
+ cache?: Cache;
413
+ }
414
+ export type ColorScheme = 'light' | 'dark' | 'light dark';
415
+ /** What a style function may return. */
416
+ export type StyleResult = WebStyleObject | null | undefined | false;
417
+ /** A style that is computed from the props and the theme. */
418
+ export type StyleFunction<T, P> = (props: P & {
419
+ theme: T;
420
+ }) => StyleResult;
421
+ /** A style object, or a function of the props and the theme; the defaults accept any function. */
422
+ export type StyleInput<T = never, P = never> = WebStyleObject | StyleFunction<T, P>;
423
+ /** The label of a styled component, and what it takes from the styles of the one it wraps. */
424
+ export interface StylerOptions {
425
+ /** With `slot`, the label of the class: `name-slot` in kebab-case. */
426
+ name?: string;
427
+ /** Default 'root'. */
428
+ slot?: string;
429
+ }
430
+ export type SheetStyles = Record<string, WebStyleObject>;
431
+ /**
432
+ * What a sheet is made from: one style for each name, or a function of the theme that returns them. The
433
+ * names are the type parameter, so that an object literal given here is checked key by key.
434
+ */
435
+ export type SheetInput<K extends string, T> = Record<K, WebStyleObject> | ((theme: T) => Record<K, WebStyleObject>);
436
+ /**
437
+ * A sheet given as an object: one style for each name. It is a record of styles with a function
438
+ * left out, so that a function of the theme is not taken for one (the compiler tries the object form first).
439
+ */
440
+ export type ObjectSheet<K extends string> = Record<K, WebStyleObject> & {
441
+ call?: never;
442
+ };
443
+ /** The entries of a sheet, by name: each is made on first access, and its rule is written when it is first used. */
444
+ export type SheetEntries<K extends string> = { readonly [P in K]: SheetEntry; };
445
+ /** A sheet made from a function of the theme: it has no entries until it is resolved against a theme, which `useStyle` does. */
446
+ export interface ThemedSheet<K extends string, T> {
447
+ /** The entries, against `theme` (a theme view) when given, else against the base theme. */
448
+ resolve(theme?: T): SheetEntries<K>;
449
+ }
450
+ /**
451
+ * The shape of the theme of an app. It has no members of its own (the optional one below only keeps it
452
+ * from being empty): an app adds its own by merging, with
453
+ * `declare module '@umber-style/core' { interface Theme extends MyTheme {} }`.
454
+ */
455
+ export interface Theme {
456
+ readonly _theme?: never;
457
+ }
458
+ /** Whether `sheet` is a sheet made from a function of the theme, which `resolve` turns into entries; an object sheet is its entries, none of which is a function. */
459
+ export declare function isThemedSheet(sheet: object): sheet is ThemedSheet<string, unknown>;
460
+ /** What is thrown when something needs the shape of the theme before any theme is known. */
461
+ export declare const NO_THEME_MESSAGE = "There is no theme yet: render a ThemeProvider with the full theme first, or call setTheme (or configure({ theme })) before a function style, a sheet or useTheme is used.";
462
+ /** The options of a binding's `createStyle`: those of the engine, or an engine to share with other bindings. */
463
+ export interface BindingOptions<T> extends EngineOptions {
464
+ /** When given, the engine options are not used. */
465
+ engine?: Engine<T>;
466
+ }
467
+ export interface Styler {
468
+ /** The full style list, for a component that wraps this one. */
469
+ styles: readonly StyleInput[];
470
+ /** Whether a style is a function: only then the class depends on the props and the theme. */
471
+ isDynamic: boolean;
472
+ /**
473
+ * The class names for these props and what comes in after the styles (sheet entries, plain objects,
474
+ * a className). With layers: the base class (the plain objects before the first function, made once)
475
+ * and the props class (from the first function on, made for each render), both in the `components`
476
+ * layer, base first; then, only when something comes in, one override class in the `overrides` layer
477
+ * (all of it merged in order, the last winning; or, when it is exactly one sheet entry, the class of
478
+ * that entry for the layer); foreign class names pass through. Without layers there is no order between
479
+ * classes to rely on, so when something comes in all of it is merged into one class. Without
480
+ * `hasBaseClass`: one class for the styles.
481
+ */
482
+ getClassName(props: Record<string, unknown>, extra?: ClassValue | readonly ClassValue[], theme?: unknown): string;
483
+ }
484
+ export interface Engine<T> {
485
+ cache: Cache;
486
+ /** Whether a base theme is known: it is given by `setTheme`, or by the first `themeClass`. */
487
+ readonly hasTheme: boolean;
488
+ /** The base theme, the real values, or undefined while there is none. */
489
+ readonly baseTheme: T | undefined;
490
+ /** The view of the base theme: its shape, with a var(--name) reference for each token. Throws while there is no theme. */
491
+ readonly refs: T;
492
+ /** The view of `realTheme`: each token is a var(--name) reference, every other part (breakpoints, functions, other objects) is taken from `realTheme`. Made once for each theme object. */
493
+ createThemeView(realTheme: T): T;
494
+ /** Gives the engine its base theme. The same object again does nothing; another one replaces the base. */
495
+ setTheme(theme: T): void;
496
+ css: Cache['css'];
497
+ /**
498
+ * The classes of a theme, made once for each theme object and color scheme: the theme class (the
499
+ * variables), the boundary marker `<prefix>-boundary`, and for a `light` or `dark` color scheme the
500
+ * marker `<prefix>-scheme-light` or `-dark`. Put the whole string where a class goes. With no base
501
+ * theme yet, this theme becomes it.
502
+ */
503
+ themeClass(theme: DeepPartial<T>, colorScheme?: ColorScheme): string;
504
+ /** The theme class alone, `<prefix>-theme-<hash>`: the id that rules and style elements are keyed by. Makes the theme class as `themeClass` does. */
505
+ themeId(theme: DeepPartial<T>, colorScheme?: ColorScheme): string;
506
+ /** The theme classes already made for this theme object (one for each color scheme it was asked with), without making any. */
507
+ findThemeIds(theme: DeepPartial<T>): string[];
508
+ /** A style key for "the nearest theme is this theme": `{ [when(dark)]: { border: ... } }`. Needs `@scope` (see `hasScope`). */
509
+ when(theme: DeepPartial<T>, colorScheme?: ColorScheme): ThemeKey;
510
+ /** A style key for "the nearest color scheme is this one": the nearest theme given that `colorScheme`, else the system preference. */
511
+ whenScheme(scheme: SchemeName): SchemeKey;
512
+ /** The class of a wrapper that a provider renders: it only has display: contents. Inserted once. It is not part of a theme class, which is also put on <html>. */
513
+ scopeClass(): string;
514
+ /**
515
+ * A sheet of named styles. Given a function of the theme it is a sheet that is resolved against a
516
+ * theme (`resolve`, which `useStyle` calls). Given an object it is the entries themselves, usable at
517
+ * once: no theme is read, so it works before there is one. Entries are made on first access and a
518
+ * class's rule is written when the entry is first used, in the layer of how it is used.
519
+ */
520
+ createSheet<K extends string>(styles: ObjectSheet<K>): SheetEntries<K>;
521
+ createSheet<K extends string>(styles: (theme: T) => Record<K, WebStyleObject>): ThemedSheet<K, T>;
522
+ /** The logic that every web `styled` shares: the label, the style list, function styles and the class memo. */
523
+ createStyler(options: StylerOptions, styles: readonly StyleInput[], inherited?: readonly StyleInput[]): Styler;
524
+ }
525
+ /** Makes an engine that has no theme yet: it takes one from `setTheme`, or from the first `themeClass`. It needs no framework. */
526
+ export declare function createLazyEngine<T extends object = Theme>(options?: EngineOptions): Engine<T>;
527
+ /** Makes the engine of one theme shape: a cache, the theme as variables, and what the bindings build on. It needs no framework. */
528
+ export declare function createEngine<T extends object>(theme: T, options?: EngineOptions): Engine<T>;
529
+ /**
530
+ * The style element of a static page or a server render: everything `cache` inserted, whatever page
531
+ * inserted it. A cache that renders more than one page (a server process) should use `extractPageStyles`,
532
+ * which carries only what one page uses. The element is stamped with the options of the cache
533
+ * (`data-options`), which a cache made in the browser compares with its own; it holds no list of ids,
534
+ * because the browser reads the rules themselves.
535
+ */
536
+ export declare function createStyleTag(cache: Cache): string;
537
+ /** What one page needs: its CSS, what that CSS covers, and the element to put in its head. */
538
+ export interface PageStyles {
539
+ /** The CSS of the page: the layer order, the `@property` rules, the themes, the rules of its classes. */
540
+ css: string;
541
+ /** The theme classes and the classes that `css` has rules for. */
542
+ ids: string[];
543
+ /** The stamp of the options of the cache: the `data-options` of the style element, for a page that writes the element itself. */
544
+ options: string;
545
+ /** The style element with `css`, stamped with the options of the cache. */
546
+ tag: string;
547
+ }
548
+ export interface PageStyleOptions {
549
+ /** Theme classes (`themeClass(...)` results, or their first class) to include although no element of `html` has them: the themes the page offers for switching, and the one on `<html>`, which `html` does not hold when it is the markup of the root only. They get the variables that the page uses, like the others. */
550
+ themes?: readonly string[];
551
+ }
552
+ /**
553
+ * The CSS of one page, decided from the page: the finished `html` is scanned for the class names it
554
+ * holds (the values of its `class` and `className` attributes only; scripts, styles, comments and other
555
+ * attributes are not looked at), and only those classes are written, with the theme classes
556
+ * trimmed to the variables that the page uses. Nothing depends on what else the cache holds, on the
557
+ * order pages were rendered in, or on pages being rendered at the same time, and the cache is not changed.
558
+ * The `<style href precedence>` elements that `html` carries already (React's server render of the
559
+ * client build emits them) are not written again.
560
+ */
561
+ export declare function extractPageStyles(cache: Cache, html: string, options?: PageStyleOptions): PageStyles;
562
+ /** What `findMissingStyles` can find. */
563
+ export type StyleProblemKind = 'class-without-rule' | 'variable-without-value';
564
+ /** One thing the page lacks. */
565
+ export interface StyleProblem {
566
+ kind: StyleProblemKind;
567
+ /** The class, or the variable. */
568
+ name: string;
569
+ /** A short description of the element: `tag[test id or id]`. */
570
+ element: string;
571
+ /** What is wrong, in a sentence. */
572
+ message: string;
573
+ /** What makes two problems the same one: the kind and the name, and for a variable the rule that uses it. */
574
+ key: string;
575
+ }
576
+ export interface FindMissingStylesOptions {
577
+ /** The prefix of the engine. Default: the one the style elements of the page say. */
578
+ prefix?: string;
579
+ }
580
+ /**
581
+ * Looks at a page that an engine styled, and lists what is missing. For each element under `root`
582
+ * (the document by default): every class of the engine on it is named by at least one rule of the
583
+ * engine's style elements (its own, and the ones React hoists), and every variable of the engine that
584
+ * a rule matching the element uses, without a fallback, has a value on the element. The classes that
585
+ * are markers (`<prefix>-boundary`, `<prefix>-scheme-light` and `-dark`) have no rule of their own and
586
+ * are left out, and so are the rules for `:hover`, `:focus` and the like. An empty list means nothing
587
+ * is missing. Where there is no document, or no style element of an engine, the list is empty.
588
+ */
589
+ export declare function findMissingStyles(root?: ParentNode, options?: FindMissingStylesOptions): StyleProblem[];
590
+ /** A short, stable hash of `text`, in base 36. */
591
+ export declare function hashString(text: string): string;
592
+ /**
593
+ * An object with one key for each of `keys`, whose value is made by `make` the first time the key is
594
+ * read, and kept. `Object.keys` and a spread list the keys (a spread reads every one); nothing is made
595
+ * until then. The object is frozen.
596
+ */
597
+ export declare function createLazyRecord<K extends string, V>(keys: readonly K[], make: (key: K) => V): { readonly [P in K]: V; };
598
+ /**
599
+ * `createLazyRecord` for the keys of `source`, with every value taken from the record that `build` makes,
600
+ * which is called once, when the first key is read: for a sheet whose engine must not be made, or whose
601
+ * platform call must not run, before it is used.
602
+ */
603
+ export declare function createDeferredRecord<V>(source: object, build: () => Record<string, V>): Readonly<Record<string, V>>;
604
+ /** `override` over `base`: plain objects merge key by key, everything else is replaced, undefined keeps `base`. */
605
+ export declare function mergeDeep<T>(base: T, override: DeepPartial<T> | undefined): T;
606
+ export interface ThemeRuleOptions {
607
+ /** Sets the color-scheme property in the scope. */
608
+ colorScheme?: 'light' | 'dark' | 'light dark';
609
+ }
610
+ /** The CSS declarations `name:value;` of `entries`. */
611
+ export declare function toDeclarationText(entries: Iterable<readonly [string, string]>): string;
612
+ /**
613
+ * Registers the theme class of `declarations` and returns it: the scope of a theme. Its name is the
614
+ * hash of all the declarations, whatever the cache writes of them (see `hasPruning`).
615
+ */
616
+ export declare function createThemeClass(cache: Cache, declarations: Readonly<Record<string, string>>, options?: ThemeRuleOptions): string;
617
+ export type { RegisteredSyntax };