@e280/sly 0.2.0-16 → 0.2.0-17

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/
 
@@ -42,11 +44,11 @@ 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 +91,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 +100,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`
@@ -351,7 +353,7 @@ 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*.
 
@@ -533,7 +535,7 @@ import {dom} from "@e280/sly"
 
 ```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 +634,28 @@ 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
+> *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,6 +671,99 @@ import {Pod, podium, Op, makeLoader, anims} from "@e280/sly"
 
 
 
+<br/><br/>
+<a id="spa"></a>
+
+## 💅🦝 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`)
+    - 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"
+
+    return html`
+      <a href="${hash}">user 123</a>
+    `
+    ```
+- **check if a route is the currently-active one**
+    ```ts
+    const hash = router.nav.user.active
+      // true
+
+    return html`
+      <a href="${hash}">user 123</a>
+    `
+    ```
+- **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>
 

package/package.json

@@ -1,12 +1,18 @@
 {
 	"name": "@e280/sly",
-	"version": "0.2.0-16",
+	"version": "0.2.0-17",
 	"description": "web shadow views",
 	"license": "MIT",
 	"type": "module",
 	"main": "./x/index.js",
 	"exports": {
-		".": "./x/index.js"
+		".": "./x/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",
+		"./ui": "./x/ui/index.js"
 	},
 	"files": [
 		"x",
@@ -16,8 +22,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/demo/views/loaders.ts

@@ -2,8 +2,8 @@
 import {css, html} from "lit"
 import {Op} from "../../ops/op.js"
 import {view} from "../../ui/view.js"
+import {loaders} from "../../loaders/index.js"
 import {cssReset} from "../../ui/base/css-reset.js"
-import {anims, makeLoader} from "../../ops/loaders/make-loader.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/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 {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/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 "./ui/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 "../ui/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 "../../ui/types.js"
 
 const fast = 20
 const mid = 10

package/s/{ops/loaders → loaders}/parts/ascii-anim.ts

@@ -2,9 +2,9 @@
 import {css} from "lit"
 import {nap, repeat} from "@e280/stz"
 
-import {view} from "../../../ui/view.js"
-import {Content} from "../../../ui/types.js"
-import {cssReset} from "../../../ui/base/css-reset.js"
+import {view} from "../../ui/view.js"
+import {Content} from "../../ui/types.js"
+import {cssReset} from "../../ui/base/css-reset.js"
 
 export function makeAsciiAnim(hz: number, frames: string[]): () => Content {
 	return () => AsciiAnim({hz, frames})
@@ -17,6 +17,7 @@ export const AsciiAnim = view(use => ({hz, frames}: {
 
 	use.name("loading")
 	use.styles(cssReset, style)
+
 	const frame = use.signal(0)
 
 	use.mount(() => repeat(async() => {

package/s/{ops/loaders → loaders}/parts/error-display.ts

@@ -1,7 +1,7 @@
 
 import {css, html} from "lit"
-import {view} from "../../../ui/view.js"
-import {cssReset} from "../../../ui/base/css-reset.js"
+import {view} from "../../ui/view.js"
+import {cssReset} from "../../ui/base/css-reset.js"
 
 export const ErrorDisplay = view(use => (error: any) => {
 	use.name("error")

package/s/loaders/types.ts

@@ -0,0 +1,6 @@
+
+import type {Op} from "../ops/op.js"
+import type {Content} from "../ui/types.js"
+
+export type Loader = <V>(op: Op<V>, ready: (value: V) => Content) => Content
+

package/s/loot/index.barrel.ts

@@ -0,0 +1,5 @@
+
+export * from "./drag-and-drops.js"
+export * from "./drops.js"
+export * from "./helpers.js"
+

package/s/loot/index.ts

@@ -1,5 +1,3 @@
 
-export * from "./drag-and-drops.js"
-export * from "./drops.js"
-export * from "./helpers.js"
+export * as loot from "./index.barrel.js"
 

package/s/ops/index.ts

@@ -0,0 +1,5 @@
+
+export * from "./op.js"
+export * from "./podium.js"
+export * from "./types.js"
+

package/s/spa/index.barrel.ts

@@ -0,0 +1,6 @@
+
+export {route} from "./plumbing/braces.js"
+export type {Navigable} from "./plumbing/primitives.js"
+export {RouterOptions, Hasher, Route, Routes, Navigables} from "./plumbing/types.js"
+export {Router} from "./router.js"
+

package/s/spa/index.ts

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

package/s/spa/plumbing/braces.ts

@@ -0,0 +1,76 @@
+
+import {Hasher, Route} from "./types.js"
+import type {Content} from "../../ui/types.js"
+
+type ParamKeys<S extends string> =
+	S extends `${string}{${infer P}}${infer R}` ? (string & P) | ParamKeys<R> : never
+
+type ParamsOf<S extends string> =
+	[ParamKeys<S>] extends [never] ? {} : { [K in ParamKeys<S>]: string }
+
+type ParamsTuple<S extends string> =
+	keyof ParamsOf<S> extends never ? [] : [ParamsOf<S>]
+
+export function hasher<S extends string>(spec: S): Hasher<ParamsTuple<S>> {
+	if (!spec.startsWith("#/"))
+		throw new Error(`hash route spec must start with "#/"`)
+
+	const specparts = spec.split("/")
+	const braceregex = /\{([^\}\/]+)\}/
+
+	function parse(hash: string): ParamsTuple<S> | null {
+		if (!hash.startsWith("#/"))
+			throw new Error(`hash must start with "#/"`)
+
+		const hashparts = hash.split("/")
+		const params: Record<string, string> = {}
+
+		if (hashparts.length !== specparts.length)
+			return null
+
+		for (const [index, specpart] of specparts.entries()) {
+			const hashpart = hashparts.at(index)
+			if (hashpart === undefined) return null
+			const bracematch = specpart.match(braceregex)
+			try {
+				if (bracematch) params[bracematch[1]] = decodeURIComponent(hashpart)
+				else if (hashpart !== specpart) return null
+			}
+			catch {
+				return null
+			}
+		}
+
+		return (Object.keys(params).length === 0)
+			? ([] as ParamsTuple<S>)
+			: ([params as ParamsOf<S>] as ParamsTuple<S>)
+	}
+
+	function make(...[braces]: any[]): string {
+		const get = (param: string) => {
+			const p = param as any
+			if (p in braces) return braces[p]
+			else throw new Error(`missing param "${p}"`)
+		}
+		return specparts.map(specpart => {
+			const bracematch = specpart.match(braceregex)
+			return bracematch
+				? encodeURIComponent(get(bracematch[1]))
+				: specpart
+		}).join("/")
+	}
+
+	return {parse, make}
+}
+
+export function route<S extends string>(
+		spec: S,
+		fn: (...params: ParamsTuple<S>) => Promise<Content>,
+	): Route<ParamsTuple<S>> {
+
+	return {
+		hasher: hasher(spec),
+		fn,
+	}
+}
+

package/s/spa/plumbing/primitives.ts

@@ -0,0 +1,85 @@
+
+import {ev, ob} from "@e280/stz"
+import {Op} from "../../ops/op.js"
+import {ResolvedRoute, Route, Routes} from "./types.js"
+
+export function eraseWindowHash() {
+	const {pathname, search} = window.location
+	history.replaceState(null, "", pathname + search)
+}
+
+export function normalizeHash(hash: string) {
+	const homeEquivalents = [/^$/, /^#$/, /^#\/$/]
+	return (homeEquivalents.some(regex => regex.test(hash)))
+		? "#/"
+		: hash
+}
+
+export class HashNormalizer {
+	constructor(public location: Location) {}
+
+	get hash() {
+		const hash = normalizeHash(this.location.hash)
+		if (hash === "#/") eraseWindowHash()
+		return hash
+	}
+
+	set hash(hash: string) {
+		this.location.hash = hash
+	}
+}
+
+export class Navigable<R extends Routes = any, K extends keyof R = any> {
+	static all<R extends Routes>(
+			routes: R,
+			getRoute: () => Route<any> | null,
+			navigate: (hash: string) => Promise<ResolvedRoute<R>>,
+		): {[K in keyof R]: Navigable<R, K>} {
+
+		return ob(routes).map(route => new this(
+			route,
+			() => (getRoute() === route),
+			async(...params: any[]) => navigate(route.hasher.make(...params)),
+		))
+	}
+
+	constructor(
+		public route: Route<Parameters<R[K]["hasher"]["make"]>>,
+		private isActive: () => boolean,
+		public go: (...params: Parameters<R[K]["hasher"]["make"]>) => Promise<ResolvedRoute<R>>,
+	) {}
+
+	get active() {
+		return this.isActive()
+	}
+
+	hash(...params: Parameters<R[K]["hasher"]["make"]>) {
+		return this.route.hasher.make(...params)
+	}
+}
+
+export function resolveRoute<R extends Routes>(
+		hash: string,
+		routes: R,
+	): ResolvedRoute<R> | null {
+
+	for (const key in routes) {
+		const route = routes[key]
+		const params = route.hasher.parse(hash)
+		if (params) {
+			return {
+				key,
+				route,
+				params,
+				op: Op.promise(route.fn(...params))
+			}
+		}
+	}
+
+	return null
+}
+
+export function onHashChange(fn: (event: HashChangeEvent) => void) {
+	return ev(window, {hashchange: fn})
+}
+

package/s/spa/plumbing/router-core.ts

@@ -0,0 +1,49 @@
+
+import {signal} from "@e280/strata"
+import type {Content} from "../../ui/types.js"
+import {Navigable, normalizeHash, resolveRoute} from "./primitives.js"
+import {Hashbearer, Navigables, ResolvedRoute, Routes} from "./types.js"
+
+export class RouterCore<R extends Routes> {
+	readonly nav: Navigables<R>
+	readonly $resolved = signal<ResolvedRoute<R> | null>(null)
+
+	constructor(
+			public readonly routes: R,
+			public readonly location: Hashbearer,
+		) {
+
+		this.nav = Navigable.all(
+			routes,
+			() => this.route,
+			async hash => {
+				this.location.hash = hash
+				const resolved = await this.refresh()
+				if (!resolved) throw new Error(`route failed "${hash}"`)
+				return resolved
+			},
+		)
+	}
+
+	get hash() {
+		return normalizeHash(this.location.hash)
+	}
+
+	get content(): Content | null {
+		return this.$resolved.get()?.op.value ?? null
+	}
+
+	get route() {
+		return this.$resolved.get()?.route ?? null
+	}
+
+	async refresh(hash?: string) {
+		if (hash !== undefined) this.location.hash = hash
+		hash = this.hash
+		const resolved = resolveRoute(hash, this.routes)
+		await this.$resolved.set(resolved)
+		await resolved?.op
+		return resolved
+	}
+}
+