@mindlogic-ai/logician-ui 3.1.0-alpha.9 → 3.2.0-alpha.0

package/src/components/Workflow/WorkflowContext/WorkflowContext.tsx

@@ -0,0 +1,215 @@
+'use client';
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import type { Issue, RunState } from '../Workflow.types';
+import type {
+  DrawerTarget,
+  WorkflowContextValue,
+  WorkflowProviderProps,
+} from './WorkflowContext.types';
+
+const WorkflowContext = createContext<WorkflowContextValue | null>(null);
+
+export function useWorkflow(): WorkflowContextValue {
+  const ctx = useContext(WorkflowContext);
+  if (!ctx) {
+    throw new Error('useWorkflow must be used inside a <Workflow> component');
+  }
+  return ctx;
+}
+
+/**
+ * Convenience accessor for the host-injected translator. Canvas chrome calls
+ * this exactly where it would otherwise reach for an app-level `useTranslate`,
+ * keeping the core free of any direct i18n dependency.
+ */
+export function useWorkflowTranslate() {
+  return useWorkflow().translate;
+}
+
+export function WorkflowProvider({
+  graph,
+  dispatch,
+  undo,
+  redo,
+  canUndo,
+  canRedo,
+  nodeTypes,
+  translate,
+  issues,
+  onArrange,
+  readOnly = false,
+  onSelectionChange,
+  validating = false,
+  categoryTokens,
+  hostBridge,
+  children,
+}: WorkflowProviderProps) {
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
+  const [selectedEdgeId, setSelectedEdgeId] = useState<string | null>(null);
+  const [drawerTarget, setDrawerTarget] = useState<DrawerTarget | null>(null);
+  const [runStates, setRunStates] = useState<Record<string, RunState>>({});
+  const [fieldFocusRequest, setFieldFocusRequest] = useState<{
+    nodeId: string;
+    fieldKey: string;
+  } | null>(null);
+
+  const requestFieldFocus = useCallback((nodeId: string, fieldKey: string) => {
+    setFieldFocusRequest({ nodeId, fieldKey });
+  }, []);
+
+  const consumeFieldFocusRequest = useCallback(
+    () => setFieldFocusRequest(null),
+    []
+  );
+
+  const setRunState = useCallback((id: string, state: RunState) => {
+    setRunStates((prev) => ({ ...prev, [id]: state }));
+  }, []);
+
+  const resetRunStates = useCallback(() => setRunStates({}), []);
+
+  // Single entry point for "select this element": every open-intent caller
+  // (canvas node/edge click, edge label, error-banner jump) routes through here
+  // so selection lives in one place. The host is notified via the
+  // `onSelectionChange` effect below.
+  const revealInspector = useCallback(
+    (target: DrawerTarget) => setDrawerTarget(target),
+    []
+  );
+
+  // Notify the host whenever the selected element changes — so it can drive its
+  // own inspector / side panel anywhere in its layout. Keyed on the target
+  // identity (set fresh per click), so graph edits don't re-fire it; the
+  // node/edge snapshot is read at fire time via a ref to avoid stale closures.
+  const graphRef = useRef(graph);
+  graphRef.current = graph;
+  useEffect(() => {
+    if (!onSelectionChange) return;
+    if (!drawerTarget) {
+      onSelectionChange(null);
+      return;
+    }
+    const g = graphRef.current;
+    if (drawerTarget.type === 'node') {
+      const node = g.nodes.find((n) => n.id === drawerTarget.id);
+      onSelectionChange(node ? { type: 'node', id: node.id, node } : null);
+    } else {
+      const edge = g.edges.find((e) => e.id === drawerTarget.id);
+      onSelectionChange(edge ? { type: 'edge', id: edge.id, edge } : null);
+    }
+    // Depends on `drawerTarget` only — fire on selection-identity change, not on
+    // every graph edit (the node/edge snapshot is read via `graphRef`).
+  }, [drawerTarget]);
+
+  const getNodeType = useCallback(
+    (kind: string) => nodeTypes[kind],
+    [nodeTypes]
+  );
+
+  const issuesByNode = useMemo(() => {
+    const map: Record<string, Issue[]> = {};
+    for (const issue of issues) {
+      if (!issue.nodeId) continue;
+      (map[issue.nodeId] ||= []).push(issue);
+    }
+    return map;
+  }, [issues]);
+
+  const issuesByEdge = useMemo(() => {
+    const map: Record<string, Issue[]> = {};
+    for (const issue of issues) {
+      if (!issue.edgeId) continue;
+      (map[issue.edgeId] ||= []).push(issue);
+    }
+    return map;
+  }, [issues]);
+
+  const issuesByField = useMemo(() => {
+    const map: Record<string, Issue[]> = {};
+    for (const issue of issues) {
+      if (!issue.nodeId || !issue.fieldKey) continue;
+      const key = `${issue.nodeId}.${issue.fieldKey}`;
+      (map[key] ||= []).push(issue);
+    }
+    return map;
+  }, [issues]);
+
+  const value = useMemo<WorkflowContextValue>(
+    () => ({
+      graph,
+      dispatch,
+      undo,
+      redo,
+      canUndo,
+      canRedo,
+      nodeTypes,
+      getNodeType,
+      translate,
+      issues,
+      issuesByNode,
+      issuesByEdge,
+      issuesByField,
+      editor: { selectedNodeId, selectedEdgeId, drawerTarget, runStates },
+      onArrange,
+      setSelectedNodeId,
+      setSelectedEdgeId,
+      setDrawerTarget,
+      revealInspector,
+      setRunState,
+      resetRunStates,
+      fieldFocusRequest,
+      requestFieldFocus,
+      consumeFieldFocusRequest,
+      readOnly,
+      validating,
+      categoryTokens,
+      hostBridge,
+    }),
+    [
+      graph,
+      dispatch,
+      undo,
+      redo,
+      canUndo,
+      canRedo,
+      nodeTypes,
+      getNodeType,
+      translate,
+      issues,
+      issuesByNode,
+      issuesByEdge,
+      issuesByField,
+      onArrange,
+      selectedNodeId,
+      selectedEdgeId,
+      drawerTarget,
+      revealInspector,
+      runStates,
+      setRunState,
+      resetRunStates,
+      fieldFocusRequest,
+      requestFieldFocus,
+      consumeFieldFocusRequest,
+      readOnly,
+      validating,
+      categoryTokens,
+      hostBridge,
+    ]
+  );
+
+  return (
+    <WorkflowContext.Provider value={value}>
+      {children}
+    </WorkflowContext.Provider>
+  );
+}

