Skip to content
/ surreal Public
forked from gnat/surreal

🗿 Mini jQuery alternative. Dependency-free animations. Pairs with htmx. Locality of Behavior. Use one element or arrays transparently. Vanilla querySelector() but better!

gnat.github.io/surreal/showcase.html

License

MIT license
2 stars 26 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

davidwilde/surreal

BranchesTags
 
 

Repository files navigation

🗿 Surreal - mini jQuery alternative for vanilla JS with inline Locality of Behavior

cover (Art by shahabalizadeh)

Why does this exist?

For devs who love ergonomics! You may appreciate Surreal if:

  • You want to stay as close as possible to Vanilla JS.
  • Hate typing document.querySelector over.. and over..
  • Hate typing addEventListener over.. and over..
  • Really wish document.querySelectorAll had Array functions..
  • Really wish this would work in any inline <script> tag
  • Enjoyed using jQuery selector syntax.
  • Animations, timelines, tweens with no extra libraries.
  • Only 320 lines. No build step. No dependencies.
  • Pairs well with htmx
  • Want fewer layers, less complexity. Are aware of the cargo cult. ✈️

✨ What will this add to my vanilla javascript?

  • ⚡️ Locality of Behavior (LoB) Use me() inside <script>
    • Get an element without creating a unique name: No .class or #id needed!
    • this but better!
    • Want to use it in your CSS <style> tags, too? See our companion script
  • 🔗 Call chaining, jQuery style.
  • ♻️ Functions work seamlessly on one element or arrays of elements!
    • All functions can use: me(), any(), NodeList, HTMLElement (..or arrays of these!)
    • Get 1 element: me()
    • ..or many elements: any()
    • me() or any() can chain with any Surreal function.
      • me() can be used directly as a single element (like querySelector() or $())
      • any() can use: for / forEach / filter / map (like querySelectorAll() or $())
  • 🌗 No forced style: class_add is just an alias of classAdd
    • Use camelCase (Javascript) or snake_case (Python, Rust, PHP, Ruby, SQL, CSS).

🤔 Why use me() / any() instead of $()

  • 💡 We solve the classic jQuery code bloat problem: Am I getting 1 element or an array of elements?
    • me() is guaranteed to return 1 element (or first found, or none).
    • any() is guaranteed to return an array (or empty array).
    • No more checks! Write less code! Bonus: Code reads more like self-documenting english.

👁️ How does it look?

Do surreal things with Locality of Behavior like:

<label for="file-input" >
  <div class="uploader"></div>
  <script>
    me().on("dragover", ev => { halt(ev); me(ev).classAdd('.hover'); console.log("Files in drop zone.") })
    me().on("dragleave", ev => { halt(ev); me(ev).classAdd('.hover'); console.log("Files left drop zone.") })
    me().on("drop", ev => { halt(ev); me(ev).classRemove('.hover').classAdd('.loading'); me('#file-input').attribute('files', ev.dataTransfer.files); me('#form').trigger('change') })
  </script>
</label>

See the Live Example! Then view source.

🎁 Installation

Surreal is only 320 lines. No build step. No dependencies.

  • Download Surreal and drag surreal.js into a directory of your project.
  • Add <script src="surreal.js"></script> to your <head>.

📚️ Inspired by

  • jQuery for the chainable syntax we all love.
  • BlingBling.js for modern minimalism.
  • Bliss.js for a focus on single elements and extensibility.
  • Hyperscript for Locality of Behavior and awesome ergonomics.
  • Shout out to Umbrella, Cash, Zepto- Not quite as ergonomic. Requires build step to extend.

➡️ Usage Overview

🔍️ DOM Selection

  • Select one element: me(SELECTOR)
    • SELECTOR can be any of:
      • CSS selector: ".button", "#header", "h1", "body > .block"
      • Variables: body, elt, some_element
      • Events: the event.target will be used.
      • Surreal selectors: me(),any()
      • Adding the , start= parameter provides a starting point to select from, default is document.
        • Example: any('button', start='header').classAdd('red')
    • me() Get current element for Locality of Behavior in <script> without an explicit .class or #id
    • me("body") Gets <body>
    • me(".button") Gets the first <div class="button">...</div>. To get all of them use any()
  • Select one or more elements as an array: any(SELECTOR)
    • Similar to me() but guaranteed to return an array (or empty array).
    • any(".button") Gets all matching elements, example: <div class="button">...</div>
    • Feel free to convert between arrays of elements and single elements: any(me()), me(any(".something"))

