DEV Community: 🈚️うひょ🤪

TypeScript 4.5 Shortens Path to Safer Standard Library

🈚️うひょ🤪 — Sat, 02 Oct 2021 02:08:39 +0000

Amongst the new features of TypeScript 4.5, support for loading external packages in place of built-in type definitions (standard library) is particularly of note. The original intent seems to be externalizing lib.dom.d.ts as @types/web so that users can have separate upgrading schedule for TypeScript's core type definitions and one for DOM. The type definitions for DOM are fragile and often breaks backwards compatibility, probably because they are auto-generated.

Thanks to this nicely generalized solution for externalized standard library, better-typescript-lib, a library developed by the author, also receives huge benefit. Particularly, installation is far easier starting from better-typescript-lib v2 that supports TS 4.5 and later.

What is better-typescript-lib?

better-typescript-lib is a package that provides alternative type definitions for standard library.

TypeScript's built-in type definitions are sometimes problematic in view of safety. For example, the return type of JSON.parse is any 😱 and it is too easy to guide users to the unsafe hell.

As TypeScript needs to keep backwards compatibility, directly fixing built-in type definitions is impossible. Previous solutions for this kind of problems have been compiler options, but something like --strictStandardLibrary does not look like a right way to go.

better-typescript-lib solves the problem by replacing the entire built-in type definitions with safer ones. It ships with alternative complete set of type definitions for supported ECMAScript and DOM features.

Previous Installation Steps of better-typescript-lib

Before TS 4.5, installation of better-typescript-lib was a complicated task. Three steps were required:

1. Install better-typescript-lib.

npm i -D better-typescript-lib

2. Add "noLib": true to tsconfig.json so that TypeScript's built-in type definitions are not automatically loaded.

-  "lib": ["es5", "dom"]
+  "noLib": true

3. Manually load needed libs from inside better-typescript-lib.

/// <reference path="./node_modules/better-typescript-lib/lib.es5.d.ts" />
/// <reference path="./node_modules/better-typescript-lib/lib.dom.d.ts" />

New Installation Step

Thanks to TS 4.5's new feature, now you can use the safer type definitions by literally one step:

1. Install better-typescript-lib.

npm i -D better-typescript-lib

Done! Wow, everything is so automatic. Now TypeScript loads safer type definitions instead of built-in ones.

How the New Installation Step Works

Starting from TS 4.5, TypeScript detects packages of name with form @typescript/lib-[lib] and loads that package in place of corresponding built-in type definition. For example, @typescript/lib-es2015 replaces built-in lib.es2015.d.ts. What a simple but widely applicable solution!

The @typescript scope is owned by TypeScript team, of course, but package managers support installing packages with different names. better-typescript-lib utilizes this feature and have below dependency definitions in package.json:

    "@typescript/lib-dom": "npm:@better-typescript-lib/dom@2.0.0-alpha.1",
    "@typescript/lib-es2015": "npm:@better-typescript-lib/es2015@2.0.0-alpha.1",
    "@typescript/lib-es2016": "npm:@better-typescript-lib/es2016@2.0.0-alpha.1",
    "@typescript/lib-es2017": "npm:@better-typescript-lib/es2017@2.0.0-alpha.1",
    "@typescript/lib-es2018": "npm:@better-typescript-lib/es2018@2.0.0-alpha.1",
    "@typescript/lib-es2019": "npm:@better-typescript-lib/es2019@2.0.0-alpha.1",
    "@typescript/lib-es2020": "npm:@better-typescript-lib/es2020@2.0.0-alpha.1",
    "@typescript/lib-es2021": "npm:@better-typescript-lib/es2021@2.0.0-alpha.1",
    "@typescript/lib-es5": "npm:@better-typescript-lib/es5@2.0.0-alpha.1",
    "@typescript/lib-esnext": "npm:@better-typescript-lib/esnext@2.0.0-alpha.1",
    "@typescript/lib-header": "npm:@better-typescript-lib/header@2.0.0-alpha.1",
    "@typescript/lib-scripthost": "npm:@better-typescript-lib/scripthost@2.0.0-alpha.1",
    "@typescript/lib-webworker": "npm:@better-typescript-lib/webworker@2.0.0-alpha.1"

