```
- **useCss,** attach stylesheets (use lit's `css`!) to the shadow root
```ts
useCss(css1, css2, css3)
```
- **useHost,** get the host element
```ts
const host = useHost()
```
- **useShadow,** get the shadow root
```ts
const shadow = useShadow()
```
- **useAttrs,** access host element attributes (and rerender on attr changes)
```ts
const attrs = useAttrs({
name: String,
count: Number,
active: Boolean,
})
attrs.count = 123 // set the attr
```
### ๐ universal hooks
- **useState,** react-like hook to create some reactive state (we prefer signals)
```ts
const [count, setCount] = useState(0)
const increment = () => setCount(n => n + 1)
```
- **useRef,** react-like hook to make a non-reactive box for a value
```ts
const ref = useRef(0)
ref.current // 0
ref.current = 1 // does not trigger rerender
```
- **useSignal,** create a [strata](https://github.com/e280/strata) signal
```ts
const $count = useSignal(1)
// read the signal
$count()
// write the signal
$count(2)
```
- **useDerived,** create a [strata](https://github.com/e280/strata) derived formula
```ts
const $product = useDerived(() => $count() * $whatever())
```
- **useEffect,** run a fn whenever [strata](https://github.com/e280/strata) state changes
```ts
useEffect(() => console.log($count))
```
- **useOnce,** run fn at initialization, and return a value
```ts
const whatever = useOnce(() => {
console.log("happens one time")
return 123
})
whatever // 123
```
- **useMount,** setup mount/unmount lifecycle
```ts
useMount(() => {
console.log("mounted")
return () => console.log("unmounted")
})
```
- **useWake,** run fn each time mounted, and return value
```ts
const whatever = useWake(() => {
console.log("mounted")
return 123
})
whatever // 123
```
- **useLifecycle,** mount/unmount lifecycle, but also return a value
```ts
const whatever = useLifecycle(() => {
console.log("mounted")
const value = 123
return [value, () => console.log("unmounted")]
})
whatever // 123
```
- **useRender,** returns a fn to rerender the view (debounced)
```ts
const render = useRender()
render().then(() => console.log("render done"))
```
- **useRendered,** get a promise that resolves *after* the next render
```ts
useRendered().then(() => console.log("rendered"))
```
- **useWait,** start loading a [strata#wait](https://github.com/e280/strata#wait) signal
```ts
const $wait = useWait(async() => {
await nap(2000)
return 123
})
```
- look at the current `Wait` state
```ts
$wait()
// {done: true, ok: true, value: 123}
```
- await for when the value is ready
```ts
await $wait.ready
// 123
```
- **useWaitFormal,** start a [strata#wait](https://github.com/e280/strata#wait), but with a formal [stz#ok](https://github.com/e280/stz#ok) ok/err result
```ts
const $wait = useWaitFormal(async() => {
await nap(2000)
return (Math.random() > 0.5)
? ok(123)
: err("uh oh")
})
```
### ๐งโ๐ณ happy hooks recipes
- make a ticker, mount, cycle, and nap
```ts
import {cycle, nap} from "@e280/stz"
```
```ts
const $seconds = useSignal(0)
useMount(() => cycle(async() => {
await nap(1000)
$seconds($seconds() + 1)
}))
```
- wake + rendered, to do something after each mount's first render
```ts
const rendered = useRendered()
useWake(() => rendered.then(() => {
console.log("after first render")
}))
```
## โณ๏ธ spinners
> *animated loading spinners*
sly's spinners integrate with [strata wait](https://github.com/e280/strata#wait), which in turn integrates with [stz ok](https://github.com/e280/stz#ok), so you might want to read each of those docs.
### โณ๏ธ ui jumpstart
- **okay, so let's just do a loading spinner example**
```ts
import {html} from "lit"
import {shadow, useWait, spinner} from "@e280/sly"
const MyView = shadow(() => {
// โณ๏ธ create a $wait signal
const $wait = useWait(async() => {
await nap(2000) // contrived async job
return 123 // return a value
})
// โณ๏ธ ui display for the changing $wait signal
return spinner($wait(), value => html`
done, the value is ${value}
`)
})
```
- while the async fn is running, an animated spinner will be shown
- when the async fn resolves, our little `` tag will render
- if the async fn errors out, the error message will be displayed in red
- **stock spinners for your convenience** *(earth is my favorite)*
```ts
import {spinner, dotsSpinner, waveSpinner, earthSpinner, moonSpinner} from "@e280/sly"
```
### โณ๏ธ make your own spinners
- **it's easy**
```ts
import {makeSpinner, makeAsciiAnim, ErrorDisplay} from "@e280/sly"
export const pieSpinner = makeSpinner(
makeAsciiAnim(10, ["โท", "โถ", "โต", "โด"]),
ErrorDisplay,
)
```
- so makeSpinner accepts two views, one for the loading state, and one for the error state
- feel free to make your own views
## ๐
spa
> *tiny router for cozy single page apps*
```ts
import {derived} from "@e280/strata"
import {router, norm, hashNav, hashSignal} from "@e280/sly"
```
the spa router is agnostic about whether you're routing `location.hash` or `location.pathname` or otherwise.
- **router**
```ts
const route = router({
"": () => "home", // ๐ routes can return anything
"settings": () => "settings",
// ๐งฉ params use braces
"user/{id}": params => `user ${params.id}`,
// ๐ subpath with {*}
"user/{id}/{*}": (params, subpath) => `user ${params.id} ${subpath}`,
})
```
you get a fn that resolves the path you give it
```ts
route("")
// "home"
route("settings")
// "settings"
route("user/123/profile")
// "user 123 profile"
route("unknown/whatever")
// undefined
```
- **`norm` fn** chops off leading slashes and/or hash chars
```ts
route(norm(location.hash))
// "#/settings" -> "settings"
```
```ts
route(norm(location.pathname))
// "/settings" -> "settings"
```
- **subrouting pattern**
```ts
// here's a subrouter
const user = (params: {id: string}) => router({
"profile": () => `user ${params.id} profile`,
"invites": () => `user ${params.id} invites`,
})
// here's the main router, where we can nest the subrouter
const route = router({
// this {*} captures the rest of the string, we pass it to the subrouter
"user/{id}/{*}": (params, subpath) => user(params)(subpath),
})
```
```ts
route("user/123/profile")
// "user 123 profile"
```
now, if you want to setup `location.hash` routing, you might want these primitives.
- **hashNav** fn to trigger navigations
```ts
const go = hashNav({
home: () => ``,
settings: () => `settings`,
user: (id: string) => `user/${id}`,
userProfile: (id: string) => `user/${id}/profile`,
userInvites: (id: string) => `user/${id}/invites`,
})
go.settings()
// navigates to "#/settings"
go.user("123")
// navigates to "#/user/123"
```
- **hashSignal** create a [strata](https://github.com/e280/strata) signal for the current normalized `location.hash`
```ts
const $hash = hashSignal()
```
```ts
$hash()
// "user/123/profile"
```
- the signal value auto-updates whenever the hash changes
- the value is run through the `norm` fn to chop off the leading `#/`
- whenever the hash changes, it runs `cleanHash` fn which aesthetically converts `e280.org/#/` to just `e280.org/` in the address bar
- **you should setup a derived signal** that routes whenever that hash signal changes
```ts
const $content = derived(() => route($hash()))
// "user 123 profile"
```
then you can plop that content into your lit html
```ts
html`
${$content()}
`
```
## ๐ช loot
> *drag-and-drop facilities*
```ts
import {loot, view, dom} from "@e280/sly"
import {ev} from "@e280/stz"
```
### ๐ช `loot.Drops`
> *accept the user dropping stuff like files onto the page*
- **setup drops**
```ts
const drops = new loot.Drops({
predicate: loot.hasFiles,
acceptDrop: event => {
const files = loot.files(event)
console.log("files dropped", files)
},
})
```
- **attach event listeners to your dropzone,** one of these ways:
- **view example**
```ts
light(() => html`
my dropzone
`)
```
- **vanilla-js whole-page example**
```ts
// attach listeners to the body
ev(document.body, {
dragover: drops.dragover,
dragleave: drops.dragleave,
drop: drops.drop,
})
// sly attribute handler for the body
const attrs = dom.attrs(document.body).spec({
"data-indicator": Boolean,
})
// sync the data-indicator attribute
drops.$indicator.on(bool => attrs["data-indicator"] = bool)
```
- **flashy css indicator for the dropzone,** so the user knows your app is eager to accept the drop
```css
[data-indicator] {
border: 0.5em dashed cyan;
}
```
### ๐ช `loot.DragAndDrops`
> *setup drag-and-drops between items within your page*
- **declare types for your draggy and droppy things**
```ts
// money that can be picked up and dragged
type Money = {value: number}
// dnd will call this a "draggy"
// bag that money can be dropped into
type Bag = {id: number}
// dnd will call this a "droppy"
```
- **make your dnd**
```ts
const dnd = new loot.DragAndDrops({
acceptDrop: (event, money, bag) => {
console.log("drop!", {money, bag})
},
})
```
- **attach dragzone listeners** (there can be many dragzones...)
```ts
light(() => {
const money = useOnce((): Money => ({value: 280}))
const dragzone = useOnce(() => dnd.dragzone(() => money))
return html`
money ${money.value}
`
})
```
- **attach dropzone listeners** (there can be many dropzones...)
```ts
light(() => {
const bag = useOnce((): Bag => ({id: 1}))
const dropzone = useOnce(() => dnd.dropzone(() => bag))
const indicator = !!(dnd.dragging && dnd.hovering === bag)
return html`
bag ${bag.id}
`
})
```
### ๐ช loot helpers
- **`loot.hasFiles(event)`** โ return true if `DragEvent` contains any files (useful in `predicate`)
- **`loot.files(event)`** โ returns an array of files in a drop's `DragEvent` (useful in `acceptDrop`)
## ๐ช dom
> *the "it's not jquery!" multitool*
```ts
import {dom} from "@e280/sly"
```
### ๐ช dom queries
- `need` an element
```ts
dom(".demo")
// HTMLElement (or throws)
```
```ts
// alias
dom.need(".demo")
// HTMLElement (or throws)
```
- `maybe` get an element
```ts
dom.maybe(".demo")
// HTMLElement | undefined
```
- `all` matching elements in an array
```ts
dom.all(".demo ul li")
// HTMLElement[]
```
### ๐ช dom.in scope
- make a scope
```ts
dom.in(".demo") // selector
// Dom instance
```
```ts
dom.in(demoElement) // element
// Dom instance
```
- run queries in that scope
```ts
dom.in(demoElement).need(".button")
```
```ts
dom.in(demoElement).maybe(".button")
```
```ts
dom.in(demoElement).all("ol li")
```
### ๐ช dom utilities
- `dom.register` web components
```ts
dom.register({MyComponent, AnotherCoolComponent})
//
//
```
- `dom.register` automatically dashes the tag names (`MyComponent` becomes ``)
- `dom.render` content into an element
```ts
dom.render(element, html`hello world
`)
```
```ts
dom.in(".demo").render(html`hello world
`)
```
- `dom.el` little element builder
```ts
const div = dom.el("div", {"data-whatever": 123, "data-active": true})
//
```
- `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`
hello world
`) // HTMLElement
```
- `dom.events` 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),
})
```
```ts
// unattach those event listeners when you're done
detach()
```
- `dom.attrs` to setup a type-happy html attribute helper
```ts
const attrs = dom.attrs(element).spec({
name: String,
count: Number,
active: Boolean,
})
```
```ts
const attrs = dom.in(".demo").attrs.spec({
name: String,
count: Number,
active: Boolean,
})
```
```ts
attrs.name // "chase"
attrs.count // 123
attrs.active // true
```
```ts
attrs.name = "zenky"
attrs.count = 124
attrs.active = false // removes html attr
```
```ts
attrs.name = undefined // removes the attr
attrs.count = undefined // removes the attr
```
or if you wanna be more loosey-goosey, skip the spec
```ts
const {attrs} = dom.in(".demo")
attrs.strings.name = "pimsley"
attrs.numbers.count = 125
attrs.booleans.active = true
```
## ๐งโ๐ป sly is by e280
reward us with github stars
build with us at https://e280.org/ but only if you're cool
