@igor.dvlpr/rawelement

<RawElement />

🐯 A utility that lets you manipulate HTML elements, their attributes and
innerHTML as strings, on the go and then render the modified HTML.
Very useful in SSG projects. 💤

💖 Support further development

I work hard for every project, including this one
and your support means a lot to me!

Consider buying me a coffee. ☕
Thank you for supporting my efforts! 🙏😊



@igorskyflyer

📃 Table of contents

• Usage
• API
  • constructor()
  • IRawElementOptions
    • data
    • tag
    • format
  • wrapper
  • source
  • hasAttribute()
  • setAttribute()
  • removeAttribute()
• Examples
• Changelog
• License
• Related
• Author

🕵🏼 Usage

Install it by executing:

npm i "@igor.dvlpr/rawelement"

🤹🏼 API

RawElement(options: IRawElementOptions)

Creates a RawElement instance.

If no options are specified or the required data property is not passed, it will throw an error.

IRawElementOptions

Options are an interface IRawElementOptions of the following structure:

interface IRawElementOptions {
  data: string
  tag?: keyof HTMLElementTagNameMap // = string
  format?: boolean
}

data: string

Required, the actual HTML element/data to process, as a String.

Data will be normalized, i.e. CRLF (\r\n) replaced with LF (\n).

tag?: string

Optional, a wrapper HTML tag for the element that will contain the text content and optional attributes set by the setAttribute() method.

The provided HTML element MUST have a matching start and an end tag that correspond to the value of the tag property, otherwise an error is thrown.

[!NOTE] setAttribute only works when the tag property is defined.

format?: boolean

Optional, indicates whether to format the text content inside of the element.

[!TIP] It is highly recommended to leave the property format to its default value of true otherwise the source property of an instance of RawElement might contain a lot of leading whitespace.

---

wrapper

Gets the whole wrapper element made of:

• a start tag (if tag was set),
• attributes (if tag was set),
• text content,
• an end tag (if tag was set).

---

source

Gets the text content of the element.

[!TIP] The text content can be formatted (the default behavior), set format in the options to false to disable formatting.

---

hasAttribute(name: string): boolean

Checks whether the wrapper element has an attribute.

[!CAUTION] If the wrapper element is not set, i.e. tag is not defined, attributes cannot be used and this method will throw an Error.

Returns a Boolean indicating whether the provided attribute exists.

---

setAttribute(name: string, value: string | null): boolean

Sets an attribute and its value on the wrapper element.

[!CAUTION] If the wrapper element is not set, i.e. tag is not defined, attributes cannot be used and this method will throw an Error.

Passing the value of null removes the attribute (see removeAttribute) as well.

Returns a Boolean indicating whether the action succeeded.

---

removeAttribute(name: string): boolean

Removes an attribute and its value from the wrapper element.

[!CAUTION] If the wrapper element is not set, i.e. tag is not defined, attributes cannot be used and this method will throw an Error.

Returns a Boolean with the value of:

• true - if the attribute was found and removed,
• false - if the attribute does not exist or there was an error in removing it.

---

✨ Examples

EncodedComponent.astro

---
import { Encoder } from '@igor.dvlpr/encode-entities'
import { RawElement } from '@igor.dvlpr/rawelement'

// here we are using Astro (the SSG)
// but the data can come from any source
const slot: string = await Astro.slots.render('default')

const element: RawElement = new RawElement({
  tag: 'div',
  data: slot
})
const encoder: Encoder = new Encoder()
const source: string = encoder.encode(element.source) // this component will always output encoded content
---

<Fragment set:html={source} />

my-page.astro

import EncodedComponent from './EncodedComponent.astro'

<EncodedComponent>
  <div is:raw>
    Mitochondria are known as the "powerhouses" of the cell because they generate most of the cell's supply of ATP & CO<sub>2</sub>, which is used as a source of chemical energy.
  </div>
</EncodedComponent>

{/*
  Will get rendered as:

  Mitochondria are known as the &#34;powerhouses&#34; of the cell because they generate most of the cell&#39;s supply of ATP &#38; CO&#60;sub&#62;2&#60;/sub&#62;, which is used as a source of chemical energy.
*/}

---

📝 Changelog

📑 The changelog is available here: CHANGELOG.md.

---

🪪 License

Licensed under the MIT license which is available here, MIT license.

---

🧬 Related

@igor.dvlpr/astro-post-excerpt

⭐ An Astro component that renders post excerpts for your Astro blog - directly from your Markdown and MDX files. Astro v2+ collections are supported as well! 💎

@igor.dvlpr/extendable-string

🦀 ExtendableString allows you to create strings on steroids that have custom transformations applied to them, unlike common, plain strings. 🪀

@igor.dvlpr/duoscribi

✒ DúöScríbî allows you to convert letters with diacritics to regular letters. 🤓

@igor.dvlpr/magic-queryselector

🪄 A TypeScript-types patch for querySelector/querySelectorAll, make them return types you expect them to! 🔮

@igor.dvlpr/strip-headings

⛸ Strips Markdown headings!🏹

---

👨🏻‍💻 Author

Created by Igor Dimitrijević (@igorskyflyer).

Changelog

v1.1.0

<p align="right"><em>26-Jul-2024</em></p>

• 🪅 feat: make the tag property optional
• 🪅 feat: add the hasAttribute method for checking whether an attribute exists
• 🪅 feat: add the removeAttribute method for attribute removal

<br>

• 💻 dev: improve JSDocs

<br> <br>