npm - @e280/sly - Versions diffs - 0.2.0-3 → 0.2.0-5 - Mend

@e280/sly 0.2.0-3 → 0.2.0-5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/README.md +217 -17
package/package.json +1 -1
package/s/demo/demo.bundle.ts +6 -1
package/s/demo/views/demo.ts +1 -0
package/s/demo/views/incredi.ts +28 -0
package/s/dom/dom.ts +25 -13
package/s/index.html.ts +1 -0
package/s/index.ts +1 -0
package/s/loot/drag-and-drops.ts +82 -0
package/s/loot/{drop.ts → drops.ts} +8 -17
package/s/loot/helpers.ts +3 -3
package/s/loot/index.ts +2 -2
package/s/views/attributes.ts +6 -6
package/s/views/base-element.ts +84 -0
package/s/views/use.ts +1 -1
package/s/views/view.ts +4 -4
package/x/demo/demo.bundle.js +5 -1
package/x/demo/demo.bundle.js.map +1 -1
package/x/demo/demo.bundle.min.js +17 -14
package/x/demo/demo.bundle.min.js.map +4 -4
package/x/demo/views/demo.js +1 -0
package/x/demo/views/demo.js.map +1 -1
package/x/demo/views/incredi.d.ts +12 -0
package/x/demo/views/incredi.js +21 -0
package/x/demo/views/incredi.js.map +1 -0
package/x/dom/dom.d.ts +6 -5
package/x/dom/dom.js +19 -11
package/x/dom/dom.js.map +1 -1
package/x/index.d.ts +1 -0
package/x/index.html +3 -2
package/x/index.html.js +1 -0
package/x/index.html.js.map +1 -1
package/x/index.js +1 -0
package/x/index.js.map +1 -1
package/x/loot/drag-and-drops.d.ts +30 -0
package/x/loot/drag-and-drops.js +63 -0
package/x/loot/drag-and-drops.js.map +1 -0
package/x/loot/{drop.d.ts → drops.d.ts} +3 -5
package/x/loot/drops.js +25 -0
package/x/loot/drops.js.map +1 -0
package/x/loot/helpers.d.ts +3 -3
package/x/loot/helpers.js +3 -3
package/x/loot/helpers.js.map +1 -1
package/x/loot/index.d.ts +2 -2
package/x/loot/index.js +2 -2
package/x/loot/index.js.map +1 -1
package/x/views/attributes.d.ts +1 -1
package/x/views/attributes.js +5 -5
package/x/views/attributes.js.map +1 -1
package/x/views/base-element.d.ts +14 -0
package/x/views/base-element.js +62 -0
package/x/views/base-element.js.map +1 -0
package/x/views/use.js.map +1 -1
package/x/views/view.js +4 -4
package/x/views/view.js.map +1 -1
package/s/loot/drag-drop.ts +0 -76
package/x/loot/drag-drop.d.ts +0 -29
package/x/loot/drag-drop.js +0 -54
package/x/loot/drag-drop.js.map +0 -1
package/x/loot/drop.js +0 -32
package/x/loot/drop.js.map +0 -1

package/README.md CHANGED Viewed

@@ -9,7 +9,9 @@ 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
+- 🪙 **loot** — drag-and-drop facilities
 - 🧪 **testing page** — https://sly.e280.org/
