@vectara/vectara-ui 16.3.1 → 16.4.0

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/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 {};

package/lib/components/spans/buildAndFlattenSpans.test.js

@@ -0,0 +1,388 @@
+import { buildAndFlattenSpans } from "./buildAndFlattenSpans";
+const getId = (s) => s.id;
+const getParentId = (s) => s.parentId;
+const flatten = (rows, expandedIds = new Set()) => buildAndFlattenSpans(rows, expandedIds, getId, getParentId);
+describe("buildAndFlattenSpans", () => {
+    test("emits only top-level rows when nothing is expanded", () => {
+        const rows = [
+            { id: "a", parentId: null },
+            { id: "b", parentId: null },
+            { id: "a-1", parentId: "a" },
+            { id: "a-2", parentId: "a" }
+        ];
+        expect(flatten(rows)).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 2
+            },
+            {
+                row: rows[1],
+                id: "b",
+                parentId: null,
+                depth: 0,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 2,
+                setSize: 2
+            }
+        ]);
+    });
+    test("emits children of expanded parents in render order", () => {
+        const rows = [
+            { id: "a", parentId: null },
+            { id: "b", parentId: null },
+            { id: "a-1", parentId: "a" },
+            { id: "a-2", parentId: "a" }
+        ];
+        expect(flatten(rows, new Set(["a"]))).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 2
+            },
+            {
+                row: rows[2],
+                id: "a-1",
+                parentId: "a",
+                depth: 1,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 1,
+                setSize: 2
+            },
+            {
+                row: rows[3],
+                id: "a-2",
+                parentId: "a",
+                depth: 1,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 2,
+                setSize: 2
+            },
+            {
+                row: rows[1],
+                id: "b",
+                parentId: null,
+                depth: 0,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 2,
+                setSize: 2
+            }
+        ]);
+    });
+    test("walks deep trees", () => {
+        const rows = [
+            { id: "a", parentId: null },
+            { id: "a-1", parentId: "a" },
+            { id: "a-1-1", parentId: "a-1" },
+            { id: "a-1-1-1", parentId: "a-1-1" }
+        ];
+        expect(flatten(rows, new Set(["a", "a-1", "a-1-1"]))).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 1
+            },
+            {
+                row: rows[1],
+                id: "a-1",
+                parentId: "a",
+                depth: 1,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 1
+            },
+            {
+                row: rows[2],
+                id: "a-1-1",
+                parentId: "a-1",
+                depth: 2,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 1
+            },
+            {
+                row: rows[3],
+                id: "a-1-1-1",
+                parentId: "a-1-1",
+                depth: 3,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 1,
+                setSize: 1
+            }
+        ]);
+    });
+    test("flags hasChildren when actual children exist", () => {
+        const rows = [
+            { id: "a", parentId: null },
+            { id: "b", parentId: null },
+            { id: "a-1", parentId: "a" }
+        ];
+        expect(flatten(rows)).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 2
+            },
+            {
+                row: rows[1],
+                id: "b",
+                parentId: null,
+                depth: 0,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 2,
+                setSize: 2
+            }
+        ]);
+    });
+    test("flags hasChildren when row says so even with no actual children", () => {
+        const rows = [{ id: "a", parentId: null, hasChildren: true }];
+        expect(flatten(rows)).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: false,
+                posInSet: 1,
+                setSize: 1
+            }
+        ]);
+    });
+    test("does not recurse when expanded but no children loaded", () => {
+        // Lazy-load case: row says it has children but they aren't in the list.
+        const rows = [{ id: "a", parentId: null, hasChildren: true }];
+        expect(flatten(rows, new Set(["a"]))).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: false,
+                posInSet: 1,
+                setSize: 1
+            }
+        ]);
+    });
+    test("drops orphans (parent id that doesn't appear in rows)", () => {
+        const rows = [
+            { id: "a", parentId: null },
+            { id: "ghost", parentId: "missing" }
+        ];
+        expect(flatten(rows)).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 1,
+                setSize: 1
+            }
+        ]);
+    });
+    test("breaks cycles", () => {
+        // Duplicate id forms a cycle: the root "a" claims "a" as a child of itself.
+        // The recursive walk should bail at the duplicate, leaving just the root.
+        const rows = [
+            { id: "a", parentId: null },
+            { id: "a", parentId: "a" }
+        ];
+        expect(flatten(rows, new Set(["a"]))).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 1
+            }
+        ]);
+    });
+    test("sets posInSet and setSize per sibling group", () => {
+        const rows = [
+            { id: "a", parentId: null },
+            { id: "b", parentId: null },
+            { id: "c", parentId: null },
+            { id: "b-1", parentId: "b" },
+            { id: "b-2", parentId: "b" }
+        ];
+        expect(flatten(rows, new Set(["b"]))).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 1,
+                setSize: 3
+            },
+            {
+                row: rows[1],
+                id: "b",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 2,
+                setSize: 3
+            },
+            {
+                row: rows[3],
+                id: "b-1",
+                parentId: "b",
+                depth: 1,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 1,
+                setSize: 2
+            },
+            {
+                row: rows[4],
+                id: "b-2",
+                parentId: "b",
+                depth: 1,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 2,
+                setSize: 2
+            },
+            {
+                row: rows[2],
+                id: "c",
+                parentId: null,
+                depth: 0,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 3,
+                setSize: 3
+            }
+        ]);
+    });
+    test("preserves input order among siblings", () => {
+        const rows = [
+            { id: "z", parentId: null },
+            { id: "a", parentId: null },
+            { id: "m", parentId: null }
+        ];
+        expect(flatten(rows)).toEqual([
+            {
+                row: rows[0],
+                id: "z",
+                parentId: null,
+                depth: 0,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 1,
+                setSize: 3
+            },
+            {
+                row: rows[1],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 2,
+                setSize: 3
+            },
+            {
+                row: rows[2],
+                id: "m",
+                parentId: null,
+                depth: 0,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 3,
+                setSize: 3
+            }
+        ]);
+    });
+    test("collapsed parent hides its descendants but state persists for re-expand", () => {
+        const rows = [
+            { id: "a", parentId: null },
+            { id: "a-1", parentId: "a" },
+            { id: "a-1-1", parentId: "a-1" }
+        ];
+        // Both a and a-1 expanded — full subtree visible.
+        expect(flatten(rows, new Set(["a", "a-1"]))).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 1
+            },
+            {
+                row: rows[1],
+                id: "a-1",
+                parentId: "a",
+                depth: 1,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 1
+            },
+            {
+                row: rows[2],
+                id: "a-1-1",
+                parentId: "a-1",
+                depth: 2,
+                hasChildren: false,
+                hasLoadedChildren: false,
+                posInSet: 1,
+                setSize: 1
+            }
+        ]);
+        // a-1 still in expandedIds but a is collapsed — only a should render. The
+        // a-1 expand state is preserved for when the user re-expands a.
+        expect(flatten(rows, new Set(["a-1"]))).toEqual([
+            {
+                row: rows[0],
+                id: "a",
+                parentId: null,
+                depth: 0,
+                hasChildren: true,
+                hasLoadedChildren: true,
+                posInSet: 1,
+                setSize: 1
+            }
+        ]);
+    });
+});

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

