@e280/sly 0.0.0-6 → 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,56 +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.
+
+```ts
+view(use => () => "hello world")
+```
 
-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.
+views are not web components.
 
-sly views are wired to automatically rerender whenever they're using any state stuff from [@e280/strata](https://github.com/e280/strata).
+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.
 
-### 🍋 basic 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**
+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
+- **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) => {
@@ -79,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")
@@ -110,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
@@ -134,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(() => {
@@ -142,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.attrs** — ergonomic typed html attribute access
+    ```ts
+    const attrs = use.attrs({
+      name: String,
+      count: Number,
+      active: Boolean,
+    })
     ```
-- **use.render** — force a hard render (not debounced)
+    ```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
     })
@@ -167,7 +235,7 @@ sly views are wired to automatically rerender whenever they're using any state s
     const op = use.op.promise(doAsyncWork())
     ```
 
-### 🍋 neat tricks to impress the ladies
+### 🍋 view "use" recipes
 - make a ticker — mount, repeat, and nap
     ```ts
     import {repeat, nap} from "@e280/stz"
@@ -180,23 +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 `$` DOM MULTITOOL
+
+### 💲 follow the money
+- import the dollarsign
+    ```ts
+    import {$} from "@e280/sly"
+    ```
+
+### 💲 dom queries
+- require an element
+    ```ts
+    $(".demo")
+      // HTMLElement (or throws error)
+    ```
+- request an element
+    ```ts
+    $.maybe(".demo")
+      // HTMLElement | undefined
+    ```
+- query all elements
+    ```ts
+    for (const item of $.all("ul li"))
+      console.log(item)
+    ```
+- specify what element to query under
+    ```ts
+    $("li", listElement)
+      // HTMLElement
+    ```
+
+### 💲 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>
+    ```
+
+<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-6",
+	"version": "0.0.0-8",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",

package/s/demo/demo.bundle.ts

@@ -1,8 +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)})
 
 console.log("🦝 sly")
 

package/s/demo/views/counter.ts

@@ -2,10 +2,10 @@
 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 => () => {
+export const CounterView = view(use => (initial: number) => {
 	use.name("counter")
 	use.styles(cssReset, styles)
 
@@ -17,10 +17,11 @@ export const CounterView = view(use => () => {
 		seconds(Math.floor(since / 1000))
 	}))
 
-	const count = use.signal(0)
+	const count = use.signal(initial)
 	const increment = () => count(count() + 1)
 
 	return html`
+		<slot></slot>
 		<div>
 			<span>${seconds()}</span>
 		</div>
@@ -34,9 +35,12 @@ export const CounterView = view(use => () => {
 const styles = css`
 :host {
 	display: flex;
-	flex-direction: column;
 	justify-content: center;
-	text-align: center;
+	gap: 1em;
+}
+
+button {
+	padding: 0.2em 0.5em;
 }
 `
 

package/s/demo/views/demo.ts

@@ -1,16 +1,16 @@
 
 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")
 	use.styles(cssReset, styles)
 
 	return html`
-		${CounterView()}
+		${CounterView.children("view")(2)}
 		${LoadersView()}
 	`
 })

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/{features/dom → dom}/dollar.ts

@@ -1,5 +1,6 @@
 
 import {render} from "lit"
+import {register} from "./register.js"
 import {Content} from "../views/types.js"
 
 export type Container = HTMLElement | ShadowRoot | DocumentFragment
@@ -22,4 +23,5 @@ $.maybe = <E extends HTMLElement = HTMLElement>(selector: string, context: Query
 $.all = all
 
 $.render = (container: Container, ...content: Content[]) => render(content, container)
+$.register = register
 

package/s/index.html.ts

@@ -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>
+		<demo-counter>component</demo-counter>
 		<div class=demo></div>
 	`,
 }))

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)
 	}
 }