This way, safer type definitions published as @better-typescript-lib/[lib] are installed with names @typescript/lib-[lib] so that they are used instead of built-in type definitions.

Note: this depends on the behavior of package managers that flattens contents in node_modules. Package managers with different strategy for dependency management may not work well. Support for such environments may be added in the future if there are several requests.

Conclusion

TypeScript 4.5's new feature for replacing built-in type definitions shall have wide application. better-typescript-lib is one of the earliest users of the new feature and is now able to provide safety with far easier installation step.

You can try now by installing TypeScript 4.5 Beta and better-typescript-lib@2.0.0-beta.

Is HTML A Programming Language? — A Definitive Answer

🈚️うひょ🤪 — Tue, 27 Apr 2021 01:44:25 +0000

Hello. I created the HTML programming language (THPL), a programming language whose source code is an HTML document. Therefore, HTML is a programming language!

Visit THPL Tutorial to learn more about THPL.

Here are a couple of examples.

Hello World in HTML:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>My First HTML Program</title>
    <script src="https://unpkg.com/the-html-programming-language@0.1.0/browser.min.js"></script>
  </head>
  <body>
    <p><output>Hello, world!</output></p>
  </body>
</html>

Even FizzBuzz in HTML is possible:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>FizzBuzz</title>
    <script src="https://unpkg.com/the-html-programming-language@0.1.0/browser.min.js"></script>
  </head>
  <body>
    <section title="fizzbuzz">
      <dl>
        <dt>rem3</dt>
        <dd>
          <abbr>
            <math><rem /></math><br />
            <slot></slot><br />3
          </abbr>
        </dd>
        <dt>rem5</dt>
        <dd>
          <abbr>
            <math><rem /></math><br />
            <slot></slot><br />5
          </abbr>
        </dd>
        <dt>text</dt>
        <dd>
          <abbr>
            <math><eq /></math><br /><var>rem3</var><br /><meter>0</meter></abbr
          ><abbr>
            <math><eq /></math><br /><var>rem5</var><br /><meter>0</meter></abbr
          ><ruby>
            <span>00</span>
            <rt><slot></slot></rt>
            <span>10</span>
            <rt>Fizz</rt>
            <span>01</span>
            <rt>Buzz</rt>
            <span>11</span>
            <rt>FizzBuzz</rt>
          </ruby>
        </dd>
      </dl>
      <p>
        <output><var>text</var><wbr /></output>
      </p>
      <footer>
        <slot></slot>
        <ruby>
          <meter>100</meter>
          <rt><span></span></rt>
          <rt
            ><abbr title="fizzbuzz">
              <abbr
                ><math><plus /></math><br /><slot></slot><br />1</abbr
              >
            </abbr></rt
          >
        </ruby>
      </footer>
    </section>
    <p>
      <abbr title="fizzbuzz"><meter>1</meter></abbr>
    </p>
  </body>
</html>

Now it's obvious that you can write programs in HTML!

Q&As

I have gathered feedback from a Japanese community. Here are feedbacks and answers to them in a form of Q&As.

Q: But a script tag exists in your source code, so the HTML document itself is not a program.

A: the script tag exists only for automatically executing the HTML program when opened with a browser, so this is not essential for HTML to be a programming language.

Q: you need a JavaScript interpreter to run an HTML program. This means that HTML is not a standalone programming language.

A: Yeah. Then Ruby is not a programming language because it is run by a C interpreter, right?

Q: But HTML identifies itself as a markup language, not programming language.

A: You should already know that name is no more than historical stuff. Please complain that JavaScript is calling itself Java first.

Q: What you created is only that THPL interpreter thing, so HTML is not affected at all.

A: The THPL interpreter is just an auxiliary tool that helps understanding THPL. Defining syntax and semantics is essential for something to be a programming language. Syntax already exists for HTML, and I defined semantics directly onto HTML, so HTML is now a programming language.

Q: HTML is a language for defining document data in the form of tree structure, not a program. HTML is more like JSON, YAML or S-expression, which are still not programming languages.

