From a4ac76b5da16ae063d0684f1b9b61a83620461bc Mon Sep 17 00:00:00 2001
From: Cagatay Civici <cagatay.civici@gmail.com>
Date: Sun, 31 Mar 2024 16:42:46 +0300
Subject: [PATCH] Add css layer doc

---
 assets/data/news.json                         |  4 +-
 assets/menu/menu.json                         |  4 --
 doc/csslayer/BootstrapDoc.vue                 | 23 -------
 doc/csslayer/NormalizeDoc.vue                 | 23 -------
 doc/csslayer/TailwindDoc.vue                  | 33 ---------
 doc/theming/styled/CSSLayerDoc.vue            | 22 ------
 doc/theming/styled/ColorsDoc.vue              |  4 +-
 doc/theming/styled/csslayer/LibrariesDoc.vue  | 56 +++++++++++++++
 .../styled}/csslayer/ResetDoc.vue             |  0
 .../styled}/csslayer/SpecificityDoc.vue       |  8 +--
 pages/csslayer/index.vue                      | 68 -------------------
 pages/theming/styled/index.vue                | 23 ++++++-
 12 files changed, 85 insertions(+), 183 deletions(-)
 delete mode 100644 doc/csslayer/BootstrapDoc.vue
 delete mode 100644 doc/csslayer/NormalizeDoc.vue
 delete mode 100644 doc/csslayer/TailwindDoc.vue
 delete mode 100644 doc/theming/styled/CSSLayerDoc.vue
 create mode 100644 doc/theming/styled/csslayer/LibrariesDoc.vue
 rename doc/{ => theming/styled}/csslayer/ResetDoc.vue (100%)
 rename doc/{ => theming/styled}/csslayer/SpecificityDoc.vue (70%)
 delete mode 100644 pages/csslayer/index.vue

diff --git a/assets/data/news.json b/assets/data/news.json
index 4f15ee406..65337897b 100644
--- a/assets/data/news.json
+++ b/assets/data/news.json
@@ -1,6 +1,6 @@
 {
     "id": 60,
-    "content": "Introducing the new Styled Mode Theming",
+    "content": "Introducing the all-new Styled Mode",
     "linkText": "Learn More",
-    "linkHref": "http://primevue.org/theming"
+    "linkHref": "http://primevue.org/theming/styled"
 }
diff --git a/assets/menu/menu.json b/assets/menu/menu.json
index 360dc56cc..ebc369ad1 100644
--- a/assets/menu/menu.json
+++ b/assets/menu/menu.json
@@ -47,10 +47,6 @@
                 {
                     "name": "Auto Import",
                     "to": "/autoimport"
-                },
-                {
-                    "name": "CSS Layer",
-                    "to": "/csslayer"
                 }
             ]
         },
diff --git a/doc/csslayer/BootstrapDoc.vue b/doc/csslayer/BootstrapDoc.vue
deleted file mode 100644
index 792b3f45e..000000000
--- a/doc/csslayer/BootstrapDoc.vue
+++ /dev/null
@@ -1,23 +0,0 @@
-<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" hideToggleCode hideStackBlitz />
-    </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/csslayer/NormalizeDoc.vue b/doc/csslayer/NormalizeDoc.vue
deleted file mode 100644
index 644230f57..000000000
--- a/doc/csslayer/NormalizeDoc.vue
+++ /dev/null
@@ -1,23 +0,0 @@
-<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" hideToggleCode hideStackBlitz />
-    </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/csslayer/TailwindDoc.vue b/doc/csslayer/TailwindDoc.vue
deleted file mode 100644
index 21ff2bc95..000000000
--- a/doc/csslayer/TailwindDoc.vue
+++ /dev/null
@@ -1,33 +0,0 @@
-<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" hideToggleCode hideStackBlitz />
-    </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/theming/styled/CSSLayerDoc.vue b/doc/theming/styled/CSSLayerDoc.vue
deleted file mode 100644
index a4c9e2788..000000000
--- a/doc/theming/styled/CSSLayerDoc.vue
+++ /dev/null
@@ -1,22 +0,0 @@
-<template>
-    <DocSectionText v-bind="$attrs">
-        <p>CSS Layer.</p>
-    </DocSectionText>
-    <DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz />
-</template>
-
-<script>
-export default {
-    data() {
-        return {
-            code: {
-                basic: `
-html {
-    font-size: 14px;
-}
-`
-            }
-        };
-    }
-};
-</script>
diff --git a/doc/theming/styled/ColorsDoc.vue b/doc/theming/styled/ColorsDoc.vue
index 278a03546..ebca3a753 100644
--- a/doc/theming/styled/ColorsDoc.vue
+++ b/doc/theming/styled/ColorsDoc.vue
@@ -6,8 +6,8 @@
     </DocSectionText>
     <div class="card">
         <ul class="p-0 m-0 list-none flex sm:flex-column gap-3 flex-wrap sm:flex-nowrap">
