Organize repo to consistently have an import per component

[rajsite]

Currently nimble-components and nimble-angular organize each component into a separate directory with separate import strategies.

Edit August 2023:

The current recommendation would be as follows (these are not coupled, we could do the smaller nimble-components work first):

• nimble-components:
  • Switch to using npm package entry points
  • Leveraging package entrypoints, elide the dist/esm from import paths so for instance a button import changes from import '@ni/nimble-components/dist/esm/button'; to import '@ni/nimble-components/button';
  • Should decide how we migrate to es module resolution within the package. i.e. showing the full extension in the import path.
  • Should decide what is private and what is public apis in nimble-components when using package exports.
    • Could potentially stage the private/public enforcement before the rename to remove dist/esm. This could help avoid bugs like we fixed in #2290
• nimble-angular:
  • Switch to secondary entrypoints per directive. Note: we should profile build performance before going down this road. We might also want to be on a nearly-new version of Angular to get modern performance numbers.
  • Switch to Angular single file / standalone component pattern for our directives, pipes, etc.
  • Leveraging secondary entrypoints and single file components an angular app can avoid needing to import a Module per component and would import a button directive from @ni/nimble-angular/button
• Go through the comments in the thread and make sure they are addressed

Known issues this change will resolve:

• In nimble-angular today the vast majority of components are exported together from the top-level primary entrypoint. Any import at that level results in all components from that entry point being registered and defined in a page: https://github.com/ni/nimble/issues/1476

[jattasNI]

As part of closing this issue we should include CONTRIBUTING docs that explain whatever layout philosophy we land on.

[rajsite]

Related tasks for repo layout:

• We should use npm "exports" so that users importing controls do not see /dist/esm in their import paths.
  • hmmmm I wonder if conditional exports would help with the issues I was having in https://github.com/ni/nimble/pull/272#discussion_r791063093. We could potentially keep the package as the default type (commonjs) and have conditional exports for the import condition. Maybe the script would allow imports correctly then?
• We should do the same for the Angular package. It's possible that only works in Angular 13 though since that's the first time exports is discussed in docs
  • We need to make each set of related modules a separate export. The issue right now is that because they are all exported together, and because we intentionally use imports with side-effects, the dead-code checkers can't toss unused component definitions. Importing a button imports all the components. If each module is moved to secondary imports via the exports feature, ie import {ButtonModule} from '@ni/nimble-angular/button'; then dead code elimination can work as expected.

[rajsite]

As part of this work we should control our exports. This helps two issues, one is the Angular warning about deep entry points:

 - Generating browser application bundles (phase: setup)...Warning: Entry point '@ni/nimble-angular' contains deep imports into 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/button/types', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/button', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/checkbox', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/drawer/types', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/drawer', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/listbox-option', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/menu', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/menu-item', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/number-field', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/select', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/tab', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/tab-panel', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/tabs', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/tabs-toolbar', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/text-field/types', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/text-field', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/theme-provider/types', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/theme-provider', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/tree-item', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/tree-view/types', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/tree-view', 'C:/dev/github/nimble/node_modules/@ni/nimble-components/dist/esm/testing/async-helpers'. This is probably not a problem, but may cause the compilation of entry points to be out of order.

The other is we can prevent implementation details from being exposed externally, like stuff in src/patterns styles.

[rajsite]

As part of adding secondary entrypoints to the nimble-angular library we should export the ButtonAppearance from each component. See https://github.com/ni/nimble/pull/344/files#r803863208

[rajsite]

Some initial research:

• TypeScript support for npm package exports did not make it in TS 4.5, but should be in 4.6. Not sure if that actually blocks us.
• Angular 13 has supports for using npm package exports. But can still use the older multiple package.json approach. We can likely start with the multiple package.json approach in 12 today.

[rajsite]

As part of this work we should control our exports. This helps two issues, one is the Angular warning about deep entry points:

The other is we can prevent implementation details from being exposed externally, like stuff in src/patterns styles.

In addition, we should evaluate our exported .d.ts files to make sure internal libraries are not exposed and move @types to devDependencies where possible. See https://github.com/ni/nimble/pull/831/files#r1029565900

[rajsite]

Related issue suggesting we should use package exports as described above. That is technically independent of re-organizing the repo so not closing as a duplicate. It's essentially a subtask of this issue https://github.com/ni/nimble/issues/694

[rajsite]

As part of a repo re-org we should move the design-tokens to a top-level export so applications that only need the tokens can adopt them independently of the theme-provider or of importing elements. Example the microstrategy theme customization and the nimble landing page which just need the tokens and no components.

[rajsite]

As part of adding secondary entrypoints to nimble-angular we should expose testing entrypoints as we have done in nimble-components.

[jattasNI]

I created an AzDO tech debt feature to help us prioritize this large body of work against other non-tech debt work. Feature 2677713: [Tech Debt] Nimble entry point refactor

[jattasNI]

Next step is to create an HLD that describes the overall plan. It should cover the issues raised in the comments and description above.