Hugging Face's logo

Spaces:
NERDDISCO
/
LeRobot.js
Running

App Files Community
LeRobot.js / docs /planning /003_demo_in_react.md
NERDDISCO's picture
NERDDISCO
feat: added calibrate
ec936d5
preview code
|
raw
history blame contribute delete
11.1 kB

User Story 003: Interactive React Demo

Story

As a potential lerobot.js user exploring the library capabilities
I want an interactive web demo with a modern, polished UI
So that I can easily test robot calibration features and understand the library's potential before integrating it into my own projects

Background

While lerobot.js provides platform-agnostic robotics functionality, we need a compelling demo interface to showcase its web capabilities. The current development setup uses Vite with basic HTML/CSS, but lacks the polish needed to demonstrate professional robotics applications.

The Python lerobot ecosystem includes various visualization tools and demos. For lerobot.js, we need a modern web demo that:

  1. Showcases the existing web calibration functionality from User Story 002
  2. Provides an intuitive UI for robot setup and calibration
  3. Demonstrates real-time robot interaction capabilities
  4. Serves as a reference implementation for web integration

Critical Requirement: React, Tailwind, and shadcn/ui should be development dependencies only - the core lerobot library must remain framework-agnostic so users can integrate it with any frontend framework or vanilla JavaScript.

Acceptance Criteria

Core Demo Features

  • Robot Calibration Interface: Modern UI for SO-100 follower/leader calibration
  • Port Selection: Intuitive Web Serial API port selection with visual feedback
  • Calibration Progress: Real-time progress indicators during calibration procedures
  • Configuration Display: View and manage saved calibration configurations
  • Error Handling: User-friendly error messages and recovery suggestions
  • Responsive Design: Works on desktop, tablet, and mobile devices

UI/UX Requirements

  • Modern Design: Clean, professional interface using Tailwind 4 and shadcn/ui
  • Brand Consistency: Consistent with Hugging Face design language
  • Accessibility: WCAG 2.1 AA compliant interface
  • Dark/Light Mode: Theme switching support
  • Loading States: Smooth loading and transition animations
  • Visual Feedback: Clear status indicators for connection, calibration, and errors

Technical Requirements

  • Framework Isolation: React used only for demo, core library remains framework-agnostic
  • Development Only: React/Tailwind/shadcn as devDependencies, not regular dependencies
  • Vite Integration: Seamless integration with existing Vite development setup
  • TypeScript: Full type safety throughout React components
  • Build Separation: Demo build separate from library build
  • Tree Shaking: Demo dependencies excluded from library builds

Library Integration

  • Web API Usage: Demonstrates proper usage of lerobot web APIs
  • Error Boundaries: Robust error handling that doesn't break the demo
  • Performance: Smooth interaction without blocking the UI thread
  • Real Hardware: Demo works with actual SO-100 hardware via Web Serial API

Expected User Flow

Development Experience 

# Install demo dependencies (includes React, Tailwind, shadcn/ui as devDependencies)
$ pnpm install

# Start development server with React demo
$ pnpm run dev
# Opens modern React interface at http://localhost:5173

Demo Interface Flow

  1. Landing Page: Clean introduction to lerobot.js with call-to-action buttons
  2. Robot Setup: Card-based interface for selecting robot type (SO-100 follower/leader)
  3. Port Connection:
    • Click "Connect Robot" button
    • Browser shows Web Serial API port selection dialog
    • Visual feedback shows connection status
  4. Calibration Interface:
    • Step-by-step calibration wizard
    • Progress indicators and instructions
    • Real-time motor position feedback (if applicable)
  5. Results Display:
    • Success confirmation with visual feedback
    • Option to download configuration file
    • Suggestions for next steps

Error Handling Flow

  • No Web Serial Support: Clear message with browser compatibility info
  • Connection Failed: Troubleshooting steps with visual aids
  • Calibration Errors: Descriptive error messages with retry options
  • Permission Denied: Guide user through browser permission setup

Implementation Details

Project Structure Changes 

lerobot.js/
├── src/
│   ├── demo/                    # Demo-specific React components (new)
│   │   ├── components/
│   │   │   ├── ui/              # shadcn/ui components
│   │   │   ├── CalibrationWizard.tsx
│   │   │   ├── RobotCard.tsx
│   │   │   ├── ConnectionStatus.tsx
│   │   │   └── ErrorBoundary.tsx
│   │   ├── pages/
│   │   │   ├── Home.tsx
│   │   │   ├── Setup.tsx
│   │   │   └── Calibrate.tsx
│   │   ├── hooks/
│   │   │   ├── useRobotConnection.ts
│   │   │   └── useCalibration.ts
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── lerobot/                 # Core library (unchanged)
│   │   ├── web/
│   │   └── node/
│   └── main.ts                  # Original Vite entry (unchanged)
├── index.html                   # Updated to load React demo
├── demo.html                    # New: Vanilla JS demo option
└── lib.html                     # New: Library-only demo

Package.json Changes 

