vira 22.2.1 → 23.0.0

package/dist/styles/focus.js

@@ -1,7 +1,13 @@
 import { addPx } from '@augment-vir/common';
 import { css, unsafeCSS } from 'element-vir';
 import { defineCssVars } from 'lit-css-vars';
-import { viraBorders } from './border';
+import { viraBorders } from './border.js';
+/**
+ * CSS vars for Vira focus colors.
+ *
+ * @category CSS Vars
+ * @category Styles
+ */
 export const viraFocusCssVars = defineCssVars({
     'vira-focus-outline-color': '#59b1ff',
     'vira-focus-outline-border-radius': css `calc(${viraBorders['vira-form-input-radius'].value} + 4px)`,
@@ -9,8 +15,10 @@ export const viraFocusCssVars = defineCssVars({
 /**
  * Create styles that look like an outline for the given selector.
  *
- * It is recommended to use the pseudo selectors ":focus:focus-visible:not(:active)" to preventing
- * clicking from creating focus styles in Chrome.
+ * It is recommended to use the pseudo selector chain ":focus:focus-visible:not(:active)" to
+ * preventing clicking an element from creating focus styles in Chrome.
+ *
+ * @category Styles
  */
 export function createFocusStyles({ selector, elementBorderSize, outlineGap = 2, outlineWidth = 2, }) {
     const outlineSpacing = unsafeCSS(addPx(outlineWidth + outlineGap + elementBorderSize));

package/dist/styles/form-themes.d.ts

@@ -1,8 +1,14 @@
+/**
+ * CSS vars for vira form elements.
+ *
+ * @category CSS Vars
+ * @category Styles
+ */
 export declare const viraFormCssVars: import("lit-css-vars").CssVarDefinitions<{
-    'vira-form-border-color': string;
-    'vira-form-background-color': string;
-    'vira-form-foreground-color': string;
-    'vira-form-focus-color': import("lit").CSSResult;
-    'vira-form-selection-hover-background-color': string;
-    'vira-form-selection-hover-foreground-color': string;
+    readonly 'vira-form-border-color': "#cccccc";
+    readonly 'vira-form-background-color': "white";
+    readonly 'vira-form-foreground-color': "black";
+    readonly 'vira-form-focus-color': import("lit").CSSResult;
+    readonly 'vira-form-selection-hover-background-color': "#d2eaff";
+    readonly 'vira-form-selection-hover-foreground-color': "black";
 }>;

package/dist/styles/form-themes.js

@@ -1,5 +1,11 @@
 import { defineCssVars } from 'lit-css-vars';
-import { viraFocusCssVars } from './focus';
+import { viraFocusCssVars } from './focus.js';
+/**
+ * CSS vars for vira form elements.
+ *
+ * @category CSS Vars
+ * @category Styles
+ */
 export const viraFormCssVars = defineCssVars({
     'vira-form-border-color': '#cccccc',
     'vira-form-background-color': 'white',

package/dist/styles/index.d.ts

@@ -1,11 +1,11 @@
 /** This file is automatically updated by update-index-exports.ts */
-export * from './border';
-export * from './color';
-export * from './disabled';
-export * from './durations';
-export * from './focus';
-export * from './form-themes';
-export * from './native-styles';
-export * from './scrollbar';
-export * from './shadows';
-export * from './user-select';
+export * from './border.js';
+export * from './color.js';
+export * from './disabled.js';
+export * from './durations.js';
+export * from './focus.js';
+export * from './form-themes.js';
+export * from './native-styles.js';
+export * from './scrollbar.js';
+export * from './shadows.js';
+export * from './user-select.js';

package/dist/styles/index.js

@@ -1,11 +1,11 @@
 /** This file is automatically updated by update-index-exports.ts */
-export * from './border';
-export * from './color';
-export * from './disabled';
-export * from './durations';
-export * from './focus';
-export * from './form-themes';
-export * from './native-styles';
-export * from './scrollbar';
-export * from './shadows';
-export * from './user-select';
+export * from './border.js';
+export * from './color.js';
+export * from './disabled.js';
+export * from './durations.js';
+export * from './focus.js';
+export * from './form-themes.js';
+export * from './native-styles.js';
+export * from './scrollbar.js';
+export * from './shadows.js';
+export * from './user-select.js';

package/dist/styles/native-styles.d.ts

@@ -1,2 +1,13 @@
+/**
+ * A chunk of CSS that succinctly removes all padding and margin from an element.
+ *
+ * @category Styles
+ */
 export declare const noNativeSpacing: import("element-vir").CSSResult;
+/**
+ * A chunk of CSS that succinctly removes all default built-in form element styles. This is
+ * particularly useful for `<button>` elements.
+ *
+ * @category Styles
+ */
 export declare const noNativeFormStyles: import("element-vir").CSSResult;

package/dist/styles/native-styles.js

@@ -1,8 +1,19 @@
 import { css } from 'element-vir';
+/**
+ * A chunk of CSS that succinctly removes all padding and margin from an element.
+ *
+ * @category Styles
+ */
 export const noNativeSpacing = css `
     padding: 0;
     margin: 0;
 `;
+/**
+ * A chunk of CSS that succinctly removes all default built-in form element styles. This is
+ * particularly useful for `<button>` elements.
+ *
+ * @category Styles
+ */
 export const noNativeFormStyles = css `
     ${noNativeSpacing};
     cursor: unset;

package/dist/styles/scrollbar.d.ts

@@ -1 +1,6 @@
+/**
+ * A function that generates CSS to hide scrollbars for the given CSS selector.
+ *
+ * @category Styles
+ */
 export declare function hideScrollbars(selector: string): import("element-vir").CSSResult;

package/dist/styles/scrollbar.js

@@ -1,4 +1,9 @@
 import { css, unsafeCSS } from 'element-vir';
+/**
+ * A function that generates CSS to hide scrollbars for the given CSS selector.
+ *
+ * @category Styles
+ */
 export function hideScrollbars(selector) {
     return css `
         ${unsafeCSS(selector)} {

package/dist/styles/shadows.d.ts

@@ -1,4 +1,9 @@
 import { CSSResult } from 'element-vir';
+/**
+ * CSS chunks for default Vira shadow styles.
+ *
+ * @category Styles
+ */
 export declare const viraShadows: {
     readonly menuShadow: CSSResult;
     readonly menuShadowReversed: CSSResult;

package/dist/styles/shadows.js

@@ -1,5 +1,10 @@
 import { css } from 'element-vir';
 const shadowColor = css `#e2e2e2`;
+/**
+ * CSS chunks for default Vira shadow styles.
+ *
+ * @category Styles
+ */
 export const viraShadows = {
     menuShadow: css `
         filter: drop-shadow(0px 5px 5px ${shadowColor});

package/dist/styles/user-select.d.ts

@@ -1 +1,6 @@
+/**
+ * A chunk of CSS that disables user selection.
+ *
+ * @category Styles
+ */
 export declare const noUserSelect: import("element-vir").CSSResult;

package/dist/styles/user-select.js

@@ -1,4 +1,9 @@
 import { css } from 'element-vir';
+/**
+ * A chunk of CSS that disables user selection.
+ *
+ * @category Styles
+ */
 export const noUserSelect = css `
     /* iOS Safari */
     -webkit-touch-callout: none;

package/dist/util/index.d.ts

@@ -1 +1 @@
-export * from './pop-up-manager';
+export * from './pop-up-manager.js';

package/dist/util/index.js

@@ -1 +1 @@
-export * from './pop-up-manager';
+export * from './pop-up-manager.js';

package/dist/util/pop-up-manager.d.ts

@@ -1,13 +1,28 @@
 import { MaybePromise } from '@augment-vir/common';
 import { Coords } from 'device-navigation';
 import { ExtractEventByType, ExtractEventTypes, ListenOptions, RemoveListenerCallback } from 'typed-event-target';
+/**
+ * A type used for representing a rectangle's position.
+ *
+ * @category Internal
+ */
 export type PositionRect = {
     top: number;
     left: number;
     right: number;
     bottom: number;
 };
+/**
+ * The default empty {@link PositionRect}, with all values set to 0.
+ *
+ * @category Internal
+ */
 export declare const emptyPositionRect: PositionRect;
+/**
+ * Options for {@link PopUpManager}.
+ *
+ * @category Pop Up
+ */
 export type PopUpManagerOptions = {
     /**
      * The minimum number of pixels for allowing the pop-up to go downwards. If the downward
@@ -43,6 +58,11 @@ export type PopUpManagerOptions = {
      */
     supportNavigation: boolean;
 };
+/**
+ * Output type from {@link PopUpManager.showPopUp}
+ *
+ * @category Pop Up
+ */
 export type ShowPopUpResult = {
     /**
      * Indicates if the "pop up" should pop in the downwards direction or not. If not, it should pop
@@ -52,27 +72,53 @@ export type ShowPopUpResult = {
     popDown: boolean;
     positions: Record<'root' | 'container' | 'diff', PositionRect>;
 };
-declare const HidePopUpEvent_base: (new (eventInitDict?: EventInit | undefined) => import("typed-event-target").TypedEvent<"hide-pop-up">) & Pick<{
-    new (type: string, eventInitDict?: EventInit | undefined): Event;
+declare const HidePopUpEvent_base: (new (eventInitDict?: EventInit) => import("typed-event-target").TypedEvent<"hide-pop-up">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
     prototype: Event;
     readonly NONE: 0;
     readonly CAPTURING_PHASE: 1;
     readonly AT_TARGET: 2;
     readonly BUBBLING_PHASE: 3;
-}, "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE" | "prototype"> & Pick<import("typed-event-target").TypedEvent<"hide-pop-up">, "type">;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"hide-pop-up">, "type">;
+/**
+ * An event fired from {@link PopUpManager} when the pop up should be hidden.
+ *
+ * @category Pop Up
+ */
 export declare class HidePopUpEvent extends HidePopUpEvent_base {
 }
-declare const NavSelectEvent_base: (new (eventInitDict: import("typed-event-target").TypedCustomEventInit<Coords>) => import("typed-event-target").TypedCustomEvent<Coords, "nav-select">) & Pick<{
-    new (type: string, eventInitDict?: EventInit | undefined): Event;
+declare const NavSelectEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: Coords;
+}) => import("typed-event-target").TypedCustomEvent<Coords, "nav-select">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
     prototype: Event;
     readonly NONE: 0;
     readonly CAPTURING_PHASE: 1;
     readonly AT_TARGET: 2;
     readonly BUBBLING_PHASE: 3;
-}, "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE" | "prototype"> & Pick<import("typed-event-target").TypedCustomEvent<Coords, "nav-select">, "type">;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<Coords, "nav-select">, "type">;
+/**
+ * An event fired from {@link PopUpManager} when an individual item in the pop up has been selected
+ * by the user.
+ *
+ * @category Pop Up
+ */
 export declare class NavSelectEvent extends NavSelectEvent_base {
 }
+/**
+ * All events that can be emitted by {@link PopUpManager}.
+ *
+ * @category Internal
+ */
 export type PopUpManagerEvents = HidePopUpEvent | NavSelectEvent;
+/**
+ * A "pop up" manager for items that pop up from the HTML page, like dropdowns or menus.
+ *
+ * @category Pop Up
+ */
 export declare class PopUpManager {
     private listenTarget;
     private options;
@@ -80,11 +126,20 @@ export declare class PopUpManager {
     private lastRootElement;
     constructor(options?: Partial<PopUpManagerOptions> | undefined);
     private attachGlobalListeners;
+    /** Listen to events emitted from a {@link PopUpManager} instance. */
     listen<const EventDefinition extends Readonly<{
         type: ExtractEventTypes<PopUpManagerEvents>;
     }>>(event: EventDefinition, listener: (event: ExtractEventByType<PopUpManagerEvents, EventDefinition['type']>) => MaybePromise<void>, options?: ListenOptions | undefined): RemoveListenerCallback;
+    /** Trigger removal or hiding of the pop up. */
     removePopUp(): void;
+    /** Trigger showing the pop up. */
     showPopUp(rootElement: HTMLElement, options?: Partial<PopUpManagerOptions> | undefined): ShowPopUpResult;
+    /**
+     * Cleanup and destroy the {@link PopUpManager} instance. This:
+     *
+     * - Removes the existing pop up
+     * - Cleans up all internal and external listeners
+     */
     destroy(): void;
 }
 export {};

package/dist/util/pop-up-manager.js

@@ -1,49 +1,50 @@
-import { findOverflowParent } from '@augment-vir/browser';
+import { assert } from '@augment-vir/assert';
 import { mapObjectValues } from '@augment-vir/common';
+import { findOverflowAncestor } from '@augment-vir/web';
 import { NavController, NavDirection } from 'device-navigation';
 import { listenToPageActivation } from 'page-active';
-import { assertInstanceOf } from 'run-time-assertions';
 import { ListenTarget, defineTypedCustomEvent, defineTypedEvent, listenToGlobal, } from 'typed-event-target';
+/**
+ * The default empty {@link PositionRect}, with all values set to 0.
+ *
+ * @category Internal
+ */
 export const emptyPositionRect = {
     top: 0,
     left: 0,
     right: 0,
     bottom: 0,
 };
+/**
+ * An event fired from {@link PopUpManager} when the pop up should be hidden.
+ *
+ * @category Pop Up
+ */
 export class HidePopUpEvent extends defineTypedEvent('hide-pop-up') {
 }
+/**
+ * An event fired from {@link PopUpManager} when an individual item in the pop up has been selected
+ * by the user.
+ *
+ * @category Pop Up
+ */
 export class NavSelectEvent extends defineTypedCustomEvent()('nav-select') {
 }
+/**
+ * A "pop up" manager for items that pop up from the HTML page, like dropdowns or menus.
+ *
+ * @category Pop Up
+ */
 export class PopUpManager {
+    listenTarget = new ListenTarget();
+    options = {
+        minDownSpace: 200,
+        verticalDiffThreshold: 20,
+        supportNavigation: true,
+    };
+    cleanupCallbacks = [];
+    lastRootElement;
     constructor(options) {
-        Object.defineProperty(this, "listenTarget", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: new ListenTarget()
-        });
-        Object.defineProperty(this, "options", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: {
-                minDownSpace: 200,
-                verticalDiffThreshold: 20,
-                supportNavigation: true,
-            }
-        });
-        Object.defineProperty(this, "cleanupCallbacks", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
-        Object.defineProperty(this, "lastRootElement", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         this.options = { ...this.options, ...options };
     }
     attachGlobalListeners(rootElement) {
@@ -104,7 +105,7 @@ export class PopUpManager {
                         const currentlyFocused = navController.getCurrentlyFocused();
                         if (currentlyFocused) {
                             navController.enterInto();
-                            this.listenTarget.dispatch(new NavSelectEvent({ detail: currentlyFocused.coords }));
+                            this.listenTarget.dispatch(new NavSelectEvent({ detail: currentlyFocused.node.coords }));
                             event.stopImmediatePropagation();
                             event.preventDefault();
                         }
@@ -113,18 +114,21 @@ export class PopUpManager {
             }),
         ];
     }
+    /** Listen to events emitted from a {@link PopUpManager} instance. */
     listen(event, listener, options) {
         return this.listenTarget.listen(event, listener, options);
     }
+    /** Trigger removal or hiding of the pop up. */
     removePopUp() {
         this.cleanupCallbacks.forEach((callback) => callback());
         this.listenTarget.dispatch(new HidePopUpEvent());
     }
+    /** Trigger showing the pop up. */
     showPopUp(rootElement, options) {
         this.lastRootElement = rootElement;
         const currentOptions = { ...this.options, ...options };
-        const container = findOverflowParent(rootElement);
-        assertInstanceOf(container, HTMLElement);
+        const container = findOverflowAncestor(rootElement);
+        assert.instanceOf(container, HTMLElement);
         const rootRect = rootElement.getBoundingClientRect();
         const containerRect = container.getBoundingClientRect();
         const containerScrollbarWidth = container.offsetWidth - container.clientWidth;
@@ -162,6 +166,12 @@ export class PopUpManager {
             },
         };
     }
+    /**
+     * Cleanup and destroy the {@link PopUpManager} instance. This:
+     *
+     * - Removes the existing pop up
+     * - Cleans up all internal and external listeners
+     */
     destroy() {
         this.removePopUp();
         this.listenTarget.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "22.2.1",
+    "version": "23.0.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",
@@ -18,53 +18,57 @@
     },
     "repository": {
         "type": "git",
-        "url": "https://github.com/electrovir/element-vir"
+        "url": "git+https://github.com/electrovir/element-vir.git"
     },
     "license": "(MIT or CC0 1.0)",
     "author": {
         "name": "electrovir",
         "url": "https://github.com/electrovir"
     },
+    "type": "module",
     "main": "dist/index.js",
+    "module": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
-        "compile": "rm -rf dist && tsc -b -f --pretty",
-        "test": "virmator test-web"
+        "build": "npm run docs",
+        "compile": "virmator compile",
+        "docs": "virmator docs",
+        "test": "virmator test web",
+        "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/browser": "^27.0.0",
-        "@augment-vir/common": "^27.0.0",
-        "colorjs.io": "^0.5.0",
-        "date-vir": "^5.1.4",
-        "device-navigation": "^1.0.0",
-        "lit-css-vars": "^3.0.9",
-        "observavir": "^2.0.0",
+        "@augment-vir/assert": "^30.3.0",
+        "@augment-vir/common": "^30.3.0",
+        "@augment-vir/web": "^30.3.0",
+        "colorjs.io": "^0.5.2",
+        "date-vir": "^6.0.1",
+        "device-navigation": "^3.0.1",
+        "lit-css-vars": "^3.0.10",
+        "observavir": "^2.0.3",
         "page-active": "^1.0.0",
-        "spa-router-vir": "^4.0.3",
-        "type-fest": "^4.17.0",
-        "typed-event-target": "^3.4.0"
+        "spa-router-vir": "^4.0.4",
+        "type-fest": "^4.26.1",
+        "typed-event-target": "^4.0.0"
     },
     "devDependencies": {
-        "@augment-vir/browser-testing": "^27.0.0",
-        "@augment-vir/node-js": "^27.0.0",
-        "@open-wc/testing": "^4.0.0",
-        "@types/chai": "^4.3.14",
-        "@types/mocha": "^10.0.6",
+        "@augment-vir/test": "^30.3.0",
         "@web/dev-server-esbuild": "^1.0.2",
-        "@web/test-runner": "^0.18.1",
+        "@web/test-runner": "^0.19.0",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.0",
-        "@web/test-runner-visual-regression": "^0.9.0",
-        "esbuild": "^0.20.2",
-        "istanbul-smart-text-reporter": "^1.1.4",
-        "markdown-code-example-inserter": "^1.0.0",
-        "run-time-assertions": "^1.2.0",
-        "typedoc": "^0.25.13",
-        "typescript": "5.3.3",
-        "vite": "^4.5.0",
-        "vite-tsconfig-paths": "^4.3.2"
+        "@web/test-runner-visual-regression": "^0.10.0",
+        "esbuild": "^0.24.0",
+        "istanbul-smart-text-reporter": "^1.1.5",
+        "markdown-code-example-inserter": "^3.0.0",
+        "typedoc": "^0.26.10",
+        "typescript": "5.6.3",
+        "vite": "^5.4.10",
+        "vite-tsconfig-paths": "^5.0.1"
     },
     "peerDependencies": {
-        "element-vir": ">=17"
+        "element-vir": "^23.0.0"
+    },
+    "engines": {
+        "node": ">=22"
     }
 }

package/dist/elements/dropdown/dropdown.mock.d.ts

@@ -1,13 +0,0 @@
-export declare const mockOptions: readonly [{
-    readonly label: "Option 0";
-    readonly id: 0;
-}, {
-    readonly label: "Option 1";
-    readonly id: 1;
-}, {
-    readonly label: "Option 2";
-    readonly id: 2;
-}, {
-    readonly label: "Option 3";
-    readonly id: 3;
-}];

package/dist/elements/dropdown/dropdown.mock.js

@@ -1,18 +0,0 @@
-export const mockOptions = [
-    {
-        label: 'Option 0',
-        id: 0,
-    },
-    {
-        label: 'Option 1',
-        id: 1,
-    },
-    {
-        label: 'Option 2',
-        id: 2,
-    },
-    {
-        label: 'Option 3',
-        id: 3,
-    },
-];