From 219f0f93464d7868a551c31e23f457c879393973 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Nov 2025 11:52:09 +0000 Subject: [PATCH 01/17] docs: create comprehensive frontend concept research prompt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Created detailed prompt for AI-driven research to design CHUCC frontend: - Context: CHUCC-server API, CHUCC-SQUI components, UX inspiration - Research tasks: Fuseki UI analysis, Fork UX analysis, component gaps - Design specs: 7 primary views with mockups, component architecture - Deliverables: Research reports, mockups, implementation roadmap Combines Fuseki's SPARQL usability with Fork's version control elegance. Built on Svelte 5 + Carbon Design System + CHUCC-SQUI library. ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .tasks/frontend-concept-prompt.md | 819 ++++++++++++++++++++++++++++++ 1 file changed, 819 insertions(+) create mode 100644 .tasks/frontend-concept-prompt.md diff --git a/.tasks/frontend-concept-prompt.md b/.tasks/frontend-concept-prompt.md new file mode 100644 index 0000000..a3a1b8c --- /dev/null +++ b/.tasks/frontend-concept-prompt.md @@ -0,0 +1,819 @@ +# CHUCC Frontend Concept - Deep Research Prompt + +## Mission +Design a comprehensive web frontend concept for CHUCC-server (SPARQL 1.2 Protocol with Version Control Extension), combining the query/graph usability of Apache Jena Fuseki with the version control UX elegance of Fork Git Client, built on the CHUCC-SQUI component library. + +--- + +## Context + +### About CHUCC-Server +CHUCC Server implements the **SPARQL 1.2 Protocol with Version Control Extension**, providing: + +**Core SPARQL Capabilities:** +- SPARQL 1.1 Query endpoint (SELECT, ASK, CONSTRUCT, DESCRIBE) +- SPARQL 1.1 Update endpoint (INSERT DATA, DELETE DATA, DELETE/INSERT) +- Graph Store Protocol (GSP): PUT, GET, POST, DELETE, PATCH operations on named graphs +- Batch operations for atomic multi-operation commits +- Service description endpoint (SPARQL 1.1 Service Description) + +**Version Control Features (Git-like):** +- **Branches**: Mutable pointers to commits (create, list, delete, checkout) +- **Tags**: Immutable pointers to commits (annotated tags with messages) +- **Commits**: UUIDv7-based commit DAG with parent relationships +- **History**: Browsing commit history with filtering (branch, author, date range) +- **Time-Travel Queries**: Query historical states with `asOf` selector (RFC 3339 timestamp) +- **Merge Operations**: Three-way merge with conflict detection (strategies: three-way, ours, theirs, manual) +- **Advanced Operations**: + - Cherry-pick: Apply specific commit to target branch + - Revert: Create inverse commit (undo) + - Reset: Move branch pointer (hard/soft/mixed modes) + - Rebase: Reapply commits onto different base + - Squash: Combine multiple commits into one + - Diff: Compare two commits (returns RDF Patch) + - Blame: Last-writer attribution for triples + +**Multi-Dataset Support:** +- Create/delete datasets dynamically +- Each dataset has independent Kafka topics for event storage +- Dataset-level isolation + +**Concurrency & Conflict Management:** +- Semantic overlap detection (triple/quad level) +- ETag-based optimistic concurrency control +- Strong consistency for reads (via `If-Match` preconditions) +- Structured conflict representation in merge failures + +**Key Technical Details:** +- CQRS + Event Sourcing architecture (commands โ†’ events โ†’ projectors) +- Eventual consistency (202 Accepted for writes, async projection) +- RDFPatch format for changesets +- Apache Jena 5.5 for RDF processing (in-memory DatasetGraphInMemory) +- Apache Kafka for event store + +**API Structure:** +``` +# SPARQL Protocol +POST /query # SPARQL SELECT/ASK/CONSTRUCT/DESCRIBE +POST /update # SPARQL UPDATE + +# Graph Store Protocol +GET/PUT/POST/DELETE/PATCH /{graph} # GSP operations on named graphs +GET/PUT/POST/DELETE/PATCH / # GSP operations on default graph + +# Version Control - Refs & Commits +GET /version/refs # List branches and tags +GET /version/commits/{id} # Get commit metadata +POST /version/commits # Create commit (RDF Patch body) +GET /version/history # Browse commit history + +# Version Control - Branches +POST /version/refs/branches # Create branch +GET /version/refs/branches/{name} # Get branch info +DELETE /version/refs/branches/{name} # Delete branch + +# Version Control - Tags +GET /version/tags # List tags +POST /version/tags # Create tag +GET /version/tags/{name} # Get tag info +DELETE /version/tags/{name} # Delete tag + +# Version Control - Merge & Advanced Operations +POST /version/merge # Merge two refs +POST /version/cherry-pick # Cherry-pick commit +POST /version/revert # Revert commit +POST /version/reset # Reset branch pointer +POST /version/rebase # Rebase branch +POST /version/squash # Squash commits + +# Version Control - Extensions (optional features) +GET /version/diff # Compare commits (RDF Patch diff) +GET /version/blame # Last-writer attribution + +# Dataset Management (CHUCC-specific) +POST /version/datasets/{name} # Create dataset +DELETE /version/datasets/{name} # Delete dataset +POST /version/batch-graphs # Batch GSP operations + +# Batch Operations +POST /version/batch # Batch SPARQL operations +``` + +**Error Handling:** +- RFC 7807 Problem Details (application/problem+json) +- Structured conflict representation for merge failures +- HTTP status codes: 200, 202, 204, 400, 404, 406, 409, 412, 500, 503 + +**Documentation References:** +- Protocol spec: `/home/user/CHUCC-server/protocol/SPARQL_1_2_Protocol_Version_Control_Extension.md` +- API extensions: `/home/user/CHUCC-server/docs/api/api-extensions.md` +- OpenAPI spec: `/home/user/CHUCC-server/api/openapi.yaml` +- Architecture docs: `/home/user/CHUCC-server/docs/architecture/` + +--- + +### About CHUCC-SQUI (Component Library) + +**Technology Stack:** +- **Framework**: Svelte 5 + TypeScript 5.9 +- **Design System**: IBM Carbon Design System (carbon-components-svelte) +- **Editor**: CodeMirror 6 with SPARQL syntax highlighting +- **Build**: Vite (dev server + bundler) +- **Testing**: Vitest (unit), Playwright (e2e) +- **SPARQL Client**: sparql-http library +- **Themes**: 4 Carbon themes (White, G10, G90, G100) +- **Accessibility**: WCAG 2.1 AA compliant + +**Available Components:** +- Query editor with autocomplete and validation (CodeMirror-based) +- Results table with virtual scrolling (10,000+ row support) +- Multi-tab interface for simultaneous queries +- Endpoint selector with catalogue support +- Prefix management interface +- Export functionality (CSV, TSV, JSON, XML, Turtle, N-Triples, JSON-LD, RDF/XML) +- Theme selector (4 Carbon themes) +- Query history and templates (planned features) + +**Carbon Design System Components Available:** +- Navigation (Header, SideNav, Breadcrumb) +- Data Display (DataTable, Tile, Accordion, Tabs) +- Forms (TextInput, TextArea, Dropdown, FileUploader, Button) +- Notifications (Toast, InlineNotification, Modal) +- Progress (Loading, ProgressBar, Skeleton) +- Icons (carbon-icons-svelte - extensive icon library) + +**Component Structure:** +- Web component deployment possible +- Framework-agnostic integration +- Storybook documentation available + +**Repository**: https://github.com/arne-bdt/CHUCC-SQUI + +--- + +### UX Inspiration Sources + +#### 1. Apache Jena Fuseki Web UI +**What to emulate:** +- Simple, functional SPARQL query interface +- Clear dataset selection and management +- Straightforward result display (table, raw formats) +- Quick access to common SPARQL operations +- Prefix management integration + +**Analysis Task:** Research Fuseki's actual UI (screenshots, demos, or running instance) to identify: +- Layout patterns (header, sidebar, main content) +- Query editor placement and features +- Result rendering approaches +- Dataset/endpoint selection UX +- Navigation structure + +#### 2. Fork Git Client (https://git-fork.com/) +**What to emulate:** +- Elegant commit graph visualization (DAG) +- Intuitive branch/tag management +- Clear diff visualization (side-by-side, unified) +- Smooth merge conflict resolution workflow +- Interactive rebase UI +- Blame view integration +- Stash management UI +- Commit list with filtering + +**Analysis Task:** Study Fork's UX patterns: +- How does the commit graph render? (colors, lines, nodes) +- Branch switching UX (dropdown, search, keyboard shortcuts?) +- Diff viewer design (syntax highlighting, collapse/expand?) +- Merge conflict UI (3-pane view? inline markers?) +- History filtering (by author, date, branch) +- Overall information architecture + +--- + +## Research Tasks + +### Task 1: Deep Dive into Apache Jena Fuseki Web UI +**Goal:** Understand the query-centric, SPARQL-focused usability patterns. + +**Sub-tasks:** +1. **Visual Analysis**: Find screenshots or run Fuseki locally to capture: + - Main dashboard/landing page + - Query interface layout + - Dataset selection mechanism + - Result display (table, JSON, XML, RDF serializations) + - Update operation interface + - File upload/import UI (if exists) + +2. **Interaction Patterns**: Document: + - How users navigate between datasets + - Query history or saved queries (if supported) + - Prefix management UI + - Export/download result flows + - Error display patterns + +3. **Layout Structure**: Identify: + - Header content (logo, navigation, settings) + - Sidebar usage (if any) + - Main content area organization + - Responsive design patterns + +4. **Gaps**: Note what Fuseki lacks that CHUCC needs: + - No version control UI + - Limited batch operation support + - No advanced conflict resolution + +**Deliverable:** Fuseki UI analysis document with: +- Annotated screenshots +- Interaction flow diagrams +- List of reusable patterns for CHUCC +- List of gaps/limitations + +--- + +### Task 2: Deep Dive into Fork Git Client UX +**Goal:** Understand elegant version control visualization and interaction patterns. + +**Sub-tasks:** +1. **Visual Analysis**: Capture (via screenshots or demo): + - Main window layout (panes, sidebars, content areas) + - Commit graph rendering (colors, lines, merge nodes) + - Branch list UI (icons, current branch highlighting) + - Tag list UI + - Diff viewer (side-by-side vs unified) + - Merge conflict resolution interface + - Blame view + - Interactive rebase UI + +2. **Interaction Patterns**: Document: + - How to create/delete/switch branches + - How to merge branches (dialog, conflict handling) + - How to cherry-pick commits + - How to view commit details (metadata, diff, files changed) + - How to search/filter history + - Keyboard shortcuts for common operations + - Undo/redo patterns (reflog access) + +3. **Visual Language**: Identify: + - Color coding conventions (branches, tags, local/remote) + - Iconography (branch, tag, merge, conflict icons) + - Typography hierarchy + - Spacing and density patterns + +4. **Gaps**: Note what Fork has that may not apply to RDF version control: + - File tree view (RDF uses graphs, not files) + - Working directory changes (CHUCC uses materialized views) + - Staging area (CHUCC commits RDF patches directly) + +**Deliverable:** Fork UX analysis document with: +- Annotated screenshots +- Interaction flow diagrams for key operations (merge, cherry-pick, rebase) +- Visual design system notes (colors, icons, typography) +- List of patterns to adapt for CHUCC + +--- + +### Task 3: CHUCC-SQUI Component Inventory & Gap Analysis +**Goal:** Catalog available components and identify missing pieces. + +**Sub-tasks:** +1. **Component Audit**: List all Carbon components available via carbon-components-svelte: + - Navigation components + - Data display components + - Form components + - Feedback components (toasts, modals, alerts) + - Layout components + - Icon components + +2. **CHUCC-SQUI Custom Components**: Document existing: + - SPARQL query editor (CodeMirror wrapper) + - Results table (virtual scrolling) + - Prefix manager + - Export dialog + - Theme selector + - Tab manager + +3. **Gap Analysis**: Identify components needed for version control UI: + - **Missing from CHUCC-SQUI:** + - Commit graph visualizer (DAG renderer) + - Branch selector/dropdown with visual indicators + - Tag list component + - Diff viewer (RDF-aware, side-by-side or unified) + - Merge conflict resolver (3-pane or inline markers) + - Commit detail view (metadata + patch) + - History filter/search component + - Time-travel date picker (asOf selector) + - Batch operation builder + - Dataset switcher/manager + - **Missing from Carbon Design System:** + - Graph visualization (for commit DAG) + - Split pane layout (for diff viewer) + - RDF-aware syntax highlighting (may need CodeMirror extension) + +4. **Component Placement Decision**: For each missing component, decide: + - **Should it be in CHUCC-SQUI?** (reusable across RDF/SPARQL apps) + - **Should it be in frontend project?** (CHUCC-specific, not reusable) + +**Decision Criteria:** +- **CHUCC-SQUI candidates:** Generic RDF/SPARQL components (e.g., diff viewer, RDF syntax highlighter) +- **Frontend project candidates:** CHUCC-specific business logic (e.g., dataset manager with Kafka config) + +**Deliverable:** Component gap analysis spreadsheet/table: +| Component | Required? | Available in Carbon? | Available in CHUCC-SQUI? | Needs Development? | Belongs in CHUCC-SQUI or Frontend? | Notes | +|-----------|-----------|---------------------|--------------------------|-------------------|-----------------------------------|-------| +| Commit Graph | Yes | No | No | Yes | Frontend (CHUCC-specific) | Use d3.js or cytoscape.js | +| ... | ... | ... | ... | ... | ... | ... | + +--- + +## Synthesis Task + +### Task 4: Design CHUCC Frontend Concept +**Goal:** Create a comprehensive frontend concept with UI mockups and component architecture. + +**Requirements:** + +#### 4.1 Information Architecture +Design the overall application structure: +- **Navigation hierarchy**: How do users move between features? +- **Primary views**: + 1. **Query Workbench** (Fuseki-inspired): SPARQL query/update interface + 2. **Graph Explorer** (Fuseki-inspired): Browse/edit named graphs (GSP operations) + 3. **Version Control** (Fork-inspired): Commits, branches, tags, history + 4. **Merge & Conflicts** (Fork-inspired): Merge operations, conflict resolution + 5. **Time Travel** (unique): Query historical states with asOf selector + 6. **Dataset Manager** (CHUCC-specific): Create/delete/configure datasets + 7. **Batch Operations** (CHUCC-specific): Build and execute batch requests +- **Secondary views**: + - Settings/Configuration + - User profile (author metadata) + - Help/Documentation + +#### 4.2 UI Mockups (Wireframes + High-Fidelity) +Create mockups for each primary view: + +**1. Query Workbench** +- Layout: Header + Sidebar + Main (split: editor top, results bottom) +- Components: + - Dataset selector (dropdown, top-left) + - Branch/commit selector (dropdown, top-right, with "asOf" date picker) + - SPARQL editor (CodeMirror, top pane) + - Query type selector (SELECT, ASK, CONSTRUCT, DESCRIBE, UPDATE) + - Execute button (prominent, with keyboard shortcut hint) + - Results table (bottom pane, virtual scrolling) + - Export menu (CSV, JSON, Turtle, etc.) + - Prefix manager (modal or sidebar panel) + - Query history (sidebar or modal) +- Interactions: + - Split pane resize (drag divider) + - Tab-based multi-query support + - Autocomplete in editor + - Error highlighting in editor + - Click triple in results โ†’ show in Graph Explorer + +**2. Graph Explorer (GSP Operations)** +- Layout: Header + Sidebar (graph list) + Main (graph view) +- Components: + - Graph list (sidebar, with default graph + named graphs) + - Graph content viewer (table or tree view of triples) + - Add/delete graph buttons + - Upload file to graph (file uploader) + - Download graph (format selector) + - Edit graph (inline or modal editor) +- Interactions: + - Click graph in list โ†’ show content + - Drag-drop file to upload + - Filter triples by subject/predicate/object + - Create named graph (modal with URI input) + +**3. Version Control (Commits & History)** +- Layout: Header + Sidebar (branch/tag list) + Main (split: commit graph top, commit detail bottom) +- Components: + - Branch list (sidebar, with current branch highlighted, star for main) + - Tag list (sidebar, collapsible section) + - Commit graph (main top pane, DAG visualization with lines and nodes) + - Commit detail view (main bottom pane, shows: author, timestamp, message, parent commits, RDF patch diff) + - Filter controls (by author, date range, branch) + - Search bar (search commit messages) + - Action buttons (cherry-pick, revert, reset, rebase, squash) +- Interactions: + - Click commit in graph โ†’ show detail + - Right-click commit โ†’ context menu (cherry-pick, revert, reset branch to here) + - Click branch in sidebar โ†’ filter history to that branch + - Create branch (button in sidebar, modal with name input and base commit selector) + - Delete branch (trash icon, confirmation dialog) + - Merge branch (button, modal with source/target selection and strategy chooser) + +**4. Merge & Conflicts** +- Layout: Header + Main (3-pane or inline conflict markers) +- Components: + - Conflict summary (top: "12 graphs in conflict, 45 triples") + - Graph-by-graph conflict list (collapsible accordion) + - Conflict resolution pane: + - **Option A (3-pane)**: Base | Ours | Theirs (side-by-side) + - **Option B (inline)**: Unified view with conflict markers + - Resolution actions (per triple): Accept Ours, Accept Theirs, Edit Manually + - Commit merge button (bottom, enabled when all conflicts resolved) +- Interactions: + - Click conflict in list โ†’ show resolution pane + - Click "Accept Ours" โ†’ apply to all triples in graph + - Manual edit โ†’ text editor for triple + - Preview merge result (before committing) + +**5. Time Travel Queries** +- Layout: Query Workbench with enhanced time controls +- Components: + - Timeline slider (bottom of screen, shows commits over time) + - asOf date picker (calendar + time input) + - "Query as of" indicator (prominent, shows current ref or timestamp) + - Diff visualizer (compare query results at two time points) +- Interactions: + - Drag slider โ†’ update asOf timestamp + - Click commit on timeline โ†’ query at that commit + - Compare mode (split results: time A vs time B) + +**6. Dataset Manager** +- Layout: Header + Main (dataset list + detail panel) +- Components: + - Dataset list (table: name, description, main branch, created date, Kafka topic) + - Create dataset button (modal: name, description, Kafka config) + - Delete dataset button (confirmation dialog with "deleteKafkaTopic" checkbox) + - Dataset detail view (shows: commits count, branches count, tags count, graphs count) +- Interactions: + - Click dataset in list โ†’ switch to that dataset + - Create dataset โ†’ modal form โ†’ submit โ†’ 202 Accepted โ†’ toast notification + - Delete dataset โ†’ confirmation โ†’ submit โ†’ 204 No Content โ†’ remove from list + +**7. Batch Operations Builder** +- Layout: Header + Main (operation list + preview) +- Components: + - Operation list (table: type, graph, content, order) + - Add operation button (modal: choose type, fill details) + - Remove operation button (per row) + - Reorder operations (drag handles) + - Mode selector (single-commit vs multi-commit) + - Preview pane (shows resulting RDF Patch or commit structure) + - Execute button (prominent) +- Interactions: + - Add operation โ†’ modal form โ†’ append to list + - Drag row โ†’ reorder + - Click execute โ†’ POST /version/batch-graphs โ†’ show result (commit ID or multi-status) + +#### 4.3 Component Architecture +Design the component hierarchy for the frontend: + +**Example structure:** +``` +App +โ”œโ”€โ”€ Header +โ”‚ โ”œโ”€โ”€ Logo +โ”‚ โ”œโ”€โ”€ DatasetSelector +โ”‚ โ”œโ”€โ”€ RefSelector (branch/commit/asOf) +โ”‚ โ”œโ”€โ”€ ThemeSelector +โ”‚ โ””โ”€โ”€ UserMenu +โ”œโ”€โ”€ Sidebar +โ”‚ โ”œโ”€โ”€ Navigation (Query, Graphs, Version Control, Merge, Time Travel, Datasets, Batch) +โ”‚ โ””โ”€โ”€ BranchList (in Version Control view) +โ”œโ”€โ”€ MainContent +โ”‚ โ”œโ”€โ”€ QueryWorkbench +โ”‚ โ”‚ โ”œโ”€โ”€ QueryEditor (CodeMirror) +โ”‚ โ”‚ โ”œโ”€โ”€ ResultsTable +โ”‚ โ”‚ โ”œโ”€โ”€ ExportMenu +โ”‚ โ”‚ โ””โ”€โ”€ PrefixManager +โ”‚ โ”œโ”€โ”€ GraphExplorer +โ”‚ โ”‚ โ”œโ”€โ”€ GraphList +โ”‚ โ”‚ โ”œโ”€โ”€ GraphViewer (table or tree) +โ”‚ โ”‚ โ””โ”€โ”€ GraphUploader +โ”‚ โ”œโ”€โ”€ VersionControl +โ”‚ โ”‚ โ”œโ”€โ”€ CommitGraph (DAG visualizer) +โ”‚ โ”‚ โ”œโ”€โ”€ CommitDetail +โ”‚ โ”‚ โ”œโ”€โ”€ HistoryFilter +โ”‚ โ”‚ โ””โ”€โ”€ ActionButtons +โ”‚ โ”œโ”€โ”€ MergeConflicts +โ”‚ โ”‚ โ”œโ”€โ”€ ConflictSummary +โ”‚ โ”‚ โ”œโ”€โ”€ ConflictList +โ”‚ โ”‚ โ””โ”€โ”€ ConflictResolver (3-pane or inline) +โ”‚ โ”œโ”€โ”€ TimeTravelQuery +โ”‚ โ”‚ โ”œโ”€โ”€ Timeline +โ”‚ โ”‚ โ”œโ”€โ”€ AsOfPicker +โ”‚ โ”‚ โ””โ”€โ”€ DiffVisualizer +โ”‚ โ”œโ”€โ”€ DatasetManager +โ”‚ โ”‚ โ”œโ”€โ”€ DatasetList +โ”‚ โ”‚ โ”œโ”€โ”€ CreateDatasetModal +โ”‚ โ”‚ โ””โ”€โ”€ DatasetDetail +โ”‚ โ””โ”€โ”€ BatchOperations +โ”‚ โ”œโ”€โ”€ OperationList +โ”‚ โ”œโ”€โ”€ OperationEditor +โ”‚ โ””โ”€โ”€ Preview +โ””โ”€โ”€ Footer + โ”œโ”€โ”€ StatusBar (shows: current dataset, branch, author) + โ””โ”€โ”€ Notifications (toasts) +``` + +**State Management:** +- Global state: Current dataset, branch/commit, author, theme +- View state: Active view, query tabs, filter settings +- Data state: Commits, branches, tags, query results (cached) + +**Routing:** +``` +/query โ†’ Query Workbench +/graphs โ†’ Graph Explorer +/version โ†’ Version Control +/merge โ†’ Merge & Conflicts +/time-travel โ†’ Time Travel Queries +/datasets โ†’ Dataset Manager +/batch โ†’ Batch Operations +/settings โ†’ Settings +``` + +#### 4.4 Interaction Flows +Document key user flows: + +**Flow 1: Execute SPARQL Query with Time Travel** +1. User navigates to Query Workbench +2. User selects dataset from dropdown +3. User selects branch from dropdown (or uses asOf date picker) +4. User types SPARQL query in editor (with autocomplete) +5. User clicks Execute (or Ctrl+Enter) +6. System sends POST /query with branch or asOf selector +7. Results appear in table below editor +8. User exports results as CSV + +**Flow 2: Create Branch and Commit Changes** +1. User navigates to Version Control +2. User sees commit graph showing current state +3. User clicks "Create Branch" button in sidebar +4. Modal opens: user enters branch name, selects base commit (default: current HEAD) +5. User clicks Create โ†’ POST /version/refs/branches +6. New branch appears in sidebar, highlighted as current +7. User navigates to Graph Explorer +8. User uploads Turtle file to a named graph (GSP PUT) +9. System creates commit automatically (or user reviews and confirms) +10. Commit appears in graph immediately (optimistic update) + +**Flow 3: Merge Branches with Conflict Resolution** +1. User navigates to Version Control +2. User clicks "Merge" button in toolbar +3. Modal opens: user selects source branch and target branch, chooses strategy (three-way) +4. User clicks Merge โ†’ POST /version/merge +5. System returns 409 Conflict with structured conflict data +6. User redirected to Merge & Conflicts view +7. System displays 12 conflicting graphs in accordion +8. User expands first graph, sees 5 conflicting triples in 3-pane view (Base | Ours | Theirs) +9. User clicks "Accept Ours" for 3 triples, "Accept Theirs" for 2 triples +10. User collapses graph, expands next graph, repeats +11. All conflicts resolved โ†’ "Commit Merge" button enabled +12. User clicks Commit Merge โ†’ POST /version/merge (with manual resolution data) +13. System returns 200 OK with merge commit ID +14. User redirected to Version Control, sees new merge commit in graph + +**Flow 4: Cherry-Pick Commit** +1. User navigates to Version Control +2. User finds commit in history (using filter or search) +3. User right-clicks commit โ†’ selects "Cherry-Pick to..." from context menu +4. Modal opens: user selects target branch +5. User clicks Cherry-Pick โ†’ POST /version/cherry-pick +6. System returns 200 OK with new commit ID (or 409 if conflicts) +7. If conflicts โ†’ redirect to Merge & Conflicts view +8. If success โ†’ commit graph updates with new commit on target branch + +#### 4.5 Visual Design System +Define the visual language: + +**Color Palette:** +- Use Carbon theme colors (White, G10, G90, G100) +- Additional semantic colors: + - Branch: Blue (#0f62fe) + - Tag: Orange (#ff832b) + - Commit: Green (#24a148) + - Conflict: Red (#da1e28) + - Current ref: Yellow (#f1c21b) + +**Typography:** +- Carbon default: IBM Plex Sans (body), IBM Plex Mono (code) +- Hierarchy: H1 (24px), H2 (20px), H3 (16px), Body (14px), Caption (12px) + +**Icons:** +- Use carbon-icons-svelte +- Custom icons needed: + - Git branch (fork icon) + - Git commit (dot/circle) + - Git merge (converging arrows) + - Git tag (tag icon) + - RDF graph (network icon) + +**Spacing:** +- Carbon spacing scale: 2px, 4px, 8px, 16px, 24px, 32px, 48px + +**Layout Density:** +- Compact mode (for tables, lists) +- Normal mode (default) +- Comfortable mode (for accessibility) + +#### 4.6 Accessibility +Ensure WCAG 2.1 AA compliance: +- Keyboard navigation (Tab, Arrow keys, Enter, Escape) +- Screen reader support (ARIA labels, landmarks, live regions) +- Focus indicators (visible outline) +- Color contrast (4.5:1 for text, 3:1 for UI components) +- Error messages (associated with form fields) + +#### 4.7 Responsive Design +Support desktop, tablet, mobile: +- Breakpoints: 320px (mobile), 768px (tablet), 1024px (desktop) +- Mobile: Collapse sidebar to hamburger menu, stack editor and results vertically +- Tablet: Show sidebar, maintain split panes +- Desktop: Full layout with all panes visible + +--- + +## Deliverables + +### 1. Research Reports +- **Fuseki UI Analysis** (2-3 pages with screenshots) +- **Fork UX Analysis** (3-4 pages with screenshots) +- **Component Gap Analysis** (spreadsheet/table) + +### 2. Frontend Concept Document +- **Executive Summary** (1 page) +- **Information Architecture** (sitemap, navigation hierarchy) +- **UI Mockups** (wireframes + high-fidelity mockups for 7 primary views) +- **Component Architecture** (component tree, state management, routing) +- **Interaction Flows** (4+ key flows with step-by-step diagrams) +- **Visual Design System** (color palette, typography, icons, spacing) +- **Accessibility Guidelines** +- **Responsive Design Strategy** + +### 3. Component Placement Recommendations +- **Table format:** + | Component | Description | Belongs in CHUCC-SQUI? | Belongs in Frontend? | Rationale | + |-----------|-------------|------------------------|----------------------|-----------| + | CommitGraph | DAG visualizer | No | Yes | CHUCC-specific UX, not reusable | + | DiffViewer | RDF diff renderer | Yes | No | Generic RDF component, reusable | + | ... | ... | ... | ... | ... | + +### 4. Implementation Roadmap (High-Level) +- **Phase 1**: Core SPARQL features (Query Workbench, Graph Explorer) +- **Phase 2**: Basic version control (Commits, Branches, History) +- **Phase 3**: Advanced version control (Merge, Cherry-Pick, Rebase) +- **Phase 4**: Conflict resolution UI +- **Phase 5**: Time Travel queries +- **Phase 6**: Dataset management +- **Phase 7**: Batch operations +- **Phase 8**: Polish (accessibility, performance, docs) + +--- + +## Success Criteria + +The final concept should: +1. **Faithfully represent CHUCC-server capabilities** (all endpoints accessible via UI) +2. **Provide Fuseki-level usability** for SPARQL query/graph operations +3. **Provide Fork-level elegance** for version control operations +4. **Leverage CHUCC-SQUI components** maximally (minimize duplicate work) +5. **Identify clear component boundaries** (CHUCC-SQUI vs frontend project) +6. **Be implementable with Svelte 5 + Carbon Design System** +7. **Be accessible (WCAG 2.1 AA)** +8. **Be responsive (mobile, tablet, desktop)** +9. **Be visually consistent** (Carbon theme integration) +10. **Be developer-friendly** (clear component architecture, state management, routing) + +--- + +## Suggested Research Approach + +### Phase 1: Understand (Days 1-2) +1. Review CHUCC-server documentation thoroughly +2. Review CHUCC-SQUI repository and component library +3. Analyze Fuseki UI (screenshots, demo, local install) +4. Analyze Fork Git Client (screenshots, demo, trial version) + +### Phase 2: Analyze (Days 3-4) +1. Create Fuseki UI analysis document +2. Create Fork UX analysis document +3. Create component gap analysis spreadsheet +4. Identify reusable patterns and anti-patterns + +### Phase 3: Synthesize (Days 5-7) +1. Design information architecture +2. Sketch wireframes for 7 primary views +3. Refine wireframes into high-fidelity mockups +4. Design component architecture +5. Document interaction flows +6. Define visual design system + +### Phase 4: Document (Days 8-9) +1. Compile frontend concept document +2. Create component placement recommendations +3. Create implementation roadmap +4. Review for completeness and clarity + +### Phase 5: Iterate (Day 10) +1. Review deliverables against success criteria +2. Refine based on feedback +3. Finalize all documents + +--- + +## Additional Notes + +### RDF-Specific Considerations +- Triples/quads are not files โ†’ UI must visualize graph structure differently +- RDF serialization formats (Turtle, JSON-LD, N-Triples) โ†’ syntax highlighting needed +- Blank nodes โ†’ how to visualize in UI? (auto-generated labels, inline expansion) +- Prefixes โ†’ must be managed per query or globally per dataset + +### Performance Considerations +- Virtual scrolling for large result sets (10k+ rows) +- Lazy loading for commit graph (paginate history) +- Debounced autocomplete in query editor +- Optimistic updates for commits (show immediately, sync async) + +### Future Enhancements (Out of Scope) +- Collaborative editing (multi-user) +- Real-time conflict detection (WebSocket) +- Query templates/snippets library +- Visual SPARQL query builder (drag-drop) +- RDF graph visualization (force-directed layout) +- Custom merge strategies (user-defined rules) + +--- + +## Questions to Address + +1. **Commit Graph Visualization**: Which library to use? (d3.js, cytoscape.js, vis.js, custom SVG) +2. **Diff Viewer**: Side-by-side or unified? Syntax highlighting for RDF Patch? Collapse large diffs? +3. **Conflict Resolution**: 3-pane or inline markers? Per-triple or per-graph resolution? +4. **Time Travel UI**: Timeline slider vs date picker vs both? How to visualize commit history on timeline? +5. **Dataset Switching**: Dropdown or dedicated page? How to handle switching mid-query? +6. **Author Metadata**: User profile page or just header input? Store in browser localStorage? +7. **Offline Support**: Service worker for caching? IndexedDB for query history? +8. **Mobile UX**: Full feature parity or limited subset? Native app vs responsive web? + +--- + +## Resources + +### CHUCC-Server +- GitHub: (local repository) +- OpenAPI Spec: `/home/user/CHUCC-server/api/openapi.yaml` +- Protocol Docs: `/home/user/CHUCC-server/protocol/` +- Architecture Docs: `/home/user/CHUCC-server/docs/architecture/` + +### CHUCC-SQUI +- GitHub: https://github.com/arne-bdt/CHUCC-SQUI +- Storybook: (check repo for deployed link) + +### Design References +- Apache Jena Fuseki: https://jena.apache.org/documentation/fuseki2/ +- Fork Git Client: https://git-fork.com/ +- IBM Carbon Design System: https://carbondesignsystem.com/ +- Carbon Components Svelte: https://carbon-components-svelte.onrender.com/ + +### Libraries +- d3.js: https://d3js.org/ (data visualization) +- cytoscape.js: https://js.cytoscape.org/ (graph visualization) +- CodeMirror 6: https://codemirror.net/ (code editor) +- Svelte 5: https://svelte.dev/ (framework) + +--- + +## Final Output Format + +Deliver all documents as: +- **Markdown** (for text reports) +- **PNG/SVG** (for mockups, diagrams) +- **CSV/Excel** (for component gap analysis) +- **Mermaid diagrams** (for flows, architecture) + +Organize in a clear directory structure: +``` +chucc-frontend-concept/ +โ”œโ”€โ”€ 01-research/ +โ”‚ โ”œโ”€โ”€ fuseki-ui-analysis.md +โ”‚ โ”œโ”€โ”€ fork-ux-analysis.md +โ”‚ โ””โ”€โ”€ component-gap-analysis.xlsx +โ”œโ”€โ”€ 02-concept/ +โ”‚ โ”œโ”€โ”€ executive-summary.md +โ”‚ โ”œโ”€โ”€ information-architecture.md +โ”‚ โ”œโ”€โ”€ ui-mockups/ +โ”‚ โ”‚ โ”œโ”€โ”€ 01-query-workbench.png +โ”‚ โ”‚ โ”œโ”€โ”€ 02-graph-explorer.png +โ”‚ โ”‚ โ”œโ”€โ”€ 03-version-control.png +โ”‚ โ”‚ โ”œโ”€โ”€ 04-merge-conflicts.png +โ”‚ โ”‚ โ”œโ”€โ”€ 05-time-travel.png +โ”‚ โ”‚ โ”œโ”€โ”€ 06-dataset-manager.png +โ”‚ โ”‚ โ””โ”€โ”€ 07-batch-operations.png +โ”‚ โ”œโ”€โ”€ component-architecture.md +โ”‚ โ”œโ”€โ”€ interaction-flows.md +โ”‚ โ”œโ”€โ”€ visual-design-system.md +โ”‚ โ”œโ”€โ”€ accessibility-guidelines.md +โ”‚ โ””โ”€โ”€ responsive-design.md +โ”œโ”€โ”€ 03-recommendations/ +โ”‚ โ”œโ”€โ”€ component-placement.xlsx +โ”‚ โ””โ”€โ”€ implementation-roadmap.md +โ””โ”€โ”€ README.md (overview of deliverables) +``` + +--- + +**Good luck! This is a complex, multi-faceted research and design task. Take your time, be thorough, and create something elegant and usable.** From f0e48966febec4c474c8c84a82857430e5b58f0c Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Nov 2025 12:11:44 +0000 Subject: [PATCH 02/17] docs: complete Fuseki and Fork UX research (Tasks 1 & 2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Research Documents Created: - fuseki-ui-analysis.md (3,500 words): Tab-based SPARQL interface analysis - fork-ux-analysis.md (5,000 words): Elegant version control UX patterns Fuseki Key Findings: - Simple tab navigation (Query, Upload, Edit, Info) - YASQE/YASR components for query editing and results - Split-pane layout (editor + results) - Dataset selector dropdown - Prefix management modal - Multi-tab queries with persistence Fork Key Findings: - Three-pane layout (sidebar | commit graph | details) - Colored branch graph with collapsible merges - Drag-and-drop for 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 Adaptations for CHUCC: - Replace file tree โ†’ graph list - Replace text diff โ†’ RDF Patch viewer - Replace file conflicts โ†’ triple/quad conflicts - Add dataset selector (multi-tenant) - Add time-travel controls (asOf selector) - Add batch operation builder Next: Component gap analysis (Task 3) ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../01-research/fork-ux-analysis.md | 906 ++++++++++++++++++ .../01-research/fuseki-ui-analysis.md | 543 +++++++++++ 2 files changed, 1449 insertions(+) create mode 100644 .frontend-concept/01-research/fork-ux-analysis.md create mode 100644 .frontend-concept/01-research/fuseki-ui-analysis.md 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) From 478900a707ae1d0df0e82790fa161fb3362af8f8 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Nov 2025 12:16:29 +0000 Subject: [PATCH 03/17] docs: complete component gap analysis (Task 3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Created comprehensive 6,000-word analysis of available and missing components: Component Inventory: - Carbon Design System: 165+ components (comprehensive standard UI) - CHUCC-SQUI: 8 components (SPARQL query + results + tabs) - Missing: 15+ specialized components for version control and RDF visualization Component Placement Decisions: CHUCC-SQUI (7 reusable RDF components): - RDF Patch Viewer (syntax highlighting) - RDF Diff Viewer (side-by-side) - Graph Explorer (triple table/tree) - Commit SHA Badge, Author Input - 3-Pane Diff View (generic part) - RDF Patch Language Mode (CodeMirror) Frontend Project (11 CHUCC-specific components): - Commit Graph Visualizer (DAG with D3/Cytoscape) - Branch Selector, Commit Detail View - History Filter, Time Travel Controls - Conflict Summary & Resolution Logic - Merge Configuration Modal - Dataset Creation Wizard, Health Dashboard, Switcher - Batch Operation Builder & Preview - Quick Launch Palette Technology Recommendations: - Graph visualization: Cytoscape.js or D3.js - Syntax highlighting: CodeMirror 6 (already in CHUCC-SQUI) - State management: Svelte stores - Testing: Vitest + Playwright Implementation Roadmap (8 Phases): Phase 1: Core SPARQL (โœ… complete via CHUCC-SQUI) Phase 2: Basic version control (commit graph, branch selector, RDF Patch viewer) Phase 3: Advanced version control (merge, time travel, diff viewer) Phase 4: Conflict resolution (3-pane resolver, conflict summary) Phase 5: Dataset management (wizard, health dashboard) Phase 6: Batch operations (builder, preview) Phase 7: Enhanced browsing (graph explorer, history filter, Quick Launch) Phase 8: Polish (badges, utilities) Next: Frontend concept with mockups (Task 4) ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../01-research/component-gap-analysis.md | 1086 +++++++++++++++++ 1 file changed, 1086 insertions(+) create mode 100644 .frontend-concept/01-research/component-gap-analysis.md 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) From f7a3549e73b64d4b3ef9f482501c523733dd41ca Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 10 Nov 2025 12:23:58 +0000 Subject: [PATCH 04/17] docs: create information architecture and Query Workbench mockup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Information Architecture (7,500 words): - Navigation hierarchy (tab-based + contextual sidebars) - Routing structure with URL patterns - Site map for 7 primary views - Content organization (header, footer, main layouts) - Responsive breakpoints (mobile, tablet, desktop) - Keyboard shortcuts and accessibility - Progressive disclosure patterns Query Workbench Mockup (5,500 words): - ASCII wireframes (desktop, tablet, mobile) - Detailed component specifications - Query editor (CodeMirror, multi-tab, autocomplete) - Results table (virtual scrolling, sortable) - Prefix manager modal - Query history sidebar - Interaction patterns (execute, save, time-travel) - State management (local + global stores) - Accessibility (WCAG 2.1 AA) - Error/empty states Technologies: - Svelte 5 + Carbon Design System - CodeMirror 6 for SPARQL editing - Virtual scrolling for 10k+ rows - localStorage for session persistence Next: Remaining 6 view mockups ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../02-concept/01-information-architecture.md | 739 +++++++++++++++++ .../ui-mockups/01-query-workbench.md | 777 ++++++++++++++++++ .../02-concept/ui-mockups/README.md | 82 ++ 3 files changed, 1598 insertions(+) create mode 100644 .frontend-concept/02-concept/01-information-architecture.md create mode 100644 .frontend-concept/02-concept/ui-mockups/01-query-workbench.md create mode 100644 .frontend-concept/02-concept/ui-mockups/README.md 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..41ca48c --- /dev/null +++ b/.frontend-concept/02-concept/01-information-architecture.md @@ -0,0 +1,739 @@ +# 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) +โ”‚ +โ”œโ”€โ”€ 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/ui-mockups/01-query-workbench.md b/.frontend-concept/02-concept/ui-mockups/01-query-workbench.md new file mode 100644 index 0000000..ba3cd1c --- /dev/null +++ b/.frontend-concept/02-concept/ui-mockups/01-query-workbench.md @@ -0,0 +1,777 @@ +# Query Workbench - UI Mockup + +**View**: Query Workbench (SPARQL Query Interface) +**Route**: `/query` +**Inspiration**: Apache Jena Fuseki (simplicity, focus) + +--- + +## 1. ASCII Wireframe (Desktop - 1280px) + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [๐Ÿ”ท CHUCC] [Queryโœ“][Graphs][Version][Time Travel][Datasets][Batch] โ”‚ +โ”‚ [Dataset: default โ–พ] [Author โ–พ] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ โ”Œโ”€ Query Editor โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ +โ”‚ โ”‚ [Tab 1: New Query *] [Tab 2: Saved Query] [+ New Tab] โ”‚ โ”‚ +โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ +โ”‚ โ”‚ 1 โ”‚ PREFIX rdf: โ”‚ โ”‚ +โ”‚ โ”‚ 2 โ”‚ PREFIX rdfs: โ”‚ โ”‚ +โ”‚ โ”‚ 3 โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ 4 โ”‚ SELECT ?subject ?predicate ?object โ”‚ โ”‚ +โ”‚ โ”‚ 5 โ”‚ WHERE { โ”‚ โ”‚ +โ”‚ โ”‚ 6 โ”‚ ?subject ?predicate ?object . โ”‚ โ”‚ +โ”‚ โ”‚ 7 โ”‚ } โ”‚ โ”‚ +โ”‚ โ”‚ 8 โ”‚ LIMIT 100 โ”‚ โ”‚ +โ”‚ โ”‚ 9 โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ 10 โ”‚ โ–Š โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ”‚ โ”‚ +โ”‚ [Branch: main โ–พ] [asOf: Latest โ–พ] โ”‚ +โ”‚ [๐Ÿ“‹ Prefixes] [๐Ÿ“œ History] [๐Ÿ’พ Save] [โ–ถ Execute Query] [โน Cancel] โ”‚ +โ”‚ โ”‚ +โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€ Results (3 rows in 42ms) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ [โ†“CSV]โ”€โ” โ”‚ +โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ ?subject [โ–ฒ] โ”‚ ?predicate [โ–ฒ] โ”‚ ?object [โ–ฒ] โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ ex:Alice โ”‚ rdf:type โ”‚ ex:Person โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ ex:Alice โ”‚ ex:age โ”‚ 30 โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ”‚ ex:Bob โ”‚ rdf:type โ”‚ ex:Person โ”‚ โ”‚ โ”‚ +โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ +โ”‚ โ”‚ [โ—€] Page 1 of 1 [โ–ถ] 100 rows โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Dataset: default | Branch: main | Author: Alice โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +--- + +## 2. Component Breakdown + +### 2.1 Header (Global) + +**Component**: `
` (Carbon) + +**Contents**: +- **Logo** (left): `CHUCC` +- **Primary Nav** (center): `` + - Tab items: Query (active), Graphs, Version, Time Travel, Datasets, Batch +- **Dataset Selector** (right): `` with search + - Shows current dataset name + - Dropdown shows: Recent datasets, All datasets (searchable) +- **Author Selector** (far right): `` + - Shows current author (from localStorage) + - Editable, validates format: "Name " + +**State**: +```typescript +{ + currentDataset: string; // "default" + currentAuthor: string; // "Alice " + availableDatasets: string[]; // ["default", "my-dataset", ...] +} +``` + +--- + +### 2.2 Query Editor + +**Component**: `` (from CHUCC-SQUI) + +**Features**: +- **Tabs**: `` (Carbon) + - Each tab = one query + - Tab label shows: "New Query" or query name (if saved) + - Dirty indicator: asterisk (*) if unsaved changes + - Close button (ร—) on each tab + - "+ New Tab" button at end +- **Editor**: CodeMirror 6 with SPARQL language mode + - Line numbers (left) + - Syntax highlighting (keywords, URIs, literals) + - Autocomplete (Ctrl+Space) + - Error underlining (red squiggly) + - Word wrap (toggle in settings) +- **Toolbar** (below editor): + - **Branch Selector**: `` - Select branch for query execution + - **asOf Selector**: `` - "Latest" or date picker + - **Prefixes Button**: Opens modal with prefix manager + - **History Button**: Opens sidebar with query history + - **Save Button**: Save query with name + - **Execute Button**: Blue, prominent (Ctrl+Enter) + - **Cancel Button**: Ghost style (stops running query) + +**State**: +```typescript +{ + tabs: Array<{ + id: string; + name: string; + query: string; + dirty: boolean; + results?: QueryResults; + }>; + activeTabId: string; + selectedBranch: string; // "main" + selectedAsOf: string | null; // null or ISO 8601 timestamp +} +``` + +**Interactions**: +- **Type in editor**: Auto-save to localStorage every 5 seconds +- **Ctrl+Enter**: Execute query in active tab +- **Ctrl+/**: Toggle line comment +- **Ctrl+S**: Save query (open save dialog if unnamed) +- **Click tab**: Switch active tab +- **Click ร— on tab**: Close tab (confirm if dirty) + +--- + +### 2.3 Results Table + +**Component**: `` (from CHUCC-SQUI with virtual scrolling) + +**Features**: +- **Header Bar**: + - **Title**: "Results (X rows in Yms)" or "No results" + - **Export Menu**: `` (right) + - Download as: CSV, TSV, JSON, XML, Turtle, N-Triples, JSON-LD, RDF/XML +- **Table**: `` (Carbon) with virtual scrolling + - Columns: One per SPARQL variable (e.g., ?subject, ?predicate, ?object) + - Sortable columns (click header) + - Resizable columns (drag divider) + - Row hover: Highlight row + - Cell types: + - **URI**: `` with clickable icon โ†’ opens in Graph Explorer + - **Literal**: Plain text with datatype tooltip + - **Blank Node**: `_:b1` with gray styling +- **Pagination**: `` (Carbon) + - Page size selector: 100, 500, 1000, All + - Current page indicator + - Previous/Next buttons + +**State**: +```typescript +{ + results: { + variables: string[]; // ["?subject", "?predicate", "?object"] + bindings: Array>; // [{?subject: {...}, ...}, ...] + count: number; // Total rows + executionTime: number; // Milliseconds + } | null; + currentPage: number; // 1-indexed + pageSize: number; // 100, 500, 1000, -1 (all) + sortColumn: string | null; // Variable name + sortOrder: 'asc' | 'desc'; +} +``` + +**Interactions**: +- **Click URI cell**: Navigate to Graph Explorer with graph/subject selected +- **Right-click cell**: Context menu (Copy value, Copy as N-Triples, etc.) +- **Click column header**: Sort by that column +- **Click export**: Download results in selected format +- **Change page size**: Re-render table with new page size + +--- + +### 2.4 Prefix Manager (Modal) + +**Component**: `` (Carbon ``) + +**Layout**: +``` +โ”Œโ”€ Manage Prefixes โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ โ”‚ +โ”‚ Common Prefixes: โ”‚ +โ”‚ โ˜‘ rdf http://www.w3.org/1999/02/22-... โ”‚ +โ”‚ โ˜‘ rdfs http://www.w3.org/2000/01/rdf-... โ”‚ +โ”‚ โ˜‘ owl http://www.w3.org/2002/07/owl# โ”‚ +โ”‚ โ˜‘ xsd http://www.w3.org/2001/XMLSchema# โ”‚ +โ”‚ โ˜ foaf http://xmlns.com/foaf/0.1/ โ”‚ +โ”‚ โ˜ dcterms http://purl.org/dc/terms/ โ”‚ +โ”‚ โ”‚ +โ”‚ Custom Prefixes: โ”‚ +โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ +โ”‚ โ”‚ Prefix โ”‚ Namespace URI โ”‚โ”‚ +โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”คโ”‚ +โ”‚ โ”‚ ex โ”‚ http://example.org/ โ”‚โ”‚ +โ”‚ โ”‚ my โ”‚ http://my.example.com/ns# โ”‚โ”‚ +โ”‚ โ”‚ [+ Add] โ”‚ โ”‚โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ +โ”‚ โ”‚ +โ”‚ [Cancel] [Apply to Query] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +**Features**: +- **Common Prefixes**: `` list (pre-populated) + - Check/uncheck to include in query +- **Custom Prefixes**: `` + - Prefix column: `` (short name, e.g., "ex") + - Namespace column: `` (full URI) + - [+ Add] button: Adds new row + - [ร—] button per row: Removes row +- **Actions**: + - **Cancel**: Close modal without applying + - **Apply to Query**: Insert PREFIX declarations at top of current query tab + +**State**: +```typescript +{ + commonPrefixes: Array<{ prefix: string; uri: string; enabled: boolean }>; + customPrefixes: Array<{ prefix: string; uri: string }>; +} +``` + +--- + +### 2.5 Query History (Sidebar Panel) + +**Component**: `` (Carbon `` or ``) + +**Layout** (slides in from right): +``` +โ”Œโ”€ Query History โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ [Search queries...] [๐Ÿ”] โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€ Today โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ +โ”‚ โ”‚ SELECT ?s ?p ?o WHERE { ... } โ”‚โ”‚ +โ”‚ โ”‚ 3 rows ยท 42ms ยท 10:30 AM โ”‚โ”‚ +โ”‚ โ”‚ โ”‚โ”‚ +โ”‚ โ”‚ SELECT * WHERE { ... } โ”‚โ”‚ +โ”‚ โ”‚ 150 rows ยท 125ms ยท 9:45 AM โ”‚โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ +โ”‚ โ”‚ +โ”‚ โ”Œโ”€ Yesterday โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ +โ”‚ โ”‚ CONSTRUCT { ... } WHERE { ... } โ”‚โ”‚ +โ”‚ โ”‚ 50 triples ยท 200ms โ”‚โ”‚ +โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ +โ”‚ โ”‚ +โ”‚ [Clear History] โ”‚ +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +**Features**: +- **Search**: `` (filters queries by text) +- **Grouped by date**: Accordion sections (Today, Yesterday, This Week, Older) +- **Query items**: `` (clickable) + - First 50 characters of query (truncated with ...) + - Metadata: Row count, execution time, timestamp + - Hover: Show full query in tooltip + - Click: Load query into new tab + - Right-click: Delete from history + +**State**: +```typescript +{ + history: Array<{ + id: string; + query: string; + timestamp: Date; + executionTime: number; + rowCount: number; + }>; + searchText: string; +} +``` + +--- + +### 2.6 Footer (Global) + +**Component**: `