wave-ui 4.1.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-ui",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "A UI framework for Vue.js 3 (and 2) with only the bright side. :sunny:",
   "author": "Antoni Andre <antoniandre.web@gmail.com>",
   "homepage": "https://antoniandre.github.io/wave-ui",

package/src/wave-ui/components/w-accordion/item.vue

@@ -94,6 +94,7 @@ import { focusElement } from '../../utils/focus'
 
 export default {
   name: 'w-accordion-item',
+  focusable: true,
   expose: ['focus'],
   mixins: [RippleMixin],
 

package/src/wave-ui/components/w-button/index.vue

@@ -16,6 +16,7 @@ import { focusElement } from '../../utils/focus'
 
 export default {
   name: 'w-button',
+  focusable: true,
   expose: ['focus'],
   inheritAttrs: false, // The attrs are only bound to the button-partial, not the root.
 

package/src/wave-ui/components/w-checkboxes.vue

@@ -37,6 +37,7 @@ import { guardFocusable } from '../utils/focus'
 
 export default {
   name: 'w-checkboxes',
+  focusable: true,
   expose: ['focus'],
   mixins: [FormElementMixin],
 

package/src/wave-ui/components/w-list.vue

@@ -49,6 +49,7 @@ import { focusElement } from '../utils/focus'
 
 export default {
   name: 'w-list',
+  focusable: true,
   expose: ['focus'],
   mixins: [RippleMixin],
 

package/src/wave-ui/components/w-menu.vue

@@ -2,7 +2,7 @@
 slot(name="activator")
 slot(v-if="!$slots.activator")
 teleport(v-if="detachableDomReady" :to="teleportTarget" :disabled="!teleportTarget")
-  transition(:name="transitionName" appear @after-leave="onAfterLeave")
+  transition(:name="transitionName" appear @after-enter="onDetachableAfterEnter" @after-leave="onAfterLeave")
     .w-menu(
       v-if="custom && detachableVisible"
       ref="detachable"

package/src/wave-ui/components/w-radios.vue

@@ -36,6 +36,7 @@ import { guardFocusable } from '../utils/focus'
 
 export default {
   name: 'w-radios',
+  focusable: true,
   expose: ['focus'],
   mixins: [FormElementMixin],
 

package/src/wave-ui/components/w-rating.vue

@@ -34,6 +34,7 @@ import { guardFocusable, focusElement } from '../utils/focus'
 
 export default {
   name: 'w-rating',
+  focusable: true,
   expose: ['focus'],
   mixins: [FormElementMixin],
 

package/src/wave-ui/components/w-scrollable.vue

@@ -43,7 +43,7 @@
 import { ref, computed, onMounted, onBeforeUnmount, nextTick, watch, useId, useAttrs } from 'vue'
 import { objectifyClasses } from '../utils/index'
 
-defineOptions({ name: 'WScrollable' })
+defineOptions({ name: 'WScrollable', focusable: true })
 
 const props = defineProps({
   color: { type: String, default: 'primary' },

package/src/wave-ui/components/w-tabs/index.vue

@@ -80,6 +80,7 @@ import { focusElement } from '../../utils/focus'
 
 export default {
   name: 'w-tabs',
+  focusable: true,
   expose: ['focus'],
   mixins: [RippleMixin],
 

package/src/wave-ui/components/w-tag.vue

@@ -23,6 +23,7 @@ import { focusElement } from '../utils/focus'
 
 export default {
   name: 'w-tag',
+  focusable: true,
   expose: ['focus'],
   mixins: [RippleMixin],
 

package/src/wave-ui/components/w-tooltip.vue

@@ -2,7 +2,7 @@
 slot(name="activator")
 slot(v-if="!$slots.activator")
 teleport(v-if="detachableDomReady" :to="teleportTarget" :disabled="!teleportTarget")
-  transition(:name="transitionName" appear @after-leave="onAfterLeave")
+  transition(:name="transitionName" appear @after-enter="onDetachableAfterEnter" @after-leave="onAfterLeave")
     .w-tooltip(
       v-if="detachableVisible"
       ref="detachable"

package/src/wave-ui/components/w-tree.vue

@@ -72,6 +72,7 @@ import { focusElement } from '../utils/focus'
 
 export default {
   name: 'w-tree',
+  focusable: true,
   expose: ['focus'],
 
   mixins: [RippleMixin],

package/src/wave-ui/core.js

@@ -2,10 +2,10 @@ import { reactive, inject } from 'vue'
 import { mergeConfig } from './utils/config'
 import { consoleWarn } from './utils/console'
 import { colorPalette, generateColorShades, flattenColors } from './utils/colors'
-import { injectColorsCSSInDOM, injectCSSInDOM } from './utils/dynamic-css'
+import { injectColorsCSSInDOM, injectCSSInDOM, generatePaletteVariables, generateColors } from './utils/dynamic-css'
 import { injectNotifManagerInDOM, NotificationManager } from './utils/notification-manager'
 import { waveRippleDirective } from './utils/wave-ripple-directive'
-import { scheduleFocus } from './utils/focus'
+import { scheduleFocus, registerVFocus, unregisterVFocus } from './utils/focus'
 import './scss/index.scss'
 
 let mounted = false
@@ -88,9 +88,12 @@ export default class WaveUI {
      * @param {string} theme - The theme to switch to.
      */
     switchTheme (theme) {
+      // Only remove the current colors stylesheet when the theme actually changes.
+      // This prevents a blink when switchTheme is called on first mount with the same theme
+      // that was already set during SSR (via getSSRStyles + useHead) or in the constructor.
+      if (this.theme !== theme) document.head.querySelector('#wave-ui-colors')?.remove?.()
       this.theme = theme
       document.documentElement.setAttribute('data-theme', theme)
-      document.head.querySelector('#wave-ui-colors')?.remove?.()
       const themeColors = this.config.colors[this.theme]
       injectColorsCSSInDOM(themeColors, colorPalette, this.config.css.colorShadeCssVariables)
       this.colors = flattenColors(themeColors, colorPalette)
@@ -107,13 +110,99 @@ export default class WaveUI {
         wApp.className = 'w-app' // First reset the classes.
         if (classes.length && classes[0]) wApp.classList.add(...classes)
       }
+    },
+
+    /**
+     * Returns the CSS strings for both Wave UI stylesheets so they can be injected
+     * server-side (e.g. via Nuxt's useHead) to prevent FOUC.
+     * The returned strings map to the `#wave-ui-palette` and `#wave-ui-colors` <style> tags.
+     *
+     * When called without a `theme` argument (recommended), `colors` contains both themes'
+     * custom color variables each scoped to `[data-theme="light"]` / `[data-theme="dark"]`.
+     * Combined with `WaveUI.getThemeInitScript()` injected as a blocking <script> in <head>,
+     * this guarantees the correct colors are present at first paint — no flash of wrong theme.
+     *
+     * When called with an explicit `theme`, returns only that theme's variables on `:root`
+     * (legacy / single-theme use cases).
+     *
+     * @param {string} [theme] - Explicit theme ('light'|'dark'). Omit for dual-scoped output.
+     * @returns {{ theme: string, palette: string, colors: string }}
+     */
+    getSSRStyles (theme) {
+      const palette = generatePaletteVariables(colorPalette)
+      const { colorShadeCssVariables } = this.config.css
+
+      // No theme specified → emit both themes scoped to [data-theme="X"] so a blocking init
+      // script only needs to set the attribute — no color flash is possible.
+      if (!theme) {
+        return {
+          theme: this.theme || this.config?.theme || 'light',
+          palette,
+          colors:
+            generateColors(this.config.colors.light, colorShadeCssVariables, '[data-theme="light"]') +
+            generateColors(this.config.colors.dark, colorShadeCssVariables, '[data-theme="dark"]')
+        }
+      }
+
+      return {
+        theme,
+        palette,
+        colors: generateColors(this.config.colors[theme], colorShadeCssVariables)
+      }
     }
   }
 
+  /**
+   * Resolves the initial theme from localStorage or OS preference.
+   * Use this as the `theme` install option so Wave UI is initialized with the correct
+   * theme from the very first render — no flash, no manual localStorage reading needed.
+   *
+   *   app.use(WaveUI, { theme: WaveUI.resolveInitialTheme() })
+   *
+   * On the server (SSR) where localStorage/window are unavailable, always returns 'light'
+   * as the safe fallback — pair with `getSSRStyles()` + `getThemeInitScript()` to handle
+   * the server → client handoff without FOUC.
+   *
+   * @param {string} [storageKey='waveui-theme'] - The localStorage key to read.
+   * @returns {'light'|'dark'}
+   */
+  static resolveInitialTheme (storageKey = 'waveui-theme') {
+    if (typeof window === 'undefined') return 'light'
+    try {
+      const stored = localStorage.getItem(storageKey)
+      if (stored === 'light' || stored === 'dark') return stored
+    }
+    catch { }
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+  }
+
+  /**
+   * Returns a minified inline script that sets `data-theme` on `<html>` synchronously,
+   * before any CSS is parsed or rendered — eliminating theme FOUC entirely.
+   *
+   * Inject it as a blocking (no async/defer) <script> in <head> before any CSS:
+   *
+   *   Nuxt — nuxt.config.ts:
+   *     app: { head: { script: [{ innerHTML: WaveUI.getThemeInitScript() }] } }
+   *
+   *   Plain HTML:
+   *     <script><%= WaveUI.getThemeInitScript() %></script>
+   *
+   * @param {string} [storageKey='waveui-theme'] - Must match the key used when saving the theme.
+   * @returns {string} Minified inline script string (no <script> tags).
+   */
+  static getThemeInitScript (storageKey = 'waveui-theme') {
+    const key = JSON.stringify(storageKey)
+    return `(function(){try{var t=localStorage.getItem(${key});if(t==='dark'||t==='light'){document.documentElement.setAttribute('data-theme',t);return}}catch(e){}if(window.matchMedia('(prefers-color-scheme:dark)').matches)document.documentElement.setAttribute('data-theme','dark')})()`
+  }
+
   static install (app, options = {}) {
     // Register directives.
     app.directive('focus', {
-      mounted: (el, binding, vnode) => scheduleFocus(vnode, el)
+      mounted: (el) => {
+        if (!registerVFocus(el)) scheduleFocus(el)
+      },
+      unmounted: (el) => unregisterVFocus(el)
     })
     app.directive('scroll', {
       mounted: (el, binding) => {
@@ -156,7 +245,12 @@ export default class WaveUI {
           }
 
           if (config.theme === 'auto') detectOSDarkMode($waveui) // Also switches the theme.
-          else $waveui.switchTheme(config.theme, true)
+          else {
+            // Respect any data-theme already set on <html> (e.g. by getThemeInitScript) so a
+            // blocking init script is enough — no need to pass `theme` to app.use(WaveUI, ...).
+            const docTheme = document.documentElement.getAttribute('data-theme')
+            $waveui.switchTheme(docTheme === 'light' || docTheme === 'dark' ? docTheme : config.theme)
+          }
 
           injectCSSInDOM($waveui)
           injectNotifManagerInDOM(app)
@@ -200,6 +294,7 @@ export default class WaveUI {
     app.provide('$waveui', $waveui)
 
     if (config.theme !== 'auto') {
+      this.$waveui.theme = config.theme
       this.$waveui.colors = flattenColors(config.colors[config.theme], colorPalette)
     }
   }

package/src/wave-ui/mixins/detachable.js

@@ -9,6 +9,7 @@
  */
 
 import { consoleWarn } from '../utils/console'
+import { callFocus } from '../utils/focus'
 
 // Minimum space (px) from the viewport edge when flipping / nudging.
 const VIEWPORT_MARGIN = 4
@@ -65,6 +66,10 @@ export default {
     // Components use this to bind visibility:hidden, so the element is never visible at the
     // wrong position before its coordinates are calculated.
     detachableReady: false,
+    // Transition @after-enter has run for the current open cycle.
+    _contentEntered: false,
+    // v-focus entries waiting for detachableReady + _contentEntered.
+    _autofocusTargets: [],
     // The Vue Teleport target. Stored as data (not computed) so it is resolved lazily at
     // open()-time — after the DOM is committed — rather than during VNode creation where
     // document.querySelector() may return null for elements that are part of the same render batch.
@@ -171,6 +176,35 @@ export default {
     onAfterLeave () {
       this.detachableReady = false
       this.detachableEl = null
+      this._contentEntered = false
+      this._autofocusTargets = []
+    },
+
+    onDetachableAfterEnter () {
+      this._contentEntered = true
+      this._maybeFlushAutofocus()
+    },
+
+    registerAutofocus (entry) {
+      if (!this._autofocusTargets) this._autofocusTargets = []
+      this._autofocusTargets.push(entry)
+      this._maybeFlushAutofocus()
+    },
+
+    unregisterAutofocus (el) {
+      if (!this._autofocusTargets?.length) return
+      this._autofocusTargets = this._autofocusTargets.filter(entry => entry.el !== el)
+    },
+
+    _maybeFlushAutofocus () {
+      if (this.detachableReady && this._contentEntered) this.flushAutofocus()
+    },
+
+    flushAutofocus () {
+      const targets = this._autofocusTargets || []
+      this._autofocusTargets = []
+      if (!targets.length) return
+      this.$nextTick(() => targets.forEach(({ el }) => callFocus(el)))
     },
 
     unbindActivatorDocEvents () {
@@ -253,6 +287,7 @@ export default {
 
       // Hide before entering the DOM; handles rapid re-opens where detachableReady is still true.
       this.detachableReady = false
+      this._contentEntered = false
 
       // Resolve the teleport target here, at open()-time, so the DOM is fully committed and
       // detachableDefaultRoot() (for nested menus/tooltips) returns the correct element.
@@ -274,8 +309,11 @@ export default {
         this.activatorWidth = this.activatorEl.offsetWidth
       }
 
-      if (!this.noPosition) this.computeDetachableCoords()
-      else this.detachableReady = true
+      if (!this.noPosition) await this.computeDetachableCoords()
+      else {
+        this.detachableReady = true
+        this._maybeFlushAutofocus()
+      }
 
       // In `getActivatorCoordinates` accessing the menu computed styles takes a few ms (less than 10ms),
       // if we don't postpone the Menu apparition it will start transition from a visible menu and
@@ -412,6 +450,7 @@ export default {
       // Always await $nextTick so coordinates, placement class, and visibility are flushed atomically.
       this.detachableReady = true
       await this.$nextTick()
+      this._maybeFlushAutofocus()
 
       // Guard against the component being unmounted while awaiting.
       if (!this.detachableEl) return

package/src/wave-ui/mixins/focusable.js

@@ -1,13 +1,22 @@
 import { guardFocusable, focusElement } from '../utils/focus'
 
 export default {
+  focusable: true,
+
   methods: {
     focus () {
       if (!guardFocusable(this)) return
       const refName = this.$options.focusTargetRef || 'input'
-      const target = this.$refs[refName]
-      if (target) focusElement(target)
-      else this.$nextTick(() => focusElement(this.$refs[refName]))
+      const tryFocus = () => {
+        const target = this.$refs[refName]
+        if (target) focusElement(target)
+        return !!target
+      }
+      if (tryFocus()) return
+      this.$nextTick(() => {
+        if (tryFocus()) return
+        this.$nextTick(() => tryFocus())
+      })
     }
   }
 }

package/src/wave-ui/utils/dynamic-css.js

@@ -9,7 +9,7 @@ const cssVars = {
 let breakpointsDef = { keys: [], values: [] }
 let currentBreakpoint = null
 
-const generatePaletteVariables = colorPalette => {
+export const generatePaletteVariables = colorPalette => {
   let cssVariablesString = ''
 
   colorPalette.forEach(({ label, color, shades = [] }) => {
@@ -26,7 +26,7 @@ const generatePaletteVariables = colorPalette => {
 // :root {[color1-variable], [color2-variable]}
 // .color1--bg {background-color: [color1-variable]}
 // .color1 {color: [color1-variable]}
-const generateColors = (themeColors, generateShadeCssVariables) => {
+export const generateColors = (themeColors, generateShadeCssVariables, scope = ':root') => {
   let styles = ''
   let cssVariablesString = ''
 
@@ -62,7 +62,7 @@ const generateColors = (themeColors, generateShadeCssVariables) => {
     for (const colorName in shades) cssVariablesString += `--w-${colorName}-color: ${shades[colorName]};`
   }
 
-  return `:root{${cssVariablesString}}${styles}`
+  return `${scope}{${cssVariablesString}}${styles}`
 }
 
 // Generate the layout grid. E.g. xs1, xs2, ..., xl12.

package/src/wave-ui/utils/focus.js

@@ -1,5 +1,29 @@
 import { nextTick } from 'vue'
 
+const DETACHABLE_COMPONENTS = new Set(['w-menu', 'w-tooltip'])
+
+/** Walk Vue 3 logical parent instances from a directive host element (`__vueParentComponent`). */
+function walkParentInstances (el, predicate) {
+  let instance = el?.__vueParentComponent
+  while (instance) {
+    if (predicate(instance)) return instance
+    instance = instance.parent
+  }
+  return null
+}
+
+function componentName (instance) {
+  return instance?.type?.name ?? instance?.proxy?.$options?.name
+}
+
+function isFocusableInstance (instance) {
+  return !!(instance?.type?.focusable || instance?.proxy?.$options?.focusable)
+}
+
+function isDetachableInstance (instance) {
+  return DETACHABLE_COMPONENTS.has(componentName(instance))
+}
+
 export function focusElement (el) {
   el?.focus?.()
 }
@@ -9,23 +33,20 @@ export function guardFocusable (vm) {
   return true
 }
 
-/**
- * Resolve focus() from a directive host. On components, `vnode` is the root element
- * VNode (no `vnode.component`); the DOM owner is on `el.__vueParentComponent`.
- * Walk up when the root is a wrapper (e.g. `w-form-element` around `w-input`).
- */
-export function resolveFocusFn (vnode, el) {
-  let instance = vnode?.component ?? el?.__vueParentComponent
-  while (instance) {
-    const focusFn = instance.exposed?.focus ?? instance.proxy?.focus
-    if (typeof focusFn === 'function') return focusFn
-    instance = instance.parent
-  }
-  return null
+/** Nearest ancestor component with `focusable: true` (e.g. w-input inside w-form-element). */
+export function resolveFocusableInstance (el) {
+  return walkParentInstances(el, isFocusableInstance)
+}
+
+/** w-menu / w-tooltip host for deferred v-focus while floating content opens. */
+export function findDetachableInstance (el) {
+  const instance = walkParentInstances(el, isDetachableInstance)
+  return instance?.proxy ?? null
 }
 
-export function callFocus (vnode, el) {
-  const focusFn = resolveFocusFn(vnode, el)
+export function callFocus (el) {
+  const instance = resolveFocusableInstance(el)
+  const focusFn = instance?.exposed?.focus ?? instance?.proxy?.focus
   if (typeof focusFn === 'function') {
     focusFn()
     return
@@ -34,6 +55,20 @@ export function callFocus (vnode, el) {
 }
 
 /** Schedule focus after mount so template refs exist on the host component. */
-export function scheduleFocus (vnode, el) {
-  nextTick(() => callFocus(vnode, el))
+export function scheduleFocus (el) {
+  nextTick(() => callFocus(el))
+}
+
+/** Register v-focus on a detachable host; returns false when not inside w-menu/w-tooltip. */
+export function registerVFocus (el) {
+  const detachable = findDetachableInstance(el)
+  if (!detachable) return false
+  el.__waveUiDetachable = detachable
+  detachable.registerAutofocus({ el })
+  return true
+}
+
+export function unregisterVFocus (el) {
+  el.__waveUiDetachable?.unregisterAutofocus(el)
+  delete el.__waveUiDetachable
 }