DOM Operations

The DOM Module provides a lightweight encapsulation of native DOM operations, specifically optimized for the TechUI TuiAdaptive system.

In addition to standard element querying and traversal, it features core algorithms for accurately calculating element dimensions and coordinates within complex scaling contexts.

Import Method

import { syncContSize, tCoreTpl, tDom, tQuery } from "@techui/utils";

Element Querying

The tQuery object provides a set of shortcut methods for finding and traversing DOM nodes.

tQuery.el(selector, all)

A shorthand wrapper for querySelector.

• selector: CSS selector string.
• all: boolean. Defaults to false (returns a single element); set to true to return a NodeList.

const app = tQuery.el('#app'); 
const items = tQuery.el('.list-item', true);

tQuery.get1stParent(el, selector)

Finds the nearest matching parent element (a wrapper for closest).

// Finds the nearest .card parent of the currently clicked element
const card = tQuery.get1stParent(e.target, '.card');

tQuery.clearExcept(container, exceptEl)

Clears all child elements within a container except for one specified element. This is commonly used to preserve a loading mask or a specific state node.

tQuery.clearExcept(document.body, document.querySelector('#app'));

tQuery.valueByPath(obj, path, fallback)

Multi-language/Deep Object Value Extractor. While not a direct DOM operation, this is frequently used to safely retrieve data in the form of data.user.profile.name before DOM rendering.

const data = { user: { name: 'TechUI' } };
const name = tQuery.valueByPath(data, 'user.name'); // "TechUI"
const age = tQuery.valueByPath(data, 'user.age', 18); // 18 (Fallback)

Dimensions and Adaptive

tDom is the core object TechUI uses to handle adaptive layouts. It identifies whether an element is inside a #tuiAdpt (Adaptive Scaling Panel) and calculates its true physical coordinates.

tDom.isInAdp(el)

Determines if an element is located inside an adaptive scaling container (#tuiAdpt).

if (tDom.isInAdp(myElement)) {
  console.log("The current element is in a scaled environment");
}

tDom.rootInfo(el)

Retrieves detailed layout information for an element relative to both the browser viewport (Root) and the adaptive container (Adpt). This method resolves issues where native getBoundingClientRect data is difficult to convert within a transform: scale() environment.

• Returns: An object containing rootWidth, isInAdp, and critical coordinate offsets like A2RTop (Adaptive To Root Top).

const layout = tDom.rootInfo(el);
// layout.A2RLeft represents the distance from the adaptive container's left boundary to the viewport

syncContSize(options)

Container Size Synchronization Calculator. Calculates the geometric properties of a "source element" so they can be applied to a "target element" (primarily used for calculations in TuiAdaptive synchronization containers).

• Parameters:
  • source: Source DOM element.
  • target: Target DOM element (Note: In the source code, actual style assignment is commented out; this is mainly used to return the calculated Rect object).
  • syncPosition: boolean, whether to calculate position.
  • positionBaseTo: 'root' (based on viewport) | 'parent' (based on parent container offset).
• Logic: Automatically detects if the source is within an adaptive panel. If it is, it uses clientWidth instead of rect.width to avoid dimension deviations caused by scaling.

const rect = syncContSize({
  source: buttonEl,
  target: tooltipEl,
  syncPosition: true,
  positionBaseTo: 'root'
});
// rect: { width: 100, height: 40, left: 200, top: 300 }

Template Parsing

tCoreTpl(string)

A minimalist string template parsing function. It is used to parse specific configuration strings in the format [key]value (currently used for parsing certain template strings in Wasm modules).

const configStr = "[title]Hello TechUI[color]Blue";
const config = tCoreTpl(configStr);

console.log(config);
// Output: { title: "Hello TechUI", color: "Blue" }