cocoanut 0.2.3

# Cocoanut TODO

## Completed Versions

### v0.2.0 (COMPLETE)

Rewrote from scratch. Declarative view tree, reactive state, zero warnings.

### v0.3.0 (COMPLETE)

Developer experience improvements, async support, CLI tool, two-way binding.

---

## Code Quality Improvements

### High Priority

- [ ] **Add `#[must_use]` attributes** to `AppBuilder`, `View`, `Style`, `State` to prevent unused result warnings
- [ ] **Improve error handling** - add more `CocoanutError` variants with context:
  - `LayoutError(String)` for Auto Layout failures
  - `DelegateError(String)` for delegate registration failures
  - `InvalidTag(isize)` for invalid view tags
  - `WindowError(String)` for window creation failures
- [ ] **Add safety documentation** for all `unsafe` functions with `# Safety` sections
- [ ] **Use `thiserror::Error` derive** consistently for all error types

### Medium Priority

- [ ] **Add `Default` trait** for `ViewStyle`, `EventBinding`, `ConstraintDescriptor`
- [ ] **Implement `Debug`** for `View`, `EventBinding`, `Binding` (currently missing)
- [ ] **Add `Clone` bound** requirements where appropriate for consistency
- [ ] **Replace `String` with `Arc<str>`** in `ViewKind` variants to reduce allocations
- [ ] **Add `#[non_exhaustive]`** to public enums (`Appearance`, `ViewKind`, etc.)

---

## API Improvements

### Event System

- [ ] **Add more event handlers:**
  - `on_hover(enter: bool)` - mouse enter/leave
  - `on_focus(gained: bool)` - focus tracking
  - `on_key(key: KeyCode, modifiers: Modifiers)` - keyboard events
  - `on_double_click(callback_id)` - double click support
  - `on_right_click(callback_id)` - context menu support
- [ ] **Add typed callbacks** instead of raw `usize` IDs:
  - `OnClick<F>`, `OnChange<F>` wrapper types
  - Return `EventHandler` handle for unregistration

### View Modifiers

- [ ] **Add keyboard shortcuts:**
  - `.shortcut(key: &str, modifiers: Modifiers)` for buttons/menu items
  - `.on_key_shortcut(key, modifiers, callback)`
- [ ] **Add conditional modifiers:**
  - `.visible_if(bool)` - toggle visibility
  - `.enabled_if(bool)` - toggle enabled state
- [ ] **Add layout modifiers:**
  - `.frame(max_width: f64, max_height: f64)` - size constraints
  - `.position(x: f64, y: f64)` - absolute positioning
  - `.z_index(i32)` - Z-ordering for ZStack

### State Management

- [ ] **Add `State::watch`** for derived state that auto-updates
- [ ] **Add `State::computed`** for computed values from multiple states
- [ ] **Add `use_state` macro** for ergonomics: `use_state!(0)`
- [ ] **Add state persistence** helpers (save/load to file)

---

## Type Safety

- [ ] **Strong typing for IDs:**
  ```rust
  pub struct ViewTag(isize);
  pub struct CallbackId(usize);
  pub struct TableId(usize);
  ```
- [ ] **Strong typing for colors:**
  ```rust
  pub struct Color { r: f64, g: f64, b: f64, a: f64 }
  impl Color { pub const RED: Self = ...; }
  ```
- [ ] **Strong typing for dimensions:**
  ```rust
  pub struct Points(f64);
  pub struct Pixels(f64);
  ```

---

## Feature Completeness

### Window Management

- [ ] **Add window lifecycle callbacks:**
  - `on_close(callback)` - window close handler
  - `on_resize(callback)` - resize handler
  - `on_move(callback)` - move handler
  - `on_minimize(callback)` - minimize handler
- [ ] **Add window configuration:**
  - `.resizable(bool)`
  - `.minimizable(bool)`
  - `.closable(bool)`
  - `.fullscreen(bool)`
  - `.always_on_top(bool)`

### TableView Improvements

- [ ] **Wire up `NSTableViewDataSource`** in renderer
- [ ] **Add `TableColumn` builder** with:
  - `.width(f64)` / `.min_width(f64)` / `.max_width(f64)`
  - `.sortable(bool)`
  - `.editable(bool)`
- [ ] **Add row selection callbacks:**
  - `on_select_row(callback)`
  - `on_double_click_row(callback)`
- [ ] **Add reactive table updates** when `State` changes

### New Views

- [ ] **Add `Toolbar`** support (NSToolbar)
- [ ] **Add `StatusItem`** for menu bar apps (NSStatusItem)
- [ ] **Add `Notification`** support (NSUserNotification)
- [ ] **Add `OpenPanel/SavePanel`** file dialogs
- [ ] **Add `Alert`** dialog helper
- [ ] **Add `Popover`** view (NSPopover)

---

## Code Organization

### Refactoring

- [ ] **Split `renderer.rs`** into modules:
  - `renderer/mod.rs` - main render dispatch
  - `renderer/containers.rs` - VStack, HStack, ZStack, etc.
  - `renderer/controls.rs` - Button, Slider, etc.
  - `renderer/text.rs` - Text, TextField, TextArea
  - `renderer/data.rs` - TableView, ProgressBar, etc.
- [ ] **Create `theme.rs`** for styling presets
- [ ] **Create `keyboard.rs`** for key code handling

### Testing

- [ ] **Add property-based tests** with `proptest` for:
  - View tree serialization/deserialization
  - Layout calculations
  - State update propagation
- [ ] **Add integration tests** for renderer mock mode
- [ ] **Add snapshot tests** for `ViewDesc` JSON output

---

## Performance

- [ ] **Add view recycling** for large lists (virtual scrolling)
- [ ] **Batch state updates** to reduce re-renders
- [ ] **Use `SmallVec`** for small collections in hot paths
- [ ] **Add `Cow<str>`** for strings that are usually static

---

## Documentation

- [ ] **Add comprehensive rustdoc** with:
  - Examples for every public function
  - Panic documentation (`# Panics`)
  - Safety documentation (`# Safety`)
  - Error documentation (`# Errors`)
- [ ] **Create user guide** in `docs/`:
  - Getting started
  - Core concepts (Views, State, Events)
  - Common patterns
  - Migration guide
- [ ] **Add architecture diagrams** (ASCII or Mermaid)

---

## Future Versions (from original TODO)

### v0.4.0 — Auto Layout
- [ ] NSLayoutConstraint-based layout (replace frame-based)
- [ ] Intrinsic content size support
- [ ] Layout guides and anchors

### v0.5.0 — TableView Data Source
- [ ] NSTableViewDataSource ObjC delegate for row data
- [ ] Reactive table updates from State changes

### v0.6.0 — Hot Reload
- [ ] File watching with cargo-watch integration
- [ ] Live preview mode