Forem: Matsura Yuma

Implement FormControl to ensure form accessibility in React

Matsura Yuma — Mon, 26 Dec 2022 05:52:43 +0000

This post was originally published on my blog

Forms are an important part of website and app development. They are critical elements in terms of UX and accessibility because they are the parts that users actually interact with. Poorly designed forms are not only annoying for everyone, but if they are not properly marked up, they may also hinder the use of assistive technologies.

However, the implementation of a user-friendly form is complex, and if it includes validation by JavaScript, it can be burdensome for developers. In this article, I would like to introduce the implementation of a React component called FormControl that helps us appropriately markup the form fields.

The implementation in this article is largely based on MUI - FormControl.

Usage

If you want to use all options:

return (
  <FormControl labelText="Name" helperText="Tell us your name" error="Something is wrong">
    <TextInput required placeholder="John Doe" />
  </FormControl>
)

The following is the output HTML. The id is automatically published within the component and is properly linked to the label element. In addition, aria attributes such as aria-describedby are also assigned.

<div class="FormControl">
  <label for=":r1:" id=":r1:--label">Name</label>
  <div id=":r1:--helper-text">Tell us your name</div>
  <input
    id=":r1:"
    aria-describedby=":r1:--helper-text :r1:--error-text"
    aria-invalid="true"
    placeholder="John Doe"
  />
  <div id=":r1:--error-text">Something is wrong</div>
</div>

Here is a style example. We will not touch on CSS much in this article, but you can pass the error prop to add a class name, or use the &:has([required]) selector to display an asterisk for required items as a pseudo-element.

Firefox doesn't support :has() yet.

Implementation method

Approach

As a premise, it is required that the user input component can be flexibly passed to the TextInput part mentioned above. Not all form fields are input, so it should be loosely coupled.

This time, we will use the Context of React as an interface. FormControl will add appropriate markup to the user input element received as children, wrap it with Context.Provider, and pass data such as the automatically generated id. This allows the child element to consume the data by calling useContext.

Define Context

Let's define FormControlContextValue as follows:

import React from "react"

export type FormControlContextValue = {
  id: string | undefined
  labelId: string | undefined
  helperTextId: string | undefined
  errorTextId: string | undefined
  isError: boolean | string
}

export const FormControlContext = React.createContext<FormControlContextValue>({
  id: undefined,
  labelId: undefined,
  helperTextId: undefined,
  errorTextId: undefined,
  isError: false,
})

export function useFormControlContext() {
  return React.useContext(FormControlContext)
}

Implement FormControl

We generate a single id to pass to the input element using React.useId and add a suffix to other IDs. Other than being surrounded by FormControlContext.Provider, nothing is special.

import React from "react"

import { FormControlContext } from "./FormControlContext"

export type FormControlProps = {
  labelText: string
  helperText?: string
  error?: boolean | string
  children: React.ReactNode
}

export function FormControl({
  labelText,
  helperText: helperText,
  error = false,
  children,
}: FormControlProps) {
  const id = React.useId()
  const labelId = `${id}--label`
  const helperTextId = `${id}--helper-text`
  const errorTextId = `${id}--error-text`
  const ctxValue = {
    id,
    labelId,
    helperTextId,
    errorTextId,
    isError: !!error,
  }

  return (
    <FormControlContext.Provider value={ctxValue}>
      <div>
        <label htmlFor={id} id={labelId}>
          {labelText}
        </label>
        {helperText && <span id={helperText}>{helperText}</span>}
        {children}
        {typeof error === "string" && <span id={errorTextId}>{error}</span>}
      </div>
    </FormControlContext.Provider>
  )
}

Implement Input

We will first implement the generic Input component, rather than the TextInput component in the first example. By calling useFormControlContext(), you can use the values provided by the enclosing FormControl.

aria-describedby can specify multiple IDs separated by spaces, so we pass both supplementary explanatory text and error messages.
isError passed to aria-invalid becomes true when error is specified with a truthy value (true or a non-empty string). You can style erroneous state with CSS selectors like input[aria-invalid="true"].

import React from "react"

import { useFormControlContext } from "../FormControl/useFormControlContext"

type Props = JSX.IntrinsicElements["input"]

export const Input = React.forwardRef<HTMLInputElement, Props>((props, forwardedRef) => {
  const { id, helperTextId, errorTextId, isError } = useFormControlContext()
  return (
    <input
      id={id}
      aria-describedby={[helperTextId || "", errorTextId || ""].join(" ")}
      aria-invalid={isError}
      ref={forwardedRef}
      {...props}
    />
  )
})

Input.displayName = "Input"

In this implementation, extra spaces are added to aria-describedby, so it may be better to do some filtering.

Extend Input

You can use the Input component as is, or create extended components such as TextInput or Checkbox by specifying the type. It should be easy to integrate with external libraries by passing them id.

Other considerations

What if nested?

Since useContext refers to the value of the nearest Provider, there is no problem even if FormControl is nested. Therefore, it can be used as follows.

