Add support for bg image in surface

Author: cviterirei

src/components/surface/CdrSurface.vue

@@ -1,19 +1,46 @@
 <script setup lang="ts">
-import { useCssModule, computed } from 'vue';
+import { useCssModule, computed, type StyleValue } from 'vue';
 import type { surface } from '../../types/interfaces';
 import { getSurfaceProps } from '../../utils/surface';
 
 /** Foundational container for creating structured layouts */
 defineOptions({ name: 'CdrSurface' });
 
-const props = withDefaults(defineProps<surface>(), {
+const props = withDefaults(defineProps<surface & {
+  /** URL for the background image */
+  backgroundImage?: string;
+  /** Value for the background-size CSS property */
+  backgroundSize?: string;
+  /** Value for the background-position CSS property */
+  backgroundPosition?: string;
+}>(), {
   tag: 'div',
+  backgroundImage: undefined,
+  backgroundSize: 'cover',
+  backgroundPosition: 'center',
 });
 
 const style = useCssModule();
 
 // Use the merged props to compute the root props for the component.
-const rootProps = computed(() => getSurfaceProps(props));
+const baseProps = computed(() => getSurfaceProps(props));
+
+// Compute the inline styles for background image properties
+const imageStyles = computed(() => {
+  const styles: StyleValue = {};
+  if (props.backgroundImage) {
+    styles['--cdr-surface-background-image'] = `url(${props.backgroundImage})`;
+    styles['--cdr-surface-background-size'] = props.backgroundSize;
+    styles['--cdr-surface-background-position'] = props.backgroundPosition;
+  }
+  return styles;
+});
+
+// Merge base props and image styles
+const rootProps = computed(() => ({
+  ...baseProps.value,
+  style: imageStyles.value,
+}));
 </script>
 
 <template>

src/components/surface/__tests__/CdrSurface.spec.js

@@ -112,4 +112,40 @@ describe('CdrSurface', () => {
     expect(wrapper.attributes('data-background')).toBe('primary');
     expect(wrapper.element).toMatchSnapshot();
   });
+
+  it('applies background image properties via style attribute', () => {
+    const wrapper = mount(CdrSurface, {
+      props: {
+        backgroundImage: 'path/to/image.jpg',
+        backgroundSize: 'contain',
+        backgroundPosition: 'top left',
+      }
+    });
+    const style = wrapper.attributes('style');
+    expect(style).toContain('--cdr-surface-background-image: url(path/to/image.jpg);');
+    expect(style).toContain('--cdr-surface-background-size: contain;');
+    expect(style).toContain('--cdr-surface-background-position: top left;');
+    expect(wrapper.element).toMatchSnapshot();
+  });
+
+  it('applies background image with default size and position', () => {
+    const wrapper = mount(CdrSurface, {
+      props: {
+        backgroundImage: 'path/to/another.png',
+      }
+    });
+    const style = wrapper.attributes('style');
+    expect(style).toContain('--cdr-surface-background-image: url(path/to/another.png);');
+    expect(style).toContain('--cdr-surface-background-size: cover;'); // Default
+    expect(style).toContain('--cdr-surface-background-position: center;'); // Default
+    expect(wrapper.element).toMatchSnapshot();
+  });
+
+  it('does not apply background image styles if prop is not provided', () => {
+    const wrapper = mount(CdrSurface);
+    const style = wrapper.attributes('style');
+    // Expect style attribute to be undefined or not contain the background image variables
+    expect(style === undefined || !style.includes('--cdr-surface-background-image')).toBe(true);
+    expect(wrapper.element).toMatchSnapshot(); // Should match default snapshot
+  });
 });

src/components/surface/__tests__/__snapshots__/CdrSurface.spec.js.snap

@@ -1,5 +1,25 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`CdrSurface > applies background image properties via style attribute 1`] = `
+<div
+  class="cdr-surface"
+  style="--cdr-surface-background-image: url(path/to/image.jpg); --cdr-surface-background-size: contain; --cdr-surface-background-position: top left;"
+>
+  
+  
+</div>
+`;
+
+exports[`CdrSurface > applies background image with default size and position 1`] = `
+<div
+  class="cdr-surface"
+  style="--cdr-surface-background-image: url(path/to/another.png); --cdr-surface-background-size: cover; --cdr-surface-background-position: center;"
+>
+  
+  
+</div>
+`;
+
 exports[`CdrSurface > applies background property 1`] = `
 <div
   class="cdr-surface"
@@ -122,6 +142,15 @@ exports[`CdrSurface > default snapshot 1`] = `
 >
   
   
+</div>
+`;
+
+exports[`CdrSurface > does not apply background image styles if prop is not provided 1`] = `
+<div
+  class="cdr-surface"
+>
+  
+  
 </div>
 `;
 

src/components/surface/examples/Surface.vue

@@ -11,7 +11,7 @@ defineOptions({ name: 'Surface' });
 export interface Example {
   label: string;
   title: string;
-  props: surface | HtmlAttributes;
+  props: surface | HtmlAttributes | Record<string, any>;
 }
 
 const boxes: Example[] = [
@@ -78,6 +78,19 @@ const boxes: Example[] = [
       borderColor: 'primary',
     },
   },
+  {
+    label: 'This surface has a background image',
+    title: 'Background Image Example',
+    props: {
+      class: 'example__card example__card--image',
+      backgroundImage: 'https://picsum.photos/600/200',
+      backgroundSize: 'cover',
+      backgroundPosition: 'center center',
+      style: {
+        padding: '16px'
+      }
+    },
+  },
 ];
 </script>
 
@@ -109,6 +122,26 @@ const boxes: Example[] = [
   &__card {
     display: inline-block;
     padding: $cdr-space-two-x;
+    min-width: 300px;
+
+    &--image {
+      min-height: 150px;
+      position: relative;
+
+      &::after {
+        content: '';
+        position: absolute;
+        inset: 0;
+        background: linear-gradient(rgba(0,0,0,0.1), rgba(0,0,0,0.4));
+        border-radius: inherit;
+        pointer-events: none;
+      }
+
+      > * {
+        position: relative;
+        z-index: 1;
+      }
+    }
   }
 
   &__pill {

src/components/surface/styles/CdrSurface.module.scss

@@ -60,7 +60,7 @@ $css-vars: (
   border-width: --cdr-surface-border-width,
   border-style: --cdr-surface-border-style,
   border-radius: --border-radius,
-  box-shadow: --cdr-surface-box-shadow,
+  box-shadow: --cdr-surface-box-shadow
 );
 
 .cdr-surface {
@@ -112,9 +112,14 @@ $css-vars: (
   }
 
   background: var(--cdr-surface-background);
-  border-radius: var(--cdr-surface-border-radius);
+  border-radius: var(--cdr-surface-border-radius, var(--border-radius)); // Added fallback for potential naming mismatch
   box-shadow: var(--cdr-surface-box-shadow);
 
+  background-image: var(--cdr-surface-background-image);
+  background-size: var(--cdr-surface-background-size);
+  background-position: var(--cdr-surface-background-position);
+  background-repeat: no-repeat;
+
   &::before {
     border: var(--cdr-surface-border-width) var(--cdr-surface-border-style) var(--cdr-surface-border-color);
     border-radius: inherit;