feat(components): Autocomplete Custom Menu Rendering #2229

MichaelParadis · 2024-12-10T17:44:52Z

Motivations

As a part of our composability and customizabilty work we wanted to add support for rendering a custom menu in the Autocomplete. To achieve this I added a customMenuRender prop that will be used to replace the content when the Autocomplete menu is opened.

To help achieve this I did the following:

Exposed two hooks to aid in handling keyboard navigation with the Autocomplete
- useKeyboardNavigation for handling the existing keyboard navigation behaviour. This works when the customization of the menu only renders MenuOptions and doesn't include custom elements
- useCustomKeyboardNavigation this is used when the Autocomplete menu has elements that aren't just options. The reason for this is that the Autocomplete can not be certain of how people want keyboard navigation to work. This works to prevent issues with custom selectable items such as a footer to create another option.
Expose various atoms that we use for rendering the content in the Autocomplete menu such as:
- MenuOption which is the default behaviour of menu options in Autocomplete
- MenuOptionContent the default rendering of the content of a MenuOption
- BaseMenuOption the base wrapper of the MenuOption this component handles the highlighted and separator logic
- Also added UNSAFE_ props for overriding the styles of these atoms

Decisions

I decided to give full access to the Autocomplete Menu including when it is rendered when using the customMenuRender. The reason for this is that the existing Autocomplete wouldn't display a menu if no options were available. However, when custom rendering a Menu the consumer may want to show a "Create new X` option instead.

I made the options type support generics, the reason for this is that if generics weren't provided then the customMenuRender wouldn't be aware of the properties of the options it is rendering which would require consumers to use typescript casting to be able to get the properties of an object for rendering.

I removed the XOR of Option and Group option for OptionCollection the reason for this is that I found it was causing headaches when introducing support for generic option types. I also found that OptionCollection wasn't actually enforcing that initialOptions and getOptions was only an array of Options or GroupOptions

Changes

Added

feat(components): Added ability to render a custom menu in the Autocomplete
Expose Atoms used for rendering the Menu in Autocomplete

Testing

Verify existing Autocomplete stories work as the did previously (verify keyboard navigation and using a mouse, etc.)
Verify that the Custom Rendering story can be used with both a keyboard and a mouse
Verify existing Autocomplete usages work (see testing branch referencing this PR)

Changes can be
tested via Pre-release

In Atlantis we use Github's built in pull request reviews.

cloudflare-workers-and-pages · 2024-12-10T17:46:25Z

Deploying atlantis with Cloudflare Pages

Latest commit:	`3f80505`
Status:	✅ Deploy successful!
Preview URL:	https://638c0714.atlantis.pages.dev
Branch Preview URL:	https://job-111436-rhf-autocomplete.atlantis.pages.dev

View logs

MichaelParadis · 2025-01-23T22:43:49Z

packages/components/src/Autocomplete/Autocomplete.types.ts

+export interface AutocompleteProps<
+  GenericOption extends AnyOption = AnyOption,
+  GenericOptionValue extends Option = Option,
+  GenericGetOptionsValue extends AnyOption = AnyOption,


The generic on GetOptionsValue is because some people were passing an initialOptions value that would be a different type to what was returned by getOptions e.g. Initial options would be a list of GroupOptions but getOptions would give Options based on another value in the form

MichaelParadis · 2025-01-28T17:39:59Z

packages/components/src/Autocomplete/Autocomplete.module.css

