@e280/sly 0.2.0-0 → 0.2.0-10

package/README.md

@@ -1,63 +1,67 @@
 
 <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 new [lit](https://lit.dev/)-based frontend lib for webdevs. *(sly replaces its predecessor, [slate](https://github.com/benevolent-games/slate))*
 
-<br/>
+- 🍋 [**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/
+
+
+
+<br/><br/>
 
 ## 🦝 sly and friends
 
 ```sh
-npm install @e280/sly lit
+npm install @e280/sly lit @e280/strata @e280/stz
 ```
 
 > [!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
+> - 🔥 [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), our ts standard library
+> - 🐢 [@e280/scute](https://github.com/e280/scute), our buildy-bundly-buddy
+
+
 
-<br/>
+<br/><br/>
+<a id="views"></a>
 
-## 🦝 sly views
+## 🦝🍋 sly views and components
 > *views are the crown jewel of sly.. shadow-dom'd.. hooks-based.. "ergonomics"..*
 
 ```ts
 view(use => () => html`<p>hello world</p>`)
 ```
 
-- views are not [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components), but they do have [shadow roots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) and support [slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots)
-- any view can be registered as a web component, perfect for entrypoints or sharing widgets with html authors
+- any view can be converted into a web component
+- views are not [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) per se, but they do have [shadow roots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) and support [slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots)
 - views are typescript-native and comfy for webdevs building apps
 - views automatically rerender whenever any [strata-compatible](https://github.com/e280/strata) state changes
 
 ### 🍋 view example
-- **import stuff**
-    ```ts
-    import {$, view} from "@e280/sly"
-    import {html, css} from "lit"
-    ```
+```ts
+import {view, dom, BaseElement} from "@e280/sly"
+import {html, css} from "lit"
+```
 - **declare a view**
     ```ts
     export const CounterView = view(use => (start: number) => {
       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>
+        <span>${$count.value}</span>
         <button @click="${increment}">+</button>
       `
     })
@@ -65,16 +69,21 @@ 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)})
-      // <my-counter></my-counter>
+    dom.register({
+      MyCounter: CounterView
+        .component(BaseElement)
+        .props(component => [dom.attrs(component).number.start ?? 0]),
+    })
+    ```
+    ```html
+    <my-counter start="1"></my-counter>
     ```
 
 ### 🍋 view declaration settings
@@ -82,7 +91,7 @@ view(use => () => html`<p>hello world</p>`)
     ```ts
     export const CoolView = view
       .settings({mode: "open", delegatesFocus: true})
