From 9a3fdf3c394eaea29e4fbceb660d9f56655a1337 Mon Sep 17 00:00:00 2001
From: Cagatay Civici <cagatay.civici@gmail.com>
Date: Mon, 1 Apr 2024 10:43:18 +0300
Subject: [PATCH] Initiate migration guide

---
 assets/menu/menu.json                         |  5 ++
 doc/migration/v4/NewFeaturesDoc.vue           |  9 +++
 doc/migration/v4/OverviewDoc.vue              |  9 +++
 .../v4/breakingchanges/ComponentsDoc.vue      | 13 +++++
 .../v4/breakingchanges/StyledModeDoc.vue      | 14 +++++
 pages/migration/v4/index.vue                  | 58 +++++++++++++++++++
 6 files changed, 108 insertions(+)
 create mode 100644 doc/migration/v4/NewFeaturesDoc.vue
 create mode 100644 doc/migration/v4/OverviewDoc.vue
 create mode 100644 doc/migration/v4/breakingchanges/ComponentsDoc.vue
 create mode 100644 doc/migration/v4/breakingchanges/StyledModeDoc.vue
 create mode 100644 pages/migration/v4/index.vue

diff --git a/assets/menu/menu.json b/assets/menu/menu.json
index 8eafb8a4f..daedff1b4 100644
--- a/assets/menu/menu.json
+++ b/assets/menu/menu.json
@@ -18,6 +18,11 @@
                 }
             ]
         },
+        {
+            "name": "Migration to V4",
+            "icon": "pi pi-sync",
+            "to": "/migration/v4"
+        },
         {
             "name": "Installation",
             "icon": "pi pi-cloud-download",
diff --git a/doc/migration/v4/NewFeaturesDoc.vue b/doc/migration/v4/NewFeaturesDoc.vue
new file mode 100644
index 000000000..75a8eaa80
--- /dev/null
+++ b/doc/migration/v4/NewFeaturesDoc.vue
@@ -0,0 +1,9 @@
+<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/migration/v4/OverviewDoc.vue b/doc/migration/v4/OverviewDoc.vue
new file mode 100644
index 000000000..14d0d2219
--- /dev/null
+++ b/doc/migration/v4/OverviewDoc.vue
@@ -0,0 +1,9 @@
+<template>
+    <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
+            2024.
+        </p>
+    </DocSectionText>
+</template>
diff --git a/doc/migration/v4/breakingchanges/ComponentsDoc.vue b/doc/migration/v4/breakingchanges/ComponentsDoc.vue
new file mode 100644
index 000000000..57ee08b37
--- /dev/null
+++ b/doc/migration/v4/breakingchanges/ComponentsDoc.vue
@@ -0,0 +1,13 @@
+<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-column 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://tailwind.primevue.org" target="_blank" rel="noopener noreferrer" class="doc-link">#5426</a> and
+            <a href="https://tailwind.primevue.org" target="_blank" rel="noopener noreferrer" class="doc-link">#5437</a> for more information.
+        </li>
+    </ul>
+</template>
diff --git a/doc/migration/v4/breakingchanges/StyledModeDoc.vue b/doc/migration/v4/breakingchanges/StyledModeDoc.vue
new file mode 100644
index 000000000..261923a67
--- /dev/null
+++ b/doc/migration/v4/breakingchanges/StyledModeDoc.vue
@@ -0,0 +1,14 @@
+<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-column 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/pages/migration/v4/index.vue b/pages/migration/v4/index.vue
new file mode 100644
index 000000000..1a76404f6
--- /dev/null
+++ b/pages/migration/v4/index.vue
@@ -0,0 +1,58 @@
+<template>
+    <Head>
+        <Title>Migration - PrimeVue</Title>
+        <Meta name="description" content="Migration Guide to PrimeVue v4." />
+    </Head>
+    <div class="doc">
+        <div class="doc-main">
+            <div class="doc-intro">
+                <h1>Introduction</h1>
+                <p>Migration guide to PrimeVue v4.</p>
+            </div>
+            <DocSections :docs="docs" />
+        </div>
+        <DocSectionNav :docs="docs" />
+    </div>
+</template>
+
+<script>
+import NewFeaturesDoc from '@/doc/migration/v4/NewFeaturesDoc.vue';
+import OverviewDoc from '@/doc/migration/v4/OverviewDoc.vue';
+import ComponentsDoc from '@/doc/migration/v4/breakingchanges/ComponentsDoc.vue';
+import StyledModeDoc from '@/doc/migration/v4/breakingchanges/StyledModeDoc.vue';
+
+export default {
+    data() {
+        return {
+            docs: [
+                {
+                    id: 'overview',
+                    label: 'Overview',
+                    component: OverviewDoc
+                },
+                {
+                    id: 'newfeatures',
+                    label: 'New Features',
+                    component: NewFeaturesDoc
+                },
+                {
+                    id: 'breakingchanges',
+                    label: 'Breaking Changes',
+                    children: [
+                        {
+                            id: 'styledmode',
+                            label: 'Styled Mode',
+                            component: StyledModeDoc
+                        },
+                        {
+                            id: 'components',
+                            label: 'Components',
+                            component: ComponentsDoc
+                        }
+                    ]
+                }
+            ]
+        };
+    }
+};
+</script>