Forem: Nayaab Khan

Swift-like React: Can We? Should We?

Nayaab Khan — Tue, 12 Apr 2022 05:04:05 +0000

⚠️ This is just an experiment that is clearly not meant for production.

After playing with SwiftUI for a few days I was impressed by its syntax and
wanted to see if I can write React this way. Possibly an absurd thought, but why not.

It turned out like this:

const SandwichItem = (sandwich: Sandwich) =>
  HStack(
    Image(sandwich.thumbnailName)
      .rounded(8),

    VStack(
      Text(sandwich.name)
        .as('h2')
        .variant('title'),
      Text(`${sandwich.ingredientCount} ingredients`)
        .as('small')
        .variant('subtitle'),
    ),
  )
    .alignment('center')
    .spacing('medium')

render(root, List(sandwiches, SandwichItem))

To compare, this is what it would look like in JSX:

const SandwichItem = ({ sandwich }: SandwichItemProps) => (
  <HStack alignment="center" spacing="medium">
    <Image src={sandwich.thumbnailName} cornerRadius={8} />

    <VStack>
      <Text as="h2" variant="title">
        {sandwich.name}
      </Text>
      <Text as="small" variant="subtitle">
        {sandwich.ingredientCount} ingredients
      </Text>
    </VStack>
  </HStack>
)

render(
  root,
  <List
    items={sandwiches}
    renderItem={(sandwich) => <SandwichItem sandwich={sandwich} />}
  />,
)

Syntax is subjective. I’m sure some of you will prefer one over the other for
various reasons. Besides personal preferences, a few things do stand out with this syntax:

It is a composition of function calls, nothing on top of JavaScript.
Components take required inputs as arguments.
Modifications are done through chained-functions, called modifiers.

I particularly like the separation between inputs and modifiers. In JSX, both would be props.

Text('Professional photographer')
  .variant('subtitle')
  .color('muted')

Inputs could be primitive types like a string or object types like an array of components.

VStack(
  Text('Your Messages').variant('title'),
  Text(`${unread} messages`).variant('subtitle'),
)

Polymorphic, Chain-able Modifiers

Modifiers are just functions. What makes them interesting is that they can be shared by multiple components and implemented independently.

Text(/*...*/)
  .color('muted')

HStack(/*...*/)
  .color('muted')
  .align('start')
  .spacing('gutter')

AutoGrid(/*...*/)
  .minWidth(360)
  .spacing('small')

Let’s see a couple of modifier implementations:

// Colorable.ts
export interface Colorable extends JSX.Element {
  color: <T extends Colorable>(this: T, color: string) => T
}

export function color<T extends Colorable>(this: T, color: string) {
  const style = {
    ...this.props.style,
    color,
  }

  this.props = {
    ...this.props,
    style,
  }

  return this
}

// Fontable.ts
type Font = keyof typeof fontVariants

export interface Fontable extends JSX.Element {
  font: <T extends Fontable>(this: T, font: Font) => T
}

export function font<T extends Fontable>(this: T, font: Font) {
  const style = {
    ...this.props.style,
    ...fontVariants[font],
  }

  this.props = {
    ...this.props,
    style,
  }

  return this
}

A component can now implement these traits:

// Text.tsx
import { Fontable, font } from '@modifiers/Fontable'
import { Colorable, color } from '@modifiers/Colorable'

export default function Text(text: string): Fontable & Colorable {
  const element = <span>{text}</span>

  return {
    ...element,
    font,
    color,
  }
}

And now the component could be invoked using:

Text('Hello, world!')
  .font('title')
  .color('hotpink')

A component can implement multiple modifiers which can be chained. Also, a modifier could be implemented by many components, making them polymorphic.

ℹ️ You can see more components and modifiers at https://github.com/nayaabkhan/swift-react.

Problems

There are a few things I noticed that don’t work. Very likely, there are be more.

useContext doesn’t work. But <Context.Consumer /> works fine.
React Developer Tools doesn’t show the components in the inspector.

I suspect this is because React cannot identify our components as we don’t use either JSX or createElement when creating them. If you find more problems, please report them in the comments. And if you know work-arounds, they’re very welcome.

