feat(table): s2 table migration layout part-1 #3799

marissahuysentruyt · 2025-05-20T21:16:49Z

Description

This PR is part 1 of the table's migration to S2! Table has been updated to include:

new layout tokens (in the table Figma token specs, only tokens for Layout have been addressed)
new stories to demonstrate support, including a numerical data table showcasing proper text alignment, and row/cell states
removal of the table t-shirt sizes
the removal of the dropzone table stories on the docs pages (those are still in the code, but have been tagged !autodocs)
inclusion of new visual elements to support avatars and icons, as well as thumbnails
new empty and loading state tables
CSS reorganization to match the patterns of other components, which includes organizing all custom properties towards the top of the file, putting the forced-colors query at the bottom of the file, consolidating repetitive styles/selectors
minimal style updates to address new table styles, like a new row focus indicator, a cell focus indicator, new borders around header cells

NOTE: Tokens for color and typography, variant support for sparklines, and any remaining touch ups (like selected hover/down states) will be done in part 2 of the table migration here: #3818

All styles for the full migration will not be addressed in this PR. Layout changes only!

Jira/Specs

CSS-1178
Figma token specs- layout token column only
CSS-1180- this is a corresponding spike ticket. I used the answers to the questions in that ticket to inform some of my decisions around not exposing certain stories.

How and where has this been tested?

Please tag yourself on the tests you've marked complete to confirm the tests have been run by someone other than the author.

Validation steps

Please review the following table layout-specific styles to ensure the tokens are used as outlined in the tokens spec Figma file:

Additional validation

Proofread the documentation. There's been additions that need to be reviewed for grammar and to make sure they make sense.
Make sure all tables that cannot be created in the controls are listed in the side nav.
The testing grid covers all of the stories in some form or another. We also want to include the various focus indicators for rows and cells, along with selected vs highlighted rows, etc.
Double check that the fullscreen dialog looks acceptable still 👍
Double check the the WHCM mode at least matches what we see on production.

Regression testing

Validate:

The documentation pages for at least two other components are still loading, including:

The pages render correctly, are accessible, and are responsive.

If components have been modified, VRTs have been run on this branch:

VRTs have been run and looked at.
Any VRT changes have been accepted (by reviewer and/or PR author), or there are no changes.

Screenshots

To-do list

I have read the contribution guidelines.
I have updated relevant storybook stories and templates.
I have tested these changes in Windows High Contrast mode.
If my change impacts other components, I have tested to make sure they don't break.
If my change impacts documentation, I have updated the documentation accordingly.
✨ This pull request is ready to merge. ✨

github-actions · 2025-05-20T21:38:56Z

🚀 Deployed on https://pr-3799--spectrum-css.netlify.app

github-actions · 2025-05-20T21:51:20Z

File metrics

Summary

Total size: 1.40 MB^*

Package	Size	Minified	Gzipped
table	41.26 KB	39.38 KB	4.57 KB

table

Filename	Head	Minified	Gzipped	Compared to base
index.css	41.26 KB	39.38 KB	4.57 KB	🟢 ⬇ 5.83 KB
metadata.json	19.17 KB	-	-	🟢 ⬇ 2.75 KB

* Size is the sum of all main files for packages in the library.
* An ASCII character in UTF-8 is 8 bits or 1 byte.

changeset-bot · 2025-05-21T19:35:58Z

⚠️ No Changeset found

Latest commit: 4b76b0c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

- creates a TableCellTemplate - creates a TableRowTemplate - creates several helper functions like createCell, createRow - implements some new arguments, such as isSortable, support for more visual elements, different text alignments in the table cells, and the different sorting icons - adds numerical data handling (text alignment) - adds menu disclosure icon to table header cells

- uses new approach for creating table cells and rows (createRow()) - new args implemented like isSortable, visual elements, isLoading,etc. - new stories for sortable columns, selection modes (previously known as multi-select), empty state, loading - removes any dropzone stories from autodocs since design isn't certain the S2 table will support those. - adds numerical data alignment story - adds hasMenu story (disclosure icon)

- consolidates repetitive code - moves custom properties to top of file - moves high contrast styles to bottom of file

- removes createRow and createCell functions - reimplements ExampleRowItems - adjusts numerical data story to show text alignment - removes sort icon story - adds table row focus/selected states

- removes createRow and createCell functions - removes the TableCell and TableRow components - adds support for text alignment, selection and checkboxes, loading and empty states - reimplements sorting icons with new S2 icons in spec - attempts to re-simplify the template

- continues to reorganize custom properties - adds styles for headCells and icons

- clarifies some code comments - reorganizes code for focus styles - corrects border and border-radii for cells and rows based on new specs - fixes any scroll styling issues

- uses sentence-case for story names - updates to some display names and cell organization

