Restructure widget folders

[tomdye]

As our widget library grows we should consider creating a better folder structure for them. This is particularly important now that we are adding multiple button and input types. There are many ways we could go about grouping our widgets.

My initial thoughts are thus;

1. Group all form widgets under a form directory. (form/Select, form/Text etc)
2. Group button widgets under a button directory. (button/Button, button/Raised etc)
3. Drop barrel files (index.ts)

Questions

1. Should we group inputs ie, Text/Number/Email etc under a form/input directory?
2. Should we group selects ie. Select/Combo/Typeahead under a form/select directory?

[samends]

Should this extend to the example app as well? For instance should we have nested menu items? The top menu bar on the example app will get kinda long

[tomdye]

yes, the example app structure will mirror the widget structure

[samends]

I think this is a good idea honestly, the widgets could get out of control especially since we're adding in all the new specialized inputs. I like the form/input nesting structure, I don't think we're going to need a button folder though unless we're planning on having alot of them. If we are I'm not sure if buttons should go under form/button to follow the pattern.

[tomdye]

Thanks for you input @samenz. I'm keen to get the rest of the communities opinions on this also however I feel that it is something that would be better tackled towards the end of this dojo 7.0 push so that we can get a better picture of what widgets we end up with and ensure that we choose the correct solution.

[msssk]

I think the nesting and organization is a good idea - logical hierarchies are much easier to make sense of and navigate.

I am a fan of barrel files, perhaps even to a greater degree. I realize a lot of decisions to simplify one thing lead to complicating another thing, so there's a need to weigh the pros and cons. Barrel files are nice for simplifying imports - what are the downsides?

When you mention barrel files I assume you're talking about form/button/Button/index.ts (exports form/button/Button/Button.ts) so that an import can be:

import Button from 'form/button/Button';

instead of

import Button from 'form/button/Button/Button';

I am in favor of retaining such barrel files for the import simplification. It may even be worth considering a barrel file in form that enables imports like:

import {
    Button,
    Text
} from 'form';

Why is button/Raised its own widget? I do think we need to find a balance between a limited number of 1-size-fits-all widgets versus a plethora of variations for every possible use case, but I feel like this one is veering into plethora territory. If a variation can be handled by theming or a single option then it would be better to keep it within an existing widget rather than creating a new widget variant.

[nicknisi]

This sounds good to me, too, but why remove barrel files? They could be auto-generated during the build.

[tomdye]

The idea of removing the index.tsx files is because we would be grouping different inputs / buttons etc under a folder and thus they would no longer have their own folder. For example:

• /button/
  • RaisedButton.tsx
  • RaisedButton.spec.tsx
  • RaisedButton.m.css
  • RaisedButton.md
  • Button.tsx
  • Button.spec.tsx
  • Button.m.css
  • Button.md
• /input/
  • Text.tsx
  • Text.spec.tsx
  • Text.m.css
  • Text.md
  • Email.tsx
  • Email.spec.tsx
  • Email.m.css
  • Email.md

@matt-gadd recently posted in dojo chat on the subject of barrel files:

I always worry about the barrels just due to the maintenance of them (we ditched barrels in framework due to this) and also i don’t think they treeshake properly still (or at least widgets isnt’ set up so it does). I care less about the shorter names nowadays due to intellisense, but to be honest i’m good with either call. The main thing I definitely do agree with is grouping them like you said.

They're also pretty terrible in an IDE when searching for files.

[msssk]

They're also pretty terrible in an IDE when searching for files.

The way they've been done has been a hassle in this regard. The module definition should definitely be in a file with a name that matches the module name. Barrel files that are just one-liners exporting another module would provide a good developer experience:

/input/
    Email/
        Email.m.css
        Email.md
        Email.spec.tsx
        Email.tsx
        index.ts

To go even further we could add group barrel files:

/input/
    index.ts (exports everything in the folder)

then you can import:

import {
    Email,
    Text
} from 'input';

[tomdye]

Just to clarify, I think people are getting confused between index files and barrel files. Both of which we wish to remove / not use.

• index files are currently used to make the existing file paths easier to reason with when importing widgets to use. ie. @dojo/widgets/button rather than @dojo/widgets/button/Button. However, they are hard to work with in the IDE as file lookups often end up at the test file and they wouldn't work with the folder reorganisation and grouping that we are proposing.
• barrel files are used to group things together and re-export them from other modules. We don't currently use these and do not wish to. One such reason for avoiding these is that they will not work with tree shaking. ie. if you import one of our many (coming soon) input widgets from a Input barrel file you would get the code / css etc for all input varieties in your bundle and this is not good.

The proposed folder / file structure alleviates all of the current issues we are having and provides the best possible experience going forward.

[tomdye]

This is being removed from dojo 7 atm due to the large number of breaking changes already created.