mationhtml 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rezzvy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# MationHTML
+
+Transform HTML into absolutely any format imaginable.
+
+## Overview
+
+MationHTML lets you transform HTML into specific formats based on rules you define.
+
+- Works in both the browser and Node.js.
+- Define transformations using simple strings or logic-based functions.
+- Gain full control over how specific elements are processed.
+- Apply global string replacements for post-conversion cleanup.
+
+## Installation & Usage
+
+### Installation
+
+#### Browser
+
+Include the library via script tag:
+
+```html
+<script src="https://cdn.jsdelivr.net/gh/rezzvy/mationhtml@933d9de/dist/mationhtml.min.js"></script>
+```
+
+```javascript
+const converter = new MationHTML();
+```
+
+#### Node
+
+Install via npm:
+
+```bash
+npm install mationhtml
+```
+
+```javascript
+const converter = require("mationhtml");
+```
+
+### Usage
+
+```javascript
+converter.addRule([
+  {
+    selector: "p",
+    render: "[text]{content}[/text]",
+  },
+  {
+    selector: "strong",
+    render: "[b]{content}[/b]",
+  },
+  {
+    selector: "a",
+    render: "[url={attributes.href}]{content}[/url]",
+  },
+]);
+
+const output = converter.convert(`<p><strong>Hello</strong> there! <a href="https://google.com">Click me!</a></p>`);
+console.log(output);
+// [text][b]Hello[/b] there! [url=https://google.com]Click me![/url][/text]
+```
+
+## Examples
+
+### String Replacement
+
+```javascript
+const converter = new MationHTML();
+converter.addStringReplacements({ from: "Hello!", to: "Bonjour!" });
+converter.addRule({
+  selector: "strong",
+  render: "[b]{content}[/b]",
+});
+
+const output = converter.convert(`<strong>Hello!</strong>`);
+console.log(output);
+// [b]Bonjour![/b]
+```
+
+### Fallback Handler
+
+```javascript
+const converter = new MationHTML();
+converter.fallbackHandler = ({ content, node }) => {
+  return `[unknown tag=${node.tagName}]${content}[/unknown]`;
+};
+
+converter.addRule({
+  selector: "body",
+  render: "{content}",
+});
+
+const output = converter.convert(`<strong>Hello!</strong>`);
+console.log(output);
+// [unknown tag=STRONG]Hello![/unknown]
+```
+
+### Function-Based Render
+
+```javascript
+const converter = new MationHTML();
+
+converter.addRule({
+  selector: "img",
+  render: ({ attributes }) => {
+    return attributes.alt ? `Image: ${attributes.alt}` : `Source: ${attributes.src}`;
+  },
+});
+
+const output = converter.convert(`<img src="sample.jpg" alt="Example">`);
+console.log(output);
+// Image: Example
+```
+
+### Hide Specific Selectors
+
+```javascript
+const converter = new MationHTML();
+converter.addIgnoredSelectors(["strong"]);
+converter.addRule({
+  selector: "p",
+  render: "{content}",
+});
+
+const output = converter.convert(`<p>Hello <strong>there!</strong></p>`);
+console.log(output);
+// Hello
+```
+
+## Documentation
+
+### API Reference
+
+#### `convert(htmlString, normalizeWhitespace)`
+
+The primary method to transform your HTML string.
+
+| Parameter             | Type      | Default    | Description                                             |
+| :-------------------- | :-------- | :--------- | :------------------------------------------------------ |
+| `htmlString`          | `string`  | _Required_ | The HTML content to transform.                          |
+| `normalizeWhitespace` | `boolean` | `true`     | Collapses multiple spaces/newlines (except in `<pre>`). |
+
+#### `addRule(rule)`
+
+Adds one or more transformation rules.
+
+| Parameter | Type           | Description                                               |
+| :-------- | :------------- | --------------------------------------------------------- |
+| `rule`    | `Object/Array` | A rule object `{ selector, render }` or an array of them. |
+
+#### `fallbackHandler` (Setter)
+
+Sets a global handler for elements that don't match any rules.
+
+| Parameter  | Type       | Description                                                           |
+| :--------- | :--------- | :-------------------------------------------------------------------- |
+| `callback` | `function` | A function receiving the API object. Must return a string of content. |
+
+#### `addIgnoredSelectors(selectors)`
+
+Prevents specific elements and their children from being processed.
+
+| Parameter   | Type       | Description                                          |
+| :---------- | :--------- | :--------------------------------------------------- |
+| `selectors` | `string[]` | Array of CSS selectors (e.g., `['script', '.ads']`). |
+
+#### `addStringReplacements(replacements)`
+
+Post-processing string swaps performed on the final result.
+
+| Parameter      | Type           | Description                               |
+| :------------- | :------------- | :---------------------------------------- |
+| `replacements` | `Object/Array` | Object(s) with `{ from, to }` properties. |
+
+### API
+
+When `render` is a function or when using the `fallbackHandler`, you receive an object with these properties:
+
+| Property           | Type              | Description                                          |
+| :----------------- | :---------------- | :--------------------------------------------------- |
+| `node`             | `Node`            | The current DOM node being processed.                |
+| `attributes`       | `Object`          | A key-value map of the element's attributes.         |
+| `depth`            | `number`          | The current nesting level.                           |
+| `content`          | `string` (getter) | The processed string of all child nodes.             |
+| `applyRules(node)` | `function`        | Manually trigger rule processing on a specific node. |
+
+### Template Placeholders
+
+Shortcuts for defining `render` strings:
+
+| Placeholder      | Description                                | Example                |
+| :--------------- | :----------------------------------------- | :--------------------- |
+| `{content}`      | Inserts processed child text/tags.         | `[tag]{content}[/tag]` |
+| `{attributes.x}` | Inserts the value of attribute `x`.        | `{attributes.href}`    |
+| `{null}`         | Returns an empty string (removes the tag). | `render: "{null}"`     |
+
+### Behavior
+
+#### Top-Down Processing
+
+By default, MationHTML processes from the parent down to the children. If a parent rule doesn't include the `{content}` placeholder, the children are simply ignored.
+
+For example, these li elements won't show up because the ul rule returns a static string:
+
+```javascript
+converter.addRule([
+  { selector: "ul", render: "List Placeholder" },
+  { selector: "li", render: "[*] {content}" },
+]);
+```
+
+If you want to build the parent structure manually without just dumping `{content}` in, you can process child nodes yourself using `applyRules()`
+
+```javascript
+const converter = new MationHTML();
+
+converter.addRule([
+  {
+    selector: "ul",
+    render: (api) => {
+      let items = Array.from(api.node.children);
+      let processedChildren = "";
+      items.forEach((el) => {
+        processedChildren += api.applyRules(el);
+      });
+
+      return `[list]${processedChildren}[/list]`;
+    },
+  },
+  {
+    selector: "li",
+    render: "[*] {content}",
+  },
+]);
+```
+
+#### Cascading Rules
+
+MationHTML supports cascading. If an element matches multiple rules, they are applied in the order they were added. The output of the first rule becomes the `{content}` for the subsequent rule.
+
+```javascript
+const converter = new MationHTML();
+
+converter.addRule([
+  {
+    selector: ".text",
+    render: "@{content}",
+  },
+  {
+    selector: "p",
+    render: "{content}@",
+  },
+]);
+
+const output = converter.convert(`<p class="text">Hi!</p>`);
+console.log(output);
+// @Hi!@
+```
+
+#### Rules Must Return a Value
+
+When defining a rule, the `render` property (whether it's a string or a function) cannot be `undefined` or an empty string (if it isn't a function-based).
+
+```javascript
+// This will throw an error!
+converter.addRule({ selector: "p", render: "" });
+```
+
+If you intentionally want to output nothing for a specific rule, use the `{null}` placeholder in strings:
+
+```javascript
+converter.addRule({ selector: "p", render: "{null}" });
+```
+
+If you are using a function-based render, you can simply return an empty string:
+
+```javascript
+converter.addRule({ selector: "p", render: () => "" });
+```
+
+## Contributing
+
+There's always room for improvement. Feel free to contribute!
+
+## Licensing
+
+The project is licensed under MIT License. Check the license file for more details.

