npm package: @foodforplanet/petfood-react-ui
Description: React UI component library for FoodForPlanet applications with Atomic Design pattern
Author: Food For Planet
Latest version: 0.3.7

# @foodforplanet/petfood-react-ui

> ⚠️ **Experimental PoC Alert** - This is a proof-of-concept component library that might explode, evolve dramatically, or disappear entirely. Use at your own risk, but hopefully not in production. Yet.

A React component library for **Josera PetFood GmbH** applications, crafted by the FoodForPlanet dev team with an unhealthy obsession for lean solutions, vanilla approaches, and brand consistency.

## The Mission

This experimental library aims to:
- Standardise UI components across our ecosystem
- Evangelise good practices among our partners and cooperators
- Keep things refreshingly simple (we're allergic to bloated frameworks)
- Maintain visual coherence with the Josera PetFood brand
- Probably break a few things along the way (it's called "learning")

## Installation

```bash
npm install @foodforplanet/petfood-react-ui
# or yarn add (if you're into that sort of thing)
# or pnpm add (the cool kids' choice)
```

> **Pro tip**: We won't judge your package manager choice. Much.

## Quick Start

```tsx
import { Button } from '@foodforplanet/petfood-react-ui';
import '@foodforplanet/petfood-react-ui/style.css';

function App() {
  return (
    <Button variant="primary" size="medium">
      Feed the world!
    </Button>
  );
}
```

That's it. No configuration files, no webpack plugins, no sacrificial ceremonies. Just import and go.

## What You Get

- 🎨 **Josera Brand Consistency** - Components that don't look like they were designed by committee
- 🔧 **TypeScript Ready** - Because JavaScript without types is like pet food without nutrition labels
- 📱 **Actually Responsive** - Works on phones, tablets, and those weird in-between sizes
- ♿ **Accessibility First** - Screen readers welcome (we're not monsters)
- 🎭 **Atomic Design** - Organised like Marie Kondo's sock drawer
- 📖 **Storybook Docs** - Interactive playground for the design-curious
- 🎯 **Lean & Mean** - Small bundle, big impact (we measure in kilobytes, not megabytes)
- 🧪 **Battle-Tested** - In production across multiple Josera PetFood applications

## Component Library Structure

Following **Atomic Design** methodology, our components are organised into three main categories:

### Atoms ⚛️
*Basic building blocks - the fundamental HTML elements styled for the Josera brand*

**Interactive Elements**
- ✅ **Button** - Primary interaction element with variants, sizes, and states
- ⏳ **IconButton** - Button with icon integration, icon-only variants *(planned)*
- ⏳ **Checkbox** - Standard checkboxes with custom styling *(planned)*
- ⏳ **Toggle** - Switch/toggle controls for binary states *(planned)*
- ⏳ **RangeSlider** - Value selection with draggable handles *(planned)*

**Form Elements**
- ⏳ **Input** - Text inputs, textareas, and form controls *(planned)*
- ⏳ **Label** - Form labels and text indicators *(planned)*

**Visual Elements**
- ⏳ **Icon** - SVG icon system with consistent sizing and semantics *(planned)*
- ⏳ **Avatar** - User/pet profile images with fallbacks *(planned)*
- ⏳ **Badge** - Status indicators and counters *(planned)*

**Typography** *(BBC GEL responsive type scale with baseline grid)*
- ⏳ **Text** - Responsive text component with GEL size scale (Atlas, Elephant, Imperial, Royal, Foolscap, Canon, Trafalgar, Double Pica, Great Primer, Body Copy, Pica, Long Primer, Brevier, Minion) *(planned)*
- ⏳ **Heading** - Semantic heading component mapping to appropriate GEL sizes *(planned)*
- ⏳ **Caption** - Small descriptive text using Brevier/Minion sizes *(planned)*

**Layout Primitives** *(baseline-aware spacing)*
- ⏳ **Container** - Max-width containers with responsive breakpoints *(planned)*
- ⏳ **Grid** - CSS Grid layout system with baseline alignment *(planned)*
- ⏳ **Stack** - Vertical spacing component maintaining baseline rhythm *(planned)*
- ⏳ **Cluster** - Horizontal grouping with consistent gaps *(planned)*
- ⏳ **Sidebar** - Sidebar layout with flexible content area *(planned)*
- ⏳ **Switcher** - Responsive layout switching component *(planned)*
- ⏳ **Cover** - Full-height centered content layout *(planned)*

### Molecules 🧬  
*Simple groups of UI elements functioning together*

- ⏳ **SearchBox** - Input + button combination *(planned)*
- ⏳ **FormField** - Label + input + validation messaging *(planned)*
- ⏳ **Card** - Content container with optional header/footer *(planned)*
- ⏳ **Pagination** - Page navigation controls *(planned)*
- ⏳ **Breadcrumbs** - Navigation path indicator *(planned)*

### Organisms 🦎
*Complex UI components combining molecules and atoms*

- ⏳ **Header** - Site navigation and branding *(planned)*
- ⏳ **DataTable** - Sortable, filterable data display *(planned)*
- ⏳ **ProductCard** - Pet food product information display *(planned)*
- ⏳ **ContactForm** - Complete contact/inquiry form *(planned)*

## Currently Available

### Button

```tsx
import { Button } from '@foodforplanet/petfood-react-ui';

<Button variant="primary" size="medium">
  Primary Action
</Button>
```

**Props:**
- `variant`: `primary` | `secondary` | `outline` | `danger`
- `size`: `small` | `medium` | `large`  
- `loading`: boolean - shows spinner, disables interaction
- `disabled`: boolean - disables button
- `fullWidth`: boolean - takes full container width
- Plus all standard HTML button attributes

## Styling Philosophy

This library embraces **vanilla CSS with CSS Custom Properties** (CSS variables) over framework overhead like Tailwind or styled-components. We believe in:

- 🎯 **Native CSS** - Leveraging modern CSS features without abstraction layers
- ⚡ **CSS Custom Properties** - Dynamic theming and responsive design tokens
- 📦 **CSS Modules** - Scoped styling without runtime overhead
- 🚀 **Performance First** - Zero-runtime CSS, maximum browser optimization

Import the CSS file to include component styles:

```tsx
import '@foodforplanet/petfood-react-ui/style.css';
```

The components automatically inherit your CSS custom properties for theming:

```css
:root {
  --josera-primary-color: #your-brand-color;
  --josera-font-family: 'Your Brand Font';
}
```

## TypeScript Support

This library is built with TypeScript and includes complete type definitions. No additional `@types` packages needed.

```tsx
import type { ButtonProps } from '@foodforplanet/petfood-react-ui';

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};
```

## Browser Support

- Chrome (last 2 versions)
- Firefox (last 2 versions)
- Safari (last 2 versions)
- Edge (last 2 versions)

## The Fine Print

**Browser Support**: We support the last 2 versions of browsers that people actually use. IE11? No. Edge Legacy? Also no. If your users are still on Windows XP, we need to have a serious conversation.

**Experimental Status**: This is a PoC. Things will change. APIs might evolve. Components might grow extra features or lose unnecessary ones. We'll try not to break your build, but no promises.

## Want to Contribute?

Fancy yourself a component library contributor? Brilliant! Check out our monorepo:

🔗 [PartikelUI Repository](https://bitbucket.org/foodforplanet/partikel-ui)

We accept PRs, bug reports, feature requests, and existential questions about whether a button really needs 47 different variants.

## Who's Behind This?

**Made with caffeine and questionable decisions by the FoodForPlanet Dev Team**

We're the folks who think vanilla solutions are underrated, that simple is better than clever, and that pet food deserves the same engineering standards as rocket ships.

## License

© Josera PetFood GmbH / Food For Planet

> "Because even pets deserve well-crafted user interfaces."

---

*Built for a more sustainable, better-designed pet food future* 🐕 🌱