Component Directory

All components live under foundation/static/main/src/components/. Each feature area has its own directory with an optional __tests__/ subdirectory.

---

Pages (src/pages/)

LensList.tsx

Legacy lens card grid. Shows all accessible lenses as cards with issue counts, sync agent counts, and relative timestamps. Supports hover-to-prefetch (calls prefetchLensView on mouseenter). Includes rename/delete/share kebab menus.

LensMenu.tsx

Replacement for LensList — a two-pane layout with a sidebar listing lenses and a preview pane showing stats, collaborators, and recent activity for the selected lens. Also contains RenameDialog and DeleteDialog modal components.

LensView.tsx

The main orchestrator component. Owns all data state for the active lens and delegates rendering to sub-components. Decomposed into 12+ custom hooks in pages/lens-view/:

Hook	Responsibility
useLensContextBootstrap	Load field metadata, priorities, user prefs, admin status
useLensDataLoader	Fetch lens data, manage nodes/views/syncAgents state
useLensViewDraft	Track view configuration (columns, density, formatting, pipeline) with dirty/save/revert
useLensDialogState	Boolean state for all dialog/overlay open states
useLensIncrementalSync	Realtime and manual refresh — incremental node diffing
useLensRealtimeController	Forge Realtime subscription setup and teardown
useLensSchedulingController	Auto-schedule engine coordination
useLensSelection	Row selection state and multi-select operations
useLensInspectorState	Inspector panel open/close, section expand/collapse
useLensExport	CSV and timeline export logic
useLensCreateController	Inline issue creation queue and state

Sub-components in pages/lens-view/:

• LensViewMainPane — grid + Gantt split-pane layout
• LensViewInspector — inspector panel with all sections
• LensViewOverlays — dialogs, modals, command palette, tour

AdminPage.tsx

Lazy-loaded admin dashboard for feature flags and monitoring.

---

Grid (src/components/Grid/)

The largest and most complex component directory. Contains the AG Grid wrapper and all supporting renderers.

HierarchyGrid.tsx (~89KB)

The core grid component. A forwardRef component exposing HierarchyGridHandle for imperative operations. Key responsibilities:

• Converts HierarchyNode[] into flat rows via buildFlatRows() (depth-first tree walk)
• Builds AG Grid ColDef[] via buildColumnDefs() from columns.tsx
• Registers 20+ inline cell editors (TextEditor, StatusDropdown, AssigneePicker, etc.)
• Manages row selection, context menus, insert lines, and inline create panels
• Applies conditional formatting rules via evaluateRowRules()
• Executes the pipeline engine (sort/group/filter) via executePipeline()
• Handles column resize, reorder, wrap toggle, and header sort
• Coordinates with Gantt for row height synchronization

Key exported function:

export function buildFlatRows(nodes: HierarchyNode[]): FlatRow[]

Converts the backend’s breadth-first node array into a depth-first tree-walk order using treeWalkOrder(). This ordering is critical — any component rendering content aligned with grid rows must use the same depth-first ordering.

Props interface: ~50 props covering data, callbacks, display configuration, filtering, pipeline, and animation state.

columns.tsx (~40KB)

Builds AG Grid column definitions. The buildColumnDefs() function maps ColumnConfig[] to AG Grid ColDef[], handling:

• Summary column with indentation, expand/collapse chevrons, issue type icons, and description subtitles
• Field-specific renderers (status lozenges, priority icons, user avatars, date formatting, progress bars)
• Custom field type detection and editor assignment
• Column header menu integration

ColumnHeaderMenu.tsx

Per-column dropdown menu with sort, wrap text, hide column, icon toggle, and column filter options. Uses position: fixed with viewport clamping.

SummaryCell.tsx

Custom cell renderer for the summary column. Renders the hierarchical tree structure with:

• Depth-based indentation
• Expand/collapse chevrons
• Issue type icons (colored SVGs from issueTypeIcons.tsx)
• Flex item / milestone visual indicators
• Description subtitle (stacked below the summary text)
• Selection checkboxes and drag handles

