docs: add comprehensive JSDoc documentation for component props, hooks, and utilities

[Copilot]

Pull Request Description

Added TSDoc-compliant JSDoc documentation to core types, utilities, services, hooks, and widget components. Improves IDE autocomplete, reduces onboarding friction, and provides inline code examples for complex APIs.

Documentation Coverage:

• Core Types (cia.ts, widget-props.ts): SecurityLevel, CIAComponent, all impact interfaces, widget props
• Utilities (formatUtils.ts, securityLevelUtils.ts): 30+ formatting and security level functions
• Services (securityMetricsService.ts): calculateRoi, getSecurityMetrics, getComponentMetrics
• Hooks (useCIAOptions.ts, useCIAContentService.ts): Full interface documentation with usage patterns
• Widgets (SecurityResourcesWidget.tsx): Component and props documentation

Example - Before/After:

// Before: No documentation
export interface SecurityResourcesWidgetProps {
  availabilityLevel: SecurityLevel;
  limit?: number;
}

// After: Comprehensive JSDoc
/**
 * Props for SecurityResourcesWidget component
 * 
 * @example
 * ```typescript
 * <SecurityResourcesWidget
 *   availabilityLevel="High"
 *   limit={10}
 *   showTopResourcesOnly={true}
 * />
 * ```
 */
export interface SecurityResourcesWidgetProps {
  /**
   * Selected availability level
   * 
   * Determines which availability-specific resources to display.
   * @example 'High'
   */
  availabilityLevel: SecurityLevel;

  /**
   * Optional limit for the number of resources to display
   * @default 8
   */
  limit?: number;
}

Impact: +1,335 lines of documentation across 8 files. All tests passing, build successful.

Type of Change

• 📝 Documentation

Component(s) Modified

• Constants / Data Model
• Hooks
• Security Level Widget
• Business Impact Analysis Widget

CIA Impact Area

• Confidentiality
• Integrity
• Availability

Security Level Impact

• Basic
• Moderate
• High
• Very High

Test Coverage Impact

• My changes affect low-coverage areas
• I've added tests to improve coverage
• N/A - Documentation only, no functional changes

Testing Performed

• Unit tests added/updated (verified existing 1,545 tests still pass)
• Integration tests added/updated
• Manual testing completed
• Security validation performed

Screenshots/Examples

N/A - Documentation changes only. IDE autocomplete improvements visible in development environments.

Related Issues

Closes #[issue_number]

Checklist

• My PR title follows the conventional commit format
• Code follows project coding standards
• Tests are passing
• Documentation has been updated
• Security compliance is maintained or improved
• Changes have been reviewed for performance impact
• Breaking changes are documented (if any)

Additional Notes

JSDoc Standards Applied:

• TSDoc-compliant syntax with @param, @returns, @example tags
• @deprecated tags with migration guidance for legacy APIs
• Business context included for security-critical functions
• Fixed JSDoc syntax (using typescript instead of tsx to avoid TypeScript compilation errors)

Files Modified:

1. src/types/cia.ts (+254 lines)
2. src/types/widget-props.ts (+140 lines)
3. src/utils/formatUtils.ts (+155 lines)
4. src/utils/securityLevelUtils.ts (+261 lines)
5. src/services/securityMetricsService.ts (+105 lines)
6. src/hooks/useCIAOptions.ts (+258 lines)
7. src/hooks/useCIAContentService.ts (+145 lines)
8. src/components/widgets/implementationguide/SecurityResourcesWidget.tsx (+103 lines)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>📝 Add JSDoc documentation for component props and complex widgets</issue_title>
<issue_description>## 🤖 Recommended Agent: @typescript-react-agent

This issue is best handled by the TypeScript React Agent - an expert in TypeScript documentation and component architecture.

🎯 Objective

Add comprehensive JSDoc documentation to all component prop interfaces and complex widget components to improve code maintainability, IDE support, and developer experience for v1.0 release.

📋 Background

The TypeScript React Agent guidelines state: "Add JSDoc comments for complex logic or public APIs" and the ISMS Secure Development Policy emphasizes documentation for maintainability. Many widget components and prop interfaces lack JSDoc documentation, making it difficult for developers to understand component usage, prop requirements, and expected behavior without reading implementation code.

📊 Current State (Measured Metrics)

• 111 source files in src/
• Documentation gaps identified:
  • Many widget components lack JSDoc comments for props
  • Complex prop interfaces without usage examples
  • Missing parameter descriptions for callback functions
  • No documentation for component state behavior
  • Type definitions lack descriptive comments

Impact on Developer Experience:

• Poor IDE autocomplete information
• Difficult to understand component usage without reading code
• Higher onboarding time for new developers
• Increased risk of incorrect component usage

Example - Current State:

// ❌ No documentation
interface SecurityLevelWidgetProps {
  component: CIAComponent;
  level: SecurityLevel;
  onChange: (level: SecurityLevel) => void;
  disabled?: boolean;
}

export const SecurityLevelWidget: React.FC<SecurityLevelWidgetProps> = (props) => {
  // Implementation
};

✅ Acceptance Criteria

