From fbc12930b173f6fbbb10e966ffc7bf1dced36e05 Mon Sep 17 00:00:00 2001
From: Cagatay Civici <cagatay.civici@gmail.com>
Date: Sun, 8 Dec 2024 00:18:08 +0300
Subject: [PATCH] Theming doc updates

---
 .../doc/theming/styled/ScopedTokensDoc.vue    |  3 +-
 .../styled/configuration/OptionsDoc.vue       |  2 +-
 .../doc/theming/styled/csslayer/ResetDoc.vue  |  5 +-
 .../styled/csslayer/SpecificityDoc.vue        | 66 ++-----------------
 .../styled/customization/ExtendDoc.vue        | 51 ++++++++------
 .../theming/styled/customization/NoirDoc.vue  |  2 +-
 .../styled/customization/SurfaceDoc.vue       |  2 +-
 apps/showcase/pages/theming/styled/index.vue  | 18 ++---
 8 files changed, 48 insertions(+), 101 deletions(-)

diff --git a/apps/showcase/doc/theming/styled/ScopedTokensDoc.vue b/apps/showcase/doc/theming/styled/ScopedTokensDoc.vue
index f0983a47e..52aa4f074 100644
--- a/apps/showcase/doc/theming/styled/ScopedTokensDoc.vue
+++ b/apps/showcase/doc/theming/styled/ScopedTokensDoc.vue
@@ -1,6 +1,7 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>Design tokens can be scoped to a certain component using CSS variables. In this example, first switch uses the global tokens whereas second one overrides the global with its own tokens.</p>
+        <p>Design tokens can be scoped to a certain component using the <i>dt</i> property. In this example, first switch uses the global tokens whereas second one overrides the global with its own tokens.</p>
+        <p>This approach is recommended over the <i>:deep()</i> as it offers a cleaner API while avoiding the hassle of CSS rule overrides.</p>
     </DocSectionText>
     <div class="card flex justify-center gap-4">
         <ToggleSwitch v-model="checked1" />