- updates the thumbnail styles to "visual" to reflect the avatar, icon, and thumbnail support - minor changes to code comments for clarity - fixes vertical alignment for sort and disclosure/menu icons

- fixes the indentation for the isCollapsible block - removes columnIndex limit for visual elements - adds tabIndex to cells and rows to support keyboard navigation and design specs - adds -headRow class name for header rows - adds isFocused arg for rows

- reorganizes custom properties for section headers and summary rows into the rest of the custom properties - corrects some styles for section headers - adds some mods for summary rows and section headers - corrects some styling for checkboxes

- adds focus indicators for cells and rows - opts for a pseudo-element for the focus indicator instead of outline - adds cellCustomClasses to support focused cells - adds a TableStates story to show the focus and selected states

- addresses some unused or "undefined" custom properties related to thumbnail that are not in use anymore - updates metadata - passes density arg to table row template to appropriately size the visuals

marissahuysentruyt · 2025-05-22T18:08:54Z

components/table/stories/table.stories.js

+Visuals.storyName = "With visuals";
+
+
+// TODO: The design team doesn't have support for collapsible rows in the table component, so they are removed from the docs page for now.


I have a couple TODO notes throughout the stories file here, reflecting on the conversation I had with Stefan.

Design doesn't have collapsible row designs, or dropzone designs done (and they're unsure if they will). React only has beta drag & drop table components.

So I didn't really want to get rid of our stories or tests for those table variants/options. What are our thoughts on just removing these 5 or 6 stories regarding collapsible rows and dropzones from the autodocs?

marissahuysentruyt · 2025-05-22T18:18:53Z

components/table/stories/table.stories.js

