@e280/sly 0.0.0-1 → 0.0.0-2

package/README.md

@@ -1,7 +1,187 @@
 
-<div align="center"><img alt="" width="512" src="./assets/favicon.png"/></div>
+<div align="center"><img alt="" width="256" src="./assets/favicon.png"/></div>
 
-# 🦝 sly
+# 🦝 sly — mischievious frontend web framework
+- 🪒 lean view framework for [lit](https://lit.dev/)
+- 🌅 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)
+- 🧑‍💻 project by [@e280](https://e280.org/)
 
-> *wip — lit html shadow view library — will replace [`@benev/slate`](https://github.com/benevolent-games/slate)*
+<br/>
+
+## 📦 INSTALL SLY AND PEERS
+they all super work together.
+
+```sh
+npm install @e280/sly @e280/stz @e280/strata lit
+```
+
+<br/>
+
+## 🪟 VIEWS ARE LEAN
+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.
+
+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">`
+
+#### 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)}
+`
+
+render(content, document.body)
+```
+
+### 🍋 view `use`
+> super special view helper, with hooks and other goodies
+
+- **use.signal** — create a [strata signal](https://github.com/e280/strata)
+    ```ts
+    const count = use.signal(1)
+
+    // read the signal
+    count() //-> 1
+
+    // write the signal
+    count(2)
+    ```
+- **use.once** — run fn at initialization
+    ```ts
+    const whatever = use.once(() => {
+      console.log("happens only once")
+      return 123
+    })
+
+    whatever //-> 123
+    ```
+- **use.mount** — setup mount/unmount lifecycle
+    ```ts
+    use.mount(() => {
+      console.log("view mounted")
+
+      return () => {
+        console.log("view unmounted")
+      }
+    })
+    ```
+- **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.rendered** — promise that resolves *after* view has rendered
+    ```ts
+    use.rendered.then(() => {
+      const slot = use.shadow.querySelector("slot")!
+      console.log(slot)
+    })
+    ```
+
+### 🍋 neat tricks to impress the ladies
+> common patterns and snippets
+
+- make a ticker — mount, repeat, and nap
+    ```ts
+    import {repeat, nap} from "@e280/stz"
+    ```
+    ```ts
+    const seconds = use.signal(0)
+
+    use.mount(() => repeat(async() => {
+      await nap(1000)
+      seconds.value++
+    }))
+    ```
+- once+rendered to do an action after the first render
+    ```ts
+    use.once(() => use.rendered.then(() => {
+      console.log("after first render")
+    }))
+    ```
+
+### 🍋 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)
+- `Op` class wraps a pod signal and has some ergonomic fns
+- `loady` has various loading indicators for dealing with ops
+
+<br/>
+
+<br/>
+
+## 💖 PROJECT 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-1",
+	"version": "0.0.0-2",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",
@@ -13,10 +13,8 @@
 		"s"
 	],
 	"peerDependencies": {
-		"@e280/strata": "^0.0.0-9"
-	},
-	"dependencies": {
-		"@e280/stz": "^0.0.0-34",
+		"@e280/stz": "^0.0.0-35",
+		"@e280/strata": "^0.0.0-10",
 		"lit": "^3.3.1"
 	},
 	"devDependencies": {

package/s/demo/demo.bundle.ts

@@ -1,3 +1,52 @@
 
+import {nap, repeat} from "@e280/stz"
+import {css, html, render} from "lit"
+
+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++
+	}))
+
+	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"),
+)
+

package/s/demo/demo.css

@@ -79,11 +79,17 @@
 		display: block;
 		width: 100%;
 		max-width: 24em;
+		max-height: 30vh;
+		object-fit: contain;
 	}
 
 	.lil {
 		opacity: 0.6;
 		font-size: 0.8em;
 	}
+
+	:not(:defined) {
+		display: none;
+	}
 }
 

package/s/features/dom/dashify.ts

@@ -0,0 +1,11 @@
+
+/**
+ * Convert a camel-case name into a dashed name
+ * - for example
+ *       dashify("BigManStyle")
+ *        // "big-man-style"
+ */
+export function dashify(camel: string) {
+	return camel.replace(/([a-zA-Z])(?=[A-Z])/g, '$1-').toLowerCase()
+}
+

package/s/features/dom/dollar.ts

@@ -0,0 +1,21 @@
+
+export const $ = one
+
+export type Queryable = HTMLElement | Document | ShadowRoot | Element
+
+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) {
+	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) => {
+	return context.querySelector<E>(selector)
+}
+
+one.all = all
+

package/s/features/dom/register.ts