Cell Renderers

File	Purpose
AssigneeCellRenderer.tsx	Avatar display (name, initials, or avatar image based on display mode)
StatusCellRenderer.tsx	Status lozenge with category-based coloring
DateCellRenderer.tsx	Formatted date with overdue/upcoming highlighting
DateTimeRenderer.tsx	Date+time display
RichTextRenderer.tsx	ADF (Atlassian Document Format) to HTML
IssueLinkRenderer.tsx	Issue link badges
UserCard.tsx	Assignee card (name + initials + avatar variants)
ProgressCellRenderer.tsx	Progress bar (resolution, status category, story points, or custom percent)
RollupRenderer.tsx	Aggregate/rollup values for parent rows
OptionLozengeRenderer.tsx	Generic option lozenge (select field values)
UrlLinkRenderer.tsx	Clickable URL links
FlagIconRenderer.tsx	Flagged/impediment icon
TimeTrackingRenderer.tsx	Time tracking display (original/remaining/logged)
NameLozengeRenderer.tsx	Name-based lozenge (components, versions)
CustomUserRenderer.tsx	Custom user field display
AttachmentRenderer.tsx	Attachment count/indicator

Other Grid Files

File	Purpose
WrapRowRenderer.tsx	Row wrapper for wrap-text mode (variable row heights)
ContextMenu.tsx	Right-click context menu (indent, outdent, delete, insert, view detail)
InsertLine.tsx	Visual insert indicator between rows for drag operations
InlineCreatePanel.tsx	Inline issue creation form that appears between grid rows
QuickAddRow.tsx	Quick-add row at the bottom of the grid
EmptyLensState.tsx	Empty state with import/create guidance
SumsBar.tsx	Summary bar showing totals (story points, issue count)
progress.ts	Progress computation (4 modes: resolution, status, story points, percent)
rollups.ts	Recursive rollup aggregation for parent nodes
statusUtils.ts	Status category color mapping
depthResolution.ts	Indent/outdent depth resolution logic
gridConstants.ts	Grid configuration constants
chips/	Chip sub-components (labels, versions, components)

---

Gantt (src/components/Gantt/)

The second-largest component directory. Implements a timeline/Gantt chart visualization synchronized with the grid.

GanttChart.tsx (~49KB)

The main Gantt component. Renders a scrollable timeline with:

• Time-scaled headers (day/week/month/quarter)
• Horizontal bars for issues with start/end dates
• Milestone diamonds for milestone nodes
• Dependency arrows between linked issues
• Group rollup brackets
• Resource capacity indicators
• Bar drag for date editing
• Dependency drag-to-link

GanttBar.tsx (~22KB)

Individual Gantt bar renderer. Supports:

• Configurable bar colors (by status, priority, issue type, or custom formatting)
• Bar labels (headline + subhead)
• Bar icons (issue type, priority, status, assignee avatar)
• Progress fill
• Drag handles for start/end date adjustment
• Dependency connection handles
• Critical path highlighting

Core Files

File	Purpose
ganttData.ts	extractGanttItems() — converts nodes to Gantt items using tree-walk ordering
types.ts	GanttItem, GanttConfig, TimeScale, DependencyEdge, and 20+ type definitions
constants.ts	Scale constants, color palettes, dimension constants
gantt-tokens.ts	Design token mapping for Gantt-specific colors
useGanttLayout.ts	Layout computation (column widths, date ranges, pixel positions)
useBarDrag.ts	Bar drag-and-drop for date editing with snap-to-grid
useDependencyDrag.ts	Dependency arrow creation via drag
useScrollSync.ts	Synchronized scrolling between grid and Gantt
useGanttUndo.ts	Undo/redo for Gantt date changes
useSmartNudge.ts	Smart nudge for overlapping bars
useScheduleLog.ts	Schedule change logging
rowGeometry.ts	Row Y-position calculation (must match grid row order)
dateUtils.ts	Date math (working days, date ranges, scale snapping)
labelUtils.ts	Bar label formatting

Advanced Features

