APX DOM Wrapper

APX is a versatile DOM wrapper designed to simplify interactions with HTML elements. It provides a unified interface for working with various input types, including XPath, CSS selectors, individual HTMLElements, NodeLists, HTMLCollections, arrays of elements, jQuery objects, and even functions that return APX objects.

Core Library

The main APX library is defined in APX.mjs, which provides the core DOM wrapping functionality and integrates all modules.

Quick Start:

import APX from './APX.mjs';

// Use APX to select and manipulate elements
APX('.my-class').each((el) => console.log(el));

Features

• XPath Support: Easily select elements using XPath queries.
• CSS Selector Support: Utilize CSS selectors for element selection.
• Enhanced Interactions: Augmented with modules like listen for event handling and tristate for managing tristate logic.
• Utility Functions: Includes tools like loadCss, dialog, and toast for extended functionality.
• jQuery Compatibility: Seamlessly works with jQuery objects.
• Function Input: Accepts functions returning an APX object as input.

Modules

APX is enhanced with several modules, each adding specialized functionality. Each module has its own detailed documentation:

listen

The listen module simplifies event handling for wrapped elements. It provides an intuitive way to attach and manage event listeners with support for event delegation, multiple callbacks, debouncing, and manual event triggering.

Documentation: modules/listen/README.md

Quick Example:

APX('.button').listen('click').do((event) => {
    console.log('Button clicked!');
});

tristate

The tristate module allows you to manage tristate logic (e.g., on/off/indeterminate) for HTML elements efficiently.

Documentation: modules/tristate/README.md

Demo page:

• demo/modules/tristate/index.html (state preview and interactive cycle)

dialog

The dialog module provides utilities to create and manage modal dialogs with lifecycle management, button interactions, and flexible content loading.

Documentation: modules/dialog/README.md

Since 2.4.0, dialog content can be fetched via GET (default) or POST with optional payload and headers.

// Example: POST fetch for dialog content (APX 2.4.0+)
const myDialog = APX.dialog({
    title: 'Submit and Load',
    contentURI: '/api/dialog/content',
    contentMethod: 'POST',
    contentData: { foo: 'bar' }, // also supports FormData, URLSearchParams, string, Blob
    contentHeaders: { 'X-Request-ID': '123' },
    buttons: [
        { key: 'ok', label: 'OK', closeOnClick: true },
        { key: 'cancel', label: 'Cancel', closeOnClick: true }
    ],
    size: 'medium'
});

myDialog.open();

toast (since 2.5.0)

Minimal, framework‑agnostic toast notifications with auto‑loaded CSS and a small API. Exposed as APX.toast. Supports advanced positioning (sticky, relative, anchored), flow control, and container management.

Documentation: modules/toast/README.md

Quick Start:

// One‑liners on the default manager
APX.toast.success('Saved!');
APX.toast.warning('Heads up', { durationMs: 4000 });

// Callable shorthand (equivalent to show)
APX.toast({ message: 'Processing…', type: 'info', durationMs: 0 });

// Configure defaults
APX.toast.configure({ position: 'top-right', maxToasts: 4, dedupe: true });

// Named managers (profiles)
APX.toast.create('admin', { position: 'bottom-left' });
APX.toast.use('admin').info('Admin ready');

