@heartml/streetcar-elements 1.0.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-2026 Jared White
+
+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,48 @@
+# Ride The Streetcar 🚋
+## Custom Elements (by the ❤️ Heartml project)
+
+This is the client-side component of Ride The Streetcar. You will also need to install a backend (alternatively you can write your own). The [Ruby backend is here](https://codeberg.org/heartml/ride_the_streetcar), or the [JavaScript backend is here](https://codeberg.org/heartml/ride-the-streetcar-js).
+
+> [!NOTE]
+> A work in progress! Docs coming upon release!
+
+## 1:1 API Completion
+
+- [x] `document.querySelector` : `<sc-query-selector>`
+- [x] `document.querySelectorAll` : `<sc-query-selector all>`
+- [x] `innerHTML` : `<sc-inner-html>`
+- [x] `outerHTML` : `<sc-outer-html>`
+- [x] `textContent` : `<sc-text-content>`
+- [x] `classList.toggle` : `<sc-class-list toggle>`
+- [x] `classList.{add,remove}` : `<sc-class-list {add,remove}="..."`
+- [x] `console.{debug,log,warn,error}` : `<sc-console {debug,log,warn,error}="...">`
+- [x] `toggleAttribute` : `<sc-toggle-attribute>`
+- [x] `setAttribute` : `<sc-set-attribute>`
+- [x] `removeAttribute` : `<sc-remove-attribute>`
+- [x] `insertAdjacentElement` : `<sc-insert where="...">`
+  - also `<sc-before>`, `<sc-prepend>`, `<sc-append>`, `<sc-after>` 
+- [x] `remove` (element) : `<sc-remove>`
+- [x] `.{property} =` : `<sc-set-property>`
+- [x] `.{method}(...)` (via `apply`) : `<sc-apply>`
+- [x] `.style.{...} =` : `<sc-set-style>`
+- [x] `location.href =` (or custom visit/redirect strategies) : `<sc-navigate>`
+- [x] `event.dispatch` (support native or custom events with payloads) : `<sc-dispatch-event>`
+- [x] `setTimeout` (wrap 1 or more statements in here to delay execution) : `<sc-set-timeout>`
+
+----
+
+## Testing
+
+Run `npm run test` to run the test suite. It's built with Node test runner, Puppeteer, and a Node static site.
+
+## Contributing
+
+1. Fork it (https://codeberg.org/heartml/streetcar-elements/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@heartml/streetcar-elements",
+  "version": "1.0.0",
+  "description": "Ride The Streetcar is a protocol of sorts built out of HTML and custom elements. Drive surgical state changes to your frontend DOM and JavaScript objects…from any backend.",
+  "main": "src/streetcar-elements.js",
+  "type": "module",
+  "scripts": {
+    "test": "node --test --test-reporter node-test-reporter '**/*.test.js'",
+    "test:watch": "node --test --test-reporter node-test-reporter --watch '**/*.test.js'"
+  },
+  "exports": {
+    ".": "./src/streetcar-elements.js",
+    "./src/*": "./src/*.js"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/heartml/streetcar-elements"
+  },
+  "keywords": [],
+  "author": "Jared White <jared@whitefusion.studio>",
+  "license": "MIT",
+  "prettier": {
+    "printWidth": 100,
+    "semi": false
+  },
+  "devDependencies": {
+    "node-test-reporter": "^1.2.0",
+    "puppeteer": "^24.17.1"
+  }
+}

package/src/htmx-extension.js

@@ -0,0 +1,30 @@
+// @ts-check
+
+/**
+ * @typedef {import('./streetcar-elements.js').StreetcarLineElement} StreetcarLineElement
+ */
+
+// @ts-ignore
+import htmx from "htmx.org"
+
+htmx.defineExtension("streetcar", {
+  onEvent: (name, event) => {
+    if (name !== "htmx:beforeOnLoad") return
+
+    /** @type {HTMLElement} */
+    const elt = event.detail.elt
+    if (elt.getAttribute("hx-swap") === "streetcar" && !elt.hasAttribute("hx-push-url")) {
+      elt.setAttribute("hx-push-url", "false")
+    }
+  },
+  isInlineSwap: (swapStyle) => swapStyle === "streetcar",
+  handleSwap: (swapStyle, _target, /** @type {Element} */ fragment) => {
+    /** @type {StreetcarLineElement} */
+    let line
+    if (swapStyle === "streetcar" && (line = fragment.querySelector("sc-line"))) {
+      document.body.append(line)
+      line.operate()
+      return true
+    }
+  },
+})

package/src/streetcar-elements.js

@@ -0,0 +1,457 @@
+// @ts-check
+
+export class StreetcarLineElement extends HTMLElement {
+  static {
+    customElements.define("sc-line", this)
+  }
+
+  constructor() {
+    super()
+
+    this.style.display = "none" // don't paint when added to DOM
+  }
+
+  /** Performs a set of one or more DOM operations and then removes itself from the DOM */
+  operate() {
+    const operationsLoop = () => {
+      for (const statement of /** @type {StreetcarStatementElement[]} */ ([...this.children])) {
+        statement.operate()
+      }
+    }
+
+    this.shouldTransition ? document.startViewTransition(() => operationsLoop()) : operationsLoop()
+    this.remove()
+  }
+
+  get shouldTransition() {
+    return this.hasAttribute("start-transition") && document.startViewTransition
+  }
+}
+
+export class StreetcarStatementElement extends HTMLElement {
+  /** Performs a specific DOM operation according to this statement */
+  operate() {
+    throw "Override this in statement subclass"
+  }
+
+  /**
+   * If current statement is wrapped in a query, return that element
+   *
+   * @returns {StreetcarQuerySelectorElement} */
+  get queryElement() {
+    return this.closest("sc-query-selector")
+  }
+}
+
+export class StreetcarQuerySelectorElement extends StreetcarStatementElement {
+  static {
+    customElements.define("sc-query-selector", this)
+  }
+
+  constructor() {
+    super()
+
+    /** @type {Element} - the element which was matched via the selectors */
+    this.resolvedElement = null
+  }
+
+  operate() {
+    let selectors = this.selectors
+    if (selectors.startsWith("--")) {
+      const line = this.closest("sc-line")
+      selectors = window.getComputedStyle(line).getPropertyValue(selectors).slice(1, -1)
+    }
+
+    const resolvedElements = this.hasAttribute("all")
+      ? document.querySelectorAll(selectors)
+      : [document.querySelector(selectors)]
+    if (!resolvedElements[0]) {
+      console.warn(
+        "[Streetcar] 'querySelector' failed, no element(s) found for selectors",
+        selectors,
+      )
+      return
+    }
+
+    for (const rel of resolvedElements) {
+      this.resolvedElement = rel
+      for (const statement of /** @type {StreetcarStatementElement[]} */ ([...this.children])) {
+        statement.operate()
+      }
+    }
+  }
+
+  get selectors() {
+    return this.getAttribute("selectors")
+  }
+}
+
+export class StreetcarInnerHTMLElement extends StreetcarStatementElement {
+  static {
+    customElements.define("sc-inner-html", this)
+  }
+
+  operate() {
+    const resolvedElement = this.queryElement.resolvedElement
+
+    /** @type {HTMLTemplateElement} */
+    const tmpl = this.querySelector(":scope > template")
+
+    resolvedElement.replaceChildren(tmpl.content)
+  }
+}
+
+export class StreetcarTextContentElement extends StreetcarStatementElement {
+  static {
+    customElements.define("sc-text-content", this)
+  }
+
+  operate() {
+    const resolvedElement = this.queryElement.resolvedElement
+
+    /** @type {HTMLTemplateElement} */
+    const tmpl = this.querySelector(":scope > template")
+
+    resolvedElement.textContent = tmpl.textContent
+  }
+}
+
+export class StreetcarOuterHTMLElement extends StreetcarStatementElement {
+  static {
+    customElements.define("sc-outer-html", this)
+  }
+
+  operate() {
+    const queryElement = this.queryElement
+
+    /** @type {HTMLTemplateElement} */
+    const tmpl = this.querySelector(":scope > template")
+    const newElement = tmpl.content.firstElementChild
+
+    queryElement.resolvedElement.replaceWith(tmpl.content)
+    queryElement.resolvedElement = newElement
+  }
+}
+
+export class StreetcarConsoleElement extends StreetcarStatementElement {
+  static {
+    customElements.define("sc-console", this)
+  }
+
+  operate() {
+    let debugMessage, logMessage, warnMessage, errorMessage
+
+    if ((debugMessage = this.getAttribute("debug"))) {
+      console.debug(debugMessage)
+    }
+
+    if ((logMessage = this.getAttribute("log"))) {
+      console.log(logMessage)
+    }
+
+    if ((warnMessage = this.getAttribute("warn"))) {
+      console.warn(warnMessage)
+    }
+
+    if ((errorMessage = this.getAttribute("error"))) {
+      console.error(errorMessage)
+    }
+  }
+}
+
+export class StreetcarClassListElement extends StreetcarStatementElement {
+  static {
+    customElements.define("sc-class-list", this)
+  }
+
+  operate() {
+    if (this.hasAttribute("toggle")) {
+      this.operateToggle()
+      return
+    }
+
+    const classNames = (this.getAttribute("add") || this.getAttribute("remove"))
+      .split(",")
+      .map((str) => str.trim())
+    const resolvedElement = this.queryElement.resolvedElement
+
+    if (this.hasAttribute("add")) {
+      resolvedElement.classList.add(...classNames)
+    } else {
+      resolvedElement.classList.remove(...classNames)
+    }
+  }
+
+  operateToggle() {
+    const className = this.getAttribute("toggle")
+    const shouldForce = this.getAttribute("force")
+    const resolvedElement = this.queryElement.resolvedElement
+
+    if (shouldForce) {
+      resolvedElement.classList.toggle(className, shouldForce === "true")
+    } else {
+      resolvedElement.classList.toggle(className)
+    }
+  }
+}
+
+export class StreetcarSetAttributeElement extends StreetcarStatementElement {
+  static {
+    customElements.define("sc-set-attribute", this)
+  }
+
+  operate() {
+    const name = this.getAttribute("name")
+    const value = this.getAttribute("value") || ""
+
+    this.queryElement.resolvedElement.setAttribute(name, value)
+  }
+}
+
+export class StreetcarRemoveAttributeElement extends StreetcarStatementElement {
+  static {
+    customElements.define("sc-remove-attribute", this)
+  }
+
+  operate() {
+    const name = this.getAttribute("name")
+
+    this.queryElement.resolvedElement.removeAttribute(name)
+  }
+}
+
+export class StreetcarToggleAttributeElement extends StreetcarStatementElement {
+  static {
+    customElements.define("sc-toggle-attribute", this)
+  }
+
+  operate() {
+    const name = this.getAttribute("name")
+    const shouldForce = this.getAttribute("force")
+    const resolvedElement = this.queryElement.resolvedElement
+
+    if (shouldForce) {
+      resolvedElement.toggleAttribute(name, shouldForce === "true")
+    } else {
+      resolvedElement.toggleAttribute(name)
+    }
+  }
+}
+
+export class StreetcarInsertElement extends StreetcarStatementElement {
+  static { customElements.define("sc-insert", this) } // prettier-ignore
+  operate() {
+    const resolvedElement = this.queryElement.resolvedElement
+
+    /** @type {HTMLTemplateElement} */
+    const tmpl = this.querySelector(":scope > template")
+
+    const position = this.where
+    switch (position) {
+      case "beforebegin":
+      case "afterbegin":
+      case "beforeend":
+      case "afterend":
+        resolvedElement.insertAdjacentElement(position, tmpl.content.firstElementChild)
+    }
+  }
+
+  get where() {
+    return this.getAttribute("where")
+  }
+}
+export class StreetcarBeforeElement extends StreetcarInsertElement {
+  static { customElements.define("sc-before", this) } // prettier-ignore
+  get where() { return "beforebegin" } // prettier-ignore
+}
+export class StreetcarPrependElement extends StreetcarInsertElement {
+  static { customElements.define("sc-prepend", this) } // prettier-ignore
+  get where() { return "afterbegin" } // prettier-ignore
+}
+export class StreetcarAppendElement extends StreetcarInsertElement {
+  static { customElements.define("sc-append", this) } // prettier-ignore
+  get where() { return "beforeend" } // prettier-ignore
+}
+export class StreetcarAfterElement extends StreetcarInsertElement {
+  static { customElements.define("sc-after", this) } // prettier-ignore
+  get where() { return "afterend" } // prettier-ignore
+}
+
+export class StreetcarRemoveElement extends StreetcarStatementElement {
+  static { customElements.define("sc-remove", this) } // prettier-ignore
+  operate() {
+    this.queryElement.resolvedElement.remove()
+  }
+}
+
+export class StreetcarApplyElement extends StreetcarStatementElement {
+  static { customElements.define("sc-apply", this) } // prettier-ignore
+
+  get chainAttribute() {
+    return this.getAttribute("method")
+  }
+
+  operate() {
+    let receiver
+    let firstObjectInChain
+    const element = this.queryElement?.resolvedElement // null if outside of a query
+    const method = this.chainAttribute
+    let chain = method.split(".")
+    if (!element) {
+      receiver = chain[0]
+      chain = chain.slice(1)
+    }
+
+    switch (receiver) {
+      case "window":
+        firstObjectInChain = window
+        break
+      case "document":
+        firstObjectInChain = document
+        break
+      default:
+        firstObjectInChain = element
+    }
+    if (!firstObjectInChain) {
+      console.warn(`[Streetcar] unable to determine receiver for 'apply'`)
+    }
+
+    this.operateViaChain(firstObjectInChain, chain)
+  }
+
+  operateViaChain(firstObjectInChain, chain) {
+    /** @type {array} */
+    const args = JSON.parse(this.getAttribute("arguments") || "[]")
+    let lastObjectInChain = firstObjectInChain
+    const foundMethod = chain.reduce((lastTerm, nextTerm) => {
+      lastObjectInChain = lastTerm
+      return lastTerm[nextTerm] || {}
+    }, firstObjectInChain)
+
+    if (foundMethod instanceof Function) {
+      foundMethod.apply(lastObjectInChain, args)
+    } else {
+      console.warn(
+        `[Streetcar] 'apply' failed due to missing '${this.chainAttribute}' method for:`,
+        firstObjectInChain,
+      )
+    }
+  }
+}
+
+export class StreetcarSetPropertyElement extends StreetcarApplyElement {
+  static { customElements.define("sc-set-property", this) } // prettier-ignore
+
+  get chainAttribute() {
+    return this.getAttribute("name")
+  }
+
+  operateViaChain(firstObjectInChain, chain) {
+    let lastObjectInChain = firstObjectInChain
+    const chainBeforeProperty = chain.slice(0, -1)
+    const property = chain.at(-1)
+    const foundObject = chainBeforeProperty.reduce((lastTerm, nextTerm) => {
+      lastObjectInChain = lastTerm
+      return lastTerm[nextTerm] || {}
+    }, firstObjectInChain)
+
+    foundObject[property] = JSON.parse(this.getAttribute("value"))
+  }
+}
+
+export class StreetcarSetStyleElement extends StreetcarStatementElement {
+  static { customElements.define("sc-set-style", this) } // prettier-ignore
+
+  operate() {
+    const name = this.getAttribute("name")
+    const value = this.getAttribute("value")
+
+    this.queryElement.resolvedElement["style"][name] = value
+  }
+}
+
+export class StreetcarDispatchEventElement extends StreetcarStatementElement {
+  static { customElements.define("sc-dispatch-event", this) } // prettier-ignore
+
+  operate() {
+    const name = this.getAttribute("name")
+
+    /** @type {CustomEventInit} */
+    const eventOptions = {}
+    if (this.hasAttribute("bubbles")) eventOptions.bubbles = true
+    if (this.hasAttribute("cancelable")) eventOptions.cancelable = true
+    if (this.hasAttribute("composed")) eventOptions.composed = true
+    if (this.hasAttribute("detail")) eventOptions.detail = JSON.parse(this.getAttribute("detail"))
+    const isCustom = typeof eventOptions.detail !== "undefined"
+    let newEvent
+
+    if (isCustom) {
+      newEvent = new CustomEvent(name, eventOptions)
+    } else {
+      newEvent = new Event(name, eventOptions)
+    }
+
+    this.queryElement.resolvedElement.dispatchEvent(newEvent)
+  }
+}
+
+export class StreetcarNavigateElement extends StreetcarStatementElement {
+  static { customElements.define("sc-navigate", this) } // prettier-ignore
+
+  /**
+   * Applications can override this static function to provide their own
+   * framework-specific navigation strategy
+   *
+   * @param {string} url
+   */
+  static navigationStrategy(url) {
+    window.location.href = url
+  }
+
+  operate() {
+    const url = this.getAttribute("href")
+
+    this.constructor["navigationStrategy"](url)
+  }
+}
+
+export class StreetcarSetTimeoutElement extends StreetcarStatementElement {
+  static { customElements.define("sc-set-timeout", this) } // prettier-ignore
+
+  operate() {
+    const delay = parseInt(this.getAttribute("delay"), 10)
+
+    setTimeout(() => {
+      for (const statement of /** @type {StreetcarStatementElement[]} */ ([...this.children])) {
+        statement.operate()
+      }
+    }, delay)
+  }
+}
+
+// Singleton helper:
+const Streetcar = {
+  /**
+   * Parses an incoming HTML string and operates the first `<sc-line>` element found.
+   *
+   * @param {string} htmlText
+   */
+  run(htmlText) {
+    const doc = Document.parseHTMLUnsafe(htmlText)
+    this.runFragment(doc)
+  },
+
+  /**
+   * Operates the first `<sc-line>` element found in the fragment.
+   * 
+   * @param {Document|DocumentFragment} fragment
+   */
+  runFragment(fragment) {
+    /** @type {StreetcarLineElement} */
+    const line = fragment.querySelector("sc-line")
+    document.body.append(line)
+    line.operate()
+  },
+}
+
+export default Streetcar