@telefonica/mistica 17.2.0 → 17.4.0

package/src/sidenav-bar-section.tsx

@@ -0,0 +1,98 @@
+'use client';
+import * as React from 'react';
+import classnames from 'classnames';
+import * as styles from './sidenav-bar.css';
+import {useThemeVariant} from './theme-variant-context';
+import {getPrefixedDataAttributes} from './utils/dom';
+import Divider from './divider';
+import {Text2} from './text';
+import {useSidenavBarContext} from './sidenav-bar-context';
+import {useRestWidth} from './sidenav-bar-motion';
+import {getSidenavSectionTitle} from './sidenav-bar-data';
+
+import type {SidenavSectionTitle} from './sidenav-bar-types';
+import type {DataAttributes} from './utils/types';
+
+type SidenavSectionProps = {
+    /**
+     * Section heading, and accessible name of the list of the section. It is mandatory: a screen reader
+     * needs it to tell one section from another. When the sidenav is collapsed the heading closes and the
+     * items move up, but it still names the list. Give `{text, hidden: true}` to keep the name and paint
+     * no heading.
+     */
+    title: SidenavSectionTitle;
+    /** Renders a divider above the section. @default false */
+    dividerTop?: boolean;
+    /** Renders a divider below the section. @default false */
+    dividerBottom?: boolean;
+    /** Navigation items (`SidenavItem` elements).
+     * @see SidenavItem
+     */
+    children: React.ReactNode;
+    dataAttributes?: DataAttributes;
+};
+
+const SidenavSection = ({
+    title,
+    dividerTop,
+    dividerBottom,
+    children,
+    dataAttributes,
+}: SidenavSectionProps): JSX.Element => {
+    const {collapsed, collapseState} = useSidenavBarContext();
+    const variant = useThemeVariant();
+    const {text: titleText, isHeadingVisible} = getSidenavSectionTitle(title);
+    // The title names the list of the section, so the name a screen reader speaks is always the text of
+    // the heading, visible or not. The section itself carries no role and no name: the named list is the
+    // whole structure, as in the second level (see `sidenav-bar-panel.tsx`).
+    const titleId = React.useId();
+    // The title holds the width that it had at rest while the sidenav moves, in both directions, so its
+    // lines stay where they are while its box folds. See `sectionTitleKeepsWidth` for the fallback. A
+    // hidden heading never moves, so it needs no measurement.
+    const isTitleWidthKept = isHeadingVisible && collapseState !== 'expanded';
+    const {ref: titleRef, frozenWidth: titleWidth} = useRestWidth(isTitleWidthKept);
+
+    return (
+        <div
+            className={styles.section}
+            {...getPrefixedDataAttributes({testid: 'SidenavSection', ...dataAttributes})}
+        >
+            {dividerTop && (
+                <div className={styles.sectionDividerTop}>
+                    <Divider />
+                </div>
+            )}
+            <div
+                ref={titleRef}
+                id={titleId}
+                // 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"
+                className={classnames(styles.sectionTitle, styles.sectionTitleVariant[variant], {
+                    [styles.sectionTitleHidden]: !isHeadingVisible,
+                    [styles.sectionTitleCollapsed]: isHeadingVisible && collapsed,
+                    [styles.sectionTitleKeepsWidth]: isTitleWidthKept && titleWidth === undefined,
+                })}
+                style={titleWidth !== undefined ? {width: titleWidth} : undefined}
+            >
+                <div className={styles.sectionTitleContent}>
+                    <Text2 medium color="inherit">
+                        {titleText}
+                    </Text2>
+                </div>
+            </div>
+            {/* The title names the list, and the list gives the count of its items. */}
+            <div className={styles.sectionContent} role="list" aria-labelledby={titleId}>
+                {children}
+            </div>
+            {dividerBottom && (
+                <div className={styles.sectionDividerBottom}>
+                    <Divider />
+                </div>
+            )}
+        </div>
+    );
+};
+
+export {SidenavSection};

package/src/sidenav-bar-types.ts

