From cf344e915523b59e8ac875b5dd2c8a51828c6c69 Mon Sep 17 00:00:00 2001
From: Cagatay Civici <cagatay.civici@gmail.com>
Date: Thu, 30 May 2024 01:40:50 +0300
Subject: [PATCH] New migration doc

---
 assets/styles/layout/_doc.scss                | 22 +++++++----
 doc/guides/migration/v4/NewFeaturesDoc.vue    |  9 -----
 doc/guides/migration/v4/OverviewDoc.vue       | 16 +++++++-
 .../v4/breakingchanges/ComponentsDoc.vue      | 13 -------
 .../v4/breakingchanges/StyledModeDoc.vue      | 14 -------
 .../migration/v4/changes/BreakingDoc.vue      | 39 +++++++++++++++++++
 .../migration/v4/changes/CompatibleDoc.vue    | 30 ++++++++++++++
 pages/guides/migration/v4/index.vue           | 29 ++++++--------
 8 files changed, 111 insertions(+), 61 deletions(-)
 delete mode 100644 doc/guides/migration/v4/NewFeaturesDoc.vue
 delete mode 100644 doc/guides/migration/v4/breakingchanges/ComponentsDoc.vue
 delete mode 100644 doc/guides/migration/v4/breakingchanges/StyledModeDoc.vue
 create mode 100644 doc/guides/migration/v4/changes/BreakingDoc.vue
 create mode 100644 doc/guides/migration/v4/changes/CompatibleDoc.vue

