Skip to content

Commit

Permalink
updated changelog and readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexkatz
alexkatz committed Sep 12, 2024
1 parent b4c8a65 commit 76bef5d
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 17 deletions.
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
## [8.1.0] - 2024-9-12

### Changed

- `contentLocation` prop has been renamed to `positionTransform`, behaves exactly the same

## [8.0.3] - 2023-10-19

### Fixed
Expand Down
28 changes: 11 additions & 17 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
- [Demo](#demo)
- [Examples](#examples)
- [Hooks](#hooks)
- [Migrating to version 8](#migrating-to-version-8)
- [Migrating from versions 3 and 4](#migrating-from-versions-3-and-4)
- [Migrating to 8.0](#migrating-to-8.0)
- [Migrating to 5.0](#migrating-to-5.0)
- [API](#api)
- [Popover](#popover)
- [PopoverState](#popoverstate)
Expand All @@ -25,13 +25,7 @@ Since `react-tiny-popover` tries to be as non-invasive as possible, it will simp
## Install

```shell
yarn add react-tiny-popover
```

or

```shell
npm install react-tiny-popover --save
npm i react-tiny-popover --save
```

## [Demo](https://alexkatz.github.io/react-tiny-popover/)
Expand Down Expand Up @@ -213,7 +207,7 @@ After attaching `popoverRef` and `childRef` to the DOM, you can fire `positionPo
This is a bit more advanced, but play around and see what you can come up with! Feel free to examine the internal Popover component to see how the hook is used there.
## Migrating to version 8
## Migrating to 8.0
`react-tiny-popover` 8.0 removes the `contentLocation` prop and replaces it with a slightly more capable `transform` prop. By default, the `transform` prop behaves exactly as `contentLocation` did.
Expand Down Expand Up @@ -254,9 +248,9 @@ Now, you have access to an additional handy prop, `transformMode`:
The above popover will now render 20 pixels down and left of where it originally would have appeared without the transform, rather than at a fixed/absolute position.
The other `transformMode` value, `"absolute"` is the default value when `transformMode` is omitted. This produces the same behavior as `contentLocation` did.
The other `transformMode` value, `"absolute"` is the default value when `transformMode` is omitted. This produces the same behavior that `contentLocation` did.
## Migrating from versions 3 and 4
## Migrating to 5.0
`react-tiny-popover` 5 and up has abandoned use of `findDOMNode` to gain a reference to `Popover`'s target DOM node, and now explicitly relies on a ref. Since React has deprecated `findDOMNode` in `StrictMode`, now seems like an appropriate time to shift away from this under-the-hood logic toward a clearer and more declarative API.

Expand Down Expand Up @@ -314,7 +308,7 @@ Check out [React's ref forwarding API](https://reactjs.org/docs/forwarding-refs.
| align | `string` | | Possible values are `start`, `center`, and `end`. If `start` is specified, the popover content's top or left location is aligned with its target's. With `end` specified, the content's bottom or right location is aligned with its target's. If `center` is specified, the popover content and target's centers are aligned. Defaults to `center`. |
| ref | `React.Ref` | | Since `Popover` relies on ref forwarding to access its child, it's not simple to obtain a second reference to that child. This property acts as a "pass through" for you to obtain a ref to the child you've provided `Popover`. The value of the ref you provide here will be `Popover`'s child. |
| onClickOutside | `(e: MouseEvent) => void` | | If `react-tiny-popover` detects a click event outside of the target and outside of the popover, you may handle this event here. |
| clickOutsideCapture | `boolean ` | | This boolean represents the `useCapture` option passed along as the third argument to the internal `window.addEventListener` used by `onClickOutside`. |
| clickOutsideCapture | `boolean` | | This boolean represents the `useCapture` option passed along as the third argument to the internal `window.addEventListener` used by `onClickOutside`. |
| transform | `{ top: number; left: number}` or `(popoverState: PopoverState) => { top: number, left: number }` | | If you'd like to hook directly into the positioning process, you may do so here! `top` and `left` positions provided or returned here will override the popover content's (`popoverRect`) location in a fashion specified by the `transformMode` prop. |
| transformMode | `"absolute"` or `"relative"` | | A value of `"absolute"` will popsition the popover at precisely the `top` and `left` values provided by `transform`, relative to the `parentElement`. A value of `"relative"` will "nudge" the popover from where it would appear pre-transform by the `top` and `left` values provided in `transform`. |
| parentElement | `HTMLElement` | | Provide an HTML element ref here to have your popover content appended to that element rather than `document.body`. This is useful if you'd like your popover to sit at a particular place within the DOM. Supplying a `parentElement` ref will not in most cases directly affect the positioning of the popover. |
Expand All @@ -328,16 +322,16 @@ Check out [React's ref forwarding API](https://reactjs.org/docs/forwarding-refs.
| <b>Property<b> | Type | Description |
| -------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| isPositioned | `boolean` | After the popover has positioned its contents, this field is true. Prior, it is false. |
| childRect | `Rect` | The current rect of the popover's child (i.e., the source from which the popover renders). |
| popoverRect | `Rect` | The current rect of the popover's contents. |
| parentRect | `Rect` | The current rect of the popover child's parent. |
| childRect | `Rect` | The current rect of the popover's child (i.e., the source from which the popover renders). |
| popoverRect | `Rect` | The current rect of the popover's contents. |
| parentRect | `Rect` | The current rect of the popover child's parent. |
| position | `'left'` \| `'right'` \| `'top'` \| `'bottom'` \| `undefined` | The current position of the popover in relation to the child. `undefined` implies the user has set an absolute transform. |
| align | `'start'` \| `'center'` \| `'end'` \| `undefined` | The cross-axis alignment of the popover's contents. `undefined` implies the user has set an explicit `contentLocation`. |
| padding | `number` | The distance between the popover's child and contents. If set to zero, the two are touching. |
| nudgedLeft | `number` | If the popover's contents encounter a boundary violation that does not warrant a reposition, the contents are instead "nudged" by the appropriate top and left values to keep the contents within the boundary. This is the left value. |
| nudgedTop | `number` | If the popover's contents encounter a boundary violation that does not warrant a reposition, the contents are instead "nudged" by the appropriate top and left values to keep the contents within the boundary. This is the top value. |
| boundaryInset | `number` | The popover's contents will encounter boundary violations prior to the actual `parentElement`'s boundaries by this number in pixels. Can be negative. |
| boundaryRect | `Rect` | The current rect of the popover's boundaries. |
| boundaryRect | `Rect` | The current rect of the popover's boundaries. |
| transform | `{ top?: number; left?: number; }` \| undefined | The values you provided to the `transform` prop, if they exist. |
| violations | `{ top: number; left: number; bottom: number; right: number; }` | An object containing boundary violations. Expect a value of `0` if no boundary violation exists at that bound (i.e., your popover is entirely within that bound), and expect positive values representing pixels beyond that bound if a violation exists (i.e., your popover exceeds the `top` bound by ten pixels, `top` will be `10`). |
| hasViolations | `boolean` | `true` if violations exist at any boundary, `false` otherwise. |
Expand Down

0 comments on commit 76bef5d

Please sign in to comment.