@aglyn/shared-util-dom 1.0.0-beta.143 → 1.0.0-beta.144
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/README.md +50 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,7 +1,54 @@
|
|
|
1
1
|
# @aglyn/shared-util-dom
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
DOM measurement helpers and type guards: bounding and clipping rects, scroll parents, offset parents, the owning window of a node (including across iframes), and event coordinates. It is mainly an internal building block of the Besigner visual editor (`@aglyn/besigner-ui`) and of `@aglyn/shared-ui-next`, and is usable on its own.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> Beta. Published from the Aglyn monorepo under the `beta` dist-tag; APIs can change between beta releases.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
npm install @aglyn/shared-util-dom@beta
|
|
10
|
+
|
|
11
|
+
No peer dependencies. `mobx` and `rxjs` are regular dependencies, used only by the page-title controller.
|
|
12
|
+
|
|
13
|
+
## What's in it
|
|
14
|
+
|
|
15
|
+
Everything below is exported from the package root.
|
|
16
|
+
|
|
17
|
+
- Rect and geometry: `getElementClientRectBounding`, `getElementClientRectBoundingInner`, `getElementRectAsClientRect`, `getElementClippingRect`, `getElementViewportRect`, `getElementDocumentElementRect`, `getElementFragmentRects`, `getElementWindowScrollBarX`.
|
|
18
|
+
- Tree walking: `getElementScrollParent`, `getElementListScrollParents`, `getElementOffsetParent`, `getElementParentNode`, `getElementDocumentElement`, `getElementNodeName`, `getElementComputedStyle`.
|
|
19
|
+
- Windows and frames: `getNodeWindow`, `getNodeWindowScroll`, `getIframeDocument`. These resolve the window that owns a node rather than assuming the global one, so they work on elements inside an iframe.
|
|
20
|
+
- Events: `getEventCoordinates`, `eventHasViewportCoordinates`, `isTouchEvent`, `isKeyboardEvent`.
|
|
21
|
+
- Guards: `isNodeObject`, `isNodeElement`, `isElementHTMLElement`, `isSVGElement`, `isNodeShadowRoot`, `isNodeTableElement`, `isNodeDocument`, `isElementWindow`, `isElementScrollParentElement`, `elementContainsChildElement`.
|
|
22
|
+
- Types and constants: `Rect`, `ClientRectObject`, `Coordinates`, `VirtualElement`, `Boundary`, `RootBoundary`, and the `clippingParents` / `viewport` constants.
|
|
23
|
+
- A page-title controller: `PageTitle` (a MobX observable class), the shared instance `$title`, the RxJS observable `$pageTitle`, and the setters `setScreenName`, `setScreenNumber`, `setScreenSuffix`, `setScreenSeparator`, `setScreenTitle`.
|
|
24
|
+
|
|
25
|
+
Each file under `src/lib` is also importable by subpath, for example `@aglyn/shared-util-dom/get-element-scroll-parent` or `@aglyn/shared-util-dom/guards/is-touch-event`. `getOwnerDocument` is available only that way, as `@aglyn/shared-util-dom/get-owner-document`.
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import {
|
|
31
|
+
getElementListScrollParents,
|
|
32
|
+
getEventCoordinates,
|
|
33
|
+
getNodeWindow,
|
|
34
|
+
} from '@aglyn/shared-util-dom'
|
|
35
|
+
|
|
36
|
+
function onPointerDown(event: PointerEvent) {
|
|
37
|
+
const { x, y } = getEventCoordinates(event)
|
|
38
|
+
const win = getNodeWindow(event.target)
|
|
39
|
+
const scrollers = getElementListScrollParents(event.target as Element)
|
|
40
|
+
// ...
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Import-time effect
|
|
45
|
+
|
|
46
|
+
This package imports the root of `@aglyn/shared-util-tools`, and that root defines a set of non-enumerable `$_`-prefixed methods on `Array.prototype` when it loads. See that package's README for the exact list.
|
|
47
|
+
|
|
48
|
+
## How it fits
|
|
49
|
+
|
|
50
|
+
A `shared` package: generic, with no knowledge of Aglyn's model. Shared packages may only import other shared packages; this one depends on `@aglyn/shared-util-tools`. `@aglyn/besigner-ui` and `@aglyn/shared-ui-next` depend on it.
|
|
51
|
+
|
|
52
|
+
## License
|
|
53
|
+
|
|
54
|
+
Apache-2.0. Source: https://github.com/aglyn/aglyn/tree/main/libs/shared/util/dom
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aglyn/shared-util-dom",
|
|
3
|
-
"version": "1.0.0-beta.
|
|
3
|
+
"version": "1.0.0-beta.144",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"homepage": "https://aglyn.com",
|
|
6
6
|
"repository": {
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"./package.json": "./package.json"
|
|
26
26
|
},
|
|
27
27
|
"dependencies": {
|
|
28
|
-
"@aglyn/shared-util-tools": "1.0.0-beta.
|
|
28
|
+
"@aglyn/shared-util-tools": "1.0.0-beta.144",
|
|
29
29
|
"@swc/helpers": "0.5.23",
|
|
30
30
|
"mobx": "^6.16.1",
|
|
31
31
|
"rxjs": "^7.8.2"
|