Updated styling docs

primefaces · Oct 7, 2023 · 5d1f615 · 5d1f615
1 parent 3cb9b4c
commit 5d1f615
Show file tree

Hide file tree

Showing 8 changed files with 126 additions and 46 deletions.
diff --git a/components/doc/DocSectionCode.vue b/components/doc/DocSectionCode.vue
@@ -80,7 +80,7 @@
             ></Button>
         </div>
 
-        <div :style="scrollable ? { 'max-height': '40rem' } : undefined">
+        <div :style="scrollable ? { 'max-height': '40rem', overflow: 'auto' } : undefined">
             <template v-if="codeMode === 'basic' && importCode">
                 <pre v-code.script><code>{{ code.basic }}
 </code></pre>

diff --git a/doc/theming/TailwindDoc.vue → doc/tailwind/CSSLayerDoc.vue b/doc/theming/TailwindDoc.vue → doc/tailwind/CSSLayerDoc.vue
@@ -1,8 +1,8 @@
 <template>
     <DocSectionText v-bind="$attrs">
         <p>
-            Tailwind CSS can be used with styled or unstyled modes of PrimeVue. For unstyled mode, visit the exclusive <PrimeVueNuxtLink to="/tailwind">Tailwind</PrimeVueNuxtLink> documentation. In styled mode, preflight mode may override the default
-            styles of the components so <i>@layer</i> configuration in your style file that includes tailwind styles is necessary for compatibility. Note that, this is only required when you are using PrimeVue in styled mode.
+            Tailwind CSS can be used with styled or unstyled modes of PrimeVue. In both cases, <a href="https://tailwindcss.com/docs/preflight" target="_blank" rel="noopener noreferrer">preflight</a> mode may break styling of the core functionality
+            so <i>@layer</i> configuration in your style file that includes tailwind styles is necessary for compatibility.
         </p>
     </DocSectionText>
     <DocSectionCode :code="code" hideToggleCode hideCodeSandbox hideStackBlitz />
@@ -20,8 +20,8 @@ export default {
 }
 
 @layer tailwind-utilities {
+  @tailwind components;
   @tailwind utilities;
-  @tailwind variants;
 }`
             }
         };

diff --git a/doc/tailwind/CustomizationDoc.vue → doc/tailwind/PresetDoc.vue b/doc/tailwind/CustomizationDoc.vue → doc/tailwind/PresetDoc.vue
diff --git a/doc/tailwind/SetupDoc.vue b/doc/tailwind/SetupDoc.vue
@@ -1,17 +1,36 @@
 <template>
     <DocSectionText v-bind="$attrs">
         <p>
-            This section assumes that Tailwind is already available in your application, if not visit the Tailwind CSS <a href="https://tailwindcss.com/docs/installation/framework-guides">framework guides</a> like Vite or Nuxt for the installation.
-            The built-in default theme is basically a <PrimeVueNuxtLink to="/passthrough">global pass through</PrimeVueNuxtLink> preset that needs to be imported from <i>primevue/passthrough/tailwind</i> path and then defined during setup. Since the
-            theme is exclusive to unstyled mode, the <i>unstyled</i> setting is required in addition.
+            This section assumes that Tailwind is already available in your application, if not visit the Tailwind CSS <a href="https://tailwindcss.com/docs/installation/framework-guides">framework guides</a> like Vite for the installation and make
+            sure to apply the CSS layer configuration above when including the styles of Tailwind as well.
+        </p>
+        <p class="flex align-items-start gap-2">
+            <Badge value="1"></Badge>
+            <span
+                >Tailwind uses PurgeCSS internally to remove unused classes, as PrimeVue components are loaded from <i>node_modules</i> the <i>content</i> property at <i>tailwind.config.js</i> needs to be aware of PrimeVue, otherwise the classes
+                utilized in the theme will be removed as well.</span
+            >
         </p>
         <DocSectionCode :code="code1" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
-        <p>
-            Tailwind uses PurgeCSS internally to remove unused classes, as PrimeVue components are loaded from <i>node_modules</i> the <i>content</i> property at <i>tailwind.config.js</i> needs to be aware of PrimeVue, otherwise the classes utilized
-            in the theme will be removed as well.
+        <p class="flex align-items-start gap-2">
+            <Badge value="2"></Badge>
+            <span
+                >Next step is enabling the <i>unstyled</i> option to remove the default style classes from the components and adding an empty <i>pt</i> so that they can be styled with Tailwind in the next section. Note that if you run your
+                application at this stage, functionality and accessibility of the components will still work but everything will be transparent as there is no style.</span
+            >
         </p>
         <DocSectionCode :code="code2" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
-        <p>Voilà 💚, you now have 90+ awesome Vue UI components styled with Tailwind that will work in harmony with the rest of your application. Time to customize it to bring in your own style with Tailwind.</p>
+
+        <p class="flex align-items-start gap-2">
+            <Badge value="3"></Badge>
+            <span
+                >At the final step, component styles are provided via a pass through configuration that utilizes Tailwind CSS. The default preset of each component is available at the Tailwind part under theming section of each component so you'll
+                able to copy paste instead of starting from scratch. Example below styles, inputtext and panel components;
+            </span>
+        </p>
+        <DocSectionCode :code="code3" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
+
+        <p>Voilà 💚, you now have access to 90+ awesome Vue UI components styled with Tailwind that will work in harmony with the rest of your application.</p>
     </DocSectionText>
 </template>
 
@@ -21,26 +40,88 @@ export default {
         return {
             code1: {
                 basic: `
