@telefonica/mistica 17.2.0 → 17.4.0

package/src/sidenav-bar-panel.tsx

@@ -0,0 +1,269 @@
+'use client';
+import * as React from 'react';
+import classnames from 'classnames';
+import * as styles from './sidenav-bar.css';
+import {useSidenavBarContext} from './sidenav-bar-context';
+import {useDialogPanelKeyboard, getItemFocusables} from './sidenav-bar-keyboard';
+import {Portal} from './portal';
+import {Text2} from './text';
+import {listenResize} from './utils/dom';
+import {combineRefs} from './utils/common';
+import {ThemeVariant} from './theme-variant-context';
+
+import type {NonDeprecatedVariant} from './theme-variant-context';
+
+/*
+ * A panel holds the children of a parent item away from its row: `SidenavDialogPanel` floats over the
+ * collapsed rail, and `SidenavDoublePanel` is the second column. The expanded rail opens the children in
+ * place instead, so that form is not a panel.
+ */
+
+/** Minimum distance kept between the panel and the viewport edges. */
+const VIEWPORT_MARGIN = 8;
+
+/**
+ * Closes the dialog panel when the user presses outside of it, or presses the Escape key. A press on a
+ * parent item does not close the panel here: that item toggles the panel itself, or replaces its content.
+ *
+ * The double panel does not use this hook: it is a column of the sidenav, not a floating dialog, so only
+ * a press outside of the whole bar dismisses it. `SidenavBar` owns that rule.
+ */
+const useClosePanelOnOutsideInteraction = (panelElement: HTMLElement | null): void => {
+    const {setPanelOpenForItemId} = useSidenavBarContext();
+
+    React.useEffect(() => {
+        const handleClickOutside = (event: MouseEvent) => {
+            if (!panelElement) {
+                return;
+            }
+            // See the same call in `sidenav-bar.tsx`: the path holds the nodes that the press travelled
+            // through, and not the node that survived until this listener ran.
+            const path = event.composedPath();
+            if (path.includes(panelElement)) {
+                return;
+            }
+            // A press on a parent item lands outside of this panel, but that item owns the panel and
+            // toggles it on its own, so this listener leaves it alone. The marker travels in the path
+            // above, which is why it still reads a row that React already replaced.
+            const isParentItem = path.some(
+                (node) => node instanceof Element && node.matches('[data-parent-item="true"]')
+            );
+            if (!isParentItem) {
+                setPanelOpenForItemId(null);
+            }
+        };
+
+        const handleEscape = (event: KeyboardEvent) => {
+            if (event.key === 'Escape') {
+                setPanelOpenForItemId(null);
+            }
+        };
+
+        document.addEventListener('click', handleClickOutside);
+        document.addEventListener('keydown', handleEscape);
+
+        return () => {
+            document.removeEventListener('click', handleClickOutside);
+            document.removeEventListener('keydown', handleEscape);
+        };
+    }, [panelElement, setPanelOpenForItemId]);
+};
+
+type SidenavDialogPanelProps = {
+    id: string;
+    itemId: string;
+    label: string;
+    containerRef: React.RefObject<HTMLElement | null>;
+    children: React.ReactNode;
+};
+
+/**
+ * A floating panel with the children of a parent item. It is used when the sidenav is collapsed and the
+ * double panel mode is off. The panel is anchored to the top of its trigger whenever it fits.
+ */
+const SidenavDialogPanel = ({
+    id,
+    itemId,
+    label,
+    containerRef,
+    children,
+}: SidenavDialogPanelProps): JSX.Element => {
+    const {setPanelOpenForItemId} = useSidenavBarContext();
+    // `Portal` creates its host element in an effect, so the panel node appears one render after the
+    // panel mounts. Keeping the node in state (instead of in a ref) re-runs the effects that measure
+    // it as soon as it exists.
+    const [panelElement, setPanelElement] = React.useState<HTMLDivElement | null>(null);
+    const [panelPosition, setPanelPosition] = React.useState<{top: number; left: number} | null>(null);
+    // The visible title names the list, so the name a screen reader speaks is always the text the user
+    // sees. The panel itself carries no role and no name: the named list is the whole structure.
+    const titleId = React.useId();
+
+    useClosePanelOnOutsideInteraction(panelElement);
+    // The first item of the panel takes the focus only once the panel stands where it belongs: it stays
+    // hidden until the effect below measures it, and a hidden element takes no focus.
+    useDialogPanelKeyboard({
+        panelElement,
+        containerRef,
+        itemId,
+        isPositioned: panelPosition !== null,
+        onClose: () => setPanelOpenForItemId(null),
+    });
+
+    // The panel opens aligned with its trigger, but a trigger close to the bottom edge pushes the
+    // panel out of the viewport. The top is therefore clamped to the lowest position where the whole
+    // panel still fits, so every item stays readable and clickable. A panel taller than the viewport
+    // starts at the top margin and scrolls inside its own `maxHeight`.
+    React.useEffect(() => {
+        const updatePosition = () => {
+            const container = containerRef.current;
+            if (!container) return;
+
+            const triggerElement = container.querySelector(`[data-sidenav-item-id="${itemId}"]`);
+            if (!triggerElement) return;
+
+            const containerRect = container.getBoundingClientRect();
+            const triggerRect = triggerElement.getBoundingClientRect();
+            const panelHeight = panelElement?.offsetHeight ?? 0;
+            const lowestFittingTop = window.innerHeight - panelHeight - VIEWPORT_MARGIN;
+
+            setPanelPosition({
+                top: Math.max(VIEWPORT_MARGIN, Math.min(triggerRect.top, lowestFittingTop)),
+                left: containerRect.right + 8,
+            });
+        };
+
+        updatePosition();
+
+        const stopListeningResize = panelElement ? listenResize(panelElement, updatePosition) : undefined;
+        window.addEventListener('resize', updatePosition);
+        return () => {
+            stopListeningResize?.();
+            window.removeEventListener('resize', updatePosition);
+        };
+    }, [itemId, containerRef, panelElement]);
+
+    return (
+        <Portal>
+            <div
+                ref={setPanelElement}
+                id={id}
+                className={styles.dialogPanel}
+                data-sidenav-dialog-panel={itemId}
+                style={
+                    panelPosition
+                        ? {
+                              position: 'fixed' as const,
+                              top: panelPosition.top,
+                              left: panelPosition.left,
+                          }
+                        : // The panel needs its own height to know whether it fits below the
+                          // trigger, so it stays hidden for the render that precedes the
+                          // measurement instead of flashing at a placeholder position.
+                          {
+                              position: 'fixed' as const,
+                              top: 0,
+                              left: 0,
+                              visibility: 'hidden' as const,
+                          }
+                }
+            >
+                <ThemeVariant variant="default">
+                    <div
+                        id={titleId}
+                        className={classnames(styles.dialogPanelTitle, styles.sectionTitleVariant.default)}
+                        // The list already speaks this text as its name, so the title steps out of the
+                        // reading order. The name survives: `aria-labelledby` reads a hidden element that
+                        // it references directly.
+                        aria-hidden="true"
+                    >
+                        <Text2 medium color="inherit">
+                            {label}
+                        </Text2>
+                    </div>
+                    {/* The title names the list, and the list gives the count of its items. */}
+                    <div className={styles.panelRows} role="list" aria-labelledby={titleId}>
+                        {children}
+                    </div>
+                </ThemeVariant>
+            </div>
+        </Portal>
+    );
+};
+
+type SidenavDoublePanelProps = {
+    itemId: string;
+    label: string;
+    variant: NonDeprecatedVariant;
+    backgroundColor?: string;
+    children: React.ReactNode;
+};
+
+/**
+ * The second column of the sidenav, with the children of the open parent item. It is used in double
+ * panel mode, both when the sidenav is expanded and when it is collapsed.
+ *
+ * It forwards its ref because `SidenavBar` slides it out and back in with a `CSSTransition`, which needs
+ * the node of the column. The column itself carries no padding: an inner box of the width of the open
+ * column holds it instead, so the column can narrow to zero without reflowing its content.
+ */
+const SidenavDoublePanel = React.forwardRef<HTMLDivElement, SidenavDoublePanelProps>(
+    ({itemId, label, variant, backgroundColor, children}, ref) => {
+        const {containerRef} = useSidenavBarContext();
+        // The bar owns the forwarded ref for its transition; this one lets the column read its own node.
+        const columnRef = React.useRef<HTMLDivElement>(null);
+        // The visible title names the list, so the name a screen reader speaks is always the text the
+        // user sees. The column itself carries no role and no name: the named list is the whole structure.
+        const titleId = React.useId();
+
+        // The first item takes the focus when the column opens (the bar mounts it then), and again when
+        // the column moves to another parent, so a screen reader announces the named list that the user
+        // entered. It only takes a focus that already belongs to the sidenav, or one that fell to the
+        // body when the collapsed rail replaced the trigger row. An app that moves the selection from
+        // elsewhere on the page opens this column too, and it must not drag the user out of the place
+        // they were reading.
+        React.useEffect(() => {
+            const column = columnRef.current;
+            const container = containerRef.current;
+            if (!column || !container) {
+                return;
+            }
+            const active = document.activeElement;
+            if (active && active !== document.body && !container.contains(active)) {
+                return;
+            }
+            getItemFocusables(column)[0]?.focus();
+        }, [itemId, containerRef]);
+
+        return (
+            <div
+                ref={combineRefs(ref, columnRef)}
+                className={classnames(styles.doublePanelColumn, styles.regionBackground[variant])}
+                style={backgroundColor ? {backgroundColor} : undefined}
+                // Marks the column with the id of the item that owns it, so the keyboard of the rail finds
+                // the list of a trigger, and the trigger of a list.
+                data-sidenav-double-panel={itemId}
+            >
+                <div className={styles.doublePanelContent}>
+                    <div
+                        id={titleId}
+                        className={classnames(styles.doublePanelTitle, styles.sectionTitleVariant[variant])}
+                        // The list already speaks this text as its name, so the title steps out of the
+                        // reading order. The name survives: `aria-labelledby` reads a hidden element that
+                        // it references directly.
+                        aria-hidden="true"
+                    >
+                        <Text2 medium color="inherit">
+                            {label}
+                        </Text2>
+                    </div>
+                    {/* The title names the list, and the list gives the count of its items. */}
+                    <div className={styles.panelRows} role="list" aria-labelledby={titleId}>
+                        {children}
+                    </div>
+                </div>
+            </div>
+        );
+    }
+);
+
+export {SidenavDialogPanel, SidenavDoublePanel};

