@salesforce/ui-theme-manager 11.46.0

package/dist/protocol/brandTypes.d.cts

@@ -0,0 +1,198 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Brand data model types for Salesforce CMS Brand tokens.
+ *
+ * Evolution policy: Add new fields as optional. Never rename or remove fields.
+ * Never change field semantics. Brand tokens are portable across hosts.
+ */
+/**
+ * A brand reference string in the form "{!$brand.path.to.token}".
+ */
+export type BrandRef = string;
+/**
+ * A value that can be either a literal or a reference to another brand token.
+ */
+export type Ref<T> = T | BrandRef;
+/**
+ * A dimension with a unit and value (e.g., rem, px).
+ */
+export interface BrandDimension {
+    unit: string;
+    value: number;
+}
+/**
+ * A box model with all four edges.
+ */
+export interface BrandBox {
+    top: BrandDimension;
+    bottom: BrandDimension;
+    left: BrandDimension;
+    right: BrandDimension;
+}
+/**
+ * Letter spacing can be a dimension or the literal string "normal".
+ */
+export type BrandLetterSpacingValue = BrandDimension | "normal";
+/**
+ * A font family definition with name, category, and optional fallbacks.
+ */
+export interface BrandFontFamily {
+    name: string;
+    category: string;
+    fallbacks?: string[];
+}
+/**
+ * A typography entry with font family, size, weight, spacing, line height, and transform.
+ */
+export interface BrandTypographyEntry {
+    fontFamily: Ref<string>;
+    fontSize: Ref<BrandDimension>;
+    fontWeight: Ref<number>;
+    letterSpacing: BrandLetterSpacingValue;
+    lineHeight: number;
+    textTransform: string;
+}
+/**
+ * Button color group with background, border, and text colors.
+ * Tertiary buttons may omit backgroundColor, backgroundHoverColor, borderColor, borderHoverColor.
+ */
+export interface BrandButtonColorGroup {
+    backgroundColor?: Ref<string>;
+    backgroundHoverColor?: Ref<string>;
+    borderColor?: Ref<string>;
+    borderHoverColor?: Ref<string>;
+    textColor: Ref<string>;
+    textHoverColor: Ref<string>;
+}
+/**
+ * Button style definition with namespaced Lightning keys.
+ */
+export interface BrandButtonStyle {
+    "lightning:borderRadius": Ref<BrandDimension>;
+    "lightning:borderWidth": Ref<BrandDimension>;
+    "lightning:buttonColorGroup": BrandButtonColorGroup;
+    "lightning:padding": BrandBox;
+    "lightning:typography": Ref<BrandTypographyEntry>;
+}
+/**
+ * A brand logo asset. The `url` is a resolved, directly-loadable image URL;
+ * `source` carries the CMS content reference it was resolved from.
+ */
+export interface BrandLogo {
+    url: string;
+    altText?: string;
+    overrideAltText?: boolean;
+    source?: {
+        mimeType?: string;
+        size?: number;
+        type?: string;
+        ref?: {
+            contentKey?: string;
+        };
+    };
+}
+/**
+ * Root brand content body containing all tokens.
+ */
+export interface BrandContentBody {
+    colorScheme: Record<string, string>;
+    fontFamily: Record<string, BrandFontFamily>;
+    fontSize: Record<string, BrandDimension>;
+    fontWeight: Record<string, number>;
+    borderRadius: Record<string, BrandDimension>;
+    borderWeight: Record<string, BrandDimension>;
+    spacing: Record<string, BrandBox>;
+    letterSpacing: Record<string, BrandLetterSpacingValue>;
+    baseFontFamily: BrandRef;
+    baseFontSize: BrandDimension;
+    typography: {
+        heading: Record<string, BrandTypographyEntry>;
+        paragraph: Record<string, BrandTypographyEntry>;
+        button: Record<string, BrandTypographyEntry>;
+        label: Record<string, BrandTypographyEntry>;
+        input: Record<string, BrandTypographyEntry>;
+    };
+    buttonStyleGroup: {
+        primary: BrandButtonStyle;
+        secondary: BrandButtonStyle;
+        tertiary: BrandButtonStyle;
+    };
+    /** Optional brand logo asset. Absent when the brand defines no logo. */
+    logo?: BrandLogo;
+    "lightning:dataProviders"?: unknown[];
+    "sfdc_cms:title"?: string;
+    "sfdc_cms:einsteinBrandProperties"?: {
+        personality?: {
+            defaultPersonality?: string;
+        };
+    };
+    "sfdc_cms:variants"?: unknown[];
+}
+/**
+ * The complete Brand model.
+ */
+export type Brand = BrandContentBody;
+/**
+ * Metadata-like summary for gallery display or selection lists.
+ */
+export interface BrandSummary {
+    title: string;
+    managedContentId?: string;
+    managedContentKey?: string;
+    contentUrl?: string;
+}
+/**
+ * Extracts the brand title from the CMS metadata.
+ */
+export declare function getBrandTitle(brand: Brand): string;
+/**
+ * Returns the brand's logo URL, or undefined when the brand defines no logo.
+ */
+export declare function getBrandLogoUrl(brand: Brand): string | undefined;
+/**
+ * Returns the brand logo's alt text, falling back to the brand title.
+ */
+export declare function getBrandLogoAltText(brand: Brand): string;
+/**
+ * CMS delivery envelope for brand content.
+ * The outer wrapper returned by CMS delivery APIs.
+ */
+export interface BrandEnvelope {
+    managedContentId?: string;
+    title?: string;
+    contentKey?: string;
+    contentType?: {
+        fullyQualifiedName?: string;
+    };
+    language?: string;
+    publishedDate?: string;
+    resourceUrl?: string;
+    unauthenticatedUrl?: string;
+    urlName?: string;
+    channelSummary?: {
+        domainUrl?: string;
+        id?: string;
+        name?: string;
+        resourceUrl?: string;
+        type?: string;
+    };
+    contentBody: BrandContentBody;
+}
+/**
+ * Unwraps a CMS delivery envelope to extract the Brand content body.
+ *
+ * This function is idempotent:
+ * - If the input is an envelope (has `contentBody`), returns the inner `contentBody`.
+ * - If the input is already an unwrapped Brand (has `colorScheme`), returns it as-is.
+ * - Throws an error for null, undefined, or non-object inputs.
+ *
+ * @param raw - The raw data from CMS (may be envelope or already unwrapped)
+ * @returns The unwrapped Brand (BrandContentBody)
+ * @throws Error if input is null, undefined, or not an object
+ */
+export declare function unwrapBrandEnvelope(raw: unknown): Brand;
+//# sourceMappingURL=brandTypes.d.ts.map

