Skip to main content

Graph Component Refactoring Summary

· 2 min read

Execution Plan​

The goal was to refactor the Graph component system from a single 3200+ line file into a modular architecture with focused components, hooks, and utilities.

Planned Components​

  1. GraphMenuBar.tsx - Menu bar with control buttons
  2. GraphInfoPanel.tsx - Side panel for node/edge information
  3. GraphCanvas.tsx - ForceGraph2D wrapper component

Planned Hooks​

  1. useGraphState.ts - Centralized state management
  2. useGraphData.ts - Data transformation and flattening
  3. useGraphInteractions.ts - Event handler management

Planned Documentation​

  1. Storybook setup and stories for all components
  2. Architecture documentation
  3. Usage guides

Execution Results / Attempts​

✅ Completed Components​

  1. GraphMenuBar.tsx ✅

    • Menu bar with control buttons
    • ~100 lines
    • Fully documented with Storybook stories

  2. GraphInfoPanel.tsx ✅

    • Side panel for node/edge information
    • ~400 lines
    • Handles node display, edge display, connections, external links
    • Fully documented with Storybook stories

  3. GraphCanvas.tsx ✅

    • ForceGraph2D wrapper component
    • ~150 lines
    • Handles canvas rendering configuration

✅ Completed Hooks​

  1. useGraphState.ts ✅

    • Centralized state management
    • ~120 lines
    • Returns { state, actions } object

  2. useGraphData.ts ✅

    • Data transformation and flattening
    • ~100 lines
    • Handles hierarchical node flattening

  3. useGraphInteractions.ts ✅

    • Event handler management
    • ~150 lines
    • All interaction handlers (click, drag, zoom, etc.)

✅ Utility Files (Previously Created)​

  1. GraphDataUtils.ts ✅
  2. GraphNodeUtils.ts ✅
  3. GraphRenderingUtils.ts ✅
  4. GraphTextUtils.ts ✅
  5. graphUtils.ts ✅ (re-export for backward compatibility)

✅ Storybook Setup​

  1. .storybook/main.ts ✅

    • Storybook configuration
    • Webpack configuration for canvas support

  2. .storybook/preview.ts ✅

    • Global Storybook settings
    • Decorators and parameters

  3. GraphMenuBar.stories.tsx ✅

    • Menu bar stories
    • Multiple examples (default, dark mode, etc.)

  4. GraphInfoPanel.stories.tsx ✅

    • Info panel stories
    • Node/edge examples, dark mode, differentiating edges

  5. Graph.stories.tsx ✅

    • Architecture overview
    • Component composition examples

✅ Documentation​

  1. README.md ✅

    • Complete component system documentation
    • Usage examples
    • File structure

  2. COMPONENT_ARCHITECTURE.md ✅

    • Detailed architecture documentation
    • Component hierarchy diagrams
    • Data flow diagrams

  3. STORYBOOK_GUIDE.md ✅

    • Storybook usage guide
    • Story documentation
    • Best practices

  4. COMPONENT_STRUCTURE.md ✅

    • Component structure overview
    • Status tracking

📊 Impact Achieved​

File Size Reduction:

  • Before: Single file with ~3,219 lines
  • After: Split into 10+ focused files
  • Main File: Will be reduced to ~800-1000 lines after full refactor

Organization:

  • Components: 3 focused components
  • Hooks: 3 custom hooks
  • Utilities: 4 utility files (previously created)
  • Stories: 3 Storybook story files

Benefits Achieved: ✅ Better code organization ✅ Improved maintainability ✅ Enhanced testability ✅ Interactive documentation (Storybook) ✅ Reusable components ✅ Clear separation of concerns

⏳ Remaining Work​

  1. Refactor GraphRendererImpl ⏳

    • Update to use new components
    • Replace inline code with component imports
    • Maintain backward compatibility

  2. Testing ⏳

    • Add unit tests for components
    • Add integration tests
    • Test Storybook stories

  3. Performance ⏳

    • Profile component rendering
    • Optimize re-renders
    • Code splitting optimization

Component Creation - Changelog Component

· 11 min read

Execution Plan​

Create a comprehensive Changelog React component with:

  • GitHub-style heatmap visualization (month/quarter/year granularity)
  • Separate heatmap rows for content vs development categories
  • Shared date overlay (year/quarter headers) above heatmap rows
  • Legend section positioned to the right of heatmap rows
  • Modular component architecture for maintainability
  • Quarter-based list view with filtering
  • Responsive design and proper alignment

Execution Results / Attempts​