package/src/components/Workflow/WorkflowContext/WorkflowContext.types.ts

@@ -0,0 +1,122 @@
+import type { ReactNode } from 'react';
+
+import type { CategoryTokenMap } from '../canvas/IconTile';
+import type { GraphAction } from '../graphReducer';
+import type {
+  Graph,
+  Issue,
+  NodeTypeDef,
+  NodeTypeRegistry,
+  RunState,
+  WorkflowSelection,
+  WorkflowTranslate,
+} from '../Workflow.types';
+
+/**
+ * What the right-hand inspector drawer is currently showing. A node and an
+ * edge share the same drawer surface, so a single discriminated target — set
+ * together with the matching canvas-selection id — keeps "what's selected" and
+ * "what's inspected" in lockstep without two separate drawer ids.
+ */
+export type DrawerTarget =
+  | { type: 'node'; id: string }
+  | { type: 'edge'; id: string };
+
+export type EditorState = {
+  selectedNodeId: string | null;
+  /** Currently selected edge id (canvas selection highlight). */
+  selectedEdgeId: string | null;
+  /** Node or edge whose properties the inspector drawer renders, or null. */
+  drawerTarget: DrawerTarget | null;
+  runStates: Record<string, RunState>;
+};
+
+export type WorkflowContextValue = {
+  graph: Graph;
+  dispatch: (action: GraphAction) => void;
+  undo: () => void;
+  redo: () => void;
+  canUndo: boolean;
+  canRedo: boolean;
+  nodeTypes: NodeTypeRegistry;
+  getNodeType: (kind: string) => NodeTypeDef | undefined;
+  /** Host-injected translator for the editor's chrome copy. */
+  translate: WorkflowTranslate;
+  issues: Issue[];
+  issuesByNode: Record<string, Issue[]>;
+  /** Issues keyed by `edgeId` — surfaced in the edge inspector drawer. */
+  issuesByEdge: Record<string, Issue[]>;
+  /**
+   * Issues keyed by `${nodeId}.${fieldKey}` for inline field rendering.
+   * Issues missing a `fieldKey` (graph-wide checks, generic node issues) do
+   * not appear here — those still surface in the canvas validation banner.
+   */
+  issuesByField: Record<string, Issue[]>;
+  editor: EditorState;
+  /**
+   * Host hook fired with the laid-out graph when the user runs auto-arrange.
+   * See `WorkflowProps.onArrange` — lets the host force-persist the reposition.
+   */
+  onArrange?: (graph: Graph) => void;
+  setSelectedNodeId: (id: string | null) => void;
+  setSelectedEdgeId: (id: string | null) => void;
+  /** Set (or clear) the node/edge the inspector drawer renders. */
+  setDrawerTarget: (target: DrawerTarget | null) => void;
+  setRunState: (id: string, state: RunState) => void;
+  resetRunStates: () => void;
+  /**
+   * Latest `(nodeId, fieldKey)` the user asked to jump to via the canvas
+   * validation banner. FieldWrapper subscribes — if its key matches it
+   * scrolls into view and focuses the input, then calls
+   * `consumeFieldFocusRequest` so a re-render doesn't refocus repeatedly.
+   */
+  fieldFocusRequest: { nodeId: string; fieldKey: string } | null;
+  requestFieldFocus: (nodeId: string, fieldKey: string) => void;
+  consumeFieldFocusRequest: () => void;
+  readOnly: boolean;
+  /**
+   * Select a node or edge and make it the inspector's target. Every "open this
+   * element's details" entry point — canvas node/edge click, edge label,
+   * error-banner jump — routes through here so selection stays in one place
+   * (read it via `editor.drawerTarget`; the host is also notified through
+   * `WorkflowProps.onSelectionChange`).
+   */
+  revealInspector: (target: DrawerTarget) => void;
+  /**
+   * Issues are being recomputed (host save/validation in flight). Surfaces a
+   * loading affordance (e.g. in `GraphErrorBanner`) so an empty `issues` list
+   * mid-validation isn't treated as "no issues". See `WorkflowProps.validating`.
+   */
+  validating: boolean;
+  /** Optional host override for category → token map. */
+  categoryTokens?: CategoryTokenMap;
+  /**
+   * Opaque host bridge threaded down to inspectors so they can reach
+   * host-supplied data (live model list, tool catalog, etc.) without the
+   * generic Workflow core depending on FactChat APIs. Inspectors narrow it.
+   */
+  hostBridge?: unknown;
+};
+
+export type WorkflowProviderProps = {
+  graph: Graph;
+  dispatch: (action: GraphAction) => void;
+  undo: () => void;
+  redo: () => void;
+  canUndo: boolean;
+  canRedo: boolean;
+  nodeTypes: NodeTypeRegistry;
+  /** Host-injected translator for the editor's chrome copy. */
+  translate: WorkflowTranslate;
+  issues: Issue[];
+  /** See `WorkflowContextValue.onArrange`. */
+  onArrange?: (graph: Graph) => void;
+  readOnly?: boolean;
+  /** See `WorkflowProps.onSelectionChange`. Fired by the provider on selection change. */
+  onSelectionChange?: (selection: WorkflowSelection | null) => void;
+  /** See `WorkflowContextValue.validating`. */
+  validating?: boolean;
+  categoryTokens?: CategoryTokenMap;
+  hostBridge?: unknown;
+  children: ReactNode;
+};

