diff --git a/eslint.config.mjs b/eslint.config.mjs index 61d4f8e1350..9e3da71d072 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -176,7 +176,7 @@ export default tseslint.config( // JSDoc requirements for components library { files: ["libs/components/src/**/*.ts"], - ignores: ["**/*.spec.ts", "**/*.stories.ts"], + ignores: ["**/*.spec.ts", "**/*.stories.ts", "**/stories/**/*.ts", "**/kitchen-sink/**/*.ts"], plugins: { jsdoc: jsdoc, }, diff --git a/libs/components/src/a11y/router-focus-manager.service.ts b/libs/components/src/a11y/router-focus-manager.service.ts index f7371e02a17..9e2878284de 100644 --- a/libs/components/src/a11y/router-focus-manager.service.ts +++ b/libs/components/src/a11y/router-focus-manager.service.ts @@ -6,6 +6,9 @@ import { skip, filter, combineLatestWith, tap } from "rxjs"; import { FeatureFlag } from "@bitwarden/common/enums/feature-flag.enum"; import { ConfigService } from "@bitwarden/common/platform/abstractions/config/config.service"; +/** + * Service that manages focus after SPA route navigation for accessibility. + */ @Injectable({ providedIn: "root" }) export class RouterFocusManagerService { private router = inject(Router); diff --git a/libs/components/src/anon-layout/anon-layout-wrapper-data.service.ts b/libs/components/src/anon-layout/anon-layout-wrapper-data.service.ts index 4789ac5c46e..5162551825a 100644 --- a/libs/components/src/anon-layout/anon-layout-wrapper-data.service.ts +++ b/libs/components/src/anon-layout/anon-layout-wrapper-data.service.ts @@ -8,7 +8,6 @@ import { AnonLayoutWrapperData } from "./anon-layout-wrapper.component"; */ export abstract class AnonLayoutWrapperDataService { /** - * * @param data - The data to set on the AnonLayoutWrapperComponent to feed into the AnonLayoutComponent. */ abstract setAnonLayoutWrapperData(data: Partial): void; diff --git a/libs/components/src/dialog/dialog.service.ts b/libs/components/src/dialog/dialog.service.ts index 2b95f729097..5940434788f 100644 --- a/libs/components/src/dialog/dialog.service.ts +++ b/libs/components/src/dialog/dialog.service.ts @@ -46,6 +46,9 @@ class CustomBlockScrollStrategy implements ScrollStrategy { detach() {} } +/** + * Abstract base class for dialog references that provides a consistent interface for both dialogs and drawers. + */ export abstract class DialogRef implements Pick< CdkDialogRef, "close" | "closed" | "disableClose" | "componentInstance" diff --git a/libs/components/src/dialog/simple-dialog/types.ts b/libs/components/src/dialog/simple-dialog/types.ts index 9724111b4c2..b377ea1fdba 100644 --- a/libs/components/src/dialog/simple-dialog/types.ts +++ b/libs/components/src/dialog/simple-dialog/types.ts @@ -5,7 +5,6 @@ export interface Translation { // Using type lets devs skip optional params w/out having to pass undefined. /** - * * @typedef {Object} SimpleDialogOptions - A configuration type for the Simple Dialog component */ export type SimpleDialogOptions = { diff --git a/libs/components/src/drawer/drawer.component.ts b/libs/components/src/drawer/drawer.component.ts index 042d1eace79..d5851357e61 100644 --- a/libs/components/src/drawer/drawer.component.ts +++ b/libs/components/src/drawer/drawer.component.ts @@ -39,9 +39,9 @@ export class DrawerComponent { * The ARIA role of the drawer. * * - [complementary](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/complementary_role) - * - For drawers that contain content that is complementary to the page's main content. (default) + * - For drawers that contain content that is complementary to the page's main content. (default) * - [navigation](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role) - * - For drawers that primary contain links to other content. + * - For drawers that primary contain links to other content. */ readonly role = input<"complementary" | "navigation">("complementary"); diff --git a/libs/components/src/form-control/form-control.component.ts b/libs/components/src/form-control/form-control.component.ts index 642d280bdcb..6767998179e 100644 --- a/libs/components/src/form-control/form-control.component.ts +++ b/libs/components/src/form-control/form-control.component.ts @@ -8,6 +8,9 @@ import { TypographyDirective } from "../typography/typography.directive"; import { BitFormControlAbstraction } from "./form-control.abstraction"; +/** + * Container component that provides consistent layout and styling for form inputs with labels and hints. + */ // FIXME(https://bitwarden.atlassian.net/browse/CL-764): Migrate to OnPush // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection @Component({ diff --git a/libs/components/src/form-control/hint.directive.ts b/libs/components/src/form-control/hint.directive.ts index 110aefc30e7..e4ce2f32d48 100644 --- a/libs/components/src/form-control/hint.directive.ts +++ b/libs/components/src/form-control/hint.directive.ts @@ -3,6 +3,9 @@ import { Directive, HostBinding } from "@angular/core"; // Increments for each instance of this component let nextId = 0; +/** + * Directive for displaying hint text below form inputs. + */ @Directive({ selector: "bit-hint", host: { diff --git a/libs/components/src/form-control/label.component.ts b/libs/components/src/form-control/label.component.ts index 95133cae99f..def338a5d81 100644 --- a/libs/components/src/form-control/label.component.ts +++ b/libs/components/src/form-control/label.component.ts @@ -6,6 +6,9 @@ import { FormControlComponent } from "./form-control.component"; // Increments for each instance of this component let nextId = 0; +/** + * Label component for form inputs with support for required indicators. + */ // FIXME(https://bitwarden.atlassian.net/browse/CL-764): Migrate to OnPush // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection @Component({ diff --git a/libs/components/src/form-field/error-summary.component.ts b/libs/components/src/form-field/error-summary.component.ts index cbcd172399a..5cbcaa94cbd 100644 --- a/libs/components/src/form-field/error-summary.component.ts +++ b/libs/components/src/form-field/error-summary.component.ts @@ -3,6 +3,9 @@ import { AbstractControl, UntypedFormGroup } from "@angular/forms"; import { I18nPipe } from "@bitwarden/ui-common"; +/** + * Component that displays a summary count of validation errors in a form. + */ // FIXME(https://bitwarden.atlassian.net/browse/CL-764): Migrate to OnPush // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection @Component({ diff --git a/libs/components/src/form-field/error.component.ts b/libs/components/src/form-field/error.component.ts index 9d931a64db2..b260b764497 100644 --- a/libs/components/src/form-field/error.component.ts +++ b/libs/components/src/form-field/error.component.ts @@ -5,6 +5,9 @@ import { I18nService } from "@bitwarden/common/platform/abstractions/i18n.servic // Increments for each instance of this component let nextId = 0; +/** + * Component that displays validation error messages for form fields. + */ // FIXME(https://bitwarden.atlassian.net/browse/CL-764): Migrate to OnPush // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection @Component({ diff --git a/libs/components/src/form-field/form-field.component.ts b/libs/components/src/form-field/form-field.component.ts index 10cf33b8257..8345aeaa7ca 100644 --- a/libs/components/src/form-field/form-field.component.ts +++ b/libs/components/src/form-field/form-field.component.ts @@ -22,6 +22,9 @@ import { inputBorderClasses } from "../input/input.directive"; import { BitErrorComponent } from "./error.component"; import { BitFormFieldControl } from "./form-field-control"; +/** + * Container component that manages form field layout with labels, inputs, errors, and hints. + */ // FIXME(https://bitwarden.atlassian.net/browse/CL-764): Migrate to OnPush // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection @Component({ diff --git a/libs/components/src/form-field/password-input-toggle.directive.ts b/libs/components/src/form-field/password-input-toggle.directive.ts index ba5539250a6..72fce4baf96 100644 --- a/libs/components/src/form-field/password-input-toggle.directive.ts +++ b/libs/components/src/form-field/password-input-toggle.directive.ts @@ -16,6 +16,9 @@ import { BitIconButtonComponent } from "../icon-button/icon-button.component"; import { BitFormFieldComponent } from "./form-field.component"; +/** + * Directive for toggling password visibility in password input fields. + */ @Directive({ selector: "[bitPasswordInputToggle]", host: { diff --git a/libs/components/src/form-field/prefix.directive.ts b/libs/components/src/form-field/prefix.directive.ts index 8a3d7ab6fe5..3bcbcc151e3 100644 --- a/libs/components/src/form-field/prefix.directive.ts +++ b/libs/components/src/form-field/prefix.directive.ts @@ -2,6 +2,9 @@ import { Directive, OnInit, Optional } from "@angular/core"; import { BitIconButtonComponent } from "../icon-button/icon-button.component"; +/** + * Directive for adding prefix content to form fields. + */ @Directive({ selector: "[bitPrefix]", host: { diff --git a/libs/components/src/form-field/suffix.directive.ts b/libs/components/src/form-field/suffix.directive.ts index c892ebc51eb..bc92319c51d 100644 --- a/libs/components/src/form-field/suffix.directive.ts +++ b/libs/components/src/form-field/suffix.directive.ts @@ -2,6 +2,9 @@ import { Directive, OnInit, Optional } from "@angular/core"; import { BitIconButtonComponent } from "../icon-button/icon-button.component"; +/** + * Directive for adding suffix content to form fields. + */ @Directive({ selector: "[bitSuffix]", host: { diff --git a/libs/components/src/header/header.component.ts b/libs/components/src/header/header.component.ts index 44b0c063d89..1574a760ee1 100644 --- a/libs/components/src/header/header.component.ts +++ b/libs/components/src/header/header.component.ts @@ -2,6 +2,9 @@ import { ChangeDetectionStrategy, Component, input } from "@angular/core"; import { TypographyDirective } from "../typography/typography.directive"; +/** + * Header component that displays a page title with an optional icon. + */ @Component({ selector: "bit-header", templateUrl: "./header.component.html", diff --git a/libs/components/src/icon-button/icon-button.component.ts b/libs/components/src/icon-button/icon-button.component.ts index c7eb28fc086..73fa34984d6 100644 --- a/libs/components/src/icon-button/icon-button.component.ts +++ b/libs/components/src/icon-button/icon-button.component.ts @@ -84,12 +84,13 @@ const sizes: Record = { default: ["tw-text-xl", "tw-p-2.5", "tw-rounded-md"], small: ["tw-text-base", "tw-p-2", "tw-rounded"], }; + /** - * Icon buttons are used when no text accompanies the button. It consists of an icon that may be updated to any icon in the `bwi-font`, a `title` attribute, and an `aria-label` that are added via the `label` input. - - * The most common use of the icon button is in the banner, toast, and modal components as a close button. It can also be found in tables as the 3 dot option menu, or on navigation list items when there are options that need to be collapsed into a menu. - - * Similar to the main button components, spacing between multiple icon buttons should be .5rem. + * Icon buttons are used when no text accompanies the button. It consists of an icon that may be updated to any icon in the `bwi-font`, a `title` attribute, and an `aria-label` that are added via the `label` input. + * + * The most common use of the icon button is in the banner, toast, and modal components as a close button. It can also be found in tables as the 3 dot option menu, or on navigation list items when there are options that need to be collapsed into a menu. + * + * Similar to the main button components, spacing between multiple icon buttons should be .5rem. */ // FIXME(https://bitwarden.atlassian.net/browse/CL-764): Migrate to OnPush // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection diff --git a/libs/components/src/icon/icon.component.ts b/libs/components/src/icon/icon.component.ts index f57a3627383..78bd2aad164 100644 --- a/libs/components/src/icon/icon.component.ts +++ b/libs/components/src/icon/icon.component.ts @@ -3,6 +3,9 @@ import { DomSanitizer, SafeHtml } from "@angular/platform-browser"; import { Icon, isIcon } from "@bitwarden/assets/svg"; +/** + * Component for displaying SVG icons with proper accessibility support. + */ // FIXME(https://bitwarden.atlassian.net/browse/CL-764): Migrate to OnPush // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection @Component({ diff --git a/libs/components/src/item/item-action.component.ts b/libs/components/src/item/item-action.component.ts index b7ce1705f7c..1b6d32e3752 100644 --- a/libs/components/src/item/item-action.component.ts +++ b/libs/components/src/item/item-action.component.ts @@ -1,5 +1,8 @@ import { Component } from "@angular/core"; +/** + * Component for rendering action buttons within an item. + */ // FIXME(https://bitwarden.atlassian.net/browse/CL-764): Migrate to OnPush // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection @Component({ diff --git a/libs/components/src/item/item-content.component.ts b/libs/components/src/item/item-content.component.ts index 9c24d010946..b3ff3f97dc1 100644 --- a/libs/components/src/item/item-content.component.ts +++ b/libs/components/src/item/item-content.component.ts @@ -11,6 +11,9 @@ import { import { TypographyModule } from "../typography"; +/** + * Component for rendering the main content area of an item with support for text truncation. + */ @Component({ selector: "bit-item-content, [bit-item-content]", imports: [TypographyModule, NgClass], diff --git a/libs/components/src/item/item-group.component.ts b/libs/components/src/item/item-group.component.ts index 6e53d2636be..412d2292875 100644 --- a/libs/components/src/item/item-group.component.ts +++ b/libs/components/src/item/item-group.component.ts @@ -1,5 +1,8 @@ import { ChangeDetectionStrategy, Component } from "@angular/core"; +/** + * Container component for grouping multiple items together. + */ @Component({ selector: "bit-item-group", imports: [], diff --git a/libs/components/src/item/item.component.ts b/libs/components/src/item/item.component.ts index a3fa8386325..a10fdacf2ab 100644 --- a/libs/components/src/item/item.component.ts +++ b/libs/components/src/item/item.component.ts @@ -8,6 +8,9 @@ import { import { ItemActionComponent } from "./item-action.component"; +/** + * List item component with support for hover states and focus-visible styling. + */ @Component({ selector: "bit-item", imports: [ItemActionComponent], diff --git a/libs/components/src/layout/layout.component.ts b/libs/components/src/layout/layout.component.ts index 5e3d420c8e5..db3beb0eb73 100644 --- a/libs/components/src/layout/layout.component.ts +++ b/libs/components/src/layout/layout.component.ts @@ -12,6 +12,9 @@ import { SharedModule } from "../shared"; import { ScrollLayoutHostDirective } from "./scroll-layout.directive"; +/** + * Main layout component providing page structure with side navigation and drawer support. + */ // FIXME(https://bitwarden.atlassian.net/browse/CL-764): Migrate to OnPush // eslint-disable-next-line @angular-eslint/prefer-on-push-component-change-detection @Component({ diff --git a/libs/components/src/link/link.directive.ts b/libs/components/src/link/link.directive.ts index 62f0d8b878f..0b5198cdd13 100644 --- a/libs/components/src/link/link.directive.ts +++ b/libs/components/src/link/link.directive.ts @@ -83,18 +83,21 @@ const commonStyles = [ "aria-disabled:hover:tw-no-underline", ]; +/** + * Base directive for link styling. + */ @Directive() abstract class LinkDirective { readonly linkType = input("default"); } /** - * Text Links and Buttons can use either the `` or `