+export default {
+    ...
+    content: [
+        "./index.html",
+        "./src/**/*.{vue,js,ts,jsx,tsx}",
+        "./node_modules/primevue/**/*.{vue,js,ts,jsx,tsx}"
+    ],
+    ...
+}
+`
+            },
+            code2: {
+                basic: `
 import {createApp} from "vue";
 import PrimeVue from "primevue/config";
 import Tailwind from "primevue/passthrough/tailwind";
 
 const app = createApp(App);
 
-app.use(PrimeVue, { unstyled: true, pt: Tailwind });
+app.use(PrimeVue, { unstyled: true, pt: {} });
 `
             },
-            code2: {
+            code3: {
                 basic: `
-export default {
-    ...
-    content: [
-        "./index.html",
-        "./src/**/*.{vue,js,ts,jsx,tsx}",
-        "./node_modules/primevue/**/*.{vue,js,ts,jsx,tsx}"
-    ],
-    ...
+import {createApp} from "vue";
+import PrimeVue from "primevue/config";
+import Tailwind from "primevue/passthrough/tailwind";
+
+const app = createApp(App);
+
+//My Design System with Tailwind
+const MyDesignSystem = {
+    inputtext: {
+        root: ({ props: InputTextProps, context: InputTextContext }) => ({
+            class: [
+                'm-0',
+                'font-sans text-gray-600 dark:text-white/80 bg-white dark:bg-gray-900 border border-gray-300 dark:border-blue-900/40 transition-colors duration-200 appearance-none rounded-lg',
+                {
+                    'hover:border-blue-500 focus:outline-none focus:outline-offset-0 focus:shadow-[0_0_0_0.2rem_rgba(191,219,254,1)] dark:focus:shadow-[0_0_0_0.2rem_rgba(147,197,253,0.5)]': !context.disabled,
+                    'opacity-60 select-none pointer-events-none cursor-default': context.disabled
+                },
+                {
+                    'text-lg px-4 py-4': props.size == 'large',
+                    'text-xs px-2 py-2': props.size == 'small',
+                    'p-3 text-base': props.size == null
+                }
+            ]
+        })
+    },
+    panel: {
+        header: ({ props: PanelProps }) => ({
+            class: [
+                'flex items-center justify-between', // flex and alignments
+                'border border-gray-300 bg-gray-100 text-gray-700 rounded-tl-lg rounded-tr-lg', // borders and colors
+                'dark:bg-gray-900 dark:border-blue-900/40 dark:text-white/80', // Dark mode
+                { 'p-5': !props.toggleable, 'py-3 px-5': props.toggleable } // condition
+            ]
+        }),
+        title: {
+            class: ['leading-none font-bold']
+        },
+        toggler: {
+            class: [
+                'inline-flex items-center justify-center overflow-hidden relative no-underline', // alignments
+                'w-8 h-8 text-gray-600 border-0 bg-transparent rounded-full transition duration-200 ease-in-out', // widths, borders, and transitions
+                'hover:text-gray-900 hover:border-transparent hover:bg-gray-200 dark:hover:text-white/80 dark:hover:bg-gray-800/80 dark:focus:shadow-[inset_0_0_0_0.2rem_rgba(147,197,253,0.5)]', // hover
+                'focus:outline-none focus:outline-offset-0 focus:shadow-[0_0_0_0.2rem_rgba(191,219,254,1)]' // focus
+            ]
+        },
+        togglerIcon: {
+            class: ['inline-block']
+        },
+        content: {
+            class: [
+                'p-5 border border-gray-300 bg-white text-gray-700 border-t-0 last:rounded-br-lg last:rounded-bl-lg',
+                'dark:bg-gray-900 dark:border-blue-900/40 dark:text-white/80' // Dark mode
+            ] // padding, borders, and colors
+        }
+    }
 }
+
+app.use(PrimeVue, { unstyled: true, pt: MyDesignSystem });
 `
             }
         };

diff --git a/doc/theming/ArchitectureDoc.vue b/doc/theming/ArchitectureDoc.vue
@@ -1,7 +1,7 @@
 <template>
     <DocSectionText v-bind="$attrs">
         <p class="line-height-3 bg-indigo-600 text-white p-3 text-lg" style="border-radius: 10px">
-            <strong>Note</strong>: In upcoming versions, theming architecture will be redesigned to utilize CSS variables instead of SCSS variables in a backward compatible way for a dynamic approach.
+            <strong>Note</strong>: In near future, theming architecture of the styled mode will be redesigned to utilize CSS variables instead of SCSS variables in a backward compatible way for a dynamic approach.
         </p>
         <p>
             PrimeVue is a design agnostic library so unlike other UI libraries it does not enforce a certain styling such as material or bootstrap. In order to achieve this, styling has been separated into two parts, core and theme. The core resides

diff --git a/doc/theming/BuiltInThemesDoc.vue b/doc/theming/BuiltInThemesDoc.vue
@@ -2,7 +2,7 @@
     <DocSectionText v-bind="$attrs">
         <p>
             PrimeVue ships with various free themes to choose from. The list below states all the available themes in the npm distribution with import paths. For a live preview, use the configurator
-            <span class="border-round inline-flex border-1 w-2rem h-2rem p-0 align-items-center justify-content-center bg-primary"><span class="pi pi-cog"></span></span> at the topbar to switch themes.
+            <span class="border-round inline-flex border-1 w-2rem h-2rem p-0 align-items-center justify-content-center bg-primary"><span class="pi pi-palette"></span></span> at the topbar to switch themes.
         </p>
     </DocSectionText>
     <DocSectionCode :code="code" hideToggleCode importCode hideCodeSandbox hideStackBlitz scrollable />

diff --git a/pages/tailwind/index.vue b/pages/tailwind/index.vue
@@ -9,11 +9,7 @@
             <div class="doc-main">
                 <div class="doc-intro">
                     <h1>Tailwind CSS</h1>
-                    <p>
-                        The exclusive Tailwind integration of PrimeVue is a great choice for developers who want the flexibility of Tailwind with the convenience of a UI Component library. Tailwind simply fits perfectly to the unstyled mode of
-                        PrimeVue to implement design systems. A <b>built-in Tailwind theme</b> based on <PrimeVueNuxtLink to="/uikit" class="text-primary hover:underline font-semibold">PrimeOne Design</PrimeVueNuxtLink> is even available to get
-                        started in no time. In the upcoming iterations, PrimeVue will provide more presets to implement various design systems.
-                    </p>
+                    <p>Tailwind CSS is a popular utility first CSS library that fits perfectly to the unstyled mode to skin the entire UI suite with a design system of your choice.</p>
                 </div>
                 <DocSections :docs="docs" />
             </div>
@@ -23,7 +19,7 @@
 </template>
 
 <script>
-import CustomizationDoc from '@/doc/tailwind/CustomizationDoc.vue';
+import CSSLayerDoc from '@/doc/tailwind/CSSLayerDoc.vue';
 import ExampleDoc from '@/doc/tailwind/ExampleDoc.vue';
 import SetupDoc from '@/doc/tailwind/SetupDoc.vue';
 
@@ -32,19 +28,28 @@ export default {
         return {
             docs: [
                 {
-                    id: 'setup',
-                    label: 'Setup',
-                    component: SetupDoc
+                    id: 'csslayer',
+                    label: 'CSS Layer',
+                    component: CSSLayerDoc
                 },
                 {
-                    id: 'customization',
-                    label: 'Customization',
-                    component: CustomizationDoc
-                },
-                {
-                    id: 'example',
-                    label: 'Example',
-                    component: ExampleDoc
+                    id: 'unstyled',
+                    label: 'Unstyled Mode',
+                    description: `In unstyled mode, the exclusive Tailwind integration of PrimeVue is a great choice for developers who want the flexibility of Tailwind with the convenience of
+                        a UI Component library. Tailwind is a perfect match for the unstyled mode of PrimeVue to implement design systems. A built-in Tailwind theme as a pass through preset based on
+                        PrimeOne Design is even available to get started in no time. In upcoming iterations, a preset gallery will be available to share implementations developed by the PrimeVue community.`,
+                    children: [
+                        {
+                            id: 'setup',
+                            label: 'Setup',
+                            component: SetupDoc
+                        },
+                        {
+                            id: 'example',
+                            label: 'Example',
+                            component: ExampleDoc
+                        }
+                    ]
                 }
             ]
         };

diff --git a/pages/theming/index.vue b/pages/theming/index.vue
@@ -28,7 +28,6 @@ import PrimeFlexDoc from '@/doc/theming/PrimeFlexDoc.vue';
 import ScaleDoc from '@/doc/theming/ScaleDoc.vue';
 import ScopedCSSDoc from '@/doc/theming/ScopedCSSDoc.vue';
 import SwitchThemesDoc from '@/doc/theming/SwitchThemesDoc.vue';
-import TailwindDoc from '@/doc/theming/TailwindDoc.vue';
 import UtilsDoc from '@/doc/theming/UtilsDoc.vue';
 
 export default {
@@ -75,11 +74,6 @@ export default {
                     label: 'PrimeFlex',
                     component: PrimeFlexDoc
                 },
-                {
-                    id: 'tailwind',
-                    label: 'Tailwind',
-                    component: TailwindDoc
-                },
                 {
                     id: 'utils',
                     label: 'Utils',