feat: typescript improvements

gclark-eightfold commented 2 months ago

SUMMARY:

Modifies the tsconfig.json to enable JSDoc comments to be compiled with the compiled .d.ts files. This is a DX improvement allowing developers to reference the types instead of needing to look at source code or documentation when writing components.
```
// lib/components/Dropdown/Dropdown.types.d.ts
```

// BEFORE: ❌ No JSDoc comments are emitted to the .d.ts files, with export interface DropdownProps { ariaRef?: React.MutableRefObject; children?: React.ReactNode; // ... }

// After: ✅ JSDoc comments are emitted to the .d.ts files export interface DropdownProps { /**

The ref of element that should implement the following props:
'aria-controls', 'aria-expanded', 'aria-haspopup', 'role'
@default child */ ariaRef?: React.MutableRefObject; /**
The child renderer.
@deprecated Wrap your element instead, e.g. <Dropdown><MyElement /></Dropdown>. */ children?: React.ReactNode; // ... }

Upgrades @types/react to the latest v17 patch version. This includes a fix for the PropsWithoutRef type which was affecting the compiled type for Panel. See: https://github.com/DefinitelyTyped/DefinitelyTyped/pull/65639
```
// lib/components/Panel.d.ts
```

// AFTER: ✅ This type is much better and works withmodule augmentation if extending something like HTMLAttributes in application code export declare const Panel: React.ForwardRefExoticComponent<Omit<PanelProps, "ref"> & React.RefAttributes>;

```ts
// my-app/types/react.d.ts (in application / consuming code)

// BEFORE: ❌ Augmenting HTMLAttributes works for all Octuple components *except* for Panel.
// AFTER:  ✅ Augmenting HTMLAttributes works for ALL Octuple components.
import { HTMLAttributes } from "react";
declare module "react" {
  interface HTMLAttributes<T> {
    /**
     * An example global attribute w/ expected types defined.
     */
    "data-custom-global-attribute"?: "open" | "closed";
  }
}

GITHUB ISSUE (Open Source Contributors)

JIRA TASK (Eightfold Employees Only):

https://eightfoldai.atlassian.net/browse/ENG-100260

CHANGE TYPE:

[x] Bugfix Pull Request
[x] Feature Pull Request

TEST COVERAGE:

[x] Tests for this change already exist
[ ] I have added unittests for this change

TEST PLAN:

Run yarn build
- [ ] Observe that the files like lib/components/Dropdown/Dropdown.types.d.ts include JSDoc comments.
Create a pre-release build of Octuple and install in application code (or patch the node_modules locally)
Include the above snippet somewhere in application code to augment HTMLAttributes for react.
- [ ] When typing data- on a Panel component, you will now see an autocomplete suggestion for data-custom-global-attribute.
- [ ] Passing an invalid prop to data-custom-global-attribute on Panel will show a type error.

codesandbox-ci[bot] commented 2 months ago

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

codecov[bot] commented 2 months ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 84.63%. Comparing base (6de011a) to head (492f9af).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #863 +/- ## ======================================= Coverage 84.63% 84.63% ======================================= Files 1098 1098 Lines 20354 20354 Branches 7690 7690 ======================================= Hits 17226 17226 Misses 3043 3043 Partials 85 85 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

EightfoldAI / octuple