feat(hub-ui): accept custom viewer backgrounds

Author: dvcolomban

docs/content/1.guide/18.hub-initiate.md

@@ -62,7 +62,7 @@ interface DevframeHubUi {
 `@devframes/hub-ui`'s `createUi()` is the reference (standalone `viewer` SPA + floating dock); its `setup(ctx)` publishes config to `ctx.staticConfig.ui` (`ConnectionMeta.configs.ui`):
 
 - **`viewer`** — set to `false` to disable the standalone viewer.
-- **`branding`** — rebrand the UI (logo, name, primary color), or set `background: 'transparent'` when the standalone viewer should reveal the host page behind its iframe.
+- **`branding`** — rebrand the UI (logo, name, primary color). `background` accepts any CSS `background` value (color, gradient, image, or `transparent`) or `{ light, dark }` variants; omit it to keep the design default.
 - **`dockPreferences`** — dock-rail: `categoryOrder`, floating-dock `maxVisibleItems`, first-run `defaultMode` (`'float'`/`'edge'`) and `defaultPosition`.
 - **`embeddedVisibility`** — the floating dock's reveal policy:
   - `'normal'` (default) — shows immediately.

packages/hub-ui/src/client/standalone/index.html

@@ -14,9 +14,8 @@
         color-scheme: dark;
         --devframes-viewer-background: #111;
       }