export function RadioGroup({ children }: RadioGroupProps) {
  const { labelId } = useFormControlContext()
  return (
    <div role="radiogroup" aria-labeledby={labelId}>
      {children}
    </div>
  )
}

return (
  <FormControl labelText="PPAP">
    <RadioGroup>
      <FormControl labelText="Pen">
        <Input type="radio" name="ppap" value="pen" />
      </FormControl>
      <FormControl labelText="Pineapple">
        <Input type="radio" name="ppap" value="pineapple" />
      </FormControl>
      <FormControl labelText="Apple">
        <Input type="radio" name="ppap" value="apple" />
      </FormControl>
    </RadioGroup>
  </FormControl>
)

Is it bad idea to enclose `input` by `label`?

Although it is certainly convenient to eliminate the management of IDs by putting input inside label, I think it is better to link with htmlFor if you want to support aria-describedby and behavior when nested. If those are not needed, it is also fine to simply surround it.

What are the other implementation methods besides Context?

It may be convenient to also support render props.

export type FormControlProps = {
  {...},
  children:
    | React.ReactNode
    | ((props: FormControlContextValue) => React.ReactNode);
};

function FormControl() {
  {...}
  return (
    {...}
    {typeof children === "function" ? children(ctxValue) : children}
    {...}
  )
}

function Component() {
  return (
    <FormControl labelText={labelText}>
      {({ id, helperTextId }) => (
        <input id={id} aria-describedby={helperTextId} />
      )}
    </FormControl>
  )
}

TODO

I think the FormControl implementation we did this time can solve most markup problems, but there are still things left to do such as styling and validation.

Styling

Not all labels and supplementary text will be displayed in the same place or appearance. For example, you should probably place radio buttons horizontally with the label. The appearance of FormControl should be able to be flexibly set from the outside.

Validation

Since FormControl does not do anything more than helping markup, I think it is quite compatible with React Hook Form. If you want to add client-side behavior, it is probably easier to separate responsibilities by overlaying it as a higher layer (rather than modifying FormControl).

How to embed live code editor for React components in MDX docs

Matsura Yuma — Thu, 15 Dec 2022 01:08:44 +0000

Overview

I'd like to share how to embed live code editor for React components in your docs page like Chakra UI's docs. Live means that you can, for instance, click the rendered button and the code is editable: if you change the inner text of the button, the preview reflects the change.

By taking the advantage of the extensibility of MDX, we can (kind of) easily accomplish the functionality which looks hard to implement.

Notation is like this:

{/* 3 backticks, actually */}
``tsx live
<>
  <Button variant="solid">Solid</Button>
  <Button variant="subtle">Solid</Button>
  <Button variant="ghost">Solid</Button>
</>
``

And the rendered page is:

We want a live preview (and a code editor) to be shown if there is a live argument, while a normal code block should be shown if no argument is passed.

In this article, I assume you already have a statically-generated site powered by a unified pipeline. Take a look at Gatsby or Next.js starters if not.

Add `remark-mdx-code-meta` plugin

Let's get started from customizing unified pipeline to support the live argument after the triple backtick (code fence) and the name of language. Install remark-mdx-code-meta to do so.

pnpm add remark-mdx-code-meta

/** @type {import('@mdx-js/mdx').CompileOptions} */
const mdxOptions = {
  remarkPlugins: [remarkMdxCodeMeta, ...otherPlugins],
  rehypePlugins: [...otherPlugins],
}

This plugin enables the support for <3 backticks>language key=value notation. The key-value pair is passed to the custom Pre component we'll make in the next section.

Custom `Pre` component

MDX allows us to specify custom components dedicated to each HTML tag by passing an object like { image: Image, pre: Pre }. A code fence is transformed into <pre><code>Your code here</code></pre> so we want to pass a custom component to add the live-preview feature.

The following component examines the content of a pre tag to decide whether it's a code block because pre can be used for other purposes. The role for rendering a preview and highlighted code should be delegated to CodeBlock which is implemented next.

// Pre.tsx
import React from "react"
// We'll create this later
import CodeBlock from "@/components/MdxComponents/CodeBlock"

type Props = {
  live?: boolean
  children?: React.ReactNode
}

export default function Pre({ live, children, ...props }: Props) {
  if (React.isValidElement(children) && children.type === "code") {
    return (
      <div {...props}>
        <CodeBlock live={live} {...children.props} />
      </div>
    )
  }
  return <pre {...props}>{children}</pre>
}

// MdxComponents.tsx
export const mdxComponents: MDXComponents = {
  pre: Pre,
} as const

`CodeBlock` component

We depend on react-live for preview and editor.

// CodeBlock.tsx
import React from "react"
import { LiveProvider, LiveError, LivePreview, LiveEditor } from "react-live"
import { type Language } from "prism-react-renderer"
import theme from "prism-react-renderer/themes/vsDark"
import Button from "@/components/Button"