⚙️ DOM Functions

  • ♻️ All functions work on single elements or arrays of elements.
  • 🔗 Start a chain using me() and any()
    • 🟢 Style A - 🔗 Chain style
      • me().classAdd('red') (⭐ RECOMMENDED)
        • Alternative, no conveniences: $.me().classAdd('red')
    • 🟠 Style B
      • classAdd(me(), 'red')
        • Alternative, no conveniences: $.classAdd($.me(), 'red')
  • 🌐 Global conveniences help you write less code.
    • globalsAdd() will automatically warn about any clobbering issues. If you prefer no conveniences, just delete globalsAdd()

See: Quick Start and Reference and No Surreal Needed

🔥 Quick Start

  • Add a class
    • me().classAdd('red')
    • any("button").classAdd('red')
  • Events
    • me().on("click", ev => me(ev).fade_out() )
    • on(any('button'), 'click', ev => { me(ev).styles('color: red') })
  • Run functions over elements.
    • any('button').run(_ => { alert(_) })
  • Styles / CSS
    • me().styles('color: red')
    • me().styles({ 'color':'red', 'background':'blue' })
  • Attributes
    • me().attribute('active', true)

Timeline animations without any libraries.

<div>I change color every second.
  <script>
    // Locality of Behavior
    me().on("click", async ev => {
      me(ev).styles({ "transition": "background 1s" })
      await sleep(1000)
      me(ev).styles({ "background": "red" })
      await sleep(1000)
      me(ev).styles({ "background": "green" })
      await sleep(1000)
      me(ev).styles({ "background": "blue" })
      await sleep(1000)
      me(ev).styles({ "background": "none" })
      await sleep(1000)
      me(ev).remove()
    })
  </script>
</div>
<div>I fade out and remove myself.
  <script>
    // Keepin it simple! Locality of Behavior.
    me().on("click", ev => { me(ev).fadeOut() })
  </script>
</div>
<div>I change color every second.
<script>
  // Run on load.
  (async (el = me())=>{
    me(el).styles({ "transition": "background 1s" })
    await sleep(1000)
    me(el).styles({ "background": "red" })
    await sleep(1000)
    me(el).styles({ "background": "green" })
    await sleep(1000)
    me(el).styles({ "background": "blue" })
    await sleep(1000)
    me(el).styles({ "background": "none" })
    await sleep(1000)
    me(el).remove()
  })()
</script>
</div>
<script>
  // Keepin it simple! Globally!
  (async ()=>{
    any("button").fadeOut()
  })()
</script>

Array methods

any('button')?.forEach(...)
any('button')?.map(...)

👁️ Function Reference

Looking for DOM Selectors?

🧭 Legend

  • 🔗 Chainable off me() and any()
  • 🌐 Global convenience helper.
  • 🏁 Runnable example.
  • 🔌 Built-in Plugin

👁️ At a glance

  • 🔗 run
    • It's forEach but less wordy and works on single elements, too!
    • 🏁 me().run(el => { alert(el) })
    • 🏁 any('button').run(el => { alert(el) })
  • 🔗 remove
    • 🏁 me().remove()
    • 🏁 any('button').remove()
  • 🔗 classAdd or class_add
    • 🏁 me().classAdd('active')
    • Leading . is optional for all class functions, to prevent typical syntax errors with me() and any().
      • me().classAdd('active') and me().classAdd('.active') are equivalent.
  • 🔗 classRemove or class_remove
    • 🏁 me().classRemove('active')
  • 🔗 classToggle or class_toggle
    • 🏁 me().classToggle('active')
  • 🔗 styles
    • 🏁 me().styles('color: red') Add style.
    • 🏁 me().styles({ 'color':'red', 'background':'blue' }) Add multiple styles.
    • 🏁 me().styles({ 'background':null }) Remove style.
  • 🔗 attribute or attributes or attr
    • Get: 🏁 me().attribute('data-x')
      • Get is only for single elements. For many, wrap the call in any(...).run(...) or any(...).forEach(...).
    • Set: 🏁me().attribute('data-x', true)
    • Set multiple: 🏁 me().attribute({ 'data-x':'yes', 'data-y':'no' })
    • Remove: 🏁 me().attribute('data-x', null)
    • Remove multiple: 🏁 me().attribute({ 'data-x': null, 'data-y':null })
  • 🔗 trigger
    • 🏁 me().trigger('hello')
    • Wraps dispatchEvent
  • 🔗 on
    • 🏁 me().on('click', ev => { me(ev).styles('background', 'red') })
    • Wraps addEventListener
  • 🔗 off
    • 🏁 me().remove('click')
    • Wraps removeEventListener
  • 🔗 offAll
    • 🏁 me().offAll()
  • 🌐 sleep
    • 🏁 await sleep(1000, ev => { alert(ev) })
    • async version of setTimeout
    • Wonderful for animation timelines.
  • 🌐 tick
    • 🏁 await tick()
    • await version of rAF / requestAnimationFrame.
    • Animation tick. Waits 1 frame.
    • Great if you need to wait for events to propagate.
  • 🌐 rAF
    • 🏁 rAF(e => { return e })
    • Animation tick. Fires when 1 frame has passed. Alias of requestAnimationFrame
    • Great if you need to wait for events to propagate.
  • 🌐 rIC
    • 🏁 rIC(e => { return e })
    • Great time to compute. Fires function when JS is idle. Alias of requestIdleCallback
  • 🌐 halt
    • 🏁 halt(event)
    • Great to prevent default browser behavior: such as displaying an image vs letting JS handle it.
    • Wrapper for preventDefault
  • 🌐 createElement or create_element
    • 🏁 el_new = createElement("div"); me().prepend(el_new)
    • Alias of document.createElement
  • 🌐 onloadAdd or onload_add
    • 🏁 onloadAdd(_ => { alert("loaded!"); })
    • Execute after the DOM is ready. Similar to jquery ready()
    • Queues functions onto window.onload
    • Why? So you don't overwrite window.onload, also predictable sequential loading!