File	Purpose
DependencyArrowLayer.tsx	SVG arrow rendering for issue dependencies
dependencyUtils.ts	Dependency graph utilities (cycle detection, path finding)
criticalPath.ts	Critical path calculation (longest dependency chain)
scheduleEngine.ts	Auto-scheduling engine (forward/backward pass)
resourceLeveling.ts	Resource leveling algorithm
resourceUtils.ts	Resource availability computation
cascadeEngine.ts	Date cascade propagation (parent/child date changes)
CascadeNotification.tsx	UI notification for cascading date changes
cascadeTypes.ts	Cascade operation type definitions

Panels and UI

File	Purpose
GanttConfigPanel.tsx	Gantt configuration panel (scale, date fields, color mode)
GanttFormattingPanel.tsx	Gantt-specific conditional formatting rules
GanttResourcePanel.tsx	Resource workload panel
GanttMilestone.tsx	Diamond milestone marker
GanttPointMarker.tsx	Point-in-time marker (single-date items)
GanttTimeHeader.tsx	Time scale header (day/week/month/quarter labels)
GanttTooltip.tsx	Hover tooltip for bars
GanttDivider.tsx	Resizable divider between grid and Gantt
GroupBoundingBoxLayer.tsx	Visual grouping boundaries
BarIcon.tsx	Icon renderer inside Gantt bars
DragDateBadges.tsx	Date badges shown during bar drag
DragToLinkOverlay.tsx	Visual overlay during dependency drag creation
SaveStatusIndicator.tsx	Auto-save status indicator
ZoomControls.tsx	Timeline zoom in/out buttons
LevelingPanel.tsx	Resource leveling control panel
SkillsPanel.tsx	Skills/capabilities panel
PlaceholderPanel.tsx	Placeholder resource panel
CapacityDetailPopup.tsx	Resource capacity detail popup
CrossStructureWorkloadView.tsx	Cross-lens workload aggregation view

---

InlineEdit (src/components/InlineEdit/)

All AG Grid cell editors. Each editor implements AG Grid’s cell editor interface via useGridCellEditor({}). See Inline Editing for the full system documentation.

Editor	Field Type	UI Pattern
TextEditor.tsx	Summary, text fields	<input> with focus/select on mount
NumberInput.tsx	Story points, numeric	<input type="number">
DatePicker.tsx	Due date, start date	Calendar <input type="date">
DateTimePicker.tsx	DateTime custom fields	Date + time inputs
StatusDropdown.tsx	Status	<select> with Jira transitions
PriorityDropdown.tsx	Priority	<select> with priorities
AssigneePicker.tsx	Assignee	Search input + avatar dropdown
ReporterPicker.tsx	Reporter	Search input + user dropdown
SprintDropdown.tsx	Sprint	<select> with active/future sprints
LabelsEditor.tsx	Labels	Multi-value tag input
SelectDropdown.tsx	Single-select custom	<select> with field options
MultiSelectDropdown.tsx	Multi-select custom	Checkbox list dropdown
CascadingSelectEditor.tsx	Cascading select	Nested parent/child selects
OptionSelectEditor.tsx	Complex select fields	Searchable option picker
ComponentPicker.tsx	Jira components	Multi-select component picker
VersionPicker.tsx	Fix versions	Version picker
MultiVersionPicker.tsx	Multiple versions	Multi-select version picker
GroupPicker.tsx	User groups	Group picker
MultiGroupPicker.tsx	Multiple groups	Multi-select group picker
CustomUserPicker.tsx	Custom user fields	User search picker
MultiUserPicker.tsx	Multi-user custom	Multi-user search picker
UrlTextEditor.tsx	URL fields	Text input with URL validation
IssueLinkEditor.tsx	Issue links	Link type + issue search
FlaggedToggleEditor.tsx	Flagged/impediment	Toggle editor

---

Toolbar (src/components/Toolbar/)

Toolbar.tsx

Main toolbar rendered above the grid. Contains:

• Add menu (issue, flex item, milestone)
• Sync agent controls
• View switcher
• Column picker
• Sort/group menu
• Timeline toggle
• Density selector
• Zoom controls
• Search input
• Fullscreen toggle

