Composable Tearsheet ☂️

[oliviaflory]

We want to make Tearsheet more composable and allow for the option to move it into the Carbon core repo.

Carbon for IBM Products

• There are two variants of Tearsheet
  • Tearsheet (wide)
  • Tearsheet narrow
  • Website
• A number of components and/or patterns in Carbon for IBM Products have dependencies on Tearsheet
  • Create flows
  • Edit and update *in preview/experimental

Carbon

• What changes need to be made to move Tearsheet into core, what are the options
  • Consult with Kenny (Tearsheet as dialogue)
• What level of effort would our adopters face if Tearsheet is moved into core
• Feature flags?

Checklist of features / common elements

Elements

• Header
  • Label
  • Title
  • Description
  • Action items
    • Dropdown
    • Buttons
• Influencer
  • right and left
    • different visually
    • Add and select uses a similar right influencer
    • Are they providing different use cases?
    • Would you ever allow for BOTH right and left
  • Influencer width
• Action bar / footer
  • Two, three or four buttons, NO buttons
  • Button height (current 64 and 80) I've seen requests for smaller
  • Requests for more flexibility
• Layering
  • Tearsheet may not follow v11 layering fully

Elements specific to Create tearsheet

• Divider
• something else

Functionality

• Stacking
  • Open another tearsheet on top of the existing one
  • Remove stacking??
  • Read docs on stacking
  • Research how people are using stacking
• Stepping: click on the next button and takes you to next step
  • Ideally works within the existing tearsheet: this does exist in Create
• Always pinned to bottom
  • I've seen requests for not pinned to the bottom
• Breakpoints

Design explorations

• Reach out to teams about stacking usage
• Tearsheet design explo: Keyboard interactions
• Tearsheet design exploration: Responsiveness

Documentation/Guidance

• Write new Tearsheet v2 guidance

For documentation, reference Calendar usage guidance.

[kingtraceyj]

@RichKummer jan noticed a discrepancy for padding in tearsheet. there are a few differences:

Hey, we stumbled upon an inconsistency in the Tearsheet guidelines. In the Create flows guideline the wide CreateTearsheet has a 24px padding on the left and right of the main content. This is also how it’s implemented in code. On the other hand, the general, wide tearsheet guidelines specify that the padding should be 32px.
https://pages.github.ibm.com/carbon/ibm-products/patterns/create-flows/usage/#wide-tearsheet
https://pages.github.ibm.com/carbon/ibm-products/components/tearsheet/style/

Wondering if we should update the old one as well as incorporate it into the new one (or however we decided to update the component)

[RichKummer]

Carbon design crit 12/03/24

Truncation

