@dloizides/theme-web 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.5.0
4
+
5
+ INVOICE-5 "Edit invoices before sending, shared background and menu hover": app background presets. `TenantThemeConfig.backdrop` takes one `BackdropPreset` (`plain` default, `paper`, `ledger`, `horizon`, `tint`); `resolveTheme` puts the result on `theme.backdrop`, and `resolveBackdrop(theme, preset)` resolves one directly. Every colour comes from the theme; page and band inks clear 4.5:1 plus the 0.25 margin. No preset set = today's flat background.
6
+
7
+ ## 1.4.0
8
+
9
+ INVOICE-3 "Invoice interface over a user-chosen folder": `ThemeProvider` gains `forcedMode`, which holds one mode whatever the OS or a stored preference says.
10
+
3
11
  ## 1.3.0
4
12
 
5
13
  **Accessibility — two structural contrast defects closed, both guarded at the class level.**
package/README.md CHANGED
@@ -75,6 +75,10 @@ badgeColors(theme.semantic.info)
75
75
  plus `AA_CONTRAST_MARGIN`, so dark seeds keep a rich `600` and pale seeds fall through to `900`.
76
76
  The result is mode-independent (semantic scales are seeded from the config alone).
77
77
 
78
+ ## App background — `backdrop`
79
+
80
+ Set one value: `{ ...config, backdrop: BackdropPreset.Horizon }`. `theme.backdrop` then holds `color`, an optional web CSS `image` + `imageSize`, `text` / `textSecondary` inks that clear AA on `color`, a `band` (horizon only: colour, inks, `overlap` of 56 px compact / 64 px wide) and `liftSurfaces` (cards get a shadow). Presets: `plain` (default, unchanged), `paper` (surface + border grain), `ledger` (divider rules every 32 px), `horizon` (brand band behind the header), `tint` (lightest brand shade, darkest in dark mode).
81
+
78
82
  ## Asserting your own palette
79
83
 
80
84
  `contrastRatio`, `meetsContrast`, `relativeLuminance`, the `AA_*` thresholds and
package/dist/index.d.mts CHANGED
@@ -13,6 +13,16 @@ declare const ThemeMode: {
13
13
  };
14
14
  type ThemeMode = (typeof ThemeMode)[keyof typeof ThemeMode];
15
15
 
16
+ /** App background preset, chosen by one config value. `Plain` keeps today's flat background. */
17
+ declare const BackdropPreset: {
18
+ readonly Plain: "plain";
19
+ readonly Paper: "paper";
20
+ readonly Ledger: "ledger";
21
+ readonly Horizon: "horizon";
22
+ readonly Tint: "tint";
23
+ };
24
+ type BackdropPreset = (typeof BackdropPreset)[keyof typeof BackdropPreset];
25
+
16
26
  /**
17
27
  * Theme type system — promoted verbatim (shapes unchanged) from the duplicated
18
28
  * erevna-web / katalogos-web `src/theme/types`, so a migrated app's
@@ -82,6 +92,8 @@ interface TenantThemeConfig {
82
92
  dark: ThemeModeColors;
83
93
  typography?: TypographyConfig;
84
94
  branding: BrandingConfig;
95
+ /** App background preset; omitted = `plain`, today's flat background. */
96
+ backdrop?: BackdropPreset;
85
97
  }
86
98
  /** Full shade palettes for brand colors. Type alias — see {@link ColorScale}. */
87
99
  type ResolvedPalette = {
@@ -114,6 +126,29 @@ interface ResolvedTheme {
114
126
  typography: ResolvedTypography;
115
127
  mode: ThemeMode;
116
128
  branding: ResolvedBranding;
129
+ /** Resolved app background; set by `resolveTheme`. */
130
+ backdrop?: ResolvedBackdrop;
131
+ }
132
+ /** Brand band of the `horizon` backdrop, with how far content overlaps its lower edge. */
133
+ interface ResolvedBackdropBand {
134
+ color: string;
135
+ text: string;
136
+ textSecondary: string;
137
+ overlap: {
138
+ compact: number;
139
+ wide: number;
140
+ };
141
+ }
142
+ /** App background: base colour, optional web CSS image, inks that clear AA on it. */
143
+ interface ResolvedBackdrop {
144
+ preset: BackdropPreset;
145
+ color: string;
146
+ image: string | null;
147
+ imageSize: string | null;
148
+ text: string;
149
+ textSecondary: string;
150
+ band: ResolvedBackdropBand | null;
151
+ liftSurfaces: boolean;
117
152
  }
118
153
 
119
154
  /**
@@ -136,9 +171,11 @@ interface ThemeProviderProps {
136
171
  defaultThemeConfig?: TenantThemeConfig;
137
172
  /** Override the localStorage key for the dark-mode preference. */
138
173
  storageKey?: string;
174
+ /** Holds this mode whatever the OS or a stored preference says, for a product designed in one mode. */
175
+ forcedMode?: ThemeMode;
139
176
  children: React__default.ReactNode;
140
177
  }
