We want to ship client side behavioural elements with Primer View Components to increase the fidelity of our components.
Doing so requires us to align to a set of constraints for the Browser ecosystem, as well as the ecosystems that consumers of Primer View Components have:
primer/components which is also a motivating factor.
Behaviours will live in TypeScript files in the
app/components directory next to their respective
.rb files. By convention files will be named with the same basename as the Ruby counterpart. An
app/components/primer.ts file will also exist which must import all other
.ts files, acting as an index file. A single
.js file with no external dependencies, which will live in
import "@primer/view_components" within their JS, which means their JS toolchain will be able to perform necessary transformations or optimisations. This will also allow for selective component imports, for example
import "@primer/view_components/time_ago_component" could import just
We will test our behaviours in the Browser environment (using Rails System tests), as this is where they will be consumed. This will require using Browser APIs to automate testing. We will use test automation libraries that automate browsers via the Devtools Protocol such as Puppeteer, Playwright or Ferrum. Using a Devtools Protocol based tool gives us the best level of flexibility in testing, while also being compatible with current browsers.
We will document which components are behavioural, so that consumers are aware they are required to load the client side bundle code for these components to work properly. We will offer a documentation page on how to use the
This library will be able to provide behaviours for higher fidelity components, using consistent methods that lean to the strengths of the Rails & JS ecosystems.
Contributors of Primer View Components will need to have an understanding of TypeScript if they wish to author behavioural components.
There will be additional work for our consumers if they wish to use behavioural components. Consumers will need to use the