⚡ PatternFly Elements 2.0: Lit, TypeScript, pfe-tools, and more #1804

bennypowers · 2021-10-25T13:19:59Z

🔥 🐵 Migrate to Lit ⚡ 🚧

This PR aims to massively overhaul the PatternFly Elements codebase: updating it, reducing its complexity, and improving both the user's and the contributor's experience

Sticky Notes

What has changed and why

Adopt TypeScript

Gains: code correctness, API documentation, developer ergonomics

TypeScript allows us to find and eliminate bugs before they hit production. In the process of converting components, several of these types of problems were identified and ameliorated. TypeScript also lets us develop faster and with confidence, as the objects in our project and their behaviour are now are well-defined. As well, adopting TypeScript is an a11y feature for contributors, as the IDE features of ts language server let them access information about the objects 'under their cursor' faster, without having to page back and forth between docs (as much)

Adopt Custom Elements Manifest

Gains: standards, complexity, bundle size, tooling

This PR removes the custom manifest schema developed for PFE in favour of the custom elements manifest, a community standard for documenting javascript packages, particularly geared to web components. By documenting our components in the manifest, tooling such as docs-site generators and IDEs will be able to understand the contents of our components and their abilities without requiring us to ship that code over the wire to end users.

In particular, our 11ty docs site now uses the generated manifests to generate docs pages.

Removed `PFElement` base class and package in favour of `LitElement`

Gains: maintainability, performance, complexity

The PFElement base class implemented a wide variety of features, some related to DOM templating and component lifecycle, others related to analytics, still more related to 'colour context'. The DOM templating and component lifecycle features are the main reason we're switching to Lit - they are well maintained there, so removing that code from PFE frees us up to 'move up the stack' and focus on UI problems. Other features like colour context, analytics events, etc, could therefore be replaced by reactive controllers and typescript decorators, allowing component authors to add them to elements a la carte. This will result in smaller javascript payloads for some pages

Rename slots and events

Gains: API surface, best practices

Slot names like pfe-card--header have been renamed to simply header. This is in line with web components community best practices and conventions and simplifies element APIs, amking them easier to use.
The old slots will still work, until the next major version, so upgrading should be smooth.

Rename events and deprecate `CustomEvent`

Gains: API surface, semantics

CustomEvent is a throwback to a time when the spec did not allow us to subclass Event. Now that we can, we can prefer to define our own event classes. This lets us validate event's data at run time, use instanceof to validate them in listeners, and generally improve API readability. Events are still composed, so analytics code should be able to pick them up.

As well, events like pfe-clipboard:copied are renamed (in their new form) to copied, for simplicity, and framework compatibility.

The old CustomEvent-based events are still used, under their old names, until the next version, to aid in migration

Adopt a 'buildless' development workflow

Gains: Developer's time

Contributors no longer need to keep a file watcher to re-compile components when working on elements. Instead, source files (typescript and sass) are compiled on-the-fly by the dev server. Just install dependencies and run npm start

Adopt Playwright for E2E and visual regression tests

Update to `dart-sass`

Gains: build performance, language features, security

node-sass is deprecated. Updating to dart-sass improved performance and made new language features available.

Rewrite the element generator

Gains: fewer dependencies

Removed the dependency on yeoman and rewrote the element generator to generate LitElements for PFE. once published, contributors will be able to npm init @patternfly/element

Add `@patternfly/pfe-tools`

Gains: Simplify root repository, unblock template repo

Users wishing to develop their own set of elements based on patternfly will be able to clone a template repo and import tooling helpers from @patternfly/pfe-tools. This will include things like

dev server and testing configuration
build scripts and config
custom-elements manifest analyzer config

Add Linting Rules

Gains: code standards, readability, consistency

This PR adds eslint rules for PFE. It's recommended to install an ESLint plugin for your editor and enable "fix on save"

Remove `<pfe-navigation>`

The decision was taken to move pfe-navigation downstream to red hat's design system. This frees up PFE to concentrate on lower-level components

Add Lighthouse Testing in CI

Gains: performance and a11y visibility

PRs will now be tested using lighthouse against each element's demo page and the results formatted and printed to the PR thread

Commitlint Reporting

Gains: repo consistency

Commitlint errors and warnings will now be reported to the PR thread.

Testing instructions

Step 0: Edit the checklist in the PR description for codereview
Open a tab to patternflyelements.org docs to the element you’re reviewing
Open a tab to the deploy preview docs to the element you’re reviewing