141
- declare const ThemeProvider: ({ tenantThemeConfig, defaultThemeConfig, storageKey, children, }: ThemeProviderProps) => React__default.ReactElement;
178
+ declare const ThemeProvider: ({ tenantThemeConfig, defaultThemeConfig, storageKey, forcedMode, children, }: ThemeProviderProps) => React__default.ReactElement;
142
179
 
143
180
  /**
144
181
  * User dark-mode preference: an explicit `light`/`dark`, or `system` (follow the
@@ -210,6 +247,9 @@ declare const DEFAULT_THEME_CONFIG: TenantThemeConfig;
210
247
  /** Project a design-token set onto a `TenantThemeConfig`. */
211
248
  declare function fromDesignTokens(tokens: DesignTokens): TenantThemeConfig;
212
249
 
250
+ /** Resolve a backdrop preset to theme-derived fills whose text inks clear WCAG AA. */
251
+ declare function resolveBackdrop(theme: ResolvedTheme, preset?: BackdropPreset): ResolvedBackdrop;
252
+
213
253
  /**
214
254
  * Palette Generator — promoted verbatim (algorithm + constants unchanged) from
215
255
  * the duplicated erevna-web / katalogos-web `theme/utils/palette-generator.ts`.
@@ -331,4 +371,4 @@ declare function contrastRatio(foreground: string, background: string): number;
331
371
  /** True when `foreground` on `background` meets `requiredRatio`. */
332
372
  declare function meetsContrast(foreground: string, background: string, requiredRatio: number): boolean;
333
373
 
334
- export { AA_CONTRAST_MARGIN, AA_LARGE_TEXT_RATIO, AA_NON_TEXT_RATIO, AA_NORMAL_TEXT_RATIO, BADGE_TINT_SHADE, type BadgeColors, type BrandingConfig, type ColorScale, DEFAULT_DARK_MODE_STORAGE_KEY, DEFAULT_THEME_CONFIG, DarkModePreference, type ResolvedBranding, type ResolvedPalette, type ResolvedSemanticColors, type ResolvedTheme, type ResolvedTypography, type SemanticColorOverrides, type TenantThemeConfig, ThemeContext, type ThemeContextValue, ThemeMode, type ThemeModeColors, ThemeProvider, type ThemeProviderProps, type TypographyConfig, type UseDarkModeReturn, badgeColors, contrastRatio, darken, fromDesignTokens, generateColorScale, generateThemePalette, hexToHsl, hslToHex, isValidHex, lighten, meetsContrast, relativeLuminance, resolveTheme, useDarkMode, useTheme };
374
+ export { AA_CONTRAST_MARGIN, AA_LARGE_TEXT_RATIO, AA_NON_TEXT_RATIO, AA_NORMAL_TEXT_RATIO, BADGE_TINT_SHADE, BackdropPreset, type BadgeColors, type BrandingConfig, type ColorScale, DEFAULT_DARK_MODE_STORAGE_KEY, DEFAULT_THEME_CONFIG, DarkModePreference, type ResolvedBackdrop, type ResolvedBackdropBand, type ResolvedBranding, type ResolvedPalette, type ResolvedSemanticColors, type ResolvedTheme, type ResolvedTypography, type SemanticColorOverrides, type TenantThemeConfig, ThemeContext, type ThemeContextValue, ThemeMode, type ThemeModeColors, ThemeProvider, type ThemeProviderProps, type TypographyConfig, type UseDarkModeReturn, badgeColors, contrastRatio, darken, fromDesignTokens, generateColorScale, generateThemePalette, hexToHsl, hslToHex, isValidHex, lighten, meetsContrast, relativeLuminance, resolveBackdrop, resolveTheme, useDarkMode, useTheme };
package/dist/index.d.ts CHANGED
@@ -13,6 +13,16 @@ declare const ThemeMode: {
13
13
  };
