@vectara/vectara-ui 16.3.1 → 16.4.1

package/lib/components/index.d.ts

@@ -79,6 +79,8 @@ import { VuiStepsVertical, StepsVertical, StepVerticalStatus } from "./stepsVert
 import { SKELETON_COLOR, VuiSkeleton } from "./skeleton/Skeleton";
 import { VuiSummary, VuiSummaryCitation } from "./summary";
 import { VuiTable } from "./table/Table";
+import { VuiSpans } from "./spans/Spans";
+import { SpansRow } from "./spans/types";
 import { VuiTab } from "./tabs/Tab";
 import { VuiTabbedRoutes } from "./tabs/TabbedRoutes";
 import { VuiTabs } from "./tabs/Tabs";
@@ -95,5 +97,5 @@ import { VuiInfoTooltip } from "./tooltip/InfoTooltip";
 import { VuiTopicButton } from "./topicButton/TopicButton";
 import { copyToClipboard } from "../utils/copyToClipboard";
 import { toRgb, toRgba } from "./context/Theme";
-export type { AnchorSide, AppContentPadding, ButtonColor, CalloutColor, ChatLanguage, ChatStyle, ChatTurn, CheckboxConfig, CodeEditorColorConfig, CodeEditorError, CodeLanguage, InfoListItemType, InfoListType, InfoTableColumnAlign, InfoTableRow, InfoTableRowType, LinkProps, MenuItem, OptionListItem, Pagination, RadioButtonConfig, SearchResult, SearchSuggestion, Sections, SectionItem, Stat, StepStatus, StepSize, Steps, StepsVertical, StepVerticalStatus, TabSize, Tree, TreeItem };
-export { BADGE_COLOR, BUTTON_COLOR, BUTTON_SIZE, CALLOUT_COLOR, CALLOUT_SIZE, ICON_COLOR, ICON_SIZE, ICON_TYPE, PROGRESS_BAR_COLOR, SPACER_SIZE, SPINNER_COLOR, SKELETON_COLOR, SPINNER_SIZE, TAB_SIZE, TEXT_COLOR, TEXT_SIZE, TITLE_SIZE, addNotification, copyToClipboard, generateTokensProvider, toRgb, toRgba, VuiAccordion, VuiAccountButton, VuiAppContent, VuiAppHeader, VuiAppLayout, VuiAppSideNav, VuiAppSideNavLink, VuiAppSideNavGroup, VuiBadge, VuiButtonPrimary, VuiButtonSecondary, VuiButtonTertiary, VuiIconButton, VuiCallout, VuiCard, VuiChat, VuiCheckbox, VuiCode, VuiCodeEditor, VuiComplexConfigurationButton, VuiContextProvider, VuiCopyButton, VuiDatePicker, VuiDateRangePicker, VuiDrawer, VuiErrorBoundary, VuiFlexContainer, VuiFlexItem, VuiFormGroup, VuiGrid, VuiGridItem, VuiHorizontalRule, VuiIcon, VuiImage, VuiImagePreview, VuiInfoList, VuiInfoListItem, VuiInfoMenu, VuiInfoTable, VuiInfoTooltip, VuiInProgress, VuiItemsInput, VuiLabel, VuiLink, VuiLinkInternal, VuiList, VuiMenu, VuiMenuItem, VuiModal, VuiNotifications, VuiNumberInput, VuiOptionsButton, VuiOptionsList, VuiOptionsListItem, VuiPagination, VuiPanel, VuiPasswordInput, VuiPopover, VuiPortal, VuiProgressBar, VuiPrompt, VuiRadioButton, VuiScreenBlock, VuiSearchInput, VuiSearchResult, VuiSearchSelect, VuiSelect, VuiSetting, VuiSimpleCard, VuiSimpleGrid, VuiSpacer, VuiSpinner, VuiStat, VuiStatList, VuiStatus, VuiSteps, VuiStepsVertical, VuiSummary, VuiSkeleton, VuiSummaryCitation, VuiSuperCheckboxGroup, VuiSuperRadioGroup, VuiTable, VuiTab, VuiTabbedRoutes, VuiTabs, VuiTabsNavigator, VuiText, VuiTextArea, VuiTextColor, VuiTextInput, VuiTimeline, VuiTimelineItem, VuiTitle, VuiToggle, VuiTooltip, VuiTopicButton };
+export type { AnchorSide, AppContentPadding, ButtonColor, CalloutColor, ChatLanguage, ChatStyle, ChatTurn, CheckboxConfig, CodeEditorColorConfig, CodeEditorError, CodeLanguage, InfoListItemType, InfoListType, InfoTableColumnAlign, InfoTableRow, InfoTableRowType, LinkProps, MenuItem, OptionListItem, Pagination, RadioButtonConfig, SearchResult, SearchSuggestion, Sections, SectionItem, SpansRow, Stat, StepStatus, StepSize, Steps, StepsVertical, StepVerticalStatus, TabSize, Tree, TreeItem };
+export { BADGE_COLOR, BUTTON_COLOR, BUTTON_SIZE, CALLOUT_COLOR, CALLOUT_SIZE, ICON_COLOR, ICON_SIZE, ICON_TYPE, PROGRESS_BAR_COLOR, SPACER_SIZE, SPINNER_COLOR, SKELETON_COLOR, SPINNER_SIZE, TAB_SIZE, TEXT_COLOR, TEXT_SIZE, TITLE_SIZE, addNotification, copyToClipboard, generateTokensProvider, toRgb, toRgba, VuiAccordion, VuiAccountButton, VuiAppContent, VuiAppHeader, VuiAppLayout, VuiAppSideNav, VuiAppSideNavLink, VuiAppSideNavGroup, VuiBadge, VuiButtonPrimary, VuiButtonSecondary, VuiButtonTertiary, VuiIconButton, VuiCallout, VuiCard, VuiChat, VuiCheckbox, VuiCode, VuiCodeEditor, VuiComplexConfigurationButton, VuiContextProvider, VuiCopyButton, VuiDatePicker, VuiDateRangePicker, VuiDrawer, VuiErrorBoundary, VuiFlexContainer, VuiFlexItem, VuiFormGroup, VuiGrid, VuiGridItem, VuiHorizontalRule, VuiIcon, VuiImage, VuiImagePreview, VuiInfoList, VuiInfoListItem, VuiInfoMenu, VuiInfoTable, VuiInfoTooltip, VuiInProgress, VuiItemsInput, VuiLabel, VuiLink, VuiLinkInternal, VuiList, VuiMenu, VuiMenuItem, VuiModal, VuiNotifications, VuiNumberInput, VuiOptionsButton, VuiOptionsList, VuiOptionsListItem, VuiPagination, VuiPanel, VuiPasswordInput, VuiPopover, VuiPortal, VuiProgressBar, VuiPrompt, VuiRadioButton, VuiScreenBlock, VuiSearchInput, VuiSearchResult, VuiSearchSelect, VuiSelect, VuiSetting, VuiSimpleCard, VuiSimpleGrid, VuiSpacer, VuiSpans, VuiSpinner, VuiStat, VuiStatList, VuiStatus, VuiSteps, VuiStepsVertical, VuiSummary, VuiSkeleton, VuiSummaryCitation, VuiSuperCheckboxGroup, VuiSuperRadioGroup, VuiTable, VuiTab, VuiTabbedRoutes, VuiTabs, VuiTabsNavigator, VuiText, VuiTextArea, VuiTextColor, VuiTextInput, VuiTimeline, VuiTimelineItem, VuiTitle, VuiToggle, VuiTooltip, VuiTopicButton };

