From bd71b03f64fd89557fe8573db5ed8f7e3e3d4863 Mon Sep 17 00:00:00 2001
From: Cagatay Civici <cagatay.civici@gmail.com>
Date: Tue, 26 Dec 2023 11:13:55 +0300
Subject: [PATCH] Add CSS layer docs

---
 assets/menu/menu.json                         | 41 ++++++-----
 doc/{ => guides}/accessibility/ColorsDoc.vue  |  0
 .../accessibility/FormControlsDoc.vue         |  0
 .../accessibility/IntroductionDoc.vue         |  0
 .../accessibility/SemanticHTMLDoc.vue         |  0
 doc/{ => guides}/accessibility/WAIAriaDoc.vue |  0
 doc/{ => guides}/accessibility/WCAGDoc.vue    |  0
 doc/guides/csslayer/BootstrapDoc.vue          | 23 +++++++
 doc/guides/csslayer/NormalizeDoc.vue          | 23 +++++++
 doc/guides/csslayer/ResetDoc.vue              | 45 ++++++++++++
 doc/guides/csslayer/SpecificityDoc.vue        | 63 +++++++++++++++++
 doc/guides/csslayer/TailwindDoc.vue           | 33 +++++++++
 doc/installation/StyledModeDoc.vue            | 24 ++++++-
 doc/nuxt/configuration/CSSLayerOrderDoc.vue   |  2 +-
 pages/{ => guides}/accessibility/index.vue    | 12 ++--
 pages/guides/csslayer/index.vue               | 68 +++++++++++++++++++
 pages/roadmap/index.vue                       | 12 +++-
 17 files changed, 318 insertions(+), 28 deletions(-)
 rename doc/{ => guides}/accessibility/ColorsDoc.vue (100%)
 rename doc/{ => guides}/accessibility/FormControlsDoc.vue (100%)
 rename doc/{ => guides}/accessibility/IntroductionDoc.vue (100%)
 rename doc/{ => guides}/accessibility/SemanticHTMLDoc.vue (100%)
 rename doc/{ => guides}/accessibility/WAIAriaDoc.vue (100%)
 rename doc/{ => guides}/accessibility/WCAGDoc.vue (100%)
 create mode 100644 doc/guides/csslayer/BootstrapDoc.vue
 create mode 100644 doc/guides/csslayer/NormalizeDoc.vue
 create mode 100644 doc/guides/csslayer/ResetDoc.vue
 create mode 100644 doc/guides/csslayer/SpecificityDoc.vue
 create mode 100644 doc/guides/csslayer/TailwindDoc.vue
 rename pages/{ => guides}/accessibility/index.vue (80%)
 create mode 100644 pages/guides/csslayer/index.vue

diff --git a/assets/menu/menu.json b/assets/menu/menu.json
index 747343581..f597c2e68 100644
--- a/assets/menu/menu.json
+++ b/assets/menu/menu.json
@@ -14,13 +14,11 @@
                 },
                 {
                     "name": "Nuxt",
-                    "to": "/nuxt",
-                    "badge": "NEW"
+                    "to": "/nuxt"
                 },
                 {
                     "name": "Playground",
-                    "to": "/playground",
-                    "badge": "NEW"
+                    "to": "/playground"
                 }
             ]
         },
@@ -522,14 +520,23 @@
             "href": "https://blocks.primevue.org"
         },
         {
-            "name": "PrimeFlex CSS",
-            "icon": "pi pi-table",
-            "href": "https://primeflex.org"
-        },
-        {
-            "name": "Accessibility",
-            "icon": "pi pi-users",
-            "to": "/accessibility"
+            "name": "Guides",
+            "icon": "pi pi-book",
+            "children": [
+                {
+                    "name": "Accessibility",
+                    "to": "/guides/accessibility"
+                },
+                {
+                    "name": "CSS Layer",
+                    "to": "/guides/csslayer"
+                },
+                {
+                    "name": "PrimeTV",
+                    "icon": "pi pi-youtube",
+                    "href": "https://www.youtube.com/channel/UCTgmp69aBOlLnPEqlUyetWw"
+                }
+            ]
         },
         {
             "name": "Support",
@@ -549,11 +556,6 @@
                 }
             ]
         },
