UI Components & Loading States#

Overview#

Implement reusable UI components and loading state patterns for consistent user experience across the application. This ticket creates the foundational UI building blocks used by other tickets.

Scope#

Included:

• ViewComponents for all new UI patterns
• Stimulus controllers for interactivity (tabs, toasts)
• Skeleton loader components for loading states
• Toast notification system
• Component templates (ERB files)
• Component tests

Excluded:

• Integration with specific pages (handled by feature tickets)
• Existing components (StatusPill, ProgressBar already exist)

Acceptance Criteria#

ViewComponents#

AgentStatusCardComponent:

• Component created: app/components/agent_status_card_component.rb
• Template created: app/components/agent_status_card_component.html.erb
• Displays: status badge, agent name, hash rate, error indicator
• Uses existing StatusPillComponent for status badge
• Error indicator shows count if > 0 errors in last 24h
• Card links to agent detail page
• Component delegates to Turbo Stream broadcast partials for real-time updates
• Individual card sections update without full-page refresh
• State, last seen, hash rate, and errors broadcast independently
• Broadcast partials are minimal and don't reference current_user
• Stable DOM IDs enable targeted replacement
• error_count_last_24h method removed from component class, moved to partial logic
• Fragment cache key uses cache: agent (not cache: true) to incorporate cache_key_with_version with agent's updated_at timestamp, preventing stale cached cards when agent state or errors change

Agent Index Partials:

Four targeted partials handle independent Turbo Stream broadcasts for agent index cards:

• _index_state.html.erb - Displays agent state badge with color coding (online/offline/error). Uses StatusPillComponent and has a stable DOM ID using dom_id(agent, :index_state) pattern.
• _index_last_seen.html.erb - Shows relative time since last heartbeat ("X minutes ago" or "Not seen yet"). DOM ID: dom_id(agent, :index_last_seen).
• _index_hash_rate.html.erb - Displays current hash rate or "N/A" fallback. DOM ID: dom_id(agent, :index_hash_rate).
• _index_errors.html.erb - Shows error count badge for last 24 hours (excluding info severity). Entire <div> has DOM ID: dom_id(agent, :index_errors). Text turns red when error count > 0.

Each partial:

• Has a stable DOM ID for targeted replacement
• Is broadcast via broadcast_replace_later_to callback (runs in background job)
• Runs WITHOUT access to current_user or session (background job context)
• Contains only the minimum HTML needed for that specific UI element

Broadcast Callbacks:

Agent model callbacks trigger targeted broadcasts:

after_update_commit :broadcast_index_state, if: -> { saved_change_to_state? }
after_update_commit :broadcast_index_last_seen, if: -> { saved_change_to_last_seen_at? }

AgentError model callback triggers Agent#broadcast_index_errors:

after_create_commit -> { agent.broadcast_index_errors }

The Agent#broadcast_index_errors method follows the same pattern as broadcast_index_state and broadcast_index_last_seen: it uses broadcast_replace_later_to with a stable DOM ID (dom_id(agent, :index_errors)) to update the error count display on agent index cards in real-time. Keeping the broadcast contract on the Agent model maintains consistency across all agent index card updates.

HashcatStatus updates trigger hash rate broadcasts via update_agent_metrics method (uses update_columns to bypass callbacks, then manually broadcasts).

AgentDetailTabsComponent:

• Component created: app/components/agent_detail_tabs_component.rb
• Template created: app/components/agent_detail_tabs_component.html.erb
• Renders slots: overview_tab, errors_tab, configuration_tab, capabilities_tab
• Integrates with Stimulus tabs controller
• Preserves tab structure for Turbo Stream broadcasts

CampaignProgressComponent:

• Component created: app/components/campaign_progress_component.rb
• Template created: app/components/campaign_progress_component.html.erb
• Displays: progress bar, percentage text, ETA text
• Uses existing ProgressBarComponent or extends it
• Handles missing ETA gracefully ("Calculating...")

ErrorModalComponent:

• Component created: app/components/error_modal_component.rb
• Template created: app/components/error_modal_component.html.erb
• Displays: error message, severity badge, timestamp
• Uses Bootstrap modal component
• Severity badges: fatal/error (danger), warning (warning), info (info)

SystemHealthCardComponent:

• Component created: app/components/system_health_card_component.rb
• Template created: app/components/system_health_card_component.html.erb
• Displays: service name, status badge, latency, error message
• Status variants: healthy (success), unhealthy (danger), checking (secondary)
• Icons: check-circle (healthy), x-circle (unhealthy)

TaskActionsComponent:

• Component created: app/components/task_actions_component.rb
• Template created: app/components/task_actions_component.html.erb
• Conditional buttons: cancel, retry, reassign, view logs, download results
• Buttons shown based on task state and user permissions
• Uses plain Bootstrap button classes (btn btn-primary, btn btn-danger, btn-sm, etc.)

SkeletonLoaderComponent:

• Component created: app/components/skeleton_loader_component.rb
• Template created: app/components/skeleton_loader_component.html.erb
• Types supported: , ,
• Configurable count (default: 5)
• Uses CSS animations for shimmer effect
• Matches layout of actual content

ToastNotificationComponent:

• Component created: app/components/toast_notification_component.rb
• Template created: app/components/toast_notification_component.html.erb
• Variants: success, danger, warning, info
• Integrates with Stimulus toast controller
• Auto-dismiss after 5 seconds
• Positioned in top-right corner