14
14
  type ThemeMode = (typeof ThemeMode)[keyof typeof ThemeMode];
15
15
 
16
+ /** App background preset, chosen by one config value. `Plain` keeps today's flat background. */
17
+ declare const BackdropPreset: {
18
+ readonly Plain: "plain";
19
+ readonly Paper: "paper";
20
+ readonly Ledger: "ledger";
21
+ readonly Horizon: "horizon";
22
+ readonly Tint: "tint";
23
+ };
24
+ type BackdropPreset = (typeof BackdropPreset)[keyof typeof BackdropPreset];
25
+
16
26
  /**
17
27
  * Theme type system — promoted verbatim (shapes unchanged) from the duplicated
18
28
  * erevna-web / katalogos-web `src/theme/types`, so a migrated app's
@@ -82,6 +92,8 @@ interface TenantThemeConfig {
82
92
  dark: ThemeModeColors;
83
93
  typography?: TypographyConfig;
84
94
  branding: BrandingConfig;
95
+ /** App background preset; omitted = `plain`, today's flat background. */
96
+ backdrop?: BackdropPreset;
85
97
  }
86
98
  /** Full shade palettes for brand colors. Type alias — see {@link ColorScale}. */
87
99
  type ResolvedPalette = {
@@ -114,6 +126,29 @@ interface ResolvedTheme {
114
126
  typography: ResolvedTypography;
115
127
  mode: ThemeMode;
116
128
  branding: ResolvedBranding;
129
+ /** Resolved app background; set by `resolveTheme`. */
130
+ backdrop?: ResolvedBackdrop;
131
+ }
132
+ /** Brand band of the `horizon` backdrop, with how far content overlaps its lower edge. */
133
+ interface ResolvedBackdropBand {
134
+ color: string;
135
+ text: string;
136
+ textSecondary: string;
137
+ overlap: {
138
+ compact: number;
139
+ wide: number;
140
+ };
141
+ }
142
+ /** App background: base colour, optional web CSS image, inks that clear AA on it. */
143
+ interface ResolvedBackdrop {
144
+ preset: BackdropPreset;
145
+ color: string;
146
+ image: string | null;
147
+ imageSize: string | null;
148
+ text: string;
149
+ textSecondary: string;
150
+ band: ResolvedBackdropBand | null;
151
+ liftSurfaces: boolean;
117
152
  }
118
153
 
119
154
  /**
@@ -136,9 +171,11 @@ interface ThemeProviderProps {
136
171
  defaultThemeConfig?: TenantThemeConfig;
137
172
  /** Override the localStorage key for the dark-mode preference. */
138
173
  storageKey?: string;
174
+ /** Holds this mode whatever the OS or a stored preference says, for a product designed in one mode. */
175
+ forcedMode?: ThemeMode;
139
176
  children: React__default.ReactNode;
140
177
  }
141
- declare const ThemeProvider: ({ tenantThemeConfig, defaultThemeConfig, storageKey, children, }: ThemeProviderProps) => React__default.ReactElement;
178
+ declare const ThemeProvider: ({ tenantThemeConfig, defaultThemeConfig, storageKey, forcedMode, children, }: ThemeProviderProps) => React__default.ReactElement;
142
179
 
143
180
  /**
144
181
  * User dark-mode preference: an explicit `light`/`dark`, or `system` (follow the
@@ -210,6 +247,9 @@ declare const DEFAULT_THEME_CONFIG: TenantThemeConfig;
210
247
  /** Project a design-token set onto a `TenantThemeConfig`. */
211
248
  declare function fromDesignTokens(tokens: DesignTokens): TenantThemeConfig;
212
249
 
250
+ /** Resolve a backdrop preset to theme-derived fills whose text inks clear WCAG AA. */
251
+ declare function resolveBackdrop(theme: ResolvedTheme, preset?: BackdropPreset): ResolvedBackdrop;
252
+
213
253
  /**
214
254
  * Palette Generator — promoted verbatim (algorithm + constants unchanged) from
215
255
  * the duplicated erevna-web / katalogos-web `theme/utils/palette-generator.ts`.
@@ -331,4 +371,4 @@ declare function contrastRatio(foreground: string, background: string): number;
331
371
  /** True when `foreground` on `background` meets `requiredRatio`. */
332
372
  declare function meetsContrast(foreground: string, background: string, requiredRatio: number): boolean;
333
373
 
