docs(core): add jsdoc to exports in core package

core/src/components/accordion/accordion.ts

@@ -9,6 +9,17 @@ import {typeBoolean, typeFunction, typeString} from '../../utils/writables';
 import {bindDirectiveNoArg, createAttributesDirective, directiveSubscribe, mergeDirectives, registrationArray} from '../../utils/directive';
 import {generateId} from '../../utils/internal/dom';
 
+/**
+ * Adjusts the visibility of accordion items based on the provided open items.
+ * If there are exactly two open items, it keeps the one that is not the old open item visible.
+ * If there are more than two open items, it keeps the first one visible.
+ * All other items are set to not visible.
+ *
+ * @param items - The array of AccordionItemWidget objects to adjust.
+ * @param openItems - An array of strings representing the IDs of the open items.
+ * @param oldOpen - (Optional) The ID of the previously open item.
+ * @returns The adjusted array of AccordionItemWidget objects.
+ */
 function adjustItemsCloseOthers(items: AccordionItemWidget[], openItems: string[], oldOpen?: string): AccordionItemWidget[] {
 	let keepOpen: undefined | string;
 	if (openItems.length == 2) {
@@ -28,10 +39,20 @@ function adjustItemsCloseOthers(items: AccordionItemWidget[], openItems: string[
 	return items;
 }
 
+/**
+ * Retrieves an accordion item by its ID.
+ *
+ * @param items - An array of `AccordionItemWidget` objects.
+ * @param id - The ID of the accordion item to retrieve.
+ * @returns The `AccordionItemWidget` with the matching ID, or `undefined` if no match is found.
+ */
 function getItem(items: AccordionItemWidget[], id: string): AccordionItemWidget | undefined {
 	return items.find((item) => item.stores.id$() === id);
 }
 
+/**
+ * Properties for the Accordion component.
+ */
 export interface AccordionProps extends WidgetsCommonPropsAndState {
 	/**
 	 * If `true`, only one accordion-item at the time can stay open.
@@ -121,13 +142,19 @@ export interface AccordionProps extends WidgetsCommonPropsAndState {
 	itemHeadingTag: string;
 }
 
+/**
+ * Represents the state of an Accordion component.
+ */
 export interface AccordionState extends WidgetsCommonPropsAndState {
 	/**
 	 * Array containing all the accordion-items contained in the accordion.
 	 */
 	itemWidgets: AccordionItemWidget[];
 }
 
+/**
+ * Interface representing the API for an accordion component.
+ */
 export interface AccordionApi {
 	/**
 	 * Given the itemId, will expand the corresponding accordion-item.
@@ -163,22 +190,34 @@ export interface AccordionApi {
 	registerItem(itemConfig?: PropsConfig<AccordionItemProps>): AccordionItemWidget;
 }
 
+/**
+ * Interface representing the directives used in the Accordion component.
+ */
 export interface AccordionDirectives {
 	/**
 	 * Directive to put on the accordion DOM element
 	 */
 	accordionDirective: Directive;
 }
 
+/**
+ * Represents an Accordion widget with specific properties, state, API, and directives.
+ */
 export type AccordionWidget = Widget<AccordionProps, AccordionState, AccordionApi, object, AccordionDirectives>;
 
+/**
+ * Interface representing the actions that can be performed on an accordion item.
+ */
 export interface AccordionItemActions {
 	/**
 	 * Action to be called when the user clicks on the accordion-item button. If the accordion-item is disabled nothing will happen.
 	 */
 	click(): void;
 }
 
+/**
+ * Interface representing the API for an accordion item.
+ */
 export interface AccordionItemApi {
 	/**
 	 * It will collapse the accordion-item.
@@ -199,6 +238,9 @@ export interface AccordionItemApi {
 	initDone(): void;
 }
 
+/**
+ * Interface representing the directives used in an accordion item.
+ */
 export interface AccordionItemDirectives {
 	/**
 	 * Directive to use in special cases, if the accordion header does not use a button element to control the collapsing.
@@ -237,6 +279,9 @@ export interface AccordionItemDirectives {
 	itemDirective: Directive;
 }
 
+/**
+ * Interface representing the common properties and state for an accordion item.
+ */
 interface AccordionItemCommonPropsAndState extends WidgetsCommonPropsAndState {
 	/**
 	 * If `true`, the accordion-item will be visible (expanded). Otherwise, it will be hidden (collapsed).
@@ -274,6 +319,9 @@ interface AccordionItemCommonPropsAndState extends WidgetsCommonPropsAndState {
 	headingTag: string;
 }
 
+/**
+ * Properties for an AccordionItem component.
+ */
 export interface AccordionItemProps extends AccordionItemCommonPropsAndState {
 	/**
 	 * If `true`, accordion-item will be animated.
@@ -303,6 +351,9 @@ export interface AccordionItemProps extends AccordionItemCommonPropsAndState {
 	onVisibleChange: (visible: boolean) => void;
 }
 
+/**
+ * Represents the state of an accordion item.
+ */
 export interface AccordionItemState extends AccordionItemCommonPropsAndState {
 	/**
 	 * If `true` the content of the accordion-item collapse should be in DOM. Its value depends on the
@@ -311,6 +362,9 @@ export interface AccordionItemState extends AccordionItemCommonPropsAndState {
 	shouldBeInDOM: boolean;
 }
 
+/**
+ * Represents a widget for an accordion item.
+ */
 export type AccordionItemWidget = Widget<AccordionItemProps, AccordionItemState, AccordionItemApi, AccordionItemActions, AccordionItemDirectives>;
 
 const defaultAccordionConfig: AccordionProps = {

core/src/components/alert/alert.ts

@@ -2,10 +2,31 @@ import type {CommonAlertApi, CommonAlertDirectives, CommonAlertProps, CommonAler
 import {createCommonAlert, getCommonAlertDefaultConfig} from './common';
 import type {Widget, WidgetFactory} from '../../types';
 
+/**
+ * Represents the state of an alert component.
+ * This interface extends the `CommonAlertState` interface, inheriting its properties.
+ */
 export interface AlertState extends CommonAlertState {}
+
+/**
+ * Represents the properties for the Alert component.
+ */
 export interface AlertProps extends CommonAlertProps {}
+/**
+ * Represents the API for an alert component.
+ *
+ * This interface extends the `CommonAlertApi` interface, inheriting its properties and methods.
+ * It is used to define the structure and behavior of alert components within the application.
+ */
 export interface AlertApi extends CommonAlertApi {}
+/**
+ * This interface extends the `CommonAlertDirectives` and is used to define
+ * the directives specific to the Alert component in the application.
+ */
 export interface AlertDirectives extends CommonAlertDirectives {}
+/**
+ * Represents an alert widget with specific properties, state, API, and directives.
+ */
 export type AlertWidget = Widget<AlertProps, AlertState, AlertApi, object, AlertDirectives>;
 
 /**

core/src/components/alert/common.ts

@@ -7,6 +7,9 @@ import {stateStores, writablesForProps} from '../../utils/stores';
 import {bindDirectiveNoArg} from '../../utils/directive';
 import {typeBoolean} from '../../utils/writables';
 
+/**
+ * Interface representing the common properties and state for an alert component.
+ */
 export interface CommonAlertCommonPropsAndState extends WidgetsCommonPropsAndState {
 	/**
 	 * If `true`, alert can be dismissed by the user.
@@ -30,13 +33,19 @@ export interface CommonAlertCommonPropsAndState extends WidgetsCommonPropsAndSta
 	ariaCloseButtonLabel: string;
 }
 
+/**
+ * Represents the state of a common alert component.
+ */
 export interface CommonAlertState extends CommonAlertCommonPropsAndState {
 	/**
 	 * Is `true` when the alert is hidden. Compared to `visible`, this is updated after the transition is executed.
 	 */
 	hidden: boolean;
 }
 
+/**
+ * Interface representing the common properties for an alert component.
+ */
 export interface CommonAlertProps extends CommonAlertCommonPropsAndState {
 	/**
 	 * Callback called when the alert visibility changed.
@@ -100,6 +109,9 @@ export interface CommonAlertProps extends CommonAlertCommonPropsAndState {
 	animated: boolean;
 }
 
+/**
+ * Interface representing the common API for alert components.
+ */
 export interface CommonAlertApi {
 	/**
 	 * Triggers alert closing programmatically (same as clicking on the close button (×)).
@@ -112,13 +124,19 @@ export interface CommonAlertApi {
 	open(): void;
 }
 
+/**
+ * Interface representing common alert directives.
+ */
 export interface CommonAlertDirectives {
 	/**
 	 * the transition directive, piloting what is the visual effect of going from hidden to visible
 	 */
 	transitionDirective: Directive;
 }
 
+/**
+ * Represents a common alert widget with specified properties, state, API, and directives.
+ */
 export type CommonAlertWidget = Widget<CommonAlertProps, CommonAlertState, CommonAlertApi, object, CommonAlertDirectives>;
 
 const defaultCommonAlertConfig: CommonAlertProps = {

core/src/components/commonProps.ts

@@ -1,3 +1,6 @@
+/**
+ * Interface representing the common properties and state for widgets.
+ */
 export interface WidgetsCommonPropsAndState {
 	/**
 	 * CSS classes to be applied on the widget main container

core/src/components/pagination/pagination.ts

@@ -9,6 +9,9 @@ import {noop} from '../../utils/internal/func';
 import type {WidgetsCommonPropsAndState} from '../commonProps';
 import {createAttributesDirective} from '../../utils/directive';
 
+/**
+ * Interface representing the common properties and state for a pagination component.
+ */
 interface PaginationCommonPropsAndState extends WidgetsCommonPropsAndState {
 	/**
 	 * The current page.
@@ -129,6 +132,9 @@ interface PaginationCommonPropsAndState extends WidgetsCommonPropsAndState {
 	boundaryLinks: boolean;
 }
 
+/**
+ * Interface representing the properties for the Pagination component.
+ */
 export interface PaginationProps extends PaginationCommonPropsAndState {
 	/**
 	 * The number of items in your paginated collection.
@@ -228,6 +234,9 @@ export interface PaginationProps extends PaginationCommonPropsAndState {
 	pageLink: (pageNumber: number) => string;
 }
 
+/**
+ * Interface representing the hrefs for pagination navigation links.
+ */
 export interface DirectionsHrefs {
 	/**
 	 * The href for the 'Previous' navigation link
@@ -239,6 +248,9 @@ export interface DirectionsHrefs {
 	next: string;
 }
 
+/**
+ * Represents the state of the pagination component.
+ */
 export interface PaginationState extends PaginationCommonPropsAndState {
 	/**
 	 * The number of pages.
@@ -271,6 +283,9 @@ export interface PaginationState extends PaginationCommonPropsAndState {
 	ariaLiveLabelText: string;
 }
 
+/**
+ * Interface representing pagination actions for navigating through pages.
+ */
 export interface PaginationActions {
 	/**
 	 * To "go" to a specific page
@@ -295,6 +310,9 @@ export interface PaginationActions {
 	last(event?: MouseEvent): void;
 }
 
+/**
+ * Interface representing the directives for pagination components.
+ */
 export interface PaginationDirectives {
 	/**
 	 * A directive to be applied to each page link
@@ -325,6 +343,9 @@ export interface PaginationDirectives {
 	pageLast: Directive;
 }
 
+/**
+ * Represents a pagination widget with specific properties, state, API, actions, and directives.
+ */
 export type PaginationWidget = Widget<PaginationProps, PaginationState, object, PaginationActions, PaginationDirectives>;
 
 const PAGE_LINK_DEFAULT = '#';

core/src/components/progressbar/progressbar.ts

@@ -33,13 +33,19 @@ interface ProgressbarCommonPropsAndState extends WidgetsCommonPropsAndState {
 	ariaLabel: string;
 }
 
+/**
+ * Interface representing directives for a progress bar component.
+ */
 export interface ProgressbarDirectives {
 	/**
 	 * A directive to be applied to the main container that handles aria attributes.
 	 */
 	ariaDirective: Directive;
 }
 
+/**
+ * Represents the state of a progress bar component.
+ */
 export interface ProgressbarState extends ProgressbarCommonPropsAndState {
 	/**
 	 * Percentage of completion.
@@ -59,6 +65,9 @@ export interface ProgressbarState extends ProgressbarCommonPropsAndState {
 	ariaValueText: string | undefined;
 }
 
+/**
+ * Interface representing the properties for the Progressbar component.
+ */
 export interface ProgressbarProps extends ProgressbarCommonPropsAndState {
 	/**
 	 * Return the value for the 'aria-valuetext' attribute.
@@ -74,6 +83,9 @@ export interface ProgressbarProps extends ProgressbarCommonPropsAndState {
 	ariaValueTextFn: (value: number, minimum: number, maximum: number) => string | undefined;
 }
 
+/**
+ * Represents a Progressbar widget with specific properties, state, API, and directives.
+ */
 export type ProgressbarWidget = Widget<ProgressbarProps, ProgressbarState, object, object, ProgressbarDirectives>;
 
 const defaultConfig: ProgressbarProps = {