@@ -0,0 +1,48 @@
+
+import {dashify} from "./dashify.js"
+import {HTMLElementClasses} from "./types.js"
+
+export type RegistrationOptions = {
+	soft: boolean
+	upgrade: boolean
+}
+
+/**
+ * register custom elements (web components) to the dom
+ *  - takes an object full of custom html elements, and automatically dashes the names
+ *    - eg, `MyCoolElement` is registered as `<my-cool-element></my-cool-element>`
+ *  - calls `customElements.define`
+ *  - option `soft`
+ *    - `false` (default) will throw errors if elements are already defined
+ *    - `true` will do nothing if an element is already defined
+ *  - option `upgrade`
+ *    - `true` (default) will run `customElements.upgrade` where appropriate
+ *    - `false` will NOT upgrade any existing elements on the page
+ */
+export function register<E extends HTMLElementClasses>(
+		elements: E,
+		options: Partial<RegistrationOptions> = {},
+	) {
+
+	const {
+		soft = false,
+		upgrade = true,
+	} = options
+
+	for (const [name, Element] of Object.entries(elements)) {
+		const tag = dashify(name)
+		const already = customElements.get(tag)
+
+		if (soft && already)
+			continue
+
+		customElements.define(tag, Element)
+
+		if (upgrade)
+			document.querySelectorAll(tag).forEach(element => {
+				if (element.constructor === HTMLElement)
+					customElements.upgrade(element)
+			})
+	}
+}
+

package/s/features/dom/types.ts

@@ -0,0 +1,5 @@
+
+export type HTMLElementClasses = {
+	[key: string]: {new(...args: any[]): HTMLElement}
+}
+

package/s/features/loady/ascii-loader.ts

@@ -0,0 +1,38 @@
+
+import {makeAsciiLoader} from "./parts/ascii-loader.js";
+
+const hz = 15
+
+export const loady = {
+	cylon: makeAsciiLoader(hz, [
+		"=----",
+		"-=---",
+		"--=--",
+		"---=-",
+		"----=",
+		"-----",
+		"-----",
+	]),
+
+	dots: makeAsciiLoader(hz, [
+		":....",
+		"::...",
+		".::..",
+		"..::.",
+		"...::",
+		"....:",
+		".....",
+		".....",
+	]),
+
+	binary: makeAsciiLoader(hz, [
+		"01111",
+		"10111",
+		"11011",
+		"11101",
+		"11110",
+		"11111",
+		"11111",
+	]),
+}
+

package/s/features/loady/parts/ascii-anim.ts

@@ -0,0 +1,27 @@
+
+import {css} from "lit"
+import {nap, repeat} from "@e280/stz"
+
+import {view} from "../../views/view.js"
+import {cssReset} from "../../views/css-reset.js"
+
+const style = css`
+:host {
+	font-family: monospace;
+}
+`
+
+export const AsciiAnim = view(use => (hz: number, anim: string[]) => {
+	use.name("loading")
+	use.styles(cssReset, style)
+	const frame = use.signal(0)
+
+	use.mount(() => repeat(async() => {
+		await nap(1000 / hz)
+		const next = frame() + 1
+		frame(next >= anim.length ? 0 : next)
+	}))
+
+	return anim.at(frame())
+})
+

package/s/features/loady/parts/ascii-loader.ts

@@ -0,0 +1,14 @@
+
+import {Op} from "../../op/op.js"
+import {AsciiAnim} from "./ascii-anim.js"
+import {Content} from "../../views/types.js"
+import {ErrorDisplay} from "./error-display.js"
+
+export function makeAsciiLoader(hz: number, anim: string[]) {
+	return <V>(op: Op<V>, fn: (value: V) => Content) => op.select({
+		loading: () => AsciiAnim(hz, anim),
+		error: error => ErrorDisplay(error),
+		ready: fn,
+	})
+}
+

package/s/features/loady/parts/error-display.ts

@@ -0,0 +1,26 @@
+
+import {css, html} from "lit"
+import {view} from "../../views/view.js"
+import {cssReset} from "../../views/css-reset.js"
+
+const style = css`
+:host {
+	font-family: monospace;
+	color: red;
+}
+`
+
+export const ErrorDisplay = view(use => (error: any) => {
+	use.name("loading")
+	use.styles(cssReset, style)
+
+	if (typeof error === "string")
+		return error
+
+	else if (error instanceof Error)
+		return html`<strong>${error.name}:</strong> <span>${error.message}</span>`
+
+	else
+		return `error`
+})
+

package/s/features/op/op.ts

