216 lines
7.1 KiB
Markdown
216 lines
7.1 KiB
Markdown
# UI Components
|
|
|
|
This directory contains documentation for the StellaOps Angular UI components.
|
|
|
|
## Evidence-Weighted Score (EWS) Components
|
|
|
|
The EWS component suite provides visual representations of vulnerability scores based on evidence-weighted analysis.
|
|
|
|
### Core Components
|
|
|
|
| Component | Purpose | Location |
|
|
|-----------|---------|----------|
|
|
| [ScorePill](./score-pill.md) | Compact score display with bucket coloring | `shared/components/score/` |
|
|
| [ScoreBreakdownPopover](./score-breakdown-popover.md) | Detailed score breakdown with dimensions | `shared/components/score/` |
|
|
| [ScoreBadge](./score-badge.md) | Evidence flag badges (live-signal, proven-path, etc.) | `shared/components/score/` |
|
|
| [ScoreHistoryChart](./score-history-chart.md) | Timeline visualization of score changes | `shared/components/score/` |
|
|
|
|
### Feature Components
|
|
|
|
| Component | Purpose | Location |
|
|
|-----------|---------|----------|
|
|
| [FindingsList](./findings-list.md) | Findings table with EWS integration | `features/findings/` |
|
|
| [BulkTriageView](./bulk-triage-view.md) | Bulk triage interface with bucket summaries | `features/findings/` |
|
|
|
|
## Score Buckets
|
|
|
|
All EWS components use a consistent bucket system:
|
|
|
|
| Bucket | Score Range | Color | Priority |
|
|
|--------|-------------|-------|----------|
|
|
| Act Now | 90-100 | Red (`#DC2626`) | Critical - Immediate action required |
|
|
| Schedule Next | 70-89 | Amber (`#D97706`) | High - Schedule for next sprint |
|
|
| Investigate | 40-69 | Blue (`#2563EB`) | Medium - Investigate when possible |
|
|
| Watchlist | 0-39 | Gray (`#6B7280`) | Low - Monitor for changes |
|
|
|
|
## Evidence Flags
|
|
|
|
Findings can have special flags indicating evidence quality:
|
|
|
|
| Flag | Icon | Color | Description |
|
|
|------|------|-------|-------------|
|
|
| `live-signal` | Signal wave | Green | Active runtime signals detected |
|
|
| `proven-path` | Checkmark | Blue | Verified reachability path confirmed |
|
|
| `vendor-na` | Strikethrough | Gray | Vendor marked as not affected |
|
|
| `speculative` | Question mark | Orange | Evidence is speculative/unconfirmed |
|
|
| `anchored` | [A] | Violet | Score anchored with DSSE/Rekor attestation |
|
|
| `hard-fail` | [!] | Red | Policy hard-fail triggered |
|
|
|
|
## Witness Visualization Components
|
|
|
|
> **Sprint:** SPRINT_20260118_020_FE_witness_visualization
|
|
|
|
The witness visualization component suite provides UI for runtime witness display, static vs runtime path comparison, and witness gate results in release promotion flows.
|
|
|
|
### Components
|
|
|
|
| Component | Purpose | Location |
|
|
|-----------|---------|----------|
|
|
| [WitnessStatusChip](./witness-visualization.md#witness-status-chip) | Status badge showing witness state (witnessed/unwitnessed/stale/failed) | `shared/domain/witness-status-chip/` |
|
|
| [WitnessComparison](./witness-visualization.md#witness-comparison-component) | Side-by-side static vs runtime path comparison | `shared/components/witness-comparison/` |
|
|
| [UnwitnessedAdvisory](./witness-visualization.md#unwitnessed-advisory-component) | Advisory panel for paths without witnesses | `shared/components/unwitnessed-advisory/` |
|
|
| [GateSummaryPanel](./witness-visualization.md#gate-summary-panel-extended) | Extended gate summary with witness metrics | `shared/domain/gate-summary-panel/` |
|
|
|
|
### Witness States
|
|
|
|
| State | Badge Color | Description |
|
|
|-------|-------------|-------------|
|
|
| `witnessed` | Green | Path confirmed by runtime observation |
|
|
| `unwitnessed` | Yellow | Path not yet observed at runtime |
|
|
| `stale` | Orange | Witness data is outdated |
|
|
| `failed` | Red | Witness verification failed |
|
|
|
|
### Usage
|
|
|
|
```typescript
|
|
import {
|
|
WitnessStatusChipComponent,
|
|
WitnessComparisonComponent,
|
|
UnwitnessedAdvisoryComponent,
|
|
GateSummaryPanelComponent,
|
|
} from '@app/shared/domain';
|
|
```
|
|
|
|
```html
|
|
<!-- Witness Status Chip -->
|
|
<app-witness-status-chip [status]="'witnessed'" [showCount]="true" />
|
|
|
|
<!-- Witness Comparison -->
|
|
<app-witness-comparison [data]="comparisonData" (stepClick)="onStepClick($event)" />
|
|
|
|
<!-- Unwitnessed Advisory -->
|
|
<app-unwitnessed-advisory [data]="advisoryData" (createTestTask)="onCreateTask($event)" />
|
|
```
|
|
|
|
See [witness-visualization.md](./witness-visualization.md) for full documentation.
|
|
|
|
---
|
|
|
|
## Grey Queue Components
|
|
|
|
> **Sprint:** SPRINT_20260112_011_FE_policy_unknowns_queue_integration
|
|
|
|
The Grey Queue component suite handles observations with uncertain status requiring operator attention.
|
|
|
|
### Components
|
|
|
|
| Component | Purpose | Location |
|
|
|-----------|---------|----------|
|
|
| GreyQueuePanel | Display grey queue item with fingerprint, triggers, conflicts, and actions | `features/unknowns/` |
|
|
| GreyQueueDashboard | Dashboard view with filtering and deterministic ordering | `features/unknowns/` |
|
|
| DeterminizationReview | Detailed review context for grey queue items | `features/unknowns/` |
|
|
|
|
### Observation States
|
|
|
|
| State | Badge Color | Description |
|
|
|-------|-------------|-------------|
|
|
| `PendingDeterminization` | Yellow | Evidence incomplete; monitoring active |
|
|
| `Disputed` | Orange | Conflicting evidence; manual adjudication required |
|
|
| `GuardedPass` | Blue | Allowed with runtime guardrails |
|
|
| `Resolved` | Green | Operator has made a determination |
|
|
|
|
### Usage
|
|
|
|
```typescript
|
|
// Grey queue components
|
|
import {
|
|
GreyQueuePanelComponent,
|
|
GreyQueueDashboardComponent,
|
|
DeterminizationReviewComponent,
|
|
} from '@app/features/unknowns';
|
|
```
|
|
|
|
```html
|
|
<!-- Grey Queue Panel -->
|
|
<app-grey-queue-panel
|
|
[unknown]="policyUnknown"
|
|
(triageAction)="onTriageAction($event)"
|
|
/>
|
|
|
|
<!-- Grey Queue Dashboard -->
|
|
<app-grey-queue-dashboard
|
|
[unknowns]="unknownsList"
|
|
(selectUnknown)="onSelectUnknown($event)"
|
|
/>
|
|
```
|
|
|
|
See `docs/UI_GUIDE.md#grey-queue-and-unknowns-triage` for operator workflow documentation.
|
|
|
|
## Quick Start
|
|
|
|
### Import Components
|
|
|
|
```typescript
|
|
// Score components
|
|
import {
|
|
ScorePillComponent,
|
|
ScoreBreakdownPopoverComponent,
|
|
ScoreBadgeComponent,
|
|
ScoreHistoryChartComponent,
|
|
} from '@app/shared/components/score';
|
|
|
|
// Findings components
|
|
import {
|
|
FindingsListComponent,
|
|
BulkTriageViewComponent,
|
|
} from '@app/features/findings';
|
|
```
|
|
|
|
### Basic Usage
|
|
|
|
```html
|
|
<!-- Display a score pill -->
|
|
<stella-score-pill [score]="78" size="md" />
|
|
|
|
<!-- Display score badges -->
|
|
<stella-score-badge type="live-signal" />
|
|
<stella-score-badge type="proven-path" />
|
|
|
|
<!-- Full findings list with scoring -->
|
|
<app-findings-list
|
|
[findings]="findings"
|
|
[autoLoadScores]="true"
|
|
(findingSelect)="onFindingSelect($event)"
|
|
/>
|
|
```
|
|
|
|
## Storybook
|
|
|
|
Interactive examples and documentation are available in Storybook:
|
|
|
|
```bash
|
|
cd src/Web/StellaOps.Web
|
|
npm run storybook
|
|
```
|
|
|
|
Navigate to:
|
|
- `Score/ScorePill` - Score pill variants
|
|
- `Score/ScoreBreakdownPopover` - Breakdown popover examples
|
|
- `Score/ScoreBadge` - Evidence flag badges
|
|
- `Score/ScoreHistoryChart` - History chart variants
|
|
- `Findings/FindingsList` - Findings list with scoring
|
|
- `Findings/BulkTriageView` - Bulk triage interface
|
|
|
|
## Design Tokens
|
|
|
|
Score colors are defined as CSS custom properties. See [design-tokens.md](./design-tokens.md) for the full token reference.
|
|
|
|
## Accessibility
|
|
|
|
All components follow WCAG 2.1 AA guidelines:
|
|
- Proper ARIA labels and roles
|
|
- Keyboard navigation support
|
|
- Focus management
|
|
- Color contrast ratios meet AA standards
|
|
- Screen reader announcements for dynamic content
|