📃 Table of Contents

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

🤖 Features

• 🏗 Create and manage raw HTML element wrappers from plain strings
• 🛡 Validates matching start/end tags for consistency
• ✂ Strips wrapper tags while keeping inner content intact
• 🎨 Optional formatting to remove leading indentation
• 🏷 Add, update, check, or remove wrapper element attributes
• 📦 Returns full wrapper or just inner source on demand
• ⚡ Precompiled regex for fast whitespace and tag matching
• 🚫 Throws clear errors on invalid data or attribute usage without a wrapper

🕵🏼 Usage

Install it by executing any of the following, depending on your preferred package manager:

pnpm add @igorskyflyer/rawelement

yarn add @igorskyflyer/rawelement

npm i @igorskyflyer/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 '@igorskyflyer/encode-entities'
import { RawElement } from '@igorskyflyer/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.

💖 Support

🧬 Related

@igorskyflyer/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! 💎

@igorskyflyer/extendable-string

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

@igorskyflyer/duoscribi

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

@igorskyflyer/magic-queryselector

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

@igorskyflyer/strip-headings

⛸ Strips Markdown headings!🏹

👨🏻‍💻 Author

Created by Igor Dimitrijević (@igorskyflyer).