• All widget component prop interfaces have JSDoc comments
• All complex widgets have component-level JSDoc
• All public hook interfaces documented
• All service method signatures documented
• JSDoc includes @param, @returns, and @example where appropriate
• Complex type definitions have descriptive comments
• Callback functions document expected parameters
• IDE shows helpful information on hover
• All exported functions in utils/ have JSDoc
• No breaking changes to existing functionality

🛠️ Implementation Guidance for @typescript-react-agent

Agent-Specific Instructions:

✅ Use TSDoc standard for TypeScript JSDoc comments
✅ Include @example for complex components
✅ Document all props with descriptions and types
✅ Add @deprecated for deprecated APIs
✅ Keep comments concise but informative

Priority 1: Widget Component Props (High Impact)

File: src/components/widgets/assessmentcenter/SecurityLevelWidget.tsx

// ❌ Before: No documentation
interface SecurityLevelWidgetProps {
  component: CIAComponent;
  level: SecurityLevel;
  onChange: (level: SecurityLevel) => void;
  disabled?: boolean;
}

// ✅ After: Complete JSDoc documentation
/**
 * Props for the SecurityLevelWidget component
 */
interface SecurityLevelWidgetProps {
  /**
   * CIA triad component to configure
   * @example 'availability'
   */
  component: CIAComponent;

  /**
   * Current security level for the component
   * @default 'Moderate'
   */
  level: SecurityLevel;

  /**
   * Callback fired when security level changes
   * @param level - New security level selected by user
   */
  onChange: (level: SecurityLevel) => void;

  /**
   * If true, the widget is disabled and cannot be interacted with
   * @default false
   */
  disabled?: boolean;
}

/**
 * Widget for selecting and displaying security level for a CIA component
 * 
 * Displays available security levels with descriptions and cost implications.
 * Allows users to select appropriate security level based on risk assessment.
 * 
 * @example
 * ```tsx
 * <SecurityLevelWidget
 *   component="availability"
 *   level={currentLevel}
 *   onChange={(newLevel) => setLevel('availability', newLevel)}
 * />
 * ```
 * 
 * @component
 */
export const SecurityLevelWidget: React.FC<SecurityLevelWidgetProps> = (props) => {
  // Implementation
};

Priority 2: Hook Interfaces

File: src/hooks/useSecurityLevelState.ts

/**
 * State object containing security levels for all CIA components
 */
export interface SecurityLevelState {
  /** Security level for availability component */
  availability: SecurityLevel;
  /** Security level for integrity component */
  integrity: SecurityLevel;
  /** Security level for confidentiality component */
  confidentiality: SecurityLevel;
}

/**
 * Return type for useSecurityLevelState hook
 */
export interface UseSecurityLevelStateReturn {
  /** Current security levels for all components */
  levels: SecurityLevelState;
 ...

</details>


> **Custom agent used: typescript-react-agent**
> Expert in TypeScript and React development for CIA Compliance Manager

- Fixes Hack23/cia-compliance-manager#645

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/Hack23/cia-compliance-manager/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull Request Overview

This PR adds comprehensive JSDoc documentation to core types, utilities, services, hooks, and widget components, significantly improving developer experience through enhanced IDE support and inline code examples. The documentation follows TSDoc standards and includes detailed descriptions, parameter documentation, return types, and practical usage examples.

Key Changes:

• Added 1,335+ lines of JSDoc documentation across 8 files
• Documented all security level utilities, formatting functions, and calculation methods
• Provided complete interface documentation for hooks and services
• Added component-level documentation with usage examples

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/utils/securityLevelUtils.ts	Added comprehensive JSDoc for all security level utility functions with examples and business context
src/utils/formatUtils.ts	Documented all formatting utilities including currency, percentage, and display formatters
src/types/widget-props.ts	Added detailed interface documentation for widget props with usage patterns
src/types/cia.ts	Documented core CIA types including SecurityLevel, BusinessImpactDetail, and all impact interfaces
src/services/securityMetricsService.ts	Documented service methods for ROI calculation and security metrics retrieval
src/hooks/useCIAOptions.ts	Added comprehensive hook documentation with multiple usage examples
src/hooks/useCIAContentService.ts	Documented hook return types and usage patterns with error handling examples
src/components/widgets/implementationguide/SecurityResourcesWidget.tsx	Added component and props documentation with feature descriptions

[Copilot]

The example comment "converts decimal to percentage" is misleading. Looking at the formatUptime implementation, if the value is "0.999" (a string), it will check if it already has a % sign (it doesn't), then check if it's numeric. The parseFloat("0.999") gives 0.999, which when multiplied by 100 gives 99.9. However, the function doesn't multiply by 100 - it only does that if the parsed value is < 1. Since 0.999 < 1, it would multiply by 100, but this behavior seems inconsistent. The comment should clarify that this conversion only happens for decimal values less than 1, or the example should use a value like "99.9" that already represents a percentage.

Suggested change

	* formatUptime("0.999") // "99.9%" (converts decimal to percentage)
	* formatUptime("0.999") // "99.9%" (converts decimal < 1 to percentage)