Automatic discovery of components to include in freestyle guide

[lukemelia]

This issue lays out a plan for adding automatic discovery of content for the styleguide.

This plan takes some inspiration from @Turbo87's blog post Autodiscovery for the Ember.js component playground but imagines a different approach then outlined in the post.

The goal is to reduce the friction and busy-work of adding and updating components to your freestyle guide. Specifically, it allows for colocating a "freestyle" component with the component is is demonstrating and removes the need to edit the main freestyle.hbs template, which otherwise can become unwieldy in large apps.

There are two parts of the plan:

1. Build-time discovery via ember-cli hook
2. Run-time generation with a component and service pair

There are also number of related ideas to improve the experience further.

Here are some details on the above, followed by a step-by-step plan:

1) Build-time discovery via ember-cli hook

ember-freestyle will discover components from app's file structure at build time. This will be implemented via the preprocessTree hook and a configurable set of path patterns for which matching files will be considered components to be included. Those component names will be written to a "manifest" module for consumption at run-time.

The proposed default file path patterns are:

• app/components/**/freestyle/component.js
• app/components/**/freestyle.js
• app/components/freestyle/*.js

TODO: What additional patterns, if any, are necessary to support:

• the module unification layout?
• template-only components?

The manifest module will be named -freestyle/discovered-components.js and export an array of the discovered component names.

2) Run-time generation with a component and service pair

The ember-freestyle service will be updated to import the manifest module that is generated at build time and expose it as a property named discoveredComponents on the service.

A new component will be provided by ember-freestyle to allow including these discovered components. It will looks like this in the generated freestyle.hbs template:

  {{freestyle-auto}}

This component will iterate over the discoveredComponents array from the service and use the component helper to output each component.

Related ideas

• The preprocessTree hook should also be able to remove match components for production builds based on a config flag. This allows an consuming app to get the benefits of freestyle in development, without a size or load time penalty in production.

• Currently, all freestyle entries need to be wrapped in the freestyle-usage component. This creates some annoying boilerplate and we would like to make this optional for these auto-discovered components. The same goes for within freestyle-collection's variant blocks.

• There is a strong likelihood that the work required fo this plan will allow us to improve the efficiency and robustness of the snippet finder code used by ember-freestyle. We can also move sass and js snippet parsing to a plugin as it is not used frequently in our experience.

• Another idea, likely suitable for a plugin, would be to allow automatic generation of freestyle components via ember-cli-prop-types data and an AST traversal.

Detailed implementation steps:

• broccoli code to discover components and write -freestyle/discovered-components.js file
  • basic implementation
  • refactor FreestyleDiscovery plugin to ES6 (example: https://github.com/embermap/ember-cli-tailwind/blob/master/lib/build-tailwind-plugin.js)
• freestyle-auto-section outputs discovered components
• configurable auto-discover path pattern
• configurable auto-discover component name (default: 'freestyle') (TODO: maybe we should encourage usage?)
• Beta release
• allow preprocessTree to optionally remove matched files instead, to remove them for production builds, with a configuration option to control this
• Beta release
• allow discovered components to declare a freestyle section and subSection and organize the nav accordingly
• Beta release
• make slug optional for freestyle-usage
• make freestyle-usage optional within discovered component
• make freestyle-usage optional within freestyle-variant
• Beta release
• make snippetPaths array leverage configured discovery paths
• make SnippetFinder less regexp-dependent
• Beta release
• move sass and js snippet parsing to a plugin
• Beta release

Other ideas:

• bundle configuration options as strategies?
• Enable automatic auto-discovery output on freestyle-guide without including an additional component
• prop-types plugin to auto-generate usage components

[Turbo87]

@lukemelia the reason why we're not colocating the files is that we don't want to ship them with the production app, and having them in an in-repo-addon means that we can disable the addon for the production build. maybe I missed it, but that does not seem to be mentioned in the plan above? 🤔

[lukemelia]

@Turbo87 Thanks for that reminder! This is something I discussed with @chrislopresto but didn't make it in the doc. I have now updated.