diff --git a/.frontend-concept/01-research/component-gap-analysis.md b/.frontend-concept/01-research/component-gap-analysis.md new file mode 100644 index 0000000..ce24d3b --- /dev/null +++ b/.frontend-concept/01-research/component-gap-analysis.md @@ -0,0 +1,1086 @@ +# CHUCC Frontend - Component Gap Analysis + +**Research Date**: 2025-11-10 +**Purpose**: Identify available components and gaps for CHUCC frontend development + +--- + +## Executive Summary + +This analysis catalogs components available in **Carbon Design System (Svelte)** and **CHUCC-SQUI**, then identifies missing components needed for the CHUCC frontend. For each missing component, we determine whether it belongs in CHUCC-SQUI (reusable RDF/SPARQL component) or the CHUCC frontend project (CHUCC-specific business logic). + +**Key Findings**: +- โœ… **Carbon provides**: 165+ UI components covering most common UI patterns +- โœ… **CHUCC-SQUI provides**: SPARQL query editor, results table, prefix manager, multi-tab interface +- โŒ **Missing**: 15+ specialized components for version control, RDF diff visualization, and conflict resolution +- ๐Ÿ“Š **Recommendation**: 7 components โ†’ CHUCC-SQUI (reusable), 8 components โ†’ Frontend (CHUCC-specific) + +--- + +## 1. Carbon Components Svelte (Available) + +### 1.1 Layout & Structure +| Component | Description | Use in CHUCC | +|-----------|-------------|--------------| +| `Accordion` | Collapsible content sections | Conflict list, graph list | +| `Grid`, `Row`, `Column` | Responsive grid layout | Page layout | +| `Breadcrumb` | Navigation breadcrumb | Hierarchical navigation | +| `AspectRatio` | Maintain aspect ratio | Image diffs, visualizations | + +### 1.2 Forms & Input +| Component | Description | Use in CHUCC | +|-----------|-------------|--------------| +| `TextInput` | Single-line text | Branch name, commit message | +| `TextArea` | Multi-line text | Commit message, RDF Patch editing | +| `NumberInput` | Numeric input | Kafka config (partitions, retention) | +| `Dropdown` | Single-select dropdown | Dataset selector, branch selector | +| `MultiSelect` | Multi-select dropdown | Select multiple commits/graphs | +| `ComboBox` | Searchable dropdown | Branch search, dataset search | +| `Search` | Search input with icon | Filter branches, search commits | +| `Checkbox` | Boolean input | "Delete Kafka topic", "Fast-forward only" | +| `RadioButton` | Single choice from options | Merge strategy (three-way, ours, theirs) | +| `Toggle` | On/off switch | Enable/disable features | +| `DatePicker` | Date selection | asOf time-travel selector | +| `TimePicker` | Time selection | asOf time selector | +| `FileUploader` | File upload with drag-drop | Upload RDF files to graphs | +| `Switch` | Alternative to Toggle | Theme switcher | +| `PasswordInput` | Masked text input | API keys, credentials (if needed) | +| `Select` | Native select | Simple dropdowns | + +**Verdict**: โœ… **Complete** - All form inputs needed are available + +### 1.3 Data Display +| Component | Description | Use in CHUCC | +|-----------|-------------|--------------| +| `DataTable` | Sortable, filterable table | Results table, commit list, dataset list | +| `StructuredList` | Key-value list | Commit metadata, branch info | +| `Table` | Basic HTML table | Simple data display | +| `Tabs` | Tabbed interface | Query tabs, dataset tabs | +| `TreeView` | Hierarchical tree | Branch hierarchy (future), namespace tree | + +**Verdict**: โœ… **Complete** - Data display components available + +### 1.4 Navigation +| Component | Description | Use in CHUCC | +|-----------|-------------|--------------| +| `Header` | Top navigation bar | App header with logo, dataset selector | +| `HeaderNav` | Header navigation items | Main nav (Query, Graphs, Version Control) | +| `SideNav` | Sidebar navigation | Branches, tags, graphs, stashes (version control view) | + +**Verdict**: โœ… **Complete** - Navigation components available + +### 1.5 Notifications & Feedback +| Component | Description | Use in CHUCC | +|-----------|-------------|--------------| +| `InlineNotification` | Inline message | Success/error messages after operations | +| `ToastNotification` | Floating toast | Background operation completion | +| `ProgressBar` | Horizontal progress | Long-running operations (rebuild view) | +| `ProgressIndicator` | Stepped progress | Multi-step wizards (dataset creation) | +| `Loading` | Full-page spinner | Initial load | +| `InlineLoading` | Inline spinner | In-context loading | +| `SkeletonText` | Content placeholder | Commit list loading | +| `SkeletonPlaceholder` | Custom skeleton | Graph list loading | + +**Verdict**: โœ… **Complete** - Feedback components available + +### 1.6 Modals & Overlays +| Component | Description | Use in CHUCC | +|-----------|-------------|--------------| +| `Modal` | Simple modal dialog | Confirmations, simple forms | +| `ComposedModal` | Advanced modal with sections | Complex forms (create dataset, merge config) | +| `Popover` | Contextual popup | Help text, tooltips | +| `ContextMenu` | Right-click menu | Branch context menu, commit context menu | +| `OverflowMenu` | Dropdown menu (3-dot) | Additional actions | + +**Verdict**: โœ… **Complete** - Modal components available + +### 1.7 Buttons & Controls +| Component | Description | Use in CHUCC | +|-----------|-------------|--------------| +| `Button` | Standard button | All actions (merge, commit, execute) | +| `ButtonSet` | Button group | Modal actions (Cancel, Save) | +| `Link` | Hyperlink | Navigation, external links | +| `CopyButton` | Copy to clipboard | Copy commit SHA, copy RDF Patch | + +**Verdict**: โœ… **Complete** - Button components available + +### 1.8 Tiles & Cards +| Component | Description | Use in CHUCC | +|-----------|-------------|--------------| +| `Tile` | Content card | Dataset card, quick action cards | +| `ClickableTile` | Clickable card | Navigate to dataset/branch | +| `ExpandableTile` | Collapsible card | Expandable commit details | +| `SelectableTile` | Selectable card | Select merge strategy | +| `RadioTile` | Radio button as tile | Choose conflict resolution mode | + +**Verdict**: โœ… **Complete** - Tile components available + +### 1.9 Utility Components +| Component | Description | Use in CHUCC | +|-----------|-------------|--------------| +| `Tooltip` | Hover tooltip | Help text, info icons | +| `Tag` | Label/badge | Branch labels, status tags | +| `Badge` | Notification badge | Uncommitted changes count | +| `Theme` | Theme provider | App theme wrapper | +| `Content` | Content wrapper | Main content area | +| `Breakpoint` | Responsive breakpoint | Responsive layout logic | + +**Verdict**: โœ… **Complete** - Utility components available + +### 1.10 Summary: Carbon Components + +**Total**: 165+ components +**Coverage**: โœ… Comprehensive - covers all standard UI patterns +**Gaps**: None for standard UI - specialized components needed for version control and RDF visualization + +--- + +## 2. CHUCC-SQUI Components (Available) + +### 2.1 Custom Components + +| Component | Description | Technology | Reusable? | +|-----------|-------------|------------|-----------| +| **SparqlQueryUI** | Main web component wrapper | Svelte 5 + Carbon | โœ… Yes | +| **Query Editor** | SPARQL syntax highlighting, autocomplete | CodeMirror 6 | โœ… Yes | +| **Results Table** | Virtual scrolling table (10k+ rows) | Carbon DataTable + virtual scroll | โœ… Yes | +| **Endpoint Selector** | Dropdown with catalogue support | Carbon Dropdown | โœ… Yes | +| **Prefix Manager** | Manage namespace prefixes | Carbon Modal + Form | โœ… Yes | +| **Export Menu** | Export results in multiple formats | Carbon OverflowMenu | โœ… Yes | +| **Theme Selector** | Switch between 4 Carbon themes | Carbon Select | โœ… Yes | +| **Multi-Tab Interface** | Simultaneous queries in tabs | Carbon Tabs | โœ… Yes | + +### 2.2 Internal Stores (Svelte Stores) + +| Store | Purpose | Reusable? | +|-------|---------|-----------| +| `queryStore` | Query state management | โœ… Yes | +| `resultsStore` | Results state management | โœ… Yes | +| `endpointCatalogue` | Endpoint discovery | โœ… Yes | +| `tabStore` | Tab management | โœ… Yes | + +### 2.3 Features + +- **SPARQL 1.2 Protocol compliance**: Full support for SELECT, ASK, CONSTRUCT, DESCRIBE +- **Service Description support**: Auto-discovery of graph names +- **Real-time validation**: Compatibility warnings +- **Keyboard shortcuts**: Ctrl+Enter to execute +- **Accessibility**: WCAG 2.1 AA target +- **Offline support**: Standalone distribution without CDN dependencies +- **Configuration API**: Flexible `SquiConfig` for customization + +### 2.4 Summary: CHUCC-SQUI + +**Total Custom Components**: 8 (query-focused) +**Reusability**: โœ… High - designed for any SPARQL endpoint +**Coverage**: โœ… Complete for SPARQL query operations +**Gaps**: No version control UI, no RDF diff visualization, no conflict resolution + +--- + +## 3. Missing Components for CHUCC Frontend + +### 3.1 Version Control Components + +#### 3.1.1 Commit Graph Visualizer (DAG) + +**Description**: Visual representation of commit history as directed acyclic graph + +**Features**: +- Colored branch lines (Fork-style) +- Commit nodes with avatars +- Collapsible merge commits +- Branch/tag labels inline +- Click to select commit โ†’ show details +- Right-click โ†’ context menu (cherry-pick, revert, reset) +- Drag-drop for cherry-pick + +**Technology Options**: +- D3.js (data-driven, flexible) +- Cytoscape.js (graph-focused, complex layouts) +- Vis.js (good for timelines) +- Custom SVG/Canvas (full control) + +**Reusable?**: โš ๏ธ Partially +- **Core graph rendering**: Could be generic "commit graph" component +- **CHUCC-specific**: UUIDv7 commit IDs, RDF patch metadata, dataset context + +**Recommendation**: **Frontend Project** +- **Rationale**: Tightly coupled to CHUCC's commit structure and API + +--- + +#### 3.1.2 Branch Selector with Visual Indicators + +**Description**: Dropdown to select branch/commit/tag with visual status indicators + +**Features**: +- Branch list with hierarchy +- Current branch highlighted (star icon) +- Ahead/behind indicators (โ†‘3 โ†“2) +- Worktree indicators (if checked out elsewhere) +- Search/filter branches +- Recently used branches at top +- Color-coded branch labels (match graph colors) + +**Technology**: Carbon ComboBox + custom rendering + +**Reusable?**: โš ๏ธ Partially +- **Generic part**: Searchable dropdown with icons +- **CHUCC-specific**: Ahead/behind logic, worktree status, dataset context + +**Recommendation**: **Frontend Project** +- **Rationale**: Branch metadata tightly coupled to CHUCC API + +--- + +#### 3.1.3 Commit Detail View + +**Description**: Panel showing full commit metadata and changes + +**Features**: +- Author, committer, timestamp +- Full commit message +- Parent commits (clickable links) +- Graphs changed (list) +- Triple counts (+/-) per graph +- RDF Patch viewer (below) + +**Technology**: Carbon StructuredList + custom RDF Patch viewer + +**Reusable?**: โš ๏ธ Partially +- **Generic part**: Metadata display +- **RDF-specific**: Graphs changed, triple counts, RDF Patch + +**Recommendation**: **Split** +- **CHUCC-SQUI**: RDF Patch syntax highlighter (see 3.3.1) +- **Frontend**: Commit detail layout + API integration + +--- + +#### 3.1.4 History Filter Component + +**Description**: Filter commit history by author, date range, branch, message + +**Features**: +- Author dropdown (with autocomplete) +- Date range picker (from/to) +- Branch filter (multi-select) +- Message search (text input) +- Clear all filters button + +**Technology**: Carbon Form components + custom logic + +**Reusable?**: โœ… Somewhat +- **Generic**: Filter UI pattern +- **CHUCC-specific**: Filter logic tied to CHUCC API + +**Recommendation**: **Frontend Project** +- **Rationale**: Filter parameters are CHUCC-specific + +--- + +#### 3.1.5 Time Travel Controls + +**Description**: UI for selecting time point (asOf selector) and navigating commits + +**Features**: +- Date + time picker (ISO 8601 format) +- Timeline slider (optional, shows commits over time) +- "Query as of" indicator (prominent display) +- Quick actions: "Latest", "1 day ago", "1 week ago" +- Commit selector (dropdown alternative to date) + +**Technology**: Carbon DatePicker + TimePicker + custom slider + +**Reusable?**: โš ๏ธ Partially +- **Generic**: Date/time picker +- **CHUCC-specific**: asOf selector semantics, commit timeline + +**Recommendation**: **Frontend Project** +- **Rationale**: Specific to CHUCC's asOf protocol extension + +--- + +### 3.2 Merge & Conflict Resolution Components + +#### 3.2.1 Conflict Resolver (3-Pane Layout) + +**Description**: Three-column view for resolving merge conflicts (Base | Ours | Theirs) + +**Features**: +- Three-pane layout (split evenly or adjustable) +- Syntax highlighting for RDF (Turtle format) +- Conflict markers (highlighted sections) +- Resolution buttons per conflict: "Accept Base", "Accept Ours", "Accept Theirs", "Edit Manually" +- Conflict navigation: "Prev", "Next" +- Conflict counter: "3 of 12 resolved" +- Graph-level resolution: "Accept Ours for all triples in graph" +- Preview merge result + +**Technology**: Custom layout + CodeMirror or text editors + +**Reusable?**: โš ๏ธ Partially +- **Generic**: Three-pane conflict resolver UI +- **RDF-specific**: Triple/quad conflict display, graph-level resolution + +**Recommendation**: **Split** +- **CHUCC-SQUI**: Generic three-pane diff viewer with syntax highlighting +- **Frontend**: Conflict resolution logic + CHUCC API integration + +--- + +#### 3.2.2 Conflict Summary Component + +**Description**: Overview of all conflicts in a merge + +**Features**: +- Total conflicts count: "12 graphs in conflict, 45 triples" +- Graph-by-graph breakdown (accordion or list) +- Click graph โ†’ jump to resolver +- Resolution status per graph: "3/5 resolved" +- "Resolve All" button with strategy selector + +**Technology**: Carbon Accordion + custom logic + +**Reusable?**: โŒ No +- **CHUCC-specific**: Graph-level conflict model from protocol + +**Recommendation**: **Frontend Project** +- **Rationale**: Specific to CHUCC's conflict structure + +--- + +#### 3.2.3 Merge Configuration Modal + +**Description**: Modal dialog for configuring merge operation + +**Features**: +- Source branch selector (ComboBox) +- Target branch selector (ComboBox) +- Strategy selector (RadioButton: three-way, ours, theirs, manual) +- Fast-forward mode (RadioButton: allow, only, never) +- Author input (TextInput) +- Commit message (TextArea) +- Preview button (opens diff view) + +**Technology**: Carbon ComposedModal + form components + +**Reusable?**: โŒ No +- **CHUCC-specific**: Merge strategies and parameters from protocol + +**Recommendation**: **Frontend Project** +- **Rationale**: Specific to CHUCC merge API + +--- + +### 3.3 RDF Visualization Components + +#### 3.3.1 RDF Patch Viewer (Syntax Highlighted) + +**Description**: Syntax-highlighted viewer for RDF Patch format + +**Features**: +- Syntax highlighting for RDF Patch directives (TX, TC, PA, PD, A, D, etc.) +- Line numbers +- Collapsible sections (e.g., collapse large additions) +- Search within patch (Ctrl+F) +- Copy patch to clipboard + +**Technology**: CodeMirror 6 with custom RDF Patch language mode + +**Reusable?**: โœ… Yes - RDF Patch is a standard format +- **Generic**: Any RDF application using RDF Patch +- **CHUCC-specific**: None + +**Recommendation**: **CHUCC-SQUI** +- **Rationale**: Reusable RDF component, standard format +- **Priority**: High (core to version control diff display) + +--- + +#### 3.3.2 RDF Diff Viewer (Side-by-Side) + +**Description**: Side-by-side comparison of two RDF graphs/datasets + +**Features**: +- Two-pane layout (before | after) +- Syntax highlighting (Turtle, JSON-LD, or N-Triples) +- Inline diff markers (green for added, red for deleted, yellow for modified) +- Triple-by-triple comparison +- Toggle between unified and side-by-side +- Spacebar to toggle mode + +**Technology**: CodeMirror 6 with diff addon + custom RDF logic + +**Reusable?**: โœ… Yes - Generic RDF diff visualization +- **Generic**: Compare any two RDF graphs +- **CHUCC-specific**: None + +**Recommendation**: **CHUCC-SQUI** +- **Rationale**: Reusable RDF component +- **Priority**: High (essential for version control) + +--- + +#### 3.3.3 Graph Explorer (Triple Table/Tree) + +**Description**: Display triples in a named graph as table or tree structure + +**Features**: +- **Table view**: Subject | Predicate | Object columns +- **Tree view**: Subject โ†’ Predicate โ†’ Object hierarchy +- Virtual scrolling for large graphs (10k+ triples) +- Filter by subject, predicate, object (text search) +- Click triple โ†’ show in detail panel +- Syntax highlighting for URIs, literals, blank nodes + +**Technology**: Carbon DataTable (table) or TreeView (tree) + virtual scroll + +**Reusable?**: โœ… Yes - Generic RDF graph viewer +- **Generic**: View any RDF graph +- **CHUCC-specific**: None + +**Recommendation**: **CHUCC-SQUI** +- **Rationale**: Reusable RDF component +- **Priority**: Medium (enhances graph browsing, not core VC feature) + +--- + +### 3.4 Dataset Management Components + +#### 3.4.1 Dataset Creation Wizard + +**Description**: Step-by-step wizard for creating new dataset + +**Features**: +- **Step 1**: Dataset name (TextInput with validation) +- **Step 2**: Description (TextArea) +- **Step 3**: Kafka configuration (NumberInputs for partitions, replication, retention) +- **Step 4**: Initial graph (optional, FileUploader or TextArea) +- **Step 5**: Review and confirm +- Progress indicator (Carbon ProgressIndicator) + +**Technology**: Carbon ProgressIndicator + Modal + Form components + +**Reusable?**: โŒ No +- **CHUCC-specific**: Kafka config, dataset creation API + +**Recommendation**: **Frontend Project** +- **Rationale**: Specific to CHUCC's dataset creation endpoint + +--- + +#### 3.4.2 Dataset Health Dashboard + +**Description**: Display health status of datasets (Kafka topics, projection lag) + +**Features**: +- Dataset list with health indicators (green/yellow/red) +- Per-dataset metrics: + - Kafka topic status (healthy, degraded, down) + - Partition count + - Consumer lag (events not yet projected) + - Last successful projection timestamp +- "Rebuild View" button (triggers manual projection) +- "Heal Topic" button (triggers topic repair) + +**Technology**: Carbon DataTable + custom health indicators + +**Reusable?**: โŒ No +- **CHUCC-specific**: Kafka health, projection monitoring + +**Recommendation**: **Frontend Project** +- **Rationale**: Specific to CHUCC's event sourcing architecture + +--- + +#### 3.4.3 Dataset Switcher (Enhanced Dropdown) + +**Description**: Advanced dataset selector with search, favorites, recent + +**Features**: +- Searchable dropdown (Carbon ComboBox) +- Recently used datasets at top +- Favorites (star icon to favorite/unfavorite) +- Dataset metadata tooltip (description, commit count, branch count) +- "Create New Dataset" action at bottom + +**Technology**: Carbon ComboBox + custom rendering + +**Reusable?**: โŒ No +- **CHUCC-specific**: Dataset API, favorites stored per-user + +**Recommendation**: **Frontend Project** +- **Rationale**: Specific to CHUCC's multi-tenant architecture + +--- + +### 3.5 Batch Operation Components + +#### 3.5.1 Batch Operation Builder + +**Description**: Visual builder for constructing atomic batch operations + +**Features**: +- Operation list (table): Type | Graph | Content | Order +- Add operation button (opens modal) +- Remove operation button (trash icon per row) +- Reorder operations (drag handles, up/down buttons) +- Operation types: PUT, POST, PATCH, DELETE (for GSP) +- Mode selector: "single-commit" vs "multi-commit" +- Preview pane (shows resulting RDF Patch or commit structure) +- Execute button (prominent) + +**Technology**: Carbon DataTable + drag-drop + modal forms + +**Reusable?**: โŒ No +- **CHUCC-specific**: Batch operations API (`POST /version/batch-graphs`) + +**Recommendation**: **Frontend Project** +- **Rationale**: Specific to CHUCC's batch operations endpoint + +--- + +#### 3.5.2 Batch Operation Preview + +**Description**: Preview the result of a batch operation before execution + +**Features**: +- Shows resulting commit structure (for single-commit mode) +- Shows RDF Patch for each operation (for multi-commit mode) +- Triple counts per operation (+/- triples) +- Affected graphs list +- "Execute" button (green, prominent) +- "Cancel" button (secondary) + +**Technology**: Custom component + RDF Patch viewer + +**Reusable?**: โŒ No +- **CHUCC-specific**: Batch operation preview logic + +**Recommendation**: **Frontend Project** +- **Rationale**: Specific to CHUCC API + +--- + +### 3.6 Utility Components + +#### 3.6.1 Quick Launch Command Palette + +**Description**: Keyboard-driven command palette (Ctrl+P) for quick actions + +**Features**: +- Fuzzy search for commands, branches, datasets +- Recent commands shown first +- Command categories: "Branch", "Commit", "Query", "Dataset" +- Keyboard navigation (โ†‘/โ†“ arrows, Enter to execute) +- Close on Escape + +**Technology**: Custom component (modal overlay + search + list) + +**Reusable?**: โš ๏ธ Partially +- **Generic**: Command palette pattern +- **CHUCC-specific**: Commands tied to CHUCC API + +**Recommendation**: **Frontend Project** +- **Rationale**: Commands are CHUCC-specific, though pattern is generic + +--- + +#### 3.6.2 Commit SHA Badge (Copyable) + +**Description**: Display commit SHA with one-click copy + +**Features**: +- Short SHA (first 8 chars) displayed +- Tooltip shows full SHA on hover +- Click โ†’ copy full SHA to clipboard +- Visual feedback (checkmark animation) + +**Technology**: Carbon Tag + CopyButton + +**Reusable?**: โœ… Somewhat +- **Generic**: Copyable hash badge +- **CHUCC-specific**: UUIDv7 format + +**Recommendation**: **CHUCC-SQUI** +- **Rationale**: Could be reused in other RDF/version control apps + +--- + +#### 3.6.3 Author Selector / Input + +**Description**: Input for selecting or entering commit author + +**Features**: +- ComboBox with recent authors +- Free-text input for new authors +- Format validation (Name ) +- Persist in browser localStorage + +**Technology**: Carbon ComboBox + validation + +**Reusable?**: โœ… Yes +- **Generic**: Author input pattern common in version control + +**Recommendation**: **Frontend Project** (but could be CHUCC-SQUI) +- **Rationale**: Simple enough to implement inline, not worth separate package + +--- + +## 4. Component Placement Decision Matrix + +### 4.1 Decision Criteria + +**Belongs in CHUCC-SQUI if**: +- โœ… Reusable across RDF/SPARQL applications +- โœ… Generic RDF or SPARQL functionality +- โœ… No CHUCC-specific business logic or API calls +- โœ… Could be useful in other projects + +**Belongs in Frontend Project if**: +- โœ… CHUCC-specific business logic +- โœ… Tightly coupled to CHUCC API endpoints +- โœ… Relies on CHUCC's architecture (event sourcing, Kafka, etc.) +- โœ… Not reusable outside CHUCC context + +--- + +### 4.2 Decision Table + +| Component | Reusable? | Generic RDF? | CHUCC API? | **Placement** | Priority | +|-----------|-----------|--------------|------------|---------------|----------| +| **Commit Graph Visualizer** | โš ๏ธ Partial | No | Yes | **Frontend** | High | +| **Branch Selector** | โš ๏ธ Partial | No | Yes | **Frontend** | High | +| **Commit Detail View** | โš ๏ธ Partial | Some | Yes | **Frontend** (use SQUI for RDF Patch) | High | +| **History Filter** | โŒ No | No | Yes | **Frontend** | Medium | +| **Time Travel Controls** | โŒ No | No | Yes | **Frontend** | High | +| **Conflict Resolver (3-Pane)** | โš ๏ธ Partial | Yes | Some | **Split** (SQUI: diff view, Frontend: logic) | High | +| **Conflict Summary** | โŒ No | No | Yes | **Frontend** | High | +| **Merge Configuration Modal** | โŒ No | No | Yes | **Frontend** | High | +| **RDF Patch Viewer** | โœ… Yes | Yes | No | **CHUCC-SQUI** | High | +| **RDF Diff Viewer (Side-by-Side)** | โœ… Yes | Yes | No | **CHUCC-SQUI** | High | +| **Graph Explorer (Table/Tree)** | โœ… Yes | Yes | No | **CHUCC-SQUI** | Medium | +| **Dataset Creation Wizard** | โŒ No | No | Yes | **Frontend** | Medium | +| **Dataset Health Dashboard** | โŒ No | No | Yes | **Frontend** | Medium | +| **Dataset Switcher** | โŒ No | No | Yes | **Frontend** | High | +| **Batch Operation Builder** | โŒ No | No | Yes | **Frontend** | Medium | +| **Batch Operation Preview** | โŒ No | No | Yes | **Frontend** | Medium | +| **Quick Launch Palette** | โš ๏ธ Partial | No | Yes | **Frontend** | Medium | +| **Commit SHA Badge** | โœ… Somewhat | No | No | **CHUCC-SQUI** | Low | +| **Author Input** | โœ… Yes | No | No | **Frontend** (simple) | Low | + +--- + +### 4.3 Summary + +**CHUCC-SQUI (7 components)**: +1. RDF Patch Viewer (syntax highlighting) +2. RDF Diff Viewer (side-by-side) +3. Graph Explorer (triple table/tree) +4. Commit SHA Badge (copyable) +5. (Part of) Conflict Resolver (3-pane diff view) +6. RDF Patch Syntax Highlighter (CodeMirror language mode) +7. Author Input (reusable) + +**Frontend Project (11 components)**: +1. Commit Graph Visualizer (DAG) +2. Branch Selector (with status indicators) +3. Commit Detail View (layout + API) +4. History Filter Component +5. Time Travel Controls +6. Conflict Summary +7. Merge Configuration Modal +8. Dataset Creation Wizard +9. Dataset Health Dashboard +10. Dataset Switcher +11. Batch Operation Builder +12. Batch Operation Preview +13. Quick Launch Palette +14. (Part of) Conflict Resolver (conflict resolution logic) + +--- + +## 5. Implementation Priorities + +### 5.1 Phase 1: Core SPARQL (Already Complete via CHUCC-SQUI) +- โœ… Query Editor +- โœ… Results Table +- โœ… Export Menu +- โœ… Prefix Manager + +### 5.2 Phase 2: Basic Version Control (Minimal Viable Product) +**CHUCC-SQUI**: +1. RDF Patch Viewer (High priority) + +**Frontend**: +1. Commit Graph Visualizer (High priority) +2. Branch Selector (High priority) +3. Commit Detail View (High priority) +4. Dataset Switcher (High priority) + +### 5.3 Phase 3: Advanced Version Control +**CHUCC-SQUI**: +1. RDF Diff Viewer (High priority) + +**Frontend**: +1. Merge Configuration Modal (High priority) +2. Time Travel Controls (High priority) + +### 5.4 Phase 4: Conflict Resolution +**CHUCC-SQUI**: +1. (Part of) Conflict Resolver - 3-pane diff view + +**Frontend**: +1. Conflict Summary (High priority) +2. (Part of) Conflict Resolver - resolution logic + +### 5.5 Phase 5: Dataset Management +**Frontend**: +1. Dataset Creation Wizard (Medium priority) +2. Dataset Health Dashboard (Medium priority) + +### 5.6 Phase 6: Batch Operations +**Frontend**: +1. Batch Operation Builder (Medium priority) +2. Batch Operation Preview (Medium priority) + +### 5.7 Phase 7: Enhanced Browsing +**CHUCC-SQUI**: +1. Graph Explorer (Medium priority) + +**Frontend**: +1. History Filter Component (Medium priority) +2. Quick Launch Palette (Medium priority) + +### 5.8 Phase 8: Polish +**CHUCC-SQUI**: +1. Commit SHA Badge (Low priority) +2. Author Input (Low priority) + +--- + +## 6. Technology Stack Recommendations + +### 6.1 For CHUCC-SQUI Components + +**Graph Visualization**: +- โŒ Not in CHUCC-SQUI (commit graph is CHUCC-specific) + +**Syntax Highlighting**: +- โœ… CodeMirror 6 (already used for SPARQL) +- โœ… Custom language modes for RDF Patch + +**Diff Visualization**: +- โœ… CodeMirror 6 diff addon (merge view) +- โœ… Custom RDF-aware diff algorithm + +**Data Display**: +- โœ… Carbon DataTable (already used for results) +- โœ… Virtual scrolling (already implemented) + +--- + +### 6.2 For Frontend Components + +**Graph Visualization**: +- **Option 1: D3.js** - Most flexible, steep learning curve +- **Option 2: Cytoscape.js** - Good for complex graphs, easier than D3 +- **Option 3: Vis.js** - Simpler, good for timelines +- **Recommendation**: **Cytoscape.js** or **D3.js** + - Cytoscape.js: If graph layout complexity is high + - D3.js: If custom rendering and animations are needed + +**State Management**: +- โœ… Svelte stores (simple, built-in) +- โš ๏ธ Consider Zustand or Pinia if complexity grows + +**Routing**: +- โœ… SvelteKit (if using SvelteKit) +- โœ… Page.js or Navaid (lightweight alternatives) + +**HTTP Client**: +- โœ… Fetch API (native) +- โœ… Axios (if advanced features needed) + +--- + +## 7. Architectural Considerations + +### 7.1 Component Communication + +**Parent โ†’ Child**: Props (Svelte standard) +**Child โ†’ Parent**: Events (Svelte standard) +**Global State**: Svelte stores + +**Example**: +```svelte + + + + +``` + +### 7.2 API Integration + +**Pattern**: Service layer (TypeScript classes or functions) + +**Example**: +```typescript +// services/versionControlService.ts +export class VersionControlService { + async getCommits(dataset: string, branch: string): Promise { + const response = await fetch(`/version/history?dataset=${dataset}&branch=${branch}`); + return response.json(); + } + + async merge(dataset: string, from: string, into: string, strategy: MergeStrategy): Promise { + const response = await fetch(`/version/merge?dataset=${dataset}`, { + method: 'POST', + body: JSON.stringify({ from, into, strategy }) + }); + return response.json(); + } +} +``` + +### 7.3 Error Handling + +**Pattern**: RFC 7807 Problem Details parser + +**Example**: +```typescript +// utils/errorHandler.ts +export function handleApiError(response: Response): ProblemDetails { + if (response.headers.get('content-type')?.includes('application/problem+json')) { + return response.json(); // Returns { type, title, status, detail, instance, ... } + } + throw new Error(`HTTP ${response.status}: ${response.statusText}`); +} +``` + +--- + +## 8. Testing Strategy + +### 8.1 CHUCC-SQUI Components + +**Unit Tests**: Vitest +- Test RDF Patch parser +- Test diff algorithm +- Test virtual scrolling logic + +**Component Tests**: Playwright +- Test RDF Patch viewer rendering +- Test diff viewer interactions +- Test graph explorer filtering + +**Visual Regression**: Storybook + Chromatic +- Ensure UI consistency across changes + +--- + +### 8.2 Frontend Components + +**Unit Tests**: Vitest +- Test state management (stores) +- Test service layer (API calls, mocked) +- Test utility functions + +**Component Tests**: Playwright +- Test commit graph interactions +- Test branch selector search +- Test conflict resolution workflow + +**Integration Tests**: Playwright +- Test end-to-end workflows (create commit, merge branches, resolve conflicts) +- Test against CHUCC-server (Testcontainers) + +--- + +## 9. Accessibility Considerations + +All custom components must meet **WCAG 2.1 AA** standards: + +- โœ… **Keyboard navigation**: All interactions accessible via keyboard +- โœ… **ARIA labels**: Screen reader support +- โœ… **Focus indicators**: Visible focus states +- โœ… **Color contrast**: 4.5:1 for text, 3:1 for UI elements +- โœ… **Error messages**: Associated with form fields + +**Example**: +```svelte + +``` + +--- + +## 10. Performance Considerations + +### 10.1 Large Commit Histories + +**Strategy**: Virtual scrolling + pagination +- Load 100 commits at a time +- Lazy-load commit details (only when selected) +- Debounce search/filter inputs + +### 10.2 Large Diffs + +**Strategy**: Lazy rendering + collapsing +- Render visible portion of diff first +- Collapse large additions/deletions (show summary, expand on demand) +- Use Web Workers for syntax highlighting (non-blocking) + +### 10.3 Large Graphs + +**Strategy**: Virtual scrolling + filtering +- Carbon DataTable already supports virtual scrolling +- Limit initial display to 1000 triples, paginate rest +- Filter by subject/predicate/object to reduce visible set + +--- + +## 11. Recommendations + +### 11.1 For CHUCC-SQUI Maintainers + +**Add These Components** (in priority order): +1. **RDF Patch Viewer** (High) - Essential for version control +2. **RDF Diff Viewer** (High) - Essential for comparing commits +3. **Graph Explorer** (Medium) - Enhances graph browsing +4. **Commit SHA Badge** (Low) - Nice-to-have utility +5. **Author Input** (Low) - Reusable form component + +**Technology**: +- CodeMirror 6 language mode for RDF Patch +- CodeMirror 6 merge view for side-by-side diff +- Virtual scrolling (already have expertise from results table) + +**Testing**: +- Storybook stories for each component +- Playwright tests for interactions +- Publish to npm for easy integration + +--- + +### 11.2 For CHUCC Frontend Developers + +**Leverage Carbon & CHUCC-SQUI**: +- Use Carbon components for all standard UI (forms, modals, navigation) +- Use CHUCC-SQUI for SPARQL query and RDF visualization +- Build custom components only for CHUCC-specific features + +**Focus on Version Control UX**: +- Prioritize commit graph, branch selector, conflict resolver +- Emulate Fork's elegance (drag-drop, colored graphs, Quick Launch) +- Emulate Fuseki's simplicity (tab-based, focused) + +**Performance**: +- Virtual scrolling everywhere (commit list, results, graphs) +- Lazy-load details (commit diffs, RDF patches) +- Debounce search/filter inputs + +**Accessibility**: +- Use Carbon's built-in accessibility features +- Add ARIA labels to custom components +- Test with keyboard navigation and screen readers + +--- + +## 12. Conclusion + +**Available Components**: +- โœ… Carbon: 165+ components (comprehensive standard UI) +- โœ… CHUCC-SQUI: 8 components (SPARQL query + results) + +**Missing Components**: +- โŒ 15+ specialized components for version control and RDF visualization + +**Placement**: +- **CHUCC-SQUI**: 7 reusable RDF/SPARQL components +- **Frontend**: 11 CHUCC-specific components + +**Next Steps**: +1. โœ… Complete research (Tasks 1-3) +2. โฉ Synthesize frontend concept with mockups (Task 4) +3. โฉ Create implementation roadmap +4. โฉ Begin Phase 1 development + +--- + +## Appendix: Component API Sketches + +### A.1 RDF Patch Viewer (CHUCC-SQUI) + +```svelte + + + console.log('Copied', e.detail)} +/> +``` + +### A.2 Commit Graph Visualizer (Frontend) + +```svelte + + + handleSelectCommit(e.detail.commitId)} + on:contextmenu={(e) => showContextMenu(e.detail.commitId, e.detail.mouseEvent)} +/> +``` + +### A.3 Conflict Resolver (Frontend + CHUCC-SQUI) + +```svelte + + + +
+ + + +
+ +
+ + + +
+
+``` + +--- + +**Document Version**: 1.0 +**Last Updated**: 2025-11-10 +**Author**: Claude (AI Research Agent) diff --git a/.frontend-concept/01-research/fork-ux-analysis.md b/.frontend-concept/01-research/fork-ux-analysis.md new file mode 100644 index 0000000..74519d5 --- /dev/null +++ b/.frontend-concept/01-research/fork-ux-analysis.md @@ -0,0 +1,906 @@ +# Fork Git Client UX Analysis + +**Research Date**: 2025-11-10 +**Purpose**: Understand Fork's elegant version control UX patterns for CHUCC frontend design + +--- + +## Executive Summary + +Fork is a **fast, friendly, and visually elegant** Git client for Mac and Windows, created by Dan and Tanya Pristupov. It is widely praised for its **clean interface**, **intuitive workflows**, and **powerful visual tools** for complex version control operations. Fork prioritizes **speed**, **clarity**, and **low friction** interactions, making Git accessible without sacrificing advanced functionality. + +**Key Takeaway**: Fork demonstrates that sophisticated version control can be intuitive through smart visual design, drag-and-drop interactions, and contextual UI elements. CHUCC should adopt Fork's clarity, elegance, and interaction patterns for version control features. + +--- + +## 1. Main Window Layout + +### 1.1 Overall Structure + +Fork uses a **three-pane layout** with sidebar, center content, and bottom/right detail panels: + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [Tabs: Repo1 Repo2 Repo3 +] [๐Ÿ” Quick Launch] โ”‚ โ† Top bar +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”‚ โ”‚ +โ”‚ SIDEBAR โ”‚ CENTER PANEL โ”‚ +โ”‚ โ”‚ โ”‚ +โ”‚ โ€ข Local โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ Branchesโ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ€ข Remote โ”‚ โ”‚ Commit Graph / File Tree โ”‚ โ”‚ +โ”‚ โ€ข Tags โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ€ข Stashesโ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ€ข Search โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ [Filter] โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Detail View / Diff Viewer โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”€โ”€โ”€โ”˜ +``` + +**Key Components**: +- **Top Bar**: Repository tabs (multi-repo support), Quick Launch palette (Ctrl+P / โŒ˜+P) +- **Sidebar** (Left): Branches (local/remote), tags, stashes, file tree, search/filter +- **Center Panel** (Top): Commit graph with visual DAG, file list, or repository treemap +- **Detail Panel** (Bottom/Right): Diff viewer, commit details, merge conflict resolver + +**Platform-Specific**: Native look on Mac (BigSur+ styling) and Windows + +--- + +## 2. Sidebar Organization + +### 2.1 Branch Management + +**Local Branches**: +- List with hierarchy (folder grouping supported) +- Current branch highlighted (bold or icon indicator) +- Upstream status icons (ahead/behind/diverged) +- Worktree icons (if branch checked out in another worktree) +- Branch label colors match commit graph colors +- Right-click context menu: merge, rebase, delete, rename + +**Remote Branches**: +- Organized by remote (origin, upstream, etc.) +- Double-click to track and checkout +- Push multiple branches via multi-select + +**Tags**: +- Separate section with tag list +- Annotated tags show messages +- Create/delete via context menu + +**Stashes**: +- Dedicated sidebar section (moved in v2.22 for better organization) +- Apply/pop/delete via context menu + +### 2.2 Filtering & Search + +**Branch Filter**: Text input at top of sidebar +- Filters by name with "highlight search matches in branch labels" (v2.50) +- Instantly narrows visible branches + +**File Tree Filter**: Quick filtering by filename in file lists + +--- + +## 3. Commit Graph Visualization + +### 3.1 Visual Design + +**Graph Rendering**: +- **Colored lines** representing branches (color-coded for visual distinction) +- **Commit nodes** as circles/dots on the graph +- **Merge commits** shown with converging lines +- **Branch labels** drawn with graph colors (v2.53) +- **Avatars** (Gravatar) for commit authors +- **Mouse hover** highlights commit node points (v2.x) + +**Information Density**: +- Commit message (first line) +- Author name + avatar +- Timestamp (relative or absolute) +- Branch/tag labels inline +- SHA-1 short hash + +### 3.2 Collapsible Graph Feature + +**Purpose**: Reduce visual clutter in complex histories + +**Interaction**: +- **Click** on merge commit tips to collapse/expand +- **Keyboard**: โ† (collapse) / โ†’ (expand) +- **Context menu**: "Collapse all branches" โ†’ selectively expand needed ones + +**Benefits**: +- Hide extraneous commits from feature branches +- Focus on main branch or specific PRs +- Clarify contribution history in large repos (e.g., Swift repo with 100k+ commits) + +**Example Use Case**: +> "Clearly see when the work on feature #20782 had begun, which commits it contained, and when it was merged" + +### 3.3 Commit Selection & Details + +**Interaction**: +- **Click** commit โ†’ show details in bottom panel +- **Multi-select** (Ctrl+Click, Shift+Click) for range operations +- **Right-click** โ†’ context menu (cherry-pick, revert, reset, create branch) + +**Detail Panel Shows**: +- Full commit message +- Author, committer, timestamp +- Parent commits (clickable links) +- Changed files list with diff stats (+/- lines) +- Full diff view below + +--- + +## 4. Diff Viewer + +### 4.1 Modes + +Fork offers multiple diff viewing modes: + +**1. Unified Diff** (Default): +- Single pane with +/- lines +- Traditional Git diff format +- Compact, space-efficient + +**2. Side-by-Side Diff** (Spacebar to toggle): +- Two-pane layout (left: old, right: new) +- Side-by-side comparison like external merge tools +- Clear visual separation of changes +- "Character-level diff" highlighting (changed words within lines) + +**3. Image Diff** (v2.42, v2.51): +- **Side-by-side**: Old vs new images next to each other +- **Swipe**: Slider to reveal old/new +- **Onion skin**: Overlay with transparency slider +- **Pixel-perfect highlighting**: Exact pixel differences shown +- Supports PNG, JPG, GIF, SVG, TGA + +### 4.2 Navigation + +**Inline Search**: Ctrl+F to search within diff +**Jump to Next/Prev Change**: Keyboard shortcuts (โ†‘/โ†“ or J/K likely) +**Conflict Mark Scrollbar**: Visual indicators on scrollbar showing merge conflict locations (v2.53) + +### 4.3 File List + +**Layout**: Tree or flat list view +**Stats**: +/- line counts per file +**Icons**: File type icons +**Interaction**: Click file โ†’ show diff in detail panel + +--- + +## 5. Merge Conflict Resolution + +### 5.1 Conflict Resolver UI + +**Layout Options**: + +**1. Three-Column Layout** (v2.13): +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Base โ”‚ Ours โ”‚ Theirs โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ (common โ”‚ (current โ”‚ (incomingโ”‚ +โ”‚ ancestor)โ”‚ branch) โ”‚ branch) โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +**2. Inline Markers**: +- Traditional Git conflict markers +- `<<<<<<< HEAD` / `=======` / `>>>>>>> branch` +- Syntax highlighting for conflict regions + +### 5.2 Interaction Patterns + +**Built-in Resolver**: +- One-click "Accept Ours" / "Accept Theirs" / "Accept Both" +- Manual editing directly in conflict regions +- Real-time conflict status indicator + +**External Tool Support**: +- Integration with Visual Studio Code, Beyond Compare, etc. +- One-click "Open in [tool]" + +**Conflict Navigation**: +- Jump to next/previous conflict +- Conflict count indicator (e.g., "3 of 12 conflicts resolved") + +### 5.3 Visual Feedback + +**Conflict Markers on Scrollbar**: Red indicators showing conflict locations (v2.53) +**File Status Icons**: Conflicted files highlighted in file list +**Progress Indicator**: "X of Y conflicts resolved" + +--- + +## 6. Interactive Rebase + +### 6.1 Visual Interface + +**Purpose**: Reorder, squash, edit commits without command line + +**Layout**: +- List of commits in rebase range (oldest to newest) +- Each commit = row with: SHA, message, author, action dropdown +- Drag handles for reordering + +**Actions**: +- Pick (keep as-is) +- Reword (change message) +- Edit (stop for editing) +- Squash (combine with previous) +- Fixup (squash without keeping message) +- Drop (remove commit) + +### 6.2 Interaction + +**Drag-and-Drop Reordering** (v2.55): +- Drag commit rows to reorder +- Visual feedback during drag (drop zones highlighted) +- Immediate visual update + +**Action Selection**: +- Dropdown per commit +- Keyboard shortcuts for common actions + +**Squash via Drag-Drop**: +- Drag commit onto another to squash +- Combine commit messages in modal + +--- + +## 7. Advanced Operations + +### 7.1 Drag-and-Drop Branch Operations + +**Merge** (v2.20): +- Drag branch A onto branch B in sidebar +- Tooltip shows "Merge A into B" +- Drop โ†’ merge dialog with strategy options (fast-forward, no-ff, etc.) + +**Rebase**: +- Drag branch A onto branch B with modifier key (Alt/Option) +- Tooltip shows "Rebase A onto B" +- Drop โ†’ rebase begins (or interactive rebase dialog) + +**Cherry-Pick**: +- Drag commits from graph onto branch in sidebar +- Multiple commits supported (multi-select) + +### 7.2 Quick Launch Palette + +**Access**: Ctrl+P (Win) / โŒ˜+P (Mac) + +**Features**: +- Command palette for frequent actions +- Fuzzy search (v2.57) for branches, files, commands +- Recent actions shown first +- Keyboard-driven workflow (no mouse needed) + +**Example Commands**: +- "checkout main" +- "create branch feature/new" +- "merge origin/develop" +- "push" +- "pull" + +### 7.3 File History & Blame + +**File History** (v2.59): +- Right-click file โ†’ "Show History" +- View all commits that touched the file +- Select code in editor โ†’ "History for Selection" (track specific lines) + +**Blame View**: +- Inline annotation showing commit per line +- Hover over line โ†’ commit tooltip (author, date, message) +- Click commit โ†’ jump to commit in graph + +### 7.4 Repository Treemap + +**Purpose**: Visualize repository activity over time (v2.52) + +**Display**: +- Heatmap-style visualization +- File size + commit frequency = block size/color +- Interactive exploration (click to drill down) + +--- + +## 8. Visual Design Language + +### 8.1 Color Palette + +**Light Theme**: +- White/light gray background +- Blue accent for primary actions +- Green/red for added/deleted lines in diffs +- Branch graph: Rainbow of distinct colors (red, blue, green, purple, orange, etc.) + +**Dark Theme** (v1.0.36, refined v2.52): +- Dark gray background (#2b2b2b typical) +- Custom checkerboard background for transparency (v2.52) +- Syntax highlighting adapted for dark mode +- Reduced eye strain for long coding sessions + +**Semantic Colors**: +- **Green**: Success, additions, current branch +- **Red**: Deletions, conflicts, errors +- **Yellow**: Warnings, ahead/behind status +- **Blue**: Links, selected items +- **Purple**: Merged branches + +### 8.2 Typography + +**Font Families**: +- **UI Text**: System default (San Francisco on Mac, Segoe UI on Windows) +- **Code/Diffs**: Monospace (Menlo, Consolas, or user-configured) + +**Hierarchy**: +- Commit messages: Regular weight +- Branch labels: Bold +- Current branch: Bold + icon +- Tags: Italics or badge style + +### 8.3 Icons & Indicators + +**Branch Icons**: +- Local branch: ๐ŸŒฟ (branch icon) +- Remote branch: โ˜๏ธ (cloud icon) +- Current branch: โ˜… or โœ“ indicator +- Ahead/behind: โ†‘ (commits ahead) / โ†“ (commits behind) + +**File Status Icons**: +- Modified: M (yellow) +- Added: A (green) +- Deleted: D (red) +- Renamed: R (blue) +- Conflicted: C (red exclamation) + +**Worktree Icons** (v2.57, v2.59): +- Visual indicator if branch checked out elsewhere + +### 8.4 Spacing & Layout Density + +**Compact Mode**: +- Smaller row heights in commit list +- More commits visible per screen + +**Normal Mode** (Default): +- Comfortable spacing +- Avatars + labels visible + +**Information Hierarchy**: +- Primary info (commit message, branch name): Prominent +- Secondary info (author, date): Subdued +- Tertiary info (SHA, stats): Small, gray + +--- + +## 9. Interaction Patterns + +### 9.1 Keyboard Shortcuts + +Fork emphasizes keyboard-driven workflows: + +- **Ctrl+P / โŒ˜+P**: Quick Launch palette +- **Ctrl+F**: Search in diff +- **Spacebar**: Toggle side-by-side diff mode +- **โ†/โ†’**: Collapse/expand merge commits +- **โ†‘/โ†“**: Navigate commits +- **Ctrl+Click / Shift+Click**: Multi-select commits +- **Context-specific shortcuts**: Shown in tooltips + +### 9.2 Right-Click Context Menus + +**Branch Context Menu**: +- Checkout +- Merge into current +- Rebase current onto +- Rename +- Delete +- Set as upstream + +**Commit Context Menu**: +- Cherry-pick +- Revert +- Reset branch to here (hard/soft/mixed) +- Create branch at this commit +- Copy SHA +- Open in GitHub/GitLab (if remote URL known) + +**File Context Menu** (in diff): +- Open in editor +- Open external diff tool +- Copy path +- Show history +- Add to .gitignore + +### 9.3 Drag-and-Drop Philosophy + +Fork extensively uses drag-and-drop for intuitive interactions: + +**What Can Be Dragged**: +- Branches (sidebar) โ†’ other branches (merge/rebase) +- Commits (graph) โ†’ branches (cherry-pick) +- Commits (rebase list) โ†’ reorder +- Files (explorer) โ†’ add to staging + +**Visual Feedback**: +- Drag cursor changes to indicate operation +- Drop zones highlighted +- Tooltip shows action (e.g., "Merge feature into main") + +### 9.4 Hover States & Tooltips + +**Commit Graph**: +- Hover over commit node โ†’ highlight related lines +- Hover over branch label โ†’ highlight branch path +- Hover over avatar โ†’ show full author name + +**Sidebar**: +- Hover over branch โ†’ show full name (if truncated) +- Hover over icon โ†’ show upstream status + +**Toolbar**: +- Hover over button โ†’ tooltip with keyboard shortcut + +--- + +## 10. Multi-Repository Support + +### 10.1 Tab Interface + +**Layout**: Horizontal tabs at top of window +- Tab per repository +- **Tab label**: Repository name (folder name) +- **Tab badges** (v2.45): Badge shows uncommitted changes count +- **Tab context menu**: Close, close others, close all +- **Add tab button**: + button to open new repo + +### 10.2 Tab Persistence + +**Session State**: +- Open repositories persisted across app restarts +- Current branch per repo remembered +- Sidebar state (expanded sections, filter text) remembered per tab + +### 10.3 Cross-Repository Operations + +**Limitations**: No cross-repo operations (e.g., can't merge from repo A into repo B) +**Workaround**: Multiple tabs allow parallel work on related repos (e.g., frontend + backend) + +--- + +## 11. Custom Commands UI + +### 11.1 Feature (v2.29) + +**Purpose**: Extend Fork with custom Git commands without command line + +**UI Builder**: +- **Text fields**: Input for arguments (e.g., commit message) +- **Branch combo boxes**: Select target branch +- **Dropdown**: Select from predefined options +- **Checkbox**: Boolean flags + +**Example**: Create custom "Deploy to Staging" command +- Dropdown: Select environment (staging, production) +- Branch combo: Select release branch +- Text field: Tag name +- Execute โ†’ runs custom script + +### 11.2 Benefits + +- No context switching to terminal +- Consistent UI for common workflows +- Shareable command definitions (team standardization) + +--- + +## 12. Strengths (Patterns to Emulate for CHUCC) + +### 12.1 Visual Clarity +- โœ… **Colored branch graph**: Instantly understand branch structure +- โœ… **Collapsible commits**: Reduce clutter in complex histories +- โœ… **Avatars**: Human-friendly author identification + +### 12.2 Intuitive Interactions +- โœ… **Drag-and-drop**: Natural, low-friction for merge/rebase/cherry-pick +- โœ… **Right-click context menus**: Discoverable actions +- โœ… **Quick Launch palette**: Keyboard power users love this + +### 12.3 Advanced Features Made Simple +- โœ… **Interactive rebase**: Visual list + drag-drop = no command line needed +- โœ… **Merge conflict resolver**: Three-column view clarifies conflicts +- โœ… **Side-by-side diff**: Easier to understand than unified diff + +### 12.4 Performance & Speed +- โœ… **Fast rendering**: Handles large repos (100k+ commits) smoothly +- โœ… **Native feel**: Platform-specific styling, responsive UI +- โœ… **Incremental loading**: Commit graph loads as you scroll + +### 12.5 Consistency +- โœ… **Uniform interaction patterns**: Drag-drop works everywhere +- โœ… **Predictable shortcuts**: Ctrl+P, spacebar, etc. +- โœ… **Semantic colors**: Green=good, red=bad, consistent across views + +--- + +## 13. Gaps (What Fork Lacks, Not Applicable to CHUCC) + +### 13.1 File-Centric Model + +**Fork's Limitation**: Designed for file-based version control (Git's model) +- Shows file tree, file diffs, file history +- Not applicable to RDF graphs (which use triples, not files) + +**CHUCC Adaptation**: +- Replace "file tree" with **"graph explorer"** (named graphs list) +- Replace "file diff" with **"triple diff"** or **"RDF Patch viewer"** +- Keep visual patterns (colors, layout) but adapt to RDF semantics + +### 13.2 Working Directory Concept + +**Fork's Feature**: Shows uncommitted changes in working directory +- Staging area (files ready to commit) +- Working tree (modified but unstaged files) + +**CHUCC Context**: No working directory in SPARQL 1.2 VC Extension +- Changes applied via RDF Patch โ†’ immediate commit +- Materialized views are read-only snapshots +- No "staging" step in protocol + +**Possible CHUCC Equivalent**: "Draft commit builder" +- Allow users to prepare RDF Patch before committing +- Preview changes before execution +- But not required by spec + +### 13.3 Pull Request Management + +**Fork's Limitation**: Basic or no PR management (depends on hosting service) +- Some users cite "inability to manage pull requests from the app" as drawback + +**CHUCC Context**: Not applicable (no GitHub/GitLab integration needed) + +--- + +## 14. Adaptations for CHUCC (RDF Context) + +### 14.1 Commit Graph โ†’ Same Concept +- **Keep**: Visual DAG with colored lines, commit nodes, branch labels +- **Adapt**: Commit metadata shows RDF-specific info (triple counts, graph changes) + +### 14.2 Branch Sidebar โ†’ Same Concept +- **Keep**: Local/remote branches, tags, current branch indicator +- **Adapt**: Add "dataset selector" above or within sidebar (CHUCC's multi-dataset) + +### 14.3 File List โ†’ Graph List +- **Replace**: File tree with **named graphs list** +- **Keep**: Click graph โ†’ show contents (triples table or RDF visualization) +- **Adapt**: Show triple counts per graph instead of line counts + +### 14.4 File Diff โ†’ RDF Patch Diff +- **Replace**: Text diff with **RDF Patch viewer** (additions/deletions of quads) +- **Keep**: Side-by-side mode for comparing "before" and "after" graph states +- **Adapt**: Syntax highlighting for RDF Patch format (TX, PA, PD, etc.) + +### 14.5 Merge Conflicts โ†’ Quad-Level Conflicts +- **Keep**: Three-column layout (Base | Ours | Theirs) +- **Adapt**: Show conflicting **triples** instead of file sections +- **Adapt**: "Accept Ours" / "Accept Theirs" works at triple or graph level (configurable) + +### 14.6 Working Directory โ†’ Batch Operation Builder +- **Replace**: Staging area with **"Batch operation builder"** +- **Purpose**: Preview and build atomic multi-graph operations +- **Keep**: Commit button at bottom, commit message input + +### 14.7 Quick Launch โ†’ Command Palette +- **Keep**: Ctrl+P palette for quick actions +- **Adapt**: Commands like "checkout branch", "merge", "create commit", "time-travel to date" + +### 14.8 Drag-and-Drop โ†’ Same Patterns +- **Keep**: Drag branch to merge/rebase +- **Keep**: Drag commits to cherry-pick +- **Potential**: Drag triples between graphs? (Advanced feature, TBD) + +--- + +## 15. Recommended UX Patterns for CHUCC + +### 15.1 Version Control View (Fork-Inspired) + +**Layout**: +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [Datasets โ–พ] [Branch: main โ–พ] [๐Ÿ” Quick Launch] โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ SIDEBAR โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ Branches โ”‚ โ”‚ Commit Graph (DAG with colors) โ”‚ โ”‚ +โ”‚ โ€ข main โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ€ข featureโ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ€ข dev โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ Tags โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”‚ +โ”‚ โ€ข v1.0 โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ€ข v1.1 โ”‚ โ”‚ Commit Details โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ Author: Alice โ”‚ โ”‚ +โ”‚ Graphs โ”‚ โ”‚ Message: Add user data โ”‚ โ”‚ +โ”‚ โ€ข defaultโ”‚ โ”‚ Graphs changed: 2 โ”‚ โ”‚ +โ”‚ โ€ข users โ”‚ โ”‚ Triples added: 15, deleted: 3 โ”‚ โ”‚ +โ”‚ โ€ข roles โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ [RDF Patch Diff] โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”€โ”˜ +``` + +**Emulate from Fork**: +- Three-pane layout (sidebar | graph | details) +- Colored branch graph with collapsible merges +- Branch/tag list in sidebar with icons +- Right-click context menus for actions +- Drag-and-drop branch operations + +**Adapt for CHUCC**: +- Add dataset selector at top +- Replace file list with graph list +- Show RDF Patch instead of text diff +- Triple counts instead of line counts + +### 15.2 Merge Conflict Resolution + +**Layout** (Three-Column): +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Base โ”‚ Ours (main) โ”‚ Theirs (dev)โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ ex:Alice โ”‚ ex:Alice โ”‚ ex:Alice โ”‚ +โ”‚ ex:age 30 โ”‚ ex:age 31 โ”‚ ex:age 32 โ”‚ โ† Conflict! +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ [Accept Base] [Accept Ours] [Accept Theirs]โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + +Conflict 1 of 5: ex:Alice ex:age ?o (graph: default) +[โ—€ Prev] [Resolve All in Graph: Accept Ours โ–พ] [Next โ–ถ] +``` + +**Emulate**: +- Three-column visual comparison +- One-click resolution buttons +- Conflict navigation (prev/next) + +**Adapt**: +- Show triples instead of file content +- Graph-level resolution option (per CHUCC architecture) +- Preview merge result before committing + +### 15.3 Quick Launch for CHUCC + +**Commands**: +- "checkout main" โ†’ switch to main branch +- "merge dev" โ†’ merge dev into current branch +- "time-travel 2025-11-01" โ†’ query as of date +- "create branch feature/auth" โ†’ create new branch +- "cherry-pick 019abc..." โ†’ cherry-pick commit +- "revert 019xyz..." โ†’ revert commit +- "squash last 3" โ†’ squash recent commits +- "switch to dataset mydata" โ†’ change dataset + +**Features**: +- Fuzzy search (like Fork v2.57) +- Recent commands first +- Keyboard-only workflow +- Command history + +### 15.4 Collapsible Commit Graph + +**CHUCC Benefit**: +- Datasets may have long-lived branches with many merges +- Feature branches for data updates (e.g., "import-2025-Q1") +- Collapsing extraneous merges clarifies main branch history + +**Interaction** (Same as Fork): +- Click merge commit tip โ†’ collapse/expand +- Keyboard: โ† / โ†’ arrows +- Context menu: "Collapse all branches" + +### 15.5 Side-by-Side Triple Diff + +**Layout**: +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Before (Commit 019abc) โ”‚ After (Commit 019xyz) โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ ex:Alice ex:age "30" . โ”‚ ex:Alice ex:age "31" . โ”‚ โ† Modified +โ”‚ ex:Bob ex:name "Bob" . โ”‚ ex:Bob ex:name "Bob" . โ”‚ +โ”‚ โ”‚ ex:Carol ex:role ex:Admin . โ”‚ โ† Added +โ”‚ ex:Dan ex:status ex:Active . โ”‚ โ”‚ โ† Deleted +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + +[Unified View] [Side-by-Side โœ“] [Spacebar to toggle] +``` + +**Emulate**: +- Spacebar toggle between unified and side-by-side +- Syntax highlighting for RDF (Turtle format) +- Character-level diff for modified triples + +### 15.6 Branch Drag-and-Drop + +**CHUCC Merge Flow**: +1. User drags "feature/auth" branch from sidebar +2. User drops on "main" branch +3. Tooltip shows "Merge feature/auth into main" +4. Modal opens: Select merge strategy (three-way, ours, theirs) +5. User clicks "Merge" โ†’ POST /version/merge +6. On conflict โ†’ redirect to conflict resolver +7. On success โ†’ commit graph updates + +**Emulate from Fork**: +- Drag-and-drop visual feedback +- Strategy selector in modal +- Fast-forward detection + +--- + +## 16. Visual Design Recommendations + +### 16.1 Adapt Fork's Color Scheme + +**Branch Colors** (Rainbow for distinction): +- main: Blue (#0f62fe) +- dev: Green (#24a148) +- feature/*: Orange (#ff832b) +- bugfix/*: Red (#da1e28) +- release/*: Purple (#8a3ffc) + +**Semantic Colors**: +- Added triples: Green background (light green in diff) +- Deleted triples: Red background (light red in diff) +- Modified triples: Yellow highlight +- Conflict markers: Red border +- Current branch: Yellow star icon + +### 16.2 Typography Hierarchy + +**Adopt Carbon Design System** (already in CHUCC-SQUI): +- Body: IBM Plex Sans +- Code: IBM Plex Mono +- Commit messages: 14px regular +- Branch labels: 14px bold +- Current branch: 14px bold + icon +- Tags: 12px badge style + +### 16.3 Iconography + +**Use Carbon Icons** (carbon-icons-svelte): +- Branch: `` icon +- Tag: `` icon +- Commit: Dot/circle (custom SVG) +- Merge: Converging arrows +- Conflict: `` icon +- Ahead/behind: `` / `` + +### 16.4 Spacing (Carbon Scale) + +- Sidebar width: 240px (adjustable) +- Commit graph row height: 32px (compact: 24px) +- Commit node diameter: 8px +- Branch line width: 2px +- Padding: 8px, 16px, 24px (Carbon scale) + +--- + +## 17. Performance Considerations + +### 17.1 Large Commit Histories + +**Fork's Approach**: +- Incremental rendering (load visible commits first) +- Virtual scrolling for commit list +- Lazy-load commit details (only when selected) + +**CHUCC Adoption**: +- Paginate commit history API calls (e.g., 100 commits at a time) +- Virtual scrolling for commit graph +- Lazy-load RDF Patch diffs (only when commit selected) + +### 17.2 Large Diffs + +**Fork's Approach**: +- Collapse large files (show summary, expand on demand) +- Syntax highlighting with worker threads (non-blocking) + +**CHUCC Adoption**: +- Collapse large graphs in diff (show summary: "+500 triples, -200 triples") +- Lazy-render RDF Patch (render visible portion first) + +--- + +## 18. Comparison to Other Git Clients + +### 18.1 GitKraken +- **Strengths**: Beautiful UI, built-in Git flow +- **Weaknesses**: Confusing workflows, paywalled conflict resolution +- **Fork Advantage**: Simpler, faster, more intuitive + +### 18.2 SourceTree +- **Strengths**: Free, Atlassian integration +- **Weaknesses**: Buggy, slow, limited conflict resolution +- **Fork Advantage**: More stable, cleaner UI + +### 18.3 GitHub Desktop +- **Strengths**: Simple, GitHub-focused +- **Weaknesses**: Lacks advanced features (rebase, cherry-pick) +- **Fork Advantage**: Full Git feature set without sacrificing simplicity + +### 18.4 Tower +- **Strengths**: Native Mac app, polished +- **Weaknesses**: Expensive ($69/year), similar feature set +- **Fork Advantage**: One-time payment ($49.99), faster updates + +--- + +## 19. Conclusion + +Fork Git Client demonstrates that **sophisticated version control can be intuitive** through: +- **Visual clarity**: Colored graphs, avatars, semantic colors +- **Low-friction interactions**: Drag-and-drop, keyboard shortcuts, Quick Launch +- **Smart design**: Collapsible graphs, side-by-side diffs, three-column merge +- **Performance**: Fast rendering, incremental loading, native feel + +**CHUCC should emulate**: +- Three-pane layout (sidebar | graph | details) +- Colored branch graph with collapsible merges +- Drag-and-drop for merge/rebase/cherry-pick +- Quick Launch command palette +- Side-by-side diff viewer +- Three-column merge conflict resolver +- Right-click context menus +- Multi-tab repository/dataset management + +**CHUCC must adapt**: +- Replace file tree with graph list +- Replace text diff with RDF Patch viewer +- Replace file conflicts with triple/quad conflicts +- Add dataset selector (multi-tenant support) +- Add time-travel controls (asOf selector) +- Add batch operation builder (unique to CHUCC) + +**Next Steps**: +1. Complete CHUCC-SQUI component gap analysis (Task 3) +2. Synthesize findings into comprehensive frontend concept (Task 4) +3. Create mockups blending Fuseki's query simplicity with Fork's version control elegance + +--- + +## Appendix: Research Sources + +### Primary Sources +- Fork official website: https://git-fork.com / https://fork.dev +- Release notes: https://git-fork.com/releasenotes (v1.0 - v2.59) +- Blog posts: https://fork.dev/blog/ + - Collapsible graph: https://fork.dev/blog/posts/collapsible-graph/ + - Drag-and-drop merge/rebase: https://fork.dev/blog/posts/ (May 2020) + +### Secondary Sources +- User reviews: https://dev.to/cadams/why-git-fork-is-my-favorite-git-client-19fe +- Comparisons: Slant.co (Fork vs GitHub Desktop, Fork vs GitKraken) + +### Feature References +- YASQE/YASR (for comparison): https://github.com/TriplyDB/Yasgui +- Carbon Design System (CHUCC's choice): https://carbondesignsystem.com + +--- + +**Document Version**: 1.0 +**Last Updated**: 2025-11-10 +**Author**: Claude (AI Research Agent) diff --git a/.frontend-concept/01-research/fuseki-ui-analysis.md b/.frontend-concept/01-research/fuseki-ui-analysis.md new file mode 100644 index 0000000..380898a --- /dev/null +++ b/.frontend-concept/01-research/fuseki-ui-analysis.md @@ -0,0 +1,543 @@ +# Apache Jena Fuseki Web UI Analysis + +**Research Date**: 2025-11-10 +**Purpose**: Understand Fuseki's SPARQL-focused usability patterns for CHUCC frontend design + +--- + +## Executive Summary + +Apache Jena Fuseki provides a **functional, straightforward web interface** for SPARQL operations at `http://localhost:3030`. The UI prioritizes simplicity and practicality over visual polish, using industry-standard components (YASQE/YASR) for query editing and results display. The interface is **tab-based**, **single-page**, and focuses on core SPARQL protocol operations without advanced dataset management or collaboration features. + +**Key Takeaway**: Fuseki's UI excels at making SPARQL accessible through clean, focused interactions. CHUCC should emulate this simplicity while adding sophisticated version control and multi-dataset management. + +--- + +## 1. UI Structure & Layout + +### 1.1 Overall Architecture + +**Access Point**: `http://localhost:3030` + +**Page Structure**: +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Navigation Bar (Brand + Server Status) โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ Dataset Selector Dropdown โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚Queryโ”‚ Upload files โ”‚ Edit โ”‚ Info โ”‚ (Tabs) โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ Active Tab Content Area โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +**Layout Components**: +- **Top Navigation**: Fixed header with Jena Fuseki branding, server status light (green when healthy) +- **Dataset Selector**: Dropdown in first content row, dynamically controls which dataset operations target +- **Tab Navigation**: 4 primary tabs (Query, Upload, Edit, Info) +- **Main Content**: Tab-specific interface below navigation + +**URL Pattern**: `http://localhost:3030/dataset.html?tab=query&ds=/datasetone` + +**Framework**: Bootstrap (responsive grid, navigation components) + +--- + +## 2. Primary Views/Tabs + +### 2.1 Query Tab (Primary Interface) + +**Purpose**: Execute SPARQL queries and updates + +**Components**: +- **SPARQL Editor**: Uses YASQE (Yet Another SPARQL Query Editor) + - Powered by CodeMirror with SPARQL syntax highlighting + - Element ID: `#query-edit-cm` + - Features: Autocomplete, syntax validation, customizable tab size + - Autocomplete via LOV (Linked Open Vocabularies) API by default +- **Query Type Indicator**: Automatically detects SELECT, ASK, CONSTRUCT, DESCRIBE, UPDATE +- **Prefix Management**: + - Button opens modal dialog (`#prefixEditor`) + - Example queries section with common namespace prefixes (rdf, rdfs, owl, xsd, etc.) + - Configuration: `%FUSEKI_HOME%\webapp\js\app\qonsole-config.js` +- **Execute Button**: Prominent, triggers query execution +- **Endpoint Switcher**: Toggle between `/sparql` (read-only) and `/update` (write operations) +- **Results Block** (`#results-block`): + - Uses YASR (Yet Another SPARQL Results) for visualization + - Loading spinner during execution + - Query timing information displayed + - Results container: `#results` + +**Result Formats**: +- **SELECT/ASK**: JSON, XML, CSV, TSV +- **CONSTRUCT/DESCRIBE**: Turtle, JSON-LD, N-Triples, RDF/XML + +**YASR Visualization Options**: +- Table view (default) - each column = variable, each row = result +- Graph view (for CONSTRUCT results) +- Google Charts integration +- HTML widget gallery view +- SPARQL Templates support (e.g., `{{x}}` replaced with variable `?x` binding) + +**Interaction Flow**: +1. User selects dataset from dropdown +2. User types/pastes query in editor (with autocomplete) +3. User clicks Execute (or keyboard shortcut) +4. Results render in table below editor +5. User can export results in chosen format + +**Notable Features**: +- Resizable editor interface +- Query persistence in browser storage +- Syntax highlighting and validation +- Multi-tab support (each tab = isolated query + results) + +--- + +### 2.2 Upload Files Tab + +**Purpose**: Ingest RDF data into the selected dataset + +**Components**: +- File uploader (jQuery File Upload library) +- "Add data" button per dataset +- Drag-and-drop support (typical for jQuery File Upload) + +**Interaction Flow**: +1. User selects dataset +2. User uploads RDF file (formats: N3, Turtle, RDF/XML, etc.) +3. Data ingested into dataset's default or specified graph + +**Limitations**: No bulk upload UI or batch processing mentioned + +--- + +### 2.3 Edit Tab + +**Purpose**: Modify dataset contents (view/edit graphs) + +**Components**: +- "List current graphs" button +- Default graph selector +- Named graph list + +**Interaction Flow**: +1. User clicks "List current graphs" +2. User clicks default graph or named graph +3. Triples displayed (likely in table format) + +**Limitations**: Basic CRUD, no visual graph editor or advanced triple management + +--- + +### 2.4 Info Tab + +**Purpose**: Display dataset metadata and statistics + +**Components**: +- Dataset name, description +- Statistics (triple count, graph count) +- Likely shows service description metadata + +**Details**: Limited documentation available on specific fields displayed + +--- + +## 3. Technology Stack + +### 3.1 JavaScript Libraries + +| Library | Purpose | Version Notes | +|---------|---------|---------------| +| **RequireJS** | Module loader | Entry point: `main.dataset.js` | +| **Bootstrap** | UI framework | Responsive grid, nav tabs | +| **CodeMirror** | Code editor | SPARQL syntax highlighting | +| **YASQE** | SPARQL query editor | @zazuko/yasqe 4.6.0+ (Nov 2025) | +| **YASR** | SPARQL results display | @zazuko/yasr 4.6.0+ (Nov 2025) | +| **jQuery File Upload** | File handling | Drag-drop, multi-file | +| **Font Awesome** | Icons | Standard UI icons | + +### 3.2 CSS Frameworks + +- `bootstrap.min.css` - Layout and components +- `codemirror.min.css` - Editor styling +- `yasqe.min.css` - Query editor theme +- `yasr.min.css` - Results display theme +- `font-awesome.min.css` - Icon fonts + +### 3.3 Configuration + +**Qonsole Config**: `%FUSEKI_HOME%\webapp\js\app\qonsole-config.js` +- Default prefixes +- Sample queries +- Endpoint URLs + +**Runtime Config** (proposed): `http://localhost:3030/config.json` +- JSON-based UI configuration +- Not yet implemented (from Issue #2775) + +--- + +## 4. Interaction Patterns + +### 4.1 Navigation + +**Primary Navigation**: Horizontal tabs (Query, Upload, Edit, Info) +- No deep nesting or hierarchical menus +- All features accessible from single page + +**Dataset Switching**: Dropdown selector +- Changes context for all operations +- Shows `.with-dataset` sections when dataset selected +- URL parameter: `?ds=/datasetname` + +**Server Status**: Visual indicator (green light) in navbar +- Provides at-a-glance health check + +### 4.2 Query Execution + +**Workflow**: +1. Select dataset (dropdown) +2. Type query (with autocomplete) +3. Execute (button or shortcut) +4. View results (table/graph) +5. Export (format selector) + +**Visual Feedback**: +- Loading spinner during query execution +- Timing information after completion +- Error messages inline (if query fails) + +**Keyboard Shortcuts**: Likely supported via CodeMirror defaults (Ctrl+Enter to execute, etc.) + +### 4.3 Prefix Management + +**Pattern**: Modal dialog approach +- Button opens modal +- User adds/removes prefixes +- Saved to browser storage (cookie/localStorage) + +**UX**: Keeps editor clean while allowing customization + +### 4.4 Multi-Tab Queries + +**Feature**: Execute multiple queries in parallel +- Each tab = isolated query + results +- Tab persistence across page reloads +- No cross-tab state interference + +--- + +## 5. Visual Design + +### 5.1 Design Philosophy + +**Utilitarian over Aesthetic**: Focuses on function, not visual polish +- Minimal custom styling +- Relies on Bootstrap defaults +- No custom illustrations or branding elements (beyond logo) + +**Color Palette**: +- Server status: Green (healthy) +- Standard Bootstrap colors for buttons, alerts +- CodeMirror default theme (likely light background) + +**Typography**: +- Bootstrap default (typically Helvetica/Arial) +- Monospace font in query editor (CodeMirror default) + +**Spacing**: Bootstrap grid system (12-column, responsive breakpoints) + +### 5.2 Responsive Design + +**Breakpoints**: Bootstrap defaults (768px tablet, 992px desktop) +**Mobile UX**: Likely collapses tabs to dropdown or accordion (standard Bootstrap behavior) + +--- + +## 6. Strengths (Patterns to Emulate) + +### 6.1 Simplicity +- โœ… Single-page interface reduces cognitive load +- โœ… Tab-based navigation is intuitive +- โœ… Dataset selector clearly scopes operations + +### 6.2 Industry-Standard Components +- โœ… YASQE/YASR are mature, well-tested SPARQL components +- โœ… CodeMirror provides robust editor experience +- โœ… Bootstrap ensures consistent, accessible UI + +### 6.3 Focused Features +- โœ… Query interface prioritizes SPARQL execution (core use case) +- โœ… No feature bloat or unnecessary complexity +- โœ… Clear separation of concerns (query, upload, edit, info) + +### 6.4 Accessibility +- โœ… Bootstrap components are WCAG-compliant +- โœ… Keyboard navigation supported via CodeMirror +- โœ… Semantic HTML structure + +### 6.5 Prefix Management +- โœ… Modal approach keeps editor clean +- โœ… Pre-populated common prefixes reduce typing +- โœ… Persistence across sessions + +--- + +## 7. Weaknesses (Gaps for CHUCC) + +### 7.1 No Version Control +- โŒ No commit history +- โŒ No branch/tag management +- โŒ No time-travel queries +- โŒ No diff visualization +- โŒ No merge/rebase operations + +### 7.2 Limited Dataset Management +- โŒ Basic dataset dropdown, no advanced management UI +- โŒ No dataset creation/deletion via UI +- โŒ No multi-dataset operations +- โŒ No dataset configuration (Kafka topics, retention, etc.) + +### 7.3 Basic Results Display +- โŒ Table view only for SELECT (YASR has plugins, but limited in Fuseki) +- โŒ No graph visualization for RDF structure +- โŒ No result comparison (e.g., diff two query results) + +### 7.4 No Batch Operations +- โŒ No UI for atomic multi-operation commits +- โŒ No operation sequencing or preview + +### 7.5 Minimal Collaboration Features +- โŒ No author tracking +- โŒ No audit log +- โŒ No user management or permissions + +### 7.6 Limited Query History +- โŒ Multi-tab persistence exists, but no dedicated history view +- โŒ No query templates library +- โŒ No saved queries with metadata (tags, descriptions) + +### 7.7 Static Configuration +- โŒ Prefix config in JavaScript file, not user-facing settings +- โŒ No per-user customization (themes, layout preferences) + +--- + +## 8. UI Evolution Plans (from Issue #2775) + +### 8.1 Proposed Improvements + +**Phase One (Issue #2902)**: +- Transform `fuseki-server.jar` with admin functionality + UI +- Browser-side UI with server-side page serving +- Shiro security support +- Command-line admin password management + +**Future Vision**: +- Modular UI responding to available server functions +- Independent server statistics (currently embedded in admin) +- Unified dataset initialization (config file or CLI) + +### 8.2 Community Feedback + +**Desired Features** (from JIRA JENA-420): +- Enhanced query input with IDE-like features: + - Syntax highlighting โœ… (already has via CodeMirror) + - Automatic indentation โœ… (already has via CodeMirror) + - Easy commenting of selected lines +- User-customizable prefix defaults (stored in cookie) +- Improved dataset management interface + +**Technology Debate**: +- Proposal: Adopt JAX-RS for REST abstraction +- Maintainer response: "Fuseki having its own HTTP handling has been an advantage because details matter" +- Conclusion: Custom solutions via modules preferred over heavy frameworks + +--- + +## 9. Reusable Patterns for CHUCC + +### 9.1 Tab-Based Navigation +**Emulate**: Use tabs for primary feature areas (Query, Graphs, Version Control, etc.) +**Reason**: Reduces navigation complexity, keeps related features accessible + +### 9.2 Dataset Selector +**Emulate**: Prominent dropdown for dataset switching +**Reason**: Clear scoping of operations, especially critical for CHUCC's multi-dataset support + +### 9.3 YASQE/YASR Components +**Consider**: Leverage YASQE/YASR in CHUCC-SQUI or frontend +**Reason**: Battle-tested, feature-rich, actively maintained +**Alternative**: CHUCC-SQUI already has CodeMirror-based query editor; may not need YASQE + +### 9.4 Prefix Management Modal +**Emulate**: Modal dialog for prefix configuration +**Reason**: Keeps editor interface clean, allows rich editing experience + +### 9.5 Server Status Indicator +**Emulate**: Visual health indicator (e.g., green/red light) +**Reason**: Immediate feedback on system status + +### 9.6 Split Pane Layout (Query + Results) +**Emulate**: Editor on top, results below (or side-by-side on wide screens) +**Reason**: Reduces scrolling, keeps query and results in view + +--- + +## 10. Anti-Patterns to Avoid + +### 10.1 Overly Simplistic Dataset Management +**Issue**: Fuseki's dropdown-only approach scales poorly with many datasets +**CHUCC Solution**: Dedicated dataset management view with table, search, filters + +### 10.2 Static Configuration in Code +**Issue**: Prefix config in JS file requires redeployment +**CHUCC Solution**: User-facing settings page, persist in browser localStorage or server-side + +### 10.3 Limited Query History +**Issue**: Only tab persistence, no searchable history +**CHUCC Solution**: Dedicated history view with search, tags, metadata + +### 10.4 No Result Comparison +**Issue**: Can't diff query results or time-travel comparisons +**CHUCC Solution**: Time-travel UI with side-by-side result comparison + +--- + +## 11. Visual Mockup Analysis (Conceptual) + +Since no screenshots were available during research, here's a conceptual layout based on HTML/JS analysis: + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [Jena Fuseki Logo] [Status: โ—] โ”‚ โ† Navbar +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ Dataset: [Select dataset โ–พ] โ”‚ โ† Dataset selector +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ [Query] [Upload files] [Edit] [Info] โ”‚ โ† Tabs +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ PREFIX rdf: โ”‚ โ”‚ +โ”‚ โ”‚ PREFIX rdfs: โ”‚ โ”‚ Query editor +โ”‚ โ”‚ โ”‚ โ”‚ (CodeMirror/YASQE) +โ”‚ โ”‚ SELECT ?s ?p ?o WHERE { โ”‚ โ”‚ +โ”‚ โ”‚ ?s ?p ?o . โ”‚ โ”‚ +โ”‚ โ”‚ } โ”‚ โ”‚ +โ”‚ โ”‚ LIMIT 100 โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ +โ”‚ [Prefixes โ–พ] [Example Queries โ–พ] [โ–ถ Execute Query] โ”‚ โ† Controls +โ”‚ โ”‚ +โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”‚ +โ”‚ โ”‚ +โ”‚ Results (10 rows, 42ms): โ”‚ โ† Results header +โ”‚ โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ ?s โ”‚ ?p โ”‚ ?o โ”‚ โ”‚ Results table +โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ (YASR) +โ”‚ โ”‚ ex:Alice โ”‚ ex:age โ”‚ 30 โ”‚ โ”‚ +โ”‚ โ”‚ ex:Bob โ”‚ ex:name โ”‚ "Bob" โ”‚ โ”‚ +โ”‚ โ”‚ ... โ”‚ ... โ”‚ ... โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ +โ”‚ [Export: JSON โ–พ] [Download โ†“] โ”‚ โ† Export controls +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +**Key Layout Observations**: +- Horizontal layout (no sidebar) +- Top-heavy navigation (navbar, dataset selector, tabs all stacked) +- Split-pane query editor and results (vertical split) +- Minimal chrome, maximal content area + +--- + +## 12. Recommendations for CHUCC Frontend + +### 12.1 Adopt from Fuseki +1. **Tab-based primary navigation** for Query, Graphs, Version Control, etc. +2. **Dataset selector** at top of interface (dropdown or more advanced picker) +3. **Split-pane layout** for editor and results/output +4. **Prefix management modal** for clean editor experience +5. **Server status indicator** for health monitoring +6. **YASQE/YASR** as options for query/results (or CHUCC-SQUI equivalents) + +### 12.2 Improve upon Fuseki +1. **Add sidebar** for version control (branches, tags, commits list) +2. **Dedicated dataset management view** with advanced features +3. **Query history** as first-class feature (searchable, taggable) +4. **Result comparison** for time-travel queries +5. **Batch operation builder** with visual preview +6. **User settings** page (theme, layout, defaults) +7. **Visual graph explorer** for RDF structure (beyond triple table) + +### 12.3 Version Control Integration +- **Branch selector** alongside dataset selector (or combined) +- **Commit indicator** showing current HEAD +- **Time-travel controls** (asOf date picker, timeline slider) +- **Diff viewer** for commit comparisons (RDF Patch rendering) + +### 12.4 Multi-Dataset UX +- **Dataset switcher** with search, favorites, recent +- **Dataset creation wizard** (step-by-step with Kafka config) +- **Dataset health dashboard** (Kafka topic status, projection lag) + +--- + +## 13. Conclusion + +Apache Jena Fuseki's web UI provides a **solid foundation** for SPARQL operations through its: +- **Simple, focused design** prioritizing core use cases +- **Industry-standard components** (YASQE, YASR, CodeMirror) +- **Functional, accessible interface** with minimal friction + +However, it **lacks advanced features** needed for CHUCC: +- No version control UI +- Limited dataset management +- Basic results display +- No collaboration or audit features + +**CHUCC should**: +- **Emulate** Fuseki's simplicity and focus in the Query Workbench +- **Extend** with sophisticated version control UI (Fork-inspired) +- **Add** multi-dataset management and batch operations +- **Maintain** the single-page, tab-based navigation paradigm +- **Enhance** with time-travel, conflict resolution, and collaboration features + +**Next Steps**: +1. Research Fork Git Client UX (Task 2) +2. Conduct CHUCC-SQUI component gap analysis (Task 3) +3. Synthesize findings into comprehensive frontend concept (Task 4) + +--- + +## Appendix: Research Sources + +### Primary Sources +- Fuseki dataset.html analysis: https://github.com/streamreasoning/TripleWave/blob/master/fuseki/webapp/dataset.html +- Fuseki UI evolution discussion: https://github.com/apache/jena/issues/2775 +- YASGUI documentation: https://docs.triply.cc/yasgui/ + +### Secondary Sources +- Fuseki demo: https://github.com/hectorcorrea/fuseki_demo +- Practical session: https://www.emse.fr/~zimmermann/Teaching/SemWeb/session5.html +- Getting started guide: https://christinemdraper.wordpress.com/2017/04/09/getting-started-with-rdf-sparql-jena-fuseki/ + +### Component Libraries +- YASQE: https://github.com/TriplyDB/Yasgui (Yet Another SPARQL Query Editor) +- YASR: https://github.com/TriplyDB/Yasgui (Yet Another SPARQL Results) +- CodeMirror: https://codemirror.net/ +- Bootstrap: https://getbootstrap.com/ + +--- + +**Document Version**: 1.0 +**Last Updated**: 2025-11-10 +**Author**: Claude (AI Research Agent) diff --git a/.frontend-concept/02-concept/01-information-architecture.md b/.frontend-concept/02-concept/01-information-architecture.md new file mode 100644 index 0000000..d6a3a50 --- /dev/null +++ b/.frontend-concept/02-concept/01-information-architecture.md @@ -0,0 +1,742 @@ +# CHUCC Frontend - Information Architecture + +**Date**: 2025-11-10 +**Version**: 1.0 + +--- + +## 1. Executive Summary + +This document defines the information architecture for the CHUCC frontend, including: +- **Navigation hierarchy** - How users move between features +- **Routing structure** - URL patterns and navigation flows +- **Primary views** - 7 main application views +- **Content organization** - How information is structured and prioritized + +**Design Philosophy**: +- **Tab-based primary navigation** (Fuseki pattern) for main feature areas +- **Sidebar for context** (Fork pattern) in version control views +- **Single-page app** with client-side routing +- **Progressive disclosure** - show simple first, advanced on demand + +--- + +## 2. Site Map + +``` +CHUCC Frontend +โ”‚ +โ”œโ”€โ”€ Query Workbench (/query) +โ”‚ โ”œโ”€โ”€ Query Editor +โ”‚ โ”œโ”€โ”€ Results Viewer +โ”‚ โ”œโ”€โ”€ Prefix Manager (modal) +โ”‚ โ””โ”€โ”€ Query History (sidebar, optional) +โ”‚ +โ”œโ”€โ”€ Graph Explorer (/graphs) +โ”‚ โ”œโ”€โ”€ Graph List (sidebar) +โ”‚ โ”œโ”€โ”€ Graph Viewer (main) +โ”‚ โ”œโ”€โ”€ Upload Graph (modal) +โ”‚ โ””โ”€โ”€ Graph Operations (PUT, POST, DELETE, PATCH) +โ”‚ +โ”œโ”€โ”€ Version Control (/version) +โ”‚ โ”œโ”€โ”€ Commit Graph (main) +โ”‚ โ”œโ”€โ”€ Branches (sidebar) +โ”‚ โ”œโ”€โ”€ Tags (sidebar) +โ”‚ โ”œโ”€โ”€ Commit Details (bottom panel) +โ”‚ โ”œโ”€โ”€ History Filter (toolbar) +โ”‚ โ””โ”€โ”€ Advanced Operations (modals) +โ”‚ โ”œโ”€โ”€ Merge +โ”‚ โ”œโ”€โ”€ Cherry-Pick +โ”‚ โ”œโ”€โ”€ Revert +โ”‚ โ”œโ”€โ”€ Reset +โ”‚ โ”œโ”€โ”€ Rebase +โ”‚ โ””โ”€โ”€ Squash +โ”‚ +โ”œโ”€โ”€ Merge & Conflicts (/merge/conflicts) +โ”‚ โ”œโ”€โ”€ Conflict Summary +โ”‚ โ”œโ”€โ”€ Conflict List (sidebar) +โ”‚ โ”œโ”€โ”€ Conflict Resolver (main, 3-pane) +โ”‚ โ””โ”€โ”€ Merge Preview (modal) +โ”‚ +โ”œโ”€โ”€ Time Travel (/time-travel) +โ”‚ โ”œโ”€โ”€ Query Workbench (enhanced) +โ”‚ โ”œโ”€โ”€ Timeline Slider +โ”‚ โ”œโ”€โ”€ asOf Date Picker +โ”‚ โ”œโ”€โ”€ Commit Selector +โ”‚ โ””โ”€โ”€ Comparison Mode (side-by-side results) +โ”‚ Note: Provides timeline view of commits for historical analysis. +โ”‚ Queries resolve to specific commits (no data "between" commits). +โ”‚ Alternative: Consider merging with /version as visualization mode +โ”‚ +โ”œโ”€โ”€ Dataset Manager (/datasets) +โ”‚ โ”œโ”€โ”€ Dataset List (table) +โ”‚ โ”œโ”€โ”€ Dataset Detail (panel) +โ”‚ โ”œโ”€โ”€ Create Dataset (wizard modal) +โ”‚ โ”œโ”€โ”€ Delete Dataset (confirmation modal) +โ”‚ โ””โ”€โ”€ Dataset Health (dashboard) +โ”‚ +โ”œโ”€โ”€ Batch Operations (/batch) +โ”‚ โ”œโ”€โ”€ Operation Builder (main) +โ”‚ โ”œโ”€โ”€ Operation List (table) +โ”‚ โ”œโ”€โ”€ Add Operation (modal) +โ”‚ โ”œโ”€โ”€ Preview (panel) +โ”‚ โ””โ”€โ”€ Execute (confirmation) +โ”‚ +โ””โ”€โ”€ Settings (/settings) + โ”œโ”€โ”€ User Profile (author metadata) + โ”œโ”€โ”€ Theme Preferences + โ”œโ”€โ”€ Default Prefixes + โ”œโ”€โ”€ Keyboard Shortcuts + โ””โ”€โ”€ API Configuration +``` + +--- + +## 3. Navigation Hierarchy + +### 3.1 Primary Navigation (Top-Level) + +**Pattern**: Horizontal tabs in header (always visible) + +**Structure**: +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [CHUCC Logo] [Query] [Graphs] [Version] [Time Travel] โ”‚ +โ”‚ [Datasets] [Batch] [Settings] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +**Navigation Items**: +1. **Query** - SPARQL query workbench (default landing page) +2. **Graphs** - Graph Store Protocol operations +3. **Version** - Version control (commits, branches, tags) +4. **Time Travel** - Historical queries with asOf selector +5. **Datasets** - Multi-dataset management +6. **Batch** - Atomic batch operations +7. **Settings** - User preferences (right-aligned) + +**Active State**: Current tab highlighted with blue underline (Carbon style) + +--- + +### 3.2 Secondary Navigation (Context-Specific) + +#### 3.2.1 Query Workbench - No Secondary Nav +- Single-pane focus on query editing and results +- Actions via toolbar buttons (Execute, Export, Prefixes) + +#### 3.2.2 Graph Explorer - Sidebar (Left) +- **Graph List**: Collapsible tree + - Default Graph (always present) + - Named Graphs (alphabetically sorted) +- **Actions**: Add, Delete, Upload (buttons at bottom) + +#### 3.2.3 Version Control - Sidebar (Left) + Bottom Panel +- **Sidebar**: + - Branches (collapsible section) + - Local Branches (with current indicator) + - Remote Branches (collapsible subsection) + - Tags (collapsible section) + - Filter Input (at top) +- **Bottom Panel**: Commit details (appears when commit selected) + +#### 3.2.4 Merge & Conflicts - Sidebar (Left) +- **Conflict List**: Graph-by-graph accordion + - Each graph shows: "3 of 5 conflicts resolved" + - Click graph โ†’ show resolver in main panel + +#### 3.2.5 Time Travel - Toolbar (Top) +- **Timeline Controls**: Date picker, slider, commit selector +- **Mode Toggle**: Single query vs. Comparison mode + +#### 3.2.6 Dataset Manager - No Secondary Nav +- **Table View**: Dataset list with actions in rows + +#### 3.2.7 Batch Operations - No Secondary Nav +- **Builder View**: Operation list with add/remove actions + +--- + +### 3.3 Tertiary Navigation (Modals & Panels) + +**Modals** (overlay entire app): +- Prefix Manager (from Query Workbench) +- Upload Graph (from Graph Explorer) +- Create Dataset Wizard (from Dataset Manager) +- Delete Dataset Confirmation (from Dataset Manager) +- Merge Configuration (from Version Control) +- Cherry-Pick / Revert / Reset / Rebase / Squash (from Version Control) +- Add Operation (from Batch Operations) + +**Panels** (slide out from side or bottom): +- Query History (optional, from Query Workbench) +- Commit Details (from Version Control) +- Dataset Health (from Dataset Manager) + +**Popovers** (contextual): +- Help tooltips (? icons) +- Branch info on hover +- Commit SHA on hover + +--- + +## 4. Routing Structure + +### 4.1 URL Patterns + +**Base URL**: `https://chucc.example.com/` + +**Routes**: +``` +/ โ†’ Redirect to /query +/query โ†’ Query Workbench +/query?dataset={name}&branch={name} โ†’ Query with pre-selected dataset/branch + +/graphs โ†’ Graph Explorer +/graphs?dataset={name}&graph={uri} โ†’ Graph Explorer with specific graph selected + +/version โ†’ Version Control (default: current branch) +/version?dataset={name}&branch={name} โ†’ Version Control for specific branch +/version/commits/{commitId} โ†’ Version Control with commit selected + +/merge/conflicts โ†’ Merge Conflicts Resolver +/merge/conflicts?dataset={name}&merge={id} โ†’ Specific merge conflict + +/time-travel โ†’ Time Travel Queries +/time-travel?dataset={name}&asOf={timestamp} โ†’ Time Travel with asOf pre-set + +/datasets โ†’ Dataset Manager +/datasets/{name} โ†’ Dataset Detail View + +/batch โ†’ Batch Operations +/batch?dataset={name} โ†’ Batch Operations for specific dataset + +/settings โ†’ Settings +/settings/profile โ†’ User Profile +/settings/theme โ†’ Theme Preferences +/settings/shortcuts โ†’ Keyboard Shortcuts +``` + +### 4.2 Query Parameters + +**Global Parameters** (applicable to most routes): +- `dataset={name}` - Selected dataset (default: "default") +- `branch={name}` - Selected branch (default: "main") +- `commit={commitId}` - Selected commit (UUIDv7) +- `asOf={timestamp}` - Time-travel timestamp (RFC 3339) + +**View-Specific Parameters**: +- **Query**: `query={base64}` - Pre-filled query (for sharing) +- **Graphs**: `graph={uri}` - Selected named graph +- **Version**: `filter={text}` - Branch/commit filter +- **Merge**: `merge={id}` - Merge operation ID +- **Time Travel**: `compare={timestamp}` - Second timestamp for comparison +- **Batch**: `operation={json}` - Pre-configured operation + +### 4.3 Hash Navigation (Within Views) + +Use hash fragments for sub-view navigation (doesn't trigger page reload): + +- `/version#branches` - Scroll to branches section +- `/version#tags` - Scroll to tags section +- `/settings#theme` - Jump to theme settings + +--- + +## 5. Content Organization + +### 5.1 Header (Global) + +**Layout**: +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [Logo] [Query][Graphs][Version][Time Travel][Datasets][Batch] โ”‚ +โ”‚ [Datasetโ–พ] [โš™๏ธ] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +**Components** (left to right): +1. **Logo** (left): "CHUCC" logo + icon (click โ†’ home/query) +2. **Primary Nav Tabs** (center-left): Main feature areas +3. **Dataset Selector** (right): Dropdown showing current dataset +4. **Settings Icon** (far right): Gear icon โ†’ Settings page + +**Sticky**: Header fixed at top (always visible on scroll) + +--- + +### 5.2 Footer (Global) + +**Layout**: +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Dataset: my-dataset | Branch: main | Author: Alice โ”‚ +โ”‚ [Notification Toast Area] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +**Components**: +1. **Status Bar** (left): Current context (dataset, branch, author) +2. **Notification Area** (bottom-right): Toast notifications appear here + +**Sticky**: Footer fixed at bottom + +--- + +### 5.3 Main Content Area + +**Layout Patterns**: + +#### Pattern A: Single Pane (Query, Batch, Datasets) +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ โ”‚ +โ”‚ โ”‚ +โ”‚ Full-Width Content โ”‚ +โ”‚ โ”‚ +โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +#### Pattern B: Sidebar + Main (Graphs, Version, Merge) +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ โ”‚ โ”‚ +โ”‚ Sidebar โ”‚ Main Content โ”‚ +โ”‚ (240px) โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +#### Pattern C: Sidebar + Main + Bottom Panel (Version Control) +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ โ”‚ โ”‚ +โ”‚ Sidebar โ”‚ Commit Graph โ”‚ +โ”‚ โ”‚ โ”‚ +โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค +โ”‚ Commit Details / Diff โ”‚ +โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +#### Pattern D: Three-Pane (Merge Conflicts) +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ Conflict โ”‚ Base โ”‚ Ours โ”‚ Theirs (below) +โ”‚ List โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +--- + +## 6. Information Hierarchy + +### 6.1 Priority Levels + +**P1 (Critical)**: Always visible, primary user goal +- Query editor (Query Workbench) +- Commit graph (Version Control) +- Dataset selector (Header) +- Execute/Commit/Merge buttons + +**P2 (Important)**: Visible but secondary +- Results table (Query Workbench) +- Branch list (Version Control) +- Commit details (Version Control) +- Graph list (Graph Explorer) + +**P3 (Supporting)**: Hidden by default, shown on demand +- Prefix manager (modal) +- Query history (panel) +- Advanced operations (modals) +- Settings (separate page) + +### 6.2 Visual Weight + +**Heavy** (draws attention): +- Primary action buttons (blue, prominent) +- Current dataset/branch indicators (bold, highlighted) +- Active tab (blue underline) +- Error states (red) + +**Medium** (standard): +- Secondary action buttons (ghost style) +- Navigation items (inactive tabs) +- Data tables (standard rows) + +**Light** (de-emphasized): +- Help text, tooltips +- Timestamps, metadata +- Disabled buttons + +--- + +## 7. Responsive Breakpoints + +### 7.1 Breakpoints (Carbon Design System) + +| Breakpoint | Width | Layout | +|------------|-------|--------| +| **Small (sm)** | 320px - 671px | Mobile (stacked, collapsed sidebar) | +| **Medium (md)** | 672px - 1055px | Tablet (sidebar collapsible, split-pane vertical) | +| **Large (lg)** | 1056px - 1311px | Desktop (full layout, sidebar visible) | +| **X-Large (xlg)** | 1312px - 1583px | Wide desktop (spacious layout) | +| **Max (max)** | 1584px+ | Ultra-wide (max content width) | + +### 7.2 Responsive Behavior + +#### Mobile (320px - 671px) +- **Header**: Logo + hamburger menu (hide tabs) +- **Sidebar**: Collapsed by default (slide-out on hamburger click) +- **Query Workbench**: Editor and results stacked vertically +- **Version Control**: Commit graph full-width, details in modal +- **Merge Conflicts**: Three-pane becomes accordion (one pane at a time) + +#### Tablet (672px - 1055px) +- **Header**: Logo + all tabs visible +- **Sidebar**: Collapsible (toggle button), overlay when open +- **Query Workbench**: Editor and results side-by-side (50/50 split) +- **Version Control**: Sidebar + graph, details in bottom panel +- **Merge Conflicts**: Two-pane visible, third in tab/toggle + +#### Desktop (1056px+) +- **Header**: Full layout +- **Sidebar**: Always visible, adjustable width +- **Query Workbench**: Editor and results side-by-side (adjustable split) +- **Version Control**: Full three-pane (sidebar | graph | details) +- **Merge Conflicts**: Full three-pane visible + +--- + +## 8. Navigation Patterns + +### 8.1 Cross-View Navigation + +**From Query Workbench**: +- Click triple in results โ†’ navigate to Graph Explorer with graph/triple selected +- Right-click branch selector โ†’ "View History" โ†’ navigate to Version Control + +**From Graph Explorer**: +- Right-click graph โ†’ "View History" โ†’ navigate to Version Control, filter by graph + +**From Version Control**: +- Click commit โ†’ show commit details (bottom panel) +- Double-click commit โ†’ navigate to Time Travel with asOf set to commit timestamp +- Right-click commit โ†’ "Query at this commit" โ†’ navigate to Time Travel + +**From Time Travel**: +- Click "View Commit" โ†’ navigate to Version Control with commit selected + +**From Dataset Manager**: +- Click dataset โ†’ switch dataset globally, stay on current view +- Click "Query" button โ†’ navigate to Query Workbench with dataset selected + +--- + +### 8.2 Context Preservation + +**Global Context** (persisted across views): +- **Current Dataset**: Stored in global state, persists in URL +- **Current Branch**: Stored in global state, persists in URL +- **Author**: Stored in localStorage, shown in footer + +**View-Specific Context** (not preserved when switching views): +- Query text (Query Workbench) +- Selected commit (Version Control) +- Conflict resolution state (Merge & Conflicts) + +**Session Persistence**: +- Store in browser localStorage: + - Last selected dataset + - Last selected branch per dataset + - Query history (last 50 queries) + - User preferences (theme, author) + +--- + +### 8.3 Breadcrumb Navigation + +**Not Used** - Primary nav tabs replace breadcrumbs +- Tabs always show current location +- Dataset/branch context shown in header and footer + +**Exception**: Multi-step wizards (e.g., Create Dataset) +- Use Carbon ProgressIndicator component to show wizard steps + +--- + +## 9. Search & Filter + +### 9.1 Global Search (Not Implemented in v1) + +**Future Feature**: Search bar in header +- Search commits by message +- Search branches by name +- Search datasets by name/description +- Search queries in history + +**v1 Workaround**: View-specific filters (e.g., branch filter in Version Control) + +--- + +### 9.2 View-Specific Filters + +| View | Filter Location | Filter Targets | +|------|-----------------|----------------| +| **Version Control** | Sidebar top | Branches, commits by message, author | +| **Graph Explorer** | Sidebar top | Named graphs by URI | +| **Dataset Manager** | Table toolbar | Datasets by name, description | +| **Batch Operations** | Table toolbar | Operations by type, graph | + +**Filter UI**: Carbon Search component (icon + text input) +**Behavior**: Live filtering (no submit button) + +--- + +## 10. Keyboard Navigation + +### 10.1 Global Shortcuts + +| Shortcut | Action | +|----------|--------| +| `Ctrl+P` / `โŒ˜+P` | Open Quick Launch palette | +| `Ctrl+K` / `โŒ˜+K` | Focus dataset selector | +| `Ctrl+1` ... `Ctrl+7` | Jump to primary nav tab (Query, Graphs, etc.) | +| `Ctrl+,` / `โŒ˜+,` | Open Settings | +| `Esc` | Close modal/panel | +| `?` | Show keyboard shortcuts help | + +### 10.2 View-Specific Shortcuts + +**Query Workbench**: +- `Ctrl+Enter` / `โŒ˜+Enter` - Execute query +- `Ctrl+/` / `โŒ˜+/` - Toggle comment (in editor) +- `Ctrl+S` / `โŒ˜+S` - Save query to history + +**Graph Explorer**: +- `Ctrl+U` / `โŒ˜+U` - Upload graph +- `Del` - Delete selected graph + +**Version Control**: +- `Ctrl+F` / `โŒ˜+F` - Focus filter input +- `โ†‘` / `โ†“` - Navigate commits +- `Enter` - View commit details +- `Ctrl+M` / `โŒ˜+M` - Merge current branch + +**Merge & Conflicts**: +- `Ctrl+O` / `โŒ˜+O` - Accept Ours +- `Ctrl+T` / `โŒ˜+T` - Accept Theirs +- `Ctrl+B` / `โŒ˜+B` - Accept Base +- `Ctrl+]` - Next conflict +- `Ctrl+[` - Previous conflict + +--- + +## 11. Progressive Disclosure + +### 11.1 Simple โ†’ Advanced + +**Default View**: Simple, focused on common tasks +- Query Workbench: Editor + results (no advanced options visible) +- Version Control: Commit graph + branches (no advanced operations visible) + +**Advanced Features** (hidden by default): +- Advanced query options (timeout, format preferences) โ†’ Expandable section +- Version control advanced operations (rebase, squash) โ†’ Context menu or toolbar overflow +- Dataset Kafka configuration โ†’ Expandable section in wizard + +**Disclosure Patterns**: +- **Expandable Sections**: Carbon Accordion for collapsible content +- **Context Menus**: Right-click for advanced actions +- **Overflow Menus**: Three-dot menu for secondary actions +- **Modals**: Complex operations open in dedicated modals + +--- + +### 11.2 Progressive Depth + +**Level 1** (Overview): Summary information +- Dataset list โ†’ Name, description, main branch + +**Level 2** (Details): More metadata +- Click dataset row โ†’ Expand to show commit count, branch count, created date + +**Level 3** (Full Context): Complete information +- Click "View Details" โ†’ Navigate to Dataset Detail page with health dashboard + +--- + +## 12. Error States & Empty States + +### 12.1 Error States + +**No Dataset Selected**: +- Show: "Please select a dataset to continue" +- Action: Prominent dataset selector button + +**No Branch Selected**: +- Show: "Please select a branch" +- Action: Branch selector dropdown + +**Network Error**: +- Show: "Unable to connect to CHUCC server" +- Action: "Retry" button + +**404 Not Found**: +- Show: "Dataset not found" or "Commit not found" +- Action: "Go back" or "View all datasets" + +**409 Conflict**: +- Show: "Merge conflict detected" +- Action: "Resolve conflicts" button โ†’ navigate to /merge/conflicts + +--- + +### 12.2 Empty States + +**No Commits**: +- Show: "No commits yet. Create your first commit by modifying a graph." +- Action: "Go to Graph Explorer" button + +**No Branches**: +- Show: "No branches. The main branch will be created automatically." + +**No Tags**: +- Show: "No tags yet. Create a tag from a commit." +- Action: "Learn about tags" link + +**No Conflicts**: +- Show: "โœ“ No conflicts. Ready to merge." +- Action: "Complete merge" button + +**No Datasets**: +- Show: "No datasets yet. Create your first dataset." +- Action: "Create Dataset" button (prominent, blue) + +--- + +## 13. Loading States + +### 13.1 Loading Patterns + +**Initial Load** (full page): +- Carbon Loading component (spinner + "Loading CHUCC...") + +**Partial Load** (content area): +- Carbon InlineLoading component (spinner in context) + +**Background Load** (non-blocking): +- ProgressBar at top of view (thin blue line) +- Toast notification when complete + +**Skeleton Loading** (for tables/lists): +- Carbon SkeletonText for commit list, dataset list + +--- + +### 13.2 Loading Indicators + +| Context | Indicator | Duration | +|---------|-----------|----------| +| **Page Load** | Full-page spinner | Until first content renders | +| **Query Execution** | Inline spinner in results area | Until results or error | +| **Commit Graph Load** | Skeleton rows | Until first 100 commits load | +| **Branch List Load** | Skeleton items | Until branches load | +| **Merge Operation** | Progress modal (indeterminate) | Until success/conflict | +| **Dataset Creation** | Progress modal (stepped) | Until 202 Accepted | + +--- + +## 14. Notification System + +### 14.1 Notification Types + +**Success** (Green): +- "Query executed successfully" +- "Commit created: 019abc..." +- "Branch merged successfully" +- "Dataset created: my-dataset" + +**Warning** (Yellow): +- "Projection lag detected (5 seconds behind)" +- "Kafka topic health degraded" +- "Large result set (10,000+ rows)" + +**Error** (Red): +- "Query failed: Syntax error at line 5" +- "Merge conflict: 12 graphs in conflict" +- "Dataset creation failed: Name already exists" + +**Info** (Blue): +- "Update accepted (202). Changes pending projection." +- "Time-travel query executed at 2025-11-10T10:30:00Z" + +--- + +### 14.2 Notification Placement + +**Toast Notifications** (bottom-right): +- Auto-dismiss after 5 seconds (success, info) +- Manual dismiss (warning, error) +- Stack vertically if multiple +- Max 3 visible at once + +**Inline Notifications** (context-specific): +- Above results table (Query Workbench) +- Above commit graph (Version Control) +- Above operation list (Batch Operations) + +**Modal Notifications** (blocking): +- Confirmations (delete dataset, reset branch) +- Critical errors (server unreachable) + +--- + +## 15. Accessibility (WCAG 2.1 AA) + +### 15.1 Keyboard Navigation + +- โœ… All functionality accessible via keyboard +- โœ… Tab order follows visual hierarchy +- โœ… Focus indicators visible (2px blue outline) +- โœ… Skip links for main content ("Skip to content") + +### 15.2 Screen Reader Support + +- โœ… ARIA labels on all interactive elements +- โœ… ARIA landmarks (navigation, main, complementary) +- โœ… ARIA live regions for dynamic content (notifications, results) +- โœ… Alt text for icons and images + +### 15.3 Color Contrast + +- โœ… Text: 4.5:1 minimum (body text) +- โœ… UI elements: 3:1 minimum (buttons, inputs) +- โœ… Links: Underlined (not color-only) +- โœ… Error states: Icon + color + text + +--- + +## 16. Summary + +**Navigation Philosophy**: Tab-based (Fuseki) + Sidebar for context (Fork) +**Routing**: Client-side SPA with query parameters for state +**Layout Patterns**: 4 patterns (single-pane, sidebar, sidebar+bottom, three-pane) +**Responsive**: Mobile-first, 5 breakpoints (sm, md, lg, xlg, max) +**Progressive Disclosure**: Simple by default, advanced on demand +**Accessibility**: Full WCAG 2.1 AA compliance + +**Next Steps**: +1. Create detailed UI mockups for 7 primary views +2. Define component architecture and state management +3. Document interaction flows for key operations +4. Define visual design system + +--- + +**Document Version**: 1.0 +**Last Updated**: 2025-11-10 +**Author**: Claude (AI Research Agent) diff --git a/.frontend-concept/02-concept/executive-summary.md b/.frontend-concept/02-concept/executive-summary.md new file mode 100644 index 0000000..c2bb629 --- /dev/null +++ b/.frontend-concept/02-concept/executive-summary.md @@ -0,0 +1,753 @@ +# CHUCC Frontend Concept - Executive Summary + +**Date**: 2025-11-10 +**Version**: 1.0 + +--- + +## 1. Project Overview + +The CHUCC frontend combines the **query-focused simplicity of Apache Jena Fuseki** with the **elegant version control UX of Fork Git Client**, creating a powerful interface for SPARQL query execution and RDF dataset version control. + +**Technology Stack**: +- **Framework**: Svelte 5 +- **Design System**: IBM Carbon Design System +- **Component Library**: CHUCC-SQUI (SPARQL query components) +- **Build Tool**: Vite +- **Testing**: Vitest + Playwright + +--- + +## 2. Research Findings Summary + +### 2.1 Fuseki UI Analysis (3,500 words) + +**Strengths to Emulate**: +- โœ… Tab-based navigation (Query, Upload, Edit, Info) +- โœ… YASQE/YASR components (query editor + results) +- โœ… Split-pane layout (editor + results) +- โœ… Dataset selector dropdown +- โœ… Prefix management modal +- โœ… Simple, functional design + +**Gaps to Address**: +- โŒ No version control +- โŒ Limited dataset management +- โŒ No batch operations +- โŒ Basic results display + +### 2.2 Fork UX Analysis (5,000 words) + +**Patterns to Adopt**: +- โœ… Three-pane layout (sidebar | graph | details) +- โœ… Colored branch graph with collapsible merges +- โœ… Drag-and-drop operations (merge, rebase, cherry-pick) +- โœ… Quick Launch command palette (Ctrl+P) +- โœ… Side-by-side diff viewer +- โœ… Three-column merge conflict resolver +- โœ… Interactive rebase with visual drag-to-reorder +- โœ… Right-click context menus + +**Adaptations for RDF**: +- File tree โ†’ Graph list +- Text diff โ†’ RDF Patch viewer +- File conflicts โ†’ Triple/quad conflicts +- Working directory โ†’ Batch operation builder + +### 2.3 Component Gap Analysis (6,000 words) + +**Available Components**: +- Carbon: 165+ components (complete standard UI) +- CHUCC-SQUI: 8 components (SPARQL query + results) + +**Missing Components**: 15+ +- **CHUCC-SQUI (7 new)**: RDF Patch Viewer, RDF Diff Viewer, Graph Explorer, Commit SHA Badge, Author Input, 3-Pane Diff View, RDF Patch Language Mode +- **Frontend (11 new)**: Commit Graph (DAG), Branch Selector, Commit Detail, History Filter, Time Travel Controls, Conflict Summary/Resolver, Merge Modal, Dataset Wizard/Health/Switcher, Batch Builder/Preview, Quick Launch + +--- + +## 3. Information Architecture + +### 3.1 Primary Views (7) + +1. **Query Workbench** (`/query`) - SPARQL query interface +2. **Graph Explorer** (`/graphs`) - Graph Store Protocol operations +3. **Version Control** (`/version`) - Commit history, branches, tags +4. **Merge & Conflicts** (`/merge/conflicts`) - Conflict resolution +5. **Time Travel** (`/time-travel`) - Historical queries (asOf) +6. **Dataset Manager** (`/datasets`) - Multi-dataset management +7. **Batch Operations** (`/batch`) - Atomic batch operations + +### 3.2 Navigation Pattern + +**Primary**: Horizontal tabs (Carbon ``) +**Secondary**: Contextual sidebars (branches/tags in Version Control, graphs in Graph Explorer) +**Tertiary**: Modals and panels (prefix manager, create dataset wizard) + +### 3.3 Routing + +``` +/ โ†’ /query (default) +/query โ†’ Query Workbench +/graphs โ†’ Graph Explorer +/version โ†’ Version Control +/merge/conflicts โ†’ Merge Conflicts +/time-travel โ†’ Time Travel Queries +/datasets โ†’ Dataset Manager +/batch โ†’ Batch Operations +/settings โ†’ Settings +``` + +**Query Parameters** (global): +- `dataset={name}` - Current dataset +- `branch={name}` - Current branch +- `commit={id}` - Selected commit +- `asOf={timestamp}` - Time-travel timestamp + +--- + +## 4. UI Mockups + +### 4.1 Query Workbench (Complete - 5,500 words) + +**Layout**: Split-pane (editor top, results bottom) + +**Key Features**: +- Multi-tab query editor (CodeMirror with SPARQL syntax) +- Virtual scrolling results table (10k+ rows) +- Branch/asOf selector for time-travel queries +- Prefix manager modal +- Query history sidebar +- Export (CSV, JSON, Turtle, etc.) + +**State Management**: +- Local: Tabs, query text, results +- Global: Current dataset, author +- Persistence: localStorage (auto-save every 5s) + +### 4.2 Graph Explorer + +**Layout**: Sidebar (graph list) + Main (graph viewer) + +**Key Features**: +- Named graph list (sidebar, collapsible tree) +- Triple table/tree view (CodeMirror or Carbon DataTable) +- Upload graph (file uploader + drag-drop) +- GSP operations (PUT, POST, DELETE, PATCH) +- Filter triples by subject/predicate/object + +### 4.3 Version Control (Complete - 3,000 words) + +**Layout**: Three-pane (sidebar | graph | details) + +**Key Features**: +- **Sidebar**: Branches (local/remote), tags, filter input +- **Graph**: Colored DAG visualization (D3.js or Cytoscape.js) + - Commit nodes with avatars + - Branch lines (colored, 3px width) + - Collapsible merge commits + - Drag-and-drop for merge/cherry-pick +- **Details**: Commit metadata, RDF Patch viewer, actions +- **Modals**: Create branch, merge configuration, cherry-pick + +**Interactions**: +- Click commit โ†’ show details +- Right-click commit โ†’ context menu (cherry-pick, revert, reset) +- Double-click commit โ†’ time-travel to that commit +- Drag branch โ†’ merge/rebase + +### 4.4 Merge & Conflicts + +**Layout**: Sidebar (conflict list) + Main (3-pane resolver) + +**Key Features**: +- **Conflict Summary**: "12 graphs in conflict, 45 triples" +- **Conflict List**: Accordion (graph-by-graph) +- **3-Pane Resolver**: Base | Ours | Theirs + - RDF syntax highlighting + - One-click resolution buttons + - Manual editing +- **Navigation**: Prev/Next conflict buttons +- **Graph-Level Resolution**: "Accept Ours for all in graph" + +### 4.5 Time Travel + +**Layout**: Query Workbench + Timeline controls + +**Key Features**: +- **asOf Selector**: Date/time picker + commit selector +- **Timeline Slider**: Visual timeline with commits +- **Comparison Mode**: Side-by-side results (time A vs time B) +- **Query Indicator**: "Results as of 2025-11-10 10:30:00" + +**Architecture Note**: Time travel queries execute at specific commits. +The asOf selector finds the commit at or before the specified timestamp. +The timeline visualization shows commit history chronologically - +essentially the same data as the Version Control view's commit graph, +but laid out by time instead of by branch structure. + +**Design Decision**: We maintain separate views because: +- Version Control focuses on branch operations (merge, rebase, etc.) +- Time Travel focuses on historical query analysis (animation, comparison) + +Alternative: These could be merged into a single view with visualization modes. + +### 4.6 Dataset Manager + +**Layout**: Table view + +**Key Features**: +- **Dataset Table**: Name, description, main branch, created date, health +- **Create Wizard**: Step-by-step (name, description, Kafka config, initial graph) +- **Health Dashboard**: Kafka topic status, partition count, consumer lag +- **Actions**: Delete dataset (confirmation required) + +### 4.7 Batch Operations + +**Layout**: Operation builder (table + preview) + +**Key Features**: +- **Operation List**: Table with type, graph, content, order +- **Add Operation**: Modal (type selector, graph input, content editor) +- **Reorder**: Drag handles or up/down buttons +- **Mode Selector**: Single-commit vs multi-commit +- **Preview**: Shows resulting RDF Patch +- **Execute**: Confirmation modal + +--- + +## 5. Visual Design System + +### 5.1 Color Palette (Carbon + Semantic) + +**Carbon Themes**: White, G10 (default), G90, G100 + +**Semantic Colors**: +- **Branch Colors** (for graph): + - main: Blue (#0f62fe) + - dev: Green (#24a148) + - feature/*: Orange (#ff832b) + - bugfix/*: Red (#da1e28) + - release/*: Purple (#8a3ffc) +- **Diff Colors**: + - Added: Green (#24a148) + - Deleted: Red (#da1e28) + - Modified: Yellow (#f1c21b) +- **Status Colors**: + - Success: Green (#24a148) + - Warning: Yellow (#f1c21b) + - Error: Red (#da1e28) + - Info: Blue (#0f62fe) + +### 5.2 Typography + +- **Body**: IBM Plex Sans (14px regular) +- **Code**: IBM Plex Mono (14px regular) +- **Headings**: IBM Plex Sans (H1: 24px, H2: 20px, H3: 16px) +- **Captions**: IBM Plex Sans (12px) + +### 5.3 Iconography + +**Carbon Icons** (carbon-icons-svelte): +- Branch: `` icon +- Tag: `` icon +- Commit: Custom dot/circle SVG (10px diameter) +- Merge: Converging arrows +- Conflict: `` icon +- Ahead/Behind: `` / `` +- Settings: `` icon + +### 5.4 Spacing (8px Grid) + +- **Padding**: 8px, 16px, 24px, 32px +- **Margins**: 8px, 16px, 24px, 32px +- **Component Spacing**: 16px between components +- **Sidebar Width**: 240px (adjustable) +- **Commit Graph Row Height**: 32px (compact: 24px) + +--- + +## 6. Component Architecture + +### 6.1 Component Tree + +``` +App +โ”œโ”€โ”€ Header (Carbon) +โ”‚ โ”œโ”€โ”€ Logo +โ”‚ โ”œโ”€โ”€ PrimaryNav (tabs) +โ”‚ โ”œโ”€โ”€ DatasetSelector (Dropdown) +โ”‚ โ””โ”€โ”€ AuthorSelector (ComboBox) +โ”‚ +โ”œโ”€โ”€ Router (client-side) +โ”‚ โ”œโ”€โ”€ QueryWorkbench +โ”‚ โ”‚ โ”œโ”€โ”€ QueryEditor (CHUCC-SQUI) +โ”‚ โ”‚ โ”œโ”€โ”€ ResultsTable (CHUCC-SQUI) +โ”‚ โ”‚ โ”œโ”€โ”€ PrefixManager (modal) +โ”‚ โ”‚ โ””โ”€โ”€ QueryHistory (sidebar) +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ GraphExplorer +โ”‚ โ”‚ โ”œโ”€โ”€ GraphList (sidebar) +โ”‚ โ”‚ โ”œโ”€โ”€ GraphViewer (CHUCC-SQUI) +โ”‚ โ”‚ โ””โ”€โ”€ GraphUploader (modal) +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ VersionControl +โ”‚ โ”‚ โ”œโ”€โ”€ BranchSidebar +โ”‚ โ”‚ โ”œโ”€โ”€ CommitGraph (D3.js/Cytoscape.js) +โ”‚ โ”‚ โ”œโ”€โ”€ CommitDetails (bottom panel) +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ RdfPatchViewer (CHUCC-SQUI) +โ”‚ โ”‚ โ””โ”€โ”€ Modals (CreateBranch, MergeConfig) +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ MergeConflicts +โ”‚ โ”‚ โ”œโ”€โ”€ ConflictSidebar +โ”‚ โ”‚ โ””โ”€โ”€ ConflictResolver (3-pane) +โ”‚ โ”‚ โ””โ”€โ”€ RdfDiffViewer (CHUCC-SQUI) +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ TimeTravelQuery +โ”‚ โ”‚ โ”œโ”€โ”€ TimelineSlider +โ”‚ โ”‚ โ”œโ”€โ”€ AsOfPicker +โ”‚ โ”‚ โ””โ”€โ”€ QueryWorkbench (enhanced) +โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€ DatasetManager +โ”‚ โ”‚ โ”œโ”€โ”€ DatasetTable +โ”‚ โ”‚ โ”œโ”€โ”€ CreateDatasetWizard (modal) +โ”‚ โ”‚ โ””โ”€โ”€ HealthDashboard +โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€ BatchOperations +โ”‚ โ”œโ”€โ”€ OperationBuilder +โ”‚ โ”œโ”€โ”€ OperationList +โ”‚ โ””โ”€โ”€ BatchPreview +โ”‚ +โ”œโ”€โ”€ Footer +โ”‚ โ”œโ”€โ”€ StatusBar (dataset, branch, author) +โ”‚ โ””โ”€โ”€ NotificationArea (toasts) +โ”‚ +โ””โ”€โ”€ GlobalModals + โ”œโ”€โ”€ QuickLaunch (Ctrl+P) + โ””โ”€โ”€ Settings +``` + +### 6.2 State Management (Svelte Stores) + +**Global Stores**: +```typescript +// appStore.ts +export const appStore = writable({ + currentDataset: 'default', + currentAuthor: 'Alice ', + availableDatasets: string[], + theme: 'g10', +}); + +// queryStore.ts +export const queryStore = writable({ + tabs: QueryTab[], + activeTabId: string, + history: QueryHistoryItem[], + savedQueries: SavedQuery[], +}); + +// versionStore.ts +export const versionStore = writable({ + commits: Commit[], + branches: Branch[], + tags: Tag[], + selectedCommitId: string | null, + collapsedMerges: Set, +}); +``` + +**Service Layer** (API calls): +```typescript +// services/versionControlService.ts +export class VersionControlService { + async getCommits(dataset: string, branch?: string): Promise { ... } + async merge(dataset: string, from: string, into: string, strategy: MergeStrategy): Promise { ... } + async cherryPick(dataset: string, commitId: string, onto: string): Promise { ... } + async createBranch(dataset: string, name: string, base: string): Promise { ... } + // ... +} +``` + +--- + +## 7. Interaction Flows + +### 7.1 Execute SPARQL Query with Time Travel + +1. User navigates to Query Workbench (`/query`) +2. User selects dataset ("my-dataset") from header dropdown +3. User selects branch ("main") from editor toolbar +4. User clicks "asOf: Latest" โ†’ selects "Specific Date/Time" +5. Date picker opens, user selects "2025-11-10 10:00:00" +6. User types SPARQL query in editor +7. User presses Ctrl+Enter to execute +8. Query sent: `POST /query?dataset=my-dataset&branch=main&asOf=2025-11-10T10:00:00Z` +9. Results appear in table (with notification: "Results as of 2025-11-10 10:00:00") +10. User clicks export dropdown โ†’ "Download as CSV" + +### 7.2 Create Branch and Commit Changes + +1. User navigates to Version Control (`/version`) +2. User sees commit graph with current branch "main" +3. User clicks "Create Branch" button +4. Modal opens: User enters "feature/new-data", selects base "HEAD", checks "Checkout after creation" +5. User clicks "Create Branch" โ†’ `POST /version/refs/branches?dataset=default` +6. New branch appears in sidebar (highlighted as current) +7. User navigates to Graph Explorer (`/graphs`) +8. User selects "default" graph from sidebar +9. User clicks "Upload File" โ†’ uploads Turtle file +10. Modal shows: "Upload will create a commit. Enter commit message." +11. User enters message: "Add new user data" +12. User clicks "Upload" โ†’ `PUT /graphs/default` with file content +13. Server returns `202 Accepted` with commit ID +14. Toast notification: "Commit created: 019abc..." +15. User navigates back to Version Control โ†’ sees new commit in graph + +### 7.3 Merge Branches with Conflict Resolution + +1. User in Version Control view, branch "main" +2. User clicks "Merge..." dropdown โ†’ "Merge Branch" +3. Modal opens: From "feature/new-data", Into "main", Strategy "three-way" +4. User clicks "Merge" โ†’ `POST /version/merge?dataset=default` +5. Server returns `409 Conflict` with conflict data +6. User automatically redirected to `/merge/conflicts?merge={id}` +7. Conflict summary shows: "5 graphs in conflict, 12 triples" +8. User expands "default" graph in sidebar +9. 3-pane resolver shows: Base | Ours | Theirs +10. User sees conflicting triple: `ex:Alice ex:age "30"` (Ours) vs `"31"` (Theirs) +11. User clicks "Accept Theirs" button +12. Conflict resolved, UI updates (green checkmark) +13. User navigates to next conflict (4 remaining) +14. After resolving all, "Complete Merge" button enabled +15. User clicks "Complete Merge" โ†’ `POST /version/merge` (with resolution data) +16. Server returns `200 OK` with merge commit ID +17. User redirected to Version Control โ†’ sees merge commit in graph + +### 7.4 Cherry-Pick Commit + +1. User in Version Control view, sees commit "019abc..." on "feature/auth" branch +2. User right-clicks commit โ†’ "Cherry-pick to..." +3. Submenu shows branches: main, dev +4. User clicks "main" +5. `POST /version/cherry-pick?dataset=default` (body: `{commit: "019abc", onto: "main"}`) +6. **Success**: Toast "Commit cherry-picked to main", graph updates with new commit +7. **Conflict**: Redirect to conflict resolver (same as merge flow) + +--- + +## 8. Accessibility (WCAG 2.1 AA) + +### 8.1 Keyboard Navigation + +**Global Shortcuts**: +- `Ctrl+P` / `โŒ˜+P`: Quick Launch +- `Ctrl+1` ... `Ctrl+7`: Jump to primary nav tab +- `Ctrl+K` / `โŒ˜+K`: Focus dataset selector +- `Esc`: Close modal/panel + +**View-Specific Shortcuts**: +- Query Workbench: `Ctrl+Enter` (execute), `Ctrl+S` (save) +- Version Control: `โ†‘/โ†“` (navigate commits), `Ctrl+M` (merge) +- Merge Conflicts: `Ctrl+O` (accept ours), `Ctrl+T` (accept theirs), `Ctrl+]` (next conflict) + +### 8.2 Screen Reader Support + +- ARIA labels on all interactive elements +- ARIA landmarks (`