@kiberon-labs/behave-graph-flow 1.0.0 → 2.0.0

package/tests/util/mergeSockets.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { mergeSockets } from '@/util/mergeSockets';
+
+const specSocket = (name: string, valueType: string) =>
+  ({ name, valueType }) as any;
+
+describe('mergeSockets', () => {
+  it('maps spec sockets to socket-base objects keyed by name', () => {
+    const result = mergeSockets([
+      specSocket('a', 'flow'),
+      specSocket('b', 'string')
+    ]);
+
+    expect(result).toHaveLength(2);
+    expect(result.map((s) => s.key)).toEqual(['a', 'b']);
+    expect(result[0]).toMatchObject({ key: 'a', name: 'a', valueType: 'flow' });
+  });
+
+  it('returns spec sockets unchanged when no dynamic ports are given', () => {
+    const result = mergeSockets([specSocket('a', 'flow')], undefined);
+    expect(result).toEqual([{ key: 'a', name: 'a', valueType: 'flow' }]);
+  });
+
+  it('lets a dynamic port override a spec socket with the same key', () => {
+    const result = mergeSockets(
+      [specSocket('a', 'flow'), specSocket('b', 'string')],
+      [{ key: 'b', name: 'b', valueType: 'integer' } as any]
+    );
+
+    expect(result).toHaveLength(2);
+    const b = result.find((s) => s.key === 'b');
+    expect(b?.valueType).toBe('integer');
+  });
+
+  it('appends dynamic ports that do not match any spec socket', () => {
+    const result = mergeSockets(
+      [specSocket('a', 'flow')],
+      [{ key: 'extra', name: 'extra', valueType: 'boolean' } as any]
+    );
+
+    expect(result.map((s) => s.key)).toEqual(['a', 'extra']);
+  });
+});

package/tests/visual/README.md

