@umber-style/core 0.1.0-alpha.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/dist/index.cjs +2179 -502
- package/dist/index.d.cts +662 -135
- package/dist/index.d.mts +662 -135
- package/dist/index.mjs +2142 -492
- package/package.json +2 -2
package/dist/index.d.cts
CHANGED
|
@@ -9,6 +9,8 @@ export interface AlphaColor {
|
|
|
9
9
|
readonly fallback: string;
|
|
10
10
|
/** The color-mix() value. */
|
|
11
11
|
readonly value: string;
|
|
12
|
+
/** The text of the colour: `value`. */
|
|
13
|
+
toString(): string;
|
|
12
14
|
}
|
|
13
15
|
/** Whether `value` was made by `alpha()` as a mix: a plain string is a color, not a fallback pair. */
|
|
14
16
|
export declare function isAlphaColor(value: unknown): value is AlphaColor;
|
|
@@ -42,8 +44,12 @@ type DisplayValue = Keywords<CSS.Property.Display> | `${DisplayOutside} ${Displa
|
|
|
42
44
|
type CssProperties = CSS.Properties<string | number>;
|
|
43
45
|
/** The properties whose value is a color, and so also take the result of `alpha()`. */
|
|
44
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';
|
|
45
|
-
/**
|
|
46
|
-
|
|
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>>; };
|
|
47
53
|
/** What a nested key holds: a style of its own, or nothing (so `isOpen && { ... }` works). */
|
|
48
54
|
export type WebNested = WebStyleObject | null | undefined | false;
|
|
49
55
|
/**
|
|
@@ -123,9 +129,10 @@ export declare function mergeStyles(styles: readonly StyleObject[]): StyleObject
|
|
|
123
129
|
/**
|
|
124
130
|
* The flat CSS rules of `style` for `selector`; without `hasColorFallbacks` an `alpha()` result is
|
|
125
131
|
* written as its mix alone. A `when()` or `whenScheme()` key becomes a scoped rule, written as
|
|
126
|
-
* `scoping` says.
|
|
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.
|
|
127
134
|
*/
|
|
128
|
-
export declare function compileRules(selector: string, style: StyleObject, hasColorFallbacks?: boolean, scoping?: Scoping): string[];
|
|
135
|
+
export declare function compileRules(selector: string, style: StyleObject, hasColorFallbacks?: boolean, scoping?: Scoping, hasValueRepair?: boolean): string[];
|
|
129
136
|
/** The label of `style` (its `label` key), or ''. */
|
|
130
137
|
export declare function readLabel(style: StyleObject): string;
|
|
131
138
|
/** The two ways an entry is used: on its own (a plain element, `apply`), or given to a styled component through `style`. */
|
|
@@ -134,6 +141,8 @@ export type EntryRole = 'components' | 'overrides';
|
|
|
134
141
|
export interface EntrySource {
|
|
135
142
|
/** The style of the entry, merged. */
|
|
136
143
|
readonly style: StyleObject;
|
|
144
|
+
/** The cache that made the entry, whose rules `use` writes. */
|
|
145
|
+
readonly cache: Cache;
|
|
137
146
|
/** The class name for `role`; its rule is written, once, the first time it is asked for. */
|
|
138
147
|
use(role: EntryRole): string;
|
|
139
148
|
}
|
|
@@ -156,6 +165,14 @@ export declare function createSheetEntry(className: string, source?: EntrySource
|
|
|
156
165
|
export declare function isSheetEntry(value: unknown): value is SheetEntry;
|
|
157
166
|
/** What a cache gave `entry` to make its classes, or undefined for an entry that is only a name. */
|
|
158
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;
|
|
159
176
|
/**
|
|
160
177
|
* What a `style` prop holds, as a flat list in order, for the cache to merge into one class: sheet
|
|
161
178
|
* entries and plain style objects, with arrays flattened and what is empty dropped. An object in which a
|
|
@@ -164,6 +181,219 @@ export declare function readEntrySource(entry: SheetEntry): EntrySource | undefi
|
|
|
164
181
|
* A string is an error: a text style cannot be merged into a class.
|
|
165
182
|
*/
|
|
166
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>;
|
|
167
397
|
export interface CacheOptions {
|
|
168
398
|
/** First part of every class name. Default 'css'. Must match /^[a-z][a-z0-9-]*$/ or createCache throws. */
|
|
169
399
|
prefix?: string;
|
|
@@ -184,6 +414,13 @@ export interface CacheOptions {
|
|
|
184
414
|
* color-mix(). Default true. Without it only the color-mix() value is written.
|
|
185
415
|
*/
|
|
186
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;
|
|
187
424
|
/**
|
|
188
425
|
* Whether a style written with `when()` or `whenScheme()` is scoped with `@scope`, so that it follows the
|
|
189
426
|
* nearest theme. Default true. Without it the rule is the plain descendant form `:where(.theme) .class`,
|
|
@@ -200,7 +437,7 @@ export interface CacheOptions {
|
|
|
200
437
|
hasBaseClass?: boolean;
|
|
201
438
|
/**
|
|
202
439
|
* 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
|
|
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,
|
|
204
441
|
* after the first render and when rules are inserted. Default: on in development (`process.env.NODE_ENV`
|
|
205
442
|
* is not `production`), off in production, and off where there is no `document`.
|
|
206
443
|
*/
|
|
@@ -209,20 +446,79 @@ export interface CacheOptions {
|
|
|
209
446
|
tokenSignature?: string;
|
|
210
447
|
/** Where rules go. Default: a DOM sheet when `document` exists, otherwise an in-memory one. */
|
|
211
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;
|
|
212
469
|
}
|
|
213
470
|
/** What `extractPage` is told besides the classes of the page. */
|
|
214
471
|
export interface PageExtractOptions {
|
|
215
472
|
/** Theme classes to include although no element has them (the themes the page offers for switching). */
|
|
216
473
|
themes?: Iterable<string>;
|
|
217
|
-
/**
|
|
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. */
|
|
218
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;
|
|
219
493
|
}
|
|
220
494
|
export interface Sheet {
|
|
221
495
|
insert(rule: string): void;
|
|
222
|
-
/** Every rule inserted so far, in order. */
|
|
496
|
+
/** Every rule inserted so far and not removed, in order. */
|
|
223
497
|
readonly rules: readonly string[];
|
|
224
498
|
/** Replaces the rule inserted at `index` of `rules`; a sheet that cannot (a browser one) has none, and the cache appends instead. */
|
|
225
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[];
|
|
226
522
|
}
|
|
227
523
|
/** The cascade layers of a cache, from the lowest priority to the highest. */
|
|
228
524
|
export declare const RULE_LAYERS: readonly ['theme', 'global', 'components', 'overrides'];
|
|
@@ -244,6 +540,17 @@ export interface ClassOptions {
|
|
|
244
540
|
*/
|
|
245
541
|
after?: string;
|
|
246
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
|
+
}
|
|
247
554
|
export interface Cache {
|
|
248
555
|
readonly prefix: string;
|
|
249
556
|
/** Whether rules go into cascade layers. */
|
|
@@ -266,10 +573,33 @@ export interface Cache {
|
|
|
266
573
|
* of the entry for that layer is used, and written if it was not.
|
|
267
574
|
*/
|
|
268
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;
|
|
269
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. */
|
|
270
593
|
createEntry(style: WebStyleObject): SheetEntry;
|
|
271
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. */
|
|
272
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;
|
|
273
603
|
/** Whether a component's styles are split into a base class and a props class. */
|
|
274
604
|
readonly hasBaseClass: boolean;
|
|
275
605
|
/**
|
|
@@ -294,6 +624,15 @@ export interface Cache {
|
|
|
294
624
|
* Does nothing for a class that is already there.
|
|
295
625
|
*/
|
|
296
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;
|
|
297
636
|
/**
|
|
298
637
|
* Gives the cache the `@property` rule of each registered variable, by variable name (`createTokens`
|
|
299
638
|
* makes them), replacing those it had. A rule is written once, outside every layer, when its variable
|
|
@@ -301,35 +640,89 @@ export interface Cache {
|
|
|
301
640
|
* that is the same as a written one, or that a server render sent, is not written again.
|
|
302
641
|
*/
|
|
303
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;
|
|
304
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. */
|
|
305
671
|
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. */
|
|
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. */
|
|
307
673
|
extract(): {
|
|
308
674
|
css: string;
|
|
309
675
|
ids: string[];
|
|
310
676
|
};
|
|
311
677
|
/**
|
|
312
|
-
* The CSS that one page needs, decided from the class names it holds and not from what the cache holds
|
|
313
|
-
*
|
|
314
|
-
*
|
|
315
|
-
*
|
|
316
|
-
*
|
|
317
|
-
*
|
|
318
|
-
*
|
|
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.
|
|
319
691
|
*/
|
|
320
692
|
extractPage(classNames: Iterable<string>, options?: PageExtractOptions): {
|
|
321
693
|
css: string;
|
|
322
694
|
ids: string[];
|
|
323
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;
|
|
324
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. */
|
|
325
699
|
readonly fingerprint: string;
|
|
326
700
|
}
|
|
327
701
|
/** A sheet that keeps its rules in memory, for a server render or a test. */
|
|
328
702
|
export declare function createMemorySheet(): Sheet;
|
|
329
|
-
/**
|
|
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
|
+
*/
|
|
330
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;
|
|
331
717
|
/** Makes a cache: it turns styles into classes and inserts each class's rules once. */
|
|
332
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;
|
|
333
726
|
/** A value of arithmetic on tokens: a CSS value (a reference such as `var(--space-2)`, a length) or a number. */
|
|
334
727
|
export type Operand = string | number;
|
|
335
728
|
/** `value` times `factor`: a number for numbers, otherwise a CSS value that the browser computes. */
|
|
@@ -347,114 +740,6 @@ export declare function subtract(value: Operand, ...values: Operand[]): Operand;
|
|
|
347
740
|
/** `value` times -1: a negative margin from a token. */
|
|
348
741
|
export declare function negate(value: number): number;
|
|
349
742
|
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
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. */
|
|
459
744
|
export declare function isThemedSheet(sheet: object): sheet is ThemedSheet<string, unknown>;
|
|
460
745
|
/** What is thrown when something needs the shape of the theme before any theme is known. */
|
|
@@ -480,6 +765,22 @@ export interface Styler {
|
|
|
480
765
|
* `hasBaseClass`: one class for the styles.
|
|
481
766
|
*/
|
|
482
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[];
|
|
483
784
|
}
|
|
484
785
|
export interface Engine<T> {
|
|
485
786
|
cache: Cache;
|
|
@@ -489,7 +790,14 @@ export interface Engine<T> {
|
|
|
489
790
|
readonly baseTheme: T | undefined;
|
|
490
791
|
/** The view of the base theme: its shape, with a var(--name) reference for each token. Throws while there is no theme. */
|
|
491
792
|
readonly refs: T;
|
|
492
|
-
/** The
|
|
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
|
+
*/
|
|
493
801
|
createThemeView(realTheme: T): T;
|
|
494
802
|
/** Gives the engine its base theme. The same object again does nothing; another one replaces the base. */
|
|
495
803
|
setTheme(theme: T): void;
|
|
@@ -505,12 +813,52 @@ export interface Engine<T> {
|
|
|
505
813
|
themeId(theme: DeepPartial<T>, colorScheme?: ColorScheme): string;
|
|
506
814
|
/** The theme classes already made for this theme object (one for each color scheme it was asked with), without making any. */
|
|
507
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;
|
|
508
831
|
/** A style key for "the nearest theme is this theme": `{ [when(dark)]: { border: ... } }`. Needs `@scope` (see `hasScope`). */
|
|
509
832
|
when(theme: DeepPartial<T>, colorScheme?: ColorScheme): ThemeKey;
|
|
510
833
|
/** A style key for "the nearest color scheme is this one": the nearest theme given that `colorScheme`, else the system preference. */
|
|
511
834
|
whenScheme(scheme: SchemeName): SchemeKey;
|
|
512
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>. */
|
|
513
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;
|
|
514
862
|
/**
|
|
515
863
|
* A sheet of named styles. Given a function of the theme it is a sheet that is resolved against a
|
|
516
864
|
* theme (`resolve`, which `useStyle` calls). Given an object it is the entries themselves, usable at
|
|
@@ -521,11 +869,64 @@ export interface Engine<T> {
|
|
|
521
869
|
createSheet<K extends string>(styles: (theme: T) => Record<K, WebStyleObject>): ThemedSheet<K, T>;
|
|
522
870
|
/** The logic that every web `styled` shares: the label, the style list, function styles and the class memo. */
|
|
523
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>;
|
|
524
885
|
}
|
|
525
886
|
/** Makes an engine that has no theme yet: it takes one from `setTheme`, or from the first `themeClass`. It needs no framework. */
|
|
526
887
|
export declare function createLazyEngine<T extends object = Theme>(options?: EngineOptions): Engine<T>;
|
|
527
888
|
/** Makes the engine of one theme shape: a cache, the theme as variables, and what the bindings build on. It needs no framework. */
|
|
528
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;
|
|
529
930
|
/**
|
|
530
931
|
* The style element of a static page or a server render: everything `cache` inserted, whatever page
|
|
531
932
|
* inserted it. A cache that renders more than one page (a server process) should use `extractPageStyles`,
|
|
@@ -536,7 +937,7 @@ export declare function createEngine<T extends object>(theme: T, options?: Engin
|
|
|
536
937
|
export declare function createStyleTag(cache: Cache): string;
|
|
537
938
|
/** What one page needs: its CSS, what that CSS covers, and the element to put in its head. */
|
|
538
939
|
export interface PageStyles {
|
|
539
|
-
/** The CSS of the page: the layer order, the `@property` rules, the themes, the rules of its classes. */
|
|
940
|
+
/** The CSS of the page: the layer order, the `@property` rules, the `@keyframes` rules, the themes, the rules of its classes. */
|
|
540
941
|
css: string;
|
|
541
942
|
/** The theme classes and the classes that `css` has rules for. */
|
|
542
943
|
ids: string[];
|
|
@@ -548,19 +949,30 @@ export interface PageStyles {
|
|
|
548
949
|
export interface PageStyleOptions {
|
|
549
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. */
|
|
550
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[];
|
|
551
954
|
}
|
|
552
955
|
/**
|
|
553
956
|
* The CSS of one page, decided from the page: the finished `html` is scanned for the class names it
|
|
554
957
|
* 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
|
|
556
|
-
* trimmed to the variables that the page uses. Nothing depends on what else the cache holds, on the
|
|
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
|
|
557
960
|
* order pages were rendered in, or on pages being rendered at the same time, and the cache is not changed.
|
|
558
961
|
* The `<style href precedence>` elements that `html` carries already (React's server render of the
|
|
559
|
-
* client build emits them) are not written again.
|
|
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.
|
|
560
966
|
*/
|
|
561
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;
|
|
562
974
|
/** What `findMissingStyles` can find. */
|
|
563
|
-
export type StyleProblemKind = 'class-without-rule' | 'variable-without-value';
|
|
975
|
+
export type StyleProblemKind = 'class-without-rule' | 'variable-without-value' | 'root-without-theme';
|
|
564
976
|
/** One thing the page lacks. */
|
|
565
977
|
export interface StyleProblem {
|
|
566
978
|
kind: StyleProblemKind;
|
|
@@ -579,12 +991,15 @@ export interface FindMissingStylesOptions {
|
|
|
579
991
|
}
|
|
580
992
|
/**
|
|
581
993
|
* 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
|
|
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
|
|
583
995
|
* engine's style elements (its own, and the ones React hoists), and every variable of the engine that
|
|
584
996
|
* a rule matching the element uses, without a fallback, has a value on the element. The classes that
|
|
585
997
|
* are markers (`<prefix>-boundary`, `<prefix>-scheme-light` and `-dark`) have no rule of their own and
|
|
586
|
-
* are left out, and so
|
|
587
|
-
*
|
|
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.
|
|
588
1003
|
*/
|
|
589
1004
|
export declare function findMissingStyles(root?: ParentNode, options?: FindMissingStylesOptions): StyleProblem[];
|
|
590
1005
|
/** A short, stable hash of `text`, in base 36. */
|
|
@@ -601,17 +1016,129 @@ export declare function createLazyRecord<K extends string, V>(keys: readonly K[]
|
|
|
601
1016
|
* platform call must not run, before it is used.
|
|
602
1017
|
*/
|
|
603
1018
|
export declare function createDeferredRecord<V>(source: object, build: () => Record<string, V>): Readonly<Record<string, V>>;
|
|
604
|
-
/**
|
|
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
|
+
*/
|
|
605
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;
|
|
606
1057
|
export interface ThemeRuleOptions {
|
|
607
1058
|
/** Sets the color-scheme property in the scope. */
|
|
608
1059
|
colorScheme?: 'light' | 'dark' | 'light dark';
|
|
609
1060
|
}
|
|
610
1061
|
/** The CSS declarations `name:value;` of `entries`. */
|
|
611
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;
|
|
612
1069
|
/**
|
|
613
1070
|
* Registers the theme class of `declarations` and returns it: the scope of a theme. Its name is the
|
|
614
1071
|
* hash of all the declarations, whatever the cache writes of them (see `hasPruning`).
|
|
615
1072
|
*/
|
|
616
1073
|
export declare function createThemeClass(cache: Cache, declarations: Readonly<Record<string, string>>, options?: ThemeRuleOptions): string;
|
|
617
|
-
|
|
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 };
|