🔌 Built-in Plugins

Effects

Build your own effects with me().styles({...}) then timelining with CSS transitions using await or callbacks. We ship some common effects:

  • 🔗 fadeOut or fade_out

    • Fade out and remove element.
    • Keep element with remove=false.
    • 🏁 me().fadeOut()
    • 🏁 me().fadeOut(ev => { alert("Faded out!") }, 3000) Over 3 seconds then call function.

  • 🔗 fadeIn or fade_in

    • Fade in existing element which has opacity: 0
    • 🏁 me().fadeIn()
    • 🏁 me().fadeIn(ev => { alert("Faded in!") }, 3000) Over 3 seconds then call function.

🔮 No Surreal Needed

More often than not, Vanilla JS is the easiest way!

Logging

  • 🌐 console.log() console.warn() console.error()
  • Event logging: 🏁 monitorEvents(me()) See: Chrome Blog

Benchmarking / Time It!

  • 🏁 console.time('name')
  • 🏁 console.timeEnd('name')

Text / HTML Content

  • 🏁 me().textContent = "hello world"
    • XSS Safe! See: MDN
  • 🏁 me().innerHTML = "<p>hello world</p>"
  • 🏁 me().innerText = "hello world"

Children

  • 🏁 me().children
  • 🏁 me().children.hidden = true

Append / Prepend elements.

  • 🏁 me().prepend(el_new)
  • 🏁 me().appendChild(el_new)
  • 🏁 me().insertBefore(el_new, el.firstChild)
  • 🏁 me().insertAdjacentHTML("beforebegin", el_new)

💎 Conventions & Tips

  • _ = for temporary or unused variables. Keep it short and sweet!
  • e, el, elt = element
  • e, ev, evt = event
  • f, fn = function
  • Developer ergonomics and simplicity wins.
  • Find the layer where the change needs to touch the least places.
  • Animations are done with me().styles(...) with CSS transitions. Use await sleep(...) for timelining.
  • Dropdowns can be done in pure HTML / CSS.

🔌 Extending Surreal

Surreal is tiny enough to be modified for a particular use-case; but there is a system if you prefer to effortlessly merge with new versions.

  1. Add your function to Surreal
var $thing = {
  test(e, name) {
    console.log(`Hello ${name} from ${e}`)
    return e
  }
}
$ = {...$, ...$thing}
  1. Is your function chainable? Add it to Surreal sugar()
$.sugars['test'] = (name) => { return $.test($._e, name) }
  1. Your function will automatically will be added globally by globalsAdd() If you do not want this (ex: Naming clash), add it to the restricted list in globalsAdd()

Should your function work with both single elements and arrays of elements? Refer to an existing function to see how to make this work.

Make an issue or pull request if you think people would like to use it! If it's useful enough we may want it in the core!

🌘 Future

About

🗿 Mini jQuery alternative. Dependency-free animations. Pairs with htmx. Locality of Behavior. Use one element or arrays transparently. Vanilla querySelector() but better!

gnat.github.io/surreal/showcase.html

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 78.3%
  • HTML 15.4%
  • CSS 6.3%