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.

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, and dialog 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:

listen

The listen module simplifies event handling for wrapped elements. It provides an intuitive way to attach and manage event listeners.

Documentation: /modules/listen

tristate

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

Documentation: /modules/tristate

dialog

The dialog module provides utilities to create and manage modal dialogs.

Documentation: /modules/dialog

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.

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 });

// Dedupe requires a stable id
APX.toast.show({ id: 'status', message: 'Working…', type: 'info', durationMs: 0 });
APX.toast.show({ id: 'status', message: 'Done', type: 'success', durationMs: 1500 });

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

Notes:

• CSS is auto‑imported by the toast module; no <link> needed.
• Overflow policy enforces a strict cap: if maxToasts is exceeded, the oldest is removed immediately.
• Named managers are accessible via APX.toast.use('<name>').

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

• demo/index.html (landing)
• demo/modules/toast/index.html (basic and advanced examples with code viewer)

Utilities

• loadCss: Dynamically load CSS files into your document.

Documentation: /modules/common.mjs

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.getApxPathURI(): Retrieve the URI path for a given element.
• APX.loadCss(): Dynamically load CSS files.
• APX.dialog(): Manage and display dialogs.
• 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.