A: This point is worth discussing, but please remember that programs are finally interpreted as abstract syntax trees. In this sense, code for normal programming languages can also be seen as one that defines data in the form of tree structure. With this in mind, difference between HTML and other programming languages are quite vague.

Q: But program ASTs are different from other data formats in that they don't have other uses. HTML is originally for document markups, and JSON and YAML are for general purpose data exchange.

A: Okay, please wait for my next project which uses JavaScript programs as general-purpose data format. Then you would say JavaScript is not a programming language.

Now what do you think? Is HTML a programming language? Discuss!

Use Resource Bundles Now -- A Static Web Server

🈚️うひょ🤪 — Sun, 14 Mar 2021 15:32:28 +0000

Resource Bundles is a new proposal regarding the problem of nested resource loading on the web. HTTP/2 Server Push previously tried to solve the problem without success; Resource Bundles is the next iteration of the attempt to push the web to the era of native ES Modules.

In the Resource Bundles era, bundlers like webpack would emit a Resource Bundle instead of a big JavaScript file. Browsers would natively understand Resource Bundles.

A resource bundle is simply a set of multiple resources. A resource is a pair of raw payload and all HTTP headers for that payload, identified by URLs. In addition to a resource bundle, bundlers would also emit a “manifest”, a dependency graph between resources in the resource bundle. Thanks to this, browsers can download all the resources needed by one request.

By browsers natively understanding Resource Bundles, efficient caching of resources is enabled too. Browsers can choose to request a subset of whole resource bundle, only requesting ones that aren't cached yet. The server that serves resource bundles would also support subsetting.

Although Resource Bundles are in its very early stage and few of its details are decided, you can try using Resource Bundles now. The author created a tools for parsing and serializing Resource Bundles based on the current draft of the proposal, as well as a CLI for inspecting and creating Resource Bundles and a static server for serving resources from a Resource Bundle.

The last one, static server, is actually going aside from the main purpose of Resource Bundles, and is described as “other uses” in the proposal. As resource bundles already include HTTP headers for each resource, configuring a static web server would be made extremely easy with Resource Bundles. This means that, in a future, bundler config would include HTTP headers for generated resources.

Finally, you can try that static server now! Try @resourcebundles/static-server.

Disclaimer: this work is totally unofficial.

What If Every Color Is Given Its Own Name? Here It Is!

🈚️うひょ🤪 — Fri, 26 Feb 2021 08:39:39 +0000

What is the most comprehensive way of expressing colors in CSS? For a majority of developers, it should be color names.

a {
  color: blue; /* <- color name for #0000ff */
  text-decoration: none;
}

However, color names have one critical downside; not all colors are given names. While the sRGB color space can express 16,777,216 colors, only less than 0.002% of them are given names by the CSS standard.

That's why the author has created Everycolor. With this package, all colors are given systematic names. It comes with a PostCSS plugin that converts the Everycolor names to the #123456 notation, so you can use the Everycolor names in your CSS now!

Let's see what the Everycolor names look like.

p {
  background-color: redhalfwhite; /* #ff8080 */
}

Everycolor gives the name redhalfwhite to #ff8080, as this color is halfway towards white (#ffffff) from red (#ff0000). Wow, how easy it is!

Then, can you guess what name #ff4040 is? Yes, it's redquarterwhite. Now you know how to express colors you want to use!

With Everycolor, you can express every single color with names rather than hard-to-recognize numbers.

We also provide a website where you can convert color codes to Everycolor names. This is very useful for learning Everycolor quickly.

https://everycolor.vercel.app/

At the end, let's see a little more complicated examples.

body {
  /* #14211a */
  background-color: quarterimperceptiblegreensomewhatlittleslighttealsomewhatbitgray;
  /* #c7eaf9 */
  color: navyhalfquartersomewhatlittleimperceptiblebluetealhalfquarterlittleslightaquahalfquarterslightimperceptibleinfinitesimalwhite;
}
a {
  /* #e4d923 */
  color: maroonhalfquarterbitredolivehalfsomewhatlittleimperceptibleyellowsomewhatimperceptibleinfinitesimalwhite;
}

Wow, so understandable! 😍

What If You Don't Have to Remember Tailwind CSS Classes? Here It Is!