But, Why?

Finally, let’s address the elephant in the room. Why all this trouble?

Maybe I’m bike shedding. But experimenting and sharing with everyone is the only way to know. Maybe this resonates with others and becomes a thing. Or gets buried in the rubble of bad ideas. Who knows, but it was worth it for the fun I had.

I had a great time authoring React this way. Maybe this kind of syntactic change can have unexpected, but useful impact.

Allow component API designers to be very specific of expected input types. For instance, Text only accepts strings or markdown instead of any kind of ReactNode.
Make it easier to share the common API along with its implementation using modifiers.
Introduce higher-level constructs like Identifiers.
Swap React with something else without any impact on the users of the library.

In closing, I hope you try it out on CodeSandbox, have fun, and share your thoughts.

Until next time 👋.

Benefits Of Categorising Components By Use-Case

Nayaab Khan — Mon, 28 Mar 2022 11:08:20 +0000

Organising things feels good. If you have a design system, you might have organised the components with categories.

Besides cleaner organisation, is there something that we can get out of good categorisation?

It turns out there's a lot.

Meet the Categories

Over the years, these are the categories I've come up. This categorisation is based on use case. Almost all components fall into one of these.

Structural.

These are the visible or invisible components that provide structure to your app. Examples include Stack, Grid, and Columns.

Informational.

These components are used to display information to the users. They may display this information using text, icons, colors, and so on. Examples include Badge and Tooltip.

Input.

These components are used to get information from the users and often used inside a form. Examples include TextField, AutoComplete, CheckboxList, and Select.

Action.

These components are used to perform an action immediately. Examples include Button and Menu.

Feedback.

These components are used to provide a feedback as a response. Examples include Toast and Progress.

Navigational.

These components are used to provide navigational aid to the users. Examples include Link, Breadcrumb, and Pagination.

Let's go through the benefits of this kind of categorisation.

Benefit 1: Clear Distinction

Often we find components used in a way they're not meant to be. A very common one is the use of dropdowns as menu of actions.

Depending on your designs, they may even look very similar. But functionally, they are different, and the astute among you would already know it.

If you try to sort them in one of the categories we saw before, they start making sense. One provides a menu to input a selection, but not act immediately upon it, while the other provides a menu for actions that happens immediately on selection.

Naming is hard and cannot be decoupled from opinions. In the wild, often they're called select and menu respectively. If you're looking to get insipred, the Component Name Matrix is a great place to start.

Another common mistake is using a button that looks like a link to navigate to another page. Or using a link that looks like a button to perform an action. While it is okay to have such variants, categorising them thoughtfully can help you avoid misuse and help you write clear do's and dont's.

Benefit 2: Precise Semantics

A lot of components that fall in the same category share semantic traits. Informational components like Badge and Alert display part of their information using colors, often called the tone of the information they're displaying. Similarly, actions share the nature of the action being performed.

Once you have a category, you can easily find the components that share the same semantic traits and create semantic tokens for them.

Benefit 3: Correct Features By Common Traits

Similar to how the category can surface the semantics of the components, it also helps in aiding the API design and features of a component. More precisely, what should and should not be in the API.

Going back to the example of LinkButton and ButtonLink. The former should support actional properties like onClick while the later should support navigational properties like href.

This can help you avoid common pitfalls found on the web. Like in this case, using a button as a link and vice-versa. Have you even tried opening a link in a new tab just to find out that you're looking at a button disguised as a link? It is a frustrating experience.

Closing

I find this topic very interesting and certainly intend to write more in-depth posts on it. There's so much more to uncover.

For instance, the input components Select, CheckboxList, and RadioList are all choice components and could be used interchangeably depending on the space available, amount of choices, and ability to select multiple choices.

Once you start seeing the patterns, interesting facts emerge. And I hope to keep sharing them as I discover them.

Cheers!

Essential Layout Components For Your Design System

Nayaab Khan — Sun, 20 Mar 2022 09:25:20 +0000

If your app uses a component based library/framework like React, Vue, or Svelte, leverage the power of re-usable layout components. Go a level higher in the abstraction ladder.

