feat(flow): add support for custom flow-item elements #7608

jcfranco · 2023-08-26T00:02:57Z

Related Issue: #6237

Summary

This enables flow to work with custom components using shadow DOM wrapping flow-item.

Custom components will have to implement the FlowItemLike interface and set the new custom-item-selectors/customItemSelectors attr/prop to target custom components (see E2E test for vanilla JS example).

Note: customItemSelectors is intentionally marked internal since we don't have any documentation yet on developing custom components, which this is meant to support. We could additionally hide FlowItemLike in the doc site to avoid confusion until we have more documentation on this use case. I'm open to suggestions on this. @geospatialem @macandcheese @driskull

driskull

This is looking awesome @jcfranco. I think we just need to decide on the name & finalize it since this may pop up for other components.

driskull · 2023-08-31T17:45:31Z

packages/calcite-components/src/components/flow/flow.tsx

+   *
+   * @internal
+   */
+  @Prop() extraItemSelector: string;


I think we'll need to decide on this name so it can be standardized ™️ and used for any components that may need to adopt this pattern.

Would we want to expose the fact that this is a selector or just allow other item types?

Maybe this should be an array? Then we can just join them with a comma? Like extraItems: string[]

Other names:

customItems

additionalItems

extendedItems

Agreed on standardizing. I plan to update the conventions doc with info on this.

I went with the current name because it captures what it'll be used for and the type of value that's expected.

WRT the type, I think we should leave it as a string to keep it simple on both sides and because it would also align with DOM-querying APIs where a string selectors argument supports one or more selectors.

Based on the above and your suggestions, I kind of like customItemSelector(s) since it conveys the use case better than the current name.

Alternatively, we can buy some extra time to think about alternative names if we keep everything internal for this release.

Sounds good!

packages/calcite-components/src/components/flow/flow.tsx

driskull

Awesome! MV team will appreciate this :) 💯 🏅

driskull · 2023-08-31T22:32:38Z

packages/calcite-components/conventions/README.md

+
+#### Parent component
+
+- Must provide a `customItemSelectors` property to allow querying for custom elements in addition to their expected children.


The plurality of customItemSelectors threw me off a little because its a single string. Would it make more sense as customItemSelector? I guess technically it can be a single or multiple selectors but its a single string. 🤔

I guess its fine since its referred to as selectors here: https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector

Just ignore my comment then:)

FWIW, I feel the same way about the name. 😅

driskull · 2023-08-31T22:34:29Z

packages/calcite-components/src/components/flow/flow.tsx

 import { createObserver } from "../../utils/observers";
-import { FlowDirection } from "./interfaces";
+import { FlowDirection, FlowItemLikeElement } from "./interfaces";


I think FlowItemLikeElement is fine but it could also be CustomFlowItemElement? I'm fine either way.

I like your name suggestion better, but the interface only requires the props expected by the parent and not all from flow-item.

driskull · 2023-08-31T22:38:24Z

packages/calcite-components/src/components/flow/flow.tsx

