[calcite-flow-item] does not have a back button if within a shadow root

[ethanbdev]

Actual Behavior

With showBackButton being internal and defaulting to false, by default a flow item within a shadow root is missing the back button, breaking the functionality of a flow item.

Expected Behavior

It should show a back button when it is the active flow item

Reproduction Sample

https://codepen.io/eborgen/pen/vYaygZy

Reproduction Steps

Observe that with a structure that puts a shadow root boundary between the calcite-flow and calcite-flow-item, the back button does not render.

Reproduction Version

next.707

Relevant Info

No response

Regression?

between beta.99 and next.707

Impact

High - it breaks the workflow unless I set an internal prop and ignore the type error

Esri team

ArcGIS Map Viewer

[geospatialem]

Could be related to the utilities used, will need a refactor in the component to mitigate without the use of the utility functions.

[jcfranco]

@ethanbdev I could be misinterpreting the issue, but from what I can recall, flow never supported flow-items within the shadow DOM of extraneous components. Can you update your codepen or provide one that shows this behavior?

[ethanbdev]

@ethanbdev I could be misinterpreting the issue, but from what I can recall, flow never supported flow-items within the shadow DOM of extraneous components. Can you update your codepen or provide one that shows this behavior?

That makes sense, I think we are not using the flow-item quite correctly. But with the removal of the showBackButton attribute it made it not work at all. It could be reasonable to have a tree structure like:

<calcite-flow>
  <my-custom-component>
    <calcite-flow-item />
  </my-custom-component>
</calcite-flow>

If that is not supported we can adjust the structure or consider a different component, like a panel with a slotted action in the header.

[geospatialem]

Allocating to the February release for further discussion.

[jcfranco]

@ethanbdev Gotcha. In the above structure snippet, is the item in the same light DOM tree as the flow? If so, I think that would work. I believe Map Viewer has some components structured similarly. @AdelheidF can you confirm?

[AdelheidF]

Yes, I use this in a few places, though with

shadow: false,
scoped: true

[ethanbdev]

@ethanbdev Gotcha. In the above structure snippet, is the item in the same light DOM tree as the flow? If so, I think that would work. I believe Map Viewer has some components structured similarly. @AdelheidF can you confirm?

It is not, all of our components utilize shadow: true

(I added show-back-button manually, ignoring the type error)

[jcfranco]

@ethanbdev Thanks for the info and apologies for the belated reply. 😅 We'll need to revisit the timeline for this while we do some research on the approach. FWIW, we prototyped something that could be used as the base for this: #4817 (comment).

Did you find a workaround or is this still a high impact issue for you?

[AdelheidF]

I would very much like to use shadow: true as well. Considering that we want to create all these custom flow-item wrapping components to be used everywhere they all run into this issue. I would still like to see this fixed.

If I don't use shadow: false the flow-items appear in a single panel underneath each other with 1.0.7.

[ethanbdev]

I would say it has moved to a more moderate impact. The workaround is to use an undocumented, internal prop. We hope to change the structure of the components to not have the flow item in the shadow root, but I think it still felt like a regression when this behaviour changed

[johngalambos]

It's possible I'm doing things wrong here, but with the calcite-components-react, I think the the flow item is always in a shadow root? And without the showBackButton attribute public anymore, I don't think it's possible to display a back button?

E.g.
`function AreaSelector (props:NoSelectionProps) {

return (
	<CalciteFlow>
	<CalciteFlowItem
		heading="Areas"
		closed={false}>
		<div className="esri-widget esri-widget--panel parcel-manager parcel-manager__panel-content">
			<div className="parcel-manager__panel-content__message">Select an area</div>
		</div>
	</CalciteFlowItem>
	</CalciteFlow>
);

}
`

renders as:

[driskull]

I think we want to make sure parent/child components are within the same DOM and not separated by a shadowDOM so that they can work correctly.

I think even native elements need to be like this to work and are accessible.

I may be mistaken, but I don't think you can do a native select and child option elements in a shadowRoot.

[github-actions]

Installed and assigned for verification.

[jcfranco]

@ethanbdev @AdelheidF calcite-flow now supports custom flow items (i.e., custom elements using shadow DOM that wrap a calcite-flow-item). There are 2 steps needed to have flow pick these custom items:

1. Set flow's customItemSelectors/custom-item-selectors to match the custom item element.
2. Update your custom item element to implement the FlowItemLike interface. The simplest approach would be to wrap a flow item, which I believe you already do.

Here's an example showing how you can do that with vanilla JS: https://codepen.io/jcfranco/pen/zYyBJEV. It should be much more straightforward w/ Stencil or similar tooling.

Stencil component example

import { Component, Host, h, Prop, Method } from "@stencil/core";
import type { FlowItemLike } from "@esri/calcite-components/dist/types/components/flow/interfaces.d.ts";

@Component({
  tag: 'custom-flow-item',
  shadow: true,
})
export class CustomFlowItem implements FlowItemLike {

  private flowItem: HTMLCalciteFlowItemElement;

  @Prop() beforeBack: () => Promise<void>;

  // not required by the interface, but adding to allow passing through to `calcite-flow-item`
  @Prop() heading: string;

  @Prop() menuOpen: boolean;

  @Prop() showBackButton: boolean;

  @Method()  async setFocus(): Promise<void> {
    await this.flowItem.setFocus();
  };

  render() {
    return (
      <Host>
        <calcite-flow-item
          beforeBack={this.beforeBack}
          heading={this.heading}
          menuOpen={this.menuOpen}

          // @ts-ignore -- internal
          showBackButton={this.showBackButton}
     
          // eslint-disable-next-line react/jsx-sort-props -- ref should be last so node attrs/props are in sync (see https://github.com/Esri/calcite-design-system/pull/6530)
          ref={el => this.flowItem = el}
        >
          <slot/>
        </calcite-flow-item>
      </Host>
    );
  }
}

Note that the new prop and interface won't be available in the documentation until we have something covering custom element creation (no timeline on that). cc @geospatialem @macandcheese

Let us know if you need any help or have any questions.

Happy coding! ✨💻✨

[geospatialem]

Verified with the Codepen mentioned in Franco's post above. ☝🏻

[AdelheidF]

The & HTMLElement is giving me issues here
export type FlowItemLikeElement = Pick<HTMLCalciteFlowItemElement, "beforeBack" | "menuOpen" | "setFocus" | "showBackButton"> & HTMLElement;

Error
Class 'ArcgisSmartMappingGallery' incorrectly implements interface 'Pick<HTMLCalciteFlowItemElement, "beforeBack" | "menuOpen" | "setFocus" | "showBackButton"> & HTMLElement'. Type 'ArcgisSmartMappingGallery' is not assignable to type 'HTMLElement'. Type 'ArcgisSmartMappingGallery' is missing the following properties from type 'HTMLElement': accessKey, accessKeyLabel, autocapitalize, dir, and 285 more.ts(2420)

[jcfranco]

#7666 will split up the interface into:

• FlowItemLike – interface for classes to implement
• FlowItemLikeElement – interface for APIs of parent components supporting custom items

I've also added a Stencil-based example for custom flow items in my previous comment.

Technically, the custom item doesn't need to implement the interface for it to be picked up by flow, but it should to ensure APIs are in sync.

[github-actions]

Installed and assigned for verification.

[jcfranco]

#7666 landed! 🛬

@AdelheidF Would you be able to help verify once 1.7.1-next.3 (or greater) is deployed later today?

[AdelheidF]

Seems good with 1.8.0-next.0. Thanks!

[geospatialem]

Closing per #6237 (comment).

[jcfranco]

@AdelheidF Thanks for testing! 🙌