In this article, I'll show you a system of solid layout components with their features and API. These are common and versatile enough to be used for most products and teams. I promise you once you meet these layout, you'll start seeing them everywhere.

In the end, there's a CodeSandbox that uses all these components to build a real use case: a responsive listing of product cards.

I'd like to credit upfront the excellent Braid Design System by Seek-OSS. All the components are heavily inspired from it. You should definitely check it out.

1. Stack

The most common way to layout your interface elements is a vertical Stack. They are everywhere.

<Stack space="large">
  <Placeholder height={48} />
  <Placeholder height={48} />
  <Placeholder height={48} />
</Stack>

API

type StackProps = {
  // The element used for the root node.
  as?: 'div' | 'span' | 'ol' | 'ul' // Feel free to change these as per your uses
  // Defines the spacing between the items.
  space?: 'small' | 'medium' | 'large' // All of your spacing tokens
  // Sets the horizontal alignment of the items.
  align?: 'start' | 'center' | 'end' | 'stretch'
  // The items to layout in the stack.
  children: React.ReactNode
}

2. Columns and Column

The next most common layout is a single row of Columns.

<Columns space="medium">
  <Column><Placeholder height={60} /></Column>
  <Column><Placeholder height={60} /></Column>
</Columns>

Collapsing

A common need is to collapse the columns to a stack below a certain size. This can be implemented using ResizeObserver (and hopefully soon using Container Queries).

Alignments

Columns support alignments in both directions.

Individual column sizing

We have a Column component to wrap each column that provides ability to size itself in different implicit and explicit sizes.

<Stack space="medium">
  <Columns space="xsmall">
    <Column width="content">
      <Placeholder height={30} label="content" />
    </Column>
    <Column>
      <Placeholder height={30} label="fluid" />
    </Column>
  </Columns>
  <Columns space="xsmall">
    <Column width="1/5">
      <Placeholder height={30} label="1/5" />
    </Column>
    <Column>
      <Placeholder height={30} label="fluid" />
    </Column>
  </Columns>
  <Columns space="xsmall">
    <Column width="1/4">
      <Placeholder height={30} label="1/4" />
    </Column>
    <Column>
      <Placeholder height={30} label="fluid" />
    </Column>
  </Columns>
  <Columns space="xsmall">
    <Column width="1/3">
      <Placeholder height={30} label="1/3" />
    </Column>
    <Column>
      <Placeholder height={30} label="fluid" />
    </Column>
  </Columns>
  ...
</Stack>

API

type ColumnsProps = {
  // The element used for the root node.
  as?: 'div' | 'span' | 'ol' | 'ul'
  // Defines the spacing between the items.
  space?: 'small' | 'medium' | 'large' // All of your spacing tokens
  // Collapse items to a stack below this size.
  collapseBelow?: number
  // Sets the horizontal alignment of the items.
  align?: 'start' | 'center' | 'end' | 'stretch'
  // Sets the vertical alignment of the items.
  alignY?: 'start' | 'center' | 'end'
  // The columns.
  children: React.ReactNode
}

Cluster

This is very similar to Columns but it allows the items to wrap if needed. Most commonly used to show a list of badges.

<Cluster space="small">
  <Tag tone="positive" weight="subtle" label="Confirmed" icon="IconCalendar" />
  <Tag tone="cautional" weight="subtle" label="Pending" icon="IconApple" />
  <Tag tone="informational" weight="subtle" label="Hired" icon="IconRemote" />
  <Tag tone="neutral" weight="subtle" label="Refunded" icon="IconLike" />
  <Tag tone="promotional" weight="subtle" label="New" icon="IconHeart" />
</Cluster>

Clusters also support collapsing and alignments in both directions just like Columns.

API

type ClusterProps = {
  // The element used for the root node.
  as?: 'div' | 'span' | 'ol' | 'ul'
  // Defines the spacing between the items.
  space?: 'small' | 'medium' | 'large'
  // Collapse items to a stack below this size.
  collapseBelow?: number
  // Sets the horizontal alignment of the items.
  align?: 'start' | 'center' | 'end'
  // Sets the vertical alignment of the items.
  alignY?: 'start' | 'center' | 'end'
  // The items to lay out in this cluster.
  children: React.ReactNode
}