package/src/sidenav-bar-row.tsx

@@ -0,0 +1,272 @@
+'use client';
+import * as React from 'react';
+import classnames from 'classnames';
+import * as styles from './sidenav-bar.css';
+import {useSidenavBarContext} from './sidenav-bar-context';
+import {useRestWidth} from './sidenav-bar-motion';
+import {getPrefixedDataAttributes} from './utils/dom';
+import {useThemeVariant} from './theme-variant-context';
+import Touchable from './touchable';
+import Tooltip from './tooltip';
+import {Text2} from './text';
+import IconChevron from './icons/icon-chevron';
+
+import type {DataAttributes} from './utils/types';
+import type {SidenavAsset} from './sidenav-bar-types';
+
+/**
+ * Where a row stands. The rail (a first-level row) and the accordion (a second-level row under its parent)
+ * move with the bar when it collapses. A panel (the dialog panel, or the second column) never moves with
+ * it, so a row of a panel always sees a bar at rest expanded.
+ */
+type SidenavRowPlacement = 'rail' | 'accordion' | 'panel';
+
+/** Props that make the row navigate. The item builds them with `useSidenavNavigation`. */
+type SidenavRowNavigationProps =
+    | {onPress: () => Promise<void>}
+    | {href: string; newTab?: boolean; onNavigate: () => Promise<void>}
+    | {to: string; newTab?: boolean; onNavigate: () => Promise<void>};
+
+/** Props that make the row open and close its children instead of navigating. */
+type SidenavRowToggleProps = {
+    onPress: () => void;
+    expanded: boolean;
+    /** Id of the dialog panel that the row opens, when it opens one. */
+    controls?: string;
+};
+
+type SidenavRowProps = {
+    /** Id of the item, written to the DOM so the keyboard code and the tests find the row. */
+    id?: string;
+    label: string;
+    asset?: SidenavAsset;
+    /** Hide the asset without removing it from the data. The collapsed rail always shows it. */
+    showAsset?: boolean;
+    rightSlot?: React.ReactNode;
+    /** Paint the selected background. A parent takes it for a hidden selected descendant. */
+    showBackground?: boolean;
+    /** Paint the accent bar. Only the selected item itself takes it, never a parent of it. */
+    showAccent?: boolean;
+    /** Id written on the label, so the accordion list can take its name from it. */
+    labelId?: string;
+    /** Render the chevron of a parent item, rotated when its children are open. */
+    chevron?: {rotated: boolean; direction: 'down' | 'right'};
+    /**
+     * Where the row stands, which tells it whether the collapse motion of the bar reaches it. The context
+     * gives the phase of that motion, and it cannot tell the place.
+     */
+    placement: SidenavRowPlacement;
+    /** Show the label as a tooltip on the right, for the collapsed rail. */
+    tooltip?: boolean;
+    /** Present when the row navigates. Mutually exclusive with `toggle`. */
+    navigation?: SidenavRowNavigationProps;
+    /** Present when the row opens and closes its children. Mutually exclusive with `navigation`. */
+    toggle?: SidenavRowToggleProps;
+    /** True when the row is the current page, or holds it among its children. */
+    current?: boolean;
+    dataAttributes?: DataAttributes;
+};
+
+/**
+ * The visible row of an item, at both levels: the accent, the asset, the label, the right slot, the
+ * chevron, and the tooltip of the collapsed rail. It holds no state: `SidenavFirstLevelItem` and
+ * `SidenavSecondLevelItem` decide what the row shows, and this component paints it.
+ */
+const SidenavRow = ({
+    id,
+    label,
+    asset,
+    showAsset = true,
+    rightSlot,
+    showBackground = false,
+    showAccent = false,
+    labelId,
+    chevron,
+    placement,
+    tooltip = false,
+    navigation,
+    toggle,
+    current = false,
+    dataAttributes,
+}: SidenavRowProps): JSX.Element => {
+    // Read from context, not from `SidenavBar`: the floating panel restores the default variant.
+    const variant = useThemeVariant();
+
+    // The row paints the collapsed rail (the asset alone, and the label faded but in the DOM) when the
+    // bar is collapsed or collapsing, and it holds the width of its label whenever the bar does not rest
+    // expanded. A row of a panel never moves with the bar, so it sees a bar at rest expanded.
+    const {collapseState: barCollapseState} = useSidenavBarContext();
+    const collapseState = placement === 'panel' ? 'expanded' : barCollapseState;
+    const collapsed = collapseState === 'collapsed' || collapseState === 'collapsing';
+    // The label keeps the width of its text while the bar moves in either direction, and wraps only at
+    // rest expanded. See `itemLabelKeepsWidth`.
+    const labelWidthFixed = collapseState !== 'expanded';
+
+    let assetContent: React.ReactNode = null;
+    if (typeof asset === 'function') {
+        const Asset = asset;
+        assetContent = <Asset size={20} color="currentColor" />;
+    } else if (asset) {
+        assetContent = asset;
+    }
+    const assetElement =
+        showAsset && assetContent ? (
+            <span className={classnames(styles.itemAsset, styles.itemAssetVariant[variant])}>
+                {assetContent}
+            </span>
+        ) : null;
+
+    // The collapsed label stays in the DOM: a screen reader still reads it, and the fade needs it.
+    const {ref: labelRef, frozenWidth: labelWidth} = useRestWidth(labelWidthFixed);
+    const labelNode = (
+        <div
+            ref={labelRef}
+            id={labelId}
+            className={classnames(styles.itemLabel, {
+                [styles.itemLabelCollapsed]: collapsed,
+                [styles.itemLabelFrozenWidth]: labelWidth !== undefined,
+                [styles.itemLabelKeepsWidth]: labelWidthFixed && labelWidth === undefined,
+            })}
+            style={labelWidth !== undefined ? {width: labelWidth} : undefined}
+        >
+            <div className={styles.itemLabelContent}>
+                <Text2 regular color="inherit">
+                    {label}
+                </Text2>
+            </div>
+        </div>
+    );
+
+    const touchableClassName = classnames(styles.itemTouchable, styles.itemTouchableVariant[variant], {
+        [styles.itemTouchableSelected[variant]]: showBackground,
+        [styles.itemTouchableCollapsed]: collapsed,
+    });
+
+    const rowContent = (
+        <>
+            {assetElement}
+            {labelNode}
+            {rightSlot && (
+                <span
+                    className={classnames(styles.itemRightSlot, {
+                        [styles.itemRightSlotCollapsed]: collapsed,
+                    })}
+                >
+                    {rightSlot}
+                </span>
+            )}
+            {chevron && (
+                <span
+                    className={classnames(styles.itemChevron, styles.itemChevronVariant[variant], {
+                        [styles.itemChevronRotated]: chevron.rotated,
+                        [styles.itemChevronCollapsed]: collapsed,
+                    })}
+                    aria-hidden="true"
+                >
+                    <IconChevron size={16} color="currentColor" direction={chevron.direction} />
+                </span>
+            )}
+        </>
+    );
+
+    const ariaCurrent = current ? ('page' as const) : undefined;
+
+    const interactiveRow = (() => {
+        if (toggle) {
+            return (
+                <Touchable
+                    className={touchableClassName}
+                    onPress={toggle.onPress}
+                    aria-expanded={toggle.expanded}
+                    aria-controls={toggle.controls}
+                    aria-label={label}
+                    dataAttributes={{'parent-item': 'true'}}
+                >
+                    {rowContent}
+                </Touchable>
+            );
+        }
+
+        if (navigation) {
+            return (
+                <Touchable
+                    {...navigation}
+                    className={touchableClassName}
+                    aria-current={ariaCurrent}
+                    aria-label={collapsed ? label : undefined}
+                >
+                    {rowContent}
+                </Touchable>
+            );
+        }
+
+        return (
+            <div className={touchableClassName} aria-current={ariaCurrent}>
+                {rowContent}
+            </div>
+        );
+    })();
+
+    const rowDataAttributes: DataAttributes = {testid: 'SidenavItem', ...dataAttributes};
+    if (id) {
+        rowDataAttributes['sidenav-item-id'] = id;
+    }
+
+    return (
+        <div className={styles.itemRow} {...getPrefixedDataAttributes(rowDataAttributes)}>
+            {showAccent && (
+                <div className={classnames(styles.itemAccent, styles.itemAccentVariant[variant])} />
+            )}
+            {tooltip ? (
+                <Tooltip
+                    position="right"
+                    description={label}
+                    target={interactiveRow}
+                    // Without `minWidth: 0` the wrapper never shrinks below its content, past the rail.
+                    targetStyle={{flex: 1, minWidth: 0}}
+                />
+            ) : (
+                interactiveRow
+            )}
+        </div>
+    );
+};
+
+/**
+ * Builds the props that make a row navigate. Every navigation of the sidenav reports the new selection
+ * and closes the open panel in one call, so the selection does not reopen the column that the press
+ * closed.
+ */
+const useSidenavNavigation = (
+    itemId: string,
+    props: {
+        onPress?: () => void;
+        href?: string;
+        to?: string;
+        newTab?: boolean;
+        onNavigate?: () => void | Promise<void>;
+    }
+): SidenavRowNavigationProps | undefined => {
+    const {selectItemAndClosePanel} = useSidenavBarContext();
+
+    const wrapNavCallback = (callback?: () => void | Promise<void>): (() => Promise<void>) => {
+        return async () => {
+            selectItemAndClosePanel(itemId ?? null);
+            await callback?.();
+        };
+    };
+
+    if (props.onPress) {
+        return {onPress: wrapNavCallback(props.onPress)};
+    }
+    if (props.href !== undefined) {
+        return {href: props.href, newTab: props.newTab, onNavigate: wrapNavCallback(props.onNavigate)};
+    }
+    if (props.to !== undefined) {
+        return {to: props.to, newTab: props.newTab, onNavigate: wrapNavCallback(props.onNavigate)};
+    }
+    return undefined;
+};
+
+export {SidenavRow, useSidenavNavigation};
+export type {SidenavRowPlacement};