Demo pages (work from file:// via standalone build):

• demo/index.html (landing)
• demo/modules/toast/index.html (basic and advanced examples with code viewer)
• demo/modules/tristate/index.html (state preview and interactive cycle)
• demo/modules/scrollableTable/index.html (scrollable tbody with colspan/rowspan)

scrollableTable (since 2.7.0)

Makes the tbody of a table scrollable while keeping thead and tfoot fixed. Uses CSS Grid with subgrid; column and row sizes can be preserved from the table’s natural layout or overridden (full or hybrid). Dynamic body height (2.7.1): bodyHeightDynamic: { get, useAs, updateOn? } re-resolves height on resize (and optionally scroll); default updateOn uses window resize + ResizeObserver on document (scrollbar appearance), scroll: false.

Documentation: modules/scrollableTable/README.md

Quick Start:

APX('table.my-table').scrollableTable({ maxHeight: 300 });
APX('table.my-table').scrollableTable({ height: '50vh' });
// dynamic (viewport-based, updates on resize/scrollbar)
APX('table.my-table').scrollableTable({ bodyHeightDynamic: { get: (t) => window.innerHeight - t.getBoundingClientRect().top - 40, useAs: 'maxHeight' } });
APX('table.my-table').scrollableTable('refresh');

Demo page: demo/modules/scrollableTable/index.html

tools (since 2.6.0)

The tools module provides utility functions for common web development tasks: form handling (form-packer), dynamic CSS loading (loadCss), scrollbar measurement (getScrollbarSize), and more planned for future releases. Since 2.8.0, loadCss lives in tools (upgraded; idempotent, rejects on failure, optional options) and getScrollbarSize was added.

Documentation: modules/tools/README.md · Changelog: modules/tools/CHANGELOG.md

Quick Start:

// Convert form to JSON
const data = APX('form#myForm').pack();
// or
const data = APX.tools.packFormToJSON(document.querySelector('#myForm'));

// Load CSS (idempotent; since 2.8.0 also APX.tools.loadCss)
await APX.loadCss('/path/to/styles.css');

// Scrollbar size in pixels (cached; since 2.8.0)
const scrollbarWidth = APX.tools.getScrollbarSize();

Sub-modules / utilities:

• form-packer: Convert HTML forms to JSON with support for nested objects, arrays, and complex structures.
  • Documentation: modules/tools/form-packer/README.md
• loadCss (since 2.8.0 in tools): Dynamic CSS loading; also available as APX.loadCss. See modules/tools/README.md.
• getScrollbarSize (since 2.8.0): Scrollbar size in pixels; APX.tools.getScrollbarSize().

Demo page:

• demo/modules/tools/index.html (interactive form examples and validation)

Utilities

• loadCss: Dynamically load CSS files (since 2.8.0: idempotent, rejects on failure, optional options). Use APX.loadCss(url) or APX.tools.loadCss(url, options?). See modules/tools/README.md.

Usage

Here are some examples of how you can use APX:

// Using XPath
const apx1 = APX('//div[@class="example"]');

// Using CSS selector
const apx2 = APX('.example');

// Using a single element
const element = document.querySelector('.example');
const apx3 = APX(element);

// Using NodeList or HTMLCollection
const nodeList = document.querySelectorAll('.example');
const apx4 = APX(nodeList);

// Using an array of elements
const elements = [document.querySelector('.example1'), document.querySelector('.example2')];
const apx5 = APX(elements);

// Using a jQuery object
const $example = $('.example');
const apx6 = APX($example);

// Using a function returning an APX object
const apx7 = APX(() => APX('.example'));

API

Core Functionality

• APX(input, context = document): The main function that creates an APX object. Accepts a wide variety of input types:
  • string: XPath or CSS selectors.
  • HTMLElement: Single DOM element.
  • NodeList/HTMLCollection: A collection of DOM elements.
  • Array<HTMLElement>: An array of DOM elements.
  • jQuery: A jQuery object.
  • Function: A function that returns an APX object.
• Methods on APX objects:
  • .each(callback): Iterates over elements.
  • .get(index): Retrieves an element by index.
  • .all(): Returns all wrapped elements.
  • .first(): Returns the first wrapped element.

Utilities

• APX.loadCss(url, options?): Dynamically load CSS files (since 2.8.0: idempotent, rejects on failure; optional options: id, media, before). Also APX.tools.loadCss().
• APX.dialog(): Manage and display dialogs. See modules/dialog/README.md
• APX.toast: Toast notification system. See modules/toast/README.md
• APX('table').scrollableTable(options): Scrollable tbody with fixed thead/tfoot. See modules/scrollableTable/README.md
• APX.tools: Utility functions. See modules/tools/README.md
• APX.isAPXObject(obj): Check if an object is an APX object.
• APX.is_numeric(n): Check if a value is numeric.

Installation

To include APX in your project:

1. Clone the repository or download the package.
2. Import APX and its modules into your project:

   import APX from './path-to-apx/apx.mjs';

Contributing

We welcome contributions! Please refer to the contribution guidelines in the repository.

License

Author : Thibault SAELEN Copyright Appius SARL.