Add support for bg image in surface

[c4rlosviteri]

Add background image support

Overview

This PR enhances the CdrSurface component by adding the capability to display background images. Users can now specify an image URL, along with optional background-size and background-position properties.

Key Changes

• New Props: Introduced three new optional props to <CdrSurface>:
  • backgroundImage (string): URL of the background image.
  • backgroundSize (string, default: 'cover'): Sets the background-size CSS property.
  • backgroundPosition (string, default: 'center'): Sets the background-position CSS property.
• Component Implementation (CdrSurface.vue):
  • Updated defineProps to include the new properties.
  • Added computed properties (imageStyles, rootProps) to dynamically generate inline styles that set CSS custom properties (--cdr-surface-background-image, --cdr-surface-background-size, --cdr-surface-background-position) when backgroundImage is provided.
• Styling (styles/CdrSurface.module.scss):
  • Added background-image, background-size, and background-position CSS rules that consume the corresponding CSS custom properties.
  • Set background-repeat: no-repeat by default when a background image is applied.
• Testing (__tests__/CdrSurface.spec.js):
  • Added new unit tests to verify that the component correctly applies the background image styles via CSS custom properties based on the provided props.
  • Updated existing snapshots.
• Examples (examples/Surface.vue):
  • Added a new example demonstrating how to use the backgroundImage, backgroundSize, and backgroundPosition props.
  • Included example styling for text readability over an image.

Motivation

This feature provides developers with more flexibility in styling surface containers, allowing for richer visual designs by incorporating background imagery directly within the component's API.

How to Test

1. Run the documentation site locally.
2. Navigate to the CdrSurface examples page.
3. Verify the new example with the background image renders correctly.
4. Inspect the element to confirm the inline styles and CSS custom properties are applied as expected.
5. Run unit tests (npm run test) and ensure all tests pass.

[mhewson]

can this support multiple images? I assume we will see cases where the surface needs specific art direction and a team will need to manage the image and its properties for each breakpoint?

[mhewson]

https://www.techie-jim.net/2024/05/18/responsive-background-images-with-or-without-image-set-the-proven-way/