From 28cde34d90d98bb8d2af7bb589fa8390a227152e Mon Sep 17 00:00:00 2001
From: Alireza <alireza.mirian@gmail.com>
Date: Thu, 28 Dec 2023 19:14:15 +0100
Subject: [PATCH] feat(toolbar): handle toolbar overflow

---
 .../ChangesView/ChangesViewToolbar.tsx        |   2 +-
 packages/jui/src/Icon/useSvgIcon.tsx          |  30 +-
 .../jui/src/InputField/InputField.stories.tsx |   2 +-
 packages/jui/src/Menu/Menu.stories.tsx        |   2 +-
 packages/jui/src/Menu/MenuTrigger.tsx         |  19 +-
 packages/jui/src/Popup/Popup.tsx              |   3 +-
 packages/jui/src/StyledSeparator.tsx          |   2 +-
 packages/jui/src/Tabs/2-Tabs.stories.tsx      |  57 ++-
 packages/jui/src/Tabs/Tab.tsx                 |  36 +-
 packages/jui/src/Tabs/Tabs.tsx                |  16 +-
 .../Tabs/useCollectionOverflowObserver.tsx    |  69 ---
 .../ToolWindows/StyledToolWindowStripe.tsx    |   7 +
 .../stories/components/FakeExecution.tsx      |   2 +-
 .../DefaultToolWindowToolbarButton.tsx        |   9 +-
 .../ToolWindowsImpl/DefaultToolWindows.cy.tsx |   2 +-
 packages/jui/src/Toolbar/Toolbar.cy.tsx       | 251 +++++++++++
 packages/jui/src/Toolbar/Toolbar.stories.tsx  | 241 +++++++++++
 packages/jui/src/Toolbar/Toolbar.tsx          | 401 +++++++++++++++---
 .../utils/overflow-utils/OverflowObserver.ts  | 133 ++++++
 .../overflow-utils/useOverflowObserver.tsx    |  42 ++
 packages/website/docs/components/Toolbar.mdx  | 247 ++++++++++-
 21 files changed, 1384 insertions(+), 189 deletions(-)
 delete mode 100644 packages/jui/src/Tabs/useCollectionOverflowObserver.tsx
 create mode 100644 packages/jui/src/Toolbar/Toolbar.cy.tsx
 create mode 100644 packages/jui/src/Toolbar/Toolbar.stories.tsx
 create mode 100644 packages/jui/src/utils/overflow-utils/OverflowObserver.ts
 create mode 100644 packages/jui/src/utils/overflow-utils/useOverflowObserver.tsx

