Using kintone UI Component v1 in React with @lit/react

[h000780]

Background

createComponent() is the API provided by @lit/react, which allows Web Components to be directly used within React.
Based on this API, KUC Components can also be seamlessly integrated and utilized within React applications.

Here is an unofficial guide on how to create React wrapper of KUC v1.
Unofficial means that we don't test the behavior and support it.
So please develop on your own responsibility.

Please give us feedback if you have any opinions or feedback.

Alternative Integration Approach

This guide presents a method using @lit/react to create React wrappers for KUC components, which is particularly beneficial for TypeScript projects. Before developing this approach, we documented a more direct method using DOM manipulation and refs, which you can find here: Using kintone UI Component v1 in React.

The previous approach may be easier to implement initially but can become challenging when working with complex components or in TypeScript environments.

Overview

This article introduces how to create React wrapper components for KUC Components without modifying the KUC source code itself. This approach allows you to use KUC components in your React customization projects.

‼️The method described here has been verified with:

• KUC v1.20.1
• @lit/react v1.0.7
• Compatible with React 18 and React 19

While most KUC components can be successfully wrapped for React, there is a limitation to be aware of:

• Complex Event Interactions: In particularly complex event handling scenarios (such as nested custom events or cross-component event coordination), subtle differences may still exist.

Preparation

Before creating React wrappers for KUC components, follow these general steps:

1. Install the required dependencies:

npm install kintone-ui-component @lit/react

2. Move to the customization project source code where you want to use KUC.

Simple components

This method can be applied following components:

• desktop:
  • Attachment, Checkbox, Combobox, DatePicker, DateTimePicker, Dropdown, MultiChoice, RadioButton, Text, TextArea, TimePicker
• mobile:
  • Checkbox, DatePicker, DateTimePicker, Dropdown, MultiChoice, RadioButton, Text, TextArea, TimePicker

We will use the createComponent() API to wrap some simple components from @lit/react to achieve this conversion.
Create React wrapper components using the createComponent() API (as shown in the examples below)

import React from "react";
import { createComponent } from "@lit/react";
import { Text } from "kintone-ui-component";

export const ReactText = createComponent({
  react: React, 
  tagName: `kuc-text-1-20-1`, 
  elementClass: Text, 
  events: {
    onChange: "change",
    onFocus: "focus",
    onInput: "input"
  }
});

In this example, we created a new ReactText component based on the KUC Text component. When the value of the ReactText component changes, it triggers an onChange/onFocus/onInput event, which is consistent with the behavior of the KUC Text component.

Import and use these wrapper components in your React application

<App>
  ...
    <ReactText
      value="sample text"
      label="React Wrapper"
      onChange={(event) => {
        console.log(event);
      }}
      onInput={(event) => {
        console.log(event);
      }}
      onFocus={(event) => {
        console.log(event);
      }}
    />
</App>

Components that can contain HTML elements

This method can be applied following components:

• desktop:
  • Button, Dialog, FieldGroup, Notification, Spinner, Tabs, Tooltip
• mobile:
  • Button, Notification

However, some KUC Components have custom components set directly through properties. These cannot be used directly after conversion and need further wrapping. The wrapping method will be explained in conjunction with the sample of the button component.

We create a KucReactButton class through the createComponent() API.

import { createComponent } from "@lit/react";
import { Button, ButtonProps } from "kintone-ui-component/lib/button";
import React, { ReactElement } from "react";
import { createRoot } from "react-dom/client";

export const KucReactButton = createComponent({
  react: React,
  tagName: `kuc-button-1-20-1`,
  elementClass: Button,
  events: {
    onClick: 'click',
  },
});

Then, we need to rewrite the ButtonProps type declaration, changing the type of the content property from content?: string | HTMLElement to string | ReactElement, and adding the onClick property.

Note that the event name here must be consistent with the key of the events parameter in createComponent() :

type ReactButtonProps = Omit<ButtonProps, "content"> & {
  content?: string | ReactElement;
} & { onClick?: (e: Event) => void };

Finally, we create a new ReactButton component that uses the KucReactButton component internally and handles updates to custom components:

const ReactButton: React.FC<ReactButtonProps> = ({ content, ...otherProps }) => {
  const [transformedContent, setTransformedContent] = useState<string | HTMLElement>("");

  useEffect(() => {
    setTransformedContent(transformContent(content));
  }, [content]);

  const transformContent = (originalContent: string | ReactElement | undefined): string | HTMLElement => {
    if (typeof originalContent === "string") {
      return originalContent;
    }
    if (originalContent) {
      const contentElement = document.createElement("div");
      const root = createRoot(contentElement);
      root.render(originalContent);
      return contentElement;
    }
    return "";
  };

  return <KucReactButton content={transformedContent} {...otherProps} />;
};

In this example, the ReactButton component uses the KucReactButton component internally and updates the custom component when the content property changes.
This is achieved by calling the transformContent method within a useEffect hook that executes whenever the content prop changes.

In the transformContent method:

• If content is a string type, the method simply returns the string as is
• If content is a React element, the method uses React's createRoot method to create a new React root on a newly created div element and renders the content prop within it
• If content is undefined, an empty string is returned

Then, in the component's return statement, we pass the transformed content (the transformedContent state) to the KucReactButton component as its content property, while passing all other props through the spread operator.

Through this approach, we have successfully converted the KucButton component into a ReactButton component that can accept React elements as content.
In React, we can use it like this:

const [buttonContent, setButtonContent] = React.useState<string | ReactElement>(
    "test",
  );
<App>
  <ReactButton
    onClick={() => {
      setButtonContent(<span>clicked</span>);
    }}
    content={buttonContent}
  />
</App>

Components with method

This method can be applied following components:

• desktop:
  • Dialog, Notification, Spinner