AutoGrid

Auto grid is basically a component abstraction for repeat-auto-minmax.

<AutoGrid space="medium" minItemWidth={120}>
  <Placeholder />
  <Placeholder />
  <Placeholder />
  <Placeholder />
  <Placeholder />
  <Placeholder />
  <Placeholder />
</AutoGrid>

API

type AutoGridProps = {
  // The element used for the root node.
  as?: 'div' | 'section' | 'ul' | 'ol'
  // The minimum width for items to shrink to before the grid starts wrapping to make space.
  minItemWidth: number
  // The gap between the items or the column gap if spaceY is present.
  space?: 'small' | 'medium' | 'large'
  // The row gap between the items.
  spaceY?: 'small' | 'medium' | 'large'
  // Items inside the AutoGrid.
  children: React.ReactNode
}

Layout Components In Action

Now that we've seen the components. Let's see them in action.

I've used NextJS and Vanilla-Extract to style the components. But you can, of course, use any solution down to plain CSS.

codesandbox.io

Let's appreciate all the functionality going on in the demo:

We have a sidebar that collapses on smaller screens.
The product grid is responsive
The card itself has two layouts: horizontal and vertical and it responds based on available space.
The badges inside the Cluster can wrap if required.
The buttons also respond to available size and collapse if too narrow.

All this with just a system of well thought out components. Totally declarative, readable, and re-usable.

And we've only covered the most basic common denominator of layout components. You can do much more depending on your use case. Like:

Add a Spacer component to create flexible space between Stack or Column items.
Add a prop to make column items fill the available space inside the Column.
Add a FixedGrid with explicit column and row counts to create a rigid grid.

But I hope that you find this system inspiring and already have ideas to build on top of this. Feel free to fork the sandbox or the repo to use it as a starting point.

I'll see you next time! 👋🏻

Vanilla-Extract & Stitches: A Comparison

Nayaab Khan — Mon, 14 Mar 2022 08:37:16 +0000

How do you pick between these two great options?

Both focus on providing the best-in-class developer experience with minimal runtime.

So, how do they compare? If you had to pick one which one would you pick given your context?

Let’s get the similarities out of the way first.

Similarities

Both libraries support:

Type-safe API: Both have a typed library API to assist the developers.
Token-based theming: Tokens are the building block of a system, both libraries provide a first-class support for typed tokens.
Variants: Both libraries provide an API to add variants to a component.
CSS custom properties: Both libraries convert theme tokens to CSS custom properties. They also provide API for user-defined CSS custom properties.

In a gist, they provide a very comparable developer experience. So what’s different?

Differences

Library Runtime

This is the amount of JavaScript the libraries ship by default.

🧵 Stitches claims a “near-zero runtime.” Bundlephobia reports 6 kB gzipped which is quite slim.

🧁 Vanilla-Extract runs at build-time. So no runtime is added. If you use the @vanilla-extract/dynamic package, it’d add 718 bytes to your bundle.

Userland Runtime

This is the amount of runtime added due to the user-land code.

🧵 Stitches: User-land runtime code scales linearly as CSS is bundled in JavaScript. Theoretically, this will be as big as the design system itself.

🧁 Vanilla-Extract: None if you use the styling API only. If you use the Sprinkles API for generating Atoms, it generates a script to look-up the classnames which doesn’t impact rendering performance. This script grows along with the amount of atoms generated which usually stop growing over time.

Rendering Performance

The way in which CSS is delivered to the users can have an impact on several metrics like FCP and TTI of the first page and subsequent pages.

🧵 Stitches

Because the styles are rendered inline, FCP happens much earlier for the first page load.

New styles are injected dynamically which invalidates a lot of the work that has already been done by the browser, no matter how little CSS was injected.

TTI happens later because a significant time of main thread is spent on “Style & Layout”. The “uncanny valley” is quite wide.

🧁 Vanilla-Extract

Because CSS files are generated statically and are <link />ed and requested separately, FCP happens later in comparison to Stitches for the first page load.

Subsequent renders are fast as the common CSS (atoms) are cached on the first request. Only new styles are fetched, if any.

