fix: white background option for export + Firefox download

Fixes two issues reported in #165:

- Export always produced a black background, making prints with a
  white page wasteful/unreadable. Adds a Dark/White background choice
  in the export modal, threaded through both PNG and SVG export.
- Firefox refused the download because the programmatic anchor was not
  attached to the document. The anchor is now appended before click and
  removed after, which Firefox requires.

Closes #165

ha-relevant: yes

frontend/src/utils/__tests__/export.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { exportToPng, exportToSvg, EXPORT_QUALITY_OPTIONS } from '../export'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { exportToPng, exportToSvg, EXPORT_QUALITY_OPTIONS, EXPORT_BACKGROUND_OPTIONS } from '../export'
 
 const mockToPng = vi.fn()
 const mockToSvg = vi.fn()
@@ -12,6 +12,7 @@ describe('exportToPng', () => {
   let el: HTMLElement
   let clickSpy: ReturnType<typeof vi.fn>
   let appendSpy: ReturnType<typeof vi.spyOn>
+  let removeSpy: ReturnType<typeof vi.spyOn>
   let createSpy: ReturnType<typeof vi.spyOn>
 
   beforeEach(() => {
@@ -21,6 +22,7 @@ describe('exportToPng', () => {
       Object.assign(document.createElement('a'), { click: clickSpy }) as HTMLAnchorElement
     )
     appendSpy = vi.spyOn(document.body, 'appendChild').mockImplementation((n) => n)
+    removeSpy = vi.spyOn(document.body, 'removeChild').mockImplementation((n) => n)
     mockToPng.mockResolvedValue('data:image/png;base64,abc')
     mockToSvg.mockResolvedValue('data:image/svg+xml;base64,abc')
   })
@@ -28,6 +30,7 @@ describe('exportToPng', () => {
   afterEach(() => {
     createSpy.mockRestore()
     appendSpy.mockRestore()
+    removeSpy.mockRestore()
   })
 
   it('calls toPng with pixelRatio 1 for standard quality', async () => {
@@ -55,15 +58,28 @@ describe('exportToPng', () => {
     expect(clickSpy).toHaveBeenCalled()
   })
 
-  it('passes dark background color', async () => {
+  it('defaults to dark background color', async () => {
     await exportToPng(el, 'standard')
     expect(mockToPng).toHaveBeenCalledWith(el, expect.objectContaining({ backgroundColor: '#0d1117' }))
   })
+
+  it('uses white background color when white is requested (printing)', async () => {
+    await exportToPng(el, 'standard', 'white')
+    expect(mockToPng).toHaveBeenCalledWith(el, expect.objectContaining({ backgroundColor: '#ffffff' }))
+  })
+
+  it('attaches the download anchor to the DOM so Firefox triggers the download', async () => {
+    await exportToPng(el, 'high')
+    expect(appendSpy).toHaveBeenCalled()
+    expect(removeSpy).toHaveBeenCalled()
+  })
 })
 
 describe('exportToSvg', () => {
   let el: HTMLElement
   let clickSpy: ReturnType<typeof vi.fn>
+  let appendSpy: ReturnType<typeof vi.spyOn>
+  let removeSpy: ReturnType<typeof vi.spyOn>
   let createSpy: ReturnType<typeof vi.spyOn>
 
   beforeEach(() => {
@@ -72,18 +88,27 @@ describe('exportToSvg', () => {
     createSpy = vi.spyOn(document, 'createElement').mockReturnValue(
       Object.assign(document.createElement('a'), { click: clickSpy }) as HTMLAnchorElement
     )
+    appendSpy = vi.spyOn(document.body, 'appendChild').mockImplementation((n) => n)
+    removeSpy = vi.spyOn(document.body, 'removeChild').mockImplementation((n) => n)
     mockToSvg.mockResolvedValue('data:image/svg+xml;base64,abc')
   })
 
   afterEach(() => {
     createSpy.mockRestore()
+    appendSpy.mockRestore()
+    removeSpy.mockRestore()
   })
 
-  it('calls toSvg with dark background color', async () => {
+  it('defaults to dark background color', async () => {
     await exportToSvg(el)
     expect(mockToSvg).toHaveBeenCalledWith(el, expect.objectContaining({ backgroundColor: '#0d1117' }))
   })
 
+  it('uses white background color when white is requested (printing)', async () => {
+    await exportToSvg(el, 'white')
+    expect(mockToSvg).toHaveBeenCalledWith(el, expect.objectContaining({ backgroundColor: '#ffffff' }))
+  })
+
   it('triggers a download', async () => {
     await exportToSvg(el)
     expect(clickSpy).toHaveBeenCalled()
@@ -103,3 +128,13 @@ describe('EXPORT_QUALITY_OPTIONS', () => {
     expect(EXPORT_QUALITY_OPTIONS.map((o) => o.pixelRatio)).toEqual([1, 2, 4])
   })
 })
+
+describe('EXPORT_BACKGROUND_OPTIONS', () => {
+  it('offers dark and white', () => {
+    expect(EXPORT_BACKGROUND_OPTIONS.map((o) => o.value)).toEqual(['dark', 'white'])
+  })
+
+  it('maps to the expected colors', () => {
+    expect(EXPORT_BACKGROUND_OPTIONS.map((o) => o.color)).toEqual(['#0d1117', '#ffffff'])
+  })
+})

frontend/src/utils/export.ts

@@ -2,6 +2,7 @@ import { toPng, toSvg } from 'html-to-image'
 
 export type ExportQuality = 'standard' | 'high' | 'ultra'
 export type ExportFormat = 'png' | 'svg'
+export type ExportBackground = 'dark' | 'white'
 
 export const EXPORT_QUALITY_OPTIONS: { value: ExportQuality; label: string; pixelRatio: number; hint: string }[] = [
   { value: 'standard', label: 'Standard', pixelRatio: 1, hint: '1× — small file' },
@@ -9,10 +10,23 @@ export const EXPORT_QUALITY_OPTIONS: { value: ExportQuality; label: string; pixe
   { value: 'ultra',    label: 'Ultra',    pixelRatio: 4, hint: '4× — print quality, large file' },
 ]
 
-export async function exportToPng(element: HTMLElement, quality: ExportQuality = 'high'): Promise<void> {
+export const EXPORT_BACKGROUND_OPTIONS: { value: ExportBackground; label: string; color: string; hint: string }[] = [
+  { value: 'dark',  label: 'Dark',  color: '#0d1117', hint: 'screen / docs' },
+  { value: 'white', label: 'White', color: '#ffffff', hint: 'printing' },
+]
+
+function backgroundColor(background: ExportBackground): string {
+  return (EXPORT_BACKGROUND_OPTIONS.find((o) => o.value === background) ?? EXPORT_BACKGROUND_OPTIONS[0]).color
+}
+
+export async function exportToPng(
+  element: HTMLElement,
+  quality: ExportQuality = 'high',
+  background: ExportBackground = 'dark',
+): Promise<void> {
   const option = EXPORT_QUALITY_OPTIONS.find((o) => o.value === quality) ?? EXPORT_QUALITY_OPTIONS[1]
   const dataUrl = await toPng(element, {
-    backgroundColor: '#0d1117',
+    backgroundColor: backgroundColor(background),
     pixelRatio: option.pixelRatio,
     style: {
       '--xy-controls-display': 'none',
@@ -22,9 +36,12 @@ export async function exportToPng(element: HTMLElement, quality: ExportQuality =
   triggerDownload(dataUrl, 'homelable-canvas.png')
 }
 
-export async function exportToSvg(element: HTMLElement): Promise<void> {
+export async function exportToSvg(
+  element: HTMLElement,
+  background: ExportBackground = 'dark',
+): Promise<void> {
   const dataUrl = await toSvg(element, {
-    backgroundColor: '#0d1117',
+    backgroundColor: backgroundColor(background),
     style: {
       '--xy-controls-display': 'none',
     } as Partial<CSSStyleDeclaration>,
@@ -37,5 +54,8 @@ function triggerDownload(dataUrl: string, filename: string): void {
   const link = document.createElement('a')
   link.download = filename
   link.href = dataUrl
+  // Firefox only triggers a programmatic click when the anchor is in the DOM.
+  document.body.appendChild(link)
   link.click()
+  document.body.removeChild(link)
 }