feat: support css cascade layers (#19641)

vuetifyjs · Apr 18, 2024 · 4820347 · 4820347
1 parent 69b5cc8
commit 4820347
Show file tree

Hide file tree

Showing 128 changed files with 7,014 additions and 6,788 deletions.
diff --git a/packages/docs/src/main.ts b/packages/docs/src/main.ts
@@ -1,17 +1,11 @@
 // Styles
 import 'prism-theme-vars/base.css'
 
-// App
-import App from './App.vue'
-
-// Virtual
-// import 'virtual:api'
-import { setupLayouts } from 'virtual:generated-layouts'
-
 // Plugins
 import { createApp } from 'vue'
 import { createRouter, createWebHistory } from 'vue-router'
 import { createHead } from '@unhead/vue'
+import { installVuetify } from '@/plugins/vuetify'
 import { installPinia, pinia } from '@/plugins/pinia'
 import { installGlobalComponents } from '@/plugins/global-components'
 import { installGtag } from '@/plugins/gtag'
@@ -21,7 +15,13 @@ import { useAppStore } from '@/stores/app'
 import { useLocaleStore } from '@/stores/locale'
 import { installPwa } from '@/plugins/pwa'
 import { useUserStore } from '@vuetify/one'
-import { installVuetify } from '@/plugins/vuetify'
+
+// App
+import App from './App.vue'
+
+// Virtual
+// import 'virtual:api'
+import { setupLayouts } from 'virtual:generated-layouts'
 
 // Utilities
 import {

diff --git a/packages/docs/src/pages/en/features/sass-variables.md b/packages/docs/src/pages/en/features/sass-variables.md
@@ -233,6 +233,30 @@ Color packs are handy for quickly applying a color to a component but mostly unu
 );
 ```
 
+## Enabling CSS cascade layers
+
+::: success
+This feature was introduced in [v3.6.0 (Nebula)](/getting-started/release-notes/?version=v3.6.0)
+:::
+
+[Cascade layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) are a modern CSS feature that makes it easier to write custom styles without having to deal with specificity issues and `!important`. This will be included by default in Vuetify 4 but can optionally be used now:
+
+```scss { resource="src/styles/settings.scss" }
+@forward 'vuetify/settings' with (
+  $layers: true,
+);
+```
+
+Import order of stylesheets becomes much more important with layers enabled, `import 'vuetify/styles'` or a file containing `@use 'vuetify'` **must** be loaded *before* any components or the CSS reset will take precedence over component styles and break everything. If you have separate plugin files make sure to import vuetify's before `App.vue`.
+
+Your own styles will always<sup>*</sup> override vuetify's if you don't use `@layer` yourself, or you can specify an order for custom layers in a stylesheet loaded before vuetify.
+
+```css { resource="src/styles/layers.css" }
+@layer base, vuetify, overrides;
+```
+
+\* Layers invert `!important`, so anything trying to override an important vuetify style must also be in a layer. { class="text-caption" }
+
 ## Caveats
 
 When using sass variables, there are a few considerations to be aware of.

diff --git a/packages/docs/src/pages/en/getting-started/installation.md b/packages/docs/src/pages/en/getting-started/installation.md
@@ -218,7 +218,6 @@ You should now have access to all Vuetify components and tools in Nuxt app.
 
 ```js
 import { createApp } from 'vue'
-import App from './App.vue'
 
 // Vuetify
 import '@mdi/font/css/materialdesignicons.css'
@@ -227,6 +226,9 @@ import { createVuetify } from 'vuetify'
 import * as components from 'vuetify/components'
 import * as directives from 'vuetify/directives'
 
+// Components
+import App from './App.vue'
+
 const vuetify = createVuetify({
   components,
   directives
@@ -293,14 +295,16 @@ In the file where you create the Vue application, add the following code
 
 ```js
 import { createApp } from 'vue'
-import App from './App.vue'
 
 // Vuetify
 import 'vuetify/styles'
 import { createVuetify } from 'vuetify'
 import * as components from 'vuetify/components'
 import * as directives from 'vuetify/directives'
 
+// Components
+import App from './App.vue'
+
 const vuetify = createVuetify({
   components,
   directives,

diff --git a/packages/vuetify/src/components/VAlert/VAlert.sass b/packages/vuetify/src/components/VAlert/VAlert.sass
@@ -1,132 +1,133 @@
 @use '../../styles/tools'
 @use './variables' as *
 
-.v-alert
-  display: grid
-  flex: 1 1
-  grid-template-areas: "prepend content append close" ". content . ."
-  grid-template-columns: max-content auto max-content max-content
-  position: relative
-  padding: $alert-padding
-  overflow: hidden
-  --v-border-color: #{$alert-border-color}
-
-  @include tools.position($alert-positions)
-  @include tools.rounded($alert-border-radius)
-  @include tools.variant($alert-variants...)
-
-  &--prominent
-    grid-template-areas: "prepend content append close" "prepend content . ."
-
-  &.v-alert--border
-    --v-border-opacity: #{$alert-border-opacity}
-
-    &.v-alert--border-start
-      padding-inline-start: $alert-padding + $alert-border-thin-width
-
-    &.v-alert--border-end
-      padding-inline-end: $alert-padding + $alert-border-thin-width
-
-  &--variant-plain
-    transition: $alert-plain-transition
-
-  @at-root
-    @include tools.density('v-alert', $alert-density) using ($modifier)
-      padding-bottom: $alert-padding + $modifier
-      padding-top: $alert-padding + $modifier
-
-      &.v-alert--border-top
-        padding-top: $alert-padding + $alert-border-thin-width + $modifier
-
-      &.v-alert--border-bottom
-        padding-bottom: $alert-padding + $alert-border-thin-width + $modifier
-
-.v-alert__border
-  border-radius: inherit
-  bottom: 0
-  left: 0
-  opacity: var(--v-border-opacity)
-  position: absolute
-  pointer-events: none
-  right: 0
-  top: 0
-  width: 100%
-
-  @include tools.border($alert-border...)
-
-  .v-alert--border-start &
-    border-inline-start-width: $alert-border-thin-width
-
-  .v-alert--border-end &
-    border-inline-end-width: $alert-border-thin-width
-
-  .v-alert--border-top &
-    border-top-width: $alert-border-thin-width
-
-  .v-alert--border-bottom &
-    border-bottom-width: $alert-border-thin-width
-
-.v-alert__close
-  flex: 0 1 auto
-  grid-area: close
-
-.v-alert__content
-  align-self: center
-  grid-area: content
-  overflow: hidden
-
-.v-alert__append,
-.v-alert__close
-  align-self: flex-start
-  margin-inline-start: $alert-append-margin-inline-start
-
-.v-alert__append
-  align-self: flex-start
-  grid-area: append
-
-  + .v-alert__close
-    margin-inline-start: $alert-append-close-margin-inline-start
-
-.v-alert__prepend
-  align-self: flex-start
-  display: flex
-  align-items: center
-  grid-area: prepend
-  margin-inline-end: $alert-prepend-margin-inline-end
-
-  .v-alert--prominent &
+@include tools.layer('components')
+  .v-alert
+    display: grid
+    flex: 1 1
+    grid-template-areas: "prepend content append close" ". content . ."
+    grid-template-columns: max-content auto max-content max-content
+    position: relative
+    padding: $alert-padding
+    overflow: hidden
+    --v-border-color: #{$alert-border-color}
+
+    @include tools.position($alert-positions)
+    @include tools.rounded($alert-border-radius)
+    @include tools.variant($alert-variants...)
+
+    &--prominent
+      grid-template-areas: "prepend content append close" "prepend content . ."
+
+    &.v-alert--border
+      --v-border-opacity: #{$alert-border-opacity}
+
+      &.v-alert--border-start
+        padding-inline-start: $alert-padding + $alert-border-thin-width
+
+      &.v-alert--border-end
+        padding-inline-end: $alert-padding + $alert-border-thin-width
+
+    &--variant-plain
+      transition: $alert-plain-transition
+
+    @at-root
+      @include tools.density('v-alert', $alert-density) using ($modifier)
+        padding-bottom: $alert-padding + $modifier
+        padding-top: $alert-padding + $modifier
+
+        &.v-alert--border-top
+          padding-top: $alert-padding + $alert-border-thin-width + $modifier
+
+        &.v-alert--border-bottom
+          padding-bottom: $alert-padding + $alert-border-thin-width + $modifier
+
+  .v-alert__border
+    border-radius: inherit
+    bottom: 0
+    left: 0
+    opacity: var(--v-border-opacity)
+    position: absolute
+    pointer-events: none
+    right: 0
+    top: 0
+    width: 100%
+
+    @include tools.border($alert-border...)
+
+    .v-alert--border-start &
+      border-inline-start-width: $alert-border-thin-width
+
+    .v-alert--border-end &
+      border-inline-end-width: $alert-border-thin-width
+
+    .v-alert--border-top &
+      border-top-width: $alert-border-thin-width
+
+    .v-alert--border-bottom &
+      border-bottom-width: $alert-border-thin-width
+
+  .v-alert__close
+    flex: 0 1 auto
+    grid-area: close
+
+  .v-alert__content
     align-self: center
+    grid-area: content
+    overflow: hidden
+
+  .v-alert__append,
+  .v-alert__close
+    align-self: flex-start
+    margin-inline-start: $alert-append-margin-inline-start
+
+  .v-alert__append
+    align-self: flex-start
+    grid-area: append
+
+    + .v-alert__close
+      margin-inline-start: $alert-append-close-margin-inline-start
+
+  .v-alert__prepend
+    align-self: flex-start
+    display: flex
+    align-items: center
+    grid-area: prepend
+    margin-inline-end: $alert-prepend-margin-inline-end
 
-.v-alert__underlay
-  grid-area: none
-  position: absolute
-
-  .v-alert--border-start &
-    border-top-left-radius: 0
-    border-bottom-left-radius: 0
-
-  .v-alert--border-end &
-    border-top-right-radius: 0
-    border-bottom-right-radius: 0
-
-  .v-alert--border-top &
-    border-top-left-radius: 0
-    border-top-right-radius: 0
-
-  .v-alert--border-bottom &
-    border-bottom-left-radius: 0
-    border-bottom-right-radius: 0
-
-.v-alert-title
-  align-items: center
-  align-self: center
-  display: flex
-  font-size: $alert-title-font-size
-  font-weight: $alert-title-font-weight
-  hyphens: $alert-title-hyphens
-  letter-spacing: $alert-title-letter-spacing
-  line-height: $alert-title-line-height
-  overflow-wrap: $alert-title-overflow-wrap
-  text-transform: $alert-title-text-transform
-  word-break: $alert-title-word-break
-  word-wrap: $alert-title-word-wrap
+    .v-alert--prominent &
+      align-self: center
+
+  .v-alert__underlay
+    grid-area: none
+    position: absolute
+
+    .v-alert--border-start &
+      border-top-left-radius: 0
+      border-bottom-left-radius: 0
+
+    .v-alert--border-end &
+      border-top-right-radius: 0
+      border-bottom-right-radius: 0
+
+    .v-alert--border-top &
+      border-top-left-radius: 0
+      border-top-right-radius: 0
+
+    .v-alert--border-bottom &
+      border-bottom-left-radius: 0
+      border-bottom-right-radius: 0
+
+  .v-alert-title
+    align-items: center
+    align-self: center
+    display: flex
+    font-size: $alert-title-font-size
+    font-weight: $alert-title-font-weight
+    hyphens: $alert-title-hyphens
+    letter-spacing: $alert-title-letter-spacing
+    line-height: $alert-title-line-height
+    overflow-wrap: $alert-title-overflow-wrap
+    text-transform: $alert-title-text-transform
+    word-break: $alert-title-word-break
+    word-wrap: $alert-title-word-wrap
diff --git a/packages/vuetify/src/components/VApp/VApp.sass b/packages/vuetify/src/components/VApp/VApp.sass
@@ -1,16 +1,18 @@
+@use '../../styles/tools'
 @use './variables' as *
 
-.v-application
-  display: flex
-  background: $application-background
-  color: $application-color
+@include tools.layer('components')
+  .v-application
+    display: flex
+    background: $application-background
+    color: $application-color
 
-.v-application__wrap
-  backface-visibility: hidden
-  display: flex
-  flex-direction: column
-  flex: 1 1 auto
-  max-width: 100%
-  min-height: 100vh
-  min-height: 100dvh
-  position: relative
+  .v-application__wrap
+    backface-visibility: hidden
+    display: flex
+    flex-direction: column
+    flex: 1 1 auto
+    max-width: 100%
+    min-height: 100vh
+    min-height: 100dvh
+    position: relative