feat(useCssSupports): add useCssSupports (#5266)

Author: OrbisK

packages/core/index.ts

@@ -27,6 +27,7 @@ export * from './useCloned'
 export * from './useColorMode'
 export * from './useConfirmDialog'
 export * from './useCountdown'
+export * from './useCssSupports'
 export * from './useCssVar'
 export * from './useCurrentElement'
 export * from './useCycleList'

packages/core/useCssSupports/demo.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { useCssSupports } from '@vueuse/core'
+import { shallowRef } from 'vue'
+
+const conditionText = shallowRef('display: flex')
+const prop = shallowRef('container-type')
+const value = shallowRef('scroll-state')
+
+const { isSupported: conditionTextSupported } = useCssSupports(conditionText)
+const { isSupported: propValueSupported } = useCssSupports(prop, value)
+</script>
+
+<template>
+  <div style="display: flex; flex-direction: column;">
+    <input v-model="conditionText" name="condition" type="text">
+    <span><code>useCssSupports("{{ conditionText }}")</code>: {{ conditionTextSupported }}</span>
+    <hr>
+    <input v-model="prop" name="prop" type="text"><input v-model="value" name="value" type="text">
+    <span><code>useCssSupports("{{ prop }}", "{{ value }}")</code>: {{ propValueSupported }}</span>
+  </div>
+</template>

packages/core/useCssSupports/index.browser.test.ts

@@ -0,0 +1,57 @@
+import { useCssSupports } from '@vueuse/core'
+import { describe, expect, it } from 'vitest'
+import { shallowRef } from 'vue'
+
+describe('useCssSupports', () => {
+  it('should be defined', () => {
+    expect(useCssSupports).toBeDefined()
+  })
+
+  it('should correctly support existing features', () => {
+    const { isSupported: textDecoration } = useCssSupports('text-decoration-style', 'blink')
+    const { isSupported: transformOrigin } = useCssSupports('transform-origin', '5%')
+    const { isSupported: flex } = useCssSupports('display: flex')
+    const { isSupported: variable } = useCssSupports('(--foo: red)')
+    const { isSupported: selectorHas } = useCssSupports('selector(:has(a))')
+    const { isSupported: query } = useCssSupports('(transform-style: preserve) or (-moz-transform-style: preserve) or (-webkit-transform-style: preserve)')
+    const { isSupported: doesNotExists } = useCssSupports('doesNotExist')
+
+    expect(textDecoration.value).toBe(false)
+    expect(transformOrigin.value).toBe(true)
+    expect(flex.value).toBe(true)
+    expect(variable.value).toBe(true)
+    expect(selectorHas.value).toBe(true)
+    expect(query.value).toBe(false)
+    expect(doesNotExists.value).toBe(false)
+  })
+
+  it('should reactively update if condition, prop or value changes', () => {
+    const condition = shallowRef('display: flex')
+    const { isSupported } = useCssSupports(condition)
+    expect(isSupported.value).toBe(true)
+    condition.value = 'e18e'
+    expect(isSupported.value).toBe(false)
+    const prop = shallowRef('transform-origin')
+    const value = shallowRef('5%')
+    const { isSupported: variable } = useCssSupports(prop, value)
+    expect(variable.value).toBe(true)
+    value.value = 'e18e'
+    expect(variable.value).toBe(false)
+    value.value = '5%'
+    expect(variable.value).toBe(true)
+    prop.value = 'e18e'
+    expect(variable.value).toBe(false)
+  })
+
+  it('should not treat conditionText as prop when options is set and value is undefined', () => {
+    expect(useCssSupports('display: flex').isSupported.value).toBe(true)
+    expect(useCssSupports('display: flex', {}).isSupported.value).toBe(true)
+  })
+
+  it('should use prop + value instead of condition if value is explicitly undefined', () => {
+    expect(useCssSupports('display: flex').isSupported.value).toBe(true)
+    expect(useCssSupports('display: flex', undefined).isSupported.value).toBe(false)
+    // @ts-expect-error overload catches this issue correctly
+    expect(useCssSupports('display: flex', shallowRef(undefined)).isSupported.value).toBe(false)
+  })
+})

packages/core/useCssSupports/index.md

@@ -0,0 +1,15 @@
+---
+category: Browser
+---
+
+# useCssSupports
+
+SSR compatible and reactive [`CSS.supports`](https://developer.mozilla.org/docs/Web/API/CSS/supports_static).
+
+## Usage
+
+```ts
+import { useCssSupports } from '@vueuse/core'
+
+const { isSupported } = useCssSupports('container-type', 'scroll-state')
+```

packages/core/useCssSupports/index.ts

@@ -0,0 +1,48 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue'
+import type { ConfigurableWindow } from '../_configurable'
+import { isClient } from '@vueuse/shared'
+import { computed, toValue } from 'vue'
+import { defaultWindow } from '../_configurable'
+import { useMounted } from '../useMounted'
+
+export interface UseCssSupportsOptions extends ConfigurableWindow {
+  ssrValue?: boolean
+}
+
+export interface UseCssSupportsReturn {
+  isSupported: ComputedRef<boolean>
+}
+
+export function useCssSupports(property: MaybeRefOrGetter<string>, value: MaybeRefOrGetter<string>, options?: UseCssSupportsOptions): UseCssSupportsReturn
+export function useCssSupports(conditionText: MaybeRefOrGetter<string>, options?: UseCssSupportsOptions): UseCssSupportsReturn
+export function useCssSupports(...args: any[]): UseCssSupportsReturn {
+  let options: UseCssSupportsOptions = {}
+
+  if (typeof toValue(args.at(-1)) === 'object') {
+    options = args.pop()
+  }
+
+  const [prop, value] = args
+
+  const { window = defaultWindow, ssrValue = false } = options
+
+  const isMounted = useMounted()
+
+  return {
+    isSupported: computed(() => {
+      // to trigger the ref
+      // eslint-disable-next-line ts/no-unused-expressions
+      isMounted.value
+
+      if (!isClient) {
+        return ssrValue
+      }
+
+      return args.length === 2
+        // @ts-expect-error window type is not correct
+        ? window?.CSS.supports(toValue(prop), toValue(value))
+        // @ts-expect-error window type is not correct
+        : window?.CSS.supports(toValue(prop))
+    }),
+  }
+}

test/exports/core.yaml

@@ -156,6 +156,7 @@
   useConfirmDialog: function
   useCountdown: function
   useCounter: function
+  useCssSupports: function
   useCssVar: function
   useCurrentElement: function
   useCycleList: function