$3

$3

🚀 Getting Started

$3

Run example (recommended)

Run tests

Type checking

$3

The example app runs in a separate directory:

`typescript
import {
Mosaic,
MosaicWindow,
createBalancedTreeFromLeaves,
getLeaves,
} from 'react-mosaic-ui';

function App() {
const [tree, setTree] = useState | null>(null);

const createNode = () => window-${Date.now()};

const autoArrange = () => {
if (!tree) return;
const leaves = getLeaves(tree);
const balanced = createBalancedTreeFromLeaves(leaves);
setTree(balanced);
};

return (
renderTile={(id, path) => (
path={path}
title={id}
createNode={createNode}
onDragStart={() => console.log('Drag started')}
onDragEnd={(type) => console.log('Drag ended:', type)}
additionalControls={


`typescript
path={path}
title="Window"
onDragStart={() => {
console.log('Window drag started');
}}
onDragEnd={(type) => {
// type: 'drop' | 'reset'
console.log('Window drag ended:', type);
}}
>


`typescript
path={path}
title="Window"
additionalControls={


`css
:root {
--rm-border-color: #cbd5e1;
--rm-background: #ffffff;
--rm-window-bg: #f8fafc;
--rm-toolbar-bg: #f1f5f9;
--rm-split-color: #94a3b8;
--rm-split-hover: #64748b;
--rm-split-size: 4px;
--rm-toolbar-height: 40px;
}
`

🔧 API

$3

`typescript
interface MosaicProps {
renderTile: (id: T, path: MosaicPath) => JSX.Element;
value?: MosaicNode | null;
initialValue?: MosaicNode | null;
onChange?: (node: MosaicNode | null) => void;
onRelease?: (node: MosaicNode | null) => void;
className?: string;
zeroStateView?: JSX.Element;
mosaicId?: string;
createNode?: () => T | Promise;
}
`

$3

`typescript
interface MosaicWindowProps {
title: string;
path: MosaicPath;
children: ReactNode;
createNode?: () => T | Promise;
draggable?: boolean;
toolbarControls?: ReactNode;
additionalControls?: ReactNode;
renderToolbar?: (props: MosaicWindowToolbarProps, defaultToolbar: ReactNode) => ReactNode;
onDragStart?: () => void;
onDragEnd?: (type: 'drop' | 'reset') => void;
className?: string;
}
`

$3

`typescript
// Tree manipulation
getLeaves(node: MosaicNode): T[]
getNodeAtPath(node: MosaicNode, path: MosaicPath): MosaicNode | null
createBalancedTreeFromLeaves(leaves: T[]): MosaicNode | null

// Tree updates
updateTree(root: MosaicNode, updates: MosaicUpdate[]): MosaicNode
createRemoveUpdate(root: MosaicNode, path: MosaicPath): MosaicUpdate
createExpandUpdate(path: MosaicPath, percentage?: number): MosaicUpdate
`

🛠️ Tech Stack

- React 18+: UI library
- TypeScript 5: Type safety
- Rollup: Bundler
- Tailwind CSS v4: Styling (prefix: rm-)
- React DnD: Drag and drop
- Immer: Immutable state updates
- Vitest: Testing
- Bun: Package manager

📋 Features

✅ Modern React: React 18+ support
✅ TypeScript: Full type safety
✅ FSD Architecture: Scalable structure
✅ Tailwind CSS v4: Conflict-free styling (rm- prefix)
✅ Tree Structure: Flexible layouts
✅ Drag and Drop: Intuitive UI based on React DnD
✅ Built-in Controls: Replace, Split, Expand, Remove buttons
✅ Additional Controls: Drawer menu via additionalControls
✅ Drag Events: onDragStart, onDragEnd hooks
✅ Customization: Theme via CSS variables, full customization via renderToolbar
✅ Controlled/Uncontrolled: Both modes supported

🤝 Contributing

This project strictly follows FSD architecture and clean code principles.
Before contributing, please review the Clean Code Guide and FSD Architecture.

$3

This project uses Husky for git hooks and follows conventional commit standards.

#### Commit Message Format

All commits must follow the conventional commit format:

`
type(scope?): subject

Examples:
feat: add window resize feature
fix(mosaic): resolve drag and drop issue
docs: update README
`

Allowed types:
- feat: New feature
- fix: Bug fix
- docs: Documentation changes
- style: Code style changes (formatting, missing semicolons, etc.)
- refactor: Code refactoring
- test: Adding or updating tests
- chore: Maintenance tasks
- perf: Performance improvements
- ci: CI/CD changes
- build: Build system changes
- revert: Revert previous commit

#### Pre-commit Hooks

Before each commit, the following checks run automatically:
1. Linting (bun run lint)
2. Type checking (bun run typecheck)
3. Tests (bun test)

If any check fails, the commit will be blocked.

$3

This project uses release-it for automated releases.

#### Creating a Release

`bash


Patch release (1.0.0 → 1.0.1)

The release process will:
1. Run all checks (lint, typecheck, tests)
2. Build the project
3. Update version in package.json
4. Generate/update CHANGELOG.md
5. Create a git tag
6. Push to GitHub
7. Create a GitHub release
8. Publish to npm

📄 License

MIT