Clone the repo and/or fetch/reset the branch

git fetch && git reset --hard origin/feat/pfe-tools

Install deps and run the dev server
```
npm ci && npm start
```
Do the new docs accurately reflect the new version?
Do the changes in the new version make sense?
While reviewing, requested changes should go in github PR review comments

Review Work Assignments

Check the box and tag your GitHub user to claim an element for review.

Core

pfe-sass
pfe-styles
pfe-core (@kylebuch8, @mwcz, @heyMP)

Elements

Ready-for-merge Checklist

Commit history rebased and cleaned up
Expected files: all files in this pull request are related to one request or issue (no stragglers ~~or scope-creep~~).
Tests have been updated to cover these changes.
Browser testing passed.
Changelog updated.
Documentation (README.md, WHY.md, etc.) updated or added.
Link to the demo recording:
Approved by designer.

Related issues

Preview

Deploy Preview Link

Merging

Please rebase when merging and ensure your commit messages use conventional commit formatting.

Be sure to share your updates with the patternfly-elements-contribute@redhat.com mailing list!

bennypowers · 2021-10-31T18:30:28Z

Heads up to everyone following this branch, I just rebased and force pushed in order to organize the commit history. It should be much easier to follow the progression of commits now, but it does mean you should fetch and reset your local branch

**Fixes** - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - inline docs - refactor docs page - add changeset