🈚️うひょ🤪 — Sat, 30 Jan 2021 16:27:09 +0000

This article is an English translation of an article: Tailwind CSSからクラス名覚えにくさを消したらどうなる？　こうなった

Tailwind CSS is a CSS framework with which you utilize predefined CSS classes to compose a design.

I created a new library, Lightwind CSS, which inherits all the goodness of Tailwind CSS but does not require you to memorize class names specific to Tailwind CSS.

https://github.com/uhyo/lightwindcss

Pros and Cons of Tailwind CSS

An example from the official site of Tailwind CSS is quoted below:

<figure class="md:flex bg-gray-100 rounded-xl p-8 md:p-0">
  ...
</figure>

These classes correspond to plain CSS as follows.

md:flex → @media (min-width: 768px) { display: flex; }
bg-gray-100 → background-color: #F3F4F6;
rounded-xl → border-radius: 0.75rem;
p-8 → padding: 2rem;
md:p-0 → @media (min-width: 768px) { padding: 0; }

As you can see, display: flex is shortened into flex. Also, pedding is abbreviated as p.

According to the official site, this way of composing styles is called Utility-First. Utility-First CSS frameworks offer these merits:

You don't have to name classes by yourself. A traditional approach would invent and apply a class name to each component that needs to be styled. With Tailwind CSS, you just use predefined class names whenever you want to apply styles to the DOM.
CSS doesn't grow. With a traditional approach, new CSS is added every time you have a new component to be styled. With Tailwind CSS, you always use the same set of predefined styles so your CSS doesn't grow.
Styles are kept local. A traditional approach would allow using a single class from multiple elements, or writing selectors that indirectly affects descendant elements (like .cls div). Such situations make it hard to predict how a style change affects to your whole app. With Tailwind CSS, your styles are tightly tied to specific DOM elements. Also, Tailwind classes don't have the indirect effects. These characteristics keep the styles local so that making changes to styles are safe.

On the other hand, the author doesn't feel good about how Tailwind CSS isn't CSS while it is based on CSS. As seen in the example above, Tailwind CSS consists of utility classes made by abbreviating and abstracting pure CSS concepts, which means that you have to memorize Tailwind-specific vocabulary. However, this does not mean that you don't have to learn pure CSS in order to use Tailwind CSS. If you don't know how CSS's padding works, you can't understand Tailwind's p-8! Moreover, Tailwind CSS doesn't offer full CSS features through its predefined utility classes. To use modern CSS features, Tailwind CSS isn't sufficient.

Lightwind CSS Lets You Use Plain CSS

Lightwind CSS, the CSS framework created by the author, is designed so that it offers all the merits from Tailwind CSS and also allows use of the plain CSS. For example, you write styles with Lightwind CSS as follows:

<div
  className={css`
    display: flex;
    flex-flow: row nowrap;
    justify-content: center;
  `}
>
  <main
    className={css`
      display: flex;
      flex-flow: column nowrap;
      justify-content: center;
      align-items: center;
    `}
  >
    Hello, world!
  </main>
</div>

Similarly to Tailwind, you attach CSS directly to HTML elements. The css function receives a CSS string and returns corresponding class names. The syntax is actually the same as emotion's css API. This reduces the need of inventing class names similarly to how Tailwind does so. It also helps keep the styles local.

The key feature of Lightwind CSS is the ability to globally optimize CSS for production builds. Lightwind CSS generates one CSS file that contains all the styles in your app. A CSS file that corresponds to the above code would be:

.a {
  display: flex;
  justify-content: center;
}
.b {
  flex-flow: row nowrap;
}
.c {
  flex-flow: column nowrap;
  align-items: center;
}

The markup would be transformed into the following by Lightwind CSS's Babel plugin:

<div className="a b">
  <main className="a c">Hello, world!</main>
</div>

Of note is that Lightwind CSS has optimizes globally; styles from two distinct css are detected and named a, and a is shared by two HTML elements. Usage of css from different files would also be properly optimized. This feature lets us prevent CSS from growing. You may write the same styles in different places, and they are all optimized into one by Lightwind CSS.

