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 1/2] 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>

From b5a76759788e62419c8c01de1577fd112ee0459f Mon Sep 17 00:00:00 2001
From: Cagatay Civici <cagatay.civici@gmail.com>
Date: Mon, 1 Apr 2024 10:55:51 +0300
Subject: [PATCH 2/2] Add case doc

---
 doc/theming/styled/CaseStyleDoc.vue | 39 +++++++++++++++++++++++++++++
 doc/theming/styled/PresetsDoc.vue   | 14 ++++++-----
 pages/theming/styled/index.vue      |  6 +++++
 3 files changed, 53 insertions(+), 6 deletions(-)
 create mode 100644 doc/theming/styled/CaseStyleDoc.vue

diff --git a/doc/theming/styled/CaseStyleDoc.vue b/doc/theming/styled/CaseStyleDoc.vue
new file mode 100644
index 000000000..900ed1aa3
--- /dev/null
+++ b/doc/theming/styled/CaseStyleDoc.vue
@@ -0,0 +1,39 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>
+            Tokens are described with the dot separator e.g. <i>primary.color</i>, <i>form.field.background</i> or <i>checkbox.icon.checked.color</i>. At preset configuration, camel case and object property are used when mapping the dot separator.
+            The following is an example from the checkbox component tokens to represent the <i>checkbox.icon.checked.color</i>, all alternatives have the same result.
+        </p>
+    </DocSectionText>
+    <DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz />
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            code: {
+                basic: `
+export default {
+    iconCheckedColor: //...,
+}
+
+export default {
+    icon: {
+        checkedColor: //...
+    }
+}
+
+export default {
+    icon: {
+        checked: {
+            color: //...
+        }
+    }
+}
+`
+            }
+        };
+    }
+};
+</script>
diff --git a/doc/theming/styled/PresetsDoc.vue b/doc/theming/styled/PresetsDoc.vue
index d94203558..935e5c482 100644
--- a/doc/theming/styled/PresetsDoc.vue
+++ b/doc/theming/styled/PresetsDoc.vue
@@ -2,12 +2,14 @@
     <DocSectionText v-bind="$attrs">
         <p>Currently Aura is the only available preset and more will follow in the upcoming updates.</p>
     </DocSectionText>
-    <TabView>
-        <TabPanel header="Aura"><DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz /></TabPanel>
-        <TabPanel header="Lara">Under development.</TabPanel>
-        <TabPanel header="Nora">Under development.</TabPanel>
-        <TabPanel header="Material">Under development.</TabPanel>
-    </TabView>
+    <div class="card">
+        <TabView>
+            <TabPanel header="Aura"><DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz /></TabPanel>
+            <TabPanel header="Lara">Under development.</TabPanel>
+            <TabPanel header="Nora">Under development.</TabPanel>
+            <TabPanel header="Material">Under development.</TabPanel>
+        </TabView>
+    </div>
 </template>
 
 <script>
diff --git a/pages/theming/styled/index.vue b/pages/theming/styled/index.vue
index 077cc4937..20620f829 100755
--- a/pages/theming/styled/index.vue
+++ b/pages/theming/styled/index.vue
@@ -21,6 +21,7 @@
 <script>
 import ArchitectureDoc from '@/doc/theming/styled/ArchitectureDoc.vue';
 import CSSModulesDoc from '@/doc/theming/styled/CSSModulesDoc.vue';
+import CaseStyleDoc from '@/doc/theming/styled/CaseStyleDoc.vue';
 import ColorsDoc from '@/doc/theming/styled/ColorsDoc.vue';
 import DarkModeToggleDoc from '@/doc/theming/styled/DarkModeToggleDoc.vue';
 import PresetsDoc from '@/doc/theming/styled/PresetsDoc.vue';
@@ -75,6 +76,11 @@ export default {
                     label: 'Presets',
                     component: PresetsDoc
                 },
+                {
+                    id: 'casestyle',
+                    label: 'Case Style',
+                    component: CaseStyleDoc
+                },
                 {
                     id: 'customization',
                     label: 'Customization',