@nice2dev/ui-core 1.3.18 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,74 @@
1
1
  # @nice2dev/ui-core — Changelog
2
2
 
3
+ ## 1.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 41a88b4: 1.4.0 — **NiceThemeDesigner edits the new theme fields**:
8
+
9
+ - Every colour field is a **colour, a gradient (surfaces) or a link** — to a palette swatch, a gradient or another
10
+ field ("the same colour, like a variable"). A linked field shows a chip with the target, **Go to the source**
11
+ and **Unlink** (it keeps the colour it showed; one undo step); a value other fields link to shows how many.
12
+ Links that would close a loop are not offered.
13
+ - New sections: **Palette** (named colours and gradients — renaming a swatch rewrites every link to it, removing a
14
+ used one leaves the linked fields their colour), **Layout** (body, panel, top bar, sidebar, sidebar items, with
15
+ their texts and borders; the sidebar's **header levels** — shaded from one colour, a palette or a list, with
16
+ **Sync** and **Sync once** to fix single levels — and the **active item's branch**), **Scrollbar** (colours,
17
+ track and thumb widths, rounding, a live sample).
18
+ - NiceThemePreview draws the theme with its links resolved; its Navigation tab opens with the layout in
19
+ miniature (top bar, sidebar with the shaded active branch, body with a panel, a scroller), and its tints no
20
+ longer break on colours that are not `#rrggbb`.
21
+ - `resolveThemeValue(theme, path)` (ui-core): what a field stands for now, links and defaults followed.
22
+
23
+ - a430ce8: Theme model 1.4.0 — **links, palette, gradients, layout roles, scrollbar**:
24
+
25
+ - A theme value can **link** to another, like a variable: `{palette.gold}`, `{colors.primary}`,
26
+ `{layout.topNav.background}` — the linked field always has the colour of its source. A theme carries a named
27
+ `palette` and named `gradients`; a gradient may carry links (`linear-gradient(135deg, {palette.onyx},
28
+ {palette.gold})`).
29
+ - **`layout`**: the colours of the body, panels, the top bar and the sidebar (`background` — a colour, a gradient or a
30
+ link — `text`, `border`). The sidebar adds its tree's **header levels** (`headers`: shaded from one colour by
31
+ default, a palette or a list; `sync` keeps them derived live, a snapshot lets single levels be fixed), its
32
+ **items** (the leaves) and its **highlight** (the active item and its branch, shaded from the highlight colour, more
33
+ strongly the deeper the level).
34
+ - **`scrollbar`**: track, thumb (colour or gradient), hover, width, the thumb's width inside it, rounding.
35
+ - `resolveTheme()` resolves the links (a loop or a missing link falls back to the field's default, with a
36
+ diagnostic the provider reports once) and derives the colour sets; `themeToCssVars()` uses it, so the new fields
37
+ become `--nice-bg-topnav`, `--nice-bg-topnav-image`, `--nice-sidebar-level-N-*`, `--nice-scrollbar-*` …. Helpers
38
+ for editors: `themeRefsOf`, `wouldCreateCycle`, `renameThemeRef`, `colorSetSnapshot`, `deriveColorSet`.
39
+ - `useNiceTheme().theme` is the theme **with its links resolved**; `sourceTheme` is the theme as written.
40
+ - The colour arithmetic is exported (`parseThemeColor` — now also `#rgba`, `#rrggbbaa`, `hsl()` — `mixThemeColor`,
41
+ `themeContrastText` …). `nesting.sidebar` is deprecated in favour of `layout.sideNav.headers` (still read).
42
+ - A theme switch also clears the previous theme's variables from the portal host.
43
+
44
+ - 8bb55b6: 1.4.0 — **theme previews show the layout**:
45
+
46
+ - `themePreviewRoles(theme)` (ui-core): the colours a thumbnail needs — top bar, sidebar with its first three
47
+ header levels, highlight, body, panel (gradients kept) — every default followed, so themes from before 1.4.0
48
+ get them too.
49
+ - `toThemeDescriptor` resolves links and adds them as `preview.roles`; with roles **`ThemePreviewSwatch`** draws
50
+ `'swatch'` / `'columns'` as one column per role (the sidebar with its header levels at its top) and `'page'` /
51
+ `'layout'` as the app in miniature (top bar, sidebar with levels and the active row, body with a panel). Without
52
+ roles the shapes draw as before. NiceThemePicker, the first-run and setup-wizard pickers and the top bar's
53
+ cluster use it through their descriptors.
54
+ - **NiceThemeDesigner**'s themes tree shows the columns preview in place of its two bars.
55
+
56
+ - 2290551: 1.4.0 — **eight curated themes, the rest archived** (breaking):
57
+
58
+ - `NICE_THEME_PRESETS` — what the pickers, the theme catalog and NiceThemeDesigner offer — is now eight themes in the
59
+ 1.4.0 standard (palette, gradients, layout colours, shaded sidebar headers, active path, scrollbars): **Black Tie
60
+ Gala** — black and gold, the **default** (`NICE_THEME_DEFAULT`; sans-serif now) — then Fluent, Slate, Minimalism,
61
+ Banking (light) and Obsidian, Onyx, Shadow (dark). As packs: `NICE_THEME_CURATED_PACKS`. Each passes WCAG AA on
62
+ every layout surface, header level and the active row.
63
+ - The themes from before 1.4.0 — the 100-theme gallery, the 36 packs, Blue / High Contrast / Material / Bootstrap /
64
+ the old Fluent — are in **`NICE_THEME_ARCHIVE`** (`core`, `gallery`, `packs`, `packsExtended`, `all`), names a
65
+ curated theme took suffixed " Classic"; their named exports stay. `NICE_THEME_ARCHIVE_CATALOG` (ui) lists them in
66
+ their old categories.
67
+ - `NICE_THEME_CATALOG` has three categories: Premium, Light, Dark.
68
+ - NiceThemeProvider: `theme="light"` / `"dark"` keep the base themes (`niceThemeLight` / `niceThemeDark`); a curated
69
+ name selects that theme; any other name — an archived theme's among them — falls back to Black Tie Gala with a
70
+ warning (import the archived theme and pass the object).
71
+
3
72
  ## 1.3.18
