🦝 sly

npm install lit @e280/sly @e280/strata @e280/stz

@e280's lit-based web library for reactive light or shadow views

🎭 #views, reactive lit views, light-dom or shadow-dom
🪝 #hooks, react-like composable hooks
⏳ #spinners, display async operations with animations
💅 #spa, tiny router for hashy little single-page-apps
🪙 #loot, drag-and-drop facilities
🪄 #dom, the "it's not jquery" multitool
🧪 https://sly.e280.org/ sly's testing page

🎭 views

reactive lit-html views

🔮 see codepen demo, plain html (no build!)
🌗 light or shadow, render nakedly on the page, or within a cozy shadow bubble
🪝 hooks-based, familiar react-style hooks
⚡ auto-reactive, views magically rerender on strata-compatible state changes
🪶 no compile step, just god's honest javascript via lit-html tagged-templates
🧩 not web components, no dom registration needed, just vibes and good typings

import {html} from "lit"
import {light, shadow, dom} from "@e280/sly"

export const MyLightView = light(() => html`<p>blinded by the light</p>`)

export const MyShadowView = shadow(() => html`<p>shrouded in darkness</p>`)

🌞 light views

lit, signals, hooks — life is joyous again

define a light view

import {html} from "lit"
import {light, useSignal} from "@e280/sly"

export const MyCounter = light((start: number) => {
  const $count = useSignal(start)
  const increment = () => $count.value++

  return html`
    <button @click="${increment}">${$count.value}</button>
  `
})

render it into the dom

dom.render(dom(".demo"), html`
  <h1>my cool counter demo</h1>
  ${MyCounter(123)}
`)

remember, light views are naked.
so they don't have a containing host element,
and they can't have their own styles.

🌚 shadow views

each shadow view gets its own cozy shadow-dom bubble, which scopes local css, and also supports slotting

define a shadow view

import {css, html} from "lit"
import {shadow, useName, useCss, useSignal} from "@e280/sly"

export const MyShadowCounter = shadow((start: number) => {
  useName("counter")
  useCss(css`button { color: cyan }`)

  const $count = useSignal(start)
  const increment = () => $count.value++

  return html`
    <button @click="${increment}">${$count.value}</button>
    <slot></slot>
  `
})

render it into the dom

dom.render(dom(".demo"), html`
  <h1>my cool counter demo</h1>
  ${MyShadowCounter(234)}
`)

shadow views have a host element, rendered output looks like:

<h1>my cool counter demo</h1>
<sly-shadow view="counter"></sly-shadow>

.with to nest children or set attrs

dom.render(dom(".demo"), html`
  <h1>my cool counter demo</h1>

  ${MyShadowCounter.with({
    props: [234],
    attrs: {"data-whatever": 555},
    children: html`
      <p>woah, slotting support!</p>
    `,
  })}
`)

you can do custom shadow setup if needed (default shown)

import {SlyShadow} from "@e280/sly"

const customShadow = shadow.setup(() => {
  SlyShadow.register()
  const host = document.createElement("sly-shadow")
  const shadow = host.attachShadow({mode: "open"})
  return {host, shadow}
})

const MyShadowView = customShadow(() => html`<p>shrouded in darkness</p>`)

🍨 web components

web-native custom elements

they use hooks like the views, but they don't take props

import {html} from "lit"
import {lightElement, shadowElement} from "@e280/sly"

const MyLight = lightElement(() => html`hello`)
const MyShadow = shadowElement(() => html`hello`)

dom.register({MyLight, MyShadow})

<my-light></my-light>
<my-shadow></my-shadow>

🪝 hooks

composable view state and utilities

👮 follow the hooks rules, or you go to hooks jail

just like react hooks, the execution order of hooks seriously matters.

you must not call these hooks under if-conditionals, or for-loops, or inside callback functions, or after a conditional return statement, or anything like that.. otherwise, heed my warning: weird bad stuff will happen..

🌚 shadow-only hooks

useName, set the "view" attribute value

useName("squarepants")
  // <sly-shadow view="squarepants">

useCss, attach stylesheets (use lit's css!) to the shadow root
```
useCss(css1, css2, css3)
```
useHost, get the host element
```
const host = useHost()
```
useShadow, get the shadow root
```
const shadow = useShadow()
```

useAttrs, access host element attributes (and rerender on attr changes)

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)

