@e280/sly 0.2.0-26 → 0.2.0-27

package/README.md

@@ -4,8 +4,9 @@
 # 🦝 sly
 > *mischievous shadow views*
 
-[@e280](https://e280.org/)'s shiny new [lit](https://lit.dev/)-based frontend webdev library. *(sly replaces its predecessor, [slate](https://github.com/benevolent-games/slate))*
+[@e280](https://e280.org/)'s new [lit](https://lit.dev/)-based frontend webdev library. *(sly replaces its predecessor, [slate](https://github.com/benevolent-games/slate))*
 
+- **✨[shiny](https://shiny.e280.org/)✨** — our wip component library https://shiny.e280.org/
 - 🍋 [**#views**](#views) — shadow-dom'd, hooks-based, componentizable
 - 🪵 [**#base-element**](#base-element) — for a more classical experience
 - 🪄 [**#dom**](#dom) — the "it's not jquery" multitool
@@ -285,8 +286,15 @@ import {html, css} from "lit"
 
     v // 123
     ```
+- **use.events** — attach event listeners to the element (auto-cleaned up)  
+    ```ts
+    use.events({
+      keydown: (e: KeyboardEvent) => console.log("keydown", e.code),
+      keyup: (e: KeyboardEvent) => console.log("keyup", e.code),
+    })
+    ```
 - **use.attrs** — ergonomic typed html attribute access  
-    - `use.attrs` is a bit different than `dom.attrs`, just to properly memoize .spec and .on for the render fn
+    - `use.attrs` is a bit different than [#dom.attrs](#dom.attrs), just to properly memoize .spec and .on for the render fn
     - use.attrs.spec
         ```ts
         const attrs = use.attrs.spec({
@@ -338,14 +346,14 @@ import {html, css} from "lit"
     ```
 
 ### 🍋 "use" recipes
-- make a ticker — mount, repeat, and nap
+- make a ticker — mount, cycle, and nap
     ```ts
-    import {repeat, nap} from "@e280/stz"
+    import {cycle, nap} from "@e280/stz"
     ```
     ```ts
     const $seconds = use.signal(0)
 
-    use.mount(() => repeat(async() => {
+    use.mount(() => cycle(async() => {
       await nap(1000)
       $seconds.value++
     }))
@@ -473,6 +481,11 @@ import {dom} from "@e280/sly"
     dom(".demo")
       // HTMLElement (or throws)
     ```
+    ```ts
+    // alias
+    dom.require(".demo")
+      // HTMLElement (or throws)
+    ```
 - `maybe` get an element
     ```ts
     dom.maybe(".demo")
@@ -483,39 +496,83 @@ import {dom} from "@e280/sly"
     dom.all(".demo ul li")
       // HTMLElement[]
     ```
-- scoped to an element
+
+### 🪄 dom.in scope
+- make a scope
     ```ts
-    dom(element).require("li")
-      // HTMLElement (or throws)
+    dom.in(".demo") // selector
+      // Dom instance
     ```
     ```ts
-    dom(element).maybe("li")
-      // HTMLElement | undefined
+    dom.in(demoElement) // element
+      // Dom instance
     ```
+- run queries in that scope
     ```ts
-    dom(element).all("li")
-      // HTMLElement[]
+    dom.in(demoElement).require(".button")
+    ```
+    ```ts
+    dom.in(demoElement).maybe(".button")
+    ```
+    ```ts
+    dom.in(demoElement).all("ol li")
     ```
 
 ### 🪄 dom utilities
-- `register` web components
+- `dom.register` web components
     ```ts
     dom.register({MyComponent, AnotherCoolComponent})
       // <my-component>
       // <another-cool-component>
     ```
     - `dom.register` automatically dashes the tag names (`MyComponent` becomes `<my-component>`)
-- `render` content into an element
+- `dom.render` content into an element
     ```ts
-    dom(element).render(html`<p>hello world</p>`)
+    dom.render(element, html`<p>hello world</p>`)
     ```
     ```ts
     dom.in(".demo").render(html`<p>hello world</p>`)
     ```
+- `dom.el` little element builder
     ```ts
-    dom.render(element, html`<p>hello world</p>`)
+    const div = dom.el("div", {"data-whatever": 123, "data-active": true})
+      // <div data-whatever="123" data-active></div>
+    ```
+- `dom.elmer` make an element with a fluent chain
+    ```ts
+    const div = dom.elmer("div")
+      .attr("data-whatever", 123)
+      .attr("data-active")
+      .children("hello world")
+      .done()
+        // HTMLElement
     ```
-- `attrs` <a id="dom.attrs"></a> to setup a type-happy html attribute helper
+- `dom.mk` make an element with a lit template (returns the first)
+    ```ts
+    const div = dom.mk(html`
+      <div data-whatever="123" data-active>
+        hello world
+      </div>
+    `) // HTMLElement
+    ```
+- `dom.events` <a id="dom.events"></a> to attach event listeners
+    ```ts
+    const detach = dom.events(element, {
+      keydown: (e: KeyboardEvent) => console.log("keydown", e.code),
+      keyup: (e: KeyboardEvent) => console.log("keyup", e.code),
+    })
+    ```
+    ```ts
+    const detach = dom.in(".demo").events({
+      keydown: (e: KeyboardEvent) => console.log("keydown", e.code),
+      keyup: (e: KeyboardEvent) => console.log("keyup", e.code),
+    })
+    ```
+    ```ts
+    // unattach those event listeners when you're done
+    detach()
+    ```
+- `dom.attrs` <a id="dom.attrs"></a> to setup a type-happy html attribute helper
     ```ts
     const attrs = dom.attrs(element).spec({
       name: String,
@@ -524,6 +581,13 @@ import {dom} from "@e280/sly"
     })
     ```
     ```ts
+    const attrs = dom.in(".demo").attrs.spec({
+      name: String,
+      count: Number,
+      active: Boolean,
+    })
+    ```
+    ```ts
     attrs.name // "chase"
     attrs.count // 123
     attrs.active // true
@@ -537,11 +601,12 @@ import {dom} from "@e280/sly"
     attrs.name = undefined // removes the attr
     attrs.count = undefined // removes the attr
     ```
-    or if you wanna be more loosey-goosy, skip the spec
+    or if you wanna be more loosey-goosey, skip the spec
     ```ts
-    dom.attrs(element).strings.name = "pimsley"
-    dom.attrs(element).numbers.count = 125
-    dom.attrs(element).booleans.active = true
+    const a = dom.in(".demo").attrs
+    a.strings.name = "pimsley"
+    a.numbers.count = 125
+    a.booleans.active = true
     ```
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/sly",
-	"version": "0.2.0-26",
+	"version": "0.2.0-27",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",
@@ -23,12 +23,12 @@
 		"lit": "^3.3.1"
 	},
 	"dependencies": {
-		"@e280/strata": "^0.2.0-14",
-		"@e280/stz": "^0.2.9"
+		"@e280/strata": "^0.2.0",
+		"@e280/stz": "^0.2.10"
 	},
 	"devDependencies": {
 		"@e280/science": "^0.1.2",
-		"@e280/scute": "^0.1.0",
+		"@e280/scute": "^0.1.1",
 		"http-server": "^14.1.1",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.9.3"

package/s/base/use.ts

@@ -7,6 +7,7 @@ import {Op} from "../ops/op.js"
 import {Mounts} from "./utils/mounts.js"
 import {UseAttrs} from "./utils/use-attrs.js"
 import {applyStyles} from "./utils/apply-styles.js"
+import { eve, EveSpec } from "../dom/parts/eve.js"
 
 export const _wrap = Symbol()
 export const _disconnect = Symbol()
@@ -90,6 +91,10 @@ export class Use {
 		return this.life(() => [fn(), () => {}])
 	}
 
+	events(spec: EveSpec) {
+		return this.mount(() => eve(this.element, spec))
+	}
+
 	op = (() => {
 		const that = this
 		function op<V>(f: () => Promise<V>) {

package/s/demo/views/fastcount.ts

@@ -1,6 +1,6 @@
 
 import {css, html} from "lit"
-import {nap, repeat} from "@e280/stz"
+import {nap, cycle} from "@e280/stz"
 
 import {dom} from "../../dom/dom.js"
 import {Use} from "../../base/use.js"
@@ -16,7 +16,7 @@ export class FastcountElement extends BaseElement {
 		const {value = 1} = this.attrs
 		const $count = use.signal(0)
 
-		use.mount(() => repeat(async() => {
+		use.mount(() => cycle(async() => {
 			await nap(10)
 			await $count($count() + 1)
 		}))

package/s/dom/attrs/attrs.ts

@@ -1,9 +1,9 @@
 
 import {AttrSpec} from "../types.js"
 import {onAttrs} from "./parts/on-attrs.js"
-import {attrFns} from "./parts/attr-fns.js"
 import {attrSpec} from "./parts/attr-spec.js"
 import {AttrProxies} from "./parts/attr-proxies.js"
+import {attrGet, attrSet} from "./parts/attr-fns.js"
 
 export function attrs(element: HTMLElement) {
 	const proxies = new AttrProxies(element)
@@ -16,6 +16,6 @@ export function attrs(element: HTMLElement) {
 	}
 }
 
-attrs.get = attrFns.get
-attrs.set = attrFns.set
+attrs.get = attrGet
+attrs.set = attrSet
 

package/s/dom/attrs/parts/attr-fns.ts

@@ -1,38 +1,68 @@
 
-/** fns for getting and setting html attributes of various types */
-export const attrFns = {
-	get: {
-		string: (e: HTMLElement, key: string) => {
-			return e.getAttribute(key) ?? undefined
-		},
-		number: (e: HTMLElement, key: string) => {
-			const raw = e.getAttribute(key)
-			return (raw === null || !raw)
-				? undefined
-				: Number(raw)
-		},
-		boolean: (e: HTMLElement, key: string) => {
-			const raw = e.getAttribute(key)
-			return raw !== null
-		},
-	},
-
-	set: {
-		string: (e: HTMLElement, key: string, value: string | undefined) => {
-			if (value === undefined) e.removeAttribute(key)
-			else e.setAttribute(key, value)
-			return true
-		},
-		number: (e: HTMLElement, key: string, value: number | undefined) => {
-			if (value === undefined) e.removeAttribute(key)
-			else e.setAttribute(key, value.toString())
-			return true
-		},
-		boolean: (e: HTMLElement, key: string, value: boolean | undefined) => {
-			if (value) e.setAttribute(key, "")
-			else e.removeAttribute(key)
-			return true
-		},
+import {AttrValue} from "../../types.js"
+
+/** get html attributes */
+export const attrGet = {
+	string: (e: HTMLElement, key: string) => {
+		return e.getAttribute(key) ?? undefined
+	},
+	number: (e: HTMLElement, key: string) => {
+		const raw = e.getAttribute(key)
+		return (raw === null || !raw)
+			? undefined
+			: Number(raw)
+	},
+	boolean: (e: HTMLElement, key: string) => {
+		const raw = e.getAttribute(key)
+		return raw !== null
+	},
+}
+
+/** set html attributes */
+export const attrSet = {
+	string: (e: HTMLElement, key: string, value: string | undefined) => {
+		if (value === undefined) e.removeAttribute(key)
+		else e.setAttribute(key, value)
+		return true
+	},
+	number: (e: HTMLElement, key: string, value: number | undefined) => {
+		if (value === undefined) e.removeAttribute(key)
+		else e.setAttribute(key, value.toString())
+		return true
+	},
+	boolean: (e: HTMLElement, key: string, value: boolean | undefined) => {
+		if (value) e.setAttribute(key, "")
+		else e.removeAttribute(key)
+		return true
+	},
+
+	any: (element: HTMLElement, key: string, value: AttrValue) => {
+		if (value === undefined || value === null)
+			element.removeAttribute(key)
+
+		else if (typeof value === "string")
+			element.setAttribute(key, value)
+
+		else if (typeof value === "number")
+			element.setAttribute(key, value.toString())
+
+		else if (typeof value === "boolean") {
+			if (value === true)
+				element.setAttribute(key, "")
+			else
+				element.removeAttribute(key)
+		}
+
+		else console.warn(`invalid attribute "${key}" type is "${typeof value}"`)
+	},
+
+	entries: (element: HTMLElement, entries: Iterable<[key: string, value: AttrValue]>) => {
+		for (const [key, value] of entries)
+			attrSet.any(element, key, value)
+	},
+
+	record: (element: HTMLElement, record: Record<string, AttrValue>) => {
+		return attrSet.entries(element, Object.entries(record))
 	},
 }
 

package/s/dom/attrs/parts/attr-proxies.ts

@@ -1,5 +1,5 @@
 
-import {attrFns} from "./attr-fns.js"
+import {attrGet, attrSet} from "./attr-fns.js"
 
 /** a typed proxy accessor for html attributes */
 export class AttrProxies {
@@ -7,28 +7,28 @@ export class AttrProxies {
 
 	strings = new Proxy({}, {
 		get: (_t, key: string) => (
-			attrFns.get.string(this.element, key)
+			attrGet.string(this.element, key)
 		),
 		set: (_t, key: string, value: string | undefined) => (
-			attrFns.set.string(this.element, key, value)
+			attrSet.string(this.element, key, value)
 		),
 	}) as Record<string, string | undefined>
 
 	numbers = new Proxy({}, {
 		get: (_t, key: string) => (
-			attrFns.get.number(this.element, key)
+			attrGet.number(this.element, key)
 		),
 		set: (_t, key: string, value: number | undefined) => (
-			attrFns.set.number(this.element, key, value)
+			attrSet.number(this.element, key, value)
 		),
 	}) as Record<string, number | undefined>
 
 	booleans = new Proxy({}, {
 		get: (_t, key: string) => (
-			attrFns.get.boolean(this.element, key)
+			attrGet.boolean(this.element, key)
 		),
 		set: (_t, key: string, value: boolean | undefined) => (
-			attrFns.set.boolean(this.element, key, value)
+			attrSet.boolean(this.element, key, value)
 		),
 	}) as Record<string, boolean | undefined>
 }

package/s/dom/attrs/parts/attr-spec.ts

@@ -1,6 +1,6 @@
 
+import {attrGet, attrSet} from "./attr-fns.js"
 import {AttrSpec, AttrTypes} from "../../types.js"
-import {attrFns} from "./attr-fns.js"
 
 /** specify available html attributes and their types and create a proxy accessor */
 export const attrSpec = <A extends AttrSpec>(
@@ -10,18 +10,18 @@ export const attrSpec = <A extends AttrSpec>(
 
 	get: (_target, key: string) => {
 		switch (spec[key]) {
-			case String: return attrFns.get.string(e, key)
-			case Number: return attrFns.get.number(e, key)
-			case Boolean: return attrFns.get.boolean(e, key)
+			case String: return attrGet.string(e, key)
+			case Number: return attrGet.number(e, key)
+			case Boolean: return attrGet.boolean(e, key)
 			default: throw new Error(`invalid attribute type for "${key}"`)
 		}
 	},
 
 	set: (_target, key: string, value: any) => {
 		switch (spec[key]) {
-			case String: return attrFns.set.string(e, key, value)
-			case Number: return attrFns.set.number(e, key, value)
-			case Boolean: return attrFns.set.boolean(e, key, value)
+			case String: return attrSet.string(e, key, value)
+			case Number: return attrSet.number(e, key, value)
+			case Boolean: return attrSet.boolean(e, key, value)
 			default: throw new Error(`invalid attribute type for "${key}"`)
 		}
 	},

package/s/dom/dom.ts

@@ -1,77 +1,31 @@
 
 import {render} from "lit"
 import {el} from "./parts/el.js"
-import {AttrSpec} from "./types.js"
+import {mk} from "./parts/mk.js"
+import {eve} from "./parts/eve.js"
 import {attrs} from "./attrs/attrs.js"
+import {elmer} from "./parts/elmer.js"
 import {Content} from "../view/types.js"
-import {eve, EveSpec} from "./parts/eve.js"
+import {Dom} from "./parts/dom-scope.js"
 import {register} from "./parts/register.js"
+import {Queryable, Renderable} from "./types.js"
+import {queryAll, queryMaybe, queryRequire} from "./parts/queries.js"
 
-export type Renderable = HTMLElement | ShadowRoot | DocumentFragment
-export type Queryable = HTMLElement | ShadowRoot | Element | Document | DocumentFragment
-
-function require<E extends Element>(
-		container: Queryable,
-		selector: string,
-	) {
-	const e = container.querySelector<E>(selector)
-	if (!e) throw new Error(`element not found (${selector})`)
-	return e
-}
-
-export class Dom<C extends Queryable> {
-	constructor(public element: C) {}
-
-	in<E extends HTMLElement>(selectorOrElement: string | E) {
-		return new Dom<E>(
-			(typeof selectorOrElement === "string")
-				? require(this.element, selectorOrElement) as E
-				: selectorOrElement
-		)
-	}
-
-	require<E extends Element = HTMLElement>(selector: string) {
-		const e = this.element.querySelector<E>(selector)
-		if (!e) throw new Error(`element not found (${selector})`)
-		return e
-	}
-
-	maybe<E extends Element = HTMLElement>(selector: string) {
-		return this.element.querySelector<E>(selector)
-	}
-
-	all<E extends Element = HTMLElement>(selector: string) {
-		return Array.from(this.element.querySelectorAll<E>(selector))
-	}
-
-	render(...content: Content[]) {
-		return render(content, this.element as Renderable)
-	}
-
-	attrs() {
-		return attrs(this.element as HTMLElement)
-	}
-
-	events(spec: EveSpec) {
-		return eve(this.element, spec)
-	}
+export function dom<E extends Element>(selector: string, container: Queryable = document): E {
+	return queryRequire<E>(selector, container)
 }
 
-export function dom<E extends Queryable>(selector: string): E
-export function dom<E extends Queryable>(element: E): Dom<E>
-export function dom<E extends Queryable>(selectorOrElement: string | E): E | Dom<E> {
-	return (typeof selectorOrElement === "string")
-		? require(document, selectorOrElement) as E
-		: new Dom(selectorOrElement)
+dom.in = <E extends HTMLElement>(selectorOrElement: string | E, container: Queryable = document) => {
+	return new Dom(container).in(selectorOrElement)
 }
 
-const doc = new Dom(document)
-dom.in = doc.in.bind(doc)
-dom.require = doc.require.bind(doc)
-dom.maybe = doc.maybe.bind(doc)
-dom.all = doc.all.bind(doc)
+dom.require = queryRequire
+dom.maybe = queryMaybe
+dom.all = queryAll
 
 dom.el = el
+dom.elmer = elmer
+dom.mk = mk
 dom.events = eve
 dom.attrs = attrs
 dom.register = register

package/s/dom/parts/dom-scope.ts

@@ -0,0 +1,46 @@
+
+import {render} from "lit"
+import {eve, EveSpec} from "./eve.js"
+import {attrs} from "../attrs/attrs.js"
+import {Content} from "../../view/types.js"
+import {Attrs, Queryable, Renderable} from "../types.js"
+import {queryAll, queryMaybe, queryRequire} from "./queries.js"
+
+export class Dom<C extends Queryable> {
+	#attrs?: Attrs
+
+	constructor(public element: C) {}
+
+	in<E extends HTMLElement>(selectorOrElement: string | E) {
+		return new Dom<E>(
+			(typeof selectorOrElement === "string")
+				? queryRequire(selectorOrElement, this.element) as E
+				: selectorOrElement
+		)
+	}
+
+	require<E extends Element = HTMLElement>(selector: string) {
+		return queryRequire<E>(selector, this.element)
+	}
+
+	maybe<E extends Element = HTMLElement>(selector: string) {
+		return queryMaybe<E>(selector, this.element)
+	}
+
+	all<E extends Element = HTMLElement>(selector: string) {
+		return queryAll<E>(selector, this.element)
+	}
+
+	render(...content: Content[]) {
+		return render(content, this.element as Renderable)
+	}
+
+	get attrs(): Attrs {
+		return this.#attrs ??= attrs(this.element as HTMLElement)
+	}
+
+	events(spec: EveSpec) {
+		return eve(this.element, spec)
+	}
+}
+

package/s/dom/parts/el.ts

@@ -1,14 +1,14 @@
 
-import {AttrValue} from "../../view/types.js"
-import {setAttrs} from "../../view/utils/parts/set-attrs.js"
+import {AttrValue} from "../types.js"
+import {attrSet} from "../attrs/parts/attr-fns.js"
 
 export function el<E extends HTMLElement>(
 		tagName: string,
-		attrs: Record<string, AttrValue>,
+		attrs: Record<string, AttrValue> = {},
 	) {
 
 	const element = document.createElement(tagName) as E
-	setAttrs(element, Object.entries(attrs))
+	attrSet.record(element, attrs)
 	return element
 }
 

package/s/dom/parts/elmer.ts

@@ -0,0 +1,38 @@
+
+import {AttrValue} from "../types.js"
+import {attrSet} from "../attrs/parts/attr-fns.js"
+
+export function elmer<E extends HTMLElement = HTMLElement>(tagName: string) {
+	return new Elmer<E>(tagName)
+}
+
+export class Elmer<E extends HTMLElement = HTMLElement> {
+	#attrs = new Map<string, AttrValue>()
+	#children: (Node | string)[] = []
+
+	constructor(public tagName: string) {}
+
+	attr(key: string, value: AttrValue = true) {
+		this.#attrs.set(key, value)
+		return this
+	}
+
+	attrs(record: Record<string, AttrValue>) {
+		for (const [key, value] of Object.entries(record))
+			this.attr(key, value)
+		return this
+	}
+
+	children(...elements: (Node | string)[]) {
+		this.#children.push(...elements)
+		return this
+	}
+
+	done() {
+		const element = document.createElement(this.tagName)
+		attrSet.entries(element, this.#attrs)
+		element.append(...this.#children)
+		return element as E
+	}
+}
+

package/s/dom/parts/mk.ts

@@ -0,0 +1,9 @@
+
+import {render, TemplateResult} from "lit"
+
+export function mk<E extends Element = HTMLElement>(template: TemplateResult) {
+	const fragment = document.createDocumentFragment()
+	render(template, fragment)
+	return fragment.firstElementChild as E
+}
+