@designcrowd/library.brand-page 6.0.13 → 6.0.14-5804-2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@designcrowd/library.brand-page",
   "description": "A collection of Maker/Designer applications",
-  "version": "6.0.13",
+  "version": "6.0.14-5804-2",
   "author": "Design.com Eng",
   "license": "UNLICENSED",
   "type": "module",

package/src/brand-page/components/button/Button.vue

@@ -12,6 +12,7 @@
           class="tw-no-underline"
           :to="{ name: routes.name, params: routes.routeParams }"
           :class="{ 'tw-w-full': isBrushStrokeIcon }"
+          @click="onPageLinkClick"
         >
           <div
             :title="viewModel.title"
@@ -101,6 +102,7 @@
 
 <script setup lang="ts">
 import { computed, ref } from 'vue';
+import { useRouter } from 'vue-router';
 import { HashRouteModal } from '@designcrowd/fe-shared-lib';
 import { isEmail, isTel, isURL } from '../../../utils/validator.util';
 import type { BrandPageContext } from '@brand-page/models';
@@ -231,6 +233,24 @@ const buttonStateClass = computed(() => ({
   'tw-w-full': isBrushStrokeIcon.value,
 }));
 
+const router = useRouter();
+
+const onPageLinkClick = (): void => {
+  // A page-link pointing to its own page (e.g. a "back to top" button) resolves
+  // to the current route. Vue Router dedupes that as a redundant navigation and
+  // never runs the global guard that scrolls to top, so trigger it explicitly.
+  if (!router) return;
+
+  const target = router.resolve({
+    name: routes.value.name,
+    params: routes.value.routeParams,
+  });
+
+  if (target.fullPath === router.currentRoute.value.fullPath) {
+    window.scrollTo(0, 0);
+  }
+};
+
 const onClick = (): void => {
   if (isModalUrl.value && isModalImageUrlValid.value) {
     isModalVisible.value = true;

package/src/brand-page/components/button/Button.vue.test.ts

@@ -0,0 +1,175 @@
+import { vi } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { createRouter, createMemoryHistory, RouterLink } from 'vue-router';
+import { createPinia, setActivePinia } from 'pinia';
+import Button from './Button.vue';
+import {
+  BRAND_PAGE_TYPES,
+  MEDIA_SIZES,
+  type BrandPageContext,
+} from '@brand-page/models';
+import type {
+  ButtonViewModel,
+  NavItemViewModel,
+} from '@brand-page/view-models';
+
+global.ResizeObserver = vi.fn().mockImplementation(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn(),
+}));
+
+const LINKED_PAGE_ID = 'page-2';
+const LINKED_PAGE_PATH = '/my-brand/second-page';
+const OTHER_PAGE_PATH = '/my-brand';
+
+const createTestNavItem = (): NavItemViewModel => ({
+  pageId: LINKED_PAGE_ID,
+  slug: 'my-brand',
+  displayName: 'Second Page',
+  routeName: 'page-route',
+  routeParams: { slug: 'my-brand', pageSlug: 'second-page' },
+  isRoot: false,
+  isHidden: false,
+  relativePath: 'second-page',
+  nestedNavItems: [],
+});
+
+const createTestBrandPageContext = (): BrandPageContext => ({
+  brandPageSlug: 'my-brand',
+  brandPageToken: '',
+  isMobile: false,
+  isPreview: true,
+  isProduction: false,
+  isServerRender: false,
+  options: {
+    mediaSizes: MEDIA_SIZES.sizeThumb,
+  },
+  isTemplate: false,
+  isDesignCom: false,
+  pageTitle: 'My Brand',
+  runtimeEnvironment: '',
+  stripePublishableKey: undefined,
+  customDomain: undefined,
+  brandPageType: BRAND_PAGE_TYPES.brandSite,
+  isBrandPage: false,
+  isBrandPageOrIsBrandContact: false,
+  isBrandSite: true,
+  isBrandContact: false,
+  pages: [],
+  isCapturingPreview: false,
+  recaptchaSiteKey: undefined,
+  nav: {
+    navItems: [createTestNavItem()],
+  },
+});
+
+const textStyle = {
+  fontSize: '1rem',
+  lineHeight: '1.5rem',
+  fontFamily: 'Lato',
+  textAlign: 'center',
+  overflowWrap: 'anywhere',
+  wordBreak: 'normal',
+};
+
+const createTestButtonViewModel = (
+  overrides: Partial<ButtonViewModel> = {},
+): ButtonViewModel =>
+  ({
+    id: 'button-1',
+    type: 'button',
+    role: 'banner-section',
+    title: 'Go to top',
+    url: '',
+    page: LINKED_PAGE_ID,
+    pageSlug: '',
+    buttonLinkType: 'page',
+    clickActionField: 'url',
+    iconUrl: '',
+    modalImageUrl: '',
+    titleStyle: textStyle,
+    styles: { selectedButtonStyleId: 'BUTTON_STYLE_1', style: {} },
+    onClicked: vi.fn(),
+    ...overrides,
+  }) as ButtonViewModel;
+
+const createTestRouter = () =>
+  createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      {
+        path: '/:slug/:pageSlug',
+        name: 'page-route',
+        component: { template: '<div />' },
+      },
+      {
+        path: '/:slug',
+        name: 'home-route',
+        component: { template: '<div />' },
+      },
+    ],
+  });
+
+const mountButton = async (currentPath: string) => {
+  const router = createTestRouter();
+
+  router.push(currentPath);
+  await router.isReady();
+
+  const wrapper = mount(Button, {
+    propsData: {
+      context: createTestBrandPageContext(),
+      viewModel: createTestButtonViewModel(),
+    },
+    global: {
+      plugins: [router],
+    },
+  });
+
+  return { wrapper, router };
+};
+
+describe('Button - page link "back to top" behaviour (BP-5834)', () => {
+  let scrollToSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    setActivePinia(createPinia());
+    scrollToSpy = vi
+      .spyOn(window, 'scrollTo')
+      .mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    scrollToSpy.mockRestore();
+  });
+
+  test('scrolls to top when the page-link target is the current route (duplicated navigation is skipped by the router)', async () => {
+    // A banner "back to top" button points to the page it lives on. Vue Router
+    // dedupes the navigation to the current location and never runs the guard
+    // that scrolls to top, so the button must scroll explicitly.
+    const { wrapper } = await mountButton(LINKED_PAGE_PATH);
+
+    const link = wrapper.findComponent(RouterLink);
+
+    expect(link.exists()).toBe(true);
+
+    await link.get('a').trigger('click');
+
+    expect(scrollToSpy).toHaveBeenCalledWith(0, 0);
+  });
+
+  test('does not scroll to top when the page-link target is a different page', async () => {
+    // A page-link to another page is a real navigation; the router guard owns
+    // scroll-to-top there, so the button must not scroll on its own.
+    const { wrapper } = await mountButton(OTHER_PAGE_PATH);
+
+    const link = wrapper.findComponent(RouterLink);
+
+    expect(link.exists()).toBe(true);
+
+    await link.get('a').trigger('click');
+
+    expect(scrollToSpy).not.toHaveBeenCalled();
+  });
+});

