Forem: chrisfrank

Uninformed: nostalgically simple forms for React & Preact

chrisfrank — Mon, 10 Jun 2019 11:57:08 +0000

Forms in Rails do two useful things automatically that I miss when I'm working in other frameworks:

They submit data without reloading the page.
They disable themselves on submit, so that you can't accidentally submit data twice by double-clicking.

These are great defaults! In a web app in 2019, I should have to write code to disable this behavior -- but I've found myself re-implementing it from scratch in several React projects.

I wrote Uninformed to bring these defaults to the React ecosystem. Here's how to use Uninformed in an app:

import { Form } from 'uninformed';
import React from 'react';

const SignupForm = props => (
  <Form action="/api/signups" onSuccess={props.handleSuccess}>
    <input type="email" name="email" required />
    <input type="submit" value="Sign Up" />
  </Form>
)

That’s it! No onChange handlers, no Input components, just a lightly-enhanced HTML form that disables itself on submit, sends data to a server via an XMLHttpRequest, and re-enables itself after the server responds. When you need more power -- for setting request headers, running input validation, etc -- Uninformed lets you customize its behavior by passing functions as props. See the README for more info.

Uninformed is brand new, and I'd love to hear your ideas for how to improve it! Please feel free to file issues, pull requests, or ask questions in the comments below.

(Cover image by Kelly Sikkema via Unsplash)

Introducing nanostyled: CSS-in-JS without CSS-in-JS

chrisfrank — Mon, 01 Oct 2018 20:01:29 +0000

Nanostyled is a tiny library (< 1 Kb unminified) for building styled React components. It tries to combine the flexible, component-based API of CSS-in-JS libraries with the extremely low overhead of plain CSS:

	Low overhead	Flexible, component-based API
Plain CSS	✅	❌
CSS-in-JS	❌	✅
nanostyled	✅	✅

Like the CSS-in-JS libraries that inspired it -- 💕 to styled-components -- nanostyled lets you build UI elements with complex default styles, then tweak those styles throughout your app via props:

<Button>A nice-looking button</Button>
<Button color="blue">A nice-looking button that is blue.</Button>

Unlike a CSS-in-JS library, nanostyled doesn't use any CSS-in-JS. Instead, it's designed to accompany a functional CSS framework like Tachyons or Tailwind. Nanostyled makes functional CSS less verbose, and easier to extract into props-controlled components.

Check out nanostyled on npm for installation and usage instructions, or read on for more context.

Functional CSS?

The basic premise of a functional CSS framework is that you can build complex styles by composing tiny CSS utility classes.

A button styled with Tachyons might look like this in markup:

<button class="bg-blue white br2 pa2">Button</button>

That's a button with a blue background, white text, rounded corners (br2), and some padding on all sides (pa2).

holy hell this is the worst thing I've ever seen
-Adam Wathan, author of Tailwind.css

It's true. Functional CSS is ugly, and defies decades-old best practices re: separating content from styling.

On the other hand, styling with functional CSS scales well across large projects, enforces visual consistency, and makes it easy to build new UI elements without writing any new CSS. Adam Wathan, creator of, Tailwind, defends the approach elegantly here.

Nanostyled makes functional CSS easier to abstract into components, without giving up any of its strengths.

Why building flexible components with functional CSS in React is hard

To make working with functional CSS less verbose, you can extract long class strings into self-contained React components:

const Button = ({ className = '', ...rest }) => (
  <button className={`bg-blue white br3 pa2 fw7 ${className}`} {...rest} />
)

The problem, in this case, is that there's no good way to render our <Button> with a different background color. Even though it accepts a className prop, writing <Button className="bg-red" /> won't necessarily render a red button.

Max Stoiber's recent Twitter poll is a good illustration of why:

How well do you know CSS? Given these classes:
.red { color: red; }
.blue { color: blue; }
Which color would these divs be?
<div class="red blue">
<div class="blue red">

The correct answer, which 57% of respondents got wrong, is that both divs would be blue.

You can't know the answer by looking at just the HTML. You need to look at the CSS, because when two conflicting CSS classes have the same specificity, their order in the markup is irrelevant. Which class wins depends on which one is defined last in the stylesheet.

So to build a robust <Button> with functional CSS, we need to be able to

Declare some stock CSS classes that style it
Expose a convenient API for replacing some of the stock classes with alternatives

This second requirement is key for avoiding counterintuitive class collisions like in Max's poll, and it's the thing nanostyled makes easy.

Building flexible components with nanostyled and style props

Nanostyled works by mapping style props onto class names from your functional CSS framework of choice.

Style props can be named whatever you like, and can each hold any number of CSS classes:

A nanostyled Button

import nanostyled from 'nanostyled';
// This example uses CSS classes from Tachyons
import 'tachyons/css/tachyons.css';

// A Button with three style props:
const Button = nanostyled('button', {
  color: 'white',
  bg: 'bg-blue',
  base: 'fw7 br3 pa2 sans-serif f4 bn input-reset'
});

const App = () => (
  <div>
    <Button>Base Button</Button>
    <Button bg="bg-yellow">Yellow Button</Button>
  </div>
);

/* rendering <App /> produces this markup:
<div>
  <button class="white bg-blue fw7 br3 pa2 sans-serif f4 bn input-reset">Base Button</button>
  <button class="white bg-yellow fw7 br3 pa2 sans-serif f4 bn input-reset">Yellow Button</button>
</div>
*/

When a nanostyled(element) renders, it consumes its style props and merges them into an HTML class string, as per above.

It's totally to you which style props to use. The <Button> above has an API that would make it easy to restyle color or background-color via the color and bg props, but hard to change other styles without totally rewriting the base prop.

A more flexible nanostyled Button

By using more style props, we can make a more flexible button:

