feat: add Comparison Table (v0) [WIP]

[ernst-dev]

Description

[WIP] First-cut (v0) of a Comparison Table component — tracking AWSUI-59913.

⚠️ This is an intentionally-scoped v0 / work-in-progress for an epic-sized effort. It is additive and opt-in and is not a finished feature. It exists to establish a coherent, buildable foundation and to gather early design/API feedback. Do not merge as-is.

Comparison Table lets customers compare two or more entities (resources) side-by-side: attributes are rendered as rows, entities as columns, with a sticky attribute column and optional highlight-differences. The requesting teams on the ticket are Amazon RDS (already using a bespoke version), Redshift, and DynamoDB.

Approach

Rather than reimplement a data grid, v0 is a thin, opt-in composition over the existing Table component (via InternalTable), so it inherits Table's rendering, sticky-column, and accessibility machinery. The public component transforms attributes + entities into Table columnDefinitions/items:

• Column 0 = the attribute label column, marked isRowHeader and pinned via stickyColumns={{ first: 1 }}.
• One column per entity; each cell resolves entity.data[attribute.id] (or a per-attribute render).
• highlightDifferences compares raw per-entity values (Object.is) and emphasizes cells in rows that are not identical across all entities.

What's done in this v0 ✅

• New public component ComparisonTable (src/comparison-table/): index.tsx, internal.tsx, interfaces.ts, styles.scss.
• Public interface ComparisonTableProps with full JSDoc — attributes, entities, attributeColumnHeader, stickyAttributeColumn (default true), highlightDifferences (default false), variant, ariaLabel, plus Attribute / Entity sub-interfaces.
• Core rendering: attributes-as-rows × entities-as-columns, sticky attribute column, optional highlight-differences, custom per-attribute render, empty-state safe.
• test-utils DOM wrapper (findComparisonTable / findAllComparisonTables, findAttributeLabels, findHighlightedCells, findRows).
• Dev page: pages/comparison-table/simple.page.tsx (toggles for highlight + sticky, plus an empty-state example).
• 8 unit tests covering find-ability, rows-per-attribute, header count, sticky labels, highlight on/off, custom render, empty state.
• Registered required-props entry and plural form; documenter snapshot regenerated for the new public API (purely additive, +203 lines).

Remaining work / follow-ups 🚧 (out of scope for this v0)

• Design sign-off: run the full Cloudscape component process (research → scope → API proposal → design iteration/validation) against the reference design on the ticket. API is provisional.
• Row-level highlight: current highlight styles the differing cells; move to a first-class row-level treatment and a11y annotation (needs a Table row-className/decoration hook — currently not a public Table capability).
• Deep value comparison: highlightDifferences uses Object.is on raw values; add a configurable comparator for objects/ReactNode.
• Accessibility pass: manual SR/keyboard testing, row-header semantics review, ariaLabels coverage beyond tableLabel, RTL check.
• Selectors test-utils wrapper (only DOM wrapper added so far), integration/a11y tests, and visual/permutation screenshot coverage.
• Documentation: usage guidelines (do/don't), examples, and website/Contentful content.
• API breadth: sorting/pinning entity columns, wrapping/vertical-align options, loading/empty slots, i18n, analytics metadata, and whether this should ship as a distinct component vs. a documented Table pattern.
• Design tokens/visual polish for the highlight treatment.

Related links, issue #, if available: AWSUI-59913 (Cloudscape contribution request: Comparison Table)

Ticket-mismatch note: AWSUI-59913 resolved correctly to the Comparison Table contribution request (not an unrelated/Aperture ticket), so implementation follows both the ticket and the task description. Medic metadata lookup returned "Ticket Not Found" for the SIM-T backend, which is expected for a Taskei feature-request ticket.

How has this been tested?

Local, Node v24.15.0:

• eslint (touched files) — pass; stylelint (scss) — pass.
• gulp quick-build — pass.
• Unit tests: src/comparison-table — 8/8 pass.
• Repo-wide consistency suites (src/__tests__/functional-tests, which iterate every component incl. the new one: base-props, ssr, use-base-component, use-telemetry, naming-convention, outer-form-submit, test-utils) — 1843/1843 pass.
• Full gulp build (incl. static dev-pages compile) — pass.
• Documenter snapshot (src/__tests__/snapshot-tests/documenter.test.ts) regenerated and re-verified — 98/98 pass.

Reviewers can explore the component via the dev page comparison-table/simple after npm run quick-build + npm start.

Review checklist

The following items are to be evaluated by the author(s) and the reviewer(s).

Correctness

• Changes include appropriate documentation updates. — WIP: usage docs are a follow-up.
• Changes are backward-compatible if not indicated. — Yes: purely additive/opt-in, no existing API changed.
• Changes do not include unsupported browser features. — Yes (reuses Table only).
• Changes were manually tested for accessibility. — WIP: dedicated a11y pass is a follow-up.

Security

• If the code handles URLs: all URLs are validated through checkSafeUrl. — N/A (no URL handling).

Testing

• Changes are covered with new/existing unit tests? — Yes (8 new unit tests + all consistency suites).
• Changes are covered with new/existing integration tests? — WIP: integration/visual tests are a follow-up.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.