package/src/sidenav-bar-second-level-item.tsx

@@ -0,0 +1,99 @@
+'use client';
+import * as React from 'react';
+import {useSidenavBarContext} from './sidenav-bar-context';
+import {SidenavRow, useSidenavNavigation} from './sidenav-bar-row';
+
+import type {SidenavRowPlacement} from './sidenav-bar-row';
+import type {DataAttributes} from './utils/types';
+import type {SidenavAsset, SidenavSecondLevelItem as SidenavSecondLevelItemData} from './sidenav-bar-types';
+
+/** A second-level row never stands on the rail: it stands in the accordion of its parent, or in a panel. */
+type SidenavSecondLevelPlacement = Exclude<SidenavRowPlacement, 'rail'>;
+
+type SidenavSecondLevelItemProps = {
+    /** Unique identifier for selection tracking. */
+    id: string;
+    /** Display text. A text longer than the row wraps over several lines, and it never truncates. */
+    label: string;
+    /** Icon component or element. The collapsed rail never shows a second-level row, so it is optional. */
+    asset?: SidenavAsset;
+    /** Custom content on the right side (e.g., Badge). */
+    rightSlot?: React.ReactNode;
+    /**
+     * Where the row stands. The accordion of its parent opens in place and moves with the bar; a panel
+     * (the dialog panel, or the second column) never moves with it. The context alone cannot tell the two
+     * apart, so the parent names the place.
+     */
+    placement: SidenavSecondLevelPlacement;
+    onPress?: () => void;
+    href?: string;
+    to?: string;
+    /** Open link in new tab. @default false */
+    newTab?: boolean;
+    /** Called after navigation. */
+    onNavigate?: () => void | Promise<void>;
+    dataAttributes?: DataAttributes;
+};
+
+/**
+ * A second-level item. It always navigates, and it never has children of its own, so it holds no state:
+ * it reads the current selection and renders one row.
+ */
+const SidenavSecondLevelItem = ({
+    id,
+    label,
+    asset,
+    rightSlot,
+    placement,
+    dataAttributes,
+    ...navigationProps
+}: SidenavSecondLevelItemProps): JSX.Element => {
+    const {selectedItemId} = useSidenavBarContext();
+    const navigation = useSidenavNavigation(id, navigationProps);
+    const selected = selectedItemId === id;
+
+    return (
+        <div role="listitem">
+            <SidenavRow
+                id={id}
+                label={label}
+                asset={asset}
+                rightSlot={rightSlot}
+                showBackground={selected}
+                showAccent={selected}
+                current={selected}
+                // A row of the accordion moves with the bar like the row of its parent: it folds and fades,
+                // and its label keeps its width. Without this, the labels re-wrap as the rail narrows, the
+                // rows grow, and the accordion bounces while it folds. A row of a panel never moves.
+                placement={placement}
+                navigation={navigation}
+                dataAttributes={dataAttributes}
+            />
+        </div>
+    );
+};
+
+/**
+ * Renders a second-level item from its data. The accordion of a parent item, the dialog panel and the second
+ * column list the same items, so this is the one place that maps the data to the props of the row.
+ */
+const renderSidenavSecondLevelItem = (
+    item: SidenavSecondLevelItemData,
+    {placement}: {placement: SidenavSecondLevelPlacement}
+): React.ReactElement => (
+    <SidenavSecondLevelItem
+        key={item.id}
+        id={item.id}
+        label={item.label}
+        asset={item.asset}
+        rightSlot={item.rightSlot}
+        placement={placement}
+        href={item.href}
+        to={item.to}
+        onPress={item.onPress}
+        newTab={item.newTab}
+        onNavigate={item.onNavigate}
+    />
+);
+
+export {SidenavSecondLevelItem, renderSidenavSecondLevelItem};