@e280/sly 0.3.0-2 → 0.3.0-3

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,10 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
       ${MyCounter(123)}
     `)
     ```
+- **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
@@ -81,7 +82,7 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
       const increment = () => $count.value++
 
       return html`
-        <button @click="${increment}">${$count()}</button>
+        <button @click="${increment}">${$count.value}</button>
         <slot></slot>
       `
     })
@@ -109,12 +110,15 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
     ```
 - **you can do custom shadow config if needed**
     ```ts
-    const MyShadowView = shadow.config(() => {
+    const customShadow = shadow.config(() => {
       const host = document.createElement("div")
       const shadow = host.attachShadow({mode: "open"})
       return {host, shadow}
-    })(() => html`<p>shrouded in darkness</p>`)
+    })
+
+    const MyShadowView = customShadow(() => html`<p>shrouded in darkness</p>`)
     ```
+- **shadow views are rendered inside** a `<sly-shadow>` host element by default
 
 
 
@@ -122,48 +126,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)
 
@@ -174,12 +178,12 @@ you must not call these hooks under `if` conditionals, or `for` loops, or in cal
     $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 +192,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 +208,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 +218,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 +255,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 +268,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 +306,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 +345,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 +376,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 +533,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-3",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",

package/x/index.html

@@ -25,7 +25,7 @@
 		<img class=icon alt="" src="/assets/favicon.png"/>
 		<h1>sly testing page</h1>
 		<p><a href="https://github.com/e280/sly">github.com/e280/sly</a></p>
-		<p class=lil>v0.3.0-2</p>
+		<p class=lil>v0.3.0-3</p>
 		<div class="demo"></div>
 	</body>
 </html>