**Features** - add parts for wrapper elements, updated docs (#1836) - add {{version}} to element classes **Tests** - e2e tests with page object model **Breaking Changes** - remove public `has_` attrs **Docs** - fix demo - inline docs - refactor docs page - add changeset - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - synchronize `type` attr **Breaking Changes** - use ::slotted button instead of copying button into shadow DOM **Fixes** - slotted button styles - add {{version}} to element classes - reflect disabled attribute - rename `pfeEvent` to `deprecatedCustomEvent` **Tests** test(button): e2e tests test(button): e2e tests with page object model **Docs** - todo for context support - fix demo - inline docs - add changeset

**Features** - add parts to card - update docs (#1842) - transfer css props from docs to CEM - chore: fix href in demo - add {{version}} to element classes **Fixes** - make imgSrc optional **Tests** - adjust test for changes in slot controller - e2e tests with page object model **Breaking Changes** - remove public `has_` attrs **Docs** - inline docs - refactor docs page - add changeset - document CSS parts - fix a11y bugs in demo - use pfe-styles - simplify demo Co-Authored-By: Michael Potter <mgp140@gmail.com> Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - updated size of copy icon for Safari display (#1824) **Fixes** - hide deprecated slot when not in use - add CopiedEvent - rename `pfeEvent` to `deprecatedCustomEvent` - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - inline docs - fix a11y bugs in demo - use pfe-styles - add changeset Co-Authored-By: Rob Lahoda <rob@roblahoda.com> Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add CSS parts - remove `<slot>` - remove unused private `codeblock-render` attr - simplify class methods with computed render vars - add {{version}} to element classes **Tests** - e2e tests with page object model **Docs** - rearrange docs urls - fix demo - inline docs - refactor docs page - add changeset - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - `expand()` and `collapse()` methods **Fixes** - compose UI events - rename `pfeEvent` to `deprecatedCustomEvent` - do not export styles - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - inline docs - add changeset

**Fixes** - compose UI events - rename `pfeEvent` to `deprecatedCustomEvent` - add {{version}} to element classes - removed duplicate event listener in connectedCallback - add lightdom CSS build script **Docs** - rearrange docs urls - add changeset - use pfe-styles **Tests** - e2e tests with page object model - build demo with optional shadowroot Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com> Co-Authored-By: Kyle Buchanan <kylebuch8@gmail.com>

**Fixes** - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - inline docs - refactor docs page - add changeset - use pfe-styles - update changeset Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - switched to options in docs. Added public expanded property. Updated tests - add CSS shadow parts **Fixes** - compose UI events - rename `pfeEvent` to `deprecatedCustomEvent` - remove extra focus() method - use focus-within in item - moved public focus method to private. (#1851) - add {{version}} to element classes - add guard for item clicks - prev next keyboard actions for items - fixed keyboard navigation. added tests to cover a11y tests - added better tests, weeded out race conditions **Tests** - e2e tests - fix types in e2e tests - e2e tests with page object model - build demo with optional shadowroot - pick nits in dropdown tests **Docs** - rearrange docs urls - inline docs - add changeset - use pfe-styles Co-Authored-By: Michael Potter <mgp140@gmail.com> Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add CSS parts - add {{version}} to element classes **Tests** - e2e tests with page object model **Docs** - rearrange docs urls - fix demo - update inline docs - refactor docs page - add changeset - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - fix demo - inline docs - refactor docs page - add changeset - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add CSS parts - add {{version}} to element classes **Tests** - e2e tests with page object model **Docs** - rearrange docs urls - inline docs - refactor docs page - add changeset - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - support multiple nested scroll containers - migrate events to ComposedEvent - changed event names/types for change, stuck & content-change. Updated tests - add CSS parts **Fixes** - enable offset to be set to zero - accent-bar mixin wasn't setting proper width - remove duplicate background-color property. - prevent uncaught error - declare Breakpoints interface locally - add {{version}} to element classes - rename `pfeEvent` to `deprecatedCustomEvent` - type of ActiveItemEvent param - align styles to match red hat designs **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - doc updates and fixes (#1829) - update docs - update demo file - remove old demo sticky nav - remove old demo panel offset - rearrange docs urls - if there are no links and autobuild is unset - inline docs - rewrite docs page - add changeset - use pfe-styles Co-Authored-By: Michael Potter <mgp140@gmail.com> Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com> Co-Authored-By: Daniel Faucette <dfaucett@redhat.com>

**Features** - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot - rename element instance in tests - pfeAccordion => element **Docs** - rearrange docs urls - inline docs - refactor docs page - add changeset - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Breaking Changes** - implement HTMLDialogElement interface. See changelog for more info **Features** - add CSS parts **Fixes** - compose UI events - rename `pfeEvent` to `deprecatedCustomEvent` - remove public has_ attrs - add {{version}} to element classes **Docs** - rearrange docs urls - inline docs - add changeset - use pfe-styles **Tests** - e2e tests with page object model - build demo with optional shadowroot **Refactorings** - handle side effects in lifecycle Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add {{version}} to element classes **Fixes** - remove `on` attr when context is null **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - inline docs - refactor docs page - add changeset - fix a11y bugs in demo - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add CSS part - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - inline docs - refactor docs page - add changeset - Move header and options select inside pfe-band - improve demo - use pfe-styles Co-Authored-By: Em Nouveau <Nouveau@users.noreply.github.com> Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add CSS parts **Fixes** - bad aria-expanded attribute - Was being set to an ID, should be true or false - Inline attribute in template markup was producing odd results, moved to ye ole fashioned JS - compose UI events - rename `pfeEvent` to `deprecatedCustomEvent` - simplify back button text and remove unused functions - Removed aria attributes from element surrounding text, only need htose on the button wrapper - Set back button text to property so we aren't reading the DOM during render (? seems like the that's recommended) - Removed unused functions made during original development, but are now unused - Updated Demo HTML, thought text in 'details' was a bug in functionality, but was content in the slot. Hopefully the slight adjustment makes that more clear. - null checks - catch errors in render cycle - add {{version}} to element classes - fix animations, move breakpoint prop to private - remove scss causing extra border - refactor primary-detail **Tests** - update snapshot - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - refactor demo - inline docs - add changeset - use pfe-styles Co-Authored-By: Wes Ruvalcaba <wesruv@gmail.com> Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - allow text fallback - add {{version}} to element classes **Tests** - e2e tests with page object model **Docs** - fix demo - inline docs - refactor docs page - add changeset - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add CSS parts - add {{version}} to element classes **Fixes** - remove erroneous count property (#1822) - remove `has_` attrs **Docs** - added pfe-progress-steps-item slots to docs (#1825) - fix demo - inline docs - refactor docs page - add changeset - update inline docs - use pfe-styles - update slot definitions for docs (#1823) **Tests** - e2e tests with page object model Co-authored-by: Michael Potter <mgp140@gmail.com> Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Breaking Changes** - make readtime prop readonly **Features** - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - fix demo - inline docs - refactor docs page - add changeset - use pfe-styles Co-authored-by: Michael Potter <mgp140@gmail.com> Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add `value` property **Fixes** - compose UI events - rename `pfeEvent` to `deprecatedCustomEvent` - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - inline docs - refactor docs page - add changeset - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add CSS parts **Fixes** - add {{version}} to element classes - rename `pfeEvent` to `deprecatedCustomEvent` **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - add CSS to demo page for tabs (#1835) - rearrange docs urls - inline docs - refactor docs page - add changeset - use pfe-styles Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

**Features** - add CSS parts - add static `toast(text)` method - allows users to create an ephemeral toast via JS **Fixes** - compose UI events - rename `pfeEvent` to `deprecatedCustomEvent` - add {{version}} to element classes **Docs** - 2.0 [pfe-toast] update docs (#1826) - pfe-toast update docs - add .no-header-styles opt-out class for headers - rearrange docs urls - inline docs - refactor docs page - add changeset - use pfe-styles **Tests** - e2e tests with page object model - build demo with optional shadowroot Co-Authored-By: Michael Potter <mgp140@gmail.com> Co-Authored-By: Steven Spriggs <steven.spriggs@gmail.com>

github-actions bot added work in progress POC / Not ready for review AT passed Automated testing has passed demo Updating demo pages docs Documentation updates styles An issue or PR pertaining only to CSS/Sass tests Related to testing labels Oct 25, 2021

github-actions bot added this to In progress in Workflow Oct 25, 2021

github-actions bot added functionality Functionality, typically pertaining to the JavaScript. tools Development and build tools labels Oct 25, 2021

bennypowers mentioned this pull request Oct 26, 2021

fix: enable dart-sass compilation patternfly/patternfly#4474

Closed

github-actions bot added the generator Updates relating to the generator label Oct 27, 2021

bennypowers mentioned this pull request Oct 28, 2021

feat: adds custom event for clear search event, adds an aria label for search button (when applicable), and resolves dupe "x" with input[type="search"] #1796

Merged

18 tasks

bennypowers force-pushed the feat/pfe-tools branch from 3dc5f2a to 76c306c Compare October 31, 2021 18:29

github-actions bot removed the generator Updates relating to the generator label Oct 31, 2021

bennypowers force-pushed the feat/pfe-tools branch 15 times, most recently from d898827 to 0243f5a Compare November 5, 2021 13:02

bennypowers and others added 25 commits February 23, 2022 11:15

feat(badge)!: migrate pfe-badge to lit

9b08f46

**Fixes** - add {{version}} to element classes **Tests** - e2e tests with page object model - build demo with optional shadowroot **Docs** - rearrange docs urls - inline docs - refactor docs page - add changeset

bennypowers force-pushed the feat/pfe-tools branch from 7502dd5 to 6d9e592 Compare February 23, 2022 16:15

bennypowers merged commit ff5adfb into master Feb 23, 2022

Workflow automation moved this from Ready: code & design review to Done Feb 23, 2022

bennypowers deleted the feat/pfe-tools branch February 23, 2022 16:28

bennypowers mentioned this pull request Feb 25, 2022

fix: consolidate hexToRgb functions in tests #1802

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

⚡ PatternFly Elements 2.0: Lit, TypeScript, pfe-tools, and more #1804

⚡ PatternFly Elements 2.0: Lit, TypeScript, pfe-tools, and more #1804

bennypowers commented Oct 25, 2021 •

edited

Loading

bennypowers commented Oct 31, 2021

⚡ PatternFly Elements 2.0: Lit, TypeScript, pfe-tools, and more #1804

⚡ PatternFly Elements 2.0: Lit, TypeScript, pfe-tools, and more #1804

Conversation

bennypowers commented Oct 25, 2021 • edited Loading

🔥 🐵 Migrate to Lit ⚡ 🚧

Sticky Notes

What has changed and why

Adopt TypeScript

Adopt Custom Elements Manifest

Removed PFElement base class and package in favour of LitElement

Rename slots and events

Rename events and deprecate CustomEvent

Adopt a 'buildless' development workflow

Adopt Playwright for E2E and visual regression tests

Update to dart-sass

Rewrite the element generator

Add @patternfly/pfe-tools

Add Linting Rules

Remove <pfe-navigation>

Add Lighthouse Testing in CI

Commitlint Reporting

Testing instructions

Review Work Assignments

Core

Elements

Ready-for-merge Checklist

Related issues

Preview

Merging

bennypowers commented Oct 31, 2021

bennypowers commented Oct 25, 2021 •

edited

Loading

Removed `PFElement` base class and package in favour of `LitElement`

Rename events and deprecate `CustomEvent`

Update to `dart-sass`

Add `@patternfly/pfe-tools`

Remove `<pfe-navigation>`