import nanostyled from 'nanostyled';
import 'tachyons/css/tachyons.css';

const FlexibleButton = nanostyled('button', {
  color: 'white', // white text
  bg: 'bg-blue', // blue background
  weight: 'fw7', // bold font
  radius: 'br3', // round corners
  padding: 'pa2', // some padding
  typeface: 'sans-serif', // sans-serif font
  fontSize: 'f4', // font size #4 in the Tachyons font scale
  base: 'bn input-reset', // remove border and appearance artifacts
});

Rendering a stock <FlexibleButton /> will produce the same markup as its simpler relative. But it's much easier to render alternate styles:

<FlexibleButton
  bg="bg-light-green"
  color="black"
  weight="fw9"
  radius="br4"
>
  Button with a green background, black text, heavier font, and rounder corners
</FlexibleButton>

When you need a variation that you didn't plan for in your style props, you can still use the className prop:

<FlexibleButton className="dim pointer">
  A button that dims on hover and sets the cursor to 'pointer'
</FlexibleButton>

Sharing style props across multiple components

If you're building multi-component UI kits with nanostyled, I recommend sharing at least a few basic style props across all your components. Otherwise it gets hard to remember which components support, say, a color prop, and which ones don't.

I usually start here:

import React from "react";
import ReactDOM from "react-dom";
import nanostyled from "nanostyled";
import "tachyons/css/tachyons.css";

// The keys in this styleProps will determine which style props
// our nanostyled elements will accept:
const styleProps = {
  bg: null,
  color: null,
  margin: null,
  padding: null,
  font: null,
  css: null
};

/* 
Why choose those keys, in particular? For everything except `css`, 
it's because the elements in the UI kit probably will have some default 
bg, color, margin, padding, or font we'll want to be able to easily override via props.

The `css` prop is an exception. I just like being able to use it instead of `className`.
*/

// Box will support all styleProps, but only use them when we explicitly pass values
const Box = nanostyled("div", styleProps);
/*
<Box>Hi!</Box>
renders <div>Hi!</div>

<Box color="red">Hi!</Box>
renders <div class="red">Hi!</div>
*/

// Button will also support all styleProps, and will use some of them by default
const Button = nanostyled("button", {
  ...styleProps,
  bg: "bg-blue",
  color: "white",
  padding: "pa2",
  font: "fw7",
  // I use a 'base' prop to declare essential component styles that I'm unlikely to override
  base: "input-reset br3 dim pointer bn"
});
/*
<Button>Hi!</Button>
renders
<button class="bg-blue white pa2 dim pointer bn input-reset>Hi!</button>
*/

// Heading uses styleProps, plus some extra props for fine-grained control over typography
const Heading = nanostyled("h1", {
  ...styleProps,
  size: "f1",
  weight: "fw7",
  tracking: "tracked-tight",
  leading: "lh-title"
});

// Putting them all together....
const App = () => (
  <Box padding="pa3" font="sans-serif">
    <Heading>Styling with Nanostyled</Heading>
    <Heading tracking={null} tag="h2" size="f3" weight="fw6">
      A brief overview
    </Heading>
    <Heading tag="h3" weight="fw4" size="f5" tracking={null} css="bt pv3 b--light-gray">
      Here are some buttons:
    </Heading>
    <Button>Base Button</Button>
    <Button css="w-100 mv3" padding="pa3" bg="bg-green">
      Wide Green Padded Button
    </Button>
    <Box css="flex">
      <Button css="w-50" margin="mr2" bg="bg-gold">
        50% Wide, Gold
      </Button>
      <Button css="w-50" margin="ml2" bg="bg-red">
        50% wide, Red
      </Button>
    </Box>
  </Box>
);

const rootElement = document.getElementById("root");
ReactDOM.render(<App />, rootElement);

This full example is available on CodeSandbox for you to experiment with.

Nanostyled is available on npm, and you can contribute to the library on GitHub.

Dynamically filter data via URL params with Rack::Reducer

chrisfrank — Thu, 29 Mar 2018 17:48:26 +0000

Whether you're building a tiny API or a giant monolith, your app probably needs to render a list of database records somewhere. And you probably want those records to be filterable via URL params, like so:

GET /artists?genre=electronic&sort=name

It'd be nice to sort or filter when the relevant params are present, and return a sensible default dataset otherwise.

GET /artists?name=blake` => artists named 'blake'
GET /artists?genre=electronic&sort=name => electronic artists, sorted by name
GET /artists => all artists

You could conditionally apply filters with hand-written if statements, but that approach gets uglier the more filters you add.

In Rails, you could use Plataformatec's venerable HasScope gem.

But what if you're working in Roda, Sinatra, or Hanami? Even in Rails, what if you'd rather write dedicated query objects than pollute your models and controllers with filtering code?

Rack::Reducer can help. It's a gem that maps incoming URL params to an array of filter functions you define, applies only the applicable filters, and returns your filtered data. It can make your controller logic as minimal as...

@artists = Artist.reduce(params)

...or, if magical, implicit code isn't your thing, you can call Rack::Reducer as a function to build more explicit queries -- maybe right in your controllers, maybe in dedicated query objects, or really anywhere you like.

# app/controllers/artists_controller.rb
class ArtistsController < ApplicationController
  def index
    @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
      ->(name:) { where('lower(name) like ?', "%#{name.downcase}%") },
      ->(genre:) { where(genre: genre) },
      ->(sort:) { order(sort.to_sym) },
    ])
    render json: @artists
  end
end

Rack::Reducer works in any Rack-compatible app, with any ORM, and has no dependencies beyond Rack itself. Full documentation is on GitHub. Whether you work in Rails, Sinatra, Roda, Hanami, or raw Rack, I hope it can be of use to you.