-            <li v-for="(color, i) of colors" :key="i" class="flex-auto">
-                <span class="font-medium capitalize w-6rem block mb-2 text-center sm:text-left">{{ color }}</span>
+            <li v-for="(color, i) of colors" :key="i" class="flex-auto" style="min-width: 6rem">
+                <span class="font-medium capitalize block mb-2 text-center sm:text-left">{{ color }}</span>
                 <div class="flex gap-3 flex-auto flex-column sm:flex-row">
                     <div v-for="(shade, j) of shades" :key="shade" class="flex flex-column align-items-center gap-1 flex-1">
                         <div v-tooltip.click.top="'Copied'" class="border-round h-2rem w-full" :style="`background-color: var(--p-${color}-${shades[j]})`" @click="copyColor(`var(--p-${color}-${shades[j]})`)"></div>
diff --git a/doc/theming/styled/csslayer/LibrariesDoc.vue b/doc/theming/styled/csslayer/LibrariesDoc.vue
new file mode 100644
index 000000000..6cca476ae
--- /dev/null
+++ b/doc/theming/styled/csslayer/LibrariesDoc.vue
@@ -0,0 +1,56 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>Example layer configuration for the popular CSS libraries.</p>
+    </DocSectionText>
+    <h4>Bootstrap</h4>
+    <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="code1" hideToggleCode hideStackBlitz />
+
+    <h4>Tailwind</h4>
+    <p>
+        Tailwind CSS includes a reset utility in base called <a href="https://tailwindcss.com/docs/preflight" target="_blank" rel="noopener noreferrer" class="doc-link">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="code2" hideToggleCode hideStackBlitz />
+
+    <h4>Normalize</h4>
+    <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="code3" hideToggleCode hideStackBlitz />
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            code1: {
+                basic: `
+@layer bootstrap-reboot, primevue;
+
+@import "bootstrap-reboot.css" layer(bootstrap-rebooot);
+`
+            },
+            code2: {
+                basic: `
+@layer tailwind-base, primevue, tailwind-utilities;
+
+@layer tailwind-base {
+    @tailwind base;
+}
+
+@layer tailwind-utilities {
+    @tailwind components;
+    @tailwind utilities;
+}
+`
+            },
+            code3: {
+                basic: `
+@layer normalize, primevue;
+
+@import "normalize.css" layer(normalize-reset);
+`
+            }
+        };
+    }
+};
+</script>
diff --git a/doc/csslayer/ResetDoc.vue b/doc/theming/styled/csslayer/ResetDoc.vue
similarity index 100%
rename from doc/csslayer/ResetDoc.vue
rename to doc/theming/styled/csslayer/ResetDoc.vue
diff --git a/doc/csslayer/SpecificityDoc.vue b/doc/theming/styled/csslayer/SpecificityDoc.vue
similarity index 70%
rename from doc/csslayer/SpecificityDoc.vue
rename to doc/theming/styled/csslayer/SpecificityDoc.vue
index e0ab7f535..6690dc4be 100644
--- a/doc/csslayer/SpecificityDoc.vue
+++ b/doc/theming/styled/csslayer/SpecificityDoc.vue
@@ -1,10 +1,10 @@
 <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.