334
- export { AA_CONTRAST_MARGIN, AA_LARGE_TEXT_RATIO, AA_NON_TEXT_RATIO, AA_NORMAL_TEXT_RATIO, BADGE_TINT_SHADE, type BadgeColors, type BrandingConfig, type ColorScale, DEFAULT_DARK_MODE_STORAGE_KEY, DEFAULT_THEME_CONFIG, DarkModePreference, type ResolvedBranding, type ResolvedPalette, type ResolvedSemanticColors, type ResolvedTheme, type ResolvedTypography, type SemanticColorOverrides, type TenantThemeConfig, ThemeContext, type ThemeContextValue, ThemeMode, type ThemeModeColors, ThemeProvider, type ThemeProviderProps, type TypographyConfig, type UseDarkModeReturn, badgeColors, contrastRatio, darken, fromDesignTokens, generateColorScale, generateThemePalette, hexToHsl, hslToHex, isValidHex, lighten, meetsContrast, relativeLuminance, resolveTheme, useDarkMode, useTheme };
374
+ export { AA_CONTRAST_MARGIN, AA_LARGE_TEXT_RATIO, AA_NON_TEXT_RATIO, AA_NORMAL_TEXT_RATIO, BADGE_TINT_SHADE, BackdropPreset, type BadgeColors, type BrandingConfig, type ColorScale, DEFAULT_DARK_MODE_STORAGE_KEY, DEFAULT_THEME_CONFIG, DarkModePreference, type ResolvedBackdrop, type ResolvedBackdropBand, type ResolvedBranding, type ResolvedPalette, type ResolvedSemanticColors, type ResolvedTheme, type ResolvedTypography, type SemanticColorOverrides, type TenantThemeConfig, ThemeContext, type ThemeContextValue, ThemeMode, type ThemeModeColors, ThemeProvider, type ThemeProviderProps, type TypographyConfig, type UseDarkModeReturn, badgeColors, contrastRatio, darken, fromDesignTokens, generateColorScale, generateThemePalette, hexToHsl, hslToHex, isValidHex, lighten, meetsContrast, relativeLuminance, resolveBackdrop, resolveTheme, useDarkMode, useTheme };
package/dist/index.js CHANGED
@@ -209,13 +209,155 @@ function generateThemePalette(config) {
209
209
  };
210
210
  }
211
211
 
