feat(responsive-tabs): allow scroll on components with tabs

.changeset/fresh-points-breathe.md

@@ -0,0 +1,6 @@
+---
+"@twilio-paste/design-tokens": minor
+"@twilio-paste/core": minor
+---
+
+[Design Token] added new box shadows to support scrollable styling on inverse colored components

.changeset/grumpy-dryers-remain.md

@@ -0,0 +1,6 @@
+---
+"@twilio-paste/code-block": patch
+"@twilio-paste/core": patch
+---
+
+[CodeBlock] make tabs responsive

.changeset/loud-items-rhyme.md

@@ -0,0 +1,6 @@
+---
+"@twilio-paste/in-page-navigation": patch
+"@twilio-paste/core": patch
+---
+
+[In Page Navigation] make items scrollable

.changeset/strong-eagles-complain.md

@@ -0,0 +1,7 @@
+---
+"@twilio-paste/tabs": minor
+"@twilio-paste/core": minor
+"@twilio-paste/codemods": minor
+---
+
+[Tabs] make the non-fitted variant Tabs responsive. Export the context provider `TabsContext`.

packages/paste-codemods/tools/.cache/mappings.json

@@ -306,6 +306,7 @@
  "TabPanel": "@twilio-paste/core/tabs",
  "TabPanels": "@twilio-paste/core/tabs",
  "Tabs": "@twilio-paste/core/tabs",
+ "TabsContext": "@twilio-paste/core/tabs",
  "useTabState": "@twilio-paste/core/tabs",
  "TextArea": "@twilio-paste/core/textarea",
  "TimePicker": "@twilio-paste/core/time-picker",

packages/paste-core/components/code-block/__tests__/customization.spec.tsx

@@ -27,6 +27,8 @@ const CustomizationWrapper: React.FC<React.PropsWithChildren> = ({ children }) =
  CODE_BLOCK_TAB: { borderRadius: "borderRadius0" },
  CODE_BLOCK_WRAPPER: { width: "size50" },
  CODE_BLOCK: { width: "size50" },
+ CODE_BLOCK_TAB_LIST_CHILD: { backgroundColor: "colorBackgroundError" },
+ CODE_BLOCK_TAB_LIST_CHILD_SCROLL_WRAPPER: { backgroundColor: "colorBackgroundAvailable" },
  }}
  >
  {children}
@@ -47,6 +49,8 @@ const CustomizationMyWrapper: React.FC<React.PropsWithChildren> = ({ children })
  MY_CODE_BLOCK_TAB: { borderRadius: "borderRadius0" },
  MY_CODE_BLOCK_WRAPPER: { width: "size50" },
  MY_CODE_BLOCK: { width: "size50" },
+ MY_CODE_BLOCK_TAB_LIST_CHILD: { backgroundColor: "colorBackgroundError" },
+ MY_CODE_BLOCK_TAB_LIST_CHILD_SCROLL_WRAPPER: { backgroundColor: "colorBackgroundAvailable" },
  }}
  >
  {children}