Supporting Components

File	Purpose
ColumnPicker.tsx	Column visibility toggle with custom field support
CreateIssueButton.tsx	Issue creation dropdown
LensSwitcherMenu.tsx	Quick lens switching dropdown
QuickFilterBar.tsx	Quick filter chips (status, assignee, priority, sprint, label)
SearchInput.tsx	Grid search input with match count
SortGroupMenu.tsx	Sort and group configuration
TimelineConfigModal.tsx	Timeline/Gantt configuration dialog
TimelineMenu.tsx	Timeline toggle and scale selection

---

Inspector (src/components/Inspector/)

Right-side panel (320px, 280px in compact density) with collapsible accordion sections.

InspectorPanel.tsx

Panel shell with open/close toggle. When collapsed, shows an icon strip for quick section access. Props include section icons, active section highlighting, and expand/collapse all.

InspectorToolbar.tsx

Toolbar rendered inside the inspector with section-specific controls.

AccordionSection.tsx

Reusable collapsible section with sectionId, badge, defaultExpanded, and onToggle props. Stores expand/collapse state in localStorage keyed by foundation-{lensId}-{sectionId}.

Sections (sections/)

File	Purpose
ColumnsSection.tsx	Column configuration and ordering
DisplaySection.tsx	Density, wrap rows, assignee display mode
ViewConfigSection.tsx	View save/revert, view properties
TimelineSection.tsx	Gantt configuration (scale, date fields, colors, labels)
PreferencesSection.tsx	User preferences (new tab, date format)
ExportShareSection.tsx	CSV export and sharing controls
ScheduleLogSection.tsx	Auto-schedule change log
DebugSection.tsx	Debug information (admin only)
MarketingCaptureSection.tsx	Marketing screenshot capture

---

Formatting (src/components/Formatting/)

ConditionalFormatDialog.tsx

Rule builder dialog for conditional formatting. Users define rules with field, operator, value, and styling (background color, text color, scope, bold).

evaluator.ts

The formatting rule engine. Exports:

• FormattingRule interface — rule definition with 18 operators
• evaluateCondition(rule, row) — tests a single rule against a row
• evaluateRowRules(rules, row) — returns combined styling for a row

Supports operators: equals, not_equals, contains, not_contains, is_empty, is_not_empty, greater_than, less_than, between, in_the_past, today, in_the_next_n_days, before, after, is_one_of, is_none_of, and more. Handles custom fields by parsing the custom_fields JSON blob.

---

Filters (src/components/Filters/)

File	Purpose
FilterPanel.tsx	Full filter configuration panel
FilterBanner.tsx	Active filter summary bar shown above grid
ColumnFilterDropdown.tsx	Per-column filter dropdown in column headers

---

Views (src/components/Views/)

ViewSelector.tsx

View tab bar for switching between saved views. Supports create, rename, delete, set default, and dirty indicator.

---

Pipeline (src/components/Pipeline/)

Visual pipeline builder for sort/group/filter operations that compose into a processing chain.

File	Purpose
PipelineStudio.tsx	Full pipeline editor UI
PipelineSummary.tsx	Compact summary of active pipeline operations
AddOperationMenu.tsx	Menu to add sort/group/filter operations
OperationCard.tsx	Individual operation card (draggable, configurable)
FlowConnector.tsx	Visual connector between pipeline steps
configs/	Per-operation-type configuration forms

---

DnD (src/components/DnD/)

useDragDrop.ts

Custom hook wrapping @dnd-kit for tree node drag and drop. Handles:

• Reparenting (drop on a node to make it a child)
• Reordering (drop between nodes)
• Visual drop indicators
• Position calculation (gap=100 strategy)

---

SyncAgents (src/components/SyncAgents/)

File	Purpose
SyncAgentSection.tsx	List of sync agents with execute/edit/delete controls
SyncAgentForm.tsx	Create/edit sync agent form (JQL query, type, parent node)

---

Sharing (src/components/Sharing/)

