@e280/sly 0.2.0-0 → 0.2.0-2

package/README.md

@@ -1,19 +1,20 @@
 
 <div align="center"><img alt="" width="256" src="./assets/favicon.png"/></div>
 
-# 🦝 sly — mischievous shadow views
-> testing page https://sly.e280.org/
+# 🦝 sly
+> *mischievous shadow views*
 
-- 🍋 web app view library with taste
-- 🥷 leverage shadow-dom and slots
-- 🤯 register any view as a web component
-- 💲 handy little dom multitool
-- 🫛 ops for fancy loading spinners
-- 🧙‍♂️ took many years to get it right
-- 🌅 sly is the successor that replaces [@benev/slate](https://github.com/benevolent-games/slate)
-- 🧑‍💻 project by [@e280](https://e280.org/)
+[@e280](https://e280.org/)'s shiny, tasteful, incredible new [lit](https://lit.dev/)-based toolkit for frontend web developers.  
+sly replaces its predecessor, [slate](https://github.com/benevolent-games/slate).  
 
-<br/>
+- 🍋 **views** — hooks-based, shadow-dom'd, componentizable
+- 🪄 **dom** — the "it's not jquery" multitool
+- 🫛 **ops** — tools for async operations and loading spinners
+- 🧪 **testing page** — https://sly.e280.org/
+
+
+
+<br/><br/>
 
 ## 🦝 sly and friends
 
@@ -23,13 +24,15 @@ npm install @e280/sly lit
 
 > [!NOTE]
 > - 🔥 [lit](https://lit.dev/) for html rendering
-> - ⛏️ [@e280/strata](https://github.com/e280/strata) for state management (signals, state trees)
-> - 🏂 [@e280/stz](https://github.com/e280/stz) ***(optional)*** stz is our ts standard library
-> - 🐢 [scute](https://github.com/e280/scute) ***(optional)*** is our buildy-bundly-buddy
+> - ⛏️ [@e280/strata](https://github.com/e280/strata), for state management (signals, state trees)
+> - 🏂 [@e280/stz](https://github.com/e280/stz) is our ts standard library
+> - 🐢 [scute](https://github.com/e280/scute) is our buildy-bundly-buddy
+
 
-<br/>
 
-## 🦝 sly views
+<br/><br/>
+
+## 🦝🍋 sly views
 > *views are the crown jewel of sly.. shadow-dom'd.. hooks-based.. "ergonomics"..*
 
 ```ts
@@ -44,7 +47,7 @@ view(use => () => html`<p>hello world</p>`)
 ### 🍋 view example
 - **import stuff**
     ```ts
-    import {$, view} from "@e280/sly"
+    import {view, dom} from "@e280/sly"
     import {html, css} from "lit"
     ```
 - **declare a view**
@@ -53,11 +56,11 @@ view(use => () => html`<p>hello world</p>`)
       use.name("counter")
       use.styles(css`p {color: green}`)
 
-      const count = use.signal(start)
-      const increment = () => { count.value++ }
+      const $count = use.signal(start)
+      const increment = () => $count.value++
 
       return html`
-        <p>count ${count()}</p>
+        <p>count ${$count.value}</p>
         <button @click="${increment}">+</button>
       `
     })
@@ -65,15 +68,14 @@ view(use => () => html`<p>hello world</p>`)
     - each view renders into a `<sly-view view="counter">` host (where "counter" is the `use.name` you provided)
 - **inject a view into the dom**
     ```ts
-    $.render($(".app"), html`
-      <h1>my cool counter demo</h1>
-
+    dom.in(".app").render(html`
+      <h1>cool counter demo</h1>
       ${CounterView(1)}
     `)
     ```
 - 🤯 **register a view as a web component**
     ```ts
-    $.register({MyCounter: CounterView.component(1)})
+    dom.register({MyCounter: CounterView.component(1)})
       // <my-counter></my-counter>
     ```
 
@@ -92,9 +94,8 @@ view(use => () => html`<p>hello world</p>`)
 ### 🍋 view injection options
 - options for views at the template injection site
     ```ts
-    $.render($(".app"), html`
-      <h2>super cool example</h2>
-
+    dom.in(".app").render(html`
+      <h2>cool example</h2>
       ${CoolView.props("hello")
         .attr("class", "hero")
         .children(html`<em>spongebob</em>`)
@@ -106,7 +107,7 @@ view(use => () => html`<p>hello world</p>`)
     - `children` — nested content in the host element, can be [slotted](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots)
     - `render` — end the view chain and render the lit directive
 
-### 🍋 web components
+### 🍋 view web components
 - **build a component directly**
     ```ts
     const MyComponent = view.component(use => html`<p>hello world</p>`)
@@ -120,11 +121,11 @@ view(use => () => html`<p>hello world</p>`)
     - note that the component instance has a render method like `element.render(2)` which can take new props at runtime
 - **register web components to the dom**
     ```ts
-    $.register({MyComponent, MyCounter})
+    dom.register({MyComponent, MyCounter})
       // <my-component></my-component>
       // <my-counter></my-counter>
     ```
-    - `$.register` automatically dashes the tag names (`MyComponent` becomes `<my-component>`)
+    - `dom.register` automatically dashes the tag names (`MyComponent` becomes `<my-component>`)
 
 ### 🍋 view "use" hooks reference
 - 👮 **follow the hooks rules**  
@@ -138,16 +139,26 @@ view(use => () => html`<p>hello world</p>`)
     ```ts
     use.styles(css1, css2, css3)
     ```
+    *(alias `use.css`)*
 - **use.signal** — create a [strata signal](https://github.com/e280/strata)
     ```ts
-    const count = use.signal(1)
+    const $count = use.signal(1)
 
     // read the signal
-    count() // 1
+    $count()
 
     // write the signal
-    count(2)
-    ```
+    $count(2)
+    ```
+    - `derive` signals
+        ```ts
+        const $product = use.derive(() => $count() * $whatever())
+        ```
+    - `lazy` signals
+        ```ts
+        const $product = use.lazy(() => $count() * $whatever())
+        ```
+    - go read the [strata readme](https://github.com/e280/strata) about this stuff
 - **use.once** — run fn at initialization, and return a value
     ```ts
     const whatever = use.once(() => {
@@ -240,11 +251,11 @@ view(use => () => html`<p>hello world</p>`)
     import {repeat, nap} from "@e280/stz"
     ```
     ```ts
-    const seconds = use.signal(0)
+    const $seconds = use.signal(0)
 
     use.mount(() => repeat(async() => {
       await nap(1000)
-      seconds.value++
+      $seconds.value++
     }))
     ```
 - wake + rendered, to do something after each mount's first render
@@ -254,55 +265,71 @@ view(use => () => html`<p>hello world</p>`)
     }))
     ```
 
-<br/>
 
-## 🦝 sly dom multitool
-> *"it's not jquery!"*
 
-### 💲 follow the money
-- import the dollarsign
-    ```ts
-    import {$} from "@e280/sly"
-    ```
+<br/><br/>
+
+## 🦝🪄 sly dom
+> *the "it's not jquery!" multitool*
+
+```ts
+import {dom} from "@e280/sly"
+```
 
-### 💲 dom queries
+### 🪄 dom queries
 - require an element
     ```ts
-    $(".demo")
-      // HTMLElement (or throws error)
+    dom(".demo")
+      // HTMLElement (or throws)
     ```
-- request an element
+- maybe get an element
     ```ts
-    $.maybe(".demo")
+    dom.maybe(".demo")
       // HTMLElement | undefined
     ```
-- query all elements
+- select all elements
     ```ts
-    for (const item of $.all("ul li"))
-      console.log(item)
+    dom.all(".demo ul li")
+      // HTMLElement[]
     ```
-- specify what element to query under
+- within a specific container
     ```ts
-    $("li", listElement)
-      // HTMLElement
+    dom.in(element).require("li")
+      // HTMLElement (or throws)
     ```
-
-### 💲 dom utilities
-- render content into an element
     ```ts
-    $.render(element, html`<p>hello world</p>`)
+    dom.in(element).maybe("li")
+      // HTMLElement | undefined
+    ```
+    ```ts
+    dom.in(element).all("li")
+      // HTMLElement[]
     ```
+
+### 🪄 dom utilities
 - register web components
     ```ts
-    $.register({MyComponent, AnotherCoolComponent})
+    dom.register({MyComponent, AnotherCoolComponent})
       // <my-component>
       // <another-cool-component>
     ```
+- render content into an element
+    ```ts
+    dom.render(element, html`<p>hello world</p>`)
+    ```
+    ```ts
+    dom.in(element).render(html`<p>hello world</p>`)
+    ```
+    ```ts
+    dom.in(".demo").render(html`<p>hello world</p>`)
+    ```
+
 
-<br/>
 
-## 🦝 sly ops, pods, and loaders
-> *async operations and displaying loading spinners.*
+<br/><br/>
+
+## 🦝🫛 sly ops
+> *tools for async operations and loading spinners*
 
 ```ts
 import {nap} from "@e280/stz"
@@ -426,9 +453,11 @@ import {Pod, podium, Op, makeLoader, anims} from "@e280/sly"
     - when the op is in error, the error will be displayed
     - when the op is ready, your fn is called and given the value
 
-<br/>
 
-## 🧑‍💻 sly by e280
+
+<br/><br/>
+
+## 🦝🧑‍💻 sly is by e280
 reward us with github stars  
 build with us at https://e280.org/ but only if you're cool  
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/sly",
-	"version": "0.2.0-0",
+	"version": "0.2.0-2",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",
@@ -16,11 +16,11 @@
 		"lit": "^3.3.1"
 	},
 	"dependencies": {
-		"@e280/strata": "^0.2.0-0",
+		"@e280/strata": "^0.2.0-6",
 		"@e280/stz": "^0.2.0"
 	},
 	"devDependencies": {
-		"@e280/science": "^0.1.1",
+		"@e280/science": "^0.1.2",
 		"@e280/scute": "^0.0.0",
 		"http-server": "^14.1.1",
 		"npm-run-all": "^4.1.5",

package/s/demo/demo.bundle.ts

@@ -1,10 +1,10 @@
 
-import {$} from "../dom/dollar.js"
+import {dom} from "../dom/dom.js"
 import {DemoView} from "./views/demo.js"
 import {CounterView} from "./views/counter.js"
 
-$.render($(".demo"), DemoView())
-$.register({DemoCounter: CounterView.component(1)})
+dom.in(".demo").render(DemoView())
+dom.register({DemoCounter: CounterView.component(1)})
 
 console.log("🦝 sly")
 

package/s/demo/views/counter.ts

@@ -9,24 +9,31 @@ export const CounterView = view(use => (initial: number) => {
 	use.name("counter")
 	use.styles(cssReset, styles)
 
+	const $seconds = use.signal(0)
 	const start = use.once(() => Date.now())
-	const seconds = use.signal(0)
-
 	use.mount(() => repeat(async() => {
 		const since = Date.now() - start
-		seconds.set(Math.floor(since / 1000))
+		$seconds.set(Math.floor(since / 1000))
 	}))
 
-	const count = use.signal(initial)
-	const increment = () => count.value++
+	const $count = use.signal(initial)
+	const increment = () => $count.value++
+
+	const $product = use.signal
+		.derive(() => $count() * $seconds())
 
 	return html`
 		<slot></slot>
 		<div>
-			<span>${seconds.get()}</span>
+			<span>${$seconds.get()}</span>
+		</div>
+		<div>
+			<span>${$count.get()}</span>
+		</div>
+		<div>
+			<span>${$product.get()}</span>
 		</div>
 		<div>
-			<span>${count.get()}</span>
 			<button @click="${increment}">+</button>
 		</div>
 	`

package/s/dom/dom.ts

@@ -0,0 +1,51 @@
+
+import {render} from "lit"
+import {register} from "./register.js"
+import {Content} from "../views/types.js"
+import {Queryable, Renderable} from "./types.js"
+
+export class Dom<C extends Queryable> {
+	constructor(public element: C) {}
+
+	in<E extends HTMLElement>(elementOrSelector: E | string) {
+		return new Dom(
+			typeof elementOrSelector === "string"
+				? this.require<E>(elementOrSelector)
+				: elementOrSelector
+		)
+	}
+
+	require<E extends Element = HTMLElement>(selector: string) {
+		const e = this.element.querySelector<E>(selector)
+		if (!e) throw new Error(`$1 ${selector} not found`)
+		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)
+	}
+}
+
+export function dom(selector: string) {
+	return new Dom(document).require(selector)
+}
+
+const doc = new Dom(document)
+dom.register = register
+dom.render = (container: Renderable, ...content: Content[]) => {
+	return render(content, container)
+}
+
+dom.in = doc.in.bind(doc)
+dom.require = doc.require.bind(doc)
+dom.maybe = doc.maybe.bind(doc)
+dom.all = doc.all.bind(doc)
+

package/s/dom/types.ts

@@ -1,4 +1,7 @@
 
+export type Renderable = HTMLElement | ShadowRoot | DocumentFragment
+export type Queryable = HTMLElement | ShadowRoot | Element | Document | DocumentFragment
+
 export type HTMLElementClasses = {
 	[key: string]: {new(...args: any[]): HTMLElement}
 }

package/s/index.ts

@@ -1,17 +1,17 @@
 
 export * from "./dom/dashify.js"
-export * from "./dom/dollar.js"
 export * from "./dom/register.js"
 export * from "./dom/types.js"
 
 export * from "./ops/loaders/make-loader.js"
 export * from "./ops/loaders/parts/ascii-anim.js"
 export * from "./ops/loaders/parts/error-display.js"
-
 export * from "./ops/op.js"
 export * from "./ops/podium.js"
 export * from "./ops/types.js"
 
+export * as loot from "./loot/index.js"
+
 export * from "./views/attributes.js"
 export * from "./views/css-reset.js"
 export * from "./views/types.js"

package/s/loot/drag-drop.ts

@@ -0,0 +1,76 @@
+
+import {signal} from "@e280/strata"
+import {dragIsOutsideCurrentTarget} from "./helpers.js"
+
+/** system for dragging-and-dropping things around on a webpage */
+export class DragDrop<Grabbed, Hovering> {
+	#$grabbed = signal<Grabbed | undefined>(undefined)
+	#$hovering = signal<Hovering | undefined>(undefined)
+
+	constructor(private params: {
+
+		/** accept a dropped item that was declared within this system */
+		acceptDrop: (event: DragEvent, grabbed: Grabbed, hovering: Hovering) => void
+
+		/** accept undeclared drops from outside this system */
+		fromOutside?: {
+			predicate: (event: DragEvent, hovering: Hovering) => boolean
+			acceptDrop: (event: DragEvent, hovering: Hovering) => void
+		}
+	}) {}
+
+	/** make event listeners to attach to your dragzone(s) */
+	readonly dragzone = {
+		draggable: () => "true",
+
+		dragstart: (grabbed: Grabbed) => (_: DragEvent) => {
+			this.#$grabbed.value = grabbed
+		},
+
+		dragend: () => (_: DragEvent) => {
+			this.#$grabbed.value = undefined
+			this.#$hovering.value = undefined
+		},
+	}
+
+	/** make event listeners to attach to your dropzones(s) */
+	readonly dropzone = {
+		dragenter: () => (_: DragEvent) => {},
+
+		dragleave: () => (event: DragEvent) => {
+			if (dragIsOutsideCurrentTarget(event))
+				this.#$hovering.value = undefined
+		},
+
+		dragover: (hovering: Hovering) => (event: DragEvent) => {
+			event.preventDefault()
+			const {fromOutside} = this.params
+
+			if (this.#$grabbed() || (fromOutside && fromOutside.predicate(event, hovering)))
+				this.#$hovering.value = hovering
+		},
+
+		drop: (hovering: Hovering) => (event: DragEvent) => {
+			event.preventDefault()
+			const {acceptDrop, fromOutside} = this.params
+
+			const grabbed = this.#$grabbed()
+			this.#$grabbed.value = undefined
+			this.#$hovering.value = undefined
+
+			if (grabbed)
+				acceptDrop(event, grabbed, hovering)
+			else if (fromOutside && fromOutside.predicate(event, hovering))
+				fromOutside.acceptDrop(event, hovering)
+		},
+	}
+
+	get grabbed() {
+		return this.#$grabbed()
+	}
+
+	get hovering() {
+		return this.#$hovering()
+	}
+}
+

package/s/loot/drop.ts

@@ -0,0 +1,44 @@
+
+import {signal} from "@e280/strata"
+import {dragIsOutsideCurrentTarget} from "./helpers.js"
+
+/** dropzone that accepts dropped stuff like files */
+export class Drop {
+	#$indicator = signal(false)
+
+	constructor(private params: {
+
+		/** whether or not the dragged item is acceptable for a drop */
+		predicate: (event: DragEvent) => boolean
+
+		/** fn to handle the drop of an acceptable item */
+		acceptDrop: (event: DragEvent) => void
+	}) {}
+
+	get indicator() {
+		return this.#$indicator.value
+	}
+
+	resetIndicator = () => {
+		this.#$indicator.value = false
+	}
+
+	dragover = (event: DragEvent) => {
+		event.preventDefault()
+		if (this.params.predicate(event))
+			this.#$indicator.value = true
+	}
+
+	dragleave = (event: DragEvent) => {
+		if (dragIsOutsideCurrentTarget(event))
+			this.#$indicator.value = false
+	}
+
+	drop = (event: DragEvent) => {
+		event.preventDefault()
+		this.#$indicator.value = false
+		if (this.params.predicate(event))
+			this.params.acceptDrop(event)
+	}
+}
+

package/s/loot/helpers.ts

@@ -0,0 +1,31 @@
+
+export function dragHasFiles(event: DragEvent) {
+	return !!(
+		event.dataTransfer &&
+		event.dataTransfer.types.includes("Files")
+	)
+}
+
+export function droppedFiles(event: DragEvent) {
+	return event.dataTransfer
+		? Array.from(event.dataTransfer.files)
+		: []
+}
+
+export function dragIsOutsideCurrentTarget(event: DragEvent) {
+	const isCursorOutsideViewport = !event.relatedTarget || (
+		event.clientX === 0 &&
+		event.clientY === 0
+	)
+
+	if (isCursorOutsideViewport)
+		return true
+
+	const rect = (event.currentTarget as any).getBoundingClientRect()
+	const withinX = event.clientX >= rect.left && event.clientX <= rect.right
+	const withinY = event.clientY >= rect.top && event.clientY <= rect.bottom
+	const cursorOutsideCurrentTarget = !(withinX && withinY)
+
+	return cursorOutsideCurrentTarget
+}
+

package/s/loot/index.ts

@@ -0,0 +1,5 @@
+
+export * from "./drag-drop.js"
+export * from "./drop.js"
+export * from "./helpers.js"
+

package/s/views/use.ts

@@ -1,7 +1,7 @@
 
 import {CSSResultGroup} from "lit"
 import {defer, MapG} from "@e280/stz"
-import {signal} from "@e280/strata/signals"
+import {Derive, Lazy, Signal, signal, SignalOptions} from "@e280/strata/signals"
 
 import {Op} from "../ops/op.js"
 import {Mounts} from "./utils/mounts.js"
@@ -101,8 +101,26 @@ export class Use {
 		return op
 	})()
 
-	signal<V>(value: V) {
-		return this.once(() => signal<V>(value))
+	signal = (() => {
+		const that = this
+		function sig<V>(value: V, options?: Partial<SignalOptions>) {
+			return that.once(() => signal<V>(value, options))
+		}
+		sig.derive = function derive<V>(formula: () => V, options?: Partial<SignalOptions>) {
+			return that.once(() => signal.derive<V>(formula, options))
+		}
+		sig.lazy = function lazy<V>(formula: () => V, options?: Partial<SignalOptions>) {
+			return that.once(() => signal.lazy<V>(formula, options))
+		}
+		return sig
+	})()
+
+	derive<V>(formula: () => V, options?: Partial<SignalOptions>) {
+		return this.once(() => signal.derive<V>(formula, options))
+	}
+
+	lazy<V>(formula: () => V, options?: Partial<SignalOptions>) {
+		return this.once(() => signal.lazy<V>(formula, options))
 	}
 }
 

package/x/demo/demo.bundle.js

@@ -1,7 +1,7 @@
-import { $ } from "../dom/dollar.js";
+import { dom } from "../dom/dom.js";
 import { DemoView } from "./views/demo.js";
 import { CounterView } from "./views/counter.js";
-$.render($(".demo"), DemoView());
-$.register({ DemoCounter: CounterView.component(1) });
+dom.in(".demo").render(DemoView());
+dom.register({ DemoCounter: CounterView.component(1) });
 console.log("🦝 sly");
 //# sourceMappingURL=demo.bundle.js.map

package/x/demo/demo.bundle.js.map

@@ -1 +1 @@
-{"version":3,"file":"demo.bundle.js","sourceRoot":"","sources":["../../s/demo/demo.bundle.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,CAAC,EAAC,MAAM,kBAAkB,CAAA;AAClC,OAAO,EAAC,QAAQ,EAAC,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAA;AAE9C,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAA;AAChC,CAAC,CAAC,QAAQ,CAAC,EAAC,WAAW,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,EAAC,CAAC,CAAA;AAEnD,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA"}
+{"version":3,"file":"demo.bundle.js","sourceRoot":"","sources":["../../s/demo/demo.bundle.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,GAAG,EAAC,MAAM,eAAe,CAAA;AACjC,OAAO,EAAC,QAAQ,EAAC,MAAM,iBAAiB,CAAA;AACxC,OAAO,EAAC,WAAW,EAAC,MAAM,oBAAoB,CAAA;AAE9C,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAA;AAClC,GAAG,CAAC,QAAQ,CAAC,EAAC,WAAW,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,EAAC,CAAC,CAAA;AAErD,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA"}