DOM helpers: clay-dom, clay-events and All

ClayJS ships three optional DOM satellites for writing compact, DOM-first scripts and inline handlers: clay-dom.js, clay-events.js, and all.js. Each loads from its own classic <script> tag and works with or without clay.js, in both edit mode and view mode.

Loading the satellites#

Load each satellite with a classic <script src="..."> tag using the same version prefix as clay.js. Never load them with type="module".

<script src="https://clayjs.com/v1/clay.js"></script>
<script src="https://clayjs.com/v1/clay-dom.js"></script>
<script src="https://clayjs.com/v1/clay-events.js"></script>
<script src="https://clayjs.com/v1/all.js"></script>

Each tag registers a readiness promise on window.clay.loaded:

If you call a satellite from an inline script immediately after its tag, await its readiness promise first (await clay.loaded.dom). If you use the offline build (clay.standalone.js), all three satellites are already bundled inside it, so omit the extra <script> tags.

clay-dom.js#

clay-dom.js adds relative lookup and manipulation helpers to Element.prototype and HTMLElement.prototype, plus content-filtering helpers on clay.dom.

Element prototype properties and methods#

• elem.nearest.NAME and elem.el.NAME: Getter proxies that search outward from elem for the nearest element matching [NAME], .NAME (an attribute or class named NAME). The search checks elem itself, then its descendants, previous siblings, next siblings, and finally parent and ancestor subtrees. Returns the found Element or null.
• elem.val.NAME: Getter and setter for the nearest [NAME], .NAME element. On <input>, <select>, and <textarea>, it reads or writes .value; on any other element, it calls getAttribute("NAME") or setAttribute("NAME", value). Setting is a no-op if nothing matches.
• elem.text.NAME: Getter and setter for innerText on the nearest [NAME], .NAME element. Setting is a no-op if nothing matches.
• elem.exec.NAME(): Finds the nearest [NAME], .NAME element, reads its NAME attribute as JavaScript code, and executes it with this bound to that element. Returns undefined when nothing matches or the attribute is empty.
• elem.cycleAttr(order = 1, setAttr, lookupAttr = setAttr): Collects all unique values of lookupAttr across the document, sorts them alphabetically, and sets setAttr on elem to the next (1) or previous (-1) value.
• elem.cycle(order = 1, attr): Finds all [attr] elements in the document, deduplicates them by textContent, sorts them with localeCompare, and replaces elem in the DOM with a cloneNode(true) copy of the next (1) or previous (-1) element.
• elem.show() and elem.hide(): show() sets elem.style.display = "" and hide() sets elem.style.display = "none". Both return elem.

<div class="card">
  <h3 class="title">Draft</h3>
  <button type="button" onclick="this.text.title = 'Published'">Publish</button>
  <button type="button" data-status="todo" onclick="this.cycleAttr(1, 'data-status')">Next status</button>
</div>

clay.dom functions#

• clay.dom.createContentView(context, options): Builds an inert clone of context with elements matching a region capability removed. options accepts { capability = "data", exclude = null, inherit = true, provenance = null } (the default "data" strips no-data and editor-ui). Returns { root, document, capability, selector, cloneToLive, liveToClone, original(node), cloneOf(node), query(selector, queryRoot = root), text(node = root), html(node = root), clone(node = root) }.
• clay.dom.cleanContentClone(node, options): Shorthand for clay.dom.createContentView(node, options).root.

clay-events.js#

clay-events.js waits for DOMContentLoaded (and for clay.loaded.dom if clay-dom.js is present on the page) and activates six HTML attributes:

<nav onclickchildren="for (const tab of this.parentElement.children) tab.removeAttribute('aria-current'); this.setAttribute('aria-current', 'page')">
  <button type="button" aria-current="page">Board</button>
  <button type="button">Archive</button>
</nav>

<div class="menu" onclickaway="this.hidden = true">...</div>

all.js (All)#

all.js publishes window.All (and clay.All), a zero-dependency Proxy wrapper around element collections.

Selecting elements#

• All(selectorOrElements, contextSelector?): Accepts a CSS selector string, an Element, Document, or an array of Element/Document nodes (anything else throws a TypeError). When contextSelector is passed, All searches within matching context elements (including any context element that matches selectorOrElements itself) or filters a passed element array to nodes inside those contexts.
• All.NAME shorthand: Accessing any unknown property on All queries [NAME], .NAME (for example, All.card returns All("[card], .card")). Because All.name and All.length are built-in Function properties, pass a selector string for those names: All("[name]").

Chaining, properties, and events#

An All collection behaves like an array (.length, numeric indexing cards[0], for...of, and Array.prototype methods) while forwarding DOM properties, methods, and events across every matched element:

• Property and method fan-out: Setting a property such as All(".card").className = "card open" writes to every matched element. Accessing .style, .classList, .dataset, or calling DOM methods chains across all elements and stays a safe no-op when the collection is empty.
• Event binding (on* methods):
  • All(".btn").onclick(fn): Attaches a click listener to each element.
  • All("#board").onclick(".card", fn): Delegated listener; invokes fn with this set to the closest .card.
  • All("#board").onclick({ ".add": addCard, ".remove": removeCard }): Map of delegated selectors to handlers.

Collection methods#

await clay.loaded.all;

const ids = All(".card").pluck("data-id"); // ["1", "2", "3"]
All(".card").eq(0).classList.add("active");
All("#list").onclick(".remove", function () {
  this.closest("li").remove();
});