In summary, Lightwind CSS takes an opposite approach to Tailwind CSS. While Tailwind CSS first defines the set of class names to be used, Lightwind CSS lets you write arbitrary CSS and then calculate the optimized set of class names from what you wrote. This way, Lightwind CSS still provides you the three merits while not forcing you to remember Tailwind-specific classes.

Comparison to Plain Inline Styles

Lightwind CSS' way of writing styles is close to writing plain inline styles, that is:

<div
  style={{
    display: "flex",
    flexFlow: "row nowrap",
    justifyContent: "center"
  }}
>
  ...
</div>

Actually, the documents of Tailwind CSS discusses it in the section named Why not just use inline styles?, as follows:

Tailwind CSS offers abstracted styles like p-8 or rounded-xl instead of using concrete numbers like padding: 0.75rem; or border-radius: 8px;. This helps you easily build consistent designs.
Media queries cannot be used with inline styles. Tailwind CSS offers media queries-aware classes like md:flex.
Pseudo classes (like :hover or :focus) can neither be used with inline styles. Tailwind CSS also offers classes like hover:bg-purple-700 for this use case.

Lightwind CSS solves 2 and 3 by allowing nested rules:

  <main
    className={css`
      display: flex;
      flex-flow: column nowrap;
      justify-content: center;
      align-items: center;

      &:hover {
        opacity: 0.5;
      }
    `}
  >
    Hello, world!
  </main>

On the other hand, Lightwind CSS excludes the first point -- consistent designs -- from its responsibility, on purpose. This is because we want to provide the experience of writing plain CSS. Building a consistent design system is now your duty.

If you need theming, CSS Variable should be useful. Lightwind CSS might provide a helper to utilize CSS Variables easily in the future.

Notes on Nested Rules

As described above, Lightwind CSS supports nested CSS rules. Please note that it allows you to break the CSS locality, which is one of the goodness of Lightwind CSS that is inherited from Tailwind. For example:

  <main
    className={css`
      display: flex;
      flex-flow: column nowrap;
      justify-content: center;
      align-items: center;

      /* This is not local, affects
       * all the p elements under this!
       */
      p {
        color: red;
      }
    `}
  >
    Hello, world!
  </main>

It may be seen as Lightwind CSS offering more freedom on breaking the locality. Lightwind CSS a light utility so it doesn't restrict a lot of things.

If you want that restriction (I recommend to do so!), you can utilize linters like stylelint to ban the above pattern.

Conclusion

This article introduced Lightwind CSS, a CSS framework that offers the same goodness as Tailwind CSS and lets you write plain CSS instead of Tailwind-specific class names. The key feature of Lightwind CSS is the global optimization to generate one optimized class definitions.

A Concurrent Mode-Safe Version of useRef

🈚️うひょ🤪 — Wed, 22 Apr 2020 15:20:49 +0000

When you use React Hooks, components maintain internal states for hooks. For example, caches made by useMemo and objects returned by useRef are also residents of the internal state, as well as states controlled by the useState hook. During a rendering of a component, the internal states of that component are updated. The useMemo hook should be one of the easiest example of updates during a rendering. Caches of useMemo are updated immediately during a useMemo call, if necessary.

In React's Concurrent Mode, components have possibility of suspension. That is, a rendering of a component does not necessarily result in a DOM update (or other view updates if you are not using react-dom). Every time a component suspends, modifications made during the rendering that suspended are rolled back to the state before rendering. For example, a cache newly made by useMemo is discarded if that rendering suspends.

From this characteristic of Concurrent Mode, it follows that we ought to take extra care on usage of the useRef hook. The role of useRef is very simple; it always returns the same object (ref object; more accurately, an object that is made on the first rendering of that component). This object can be utilized for communication between rendering or any other side effects that originate from a component. The point is that, modifications made to the ref object is not rolled back even if a rendering suspends.

In an article How To Properly Use the React useRef Hook in Concurrent Mode by Daishi Kato, a usage of useRef where a ref object is modified during a rendering is regarded as a Bad Code:

const BadCounter = () => {
  const count = useRef(0);
  count.current += 1;
  return <div>count:{count.current}</div>;
};