@@ -0,0 +1,5 @@
+import { Column, Row } from "../table/types";
+export type { Column };
+export type SpansRow = Row & {
+    hasChildren?: boolean;
+};

package/lib/components/spans/types.js

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

package/lib/styles/index.css

@@ -4786,6 +4786,104 @@ h2.react-datepicker__current-month {
   height: 40px;
 }
 
+.vuiSpansWrapper {
+  width: 100%;
+  position: relative;
+}
+
+.vuiSpans {
+  width: 100%;
+  table-layout: fixed;
+}
+.vuiSpans thead {
+  border-bottom: 1px solid var(--vui-color-border-medium);
+}
+.vuiSpans tbody tr {
+  border-bottom: 1px solid var(--vui-color-border-light);
+}
+.vuiSpans tbody tr:not(.vuiSpansRow--inert):hover {
+  background-color: rgba(var(--vui-color-light-shade-rgb), 0.25);
+}
+.vuiSpans tbody tr:last-child {
+  border-bottom: 1px solid var(--vui-color-border-medium);
+}
+.vuiSpans th {
+  font-size: 14px;
+  font-weight: 600;
+  padding: 4px;
+  text-align: left;
+}
+.vuiSpans td {
+  font-size: 14px;
+  padding: 4px;
+  vertical-align: middle;
+  word-break: break-word;
+}
+
+.vuiSpans--fluid {
+  table-layout: auto;
+}
+
+.vuiSpansCell__indent {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.vuiSpansCell__chevron {
+  flex: 0 0 auto;
+  width: 24px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.vuiSpansCell__chevronPlaceholder {
+  display: inline-block;
+  width: 24px;
+  height: 1px;
+}
+
+.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: 4px;
+}
+
+.vuiSpansStickyHeader {
+  position: sticky;
+  top: 0;
+  background-color: var(--vui-color-empty-shade);
+  z-index: 1;
+}
+
+.vuiSpansLoadingRow {
+  background-color: rgba(var(--vui-color-light-shade-rgb), 0.15);
+}
+
+.vuiSpansLoadingRow__cell {
+  padding: 4px !important;
+}
+
+.vuiSpansLoadingRow__inner {
+  display: flex;
+  align-items: center;
+}
+
 .vuiSpinner {
   display: inline-block;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectara/vectara-ui",
-  "version": "16.3.1",
+  "version": "16.4.0",
   "homepage": "./",
   "description": "Vectara's design system, codified as a React and Sass component library",
   "author": "Vectara",

package/src/docs/pages/spans/Spans.tsx

@@ -0,0 +1,170 @@
+import { useMemo, useState } from "react";
+import {
+  VuiBadge,
+  VuiFlexContainer,
+  VuiFlexItem,
+  VuiIcon,
+  VuiSpacer,
+  VuiSpans,
+  VuiText,
+  VuiTextColor,
+  VuiToggle
+} from "../../../lib";
+import { BiCog, BiError, BiNetworkChart, BiSearch, BiSitemap, BiSpreadsheet } from "react-icons/bi";
+import { FakeSpan, LAZY_CHILDREN, ROOT_SPANS } from "./createFakeSpans";
+
+const KIND_ICON = {
+  workflow: BiSitemap,
+  tool: BiCog,
+  llm: BiNetworkChart,
+  search: BiSearch,
+  embedding: BiSpreadsheet
+} as const;
+
+const STATUS_COLOR = {
+  ok: "success",
+  error: "danger",
+  running: "primary"
+} as const;
+
+export const Spans = () => {
+  const [hasData, setHasData] = useState(true);
+  const [isLoading, setIsLoading] = useState(false);
+  const [hasError, setHasError] = useState(false);
+  const [isHeaderSticky, setIsHeaderSticky] = useState(false);
+  const [fluid, setFluid] = useState(true);
+
+  const [rows, setRows] = useState<FakeSpan[]>(ROOT_SPANS);
+  const [expandedIds, setExpandedIds] = useState<Set<string>>(new Set(["wf-1"]));
+
+  const visibleRows = hasData ? rows : [];
+
+  const onExpand = async (row: FakeSpan) => {
+    // Only the wf-1-c2 span lazy-loads in this demo.
+    if (row.id !== "wf-1-c2") return;
+
+    // Simulate a network round-trip.
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+
+    setRows((prev) => {
+      // De-dupe in case the user toggles repeatedly.
+      const alreadyLoaded = prev.some((r) => r.parentId === row.id);
+      if (alreadyLoaded) return prev;
+      return prev.concat(LAZY_CHILDREN);
+    });
+  };
+
+  const columns = useMemo(
+    () => [
+      {
+        name: "name",
+        width: "55%",
+        header: { render: () => "Name" },
+        render: (row: FakeSpan) => {
+          const KindIcon = KIND_ICON[row.kind];
+          return (
+            <VuiFlexContainer alignItems="center" spacing="xs">
+              <VuiFlexItem grow={false} shrink={false}>
+                <VuiIcon size="s" color="subdued">
+                  <KindIcon />
+                </VuiIcon>
+              </VuiFlexItem>
+              <VuiFlexItem grow={false}>{row.name}</VuiFlexItem>
+            </VuiFlexContainer>
+          );
+        }
+      },
+      {
+        name: "status",
+        width: "120px",
+        header: { render: () => "Status" },
+        render: (row: FakeSpan) => <VuiBadge color={STATUS_COLOR[row.status]}>{row.status}</VuiBadge>
+      },
+      {
+        name: "startAt",
+        width: "140px",
+        header: { render: () => "Start at" },
+        render: (row: FakeSpan) => (
+          <VuiText size="s">
+            <p>
+              <VuiTextColor color="subdued">{row.startAt}</VuiTextColor>
+            </p>
+          </VuiText>
+        )
+      },
+      {
+        name: "duration",
+        width: "120px",
+        header: { render: () => "Duration" },
+        render: (row: FakeSpan) => (
+          <VuiText size="s">
+            <p>
+              <VuiTextColor color="subdued">{row.durationMs}ms</VuiTextColor>
+            </p>
+          </VuiText>
+        )
+      }
+    ],
+    []
+  );
+
+  const errorContent = (
+    <>
+      <VuiFlexItem grow={false}>
+        <VuiIcon color="danger">
+          <BiError />
+        </VuiIcon>
+      </VuiFlexItem>
+      <VuiFlexItem grow={false}>
+        <VuiText>
+          <p>
+            <VuiTextColor color="danger">Couldn't retrieve trace</VuiTextColor>
+          </p>
+        </VuiText>
+      </VuiFlexItem>
+    </>
+  );
+
+  return (
+    <>
+      <VuiFlexContainer wrap spacing="l">
+        <VuiFlexItem shrink={false}>
+          <VuiToggle label="Has data" checked={hasData} onChange={(e) => setHasData(e.target.checked)} />
+        </VuiFlexItem>
+        <VuiFlexItem shrink={false}>
+          <VuiToggle label="Is loading" checked={isLoading} onChange={(e) => setIsLoading(e.target.checked)} />
+        </VuiFlexItem>
+        <VuiFlexItem shrink={false}>
+          <VuiToggle label="Has error" checked={hasError} onChange={(e) => setHasError(e.target.checked)} />
+        </VuiFlexItem>
+        <VuiFlexItem shrink={false}>
+          <VuiToggle
+            label="Sticky header"
+            checked={isHeaderSticky}
+            onChange={(e) => setIsHeaderSticky(e.target.checked)}
+          />
+        </VuiFlexItem>
+        <VuiFlexItem shrink={false}>
+          <VuiToggle label="Fluid layout" checked={fluid} onChange={(e) => setFluid(e.target.checked)} />
+        </VuiFlexItem>
+      </VuiFlexContainer>
+
+      <VuiSpacer size="xl" />
+
+      <VuiSpans
+        data-testid="spansTable"
+        idField="id"
+        parentField="parentId"
+        rows={visibleRows}
+        columns={columns}
+        expandedIds={expandedIds}
+        onExpandedIdsChange={setExpandedIds}
+        onExpand={onExpand}
+        isLoading={isLoading}
+        content={hasError ? errorContent : undefined}
+        isHeaderSticky={isHeaderSticky}
+        fluid={fluid}
+      />
+    </>
+  );
+};

package/src/docs/pages/spans/createFakeSpans.ts

@@ -0,0 +1,118 @@
+export type FakeSpan = {
+  id: string;
+  parentId: string | null;
+  name: string;
+  kind: "workflow" | "tool" | "llm" | "search" | "embedding";
+  status: "ok" | "error" | "running";
+  startAt: string;
+  durationMs: number;
+  hasChildren?: boolean;
+};
+
+export const ROOT_SPANS: FakeSpan[] = [
+  {
+    id: "wf-1",
+    parentId: null,
+    name: "Run search workflow",
+    kind: "workflow",
+    status: "ok",
+    startAt: "10:42:17.103",
+    durationMs: 3420
+  },
+  {
+    id: "wf-1-c1",
+    parentId: "wf-1",
+    name: "Generate query embeddings",
+    kind: "embedding",
+    status: "ok",
+    startAt: "10:42:17.110",
+    durationMs: 142
+  },
+  {
+    id: "wf-1-c2",
+    parentId: "wf-1",
+    name: "Vector search (corpus: support_docs)",
+    kind: "search",
+    status: "ok",
+    startAt: "10:42:17.260",
+    durationMs: 980,
+    // Lazy: chevron shown but no child rows present in initial fetch.
+    hasChildren: true
+  },
+  {
+    id: "wf-1-c3",
+    parentId: "wf-1",
+    name: "Re-rank top-25 candidates",
+    kind: "tool",
+    status: "ok",
+    startAt: "10:42:18.250",
+    durationMs: 412
+  },
+  {
+    id: "wf-1-c4",
+    parentId: "wf-1",
+    name: "Generate summary",
+    kind: "llm",
+    status: "running",
+    startAt: "10:42:18.670",
+    durationMs: 1850
+  },
+  {
+    id: "wf-1-c4-c1",
+    parentId: "wf-1-c4",
+    name: "Build prompt context",
+    kind: "tool",
+    status: "ok",
+    startAt: "10:42:18.671",
+    durationMs: 12
+  },
+  {
+    id: "wf-1-c4-c2",
+    parentId: "wf-1-c4",
+    name: "claude-haiku-4-5 streaming call",
+    kind: "llm",
+    status: "running",
+    startAt: "10:42:18.700",
+    durationMs: 1820
+  },
+  {
+    id: "wf-2",
+    parentId: null,
+    name: "Persist trace",
+    kind: "tool",
+    status: "error",
+    startAt: "10:42:20.523",
+    durationMs: 38
+  }
+];
+
+// Children of "wf-1-c2"
+export const LAZY_CHILDREN: FakeSpan[] = [
+  {
+    id: "wf-1-c2-c1",
+    parentId: "wf-1-c2",
+    name: "Search Vectara API",
+    kind: "search",
+    status: "ok",
+    startAt: "10:42:17.262",
+    durationMs: 940
+  },
+  {
+    id: "wf-1-c2-c2",
+    parentId: "wf-1-c2",
+    name: "Parse filter expression",
+    kind: "tool",
+    status: "ok",
+    startAt: "10:42:17.265",
+    durationMs: 4
+  },
+  {
+    id: "wf-1-c2-c3",
+    parentId: "wf-1-c2",
+    name: "Apply MMR diversification",
+    kind: "tool",
+    status: "ok",
+    startAt: "10:42:18.205",
+    durationMs: 32
+  }
+];

package/src/docs/pages/spans/index.tsx

@@ -0,0 +1,11 @@
+import { Spans } from "./Spans";
+const SpansSource = require("!!raw-loader!./Spans");
+
+export const spans = {
+  name: "Spans",
+  path: "/spans",
+  example: {
+    component: <Spans />,
+    source: SpansSource.default.toString()
+  }
+};

package/src/docs/pages.tsx

@@ -57,6 +57,7 @@ import { summary } from "./pages/summary";
 import { skeleton } from "./pages/skeleton";
 import { superCheckboxGroup } from "./pages/superCheckboxGroup";
 import { superRadioGroup } from "./pages/superRadioGroup";
+import { spans } from "./pages/spans";
 import { table } from "./pages/table";
 import { tabs } from "./pages/tabs";
 import { text } from "./pages/text";
@@ -87,7 +88,7 @@ export const categories: Category[] = [
   },
   {
     name: "Info",
-    pages: [table, infoTable, infoList, statList, list, pagination]
+    pages: [table, spans, infoTable, infoList, statList, list, pagination]
   },
   {
     name: "Layout",