From 0baf221ce9ddfaa8e856caa7978fe01c9f1c5f7c Mon Sep 17 00:00:00 2001 From: Denys Vuika Date: Wed, 23 Jul 2025 09:50:51 -0400 Subject: [PATCH] new docs for About component --- docs/core/components/about.component.md | 407 +++++++++++++++++++++++- 1 file changed, 392 insertions(+), 15 deletions(-) diff --git a/docs/core/components/about.component.md b/docs/core/components/about.component.md index b14bb44a8c..1e548aec5b 100644 --- a/docs/core/components/about.component.md +++ b/docs/core/components/about.component.md @@ -2,55 +2,432 @@ Title: About Component Added: v3.5.0 Status: Active -Last reviewed: 2022-11-11 +Last reviewed: 2025-07-23 --- -# [About Component](../../../lib/core/src/lib/about/about.component.ts "Defined in about.component.ts") +# About Component -Presentational component to display About information as a set of collapsible panels. +A flexible presentational component that displays information in collapsible accordion panels. The About Component is ideal for organizing application information, settings, or any content that benefits from a collapsible interface structure. + +## Overview + +The About Component creates an accordion-style interface using Angular Material's expansion panels. Each panel can contain any content and can be conditionally displayed. This component is commonly used for: + +- Application information and version details +- Feature lists and documentation +- Settings panels +- Help and support sections +- Plugin or extension information + +## Prerequisites + +Before using the About Component, ensure you have imported the necessary modules: + +```typescript +import { AboutComponent } from '@alfresco/adf-core'; +import { CommonModule } from '@angular/common'; + +@Component({ + selector: 'app-example', + imports: [CommonModule, AboutComponent], + template: ` + + ` +}) +export class ExampleComponent { + // Component logic +} +``` + +## API Reference + +### AboutComponent + +| Property | Type | Description | +|----------|------|-------------| +| `panels` | `QueryList` | Content children representing the panels to display | + +### AboutPanelDirective (adf-about-panel) + +| Property | Type | Required | Default | Description | +|----------|------|----------|---------|-------------| +| `label` | `string` | Yes | - | The title text displayed in the panel header | +| `automationId` | `string` | No | - | Data automation ID for testing purposes | ## Basic Usage +### Simple Panel Structure + ```html - + - +
+

My Application

+

Version: 1.0.0

+

Built with Angular and ADF

+
- + - +
    +
  • Document management
    • +
  • User authentication
    • +
  • Process workflows
    • +
``` -## Conditional Display - -You can wire each panel with the `*ngIf` conditions: +### Using Automation IDs for Testing ```html - + - + ``` -Where `devMode` is an example of an input property exposed by your component. +## Advanced Usage -Observables are also supported: +### Conditional Panel Display + +You can control panel visibility using Angular's structural directives: ```html - + + + +
+

Debug Tools

+ + +
+ + + + + + + + + + +``` + +### Working with Observables and Async Data + +```html + + + + + + + +
+ {{ permission.name }}: {{ permission.granted ? 'Granted' : 'Denied' }} +
+ + + + + + +

Loading permissions...

+ + + ``` + +### Dynamic Panel Generation + +```typescript +// Component logic +export class MyAboutComponent { + isDevelopmentMode = environment.production === false; + + extensions$ = this.extensionService.getExtensions(); + userPermissions$ = this.authService.getUserPermissions(); + + panels = [ + { + label: 'System Info', + content: 'system-info', + show: true + }, + { + label: 'Debug Tools', + content: 'debug-tools', + show: this.isDevelopmentMode + } + ]; + + clearCache(): void { + // Clear cache implementation + } + + showLogs(): void { + // Show logs implementation + } +} +``` + +```html + + + + + + + + + + + +``` + +## Styling and Customization + +### CSS Classes + +The About Component uses these CSS classes that you can customize: + +- `.adf-about-panel` - Main accordion container +- `.adf-about-panel-header` - Panel header styling +- `.adf-about-panel-header__title` - Panel title styling + +### Custom Styling Example + +```scss +// Custom panel styling +.adf-about-panel { + .mat-expansion-panel { + margin-bottom: 8px; + border-radius: 4px; + box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1); + + &:not(.mat-expanded) { + .mat-expansion-panel-header { + background-color: #f5f5f5; + } + } + } + + .adf-about-panel-header__title { + font-weight: 600; + color: #333; + } +} + +// Custom content styling +.about-content { + padding: 16px 0; + + h3 { + margin-top: 0; + color: #1976d2; + } + + .permission-item { + padding: 4px 0; + border-bottom: 1px solid #eee; + + &:last-child { + border-bottom: none; + } + } +} +``` + +## Accessibility Features + +The About Component inherits accessibility features from Angular Material's expansion panels: + +- **Keyboard Navigation**: Use Tab to navigate between panels, Enter/Space to expand/collapse +- **Screen Reader Support**: Panels are properly labeled and state changes are announced +- **ARIA Attributes**: Proper ARIA attributes are automatically applied +- **Focus Management**: Focus is managed correctly when panels are expanded/collapsed + +### Enhancing Accessibility + +```html + + + +
+

Current System Status

+

+ All systems are operational. +

+
+ + + +``` + +## Testing + +### Unit Testing Example + +```typescript +import { ComponentFixture, TestBed } from '@angular/core/testing'; +import { AboutComponent } from '@alfresco/adf-core'; +import { DebugElement } from '@angular/core'; +import { By } from '@angular/platform-browser'; + +describe('AboutComponent', () => { + let component: AboutComponent; + let fixture: ComponentFixture; + + beforeEach(async () => { + await TestBed.configureTestingModule({ + imports: [AboutComponent] + }).compileComponents(); + + fixture = TestBed.createComponent(AboutComponent); + component = fixture.componentInstance; + }); + + it('should create', () => { + expect(component).toBeTruthy(); + }); + + it('should display panels with correct labels', () => { + const panels = fixture.debugElement.queryAll( + By.css('[data-automation-id="system-info-panel"]') + ); + expect(panels.length).toBeGreaterThan(0); + }); +}); +``` + +### E2E Testing with Automation IDs + +```typescript +// Page object example +export class AboutPage { + async expandPanel(automationId: string): Promise { + const panel = element(by.css(`[data-automation-id="${automationId}"]`)); + const header = panel.element(by.css('.mat-expansion-panel-header')); + await header.click(); + } + + async isPanelExpanded(automationId: string): Promise { + const panel = element(by.css(`[data-automation-id="${automationId}"]`)); + const classes = await panel.getAttribute('class'); + return classes.includes('mat-expanded'); + } +} +``` + +## Best Practices + +### 1. Use Descriptive Labels + +```html + + + + + +``` + +### 2. Provide Automation IDs for Testing + +```html + + +``` + +### 3. Handle Loading States + +```html + + +
{{ data.content }}
+ + + + + + + + + + +``` + +### 4. Organize Related Information + +Group related information into logical panels to improve user experience and information architecture. + +## Common Use Cases + +### Application Information Dashboard + +```html + + + +
+

{{ appName }}

+

Version: {{ appVersion }}

+

Build: {{ buildNumber }}

+

Environment: {{ environment }}

+
+ + + + + +
    +
  • + {{ dep.name }}: {{ dep.version }} +
    • +
+ + + +``` + +## See Also + +- [Angular Material Expansion Panel](https://material.angular.io/components/expansion/overview) +- [ADF Core Components](../README.md) +- [Accessibility Guidelines](../../user-guide/accessibility.md)