@exhaustive-ui/mcp 22.0.0-rc.3 → 22.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/data/components.json +410 -354
- package/data/llms-full.txt +1750 -509
- package/data/llms.txt +2 -1
- package/data/manifest.json +1 -1
- package/data/pages/accessibility.md +164 -6
- package/data/pages/animations.md +110 -5
- package/data/pages/configuration.md +107 -102
- package/data/pages/contribution.md +68 -7
- package/data/pages/customicons.md +8 -8
- package/data/pages/faq.md +103 -8
- package/data/pages/icons.md +24 -23
- package/data/pages/installation.md +77 -25
- package/data/pages/llms.md +71 -15
- package/data/pages/passthrough.md +96 -7
- package/data/pages/philosophy.md +80 -11
- package/data/pages/primeflex.md +41 -4
- package/data/pages/rtl.md +4 -1
- package/data/pages/styled.md +174 -66
- package/data/pages/tailwind.md +309 -218
- package/data/pages/unstyled.md +48 -7
- package/data/pages/update.md +42 -13
- package/data/pages/v22.md +218 -0
- package/data/snapshot.json +3 -3
- package/dist/index.mjs +2 -2
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/data/pages/styled.md
CHANGED
|
@@ -4,43 +4,158 @@ Choose from a variety of pre-styled themes or develop your own.
|
|
|
4
4
|
|
|
5
5
|
## Architecture
|
|
6
6
|
|
|
7
|
-
ExhaustiveUI 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
|
|
7
|
+
ExhaustiveUI 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
|
|
8
|
+
parts;
|
|
9
|
+
`base` and `preset`. 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
|
|
10
|
+
presets, currently Aura, Material, Lara and Nora are the available built-in options.
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
The core of the styled mode architecture is based on a concept named `design token`, a preset defines the token configuration in 3 tiers; `primitive`, `semantic` and `component`.
|
|
13
|
+
|
|
14
|
+
### Primitive Tokens
|
|
15
|
+
|
|
16
|
+
Primitive tokens have no context, a color palette is a good example for a primitive token such as `blue-50` to `blue-900`. A token named `blue-500` may be used as the primary color, the background of a message however
|
|
17
|
+
on its own, the name of the token does not indicate context. Usually they are utilized by the semantic tokens.
|
|
18
|
+
|
|
19
|
+
### Semantic Tokens
|
|
20
|
+
|
|
21
|
+
Semantic tokens define content and their names indicate where they are utilized, a well known example of a semantic token is the `primary.color`. Semantic tokens map to primitive tokens or other semantic tokens. The
|
|
22
|
+
`colorScheme` token group is a special variable to define tokens based on the color scheme active in the application, this allows defining different tokens based on the color scheme like dark mode.
|
|
23
|
+
|
|
24
|
+
### Component Tokens
|
|
25
|
+
|
|
26
|
+
Component tokens are isolated tokens per component such as `inputtext.background` or `button.color` that map to the semantic tokens. As an example, `button.background` component token maps to the
|
|
27
|
+
`primary.color` semantic token which maps to the `green.500` primitive token.
|
|
28
|
+
|
|
29
|
+
### Best Practices
|
|
30
|
+
|
|
31
|
+
Use primitive tokens when defining the core color palette and semantic tokens to specify the common design elements such as focus ring, primary colors and surfaces. Components tokens should only be used when customizing a specific
|
|
32
|
+
component. By defining your own design tokens as a custom preset, you'll be able to define your own style without touching CSS. Overriding the ExhaustiveUI components using style classes is not a best practice and should be the last
|
|
33
|
+
resort, design tokens are the suggested approach.
|
|
34
|
+
|
|
35
|
+
## Theme
|
|
36
|
+
|
|
37
|
+
The `theme` property is used to customize the initial theme.
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import { ApplicationConfig } from '@angular/core';
|
|
41
|
+
import { provideExhaustive } from '@exhaustive-ui/core/config';
|
|
42
|
+
import Aura from '@exhaustive-ui/themes/aura';
|
|
43
|
+
|
|
44
|
+
export const appConfig: ApplicationConfig = {
|
|
45
|
+
providers: [
|
|
46
|
+
provideExhaustive({
|
|
47
|
+
theme: {
|
|
48
|
+
preset: Aura
|
|
49
|
+
}
|
|
50
|
+
})
|
|
51
|
+
]
|
|
52
|
+
};
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## Options
|
|
56
|
+
|
|
57
|
+
The `options` property defines the how the CSS would be generated from the design tokens of the preset.
|
|
58
|
+
|
|
59
|
+
prefix
|
|
10
60
|
|
|
11
|
-
|
|
61
|
+
The prefix of the CSS variables, defaults to `p`. For instance, the `primary.color` design token would be `var(--p-primary-color)`.
|
|
62
|
+
|
|
63
|
+
darkModeSelector
|
|
64
|
+
|
|
65
|
+
The CSS rule to encapsulate the CSS variables of the dark mode, the default is the `system` to generate `{{ '@' }}media (prefers-color-scheme: dark)`. If you need to make the dark mode toggleable based on the user selection
|
|
66
|
+
define a class selector such as `.app-dark` and toggle this class at the document root. See the dark mode toggle section for an example.
|
|
67
|
+
|
|
68
|
+
cssLayer
|
|
69
|
+
|
|
70
|
+
Defines whether the styles should be defined inside a
|
|
71
|
+
[CSS layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer)
|
|
72
|
+
by default or not. A CSS layer would be handy to declare a custom cascade layer for easier customization if necessary. The default is `false`.
|
|
73
|
+
|
|
74
|
+
## Presets
|
|
75
|
+
|
|
76
|
+
Aura, Material, Lara and Nora are the available built-in options, created to demonstrate the power of the design-agnostic theming. Aura is PrimeTek's own vision, Material follows Google Material Design v2, Lara is based on Bootstrap
|
|
77
|
+
and Nora is inspired by enterprise applications. Visit the [source code](https://github.com/e-xiste/exhaustive-ui/tree/main/packages/themes/src/presets) to learn more about the
|
|
78
|
+
structure of presets. You may use them out of the box with modifications or utilize them as reference in case you need to build your own presets from scratch.
|
|
12
79
|
|
|
13
80
|
## Colors
|
|
14
81
|
|
|
15
|
-
Color palette of a preset is defined by the primitive design token group. You can access colors using CSS variables or the
|
|
82
|
+
Color palette of a preset is defined by the `primitive` design token group. You can access colors using CSS variables or the `$dt` utility.
|
|
16
83
|
|
|
17
|
-
|
|
84
|
+
@for (color of colors; track color) {
|
|
85
|
+
- {{ color }} @for (shade of shades; track shade) { {{ shade }} }
|
|
86
|
+
}
|
|
18
87
|
|
|
19
|
-
|
|
88
|
+
## Dark Mode
|
|
20
89
|
|
|
21
|
-
|
|
90
|
+
ExhaustiveUI uses the `system` as the default `darkModeSelector` in theme configuration. If you have a dark mode switch in your application, set the `darkModeSelector` to the selector you utilize such as
|
|
91
|
+
`.my-app-dark` so that ExhaustiveUI can fit in seamlessly with your color scheme.
|
|
92
|
+
|
|
93
|
+
```typescript
|
|
94
|
+
provideExhaustive({
|
|
95
|
+
theme: {
|
|
96
|
+
preset: Aura,
|
|
97
|
+
options: {
|
|
98
|
+
darkModeSelector: '.my-app-dark'
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
})
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Following is a very basic example implementation of a dark mode switch, you may extend it further by involving
|
|
105
|
+
`prefers-color-scheme` to retrieve it from the system initially and use `localStorage` to make it stateful. See this
|
|
106
|
+
[article](https://dev.to/abbeyperini/dark-mode-toggle-and-prefers-color-scheme-4f3m)
|
|
107
|
+
for more information.
|
|
22
108
|
|
|
23
|
-
|
|
109
|
+
In case you prefer to use dark mode all the time, apply the `darkModeSelector` initially and never change it.
|
|
24
110
|
|
|
25
|
-
|
|
111
|
+
It is also possible to disable dark mode completely using `false` or `none` as the value of the selector.
|
|
26
112
|
|
|
27
|
-
|
|
113
|
+
```typescript
|
|
114
|
+
provideExhaustive({
|
|
115
|
+
theme: {
|
|
116
|
+
preset: Aura,
|
|
117
|
+
options: {
|
|
118
|
+
darkModeSelector: false || 'none'
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
})
|
|
122
|
+
```
|
|
28
123
|
|
|
29
|
-
##
|
|
124
|
+
## definePreset
|
|
30
125
|
|
|
31
|
-
The definePreset utility is used to customize an existing preset during the ExhaustiveUI setup. The first parameter is the preset to customize and the second is the design tokens to override.
|
|
126
|
+
The `definePreset` utility is used to customize an existing preset during the ExhaustiveUI setup. The first parameter is the preset to customize and the second is the design tokens to override.
|
|
32
127
|
|
|
33
|
-
##
|
|
128
|
+
## Color Scheme
|
|
34
129
|
|
|
35
|
-
|
|
130
|
+
A token can be defined per color scheme using `light` and `dark` properties of the `colorScheme` property. Each token can have specific values based on the current color scheme.
|
|
36
131
|
|
|
37
|
-
|
|
132
|
+
Common Pitfall
|
|
38
133
|
|
|
39
|
-
|
|
134
|
+
When customizing an existing preset, your token overrides may be ignored if you don't properly account for color scheme variations. If the original preset defines a token using the `colorScheme` property, but your customization
|
|
135
|
+
only provides a direct value, your override will be ignored because the `colorScheme` property takes precedence over direct values and the system will continue using the preset's scheme-specific values. When customizing tokens
|
|
136
|
+
that are not defined with `colorScheme` in the original preset, your customizations will be applied successfully regardless of how you structure them; whether direct or under colorScheme.
|
|
40
137
|
|
|
41
|
-
|
|
138
|
+
Best Practices
|
|
42
139
|
|
|
43
|
-
|
|
140
|
+
- Check how tokens are defined in the preset before customizing from the [source](https://github.com/e-xiste/exhaustive-ui/blob/main/packages/themes/src/presets).
|
|
141
|
+
- Always maintain the same structure (direct value or colorScheme) as the original preset.
|
|
142
|
+
- Consider both light and dark mode values when overriding scheme-dependent tokens.
|
|
143
|
+
|
|
144
|
+
This approach ensures your customizations will be applied correctly regardless of the user's selected color scheme.
|
|
145
|
+
|
|
146
|
+
## Primary
|
|
147
|
+
|
|
148
|
+
The `primary` defines the main color palette, default value maps to the `emerald` primitive token. Let's setup to use `indigo` instead.
|
|
149
|
+
|
|
150
|
+
## Surface
|
|
151
|
+
|
|
152
|
+
The color scheme palette that varies between light and dark modes is specified with the surface tokens. Example below uses
|
|
153
|
+
`zinc` for light mode and `slategray` for dark mode. With this setting, light mode, would have a grayscale tone and dark mode would include bluish tone.
|
|
154
|
+
|
|
155
|
+
## Noir
|
|
156
|
+
|
|
157
|
+
The `noir` mode is the nickname of a variant that uses surface tones as the primary and requires and additional `colorScheme` configuration to implement. A sample preset configuration with black and white variants as the
|
|
158
|
+
primary color;
|
|
44
159
|
|
|
45
160
|
## Font
|
|
46
161
|
|
|
@@ -48,85 +163,78 @@ There is no design for fonts as UI components inherit their font settings from t
|
|
|
48
163
|
|
|
49
164
|
## Forms
|
|
50
165
|
|
|
51
|
-
The design tokens of the form input components are derived from the form.field token group. This customization example changes border color to primary on hover. Any component that depends on this semantic token such as
|
|
52
|
-
|
|
53
|
-
## Libraries
|
|
166
|
+
The design tokens of the form input components are derived from the `form.field` token group. This customization example changes border color to primary on hover. Any component that depends on this semantic token such as
|
|
167
|
+
`dropdown.hover.border.color` and `textarea.hover.border.color` would receive the change.
|
|
54
168
|
|
|
55
|
-
|
|
169
|
+
## Focus Ring
|
|
56
170
|
|
|
57
|
-
|
|
171
|
+
Focus ring defines the outline width, style, color and offset. Let's use a thicker ring with the primary color for the outline.
|
|
58
172
|
|
|
59
|
-
|
|
173
|
+
## Component
|
|
60
174
|
|
|
61
|
-
|
|
175
|
+
The design tokens of a specific component is defined at `components` layer. Overriding components tokens is not the recommended approach if you are building your own style, building your own preset should be preferred instead.
|
|
176
|
+
This configuration is global and applies to all card components, in case you need to customize a particular component on a page locally, view the Scoped CSS section for an example.
|
|
62
177
|
|
|
63
|
-
|
|
178
|
+
## Extend
|
|
64
179
|
|
|
65
|
-
|
|
180
|
+
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
|
|
181
|
+
default tokens.
|
|
66
182
|
|
|
67
|
-
|
|
183
|
+
The example preset configuration adds a new `accent` button with custom `button.accent.color` and `button.accent.inverse.color` tokens. It is also possible to add tokens globally to share them within the components.
|
|
68
184
|
|
|
69
|
-
##
|
|
185
|
+
## Scoped Tokens
|
|
70
186
|
|
|
71
|
-
|
|
187
|
+
Design tokens can be scoped to a certain component using the `dt` property. In this example, first switch uses the global tokens whereas second one overrides the global with its own tokens.
|
|
72
188
|
|
|
73
|
-
|
|
189
|
+
This approach is recommended over the `::ng-deep` as it offers a cleaner API while avoiding the hassle of CSS rule overrides.
|
|
74
190
|
|
|
75
|
-
|
|
191
|
+
## usePreset
|
|
76
192
|
|
|
77
|
-
|
|
193
|
+
Replaces the current presets entirely, common use case is changing the preset dynamically at runtime.
|
|
78
194
|
|
|
79
|
-
|
|
195
|
+
## updatePreset
|
|
80
196
|
|
|
81
|
-
|
|
197
|
+
Merges the provided tokens to the current preset, an example would be changing the primary color palette dynamically.
|
|
82
198
|
|
|
83
|
-
|
|
199
|
+
## updatePrimaryPalette
|
|
84
200
|
|
|
85
|
-
|
|
201
|
+
Updates the primary colors, this is a shorthand to do the same update using `updatePreset`.
|
|
86
202
|
|
|
87
|
-
|
|
203
|
+
## updateSurfacePalette
|
|
88
204
|
|
|
89
|
-
|
|
205
|
+
Updates the surface colors, this is a shorthand to do the same update using `updatePreset`.
|
|
90
206
|
|
|
91
|
-
|
|
207
|
+
## $dt
|
|
92
208
|
|
|
93
|
-
|
|
209
|
+
The `$dt` function returns the information about a token like the full path and value. This would be useful if you need to access tokens programmatically.
|
|
94
210
|
|
|
95
|
-
|
|
211
|
+
## palette
|
|
96
212
|
|
|
97
|
-
|
|
213
|
+
Returns shades and tints of a given color from 50 to 950 as an array.
|
|
98
214
|
|
|
99
|
-
|
|
215
|
+
## Specificity
|
|
100
216
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
import { provideExhaustive } from '@exhaustive-ui/core/config';
|
|
104
|
-
import Aura from '@exhaustive-ui/themes/aura';
|
|
217
|
+
The `@layer` is a standard CSS feature to define cascade layers for a customizable order of precedence. If you need to become more familiar with layers, visit the documentation at
|
|
218
|
+
[MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) to begin with.
|
|
105
219
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
provideExhaustive({
|
|
109
|
-
theme: {
|
|
110
|
-
preset: Aura
|
|
111
|
-
}
|
|
112
|
-
})
|
|
113
|
-
]
|
|
114
|
-
};
|
|
115
|
-
```
|
|
220
|
+
The `cssLayer` is disabled by default, when it is enabled at theme configuration, ExhaustiveUI wraps the built-in style classes under the `exhaustive` cascade layer to make the library styles easy to override. CSS in your
|
|
221
|
+
app without a layer has the highest CSS specificity, so you'll be able to override styles regardless of the location or how strong a class is written.
|
|
116
222
|
|
|
117
|
-
##
|
|
223
|
+
## Reset
|
|
118
224
|
|
|
119
|
-
|
|
225
|
+
In case ExhaustiveUI components have visual issues in your application, a Reset CSS may be the culprit. CSS layers would be an efficient solution that involves enabling the ExhaustiveUI layer, wrapping the Reset CSS in another layer
|
|
226
|
+
and defining the layer order. This way, your Reset CSS does not get in the way of ExhaustiveUI components.
|
|
120
227
|
|
|
121
|
-
##
|
|
228
|
+
## Scale
|
|
122
229
|
|
|
123
|
-
|
|
230
|
+
ExhaustiveUI UI component use `rem` units, 1rem equals to the font size of the `html` element which is `16px` by default. Use the root font-size to adjust the size of the components globally. This website uses
|
|
231
|
+
`14px` as the base so it may differ from your application if your base font size is different.
|
|
124
232
|
|
|
125
|
-
##
|
|
233
|
+
## Bootstrap
|
|
126
234
|
|
|
127
|
-
|
|
235
|
+
Bootstrap has a `reboot` utility to reset the CSS of the standard elements. If you are including this utility, you may give it a layer while importing it.
|
|
128
236
|
|
|
129
|
-
##
|
|
237
|
+
## Libraries
|
|
130
238
|
|
|
131
|
-
|
|
239
|
+
Example layer configuration for the popular CSS libraries.
|
|
132
240
|
|