package/dist/protocol/brandTypes.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * Brand data model types for Salesforce CMS Brand tokens.
+ *
+ * Evolution policy: Add new fields as optional. Never rename or remove fields.
+ * Never change field semantics. Brand tokens are portable across hosts.
+ */
+/**
+ * A brand reference string in the form "{!$brand.path.to.token}".
+ */
+export type BrandRef = string;
+/**
+ * A value that can be either a literal or a reference to another brand token.
+ */
+export type Ref<T> = T | BrandRef;
+/**
+ * A dimension with a unit and value (e.g., rem, px).
+ */
+export interface BrandDimension {
+    unit: string;
+    value: number;
+}
+/**
+ * A box model with all four edges.
+ */
+export interface BrandBox {
+    top: BrandDimension;
+    bottom: BrandDimension;
+    left: BrandDimension;
+    right: BrandDimension;
+}
+/**
+ * Letter spacing can be a dimension or the literal string "normal".
+ */
+export type BrandLetterSpacingValue = BrandDimension | "normal";
+/**
+ * A font family definition with name, category, and optional fallbacks.
+ */
+export interface BrandFontFamily {
+    name: string;
+    category: string;
+    fallbacks?: string[];
+}
+/**
+ * A typography entry with font family, size, weight, spacing, line height, and transform.
+ */
+export interface BrandTypographyEntry {
+    fontFamily: Ref<string>;
+    fontSize: Ref<BrandDimension>;
+    fontWeight: Ref<number>;
+    letterSpacing: BrandLetterSpacingValue;
+    lineHeight: number;
+    textTransform: string;
+}
+/**
+ * Button color group with background, border, and text colors.
+ * Tertiary buttons may omit backgroundColor, backgroundHoverColor, borderColor, borderHoverColor.
+ */
+export interface BrandButtonColorGroup {
+    backgroundColor?: Ref<string>;
+    backgroundHoverColor?: Ref<string>;
+    borderColor?: Ref<string>;
+    borderHoverColor?: Ref<string>;
+    textColor: Ref<string>;
+    textHoverColor: Ref<string>;
+}
+/**
+ * Button style definition with namespaced Lightning keys.
+ */
+export interface BrandButtonStyle {
+    "lightning:borderRadius": Ref<BrandDimension>;
+    "lightning:borderWidth": Ref<BrandDimension>;
+    "lightning:buttonColorGroup": BrandButtonColorGroup;
+    "lightning:padding": BrandBox;
+    "lightning:typography": Ref<BrandTypographyEntry>;
+}
+/**
+ * A brand logo asset. The `url` is a resolved, directly-loadable image URL;
+ * `source` carries the CMS content reference it was resolved from.
+ */
+export interface BrandLogo {
+    url: string;
+    altText?: string;
+    overrideAltText?: boolean;
+    source?: {
+        mimeType?: string;
+        size?: number;
+        type?: string;
+        ref?: {
+            contentKey?: string;
+        };
+    };
+}
+/**
+ * Root brand content body containing all tokens.
+ */
+export interface BrandContentBody {
+    colorScheme: Record<string, string>;
+    fontFamily: Record<string, BrandFontFamily>;
+    fontSize: Record<string, BrandDimension>;
+    fontWeight: Record<string, number>;
+    borderRadius: Record<string, BrandDimension>;
+    borderWeight: Record<string, BrandDimension>;
+    spacing: Record<string, BrandBox>;
+    letterSpacing: Record<string, BrandLetterSpacingValue>;
+    baseFontFamily: BrandRef;
+    baseFontSize: BrandDimension;
+    typography: {
+        heading: Record<string, BrandTypographyEntry>;
+        paragraph: Record<string, BrandTypographyEntry>;
+        button: Record<string, BrandTypographyEntry>;
+        label: Record<string, BrandTypographyEntry>;
+        input: Record<string, BrandTypographyEntry>;
+    };
+    buttonStyleGroup: {
+        primary: BrandButtonStyle;
+        secondary: BrandButtonStyle;
+        tertiary: BrandButtonStyle;
+    };
+    /** Optional brand logo asset. Absent when the brand defines no logo. */
+    logo?: BrandLogo;
+    "lightning:dataProviders"?: unknown[];
+    "sfdc_cms:title"?: string;
+    "sfdc_cms:einsteinBrandProperties"?: {
+        personality?: {
+            defaultPersonality?: string;
+        };
+    };
+    "sfdc_cms:variants"?: unknown[];
+}
+/**
+ * The complete Brand model.
+ */
+export type Brand = BrandContentBody;
+/**
+ * Metadata-like summary for gallery display or selection lists.
+ */
+export interface BrandSummary {
+    title: string;
+    managedContentId?: string;
+    managedContentKey?: string;
+    contentUrl?: string;
+}
+/**
+ * Extracts the brand title from the CMS metadata.
+ */
+export declare function getBrandTitle(brand: Brand): string;
+/**
+ * Returns the brand's logo URL, or undefined when the brand defines no logo.
+ */
+export declare function getBrandLogoUrl(brand: Brand): string | undefined;
+/**
+ * Returns the brand logo's alt text, falling back to the brand title.
+ */
+export declare function getBrandLogoAltText(brand: Brand): string;
+/**
+ * CMS delivery envelope for brand content.
+ * The outer wrapper returned by CMS delivery APIs.
+ */
+export interface BrandEnvelope {
+    managedContentId?: string;
+    title?: string;
+    contentKey?: string;
+    contentType?: {
+        fullyQualifiedName?: string;
+    };
+    language?: string;
+    publishedDate?: string;
+    resourceUrl?: string;
+    unauthenticatedUrl?: string;
+    urlName?: string;
+    channelSummary?: {
+        domainUrl?: string;
+        id?: string;
+        name?: string;
+        resourceUrl?: string;
+        type?: string;
+    };
+    contentBody: BrandContentBody;
+}
+/**
+ * Unwraps a CMS delivery envelope to extract the Brand content body.
+ *
+ * This function is idempotent:
+ * - If the input is an envelope (has `contentBody`), returns the inner `contentBody`.
+ * - If the input is already an unwrapped Brand (has `colorScheme`), returns it as-is.
+ * - Throws an error for null, undefined, or non-object inputs.
+ *
+ * @param raw - The raw data from CMS (may be envelope or already unwrapped)
+ * @returns The unwrapped Brand (BrandContentBody)
+ * @throws Error if input is null, undefined, or not an object
+ */
+export declare function unwrapBrandEnvelope(raw: unknown): Brand;
+//# sourceMappingURL=brandTypes.d.ts.map

