npm package: @stolution/ui
Description: Stolution's Material-UI based component library for PWA-first applications
Author: Stolution Team
Latest version: 1.1.0

# @stolution/ui

> Stolution's Material-UI based component library for PWA-first applications

[![npm version](https://img.shields.io/npm/v/@stolution/ui.svg)](https://www.npmjs.com/package/@stolution/ui)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A comprehensive, production-ready UI component library built on Material-UI with Stolution branding and PWA-first responsive design.

## Features

✨ **Stolution Branding** - Cyan Teal primary (#0891B2) and Emerald Green secondary (#10B981) color scheme  
🎨 **Material Design 3** - Modern, accessible components following Google's design system  
📱 **PWA-First** - Mobile-optimized with 44×44px minimum touch targets (WCAG 2.1)  
♿ **Accessible** - WCAG 2.1 AA compliant with comprehensive ARIA support  
🌓 **Dark Mode** - Built-in light/dark theme support  
⚡ **Next.js Ready** - Full SSR/SSG support for SEO optimization  
🎯 **TypeScript** - Full type safety with comprehensive type definitions  
📦 **Tree-Shakable** - Optimized bundle size with ESM support  
🧪 **Well-Tested** - Comprehensive unit tests and Storybook documentation  
🎨 **Custom Variants** - "Soft" button variant with alpha backgrounds  

## Installation

```bash
npm install @stolution/ui
# or
yarn add @stolution/ui
# or
pnpm add @stolution/ui
```

### Peer Dependencies

The library requires these peer dependencies (auto-installed in most cases):

```bash
npm install @mui/material @mui/icons-material @emotion/react @emotion/styled react react-dom
```

## Quick Start

### 1. Wrap your app with `StolutionThemeProvider`

#### Next.js App Router (app/layout.tsx)

```tsx
import { StolutionThemeProvider } from '@stolution/ui';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <StolutionThemeProvider mode="light">
          {children}
        </StolutionThemeProvider>
      </body>
    </html>
  );
}
```

#### Next.js Pages Router (_app.tsx)

```tsx
import { StolutionThemeProvider } from '@stolution/ui';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <StolutionThemeProvider mode="light">
      <Component {...pageProps} />
    </StolutionThemeProvider>
  );
}
```

### 2. Use Components

```tsx
import { Button, Card, CardContent, Typography } from '@stolution/ui';

export default function HomePage() {
  return (
    <Card>
      <CardContent>
        <Typography variant="h4" gutterBottom>
          Welcome to Stolution
        </Typography>
        <Typography variant="body1" color="text.secondary" paragraph>
          Build modern, accessible web applications with our PWA-first component library.
        </Typography>
        <Button variant="contained" color="primary">
          Get Started
        </Button>
        <Button variant="soft" color="secondary" sx={{ ml: 2 }}>
          Learn More
        </Button>
      </CardContent>
    </Card>
  );
}
```

## Core Components

### Inputs
- `Button` - Material button with custom "soft" variant
- `TextField`, `Select`, `Autocomplete` - Form inputs
- `Checkbox`, `Radio`, `Switch` - Selection controls

### Data Display
- `Typography` - Text with consistent styling
- `Avatar`, `Badge`, `Chip` - Visual elements
- `Table`, `List` - Data presentation

### Surfaces
- `Card` - Content containers
- `Paper` - Elevated surfaces

### Layout
- `Box`, `Container`, `Grid`, `Stack` - Layout primitives

### Feedback
- `Alert`, `Dialog`, `Snackbar` - User notifications

### Navigation
- `Drawer`, `Menu`, `Tabs`, `Breadcrumbs` - Navigation components

[See full component list →](https://storybook.stolution.com)

## Custom Features

### "Soft" Button Variant

A unique Stolution variant with colored text on alpha background:

```tsx
<Button variant="soft" color="primary">
  Soft Button
</Button>
```

### Responsive Hooks

```tsx
import { useResponsive } from '@stolution/ui';

function MyComponent() {
  const { isMobile, isTablet, isDesktop, isPortrait } = useResponsive();

  return (
    <div>
      {isMobile && <MobileView />}
      {isTablet && <TabletView />}
      {isDesktop && <DesktopView />}
    </div>
  );
}
```

### Platform Detection (for analytics)

```tsx
import { usePlatform } from '@stolution/ui';

function MyComponent() {
  const { isIOS, isAndroid, isStandalone } = usePlatform();

  // Use for analytics, NOT for changing UI
  useEffect(() => {
    analytics.track('page_view', { 
      platform: isIOS ? 'ios' : isAndroid ? 'android' : 'desktop',
      isPWA: isStandalone 
    });
  }, []);

  return <div>Consistent UI across all platforms</div>;
}
```

## PWA Configuration

### Next.js with next-pwa

```bash
npm install next-pwa
```

```js
// next.config.js
const withPWA = require('next-pwa')({
  dest: 'public',
  register: true,
  skipWaiting: true,
});

module.exports = withPWA({
  reactStrictMode: true,
});
```

### PWA Manifest (public/manifest.json)

```json
{
  "name": "Your Stolution App",
  "short_name": "Stolution",
  "theme_color": "#0891B2",
  "background_color": "#ffffff",
  "display": "standalone",
  "orientation": "portrait-primary",
  "scope": "/",
  "start_url": "/",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}
```

## Theming

### Custom Theme

```tsx
import { createStolutionTheme } from '@stolution/ui';
import { ThemeProvider } from '@mui/material/styles';

const customTheme = createStolutionTheme('light');

// Extend with your own customizations
const myTheme = {
  ...customTheme,
  components: {
    ...customTheme.components,
    MuiButton: {
      styleOverrides: {
        root: {
          borderRadius: 16, // More rounded buttons
        },
      },
    },
  },
};

function App() {
  return (
    <ThemeProvider theme={myTheme}>
      {/* Your app */}
    </ThemeProvider>
  );
}
```

### Dark Mode

```tsx
import { useState } from 'react';
import { StolutionThemeProvider } from '@stolution/ui';

function App() {
  const [mode, setMode] = useState<'light' | 'dark'>('light');

  const toggleMode = () => {
    setMode(mode === 'light' ? 'dark' : 'light');
  };

  return (
    <StolutionThemeProvider mode={mode}>
      <button onClick={toggleMode}>Toggle Theme</button>
      {/* Your app */}
    </StolutionThemeProvider>
  );
}
```

## Design Tokens

### Colors

```tsx
// Primary - Cyan Teal
primary.main: '#0891B2'
primary.light: '#67E8F9'
primary.dark: '#0E7490'

// Secondary - Emerald Green
secondary.main: '#10B981'
secondary.light: '#A7F3D0'
secondary.dark: '#059669'
```

### Typography

```tsx
h1: 2.5rem (40px)
h2: 2rem (32px)
h3: 1.5rem (24px)
body1: 1rem (16px)
body2: 0.875rem (14px)
```

### Spacing

```tsx
theme.spacing(1) = 8px
theme.spacing(2) = 16px
theme.spacing(3) = 24px
```

### Breakpoints

```tsx
xs: 0px      // Mobile portrait
sm: 600px    // Mobile landscape
md: 900px    // Tablet portrait
lg: 1200px   // Desktop
xl: 1536px   // Large desktop
```

## Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+
- Mobile Safari (iOS 14+)
- Chrome Mobile (Android 5+)

## License

MIT © Stolution Team

## Contributing

Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) first.

## Links

- [Documentation](https://stolution.com/docs/ui)
- [Storybook](https://storybook.stolution.com)
- [GitHub](https://github.com/prakashgbid/stolution)
- [NPM](https://www.npmjs.com/package/@stolution/ui)

---

**Made with ❤️ by the Stolution Team**