export default function CodeBlock({ children, className, live }: Props) {
  const language = className.replace(/language-/, "") as Language
  const code = children.replace(/\n$/, "")
  const codeBlock = <code>Render Non-interactive code here...</code>

  if (live) {
    return (
      <LiveProvider code={code} scope={{ Button }}>
        <LivePreview />
        <LiveError />
        <LiveEditor code={code} language={language} theme={theme} />
      </LiveProvider>
    )
  }

  return codeBlock
}

There is nothing difficult here thanks to the simple API, but some things to consider:

The newline (\n) at the end must be trimmed otherwise a blank line is shown in the editor.
Every component you want to render as a preview must be passed to the scope prop.
For non-live codeBlock, you may want to render it by prism-react-renderer which is working also under the LiveEditor. I'm not sure what is the best way to share the style and theme between them but do so anyhow.
LivePreview is not server-rendered so a layout shift occurs, though LiveEditor seems to support SSR. You should refer to Docusaurus Live Codeblock theme for more solid implementation including fallback on the server. Also, see the issue about SSR

Summary

The amount of code is not much but it took me a while for finding the correct way to achieve this feature. I like the docs of MUI and Mantine don't cause any layout shift but their implementation is more complex so I give up for now.

How to build a docs site with Next.js and Contentlayer

Matsura Yuma — Wed, 30 Nov 2022 07:12:02 +0000

This post was originally published on my blog

Have you ever wanted to build a docs site for your open-source library or side project?

Docusaurus is a popular framework for generating docs from Markdown/MDX files and it does a great job! However, perhaps you have already an existing Next.js website so don’t want to create another one from a whole new codebase or on another domain.

In this post, we’ll build a static docs generator powered by Next.js and Contentlayer. Contentlayer is something like Prisma for local Markdown content — you define the schema of documents to make Contentlayer generate validated (so type-safe) JSON data you can import from anywhere.

What we’ll build in this post

Create a Next.js app and install dependencies

Now, let’s get started by creating a new Next app. Make sure to opt-in to TypeScript.

pnpm create next-app
# And answer the prompts
pnpm add contentlayer next-contentlayer sass clsx @heroicons/react remark-gfm rehype-prism-plus

Connect Contentlayer with Next.js

Follow the Getting Started to integrate Contentlayer into Next.js.

// next.config.mjs
import { withContentlayer } from "next-contentlayer";

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
};

module.exports = withContentlayer(nextConfig);

A cool thing is that Contentlayer triggers Fast Refresh as you edit Markdown content, while you need manual reloads with a naive fs.readFile approach.

Define Contentlayer document

Then, we’ll define a Docs schema. You may feel familiar with this (and code generation) if you have ever used Prisma.

We included remark-gfm to support GitHub Flavored Markdown and rehype-prism-plus for syntax highlight of code blocks.

// contentlayer.config.ts
import { defineDocumentType, makeSource } from "contentlayer/source-files";
import rehypePrismPlus from "rehype-prism-plus";
import remarkGfm from "remark-gfm";

export const Docs = defineDocumentType(() => ({
  name: "Docs",
  filePathPattern: `docs/**/*.mdx`,
  contentType: "mdx",
  fields: {
    id: {
      type: "string",
    },
    title: {
      type: "string",
      required: true,
    },
  },
  computedFields: {
    id: {
      type: "string",
      resolve: (doc) => doc.id || doc._raw.flattenedPath.replace("docs/", ""),
    },
    slug: {
      type: "string",
      resolve: (doc) => doc._raw.flattenedPath.replace("docs/", ""),
    },
  },
}));

export default makeSource({
  contentDirPath: "content",
  documentTypes: [Docs],
  mdx: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: [[rehypePrismPlus, { ignoreMissing: true }]],
  },
});

Add MDX content

Let’s write MDX content and add it under content/docs directory. Make sure to put an image named car.jpg in /public directory.

/content/docs/sample.mdx
---
id: "sample"
title: "This is the title"
---

## Heading level 2

### Heading level 3

Ullamco et `nostrud magna` commodo nostrud occaecat quis pariatur id ipsum. Ipsum
consequat enim id excepteur consequat nostrud esse esse fugiat dolore.
Reprehenderit occaecat exercitation non cupidatat in eiusmod laborum ex eu
fugiat aute culpa pariatur. Irure elit proident consequat veniam minim ipsum ex
pariatur.

- list item 1
- list item 2
- list item 3

### Heading level 3

![image alt](/car.jpg)

``ts
function sum(a: number, b: number) {
  return a + b
}
``

Line at the top is the file name. Don’t include it!

Create a dynamic route for docs pages

Now, you can easily import all the docs from contentlayer/generated with validated and typed metadata. No need to dig into the file structure or handle invalid content. Clean!

// /pages/docs/[...slug].tsx
import React from "react";
import { GetStaticPathsResult, GetStaticPropsContext } from "next";
import { useMDXComponent } from "next-contentlayer/hooks";
import { allDocs, type Docs } from "contentlayer/generated";

type Props = {
  doc: Docs;
};

export default function DocsPage({ doc }: Props) {
  const MDXContent = useMDXComponent(doc.body.code);
  return (
    <div>
      <h1>{doc.title}</h1>
      <MDXContent />
    </div>
  );
}

export async function getStaticProps({ params }: GetStaticPropsContext) {
  const slug = params?.slug;
  if (!Array.isArray(slug)) {
    return {
      notFound: true,
    };
  }
  const doc = allDocs.find((post) => post.slug === slug.join("/"));

  if (!doc) {
    return { notFound: true };
  }

  const props: Props = {
    doc,
  };

  return {
    props,
  };
}

export async function getStaticPaths(): Promise<GetStaticPathsResult> {
  const paths = allDocs.map((doc) => ({
    params: { slug: doc.slug.split("/") },
  }));

  return {
    paths,
    fallback: false,
  };
}

Add CSS files
Before writing styles, we’d like to add global CSS files.

reset.css — download here
tokens.css — download here
prism.css — download any here

// /pages/_app.tsx
import "../styles/normalize.css"; // Reset browser defaults
import "../styles/tokens.css"; // Includes CSS variables
import "../styles/prism.css"; // Syntax highlight

If Prism is working correctly, code blocks (surrounded by triple backticks) look pretty like the below:

Style MDX content

We’d like to style the article by wrapping <MDXContent /> with <Markup /> component. This is not the only way but the simplest solution.

/// components/Markup/index.tsx
import React from "react";
import styles from "./styles.module.scss";

type Props = {
  children?: React.ReactNode;
};

export default function Markup({ children }: Props) {
  return <div className={styles.container}>{children}</div>;
}

// /components/Markup/styles.module.scss
.container {
  :where(h2, h3, h4) {
    margin-top: 2.25rem;
    margin-bottom: 1.2rem;
    line-height: 1.3;
  }

  :where(table, img, blockquote) {
    margin-top: 1.5rem;
    margin-bottom: 1.5rem;
  }

  :where(p) {
    margin-top: 1rem;
  }

  :where(ul, ol):not(:first-child) {
    margin: 1.5rem 0;
  }

  :where(ul, ol) :where(ul, ol) {
    // margin-top should be the same as the gap of list items.
    margin: 0.5rem 0 0 0;
  }

  > *:first-child {
    margin-top: 0;
  }

  :where(h2) {
    font-weight: var(--font-weight-bold);
    font-size: var(--font-size-2xl);
    border-bottom: 1px solid var(--color-gray-200);
    padding-bottom: 0.3rem;
  }

  :where(h3) {
    font-weight: var(--font-weight-bold);
    font-size: var(--font-size-xl);
  }

  :where(h4) {
    font-weight: var(--font-weight-bold);
    font-size: var(--font-size-lg);
  }

  :where(a) {
    color: var(--color-primary-600);
    font-weight: var(--font-weight-medium);

    &:hover {
      text-decoration: underline;
    }
  }

  :where(code):not([class*="language-"]) {
    background-color: var(--color-gray-100);
    padding: 0.1em 0.3em;
    border: 1px solid var(--color-gray-200);
    border-radius: var(--rounded-md);
    font-family: var(--font-family-code);
    font-weight: var(--font-weight-medium);
    font-size: 0.9em;
    overflow: auto;
  }

  :where(pre):not([class*="language-"]) {
    // Firefox doesn't support :has() yet, but OK as not so important.
    &:has(code) {
      margin-top: 2rem;
      margin-bottom: 2rem;
    }
  }

  :where(blockquote) {
    border-left: 0.2rem solid var(--color-gray-300);
    padding-left: 1em;
  }

  :where(ul, ol) {
    padding-left: 1.5rem;
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
  }

  :where(ul) {
    list-style: disc;
  }

  :where(ul[class~="contains-task-list"]) {
    list-style: none;
  }

  :where(ol) {
    list-style: decimal;
  }

  :where(p) {
    line-height: 1.75;
  }
}

// /pages/docs/[...slug].tsx
export default function DocsPage({ doc }: Props) {
  return (
      {...}
      <Markup>
        <MDXContent />
      </Markup>
      {...}
  );
}

Layout for the sidebar navigation

Then, let’s create a layout for the sidebar navigation.

// /components/DocsTemplate/index.tsx
import { useMDXComponent } from "next-contentlayer/hooks";
import { type Docs } from "contentlayer/generated";
import Markup from "../Markup";
import styles from "./styles.module.scss";

type Props = {
  doc: Docs;
};

export default function DocsTemplate({ doc: { title, body } }: Props) {
  const MDXContent = useMDXComponent(body.code);
  return (
    <div className={styles.container}>
      <div />
      <article className={styles.article}>
        <header className={styles.header}>
          <h1 className={styles.title}>{title}</h1>
        </header>
        <Markup>
          <MDXContent />
        </Markup>
      </article>
    </div>
  );
}

// /components/DocsTemplate/styles.module.scss
.container {
  display: grid;
  grid-template-columns: 18rem 1fr;
  column-gap: 1rem;
}

.article {
  padding: 1rem;
}

.header {
  padding-bottom: 2rem;

  .title {
    font-weight: var(--font-weight-extrabold);
    font-size: var(--font-size-5xl);
    line-height: 1.2;
    margin: 0;
  }
}

// /pages/docs/[...slug].tsx
export default function DocsPage({ doc }: Props) {
  return <DocsTemplate doc={doc} />;
}

Create Sidebar component

We want to make navigation accept arbitrary levels of nested categories like /category/article.mdx and /cateogry/another-category/article.mdx.

To support this, we define a recursive type (not an official name) as follows:

// /types.ts
export type NavItemCategory = {
  id: string;
  label: string;
  open?: boolean;
  items: NavItem[]; // Self reference
};

export type NavItemLink = {
  id: string;
  label: string;
  href: string;
};

export type NavItem = NavItemCategory | NavItemLink;

And Sidebar component handles the passed data in a recursive way:

// /components/Sidebar/index.tsx
import { ChevronRightIcon } from "@heroicons/react/20/solid";
import clsx from "clsx";
import Link from "next/link";
import { useRouter } from "next/router";
import React from "react";

import { NavItem } from "../../types";

import styles from "./styles.module.scss";

type Props = {
  items: NavItem[];
};

export default function Sidebar({ items }: Props) {
  return (
    <nav className={styles.container}>
      <ul className={styles.list}>
        {items.map((item) => (
          <Item key={item.id} item={item} />
        ))}
      </ul>
    </nav>
  );
}


type ItemProps = {
  item: NavItem;
};

function Item({ item }: ItemProps) {
  const router = useRouter();
  const isActive = React.useCallback(
    (href: string) => href === router.asPath,
    [router.asPath]
  );

  if ("items" in item) {
    // Category
    return (
      <li className={styles.category}>
        <details>
          <summary className={styles.button}>
            {item.label}
            <ChevronRightIcon />
          </summary>
          <ul className={styles.list}>
            {item.items.map((item) => (
              <Item key={item.id} item={item} /> {/* Recursion */}
            ))}
          </ul>
        </details>
      </li>
    );
  } else {
    // Document link
    return (
      <li key={item.href}>
        <Link
          href={item.href}
          className={clsx(
            styles.button,
            isActive(item.href) && styles.isActive
          )}
          aria-current={isActive(item.href) ? "page" : undefined}
        >
          {item.label}
        </Link>
      </li>
    );
  }
}

// /components/Sidebar/styles.module.scss
$rowGap: 0.25rem;

.container {
  padding: 1rem;
  border-right: 1px solid var(--color-gray-200);
  height: 100vh;
  position: sticky;
  top: 0;
}

.list {
  display: grid;
  row-gap: $rowGap;
  color: var(--color-gray-600);
}

.category {
  details[open] {
    > summary svg {
      rotate: 90deg;
    }
  }

  summary {
    display: flex;
    align-items: center;
    justify-content: space-between;
    user-select: none;

    svg {
      width: 1.6rem;
      height: 1.6rem;
      color: var(--color-gray-500);
      translate: 0.25rem;
    }
  }

  summary::-webkit-details-marker {
    display: none;
  }

  ul {
    margin-left: 1rem;
    margin-top: $rowGap;
  }
}

.button {
  display: flex;
  padding: 0.3rem 0.75rem;
  border-radius: var(--rounded-md);
  font-weight: var(--font-weight-medium);
  transition: var(--transition-bg);
  border: 1px solid transparent;
  cursor: pointer;
  width: 100%;

  &.isActive {
    font-weight: var(--font-weight-semibold);
    color: var(--color-primary-500);
    background-color: var(--color-gray-50);
    border-color: var(--color-gray-200);
  }

  &:hover {
    background-color: var(--color-gray-100);
  }
}

Test Sidebar with dummy data

// /components/DocsTemplate/index.tsx
export default function DocsTemplate({ doc: { title, body } }: Props) {
  const MDXContent = useMDXComponent(body.code);
  return (
    <div className={styles.container}>
      <Sidebar
        items={[
          {
            id: "item1",
            href: "#",
            label: "Item 1",
          },
          {
            id: "category1",
            label: "Category 1",
            items: [
              {
                id: "category1-1",
                label: "Category 1-1",
                href: "#",
              },
              {
                id: "category1-2",
                label: "Category 1-2",
                href: "#",
              },
            ],
          },
        ]}
      />
      <article className={styles.article}>
       {...}
      </article>
    </div>
  );
}

Seems like it’s working! The category is handled correctly.

Sidebar data from real content

Add categorized docs

/content/docs/frameworks/react.mdx
---
id: "react"
title: "React"
---

Article about React.

/content/docs/frameworks/vue.mdx
---
id: "vue"
title: "Vue"
---

Article about Vue.

Define sidebar config

We'd like to specify the order and categories in sidebar.js. For the config file, we define types to remove href and make label optional (and default to the title) as follows:

// /types.ts
type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;

export type DocsSidebarItemConfig =
  | NavItemCategory
  | Optional<Omit<NavItemLink, "href">, "label">;

export type DocsSidebarConfig = {
  items: DocsSidebarItemConfig[];
};

// /sidebar.js
/** @type {import('./types').DocsSidebarConfig} */
const sidebar = {
  items: [
    {
      id: "sample",
    },
    {
      id: "frameworks",
      label: "Frameworks",
      items: [
        {
          id: "react",
        },
        {
          id: "vue",
        },
      ],
    },
  ],
};

export default sidebar;

// /lib/docs.ts
import { allDocs } from "contentlayer/generated";
import sidebar from "../sidebar";
import { NavItem, DocsSidebarItemConfig, NavItemLink } from "../types";

export function getSidebarItems(
  items: DocsSidebarItemConfig[] = sidebar.items
) {
  const result: NavItem[] = [];
  for (const item of items) {
    if ("items" in item) {
      // Category
      result.push({
        ...item,
        items: getSidebarItems(item.items),
      });
    } else {
      // Document link
      const doc = allDocs.find((d) => d.id === item.id);
      if (!doc) continue;
      result.push({
        ...item,
        href: "/docs/" + doc.slug,
        label: item.label ?? doc.title,
      });
    }
  }
  return result;
}

// /components/DocsTemplate/index.tsx
type Props = {
  doc: Docs;
  sidebarItems: NavItem[];
};

export default function DocsTemplate({
  doc: { title, body },
  sidebarItems,
}: Props) {
  const MDXContent = useMDXComponent(body.code);
  return (
    <div className={styles.container}>
      <Sidebar items={sidebarItems} />
      <article className={styles.article}>
       {...}
      </article>
    </div>
  );
}

Call getSidebarItems() to get navigation items for the sidebar.

// /pages/docs/[...slug].tsx
type Props = {
  doc: Docs;
  sidebarItems: NavItem[];
};

export default function DocsPage({ doc, sidebarItems }: Props) {
  return <DocsTemplate doc={doc} sidebarItems={sidebarItems} />;
}

export async function getStaticProps({ params }: GetStaticPropsContext) {
  //  {...}
  const doc = allDocs.find((post) => post.slug === slug.join("/"));
  const sidebarItems = getSidebarItems();
  //  {...}
  const props: Props = {
    doc,
    sidebarItems,
  };
  //  {...}
}

It works just like expected!

Still much more to do…

We could build a simple docs generator but there are so many missing things:

Image optimization by next/image
Table of contents
Next/previous navigation
File name for code blocks
Anchor link for each heading
Using React components inside .mdx files
On mobile devices, the sidebar should be hidden and expanded as a modal menu

Saazy Template supports all the missing features!

I built Saazy Template, a Next.js starter for marketing that includes:

Landing page
Pricing page
Sign in page
And other 10+ pages
Docs/blog
Integrated forms
16+ reusable components

Visit the live preview or get it now

How to support admonition (or callout) in Markdown

Matsura Yuma — Wed, 30 Nov 2022 04:56:50 +0000

This post was originally published on my blog

Sometimes you may want to emphasize that command is destructive or note additional information in your blog or docs like this:

But this is not included in standard Markdown or GitHub Flavored Markdown. In this post, I will show you how to support this feature and notation with remark plugins.

I assume you've already set up a static site generator that supports MDX by unified pipeline.

Remark plugins

Support notation

We'd like to add this custom notation for admonition:

:::info
Laboris dolore aliquip laboris irure.
:::

Fortunately, we don't have to write any code as there is remark-directive that does exactly what we need.

yarn add remark-directive

And add it to your own unified pipeline.

import remarkDirective from "remark-directive"
import remarkAdmonition from "./remarkAdmonitions" // We'll implement this next

const remarkPlugins = [remarkDirective, remarkAdmonition]

Convert to `mdxJsxFlowElement`

But remark-directive doesn't do everything we need for displaying admonitions. To convert the block into an MDX component, define the following plugin:

import { visit } from "unist-util-visit"

export default function remarkAdmonition() {
  return (tree) => {
    visit(tree, (node) => {
      if (
        node.type === "textDirective" ||
        node.type === "leafDirective" ||
        node.type === "containerDirective"
      ) {
        if (!["info", "warn", "danger"].includes(node.name)) return
        // Store node.name before overwritten with "Alert".
        const status = node.name

        const data = node.data || (node.data = {})
        const tagName = node.type === "textDirective" ? "span" : "div"

        node.type = "mdxJsxFlowElement"
        node.name = "Admonition"
        node.attributes = [{ type: "mdxJsxAttribute", name: "status", value: status }]
      }
    })
  }
}

Note that the node's name is Admonition. We'll have to add a custom MDX component that has the same name.

React component and styles

Then we need a React component that accepts the status property. This value comes from any of :::info, :::warn or :::danger.

import { HiInformationCircle, HiExclamationTriangle } from "react-icons/hi2"
import clsx from "clsx"
import React from "react"

import styles from "./styles.module.scss"

type SvgComponent = React.ComponentType<React.ComponentProps<"svg">>
type Status = "info" | "danger" | "warn"

type Props = {
  status?: Status
  title?: React.ReactNode
  children?: React.ReactNode
  className?: string
}

const statusIconMap: { [S in Status]: SvgComponent } = {
  info: HiInformationCircle,
  danger: HiExclamationTriangle,
  warn: HiExclamationTriangle,
}

export default function Message({ status = "info", children, className }: Props) {
  const Icon = statusIconMap[status]
  const statusClass = styles[`--${status}`]
  return (
    <aside className={clsx(styles.container, statusClass, className)}>
      <div>
        <Icon className={clsx(styles.icon, statusClass)} />
      </div>
      <div className={styles.text}>
        {children && <div className={styles.message}>{children}</div>}
      </div>
    </aside>
  )
}

$infoColor: #3182ce;
$warnColor: #e6a700;
$dangerColor: #e53e3e;

.container {
  display: grid;
  grid-template-columns: auto 1fr;
  gap: 0.5rem;
  padding: 1rem;
  border-radius: 0.5rem;
  border: 1px solid #e2e8f0;
  border-left-width: 4px;
  background: white;

  &.--info {
    border-left-color: $infoColor;
  }
  &.--warn {
    border-left-color: $warnColor;
  }
  &.--danger {
    border-left-color: $dangerColor;
  }
}

.text {
  display: grid;
  row-gap: 0.25rem;
}

.title {
  display: flex;
  align-items: center;
  column-gap: 0.5rem;
  font-weight: var(--camome-font-weight-bold);
  font-size: var(--camome-font-size-lg);

  &.--info {
    color: $infoColor;
  }
  &.--warn {
    color: $warnColor;
  }
  &.--danger {
    color: $dangerColor;
  }
}

.message {
  & > *:first-child {
    margin-top: 0;
  }

  & > *:last-child {
    margin-bottom: 0;
  }
}

.icon {
  width: 1.75rem;
  height: 1.75rem;

  &.--info {
    color: $infoColor;
  }
  &.--warn {
    color: $warnColor;
  }
  &.--danger {
    color: $dangerColor;
  }
}

Pass it as a custom component

Now, register it as a custom component otherwise MDX complains that you've forgotten to import it!

import { MDXProvider } from "@mdx-js/react"
import Admonition from "@/components/Admonition"

const components = {
  Admonition,
}

export default function Post(props) {
  return (
    <MDXProvider components={components}>
      <main {...props} />
    </MDXProvider>
  )
}

Exact code could be different if you're using mdx-bundler, Contentlayer, or anything else. But there should be a similar API for adding components.

That's all

You can add another type like :::note or anything, and style the component as you want.

Thank you for reading!

How to capture 3D animation and encode it into video by WebCodecs

Matsura Yuma — Wed, 30 Nov 2022 04:40:43 +0000

This post was originally published on my blog

I built a web service called Reaktr that enables users to create audio-reactive video like the demo below:

It can capture every frame of the 3D scene rendered on the browser and encode them into an MP4 video.

I managed this feature to work with the help of WebCodecs API. Most of the APIs are still experimental but available on Chrome.

You can record the viewport of the browser by MediaRecorder but it may be unstable (frames are skipped) and the quality is limited depending on the spec of the user's device. Another method is performing rendering on a server, but it requires a powerful and expensive GPU.

WebCodecs is only supported by Chromium browsers as of 2022-11-30.

The strategy

On the other hand, performing everything on the user's browser enables cost-effective and high-quality rendering (speed depends on the spec of the device, though).

Here's the strategy I did in Reaktr:

Render the 3D scene by Three.js on the HTML Canvas
On every frame, create a new VideoFrame from the Canvas (its constructor accepts Canvas as the first parameter)
Pass the frame to VideoEncoder.prototype.encode method to get an EncodedVideoChunk.
Pass the chunk to WebM Writer to compose a WebM file.
Mux the WebM and audio file on AWS Elemental Convert into an MP4 file.
Upload the MP4 file to S3.

I could mux the video and audio on the browser into an MP4 with MP4Box.js, but somehow it was misformatted and weirdly played with some players. I gave up and relied on Elemental Convert as it's not so expensive.

I found webm-muxer while writing this post and it seems great! I'll try it later.

Source and demo

See the full code and try the demo on the links below:

https://github.com/sabigara/capture-and-encode

https://capture-and-encode.vercel.app/

Create a Three.js scene with two rotating cubes

First, let's create a 3D scene to be captured. I think anything drawn on HTML Canvas can be captured, but this time I'd like to render rotating cubes by Three.js.

import * as THREE from "three"
import "./styles.css"

const appElm = document.getElementById("app")!

const size = {
  width: 1280,
  height: 720,
} as const