-      .declare(use => (greeting: string) => {
+      .render(use => (greeting: string) => {
         return html`😎 ${greeting} <slot></slot>`
       })
     ```
@@ -92,9 +101,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,27 +114,77 @@ 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
-- **build a component directly**
+### 🍋 view/component universality
+- **you can start with a view,**
     ```ts
-    const MyComponent = view.component(use => html`<p>hello world</p>`)
+    export const GreeterView = view(use => (name: string) => {
+      return html`<p>hello ${name}</p>`
+    })
+
+    // view usage:
+    //   GreeterView("pimsley")
     ```
-    - notice that direct components don't take props (do `use.attrs` instead)
-- **convert any view into a web component**
+    then convert it to a component.
     ```ts
-    const MyCounter = CounterView.component(1)
+    export class GreeterComponent extends (
+      GreeterView
+        .component(BaseElement)
+        .props(component => [component.getAttribute("name") ?? "unknown"])
+    ) {}
+
+    // html usage:
+    //   <greeter-component name="pimsley"></greeter-component>
     ```
-    - to convert a view to a component, you provide props
-    - note that the component instance has a render method like `element.render(2)` which can take new props at runtime
+    - this trick with `class` and `extends` is amazing because typescript exports both the value of your component class, but also its type (doesn't work if you use `const`)
+- **you can start with a component,**
+    ```ts
+    export class GreeterComponent extends (
+      view(use => (name: string) => {
+        return html`<p>hello ${name}</p>`
+      })
+      .component(BaseElement)
+      .props(component => [component.getAttribute("name") ?? "unknown"])
+    ) {}
+
+    // html usage:
+    //   <greeter-component name="pimsley"></greeter-component>
+    ```
+    then it already has a `.view` ready for you.
+    ```ts
+    // view usage:
+    //   GreeterComponent.view("pimsley")
+    ```
+- **understanding `.component(C)` and `.props(fn)`**
+    - `.props` takes a fn that is called every render, which returns the props given to the view
+        ```ts
+        .component(BaseElement)
+        .props(() => ["pimsley"])
+        ```
+        the props fn receives the component instance, so you can query html attributes or instance properties
+        ```ts
+        .component(BaseElement)
+        .props(component => [component.getAttribute("name") ?? "unknown"])
+        ```
+    - `.component` accepts a subclass of `BaseElement`, which lets you define your own properties and methods for your component class
+        ```ts
+        .component(class extends BaseElement {
+          $name = signal("jim raynor")
+          updateName(name: string) {
+            this.$name.value = name
+          }
+        })
+        .props(component => [component.$name.value])
+        ```
+    - `.component` lets devs interacting with your component get nice types
+        ```ts
+        dom<GreeterComponent>("my-component").updateName("mortimer")
+        ```
 - **register web components to the dom**
     ```ts
-    $.register({MyComponent, MyCounter})
-      // <my-component></my-component>
-      // <my-counter></my-counter>
+    dom.register({GreeterComponent})
     ```
-    - `$.register` automatically dashes the tag names (`MyComponent` becomes `<my-component>`)
 
-### 🍋 view "use" hooks reference
+### 🍋 "use" hooks reference
 - 👮 **follow the hooks rules**  
     > just like [react hooks](https://react.dev/warnings/invalid-hook-call-warning), the execution order of sly's `use` hooks actually matters..  
     > you must not call these hooks under `if` conditionals, or `for` loops, or in callbacks, or after a conditional `return` statement, or anything like that.. *otherwise, heed my warning: weird bad stuff will happen..*
@@ -138,16 +196,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)
+    ```
+    - `derived` signals
+        ```ts
+        const $product = use.derived(() => $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(() => {
@@ -186,9 +254,10 @@ 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({
+    const attrs = use.attrs.spec({
       name: String,
       count: Number,
       active: Boolean,
@@ -199,14 +268,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()
@@ -234,17 +295,17 @@ view(use => () => html`<p>hello world</p>`)
     const op = use.op.promise(doAsyncWork())
     ```
 
-### 🍋 view "use" recipes
+### 🍋 "use" recipes
 - make a ticker — mount, repeat, and nap
     ```ts
     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 +315,182 @@ view(use => () => html`<p>hello world</p>`)
     }))
     ```
 
-<br/>
 
-## 🦝 sly dom multitool
-> *"it's not jquery!"*
 
-### 💲 follow the money
-- import the dollarsign
+<br/><br/>
+<a id="base-element"></a>
+
+## 🦝🪵 sly base element
+> *the classic experience*
+
+```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.
+
+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
-    import {$} from "@e280/sly"
+    export class MyElement extends BaseElement {
+      static styles = css`span{color:orange}`
+
+      // custom property
+      start = 10
+
+      // custom attributes
+      attrs = dom.attrs(this).spec({
+        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.attrs.multiply = 2
+
+    // methods
+    myElement.hello()
+      // "world"
     ```
 
-### 💲 dom queries
-- require an element
+
+
+<br/><br/>
+<a id="dom"></a>
+
+## 🦝🪄 sly dom
+> *the "it's not jquery!" multitool*
+
+```ts
+import {dom} from "@e280/sly"
+```
+
+### 🪄 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
+- `in` the scope of an element
     ```ts
-    $("li", listElement)
-      // HTMLElement
+    dom(element).require("li")
+      // HTMLElement (or throws)
+    ```
+    ```ts
+    dom(element).maybe("li")
+      // HTMLElement | undefined
     ```
-
-### 💲 dom utilities
-- render content into an element
     ```ts
-    $.render(element, html`<p>hello world</p>`)
+    dom(element).all("li")
+      // HTMLElement[]
     ```
-- register web components
+
+### 🪄 dom utilities
+- `register` web components
     ```ts
-    $.register({MyComponent, AnotherCoolComponent})
+    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
+    ```ts
+    dom(element).render(html`<p>hello world</p>`)
+    ```
+    ```ts
+    dom.in(".demo").render(html`<p>hello world</p>`)
+    ```
+    ```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(element).spec({
+      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
+    ```
+    or if you wanna be more loosey-goosy, skip the spec
+    ```ts
+    dom.attrs(element).string.name = "pimsley"
+    dom.attrs(element).number.count = 125
+    dom.attrs(element).boolean.active = true
+    ```
+
+
 
-<br/>
+<br/><br/>
+<a id="ops"></a>
 
-## 🦝 sly ops, pods, and loaders
-> *async operations and displaying loading spinners.*
+## 🦝🫛 sly ops
+> *tools for async operations and loading spinners*
 
 ```ts
 import {nap} from "@e280/stz"
@@ -356,7 +544,7 @@ import {Pod, podium, Op, makeLoader, anims} from "@e280/sly"
     ```
 - 🔥 create an op that calls and tracks an async fn
     ```ts
-    const op = Op.fn(async() => {
+    const op = Op.load(async() => {
       await nap(4000)
       return 123
     })
@@ -426,9 +614,138 @@ 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/>
+<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).spec({
+        "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-0",
+	"version": "0.2.0-10",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",
@@ -16,12 +16,12 @@
 		"lit": "^3.3.1"
 	},
 	"dependencies": {
-		"@e280/strata": "^0.2.0-0",
+		"@e280/strata": "^0.2.0-8",
 		"@e280/stz": "^0.2.0"
 	},
 	"devDependencies": {
-		"@e280/science": "^0.1.1",
-		"@e280/scute": "^0.0.0",
+		"@e280/science": "^0.1.2",
+		"@e280/scute": "^0.1.0",
 		"http-server": "^14.1.1",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.9.2"