212
+ // src/BackdropPreset.ts
213
+ var BackdropPreset = {
214
+ Plain: "plain",
215
+ Paper: "paper",
216
+ Ledger: "ledger",
217
+ Horizon: "horizon",
218
+ Tint: "tint"
219
+ };
220
+
221
+ // src/contrast.ts
222
+ var AA_NORMAL_TEXT_RATIO = 4.5;
223
+ var AA_LARGE_TEXT_RATIO = 3;
224
+ var AA_NON_TEXT_RATIO = 3;
225
+ var AA_CONTRAST_MARGIN = 0.25;
226
+ var SRGB_CHANNEL_MAX = 255;
227
+ var GAMMA_LINEAR_THRESHOLD = 0.03928;
228
+ var GAMMA_LINEAR_DIVISOR = 12.92;
229
+ var GAMMA_OFFSET = 0.055;
230
+ var GAMMA_DIVISOR = 1.055;
231
+ var GAMMA_EXPONENT = 2.4;
232
+ var LUMA_COEFFICIENT_RED = 0.2126;
233
+ var LUMA_COEFFICIENT_GREEN = 0.7152;
234
+ var LUMA_COEFFICIENT_BLUE = 0.0722;
235
+ var CONTRAST_FLARE = 0.05;
236
+ var HEX_RADIX = 16;
237
+ var HEX_PAIR_LENGTH = 2;
238
+ var HEX_SHORTHAND_LENGTH = 3;
239
+ var HEX_FULL_LENGTH = 6;
240
+ var CHANNEL_OFFSET_RED = 0;
241
+ var CHANNEL_OFFSET_GREEN = 2;
242
+ var CHANNEL_OFFSET_BLUE = 4;
243
+ function normalizeHexDigits(hex) {
244
+ const clean = hex.trim().replace("#", "").toLowerCase();
245
+ if (clean.length === HEX_SHORTHAND_LENGTH)
246
+ return `${clean[0] ?? ""}${clean[0] ?? ""}${clean[1] ?? ""}${clean[1] ?? ""}${clean[2] ?? ""}${clean[2] ?? ""}`;
247
+ return clean;
248
+ }
249
+ function parseChannel(digits, offset) {
250
+ const pair = digits.slice(offset, offset + HEX_PAIR_LENGTH);
251
+ return parseInt(pair, HEX_RADIX) / SRGB_CHANNEL_MAX;
252
+ }
253
+ function linearizeChannel(channel) {
254
+ if (channel <= GAMMA_LINEAR_THRESHOLD) return channel / GAMMA_LINEAR_DIVISOR;
255
+ return Math.pow((channel + GAMMA_OFFSET) / GAMMA_DIVISOR, GAMMA_EXPONENT);
256
+ }
257
+ function relativeLuminance(hex) {
258
+ const digits = normalizeHexDigits(hex);
259
+ if (digits.length !== HEX_FULL_LENGTH || !/^[0-9a-f]{6}$/.test(digits))
260
+ throw new Error(`relativeLuminance: not a hex colour: ${hex}`);
261
+ const red = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_RED));
262
+ const green = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_GREEN));
263
+ const blue = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_BLUE));
264
+ return LUMA_COEFFICIENT_RED * red + LUMA_COEFFICIENT_GREEN * green + LUMA_COEFFICIENT_BLUE * blue;
265
+ }
266
+ function contrastRatio(foreground, background) {
267
+ const first = relativeLuminance(foreground);
268
+ const second = relativeLuminance(background);
269
+ const lighter = Math.max(first, second);
270
+ const darker = Math.min(first, second);
271
+ return (lighter + CONTRAST_FLARE) / (darker + CONTRAST_FLARE);
272
+ }
273
+ function meetsContrast(foreground, background, requiredRatio) {
274
+ return contrastRatio(foreground, background) >= requiredRatio;
275
+ }
276
+
277
+ // src/ThemeMode.ts
278
+ var ThemeMode = {
279
+ Light: "light",
280
+ Dark: "dark"
281
+ };
282
+
283
+ // src/resolveBackdrop.ts
284
+ var SAFE_TEXT_RATIO = AA_NORMAL_TEXT_RATIO + AA_CONTRAST_MARGIN;
285
+ var LEDGER_RULE_SPACING_PX = 32;
286
+ var LEDGER_RULE_WIDTH_PX = 1;
287
+ var PAPER_GRAIN_SIZE_PX = 6;
288
+ var BAND_OVERLAP_COMPACT_PX = 56;
289
+ var BAND_OVERLAP_WIDE_PX = 64;
290
+ function readable(candidates, background, fallback) {
291
+ return candidates.find((ink) => contrastRatio(ink, background) >= SAFE_TEXT_RATIO) ?? fallback;
292
+ }
293
+ function strongest(candidates, background) {
294
+ const ranked = [...candidates].sort((a, b) => contrastRatio(b, background) - contrastRatio(a, background));
295
+ return ranked[0] ?? background;
296
+ }
297
+ function ledgerFill(theme) {
298
+ const ruleStart = LEDGER_RULE_SPACING_PX - LEDGER_RULE_WIDTH_PX;
299
+ const rule = theme.colors.divider;
300
+ return {
301
+ color: theme.colors.background,
302
+ image: `linear-gradient(to bottom, transparent ${ruleStart}px, ${rule} ${ruleStart}px)`,
303
+ imageSize: `100% ${LEDGER_RULE_SPACING_PX}px`
304
+ };
305
+ }
306
+ function paperFill(theme) {
307
+ return {
308
+ color: theme.colors.surface,
309
+ image: `radial-gradient(${theme.colors.border} 0.5px, transparent 0.5px)`,
310
+ imageSize: `${PAPER_GRAIN_SIZE_PX}px ${PAPER_GRAIN_SIZE_PX}px`
311
+ };
312
+ }
313
+ function flatFill(color) {
314
+ return { color, image: null, imageSize: null };
315
+ }
316
+ function tintShade(theme) {
317
+ return theme.mode === ThemeMode.Dark ? theme.palette.primary["900"] : theme.palette.primary["50"];
318
+ }
319
+ function fillFor(theme, preset) {
320
+ if (preset === BackdropPreset.Ledger) return ledgerFill(theme);
321
+ if (preset === BackdropPreset.Paper) return paperFill(theme);
322
+ if (preset === BackdropPreset.Horizon) return flatFill(theme.colors.surface);
323
+ if (preset === BackdropPreset.Tint) return flatFill(tintShade(theme));
324
+ return flatFill(theme.colors.background);
325
+ }
326
+ function bandFor(theme) {
327
+ const color = theme.palette.primary["500"];
328
+ const { primary } = theme.palette;
329
+ const text = strongest([theme.colors.surfaceElevated, theme.colors.background, theme.colors.text, primary["50"]], color);
330
+ return {
331
+ color,
332
+ text,
333
+ textSecondary: readable([primary["100"], primary["200"], primary["800"], primary["900"]], color, text),
334
+ overlap: { compact: BAND_OVERLAP_COMPACT_PX, wide: BAND_OVERLAP_WIDE_PX }
335
+ };
336
+ }
337
+ function safeFill(theme, preset) {
338
+ const fill = fillFor(theme, preset);
339
+ const textFits = contrastRatio(theme.colors.text, fill.color) >= SAFE_TEXT_RATIO;
340
+ return textFits ? fill : flatFill(theme.colors.background);
341
+ }
342
+ function resolveBackdrop(theme, preset = BackdropPreset.Plain) {
343
+ const fill = safeFill(theme, preset);
344
+ return {
345
+ preset,
346
+ ...fill,
347
+ text: theme.colors.text,
348
+ textSecondary: readable([theme.colors.textSecondary], fill.color, theme.colors.text),
349
+ band: preset === BackdropPreset.Horizon ? bandFor(theme) : null,
350
+ liftSurfaces: preset === BackdropPreset.Tint || preset === BackdropPreset.Horizon
351
+ };
352
+ }
353
+
212
354
  // src/resolveTheme.ts
