├── LICENSE
├── .github
    └── workflows
    │   ├── npm.yml
    │   └── test.yml
├── example.html
├── surreal.js
└── README.md


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


--------------------------------------------------------------------------------
/.github/workflows/npm.yml:
--------------------------------------------------------------------------------
 1 | name: Publish to npm
 2 | 
 3 | on:
 4 |   push:
 5 |     tags:
 6 |       - '*'  # Matches all tags like 1.2.3
 7 |   workflow_dispatch:
 8 | 
 9 | jobs:
10 |   publish:
11 |     runs-on: ubuntu-latest
12 | 
13 |     steps:
14 |       - name: Checkout repository
15 |         uses: actions/checkout@v4
16 | 
17 |       - name: Set up Node.js
18 |         uses: actions/setup-node@v4
19 |         with:
20 |           node-version: '20'
21 |           registry-url: 'https://registry.npmjs.org/'
22 | 
23 |       - name: Extract version from tag
24 |         id: get_version
25 |         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
26 | 
27 |       - name: Generate package.json
28 |         run: |
29 |           cat > package.json <<EOF
30 |           {
31 |             "name": "@geenat/surreal",
32 |             "version": "${{ steps.get_version.outputs.VERSION }}",
33 |             "description": "Surreal",
34 |             "main": "surreal.js",
35 |             "files": [
36 |               "surreal.js",
37 |               "README.md",
38 |               "LICENSE"
39 |             ],
40 |             "repository": {
41 |               "type": "git",
42 |               "url": "https://github.com/gnat/surreal.git"
43 |             },
44 |             "author": "gnat",
45 |             "license": "MIT",
46 |             "keywords": [
47 |               "jquery",
48 |               "jquery-like",
49 |               "jquery-alternative",
50 |               "jquery-replacement",
51 |               "javascript",
52 |               "utility",
53 |               "hyperscript",
54 |               "dom",
55 |               "dom-manipulation",
56 |               "lob",
57 |               "locality-of-behavior",
58 |               "htmx",
59 |               "selector",
60 |               "queryselectorall",
61 |               "queryselector"
62 |             ],
63 |             "bugs": {
64 |               "url": "https://github.com/gnat/surreal/issues"
65 |             }
66 |           }
67 |           EOF
68 | 
69 |       - name: Publish to npm
70 |         run: npm publish --access public
71 |         env:
72 |           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
73 | 


--------------------------------------------------------------------------------
/.github/workflows/test.yml:
--------------------------------------------------------------------------------
 1 | name: Test Surreal.js in Emulated Browser
 2 | 
 3 | on:
 4 |   push:
 5 |     branches:
 6 |       - main
 7 |   pull_request:
 8 | 
 9 | jobs:
10 |   test:
11 |     runs-on: ubuntu-latest
12 | 
13 |     steps:
14 |       - name: Checkout repo
15 |         uses: actions/checkout@v3
16 | 
17 |       - name: Download surreal.js
18 |         run: curl -o surreal.js https://raw.githubusercontent.com/gnat/surreal/refs/heads/main/surreal.js
19 | 
20 |       - name: Add global export at bottom of surreal.js for node
21 |         run: |
22 |           cat << 'EOF' >> surreal.js
23 |           if (typeof window !== 'undefined') { window.surreal = surreal; } else if (typeof globalThis !== 'undefined') { globalThis.surreal = surreal; }
24 |           EOF
25 |           
26 |       - name: Setup Node.js
27 |         uses: actions/setup-node@v3
28 |         with:
29 |           node-version: '18'
30 | 
31 |       - name: Install dependencies and configure ESM
32 |         run: |
33 |           npm init -y
34 |           jq '. + {type: "module"}' package.json > tmp.json && mv tmp.json package.json
35 |           npm install mocha chai jsdom jsdom-global
36 | 
37 |       - name: Create test file
38 |         run: |
39 |           mkdir -p test
40 |           cat << 'EOF' > test/surreal.test.js
41 |           import 'jsdom-global/register.js';
42 |           import { expect } from 'chai';
43 | 
44 |           // Load surreal.js (adds Surreal to window)
45 |           import '../surreal.js';
46 | 
47 |           describe('Surreal Test Suite', () => {
48 |             it('Test suite works?', () => {
49 |               expect(1 + 1).to.equal(2);
50 |             });
51 |             
52 |             it('should have surreal defined globally on window', () => {
53 |               expect(window.surreal).to.exist;
54 |             });
55 | 
56 |             it('should have a method classRemove if exists', () => {
57 |               expect(window.surreal.classRemove).to.be.a('function');
58 |             });
59 | 
60 |             it('classAdd should add class to element', () => {
61 |               expect(window.surreal.classAdd).to.be.a('function');
62 | 
63 |               const el = document.createElement('div');
64 |               window.surreal.classAdd(el, 'test-class');
65 | 
66 |               expect(el.classList.contains('test-class')).to.be.true;
67 |             });
68 |           });
69 |           EOF
70 | 
71 |       - name: Run tests
72 |         run: npx mocha test/surreal.test.js
73 | 