-        {
-            "name": "PrimeTV",
-            "icon": "pi pi-youtube",
-            "href": "https://www.youtube.com/channel/UCTgmp69aBOlLnPEqlUyetWw"
-        },
         {
             "name": "Discover",
             "icon": "pi pi-search",
@@ -589,6 +591,11 @@
                 {
                     "name": "PrimeGear",
                     "href": "https://gear.primefaces.org"
+                },
+                {
+                    "name": "PrimeFlex CSS",
+                    "icon": "pi pi-table",
+                    "href": "https://primeflex.org"
                 }
             ]
         }
diff --git a/doc/accessibility/ColorsDoc.vue b/doc/guides/accessibility/ColorsDoc.vue
similarity index 100%
rename from doc/accessibility/ColorsDoc.vue
rename to doc/guides/accessibility/ColorsDoc.vue
diff --git a/doc/accessibility/FormControlsDoc.vue b/doc/guides/accessibility/FormControlsDoc.vue
similarity index 100%
rename from doc/accessibility/FormControlsDoc.vue
rename to doc/guides/accessibility/FormControlsDoc.vue
diff --git a/doc/accessibility/IntroductionDoc.vue b/doc/guides/accessibility/IntroductionDoc.vue
similarity index 100%
rename from doc/accessibility/IntroductionDoc.vue
rename to doc/guides/accessibility/IntroductionDoc.vue
diff --git a/doc/accessibility/SemanticHTMLDoc.vue b/doc/guides/accessibility/SemanticHTMLDoc.vue
similarity index 100%
rename from doc/accessibility/SemanticHTMLDoc.vue
rename to doc/guides/accessibility/SemanticHTMLDoc.vue
diff --git a/doc/accessibility/WAIAriaDoc.vue b/doc/guides/accessibility/WAIAriaDoc.vue
similarity index 100%
rename from doc/accessibility/WAIAriaDoc.vue
rename to doc/guides/accessibility/WAIAriaDoc.vue
diff --git a/doc/accessibility/WCAGDoc.vue b/doc/guides/accessibility/WCAGDoc.vue
similarity index 100%
rename from doc/accessibility/WCAGDoc.vue
rename to doc/guides/accessibility/WCAGDoc.vue
diff --git a/doc/guides/csslayer/BootstrapDoc.vue b/doc/guides/csslayer/BootstrapDoc.vue
new file mode 100644
index 000000000..58c76a568
--- /dev/null
+++ b/doc/guides/csslayer/BootstrapDoc.vue
@@ -0,0 +1,23 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>Bootstrap has a <i>reboot</i> utility to reset the CSS of the standard elements. If you are including this utility, you may give it a layer while importing it.</p>
+        <DocSectionCode :code="code" />
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+@layer bootstrap-reboot, primevue;
+
+@import "bootstrap-reboot.css" layer(bootstrap-rebooot);
+`
+            }
+        };
+    }
+};
+</script>
diff --git a/doc/guides/csslayer/NormalizeDoc.vue b/doc/guides/csslayer/NormalizeDoc.vue
new file mode 100644
index 000000000..d158c8505
--- /dev/null
+++ b/doc/guides/csslayer/NormalizeDoc.vue
@@ -0,0 +1,23 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>Normalize is another utility to reset CSS of the standard elements. While importing the CSS file, assign it to a layer and define the layer order with primevue coming after the normalized layer.</p>
+        <DocSectionCode :code="code" />
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+@layer normalize, primevue;
+
+@import "normalize.css" layer(normalize-reset);
+`
+            }
+        };
+    }
+};
+</script>
diff --git a/doc/guides/csslayer/ResetDoc.vue b/doc/guides/csslayer/ResetDoc.vue
new file mode 100644
index 000000000..8026d6a1e
--- /dev/null
+++ b/doc/guides/csslayer/ResetDoc.vue
@@ -0,0 +1,45 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>
+            Ease of customization may present an issue if you have global styles on HTML elements like inputs and buttons that are also utilized by PrimeVue because global styles with a broader scope e.g. <i>button { }</i> and no layer always
+            override the PrimeVue components leading to unexpected results. A common use case for global styles applying to standard HTML elements is CSS reset utilities to remove the default styling of the browsers. In this case, best practice is
+            wrapping your CSS in a layer like <i>reset</i> and make sure <i>primevue</i> comes after your layer since layers defined after has higher precedence. This way, your Reset CSS does not get in the way of PrimeVue components.
+        </p>
+        <DocSectionCode :code="code" />
+        <p>If you are using Nuxt, use the built-in <i>cssLayerOrder</i> property of the PrimeVue nuxt module instead.</p>
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+/* Order */
+@layer reset, primevue;
+
+/* Reset CSS */
+@layer reset {
+    button,
+    input {
+        /* CSS to Reset */
+    }
+}
+`
+            }
+        };
+    }
+};
+</script>
+
+<style>
+.my-switch-slider {
+    border-radius: 0;
+}
+
+.my-switch-slider:before {
+    border-radius: 0;
+}
+</style>
diff --git a/doc/guides/csslayer/SpecificityDoc.vue b/doc/guides/csslayer/SpecificityDoc.vue
new file mode 100644
index 000000000..aa343cf39
--- /dev/null
+++ b/doc/guides/csslayer/SpecificityDoc.vue
@@ -0,0 +1,63 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p class="notification">A CSS layer is utilized in styled mode only, in unstyled mode the built-in CSS classes are not included and as a result no layer is defined. This documentation only applies to styled mode.</p>
+        <p>
+            The <i>@layer</i> is a standard CSS feature to define cascade layers for a customizable order of precedence. If you need to become more familiar with layers, visit the documentation at
+            <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@layer">MDN</a> to begin with. In styled mode, PrimeVue wraps the built-in style classes under the <i>primevue</i> cascade layer to make the library styles easy to override. CSS in
+            your app without a layer has the highest CSS specificity, so you'll be able to override styles regardless of the location or how strong a class is written.
+        </p>
+        <p>
+            For example, let's assume you need to remove the rounded borders of the InputSwitch component defined by the theme in use. In order to achieve this, <i>.p-inputswitch .p-inputswitch-slider</i> selector needs to be overriden. Without the
+            layers, we'd have to write a stronger css or use <i>!important</i> however, with layers, this does not present an issue as your CSS can always override PrimeVue with a more straightforward class name such as <i>my-switch-slider</i>.
+            Another advantage of this approach is that it does not force you to figure out the built-in class names of the components.
+        </p>
+        <div class="card flex justify-content-center">
+            <InputSwitch v-model="checked" :pt="{ slider: 'my-switch-slider' }" />
+        </div>
+        <DocSectionCode :code="code" />
+        <p>Layers also make it possible to use CSS Modules, view the <NuxtLink to="/theming/#cssmodules">CSS Modules</NuxtLink> guide for examples.</p>
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+<template>
+    <InputSwitch v-model="checked" :pt="{ slider: 'my-switch-slider' }" />
+</template>
+
+<script>
+import { ref } from "vue";
+
+const checked = ref(false);
+<\/script>
+
+<style>
+.my-switch-slider {
+    border-radius: 0;
+}
+
+.my-switch-slider:before {
+    border-radius: 0;
+}
+</style>
+`
+            }
+        };
+    }
+};
+</script>
+
+<style>
+.my-switch-slider {
+    border-radius: 0;
+}
+
+.my-switch-slider:before {
+    border-radius: 0;
+}
+</style>
diff --git a/doc/guides/csslayer/TailwindDoc.vue b/doc/guides/csslayer/TailwindDoc.vue
new file mode 100644
index 000000000..dda77ddf2
--- /dev/null
+++ b/doc/guides/csslayer/TailwindDoc.vue
@@ -0,0 +1,33 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>
+            Tailwind CSS includes a reset utility in base called <a href="https://tailwindcss.com/docs/preflight" target="_blank" rel="noopener noreferrer">preflight</a>. If you are using this feature, wrap the base and utilities in separate layers
+            and make sure primevue layer comes after the base.
+        </p>
+        <DocSectionCode :code="code" />
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+@layer tailwind-base, primevue, tailwind-utilities;
+
+@layer tailwind-base {
+  @tailwind base;
+}
+
+@layer tailwind-utilities {
+  @tailwind components;
+  @tailwind utilities;
+}
+`
+            }
+        };
+    }
+};
+</script>
diff --git a/doc/installation/StyledModeDoc.vue b/doc/installation/StyledModeDoc.vue
index d87b40aae..49c9af453 100644
--- a/doc/installation/StyledModeDoc.vue
+++ b/doc/installation/StyledModeDoc.vue
@@ -4,7 +4,13 @@
             Styled mode is based on pre-skinned components with opinionated themes like Material, Bootstrap or PrimeOne themes. Theme is the required css file to be imported, visit the
             <NuxtLink to="/theming/#themes">Themes</NuxtLink> section for the complete list of available themes to choose from.
         </p>
-        <DocSectionCode :code="code" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
+        <DocSectionCode :code="code1" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
+        <p>
+            The classes of PrimeVue is defined under the <i>primevue</i> CSS layer to be easier to customize by having low specificity. If you are using a CSS library that styles default HTML elements such as Tailwind Preflight, Bootstrap, Normalize
+            or similar a custom CSS layer configuration might be necessary. Note that this only applies to Styled Mode as Unstyled Mode does not use any default styles or layers. Here is an example with Tailwind, visit the
+            <NuxtLink to="/guides/csslayer">CSS Layer</NuxtLink> for more information.
+        </p>
+        <DocSectionCode :code="code2" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
     </DocSectionText>
 </template>
 
@@ -12,8 +18,22 @@
 export default {
     data() {
         return {
-            code: {
+            code1: {
                 basic: "\nimport 'primevue/resources/themes/lara-light-green/theme.css'\n"
+            },
+            code2: {
+                basic: `
+@layer tailwind-base, primereact, tailwind-utilities;
+
+@layer tailwind-base {
+  @tailwind base;
+}
+
+@layer tailwind-utilities {
+  @tailwind components;
+  @tailwind utilities;
+}
+`
             }
         };
     }
diff --git a/doc/nuxt/configuration/CSSLayerOrderDoc.vue b/doc/nuxt/configuration/CSSLayerOrderDoc.vue
index 4d1b81a57..240c10431 100644
--- a/doc/nuxt/configuration/CSSLayerOrderDoc.vue
+++ b/doc/nuxt/configuration/CSSLayerOrderDoc.vue
@@ -1,6 +1,6 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>Defines the CSS layer order setting for compatibility with libraries like Tailwind.</p>
+        <p>Defines the CSS layer order setting for compatibility with libraries like Tailwind and Bootstrap in styled mode. Visit the <NuxtLink to="/guides/csslayer">CSS Layer</NuxtLink> guide for detailed information.</p>
     </DocSectionText>
     <DocSectionCode :code="code1" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
     <DocSectionCode :code="code2" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
diff --git a/pages/accessibility/index.vue b/pages/guides/accessibility/index.vue
similarity index 80%
rename from pages/accessibility/index.vue
rename to pages/guides/accessibility/index.vue
index 4368e620d..2eac2d9ef 100644
--- a/pages/accessibility/index.vue
+++ b/pages/guides/accessibility/index.vue
@@ -19,12 +19,12 @@
 </template>
 
 <script>
-import ColorsDoc from '@/doc/accessibility/ColorsDoc.vue';
-import FormControlsDoc from '@/doc/accessibility/FormControlsDoc.vue';
-import IntroductionDoc from '@/doc/accessibility/IntroductionDoc.vue';
-import SemanticHTMLDoc from '@/doc/accessibility/SemanticHTMLDoc.vue';
-import WAIAriaDoc from '@/doc/accessibility/WAIAriaDoc.vue';
-import WCAGDoc from '@/doc/accessibility/WCAGDoc.vue';
+import ColorsDoc from '@/doc/guides/accessibility/ColorsDoc.vue';
+import FormControlsDoc from '@/doc/guides/accessibility/FormControlsDoc.vue';
+import IntroductionDoc from '@/doc/guides/accessibility/IntroductionDoc.vue';
+import SemanticHTMLDoc from '@/doc/guides/accessibility/SemanticHTMLDoc.vue';
+import WAIAriaDoc from '@/doc/guides/accessibility/WAIAriaDoc.vue';
+import WCAGDoc from '@/doc/guides/accessibility/WCAGDoc.vue';
 
 export default {
     data() {
diff --git a/pages/guides/csslayer/index.vue b/pages/guides/csslayer/index.vue
new file mode 100644
index 000000000..0c19b13fd
--- /dev/null
+++ b/pages/guides/csslayer/index.vue
@@ -0,0 +1,68 @@
+<template>
+    <div>
+        <Head>
+            <Title>CSS Layer - PrimeVue</Title>
+            <Meta name="description" content="Best practices for the PrimeVue cascade layer in styled mode." />
+        </Head>
+
+        <div class="doc">
+            <div class="doc-main">
+                <div class="doc-intro">
+                    <h1>CSS Layer</h1>
+                    <p>Best practices for the PrimeVue cascade layer in styled mode.</p>
+                </div>
+                <DocSections :docs="docs" />
+            </div>
+            <DocSectionNav :docs="docs" />
+        </div>
+    </div>
+</template>
+
+<script>
+import BootstrapDoc from '@/doc/guides/csslayer/BootstrapDoc.vue';
+import NormalizeDoc from '@/doc/guides/csslayer/NormalizeDoc.vue';
+import ResetDoc from '@/doc/guides/csslayer/ResetDoc.vue';
+import SpecificityDoc from '@/doc/guides/csslayer/SpecificityDoc.vue';
+import TailwindDoc from '@/doc/guides/csslayer/TailwindDoc.vue';
+
+export default {
+    data() {
+        return {
+            docs: [
+                {
+                    id: 'css-specificity',
+                    label: 'CSS Specificity',
+                    component: SpecificityDoc
+                },
+                {
+                    id: 'reset',
+                    label: 'Reset',
+                    component: ResetDoc
+                },
+                {
+                    id: 'libraries',
+                    label: 'Libraries',
+                    description: 'Compatibility between PrimeVue and CSS libraries.',
+                    children: [
+                        {
+                            id: 'tailwind',
+                            label: 'Tailwind CSS',
+                            component: TailwindDoc
+                        },
+                        {
+                            id: 'bootstrap',
+                            label: 'Bootstrap',
+                            component: BootstrapDoc
+                        },
+                        {
+                            id: 'normalize',
+                            label: 'Normalize',
+                            component: NormalizeDoc
+                        }
+                    ]
+                }
+            ]
+        };
+    }
+};
+</script>
diff --git a/pages/roadmap/index.vue b/pages/roadmap/index.vue
index f075ad043..f6da98c82 100644
--- a/pages/roadmap/index.vue
+++ b/pages/roadmap/index.vue
@@ -165,8 +165,16 @@
                         <div class="flex-1 flex gap-3 flex-column"></div>
                     </div>
                     <div class="flex gap-3 border-bottom-1 surface-border pb-3">
-                        <div class="flex-shrink-0 p-3 bg-pink-500 text-white border-round font-bold text-lg flex align-items-center justify-content-center w-14rem">Designer</div>
-                        <div class="flex-1 flex gap-3 flex-column"></div>
+                        <div class="flex-shrink-0 p-3 bg-pink-500 text-white border-round font-bold text-lg flex align-items-center justify-content-center w-14rem">Design</div>
+                        <div class="flex-1 flex gap-3 flex-column">
+                            <div class="p-3 surface-card border-round border-pink-500" style="border-left: 6px solid">
+                                <h2 class="text-lg font-bold mt-0 mb-2">New UI Theme</h2>
+                                <p class="mt-0 mb-3 line-height-3">Brand new default theme with a modern and attractive design.</p>
+                                <div class="surface-200 border-round">
+                                    <div class="bg-pink-500 border-round" style="width: 0%; height: 4px"></div>
+                                </div>
+                            </div>
+                        </div>
                         <div class="flex-1 flex gap-3 flex-column">
                             <div class="p-3 surface-card border-round border-pink-500" style="border-left: 6px solid">
                                 <h2 class="text-lg font-bold mt-0 mb-2">New UI Based Theme Editor</h2>