@e280/sly 0.0.0-7 → 0.0.0-8

package/README.md

@@ -4,11 +4,13 @@
 # 🦝 sly — mischievous shadow views
 > testing page at https://sly.e280.org/
 
-- 🪒 lean view framework for [lit](https://lit.dev/) web devs
-- 🌅 sly is the successor to [@benev/slate](https://github.com/benevolent-games/slate)
-- 🏂 commonly used with stz standard library [@e280/stz](https://github.com/e280/stz)
-- ⛏️ integrates signals and state trees from [@e280/strata](https://github.com/e280/strata)
-- 🐢 if you need a buildy-bundler-buddy, try [scute](https://github.com/e280/scute)
+- 🍋 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 of iteration and suffering
+- 🌅 sly is the successor that replaces [@benev/slate](https://github.com/benevolent-games/slate)
 - 🧑‍💻 project by [@e280](https://e280.org/)
 
 <br/>
@@ -16,63 +18,73 @@
 ## 🦝 INSTALL SLY AND PALS
 
 ```sh
-npm install @e280/sly @e280/stz @e280/strata 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)
+> - 🏂 *(optional)* [@e280/stz](https://github.com/e280/stz) stz is our ts standard library
+> - 🐢 *(optional)* [scute](https://github.com/e280/scute) is our buildy-bundly-buddy
+
 <br/>
 
 ## 🦝 SLY VIEWS
-views are the crown jewel of sly. shadow-dom'd. hooks-based. fancy ergonomics. not components.
+views are the crown jewel of sly. shadow-dom'd. hooks-based. fancy ergonomics.
 
-views are leaner than web components.. no dom registration, no string tag names.. just import 'em, and the types work.. web components are fine, but they're for providing html authors with entrypoints to your cool widgets.. whereas views are the building blocks for frontend app devs.
+```ts
+view(use => () => "hello world")
+```
 
-sly views are wired to automatically rerender whenever they're using any state stuff from [@e280/strata](https://github.com/e280/strata).
+views are not web components.
 
-- a minimal view looks like this:
-    ```ts
-    import {view} from "@e280/sly"
+where web components are html-native, views are typescript-native — with views, there's no dom registration or string tag names, you just import them and the types work.
 
-    view(use => () => "hello world")
-    ```
+web components are best for giving html authors access to your cool widgets.. and that's cool, because any sly view can be registered as a web component.
+
+views automatically rerender whenever any state stuff from [@e280/strata](https://github.com/e280/strata) changes.
+
+🥷 views have a [shadow root](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 have the good parts of web components, but they aren't cumbersome.
 
 ### 🍋 view example
-- views are hooks-based functional components with a [shadow root](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM)
-- **declaring a view**
+- **import some stuff**
     ```ts
-    import {view} from "@e280/sly"
+    import {$, view} from "@e280/sly"
     import {html, css} from "lit"
-
+    ```
+- **declaring 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++ }
 
       return html`
         <p>count ${count()}</p>
-        <button @click="${() => { count.value++ }}">+</button>
+        <button @click="${increment}">+</button>
       `
     })
     ```
-    - each view renders into a `<sly-view>` host, with the provided `name` set as its view attribute, eg `<sly-view view="counter">`
-- **injecting a view into the dom**
+    - 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
-    import {render, html} from "lit"
-    import {CounterView} from "./my-counter.js"
+    $.render($(".app"), html`
+      <h1>my cool counter demo</h1>
 
-    const content = html`
-      <h1>my demo page</h1>
       ${CounterView(1)}
-    `
-
-    render(content, document.querySelector(".app")!)
+    `)
+    ```
+- 🤯 **register view as a web component**
+    ```ts
+    $.register({MyCounter: CounterView.component(1)})
+      // <my-counter></my-counter>
     ```
 
 ### 🍋 view declaration settings
 - special settings for views at declaration-time
     ```ts
-    import {view} from "@e280/sly"
-    import {html} from "lit"
-
     export const CoolView = view
       .settings({mode: "open", delegatesFocus: true})
       .view(use => (greeting: string) => {
@@ -86,24 +98,39 @@ sly views are wired to automatically rerender whenever they're using any state s
 ### 🍋 view injection options
 - options for views at the template injection site
     ```ts
-    import {render, html} from "lit"
-    import {CoolView} from "./cool-view.js"
-
-    const content = html`
+    $.render($(".app"), html`
       <h2>super cool example</h2>
       ${CoolView
         .attr("class", "hero")
         .children(html`<em>spongebob</em>`)
         .props("hello")}
-    `
-
-    render(content, document.querySelector(".app")!)
+    `)
     ```
     - `attr` — set html attributes on the `<sly-view>` host element
     - `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)
     - `props` — finally inject the view by providing its props
 
-### 🍋 view `use` reference
+### 🍋 web components
+- **build a component directly**
+    ```ts
+    const MyComponent = view.component(use => html`hello world`)
+    ```
+    - notice that components don't take props
+- **convert any view into a web component**
+    ```ts
+    const MyCounter = CounterView.component(1)
+    ```
+    - 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
+- **register web components to the dom**
+    ```ts
+    $.register({MyComponent, MyCounter})
+      // <my-component></my-component>
+      // <my-counter></my-counter>
+    ```
+    - `$.register` automatically dashes the tag names (`MyComponent` becomes `<my-component>`)
+
+### 🍋 view "use" reference
 - **use.name** — set the "view" attr value, eg `<sly-view view="squarepants">`
     ```ts
     use.name("squarepants")
@@ -117,19 +144,19 @@ sly views are wired to automatically rerender whenever they're using any state s
     const count = use.signal(1)
 
     // read the signal
-    count() //-> 1
+    count() // 1
 
     // write the signal
     count(2)
     ```
-- **use.once** — run fn at initialization
+- **use.once** — run fn at initialization, and return a value
     ```ts
     const whatever = use.once(() => {
       console.log("happens only once")
       return 123
     })
 
-    whatever //-> 123
+    whatever // 123
     ```
 - **use.mount** — setup mount/unmount lifecycle
     ```ts
@@ -141,6 +168,15 @@ sly views are wired to automatically rerender whenever they're using any state s
       }
     })
     ```
+- **use.wake** — run fn each time mounted, and return value
+    ```ts
+    const whatever = use.wake(() => {
+      console.log("view mounted")
+      return 123
+    })
+
+    whatever // 123
+    ```
 - **use.life** — mount/unmount lifecycle, but also return a value
     ```ts
     const v = use.life(() => {
@@ -149,22 +185,47 @@ sly views are wired to automatically rerender whenever they're using any state s
       return [value, () => console.log("unmounted")]
     })
 
-    v //-> 123
+    v // 123
     ```
-- **use.render** — force a hard render (not debounced)
+- **use.attrs** — ergonomic typed html attribute access
+    ```ts
+    const attrs = use.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
+    ```
+- **use.render** — rerender the view (debounced)
     ```ts
     use.render()
     ```
+- **use.renderNow** — rerender the view instantly (not debounced)
+    ```ts
+    use.renderNow()
+    ```
 - **use.rendered** — promise that resolves *after* the next render
     ```ts
     use.rendered.then(() => {
-      const slot = use.shadow.querySelector("slot")!
+      const slot = use.shadow.querySelector("slot")
       console.log(slot)
     })
     ```
-- **use.op.fn** — start with an op based on an async fn
+- **use.op** — start with an op based on an async fn
     ```ts
-    const op = use.op.fn(async() => {
+    const op = use.op(async() => {
       await nap(5000)
       return 123
     })
@@ -174,30 +235,7 @@ sly views are wired to automatically rerender whenever they're using any state s
     const op = use.op.promise(doAsyncWork())
     ```
 
-### 🍋 web components
-- convert any view into a proper web component
-    ```ts
-    CounterView.component(1)
-    ```
-- or build a component directly
-    ```ts
-    const MyComponent = view(use => html`hello world`)
-    ```
-- register web components to the dom like this
-    ```ts
-    import {$} from "@e280/sly"
-
-    $.register({
-      MyCounter: CounterView.component(1),
-      MyComponent,
-    })
-
-    // <my-counter></my-counter>
-    // <my-component></my-component>
-    ```
-    - `$.register` automatically dashes the tag names (`MyComponent` becomes `<my-component>`)
-
-### 🍋 neat tricks to impress the ladies
+### 🍋 view "use" recipes
 - make a ticker — mount, repeat, and nap
     ```ts
     import {repeat, nap} from "@e280/stz"
@@ -210,65 +248,183 @@ sly views are wired to automatically rerender whenever they're using any state s
       seconds.value++
     }))
     ```
-- once+rendered to do an action after the first render
+- wake + rendered, to do something after each mount's first render
     ```ts
-    use.once(() => use.rendered.then(() => {
+    use.wake(() => use.rendered.then(() => {
       console.log("after first render")
     }))
     ```
 
 <br/>
 
-## 🦝 SLY'S `$` DOLLAR DOM MULTITOOL
-- import the `$` and it has a bunch of goodies
+## 🦝 SLY `$` DOM MULTITOOL
+
+### 💲 follow the money
+- import the dollarsign
     ```ts
     import {$} from "@e280/sly"
     ```
-- query an element (throws an error if not found)
+
+### 💲 dom queries
+- require an element
     ```ts
     $(".demo")
-      // HTMLElement
+      // HTMLElement (or throws error)
     ```
-
-### queries
-- query an element (undefined if not found)
+- request an element
     ```ts
     $.maybe(".demo")
       // HTMLElement | undefined
     ```
-- query all elements (returns an array)
+- query all elements
     ```ts
-    $.maybe("ul li")
-      // HTMLElement[]
+    for (const item of $.all("ul li"))
+      console.log(item)
     ```
-- query all elements (returns an array)
+- specify what element to query under
     ```ts
-    $.maybe("ul li")
-      // HTMLElement[]
+    $("li", listElement)
+      // HTMLElement
     ```
 
-### dom stuff
+### 💲 dom utilities
+- render content into an element
+    ```ts
+    $.render(element, html`hello world`)
+    ```
 - register web components
     ```ts
     $.register({MyComponent, AnotherCoolComponent})
       // <my-component>
       // <another-cool-component>
     ```
-- render content into an element
-    ```ts
-    $.render(element, html`hello world`)
-    ```
 
 <br/>
 
 ## 🦝 SLY OPS, PODS, AND LOADERS
-> ***TODO*** *we need to write real docs for this, lol*
-- `Pod` is a type for loading/ready/error states
-- `podium` is a tool with fns for working with pods
-- `Op` class wraps a pod signal and has some ergonomic fns
-- `makeLoader(anims.bar2)` makes it easy to create a loader
-  - see the available `anims` on the testing page: https://sly.e280.org/
-  - a loader's job is to render an op, with a nice loading anim and error display view
+async operations and displaying loading spinners.
+
+```ts
+import {nap} from "@e280/stz"
+import {Pod, podium, Op, makeLoader, anims} from "@e280/sly"
+```
+
+### 🫛 pods: loading/ready/error data
+- a pod represents an async operation
+- pods are simple json-serializable data
+- there are three kinds of `Pod<V>`
+    ```ts
+    // loading pod
+    ["loading"]
+
+    // ready pod contains value 123
+    ["ready", 123]
+
+    // error pod contains an error
+    ["error", new Error()]
+    ```
+
+### 🫛 podium: helps you work with pods
+- get pod status
+    ```ts
+    podium.status(["ready", 123])
+      // "ready"
+    ```
+- get pod ready value (or undefined)
+    ```ts
+    podium.value(["loading"])
+      // undefined
+
+    podium.value(["ready", 123])
+      // 123
+    ```
+- see more at [podium.ts](./s/ops/podium.ts)
+
+### 🫛 ops: nice pod ergonomics
+- an `Op<V>` wraps a pod with a signal for reactivity
+- create an op
+    ```ts
+    const op = new Op<number>() // loading status by default
+    ```
+    ```ts
+    const op = Op.loading<number>()
+    ```
+    ```ts
+    const op = Op.ready<number>(123)
+    ```
+    ```ts
+    const op = Op.error<number>(new Error())
+    ```
+- 🔥 create an op that calls and tracks an async fn
+    ```ts
+    const op = Op.fn(async() => {
+      await nap(4000)
+      return 123
+    })
+    ```
+- await for the next ready value (or thrown error)
+    ```ts
+    await op // 123
+    ```
+- get pod info
+    ```ts
+    op.status // "loading"
+    op.pod // ["loading"]
+    op.value // undefined (or value if ready)
+    ```
+    ```ts
+    op.isLoading // true
+    op.isReady // false
+    op.isError // false
+    ```
+- select executes a fn based on the status
+    ```ts
+    const result = op.select({
+      loading: () => "it's loading...",
+      ready: value => `dude, it's ready! ${value}`,
+      error: err => `dude, there's an error!`,
+    })
+
+    result
+      // "dude, it's ready! 123"
+    ```
+- morph returns a new pod, transforming the value if ready
+    ```ts
+    op.morph(n => n + 1)
+      // ["ready", 124]
+    ```
+- you can combine a number of ops into a single pod like this
+    ```ts
+    Op.all(Op.ready(123), Op.loading())
+      // ["loading"]
+    ```
+    ```ts
+    Op.all(Op.ready(1), Op.ready(2), Op.ready(3))
+      // ["ready", [1, 2, 3]]
+    ```
+    - error if any ops are in error, otherwise
+    - loading if any ops are in loading, otherwise
+    - ready if all the ops are ready
+
+### 🫛 loaders: animated loading spinners
+- create a `loader` using `makeLoader`
+    ```ts
+    const loader = makeLoader(anims.dots)
+    ```
+    - see all the anims available on the testing page https://sly.e280.org/
+- use the loader to render your op
+    ```ts
+    return html`
+      <h2>cool stuff</h2>
+
+      ${loader(op, value => html`
+        <div>${value}</div>
+      `)}
+    `
+    ```
+    - when the op is loading, the loading spinner will animate
+    - 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/>
 

package/package.json

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

package/s/demo/demo.bundle.ts

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

package/s/demo/views/counter.ts

@@ -2,8 +2,8 @@
 import {css, html} from "lit"
 import {repeat} from "@e280/stz"
 
-import {view} from "../../features/views/view.js"
-import {cssReset} from "../../features/views/css-reset.js"
+import {view} from "../../views/view.js"
+import {cssReset} from "../../views/css-reset.js"
 
 export const CounterView = view(use => (initial: number) => {
 	use.name("counter")

package/s/demo/views/demo.ts

@@ -1,9 +1,9 @@
 
 import {css, html} from "lit"
+import {view} from "../../views/view.js"
 import {CounterView} from "./counter.js"
 import {LoadersView} from "./loaders.js"
-import {view} from "../../features/views/view.js"
-import {cssReset} from "../../features/views/css-reset.js"
+import {cssReset} from "../../views/css-reset.js"
 
 export const DemoView = view(use => () => {
 	use.name("demo")

package/s/demo/views/loaders.ts

@@ -1,9 +1,9 @@
 
 import {css, html} from "lit"
-import {Op} from "../../features/op/op.js"
-import {view} from "../../features/views/view.js"
-import {cssReset} from "../../features/views/css-reset.js"
-import {anims, makeLoader} from "../../features/op/loaders/make-loader.js"
+import {Op} from "../../ops/op.js"
+import {view} from "../../views/view.js"
+import {cssReset} from "../../views/css-reset.js"
+import {anims, makeLoader} from "../../ops/loaders/make-loader.js"
 
 export const LoadersView = view(use => () => {
 	use.name("loaders")

package/s/index.ts

@@ -1,19 +1,20 @@
 
-export * from "./features/dom/dashify.js"
-export * from "./features/dom/dollar.js"
-export * from "./features/dom/register.js"
-export * from "./features/dom/types.js"
+export * from "./dom/dashify.js"
+export * from "./dom/dollar.js"
+export * from "./dom/register.js"
+export * from "./dom/types.js"
 
-export * from "./features/op/loaders/make-loader.js"
-export * from "./features/op/loaders/parts/ascii-anim.js"
-export * from "./features/op/loaders/parts/error-display.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 "./features/op/op.js"
-export * from "./features/op/podium.js"
-export * from "./features/op/types.js"
+export * from "./ops/op.js"
+export * from "./ops/podium.js"
+export * from "./ops/types.js"
 
-export * from "./features/views/css-reset.js"
-export * from "./features/views/types.js"
-export * from "./features/views/use.js"
-export * from "./features/views/view.js"
+export * from "./views/attributes.js"
+export * from "./views/css-reset.js"
+export * from "./views/types.js"
+export * from "./views/use.js"
+export * from "./views/view.js"
 

package/s/{features/op → ops}/op.ts

@@ -22,11 +22,11 @@ export class Op<V> {
 
 	static all<V>(...ops: Op<V>[]) {
 		const pods = ops.map(op => op.pod)
-		const pod = podium.all(...pods)
-		return new this(pod)
+		return podium.all(...pods)
 	}
 
 	readonly signal: Signal<Pod<V>>
+	#count = 0
 	#resolve = pub<[V]>()
 	#reject = pub<[any]>()
 
@@ -35,12 +35,16 @@ export class Op<V> {
 	}
 
 	get wait() {
-		return new Promise((resolve, reject) => {
-			this.#resolve.next().then(resolve)
-			this.#reject.next().then(reject)
+		return new Promise<V>((resolve, reject) => {
+			this.#resolve.next().then(([v]) => resolve(v))
+			this.#reject.next().then(([e]) => reject(e))
 		})
 	}
 
+	get then() { return this.wait.then.bind(this.wait) }
+	get catch() { return this.wait.catch.bind(this.wait) }
+	get finally() { return this.wait.finally.bind(this.wait) }
+
 	async setLoading() {
 		await this.signal(["loading"])
 	}
@@ -56,14 +60,17 @@ export class Op<V> {
 	}
 
 	async promise(promise: Promise<V>) {
+		const count = ++this.#count
 		await this.setLoading()
 		try {
 			const value = await promise
-			await this.setReady(value)
+			if (count === this.#count)
+				await this.setReady(value)
 			return value
 		}
 		catch (error) {
-			await this.setError(error)
+			if (count === this.#count)
+				await this.setError(error)
 		}
 	}
 
@@ -114,7 +121,7 @@ export class Op<V> {
 	}
 
 	morph<V2>(fn: (value: V) => V2) {
-		return new Op(podium.morph(this.pod, fn))
+		return podium.morph(this.pod, fn)
 	}
 }