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

apps/prs/angular/src/app/everything.component.html

@@ -754,7 +754,7 @@
           <goab-form-item label="Upload card" helpText="Cancel and delete emit events.">
             <goab-file-upload-card
               filename="budget.xlsx"
-              filesize="1.2 MB"
+              size="1.2 MB"
               (onCancel)="onFileUploadCardCancel($event)"
               (onDelete)="onFileUploadCardDelete($event)"
             ></goab-file-upload-card>

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

@@ -46,17 +46,26 @@ import { GoabBaseComponent } from "../base.component";
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** Let users show and hide sections of related content on a page. */
 export class GoabAccordion extends GoabBaseComponent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
+  /** Sets the heading text. */
   @Input() heading?: string;
+  /** Sets secondary text. */
   @Input() secondaryText?: string;
+  /** Sets the state of the accordion container open or closed. */
   @Input({ transform: booleanAttribute }) open?: boolean;
+  /** Sets the heading size of the accordion container heading. */
   @Input() headingSize?: GoabAccordionHeadingSize;
+  /** Sets the heading content template reference. */
   @Input() headingContent!: TemplateRef<any>;
+  /** Sets the maximum width of the accordion. */
   @Input() maxWidth?: string;
+  /** Sets the position of the expand/collapse icon. */
   @Input() iconPosition?: GoabAccordionIconPosition;
 
+  /** Emits when the accordion opens or closes. Emits the new open state as a boolean. */
   @Output() onChange = new EventEmitter<boolean>();
 
   isReady = false;

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