package/lib/components/index.js

@@ -72,6 +72,7 @@ import { VuiStepsVertical } from "./stepsVertical/StepsVertical";
 import { SKELETON_COLOR, VuiSkeleton } from "./skeleton/Skeleton";
 import { VuiSummary, VuiSummaryCitation } from "./summary";
 import { VuiTable } from "./table/Table";
+import { VuiSpans } from "./spans/Spans";
 import { VuiTab } from "./tabs/Tab";
 import { VuiTabbedRoutes } from "./tabs/TabbedRoutes";
 import { VuiTabs } from "./tabs/Tabs";
@@ -88,4 +89,4 @@ import { VuiInfoTooltip } from "./tooltip/InfoTooltip";
 import { VuiTopicButton } from "./topicButton/TopicButton";
 import { copyToClipboard } from "../utils/copyToClipboard";
 import { toRgb, toRgba } from "./context/Theme";
-export { BADGE_COLOR, BUTTON_COLOR, BUTTON_SIZE, CALLOUT_COLOR, CALLOUT_SIZE, ICON_COLOR, ICON_SIZE, ICON_TYPE, PROGRESS_BAR_COLOR, SPACER_SIZE, SPINNER_COLOR, SKELETON_COLOR, SPINNER_SIZE, TAB_SIZE, TEXT_COLOR, TEXT_SIZE, TITLE_SIZE, addNotification, copyToClipboard, generateTokensProvider, toRgb, toRgba, VuiAccordion, VuiAccountButton, VuiAppContent, VuiAppHeader, VuiAppLayout, VuiAppSideNav, VuiAppSideNavLink, VuiAppSideNavGroup, VuiBadge, VuiButtonPrimary, VuiButtonSecondary, VuiButtonTertiary, VuiIconButton, VuiCallout, VuiCard, VuiChat, VuiCheckbox, VuiCode, VuiCodeEditor, VuiComplexConfigurationButton, VuiContextProvider, VuiCopyButton, VuiDatePicker, VuiDateRangePicker, VuiDrawer, VuiErrorBoundary, VuiFlexContainer, VuiFlexItem, VuiFormGroup, VuiGrid, VuiGridItem, VuiHorizontalRule, VuiIcon, VuiImage, VuiImagePreview, VuiInfoList, VuiInfoListItem, VuiInfoMenu, VuiInfoTable, VuiInfoTooltip, VuiInProgress, VuiItemsInput, VuiLabel, VuiLink, VuiLinkInternal, VuiList, VuiMenu, VuiMenuItem, VuiModal, VuiNotifications, VuiNumberInput, VuiOptionsButton, VuiOptionsList, VuiOptionsListItem, VuiPagination, VuiPanel, VuiPasswordInput, VuiPopover, VuiPortal, VuiProgressBar, VuiPrompt, VuiRadioButton, VuiScreenBlock, VuiSearchInput, VuiSearchResult, VuiSearchSelect, VuiSelect, VuiSetting, VuiSimpleCard, VuiSimpleGrid, VuiSpacer, VuiSpinner, VuiStat, VuiStatList, VuiStatus, VuiSteps, VuiStepsVertical, VuiSummary, VuiSkeleton, VuiSummaryCitation, VuiSuperCheckboxGroup, VuiSuperRadioGroup, VuiTable, VuiTab, VuiTabbedRoutes, VuiTabs, VuiTabsNavigator, VuiText, VuiTextArea, VuiTextColor, VuiTextInput, VuiTimeline, VuiTimelineItem, VuiTitle, VuiToggle, VuiTooltip, VuiTopicButton };
+export { BADGE_COLOR, BUTTON_COLOR, BUTTON_SIZE, CALLOUT_COLOR, CALLOUT_SIZE, ICON_COLOR, ICON_SIZE, ICON_TYPE, PROGRESS_BAR_COLOR, SPACER_SIZE, SPINNER_COLOR, SKELETON_COLOR, SPINNER_SIZE, TAB_SIZE, TEXT_COLOR, TEXT_SIZE, TITLE_SIZE, addNotification, copyToClipboard, generateTokensProvider, toRgb, toRgba, VuiAccordion, VuiAccountButton, VuiAppContent, VuiAppHeader, VuiAppLayout, VuiAppSideNav, VuiAppSideNavLink, VuiAppSideNavGroup, VuiBadge, VuiButtonPrimary, VuiButtonSecondary, VuiButtonTertiary, VuiIconButton, VuiCallout, VuiCard, VuiChat, VuiCheckbox, VuiCode, VuiCodeEditor, VuiComplexConfigurationButton, VuiContextProvider, VuiCopyButton, VuiDatePicker, VuiDateRangePicker, VuiDrawer, VuiErrorBoundary, VuiFlexContainer, VuiFlexItem, VuiFormGroup, VuiGrid, VuiGridItem, VuiHorizontalRule, VuiIcon, VuiImage, VuiImagePreview, VuiInfoList, VuiInfoListItem, VuiInfoMenu, VuiInfoTable, VuiInfoTooltip, VuiInProgress, VuiItemsInput, VuiLabel, VuiLink, VuiLinkInternal, VuiList, VuiMenu, VuiMenuItem, VuiModal, VuiNotifications, VuiNumberInput, VuiOptionsButton, VuiOptionsList, VuiOptionsListItem, VuiPagination, VuiPanel, VuiPasswordInput, VuiPopover, VuiPortal, VuiProgressBar, VuiPrompt, VuiRadioButton, VuiScreenBlock, VuiSearchInput, VuiSearchResult, VuiSearchSelect, VuiSelect, VuiSetting, VuiSimpleCard, VuiSimpleGrid, VuiSpacer, VuiSpans, VuiSpinner, VuiStat, VuiStatList, VuiStatus, VuiSteps, VuiStepsVertical, VuiSummary, VuiSkeleton, VuiSummaryCitation, VuiSuperCheckboxGroup, VuiSuperRadioGroup, VuiTable, VuiTab, VuiTabbedRoutes, VuiTabs, VuiTabsNavigator, VuiText, VuiTextArea, VuiTextColor, VuiTextInput, VuiTimeline, VuiTimelineItem, VuiTitle, VuiToggle, VuiTooltip, VuiTopicButton };