The counter's value is increased every time the BadCounter is rendered. Of note is that, in Concurrent Mode, this may not match with how many times the contents of BadCounter is reflected to the DOM.

In a worse situation the current value of a ref object may interact with other hooks during a rendering. If such a rendering suspends, the component logic may fall into an inconsistent state where the ref object's value reflects the suspended rendering's state while other hooks' state are reset.

Therefore, to involve useRef in a rendering logic, we need a concurrent-mode safe version of useRef, whose value is automatically rolled back if a rendering suspends. In other words, it is more like a variant of useState which does not trigger re-rendering.

Here it is:

type Raw<T> = {
  isRendering: boolean;
  comittedValue: T;
  currentValue: T;
  ref: { current: T };
};
export const useConcurrentModeSafeRef = <T>(initialValue: T) => {
  const rawRef = useRef<Raw<T>>();
  const raw: Raw<T> = rawRef.current ?? (
    rawRef.current ={
      isRendering: true,
      comittedValue: initialValue,
      currentValue: initialValue,
      ref: {
        get current() {
          if (raw.isRendering) {
            return raw.currentValue;
          } else {
            return raw.committedValue;
          }
        },
        set current(v) {
          if (!raw.isRendering) {
           raw.comittedValue = v;
          }
          raw.currentValue = v;
        }
      }
    }
  );
  raw.isRendering = true;
  Promise.resolve().then(()=> raw.isRendering = false)
  raw.currentValue = raw.comittedValue;
  useEffect(() => {
    raw.comittedValue = raw.currentValue;
  });

  return raw.ref;
};

This useConcurrentModeSafeRef returns an object with the same signature as useRef. The intended usage is to use ref.current as a storage that is persistent between renderings. Every time useConcurrentModeSafeRef is called, the current is reset to raw.committedValue. This value is updated only when a rendering succeeds; this behavior is realized with the help of useEffect hook. If a rendering suspends, raw.committedValue stays in the old state so that the changes made during that rendering are to be discarded.

The ref object returned by useConcurrentModeSafeRef behaves the same as useRef outside of renderings. Users can directly interact with raw.committedValue in such situations.

Conclusion

This article explained a Concurrent Mode-safe variant of useRef. The key of the Concurrent Mode safety is that the value of ref objects are rolled back if a rendering suspends for aligned behavior with other hooks.

Implementing CSS Animations with New Experimental useTransition Hook

🈚️うひょ🤪 — Thu, 19 Dec 2019 16:08:10 +0000

This is a summarized version of a Japanese article by the same author:

ワイ「アニメーションするにはこのuseTransitionってのを使えばええんか？」

Introduction

In October 2019, the React team introduced an experimental preview of React's new Concurrent Mode. Along with other innovative (but a little bit opinionated) features in it, the new useTransition hook has power to completely change how we develop React applications.

Here is a brief introduction of the useTransition hook (see the official docs for more details): the useTransition hook allows us to maintain two states at the same time, primarily designed for page transitions.

Consider a situation where you update some state in order to transition to a new page. In Concurrent Mode, the rendering of the new state may “suspend” (typically due to data fetching). Without useTransition, we have to render fallback contents (often a loading icon) during the suspension. What is important here is that the suspension can only be detected after state updates, since suspension occurs as a result of rendering based on the new state.

By utilizing useTransition, we can tell React to keep reflecting the old state to the DOM while suspension. As soon as the rendering of the new state completes, React switches the DOM to the new result. Furthermore, useTransition provides a flag of whether it is pending (waiting for the rendering of the new state) to the world of the old state. Here React is maintaining two worlds at the same time: one for the old pending state and one for the new state.

You can find nice examples of useTransition at the official documents.

Using useTransition for Animations

As is obvious from its name, the useTransition hook is fairly useful for implementing CSS animations based on the transition CSS property. This article shows how to use useTransiton for this purpose and gives a brief explanation.

The well-known problem regarding CSS animations in React is how to handle mounting and unmounting of components. If we want to utilize CSS transitions, we cannot mount a new DOM element and start its animation in one action; we have to mount an element in the before-animation state first, and then immediately alter its style to after-animation one to trigger the animation.