package/dist/protocol/brandTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brandTypes.d.ts","sourceRoot":"","sources":["../../src/protocol/brandTypes.ts"],"names":[],"mappings":"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"}

package/dist/protocol/brandTypes.js

@@ -0,0 +1,30 @@
+function getBrandTitle(brand) {
+  return brand["sfdc_cms:title"] ?? "Untitled Brand";
+}
+function getBrandLogoUrl(brand) {
+  const url = brand.logo?.url;
+  return typeof url === "string" && url.length > 0 ? url : void 0;
+}
+function getBrandLogoAltText(brand) {
+  const alt = brand.logo?.altText;
+  return typeof alt === "string" && alt.length > 0 ? alt : getBrandTitle(brand);
+}
+function unwrapBrandEnvelope(raw) {
+  if (raw === null || raw === void 0) {
+    throw new Error("unwrapBrandEnvelope: input is null or undefined");
+  }
+  if (typeof raw !== "object") {
+    throw new Error(`unwrapBrandEnvelope: input is not an object (got ${typeof raw})`);
+  }
+  const obj = raw;
+  if ("contentBody" in obj && obj.contentBody !== null && typeof obj.contentBody === "object") {
+    return obj.contentBody;
+  }
+  return raw;
+}
+export {
+  getBrandLogoAltText,
+  getBrandLogoUrl,
+  getBrandTitle,
+  unwrapBrandEnvelope
+};

package/dist/protocol/deriveColors.cjs

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const chroma = require("chroma-js");
+function darkenColor(sourceColor) {
+  if (!sourceColor) return void 0;
+  try {
+    if (!chroma.valid(sourceColor)) return void 0;
+    return chroma(sourceColor).darken(0.5).hex();
+  } catch {
+    return void 0;
+  }
+}
+function derivePrimaryAccentDerived(primaryAccent) {
+  return darkenColor(primaryAccent);
+}
+function derivePrimaryAccentContrastDerived(primaryAccentContrast, primaryAccentDerived) {
+  if (!primaryAccentContrast || !primaryAccentDerived) return void 0;
+  try {
+    if (!chroma.valid(primaryAccentContrast) || !chroma.valid(primaryAccentDerived)) {
+      return void 0;
+    }
+    const darkened = chroma(primaryAccentContrast).darken(0.5).hex();
+    const contrastRatio = chroma.contrast(darkened, primaryAccentDerived);
+    if (contrastRatio < 4.5) {
+      const isLight = chroma(primaryAccentDerived).luminance() > 0.5;
+      return isLight ? "#000000" : "#FFFFFF";
+    }
+    return darkened;
+  } catch {
+    return void 0;
+  }
+}
+function deriveBrandColors(colors) {
+  const primaryAccentDerived = derivePrimaryAccentDerived(colors.primaryAccent);
+  const primaryAccentContrastDerived = derivePrimaryAccentContrastDerived(
+    colors.primaryAccentContrast,
+    primaryAccentDerived
+  );
+  return {
+    primaryAccentDerived,
+    primaryAccentContrastDerived
+  };
+}
+function updateDerivedColors(brand) {
+  if (!brand.colorScheme || typeof brand.colorScheme !== "object") {
+    return;
+  }
+  const colorScheme = brand.colorScheme;
+  const primaryAccent = typeof colorScheme.primaryAccent === "string" ? colorScheme.primaryAccent : void 0;
+  const primaryAccentContrast = typeof colorScheme.primaryAccentContrast === "string" ? colorScheme.primaryAccentContrast : void 0;
+  const derived = deriveBrandColors({ primaryAccent, primaryAccentContrast });
+  if (derived.primaryAccentDerived !== void 0) {
+    colorScheme.primaryAccentDerived = derived.primaryAccentDerived;
+  } else {
+    delete colorScheme.primaryAccentDerived;
+  }
+  if (derived.primaryAccentContrastDerived !== void 0) {
+    colorScheme.primaryAccentContrastDerived = derived.primaryAccentContrastDerived;
+  } else {
+    delete colorScheme.primaryAccentContrastDerived;
+  }
+}
+exports.darkenColor = darkenColor;
+exports.deriveBrandColors = deriveBrandColors;
+exports.derivePrimaryAccentContrastDerived = derivePrimaryAccentContrastDerived;
+exports.derivePrimaryAccentDerived = derivePrimaryAccentDerived;
+exports.updateDerivedColors = updateDerivedColors;