• Overall, team preferred an option to expand or contract the description through "Read more" utility.
• Mike Gower: A read more mechanism is accessible for keyboard; the hover is not.
• Mike also wondered if we could have the description scroll up (similar to PageHeader as the user scrolls. We should try this in a prototype.

Close button

• Anna: I do agree the close button positioning shouldn't be conditional. It should probably always be in the same spot no matter what's around it.
• We should consider opening an issue for close button alignment across relevant components.
  • Cameron mentioned that the adoption teams had a bit of a rule to inset the close button when other buttons would align to it, and leave it flush when there are no other interactive elements nearby.

Documentation

• We should provide guidance on recommended character count for elements in the tearsheet. Specifically for the description.
• Teams often reach for tearsheet when a full page experience would make the overall flow less complex. We should add guidance that if the flow is complicated to consider starting the flow in a page rather than a tearsheet. Tearsheets are meant to be transient.
• Tracey: character limit gets a little tricky with internationalization but i also like the character count recommendation! i'm looking at that with page header right now too. we could have similar guidance here maybe.

Other

• Cameron noted that we should avoid making the title smaller in the tearsheet since we often design for 1312px size but the real world is different. The title can look small on larger screens.
• We should question where tearsheet ends up, whether in core or products team. If it goes to core, it should be less complex. If it lives in product, it might be more opinionated.
• Mike G: My naive gut feeling on tear sheet is that it's the Megamenu of our time
• Cameron: Tearsheets have their place, particularly when it's helpful to have a 'quick route' back. Psychologically, it helps the feel that you're still in the same spot within the product and the speed / immediacy of accessing a related view. Valuable for processes related to dedicated page (saving an artifact back to a project). Also valuable to bring in an ‘experience integration’ within your current view without having to navigate fully to that destination.
• Preference for horizontally aligning the header action with the AI slug and close button, over vertical alignment.
• For the main area of the tearsheet, the grid should apply to the area. For spacing consideration, need to be aware that cards could be placed in here and should align with the header content.

[RichKummer]

Slack notes on tabbing through Tearsheet

A user noticed a tabbing issue when moving through the teartsheet header where a content switcher they had placed in the description was skipped at first. If we enable a dedicated slot for components like this, it should ideally show up in the tab order. This behavior also happens with Button, TextArea, DropDown, etc., not just ContentSwitcher (because it is used in the description.

https://ibm-studios.slack.com/archives/CQGR0HC05/p1733237950971699

Issue: #6523

[RichKummer]

Requirements

Must have

Composability

• Header main slot for prominent child components (progress indicator, etc.). Adopters have been on their own to add this additional space.
• Header action slot position should be adjusted. This is currently floating without a visual anchor in the header.
• Grid influencer slot. Adopters use a variety of child components for navigation in the left influencer. Also need to consider the right grid influencer
• Main area
• Label – some teams are using Breadcrumb in this area – to do follow-up research.
• Action footer (buttons)

Responsiveness

• Right now the Tearsheet does not display content well @md and @sm breakpoints. We should consider content ordering and even a sticky condensed version of the header area on-scroll.
• Like PageHeader the header action will condense buttons into a combo button on smaller screensizes. We should align with PageHeader in allowing teams to handle this adaptive behavior how they want.

Width

• Right now the Tearsheet's width is determined by the total width of the viewport – it will always extended edge-to-edge. We should consider a smart default max-width that would avoid creating additional mouse travel time/effort on larger screens.

Content

• Should follow PageHeader "read more" functionality as an optional utility to handle a large amount of text. Teams have complained that a two line truncation is not always the best option for them.
• The heading, label, and description should have a maximum width of 640px to prevent long lines of copy in the component. This will also align it with PageHeader. We are moving away from a percentage-based layout between these two components.

Accessibility

• Should follow up with Mike Gower on stacking functionality. Is this an accessibility concern? Do we need additional guidance for using this?
• Need to update the tab order of the heading per Jeff L's discovery.

Stepping

• Matt Gallo has already explored bringing the stepping functionality from CreateTearsheet to the base component.

Documentation

• Additional content on new features (max-width, etc.).
• Information and recommendations for slotting components (main vs header action slot).
• Additional guidance on when to use Tearsheet vs Side panel vs a full page.
• Information and examples of laying out the grid responsively (Matt + Elysia confirmed that main area acts as an open canvas).
• Information on <dialog> native element? Link to core?
• If action footer is updated, then we need information on that
• Any needed information on accesibility.
• Header truncation (Depending on how it is handled in PageHeader docs).
• Examples shown for the four themes.
• Additional examples that are not simply forms (which are shown heavily in the current Tearsheet docs).
• Additional guidance on stepping. Information on when to use Stepping vs Stacking?

Nice to have

Grid

• The Tearsheet does not align with the grid in the background, and instead has its own grid to display content. Would it be possible to align the grids together? Does it matter when content is covered by the opaque dark background?

Close button

• The close button is the natural alignment tool for both the decorator and the header action. However, because the Close button is flush with the top and right edges, it makes it hard to align all the components in that corner across interactive states (hover, etc.). We might consider insetting the close button, but this would bring the Tearsheet out of sync with other similar components like Modal.

Header

1. The decorator (AI slug), and header action are not well aligned visually with the close button. We should explore using an inset button across options where the different elements are aligned whether or not they are hovered over or not.
   1. This might also need a look across all components/patterns that contain a close button.
   2. Close button should be in the same position whether or not there are other heading elements.
2. The header remains fixed and visible even as the screen is zoomed in or shrunk based on breakpoint.
   1. Considering a scroll function that would condense the heading and create more space for a main section.
   2. We could also consider removing the fixed behavior on smaller screen sizes so that the user can scroll past the header.
3. Many teams are concerned with the way the header action is automatically condensed into a combo button.
   1. We will not enable this in v2 of Tearsheet. Instead, adopters should consider how those header actions should be presented on smaller screen sizes (needs doc guidance).
4. Currently, the Tearsheet automatically truncates the description at two lines which can be hovered to view the browser-defined full version of the text.
   1. We should remove the automatic truncation and give teams tools to handle this.
   2. Right now we might offer no truncation by default, but users can use utilities to show a "Read more" link to expand or contract as needed.
5. The header section uses a percentage-based split for its contents (60% / 40%)
   1. We should mirror PageHeader in its new responsive behavior (640px max-width and column alignment).
6. The Event Automation team has some specs of Tearsheet that use breadcrumbs instead of a label. Reached out to team to get more background on what that is for (in-Tearsheet navigation? Something else?)

Responsive behavior

1. Currently the Tearsheet extends edge-to-edge with some padding. The width is entirely driven by the screensize with no max-width.
   1. We are considering a default max-width which adopters can disable to extend the Tearsheet to fill the available space.
2. The Tearsheet is not easy to use at smaller breakpoints. We should take care to redesign the Tearsheet with @sm and @md screen sizes in mind.
3. TBD

Grid behavior

1. Currently, when a Tearsheet is active, there are two grids visible: the Tearsheet's grid and the page (although this is obfuscated by the overlay).
   1. We should explore an option to align the two grids so that the content aligns even through the overlay.

Grid influencer

1. There are two grid influencers (left and right) that have different styles and purposes.
   1. We need to consider what components can be slotted into the left and right influencer areas to determine the spacing needs.
   2. We should consider providing more detail of how to use these in the guidance.

Stacking vs stepping

1. We have already ported the stepping behavior that was found in CreateTearsheet to the Tearsheet component.
2. We need to consider the stacking behavior from an accessibility standpoint.
3. We also need to consider stacking at smaller breakpoints. Currently the stack is not visualized when @sm.

Tokens and theming

1. Reference css variables from Theme not defined in Tearsheet #4589. Tearsheet does not respect local theme set on the component. This should be enabled for v2 of Tearsheet.
2. Considering tokens/layering for Tearsheet. $background > $layer-01 or $layer-01 > $background

[RichKummer]

Accessibility – tab order 02/17/25

Discussion with @jlongshore

Currently, the Tearsheet has an odd tab order for its interactive elements:

1. The order begins with the close button selected (Carbon's modal does not, it is last in the order).
2. The order also moves from some header elements such as the close button and AI slug/decorator, to the grid influencer and main content area. Only once the user has tabbed past these do they arrive at the other header elements.

Ideally the tab order follows a logical ordering (similar to PageHeader) and prioritizes header interactive elements before moving down into the grid influencer and main area.

Current tab order

tabOrder.mov

[RichKummer]

Cameron review 03/06/25

Resolved

Header area

• Insetting the close button and header actions might not work across every component that uses these. For now, we should hold off. The lightest touch is shifting the action header and adding some spacing between the decorator and the close button.
• Positioning of slots and spacing are fine.

Grid influencer

• When it comes to the grid influencer at smaller screen sizes, we should enable teams to define the way they want the grid influencer to appear. In opening up the grid influencer, we cannot have a one-size-fits-all responsive behavior. Instead, we should prompt the teams to think about how they want to handle it.

Max-width

• Need a defined max-width that presents the main area in the best way considering the grid. Need follow-on guidance.

Guidance

• Need guidance for teams to strongly consider not stacking modals and tearsheets.
• Need guidance on working with the grid inside Tearsheet. Special attention needs to be paid towards thinking about responsiveness.

Needs exploration/work

• Split on opening up the action footer. If teams have full freedom, we might see radically different flows that are inconsistent. Opening it up might help teams to use their own labels and layout. For now, we lean on keeping these structured as-is
  • We should check composable modal. If this changes it might need to be together with similar components.
• Need to still consider consistent Cancel button styling
• Do we need an option to float the tearsheet away from the bottom of the viewport?