✅ Initial Changelog Component Created (2025-01-20)​

Work Period: January 20, 2025

Key Accomplishments:

  • Created initial Changelog component with heatmap visualization
  • Implemented month/quarter/year grouping and display
  • Added quarter-based list view with horizontal scrolling
  • Integrated with changelog data generation system

✅ Component Modularization & Refinement (2025-01-20)​

Work Period: January 20, 2025 (Iterative refinement)

Key Accomplishments:

Component Architecture​

  • Modularized Changelog component into sub-components:
    • DateOverlay/ - Shared year and quarter headers above heatmap rows
    • HeatmapRow/ - Individual heatmap row for each category (content/development)
    • LegendSidebar/ - Title and legend for each heatmap row
    • Legend/ - Intensity scale legend component
    • Filters/ - Filter dropdowns (status, type, priority, category)
    • QuarterSection/ - Quarterly entries display with filtering

Layout & Alignment​

  • Separated heatmap rows from legends:
    • Heatmap rows on left side (flex: 1)
    • Legends section on right side (fixed 200px width)
    • DateOverlay positioned above rows, spanning only rows width
    • Legend section header ("Legend") aligned with DateOverlay

Heatmap Visualization​

  • Two separate heatmap rows:
    • Content row (blue color scheme)
    • Development row (green color scheme)
    • Each row has its own title and legend on the right
    • Shared date overlay (year/quarter headers) above both rows

Spacing & Alignment​

  • Quarter gaps:

    • Added 4px gap divs between quarters (matching heatmap squares)
    • CSS gap (2px) applies to gap divs, creating 8px total visual gap
    • Updated width calculations to account for quarter gaps (8px total)
    • Quarter bars align perfectly with heatmap squares below

  • Row spacing:

    • Minimal 2px gap between heatmap rows (matching square spacing)
    • Minimal 2px gap between legend entries
    • Removed excessive padding/margins

Alignment Fixes​

  • Fixed quarter bar alignment with heatmap squares:

    • Accounted for CSS gap (2px) in width calculations
    • Quarter gap divs (4px) + CSS gap (2px on each side) = 8px total
    • Year and quarter lines span correct widths
    • Quarter lines don't extend beyond their containers (overflow: hidden)

  • Fixed legend alignment:

    • Legends anchored to top-right (not bottom)
    • Added "Legend" header aligned with DateOverlay
    • Proper flex alignment (align-content: flex-start, justify-content: flex-start)

Date Overlay​

  • Year labels and lines span full year width (including quarter gaps)
  • Quarter labels and lines span individual quarter widths
  • Proper positioning above heatmap rows
  • Gap divs match heatmap row structure exactly
  • Year labels use Highlight component with gradient background
  • Year line positioned behind year label (z-index: 0)

Additional Enhancements​

  • Dynamic Date Range: Always shows 1 year ago, this year, and next year (dynamically calculated)
  • Current Month Indicator: Added to legend with bordered square and month/year label
  • Year Highlighting: Year labels use Highlight component for visual emphasis
  • Legend Header: "Legend" header anchored to top-right with minimal vertical space

Components Created:

  • src/components/Changelog/Changelog.tsx - Main component orchestrating all sub-components
  • src/components/Changelog/DateOverlay/DateOverlay.tsx - Year and quarter headers
  • src/components/Changelog/HeatmapRow/HeatmapRow.tsx - Individual heatmap row
  • src/components/Changelog/LegendSidebar/LegendSidebar.tsx - Title and legend wrapper
  • src/components/Changelog/Legend/Legend.tsx - Intensity scale legend
  • src/components/Changelog/Filters/ChangelogFilters.tsx - Filter dropdowns
  • src/components/Changelog/QuarterSection/QuarterSection.tsx - Quarterly entries display

CSS Modules Created:

  • Each component has its own .module.css file for scoped styling
  • Proper alignment and spacing rules
  • Responsive design considerations

Key Technical Details:

  • Width calculations account for:
    • Month cells: 20px each
    • Month gaps: 2px between months (CSS gap)
    • Quarter gaps: 4px gap div + 2px CSS gap on each side = 8px total
    • Year width = sum of quarter widths + (quarters.length - 1) × 8px
  • Date range: Dynamically shows 1 year ago, this year, and next year
  • Year labels use Highlight component with gradient background
  • Year line z-index: 0 (behind label), label z-index: 3 (above line)
  • Legend includes current month indicator with bordered square and month/year label

