rocky7

Fine grained reactive UI Library.

npm: npm i rocky7

cdn: https://cdn.jsdelivr.net/npm/rocky7/+esm

---

Features

• Small. Fully featured at ~7kB gzip.
• Truly reactive and fine grained. Unlike react and other VDOM libraries which use diffing to compute changes, it use fine grained updates to target only the DOM which needs to update.
• No Magic Explicit subscriptions obviate the need of sample/untrack methods found in other fine grained reactive libraries like solid/sinuous. Importantly, many feel that this also makes your code easy to reason about.
• Signals and Stores. Signals for primitives and Stores for deeply nested objects/arrays.
• First class HMR Preserves Signals/Stores across HMR loads for a truly stable HMR experience.
• DevEx. no compile step needed if you want: choose your view syntax: h for plain javascript or <JSX/> for babel/typescript.
• Rich and Complete. From support for SVG to popular patterns like dangerouslySetInnerHTML, ref to <Fragment> and <Portal /> rocky has you covered.

Ecosystem

rocky7-router	Router with a familiar react-router like API
rocky7-yjs	Bidirectional sync between Rocky7 stores and Yjs documents

Sponsors

You might want to try out grati.co, a no-code programming environment with emacs like extensibility.

Example

Counter - Codesandbox

/** @jsx h **/

import { component, h, render } from "rocky7";

type Props = { name: string };
const Page = component<Props>("HomePage", (props, { signal, wire }) => {
  const $count = signal("count", 0);
  const $doubleCount = wire(($) => $count($) * 2); // explicit subscription
  return (
    <div id="home">
      <p>Hey, {props.name}</p>
      <button
        onClick={() => {
          $count($count() + 1);
        }}
      >
        Increment to {wire($count)}
      </button>
      <p>Double count = {$doubleCount}</p>
    </div>
  );
});

render(<Page name="John Doe" />, document.body);

Motivation

This library is at its core inspired by haptic that in particular it also favours manual subscription model instead of automatic subscriptions model. This oblivates the need of sample/untrack found in almost all other reactive libraries.

Also it borrows the nomenclature of aptly named Signal and Wire from haptic.

It's also influenced by Sinuous, Solid, & S.js

API

Core

signal: create a signal

export const HomePage = component<{ name: string }>(
  "HomePage",
  (props, { signal, wire }) => {
    const $count = signal("count", 0);
    //.. rest of component
  }
);

wire: create a wire

<div id="home">
  <button
    onclick={() => {
      $count($count() + 1);
    }}
  >
    Increment to {wire(($) => $($count))}
  </button>
</div>

store: create a store to hold object/arrays

export const Todos = component("Todos", (props, { signal, wire, store }) => {
  const $todos = store("todos", {
    items: [{ task: "Do Something" }, { task: "Do Something else" }],
  });
  return (
    <ul>
      <Each
        cursor={$todos.items}
        renderItem={(item) => {
          return <li>{item.task}</li>;
        }}
      ></Each>
    </ul>
  );
});

defineContext: define context value

export const RouterContext = defineContext<RouterObject>("RouterObject");

setContext: set context value

const BrowserRouter = component("Router", (props, { setContext, signal }) => {
  setContext(
    RouterContext,
    signal("router", createRouter(window.history, window.location))
  );
  return props.children;
});

getContext: get context value

const Link = component("Link", (props: any, { signal, wire, getContext }) => {
  const router = getContext(RouterContext);
  //... rest of component
});

onMount: triggered on mount

export const Prosemirror = component("Prosemirror", (props, { onMount }) => {
  onMount(() => {
    console.log("component mounted");
  });
  // ...
});

onUnmount: triggered on unmount

export const Prosemirror = component("Prosemirror", (props, { onUnmount }) => {
  onUnmount(() => {
    console.log("component unmounted");
  });
  // ...
});

Helper Components

When: reactive if

<When
  condition={($) => $count($) > 5}
  views={{
    true: () => {
      return <div key="true">"TRUE"</div>;
    },
    false: () => {
      return <div key="false">"FALSE"</div>;
    },
  }}
></When>

Each: reactive map

<Each
  cursor={$todos.items}
  renderItem={(item) => {
    return <li>{wire(item.task)}</li>;
  }}
></Each>

Portal: mount outside of render tree

export const PortalExample = component("PortalExample", (props, utils) => {
  const $active = utils.signal("active", false);
  return (
    <div>
      <button
        onClick={(e) => {
          $active(!$active());
        }}
      >
        toggle modal
      </button>
      <When
        condition={($) => $active($)}
        views={{
          true: () => {
            return (
              <Portal mount={document.body}>
                <div style="position: fixed; max-width: 400px; max-height: 50vh; background: white; padding: 7px; width: 100%; border: 1px solid #000;top: 0;">
                  <h1>Portal</h1>
                </div>
              </Portal>
            );
          },
          false: () => {
            return "";
          },
        }}
      ></When>
    </div>
  );
});

Reciepes

HMR

/** @jsx h **/
import { h, render } from "rocky7";
import { Layout } from "./index";

const renderApp = ({ Layout }: { Layout: typeof Layout }) =>
  render(<Layout />, document.getElementById("app")!);

window.addEventListener("load", () => renderApp({ Layout }));

if (import.meta.hot) {
  import.meta.hot.accept("./index", (newModule) => {
    if (newModule) renderApp(newModule as unknown as { Layout: typeof Layout });
  });
}

Refs

/** @jsx h **/

export const Prosemirror = component("Prosemirror", (props, { onUnmount }) => {
  let container: Element | undefined = undefined;
  let prosemirror: EditorView | undefined = undefined;
  onUnmount(() => {
    if (prosemirror) {
      prosemirror.destroy();
    }
  });
  return (
    <div
      style="
    height: 100%;    position: absolute; width: 100%;"
      ref={(el) => {
        container = el;
        if (container) {
          prosemirror = setupProsemirror(container);
        }
      }}
    ></div>
  );
});

dangerouslySetInnerHTML

/** @jsx h **/
<div dangerouslySetInnerHTML={{ __html: `<!-- any HTML you want -->` }} />

Concepts

Signals

These are reactive read/write variables who notify subscribers when they've been written to. They act as dispatchers in the reactive system.

const $count = signal("count", 0);

$count(); // Passive read (read-pass)
$count(1); // Write

The subscribers to signals are wires, which will be introduced later. They subscribe by read-subscribing the signal.

Stores

Stores are for storing nested arrays/objects and also act as dispatchers in the reactive system. And like signals, stores can also be read subsribed by wires. Outside of wires, they can be read via reify function. Writes can be done via produce function immer style.

const val = { name: "Jane", friends: [{ id: "1", name: "John" }] };
const $profile = store("profile", val);

// Passive read (read-pass)
const friends = reify($profile.friends);
console.log(friends.length);
// Write
produce($profile.friends, (friends) => {
  friends.push({ id: "2", name: "John Doe 2" });
});

Wires

These are task runners who subscribe to signals/stores and react to writes. They hold a function (the task) and manage its subscriptions, nested wires, run count, and other metadata. The wire provides a $ token to the function call that, at your discretion as the developer, can use to read-subscribe to signals.

wire(($) => {
  // Explicitly subscribe to count signal using the subtoken "$"
  const count = $(count);

  // also possible to subscribe to a stores using "$" subtoken
  const friendsCount = $($profile.friends);
  return count + friendsCount;
});