cherry-studio/packages/ui/MIGRATION_STATUS.md

UI Component Library Migration Status

Usage Example

// Import components from @cherrystudio/ui
import { Spinner, DividerWithText, InfoTooltip } from '@cherrystudio/ui'

// Use in components
function MyComponent() {
  return (
    <div>
      <Spinner size={24} />
      <DividerWithText text="Divider Text" />
      <InfoTooltip content="Tooltip message" />
    </div>
  )
}

Directory Structure

@packages/ui/
├── src/
│   ├── components/         # Main components directory
│   │   ├── base/           # Basic components (buttons, inputs, labels, etc.)
│   │   ├── display/        # Display components (cards, lists, tables, etc.)
│   │   ├── layout/         # Layout components (containers, grids, spacing, etc.)
│   │   ├── icons/          # Icon components
│   │   ├── interactive/    # Interactive components (modals, tooltips, dropdowns, etc.)
│   │   └── composite/      # Composite components (made from multiple base components)
│   ├── hooks/              # Custom React Hooks
│   └── types/              # TypeScript type definitions

Component Classification Guide

When submitting PRs, please place components in the correct directory based on their function:

• base: Most basic UI elements like buttons, inputs, switches, labels, etc.
• display: Components for displaying content like cards, lists, tables, tabs, etc.
• layout: Components for page layout like containers, grid systems, dividers, etc.
• icons: All icon-related components
• interactive: Components requiring user interaction like modals, drawers, tooltips, dropdowns, etc.
• composite: Composite components made from multiple base components

Migration Overview

• Total Components: 236
• Migrated: 34
• Refactored: 18
• Pending Migration: 184

Component Status Table

Category	Component Name	Migration Status	Refactoring Status	Description
base				Base components
	CopyButton	✅	✅	Copy button
	CustomTag	✅	✅	Custom tag
	DividerWithText	✅	✅	Divider with text
	EmojiIcon	✅	✅	Emoji icon
	ErrorBoundary	✅	✅	Error boundary (decoupled via props)
	StatusTag	✅	✅	Unified status tag (merged ErrorTag, SuccessTag, WarnTag, InfoTag)
	IndicatorLight	✅	✅	Indicator light
	Spinner	✅	✅	Loading spinner
	TextBadge	✅	✅	Text badge
	CustomCollapse	✅	✅	Custom collapse panel
display				Display components
	Ellipsis	✅	✅	Text ellipsis
	ExpandableText	✅	✅	Expandable text
	ThinkingEffect	✅	✅	Thinking effect animation
	EmojiAvatar	✅	✅	Emoji avatar
	ListItem	✅	✅	List item
	MaxContextCount	✅	✅	Max context count display
	ProviderAvatar	✅	✅	Provider avatar
	CodeViewer	❌	❌	Code viewer (external deps)
	OGCard	❌	❌	OG card
	MarkdownShadowDOMRenderer	❌	❌	Markdown renderer
	Preview/*	❌	❌	Preview components
layout				Layout components
	HorizontalScrollContainer	✅	❌	Horizontal scroll container
	Scrollbar	✅	❌	Scrollbar
	Layout/*	✅	✅	Layout components
	Tab/*	❌	❌	Tab (Redux dependency)
	TopView	❌	❌	Top view (window.api dependency)
icons				Icon components
	Icon	✅	✅	Icon factory function and predefined icons (merged CopyIcon, DeleteIcon, EditIcon, RefreshIcon, ResetIcon, ToolIcon, VisionIcon, WebSearchIcon, WrapIcon, UnWrapIcon, OcrIcon)
	FileIcons	✅	❌	File icons (FileSvgIcon, FilePngIcon)
	ReasoningIcon	✅	❌	Reasoning icon
	SvgSpinners180Ring	✅	❌	Spinner loading icon
	ToolsCallingIcon	✅	❌	Tools calling icon
interactive				Interactive components
	InfoTooltip	✅	❌	Info tooltip
	HelpTooltip	✅	❌	Help tooltip
	WarnTooltip	✅	❌	Warning tooltip
	EditableNumber	✅	❌	Editable number
	InfoPopover	✅	❌	Info popover
	CollapsibleSearchBar	✅	❌	Collapsible search bar
	ImageToolButton	✅	❌	Image tool button
	DraggableList	✅	❌	Draggable list
	CodeEditor	✅	❌	Code editor
	EmojiPicker	❌	❌	Emoji picker (useTheme dependency)
	Selector	✅	❌	Selector (i18n dependency)
	ModelSelector	❌	❌	Model selector (Redux dependency)
	LanguageSelect	❌	❌	Language select
	TranslateButton	❌	❌	Translate button (window.api dependency)
composite				Composite components
	-	-	-	No composite components yet
Uncategorized				Components needing categorization
	Popups/* (16+ files)	❌	❌	Popup components (business coupled)
	RichEditor/* (30+ files)	❌	❌	Rich text editor
	MarkdownEditor/*	❌	❌	Markdown editor
	MinApp/*	❌	❌	Mini app (Redux dependency)
	Avatar/*	❌	❌	Avatar components
	ActionTools/*	❌	❌	Action tools
	CodeBlockView/*	❌	❌	Code block view (window.api dependency)
	ContextMenu	❌	❌	Context menu (Electron API)
	WindowControls	❌	❌	Window controls (Electron API)
	ErrorBoundary	❌	❌	Error boundary (window.api dependency)

Migration Steps

Phase 1: Copy Migration (Current Phase)

• Copy components as-is to @packages/ui
• Retain original dependencies (antd, styled-components, etc.)
• Add original path comment at file top

Phase 2: Refactor and Optimize

• Remove antd dependencies, replace with HeroUI
• Remove styled-components, replace with Tailwind CSS
• Optimize component APIs and type definitions

Notes

1. Do NOT migrate components with these dependencies (can be migrated after decoupling):

   • window.api calls
   • Redux (useSelector, useDispatch, etc.)
   • Other external data sources

2. Can migrate but need decoupling later:

   • Components using i18n (change i18n to props)
   • Components using antd (replace with HeroUI later)

3. Submission Guidelines:

   • Each PR should focus on one category of components
   • Ensure all migrated components are exported
   • Update migration status in this document