package/src/components/Workflow/WorkflowContext/index.ts

@@ -0,0 +1,10 @@
+export {
+  useWorkflow,
+  useWorkflowTranslate,
+  WorkflowProvider,
+} from './WorkflowContext';
+export type {
+  EditorState,
+  WorkflowContextValue,
+  WorkflowProviderProps,
+} from './WorkflowContext.types';

package/src/components/Workflow/WorkflowContext/workflowSelection.test.tsx

@@ -0,0 +1,93 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { Graph, WorkflowSelection } from '../Workflow.types';
+import { useWorkflow, WorkflowProvider } from './WorkflowContext';
+
+/**
+ * Covers the selection seam added when the inspector became opt-in: the provider
+ * must surface the selected node/edge to the host via `onSelectionChange` (the
+ * signal a host uses to drive its own inspector anywhere in its layout), and
+ * clear it on deselect. Exercised without React Flow — `revealInspector`/
+ * `setDrawerTarget` are the same entry points the canvas click handlers use.
+ */
+const graph: Graph = {
+  nodes: [
+    { id: 'n1', kind: 'task', position: { x: 0, y: 0 }, config: { v: 1 } },
+  ],
+  edges: [{ id: 'e1', source: 'n1', target: 'n1' }],
+};
+
+function Harness() {
+  const { revealInspector, setDrawerTarget } = useWorkflow();
+  return (
+    <>
+      <button onClick={() => revealInspector({ type: 'node', id: 'n1' })}>
+        select-node
+      </button>
+      <button onClick={() => revealInspector({ type: 'edge', id: 'e1' })}>
+        select-edge
+      </button>
+      <button onClick={() => setDrawerTarget(null)}>clear</button>
+    </>
+  );
+}
+
+function renderWithProvider(
+  onSelectionChange: (s: WorkflowSelection | null) => void
+) {
+  return render(
+    <WorkflowProvider
+      graph={graph}
+      dispatch={() => {}}
+      undo={() => {}}
+      redo={() => {}}
+      canUndo={false}
+      canRedo={false}
+      nodeTypes={{}}
+      translate={(key) => key}
+      issues={[]}
+      onSelectionChange={onSelectionChange}
+    >
+      <Harness />
+    </WorkflowProvider>
+  );
+}
+
+describe('Workflow selection (onSelectionChange)', () => {
+  it('fires null initially (nothing selected)', () => {
+    const spy = vi.fn();
+    renderWithProvider(spy);
+    expect(spy).toHaveBeenLastCalledWith(null);
+  });
+
+  it('surfaces the selected node with its snapshot', () => {
+    const spy = vi.fn();
+    renderWithProvider(spy);
+    fireEvent.click(screen.getByText('select-node'));
+    expect(spy).toHaveBeenLastCalledWith({
+      type: 'node',
+      id: 'n1',
+      node: graph.nodes[0],
+    });
+  });
+
+  it('surfaces the selected edge with its snapshot', () => {
+    const spy = vi.fn();
+    renderWithProvider(spy);
+    fireEvent.click(screen.getByText('select-edge'));
+    expect(spy).toHaveBeenLastCalledWith({
+      type: 'edge',
+      id: 'e1',
+      edge: graph.edges[0],
+    });
+  });
+
+  it('fires null again on deselect', () => {
+    const spy = vi.fn();
+    renderWithProvider(spy);
+    fireEvent.click(screen.getByText('select-node'));
+    fireEvent.click(screen.getByText('clear'));
+    expect(spy).toHaveBeenLastCalledWith(null);
+  });
+});

