npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

superfine

v8.2.0

Published

Minimal view layer for building web interfaces.

Downloads

449

Readme

Superfine

Superfine is a minimal view layer for building web interfaces. Think Hyperapp without the framework—no state machines, effects, or subscriptions—just the absolute bare minimum (1 kB minified+gzipped). Mix it with your favorite state management library or use it standalone for maximum flexibility.

Here's the first example to get you started. Try it here—no build step required!

<!DOCTYPE html>
<html lang="en">
  <head>
    <script type="module">
      import { h, text, patch } from "https://unpkg.com/superfine"

      const setState = (state) =>
        patch(
          document.getElementById("app"),
          h("main", {}, [
            h("h1", {}, text(state)),
            h("button", { onclick: () => setState(state - 1) }, text("-")),
            h("button", { onclick: () => setState(state + 1) }, text("+")),
          ])
        )

      setState(0)
    </script>
  </head>
  <body>
    <main id="app"></main>
  </body>
</html>

When describing how a page looks in Superfine, we don't write markup. Instead, we use the h() and text() functions to create a lightweight representation of the DOM (or virtual DOM for short), and patch() to actually render the DOM.

Superfine won't re-create the entire DOM every time we use patch(). By comparing the old and new virtual DOM we are able to change only the parts of the DOM that need to change instead of rendering everything from scratch.

Next up, let's take a look at a simple todo app. You can only add or cross off todos with it. Can you figure out what's happening just by poking around the code a bit? Have a go here.

<script type="module">
  import { h, text, patch } from "https://unpkg.com/superfine"

  const updateValue = (state, value) => ({ ...state, value })

  const addTodo = (state) => ({
    ...state,
    value: "",
    todos: state.todos.concat(state.value).filter(any => any),
  })

  const setState = (state) => {
    patch(
      document.getElementById("app"),
      h("main", {}, [
        h("h2", {}, text("To do list")),
        h("section", {}, [
          h("input", {
            type: "text",
            value: state.value,
            oninput: ({ target }) =>
              setState(updateValue(state, target.value)),
          }),
          h("button",
            { onclick: () => setState(addTodo(state)) },
            text("Add todo")
          ),
        ]),
        h("ul", {},
          state.todos.map((todo) =>
            h("li", {}, [
              h("label", {}, [
                h("input", { type: "checkbox" }),
                h("span", {}, text(todo))
              ]),
            ])
          )
        ),
      ])
    )
  }

  setState({ todos: [], value: "" })
</script>

Find more examples here

Now it's your turn to take Superfine for a spin. Can you add a button to clear all todos? How about bulk-marking as done? If you get stuck or would like to ask a question, just file an issue and I'll try to help you out—have fun! ✨

Installation

npm install superfine

Then with a module bundler import like you would anything else.

import { h, text, patch } from "superfine"

Or right in your browser without a build step.

<script type="module">
  import { h, text, app } from "https://unpkg.com/superfine"
</script>

Top-Level API

h(type, props, [children])

Create them virtual DOM nodes! h() takes the node type; an object of HTML or SVG attributes, and an array of child nodes (or just one child node).

h("main", { class: "relative" }, [
  h("label", { for: "outatime" }, text("Destination time:")),
  h("input", { id: "outatime", type: "date", value: "2015-10-21" }),
])

text(string)

Create a virtual DOM text node.

h("h1", {}, text("1.21 Gigawatts!?!"))

patch(node, vdom)

Render a virtual DOM on the DOM efficiently. patch() takes an existing DOM node, a virtual DOM, and returns the freshly patched DOM.

const node = patch(
  document.getElementById("app"),
  h("main", {}, [
    // ...
  ])
)

Attributes API

Superfine nodes can use any of the HTML attributes, SVG attributes, DOM events, and also keys.

class:

To specify one or more CSS classes, use the class attribute. This applies to all regular DOM and SVG elements alike. The class attribute expects a string.

const mainView = h("main", { class: "relative flux" }, [
  // ...
])

style:

Use the style attribute to apply arbitrary CSS rules to your DOM nodes. The style attribute expects a string.

Important: We don't recommend using the style attribute as the primary means of styling elements. In most cases, class should be used to reference classes defined in an external CSS stylesheet.

const alertView = h("h1", { style: "color:red" }, text("Great Scott!"))

key:

Keys help identify nodes whenever we update the DOM. By setting the key property on a virtual DOM node, you declare that the node should correspond to a particular DOM element. This allows us to re-order the element into its new position, if the position changed, rather than risk destroying it.

Important: Keys must be unique among sibling nodes.

import { h } from "superfine"

export const imageGalleryView = (images) =>
  images.map(({ hash, url, description }) =>
    h("li", { key: hash }, [
      h("img", {
        src: url,
        alt: description,
      }),
    ])
  )

Recycling

Superfine will patch over server-side rendered HTML, recycling existing content instead of creating new elements. This technique enables better SEO, as search engine crawlers will see the fully rendered page more easily. And on slow internet or slow devices, users will enjoy faster time-to-content as HTML renders before your JavaScript is downloaded and executed.

<!DOCTYPE html>
<html lang="en">
  <head>
    <script type="module">
      import { h, text, patch } from "https://unpkg.com/superfine"

      const setState = (state) =>
        patch(
          document.getElementById("app"),
          h("main", {}, [
            h("h1", {}, text(state)),
            h("button", { onclick: () => setState(state - 1) }, text("-")),
            h("button", { onclick: () => setState(state + 1) }, text("+")),
          ])
        )

      setState(0)
    </script>
  </head>
  <body>
    <main id="app"><h1>0</h1><button>-</button><button>+</button></main>
  </body>
</html>

Notice that all the necessary HTML is already served with the document.

Superfine expects the markup to be identical between the server and the client. Treat mismatches as bugs and fix them! Now you just need a way to send content to browsers.

JSX

JSX is a language syntax extension that lets you write HTML tags interspersed with JavaScript. To compile JSX to JavaScript, install the JSX transform plugin, and create a .babelrc file in the root of your project like this:

{
  "plugins": [["transform-react-jsx", { "pragma": "h" }]]
}

Superfine doesn't support JSX out of the box, but adding it to your project is easy.

import { h, text } from "superfine"

export default (type, props, ...children) =>
  typeof type === "function"
    ? type(props, children)
    : h(
        type,
        props || {},
        []
          .concat(...children)
          .map((any) =>
            typeof any === "string" || typeof any === "number" ? text(any) : any
          )
      )

Import that everywhere you're using JSX and you'll be good to go. Here's a working example.

import jsx from "./jsx.js"
import { patch } from "superfine"

License

MIT