Skip to content

feat(#3159): Add JSDoc comments to React and Angular component wrappers#3671

Draft
Copilot wants to merge 4 commits intodevfrom
copilot/add-jsdocs-to-wrappers
Draft

feat(#3159): Add JSDoc comments to React and Angular component wrappers#3671
Copilot wants to merge 4 commits intodevfrom
copilot/add-jsdocs-to-wrappers

Conversation

Copy link
Contributor

Copilot AI commented Mar 24, 2026

  • Understand the codebase patterns (Svelte → React/Angular JSDoc mapping)
  • Create scripts/add-jsdocs.js — re-runnable script that reads JSDoc from Svelte source and injects into React/Angular wrappers
    • Idempotent: safe to run multiple times — only adds where missing
    • --dry-run mode for previewing changes without writing
    • Handles @required, @deprecated, @default tags
    • Normalises "false"/"true" string defaults → false/true booleans
    • Covers both lib/ and experimental/ Angular wrappers
    • Skips @internal Svelte props
  • Apply script to fix 43 additional wrapper files with missing JSDoc (missed by initial commits)
  • Fix pre-existing corruption in experimental/checkbox-list/checkbox-list.tsx (Svelte imports injected into interface by original codegen)
  • Update scripts/README.md with full usage documentation for the new script
Original prompt

This section details on the original issue you should resolve

<issue_title>JSDocs in Wrappers</issue_title>
<issue_description># Info

It would be extremely beneficial to developers using our component wrappers to see better descriptions of properties in components. This would better allow them to stay in their IDE instead of having to switch between IDE and documentation website to figure out what they want to do.

Just a normal comment on a property:
Image

A proper full JSDoc comment on that same property:
Image

As you can see above, with just that one property. It properly gives a description of the property, what type of data it allows for (this can be expanded even further by documenting that type properly as well), whether it's optional or required, and what the default value is so they know.

We only need to create the comments for either Angular or React wrappers, and then have a script to copy them to other set of wrappers.

Acceptance Criteria:

  1. Give proper full JSDoc comments for every property in every component, in either Angular or React
  2. Use AI to duplicate to either Angular or React</issue_description>

<agent_instructions>1. Look at the JSDoc comments in the Svelte components
2. Add corresponding JSDoc comments to the React and Angular wrappers

Example:

  • Svelte component: libs/web-components/src/components/button/Button.svelte
  • React wrapper: libs/react-components/src/lib/button/button.tsx
  • Angular wrapper: libs/angular-components/src/lib/components/button/button.ts
  • Experimental React wrapper: libs/react-components/src/experimental/button/button.tsx
  • Experimental Angular wrapper: libs/angular-components/src/experimental/button/button.ts</agent_instructions>

Comments on the Issue (you are @copilot in this section)


💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

Adds comprehensive JSDoc comments to all React and Angular component
wrapper properties, extracted from the Svelte source-of-truth.

Changes include:
- JSDoc descriptions for all React wrapper interface props
- JSDoc descriptions for all Angular @input() decorators
- @default tags showing default values from Svelte source
- @required tags for required props
- @deprecated tags preserved from Svelte source
- Margins interface in common.ts updated with JSDoc
- Covers all 70+ components in lib and experimental directories

Closes #3159

Co-authored-by: bdfranck <1479091+bdfranck@users.noreply.github.com>
Agent-Logs-Url: https://github.com/GovAlta/ui-components/sessions/394aef6d-753c-4f64-8ac6-89a3a4049341
Copilot AI changed the title [WIP] Add JSDocs to component wrappers for better developer guidance feat(#3159): Add JSDoc comments to React and Angular component wrappers Mar 24, 2026
Copilot AI requested a review from bdfranck March 24, 2026 22:16
@bdfranck
Copy link
Collaborator

Here's the script Copilot created:
https://gist.github.com/bdfranck/5f090c4addfd064cbbc77563a056d546

…sed by initial script

The previous codegen script used regex `(\w+)\??\s*[=:]` which only
handled optional (`?`) TypeScript props but not non-null assertion (`!`)
props. Every `@Input({ required: true }) prop!: Type` line was silently
skipped.

Fixed 27 Angular wrapper files (lib + experimental) across:
- pagination (itemCount, pageNumber)
- microsite-header (type)
- skeleton (type)
- grid (minChildWidth)
- drawer (open, position)
- icon-button (icon)
- details (heading)
- icon (type)
- card-image (src, height)
- side-menu-group (heading) — lib and experimental
- file-upload-input (variant) — lib and experimental
- file-upload-card (filename) — lib and experimental
- data-grid (keyboardNav)
- menu-button/menu-action (text, action) — lib and experimental
- work-side-menu (heading, url)
- work-side-menu-item (label)
- work-side-menu-group (heading)
- work-side-notification-item (description)
- form-item-slot (slot) — lib and experimental
- popover (target)

Co-authored-by: bdfranck <1479091+bdfranck@users.noreply.github.com>
Agent-Logs-Url: https://github.com/GovAlta/ui-components/sessions/ba06df3b-2f1f-426c-bdd6-92845ab33b0c
…ing JSDoc gaps

- Add scripts/add-jsdocs.js: re-runnable codegen that reads JSDoc from Svelte
  source-of-truth and injects into React/Angular wrapper files where missing
- Supports --dry-run mode, @required/@deprecated/@default tag handling,
  boolean normalisation ("false" -> false), and experimental/ directories
- Update scripts/README.md with full usage docs for the new script
- Apply script to fix 43 wrapper files with missing JSDoc that were missed
  by the initial two commits
- Fix pre-existing corruption in experimental/checkbox-list/checkbox-list.tsx
  where original codegen incorrectly injected Svelte implementation code
  into the GoabxCheckboxListProps interface

Closes #3159

Co-authored-by: bdfranck <1479091+bdfranck@users.noreply.github.com>
Agent-Logs-Url: https://github.com/GovAlta/ui-components/sessions/16e49495-0ec3-4557-8540-b3fa171bcc11
@bdfranck
Copy link
Collaborator

@copilot There some properties that aren't in the Svelte component but are in the React and Angular Wrappers. They are TemplateRef<any> in Angular and ReactNode in React. These allow the developer to insert something into a slot. Here's an example:

libs/angular-components/src/experimental/work-side-menu/work-side-menu.ts

  @Input() primaryContent!: TemplateRef<any>;
  @Input() secondaryContent!: TemplateRef<any>;
  @Input() accountContent!: TemplateRef<any>;

libs/react-components/src/experimental/work-side-menu/work-side-menu.tsx

primaryContent?: ReactNode;
secondaryContent?: ReactNode;
accountContent?: ReactNode;

Here's what to do:

  1. Find all of these TemplateRef<any> and ReactNode properties in the wrappers
  2. Add a placeholder JSDoc comment
  3. Write "TO DO: Write a description" for the placeholder description

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

JSDocs in Wrappers

2 participants