release: Storybook v0.2.0 - Major syntax and features update
BREAKING CHANGES: - Relationship syntax now requires blocks for all participants - Removed self/other perspective blocks from relationships - Replaced 'guard' keyword with 'if' for behavior tree decorators Language Features: - Add tree-sitter grammar with improved if/condition disambiguation - Add comprehensive tutorial and reference documentation - Add SBIR v0.2.0 binary format specification - Add resource linking system for behaviors and schedules - Add year-long schedule patterns (day, season, recurrence) - Add behavior tree enhancements (named nodes, decorators) Documentation: - Complete tutorial series (9 chapters) with baker family examples - Complete reference documentation for all language features - SBIR v0.2.0 specification with binary format details - Added locations and institutions documentation Examples: - Convert all examples to baker family scenario - Add comprehensive working examples Tooling: - Zed extension with LSP integration - Tree-sitter grammar for syntax highlighting - Build scripts and development tools Version Updates: - Main package: 0.1.0 → 0.2.0 - Tree-sitter grammar: 0.1.0 → 0.2.0 - Zed extension: 0.1.0 → 0.2.0 - Storybook editor: 0.1.0 → 0.2.0
This commit is contained in:
387
design/ui-architecture.md
Normal file
387
design/ui-architecture.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# Storybook Editor UI Architecture
|
||||
|
||||
> Structured creative tools for non-technical storytelling
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
**Primary User (Lonni)**: Creative writer who thinks in characters, relationships, and narrative arcs—NOT files and syntax.
|
||||
|
||||
**Secondary User (Sienna)**: Developer who needs access to raw `.sb` files for behavior trees, schemas, and engine integration.
|
||||
|
||||
**Core Principle**: The editor should feel like **writing**, not coding. Structured panes guide creation. The file editor is "manual mode" for power users.
|
||||
|
||||
## Application Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Storybook Editor - examples/alice-in-wonderland/ │
|
||||
├──────────────┬──────────────────────────────────────┬───────────────┤
|
||||
│ │ │ │
|
||||
│ Entity │ Character Editor │ Quick │
|
||||
│ Browser │ │ Actions │
|
||||
│ │ ┌─────────────────────────────────┐ │ │
|
||||
│ Characters │ │ Name: Alice │ │ ✓ Validate │
|
||||
│ ├─ Alice │ │ Age: 7 │ │ ⎇ Versions │
|
||||
│ ├─ Rabbit │ │ Species: Human │ │ ⊕ New Char │
|
||||
│ └─ Queen │ │ │ │ ⊕ New Rel │
|
||||
│ │ │ Traits │ │ ⊕ New Place │
|
||||
│ Relations │ │ curiosity: 0.95 [━━━━━━━━━•─] │ │ │
|
||||
│ ├─ Alice │ │ politeness: 0.75 [━━━━━━━•───] │ │ 🔍 Search... │
|
||||
│ │ ↔ Rabbit │ │ │ │ │
|
||||
│ └─ Queen │ │ Backstory │ │ Git │
|
||||
│ ↔ King │ │ ┌─────────────────────────────┐ │ │ main │
|
||||
│ │ │ │ Alice was beginning to get │ │ │ 3m ago │
|
||||
│ Places │ │ │ very tired of sitting by │ │ │ 12 changes │
|
||||
│ ├─ Rabbit │ │ │ her sister on the bank... │ │ │ │
|
||||
│ │ Hole │ │ │ │ │ └───────────────┘
|
||||
│ └─ Tea │ │ └─────────────────────────────┘ │
|
||||
│ Party │ │ │
|
||||
│ │ │ [Portrait slot: click to add] │
|
||||
│ Schedules │ │ │
|
||||
│ Templates │ │ [Save Character] │
|
||||
│ Behaviors │ └─────────────────────────────────┘
|
||||
│ │ │
|
||||
│ [Manual] │ Tabs: Traits | Backstory | Schedule│
|
||||
│ │ Relationships | Behavior │
|
||||
└──────────────┴──────────────────────────────────────┴───────────────┘
|
||||
```
|
||||
|
||||
## Primary Views (Structured Editing)
|
||||
|
||||
### 1. Character Editor
|
||||
|
||||
**Purpose**: Create and edit characters through forms and rich text, NOT raw `.sb` syntax.
|
||||
|
||||
**Layout**:
|
||||
- **Header**: Name input (large, prominent)
|
||||
- **Metadata Row**: Age, species, template dropdowns
|
||||
- **Traits Section**: Sliders for numeric traits, chips for tags
|
||||
- **Prose Sections**: Tabbed rich text areas for backstory, appearance, personality
|
||||
- **Portrait**: Image upload with preview
|
||||
- **Relationships**: Quick list with "Edit" buttons
|
||||
- **Schedule**: Mini timeline preview with "Edit Full Schedule" button
|
||||
|
||||
**Interaction**:
|
||||
- All changes auto-save to `.sb` file (no explicit save button for small edits)
|
||||
- Git auto-commit on major milestones (e.g., "Update Alice: added backstory")
|
||||
- Validation errors show inline (e.g., red border + tooltip for out-of-range trait)
|
||||
|
||||
**Example**:
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Name: Alice [Portrait]│
|
||||
│ Age: 7 Species: Human Template: Child │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ Traits │
|
||||
│ curiosity 0.95 [━━━━━━━━━━━━━━━•─] │
|
||||
│ politeness 0.75 [━━━━━━━━━━━•─────] │
|
||||
│ fear_of_queen 0.10 [━•──────────────────] │
|
||||
│ │
|
||||
│ Tags: [imaginative] [brave] [+ Add Tag] │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ ⎔ Backstory │ Appearance │ Personality │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ Alice was beginning to get very tired of sitting │
|
||||
│ by her sister on the bank, and of having nothing │
|
||||
│ to do... │
|
||||
│ │
|
||||
│ [Rich text editor with basic formatting] │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. Relationship Editor
|
||||
|
||||
**Purpose**: Visually connect characters and define relationship properties.
|
||||
|
||||
**Layout**:
|
||||
- **Graph View**: Force-directed graph with character nodes
|
||||
- **Edge Selection**: Click edge to edit relationship details
|
||||
- **Properties Panel**: Bond strength, coordination level, bond type
|
||||
- **Asymmetric Fields**: "From Alice's perspective" / "From Rabbit's perspective"
|
||||
|
||||
**Interaction**:
|
||||
- Drag nodes to rearrange
|
||||
- Click edge → properties panel appears
|
||||
- Slider for bond strength (0.0 to 1.0)
|
||||
- Dropdown for bond type (romantic, familial, friendship, etc.)
|
||||
|
||||
**Example**:
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Relationship: Alice ↔ White Rabbit │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Bond Strength: 0.65 [━━━━━━━•──────] │
|
||||
│ Bond Type: friendship │
|
||||
│ Coordination: ad_hoc │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ From Alice's perspective: │
|
||||
│ Respect for punctuality: 0.80 [━━━━━━━━•──] │
|
||||
│ │
|
||||
│ From White Rabbit's perspective: │
|
||||
│ Anxiety about lateness: 0.95 [━━━━━━━━━━━•─] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ [Graph View] │
|
||||
│ │
|
||||
│ Alice ●━━━━━━● White Rabbit │
|
||||
│ │
|
||||
│ Queen ●━━━━━━━━━━● King │
|
||||
│ ╲ ╱ │
|
||||
│ ●━━━━━━━━━━● │
|
||||
│ Guards │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3. Schedule Builder
|
||||
|
||||
**Purpose**: Visual timeline for daily routines (no typing time codes!).
|
||||
|
||||
**Layout**:
|
||||
- **Timeline**: Horizontal 24-hour view with draggable blocks
|
||||
- **Activity Palette**: Drag activities from sidebar onto timeline
|
||||
- **Activity Editor**: Click block to edit parameters
|
||||
|
||||
**Interaction**:
|
||||
- Drag edges to resize time blocks
|
||||
- Drag from palette to add new activity
|
||||
- Snap to 15-minute increments
|
||||
- Validation: overlapping blocks show warning
|
||||
|
||||
**Example**:
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Schedule: Alice's Day │
|
||||
├────┬────────────────────────────────────────────────────────┤
|
||||
│ │ 00:00 06:00 12:00 18:00 24:00 │
|
||||
│ ├───────────────────────────────────────────────────────┤
|
||||
│ Su │ ████Sleep████│Breakfast│Play│Tea│Study│Play│█Sleep██ │
|
||||
│ Mo │ ████Sleep████│Breakfast│School██████│Play│██Sleep███ │
|
||||
│ └───────────────────────────────────────────────────────┘
|
||||
│ │
|
||||
│ Palette: │
|
||||
│ [Sleep] [Eat] [Play] [Study] [Social] [+ Custom] │
|
||||
│ │
|
||||
│ Selected: Tea Party (16:00 → 17:00) │
|
||||
│ Location: Garden │
|
||||
│ Participants: Mad Hatter, March Hare, Dormouse │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4. Behavior Tree Builder (Advanced)
|
||||
|
||||
**Purpose**: Visual node graph for programmable behaviors (Sienna's domain, but approachable for Lonni).
|
||||
|
||||
**Layout**:
|
||||
- **Canvas**: Infinite 2D space for nodes
|
||||
- **Node Palette**: Selector, Sequence, Condition, Action, Decorator
|
||||
- **Inspector**: Selected node's properties
|
||||
|
||||
**Interaction**:
|
||||
- Drag nodes from palette
|
||||
- Connect with edges (parent → children)
|
||||
- Right-click node → context menu (delete, duplicate, etc.)
|
||||
- Validation: orphan nodes, missing actions show errors
|
||||
|
||||
**Example**:
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Behavior: WorkAtBakery │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Palette: [Selector] [Sequence] [?Condition] [→Action] │
|
||||
│ │
|
||||
│ Canvas: │
|
||||
│ │
|
||||
│ ┌─────────────┐ │
|
||||
│ │ Selector │ │
|
||||
│ └──────┬──────┘ │
|
||||
│ ┌────────┼────────┐ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌──────┐ ┌──────┐ ┌──────┐ │
|
||||
│ │ Prep │ │ Bake │ │ Sell │ │
|
||||
│ │ Dough│ │Bread │ │ Bread│ │
|
||||
│ └──────┘ └──────┘ └──────┘ │
|
||||
│ │
|
||||
│ Selected: PrepDough │
|
||||
│ Action: knead_dough │
|
||||
│ Duration: 30 minutes │
|
||||
│ Required Skill: baking > 0.5 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Secondary View (Manual Mode)
|
||||
|
||||
### File Editor
|
||||
|
||||
**Purpose**: Direct `.sb` syntax editing for power users and edge cases.
|
||||
|
||||
**When to Use**:
|
||||
- Behavior trees (until visual editor is built)
|
||||
- Templates with ranges
|
||||
- Advanced features not yet in GUI
|
||||
- Bulk find-replace across characters
|
||||
|
||||
**Layout**:
|
||||
- Syntax-highlighted text editor (Monaspace Neon)
|
||||
- Live validation with inline errors
|
||||
- File tree on left
|
||||
|
||||
**Interaction**:
|
||||
- Standard text editor keybindings
|
||||
- Ctrl+S saves (git auto-commit)
|
||||
- Errors show inline with gold underline
|
||||
- Click error → jump to diagnostic
|
||||
|
||||
## Entity Browser (Left Sidebar)
|
||||
|
||||
**Purpose**: Navigate the storybook's content hierarchy.
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
📂 characters/
|
||||
├─ 👤 Alice
|
||||
├─ 🐰 White Rabbit
|
||||
├─ 👑 Queen of Hearts
|
||||
└─ 👑 King of Hearts
|
||||
|
||||
💑 relationships/
|
||||
├─ Alice ↔ White Rabbit
|
||||
├─ Queen ↔ King
|
||||
└─ Queen → Subjects (all)
|
||||
|
||||
📍 locations/
|
||||
├─ 🕳️ Rabbit Hole
|
||||
├─ 🫖 Tea Party Garden
|
||||
└─ 🏰 Queen's Castle
|
||||
|
||||
📋 templates/
|
||||
├─ WonderlandCreature
|
||||
├─ PlayingCard
|
||||
└─ CourtMember
|
||||
|
||||
🎭 behaviors/
|
||||
├─ WorkAtBakery
|
||||
└─ AttendTeaParty
|
||||
|
||||
📅 schedules/
|
||||
└─ DailyRoutine
|
||||
```
|
||||
|
||||
**Interaction**:
|
||||
- Click entity → load in main panel
|
||||
- Right-click → context menu (delete, duplicate, etc.)
|
||||
- Drag-drop to reorder or move files
|
||||
- Search box filters by name
|
||||
|
||||
## Quick Actions Pane (Right Sidebar)
|
||||
|
||||
**Purpose**: Common tasks and project status at fingertips.
|
||||
|
||||
**Sections**:
|
||||
|
||||
1. **Actions**
|
||||
- ✓ Validate All
|
||||
- ⊕ New Character
|
||||
- ⊕ New Relationship
|
||||
- ⊕ New Location
|
||||
- 🔍 Search Everything
|
||||
|
||||
2. **Git Status**
|
||||
- Current branch: `main`
|
||||
- Last change: `3 minutes ago`
|
||||
- Uncommitted changes: `12 files`
|
||||
- [View History] button → timeline view
|
||||
|
||||
3. **Diagnostics**
|
||||
- ✓ No errors
|
||||
- ⚠ 2 warnings
|
||||
- Click to expand inline
|
||||
|
||||
4. **Project Info**
|
||||
- Characters: 12
|
||||
- Relationships: 7
|
||||
- Locations: 5
|
||||
|
||||
## Responsive Behavior
|
||||
|
||||
### Wide Screen (> 1440px)
|
||||
Three columns: Entity Browser | Main Editor | Quick Actions
|
||||
|
||||
### Standard (1024–1440px)
|
||||
Two columns: Entity Browser | Main Editor
|
||||
Quick Actions → collapsible panel
|
||||
|
||||
### Compact (< 1024px)
|
||||
Single column focus mode
|
||||
Entity Browser → drawer (slides in from left)
|
||||
Quick Actions → toolbar at top
|
||||
|
||||
## Technical Implementation Notes
|
||||
|
||||
### Iced Framework
|
||||
- Use `iced::widget::*` for built-in components
|
||||
- Custom widgets for:
|
||||
- Timeline (schedule builder)
|
||||
- Graph (relationship map)
|
||||
- Node Canvas (behavior tree builder)
|
||||
- Trait Slider (with live value display)
|
||||
|
||||
### File Synchronization
|
||||
- Watch `.sb` files for external changes
|
||||
- Reload editor state on change
|
||||
- Warn if unsaved changes conflict
|
||||
|
||||
### Git Integration
|
||||
- Auto-commit on save with descriptive messages:
|
||||
- "Update Alice: modified backstory"
|
||||
- "Add relationship: Alice ↔ White Rabbit"
|
||||
- "Create character: Cheshire Cat"
|
||||
- Use `git2` crate (no shell commands)
|
||||
- Expose branches as "versions" in UI
|
||||
|
||||
### Theme Application
|
||||
- Load colors from `design/color-palette.md`
|
||||
- Apply 8px grid to all spacing
|
||||
- Use Monaspace Neon for code blocks
|
||||
- Geist for UI text
|
||||
- Gradient background: aubergine (sides) → cream (center) in main editor panel
|
||||
|
||||
## User Workflows
|
||||
|
||||
### Lonni Creates a New Character
|
||||
|
||||
1. Click "⊕ New Character" in Quick Actions
|
||||
2. Fill in name, age, species (dropdowns guided by schema)
|
||||
3. Adjust trait sliders (validation prevents out-of-range)
|
||||
4. Write backstory in rich text area
|
||||
5. Upload portrait image
|
||||
6. Click "Save" → `.sb` file created, git commit happens
|
||||
7. Character appears in Entity Browser
|
||||
|
||||
### Lonni Builds a Relationship
|
||||
|
||||
1. Click "⊕ New Relationship"
|
||||
2. Select two characters from dropdowns
|
||||
3. Drag bond strength slider
|
||||
4. Pick bond type from predefined options
|
||||
5. Fill in asymmetric fields (Alice's view vs. Rabbit's view)
|
||||
6. Save → `.sb` file updated, git commit
|
||||
|
||||
### Sienna Edits a Behavior Tree
|
||||
|
||||
1. Click behavior in Entity Browser
|
||||
2. See visual node graph
|
||||
3. Drag new "Action" node from palette
|
||||
4. Connect to parent Sequence
|
||||
5. Set action parameters in inspector
|
||||
6. Save → `.sb` file updated
|
||||
|
||||
### Both Users Check Validation
|
||||
|
||||
1. Quick Actions shows "⚠ 2 warnings"
|
||||
2. Click to expand → shows inline errors
|
||||
3. Click error → jumps to problematic entity
|
||||
4. Fix in structured editor
|
||||
5. Validation updates live
|
||||
|
||||
---
|
||||
|
||||
*This architecture prioritizes Lonni's creative flow while keeping power-user features accessible for Sienna.*
|
||||
Reference in New Issue
Block a user