Allow passing a prop type or interface directly to the `props` option in the docs #3771

ashikmeerankutty · 2020-07-20T17:34:08Z

Summary

Added a custom webpack loader to transform types and interfaces to objects and export them from the files.
Added typescript module declaration for the custom loader
Property __docgenInfo of the object contains types of props so it can be directly used in the docs page.
Added interfaces and types of Datagrid and ColorPicker examples to docs.
Used resolveLoader in webpack config to create alias for relative path of loader.

Checklist

~~- [ ] Check against all themes for compatibility in both light and dark modes~~
- [ ] Checked in mobile
- [ ] Checked in IE11 and Firefox
- [ ] Props have proper autodocs
- [ ] Added documentation
~~- [ ] Checked Code Sandbox works for the any docs examples~~
- [ ] Added or updated jest tests

Checked for breaking changes and labeled appropriately

~~- [ ] Checked for accessibility including keyboard-only and screenreader modes~~
~~- [ ] A changelog entry exists and is marked appropriately~~

kibanamachine · 2020-07-20T17:34:10Z

Since this is a community submitted pull request, a Jenkins build has not been kicked off automatically. Can an Elastic organization member please verify the contents of this patch and then kick off a build manually?

thompsongl · 2020-07-20T21:34:54Z

Can you add examples to show this working? The EuiPopoverPosition and PaginationBarProps output shown in the issue would be good enough, I think.

ashikmeerankutty · 2020-07-20T22:33:39Z

Can you add examples to show this working? The EuiPopoverPosition and PaginationBarProps output shown in the issue would be good enough, I think.

Added a basic example. it could be found on the props table of basic table.

thompsongl · 2020-07-20T22:43:18Z

jenkins test this

kibanamachine · 2020-07-20T23:07:08Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_3771/

chandlerprall

Nice, that didn't end up too bad :)

For the EuiPopoverPosition & PaginationBarProps examples, those should be applied to their respective pagees/sections instead of taking over the basic table's props rendering.

ashikmeerankutty · 2020-07-23T03:06:49Z

For the EuiPopoverPosition & PaginationBarProps examples, those should be applied to their respective pagees/sections instead of taking over the basic table's props rendering.

I added those for demo 😄 . I guess there are so many possible places where props of types and interfaces must be shown. Should I do that ?

chandlerprall · 2020-07-23T17:30:15Z

I added those for demo 😄 . I guess there are so many possible places where props of types and interfaces must be shown. Should I do that ?

Gotcha! Let's get at least a couple of those done as part of this PR. The other instances can follow later, especially if you find yourself waiting on us for something else.

ashikmeerankutty · 2020-07-23T19:59:08Z

EuiPopOverPosition is not used in any of the components as a prop type. PaginationBarProps is used in basic table. but the doc info of basic table is added manually. Should I replace PaginationBarProps in the doc info of basic table ?

chandlerprall · 2020-07-23T20:11:09Z

Should I replace PaginationBarProps in the doc info of basic table ?

Nah; let's see, I think the data grid props would really benefit from this

eui/src-docs/src/views/datagrid/datagrid_example.js

Lines 352 to 366 in 8ff1efb

 props: { 

 EuiDataGrid, 

 EuiDataGridColumn: DataGridColumn, 

 EuiDataGridColumnVisibility: DataGridColumnVisibility, 

 EuiDataGridControlColumn: DataGridControlColumn, 

 EuiDataGridInMemory: DataGridInMemory, 

 EuiDataGridPagination: DataGridPagination, 

 EuiDataGridSorting: DataGridSorting, 

 EuiDataGridCellValueElement: DataGridCellValueElement, 

 EuiDataGridSchemaDetector: DataGridSchemaDetector, 

 EuiDataGridStyle: DataGridStyle, 

 EuiDataGridToolbarVisibilityOptions: DataGridToolbarVisibilityOptions, 

 EuiDataGridToolBarVisibilityColumnSelectorOptions: DataGridToolBarVisibilityColumnSelectorOptions, 

 EuiDataGridPopoverContent: DataGridPopoverContent, 

 },

Another good place is the color picker.

ashikmeerankutty · 2020-07-23T20:42:06Z

When using the new method in data grid it was found that types are not expanded For eg:

I think this can be fixed in the plugin. I will try to fix this and commit.

ashikmeerankutty · 2020-07-24T17:42:54Z