-      html.viewer-background-transparent {
+      html.viewer-background-custom {
         color-scheme: normal;
-        --devframes-viewer-background: transparent;
       }
       html,
       body {

packages/hub-ui/src/client/standalone/main.ts

@@ -2,7 +2,7 @@ import type { DockSessionStorage } from '@devframes/hub/client'
 import { getDevframeRpcClient, setDevframeClientContext } from '@devframes/hub/client'
 import { useSessionStorage } from '@vueuse/core'
 import { watchEffect } from 'vue'
-import { applyDocumentHead, applyPrimaryColor, setBranding } from '../state/branding'
+import { applyDocumentHead, applyPrimaryColor, setBranding, useBrandingBackground } from '../state/branding'
 import { isDark } from '../state/color-mode'
 import { DEFAULT_DOCK_SESSION_STORE } from '../state/docks'
 
@@ -15,11 +15,21 @@ import { DEFAULT_DOCK_SESSION_STORE } from '../state/docks'
 // The standalone viewer runs in the light DOM, so mirror the color mode onto the
 // document element — its background follows the Auto/Light/Dark choice. The
 // component tree carries `color-scheme` for its native controls; keeping that
-// off the document lets the transparent viewer reveal the host page.
+// off the document lets custom backgrounds composite with the host page.
+const brandingBackground = useBrandingBackground()
+
 watchEffect(() => {
   const el = document.documentElement
   el.classList.toggle('dark', isDark.value)
   el.classList.toggle('light', !isDark.value)
+
+  const background = brandingBackground.value
+  const hasValidBackground = background !== undefined && CSS.supports('background', background)
+  el.classList.toggle('viewer-background-custom', hasValidBackground)
+  if (hasValidBackground)
+    el.style.setProperty('--devframes-viewer-background', background)
+  else
+    el.style.removeProperty('--devframes-viewer-background')
 })
 
 async function main(): Promise<void> {
@@ -39,7 +49,6 @@ async function main(): Promise<void> {
   // established above.
   const branding = setBranding(rpc.connectionMeta.configs?.ui?.branding || {})
   applyDocumentHead(document, branding)
-  document.documentElement.classList.toggle('viewer-background-transparent', branding.background === 'transparent')
 
   // Per-tab session UI state (which dock is open + its route). `sessionStorage`
   // so a reload restores the selection after the auth handshake, per-tab.

packages/hub-ui/src/client/state/branding.ts

@@ -9,7 +9,7 @@ export interface ResolvedBranding {
   logo?: BrandingLogo
   wordmark?: BrandingLogo
   primaryColor?: string
-  background: 'default' | 'transparent'
+  background?: DevframeBranding['background']
   tagline?: string
   favicon?: string
   windowTitle: string
@@ -24,7 +24,7 @@ function resolveDefaults(branding: DevframeBranding): ResolvedBranding {
     logo: branding.logo,
     wordmark: branding.wordmark,
     primaryColor: branding.primaryColor,
-    background: branding.background || 'default',
+    background: branding.background,
     tagline: branding.tagline,
     favicon: branding.favicon,
     windowTitle: branding.windowTitle?.trim() || productName,
@@ -46,15 +46,20 @@ export function setBranding(branding: DevframeBranding): ResolvedBranding {
 
 /** The logo/wordmark URL for the current color scheme, reactive to it. */
 export function useBrandingLogo(pick: (b: ResolvedBranding) => BrandingLogo | undefined = b => b.logo): Ref<string | undefined> {
-  return computed(() => resolveLogo(pick(currentBranding.value), isDark.value))
+  return computed(() => resolveColorSchemeValue(pick(currentBranding.value), isDark.value))
 }
 
-function resolveLogo(logo: BrandingLogo | undefined, dark: boolean): string | undefined {
-  if (!logo)
+/** The standalone viewer background for the current color scheme. */
+export function useBrandingBackground(): Ref<string | undefined> {
+  return computed(() => resolveColorSchemeValue(currentBranding.value.background, isDark.value))
+}
+
+function resolveColorSchemeValue(value: BrandingLogo | undefined, dark: boolean): string | undefined {
+  if (!value)
     return undefined
-  if (typeof logo === 'string')
-    return logo
-  return dark ? (logo.dark || logo.light) : logo.light
+  if (typeof value === 'string')
+    return value
+  return dark ? (value.dark || value.light) : value.light
 }
 
 // --- Applying to the DOM --------------------------------------------------

packages/hub-ui/src/index.test.ts

@@ -1,6 +1,6 @@
 import type { DevframeHubContext } from '@devframes/hub/node'
 import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { createUi } from './index'
 
@@ -10,15 +10,16 @@ function createContext(): DevframeHubContext {
 
 describe('createUi branding background', () => {
   it('defines the viewer background through a static token', () => {
-    expect.assertions(5)
+    expect.assertions(6)
 
-    const html = readFileSync(join(import.meta.dirname, '..', 'dist', 'client', 'standalone', 'index.html'), 'utf8')
+    const html = readFileSync(fileURLToPath(new URL('../dist/client/standalone/index.html', import.meta.url)), 'utf8')
 
     expect(html).not.toContain('__hub-ui.css')
-    expect(html).toContain('html.viewer-background-transparent')
-    expect(html).toContain('--devframes-viewer-background: transparent')
+    expect(html).toContain('html.viewer-background-custom')
+    expect(html).toContain('--devframes-viewer-background: #fff')
+    expect(html).toContain('--devframes-viewer-background: #111')
     expect(html).toContain('background: var(--devframes-viewer-background)')
-    expect(html).toMatch(/html\.viewer-background-transparent\s*\{[^}]*color-scheme:\s*normal/)
+    expect(html).toMatch(/html\.viewer-background-custom\s*\{[^}]*color-scheme:\s*normal/)
   })
 
   it('preserves the default viewer background', () => {
@@ -32,7 +33,7 @@ describe('createUi branding background', () => {
     expect(ui.assets).toBeUndefined()
   })
 
-  it('publishes a transparent viewer background with the branding', () => {
+  it('publishes a CSS viewer background with the branding', () => {
     expect.assertions(2)
 
     const context = createContext()
@@ -45,6 +46,20 @@ describe('createUi branding background', () => {
     expect(ui.assets).toBeUndefined()
   })
 
+  it('publishes color-scheme viewer backgrounds with the branding', () => {
+    expect.assertions(1)
+
+    const context = createContext()
+    const background = {
+      light: 'linear-gradient(white, transparent)',
+      dark: 'linear-gradient(#111, transparent)',
+    }
+    const ui = createUi({ branding: { background } })
+    ui.setup?.(context)
+
+    expect(context.staticConfig.ui).toEqual({ branding: { background } })
+  })
+
   it('disables the standalone viewer', () => {
     expect.assertions(1)
 

packages/hub-ui/src/types.ts

@@ -31,8 +31,8 @@ export interface DevframeBranding {
   wordmark?: BrandingLogo
   /** Brand color; feeds `--devframe-primary` and the whole primary ramp. */
   primaryColor?: string
-  /** Standalone viewer background. Default: `'default'`. */
-  background?: 'default' | 'transparent'
+  /** Standalone viewer CSS `background`; a string applies to both color schemes. */
+  background?: string | { light: string, dark: string }
   /** Short line for the auth screen and the standalone meta description. */
   tagline?: string
   /** Favicon URL — applied on the standalone viewer and the popped-out window only. */

tests/__snapshots__/tsnapi/@devframes/hub-ui/index.snapshot.d.ts

@@ -14,7 +14,10 @@ export interface DevframeBranding {
   logo?: BrandingLogo;
   wordmark?: BrandingLogo;
   primaryColor?: string;
-  background?: 'default' | 'transparent';
+  background?: string | {
+    light: string;
+    dark: string;
+  };
   tagline?: string;
   favicon?: string;
   windowTitle?: string;