@e280/sly 0.2.0-4 → 0.2.0-6

package/README.md

@@ -4,14 +4,14 @@
 # 🦝 sly
 > *mischievous shadow views*
 
-[@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).  
+[@e280](https://e280.org/)'s shiny new [lit](https://lit.dev/)-based frontend lib for webdevs. *(sly replaces its predecessor, [slate](https://github.com/benevolent-games/slate))*
 
-- 🍋 **views** — hooks-based, shadow-dom'd, componentizable
-- 🪄 **dom** — the "it's not jquery" multitool
-- 🪵 **base element** — for a more classical experience
-- 🫛 **ops** — tools for async operations and loading spinners
-- 🧪 **testing page** — https://sly.e280.org/
+- 🍋 [**views**](#views) — hooks-based, shadow-dom'd, componentizable
+- 🪵 [**base element**](#base-element) — for a more classical experience
+- 🪄 [**dom**](#dom) — the "it's not jquery" multitool
+- 🫛 [**ops**](#ops) — tools for async operations and loading spinners
+- 🪙 [**loot**](#loot) — drag-and-drop facilities
+- 🧪 testing page — https://sly.e280.org/
 
 
 
@@ -24,14 +24,15 @@ npm install @e280/sly lit
 ```
 
 > [!NOTE]
-> - 🔥 [lit](https://lit.dev/) for html rendering
+> - 🔥 [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) is our ts standard library
-> - 🐢 [scute](https://github.com/e280/scute) is our buildy-bundly-buddy
+> - 🏂 [@e280/stz](https://github.com/e280/stz), our ts standard library
+> - 🐢 [@e280/scute](https://github.com/e280/scute), our buildy-bundly-buddy
 
 
 
 <br/><br/>
+<a id="views"></a>
 
 ## 🦝🍋 sly views
 > *views are the crown jewel of sly.. shadow-dom'd.. hooks-based.. "ergonomics"..*
@@ -46,11 +47,10 @@ view(use => () => html`<p>hello world</p>`)
 - views automatically rerender whenever any [strata-compatible](https://github.com/e280/strata) state changes
 
 ### 🍋 view example
-- **import stuff**
-    ```ts
-    import {view, dom} from "@e280/sly"
-    import {html, css} from "lit"
-    ```
+```ts
+import {view, dom} from "@e280/sly"
+import {html, css} from "lit"
+```
 - **declare a view**
     ```ts
     export const CounterView = view(use => (start: number) => {
@@ -198,7 +198,8 @@ view(use => () => html`<p>hello world</p>`)
 
     v // 123
     ```
-- **use.attrs** — ergonomic typed html attribute access
+- **use.attrs** — ergonomic typed html attribute access  
+    *(see [dom.attrs](#dom.attrs) for more details)*
     ```ts
     const attrs = use.attrs({
       name: String,
@@ -211,14 +212,6 @@ view(use => () => html`<p>hello world</p>`)
     attrs.count // 123
     attrs.active // true
     ```
-    ```ts
-    attrs.name = "zenky"
-    attrs.count = 124
-    attrs.active = false // removes html attr
-    ```
-    ```ts
-    attrs.name = undefined // removes the attr
-    ```
 - **use.render** — rerender the view (debounced)
     ```ts
     use.render()
@@ -269,22 +262,23 @@ view(use => () => html`<p>hello world</p>`)
 
 
 <br/><br/>
+<a id="base-element"></a>
 
 ## 🦝🪵 sly base element
 > *the classic experience*
 
-so views are great, and they can be converted into components..  
-..but views have one drawback — you can't actually expose properties on the element instance itself.
+```ts
+import {BaseElement, Use, dom} from "@e280/sly"
+import {html, css} from "lit"
+```
+
+`BaseElement` is a class-based approach to create a custom element web component.
 
-that's where `BaseElement` comes in.  
-it's a proper class-based element, but it lets you have the same `use` hooks that views enjoy.
+it lets you expose js properties on the element instance, which helps you setup a better developer experience for people interacting with your element through the dom.
+
+base element enjoys the same `use` hooks as views.
 
 ### 🪵 base element setup
-- **import stuff**
-    ```ts
-    import {BaseElement, Use, attributes, dom} from "@e280/sly"
-    import {html, css} from "lit"
-    ```
 - **declare your element class**
     ```ts
     export class MyElement extends BaseElement {
@@ -294,8 +288,8 @@ it's a proper class-based element, but it lets you have the same `use` hooks tha
       start = 10
 
       // custom attributes
-      attrs = attributes(this, {
-        multiply: Number
+      attrs = dom.attrs(this, {
+        multiply: Number,
       })
 
       // custom methods
@@ -338,7 +332,7 @@ it's a proper class-based element, but it lets you have the same `use` hooks tha
     myElement.start = 100
 
     // html attributes
-    myElement.attr.multiply = 2
+    myElement.attrs.multiply = 2
 
     // methods
     myElement.hello()
@@ -348,6 +342,7 @@ it's a proper class-based element, but it lets you have the same `use` hooks tha
 
 
 <br/><br/>
+<a id="dom"></a>
 
 ## 🦝🪄 sly dom
 > *the "it's not jquery!" multitool*
@@ -403,10 +398,33 @@ import {dom} from "@e280/sly"
     ```ts
     dom.render(element, html`<p>hello world</p>`)
     ```
+- `attrs` <a id="dom.attrs"></a> to setup a type-happy html attribute helper
+    ```ts
+    const attrs = dom.attrs({
+      name: String,
+      count: Number,
+      active: Boolean,
+    })
+    ```
+    ```ts
+    attrs.name // "chase"
+    attrs.count // 123
+    attrs.active // true
+    ```
+    ```ts
+    attrs.name = "zenky"
+    attrs.count = 124
+    attrs.active = false // removes html attr
+    ```
+    ```ts
+    attrs.name = undefined // removes the attr
+    attrs.count = undefined // removes the attr
+    ```
 
 
 
 <br/><br/>
+<a id="ops"></a>
 
 ## 🦝🫛 sly ops
 > *tools for async operations and loading spinners*
@@ -536,8 +554,135 @@ import {Pod, podium, Op, makeLoader, anims} from "@e280/sly"
 
 
 <br/><br/>
+<a id="loot"></a>
+
+## 🦝🪙 loot
+> *drag-and-drop facilities*
+
+```ts
+import {loot, view, dom} from "@e280/sly"
+import {ev} from "@e280/stz"
+```
+
+### 🪙 `loot.Drops`
+> *accept the user dropping stuff like files onto the page*
+- **setup drops**
+    ```ts
+    const drops = new loot.Drops({
+      predicate: loot.hasFiles,
+      acceptDrop: event => {
+        const files = loot.files(event)
+        console.log("files dropped", files)
+      },
+    })
+    ```
+- **attach event listeners to your dropzone,** one of these ways:
+  - **view example**
+      ```ts
+      view(() => () => html`
+        <div
+          ?data-indicator="${drops.$indicator()}"
+          @dragover="${drops.dragover}"
+          @dragleave="${drops.dragleave}"
+          @drop="${drops.drop}">
+            my dropzone
+        </div>
+      `)
+      ```
+  - **vanilla-js whole-page example**
+      ```ts
+      // attach listeners to the body
+      ev(document.body, {
+        dragover: drops.dragover,
+        dragleave: drops.dragleave,
+        drop: drops.drop,
+      })
+
+      // sly attribute handler for the body
+      const attrs = dom.attrs(document.body, {
+        "data-indicator": Boolean,
+      })
+
+      // sync the data-indicator attribute
+      drops.$indicator.on(bool => attrs["data-indicator"] = bool)
+      ```
+- **flashy css indicator for the dropzone,** so the user knows your app is eager to accept the drop
+    ```css
+    [data-indicator] {
+      border: 0.5em dashed cyan;
+    }
+    ```
+
+### 🪙 `loot.DragAndDrops`
+> *setup drag-and-drops between items within your page*
+- **declare types for your draggy and droppy things**
+    ```ts
+    // money that can be picked up and dragged
+    type Money = {value: number}
+      // dnd will call this a "draggy"
+
+    // bag that money can be dropped into
+    type Bag = {id: number}
+      // dnd will call this a "droppy"
+    ```
+- **make your dnd**
+    ```ts
+    const dnd = new loot.DragAndDrops<Money, Bag>({
+      acceptDrop: (event, money, bag) => {
+        console.log("drop!", {money, bag})
+      },
+    })
+    ```
+- **attach dragzone listeners** (there can be many dragzones...)
+    ```ts
+    view(use => () => {
+      const money = use.once((): Money => ({value: 280}))
+      const dragzone = use.once(() => dnd.dragzone(() => money))
+
+      return html`
+        <div
+          draggable="${dragzone.draggable}"
+          @dragstart="${dragzone.dragstart}"
+          @dragend="${dragzone.dragend}">
+            money ${money.value}
+        </div>
+      `
+    })
+    ```
+- **attach dropzone listeners** (there can be many dropzones...)
+    ```ts
+    view(use => () => {
+      const bag = use.once((): Bag => ({id: 1}))
+      const dropzone = use.once(() => dnd.dropzone(() => bag))
+      const indicator = !!(dnd.dragging && dnd.hovering === bag)
+
+      return html`
+        <div
+          ?data-indicator="${indicator}"
+          @dragenter="${dropzone.dragenter}"
+          @dragleave="${dropzone.dragleave}"
+          @dragover="${dropzone.dragover}"
+          @drop="${dropzone.drop}">
+            bag ${bag.id}
+        </div>
+      `
+    })
+    ```
+
+### 🪙 loot helpers
+- **`loot.hasFiles(event)`** — return true if `DragEvent` contains any files (useful in `predicate`)
+- **`loot.files(event)`** — returns an array of files in a drop's `DragEvent` (useful in `acceptDrop`)
+
+
+
+<br/><br/>
+<a id="e280"></a>
 
 ## 🦝🧑‍💻 sly is by e280
 reward us with github stars  
 build with us at https://e280.org/ but only if you're cool  
 
+
+
+<br/><br/>
+

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/sly",
-	"version": "0.2.0-4",
+	"version": "0.2.0-6",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",

package/s/demo/views/incredi.ts

@@ -2,13 +2,13 @@
 import {css, html} from "lit"
 import {nap, repeat} from "@e280/stz"
 
+import {dom} from "../../dom/dom.js"
 import {Use} from "../../views/use.js"
-import {attributes} from "../../views/attributes.js"
 import {BaseElement} from "../../views/base-element.js"
 
 export class IncrediElement extends BaseElement {
 	static styles = css`span{color:orange}`
-	attrs = attributes(this, {value: Number})
+	attrs = dom.attrs(this, {value: Number})
 	something = {whatever: "rofl"}
 
 	render(use: Use) {

package/s/dom/dom.ts

@@ -2,7 +2,10 @@
 import {render} from "lit"
 import {register} from "./register.js"
 import {Content} from "../views/types.js"
-import {Queryable, Renderable} from "./types.js"
+import {attributes, AttrSpec, AttrTypes} from "./attributes.js"
+
+export type Renderable = HTMLElement | ShadowRoot | DocumentFragment
+export type Queryable = HTMLElement | ShadowRoot | Element | Document | DocumentFragment
 
 function require<E extends Element>(
 		container: Queryable,
@@ -41,6 +44,10 @@ export class Dom<C extends Queryable> {
 	render(...content: Content[]) {
 		return render(content, this.element as Renderable)
 	}
+
+	attrs<A extends AttrSpec>(spec: A) {
+		return attributes(this.element as HTMLElement, spec)
+	}
 }
 
 export function dom<E extends Queryable>(selector: string): E
@@ -56,6 +63,8 @@ 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.attrs = attributes
 dom.register = register
 dom.render = (container: Renderable, ...content: Content[]) => {
 	return render(content, container)

package/s/dom/register.ts

@@ -1,6 +1,9 @@
 
 import {dashify} from "./dashify.js"
-import {HTMLElementClasses} from "./types.js"
+
+export type HTMLElementClasses = {
+	[key: string]: {new(...args: any[]): HTMLElement}
+}
 
 export type RegistrationOptions = {
 	soft: boolean

package/s/index.ts

@@ -1,8 +1,8 @@
 
+export * from "./dom/attributes.js"
 export * from "./dom/dashify.js"
 export * from "./dom/dom.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"
@@ -13,7 +13,7 @@ export * from "./ops/types.js"
 
 export * as loot from "./loot/index.js"
 
-export * from "./views/attributes.js"
+export * from "./dom/attributes.js"
 export * from "./views/base-element.js"
 export * from "./views/css-reset.js"
 export * from "./views/types.js"

package/s/loot/drag-and-drops.ts

@@ -0,0 +1,82 @@
+
+import {signal} from "@e280/strata"
+import {Drops} from "./drops.js"
+import {outsideCurrentTarget} from "./helpers.js"
+
+/** respond to user dragging-and-dropping things around on a webpage */
+export class DragAndDrops<Draggy, Droppy> {
+
+	/** what is currently being dragged */
+	$draggy = signal<Draggy | undefined>(undefined)
+
+	/** what dropzone are we curently hovering over */
+	$droppy = signal<Droppy | undefined>(undefined)
+
+	constructor(private params: {
+
+		/** accept a dropped item that was declared within this system */
+		acceptDrop: (event: DragEvent, draggy: Draggy, droppy: Droppy) => void
+
+		/** also accept drops on the side */
+		backchannelDrops?: Drops
+	}) {}
+
+	get dragging() {
+		return this.$draggy()
+	}
+
+	get hovering() {
+		return this.$droppy()
+	}
+
+	/** make event listeners to attach to your dragzone(s) */
+	dragzone = (getDraggy: () => Draggy) => ({
+		draggable: "true",
+
+		dragstart: (_: DragEvent) => {
+			this.$draggy.value = getDraggy()
+		},
+
+		dragend: (_: DragEvent) => {
+			this.$draggy.value = undefined
+			this.$droppy.value = undefined
+		},
+	})
+
+	/** make event listeners to attach to your dropzones(s) */
+	dropzone = (getDroppy: () => Droppy) => ({
+		dragenter: (_: DragEvent) => {},
+
+		dragover: (event: DragEvent) => {
+			event.preventDefault()
+			if (this.$draggy())
+				this.$droppy.value = getDroppy()
+			else
+				this.params.backchannelDrops?.dragover(event)
+		},
+
+		dragleave: (event: DragEvent) => {
+			if (outsideCurrentTarget(event))
+				this.$droppy.value = undefined
+			this.params.backchannelDrops?.dragleave(event)
+		},
+
+		drop: (event: DragEvent) => {
+			event.preventDefault()
+			const {acceptDrop} = this.params
+			const draggy = this.$draggy()
+			const droppy = this.$droppy()
+			try {
+				if (draggy && droppy)
+					acceptDrop(event, draggy, droppy)
+				else
+					this.params.backchannelDrops?.drop(event)
+			}
+			finally {
+				this.$draggy.value = undefined
+				this.$droppy.value = undefined
+			}
+		},
+	})
+}
+

package/s/loot/{drop.ts → drops.ts}

@@ -1,10 +1,10 @@
 
 import {signal} from "@e280/strata"
-import {dragIsOutsideCurrentTarget} from "./helpers.js"
+import {outsideCurrentTarget} from "./helpers.js"
 
-/** dropzone that accepts dropped stuff like files */
-export class Drop {
-	#$indicator = signal(false)
+/** dropzone that accepts user-dropped stuff like files */
+export class Drops {
+	$indicator = signal(false)
 
 	constructor(private params: {
 
@@ -15,28 +15,19 @@ export class Drop {
 		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
+		this.$indicator.value = this.params.predicate(event)
 	}
 
 	dragleave = (event: DragEvent) => {
-		if (dragIsOutsideCurrentTarget(event))
-			this.#$indicator.value = false
+		if (outsideCurrentTarget(event))
+			this.$indicator.value = false
 	}
 
 	drop = (event: DragEvent) => {
 		event.preventDefault()
-		this.#$indicator.value = false
+		this.$indicator.value = false
 		if (this.params.predicate(event))
 			this.params.acceptDrop(event)
 	}

package/s/loot/helpers.ts

@@ -1,18 +1,18 @@
 
-export function dragHasFiles(event: DragEvent) {
+export function hasFiles(event: DragEvent) {
 	return !!(
 		event.dataTransfer &&
 		event.dataTransfer.types.includes("Files")
 	)
 }
 
-export function droppedFiles(event: DragEvent) {
+export function files(event: DragEvent) {
 	return event.dataTransfer
 		? Array.from(event.dataTransfer.files)
 		: []
 }
 
-export function dragIsOutsideCurrentTarget(event: DragEvent) {
+export function outsideCurrentTarget(event: DragEvent) {
 	const isCursorOutsideViewport = !event.relatedTarget || (
 		event.clientX === 0 &&
 		event.clientY === 0

package/s/loot/index.ts

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

package/s/views/base-element.ts

@@ -5,7 +5,7 @@ import {debounce, MapG} from "@e280/stz"
 
 import {dom} from "../dom/dom.js"
 import {Content} from "./types.js"
-import {onAttrChange} from "./attributes.js"
+import {onAttrChange} from "../dom/attributes.js"
 import {applyStyles} from "./utils/apply-styles.js"
 import {Use, _disconnect, _reconnect, _wrap} from "./use.js"
 

package/s/views/use.ts

@@ -4,9 +4,10 @@ import {defer, MapG} from "@e280/stz"
 import {signal, SignalOptions} from "@e280/strata/signals"
 
 import {Op} from "../ops/op.js"
+import {dom} from "../dom/dom.js"
 import {Mounts} from "./utils/mounts.js"
 import {applyStyles} from "./utils/apply-styles.js"
-import {attributes, AttrSpec, onAttrChange} from "./attributes.js"
+import {AttrSpec, onAttrChange} from "../dom/attributes.js"
 
 export const _wrap = Symbol()
 export const _disconnect = Symbol()
@@ -66,7 +67,7 @@ export class Use {
 
 	attrs<A extends AttrSpec>(spec: A) {
 		this.mount(() => onAttrChange(this.element, this.render))
-		return this.once(() => attributes(this.element, spec))
+		return this.once(() => dom.attrs(this.element, spec))
 	}
 
 	once<V>(fn: () => V) {