Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/igorskyflyer/npm-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. 💤
https://github.com/igorskyflyer/npm-rawelement

astro back-end dom element html igorskyflyer javascript js raw ssg string tag ts typescript wrapper

Last synced: 4 months ago
JSON representation

🐯 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. 💤

Host: GitHub
URL: https://github.com/igorskyflyer/npm-rawelement
Owner: igorskyflyer
License: mit
Created: 2024-07-22T22:22:03.000Z (7 months ago)
Default Branch: main
Last Pushed: 2024-07-28T22:05:32.000Z (6 months ago)
Last Synced: 2024-09-30T07:42:09.828Z (4 months ago)
Topics: astro, back-end, dom, element, html, igorskyflyer, javascript, js, raw, ssg, string, tag, ts, typescript, wrapper
Language: TypeScript
Homepage: https://www.npmjs.com/package/@igor.dvlpr/rawelement
Size: 77.1 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

        
<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](#-usage)

- [API](#-api)

    - [`constructor()`](#rawelementoptions-irawelementoptions)

    - [`IRawElementOptions`](#irawelementoptions)

      - [`data`](#data-string)

      - [`tag`](#tag-string)

      - [`format`](#format-boolean)

    - [`wrapper`](#wrapper)

    - [`source`](#source)

    - [`hasAttribute()`](#hasattributename-string-boolean)

    - [`setAttribute()`](#setattributename-string-value-string--null-boolean)

    - [`removeAttribute()`](#removeattributename-string-boolean)

- [Examples](#-examples)

- [Changelog](#-changelog)

- [License](#-license)

- [Related](#-related)

- [Author](#-author)







## 🕵🏼 Usage

Install it by executing:

```shell

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:

```ts

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()`](#setattributename-string-value-string--null-boolean) 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`](#setattributename-string-value-string--null-boolean) 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`](#tag-string) was set),

- attributes (if [`tag`](#tag-string) was set),

- text content,

- an end tag (if [`tag`](#tag-string) 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`](#tag-string) 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`](#tag-string) is not defined, attributes cannot be used and this method will throw an Error.

>




Passing the `value` of `null` removes the attribute (see [`removeAttribute`](#removeattributename-string-boolean)) 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`](#tag-string) 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`

```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

---

```




`my-page.astro`

```astro

import EncodedComponent from './EncodedComponent.astro'

  


    Mitochondria are known as the "powerhouses" of the cell because they generate most of the cell's supply of ATP & CO₂, which is used as a source of chemical energy.

  


{/*

  Will get rendered as:

  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.

*/}

```

---

## 📝 Changelog

📑 The changelog is available here: [CHANGELOG.md](https://github.com/igorskyflyer/npm-rawelement/blob/main/CHANGELOG.md).

---

## 🪪 License

Licensed under the MIT license which is available here, [MIT license](https://github.com/igorskyflyer/npm-rawelement/blob/main/LICENSE).

---

## 🧬 Related

[@igor.dvlpr/astro-post-excerpt](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@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](https://www.npmjs.com/package/@igor.dvlpr/duoscribi)

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




[@igor.dvlpr/magic-queryselector](https://www.npmjs.com/package/@igor.dvlpr/magic-queryselector)

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




[@igor.dvlpr/strip-headings](https://www.npmjs.com/package/@igor.dvlpr/strip-headings)

> _⛸ Strips Markdown headings!🏹_

---




### 👨🏻‍💻 Author

Created by **Igor Dimitrijević** ([*@igorskyflyer*](https://github.com/igorskyflyer/)).