diff --git a/apps/showcase/doc/theming/styled/configuration/OptionsDoc.vue b/apps/showcase/doc/theming/styled/configuration/OptionsDoc.vue
index 99064ff17..448876db5 100644
--- a/apps/showcase/doc/theming/styled/configuration/OptionsDoc.vue
+++ b/apps/showcase/doc/theming/styled/configuration/OptionsDoc.vue
@@ -42,7 +42,7 @@ options: {
 options: {
     cssLayer: {
         name: 'primevue',
-        order: 'tailwind-base, primevue, tailwind-utilities'
+        order: 'app-styles, primevue, another-css-library'
     }
 }
 `
diff --git a/apps/showcase/doc/theming/styled/csslayer/ResetDoc.vue b/apps/showcase/doc/theming/styled/csslayer/ResetDoc.vue
index 1997e1771..93cc4570b 100644
--- a/apps/showcase/doc/theming/styled/csslayer/ResetDoc.vue
+++ b/apps/showcase/doc/theming/styled/csslayer/ResetDoc.vue
@@ -1,9 +1,8 @@
 <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.
+            In case PrimeVue components have visual issues in your application, a Reset CSS may be the culprit. CSS layers would be an efficient solution that involves enabling the PrimeVue layer, wrapping the Reset CSS in another layer and defining
+            the layer order. This way, your Reset CSS does not get in the way of PrimeVue components.
         </p>
         <DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz />
     </DocSectionText>
diff --git a/apps/showcase/doc/theming/styled/csslayer/SpecificityDoc.vue b/apps/showcase/doc/theming/styled/csslayer/SpecificityDoc.vue
index 7a424c757..97b4b0cb8 100644
--- a/apps/showcase/doc/theming/styled/csslayer/SpecificityDoc.vue
+++ b/apps/showcase/doc/theming/styled/csslayer/SpecificityDoc.vue
@@ -1,71 +1,13 @@
 <template>
     <DocSectionText v-bind="$attrs">
         <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" 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 require a layer configuration for compatibility that is discussed in the next reset section.
+            The <i>&#64;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" class="doc-link">MDN</a> to begin with.
         </p>
         <p>
-            For example, let's assume you need to remove the rounded borders of the ToggleSwitch component defined by the theme in use. In order to achieve this, <i>.p-toggleswitch .p-toggleswitch-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.
+            The <i>cssLayer</i> is disabled by default, when it 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.
         </p>
-        <div class="card flex justify-center">
-            <ToggleSwitch v-model="checked" :pt="{ slider: 'my-switch-slider', handle: 'my-switch-handle', icon: 'my-switch-icon' }" />
-        </div>
-        <DocSectionCode :code="code" hideToggleCode hideStackBlitz />
         <p>Layers also make it easier to use CSS Modules, view the CSS Modules guide for examples.</p>
     </DocSectionText>
 </template>
-
-<script>
-export default {
-    data() {
-        return {
-            checked: false,
-            code: {
-                basic: `
-<template>
-    <ToggleSwitch v-model="checked" :pt="{ slider: 'my-switch-slider', handle: 'my-switch-handle', icon: 'my-switch-icon' }" />
-</template>
-
-<script>
-import { ref } from "vue";
-
-const checked = ref(false);
-<\/script>
-
-<style>
-.my-switch-slider {
-    border-radius: 0;
-}
-
-.my-switch-handle {
-    border-radius: 0;
-}
-
-.my-switch-icon {
-    display: none !important;
-}
-</style>
-`
-            }
-        };
-    }
-};
-</script>
-
-<style>
-.my-switch-slider {
-    border-radius: 0;
-}
-
-.my-switch-handle {
-    border-radius: 0;
-}
-
-.my-switch-icon {
-    display: none !important;
-}
-</style>
diff --git a/apps/showcase/doc/theming/styled/customization/ExtendDoc.vue b/apps/showcase/doc/theming/styled/customization/ExtendDoc.vue
index 15bddb4f8..99b30809b 100644
--- a/apps/showcase/doc/theming/styled/customization/ExtendDoc.vue
+++ b/apps/showcase/doc/theming/styled/customization/ExtendDoc.vue
@@ -4,10 +4,7 @@
             The theming system can be extended by adding custom design tokens and additional styles. This feature provides a high degree of customization, allowing you to adjust styles according to your needs, as you are not limited to the default
             tokens.
         </p>
-        <p>
-            Use the <i>extend</i> property to add custom tokens along with the <i>css</i> property to utilize them. As an example, let's customize the disabled state of the ToggleSwitch component to add an opacity token, and use the primary color for
-            the handle. By default, there is no opacity option available, and the disabled switch uses a gray handle by design.
-        </p>
+        <p>The example preset configuration adds a new <i>accent</i> button with custom <i>button.accent.color</i> and <i>button.accent.inverse.color</i> tokens. It is also possible to add tokens globally to share them within the components.</p>
     </DocSectionText>
     <DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz />
 </template>
@@ -20,26 +17,40 @@ export default {
                 basic: `
 const MyPreset = definePreset(Aura, {
     components: {
-        toggleswitch: {
+        // custom button tokens and additional style
+        button: {
             extend: {
-                root: {
-                    myDisabledOpacity: '0.7' 
-                },
-                handle: {
-                    myCheckedDisabledBackground: '{primary.color}'
-                } 
+                accent: {
+                    color: '#f59e0b',
+                    inverseColor: '#ffffff'
+                }
             }
-            css: ({ dt }) => \`
-.p-toggleswitch.p-disabled .p-toggleswitch-slider {
-    opacity: \${dt('toggleswitch.my.disabled.opacity')};
-}
-
-.p-toggleswitch.p-disabled .p-toggleswitch-handle {
-    background: \${dt('toggleswitch.my.checked.disabled.background')};
+        css: ({ dt }) => \`
+.p-button-accent {
+    background: \${dt('button.accent.color')};
+    color: \${dt('button.accent.inverse.color')};
+    transition-duration: \${dt('my.transition.fast')};
 }
 \`
-        },
-    }
+        }
+    },
+    // common tokens and styles
+    extend: {
+        my: {
+            transition: {
+                slow: '0.75s'
+                normal: '0.5s'
+                fast: '0.25s'
+            },
+            imageDisplay: 'block' 
+        }
+    },
+    css: ({ dt }) => \`
+        /* Global CSS */
+        img {
+            display: \${dt('my.image.display')};
+        }
+    \`
 });
 `
             }
diff --git a/apps/showcase/doc/theming/styled/customization/NoirDoc.vue b/apps/showcase/doc/theming/styled/customization/NoirDoc.vue
index ecce20656..eb5c0a1c4 100644
--- a/apps/showcase/doc/theming/styled/customization/NoirDoc.vue
+++ b/apps/showcase/doc/theming/styled/customization/NoirDoc.vue
@@ -1,7 +1,7 @@
 <template>
     <DocSectionText v-bind="$attrs">
         <p>
-            The <i>noir</i> mode is the nickname of a variant that uses black tones as the primary and requires and additional <i>colorScheme</i> configuration to implement. A sample preset configuration with black and white variants as the primary
+            The <i>noir</i> mode is the nickname of a variant that uses surface tones as the primary and requires and additional <i>colorScheme</i> configuration to implement. A sample preset configuration with black and white variants as the primary
             color;
         </p>
     </DocSectionText>
diff --git a/apps/showcase/doc/theming/styled/customization/SurfaceDoc.vue b/apps/showcase/doc/theming/styled/customization/SurfaceDoc.vue
index 4fa9367d1..9112b21b4 100644
--- a/apps/showcase/doc/theming/styled/customization/SurfaceDoc.vue
+++ b/apps/showcase/doc/theming/styled/customization/SurfaceDoc.vue
@@ -2,7 +2,7 @@
     <DocSectionText v-bind="$attrs">
         <p>
             The color scheme palette that varies between light and dark modes is specified with the surface tokens. Example below uses <i>zinc</i> for light mode and <i>slategray</i> for dark mode. With this setting, light mode, would have a
-            grayscale tone and dark mode would include blue tone.
+            grayscale tone and dark mode would include bluish tone.
         </p>
     </DocSectionText>
     <DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz />
diff --git a/apps/showcase/pages/theming/styled/index.vue b/apps/showcase/pages/theming/styled/index.vue
index c94d1471d..eb4d33b2f 100755
--- a/apps/showcase/pages/theming/styled/index.vue
+++ b/apps/showcase/pages/theming/styled/index.vue
@@ -9,7 +9,7 @@
             <div class="doc-main">
                 <div class="doc-intro">
                     <h1>Styled Mode</h1>
-                    <p>Choose from a variety of pre-styled themes or develop your own..</p>
+                    <p>Choose from a variety of pre-styled themes or develop your own.</p>
                 </div>
                 <DocSections :docs="docs" />
             </div>
@@ -30,7 +30,6 @@ import ScaleDoc from '@/doc/theming/styled/ScaleDoc.vue';
 import ScopedTokensDoc from '@/doc/theming/styled/ScopedTokensDoc.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';
@@ -113,16 +112,16 @@ export default {
                             label: 'Primary',
                             component: PrimaryDoc
                         },
-                        {
-                            id: 'noir',
-                            label: 'Noir',
-                            component: NoirDoc
-                        },
                         {
                             id: 'surface',
                             label: 'Surface',
                             component: SurfaceDoc
                         },
+                        {
+                            id: 'noir',
+                            label: 'Noir',
+                            component: NoirDoc
+                        },
                         {
                             id: 'font',
                             label: 'Font',
@@ -205,11 +204,6 @@ export default {
                             id: 'reset',
                             label: 'Reset',
                             component: ResetDoc
-                        },
-                        {
-                            id: 'libraries',
-                            label: 'Libraries',
-                            component: LibrariesDoc
                         }
                     ]
                 },