@openfin/ui-library 0.31.3-alpha.20260121152019 → 0.31.3-alpha.20260121191139

package/dist/components/layout/HorizontalOverflow/HorizontalOverflow.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import type { HorizontalOverflowProps } from './HorizontalOverflow.types';
+import './HorizontalOverflow.scss';
+/**
+ * A reusable horizontal overflow container with consistent, accessible horizontal scrolling behavior.
+ * Designed for tab rows and icon rows across Enterprise Browser, Core UI, and Here-Zero.
+ *
+ * This component is CSS-first with BEM class-based styling - all visual styles are defined in SCSS.
+ * JavaScript handles only behavioral concerns like overflow detection, scroll events, and button interactions.
+ *
+ * The component takes 100% width and height of its parent container.
+ *
+ * @example
+ * ```tsx
+ * <HorizontalOverflow
+ *   variant="enterprise-view-tabs"
+ *   showScrollShadows
+ *   showScrollButtons
+ *   hideScrollbar
+ * >
+ *   {tabs.map(tab => <Tab key={tab.id} {...tab} />)}
+ * </HorizontalOverflow>
+ * ```
+ */
+export declare const HorizontalOverflow: React.ForwardRefExoticComponent<HorizontalOverflowProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/layout/HorizontalOverflow/HorizontalOverflow.types.d.ts

@@ -0,0 +1,54 @@
+import { CSSProperties, ReactNode, RefObject, UIEvent } from 'react';
+export type HorizontalOverflowVariant = 'enterprise-top-tabs' | 'enterprise-view-tabs' | 'coreui-view-tabs' | 'dock-icons' | 'default';
+export type ScrollShadowWidth = 'small' | 'large';
+export type ScrollBehavior = 'smooth' | 'instant' | 'auto';
+export interface HorizontalOverflowProps {
+    /** Content to render inside the scrollable container */
+    children: ReactNode;
+    /** Variant that maps to BEM modifiers for theming (shadow colors, etc.) */
+    variant?: HorizontalOverflowVariant;
+    /** Additional CSS class names */
+    className?: string;
+    /** Inline styles for the container */
+    style?: CSSProperties;
+    /** Accessible label for the scrollable region */
+    ariaLabel?: string;
+    /** Semantic HTML element to render as */
+    as?: 'div' | 'nav' | 'section' | 'ul';
+    /** Show scroll shadows when content overflows */
+    showScrollShadows?: boolean;
+    /** Width of scroll shadows ('small' = 12px, 'large' = 24px) */
+    shadowWidth?: ScrollShadowWidth;
+    /** Show left/right scroll buttons when overflowing */
+    showScrollButtons?: boolean;
+    /** Amount to scroll when buttons are clicked (in px) */
+    scrollButtonAmount?: number;
+    /** Hide scrollbar visually (content still scrollable) */
+    hideScrollbar?: boolean;
+    /** Enable horizontal wheel scroll (convert vertical to horizontal) */
+    enableWheelScroll?: boolean;
+    /** Scroll behavior for programmatic scrolls */
+    scrollBehavior?: ScrollBehavior;
+    /** Callback when overflow state changes */
+    onOverflowChange?: (isOverflowing: boolean) => void;
+    /** Callback when scroll position changes */
+    onScroll?: (event: UIEvent<HTMLDivElement>) => void;
+    /** Offset for scroll shadow positioning (accounts for adjacent buttons) */
+    shadowOffset?: number;
+    /** Ref forwarded to the scrollable container */
+    containerRef?: RefObject<HTMLDivElement>;
+    /** Test ID for testing */
+    'data-testid'?: string;
+}
+export interface ScrollShadowProps {
+    direction: 'left' | 'right';
+    width: ScrollShadowWidth;
+    offset?: number;
+    visible: boolean;
+}
+export interface ScrollButtonProps {
+    direction: 'left' | 'right';
+    disabled: boolean;
+    onClick: () => void;
+    'aria-label': string;
+}

package/dist/components/layout/HorizontalOverflow/ScrollButton.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { ScrollButtonProps } from './HorizontalOverflow.types';
+/**
+ * Internal navigation button for scrolling the overflow container.
+ * Renders a left or right chevron icon and handles click events for programmatic scrolling.
+ * Styled via BEM classes - visual appearance defined in SCSS.
+ *
+ * @internal This component is not exported publicly and is used only by HorizontalOverflow.
+ */
+export declare const ScrollButton: React.FC<ScrollButtonProps>;

package/dist/components/layout/HorizontalOverflow/ScrollShadow.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { ScrollShadowProps } from './HorizontalOverflow.types';
+/**
+ * Internal component that renders a gradient shadow overlay to indicate scrollable content.
+ * The shadow fades in/out based on scroll position to provide visual feedback.
+ * Styled via BEM classes - visual appearance defined in SCSS.
+ *
+ * @internal This component is not exported publicly and is used only by HorizontalOverflow.
+ */
+export declare const ScrollShadow: React.FC<ScrollShadowProps>;