Previously, people used libraries like react-transition-group or react-spring to handle this situation. These libraries automates the above two-step state changes.

In this article, an alternative approach which utilizes useTransition is introduced. Below is an example though it is still a rough PoC:

In the example, you can click the toggle button to show and hide a blue box. The box animates its opacity on every state change and is actually mounted/unmounted every time. As usual, unmounting is delayed until the animation completes. In what follows, the trick used in this example is explained.

Preparation

We start from looking at some utilities defined in the example. The first is the Timer class:

// src/Timer.js
export class Timer {
  constructor(duration) {
    const timer = new Promise(resolve => setTimeout(resolve, duration));
    this.done = false;
    this.promise = timer.then(() => {
      this.done = true;
    });
  }
  throwIfNotDone() {
    if (!this.done) {
      throw this.promise;
    }
  }
}

new Timer(duration) creates a Promise which is fulfilled after duration milliseconds. The throwIfNotDone method, when called, throws that Promise if it is not fulfilled yet. We don't step into details, but throwing Promises is a significant characteristic of React's Concurrent Mode. In short, throwing a Promise means that the current rendering should be suspended until that Promise is fulfilled.

So we need a component that actually throws this Promise. It's called Waiter in the example. It can't be simpler; it receives a Timer from props and calls its throwIfNotDone method. It does not produce actual contents.

function Waiter({ timer }) {
  if (timer) timer.throwIfNotDone();
  return null;
}

React has a rule that, if a component may throw a Promise it must be enclosed in React's Suspense component. That's why Waiter is used as follows in the example.

      <Suspense fallback={null}>
        <Waiter timer={timer} />
      </Suspense>

Thanks to Timer and Waiter, we now have ability to cause suspensions for a certain period of time while rendering. In the example we prepare the timer state which is passed to Waiter. If you create a Timer and set the timer state to it, the next rendering would be suspended for the specified time.

Two-Step Rendering Using useTransition

Now, let's see how the animation is implemented in the example. First of all, the blue box is rendered by the following code:

      {show ? <Box show={show && !isPending} /> : null}

where show is a boolean state and isPending is a flag provided by useTransition indicating whether some rendering is suspended now. Normally isPending is false and it becomes true only while suspension.

The Box component renders a blue box; if show={false} its opacity is 0 and if show={true} its opacity is 1. It is worth noting that the Box component is actually unmounted while show is false.

Finally we see what happens when we click the toggle button:

  const toggle = () => {
    if (show) {
      startTransition(() => {
        setShow(false);
        setTimer(new Timer(500));
      });
    } else {
      setShow(true);
      startTransition(() => {
        setTimer(new Timer(10));
      });
    }
  };

If show is false, we call setShow(true), which will update state to true. The point is the startTransition call following it; it takes a callback function which is immediately called. The useTransition hook works for the states updated inside the callback; if these state updates caused a suspension, then React renders the old state while setting true to isPending during the suspension.

Here is an illustration of what happens here. In the initial state (the left box in the above image) both show and isPending are false. When toggle() is called, show is set to true as usual. Also, timer is set to new Timer(10) inside startTransition. As explained above, this will trigger a suspension which leads to the middle state (where show is true and isPending is true) being rendered to the DOM. After 10ms the suspension finishes and the last state (show is true and isPending is false) is rendered.

Here we achieved the two-step rendering with one set of state updates by cleverly utilizing suspension and isPending provided by useTransition.

Next we see what happens when trigger() is called while show is true.

      startTransition(() => {
        setShow(false);
        setTimer(new Timer(500));
      });

In the initial state show is true and isPending is false. Basically we are doing the same: set show to false and set a Timer. This time the duration of timer is 500 ms; this is the duration of the animation of opacity.

The point is that, this time the update for show is also put inside startTransition. Thanks to this, the value of show keeps the old one while the suspension caused by timer. This is why in the middle state show is still true while isPending is updated to true. After 500 ms it transitions to the last state where show is updated to false and isPending is set back to false.

Conclusion

This article explained how to utilize useTransition from React's Concurrent Mode to implement CSS animations. Thanks to the isPending flag provided by it, we can pack a two-step rendering into one set of state updates.