4
73
 
5
74
  No changes in this release.
@@ -6,10 +6,12 @@ export interface NiceThemeProviderProps {
6
6
  /**
7
7
  * Current theme. Accepts either a full {@link NiceTheme} object or the
8
8
  * name of a built-in preset (case-insensitive, hyphens/spaces ignored):
9
- * `'light'`, `'dark'`, `'blue'`, `'high-contrast'`, `'material'`,
10
- * `'bootstrap'`, `'fluent'`, or any name from `NICE_THEME_PRESETS`.
9
+ * `'light'`, `'dark'` (the base themes), or a curated theme from `NICE_THEME_PRESETS` —
10
+ * `'black-tie-gala'`, `'fluent'`, `'slate'`, `'minimalism'`, `'banking'`, `'obsidian'`,
11
+ * `'onyx'`, `'shadow'` (1.4.0).
11
12
  *
12
- * Unknown strings fall back to {@link niceThemeLight} with a dev-mode warning.
13
+ * Unknown strings — the themes from before 1.4.0 among them (`NICE_THEME_ARCHIVE`) — fall back to
14
+ * `NICE_THEME_DEFAULT` (Black Tie Gala) with a dev-mode warning.
13
15
  */
14
16
  theme: NiceTheme | string;
15
17
  /** Optional dark companion theme (used when darkMode='auto' and system prefers dark) */
@@ -192,10 +192,100 @@ export interface NiceThemeNesting {
192
192
  }
193
193
  /** Container for nesting palettes scoped to specific navigation surfaces. */
194
194
  export interface NiceThemeNestingSet {
195
+ /** @deprecated 1.4.0 — use `layout.sideNav.headers`; still read when that is absent. */
195
196
  sidebar?: NiceThemeNesting;
196
197
  menu?: NiceThemeNesting;
197
198
  tree?: NiceThemeNesting;
198
199
  }
200
+ /**
201
+ * A theme colour value (1.4.0): a CSS colour, a CSS gradient (only where a surface takes one —
202
+ * `layout.*.background`, `scrollbar.thumb`), or a link to another value written `{path}`:
203
+ * `{palette.gold}`, `{gradients.sheen}`, `{colors.primary}`, `{layout.topNav.background}`. A
204
+ * linked field always has the colour of what it links to, like a variable. A gradient may carry
205
+ * links: `linear-gradient(135deg, {palette.onyx}, {palette.gold})`.
206
+ */
207
+ export type NiceThemeValue = string;
208
+ /** A named gradient of a theme; `base` is the colour used where one colour is needed. */
209
+ export interface NiceThemeGradient {
210
+ css: string;
211
+ base?: NiceThemeValue;
212
+ }
213
+ /** One level of a colour set: its background and text (and, optionally, its hover / active). */
214
+ export interface NiceColorLevel {
215
+ background?: NiceThemeValue;
216
+ text?: NiceThemeValue;
217
+ hoverBackground?: NiceThemeValue;
218
+ activeBackground?: NiceThemeValue;
219
+ }
220
+ /** How a colour set gets its levels: shaded from one colour, a palette's swatches, or a list. */
221
+ export type NiceColorSetMode = 'shade' | 'palette' | 'list';
222
+ /**
223
+ * A set of colours, one per level — the sidebar tree's header levels, the active path (1.4.0).
224
+ * `shade` (default): `base` mixed over the surface by `curve`. `palette`: the swatches named in
225
+ * `swatches` (default all of the theme's palette), cycled. `list`: `levels` as given.
226
+ * `sync` (default true) keeps shaded / palette levels derived live; "sync once" writes the derived
227
+ * levels into `levels` and sets `sync: false`, so single levels can be fixed by hand — a level left
228
+ * out is still derived.
229
+ */
230
+ export interface NiceColorSet {
231
+ mode?: NiceColorSetMode;
232
+ base?: NiceThemeValue;
233
+ swatches?: string[];
234
+ /** Levels (1..10); default 6. */
235
+ count?: number;
236
+ /** Strength of `base` per level, 0..1; default [1, .40, .28, .18, .11, .06] (the last repeats). */
237
+ curve?: number[];
238
+ sync?: boolean;
239
+ levels?: NiceColorLevel[];
240
+ }
241
+ /** A surface of the layout: background (colour, gradient or link), text and border. */
242
+ export interface NiceSurfaceRole {
243
+ background?: NiceThemeValue;
244
+ text?: NiceThemeValue;
245
+ border?: NiceThemeValue;
246
+ }
247
+ /** The sidebar: its own surface, the tree's header levels, its items (leaves), the active path. */
248
+ export interface NiceSideNavRole extends NiceSurfaceRole {
249
+ /** Header levels of the tree (its branches), by depth. Default: shaded from the primary. */
250
+ headers?: NiceColorSet;
251
+ /** Items — the tree's leaves. Default: a `tint` (0..1, default .45) of their level's colour. */
252
+ items?: {
253
+ background?: NiceThemeValue;
254
+ text?: NiceThemeValue;
255
+ tint?: number;
256
+ };
257
+ /**
258
+ * The active item and the branch above it: `base` is the active row; each level of its path is
259
+ * shaded from it over that level's header colour, more strongly the deeper it is.
260
+ */
261
+ highlight?: NiceColorSet & {
262
+ text?: NiceThemeValue;
263
+ };
264
+ }
265
+ /** The colours of the application's layout (1.4.0). */
266
+ export interface NiceThemeLayout {
267
+ /** The page behind everything — the shell's content area. */
268
+ body?: NiceSurfaceRole;
269
+ /** Cards and panes. */
270
+ panel?: NiceSurfaceRole;
271
+ /** The top navigation bar. */
272
+ topNav?: NiceSurfaceRole;
273
+ /** The side navigation. */
274
+ sideNav?: NiceSideNavRole;
275
+ }
276
+ /** Scrollbars (1.4.0): colours, the track's width, the thumb's width inside it, rounding. */
277
+ export interface NiceThemeScrollbar {
278
+ track?: NiceThemeValue;
279
+ /** A colour or a gradient. */
280
+ thumb?: NiceThemeValue;
281
+ thumbHover?: NiceThemeValue;
282
+ /** The track's width, e.g. '10px'. */
283
+ width?: string;
284
+ /** The thumb's width inside the track, e.g. '6px'. */
285
+ thumbWidth?: string;
286
+ /** e.g. '4px', or 'full'. */
287
+ radius?: string;
288
+ }
199
289
  /**
200
290
  * Complete theme definition — a JSON-serializable object that controls all visual styling
201
291
  * via CSS custom properties. Can be created, stored, and loaded at runtime.
@@ -230,9 +320,23 @@ export interface NiceTheme {
230
320
  * by depth.
231
321
  */
232
322
  nesting?: NiceThemeNestingSet;
323
+ /** 2 for a theme that uses the 1.4.0 fields (palette, links, layout, scrollbar). */
324
+ schemaVersion?: 1 | 2;
325
+ /** Named swatches any colour field can link to: `{palette.gold}` (1.4.0). */
326
+ palette?: Record<string, string>;
327
+ /** Named gradients surfaces can use: `{gradients.sheen}` (1.4.0). */
328
+ gradients?: Record<string, string | NiceThemeGradient>;
329
+ /** The layout's colours: body, panels, top bar, sidebar (1.4.0). */
330
+ layout?: NiceThemeLayout;
331
+ /** Scrollbars (1.4.0). */
332
+ scrollbar?: NiceThemeScrollbar;
233
333
  }