const [count, setCount] = useState(0)

const increment = () => setCount(n => n + 1)

useRef, react-like hook to make a non-reactive box for a value

const ref = useRef(0)

ref.current // 0
ref.current = 1 // does not trigger rerender

useSignal, create a strata signal

const $count = useSignal(1)

// read the signal
$count()

// write the signal
$count(2)

useDerived, create a strata derived signal

const $product = useDerived(() => $count() * $whatever())

useEffect, run a fn whenever strata state changes
```
useEffect(() => console.log($count))
```

useOnce, run fn at initialization, and return a value

const whatever = useOnce(() => {
  console.log("happens one time")
  return 123
})

whatever // 123

useMount, setup mount/unmount lifecycle

useMount(() => {
  console.log("mounted")
  return () => console.log("unmounted")
})

useWake, run fn each time mounted, and return value

const whatever = useWake(() => {
  console.log("mounted")
  return 123
})

whatever // 123

useLifecycle, mount/unmount lifecycle, but also return a value

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)

const render = useRender()

render().then(() => console.log("render done"))

useRendered, get a promise that resolves after the next render
```
useRendered().then(() => console.log("rendered"))
```

useWait, start loading a strata#wait signal

const $wait = useWait(async() => {
  await nap(2000)
  return 123
})

look at the current Wait state

$wait()
  // {done: true, ok: true, value: 123}

await for when the value is ready
```
await $wait.ready
  // 123
```

useWaitResult, start a strata#wait, but with a formal stz#ok ok/err result

const $wait = useWaitResult(async() => {
  await nap(2000)
  return (Math.random() > 0.5)
    ? ok(123)
    : err("uh oh")
})

🧑‍🍳 happy hooks recipes

make a ticker, mount, cycle, and nap

import {cycle, nap} from "@e280/stz"

const $seconds = useSignal(0)

useMount(() => cycle(async() => {
  await nap(1000)
  $seconds.value++
}))

wake + rendered, to do something after each mount's first render

const rendered = useRendered()

useWake(() => rendered.then(() => {
  console.log("after first render")
}))

⏳️ spinners

animated loading spinners

⏳️ stuff you'll need

from stz#ok — ok/err, formal error handling
```
import {ok, err, nap} from "@e280/stz"
```
from strata#wait — wait, async operation state
```
import {wait} from "@e280/strata"
```

⏳️ ui jumpstart

okay, so let's just do a loading spinner example

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`
    <p>done, the value is ${value}</p>
  `)
})

while the async fn is running, an animated spinner will be shown
when the async fn resolves, our little <p> 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)

import {spinner, dotsSpinner, waveSpinner, earthSpinner, moonSpinner} from "@e280/sly"

⏳️ make your own spinners

it's easy

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

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

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

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

route(norm(location.hash))
  // "#/settings" -> "settings"

route(norm(location.pathname))
  // "/settings" -> "settings"

subrouting pattern

// 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),
})

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

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 signal for the current normalized location.hash
```
const $hash = hashSignal()
```
```
$hash.value
  // "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

const $content = derived(() => route($hash()))
  // "user 123 profile"

then you can plop that content into your lit html

html`
  <div>
    ${$content()}
  </div>
`

🪙 loot

drag-and-drop facilities

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

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

light(() => html`
  <div
    ?data-indicator="${drops.$indicator()}"
    @dragover="${drops.dragover}"
    @dragleave="${drops.dragleave}"
    @drop="${drops.drop}">
      my dropzone
  </div>
