From b5e1ba3e35df813c1613d4ee4090cac16325a5f6 Mon Sep 17 00:00:00 2001 From: Will Martin Date: Thu, 22 Jan 2026 13:21:37 -0500 Subject: [PATCH] add more jsdoc class comments to libs/components Co-authored-by: Claude --- eslint.config.mjs | 2 +- .../src/a11y/router-focus-manager.service.ts | 3 +++ .../anon-layout-wrapper-data.service.ts | 1 - libs/components/src/dialog/dialog.service.ts | 3 +++ .../src/dialog/simple-dialog/types.ts | 1 - libs/components/src/drawer/drawer.component.ts | 4 ++-- .../src/form-control/form-control.component.ts | 3 +++ .../src/form-control/hint.directive.ts | 3 +++ .../src/form-control/label.component.ts | 3 +++ .../src/form-field/error-summary.component.ts | 3 +++ .../src/form-field/error.component.ts | 3 +++ .../src/form-field/form-field.component.ts | 3 +++ .../password-input-toggle.directive.ts | 3 +++ .../src/form-field/prefix.directive.ts | 3 +++ .../src/form-field/suffix.directive.ts | 3 +++ libs/components/src/header/header.component.ts | 3 +++ .../src/icon-button/icon-button.component.ts | 11 ++++++----- libs/components/src/icon/icon.component.ts | 3 +++ .../src/item/item-action.component.ts | 3 +++ .../src/item/item-content.component.ts | 3 +++ .../src/item/item-group.component.ts | 3 +++ libs/components/src/item/item.component.ts | 3 +++ libs/components/src/layout/layout.component.ts | 3 +++ libs/components/src/link/link.directive.ts | 18 ++++++++++++------ .../src/menu/menu-divider.component.ts | 3 +++ .../components/src/menu/menu-item.component.ts | 3 +++ .../src/menu/menu-trigger-for.directive.ts | 3 +++ libs/components/src/menu/menu.component.ts | 3 +++ .../src/multi-select/multi-select.component.ts | 6 +++--- .../src/navigation/nav-divider.component.ts | 3 +++ .../src/navigation/nav-group.component.ts | 3 +++ .../src/navigation/nav-item.component.ts | 8 +++++++- .../src/navigation/nav-logo.component.ts | 3 +++ .../src/navigation/side-nav.component.ts | 3 +++ .../popover/popover-trigger-for.directive.ts | 3 +++ .../src/popover/popover.component.ts | 3 +++ .../resize-observer.directive.ts | 3 +++ .../src/section/section-header.component.ts | 3 +++ .../src/section/section.component.ts | 3 +++ libs/components/src/stepper/step.component.ts | 3 +++ libs/components/src/table/cell.directive.ts | 3 +++ libs/components/src/table/row.directive.ts | 3 +++ .../components/src/table/sortable.component.ts | 3 +++ libs/components/src/table/table-data-source.ts | 3 +++ libs/components/src/table/table.component.ts | 6 ++++++ .../src/tabs/tab-group/tab-body.component.ts | 3 +++ .../src/tabs/tab-group/tab-group.component.ts | 3 +++ .../src/tabs/tab-group/tab.component.ts | 3 +++ .../src/tabs/tab-nav-bar/tab-link.component.ts | 3 +++ .../tabs/tab-nav-bar/tab-nav-bar.component.ts | 3 +++ .../src/toast/toast-container.component.ts | 3 +++ libs/components/src/toast/toast.component.ts | 3 +++ .../src/toggle-group/toggle-group.component.ts | 3 +++ .../src/toggle-group/toggle.component.ts | 3 +++ .../src/typography/typography.directive.ts | 3 +++ libs/components/src/utils/i18n-mock.service.ts | 3 +++ libs/components/src/utils/state-mock.ts | 6 ++++++ 57 files changed, 184 insertions(+), 20 deletions(-) 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 `