@@ -28,11 +27,12 @@
 }

 .options.visible {
-  display: block;
+  position: absolute;


Changed the popper visibility to use visibility to match the recommendations in the docs
https://popper.js.org/docs/v2/modifiers/hide/
It also helped with an issue when clicking on customRendered options that didn't use the onMouseDown callback

packages/components/src/Autocomplete/Menu/MenuWrapper.tsx

github-actions · 2025-01-28T21:26:07Z

Published Pre-release for aae2a87 with versions:

  - @jobber/[email protected]+aae2a87b

To install the new version(s) for Web run:

npm install @jobber/[email protected]+aae2a87b

MichaelParadis · 2025-01-28T22:42:11Z

packages/site/src/content/Autocomplete/AutocompleteExamples.tsx

+  );
+}
+
+export const AdvancedTemplateCode = `


I tried various ways to get the Canvas to render the code as well, since the Canvas can't use any state and expects a single component to render I had to break it out into AdvancedCustomTemplate but the show code button stopped working.

I tried using things like the source option but it would also not work.

When I tried using the Source block and doing AdvancedCustomTemplate.toString() it was giving minified code. I am fine removing this is we wish

I went through basically the exact same process with my stuff, wrestled with it for a while, and wrote this ticket to come back and improve it later. So I think the way you did it is totally fine. I would maybe just suggest using a Disclosure or <details> directly to allow people to show/hide the long blocks of code as they need. Right now it is a bit of a long scroll if you aren't interested in one of the examples

chris-at-jobber · 2025-01-28T23:58:22Z

@MichaelParadis something worth checking in-product - in Storybook, I can have multiple custom Autocompletes open at once:

Move menu keyboard navigation to useKeyboardNavigation

Use utility functions in Menu.tsx

…in preparation for customMenu rendering

Support generic usages of BaseMenuOption for custom menu rendering

…ustomMenus

…Option

Move Menu to its own folder

Extract the MenuPopper into a separate component for reuse

Aiden-Brine · 2025-01-29T23:42:08Z

packages/components/src/Autocomplete/useKeyboardNavigation.ts

+  const requestedIndex = options[highlightedIndex + direction];
+
+  return requestedIndex && isGroup(requestedIndex)
+    ? direction + direction


Is it possible that direction + direction is also a group?

No, the Autocomplete removes GroupOptions that have no other options here. So if requestedIndex is a group it will move to one of the following:

The next option which will be inside of the requestedIndex's group

The previous option, which will be inside the Group of options "above" in the menu.

There will be a scenario where two group options (with no nested options) next to each other

Okay, thank you for clarifying that for me

Aiden-Brine · 2025-01-29T23:51:33Z

packages/components/src/Autocomplete/useRepositionMenu.ts

+  attachTo: MenuProps["attachTo"],
+  visible = false,
+) {
+  const [menuRef, setMenuRef] = useState<HTMLElement | null>();


I think this should default to null based on the typing

Updated in 59f6974

Aiden-Brine · 2025-01-29T23:57:36Z

packages/components/src/Autocomplete/useRepositionMenu.ts

+    popper?.update?.();
+  }, [visible]);
+
+  const targetWidth = attachTo.current?.clientWidth;


Should this also be wrapped in useSafeLayoutEffect in case attachTo is resized after this has already been called?

Popper adjusts a lot of the styling automatically. This targetWidth is helpful for initial positioning but once visible has changed react-popper starts controlling the rendering

Update types to better support Options inside of GroupOptions.

… which allows onChange to be the OptionValueType or undefined while onOptionSelect didn't allow it to be undefined

…ctual type

…headings.

…6/rhf-autocomplete

…will live in Autocomplete notes

MichaelParadis · 2025-02-03T21:58:06Z

@ZakaryH I updated storybook and the docs to include information on rendering Autocompletes with custom sections. I am just updating my pre-release branch right now

MichaelParadis · 2025-02-03T22:15:50Z

@ZakaryH

I've read the comments about keyboard navigation

Exposed two hooks to aid in handling keyboard navigation with the Autocomplete
useKeyboardNavigation for handling the existing keyboard navigation behaviour. This works when the customization of the menu only renders MenuOptions and doesn't include custom elements

useCustomKeyboardNavigation this is used when the Autocomplete menu has elements that aren't just options. The reason for this is that the Autocomplete can not be certain of how people want keyboard navigation to work. This works to prevent issues with custom selectable items such as a footer to create another option.

the first one, is there a reason we can't just provide the keyboard navigation behavior by default? I can't really think of a good argument for not implementing that, and so it makes me wonder why we'd have the consumer build it when using a MenuOption

the second one, yeah I guess that makes sense. it might make more sense once I try some very custom content, but I'm still tempted to provide a baseline keyboard experience

The main reason for this is we could need to call default keyboard behaviour in the parent above and provide the "default" highlighted index as a prop to the renderCustomMenu. I could see 2 possible issues:

Since that prop would update on keyboard events the menu would have extra unneeded rerenders
People might see highlighted index prop and not consider that there may be issues with keyboard navigation. It makes the keyboard navigation a more explicit decision to consider if custom navigation is needed

…ion` and `useCustomKeyboardNavigation`