diff --git a/assets/styles/layout/_doc.scss b/assets/styles/layout/_doc.scss
index ec6cf4360..683902249 100644
--- a/assets/styles/layout/_doc.scss
+++ b/assets/styles/layout/_doc.scss
@@ -1,3 +1,17 @@
+@mixin mark() {
+    border-radius: 6px;
+    padding: 2px 6px;
+    font-size: .875rem;
+    font-weight: 500;
+    font-style: normal;
+    background: var(--mark-background);
+    color: var(--mark-text);
+}
+
+.mark {
+    @include mark();
+}
+
 .doc-tabmenu {
     list-style: none;
     margin: 0;
@@ -132,13 +146,7 @@
         font-size: 1rem;
 
         i {
-            border-radius: 6px;
-            padding: 2px 6px;
-            font-size: .875rem;
-            font-weight: 500;
-            font-style: normal;
-            background: var(--mark-background);
-            color: var(--mark-text);
+            @include mark();
         }
 
         a {
diff --git a/doc/guides/migration/v4/NewFeaturesDoc.vue b/doc/guides/migration/v4/NewFeaturesDoc.vue
deleted file mode 100644
index 75a8eaa80..000000000
--- a/doc/guides/migration/v4/NewFeaturesDoc.vue
+++ /dev/null
@@ -1,9 +0,0 @@
-<template>
-    <DocSectionText v-bind="$attrs">
-        <p>
-            The most notable feature is the new <NuxtLink to="/theming/styled">styled mode</NuxtLink> implementation. Previous iterations use SASS at an external repo called <i>primevue-sass-theme</i> which requires compilation of a
-            <i>theme.css</i> file. This file had to be included in the application and need to be swapped at runtime for basic tasks like dark mode or primary color changes. In v4, styled mode is now part of the core, SASS is not used at all, and a
-            new design token based architecture that fully utilizes CSS variables has been created. The new API is modern and superior to the legacy styled mode.
-        </p>
-    </DocSectionText>
-</template>
diff --git a/doc/guides/migration/v4/OverviewDoc.vue b/doc/guides/migration/v4/OverviewDoc.vue
index 14d0d2219..e0a02a799 100644
--- a/doc/guides/migration/v4/OverviewDoc.vue
+++ b/doc/guides/migration/v4/OverviewDoc.vue
@@ -2,8 +2,22 @@
     <DocSectionText v-bind="$attrs">
         <p>
             At PrimeTek, we have been developing UI component libraries since 2008. The web continues to undergo technological advancements, and as a result, we have to modernize and update our libraries to stay relevant. PrimeVue v4 is the
-            next-generation version that fully embraces modern Web APIs and removes technical debt like the legacy-styled mode. As part of our commitment to our products and the community, PrimeVue v3 will continue to be maintained until the end of
+            next-generation version that fully embraces modern Web APIs and removes technical debt like the legacy-styled mode. Every component has been reviewed and enhanced. As part of our commitment to our products and the community, PrimeVue v3 will continue to be maintained until the end of
             2024.
         </p>
+        <p>
+            The most notable feature is the new <NuxtLink to="/theming/styled">styled mode</NuxtLink> implementation. Previous iterations use SASS at an external repo called <i>primevue-sass-theme</i> which requires compilation of a
+            <i>theme.css</i>a file. This file had to be included in the application and need to be swapped at runtime for basic tasks like dark mode or primary color changes. In v4, styled mode is now part of the core, SASS is not used at all, and a
+            new design token based architecture that fully utilizes CSS variables has been created. The new API is modern and superior to the legacy styled mode.
+        </p>
+        <p>
+            Names of some of the components have been changed to more common alternatives for example, <i>Popover</i> replaced <i>OverlayPanel</i> and <i>InputSwitch</i> is now called <i>ToggleSwitch</i>. Each component has been reviewed for a
+            consistent naming between CSS class names and PT sections. An example would be the <i>option</i> element of a Select component that uses <i>p-select-option</i> for the class name.
+        </p>
+        <p>
+            Components have been utilized more within other components, for instance Dialog close button is not actually a PrimeVue button so that <i>closeButtonProps</i> can be used to enable the features of button like outlined, raised and more.
+            Whenever a component is using another component, in v3 the pt sections were causing confusion, to prevent this <i>pc</i> prefix is added to indicate that the PT section is actually a PrimeVue component, not a simple DOM element. This is
+            especially useful because PT allows passing arbitrary attributes to DOM elements whereas if the element is actually a PrimeVue component, <i>props</i> can also be passed.
+        </p>
     </DocSectionText>
 </template>
diff --git a/doc/guides/migration/v4/breakingchanges/ComponentsDoc.vue b/doc/guides/migration/v4/breakingchanges/ComponentsDoc.vue
deleted file mode 100644
index 87f8aec7b..000000000
--- a/doc/guides/migration/v4/breakingchanges/ComponentsDoc.vue
+++ /dev/null
@@ -1,13 +0,0 @@
-<template>
-    <DocSectionText v-bind="$attrs">
-        <p>The team has put in a great effort to migrate the entire UI suite with minor breaking changes. Two components have been removed by design.</p>
-    </DocSectionText>
-    <ul class="flex flex-col gap-2">
-        <li><i>DataViewLayoutOptions</i> is removed, use SelectButton instead as in the demo.</li>
-        <li><i>TriStateCheckbox</i> is removed, use Checkbox with the new <i>indeterminate</i> state as a replacement.</li>
-        <li>
-            Enhancements to internal structure of some components, see the tickets <a href="https://github.com/primefaces/primevue/issues/5426" target="_blank" rel="noopener noreferrer" class="doc-link">#5426</a> and
-            <a href="https://github.com/primefaces/primevue/issues/5437" target="_blank" rel="noopener noreferrer" class="doc-link">#5437</a> for more information.
-        </li>
-    </ul>
-</template>
diff --git a/doc/guides/migration/v4/breakingchanges/StyledModeDoc.vue b/doc/guides/migration/v4/breakingchanges/StyledModeDoc.vue
deleted file mode 100644
index 1971a6dbb..000000000
--- a/doc/guides/migration/v4/breakingchanges/StyledModeDoc.vue
+++ /dev/null
@@ -1,14 +0,0 @@
-<template>
-    <DocSectionText v-bind="$attrs">
-        <p>
-            The styled mode theming has been reimplemented from scratch based on an all-new architecture. There is no theme.css involved, so you need to migrate to the API. Currently, Aura is the only available built-in preset; however, by v4 final,
-            two more presets named Lara and Nora would be included, as well as the Material Design theme. If you had a custom theme for v3, the theme needs to be recreated using the new APIs. See the customization section at
-            <NuxtLink to="/theming/styled">styled mode</NuxtLink> for details.
-        </p>
-    </DocSectionText>
-    <ul class="flex flex-col gap-2">
-        <li>Files under <i>primevue/resources</i> such as the themes, migration to new styled mode is necessary.</li>
-        <li><i>switchTheme</i> function, use the new APIs like <i>usePreset</i> instead to dynamic theme switching.</li>
-        <li>The legacy Tailwind preset at <i>primevue/passthrough/tailwind</i>, migrate to the <a href="https://tailwind.primevue.org" target="_blank" rel="noopener noreferrer" class="doc-link">Tailwind Presets</a> project.</li>
-    </ul>
-</template>
diff --git a/doc/guides/migration/v4/changes/BreakingDoc.vue b/doc/guides/migration/v4/changes/BreakingDoc.vue
new file mode 100644
index 000000000..aeb706e6c
--- /dev/null
+++ b/doc/guides/migration/v4/changes/BreakingDoc.vue
@@ -0,0 +1,39 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <h4>SASS Themes</h4>
+        <p>
+            The styled mode theming has been reimplemented from scratch based on an all-new architecture. The <i>theme.css</i> and the <i>primevue/resources</i> do not exist anymore, so any imports of these assets needs to be removed. Currently, Aura
+            is the only available built-in preset; however, by v4 final, two more presets named Lara and Nora would be included, as well as the Material Design theme. If you had a custom theme for v3, the theme needs to be recreated using the new
+            APIs. See the customization section at <NuxtLink to="/theming/styled">styled mode</NuxtLink> for details.
+        </p>
+        <h4>Removed Components</h4>
+        <ul class="flex flex-col gap-2 leading-normal">
+            <li><i class="mark">TriStateCheckbox</i> | Use Checkbox with indeterminate option.</li>
+            <li><i class="mark">DataViewLayoutOptions</i> | Use SelectButton instead.</li>
+        </ul>
+
+        <h4>Removed APIs</h4>
+        <ul class="flex flex-col gap-2 leading-normal">
+            <li><i class="mark">switchTheme</i> function, use the new APIs like <i class="mark">usePreset</i> instead to dynamic theme switching.</li>
+        </ul>
+
+        <h4>Removed Files</h4>
+        <ul class="flex flex-col gap-2 leading-normal">
+            <li>Themes under the <i class="mark">primevue/resources</i> path, migration to new styled mode is necessary.</li>
+            <li>The legacy Tailwind preset at <i class="mark">primevue/passthrough/tailwind</i>, migrate to the <a href="https://tailwind.primevue.org" target="_blank" rel="noopener noreferrer" class="doc-link">Tailwind Presets</a> project.</li>
+        </ul>
+
+        <h4>PT Section Names</h4>
+        <p>
+            The experimental PassThrough feature is not production ready, there are changes on the PT section names due to alignment with CSS classes for certain components. If when component element is another PrimeVue component <i>pc</i> prefix is
+            added for indication. Review the <i>Pass Through</i> section of a component for the new API. The Tailwind CSS presets for the unstyled mode are not updated to v4 yet.
+        </p>
+
+        <h4>Removed Features</h4>
+        <ul class="flex flex-col gap-2 leading-normal">
+            <li>Sidebar/Drawer <i>size</i> property is removed, use a responsive class utilty as replacement, demos have new examples.</li>
+            <li>Rating <i>cancel</i> prop is removed as toggling the selected star value clears it.</li>
+            <li>Inplace <i>closable</i> is removed in favor of templating and <i>closeCallback</i> prop.</li>
+        </ul>
+    </DocSectionText>
+</template>
diff --git a/doc/guides/migration/v4/changes/CompatibleDoc.vue b/doc/guides/migration/v4/changes/CompatibleDoc.vue
new file mode 100644
index 000000000..2aa4c0dea
--- /dev/null
+++ b/doc/guides/migration/v4/changes/CompatibleDoc.vue
@@ -0,0 +1,30 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <h4>Renamed Components</h4>
+        <p>Old names are deprecated but still functional, migrate to new import paths instead e.g. <i>primevue/calendar</i> becomes <i>primevue/datepicker</i>.</p>
+        <ul class="flex flex-col gap-2 leading-normal">
+            <li><i class="mark">Calendar</i> -> <i class="mark">DatePicker</i>.</li>
+            <li><i class="mark">Dropdown</i> -> <i class="mark">Select</i>.</li>
+            <li><i class="mark">InputSwitch</i> -> <i class="mark">ToggleSwitch</i>.</li>
+            <li><i class="mark">OverlayPanel</i> -> <i class="mark">Popover</i>.</li>
+            <li><i class="mark">Sidebar</i> -> <i class="mark">Drawer</i>.</li>
+        </ul>
+
+        <h4>Obsolete Components</h4>
+        <p>Components that are deprecated because of their functionality being provided by other components.</p>
+        <ul class="flex flex-col gap-2 leading-normal">
+            <li><i class="mark">Chips</i> | Use AutoComplete with <i class="mark">multiple</i> enabled and <i class="mark">typeahead</i> disabled.</li>
+            <li><i class="mark">TabMenu</i> | Use Tabs without panels.</li>
+            <li><i class="mark">BadgeDirective</i> | Use OverlayBadge instead.</li>
+            <li><i class="mark">TabView</i> | Use the new Tabs components.</li>
+            <li><i class="mark">Accordion</i> | Use with the new <i>AccordionHeader</i> and <i>AccordionContent</i> components.</li>
+        </ul>
+
+        <h4>Important Tickets</h4>
+        <p>Issue tickets with detailed information about component internal changes.</p>
+        <ul class="flex flex-col gap-2 leading-normal">
+            <li><a href="https://github.com/primefaces/primevue/issues/5426" target="_blank" rel="noopener noreferrer" class="doc-link">#5426</a></li>
+            <li><a href="https://github.com/primefaces/primevue/issues/5437" target="_blank" rel="noopener noreferrer" class="doc-link">#5437</a></li>
+        </ul>
+    </DocSectionText>
+</template>
diff --git a/pages/guides/migration/v4/index.vue b/pages/guides/migration/v4/index.vue
index 7adb35e82..2539cb995 100644
--- a/pages/guides/migration/v4/index.vue
+++ b/pages/guides/migration/v4/index.vue
@@ -6,7 +6,7 @@
     <div class="doc">
         <div class="doc-main">
             <div class="doc-intro">
-                <h1>Introduction</h1>
+                <h1>Migration</h1>
                 <p>Migration guide to PrimeVue v4.</p>
             </div>
             <DocSections :docs="docs" />
@@ -16,10 +16,9 @@
 </template>
 
 <script>
-import NewFeaturesDoc from '@/doc/guides/migration/v4/NewFeaturesDoc.vue';
 import OverviewDoc from '@/doc/guides/migration/v4/OverviewDoc.vue';
-import ComponentsDoc from '@/doc/guides/migration/v4/breakingchanges/ComponentsDoc.vue';
-import StyledModeDoc from '@/doc/guides/migration/v4/breakingchanges/StyledModeDoc.vue';
+import BreakingDoc from '@/doc/guides/migration/v4/changes/BreakingDoc.vue';
+import CompatibleDoc from '@/doc/guides/migration/v4/changes/CompatibleDoc.vue';
 
 export default {
     data() {
@@ -31,23 +30,19 @@ export default {
                     component: OverviewDoc
                 },
                 {
-                    id: 'newfeatures',
-                    label: 'New Features',
-                    component: NewFeaturesDoc
-                },
-                {
-                    id: 'breakingchanges',
-                    label: 'Breaking Changes',
+                    id: 'changes',
+                    label: 'Changes',
+                    description: 'The list of backward compatible and breaking changes.',
                     children: [
                         {
-                            id: 'styledmode',
-                            label: 'Styled Mode',
-                            component: StyledModeDoc
+                            id: 'compatible',
+                            label: 'Compatible',
+                            component: CompatibleDoc
                         },
                         {
-                            id: 'components',
-                            label: 'Components',
-                            component: ComponentsDoc
+                            id: 'breaking',
+                            label: 'Breaking',
+                            component: BreakingDoc
                         }
                     ]
                 }