@@ -85,6 +89,10 @@ describe("Customization", () => {
  expect(content?.getAttribute("data-paste-element")).toBe("CODE_BLOCK_CONTENT");
  expect(tabList.getAttribute("data-paste-element")).toBe("CODE_BLOCK_TAB_LIST");
  expect(tab.getAttribute("data-paste-element")).toBe("CODE_BLOCK_TAB");
+ expect(tab.parentElement?.getAttribute("data-paste-element")).toBe("CODE_BLOCK_TAB_LIST_CHILD");
+ expect(tab.parentElement?.parentElement?.getAttribute("data-paste-element")).toBe(
+ "CODE_BLOCK_TAB_LIST_CHILD_SCROLL_WRAPPER",
+ );
  expect(tabPanel?.getAttribute("data-paste-element")).toBe("CODE_BLOCK_TAB_PANEL");
  expect(codeBlock.getAttribute("data-paste-element")).toBe("CODE_BLOCK");
  expect(heading.getAttribute("data-paste-element")).toBe("CODE_BLOCK_HEADER");
@@ -128,6 +136,10 @@ describe("Customization", () => {
  expect(content?.getAttribute("data-paste-element")).toBe("MY_CODE_BLOCK_CONTENT");
  expect(tabList.getAttribute("data-paste-element")).toBe("MY_CODE_BLOCK_TAB_LIST");
  expect(tab.getAttribute("data-paste-element")).toBe("MY_CODE_BLOCK_TAB");
+ expect(tab.parentElement?.getAttribute("data-paste-element")).toBe("MY_CODE_BLOCK_TAB_LIST_CHILD");
+ expect(tab.parentElement?.parentElement?.getAttribute("data-paste-element")).toBe(
+ "MY_CODE_BLOCK_TAB_LIST_CHILD_SCROLL_WRAPPER",
+ );
  expect(tabPanel?.getAttribute("data-paste-element")).toBe("MY_CODE_BLOCK_TAB_PANEL");
  expect(codeBlock.getAttribute("data-paste-element")).toBe("MY_CODE_BLOCK");
  expect(heading.getAttribute("data-paste-element")).toBe("MY_CODE_BLOCK_HEADER");
@@ -167,6 +179,8 @@ describe("Customization", () => {
  expect(heading).toHaveStyleRule("border-top-right-radius", "8px");
  expect(tabList).toHaveStyleRule("column-gap", "0");
  expect(tab).toHaveStyleRule("border-radius", "0");
+ expect(tab.parentElement).toHaveStyleRule("background-color", "rgb(214, 31, 31)");
+ expect(tab.parentElement?.parentElement).toHaveStyleRule("background-color", "rgb(20, 176, 83)");
  expect(tabPanel).toHaveStyleRule("border-bottom-right-radius", "8px");
  expect(copyButton).toHaveStyleRule("background-color", "rgb(254, 236, 236)");
  expect(externalLink).toHaveStyleRule("background-color", "rgb(254, 236, 236)");
@@ -210,6 +224,8 @@ describe("Customization", () => {
  expect(heading).toHaveStyleRule("border-top-right-radius", "8px");
  expect(tabList).toHaveStyleRule("column-gap", "0");
  expect(tab).toHaveStyleRule("border-radius", "0");
+ expect(tab.parentElement).toHaveStyleRule("background-color", "rgb(214, 31, 31)");
+ expect(tab.parentElement?.parentElement).toHaveStyleRule("background-color", "rgb(20, 176, 83)");
  expect(tabPanel).toHaveStyleRule("border-bottom-right-radius", "8px");
  expect(copyButton).toHaveStyleRule("background-color", "rgb(254, 236, 236)");
  expect(externalLink).toHaveStyleRule("background-color", "rgb(254, 236, 236)");

packages/paste-core/components/code-block/src/CodeBlockTabList.tsx

@@ -1,9 +1,36 @@
-import { Box } from "@twilio-paste/box";
+import { Box, safelySpreadBoxProps } from "@twilio-paste/box";
 import type { BoxProps } from "@twilio-paste/box";
-import { TabList } from "@twilio-paste/tabs";
-import type { TabListProps } from "@twilio-paste/tabs";
+import { css, styled } from "@twilio-paste/styling-library";
+import { type TabListProps, TabsContext } from "@twilio-paste/tabs";
+import { TabPrimitiveList } from "@twilio-paste/tabs-primitive";
 import * as React from "react";
 
+import { OverflowButton } from "./OverflowButton";
+import { handleScrollDirection, useElementsOutOfBounds, useShowShadow } from "./utlis";
+
+/**
+ * This wrapper applies styles that customize the scrollbar and its track.
+ */
+const StyledTabList = styled.div(() => {
+ return css({
+ overflowX: "auto",
+ overflowY: "hidden",
+ overflowScrolling: "touch",
+ /* Firefox scrollbar */
+ "@supports (-moz-appearance:none)": {
+ paddingBottom: "0px",
+ scrollbarWidth: "none",
+ },
+ /* Chrome + Safari scrollbar */
+ "::-webkit-scrollbar": {
+ height: 0,
+ },
+ "::-webkit-scrollbar-track": {
+ background: "transparent",
+ },
+ });
+});
+
 export interface CodeBlockTabListProps extends Omit<TabListProps, "aria-label"> {
  /**
  * Overrides the default element name to apply unique styles with the Customization Provider
@@ -17,12 +44,86 @@ export interface CodeBlockTabListProps extends Omit<TabListProps, "aria-label">
 
 export const CodeBlockTabList = React.forwardRef<HTMLDivElement, CodeBlockTabListProps>(
  ({ children, element = "CODE_BLOCK_TAB_LIST", ...props }, ref) => {
+ const tabContext = React.useContext(TabsContext);
+ // ref to the scrollable element
+ const scrollableRef = React.useRef<HTMLDivElement>(null);
+ const listRef = React.useRef<HTMLDivElement>(null);
+
+ const { determineElementsOutOfBounds, elementOutOBoundsLeft, elementOutOBoundsRight } = useElementsOutOfBounds();
+ const { handleShadow, showShadow } = useShowShadow();
+
+ const handleScrollEvent = (): void => {
+ handleShadow();
+ determineElementsOutOfBounds(scrollableRef.current, listRef.current);
+ };
+
+ React.useEffect(() => {
+ if (scrollableRef.current && listRef.current) {
+ scrollableRef.current.addEventListener("scroll", handleScrollEvent);
+ window.addEventListener("resize", handleScrollEvent);
+ determineElementsOutOfBounds(scrollableRef.current, listRef.current);
+ }
+ }, [scrollableRef.current, listRef.current]);
+
+ // Cleanup event listeners on destroy
+ React.useEffect(() => {
+ return () => {
+ if (scrollableRef.current) {
+ scrollableRef.current.removeEventListener("scroll", handleScrollEvent);
+ window.removeEventListener("resize", handleScrollEvent);
+ }
+ };
+ }, []);
+
  return (
- <Box paddingX="space70">
- <TabList {...props} aria-label="label" ref={ref} element={element}>
- {children}
- </TabList>
- </Box>
+ <TabPrimitiveList {...(tabContext as any)} as={Box} {...props} element={element} ref={ref}>
+ <Box element={`${element}_CHILD_WRAPPER`} display="flex">
+ <OverflowButton
+ position="left"
+ onClick={() =>
+ handleScrollDirection("left", elementOutOBoundsLeft, elementOutOBoundsRight, listRef.current)
+ }
+ visible={Boolean(elementOutOBoundsLeft)}
+ element={element}
+ showShadow={showShadow}
+ />
+ <Box
+ {...safelySpreadBoxProps(props)}
+ as={StyledTabList as any}
+ ref={scrollableRef}
+ display="flex"
+ flexWrap="nowrap"
+ element={`${element}_CHILD_SCROLL_WRAPPER`}
+ overflowX="auto"
+ overflowY="hidden"
+ flexGrow={1}
+ width="calc(100% - 60px)"
+ >
+ <Box
+ whiteSpace="nowrap"
+ element={`${element}_CHILD`}
+ display="flex"
+ borderBottomStyle="solid"
+ borderBottomWidth="borderWidth10"
+ borderBottomColor="colorBorderInverseWeaker"
+ ref={listRef}
+ flexGrow={1}
+ columnGap="space20"
+ >
+ {children}
+ </Box>
+ </Box>
+ <OverflowButton
+ position="right"
+ onClick={() =>
+ handleScrollDirection("right", elementOutOBoundsLeft, elementOutOBoundsRight, listRef.current)
+ }
+ visible={Boolean(elementOutOBoundsRight)}
+ element={element}
+ showShadow={showShadow}
+ />
+ </Box>
+ </TabPrimitiveList>
  );
  },
 );

packages/paste-core/components/code-block/src/OverflowButton.tsx

@@ -0,0 +1,55 @@
+import { Box, BoxProps, BoxStyleProps } from "@twilio-paste/box";
+import { ChevronLeftIcon } from "@twilio-paste/icons/esm/ChevronLeftIcon";
+import { ChevronRightIcon } from "@twilio-paste/icons/esm/ChevronRightIcon";
+import { useTheme } from "@twilio-paste/theme";
+import React from "react";
+
+interface OverflowButtonProps {
+ onClick: () => void;
+ position: "left" | "right";
+ visible?: boolean;
+ element?: BoxProps["element"];
+ showShadow?: boolean;
+}
+
+const Styles: BoxStyleProps = {
+ color: "colorTextIconInverse",
+ _hover: {
+ color: "colorTextInverse",
+ cursor: "pointer",
+ },
+};
+
+export const OverflowButton: React.FC<OverflowButtonProps> = ({
+ onClick,
+ position,
+ visible,
+ element = "CODE_BLOCK_TAB_LIST",
+ showShadow,
+}) => {
+ const theme = useTheme();
+ const Chevron = position === "left" ? ChevronLeftIcon : ChevronRightIcon;
+ if (!visible && position === "right") return null;
+
+ return (
+ <Box
+ onClick={onClick}
+ aria-hidden={true}
+ display="flex"
+ alignItems="center"
+ justifyContent="center"
+ width="sizeIcon40"
+ padding="space20"
+ position="relative"
+ boxShadow={visible && showShadow ? theme.shadows.shadowScrollInverse : undefined}
+ element={`${element}_OVERFLOW_BUTTON_${position.toUpperCase()}`}
+ cursor={visible ? "pointer" : "none"}
+ {...Styles}
+ >
+ {/* For left button to align with spacing of header we hide icon */}
+ {visible && <Chevron decorative={true} />}
+ </Box>
+ );
+};
+
+OverflowButton.displayName = "OverflowButton";

packages/paste-core/components/code-block/src/utlis.ts

@@ -0,0 +1,87 @@
+import React from "react";
+
+export const useElementsOutOfBounds = (): {
+ elementOutOBoundsLeft: HTMLDivElement | null;
+ elementOutOBoundsRight: HTMLDivElement | null;
+ determineElementsOutOfBounds: (scrollContainer: HTMLDivElement | null, listContainer: HTMLElement | null) => void;
+} => {
+ // Keep track of first elements that are paritally or completely out of view in either direction
+ const [elementOutOBoundsLeft, setElementOutOfBoundsLeft] = React.useState<HTMLDivElement | null>(null);
+ const [elementOutOBoundsRight, setElementOutOfBoundsRight] = React.useState<HTMLDivElement | null>(null);
+
+ // called on load and resize and on scroll to set the elements that are out of view
+ const determineElementsOutOfBounds = (
+ scrollContainer: HTMLDivElement | null,
+ listContainer: HTMLElement | null,
+ ): void => {
+ if (scrollContainer && listContainer) {
+ const currentScrollContainerRightPosition = (scrollContainer as HTMLDivElement)?.getBoundingClientRect().right;
+ const currentScrollContainerXOffset = (scrollContainer as HTMLDivElement)?.getBoundingClientRect().x;
+
+ let leftOutOfBounds: HTMLDivElement | null = null;
+ let rightOutOfBounds: HTMLDivElement | null = null;
+
+ (listContainer.childNodes as NodeListOf<HTMLDivElement>).forEach((tab) => {
+ const { x, right } = tab.getBoundingClientRect();
+ // Check if the tab is spanning the view if text is really long on smaller devices, wont skip to next element
+ const isSpanningView = x < currentScrollContainerXOffset && right > currentScrollContainerRightPosition;
+ if (!isSpanningView) {
+ /**
+ * Compares the left side of the tab with the left side of the scrollable container position
+ * as the x value will not be 0 due to being offset in the screen.
+ */
+ if (x < currentScrollContainerXOffset) {
+ leftOutOfBounds = tab;
+ }
+ /**
+ * Compares the right side to the end of container with some buffer. Also ensure there are
+ * no value set as it loops through the array we don't want it to override the first value out of bounds.
+ */
+ if (right > currentScrollContainerRightPosition + 10 && !rightOutOfBounds) {
+ rightOutOfBounds = tab;
+ }
+ }
+
+ setElementOutOfBoundsLeft(leftOutOfBounds);
+ setElementOutOfBoundsRight(rightOutOfBounds);
+ });
+ }
+ };
+
+ return { elementOutOBoundsLeft, elementOutOBoundsRight, determineElementsOutOfBounds };
+};
+
+export const useShowShadow = (): { showShadow: boolean; handleShadow: () => void } => {
+ const [showShadow, setShowShadow] = React.useState(false);
+ let showShadowTimer: number;
+
+ const handleShadow = (): void => {
+ if (showShadowTimer) {
+ window.clearTimeout(showShadowTimer);
+ }
+ setShowShadow(true);
+ showShadowTimer = window.setTimeout(() => {
+ setShowShadow(false);
+ }, 500);
+ };
+
+ return { showShadow, handleShadow };
+};
+
+/**
+ * Scrolls to the element that is out of bounds (from React State), centering it in the scrollable container
+ * Logic to handle scrolling also replicated in CodeBlock and InPageNavigation. If changing here, consider reviewing those components too.
+ */
+export const handleScrollDirection = (
+ direction: "left" | "right",
+ elementOutOBoundsLeft: HTMLDivElement | null,
+ elementOutOBoundsRight: HTMLDivElement | null,
+ listContainer: HTMLElement | null,
+): void => {
+ if (listContainer) {
+ const elementToScrollTo = direction === "left" ? elementOutOBoundsLeft : elementOutOBoundsRight;
+ if (elementToScrollTo) {
+ elementToScrollTo.scrollIntoView({ behavior: "smooth", block: "nearest", inline: "center" });
+ }
+ }
+};