@e280/sly 0.2.0-9 → 0.2.0

package/README.md

@@ -4,13 +4,16 @@
 # 🦝 sly
 > *mischievous shadow views*
 
-[@e280](https://e280.org/)'s shiny new [lit](https://lit.dev/)-based frontend lib for webdevs. *(sly replaces its predecessor, [slate](https://github.com/benevolent-games/slate))*
-
-- 🍋 [**views**](#views) — hooks-based, shadow-dom'd, 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
-- 🪙 [**loot**](#loot) — drag-and-drop facilities
+[@e280](https://e280.org/)'s new [lit](https://lit.dev/)-based frontend webdev library. *(sly replaces its predecessor, [slate](https://github.com/benevolent-games/slate))*
+
+- **✨[shiny](https://shiny.e280.org/)✨** — our wip component library https://shiny.e280.org/
+- 🍋 [**#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) — 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 +21,7 @@
 <br/><br/>
 
 ## 🦝 sly and friends
+> `@e280/sly`  
 
 ```sh
 npm install @e280/sly lit @e280/strata @e280/stz
@@ -29,81 +33,87 @@ 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 and components
-> *views are the crown jewel of sly.. shadow-dom'd.. hooks-based.. "ergonomics"..*
+## 🍋🦝 sly views
+> `@e280/sly/view`  
+> *the crown jewel of sly*  
 
 ```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)
-- views are typescript-native and comfy for webdevs building apps
-- views automatically rerender whenever any [strata-compatible](https://github.com/e280/strata) state changes
+- 🪶 **no compile step** — just god's honest javascript, via [lit](https://lit.dev/)-html tagged-template-literals
+- 🥷 **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 component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
 
 ### 🍋 view example
 ```ts
-import {view, dom} from "@e280/sly"
+import {view, dom, BaseElement} from "@e280/sly"
 import {html, css} from "lit"
 ```
-- **declare a view**
+- **declare view**
     ```ts
     export const CounterView = view(use => (start: number) => {
-      use.name("counter")
       use.styles(css`p {color: green}`)
 
       const $count = use.signal(start)
       const increment = () => $count.value++
 
       return html`
-        <p>count ${$count.value}</p>
-        <button @click="${increment}">+</button>
+        <button @click="${increment}">
+          ${$count.value}
+        </button>
       `
     })
     ```
-    - each view renders into a `<sly-view view="counter">` host (where "counter" is the `use.name` you provided)
-- **inject a view into the dom**
+    - `$count` is a [strata signal](https://github.com/e280/strata#readme) *(we like those)*
+- **inject view into dom**
     ```ts
     dom.in(".app").render(html`
       <h1>cool counter demo</h1>
       ${CounterView(1)}
     `)
     ```
-- 🤯 **register a view as a web component**
+- 🤯 **register view as web component**
     ```ts
     dom.register({
       MyCounter: CounterView
         .component()
-        .props(component => [dom.attrs(component).number.start ?? 0]),
+        .props(() => [1]),
     })
     ```
     ```html
-    <my-counter start="1"></my-counter>
+    <my-counter></my-counter>
     ```
 
-### 🍋 view declaration settings
-- special settings for views at declaration-time
+### 🍋 view settings
+- optional settings for views you should know about
     ```ts
     export const CoolView = view
       .settings({mode: "open", delegatesFocus: true})
-      .render(use => (greeting: string) => {
-        return html`😎 ${greeting} <slot></slot>`
-      })
+      .render(use => (greeting: string) => html`😎 ${greeting} <slot></slot>`)
     ```
     - 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 injection options
-- options for views at the template injection site
+### 🍋 view chains
+- views have this sick chaining syntax for supplying more stuff at the template injection site
     ```ts
     dom.in(".app").render(html`
       <h2>cool example</h2>
-      ${CoolView.props("hello")
+      ${CoolView
+        .props("hello")
         .attr("class", "hero")
         .children(html`<em>spongebob</em>`)
         .render()}
@@ -111,78 +121,100 @@ import {html, css} from "lit"
     ```
     - `props` — provide props and start a view chain
     - `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)
+    - `children` — add nested [slottable](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots) content
     - `render` — end the view chain and render the lit directive
 
 ### 🍋 view/component universality
-- **start with a view,**
+- **you can start with a view,**
     ```ts
     export const GreeterView = view(use => (name: string) => {
       return html`<p>hello ${name}</p>`
     })
-
-    // view usage:
-    //   GreeterView("pimsley")
     ```
-    then you can convert it to a component
+    - view usage
+        ```ts
+        GreeterView("pimsley")
+        ```
+    **then you can convert it to a component.**
     ```ts
-    export class GreeterComponent extends (GreeterView
-      .component()
-      .props(component => [component.getAttribute("name") ?? "unknown"])
+    export class GreeterComponent extends (
+      GreeterView
+        .component()
+        .props(component => [component.getAttribute("name") ?? "unknown"])
     ) {}
-
-    // html usage:
-    //   <greeter-component name="pimsley"></greeter-component>
     ```
-- **start with a component,**
+    - html usage
+        ```html
+        <greeter-component name="pimsley"></greeter-component>
+        ```
+- **you can start with a component,**
     ```ts
-    export class GreeterComponent extends (view
-      .component()
-      .props(component => [component.getAttribute("name") ?? "unknown"])
-      .render(use => (name: string) => {
+    export class GreeterComponent extends (
+      view(use => (name: string) => {
         return html`<p>hello ${name}</p>`
       })
+      .component()
+      .props(component => [component.getAttribute("name") ?? "unknown"])
     ) {}
-
-    // 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)`**
+    - html usage
+        ```html
+        <greeter-component name="pimsley"></greeter-component>
+        ```
+    **and it already has `.view` ready for you.**
+    - view usage
+        ```ts
+        GreeterComponent.view("pimsley")
+        ```
+- **understanding `.component(BaseElement)` 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
+        the props fn receives the component instance, so you can query html attributes or instance properties
         ```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
+    - `.component` accepts a subclass of `BaseElement`, so you can define your own properties and methods for your component class
         ```ts
-        .component<{name?: string}>()
-        .props(component => [component.name ?? "unknown"])
+        const GreeterComponent = GreeterView
+
+          // declare your own custom class
+          .component(class extends BaseElement {
+            $name = signal("jim raynor")
+            updateName(name: string) {
+              this.$name.value = name
+            }
+          })
+
+          // props gets the right types on 'component'
+          .props(component => [component.$name.value])
         ```
-    - `.component` also takes an init fn, so you can do some setup, like use signals for reactivity
+    - `.component` provides the devs interacting with your component, with noice typings
         ```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"
+        dom<GreeterComponent>("greeter-component").updateName("mortimer")
         ```
+    - typescript class wizardry
+        - ❌ smol-brain approach exports class value, but NOT the typings
+            ```ts
+            export const GreeterComponent = (...)
+            ```
+        - ✅ giga-brain approach exports class value AND the typings
+            ```ts
+            export class GreeterComponent extends (...) {}
+            ```
 - **register web components to the dom**
     ```ts
     dom.register({GreeterComponent})
     ```
+- **oh and don't miss out on the insta-component shorthand**
+    ```ts
+    dom.register({
+      QuickComponent: view.component(use => html`⚡ incredi`),
+    })
+    ```
+
+<a id="use"></a>
 
 ### 🍋 "use" hooks reference
 - 👮 **follow the hooks rules**  
@@ -254,20 +286,46 @@ import {html, css} from "lit"
 
     v // 123
     ```
-- **use.attrs** — ergonomic typed html attribute access  
-    *(see [dom.attrs](#dom.attrs) for more details)*
+- **use.events** — attach event listeners to the element (auto-cleaned up)  
     ```ts
-    const attrs = use.attrs.spec({
-      name: String,
-      count: Number,
-      active: Boolean,
+    use.events({
+      keydown: (e: KeyboardEvent) => console.log("keydown", e.code),
+      keyup: (e: KeyboardEvent) => console.log("keyup", e.code),
     })
     ```
+- **use.states** — [internal states](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states) helper  
     ```ts
-    attrs.name // "chase"
-    attrs.count // 123
-    attrs.active // true
+    const states = use.states()
+    states.assign("active", "cool")
+    ```
+    ```css
+    [view="my-view"]::state(active) { color: yellow; }
+    [view="my-view"]::state(cool) { outline: 1px solid cyan; }
     ```
+- **use.attrs** — ergonomic typed html attribute access  
+    - `use.attrs` is similar to [#dom.attrs](#dom.attrs)
+        ```ts
+        const attrs = use.attrs({
+          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()
@@ -296,14 +354,14 @@ import {html, css} from "lit"
     ```
 
 ### 🍋 "use" recipes
-- make a ticker — mount, repeat, and nap
+- make a ticker — mount, cycle, and nap
     ```ts
-    import {repeat, nap} from "@e280/stz"
+    import {cycle, nap} from "@e280/stz"
     ```
     ```ts
     const $seconds = use.signal(0)
 
-    use.mount(() => repeat(async() => {
+    use.mount(() => cycle(async() => {
       await nap(1000)
       $seconds.value++
     }))
@@ -320,19 +378,36 @@ import {html, css} from "lit"
 <br/><br/>
 <a id="base-element"></a>
 
-## 🦝🪵 sly base element
-> *the classic experience*
+## 🪵🦝 sly base element
+> `@e280/sly/base`  
+> *the classic experience*  
 
 ```ts
 import {BaseElement, Use, dom} from "@e280/sly"
 import {html, css} from "lit"
 ```
 
-`BaseElement` is a class-based approach to create a custom element web component.
-
-it lets you expose js properties on the element instance, which helps you setup a better developer experience for people interacting with your element through the dom.
-
-base element enjoys the same `use` hooks as views.
+`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*.
+
+### 🪵 let's clarify some sly terminology
+- "Element"
+    - an html element; any subclass of the browser's HTMLElement
+    - all genuine ["web components"](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) are elements
+- "BaseElement"
+    - sly's own subclass of the browser-native HTMLElement
+    - is a true element and web component (can be registered to the dom)
+- "View"
+    - sly's own magic concept that uses a lit-directive to render stuff
+    - NOT an element or web component (can NOT be registered to the dom)
+    - NOT related to BaseElement
+    - can be converted into a Component via `view.component().props(() => [])`
+- "Component"
+    - a sly view that has been converted into an element
+    - is a true element and web component (can be registered to the dom)
+    - actually a subclass of BaseElement
+    - actually contains the view on `Component.view`
 
 ### 🪵 base element setup
 - **declare your element class**
@@ -341,7 +416,7 @@ base element enjoys the same `use` hooks as views.
       static styles = css`span{color:orange}`
 
       // custom property
-      start = 10
+      $start = signal(10)
 
       // custom attributes
       attrs = dom.attrs(this).spec({
@@ -357,9 +432,9 @@ base element enjoys the same `use` hooks as views.
         const $count = use.signal(1)
         const increment = () => $count.value++
 
-        const {start} = this
+        const {$start} = this
         const {multiply = 1} = this.attrs
-        const result = start + (multiply * $count())
+        const result = $start() + (multiply * $count())
 
         return html`
           <span>${result}</span>
@@ -385,7 +460,7 @@ base element enjoys the same `use` hooks as views.
     const myElement = dom<MyElement>("my-element")
 
     // js property
-    myElement.start = 100
+    myElement.$start(100)
 
     // html attributes
     myElement.attrs.multiply = 2
@@ -400,8 +475,9 @@ base element enjoys the same `use` hooks as views.
 <br/><br/>
 <a id="dom"></a>
 
-## 🦝🪄 sly dom
-> *the "it's not jquery!" multitool*
+## 🪄🦝 sly dom
+> `@e280/sly/dom`  
+> *the "it's not jquery!" multitool*  
 
 ```ts
 import {dom} from "@e280/sly"
@@ -413,49 +489,98 @@ import {dom} from "@e280/sly"
     dom(".demo")
       // HTMLElement (or throws)
     ```
+    ```ts
+    // alias
+    dom.require(".demo")
+      // HTMLElement (or throws)
+    ```
 - `maybe` get an element
     ```ts
     dom.maybe(".demo")
       // HTMLElement | undefined
     ```
-- `select` all elements
+- `all` matching elements in an array
     ```ts
     dom.all(".demo ul li")
       // HTMLElement[]
     ```
-- `in` the scope of an element
+
+### 🪄 dom.in scope
+- make a scope
     ```ts
-    dom(element).require("li")
-      // HTMLElement (or throws)
+    dom.in(".demo") // selector
+      // Dom instance
     ```
     ```ts
-    dom(element).maybe("li")
-      // HTMLElement | undefined
+    dom.in(demoElement) // element
+      // Dom instance
     ```
+- run queries in that scope
     ```ts
-    dom(element).all("li")
-      // HTMLElement[]
+    dom.in(demoElement).require(".button")
+    ```
+    ```ts
+    dom.in(demoElement).maybe(".button")
+    ```
+    ```ts
+    dom.in(demoElement).all("ol li")
     ```
 
 ### 🪄 dom utilities
-- `register` web components
+- `dom.register` web components
     ```ts
     dom.register({MyComponent, AnotherCoolComponent})
       // <my-component>
       // <another-cool-component>
     ```
     - `dom.register` automatically dashes the tag names (`MyComponent` becomes `<my-component>`)
-- `render` content into an element
+- `dom.render` content into an element
     ```ts
-    dom(element).render(html`<p>hello world</p>`)
+    dom.render(element, html`<p>hello world</p>`)
     ```
     ```ts
     dom.in(".demo").render(html`<p>hello world</p>`)
     ```
+- `dom.el` little element builder
     ```ts
-    dom.render(element, html`<p>hello world</p>`)
+    const div = dom.el("div", {"data-whatever": 123, "data-active": true})
+      // <div data-whatever="123" data-active></div>
+    ```
+- `dom.elmer` make an element with a fluent chain
+    ```ts
+    const div = dom.elmer("div")
+      .attr("data-whatever", 123)
+      .attr("data-active")
+      .children("hello world")
+      .done()
+        // HTMLElement
+    ```
+- `dom.mk` make an element with a lit template (returns the first)
+    ```ts
+    const div = dom.mk(html`
+      <div data-whatever="123" data-active>
+        hello world
+      </div>
+    `) // HTMLElement
+    ```
+- `dom.events` <a id="dom.events"></a> to attach event listeners
+    ```ts
+    const detach = dom.events(element, {
+      keydown: (e: KeyboardEvent) => console.log("keydown", e.code),
+      keyup: (e: KeyboardEvent) => console.log("keyup", e.code),
+    })
+    ```
+    ```ts
+    const detach = dom.in(".demo").events({
+      keydown: (e: KeyboardEvent) => console.log("keydown", e.code),
+      keyup: (e: KeyboardEvent) => console.log("keyup", e.code),
+    })
     ```
-- `attrs` <a id="dom.attrs"></a> to setup a type-happy html attribute helper
+    ```ts
+    // unattach those event listeners when you're done
+    detach()
+    ```
+- `dom.attrs` <a id="dom.attrs"></a> to setup a type-happy html attribute helper
     ```ts
     const attrs = dom.attrs(element).spec({
       name: String,
@@ -464,6 +589,13 @@ import {dom} from "@e280/sly"
     })
     ```
     ```ts
+    const attrs = dom.in(".demo").attrs.spec({
+      name: String,
+      count: Number,
+      active: Boolean,
+    })
+    ```
+    ```ts
     attrs.name // "chase"
     attrs.count // 123
     attrs.active // true
@@ -477,11 +609,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
+    or if you wanna be more loosey-goosey, skip the spec
     ```ts
-    dom.attrs(element).string.name = "pimsley"
-    dom.attrs(element).number.count = 125
-    dom.attrs(element).boolean.active = true
+    const a = dom.in(".demo").attrs
+    a.strings.name = "pimsley"
+    a.numbers.count = 125
+    a.booleans.active = true
     ```
 
 
@@ -489,12 +622,13 @@ import {dom} from "@e280/sly"
 <br/><br/>
 <a id="ops"></a>
 
-## 🦝🫛 sly ops
-> *tools for async operations and loading spinners*
+## 🫛🦝 sly ops
+> `@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
@@ -593,14 +727,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>
@@ -616,11 +765,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*
+## 🪙🦝 loot
+> `@e280/sly/loot`  
+> *drag-and-drop facilities*  
 
 ```ts
 import {loot, view, dom} from "@e280/sly"
@@ -741,7 +980,7 @@ import {ev} from "@e280/stz"
 <br/><br/>
 <a id="e280"></a>
 
-## 🦝🧑‍💻 sly is by e280
+## 🧑‍💻🦝 sly is by e280
 reward us with github stars  
 build with us at https://e280.org/ but only if you're cool