-Sizing.args = {};
-Sizing.tags = ["!dev"];
-Sizing.parameters = {
+export const EmptyState = Template.bind({});


I'd love some feedback on the empty and loading states. Should I do anything more than return the illustrated message or progress circle component? As in, do I return the header row, AND THEN render the illustrated message/progress circle, with those 2 components like "in" the table? That's not really what Figma looks like, but...open to feedback on these two new stories.

marissahuysentruyt · 2025-05-22T18:20:58Z

components/table/stories/template.js

 	>
 		${when(showCheckbox && !isSectionHeader, () => html`
 			<${cellTag}
 				role="gridcell"
 				class=${classMap({
 					[`${rootClass}-cell`]: true,
 					[`${rootClass}-checkboxCell`]: true,
+					[`${rootClass}-cell--alignEnd`]: getTextAlignment(0) === "end",
+					...cellCustomClasses?.[0]?.reduce((a, c) => ({ ...a, [c]: true }), {}),


I wanted to show the individual cell focus states, so I had to pass custom classes to the cells.

marissahuysentruyt · 2025-05-22T18:23:01Z

components/table/stories/template.js

 				})}
+				tabindex="0"


The rows should be keyboard focusable, as well as the cells (according to the designs), so I added the tabindex in quite a few places.

Any accessibility concerns with how everything is laid out right now? I don't know the flow for tables. Should each focused row move to the next focusable row, or would a user focus on a row, then move through the cells?

marissahuysentruyt · 2025-05-22T18:28:29Z

components/table/stories/table.stories.js

 */
-export const Sizing = (args, context) => Sizes({


Doesn't look like we ever really supported sizes actually. The guidance site doesn't refer to table sizes, nor do the current Figma designs for S2 🤷‍♀️

- fixes up existing tests to use new default props if necessary - adds numerical test, text alignment, visual elements, empty state, loading state, and a test of a smattering of other focus/selected tests for the rows and cells

the indeterminate checkbox for a multi-select table should only show in the header row. Single select tables should not have a checkbox in the header row.

marissahuysentruyt · 2025-05-22T18:45:55Z

components/table/stories/template.js

@@ -204,65 +285,75 @@ export const Template = ({
 		id=${ifDefined(id)}
 		role=${ifDefined(useCheckboxCell ? "grid" : useDivs ? "table" : undefined)}
 		aria-multiselectable=${ifDefined(useCheckboxCell ? "true" : undefined)}
-		style="max-width: 800px;"


Should I keep this? Is it necessary? I'm fine with adding this max-width back on, just let me know!

marissahuysentruyt · 2025-05-22T18:47:13Z

components/table/stories/template.js

-							isChecked: false,
-							isIndeterminate: true,
-							customClasses: [`${rootClass}-checkbox`],
+						${when(selectionMode === "multiple", () => html`


Checkboxes should only appear in the thead if users can select more than one row (and this puts the indeterminate checkbox in that header row). Otherwise, checkboxes for single select rows just appear in their rows.

marissahuysentruyt · 2025-05-22T18:47:46Z

components/table/stories/template.js

+					tabindex="0"
+				>
+					${Icon({
+						iconName: "Sort",


I added each of the new sort icons to each header cell.

marissahuysentruyt · 2025-05-22T18:49:13Z

components/table/stories/template.js

+						customClasses: [`${rootClass}-sortIcon`],
+					}, context)}
+					<span class="${rootClass}-columnTitle">Column title</span>
+					${Icon({


The second column now has the additional "menu" or disclosure icon. It's non functional but...should this be a button? Like an action button to trigger a menu?

The rest of the collapsible disclosure icons are all buttons so...that's what trigger the question for me.

marissahuysentruyt · 2025-05-22T18:50:47Z

components/table/stories/table.stories.js

-			description:
-				"Uses the thumbnail component at the start of the first column's cells.",
-			type: { name: "boolean" },
+		selectionMode: {


I got "selection mode" from the menu component, as well as React.

marissahuysentruyt · 2025-05-22T18:53:55Z

components/table/stories/table.stories.js


+export const LoadingState = Template.bind({});


What else can I say here? 😆 Any thoughts?

"The table may render a progress circle while populating data."

marissahuysentruyt · 2025-05-22T18:55:28Z

components/table/index.css

@@ -12,511 +12,348 @@
 */

 .spectrum-Table {


A lot of the CSS has just been reorganized to more or less match what we are doing in other components. There was a lot of consolidating of the custom properties up at the top that needed to happen.

marissahuysentruyt · 2025-05-22T18:59:48Z

components/table/index.css

 .spectrum-Table-body {
 	position: relative;
 	border: none;
-	border-radius: var(--mod-table-border-radius, var(--spectrum-table-border-radius));
+	border-end-start-radius: calc(var(--mod-table-border-radius, var(--spectrum-table-border-radius)) - var(--mod-table-border-width, var(--spectrum-table-border-width)));
+	border-end-end-radius: calc(var(--mod-table-border-radius, var(--spectrum-table-border-radius)) - var(--mod-table-border-width, var(--spectrum-table-border-width)));
 	display: table-row-group;

 	&.is-drop-target {


I'm curious if anybody has ideas on the body drop zone. Right now, I get little cell borders that interrupt the body outline.

marissahuysentruyt · 2025-05-22T19:01:09Z

components/table/index.css

+		&::after {
+			content: "";
+			position: absolute;
+			inset: calc(-1 * var(--mod-table-border-width, var(--spectrum-table-border-width)));
+			border-radius: calc(var(--mod-table-border-radius, var(--spectrum-table-border-radius)) - var(--mod-table-border-width, var(--spectrum-table-border-width)));
+			border: var(--mod-table-focus-indicator-thickness, var(--spectrum-table-focus-indicator-thickness)) solid var(--highcontrast-table-cell-focus-indicator-color, var(--highcontrast-table-focus-indicator-color, var(--mod-table-focus-indicator-color, var(--spectrum-table-focus-indicator-color))));
+			pointer-events: none;
+		}


The cells have a different focus indicator border radius, than they do when non-focused. I'd love some feedback on this ::after approach to achieve that.

marissahuysentruyt · 2025-05-22T19:03:35Z

components/table/index.css

-		--highcontrast-table-icon-color: var(--highcontrast-table-row-text-color-hover);
-		--spectrum-table-cell-background-color: var(--highcontrast-table-row-background-color-hover, var(--mod-table-row-active-color, var(--spectrum-table-row-active-color)));
-	}
+		/* First cell of focused rows need fancy new focus indicator borders & no border-radius, and the thicker row focus indicator */


This was pretty complex, so again- feedback is welcome!

The table row itself can be focused.
It's got a 4px blue side focus indicator, as well as (basically) a border that goes around the entire row.
Some rows don't have border radii, and some do. But- those border radii are created with the individual table cells in that row.

🥵🥵🥵

marissahuysentruyt · 2025-05-22T19:10:31Z

components/table/index.css

-		padding-block-start: calc(var(--mod-table-row-top-to-text, var(--spectrum-table-row-top-to-text)) - var(--mod-table-border-width, var(--spectrum-table-border-width)));
-		padding-block-end: var(--mod-table-row-bottom-to-text, var(--spectrum-table-row-bottom-to-text));
-	}
+	align-items: center;


Calling all feedback again!

The guidance says: "All content should be centered vertically within the row to offer the right visual balance." That's why I added the align-items: center, ripped out all of the custom padding, and centered everything everywhere else. That does however, prove difficult in collapsible rows for a number of reasons:

the button component (with the disclosure icon) is just tall, so the padding around the cells beefs the height up.

it's really weird to have a cell with wrapped text where everything is aligned to the center

However....collapsible rows aren't quite designed out so we don't have any true guidance on how to handle any of that spacing. I removed them from the docs page (pending others' agreement/approval). Should I reimplement some of this padding and alignment handling since the collapsible table variants are still in the test grid? How would we like to handle this?

marissahuysentruyt · 2025-05-22T19:34:33Z

@marissahuysentruyt TODO: write changeset

marissahuysentruyt self-assigned this May 20, 2025

marissahuysentruyt added size-5 L ~30-42hrs; lots of effort or complexity, most of a sprint needed to complete. wip This is a work in progress, don't judge. skip_vrt Add to a PR to skip running VRT (but still pass the action) S2 Spectrum 2 labels May 20, 2025

marissahuysentruyt force-pushed the marissahuysentruyt/css-1178-s2-table-migration-layout-pt1 branch from 25578c0 to 8a6fb2f Compare May 21, 2025 19:35

marissahuysentruyt added 15 commits May 21, 2025 17:53

feat(table): adds new table styles

f987745

- consolidates repetitive code - moves custom properties to top of file - moves high contrast styles to bottom of file

refactor(table): revert table stories to previous approach

e4e3b38

- removes createRow and createCell functions - reimplements ExampleRowItems - adjusts numerical data story to show text alignment - removes sort icon story - adds table row focus/selected states

feat(table): add styles for headCells and icons

59f6406

- continues to reorganize custom properties - adds styles for headCells and icons

feat(table): styles for body/rows/cells borders/focus/dropzones

3b6fa63

- clarifies some code comments - reorganizes code for focus styles - corrects border and border-radii for cells and rows based on new specs - fixes any scroll styling issues

docs(table): updates to stories

9a2eb95

- uses sentence-case for story names - updates to some display names and cell organization

feat(table): updates visual styles

3ce2bf3

- updates the thumbnail styles to "visual" to reflect the avatar, icon, and thumbnail support - minor changes to code comments for clarity - fixes vertical alignment for sort and disclosure/menu icons

feat(table): vertically center all text in cells

6f950f5

docs(table): adds migrated badge

e7bcd48

feat(table): styles for focus indicators

61951e3

- adds focus indicators for cells and rows - opts for a pseudo-element for the focus indicator instead of outline - adds cellCustomClasses to support focused cells - adds a TableStates story to show the focus and selected states

chore(table): update metadata.js

ec2a311

marissahuysentruyt force-pushed the marissahuysentruyt/css-1178-s2-table-migration-layout-pt1 branch from dfd9619 to 36920dd Compare May 21, 2025 22:01

fix(table): linting errors fixed

490a4e9

- addresses some unused or "undefined" custom properties related to thumbnail that are not in use anymore - updates metadata - passes density arg to table row template to appropriately size the visuals

marissahuysentruyt force-pushed the marissahuysentruyt/css-1178-s2-table-migration-layout-pt1 branch from 36920dd to 490a4e9 Compare May 21, 2025 22:18

marissahuysentruyt added 2 commits May 22, 2025 13:54

docs(table): remove collapsible variants from autodocs

6d8138d

fix(table): adds extra block borders for row focus

af27018

marissahuysentruyt commented May 22, 2025

View reviewed changes

marissahuysentruyt added 3 commits May 22, 2025 14:40

chore(table): expands test coverage

1ffe361

- fixes up existing tests to use new default props if necessary - adds numerical test, text alignment, visual elements, empty state, loading state, and a test of a smattering of other focus/selected tests for the rows and cells

chore(table): checkboxes and multi select stories

ce034e5

the indeterminate checkbox for a multi-select table should only show in the header row. Single select tables should not have a checkbox in the header row.

docs(table): isEmphasized is true by default

4b76b0c

marissahuysentruyt force-pushed the marissahuysentruyt/css-1178-s2-table-migration-layout-pt1 branch from 14fcf31 to 4b76b0c Compare May 22, 2025 18:43

marissahuysentruyt commented May 22, 2025

View reviewed changes

marissahuysentruyt added ready-for-review and removed wip This is a work in progress, don't judge. labels May 22, 2025

marissahuysentruyt marked this pull request as ready for review May 22, 2025 19:12

		Visuals.storyName = "With visuals";


		// TODO: The design team doesn't have support for collapsible rows in the table component, so they are removed from the docs page for now.

feat(table): s2 table migration layout part-1 #3799

Are you sure you want to change the base?

feat(table): s2 table migration layout part-1 #3799

Uh oh!

Conversation

marissahuysentruyt commented May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Jira/Specs

How and where has this been tested?

Validation steps

Additional validation

Regression testing

Screenshots

To-do list

Uh oh!

github-actions bot commented May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

File metrics

Summary

table

Uh oh!

changeset-bot bot commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marissahuysentruyt commented May 22, 2025

Uh oh!

Uh oh!

marissahuysentruyt commented May 20, 2025 •

edited

Loading

github-actions bot commented May 20, 2025 •

edited

Loading

github-actions bot commented May 20, 2025 •

edited

Loading

changeset-bot bot commented May 21, 2025 •

edited

Loading