package/lib/components/modal/Modal.js

@@ -59,11 +59,20 @@ export const VuiModal = (_a) => {
             onClose === null || onClose === void 0 ? void 0 : onClose();
         }, 0);
     };
+    // Handle outside clicks, but ignore clicks on notifications.
+    const handleClickOutside = (event) => {
+        const target = event.target;
+        // Check if the click is within a notification.
+        if (target.closest("[data-awareness='notification']")) {
+            return;
+        }
+        onCloseDelayed();
+    };
     const containerClasses = classNames("vuiModalContainer", {
         "vuiModalContainer-isLoaded": showTransition
     });
     const classes = classNames("vuiModal", `vuiModal--${color}`, `vuiModal--${size}`, className);
-    return (_jsx(VuiPortal, { children: (isOpen || isContentVisible || showTransition) && (_jsx(VuiScreenBlock, Object.assign({ type: "modal", isHidden: !isOpen }, { children: _jsx(FocusOn, Object.assign({ onEscapeKey: onCloseDelayed, onClickOutside: canClickOutsideToClose ? onCloseDelayed : undefined, 
+    return (_jsx(VuiPortal, { children: (isOpen || isContentVisible || showTransition) && (_jsx(VuiScreenBlock, Object.assign({ type: "modal", isHidden: !isOpen }, { children: _jsx(FocusOn, Object.assign({ onEscapeKey: onCloseDelayed, onClickOutside: canClickOutsideToClose ? handleClickOutside : undefined, 
                 // Enable manual focus return to work.
                 returnFocus: false, 
                 // Enable focus on contents when it's open,

package/lib/components/spans/Spans.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+import { Column } from "../table/types";
+import { SpansRow } from "./types";
+type Props<T extends SpansRow> = {
+    idField: keyof T | ((row: T) => string);
+    parentField: keyof T | ((row: T) => string | null);
+    columns: Column<T>[];
+    rows: T[];
+    expandedIds: Set<string>;
+    onExpandedIdsChange: (ids: Set<string>) => void;
+    onExpand?: (row: T) => void | Promise<void>;
+    isLoadingChildren?: (row: T) => boolean;
+    isLoading?: boolean;
+    content?: React.ReactNode;
+    className?: string;
+    rowDecorator?: (row: T, depth: number) => React.HTMLAttributes<HTMLTableRowElement>;
+    indentSize?: number;
+    isHeaderSticky?: boolean;
+    fluid?: boolean;
+    "data-testid"?: string;
+};
+export declare const VuiSpans: <T extends SpansRow>({ idField, parentField, columns, rows, expandedIds, onExpandedIdsChange, onExpand, isLoadingChildren, isLoading, content, className, rowDecorator, indentSize, isHeaderSticky, fluid, "data-testid": dataTestId }: Props<T>) => import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/components/spans/Spans.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useCallback, useMemo, useRef, useState } from "react";
+import classNames from "classnames";
+import { VuiFlexItem } from "../flex/FlexItem";
+import { VuiSpinner } from "../spinner/Spinner";
+import { VuiText } from "../typography/Text";
+import { VuiTableContent } from "../table/TableContent";
+import { buildAndFlattenSpans } from "./buildAndFlattenSpans";
+import { VuiSpansRow } from "./SpansRow";
+import { VuiSpansHeaderCell } from "./SpansHeaderCell";
+import { VuiSpansLoadingRow } from "./SpansLoadingRow";
+const DEFAULT_INDENT_SIZE = 16;
+const extractId = (row, idField) => {
+    return typeof idField === "function" ? idField(row) : row[idField];
+};
+const extractParentId = (row, parentField) => {
+    if (typeof parentField === "function")
+        return parentField(row);
+    const value = row[parentField];
+    return value === undefined || value === null ? null : value;
+};
+export const VuiSpans = ({ idField, parentField, columns, rows, expandedIds, onExpandedIdsChange, onExpand, isLoadingChildren, isLoading, content, className, rowDecorator, indentSize = DEFAULT_INDENT_SIZE, isHeaderSticky, fluid, "data-testid": dataTestId }) => {
+    const [internalLoadingIds, setInternalLoadingIds] = useState(new Set());
+    // Tracks pending fetches so we ignore stale resolutions (e.g. user collapses
+    // mid-fetch, then re-expands — the original promise should not clear loading
+    // state for the new attempt).
+    const fetchTokensRef = useRef(new Map());
+    const getId = useCallback((row) => extractId(row, idField), [idField]);
+    const getParentId = useCallback((row) => extractParentId(row, parentField), [parentField]);
+    const flatSpans = useMemo(() => buildAndFlattenSpans(rows, expandedIds, getId, getParentId), [rows, expandedIds, getId, getParentId]);
+    const columnCount = columns.length;
+    const handleToggle = useCallback((row, id, hasChildren, hasLoadedChildren) => {
+        var _a;
+        const isCurrentlyExpanded = expandedIds.has(id);
+        const nextExpandedIds = new Set(expandedIds);
+        if (isCurrentlyExpanded) {
+            nextExpandedIds.delete(id);
+            onExpandedIdsChange(nextExpandedIds);
+            return;
+        }
+        nextExpandedIds.add(id);
+        onExpandedIdsChange(nextExpandedIds);
+        // Only fire the consumer fetch when the row claims to have children
+        // (`hasChildren`) but none are present in the rows list yet.
+        const needsFetch = hasChildren && !hasLoadedChildren && Boolean(onExpand);
+        if (!needsFetch)
+            return;
+        const pendingFetchTokens = fetchTokensRef.current;
+        const currentFetchToken = ((_a = pendingFetchTokens.get(id)) !== null && _a !== void 0 ? _a : 0) + 1;
+        pendingFetchTokens.set(id, currentFetchToken);
+        setInternalLoadingIds((prev) => {
+            const nextLoadingIds = new Set(prev);
+            nextLoadingIds.add(id);
+            return nextLoadingIds;
+        });
+        const clearLoading = () => {
+            // Only clear if our token is still the latest — otherwise a newer
+            // fetch is in flight and owns the loading state.
+            if (pendingFetchTokens.get(id) !== currentFetchToken)
+                return;
+            setInternalLoadingIds((prev) => {
+                const nextLoadingIds = new Set(prev);
+                nextLoadingIds.delete(id);
+                return nextLoadingIds;
+            });
+        };
+        Promise.resolve(onExpand(row)).finally(clearLoading);
+    }, [expandedIds, onExpandedIdsChange, onExpand]);
+    const classes = classNames("vuiSpans", className, {
+        "vuiSpans--fluid": fluid
+    });
+    let tbodyContent;
+    if (content) {
+        tbodyContent = _jsx(VuiTableContent, Object.assign({ colSpan: columnCount }, { children: content }));
+    }
+    else if (isLoading) {
+        tbodyContent = (_jsxs(VuiTableContent, Object.assign({ colSpan: columnCount }, { children: [_jsx(VuiFlexItem, Object.assign({ grow: false }, { children: _jsx(VuiSpinner, { size: "xs" }) })), _jsx(VuiFlexItem, Object.assign({ grow: false }, { children: _jsx(VuiText, { children: _jsx("p", { children: "Loading" }) }) }))] })));
+    }
+    else {
+        tbodyContent = flatSpans.map((flat, rowIndex) => {
+            const { row, id, depth, hasChildren, hasLoadedChildren, posInSet, setSize } = flat;
+            const isExpanded = expandedIds.has(id);
+            const externalLoading = isLoadingChildren ? isLoadingChildren(row) : false;
+            const isLoadingRow = internalLoadingIds.has(id) || externalLoading;
+            const showLoadingRow = isExpanded && hasChildren && !hasLoadedChildren && isLoadingRow;
+            return (_jsxs(React.Fragment, { children: [_jsx(VuiSpansRow, { row: row, rowIndex: rowIndex, columns: columns, id: id, depth: depth, indentSize: indentSize, posInSet: posInSet, setSize: setSize, hasChildren: hasChildren, isExpanded: isExpanded, onToggle: () => handleToggle(row, id, hasChildren, hasLoadedChildren), rowDecorator: rowDecorator }), showLoadingRow && (_jsx(VuiSpansLoadingRow, { colSpan: columnCount, depth: depth + 1, indentSize: indentSize }, `${id}__loading`))] }, id));
+        });
+    }
+    return (_jsx("div", Object.assign({ className: "vuiSpansWrapper", "data-testid": dataTestId }, { children: _jsxs("table", Object.assign({ className: classes, role: "treegrid" }, { children: [_jsx("thead", Object.assign({ className: isHeaderSticky ? "vuiSpansStickyHeader" : undefined }, { children: _jsx("tr", Object.assign({ role: "row" }, { children: columns.map((column) => {
+                            const { name, width } = column;
+                            const styles = width ? { width } : undefined;
+                            return (_jsx("th", Object.assign({ role: "columnheader", style: styles }, { children: _jsx(VuiSpansHeaderCell, { column: column }) }), name));
+                        }) })) })), _jsx("tbody", { children: tbodyContent })] })) })));
+};

package/lib/components/spans/SpansCell.d.ts

@@ -0,0 +1,5 @@
+type Props = {
+    children: React.ReactNode;
+};
+export declare const VuiSpansCell: ({ children }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/components/spans/SpansCell.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export const VuiSpansCell = ({ children }) => {
+    return _jsx("div", Object.assign({ className: "vuiSpansCell" }, { children: children }));
+};

package/lib/components/spans/SpansHeaderCell.d.ts

@@ -0,0 +1,6 @@
+import { Column } from "../table/types";
+type Props<T> = {
+    column: Column<T>;
+};
+export declare const VuiSpansHeaderCell: <T>({ column }: Props<T>) => import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/components/spans/SpansHeaderCell.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export const VuiSpansHeaderCell = ({ column }) => {
+    const { name, header } = column;
+    return _jsx("div", Object.assign({ className: "vuiSpansHeaderCell" }, { children: header.render ? header.render() : name }));
+};

package/lib/components/spans/SpansLoadingRow.d.ts

@@ -0,0 +1,8 @@
+type Props = {
+    colSpan: number;
+    depth: number;
+    indentSize: number;
+    message?: React.ReactNode;
+};
+export declare const VuiSpansLoadingRow: ({ colSpan, depth, indentSize, message }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/components/spans/SpansLoadingRow.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { VuiFlexContainer } from "../flex/FlexContainer";
+import { VuiFlexItem } from "../flex/FlexItem";
+import { VuiSpinner } from "../spinner/Spinner";
+import { VuiText } from "../typography/Text";
+import { VuiTextColor } from "../typography/TextColor";
+export const VuiSpansLoadingRow = ({ colSpan, depth, indentSize, message = "Loading…" }) => {
+    return (_jsx("tr", Object.assign({ className: "vuiSpansLoadingRow vuiSpansRow--inert" }, { children: _jsx("td", Object.assign({ colSpan: colSpan, className: "vuiSpansLoadingRow__cell" }, { children: _jsx("div", Object.assign({ className: "vuiSpansLoadingRow__inner", style: { paddingLeft: depth * indentSize } }, { children: _jsxs(VuiFlexContainer, Object.assign({ alignItems: "center", spacing: "xs" }, { children: [_jsx(VuiFlexItem, Object.assign({ grow: false }, { children: _jsx(VuiSpinner, { size: "xs" }) })), _jsx(VuiFlexItem, Object.assign({ grow: false }, { children: _jsx(VuiText, Object.assign({ size: "xs" }, { children: _jsx("p", { children: _jsx(VuiTextColor, Object.assign({ color: "subdued" }, { children: message })) }) })) }))] })) })) })) })));
+};

package/lib/components/spans/SpansRow.d.ts

@@ -0,0 +1,17 @@
+import { Column, Row } from "../table/types";
+type Props<T> = {
+    row: T;
+    rowIndex: number;
+    columns: Column<T>[];
+    id: string;
+    depth: number;
+    indentSize: number;
+    posInSet: number;
+    setSize: number;
+    hasChildren: boolean;
+    isExpanded: boolean;
+    onToggle: () => void;
+    rowDecorator?: (row: T, depth: number) => React.HTMLAttributes<HTMLTableRowElement>;
+};
+export declare const VuiSpansRow: <T extends Row>({ row, rowIndex, columns, id, depth, indentSize, posInSet, setSize, hasChildren, isExpanded, onToggle, rowDecorator }: Props<T>) => import("react/jsx-runtime").JSX.Element;
+export {};

package/lib/components/spans/SpansRow.js

@@ -0,0 +1,43 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import classNames from "classnames";
+import { BiChevronDown, BiChevronRight } from "react-icons/bi";
+import { VuiIcon } from "../icon/Icon";
+import { VuiIconButton } from "../button/IconButton";
+import { VuiSpansCell } from "./SpansCell";
+// Cap visual indentation at this depth so the first column doesn't overflow
+// for very deep traces. `aria-level` continues to reflect the true depth.
+const MAX_VISUAL_DEPTH = 12;
+export const VuiSpansRow = ({ row, rowIndex, columns, id, depth, indentSize, posInSet, setSize, hasChildren, isExpanded, onToggle, rowDecorator }) => {
+    var _a;
+    const decoratorAttrs = (_a = rowDecorator === null || rowDecorator === void 0 ? void 0 : rowDecorator(row, depth)) !== null && _a !== void 0 ? _a : {};
+    const { className: decoratorClassName } = decoratorAttrs, restDecoratorAttrs = __rest(decoratorAttrs, ["className"]);
+    const rowClassName = classNames("vuiSpansRow", decoratorClassName, {
+        "vuiSpansRow-isExpanded": hasChildren && isExpanded,
+        "vuiSpansRow--leaf": !hasChildren
+    });
+    const visualDepth = Math.min(depth, MAX_VISUAL_DEPTH);
+    const indentStyle = { paddingLeft: visualDepth * indentSize };
+    return (_jsx("tr", Object.assign({ role: "row", "aria-level": depth + 1, "aria-posinset": posInSet, "aria-setsize": setSize, "aria-expanded": hasChildren ? isExpanded : undefined, "data-row-id": id, className: rowClassName }, restDecoratorAttrs, { children: columns.map((column, columnIndex) => {
+            const { name, render, className: columnClassName, testId } = column;
+            const cellClasses = classNames("vuiSpansCellWrapper", columnClassName, {
+                "vuiSpansCellWrapper--first": columnIndex === 0,
+                "vuiSpansCellWrapper--truncate": column.truncate
+            });
+            const cellContent = render ? render(row, rowIndex) : row[name];
+            if (columnIndex === 0) {
+                return (_jsx("td", Object.assign({ role: "gridcell", className: cellClasses, "data-testid": typeof testId === "function" ? testId(row) : testId }, { children: _jsxs("div", Object.assign({ className: "vuiSpansCell__indent", style: indentStyle }, { children: [_jsx("div", Object.assign({ className: "vuiSpansCell__chevron" }, { children: hasChildren ? (_jsx(VuiIconButton, { icon: _jsx(VuiIcon, { children: isExpanded ? _jsx(BiChevronDown, {}) : _jsx(BiChevronRight, {}) }), size: "xs", color: "neutral", "aria-label": isExpanded ? "Collapse span" : "Expand span", onClick: onToggle, "data-testid": `spanExpandToggle-${id}` })) : (_jsx("span", { className: "vuiSpansCell__chevronPlaceholder", "aria-hidden": "true" })) })), _jsx(VuiSpansCell, { children: cellContent })] })) }), name));
+            }
+            return (_jsx("td", Object.assign({ role: "gridcell", className: cellClasses, "data-testid": typeof testId === "function" ? testId(row) : testId }, { children: _jsx(VuiSpansCell, { children: cellContent }) }), name));
+        }) })));
+};

package/lib/components/spans/_index.scss

@@ -0,0 +1,110 @@
+$spansChevronWidth: 24px;
+
+.vuiSpansWrapper {
+  width: 100%;
+  position: relative;
+}
+
+.vuiSpans {
+  width: 100%;
+  table-layout: fixed;
+
+  thead {
+    border-bottom: 1px solid var(--vui-color-border-medium);
+  }
+
+  tbody tr {
+    border-bottom: 1px solid var(--vui-color-border-light);
+
+    &:not(.vuiSpansRow--inert):hover {
+      background-color: rgba(var(--vui-color-light-shade-rgb), 0.25);
+    }
+
+    &:last-child {
+      border-bottom: 1px solid var(--vui-color-border-medium);
+    }
+  }
+
+  th {
+    font-size: $fontSizeStandard;
+    font-weight: $fontWeightBold;
+    padding: $sizeXxs;
+    text-align: left;
+  }
+
+  td {
+    font-size: $fontSizeStandard;
+    padding: $sizeXxs;
+    vertical-align: middle;
+    word-break: break-word;
+  }
+}
+
+.vuiSpans--fluid {
+  table-layout: auto;
+}
+
+// First column: depth-indent + chevron + content laid out in a row.
+.vuiSpansCell__indent {
+  display: flex;
+  align-items: center;
+  gap: $sizeXxs;
+  // padding-left set inline based on depth.
+}
+
+.vuiSpansCell__chevron {
+  flex: 0 0 auto;
+  width: $spansChevronWidth;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.vuiSpansCell__chevronPlaceholder {
+  display: inline-block;
+  width: $spansChevronWidth;
+  height: 1px; // Reserves horizontal space; height irrelevant.
+}
+
+.vuiSpansCell {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  flex: 1 1 auto;
+}
+
+.vuiSpansCellWrapper--truncate {
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.vuiSpansHeaderCell {
+  display: flex;
+  align-items: center;
+  padding: $sizeXxs;
+}
+
+// Sticky header — same treatment as VuiTable.
+.vuiSpansStickyHeader {
+  position: sticky;
+  top: 0;
+  background-color: var(--vui-color-empty-shade);
+  z-index: 1;
+}
+
+// Loading row injected under a parent during lazy fetch.
+.vuiSpansLoadingRow {
+  background-color: rgba(var(--vui-color-light-shade-rgb), 0.15);
+}
+
+.vuiSpansLoadingRow__cell {
+  padding: $sizeXxs !important;
+}
+
+.vuiSpansLoadingRow__inner {
+  display: flex;
+  align-items: center;
+  // padding-left set inline based on depth.
+}

package/lib/components/spans/buildAndFlattenSpans.d.ts

@@ -0,0 +1,14 @@
+import { SpansRow } from "./types";
+export type FlatSpan<T> = {
+    row: T;
+    id: string;
+    parentId: string | null;
+    depth: number;
+    hasChildren: boolean;
+    hasLoadedChildren: boolean;
+    posInSet: number;
+    setSize: number;
+};
+export type IdAccessor<T> = (row: T) => string;
+export type ParentAccessor<T> = (row: T) => string | null;
+export declare const buildAndFlattenSpans: <T extends SpansRow>(rows: T[], expandedIds: Set<string>, getId: IdAccessor<T>, getParentId: ParentAccessor<T>) => FlatSpan<T>[];

package/lib/components/spans/buildAndFlattenSpans.js

@@ -0,0 +1,69 @@
+// Flattens a list of rows (linked by `parentId`) into a render-ordered, depth-tagged array,
+// showing only visible nodes based on `expandedIds`. The render layer maps this 1:1 to <tr>s.
+// Orphans (rows with missing parents) are dropped. Cycles are avoided using an ancestor set.
+export const buildAndFlattenSpans = (rows, expandedIds, getId, getParentId) => {
+    // First pass: collect every known id so we can detect orphans below.
+    const allIds = new Set();
+    for (const row of rows) {
+        allIds.add(getId(row));
+    }
+    // Group rows by their parent id, with top-level rows under a sentinel key.
+    // The sentinel can't collide with a real id because it contains spaces.
+    const ROOT_KEY = " __VuiSpansRoot__ ";
+    const childrenByParent = new Map();
+    for (const row of rows) {
+        const parentId = getParentId(row);
+        // Drop orphans: parent id set but not present in the rows list.
+        if (parentId !== null && !allIds.has(parentId))
+            continue;
+        const key = parentId === null ? ROOT_KEY : parentId;
+        const list = childrenByParent.get(key);
+        if (list) {
+            list.push(row);
+        }
+        else {
+            childrenByParent.set(key, [row]);
+        }
+    }
+    const result = [];
+    // Recursive depth-first walk. `ancestors` carries the chain of ids from the
+    // root down to (but not including) the current row, used to detect cycles.
+    const walk = (parentKey, parentId, depth, ancestors) => {
+        const siblings = childrenByParent.get(parentKey);
+        if (!siblings)
+            return;
+        siblings.forEach((row, index) => {
+            const id = getId(row);
+            // Break cycle: this id appears earlier in its own ancestor chain.
+            if (ancestors.has(id))
+                return;
+            const ownChildren = childrenByParent.get(id);
+            const ownChildCount = ownChildren ? ownChildren.length : 0;
+            const hasLoadedChildren = ownChildCount > 0;
+            // The chevron should appear if either we already have children to show
+            // or the row is hinting that lazily-loadable children exist.
+            const hasChildren = row.hasChildren || hasLoadedChildren;
+            result.push({
+                row,
+                id,
+                parentId,
+                depth,
+                hasChildren,
+                hasLoadedChildren,
+                posInSet: index + 1,
+                setSize: siblings.length
+            });
+            // Only descend if the user has expanded this row AND there's something
+            // loaded to descend into. The lazy-only case (`hasChildren` but
+            // `!hasLoadedChildren`) is handled by the loading row in the render
+            // layer, not here.
+            if (hasChildren && expandedIds.has(id) && ownChildCount > 0) {
+                const nextAncestors = new Set(ancestors);
+                nextAncestors.add(id);
+                walk(id, id, depth + 1, nextAncestors);
+            }
+        });
+    };
+    walk(ROOT_KEY, null, 0, new Set());
+    return result;
+};

package/lib/components/spans/buildAndFlattenSpans.test.d.ts

@@ -0,0 +1 @@
+export {};