refactor!: Sync repository

.circleci/config.yml

@@ -1,85 +1,76 @@
-version: 2
+version: 2.1
+
+orbs:
+  node: circleci/node@7.2.1
 
-references:
-  js_deps_cache_key: &js_deps_cache_key v1-dependencies-{{ checksum "yarn.lock" }}
-  workspace_root: &workspace_root .
-  attach_workspace: &attach_workspace
-    attach_workspace:
-      at: *workspace_root
 jobs:
   build:
-    docker:
-      - image: circleci/node:gallium
-    working_directory: ~/react-mosaic
+    executor:
+      name: node/default
+      tag: '22.22.1'
+      resource_class: large
     steps:
       - checkout
+      - node/install-packages:
+          pkg-manager: npm
+          with-cache: true
       - run:
-          name: Install Yarn
-          command: |
-            curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 1.22.18
-            export PATH="$HOME/.yarn/bin:$PATH"
-      - restore_cache:
-          keys:
-            - *js_deps_cache_key
-      - run: yarn install --frozen-lockfile
-      - save_cache:
-          paths:
-            - node_modules
-            - ~/.cache/yarn
-          key: *js_deps_cache_key
-      - run:
-          name: Build
-          command: yarn build
+          name: Build library and demo app
+          command: npm run build:lib && npm run build:app
       - persist_to_workspace:
-          root: *workspace_root
+          root: .
           paths:
-            - .
+            - dist
+            - node_modules
+
   test:
-    docker:
-      - image: circleci/node:dubnium
-    working_directory: ~/react-mosaic
+    executor:
+      name: node/default
+      tag: '22.22.1'
+      resource_class: large
     steps:
-      - *attach_workspace
-      - run: mkdir reports
+      - checkout
+      - node/install-packages:
+          pkg-manager: npm
+          with-cache: true
       - run:
-          name: Run unit tests
-          command: yarn test:unit --reporter mocha-junit-reporter --reporter-options mochaFile=reports/mocha/test-results.xml
+          name: Run linting
+          command: npm run lint
       - run:
-          name: Lint
-          command: yarn test:lint --format junit -o ./reports/tslint/tslint.xml
-      - store_test_results:
-          path: reports
-      - store_artifacts:
-          path: ./reports/mocha/test-results.xml
-      - store_artifacts:
-          path: ./reports/tslint/tslint.xml
-  deploy:
-    docker:
-      - image: circleci/node:dubnium
-    working_directory: ~/react-mosaic
+          name: Run tests
+          command: npm test
+
+  publish:
+    executor:
+      name: node/default
+      tag: '22.22.1'
+      resource_class: medium
     steps:
-      - *attach_workspace
+      - checkout
+      - attach_workspace:
+          at: .
       - run:
-          name: Publish
-          command: |
-            npm set //registry.npmjs.org/:_authToken=$NPM_TOKEN
-            npm publish
+          name: Authenticate with NPM registry
+          command: npm set //registry.npmjs.org/:_authToken=$NPM_TOKEN
+      - run:
+          name: Publish to NPM
+          command: npm publish dist/libs/react-mosaic-component/
+
 workflows:
-  version: 2
-  build-test-deploy:
+  version: 2.1
+  build-test-publish:
     jobs:
       - build:
           filters:
             tags:
               only: /^v.*/
       - test:
-          requires:
-            - build
           filters:
             tags:
               only: /^v.*/
-      - deploy:
+      - publish:
           requires:
+            - build
             - test
           filters:
             tags:

.claude/README.md