ZakaryH · 2025-02-03T22:35:10Z

is there anything different or special about these Add buttons? I noticed they're persisting for just a bit longer than the rest of the menu when I choose an option which is weird since I'd have thought their visibility would be exactly the same as everything else in the menu

MichaelParadis · 2025-02-04T15:10:22Z

@ZakaryH I too was confused by this. I pushed an update that also fixes this by adjusting the opacity too 3f80505 The position absolute wasn't needed as well so I cleaned that up.

Ideally I use display: none inside the popper but I found that when this gets toggled the onClick handler on the buttons doesn't work. onMouseDown works but I think it is better to make it "easy" to handle custom element events, especially since other aspects of Custom Menus is already pretty complex and it would add yet another thing to consider

ZakaryH · 2025-02-04T17:17:58Z

@MichaelParadis nice, yeah that looks much better!

I haven't looked at the code too closely so I'll let @Aiden-Brine give the final approval, but for the things I was playing around with and all the comments I had made this LGTM

Aiden-Brine

Thank you for making those changes and discussing everything! LGTM

MichaelParadis force-pushed the JOB-111436/rhf-autocomplete branch from 5176974 to 30167e5 Compare December 20, 2024 15:43

MichaelParadis changed the base branch from master to JOB-110887/add-input-text-rebuild December 20, 2024 16:30

Base automatically changed from JOB-110887/add-input-text-rebuild to master January 14, 2025 18:25

MichaelParadis commented Jan 23, 2025

View reviewed changes

MichaelParadis commented Jan 28, 2025

View reviewed changes

packages/components/src/Autocomplete/Menu/MenuWrapper.tsx Outdated Show resolved Hide resolved

MichaelParadis commented Jan 28, 2025

View reviewed changes

packages/components/src/Autocomplete/Menu/MenuWrapper.tsx Outdated Show resolved Hide resolved

MichaelParadis changed the title ~~feat(components): Autocomplete WIP Early work~~ feat(components): Autocomplete Custom Menu Rendering Jan 28, 2025

MichaelParadis commented Jan 28, 2025

View reviewed changes

MichaelParadis marked this pull request as ready for review January 28, 2025 22:45

MichaelParadis requested a review from a team as a code owner January 28, 2025 22:45

jobbiebot bot added review requested Team Atlantis labels Jan 28, 2025

MichaelParadis added 14 commits January 29, 2025 06:42

Add Autocomplete utils file.

1d313fc

Move menu keyboard navigation to useKeyboardNavigation

Move Menu props and Option types to types file

5903a06

Move useRepositionMenu into separate file

9fa83fd

Fix import references import not in types file

f67e495

Use utility functions in Menu.tsx

Extract Autocomplete Menu popper into a separate component for reuse …

ea62f8e

…in preparation for customMenu rendering

Build Autocomplete Menu to use Primative options

1054abd

Fixing Autocomplete prop generics to work with customMenuRendering

21abe86

Expose Atoms for Autocomplete Options.

06bc698

Support generic usages of BaseMenuOption for custom menu rendering

Update Autocomplete to use AutocompleteProps in types file

bb4a67b

Update useKeyboardNavigation to use a new API that can be reused in C…

086f8e8

…ustomMenus

Update Autocomplete utils to work with the new type definition of Any…

5f03a22

…Option

Create interface for return value of UseRepositionMenu

572eb2d

Update Menu to support rendering of CustomContent.

cb1fef5

Move Menu to its own folder

Extract DefaultMenu for Autocomplete into separate component.