234
- /** Converts a {@link NiceTheme} to a flat `Record<string, string>` of CSS custom properties. */
235
- export declare function themeToCssVars(theme: NiceTheme): Record<string, string>;
334
+ /**
335
+ * Converts a {@link NiceTheme} to a flat `Record<string, string>` of CSS custom properties. Links
336
+ * (`{palette.gold}` …) are resolved first (1.4.0, {@link resolveTheme}); the 1.4.0 fields a theme
337
+ * sets — layout, scrollbar, the sidebar's header levels — add their variables.
338
+ */
339
+ export declare function themeToCssVars(sourceTheme: NiceTheme): Record<string, string>;
236
340
  /** Applies a theme to the DOM by setting CSS custom properties on the target element (defaults to `:root`). */
237
341
  export declare function applyTheme(theme: NiceTheme, element?: HTMLElement): void;
238
342
  /** Removes all theme CSS custom properties from the target element. */
@@ -262,7 +366,10 @@ export declare function isDerivableColor(value: string): boolean;
262
366
  */
263
367
  export declare function nestingLevelColors(count: number, cfg: NiceThemeNesting, fallbackBg: string, fallbackText: string): NiceNestingLevelColors[];
264
368
  export interface NiceThemeContextValue {
369
+ /** The theme in effect, links resolved (1.4.0): `colors.primary` is a colour, never `{…}`. */
265
370
  theme: NiceTheme;
371
+ /** The theme as written — links (`{palette.gold}`) kept, as an editor or a save needs it (1.4.0). */
372
+ sourceTheme?: NiceTheme;
266
373
  setTheme: (theme: NiceTheme) => void;
267
374
  /**
268
375
  * DOM node that lives directly inside `document.body` but carries the same
@@ -0,0 +1,40 @@
1
+ /** An sRGB colour, channels 0..255, alpha 0..1. */
2
+ export interface ThemeRgb {
3
+ r: number;
4
+ g: number;
5
+ b: number;
6
+ a?: number;
7
+ }
8
+ export declare const THEME_WHITE = "#ffffff";
9
+ export declare const THEME_BLACK = "#000000";
10
+ /**
11
+ * `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` / `rgba()` and `hsl()` / `hsla()` (comma or
12
+ * space separated) as channels; anything else — a `var()`, a named colour, `oklch()` — is null.
13
+ */
14
+ export declare function parseThemeColor(value: string | undefined | null): ThemeRgb | null;
15
+ /** `#rrggbb` (alpha dropped). */
16
+ export declare function themeColorToHex({ r, g, b }: ThemeRgb): string;
17
+ /** `a` moved `t` (0..1) of the way to `b`, as hex; `a` as given when either cannot be read. */
18
+ export declare function mixThemeColor(a: string, b: string, t: number): string;
19
+ /**
20
+ * Like {@link mixThemeColor}, but a colour it cannot read (a `var()`, `oklch()` …) is mixed by the
21
+ * browser: `color-mix(in srgb, …)`.
22
+ */
23
+ export declare function mixThemeColorCss(a: string, b: string, t: number): string;
24
+ export declare const tintThemeColor: (color: string, amount: number) => string;
25
+ export declare const shadeThemeColor: (color: string, amount: number) => string;
26
+ /** WCAG relative luminance; 1 for a colour it cannot read. */
27
+ export declare function themeLuminance(color: string): number;
28
+ /** WCAG contrast ratio of two luminances. */
29
+ export declare function themeContrastRatio(a: number, b: number): number;
30
+ /** WCAG contrast ratio of two colours (1 when either cannot be read). */
31
+ export declare function themeColorContrast(a: string, b: string): number;
32
+ /**
33
+ * The text with the higher WCAG contrast on `bg` (1.3.2). A background it cannot read keeps
34
+ * `darkText`.
35
+ */
36
+ export declare function themeContrastText(bg: string, lightText: string, darkText: string): string;
37
+ /** The colour a gradient stands for when one colour is needed: its readable stops averaged. */
38
+ export declare function gradientBaseColor(css: string): string | null;
39
+ /** Whether a value is a CSS gradient. */
40
+ export declare const isThemeGradient: (value: string | undefined | null) => boolean;
@@ -6,4 +6,10 @@ export declare const niceThemeHighContrast: NiceTheme;
6
6
  export declare const niceThemeMaterial: NiceTheme;
7
7
  export declare const niceThemeBootstrap: NiceTheme;
8
8
  export declare const niceThemeFluent: NiceTheme;
9
+ /**
10
+ * The built-in themes the pickers and the catalogue offer (1.4.0): the eight curated ones — Black
11
+ * Tie Gala (the default), Fluent, Slate, Minimalism, Banking, Obsidian, Onyx, Shadow. The themes
12
+ * from before 1.4.0 are in `NICE_THEME_ARCHIVE`; `niceThemeLight` / `niceThemeDark` stay the base
13
+ * light and dark themes (`theme="light"` / `"dark"`).
14
+ */
9
15
  export declare const NICE_THEME_PRESETS: NiceTheme[];
@@ -0,0 +1,16 @@
1
+ import type { NiceTheme } from './theme';
2
+ import { type NiceThemePack } from './themePacks';
3
+ /** The themes from before 1.4.0, by origin (1.4.0). */
4
+ export interface NiceThemeArchive {
5
+ /** The core presets: Blue, High Contrast, Material, Bootstrap, Fluent Classic. */
6
+ readonly core: NiceTheme[];
7
+ /** The 100-theme gallery. */
8
+ readonly gallery: NiceTheme[];
9
+ /** The 12 packs and the 24 more (with their display styles). */
10
+ readonly packs: NiceThemePack[];
11
+ readonly packsExtended: NiceThemePack[];
12
+ /** Every archived theme in one list, the core ones first. */
13
+ readonly all: NiceTheme[];
14
+ }
15
+ /** The themes from before 1.4.0 (1.4.0) — import one and pass it to NiceThemeProvider. */
16
+ export declare const NICE_THEME_ARCHIVE: NiceThemeArchive;
@@ -0,0 +1,16 @@
1
+ import type { NiceTheme } from './theme';
2
+ import type { NiceThemePack } from './themePacks';
3
+ export declare const niceThemeBlackTieGala: NiceTheme;
4
+ export declare const niceThemeFluentV2: NiceTheme;
5
+ export declare const niceThemeSlateV2: NiceTheme;
6
+ export declare const niceThemeMinimalism: NiceTheme;
7
+ export declare const niceThemeBankingV2: NiceTheme;
8
+ export declare const niceThemeObsidianV2: NiceTheme;
9
+ export declare const niceThemeOnyxV2: NiceTheme;
10
+ export declare const niceThemeShadowV2: NiceTheme;
11
+ /** The curated themes (1.4.0) as packs: the default first, then the light ones, then the dark. */
12
+ export declare const NICE_THEME_CURATED_PACKS: readonly NiceThemePack[];
13
+ /** The curated themes (1.4.0), in the order of {@link NICE_THEME_CURATED_PACKS}. */
14
+ export declare const NICE_THEME_CURATED: readonly NiceTheme[];
15
+ /** The default theme (1.4.0): Black Tie Gala. */
16
+ export declare const NICE_THEME_DEFAULT: NiceTheme;
@@ -0,0 +1,110 @@
1
+ import type { NiceColorLevel, NiceColorSet, NiceTheme } from './theme';
2
+ /** Something the resolver could not honour; the value fell back to its default. */
3
+ export interface NiceThemeDiagnostic {
4
+ path: string;
5
+ kind: 'cycle' | 'missing' | 'gradient-in-color';
6
+ ref?: string;
7
+ message: string;
8
+ }
9
+ /** The colours of one level of a colour set. */
10
+ export interface NiceResolvedLevel {
11
+ bg: string;
12
+ text: string;
13
+ hoverBg: string;
14
+ activeBg: string;
15
+ }
16
+ /** A theme with every link resolved, and the 1.4.0 CSS variables it sets. */
17
+ export interface NiceResolvedTheme {
18
+ /** The theme without links: surfaces keep gradients, colour fields get colours. */
19
+ theme: NiceTheme;
20
+ /** CSS variables of the 1.4.0 fields the theme sets (layout, scrollbar, header levels…). */
21
+ vars: Record<string, string>;
22
+ /** The sidebar's header levels, when the theme sets them. */
23
+ headerLevels?: NiceResolvedLevel[];
24
+ diagnostics: NiceThemeDiagnostic[];
25
+ }
26
+ /** Default strength of the base colour per header level — the curve the stylesheet uses. */
27
+ export declare const THEME_HEADER_CURVE: number[];
28
+ /** Default strength of the highlight over each level of the active path, root first. */
29
+ export declare const THEME_HIGHLIGHT_CURVE: number[];
30
+ /**
31
+ * What a field stands for when a theme leaves it out — the same values the stylesheet's defaults
32
+ * use, so a link to an absent field gets what the page shows.
33
+ */
34
+ export declare const THEME_DEFAULT_LINKS: Readonly<Record<string, string>>;
35
+ /** The fields that take a gradient as well as a colour. */
36
+ export declare const THEME_SURFACE_PATHS: readonly string[];
37
+ /** The path a value links to (`{palette.gold}` → `palette.gold`), or null. */
38
+ export declare function parseThemeRef(value: unknown): string | null;
39
+ /** Every path a value links to, its gradient's embedded links included. */
40
+ export declare function themeRefsIn(value: unknown): string[];
41
+ /** The value at a dotted path (`layout.sideNav.headers.levels.0.background`). */
42
+ export declare function getThemeValue(theme: NiceTheme, path: string): unknown;
43
+ /** The paths whose value links to `target` (directly or in a gradient). */
44
+ export declare function themeRefsOf(theme: NiceTheme, target: string): string[];
45
+ /** Whether linking `from` to `to` would close a loop (defaults followed too). */
46
+ export declare function wouldCreateCycle(theme: NiceTheme, from: string, to: string): boolean;
47
+ /** The theme with every link to `from` pointing at `to` instead (e.g. a renamed swatch). */
48
+ export declare function renameThemeRef(theme: NiceTheme, from: string, to: string): NiceTheme;
49
+ /** What a colour set is derived from. */
50
+ export interface NiceColorSetContext {
51
+ /** The surface the levels are mixed over. */
52
+ over: string;
53
+ /** The default base colour. */
54
+ base: string;
55
+ /** The two texts to choose from per level (the better reading one wins). */
56
+ text: string;
57
+ onBase: string;
58
+ /** The theme's palette, resolved. */
59
+ palette: Record<string, string>;
60
+ curve: number[];
61
+ /** Resolves a colour written in the set (a colour or a link). */
62
+ color: (value: string | undefined, path: string) => string | null;
63
+ /** The path of the set, for diagnostics. */
64
+ path: string;
65
+ }
66
+ /** The levels of a colour set (see {@link NiceColorSet}). */
67
+ export declare function deriveColorSet(set: NiceColorSet, ctx: NiceColorSetContext): NiceResolvedLevel[];
68
+ /**
69
+ * What a field of a theme stands for now (1.4.0): its value with links followed — and, for a field the
70
+ * theme leaves out, its default — as CSS (`css`: a colour or a gradient) and as one colour (`color`).
71
+ * Null when nothing resolves. An editor shows a linked field with it.
72
+ */
73
+ export declare function resolveThemeValue(theme: NiceTheme, path: string): {
74
+ css: string;
75
+ color: string;
76
+ } | null;
77
+ /** The levels a colour set derives now, as plain colours — what "sync once" writes into it. */
78
+ export declare function colorSetSnapshot(theme: NiceTheme, which: 'headers' | 'highlight'): NiceColorLevel[];
79
+ /**
80
+ * The colours a small theme preview shows (1.4.0) — the layout's roles with every default followed,
81
+ * so a theme from before 1.4.0 gets them too. A surface keeps its gradient in `*Image`.
82
+ */
83
+ export interface NiceThemePreviewRoles {
84
+ topNav: string;
85
+ topNavImage?: string;
86
+ topNavText: string;
87
+ sideNav: string;
88
+ sideNavImage?: string;
89
+ sideNavText: string;
90
+ /** The first three header levels of the sidebar's tree, and their texts. */
91
+ headers: string[];
92
+ headerTexts: string[];
93
+ /** The active item. */
94
+ highlight: string;
95
+ body: string;
96
+ bodyImage?: string;
97
+ panel: string;
98
+ panelImage?: string;
99
+ panelBorder: string;
100
+ text: string;
101
+ primary: string;
102
+ accent: string;
103
+ }
104
+ /** The colours of a theme's layout for a preview thumbnail (see {@link NiceThemePreviewRoles}). */
105
+ export declare function themePreviewRoles(theme: NiceTheme): NiceThemePreviewRoles;
106
+ /**
107
+ * Resolves a theme's links and derives its colour sets (memoised per theme object). Old themes —
108
+ * without the 1.4.0 fields — come back unchanged and set no new variables.
109
+ */
110
+ export declare function resolveTheme(theme: NiceTheme): NiceResolvedTheme;