mywhy-ui

React component library for the mywhy robotics framework. Built with TypeScript, Tailwind CSS, and semantic design tokens.

Install

npm install mywhy-ui

Peer dependencies: react >= 18 and react-dom >= 18

Setup

1. Tailwind preset

Add the mywhy-ui preset to your tailwind.config.js:

import mywhyPreset from 'mywhy-ui/tailwind-preset'

export default {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/mywhy-ui/dist/**/*.{js,cjs}",
  ],
  presets: [mywhyPreset],
}

2. CSS variables (optional)

Import the global CSS custom properties for runtime theming:

// main.tsx
import 'mywhy-ui/globals.css'

Usage

import {
  Button, Input, Select, Switch, Badge,
  Alert, Tabs, FormControl, Progress,
  FileUploader, StatusBadge, useToast
} from 'mywhy-ui'

function App() {
  const { toast } = useToast()

  return (
    <div className="space-y-4">
      {/* Foundation */}
      <Button variant="solid" theme="brand" onClick={() => toast('Welcome!')}>
        Launch Robot
      </Button>
      <Input label="Robot Name" placeholder="Enter name" />
      <Switch label="Enable ROS Bridge" />

      {/* Alerts & Status */}
      <Alert theme="success" title="Connected" isDismissible>
        Robot is online and ready
      </Alert>
      <StatusBadge status="online" label="Base Station" />

      {/* Forms */}
      <FormControl label="Upload Configuration" required>
        <FileUploader accept=".yaml,.yml" />
      </FormControl>

      {/* Tabs with Content */}
      <Tabs
        tabs={[
          { label: 'Settings', value: 'settings', content: <div>Settings panel</div> },
          { label: 'Status', value: 'status', content: <div>Status panel</div> },
        ]}
      />

      {/* Progress & Rating */}
      <Progress value={65} label="Upload Progress" />
    </div>
  )
}

Components

Foundation (5)

• Button — Variants: solid, subtle, outline, ghost, link. Themes: brand, success, danger, warning, gray. Sizes: xs, sm, md, lg.
• Input — Text input with label, error state, prefix/suffix icons, and size variants.
• Select — Dropdown select with label and error state.
• Switch — Toggle switch with label, description, and error handling.
• Spinner — Loading indicator with customizable size and color.

Core UI (7)

• Badge — Status labels with semantic color themes.
• Avatar — User avatars with initials fallback, multiple sizes and shapes.
• Card — Container component with optional title and subtitle.
• Checkbox — Labeled checkbox with description and error support.
• Textarea — Multi-line text input with sizes and error states.
• Alert — Dismissible alert messages with themes: info, success, warning, danger.
• MultiSelect — Multi-value select with search, clearable, and file-like tag display.

Form Components (1)

• FormControl — Wrapper component for form fields with label, description, error, and helper text.

Navigation (3)

• Tabs — Tab navigation with variants: underline, soft. Keyboard accessible.
• Breadcrumbs — Hierarchical navigation trail with separator customization.
• Dropdown — Menu dropdown with icons, disabled states, and danger styling.

Overlays (4)

• Dialog — Modal dialog with backdrop and focus management.
• Toast / ToastContainer — Notification toasts with automatic dismiss.
• Tooltip — Hover tooltips with placement control: top, bottom, left, right.
• Link — Styled anchor with brand colors and hover effects.

Pickers (2)

• DatePicker — Date selection with formatted display and min/max constraints.
• TimePicker — Time selection with 12h/24h format support.

Advanced UI (4)

• Progress — Progress bar with themes, sizes, and optional labels.
• Rating — Star rating component with interactive selection and readonly mode.
• Slider — Range input with visual feedback and customizable styling.
• Sidebar — Collapsible navigation sidebar with sections, icons, and badges.

File Handling (1)

• FileUploader — Drag-and-drop file uploader with size validation and preview.

Robotics (2)

• StatusBadge — Robot status badge with pulse animation (online, warning, error, offline, connecting).
• ConnectionIndicator / ConnectionIcon — WebSocket connection status display.

Hooks (2)

• useDisclosure — Toggle state management for modals/drawers/disclosure components.
• useToast — Programmatic toast notification creation and management.

Design Tokens

The Tailwind preset provides semantic color tokens:

| Token | Purpose | |-------|---------| | ink-* | Text colors (default, gray, light, faint) | | surface-* | Backgrounds (default, gray, light, subtle, overlay) | | brand-* | Primary brand colors | | outline-* | Border colors | | status-* | Robot health (online, warning, error, offline) | | role-* | User roles (admin, operator, viewer) | | ros-* | ROS2 accents (topic, service, action, parameter) |

Development

Commands

# Build the library
npm run build

# Watch mode during development
npm run dev

# Type checking
npm run type-check

# Storybook (component documentation)
npm run storybook

# Run tests
npm test

# Run tests with UI
npm run test:ui

# Coverage report
npm run test:coverage

Project Structure

src/
├── components/          # All UI components
│   ├── Button/
│   ├── Input/
│   ├── Tabs/
│   └── ...
├── hooks/              # Custom React hooks
├── test/               # Test utilities and setup
├── globals.css         # Global styles and CSS variables
├── index.ts            # Main entry point
└── tailwind-preset.js  # Tailwind configuration

.storybook/            # Storybook configuration

Adding New Components

1. Create a new folder: src/components/ComponentName/
2. Add ComponentName.tsx with the component implementation
3. Add index.ts for exports
4. Add ComponentName.stories.tsx for Storybook documentation
5. Add ComponentName.test.tsx for unit tests
6. Export from src/index.ts

License

MIT