diff --git a/packages/example-app/src/VersionControl/Changes/ChangesView/ChangesViewToolbar.tsx b/packages/example-app/src/VersionControl/Changes/ChangesView/ChangesViewToolbar.tsx
index 7b93462c..aa681447 100644
--- a/packages/example-app/src/VersionControl/Changes/ChangesView/ChangesViewToolbar.tsx
+++ b/packages/example-app/src/VersionControl/Changes/ChangesView/ChangesViewToolbar.tsx
@@ -15,7 +15,7 @@ import { VcsActionIds } from "../../VcsActionIds";
 
 export function ChangesViewToolbar() {
   return (
-    <Toolbar hasBorder>
+    <Toolbar border="bottom">
       <ActionButton actionId={VcsActionIds.REFRESH} />
       <ActionButton actionId={VcsActionIds.ROLLBACK} />
       <ActionButton actionId={VcsActionIds.SHOW_DIFF} />
diff --git a/packages/jui/src/Icon/useSvgIcon.tsx b/packages/jui/src/Icon/useSvgIcon.tsx
index 09e5b438..f0c6ed4c 100644
--- a/packages/jui/src/Icon/useSvgIcon.tsx
+++ b/packages/jui/src/Icon/useSvgIcon.tsx
@@ -35,11 +35,10 @@ export function useSvgIcon(
       if (svg) {
         if (!unmounted && ref?.current) {
           if (ref) {
-            // potential SSR issues here?
             ref.current?.querySelector("svg")?.remove();
             const svgElement = document.createElement("svg");
             ref.current?.appendChild(svgElement);
-            svgElement.outerHTML = svg;
+            svgElement.outerHTML = makeIdsUnique(svg); // UNSAFE! Would require sanitization, or icon sources must be trusted.
             delete ref.current?.dataset.loadingIcon;
           }
         }
@@ -53,3 +52,30 @@ export function useSvgIcon(
     };
   }, [path, selected]);
 }
+
+/**
+ * If multiple instance of the same icon is rendered at the same time, and the SVG includes
+ * url(#...) references to locally defined ids, in some cases the icon is not rendered properly.
+ * because of ids colliding. We make sure the ids are unique in each rendered icon.
+ */
+function makeIdsUnique(svg: string): string {
+  const randomPostfix = (Math.random() * 1000).toFixed(0);
+  const idMatches = svg.matchAll(/id="(.*?)"/g);
+  return [...idMatches].reduce((modifiedSvg, [_, id]) => {
+    const newId = `${id}-${randomPostfix}`;
+    return replaceAll(
+      `id="${id}"`,
+      `id="${newId}"`,
+      replaceAll(`url(#${id})`, `url(#${newId})`, modifiedSvg)
+    );
+  }, svg);
+}
+
+function replaceAll(theOld: string, theNew: string, str: string): string {
+  const replaced = str.replace(theOld, theNew);
+  const replacedAgain = replaced.replace(theOld, theNew);
+  if (replaced === replacedAgain) {
+    return replaced;
+  }
+  return replaceAll(theOld, theNew, replacedAgain);
+}
diff --git a/packages/jui/src/InputField/InputField.stories.tsx b/packages/jui/src/InputField/InputField.stories.tsx
index 983855e8..64561d8a 100644
--- a/packages/jui/src/InputField/InputField.stories.tsx
+++ b/packages/jui/src/InputField/InputField.stories.tsx
@@ -1,5 +1,5 @@
-import { Meta, StoryFn, StoryObj } from "@storybook/react";
 import React from "react";
+import { Meta, StoryObj } from "@storybook/react";
 import { InputField, InputFieldProps } from "./InputField";
 
 export default {
diff --git a/packages/jui/src/Menu/Menu.stories.tsx b/packages/jui/src/Menu/Menu.stories.tsx
index 89900912..bb1d00cf 100644
--- a/packages/jui/src/Menu/Menu.stories.tsx
+++ b/packages/jui/src/Menu/Menu.stories.tsx
@@ -260,7 +260,7 @@ export const ContextMenu: StoryObj<{
                 />
               </Item>
               <Divider />
-              <Item textValue="Go to">
+              <Item title="Go to">
                 <Item textValue="Navigation Bar">
                   <MenuItemLayout content="Navigation Bar" shortcut="`⌘↑`" />
                 </Item>
diff --git a/packages/jui/src/Menu/MenuTrigger.tsx b/packages/jui/src/Menu/MenuTrigger.tsx
index 9cd01786..f206c10d 100644
--- a/packages/jui/src/Menu/MenuTrigger.tsx
+++ b/packages/jui/src/Menu/MenuTrigger.tsx
@@ -1,4 +1,4 @@
-import React, { HTMLProps, RefObject } from "react";
+import React, { HTMLAttributes, RefObject } from "react";
 import { useButton } from "@react-aria/button";
 import { useMenuTrigger } from "@react-aria/menu";
 import { useOverlay, useOverlayPosition } from "@react-aria/overlays";
@@ -7,6 +7,7 @@ import { useMenuTriggerState } from "@react-stately/menu";
 import { MenuTriggerProps as AriaMenuTriggerProps } from "@react-types/menu";
 
 import { MenuOverlay } from "./MenuOverlay";
+import { AriaButtonProps } from "@react-types/button";
 
 export interface MenuTriggerProps
   extends Omit<AriaMenuTriggerProps, "closeOnSelect"> {
@@ -14,7 +15,7 @@ export interface MenuTriggerProps
   // TODO: replace render function children with normal children, and utilize PressResponder. Add a story for the
   //  edge case of custom trigger, using PressResponder
   children: (
-    props: HTMLProps<HTMLElement>,
+    props: HTMLAttributes<HTMLButtonElement>,
     ref: RefObject<any> // Using a generic didn't seem to work for some reason
   ) => React.ReactNode;
   // NOTE: there is a chance of unchecked breaking change here, since this is not explicitly mentioned as public API
@@ -60,14 +61,12 @@ export const MenuTrigger: React.FC<MenuTriggerProps> = ({
     state,
     triggerRef
   );
-  const { buttonProps } = useButton(
-    {
-      ...triggerProps,
-      // @ts-expect-error: preventFocusOnPress is not defined in public API of useButton
-      preventFocusOnPress,
-    },
-    triggerRef
-  );
+  const ariaButtonProps: AriaButtonProps<"button"> = {
+    ...triggerProps,
+    // @ts-expect-error: preventFocusOnPress is not defined in public API of useButton
+    preventFocusOnPress,
+  };
+  const { buttonProps } = useButton(ariaButtonProps, triggerRef);
   const { overlayProps } = useOverlay(
     {
       onClose: () => {
diff --git a/packages/jui/src/Popup/Popup.tsx b/packages/jui/src/Popup/Popup.tsx
index 748b3224..f711ac84 100644
--- a/packages/jui/src/Popup/Popup.tsx
+++ b/packages/jui/src/Popup/Popup.tsx
@@ -26,7 +26,7 @@ import { PopupContext, PopupControllerContext } from "./PopupContext";
 import { PopupLayout } from "./PopupLayout";
 import { StyledPopupHint } from "./StyledPopupHint";
 
-const StyledPopupContainer = styled.div`
+export const StyledPopupContainer = styled.div`
   position: fixed;
   box-sizing: border-box;
   // not checked if there should be a better substitute for * in the following colors. Maybe "Component"?
@@ -175,6 +175,7 @@ export const _Popup = (
   return (
     <Overlay>
       <OverlayInteractionHandler {...overlayInteractionHandlerProps}>
+        {/* TODO: FocusScope is redundant. Test focus restoration without it (in status bar progress), and remove it if unnecessary */}
         <FocusScope restoreFocus>
           <StyledPopupContainer
             ref={ref}
diff --git a/packages/jui/src/StyledSeparator.tsx b/packages/jui/src/StyledSeparator.tsx
index 4ffdfe4f..56b9a00f 100644
--- a/packages/jui/src/StyledSeparator.tsx
+++ b/packages/jui/src/StyledSeparator.tsx
@@ -15,7 +15,7 @@ const DarculaSeparatorUI: SeparatorUI = {
 const defaultSize =
   2 * DarculaSeparatorUI.STRIPE_INDENT + DarculaSeparatorUI.STRIPE_WIDTH;
 
-const StyledSeparator = styled.hr(({ theme }) => ({
+export const StyledSeparator = styled.hr(({ theme }) => ({
   backgroundColor: theme.color(
     "Separator.separatorColor",
     theme.dark ? "#cdcdcd" : "#515151"
diff --git a/packages/jui/src/Tabs/2-Tabs.stories.tsx b/packages/jui/src/Tabs/2-Tabs.stories.tsx
index 438058e2..05d80796 100644
--- a/packages/jui/src/Tabs/2-Tabs.stories.tsx
+++ b/packages/jui/src/Tabs/2-Tabs.stories.tsx
@@ -1,6 +1,6 @@
 import { Meta, StoryObj } from "@storybook/react";
 import { MenuItemLayout, PlatformIcon } from "@intellij-platform/core";
-import React from "react";
+import React, { useEffect, useState } from "react";
 import { TabContentLayout, TabItem, TabsProps } from ".";
 import { Tabs } from "./Tabs";
 import { DOMProps } from "@react-types/shared";
@@ -53,12 +53,14 @@ export const DynamicItems: StoryObj<StoryProps> = {
 
 export const Overflow: StoryObj<StoryProps & { maxWidth: number }> = {
   render: ({ maxWidth = 800, ...props }) => {
-    const tabs = Array(10)
-      .fill(null)
-      .map((_, index) => ({
-        title: `Big tab title #${index}`,
-        icon: "nodes/folder",
-      }));
+    const [tabs, setTabs] = useState(
+      Array(10)
+        .fill(null)
+        .map((_, index) => ({
+          title: `Big tab title #${index}`,
+          icon: "nodes/folder",
+        }))
+    );
     return (
       <div style={{ maxWidth }}>
         <Tabs {...props} items={tabs}>
@@ -66,7 +68,7 @@ export const Overflow: StoryObj<StoryProps & { maxWidth: number }> = {
             const icon = <PlatformIcon icon={tab.icon} />;
             return (
               <TabItem
-                key={tab.title}
+                key={tabs.indexOf(tab)}
                 textValue={tab.title}
                 inOverflowMenu={
                   <MenuItemLayout content={tab.title} icon={icon} />
@@ -77,6 +79,45 @@ export const Overflow: StoryObj<StoryProps & { maxWidth: number }> = {
             );
           }}
         </Tabs>
+        <div style={{ marginTop: "1rem" }}>
+          <button
+            onClick={() => {
+              setTabs((tabs) => [
+                ...tabs,
+                {
+                  title: `Big tab title #${tabs.length}`,
+                  icon: "nodes/folder",
+                },
+              ]);
+            }}
+          >
+            Add tab
+          </button>
+          <button
+            onClick={() => {
+              setTabs((tabs) =>
+                tabs.map((tab, index) => {
+                  if (index === 4) {
+                    const title = tab.title;
+                    return {
+                      ...tab,
+                      title:
+                        title.replace(/ \(.*\)/, "") +
+                        ` ( edited - ${
+                          title.includes("short")
+                            ? "long long long long"
+                            : "short"
+                        })`,
+                    };
+                  }
+                  return tab;
+                })
+              );
+            }}
+          >
+            Change title of tab #4
+          </button>
+        </div>
       </div>
     );
   },
diff --git a/packages/jui/src/Tabs/Tab.tsx b/packages/jui/src/Tabs/Tab.tsx
index aad42aff..025cc9fb 100644
--- a/packages/jui/src/Tabs/Tab.tsx
+++ b/packages/jui/src/Tabs/Tab.tsx
@@ -2,12 +2,12 @@ import { useTab } from "@react-aria/tabs";
 import { TabListState } from "@react-stately/tabs";
 import { Node } from "@react-types/shared";
 import { StyledDefaultTab } from "./StyledDefaultTab";
-import React, { useEffect } from "react";
+import React, { ForwardedRef, forwardRef, RefObject, useEffect } from "react";
+import useForwardedRef from "@intellij-platform/core/utils/useForwardedRef";
 
 type TabProps<T extends object> = {
   state: TabListState<object>;
   item: Node<T>;
-  intersectionObserver: IntersectionObserver | null;
   /**
    * {@see TabsProps#focusable}
    */
@@ -19,16 +19,12 @@ type TabProps<T extends object> = {
   Component?: typeof StyledDefaultTab;
 };
 
-export const Tab = <T extends object>({
-  state,
-  item,
-  focusable,
-  active,
-  Component = StyledDefaultTab,
-  intersectionObserver,
-}: TabProps<T>): React.ReactElement => {
+export const Tab = forwardRef(function Tab<T extends object>(
+  { state, item, focusable, active, Component = StyledDefaultTab }: TabProps<T>,
+  forwardedRef: ForwardedRef<HTMLDivElement>
+): React.ReactElement {
   const { key, rendered } = item;
-  const ref = React.useRef(null);
+  const ref = useForwardedRef(forwardedRef);
   const {
     tabProps: {
       /**
@@ -41,7 +37,6 @@ export const Tab = <T extends object>({
   } = useTab({ key }, state, ref);
   const isSelected = state.selectedKey === key;
   const isDisabled = state.disabledKeys.has(key);
-  useIntersectionObserver(ref, intersectionObserver);
 
   return (
     <Component
@@ -55,19 +50,4 @@ export const Tab = <T extends object>({
       {rendered}
     </Component>
   );
-};
-
-function useIntersectionObserver(
-  ref: React.MutableRefObject<null>,
-  intersectionObserver: IntersectionObserver | null
-) {
-  useEffect(() => {
-    const element = ref.current;
-    if (element) {
-      intersectionObserver?.observe(element);
-      return () => {
-        intersectionObserver?.unobserve(element);
-      };
-    }
-  }, [intersectionObserver]);
-}
+});
diff --git a/packages/jui/src/Tabs/Tabs.tsx b/packages/jui/src/Tabs/Tabs.tsx
index 8d7e40fd..2b33943a 100644
--- a/packages/jui/src/Tabs/Tabs.tsx
+++ b/packages/jui/src/Tabs/Tabs.tsx
@@ -5,9 +5,10 @@ import { useTabListState } from "@react-stately/tabs";
 import { AriaTabListProps } from "@react-types/tabs";
 import { StyledHorizontalOverflowShadows } from "./StyledHorizontalOverflowShadows";
 import { TabsOverflowMenu } from "./TabsOverflowMenu";
-import { useCollectionOverflowObserver } from "./useCollectionOverflowObserver";
+import { useOverflowObserver } from "../utils/overflow-utils/useOverflowObserver";
 import { useHasOverflow } from "./useHasOverflow";
-import { styled, css } from "@intellij-platform/core/styled";
+import { css, styled } from "@intellij-platform/core/styled";
+import { notNull } from "@intellij-platform/core/utils/array-utils";
 import { StyledDefaultTab } from "./StyledDefaultTab";
 import { StyledDefaultTabs } from "./StyledDefaultTabs";
 import { Tab } from "./Tab";
@@ -120,8 +121,14 @@ export const Tabs = <T extends object>({
   const { tabListProps } = useTabList(props, state, ref);
 
   const { scrolledIndicatorProps, hasOverflow } = useHasOverflow({ ref });
-  const { overflowedKeys, intersectionObserver } =
-    useCollectionOverflowObserver(ref);
+  const { overflowedElements } = useOverflowObserver(ref);
+  const overflowedKeys = new Set(
+    overflowedElements
+      .map((element) =>
+        element instanceof HTMLElement ? element.dataset["key"] : null
+      )
+      .filter(notNull)
+  );
 
   useEffect(() => {
     if (!noScroll) {
@@ -162,7 +169,6 @@ export const Tabs = <T extends object>({
               focusable={focusable}
               active={active}
               Component={TabComponent}
-              intersectionObserver={intersectionObserver}
             />
           ))}
         </StyledTabList>
diff --git a/packages/jui/src/Tabs/useCollectionOverflowObserver.tsx b/packages/jui/src/Tabs/useCollectionOverflowObserver.tsx
deleted file mode 100644
index 78da9f70..00000000
--- a/packages/jui/src/Tabs/useCollectionOverflowObserver.tsx
+++ /dev/null
@@ -1,69 +0,0 @@
-import { Key, RefObject, useEffect, useState } from "react";
-
-/**
- * Given a ref to a scrollable container of collection items, returns the keys that are not completely visible and
- * are off view because of scroll. It relies on data-key property of observed elements.
- * @param scrollableItemsContainerRef
- * @param threshold
- */
-export function useCollectionOverflowObserver(
-  scrollableItemsContainerRef: RefObject<HTMLElement>,
-  { threshold = 0.9 }: { threshold?: number } = {}
-) {
-  const [intersectionObserver, setIntersectionObserver] =
-    useState<IntersectionObserver | null>(null);
-  const [overflowedKeys, setOverflowedKeys] = useState<Set<Key>>(new Set());
-
-  useEffect(() => {
-    const notScrollable =
-      scrollableItemsContainerRef.current?.scrollWidth ===
-      scrollableItemsContainerRef.current?.offsetWidth;
-    if (notScrollable && overflowedKeys.size > 0) {
-      setOverflowedKeys(new Set());
-    }
-  });
-
-  useEffect(() => {
-    const observer = new IntersectionObserver(
-      (entries) => {
-        const newHiddenKeys = entries
-          .map((entry) =>
-            !entry.isIntersecting && entry.target instanceof HTMLElement
-              ? entry.target.dataset.key
-              : undefined
-          )
-          .filter<string>((val): val is string => Boolean(val));
-        const newVisibleKeys = entries
-          .map((entry) =>
-            entry.isIntersecting && entry.target instanceof HTMLElement
-              ? entry.target.dataset.key
-              : null
-          )
-          .filter<string>((val): val is string => Boolean(val));
-
-        setOverflowedKeys(
-          (currentOverflowMenuKeys) =>
-            new Set(
-              [...currentOverflowMenuKeys]
-                .filter((key) => !newVisibleKeys.includes(`${key}`))
-                .concat(newHiddenKeys)
-            )
-        );
-      },
-      {
-        root: scrollableItemsContainerRef.current,
-        rootMargin: "0px",
-        threshold,
-      }
-    );
-    setIntersectionObserver(observer);
-    return () => {
-      observer.disconnect();
-    };
-  }, []);
-
-  return {
-    intersectionObserver,
-    overflowedKeys,
-  };
-}
diff --git a/packages/jui/src/ToolWindows/StyledToolWindowStripe.tsx b/packages/jui/src/ToolWindows/StyledToolWindowStripe.tsx
index 97c9dfb2..4dfeaec8 100644
--- a/packages/jui/src/ToolWindows/StyledToolWindowStripe.tsx
+++ b/packages/jui/src/ToolWindows/StyledToolWindowStripe.tsx
@@ -1,6 +1,7 @@
 import {
   STRIPE_BUTTON_CROSS_PADDING,
   STRIPE_BUTTON_LINE_HEIGHT,
+  StyledToolWindowStripeButton,
 } from "./StyledToolWindowStripeButton";
 import { Anchor, isHorizontalToolWindow, theOtherSide } from "./utils";
 import { css } from "styled-components";
@@ -21,11 +22,17 @@ const anchorStyles = ({
         flex-direction: row;
         width: 100%;
         min-height: ${preventCollapse ? minHeight : "fit-content"};
+        ${StyledToolWindowStripeButton} {
+          height: 1.25rem;
+        }
       `
     : css`
         flex-direction: column;
         height: 100%;
         min-width: ${preventCollapse ? minHeight : "fit-content"};
+        ${StyledToolWindowStripeButton} {
+          width: 1.25rem;
+        }
       `;
 const borderStyle = ({ anchor, theme }: { anchor: Anchor; theme: Theme }) =>
   css`border-${theOtherSide(anchor)}: 1px solid ${
diff --git a/packages/jui/src/ToolWindows/stories/components/FakeExecution.tsx b/packages/jui/src/ToolWindows/stories/components/FakeExecution.tsx
index 8e2d3197..05742cf2 100644
--- a/packages/jui/src/ToolWindows/stories/components/FakeExecution.tsx
+++ b/packages/jui/src/ToolWindows/stories/components/FakeExecution.tsx
@@ -74,7 +74,7 @@ export const FakeExecutionToolbar = ({
   execution: Execution;
   toggle: (executionId: string) => void;
 }) => (
-  <Toolbar hasBorder>
+  <Toolbar border="bottom">
     <IconButton onPress={() => toggle(id)}>
       <PlatformIcon icon={isRunning ? "actions/restart" : "actions/execute"} />
     </IconButton>
diff --git a/packages/jui/src/ToolWindowsImpl/DefaultToolWindowToolbarButton.tsx b/packages/jui/src/ToolWindowsImpl/DefaultToolWindowToolbarButton.tsx
index e601ecbe..0ebbfdcc 100644
--- a/packages/jui/src/ToolWindowsImpl/DefaultToolWindowToolbarButton.tsx
+++ b/packages/jui/src/ToolWindowsImpl/DefaultToolWindowToolbarButton.tsx
@@ -2,6 +2,7 @@ import React from "react";
 import { Shortcut, useAction } from "@intellij-platform/core/ActionSystem";
 import { ActionTooltip, TooltipTrigger } from "@intellij-platform/core/Tooltip";
 import { getActivateToolWindowActionId } from "./useToolWindowsActions";
+import styled from "styled-components";
 
 const getToolWindowNumberFromShortcut = (shortcut: Shortcut): number | null => {
   const num =
@@ -15,6 +16,10 @@ const getToolWindowNumberFromShortcut = (shortcut: Shortcut): number | null => {
   return null;
 };
 
+const StyledWrapper = styled.span`
+  display: flex;
+`;
+
 /**
  * Default UI for the toolbar button (aka. stripe button) of the tool window.
  * - Renders the title and icon for the tool window
@@ -42,7 +47,7 @@ export const DefaultToolWindowToolbarButton = ({
     <TooltipTrigger
       tooltip={<ActionTooltip actionName={title} shortcut={action?.shortcut} />}
     >
-      <span>
+      <StyledWrapper>
         {icon}
         &nbsp;
         {number != null && showNumber ? (
@@ -51,7 +56,7 @@ export const DefaultToolWindowToolbarButton = ({
           </>
         ) : null}
         {title}
-      </span>
+      </StyledWrapper>
     </TooltipTrigger>
   );
 };
diff --git a/packages/jui/src/ToolWindowsImpl/DefaultToolWindows.cy.tsx b/packages/jui/src/ToolWindowsImpl/DefaultToolWindows.cy.tsx
index d7b350f3..17f006bb 100644
--- a/packages/jui/src/ToolWindowsImpl/DefaultToolWindows.cy.tsx
+++ b/packages/jui/src/ToolWindowsImpl/DefaultToolWindows.cy.tsx
@@ -241,7 +241,7 @@ describe("DefaultToolWindowActions", () => {
 function WithActivateToolWindowKeymap({
   initialState,
 }: {
-  initialState?: { [id: string]: ToolWindowState };
+  initialState?: Record<string, ToolWindowState>;
 }) {
   return (
     <KeymapProvider
diff --git a/packages/jui/src/Toolbar/Toolbar.cy.tsx b/packages/jui/src/Toolbar/Toolbar.cy.tsx
new file mode 100644
index 00000000..5ec74a42
--- /dev/null
+++ b/packages/jui/src/Toolbar/Toolbar.cy.tsx
@@ -0,0 +1,251 @@
+import React, { useState } from "react";
+import { composeStories } from "@storybook/react";
+import { IconButton, PlatformIcon, Toolbar } from "@intellij-platform/core";
+
+import * as stories from "./Toolbar.stories";
+
+const {
+  Horizontal,
+  OverflowFittedInViewport,
+  FirstItemDivider,
+  LastItemDivider,
+  HorizontalOverflow,
+  Vertical,
+  VerticalOverflow,
+  OverflowWrap,
+} = composeStories(stories);
+
+describe("Toolbar", () => {
+  it("looks good", () => {
+    cy.viewport(320, 800);
+    cy.mount(
+      <div
+        style={{
+          display: "flex",
+          gap: "1rem",
+          alignItems: "center",
+          flexWrap: "wrap",
+          padding: "1rem",
+        }}
+      >
+        <Horizontal />
+        <Vertical />
+        <HorizontalOverflow containerWidth={150} />
+        <VerticalOverflow containerHeight={150} />
+        <FirstItemDivider /> {/* hides the first item if it's a divider*/}
+        <LastItemDivider /> {/* hides the last item if it's a divider*/}
+        <OverflowWrap />
+        <OverflowWrap orientation="horizontal" />
+      </div>
+    );
+    matchImageSnapshot("Toolbar-looks-good");
+  });
+
+  it("keeps overflowed buttons accessible", () => {
+    cy.mount(<HorizontalOverflow />);
+    // 8 toolbar buttons plus one for showing overflow popup
+    cy.findAllByRole("button").should("have.length", 9);
+  });
+
+  it("shows hidden children in an overflow menu, when orientation is vertical", () => {
+    cy.mount(
+      <VerticalOverflow
+        containerHeight={
+          /* to make the first overflowed element be a separator, which should be hidden */
+          180
+        }
+      />
+    );
+    checkOverflowPopupIsHidden();
+    cy.findByRole("toolbar").realHover({ position: "bottom" });
+    checkOverflowPopupIsVisible();
+    matchImageSnapshot("Toolbar-vertical-overflow");
+    cy.get("body").realMouseMove(200, 200, { scrollBehavior: false });
+    checkOverflowPopupIsHidden();
+  });
+
+  it("shows hidden children in an overflow menu, when orientation is horizontal", () => {
+    cy.mount(<HorizontalOverflow containerWidth={100} />);
+    checkOverflowPopupIsHidden();
+    cy.findByRole("toolbar").realHover({ position: "right" });
+    checkOverflowPopupIsVisible();
+    matchImageSnapshot("Toolbar-horizontal-overflow");
+    cy.get("body").realMouseMove(200, 200, { scrollBehavior: false });
+    checkOverflowPopupIsHidden();
+  });
+
+  it("fits the overflow popup within the viewport", () => {
+    cy.mount(<OverflowFittedInViewport containerWidth={100} />);
+    cy.findByRole("toolbar").realHover({ position: "right" });
+    matchImageSnapshot("Toolbar-horizontal-overflow-fitted-into-viewport");
+  });
+
+  it("handles very small width", () => {
+    cy.mount(<HorizontalOverflow containerWidth={20} />);
+    // all buttons should be hidden
+    cy.findAllByRole("button").filter(":visible").should("have.length", 1);
+
+    // overflow button should still be visible
+    cy.findByRole("toolbar").realHover({ position: "right" });
+    // and it should work
+    cy.findAllByRole("button")
+      .should("be.visible")
+      .and(
+        "have.length",
+        9 /* 8 buttons in the overflow popup + overflow button in the toolbar*/
+      );
+  });
+
+  it("opens the overflow popup even when half-overflowed hidden elements are hovered", () => {
+    cy.mount(<VerticalOverflow containerHeight={150} />);
+    // wait for the overflow handling to settle
+    cy.findAllByRole("button").filter(":visible").should("have.length", 4);
+
+    // Moving mouse to the area above the overflow arrow button, and on the half-overflowed hidden last button
+    cy.findByRole("button", { name: "Delete" }).realMouseMove(0, 6, {
+      position: "bottom",
+      scrollBehavior: false,
+    });
+    checkOverflowPopupIsVisible();
+
+    // moving up to visible buttons should close the overflow
+    cy.findByRole("button", { name: "Delete" }).realMouseMove(1, 0, {
+      position: "center",
+      scrollBehavior: false,
+    });
+    checkOverflowPopupIsHidden();
+
+    // Moving mouse again to the area above the overflow arrow button, and on the half-overflowed hidden last button
+    cy.findByRole("button", { name: "Delete" }).realMouseMove(1, 6, {
+      position: "bottom",
+      scrollBehavior: false,
+    });
+    checkOverflowPopupIsVisible();
+
+    // Now moving mouse onto the overflow popup. It should not close the popup.
+    Array(20)
+      .fill(null)
+      .forEach((_, index) => {
+        cy.findByRole("button", { name: "Delete" }).realMouseMove(-2, index, {
+          position: "bottomRight",
+          scrollBehavior: false,
+        });
+      });
+    checkOverflowPopupIsVisible();
+
+    // Moving mouse again to the area above the overflow arrow button, and on the half-overflowed hidden last button
+    cy.findByRole("button", { name: "Delete" }).realMouseMove(1, 6, {
+      position: "bottom",
+      scrollBehavior: false,
+    });
+    checkOverflowPopupIsVisible();
+
+    // Moving mouse out of the toolbar without moving to the overflow popup first should also close the overflow popup.
+    cy.findByRole("button", { name: "Delete" }).realMouseMove(200, 6, {
+      position: "bottom",
+      scrollBehavior: false,
+    });
+    checkOverflowPopupIsHidden();
+  });
+
+  it("prevents half-overflowed hidden elements from capturing mouse events", () => {
+    const onMouseEnter = cy.stub();
+    cy.mount(
+      <VerticalOverflow containerHeight={85}>
+        <IconButton aria-label="Hide">
+          <PlatformIcon icon="actions/arrowCollapse" />
+        </IconButton>
+        <IconButton aria-label="Add">
+          <PlatformIcon icon="general/add" />
+        </IconButton>
+        <span onMouseEnter={onMouseEnter}>
+          <IconButton aria-label="Delete">
+            <PlatformIcon icon="actions/gc" />
+          </IconButton>
+        </span>
+        <IconButton aria-label="Checkout">
+          <PlatformIcon icon="actions/checkOut" />
+        </IconButton>
+      </VerticalOverflow>
+    );
+
+    // wait for the overflow handling to settle
+    cy.findAllByRole("button").filter(":visible").should("have.length", 2);
+
+    // Moving mouse to the area above the overflow arrow button, and on the half-overflowed hidden last button
+    cy.findByRole("button", { name: "Delete" }).realMouseMove(0, 1, {
+      position: "top",
+      scrollBehavior: false,
+    });
+
+    cy.wrap(onMouseEnter).should("not.be.called");
+  });
+
+  it("works as expected when orientation changes", () => {
+    const Example = () => {
+      const [orientation, setOrientation] = useState<"vertical" | "horizontal">(
+        "horizontal"
+      );
+      const changeOrientation = () =>
+        setOrientation((orientation) =>
+          orientation === "horizontal" ? "vertical" : "horizontal"
+        );
+      return (
+        <>
+          <button onClick={changeOrientation}>Change Orientation</button>
+          <div
+            style={{ [orientation === "vertical" ? "height" : "width"]: 50 }}
+          >
+            <Toolbar orientation={orientation}>
+              <IconButton aria-label="Hide">
+                <PlatformIcon icon="actions/arrowCollapse" />
+              </IconButton>
+              <IconButton aria-label="Add">
+                <PlatformIcon icon="general/add" />
+              </IconButton>
+              <IconButton aria-label="Checkout">
+                <PlatformIcon icon="actions/checkOut" />
+              </IconButton>
+            </Toolbar>
+          </div>
+        </>
+      );
+    };
+    cy.mount(<Example />);
+
+    cy.findByRole("toolbar")
+      .findByRole("button", { name: "Add" })
+      .should("be.hidden");
+
+    cy.findByRole("button", { name: "Change Orientation" }).click();
+
+    cy.findByRole("toolbar")
+      .findByRole("button", { name: "Add" })
+      .should("be.hidden");
+  });
+});
+
+function checkOverflowPopupIsVisible(buttonNameToCheckBasedOn = "Expand All") {
+  // checking based on button visibility instead of existence, not to mix functionality with accessibility testing
+  cy.findAllByRole("button", { name: buttonNameToCheckBasedOn })
+    .should("be.visible")
+    .and("have.length.above", 0);
+}
+
+function checkOverflowPopupIsHidden(buttonNameToCheckBasedOn = "Expand All") {
+  // checking based on button visibility instead of existence, not to mix functionality with accessibility testing
+  cy.findAllByRole("button", { name: buttonNameToCheckBasedOn }).should(
+    "not.be.visible"
+  );
+}
+
+function matchImageSnapshot(snapshotsName: string) {
+  // with percy
+  cy.get("[data-loading-icon]").should("not.exist");
+  cy.percySnapshot(snapshotsName);
+
+  // or local snapshot testing
+  // cy.document().toMatchImageSnapshot({
+  //   name: snapshotsName,
+  // });
+}
diff --git a/packages/jui/src/Toolbar/Toolbar.stories.tsx b/packages/jui/src/Toolbar/Toolbar.stories.tsx
new file mode 100644
index 00000000..f51e6a18
--- /dev/null
+++ b/packages/jui/src/Toolbar/Toolbar.stories.tsx
@@ -0,0 +1,241 @@
+import React from "react";
+import { ArgTypes, Meta, StoryObj } from "@storybook/react";
+import {
+  ActionTooltip,
+  IconButton,
+  Item,
+  Menu,
+  MenuTrigger,
+  PlatformIcon,
+  styled,
+  ToolbarSeparator,
+  TooltipTrigger,
+} from "@intellij-platform/core";
+import { Toolbar, ToolbarProps as OriginalToolbarProps } from "./Toolbar";
+
+// The way overflowBehavior is defined on toolbar props breaks how composeStories infers the type of stories.
+// This is a patch to solve that type issue. Would be nicer to isolate the patch to Toolbar.cy.tsx, but couldn't figure
+// a good way of doing so.
+type ToolbarProps = Omit<OriginalToolbarProps, "overflowBehavior"> & {
+  overflowBehavior: "wrap" | "popup";
+};
+
+export default {
+  title: "Components/Toolbar",
+  component: Toolbar,
+  args: {
+    children: (
+      <>
+        <IconButton aria-label="Hide">
+          <PlatformIcon icon="actions/arrowCollapse" />
+        </IconButton>
+        <ToolbarSeparator />
+        <IconButton aria-label="Add">
+          <PlatformIcon icon="general/add" />
+        </IconButton>
+        <IconButton aria-label="Checkout">
+          <PlatformIcon icon="actions/checkOut" />
+        </IconButton>
+        <IconButton aria-label="Delete">
+          <PlatformIcon icon="actions/gc" />
+        </IconButton>
+        <IconButton aria-label="Show Diff">
+          <PlatformIcon icon="actions/diff" />
+        </IconButton>
+        <IconButton aria-label="Find">
+          <PlatformIcon icon="actions/find" />
+        </IconButton>
+        <ToolbarSeparator />
+        <IconButton aria-label="Expand All">
+          <PlatformIcon icon="actions/expandall" />
+        </IconButton>
+        <IconButton aria-label="Collapse All">
+          <PlatformIcon icon="actions/collapseall" />
+        </IconButton>
+      </>
+    ),
+  },
+  argTypes: {},
+} as Meta<ToolbarProps>;
+
+const render = (props: ToolbarProps) => {
+  return <Toolbar {...props}></Toolbar>;
+};
+
+export const Horizontal: StoryObj<ToolbarProps> = {
+  render,
+  args: {
+    orientation: "horizontal",
+  },
+};
+
+const sizeArgType: ArgTypes[string] = {
+  control: {
+    type: "range",
+    min: 0,
+    max: 300,
+    step: 10,
+  },
+};
+
+type HorizontalOverflowProps = ToolbarProps & { containerWidth: number };
+type VerticalOverflowProps = ToolbarProps & { containerHeight: number };
+export const HorizontalOverflow: StoryObj<HorizontalOverflowProps> = {
+  render: ({
+    containerWidth = 140,
+    children,
+    ...props
+  }: HorizontalOverflowProps) => (
+    <div style={{ width: containerWidth }}>
+      <Toolbar {...props}>{children}</Toolbar>
+    </div>
+  ),
+  args: {
+    orientation: "horizontal",
+  },
+  argTypes: {
+    containerWidth: sizeArgType,
+  },
+};
+
+export const OverflowWrap: StoryObj<HorizontalOverflowProps> = {
+  ...HorizontalOverflow,
+  args: {
+    ...HorizontalOverflow.args,
+    overflowBehavior: "wrap",
+  },
+};
+
+export const Vertical: StoryObj<ToolbarProps> = {
+  render,
+  args: {
+    orientation: "vertical",
+  },
+};
+export const VerticalOverflow: StoryObj<VerticalOverflowProps> = {
+  render: ({
+    containerHeight = 140,
+    children,
+    ...props
+  }: VerticalOverflowProps) => (
+    <div style={{ height: containerHeight }}>
+      <Toolbar {...props}>{children}</Toolbar>
+    </div>
+  ),
+  args: {
+    orientation: "vertical",
+  },
+  argTypes: {
+    containerHeight: sizeArgType,
+  },
+};
+export const OverflowFittedInViewport: StoryObj<HorizontalOverflowProps> = {
+  render: (props: HorizontalOverflowProps, context: any) => (
+    <div style={{ display: "flex", justifyContent: "end", paddingRight: 20 }}>
+      {HorizontalOverflow.render?.(props as any, context)}
+    </div>
+  ),
+  args: {
+    orientation: "horizontal",
+  },
+  argTypes: {
+    containerWidth: sizeArgType,
+  },
+};
+
+const StyledDropdownButton = styled.button`
+  all: unset;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding-left: 0.25rem;
+  background: ${({ theme }) => theme.color("ComboBoxButton.background")};
+  color: ${({ theme }) => theme.color("ComboBox.disabledForeground")};
+  &:hover {
+    color: ${({ theme }) => theme.color("*.foreground")};
+  }
+`;
+
+export const OverflowWithCustomItems: StoryObj<HorizontalOverflowProps> = {
+  render: ({ containerWidth = 140, ...props }: HorizontalOverflowProps) => (
+    <div style={{ width: containerWidth }}>
+      <Toolbar {...props}>
+        <MenuTrigger
+          renderMenu={({ menuProps }) => (
+            <Menu {...menuProps}>
+              <Item>Select...</Item>
+              <Item>Last 24 hours</Item>
+              <Item>Last 7 days</Item>
+            </Menu>
+          )}
+        >
+          {(props, ref) => (
+            <StyledDropdownButton {...props} ref={ref}>
+              Date <PlatformIcon icon="general/arrowDownSmall.svg" />
+            </StyledDropdownButton>
+          )}
+        </MenuTrigger>
+        <MenuTrigger
+          renderMenu={({ menuProps }) => (
+            <Menu {...menuProps}>
+              <Item>Select...</Item>
+              <Item>me</Item>
+            </Menu>
+          )}
+        >
+          {(props, ref) => (
+            <StyledDropdownButton {...props} ref={ref}>
+              User <PlatformIcon icon="general/arrowDownSmall.svg" />
+            </StyledDropdownButton>
+          )}
+        </MenuTrigger>
+        <MenuTrigger
+          renderMenu={({ menuProps }) => (
+            <Menu {...menuProps}>
+              <Item>Select in...</Item>
+              <Item>Select in Tree...</Item>
+            </Menu>
+          )}
+        >
+          {(props, ref) => (
+            <StyledDropdownButton {...props} ref={ref}>
+              Paths <PlatformIcon icon="general/arrowDownSmall.svg" />
+            </StyledDropdownButton>
+          )}
+        </MenuTrigger>
+        <ToolbarSeparator />
+        <TooltipTrigger
+          tooltip={<ActionTooltip actionName={"Open New Git Log Tab"} />}
+        >
+          <IconButton aria-label="Checkout">
+            <PlatformIcon icon="actions/openNewTab.svg" />
+          </IconButton>
+        </TooltipTrigger>
+      </Toolbar>
+    </div>
+  ),
+  args: {
+    orientation: "horizontal",
+  },
+  argTypes: {
+    containerWidth: sizeArgType,
+  },
+};
+
+export const LastItemDivider: StoryObj<ToolbarProps> = {
+  render: ({ children, ...props }: ToolbarProps) => (
+    <Toolbar {...props}>
+      {children}
+      <ToolbarSeparator />
+    </Toolbar>
+  ),
+};
+
+export const FirstItemDivider: StoryObj<ToolbarProps> = {
+  render: ({ children, ...props }: ToolbarProps) => (
+    <Toolbar {...props}>
+      <ToolbarSeparator />
+      {children}
+    </Toolbar>
+  ),
+};
diff --git a/packages/jui/src/Toolbar/Toolbar.tsx b/packages/jui/src/Toolbar/Toolbar.tsx
index 1058967c..a10b4b10 100644
--- a/packages/jui/src/Toolbar/Toolbar.tsx
+++ b/packages/jui/src/Toolbar/Toolbar.tsx
@@ -1,100 +1,389 @@
-import React, { useContext } from "react";
-import { Theme } from "@intellij-platform/core/Theme";
+import React, {
+  CSSProperties,
+  MouseEvent,
+  useContext,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
 
-import { StyledIconButton } from "../IconButton";
 import { styled } from "../styled";
 import {
   StyledHorizontalSeparator,
+  StyledSeparator,
   StyledVerticalSeparator,
 } from "../StyledSeparator";
+import { useOverflowObserver } from "@intellij-platform/core/utils/overflow-utils/useOverflowObserver";
+import { PlatformIcon } from "@intellij-platform/core/Icon";
+import { Overlay, useOverlayPosition } from "@react-aria/overlays";
+import { StyledPopupContainer } from "@intellij-platform/core/Popup/Popup";
+import { css } from "styled-components";
+import { mergeProps } from "@react-aria/utils";
 
-interface ToolbarProps {
+type ToolbarBorderProp =
+  | true
+  | "horizontal"
+  | "vertical"
+  | "bottom"
+  | "top"
+  | "left"
+  | "right";
+
+export type ToolbarProps = {
+  children: React.ReactNode;
   orientation?: "vertical" | "horizontal";
-  /**
-   * Whether to include a border to the bottom/right the toolbar, or not.
-   */
-  hasBorder?: boolean;
-}
-const StyledToolbar = styled.div`
-  display: flex;
-`;
+  border?: ToolbarBorderProp;
+  style?: CSSProperties;
+  className?: string;
+} & (
+  | {
+      orientation: "vertical";
+    }
+  | {
+      orientation?: "horizontal";
+      /**
+       * Defines how the toolbar should handle its children when there is not enough room
+       * to fit all:
+       * - popup: the overflowed children will be hidden behind a show more arrow icon that
+       *   shows the rest of the items in a popup.
+       * - wrap: children will be wrapped so that they fit the available width/height
+       **/
+      overflowBehavior?: "popup" | "wrap";
+    }
+);
 
-const getBorder = ({
-  theme,
-  hasBorder,
-}: {
-  theme: Theme;
-  hasBorder?: boolean;
-}) =>
-  hasBorder
-    ? `1px solid ${theme.color(
+const borderStyle = ({ border }: { border?: ToolbarBorderProp }) =>
+  border &&
+  css`
+    border-style: solid;
+    border-color: ${({ theme }) =>
+      theme.color(
         "Borders.color",
         theme.dark ? "rgb(50,50,50)" : "rgb(192, 192, 192)"
-      )}`
-    : "none";
-const StyledHorizontalToolbar = styled(StyledToolbar)<{
-  hasBorder?: boolean;
+      )};
+    border-width: ${border === true ? "1px" : borderPropToCssProp[border]};
+  `;
+
+const StyledToolbar = styled.div<{
+  border?: ToolbarBorderProp;
 }>`
-  padding: 2px;
-  border-bottom: ${getBorder};
-  ${StyledHorizontalSeparator} {
-    margin: 1px 2px;
-  }
+  display: inline-flex;
+  box-sizing: border-box;
+  overflow: hidden;
   // NOTE: in the original implementation, there is no empty space between buttons, but buttons have kind of an
   // invisible left padding, which is mouse-intractable, but doesn't visually seem a part of the button.
   // Although implementable, it didn't seem necessary to follow the exact same thing. Margin should be fine.
-  ${StyledIconButton} {
-    margin: 0 2px 0 2px;
+  gap: 4px;
+  ${borderStyle}
+  ${StyledSeparator}:first-child {
+    display: none;
+  }
+  ${StyledSeparator}:last-child {
+    display: none;
   }
 `;
 
-const StyledVerticalToolbar = styled(StyledToolbar)<{
-  hasBorder?: boolean;
-}>`
-  flex-direction: column;
-  padding: 0 2px;
-  border-right: ${getBorder};
+const borderPropToCssProp: Record<
+  Exclude<ToolbarBorderProp, boolean>,
+  CSSProperties["borderWidth"]
+> = {
+  top: "1px 0 0 0",
+  bottom: "0 0 1px 0",
+  right: "0 1px 0 0",
+  left: "0 0 0 1px",
+  horizontal: "0 1px",
+  vertical: "1px 0",
+};
+
+const SIDE_PADDING = 3;
+const END_PADDING = 4;
+
+const StyledShowMoreButton = styled.button`
+  all: unset;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  ${borderStyle};
+`;
+
+const StyledHorizontalToolbar = styled(StyledToolbar)`
+  padding: ${SIDE_PADDING}px ${END_PADDING}px;
+  max-width: 100%;
+  /*noinspection CssInvalidPropertyValue*/
+  max-width: -webkit-fill-available;
+  ${StyledHorizontalSeparator} {
+    margin: 1px 0;
+  }
+  ${StyledShowMoreButton} {
+    margin-right: -${END_PADDING}px;
+  }
+`;
 
+const StyledVerticalToolbar = styled(StyledToolbar)`
+  flex-direction: column;
+  max-height: 100%;
+  /*noinspection CssInvalidPropertyValue*/
+  max-height: -webkit-fill-available;
+  padding: ${END_PADDING}px ${SIDE_PADDING}px;
   ${StyledVerticalSeparator} {
-    margin: 4px 1px;
+    margin: 0 1px;
   }
-  ${StyledIconButton} {
-    margin: 2px 0 1px 0;
+  ${StyledShowMoreButton} {
+    margin-bottom: -${END_PADDING}px;
   }
 `;
 
+const StyledToolbarContent = styled.div<{ wrap?: boolean }>`
+  box-sizing: inherit;
+  display: inherit;
+  flex-direction: inherit;
+  flex-wrap: ${({ wrap }) => (wrap ? "wrap" : "nowrap")};
+  gap: inherit;
+  max-height: inherit;
+  max-width: inherit;
+  min-height: 0;
+  min-width: 0;
+`;
 // This can be used in other places if use-cases are raised for keeping orientation in the context.
 const OrientationContext = React.createContext<"horizontal" | "vertical">(
   "horizontal"
 );
 
 /**
- * Remaining features:
- * - overflow behaviour:
- *   - wrap. like main action toolbar.
- *   - hidden, shown by arrow. Similar to actions in Git->Log. Note that the behaviour for horizontal and vertical
- *     modes are different apparently.
+ * ## Toolbar API/Implementation notes
+ *
+ * ### Handling Overflow
+ *
+ * Handling the overflow popup on DOM-level, allows for a simple and flexible implementation that doesn't
+ * require any coupling between Toolbar and components like IconButton. Other components can also similarly be
+ * rendered inside toolbar without adopting any specific API. It's worth noting that any generic approach based
+ * on children react nodes instead of children DOM nodes will have many edge cases and will involve assumptions
+ * that will limit the API of toolbar. Also, any approach based on moving dom nodes to the overflow popup will
+ * conflict with React owning the DOM.
+ *
+ * #### Assumption
+ *
+ * Since the overflow popup renders the same `children`, and items in the toolbar and popup overflow are made
+ * visible/hidden based on the index of DOM nodes, it's important than children deterministically results in the
+ * same dom structure. i.e. if a component in children randomly renders different number of root dom nodes in
+ * each render, it can cause issues in hiding/showing elements.
+ *
+ * ### Orientation
+ * A few reasons for not having separate `HorizontalToolbar` and `VerticalToolbar` components instead of `Toolbar` with
+ * `orientation` prop:
+ * - From usage side, a single `Toolbar` component is considered a more discoverable API.
+ * - Separate components would require abstracting common parts which unnecessarily adds to complexity.
+ *   The amount of branching to handle the differences is considered ok, at the current state of the component.
+ */
+
+/**
+ * @description
+ * A toolbar is a container for {@link IconButton} and similar UI components.
+ *
+ * ## Features:
+ * - A toolbar can be horizontal or vertical
+ * - When there is not enough space for all children, toolbar shows an arrow icon, which shows the overflowing
+ *   items in a popup, upon mouseover.
+ *   Optionally, overflow can be wrapped into multiple lines, in horizontal toolbars.
+ *
+ * @example
+ * <Toolbar>
+ *   <IconButton aria-label="Show Diff">
+ *     <PlatformIcon icon="actions/diff" />
+ *   </IconButton>
+ *   </Toolbar>
  */
 export const Toolbar: React.FC<ToolbarProps> = ({
+  border,
   orientation = "horizontal",
-  hasBorder = false,
-  children,
+  ...props
 }): React.ReactElement => {
+  const overflowBehavior =
+    orientation === "horizontal" && "overflowBehavior" in props
+      ? props.overflowBehavior
+      : null;
+  const rootProps = { style: props.style, className: props.className };
+  const ref = useRef<HTMLDivElement>(null);
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const showMoreButtonRef = useRef<HTMLButtonElement>(null);
+  const StyledToolbar =
+    orientation === "horizontal"
+      ? StyledHorizontalToolbar
+      : StyledVerticalToolbar;
+  const { overflowedElements } = useOverflowObserver(ref, { threshold: 0.85 });
+  const [isOverflowPopupVisible, setOverflowPopupVisible] = useState(false);
+  const [popupHeight, setPopupHeight] = useState(30);
+  const [firstOverflowedChildIndex, setFirstOverflowedChildIndex] =
+    useState<number>(-1);
+  const firstOverflowedChildRef = useRef<HTMLElement | undefined>();
+
+  useLayoutEffect(() => {
+    if (ref.current) {
+      const childElements = [...ref.current.children].filter(
+        (node): node is HTMLElement => node instanceof HTMLElement
+      );
+      childElements.forEach((childElement) => {
+        applyChildStyles(
+          childElement,
+          overflowedElements.includes(childElement)
+        );
+      });
+      const index = childElements.findIndex((child) =>
+        overflowedElements.includes(child)
+      );
+      setFirstOverflowedChildIndex(index);
+      firstOverflowedChildRef.current = childElements[index];
+    }
+  }, [overflowedElements]);
+
+  useLayoutEffect(() => {
+    if (overlayRef.current && popupHeight !== overlayRef.current.offsetHeight) {
+      setPopupHeight(overlayRef.current.offsetHeight);
+    }
+  });
+
+  const { overlayProps } = useOverlayPosition({
+    isOpen: isOverflowPopupVisible,
+    placement: "bottom left",
+    offset:
+      // in lack of positioning options for aligning bottom and left of of the overflow popup with the bottom and left
+      // of the toolbar itself, we have to measure the popup height, and use offset to achieve the same
+      orientation === "horizontal"
+        ? -popupHeight + SIDE_PADDING + 1
+        : -popupHeight + 1,
+    crossOffset:
+      orientation === "horizontal" ? -(SIDE_PADDING + 2) : -(SIDE_PADDING + 1),
+    containerPadding: 0,
+    shouldFlip: false,
+    targetRef: orientation === "horizontal" ? ref : showMoreButtonRef,
+    overlayRef: overlayRef,
+    onClose: () => {
+      setOverflowPopupVisible(false);
+    },
+  });
+
+  const showOverflowPopup = () => {
+    setOverflowPopupVisible(true);
+  };
+
+  const toolbarProps = {
+    onMouseMove: (event: MouseEvent) => {
+      const firstOverflowedElement = firstOverflowedChildRef.current;
+      if (!firstOverflowedElement) {
+        return;
+      }
+      const shouldShow =
+        orientation === "vertical"
+          ? event.clientY > firstOverflowedElement.getBoundingClientRect().top
+          : event.clientX > firstOverflowedElement.getBoundingClientRect().left;
+      if (shouldShow !== isOverflowPopupVisible) {
+        setOverflowPopupVisible(shouldShow);
+      }
+    },
+    onMouseLeave: () => {
+      if (isOverflowPopupVisible) {
+        setOverflowPopupVisible(false);
+      }
+    },
+  };
+  const toolbarOverflowPopupProps = {
+    onMouseEnter: () => setOverflowPopupVisible(true),
+    onMouseLeave: () => setOverflowPopupVisible(false),
+  };
   return (
     <OrientationContext.Provider value={orientation}>
-      {orientation === "horizontal" ? (
-        <StyledHorizontalToolbar hasBorder={hasBorder}>
-          {children}
-        </StyledHorizontalToolbar>
-      ) : (
-        <StyledVerticalToolbar hasBorder={hasBorder}>
-          {children}
-        </StyledVerticalToolbar>
+      <StyledToolbar
+        border={border}
+        {...mergeProps(rootProps, toolbarProps)}
+        role="toolbar"
+      >
+        <StyledToolbarContent
+          ref={ref}
+          role="presentation"
+          wrap={overflowBehavior === "wrap"}
+        >
+          {props.children}
+        </StyledToolbarContent>
+        {overflowedElements.length > 0 && (
+          <StyledShowMoreButton
+            ref={showMoreButtonRef}
+            onMouseEnter={showOverflowPopup}
+          >
+            <PlatformIcon icon="ide/link" />
+          </StyledShowMoreButton>
+        )}
+      </StyledToolbar>
+      {isOverflowPopupVisible && overflowedElements.length > 0 && (
+        // Maybe more accessible to reuse the entire Popup here? it would require more flexible API to handle mouseleave though
+        // Note: we could also render the whole toolbar with the same props and only orientation being overwritten,
+        // but it has the risk of infinite overlay opening in some edge cases, and that level of generality doesn't
+        // seem to be necessary, at least at the moment.
+        <OrientationContext.Provider value="horizontal">
+          <Overlay>
+            <StyledPopupContainer
+              ref={overlayRef}
+              {...mergeProps(overlayProps, toolbarOverflowPopupProps)}
+            >
+              <ToolbarInOverlay
+                border
+                firstVisibleIndex={
+                  orientation === "vertical"
+                    ? firstOverflowedChildIndex
+                    : undefined
+                }
+              >
+                {props.children}
+              </ToolbarInOverlay>
+            </StyledPopupContainer>
+          </Overlay>
+        </OrientationContext.Provider>
       )}
     </OrientationContext.Provider>
   );
 };
 
+const previousStylesMap = new WeakMap<
+  HTMLElement,
+  Partial<CSSStyleDeclaration>
+>();
+function applyChildStyles(element: HTMLElement, shouldHide: boolean) {
+  /**
+   * The hidden styles should be in a way that the hidden element:
+   * - occupies its space in the document layout.
+   * - doesn't capture mouse events. (e.g. a half-overflowing hidden element shouldn't show tooltip)
+   * - remains accessible to screen readers.
+   */
+  if (shouldHide) {
+    if (!previousStylesMap.has(element)) {
+      const { opacity, pointerEvents } = element.style;
+      previousStylesMap.set(element, { opacity, pointerEvents });
+    }
+    element.style.opacity = "0";
+    element.style.pointerEvents = "none";
+  } else {
+    const previousStyles = previousStylesMap.get(element);
+    previousStylesMap.delete(element);
+
+    element.style.opacity = previousStyles?.opacity || "";
+    element.style.pointerEvents = previousStyles?.pointerEvents || "";
+  }
+}
+
+const ToolbarInOverlay = styled(StyledHorizontalToolbar)<{
+  firstVisibleIndex?: number;
+}>`
+  ${({ firstVisibleIndex }) =>
+    firstVisibleIndex &&
+    css`
+      ${StyledSeparator}:nth-child(${firstVisibleIndex}) {
+        display: none;
+      }
+      > :not(:nth-child(${firstVisibleIndex}) ~ *) {
+        display: none;
+      }
+    `};
+`;
+
 /**
  * Separator to be used between items in a toolbar.
  */
diff --git a/packages/jui/src/utils/overflow-utils/OverflowObserver.ts b/packages/jui/src/utils/overflow-utils/OverflowObserver.ts
new file mode 100644
index 00000000..93bee4fa
--- /dev/null
+++ b/packages/jui/src/utils/overflow-utils/OverflowObserver.ts
@@ -0,0 +1,133 @@
+import { notNull } from "@intellij-platform/core/utils/array-utils";
+
+export interface OverflowObserverRecord {
+  target: Element;
+  overflowedElements: Element[];
+  previouslyOverflowedElements: Element[];
+}
+
+export type OverflowObserverCallback = (
+  change: OverflowObserverRecord,
+  observer: OverflowObserver
+) => void;
+
+/**
+ * Allows observing the list of overflowing children of a given target element.
+ * An `IntersectionObserver` is created for each target to observe the intersection between the target and each child
+ * element. The child elements are observed/unobserved by the intersection observer as they are added/removed to the
+ * DOM, which is observed using a `MutationObserver`.
+ * `IntersectionObserver` options such as `rootMargin` are supported, to fine tune what should be considered as
+ * overflowed.
+ *
+ * TODO: add a takeRecords method to allow processing pending mutations before disconnect
+ * TODO: maybe add direction option?
+ *
+ */
+export class OverflowObserver {
+  private mutationObserver: MutationObserver;
+  private data: Map<
+    Element,
+    {
+      intersectionObserver: IntersectionObserver;
+      currentOverflowElements: Element[];
+    }
+  > = new Map();
+
+  constructor(private callback: OverflowObserverCallback) {
+    this.mutationObserver = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        const target = mutation.target;
+        if (!(target instanceof Element)) {
+          return;
+        }
+        mutation.removedNodes.forEach((node) => {
+          if (node instanceof Element) {
+            this.data.get(target)?.intersectionObserver.unobserve(node);
+          }
+        });
+        mutation.addedNodes.forEach((node) => {
+          if (node instanceof Element) {
+            this.data.get(target)?.intersectionObserver.observe(node);
+          }
+        });
+      });
+    });
+  }
+
+  observe(target: Element, options: Omit<IntersectionObserverInit, "root">) {
+    this.data.get(target)?.intersectionObserver.disconnect();
+
+    const intersectionObserver = new IntersectionObserver(
+      (entries) => {
+        const data = this.data.get(target);
+        const newHiddenElements = entries
+          .map((entry) =>
+            !entry.isIntersecting && entry.target instanceof Element
+              ? entry.target
+              : undefined
+          )
+          .filter(notNull);
+        const newVisibleElements = entries
+          .map((entry) =>
+            entry.isIntersecting && entry.target instanceof Element
+              ? entry.target
+              : null
+          )
+          .filter(notNull);
+
+        //  Also cover this in Toolbar with a test case
+        const previouslyOverflowedElements =
+          data?.currentOverflowElements || [];
+        const overflowedElements = previouslyOverflowedElements
+          .filter((element) => !newVisibleElements.includes(element))
+          .concat(newHiddenElements)
+          .filter((element) => {
+            // In some cases some elements may be hidden by some styles (e.g. the first/last separator in a toolbar).
+            // It doesn't make sense to report them as overflowed.
+            const isHidden =
+              element instanceof HTMLElement &&
+              element.offsetWidth === 0 &&
+              element.offsetHeight === 0;
+            return !isHidden;
+          });
+        this.callback(
+          {
+            previouslyOverflowedElements,
+            overflowedElements: overflowedElements,
+            target,
+          },
+          this
+        );
+        if (data) {
+          data.currentOverflowElements = overflowedElements;
+        }
+      },
+      {
+        ...options,
+        root: target,
+      }
+    );
+    [...(target?.children || [])].forEach((childElement) => {
+      intersectionObserver.observe(childElement);
+    });
+    this.data.set(target, {
+      intersectionObserver,
+      currentOverflowElements: [],
+    });
+    this.mutationObserver.observe(target, {
+      childList: true,
+    });
+  }
+
+  unobserve(target: Element) {
+    this.data.get(target)?.intersectionObserver.disconnect();
+  }
+
+  disconnect() {
+    [...this.data.values()].forEach(({ intersectionObserver }) =>
+      intersectionObserver.disconnect()
+    );
+    this.data = new Map();
+    this.mutationObserver.disconnect();
+  }
+}
diff --git a/packages/jui/src/utils/overflow-utils/useOverflowObserver.tsx b/packages/jui/src/utils/overflow-utils/useOverflowObserver.tsx
new file mode 100644
index 00000000..71cacbe4
--- /dev/null
+++ b/packages/jui/src/utils/overflow-utils/useOverflowObserver.tsx
@@ -0,0 +1,42 @@
+import { RefObject, useEffect, useState } from "react";
+import { OverflowObserver } from "@intellij-platform/core/utils/overflow-utils/OverflowObserver";
+
+/**
+ * Given a ref to a scrollable container, returns the child elements that are not completely visible and
+ * are off view because of scroll.
+ * @param scrollableContainerRef
+ * @param threshold
+ */
+export function useOverflowObserver(
+  scrollableContainerRef: RefObject<HTMLElement>,
+  {
+    threshold = 0.9,
+    rootMargin = "0px",
+  }: Omit<IntersectionObserverInit, "root"> = {}
+) {
+  const [overflowedElements, setOverflowedElements] = useState<Element[]>([]);
+
+  useEffect(() => {
+    const overflowObserver = new OverflowObserver((change) => {
+      setOverflowedElements(change.overflowedElements);
+    });
+    overflowObserver.observe(scrollableContainerRef.current!, {
+      rootMargin,
+      threshold,
+    });
+    return () => {
+      overflowObserver.disconnect();
+    };
+  }, [
+    /**
+     * It's ok and needed to have the ref value as a dependency here. We don't know if ref is attached to different
+     * elements in each render, and it's ok that it's not a state, since we don't change it, and it's not supposed to
+     * change without a rerender
+     **/
+    scrollableContainerRef.current,
+  ]);
+
+  return {
+    overflowedElements,
+  };
+}
diff --git a/packages/website/docs/components/Toolbar.mdx b/packages/website/docs/components/Toolbar.mdx
index de3c4668..ed1e522d 100644
--- a/packages/website/docs/components/Toolbar.mdx
+++ b/packages/website/docs/components/Toolbar.mdx
@@ -1,7 +1,250 @@
 ---
 ---
 
-import { RefToIntellijPlatform } from "@site/src/components/RefToIntellijPlatform.tsx";
-import { Example } from "@site/src/components/ExampleContext";
+import { ApiDescription } from "@site/src/components/ApiDescription";
+import { Toolbar } from "@intellij-platform/core";
 
 # Toolbar
+
+<ApiDescription of={Toolbar} />
+
+```jsx live themed
+<Toolbar>
+  <IconButton aria-label="Hide">
+    <PlatformIcon icon="actions/arrowCollapse" />
+  </IconButton>
+  <ToolbarSeparator />
+  <IconButton aria-label="Add">
+    <PlatformIcon icon="general/add" />
+  </IconButton>
+  <IconButton aria-label="Checkout">
+    <PlatformIcon icon="actions/checkOut" />
+  </IconButton>
+  <IconButton aria-label="Delete">
+    <PlatformIcon icon="actions/gc" />
+  </IconButton>
+  <IconButton aria-label="Show Diff">
+    <PlatformIcon icon="actions/diff" />
+  </IconButton>
+  <IconButton aria-label="Find">
+    <PlatformIcon icon="actions/find" />
+  </IconButton>
+  <ToolbarSeparator />
+  <IconButton aria-label="Expand All">
+    <PlatformIcon icon="actions/expandall" />
+  </IconButton>
+  <IconButton aria-label="Collapse All">
+    <PlatformIcon icon="actions/collapseall" />
+  </IconButton>
+</Toolbar>
+```
+
+## Orientation
+
+By default, toolbar is horizontal. To make it vertical, set `orientation` prop to `"vertical"`:
+
+```jsx live themed
+<Toolbar orientation="vertical">
+  <IconButton aria-label="Hide">
+    <PlatformIcon icon="actions/arrowCollapse" />
+  </IconButton>
+  <ToolbarSeparator />
+  <IconButton aria-label="Add">
+    <PlatformIcon icon="general/add" />
+  </IconButton>
+  <IconButton aria-label="Checkout">
+    <PlatformIcon icon="actions/checkOut" />
+  </IconButton>
+  <IconButton aria-label="Delete">
+    <PlatformIcon icon="actions/gc" />
+  </IconButton>
+</Toolbar>
+```
+
+## Overflow
+
+When there is not enough room to show all its items, an arrow icon will appear at the end.
+Hovering over this arrow will display the rest of the items in a popup.
+
+```jsx live themed
+function OverflowExample() {
+  const [orientation, setOrientation] = useState("horizontal");
+  const [size, setSize] = useState(140);
+  return (
+    <>
+      <div style={{ display: "flex", gap: "1rem", marginBottom: "1rem" }}>
+        <div>
+          <label>
+            <input
+              type="radio"
+              value="horizontal"
+              checked={orientation === "horizontal"}
+              onChange={(event) => setOrientation(event.target.value)}
+            />
+            Horizontal
+          </label>
+          <label>
+            <input
+              type="radio"
+              value="vertical"
+              checked={orientation === "vertical"}
+              onChange={(event) => setOrientation(event.target.value)}
+            />
+            Vertical
+          </label>
+        </div>
+        <label style={{ display: "inline-flex", gap: "0.25rem" }}>
+          Size
+          <input
+            type="range"
+            value={size}
+            step="10"
+            min="20"
+            max="500"
+            onChange={(event) => setSize(event.target.valueAsNumber)}
+          />
+        </label>
+      </div>
+      <div style={{ [orientation === "vertical" ? "height" : "width"]: size }}>
+        <Toolbar orientation={orientation}>
+          <IconButton aria-label="Hide">
+            <PlatformIcon icon="actions/arrowCollapse" />
+          </IconButton>
+          <ToolbarSeparator />
+          <IconButton aria-label="Add">
+            <PlatformIcon icon="general/add" />
+          </IconButton>
+          <IconButton aria-label="Checkout">
+            <PlatformIcon icon="actions/checkOut" />
+          </IconButton>
+          <IconButton aria-label="Delete">
+            <PlatformIcon icon="actions/gc" />
+          </IconButton>
+          <IconButton aria-label="Show Diff">
+            <PlatformIcon icon="actions/diff" />
+          </IconButton>
+          <IconButton aria-label="Find">
+            <PlatformIcon icon="actions/find" />
+          </IconButton>
+          <ToolbarSeparator />
+          <IconButton aria-label="Expand All">
+            <PlatformIcon icon="actions/expandall" />
+          </IconButton>
+          <IconButton aria-label="Collapse All">
+            <PlatformIcon icon="actions/collapseall" />
+          </IconButton>
+        </Toolbar>
+      </div>
+    </>
+  );
+}
+```
+
+### Wrapping overflowing children
+
+In horizontal toolbars, `overflowBehavior` prop can be set to `wrap` which allows overflowing items to wrap into
+multiple lines, instead of the default way of handling overflow in a popup.
+
+```jsx live themed
+<div style={{ width: 100 }}>
+  <Toolbar overflowBehavior="wrap">
+    <IconButton aria-label="Hide">
+      <PlatformIcon icon="actions/arrowCollapse" />
+    </IconButton>
+    <ToolbarSeparator />
+    <IconButton aria-label="Add">
+      <PlatformIcon icon="general/add" />
+    </IconButton>
+    <IconButton aria-label="Checkout">
+      <PlatformIcon icon="actions/checkOut" />
+    </IconButton>
+    <IconButton aria-label="Delete">
+      <PlatformIcon icon="actions/gc" />
+    </IconButton>
+    <IconButton aria-label="Show Diff">
+      <PlatformIcon icon="actions/diff" />
+    </IconButton>
+  </Toolbar>
+</div>
+```
+
+## Other children
+
+While toolbar is primarily used to render a list of action buttons,
+[other components](https://jetbrains.github.io/ui/controls/toolbar/#02) can also be rendered
+inside a toolbar, and the overflow behavior works regardless.
+
+```jsx live themed noInline
+const StyledToolbarDropdownButton = styled.button`
+  all: unset;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding-left: 0.25rem;
+  background: ${({ theme }) => theme.color("ComboBoxButton.background")};
+  color: ${({ theme }) => theme.color("ComboBox.disabledForeground")};
+  &:hover {
+    color: ${({ theme }) => theme.color("*.foreground")};
+  }
+`;
+function ToolbarChildrenExample() {
+  return (
+    <div style={{ width: 140 }}>
+      <Toolbar>
+        <MenuTrigger
+          renderMenu={({ menuProps }) => (
+            <Menu {...menuProps}>
+              <Item>Select...</Item>
+              <Item>Last 24 hours</Item>
+              <Item>Last 7 days</Item>
+            </Menu>
+          )}
+        >
+          {(props, ref) => (
+            <StyledToolbarDropdownButton {...props} ref={ref}>
+              Date <PlatformIcon icon="general/arrowDownSmall.svg" />
+            </StyledToolbarDropdownButton>
+          )}
+        </MenuTrigger>
+        <MenuTrigger
+          renderMenu={({ menuProps }) => (
+            <Menu {...menuProps}>
+              <Item>Select...</Item>
+              <Item>me</Item>
+            </Menu>
+          )}
+        >
+          {(props, ref) => (
+            <StyledToolbarDropdownButton {...props} ref={ref}>
+              User <PlatformIcon icon="general/arrowDownSmall.svg" />
+            </StyledToolbarDropdownButton>
+          )}
+        </MenuTrigger>
+        <MenuTrigger
+          renderMenu={({ menuProps }) => (
+            <Menu {...menuProps}>
+              <Item>Select in...</Item>
+              <Item>Select in Tree...</Item>
+            </Menu>
+          )}
+        >
+          {(props, ref) => (
+            <StyledToolbarDropdownButton {...props} ref={ref}>
+              Paths <PlatformIcon icon="general/arrowDownSmall.svg" />
+            </StyledToolbarDropdownButton>
+          )}
+        </MenuTrigger>
+        <ToolbarSeparator />
+        <TooltipTrigger
+          tooltip={<ActionTooltip actionName={"Open New Git Log Tab"} />}
+        >
+          <IconButton aria-label="Checkout">
+            <PlatformIcon icon="actions/openNewTab.svg" />
+          </IconButton>
+        </TooltipTrigger>
+      </Toolbar>
+    </div>
+  );
+}
+render(<ToolbarChildrenExample />);
+```