package/src/components/Workflow/canvas/Canvas/BranchLabelBadge.tsx

@@ -0,0 +1,69 @@
+'use client';
+
+import type { MouseEvent, ReactNode } from 'react';
+
+import { Badge } from '@/components/Badge';
+import { TbCheck, TbX } from '@/components/Icon';
+
+import type { EdgeLabelVariant } from './edgeLabelVariant';
+
+/**
+ * Badge variant per branch-label kind. Pass / Fail are a binary safety outcome
+ * so they read semantic (green / red); every routing key (If-Else branches, the
+ * If-Else `else` fallback, Classify categories) and any free-text label reads as
+ * a single neutral badge so the branch names all look alike.
+ */
+const VARIANT_BADGE: Record<
+  EdgeLabelVariant,
+  'success' | 'danger' | 'neutral'
+> = {
+  pass: 'success',
+  fail: 'danger',
+  key: 'neutral',
+  else: 'neutral',
+  default: 'neutral',
+};
+
+/**
+ * The chip that names a node's exit branch. Rendered in two places that must
+ * look identical so it reads as the SAME badge relocating: at the node's output
+ * handle (while the exit is unconnected) and on the connected edge's midpoint.
+ *
+ * A drop shadow lifts it off the tinted canvas in light mode; in dark mode a
+ * shadow can't lift anything, so the chip trades it for a hairline ring and
+ * the neutral variant raises its fill clear of the canvas.
+ */
+export function BranchLabelBadge({
+  variant,
+  children,
+  onClick,
+}: {
+  variant: EdgeLabelVariant;
+  children: ReactNode;
+  /** When set, the badge is clickable (the edge uses this to open its
+   * inspector); omitted at the node handle, where the badge is inert. */
+  onClick?: (e: MouseEvent) => void;
+}) {
+  const badgeVariant = VARIANT_BADGE[variant];
+  return (
+    <Badge
+      variant={badgeVariant}
+      boxShadow="sm"
+      _dark={{
+        boxShadow: '0 0 0 1px {colors.border.strong}',
+        // slate.300, not the semantically-equivalent bg.emphasized: Chakra
+        // resolves `bg.*` tokens referenced inside a nested condition to their
+        // BASE value (rendering the light-gray light-mode fill in dark mode);
+        // the slate ramp resolves correctly here. No upstream issue filed —
+        // verified via rendered-DOM probe, 2026-06-12.
+        bgColor: badgeVariant === 'neutral' ? 'slate.300' : undefined,
+      }}
+      cursor={onClick ? 'pointer' : 'default'}
+      onClick={onClick}
+    >
+      {variant === 'pass' ? <TbCheck boxSize="xs" aria-hidden /> : null}
+      {variant === 'fail' ? <TbX boxSize="xs" aria-hidden /> : null}
+      {children}
+    </Badge>
+  );
+}

