@lumx/react 3.20.1-alpha.20 → 3.20.1-alpha.21

package/src/components/tabs/TabList.tsx

@@ -0,0 +1,94 @@
+import React, { ReactNode } from 'react';
+
+import classNames from 'classnames';
+
+import { Alignment, Theme } from '@lumx/react';
+import { CSS_PREFIX } from '@lumx/react/constants';
+import { GenericProps, HasTheme } from '@lumx/react/utils/type';
+import { handleBasicClasses } from '@lumx/core/js/utils/className';
+import { mergeRefs } from '@lumx/react/utils/react/mergeRefs';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+import { useTheme } from '@lumx/react/utils/theme/ThemeContext';
+
+import { useRovingTabIndex } from '../../hooks/useRovingTabIndex';
+
+export enum TabListLayout {
+    clustered = 'clustered',
+    fixed = 'fixed',
+}
+
+/**
+ * Defines the props of the component.
+ */
+export interface TabListProps extends GenericProps, HasTheme {
+    /** ARIA label (purpose of the set of tabs). */
+    ['aria-label']: string;
+    /** Tab list. */
+    children: ReactNode;
+    /** Layout of the tabs in the list. */
+    layout?: TabListLayout;
+    /** Position of the tabs in the list (requires 'clustered' layout). */
+    position?: Alignment;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'TabList';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = `${CSS_PREFIX}-tabs`;
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<TabListProps> = {
+    layout: TabListLayout.fixed,
+    position: Alignment.left,
+};
+
+/**
+ * TabList component.
+ *
+ * Implements WAI-ARIA `tablist` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const TabList = forwardRef<TabListProps, HTMLDivElement>((props, ref) => {
+    const defaultTheme = useTheme() || Theme.light;
+    const {
+        'aria-label': ariaLabel,
+        children,
+        className,
+        layout = DEFAULT_PROPS.layout,
+        position = DEFAULT_PROPS.position,
+        theme = defaultTheme,
+        ...forwardedProps
+    } = props;
+    const tabListRef = React.useRef(null);
+    useRovingTabIndex({
+        parentRef: tabListRef,
+        elementSelector: '[role="tab"]',
+        keepTabIndex: false,
+        extraDependencies: [children],
+    });
+
+    return (
+        <div
+            ref={mergeRefs(ref, tabListRef)}
+            {...forwardedProps}
+            className={classNames(className, handleBasicClasses({ prefix: CLASSNAME, layout, position, theme }))}
+        >
+            <div className={`${CLASSNAME}__links`} role="tablist" aria-label={ariaLabel}>
+                {children}
+            </div>
+        </div>
+    );
+});
+TabList.displayName = COMPONENT_NAME;
+TabList.className = CLASSNAME;
+TabList.defaultProps = DEFAULT_PROPS;

package/src/components/tabs/TabPanel.test.tsx

@@ -0,0 +1,37 @@
+import { commonTestsSuiteRTL } from '@lumx/react/testing/utils';
+import { getByClassName } from '@lumx/react/testing/utils/queries';
+import { render, screen } from '@testing-library/react';
+
+import { TabPanel, TabPanelProps } from './TabPanel';
+
+const CLASSNAME = TabPanel.className as string;
+
+type SetupProps = Partial<TabPanelProps>;
+
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+const setup = (propsOverride: SetupProps = {}) => {
+    const props: TabPanelProps = { ...propsOverride, children: 'Tab panel content' };
+
+    render(<TabPanel {...props} />);
+    const tabPanel = getByClassName(document.body, CLASSNAME);
+
+    return { props, tabPanel };
+};
+
+describe(`<${TabPanel.displayName}>`, () => {
+    it('should render default', () => {
+        const content = 'Content';
+        const { tabPanel } = setup({ children: content });
+        expect(tabPanel).toBe(screen.queryByRole('tabpanel'));
+    });
+
+    // Common tests suite.
+    commonTestsSuiteRTL(setup, {
+        baseClassName: CLASSNAME,
+        forwardClassName: 'tabPanel',
+        forwardAttributes: 'tabPanel',
+        forwardRef: 'tabPanel',
+    });
+});

package/src/components/tabs/TabPanel.tsx

@@ -0,0 +1,67 @@
+import classNames from 'classnames';
+
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+import { useTabProviderContext } from '@lumx/react/components/tabs/state';
+import { CSS_PREFIX } from '@lumx/react/constants';
+import { GenericProps } from '@lumx/react/utils/type';
+import { handleBasicClasses } from '@lumx/core/js/utils/className';
+
+/**
+ * Defines the props of the component.
+ */
+export interface TabPanelProps extends GenericProps {
+    /** Native id property */
+    id?: string;
+    /** Whether the tab is active or not. */
+    isActive?: boolean;
+    /** Children */
+    children?: React.ReactNode;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'TabPanel';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = `${CSS_PREFIX}-tab-panel`;
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<TabPanelProps> = {};
+
+/**
+ * TabPanel component.
+ *
+ * Implements WAI-ARIA `tabpanel` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const TabPanel = forwardRef<TabPanelProps, HTMLDivElement>((props, ref) => {
+    const { children, id, className, isActive: propIsActive, ...forwardedProps } = props;
+
+    const state = useTabProviderContext('tabPanel', id);
+    const isActive = propIsActive || state?.isActive;
+
+    return (
+        <div
+            ref={ref}
+            {...forwardedProps}
+            id={state?.tabPanelId}
+            className={classNames(className, handleBasicClasses({ prefix: CLASSNAME, isActive }))}
+            role="tabpanel"
+            tabIndex={isActive ? 0 : -1}
+            aria-labelledby={state?.tabId}
+        >
+            {(!state?.isLazy || isActive) && children}
+        </div>
+    );
+});
+TabPanel.displayName = COMPONENT_NAME;
+TabPanel.className = CLASSNAME;
+TabPanel.defaultProps = DEFAULT_PROPS;

package/src/components/tabs/TabProvider.test.tsx

@@ -0,0 +1,161 @@
+import { Tab, TabList, TabPanel, TabProvider, TabProviderProps } from '@lumx/react';
+import { render } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { checkTabActive, query } from '@lumx/react/components/tabs/test-utils';
+
+const setup = (props: Partial<TabProviderProps> = {}) => {
+    render(
+        <TabProvider {...props}>
+            <TabList aria-label="Tab list">
+                <Tab label="Tab 1" />
+                <Tab label="Tab 2" isDisabled />
+                <Tab label="Tab 3" />
+            </TabList>
+
+            <TabPanel>Tab 1 content</TabPanel>
+            <TabPanel>Tab 2 content</TabPanel>
+            <TabPanel>Tab 3 content</TabPanel>
+        </TabProvider>,
+    );
+};
+
+describe('TabProvider', () => {
+    describe('default config', () => {
+        it('should render with accessible DOM', () => {
+            setup();
+
+            // Tab list
+            const tabList = query.tabList('Tab list');
+            expect(tabList).toBeInTheDocument();
+            expect(query.tabs(tabList).length).toBe(3);
+
+            // Tab 1
+            const tab1 = query.tab('Tab 1', tabList);
+            expect(tab1).toBeInTheDocument();
+
+            // Tab 2
+            const tab2 = query.tab('Tab 2', tabList);
+            expect(tab2).toBeInTheDocument();
+
+            // Tab 3
+            const tab3 = query.tab('Tab 3', tabList);
+            expect(tab3).toBeInTheDocument();
+
+            // Tab panel 1
+            const tabPanel1 = query.tabPanel('Tab 1');
+            expect(tabPanel1).toBeInTheDocument();
+            expect(tab1).toHaveAttribute('aria-controls', tabPanel1?.id);
+
+            // Tab panel 2
+            const tabPanel2 = query.tabPanel('Tab 2');
+            expect(tabPanel2).toBeInTheDocument();
+            expect(tab2).toHaveAttribute('aria-controls', tabPanel2?.id);
+
+            // Tab panel 3
+            const tabPanel3 = query.tabPanel('Tab 3');
+            expect(tabPanel3).toBeInTheDocument();
+            expect(tab3).toHaveAttribute('aria-controls', tabPanel3?.id);
+
+            // First tab is active
+            checkTabActive('Tab 1');
+        });
+
+        it('should switch tab on click', async () => {
+            setup();
+
+            checkTabActive('Tab 1');
+
+            // Click on second tab (that is disabled) should do nothing
+            await userEvent.click(query.tab('Tab 2'));
+            checkTabActive('Tab 1');
+
+            // Click on third tab should work
+            await userEvent.click(query.tab('Tab 3'));
+            checkTabActive('Tab 3');
+        });
+
+        it('should be navigable with keyboard', async () => {
+            setup();
+
+            checkTabActive('Tab 1');
+
+            // First tab stop on active tab (tab1)
+            await userEvent.tab();
+            expect(query.tab('Tab 1')).toHaveFocus();
+
+            // Second tab stop on active tab panel (tabPanel1)
+            await userEvent.tab();
+            expect(query.tabPanel('Tab 1')).toHaveFocus();
+
+            // Go back to tab1
+            await userEvent.tab({ shift: true });
+            expect(query.tab('Tab 1')).toHaveFocus();
+
+            // Navigate with ArrowRight to go to the next tab (tab2)
+            await userEvent.keyboard('[ArrowRight]');
+            expect(query.tab('Tab 2')).toHaveFocus();
+
+            // Activate tab with Enter should not work on disabled tab
+            await userEvent.keyboard('{Enter}');
+            expect(query.tab('Tab 2')).toHaveFocus();
+            checkTabActive('Tab 1');
+
+            // Navigate with ArrowRight to go to the next tab (tab3)
+            await userEvent.keyboard('[ArrowRight]');
+            expect(query.tab('Tab 3')).toHaveFocus();
+
+            // Activate tab with Enter
+            await userEvent.keyboard('{Enter}');
+            expect(query.tab('Tab 3')).toHaveFocus();
+            checkTabActive('Tab 3');
+
+            // Focus next should go to active tab panel (tabPanel3)
+            await userEvent.tab();
+            expect(query.tabPanel('Tab 3')).toHaveFocus();
+
+            // Go back to tab3
+            await userEvent.tab({ shift: true });
+            expect(query.tab('Tab 3')).toHaveFocus();
+
+            // Navigate with ArrowRight to loop back to the first tab (tab1)
+            await userEvent.keyboard('[ArrowRight]');
+            expect(query.tab('Tab 1')).toHaveFocus();
+
+            // Navigate with ArrowLeft to loop back to the last tab (tab3)
+            await userEvent.keyboard('[ArrowLeft]');
+            expect(query.tab('Tab 3')).toHaveFocus();
+
+            checkTabActive('Tab 3');
+        });
+    });
+
+    describe('not lazy', () => {
+        it('should render tab panel everytime', () => {
+            setup({ isLazy: false });
+            // Check the first tab is active and all panel are loaded
+            checkTabActive('Tab 1', { isLazy: false });
+        });
+    });
+
+    describe('activate on focus', () => {
+        it('should activate tab on focus', async () => {
+            setup({ shouldActivateOnFocus: true });
+
+            checkTabActive('Tab 1');
+
+            await userEvent.tab();
+            expect(query.tab('Tab 1')).toHaveFocus();
+            checkTabActive('Tab 1');
+
+            await userEvent.keyboard('[ArrowRight]');
+            expect(query.tab('Tab 2')).toHaveFocus();
+            // Active tab not changed since tab 2 is disabled
+            checkTabActive('Tab 1');
+
+            await userEvent.keyboard('[ArrowRight]');
+            expect(query.tab('Tab 3')).toHaveFocus();
+            // Active tab changed to tab 3
+            checkTabActive('Tab 3');
+        });
+    });
+});

package/src/components/tabs/TabProvider.tsx

@@ -0,0 +1,67 @@
+import ReactDOM from 'react-dom';
+import { ReactNode, useEffect, useReducer } from 'react';
+import { INIT_STATE, TabProviderContext, reducer } from './state';
+
+export interface TabProviderProps {
+    /** Active tab index. */
+    activeTabIndex?: number;
+    /** Tab provider children. */
+    children: ReactNode;
+    /** Tab panel children should not render if the tab panel is hidden. */
+    isLazy?: boolean;
+    /** Activate tabs on focus. */
+    shouldActivateOnFocus?: boolean;
+
+    /** Tab change callback. */
+    onChange?(index: number): void;
+}
+
+const DEFAULT_PROPS: Partial<TabProviderProps> = {
+    isLazy: INIT_STATE.isLazy,
+    shouldActivateOnFocus: INIT_STATE.shouldActivateOnFocus,
+};
+
+/**
+ * This component provides a context in which tabs can be defined and linked to their tab panel.
+ *
+ * It does not produce any markup so you can wrap it around any React elements and then split the TabList and TabPanel
+ * components in the react tree.
+ *
+ * @param  props React component props.
+ * @return React element.
+ */
+export const TabProvider: React.FC<TabProviderProps> = (props) => {
+    const { children, onChange, ...propState } = props;
+    const [state, dispatch] = useReducer(reducer, INIT_STATE);
+
+    // On prop state change => dispatch update.
+    useEffect(
+        () => {
+            dispatch({ type: 'update', payload: { ...DEFAULT_PROPS, ...propState } });
+        },
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [dispatch, ...Object.values(propState)],
+    );
+
+    // On active tab index state change => send update to the onChange.
+    useEffect(
+        () => {
+            if (state === INIT_STATE || !onChange || propState.activeTabIndex === state.activeTabIndex) {
+                return;
+            }
+
+            // Escape rendering/useEffect context
+            queueMicrotask(() => {
+                // Wait for React to commit last state changes (avoid looping state update)
+                ReactDOM.flushSync(() => {
+                    onChange(state.activeTabIndex);
+                });
+            });
+        },
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [onChange, state.activeTabIndex],
+    );
+
+    return <TabProviderContext.Provider value={[state, dispatch]}>{children}</TabProviderContext.Provider>;
+};
+TabProvider.defaultProps = DEFAULT_PROPS;

package/src/components/tabs/Tabs.stories.tsx

@@ -0,0 +1,170 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+
+import { Alignment, Button, Dialog, Tab, TabList, TabListLayout, TabPanel, TabProvider } from '@lumx/react';
+import { iconArgType } from '@lumx/react/stories/controls/icons';
+import { getSelectArgType } from '@lumx/react/stories/controls/selectArgType';
+import { withNestedProps } from '@lumx/react/stories/decorators/withNestedProps';
+import { toFlattenProps } from '@lumx/react/stories/utils/toFlattenProps';
+import { withCategory } from '@lumx/react/stories/utils/withCategory';
+import get from 'lodash/get';
+import times from 'lodash/times';
+import { useState } from 'react';
+
+export default {
+    title: 'LumX components/tabs',
+    decorators: [withNestedProps()],
+    parameters: { controls: { sort: 'alpha' } },
+};
+
+/** Default tab behavior with some controllable args */
+export const Default = {
+    render: ({ tabProviderProps, tabListProps, tabProps }: any) => (
+        <TabProvider {...tabProviderProps}>
+            <TabList aria-label="Tab list" {...tabListProps}>
+                <Tab {...tabProps[0]} />
+                <Tab {...tabProps[1]} />
+                <Tab {...tabProps[2]} />
+            </TabList>
+            <TabPanel className="lumx-spacing-padding-huge">{tabProps[0].label} content</TabPanel>
+            <TabPanel className="lumx-spacing-padding-huge">{tabProps[1].label} content</TabPanel>
+            <TabPanel className="lumx-spacing-padding-huge">{tabProps[2].label} content</TabPanel>
+        </TabProvider>
+    ),
+    args: toFlattenProps({
+        tabProps: [
+            { label: 'Tab 1' },
+            {
+                label: 'Tab 2',
+                isDisabled: true,
+            },
+            { label: 'Tab 3' },
+        ],
+    }),
+    argTypes: toFlattenProps({
+        tabProviderProps: withCategory('Tab Provider', {
+            isLazy: { control: 'boolean' },
+            shouldActivateOnFocus: { control: 'boolean' },
+        }),
+        tabListProps: withCategory('Tab List', {
+            layout: getSelectArgType(TabListLayout),
+            position: getSelectArgType([Alignment.left, Alignment.center, Alignment.right]),
+        }),
+        tabProps: times(3, (index) =>
+            withCategory(`Tab ${index + 1}`, {
+                label: { control: 'text' },
+                icon: iconArgType,
+                isDisabled: { control: 'boolean' },
+            }),
+        ),
+    }),
+};
+
+/* Control active tab externally (with activate tab on focus). */
+export const Controlled = {
+    render() {
+        const [activeTab, setActiveTab] = useState(1);
+        const changeActiveTabIndex = (evt: any) => setActiveTab(parseInt(get(evt, 'target.value', '0'), 10));
+
+        const [isLazy, setIsLazy] = useState(true);
+        const changeIsLazy = (evt: any) => setIsLazy(get(evt, 'target.checked'));
+
+        const [shouldActivateOnFocus, setShouldActivateOnFocus] = useState(true);
+        const changeShouldActivateOnFocus = (evt: any) => setShouldActivateOnFocus(get(evt, 'target.checked'));
+
+        return (
+            <>
+                <div>
+                    Active tab index:
+                    <input type="number" min={0} max={2} value={activeTab} onChange={changeActiveTabIndex} />
+                </div>
+
+                <div>
+                    Lazy render tab panel content:
+                    <input type="checkbox" checked={isLazy} onChange={changeIsLazy} />
+                </div>
+
+                <div>
+                    Activate tab on focus:
+                    <input type="checkbox" checked={shouldActivateOnFocus} onChange={changeShouldActivateOnFocus} />
+                </div>
+                <TabProvider
+                    activeTabIndex={activeTab}
+                    onChange={setActiveTab}
+                    isLazy={isLazy}
+                    shouldActivateOnFocus={shouldActivateOnFocus}
+                >
+                    <TabList aria-label="Tab list">
+                        <Tab label="Tab a" />
+                        <Tab label="Tab b" />
+                        <Tab label="Tab c" />
+                    </TabList>
+
+                    <TabPanel className="lumx-spacing-padding-huge">Tab a content</TabPanel>
+                    <TabPanel className="lumx-spacing-padding-huge">Tab b content</TabPanel>
+                    <TabPanel className="lumx-spacing-padding-huge">Tab c content</TabPanel>
+                </TabProvider>
+            </>
+        );
+    },
+    chromatic: { disable: true },
+};
+
+/* Display tabs far from their tab panels. */
+export const SplitTabListAndTabPanels = {
+    render() {
+        const [isOpen, setOpen] = useState(true);
+        const [activeTabIndex, onChange] = useState(1);
+
+        return (
+            <TabProvider activeTabIndex={activeTabIndex} onChange={onChange} isLazy={false}>
+                <Button
+                    onClick={() => {
+                        setOpen(!isOpen);
+                        onChange(1);
+                    }}
+                >
+                    Open dialog with tabs in footer
+                </Button>
+                <Dialog isOpen={isOpen} forceFooterDivider onClose={() => setOpen(false)}>
+                    <TabPanel className="lumx-spacing-padding-huge">Tab 1 content</TabPanel>
+                    <TabPanel className="lumx-spacing-padding-huge">Tab 2 content</TabPanel>
+                    <TabPanel className="lumx-spacing-padding-huge">Tab 3 content</TabPanel>
+
+                    <footer>
+                        <TabList aria-label="Tab list">
+                            <Tab label="Tab 1" />
+                            <Tab label="Tab 2" />
+                            <Tab label="Tab 3" />
+                        </TabList>
+                    </footer>
+                </Dialog>
+            </TabProvider>
+        );
+    },
+    chromatic: { disable: true },
+};
+
+/* Dynamically generate tabs. */
+export const DynamicTabs = {
+    render({ tabCount }: any) {
+        return (
+            <TabProvider>
+                <TabList aria-label="Tab list">
+                    {times(tabCount, (tabNumber) => (
+                        <Tab key={tabNumber} label={`Tab ${tabNumber}`} />
+                    ))}
+                </TabList>
+
+                {times(tabCount, (tabNumber) => (
+                    <TabPanel key={tabNumber} className="lumx-spacing-padding-huge">
+                        Tab {tabNumber} content
+                    </TabPanel>
+                ))}
+            </TabProvider>
+        );
+    },
+    args: {
+        tabCount: 3,
+    },
+    chromatic: { disable: true },
+};

package/src/components/tabs/index.ts

@@ -0,0 +1,4 @@
+export * from './TabProvider';
+export * from './TabList';
+export * from './Tab';
+export * from './TabPanel';