@e280/sly 0.2.0-8 → 0.2.0-9

package/README.md

@@ -20,7 +20,7 @@
 ## 🦝 sly and friends
 
 ```sh
-npm install @e280/sly lit
+npm install @e280/sly lit @e280/strata @e280/stz
 ```
 
 > [!NOTE]
@@ -34,15 +34,15 @@ npm install @e280/sly lit
 <br/><br/>
 <a id="views"></a>
 
-## 🦝🍋 sly views
+## 🦝🍋 sly views and components
 > *views are the crown jewel of sly.. shadow-dom'd.. hooks-based.. "ergonomics"..*
 
 ```ts
 view(use => () => html`<p>hello world</p>`)
 ```
 
+- any view can be converted into a web component
 - views are not [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components), but they do have [shadow roots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) and support [slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots)
-- any view can be registered as a web component, perfect for entrypoints or sharing widgets with html authors
 - views are typescript-native and comfy for webdevs building apps
 - views automatically rerender whenever any [strata-compatible](https://github.com/e280/strata) state changes
 
@@ -76,8 +76,14 @@ import {html, css} from "lit"
     ```
 - 🤯 **register a view as a web component**
     ```ts
-    dom.register({MyCounter: CounterView.component(1)})
-      // <my-counter></my-counter>
+    dom.register({
+      MyCounter: CounterView
+        .component()
+        .props(component => [dom.attrs(component).number.start ?? 0]),
+    })
+    ```
+    ```html
+    <my-counter start="1"></my-counter>
     ```
 
 ### 🍋 view declaration settings
@@ -85,7 +91,7 @@ import {html, css} from "lit"
     ```ts
     export const CoolView = view
       .settings({mode: "open", delegatesFocus: true})
-      .declare(use => (greeting: string) => {
+      .render(use => (greeting: string) => {
         return html`😎 ${greeting} <slot></slot>`
       })
     ```
@@ -108,27 +114,77 @@ import {html, css} from "lit"
     - `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)
     - `render` — end the view chain and render the lit directive
 
-### 🍋 view web components
-- **build a component directly**
+### 🍋 view/component universality
+- **start with a view,**
     ```ts
-    const MyComponent = view.component(use => html`<p>hello world</p>`)
+    export const GreeterView = view(use => (name: string) => {
+      return html`<p>hello ${name}</p>`
+    })
+
+    // view usage:
+    //   GreeterView("pimsley")
     ```
-    - notice that direct components don't take props (do `use.attrs` instead)
-- **convert any view into a web component**
+    then you can convert it to a component
     ```ts
-    const MyCounter = CounterView.component(1)
+    export class GreeterComponent extends (GreeterView
+      .component()
+      .props(component => [component.getAttribute("name") ?? "unknown"])
+    ) {}
+
+    // html usage:
+    //   <greeter-component name="pimsley"></greeter-component>
     ```
-    - to convert a view to a component, you provide props
-    - note that the component instance has a render method like `element.render(2)` which can take new props at runtime
+- **start with a component,**
+    ```ts
+    export class GreeterComponent extends (view
+      .component()
+      .props(component => [component.getAttribute("name") ?? "unknown"])
+      .render(use => (name: string) => {
+        return html`<p>hello ${name}</p>`
+      })
+    ) {}
+
+    // html usage:
+    //   <greeter-component name="pimsley"></greeter-component>
+    ```
+    then you can already use it as a view
+    ```ts
+    // view usage:
+    //   GreeterComponent.view("pimsley")
+    ```
+- **understanding `.component(init)` and `.props(fn)`**
+    - `.props` takes a fn that is called every render, which returns the props given to the view
+        ```ts
+        .component()
+        .props(() => ["pimsley"])
+        ```
+        the props fn receives the component instance, so you can query html attributes
+        ```ts
+        .component()
+        .props(component => [component.getAttribute("name") ?? "unknown"])
+        ```
+    - `.component` takes a mixin type added to the component type, so your `.props` can accept instance properties
+        ```ts
+        .component<{name?: string}>()
+        .props(component => [component.name ?? "unknown"])
+        ```
+    - `.component` also takes an init fn, so you can do some setup, like use signals for reactivity
+        ```ts
+        .component<{$name: SignalFn<string>}>(component => {
+          component.$name = signal("pimsley")
+        })
+        .props(component => [component.$name])
+        ```
+    - `.component` lets you set instance properties, that devs can interact with via the dom
+        ```ts
+        dom<GreeterComponent>("my-component").$name.value = "mortimer"
+        ```
 - **register web components to the dom**
     ```ts
-    dom.register({MyComponent, MyCounter})
-      // <my-component></my-component>
-      // <my-counter></my-counter>
+    dom.register({GreeterComponent})
     ```
-    - `dom.register` automatically dashes the tag names (`MyComponent` becomes `<my-component>`)
 
-### 🍋 view "use" hooks reference
+### 🍋 "use" hooks reference
 - 👮 **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..  
     > 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..*
@@ -201,7 +257,7 @@ import {html, css} from "lit"
 - **use.attrs** — ergonomic typed html attribute access  
     *(see [dom.attrs](#dom.attrs) for more details)*
     ```ts
-    const attrs = use.attrs({
+    const attrs = use.attrs.spec({
       name: String,
       count: Number,
       active: Boolean,
@@ -239,7 +295,7 @@ import {html, css} from "lit"
     const op = use.op.promise(doAsyncWork())
     ```
 
-### 🍋 view "use" recipes
+### 🍋 "use" recipes
 - make a ticker — mount, repeat, and nap
     ```ts
     import {repeat, nap} from "@e280/stz"
@@ -288,7 +344,7 @@ base element enjoys the same `use` hooks as views.
       start = 10
 
       // custom attributes
-      attrs = dom.attrs(this, {
+      attrs = dom.attrs(this).spec({
         multiply: Number,
       })
 
@@ -388,6 +444,7 @@ import {dom} from "@e280/sly"
       // <my-component>
       // <another-cool-component>
     ```
+    - `dom.register` automatically dashes the tag names (`MyComponent` becomes `<my-component>`)
 - `render` content into an element
     ```ts
     dom(element).render(html`<p>hello world</p>`)
@@ -400,7 +457,7 @@ import {dom} from "@e280/sly"
     ```
 - `attrs` <a id="dom.attrs"></a> to setup a type-happy html attribute helper
     ```ts
-    const attrs = dom.attrs(element, {
+    const attrs = dom.attrs(element).spec({
       name: String,
       count: Number,
       active: Boolean,
@@ -420,6 +477,12 @@ import {dom} from "@e280/sly"
     attrs.name = undefined // removes the attr
     attrs.count = undefined // removes the attr
     ```
+    or if you wanna be more loosey-goosy, skip the spec
+    ```ts
+    dom.attrs(element).string.name = "pimsley"
+    dom.attrs(element).number.count = 125
+    dom.attrs(element).boolean.active = true
+    ```
 
 
 
@@ -599,7 +662,7 @@ import {ev} from "@e280/stz"
       })
 
       // sly attribute handler for the body
-      const attrs = dom.attrs(document.body, {
+      const attrs = dom.attrs(document.body).spec({
         "data-indicator": Boolean,
       })
 

package/package.json

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

package/s/demo/demo.bundle.ts

@@ -1,14 +1,26 @@
 
+import {nap, repeat} from "@e280/stz"
 import {dom} from "../dom/dom.js"
 import {DemoView} from "./views/demo.js"
 import {CounterView} from "./views/counter.js"
+import {DivineElement} from "./views/divine.js"
 import {IncrediElement} from "./views/incredi.js"
 
 dom.in(".demo").render(DemoView())
 
 dom.register({
 	IncrediElement,
-	DemoCounter: CounterView.component(1),
+	DivineElement,
+	DemoCounter: CounterView
+		.component()
+		.props(c => [dom.attrs(c).number.initial ?? 0]),
+})
+
+const divine = dom<DivineElement>("divine-element")
+
+repeat(async() => {
+	await nap(1000)
+	divine.$speed.value++
 })
 
 console.log("🦝 sly")

package/s/demo/views/counter.ts

@@ -2,21 +2,22 @@
 import {css, html} from "lit"
 import {repeat} from "@e280/stz"
 
+import {dom} from "../../dom/dom.js"
 import {view} from "../../views/view.js"
 import {cssReset} from "../../views/css-reset.js"
 
-export const CounterView = view(use => (initial: number) => {
+export const CounterView = view(use => (start: number) => {
 	use.name("counter")
 	use.styles(cssReset, styles)
 
 	const $seconds = use.signal(0)
-	const start = use.once(() => Date.now())
+	const since = use.once(() => Date.now())
 	use.mount(() => repeat(async() => {
-		const since = Date.now() - start
-		$seconds.set(Math.floor(since / 1000))
+		const delta = Date.now() - since
+		$seconds.set(Math.floor(delta / 1000))
 	}))
 
-	const $count = use.signal(initial)
+	const $count = use.signal(start)
 	const increment = () => $count.value++
 
 	const $product = use.signal
@@ -39,6 +40,13 @@ export const CounterView = view(use => (initial: number) => {
 	`
 })
 
+// convert a view into a web component
+export class CounterComponent extends (
+	CounterView
+		.component<{start?: number}>()
+		.props(c => [dom.attrs(c).number.start ?? 0])
+) {}
+
 const styles = css`
 :host {
 	display: flex;

package/s/demo/views/demo.ts

@@ -1,16 +1,26 @@
 
 import {css, html} from "lit"
+import {DivineView} from "./divine.js"
 import {view} from "../../views/view.js"
 import {CounterView} from "./counter.js"
 import {LoadersView} from "./loaders.js"
 import {cssReset} from "../../views/css-reset.js"
+import { nap, repeat } from "@e280/stz"
 
 export const DemoView = view(use => () => {
 	use.name("demo")
 	use.styles(cssReset, styles)
 
+	const $speed = use.signal(3)
+
+	use.mount(() => repeat(async() => {
+		await nap(1000)
+		$speed.value++
+	}))
+
 	return html`
 		${CounterView.props(2).children("view").render()}
+		${DivineView($speed())}
 		${LoadersView()}
 	`
 })

package/s/demo/views/divine.ts

@@ -0,0 +1,22 @@
+
+import {html} from "lit"
+import {view} from "../../views/view.js"
+import {signal, SignalFn} from "@e280/strata"
+
+export class DivineElement extends (view
+	.component<{$speed: SignalFn<number>}>(component => {
+		component.$speed = signal(1)
+	})
+	.props<[speed: number]>(component => [component.$speed()])
+	.render(use => speed => {
+		const $count = use.signal(0)
+		const increment = () => $count($count() + speed)
+		return html`
+			<span>${$count()}</span>
+			<button @click="${increment}">+${speed}</button>
+		`
+	})
+) {}
+
+export const DivineView = DivineElement.view
+

package/s/demo/views/incredi.ts

@@ -8,7 +8,8 @@ import {BaseElement} from "../../views/base-element.js"
 
 export class IncrediElement extends BaseElement {
 	static styles = css`span{color:orange}`
-	attrs = dom.attrs(this, {value: Number})
+
+	attrs = dom.attrs(this).spec({value: Number})
 	something = {whatever: "rofl"}
 
 	render(use: Use) {

package/s/dom/attrs/attrs.ts

@@ -0,0 +1,21 @@
+
+import {AttrSpec} from "../types.js"
+import {onAttrs} from "./parts/on-attrs.js"
+import {attrFns} from "./parts/attr-fns.js"
+import {attrSpec} from "./parts/attr-spec.js"
+import {AttrProxies} from "./parts/attr-proxies.js"
+
+export function attrs(element: HTMLElement) {
+	const proxies = new AttrProxies(element)
+	return {
+		string: proxies.string,
+		number: proxies.number,
+		boolean: proxies.boolean,
+		on: (fn: () => void) => onAttrs(element, fn),
+		spec: <A extends AttrSpec>(spec: A) => attrSpec(element, spec),
+	}
+}
+
+attrs.get = attrFns.get
+attrs.set = attrFns.set
+

package/s/dom/attrs/parts/attr-fns.ts

@@ -0,0 +1,38 @@
+
+/** fns for getting and setting html attributes of various types */
+export const attrFns = {
+	get: {
+		string: (e: HTMLElement, key: string) => {
+			return e.getAttribute(key) ?? undefined
+		},
+		number: (e: HTMLElement, key: string) => {
+			const raw = e.getAttribute(key)
+			return (raw === null || !raw)
+				? undefined
+				: Number(raw)
+		},
+		boolean: (e: HTMLElement, key: string) => {
+			const raw = e.getAttribute(key)
+			return raw !== null
+		},
+	},
+
+	set: {
+		string: (e: HTMLElement, key: string, value: string | undefined) => {
+			if (value === undefined) e.removeAttribute(key)
+			else e.setAttribute(key, value)
+			return true
+		},
+		number: (e: HTMLElement, key: string, value: number | undefined) => {
+			if (value === undefined) e.removeAttribute(key)
+			else e.setAttribute(key, value.toString())
+			return true
+		},
+		boolean: (e: HTMLElement, key: string, value: boolean | undefined) => {
+			if (value) e.setAttribute(key, "")
+			else e.removeAttribute(key)
+			return true
+		},
+	},
+}
+

package/s/dom/attrs/parts/attr-proxies.ts

@@ -0,0 +1,35 @@
+
+import {attrFns} from "./attr-fns.js"
+
+/** a typed proxy accessor for html attributes */
+export class AttrProxies {
+	constructor(public element: HTMLElement) {}
+
+	string = new Proxy({}, {
+		get: (_t, key: string) => (
+			attrFns.get.string(this.element, key)
+		),
+		set: (_t, key: string, value: string | undefined) => (
+			attrFns.set.string(this.element, key, value)
+		),
+	}) as Record<string, string | undefined>
+
+	number = new Proxy({}, {
+		get: (_t, key: string) => (
+			attrFns.get.number(this.element, key)
+		),
+		set: (_t, key: string, value: number | undefined) => (
+			attrFns.set.number(this.element, key, value)
+		),
+	}) as Record<string, number | undefined>
+
+	boolean = new Proxy({}, {
+		get: (_t, key: string) => (
+			attrFns.get.boolean(this.element, key)
+		),
+		set: (_t, key: string, value: boolean | undefined) => (
+			attrFns.set.boolean(this.element, key, value)
+		),
+	}) as Record<string, boolean | undefined>
+}
+

package/s/dom/attrs/parts/attr-spec.ts

@@ -0,0 +1,29 @@
+
+import {AttrSpec, AttrTypes} from "../../types.js"
+import {attrFns} from "./attr-fns.js"
+
+/** specify available html attributes and their types and create a proxy accessor */
+export const attrSpec = <A extends AttrSpec>(
+		e: HTMLElement,
+		spec: A,
+	) => new Proxy(spec, {
+
+	get: (_target, key: string) => {
+		switch (spec[key]) {
+			case String: return attrFns.get.string(e, key)
+			case Number: return attrFns.get.number(e, key)
+			case Boolean: return attrFns.get.boolean(e, key)
+			default: throw new Error(`invalid attribute type for "${key}"`)
+		}
+	},
+
+	set: (_target, key: string, value: any) => {
+		switch (spec[key]) {
+			case String: return attrFns.set.string(e, key, value)
+			case Number: return attrFns.set.number(e, key, value)
+			case Boolean: return attrFns.set.boolean(e, key, value)
+			default: throw new Error(`invalid attribute type for "${key}"`)
+		}
+	},
+}) as any as AttrTypes<A>
+

package/s/dom/attrs/parts/on-attrs.ts

@@ -0,0 +1,8 @@
+
+/** respond when any attribute changes on the html element */
+export function onAttrs(element: HTMLElement, fn: () => void) {
+	const observer = new MutationObserver(fn)
+	observer.observe(element, {attributes: true})
+	return () => observer.disconnect()
+}
+

package/s/dom/dom.ts

@@ -1,8 +1,9 @@
 
 import {render} from "lit"
-import {register} from "./register.js"
+import {AttrSpec} from "./types.js"
+import {attrs} from "./attrs/attrs.js"
 import {Content} from "../views/types.js"
-import {attributes, AttrSpec, AttrTypes} from "./attributes.js"
+import {register} from "./parts/register.js"
 
 export type Renderable = HTMLElement | ShadowRoot | DocumentFragment
 export type Queryable = HTMLElement | ShadowRoot | Element | Document | DocumentFragment
@@ -45,8 +46,8 @@ export class Dom<C extends Queryable> {
 		return render(content, this.element as Renderable)
 	}
 
-	attrs<A extends AttrSpec>(spec: A) {
-		return attributes(this.element as HTMLElement, spec)
+	attrs() {
+		return attrs(this.element as HTMLElement)
 	}
 }
 
@@ -64,7 +65,7 @@ dom.require = doc.require.bind(doc)
 dom.maybe = doc.maybe.bind(doc)
 dom.all = doc.all.bind(doc)
 
-dom.attrs = attributes
+dom.attrs = attrs
 dom.register = register
 dom.render = (container: Renderable, ...content: Content[]) => {
 	return render(content, container)

package/s/dom/{register.ts → parts/register.ts}

@@ -1,14 +1,6 @@
 
 import {dashify} from "./dashify.js"
-
-export type HTMLElementClasses = {
-	[key: string]: {new(...args: any[]): HTMLElement}
-}
-
-export type RegistrationOptions = {
-	soft: boolean
-	upgrade: boolean
-}
+import {HTMLElementClasses, RegisterOptions} from "../types.js"
 
 /**
  * register custom elements (web components) to the dom
@@ -24,7 +16,7 @@ export type RegistrationOptions = {
  */
 export function register<E extends HTMLElementClasses>(
 		elements: E,
-		options: Partial<RegistrationOptions> = {},
+		options: Partial<RegisterOptions> = {},
 	) {
 
 	const {

package/s/dom/types.ts

@@ -0,0 +1,45 @@
+
+import {attrs} from "./attrs/attrs.js"
+
+// attrs
+
+export type AttrKind = (
+	| typeof String
+	| typeof Number
+	| typeof Boolean
+)
+
+export type AttrType<H extends AttrKind> = (
+	H extends typeof String
+		? string | undefined
+
+	: H extends typeof Number
+		? number | undefined
+
+	: H extends typeof Boolean
+		? boolean
+
+	: never
+)
+
+export type AttrSpec = {
+	[key: string]: AttrKind
+}
+
+export type AttrTypes<A extends AttrSpec> = {
+	[P in keyof A]: AttrType<A[P]>
+}
+
+export type Attrs = ReturnType<typeof attrs>
+
+// register
+
+export type HTMLElementClasses = {
+	[key: string]: {new(...args: any[]): HTMLElement}
+}
+
+export type RegisterOptions = {
+	soft: boolean
+	upgrade: boolean
+}
+

package/s/index.html.ts

@@ -30,7 +30,8 @@ export default ssg.page(import.meta.url, async orb => ({
 		<p><a href="https://github.com/e280/sly">github.com/e280/sly</a></p>
 		<p class=lil>v${orb.packageVersion()}</p>
 		<incredi-element></incredi-element>
-		<demo-counter>component</demo-counter>
+		<divine-element></divine-element>
+		<demo-counter initial="-1">component</demo-counter>
 		<div class=demo></div>
 	`,
 }))

package/s/index.ts

@@ -1,8 +1,6 @@
 
-export * from "./dom/attributes.js"
-export * from "./dom/dashify.js"
+export * from "./dom/types.js"
 export * from "./dom/dom.js"
-export * from "./dom/register.js"
 
 export * from "./ops/loaders/make-loader.js"
 export * from "./ops/loaders/parts/ascii-anim.js"
@@ -13,7 +11,6 @@ export * from "./ops/types.js"
 
 export * as loot from "./loot/index.js"
 
-export * from "./dom/attributes.js"
 export * from "./views/base-element.js"
 export * from "./views/css-reset.js"
 export * from "./views/types.js"