Storybook Stories:

  • Changelog.stories.tsx: Default, SingleEntry, ManyEntries, ContentOnly, DevelopmentOnly stories
  • Changelog.mdx: Comprehensive documentation of component structure, layout, and behavior
  • Stories include sample entries with proper category assignments (content/development)

Related Links:

✅ Mobile Responsiveness & UX Improvements (2025-01-20)​

Work Period: January 20, 2025 (Iterative refinement)

Key Accomplishments:

Mobile Card Design​

  • Minimal, horizontally wide rectangular cards:
    • Reduced card padding from 1.5rem to 0.75rem 1rem (horizontal emphasis)
    • Reduced border radius from 8px to 6px for tighter appearance
    • Reduced gap between cards from 1rem to 0.75rem
    • Disabled hover transform on mobile (no translateY)

Typography Optimization​

  • Smaller font sizes on mobile:
    • Title: 1.25rem → 1rem
    • Description: 0.875rem with 2-line clamp and ellipsis
    • Meta: 0.875rem → 0.75rem
    • Status titles: 1rem → 0.875rem
    • Quarter titles: 1.25rem → 1.1rem

Badge Improvements​

  • Compact badges:
    • Padding: 0.25rem 0.75rem → 0.15rem 0.5rem
    • Font size: 0.75rem → 0.65rem
    • Border radius: 12px → 8px
    • Tighter gap: 0.5rem → 0.25rem

Layout Enhancements​

  • Description truncation: Limited to 2 lines with ellipsis on mobile
  • Meta information: Horizontal layout (flex-direction: row) instead of vertical
  • Meta items: Inline with white-space: nowrap for compact display
  • Quarter section: Reduced padding from 1.5rem to 1rem on mobile
  • Quarter headers: Reduced margins and thinner borders

Mobile Heatmap & Legend Layout​

  • Vertical stacking on mobile:
    • Legend section moves above heatmap rows (order: -1)
    • Legend takes full width and left-aligns
    • Date overlay and heatmap rows scroll together (no independent scrolling)
    • Filters stack vertically with full-width dropdowns

Filter Improvements​

  • Mobile-friendly filters:
    • Stack vertically on mobile (flex-direction: column)
    • Full-width dropdowns with proper box-sizing
    • Smaller font sizes (0.8rem for labels, 0.875rem for selects)
    • Proper text wrapping and overflow handling
    • Removed appearance defaults for better mobile compatibility

CSS Files Modified:

  • QuarterSection.module.css - Mobile card styles, typography, badges, meta layout
  • Changelog.module.css - Mobile heatmap/legend layout, filter styles
  • LegendSidebar.module.css - Mobile legend alignment
  • Legend.module.css - Mobile legend alignment

✅ EntryTimeline Component Creation (2025-01-20)​

Work Period: January 20, 2025

Key Accomplishments:

Timeline Visualization​

  • Created EntryTimeline component to replace text-based date display with a proper timeline visualization:
    • Timeline bar: Horizontal line spanning full width (2px height, gray background)
    • Inception dot: Primary color dot positioned at left (0%) on the bar
    • Execution dot: Success color dot positioned at right (100%) on the bar (only shown if execution date exists)
    • Duration label: Centered on the bar, showing time between inception and execution
    • Date labels: Displayed below the bar, aligned with their respective dots

Visual Layout Structure​

[●─────────────────── 5 days ───────────────────●]
Inception                                    Execution
Jan 15, 2025                            Jan 20, 2025

Layout Components:

  1. Timeline Bar (.timelineBar):

    • Horizontal line (2px height) spanning full width
    • Gray background (var(--ifm-color-emphasis-300))
    • Position: relative container for absolutely positioned dots

  2. Timeline Dots (.timelineDotContainer):

    • Inception dot: Absolutely positioned at left: 0 (start of bar)
      • Primary color (var(--ifm-color-primary))
      • 10px diameter (8px on mobile)
      • 2px border (1.5px on mobile)
    • Execution dot: Absolutely positioned at right: 0 (end of bar)
      • Success color (var(--ifm-color-success)) when execution date exists
      • Muted gray color (var(--ifm-color-emphasis-400)) with reduced opacity when execution is TBD
      • Same size as inception dot
      • Always rendered - shows even when execution date is "TBD" or "XX"

  3. Duration Label (.timelineDuration):

    • Centered on the bar (left: 50%, transform: translate(-50%, -50%))
    • Background matches page background (appears above bar)
    • Shows calculated duration or "X days thus far" for TBD execution
    • Font: 0.7rem (0.65rem on mobile), font-weight: 600

  4. Date Labels (.timelineDates):

    • Row below the bar, flex layout with space-between
    • Inception date: Left-aligned under inception dot
    • Execution date: Right-aligned under execution dot (always shown)
    • Each date item contains:
      • Label: "INCEPTION" or "EXECUTION" (uppercase, 0.65rem, 0.6rem on mobile)
      • Date: Formatted date string (0.75rem, 0.7rem on mobile) or "TBD" if execution date is TBD