@@ -0,0 +1,194 @@
+# Claude Code Integration for React Mosaic
+
+This directory contains all the files for optimal Claude Code and LLM integration with the React Mosaic project.
+
+## Directory Contents
+
+### Configuration Files
+- **`settings.json`**: Claude Code project settings and preferences
+- **`.claudeignore`** (in root): Files/directories to exclude from LLM context
+
+### Documentation
+- **`../claude.md`**: Comprehensive project documentation for LLMs (in root)
+- **`../CONTRIBUTING_AI.md`**: AI/LLM-specific contribution guidelines (in root)
+- **`../QUICKREF.md`**: Quick reference guide for common operations (in root)
+
+### Slash Commands (`commands/`)
+Quick commands for common development tasks:
+
+- `/test` - Run tests and report failures
+- `/build` - Build the library
+- `/lint` - Run linting checks
+- `/type-check` - Run TypeScript type checking
+- `/analyze-tree` - Analyze tree manipulation utilities
+- `/review-component` - Review a specific component
+- `/explain-concept` - Explain core React Mosaic concepts
+- `/add-feature` - Plan and implement a new feature
+- `/fix-issue` - Debug and fix an issue
+- `/refactor` - Refactor code for better quality
+- `/update-deps` - Check for outdated dependencies
+
+### Prompt Templates (`prompts/`)
+Reusable templates for common scenarios:
+
+- **`tree-analysis.md`**: Template for analyzing tree structures
+- **`code-review.md`**: Template for reviewing code
+- **`feature-planning.md`**: Template for planning new features
+- **`debugging.md`**: Template for debugging issues
+
+## Quick Start for AI Assistants
+
+1. **Read `claude.md` first** - This provides comprehensive context about the project
+2. **Check `QUICKREF.md`** - Quick reference for common operations
+3. **Review `.claudeignore`** - Know what files to skip
+4. **Use slash commands** - Quick access to common tasks
+5. **Follow patterns in `CONTRIBUTING_AI.md`** - Guidelines for code contributions
+
+## Project Structure Overview
+
+```
+react-mosaic/
+├── .claude/                          # Claude Code integration files
+│   ├── commands/                     # Slash commands
+│   ├── prompts/                      # Prompt templates
+│   ├── settings.json                 # Project settings
+│   └── README.md                     # This file
+├── libs/react-mosaic-component/      # Main library [PRIMARY FOCUS]
+│   └── src/lib/                      # Source code
+│       ├── types.ts                  # Type definitions
+│       ├── contextTypes.ts           # Context types
+│       └── util/                     # Utility functions
+├── apps/demo-app/                    # Demo application
+├── claude.md                         # LLM integration guide
+├── CONTRIBUTING_AI.md                # AI contribution guidelines
+├── QUICKREF.md                       # Quick reference
+├── .claudeignore                     # Files to ignore
+└── README.md                         # User documentation
+```
+
+## Key Concepts
+
+React Mosaic is a tiling window manager built on:
+
+1. **N-ary Tree Structure**: Layout represented as a tree with split nodes, tab nodes, and leaf nodes
+2. **Numeric Paths**: Nodes identified by array of indices (e.g., `[0, 1, 2]`)
+3. **Immutable Updates**: Tree modifications always create new instances
+4. **React Context**: Components communicate via context API
+5. **Drag & Drop**: Built on react-dnd with multi-backend support
+
+## Development Workflow
+
+```bash
+# Setup
+npm install
+
+# Development
+npm start           # Start dev server
+npm test           # Run tests
+npm run build:lib  # Build library
+
+# Code Quality
+npm run lint       # Lint code
+npm run format     # Format code
+```
+
+## Important Files
+
+| File | Description |
+|------|-------------|
+| `libs/react-mosaic-component/src/index.ts` | Public API exports |
+| `libs/react-mosaic-component/src/lib/types.ts` | Type definitions |
+| `libs/react-mosaic-component/src/lib/util/mosaicUtilities.ts` | Tree operations |
+| `libs/react-mosaic-component/src/lib/util/mosaicUpdates.ts` | Tree mutations |
+
+## Using Slash Commands
+
+Slash commands provide quick access to common tasks:
+
+```
+/test                 # Run the test suite
+/build                # Build the library
+/explain-concept      # Learn about a core concept
+/add-feature          # Plan and add a new feature
+```
+
+## Using Prompt Templates
+
+Prompt templates help maintain consistency:
+
+1. Navigate to `.claude/prompts/`
+2. Choose appropriate template
+3. Follow the structure provided
+4. Adapt to your specific need
+
+## Best Practices for AI
+
+1. **Always read files before modifying** - Use Read tool first
+2. **Use utility functions** - Don't manually manipulate trees
+3. **Follow existing patterns** - Match code style and conventions
+4. **Write tests** - Add tests for new functionality
+5. **Check types** - Ensure TypeScript compilation passes
+6. **Use type guards** - Use `isSplitNode()` and `isTabsNode()`
+7. **Validate paths** - Check paths before tree operations
+8. **Handle edge cases** - Test with empty, single, and nested trees
+
+## Common Patterns
+
+### Tree Manipulation
+```typescript
+import { updateTree, createRemoveUpdate } from 'react-mosaic-component';
+
+const newTree = updateTree(currentTree, [
+  createRemoveUpdate(path)
+]);
+```
+
+### Type Checking
+```typescript
+import { isSplitNode, isTabsNode } from 'react-mosaic-component';
+
+if (isSplitNode(node)) {
+  // node is MosaicSplitNode<T>
+}
+```
+
+### Context Access
+```typescript
+import { useContext } from 'react';
+import { MosaicContext } from 'react-mosaic-component';
+
+const { mosaicActions } = useContext(MosaicContext);
+mosaicActions.remove(path);
+```
+
+## Resources
+
+- **Project Documentation**: `../claude.md`
+- **Quick Reference**: `../QUICKREF.md`
+- **AI Guidelines**: `../CONTRIBUTING_AI.md`
+- **User Documentation**: `../README.md`
+- **Live Demo**: https://nomcopter.github.io/react-mosaic/
+- **GitHub**: https://github.com/nomcopter/react-mosaic
+
+## Contributing
+
+See `CONTRIBUTING_AI.md` for detailed guidelines on:
+- Code style and conventions
+- Testing requirements
+- Common patterns
+- Debugging strategies
+- Performance considerations
+
+## Support
+
+For issues or questions:
+- Check `claude.md` for comprehensive information
+- Use `/explain-concept` to understand core concepts
+- Review existing code for patterns
+- Ask specific questions about the codebase
+
+## Version
+
+This integration is designed for React Mosaic v0.20.0.
+
+Last updated: 2025-12-04

