@e280/sly 0.3.0-1 → 0.3.0-3

package/README.md

@@ -2,33 +2,34 @@
 <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) — hooks-based, shadow-dom'd, template-literal'd
-- 🪝 [**#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
 
 
 
 <br/><br/>
 <a id="views"></a>
 
-## 🍋 views
-> *modern views.. in lightness, or darkness..*  
+## 🎭 views
+> *"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** — declarative rendering with [modern hooks](#hooks) familiar to react devs
+- 🌗 **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"
@@ -40,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
@@ -58,14 +59,15 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
     ```
 - **render it into the dom**
     ```ts
-    dom.in(".demo").render(html`
+    dom.render(dom(".demo"), html`
       <h1>my cool counter demo</h1>
       ${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
@@ -80,21 +82,21 @@ 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>
       `
     })
     ```
 - **render it into the dom**
     ```ts
-    dom.in(".demo").render(html`
+    dom.render(dom(".demo"), html`
       <h1>my cool counter demo</h1>
       ${MyShadowCounter(234)}
     `)
     ```
 - **.with to nest children or set attrs**
     ```ts
-    dom.in(".demo").render(html`
+    dom.render(dom(".demo"), html`
       <h1>my cool counter demo</h1>
 
       ${MyShadowCounter.with({
@@ -106,14 +108,17 @@ export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)
       })}
     `)
     ```
-- **oh, you can do custom shadow config if needed**
+- **you can do custom shadow config if needed**
     ```ts
-    const MyCustomShadow = 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
 
 
 
@@ -121,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)
 
@@ -173,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")
@@ -187,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")
@@ -203,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")
@@ -213,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"
     ```
@@ -250,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")
     }))
     ```
@@ -261,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"
@@ -299,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
@@ -338,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
@@ -370,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"
@@ -527,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"
@@ -661,10 +667,10 @@ import {dom} from "@e280/sly"
     ```
     or if you wanna be more loosey-goosey, skip the spec
     ```ts
-    const a = dom.in(".demo").attrs
-    a.strings.name = "pimsley"
-    a.numbers.count = 125
-    a.booleans.active = true
+    const {attrs} = dom.in(".demo")
+    attrs.strings.name = "pimsley"
+    attrs.numbers.count = 125
+    attrs.booleans.active = true
     ```
 
 

package/package.json

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

package/s/demo/demo.bundle.ts

@@ -2,6 +2,6 @@
 import {dom} from "../dom/dom.js"
 import {Demo} from "./views/demo.js"
 
-dom.in(".demo").render(Demo())
+dom.render(dom(".demo"), Demo())
 console.log("🦝 sly")
 

package/s/dom/dom.ts

@@ -11,7 +11,7 @@ import {register} from "./parts/register.js"
 import {Queryable, Renderable} from "./types.js"
 import {queryAll, queryMaybe, queryRequire} from "./parts/queries.js"
 
-export function dom<E extends Element>(selector: string, container: Queryable = document): E {
+export function dom<E extends HTMLElement>(selector: string, container: Queryable = document) {
 	return queryRequire<E>(selector, container)
 }
 

package/s/view/shadow.ts

@@ -28,7 +28,7 @@ shadow.config = (setupFn: () => ShadowSetup) => (
 	)
 )
 
-export function rawShadow<Props extends any[]>(
+function rawShadow<Props extends any[]>(
 		setup: () => ShadowSetup,
 		view: View<Props>,
 	) {

package/x/demo/demo.bundle.js

@@ -1,5 +1,5 @@
 import { dom } from "../dom/dom.js";
 import { Demo } from "./views/demo.js";
-dom.in(".demo").render(Demo());
+dom.render(dom(".demo"), Demo());
 console.log("🦝 sly");
 //# sourceMappingURL=demo.bundle.js.map

package/x/demo/demo.bundle.js.map

@@ -1 +1 @@
-{"version":3,"file":"demo.bundle.js","sourceRoot":"","sources":["../../s/demo/demo.bundle.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,GAAG,EAAC,MAAM,eAAe,CAAA;AACjC,OAAO,EAAC,IAAI,EAAC,MAAM,iBAAiB,CAAA;AAEpC,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;AAC9B,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA"}
+{"version":3,"file":"demo.bundle.js","sourceRoot":"","sources":["../../s/demo/demo.bundle.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,GAAG,EAAC,MAAM,eAAe,CAAA;AACjC,OAAO,EAAC,IAAI,EAAC,MAAM,iBAAiB,CAAA;AAEpC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;AAChC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA"}

package/x/demo/demo.bundle.min.js

@@ -90,7 +90,7 @@ div {
 		align-items: center;
 		gap: 1em;
 	}
-`;y.in(".demo").render(Ye());console.log("\u{1F99D} sly");
+`;y.render(y(".demo"),Ye());console.log("\u{1F99D} sly");
 /*! Bundled license information:
 
 @lit/reactive-element/css-tag.js: