Forem: Muhammad Ali

Live code editing in docusaurus - UX at its best

Muhammad Ali — Sat, 22 Aug 2020 16:08:52 +0000

Docusaurus is a tool designed to make it easy for teams to publish documentation websites without having to worry about the infrastructure and design details.

Docusaurus 2 is bringing a lot of new features with it but my most favorite one is live code editing. It lets you preview your changes at run-time without switching your context which gives you a really good user experience.

Installation

There is an official plugin to enable live code editing in your website, i.e. @docusaurus/theme-live-codeblock. This theme provides a @theme/CodeBlock component that is powered by react-live.
First, install the plugin in your website.

yarn add @docusaurus/theme-live-codeblock

You will also need to add the plugin to your docusaurus.config.js.

module.exports = {
  // ...
  themes: ['@docusaurus/theme-live-codeblock'],
  // ...
};

Usage

To use the plugin, create a code block with live attached to the language meta string.

```jsx live
function Clock(props) {
  const [date, setDate] = useState(new Date());
  useEffect(() => {
    var timerID = setInterval(() => tick(), 1000);

    return function cleanup() {
      clearInterval(timerID);
    };
  });

  function tick() {
    setDate(new Date());
  }

  return (
    <div>
      <h2>It is {date.toLocaleTimeString()}.</h2>
    </div>
  );
}
```

The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.

Third-party Components

By default React is in scope of live code blocks in MDX files but in order to render third-party components we need to add those components in the scope by swizzling the default theme, i.e. @docusaurus/theme-classic.
To swizzle a component for a theme, run the following command in your doc site:

docusaurus swizzle <theme name> [component name]

In our case, theme name is @docusaurus/theme-classic and component name is MDXComponents:

yarn swizzle @docusaurus/theme-classic MDXComponents

It'll copy the MDXComponents folder to src/themes. Let's say we want to render Button from material-ui, so we'll have to update the index.js file and add Button in the scope of CodeBlock component:

// ... imports

+ import Button from "@material-ui/core/Button";

export default {
  code: props => {
    const { children } = props;
    if (typeof children === "string") {
-      return <CodeBlock {...props} />;
+      return <CodeBlock {...props} scope={{ Button }} />;
    }
    return children;
  },

  // ...

};

Now, in your live code block you can just use the Button component which will render button from material-ui:

```jsx live
function MuiButton() {
  return (
    <Button variant="contained" color="primary">
      Primary
    </Button>
  );
}
```

You can also add the whole package in scope but that'll increase your bundle size even if you're not using most of the components, so I'd prefer optimized imports and adding the only components which are being used.

Customization

In order to customize the design / implementation of the code block and code preview we'll swizzle the theme:

yarn swizzle @docusaurus/theme-live-codeblock Playground

Let's change orientation of the playground by editing src/themes/Playground/index.js:

// ...

<LiveProvider
  code={children.replace(/\n$/, "")}
  transformCode={transformCode || (code => `${code};`)}
  theme={theme}
  {...props}
>
  <div className={styles.playgroundPreview}>
    <LivePreview />
    <LiveError />
  </div>
  <div
    className={classnames(
      styles.playgroundHeader,
      styles.playgroundEditorHeader,
    )}
  >
    Live Editor
  </div>
  <LiveEditor />
</LiveProvider>

// ...

You can customize this file as you like, I just wanted to demonstrate how easily you can do that.

Caution

Docusaurus team discourages the usage of swizzle so use it with caution:

We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.

Some documentation part of the article is copied from official docs of docusaurus.
And thanks to Johnny's comment which saved me from more digging regarding scope of code block.

Web Monetization made easy for Gatsby

Muhammad Ali — Fri, 05 Jun 2020 22:31:51 +0000

What I built

I'm late to the party as I got to know about #gftwhackathon yesterday. Without further ado, I read the docs of Web Monetization API and thought of creating a package for react. But after a bit of digging I found react-monetize and some other packages which were doing the same thing, so I created Gatsby plugin for react-monetize.

Submission Category:

Foundational Technology: Gatsby plugin for Web Monetization API

Link to Code

mrmuhammadali / gatsby-plugin-monetization

Gatsby plugin for integration of Web Monetization API

gatsby-plugin-monetization

A Gatsby plugin for react-monetize to speed up your integration with Web Monetization API

Install

yarn add gatsby-plugin-monetization

npm install --save gatsby-plugin-monetization

How to use

You can read how to get your payment pointer on official website of Web Monetization API.

import { useContent, useStatus } from 'gatsby-plugin-monetization';

function MyComponent() {
    // ...
    const { state, events } = useStatus();
    const { isMonetized } = useContent();
    // ...
}

./gatsby-config.js

module.exports = {
    plugins: [
        {
            resolve: `gatsby-plugin-monetization`,
            options: {
                // [required]
                paymentPointer: 'your-payment-pointer',
            },
        },
    ],
};

Examples

To setup playground locally, run following commands (without -) in sequence:

- git clone git@github.com:mrmuhammadali/gatsby-plugin-monetization.git
- cd gatsby-plugin-monetization/examples
- yarn install
- yarn start

Author

👤 Muhammad Ali hi@muhammadali.dev

Twitter: @muhammadali_io
Github: @mrmuhammadali

react-monetize Author

…

View on GitHub

Instructions for setting up example code is given in the docs.

How I built it

Technology Stack:

React
Babel
Gatsby

I learned about Web Monetization API and how it works along the way and it was my first time of creating a plugin for Gatsby.

Additional Resources/Info

I've some ideas to create components necessary for Web Monetization API to integrate in React.

I've also created a PR in official docs of web monetization API to publish this plugin there.

Managing list of form fields with formik through example

Muhammad Ali — Tue, 31 Dec 2019 18:32:15 +0000

Managing sign-in / sign-up form is not that difficult, everyone does it, but what if you've an editable list to manage which has hundreds of items, e.g. a todo app? Worry not formik is to the rescue.

Why Formik

Getting values in and out of form state is very easy and straightforward
Handles form submission, validation and error messages very well
Keeps form state local
I'm not in mood of crying

What you're going to learn

Create editable HTML tag using contentEditable prop
Formik's useField hook
FieldArray component to manage list

Getting Started

Let's create a basic component, i.e. TodoApp.jsx, for our todo list app:

const INITIAL_TODOS = [
  { id: 1, content: "learn react", isCompleted: true },
  { id: 2, content: "learn react hooks", isCompleted: true },
  { id: 3, content: "learn formik", isCompleted: false }
];

const TodoItem = ({ content, isCompleted }) => (
  <div className={["todo-item", isCompleted ? "completed" : ""].join(" ")}>
    <input type="checkbox" checked={isCompleted} />
    <span contentEditable={true} className="todo-text">{content}</span>
  </div>
);

export const TodoApp = () => {
  return INITIAL_TODOS.map(todo => (
    <TodoItem
      key={todo.id}
      content={todo.content}
      isCompleted={todo.isCompleted}
    />
  ));
};

We've 3 todo items along with checkboxes and their content, a checkbox shows if a todo item is complete or not.
Everything is same old React except contentEditable prop which is doing some magic, right? Well, it basically make content of an HTML tag editable whether it's text or anything else. We'll see it's real usage in next couple of code snippets.
Let's add some basic styling for todo items:

.todo-item {
  display: flex;
  border: 1px dashed #999;
  margin: 5px 0;
  padding: 5px;
}
.todo-item.completed {
  text-decoration: line-through;
  background: #80eec5;
}
.todo-text {
  flex-grow: 1;
  margin-left: 10px;
  min-height: 20px;
  /* Removes outline when using contentEditable */
  outline: none;
  overflow: hidden;
  word-break: break-word;
}

The one with Formik

Run yarn add formik or npm i --save formik in your project repo.
We're going to wrap our todo items with Formik.

import { Formik } from "formik";

