vertumnus
/
primevue-mirror
mirror of https://github.com/primefaces/primevue.git
1
0
Fork 0
Code Packages Releases Activity

Updated styling docs

pull/4591/head
Cagatay Civici 2023-10-07 16:04:27 +03:00
parent 3cb9b4c99b
commit 5d1f615c14
8 changed files with 127 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
components/doc/DocSectionCode.vue
View File

@ -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>

6
doc/theming/TailwindDoc.vue → doc/tailwind/CSSLayerDoc.vue
View File

@ -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;
}`
}
};

0
doc/tailwind/CustomizationDoc.vue → doc/tailwind/PresetDoc.vue
View File

117
doc/tailwind/SetupDoc.vue
View File

@ -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,17 +40,6 @@ export default {
return {
code1: {
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 });
`
},
code2: {
basic: `
export default {
...
content: [
@ -41,6 +49,79 @@ export default {
],
...
}
`
},
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: {} });
`
},
code3: {
basic: `
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 });
`
}
};

2
doc/theming/ArchitectureDoc.vue
View File

@ -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

2
doc/theming/BuiltInThemesDoc.vue
View File

@ -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 />

27
pages/tailwind/index.vue
View File

@ -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';
@ -31,22 +27,31 @@ export default {
data() {
return {
docs: [
{
id: 'csslayer',
label: 'CSS Layer',
component: CSSLayerDoc
},
{
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: 'customization',
label: 'Customization',
component: CustomizationDoc
},
{
id: 'example',
label: 'Example',
component: ExampleDoc
}
]
}
]
};
}
};

6
pages/theming/index.vue
View File

@ -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',