@@ -0,0 +1,64 @@
+# Visual (pixel) regression tests
+
+These tests render React components in a **real browser** (Chromium via Playwright)
+and compare a screenshot against a committed baseline using Vitest's built-in
+[`toMatchScreenshot`](https://vitest.dev/guide/browser/visual-regression-testing)
+assertion. They catch unintended rendering regressions that DOM-only unit tests
+miss.
+
+## Scope
+
+Coverage is deliberately minimal and panel-focused: **one snapshot per editor
+panel** (see [`panels.visual.test.tsx`](./panels.visual.test.tsx)), since the
+panels are the composed, regression-prone surfaces. Each panel is rendered
+through the same [`DefaultSystemProvider`](../../stories/defaults/defaultStoryProvider.tsx)
+the Storybook stories use, so it shows representative content.
+
+They are intentionally **separate** from the default `pnpm test` run (which uses
+happy-dom) so the heavier browser runner only starts when explicitly requested.
+
+## Running
+
+```bash
+# one-time: install the Chromium binary Playwright drives
+npx playwright install chromium
+
+# verify components against the committed baselines
+pnpm test:visual
+
+# create/refresh baselines (after an intentional visual change)
+pnpm test:visual:update
+```
+
+## How it works
+
+- Config: [`vitest.visual.config.ts`](../../vitest.visual.config.ts) — browser
+  mode, Playwright/Chromium, headless, fixed `900x700` viewport.
+- Test files: `tests/visual/**/*.visual.test.tsx`.
+- Each panel is rendered inside a fixed-size `640x480` frame on the editor
+  background so screenshots are bounded and stable. The full app stylesheet
+  (`@/index.css`) is imported so `--vscode-*` theme tokens resolve.
+- Baselines live in `__screenshots__/` and are committed. Vitest names them per
+  platform (e.g. `*-chromium-win32.png`), because font rendering and
+  anti-aliasing differ across operating systems.
+
+## Important: baselines are platform-specific
+
+Generate and verify baselines on the **same OS / CI image**. A baseline captured
+on Windows will not match one rendered on Linux. For CI, run
+`pnpm test:visual:update` on the CI platform once (or in a container that matches
+CI) and commit those baselines. The comparator is configured with a small
+`allowedMismatchedPixelRatio` to tolerate negligible anti-aliasing noise.
+
+## Adding a panel
+
+When a new panel is added under `src/components/panels`, add one entry to the
+`panels` array in [`panels.visual.test.tsx`](./panels.visual.test.tsx):
+
+```tsx
+['myPanel', <MyPanel />],
+```
+
+Then run `pnpm test:visual:update` to create the baseline, eyeball the generated
+PNG, and commit it. Keep it to a single representative snapshot per panel — the
+unit tests under `tests/util` and `tests/components` cover finer-grained logic.

package/tests/visual/panels.visual.test.tsx

@@ -0,0 +1,76 @@
+// Full editor stylesheet (vscode theme vars, rc-dock, reactflow, etc.) so the
+// panels render the way they do in the real app.
+import '@/index.css';
+
+import type { ReactElement } from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { page } from 'vitest/browser';
+import { cleanup, render } from 'vitest-browser-react';
+import { DefaultSystemProvider } from '../../stories/defaults/defaultStoryProvider';
+
+import { AlignmentPanel } from '@/components/panels/alignment';
+import { ConversationPanel } from '@/components/panels/conversation';
+import { EventsPanel } from '@/components/panels/events';
+import { HistoryPanel } from '@/components/panels/history';
+import { KeymapsPanel } from '@/components/panels/keymaps';
+import { LayersPanel } from '@/components/panels/layers';
+import { LegendPanel } from '@/components/panels/legend';
+import { LogsPanel } from '@/components/panels/logs';
+import { NodeInputsPanel } from '@/components/panels/nodeInputs';
+import { NodePickerPanel } from '@/components/panels/nodePicker';
+import { PanelPanel } from '@/components/panels/panel';
+import { SearchPanel } from '@/components/panels/search';
+import { Settings } from '@/components/panels/systemSettings';
+import { TracesPanel } from '@/components/panels/traces';
+import { VariablesPanel } from '@/components/panels/variables';
+
+/**
+ * One pixel-snapshot per panel. The shared {@link DefaultSystemProvider} (the
+ * same provider the Storybook stories use) supplies a populated System so each
+ * panel renders representative content.
+ */
+const panels: ReadonlyArray<readonly [name: string, element: ReactElement]> = [
+  ['alignment', <AlignmentPanel />],
+  ['conversation', <ConversationPanel />],
+  ['events', <EventsPanel />],
+  ['history', <HistoryPanel />],
+  ['keymaps', <KeymapsPanel />],
+  ['layers', <LayersPanel />],
+  ['legend', <LegendPanel />],
+  ['logs', <LogsPanel />],
+  ['nodeInputs', <NodeInputsPanel />],
+  ['nodePicker', <NodePickerPanel />],
+  ['panel', <PanelPanel />],
+  ['search', <SearchPanel />],
+  ['systemSettings', <Settings />],
+  ['traces', <TracesPanel />],
+  ['variables', <VariablesPanel />]
+];
+
+afterEach(() => {
+  cleanup();
+});
+
+describe('panels (visual)', () => {
+  it.each(panels)('renders the %s panel', async (name, element) => {
+    render(
+      <DefaultSystemProvider>
+        <div
+          data-testid="panel-frame"
+          style={{
+            width: 640,
+            height: 480,
+            overflow: 'auto',
+            background: 'var(--vscode-editor-background, #1f1f1f)'
+          }}
+        >
+          {element}
+        </div>
+      </DefaultSystemProvider>
+    );
+
+    await expect(page.getByTestId('panel-frame')).toMatchScreenshot(
+      `panel-${name}`
+    );
+  });
+});

package/tsconfig.base.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Monorepo shared library – base (no references)",
+  "compilerOptions": {
+    /* Base Options: */
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "target": "esnext",
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "moduleDetection": "force",
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    /* Strictness */
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "erasableSyntaxOnly": true,
+    /* Opinion */
+    "module": "preserve",
+    "outDir": "./dist",
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ],
+      "~/*": [
+        "./stories/*"
+      ]
+    },
+    "declaration": true,
+    "declarationMap": true,
+    "jsx": "react-jsx",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+  },
+}