@@ -0,0 +1,224 @@
+import type {ExclusifyUnion} from './utils/utility-types';
+import type {IconProps} from './utils/types';
+import type {InteractiveProps} from './navigation-shared';
+
+type SidenavAsset = ((props: IconProps) => JSX.Element) | React.ReactElement;
+
+/** Props shared by every navigation item, at any level. */
+type SidenavItemBaseProps = {
+    /** Unique identifier within the sidenav for selection tracking and panel state. */
+    id: string;
+    /** Display text (truncated if too long). */
+    label: string;
+    /** Custom content on right side (e.g., Badge). */
+    rightSlot?: React.ReactNode;
+};
+
+/**
+ * Parent item: it owns the items of the second level, it only opens and closes them, and it cannot
+ * navigate (`href`, `to`, and `onPress` are not allowed).
+ */
+type SidenavParentItemProps = {
+    /** Second-level items (max 1 level, level 0 items only). A parent item cannot navigate. */
+    children: ReadonlyArray<SidenavSecondLevelItem>;
+    /** Initial open state of the children. @default false */
+    defaultOpen?: boolean;
+};
+
+/**
+ * Navigable item: it navigates with exactly one of `href`, `to`, or `onPress`, and it cannot have
+ * children.
+ */
+type SidenavNavigableItemProps = InteractiveProps & {
+    /** Called after navigation (when item has href, to, or onPress). */
+    onNavigate?: () => void | Promise<void>;
+    /** Open link in new tab. Only applies when href or to is set. @default false */
+    newTab?: boolean;
+};
+
+/**
+ * Navigation item data for SidenavBar.
+ *
+ * Supports 2-level nesting:
+ * - **Level 0 items** can have children. They always carry an `asset`, because the collapsed rail shows
+ *   nothing else of them.
+ * - **Level 1 items** (children) cannot have children (leaf nodes). See `SidenavSecondLevelItem`.
+ *
+ * Each item is exactly one of:
+ * - **Parent** — has `children` and only opens/closes them. It cannot navigate, so
+ *   `href`, `to`, and `onPress` are not allowed (enforced by the type).
+ * - **Navigable** — has `href`, `to`, or `onPress`. It cannot have `children`.
+ *
+ * @example
+ * // Navigable item (leaf)
+ * {id: 'home', label: 'Home', asset: IconHome, href: '/', onNavigate: () => {}}
+ *
+ * // Parent item (only opens/closes its children, no navigation prop allowed)
+ * {
+ *   id: 'projects',
+ *   label: 'Projects',
+ *   asset: IconFolder,
+ *   children: [
+ *     {id: 'active', label: 'Active', href: '/projects/active'},
+ *     {id: 'archived', label: 'Archived', href: '/projects/archived'}
+ *   ]
+ * }
+ *
+ * // Item with right slot (e.g., badge)
+ * {id: 'notifications', label: 'Notifications', asset: IconBell, href: '#', rightSlot: <Badge value={5} />}
+ */
+type SidenavFirstLevelItem = SidenavItemBaseProps & {
+    /** Icon component or element. It is the only visible part of the item on the collapsed rail. */
+    asset: SidenavAsset;
+    /** Show asset when expanded (not collapsed). @default true */
+    showAssetWhenExpanded?: boolean;
+} & ExclusifyUnion<SidenavParentItemProps | SidenavNavigableItemProps>;
+
+/**
+ * Second-level item data: a child of a parent item. It is always navigable, and it cannot have children of its
+ * own. See `SidenavFirstLevelItem`.
+ *
+ * The collapsed rail never shows a second-level item, so the asset is optional and `showAssetWhenExpanded` has
+ * no meaning. The `undefined` members let a consumer read both item types through one union.
+ *
+ * @example
+ * {id: 'active', label: 'Active', href: '/projects/active'}
+ */
+type SidenavSecondLevelItem = SidenavItemBaseProps &
+    SidenavNavigableItemProps & {
+        /** Icon component or element. */
+        asset?: SidenavAsset;
+        showAssetWhenExpanded?: undefined;
+        children?: undefined;
+        defaultOpen?: undefined;
+    };
+
+/**
+ * Title of a section. Every section declares one, because it names the list of the section for a screen
+ * reader. A plain string also paints the heading. The object form with `hidden: true` keeps the name and
+ * paints no heading, so only assistive technology reads it.
+ *
+ * @example
+ * // Visible heading, and name of the list
+ * 'Workspace'
+ *
+ * // Name of the list only: no heading appears
+ * {text: 'Workspace', hidden: true}
+ */
+type SidenavSectionTitle =
+    | string
+    | {
+          /** Text of the heading, and name of the list of the section. */
+          text: string;
+          /** Hide the heading. The list keeps this text as its name. @default false */
+          hidden?: boolean;
+      };
+
+/**
+ * Section data that groups navigation items under a title, with optional dividers.
+ *
+ * Sections provide visual organization of items within a SidenavBar.
+ * The title is mandatory, because the list of the section takes its accessible name from it. When the
+ * sidenav is collapsed, the title is hidden visually but remains available to screen readers.
+ *
+ * @example
+ * // Section with a visible title and items
+ * {
+ *   title: 'Workspace',
+ *   dividerTop: true,
+ *   items: [
+ *     {id: 'projects', label: 'Projects', asset: IconFolder, href: '/projects'},
+ *     {id: 'teams', label: 'Teams', asset: IconPeople, href: '/teams'}
+ *   ]
+ * }
+ *
+ * // Section that groups items without a visible heading. Only a screen reader reads the title.
+ * {
+ *   title: {text: 'Workspace', hidden: true},
+ *   items: [{id: 'teams', label: 'Teams', asset: IconPeople, href: '/teams'}]
+ * }
+ */
+type SidenavSection = {
+    /**
+     * Section heading, and accessible name of the list of the section. It is mandatory, because a list
+     * without a name leaves a screen reader with no way to tell one section from another. Give
+     * `{text, hidden: true}` to keep the name and paint no heading.
+     */
+    title: SidenavSectionTitle;
+    /** Show divider above section. The first entry of the body draws none: a line parts two entries. */
+    dividerTop?: boolean;
+    /** Show divider below section. The last entry of the body draws none: a line parts two entries. */
+    dividerBottom?: boolean;
+    /** Navigation items in this section. */
+    items: ReadonlyArray<SidenavFirstLevelItem>;
+};
+
+/**
+ * First-level entry of the sidenav body. The first level admits sections and stand-alone items,
+ * in any order, so an item does not need a section around it.
+ *
+ * Each entry is exactly one of:
+ * - **Section** — has `items` and groups them under a title and optional dividers.
+ * - **Stand-alone item** — a `SidenavFirstLevelItem` placed directly at the first level. It carries no
+ *   title, so it is the entry to use when a group of one item needs no name.
+ *
+ * A stand-alone item aligns with the items of a section, and every first-level entry is
+ * separated from the next one by the same vertical space.
+ *
+ * @example
+ * // A stand-alone item, then a section, then another stand-alone item
+ * [
+ *   {id: 'home', label: 'Home', asset: IconHome, href: '/'},
+ *   {title: 'Workspace', items: [{id: 'teams', label: 'Teams', asset: IconPeople, href: '/teams'}]},
+ *   {id: 'settings', label: 'Settings', asset: IconSettings, href: '/settings'}
+ * ]
+ */
+type SidenavEntry = ExclusifyUnion<SidenavSection | SidenavFirstLevelItem>;
+
+/**
+ * Phase of the collapse motion of the desktop rail. `collapsing` and `expanding` last for the movement of
+ * the rail, and they never appear when motion is off. The mobile top bar always reports `expanded`.
+ */
+type SidenavCollapseState = 'expanded' | 'collapsing' | 'collapsed' | 'expanding';
+
+const isSidenavMoving = (state: SidenavCollapseState): boolean =>
+    state === 'collapsing' || state === 'expanding';
+
+/**
+ * Props of the slots that render per state: the logo, the header slot, the footer slot, and the collapse
+ * action. `collapsed` flips at the first frame of the motion, and `state` tells the phase, so a slot can
+ * keep its content while the rail moves and swap it when the rail rests.
+ */
+type SidenavSlotRenderProps = {
+    /** Target collapsed state. The mobile top bar reports false, because it is not a rail. */
+    collapsed: boolean;
+    /** Phase of the collapse motion. */
+    state: SidenavCollapseState;
+};
+
+/** Props of the logo of the header. The default logo keeps the isotype in both states. */
+type SidenavLogoRenderProps = SidenavSlotRenderProps;
+
+/**
+ * Logo of the header. It takes true for the logo of the skin, false to hide the logo, an element of your
+ * own, or a function that receives the collapse state and returns one logo for each state.
+ */
+type SidenavLogo = React.ReactElement | boolean | ((props: SidenavLogoRenderProps) => React.ReactNode);
+
+/** Content of the header slot or of the footer slot: an element, or a function of the collapse state. */
+type SidenavSlot = React.ReactNode | ((props: SidenavSlotRenderProps) => React.ReactNode);
+
+export type {
+    SidenavAsset,
+    SidenavFirstLevelItem,
+    SidenavSecondLevelItem,
+    SidenavSection,
+    SidenavSectionTitle,
+    SidenavEntry,
+    SidenavLogo,
+    SidenavLogoRenderProps,
+    SidenavSlot,
+    SidenavSlotRenderProps,
+    SidenavCollapseState,
+};
+export {isSidenavMoving};