TTI isn’t delayed because the main thread isn’t busy with “Style & Layout.” The “uncanny valley” is narrow.

Token typing and mapping

This is whether the tokens themselves are strictly typed and any deviations from token usage are reported.

🧵 Stitches sensibly and conveniently maps the tokens to the CSS properties. But they are not typed to be limited to the tokens only. Though, there is a provision to have a stricter experience.

🧁 Vanilla-Extract doesn’t give you any mappings if you use the styling API. Though, if you use Sprinkles (for atoms), which you should, you can do your own mapping. The CSS properties are strictly limited to the tokens.

Component Debug-ability (React Developer Tools)

The library should not come in the way of debug-ability using Devtools.

🧵 Stitches: Using styled API causes component names to be mangled, also you cannot view component source code if you use styled. However, using the css function doesn’t have any of these problems.

🧁 Vanilla-Extract: No negative impact on React Developer Tools.

Documentation

How thorough and thoughtful the library documentation is.

🧵 Stitches comes with an excellent documentation. Even the, otherwise usually neglected, TypeScript experience is given full attention.

🧁 Vanilla-Extract has terse and API like docs. They’re difficult to get started with and require a lot of jumping around.

Custom Tokens and Names

Does the libary allow custom tokens and token names (e.g., spacings instead of space) as per the vocabulary that suits their team? E.g., timingFunctions.

🧵 Stitches only supports tokens from system-ui specs. Also not possible to customise token names either.

🧁 Vanilla-Extract supports custom tokens with custom names.

Atomic style generation

Does the library provide a way to generate a set of atomic classes to reuse and reduce the amount of CSS to be shipped?

🧵 Stitches doesn’t support atomic generation at this time.

🧁 Vanilla-Extract supports atomic generation using Sprinkles. You can even use the atoms inside variants.

Takeaway

For us, performance and user experience are important as a lot of our users come from a low powered mobile device. The choice was obvious, we decided to go with Vanilla-Extract:

Zero runtime
Ability to generate atoms that helps in limiting the amount of CSS we ship to our users
Better rendering performance overall
Ability to use expensive libraries like Polished in .css.ts files without worrying about the impact on bundle-size as they’re evaluated at build time.

A Note On React 18

If you care about performance and the nitty-gritty details, you should definitely read the library upgrade guides by the React Working Group:

Here’s an interesting excerpt from the upgrade guide for <style>:

While this technique for generating CSS is popular today, we’ve found that it has a number of problems that we’d like to avoid. Therefore we don’t have plans for adding any solutions upstream to handle this in React. For the time being, we expect this to have to be handled by third-party libraries such as in this guide.

Our preferred solution is to use <link rel="stylesheet"> for statically extracted styles and plain inline styles for dynamic values. E.g. <div style={{...}}>. You could however build a CSS-in-JS library that extracts static rules into external files using a compiler. That’s what we use at Facebook.

It’s tempting to use dynamically generated style sheets since it contains only the rules that are active on the page right now. However, this comes at a cost. Usually at the expense of runtime cost. It also comes at a cost of inserting new rules frequently which invalidates a lot of the work that has already been done.

Shared stylesheets are efficient to parse and are very cacheable. By extracting them into shared styles you are also effectively batching a lot of that work up front. This lets you avoid doing that work later on as the user starts interacting with the page.

References

Add Command Palette (CMD+P) To Any App!

Nayaab Khan — Thu, 18 Nov 2021 09:36:11 +0000

tldr;

Use Raycast's “Search Menu Items” from any app and get a command palette.

If you love Alfred or can‘t switch, you can use a workflow like BenziAhamed/Menu-Bar-Search to do the same.

Command palettes from Sublime Text and Visual Studio Code are awesome. They give quick access to commands with fuzzy search. It sucks when apps don’t have it.

Recently, I switched to Raycast which is a great alternative to the fantastic app that Alfred is.

It has a fantastic command called “Search Menu Items”. It gives me a searchable list of commands with their shortcuts keys. For example, this is what it gives me on iTerm:

Hotkey

I've set up a hotkey to quick access the commands as well. This saves me a few keystrokes.

Bonus, one less app

It has also replaced Cheatsheet for me.