@e280/sly 0.0.0-3 → 0.0.0-5

package/README.md

@@ -1,8 +1,10 @@
 
 <div align="center"><img alt="" width="256" src="./assets/favicon.png"/></div>
 
-# 🦝 sly — mischievious frontend web framework
-- 🪒 lean view framework for [lit](https://lit.dev/)
+# 🦝 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)
@@ -11,8 +13,7 @@
 
 <br/>
 
-## 🦝 INSTALL SLY AND PEERS
-they all super work together.
+## 🦝 INSTALL SLY AND PALS
 
 ```sh
 npm install @e280/sly @e280/stz @e280/strata lit
@@ -20,50 +21,90 @@ npm install @e280/sly @e280/stz @e280/strata lit
 
 <br/>
 
-## 🦝 VIEWS ARE LEAN
+## 🦝 SLY VIEWS
 views are the crown jewel of sly. shadow-dom'd. hooks-based. fancy ergonomics. not components.
 
-views are leaner than web components.. no dom registration, 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 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.
 
 sly views are wired to automatically rerender whenever they're using any state stuff from [@e280/strata](https://github.com/e280/strata).
 
 ### 🍋 basic view example
-> views are hooks-based functional components. they are *not* web components nor *custom elements*, yet they are encapsulated within a [shadow root](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM).
-
-#### declaring a view
-```ts
-import {view} from "@e280/sly"
-import {html, css} from "lit"
-
-export const CounterView = view(use => (start: number) => {
-  use.name("counter")
-  use.styles(css`p {color: green}`)
-  const count = use.signal(start)
-
-  return html`
-    <p>count ${count()}</p>
-    <button @click="${() => { count.value++ }}"></button>
-  `
-})
-```
-- each view renders into a `<sly-view>` host, with the provided `name` set as its view attribute, eg `<sly-view view="counter">`
+- 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**
+    ```ts
+    import {view} from "@e280/sly"
+    import {html, css} from "lit"
+
+    export const CounterView = view(use => (start: number) => {
+      use.name("counter")
+      use.styles(css`p {color: green}`)
+      const count = use.signal(start)
+
+      return html`
+        <p>count ${count()}</p>
+        <button @click="${() => { count.value++ }}"></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**
+    ```ts
+    import {render, html} from "lit"
+    import {CounterView} from "./my-counter.js"
 
-#### injecting a view into the dom
-```ts
-import {render, html} from "lit"
-import {CounterView} from "./my-counter.js"
+    const content = html`
+      <h1>my demo page</h1>
+      ${CounterView(1)}
+    `
 
-const content = html`
-  <h1>my demo page</h1>
-  ${CounterView(1)}
-`
+    render(content, document.querySelector(".app")!)
+    ```
 
-render(content, document.body)
-```
+### 🍋 view declaration settings
+- special settings for views at declaration-time
+    ```ts
+    import {view} from "@e280/sly"
+    import {html} from "lit"
 
-### 🍋 view `use`
-> super special view helper, with hooks and other goodies
+    export const CoolView = view
+      .settings({mode: "open", delegatesFocus: true})
+      .view(use => (greeting: string) => {
+
+      return html`😎 ${greeting} <slot></slot>`
+    })
+    ```
+    - these `settings` like `mode` and `delegatesFocus` are [attachShadow params](https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#parameters)
+    - note the `<slot></slot>` we'll use in the next example lol
 
+### 🍋 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`
+      <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
+- **use.name** — set the "view" attr value, eg `<sly-view view="squarepants">`
+    ```ts
+    use.name("squarepants")
+    ```
+- **use.styles** — attach stylesheets into the view's shadow dom
+    ```ts
+    use.styles(css1, css2, css3)
+    ```
 - **use.signal** — create a [strata signal](https://github.com/e280/strata)
     ```ts
     const count = use.signal(1)
@@ -93,25 +134,40 @@ render(content, document.body)
       }
     })
     ```
-- **use.name** — set the "view" attr value, eg `<sly-view view="squarepants">`
+- **use.life** — mount/unmount lifecycle, but also return a value
     ```ts
-    use.name("squarepants")
+    const v = use.life(() => {
+      console.log("mounted")
+      const value = 123
+      return [value, () => console.log("unmounted")]
+    })
+
+    v //-> 123
     ```
-- **use.styles** — attach stylesheets into the view's shadow dom
+- **use.render** — force a hard render (not debounced)
     ```ts
-    use.styles(css1, css2, css3)
+    use.render()
     ```
-- **use.rendered** — promise that resolves *after* view has rendered
+- **use.rendered** — promise that resolves *after* the next render
     ```ts
     use.rendered.then(() => {
       const slot = use.shadow.querySelector("slot")!
       console.log(slot)
     })
     ```
+- **use.op.fn** — start with an op based on an async fn
+    ```ts
+    const op = use.op.fn(async() => {
+      await nap(5000)
+      return 123
+    })
+    ```
+- **use.op.promise** — start with an op based on a promise
+    ```ts
+    const op = use.op.promise(doAsyncWork())
+    ```
 
 ### 🍋 neat tricks to impress the ladies
-> common patterns and snippets
-
 - make a ticker — mount, repeat, and nap
     ```ts
     import {repeat, nap} from "@e280/stz"
@@ -131,55 +187,20 @@ render(content, document.body)
     }))
     ```
 
-### 🍋 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) => {
-
-  return html`😎 ${greeting} <slot></slot>`
-})
-```
-- these `settings` like `mode` and `delegatesFocus` are [attachShadow params](https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#parameters)
-- note the `<slot></slot>` we'll use in the next example lol
-
-### 🍋 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`
-  <h2>super cool example</h2>
-  ${CoolView
-    .attr("class", "hero")
-    .children(html`<em>spongebob</em>`)
-    .props("hello")}
-`
-
-render(content, document.body)
-```
-- `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
-
 <br/>
 
-## 🦝 OPS LOADING INDICATORS
-> ***TODO*** *implemented but not yet documented, lol*
-- `Pod` is a type for (loading/ready/error states)
+## 🦝 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
-- `loady` has various loading indicators for dealing with ops
+- `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
 
 <br/>
 
-## 🧑‍💻 PROJECT BY e280
+## 🧑‍💻 SLY BY E280
 reward us with github stars  
 build with us at https://e280.org/ but only if you're cool  
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@e280/sly",
-	"version": "0.0.0-3",
+	"version": "0.0.0-5",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",
@@ -13,8 +13,8 @@
 		"s"
 	],
 	"peerDependencies": {
-		"@e280/stz": "^0.0.0-35",
 		"@e280/strata": "^0.0.0-10",
+		"@e280/stz": "^0.0.0-36",
 		"lit": "^3.3.1"
 	},
 	"devDependencies": {
@@ -26,7 +26,7 @@
 	},
 	"scripts": {
 		"build": "run-s _clean _ln _tsc _scute",
-		"watch": "octo 'scute -vw' 'tsc -w' 'node --watch x/tests.test.js' 'http-server x'",
+		"start": "octo 'scute -vw' 'tsc -w' 'node --watch x/tests.test.js' 'http-server x'",
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +",
 		"test": "node x/tests.test.js",
 		"test-inspect": "node inspect x/tests.test.js",

package/s/demo/demo.bundle.ts

@@ -1,52 +1,8 @@
 
-import {nap, repeat} from "@e280/stz"
-import {css, html, render} from "lit"
-
+import {DemoView} from "./views/demo.js"
 import {$} from "../features/dom/dollar.js"
-import {view} from "../features/views/view.js"
-import {cssReset} from "../features/views/css-reset.js"
-import {loady} from "../features/loady/ascii-loader.js"
-
-console.log("🦝 sly")
-
-const styles = css`
-:host {
-	display: flex;
-	flex-direction: column;
-	justify-content: center;
-	text-align: center;
-}
-`
-
-const MyView = view(use => (greeting: string) => {
-	use.name("my-view")
-	use.styles(cssReset, styles)
-	const count = use.signal(0)
 
-	use.mount(() => repeat(async() => {
-		await nap(1000)
-		count.value++
-	}))
+$.render($(".demo"), DemoView())
 
-	use.once(() => use.rendered.then(() => {
-		console.log("slot", $("slot", use.shadow))
-	}))
-
-	const op = use.op.fn(async() => {
-		await nap(5000)
-	})
-
-	return html`
-		<p>${greeting} <slot></slot> ${count()}</p>
-		<p>${loady.dots(op, () => "op loaded")}</p>
-	`
-})
-
-render(
-	MyView
-		.attr("class", "incredi")
-		.children("world")
-		.props("hello"),
-	$(".demo"),
-)
+console.log("🦝 sly")
 

package/s/demo/demo.css

@@ -5,6 +5,7 @@
 	:root {
 		--prime: #1eff00;
 		--accent: #387d42;
+		--pill: #12763959;
 		--bg: #0e2316;
 		--link: cyan;
 	}
@@ -51,15 +52,12 @@
 
 @layer page {
 	:root {
-		color-scheme: dark;
-
-		padding: 5vw 0.5em;
-		min-height: 100%;
-		scrollbar-gutter: stable;
-
 		font-size: 21px;
 		font-family: sans-serif;
 
+		color-scheme: dark;
+		scrollbar-gutter: stable;
+
 		color: color-mix(in lch, var(--prime), #fff8 50%);
 		background: radial-gradient(
 			circle,
@@ -69,6 +67,11 @@
 	}
 
 	body {
+		width: 100%;
+		max-width: 32em;
+		margin: auto;
+		padding: 1em;
+
 		display: flex;
 		flex-direction: column;
 		align-items: center;
@@ -88,6 +91,10 @@
 		font-size: 0.8em;
 	}
 
+	.demo {
+		width: 100%;
+	}
+
 	:not(:defined) {
 		display: none;
 	}

package/s/demo/views/counter.ts

@@ -0,0 +1,42 @@
+
+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"
+
+export const CounterView = view(use => () => {
+	use.name("counter")
+	use.styles(cssReset, styles)
+
+	const start = use.once(() => Date.now())
+	const seconds = use.signal(0)
+
+	use.mount(() => repeat(async() => {
+		const since = Date.now() - start
+		seconds(Math.floor(since / 1000))
+	}))
+
+	const count = use.signal(0)
+	const increment = () => count(count() + 1)
+
+	return html`
+		<div>
+			<span>${seconds()}</span>
+		</div>
+		<div>
+			<span>${count()}</span>
+			<button @click="${increment}">+</button>
+		</div>
+	`
+})
+
+const styles = css`
+:host {
+	display: flex;
+	flex-direction: column;
+	justify-content: center;
+	text-align: center;
+}
+`
+

package/s/demo/views/demo.ts

@@ -0,0 +1,25 @@
+
+import {css, html} from "lit"
+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"
+
+export const DemoView = view(use => () => {
+	use.name("demo")
+	use.styles(cssReset, styles)
+
+	return html`
+		${CounterView()}
+		${LoadersView()}
+	`
+})
+
+const styles = css`
+:host {
+	display: flex;
+	flex-direction: column;
+	gap: 1em;
+}
+`
+

package/s/demo/views/loaders.ts

@@ -0,0 +1,58 @@
+
+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"
+
+export const LoadersView = view(use => () => {
+	use.name("loaders")
+	use.styles(cssReset, styles)
+
+	const op = use.once(() => Op.loading())
+
+	const loaders = use.once(() =>
+		Object.entries(anims).map(([key, anim]) => ({
+			key,
+			loader: makeLoader(anim)
+		}))
+	)
+
+	return loaders.map(({key, loader}) => html`
+		<div data-anim="${key}">
+			<span>${key}</span>
+			<span>${loader(op, () => null)}</span>
+		</div>
+	`)
+})
+
+const styles = css`
+:host {
+	display: flex;
+	flex-direction: row;
+	justify-content: center;
+	flex-wrap: wrap;
+
+	gap: 0.2em;
+	padding: 1em;
+
+	width: 100%;
+}
+
+div {
+	font-family: monospace;
+
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: 0.4em;
+
+	padding: 0.2em 0.5em;
+	background: var(--pill);
+	border-radius: 0.5em;
+
+	span:nth-child(1) { font-size: 0.6em; }
+	span:nth-child(2) { font-size: 1.2em; }
+}
+`
+

package/s/features/dom/dollar.ts

@@ -1,21 +1,25 @@
 
-export const $ = one
+import {render} from "lit"
+import {Content} from "../views/types.js"
 
-export type Queryable = HTMLElement | Document | ShadowRoot | Element
+export type Container = HTMLElement | ShadowRoot | DocumentFragment
+export type Queryable = HTMLElement | ShadowRoot | Element | Document | DocumentFragment
 
-function all<E extends HTMLElement = HTMLElement>(selector: string, context: Queryable = document) {
-	return Array.from(context.querySelectorAll<E>(selector))
-}
-
-function one<E extends HTMLElement = HTMLElement>(selector: string, context: Queryable = document) {
+export function $<E extends HTMLElement = HTMLElement>(selector: string, context: Queryable = document) {
 	const e = context.querySelector<E>(selector)
 	if (!e) throw new Error(`$1 ${selector} not found`)
 	return e
 }
 
-one.maybe = <E extends HTMLElement = HTMLElement>(selector: string, context: Queryable = document) => {
+function all<E extends HTMLElement = HTMLElement>(selector: string, context: Queryable = document) {
+	return Array.from(context.querySelectorAll<E>(selector))
+}
+
+$.maybe = <E extends HTMLElement = HTMLElement>(selector: string, context: Queryable = document) => {
 	return context.querySelector<E>(selector)
 }
 
-one.all = all
+$.all = all
+
+$.render = (container: Container, ...content: Content[]) => render(content, container)
 

package/s/features/op/loaders/make-loader.ts

@@ -0,0 +1,18 @@
+
+import {Op} from "../op.js"
+import {braille} from "./parts/anims.js"
+import {Content} from "../../views/types.js"
+import {ErrorDisplay} from "./parts/error-display.js"
+
+export * as anims from "./parts/anims.js"
+
+export type Loader = <V>(op: Op<V>, ready: (value: V) => Content) => Content
+
+export function makeLoader(
+		loading: () => Content = braille,
+		error: (error: any) => Content = (error: any) => ErrorDisplay(error),
+	): Loader {
+
+	return (op, ready) => op.select({loading, ready, error})
+}
+