package/src/brand-page/components/contact-form/ContactForm.mixin.test.ts

@@ -0,0 +1,59 @@
+import ContactFormMixin from './ContactForm.mixin';
+
+// Calls the disclosureColor computed with a mocked `this`. It reads the sibling
+// computeds (hasCard/isDividedContent/hasBgColor) as plain properties, so they
+// can be supplied directly on the mock.
+const disclosureColor = (ctx: unknown): string | undefined =>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (ContactFormMixin as any).computed.disclosureColor.call(ctx);
+
+describe('ContactForm disclosureColor', () => {
+  test('brand.page / brand.contact anchor to the global button fill colour', () => {
+    const color = disclosureColor({
+      context: { isBrandSite: false },
+      hasCard: false,
+      isDividedContent: false,
+      hasBgColor: false,
+      viewModel: {
+        buttonStyles: { style: { backgroundColor: '#101010' } }, // dark fill
+        titleStyle: { color: '#ff0000' },
+      },
+    });
+
+    // Anchored to the dark button fill → a lighter colour, not the title red.
+    expect(color).toBeDefined();
+    expect(color).not.toBe('#ff0000');
+  });
+
+  test('brandSite card layout anchors to the card background', () => {
+    const color = disclosureColor({
+      context: { isBrandSite: true },
+      hasCard: true,
+      isDividedContent: false,
+      hasBgColor: true,
+      viewModel: {
+        cardStyle: { background: '#f5f0e6' }, // light beige card (background shorthand)
+        buttonStyles: { style: { backgroundColor: '#101010' } },
+        titleStyle: { color: '#ff0000' },
+      },
+    });
+
+    expect(color).toBeDefined();
+    expect(color).not.toBe('#ff0000');
+  });
+
+  test('falls back to the title colour when no solid background is available', () => {
+    const color = disclosureColor({
+      context: { isBrandSite: true },
+      hasCard: false,
+      isDividedContent: false,
+      hasBgColor: false,
+      viewModel: {
+        buttonStyles: { style: {} },
+        titleStyle: { color: '#123456' },
+      },
+    });
+
+    expect(color).toBe('#123456');
+  });
+});

