Skip to content

Commit

Permalink
Merge pull request #65 from tonysamperi/v17-floating-ui
Browse files Browse the repository at this point in the history 
V17
  • Loading branch information
@tonysamperi
tonysamperi authored Nov 8, 2023
2 parents 3708eac + 4f63b70 commit cc26fc0
Show file tree
Hide file tree
Showing 34 changed files with 2,874 additions and 1,764 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/gh-pages.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ jobs:
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: "16.16.0"
node-version: "20.9.0"
cache: ${{ steps.detect-package-manager.outputs.manager }}
- name: Restore cache
uses: actions/cache@v3
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/main.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ jobs:

strategy:
matrix:
node-version: [16.x]
node-version: [20.9.0]
# See supported Node.js release schedule at https://nodejs.org/en/about/releases/
steps:
- uses: actions/checkout@v3
Expand Down
101 changes: 59 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,40 @@

[![npm][badge-npm-version]][url-npm] [![npm][badge-npm-downloads]][url-npm] [![MIT licensed][badge-licence]][url-licence] [![Build state][badge-ci-state]][url-ci-state] [![Size][badge-bundle]][url-bundle] [![Rate this package][badge-openbase]][url-openbase]

ngx-popperjs is an angular wrapper for the [Popper.js](https://popper.js.org/) library.

*Note* that I also updated everything to use **Popper 2** (v *2.4.4* in v 9.0.0)
ngx-popperjs is an angular wrapper for the [FloatingUI](https://floating-ui.com/) library (v ^1.5.3).

## VERY IMPORTANT READ THIS
I'm moving this to the top because it appears that people don't get to reading it in the **contribute** section.
FOR THIS LIBRARY **PLEASE USE ISSUES ONLY FOR BUG REPORTING**. DON'T OPEN ISSUES SUCH AS "I need upgrade for Angular 1745646456" especially if Angular 1745646456 was released a few days ago.
I **guarantee** that I manage the updates **AS SOON AS POSSIBLE**. But as you understand this is not a paying job, so you can't get Angular 1745646456 the day it gets released.
**ISSUES NOT RESPECTING THIS WILL BE DELETED IMMEDIATELY WITHOUT ANY RESPONSE**.
Thank you.
With v17 ngx-popperjs **won't get any updates**. That's because from v17 it's not actually using popper.js anymore.

I developed ngx-float-ui and released v17 at the same time of this.
My suggestion is to migrate to that one. In 6 months from the release, this version will be marked as **deprecated**.
Since the new library isn't affected by the "Chrome 110 bug" I would suggest to migrate earlier versions as well.
If you open an issue on ngx-float-ui asking for a certain version (or search for an open issue for that version and leave a thumb), I will publish earlier versions as well.

## NOW USING FLOATING UI - UPGRADING TO v17
If you used previous versions of ngx-popperjs, you'll now that it wrapped popper.js initially.
Since Floating UI is the future version of Popper.js and since latest happenings with recent Chrome updates breaking ngx-popperjs, I decided to move to the newer technology.

What impacts does it have for the library?

Well on a graphic perspective, none. You will be able to use the v17 without changing any stylings.

The only deprecation is in the `NgxPopperjsOptions` which now doesn't provide the **modifiers**.
The reason is that **you can't now pass modifiers** like you did in Popper.js.
It didn't seem like a huge change, since in this library modifiers should be mostly (but let me know with an issue) for preventing the popper flipping.
Maybe if we see that it can be useful we can pass an override for the `middleware`.

I simply added a new attribute, `popperFlip`, that you can set to false, in order to prevent the flipping (default `true`).

Check NgxPopperjs official [page](https://tonysamperi.github.io/ngx-popperjs) to stay up to date!

### Premise

The goal of this library is to take Mr Frankel's [ngx-popper](https://github.com/MrFrankel/ngx-popper/) and update the compatibility for more recent versions of Angular.
Since the old library is compatible with Angular 7 and earlier, I started with Angular 8.
If you need to work with an older version of Angular (5 to 7), please refer to Mr Frankel's [ngx-popper](https://github.com/MrFrankel/ngx-popper/).

### Premise, new in v 15.2.0: popperLoose
### From v15.2.0:

Since many complained about using the `NgxPopperjsPlacements` enum, I added a version of the popper directive which accepts a plain string as placement!
Now you can use it with all the options of the classic popper, but you'll have to use:
Expand All @@ -35,13 +53,13 @@ node and npm are required to run this package.
1. Use npm/yarn to install the package:

```terminal
$ npm install @popperjs/core ngx-popperjs --save
$ npm install @floating-ui/dom ngx-popperjs --save
```

Or

```terminal
$ yarn add @popperjs/core --save
$ yarn add @floating-ui/dom --save
$ yarn add ngx-popperjs --save
```

Expand Down Expand Up @@ -86,7 +104,7 @@ body {
<div [popper]="popper1Content"
[popperShowOnStart]="true"
[popperTrigger]="'click'"
[popperHideOnClickOutside]="true"
popperHideOnClickOutside
[popperHideOnScroll]="true"
[popperPlacement]="'bottom'">
<p class="bold">Hey!</p>
Expand All @@ -109,7 +127,7 @@ body {
<div popper="{{someTextProperty}}"
[popperTrigger]="'hover'"
[popperPlacement]="'bottom'"
[popperStyles]="{'background-color: 'blue''}",
[popperStyles]="{'background-color: 'blue''}"
(popperOnShown)="onShown($event)">
<p class="bold">Pop</p>
<p class="thin">on the bottom</p>
Expand Down Expand Up @@ -157,34 +175,34 @@ body {

8. Attributes map:

| Option | Type | Default | Description |
|:----------------------- |:---------------- |:--------- | :------------------------------------------------------------------------------------------------------ |
| popperDisableAnimation | boolean | false | Disable the default animation on show/hide |
| popperDisableStyle | boolean | false | Disable the default styling |
| popperDisabled | boolean | false | Disable the popper, ignore all events |
| popperDelay | number | 0 | Delay time until popper it shown |
| popperTimeout | number | 0 | Set delay before the popper is hidden |
| popperTimeoutAfterShow | number | 0 | Set a time on which the popper will be hidden after it is shown |
| popperPlacement | Placement(string) | auto | The placement to show the popper relative to the reference element |
| popperTarget | HtmlElement | auto | Specify a different reference element other the the one hosting the directive |
| popperBoundaries | string(selector) | undefined | Specify a selector to serve as the boundaries of the element |
| popperShowOnStart | boolean | false | Popper default to show |
| popperTrigger | Trigger(string) | click | Trigger/Event on which to show/hide the popper |
| popperPositionFixed | boolean | false | Set the popper element to use position: fixed |
| popperAppendTo | string | undefined | append The popper-content element to a given selector, if multiple will apply to first |
| popperPreventOverflow | boolean | undefined | Prevent the popper from being positioned outside the boundary |
| popperHideOnClickOutside | boolean | true | Popper will hide on a click outside |
| popperHideOnScroll | boolean | false | Popper will hide on scroll |
| popperHideOnMouseLeave | boolean | false | Popper will hide on mouse leave |
| popperModifiers | popperModifier | undefined | popper.js custom modifiers hock |
| popperApplyClass | string | undefined | list of comma separated class to apply on ngpx__container |
| popperStyles | Object | undefined | Apply the styles object, aligned with ngStyles |
| popperApplyArrowClass | string | undefined | list of comma separated class to apply on ngpx__arrow |
| popperOnShown | EventEmitter<> | $event | Event handler when popper is shown |
| popperOnHidden | EventEmitter<> | $event | Event handler when popper is hidden |
| popperOnUpdate | EventEmitter<> | $event | Event handler when popper is updated |
| popperAriaDescribeBy | string | undefined | Define value for aria-describeby attribute |
| popperAriaRole | string | popper | Define value for aria-role attribute |
| Option | Type | Default | Description |
|:-------------------------|:------------------|:----------|:---------------------------------------------------------------------------------------|
| popperDisableAnimation | boolean | false | Disable the default animation on show/hide |
| popperDisableStyle | boolean | false | Disable the default styling |
| popperDisabled | boolean | false | Disable the popper, ignore all events |
| popperDelay | number | 0 | Delay time until popper it shown |
| popperTimeout | number | 0 | Set delay before the popper is hidden |
| popperTimeoutAfterShow | number | 0 | Set a time on which the popper will be hidden after it is shown |
| popperPlacement | Placement(string) | auto | The placement to show the popper relative to the reference element |
| popperTarget | HtmlElement | auto | Specify a different reference element other the the one hosting the directive |
| popperBoundaries | string(selector) | undefined | Specify a selector to serve as the boundaries of the element |
| popperShowOnStart | boolean | false | Popper default to show |
| popperTrigger | Trigger(string) | click | Trigger/Event on which to show/hide the popper |
| popperPositionFixed | boolean | false | Set the popper element to use position: fixed |
| popperAppendTo | string | undefined | append The popper-content element to a given selector, if multiple will apply to first |
| popperPreventOverflow | boolean | undefined | Prevent the popper from being positioned outside the boundary |
| popperHideOnClickOutside | boolean | true | Popper will hide on a click outside |
| popperHideOnScroll | boolean | false | Popper will hide on scroll |
| popperHideOnMouseLeave | boolean | false | Popper will hide on mouse leave |
| popperApplyClass | string | undefined | list of comma separated class to apply on ngpx__container |
| popperStyles | Object | undefined | Apply the styles object, aligned with ngStyles |
| popperApplyArrowClass | string | undefined | list of comma separated class to apply on ngpx__arrow |
| popperOnShown | EventEmitter<> | $event | Event handler when popper is shown |
| popperOnHidden | EventEmitter<> | $event | Event handler when popper is hidden |
| popperOnUpdate | EventEmitter<> | $event | Event handler when popper is updated |
| popperAriaDescribeBy | string | undefined | Define value for aria-describeby attribute |
| popperAriaRole | string | popper | Define value for aria-role attribute |
| popperFlip | boolean | true | Enable or disable the flipping |


9. Override defaults:
Expand Down Expand Up @@ -212,7 +230,6 @@ NgModule({
| placement | Placement(string) | auto |
| boundariesElement | string(selector) | undefined |
| trigger | Trigger(string) | hover |
| popperModifiers | popperModifier | undefined |
| positionFixed | boolean | false |
| hideOnClickOutside | boolean | true |
| hideOnMouseLeave | boolean | false |
Expand Down
8 changes: 4 additions & 4 deletions angular.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,22 +118,22 @@
"serve": {
"builder": "@angular-devkit/build-angular:dev-server",
"options": {
"browserTarget": "ngx-popperjs-repo:build"
"buildTarget": "ngx-popperjs-repo:build"
},
"configurations": {
"development": {
"browserTarget": "ngx-popperjs-repo:build:dev"
"buildTarget": "ngx-popperjs-repo:build:dev"
},
"production": {
"browserTarget": "ngx-popperjs-repo:build:production"
"buildTarget": "ngx-popperjs-repo:build:production"
}
},
"defaultConfiguration": "development"
},
"extract-i18n": {
"builder": "@angular-devkit/build-angular:extract-i18n",
"options": {
"browserTarget": "ngx-popperjs-repo:build"
"buildTarget": "ngx-popperjs-repo:build"
}
},
"test": {
Expand Down
3 changes: 3 additions & 0 deletions changelog.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
#17.0.0
* Update for Angular 17! 🎉

#16.0.6
* The final fix of the "Chrome 115.0.5790.102 bug" reverting the original behaviour
* Refine tests
Expand Down
4 changes: 4 additions & 0 deletions gulpfile.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,10 @@ task("bump:major", () => {
return doBump("major");
});

gulp.task("bump:beta", () => {
return doBump("prerelease", "beta");
});

task("build++", () => {
return gulp.src(join(__dirname, "package.json"))
.pipe(obj((file, enc, cb) => {
Expand Down
Loading

0 comments on commit cc26fc0

Please sign in to comment.