Consumer Products UI Kit

Angular shared components library

This repository consists of two projects:

• cps-ui-kit - shared components library itself
• composition - application for previewing compositions of components consumed from the library

Available components

• Autocomplete
• Button
• Button toggles
• Checkbox
• Chip
• Datepicker
• Dialog
• Divider
• Expansion panel
• File upload
• Icon
• Info circle
• Input
• Loader
• Menu
• Notifications
• Paginator
• Progress circular (indeterminate)
• Progress linear (indeterminate)
• Radio
• Scheduler
• Select
• Sidebar menu
• Switch
• Table
• Tabs
• Tag
• Textarea
• Timepicker
• Tooltip directive
• Tree autocomplete
• Tree select
• Tree table

Development server

Run ng build cps-ui-kit --watch and ng serve for a dev server. Navigate to http://localhost:4200/. The application will automatically reload if you change any of the source files.

Design guidelines

https://www.figma.com/file/JAlfp4zwZIONMWYPbLY4aM/Consumer-products-design-system?node-id=0%3A1&t=qVkCtHGgnZSpAYVp-1

How-to

Create a new component

• go to projects/cps-ui-kit/src/lib/components directory
• run: ng g c cps-componentname --standalone --prefix
• modify projects/cps-ui-kit/src/public-api.ts to export the component from the library
• update available components list in projects/cps-ui-kit/README.md (keep alphabetical order!)

Make sure ng build cps-ui-kit --watch is running, so the library will be rebuilt on each change of its contents due to --watch flag

Create a composition page

• go to projects/composition/src/app/pages directory
• run: ng g c componentname-page --standalone
• there is no need to test composition pages, so manually delete componentname-page.component.cy.ts file (can't be done automatically with Angular CLI flag, since cypress is used)
• provide host: { class: 'composition-page' } into page @Component
• import the components for the composition page from cps-ui-kit, provide them to imports array of @Component
• include ComponentDocsViewerComponent into @Component imports array in case of a new component page, include ServiceDocsViewerComponent into @Component imports array in case of a new service page
• import ComponentData or ServiceData from '../../api-data/cps-componentname.json' once it is generated
• wrap page html template contents into <app-component-docs-viewer [componentData]="componentData">...</app-component-docs-viewer> in case of a new component page, wrap page html template contents into <app-service-docs-viewer [serviceData]="serviceData">...</app-service-docs-viewer> in case of a new service page
• go to projects/composition/src/app/components/navigation-sidebar.component.ts file and extend _components array (keep alphabetical order!)
• go to projects/composition/src/app/app-routing.module.ts and add a new route for a new page
• update available components list in /README.md (keep alphabetical order!)

Generate API documentation

Execute npm run generate-json-api to generate documentation for any changes in the components' API.

Run Jest unit tests

npm run test

Run Playwright e2e tests

npm run test:playwright (headless run)

npm run test:playwright:headed to run tests in headed mode (browser visible)

npm run test:playwright:interactive to open Playwright UI mode

See playwright/README.md for full details.

Commit / PR title convention

Versioning and the changelog are driven by Conventional Commits. Because PRs are squash-merged, the PR title becomes the single commit on master, so the PR title is what must follow the convention (enforced by the Check PR Title workflow):

<type>(<scope>): <subject>

Type determines the version bump and changelog section:

Type	Bump	Changelog
feat	minor	Features
fix	patch	Bug Fixes
perf	patch	Performance Improvements
feat! / fix! / BREAKING CHANGE: footer	major	Breaking section
docs, style, refactor, test, build, ci, chore	none	hidden

Scope (optional) is the component the change targets, written as the component name without the cps- prefix. It only affects how the entry is grouped/labelled in the changelog (this is a single package, so the scope does not change versioning). Use the component name from the list above:

feat(chip): add dismissible variant
fix(scheduler): correct keyboard navigation in month view
fix(tree-table): resolve a11y issue with row focus

Omit the scope for cross-cutting changes that don't map to a single component (theming, shared utilities, build, repo-wide a11y sweeps):

chore: bump X package to v1.2.3

There is intentionally no fixed list of allowed scopes: scope is free-form so new components don't require a CI change. Keep names consistent with the component directory (minus cps-).

Versioning and publishing

Publishing is fully automated by Release Please. You never edit the version in package.json by hand.

1. Merge feature/fix PRs to master as usual (squash merge, conventional title).
2. Release Please keeps an open "release" PR up to date, accumulating the next version bump and the generated CHANGELOG.md from the merged commits.
3. When you're ready to ship, merge the release PR. That tags the release and triggers the publish job, which builds and publishes to NPM via trusted publishing (OIDC), with no NPM token required.

The current released version is tracked in .release-please-manifest.json; Release Please updates both it and projects/cps-ui-kit/package.json inside the release PR.

Run accessibility tests

The project uses pa11y-ci to test all components for WCAG 2.0 AA compliance.

To run accessibility tests:

1. Start the development server:

   npm run start

2. In a separate terminal, run the accessibility tests:

   npm run test:a11y

Alternatively, use the combined script that starts the server and runs tests:

npm run test:a11y:local

For a colorful summary with statistics:

npm run test:a11y:summary

This will display:

• Total URLs tested with pass/fail ratio
• Total accessibility errors found
• Accessibility standard (WCAG 2.0 AA)
• Test engine (axe-core via pa11y-ci)
• Top 10 components with the most issues

The tests will check all 33 components for accessibility issues and report any violations found.