Skip to content

feat(beta): add BasicTable beta component (src/beta/basic-table-0.1) - #4868

Draft
gethinwebster wants to merge 12 commits into
mainfrom
dev-v3-gethinw-basic-table-beta
Draft

feat(beta): add BasicTable beta component (src/beta/basic-table-0.1)#4868
gethinwebster wants to merge 12 commits into
mainfrom
dev-v3-gethinw-basic-table-beta

Conversation

@gethinwebster

@gethinwebster gethinwebster commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Description

Introduces BasicTable as the first beta component, published at a versioned export path
@cloudscape-design/components/beta/basic-table-0.1. Because we publish via Brazil (no semver escape
hatch), the version lives in the directory/subpath: a breaking API change bumps the dir
(…-0.2) rather than the package version. This is the same escape-hatch idea used long ago for top
navigation, generalised here.

Moving BasicTable into the components repo (from a standalone package) lets it inherit the existing
build infrastructure out of the box — screenshot testing, multi-variant output, the documenter — and
lets us drop the shared code that had been duplicated into the toolkit.

Design decisions (feedback welcome — this establishes the beta convention):

  • Flat API. BasicTable (root) + BasicTableHeader/HeaderCell/Body/Row/Cell/ExpandedContent as
    flat named exports (not a BasicTable.Row compound namespace). Flat exports are individually
    tree-shakeable, each is a normal documentable component, and it matches every existing repo
    release/doc/test-utils convention.
  • Opt-in, not in the top-level barrel. Beta is reachable only via the explicit
    beta/basic-table-0.1 subpath; it is intentionally excluded from @cloudscape-design/components.
  • Per-component dirs under src/beta/basic-table-0.1/ so the documenter names each part from its
    dir basename (Variant A) — no documenter-package change needed.
  • No virtualization — bring your own. BasicTable is windowing-free and ships no virtualization
    primitive. To window a large/streaming dataset, a consumer brings their own virtualizer and spreads
    the offset/measure props onto Body/Row; totalRowCount keeps aria-rowcount/empty-detection
    correct for the un-rendered rows.
  • Uses repo internals. Toolkit imports re-pointed to @cloudscape-design/component-toolkit + repo
    originals (table/table-role, table/sticky-columns, internal/components/*,
    internal/base-component, internal/events, internal/utils/apply-display-name). The vendored
    internal/ and types/ folders are deleted entirely — nothing is duplicated from the toolkit or
    repo internals anymore.
  • Test-utils under root. The BasicTable wrapper lives at src/test-utils/dom/basic-table/ like
    every other component (not under beta/*), so it is generated + exported the standard way:
    createWrapper().findBasicTable() and the ./test-utils/dom/basic-table subpath both come for free.

Build-tools additions (all beta-scoped):

  • listBetaItems() enumerates src/beta/*; beta excluded from listPublicItems (kept out of the
    barrel) and from the documenter-snapshot getAllComponents.
  • package.json exports gains ./beta/basic-table-0.1. Test-utils are NOT a beta subpath — the
    wrapper lives in the root tree, so it's exported as ./test-utils/dom/basic-table and generated
    into the standard createWrapper() aggregate (added BasicTable to the test-utils pluralization map).

Tracked follow-ups (not in this PR):

  • Documenter for the beta parts. The per-component dirs + a beta documenter glob are wired but the
    pass is deferred (commented, with a TODO): the parts currently extends React.*HTMLAttributes, which
    the documenter can't serialise (ReactEventHandler<T>). Unblock by minimising the part interfaces to
    explicit, consumer-facing props — which also aligns with the repo's minimal-interface convention.
  • Integ / visual-regression pages.
  • Revert the shared code that was duplicated into AWS-UI-Component-Toolkit (separate CR), now that
    BasicTable uses the repo originals again.

How has this been tested?

Local gulp quick-build is green; the component compiles to lib/components/beta/basic-table-0.1/**
with correct subpath exports, and the top-level barrel excludes it. All 6 beta unit suites pass
(58/58) under the repo's jest config (run against lib, using the repo renderHook helper). The
documenter snapshot test passes (97), regenerated to include the BasicTable dom/selectors test-utils
definitions; stable components are otherwise unchanged and beta is excluded from getAllComponents.

Draft: functional/visual-regression e2e pages and the beta documenter pass are follow-ups (see above).

@gethinwebster
feat(beta): add BasicTable beta component under src/beta/basic-table-0.1
bc63f8c 
Moved from the standalone AWS-UI-Basic-Table-Components package. Flat API
(BasicTable + BasicTable* named exports). Toolkit imports re-pointed to the
OSS @cloudscape-design/component-toolkit + repo originals (table-role,
sticky-columns, drag-handle-wrapper, transition); vendored dupes deleted.
@gethinwebster
build(beta): enumerate versioned beta components + emit their subpath…
6fc3d5a 
… exports

listBetaItems() enumerates src/beta/* ; excluded 'beta' from listPublicItems so
it is not treated as a normal component (kept out of the top-level barrel).
package.json exports gains ./beta/<name> -> ./beta/<name>/index.js.
@gethinwebster
build(beta): per-component dirs for documenter + add beta documenter …
fdbd860 
…pass

Variant A: each flat BasicTable* part gets its own dir (basic-table-row, ...)
whose basename pascalCases to the component name, so the documenter names each
natively (no documenter-package change). docs.js gains a beta pass with glob
src/beta/*/*/index.tsx (verified via micromatch to match exactly the 7 component
dirs). Subpath entry re-exports the unchanged flat surface.
@gethinwebster
test(beta): WIP convert ported suites vitest->jest + compound->flat
c778e95 
Converts the 9 ported suites to jest globals and the flat BasicTable* API
(71/84 green in a source run). NOT wired to the repo's build-then-test-against-lib
model yet: the global css.js mapper was reverted, and the RTL12 renderHook import
+ test-utils-from-lib + test-utils-gen-for-beta remain. Pending test-model decision.
@gethinwebster
test(beta): run against lib + finish repo integration
d70f23a 
- beta tests import component/test-utils/styles from lib/components/beta/... and
  renderHook from the repo's src/__tests__/render-hook helper (RTL12 has none).
- re-point base-component + use-base-component to repo originals (drop vendored
  copies whose orphan styles.css.js side-effect broke the lib build).
- re-point styles.scss to repo internal/styles + tokens (drop vendored internal/styles).
- add beta test-utils/dom subpath export.
All 9 suites green (84/84) against lib via gulp quick-build.
@gethinwebster
build(beta): documenter-ready part wrappers + snapshot beta-exclusion
580da3f 
- part dirs are now documenter-recognized wrappers (function decls / forwardRef);
  root component dir is lean (BasicTable + BasicTableProps), hooks+shared types
  live on the beta entry.
- getAllComponents excludes 'beta' so the documenter snapshot governs stable
  components only (beta is opt-in/ungoverned).
- beta documenter pass deferred with a TODO: parts extend React.*HTMLAttributes
  which the documenter can't serialize (ReactEventHandler<T>); unblock by
  minimizing part interfaces (also aligns with the minimal-interface convention).
docs() OK, documenter snapshot green (97), beta unit 84/84, build green.
@gethinwebster
refactor(beta/basic-table): drop virtualization (BYO), remove vendore…
ed361e6 
…d internal/types, relocate test-utils to root

- Remove use-virtualization primitive + its 3 test suites; virtualization is now
  bring-your-own (consumer spreads offset/measure props onto Body/Row).
- Delete the vendored internal/ and types/ folders; re-point apply-display-name, events,
  and the base-component/event types to the repo originals (extends the toolkit-revert).
- Move test-utils from beta/basic-table-0.1/test-utils to src/test-utils/dom/basic-table so
  it is generated + exported like every other component (drops the beta test-utils subpath).
- Reword USAGE.md + interface/code comments to reflect BYO virtualization.
@gethinwebster
test-utils(beta/basic-table): wire generated wrapper into root test-u…
ddf2455 
…tils

- Add BasicTable to the test-utils pluralization map (findAllBasicTables).
- Make findRowByIndex use a nth-child selector so the generated selectors wrapper compiles.
- Regenerate documenter snapshot to include the BasicTable dom/selectors test-utils definitions.
@gethinwebster
feat(beta/basic-table): minimize part interfaces + enable beta docume…
ee50c0e 
…nter

Drop `React.*HTMLAttributes` from HeaderCell/Body/Row/Cell props in favour of an
explicit, minimal surface: className, style, and a `data-*` pass-through (so
3rd-party virtualization libraries — react-window, TanStack Virtual — can spread
their measurement hooks), plus `aria-sort` (sortable header) and `aria-rowindex`
(virtualized row-position override). This removes the event-handler grab-bag the
documenter cannot serialize and over-exposed the DOM.

Retype `Row.onToggleExpand` as a `NonCancelableEventHandler` (Cloudscape event
convention — the documenter rejects a bare `() => void` on an `on*` prop); the
internal row context keeps a plain thunk and Row fires the event.

Re-enable the beta documenter pass, writing definitions to a separate
`components-beta` folder so it does not clobber the stable `components` index
barrel (each pass rewrites the index from its own glob).

Verified: quick-build green; 6 beta suites / 58 tests pass against lib;
documenter snapshot test 97 pass (stable definitions unaffected); beta
definitions generate for all 7 components.
@gethinwebster
build(beta): export components-beta definitions subpath
12a3f7b 
Expose the beta api-docs barrel at @cloudscape-design/components-definitions/components-beta so the website's component-metadata definitions can source the beta components' definitions (the beta documenter pass writes here to avoid clobbering the stable components index).
@gethinwebster
build(beta): fold beta definitions into the components barrel (no sep…
75ada8e 
…arate barrel)

Per review, beta components must not ship as a separate definitions barrel. The
docs task now documents the stable components AND the versioned beta components
into the single `components` output via a combined glob, and post-stamps the 7
beta definitions with releaseStatus: 'beta' (the documenter hard-codes 'stable'
with no tag override). The website already derives isBeta from releaseStatus, so
beta components surface (beta header alert + nav badge) with no website
definitions wiring. Reverts the separate components-beta subpath export.

Verified: single components barrel = 95 stable + 7 beta; beta defs flagged 'beta';
documenter snapshot test 97 pass (stable unaffected).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@gethinwebster