@@ -0,0 +1,98 @@
+
+import {pub} from "@e280/stz"
+import {signal} from "@e280/strata/signals"
+
+import {pod} from "./pod.js"
+import {Pod, PodSelect} from "./types.js"
+
+export class Op<V> {
+	static loading() {
+		return new this()
+	}
+
+	static ready<V>(value: V) {
+		const op = new this<V>()
+		op.signal(["ready", value])
+		return op
+	}
+
+	static error(error: any) {
+		const op = new this()
+		op.signal(["error", error])
+		return op
+	}
+
+	static promise<V>(promise: Promise<V>) {
+		const op = new this<V>()
+		op.promise(promise)
+		return op
+	}
+
+	static fn<V>(fn: () => Promise<V>) {
+		return this.promise(fn())
+	}
+
+	readonly signal = signal<Pod<V>>(["loading"])
+	#resolve = pub<[V]>()
+	#reject = pub<[any]>()
+
+	get wait() {
+		return new Promise((resolve, reject) => {
+			this.#resolve.next().then(resolve)
+			this.#reject.next().then(reject)
+		})
+	}
+
+	async setLoading() {
+		await this.signal(["loading"])
+	}
+
+	async setReady(value: V) {
+		await this.signal(["ready", value])
+		await this.#resolve(value)
+	}
+
+	async setError(error: any) {
+		await this.signal(["error", error])
+		await this.#reject(error)
+	}
+
+	async promise(promise: Promise<V>) {
+		await this.setLoading()
+		try {
+			const value = await promise
+			await this.setReady(value)
+			return value
+		}
+		catch (error) {
+			await this.setError(error)
+		}
+	}
+
+	async fn(fn: () => Promise<V>) {
+		return this.promise(fn())
+	}
+
+	get pod() {
+		return this.signal()
+	}
+
+	get status() {
+		return this.signal()[0]
+	}
+
+	get value() {
+		return pod.value(this.signal())
+	}
+
+	require() {
+		const pod = this.signal()
+		if (pod[0] !== "ready") throw new Error("required value not ready")
+		return pod[1]
+	}
+
+	select<R>(select: PodSelect<V, R>) {
+		return pod.select(this.signal(), select)
+	}
+}
+

package/s/features/op/pod.ts

@@ -0,0 +1,19 @@
+
+import {Pod, PodSelect} from "./types.js"
+
+export const pod = {
+	value: <V>(pod: Pod<V>) => {
+		return pod[0] === "ready"
+			? pod[1]
+			: undefined
+	},
+	select: <V, R>(pod: Pod<V>, select: PodSelect<V, R>) => {
+		switch (pod[0]) {
+			case "loading": return select.loading()
+			case "error": return select.error(pod[1])
+			case "ready": return select.ready(pod[1])
+			default: throw new Error("unknown op status")
+		}
+	},
+}
+

package/s/features/op/types.ts

@@ -0,0 +1,12 @@
+
+export type PodLoading = [status: "loading"]
+export type PodReady<V> = [status: "ready", value: V]
+export type PodError = [status: "error", error: any]
+export type Pod<V> = PodLoading | PodReady<V> | PodError
+
+export type PodSelect<V, R> = {
+	loading: () => R
+	ready: (value: V) => R
+	error: (error: any) => R
+}
+

package/s/features/views/css-reset.ts

@@ -0,0 +1,21 @@
+
+import {css, CSSResultGroup} from "lit"
+
+export const cssReset: CSSResultGroup = css`
+	@layer reset {
+		* {
+			margin: 0;
+			padding: 0;
+			box-sizing: border-box;
+
+			scrollbar-width: thin;
+			scrollbar-color: #888 transparent;
+		}
+
+		::-webkit-scrollbar { width: 8px; }
+		::-webkit-scrollbar-track { background: transparent; }
+		::-webkit-scrollbar-thumb { background: #333; border-radius: 1em; }
+		::-webkit-scrollbar-thumb:hover { background: #444; }
+	}
+`
+

package/s/features/views/types.ts

@@ -0,0 +1,23 @@
+
+import {DirectiveResult} from "lit/directive.js"
+import {CSSResultGroup, TemplateResult} from "lit"
+
+import {Use} from "./use.js"
+
+export type Content = TemplateResult | DirectiveResult | HTMLElement | string | null | undefined | void
+export type AttrValue = string | boolean | number | undefined | null | void
+
+export type ViewFn<Props extends any[]> = (use: Use) => (...props: Props) => Content
+export type View<Props extends any[]> = (...props: Props) => DirectiveResult<any>
+
+export type ViewSettings = ShadowRootInit & {
+	tag?: string
+	name?: string
+	styles?: CSSResultGroup
+}
+
+export type ViewWith = {
+	children: Content
+	attrs: Record<string, AttrValue>
+}
+