One thing to note here. If the types are exported using index.ts. It will show as the type is not exported. Since typescript strips that information. In order to work the types must be exported directly from the file

chandlerprall · 2020-07-27T15:59:30Z

The props tab for Color palette picker errors with

guide_section.js:30 Uncaught TypeError: Cannot read property 'split' of undefined
at markup (guide_section.js:30)
at guide_section.js:316
at Array.map ()
at GuideSection.renderPropsForComponent (guide_section.js:292)
at guide_section.js:412
at Array.map ()
at GuideSection.renderProps (guide_section.js:411)
at GuideSection.renderContent (guide_section.js:495)
at GuideSection.render (guide_section.js:522)
at finishClassComponent (react-dom.development.js:18470)

ashikmeerankutty · 2020-07-27T16:47:09Z

The props tab for Color palette picker errors with

guide_section.js:30 Uncaught TypeError: Cannot read property 'split' of undefined
at markup (guide_section.js:30)
at guide_section.js:316
at Array.map ()
at GuideSection.renderPropsForComponent (guide_section.js:292)
at guide_section.js:412
at Array.map ()
at GuideSection.renderProps (guide_section.js:411)
at GuideSection.renderContent (guide_section.js:495)
at GuideSection.render (guide_section.js:522)
at finishClassComponent (react-dom.development.js:18470)

Cache showed no error so I missed it 😞 . I will fix this.

ashikmeerankutty · 2020-07-27T17:09:54Z

@chandlerprall Thanks for the review. Fixed it 😃

thompsongl · 2020-07-27T17:16:47Z

jenkins test this

kibanamachine · 2020-07-27T17:41:16Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_3771/

chandlerprall · 2020-07-27T19:41:24Z

Thinking through this change and how it can impact things in the future: the syntax of passing a type/interface as a value in the props object is invalid typescript, and when the examples are converted will need a lot of @ts-ignore to make it work.

Only thing I can think of is, instead of making this a babel plugin, do this same logic/conversion in a webpack loader. Then we can specify the loader in the examples when importing the type,

import * as EuiColorProps from '!!props-loader!../../../../src/components/color_picker/color_palette_picker/color_palette_picker';

...

{props: pick(EuiColorProps, ['EuiColorPalettePickerPaletteText', 'EuiColorPalettePickerPaletteFixed', 'EuiColorPalettePickerPaletteGradient'])}

Webpack loader results can be defined in .d.ts files, like

declare module '!!props-loader!*' {
  const contents: { [key: string]: PropsDefinitionType };
  export = contents;
}

ashikmeerankutty · 2020-07-27T19:52:56Z

Only thing I can think of is, instead of making this a babel plugin, do this same logic/conversion in a webpack loader.

Sure I will convert this into a webpack loader

chandlerprall · 2020-07-31T21:32:12Z

@ashikmeerankutty I'm looking into how to replace the type/interface with the object, instead of appending. I have that "working", but for some reason babel still sees/errors on a duplicate export name 😕

I'll let you know what I find

…types & interfaces; use the loader specifically when needed

chandlerprall · 2020-08-03T16:03:26Z

@ashikmeerankutty I sent a PR your way ashikmeerankutty#4

I don't like having to use a relative path to specify the prop-loader , would you mind investigating some to see if there's a way to specify a local webpack loader without the relative path? I have some ideas for "fixing" that, but I'd like to see if anyone has a better solution first :)

note: I have not addressed the typescript module issue, as the current examples aren't TS files. Also think we need to address the loader-as-a-relative-path issue before the TS module.

…ement Update prop-loader & usage

ashikmeerankutty · 2020-08-03T18:09:38Z

@chandlerprall Reading through the docs https://webpack.js.org/configuration/resolve/#resolvealias this seems to work. But I couldn't make it work on the project. 😞

ashikmeerankutty · 2020-08-05T14:04:13Z

@chandlerprall Reading through the docs https://webpack.js.org/configuration/resolve/#resolvealias this seems to work. But I couldn't make it work on the project. 😞

Fixed it. Can you please review it

chandlerprall · 2020-08-05T16:33:29Z

Nice, good find with resolveLoader!! src-docs/src/views/datagrid/props.tsx and src-docs/src/views/color_picker/props.tsx should be deletable now. I expect the playground things you commented out can be re-enabled now too.