package/tsconfig.json

@@ -1,60 +1,19 @@
-{
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "display": "Monorepo shared library",
-  "compilerOptions": {
-    /* Base Options: */
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "target": "esnext",
-    "allowJs": true,
-    "resolveJsonModule": true,
-    "moduleDetection": "force",
-    "isolatedModules": true,
-    "verbatimModuleSyntax": true,
-    /* Strictness */
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-    "erasableSyntaxOnly": true,
-    /* Opinion */
-    "incremental": true,
-    "tsBuildInfoFile": "./tsconfig.tsbuildinfo",
-    "module": "preserve",
-    "outDir": "./dist",
-    "baseUrl": ".",
-    "rootDir": "./src",
-    "paths": {
-      "~/*": [
-        "./src/*"
-      ],
-      "@/*": [
-        "./src/*"
-      ]
-    },
-    /* Required for project references, which provide go-to-definition in your
-    IDE without first having to build the module, which is essential during development. */
-    "composite": true,
-    /* Assuming your bundler will output everything, but we can not have noEmit
-    enabled because it is not compatible with composite  / project references. Also declaration might be required for references to work fully. Not sure yet... */
-    "declaration": true,
-    "declarationMap": true,
-    "jsx": "react-jsx",
-    "lib": [
-      "dom",
-      "dom.iterable",
-      "esnext"
-    ],
-  },
-  "include": [
-    "./src",
-    "./src/**/*.json",
-  ],
-  "exclude": [
-    "!./src/**"
-  ],
-  "references": [
-    {
-      "path": "../core"
-    }
-  ],
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Monorepo shared library",
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    /* Required for project references, which provide go-to-definition in your
+    IDE without first having to build the module, which is essential during development. */
+    "composite": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./tsconfig.tsbuildinfo",
+  },
+  "include": [
+    "./**/*.ts",
+    "./**/*.tsx",
+    "./**/*.json",
+  ],
+  "exclude": []
 }

package/tsconfig.prod.json

@@ -0,0 +1,23 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "composite": false,
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ],
+      "~/*": [
+        "./stories/*"
+      ],
+      "@kiberon-labs/behave-graph": [
+        "../core/dist/index.d.ts"
+      ]
+    },
+  },
+  "include": [
+    "./src",
+    "./src/**/*.json",
+  ],
+  "exclude": [],
+}

package/tsdown.config.ts

@@ -1,15 +1,27 @@
 import { defineConfig } from 'tsdown';
+import LightningCSS from 'unplugin-lightningcss/rolldown';
 
 export default defineConfig({
-  entry: ['./src/index.ts'],
+  entry: {
+    index: './src/index.ts'
+  },
+
   outDir: 'dist',
   target: 'es2022',
   sourcemap: true,
+  tsconfig: 'tsconfig.prod.json',
   skipNodeModulesBundle: true,
-  external: ['@kiberon-labs/behave-graph'],
+  copy: [{ from: 'src/entry.css', to: 'dist/entry.css' }],
+  plugins: [LightningCSS({ options: { minify: true } })],
+  external: [
+    '@kiberon-labs/behave-graph',
+    '@vscode-elements/react-elements',
+    'rc-dock',
+    'rc-menu'
+  ],
   format: ['esm'],
   dts: true,
+  // unbundle: true,
   logLevel: 'warn',
-  unbundle: true,
   platform: 'neutral'
 });

package/typedoc.json

