npm package: @kahwee/notebook
Description: A modern recipe editor with dual-pane ingredient and steps editing, built with React and TipTap
Author: KahWee Teng
Latest version: 1.1.5

# Recipe Editor

Modern recipe editing application with dual-pane interface, smart ingredient extraction, and real-time mention system. Built with React, TipTap, and TypeScript.

![Recipe Editor Interface](https://via.placeholder.com/800x400/1f2937/white?text=Recipe+Editor+Interface)

## ✨ Features

- **🔄 Dual-Pane Interface** - Resizable ingredient and steps editors
- **🧠 Smart Ingredient Extraction** - Automatic parsing from text (e.g., "2 cups flour" → "flour")
- **💬 Real-time Mentions** - Type `@` to reference ingredients and appliances in steps
- **📱 Responsive Design** - Works on desktop and mobile with focus management
- **🎨 Modern UI** - Clean interface with HeadlessUI components and Tailwind CSS
- **🌙 Dark Mode** - Full dark theme support
- **📚 Component Library** - Documented with Storybook

## 📦 Installation

```bash
npm install @kahwee/notebook
```

### Import Components

```typescript
import { ResizableRecipeForm, IngredientEditor, StepsEditor } from '@kahwee/notebook';

import '@kahwee/notebook/editor.css';
```

### Utility Functions

```typescript
import { parseIngredient, extractIngredientNamesFromText } from '@kahwee/notebook/utils';
import { ingredientsTextToHTML, htmlToIngredientsText } from '@kahwee/notebook/content-utils';
```

## 🚀 Development Setup

```bash
# Clone and install dependencies
npm install

# Start development server
npm run dev

# Open Storybook for component exploration
npm run storybook
```

Visit `http://localhost:5173` for the app or `http://localhost:6006` for Storybook.

## 🛠️ Tech Stack

| Category          | Technology                     |
| ----------------- | ------------------------------ |
| **Framework**     | React 19 + TypeScript (strict) |
| **Build Tool**    | Vite                           |
| **Rich Text**     | TipTap with custom extensions  |
| **Styling**       | Tailwind CSS v4                |
| **UI Components** | HeadlessUI + Heroicons         |
| **Documentation** | Storybook                      |
| **Code Quality**  | ESLint + Prettier              |

## 🎯 Core Components

### ResizableRecipeForm

The main component combining both editors with resizable interface.

```typescript
<ResizableRecipeForm
  initialLeftWidth={40} // percentage
  ref={formRef}
/>

// Access methods
formRef.current?.getIngredientNames() // ['flour', 'sugar', ...]
formRef.current?.getSteps()           // ['Step 1 text', 'Step 2 text', ...]
```

### IngredientEditor

Extracts ingredient names from formatted text using regex patterns.

```typescript
<IngredientEditor
  placeholder="Add ingredients..."
  editable={true}
  ref={ingredientRef}
/>

// Extract ingredients from "2 cups all-purpose flour" → "flour"
ingredientRef.current?.extractIngredientNames()
```

### StepsEditor

Numbered steps with mention system for ingredients and appliances.

```typescript
<StepsEditor
  ingredientNames={['flour', 'sugar', 'butter']}
  editable={true}
  ref={stepsRef}
/>

// Type @ in editor to see mention dropdown
```

## 🔍 Smart Features

### Ingredient Extraction

Intelligently parses ingredients from various formats:

- **Measurements:** "2 cups flour" → "flour"
- **Counts:** "3 large eggs" → "eggs"
- **Complex:** "350g warm water (104°F)" → "warm water"

### Mention System

- **Trigger:** Type `@` anywhere in recipe steps
- **Categories:** Appliances (blue) and ingredients (green)
- **Real-time:** Updates as you add ingredients
- **Visual:** Hover cards with contextual information

### Focus Management

- Click editor headers to activate/focus
- Only one editor editable at a time
- Inactive editor still selectable for copy/paste

## 📊 Sample Recipe

The app comes with a professional Japanese Milk Bread (Shokupan) recipe:

**Ingredients:** 350g warm water, bread flour, instant yeast, honey, butter, etc.
**Steps:** 11 detailed steps from mixing to baking (425°F → 415°F, 25-30 minutes)

Perfect for demonstrating the mention system and ingredient extraction capabilities.

## 🧪 Development

### Available Scripts

```bash
npm run dev          # Development server with HMR
npm run build        # Production build
npm run preview      # Preview production build
npm run typecheck    # TypeScript validation
npm run lint         # ESLint with auto-fix
npm run format       # Prettier formatting
npm run storybook    # Component documentation
```

### Code Quality Standards

- **TypeScript:** Strict mode with no `any` types
- **ESLint:** Extended rules for React and TypeScript
- **Prettier:** Consistent code formatting
- **Git Hooks:** Pre-commit validation (optional)

## 📚 Documentation

- **Storybook:** Interactive component documentation at `/storybook`
- **CLAUDE.md:** Comprehensive development guide and API reference
- **TypeScript:** Full type definitions for all components and props
- **Comments:** JSDoc comments for complex functions and logic

## 🔧 Configuration

| File                 | Purpose                         |
| -------------------- | ------------------------------- |
| `tsconfig.json`      | TypeScript strict configuration |
| `tailwind.config.js` | Tailwind CSS v4 setup           |
| `vite.config.ts`     | Development server and build    |
| `.eslintrc.cjs`      | Code quality rules              |
| `.storybook/main.ts` | Component documentation         |

## 🚀 Deployment

### Build for Production

```bash
npm run build        # Creates optimized build in dist/
npm run preview      # Test production build locally
```

### Storybook Deployment

```bash
npm run build-storybook  # Static documentation site
```

Deploy `dist/` or `storybook-static/` to any static hosting service.

## 🤝 Contributing

1. **Fork** the repository
2. **Branch** from main: `feat/new-feature` or `fix/bug-name`
3. **Code** with TypeScript strict mode
4. **Test** with Storybook and manual testing
5. **Lint** with `npm run lint` and `npm run typecheck`
6. **Submit** pull request with clear description

## 📄 License

MIT License - see LICENSE file for details.

---

**Built with ❤️ using React, TipTap, and TypeScript**