Ripple

Atom based state management for Haunted web components, heavily inspired by the Jotai project.

Note Due to some React specific implementations that do not overlap with Haunted, this project is required. It is possible in the future that this project may not be required if the internals of Jotai use only React apis that can be aliased by Haunted.

Installation

npm i @martel/ripple haunted

Define an atom

import { atom } from '@martel/ripple'

export const countAtom = atom(0)

Use the atom

import { component, html } from 'haunted'
import { useAtom } from '@martel/ripple'

function Counter() {
  const [count, setCount] = useAtom(countAtom)

  return html`
    <div id="count">${count}</div>
    <button type="button" @click=${() => setCount(count + 1)}>Increment</button>
  `
}

customElements.define('my-counter', component(Counter))

Define an atomList

import { atomList } from '@martel/ripple'

export interface IPost {
  id: number
  userId: number
  title: string
  body: string
}

export const postsAtom = atomList<IPost>([
  { id: 1, userId: 1, body: 'foo', title: 'bar' },
  { id: 2, userId: 1, body: 'baz', title: 'bar' },
])

Use the atomList

import { component, html } from 'haunted'
import { repeat } from 'lit-html/directives/repeat.js'
import { useAtomList } from '@martel/ripple'

function PostList() {
  const [posts] = useAtomList(postsAtom, { hydrateList: true }) // Load list of IPost[], not string[]

  return html`
    <style>
      :host {
        display: block;
        box-sizing: border-box;
      }
    </style>
    ${posts
      ? repeat(
          posts as IPost[],
          (p) => p.id,
          (p) => html`<p>${p.body}</p>`,
        )
      : ''}
  `
}

customElements.define('my-posts', component(PostList))

Define an effect

import { atomList, atomEffect } from '@martel/ripple'

export interface IPost {
  id: number
  userId: number
  title: string
  body: string
}

export const postsAtom = atomList<IPost>([])

export const postsLoadEffect = atomEffect(async (get, set) => {
  const currentPostCount = get(countAtom) // any `get` calls to other atoms will recompute this effect for any outside changes
  if (currentPostCount < 1) {
    const posts = await fetch('http://jsonplaceholder.typicode.com/posts').then((res) => (res.ok ? res.json() : []))
    set(postsAtom, posts)
    set(countAtom, posts.length) // calls to set an atom will trigger a recompute of any other subscribers outside of this immediate effect
  }
})

Use the effect

import { component, html } from 'haunted'
import { repeat } from 'lit-html/directives/repeat.js'
import { useAtomList, useAtomEffect } from '@martel/ripple'

function PostList() {
  const [posts] = useAtomList(postsAtom, { hydrateList: true }) // Load list of IPost[], not string[]

  useAtomEffect(postsLoadEffect) // Handle async fetching

  return html`
    <style>
      :host {
        display: block;
        box-sizing: border-box;
      }
    </style>
    ${posts
      ? repeat(
          posts as IPost[],
          (p) => p.id,
          (p) => html`<p>${p.body}</p>`,
        )
      : ''}
  `
}

customElements.define('my-posts', component(PostList))

Define a ref

import { atomRef } from '@martel/ripple'

export interface IPost {
  id: number
  userId: number
  title: string
  body: string
}

export const postsCountRef = atomRef<number>((get) => {
  const postsCount = get(postsAtom)?.length // anytime postsAtom changes, this ref will recompute

  return postsCount || 0
})

Use a ref

import { component, html } from 'haunted'
import { useAtomRef } from '@martel/ripple'

function PostsCount() {
  const count = useAtomRef(postsCountRef)

  return html` <div id="count">${count}</div> `
}

Atom Storage

Init atom stores (required only for indexeddb usage of non default db or stores)

Define any stores that can be in use for any of your component atoms.

import { initAtomStorage } from '@martel/ripple'

// default db name is rpldata
// default store name is rpldata
// default version is 1
initAtomStorage({ version: 1 }, ['posts'])

Define an atom backed by storage

LocalStorage (default)

import { atom } from '@martel/ripple'

// default storage is 'local'
const postAtom = atom({ id: '1', body: 'test' }, { key: 'post:1' })
// const postAtom = atom({ id: '1', body: 'test' }, { key: 'post:1', type: 'local' })

SessionStorage

import { atom } from '@martel/ripple'

const postAtom = atom({ id: '1', body: 'test' }, { key: 'post:1', type: 'session' })

Indexeddb

import { atom } from '@martel/ripple'

const postAtom = atom({ id: '1', body: 'test' }, { key: 'post:1', type: 'indexeddb', store: 'posts' })