Fix ComboBox options' tag flicking

[r100-stack]

Changes

Fixes #2112. As mentioned in #2112 (comment), I believe the flickering is because of an infinite loop:

visibleCount from our useOverflow internal hook changes on each resize of iui-select-tag-container and each resize changes the visibleCount.

I think this is because our useOverflow hook makes the assumption that all items are around the same size and thus we can take an average:

iTwinUI/packages/itwinui-react/src/utils/hooks/useOverflow.tsx

Line 79 in 4f431e5

const avgItemSize = requiredSize / visibleCount;

While this may work for cases like the TablePaginator, it doesn't seem to work for the ComboBox case where tags could have different widths.

This PR refactors useOverflow with a new algorithm that now takes the actual widths/heights into consideration.

New algorithm for useOverflow

Logic:

• Have a guess range for visibleCount. e.g. [0, 32] (32 is an arbitrary choice).
• Keep doubling the max guess until the container overflows.
  i.e. the max guess should always be ≥ the correct visibleCount.
  • With each such doubling, the new min guess is the current max guess (since underflow = we guessed low).
• Set visibleCount to the maxGuess.
• Repeat the following by calling guessVisibleCount() (keep re-rendering but not painting):
  • Each time the container overflows, new max guess is the average of the two guesses.
  • Each time the container does not overflow, new min guess is the average of the two guesses.
• Stop when the average of the two guesses is the min guess itself. i.e. no more averaging possible.
• The min guess is then the correct visibleCount.

Why this works:

• This approach takes the real widths/heights into account. So, the previous flickering is no longer there.
• Even if there are 10k items (for example), the maximum number of items we render starts from 32 and keeps doubling until we reach the first overflow. After the first overflow, the number of items we render always goes down. So, performance is not affected because we don't render any more items than needed.
• Since this approach involves halving the guess in each render, I believe this approach is of the order of log(n).

While working on useOverflow, it seemed hard to get it to work by using refs and also not knowing the children. So, this PR creates a new private component called OverflowContainer that calls useOverflow internally. useOverflow is this now no longer used by any other component.

OverflowContainer:

• We just pass it the children, overflowTag and overflowTagPlacement (e.g. overflow from start or end). It automatically places the overflowTag at the overflowTagPlacement.
• For custom cases (e.g. where overflow doesn't happen exactly in the start or end), a function could be passed ((visibleCount) => React.ReactNode) as the child of OverflowContainer. Now what to render based be customized based on the visibleCount. itemLength is required in this case.

---

I also tested that this bug does not regress some related prior bug fixes. Examples:

• Select : Incorrect tags being displayed when we have long string as dropdown menu item in Multi Select component #1633 (comment): Added an e2e test in Select and ComboBox for this case.

Testing

• Since useOverflow now renders multiple times, having unit tests to mock rendered sizes is now unreasonable. So, I replaced all failing unit tests related to useOverflow with e2e tests.

Before/After

Before:

Enregistrement.de.l.ecran.2024-06-28.a.13.28.29.mov

After:

Enregistrement.de.l.ecran.2024-06-28.a.13.25.54.mov

Docs

• Added JSDocs for the new algorithm, components, hooks, etc. to better explain this new algorithm.
• Added changesets.

[r100-stack]

Needed this to allow the .iui-breadcrumbs-list's visibleCount to update whenever .iui-breadcrumbs resizes.

[mayank99]

Is it possible to split this into multiple stacked PRs? It's extremely difficult to understand/review it right now (unless you're looking for a quick LGTM)

[r100-stack]

Looks like there's some flakiness/unreliability in the e2e tests when running on the GitHub CI (action run).

Investigating why it keeps failing only in the CI and not locally despite having awaits with the Promise returning expects.

[Ben-Pusey-Bentley]

I don't think that I understand how this part of the algorithm works. This is apparently halving the visibleCountGuesssRange, but I don't know how visibleCount is half of the max for the guess range. I must be missing something, since I am able to test the overflow container out with the deploy preview and see that it is working.