I'm looking into the typescript side of this; I can get a module declaration for the loader, but having some issues with getting the imports right, mostly around being able to define arbitrary named exports.

@cchaos would you mind taking a look at the usage here? Primarily the !!prop-loader!... imports in the data grid and color picker example files. Just want a sanity check that it isn't a terrible change in developer experience.

ashikmeerankutty · 2020-08-05T17:25:09Z

I'm looking into the typescript side of this; I can get a module declaration for the loader, but having some issues with getting the imports right, mostly around being able to define arbitrary named exports.

I tried using the wildcard but still its showing cannot find module

cchaos · 2020-08-05T17:37:23Z

I think that's ok from a dev/syntax experience. So long as we have examples to copy/paste from and probably add a section to our Documentation guidelines wiki doc.

Is this PR also supposed to show the examples currently working in the docs? I'm wondering how we will now "link" to the props table as references like how we would do #EuiPropsOfSomething in the prop comments.

chandlerprall · 2020-08-05T19:13:12Z

I tried using the wildcard but still its showing cannot find module

I added a prop-loader.d.ts file into src/custom_typings with

declare module '!!prop-loader!*' {
  const contents: Record<string, any>;
  export = contents;
}

which allows, e.g.

import * as EuiDataGridTypes from '!!prop-loader!...';

but not

import {TypeA, TypeB, TypeC, ...} from '!!prop-loader!...';

chandlerprall · 2020-08-05T19:18:05Z

I think that's ok from a dev/syntax experience. So long as we have examples to copy/paste from and probably add a section to our Documentation guidelines wiki doc.

Is this PR also supposed to show the examples currently working in the docs? I'm wondering how we will now "link" to the props table as references like how we would do #EuiPropsOfSomething in the prop comments.

The links continue working the same, just verified locally where EuiDataGridColumnVisibility references EuiDataGridColumn and that jump works.

ashikmeerankutty · 2020-08-06T08:16:37Z

import {TypeA, TypeB, TypeC, ...} from '!!prop-loader!...

I couldn't find a better way to solve this issue till now. The only way I found was to define the module as any as

 declare module '!!props-loader!*';

so that we can import in any way we want.

This can avoid the use of tsignore.

chandlerprall · 2020-08-06T15:09:39Z

import {TypeA, TypeB, TypeC, ...} from '!!prop-loader!...

I couldn't find a better way to solve this issue till now. The only way I found was to define the module as any as
 declare module '!!props-loader!*';
so that we can import in any way we want.

This can avoid the use of tsignore.

Perfect! I confirmed that module declaration allows the import. Woo! Can you push that .d.ts file and update the PR description to reflect all the changes? I don't think this needs any work beyond that; I'll do a another review after this last addition is pushed.

ashikmeerankutty · 2020-08-06T15:33:23Z

Can you push that .d.ts file

Should I add the declaration file to src/custom_typings directory or in the scripts directory ?

chandlerprall · 2020-08-06T15:45:28Z

Please add it to src/custom_typings, typescript is already configured to look there and will pick it up automatically.

ashikmeerankutty · 2020-08-06T15:52:32Z

@chandlerprall Pushed the changes 😃 . Can you please review it

thompsongl · 2020-08-11T18:23:46Z

jenkins test this

kibanamachine · 2020-08-11T18:47:24Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_3771/

chandlerprall

LGTM! Examples' props come through the same, new code looks good, nice isolated use with the custom loader.

Thanks again @ashikmeerankutty !

thompsongl · 2020-08-11T22:06:27Z

🎉 Great work!

