Angular Carbon v12 Support

[tay1orjones]

@carbon/angular is the official Angular implementation of the Carbon Design System, wrapping @carbon/web-components custom elements with idiomatic Angular components. It replaces the community-maintained Carbon Components Angular (CCA) package with a first-party solution that ships inside the Carbon monorepo. This epic tracks all work required to reach a stable 1.0.0 release aligned with Carbon v12.

---

Why @carbon/angular?

Metric	CCA (previous)	@carbon/angular v1
Component count	~35	87
Module style	NgModule	Standalone (Angular 17+)
WC feature parity	Partial	Full
Theming API	Per-component theme input	CSS custom properties
Maintained in monorepo	No	Yes

The Angular layer owns only data binding, property reflection, and event normalisation. All behaviour is delegated to @carbon/web-components, giving @carbon/angular automatic feature parity with @carbon/react as the WC layer evolves.

---

Package Details

Field	Value
Monorepo location	packages/angular/
Package name	@carbon/angular
Selector prefix (public)	cds-*
WC tag prefix (internal)	cds-wc-*
Angular version	17+ (standalone APIs required)
Build tool	ng-packagr

---

Versioning Milestones

Phase	Version	Description
Prerelease	0.0.0-prerelease.N	Now through v12 RC; active development, no stability guarantees
Release Candidate	1.0.0-rc.0	API frozen, bug fixes only, community testing period
General Availability	1.0.0	Stable release, semver guarantees begin

---

Dependencies

Blocker: The feat/wc-class-exports branch in @carbon/web-components must be merged and released before any component can be built. This branch exposes named class exports that enable the defineCustomElement registration pattern used throughout this package.

Tracked at: carbon-design-system/carbon#22416

No component workstream items should be marked complete until this dependency is resolved.

---

Workstreams

Infrastructure & Scaffolding

• Bootstrap packages/angular/ directory in the monorepo
• Configure ng-packagr build pipeline and tsconfig targets
• Set up ESLint, Prettier, and commit lint rules scoped to the package
• Wire package into the root Turborepo/Nx task graph
• Publish dry-run CI job (npm pack + artifact upload)
• Establish Storybook instance for @carbon/angular within the monorepo

Pre-Implementation Test Sprint

• Write 100+ failing Jest/jsdom API boundary tests before any component code
• Define Playwright test harness and baseline fixture page
• Document test conventions and file naming standards for contributors
• Gate CI to require all pre-written tests to pass before PR merge

Tier 1 - Thin Wrappers

Thin wrappers: WC element owns all behaviour; Angular component reflects properties and normalises events only.

• Checkbox
• RadioButton
• Toggle
• Tag
• Loading
• InlineLoading
• Skeleton variants (SkeletonText, SkeletonPlaceholder, SkeletonIcon)
• Tooltip
• TextInput
• TextArea
• NumberInput

Tier 2 - Slot Materialisation

Components that project Angular content into named WC slots.

• Select
• Dropdown
• MultiSelect
• Breadcrumb
• Notification (inline, toast, actionable variants)
• Pagination

Tier 3 - Non-Trivial Adapters

Components requiring non-trivial lifecycle coordination between Angular and WC.

• Tabs
• Accordion
• ComboBox
• Modal
• FileUploader

Tier 4 - DataTable

• DataTable core (sort, filter, selection)
• Remove DataTableModel class dependency (see Breaking Changes)
• Toolbar integration
• Batch actions

Tier 5 - Pure Angular

Components with no WC counterpart; implemented entirely in Angular.

• Stepper
• StructuredList

Testing

• Layer 2: Playwright real-browser WC lifecycle tests for all Tier 1-3 components
• Layer 3: Storybook IBM Equal Access a11y audit for all components
• Achieve zero a11y violations baseline before RC

Documentation & Release

• Write migration guide from CCA (see Breaking Changes section)
• Populate CHANGELOG.md with all prerelease changes
• Update monorepo root README.md to reference @carbon/angular
• Publish 1.0.0-rc.0 to npm
• Address RC feedback and publish 1.0.0

---

Test Strategy

Layer	Tool	Scope
1 - Unit	Jest + jsdom	API boundary: inputs, outputs, property reflection
2 - Integration	Playwright	Real-browser WC lifecycle, slot hydration, event bubbling
3 - Accessibility	Storybook + IBM Equal Access	a11y audit across all component stories

TDD approach: The Pre-Implementation Test Sprint writes all Layer 1 and Layer 2 tests before any component code is written. Green tests are the definition of done for each component.

---

Key Technical Decisions

Decision	Choice	Rationale
Build tool	ng-packagr	Required for correct Angular package format (APF); tsdown does not produce the FESM/UMD bundles Angular tooling expects
Module style	Standalone components	Angular 17+ default; removes NgModule boilerplate and enables tree-shaking at the component level
Internal WC tag prefix	cds-wc-*	Prevents collisions with externally registered cds-* elements in the consumer's document
WC registration pattern	defineCustomElement(CDSModal, { name: 'cds-wc-modal' })	Scoped registration without polluting the global custom element registry via es-custom side-effects
CUSTOM_ELEMENTS_SCHEMA	Scoped per component module	Avoids suppressing Angular template errors globally; each component opts in explicitly
es-custom barrel	Not used	Registration is explicit and lazy; no silent global side-effects on import

---

Intentional Breaking Changes from CCA

#	Area	CCA behaviour	@carbon/angular v1 behaviour
1	DatePicker value type	Date object	string (ISO 8601)
2	DatePicker onChange event shape	{ date: Date }	{ selectedDates: string[], value: string }
3	Composition model	Array input API	Projected children via ng-content slots
4	Module imports	NgModule (e.g. CarbonModule)	Standalone component imports
5	Theming	Per-component theme input	CSS custom properties on host element
6	flatpickr integration	Exposed as input	Dropped; WC layer manages date picker internally
7	Pagination event shape	{ page, pageSize } object	CustomEvent detail mirroring WC spec
8	Tabs / Accordion item API	Declarative array of config objects	Projected <cds-tab> / <cds-accordion-item> children
9	DataTableModel class	Required for all DataTable usage	Dropped; pass plain data arrays directly

---

Out of Scope for v1

• ng add schematics / ng generate blueprints
• i18n / locale support beyond what the WC layer provides
• Server-Side Rendering (SSR) / Angular Universal support
• DataTable virtual scroll
• TimePicker component

---

Open Questions

1. DatePicker onChange type: Should the emitted value be string[] (always an array, consistent with range mode) or string (scalar for single-date mode, array for range)? Decision needed before Tier 3 work begins.

2. Storybook Compodoc integration: Should the Storybook instance generate API docs via Compodoc, or rely on Storybook's built-in ArgTypes inference? Compodoc gives richer output but adds a build step.

3. Secondary entry points: Should @carbon/angular expose secondary entry points (e.g. @carbon/angular/modal) to enable finer-grained tree-shaking, or ship a single flat entry point for v1 simplicity?

---

Related

• carbon#22416 - feat/wc-class-exports branch tracking (blocker): Provide pure class exports for web components carbon#22416
• carbon#22411 - Related upstream WC work: Establish Motion Standards carbon#22411