@e280/sly 0.2.0-16 → 0.2.0-18

package/README.md

@@ -9,7 +9,9 @@
 - 🍋 [**#views**](#views) — shadow-dom'd, hooks-based, componentizable
 - 🪵 [**#base-element**](#base-element) — for a more classical experience
 - 🪄 [**#dom**](#dom) — the "it's not jquery" multitool
-- 🫛 [**#ops**](#ops) — tools for async operations and loading spinners
+- 🫛 [**#ops**](#ops) — reactive tooling for async operations
+- ⏳ [**#loaders**](#loaders) — animated loading spinners for rendering ops
+- 💅 [**#spa**](#spa) — hash routing for your spa-day
 - 🪙 [**#loot**](#loot) — drag-and-drop facilities
 - 🧪 testing page — https://sly.e280.org/
 
@@ -18,6 +20,7 @@
 <br/><br/>
 
 ## 🦝 sly and friends
+> `@e280/sly`  
 
 ```sh
 npm install @e280/sly lit @e280/strata @e280/stz
@@ -29,24 +32,28 @@ npm install @e280/sly lit @e280/strata @e280/stz
 > - 🏂 [@e280/stz](https://github.com/e280/stz), our ts standard library
 > - 🐢 [@e280/scute](https://github.com/e280/scute), our buildy-bundly-buddy
 
+> [!TIP]
+> you can import everything in sly from `@e280/sly`, or from specific subpackages like `@e280/sly/view`, `@e280/sly/dom`, etc...
+
 
 
 <br/><br/>
 <a id="views"></a>
 
 ## 🍋🦝 sly views
-> *the crown jewel of sly*
+> `@e280/sly/view`  
+> *the crown jewel of sly*  
 
 ```ts
 view(use => () => html`<p>hello world</p>`)
 ```
 
 - 🪶 **no compile step** — just god's honest javascript, via [lit](https://lit.dev/)-html tagged-template-literals
-- 🥷 **shadow dom'd** — each gets its own cozy [shadow](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)
-- 🪝 **hooks-based** — declarative rendering with the [`use.*`](#use) family of ergonomic hooks
+- 🥷 **shadow dom'd** — each view gets its own cozy [shadow](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)
+- 🪝 **hooks-based** — declarative rendering with the [`use`](#use) family of ergonomic hooks
 - ⚡ **reactive** — they auto-rerender whenever any [strata](https://github.com/e280/strata)-compatible state changes
 - 🧐 **not components, per se** — they're comfy typescript-native ui building blocks [(technically, lit directives)](https://lit.dev/docs/templates/custom-directives/)
-- 🧩 **componentizable** — any view can be magically converted into a proper [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
+- 🧩 **componentizable** — any view can be magically converted into a proper [web component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
 
 ### 🍋 view example
 ```ts
@@ -89,7 +96,7 @@ import {html, css} from "lit"
     ```
 
 ### 🍋 view settings
-- lame settings for views you should know about
+- optional settings for views you should know about
     ```ts
     export const CoolView = view
       .settings({mode: "open", delegatesFocus: true})
@@ -98,7 +105,7 @@ import {html, css} from "lit"
     - all [attachShadow params](https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#parameters) (like `mode` and `delegatesFocus`) are valid `settings`
     - note the `<slot></slot>` we'll use in the next example lol
 
-### 🍋 view chain
+### 🍋 view chains
 - views have this sick chaining syntax for supplying more stuff at the template injection site
     ```ts
     dom.in(".app").render(html`
@@ -278,19 +285,30 @@ import {html, css} from "lit"
     v // 123
     ```
 - **use.attrs** — ergonomic typed html attribute access  
-    *(see [dom.attrs](#dom.attrs) for more details)*
-    ```ts
-    const attrs = use.attrs.spec({
-      name: String,
-      count: Number,
-      active: Boolean,
-    })
-    ```
-    ```ts
-    attrs.name // "chase"
-    attrs.count // 123
-    attrs.active // true
-    ```
+    - `use.attrs` is a bit different than `dom.attrs`, just to properly memoize .spec and .on for the render fn
+    - use.attrs.spec
+        ```ts
+        const attrs = use.attrs.spec({
+          name: String,
+          count: Number,
+          active: Boolean,
+        })
+        ```
+        ```ts
+        attrs.name // "chase"
+        attrs.count // 123
+        attrs.active // true
+        ```
+    - use.attrs.(strings/numbers/booleans)
+        ```ts
+        use.attrs.strings.name // "chase"
+        use.attrs.numbers.count // 123
+        use.attrs.booleans.active // true
+        ```
+    - use.attrs.on
+        ```ts
+        use.attrs.on(() => console.log("an attribute changed"))
+        ```
 - **use.render** — rerender the view (debounced)
     ```ts
     use.render()
@@ -344,14 +362,15 @@ import {html, css} from "lit"
 <a id="base-element"></a>
 
 ## 🪵🦝 sly base element
-> *the classic experience*
+> `@e280/sly/base`  
+> *the classic experience*  
 
 ```ts
 import {BaseElement, Use, dom} from "@e280/sly"
 import {html, css} from "lit"
 ```
 
-`BaseElement` is more of an old-timey class-based "boomer" approach to making web components, but with a zoomer twist — its `render` method gives you the same `use` hooks that views enjoy.
+`BaseElement` is more of an old-timey class-based "boomer" approach to making web components, but with a millennial twist — its `render` method gives you the same `use` hooks that views enjoy.
 
 👮 a *BaseElement* is not a *View*, and cannot be converted into a *View*.
 
@@ -440,7 +459,8 @@ import {html, css} from "lit"
 <a id="dom"></a>
 
 ## 🪄🦝 sly dom
-> *the "it's not jquery!" multitool*
+> `@e280/sly/dom`  
+> *the "it's not jquery!" multitool*  
 
 ```ts
 import {dom} from "@e280/sly"
@@ -518,9 +538,9 @@ import {dom} from "@e280/sly"
     ```
     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
+    dom.attrs(element).strings.name = "pimsley"
+    dom.attrs(element).numbers.count = 125
+    dom.attrs(element).booleans.active = true
     ```
 
 
@@ -529,11 +549,12 @@ import {dom} from "@e280/sly"
 <a id="ops"></a>
 
 ## 🫛🦝 sly ops
-> *tools for async operations and loading spinners*
+> `@e280/sly/ops`  
+> *tools for async operations and loading spinners*  
 
 ```ts
 import {nap} from "@e280/stz"
-import {Pod, podium, Op, makeLoader, anims} from "@e280/sly"
+import {Pod, podium, Op, loaders} from "@e280/sly"
 ```
 
 ### 🫛 pods: loading/ready/error
@@ -632,14 +653,29 @@ import {Pod, podium, Op, makeLoader, anims} from "@e280/sly"
     - loading if any ops are in loading, otherwise
     - ready if all the ops are ready
 
-### 🫛 loaders: animated loading spinners
-- create a `loader` using `makeLoader`
+
+
+<br/><br/>
+<a id="loaders"></a>
+
+## ⏳🦝 sly loaders
+> `@e280/sly/loaders`  
+> *animated loading spinners for ops*  
+
+```ts
+import {loaders} from "@e280/sly"
+```
+
+### ⏳ make a loader, choose an anim
+- create a loader fn
     ```ts
-    const loader = makeLoader(anims.dots)
+    const loader = loaders.make(loaders.anims.dots)
     ```
     - see all the anims available on the testing page https://sly.e280.org/
     - ngl, i made too many.. *i was having fun, okay?*
-- use the loader to render your op
+
+### ⏳ render an op with it
+- use your loader to render an op
     ```ts
     return html`
       <h2>cool stuff</h2>
@@ -655,11 +691,101 @@ import {Pod, podium, Op, makeLoader, anims} from "@e280/sly"
 
 
 
+<br/><br/>
+<a id="spa"></a>
+
+## 💅🦝 sly spa
+> `@e280/sly/spa`  
+> *hash router for single-page-apps*  
+
+```ts
+import {spa, html} from "@e280/sly"
+```
+
+### 💅 spa.Router basics
+- **make a spa router**
+    ```ts
+    const router = new spa.Router({
+      routes: {
+        home: spa.route("#/", async() => html`home`),
+        settings: spa.route("#/settings", async() => html`settings`),
+        user: spa.route("#/user/{userId}", async({userId}) => html`user ${userId}`),
+      },
+    })
+    ```
+    - all route strings must start with `#/`
+    - use braces like `{userId}` to accept string params
+    - home-equivalent hashes like `""` and `"#"` are normalized to `"#/"`
+    - the router has an effect on the appearance of the url in the browser address bar -- the home `#/` is removed, aesthetically, eg, `e280.org/#/` is rewritten to `e280.org` using *history.replaceState*
+    - you can provide `loader` option if you want to specify the loading spinner (defaults to `loaders.make()`)
+    - you can provide `notFound` option, if you want to specify what is shown on invalid routes (defaults to `() => null`)
+    - when `auto` is true (default), the router calls `.refresh()` and `.listen()` in the constructor.. set it to `false` if you want manual control
+    - you can set `auto` option false if you want to omit the default initial refresh and listen calls
+- **render your current page**
+    ```ts
+    return html`
+      <div class="my-page">
+        ${router.render()}
+      </div>
+    `
+    ```
+    - returns lit content
+    - shows a loading spinner when pages are loading
+    - will display the notFound content for invalid routes (defaults to null)
+- **perform navigations**
+    - go to settings page
+        ```ts
+        await router.nav.settings.go()
+          // goes to "#/settings"
+        ```
+    - go to user page
+        ```ts
+        await router.nav.user.go("123")
+          // goes to "#/user/123"
+        ```
+
+### 💅 spa.Router advanced
+- **generate a route's hash string**
+    ```ts
+    const hash = router.nav.user.hash("123")
+      // "#/user/123"
+
+    html`<a href="${hash}">user 123</a>`
+    ```
+- **check if a route is the currently-active one**
+    ```ts
+    const hash = router.nav.user.active
+      // true
+    ```
+- **force-refresh the router**
+    ```ts
+    await router.refresh()
+    ```
+- **force-navigate the router by hash**
+    ```ts
+    await router.refresh("#/user/123")
+    ```
+- **get the current hash string (normalized)**
+    ```ts
+    router.hash
+      // "#/user/123"
+    ```
+- **the `route(...)` helper fn enables the braces-params syntax**
+    - but, if you wanna do it differently, you *can* implement your own hash parser to do your own funky syntax
+- **dispose the router when you're done with it**
+    ```ts
+    router.dispose()
+      // stop listening to hashchange events
+    ```
+
+
+
 <br/><br/>
 <a id="loot"></a>
 
 ## 🪙🦝 loot
-> *drag-and-drop facilities*
+> `@e280/sly/loot`  
+> *drag-and-drop facilities*  
 
 ```ts
 import {loot, view, dom} from "@e280/sly"

package/package.json

@@ -1,12 +1,19 @@
 {
 	"name": "@e280/sly",
-	"version": "0.2.0-16",
+	"version": "0.2.0-18",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",
 	"main": "./x/index.js",
 	"exports": {
-		".": "./x/index.js"
+		".": "./x/index.js",
+		"./base": "./x/base/index.js",
+		"./dom": "./x/dom/index.js",
+		"./loaders": "./x/loaders/index.js",
+		"./loot": "./x/loot/index.js",
+		"./ops": "./x/ops/index.js",
+		"./spa": "./x/spa/index.js",
+		"./view": "./x/view/index.js"
 	},
 	"files": [
 		"x",
@@ -16,8 +23,8 @@
 		"lit": "^3.3.1"
 	},
 	"dependencies": {
-		"@e280/strata": "^0.2.0-13",
-		"@e280/stz": "^0.2.5"
+		"@e280/strata": "^0.2.0-14",
+		"@e280/stz": "^0.2.6"
 	},
 	"devDependencies": {
 		"@e280/science": "^0.1.2",

package/s/{ui/base-element.ts → base/element.ts}

@@ -3,11 +3,11 @@ import {debounce} from "@e280/stz"
 import {CSSResultGroup} from "lit"
 
 import {dom} from "../dom/dom.js"
-import {Content} from "./types.js"
-import {Reactor} from "./base/utils/reactor.js"
-import {AttrWatcher} from "./base/utils/attr-watcher.js"
-import {applyStyles} from "./base/utils/apply-styles.js"
-import {Use, _disconnect, _reconnect, _wrap} from "./base/use.js"
+import {Content} from "../view/types.js"
+import {Reactor} from "./utils/reactor.js"
+import {AttrWatcher} from "./utils/attr-watcher.js"
+import {applyStyles} from "./utils/apply-styles.js"
+import {Use, _disconnect, _reconnect, _wrap} from "./use.js"
 
 export class BaseElement extends HTMLElement {
 	static styles: CSSResultGroup | undefined

package/s/base/index.ts

@@ -0,0 +1,5 @@
+
+export * from "../base/css-reset.js"
+export * from "../base/element.js"
+export * from "../base/use.js"
+

package/s/{ui/base → base}/use.ts

@@ -3,10 +3,9 @@ import {CSSResultGroup} from "lit"
 import {defer, MapG} from "@e280/stz"
 import {signal, SignalOptions} from "@e280/strata/signals"
 
-import {Op} from "../../ops/op.js"
-import {dom} from "../../dom/dom.js"
-import {Attrs} from "../../dom/types.js"
+import {Op} from "../ops/op.js"
 import {Mounts} from "./utils/mounts.js"
+import {UseAttrs} from "./utils/use-attrs.js"
 import {applyStyles} from "./utils/apply-styles.js"
 
 export const _wrap = Symbol()
@@ -14,7 +13,7 @@ export const _disconnect = Symbol()
 export const _reconnect = Symbol()
 
 export class Use {
-	attrs: Attrs
+	readonly attrs: UseAttrs
 
 	#runs = 0
 	#position = 0
@@ -45,7 +44,7 @@ export class Use {
 			public renderNow: () => void,
 			public render: () => Promise<void>,
 		) {
-		this.attrs = dom.attrs(this.element)
+		this.attrs = new UseAttrs(this)
 	}
 
 	get renderCount() {

package/s/{ui/base → base}/utils/attr-watcher.ts

@@ -1,5 +1,5 @@
 
-import {dom} from "../../../dom/dom.js"
+import {dom} from "../../dom/dom.js"
 
 export class AttrWatcher {
 	#stopper: (() => void) | undefined

package/s/base/utils/use-attrs.ts

@@ -0,0 +1,27 @@
+
+import {Use} from "../use.js"
+import {dom} from "../../dom/dom.js"
+import {Attrs, AttrSpec} from "../../dom/types.js"
+
+export class UseAttrs {
+	#use: Use
+	#attrs: Attrs
+
+	constructor(use: Use) {
+		this.#use = use
+		this.#attrs = dom.attrs(use.element)
+	}
+
+	get strings() { return this.#attrs.strings }
+	get numbers() { return this.#attrs.numbers }
+	get booleans() { return this.#attrs.booleans }
+
+	spec<A extends AttrSpec>(spec: A) {
+		return this.#use.once(() => this.#attrs.spec(spec))
+	}
+
+	on(fn: () => void) {
+		return this.#use.mount(() => this.#attrs.on(fn))
+	}
+}
+

package/s/demo/views/counter.ts

@@ -2,9 +2,9 @@
 import {css, html} from "lit"
 
 import {dom} from "../../dom/dom.js"
-import {view} from "../../ui/view.js"
-import {cssReset} from "../../ui/base/css-reset.js"
-import {BaseElement} from "../../ui/base-element.js"
+import {view} from "../../view/view.js"
+import {cssReset} from "../../base/css-reset.js"
+import {BaseElement} from "../../base/element.js"
 
 export const CounterView = view(use => (start: number, step: number) => {
 	use.name("counter")

package/s/demo/views/demo.ts

@@ -1,10 +1,10 @@
 
 import {css, html} from "lit"
 
-import {view} from "../../ui/view.js"
+import {view} from "../../view/view.js"
 import {CounterView} from "./counter.js"
 import {LoadersView} from "./loaders.js"
-import {cssReset} from "../../ui/base/css-reset.js"
+import {cssReset} from "../../base/css-reset.js"
 
 export class DemoComponent extends (view.component(use => {
 	use.name("demo")

package/s/demo/views/fastcount.ts

@@ -3,8 +3,8 @@ import {css, html} from "lit"
 import {nap, repeat} from "@e280/stz"
 
 import {dom} from "../../dom/dom.js"
-import {Use} from "../../ui/base/use.js"
-import {BaseElement} from "../../ui/base-element.js"
+import {Use} from "../../base/use.js"
+import {BaseElement} from "../../base/element.js"
 
 export class FastcountElement extends BaseElement {
 	static styles = css`span{color:orange}`

package/s/demo/views/loaders.ts

@@ -1,9 +1,9 @@
 
 import {css, html} from "lit"
 import {Op} from "../../ops/op.js"
-import {view} from "../../ui/view.js"
-import {cssReset} from "../../ui/base/css-reset.js"
-import {anims, makeLoader} from "../../ops/loaders/make-loader.js"
+import {view} from "../../view/view.js"
+import {loaders} from "../../loaders/index.js"
+import {cssReset} from "../../base/css-reset.js"
 
 export const LoadersView = view(use => () => {
 	use.name("loaders")
@@ -11,14 +11,14 @@ export const LoadersView = view(use => () => {
 
 	const op = use.once(() => Op.loading())
 
-	const loaders = use.once(() =>
-		Object.entries(anims).map(([key, anim]) => ({
+	const library = use.once(() =>
+		Object.entries(loaders.anims).map(([key, anim]) => ({
 			key,
-			loader: makeLoader(anim)
+			loader: loaders.make(anim)
 		}))
 	)
 
-	return loaders.map(({key, loader}) => html`
+	return library.map(({key, loader}) => html`
 		<div data-anim="${key}">
 			<span>${key}</span>
 			<span>${loader(op, () => null)}</span>

package/s/dom/attrs/attrs.ts

@@ -8,9 +8,9 @@ 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,
+		strings: proxies.strings,
+		numbers: proxies.numbers,
+		booleans: proxies.booleans,
 		on: (fn: () => void) => onAttrs(element, fn),
 		spec: <A extends AttrSpec>(spec: A) => attrSpec(element, spec),
 	}

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

@@ -5,7 +5,7 @@ import {attrFns} from "./attr-fns.js"
 export class AttrProxies {
 	constructor(public element: HTMLElement) {}
 
-	string = new Proxy({}, {
+	strings = new Proxy({}, {
 		get: (_t, key: string) => (
 			attrFns.get.string(this.element, key)
 		),
@@ -14,7 +14,7 @@ export class AttrProxies {
 		),
 	}) as Record<string, string | undefined>
 
-	number = new Proxy({}, {
+	numbers = new Proxy({}, {
 		get: (_t, key: string) => (
 			attrFns.get.number(this.element, key)
 		),
@@ -23,7 +23,7 @@ export class AttrProxies {
 		),
 	}) as Record<string, number | undefined>
 
-	boolean = new Proxy({}, {
+	booleans = new Proxy({}, {
 		get: (_t, key: string) => (
 			attrFns.get.boolean(this.element, key)
 		),

package/s/dom/dom.ts

@@ -1,11 +1,11 @@
 
 import {render} from "lit"
+import {el} from "./parts/el.js"
 import {AttrSpec} from "./types.js"
 import {attrs} from "./attrs/attrs.js"
-import {Content} from "../ui/types.js"
+import {Content} from "../view/types.js"
+import {eve, EveSpec} from "./parts/eve.js"
 import {register} from "./parts/register.js"
-import { eve, EveSpec } from "./parts/eve.js"
-import { el } from "./parts/el.js"
 
 export type Renderable = HTMLElement | ShadowRoot | DocumentFragment
 export type Queryable = HTMLElement | ShadowRoot | Element | Document | DocumentFragment

package/s/dom/index.ts

@@ -0,0 +1,4 @@
+
+export * from "./types.js"
+export * from "./dom.js"
+

package/s/dom/parts/el.ts

@@ -1,6 +1,6 @@
 
-import {AttrValue} from "../../ui/types.js"
-import {setAttrs} from "../../ui/view/parts/set-attrs.js"
+import {AttrValue} from "../../view/types.js"
+import {setAttrs} from "../../view/utils/parts/set-attrs.js"
 
 export function el<E extends HTMLElement>(
 		tagName: string,

package/s/index.ts

@@ -1,21 +1,8 @@
 
-export * from "./dom/types.js"
-export * from "./dom/dom.js"
-
-export * from "./ops/loaders/make-loader.js"
-export * from "./ops/loaders/parts/ascii-anim.js"
-export * from "./ops/loaders/parts/error-display.js"
-export * from "./ops/op.js"
-export * from "./ops/podium.js"
-export * from "./ops/types.js"
-
-export * as loot from "./loot/index.js"
-
-export * from "./ui/base/css-reset.js"
-export * from "./ui/base/use.js"
-export * from "./ui/view/parts/chain.js"
-export * from "./ui/view/parts/sly-view.js"
-export * from "./ui/base-element.js"
-export * from "./ui/types.js"
-export * from "./ui/view.js"
+export * from "./dom/index.js"
+export * from "./loaders/index.js"
+export * from "./loot/index.js"
+export * from "./ops/index.js"
+export * from "./spa/index.js"
+export * from "./view/index.js"
 

package/s/loaders/index.barrel.ts

@@ -0,0 +1,9 @@
+
+export * as anims from "./parts/anims.js"
+export * from "./parts/ascii-anim.js"
+export * from "./parts/error-display.js"
+export * from "./make.js"
+export * from "./mock.js"
+export * from "./types.js"
+
+

package/s/loaders/index.ts

@@ -0,0 +1,3 @@
+
+export * as loaders from "./index.barrel.js"
+

package/s/{ops/loaders/make-loader.ts → loaders/make.ts}

@@ -1,14 +1,10 @@
 
-import {Op} from "../op.js"
+import {Loader} from "./types.js"
 import {earth} from "./parts/anims.js"
-import {Content} from "../../ui/types.js"
+import type {Content} from "../view/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(
+export function make(
 		loading: () => Content = earth,
 		error: (error: any) => Content = (error: any) => ErrorDisplay(error),
 	): Loader {

package/s/loaders/mock.ts

@@ -0,0 +1,11 @@
+
+import {Loader} from "./types.js"
+
+export function mock(): Loader {
+	return (op, ready) => op.select({
+		ready,
+		loading: () => `[loading]`,
+		error: () => `[error]`,
+	})
+}
+

package/s/{ops/loaders → loaders}/parts/anims.ts

@@ -1,6 +1,6 @@
 
 import {makeAsciiAnim} from "./ascii-anim.js"
-import {Content} from "../../../ui/types.js"
+import type {Content} from "../../view/types.js"
 
 const fast = 20
 const mid = 10