package/dist/protocol/deriveColors.d.cts

@@ -0,0 +1,39 @@
+import { Brand } from './brandTypes.cjs';
+/**
+ * Darkens a color by 0.5 in LAB space, matching Salesforce Core's algorithm.
+ * Core uses: `chroma(hex).darken(0.5).hex()`
+ * This operates in LAB color space: L_new = L - (18 * 0.5) = L - 9
+ *
+ * @param sourceColor - 6-digit or 8-digit hex color (with or without #)
+ * @returns Lowercase 6-digit hex (e.g., "#0060ba"), or undefined if input is invalid
+ */
+export declare function darkenColor(sourceColor: string | undefined): string | undefined;
+/** Derives primaryAccentDerived from primaryAccent (darkens by 0.5 in LAB space). */
+export declare function derivePrimaryAccentDerived(primaryAccent: string | undefined): string | undefined;
+/**
+ * Derives primaryAccentContrastDerived from primaryAccentContrast.
+ * Matches Core's algorithm exactly: darken(0.5), then contrast check with fallback.
+ * Core's getValidContrast: if contrast(darkened, bg) < 4.5, return '#000000' (light bg) or '#FFFFFF' (dark bg).
+ */
+export declare function derivePrimaryAccentContrastDerived(primaryAccentContrast: string | undefined, primaryAccentDerived: string | undefined): string | undefined;
+/** Derives both brand colors (primaryAccentDerived first, then primaryAccentContrastDerived). */
+export declare function deriveBrandColors(colors: {
+    primaryAccent?: string;
+    primaryAccentContrast?: string;
+}): {
+    primaryAccentDerived: string | undefined;
+    primaryAccentContrastDerived: string | undefined;
+};
+/**
+ * Recomputes both derived accent colors from a brand's source colors and writes them
+ * back into `brand.colorScheme` in place. Matches Core's recompute-on-change behavior:
+ * a derived field is written when its source is valid and DELETED when the source is
+ * missing or invalid. No-op when the brand has no `colorScheme`.
+ *
+ * Hosts should call this on initial brand load and whenever `primaryAccent` or
+ * `primaryAccentContrast` is edited.
+ *
+ * @param brand - The brand model to mutate in place
+ */
+export declare function updateDerivedColors(brand: Brand): void;
+//# sourceMappingURL=deriveColors.d.ts.map

package/dist/protocol/deriveColors.d.ts

@@ -0,0 +1,39 @@
+import { Brand } from './brandTypes.js';
+/**
+ * Darkens a color by 0.5 in LAB space, matching Salesforce Core's algorithm.
+ * Core uses: `chroma(hex).darken(0.5).hex()`
+ * This operates in LAB color space: L_new = L - (18 * 0.5) = L - 9
+ *
+ * @param sourceColor - 6-digit or 8-digit hex color (with or without #)
+ * @returns Lowercase 6-digit hex (e.g., "#0060ba"), or undefined if input is invalid
+ */
+export declare function darkenColor(sourceColor: string | undefined): string | undefined;
+/** Derives primaryAccentDerived from primaryAccent (darkens by 0.5 in LAB space). */
+export declare function derivePrimaryAccentDerived(primaryAccent: string | undefined): string | undefined;
+/**
+ * Derives primaryAccentContrastDerived from primaryAccentContrast.
+ * Matches Core's algorithm exactly: darken(0.5), then contrast check with fallback.
+ * Core's getValidContrast: if contrast(darkened, bg) < 4.5, return '#000000' (light bg) or '#FFFFFF' (dark bg).
+ */
+export declare function derivePrimaryAccentContrastDerived(primaryAccentContrast: string | undefined, primaryAccentDerived: string | undefined): string | undefined;
+/** Derives both brand colors (primaryAccentDerived first, then primaryAccentContrastDerived). */
+export declare function deriveBrandColors(colors: {
+    primaryAccent?: string;
+    primaryAccentContrast?: string;
+}): {
+    primaryAccentDerived: string | undefined;
+    primaryAccentContrastDerived: string | undefined;
+};
+/**
+ * Recomputes both derived accent colors from a brand's source colors and writes them
+ * back into `brand.colorScheme` in place. Matches Core's recompute-on-change behavior:
+ * a derived field is written when its source is valid and DELETED when the source is
+ * missing or invalid. No-op when the brand has no `colorScheme`.
+ *
+ * Hosts should call this on initial brand load and whenever `primaryAccent` or
+ * `primaryAccentContrast` is edited.
+ *
+ * @param brand - The brand model to mutate in place
+ */
+export declare function updateDerivedColors(brand: Brand): void;
+//# sourceMappingURL=deriveColors.d.ts.map

