lobe-editor / rules

---
description: Comprehensive React component development guidelines for LobeHub Editor
globs: *.tsx,*.jsx,src/react/**/*,src/plugins/*/react/**/*
---

# React Component Guidelines

React code lives in two places:

1. [src/react/](mdc:src/react/): high-level components exported from `@lobehub/editor/react`
   (`ChatInput`, `ChatInputActionBar`, `ChatInputActions`, `CodeLanguageSelect`, `Editor`,
   `EditorProvider`, `FloatActions`, `SendButton`) and hooks (`useEditor`, `useEditorState`).
2. `src/plugins/<name>/react/`: React plugins (`React<Name>Plugin`) exported from
   `@lobehub/editor`.

## Component Folder

Mirror [src/react/SendButton/](mdc:src/react/SendButton/):

```text
src/react/<Component>/
├── <Component>.tsx   # FC + default export + displayName
├── type.ts           # Props interface with JSDoc
├── style.ts          # createStaticStyles
├── index.ts          # export { default } from './<Component>'; export * from './type';
├── components/       # Optional private sub-components
├── demos/index.tsx   # Docs demo
├── index.mdx         # Docs page
└── __tests__/        # When there is logic
```

Then export it from [src/react/index.ts](mdc:src/react/index.ts):
`export { default as <Component>, type <Component>Props } from './<Component>';`.

## Component Pattern

```tsx
'use client';

import { cx } from '@lobehub/ui';
import { type FC, useCallback } from 'react';

import { styles } from './style';
import type { MyButtonProps } from './type';

const MyButton: FC<MyButtonProps> = ({ className, style, disabled, onClick, children }) => {
  const handleClick = useCallback(() => {
    if (!disabled) onClick?.();
  }, [disabled, onClick]);

  return (
    <button className={cx(styles.root, className)} onClick={handleClick} style={style} type="button">
      {children}
    </button>
  );
};

MyButton.displayName = 'MyButton';

export default MyButton;
```

```typescript
// type.ts
import type { CSSProperties, ReactNode } from 'react';

export interface MyButtonProps {
  children?: ReactNode;
  className?: string;
  /**
   * Disable the button
   * @default false
   */
  disabled?: boolean;
  onClick?: () => void;
  style?: CSSProperties;
}
```

- Use `memo` only with a `// Keep memo: <reason>` comment (see `src/react/Editor/Editor.tsx`,
  `src/react/ChatInputActions/ChatInputActions.tsx`).
- Use `useMemo` / `useCallback` where they avoid real work or keep props stable, not by default.

## Styling

```typescript
// style.ts
import { createStaticStyles } from '@lobehub/ui';

export const styles = createStaticStyles(({ css, cssVar }) => ({
  root: css`
    border-radius: ${cssVar.borderRadiusLG};
    color: ${cssVar.colorText};
  `,
}));
```

- Styles are computed once at module load: use `cssVar` tokens (CSS variables) and CSS custom
  properties for runtime values (e.g. `var(--send-button-size, 32px)` in `SendButton`).
- Merge class names with `cx` from `@lobehub/ui`.
- The package no longer depends on `antd` / `antd-style`; do not add `createStyles` hooks.

## React Plugin Pattern

```tsx
'use client';

import { type FC, useLayoutEffect } from 'react';

import { useLexicalComposerContext } from '@/editor-kernel/react/react-context';
import { MarkdownPlugin } from '@/plugins/markdown/plugin';

import { ListPlugin } from '../plugin';
import type { ReactListPluginProps } from './type';

const ReactListPlugin: FC<ReactListPluginProps> = ({ enableHotkey = true }) => {
  const [editor] = useLexicalComposerContext();

  useLayoutEffect(() => {
    editor.registerPlugin(MarkdownPlugin);
    editor.registerPlugin(ListPlugin, { enableHotkey });
  }, []);

  return null;
};

ReactListPlugin.displayName = 'ReactListPlugin';

export default ReactListPlugin;
```

- `editor` here is the kernel (`IEditor`), obtained from context; React plugins do not take an
  `editor` prop.
- Render node UI through the kernel plugin's `decorator` option, not by returning JSX from the
  plugin component (plugins with floating UI, e.g. `slash` or `toolbar`, are the exception).
- Translations: `useTranslation()` from `@/editor-kernel/react/useTranslation`.

## Using the Editor

```tsx
import { ReactCodeblockPlugin, ReactListPlugin, ReactMentionPlugin } from '@lobehub/editor';
import { Editor, useEditor } from '@lobehub/editor/react';

const MyEditor = () => {
  const editor = useEditor();

  return (
    <Editor
      editor={editor}
      mentionOption={{ items: mentionItems }}
      onTextChange={(editor) => {
        const markdown = editor.getDocument('markdown');
      }}
      placeholder="Start typing..."
      plugins={[
        ReactListPlugin,
        ReactCodeblockPlugin,
        Editor.withProps(ReactMentionPlugin, { className: 'my-mention' }),
      ]}
      slashOption={{ items: slashItems }}
    />
  );
};
```

- Pass plugin options with `Editor.withProps(ReactXPlugin, props)`.
- `onChange` / `onTextChange` are debounced by `debounceWait`; `onTextChange` ignores
  selection-only changes.
- `useEditorState(editor)` exposes toolbar state and actions (bold, lists, blocks, ...).

### Chat Input

```tsx
import { ChatInput, ChatInputActionBar, ChatInputActions, Editor, SendButton } from '@lobehub/editor/react';

<ChatInput
  footer={
    <ChatInputActionBar
      left={<ChatInputActions items={actions} />}
      right={<SendButton onSend={handleSend} />}
    />
  }
>
  <Editor editor={editor} plugins={plugins} />
</ChatInput>;
```

## Demos

Demos in `demos/` import from `@lobehub/editor` / `@lobehub/editor/react` and have one
`export default` each. Use `devConsole` from `@/utils/debug` only in demos for ad-hoc output.

## Testing

Vitest + jsdom. Render with `createRoot` and `act` (see
`src/react/SendButton/__tests__/SendButton.test.tsx`); wrap components that use motion in
`MotionProvider` from `@lobehub/ui`. There is no Testing Library or Jest dependency.