… in the docs (#3771) * Add docgen from ts props babel plugin * Add a basic example for demo * Removed example * Remove props.tsx and use props directly * Expand types * Passed interfaces directly to props in color picker example * Fixed type value in extended props * Added props-loader to convert interfaces to props * removed logger for result * Add comments * Update the prop-loader script to output only the processed, exported types & interfaces; use the loader specifically when needed * Fixed relative path for loader * Removed props.tsx files and uncomment playground files * removed docgen from ts props * Declare module as any * Add prop-loader declaration to custom typings Co-authored-by: Chandler Prall <chandler.prall@gmail.com>

Add docgen from ts props babel plugin

7968aed

Add a basic example for demo

6b9a0ec

thompsongl requested review from chandlerprall and thompsongl July 21, 2020 23:14

chandlerprall suggested changes Jul 22, 2020

View reviewed changes

ashikmeerankutty mentioned this pull request Jul 23, 2020

[GSOC] Automatic Documentation System for TypeScript Components #3554

Merged

92 tasks

Removed example

4a033fb

Remove props.tsx and use props directly

38839d4

ashikmeerankutty added 2 commits July 24, 2020 22:04

Expand types

2aa0a5d

Passed interfaces directly to props in color picker example

9fcaaec

Fixed type value in extended props

12da631

ashikmeerankutty requested a review from chandlerprall July 27, 2020 17:09

ashikmeerankutty added 2 commits August 1, 2020 01:00

removed logger for result

db73a0e

Add comments

402784f

Update the prop-loader script to output only the processed, exported …

1680a65

…types & interfaces; use the loader specifically when needed

ashikmeerankutty added 2 commits August 3, 2020 21:42

Merge pull request #4 from chandlerprall/types-transform-replace-stat…

706a840

…ement Update prop-loader & usage

Merge remote-tracking branch 'upstream/master' into types-transform

f7c524e

Fixed relative path for loader

a402ac0

ashikmeerankutty added 2 commits August 5, 2020 22:21

Removed props.tsx files and uncomment playground files

af6e599

removed docgen from ts props

2d166ef

Declare module as any

4adb6f3

Add prop-loader declaration to custom typings

4ee861c

chandlerprall approved these changes Aug 11, 2020

View reviewed changes

chandlerprall merged commit 7572226 into elastic:master Aug 11, 2020

Allow passing a prop type or interface directly to the props option in the docs #3771

Allow passing a prop type or interface directly to the props option in the docs #3771

Conversation

ashikmeerankutty commented Jul 20, 2020 • edited Loading

Summary

Checklist

kibanamachine commented Jul 20, 2020

thompsongl commented Jul 20, 2020

ashikmeerankutty commented Jul 20, 2020

thompsongl commented Jul 20, 2020

kibanamachine commented Jul 20, 2020

chandlerprall left a comment

Choose a reason for hiding this comment

ashikmeerankutty commented Jul 23, 2020

chandlerprall commented Jul 23, 2020

ashikmeerankutty commented Jul 23, 2020

chandlerprall commented Jul 23, 2020

ashikmeerankutty commented Jul 23, 2020

ashikmeerankutty commented Jul 24, 2020

chandlerprall commented Jul 27, 2020

ashikmeerankutty commented Jul 27, 2020

ashikmeerankutty commented Jul 27, 2020

thompsongl commented Jul 27, 2020

kibanamachine commented Jul 27, 2020

chandlerprall commented Jul 27, 2020 • edited Loading

ashikmeerankutty commented Jul 27, 2020

chandlerprall commented Jul 31, 2020

chandlerprall commented Aug 3, 2020 • edited Loading

ashikmeerankutty commented Aug 3, 2020

ashikmeerankutty commented Aug 5, 2020

chandlerprall commented Aug 5, 2020 • edited Loading

ashikmeerankutty commented Aug 5, 2020

cchaos commented Aug 5, 2020 • edited Loading

chandlerprall commented Aug 5, 2020

chandlerprall commented Aug 5, 2020

ashikmeerankutty commented Aug 6, 2020

chandlerprall commented Aug 6, 2020 • edited Loading

ashikmeerankutty commented Aug 6, 2020 • edited Loading

chandlerprall commented Aug 6, 2020

ashikmeerankutty commented Aug 6, 2020 • edited Loading

thompsongl commented Aug 11, 2020

kibanamachine commented Aug 11, 2020

chandlerprall left a comment

Choose a reason for hiding this comment

thompsongl commented Aug 11, 2020

Allow passing a prop type or interface directly to the `props` option in the docs #3771

Allow passing a prop type or interface directly to the `props` option in the docs #3771

ashikmeerankutty commented Jul 20, 2020 •

edited

Loading

chandlerprall commented Jul 27, 2020 •

edited

Loading

chandlerprall commented Aug 3, 2020 •

edited

Loading

chandlerprall commented Aug 5, 2020 •

edited

Loading

cchaos commented Aug 5, 2020 •

edited

Loading

chandlerprall commented Aug 6, 2020 •

edited

Loading

ashikmeerankutty commented Aug 6, 2020 •

edited

Loading

ashikmeerankutty commented Aug 6, 2020 •

edited

Loading