-    ).filter((flowItem) => flowItem.closest("calcite-flow") === el) as HTMLCalciteFlowItemElement[];
+    const newItems = Array.from<FlowItemLikeElement>(
+      el.querySelectorAll(
+        `calcite-flow-item${this.customItemSelectors ? `,${this.customItemSelectors}` : ""}`


nitpick: since this.customItemSelectors is used twice, might be nice to include it here:

const { el, items, customItemSelectors } = this;

🤖 I have created a release *beep* *boop* --- <details><summary>@esri/calcite-components: 1.7.0</summary> ## [1.7.0](https://github.com/Esri/calcite-design-system/compare/@esri/[email protected]...@esri/[email protected]) (2023-09-01) ### Features * **action-bar, action-pad, action-group:** Add label properties for group context ([#7415](#7415)) ([b34f36d](b34f36d)) * **combobox:** Add single-persist selection mode ([#7583](#7583)) ([dab06a3](dab06a3)) * **flow:** Add support for custom flow-item elements ([#7608](#7608)) ([197adfe](197adfe)) * **input-date-picker:** Normalize year to current century for user typed values only ([#7638](#7638)) ([a1db718](a1db718)) * **input-number:** Add integer property ([#7646](#7646)) ([cd66a6d](cd66a6d)) * **input-time-picker:** Support fractional seconds ([#7532](#7532)) ([c2bf34b](c2bf34b)) * **meter:** Add Meter component ([#7401](#7401)) ([47163ed](47163ed)) * **sheet:** Add Sheet component ([#7561](#7561)) ([f12a393](f12a393)) * **sheet:** Update default widths ([#7617](#7617)) ([47d2c0b](47d2c0b)) * **shell:** Add "Sheets" Slot ([#7579](#7579)) ([e798765](e798765)) * **table:** Add Table and related components ([#7607](#7607)) ([b067e72](b067e72)) ### Bug Fixes * **accordion, accordion-item:** Improve a11y ([#7560](#7560)) ([b5170b6](b5170b6)) * Add drag styles for improved UX ([#7644](#7644)) ([afbb764](afbb764)) * **block, block-section:** Improve a11y ([#7557](#7557)) ([1f44f6b](1f44f6b)) * **chip-group:** Add existence checks ([#7586](#7586)) ([5ca64f1](5ca64f1)) * **color-picker:** Update value when alphaChannel is toggled ([#7563](#7563)) ([1f753dd](1f753dd)) * **combobox:** Prevent deselecting items via keyboard in single-persist mode ([#7634](#7634)) ([4f5f8b0](4f5f8b0)) * **combobox:** Update combobox height to follow design spec ([#7558](#7558)) ([ec08845](ec08845)) * **date-picker:** Set start of week to monday in zh-CN ([#7578](#7578)) ([7e385cb](7e385cb)) * **dropdown:** Prevents navigating dropdown items with Tab key ([#7527](#7527)) ([3ea658d](3ea658d)) * Ensure label only focuses the first labelable child ([#7553](#7553)) ([426159c](426159c)) * **flow:** Catch error when beforeBack promise is rejected ([#7601](#7601)) ([cb70671](cb70671)) * **input-date-picker, input-time-picker:** Do not show dropdown affordance when read-only ([#7559](#7559)) ([5a3f19c](5a3f19c)) * **input, input-number:** Correctly sanitize numbers when pasting string with 'e' ([#7648](#7648)) ([b8bc11c](b8bc11c)) * **list, sortable-list, value-list:** Emit calciteListOrderChange when dragging between lists ([#7614](#7614)) ([4653581](4653581)) * **list:** Fixes dragging nested list items ([#7555](#7555)) ([c25f7b3](c25f7b3)) * **list:** Stop emitting calciteListChange when a list-item is disabled or closed. ([#7624](#7624)) ([7008463](7008463)) * **loader:** Tweak loading animations to work in Safari ([#7564](#7564)) ([2103654](2103654)) * **modal:** Catch error when beforeClose promise is rejected ([#7600](#7600)) ([70405d0](70405d0)) * **modal:** Handle removal of open attribute and prevent multiple beforeClose calls ([#7470](#7470)) ([f31588f](f31588f)) * **rating:** Adds focus outline on click ([#7341](#7341)) ([af30073](af30073)) * **segmented-control:** Refresh items when added dynamically ([#7567](#7567)) ([2e36eb3](2e36eb3)) * **split-button:** Update divider and borders to follow design spec ([#7568](#7568)) ([8df59ab](8df59ab)) * **tree-item:** Move focus outline to item label area ([#7581](#7581)) ([1327cef](1327cef)) * **tree-item:** Updates state when selection changes programmatically for `selection-mode='ancestors'` ([#7572](#7572)) ([40758c5](40758c5)) * **tree:** Improve keyboard navigation ([#7618](#7618)) ([826a5cb](826a5cb)) </details> <details><summary>@esri/calcite-components-react: 1.7.0</summary> ## [1.7.0](https://github.com/Esri/calcite-design-system/compare/@esri/[email protected]...@esri/[email protected]) (2023-09-01) ### Bug Fixes * Make sure components are defined in environments like in codesandbox ([#7632](#7632)) ([7005cce](7005cce)) ### Dependencies * The following workspace dependencies were updated * dependencies * @esri/calcite-components bumped from ^1.7.0-next.22 to ^1.7.0 </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* origin/main: (35 commits) ci: make sure to exit on maitenance milestone failure (#7656) chore: release next fix(block): provide textual name on collapse and expansion to AT (#7652) chore: release main (#7571) chore: release next fix(block, block-section): improve a11y (#7557) chore: release next fix: add drag styles for improved UX (#7644) fix(input, input-number): correctly sanitize numbers when pasting string with 'e' (#7648) chore: release next feat(flow): add support for custom flow-item elements (#7608) chore: release next fix(list, sortable-list, value-list): Emit calciteListOrderChange when dragging between lists (#7614) feat(input-number): add integer property (#7646) chore: release next fix(accordion, accordion-item): improve a11y (#7560) refactor(stepper, stepper-item): `getElementProp` is refactored out in favor of inheritable props set directly on parent (#7593) docs(contributing): update the commit message format example URL (#7641) chore: release next feat(input-date-picker): normalize year to current century for user typed values only (#7638) ...

**Related Issue:** #7608 ## Summary Splits up interfaces for custom flow item class and elements. This also updates the conventions doc with info on interface usage.

feat(flow): add support for custom flow-item elements

97ea77d

github-actions bot assigned jcfranco Aug 26, 2023

github-actions bot added the enhancement Issues tied to a new feature or request. label Aug 26, 2023

jcfranco added 2 commits August 26, 2023 01:13

tidy up

3e2d8f8

add test

d712724

jcfranco added the pr ready for visual snapshots Adding this label will run visual snapshot testing. label Aug 26, 2023

driskull reviewed Aug 31, 2023

View reviewed changes

rename custom item selectors prop

e87200c

jcfranco added pr ready for visual snapshots Adding this label will run visual snapshot testing. and removed pr ready for visual snapshots Adding this label will run visual snapshot testing. labels Aug 31, 2023

add conventions entry with info on pattern

5587256

jcfranco marked this pull request as ready for review August 31, 2023 22:28

jcfranco requested a review from a team as a code owner August 31, 2023 22:28

jcfranco added pr ready for visual snapshots Adding this label will run visual snapshot testing. and removed pr ready for visual snapshots Adding this label will run visual snapshot testing. labels Aug 31, 2023

driskull approved these changes Aug 31, 2023

View reviewed changes

tidy up

4651af9

jcfranco added pr ready for visual snapshots Adding this label will run visual snapshot testing. and removed pr ready for visual snapshots Adding this label will run visual snapshot testing. labels Aug 31, 2023

jcfranco merged commit 197adfe into main Sep 1, 2023

jcfranco deleted the jcfranco/6237-add-support-for-custom-flow-items branch September 1, 2023 00:04

github-actions bot added this to the 2023 September Priorities - Main release milestone Sep 1, 2023

calcite-admin mentioned this pull request Sep 1, 2023

chore: release main #7571

Merged

jcfranco mentioned this pull request Sep 2, 2023

feat(flow): split up custom flow item interfaces #7666

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(flow): add support for custom flow-item elements #7608

feat(flow): add support for custom flow-item elements #7608

jcfranco commented Aug 26, 2023 •

edited

Loading

driskull left a comment

driskull Aug 31, 2023 •

edited

Loading

jcfranco Aug 31, 2023

driskull Aug 31, 2023

driskull left a comment

driskull Aug 31, 2023

driskull Aug 31, 2023

jcfranco Aug 31, 2023

driskull Aug 31, 2023

jcfranco Aug 31, 2023

driskull Aug 31, 2023


		#### Parent component

		- Must provide a `customItemSelectors` property to allow querying for custom elements in addition to their expected children.

feat(flow): add support for custom flow-item elements #7608

feat(flow): add support for custom flow-item elements #7608

Conversation

jcfranco commented Aug 26, 2023 • edited Loading

Summary

driskull left a comment

Choose a reason for hiding this comment

driskull Aug 31, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

driskull left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jcfranco commented Aug 26, 2023 •

edited

Loading

driskull Aug 31, 2023 •

edited

Loading