• mobile:
  • Notification

In KUC, there are 4 components that expose methods for programmatic control: Dialog, Notification, Spinner, and MobileNotification. These components provide methods like open() and close() that need special handling when used in React.
We use Dialog for our example.
Method: open(), close()

The wrapper created by createComponent() can not call the methods of the custom element directly.
We need to use a ref to call the methods of KUC components.

• We can call the open method of the dialog in react directly through ref and createComponent.
  Here is the suggested usage:
  • Define the Dialog component with createComponent()

import React from "react";
import { createComponent } from "@lit/react";
import { Dialog } from "kintone-ui-component/lib/dialog";

export const ReactDialog = createComponent({
  react: React,
  tagName: `kuc-dialog-1-20-1`,
  elementClass: Dialog,
  events: {
    onClose: "close",
  }
});

export { Dialog as KucDialog }

• Use ref to open the dialog

const dialogRef = useRef<KucDialog>(null);
return (
  <div className="App">
    <DialogComponent
      icon="info"
      title="React Dialog"
      content="<div style='font-size:50px;'>Content</div>"
      footer="Footer"
      onClose={() => {
        console.log("close");
      }}
      ref={dialogRef}
    />
    <ReactButton text={"Open Dialog"} onClick={()=>{dialogRef.current?.open()}}/>
  </div>
);

Demo:

• We can also transform the open method into the isOpen property
  We will create a property isOpen because the open() and close() methods are used to control whether the dialog is open or not.
  Here is the sample:
  • Use createComponent() to create a Dialog Component.
    Then use the Dialog Component to create a React wrapper with the property isOpen.

import React, { useEffect, useRef } from "react";
import { createComponent } from "@lit/react";
import { Dialog, DialogProps } from "kintone-ui-component/lib/dialog";

const DialogComponent = createComponent({
  react: React,
  tagName: `kuc-dialog-1-20-1`,
  elementClass: Dialog,
  events: {
    onClose: "close",
  }
});

type ReactDialogProps = DialogProps & { isOpen?: boolean; onClose?: () => void };

export const ReactDialog = (props: ReactDialogProps) => {
  const dialogRef = useRef<Dialog>(null);

  useEffect(() => {
    if (props.isOpen) {
      dialogRef.current?.open();
    } else {
      dialogRef.current?.close();
    }
  }, [props.isOpen]);

  return <DialogComponent {...props} ref={dialogRef} />;
};

• In React, use State to open the dialog.

const [isOpen, setIsOpen] = useState(false);
return (
  <div className="App">
    <ReactDialog
      icon="success"
      title="React Dialog"
      content="<div style='font-size: 40px; color: #ff0000'>Content</div>"
      footer="Footer"
      isOpen={isOpen}
      onClose={() => {
        setIsOpen(false);
      }}
    />
    <ReactButton text={"Open Dialog"} onClick={()=>{setIsOpen(true)}}/>
  </div>
);

Complex components

This method can be applied following components:

• desktop:
  • Table, ReadOnlyTable

Finally, let's look at how to handle those KUC Components that set custom components in callback methods.
In the table, custom components are set in the render property, and they can be wrapped in React in another way. Here is an example of wrapping a table in React.

First, we create a KucReactTable component using createComponent:

import { createComponent } from "@lit/react";
import { Table, TableColumn, TableProps } from "kintone-ui-component/lib/table";
import React, { ReactElement } from "react";
import { createRoot } from "react-dom/client";

export const KucReactTable = createComponent({
  react: React,
  tagName: `kuc-table-1-20-1`,
  elementClass: Table,
  events: {
    onChange: "change"
  }
});

Then, we rewrite the type declaration, change the HTMLElement in the type declaration to ReactElement, and add an event in ReactTableProps -> onChange?: (event: any) => void;

type ReactTableColumn = Omit<TableColumn, "render"> & {
  render?: (cellData: any, rowData: object, rowIndex: number) => ReactElement;
};

type ReactTableProps = Omit<TableProps, "columns"> & {
  columns?: ReactTableColumn[];
} & { onChange?: (e: Event) => void };

Next, we create a new ReactTable component that uses the KucReactTable component internally and handles updates to child components.

export const ReactTable = (props: ReactTableProps) => {
  const { columns, ...otherProps } = props;
  const newColumns = columns?.map((column) => {
    const { render, ...otherColumnProps } = column;
    return {
      ...otherColumnProps,
      render: render
        ? (cellData: any, rowData: object, rowIndex: number) => {
            const contentElement = document.createElement("div");
            const root = createRoot(contentElement);
            root.render(render(cellData, rowData, rowIndex));
            return contentElement;
          }
        : undefined,
    };
  });
  return <KucReactTable columns={newColumns} {...otherProps} />;
};

The process starts by grabbing the columns from the ReactTable component's props. It checks each column for a render function. If it finds one, it wraps the function's output in a new DOM container, similar to how we wrapped a Button before. These updated columns are then passed to the KucReactTable for display.

In React, we can use it like this:

const renderCheckBox = (
    cellData: string[] | undefined,
    _rowData: any,
    _index: any,
  ) => {
    return (
      <ReactCheckBox
        label="checkbox"
        requiredIcon={true}
        items={items}
        value={cellData}
        onChange={(event: any) => {
          console.log(event);
        }}
      ></ReactCheckBox>
    );
  };

<App>
  <ReactTable
    columns={[
        {
          title: "Name",
          field: "name",
          requiredIcon: true,
          render: renderCheckBox,
        }
      ]}
      data={[{ name: ["sample1"] }]}
      onChange={(event) => {
        console.log(event);
      }}
  ></ReactTable>
</App>

These are the detailed steps on how to convert KUC components to React components. Hope this article will be helpful for you!