--------------------------------------------------------------------------------
/example.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html>
  3 | 	<head>
  4 | 		<title>Quick and Dirty Testing for Surreal</title>
  5 | 		<!-- <script src="https://cdn.jsdelivr.net/gh/gnat/surreal@main/surreal.js"></script> -->
  6 | 		<script src="surreal.js"></script>
  7 | 		<meta http-equiv="cache-control" content="no-cache" />
  8 | 	</head>
  9 | 	<body>
 10 | 		<!-- Basic examples -->
 11 | 		<button>👁️ Click me to fade out and remove.
 12 | 			<script>
 13 | 				me().on("click", ev => { me(ev).disable(); me(ev).fadeOut() })
 14 | 			</script>
 15 | 		</button>
 16 | 		<button class="invisible">👻 Click me to fade in.
 17 | 			<script>
 18 | 				me().on("click", ev => {
 19 | 					// Simple way to limit number of actions.
 20 | 					if(me(ev)?.fadeInLimit <= 1) return; else { me(ev).fadeInLimit = 1; me(ev).fadeIn() }
 21 | 				})
 22 | 			</script>
 23 | 		</button>
 24 | 		<div class="yeet noot">I should be red.
 25 | 			<script>
 26 | 				any(".yeet.noot").classAdd('.active')
 27 | 			</script>
 28 | 		</div>
 29 | 		<!-- Basic async examples -->
 30 | 		<div id="random">I should turn grey after 2 seconds.
 31 | 			<script>
 32 | 				// Basic usage with id. Runs immediately.
 33 | 				(async ()=>{
 34 | 					me("#random").classAdd('active')
 35 | 					await sleep(2000)
 36 | 					me("#random").classAdd('inactive')
 37 | 				})()
 38 | 			</script>
 39 | 		</div>
 40 | 		<div>I should be animated using events.
 41 | 			<script>
 42 | 				// Now you're thinking with events!
 43 | 				me().on("ping", async ev => {
 44 | 					let e = me(ev)
 45 | 					e.styles({"background":"hotpink", "color":"purple"})
 46 | 					await sleep(1000)
 47 | 					e.send("pong")
 48 | 				})
 49 | 				me().on("pong", async ev => {
 50 | 					let e = me(ev)
 51 | 					e.styles({"background":"blue", "color":"#002200"})
 52 | 					await sleep(1000)
 53 | 					e.send("ping")
 54 | 				})
 55 | 				me().styles({"transition":"all 2s"}).send("pong")
 56 | 			</script>
 57 | 		</div>
 58 | 		<div>I should be animated using timeline / async until finished!
 59 | 			<script>
 60 | 				// Now you're thinking with async! Runs immediately. No event.
 61 | 				(async (e = me()) => { // Special case where we can save element right away.
 62 | 					e.styles({"transition": "all 2s"})
 63 | 					e.styles({"background":"#0030F7", "color":"#002200"})
 64 | 					await sleep(2000)
 65 | 					e.styles({"background":"#006BFF", "color":"#000033"})
 66 | 					await sleep(2000)
 67 | 					e.styles({"background":"#00A1FF", "color":"#005500"})
 68 | 					await sleep(2000)
 69 | 					e.styles({"background":"#00C08C", "color":"#660033"})
 70 | 					await sleep(2000)
 71 | 
 72 | 					// New element!
 73 | 					var e2 = me(createElement("div"))
 74 | 					e2.styles({"transition":"all 2s", "opacity":"0", "height":"0%"})
 75 | 					e2.innerText = "🔥🔥🔥🔥🔥🔥"
 76 | 					e.appendChild(e2)
 77 | 					await sleep(1000)
 78 | 					e2.styles({"opacity":"1", "height":"fit-content"})
 79 | 				})()
 80 | 			</script>
 81 | 		</div>
 82 | 		<div>I should be surrounded by diamonds after a few seconds.
 83 | 			<script>
 84 | 				// Now you're thinking with async! Runs immediately. No event.
 85 | 				(async (e = me()) => { // Special case where we can save element right away.
 86 | 					e.styles({"transition":"all 2s", "color":"#fff"})
 87 | 
 88 | 					// New element!
 89 | 					var e2 = me(createElement("div"))
 90 | 					e2.innerText = "💎💎💎"
 91 | 					e.prepend(e2)
 92 | 					e2.styles({"transition":"all 2s", "opacity":"0"})
 93 | 					await sleep(1000)
 94 | 					e2.styles({"opacity":"1"})
 95 | 					await sleep(2000)
 96 | 
 97 | 					// New element!
 98 | 					var e2 = me(createElement("div"))
 99 | 					e2.styles({"transition":"all 2s", "opacity":"0"})
100 | 					e2.innerText = "💎💎💎"
101 | 					e.appendChild(e2)
102 | 					await sleep(1000)
103 | 					e2.styles({"opacity":"1"})
104 | 				})()
105 | 			</script>
106 | 		</div>
107 | 		<!-- Event examples -->
108 | 		<div thick>📬 I close from a child button event.
109 | 			<script>
110 | 				me().on("close", async event => { me(event).fadeOut() }) // Recieve "close" event.
111 | 			</script>
112 | 			<button  class="close">✉️ Send "close"
113 | 				<script>
114 | 					me().on("click", event => { me(event).disable(); me(event).send("close") })
115 | 				</script>
116 | 			</button>
117 | 		</div>
118 | 		<div thick>📭 I stay open because of <strong>halt()</strong>
119 | 			<script>
120 | 				me().on("close", event => {  me(event).fadeOut() }) // I will never recieve "close" event because of halt()
121 | 			</script>
122 | 			<div thick>📬 I close dramatically from a child button <strong>async</strong> event
123 | 				<script>
124 | 					me().on("close", async event => {
125 | 						let e = me(event) // Save element because event.currentTarget will be lost after await.
126 | 						e.halt(event) // Event stops here.
127 | 						e.disable() // Prevent user from clicking button many times.
128 | 						e.styles({"transition":"all 0.5s", "background":"red"})
129 | 						await sleep(500)
130 | 						e.styles({"background":"white"})
131 | 						await sleep(500)
132 | 						e.styles({"background":"red"})
133 | 						await sleep(500)
134 | 						e.styles({"background":"white"})
135 | 						e.fadeOut()
136 | 					})
137 | 				</script>
138 | 				<button class="close">✉️ Send "close"
139 | 					<script>
140 | 						me().on("click", event => { me(event).disable(); me(event).send("close") }) // Use disable() to stop clicking more than once.
141 | 					</script>
142 | 				</button>
143 | 			</div>
144 | 		</div>
145 | 		<!-- Scoping and 3D -->
146 | 		<div class="card">
147 | 			3D Card
148 | 			<div></div>
149 | 			<script>
150 | 				me().on('mouseenter', (ev) => {
151 | 					let e = me(ev)
152 | 					e.bounds = e.getBoundingClientRect()
153 | 					e.on('mousemove', e.rotateToMouse)
154 | 				})
155 | 				me().on('mouseleave', (ev) => {
156 | 					let e = me(ev)
157 | 					e.off('mousemove', e.rotateToMouse)
158 | 					e.style.transform = ''
159 | 					e.style.background = ''
160 | 				})
161 | 				me().rotateToMouse = (ev) => {
162 | 					let e = me(ev)
163 | 					let mouseX = ev.clientX
164 | 					let mouseY = ev.clientY
165 | 					let leftX = mouseX - e.bounds.x
166 | 					let topY = mouseY - e.bounds.y
167 | 					let center = { x: leftX - e.bounds.width / 2, y: topY - e.bounds.height / 2 }
168 | 					let distance = Math.sqrt(center.x**2 + center.y**2)
169 | 					e.style.transform = `scale3d(1.07, 1.07, 1.0) rotate3d(${center.y / 100}, ${-center.x / 100}, 0, ${Math.log(distance)* 1}0deg)`
170 | 					me('div', e).style.backgroundImage = `radial-gradient(circle at ${center.x * 2 + e.bounds.width/2}px ${center.y * 2 + e.bounds.height/2}px, #ffffff55, #0000000f)`
171 | 				}
172 | 			</script>
173 | 		</div>
174 | 		<!-- Try out window.onload predictable call chain -->
175 | 		<script>onloadAdd(()=>{ console.log("Hello from Surreal onloadAdd()") })</script>
176 | 		<script>onloadAdd(()=>{ console.log("I added to onload without clobbering the previous function") })</script>
177 | 		<!-- Check the code! -->
178 | 		<button class="blue">😺 Visit the source code for this page.
179 | 			<script>
180 | 				me().on("click", ev => { window.location.href ="https://github.com/gnat/surreal/blob/main/example.html" })
181 | 			</script>
182 | 		</button>
183 | 	</body>
184 | 	<style>
185 | 		/* stylesheet.css */
186 | 		html,body,p,ol,ul,li,dl,dt,dd,blockquote,figure,fieldset,legend,textarea,pre,iframe,hr,h1,h2,h3,h4,h5,h6,label {
187 | 			margin: 0;
188 | 			padding: 0;
189 | 			font-family: sans-serif;
190 | 		}
191 | 		button,input,select,textarea {
192 | 			margin: 0;
193 | 			font: inherit;
194 | 		}
195 | 		html {
196 | 			font-size: 10px; /* 1.8 rem = 18px */
197 | 			text-size-adjust: none; /* Fixes chrome on mobile. */
198 | 			-webkit-text-size-adjust: none; /* Fixes safari on mobile. */
199 | 			-moz-text-size-adjust: none; /* Firefox works fine, but for consistency. */
200 | 			background: #adadad;
201 | 		}
202 | 		/* Custom for showcase. */
203 | 		body {
204 | 			font-family: system-ui, sans-serif;
205 | 			font-size: 2rem;
206 | 			padding: 1rem;
207 | 			background: #adadad;
208 | 			color: #ccc;
209 | 			perspective: 1500px;
210 | 		}
211 | 		.active {
212 | 			background: hsl(345deg 100% 47%);
213 | 			transition: background 3s;
214 | 		}
215 | 		.inactive {
216 | 			background: grey;
217 | 			transition: background 3s;
218 | 		}
219 | 		body > div {
220 | 			color: #222;
221 | 			margin: 1rem;
222 | 			padding: 1rem;
223 | 			border-radius: 1rem;
224 | 		}
225 | 		body div[thick] {
226 | 			color: #222;
227 | 			margin: 2rem;
228 | 			padding: 3rem;
229 | 			border-radius: 1rem;
230 | 			background: #eee;
231 | 		}
232 | 		body div[thick] div[thick] {
233 | 			background: #ccc;
234 | 		}
235 | 		button {
236 | 			cursor: pointer;
237 | 			color: #fff;
238 | 			padding: 2rem 3rem;
239 | 			margin: 2rem;
240 | 			border: none;
241 | 			background: hsl(262deg 86% 47%);
242 | 			border-bottom: 0.5rem solid hsl(262deg 86% 28%);
243 | 			border-radius: 12px;
244 | 			text-shadow: 0 2px #222222AA;
245 | 		}
246 | 		button:active {
247 | 			transform: translateY(0.2rem);
248 | 		}
249 | 		button.blue {
250 | 			background: hsl(200deg 100% 47%);
251 | 			border: none;
252 | 			border-bottom: 0.5rem solid hsl(200deg 100% 28%);
253 | 		}
254 | 		button.invisible {
255 | 			opacity: 0.2;	
256 | 			background: hsl(147, 60%, 50%);
257 | 			border-bottom: 0.5rem solid hsl(147 80% 28%);
258 | 		}
259 | 		button.close {
260 | 			background: hsl(345deg 90% 40%);
261 | 			border-bottom: 0.5rem solid hsl(345deg 100% 28%);
262 | 			border-radius: 12px;
263 | 		}
264 | 		button.close:disabled {
265 | 			color: #aaa;
266 | 			background: hsl(345deg 0% 30%);
267 | 			border-bottom: 0.5rem solid hsl(345deg 0% 18%);
268 | 			transform: translateY(0.2rem);
269 | 		}
270 | 		.card {
271 | 			position: relative;
272 | 			width: 300px;
273 | 			height: 400px;
274 | 			padding: 1em;
275 | 			margin: 2em auto;
276 | 			font-weight: bold;
277 | 			text-align: right;
278 | 			text-shadow: 0 0 4px #000;
279 | 			color: #ddd;
280 | 			box-shadow: 0 1px 5px #00000099;
281 | 			border-radius: 10px;
282 | 			background: #999 center;
283 | 			background-size: cover;
284 | 			cursor: pointer;
285 | 			transition-duration: 300ms;
286 | 			transition-property: transform, box-shadow;
287 | 			transition-timing-function: ease-out;
288 | 			transform: rotate3d(0);
289 | 		}
290 | 		.card :hover {
291 | 			transition-duration: 150ms;
292 | 			box-shadow: 0 5px 20px 5px #00000044;
293 | 		}
294 | 		.card > div {
295 | 			position: absolute;
296 | 			width: 100%;
297 | 			height: 100%;
298 | 			left: 0;
299 | 			top: 0;
300 | 			border-radius: 10px;
301 | 			background-image: radial-gradient(circle at 90% -20%, #ffffff33, #0000000f);
302 | 		}
303 | 	</style>
304 | </html>
305 | 
306 | 


--------------------------------------------------------------------------------
/surreal.js:
--------------------------------------------------------------------------------
  1 | // Welcome to Surreal 1.3.4
  2 | // Documentation: https://github.com/gnat/surreal
  3 | // Locality of Behavior (LoB): https://htmx.org/essays/locality-of-behaviour/
  4 | let surreal = (function () {
  5 | let $ = { // Convenience for internals.
  6 | 	$: this, // Convenience for internals.
  7 | 	plugins: [],
  8 | 
  9 | 	// Table of contents and convenient call chaining sugar. For a familiar "jQuery like" syntax. 🙂
 10 | 	// Check before adding new: https://youmightnotneedjquery.com/
 11 | 	sugar(e) {
 12 | 		if (!$.isNode(e) && !$.isNodeList(e)) { console.warn(`Surreal: Not a supported element / node / node list "${e}"`); return e }
 13 | 		if ($.isNodeList(e)) e.forEach(_ => { $.sugar(_) }) // Add Surreal to all nodes from any()
 14 | 		if (e.hasOwnProperty('hasSurreal')) return e // Surreal already added.
 15 | 
 16 | 		// General
 17 | 		e.run           = (f) => { return $.run(e, f) }
 18 | 		e.remove        = () => { return $.remove(e) }
 19 | 
 20 | 		// Classes and CSS.
 21 | 		e.classAdd      = (name) => { return $.classAdd(e, name) }
 22 | 		e.class_add     = e.add_class = e.addClass = e.classAdd // Alias
 23 | 		e.classRemove   = (name) => { return $.classRemove(e, name) }
 24 | 		e.class_remove  = e.remove_class = e.removeClass = e.classRemove // Alias
 25 | 		e.classToggle   = (name, force) => { return $.classToggle(e, name, force) }
 26 | 		e.class_toggle  = e.toggle_class = e.toggleClass = e.classToggle // Alias
 27 | 		e.styles        = (value) => { return $.styles(e, value) }
 28 | 
 29 | 		// Events.
 30 | 		e.on            = (name, f) => { return $.on(e, name, f) }
 31 | 		e.off           = (name, f) => { return $.off(e, name, f) }
 32 | 		e.offAll        = (name) => { return $.offAll(e, name) }
 33 | 		e.off_all       = e.offAll // Alias
 34 | 		e.disable       = () => { return $.disable(e) }
 35 | 		e.enable        = () => { return $.enable(e) }
 36 | 		e.send          = (name, detail) => { return $.send(e, name, detail) }
 37 | 		e.trigger       = e.send // Alias
 38 | 		e.halt          = (ev, keepBubbling, keepDefault) => { return $.halt(ev, keepBubbling, keepDefault) }
 39 | 
 40 | 		// Attributes.
 41 | 		e.attribute 	= (name, value) => { return $.attribute(e, name, value) }
 42 | 		e.attributes    = e.attr = e.attribute // Alias
 43 | 
 44 | 		// Add all plugins.
 45 | 		$.plugins.forEach(function(func) { func(e) })
 46 | 
 47 | 		e.hasSurreal = 1
 48 | 		return e
 49 | 	},
 50 | 	// me() will return a single element or null. Selector not needed if used with inline <script>
 51 | 	// If you select many elements, me() will return the first.
 52 | 	// Example
 53 | 	//	<div>
 54 | 	//		Hello World!
 55 | 	//		<script>me().style.color = 'red'</script>
 56 | 	//	</div>
 57 | 	me(selector=null, start=document, warning=true) {
 58 | 		if (selector == null) return $.sugar(start.currentScript.parentElement) // Just local me() in <script>
 59 | 		if (selector instanceof Event) return selector.currentTarget ? $.me(selector.currentTarget) : (console.warn(`Surreal: Event currentTarget is null. Please save your element because async will lose it`), null) // Events try currentTarget
 60 | 		if (selector === '-' || selector === 'prev' || selector === 'previous') return $.sugar(start.currentScript.previousElementSibling) // Element directly before <script>
 61 | 		if ($.isSelector(selector, start, warning)) return $.sugar(start.querySelector(selector)) // String selector.
 62 | 		if ($.isNodeList(selector)) return $.me(selector[0]) // If we got a list, return the first element.
 63 | 		if ($.isNode(selector)) return $.sugar(selector) // Valid element.
 64 | 		return null // Invalid.
 65 | 	},
 66 | 	// any() is me() but will return an array of elements or empty [] if nothing is found.
 67 | 	// You may optionally use forEach/map/filter/reduce.
 68 | 	// Example: any('button')
 69 | 	any(selector, start=document, warning=true) {
 70 | 		if (selector == null) return $.sugar([start.currentScript.parentElement]) // Similar to me()
 71 | 		if (selector instanceof Event) return selector.currentTarget ? $.any(selector.currentTarget) : (console.warn(`Surreal: Event currentTarget is null. Please save your element because async will lose it`), null) // Events try currentTarget
 72 | 		if (selector === '-' || selector === 'prev' || selector === 'previous') return $.sugar([start.currentScript.previousElementSibling]) // Element directly before <script>
 73 | 		if ($.isSelector(selector, start, warning)) return $.sugar(Array.from(start.querySelectorAll(selector))) // String selector.
 74 | 		if ($.isNode(selector)) return $.sugar([selector]) // Single element. Convert to Array.
 75 | 		if ($.isNodeList(selector)) return $.sugar(Array.from(selector)) // Valid NodeList or Array.
 76 | 		return $.sugar([]) // Invalid.
 77 | 	},
 78 | 	// Run any function on element(s)
 79 | 	run(e, f) {
 80 | 		if (typeof f !== 'function') { console.warn(`Surreal: run(f) f must be a function`); return e }
 81 | 		if ($.isNodeList(e)) e.forEach(_ => { $.run(_, f) })
 82 | 		if ($.isNode(e)) { f(e); }
 83 | 		return e
 84 | 	},
 85 | 	// Remove element(s)
 86 | 	remove(e) {
 87 | 		if ($.isNodeList(e)) e.forEach(_ => { $.remove(_) })
 88 | 		if ($.isNode(e)) e.parentNode.removeChild(e)
 89 | 		return // Special, end of chain.
 90 | 	},
 91 | 	// Add class to element(s).
 92 | 	classAdd(e, name) {
 93 | 		if (typeof name !== 'string') return e
 94 | 		if (name.charAt(0) === '.') name = name.substring(1)
 95 | 		if ($.isNodeList(e)) e.forEach(_ => { $.classAdd(_, name) })
 96 | 		if ($.isNode(e)) e.classList.add(name)
 97 | 		return e
 98 | 	},
 99 | 	// Remove class from element(s).
100 | 	classRemove(e, name) {
101 | 		if (typeof name !== 'string') return e
102 | 		if (name.charAt(0) === '.') name = name.substring(1)
103 | 		if ($.isNodeList(e)) e.forEach(_ => { $.classRemove(_, name) })
104 | 		if ($.isNode(e)) e.classList.remove(name)
105 | 		return e
106 | 	},
107 | 	// Toggle class in element(s).
108 | 	classToggle(e, name, force) {
109 | 		if (typeof name !== 'string') return e
110 | 		if (name.charAt(0) === '.') name = name.substring(1)
111 | 		if ($.isNodeList(e)) e.forEach(_ => { $.classToggle(_, name, force) })
112 | 		if ($.isNode(e)) e.classList.toggle(name, force)
113 | 		return e
114 | 	},
115 | 	// Add inline style to element(s).
116 | 	// Can use string or object formats.
117 | 	// 	String format: "font-family: 'sans-serif'"
118 | 	// 	Object format; { fontFamily: 'sans-serif', backgroundColor: '#000' }
119 | 	styles(e, value) {
120 | 		if (typeof value === 'string') { // Format: "font-family: 'sans-serif'"
121 | 			if ($.isNodeList(e)) e.forEach(_ => { $.styles(_, value) })
122 | 			if ($.isNode(e)) { $.attribute(e, 'style', ($.attribute(e, 'style') == null ? '' : $.attribute(e, 'style') + '; ') + value)  }
123 | 			return e
124 | 		}
125 | 		if (typeof value === 'object') { // Format: { fontFamily: 'sans-serif', backgroundColor: '#000' }
126 | 			if ($.isNodeList(e)) e.forEach(_ => { $.styles(_, value) })
127 | 			if ($.isNode(e)) { Object.assign(e.style, value)  }
128 | 			return e
129 | 		}
130 | 		return e
131 | 	},
132 | 	// Add event listener to element(s).
133 | 	// Match a sender: if (!event.target.matches(".selector")) return;
134 | 	//	📚️ https://developer.mozilla.org/en-US/docs/Web/API/Event
135 | 	//	✂️ Vanilla: document.querySelector(".thing").addEventListener("click", (e) => { alert("clicked") }
136 | 	on(e, name, f) {
137 | 		if ($.isNodeList(e)) e.forEach(_ => { $.on(_, name, f) })
138 | 		if ($.isNode(e)) e.addEventListener(name, f)
139 | 		return e
140 | 	},
141 | 	off(e, name, f) {
142 | 		if ($.isNodeList(e)) e.forEach(_ => { $.off(_, name, f) })
143 | 		if ($.isNode(e)) e.removeEventListener(name, f)
144 | 		return e
145 | 	},
146 | 	offAll(e) {
147 | 		if ($.isNodeList(e)) e.forEach(_ => { $.offAll(_) })
148 | 		if ($.isNode(e)) e.parentNode.replaceChild(e.cloneNode(true), e)
149 | 		return e
150 | 	},
151 | 	// Easy alternative to off(). Disables click, key, submit events.
152 | 	disable(e) {
153 | 		if ($.isNodeList(e)) e.forEach(_ => { $.disable(_) })
154 | 		if ($.isNode(e)) e.disabled = true
155 | 		return e
156 | 	},
157 | 	// For reversing disable()
158 | 	enable(e) {
159 | 		if ($.isNodeList(e)) e.forEach(_ => { $.enable(_) })
160 | 		if ($.isNode(e)) e.disabled = false
161 | 		return e
162 | 	},
163 | 	// Send / trigger event.
164 | 	// ✂️ Vanilla: Events Dispatch: document.querySelector(".thing").dispatchEvent(new Event('click'))
165 | 	send(e, name, detail=null) {
166 | 		if ($.isNodeList(e)) e.forEach(_ => { $.send(_, name, detail) })
167 | 		if ($.isNode(e)) {
168 | 			const event = new CustomEvent(name, { detail: detail, bubbles: true })
169 | 			e.dispatchEvent(event)
170 | 		}
171 | 		return e
172 | 	},
173 | 	// Halt event. Default: Stops normal event actions and event propagation.
174 | 	halt(ev, keepBubbling=false, keepDefault=false) {
175 | 		if (ev instanceof Event) {
176 | 			if (!keepDefault) ev.preventDefault()
177 | 			if (!keepBubbling) ev.stopPropagation()
178 | 		}
179 | 		return ev
180 | 	},
181 | 	// Add or remove attributes from element(s)
182 | 	attribute(e, name, value=undefined) {
183 | 		// Get. (Format: "name", "value") Special: Ends call chain.
184 | 		if (typeof name === 'string' && value === undefined) {
185 | 			if ($.isNodeList(e)) return [] // Not supported for Get. For many elements, wrap attribute() in any(...).run(...) or any(...).forEach(...)
186 | 			if ($.isNode(e)) return e.getAttribute(name)
187 | 			return null // No value. Ends call chain.
188 | 		}
189 | 		// Remove.
190 | 		if (typeof name === 'string' && value === null) {
191 | 			if ($.isNodeList(e)) e.forEach(_ => { $.attribute(_, name, value) })
192 | 			if ($.isNode(e)) e.removeAttribute(name)
193 | 			return e
194 | 		}
195 | 		// Add / Set.
196 | 		if (typeof name === 'string') {
197 | 			if ($.isNodeList(e)) e.forEach(_ => { $.attribute(_, name, value) })
198 | 			if ($.isNode(e)) e.setAttribute(name, value)
199 | 			return e
200 | 		}
201 | 		// Format: { "name": "value", "blah": true }
202 | 		if (typeof name === 'object') {
203 | 			if ($.isNodeList(e)) e.forEach(_ => { Object.entries(name).forEach(([key, val]) => { $.attribute(_, key, val) }) })
204 | 			if ($.isNode(e)) Object.entries(name).forEach(([key, val]) => { $.attribute(e, key, val) })
205 | 			return e
206 | 		}
207 | 		return e
208 | 	},
209 | 	// Puts Surreal functions except for "restricted" in global scope.
210 | 	globalsAdd() {
211 | 		console.log(`Surreal: Adding convenience globals to window.`)
212 | 		let restricted = ['$', 'sugar', 'plugins']
213 | 		for (const [key, value] of Object.entries(this)) {
214 | 			if (!restricted.includes(key)) window[key] === undefined ? window[key] = value : console.warn(`Surreal: "${key}()" already exists on window. Skipping to prevent overwrite.`)
215 | 			if (!restricted.includes(key)) window.document[key] === undefined ? window.document[key] = value : console.warn(`Surreal: "${key}()" already exists on document. Skipping to prevent overwrite.`)
216 | 		}
217 | 	},
218 | 	// ⚙️ Used internally. Is this an element / node?
219 | 	isNode(e) {
220 | 		return (e instanceof HTMLElement || e instanceof SVGElement || e instanceof Document) ? true : false
221 | 	},
222 | 	// ⚙️ Used internally by DOM functions. Is this a list of elements / nodes?
223 | 	isNodeList(e) {
224 | 		return (e instanceof NodeList || Array.isArray(e)) ? true : false
225 | 	},
226 | 	// ⚙️ Used internally by DOM functions. Warning when selector is invalid. Likely missing a "#" or "."
227 | 	isSelector(selector="", start=document, warning=true) {
228 | 		if (typeof selector !== 'string') return false
229 | 		if (start.querySelector(selector) == null) {
230 | 			if (warning) console.log(`Surreal: "${selector}" not found, ignoring.`)
231 | 			return false
232 | 		}
233 | 		return true // Valid.
234 | 	},
235 | }
236 | // Finish up...
237 | $.globalsAdd() // Full convenience.
238 | console.log("Surreal: Loaded.")
239 | return $
240 | })() // End of Surreal 👏
241 | 
242 | // 🔌 Plugin: Effects
243 | function pluginEffects(e) {
244 | 	// Fade out and remove element.
245 | 	// Equivalent to jQuery fadeOut(), but actually removes the element!
246 | 	function fadeOut(e, f=undefined, ms=1000, remove=true) {
247 | 		let thing = e
248 | 		if (surreal.isNodeList(e)) e.forEach(_ => { fadeOut(_, f, ms) })
249 | 		if (surreal.isNode(e)) {
250 | 			(async() => {
251 | 				surreal.styles(e, {transform: 'scale(1)', transition: `all ${ms}ms ease-out`, overflow: 'hidden'})
252 | 				await tick()
253 | 				surreal.styles(e, {transform: 'scale(0.9)', opacity: '0'})
254 | 				await sleep(ms, e)
255 | 				if (typeof f === 'function') f(thing) // Run custom callback?
256 | 				if (remove) surreal.remove(thing) // Remove element after animation is completed?
257 | 			})()
258 | 		}
259 | 	}
260 | 	// Fade in an element that has opacity under 1
261 | 	function fadeIn(e, f=undefined, ms=1000) {
262 | 		let thing = e
263 | 		if (surreal.isNodeList(e)) e.forEach(_ => { fadeIn(_, f, ms) })
264 | 		if (surreal.isNode(e)) {
265 | 			(async() => {
266 | 				let save = e.style // Store original style.
267 | 				surreal.styles(e, {transition: `all ${ms}ms ease-in`, overflow: 'hidden'})
268 | 				await tick()
269 | 				surreal.styles(e, {opacity: '1'})
270 | 				await sleep(ms, e)
271 | 				e.style = save // Revert back to original style.
272 | 				surreal.styles(e, {opacity: '1'}) // Ensure we're visible after reverting to original style.
273 | 				if (typeof f === 'function') f(thing) // Run custom callback?
274 | 			})()
275 | 		}
276 | 	}
277 | 	// Add sugar
278 | 	e.fadeOut  = (f, ms, remove) => { return fadeOut(e, f, ms, remove) }
279 | 	e.fade_out = e.fadeOut
280 | 	e.fadeIn   = (f, ms) => { return fadeIn(e, f, ms) }
281 | 	e.fade_in  = e.fadeIn
282 | }
283 | 
284 | // 🔌 Add plugins here!
285 | surreal.plugins.push(pluginEffects)
286 | console.log("Surreal: Added plugins.")
287 | 
288 | // 🌐 Add global shortcuts here!
289 | // DOM.
290 | const createElement = document.createElement.bind(document); const create_element = createElement
291 | // Animation.
292 | const rAF = typeof requestAnimationFrame !== 'undefined' && requestAnimationFrame
293 | const rIC = typeof requestIdleCallback !== 'undefined' && requestIdleCallback
294 | // Animation: Wait for next animation frame, non-blocking.
295 | async function tick() {
296 | 	return await new Promise(resolve => { requestAnimationFrame(resolve) })
297 | }
298 | // Animation: Sleep, non-blocking.
299 | async function sleep(ms, e) {
300 | 	return await new Promise(resolve => setTimeout(() => { resolve(e) }, ms))
301 | }
302 | // Loading: Why? So you don't clobber window.onload (predictable sequential loading)
303 | // Example: <script>onloadAdd(() => { console.log("Page was loaded!") })</script>
304 | // Example: <script>onloadAdd(() => { console.log("Lets do another thing without clobbering window.onload!") })</script>
305 | const addOnload = (f) => {
306 | 	if (typeof window.onload === 'function') { // window.onload already is set, queue functions together (creates a call chain).
307 | 		let onload_old = window.onload
308 | 		window.onload = () => {
309 | 			onload_old()
310 | 			f()
311 | 		}
312 | 		return
313 | 	}
314 | 	window.onload = f // window.onload was not set yet.
315 | }
316 | const onloadAdd = addOnload; const onload_add = addOnload; const add_onload = addOnload
317 | console.log("Surreal: Added shortcuts.")
318 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # 🗿 Surreal
  2 | ### Tiny jQuery alternative for plain Javascript with inline [Locality of Behavior](https://htmx.org/essays/locality-of-behaviour/)!
  3 | 
  4 | ![cover](https://user-images.githubusercontent.com/24665/171092805-b41286b2-be4a-4aab-9ee6-d604699cc507.png)
  5 | (Art by [shahabalizadeh](https://www.deviantart.com/shahabalizadeh))
  6 | <!--
  7 | <a href="https://github.com/gnat/surreal/archive/refs/heads/main.zip"><img src="https://img.shields.io/badge/Download%20.zip-ff9800?style=for-the-badge&color=%234400e5" alt="Download badge" /></a>
  8 | 
  9 | <a href="https://github.com/gnat/surreal"><img src="https://img.shields.io/github/workflow/status/gnat/surreal/ci?label=ci&style=for-the-badge&color=%237d91ce" alt="CI build badge" /></a>
 10 | <a href="https://github.com/gnat/surreal/releases"><img src="https://img.shields.io/github/workflow/status/gnat/surreal/release?label=Mini&style=for-the-badge&color=%237d91ce" alt="Mini build badge" /></a>
 11 | <a href="https://github.com/gnat/surreal/blob/main/LICENSE"><img src="https://img.shields.io/github/license/gnat/surreal?style=for-the-badge&color=%234400e5" alt="License badge" /></a>-->
 12 | 
 13 | ## Why does this exist?
 14 | 
 15 | For devs who love ergonomics! You may appreciate Surreal if:
 16 | 
 17 | * You want to stay as close as possible to Vanilla JS.
 18 | * Hate typing `document.querySelector` over.. and over..
 19 | * Hate typing `addEventListener` over.. and over..
 20 | * Really wish `document.querySelectorAll` had Array functions..
 21 | * Really wish `this` would work in any inline `<script>` tag
 22 | * Enjoyed using jQuery selector syntax.
 23 | * [Animations, timelines, tweens](#-quick-start) with no extra libraries.
 24 | * Only 320 lines. No build step. No dependencies.
 25 | * Pairs well with [htmx](https://htmx.org)
 26 | * Want fewer layers, less complexity. Are aware of the cargo cult. ✈️
 27 | 
 28 | ## ✨ What does it add to Javascript?
 29 | 
 30 | * ⚡️ [Locality of Behavior (LoB)](https://htmx.org/essays/locality-of-behaviour/) Use `me()` inside `<script>`
 31 |   * No **.class** or **#id** needed! Get an element without creating a unique name.
 32 |   * `this` but much more flexible!
 33 |   * Want `me` in your CSS `<style>` tags, too? See our [companion script](https://github.com/gnat/css-scope-inline)
 34 | * 🔗 Call chaining, jQuery style.
 35 | * ♻️ Functions work seamlessly on 1 element or arrays of elements!
 36 |   * All functions can use: `me()`, `any()`, `NodeList`, `HTMLElement` (..or arrays of these!)
 37 |   * Get 1 element: `me()`
 38 |   * ..or many elements: `any()`
 39 |   * `me()` or `any()` can chain with any Surreal function.
 40 |     * `me()` can be used directly as a single element (like `querySelector()` or `$()`)
 41 |     * `any()` can use: `for` / `forEach` / `filter` / `map` (like `querySelectorAll()` or `$()`)
 42 | * 🌗 No forced style. Use: `classAdd` or `class_add` or `addClass` or `add_class`
 43 |   * Use `camelCase` (Javascript) or `snake_case` (Python, Rust, PHP, Ruby, SQL, CSS).
 44 | 
 45 | ### 🤔 Why use `me()` / `any()` instead of `$()`
 46 | * 💡 Solves the classic jQuery bloat problem: Am I getting 1 element or an array of elements?
 47 |   * `me()` is guaranteed to return 1 element (or first found, or null).
 48 |   * `any()` is guaranteed to return an array (or empty array).
 49 |   * No more checks = write less code. Bonus: Reads more like self-documenting english.
 50 | 
 51 | ## 👁️ How does it look?
 52 | 
 53 | Do surreal things with [Locality of Behavior](https://htmx.org/essays/locality-of-behaviour/) like:
 54 | ```html
 55 | <label for="file-input" >
 56 |   <div class="uploader"></div>
 57 |   <script>
 58 |     me().on("dragover", ev => { halt(ev); me(ev).classAdd('.hover'); console.log("Files in drop zone.") })
 59 |     me().on("dragleave", ev => { halt(ev); me(ev).classRemove('.hover'); console.log("Files left drop zone.") })
 60 |     me().on("drop", ev => { halt(ev); me(ev).classRemove('.hover').classAdd('.loading'); me('#file-input').attribute('files', ev.dataTransfer.files); me('#form').send('change') })
 61 |   </script>
 62 | </label>
 63 | ```
 64 | 
 65 | See the [Live Example](https://gnat.github.io/surreal/example.html)! Then [view source](https://github.com/gnat/surreal/blob/main/example.html).
 66 | 
 67 | ## 🎁 Install
 68 | 
 69 | Surreal is only 320 lines. No build step. No dependencies.
 70 | 
 71 | [📥 Download](https://raw.githubusercontent.com/gnat/surreal/main/surreal.js) into your project, and add `<script src="/surreal.js"></script>` in your `<head>`
 72 | 
 73 | Or, 🌐 via CDN: `<script src="https://cdn.jsdelivr.net/gh/gnat/surreal@main/surreal.js"></script>`
 74 | 
 75 | ## ⚡ Usage
 76 | 
 77 | ### <a name="selectors"></a>🔍️ DOM Selection
 78 | 
 79 | * Select **one** element: `me(...)`
 80 |   * Can be any of:
 81 |     * CSS selector: `".button"`, `"#header"`, `"h1"`, `"body > .block"`
 82 |     * Variables: `body`, `e`, `some_element`
 83 |     * Events: `event.currentTarget` will be used.
 84 |     * Surreal selectors: `me()`,`any()`
 85 |     * Choose the start location in the DOM with the 2nd arg. (Default: `document`)
 86 |       * 🔥 `any('button', me('#header')).classAdd('red')`
 87 |         * Add `.red` to any `<button>` inside of `#header`
 88 |   * `me()` ⭐ Get parent element of `<script>` without a **.class** or **#id** !
 89 |   * `me("body")` Gets `<body>`
 90 |   * `me(".button")` Gets the first `<div class="button">...</div>`. To get all of them use `any()`
 91 | * Select **one or more** elements as an array: `any(...)`
 92 |   * Like `me()` but guaranteed to return an array (or empty array). 
 93 |   * `any(".foo")` ⭐ Get all matching elements.
 94 |   * Convert between arrays of elements and single elements: `any(me())`, `me(any(".something"))`
 95 |  
 96 | ### 🔥 DOM Functions
 97 | 
 98 | * ♻️ All functions work on single elements or arrays of elements.
 99 | * 🔗 Start a chain using `me()` and `any()`
100 |   * 🟢 Style A `me().classAdd('red')` ⭐ Chain style. Recommended!
101 |   * 🟠 Style B: `classAdd(me(), 'red')`
102 | * 🌐 Global conveniences help you write less code.
103 |   * `globalsAdd()` will automatically warn you of any clobbering issues!
104 |   * 💀🩸 If you want no conveniences, or are a masochist, delete `globalsAdd()`
105 |     * 🟢 `me().classAdd('red')` becomes `surreal.me().classAdd('red')`
106 |     * 🟠 `classAdd(me(), 'red')` becomes `surreal.classAdd(surreal.me(), 'red')`
107 | 
108 | See: [Quick Start](#quick-start) and [Reference](#reference) and [No Surreal Needed](#no-surreal)
109 | 
110 | ## <a name="quick-start"></a>⚡ Quick Start
111 | 
112 | * Add a class
113 |   * `me().classAdd('red')`
114 |   * `any("button").classAdd('red')`
115 | * Events
116 |   * `me().on("click", ev => me(ev).fadeOut() )`
117 |   * `any('button').on('click', ev => { me(ev).styles('color: red') })`
118 | * Run functions over elements.
119 |   * `any('button').run(_ => { alert(_) })`
120 | * Styles / CSS
121 |   * `me().styles('color: red')`
122 |   * `me().styles({ 'color':'red', 'background':'blue' })`
123 | * Attributes
124 |   * `me().attribute('active', true)`
125 | 
126 | <a name="timelines"></a>
127 | #### Timeline animations without any libraries.
128 | ```html
129 | <div>I change color every second.
130 |   <script>
131 |     // On click, animate something new every second.
132 |     me().on("click", async ev => {
133 |       let el = me(ev) // Save target because async will lose it.
134 |       me(el).styles({ "transition": "background 1s" })
135 |       await sleep(1000)
136 |       me(el).styles({ "background": "red" })
137 |       await sleep(1000)
138 |       me(el).styles({ "background": "green" })
139 |       await sleep(1000)
140 |       me(el).styles({ "background": "blue" })
141 |       await sleep(1000)
142 |       me(el).styles({ "background": "none" })
143 |       await sleep(1000)
144 |       me(el).remove()
145 |     })
146 |   </script>
147 | </div>
148 | ```
149 | ```html
150 | <div>I fade out and remove myself.
151 |   <script>me().on("click", ev => { me(ev).fadeOut() })</script>
152 | </div>
153 | ```
154 | ```html
155 | <div>Change color every second.
156 |   <script>
157 |     // Run immediately.
158 |     (async (e = me()) => {
159 |       me(e).styles({ "transition": "background 1s" })
160 |       await sleep(1000)
161 |       me(e).styles({ "background": "red" })
162 |       await sleep(1000)
163 |       me(e).styles({ "background": "green" })
164 |       await sleep(1000)
165 |       me(e).styles({ "background": "blue" })
166 |       await sleep(1000)
167 |       me(e).styles({ "background": "none" })
168 |       await sleep(1000)
169 |       me(e).remove()
170 |     })()
171 |   </script>
172 | </div>
173 | ```
174 | ```html
175 | <script>
176 |   // Run immediately, for every <button> globally!
177 |   (async () => {
178 |     any("button").fadeOut()
179 |   })()
180 | </script>
181 | ```
182 | #### Array methods
183 | ```js
184 | any('button')?.forEach(...)
185 | any('button')?.map(...)
186 | ```
187 | 
188 | ## <a name="reference"></a>👁️ Functions
189 | Looking for [DOM Selectors](#selectors)?
190 | Looking for stuff [we recommend doing in vanilla JS](#no-surreal)?
191 | ### 🧭 Legend
192 | * 🔗 Chainable off `me()` and `any()`
193 | * 🌐 Global shortcut.
194 | * 🔥 Runnable example.
195 | * 🔌 Built-in Plugin
196 | ### 👁️ At a glance
197 | 
198 | * 🔗 `run`
199 |   * It's `forEach` but less wordy and works on single elements, too!
200 |   * 🔥 `me().run(e => { alert(e) })`
201 |   * 🔥 `any('button').run(e => { alert(e) })`
202 | * 🔗 `remove`
203 |   * 🔥 `me().remove()`
204 |   * 🔥 `any('button').remove()`
205 | * 🔗 `classAdd` 🌗 `class_add` 🌗 `addClass` 🌗 `add_class`
206 |   * 🔥 `me().classAdd('active')`
207 |   * Leading `.` is **optional**
208 |     * Same thing: `me().classAdd('active')` 🌗 `me().classAdd('.active')`
209 | * 🔗 `classRemove` 🌗 `class_remove` 🌗 `removeClass` 🌗 `remove_class`
210 |   * 🔥 `me().classRemove('active')`
211 | * 🔗 `classToggle` 🌗 `class_toggle` 🌗 `toggleClass` 🌗 `toggle_class`
212 |   * 🔥 `me().classToggle('active')`
213 | * 🔗 `styles`
214 |   * 🔥 `me().styles('color: red')` Add style.
215 |   * 🔥 `me().styles({ 'color':'red', 'background':'blue' })` Add multiple styles.
216 |   * 🔥 `me().styles({ 'background':null })` Remove style.
217 | * 🔗 `attribute` 🌗 `attributes` 🌗 `attr`
218 |   * Get: 🔥 `me().attribute('data-x')`
219 |     * For single elements.
220 |     * For many elements, wrap it in: `any(...).run(...)` or `any(...).forEach(...)`
221 |   * Set: 🔥`me().attribute('data-x', true)`
222 |   * Set multiple: 🔥 `me().attribute({ 'data-x':'yes', 'data-y':'no' })`
223 |   * Remove: 🔥 `me().attribute('data-x', null)`
224 |   * Remove multiple: 🔥 `me().attribute({ 'data-x': null, 'data-y':null })`
225 | * 🔗 `send` 🌗 `trigger`
226 |   * 🔥 `me().send('change')`
227 |   * 🔥 `me().send('change', {'data':'thing'})`
228 |   * Wraps `dispatchEvent`
229 | * 🔗 `on`
230 |   * 🔥 `me().on('click', ev => { me(ev).styles('background', 'red') })`
231 |   * Wraps `addEventListener`
232 | * 🔗 `off`
233 |   * 🔥 `me().off('click', fn)`
234 |   * Wraps `removeEventListener`
235 | * 🔗 `offAll`
236 |   * 🔥 `me().offAll()`
237 | * 🔗 `disable`
238 |   * 🔥 `me().disable()`
239 |   * Easy alternative to `off()`. Disables click, key, submit events.
240 | * 🔗 `enable`
241 |   * 🔥 `me().enable()`
242 |   * Opposite of `disable()`
243 | * 🌐 `createElement` 🌗 `create_element`
244 |   * 🔥 `e_new = createElement("div"); me().prepend(e_new)`
245 |   * Alias of [document.createElement](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement)
246 | * 🌐 `sleep`
247 |   * 🔥 `await sleep(1000, ev => { alert(ev) })`
248 |   * `async` version of `setTimeout`
249 |   * Wonderful for animation timelines.
250 | * 🌐 `halt`
251 |   * 🔥 `halt(event)`
252 |   * When recieving an event, stop propagation, and prevent default actions (such as form submit).
253 |   * Wrapper for [stopPropagation](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation) and [preventDefault](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault)
254 | * 🌐 `tick`
255 |   * 🔥 `await tick()`
256 |   * `await` version of `rAF` / `requestAnimationFrame`.
257 |   * Waits for 1 frame (browser paint).
258 |   * Useful to guarantee CSS properties are applied, and events have propagated.
259 | * 🌐 `rAF`
260 |   * 🔥 `rAF(e => { return e })`
261 |   * Calls after 1 frame (browser paint). Alias of [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame)
262 |   * Useful to guarantee CSS properties are applied, and events have propagated.
263 | * 🌐 `rIC`
264 |   * 🔥 `rIC(e => { return e })`
265 |   * Calls when Javascript is idle. Alias of [requestIdleCallback](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback)
266 | * 🌐 `onloadAdd` 🌗 `onload_add` 🌗 `addOnload` 🌗 `add_onload`
267 |   * 🔥 `onloadAdd(_ => { alert("loaded!"); })`
268 |   * 🔥 `<script>let e = me(); onloadAdd(_ => { me(e).on("click", ev => { alert("clicked") }) })</script>`
269 |   * Execute after the DOM is ready. Similar to jquery `ready()`
270 |   * Add to `window.onload` while preventing overwrites of `window.onload` and predictable loading!
271 |   * Alternatives:
272 |     * Skip missing elements using `?.` example: `me("video")?.requestFullscreen()`
273 |     * Place `<script>` after the loaded element.
274 |       * See `me('-')` / `me('prev')`
275 | * 🔌 `fadeOut`
276 |   * See below
277 | * 🔌 `fadeIn`
278 |   * See below
279 | 
280 | ### <a name="plugin-included"></a>🔌 Built-in Plugins
281 | 
282 | ### Effects
283 | Build effects with `me().styles({...})` with timelines using [CSS transitioned `await` or callbacks](#timelines).
284 | 
285 | Common effects included:
286 | 
287 | * 🔗 `fadeOut` 🌗 `fade_out`
288 |   * Fade out and remove element.
289 |   * Keep element with `remove=false`.
290 |   * 🔥 `me().fadeOut()`
291 |   * 🔥 `me().fadeOut(ev => { alert("Faded out!") }, 3000)` Over 3 seconds then call function.
292 | 
293 | * 🔗 `fadeIn` 🌗 `fade_in`
294 |   * Fade in existing element which has `opacity: 0`
295 |   * 🔥 `me().fadeIn()`
296 |   * 🔥 `me().fadeIn(ev => { alert("Faded in!") }, 3000)` Over 3 seconds then call function.
297 | 
298 | 
299 | ## <a name="no-surreal"></a>⚪ No Surreal Needed
300 | 
301 | More often than not, Vanilla JS is the easiest way!
302 | 
303 | Logging
304 | * 🔥 `console.log()` `console.warn()` `console.error()`
305 | * Event logging: 🔥 `monitorEvents(me())` See: [Chrome Blog](https://developer.chrome.com/blog/quickly-monitor-events-from-the-console-panel-2/)
306 | 
307 | Benchmarking / Time It!
308 | * 🔥 `console.time('name')`
309 | * 🔥 `console.timeEnd('name')`
310 | 
311 | Text / HTML Content
312 | * 🔥 `me().textContent = "hello world"`
313 |   * XSS Safe! See: [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
314 | * 🔥 `me().innerHTML = "<p>hello world</p>"`
315 | * 🔥 `me().innerText = "hello world"`
316 | 
317 | Children
318 | * 🔥 `me().children`
319 | * 🔥 `me().children.hidden = true`
320 | 
321 | Append / Prepend elements.
322 | * 🔥 `me().prepend(new_element)`
323 | * 🔥 `me().appendChild(new_element)`
324 | * 🔥 `me().insertBefore(element, other_element.firstChild)`
325 | * 🔥 `me().insertAdjacentHTML("beforebegin", new_element)`
326 | 
327 | AJAX (replace jQuery `ajax()`)
328 | * Use [htmx](https://htmx.org/) or [htmz](https://leanrada.com/htmz/) or [fetch()](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or [XMLHttpRequest()](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest)
329 | * Example using `fetch()`
330 | ```js
331 | me().on("click", async event => {
332 |   let e = me(event)
333 |   // EXAMPLE 1: Hit an endpoint.
334 |   if((await fetch("/webhook")).ok) console.log("Did the thing.")
335 |   // EXAMPLE 2: Get content and replace me()
336 |   try {
337 |     let response = await fetch('/endpoint')
338 |     if (response.ok) e.innerHTML = await response.text()
339 |     else console.warn('fetch(): Bad response')
340 |   }
341 |   catch (error) { console.warn(`fetch(): ${error}`) }
342 | })
343 | ```
344 | * Example using `XMLHttpRequest()`
345 | ```js
346 | me().on("click", async event => {
347 |   let e = me(event)
348 |   // EXAMPLE 1: Hit an endpoint.
349 |   var xhr = new XMLHttpRequest()
350 |   xhr.open("GET", "/webhook")
351 |   xhr.send()
352 |   // EXAMPLE 2: Get content and replace me()
353 |   var xhr = new XMLHttpRequest()
354 |   xhr.open("GET", "/endpoint")
355 |   xhr.onreadystatechange = () => {
356 |     if (xhr.readyState == 4 && xhr.status >= 200 && xhr.status < 300) e.innerHTML = xhr.responseText
357 |   }
358 |   xhr.send()
359 | })
360 | ```
361 | 
362 |  ## 💎 Conventions & Tips
363 | 
364 | * Many ideas can be done in HTML / CSS (ex: dropdowns)
365 | * `_` = for temporary or unused variables. Keep it short and sweet!
366 | * `e`, `el`, `elt` = element
367 | * `e`, `ev`, `evt` = event
368 | * `f`, `fn` = function
369 | 
370 | #### Scope functions and variables inside `<script>`
371 |   * ⭐ Use a block `{ let note = "hi"; function hey(text) { alert(text) }; me().on('click', ev => { hey(note) }) }`
372 |     * `let` and `function` is scoped within `{ }`
373 |   * ⭐ Use `me()`
374 |     *  `me().hey = (text) => { alert(text) }`
375 |     *  `me().on('click', (ev) => { me(ev).hey("hi") })`
376 |   * ⭐ Use an event `me().on('click', ev => { /* add and call function here */ })`
377 |   * Use an inline module: `<script type="module">`
378 |     * Note: `me()` in modules will not see `parentElement`, explicit selectors are required: `me(".mybutton")`
379 | 
380 | #### Select a void element like `<input type="text" />`
381 | * Use: `me('-')` or `me('prev')` or `me('previous')`
382 |   * 🔥 `<input type="text" /> <script>me('-').value = "hello"</script>`
383 |   * Inspired by the CSS "next sibling" combinator `+` but in reverse `-`
384 | * Or, use a relative start.
385 |   * 🔥 `<form> <input type="text" n1 /> <script>me('[n1]', me()).value = "hello"</script> </form>`
386 | 
387 | #### Ignore call chain when element is missing.
388 | * 🔥 `me("#i_dont_exist")?.classAdd('active')`
389 | * No warnings: 🔥 `me("#i_dont_exist", document, false)?.classAdd('active')`
390 | 
391 | ## <a name="plugins"></a>🔌 Your own plugin
392 | 
393 | Feel free to edit Surreal directly- but if you prefer, you can use plugins to effortlessly merge with new versions.
394 | 
395 | ```javascript
396 | function pluginHello(e) {
397 |   function hello(e, name="World") {
398 |     console.log(`Hello ${name} from ${e}`)
399 |     return e // Make chainable.
400 |   }
401 |   // Add sugar
402 |   e.hello = (name) => { return hello(e, name) }
403 | }
404 | 
405 | surreal.plugins.push(pluginHello)
406 | ```
407 | 
408 | Now use your function like: `me().hello("Internet")`
409 | 
410 | * See the included `pluginEffects` for a more comprehensive example.
411 | * Your functions are added globally by `globalsAdd()` If you do not want this, add it to the `restricted` list.
412 | * Refer to an existing function to see how to make yours work with 1 or many elements.
413 | 
414 | Make an [issue](https://github.com/gnat/surreal/issues) or [pull request](https://github.com/gnat/surreal/pulls) if you think people would like to use it! If it's useful enough we'll want it in core.
415 | 
416 | ## 🌘 Change Log
417 | 
418 | ### 1.3.4
419 | * New automated official NPM (<https://www.npmjs.com/package/@geenat/surreal>)
420 | * New automated test system.
421 | * This repo is actually **smaller** now because the github-only automations generate their own support files for testing and publishing.
422 | * Fixed warning about `document.plugins` https://github.com/gnat/surreal/issues/52
423 | 
424 | ## 📚️ Inspired by
425 | 
426 | * [jQuery](https://jquery.com/) for the chainable syntax we all love.
427 | * [Hyperscript](https://hyperscript.org) for Locality of Behavior and ergonomics.
428 | * [BlingBling.js](https://github.com/argyleink/blingblingjs) for modern minimalism.
429 | * [Bliss.js](https://blissfuljs.com/) for a focus on single elements and extensibility.
430 | * Shout out to [Umbrella](https://umbrellajs.com/), [Cash](https://github.com/fabiospampinato/cash), [Zepto](https://zeptojs.com/)
431 | 
432 | ### ⭐ Check out [awesome-surreal](https://github.com/gnat/awesome-surreal) for extra examples, plugins, and resources !
433 | 


--------------------------------------------------------------------------------