213
355
  var DEFAULT_FONT_FAMILY = "System";
214
356
  var DEFAULT_HEADING_SCALE = 1;
215
357
  function resolveTheme(config, mode) {
216
358
  const effectiveConfig = config ?? DEFAULT_THEME_CONFIG;
217
359
  const paletteResult = generateThemePalette(effectiveConfig);
218
- return {
360
+ const theme = {
219
361
  colors: effectiveConfig[mode],
220
362
  palette: {
221
363
  primary: paletteResult.primary,
@@ -233,14 +375,9 @@ function resolveTheme(config, mode) {
233
375
  faviconUrl: effectiveConfig.branding.faviconContentId
234
376
  }
235
377
  };
378
+ return { ...theme, backdrop: resolveBackdrop(theme, effectiveConfig.backdrop) };
236
379
  }
237
380
  var ThemeContext = react.createContext(null);
238
-
239
- // src/ThemeMode.ts
240
- var ThemeMode = {
241
- Light: "light",
242
- Dark: "dark"
243
- };
244
381
  var MEDIA_QUERY = "(prefers-color-scheme: dark)";
245
382
  var DEFAULT_DARK_MODE_STORAGE_KEY = "DARK_MODE_PREFERENCE";
246
383
  function getMatchMedia() {
@@ -321,9 +458,11 @@ var ThemeProvider = ({
321
458
  tenantThemeConfig,
322
459
  defaultThemeConfig = DEFAULT_THEME_CONFIG,
323
460
  storageKey,
461
+ forcedMode,
324
462
  children
325
463
  }) => {
326
- const { preference, effectiveMode, setPreference } = useDarkMode(storageKey);
464
+ const { preference, effectiveMode: preferredMode, setPreference } = useDarkMode(storageKey);
465
+ const effectiveMode = forcedMode ?? preferredMode;
327
466
  const [config, setConfig] = react.useState(tenantThemeConfig ?? null);
328
467
  react.useEffect(() => {
329
468
  setConfig(tenantThemeConfig ?? null);
@@ -396,62 +535,6 @@ function fromDesignTokens(tokens) {
396
535
  return config;
397
536
  }
398
537
 
399
- // src/contrast.ts
400
- var AA_NORMAL_TEXT_RATIO = 4.5;
401
- var AA_LARGE_TEXT_RATIO = 3;
402
- var AA_NON_TEXT_RATIO = 3;
403
- var AA_CONTRAST_MARGIN = 0.25;
404
- var SRGB_CHANNEL_MAX = 255;
405
- var GAMMA_LINEAR_THRESHOLD = 0.03928;
406
- var GAMMA_LINEAR_DIVISOR = 12.92;
407
- var GAMMA_OFFSET = 0.055;
408
- var GAMMA_DIVISOR = 1.055;
409
- var GAMMA_EXPONENT = 2.4;
410
- var LUMA_COEFFICIENT_RED = 0.2126;
411
- var LUMA_COEFFICIENT_GREEN = 0.7152;
412
- var LUMA_COEFFICIENT_BLUE = 0.0722;
413
- var CONTRAST_FLARE = 0.05;
414
- var HEX_RADIX = 16;
415
- var HEX_PAIR_LENGTH = 2;
416
- var HEX_SHORTHAND_LENGTH = 3;
417
- var HEX_FULL_LENGTH = 6;
418
- var CHANNEL_OFFSET_RED = 0;
419
- var CHANNEL_OFFSET_GREEN = 2;
420
- var CHANNEL_OFFSET_BLUE = 4;
421
- function normalizeHexDigits(hex) {
422
- const clean = hex.trim().replace("#", "").toLowerCase();
423
- if (clean.length === HEX_SHORTHAND_LENGTH)
424
- return `${clean[0] ?? ""}${clean[0] ?? ""}${clean[1] ?? ""}${clean[1] ?? ""}${clean[2] ?? ""}${clean[2] ?? ""}`;
425
- return clean;
426
- }
427
- function parseChannel(digits, offset) {
428
- const pair = digits.slice(offset, offset + HEX_PAIR_LENGTH);
429
- return parseInt(pair, HEX_RADIX) / SRGB_CHANNEL_MAX;
430
- }
431
- function linearizeChannel(channel) {
432
- if (channel <= GAMMA_LINEAR_THRESHOLD) return channel / GAMMA_LINEAR_DIVISOR;
433
- return Math.pow((channel + GAMMA_OFFSET) / GAMMA_DIVISOR, GAMMA_EXPONENT);
434
- }
435
- function relativeLuminance(hex) {
436
- const digits = normalizeHexDigits(hex);
437
- if (digits.length !== HEX_FULL_LENGTH || !/^[0-9a-f]{6}$/.test(digits))
438
- throw new Error(`relativeLuminance: not a hex colour: ${hex}`);
439
- const red = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_RED));
440
- const green = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_GREEN));
441
- const blue = linearizeChannel(parseChannel(digits, CHANNEL_OFFSET_BLUE));
442
- return LUMA_COEFFICIENT_RED * red + LUMA_COEFFICIENT_GREEN * green + LUMA_COEFFICIENT_BLUE * blue;
443
- }
444
- function contrastRatio(foreground, background) {
445
- const first = relativeLuminance(foreground);
446
- const second = relativeLuminance(background);
447
- const lighter = Math.max(first, second);
448
- const darker = Math.min(first, second);
449
- return (lighter + CONTRAST_FLARE) / (darker + CONTRAST_FLARE);
450
- }
451
- function meetsContrast(foreground, background, requiredRatio) {
452
- return contrastRatio(foreground, background) >= requiredRatio;
453
- }
454
-
455
538
  // src/badgeColors.ts
456
539
  var BADGE_TEXT_REQUIRED_RATIO = AA_NORMAL_TEXT_RATIO + AA_CONTRAST_MARGIN;
457
540
  var BADGE_TINT_SHADE = "100";
@@ -470,6 +553,7 @@ exports.AA_LARGE_TEXT_RATIO = AA_LARGE_TEXT_RATIO;
470
553
  exports.AA_NON_TEXT_RATIO = AA_NON_TEXT_RATIO;
471
554
  exports.AA_NORMAL_TEXT_RATIO = AA_NORMAL_TEXT_RATIO;
472
555
  exports.BADGE_TINT_SHADE = BADGE_TINT_SHADE;
556
+ exports.BackdropPreset = BackdropPreset;
473
557
  exports.DEFAULT_DARK_MODE_STORAGE_KEY = DEFAULT_DARK_MODE_STORAGE_KEY;
474
558
  exports.DEFAULT_THEME_CONFIG = DEFAULT_THEME_CONFIG;
475
559
  exports.DarkModePreference = DarkModePreference;
@@ -488,6 +572,7 @@ exports.isValidHex = isValidHex;
488
572
  exports.lighten = lighten;
489
573
  exports.meetsContrast = meetsContrast;
490
574
  exports.relativeLuminance = relativeLuminance;
575
+ exports.resolveBackdrop = resolveBackdrop;
491
576
  exports.resolveTheme = resolveTheme;
492
577
  exports.useDarkMode = useDarkMode;
493
578
  exports.useTheme = useTheme;