Duration Calculation​

  • Smart duration formatting:
    • TBD execution: Shows "X days thus far" (calculated from inception to today)
    • Completed execution: Shows duration between inception and execution dates
    • Duration formats:
      • "Same day" if 0 days
      • "X days" if < 7 days
      • "X weeks" if < 30 days
      • "X months" if < 365 days
      • "X years, Y months" if >= 1 year
    • Handles invalid dates gracefully (returns "TBD")
  • Visual indication for TBD execution:
    • Execution dot always visible (even when TBD)
    • TBD execution dot uses muted gray color with reduced opacity (.timelineDotTBD)
    • Execution date label shows "TBD" instead of formatted date
    • Duration shows "X days thus far" to indicate ongoing work

Date Formatting​

  • Smart date formatting:
    • Handles "TBD" and "XX" dates gracefully (replaces "XX" with "??")
    • Formats dates as "Jan 15, 2025" (month short, day numeric, year numeric)
    • Falls back to original string if date parsing fails

Responsive Design​

  • Mobile optimization:
    • Thinner bar: 2px → 1.5px height on mobile
    • Smaller dots: 10px → 8px diameter on mobile
    • Thinner borders: 2px → 1.5px on mobile
    • Smaller duration label: 0.7rem → 0.65rem on mobile
    • Smaller date fonts: 0.75rem → 0.7rem for dates, 0.65rem → 0.6rem for labels
    • Tighter spacing: 0.5rem → 0.375rem gap
    • Reduced padding on duration label: 0.125rem 0.375rem → 0.1rem 0.25rem

Integration​

  • Replaced text-based dates in QuarterSection:
    • Removed separate "Inception:" and "Execution:" text spans
    • Integrated EntryTimeline component into entryMeta section
    • Timeline aligns properly with other meta items (component name, etc.)
    • Works seamlessly with horizontal meta layout on mobile

Components Created:

  • src/components/Changelog/EntryTimeline/EntryTimeline.tsx - Timeline component with duration calculation
  • src/components/Changelog/EntryTimeline/EntryTimeline.module.css - Timeline styles with bar, dots, and date layout
  • src/components/Changelog/EntryTimeline/index.tsx - Export file

CSS Classes:

  • .timeline - Main container (flex column)
  • .timelineBar - Horizontal bar/line (relative positioning)
  • .timelineDotContainer - Container for dots (absolute positioning)
  • .timelineDot - Dot styling (circular, colored)
  • .timelineDotInception - Primary color for inception dot
  • .timelineDotExecution - Success color for execution dot (when execution date exists)
  • .timelineDotTBD - Muted gray color for execution dot when execution is TBD
  • .timelineDuration - Duration label (centered on bar)
  • .durationLabel - Duration text styling
  • .timelineDates - Date labels row (flex, space-between)
  • .timelineDateItem - Individual date item container
  • .timelineLabel - "INCEPTION" / "EXECUTION" label styling
  • .timelineDate - Formatted date text styling

CSS Integration:

  • Added timeline styles integration in QuarterSection.module.css
  • Timeline works seamlessly with horizontal meta layout on mobile

✅ Docusaurus Routing Configuration (2025-01-20)​

Work Period: January 20, 2025

Key Accomplishments:

