Updated theming docs

Sim

apps/showcase/assets/data/menu.json

@@ -473,11 +473,6 @@
             "icon": "pi pi-heart",
             "routerLink": "/tailwind"
         },
-        {
-            "name": "Figma UI Kit",
-            "icon": "pi pi-pencil",
-            "routerLink": "/uikit"
-        },
         {
             "name": "Icons",
             "icon": "pi pi-eye",
@@ -492,6 +487,11 @@
                 }
             ]
         },
+        {
+            "name": "Figma UI Kit",
+            "icon": "pi pi-pencil",
+            "routerLink": "/uikit"
+        },
         {
             "name": "Templates",
             "icon": "pi pi-star",

apps/showcase/doc/theming/reversedkeysdoc.ts → apps/showcase/doc/splitbutton/reversedkeysdoc.ts

@@ -6,7 +6,7 @@ import { Component } from '@angular/core';
         <app-docsectiontext>
             <p>
                 Following keys are reserved in the preset scheme and cannot be used as a token name; <i>primitive</i>, <i>semantic</i>, <i>components</i>, <i>directives</i>, <i>colorscheme</i>, <i>light</i>, <i>dark</i>, <i>common</i>, <i>root</i>,
-                <i>states</i>.
+                <i>states</i> and <i>extend</i>.
             </p>
         </app-docsectiontext>
     `

apps/showcase/doc/theming/architecturedoc.ts

@@ -7,7 +7,7 @@ import { Component } from '@angular/core';
             <p>
                 PrimeNG is a design agnostic library so unlike some other UI libraries it does not enforce a certain styling such as material design. Styling is decoupled from the components using the themes instead. A theme consists of two parts;
                 <i>base</i> and <i>preset</i>. The base is the style rules with CSS variables as placeholders whereas the preset is a set of design tokens to feed a base by mapping the tokens to CSS variables. A base may be configured with different
-                presets, currently Aura, Lara and Nora are the available presets and in upcoming version more presets will be available such as Material Design.
+                presets, currently Aura, Material, Lara and Nora are the available built-in options.
             </p>
             <img alt="Architecture" src="https://primefaces.org/cdn/primevue/images/primevue-v4-styled-architecture.png" class="w-full mb-4" />
             <p>The core of the styled mode architecture is based on a concept named <i>design token</i>, a preset defines the token configuration in 3 tiers; <i>primitive</i>, <i>semantic</i> and <i>component</i>.</p>

apps/showcase/doc/theming/colorsdoc.ts

@@ -4,11 +4,7 @@ import { Component } from '@angular/core';
     selector: 'colors-doc',
     template: `
         <app-docsectiontext>
-            <p>
-                Color palette of a preset is defined by the <i>primitive</i> design token group. The default colors are derived from the Tailwind colors with some extensions to make it consistent with the Tailwind Presets projects of the unstyled
-                mode.
-            </p>
-            <p>Colors can be accessed at CSS as a variable and programmatically using the <i>$dt</i> utility.</p>
+            <p>Color palette of a preset is defined by the <i>primitive</i> design token group. You can access colors using CSS variables or the <i>$dt</i> utility.</p>
             <app-code [code]="code" selector="colors-demo" [hideToggleCode]="true"></app-code>
             <div class="card mt-4">
                 <ul class="p-0 m-0 list-none flex sm:flex-col gap-4 flex-wrap sm:flex-nowrap">
@@ -19,7 +15,7 @@ import { Component } from '@angular/core';
                                 @for (shade of shades; track shade) {
                                     <div class="flex flex-col items-center gap-1 flex-1">
                                         <div class="rounded h-8 w-full" [style]="'background-color: var(--p-' + color + '-' + shade + ')'"></div>
-                                        <span class="text-sm text-surface-500 dark:text-surface-400 font-medium">{{ shades[j] }}</span>
+                                        <span class="text-sm text-surface-500 dark:text-surface-400 font-medium">{{ shade }}</span>
                                     </div>
                                 }
                             </div>

apps/showcase/doc/theming/darkmodedoc.ts

@@ -1,3 +1,4 @@
+import { Code } from '@/domain/code';
 import { Component } from '@angular/core';
 
 @Component({
@@ -6,7 +7,7 @@ import { Component } from '@angular/core';
         <app-docsectiontext>
             <p>
                 PrimeNG uses the <i>system</i> as the default <i>darkModeSelector</i> in theme configuration. If you have a dark mode switch in your application, set the <i>darkModeSelector</i> to the selector you utilize such as
-                <i>.my-app-dark</i> so that PrimeNG can fit in seamlessly with your light-dark toggle.
+                <i>.my-app-dark</i> so that PrimeNG can fit in seamlessly with your color scheme.
             </p>
             <app-code [code]="code1" selector="darkmode-demo1" [hideToggleCode]="true"></app-code>
             <p class="mt-4">
@@ -22,29 +23,24 @@ import { Component } from '@angular/core';
                 <app-code [code]="code3" selector="darkmode-demo3" [hideToggleCode]="true"></app-code>
             </div>
             <p>In case you prefer to use dark mode all the time, apply the <i>darkModeSelector</i> initially and never change it.</p>
+            <div class="mb-4">
+                <app-code [code]="code4" selector="darkmode-demo4" [hideToggleCode]="true"></app-code>
+            </div>
+            <p>It is also possible to disable dark mode completely using <i>false</i> or <i>none</i> as the value of the selector.</p>
+            <div class="mb-4">
+                <app-code [code]="code5" selector="darkmode-demo4" [hideToggleCode]="true"></app-code>
+            </div>
         </app-docsectiontext>
     `
 })
 export class DarkModeDoc {
-    code1 = {
-        typescript: `import { Component, inject} from '@angular/core';
-import { PrimeNG } from 'primeng/config';
-import Aura from '@primeng/themes/aura';
-
-@Component({...})
-export class AppComponent {
-    config: PrimeNG = inject(PrimeNG);
-
-    constructor() {
-        // Default theme configuration
-        this.config.theme.set({
-            preset: Aura,
-            options: {
-                darkModeSelector: '.my-app-dark',
-            }
-        })
+    code1: Code = {
+        typescript: `providePrimeNG({ 
+    theme: {
+        preset: Aura,
+        darkModeSelector: '.my-app-dark'
     }
-}`
+})`
     };
 
     code2 = {
@@ -57,4 +53,17 @@ export class AppComponent {
     element.classList.toggle('my-app-dark');
 }`
     };
+
+    code4 = {
+        html: `<html class="my-app-dark">`
+    };
+
+    code5: Code = {
+        typescript: `providePrimeNG({ 
+    theme: {
+        preset: Aura,
+        darkModeSelector: false || 'none'
+    }
+})`
+    };
 }

apps/showcase/doc/theming/definepresetdoc.ts

@@ -1,3 +1,4 @@
+import { Code } from '@/domain/code';
 import { Component } from '@angular/core';
 
 @Component({
@@ -6,27 +7,38 @@ import { Component } from '@angular/core';
         <app-docsectiontext>
             <p>The <i>definePreset</i> utility is used to customize an existing preset during the PrimeNG setup. The first parameter is the preset to customize and the second is the design tokens to override.</p>
         </app-docsectiontext>
-        <app-code [code]="code" selector="define-preset-demo" [hideToggleCode]="true"></app-code>
+        <app-code [code]="code1" selector="define-preset-demo" [hideToggleCode]="true" class="block mb-4"></app-code>
+        <app-code [code]="code2" selector="define-preset-demo" [hideToggleCode]="true"></app-code>
     `
 })
 export class DefinePresetDoc {
-    code = {
-        typescript: `import { Component, inject } from '@angular/core';
-import { PrimeNG } from 'primeng/config';
+    code1: Code = {
+        typescript: `//mypreset.ts
 import { definePreset } from '@primeng/themes';
 import Aura from '@primeng/themes/aura';
 
 const MyPreset = definePreset(Aura, {
     //Your customizations, see the following sections for examples
 });
 
-@Component({...})
-export class AppComponent {
-    public config: PrimeNG = inject(PrimeNG);
+export MyPreset;`
+    };
+
+    code2: Code = {
+        typescript: `import { ApplicationConfig } from '@angular/core';
+import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
+import { providePrimeNG } from 'primeng/config';
+import MyPreset from './mypreset'; 
 
-    constructor() {
-       this.config.theme.set({ preset: MyPreset });
-    }
-}`
+export const appConfig: ApplicationConfig = {
+    providers: [
+        provideAnimationsAsync(),
+        providePrimeNG({ 
+            theme: {
+                preset: MyPreset
+            }
+        })
+    ]
+};`
     };
 }

apps/showcase/doc/theming/dtdoc.ts

@@ -6,14 +6,17 @@ import { Component } from '@angular/core';
         <app-docsectiontext>
             <p>The <i>$dt</i> function returns the information about a token like the full path and value. This would be useful if you need to access tokens programmatically.</p>
         </app-docsectiontext>
-        <app-code [code]="code" selector="dt-demo" [hideToggleCode]="true"></app-code>
+        <app-code [code]="code1" selector="dt-demo" [hideToggleCode]="true" class="block mb-4"></app-code>
+        <app-code [code]="code2" selector="dt-demo" [hideToggleCode]="true"></app-code>
     `
 })
 export class DtDoc {
-    code = {
-        typescript: `import { $dt } from '@primeng/themes';
+    code1 = {
+        typescript: `import { $dt } from '@primeng/themes';`
+    };
 
-const duration = $dt('transition.duration');
+    code2 = {
+        typescript: `const duration = $dt('transition.duration');
 /*
     duration: {
         name: '--transition-duration',

apps/showcase/doc/theming/extenddoc.ts

@@ -0,0 +1,56 @@
+import { Component } from '@angular/core';
+
+@Component({
+    selector: 'extend-doc',
+    template: `
+        <app-docsectiontext>
+            <p>
+                The theming system can be extended by adding custom design tokens and additional styles. This feature provides a high degree of customization, allowing you to adjust styles according to your needs, as you are not limited to the
+                default tokens.
+            </p>
+            <p>The example preset configuration adds a new <i>accent</i> button with custom <i>button.accent.color</i> and <i>button.accent.inverse.color</i> tokens. It is also possible to add tokens globally to share them within the components.</p>
+        </app-docsectiontext>
+        <app-code [code]="code" selector="component-demo" [hideToggleCode]="true"></app-code>
+    `
+})
+export class ExtendDoc {
+    code = {
+        typescript: `const MyPreset = definePreset(Aura, {
+    components: {
+        // custom button tokens and additional style
+        button: {
+            extend: {
+                accent: {
+                    color: '#f59e0b',
+                    inverseColor: '#ffffff'
+                }
+            }
+            css: ({ dt }) => \`
+.p-button-accent {
+    background: \${dt('button.accent.color')};
+    color: \${dt('button.accent.inverse.color')};
+    transition-duration: \${dt('my.transition.fast')};
+}
+\`
+        }
+    },
+    // common tokens and styles
+    extend: {
+        my: {
+            transition: {
+                slow: '0.75s'
+                normal: '0.5s'
+                fast: '0.25s'
+            },
+            imageDisplay: 'block' 
+        }
+    },
+    css: ({ dt }) => \`
+        /* Global CSS */
+        img {
+            display: \${dt('my.image.display')};
+        }
+    \`
+});`
+    };
+}

apps/showcase/doc/theming/noirdoc.ts

@@ -5,7 +5,7 @@ import { Component } from '@angular/core';
     template: `
         <app-docsectiontext>
             <p>
-                The <i>noir</i> mode is the nickname of a variant that uses black tones as the primary and requires and additional <i>colorScheme</i> configuration to implement. A sample preset configuration with black and white variants as the
+                The <i>noir</i> mode is the nickname of a variant that uses surface tones as the primary and requires and additional <i>colorScheme</i> configuration to implement. A sample preset configuration with black and white variants as the
                 primary color;
             </p>
         </app-docsectiontext>

apps/showcase/doc/theming/optionsdoc.ts

@@ -10,15 +10,15 @@ import { Component } from '@angular/core';
             <app-code [code]="code1" selector="options-demo-1" [hideToggleCode]="true"></app-code>
             <h4>darkModeSelector</h4>
             <p>
-                The CSS rule to encapsulate the CSS variables of the dark mode, the default is the <i>system</i> to generate <i>media (prefers-color-scheme: dark)</i>. If you need to make the dark mode toggleable based on the user selection define a
-                class selector such as <i>.app-dark</i> and toggle this class at the document root. See the dark mode toggle section for an example.
+                The CSS rule to encapsulate the CSS variables of the dark mode, the default is the <i>system</i> to generate <i>{{ '@' }}media (prefers-color-scheme: dark)</i>. If you need to make the dark mode toggleable based on the user selection
+                define a class selector such as <i>.app-dark</i> and toggle this class at the document root. See the dark mode toggle section for an example.
             </p>
             <app-code [code]="code2" selector="options-demo-2" [hideToggleCode]="true"></app-code>
             <h4>cssLayer</h4>
             <p>
                 Defines whether the styles should be defined inside a
                 <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@layer" target="_blank" rel="noopener noreferrer">CSS layer</a>
-                named <i>primeui</i> by default or not. A CSS layer would be handy to declare a custom cascade layer for easier customization. The default is <i>false</i>.
+                by default or not. A CSS layer would be handy to declare a custom cascade layer for easier customization if necessary. The default is <i>false</i>.
             </p>
             <app-code [code]="code3" selector="options-demo-3" [hideToggleCode]="true"></app-code>
         </app-docsectiontext>
@@ -41,7 +41,7 @@ export class OptionsDoc {
         typescript: `options: {
     cssLayer: {
         name: 'primeng',
-        order: 'tailwind-base, primeng, tailwind-utilities'
+        order: 'app-styles, primeng, another-css-library'
     }
 }`
     };

apps/showcase/doc/theming/palettedoc.ts

@@ -6,14 +6,17 @@ import { Component } from '@angular/core';
         <app-docsectiontext>
             <p>Returns shades and tints of a given color from 50 to 950 as an array.</p>
         </app-docsectiontext>
-        <app-code [code]="code" selector="palette-demo" [hideToggleCode]="true"></app-code>
+        <app-code [code]="code1" selector="palette-demo" [hideToggleCode]="true" class="block mb-4"></app-code>
+        <app-code [code]="code2" selector="palette-demo" [hideToggleCode]="true"></app-code>
     `
 })
 export class PaletteDoc {
-    code = {
-        typescript: `import { palette } from '@primeng/themes';
+    code1 = {
+        typescript: `import { palette } from '@primeng/themes';`
+    };
 
-// custom color
+    code2 = {
+        typescript: `// custom color
 const values1 = palette('#10b981');
 
 // copy an existing token set