@umber-style/core 0.0.0 → 0.1.0-alpha.1
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/LICENSE +21 -0
- package/README.md +13 -1
- package/dist/index.cjs +3741 -0
- package/dist/index.d.cts +1144 -0
- package/dist/index.d.mts +1144 -0
- package/dist/index.mjs +3670 -0
- package/package.json +66 -5
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,1144 @@
|
|
|
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
|
+
/** The text of the colour: `value`. */
|
|
13
|
+
toString(): string;
|
|
14
|
+
}
|
|
15
|
+
/** Whether `value` was made by `alpha()` as a mix: a plain string is a color, not a fallback pair. */
|
|
16
|
+
export declare function isAlphaColor(value: unknown): value is AlphaColor;
|
|
17
|
+
/**
|
|
18
|
+
* `color` at `opacity` as `rgba(r, g, b, a)`, when `color` is a literal that can be read (`#rgb`, `#rgba`,
|
|
19
|
+
* `#rrggbb`, `#rrggbbaa`, `rgb()` or `rgba()` with numbers; its own alpha is multiplied), else undefined.
|
|
20
|
+
*/
|
|
21
|
+
export declare function toRgba(color: string, opacity: number): string | undefined;
|
|
22
|
+
/** 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. */
|
|
23
|
+
export declare function assertAlphaInput(color: unknown, opacity: unknown): void;
|
|
24
|
+
/**
|
|
25
|
+
* `color` at `opacity` (0 to 1). Between 0 and 1 the result is an `AlphaColor`: written as a fallback
|
|
26
|
+
* (`rgba()` for a literal colour, else the colour itself) followed by `color-mix(in srgb, <color> <n>%,
|
|
27
|
+
* transparent)`, which works with var(--x) colors. 1 returns `color` and 0 returns `transparent`. A
|
|
28
|
+
* fallback is only written when the result is the whole value of a property; in a longer string
|
|
29
|
+
* (`1px solid ${alpha(c, 0.5)}`) it is the color-mix() form alone. Throws a `TypeError` for a color
|
|
30
|
+
* that is not a string or an opacity that is not a number, a `RangeError` for an opacity outside 0 to 1.
|
|
31
|
+
*/
|
|
32
|
+
export declare function alpha(color: string, opacity: number): AlphaColor | string;
|
|
33
|
+
/** A property's value: what the CSS typings allow, or a list of those (fallbacks, tried in order), or nothing. */
|
|
34
|
+
type WebValue<V> = V | readonly V[] | null | undefined | false;
|
|
35
|
+
/** `V` without the "any other string" member that the CSS typings add to a keyword list. */
|
|
36
|
+
type Keywords<V> = V extends string ? (string extends V ? never : V) : V;
|
|
37
|
+
type DisplayOutside = CSS.DataType.DisplayOutside;
|
|
38
|
+
type DisplayInside = CSS.DataType.DisplayInside;
|
|
39
|
+
/**
|
|
40
|
+
* `display`: the keywords, and the two- and three-keyword forms (`block flex`, `block flow list-item`).
|
|
41
|
+
* It is the one property whose misspelling is caught, because its grammar is a closed set of keywords.
|
|
42
|
+
*/
|
|
43
|
+
type DisplayValue = Keywords<CSS.Property.Display> | `${DisplayOutside} ${DisplayInside}` | `${DisplayInside} ${DisplayOutside}` | `${DisplayOutside} list-item` | `list-item ${DisplayOutside}` | `${DisplayOutside} ${DisplayInside} list-item`;
|
|
44
|
+
type CssProperties = CSS.Properties<string | number>;
|
|
45
|
+
/** The properties whose value is a color, and so also take the result of `alpha()`. */
|
|
46
|
+
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';
|
|
47
|
+
/** The properties whose value is a time, and so also take a number: milliseconds. */
|
|
48
|
+
type TimeProperty = 'animationDelay' | 'animationDuration' | 'transitionDelay' | 'transitionDuration';
|
|
49
|
+
/** The extra values of property `K`: `alpha()` for a color, a number of milliseconds for a time. */
|
|
50
|
+
type ExtraValue<K> = (K extends ColorProperty ? AlphaColor : never) | (K extends TimeProperty ? number : never);
|
|
51
|
+
/** Every CSS property, by its camelCase name, with its value type; a color property also takes `alpha()`, a time property a number of milliseconds. */
|
|
52
|
+
export type WebProperties = { [K in keyof CssProperties]?: K extends 'display' ? WebValue<DisplayValue> : WebValue<NonNullable<CssProperties[K]> | ExtraValue<K>>; };
|
|
53
|
+
/** What a nested key holds: a style of its own, or nothing (so `isOpen && { ... }` works). */
|
|
54
|
+
export type WebNested = WebStyleObject | null | undefined | false;
|
|
55
|
+
/**
|
|
56
|
+
* A style for the web: any CSS property, a custom property (`--name`), `label`, and nested styles under
|
|
57
|
+
* a selector (a key with `&`, or one that starts with `:`) or an at-rule (a key that starts with `@`).
|
|
58
|
+
* Any other key is an error in an object literal.
|
|
59
|
+
*/
|
|
60
|
+
export type WebStyleObject = WebProperties & {
|
|
61
|
+
/** Part of the class name, for a readable class in the developer tools. */
|
|
62
|
+
label?: string;
|
|
63
|
+
[key: `--${string}`]: string | number | AlphaColor | null | undefined | false;
|
|
64
|
+
[key: `${string}&${string}`]: WebNested;
|
|
65
|
+
[key: `:${string}`]: WebNested;
|
|
66
|
+
[key: `@${string}`]: WebNested;
|
|
67
|
+
};
|
|
68
|
+
/** A key that holds a nested style: a selector with `&`, one that starts with `:`, or an at-rule. */
|
|
69
|
+
export type NestedKey = `${string}&${string}` | `:${string}` | `@${string}`;
|
|
70
|
+
/**
|
|
71
|
+
* `{ [key]: style }` typed so that it can be spread into a web style. A key that is computed in an
|
|
72
|
+
* object literal has the type `string`, and the web style type rejects it (its custom property
|
|
73
|
+
* signature takes no style); the key here keeps its template literal type, and `style` is checked as a
|
|
74
|
+
* style of its own: `{ ...at(`@media (width >= ${breakpoint})`, { gap: 16 }) }`.
|
|
75
|
+
*/
|
|
76
|
+
export declare function at<K extends NestedKey>(key: K, style: WebNested): Record<K, WebNested>;
|
|
77
|
+
/** The two color schemes that a condition can name. */
|
|
78
|
+
export type SchemeName = 'light' | 'dark';
|
|
79
|
+
/** The key of a style that applies when the nearest theme is the one with this theme class: `@theme <themeClass>`. */
|
|
80
|
+
export type ThemeKey = `@theme ${string}`;
|
|
81
|
+
/** The key of a style that applies when the nearest color scheme is this one: `@scheme dark`. */
|
|
82
|
+
export type SchemeKey = `@scheme ${SchemeName}`;
|
|
83
|
+
/** What a condition key stands for. */
|
|
84
|
+
export type Condition = {
|
|
85
|
+
readonly kind: 'theme';
|
|
86
|
+
readonly id: string;
|
|
87
|
+
} | {
|
|
88
|
+
readonly kind: 'scheme';
|
|
89
|
+
readonly scheme: SchemeName;
|
|
90
|
+
};
|
|
91
|
+
/** The names a scope is written with: the prefix of the cache, and whether `@scope` is used. */
|
|
92
|
+
export interface Scoping {
|
|
93
|
+
/** The prefix of the cache; the marker classes start with it. */
|
|
94
|
+
readonly prefix: string;
|
|
95
|
+
/** Whether a conditional rule is written with `@scope`. Without it, a plain descendant selector. */
|
|
96
|
+
readonly hasScope: boolean;
|
|
97
|
+
}
|
|
98
|
+
/** The scoping of a cache that gave none: the default prefix, with `@scope`. */
|
|
99
|
+
export declare const DEFAULT_SCOPING: Scoping;
|
|
100
|
+
/** The key for "the nearest theme is the one of this theme class". */
|
|
101
|
+
export declare function createThemeKey(themeClass: string): ThemeKey;
|
|
102
|
+
/** The key for "the nearest color scheme is this one". */
|
|
103
|
+
export declare function createSchemeKey(scheme: SchemeName): SchemeKey;
|
|
104
|
+
/** The condition a style key stands for, or undefined for any other key. */
|
|
105
|
+
export declare function readCondition(key: string): Condition | undefined;
|
|
106
|
+
/** The class that every element with a theme carries, so that it can be a scope limit. */
|
|
107
|
+
export declare function getBoundaryClass(prefix: string): string;
|
|
108
|
+
/** The class of an element whose theme has a color scheme of its own. */
|
|
109
|
+
export declare function getSchemeClass(prefix: string, scheme: SchemeName): string;
|
|
110
|
+
/**
|
|
111
|
+
* The class string of a theme: its theme class, the boundary marker, and, when its color scheme is
|
|
112
|
+
* `light` or `dark`, the scheme marker. `light dark` and no scheme have no scheme marker.
|
|
113
|
+
*/
|
|
114
|
+
export declare function createThemeClassName(prefix: string, id: string, colorScheme?: string): string;
|
|
115
|
+
/**
|
|
116
|
+
* `rules` for the elements below the elements that match `start`, down to but not into the elements
|
|
117
|
+
* that match `limits`: `@scope (start) to (limits){rules}`. A limit is relative to the scope root, so
|
|
118
|
+
* the root is never cut off by its own marker (checked in a browser: `to (.x)` and `to (:scope .x)` agree).
|
|
119
|
+
*/
|
|
120
|
+
export declare function createScopeRule(start: string, limits: string, rules: readonly string[]): string;
|
|
121
|
+
/** The selector that matches an element with no scheme marker on it or above it. Its specificity is 0. */
|
|
122
|
+
export declare function createNoSchemeGuard(prefix: string): string;
|
|
123
|
+
export type StyleValue = string | number | AlphaColor | null | undefined | false | readonly (string | number | AlphaColor)[] | StyleObject;
|
|
124
|
+
export interface StyleObject {
|
|
125
|
+
[key: string]: StyleValue;
|
|
126
|
+
}
|
|
127
|
+
/** Merges style objects left to right; a later key wins and moves to the end; nested objects merge the same way. */
|
|
128
|
+
export declare function mergeStyles(styles: readonly StyleObject[]): StyleObject;
|
|
129
|
+
/**
|
|
130
|
+
* The flat CSS rules of `style` for `selector`; without `hasColorFallbacks` an `alpha()` result is
|
|
131
|
+
* written as its mix alone. A `when()` or `whenScheme()` key becomes a scoped rule, written as
|
|
132
|
+
* `scoping` says. With `hasValueRepair` the string forms of token maths that are never valid CSS
|
|
133
|
+
* (`var(--x)1F`, `-var(--x)`, `var(--x)ms`) are rewritten in each value.
|
|
134
|
+
*/
|
|
135
|
+
export declare function compileRules(selector: string, style: StyleObject, hasColorFallbacks?: boolean, scoping?: Scoping, hasValueRepair?: boolean): string[];
|
|
136
|
+
/** The label of `style` (its `label` key), or ''. */
|
|
137
|
+
export declare function readLabel(style: StyleObject): string;
|
|
138
|
+
/** The two ways an entry is used: on its own (a plain element, `apply`), or given to a styled component through `style`. */
|
|
139
|
+
export type EntryRole = 'components' | 'overrides';
|
|
140
|
+
/** What a cache gives an entry that it made: the style, and the class of each role, written on first use. */
|
|
141
|
+
export interface EntrySource {
|
|
142
|
+
/** The style of the entry, merged. */
|
|
143
|
+
readonly style: StyleObject;
|
|
144
|
+
/** The cache that made the entry, whose rules `use` writes. */
|
|
145
|
+
readonly cache: Cache;
|
|
146
|
+
/** The class name for `role`; its rule is written, once, the first time it is asked for. */
|
|
147
|
+
use(role: EntryRole): string;
|
|
148
|
+
}
|
|
149
|
+
/** One style of a sheet: it carries the class name that the cache made for it, and nothing else. */
|
|
150
|
+
export interface SheetEntry {
|
|
151
|
+
/** The class name of the entry used on its own. Reading it writes its rule, if that was not written yet. */
|
|
152
|
+
readonly className: string;
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Makes the entry of a class name: a frozen object that `isSheetEntry` knows and that prints as the
|
|
156
|
+
* class name. Its one enumerable key is a custom property named after the class, with the value `null`,
|
|
157
|
+
* so that a framework that merges the style objects of an array (Vue does) keeps every entry, and
|
|
158
|
+
* `flattenStyle` finds them by the key. Both frameworks skip a `null` style value on a plain element, on
|
|
159
|
+
* the client and on the server, so an entry given to a plain element renders no style attribute. With a
|
|
160
|
+
* `source` (a cache made it) the class name is read through it, so that the rule is written when the entry
|
|
161
|
+
* is used, not when it is made; without one the entry is just the name.
|
|
162
|
+
*/
|
|
163
|
+
export declare function createSheetEntry(className: string, source?: EntrySource): SheetEntry;
|
|
164
|
+
/** Whether `value` was made by `createSheetEntry`: a class name is a plain string, a style object has no brand. */
|
|
165
|
+
export declare function isSheetEntry(value: unknown): value is SheetEntry;
|
|
166
|
+
/** What a cache gave `entry` to make its classes, or undefined for an entry that is only a name. */
|
|
167
|
+
export declare function readEntrySource(entry: SheetEntry): EntrySource | undefined;
|
|
168
|
+
/** The cache that made the first entry among `values` that a cache made, or undefined when there is none. */
|
|
169
|
+
export declare function findEntryCache(values: readonly unknown[]): Cache | undefined;
|
|
170
|
+
/**
|
|
171
|
+
* The style of `value` when it is a sheet entry, else `value` as it is: for a place that takes a style
|
|
172
|
+
* object and so also an entry. Throws a `TypeError`, that names `caller`, for an entry that is only a class
|
|
173
|
+
* name (one that no cache made), whose style is not known.
|
|
174
|
+
*/
|
|
175
|
+
export declare function readEntryStyle(value: unknown, caller: string): unknown;
|
|
176
|
+
/**
|
|
177
|
+
* What a `style` prop holds, as a flat list in order, for the cache to merge into one class: sheet
|
|
178
|
+
* entries and plain style objects, with arrays flattened and what is empty dropped. An object in which a
|
|
179
|
+
* framework merged entries and plain keys (Vue does) is split back into its entries, then the rest; an
|
|
180
|
+
* entry is looked up by its class name with `findEntry` (a cache's `findEntry`), else it is only the name.
|
|
181
|
+
* A string is an error: a text style cannot be merged into a class.
|
|
182
|
+
*/
|
|
183
|
+
export declare function flattenStyle(style: unknown, findEntry?: (className: string) => SheetEntry | undefined): (SheetEntry | WebStyleObject)[];
|
|
184
|
+
/** One step of an animation: properties and custom properties, written as in a style. It holds no nested style. */
|
|
185
|
+
type KeyframesStep = WebProperties & {
|
|
186
|
+
[key: `--${string}`]: string | number | AlphaColor | null | undefined | false;
|
|
187
|
+
};
|
|
188
|
+
/** The steps of an animation, by offset: `from`, `to`, a percentage (`'50%'`), or a comma list of them (`'0%, 100%'`). */
|
|
189
|
+
type KeyframesSteps = Record<string, KeyframesStep>;
|
|
190
|
+
/** What `keyframes` is given: the steps, or a function of the theme that returns them. */
|
|
191
|
+
type KeyframesInput<T> = KeyframesSteps | ((theme: T) => KeyframesSteps);
|
|
192
|
+
interface KeyframesOptions {
|
|
193
|
+
/** The first part of the name, for a readable name in the developer tools. Default `keyframes`. */
|
|
194
|
+
label?: string;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Registers an animation and returns its name, `<label>-<hash>`, at once: nothing is written until a
|
|
198
|
+
* class that names it in `animation` or `animation-name` is inserted. The hash is made from the steps
|
|
199
|
+
* alone, so it does not depend on the theme, the prefix or the token options; a function of the theme is
|
|
200
|
+
* called for it with a stand-in theme whose every token is its own path as text. Equal steps give the same
|
|
201
|
+
* name. As a tag, the template is read as steps (`parseKeyframesTemplate`), and gives the name of the
|
|
202
|
+
* equal object. Throws a `TypeError` for a step that is not one, a nested style in a step, or a label
|
|
203
|
+
* that is not an identifier.
|
|
204
|
+
*/
|
|
205
|
+
export declare function keyframes<T = never>(steps: (theme: T) => KeyframesSteps, options?: KeyframesOptions): string;
|
|
206
|
+
export declare function keyframes<T = never>(template: TemplateStringsArray, ...values: TemplateValue<unknown, T>[]): string;
|
|
207
|
+
export declare function keyframes<T = never>(steps: KeyframesInput<T>, options?: KeyframesOptions): string;
|
|
208
|
+
/** The syntax of a registered custom property, which gives its variable a type so that it can be animated. */
|
|
209
|
+
type RegisteredSyntax = '<color>' | '<length>' | '<number>' | '<percentage>' | '<length-percentage>' | '<angle>' | '<time>' | '*';
|
|
210
|
+
/** 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. */
|
|
211
|
+
export type TokenMode = 'variable' | 'inline' | 'reference' | 'raw';
|
|
212
|
+
export interface TokenOptions {
|
|
213
|
+
/** Put before every variable name, e.g. 'ds' gives --ds-palette-primary. */
|
|
214
|
+
prefix?: string;
|
|
215
|
+
/** Top-level theme keys that stay real values and get no variable: the same as mode `raw`. Default ['breakpoints', 'components']. */
|
|
216
|
+
rawKeys?: readonly string[];
|
|
217
|
+
/** Top-level theme keys whose numbers are lengths, declared with px. Default ['space', 'sizes', 'radii', 'fontSizes', 'borderWidths']. */
|
|
218
|
+
lengthKeys?: readonly string[];
|
|
219
|
+
/**
|
|
220
|
+
* The mode of a token, by dotted theme path ('zIndex', 'transitions.duration', 'palette.primary').
|
|
221
|
+
* The most specific path wins, and an entry beats `rawKeys`. Default mode: `variable`.
|
|
222
|
+
*/
|
|
223
|
+
modes?: Readonly<Record<string, TokenMode>>;
|
|
224
|
+
/**
|
|
225
|
+
* The tokens that are registered custom properties (an `@property` rule), by dotted theme path, found
|
|
226
|
+
* like `modes` (the most specific path wins; a top-level key registers everything under it). `true`
|
|
227
|
+
* infers the syntax from the base theme value, otherwise it is one of the syntaxes. A registered
|
|
228
|
+
* variable has a type, so a `transition` on it animates a theme switch. Only variable and reference
|
|
229
|
+
* tokens have a variable to register.
|
|
230
|
+
*/
|
|
231
|
+
registered?: Readonly<Record<string, RegisteredSyntax | true>>;
|
|
232
|
+
}
|
|
233
|
+
export type DeepPartial<T> = T extends ((...args: never[]) => unknown) ? T : T extends object ? { [K in keyof T]?: DeepPartial<T[K]>; } : T;
|
|
234
|
+
export interface Tokens<T> {
|
|
235
|
+
/** 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. */
|
|
236
|
+
refs: T;
|
|
237
|
+
/** The variable declarations of `theme`, which may be a partial theme: only the variable and reference tokens it has. */
|
|
238
|
+
declare(theme: DeepPartial<T>): Record<string, string>;
|
|
239
|
+
/** The shape of `realTheme` like `refs`: the same references (a fallback is the base value), the real values of `realTheme` for the rest. */
|
|
240
|
+
createView(realTheme: T): T;
|
|
241
|
+
/** The names of the variables of the base theme under these dotted paths (a top-level key or a deeper path). */
|
|
242
|
+
findNames(paths: readonly string[]): string[];
|
|
243
|
+
/** The `@property` rule of each registered variable of the base theme, by variable name. */
|
|
244
|
+
registrations: Readonly<Record<string, string>>;
|
|
245
|
+
}
|
|
246
|
+
/** Turns a theme into variable references and the declarations that give them values. */
|
|
247
|
+
export declare function createTokens<T extends object>(theme: T, options?: TokenOptions): Tokens<T>;
|
|
248
|
+
export interface EngineOptions extends TokenOptions {
|
|
249
|
+
/** First part of every class name and variable name. Default 'css'. */
|
|
250
|
+
prefix?: string;
|
|
251
|
+
/** Appended to every class name. */
|
|
252
|
+
suffix?: string;
|
|
253
|
+
/** Whether a style's label is part of its class name. */
|
|
254
|
+
hasLabels?: boolean;
|
|
255
|
+
/** Whether every rule goes into a cascade layer. Default true. */
|
|
256
|
+
hasLayers?: boolean;
|
|
257
|
+
/** Whether an `alpha()` value is written as a fallback and then the color-mix() value. Default true; used when the engine makes its cache. */
|
|
258
|
+
hasColorFallbacks?: boolean;
|
|
259
|
+
/** Whether the string forms of token maths that are never valid CSS (`var(--x)1F`, `-var(--x)`, `var(--x)ms`) are rewritten in each value. Default false; used when the engine makes its cache. */
|
|
260
|
+
hasValueRepair?: boolean;
|
|
261
|
+
/** 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. */
|
|
262
|
+
hasScope?: boolean;
|
|
263
|
+
/** Whether a theme class declares only the variables that rules refer to. Default true; used when the engine makes its cache. */
|
|
264
|
+
hasPruning?: boolean;
|
|
265
|
+
/** 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. */
|
|
266
|
+
hasBaseClass?: boolean;
|
|
267
|
+
/** Whether the cache checks the page in the browser and warns once for each problem found (`findMissingStyles`, and each inserted declaration that `CSS.supports` rejects). Default: on in development (`process.env.NODE_ENV` is `development`), off otherwise; used when the engine makes its cache. */
|
|
268
|
+
hasDevChecks?: boolean;
|
|
269
|
+
/** Theme paths (dotted, or top-level keys) whose variables are always declared, for code outside the engine that reads them. */
|
|
270
|
+
alwaysDeclare?: readonly string[];
|
|
271
|
+
/** The cache to use; one is made when not given. */
|
|
272
|
+
cache?: Cache;
|
|
273
|
+
}
|
|
274
|
+
export type ColorScheme = 'light' | 'dark' | 'light dark';
|
|
275
|
+
/** What a style function may return. */
|
|
276
|
+
export type StyleResult = WebStyleObject | null | undefined | false;
|
|
277
|
+
/** A style that is computed from the props and the theme. */
|
|
278
|
+
export type StyleFunction<T, P> = (props: P & {
|
|
279
|
+
theme: T;
|
|
280
|
+
}) => StyleResult;
|
|
281
|
+
/** A style object, or a function of the props and the theme; the defaults accept any function. */
|
|
282
|
+
export type StyleInput<T = never, P = never> = WebStyleObject | StyleFunction<T, P>;
|
|
283
|
+
/** The label of a styled component, and what it takes from the styles of the one it wraps. */
|
|
284
|
+
export interface StylerOptions {
|
|
285
|
+
/** With `slot`, the label of the class: `name-slot` in kebab-case. */
|
|
286
|
+
name?: string;
|
|
287
|
+
/** Default 'root'. */
|
|
288
|
+
slot?: string;
|
|
289
|
+
}
|
|
290
|
+
export type SheetStyles = Record<string, WebStyleObject>;
|
|
291
|
+
/**
|
|
292
|
+
* What a sheet is made from: one style for each name, or a function of the theme that returns them. The
|
|
293
|
+
* names are the type parameter, so that an object literal given here is checked key by key.
|
|
294
|
+
*/
|
|
295
|
+
export type SheetInput<K extends string, T> = Record<K, WebStyleObject> | ((theme: T) => Record<K, WebStyleObject>);
|
|
296
|
+
/**
|
|
297
|
+
* A sheet given as an object: one style for each name. It is a record of styles with a function
|
|
298
|
+
* left out, so that a function of the theme is not taken for one (the compiler tries the object form first).
|
|
299
|
+
*/
|
|
300
|
+
export type ObjectSheet<K extends string> = Record<K, WebStyleObject> & {
|
|
301
|
+
call?: never;
|
|
302
|
+
};
|
|
303
|
+
/** The entries of a sheet, by name: each is made on first access, and its rule is written when it is first used. */
|
|
304
|
+
export type SheetEntries<K extends string> = { readonly [P in K]: SheetEntry; };
|
|
305
|
+
/** A sheet made from a function of the theme: it has no entries until it is resolved against a theme, which `useStyle` does. */
|
|
306
|
+
export interface ThemedSheet<K extends string, T> {
|
|
307
|
+
/** The entries, against `theme` (a theme view) when given, else against the base theme. */
|
|
308
|
+
resolve(theme?: T): SheetEntries<K>;
|
|
309
|
+
}
|
|
310
|
+
/**
|
|
311
|
+
* The shape of the theme of an app. It has no members of its own (the optional one below only keeps it
|
|
312
|
+
* from being empty): an app adds its own by merging, with
|
|
313
|
+
* `declare module '@umber-style/core' { interface Theme extends MyTheme {} }`.
|
|
314
|
+
*/
|
|
315
|
+
export interface Theme {
|
|
316
|
+
readonly _theme?: never;
|
|
317
|
+
}
|
|
318
|
+
/** A style written as an object, on the web: `WebStyleObject`, under the name apps annotate a style with. */
|
|
319
|
+
export type CSSObject = WebStyleObject;
|
|
320
|
+
/** What `keyframes` returns: the name of the animation, a plain string. */
|
|
321
|
+
export type Keyframes = ReturnType<typeof keyframes>;
|
|
322
|
+
/**
|
|
323
|
+
* What `css()` of a web binding returns: a sheet entry of the merged style. It prints as its class name,
|
|
324
|
+
* and goes wherever an entry goes: the `style` prop of a styled component, `apply`, another `css()`.
|
|
325
|
+
*/
|
|
326
|
+
export type SerializedStyles = SheetEntry;
|
|
327
|
+
/** What a style function may return: a style object, a `css()` result or a sheet entry, or nothing. */
|
|
328
|
+
export type InterpolationResult = CSSObject | SerializedStyles | null | undefined | false;
|
|
329
|
+
/**
|
|
330
|
+
* A style in any form that `styled` takes: a style object, a `css()` result or a sheet entry, a function
|
|
331
|
+
* of the props and the theme, nothing, or a list of them. `css()` takes the same without functions
|
|
332
|
+
* (`CssArgument`): it has no props.
|
|
333
|
+
*/
|
|
334
|
+
export type Interpolation<Props = unknown, T = Theme> = InterpolationResult | ((props: Props & {
|
|
335
|
+
theme: T;
|
|
336
|
+
}) => InterpolationResult) | readonly Interpolation<Props, T>[];
|
|
337
|
+
/** What `css()` of a binding takes: style objects, `css()` results and sheet entries, nothing, and lists of them. */
|
|
338
|
+
export type CssArgument = InterpolationResult | readonly CssArgument[];
|
|
339
|
+
/** A component that stands for a selector in a template or a key: a styled component prints as `.<class>`. */
|
|
340
|
+
export interface ComponentSelector {
|
|
341
|
+
readonly _styles: readonly unknown[];
|
|
342
|
+
}
|
|
343
|
+
/**
|
|
344
|
+
* What a tagged template given to `css`, `keyframes` or `globalStyles` takes between its strings: text
|
|
345
|
+
* and numbers, a style object or a `css()` result (merged where it stands alone between declarations), an
|
|
346
|
+
* `alpha()` result, a `keyframes` name, a styled component (its selector), nothing (`null`, `undefined`,
|
|
347
|
+
* `true`, `false`), and lists of them.
|
|
348
|
+
*/
|
|
349
|
+
export type StaticTemplateValue = string | number | boolean | null | undefined | CSSObject | SerializedStyles | AlphaColor | ComponentSelector | readonly StaticTemplateValue[];
|
|
350
|
+
/**
|
|
351
|
+
* What a tagged template given to `styled` takes between its strings: what `StaticTemplateValue` lists,
|
|
352
|
+
* and a function of the props and the theme that returns one of them. A `keyframes` or `globalStyles`
|
|
353
|
+
* template calls such a function with `{ theme }`.
|
|
354
|
+
*/
|
|
355
|
+
export type TemplateValue<Props = unknown, T = Theme> = StaticTemplateValue | ((props: Props & {
|
|
356
|
+
theme: T;
|
|
357
|
+
}) => TemplateValue<Props, T>) | readonly TemplateValue<Props, T>[];
|
|
358
|
+
/** The descriptors of an at-rule that takes them (`@font-face`, `@page`, `@counter-style`, `@font-palette-values`), by camelCase name. */
|
|
359
|
+
type AtRuleDescriptors = CSS.AtRule.FontFace<string | number> | CSS.AtRule.Page<string | number> | CSS.AtRule.CounterStyle<string | number> | CSS.AtRule.FontPaletteValues<string | number>;
|
|
360
|
+
/**
|
|
361
|
+
* What a key of global styles holds: the style of a selector (an object, or a `css()` result or sheet
|
|
362
|
+
* entry, whose style is used), the styles that an at-rule such as `@media` holds (selectors as keys), the
|
|
363
|
+
* descriptors of an at-rule such as `@font-face`, or a list of those (an at-rule written once for each,
|
|
364
|
+
* because an object cannot hold the same key twice).
|
|
365
|
+
*/
|
|
366
|
+
type GlobalStyleValue = WebStyleObject | SheetEntry | GlobalStyleObject | AtRuleDescriptors | readonly (WebStyleObject | SheetEntry | AtRuleDescriptors)[] | null | undefined | false;
|
|
367
|
+
/**
|
|
368
|
+
* Styles that are not a class: selectors (`body`, `html, body`, `*, *::before, *::after`, `#root`) and
|
|
369
|
+
* at-rules (`@media (...)` holding selectors, `@supports`, `@font-face`) as keys. A selector's style is
|
|
370
|
+
* written as a class's is: `&` in a nested key stands for the selector.
|
|
371
|
+
*/
|
|
372
|
+
interface GlobalStyleObject {
|
|
373
|
+
[key: string]: GlobalStyleValue;
|
|
374
|
+
}
|
|
375
|
+
/** What `globalStyles` is given: the styles, or a function of the theme that returns them. */
|
|
376
|
+
type GlobalStylesInput<T> = GlobalStyleObject | ((theme: T) => GlobalStyleObject);
|
|
377
|
+
/** Global styles that `globalStyles` made: frozen, and identified by their content. */
|
|
378
|
+
interface GlobalStyles<T = never> {
|
|
379
|
+
/** `global-<hash>`, made from the styles alone (a function of the theme is read with a stand-in theme): equal styles give an equal id. */
|
|
380
|
+
readonly id: string;
|
|
381
|
+
/** The styles: those given, or what the function returns for the theme that `readTheme` gives, which is called only then. */
|
|
382
|
+
resolve(readTheme: () => T): GlobalStyleObject;
|
|
383
|
+
}
|
|
384
|
+
/** Global styles in any form an engine takes: a handle, an object, a function of the theme, or a list of them, written in the order of the list. */
|
|
385
|
+
type GlobalInput<T> = GlobalStyles<T> | GlobalStylesInput<T> | readonly (GlobalStyles<T> | GlobalStylesInput<T>)[];
|
|
386
|
+
/**
|
|
387
|
+
* Makes global styles and returns their handle at once: nothing is written until an engine is given the
|
|
388
|
+
* handle (`insertGlobal`), so a module can call it before there is an engine or a theme. The id is made
|
|
389
|
+
* from the styles alone; a function of the theme is called for it with a stand-in theme whose every token
|
|
390
|
+
* is its own path as text. As a tag, the template is read as CSS text (`parseStyleTemplate`): selectors
|
|
391
|
+
* and at-rules with their blocks, and a function among the interpolations is called with `{ theme }`.
|
|
392
|
+
* Throws a `TypeError` for styles that are not an object or a function.
|
|
393
|
+
*/
|
|
394
|
+
export declare function globalStyles<T = never>(styles: (theme: T) => GlobalStyleObject): GlobalStyles<T>;
|
|
395
|
+
export declare function globalStyles<T = never>(template: TemplateStringsArray, ...values: TemplateValue<unknown, T>[]): GlobalStyles<T>;
|
|
396
|
+
export declare function globalStyles<T = never>(styles: GlobalStylesInput<T>): GlobalStyles<T>;
|
|
397
|
+
export interface CacheOptions {
|
|
398
|
+
/** First part of every class name. Default 'css'. Must match /^[a-z][a-z0-9-]*$/ or createCache throws. */
|
|
399
|
+
prefix?: string;
|
|
400
|
+
/** Appended to every class name. Default ''. */
|
|
401
|
+
suffix?: string;
|
|
402
|
+
/** Whether a style's label is part of its class name. Default true. */
|
|
403
|
+
hasLabels?: boolean;
|
|
404
|
+
/** Whether every rule goes into a cascade layer (`<prefix>-theme`, `-global`, `-components`, `-overrides`). Default true. */
|
|
405
|
+
hasLayers?: boolean;
|
|
406
|
+
/**
|
|
407
|
+
* Whether a theme class declares only the variables that rules refer to (and those marked with
|
|
408
|
+
* `markUsed`), appending more as rules come in. Default true. Without it, a theme class declares every token.
|
|
409
|
+
*/
|
|
410
|
+
hasPruning?: boolean;
|
|
411
|
+
/**
|
|
412
|
+
* Whether a property whose value is `alpha()` gets two declarations, the fallback first (rgba() for a
|
|
413
|
+
* literal colour, else the colour itself) and then the color-mix() value, for a browser without
|
|
414
|
+
* color-mix(). Default true. Without it only the color-mix() value is written.
|
|
415
|
+
*/
|
|
416
|
+
hasColorFallbacks?: boolean;
|
|
417
|
+
/**
|
|
418
|
+
* Whether the string forms of token maths that are never valid CSS are rewritten in each value: a
|
|
419
|
+
* reference followed by two hex digits (`var(--x)1F`) as `alpha()` writes it, a minus before a
|
|
420
|
+
* reference (`-var(--x)`) as `negate()` writes it, and a reference followed by `ms` or `s` as a
|
|
421
|
+
* `calc()` of a time. Custom properties are left alone. Default false.
|
|
422
|
+
*/
|
|
423
|
+
hasValueRepair?: boolean;
|
|
424
|
+
/**
|
|
425
|
+
* Whether a style written with `when()` or `whenScheme()` is scoped with `@scope`, so that it follows the
|
|
426
|
+
* nearest theme. Default true. Without it the rule is the plain descendant form `:where(.theme) .class`,
|
|
427
|
+
* which also matches below a nested theme, and so is wrong for nested themes. A browser without `@scope`
|
|
428
|
+
* drops the scoped rules and keeps the rest.
|
|
429
|
+
*/
|
|
430
|
+
hasScope?: boolean;
|
|
431
|
+
/**
|
|
432
|
+
* Whether a styled component's style list is split by position into a base class (the plain objects
|
|
433
|
+
* before the first function, made once) and a props class (the rest, made for each render), both in the
|
|
434
|
+
* `components` layer. Default true. Without it the whole list is one class, as before. The cache only
|
|
435
|
+
* holds the option; the engine's `createStyler` reads it.
|
|
436
|
+
*/
|
|
437
|
+
hasBaseClass?: boolean;
|
|
438
|
+
/**
|
|
439
|
+
* Whether the cache checks the page while it runs in a browser, and warns once for each problem found
|
|
440
|
+
* (`findMissingStyles`: an engine class that has no rule, a variable that has no value; `CSS.supports`: an inserted declaration that the browser does not support), throttled,
|
|
441
|
+
* after the first render and when rules are inserted. Default: on in development (`process.env.NODE_ENV`
|
|
442
|
+
* is not `production`), off in production, and off where there is no `document`.
|
|
443
|
+
*/
|
|
444
|
+
hasDevChecks?: boolean;
|
|
445
|
+
/** 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. */
|
|
446
|
+
tokenSignature?: string;
|
|
447
|
+
/** Where rules go. Default: a DOM sheet when `document` exists, otherwise an in-memory one. */
|
|
448
|
+
sheet?: Sheet;
|
|
449
|
+
/**
|
|
450
|
+
* Called after each group of rules the cache writes to its sheet, with a name for the group and its
|
|
451
|
+
* CSS text as written: the layer order statement (`<prefix>-layers`), a class, a theme class (each time
|
|
452
|
+
* variables are added to it, the first time under the class name, later under `<class>-<hash>`), a set
|
|
453
|
+
* of global rules (its id), a `@keyframes` rule (`@keyframes:<name>`) and a `@property` rule
|
|
454
|
+
* (`@property:<variable>:<hash>`). Rules that the page has, and so are not written, are not reported.
|
|
455
|
+
*/
|
|
456
|
+
onInsert?: (name: string, css: string) => void;
|
|
457
|
+
}
|
|
458
|
+
/** A part of the CSS of a page, and the ids it covers. */
|
|
459
|
+
export interface PagePart {
|
|
460
|
+
css: string;
|
|
461
|
+
ids: string[];
|
|
462
|
+
}
|
|
463
|
+
/** The CSS of a page in two parts, which make `extractPage` when joined in this order. */
|
|
464
|
+
export interface PageParts {
|
|
465
|
+
/** What no class of the page stands for: the layer order, the `@property` and `@keyframes` rules, the theme classes and the global rules; its ids are the theme classes and the global ids. */
|
|
466
|
+
global: PagePart;
|
|
467
|
+
/** The rules of the classes of the page; its ids are the classes. */
|
|
468
|
+
classes: PagePart;
|
|
469
|
+
}
|
|
470
|
+
/** What `extractPage` is told besides the classes of the page. */
|
|
471
|
+
export interface PageExtractOptions {
|
|
472
|
+
/** Theme classes to include although no element has them (the themes the page offers for switching). */
|
|
473
|
+
themes?: Iterable<string>;
|
|
474
|
+
/** Animation names (`keyframes` results) to include although no class of the page uses them. */
|
|
475
|
+
animations?: Iterable<string>;
|
|
476
|
+
/** Keys of the `<style href precedence>` elements that the document carries already (classes, theme classes, animation names, ids of global rules): their rules are left out. */
|
|
477
|
+
carried?: ReadonlySet<string>;
|
|
478
|
+
/**
|
|
479
|
+
* The ids of the sets of global rules that the page rendered without a style element (the markers of
|
|
480
|
+
* `Global`). A set that a component inserted (`isRendered`) is part of a page only when the page
|
|
481
|
+
* carries it or names it here; a set inserted for the app is part of every page.
|
|
482
|
+
*/
|
|
483
|
+
rendered?: ReadonlySet<string>;
|
|
484
|
+
}
|
|
485
|
+
/** How `insertGlobal` writes a set of global rules. */
|
|
486
|
+
export interface GlobalInsertOptions {
|
|
487
|
+
/**
|
|
488
|
+
* Whether a component rendered the set (`Global`), so that it belongs to the pages that render it: a
|
|
489
|
+
* page's CSS (`extractPage`) holds it only when the page carries it or names it in `rendered`. Default
|
|
490
|
+
* false: a set inserted for the app, which is part of every page while it is held.
|
|
491
|
+
*/
|
|
492
|
+
isRendered?: boolean;
|
|
493
|
+
}
|
|
494
|
+
export interface Sheet {
|
|
495
|
+
insert(rule: string): void;
|
|
496
|
+
/** Every rule inserted so far and not removed, in order. */
|
|
497
|
+
readonly rules: readonly string[];
|
|
498
|
+
/** Replaces the rule inserted at `index` of `rules`; a sheet that cannot (a browser one) has none, and the cache appends instead. */
|
|
499
|
+
replace?(index: number, rule: string): void;
|
|
500
|
+
/**
|
|
501
|
+
* Removes the rule at `index` of `rules`: the rules after it move down by one, in `rules` and in what
|
|
502
|
+
* the sheet holds. A sheet without it keeps every rule: global rules that are released then stay, and
|
|
503
|
+
* count as written, and every class is permanent (see `Cache.cssHeld`).
|
|
504
|
+
*/
|
|
505
|
+
remove?(index: number): void;
|
|
506
|
+
/**
|
|
507
|
+
* The document whose style element holds the rules (`createDomSheet` gives the document of its
|
|
508
|
+
* container). The cache reads that document: the style elements a server left there, the stamp of its
|
|
509
|
+
* options, and in development the check of the page. None for a sheet in memory: the cache then reads
|
|
510
|
+
* the global `document`, where there is one.
|
|
511
|
+
*/
|
|
512
|
+
readonly document?: Document;
|
|
513
|
+
}
|
|
514
|
+
/** The rules of one set of global styles, resolved for a theme. */
|
|
515
|
+
export interface GlobalRules {
|
|
516
|
+
/** `<prefix>-global-<hash>`, a hash of `rules`: equal rules have an equal id. A style element that holds them is keyed by it. */
|
|
517
|
+
readonly id: string;
|
|
518
|
+
/** The rules, each in the `global` layer when the cache has layers. */
|
|
519
|
+
readonly rules: readonly string[];
|
|
520
|
+
/** The animation names (`keyframes` results) that the rules use, whose `@keyframes` rules are written with them. */
|
|
521
|
+
readonly animations: readonly string[];
|
|
522
|
+
}
|
|
523
|
+
/** The cascade layers of a cache, from the lowest priority to the highest. */
|
|
524
|
+
export declare const RULE_LAYERS: readonly ['theme', 'global', 'components', 'overrides'];
|
|
525
|
+
export type RuleLayer = (typeof RULE_LAYERS)[number];
|
|
526
|
+
/** The layers that a class can be made in: the styles of a component, and what is given to it from outside. */
|
|
527
|
+
export type ClassLayer = 'components' | 'overrides';
|
|
528
|
+
export type ClassValue = WebStyleObject | SheetEntry | string | null | undefined | false;
|
|
529
|
+
/** How `cssWith` makes a class, beyond what is in it. */
|
|
530
|
+
export interface ClassOptions {
|
|
531
|
+
/** The layer of the class. Default `components`. */
|
|
532
|
+
layer?: ClassLayer;
|
|
533
|
+
/** A label for the class; it wins over the labels of the values. */
|
|
534
|
+
label?: string;
|
|
535
|
+
/**
|
|
536
|
+
* A class of this cache that is written before this one, and that this one is only used with (the base
|
|
537
|
+
* class of a component, for its props class). It is part of the name, so that the same styles after two
|
|
538
|
+
* different classes are two classes, each written after its own; and a sheet entry is merged in, never
|
|
539
|
+
* used as it is, because its own class may have been written before `after`.
|
|
540
|
+
*/
|
|
541
|
+
after?: string;
|
|
542
|
+
}
|
|
543
|
+
/** A class that elements hold while they use it (see `Cache.cssHeld`). */
|
|
544
|
+
export interface HeldClass {
|
|
545
|
+
/** The class names, as `cssWith` returns them. */
|
|
546
|
+
readonly className: string;
|
|
547
|
+
/**
|
|
548
|
+
* Counts one element that uses the class, and returns the function that lets it go (once; a second
|
|
549
|
+
* call does nothing). The same function for every element while the class lives. Undefined when the
|
|
550
|
+
* class is not held: it stays for good.
|
|
551
|
+
*/
|
|
552
|
+
readonly hold: (() => () => void) | undefined;
|
|
553
|
+
}
|
|
554
|
+
export interface Cache {
|
|
555
|
+
readonly prefix: string;
|
|
556
|
+
/** Whether rules go into cascade layers. */
|
|
557
|
+
readonly hasLayers: boolean;
|
|
558
|
+
/** The statement that declares the layers in order, `@layer <prefix>-theme,...;`, or '' without layers. It is the first rule of the sheet. */
|
|
559
|
+
readonly layerOrder: string;
|
|
560
|
+
/** The style object of each class this cache made, by class name. */
|
|
561
|
+
readonly registered: ReadonlyMap<string, StyleObject>;
|
|
562
|
+
/**
|
|
563
|
+
* One class for all of `values`: style objects, and class names this cache made (resolved back
|
|
564
|
+
* to their styles), merged left to right so the last wins. Other class names pass through in
|
|
565
|
+
* front of it. Returns '' when there is nothing. The class is in the `components` layer.
|
|
566
|
+
*/
|
|
567
|
+
css(...values: ClassValue[]): string;
|
|
568
|
+
/** `css`, with the layer of the class given: `overrides` for what a component is given from outside. */
|
|
569
|
+
cssIn(layer: ClassLayer, ...values: ClassValue[]): string;
|
|
570
|
+
/**
|
|
571
|
+
* `cssIn` with more to say about the class (see `ClassOptions`). When `values` is exactly one sheet
|
|
572
|
+
* entry (and class names that are not the cache's) and there is no `after`, no class is made: the class
|
|
573
|
+
* of the entry for that layer is used, and written if it was not.
|
|
574
|
+
*/
|
|
575
|
+
cssWith(options: ClassOptions, ...values: ClassValue[]): string;
|
|
576
|
+
/**
|
|
577
|
+
* `cssWith` for a class that lives only while elements use it: what a styled component is given as a
|
|
578
|
+
* plain object in `style`, so that a value that changes leaves no class behind. The class is written
|
|
579
|
+
* now, as `cssWith` writes it, and `hold` counts each element that uses it. When the count falls to
|
|
580
|
+
* zero, the class is removed after one macrotask (a `setTimeout` of 0), unless it is held again
|
|
581
|
+
* before: its rules leave the sheet, and the class is forgotten (`registered`, `extract`), so the same
|
|
582
|
+
* styles later write it again. A class that is not held within that delay is removed too, so a render
|
|
583
|
+
* that never commits leaves nothing; `hold` writes the class again when it was removed meanwhile.
|
|
584
|
+
*
|
|
585
|
+
* A class that a server render left on the page is taken over: it is not removed before it was held,
|
|
586
|
+
* and at the last release its rules are deleted from the page, unless they cannot all be found there
|
|
587
|
+
* (then they stay). Permanent, with no `hold`: the class of one sheet entry given alone, a class that
|
|
588
|
+
* `cssWith` or an entry made (one that `cssWith` makes later becomes permanent), and every class when
|
|
589
|
+
* the sheet has no `remove`.
|
|
590
|
+
*/
|
|
591
|
+
cssHeld(options: Omit<ClassOptions, 'after'>, ...values: ClassValue[]): HeldClass;
|
|
592
|
+
/** 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. */
|
|
593
|
+
createEntry(style: WebStyleObject): SheetEntry;
|
|
594
|
+
/** 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. */
|
|
595
|
+
findEntry(className: string): SheetEntry | undefined;
|
|
596
|
+
/**
|
|
597
|
+
* This cache's entry for the style of `entry`: `entry` itself when this cache made it (or no cache did:
|
|
598
|
+
* it is only a name), else an entry of this cache for the same style, made once for each entry, so that
|
|
599
|
+
* its rule is written here and not in the cache that made `entry`. The cache does this itself for every
|
|
600
|
+
* entry it is given; a binding calls it for entries that it hands on (a sheet under a cache provider).
|
|
601
|
+
*/
|
|
602
|
+
adoptEntry(entry: SheetEntry): SheetEntry;
|
|
603
|
+
/** Whether a component's styles are split into a base class and a props class. */
|
|
604
|
+
readonly hasBaseClass: boolean;
|
|
605
|
+
/**
|
|
606
|
+
* Inserts `rules` once under `id`; returns whether it inserted them. With a `layer` (and layers on)
|
|
607
|
+
* each rule is wrapped in it. Without one the rules are written as they are, outside every layer:
|
|
608
|
+
* the place of an at-rule that is not a layer's to hold, such as `@property`.
|
|
609
|
+
*/
|
|
610
|
+
insertOnce(id: string, rules: readonly string[], layer?: RuleLayer): boolean;
|
|
611
|
+
/** The rules this cache inserted under `id` (a class name), or none: for a style element that a server component renders. */
|
|
612
|
+
getRules(id: string): readonly string[];
|
|
613
|
+
/** Whether conditional rules are written with `@scope`. */
|
|
614
|
+
readonly hasScope: boolean;
|
|
615
|
+
/** Whether theme classes declare only the variables in use. */
|
|
616
|
+
readonly hasPruning: boolean;
|
|
617
|
+
/** The names of the variables that rules refer to, or that were marked: the only ones a pruned theme class declares. It only grows. */
|
|
618
|
+
readonly usedVariables: ReadonlySet<string>;
|
|
619
|
+
/** 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. */
|
|
620
|
+
markUsed(names: Iterable<string>): void;
|
|
621
|
+
/**
|
|
622
|
+
* Registers a theme class: `declarations` are all its variables, `colorScheme` is set by its rule.
|
|
623
|
+
* Only the used variables are written, more when they become used; the class itself always exists.
|
|
624
|
+
* Does nothing for a class that is already there.
|
|
625
|
+
*/
|
|
626
|
+
insertTheme(className: string, declarations: Readonly<Record<string, string>>, colorScheme?: string): void;
|
|
627
|
+
/**
|
|
628
|
+
* Makes the root theme `id` (`<prefix>-root-<hash>`, with `declarations` and `colorScheme`) the one
|
|
629
|
+
* declared on the document root: one rule `:where(:root){...}` in the theme layer. Its specificity is
|
|
630
|
+
* 0, so a theme class on `<html>` wins over it. With pruning only the used variables are written, more
|
|
631
|
+
* as they become used. Another id replaces the rule (removed where the sheet can remove it, else
|
|
632
|
+
* written again after it), and in a browser the root rules that a server render left in the page are
|
|
633
|
+
* removed the first time; the same id again does nothing. Every id given is kept for `getFullRules`.
|
|
634
|
+
*/
|
|
635
|
+
insertRoot(id: string, declarations: Readonly<Record<string, string>>, colorScheme?: string): void;
|
|
636
|
+
/**
|
|
637
|
+
* Gives the cache the `@property` rule of each registered variable, by variable name (`createTokens`
|
|
638
|
+
* makes them), replacing those it had. A rule is written once, outside every layer, when its variable
|
|
639
|
+
* is first used (at once for a variable that is used already, or when there is no pruning); a rule
|
|
640
|
+
* that is the same as a written one, or that a server render sent, is not written again.
|
|
641
|
+
*/
|
|
642
|
+
registerProperties(rules: Readonly<Record<string, string>>): void;
|
|
643
|
+
/** Gives the cache the theme that steps written as a function of the theme are resolved against, read when a `@keyframes` rule is first written (the engine gives its references). */
|
|
644
|
+
setKeyframesTheme(read: () => unknown): void;
|
|
645
|
+
/**
|
|
646
|
+
* Writes the `@keyframes` rule of `name` (a `keyframes` result) now, once, outside every layer: for a
|
|
647
|
+
* use that the cache cannot see in a class. A rule that is written, or that the page has, is not written
|
|
648
|
+
* again. Throws a `TypeError` for a name that `keyframes` did not return.
|
|
649
|
+
*/
|
|
650
|
+
insertKeyframes(name: string): void;
|
|
651
|
+
/** The animation names (`keyframes` results) that the rules of the class `className` use. */
|
|
652
|
+
getAnimations(className: string): readonly string[];
|
|
653
|
+
/**
|
|
654
|
+
* The rules of global styles for this cache (see `globalStyles`), with their id and the animations they
|
|
655
|
+
* use; nothing is written. Throws a `TypeError` for styles that are not an object, and for a key that
|
|
656
|
+
* holds no style.
|
|
657
|
+
*/
|
|
658
|
+
compileGlobal(styles: GlobalStyleObject): GlobalRules;
|
|
659
|
+
/**
|
|
660
|
+
* Writes global rules into the `global` layer (outside every layer without layers), after the
|
|
661
|
+
* `@keyframes` rules of the animations they use, and returns the function that releases them. Rules of
|
|
662
|
+
* one id are written once and counted: each insertion adds one, each release takes one, and at none the
|
|
663
|
+
* rules are removed from the sheet (the `@keyframes` rules stay). Rules that the page has (a server
|
|
664
|
+
* render) are taken over, not written, and removed from the page when released; the style elements
|
|
665
|
+
* that arrived since the page was last read are read first. Rules that cannot be removed (a sheet
|
|
666
|
+
* without `remove`, rules of the page whose place the browser does not show) stay. `options` says whether
|
|
667
|
+
* a component rendered them, which decides the pages they are part of (see `extractPage`).
|
|
668
|
+
*/
|
|
669
|
+
insertGlobal(global: GlobalRules, options?: GlobalInsertOptions): () => void;
|
|
670
|
+
/** `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. */
|
|
671
|
+
getFullRules(id: string): readonly string[];
|
|
672
|
+
/** The CSS inserted so far and not removed, and the ids it covers (class names, then the global rules held, then the used variables): all of the cache, whatever page asked for it. See `extractPage` for one page. */
|
|
673
|
+
extract(): {
|
|
674
|
+
css: string;
|
|
675
|
+
ids: string[];
|
|
676
|
+
};
|
|
677
|
+
/**
|
|
678
|
+
* The CSS that one page needs, decided from the class names it holds and not from what the cache holds,
|
|
679
|
+
* except for the global rules, which no class stands for: the layer order statement; the `@property`
|
|
680
|
+
* rules of the variables in use; the `@keyframes` rules that the page's classes and the global rules use
|
|
681
|
+
* (and `options.animations`), by name; the rule of the root theme that is in the sheet (the one
|
|
682
|
+
* `insertRoot` was given last, so render and extract one page before the next), then each theme
|
|
683
|
+
* class (of the page, and `options.themes`), each with only
|
|
684
|
+
* the variables the page's rules and the global rules use (all that they refer to, through the values
|
|
685
|
+
* of the themes too, and the variables marked with `markUsed`) and its color-scheme; the global rules of
|
|
686
|
+
* the page, in the order they were inserted: every set held for the app, and a set that a component
|
|
687
|
+
* rendered when the page carries it or names it in `options.rendered`; and the rules of the classes, in
|
|
688
|
+
* an order that depends on the classes only: a props class after its base class, the rest by name.
|
|
689
|
+
* Names the cache made no rules for are ignored. It reads the cache and changes nothing, so pages
|
|
690
|
+
* rendered at once, or in any order, get the same CSS, apart from the root theme.
|
|
691
|
+
*/
|
|
692
|
+
extractPage(classNames: Iterable<string>, options?: PageExtractOptions): {
|
|
693
|
+
css: string;
|
|
694
|
+
ids: string[];
|
|
695
|
+
};
|
|
696
|
+
/** `extractPage` in two parts: the rules that no class stands for, and the rules of the classes. */
|
|
697
|
+
extractPageParts(classNames: Iterable<string>, options?: PageExtractOptions): PageParts;
|
|
698
|
+
/** 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. */
|
|
699
|
+
readonly fingerprint: string;
|
|
700
|
+
}
|
|
701
|
+
/** A sheet that keeps its rules in memory, for a server render or a test. */
|
|
702
|
+
export declare function createMemorySheet(): Sheet;
|
|
703
|
+
/**
|
|
704
|
+
* A sheet in the style element marked `data-style="<key>"` of the document of `container`, which it
|
|
705
|
+
* creates in `container` when that document has none. It keeps the browser's object of each rule it
|
|
706
|
+
* inserts, and removes a rule by finding where that object is at the time, so rules that others insert
|
|
707
|
+
* into or delete from the element do not confuse it. Its `document` is that document: a cache over it
|
|
708
|
+
* reads that one (an iframe's, for a container in the iframe).
|
|
709
|
+
*/
|
|
710
|
+
export declare function createDomSheet(key: string, container?: Node): Sheet;
|
|
711
|
+
/**
|
|
712
|
+
* The selector of the style elements that hold engine rules: the cache's own, the ones React hoists for
|
|
713
|
+
* the same prefix, and the `data-umber="<prefix> <ids>"` and `data-umber="<prefix>-global <ids>"` elements
|
|
714
|
+
* of `@umber-style/server` and of an app's own registry.
|
|
715
|
+
*/
|
|
716
|
+
export declare function createStyleSelector(prefix: string): string;
|
|
717
|
+
/** Makes a cache: it turns styles into classes and inserts each class's rules once. */
|
|
718
|
+
export declare function createCache(options?: CacheOptions): Cache;
|
|
719
|
+
/**
|
|
720
|
+
* The cache of `prefix` in `page`: the first cache of that prefix made with a sheet in a style element of
|
|
721
|
+
* that document (`createCache` records it), or undefined where none was made. It is how code that has no
|
|
722
|
+
* engine of its own (a component that a server component renders, in the browser) reaches the cache of the
|
|
723
|
+
* page, for example to release a global rule that a server sent.
|
|
724
|
+
*/
|
|
725
|
+
export declare function findCache(prefix: string, page: Document): Cache | undefined;
|
|
726
|
+
/** A value of arithmetic on tokens: a CSS value (a reference such as `var(--space-2)`, a length) or a number. */
|
|
727
|
+
export type Operand = string | number;
|
|
728
|
+
/** `value` times `factor`: a number for numbers, otherwise a CSS value that the browser computes. */
|
|
729
|
+
export declare function multiply(value: number, factor: number): number;
|
|
730
|
+
export declare function multiply(value: Operand, factor: number): Operand;
|
|
731
|
+
/** `value` divided by `divisor`; a `divisor` of 0 throws a `RangeError`. */
|
|
732
|
+
export declare function divide(value: number, divisor: number): number;
|
|
733
|
+
export declare function divide(value: Operand, divisor: number): Operand;
|
|
734
|
+
/** The sum of `values`; a number next to a string is a length in px. */
|
|
735
|
+
export declare function add(...values: number[]): number;
|
|
736
|
+
export declare function add(...values: Operand[]): Operand;
|
|
737
|
+
/** `value` minus each of `values`; a number next to a string is a length in px. */
|
|
738
|
+
export declare function subtract(value: number, ...values: number[]): number;
|
|
739
|
+
export declare function subtract(value: Operand, ...values: Operand[]): Operand;
|
|
740
|
+
/** `value` times -1: a negative margin from a token. */
|
|
741
|
+
export declare function negate(value: number): number;
|
|
742
|
+
export declare function negate(value: Operand): Operand;
|
|
743
|
+
/** 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. */
|
|
744
|
+
export declare function isThemedSheet(sheet: object): sheet is ThemedSheet<string, unknown>;
|
|
745
|
+
/** What is thrown when something needs the shape of the theme before any theme is known. */
|
|
746
|
+
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.";
|
|
747
|
+
/** The options of a binding's `createStyle`: those of the engine, or an engine to share with other bindings. */
|
|
748
|
+
export interface BindingOptions<T> extends EngineOptions {
|
|
749
|
+
/** When given, the engine options are not used. */
|
|
750
|
+
engine?: Engine<T>;
|
|
751
|
+
}
|
|
752
|
+
export interface Styler {
|
|
753
|
+
/** The full style list, for a component that wraps this one. */
|
|
754
|
+
styles: readonly StyleInput[];
|
|
755
|
+
/** Whether a style is a function: only then the class depends on the props and the theme. */
|
|
756
|
+
isDynamic: boolean;
|
|
757
|
+
/**
|
|
758
|
+
* The class names for these props and what comes in after the styles (sheet entries, plain objects,
|
|
759
|
+
* a className). With layers: the base class (the plain objects before the first function, made once)
|
|
760
|
+
* and the props class (from the first function on, made for each render), both in the `components`
|
|
761
|
+
* layer, base first; then, only when something comes in, one override class in the `overrides` layer
|
|
762
|
+
* (all of it merged in order, the last winning; or, when it is exactly one sheet entry, the class of
|
|
763
|
+
* that entry for the layer); foreign class names pass through. Without layers there is no order between
|
|
764
|
+
* classes to rely on, so when something comes in all of it is merged into one class. Without
|
|
765
|
+
* `hasBaseClass`: one class for the styles.
|
|
766
|
+
*/
|
|
767
|
+
getClassName(props: Record<string, unknown>, extra?: ClassValue | readonly ClassValue[], theme?: unknown): string;
|
|
768
|
+
/**
|
|
769
|
+
* `getClassName` for an element that can count the classes it uses (a styled component in the
|
|
770
|
+
* browser): when what comes in has a plain style object, the class it makes (the override class;
|
|
771
|
+
* without layers, the one merged class) is made with `Cache.cssHeld`, and `hold` counts the element
|
|
772
|
+
* that uses it. Otherwise it is `getClassName`, with no `hold`.
|
|
773
|
+
*/
|
|
774
|
+
getHeldClass(props: Record<string, unknown>, extra?: ClassValue | readonly ClassValue[], theme?: unknown): HeldClass;
|
|
775
|
+
}
|
|
776
|
+
/** The variables of a theme as text, for a rule that is made elsewhere (the browser part of a provider of the server build). */
|
|
777
|
+
export interface ThemeText {
|
|
778
|
+
/** Every variable the theme declares, with its real value: `--name:value;` for each. */
|
|
779
|
+
readonly declarations: string;
|
|
780
|
+
/** The `@property` rules of the registered variables among them, or ''. */
|
|
781
|
+
readonly properties: string;
|
|
782
|
+
/** The names of the variables, in the order of `declarations`. */
|
|
783
|
+
readonly names: readonly string[];
|
|
784
|
+
}
|
|
785
|
+
export interface Engine<T> {
|
|
786
|
+
cache: Cache;
|
|
787
|
+
/** Whether a base theme is known: it is given by `setTheme`, or by the first `themeClass`. */
|
|
788
|
+
readonly hasTheme: boolean;
|
|
789
|
+
/** The base theme, the real values, or undefined while there is none. */
|
|
790
|
+
readonly baseTheme: T | undefined;
|
|
791
|
+
/** The view of the base theme: its shape, with a var(--name) reference for each token. Throws while there is no theme. */
|
|
792
|
+
readonly refs: T;
|
|
793
|
+
/** The token options of the engine, with the prefix of its cache: what names the variables of a theme and decides which values are tokens. */
|
|
794
|
+
readonly tokenOptions: Readonly<TokenOptions>;
|
|
795
|
+
/**
|
|
796
|
+
* The view of `realTheme`: each token is a var(--name) reference, every other part (breakpoints,
|
|
797
|
+
* functions, other objects) is taken from `realTheme`. Made once for each theme object; a view that is
|
|
798
|
+
* the same as a recent one (themes that differ only in the values of their variables) is that one, so
|
|
799
|
+
* that a component that reads the view does not render again when only variables change.
|
|
800
|
+
*/
|
|
801
|
+
createThemeView(realTheme: T): T;
|
|
802
|
+
/** Gives the engine its base theme. The same object again does nothing; another one replaces the base. */
|
|
803
|
+
setTheme(theme: T): void;
|
|
804
|
+
css: Cache['css'];
|
|
805
|
+
/**
|
|
806
|
+
* The classes of a theme, made once for each theme object and color scheme: the theme class (the
|
|
807
|
+
* variables), the boundary marker `<prefix>-boundary`, and for a `light` or `dark` color scheme the
|
|
808
|
+
* marker `<prefix>-scheme-light` or `-dark`. Put the whole string where a class goes. With no base
|
|
809
|
+
* theme yet, this theme becomes it.
|
|
810
|
+
*/
|
|
811
|
+
themeClass(theme: DeepPartial<T>, colorScheme?: ColorScheme): string;
|
|
812
|
+
/** The theme class alone, `<prefix>-theme-<hash>`: the id that rules and style elements are keyed by. Makes the theme class as `themeClass` does. */
|
|
813
|
+
themeId(theme: DeepPartial<T>, colorScheme?: ColorScheme): string;
|
|
814
|
+
/** The theme classes already made for this theme object (one for each color scheme it was asked with), without making any. */
|
|
815
|
+
findThemeIds(theme: DeepPartial<T>): string[];
|
|
816
|
+
/**
|
|
817
|
+
* Declares the variables of `theme` (a whole theme, the real values) on `:root`, in the theme layer,
|
|
818
|
+
* and returns the id of that rule, `<prefix>-root-<hash>`; with a `colorScheme` the rule sets it too.
|
|
819
|
+
* The engine has one root theme: a call with another theme replaces the rule (see `Cache.insertRoot`).
|
|
820
|
+
* Made once for each theme object and color scheme. With no base theme yet, this theme becomes it.
|
|
821
|
+
*/
|
|
822
|
+
declareRoot(theme: T, colorScheme?: ColorScheme): string;
|
|
823
|
+
/**
|
|
824
|
+
* The variables of `theme` (a whole theme or a partial one) as text, with the `@property` rules of the
|
|
825
|
+
* registered ones: what a theme class or the root rule of that theme declares, every variable, used or
|
|
826
|
+
* not. Nothing is written, and the engine's base theme stays as it is. Made once for each theme object.
|
|
827
|
+
* With no base theme the variables are the same (they depend on the token options only), and the
|
|
828
|
+
* `@property` rules are made from `theme` itself; that text is not kept.
|
|
829
|
+
*/
|
|
830
|
+
readThemeText(theme: DeepPartial<T>): ThemeText;
|
|
831
|
+
/** A style key for "the nearest theme is this theme": `{ [when(dark)]: { border: ... } }`. Needs `@scope` (see `hasScope`). */
|
|
832
|
+
when(theme: DeepPartial<T>, colorScheme?: ColorScheme): ThemeKey;
|
|
833
|
+
/** A style key for "the nearest color scheme is this one": the nearest theme given that `colorScheme`, else the system preference. */
|
|
834
|
+
whenScheme(scheme: SchemeName): SchemeKey;
|
|
835
|
+
/** 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>. */
|
|
836
|
+
scopeClass(): string;
|
|
837
|
+
/**
|
|
838
|
+
* Registers an animation and returns its name at once, before there is a theme too (see `keyframes`).
|
|
839
|
+
* Its `@keyframes` rule is written once, outside every layer, when a class that uses the name in
|
|
840
|
+
* `animation` or `animation-name` is first inserted; steps given as a function of the theme are then
|
|
841
|
+
* resolved against `refs`.
|
|
842
|
+
*/
|
|
843
|
+
keyframes(steps: (theme: T) => KeyframesSteps, options?: KeyframesOptions): string;
|
|
844
|
+
/** As a tag: the steps written as CSS text; a function among the interpolations is called with `{ theme }`. */
|
|
845
|
+
keyframes(template: TemplateStringsArray, ...values: TemplateValue<unknown, T>[]): string;
|
|
846
|
+
keyframes(steps: KeyframesInput<T>, options?: KeyframesOptions): string;
|
|
847
|
+
/** Writes the `@keyframes` rule of `name` now, for a use the engine cannot see in a class (a name under another key, CSS of the app's own, the Web Animations API). Throws a `TypeError` for a name that `keyframes` did not return. */
|
|
848
|
+
insertKeyframes(name: string): void;
|
|
849
|
+
/**
|
|
850
|
+
* The rules of global styles (a handle, an object, a function of the theme, or a list of them), one set
|
|
851
|
+
* for each, in the order of the list; nothing is written. A function is called with `theme` (the theme
|
|
852
|
+
* view of the nearest provider) when given, else with `refs`: tokens are references either way, and
|
|
853
|
+
* keys that hold real values (raw keys, the `inline` mode) come from that theme.
|
|
854
|
+
*/
|
|
855
|
+
resolveGlobal(input: GlobalInput<T>, theme?: T): GlobalRules[];
|
|
856
|
+
/**
|
|
857
|
+
* Writes global styles into the `global` layer, as `resolveGlobal` resolves them, in the order of the
|
|
858
|
+
* list (the cascade order), and returns the function that releases them: the rules of a set are written
|
|
859
|
+
* once and removed when the last insertion of them is released (see `Cache.insertGlobal`).
|
|
860
|
+
*/
|
|
861
|
+
insertGlobal(input: GlobalInput<T>, theme?: T): () => void;
|
|
862
|
+
/**
|
|
863
|
+
* A sheet of named styles. Given a function of the theme it is a sheet that is resolved against a
|
|
864
|
+
* theme (`resolve`, which `useStyle` calls). Given an object it is the entries themselves, usable at
|
|
865
|
+
* once: no theme is read, so it works before there is one. Entries are made on first access and a
|
|
866
|
+
* class's rule is written when the entry is first used, in the layer of how it is used.
|
|
867
|
+
*/
|
|
868
|
+
createSheet<K extends string>(styles: ObjectSheet<K>): SheetEntries<K>;
|
|
869
|
+
createSheet<K extends string>(styles: (theme: T) => Record<K, WebStyleObject>): ThemedSheet<K, T>;
|
|
870
|
+
/** The logic that every web `styled` shares: the label, the style list, function styles and the class memo. */
|
|
871
|
+
createStyler(options: StylerOptions, styles: readonly StyleInput[], inherited?: readonly StyleInput[]): Styler;
|
|
872
|
+
/**
|
|
873
|
+
* The engine of the same theme over `cache`: this engine for its own cache, else one made on first
|
|
874
|
+
* call and kept while the cache lives. It has the token options of this engine; its prefix is that of
|
|
875
|
+
* `cache`, for classes and variables alike, and the other options of a cache are those `cache` was made
|
|
876
|
+
* with. The engines share one base theme: `setTheme` of either is the base of both. What a cache
|
|
877
|
+
* provider gives a subtree.
|
|
878
|
+
*/
|
|
879
|
+
withCache(cache: Cache): Engine<T>;
|
|
880
|
+
/**
|
|
881
|
+
* Entries of this engine's cache for `entries` (an object sheet, or what a themed sheet resolved to):
|
|
882
|
+
* each key is `cache.adoptEntry` of the entry, made on first read; one record for each record given.
|
|
883
|
+
*/
|
|
884
|
+
adoptSheet<K extends string>(entries: SheetEntries<K>): SheetEntries<K>;
|
|
885
|
+
}
|
|
886
|
+
/** Makes an engine that has no theme yet: it takes one from `setTheme`, or from the first `themeClass`. It needs no framework. */
|
|
887
|
+
export declare function createLazyEngine<T extends object = Theme>(options?: EngineOptions): Engine<T>;
|
|
888
|
+
/** Makes the engine of one theme shape: a cache, the theme as variables, and what the bindings build on. It needs no framework. */
|
|
889
|
+
export declare function createEngine<T extends object>(theme: T, options?: EngineOptions): Engine<T>;
|
|
890
|
+
/**
|
|
891
|
+
* The style of `args` when they are a tagged template (`caller` was used as a tag), read as CSS text;
|
|
892
|
+
* undefined when they are not. `caller` has no props, so a function among the interpolations is a
|
|
893
|
+
* `TypeError` that names it.
|
|
894
|
+
*/
|
|
895
|
+
export declare function readStaticTemplate(args: readonly unknown[], caller: string): StyleObject | undefined;
|
|
896
|
+
/**
|
|
897
|
+
* Throws a `TypeError` that names `caller` when an argument, or an item of a list among them, is a
|
|
898
|
+
* function: `caller` has no props to call it with.
|
|
899
|
+
*/
|
|
900
|
+
export declare function rejectFunctions(args: readonly unknown[], caller: string): void;
|
|
901
|
+
/**
|
|
902
|
+
* The style of the arguments of `css()`: a tagged template read as CSS text, or style objects, `css()`
|
|
903
|
+
* results and sheet entries, with lists flattened and `false`, `null` and `undefined` dropped, merged in
|
|
904
|
+
* order, the last winning. An entry that a framework merged into an object is found with `findEntry`.
|
|
905
|
+
* Throws a `TypeError` for a function, for a string, and for an entry that is only a class name.
|
|
906
|
+
*/
|
|
907
|
+
export declare function readCssStyle(args: readonly unknown[], findEntry?: (className: string) => SheetEntry | undefined): StyleObject;
|
|
908
|
+
/**
|
|
909
|
+
* `css()` of a web binding over `cache`: one sheet entry of the merged style (see `readCssStyle`). Its
|
|
910
|
+
* class name is worked out now and its rule is written when the entry is first used, as an entry of a
|
|
911
|
+
* sheet; equal styles give the same class.
|
|
912
|
+
*/
|
|
913
|
+
export declare function createCssEntry(cache: Cache, args: readonly unknown[]): SheetEntry;
|
|
914
|
+
/**
|
|
915
|
+
* The styles of a call of the function that `styled(tag)` returns: as a tag, the template is one style
|
|
916
|
+
* (an object, or a function of the props when an interpolation is a function); else the styles given,
|
|
917
|
+
* with lists flattened.
|
|
918
|
+
*/
|
|
919
|
+
export declare function readStyleArguments(args: readonly unknown[]): StyleInput[];
|
|
920
|
+
/**
|
|
921
|
+
* The `toString` of a styled component, which makes it a selector in a template or a key
|
|
922
|
+
* (`${Button}:hover &`): `.` and a class that every element of the component has. That is the
|
|
923
|
+
* component's own `target` when it was given one (each class of it, when it holds several); else, when none of its styles is a function, its class
|
|
924
|
+
* (the base class, the same for every element); else there is none, and it throws a `TypeError` that says
|
|
925
|
+
* to give the component a `target`.
|
|
926
|
+
*/
|
|
927
|
+
export declare function createComponentSelector(target: string | undefined, styler: Pick<Styler, 'isDynamic' | 'getClassName'>): () => string;
|
|
928
|
+
/** Whether this is a development build: `process.env.NODE_ENV` is `development`. Where `process` does not exist (a browser, no bundler) it is not. */
|
|
929
|
+
export declare function isDevelopment(): boolean;
|
|
930
|
+
/**
|
|
931
|
+
* The style element of a static page or a server render: everything `cache` inserted, whatever page
|
|
932
|
+
* inserted it. A cache that renders more than one page (a server process) should use `extractPageStyles`,
|
|
933
|
+
* which carries only what one page uses. The element is stamped with the options of the cache
|
|
934
|
+
* (`data-options`), which a cache made in the browser compares with its own; it holds no list of ids,
|
|
935
|
+
* because the browser reads the rules themselves.
|
|
936
|
+
*/
|
|
937
|
+
export declare function createStyleTag(cache: Cache): string;
|
|
938
|
+
/** What one page needs: its CSS, what that CSS covers, and the element to put in its head. */
|
|
939
|
+
export interface PageStyles {
|
|
940
|
+
/** The CSS of the page: the layer order, the `@property` rules, the `@keyframes` rules, the themes, the rules of its classes. */
|
|
941
|
+
css: string;
|
|
942
|
+
/** The theme classes and the classes that `css` has rules for. */
|
|
943
|
+
ids: string[];
|
|
944
|
+
/** The stamp of the options of the cache: the `data-options` of the style element, for a page that writes the element itself. */
|
|
945
|
+
options: string;
|
|
946
|
+
/** The style element with `css`, stamped with the options of the cache. */
|
|
947
|
+
tag: string;
|
|
948
|
+
}
|
|
949
|
+
export interface PageStyleOptions {
|
|
950
|
+
/** 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. */
|
|
951
|
+
themes?: readonly string[];
|
|
952
|
+
/** Animation names (`keyframes` results) whose `@keyframes` rule to include although no class of `html` uses them: for a use the engine cannot see. Names that `keyframes` did not return are ignored. */
|
|
953
|
+
animations?: readonly string[];
|
|
954
|
+
}
|
|
955
|
+
/**
|
|
956
|
+
* The CSS of one page, decided from the page: the finished `html` is scanned for the class names it
|
|
957
|
+
* holds (the values of its `class` and `className` attributes only; scripts, styles, comments and other
|
|
958
|
+
* attributes are not looked at), and only those classes are written, with the `@keyframes` rules they
|
|
959
|
+
* use and the theme classes trimmed to the variables that the page uses. Nothing depends on what else the cache holds, on the
|
|
960
|
+
* order pages were rendered in, or on pages being rendered at the same time, and the cache is not changed.
|
|
961
|
+
* The `<style href precedence>` elements that `html` carries already (React's server render of the
|
|
962
|
+
* client build emits them) are not written again. The global rules are those inserted for the app
|
|
963
|
+
* (`engine.insertGlobal`), which are in every page, and those of the `Global` components that `html`
|
|
964
|
+
* rendered: a style element it carries, or a marker that names the set (a `<meta name="<prefix>-global">`
|
|
965
|
+
* of React, a comment `<!--<prefix>-global ...-->` of Vue). A set that another page rendered is not.
|
|
966
|
+
*/
|
|
967
|
+
export declare function extractPageStyles(cache: Cache, html: string, options?: PageStyleOptions): PageStyles;
|
|
968
|
+
/**
|
|
969
|
+
* `extractPageStyles` in two parts, decided from `html` the same way: the rules that no class stands for
|
|
970
|
+
* (the layer order, the `@property` and `@keyframes` rules, the theme classes, the global rules) and the
|
|
971
|
+
* rules of the classes. The two CSS texts joined in this order are the CSS of `extractPageStyles`.
|
|
972
|
+
*/
|
|
973
|
+
export declare function extractPageStyleParts(cache: Cache, html: string, options?: PageStyleOptions): PageParts;
|
|
974
|
+
/** What `findMissingStyles` can find. */
|
|
975
|
+
export type StyleProblemKind = 'class-without-rule' | 'variable-without-value' | 'root-without-theme';
|
|
976
|
+
/** One thing the page lacks. */
|
|
977
|
+
export interface StyleProblem {
|
|
978
|
+
kind: StyleProblemKind;
|
|
979
|
+
/** The class, or the variable. */
|
|
980
|
+
name: string;
|
|
981
|
+
/** A short description of the element: `tag[test id or id]`. */
|
|
982
|
+
element: string;
|
|
983
|
+
/** What is wrong, in a sentence. */
|
|
984
|
+
message: string;
|
|
985
|
+
/** What makes two problems the same one: the kind and the name, and for a variable the rule that uses it. */
|
|
986
|
+
key: string;
|
|
987
|
+
}
|
|
988
|
+
export interface FindMissingStylesOptions {
|
|
989
|
+
/** The prefix of the engine. Default: the one the style elements of the page say. */
|
|
990
|
+
prefix?: string;
|
|
991
|
+
}
|
|
992
|
+
/**
|
|
993
|
+
* Looks at a page that an engine styled, and lists what is missing. For each element under `root`
|
|
994
|
+
* (the document by default; the style elements are read in the document of `root`): every class of the engine on it is named by at least one rule of the
|
|
995
|
+
* engine's style elements (its own, and the ones React hoists), and every variable of the engine that
|
|
996
|
+
* a rule matching the element uses, without a fallback, has a value on the element. The classes that
|
|
997
|
+
* are markers (`<prefix>-boundary`, `<prefix>-scheme-light` and `-dark`) have no rule of their own and
|
|
998
|
+
* are left out, and so is `<prefix>-theme-0`, the theme class of a theme that declares nothing, which has
|
|
999
|
+
* no rule by design; and so are the rules for `:hover`, `:focus` and the like. `<html>` and `<body>` without
|
|
1000
|
+
* a class of the engine are checked for the global rules that name them (see `root-without-theme`). An
|
|
1001
|
+
* empty list means nothing is missing. Where there is no document, or no style element of an engine,
|
|
1002
|
+
* the list is empty.
|
|
1003
|
+
*/
|
|
1004
|
+
export declare function findMissingStyles(root?: ParentNode, options?: FindMissingStylesOptions): StyleProblem[];
|
|
1005
|
+
/** A short, stable hash of `text`, in base 36. */
|
|
1006
|
+
export declare function hashString(text: string): string;
|
|
1007
|
+
/**
|
|
1008
|
+
* An object with one key for each of `keys`, whose value is made by `make` the first time the key is
|
|
1009
|
+
* read, and kept. `Object.keys` and a spread list the keys (a spread reads every one); nothing is made
|
|
1010
|
+
* until then. The object is frozen.
|
|
1011
|
+
*/
|
|
1012
|
+
export declare function createLazyRecord<K extends string, V>(keys: readonly K[], make: (key: K) => V): { readonly [P in K]: V; };
|
|
1013
|
+
/**
|
|
1014
|
+
* `createLazyRecord` for the keys of `source`, with every value taken from the record that `build` makes,
|
|
1015
|
+
* which is called once, when the first key is read: for a sheet whose engine must not be made, or whose
|
|
1016
|
+
* platform call must not run, before it is used.
|
|
1017
|
+
*/
|
|
1018
|
+
export declare function createDeferredRecord<V>(source: object, build: () => Record<string, V>): Readonly<Record<string, V>>;
|
|
1019
|
+
/**
|
|
1020
|
+
* An object that stands for the one `make` returns, which is made the first time the object is used in
|
|
1021
|
+
* any way (a property read, `in`, a listing of its keys, a check of whether it is frozen): from then on it
|
|
1022
|
+
* has the same properties, and is frozen as that one is. When `make` throws, the next use tries again. For a value that a module makes before the
|
|
1023
|
+
* engine it needs may exist, such as a `css()` result of a default style before `configure` is called.
|
|
1024
|
+
*/
|
|
1025
|
+
export declare function createDeferredObject<V extends object>(make: () => V): V;
|
|
1026
|
+
/**
|
|
1027
|
+
* `override` over `base`: plain objects merge key by key, everything else is replaced, undefined keeps
|
|
1028
|
+
* `base`. Every own member is taken with its descriptor, so a member that is not enumerable (a helper
|
|
1029
|
+
* function on `breakpoints`) is kept, from `override` when it has one, else from `base`.
|
|
1030
|
+
*/
|
|
1031
|
+
export declare function mergeDeep<T>(base: T, override: DeepPartial<T> | undefined): T;
|
|
1032
|
+
/** What a marker of global rules says: its name, `<prefix>-global`, and the ids of the sets, separated by spaces. */
|
|
1033
|
+
interface GlobalMarker {
|
|
1034
|
+
name: string;
|
|
1035
|
+
ids: string;
|
|
1036
|
+
}
|
|
1037
|
+
/**
|
|
1038
|
+
* The marker by which a `Global` that renders no style element names its sets in the markup of a server
|
|
1039
|
+
* render, so that `extractPageStyles` puts them in that page only: the sets that have rules, by id. None
|
|
1040
|
+
* when no set has a rule. A binding renders it as `<meta name="<name>" content="<ids>">` (React) or as a
|
|
1041
|
+
* comment `<!--<name> <ids>-->` (Vue).
|
|
1042
|
+
*/
|
|
1043
|
+
export declare function createGlobalMarker(prefix: string, sets: readonly {
|
|
1044
|
+
id: string;
|
|
1045
|
+
rules: readonly string[];
|
|
1046
|
+
}[]): GlobalMarker | undefined;
|
|
1047
|
+
/**
|
|
1048
|
+
* `styled` with a shorthand for every tag: `styled.div(...styles)` is `styled('div')(...styles)`. Nothing
|
|
1049
|
+
* is made up front: a member that the function does not have and that looks like a tag name is made when
|
|
1050
|
+
* it is read. `then` is not a tag, so that `styled` is never taken for a promise.
|
|
1051
|
+
*/
|
|
1052
|
+
export declare function withTagShorthands<F extends object>(styled: F): F;
|
|
1053
|
+
/** The selector of the rule of the root theme: the document root, with no specificity. */
|
|
1054
|
+
export declare const ROOT_SELECTOR = ":where(:root)";
|
|
1055
|
+
/** The rule `selector{body}` of a theme, inside the theme layer of `prefix` when there are layers. */
|
|
1056
|
+
export declare function createThemeRule(prefix: string, hasLayers: boolean, selector: string, body: string): string;
|
|
1057
|
+
export interface ThemeRuleOptions {
|
|
1058
|
+
/** Sets the color-scheme property in the scope. */
|
|
1059
|
+
colorScheme?: 'light' | 'dark' | 'light dark';
|
|
1060
|
+
}
|
|
1061
|
+
/** The CSS declarations `name:value;` of `entries`. */
|
|
1062
|
+
export declare function toDeclarationText(entries: Iterable<readonly [string, string]>): string;
|
|
1063
|
+
/**
|
|
1064
|
+
* The theme class of the declarations `variables` (the text of `toDeclarationText`, as `readThemeText`
|
|
1065
|
+
* gives it) and of `colorScheme`, `<prefix>-theme-<hash>`, without registering it: the name that
|
|
1066
|
+
* `createThemeClass` gives the same declarations.
|
|
1067
|
+
*/
|
|
1068
|
+
export declare function createThemeId(prefix: string, variables: string, colorScheme?: string): string;
|
|
1069
|
+
/**
|
|
1070
|
+
* Registers the theme class of `declarations` and returns it: the scope of a theme. Its name is the
|
|
1071
|
+
* hash of all the declarations, whatever the cache writes of them (see `hasPruning`).
|
|
1072
|
+
*/
|
|
1073
|
+
export declare function createThemeClass(cache: Cache, declarations: Readonly<Record<string, string>>, options?: ThemeRuleOptions): string;
|
|
1074
|
+
/**
|
|
1075
|
+
* Makes `declarations` the root theme, the one declared on `:root` (see `Cache.insertRoot`), and returns
|
|
1076
|
+
* its id, `<prefix>-root-<hash>`: like a theme class, named by the hash of all its declarations.
|
|
1077
|
+
*/
|
|
1078
|
+
export declare function declareRootTheme(cache: Cache, declarations: Readonly<Record<string, string>>, options?: ThemeRuleOptions): string;
|
|
1079
|
+
/** What a provider is given: the theme, or the part of it that its subtree changes; or a function of the theme above it that returns that. */
|
|
1080
|
+
export type ThemeInput<T> = DeepPartial<T> | ((outer: T) => DeepPartial<T>);
|
|
1081
|
+
/** The theme where there is no provider and no base theme: an object with nothing in it, never changed. */
|
|
1082
|
+
export declare const EMPTY_THEME: object;
|
|
1083
|
+
/** The theme that a provider given `input` adds below `outer` (the theme above it, or `EMPTY_THEME`): the result of a function, or the object as it is. */
|
|
1084
|
+
export declare function resolveThemeInput<T>(input: ThemeInput<T>, outer: T): DeepPartial<T>;
|
|
1085
|
+
/** The theme below a provider: `given` merged over the theme above it, or `given` as it is where there is none above and no base theme. */
|
|
1086
|
+
export declare function mergeTheme<T>(outer: T | undefined, given: DeepPartial<T>): T;
|
|
1087
|
+
/** A group of rules that the cache wrote: its name, and its CSS text as written (layer included). */
|
|
1088
|
+
interface SerializedRule {
|
|
1089
|
+
name: string;
|
|
1090
|
+
styles: string;
|
|
1091
|
+
}
|
|
1092
|
+
/** The style elements of a cache. */
|
|
1093
|
+
interface UmberSheet {
|
|
1094
|
+
/**
|
|
1095
|
+
* The style elements that hold the rules of the cache, in document order: its own, and those on the
|
|
1096
|
+
* page with its key (`data-umber="<key> ..."`, `data-umber="<key>-global ..."`). None without a document.
|
|
1097
|
+
*/
|
|
1098
|
+
readonly tags: HTMLStyleElement[];
|
|
1099
|
+
}
|
|
1100
|
+
/**
|
|
1101
|
+
* The engine's cache, with the members that server-rendering setups read and wrap: what `createCache` of
|
|
1102
|
+
* `@umber-style/cache` makes. The type lives here, with the other types apps import, and that package
|
|
1103
|
+
* re-exports it.
|
|
1104
|
+
*/
|
|
1105
|
+
interface UmberCache extends Cache {
|
|
1106
|
+
/** The key the cache was made with: its prefix. */
|
|
1107
|
+
readonly key: string;
|
|
1108
|
+
/** Whether `inserted` holds the CSS text of each rule (`true`), or only `true` (`false`, the default). */
|
|
1109
|
+
compat: boolean;
|
|
1110
|
+
/** Each group of rules written since the cache was made, by name: its CSS text when `compat` is set, else `true`. The names of the `data-umber` elements on the page at start-up are `true`. */
|
|
1111
|
+
inserted: Record<string, string | true>;
|
|
1112
|
+
/** The style object of each class this cache made (a map), also readable by class name: `registered[className]` is `true` for such a class. */
|
|
1113
|
+
readonly registered: ReadonlyMap<string, StyleObject> & {
|
|
1114
|
+
readonly [className: string]: unknown;
|
|
1115
|
+
};
|
|
1116
|
+
readonly sheet: UmberSheet;
|
|
1117
|
+
/**
|
|
1118
|
+
* Called by the cache after it writes a group of rules (`selector` is '', `serialized` the name and
|
|
1119
|
+
* the CSS text, `shouldCache` true): it records the rules in `inserted`. Replace it with a function that
|
|
1120
|
+
* calls the one it replaces to see every new rule once.
|
|
1121
|
+
*/
|
|
1122
|
+
insert(selector: string, serialized: SerializedRule, sheet: UmberSheet, shouldCache: boolean): void;
|
|
1123
|
+
}
|
|
1124
|
+
/** Whether `value` is the strings of a tagged template: an array with `raw`, which a call with styles never is. */
|
|
1125
|
+
export declare function isTemplateStrings(value: unknown): value is TemplateStringsArray;
|
|
1126
|
+
/**
|
|
1127
|
+
* The style of a tagged template, `strings` and `values` as a tag is given them: CSS text with
|
|
1128
|
+
* declarations, nested rules (`&:hover { }`, `> p { }`), at-rules (`@media (...) { }`) and comments.
|
|
1129
|
+
* A value is kept as text (`padding: 8px` is `'8px'`); a property is a camelCase key; a property declared
|
|
1130
|
+
* twice in a block is a fallback list. An interpolation in a value, a selector or a property name is
|
|
1131
|
+
* text; one alone between declarations is merged in: a style object, a sheet entry, CSS text, or a list
|
|
1132
|
+
* of them. `null`, `undefined`, `true` and `false` are nothing. When an interpolation is a function, the
|
|
1133
|
+
* result is a function of the props that calls it with them (what it returns is an interpolation too);
|
|
1134
|
+
* else it is the style. The text is split once for each `strings` array. Throws a `TypeError` with the
|
|
1135
|
+
* text around the place for a template that cannot be read.
|
|
1136
|
+
*/
|
|
1137
|
+
export declare function parseStyleTemplate<P = unknown>(strings: readonly string[], values: readonly unknown[]): StyleObject | ((props: P) => StyleObject);
|
|
1138
|
+
/**
|
|
1139
|
+
* The steps of an animation from a tagged template: `from { ... } 50% { ... } to { ... }`, read as
|
|
1140
|
+
* `parseStyleTemplate` reads a style. When an interpolation is a function, the result is a function of
|
|
1141
|
+
* the theme, and the function is called with `{ theme }`, as a function in a style is.
|
|
1142
|
+
*/
|
|
1143
|
+
export declare function parseKeyframesTemplate<T = unknown>(strings: readonly string[], values: readonly unknown[]): KeyframesInput<T>;
|
|
1144
|
+
export type { AtRuleDescriptors, GlobalInput, GlobalMarker, GlobalStyleObject, GlobalStyleValue, GlobalStyles, GlobalStylesInput, KeyframesInput, KeyframesOptions, KeyframesStep, KeyframesSteps, RegisteredSyntax, SerializedRule, UmberCache, UmberSheet };
|