Plugin Configuration​

  • Added @docusaurus/plugin-content-docs plugin to serve changelog markdown files as pages:
    • Plugin ID: changelog (unique identifier for multi-instance plugin, similar to blog plugin's id: 'designs')
    • Path: ./changelog (points to changelog directory, no file copying required)
    • Route Base Path: changelog (files accessible at /changelog/...)
    • Sidebar Configuration: sidebarPath: false (no sidebar needed for changelog entries)
    • Edit URL: Points to GitHub for easy editing
    • Uses built-in Docusaurus plugin: Follows same pattern as @docusaurus/plugin-content-blog for multiple instances

Why Docs Plugin Instead of Pages Plugin​

  • Pages plugin limitation: @docusaurus/plugin-content-pages doesn't support multiple instances (unlike blog/docs plugins)
  • Docs plugin advantage: @docusaurus/plugin-content-docs supports multiple instances with id field, just like blog plugin
  • No file copying required: Files served directly from changelog/ directory (like blog serves from designs/)
  • Proper MDX rendering: Full markdown content rendered with Docusaurus MDX features and frontmatter support
  • Fixed broken changelog entry links:
    • Previously linked to GitHub (temporary workaround)
    • Now links to /changelog/${slug} (proper Docusaurus routes)
    • Preserves subdirectory structure in URLs (e.g., /changelog/development/2025-01-15-...)
    • Links work correctly for both content and development entries

Benefits​

  • Changelog entries are now accessible as pages:
    • Full markdown content rendered with Docusaurus MDX features
    • Frontmatter properly parsed and displayed
    • Edit links point to GitHub for easy updates
    • Proper routing and navigation within Docusaurus site
    • SEO-friendly URLs
    • No file copying or custom plugins required
    • Uses standard Docusaurus plugin pattern (same as blog plugin)

Configuration Files Modified:

  • docusaurus.config.js: Added changelog docs plugin configuration (follows blog plugin pattern)
  • src/pages/changelog.tsx: Updated getEntryUrl to use proper routes

Example URLs:

  • /changelog/development/2025-01-15-component-creation-svg-kanban
  • /changelog/content/2025-XX-XX-content-post-knowledge-agents-design

Configuration Pattern:

[
  '@docusaurus/plugin-content-docs',
  {
    id: 'changelog',  // Multi-instance support (like blog plugin)
    path: './changelog',
    routeBasePath: 'changelog',
    sidebarPath: false,
    editUrl: 'https://github.com/.../changelog/',
  },
]

Status: Changelog component has been successfully created and refined with modular architecture, proper alignment, GitHub-style heatmap visualization, dynamic date range, year highlighting, current month indicator, mobile responsiveness, timeline visualization, and proper Docusaurus routing. The component is production-ready and maintains clean separation of concerns. Storybook stories and documentation are complete. All changelog entries are now accessible as pages with proper routing.

Blogging Mechanism - Storybook Component Documentation

· 2 min read

Execution Plan​

Establish Storybook as a component development and documentation tool for the blog, enabling:

  • Interactive component documentation
  • Component development environment
  • Visual component testing
  • Integration with blog navigation
  • Static site generation for production

Execution Results / Attempts​

✅ Storybook Established (2025-11-16 to 2025-11-17)​

Work Period: November 16, 2025 to November 17, 2025

Commits: 2 commits related to Storybook integration

Key Accomplishments:

  • Integrated Storybook into blog build process
  • Added Storybook tab to blog navigation
  • Set up Storybook for component documentation
  • Configured Storybook for static site generation
  • Created initial Storybook stories for Graph components

Notable Commits:

  • 7634d68b (2025-11-16): Revamping graph component, modularizing it, etc. Also added storybook tab to document components
  • 6ec4aaac (2025-11-17): Revamp component setup, story book stories, graph render on mobile, etc

Features Implemented:

  • Storybook development server integration
  • Static Storybook build integrated into Docusaurus build
  • Storybook accessible via /storybook/ route
  • Component stories for Graph components
  • Webpack configuration for Docusaurus module mocking
  • Storybook addons configured (essentials, interactions, links)

Status: Storybook has been successfully integrated into the blog infrastructure. Components can now be developed and documented in Storybook, with the static build accessible through the blog navigation. Further component stories are being added as components are created and refactored.

Graph Renderer Component Creation

· 5 min read

Execution Plan​

Establish a modular Graph Renderer component system by refactoring from a single 3200+ line file into a well-organized architecture with focused components, hooks, and utilities.

Planned Work​

  1. Component structure and hierarchy design
  2. Hook architecture implementation
  3. Utility architecture implementation
  4. Data flow design
  5. File structure organization

Execution Results / Attempts​

✅ Component Created (2025-11-08 to 2025-11-17)​

Work Period: November 8, 2025 to November 17, 2025

Commits: 10 commits related to graph component creation and refactoring

The Graph component system has been successfully created and refactored from a single 3200+ line file into a modular architecture with focused components, hooks, and utilities.

Key Commits:

  • a64d629e (2025-11-08): Updating authors and adding graph component plus stats structures and algos
  • 7333d884 (2025-11-08): Making graph component reactive
  • d2e8bf6d (2025-11-08): Adding menu bar to graph component
  • 92e82a04 (2025-11-08): Added ability to have anchor links to specific nodes in specific graphs
  • f57ee652 (2025-11-10): Adding integ and e2e tests for graph component
  • b5c58a8a (2025-11-10): Checkpointing graph renderer
  • cca8ae25 (2025-11-12): Big blog structure overhaul + finalization of graph component
  • e657ebde (2025-11-12): Revamp to readmes plus fix for graph
  • 7634d68b (2025-11-16): Revamping graph component, modularizing it, etc. Also added storybook tab to document components
  • 6ec4aaac (2025-11-17): Revamp component setup, story book stories, graph render on mobile, etc

Component Structure​

┌─────────────────────────────────────────────────────────┐
│                  GraphRenderer                           │
│  (BrowserOnly wrapper - handles SSR prevention)          │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ▼
        ┌──────────────────────┐
        │  GraphRendererImpl   │
        │  (Main Component)  │
        └──────────┬───────────┘
                   │
        ┌──────────┴──────────┐
        │                     │
        ▼                     ▼
┌──────────────┐      ┌──────────────┐
│ GraphCanvas  │      │GraphInfoPanel│
│ (ForceGraph) │      │  (Side Bar)  │
└──────────────┘      └──────────────┘
        │
        ▼
┌──────────────┐
│ GraphMenuBar │
│  (Controls)  │
└──────────────┘

Component Details​

GraphRenderer​

  • Purpose: Browser-only wrapper to prevent SSR issues
  • Location: GraphRenderer.tsx
  • Responsibilities:
    • Dynamic import of browser-only dependencies
    • Loading state management
    • Error handling

GraphRendererImpl​

  • Purpose: Main component that composes all sub-components
  • Location: GraphRenderer.tsx (to be refactored)
  • Responsibilities:
    • Component composition
    • State coordination
    • Event handling orchestration

GraphCanvas​

  • Purpose: ForceGraph2D wrapper
  • Location: GraphCanvas.tsx
  • Props: All ForceGraph2D configuration
  • Responsibilities:
    • Canvas rendering setup
    • Graph visualization
    • Event propagation

GraphInfoPanel​

  • Purpose: Side panel for node/edge information
  • Location: GraphInfoPanel.tsx
  • Size: ~400 lines (extracted from main file)
  • Responsibilities:
    • Display node information
    • Display edge information
    • Show connections (ingress/egress)
    • External links
    • Documentation links

GraphMenuBar​

  • Purpose: Control buttons
  • Location: GraphMenuBar.tsx
  • Size: ~100 lines
  • Responsibilities:
    • Center graph
    • Expand/collapse all
    • Toggle panel visibility

Hook Architecture​

useGraphState​

  • Purpose: Centralized state management
  • Location: useGraphState.ts
  • Returns: { state, actions }
  • State Properties:
    • expandedNodes: Set<string>
    • selectedNode: any
    • selectedEdge: any
    • highlightedNodeId: string | null
    • highlightedEdgeId: string | null
    • paneVisible: boolean
    • contextMenu: {...} | null
    • rightClickMenu: {...} | null
    • nodePositions: Map<string, {...}>
    • isDarkMode: boolean

useGraphData​

  • Purpose: Data transformation
  • Location: useGraphData.ts
  • Returns: { graphData, flattenNodes }
  • Features:
    • Hierarchical node flattening
    • Expansion-based filtering
    • Link generation

useGraphInteractions​

  • Purpose: Event handler management
  • Location: useGraphInteractions.ts
  • Returns: Object with all handlers
  • Handlers:
    • Node interactions (click, right-click, drag)
    • Edge interactions (click, right-click)
    • Zoom handling
    • Clipboard operations

Utility Architecture​

GraphDataUtils.ts​

Purpose: Tree traversal and data operations

  • findPathToNode - Find path to node in tree
  • findNodeById - Find node by ID
  • getAllNodesWithChildren - Get all parent nodes
  • cleanNodeForSelection - Clean node object
  • cleanEdgeForSelection - Clean edge object

GraphNodeUtils.ts​

Purpose: Node properties and styling

  • getNodeRadius - Calculate radius (12 for parents, 8 for leaves)
  • getNodeColor - Get color with fallback
  • getNodeLabel - Extract label (title > name > id)
  • isValidNodeCoordinates - Validate coordinates
  • getNodeStatusIndicator - Get status symbol (▶/▼/🌿)

GraphRenderingUtils.ts​

Purpose: Rendering calculations

  • getEdgeCoordinates - Calculate edge start/end points
  • calculateAvailableTextWidth - Text width in circular node
  • calculateEmojiAreaCenterY - Emoji area position
  • calculateLinePositions - Text line Y positions
  • calculateOptimalTitleFontSize - Title font sizing
  • calculateIndicatorFontSize - Indicator font sizing

GraphTextUtils.ts​

Purpose: Text processing

  • breakLongWord - Break words at natural boundaries
  • wrapTextIntoLines - Wrap text into 3 lines
  • truncateLine - Truncate with ellipsis
  • calculateOptimalFontSize - Optimal font size calculation
  • applyZoomScaling - Zoom-based font scaling

Data Flow​

User Interaction
    │
    ▼
useGraphInteractions (handlers)
    │
    ▼
useGraphState (state updates)
    │
    ▼
useGraphData (data transformation)
    │
    ▼
GraphCanvas (rendering)
    │
    ├──► GraphInfoPanel (display info)
    └──► GraphMenuBar (controls)

Storybook Documentation​

All components are documented in Storybook with:

  • Interactive examples
  • Prop documentation
  • Usage examples
  • Architecture overview

Running Storybook​

npm run storybook
# or
yarn storybook

Available Stories​

  1. Graph/GraphMenuBar

    • Default (light mode)
    • Dark mode
    • Pane hidden
    • Custom height

  2. Graph/GraphInfoPanel

    • Empty state
    • Node selected
    • Edge selected
    • Dark mode
    • Differentiating edge

  3. Graph/Architecture

    • Architecture overview
    • Component examples
    • Usage patterns

File Size Reduction​

Before Refactoring​

  • GraphRenderer.tsx: ~3,219 lines

After Refactoring​

  • GraphRenderer.tsx: ~800-1000 lines (estimated after full refactor)
  • GraphMenuBar.tsx: ~100 lines
  • GraphInfoPanel.tsx: ~400 lines
  • GraphCanvas.tsx: ~150 lines
  • useGraphState.ts: ~120 lines
  • useGraphData.ts: ~100 lines
  • useGraphInteractions.ts: ~150 lines
  • Utility files: ~1,200 lines (split across 4 files)

Total: Similar line count, but much better organized

Benefits​

  1. Maintainability: Smaller files are easier to understand
  2. Testability: Components can be tested independently
  3. Reusability: Components can be used in different contexts
  4. Documentation: Storybook provides interactive docs
  5. Performance: Better code splitting opportunities
  6. Collaboration: Multiple developers can work on different components

Migration Path​

  1. ✅ Created utility files (GraphDataUtils, GraphNodeUtils, etc.)
  2. ✅ Created hooks (useGraphState, useGraphData, useGraphInteractions)
  3. ✅ Created components (GraphMenuBar, GraphInfoPanel, GraphCanvas)
  4. ⏳ Refactor GraphRendererImpl to use new components
  5. ✅ Set up Storybook
  6. ✅ Create Storybook stories

Next Steps​

  1. Complete GraphRendererImpl refactoring
  2. Add unit tests for components
  3. Add integration tests
  4. Performance profiling
  5. Additional Storybook stories for edge cases

Card and Timeline Components Creation

· One min read

Execution Plan​

Create reusable Card and Timeline React components for displaying structured content in blog posts, including:

  • Card component for displaying information cards
  • Timeline component for displaying chronological information
  • Consistent styling and theming
  • Integration with Docusaurus theme

Execution Results / Attempts​

✅ Components Created (2025-09-23)​

Work Period: September 23, 2025

Commits: 1 commit

Key Accomplishments:

  • Created Card component for structured content display
  • Created Timeline component for chronological information
  • Components integrated into blog post system

Notable Commits:

  • 86ed353b (2025-09-23): Adding Card and Timeline Components

Status: Card and Timeline components have been successfully created and are available for use in blog posts. These components enable structured display of information, particularly useful for professional contributions timeline and other chronological content.

Blogging Mechanism - Frontmatter Management

· 2 min read

Execution Plan​

Establish automated mechanisms to maintain blog post frontmatter consistency and accuracy, including:

  • Frontmatter cleanup and standardization
  • Automated frontmatter validation and fixing
  • Self-healing prompts for frontmatter management
  • Scripts to ensure required frontmatter fields are present

Execution Results / Attempts​

✅ Frontmatter Management Established (2025-09-10 to 2025-09-15)​

Work Period: September 10, 2025 to September 15, 2025

Commits: 3 commits related to frontmatter management

Key Accomplishments:

  • Cleaned up blog post frontmatter across the blog
  • Created mechanisms to keep frontmatter up to date
  • Added prompt-based system to help manage frontmatter
  • Created self-healing prompt for frontmatter updates
  • Fixed multiple frontmatter issues using automated tools

Notable Commits:

  • fb310e2f (2025-09-10): Cleaning up blog post frontmatter + mechanisms to keep frontmatter up to date + plan for SEO
  • 6db853e2 (2025-09-15): Added prompt to help manage frontmatter
  • 509373789 (2025-09-15): Fixed a bunch of front matter with update to the self-healing prompt

Tools Created:

  • scripts/fix_frontmatter.py: Python script to automatically fix and standardize frontmatter in markdown files
    • Ensures required fields (slug, title, description) are present
    • Extracts title from content if missing
    • Standardizes frontmatter format
    • Located at: bytesofpurpose-blog/scripts/fix_frontmatter.py

Related Links:

Status: Frontmatter management mechanisms have been successfully established. The blog now has automated tools and processes to maintain frontmatter consistency, supporting SEO efforts and content organization. The self-healing prompt system enables ongoing maintenance of frontmatter quality.

SVG Kanban Board Component

· 3 min read

Original Intent​

  • I need to be able to make an svg roadmap through gen ai ...
    • this will allow me to bring individual ideas to git and use any genai healing tools or ifea merging tools to operate on my ideas - alternative is figma mcp - but its not free...
    • I should have a repo of ideas .... where I autogenerate svg assets from it ...
    • maybe the ideas ask live in a noteplan like repo since I need to act to fuel some of the ideas

Execution Plan​

Create a system for generating and embedding custom SVG-based Kanban boards in documentation and blog posts:

Goals​

  1. SVG Template Creation - Base template with proper layering and structure
  2. Customization System - Prompt-based system for customizing boards
  3. Component Integration - Ability to embed SVG kanban boards in MDX/Markdown
  4. Documentation - Guide for creating and using custom kanban boards

Components to Create​

  1. Base SVG Template (/static/img/kanban-structure.svg)

    • 5-column layout with distinct color themes
    • Post-it note style cards with drop shadows
    • Professional typography and spacing
    • Responsive design that scales properly

  2. Customization Prompt (prompts/draw/customize-kanban-board.md)

    • Column configuration (names, colors, themes)
    • Task card creation with proper formatting
    • Priority system with Jira-style labels
    • Visual hierarchy and sorting rules

  3. Documentation (docs/6-techniques/3-blogging-techniques/2-embed-diagrams/diagrams-kanban-customization.mdx)

    • Usage guide for creating custom boards
    • Embedding examples in MDX
    • Best practices and technical considerations

Execution Results / Attempts​

✅ Component System Created (2025-01-15)​

Work Period: January 15, 2025

Key Accomplishments:

  • Created base SVG template (kanban-structure.svg) with proper layer structure
  • Developed comprehensive customization prompt for AI-assisted board generation
  • Documented usage patterns and embedding methods
  • Established workflow for creating custom kanban boards

Components Created:

  • Base SVG Template (/static/img/kanban-structure.svg)

    • 2781 × 1623 pixel dimensions
    • 5-column layout with distinct color themes
    • Proper layer structure (backgrounds → headers → cards)
    • Professional styling with drop shadows and typography

  • Customization Prompt (prompts/draw/customize-kanban-board.md)

    • Step-by-step guide for customizing SVG template
    • Column configuration instructions
    • Task card generation guidelines
    • Priority system implementation

  • Documentation (docs/6-techniques/3-blogging-techniques/2-embed-diagrams/diagrams-kanban-customization.mdx)

    • Usage examples for embedding SVG kanban boards
    • Multiple embedding methods (component import, image reference, inline SVG)
    • Best practices for content and design
    • Technical considerations for proper rendering

Usage Pattern:

import KanbanExample from '@site/static/img/kanban-example.svg';

<div style={{ width: '100%', maxWidth: '800px', margin: '0 auto' }}>
  <KanbanExample style={{ width: '100%', height: 'auto' }} />
</div>

Features:

  • ✅ Custom column names and workflow stages
  • ✅ Task cards with titles, descriptions, and priorities
  • ✅ Jira-style priority labels with color coding
  • ✅ Professional color schemes and visual hierarchy
  • ✅ Proper SVG layering for optimal rendering
  • ✅ Responsive design that scales properly

Value Proposition:

  • Time Savings: 2-3 hours saved per custom board vs manual SVG creation
  • Annual ROI: $750-$1,125 in value for knowledge workers
  • Quality: Professional-grade SVG output with zero syntax errors
  • Flexibility: 100% customizable workflows and styling

Related Blog Post:

Status: Component system successfully created and documented. The SVG kanban board system is production-ready and being used in documentation for visual project management.