ShareDialog.tsx

Permission management dialog. Lists current grants, allows adding users/groups/roles/everyone with permission levels (view, edit, control).

---

Import (src/components/Import/)

File	Purpose
ImportHub.tsx	Hub page with import options
ProjectPicker.tsx	Jira project search and selection for import
CsvImportWizard.tsx	Multi-step CSV import wizard
BigPictureImport.tsx	BigPicture app data import
StructureImport.tsx	Structure app data import
ExportFileImport.tsx	Lens export file import
ImportSection.tsx	Reusable import section component

---

Templates (src/components/Templates/)

TemplatePicker.tsx

Template selection dialog for creating new lenses from predefined templates (e.g., Agile Board, Release Plan, Resource Plan).

---

Onboarding (src/components/Onboarding/)

File	Purpose
OnboardingWelcome.tsx	Welcome dialog for first-time users
FirstLensTour.tsx	Guided tour overlay for new lens creation
firstLensTourState.ts	Tour state management (queue, seen tracking)

---

BulkActions (src/components/BulkActions/)

File	Purpose
SelectBar.tsx	Multi-select action bar (delete, move, change status/priority/assignee)
DeleteConfirmDialog.tsx	Bulk delete confirmation
selectBarUtils.ts	Selection utilities (getDescendants, buildChildrenMap)

---

BulkAdd (src/components/BulkAdd/)

BulkAddDialog.tsx

Dialog for bulk-adding multiple issues at once (by JQL or issue keys).

---

CommandPalette (src/components/CommandPalette/)

CommandPalette.tsx

Cmd+K / Ctrl+K search overlay. Searches across issues, lenses, actions, and navigation targets.

---

IssueDetail (src/components/IssueDetail/)

IssueDetailPanel.tsx

Right-side panel showing full issue details when an issue is selected. Displays all fields, description, comments, and links.

---

Announcements (src/components/Announcements/)

AnnouncementPopup.tsx

Global announcement popup mounted in App.tsx. Reads from config/announcements.ts, filters by dismissed state/dates/audience, and queues multiple announcements.

---

Feedback (src/components/Feedback/)

File	Purpose
FeedbackButton.tsx	Floating feedback button
FeedbackModal.tsx	Feedback submission dialog
ChatPanel.tsx	Chat-style feedback panel

---

LensMenu (src/components/LensMenu/)

File	Purpose
LensMenuSidebar.tsx	Sidebar with lens list, search, and create
LensPreviewPane.tsx	Preview pane showing stats and recent activity
LensMenuItem.tsx	Individual lens list item
PreviewCollaborators.tsx	Collaborator avatars in preview
PreviewStats.tsx	Stat cards in preview pane

---

Admin (src/components/Admin/)

MonitoringDashboard.tsx

Admin monitoring dashboard showing system stats, cache health, and API usage.

---

ResourceAdmin (src/components/ResourceAdmin/)

File	Purpose
ResourceAdminModal.tsx	Main resource administration modal
TeamsPanel.tsx	Team management
SkillsPanel.tsx	Skills/capabilities management
AbsencePanel.tsx	Absence/leave management
HolidayCalendarPanel.tsx	Holiday calendar configuration
PlaceholderPanel.tsx	Placeholder resource management

---

Common (src/components/common/)

Shared UI primitives used across the application:

File	Purpose
ErrorBanner.tsx	Error message banner
BudgetBanner.tsx	Rate limit budget warning
RetryBanner.tsx	Network retry indicator
OfflineBanner.tsx	Offline state indicator
LicenseBanner.tsx	License enforcement banner
Spinner.tsx	Loading spinner
GridSkeleton.tsx	Grid loading skeleton
LensLoadingScreen.tsx	Full-page loading screen for lens data
Tooltip.tsx	Tooltip component (position: fixed, viewport-clamped)
tooltipContent.ts	Centralized tooltip text definitions
InlineDialog.tsx	Inline dialog (popover)
HighlightText.tsx	Search term highlight in text
OpenSourceDialog.tsx	Open source license dialog