domer
A library to build DOM faster.
Install
Add to your project using :
npm i @riadh-adrani/domer
Methods
setConfig
Used to set libraries configuration.
function setConfig(config: LibraryConfig): void;
You can reset by calling setConfig()
without an object.
element
Create a DOM element.
function element<T = Element>(tag: string, props: CreateElementProps, children: Array<unknown>): T;
-
tag
: element tag. -
props
: object containing attributes and events to be added. -
children
: an array of elements which will be appended as children.
to change
namespace
, usens
with the desired value as prop. default toHTML
.
accepts any children: if it is a
Node
, it will be appended directly, otherwise, aText
node will be created.
applies
class
transformation by default.
applies
event
transformation by default.
text()
create a Text
node by transforming data to a string
.
function text(data?: unknown): Text;
setEventListener
add an event listener to an element.
function setEventListener(
key: string,
event: string,
value: unknown,
element: Element,
modifiers?: Array<EventModifier>,
): void;
-
key
: a unique identifier of the event. -
event
: event name likeclick
,input
...etc -
value
: usually an event callback. In case of other value, an empty callback will be added instead. -
element
: target element. -
modifiers
: an array of all modifiers to be applied. modifiers will be applied in order.
stores the event's callback inside the element itself in field called
__events__
usingkey
, so it can be later used byremoveEventListener
.
use
key
to register multiple event listener for the sameevent
, likeclick1
andclick2
.
removeEventListener
remove event listener by its key
and event
name.
function setEventListener(key: string, event: string, element: Element): void;
-
key
: a unique identifier of the event. -
event
: event name likeclick
,input
...etc -
element
: target element.
setAttribute
add an attribute to an element.
function setAttribute(attr: string, value: unknown, el: Element): void;
style
attribute accept both anobject
andstring
.
toggle
attributes will be forced depending on the result ofBoolean(value)
.
removeAttribute
removes an attribute from an element.
function setAttribute(attr: string, el: Element): void;
insertNode
insert node within a parent in a given position.
function insertNode(node: Node, parent: Node, position?: number): void;
appends node at the end if position is invalid
insertNode
change node position within its parent.
function changeNodePosition(node: Node, position: number): void;
appends node at the end if position is invalid
removeNode
remove node from the DOM.
function removeNode(node: Node): void;
setText
update Text
content.
function setText(data: unknown, node: Text): void;
Helpers
attrToProp
convert an attribute to a DOM property, or camelcase it otherwise.
function attrToProp(attr: string): string;
extractEventDetails
extract event details from a prop
name.
function extractEventDetails(
prop: string,
): { event: string; modifiers: Array<EventModifier> } | false;
update config to control which event prop should be accepted.
Examples
// invalid
extractEventDetails('click') == false;
// react style
extractEventDetails('onClick') == { event: 'click', modifiers: [] };
// svelte style
extractEventDetails('on:click') == { event: 'click', modifiers: [] };
// vue style
extractEventDetails('@click') == { event: 'click', modifiers: [] };
// with modifiers
extractEventDetails('@click-stop-prevent') == { event: 'click', modifiers: ['stop', 'prevent'] };
isClassProp
check if the given prop is a class
related prop.
function isClassProp(prop: string): boolean;
update config to control which class prop should be accepted.
Examples
// invalid
isClassProp('click') == false;
// class
isClassProp('class') == true;
// className
isClassProp('className') == true;
// class directive
isClassProp('class:test') == true;
resolveClassProps
resolve class props and return the final class string
.
function resolveClassProps(props: Array<{ value: unknown; key: string }>): string;
accepts an array of objects containg the following keys:
-
value
: the value of the property. could be astring
, anArray<string>
or aboolean
with class directive. -
key
: the property/attribute key, likeclass
,className
orclass:*
.
the props will be sorted in the order :
class
>className
>class:*
.
Types
Namespace
enum Namespace {
SVG = 'http://www.w3.org/2000/svg',
HTML = 'http://www.w3.org/1999/xhtml',
MATH = 'http://www.w3.org/1998/Math/MathML',
}
EventModifiers
const EventModifiers = ['stop', 'prevent', 'self', 'capture', 'once', 'passive'] as const;
CreateElementProps
interface CreateElementProps extends Record<string, unknown> {
ns?: string;
}
EventModifier
type EventModifier = (typeof EventModifiers)[number];
EventHandler
type EventHandler = (e: Event) => void;
LibraryConfig
interface LibraryConfig {
events?: {
wrapper?: (event: Event, callback: EventHandler) => void;
syntax?: {
vue?: boolean;
svelte?: boolean;
react?: boolean;
};
};
attributes?: {
class?: {
directive?: boolean;
className?: boolean;
};
};
}
-
events
-
wrapper
: add a wrapper for all inserted event callbacks. -
syntax
-
vue
: allow vue-style event like@click
when creating an element.true
by default. -
svelte
: allow svelte-style event likeon:click
when creating an element.true
by default. -
react
: allow react-style event likeonClick
when creating an element.true
by default.
-
-
-
attributes
-
class
-
directive
: allow class directive. a prop withclass:test
with a value oftrue
will be evaluated toclass
of valuetest
.true
by default. -
className
: allowclassName
value to be appended to theclass
attribute.true
by default.
-
-
ElementWithEvents
interface ElementWithEvents extends Element {
__events__: Record<string, EventHandler>;
}