@benev/slate
Advanced tools
@benev/slate by chase moskal🚧 prerelease, see changelog
i've iterated on this for many years, and it's always shifting and changing as i build real apps with it.
features, handy tools, and state management patterns, are accumulating and being refined.
please don't make your whole app out of web components.. they're too cumbersome for that — you need views!
litshadow domso, you want to think of web components as the tip of your iceberg — they are the entrypoints to your ui — they are the universal control surfaces to help html authors interact with your systems — but below the surface, most of your internals can be made of nicely composable views.
npm i @benev/slate
nexusimport {Nexus, Context} from "@benev/slate"
export const nexus = new Nexus(
new class extends Context {
// this theme is applied to all your components and views
theme = css`
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
`
// add app-level stuff you'd like to make widely available
my_cool_thing = {my_awesome_data: 123}
}
)
lit's templating functions, which directly implement signals.import {html, css, svg} from "@benev/slate"
you can create custom html elements that work in plain html or any web framework.
nexus.shadowComponentexport const MyShadowComponent = nexus.shadowComponent(use => {
use.styles(css`span {color: yellow}`)
const count = use.signal(0)
const increment = () => count.value++
return html`
<span>${count}</span>
<button @click=${increment}>increment</button>
`
})
nexus.lightComponentexport const MyLightComponent = nexus.lightComponent(use => {
const count = use.signal(0)
const increment = () => count.value++
return html`
<span>${count}</span>
<button @click=${increment}>increment</button>
`
})
import {register_to_dom} from "@benev/slate"
register_to_dom({
MyShadowComponent,
MyLightComponent,
})
<section>
<my-shadow-component></my-shadow-component>
<my-light-component></my-light-component>
</section>
MyComponentName are automatically dashify'd into my-component-nameapply functions to manipulate components en masseimport {apply, css, register_to_dom} from "@benev/slate"
const applyCustomTheme = apply.css(`
button {
color: red;
}
`)
register_to_dom(
applyCustomTheme({
NastyNavbar,
DopeDropdown,
MarvelousMarquee,
})
)
register_to_dom and apply for themviews are just like components, but are not registered to the dom as custom html elements.
instead, they are used via javascript.
you import them, and inject them into your lit-html templates.
they accept js parameters called props, and are fully typescript-typed.
nexus.shadowViewexport const MyShadowView = nexus.shadowView(use => (start: number) => {
use.name("my-shadow-view")
use.styles(css`span {color: yellow}`)
const count = use.signal(start)
const increment = () => count.value++
return html`
<span>${count}</span>
<button @click=${increment}>increment</button>
`
})
auto_exportparts is enabled by default.
part attribute, then it will automatically re-export all internal parts, using the part as a prefix.::part(search-input-icon).nexus.lightViewexport const MyLightView = nexus.lightView(use => (start: number) => {
use.name("my-light-view")
const count = use.signal(start)
const increment = () => count.value++
return html`
<span>${count}</span>
<button @click=${increment}>increment</button>
`
})
html`<div>${MyShadowView([123])}</div>`
html`
<div>
${MyShadowView([123], {
content: html`<p>slotted content</p>`,
auto_exportparts: true,
attrs: {part: "cool", "data-whatever": true},
})}
</div>
`
html`<div>${MyLightView(123)}</div>`
<slate-view view="my-name"> componentuse hooks — for views and componentsslate's hooks have the same rules as any other framework's hooks: the order that hooks are executed in matters, so you must not call hooks under an if statement or in any kind of for loop or anything like that.
use.name("my-cool-view")
use.styles(css`span { color: yellow }`)
const [count, setCount] = use.state(0)
const increment = () => setCount(count + 1)
const random_number = use.once(() => Math.random())
use.mount(() => {
const interval = setInterval(increment, 1000)
return () => clearInterval(interval)
})
const scene = use.init(() => {
// called whenever dom is connected
const scene = setup_3d_scene_for_example()
return [
scene, // value returned
() => scene.cleanup(), // cleanup called on dom disconnect
]
})
use.defer(() => {
const div = document.querySelector("div")
const rect = div.getBoundingClientRect()
report_rect(rect)
})
undefined value, but gets updated after every render.
const div = use.defer(() => document.querySelector("div"))
console.log(div.value)
// undefined (until the first render is complete)
const handleClick = () => console.log(div.value)
// HTMLDivElement (after the first render)
const count = use.signal(0)
const increment = () => count.value++
html`<span>${count}</span>`
const count = use.signal(2)
const tripled = use.computed(() => count.value * 3)
console.log(tripled.value) //> 6
const count = use.op()
count.load(async() => fetchCount("/count"))
const count = use.load(() => fetchCount("/count"))
const state = use.flatstate({count: 0})
const increment = () => state.count++
watch.stateTree({}).
const whatever = use.watch(() => use.context.state.whatever)
these are not hooks, just access to useful things you may need, so you're allowed to use them under if statements or whatever.
// access your own things on the context
use.context.my_cool_thing
use.element.querySelector("p")
use.shadow.querySelector("slot")
const attrs = use.attrs({
start: Number,
label: String,
["data-active"]: Boolean,
})
attrs.start = 123
attrs.label = "hello"
attrs["data-active"] = true
console.log(attrs.start) // 123
console.log(attrs.label) // "hello"
console.log(attrs["data-active"]) // true
gold and silver are "plain" elements, which are alternatives to LitElement.
they're used as primitives underlying nexus components.
for most cases you probably want to stick with the nexus components, and only use gold/silver when you're doing some funky sorcery, or you yearn to go back to a simpler time without hooks.
consider these imports for the following examples:
import {GoldElement, SilverElement, attributes, flat} from "@benev/slate"
export class MyGold extends GoldElement {
static get styles() { return css`span {color: blue}` }
#attrs = attributes(this as GoldElement, {
label: String
})
#state = flat.state({
count: 0,
})
render() {
return html`
<span>${this.#state.count}</span>
<button @click=${() => this.#state.count++}>
${this.#attrs.label}
</button>
`
}
}
export class MySilver extends SilverElement {
#attrs = attributes(this as SilverElement, {
label: String
})
#state = flat.state({
count: 0,
})
render() {
return html`
<span>${this.#state.count}</span>
<button @click=${() => this.#state.count++}>
${this.#attrs.label}
</button>
`
}
}
if you want plain elements to have reactivity or have the context's css theme applied, you'll want to run them through nexus.components before you register them:
register_to_dom({
...nexus.components({
MyGold,
MySilver,
}),
})
you can extend the context with anything you'd like to make easily available to your components and views:
export const nexus = new Nexus(
new class extends Context {
my_cool_thing = {my_awesome_data: 123}
}
)
but since your components are importing nexus, the above example creates the context at import-time.
you may instead prefer to defer the creation of your context until later, at run-time:
// define your context class
export class MyContext extends Context {
my_cool_thing = {my_awesome_data: 123}
}
// create nexus *without yet* instancing the context
export const nexus = new Nexus<MyContext>()
//
// ... later in another file,
// maybe in your main.ts ...
//
// instance and assign your context, now, at runtime
nexus.context = new MyContext()
// just be sure to assign context *before* you register your components
register_to_dom(myComponents)
if you're using nexus components and views, you'll probably be using these utilities via the use hooks, which will provide a better developer experience.
however, the following utilities are little libraries in their own right, and can be used in a standalone capacity.
signals are a simple form of state management.
this implementation is inspired by preact signals.
import {signal, signals} from "@benev/slate"
const count = signal(0)
const greeting = signal("hello")
count.value++
greeting.value = "bonjour"
console.log(count.value) //> 1
console.log(greeting.value) //> "bonjour"
signals.reaction(() => console.log("doubled", count.value * 2))
//> doubled 2
count.value = 2
//> doubled 4
html`<p>count is ${count}</p>`
const json = signals.op<MyJson>()
console.log(json.isLoading()) //> true
await json.load(async() => {
const data = await fetch_remote_data()
return JSON.parse(data)
})
console.log(json.isReady()) //> true
console.log(json.payload) //> {"your": "json data"}
count.value = 1
const tripled = signals.computed(() => count.value * 3)
console.log(tripled.value) //> 3
const tripled = signals.computed(() => count.value * 3)
console.log(tripled.value) //> 3
count.value = 10
console.log(tripled.value) //> 3 (too soon!)
await signals.wait
console.log(tripled.value) //> 30 (there we go)
import {SignalTower} from "@benev/slate"
const signals = new SignalTower()
signals, but you can create your ownflatstate help you create state objects and react when properties change.
flatstate is inspired by mobx and snapstate, but designed to be simpler. flatstate only works on flat state objects. only the direct properties of state objects are tracked for reactivity. this simplicity helps us avoid weird edge-cases or unexpected footguns.
import {flat} from "@benev/slate"
const state = flat.state({count: 0})
flat.reaction(() => console.log(state.count))
flat.reaction(
// your "collector" function
() => ({count: state.count}),
// your "responder" function
({count}) => console.log(count),
)
const stop = flat.reaction(() => console.log(state.count))
stop() // end this particular reaction
const state = flat.state({amount: 100})
state.amount = 101
console.log(state.amount) //> 100 (old value)
await flat.wait
console.log(state.amount) //> 101 (now it's ready)
const state = flat.state({count: 0})
const rstate = Flat.readonly(state)
state.count = 1
await flat.wait
console.log(rstate.count) //> 1
rstate.count = 2 // !! ReadonlyError !!
const flat1 = new Flat()
const flat2 = new Flat()
import {apply} from "@benev/slate"
const MyElement2 = mixin.flat(flat)(MyElement)
// can also be a class decorator
const elements2 = apply.flat(flat)(elements)
create reactions that listen to both signals and flatstates at the same time.
signals and flat both share the same reaction syntax, but they are separate state management systems. reactor lets you combine both.
slate components and views are already wired up to the reactor and will respond to changes automatically. you only need the reactor when you want to respond to state changes when you're outside of slate components or views.
import {reactor, flatstate, signal} from "@benev/slate"
const state = state({count: 0})
const count = signal(0)
// use the reactor to setup a reaction
reactor.reaction(() => console.log(`
flat count is ${state.count},
signal count is ${count.value}
`))
reactor.reaction(
() => ({a: state.count, b: count.value}),
results => console.log(results),
)
const stop = reactor.reaction(
() => console.log(state.count)
)
// end this reaction
stop()
await reactor.wait
utility for ui loading/error/ready states.
useful for implementing async operations that involve loading indicators.
you get a better dev-experience if you use ops via signals, but here is the documentation for plain ops on their own, without signals.
import {Op} from "@benev/slate"
Op.loading()
//= {status: "loading"}
Op.error("a fail occurred")
//= {status: "error", reason: "a fail occurred"}
Op.ready(123)
//= {status: "ready", payload: 123}
Op.is.loading(op)
//= false
Op.is.error(op)
//= false
Op.is.ready(op)
//= true
const count = Op.ready(123)
const loadingCount = Op.loading()
Op.payload(count)
//= 123
Op.payload(loadingCount)
//= undefined
let my_op = Op.loading()
await Op.load(
// your setter designates which op to overwrite
op => my_op = op,
// your async function which returns the ready payload
async() => {
await nap(1000)
return 123
}
)
use.op() or signals.op() to create OpSignal instances which have nicer ergonomics (an OpSignal is just an op that is wrapped in a signal, plus some handy methods)
const count = signals.op()
// run an async operation
await count.load(async() => {
await sleep(1000)
return 123
})
// check the status of this OpSignal
count.isLoading() //= false
count.isError() //= false
count.isReady() //= true
// grab the payload (undefined when not ready)
count.payload //= 123
// directly assign the op signal
count.setLoading()
count.setError("big fail")
count.setReady(123)
import {loading} from "@benev/slate"
return loading.binary(videoOp, video => html`
<p>video is done loading!</p>
${video}
`)
makeLoadingEffect or makeAnimatedLoadingEffect (if you can figure out how to use 'em)// bad
register_to_dom(
apply.signals(signals)(
apply.flat(flat)(
apply.css(theme)(
requirement.provide(context)(elements)
)
)
)
)
import {Pipe} from "@benev/slate"
// good
Pipe.with(elements)
.to(requirement.provide(context))
.to(apply.css(theme))
.to(apply.flat(flat))
.to(apply.signals(signals))
.to(register_to_dom)
.done() when you want to return the resultain't got no time to document these, but they're there
debounce — my trusty debouncerdeep — utilities for data structures like 'equal' and 'freeze'is — proper type guardsob — map over an object's values with ob(object).map(fn)ev — to listen for eventsel — small syntax to generate html without litnap — sleep for x millisecondsexplode_promise — make an inside-out promisegenerate_id — generate a crypto-random hexadecimal id stringpubsub — easy pub/sub toolrequirement — pass required data to a group of thingsShockDrop and ShockDragDrop — for drag-and-drop integrationswatch — new heavy-duty state management pattern, with deep-watching in state trees, formalized actions, and even undo/redo historyv0.2.0
light_view is now lightViewlight_component is now lightComponentshadow_view is now shadowViewshadow_component is now shadowComponentuse.defer
Signalprep_op_effect replaced by makeLoadingEffect or makeAnimatedLoadingEffectloading effects like loading.binary(op, onReady) and loading.braille(op, onReady)@benev/slate/x/pure.js
pure.js was an alternative entrypoint for node to import the parts of slate that didn't touch any DOM apisimport "@benev/slate/x/node.js"
global.HTMLElement = class {} because extending HTMLElement is the only contact that slate has with the dom at import timenode.js is a little shim that lets you import all of slate in node (maybe for unit testing or to use some tools)interval tool: changed arguments
interval.hz accepts hertz, replacing what used to be called intervalinterval(1, fn) with interval.hz(1, fn)signal.subscribe in favor of signal.onTrashcan (in favor of Trashbin)pub (in favor of pubsub)use.load helper for creating an op and immediately initiating a load operationwhereforref and RefFAQs
frontend web stuff
The npm package @benev/slate receives a total of 309 weekly downloads. As such, @benev/slate popularity was classified as not popular.
We found that @benev/slate demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.