@e280/sly 0.2.0-11 → 0.2.0-12

package/README.md

@@ -4,13 +4,13 @@
 # 🦝 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))*
+[@e280](https://e280.org/)'s shiny new [lit](https://lit.dev/)-based frontend webdev library. *(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
+- 🍋 [**#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
+- 🪙 [**#loot**](#loot) — drag-and-drop facilities
 - 🧪 testing page — https://sly.e280.org/
 
 
@@ -34,76 +34,77 @@ npm install @e280/sly lit @e280/strata @e280/stz
 <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
+> *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) per se, 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 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)
 
 ### 🍋 view example
 ```ts
 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`
-        <span>${$count.value}</span>
-        <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(BaseElement)
-        .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
+- lame 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 chain
+- 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,7 +112,7 @@ 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
@@ -120,22 +121,23 @@ import {html, css} from "lit"
     export const GreeterView = view(use => (name: string) => {
       return html`<p>hello ${name}</p>`
     })
-
-    // view usage:
-    //   GreeterView("pimsley")
     ```
-    then 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(BaseElement)
         .props(component => [component.getAttribute("name") ?? "unknown"])
     ) {}
-
-    // html usage:
-    //   <greeter-component name="pimsley"></greeter-component>
     ```
-    - this trick with `class` and `extends` is amazing because typescript exports both the value of your component class, but also its type (doesn't work if you use `const`)
+    - html usage
+        ```html
+        <greeter-component name="pimsley"></greeter-component>
+        ```
 - **you can start with a component,**
     ```ts
     export class GreeterComponent extends (
@@ -145,44 +147,65 @@ import {html, css} from "lit"
       .component(BaseElement)
       .props(component => [component.getAttribute("name") ?? "unknown"])
     ) {}
-
-    // html usage:
-    //   <greeter-component name="pimsley"></greeter-component>
-    ```
-    then it already has a `.view` ready for you.
-    ```ts
-    // view usage:
-    //   GreeterComponent.view("pimsley")
     ```
+    - 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(C)` and `.props(fn)`**
     - `.props` takes a fn that is called every render, which returns the props given to the view
         ```ts
-        .component(BaseElement)
         .props(() => ["pimsley"])
         ```
         the props fn receives the component instance, so you can query html attributes or instance properties
         ```ts
-        .component(BaseElement)
         .props(component => [component.getAttribute("name") ?? "unknown"])
         ```
-    - `.component` accepts a subclass of `BaseElement`, which lets you define your own properties and methods for your component class
+    - `.component` accepts a subclass of `BaseElement`, so you can define your own properties and methods for your component class
         ```ts
-        .component(class extends BaseElement {
-          $name = signal("jim raynor")
-          updateName(name: string) {
-            this.$name.value = name
-          }
-        })
-        .props(component => [component.$name.value])
+        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` lets devs interacting with your component get nice types
+    - `.component` provides the devs interacting with your component, with noice typings
         ```ts
-        dom<GreeterComponent>("my-component").updateName("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**  
@@ -328,7 +351,7 @@ import {BaseElement, Use, dom} from "@e280/sly"
 import {html, css} from "lit"
 ```
 
-`BaseElement` is an old-timey class-based "fogey" approach to making web components, but with a modern twist — its `render` method gives you the same `use` hooks that views enjoy.
+`BaseElement` is 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.
 
 ### 🪵 base element setup
 - **declare your element class**
@@ -337,7 +360,7 @@ import {html, css} from "lit"
       static styles = css`span{color:orange}`
 
       // custom property
-      start = 10
+      $start = signal(10)
 
       // custom attributes
       attrs = dom.attrs(this).spec({
@@ -353,9 +376,9 @@ import {html, css} from "lit"
         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>
@@ -381,7 +404,7 @@ import {html, css} from "lit"
     const myElement = dom<MyElement>("my-element")
 
     // js property
-    myElement.start = 100
+    myElement.$start(100)
 
     // html attributes
     myElement.attrs.multiply = 2

package/package.json

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

package/x/index.html

@@ -131,7 +131,7 @@ body {
 	<img class=icon alt="" src="/assets/favicon.png"/>
 	<h1>sly testing page</h1>
 	<p><a href="https://github.com/e280/sly">github.com/e280/sly</a></p>
-	<p class=lil>v0.2.0-11</p>
+	<p class=lil>v0.2.0-12</p>
 
 	<fastcount-element></fastcount-element>
 	<counter-component start=280 step=2>component</counter-component>