Tools

this.tools is one of the biggest reasons to build custom modules on top of StringTune instead of bypassing the runtime. It keeps parsing, interpolation, measurement, and writes aligned with the rest of the system.

Attribute And Record Tools

domAttribute

Reads string-* and data-string-* attributes from a DOM element.

Use it when:

• you need an attribute outside normal attributesToMap
• a global module is scanning arbitrary DOM

recordAttribute

Reads values from a plain record or dataset-like object.

Use it when:

• your module already has a plain attribute object
• you are reusing DOM-like config records outside the DOM

Layout And Measurement Tools

boundingClientRect

Thin wrapper around getBoundingClientRect().

Use it when you want your custom module to stay on the same measurement primitive as the runtime.

transformNullify

Measures geometry while compensating for CSS transform matrices.

Useful when:

• your module works inside scaled or transformed surfaces
• raw DOM rects are misleading

relativePosition

Returns element position relative to a container instead of the page.

Useful when:

• your module works inside local containers
• absolute page coordinates are not the right model

transformScaleParser

Extracts scale from transform strings like:

• matrix(...)
• matrix3d(...)
• scale(...)
• scaleX(...)
• scale3d(...)
• none

Value Parsing Tools

unitParser

Converts author-facing unit strings into numeric values.

Current supported forms include:

• px
• %
• rem
• sh
• selfHeight
• additive chains split by |

Use it when your custom module accepts human-friendly spacing or offset values.

originParser

Parses origin-like strings and can normalize them into { x, y }.

Useful for transform-origin style semantics and anchor-like modules.

colorParser

Parses CSS colors into numeric { r, g, b, a }.

Useful when colors must be treated as data, not as opaque strings.

easingFunction

Turns easing strings into callable easing functions.

Supports common keywords plus cubic-bezier(...).

Interpolation And Motion Tools

lerp

Important caveat: current lerp.process({ from, to, progress }) returns a delta step, not the final interpolated value.

So the usual pattern is:

const step = this.tools.lerp.process({ from, to, progress });
current += step;

adaptiveLerp

Maps an input range into a lerp factor range.

Useful when smoothing should react differently at low and high velocity.

magneticPull

Returns a scalar attraction factor from distance, radius, and strength.

Useful for cursor-reactive interaction modules.

lerpVector

Like lerp, but for vector components. It also returns deltas, not final values.

lerpColor

Interpolates numeric color channels between two parsed colors.

Text And Form Tools

optionsParser

This is the compact parser used by StringSplit-style option strings.

Useful if your custom module wants a terse grammar like:

line[start]|char-line[center]|fit

ruleParser

Parses declarative validation rules into structured rule objects.

Useful when your module wants StringForm-style rule strings.

validation

Consumes rules and values and returns validation status plus errors.

Useful for custom field logic without rebuilding the form system.

Write Batching

styleTxn

styleTxn is part of the tool surface so custom modules can batch style writes like the built-ins do.

It provides:

• begin()
• setVar(...)
• setVars(...)
• setProp(...)
• setProps(...)
• commit()
• cancel()
• run(fn)

Use run(...) for the easiest safe path:

this.tools.styleTxn.run(() => {
  this.tools.styleTxn.setVar(object.htmlElement, '--x', 10);
  this.tools.styleTxn.setProp(object.htmlElement, 'transform', 'translateX(10px)');
});

Related Primitive: frameDOM

frameDOM is not stored on this.tools, but it belongs to the same authoring story.

Use it when you need extra scheduling outside the standard lifecycle hooks:

• measure(fn)
• mutate(fn)
• flush()

Practical Rule

Prefer injected tools over handwritten one-off helpers. That keeps your custom module aligned with:

• runtime parsing rules
• easing semantics
• unit conversion
• write batching
• scheduling expectations