@@ -49,16 +49,24 @@ import { GoabBaseComponent } from "../base.component";
     `,
   ],
 })
+/** Small labels which hold small amounts of information, system feedback, or states. */
 export class GoabBadge extends GoabBaseComponent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
+  /** Sets the context and colour of the badge. */
   @Input() type?: GoabBadgeType;
+  /** Sets the text label of the badge. */
   @Input() content?: string;
   // 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;
+  /** Sets the icon type to display in the badge. */
   @Input() iconType?: GoabIconType;
+  /** Sets the size of the badge. @default "medium" */
   @Input() size?: GoabBadgeSize = "medium";
+  /** Sets the visual emphasis. 'subtle' for less prominent, 'strong' for more emphasis. @default "strong" */
   @Input() emphasis?: GoabBadgeEmphasis = "strong";
+  /** Sets the accessible label for screen readers. */
   @Input() ariaLabel?: string;
 
   isReady = false;

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

@@ -15,11 +15,17 @@ import { ControlValueAccessor } from "@angular/forms";
   standalone: true,
   template: ``, //** IMPLEMENT IN SUBCLASS
 })
+/** Provides shared margin and test id inputs for Angular GoA wrapper components. */
 export abstract class GoabBaseComponent {
+  /** Sets the top margin spacing token. */
   @Input() mt?: Spacing;
+  /** Sets the bottom margin spacing token. */
   @Input() mb?: Spacing;
+  /** Sets the left margin spacing token. */
   @Input() ml?: Spacing;
+  /** Sets the right margin spacing token. */
   @Input() mr?: Spacing;
+  /** Sets the data-testid attribute for automated testing. */
   @Input() testId?: string;
 }
 
@@ -78,12 +84,16 @@ export abstract class GoabControlValueAccessor
   extends GoabBaseComponent
   implements ControlValueAccessor
 {
+  /** Sets the id attribute of the underlying web component. */
   @Input() id?: string;
   // supports disabled="true" instead of [disabled]="true"
+  /** Sets the disabled state for the control. */
   @Input({ transform: booleanAttribute }) public disabled?: boolean;
   // supports error="true" instead of [error]="true"
+  /** Sets the error state for the control. */
   @Input({ transform: booleanAttribute }) public error?: boolean;
   // this should be unknown (not string) as it might be an integer or a date or a boolean
+  /** Sets the control value used by Angular forms and one-way binding. */
   @Input() value?: unknown | null | undefined;
 
   // implement ControlValueAccessor

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

@@ -39,14 +39,21 @@ import { GoabBaseComponent } from "../base.component";
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** Group components into a block with consistent space between. */
 export class GoabBlock extends GoabBaseComponent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
+  /** Sets the spacing between items. Uses design system spacing tokens. */
   @Input() gap?: Spacing;
+  /** Sets the stacking direction of child components. */
   @Input() direction?: GoabBlockDirection;
+  /** Sets the primary axis alignment of child components. */
   @Input() alignment?: GoabBlockAlignment;
+  /** Sets the width of the block container. Defaults to max-content. */
   @Input() width?: string;
+  /** Sets the minimum width of the block container. */
   @Input() minWidth?: string;
+  /** Sets the maximum width of the block container. */
   @Input() maxWidth?: string;
 
   isReady = false;

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

@@ -34,10 +34,13 @@ import { GoabBaseComponent } from "../base.component";
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** Display multiple related actions stacked or in a horizontal row to help with arrangement and spacing. */
 export class GoabButtonGroup extends GoabBaseComponent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
+  /** Positions the button group in the page layout. */
   @Input() alignment?: GoabButtonGroupAlignment;
+  /** Sets the spacing between buttons in the button group. */
   @Input() gap?: GoabButtonGroupGap;
 
   isReady = false;

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

@@ -49,20 +49,32 @@ import { GoabBaseComponent } from "../base.component";
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** Carry out an important action or navigate to another page. */
 export class GoabButton extends GoabBaseComponent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
+  /** 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";
+  /** Sets the size of the button. Use "compact" for inline actions or space-constrained layouts. @default "normal" */
   @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;
+  /** Sets the disabled state. When true, prevents user interaction and applies disabled styling. */
   @Input({ transform: booleanAttribute }) disabled?: boolean;
+  /** Sets the icon displayed before the button text. */
   @Input() leadingIcon?: GoabIconType;
+  /** Icon displayed after the button text. */
   @Input() trailingIcon?: GoabIconType;
+  /** Sets a custom width for the button (e.g., "200px" or "100%"). */
   @Input() width?: string;
+  /** Action identifier passed in click events for event delegation patterns. */
   @Input() action?: string;
+  /** Single argument value passed with the action in click events. */
   @Input() actionArg?: string;
+  /** Multiple argument values passed with the action in click events. */
   @Input() actionArgs?: Record<string, unknown>;
 
+  /** Emits when the button is clicked. */
   @Output() onClick = new EventEmitter();
 
   isReady = false;

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

@@ -40,16 +40,22 @@ import { GoabBaseComponent } from "../base.component";
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** Visual calendar for date selection. */
 export class GoabCalendar extends GoabBaseComponent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
   version = "2";
 
+  /** Name identifier for the calendar, included in change events. */
   @Input() name?: string;
+  /** The currently selected date value in YYYY-MM-DD format. */
   @Input() value?: Date | string;
+  /** The minimum selectable date in YYYY-MM-DD format. Defaults to 5 years in the past. */
   @Input() min?: Date | string | undefined;
+  /** The maximum selectable date in YYYY-MM-DD format. Defaults to 5 years in the future. */
   @Input() max?: Date | string | undefined;
 
+  /** Emits when the selected date changes. Emits the selected date details as GoabCalendarOnChangeDetail. */
   @Output() onChange = new EventEmitter<GoabCalendarOnChangeDetail>();
 
   isReady = false;

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

@@ -43,6 +43,7 @@ import { GoabBaseComponent } from "../base.component";
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** Communicate important information through a strong visual emphasis. */
 export class GoabCallout extends GoabBaseComponent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
@@ -58,11 +59,18 @@ export class GoabCallout extends GoabBaseComponent implements OnInit {
     }, 0);
   }
 
+  /** Define the context and colour of the callout. @default "information" */
   @Input() type?: GoabCalloutType = "information";
+  /** Callout heading text. */
   @Input() heading?: string = "";
+  /** Sets the size of the callout. 'medium' has reduced padding and type size for compact areas. @default "large" */
   @Input() size?: GoabCalloutSize = "large";
+  /** Sets the maximum width of the callout. */
   @Input() maxWidth?: string;
+  /** Indicates how assistive technology should handle updates to the live region. @default "off" */
   @Input() ariaLive?: GoabCalloutAriaLive = "off";
+  /** Sets the icon theme. 'outline' for stroked icons, 'filled' for solid icons. @default "outline" */
   @Input() iconTheme?: GoabCalloutIconTheme = "outline";
+  /** Sets the visual prominence. 'high' for full background, 'medium' for subtle, 'low' for minimal. @default "medium" */
   @Input() emphasis?: GoabCalloutEmphasis = "medium";
 }

libs/angular-components/src/lib/components/card-actions/card-actions.ts

@@ -18,6 +18,7 @@ import {
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** A container that groups related content and actions. */
 export class GoabCardActions implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 

libs/angular-components/src/lib/components/card-content/card-content.ts

@@ -18,6 +18,7 @@ import {
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** A container that groups related content and actions. */
 export class GoabCardContent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 

libs/angular-components/src/lib/components/card-image/card-image.ts

@@ -19,10 +19,13 @@ import {
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** A container that groups related content and actions. */
 export class GoabCardImage implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
+  /** @required The URL of the image to display. */
   @Input({ required: true }) src!: string;
+  /** @required Height of the image container. Accepts CSS values like "200px" or "100%". */
   @Input({ required: true }) height!: string;
 
   isReady = false;

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

@@ -31,6 +31,7 @@ import { GoabBaseComponent } from "../base.component";
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** A container that groups related content and actions. */
 export class GoabCard extends GoabBaseComponent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
@@ -45,6 +46,8 @@ export class GoabCard extends GoabBaseComponent implements OnInit {
     }, 0);
   }
 
+  /** Adds a shadow to the card. 0 shows a border, 1-3 increase shadow intensity. */
   @Input({ transform: numberAttribute }) elevation?: number;
+  /** Sets the width of the card. */
   @Input() width?: string;
 }

libs/angular-components/src/lib/components/checkbox-list/checkbox-list.ts

@@ -1,4 +1,7 @@
-import { GoabCheckboxListOnChangeDetail, GoabCheckboxSize } from "@abgov/ui-components-common";
+import {
+  GoabCheckboxListOnChangeDetail,
+  GoabCheckboxSize,
+} from "@abgov/ui-components-common";
 import {
   CUSTOM_ELEMENTS_SCHEMA,
   Component,
@@ -47,16 +50,21 @@ import { GoabControlValueAccessor } from "../base.component";
     },
   ],
 })
+/** A multiple selection input. */
 export class GoabCheckboxList extends GoabControlValueAccessor implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
   isReady = false;
   version = "2";
+  /** @required The name for the checkbox list group. Used as group identifier in change events. */
   @Input() name!: string;
+  /** Sets the maximum width of the checkbox list container. */
   @Input() maxWidth?: string;
+  /** Sets the size of the checkbox list. 'compact' reduces spacing between items. @default "default" */
   @Input() size?: GoabCheckboxSize = "default";
 
   // Override value to handle string arrays consistently
+  /** Array of currently selected checkbox values. */
   @Input() override value?: string[];
 
 
@@ -67,6 +75,7 @@ export class GoabCheckboxList extends GoabControlValueAccessor implements OnInit
     });
   }
 
+  /** Emits when a checkbox selection changes. Emits the change detail including name, value array, and event. */
   @Output() onChange = new EventEmitter<GoabCheckboxListOnChangeDetail>();
 
   _onChange(e: Event) {

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

@@ -67,6 +67,7 @@ import { GoabControlValueAccessor } from "../base.component";
   ],
   imports: [NgTemplateOutlet],
 })
+/** Let the user select one or more options. */
 export class GoabCheckbox extends GoabControlValueAccessor implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
@@ -83,19 +84,31 @@ export class GoabCheckbox extends GoabControlValueAccessor implements OnInit {
     }, 0);
   }
 
+  /** Sets the name of the checkbox input for form submission. */
   @Input() name?: string;
+  /** Marks the checkbox item as selected. */
   @Input({ transform: booleanAttribute }) checked?: boolean;
+  /** Shows a mixed/partial selection state. Used for 'Select All' checkboxes when some items are selected. */
   @Input({ transform: booleanAttribute }) indeterminate?: boolean;
+  /** Label shown beside the checkbox. */
   @Input() text?: string;
   // ** NOTE: can we just use the base component for this?
+  /** The value binding. */
   @Input() override value?: string | number | boolean | null;
+  /** Defines how the text will be translated for the screen reader. If not specified it will fall back to the name. */
   @Input() ariaLabel?: string;
+  /** Sets additional description content displayed below the checkbox label. Accepts plain text or a template. */
   @Input() description!: string | TemplateRef<any>;
+  /** Sets the template for the expandable reveal slot content. */
   @Input() reveal?: TemplateRef<any>;
+  /** Text announced by screen readers when the reveal slot content is displayed. */
   @Input() revealArialLabel?: string;
+  /** Sets the maximum width of the checkbox. */
   @Input() maxWidth?: string;
+  /** Sets the size of the checkbox. 'compact' reduces spacing for dense layouts. @default "default" */
   @Input() size?: GoabCheckboxSize = "default";
 
+  /** Emits when the checkbox value changes. Emits the new checkbox state as a GoabCheckboxOnChangeDetail object. */
   @Output() onChange = new EventEmitter<GoabCheckboxOnChangeDetail>();
 
   getDescriptionAsString(): string {

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

@@ -41,6 +41,7 @@ import { GoabBaseComponent } from "../base.component";
   }`,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** Compact element for labels, tags, or selections. */
 export class GoabChip extends GoabBaseComponent implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
