feat(#3159): add JSDocs to React and Angular component wrappers by bdfranck · Pull Request #3715 · GovAlta/ui-components

bdfranck · 2026-03-31T14:50:32Z

This PR adds JSDocs to our React and Angular wrappers. Changes include...

Descriptions for components

Descriptions for properties

Descriptions for common types

Review feedback addressed

Changed all "Defines the..." JSDoc comments to "Sets the..." across Angular (badge.ts, input.ts, input-number.ts) and React (badge.tsx, modal.tsx, callout.tsx) wrappers
Updated testId comment in base.component.ts to "Sets the data-testid attribute for automated testing."
Added @required tag to the GoabFormItemSlot slot property comment in form-item-slot.ts

Before (the change)

JSDoc comments were missing from React and Angular wrapper components, and some existing comments used inconsistent phrasing ("Defines the..." instead of "Sets the...").

After (the change)

All React and Angular wrapper components, properties, and common types have JSDoc comments. Comments consistently use "Sets the..." phrasing, testId comments correctly reference data-testid, and required slot inputs are marked with @required.

Make sure that you've checked the boxes below before you submit the PR

I have read and followed the setup steps
I have created necessary unit tests
I have tested the functionality in both React and Angular.

Steps needed to test

Open a React or Angular project consuming @abgov/react-components or @abgov/angular-components and verify that hovering over component names and props in your IDE shows the updated JSDoc descriptions.

Co-Authored-By: Copilot <198982749+Copilot@users.noreply.github.com>

vanessatran-ddi · 2026-04-07T17:40:23Z

libs/angular-components/src/lib/components/base.component.ts

  @Input() ml?: Spacing;
+  /** Sets the right margin spacing token. */
  @Input() mr?: Spacing;
+  /** Sets the test id rendered on the underlying web component. */


the comment should be Sets the data-testid attribute for automated testing. because the attribute we render is data-testid not test id

Updated in b76d497: /** Sets the data-testid attribute for automated testing. */

chrisolsen · 2026-04-07T17:19:30Z

libs/angular-components/src/lib/components/form-item/form-item-slot.ts

 * // similar to app-footer-meta-section & app-footer-nav-section
 */
 export class GoabFormItemSlot {
+  /** Sets which form-item slot this content should render into. */


Should this have the @required in the comment?

Added @required to the slot comment in b76d497: /** @required Sets which form-item slot this content should render into. */

vanessatran-ddi · 2026-04-07T17:42:25Z

libs/angular-components/src/lib/components/badge/badge.ts

  private cdr = inject(ChangeDetectorRef);

+  /** Defines the context and colour of the badge. */
  @Input() type?: GoabBadgeType;


We should update type, content, icon, iconType to begins vs Sets the ... like the rest of some properties

Updated type comment from "Defines the..." to "Sets the..." in b76d497. The content, icon, and iconType comments didn't use "Defines the..." so they were already consistent.

vanessatran-ddi · 2026-04-07T17:59:48Z

libs/angular-components/src/lib/components/badge/badge.ts

 export class GoabBadge extends GoabBaseComponent implements OnInit {
  private cdr = inject(ChangeDetectorRef);

+  /** Defines the context and colour of the badge. */


I checked locally and the Docs site props table still shows the description and logic from Svelte web component *under extract-api.ts

For example Badge has type not required but on the docs we have this:

I think for this ticket we need to update the extract-api to make sure if we choose the language Angular we use the js docs from Angular, and React is from React js docs.
I think this is the scope of this ticket too ? cc @twjeffery and @Spark450 for the clarification. If we don't handle in this ticket, we will need another story to make sure we update the docs probs table according to React/Angular wrapper JS Docs comments.

@vanessatran-ddi I have a separate PR for updating the docs: #3754

@bdfranck Thank you.
@chrisolsen For the PR #3754 should we remove JS Docs comments on Svelte files too? Or we just leave those comments there.

@vanessatran-ddi We have the "Web components" section in our new docs so we may as well keep them. I'll make sure #3754 includes the Web Components version.

bdfranck · 2026-04-07T18:43:06Z

@copilot Make the following changes:

Change the comments from "Defines the..." with "Sets the..."
Change the testId comments to "Sets the data-testid attribute for automated testing."
Make the GoabFormItemSlot comment @required

@required

- Change 'Defines the...' to 'Sets the...' in Angular and React wrappers - Fix testId comment in base.component.ts to 'Sets the data-testid attribute for automated testing.' - Add @required to GoabFormItemSlot slot comment Agent-Logs-Url: https://github.com/GovAlta/ui-components/sessions/7e34d1c9-e70e-42de-8686-0ee52733ec88 Co-authored-by: bdfranck <1479091+bdfranck@users.noreply.github.com>

Copilot · 2026-04-07T18:46:19Z

@copilot Make the following changes:

Change the comments from "Defines the..." with "Sets the..."

Change the testId comments to "Sets the data-testid attribute for automated testing."
...

Done in b76d497:

Changed all "Defines the..." comments to "Sets the..." across Angular (badge.ts, input.ts, input-number.ts) and React (badge.tsx, modal.tsx, callout.tsx) wrappers
Updated testId comment in base.component.ts to "Sets the data-testid attribute for automated testing."
Added @required to the GoabFormItemSlot slot comment in form-item-slot.ts

vanessatran-ddi · 2026-04-07T19:10:04Z

libs/angular-components/src/lib/components/badge/badge.ts


+  /** Sets the context and colour of the badge. */
  @Input() type?: GoabBadgeType;
+  /** Text label of the badge. */


Should be Sets the text label of the badge

vanessatran-ddi · 2026-04-07T19:10:33Z

libs/angular-components/src/lib/components/badge/badge.ts

  // Ensure boolean input; attribute only set when true so default behaviour is false
+  /** @deprecated Use icontype instead. Includes an icon in the badge. */
  @Input({ transform: booleanAttribute }) icon?: boolean;
+  /** Icon type to display in the badge. */


Should be Sets the icon type to display in the badge

vanessatran-ddi · 2026-04-07T19:11:11Z

libs/angular-components/src/lib/components/badge/badge.ts

  @Input() size?: GoabBadgeSize = "medium";
+  /** Sets the visual emphasis. 'subtle' for less prominent, 'strong' for more emphasis. @default "strong" */
  @Input() emphasis?: GoabBadgeEmphasis = "strong";
+  /** Accessible label for screen readers. */


Should be Sets the accessible label for screen readers

vanessatran-ddi · 2026-04-07T19:12:36Z

libs/angular-components/src/lib/components/block/block.ts

 export class GoabBlock extends GoabBaseComponent implements OnInit {
  private cdr = inject(ChangeDetectorRef);

+  /** Spacing between items. Uses design system spacing tokens. */


Should starts vs Sets the ...

vanessatran-ddi · 2026-04-07T19:12:58Z

libs/angular-components/src/lib/components/block/block.ts


+  /** Spacing between items. Uses design system spacing tokens. */
  @Input() gap?: Spacing;
+  /** Stacking direction of child components. */


Should starts vs Sets the ...

vanessatran-ddi · 2026-04-07T19:13:21Z

libs/angular-components/src/lib/components/block/block.ts

  @Input() gap?: Spacing;
+  /** Stacking direction of child components. */
  @Input() direction?: GoabBlockDirection;
+  /** Primary axis alignment of child components. */


Should start vs Sets the ....

vanessatran-ddi · 2026-04-07T19:14:21Z

libs/angular-components/src/lib/components/button/button.ts


+  /** Sets the visual style of the button. Use "primary" for main actions, "secondary" for alternative actions, "tertiary" for low-emphasis actions, and "start" for prominent call-to-action buttons. @default "primary" */
  @Input() type?: GoabButtonType = "primary";
+  /** Controls the size of the button. Use "compact" for inline actions or space-constrained layouts. @default "normal" */


Should starts vs Sets the size...

vanessatran-ddi · 2026-04-07T19:14:45Z

libs/angular-components/src/lib/components/button/button.ts

  @Input() size?: GoabButtonSize;
+  /** Sets the color variant for semantic meaning. Use "destructive" for delete or irreversible actions, "inverse" for dark backgrounds. @default "normal" */
  @Input() variant?: GoabButtonVariant;
+  /** When true, prevents user interaction and applies disabled styling. */


Should be Sets the disabled state...

vanessatran-ddi · 2026-04-07T19:15:10Z

libs/angular-components/src/lib/components/button/button.ts

  @Input() variant?: GoabButtonVariant;
+  /** When true, prevents user interaction and applies disabled styling. */
  @Input({ transform: booleanAttribute }) disabled?: boolean;
+  /** Icon displayed before the button text. */


Should be Sets the icon displayed...

vanessatran-ddi

I see some properties in angular documented as Sets the ... while some are not. I checked this rule https://github.com/GovAlta/ui-components/blob/dev/CLAUDE.md?plain=1#L109 and looks like we should follow the rule starts vs Sets the .. pattern. However it is not a blocker for me.

vanessatran-ddi · 2026-04-07T19:23:00Z

libs/react-components/src/lib/accordion/accordion.tsx


 export interface GoabAccordionProps extends Margins, DataAttributes {
+  /** @required Sets the heading text. */
+  heading: string;


heading is required in React but not in Angular, think we should make this heading optional in this React wrapper too

vanessatran-ddi · 2026-04-07T19:25:31Z

libs/angular-components/src/lib/components/drawer/drawer.ts

  @Input({ required: true, transform: booleanAttribute }) open!: boolean;
+  /** @required The position of the drawer. */
  @Input({ required: true }) position!: GoabDrawerPosition;
+  /** @required The heading text displayed at the top of the drawer. */


heading is optional for both react and angular, so this comment @required is not correct

vanessatran-ddi · 2026-04-07T19:27:21Z

libs/angular-components/src/lib/components/file-upload-card/file-upload-card.ts

+  /** @required The name of the uploaded file to display. */
  @Input({ required: true }) filename!: string;
+  /** The file size in bytes. Displayed in a human-readable format (KB, MB). */
  @Input({ transform: numberAttribute }) size?: number;


size is a required attribute, so we miss it in Angular here, can you add required: true to the Input and update the comment

vanessatran-ddi · 2026-04-07T19:29:30Z

libs/angular-components/src/lib/components/file-upload-input/file-upload-input.ts

+  /** Sets the id attribute on the file upload input element. */
  @Input() id?: string = "";
+  /** @required The input display variant. "dragdrop" shows a drag-and-drop area, "button" shows a simple button. */
  @Input({ required: true }) variant!: GoabFileUploadInputVariant;


variant is set required in angular but not in React. Checking from Svelte, I think we can make this variant here optional

vanessatran-ddi · 2026-04-07T19:33:45Z

libs/angular-components/src/lib/components/modal/modal.ts

   * The modal will always use role="dialog".
   */
  @Input() role?: string;
+  /** @required The heading text displayed at the top of the modal. */


this heading is not required so this JS doc @required is not correct

bdfranck linked an issue Mar 31, 2026 that may be closed by this pull request

JSDocs in Wrappers #3361

Open

Spark450 added the P1 Priority 1 (must have): Prevents product teams from adopting/using DS 2.0 as intended at launch. label Mar 31, 2026

bdfranck force-pushed the benji/3159-add-jsdocs-to-wrappers branch 2 times, most recently from d245d76 to ba51038 Compare April 1, 2026 21:58

feat(#3159): add JSDocs comments to wrappers and common types

1813a47

Co-Authored-By: Copilot <198982749+Copilot@users.noreply.github.com>

bdfranck force-pushed the benji/3159-add-jsdocs-to-wrappers branch from ba51038 to 1813a47 Compare April 1, 2026 22:05

bdfranck requested a review from ArakTaiRoth April 1, 2026 22:15

bdfranck marked this pull request as ready for review April 1, 2026 22:16

bdfranck requested a review from vanessatran-ddi April 2, 2026 21:32

vanessatran-ddi reviewed Apr 7, 2026

View reviewed changes

chrisolsen reviewed Apr 7, 2026

View reviewed changes

vanessatran-ddi reviewed Apr 7, 2026

View reviewed changes

Copilot started work on behalf of bdfranck April 7, 2026 18:43 View session

Copilot finished work on behalf of bdfranck April 7, 2026 18:47

vanessatran-ddi reviewed Apr 7, 2026

View reviewed changes

Conversation

bdfranck commented Mar 31, 2026 • edited by Copilot AI Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review feedback addressed

Before (the change)

After (the change)

Make sure that you've checked the boxes below before you submit the PR

Steps needed to test

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bdfranck commented Apr 7, 2026

Uh oh!

Copilot AI commented Apr 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vanessatran-ddi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bdfranck commented Mar 31, 2026 •

edited by Copilot AI

Loading