function initScene() {
  const scene = new THREE.Scene()
  const camera = new THREE.PerspectiveCamera(75, 16 / 9, 0.1, 1000)
  camera.position.z = 2.5

  const light = new THREE.DirectionalLight(0xffffff, 1)
  light.position.set(0, 0, 2)

  scene.add(light)

  const renderer = new THREE.WebGLRenderer()
  renderer.setSize(size.width, size.height)
  appElm.appendChild(renderer.domElement)

  const cubes = [makeCube([-1, 0, 0]), makeCube([1, 0, 0])]
  scene.add(...cubes)

  return {
    renderer,
    scene,
    camera,
    cubes,
  }
}

function makeCube(position: [number, number, number]) {
  const geometry = new THREE.BoxGeometry(1, 1, 1)
  const material = new THREE.MeshStandardMaterial({
    color: 0x3283a8,
  })

  const cube = new THREE.Mesh(geometry, material)
  cube.position.set(...position)
  return cube
}

const { renderer, cubes, scene, camera } = initScene()

async function onFrame() {
  cubes.forEach((cube, i) => {
    const speed = 0.01 * (i + 1)
    cube.rotation.x += speed
    cube.rotation.y += speed
  })
  renderer.render(scene, camera)

  requestAnimationFrame(onFrame)
}

requestAnimationFrame(onFrame)

Modify WebM Writer to support `EncodedVideoChunk`

WebM Writer is a great library for building a WebM video on the browser. However, it's a little bit slow because it depends on HTMLCanvasElement.prototype.toDataURL.

Fortunately, @tungs has shared a patch that adds support for EncodedVideoChunk.

https://github.com/framekitjs/webm-writer-js-iife/blob/3dcfa6e63f3aa5bf9bd0c747af7a7989ee1a7038/src/WebMWriter.js#L971-L986

Thanks to the addChunk method, we can now take full advantage of the speed of WebCodecs!

Implement `Encoder` class

The following is the implementation of Encoder class.
Here is what this class does:

Composes suitable options for VideoEncoder and WebMWriter
Exposes addFrame method that is called after a frame is drawn on the passed Canvas
Encodes the frames into chunks and passes the chunks to WebMWriter to create a video file
Makes the file downloadable when finished

Modify `onFrame` to call `addFrame`

Initialize an encoder with options and call addFrame before requesting the next animation frame.

const encoder = new Encoder({
  canvas: renderer.domElement,
  duration: 5,
  framerate: 60,
  videoBitrate: 5_000_000,
})
await encoder.prepare()
let recording = false

async function onFrame() {
  // ...
  renderer.render(scene, camera)

  let finished = false
  if (recording) {
    finished = await encoder.addFrame()
  }
  if (!recording || !finished) {
    requestAnimationFrame(onFrame)
  }
}

When the recording variable is true, the encoder will keep adding frames and automatically emits a video file when its length reached the number specified with the duration option.

You don't have to worry about the execution time of the function as the next frame will never be drawn while processing addFrame. So, even cheap machines can reliably capture the animation, unlike real-time recording which might end up with a laggy result.

5 seconds after turning on the recording flag, the following video will be downloaded:

That's it!

Thanks to WebCodecs and WebM Writer, I could take full advantage of GPU without writing so much code by myself.

I hope other browsers than Chrome add support for WebCodecs soon!

Forem: Matsura Yuma

Implement FormControl to ensure form accessibility in React

Usage

Implementation method

Approach

Define Context

Implement FormControl

Implement Input

Extend Input

Other considerations

What if nested?

Is it bad idea to enclose input by label?

What are the other implementation methods besides Context?

TODO

Styling

Validation

How to embed live code editor for React components in MDX docs

Overview

Add remark-mdx-code-meta plugin

Custom Pre component

CodeBlock component

Summary

How to build a docs site with Next.js and Contentlayer

What we’ll build in this post

Create a Next.js app and install dependencies

Connect Contentlayer with Next.js

Define Contentlayer document

Add MDX content

Create a dynamic route for docs pages

Style MDX content

Layout for the sidebar navigation

Create Sidebar component

Test Sidebar with dummy data

Sidebar data from real content

Add categorized docs

Define sidebar config

Still much more to do…

Saazy Template supports all the missing features!

How to support admonition (or callout) in Markdown

Remark plugins

Support notation

Convert to mdxJsxFlowElement

React component and styles

Pass it as a custom component

That's all

How to capture 3D animation and encode it into video by WebCodecs

The strategy

Source and demo

Create a Three.js scene with two rotating cubes

Modify WebM Writer to support EncodedVideoChunk

Implement Encoder class

Modify onFrame to call addFrame

That's it!

Is it bad idea to enclose `input` by `label`?

Add `remark-mdx-code-meta` plugin

Custom `Pre` component

`CodeBlock` component

Convert to `mdxJsxFlowElement`

Modify WebM Writer to support `EncodedVideoChunk`

Implement `Encoder` class

Modify `onFrame` to call `addFrame`