package/src/brand-page/components/contact-form/ContactForm.mixin.ts

@@ -28,6 +28,8 @@ import {
 import {
   getRenderText,
   contentPaddingStyle as toContentPaddingStyle,
+  mutedTextForBackground,
+  backgroundColorFromStyle,
 } from '@brand-page/utils';
 import { hasRTEContent } from '@brand-page-maker/utils';
 import { useReCaptcha } from '../../composables/recaptcha.composable';
@@ -206,6 +208,28 @@ export default defineComponent({
 
       return {};
     },
+
+    disclosureColor(): string | undefined {
+      // Anchor the reCAPTCHA footnote to the surface it visually sits on, which
+      // differs by website type:
+      // - brandSite: the card style (card + divided layouts) or the section
+      //   background (other layouts).
+      // - brand.page / brand.contact: there's no section background, so the
+      //   coloured surface is the global button fill.
+      // Falls back to the title colour when there's no solid colour to anchor to.
+      const style = this.context.isBrandSite
+        ? this.hasCard || this.isDividedContent
+          ? this.viewModel.cardStyle
+          : this.hasBgColor
+            ? this.viewModel.backgroundStyle
+            : undefined
+        : this.viewModel.buttonStyles?.style;
+
+      return (
+        mutedTextForBackground(backgroundColorFromStyle(style)) ??
+        this.viewModel.titleStyle?.color
+      );
+    },
   },
   watch: {
     fields(fields: FormField[]) {

package/src/brand-page/components/contact-form/ContactForm.vue

@@ -98,6 +98,7 @@
           <p v-if="hasSubmitError" class="tw-text-center tw-mt-2 form-error">
             {{ submitError }}
           </p>
+          <RecaptchaDisclosure class="tw-pt-2" :color="disclosureColor" />
         </form>
         <div v-else :style="successMessageColorStyle">
           <TextWrapper
@@ -206,6 +207,7 @@
               >
                 {{ submitError }}
               </p>
+              <RecaptchaDisclosure class="tw-pt-2" :color="disclosureColor" />
             </form>
             <div v-else :style="successMessageColorStyle">
               <TextWrapper
@@ -311,6 +313,7 @@
             <p v-if="hasSubmitError" class="tw-text-center tw-mt-2 form-error">
               {{ submitError }}
             </p>
+            <RecaptchaDisclosure class="tw-pt-2" :color="disclosureColor" />
           </form>
           <Loader
             v-if="isSubmitting"
@@ -446,6 +449,10 @@
                   >
                     {{ submitError }}
                   </p>
+                  <RecaptchaDisclosure
+                    class="tw-pt-2"
+                    :color="disclosureColor"
+                  />
                 </form>
               </span>
               <div v-else :style="successMessageColorStyle">
@@ -469,6 +476,7 @@ import Collapsible from '../collapsible/Collapsible.vue';
 import MailingListMixin from './ContactForm.mixin.ts';
 import Media from '../media/Media.vue';
 import TextWrapper from '../text-wrapper/TextWrapper.vue';
+import RecaptchaDisclosure from '../recaptcha-disclosure/RecaptchaDisclosure.vue';
 
 export default {
   components: {
@@ -478,6 +486,7 @@ export default {
     Loader,
     Media,
     TextWrapper,
+    RecaptchaDisclosure,
   },
   mixins: [MailingListMixin],
   setup() {

package/src/brand-page/components/mailing-list/MailingList.mixin.ts

@@ -5,6 +5,8 @@ import brandPageClient from '../../clients/brand-page.client';
 import {
   getEmailValidationError,
   contentPaddingStyle as toContentPaddingStyle,
+  mutedTextForBackground,
+  backgroundColorFromStyle,
 } from '@brand-page/utils';
 import type { BrandPageContext } from '@brand-page/models';
 import {
@@ -88,6 +90,15 @@ export default defineComponent({
       return Boolean(this.submitError);
     },
 
+    disclosureColor(): string | undefined {
+      // The mailing-list box uses the button style as its background, so anchor
+      // the reCAPTCHA footnote to that. Falls back to the title colour when the
+      // background isn't a solid colour.
+      const bg = backgroundColorFromStyle(this.viewModel.styles?.style);
+
+      return mutedTextForBackground(bg) ?? this.viewModel.titleStyle?.color;
+    },
+
     buttonStyle(): BrandPageCssStyle {
       const buttonStyle = { ...this.viewModel.styles?.style };
 

package/src/brand-page/components/mailing-list/MailingList.vue

@@ -60,6 +60,7 @@
         <p v-if="hasSubmitError" class="tw-text-center tw-mt-2 form-error">
           {{ submitError }}
         </p>
+        <RecaptchaDisclosure class="tw-pt-2" :color="disclosureColor" />
       </form>
       <div v-else>
         <p class="tw-text-center tw-font-bold tw-my-0.5">
@@ -73,11 +74,13 @@
 import { TextInput } from '@designcrowd/fe-shared-lib';
 import MailingListMixin from './MailingList.mixin.ts';
 import TextWrapper from '../text-wrapper/TextWrapper.vue';
+import RecaptchaDisclosure from '../recaptcha-disclosure/RecaptchaDisclosure.vue';
 
 export default {
   components: {
     TextInput,
     TextWrapper,
+    RecaptchaDisclosure,
   },
   mixins: [MailingListMixin],
   setup() {

package/src/brand-page/components/page/Page.vue

@@ -338,6 +338,15 @@ body,
 body {
   line-height: 1.5;
 }
+/*
+ * Hide Google's floating reCAPTCHA badge. Google's Terms of Service permit this
+ * only when the reCAPTCHA branding is disclosed in the form flow instead — see
+ * RecaptchaDisclosure.vue, rendered by ContactForm and MailingList. Using
+ * visibility (not display:none) keeps the invisible-challenge flow working.
+ */
+.grecaptcha-badge {
+  visibility: hidden !important;
+}
 </style>
 
 <style scoped>

package/src/brand-page/components/recaptcha-disclosure/RecaptchaDisclosure.vue

@@ -0,0 +1,60 @@
+<!-- eslint-disable vue/no-v-html -->
+<template>
+  <!--
+    Google reCAPTCHA branding disclosure. Required by Google's Terms of Service
+    whenever the floating reCAPTCHA badge is hidden (see Page.vue). The copy is
+    static, trusted i18n content that includes the Privacy Policy / Terms of
+    Service links, so it is rendered with v-html.
+
+    Rendered only after mount (client-side). The web-renderer attaches the
+    initialised i18next instance via a server-only plugin, but on the initial
+    SSR pass `recaptchaTr` can resolve against an uninitialised instance and emit
+    the raw key. Deferring to the client (where i18next is always ready) mirrors
+    how the mailing-list form renders and guarantees the copy resolves.
+  -->
+  <p
+    v-if="isMounted"
+    data-component="recaptcha-disclosure"
+    class="recaptcha-disclosure"
+    :style="color ? { color } : undefined"
+    v-html="recaptchaTr('disclosure')"
+  />
+</template>
+<script>
+import { ref, onMounted } from 'vue';
+import { recaptchaTr } from '@src/composables/useTranslate';
+
+export default {
+  props: {
+    // Text colour for the disclosure; forms pass their title colour so the
+    // footnote follows the title style. Links inherit this colour.
+    color: {
+      type: String,
+      required: false,
+      default: undefined,
+    },
+  },
+  setup() {
+    const isMounted = ref(false);
+
+    onMounted(() => {
+      isMounted.value = true;
+    });
+
+    return {
+      recaptchaTr,
+      isMounted,
+    };
+  },
+};
+</script>
+
+<style scoped>
+.recaptcha-disclosure {
+  @apply tw-text-xs tw-text-center tw-mt-3;
+}
+.recaptcha-disclosure :deep(a) {
+  color: inherit;
+  text-decoration: underline;
+}
+</style>

package/src/brand-page/components/recaptcha-disclosure/RecaptchaDisclosure.vue.test.ts

@@ -0,0 +1,36 @@
+import { mount } from '@vue/test-utils';
+import { setLocaleAsync } from '@src/composables/useTranslate';
+import RecaptchaDisclosure from './RecaptchaDisclosure.vue';
+
+describe('RecaptchaDisclosure', () => {
+  test('renders the resolved disclosure copy after mount', async () => {
+    await setLocaleAsync('en-US');
+
+    const wrapper = mount(RecaptchaDisclosure);
+
+    await wrapper.vm.$nextTick();
+
+    const el = wrapper.find('[data-component="recaptcha-disclosure"]');
+
+    expect(el.exists()).toBe(true);
+    expect(el.element.tagName).toBe('P');
+    // Resolves the i18n key rather than emitting the raw `recaptcha.disclosure`.
+    expect(el.text()).toContain('Protected by reCAPTCHA');
+    expect(el.text()).not.toContain('recaptcha.disclosure');
+    // Links to Google's Privacy Policy / Terms are present.
+    expect(el.html()).toContain('https://policies.google.com/privacy');
+    expect(el.html()).toContain('https://policies.google.com/terms');
+  });
+
+  test('applies the provided color so it follows the title style', async () => {
+    const wrapper = mount(RecaptchaDisclosure, {
+      props: { color: 'rgb(10, 20, 30)' },
+    });
+
+    await wrapper.vm.$nextTick();
+
+    const el = wrapper.find('[data-component="recaptcha-disclosure"]');
+
+    expect(el.attributes('style')).toContain('color: rgb(10, 20, 30)');
+  });
+});

package/src/brand-page/components/recaptcha-disclosure/i18n/recaptcha.de-DE.json

@@ -0,0 +1,5 @@
+{
+  "recaptcha": {
+    "disclosure": "Geschützt durch reCAPTCHA (&lt;a href=&quot;https://policies.google.com/privacy\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Datenschutz</a> / &lt;a href=&quot;https://policies.google.com/terms\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Nutzungsbedingungen</a>)"
+  }
+}

package/src/brand-page/components/recaptcha-disclosure/i18n/recaptcha.es-ES.json

@@ -0,0 +1,5 @@
+{
+  "recaptcha": {
+    "disclosure": "Protegido por reCAPTCHA (&lt;a href=&quot;https://policies.google.com/privacy\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Privacidad</a> / &lt;a href=&quot;https://policies.google.com/terms\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Términos</a>)"
+  }
+}

package/src/brand-page/components/recaptcha-disclosure/i18n/recaptcha.fr-CA.json

@@ -0,0 +1,5 @@
+{
+  "recaptcha": {
+    "disclosure": "Protégé par reCAPTCHA (&lt;a href=&quot;https://policies.google.com/privacy\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Confidentialité</a> / &lt;a href=&quot;https://policies.google.com/terms\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Conditions</a>)"
+  }
+}

package/src/brand-page/components/recaptcha-disclosure/i18n/recaptcha.fr-FR.json

@@ -0,0 +1,5 @@
+{
+  "recaptcha": {
+    "disclosure": "Protégé par reCAPTCHA (&lt;a href=&quot;https://policies.google.com/privacy\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Confidentialité</a> / &lt;a href=&quot;https://policies.google.com/terms\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Conditions</a>)"
+  }
+}

package/src/brand-page/components/recaptcha-disclosure/i18n/recaptcha.json

@@ -0,0 +1,5 @@
+{
+  "recaptcha": {
+    "disclosure": "Protected by reCAPTCHA (<a href=\"https://policies.google.com/privacy\" target=\"_blank\" rel=\"noopener noreferrer\">Privacy</a> / <a href=\"https://policies.google.com/terms\" target=\"_blank\" rel=\"noopener noreferrer\">Terms</a>)"
+  }
+}

package/src/brand-page/components/recaptcha-disclosure/i18n/recaptcha.pt-BR.json

@@ -0,0 +1,5 @@
+{
+  "recaptcha": {
+    "disclosure": "Protegido pelo reCAPTCHA (&lt;a href=&quot;https://policies.google.com/privacy\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Termos de</a> / &lt;a href=&quot;https://policies.google.com/terms\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Privacidade</a>)"
+  }
+}

package/src/brand-page/components/recaptcha-disclosure/i18n/recaptcha.pt-PT.json

@@ -0,0 +1,5 @@
+{
+  "recaptcha": {
+    "disclosure": "Protegido pelo reCAPTCHA (&lt;a href=&quot;https://policies.google.com/privacy\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Termos de </a> / &lt;a href=&quot;https://policies.google.com/terms\" target=&quot;_blank&quot; rel=&quot;noopener noreferrer&quot;&gt;Privacidade</a>)"
+  }
+}

package/src/brand-page/utils/color.util.test.ts

@@ -1,4 +1,16 @@
-import { getNewColorBasedOnTargetColorTheme } from './color.util';
+import Color from 'color';
+import {
+  backgroundColorFromStyle,
+  getNewColorBasedOnTargetColorTheme,
+  mutedTextForBackground,
+} from './color.util';
+
+const wcagContrast = (a: string, b: string): number => {
+  const la = Color(a).luminosity();
+  const lb = Color(b).luminosity();
+
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+};
 
 describe('color.util - getNewColorBasedOnTargetColorTheme', () => {
   [
@@ -46,6 +58,71 @@ describe('color.util - getNewColorBasedOnTargetColorTheme', () => {
   });
 });
 
+describe('color.util - mutedTextForBackground', () => {
+  test('light background (beige) yields darker, legible text', () => {
+    const bg = '#f5f0e6';
+    const text = mutedTextForBackground(bg)!;
+
+    expect(text).toBeDefined();
+    // Darker than the background.
+    expect(Color(text).luminosity()).toBeLessThan(Color(bg).luminosity());
+    // Legible.
+    expect(wcagContrast(text, bg)).toBeGreaterThanOrEqual(3.4);
+  });
+
+  test('dark background yields lighter, legible text', () => {
+    const bg = '#1a2233';
+    const text = mutedTextForBackground(bg)!;
+
+    expect(text).toBeDefined();
+    // Lighter than the background.
+    expect(Color(text).luminosity()).toBeGreaterThan(Color(bg).luminosity());
+    expect(wcagContrast(text, bg)).toBeGreaterThanOrEqual(3.4);
+  });
+
+  test('mid-grey background still resolves to a legible colour', () => {
+    const bg = '#808080';
+    const text = mutedTextForBackground(bg)!;
+
+    expect(text).toBeDefined();
+    expect(wcagContrast(text, bg)).toBeGreaterThanOrEqual(3.4);
+  });
+
+  test('honours a higher target contrast', () => {
+    const bg = '#f5f0e6';
+    const text = mutedTextForBackground(bg, { targetContrast: 7 })!;
+
+    expect(wcagContrast(text, bg)).toBeGreaterThanOrEqual(6.9);
+  });
+
+  test('returns undefined for non-solid / unknown backgrounds', () => {
+    expect(mutedTextForBackground(undefined)).toBeUndefined();
+    expect(mutedTextForBackground('')).toBeUndefined();
+    expect(mutedTextForBackground('url(bg.png)')).toBeUndefined();
+    expect(mutedTextForBackground('transparent')).toBeUndefined();
+    expect(mutedTextForBackground('rgba(0,0,0,0)')).toBeUndefined();
+  });
+});
+
+describe('color.util - backgroundColorFromStyle', () => {
+  test('prefers backgroundColor (card/button styles)', () => {
+    expect(backgroundColorFromStyle({ backgroundColor: '#123456' })).toBe(
+      '#123456',
+    );
+  });
+
+  test('falls back to the `background` shorthand (section styles)', () => {
+    expect(backgroundColorFromStyle({ background: 'rgb(1, 2, 3)' })).toBe(
+      'rgb(1, 2, 3)',
+    );
+  });
+
+  test('returns undefined for empty / missing styles', () => {
+    expect(backgroundColorFromStyle(undefined)).toBeUndefined();
+    expect(backgroundColorFromStyle({})).toBeUndefined();
+  });
+});
+
 describe('color.util - getNewColorBasedOnTargetColorTheme near-grayscale snap', () => {
   // Reproducer for LangSmith trace 4e116ea3 (the "orangy drum"). The trio's
   // secondary was #fffcfa — perceptually white but HSL(24°, 100%, 99%). Without