7d77e0a

Extract the MenuPopper into a separate component for reuse

Aiden-Brine reviewed Jan 29, 2025

View reviewed changes

MichaelParadis added 14 commits January 30, 2025 07:27

Rename isGroup to isOptionsGroup to make it more clear.

b3870fc

Update types to better support Options inside of GroupOptions.

Expose BaseMenuGroupOption Atom

3b4a04a

Update naming in MenuWrapper.tsx to be more clear about what things are

1771506

Update onOptionSelect types to actually match the Autocomplete's type…

1728b0c

… which allows onChange to be the OptionValueType or undefined while onOptionSelect didn't allow it to be undefined

Update default value of menuRef in useRepositionMenu to reflect the a…

59f6974

…ctual type

Prevent mapToOptions from being called on every rerender

aef4622

Update Menu onOptionSelect which was missed in 1728b0c

6d98410

Update Autocomplete heading styling to work better with custom Group …

574bf07

…headings.

Update storybook examples with Advanced Section rendering

ec07901

Merge branch 'master' of github.com:GetJobber/atlantis into JOB-11143…

62c52eb

…6/rhf-autocomplete

Update comments in Autocomplete web stories

00e5ab8

Remove duplicated documentation in Autocomplete stories. The content …

7e87865

…will live in Autocomplete notes

Update documentation on Autocomplete for section headings

aae2a87

Readd related components to Autocomplete.stories.mdx

83703d3

Update comments with clarification on when to use `useKeyboardNavigat…

4d496c6

…ion` and `useCustomKeyboardNavigation`

Fixed Autocomplete menu rendering with Custom Elements

3f80505

MichaelParadis requested a review from Aiden-Brine February 4, 2025 17:29

Aiden-Brine approved these changes Feb 4, 2025

View reviewed changes

jobbiebot bot added approved and removed review requested labels Feb 4, 2025

MichaelParadis merged commit 262a1df into master Feb 5, 2025
13 checks passed

MichaelParadis deleted the JOB-111436/rhf-autocomplete branch February 5, 2025 15:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(components): Autocomplete Custom Menu Rendering #2229

feat(components): Autocomplete Custom Menu Rendering #2229

MichaelParadis commented Dec 10, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Dec 10, 2024 •

edited

Loading

MichaelParadis Jan 23, 2025

MichaelParadis Jan 28, 2025

github-actions bot commented Jan 28, 2025 •

edited

Loading

MichaelParadis Jan 28, 2025

Aiden-Brine Jan 29, 2025

chris-at-jobber commented Jan 28, 2025

Aiden-Brine Jan 29, 2025

MichaelParadis Jan 30, 2025

Aiden-Brine Jan 30, 2025

Aiden-Brine Jan 29, 2025

MichaelParadis Feb 3, 2025

Aiden-Brine Jan 29, 2025

MichaelParadis Jan 30, 2025

MichaelParadis commented Feb 3, 2025

MichaelParadis commented Feb 3, 2025

ZakaryH commented Feb 3, 2025

MichaelParadis commented Feb 4, 2025

ZakaryH commented Feb 4, 2025

Aiden-Brine left a comment

feat(components): Autocomplete Custom Menu Rendering #2229

feat(components): Autocomplete Custom Menu Rendering #2229

Conversation

MichaelParadis commented Dec 10, 2024 • edited Loading

Motivations

Decisions

Changes

Added

Testing

cloudflare-workers-and-pages bot commented Dec 10, 2024 • edited Loading

Deploying atlantis with Cloudflare Pages

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jan 28, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chris-at-jobber commented Jan 28, 2025

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

MichaelParadis commented Feb 3, 2025

MichaelParadis commented Feb 3, 2025

ZakaryH commented Feb 3, 2025

MichaelParadis commented Feb 4, 2025

ZakaryH commented Feb 4, 2025

Aiden-Brine left a comment

Choose a reason for hiding this comment

MichaelParadis commented Dec 10, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Dec 10, 2024 •

edited

Loading

github-actions bot commented Jan 28, 2025 •

edited

Loading