package/dist/mationhtml.min.js

@@ -0,0 +1 @@
+var MationHTML=(()=>{var m=(i,r)=>()=>(r||i((r={exports:{}}).exports,r),r.exports);var g=m((A,y)=>{var f=class i{static DOMParser=null;static Node=null;constructor(){this.rules=[]}#r=null;#e=[];#n=[];set fallbackHandler(r){if(typeof r!="function")throw new Error("Fallback handler must be a function.");this.#r=r}addIgnoredSelectors(r){if(!Array.isArray(r))throw new Error("Selectors must be an array of strings.");for(let t of r){if(typeof t!="string")throw new Error("Selector must be a string.");this.#e.includes(t)||this.#e.push(t)}}addStringReplacements(r){let t=Array.isArray(r)?r:[r];for(let n of t){if(!n?.from||!n?.to)throw new Error("Invalid replacement object. Must contain 'from' and 'to'.");this.#n.push({from:n.from,to:n.to})}}addRule(r){let t=Array.isArray(r)?r:[r];for(let n of t)this.#i(n),this.rules.push(n)}convert(r,t=!0){if(typeof r!="string")throw new Error("Input must be a string.");if(!i.DOMParser)throw new Error("DOMParser is not initialized. Check your entry point.");let l=new i.DOMParser().parseFromString(r,"text/html").body,a=this.#t(l,0,t);for(let c of this.#n)a=a.replaceAll(c.from,c.to);return a.trim()}#t(r,t=0,n=!0){return r.nodeType===i.Node.TEXT_NODE?r.parentElement?.tagName==="PRE"?r.textContent:n?r.textContent.replace(/\s+/g," "):r.textContent:r.nodeType===i.Node.ELEMENT_NODE?this.#e.some(s=>r.matches(s))?"":this.#s(r,t,n):""}#o(r,t,n){let s="";for(let l of Array.from(r.childNodes))s+=this.#t(l,t+1,n);return s}#s(r,t,n){let s=this.rules.filter(e=>r.matches(e.selector)),l=Array.from(r.attributes).reduce((e,o)=>(e[o.name]=o.value,e),{}),a=e=>{if(!e)throw new Error("applyRules requires a targetNode.");if(e===r)throw new Error("applyRules cannot be called with the current node.");return this.#t(e,t,n)},c=()=>this.#o(r,t,n),h=e=>({node:r,attributes:l,depth:t,applyRules:a,get content(){return e()}});if(s.length>0){let e=null;for(let o of s){let p=e!==null?e:c();if(typeof o.render=="function"){let w=h(()=>p),u=o.render(w);if(u===void 0)throw new Error(`Rule for "${o.selector}" returned undefined.`);e=u}else typeof o.render=="string"&&(e=o.render.replace(/{attributes\.([\w-]+)}/g,(w,u)=>l[u]||"").replace(/{content}/g,p).replace(/{null}/g,""))}return e}if(this.#r){let e=h(c),o=this.#r(e);if(o!==void 0)return o;throw new Error("Fallback handler must return content.")}return c()}#i(r){if(typeof r!="object"||!r.selector||!r.render)throw new Error("Invalid rule structure. Requires 'selector' and 'render'.");if(typeof r.render!="string"&&typeof r.render!="function")throw new Error(`Rule for "${r.selector}" is invalid. 'render' must be a string or a function.`)}};y.exports=f});var b=m((N,E)=>{var d=g();d.DOMParser=window.DOMParser;d.Node=window.Node;E.exports=d});return b();})();

package/dist/mationhtml.node.js

@@ -0,0 +1 @@
+var E=(i,r)=>()=>(r||i((r={exports:{}}).exports,r),r.exports);var y=E((A,m)=>{var f=class i{static DOMParser=null;static Node=null;constructor(){this.rules=[]}#r=null;#e=[];#n=[];set fallbackHandler(r){if(typeof r!="function")throw new Error("Fallback handler must be a function.");this.#r=r}addIgnoredSelectors(r){if(!Array.isArray(r))throw new Error("Selectors must be an array of strings.");for(let t of r){if(typeof t!="string")throw new Error("Selector must be a string.");this.#e.includes(t)||this.#e.push(t)}}addStringReplacements(r){let t=Array.isArray(r)?r:[r];for(let n of t){if(!n?.from||!n?.to)throw new Error("Invalid replacement object. Must contain 'from' and 'to'.");this.#n.push({from:n.from,to:n.to})}}addRule(r){let t=Array.isArray(r)?r:[r];for(let n of t)this.#i(n),this.rules.push(n)}convert(r,t=!0){if(typeof r!="string")throw new Error("Input must be a string.");if(!i.DOMParser)throw new Error("DOMParser is not initialized. Check your entry point.");let c=new i.DOMParser().parseFromString(r,"text/html").body,a=this.#t(c,0,t);for(let l of this.#n)a=a.replaceAll(l.from,l.to);return a.trim()}#t(r,t=0,n=!0){return r.nodeType===i.Node.TEXT_NODE?r.parentElement?.tagName==="PRE"?r.textContent:n?r.textContent.replace(/\s+/g," "):r.textContent:r.nodeType===i.Node.ELEMENT_NODE?this.#e.some(s=>r.matches(s))?"":this.#s(r,t,n):""}#o(r,t,n){let s="";for(let c of Array.from(r.childNodes))s+=this.#t(c,t+1,n);return s}#s(r,t,n){let s=this.rules.filter(e=>r.matches(e.selector)),c=Array.from(r.attributes).reduce((e,o)=>(e[o.name]=o.value,e),{}),a=e=>{if(!e)throw new Error("applyRules requires a targetNode.");if(e===r)throw new Error("applyRules cannot be called with the current node.");return this.#t(e,t,n)},l=()=>this.#o(r,t,n),h=e=>({node:r,attributes:c,depth:t,applyRules:a,get content(){return e()}});if(s.length>0){let e=null;for(let o of s){let p=e!==null?e:l();if(typeof o.render=="function"){let w=h(()=>p),u=o.render(w);if(u===void 0)throw new Error(`Rule for "${o.selector}" returned undefined.`);e=u}else typeof o.render=="string"&&(e=o.render.replace(/{attributes\.([\w-]+)}/g,(w,u)=>c[u]||"").replace(/{content}/g,p).replace(/{null}/g,""))}return e}if(this.#r){let e=h(l),o=this.#r(e);if(o!==void 0)return o;throw new Error("Fallback handler must return content.")}return l()}#i(r){if(typeof r!="object"||!r.selector||!r.render)throw new Error("Invalid rule structure. Requires 'selector' and 'render'.");if(typeof r.render!="string"&&typeof r.render!="function")throw new Error(`Rule for "${r.selector}" is invalid. 'render' must be a string or a function.`)}};m.exports=f});var{JSDOM:b}=require("jsdom"),d=y(),g=new b;d.DOMParser=g.window.DOMParser;d.Node=g.window.Node;module.exports=d;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "mationhtml",
+  "version": "1.0.2",
+  "description": "Transform HTML into absolutely any format imaginable.",
+  "main": "dist/mationhtml.node.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rezzvy/mationhtml.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rezzvy/mationhtml/issues"
+  },
+  "homepage": "https://github.com/rezzvy/mationhtml#readme",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build:browser": "esbuild ./src/mationhtml.browser.js --bundle --minify --platform=browser --format=iife --global-name=MationHTML --outfile=dist/mationhtml.min.js",
+    "build:node": "esbuild ./src/mationhtml.node.js --bundle --external:jsdom --minify --platform=node --format=cjs --outfile=dist/mationhtml.node.js",
+    "build": "npm run build:browser && npm run build:node",
+    "test": "node --test"
+  },
+  "keywords": [
+    "html",
+    "html-converter",
+    "html-to-text",
+    "dom"
+  ],
+  "author": "rezzvy",
+  "license": "MIT",
+  "type": "commonjs",
+  "dependencies": {
+    "jsdom": "^29.0.1"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.4"
+  }
+}