@principal-ai/principal-view-react 0.15.6 → 0.15.7

package/src/components/SequenceDiagramRenderer.tsx

@@ -5,7 +5,7 @@
  * Uses namespaces to determine swimlanes and event order for vertical positioning.
  */
 
-import React, { useCallback, useMemo } from 'react';
+import React, { useCallback, useMemo, useState } from 'react';
 import {
   ReactFlow,
   Background,
@@ -33,6 +33,7 @@ import {
   type SequenceEdge,
   type UseSequenceLayoutOptions,
   type Swimlane,
+  type ParentHeader,
 } from '../hooks/useSequenceLayout';
 
 /**
@@ -360,6 +361,42 @@ const defaultSequenceNodeTypes: NodeTypes = {
   sequenceMarker: SequenceMarkerNode,
 };
 
+/**
+ * Shared transition for swimlane chrome — interpolates positions and sizes
+ * when lanes shift due to drill toggles.
+ */
+const swimlaneTransition =
+  'top 350ms ease-out, left 350ms ease-out, width 350ms ease-out, height 350ms ease-out';
+
+/** Duration of the child slide-up exit animation. The close handler waits
+ * this long before applying the data change so the diagram body doesn't
+ * shift while the children are still on screen. */
+const SWIMLANE_CLOSE_EXIT_MS = 280;
+
+const swimlaneAnimationStyles = `
+@keyframes swimlaneFadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@keyframes swimlaneFadeOut {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}
+@keyframes swimlaneChildSlideDown {
+  from { transform: translateY(-100%); opacity: 0; }
+  to { transform: translateY(0); opacity: 1; }
+}
+@keyframes swimlaneChildSlideUp {
+  from { transform: translateY(0); opacity: 1; }
+  to { transform: translateY(-100%); opacity: 0; }
+}
+.swimlane-fade-in { animation: swimlaneFadeIn 250ms ease-out both; }
+.swimlane-child-bg-in { animation: swimlaneFadeIn 300ms ease-out 250ms both; }
+.swimlane-child-in { animation: swimlaneChildSlideDown 300ms ease-out 250ms both; }
+.swimlane-child-out { animation: swimlaneChildSlideUp 280ms ease-in both; }
+.swimlane-fade-out { animation: swimlaneFadeOut 250ms ease-in both; }
+`;
+
 /**
  * Default edge types including sequence arrow and participant arrow
  */
@@ -373,10 +410,18 @@ const defaultSequenceEdgeTypes: EdgeTypes = {
  */
 interface SwimlaneLayerProps {
   swimlanes: Swimlane[];
+  parentHeaders: ParentHeader[];
+  headerRows: number;
   laneWidth: number;
+  /** Per-row height (each row in the header strip is this tall) */
   headerHeight: number;
   totalHeight: number;
-  onToggleCollapse?: (namespace: string) => void;
+  /** Called when the user clicks a chevron or parent header to toggle its drilled state */
+  onToggleNamespace?: (namespace: string) => void;
+  /** Namespaces mid-close. Their children are still in the data but render
+   *  with the exit animation so the body can stay put until the animation
+   *  finishes and the data change applies. */
+  closingNamespaces?: Set<string>;
   stickyHeaders?: boolean;
   /** When true, render lane and header backgrounds as transparent. */
   transparent?: boolean;
@@ -387,11 +432,13 @@ interface SwimlaneLayerProps {
  */
 function SwimlaneLayer({
   swimlanes,
+  headerRows,
   laneWidth,
   headerHeight,
   totalHeight,
   transparent = false,
 }: SwimlaneLayerProps) {
+  const totalHeaderHeight = headerHeight * headerRows;
   const { x, y, zoom } = useViewport();
   const viewportHeight = useStore((s) => s.height);
   const { theme } = useTheme();
@@ -420,9 +467,13 @@ function SwimlaneLayer({
           : isEven
             ? theme.colors.muted
             : theme.colors.background;
+        const fadeClass = lane.isParentOpened
+          ? 'swimlane-child-bg-in'
+          : 'swimlane-fade-in';
         return (
           <div
             key={`bg-${lane.namespace}`}
+            className={fadeClass}
             style={{
               position: 'absolute',
               left: lane.x - laneWidth / 2,
@@ -431,6 +482,7 @@ function SwimlaneLayer({
               height: extendedHeight,
               backgroundColor: laneBackground,
               borderRight: `1px solid ${theme.colors.border}`,
+              transition: swimlaneTransition,
             }}
           />
         );
@@ -440,14 +492,18 @@ function SwimlaneLayer({
       {swimlanes.map((lane) => (
         <div
           key={`lifeline-${lane.namespace}`}
+          className={
+            lane.isParentOpened ? 'swimlane-child-bg-in' : 'swimlane-fade-in'
+          }
           style={{
             position: 'absolute',
             left: lane.x,
-            top: headerHeight,
+            top: totalHeaderHeight,
             width: 2,
-            height: extendedHeight - headerHeight,
+            height: extendedHeight - totalHeaderHeight,
             backgroundColor: 'rgba(255, 255, 255, 0.4)',
             transform: 'translateX(-1px)',
+            transition: swimlaneTransition,
           }}
         />
       ))}
@@ -455,24 +511,141 @@ function SwimlaneLayer({
   );
 }
 
+/**
+ * Two offset rounded rectangles signaling that a header has nested lanes
+ * underneath it. When `opened`, the front layer is filled to indicate the
+ * stack is currently expanded.
+ */
+function StackIcon({
+  opened = false,
+  hovered = false,
+  accentColor,
+}: {
+  opened?: boolean;
+  hovered?: boolean;
+  accentColor?: string;
+}) {
+  // Closed: rects compactly stacked, both outlined in text color.
+  // Hovered: strokes tint to the accent color (preview of the action).
+  // Opened: front rect drifts down/right and fades to filled in the accent.
+  const rectTransition =
+    'transform 280ms cubic-bezier(0.2, 0, 0, 1), fill-opacity 280ms ease, stroke 200ms ease';
+  const useAccent = (opened || hovered) && !!accentColor;
+  const stroke = useAccent ? accentColor : 'currentColor';
+  const fill = accentColor || 'currentColor';
+  return (
+    <svg
+      width={22}
+      height={22}
+      viewBox="0 0 14 14"
+      fill="none"
+      strokeWidth={1.3}
+      strokeLinejoin="round"
+      aria-hidden="true"
+      style={{
+        flexShrink: 0,
+        opacity: opened ? 0.95 : hovered ? 0.9 : 0.75,
+        overflow: 'visible',
+        transition: 'opacity 200ms ease',
+      }}
+    >
+      <rect
+        x={2}
+        y={3}
+        width={7}
+        height={5}
+        rx={1}
+        stroke={stroke}
+        style={{
+          transition: rectTransition,
+          transform: opened
+            ? 'translate(-1.5px, -1.5px)'
+            : 'translate(0px, 0px)',
+        }}
+      />
+      <rect
+        x={5}
+        y={6}
+        width={7}
+        height={5}
+        rx={1}
+        stroke={stroke}
+        fill={fill}
+        style={{
+          transition: rectTransition,
+          transform: opened
+            ? 'translate(1.5px, 1.5px)'
+            : 'translate(0px, 0px)',
+          fillOpacity: opened ? 0.35 : 0,
+        }}
+      />
+    </svg>
+  );
+}
+
 /**
  * Swimlane headers layer that renders on top of nodes for clickability
  */
 function SwimlaneHeadersLayer({
   swimlanes,
+  parentHeaders,
   laneWidth,
   headerHeight,
-  onToggleCollapse,
+  onToggleNamespace,
+  closingNamespaces,
   stickyHeaders = true,
   transparent = false,
 }: SwimlaneLayerProps) {
   const { x, y, zoom } = useViewport();
   const { theme } = useTheme();
+  const [hoveredNamespace, setHoveredNamespace] = useState<string | null>(null);
 
   // When sticky headers are enabled, compensate for vertical viewport panning
   // to keep headers at the top of the screen
   const headerTop = stickyHeaders ? -y / zoom : 0;
 
+  // Build a unified header list: each namespace currently in view (whether a
+  // leaf or an opened ancestor) gets ONE DOM element keyed by namespace, so
+  // clicking ▶ smoothly morphs the same cell from leaf-shape to parent-shape
+  // (wider, possibly across multiple lanes) instead of unmounting+remounting.
+  type HeaderCell = {
+    namespace: string;
+    label: string;
+    x: number;
+    width: number;
+    depth: number;
+    isOpened: boolean; // currently in `openedNamespaces`
+    isParentOpened: boolean;
+    canExpand: boolean; // only meaningful when !isOpened
+  };
+
+  const headers: HeaderCell[] = useMemo(
+    () => [
+      ...parentHeaders.map((h) => ({
+        namespace: h.namespace,
+        label: h.label,
+        x: h.x,
+        width: h.width,
+        depth: h.depth,
+        isOpened: true,
+        isParentOpened: h.depth > 1,
+        canExpand: false,
+      })),
+      ...swimlanes.map((lane) => ({
+        namespace: lane.namespace,
+        label: lane.label,
+        x: lane.x,
+        width: laneWidth,
+        depth: lane.namespace.split('.').length,
+        isOpened: false,
+        isParentOpened: lane.isParentOpened,
+        canExpand: lane.canExpand,
+      })),
+    ],
+    [parentHeaders, swimlanes, laneWidth]
+  );
+
+
   return (
     <div
       style={{
@@ -485,54 +658,132 @@ function SwimlaneHeadersLayer({
         zIndex: 10,
       }}
     >
-      {/* Lane headers */}
-      {swimlanes.map((lane) => {
-        const hasChildren = lane.children.length > 0;
+      {headers.map((header) => {
+        const rowTop = headerTop + (header.depth - 1) * headerHeight;
+        // Child leaves (under an opened parent) get the differentiated, lighter
+        // styling. Top-level leaves AND opened parents share the original
+        // header look — so the cell you clicked doesn't change appearance, it
+        // just grows to span its children.
+        const isChild = header.isParentOpened && !header.isOpened;
+        const showOpen = header.canExpand && !header.isOpened;
+        const isClickable = header.isOpened || showOpen;
+        // If this child's parent is mid-close, play the exit animation
+        // instead of the entry. After SWIMLANE_CLOSE_EXIT_MS the data
+        // change applies and the child unmounts.
+        const parentNs =
+          header.depth > 1
+            ? header.namespace.split('.').slice(0, -1).join('.')
+            : undefined;
+        const isExiting =
+          isChild && !!parentNs && !!closingNamespaces?.has(parentNs);
+        const cellClassName = isExiting
+          ? 'swimlane-child-out'
+          : isChild
+            ? 'swimlane-child-in'
+            : 'swimlane-fade-in';
         return (
           <div
-            key={`header-${lane.namespace}`}
+            key={header.namespace}
+            className={cellClassName}
+            role={isClickable ? 'button' : undefined}
+            aria-label={
+              header.isOpened
+                ? `Close ${header.namespace}`
+                : showOpen
+                  ? `Open ${header.namespace}`
+                  : undefined
+            }
+            title={
+              header.isOpened
+                ? `${header.namespace} (click to close)`
+                : showOpen
+                  ? `${header.namespace} (click to open)`
+                  : header.namespace
+            }
             style={{
               position: 'absolute',
-              left: lane.x - laneWidth / 2,
-              top: headerTop,
-              width: laneWidth,
+              left: header.x - header.width / 2,
+              top: rowTop,
+              width: header.width,
               height: headerHeight,
               display: 'flex',
               alignItems: 'center',
               justifyContent: 'center',
               padding: '0 8px',
               boxSizing: 'border-box',
-              backgroundColor: transparent ? 'transparent' : theme.colors.muted,
-              borderBottom: `2px solid ${theme.colors.border}`,
-              fontWeight: theme.fontWeights.semibold,
-              fontSize: theme.fontSizes[2],
+              backgroundColor: transparent
+                ? 'transparent'
+                : isChild
+                  ? theme.colors.background
+                  : theme.colors.muted,
+              transition: swimlaneTransition,
+              borderBottom: isChild
+                ? `1px solid ${theme.colors.border}`
+                : `2px solid ${theme.colors.border}`,
+              borderLeft: isChild
+                ? `1px solid ${theme.colors.border}`
+                : 'none',
+              borderRight: isChild
+                ? `1px solid ${theme.colors.border}`
+                : 'none',
+              fontWeight: isChild
+                ? theme.fontWeights.medium
+                : theme.fontWeights.semibold,
+              fontSize: isChild ? theme.fontSizes[1] : theme.fontSizes[2],
               fontFamily: theme.fonts.heading,
-              color: theme.colors.text,
+              color: isChild ? theme.colors.textSecondary : theme.colors.text,
               pointerEvents: 'auto',
-              cursor: hasChildren ? 'pointer' : 'default',
               userSelect: 'none',
+              cursor: isClickable ? 'pointer' : 'default',
+              gap: 6,
+              // Parent (opened) cells sit above leaves so children slide out
+              // from behind them rather than over the top.
+              zIndex: header.isOpened ? 2 : 1,
             }}
-            onClick={() => hasChildren && onToggleCollapse?.(lane.namespace)}
+            onClick={
+              isClickable
+                ? (e) => {
+                    e.stopPropagation();
+                    onToggleNamespace?.(header.namespace);
+                  }
+                : undefined
+            }
+            onMouseEnter={
+              isClickable
+                ? () => setHoveredNamespace(header.namespace)
+                : undefined
+            }
+            onMouseLeave={
+              isClickable
+                ? () =>
+                    setHoveredNamespace((current) =>
+                      current === header.namespace ? null : current
+                    )
+                : undefined
+            }
           >
-            {hasChildren && (
-              <span style={{ marginRight: 6, fontSize: 10 }}>
-                {lane.isCollapsed ? '▼' : '▶'}
-              </span>
-            )}
             <span
               style={{
                 overflowWrap: 'anywhere',
                 wordBreak: 'break-word',
                 lineHeight: 1.2,
                 textAlign: 'center',
+                flex: 1,
               }}
-              title={lane.label}
             >
-              {lane.label}
+              {header.label}
             </span>
+            {(header.isOpened || showOpen) && (
+              <StackIcon
+                opened={header.isOpened}
+                hovered={hoveredNamespace === header.namespace}
+                accentColor={theme.colors.primary}
+              />
+            )}
           </div>
         );
       })}
+
     </div>
   );
 }
@@ -556,8 +807,12 @@ export interface SequenceDiagramRendererProps {
   /** Optional custom edge types */
   edgeTypes?: EdgeTypes;
 
-  /** Callback when a namespace collapse state is toggled */
-  onToggleCollapse?: (namespace: string) => void;
+  /**
+   * Called when the user toggles a lane's drill state via the header
+   * chevrons. Update `layoutOptions.openedNamespaces` in response to
+   * open/close the lane.
+   */
+  onToggleNamespace?: (namespace: string) => void;
 
   /** Callback when a node is clicked */
   onNodeClick?: (nodeId: string, event: React.MouseEvent) => void;
@@ -604,7 +859,7 @@ function SequenceDiagramInner({
   layoutOptions = {},
   nodeTypes: customNodeTypes,
   edgeTypes: customEdgeTypes,
-  onToggleCollapse,
+  onToggleNamespace,
   onNodeClick,
   showControls = true,
   showBackground = false, // Default to false since swimlanes provide visual structure
@@ -618,6 +873,67 @@ function SequenceDiagramInner({
   // Extract layout params
   const { laneWidth = 250, headerHeight = 60 } = layoutOptions;
 
+  // openedNamespaces is controlled if provided in layoutOptions, otherwise
+  // we manage it internally so chevrons work out of the box.
+  const isOpenedControlled = layoutOptions.openedNamespaces !== undefined;
+  const [internalOpened, setInternalOpened] = useState<string[]>([]);
+  const effectiveOpened = isOpenedControlled
+    ? layoutOptions.openedNamespaces
+    : internalOpened;
+
+  // Namespaces currently mid-close. While one is here, the children still
+  // render in the data (lifelines, events, edges unchanged) but their header
+  // cells flip to the exit animation. After the exit completes we apply the
+  // real data change, so the diagram body shifts in sync with the parent
+  // header shrink instead of ahead of it.
+  const [closingNamespaces, setClosingNamespaces] = useState<Set<string>>(
+    () => new Set()
+  );
+
+  const handleToggleNamespace = useCallback(
+    (namespace: string) => {
+      const openedSet =
+        effectiveOpened instanceof Set
+          ? effectiveOpened
+          : new Set(effectiveOpened ?? []);
+      const isCurrentlyOpened = openedSet.has(namespace);
+
+      if (isCurrentlyOpened) {
+        // Stage the close: animate children out first, then apply data change.
+        setClosingNamespaces((prev) => {
+          if (prev.has(namespace)) return prev;
+          const next = new Set(prev);
+          next.add(namespace);
+          return next;
+        });
+        setTimeout(() => {
+          if (!isOpenedControlled) {
+            setInternalOpened((prev) => prev.filter((n) => n !== namespace));
+          }
+          onToggleNamespace?.(namespace);
+          setClosingNamespaces((prev) => {
+            if (!prev.has(namespace)) return prev;
+            const next = new Set(prev);
+            next.delete(namespace);
+            return next;
+          });
+        }, SWIMLANE_CLOSE_EXIT_MS);
+      } else {
+        // Open: data change is immediate; children animate in via CSS.
+        if (!isOpenedControlled) {
+          setInternalOpened((prev) => [...prev, namespace]);
+        }
+        onToggleNamespace?.(namespace);
+      }
+    },
+    [effectiveOpened, isOpenedControlled, onToggleNamespace]
+  );
+
+  const effectiveLayoutOptions = useMemo(
+    () => ({ ...layoutOptions, openedNamespaces: effectiveOpened }),
+    [layoutOptions, effectiveOpened]
+  );
+
   // Merge custom node/edge types with sequence defaults
   const nodeTypes = useMemo(
     () => ({ ...defaultSequenceNodeTypes, ...customNodeTypes }),
@@ -629,11 +945,15 @@ function SequenceDiagramInner({
   );
 
   // Compute layout
-  const { nodes: layoutNodes, edges, swimlanes, totalWidth, totalHeight } = useSequenceLayout(
-    events,
-    sequenceEdges,
-    layoutOptions
-  );
+  const {
+    nodes: layoutNodes,
+    edges,
+    swimlanes,
+    parentHeaders,
+    headerRows,
+    totalWidth,
+    totalHeight,
+  } = useSequenceLayout(events, sequenceEdges, effectiveLayoutOptions);
 
   // Mark selected node and add showEventLabels to node data
   const nodes = useMemo(() => {
@@ -730,6 +1050,7 @@ function SequenceDiagramInner({
       translateExtent={translateExtent}
       style={{ background: transparent ? 'transparent' : theme.colors.background }}
     >
+      <style>{swimlaneAnimationStyles}</style>
       {/* SVG defs for arrow markers */}
       <svg style={{ position: 'absolute', width: 0, height: 0 }}>
         <defs>
@@ -774,6 +1095,8 @@ function SequenceDiagramInner({
       {/* Swimlane layer - renders behind nodes */}
       <SwimlaneLayer
         swimlanes={swimlanes}
+        parentHeaders={parentHeaders}
+        headerRows={headerRows}
         laneWidth={laneWidth}
         headerHeight={headerHeight}
         totalHeight={totalHeight}
@@ -783,16 +1106,18 @@ function SequenceDiagramInner({
       {/* Swimlane headers layer - renders on top for clickability */}
       <SwimlaneHeadersLayer
         swimlanes={swimlanes}
+        parentHeaders={parentHeaders}
+        headerRows={headerRows}
         laneWidth={laneWidth}
         headerHeight={headerHeight}
         totalHeight={totalHeight}
-        onToggleCollapse={onToggleCollapse}
+        onToggleNamespace={handleToggleNamespace}
+        closingNamespaces={closingNamespaces}
         stickyHeaders={stickyHeaders}
         transparent={transparent}
       />
 
-      {/* Collapse toggle panel (for namespaces with children) */}
-      {swimlanes.some((s) => s.children.length > 0) && (
+      {(swimlanes.some((s) => s.canExpand) || parentHeaders.length > 0) && (
         <Panel position="top-right">
           <div
             style={{
@@ -803,9 +1128,15 @@ function SequenceDiagramInner({
               fontSize: theme.fontSizes[0],
               fontFamily: theme.fonts.body,
               color: theme.colors.textSecondary,
+              display: 'flex',
+              alignItems: 'center',
+              gap: 6,
             }}
           >
-            Click lane headers to expand/collapse
+            <StackIcon accentColor={theme.colors.primary} />
+            <span>to drill in · click parent header</span>
+            <StackIcon opened accentColor={theme.colors.primary} />
+            <span>to close</span>
           </div>
         </Panel>
       )}

package/src/components/WorkflowSequenceDiagram.tsx

@@ -146,8 +146,8 @@ function convertWorkflowToSequence(
     const isMoveEvent = eventToMoveEventMap.get(eventName) ?? true;
 
     // When the canvas provides a scope, prefix it so the event lands in that
-    // participant's lane. Otherwise, use the event name as-is so the layout's
-    // namespace strategy can derive the participant from the event name itself.
+    // participant's lane (the layout uses the first dotted segment as the
+    // default lane). Otherwise, use the event name as-is.
     const name = canvasScope ? `${canvasScope}.${eventName}` : eventName;
     const participant = canvasScope ?? eventName.split('.')[0] ?? eventName;
 
@@ -186,10 +186,7 @@ function convertWorkflowToSequence(
  *   scenario={workflowScenario}
  *   canvas={otelCanvas}
  *   height={600}
- *   layoutOptions={{
- *     namespaceStrategy: 'first',
- *     eventSpacing: 80,
- *   }}
+ *   layoutOptions={{ eventSpacing: 80 }}
  * />
  * ```
  */