@augment-vir/web 30.0.0 → 30.0.2

package/README.md

@@ -0,0 +1,9 @@
+# @augment-vir/web
+
+A collection of augments, helpers types, functions, and classes only for web (frontend) JavaScript environments.
+
+-   Includes a `querySelector` implementation that works with Shadow DOM: [`queryThroughShadow`](https://electrovir.github.io/augment-vir/functions/queryThroughShadow.html).
+-   Includes an easy way to list all nested children of an element: [`getNestedChildren`](https://electrovir.github.io/augment-vir/functions/getNestedChildren.html).
+-   and much more!
+
+See the docs under `Web`, `Web : Elements`, or `Package: @augment-vir/web` here: https://electrovir.github.io/augment-vir

package/dist/augments/animation-frame.d.ts

@@ -1 +1,9 @@
+/**
+ * Wait for an animation frame's duration. Optionally, wait for multiple frames by providing a
+ * `frameCount` input.
+ *
+ * @category Web
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function waitForAnimationFrame(frameCount?: number): Promise<void>;

package/dist/augments/animation-frame.js

@@ -1,4 +1,12 @@
 import { DeferredPromise } from '@augment-vir/common';
+/**
+ * Wait for an animation frame's duration. Optionally, wait for multiple frames by providing a
+ * `frameCount` input.
+ *
+ * @category Web
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export async function waitForAnimationFrame(frameCount = 1) {
     const deferredPromise = new DeferredPromise();
     function requestNextFrame() {

package/dist/augments/elements/element-children.d.ts

@@ -6,6 +6,10 @@
  *
  * Optionally define a second "depth" input to control how far nestings should be pursued. Leave
  * depth out or set it to undefined or any value <= 0 to allow full depth search.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
  */
 export declare function getNestedChildren(startingElement: Readonly<Element>, depth?: number | undefined): Element[];
 /**
@@ -15,5 +19,9 @@ export declare function getNestedChildren(startingElement: Readonly<Element>, de
  *
  * Note that that slotted elements and light dom elements will always be shown above shadow dom
  * elements. Besides that, the order of children is preserved.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
  */
 export declare function getDirectChildren(startingElement: Readonly<Element>): Element[];

package/dist/augments/elements/element-children.js

@@ -6,6 +6,10 @@
  *
  * Optionally define a second "depth" input to control how far nestings should be pursued. Leave
  * depth out or set it to undefined or any value <= 0 to allow full depth search.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
  */
 export function getNestedChildren(startingElement, depth) {
     return recursivelyGetNestedChildren(startingElement, depth ?? 0, 0);
@@ -30,6 +34,10 @@ function recursivelyGetNestedChildren(startingElement, maxDepth, currentDepth) {
  *
  * Note that that slotted elements and light dom elements will always be shown above shadow dom
  * elements. Besides that, the order of children is preserved.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
  */
 export function getDirectChildren(startingElement) {
     return [

package/dist/augments/elements/element-focus.d.ts

@@ -1 +1,8 @@
+/**
+ * Detects whether the given element is currently focused.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function isElementFocused(element: Element): boolean;

package/dist/augments/elements/element-focus.js

@@ -1,3 +1,10 @@
+/**
+ * Detects whether the given element is currently focused.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function isElementFocused(element) {
     return element.matches(':focus');
 }

package/dist/augments/elements/element-parent.d.ts

@@ -1,2 +1,16 @@
+/**
+ * Gets the parent element of the current element, even if the current element is a `ShadowRoot`.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function getParentElement(element: Node): Element | undefined;
+/**
+ * Recursively search for an ancestor of the starting element that passes the given callback.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function findMatchingAncestor(start: Element, testParent: (parent: Element) => boolean): Element | undefined;

package/dist/augments/elements/element-parent.js

@@ -1,3 +1,10 @@
+/**
+ * Gets the parent element of the current element, even if the current element is a `ShadowRoot`.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function getParentElement(element) {
     if (element instanceof ShadowRoot) {
         return getParentElement(element.host);
@@ -13,6 +20,13 @@ export function getParentElement(element) {
         return getParentElement(parentNode);
     }
 }
+/**
+ * Recursively search for an ancestor of the starting element that passes the given callback.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function findMatchingAncestor(start, testParent) {
     if (testParent(start)) {
         return start;

package/dist/augments/elements/element-position.d.ts

@@ -1,5 +1,38 @@
 import type { Coords } from '@augment-vir/common';
+/**
+ * Checks if the current element is completely visible in its scroll view.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function checkIfEntirelyInScrollView(element: Element): Promise<unknown>;
-export declare function checkIfInScrollView(element: Element, ratio: number): Promise<unknown>;
+/**
+ * Check if the given element is visible in its scroll container to the degree of the given ratio.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
+export declare function checkIfInScrollView(element: Element, 
+/** A number from 0-1, representing 0% to 100%. */
+ratio: number): Promise<unknown>;
+/**
+ * Get the center of the current element. This is a relatively expensive operation as it uses
+ * [`.getBoundingClientRect()`](https://developer.mozilla.org/docs/Web/API/Element/getBoundingClientRect)
+ * so this should not be called excessively.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function getCenterOfElement(element: Element): Coords;
+/**
+ * Useful for debugging purposes, this sticks an absolutely positioned and brightly colored div at
+ * the given position.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function appendPositionDebugDiv(position: Coords): HTMLDivElement;

package/dist/augments/elements/element-position.js

@@ -1,8 +1,24 @@
 import { assert } from '@augment-vir/assert';
+/**
+ * Checks if the current element is completely visible in its scroll view.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export async function checkIfEntirelyInScrollView(element) {
     return checkIfInScrollView(element, 1);
 }
-export async function checkIfInScrollView(element, ratio) {
+/**
+ * Check if the given element is visible in its scroll container to the degree of the given ratio.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
+export async function checkIfInScrollView(element, 
+/** A number from 0-1, representing 0% to 100%. */
+ratio) {
     return new Promise((resolve) => {
         const observer = new IntersectionObserver((entries, observerItself) => {
             assert.isLengthAtLeast(entries, 1);
@@ -12,6 +28,15 @@ export async function checkIfInScrollView(element, ratio) {
         observer.observe(element);
     });
 }
+/**
+ * Get the center of the current element. This is a relatively expensive operation as it uses
+ * [`.getBoundingClientRect()`](https://developer.mozilla.org/docs/Web/API/Element/getBoundingClientRect)
+ * so this should not be called excessively.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function getCenterOfElement(element) {
     const rect = element.getBoundingClientRect();
     return {
@@ -19,6 +44,14 @@ export function getCenterOfElement(element) {
         y: Math.floor((rect.bottom + rect.top) / 2),
     };
 }
+/**
+ * Useful for debugging purposes, this sticks an absolutely positioned and brightly colored div at
+ * the given position.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function appendPositionDebugDiv(position) {
     const div = document.createElement('div');
     div.classList.add('debug');

package/dist/augments/elements/element-text.d.ts

@@ -1 +1,8 @@
+/**
+ * Extracts the text content of the given element or shadow root.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function extractElementText(element: Element | ShadowRoot): string;

package/dist/augments/elements/element-text.js

@@ -1,3 +1,10 @@
+/**
+ * Extracts the text content of the given element or shadow root.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function extractElementText(element) {
     const value = element.value;
     const shadowRoot = element.shadowRoot;

package/dist/augments/elements/element-visibility.d.ts

@@ -1,2 +1,8 @@
-/** Detects `display: none` and only works if the element does not have `position: fixed;`. */
+/**
+ * Detects `display: none` and only works if the element does not have `position: fixed;`.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function isElementVisible(element: HTMLElement): boolean;

package/dist/augments/elements/element-visibility.js

@@ -1,4 +1,10 @@
-/** Detects `display: none` and only works if the element does not have `position: fixed;`. */
+/**
+ * Detects `display: none` and only works if the element does not have `position: fixed;`.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function isElementVisible(element) {
     // https://stackoverflow.com/a/21696585
     return element.offsetParent !== null;

package/dist/augments/{event-target.d.ts → elements/event-target.d.ts}

@@ -1,5 +1,20 @@
 import { PartialWithUndefined } from '@augment-vir/common';
 import { Constructor } from 'type-fest';
+/**
+ * Extract the event target element from an Event.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @example
+ *
+ * ```ts
+ * element.addEventListener('click', (event) => {
+ *     const eventTarget = extractEventTarget(event, HTMLButtonElement);
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function extractEventTarget<ExpectedTargetClassConstructor extends Constructor<Element>>(event: Event, expectedTargetClass: ExpectedTargetClassConstructor, options?: PartialWithUndefined<{
     /**
      * By default `extractEventTarget` uses the `Event.currentTarget` field to extract the event

package/dist/augments/{event-target.js → elements/event-target.js}

@@ -1,3 +1,18 @@
+/**
+ * Extract the event target element from an Event.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @example
+ *
+ * ```ts
+ * element.addEventListener('click', (event) => {
+ *     const eventTarget = extractEventTarget(event, HTMLButtonElement);
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function extractEventTarget(event, expectedTargetClass, options = {}) {
     const target = options.useOriginalTarget ? event.target : event.currentTarget;
     if (!(target instanceof expectedTargetClass)) {

package/dist/augments/elements/overflow.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Finds the given element's ancestor which allows Y overflow.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
+export declare function findOverflowAncestor(start: Element): Element;

package/dist/augments/elements/{overflow-parent.js → overflow.js}

@@ -1,5 +1,12 @@
 import { findMatchingAncestor, getParentElement } from './element-parent.js';
-export function findOverflowParent(start) {
+/**
+ * Finds the given element's ancestor which allows Y overflow.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
+export function findOverflowAncestor(start) {
     const parentElement = getParentElement(start);
     return ((parentElement &&
         findMatchingAncestor(parentElement, (element) => {

package/dist/augments/{query-through-shadow.d.ts → elements/query-through-shadow.d.ts}

@@ -1,4 +1,11 @@
 import type { PartialWithUndefined } from '@augment-vir/common';
+/**
+ * Options for {@link queryThroughShadow}.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export type QueryThroughShadowOptions = PartialWithUndefined<{
     all: boolean;
 }>;

package/dist/augments/{query-through-shadow.js → elements/query-through-shadow.js}

@@ -1,5 +1,13 @@
 import { check } from '@augment-vir/assert';
 import { stringify } from '@augment-vir/core';
+/**
+ * Perform [`.querySelector()`](https://developer.mozilla.org/docs/Web/API/Document/querySelector)
+ * on the given element with support for elements that contain an open Shadow Root.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export function queryThroughShadow(element, rawQuery, options) {
     if (!rawQuery) {
         if (element instanceof Element) {

package/dist/augments/elements/tag-or-definition.d.ts

@@ -4,5 +4,9 @@ import { SpecTagName } from 'html-spec-tags';
  * Reduce an element down to its tag name or its element definition if it's a custom element defined
  * by element-vir. Note that the types for this won't work in your project if you use custom element
  * tag names that aren't generated via element-vir.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
  */
 export declare function toTagOrDefinition(element: Element): DeclarativeElementDefinition | SpecTagName;

package/dist/augments/elements/tag-or-definition.js

@@ -4,6 +4,10 @@ import { ensureSpecTagName } from 'html-spec-tags';
  * Reduce an element down to its tag name or its element definition if it's a custom element defined
  * by element-vir. Note that the types for this won't work in your project if you use custom element
  * tag names that aren't generated via element-vir.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
  */
 export function toTagOrDefinition(element) {
     if (element instanceof DeclarativeElement) {

package/dist/augments/elements/text-dimensions.d.ts

@@ -1,5 +1,13 @@
 import { Dimensions, type PartialWithUndefined } from '@augment-vir/common';
 import type { AnyDuration } from '@date-vir/duration';
+/**
+ * Calculate the dimensions needed for an element's text. This is a relatively expensive operation,
+ * so it should not be called excessively.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function calculateTextDimensions(parentElement: Element, text: string, customOptions?: PartialWithUndefined<{
     timeout: AnyDuration;
     errorMessage: string;

package/dist/augments/elements/text-dimensions.js

@@ -1,4 +1,12 @@
 import { waitUntil } from '@augment-vir/assert';
+/**
+ * Calculate the dimensions needed for an element's text. This is a relatively expensive operation,
+ * so it should not be called excessively.
+ *
+ * @category Web : Elements
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export async function calculateTextDimensions(parentElement, text, customOptions) {
     if (!text) {
         return {

package/dist/augments/image.d.ts

@@ -1 +1,8 @@
+/**
+ * Load an image from a URL and wait for it to be totally loaded.
+ *
+ * @category Web
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function loadImage(imageUrl: string): Promise<HTMLImageElement>;

package/dist/augments/image.js

@@ -1,4 +1,11 @@
 import { DeferredPromise } from '@augment-vir/common';
+/**
+ * Load an image from a URL and wait for it to be totally loaded.
+ *
+ * @category Web
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export async function loadImage(imageUrl) {
     const deferredPromise = new DeferredPromise();
     const newImage = new Image();

package/dist/augments/video.d.ts

@@ -1 +1,8 @@
+/**
+ * Load a video from a URL and wait for it to be totally loaded.
+ *
+ * @category Web
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export declare function loadVideo(videoUrl: string): Promise<HTMLVideoElement>;

package/dist/augments/video.js

@@ -1,4 +1,11 @@
 import { DeferredPromise } from '@augment-vir/common';
+/**
+ * Load a video from a URL and wait for it to be totally loaded.
+ *
+ * @category Web
+ * @category Package : @augment-vir/web
+ * @package [`@augment-vir/web`](https://www.npmjs.com/package/@augment-vir/web)
+ */
 export async function loadVideo(videoUrl) {
     const deferredPromise = new DeferredPromise();
     const videoElement = document.createElement('video');

package/dist/index.d.ts

@@ -5,10 +5,10 @@ export * from './augments/elements/element-parent.js';
 export * from './augments/elements/element-position.js';
 export * from './augments/elements/element-text.js';
 export * from './augments/elements/element-visibility.js';
-export * from './augments/elements/overflow-parent.js';
+export * from './augments/elements/event-target.js';
+export * from './augments/elements/overflow.js';
+export * from './augments/elements/query-through-shadow.js';
 export * from './augments/elements/tag-or-definition.js';
 export * from './augments/elements/text-dimensions.js';
-export * from './augments/event-target.js';
 export * from './augments/image.js';
-export * from './augments/query-through-shadow.js';
 export * from './augments/video.js';

package/dist/index.js

@@ -5,10 +5,10 @@ export * from './augments/elements/element-parent.js';
 export * from './augments/elements/element-position.js';
 export * from './augments/elements/element-text.js';
 export * from './augments/elements/element-visibility.js';
-export * from './augments/elements/overflow-parent.js';
+export * from './augments/elements/event-target.js';
+export * from './augments/elements/overflow.js';
+export * from './augments/elements/query-through-shadow.js';
 export * from './augments/elements/tag-or-definition.js';
 export * from './augments/elements/text-dimensions.js';
-export * from './augments/event-target.js';
 export * from './augments/image.js';
-export * from './augments/query-through-shadow.js';
 export * from './augments/video.js';

package/package.json

@@ -1,6 +1,16 @@
 {
     "name": "@augment-vir/web",
-    "version": "30.0.0",
+    "version": "30.0.2",
+    "description": "A collection of augments, helpers types, functions, and classes only for web (frontend) JavaScript environments.",
+    "keywords": [
+        "augment",
+        "helper",
+        "util",
+        "browser",
+        "frontend",
+        "vir",
+        "augment-vir"
+    ],
     "homepage": "https://github.com/electrovir/augment-vir",
     "bugs": {
         "url": "https://github.com/electrovir/augment-vir/issues"
@@ -20,22 +30,20 @@
     "types": "dist/index.d.ts",
     "scripts": {
         "compile": "virmator compile",
-        "docs": "virmator docs",
         "test": "virmator --no-deps test web",
         "test:coverage": "virmator --no-deps test web coverage",
-        "test:docs": "virmator docs check",
         "test:update": "npm test"
     },
     "dependencies": {
-        "@augment-vir/assert": "^30.0.0",
-        "@augment-vir/common": "^30.0.0",
+        "@augment-vir/assert": "^30.0.2",
+        "@augment-vir/common": "^30.0.2",
         "@date-vir/duration": "^6.0.0",
         "html-spec-tags": "^2.2.0",
-        "type-fest": "^4.25.0"
+        "type-fest": "^4.26.1"
     },
     "devDependencies": {
-        "@augment-vir/test": "^30.0.0",
-        "typescript": "^5.5.4"
+        "@augment-vir/test": "^30.0.2",
+        "typescript": "^5.6.2"
     },
     "peerDependencies": {
         "element-vir": ">=22.0.0"

package/dist/augments/elements/overflow-parent.d.ts

@@ -1 +0,0 @@
-export declare function findOverflowParent(start: Element): Element;