@exhaustive-ui/mcp 22.0.0-rc.3 → 22.0.1
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 +513 -351
- package/data/llms-full.txt +1974 -489
- package/data/llms.txt +4 -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 +73 -7
- package/data/pages/customicons.md +8 -8
- package/data/pages/faq.md +108 -8
- package/data/pages/icons.md +24 -23
- package/data/pages/installation.md +78 -25
- package/data/pages/llms.md +71 -15
- package/data/pages/optimus.md +107 -0
- package/data/pages/passthrough.md +96 -7
- package/data/pages/philosophy.md +79 -11
- package/data/pages/primeflex.md +41 -4
- package/data/pages/primeng.md +120 -0
- 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 +221 -0
- package/data/snapshot.json +3 -3
- package/dist/index.mjs +4 -4
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# Migrating from Optimus UI
|
|
2
|
+
|
|
3
|
+
Moving an Optimus UI v2 application to ExhaustiveUI: package and configuration API renames, the CSS layer name, then the v22 migrations.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
ExhaustiveUI is a fork of Optimus UI, itself the MIT continuation of PrimeNG v21. An Optimus UI v2 application already runs on Angular 22 and uses the same components, selectors, CSS classes, design tokens and
|
|
8
|
+
`@openng/icons` icons. Moving it across takes two steps:
|
|
9
|
+
|
|
10
|
+
1. **The rename**: the `@openng/optimus-ui*` packages become `@exhaustive-ui/*`, and the four names of the configuration API change. The `migrate-from-optimus` schematic does it.
|
|
11
|
+
2. **The v22 changes**: the Signals API everywhere, OnPush and the API cleanup of ExhaustiveUI v22. The `ng update` migrations do most of it, and the [migration guide to v22](https://exhaustive-ui.com/migration/v22) covers the rest.
|
|
12
|
+
|
|
13
|
+
## Before you start
|
|
14
|
+
|
|
15
|
+
- **Optimus UI v2 on Angular 22.** An application still on Optimus UI v1 updates to v2 first, following Optimus UI's documentation.
|
|
16
|
+
- **A clean git working tree**, so the rename and the migrations can be reviewed on their own, and a build and test run that passes before you start.
|
|
17
|
+
|
|
18
|
+
## Migration steps
|
|
19
|
+
|
|
20
|
+
1. Install ExhaustiveUI and run the `migrate-from-optimus` schematic. It rewrites the workspace, then installs the new dependencies.
|
|
21
|
+
2. Run the v22 migrations. The workspace did not go through `ng update`, so they are run explicitly, from the version before v22.
|
|
22
|
+
3. Read both reports, fix the compiler errors, then build and run your tests.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install @exhaustive-ui/core@22
|
|
26
|
+
ng generate @exhaustive-ui/core:migrate-from-optimus
|
|
27
|
+
ng update @exhaustive-ui/core --migrate-only --from=3.0.0
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The schematic checks that `@openng/optimus-ui` v2 is installed. It takes two options: `--skip-install` leaves the install to you, and `--force` skips the version check. Like `ng update`, run it on a clean
|
|
31
|
+
working tree so its changes can be reviewed with `git diff`.
|
|
32
|
+
|
|
33
|
+
## What the schematic changes
|
|
34
|
+
|
|
35
|
+
The schematic visits every file of the workspace except `node_modules`, build output and the files your `.gitignore` excludes.
|
|
36
|
+
|
|
37
|
+
### Dependencies
|
|
38
|
+
|
|
39
|
+
In every `package.json` of the workspace, each package is replaced by its counterpart, which has the same content and the same subpaths:
|
|
40
|
+
|
|
41
|
+
- `@openng/optimus-ui` becomes `@exhaustive-ui/core`
|
|
42
|
+
- `@openng/optimus-ui-themes`, `-tailwindcss`, `-locale`, `-styled`, `-styles`, `-utils` and `-motion` become `@exhaustive-ui/themes`, `tailwindcss`, `locale`, `styled`, `styles`, `utils` and `motion`
|
|
43
|
+
- `@openng/icons` stays: ExhaustiveUI uses the same icon set.
|
|
44
|
+
|
|
45
|
+
### TypeScript
|
|
46
|
+
|
|
47
|
+
Imports, dynamic imports and `require()` calls are rewritten, subpaths included (`@openng/optimus-ui/button` becomes `@exhaustive-ui/core/button`), and so is the Tailwind CSS configuration file. The
|
|
48
|
+
configuration API is renamed where it is imported from Optimus UI, along with every use in the file: `provideOptimus` becomes `provideExhaustive`, the `Optimus` service becomes `Exhaustive`,
|
|
49
|
+
`OptimusConfigType` becomes `ExhaustiveConfigType` and `OPTIMUS_CONFIG` becomes `EXHAUSTIVE_CONFIG`. A class of your own that happens to be named `Optimus` is left alone.
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
// Before
|
|
53
|
+
import { ApplicationConfig } from '@angular/core';
|
|
54
|
+
import { provideOptimus } from '@openng/optimus-ui/config';
|
|
55
|
+
import Aura from '@openng/optimus-ui-themes/aura';
|
|
56
|
+
|
|
57
|
+
export const appConfig: ApplicationConfig = {
|
|
58
|
+
providers: [provideOptimus({ theme: { preset: Aura } })]
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
// After
|
|
62
|
+
import { ApplicationConfig } from '@angular/core';
|
|
63
|
+
import { provideExhaustive } from '@exhaustive-ui/core/config';
|
|
64
|
+
import Aura from '@exhaustive-ui/themes/aura';
|
|
65
|
+
|
|
66
|
+
export const appConfig: ApplicationConfig = {
|
|
67
|
+
providers: [provideExhaustive({ theme: { preset: Aura } })]
|
|
68
|
+
};
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Stylesheets and angular.json
|
|
72
|
+
|
|
73
|
+
`@import`, `@use`, `@plugin` and `url()` references in stylesheets, and the `styles` and `scripts` entries of `angular.json` and `project.json`, follow the new package names.
|
|
74
|
+
|
|
75
|
+
### The report
|
|
76
|
+
|
|
77
|
+
The schematic ends with the places that still mention `optimus-ui`, `Optimus`, `provideOptimus`, `OptimusConfigType` or `OPTIMUS_CONFIG`, with the file and line: templates, Markdown, comments, or module paths
|
|
78
|
+
passed to other functions, such as `jest.mock()`. Lockfiles are left out, since the install regenerates them.
|
|
79
|
+
|
|
80
|
+
## CSS layer
|
|
81
|
+
|
|
82
|
+
Optimus UI puts its styles in a CSS cascade layer named `optimus` when the theme enables `cssLayer`; ExhaustiveUI names it `exhaustive`. The schematic renames the `optimus` token in the `cssLayer`
|
|
83
|
+
`name` and `order` of your configuration, then the matching `@layer` declarations and `@import ... layer()` clauses in your stylesheets, so your overrides keep their place in the layer order. With
|
|
84
|
+
`cssLayer: true`, the configuration does not change, and only the stylesheets are renamed.
|
|
85
|
+
|
|
86
|
+
A layer of your own, with another name, is left as it is. The CSS classes (`p-button`...), the design tokens (`--p-primary-color`...) and the icon classes (`pi pi-check`...) do not change.
|
|
87
|
+
|
|
88
|
+
## v22 migrations
|
|
89
|
+
|
|
90
|
+
After `migrate-from-optimus`, run the v22 migrations. The workspace did not go through `ng update`, so they are run explicitly, from the version before v22:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
ng update @exhaustive-ui/core --migrate-only --from=3.0.0
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
They rewrite the templates and code for the inputs, outputs and templates removed or renamed in v22, and for the configuration options that became signals or changed name, such as `inputStyle`, now `inputVariant`. They
|
|
97
|
+
report what they cannot rewrite. The [migration guide to v22](https://exhaustive-ui.com/migration/v22) then covers the code changes: signal inputs, `model()` and signal queries in every component, OnPush change
|
|
98
|
+
detection, and the behavior and type changes.
|
|
99
|
+
|
|
100
|
+
## Checklist
|
|
101
|
+
|
|
102
|
+
- No `@openng/optimus-ui*` package left in any `package.json`, and the report of `migrate-from-optimus` handled.
|
|
103
|
+
- `provideExhaustive`, `Exhaustive`, `ExhaustiveConfigType` and `EXHAUSTIVE_CONFIG` in place of the Optimus names.
|
|
104
|
+
- With a CSS layer configured, your overrides still apply.
|
|
105
|
+
- The v22 migrations run and their report handled.
|
|
106
|
+
- The application compiles and its tests pass, after the code changes of the migration guide to v22.
|
|
107
|
+
|
|
@@ -4,29 +4,118 @@ Pass Through Props allow direct access to the underlying elements for complete c
|
|
|
4
4
|
|
|
5
5
|
## Basic
|
|
6
6
|
|
|
7
|
-
Each component has a special pt property to define an object with keys corresponding to the available DOM elements. Each value can either be a string, an object or a function that returns a string or an object to define the
|
|
7
|
+
Each component has a special `pt` property to define an object with keys corresponding to the available DOM elements. Each value can either be a string, an object or a function that returns a string or an object to define the
|
|
8
|
+
arbitrary properties to apply to the element such as styling, aria, data-* or custom attributes. If the value is a string or a function that returns a string, it is considered as a class definition and added to the class attribute of
|
|
9
|
+
the element. Every component documentation has a dedicated section to document the available section names exposed via PT.
|
|
8
10
|
|
|
9
11
|
## Global
|
|
10
12
|
|
|
11
|
-
PassThrough object can also be defined at a global level to apply all components in an application using the provideExhaustive provider. For example, with the configuration here all panel headers have the
|
|
13
|
+
PassThrough object can also be defined at a global level to apply all components in an application using the `provideExhaustive` provider. For example, with the configuration here all panel headers have the
|
|
14
|
+
`bg-primary` style class and all autocomplete components have a fixed width. These settings can be overridden by a particular component as components `pt` property has higher precedence over global `pt` by default.
|
|
12
15
|
|
|
13
16
|
## Instance
|
|
14
17
|
|
|
15
|
-
In cases where you need to access the UI Component instance, define a component passthrough type that exposes the component instance or a function that receives a PassThroughContext as parameter.
|
|
18
|
+
In cases where you need to access the UI Component instance, define a component passthrough type that exposes the component instance or a function that receives a `PassThroughContext` as parameter.
|
|
16
19
|
|
|
17
20
|
## Introduction
|
|
18
21
|
|
|
19
|
-
In traditional 3rd party UI libraries, users are limited to the API provided by component author. This API commonly consists of inputs, outputs, and content projection. Whenever a requirement emerges for a new customization option in
|
|
22
|
+
In traditional 3rd party UI libraries, users are limited to the API provided by component author. This API commonly consists of inputs, outputs, and content projection. Whenever a requirement emerges for a new customization option in
|
|
23
|
+
the API, the component author needs to develop and publish it with a new release.
|
|
24
|
+
|
|
25
|
+
The pass through feature is a key element to implement this vision by exposing the component internals in order to apply arbitrary attributes and listeners to the DOM elements. The primary advantage of this approach is that it frees
|
|
26
|
+
you from being restricted by the main component API. We recommend considering the pass-through feature whenever you need to tailor a component that lacks a built-in feature for your specific requirement.
|
|
27
|
+
|
|
28
|
+
Each component has a special `pt` property to define an object with keys corresponding to the available DOM elements. A value of a key can either be a string, an object or a function to define the arbitrary properties such as
|
|
29
|
+
styling, aria, data-* or custom attributes for the element. If the value is a string or a function that returns a string, it serves as a shorthand for a style class definition. Every component documentation has a dedicated segment to
|
|
30
|
+
document the available section names in the interactive PT Viewer.
|
|
31
|
+
|
|
32
|
+
### Panel Example
|
|
33
|
+
|
|
34
|
+
In this example, a Panel is customized with various options through `pt`. The styling is overriden with Tailwind CSS and header receives custom attributes along with a click event. The attributes passed to the header are not
|
|
35
|
+
available in the component API, thanks to PassThrough feature, this is no longer an issue as you are not limited to the component api. Note that, you may avoid the `!` based overrides in Tailwind classes if you setup CSS Layers
|
|
36
|
+
with ExhaustiveUI. Visit the [Override](https://exhaustive-ui.com/tailwind) section at Tailwind integration for examples.
|
|
20
37
|
|
|
21
38
|
## Lifecycle
|
|
22
39
|
|
|
23
|
-
Lifecycle hooks of components are exposed as pass through using the hooks property so that callback functions can be registered. Available callbacks are onBeforeInit
|
|
40
|
+
Lifecycle hooks of components are exposed as pass through using the `hooks` property so that callback functions can be registered. Available callbacks are `onBeforeInit`, `onInit`, `onChanges`, `onDoCheck`,
|
|
41
|
+
`onAfterContentInit`, `onAfterContentChecked`, `onAfterViewInit`, `onAfterViewChecked` and `onDestroy`. Refer to the Angular documentation for detailed information about lifecycle hooks.
|
|
24
42
|
|
|
25
43
|
## Pcprefix
|
|
26
44
|
|
|
27
|
-
A UI component may also use other UI components, in this case section names are prefixed with pc (Prime Component) to denote the ExhaustiveUI component begin used. This distinguishes components from standard DOM elements and
|
|
45
|
+
A UI component may also use other UI components, in this case section names are prefixed with `pc` (Prime Component) to denote the ExhaustiveUI component begin used. This distinguishes components from standard DOM elements and
|
|
46
|
+
indicating the necessity for a nested structure. For example, the `badge` section is identified as `pcBadge` because the button component incorporates the badge component internally.
|
|
28
47
|
|
|
29
48
|
## Ptoptions
|
|
30
49
|
|
|
31
|
-
The
|
|
50
|
+
The `ptOptions` property determines how a component's local PassThrough configuration merges with the global PT configuration, as demonstrated in the following examples using both global and component-level settings.
|
|
51
|
+
|
|
52
|
+
The `mergeSections` defines whether the sections from the main configuration gets added and the `mergeProps` controls whether to override or merge the defined props. Defaults are `true` for `mergeSections` and
|
|
53
|
+
`false` for `mergeProps`.
|
|
54
|
+
|
|
55
|
+
### Global Configuration
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
import { ApplicationConfig } from '@angular/core';
|
|
59
|
+
import { provideExhaustive } from '@exhaustive-ui/core/config';
|
|
60
|
+
|
|
61
|
+
export const appConfig: ApplicationConfig = {
|
|
62
|
+
providers: [
|
|
63
|
+
provideExhaustive({
|
|
64
|
+
pt: {
|
|
65
|
+
panel: {
|
|
66
|
+
header: {
|
|
67
|
+
'data-custom': 'acme-panel',
|
|
68
|
+
class: 'bg-primary text-primary-contrast'
|
|
69
|
+
},
|
|
70
|
+
content: 'font-medium'
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
})
|
|
74
|
+
]
|
|
75
|
+
};
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### mergeSections: true, mergeProps: false (default)
|
|
79
|
+
|
|
80
|
+
```typescript
|
|
81
|
+
import { Component } from '@angular/core';
|
|
82
|
+
import { Panel, PanelModule, PanelPassThrough } from '@exhaustive-ui/core/panel';
|
|
83
|
+
|
|
84
|
+
@Component({
|
|
85
|
+
selector: 'ptoptions-doc',
|
|
86
|
+
template: \
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### mergeSections: true, mergeProps: true
|
|
90
|
+
|
|
91
|
+
```typescript
|
|
92
|
+
import { Component } from '@angular/core';
|
|
93
|
+
import { Panel, PanelModule, PanelPassThrough } from '@exhaustive-ui/core/panel';
|
|
94
|
+
|
|
95
|
+
@Component({
|
|
96
|
+
selector: 'ptoptions-doc',
|
|
97
|
+
template: \
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### mergeSections: false, mergeProps: true
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
import { Component } from '@angular/core';
|
|
104
|
+
import { Panel, PanelModule, PanelPassThrough } from '@exhaustive-ui/core/panel';
|
|
105
|
+
|
|
106
|
+
@Component({
|
|
107
|
+
selector: 'ptoptions-doc',
|
|
108
|
+
template: \
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### mergeSections: false, mergeProps: false
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
import { Component } from '@angular/core';
|
|
115
|
+
import { Panel, PanelModule, PanelPassThrough } from '@exhaustive-ui/core/panel';
|
|
116
|
+
|
|
117
|
+
@Component({
|
|
118
|
+
selector: 'ptoptions-doc',
|
|
119
|
+
template: \
|
|
120
|
+
```
|
|
32
121
|
|
package/data/pages/philosophy.md
CHANGED
|
@@ -2,27 +2,95 @@
|
|
|
2
2
|
|
|
3
3
|
Why ExhaustiveUI exists, what it commits to, and where it stops.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Why This Fork Exists
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
In June 2026 PrimeTek archived the PrimeNG repository and moved future major versions, starting with v22, to a commercial license. They explained their reasoning in
|
|
8
|
+
[their own announcement](https://primeui.dev/nextchapter), and it is worth reading. Maintaining a component library of this size for a decade, largely for free, is genuinely hard,
|
|
9
|
+
and we do not think the decision was made lightly.
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
It did, however, leave a lot of applications on a library with no further open source releases. ExhaustiveUI exists for those applications. It is a community fork of the last MIT licensed version of PrimeNG, v21, and it stays MIT.
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
This is not an official fork and it is not endorsed by PrimeTek. It is a separate repository, seeded with PrimeNG's code and history, maintained by people who depend on it.
|
|
12
14
|
|
|
13
|
-
##
|
|
15
|
+
## What We Commit To
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
Four commitments, in the order we would want to read them if we were choosing a dependency:
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
### MIT, with no second tier
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
Every package we publish is MIT licensed. There is no paid edition, no enterprise build, no feature held back behind a subscription, and no plan to introduce one. If that ever changed, it would be a fork of this project rather than a
|
|
22
|
+
relicensing of it, because the code we inherited is MIT and so is everything we add to it.
|
|
23
|
+
|
|
24
|
+
### We track Angular
|
|
25
|
+
|
|
26
|
+
Our release cadence follows Angular's. When a new Angular major lands, the priority is a compatible ExhaustiveUI major — before new features, before refactors. Staying upgradeable is the single most valuable thing a component library
|
|
27
|
+
can do for the applications built on it.
|
|
28
|
+
|
|
29
|
+
### Bugs before features
|
|
30
|
+
|
|
31
|
+
We inherited a large backlog along with the code. Fixing what is broken ranks above adding what is missing. Feature requests are triaged and welcome, but they generally ship when someone in the community implements them.
|
|
32
|
+
|
|
33
|
+
### No surprises in your bundle
|
|
34
|
+
|
|
35
|
+
The library sends no telemetry, phones no home, and requires no account or key to use. What you install is what runs.
|
|
36
|
+
|
|
37
|
+
## What We Do Not Do
|
|
38
|
+
|
|
39
|
+
Naming the limits is what makes the commitments above worth anything. Here is what ExhaustiveUI is not.
|
|
40
|
+
|
|
41
|
+
### There is no commercial support
|
|
42
|
+
|
|
43
|
+
No SLA, no support contract, no guaranteed response time. Issues and discussions are answered by volunteers when they have time. If your organisation needs contractual guarantees, this project cannot provide them and you should plan
|
|
44
|
+
accordingly.
|
|
45
|
+
|
|
46
|
+
### There are no premium templates, blocks or design tooling
|
|
47
|
+
|
|
48
|
+
PrimeTek's application templates, block library and visual theme designer are their commercial products. They are not part of what was MIT licensed, so they are not part of this fork and will not be reimplemented. Theming here means
|
|
49
|
+
editing preset objects in code, which is documented in full.
|
|
50
|
+
|
|
51
|
+
### We are not chasing feature parity with PrimeNG v22 and beyond
|
|
52
|
+
|
|
53
|
+
PrimeNG continues under its own license and its own roadmap. ExhaustiveUI diverges from v21 forward. Some things they add, we will not have. Some things we fix, they will not. Treat the two as separate libraries that share an
|
|
54
|
+
ancestor, not as a free copy of a paid product.
|
|
55
|
+
|
|
56
|
+
### The bus factor is real
|
|
57
|
+
|
|
58
|
+
This is maintained by a small group of people in their own time. We would rather say that plainly than imply a larger organisation stands behind it. The best way to change that number is to
|
|
59
|
+
[contribute](https://github.com/e-xiste/exhaustive-ui).
|
|
60
|
+
|
|
61
|
+
## How Decisions Are Made
|
|
62
|
+
|
|
63
|
+
Everything happens in the open, in the [repository](https://github.com/e-xiste/exhaustive-ui). There is no private roadmap and no internal issue tracker. What you see in the issues,
|
|
64
|
+
the discussions and the [roadmap](https://exhaustive-ui.com/roadmap) is the whole plan.
|
|
65
|
+
|
|
66
|
+
Contributors earn commit access by contributing — the [contribution guide](https://exhaustive-ui.com/contribution) describes the Contributor and Committer roles and roughly what it takes to reach them. We would rather
|
|
67
|
+
grow the number of people who can merge a fix than route everything through one person.
|
|
68
|
+
|
|
69
|
+
Breaking changes are avoided within a major and documented when a major requires them. Where we inherited a name that no longer fits — the CSS cascade layer, the package scope, the icon library — we changed it once, at v1, with a
|
|
70
|
+
migration schematic, rather than dripping renames across releases.
|
|
71
|
+
|
|
72
|
+
## PrimeNG and PrimeTek
|
|
73
|
+
|
|
74
|
+
ExhaustiveUI is not affiliated with, endorsed by, or sponsored by PrimeTek. PrimeNG, PrimeFaces, PrimeReact, PrimeVue and PrimeFlex are their trademarks. The rename from the inherited names — the packages, the CSS layer, the icon
|
|
75
|
+
library — is a trademark matter, not a technical one, and it is why we ship a [migration schematic](https://exhaustive-ui.com/migration/primeng) rather than asking you to rewrite imports by hand.
|
|
76
|
+
|
|
77
|
+
References to PrimeNG remain throughout this documentation and the source, and they are deliberate. Attribution is the point: this library is PrimeTek's decade of work plus whatever the community adds on top. Pretending otherwise
|
|
78
|
+
would be both dishonest and useless to anyone trying to find their way around a familiar API.
|
|
79
|
+
|
|
80
|
+
The code we forked was published under the MIT license, and we distribute it under those same terms, with the original copyright notices intact.
|
|
20
81
|
|
|
21
82
|
## Sustainability
|
|
22
83
|
|
|
23
|
-
The honest answer to "how is this funded" is: it mostly is not. e-xiste covers the hosting and the domain; the work is volunteered. That is a fragile arrangement, and it is the main risk to this project — larger than any technical
|
|
84
|
+
The honest answer to "how is this funded" is: it mostly is not. e-xiste covers the hosting and the domain; the work is volunteered. That is a fragile arrangement, and it is the main risk to this project — larger than any technical
|
|
85
|
+
risk we can see today.
|
|
86
|
+
|
|
87
|
+
The things that actually help, roughly in order of impact:
|
|
24
88
|
|
|
25
|
-
|
|
89
|
+
- Reproducing and triaging issues. A bug with a minimal reproduction is several times more likely to get fixed.
|
|
90
|
+
- Sending pull requests, especially for issues labelled `help-needed`.
|
|
91
|
+
- Answering questions in discussions, so the same answer is not written five times.
|
|
92
|
+
- Improving this documentation. Every page has a source file and every fix is welcome.
|
|
93
|
+
- Telling your employer you depend on it. Sponsored maintenance time is worth more than any one-off donation.
|
|
26
94
|
|
|
27
|
-
|
|
95
|
+
The [contribution guide](https://exhaustive-ui.com/contribution) covers how to get started.
|
|
28
96
|
|
package/data/pages/primeflex.md
CHANGED
|
@@ -4,17 +4,54 @@ Moving from PrimeFlex to Tailwind CSS.
|
|
|
4
4
|
|
|
5
5
|
## Compatibility
|
|
6
6
|
|
|
7
|
-
If you are staying on PrimeFlex for now, ExhaustiveUI pairs with PrimeFlex v4 — the same combination that worked with PrimeNG v18 and newer, since the styling architecture is unchanged. PrimeFlex v3 targeted the older PrimeNG releases
|
|
7
|
+
If you are staying on PrimeFlex for now, ExhaustiveUI pairs with PrimeFlex v4 — the same combination that worked with PrimeNG v18 and newer, since the styling architecture is unchanged. PrimeFlex v3 targeted the older PrimeNG releases
|
|
8
|
+
and is not a supported pairing here.
|
|
9
|
+
|
|
10
|
+
Neither version is tested against ExhaustiveUI releases, so treat this as "should work", not as a supported configuration. The migration below is the path we actually maintain.
|
|
8
11
|
|
|
9
12
|
## Migration
|
|
10
13
|
|
|
11
|
-
PrimeFlex class names map closely onto Tailwind's, so most of the work is mechanical. PrimeTek's
|
|
14
|
+
PrimeFlex class names map closely onto Tailwind's, so most of the work is mechanical. PrimeTek's
|
|
15
|
+
[primeclt](https://www.npmjs.com/package/primeclt) ships a `pf2tw` command that does the conversion, and it works on any codebase — it rewrites class names and does not care
|
|
16
|
+
which component library you use.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install -g primeclt
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Run `pf2tw` in a directory containing the files to convert.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
prime pf2tw
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`pf2tw` was written for Tailwind v3. Tailwind v4 renamed a few of the utilities it produces, for example `shadow-sm` to `shadow-xs`, `rounded` to `rounded-sm` and `flex-grow` to `grow`. On Tailwind
|
|
29
|
+
v4, check the converted classes against the [renamed utilities](https://tailwindcss.com/docs/upgrade-guide#renamed-utilities) list of the Tailwind upgrade guide.
|
|
30
|
+
|
|
31
|
+
A handful of PrimeFlex classes have no Tailwind counterpart and are left alone. Replace them with flexbox or grid utilities by hand:
|
|
32
|
+
|
|
33
|
+
- formgrid
|
|
34
|
+
- formgroup
|
|
35
|
+
- formgroup-inline
|
|
36
|
+
- col
|
|
37
|
+
- col-fixed
|
|
38
|
+
- field
|
|
39
|
+
- field-checkbox
|
|
40
|
+
- field-radiobutton
|
|
41
|
+
- reset
|
|
12
42
|
|
|
13
43
|
## Overview
|
|
14
44
|
|
|
15
|
-
PrimeFlex was PrimeTek's lightweight CSS utility library, designed to accompany PrimeNG. PrimeTek stopped maintaining it before the relicensing, on the
|
|
45
|
+
[PrimeFlex](https://primeflex.org) was PrimeTek's lightweight CSS utility library, designed to accompany PrimeNG. PrimeTek stopped maintaining it before the relicensing, on the
|
|
46
|
+
grounds that most applications already bring their own utility layer — Tailwind, Bootstrap or something in-house — and a second one only overlaps with it.
|
|
47
|
+
|
|
48
|
+
ExhaustiveUI does not maintain PrimeFlex either, and for the same reason. Nothing in this library depends on it, and no component requires it. If your application already uses PrimeFlex it will keep working, but it will not receive
|
|
49
|
+
updates from us, and we suggest moving to Tailwind CSS.
|
|
16
50
|
|
|
17
51
|
## Tailwindcss
|
|
18
52
|
|
|
19
|
-
Tailwind CSS is the replacement we suggest. This documentation site is itself built with it, and we publish
|
|
53
|
+
Tailwind CSS is the replacement we suggest. This documentation site is itself built with it, and we publish `@exhaustive-ui/tailwindcss` for first-class integration — a plugin that teaches Tailwind about the theme's design
|
|
54
|
+
tokens and puts the component styles in a cascade layer you can override cleanly.
|
|
55
|
+
|
|
56
|
+
See the [Tailwind CSS guide](https://exhaustive-ui.com/tailwind) for setup with either Tailwind v3 or v4, and the next section for converting existing PrimeFlex classes.
|
|
20
57
|
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Migrating from PrimeNG
|
|
2
|
+
|
|
3
|
+
Moving a PrimeNG v21 application to ExhaustiveUI: the migrate-from-primeng schematic, what it changes (packages, imports, configuration API, icons, CSS layer), the manual checks and the v22 migrations.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
ExhaustiveUI is an MIT fork of PrimeNG v21, the last PrimeNG release published under the MIT license, by way of Optimus UI. The components, their selectors, the `p-*` CSS classes, the design tokens and the `pi pi-*` icon
|
|
8
|
+
classes are the same, so a PrimeNG v21 application moves across in two parts:
|
|
9
|
+
|
|
10
|
+
1. **The switch**: other package names, a configuration API named after ExhaustiveUI, another icon package and another default CSS layer name. The `migrate-from-primeng` schematic does it.
|
|
11
|
+
2. **The v22 changes**: Angular 22, the Signals API, OnPush and the API cleanup of ExhaustiveUI v22. The `ng update` migrations do most of it, and the [migration guide to v22](https://exhaustive-ui.com/migration/v22) covers the rest.
|
|
12
|
+
|
|
13
|
+
No license is needed. A PrimeTek license or subscription for PrimeNG, its templates or its theme designer does not carry over, and is not required.
|
|
14
|
+
|
|
15
|
+
## Before you start
|
|
16
|
+
|
|
17
|
+
- **PrimeNG v21.** ExhaustiveUI shares its API. On v20 or older, upgrade to v21 first with PrimeNG's own update guides; the schematic checks the installed version and stops otherwise. On PrimeNG v22, the schematic runs, but the features PrimeNG added after v21 have no ExhaustiveUI equivalent: check the compiler errors and the report.
|
|
18
|
+
- **A clean git working tree**, so every change can be reviewed and reverted on its own, and a build and test run that passes before you start.
|
|
19
|
+
- **PrimeFlex**, if the project uses it, is not migrated by this schematic. Run `migrate-from-primeflex` afterwards to move its classes to Tailwind CSS; the schematic reminds you when it finds PrimeFlex.
|
|
20
|
+
|
|
21
|
+
## Migration steps
|
|
22
|
+
|
|
23
|
+
1. Update Angular to 22. PrimeNG v21 declares Angular 21 as its peer dependency, so the Angular CLI refuses the update while `primeng` is installed: pass `--force`. The next step removes `primeng`.
|
|
24
|
+
2. Install ExhaustiveUI and run the `migrate-from-primeng` schematic. It rewrites the workspace, then installs the new dependencies.
|
|
25
|
+
3. Run the v22 migrations. The workspace did not go through `ng update`, so they are run explicitly, from the version before v22.
|
|
26
|
+
4. Read both reports, fix the compiler errors, then build and run your tests.
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
ng update @angular/core@22 @angular/cli@22 --force
|
|
30
|
+
npm install @exhaustive-ui/core@22
|
|
31
|
+
ng generate @exhaustive-ui/core:migrate-from-primeng
|
|
32
|
+
ng update @exhaustive-ui/core --migrate-only --from=3.0.0
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The schematic takes two options: `--skip-install` leaves the install to you, and `--force` skips the PrimeNG version check.
|
|
36
|
+
|
|
37
|
+
## What the schematic changes
|
|
38
|
+
|
|
39
|
+
The schematic visits every file of the workspace except `node_modules`, build output and the files your `.gitignore` excludes.
|
|
40
|
+
|
|
41
|
+
### Dependencies
|
|
42
|
+
|
|
43
|
+
In every `package.json` of the workspace, including `overrides` and `resolutions`, each package is replaced by its counterpart:
|
|
44
|
+
|
|
45
|
+
- `primeng` becomes `@exhaustive-ui/core`
|
|
46
|
+
- `@primeuix/themes`, `@primeuix/styled`, `@primeuix/styles`, `@primeuix/utils` and `@primeuix/motion` become `@exhaustive-ui/themes`, `@exhaustive-ui/styled`, `@exhaustive-ui/styles`, `@exhaustive-ui/utils` and `@exhaustive-ui/motion`
|
|
47
|
+
- `tailwindcss-primeui` becomes `@exhaustive-ui/tailwindcss`
|
|
48
|
+
- `primelocale` becomes `@exhaustive-ui/locale`
|
|
49
|
+
- `primeicons` becomes `@openng/icons`
|
|
50
|
+
|
|
51
|
+
### TypeScript
|
|
52
|
+
|
|
53
|
+
Imports, dynamic imports and `require()` calls are rewritten, subpaths included (`primeng/button` becomes `@exhaustive-ui/core/button`, `@primeuix/themes/aura` becomes
|
|
54
|
+
`@exhaustive-ui/themes/aura`), and so is the Tailwind CSS configuration file. The configuration API is renamed where it is imported: `providePrimeNG` becomes `provideExhaustive`, the `PrimeNG` service becomes
|
|
55
|
+
`Exhaustive`, `PrimeNGConfigType` becomes `ExhaustiveConfigType`, and the `PrimeIcons` constants become `OpenngIcons`.
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
// Before
|
|
59
|
+
import { ApplicationConfig } from '@angular/core';
|
|
60
|
+
import { providePrimeNG } from 'primeng/config';
|
|
61
|
+
import Aura from '@primeuix/themes/aura';
|
|
62
|
+
|
|
63
|
+
export const appConfig: ApplicationConfig = {
|
|
64
|
+
providers: [providePrimeNG({ theme: { preset: Aura } })]
|
|
65
|
+
};
|
|
66
|
+
|
|
67
|
+
// After
|
|
68
|
+
import { ApplicationConfig } from '@angular/core';
|
|
69
|
+
import { provideExhaustive } from '@exhaustive-ui/core/config';
|
|
70
|
+
import Aura from '@exhaustive-ui/themes/aura';
|
|
71
|
+
|
|
72
|
+
export const appConfig: ApplicationConfig = {
|
|
73
|
+
providers: [provideExhaustive({ theme: { preset: Aura } })]
|
|
74
|
+
};
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Stylesheets and angular.json
|
|
78
|
+
|
|
79
|
+
`@import`, `@use`, `@plugin` and `url()` references in stylesheets, and the `styles` and `scripts` entries of `angular.json` and `project.json`, follow the new package names.
|
|
80
|
+
`primeicons/primeicons.css` becomes `@openng/icons/openng-icons.css`; the `pi pi-*` classes in templates do not change.
|
|
81
|
+
|
|
82
|
+
### CSS cascade layer
|
|
83
|
+
|
|
84
|
+
When the theme sets `cssLayer`, the `primeng` layer becomes `exhaustive` in its `name` and `order`, `primeng-overwrites` becomes `exhaustive-overwrites`, and the matching
|
|
85
|
+
`@layer` declarations in your stylesheets are renamed too, so your overrides keep their place in the layer order. With `cssLayer: true`, the configuration does not change, and only the stylesheets are renamed.
|
|
86
|
+
|
|
87
|
+
### The report
|
|
88
|
+
|
|
89
|
+
The schematic ends with the places that still mention `primeng`, `primeicons`, `@primeuix`, `tailwindcss-primeui` or `primelocale`, with the file and line: templates, Markdown, JSON or code it does not
|
|
90
|
+
rewrite. Lockfiles are left out of the report, since the install regenerates them.
|
|
91
|
+
|
|
92
|
+
## Manual checks
|
|
93
|
+
|
|
94
|
+
Besides the places listed in the report, check these by hand:
|
|
95
|
+
|
|
96
|
+
- **The icon font name.** A stylesheet that names the font directly, as in `font-family: 'primeicons'`, now needs `'openng-icons'`. The schematic does not touch declaration values.
|
|
97
|
+
- **Local variables named after PrimeNG**, such as `primeng = inject(PrimeNG)`: the type is renamed, the variable name is yours to keep or change.
|
|
98
|
+
- **Module paths passed to other functions**, such as `jest.mock('primeng/button')` or `vi.mock()`: only imports, dynamic imports and `require()` are rewritten. These appear in the report.
|
|
99
|
+
- **Build and deployment files** outside the TypeScript sources and stylesheets: Dockerfiles, CI scripts, CDN links to PrimeNG or PrimeIcons.
|
|
100
|
+
- **PrimeTek products** such as templates or the theme designer are not part of ExhaustiveUI. A preset built with them is a plain `definePreset()` object and keeps working once its imports point to `@exhaustive-ui/themes`.
|
|
101
|
+
|
|
102
|
+
## What changes in v22
|
|
103
|
+
|
|
104
|
+
After the switch, the application runs on ExhaustiveUI v22, which differs from PrimeNG v21 in ways the compiler and your tests will show. The [migration guide to v22](https://exhaustive-ui.com/migration/v22)
|
|
105
|
+
details each of them:
|
|
106
|
+
|
|
107
|
+
- Inputs, two-way properties, outputs and queries are signals: code holding a component instance reads inputs with a call and writes two-way properties with `.set()`.
|
|
108
|
+
- Components use OnPush change detection, except Table, TreeTable and DynamicDialog: give them new arrays and objects, or signals, rather than mutating bound data.
|
|
109
|
+
- Deprecated and inactive inputs are removed or renamed, `styleClass` becomes `class` on most components; the v22 migrations rewrite these bindings and report the rest.
|
|
110
|
+
- Hundreds of bugs inherited from PrimeNG v21 are fixed, each with a regression test; a few of them change a visible behavior.
|
|
111
|
+
|
|
112
|
+
## Checklist
|
|
113
|
+
|
|
114
|
+
- Angular 22 installed, and no `primeng`, `@primeuix/*`, `primeicons`, `tailwindcss-primeui` or `primelocale` left in any `package.json`.
|
|
115
|
+
- The report of `migrate-from-primeng` handled, then the report of the v22 migrations.
|
|
116
|
+
- Icons render: the stylesheet is `@openng/icons/openng-icons.css` and nothing names the `primeicons` font.
|
|
117
|
+
- With a CSS layer configured, your overrides still apply: the `@layer` names match the theme's `cssLayer` order.
|
|
118
|
+
- The application compiles and its tests pass, after the code changes of the migration guide to v22.
|
|
119
|
+
- PrimeFlex, if used, migrated with `migrate-from-primeflex`.
|
|
120
|
+
|
package/data/pages/rtl.md
CHANGED
|
@@ -4,7 +4,10 @@ Right-to-left support for ExhaustiveUI components.
|
|
|
4
4
|
|
|
5
5
|
## Configuration
|
|
6
6
|
|
|
7
|
-
The ExhaustiveUI components natively support Right-to-Left (RTL) text direction through a modern CSS implementation utilizing FlexBox and classes like
|
|
7
|
+
The ExhaustiveUI components natively support Right-to-Left (RTL) text direction through a modern CSS implementation utilizing FlexBox and classes like `*-inline-start` and `*-block-end`. Consequently, no JavaScript
|
|
8
|
+
configuration is necessary; setting the document's text direction to RTL is sufficient to enable this feature.
|
|
9
|
+
|
|
10
|
+
The RTL setting can either be set using the `dir` attribute or with the `direction` style property.
|
|
8
11
|
|
|
9
12
|
## Limitations
|
|
10
13
|
|