package/src/components/Workflow/canvas/Canvas/Canvas.styles.ts

@@ -0,0 +1,91 @@
+import { type DefaultEdgeOptions, MarkerType } from '@xyflow/react';
+
+/**
+ * Edge defaults. Stroke comes from a theme token (slate.700) via CSS var
+ * since React Flow takes SVG-style props, not Chakra ones. The label
+ * itself is rendered through the `labeled` custom edge so its
+ * typography uses the design system's semantic `Subtext` primitive —
+ * see `LabeledEdge.tsx`. The arrowhead makes each edge's direction
+ * self-describing rather than implied by left→right placement alone.
+ */
+export const defaultEdgeOptions: DefaultEdgeOptions = {
+  type: 'labeled',
+  style: {
+    stroke: 'var(--chakra-colors-slate-700)',
+    strokeWidth: 1.5,
+  },
+  markerEnd: {
+    type: MarkerType.ArrowClosed,
+    color: 'var(--chakra-colors-slate-700)',
+    width: 18,
+    height: 18,
+  },
+};
+
+/**
+ * Selection outline for edges. React Flow toggles `.selected` on the
+ * edge group; we layer an outline on the path so the user gets visual
+ * feedback before pressing Delete. Scoped via the Canvas wrapper's
+ * `css` prop rather than a global stylesheet.
+ */
+export const canvasSelectionCss = {
+  // Ports paint as 8px dots (see PORT_STYLE) but that's a pixel-hunt drag
+  // target; a pseudo-element participates in its parent's hit-testing, so this
+  // pads every handle's grab area to ~24px without changing the visual dot.
+  '& .react-flow__handle::after': {
+    content: '""',
+    position: 'absolute',
+    inset: '-8px',
+  },
+  // Hover feedback: thicken/darken the path so an edge reads as grabbable
+  // before it's selected. Listed before the `.selected` rule (equal
+  // specificity) so selection styling wins when an edge is both.
+  '& .react-flow__edge:hover .react-flow__edge-path': {
+    stroke: 'var(--chakra-colors-slate-900)',
+    strokeWidth: 2,
+  },
+  '& .react-flow__edge.selected .react-flow__edge-path': {
+    stroke: 'var(--chakra-colors-primary-main)',
+    strokeWidth: 2.5,
+    filter: 'drop-shadow(0 0 4px var(--chakra-colors-primary-lighter))',
+  },
+  '& .react-flow__edge.selected .react-flow__edge-interaction': {
+    stroke: 'var(--chakra-colors-primary-main)',
+  },
+  // React Flow's stock zoom/lock controls are fixed white — point its theme
+  // vars at our tokens so the cluster follows the color mode (light values match
+  // the stock look). A solid surface (rather than transparent buttons) keeps the
+  // icons legible as the canvas pans content beneath the cluster, and matches the
+  // minimap panel in the opposite corner. Frame it like the node cards — md
+  // radius + slate.200 border + shadow — so it reads as a deliberate floating
+  // toolbar; the border carries the definition in dark mode where the stock
+  // shadow is invisible on the dark canvas. `overflow: hidden` clips the stacked
+  // buttons to the rounded corners (tooltips portal out, so they aren't clipped).
+  '& .react-flow__controls': {
+    '--xy-controls-button-background-color': 'var(--chakra-colors-bg-surface)',
+    '--xy-controls-button-background-color-hover':
+      'var(--chakra-colors-slate-100)',
+    '--xy-controls-button-color': 'var(--chakra-colors-slate-1200)',
+    '--xy-controls-button-color-hover': 'var(--chakra-colors-slate-1500)',
+    '--xy-controls-button-border-color': 'var(--chakra-colors-slate-200)',
+    '--xy-controls-box-shadow': 'var(--chakra-shadows-sm)',
+    borderRadius: 'var(--chakra-radii-md)',
+    border: '1px solid var(--chakra-colors-slate-200)',
+    overflow: 'hidden',
+  },
+  // Our control glyphs (lucide Plus/Minus + Tabler arrows/lock/maximize/sitemap)
+  // are stroke-based — `fill="none"`, `stroke="currentColor"`. React Flow's stock
+  // CSS forces `fill: currentColor` on control-button SVGs (its own icons are
+  // solid), which fills these outline icons into blobs (the lock rendered as a
+  // solid lozenge) and, via its `:disabled svg { fill-opacity: .4 }` companion,
+  // painted a translucent gray inside the disabled undo/redo arrows. Restore the
+  // intended stroke-only rendering.
+  '& .react-flow__controls-button svg': {
+    fill: 'none',
+  },
+  // With fill removed, RF's fill-opacity disabled cue is a no-op — dim the whole
+  // glyph instead so disabled undo/redo still read as inactive.
+  '& .react-flow__controls-button:disabled svg': {
+    opacity: 0.4,
+  },
+};