.claude/commands/add-feature.md

@@ -0,0 +1,16 @@
+---
+description: Plan and implement a new feature
+---
+
+I'll help you plan and implement a new feature for react-mosaic.
+
+First, describe the feature you want to add. I will then:
+
+1. Analyze the existing codebase to understand relevant patterns
+2. Create a detailed implementation plan
+3. Identify files that need to be modified or created
+4. Implement the feature following existing code conventions
+5. Add appropriate tests
+6. Update documentation if needed
+
+What feature would you like to add?

.claude/commands/analyze-tree.md

@@ -0,0 +1,10 @@
+---
+description: Analyze the MosaicNode tree structure utilities
+---
+
+Analyze the tree manipulation utilities in the codebase, specifically:
+
+1. Read and explain the tree utilities in `libs/react-mosaic-component/src/lib/util/mosaicUtilities.ts`
+2. Read and explain the tree update functions in `libs/react-mosaic-component/src/lib/util/mosaicUpdates.ts`
+3. Provide examples of how to use these utilities for common operations
+4. Identify any potential improvements or edge cases to handle

.claude/commands/build.md

@@ -0,0 +1,5 @@
+---
+description: Build the react-mosaic library
+---
+
+Build the react-mosaic library using `npm run build:lib`. Report any build errors or warnings and suggest fixes if needed.

.claude/commands/explain-concept.md

@@ -0,0 +1,16 @@
+---
+description: Explain a core concept of react-mosaic
+---
+
+Explain a core concept of the react-mosaic library. I can explain:
+
+1. **Tree Structure**: How the n-ary tree layout works
+2. **Path System**: How paths identify nodes in the tree
+3. **Drag & Drop**: How the drag-and-drop system is implemented
+4. **Split Nodes**: How split containers divide space
+5. **Tab Nodes**: How tabbed interfaces work
+6. **Context API**: How components communicate via React context
+7. **Tree Updates**: How immutable tree updates work
+8. **Migration**: How legacy binary trees are converted to n-ary
+
+Which concept would you like me to explain?

.claude/commands/fix-issue.md

@@ -0,0 +1,19 @@
+---
+description: Debug and fix an issue in the codebase
+---
+
+I'll help you debug and fix an issue in the react-mosaic codebase.
+
+Describe the issue you're experiencing, including:
+- What behavior you're seeing
+- What behavior you expected
+- Steps to reproduce (if applicable)
+- Error messages (if any)
+
+I will then:
+
+1. Investigate the relevant code
+2. Identify the root cause
+3. Propose a solution
+4. Implement the fix
+5. Add tests to prevent regression