@vectara/vectara-ui 16.3.1 → 16.4.1

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.1",
   "homepage": "./",
   "description": "Vectara's design system, codified as a React and Sass component library",
   "author": "Vectara",

package/src/docs/pages/drawer/PrimaryDrawer.tsx

@@ -218,6 +218,20 @@ export const PrimaryDrawer = () => {
             that the focus management and scroll locking still work as expected.
           </p>
         </VuiText>
+
+        <VuiSpacer size="m" />
+
+        <VuiButtonSecondary
+          color="primary"
+          onClick={() => {
+            addNotification({
+              color: "primary",
+              message: "Just some information, FYI"
+            });
+          }}
+        >
+          Add notification
+        </VuiButtonSecondary>
       </VuiModal>
 
       <VuiNotifications />

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}
+      />
+    </>
+  );
+};