@e280/sly 0.3.0-2 → 0.3.0-4

package/README.md

@@ -2,21 +2,20 @@
 <div align="center"><img alt="" width="256" src="./assets/favicon.png"/></div>
 
 # 🦝 sly
-> *mischievous shadow views*
 
 ```sh
 npm install lit @e280/sly @e280/strata @e280/stz
 ```
 
-[@e280](https://e280.org/)'s new [lit](https://lit.dev/)-based frontend webdev library.
+#### [@e280](https://e280.org/)'s [lit-based](https://lit.dev/) web library for reactive light or shadow views
 
-- 🎭 [**#views**](#views) — light-dom or shadow-dom reactive lit views
-- 🪝 [**#hooks**](#hooks) — full reference of available view hooks
-- 🫛 [**#ops**](#ops) — reactive tooling for async operations
-- ⏳ [**#loaders**](#loaders) — animated loading spinners for rendering ops
-- 🪙 [**#loot**](#loot) — drag-and-drop facilities
-- 🪄 [**#dom**](#dom) — the "it's not jquery" multitool
-- 🧪 https://sly.e280.org/ — our testing page
+- 🎭 [**#views,**](#views) reactive lit views, light-dom or shadow-dom
+- 🪝 [**#hooks,**](#hooks) react-like composable hooks
+- 🫛 [**#ops,**](#ops) tooling for async operations ui
+- ⏳ [**#loaders,**](#loaders) render ops with animated loading spinners
+- 🪙 [**#loot,**](#loot) drag-and-drop facilities
+- 🪄 [**#dom,**](#dom) the "it's not jquery" multitool
+- 🧪 **https://sly.e280.org/** sly's testing page
 
 
 
@@ -24,12 +23,13 @@ npm install lit @e280/sly @e280/strata @e280/stz
 <a id="views"></a>
 
 ## 🎭 views
-> *reactive views, light or shadow*  
+> *"flourish in the light.. or thrive in the darkness"*
 
-- 🪶 **no compile step** — just god's honest javascript, via [lit](https://lit.dev/)-html tagged-template-literals
-- ⚡ **reactive** — views auto-rerender whenever any [strata](https://github.com/e280/strata)-compatible state changes
-- 🪝 **hooks-based** — familiar react-style [hooks](#hooks)
-- 🌗 **light or shadow** — render directly in the dom, or inside a shadow-dom bubble
+- 🌗 **light or shadow,** render nakedly on the page, or within a cozy shadow bubble
+- 🪝 **hooks-based,** familiar react-style [hooks](#hooks)
+- ⚡ **auto-reactive,** views magically rerender on [strata](https://github.com/e280/strata)-compatible state changes
+- 🪶 **no compile step,** just god's honest javascript via [lit](https://lit.dev/)-html tagged-template-literals
+- 🧩 **not web components,** no dom registration needed, just vibes and good typings
 
 ```ts
 import {html} from "lit"
@@ -41,7 +41,7 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
 ```
 
 ### 🌞 light views
-> *just pretend it's react*
+> *"just pretend it's react, without jsx"*
 
 - **define a light view**
     ```ts
@@ -64,9 +64,15 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
       ${MyCounter(123)}
     `)
     ```
+    - light views have no host element, rendered output looks like:
+        ```html
+        <h1>my cool counter demo</h1>
+        <button>123</button>
+        ```
+- **light views are naked,** they don't have a containing host element
 
 ### 🌚 shadow views
-> *each shadow view gets its own cozy [shadow-dom](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) bubble and supports [slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots)*
+> *each shadow view gets its own cozy [shadow-dom](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) bubble and supports [slotting](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots)*
 
 - **define a shadow view**
     ```ts
@@ -74,14 +80,14 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
     import {shadow, useName, useCss, useSignal} from "@e280/sly"
 
     export const MyShadowCounter = shadow((start: number) => {
-      useName("shadow-counter")
+      useName("counter")
       useCss(css`button { color: cyan }`)
 
       const $count = useSignal(start)
       const increment = () => $count.value++
 
       return html`
-        <button @click="${increment}">${$count()}</button>
+        <button @click="${increment}">${$count.value}</button>
         <slot></slot>
       `
     })
@@ -93,6 +99,11 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
       ${MyShadowCounter(234)}
     `)
     ```
+    - shadow views have a host element, rendered output looks like:
+        ```html
+        <h1>my cool counter demo</h1>
+        <sly-shadow view="counter"></sly-shadow>
+        ```
 - **.with to nest children or set attrs**
     ```ts
     dom.render(dom(".demo"), html`
@@ -107,13 +118,18 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
       })}
     `)
     ```
-- **you can do custom shadow config if needed**
+- **you can do custom shadow config if needed** (default shown)
     ```ts
-    const MyShadowView = shadow.config(() => {
-      const host = document.createElement("div")
+    import {SlyShadow} from "@e280/sly"
+
+    const customShadow = shadow.config(() => {
+      SlyShadow.register()
+      const host = document.createElement("sly-shadow")
       const shadow = host.attachShadow({mode: "open"})
       return {host, shadow}
-    })(() => html`<p>shrouded in darkness</p>`)
+    })
+
+    const MyShadowView = customShadow(() => html`<p>shrouded in darkness</p>`)
     ```
 
 
@@ -122,48 +138,48 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
 <a id="hooks"></a>
 
 ## 🪝 hooks
-> *composable view state and utilities*  
+> *composable view state and utilities*
 
 ### 👮 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.
+just like [react hooks](https://react.dev/warnings/invalid-hook-call-warning), the execution order of hooks seriously 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..*
+you must not call these hooks under if-conditionals, or for-loops, or inside callback functions, or after a conditional return statement, or anything like that.. *otherwise, heed my warning: weird bad stuff will happen..*
 
 ### 🌚 shadow-only hooks
-- **useName** — *(shadow only)* — set the "view" attribute value
+- **useName,** set the "view" attribute value
     ```ts
     useName("squarepants")
       // <sly-shadow view="squarepants">
     ```
-- **useCss** — *(shadow only)*  — attach stylesheets (use lit's `css`!) to the shadow root
+- **useCss,** attach stylesheets (use lit's `css`!) to the shadow root
     ```ts
     useCss(css1, css2, css3)
     ```
-- **useHost** — *(shadow only)*  — get the host element
+- **useHost,** get the host element
     ```ts
     const host = useHost()
     ```
-- **useShadow** — *(shadow only)*  — get the shadow root
+- **useShadow,** get the shadow root
     ```ts
     const shadow = useShadow()
     ```
 
 ### 🌞 universal hooks
-- **useState** — react-like hook to create some reactive state (we prefer signals)
+- **useState,** react-like hook to create some reactive state (we prefer signals)
     ```ts
     const [count, setCount] = useState(0)
 
     const increment = () => setCount(n => n + 1)
     ```
-- **useRef** — react-like hook to make a non-reactive box for a value
+- **useRef,** react-like hook to make a non-reactive box for a value
     ```ts
     const ref = useRef(0)
 
     ref.current // 0
     ref.current = 1 // does not trigger rerender
     ```
-- **useSignal** — create a [strata](https://github.com/e280/strata) signal
+- **useSignal,** create a [strata](https://github.com/e280/strata) signal
     ```ts
     const $count = useSignal(1)
 
@@ -173,13 +189,11 @@ you must not call these hooks under `if` conditionals, or `for` loops, or in cal
     // write the signal
     $count(2)
     ```
-    - see [strata readme](https://github.com/e280/strata)
-- **useDerived** — create a [strata](https://github.com/e280/strata) derived signal
+- **useDerived,** create a [strata](https://github.com/e280/strata) derived signal
     ```ts
     const $product = useDerived(() => $count() * $whatever())
     ```
-    - see [strata readme](https://github.com/e280/strata)
-- **useOnce** — run fn at initialization, and return a value
+- **useOnce,** run fn at initialization, and return a value
     ```ts
     const whatever = useOnce(() => {
       console.log("happens one time")
@@ -188,14 +202,14 @@ you must not call these hooks under `if` conditionals, or `for` loops, or in cal
 
     whatever // 123
     ```
-- **useMount** — setup mount/unmount lifecycle
+- **useMount,** setup mount/unmount lifecycle
     ```ts
     useMount(() => {
       console.log("mounted")
       return () => console.log("unmounted")
     })
     ```
-- **useWake** — run fn each time mounted, and return value
+- **useWake,** run fn each time mounted, and return value
     ```ts
     const whatever = useWake(() => {
       console.log("mounted")
@@ -204,7 +218,7 @@ you must not call these hooks under `if` conditionals, or `for` loops, or in cal
 
     whatever // 123
     ```
-- **useLife** — mount/unmount lifecycle, but also return a value
+- **useLife,** mount/unmount lifecycle, but also return a value
     ```ts
     const whatever = useLife(() => {
       console.log("mounted")
@@ -214,30 +228,30 @@ you must not call these hooks under `if` conditionals, or `for` loops, or in cal
 
     whatever // 123
     ```
-- **useRender** — returns a fn to rerender the view (debounced)
+- **useRender,** returns a fn to rerender the view (debounced)
     ```ts
     const render = useRender()
 
     render().then(() => console.log("render done"))
     ```
-- **useRendered** — get a promise that resolves *after* the next render
+- **useRendered,** get a promise that resolves *after* the next render
     ```ts
     useRendered().then(() => console.log("rendered"))
     ```
-- **useOp** — start loading an op based on an async fn
+- **useOp,** start loading an op based on an async fn
     ```ts
     const op = useOp(async() => {
       await nap(5000)
       return 123
     })
     ```
-- **useOpPromise** — start loading an op based on a promise
+- **useOpPromise,** start loading an op based on a promise
     ```ts
     const op = useOpPromise(doAsyncWork())
     ```
 
 ### 🧑‍🍳 happy hooks recipes
-- make a ticker — mount, cycle, and nap
+- make a ticker, mount, cycle, and nap
     ```ts
     import {cycle, nap} from "@e280/stz"
     ```
@@ -251,7 +265,9 @@ you must not call these hooks under `if` conditionals, or `for` loops, or in cal
     ```
 - wake + rendered, to do something after each mount's first render
     ```ts
-    useWake(() => useRendered.then(() => {
+    const rendered = useRendered()
+
+    useWake(() => rendered.then(() => {
       console.log("after first render")
     }))
     ```
@@ -262,7 +278,7 @@ you must not call these hooks under `if` conditionals, or `for` loops, or in cal
 <a id="ops"></a>
 
 ## 🫛 ops
-> *tools for async operations and loading spinners*  
+> *helpers for async operations*
 
 ```ts
 import {nap} from "@e280/stz"
@@ -300,19 +316,19 @@ import {Pod, podium, Op, loaders} from "@e280/sly"
 - see more at [podium.ts](./s/ops/podium.ts)
 
 ### 🫛 ops: nice pod ergonomics
-- an `Op<V>` wraps a pod with a signal for reactivity
+- an `Op<V>` wraps a pod with a strata signal for reactivity
 - create an op
     ```ts
-    const op = new Op<number>() // loading status by default
+    new Op<number>() // loading status by default
     ```
     ```ts
-    const op = Op.loading<number>()
+    Op.loading<number>()
     ```
     ```ts
-    const op = Op.ready<number>(123)
+    Op.ready<number>(123)
     ```
     ```ts
-    const op = Op.error<number>(new Error())
+    Op.error<number>(new Error())
     ```
 - 🔥 create an op that calls and tracks an async fn
     ```ts
@@ -339,13 +355,12 @@ import {Pod, podium, Op, loaders} from "@e280/sly"
 - select executes a fn based on the status
     ```ts
     const result = op.select({
-      loading: () => "it's loading...",
+      loading: () => "still loading...",
       ready: value => `dude, it's ready! ${value}`,
-      error: err => `dude, there's an error!`,
+      error: err => `ack! an error!`,
     })
 
-    result
-      // "dude, it's ready! 123"
+    result // "dude, it's ready! 123"
     ```
 - morph returns a new pod, transforming the value if ready
     ```ts
@@ -371,7 +386,7 @@ import {Pod, podium, Op, loaders} from "@e280/sly"
 <a id="loaders"></a>
 
 ## ⏳ loaders
-> *animated loading spinners for ops*  
+> *animated loading spinners for ops*
 
 ```ts
 import {loaders} from "@e280/sly"
@@ -528,7 +543,7 @@ import {ev} from "@e280/stz"
 <a id="dom"></a>
 
 ## 🪄 dom
-> *the "it's not jquery!" multitool*  
+> *the "it's not jquery!" multitool*
 
 ```ts
 import {dom} from "@e280/sly"

package/package.json

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

package/s/view/{parts → common}/sly-shadow.ts

@@ -1,5 +1,11 @@
 
+import {dom} from "../../dom/dom.js"
+
 export class SlyShadow extends HTMLElement {
+	static register() {
+		dom.register({SlyShadow}, {soft: true})
+	}
+
 	connectedCallback() {
 		if (!this.hasAttribute("view"))
 			this.setAttribute("view", "")

package/s/view/index.ts

@@ -1,5 +1,6 @@
 
 export * from "./common/css-reset.js"
+export * from "./common/sly-shadow.js"
 
 export * from "./hooks/use-css.js"
 export * from "./hooks/use-cx.js"

package/s/view/shadow.ts

@@ -2,29 +2,29 @@
 import {microbounce} from "@e280/stz"
 import {render as litRender} from "lit"
 
-import {dom} from "../dom/dom.js"
 import {ShadowCx} from "./parts/cx.js"
-import {SlyShadow} from "./parts/sly-shadow.js"
 import {hooks} from "./hooks/plumbing/hooks.js"
+import {SlyShadow} from "./common/sly-shadow.js"
 import {Reactivity} from "./parts/reactivity.js"
 import {applyAttrs} from "./parts/apply-attrs.js"
 import {Hookscope} from "./hooks/plumbing/hookscope.js"
 import {View, Placement, ShadowSetup, ShadowView} from "./types.js"
 import {AsyncDirective, directive, PartInfo} from "lit/async-directive.js"
 
+export function shadowSetup(): ShadowSetup {
+	SlyShadow.register()
+	const host = document.createElement("sly-shadow")
+	const shadow = host.attachShadow({mode: "open"})
+	return {host, shadow}
+}
+
 export function shadow<Props extends any[]>(view: View<Props>) {
-	const setupFn = (): ShadowSetup => {
-		dom.register({SlyShadow}, {soft: true})
-		const host = document.createElement("sly-shadow")
-		const shadow = host.attachShadow({mode: "open"})
-		return {host, shadow}
-	}
-	return rawShadow(setupFn, view)
+	return rawShadow(shadowSetup, view)
 }
 
-shadow.config = (setupFn: () => ShadowSetup) => (
+shadow.setup = (setup: () => ShadowSetup) => (
 	<Props extends any[]>(view: View<Props>) => (
-		rawShadow(setupFn, view)
+		rawShadow(setup, view)
 	)
 )