@@ -1,8 +1,8 @@
-{
-    "extends": [
-        "../../typedoc.base.jsonc"
-    ],
-    "entryPoints": [
-        "src/index.ts"
-    ]
+{
+    "extends": [
+        "../../typedoc.base.jsonc"
+    ],
+    "entryPoints": [
+        "src/index.ts"
+    ]
 }

package/vite.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+import tsconfigPaths from 'vite-tsconfig-paths';
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [tsconfigPaths()]
+});

package/vitest.config.ts

@@ -3,8 +3,11 @@ import { configDefaults, defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
-    exclude: [...configDefaults.exclude],
-    watch: false
+    // Visual/pixel regression tests run in a real browser via the dedicated
+    // vitest.visual.config.ts — keep them out of the happy-dom unit run.
+    exclude: [...configDefaults.exclude, '**/*.visual.test.{ts,tsx}'],
+    watch: false,
+    environment: 'happy-dom'
   },
   resolve: {
     alias: {

package/vitest.visual.config.ts

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { playwright } from '@vitest/browser-playwright';
+import { defineConfig } from 'vitest/config';
+
+/**
+ * Dedicated config for visual (pixel) regression tests.
+ *
+ * These run in a real browser via Vitest browser mode + Playwright and use the
+ * built-in `toMatchScreenshot` assertion to detect rendering regressions.
+ *
+ * Run with `pnpm test:visual` (and `pnpm test:visual:update` to refresh
+ * baselines). It is intentionally separate from the default happy-dom unit-test
+ * config so the heavy browser runner is only spun up when explicitly requested.
+ *
+ * Screenshots are platform-sensitive (fonts/anti-aliasing differ across OSes),
+ * so Vitest stores baselines under per-platform folders. Generate/refresh
+ * baselines on the same platform/CI image that will verify them.
+ */
+export default defineConfig({
+  test: {
+    include: ['tests/visual/**/*.visual.test.{ts,tsx}'],
+    watch: false,
+    browser: {
+      enabled: true,
+      provider: playwright(),
+      headless: true,
+      instances: [{ browser: 'chromium' }],
+      // Deterministic viewport, large enough to contain a panel frame without
+      // introducing page scrollbars that would shift layout.
+      viewport: { width: 900, height: 700 },
+      expect: {
+        toMatchScreenshot: {
+          // Allow a tiny amount of anti-aliasing noise without failing.
+          comparatorName: 'pixelmatch',
+          comparatorOptions: {
+            allowedMismatchedPixelRatio: 0.02
+          }
+        }
+      }
+    }
+  },
+  resolve: {
+    alias: {
+      '~': path.resolve(__dirname, './src'),
+      '@': path.resolve(__dirname, './src')
+    }
+  }
+});

package/src/components/AutoSizeInput.tsx

@@ -1,65 +0,0 @@
-import React from 'react';
-import {
-  type CSSProperties,
-  type HTMLProps,
-  useCallback,
-  useEffect,
-  useRef,
-  useState
-} from 'react';
-
-export type AutoSizeInputProps = HTMLProps<HTMLInputElement> & {
-  minWidth?: number;
-};
-
-const baseStyles: CSSProperties = {
-  position: 'absolute',
-  top: 0,
-  left: 0,
-  visibility: 'hidden',
-  height: 0,
-  width: 'auto',
-  whiteSpace: 'pre'
-};
-
-export const AutoSizeInput: React.FC<AutoSizeInputProps> = ({
-  minWidth = 30,
-  ...props
-}) => {
-  const inputRef = useRef<HTMLInputElement | null>(null);
-  const measureRef = useRef<HTMLSpanElement | null>(null);
-  const [styles, setStyles] = useState<CSSProperties>({});
-
-  // grab the font size of the input on ref mount
-  const setRef = useCallback((input: HTMLInputElement | null) => {
-    if (input) {
-      const styles = window.getComputedStyle(input);
-      setStyles({
-        fontSize: styles.getPropertyValue('font-size'),
-        paddingLeft: styles.getPropertyValue('padding-left'),
-        paddingRight: styles.getPropertyValue('padding-right')
-      });
-    }
-    inputRef.current = input;
-  }, []);
-
-  // measure the text on change and update input
-  useEffect(() => {
-    if (measureRef.current === null) return;
-    if (inputRef.current === null) return;
-
-    const padding = props.type === 'number' || props.type === 'float' ? 20 : 0;
-
-    const width = measureRef.current.clientWidth + padding;
-    inputRef.current.style.width = Math.max(minWidth, width) + 'px';
-  }, [props.value, minWidth, styles, props.type]);
-
-  return (
-    <>
-      <input ref={setRef} {...props} />
-      <span ref={measureRef} style={{ ...baseStyles, ...styles }}>
-        {props.value}
-      </span>
-    </>
-  );
-};

package/src/components/Controls.tsx

@@ -1,87 +0,0 @@
-import type { GraphJSON, NodeSpecJSON } from '@kiberon-labs/behave-graph';
-import {
-  faDownload,
-  faPause,
-  faPlay,
-  faQuestion,
-  faTrash,
-  faUpload
-} from '@fortawesome/free-solid-svg-icons';
-import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
-import { useState } from 'react';
-import React from 'react';
-import { ControlButton, Controls } from 'reactflow';
-
-import { ClearModal } from './modals/ClearModal.js';
-import { HelpModal } from './modals/HelpModal.js';
-import { type Examples, LoadModal } from './modals/LoadModal.js';
-import { SaveModal } from './modals/SaveModal.js';
-
-export type CustomControlsProps = {
-  playing: boolean;
-  togglePlay: () => void;
-  setBehaviorGraph: (value: GraphJSON) => void;
-  examples: Examples;
-  specJson: NodeSpecJSON[] | undefined;
-};
-
-export const CustomControls: React.FC<CustomControlsProps> = ({
-  playing,
-  togglePlay,
-  setBehaviorGraph,
-  examples,
-  specJson
-}: {
-  playing: boolean;
-  togglePlay: () => void;
-  setBehaviorGraph: (value: GraphJSON) => void;
-  examples: Examples;
-  specJson: NodeSpecJSON[] | undefined;
-}) => {
-  const [loadModalOpen, setLoadModalOpen] = useState(false);
-  const [saveModalOpen, setSaveModalOpen] = useState(false);
-  const [helpModalOpen, setHelpModalOpen] = useState(false);
-  const [clearModalOpen, setClearModalOpen] = useState(false);
-
-  return (
-    <>
-      <Controls>
-        <ControlButton title="Help" onClick={() => setHelpModalOpen(true)}>
-          <FontAwesomeIcon icon={faQuestion} />
-        </ControlButton>
-        <ControlButton title="Load" onClick={() => setLoadModalOpen(true)}>
-          <FontAwesomeIcon icon={faUpload} />
-        </ControlButton>
-        <ControlButton title="Save" onClick={() => setSaveModalOpen(true)}>
-          <FontAwesomeIcon icon={faDownload} />
-        </ControlButton>
-        <ControlButton title="Clear" onClick={() => setClearModalOpen(true)}>
-          <FontAwesomeIcon icon={faTrash} />
-        </ControlButton>
-        <ControlButton title="Run" onClick={togglePlay}>
-          <FontAwesomeIcon icon={playing ? faPause : faPlay} />
-        </ControlButton>
-      </Controls>
-      <LoadModal
-        open={loadModalOpen}
-        onClose={() => setLoadModalOpen(false)}
-        setBehaviorGraph={setBehaviorGraph}
-        examples={examples}
-      />
-      {specJson && (
-        <SaveModal
-          open={saveModalOpen}
-          specJson={specJson}
-          onClose={() => setSaveModalOpen(false)}
-        />
-      )}
-      <HelpModal open={helpModalOpen} onClose={() => setHelpModalOpen(false)} />
-      <ClearModal
-        open={clearModalOpen}
-        onClose={() => setClearModalOpen(false)}
-      />
-    </>
-  );
-};
-
-export default CustomControls;