export const TodoApp = () => (
  <Formik initialValues={{ todos: INITIAL_TODOS }}>
    {formikProps => {
      const { values } = formikProps;

      return values.todos.map((todo, index) => (
        <TodoItem key={todo.id} index={index} />
      ));
    }}
  </Formik>
);

Nothing has happened just yet in actual but we've successfully integrated formik with our tiny TodoApp.

The one with useField

We've to change TodoItem component now as we're passing index of the array in props.

import { useField } from "formik";

const TodoItem = ({ index }) => {
  // Binding `isCompleted` using index of todos array
  const [completedField] = useField({ name: `todos[${index}].isCompleted`, type: "checkbox" });
  // Binding `content` using index of todos array
  const [contentField, contentMeta, contentHelpers] = useField(`todos[${index}].content`);
  const onContentInput = e => {
    contentHelpers.setValue(e.currentTarget.innerText);
  };
  const onContentBlur = () => {
    contentHelpers.setTouched(true);
  };

  return (
    <div
      className={["todo-item", completedField.value ? "completed" : ""].join(" ")}
    >
      <input
        type="checkbox"
        name={completedField.name}
        checked={completedField.checked}
        onChange={({ target }) => {
          completedHelpers.setValue(target.checked);
          // As type=checkbox doesn't call onBlur event
          completedHelpers.setTouched(true);
        }}
      />
      <span
        contentEditable={true}
        className={"todo-text"}
        onInput={onContentInput}
        onBlur={onContentBlur}
      >
        {/*
         * We must set html content through `contentMeta.initialValue`,
         * because `contentField.value` will be updated upon `onChange | onInput`
         * resulting in conflicts between states of content. As 1 will be managed by
         * React and other with contentEditable prop.
         */}
        {contentField.value}
      </span>
    </div>
  );
};

Custom hooks are now part of formik >= v2, useField hook returns a 3-tuple (an array with three elements) containing FieldProps, FieldMetaProps and FieldHelperProps. It accepts either a string of a field name or an object as an argument. The object must at least contain a name key. You can read more about useField here.

The one with FieldArray

Enough with the static data, let's dig a bit deeper and create an Add button for dynamically creating todo items. To do that we can make use of FieldArray. FieldArray is a component that helps with common array/list manipulations. You pass it a name property with the path to the key within values that holds the relevant array, i.e. todos. FieldArray will then give you access to array helper methods via render props.

Common array helper methods:

push: (obj: any) => void: Add a value to the end of an array
swap: (indexA: number, indexB: number) => void: Swap two values in an array
move: (from: number, to: number) => void: Move an element in an array to another index
remove<T>(index: number): T | undefined: Remove an element at an index of an array and return it

To read more about FieldArray visit official documentation.

import { Form, Formik, FieldArray } from "formik";

export const TodoApp = () => (
  <Formik initialValues={{ todos: [] }}>
    <Form>
      {/* Pass name of the array, i.e. `todos` */}
      <FieldArray name="todos">
        {({ form, ...fieldArrayHelpers }) => {
          const onAddClick = () => {
            fieldArrayHelpers.push({
              id: values.todos.length,
              content: "",
              isCompleted: false
            });
          };

          return (
            <React.Fragment>
              <button onClick={onAddClick}>Add Item</button>
              {form.values.todos.map(({ id }, index) => (
                <TodoItem key={id} index={index} />
              ))}
            </React.Fragment>
          );
        }}
      </FieldArray>
    </Form>
  </Formik>
);

There you go, it was that simple, you've a working Todo app.

You can add more features like removing the completed items but that's totally up to you.

          ...
const onRemoveClick = () => {
  form.setFieldValue(
    "todos",
    form.values.todos.filter(todo => !todo.isCompleted)
  );
};

<button onClick={onRemoveClick}>Remove</button>
          ...

I've skipped the validation part in this article as it was pretty simple but it's all implemented in the sandbox embedded below:

Most of the documentation part is taken from formik's official documentation and big thanks to Jared Palmer for all of the efforts.