@@ -55,13 +56,20 @@ export class GoabChip extends GoabBaseComponent implements OnInit {
     }, 0);
   }
 
+  /** @deprecated Use GoAFilterChip instead. Icon displayed at the start of the chip. */
   @Input() leadingIcon?: GoabIconType | null;
+  /** @deprecated Use GoAFilterChip instead. Shows an error state on the chip. */
   @Input({ transform: booleanAttribute }) error?: boolean;
+  /** @deprecated Use GoAFilterChip instead. When true, shows a delete icon and makes chip clickable. */
   @Input({ transform: booleanAttribute }) deletable?: boolean;
+  /** @deprecated Use GoAFilterChip instead. The text content displayed in the chip. */
   @Input() content?: string = "";
+  /** @deprecated Use GoAFilterChip instead. The chip variant style. */
   @Input() variant?: GoabChipVariant;
+  /** @deprecated Use GoAFilterChip instead. The icon theme - outline or filled. */
   @Input() iconTheme?: GoabChipTheme;
 
+  /** Emits when the chip is clicked. */
   @Output() onClick = new EventEmitter();
 
   _onClick() {

libs/angular-components/src/lib/components/circular-progress/circular-progress.ts

@@ -32,14 +32,21 @@ import {
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** Provide feedback of progress to users while loading. */
 export class GoabCircularProgress implements OnInit {
   private cdr = inject(ChangeDetectorRef);
 
+  /** Stretch across the full screen or use it inline. */
   @Input() variant?: GoabCircularProgressVariant;
+  /** Size of the progress indicator. */
   @Input() size?: GoabCircularProgressSize;
+  /** Loading message displayed under the progress indicator. */
   @Input() message?: string;
+  /** Show/hide the page loader. This allows for fade transition to be applied in each transition. */
   @Input({ transform: booleanAttribute }) visible?: boolean;
+  /** Set the progress value. Setting this value will change the type from infinite to progress. */
   @Input({ transform: numberAttribute }) progress?: number;
+  /** Sets a data-testid attribute for automated testing. */
   @Input() testId?: string;
 
   isReady = false;

libs/angular-components/src/lib/components/column-layout/column-layout.ts

@@ -18,6 +18,7 @@ import {
   `,
   schemas: [CUSTOM_ELEMENTS_SCHEMA],
 })
+/** Organizes page content in one, two, or three responsive columns. */
 export class GoabColumnLayout implements OnInit {
   private cdr = inject(ChangeDetectorRef);