package/dist/components/layout/HorizontalOverflow/index.d.ts

@@ -0,0 +1,2 @@
+export { HorizontalOverflow } from './HorizontalOverflow';
+export type { HorizontalOverflowProps, HorizontalOverflowVariant, ScrollShadowWidth, ScrollBehavior } from './HorizontalOverflow.types';

package/dist/hooks/useHorizontalOverflow.d.ts

@@ -0,0 +1,83 @@
+import { RefObject } from 'react';
+export interface UseHorizontalOverflowOptions {
+    /** Scroll behavior for programmatic scrolls */
+    scrollBehavior?: ScrollBehavior;
+    /** Amount to scroll when using scrollBy functions (in pixels) */
+    scrollAmount?: number;
+    /** Callback when overflow state changes */
+    onOverflowChange?: (isOverflowing: boolean) => void;
+    /** Debounce delay for resize checks (ms) */
+    resizeDebounce?: number;
+    /** External ref to use instead of creating internal ref */
+    containerRef?: RefObject<HTMLDivElement>;
+}
+export interface UseHorizontalOverflowReturn {
+    /** Ref to attach to the scrollable container */
+    containerRef: RefObject<HTMLDivElement>;
+    /** Whether content is overflowing the container */
+    isOverflowing: boolean;
+    /** Whether user can scroll left (not at start) */
+    canScrollLeft: boolean;
+    /** Whether user can scroll right (not at end) */
+    canScrollRight: boolean;
+    /** Current scroll position (0-1 normalized) */
+    scrollProgress: number;
+    /** Scroll left by configured amount */
+    scrollLeft: () => void;
+    /** Scroll right by configured amount */
+    scrollRight: () => void;
+    /** Scroll to the start of the container */
+    scrollToStart: () => void;
+    /** Scroll to the end of the container */
+    scrollToEnd: () => void;
+    /** Scroll a child element into view */
+    scrollChildIntoView: (childEl: HTMLElement, behavior?: ScrollBehavior) => void;
+    /** Manually trigger overflow check */
+    checkOverflow: () => void;
+    /** Handle wheel event (convert vertical to horizontal) */
+    handleWheelScroll: (event: WheelEvent) => void;
+}
+/**
+ * Hook for managing horizontal overflow behavior.
+ *
+ * Provides utilities for detecting overflow, scrolling programmatically,
+ * and scrolling child elements into view.
+ *
+ * @example
+ * ```tsx
+ * function TabList({ tabs, activeTabId }) {
+ *   const {
+ *     containerRef,
+ *     isOverflowing,
+ *     canScrollLeft,
+ *     canScrollRight,
+ *     scrollLeft,
+ *     scrollRight,
+ *     scrollChildIntoView,
+ *   } = useHorizontalOverflow();
+ *
+ *   // Scroll active tab into view when it changes
+ *   useEffect(() => {
+ *     const activeEl = document.getElementById(activeTabId);
+ *     if (activeEl) {
+ *       scrollChildIntoView(activeEl);
+ *     }
+ *   }, [activeTabId, scrollChildIntoView]);
+ *
+ *   return (
+ *     <div>
+ *       {isOverflowing && (
+ *         <button onClick={scrollLeft} disabled={!canScrollLeft}>←</button>
+ *       )}
+ *       <div ref={containerRef} style={{ overflowX: 'auto' }}>
+ *         {tabs.map(tab => <Tab key={tab.id} id={tab.id} {...tab} />)}
+ *       </div>
+ *       {isOverflowing && (
+ *         <button onClick={scrollRight} disabled={!canScrollRight}>→</button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useHorizontalOverflow(options?: UseHorizontalOverflowOptions): UseHorizontalOverflowReturn;

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export * from './components/input/DateInput';
 export * from './components/input/TextArea';
 export * from './components/layout/Box';
 export * from './components/layout/DefinitionList';
+export * from './components/layout/HorizontalOverflow';
 export * from './components/system';
 export * from './components/templates/ContactCard';
 export * from './components/typography/Heading';
@@ -31,8 +32,10 @@ export * from './hooks/useColorScheme';
 export * from './hooks/useMediaQuery';
 export * from './hooks/usePrevious';
 export * from './hooks/useDropdownKeyboardNavigation';
+export * from './hooks/useHorizontalOverflow';
 export * from './lib/whenFin';
 export * from './lib/color-generator';
+export * from './lib/scrollChildIntoView';
 export * from './utils';
 export * from './components/helper/ValidationError';
 export * from './assets';