`)

vanilla-js whole-page example

// 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
```
[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

// 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

const dnd = new loot.DragAndDrops<Money, Bag>({
  acceptDrop: (event, money, bag) => {
    console.log("drop!", {money, bag})
  },
})

attach dragzone listeners (there can be many dragzones...)

light(() => {
  const money = useOnce((): Money => ({value: 280}))
  const dragzone = useOnce(() => dnd.dragzone(() => money))

  return html`
    <div
      draggable="${dragzone.draggable}"
      @dragstart="${dragzone.dragstart}"
      @dragend="${dragzone.dragend}">
        money ${money.value}
    </div>
  `
})

attach dropzone listeners (there can be many dropzones...)

light(() => {
  const bag = useOnce((): Bag => ({id: 1}))
  const dropzone = useOnce(() => dnd.dropzone(() => bag))
  const indicator = !!(dnd.dragging && dnd.hovering === bag)

  return html`
    <div
      ?data-indicator="${indicator}"
      @dragenter="${dropzone.dragenter}"
      @dragleave="${dropzone.dragleave}"
      @dragover="${dropzone.dragover}"
      @drop="${dropzone.drop}">
        bag ${bag.id}
    </div>
  `
})

🪙 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

import {dom} from "@e280/sly"

🪄 dom queries

require an element

dom(".demo")
  // HTMLElement (or throws)

// alias
dom.require(".demo")
  // HTMLElement (or throws)

maybe get an element

dom.maybe(".demo")
  // HTMLElement | undefined

all matching elements in an array

dom.all(".demo ul li")
  // HTMLElement[]

🪄 dom.in scope

make a scope

dom.in(".demo") // selector
  // Dom instance

dom.in(demoElement) // element
  // Dom instance

run queries in that scope

dom.in(demoElement).require(".button")

dom.in(demoElement).maybe(".button")

dom.in(demoElement).all("ol li")

🪄 dom utilities

dom.register web components
```
dom.register({MyComponent, AnotherCoolComponent})
  // <my-component>
  // <another-cool-component>
```
- dom.register automatically dashes the tag names (MyComponent becomes <my-component>)

dom.render content into an element

dom.render(element, html`<p>hello world</p>`)

dom.in(".demo").render(html`<p>hello world</p>`)

dom.el little element builder

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

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)

const div = dom.mk(html`
  <div data-whatever="123" data-active>
    hello world
  </div>
`) // HTMLElement

dom.events to attach event listeners

const detach = dom.events(element, {
  keydown: (e: KeyboardEvent) => console.log("keydown", e.code),
  keyup: (e: KeyboardEvent) => console.log("keyup", e.code),
})

const detach = dom.in(".demo").events({
  keydown: (e: KeyboardEvent) => console.log("keydown", e.code),
  keyup: (e: KeyboardEvent) => console.log("keyup", e.code),
})

// unattach those event listeners when you're done
detach()

dom.attrs to setup a type-happy html attribute helper

const attrs = dom.attrs(element).spec({
  name: String,
  count: Number,
  active: Boolean,
})

const attrs = dom.in(".demo").attrs.spec({
  name: String,
  count: Number,
  active: Boolean,
})

attrs.name // "chase"
attrs.count // 123
attrs.active // true

attrs.name = "zenky"
attrs.count = 124
attrs.active = false // removes html attr

attrs.name = undefined // removes the attr
attrs.count = undefined // removes the attr

or if you wanna be more loosey-goosey, skip the spec

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

Name		Name	Last commit message	Last commit date
Latest commit History 474 Commits
.github/workflows		.github/workflows
assets		assets
s		s
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🦝 sly

@e280's lit-based web library for reactive light or shadow views

🎭 views

🌞 light views

🌚 shadow views

🍨 web components

🪝 hooks

👮 follow the hooks rules, or you go to hooks jail

🌚 shadow-only hooks

🌞 universal hooks

🧑‍🍳 happy hooks recipes

⏳️ spinners

⏳️ stuff you'll need

⏳️ ui jumpstart

⏳️ make your own spinners

💅 spa

🪙 loot

🪙 `loot.Drops`

🪙 `loot.DragAndDrops`

🪙 loot helpers

🪄 dom

🪄 dom queries

🪄 dom.in scope

🪄 dom utilities

🧑‍💻 sly is by e280

About

Uh oh!

Releases

Contributors 1

Languages

Folders and files

Latest commit

History

Repository files navigation

🦝 sly

@e280's lit-based web library for reactive light or shadow views

🎭 views

🌞 light views

🌚 shadow views

🍨 web components

🪝 hooks

👮 follow the hooks rules, or you go to hooks jail

🌚 shadow-only hooks

🌞 universal hooks

🧑‍🍳 happy hooks recipes

⏳️ spinners

⏳️ stuff you'll need

⏳️ ui jumpstart

⏳️ make your own spinners

💅 spa

🪙 loot

🪙 loot.Drops

🪙 loot.DragAndDrops

🪙 loot helpers

🪄 dom

🪄 dom queries

🪄 dom.in scope

🪄 dom utilities

🧑‍💻 sly is by e280

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Contributors 1

Languages

🪙 `loot.Drops`

🪙 `loot.DragAndDrops`