Stimulus Controllers#

tabs_controller.js:

• Controller created: app/javascript/controllers/tabs_controller.js
• Targets: tab, panel
• Action: switch(event) - switches active tab
• Shows first tab by default on connect
• Updates active tab styling
• Hides/shows panels with d-none class

toast_controller.js:

• Controller created: app/javascript/controllers/toast_controller.js
• Values: autohide (boolean, default: true), delay (number, default: 5000)
• Initializes Bootstrap Toast on connect
• Auto-dismiss after delay
• Removes element from DOM after hidden
• Imports Bootstrap Toast component

Shared Partials#

• Toast partial created: app/views/shared/_toast.html.erb
• Toast container added to layout: file/views/layouts/application.html.erb
• Container positioned for toast display (top-right)

Testing#

• Component tests for all ViewComponents
• Stimulus controller tests for tabs_controller
• Stimulus controller tests for toast_controller
• Visual regression tests (optional, if using tools)
• Verify components work in air-gapped environment (no external assets)

Technical References#

• Core Flows: spec:50650885-e043-4e99-960b-672342fc4139/c565e255-83e7-4d16-a4ec-d45011fa5cad (Flow 6: Loading & Feedback Patterns)
• Tech Plan: spec:50650885-e043-4e99-960b-672342fc4139/f3c30678-d7af-45ab-a95b-0d0714906b9e (Component Architecture, Stimulus Controllers)
• Turbo Stream Broadcasts: doc.md (section "Turbo Stream Broadcasts")
• Agent Monitoring: ticket:50650885-e043-4e99-960b-672342fc4139/[Agent Monitoring & Real-Time Updates]

Dependencies#

Requires:

• None (foundational ticket)

Blocks:

• ticket:50650885-e043-4e99-960b-672342fc4139/[Agent Monitoring & Real-Time Updates] - Provides AgentStatusCardComponent, tabs controller
• ticket:50650885-e043-4e99-960b-672342fc4139/[Campaign Progress & ETA Display] - Provides CampaignProgressComponent, ErrorModalComponent
• ticket:50650885-e043-4e99-960b-672342fc4139/[Task Management Actions] - Provides TaskActionsComponent
• ticket:50650885-e043-4e99-960b-672342fc4139/[System Health Monitoring] - Provides SystemHealthCardComponent

Implementation Notes#

• Follow existing ViewComponent patterns in file/components/
• Use dry-initializer option syntax (already used in existing components)
• Inherit from ApplicationViewComponent
• Use plain Bootstrap HTML and utility classes for layout/structure
• ViewComponents should render Bootstrap HTML directly (no abstraction layer)
• Use Bootstrap utility classes: btn btn-primary, d-flex, gap-2, card, list-group, etc.
• Test components in isolation before integrating
• Ensure all assets (CSS, JS) are bundled for air-gapped deployment
• Use Bootstrap 5 components (already in stack)

Component Development Guidelines:

The Railsboot component abstraction layer has been removed (PR #706). All ViewComponents now use plain ERB templates with Bootstrap utility classes directly.

• Button patterns: <button class="btn btn-primary btn-sm">, <a href="..." class="btn btn-secondary">
• Layout utilities: d-flex, justify-content-between, align-items-center, gap-2, gap-3
• Card structure: <div class="card"><div class="card-body">...</div></div>
• List groups: <ul class="list-group"><li class="list-group-item">...</li></ul>
• Reference implementations: See agent_status_card_component.html.erb, agent_detail_tabs_component.html.erb for examples of plain Bootstrap HTML patterns

For detailed component patterns and theming guidelines, reference doc.md sections on "Catppuccin Macchiato Theme" and "Layout Grid". For frontend gotchas (navbar buttons, z-index utilities, Railsboot removal), reference doc.md section "Frontend & Accessibility".

Turbo Stream Broadcast Pattern:

The AgentStatusCardComponent demonstrates a reusable pattern for real-time component updates:

1. Extract Minimal Partials - Create small partials (_index_state.html.erb, _index_hash_rate.html.erb, _index_errors.html.erb) that wrap a single UI element with a stable DOM ID using dom_id(record, :suffix).

2. Model Callbacks - Use conditional after_update_commit callbacks (e.g., if: -> { saved_change_to_state? }) to broadcast only when specific attributes change, reducing unnecessary updates. The Agent#broadcast_index_errors method is called from the AgentError model's after_create_commit callback to keep the broadcast contract on the Agent model.

3. Background Job Context - Broadcast partials run in background jobs WITHOUT access to current_user or session. All data must come from the model or explicit locals.

4. Targeted Replacement - Use broadcast_replace_later_to with the stable DOM ID as the target to update individual sections without full-page refresh.

5. Fragment Cache Invalidation - When using fragment caching on index cards, use cache: agent (not cache: true) so that cache_key_with_version incorporates the agent's updated_at timestamp. This ensures cached cards are invalidated when agent state or errors change, preventing stale content from being served.

This pattern extends to other real-time components. See the Attack model's broadcast_index_state implementation for a similar approach. For constraints and gotchas, reference doc.md section "Turbo Stream Broadcasts".

Estimated Effort#

2-3 days (8 components + 2 Stimulus controllers + templates + tests)