@@ -45,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) => {
@@ -267,6 +268,85 @@ view(use => () => html`<p>hello world</p>`)
+<br/><br/>
+## 🦝🪵 sly base element
+> *the classic experience*
+```ts
+import {BaseElement, Use, attributes, dom} from "@e280/sly"
+import {html, css} from "lit"
+```
+`BaseElement` is a class-based approach to create a custom element web component.
+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
+- **declare your element class**
+    ```ts
+    export class MyElement extends BaseElement {
+      static styles = css`span{color:orange}`
+      // custom property
+      start = 10
+      // custom attributes
+      attrs = attributes(this, {
+        multiply: Number,
+      })
+      // custom methods
+      hello() {
+        return "world"
+      }
+      render(use: Use) {
+        const $count = use.signal(1)
+        const increment = () => $count.value++
+        const {start} = this
+        const {multiply = 1} = this.attrs
+        const result = start + (multiply * $count())
+        return html`
+          <span>${result}</span>
+          <button @click="${increment}">+</button>
+        `
+      }
+    }
+    ```
+- **register your element to the dom**
+    ```ts
+    dom.register({MyElement})
+    ```
+### 🪵 base element usage
+- **place the element in your html body**
+    ```html
+    <body>
+      <my-element></my-element>
+    </body>
+    ```
+- **now you can interact with it**
+    ```ts
+    const myElement = dom<MyElement>("my-element")
+    // js property
+    myElement.start = 100
+    // html attributes
+    myElement.attr.multiply = 2
+    // methods
+    myElement.hello()
+      // "world"
+    ```
 <br/><br/>
 ## 🦝🪄 sly dom
@@ -277,51 +357,51 @@ import {dom} from "@e280/sly"
 ```
 ### 🪄 dom queries
-- require an element
+- `require` an element
     ```ts
     dom(".demo")
       // HTMLElement (or throws)
     ```
-- maybe get an element
+- `maybe` get an element
     ```ts
     dom.maybe(".demo")
       // HTMLElement | undefined
     ```
-- select all elements
+- `select` all elements
     ```ts
     dom.all(".demo ul li")
       // HTMLElement[]
     ```
-- within a specific container
+- `in` the scope of an element
     ```ts
-    dom.in(element).require("li")
+    dom(element).require("li")
       // HTMLElement (or throws)
     ```
     ```ts
-    dom.in(element).maybe("li")
+    dom(element).maybe("li")
       // HTMLElement | undefined
     ```
     ```ts
-    dom.in(element).all("li")
+    dom(element).all("li")
       // HTMLElement[]
     ```
 ### 🪄 dom utilities
-- register web components
+- `register` web components
     ```ts
     dom.register({MyComponent, AnotherCoolComponent})
       // <my-component>
       // <another-cool-component>
     ```
-- render content into an element
+- `render` content into an element
     ```ts
-    dom.render(element, html`<p>hello world</p>`)
+    dom(element).render(html`<p>hello world</p>`)
     ```
     ```ts
-    dom.in(element).render(html`<p>hello world</p>`)
+    dom.in(".demo").render(html`<p>hello world</p>`)
     ```
     ```ts
-    dom.in(".demo").render(html`<p>hello world</p>`)
+    dom.render(element, html`<p>hello world</p>`)
     ```
@@ -455,6 +535,126 @@ import {Pod, podium, Op, makeLoader, anims} from "@e280/sly"
+<br/><br/>
+## 🦝🪙 loot
+> *drag-and-drop facilities*
+```ts
+import {loot, ev, view} from "@e280/sly"
+```
+### 🪙 `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 accept drops and stuff
+      ev(document.body, {
+        dragover: drops.dragover,
+        dragleave: drops.dragleave,
+        drop: drops.drop,
+      })
+      // update indicator attribute on body
+      drops.$indicator.on(indicator => {
+        if (indicator) document.body.setAttribute("data-indicator", "")
+        else document.body.removeAttribute("data-indicator")
+      })
+      ```
+- **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 grabbable and hoverable 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/>
 ## 🦝🧑‍💻 sly is by e280

package/package.json CHANGED Viewed

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

package/s/demo/demo.bundle.ts CHANGED Viewed

@@ -2,9 +2,14 @@
 import {dom} from "../dom/dom.js"
 import {DemoView} from "./views/demo.js"
 import {CounterView} from "./views/counter.js"
+import {IncrediElement} from "./views/incredi.js"
 dom.in(".demo").render(DemoView())
-dom.register({DemoCounter: CounterView.component(1)})
+dom.register({
+	IncrediElement,
+	DemoCounter: CounterView.component(1),
+})
 console.log("🦝 sly")

package/s/demo/views/demo.ts CHANGED Viewed

@@ -19,6 +19,7 @@ const styles = css`
 :host {
 	display: flex;
 	flex-direction: column;
+	align-items: center;
 	gap: 1em;
 }
 `

package/s/demo/views/incredi.ts ADDED Viewed

@@ -0,0 +1,28 @@
+import {css, html} from "lit"
+import {nap, repeat} from "@e280/stz"
+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})
+	something = {whatever: "rofl"}
+	render(use: Use) {
+		const {value = 1} = this.attrs
+		const $count = use.signal(0)
+		use.mount(() => repeat(async() => {
+			await nap(10)
+			await $count($count() + 1)
+		}))
+		return html`
+			<span>${$count() * value}</span>
+		`
+	}
+}

package/s/dom/dom.ts CHANGED Viewed

@@ -4,20 +4,29 @@ import {register} from "./register.js"
 import {Content} from "../views/types.js"
 import {Queryable, Renderable} from "./types.js"
+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>(elementOrSelector: E | string) {
-		return new Dom(
-			typeof elementOrSelector === "string"
-				? this.require<E>(elementOrSelector)
-				: elementOrSelector
+	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(`$1 ${selector} not found`)
+		if (!e) throw new Error(`element not found (${selector})`)
 		return e
 	}
@@ -34,18 +43,21 @@ export class Dom<C extends Queryable> {
 	}
 }
-export function dom(selector: string) {
-	return new Dom(document).require(selector)
+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)
 }
 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)
+dom.register = register
+dom.render = (container: Renderable, ...content: Content[]) => {
+	return render(content, container)
+}

package/s/index.html.ts CHANGED Viewed

@@ -29,6 +29,7 @@ export default ssg.page(import.meta.url, async orb => ({
 		<h1>sly testing page</h1>
 		<p><a href="https://github.com/e280/sly">github.com/e280/sly</a></p>
 		<p class=lil>v${orb.packageVersion()}</p>
+		<incredi-element></incredi-element>
 		<demo-counter>component</demo-counter>
 		<div class=demo></div>
 	`,

package/s/index.ts CHANGED Viewed

@@ -14,6 +14,7 @@ export * from "./ops/types.js"
 export * as loot from "./loot/index.js"
 export * from "./views/attributes.js"
+export * from "./views/base-element.js"
 export * from "./views/css-reset.js"
 export * from "./views/types.js"
 export * from "./views/use.js"

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

@@ -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} RENAMED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/attributes.ts CHANGED Viewed

@@ -26,6 +26,12 @@ export type AttrTypes<A extends AttrSpec> = {
 	[P in keyof A]: AttrType<A[P]>
 }
+export function onAttrChange(element: HTMLElement, fn: () => void) {
+	const observer = new MutationObserver(fn)
+	observer.observe(element, {attributes: true})
+	return () => observer.disconnect()
+}
 export const attributes = <A extends AttrSpec>(
 		element: HTMLElement,
 		spec: A,
@@ -81,9 +87,3 @@ export const attributes = <A extends AttrSpec>(
 }) as any as AttrTypes<A>
-export function onAttrChange(element: HTMLElement, fn: () => void) {
-	const observer = new MutationObserver(fn)
-	observer.observe(element, {attributes: true})
-	return () => observer.disconnect()
-}