Audit components open/closed props for consistency

[SkyeSeitz]

Description

An audit to define open and open/closed verses expanded/collapsed properties and use consistently across Calcite components.

Audit summary: The audit effort was completed in June 2024, and deprecations and new functionality will be added during the 3.0 breaking change release, with anticipated removal in the 4.0 breaking change release.

Blocked issues: #6473, #4531, #6789

cc @geospatialem @ashetland @macandcheese @jcfranco

Acceptance Criteria

New components and props should follow this updated pattern:
open/close: Toggles visibility of entire component, or its menu
expand/collapse: Toggles visibility of more content within a component


Certain components may have need for both an open/close state as well as a expanded/collapsed such as:
[list-item] can be open (component is visible) & collapsed (child items are hidden) at the same time
[panel] can be open (component is visible) & collapsed (content area is hidden) at the same time

Action items for 3.0:
[list-item] deprecate open & add functionality to expanded
[block] deprecate open & add functionality to expanded
Consider an eslint rule to ensure a component does not have both open/closed -or- expanded/collapsed

Events:
Leverage the open/close utility for expanded and collapsed. Likely just needs some small functional tweaks. Refer to Eliza's comment below for more context.

Link to Figma file

Which Component

Applies across multiple components:
list-item, block

Esri team

Calcite (design)

[SkyeSeitz]

This is a proposal to start the discussion with follow up questions:

1. Depending on how we define open, does anything in the open category fit better in active or expanded?
2. In the case of Action's active prop, how to we define the difference between its role and a selected prop?

[anveshmekala]

During our API consistency audit, we defined expanded for components which expand or collapse within the same area as component where as open is used for component which display a popup or content outside of component with a trigger button. These are the initial thoughts and open might just work for all the use cases.

[SkyeSeitz]

During our API consistency audit, we defined expanded for components which expand or collapse within the same area as component where as open is used for component which display a popup or content outside of component with a trigger button. These are the initial thoughts and open might just work for all the use cases.

Thanks, @anveshmekala! By all use cases do you mean including Block, Accordion Item, Tree, List, and Action Bar? Those sound like they fit your description of expanded, correct?

[ashetland]

I think the original logic still makes sense, should we decide to stick with it. I think we can be more consistent in implementing it though. Based on our audit, I believe the inconsistencies are on Block and List. Both use open, but I believe expanded would be correctly following the original logic.

Tip feels like an outlier here. Its props are close-disabled and closed which is at odds with closable that's used, I think, everywhere else.

[SkyeSeitz]

Looking at Tip again, you are right, it should be in its own category to consider changing to closable if possible. I have updated the proposal image above.

[macandcheese]

Panel, Chip, Notice, etc., also have closable. I'd hold off on any updates to the Tip component as it will likely end up seeing significant change / rename : #6536

[anveshmekala]

During our API consistency audit, we defined expanded for components which expand or collapse within the same area as component where as open is used for component which display a popup or content outside of component with a trigger button. These are the initial thoughts and open might just work for all the use cases.

Thanks, @anveshmekala! By all use cases do you mean including Block, Accordion Item, Tree, List, and Action Bar? Those sound like they fit your description of expanded, correct?

they does fit the definition of expansion, but there is a discussion of using just open to limit the confusion.

cc : @jcfranco

[anveshmekala]

I think the original logic still makes sense, should we decide to stick with it. I think we can be more consistent in implementing it though. Based on our audit, I believe the inconsistencies are on Block and List. Both use open, but I believe expanded would be correctly following the original logic.

Tip feels like an outlier here. Its props are close-disabled and closed which is at odds with closable that's used, I think, everywhere else.

The reason behind using closed and closeDisabled for tip is to make sure the prop names makes sense for the default value of false, we have a convention at the code level to not use props whose default value is true.

if we replace closeDisabled with closable then the default value has to be true

[SkyeSeitz]

Updated the issue description to complete this design proposal.

[github-actions]

cc @geospatialem, @brittneytewks

[Elijbet]

I wasn't aware we had components with closed/collapsed props instead of open/expanded. I don't think the openClose commonTest util accounts for those cases. openPropName currently checks for either "open" or "expanded".
tip, chip, and flow-item that use closed don't have openClose tests set up for them. Neither do panel and shell-panel that have collapsed. flow-item has both collapsed and close.

Submitting this issue towards the effort: Expand openClose commonTest util to account for components with closed/collapsed props #9511

Also propose introducing clarity in event naming for expanded/collapsed vs open/closed: Revisit event names emitted by openCloseComponent util #9513

[driskull]

Nice catch @Elijbet. We need to add those events for sure

[github-actions]

cc @geospatialem, @brittneytewks