{
  "scripts": {
    "dev": "vite --mode demo", // Runs React demo
    "dev:vanilla": "vite --mode vanilla", // Runs vanilla demo
    "dev:lib": "vite --mode lib", // Library-only mode
    "build": "tsc && vite build --mode lib", // Library build (no React)
    "build:demo": "tsc && vite build --mode demo" // Demo build (with React)
  },
  "devDependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "tailwindcss": "^4.0.0",
    "@tailwindcss/typography": "^0.5.0",
    "autoprefixer": "^10.4.0",
    "postcss": "^8.4.0",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "tailwind-merge": "^2.0.0",
    "lucide-react": "^0.400.0"
  }
}

Vite Configuration 

// vite.config.ts
export default defineConfig(({ mode }) => {
  const baseConfig = {
    plugins: [typescript()],
    build: {
      lib: {
        entry: "src/main.ts",
        name: "LeRobot",
        fileName: "lerobot",
      },
    },
  };

  if (mode === "demo") {
    return {
      ...baseConfig,
      plugins: [...baseConfig.plugins, react()],
      css: {
        postcss: {
          plugins: [tailwindcss, autoprefixer],
        },
      },
      build: {
        // Demo-specific build configuration
        outDir: "dist/demo",
        rollupOptions: {
          input: {
            main: "index.html",
          },
        },
      },
    };
  }

  return baseConfig; // Library-only build
});

Key Dependencies

Demo-Only Dependencies (devDependencies)

  • React 18: Latest stable React with concurrent features
  • Tailwind CSS 4: Latest Tailwind with modern CSS features
  • shadcn/ui: High-quality React component library
  • Lucide React: Modern icon library
  • class-variance-authority: For component variant management
  • clsx + tailwind-merge: For conditional class management

Build Tools

  • @vitejs/plugin-react: React support for Vite
  • PostCSS: CSS processing for Tailwind
  • Autoprefixer: CSS vendor prefixing

React Components Architecture

Core Demo Components 

// Demo-specific React hooks
function useRobotConnection() {
  // Wraps lerobot web APIs in React-friendly hooks
  // Manages connection state, error handling
}

function useCalibration() {
  // Wraps lerobot calibration APIs
  // Provides progress tracking, status updates
}

// Main calibration wizard component
function CalibrationWizard({ robotType }: { robotType: string }) {
  const { connect, disconnect, status } = useRobotConnection();
  const { calibrate, progress, error } = useCalibration();

  // Multi-step wizard UI using shadcn/ui components
}

shadcn/ui Integration

  • Button: Primary actions (Connect, Calibrate, Retry)
  • Card: Robot selection, status displays, results
  • Progress: Calibration progress indicators
  • Alert: Error messages and warnings
  • Badge: Status indicators (Connected, Calibrating, Error)
  • Dialog: Confirmation dialogs and detailed error information
  • Toast: Success/error notifications

Technical Considerations

Framework Isolation Strategy

  1. Separate Entry Points: Demo uses React, library uses vanilla TypeScript
  2. Build Modes: Vite modes for demo vs library builds
  3. Dependency Isolation: React in devDependencies, excluded from library bundle
  4. Type Safety: Shared types between demo and library, but no runtime dependencies

Tailwind 4 Integration

  • New CSS Engine: Leverage Tailwind 4's improved performance
  • Container Queries: Responsive components using container queries
  • Modern CSS: CSS Grid, flexbox, custom properties integration
  • Optimization: Automatic unused CSS elimination

Performance Considerations

  • Code Splitting: Lazy load calibration components
  • Bundle Size: Demo bundle separate from library bundle
  • Web Serial API: Non-blocking serial communication
  • Error Boundaries: Prevent component crashes from breaking entire demo

Accessibility

  • Keyboard Navigation: Full keyboard support for all interactions
  • Screen Readers: Proper ARIA labels and descriptions
  • Color Contrast: WCAG AA compliant color schemes
  • Focus Management: Proper focus handling during async operations

Testing Strategy

Integration Testing

  • Library Integration: Verify demo correctly uses lerobot APIs
  • Build Testing: Ensure library builds don't include React
  • Browser Compatibility: Test Web Serial API across supported browsers

Definition of Done

  • Functional Demo: Interactive React demo showcases robot calibration
  • Modern UI: Professional interface using Tailwind 4 and shadcn/ui
  • Framework Isolation: React isolated to demo only, library remains framework-agnostic
  • Build Separation: Library builds exclude React dependencies
  • Browser Compatibility: Works in Chrome, Edge, and other Chromium browsers
  • Responsive Design: Works across desktop, tablet, and mobile devices
  • Accessibility: WCAG 2.1 AA compliant interface
  • Error Handling: Graceful error handling with user-friendly messages
  • Documentation: Demo usage documented in README
  • Performance: Smooth interactions, fast loading times
  • Type Safety: Full TypeScript coverage for demo components
  • Real Hardware: Successfully calibrates actual SO-100 hardware via Web Serial API