+            <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@layer" class="doc-link">MDN</a> to begin with. In styled mode, when the <i>cssLayer</i> option is enabled at theme configuration, 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. The <i>cssLayer</i> is disabled by default to avoid compatibility issues with 3rd party CSS libraries which requires a layer configuration for compatibility that is discussed in the next reset section.
         </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
@@ -15,7 +15,7 @@
             <InputSwitch v-model="checked" :pt="{ slider: 'my-switch-slider' }" />
         </div>
         <DocSectionCode :code="code" hideToggleCode hideStackBlitz />
-        <p>Layers also make it possible to use CSS Modules, view the <NuxtLink to="/theming/#cssmodules">CSS Modules</NuxtLink> guide for examples.</p>
+        <p>Layers also make it easier to use CSS Modules, view the CSS Modules guide for examples.</p>
     </DocSectionText>
 </template>
 
diff --git a/pages/csslayer/index.vue b/pages/csslayer/index.vue
deleted file mode 100644
index 57c258f98..000000000
--- a/pages/csslayer/index.vue
+++ /dev/null
@@ -1,68 +0,0 @@
-<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/csslayer/BootstrapDoc.vue';
-import NormalizeDoc from '@/doc/csslayer/NormalizeDoc.vue';
-import ResetDoc from '@/doc/csslayer/ResetDoc.vue';
-import SpecificityDoc from '@/doc/csslayer/SpecificityDoc.vue';
-import TailwindDoc from '@/doc/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/theming/styled/index.vue b/pages/theming/styled/index.vue
index 5c46b3131..077cc4937 100755
--- a/pages/theming/styled/index.vue
+++ b/pages/theming/styled/index.vue
@@ -20,7 +20,6 @@
 
 <script>
 import ArchitectureDoc from '@/doc/theming/styled/ArchitectureDoc.vue';
-import CSSLayerDoc from '@/doc/theming/styled/CSSLayerDoc.vue';
 import CSSModulesDoc from '@/doc/theming/styled/CSSModulesDoc.vue';
 import ColorsDoc from '@/doc/theming/styled/ColorsDoc.vue';
 import DarkModeToggleDoc from '@/doc/theming/styled/DarkModeToggleDoc.vue';
@@ -29,6 +28,9 @@ import ScaleDoc from '@/doc/theming/styled/ScaleDoc.vue';
 import ScopedCSSDoc from '@/doc/theming/styled/ScopedCSSDoc.vue';
 import OptionsDoc from '@/doc/theming/styled/configuration/OptionsDoc.vue';
 import ThemeDoc from '@/doc/theming/styled/configuration/ThemeDoc.vue';
+import LibrariesDoc from '@/doc/theming/styled/csslayer/LibrariesDoc.vue';
+import ResetDoc from '@/doc/theming/styled/csslayer/ResetDoc.vue';
+import SpecificityDoc from '@/doc/theming/styled/csslayer/SpecificityDoc.vue';
 import ComponentDoc from '@/doc/theming/styled/customization/ComponentDoc.vue';
 import DefinePresetDoc from '@/doc/theming/styled/customization/DefinePresetDoc.vue';
 import FocusRingDoc from '@/doc/theming/styled/customization/FocusRingDoc.vue';
@@ -163,7 +165,24 @@ export default {
                 {
                     id: 'csslayer',
                     label: 'CSS Layer',
-                    component: CSSLayerDoc
+                    description: 'The PrimeVue CSS layer only applies to styled mode when layering is enabled explicitly at theme configuration, in unstyled mode the built-in CSS classes are not included and as a result no layer is necessary.',
+                    children: [
+                        {
+                            id: 'specificity',
+                            label: 'Specificity',
+                            component: SpecificityDoc
+                        },
+                        {
+                            id: 'reset',
+                            label: 'Reset',
+                            component: ResetDoc
+                        },
+                        {
+                            id: 'libraries',
+                            label: 'Libraries',
+                            component: LibrariesDoc
+                        }
+                    ]
                 },
                 {
                     id: 'scopedcss',