package/dist/protocol/deriveColors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deriveColors.d.ts","sourceRoot":"","sources":["../../src/protocol/deriveColors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4BH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAa/E;AAED,qFAAqF;AACrF,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEhG;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CACjD,qBAAqB,EAAE,MAAM,GAAG,SAAS,EACzC,oBAAoB,EAAE,MAAM,GAAG,SAAS,GACtC,MAAM,GAAG,SAAS,CA0BpB;AAED,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B,GAAG;IACH,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,4BAA4B,EAAE,MAAM,GAAG,SAAS,CAAC;CACjD,CAcA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CA8BtD"}

package/dist/protocol/deriveColors.js

@@ -0,0 +1,67 @@
+import chroma from "chroma-js";
+function darkenColor(sourceColor) {
+  if (!sourceColor) return void 0;
+  try {
+    if (!chroma.valid(sourceColor)) return void 0;
+    return chroma(sourceColor).darken(0.5).hex();
+  } catch {
+    return void 0;
+  }
+}
+function derivePrimaryAccentDerived(primaryAccent) {
+  return darkenColor(primaryAccent);
+}
+function derivePrimaryAccentContrastDerived(primaryAccentContrast, primaryAccentDerived) {
+  if (!primaryAccentContrast || !primaryAccentDerived) return void 0;
+  try {
+    if (!chroma.valid(primaryAccentContrast) || !chroma.valid(primaryAccentDerived)) {
+      return void 0;
+    }
+    const darkened = chroma(primaryAccentContrast).darken(0.5).hex();
+    const contrastRatio = chroma.contrast(darkened, primaryAccentDerived);
+    if (contrastRatio < 4.5) {
+      const isLight = chroma(primaryAccentDerived).luminance() > 0.5;
+      return isLight ? "#000000" : "#FFFFFF";
+    }
+    return darkened;
+  } catch {
+    return void 0;
+  }
+}
+function deriveBrandColors(colors) {
+  const primaryAccentDerived = derivePrimaryAccentDerived(colors.primaryAccent);
+  const primaryAccentContrastDerived = derivePrimaryAccentContrastDerived(
+    colors.primaryAccentContrast,
+    primaryAccentDerived
+  );
+  return {
+    primaryAccentDerived,
+    primaryAccentContrastDerived
+  };
+}
+function updateDerivedColors(brand) {
+  if (!brand.colorScheme || typeof brand.colorScheme !== "object") {
+    return;
+  }
+  const colorScheme = brand.colorScheme;
+  const primaryAccent = typeof colorScheme.primaryAccent === "string" ? colorScheme.primaryAccent : void 0;
+  const primaryAccentContrast = typeof colorScheme.primaryAccentContrast === "string" ? colorScheme.primaryAccentContrast : void 0;
+  const derived = deriveBrandColors({ primaryAccent, primaryAccentContrast });
+  if (derived.primaryAccentDerived !== void 0) {
+    colorScheme.primaryAccentDerived = derived.primaryAccentDerived;
+  } else {
+    delete colorScheme.primaryAccentDerived;
+  }
+  if (derived.primaryAccentContrastDerived !== void 0) {
+    colorScheme.primaryAccentContrastDerived = derived.primaryAccentContrastDerived;
+  } else {
+    delete colorScheme.primaryAccentContrastDerived;
+  }
+}
+export {
+  darkenColor,
+  deriveBrandColors,
+  derivePrimaryAccentContrastDerived,
+  derivePrimaryAccentDerived,
+  updateDerivedColors
+};