docs(core): add jsdoc to exports (#942)

* docs(core): add jsdoc to exports in core package * docs(core): add jsdoc to exports in core-bootstrap package * docs(core): add jsdoc to exports in angular-headless package * docs(react-headless): add jsdoc to exports * docs(svelte-headless): add jsdoc to exports * docs(angular-bootstrap): Added directives / components / slots descriptions * docs(react-bootstrap): Add documentation for exported components, export default slots * docs: fixing bugs * fix: Escape renderer not used correctly * fix: angular small fixes * fix: last fixes * fix: rebase and mdn links * fix: last minor fixes --------- Co-authored-by: Quentin Deroubaix <[email protected]>
AmadeusITGroup · Oct 29, 2024 · e6c7c14 · e6c7c14
1 parent 926df6a
commit e6c7c14
Show file tree

Hide file tree

Showing 90 changed files with 1,686 additions and 196 deletions.
diff --git a/.gitignore b/.gitignore
@@ -16,3 +16,4 @@ verdaccio/storage
 blob-report
 *.gen.ts
 .eslintcache
+.DS_Store
diff --git a/angular/bootstrap/src/components/accordion/accordion.component.ts b/angular/bootstrap/src/components/accordion/accordion.component.ts
@@ -25,6 +25,11 @@ import {callWidgetFactory} from '../../config';
 import type {AccordionItemContext, AccordionItemWidget, AccordionWidget} from './accordion.gen';
 import {createAccordion} from './accordion.gen';
 
+/**
+ * Directive to represent the body of an accordion item.
+ *
+ * This directive provides a template reference for the {@link AccordionItemContext}.
+ */
 @Directive({selector: 'ng-template[auAccordionItemBody]', standalone: true})
 export class AccordionBodyDirective {
 	public templateRef = inject(TemplateRef<AccordionItemContext>);
@@ -33,6 +38,11 @@ export class AccordionBodyDirective {
 	}
 }
 
+/**
+ * Directive to be used as an accordion header.
+ *
+ * This directive provides a template reference for the {@link AccordionItemContext}.
+ */
 @Directive({selector: 'ng-template[auAccordionItemHeader]', standalone: true})
 export class AccordionHeaderDirective {
 	public templateRef = inject(TemplateRef<AccordionItemContext>);
@@ -41,6 +51,12 @@ export class AccordionHeaderDirective {
 	}
 }
 
+/**
+ * Directive that represents the structure of an accordion item.
+ *
+ * This directive provides a template reference for the {@link AccordionItemContext}.
+ * It also includes a static method to guard the template context type.
+ */
 @Directive({selector: 'ng-template[auAccordionItemStructure]', standalone: true})
 export class AccordionItemStructureDirective {
 	public templateRef = inject(TemplateRef<AccordionItemContext>);
@@ -132,8 +148,17 @@ export class AccordionItemStructureDirective {
 class AccordionItemDefaultSlotsComponent {
 	@ViewChild('structure', {static: true}) structure!: TemplateRef<AccordionItemContext>;
 }
-export const accordionItemDefaultSlotItemStructure = new ComponentTemplate(AccordionItemDefaultSlotsComponent, 'structure');
-
+/**
+ * Represents the default slot structure for an accordion item.
+ */
+export const accordionItemDefaultSlotStructure: SlotContent<AccordionItemContext> = new ComponentTemplate(
+	AccordionItemDefaultSlotsComponent,
+	'structure',
+);
+
+/**
+ * AccordionItemComponent is a component that represents an item within an accordion.
+ */
 @Component({
 	selector: '[auAccordionItem]',
 	exportAs: 'auAccordionItem',
@@ -255,7 +280,7 @@ export class AccordionItemComponent extends BaseWidgetDirective<AccordionItemWid
 			callWidgetFactory<AccordionItemWidget>({
 				factory: (arg) => inject(AccordionDirective).api.registerItem(arg),
 				defaultConfig: {
-					structure: accordionItemDefaultSlotItemStructure,
+					structure: accordionItemDefaultSlotStructure,
 				},
 				events: {
 					onVisibleChange: (visible) => this.visibleChange.emit(visible),
@@ -280,6 +305,13 @@ export class AccordionItemComponent extends BaseWidgetDirective<AccordionItemWid
 	}
 }
 
+/**
+ * Directive for creating an accordion component.
+ *
+ * This directive extends the `BaseWidgetDirective` and provides various inputs and outputs
+ * to customize the behavior and appearance of the accordion and its items.
+ *
+ */
 @Directive({
 	selector: '[auAccordion]',
 	exportAs: 'auAccordion',

diff --git a/angular/bootstrap/src/components/alert/alert.component.ts b/angular/bootstrap/src/components/alert/alert.component.ts
@@ -17,6 +17,11 @@ import {
 import {callWidgetFactory} from '../../config';
 import type {BSContextualClass} from '@agnos-ui/core-bootstrap/types';
 
+/**
+ * Directive to be used as a structural directive for the body of an alert component.
+ *
+ * This directive allows the use of a template reference for the alert body content, with type {@link AlertContext}.
+ */
 @Directive({selector: 'ng-template[auAlertBody]', standalone: true})
 export class AlertBodyDirective {
 	public templateRef = inject(TemplateRef<AlertContext>);
@@ -25,13 +30,19 @@ export class AlertBodyDirective {
 	}
 }
 
+/**
+ * Directive to define the structure of an alert component.
+ *
+ * This directive uses a `TemplateRef` to inject the template reference of the {@link AlertContext}.
+ */
 @Directive({selector: 'ng-template[auAlertStructure]', standalone: true})
 export class AlertStructureDirective {
 	public templateRef = inject(TemplateRef<AlertContext>);
 	static ngTemplateContextGuard(_dir: AlertStructureDirective, context: unknown): context is AlertContext {
 		return true;
 	}
 }
+
 @Component({
 	standalone: true,
 	changeDetection: ChangeDetectionStrategy.OnPush,
@@ -49,8 +60,19 @@ class AlertDefaultSlotsComponent {
 	@ViewChild('structure', {static: true}) structure!: TemplateRef<AlertContext>;
 }
 
-export const alertDefaultSlotStructure = new ComponentTemplate(AlertDefaultSlotsComponent, 'structure');
-
+/**
+ * Represents the default slot structure for the alert component.
+ */
+export const alertDefaultSlotStructure: SlotContent<AlertContext> = new ComponentTemplate(AlertDefaultSlotsComponent, 'structure');
+
+/**
+ * AlertComponent is a UI component that extends BaseWidgetDirective to provide
+ * an alert box with various customizable properties and behaviors.
+ *
+ * @remarks
+ * This component is designed to be used with Bootstrap styles and supports
+ * various Bootstrap contextual classes for different alert types.
+ */
 @Component({
 	selector: '[auAlert]',
 	standalone: true,

diff --git a/angular/bootstrap/src/components/collapse/collapse.component.ts b/angular/bootstrap/src/components/collapse/collapse.component.ts
@@ -4,6 +4,9 @@ import {createCollapse} from '@agnos-ui/core-bootstrap/components/collapse';
 import {Directive, EventEmitter, Input, Output} from '@angular/core';
 import {callWidgetFactory} from '../../config';
 
+/**
+ * Directive to control the collapse behavior of an element.
+ */
 @Directive({
 	selector: '[auCollapse]',
 	standalone: true,

diff --git a/angular/bootstrap/src/components/modal/modal.component.ts b/angular/bootstrap/src/components/modal/modal.component.ts
@@ -18,6 +18,7 @@ import {callWidgetFactory} from '../../config';
 
 /**
  * Directive to provide the slot structure for the modal widget.
+ * This directive provides a template reference for the {@link ModalContext<Data>}.
  */
 @Directive({selector: 'ng-template[auModalStructure]', standalone: true})
 export class ModalStructureDirective<Data> {
@@ -29,6 +30,7 @@ export class ModalStructureDirective<Data> {
 
 /**
  * Directive to provide the slot header for the modal widget.
+ * This directive provides a template reference for the {@link ModalContext<Data>}.
  */
 @Directive({selector: 'ng-template[auModalHeader]', standalone: true})
 export class ModalHeaderDirective<Data> {
@@ -40,6 +42,7 @@ export class ModalHeaderDirective<Data> {
 
 /**
  * Directive to provide the slot title for the modal widget.
+ * This directive provides a template reference for the {@link ModalContext<Data>}.
  */
 @Directive({selector: 'ng-template[auModalTitle]', standalone: true})
 export class ModalTitleDirective<Data> {
@@ -51,6 +54,7 @@ export class ModalTitleDirective<Data> {
 
 /**
  * Directive to provide the default slot for the modal widget.
+ * This directive provides a template reference for the {@link ModalContext<Data>}.
  */
 @Directive({selector: 'ng-template[auModalBody]', standalone: true})
 export class ModalBodyDirective<Data> {
@@ -62,6 +66,7 @@ export class ModalBodyDirective<Data> {
 
 /**
  * Directive to provide the slot footer for the modal widget.
+ * This directive provides a template reference for the {@link ModalContext<Data>}.
  */
 @Directive({selector: 'ng-template[auModalFooter]', standalone: true})
 export class ModalFooterDirective<Data> {
@@ -112,12 +117,12 @@ class ModalDefaultSlotsComponent<Data> {
 /**
  * Default slot for modal header.
  */
-export const modalDefaultSlotHeader = new ComponentTemplate(ModalDefaultSlotsComponent, 'header');
+export const modalDefaultSlotHeader: SlotContent<ModalContext<any>> = new ComponentTemplate(ModalDefaultSlotsComponent, 'header');
 
 /**
  * Default slot for modal structure.
  */
-export const modalDefaultSlotStructure = new ComponentTemplate(ModalDefaultSlotsComponent, 'structure');
+export const modalDefaultSlotStructure: SlotContent<ModalContext<any>> = new ComponentTemplate(ModalDefaultSlotsComponent, 'structure');
 
 /**
  * Modal component.

diff --git a/angular/bootstrap/src/components/modal/modal.service.ts b/angular/bootstrap/src/components/modal/modal.service.ts
@@ -3,10 +3,13 @@ import type {Subscription} from 'rxjs';
 import {ModalComponent} from './modal.component';
 import type {ModalProps} from './modal.gen';
 
-export interface ModalServiceOpenOptions {
+interface ModalServiceOpenOptions {
 	injector?: Injector;
 }
 
+/**
+ * Service to handle the opening and management of modal components.
+ */
 @Injectable({providedIn: 'root'})
 export class ModalService {
 	private readonly _injector = inject(Injector);

diff --git a/angular/bootstrap/src/components/pagination/pagination.component.ts b/angular/bootstrap/src/components/pagination/pagination.component.ts
@@ -19,6 +19,7 @@ import {createPagination} from './pagination.gen';
 
 /**
  * A directive to use to give the 'ellipsis' link template to the pagination component
+ * This directive provides a template reference for the {@link PaginationContext}.
  */
 @Directive({selector: 'ng-template[auPaginationEllipsis]', standalone: true})
 export class PaginationEllipsisDirective {
@@ -30,6 +31,7 @@ export class PaginationEllipsisDirective {
 
 /**
  * A directive to use to give the 'first' link template to the pagination component
+ * This directive provides a template reference for the {@link PaginationContext}.
  */
 @Directive({selector: 'ng-template[auPaginationFirst]', standalone: true})
 export class PaginationFirstDirective {
@@ -41,6 +43,7 @@ export class PaginationFirstDirective {
 
 /**
  * A directive to use to give the 'last' link template to the pagination component
+ * This directive provides a template reference for the {@link PaginationContext}.
  */
 @Directive({selector: 'ng-template[auPaginationLast]', standalone: true})
 export class PaginationLastDirective {
@@ -52,6 +55,7 @@ export class PaginationLastDirective {
 
 /**
  * A directive to use to give the 'next' link template to the pagination component
+ * This directive provides a template reference for the {@link PaginationContext}.
  */
 @Directive({selector: 'ng-template[auPaginationNext]', standalone: true})
 export class PaginationNextDirective {
@@ -63,6 +67,7 @@ export class PaginationNextDirective {
 
 /**
  * A directive to use to give the page 'number' template to the pagination component
+ * This directive provides a template reference for the {@link PaginationNumberContext}.
  */
 @Directive({selector: 'ng-template[auPaginationNumber]', standalone: true})
 export class PaginationNumberDirective {
@@ -74,6 +79,7 @@ export class PaginationNumberDirective {
 
 /**
  * A directive to use to give the 'previous' link template to the pagination component
+ * This directive provides a template reference for the {@link PaginationContext}.
  */
 @Directive({selector: 'ng-template[auPaginationPrevious]', standalone: true})
 export class PaginationPreviousDirective {
@@ -85,6 +91,7 @@ export class PaginationPreviousDirective {
 
 /**
  * A directive to use to give the 'Pages' template for the Pages slot
+ * This directive provides a template reference for the {@link PaginationContext}.
  */
 @Directive({selector: 'ng-template[auPaginationPages]', standalone: true})
 export class PaginationPagesDirective {
@@ -96,6 +103,7 @@ export class PaginationPagesDirective {
 
 /**
  * Directive to provide the slot structure for the pagination widget.
+ * This directive provides a template reference for the {@link PaginationContext}.
  */
 @Directive({selector: 'ng-template[auPaginationStructure]', standalone: true})
 export class PaginationStructureDirective {
@@ -180,12 +188,17 @@ class PaginationDefaultSlotsComponent {
 /**
  * The default slot for the pages
  */
-export const paginationDefaultSlotPages = new ComponentTemplate(PaginationDefaultSlotsComponent, 'pages');
+export const paginationDefaultSlotPages: SlotContent<PaginationContext> = new ComponentTemplate(PaginationDefaultSlotsComponent, 'pages');
 /**
  * The default slot for the structure
  */
-export const paginationDefaultSlotStructure = new ComponentTemplate(PaginationDefaultSlotsComponent, 'structure');
+export const paginationDefaultSlotStructure: SlotContent<PaginationContext> = new ComponentTemplate(PaginationDefaultSlotsComponent, 'structure');
 
+/**
+ * The `PaginationComponent` is an Angular component that extends the `BaseWidgetDirective`
+ * to provide a customizable pagination widget. It includes various input properties
+ * to configure labels, templates, and behavior for accessibility and internationalization (i18n).
+ */
 @Component({
 	selector: '[auPagination]',
 	standalone: true,

diff --git a/angular/bootstrap/src/components/progressbar/progressbar.component.ts b/angular/bootstrap/src/components/progressbar/progressbar.component.ts
@@ -15,6 +15,10 @@ import {createProgressbar} from './progressbar.gen';
 import {callWidgetFactory} from '../../config';
 import type {BSContextualClass} from '@agnos-ui/core-bootstrap/types';
 
+/**
+ * Directive that provides a template reference for the progress bar context.
+ * This directive provides a template reference for the {@link ProgressbarContext}.
+ */
 @Directive({selector: 'ng-template[auProgressbarBody]', standalone: true})
 export class ProgressbarBodyDirective {
 	public templateRef = inject(TemplateRef<ProgressbarContext>);
@@ -23,6 +27,11 @@ export class ProgressbarBodyDirective {
 	}
 }
 
+/**
+ * Directive to define the structure of a progress bar.
+ *
+ * This directive provides a template reference for the {@link ProgressbarContext}.
+ */
 @Directive({selector: 'ng-template[auProgressbarStructure]', standalone: true})
 export class ProgressbarStructureDirective {
 	public templateRef = inject(TemplateRef<ProgressbarContext>);
@@ -55,8 +64,17 @@ class ProgressbarDefaultSlotsComponent {
 	@ViewChild('structure', {static: true}) structure!: TemplateRef<ProgressbarContext>;
 }
 
-export const progressbarDefaultSlotStructure = new ComponentTemplate(ProgressbarDefaultSlotsComponent, 'structure');
-
+/**
+ * Represents the default slot structure for the progress bar component.
+ */
+export const progressbarDefaultSlotStructure: SlotContent<ProgressbarContext> = new ComponentTemplate(ProgressbarDefaultSlotsComponent, 'structure');
+
+/**
+ * ProgressbarComponent is a UI component that extends the BaseWidgetDirective
+ * to create a customizable progress bar widget. It provides various inputs
+ * to configure the appearance and behavior of the progress bar.
+ *
+ */
 @Component({
 	selector: '[auProgressbar]',
 	standalone: true,

diff --git a/angular/bootstrap/src/components/rating/rating.component.ts b/angular/bootstrap/src/components/rating/rating.component.ts
@@ -26,6 +26,11 @@ import {callWidgetFactory} from '../../config';
 import type {RatingWidget, StarContext} from './rating.gen';
 import {createRating} from './rating.gen';
 
+/**
+ * Directive to represent a rating star.
+ *
+ * This directive uses a template reference to render the {@link StarContext}.
+ */
 @Directive({selector: 'ng-template[auRatingStar]', standalone: true})
 export class RatingStarDirective {
 	public templateRef = inject(TemplateRef<StarContext>);
@@ -34,6 +39,10 @@ export class RatingStarDirective {
 	}
 }
 
+/**
+ * The `RatingComponent` is an Angular component that allows users to provide a rating.
+ * It extends `BaseWidgetDirective` and implements `ControlValueAccessor` to integrate with Angular forms.
+ */
 @Component({
 	selector: '[auRating]',
 	standalone: true,