# Grocy2

Modern household management frontend for Grocy. Context-aware, delightful, mobile-first.

## Quick Reference

**Backend:** Grocy server at `http://192.168.0.5:9283`
**Full Spec:** `docs/DESIGN_SPEC.md`

## Tech Stack

- React 18 + TypeScript
- Vite
- TanStack Router
- Zustand (state)
- React Query (data fetching) - TO ADD
- Lucide icons
- CSS custom properties (design tokens)

## Design Principles

1. **Context-Aware** - Dashboard adapts to time of day
2. **Progressive Disclosure** - Simple surface, power underneath
3. **Forgiving** - Everything undoable
4. **Glanceable** - Status in 1s, action in 2s, explore in 3s
5. **Rewarding** - Satisfying feedback on actions
6. **Calm** - Only demands attention when needed

## Dashboard Components

### Pulse Ring
Ambient status indicator (green/amber/red glow). Tap to expand.

### Smart Cards (priority order)
1. **Expiring Soon** - Swipe left=use, right=add to list
2. **Shopping List** - Quick view, "Start Shopping Trip" mode
3. **Low Stock** - Progress bars, "Add All to List"
4. **Recipe Suggestions** - Evening priority, shows what you can make

### Quick Action Bar (bottom)
- **[+] Add** - Bottom sheet with recent items + search
- **[Scan]** - Barcode camera
- **[Voice]** - Speech recognition

## Design Tokens

```css
/* Colors */
--color-primary: #6B8E6B;      /* Sage green */
--color-accent: #E8927C;       /* Soft coral */
--color-urgent: #C75B39;       /* Terracotta */
--color-warning: #E4A853;      /* Amber */
--color-background: #FAFAF8;   /* Warm white */
--color-text-primary: #2D3436; /* Warm charcoal */

/* Spacing: 4, 8, 16, 24, 32, 48 */
/* Radius: 4, 8, 12, 16 */
/* Transitions: 150ms (fast), 250ms (normal), 350ms (slow) */
```

## Breakpoints

- Mobile: < 640px (single column, bottom nav)
- Tablet: 640-1024px (two column, side tabs)
- Desktop: > 1024px (sidebar, three column, keyboard shortcuts)

## Key Interactions

| Gesture | Action |
|---------|--------|
| Pull down | Refresh |
| Swipe left | Use/Delete |
| Swipe right | Add to list |
| Long press | Context menu |

## Folder Structure

```
src/
├── api/           # API client + React Query hooks
├── components/
│   ├── ui/        # Button, Card, Input, etc.
│   ├── dashboard/ # PulseRing, SmartCard, QuickActionBar
│   ├── stock/
│   ├── shopping/
│   └── layout/
├── hooks/         # useVoiceInput, useSwipeGesture
├── lib/           # cardPriority, voiceParser, utils
├── pages/
├── store/
├── styles/        # tokens.css, global.css
└── types/
```

## Implementation Phases

### Phase 1: Foundation
- [x] Project setup
- [ ] Design tokens (CSS custom properties)
- [ ] Base UI components
- [ ] Responsive layout shell
- [ ] Bottom nav (mobile) / Sidebar (desktop)

### Phase 2: Smart Dashboard
- [ ] PulseRing component
- [ ] SmartCard system
- [ ] Card priority algorithm
- [ ] Swipeable rows
- [ ] QuickActionBar

### Phase 3: Quick Actions
- [ ] AddItem bottom sheet
- [ ] Barcode scanning
- [ ] Voice input
- [ ] Optimistic updates

### Phase 4: Full Pages
- [ ] Stock page (filter, search, detail)
- [ ] Shopping mode
- [ ] Recipes page
- [ ] Settings

### Phase 5: Polish
- [ ] PWA setup
- [ ] Offline support
- [ ] Siri Shortcuts docs
- [ ] Performance optimization

## Commands

```bash
npm run dev      # Start dev server
npm run build    # Production build
npm run preview  # Preview production build
```

## Siri Integration (Future)

URL scheme: `grocy://add?item=milk&list=shopping`

Voice intents to parse:
- "Add X to shopping list"
- "Used X" / "Consumed X"
- "Do we have X?"
- "What's expiring?"