From 265d34b62722067f05a21087a0de78a7bbfd6709 Mon Sep 17 00:00:00 2001 From: handreyrc Date: Tue, 30 Jun 2026 21:42:04 -0400 Subject: [PATCH 1/8] Update documentation files Signed-off-by: handreyrc --- CONTRIBUTING.md | 77 ++++++- README.md | 194 ++++++++++++++++-- packages/i18n/README.md | 174 ++++++++++++---- .../README.md | 145 ++++++++----- .../src/core/README.md | 30 ++- .../src/react-flow/README.md | 149 +++++++++++++- 6 files changed, 645 insertions(+), 124 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e24cabf9..bcf465c8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,10 +50,16 @@ pnpm run build:prod ## Development Environment -This project uses the following core technology stack: +This project uses the following technology stack: -- **Language**: [TypeScript](https://www.typescriptlang.org/) (for type safety and maintainability) -- **Library**: [React](https://react.dev/) (for building the user interface) +- **Language**: [TypeScript](https://www.typescriptlang.org/) with strict mode enabled +- **UI Library**: [React](https://react.dev/) +- **Diagram Rendering**: [@xyflow/react](https://reactflow.dev/) (isolated in `src/react-flow/`) +- **Workflow SDK**: [@serverlessworkflow/sdk](https://github.com/serverlessworkflow/sdk-typescript) (isolated in `src/core/`) +- **Testing**: [Vitest](https://vitest.dev/) for unit tests, [Playwright](https://playwright.dev/) for E2E +- **Linting**: [oxlint](https://oxc.rs/) with TypeScript, React, import, and jsx-a11y plugins +- **Formatting**: [oxfmt](https://oxc.rs/) +- **Component Development**: [Storybook](https://storybook.js.org/) The project aims for the editor to be **embeddable**, with the core logic decoupled from specific platform APIs (like VS Code or Chrome APIs) through an abstraction layer. @@ -63,7 +69,7 @@ If you find a bug or have a question, please check the [existing issues](https:/ 1. Open a new issue using the appropriate template. 2. Provide a clear description of the problem. -3. Include steps to reproduce the bug and provide a sample workflow file (`.sw.json` or `.sw.yaml`) if applicable. +3. Include steps to reproduce the bug and provide a sample workflow file (`.json` or `.yaml`) if applicable. ## Suggesting a Change @@ -110,12 +116,68 @@ If you're unsure whether your use of agents/LLMs is acceptable — ask! We're ha > This isn't about banning AI — it's about keeping this project collaborative, human-driven, and focused on quality. +## Git Hooks + +The project uses [Husky](https://typicode.github.io/husky/) to manage Git hooks automatically after `pnpm install`: + +- **`pre-commit`**: Runs `lint-staged` to automatically format staged files matching `*.{ts,tsx,js,jsx,json,md,yml,yaml}` using oxfmt. +- **`commit-msg`**: Validates that commits include a DCO `Signed-off-by` line. Commits without sign-off will be rejected. + +These hooks help maintain code quality and ensure compliance with project requirements. + +## Testing + +The project uses multiple testing strategies: + +### Unit Tests + +Unit tests are written using [Vitest](https://vitest.dev/) with React Testing Library. Tests mirror the source structure in `tests/`: + +```bash +cd packages/serverless-workflow-diagram-editor +pnpm test +``` + +### End-to-End Tests + +E2E tests use [Playwright](https://playwright.dev/) and are located in `tests-e2e/`: + +```bash +cd packages/serverless-workflow-diagram-editor +pnpm test-e2e # Run tests headless +pnpm test-e2e:ui # Run with Playwright UI +``` + +Before running E2E tests for the first time, install Playwright browsers: + +```bash +# From root directory +pnpm playwright:install:ci +``` + +### Type Checking + +Run TypeScript type checking: + +```bash +cd packages/serverless-workflow-diagram-editor +pnpm typecheck +``` + +## Continuous Integration + +Pull requests automatically trigger: + +- **Netlify Deploy Previews**: Storybook is automatically built and deployed for PRs that modify the `@serverlessworkflow/diagram-editor` package, allowing reviewers to preview changes interactively. +- **Automated Checks**: Linting, type checking, tests, and builds must pass before merging. + ## Pull Request Process 1. **Fork** the repository and create your branch from `main`. 2. **Commit** your changes with clear, descriptive messages. -3. **Verify** your changes by running the appropriate build and/or test commands for the packages you modified. -4. If your PR changes a package, run `pnpm changeset` and commit the generated `.changeset/*.md` file. +3. **DCO Sign-off**: As a CNCF project, all commits must be signed off (`git commit -s`) to certify the Developer Certificate of Origin. The `commit-msg` hook will automatically verify sign-off is present. +4. **Verify** your changes by running the appropriate build and/or test commands for the packages you modified. +5. If your PR changes a package, run `pnpm changeset` and commit the generated `.changeset/*.md` file. As an alternative you may prefer to compare against upstream explicitly: ```bash @@ -128,8 +190,7 @@ If you're unsure whether your use of agents/LLMs is acceptable — ask! We're ha git remote add upstream https://github.com/serverlessworkflow/editor.git ``` -5. **Submit** a Pull Request (PR). -6. **DCO Sign-off**: As a CNCF project, all commits must be signed off (`git commit -s`) to certify the Developer Certificate of Origin. +6. **Submit** a Pull Request (PR). 7. **Review**: At least one maintainer must review and approve your PR before it is merged. --- diff --git a/README.md b/README.md index 09f3172c..338c044f 100644 --- a/README.md +++ b/README.md @@ -16,18 +16,27 @@ # editor -CNCF Serverless Workflow Specification Visual Editor +The official **vendor-neutral visual editor** for the [Open Workflow Specification](https://github.com/serverlessworkflow/specification). + +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![CNCF Sandbox](https://img.shields.io/badge/CNCF-Sandbox-informational)](https://www.cncf.io/projects/serverless-workflow/) + +## Overview + +This project provides an interactive, visual diagram editor designed to be: + +- **Vendor-neutral**: No platform-specific dependencies +- **Embeddable**: Core logic decoupled from platform APIs (VS Code, browser extensions, etc.) +- **Specification-first**: Built around the official Open Workflow Specification ## Prerequisites To build and run the editor locally, you will need: -- **Node.js 22** (current LTS version; see https://nodejs.org/) -- **pnpm 10.31.0** +- **Node.js**: `^22.13.0 || >=24.0.0` (see [nodejs.org](https://nodejs.org/)) +- **pnpm**: `10.31.0` (exact version, enforced by `packageManager` field) -## Building the Project - -The project is structured as a monorepo to support multiple distribution targets (Web, VS Code, etc.) as defined in our architectural decisions. +## Quick Start ```bash # Clone the repository @@ -37,30 +46,183 @@ cd editor # Install dependencies pnpm install -# Build all packages in the monorepo (development) +# Build all packages (development) pnpm run build:dev -# Or build all packages in the monorepo (production) +# Or build all packages (production - includes linting and tests) pnpm run build:prod ``` +## Development + +### Running Storybook + +Storybook provides an interactive development environment for the diagram editor: + +```bash +cd packages/serverless-workflow-diagram-editor +pnpm start # Starts Storybook on http://localhost:6006 +``` + +### Running Tests + +```bash +cd packages/serverless-workflow-diagram-editor + +# Unit tests (Vitest) +pnpm test + +# E2E tests (Playwright) +pnpm test-e2e # Headless +pnpm test-e2e:ui # With Playwright UI + +# Type checking +pnpm typecheck + +# Linting +pnpm lint +``` + +Before running E2E tests for the first time: + +```bash +# From root directory +pnpm playwright:install:ci +``` + +### Code Quality + +```bash +# Format all files +pnpm format + +# Check formatting without modifying +pnpm format:check + +# Check dependency versions across packages +pnpm dependencies:check + +# Fix dependency version mismatches +pnpm dependencies:fix +``` + ## Repository Structure ``` editor/ -├── .github/ # CI workflows, issue templates, Dependabot -├── .husky/ # Git hooks (commit-msg, pre-commit) +├── .github/ # CI workflows, issue templates, Dependabot config +├── .husky/ # Git hooks (commit-msg for DCO, pre-commit for linting) +├── adr/ # Architecture Decision Records ├── packages/ # Monorepo workspace packages +│ ├── serverless-workflow-diagram-editor/ # Main diagram editor component +│ └── i18n/ # Internationalization utilities +├── .changeset/ # Changesets for version management ├── .oxfmtrc.json # Formatter config (oxfmt) ├── .oxlintrc.json # Linter config (oxlint) ├── .syncpackrc.json # Monorepo package version consistency -├── netlify.toml # Netlify configuration for Storybook preview deployment -├── pnpm-workspace.yaml # pnpm workspace definition -└── tsconfig.base.json # Shared TypeScript config +├── netlify.toml # Netlify configuration for Storybook previews +├── pnpm-workspace.yaml # pnpm workspace definition with catalog dependencies +├── tsconfig.base.json # Shared TypeScript config (strict mode enabled) +└── CONTRIBUTING.md # Contribution guidelines ``` -### Key Packages +## Packages + +### [@serverlessworkflow/diagram-editor](./packages/serverless-workflow-diagram-editor) + +The main visual diagram editor component built with: + +- **TypeScript** (strict mode) +- **React** +- **[@xyflow/react](https://reactflow.dev/)** for diagram rendering (isolated in `src/react-flow/`) +- **[@serverlessworkflow/sdk](https://github.com/serverlessworkflow/sdk-typescript)** (isolated in `src/core/`) +- **[shadcn/ui](https://ui.shadcn.com/)** for UI primitives (with `dec:` Tailwind prefix) +- **[Storybook](https://storybook.js.org/)** for component development +- **[Vitest](https://vitest.dev/)** and **[Playwright](https://playwright.dev/)** for testing + +### [@serverlessworkflow/i18n](./packages/i18n) + +Internationalization utilities used by the diagram editor. + +## Technology Stack + +- **Language**: [TypeScript](https://www.typescriptlang.org/) with strict mode +- **UI Framework**: [React](https://react.dev/) +- **Diagram Library**: [@xyflow/react](https://reactflow.dev/) (React Flow) +- **Auto Layout**: [ELK.js](https://eclipse.dev/elk/) +- **Workflow SDK**: [@serverlessworkflow/sdk](https://github.com/serverlessworkflow/sdk-typescript) +- **UI Components**: [shadcn/ui](https://ui.shadcn.com/) + [Radix UI](https://www.radix-ui.com/) +- **Styling**: [Tailwind CSS](https://tailwindcss.com/) +- **Testing**: [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/) +- **Linting**: [oxlint](https://oxc.rs/) +- **Formatting**: [oxfmt](https://oxc.rs/) +- **Component Development**: [Storybook](https://storybook.js.org/) +- **Build Tool**: [Vite](https://vite.dev/) +- **Package Manager**: [pnpm](https://pnpm.io/) + +## Architecture + +The diagram editor maintains strict separation of concerns: + +- **SDK Isolation**: Only `src/core/workflowSdk.ts` and `src/core/graph.ts` import from `@serverlessworkflow/sdk` +- **React Flow Isolation**: All `@xyflow/react` code is contained in `src/react-flow/` +- **Platform Agnostic**: Core logic decoupled from platform-specific APIs +- **Embeddable**: Designed for integration into VS Code, web apps, and browser extensions + +See [adr/](./adr/) for Architecture Decision Records. + +## Contributing + +We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details on: + +- Setting up your development environment +- Coding standards and best practices +- Testing requirements +- Pull request process +- DCO sign-off requirements (required for all commits) + +### DCO Sign-off + +As a CNCF project, all commits must include a `Signed-off-by` line: + +```bash +git commit -s -m "Your commit message" +``` + +The `commit-msg` hook will automatically verify DCO compliance. + +## Continuous Integration + +- **Automated Testing**: All PRs run linting, type checking, unit tests, and E2E tests +- **Netlify Previews**: Storybook is automatically deployed for PRs modifying the diagram editor package +- **Dependency Updates**: Automated via Dependabot +- **License Header Checks**: Apache 2.0 headers verified on all source files + +## Release Process + +This project uses [Changesets](https://github.com/changesets/changesets) for version management: + +```bash +# Create a changeset when making package changes +pnpm changeset + +# Or compare against upstream explicitly +pnpm changeset --since upstream/main +``` + +See [RELEASE_PROCESS.md](./RELEASE_PROCESS.md) for details. + +## Community + +- **Slack**: Join [#serverless-workflow](https://cloud-native.slack.com/archives/C06PYFT9HTZ) on [CNCF Slack](https://slack.cncf.io/) +- **Issues**: [GitHub Issues](https://github.com/serverlessworkflow/editor/issues) +- **Discussions**: [GitHub Discussions](https://github.com/serverlessworkflow/editor/discussions) + +## License + +This project is licensed under the [Apache License 2.0](LICENSE). -#### packages/serverless-workflow-diagram-editor/ +## Related Projects -The visual diagram editor for the [Serverless Workflow Specification](https://github.com/serverlessworkflow/specification/). Built with React Flow for interactive diagram rendering and includes Storybook for component development. +- [Open Workflow Specification](https://github.com/serverlessworkflow/specification) +- [Serverless Workflow SDK (TypeScript)](https://github.com/serverlessworkflow/sdk-typescript) diff --git a/packages/i18n/README.md b/packages/i18n/README.md index 8e0bd6bf..ebfce586 100644 --- a/packages/i18n/README.md +++ b/packages/i18n/README.md @@ -14,90 +14,184 @@ limitations under the License. --> -# i18n Usage Guide +# @serverlessworkflow/i18n -This guide explains how to use the `@serverlessworkflow/i18n` package inside your project (e.g., in the `DiagramEditor`). +A lightweight internationalization (i18n) package for React applications, providing simple translation support with automatic locale detection. ---- +## Overview -## What this package provides +This package provides a minimal i18n solution built on React Context, designed for use in the Serverless Workflow Diagram Editor and other React applications. -- `I18nProvider` → React context provider for translations -- `useI18n()` → Hook to access translations -- `detectLocale()` → Automatically detect user language -- `createI18n()` → Core translation logic (used internally) +## Features ---- +- **React Context-based**: Simple provider/hook pattern +- **Automatic locale detection**: Uses browser language preferences +- **Type-safe**: Built with TypeScript +- **Lightweight**: No heavy dependencies +- **Fallback support**: Returns keys when translations are missing -## Step 1: Define your dictionaries +## Installation -Create a file like: +```bash +pnpm add @serverlessworkflow/i18n +``` + +## API Reference + +### Exports + +- `I18nProvider` - React context provider for translations +- `useI18n()` - Hook to access translation function and current locale +- `createI18n()` - Core translation logic (typically used internally) +- `detectLocale()` - Automatically detect user's preferred language + +### Types ```ts -// i18n/locales.ts +type Dictionary = Record; +type Dictionaries = Record; +``` + +## Usage + +### 1. Define your translation dictionaries + +Create a file with your translations for each supported language: +```ts +// i18n/locales.ts export const dictionaries = { en: { save: "Save", + cancel: "Cancel", + delete: "Delete", }, fr: { save: "Enregistrer", + cancel: "Annuler", + delete: "Supprimer", }, }; ``` -- Keys (`save`) must be consistent across languages. +**Important**: Translation keys must be consistent across all languages. ---- +### 2. Detect or specify locale -## Step 2: Detect or pass locale +Choose the user's locale either manually or through automatic detection: -You can either: +```ts +import { detectLocale } from "@serverlessworkflow/i18n"; +import { dictionaries } from "./i18n/locales"; -- Pass `locale` manually via props -- Or auto-detect using `detectLocale` +const supportedLocales = Object.keys(dictionaries) as const; -Example: +// Auto-detect with fallback to "en" +const locale = detectLocale(supportedLocales); -```ts -const supportedLocales = Object.keys(dictionaries); +// Or specify manually +const locale = "fr"; -const locale = props.locale ?? detectLocale(supportedLocales); +// Or combine both approaches +const locale = props.locale ?? detectLocale(supportedLocales, "en"); ``` ---- +**`detectLocale()` behavior**: + +- Uses `navigator.languages` and `navigator.language` to detect user preferences +- Normalizes locales to their base language code (e.g., `"en-US"` → `"en"`) +- Returns the `fallback` parameter (default: `"en"`) if no match found +- Returns `fallback` in non-browser environments (SSR-safe) -## Step 3: Wrap your app with `I18nProvider` +### 3. Wrap your app with `I18nProvider` ```tsx import { I18nProvider } from "@serverlessworkflow/i18n"; -import { dictionaries } from "../i18n/locales"; +import { dictionaries } from "./i18n/locales"; - - {/* your app */} -; -``` +function App() { + const locale = detectLocale(Object.keys(dictionaries)); ---- + return ( + + + + ); +} +``` -## Step 4: Use translations with `useI18n` +### 4. Use translations with `useI18n()` -Inside any child component: +Inside any component within the provider: ```tsx import { useI18n } from "@serverlessworkflow/i18n"; -const Content = () => { - const { t } = useI18n(); - - return

{t("save")}

; -}; +function MyComponent() { + const { t, locale } = useI18n(); + + return ( +
+

Current locale: {locale}

+ + +
+ ); +} ``` -- If the key is missing, it will return the key itself: +**Translation fallback**: If a key is missing, `t()` returns the key itself: ```ts -t("unknown") → "unknown" +t("unknown_key"); // Returns: "unknown_key" ``` ---- +**Error handling**: `useI18n()` must be used inside `I18nProvider` or it will throw an error. + +## Architecture + +``` +src/ +├── index.ts # Public exports +├── core/ +│ └── createI18n.ts # Core translation logic +├── react/ +│ └── I18nProvider.tsx # React Context provider and hook +└── utils/ + └── detectLocale.ts # Browser locale detection +``` + +## Development + +### Build + +```bash +# Development build +pnpm build:dev + +# Production build (includes tests) +pnpm build:prod +``` + +### Test + +```bash +pnpm test +``` + +Tests are located in the `tests/` directory and use Vitest. + +## TypeScript + +This package is written in TypeScript and includes type definitions. The build outputs: + +- `dist/index.js` - ESM JavaScript +- `dist/index.d.ts` - TypeScript declarations + +## License + +Apache-2.0 + +## Repository + +Part of the [Serverless Workflow Editor](https://github.com/serverlessworkflow/editor) monorepo. diff --git a/packages/serverless-workflow-diagram-editor/README.md b/packages/serverless-workflow-diagram-editor/README.md index 07f0a4c4..f379260d 100644 --- a/packages/serverless-workflow-diagram-editor/README.md +++ b/packages/serverless-workflow-diagram-editor/README.md @@ -14,47 +14,114 @@ limitations under the License. --> -# serverless-workflow-diagram-editor +# @serverlessworkflow/diagram-editor -Serverless Workflow Diagram Editor React component / npm package +Official visual diagram editor for the [Open Workflow Specification](https://github.com/serverlessworkflow/specification). A vendor-neutral, embeddable React component with strict separation between core logic and platform APIs. -## Building the Component +## Installation ```bash -# Go to serverless-workflow-diagram-editor package -cd ./packages/serverless-workflow-diagram-editor +npm install @serverlessworkflow/diagram-editor +# or +pnpm add @serverlessworkflow/diagram-editor +# or +yarn add @serverlessworkflow/diagram-editor +``` + +Import the component and styles: + +```tsx +import { DiagramEditor } from "@serverlessworkflow/diagram-editor"; +import "@serverlessworkflow/diagram-editor/styles.css"; +``` + +## Development + +```bash +# Navigate to the package +cd packages/serverless-workflow-diagram-editor -# Install dependencies +# Install dependencies (or run from repo root) pnpm install +# Start Storybook dev server on port 6006 +pnpm start + +# Run unit tests +pnpm test + +# Run E2E tests +pnpm test-e2e +pnpm test-e2e:ui # with Playwright UI + +# Type checking +pnpm typecheck + +# Linting +pnpm lint + # Build package (development) pnpm run build:dev -# Or build package (production) +# Build package (production - includes linting and tests) pnpm run build:prod -# Build storybook static content for publishing (documentation and demo) +# Build Storybook static site pnpm run build:storybook - -# Run storybook (test and development / debugging) -pnpm run start ``` -## shadcn/ui +## Architecture + +### Core Principles -This package uses [shadcn/ui](https://ui.shadcn.com/) for UI primitives. Configuration lives in `components.json` at the package root. +- **Vendor-neutral**: Platform-agnostic editor that can be embedded anywhere +- **SDK isolation**: Only [`src/core/workflowSdk.ts`](src/core/workflowSdk.ts) and [`src/core/graph.ts`](src/core/graph.ts) directly import from `@serverlessworkflow/sdk` +- **React Flow isolation**: All `@xyflow/react` specifics contained in [`src/react-flow/`](src/react-flow/) +- **TypeScript strict mode**: Enforced with `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` -### Key settings +### Directory Structure + +- **[`src/core/`](src/core/)** — SDK abstraction layer and graph types +- **[`src/diagram-editor/`](src/diagram-editor/)** — Main `DiagramEditor` component and error pages +- **[`src/react-flow/`](src/react-flow/)** — React Flow rendering (nodes, edges, diagram) +- **[`src/side-panel/`](src/side-panel/)** — Side panel with workflow info and node details +- **[`src/store/`](src/store/)** — React Context state management +- **[`src/components/ui/`](src/components/ui/)** — shadcn/ui components (customized) +- **[`src/hooks/`](src/hooks/)** — Custom React hooks +- **[`src/lib/`](src/lib/)** — Utility functions (clipboard, download, utils) +- **[`src/i18n/locales/`](src/i18n/locales/)** — Translation strings (en, fr) +- **[`src/types/`](src/types/)** — Shared TypeScript types + +### Test Structure + +Tests mirror the source structure: + +- **[`tests/core/`](tests/core/)** — SDK integration tests +- **[`tests/diagram-editor/`](tests/diagram-editor/)** — Component tests +- **[`tests/react-flow/`](tests/react-flow/)** — Rendering tests (nodes, edges, diagram) +- **[`tests/side-panel/`](tests/side-panel/)** — Side panel component tests +- **[`tests/components/ui/`](tests/components/ui/)** — UI component tests +- **[`tests/store/`](tests/store/)** — Context provider tests +- **[`tests/hooks/`](tests/hooks/)** — Custom hook tests +- **[`tests/lib/`](tests/lib/)** — Utility function tests +- **[`tests/fixtures/`](tests/fixtures/)** — Shared test fixtures (workflow YAML/JSON) +- **[`tests-e2e/`](tests-e2e/)** — Playwright end-to-end tests + +## UI Components (shadcn/ui) + +This package uses [shadcn/ui](https://ui.shadcn.com/) for UI primitives. Configuration: [`components.json`](components.json) + +### Key Settings - **Style**: `new-york` — compact spacing and sharper corners -- **Tailwind prefix**: `dec:` — all generated classes are prefixed to avoid conflicts with host applications -- **CSS target**: `src/components/ui/shadcn.css` — where shadcn injects its CSS variables -- **Path aliases**: `@/components`, `@/lib`, `@/hooks` — resolved via `tsconfig.json` paths and Vite's `tsconfigPaths` -- **Icon library**: `lucide` (generates `lucide-react` imports) +- **Tailwind prefix**: `dec:` — all generated classes prefixed to avoid conflicts +- **CSS target**: [`src/components/ui/shadcn.css`](src/components/ui/shadcn.css) — CSS variables +- **Path aliases**: `@/components`, `@/lib`, `@/hooks` — resolved via tsconfig +- **Icon library**: `lucide-react` -### Adding a new shadcn component +### Adding a shadcn Component -The shadcn CLI doesn't understand pnpm catalogs, so adding a component requires a manual step. +The shadcn CLI doesn't understand pnpm catalogs, so adding a component requires manual steps: 1. **Generate the component** @@ -63,47 +130,21 @@ The shadcn CLI doesn't understand pnpm catalogs, so adding a component requires pnpm dlx shadcn@latest add ``` - This creates the component in `src/components/ui/` and adds any new dependencies (e.g. `@radix-ui/*`) to `package.json` with a pinned version. +2. **Move dependency to pnpm catalog** -2. **Move the dependency to the pnpm catalog** - - The CLI writes something like `"@radix-ui/react-tooltip": "^1.2.3"` directly into `package.json`. To follow the workspace convention: - - Add the package and version to the `catalog:` section in the **root** `pnpm-workspace.yaml` - - Replace the pinned version in the editor's `package.json` with `"catalog:"` + The CLI adds pinned versions (e.g., `"@radix-ui/react-tooltip": "^1.2.3"`). Move them to the catalog: + - Add package and version to `catalog:` in root `pnpm-workspace.yaml` + - Replace the version in `package.json` with `"catalog:"` 3. **Verify consistency** ```bash - # From the repo root - pnpm dependencies:check + pnpm dependencies:check # from repo root + pnpm dependencies:fix # if needed ``` - This runs syncpack to confirm all workspace packages use the catalog. If you missed a dependency, run `pnpm dependencies:fix`. - 4. **Install** ```bash pnpm install ``` - -## Package Structure - -``` -serverless-workflow-diagram-editor/ -├── src/ -│ ├── core/ # SDK abstraction layer -│ ├── diagram-editor/ # Main DiagramEditor component -│ ├── i18n/locales/ # Locale string definitions (en, fr) -│ ├── react-flow/diagram/ # @xyflow/react diagram rendering -│ └── store/ # React Context state management -├── tests/ -│ ├── core/ # SDK integration tests -│ ├── diagram-editor/ # DiagramEditor component tests -│ ├── react-flow/diagram/ # Diagram rendering tests -│ ├── store/ # Context provider tests -│ └── fixtures/ # Shared test fixtures (workflow YAML/JSON) -├── stories/ # Storybook stories and demo components -├── vitest.config.ts # Unit test config -├── tsconfig.json # TypeScript config -└── tsconfig.test.json # TypeScript config for tests -``` diff --git a/packages/serverless-workflow-diagram-editor/src/core/README.md b/packages/serverless-workflow-diagram-editor/src/core/README.md index 92e998b4..d1a07b06 100644 --- a/packages/serverless-workflow-diagram-editor/src/core/README.md +++ b/packages/serverless-workflow-diagram-editor/src/core/README.md @@ -18,14 +18,36 @@ Core package agnostic from the rendering library and its types. -## Modules +## SDK Isolation + +**Critical constraint**: `workflowSdk.ts`, `graph.ts`, `taskSubType.ts`, `taskDetails.ts`, and `mermaidExport.ts` are the only modules that import from `@serverlessworkflow/sdk` directly, keeping the rest of the editor decoupled from SDK implementation details. -`workflowSdk.ts` and `graph.ts` are the only places in the diagram editor that import from the SDK directly, keeping the rest of the editor decoupled from SDK implementation details. +## Modules ### workflowSdk.ts -Abstraction layer over the `@serverlessworkflow/sdk`. +Abstraction layer over the `@serverlessworkflow/sdk`. Provides functions to parse, validate, and work with workflow definitions without exposing SDK internals to the rest of the editor. ### graph.ts -Add custom types to the original sdk `Graph` type. +Utility functions for working with the SDK's `FlatGraph` type. Provides `getNodesByType()` to filter nodes by type and `fixNodesConnections()` to normalize graph edges by redirecting entry/exit node connections to their parent nodes. + +### taskSubType.ts + +Utilities for extracting task subtypes from task definitions. Provides functions like `getRunSubType()`, `getListenSubType()`, and `getCallSubType()` to determine the specific variant of each task type. + +### taskDetails.ts + +Flattens task properties into display-ready detail fields. Converts nested task objects into a flat array of `DetailField` objects (text, array, or object) for rendering in the UI, separating task-specific fields from inherited base fields. + +### elkjs.ts + +Wrapper for the ELK (Eclipse Layout Kernel) graph layout library. Provides `processElkLayout()` function with abort signal support for cancelable layout calculations. + +### mermaidExport.ts + +Converts workflow models to Mermaid diagram code. Thin wrapper over the SDK's `convertToMermaidCode()` function for exporting workflows to Mermaid format. + +### validationErrors.ts + +Filters and categorizes validation errors from the SDK. Separates node-specific errors from workflow-level errors, removes noise (redundant errors for invalid tasks), and provides utilities to map errors to their owning nodes. diff --git a/packages/serverless-workflow-diagram-editor/src/react-flow/README.md b/packages/serverless-workflow-diagram-editor/src/react-flow/README.md index 667f634e..b9f3bff3 100644 --- a/packages/serverless-workflow-diagram-editor/src/react-flow/README.md +++ b/packages/serverless-workflow-diagram-editor/src/react-flow/README.md @@ -1,12 +1,12 @@ # react-flow -All react flow library specifics must be contained within this package. + +This directory contains all React Flow (`@xyflow/react`) library-specific code. **All React Flow specifics must be contained within this directory** to maintain library isolation and ensure the editor remains embeddable across different platforms. + +## Architecture Constraint + +React Flow is the rendering library used to visualize Serverless Workflow diagrams. By isolating all React Flow dependencies to this directory, we ensure: + +- The core workflow logic remains independent of the rendering implementation +- The editor can be adapted to different rendering libraries if needed +- Platform-specific integrations (VS Code, browser extensions) don't become coupled to React Flow + +## Files and Their Purpose + +### `diagram/` + +#### [`autoLayout.ts`](diagram/autoLayout.ts) + +Automatic graph layout using the ELK (Eclipse Layout Kernel) algorithm. Handles: + +- Node sizing (default task nodes: 220×65, terminal nodes: 95×30) +- Converting React Flow graphs to ELK format +- Processing ELK layout results back to React Flow positions +- Edge waypoint calculation for orthogonal routing + +#### [`diagramBuilder.ts`](diagram/diagramBuilder.ts) + +Converts the SDK's graph representation into React Flow-compatible nodes and edges: + +- Transforms `sdk.Graph` to `ReactFlowGraph` (nodes + edges) +- Determines edge types based on source node (error edges, condition edges, default edges) +- Handles catch container nodes (special React Flow type for catch nodes with children) +- Filters out edges where source or target nodes don't exist +- Manages node data (labels, errors, task references) + +#### [`Diagram.tsx`](diagram/Diagram.tsx) + +The main diagram component that orchestrates the React Flow canvas: + +- Renders the `ReactFlowProvider` and `ReactFlow` components +- Manages diagram state (nodes, edges, selection) +- Handles auto-layout triggering +- Configures viewport (fit view, zoom limits, pan/zoom controls) +- Applies z-index management for edge selection highlighting +- Integrates with the diagram editor context +- Registers custom node and edge types + +#### [`Diagram.css`](diagram/Diagram.css) + +Styles for the diagram component and React Flow overrides. + +### `edges/` + +#### [`Edges.tsx`](edges/Edges.tsx) + +Custom edge implementations for different workflow transition types: + +- **`DefaultEdge`**: Standard workflow transitions +- **`ErrorEdge`**: Error/exception flow (dashed red line with error icon) +- **`ConditionEdge`**: Conditional branches from switch tasks (dashed blue line with branch icon) +- **Edge label positioning**: Handles waypoint-based paths and calculates label midpoints +- **Custom path rendering**: Creates orthogonal paths from ELK waypoints +- **Z-index management**: Ensures selected edge labels appear above regular ones + +### `nodes/` + +#### [`Nodes.tsx`](nodes/Nodes.tsx) + +Defines all custom node components for Serverless Workflow task types: + +- **Terminal nodes**: `StartNode`, `EndNode`, `EntryNode`, `ExitNode` (compact pill shapes) +- **Leaf task nodes**: `CallNode`, `CatchNode`, `EmitNode`, `ListenNode`, `RaiseNode`, `RunNode`, `SetNode`, `SwitchNode`, `WaitNode` +- **Container task nodes**: `DoNode`, `ForNode`, `ForkNode`, `TryCatchNode`, `TryNode`, `CatchContainerNode` + +Features: + +- Icon and color coding per task type (from `taskNodeConfig.ts`) +- Badge rendering for task subtypes (http, grpc, asyncapi, openapi, container, script, workflow, etc.) +- Error indication (red border with alert icon) +- Task labels with i18n support +- Handle positioning for edge connections +- Click handlers for side panel integration + +Exports: + +- `ReactFlowNodeTypes`: Mapping of `GraphNodeType` to React components +- `BaseNodeData`: Type definition for node data (label, task, hasError) + +#### [`taskNodeConfig.ts`](taskNodeConfig.ts) + +Visual configuration for all task node types: + +- **Colors**: Hex color codes for each task type (e.g., Call: blue, Catch: orange, Raise: red) +- **Icons**: Lucide React icons for each task type +- **Type labels**: Display labels (e.g., "CALL", "EMIT", "FOR") +- **Type guards**: `isLeafNodeType()`, `isContainerNodeType()`, `isTerminalNodeType()` +- **Custom types**: + - `CATCH_CONTAINER_NODE_TYPE`: Special React Flow type for catch nodes with children + - `TerminalNodeType`, `ContainerNodeType`, `LeafNodeType`: Union types for node categorization + +### Root Level + +#### [`zIndexConstants.ts`](zIndexConstants.ts) + +Centralized z-index layering constants for diagram rendering. + +Ensures proper visual stacking: + +- Selected edges appear above regular edges +- All labels appear above all edges (preventing overlap) +- Selected edge labels appear above regular labels + +## Integration Points + +This directory integrates with: + +- **`src/core/`**: Imports SDK graph types and workflow abstractions (via `workflowSdk.ts` and `graph.ts`) +- **`src/store/`**: Uses `DiagramEditorContext` for state management +- **`src/i18n/`**: Uses `useI18n` hook for internationalized labels +- **`src/side-panel/`**: Integrates `SidePanelTrigger` for node selection panels + +## Key Concepts + +### Node Types + +- **Terminal nodes**: Entry/exit points (start, end, entry, exit) - compact visual style +- **Leaf nodes**: Task nodes without children (call, emit, listen, raise, run, set, switch, wait, catch) +- **Container nodes**: Task nodes that contain child nodes (do, for, fork, try, try-catch, catch-container) + +### Edge Types + +- **Default**: Standard workflow transitions (solid line) +- **Error**: Exception/error flow from raise tasks (dashed red line with AlertTriangle icon) +- **Condition**: Conditional branches from switch tasks (dashed blue line with GitBranch icon) + +### Auto-Layout + +The ELK algorithm provides automatic orthogonal layout with: + +- Top-to-bottom flow direction +- Hierarchical layering +- Waypoint-based edge routing (90-degree bends) +- Container node support (parent-child relationships) From 75cfa60ce8e92724f74b34808be48cb02aa290ff Mon Sep 17 00:00:00 2001 From: handreyrc Date: Tue, 30 Jun 2026 22:29:02 -0400 Subject: [PATCH 2/8] Fix copilot complaints Signed-off-by: handreyrc --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- README.md | 4 ++-- packages/serverless-workflow-diagram-editor/README.md | 4 ++-- .../serverless-workflow-diagram-editor/src/core/README.md | 4 ---- .../src/react-flow/README.md | 1 + 5 files changed, 6 insertions(+), 9 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 8cdb0f35..ce562cc3 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -48,4 +48,4 @@ body: id: context attributes: label: Additional Context - description: Add any other context, screenshots, or .sw.json / .sw.yaml snippets here. \ No newline at end of file + description: Add any other context, screenshots, or .json / .yaml snippets here. diff --git a/README.md b/README.md index 338c044f..ae7f5f18 100644 --- a/README.md +++ b/README.md @@ -164,8 +164,8 @@ Internationalization utilities used by the diagram editor. The diagram editor maintains strict separation of concerns: -- **SDK Isolation**: Only `src/core/workflowSdk.ts` and `src/core/graph.ts` import from `@serverlessworkflow/sdk` -- **React Flow Isolation**: All `@xyflow/react` code is contained in `src/react-flow/` +- **SDK Isolation**: SDK integration helpers live under `src/core/` (e.g., `workflowSdk.ts`, `graph.ts`, `taskSubType.ts`, `taskDetails.ts`, `mermaidExport.ts`); other layers may also import SDK types/enums (e.g., `Specification`, `GraphNodeType`) when needed. +- **React Flow Isolation**: React Flow rendering components live in `src/react-flow/` (nodes/edges/diagram); other layers may import `@xyflow/react` types and/or `ReactFlowProvider`. - **Platform Agnostic**: Core logic decoupled from platform-specific APIs - **Embeddable**: Designed for integration into VS Code, web apps, and browser extensions diff --git a/packages/serverless-workflow-diagram-editor/README.md b/packages/serverless-workflow-diagram-editor/README.md index f379260d..215d9995 100644 --- a/packages/serverless-workflow-diagram-editor/README.md +++ b/packages/serverless-workflow-diagram-editor/README.md @@ -75,8 +75,8 @@ pnpm run build:storybook ### Core Principles - **Vendor-neutral**: Platform-agnostic editor that can be embedded anywhere -- **SDK isolation**: Only [`src/core/workflowSdk.ts`](src/core/workflowSdk.ts) and [`src/core/graph.ts`](src/core/graph.ts) directly import from `@serverlessworkflow/sdk` -- **React Flow isolation**: All `@xyflow/react` specifics contained in [`src/react-flow/`](src/react-flow/) +- **SDK isolation**: SDK integration helpers live under [`src/core/`](src/core/) (e.g., `workflowSdk.ts`, `graph.ts`, `taskSubType.ts`, `taskDetails.ts`, `mermaidExport.ts`); other layers may also import SDK types/enums (e.g., `Specification`, `GraphNodeType`) when needed. +- **React Flow isolation**: React Flow rendering components live in [`src/react-flow/`](src/react-flow/) (nodes/edges/diagram); other layers may import `@xyflow/react` types and/or `ReactFlowProvider`. - **TypeScript strict mode**: Enforced with `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` ### Directory Structure diff --git a/packages/serverless-workflow-diagram-editor/src/core/README.md b/packages/serverless-workflow-diagram-editor/src/core/README.md index d1a07b06..31012c72 100644 --- a/packages/serverless-workflow-diagram-editor/src/core/README.md +++ b/packages/serverless-workflow-diagram-editor/src/core/README.md @@ -18,10 +18,6 @@ Core package agnostic from the rendering library and its types. -## SDK Isolation - -**Critical constraint**: `workflowSdk.ts`, `graph.ts`, `taskSubType.ts`, `taskDetails.ts`, and `mermaidExport.ts` are the only modules that import from `@serverlessworkflow/sdk` directly, keeping the rest of the editor decoupled from SDK implementation details. - ## Modules ### workflowSdk.ts diff --git a/packages/serverless-workflow-diagram-editor/src/react-flow/README.md b/packages/serverless-workflow-diagram-editor/src/react-flow/README.md index b9f3bff3..0b108d0a 100644 --- a/packages/serverless-workflow-diagram-editor/src/react-flow/README.md +++ b/packages/serverless-workflow-diagram-editor/src/react-flow/README.md @@ -17,6 +17,7 @@ # react-flow This directory contains all React Flow (`@xyflow/react`) library-specific code. **All React Flow specifics must be contained within this directory** to maintain library isolation and ensure the editor remains embeddable across different platforms. +Note: The only exception is the `ReactFlowProvider`, needed in a top-level component to allow access to React Flow internal state. ## Architecture Constraint From 4dede19876b578a394ecd5152b082a9efb24b252 Mon Sep 17 00:00:00 2001 From: handreyrc Date: Fri, 3 Jul 2026 17:15:54 -0400 Subject: [PATCH 3/8] fix review comments Signed-off-by: handreyrc --- CONTRIBUTING.md | 9 -- .../README.md | 2 +- .../src/core/README.md | 53 ++++--- .../src/react-flow/README.md | 130 ++---------------- 4 files changed, 52 insertions(+), 142 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bcf465c8..c94dacab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -116,15 +116,6 @@ If you're unsure whether your use of agents/LLMs is acceptable — ask! We're ha > This isn't about banning AI — it's about keeping this project collaborative, human-driven, and focused on quality. -## Git Hooks - -The project uses [Husky](https://typicode.github.io/husky/) to manage Git hooks automatically after `pnpm install`: - -- **`pre-commit`**: Runs `lint-staged` to automatically format staged files matching `*.{ts,tsx,js,jsx,json,md,yml,yaml}` using oxfmt. -- **`commit-msg`**: Validates that commits include a DCO `Signed-off-by` line. Commits without sign-off will be rejected. - -These hooks help maintain code quality and ensure compliance with project requirements. - ## Testing The project uses multiple testing strategies: diff --git a/packages/serverless-workflow-diagram-editor/README.md b/packages/serverless-workflow-diagram-editor/README.md index 215d9995..a6b5c553 100644 --- a/packages/serverless-workflow-diagram-editor/README.md +++ b/packages/serverless-workflow-diagram-editor/README.md @@ -114,7 +114,7 @@ This package uses [shadcn/ui](https://ui.shadcn.com/) for UI primitives. Configu ### Key Settings - **Style**: `new-york` — compact spacing and sharper corners -- **Tailwind prefix**: `dec:` — all generated classes prefixed to avoid conflicts +- **Tailwind prefix**: `dec:` — all generated classes prefixed to avoid conflicts with host applications - **CSS target**: [`src/components/ui/shadcn.css`](src/components/ui/shadcn.css) — CSS variables - **Path aliases**: `@/components`, `@/lib`, `@/hooks` — resolved via tsconfig - **Icon library**: `lucide-react` diff --git a/packages/serverless-workflow-diagram-editor/src/core/README.md b/packages/serverless-workflow-diagram-editor/src/core/README.md index 31012c72..6c0c0d24 100644 --- a/packages/serverless-workflow-diagram-editor/src/core/README.md +++ b/packages/serverless-workflow-diagram-editor/src/core/README.md @@ -16,34 +16,55 @@ # core -Core package agnostic from the rendering library and its types. +Core business logic layer that is agnostic to rendering libraries and platform-specific APIs. This layer provides the foundation for the diagram editor while maintaining vendor neutrality and embeddability. -## Modules +## Purpose -### workflowSdk.ts +The core layer serves as the abstraction boundary between the Serverless Workflow SDK and the editor's UI layer. It handles workflow parsing, validation, graph manipulation, and data transformation without any dependencies on React Flow or other rendering frameworks. -Abstraction layer over the `@serverlessworkflow/sdk`. Provides functions to parse, validate, and work with workflow definitions without exposing SDK internals to the rest of the editor. +## Functional Areas -### graph.ts +### SDK Abstraction -Utility functions for working with the SDK's `FlatGraph` type. Provides `getNodesByType()` to filter nodes by type and `fixNodesConnections()` to normalize graph edges by redirecting entry/exit node connections to their parent nodes. +**Critical constraint**: This is the only layer allowed to directly import from `@serverlessworkflow/sdk`. All SDK interactions must go through this abstraction to keep the rest of the editor decoupled from SDK implementation details. -### taskSubType.ts +Responsibilities: -Utilities for extracting task subtypes from task definitions. Provides functions like `getRunSubType()`, `getListenSubType()`, and `getCallSubType()` to determine the specific variant of each task type. +- Parse and validate workflow definitions (YAML/JSON) +- Provide type-safe access to workflow models +- Convert workflow definitions to graph representations +- Shield the rest of the editor from SDK internals and breaking changes -### taskDetails.ts +### Graph Processing -Flattens task properties into display-ready detail fields. Converts nested task objects into a flat array of `DetailField` objects (text, array, or object) for rendering in the UI, separating task-specific fields from inherited base fields. +Utilities for working with workflow graphs as data structures: -### elkjs.ts +- Normalize graph connections and edges +- Fix entry/exit node connections by redirecting them to parent containers +- Provide graph traversal and manipulation operations -Wrapper for the ELK (Eclipse Layout Kernel) graph layout library. Provides `processElkLayout()` function with abort signal support for cancelable layout calculations. +### Layout Computation -### mermaidExport.ts +Integration with graph layout algorithms: -Converts workflow models to Mermaid diagram code. Thin wrapper over the SDK's `convertToMermaidCode()` function for exporting workflows to Mermaid format. +- Wrap layout engines with editor-specific interfaces +- Provide cancelable layout calculations with abort signal support +- Transform layout results into consumable formats +- Handle layout engine lifecycle and error cases -### validationErrors.ts +### Export Capabilities -Filters and categorizes validation errors from the SDK. Separates node-specific errors from workflow-level errors, removes noise (redundant errors for invalid tasks), and provides utilities to map errors to their owning nodes. +Convert workflow models to other formats: + +- Generate diagram code in external formats (e.g., Mermaid) +- Provide thin wrappers over SDK export functions +- Enable integration with external diagramming tools + +### Validation & Error Handling + +Process and categorize validation errors: + +- Filter SDK validation errors for relevance +- Map errors to specific nodes in the graph +- Separate node-level errors from workflow-level errors +- Provide structured error data for UI consumption diff --git a/packages/serverless-workflow-diagram-editor/src/react-flow/README.md b/packages/serverless-workflow-diagram-editor/src/react-flow/README.md index 0b108d0a..dd24c821 100644 --- a/packages/serverless-workflow-diagram-editor/src/react-flow/README.md +++ b/packages/serverless-workflow-diagram-editor/src/react-flow/README.md @@ -27,134 +27,32 @@ React Flow is the rendering library used to visualize Serverless Workflow diagra - The editor can be adapted to different rendering libraries if needed - Platform-specific integrations (VS Code, browser extensions) don't become coupled to React Flow -## Files and Their Purpose +## Directory Structure ### `diagram/` -#### [`autoLayout.ts`](diagram/autoLayout.ts) +Contains the core diagram rendering and layout logic: -Automatic graph layout using the ELK (Eclipse Layout Kernel) algorithm. Handles: - -- Node sizing (default task nodes: 220×65, terminal nodes: 95×30) -- Converting React Flow graphs to ELK format -- Processing ELK layout results back to React Flow positions -- Edge waypoint calculation for orthogonal routing - -#### [`diagramBuilder.ts`](diagram/diagramBuilder.ts) - -Converts the SDK's graph representation into React Flow-compatible nodes and edges: - -- Transforms `sdk.Graph` to `ReactFlowGraph` (nodes + edges) -- Determines edge types based on source node (error edges, condition edges, default edges) -- Handles catch container nodes (special React Flow type for catch nodes with children) -- Filters out edges where source or target nodes don't exist -- Manages node data (labels, errors, task references) - -#### [`Diagram.tsx`](diagram/Diagram.tsx) - -The main diagram component that orchestrates the React Flow canvas: - -- Renders the `ReactFlowProvider` and `ReactFlow` components -- Manages diagram state (nodes, edges, selection) -- Handles auto-layout triggering -- Configures viewport (fit view, zoom limits, pan/zoom controls) -- Applies z-index management for edge selection highlighting -- Integrates with the diagram editor context -- Registers custom node and edge types - -#### [`Diagram.css`](diagram/Diagram.css) - -Styles for the diagram component and React Flow overrides. +- **Automatic Layout**: Implements graph layout using the ELK (Eclipse Layout Kernel) algorithm with orthogonal routing, handling node sizing, waypoint calculation, and conversion between React Flow and ELK formats +- **Diagram Builder**: Transforms the SDK's graph representation into React Flow-compatible structures, determining edge types based on workflow semantics (error flows, conditional branches, standard transitions) and managing node hierarchies +- **Main Component**: Orchestrates the React Flow canvas, managing diagram state, viewport controls, auto-layout triggering, and integration with the editor's context system ### `edges/` -#### [`Edges.tsx`](edges/Edges.tsx) - -Custom edge implementations for different workflow transition types: - -- **`DefaultEdge`**: Standard workflow transitions -- **`ErrorEdge`**: Error/exception flow (dashed red line with error icon) -- **`ConditionEdge`**: Conditional branches from switch tasks (dashed blue line with branch icon) -- **Edge label positioning**: Handles waypoint-based paths and calculates label midpoints -- **Custom path rendering**: Creates orthogonal paths from ELK waypoints -- **Z-index management**: Ensures selected edge labels appear above regular ones +Custom edge implementations representing different workflow transition types, edge path rendering from ELK waypoints, label positioning along paths, and z-index layering for proper visual stacking ### `nodes/` -#### [`Nodes.tsx`](nodes/Nodes.tsx) - -Defines all custom node components for Serverless Workflow task types: - -- **Terminal nodes**: `StartNode`, `EndNode`, `EntryNode`, `ExitNode` (compact pill shapes) -- **Leaf task nodes**: `CallNode`, `CatchNode`, `EmitNode`, `ListenNode`, `RaiseNode`, `RunNode`, `SetNode`, `SwitchNode`, `WaitNode` -- **Container task nodes**: `DoNode`, `ForNode`, `ForkNode`, `TryCatchNode`, `TryNode`, `CatchContainerNode` - -Features: - -- Icon and color coding per task type (from `taskNodeConfig.ts`) -- Badge rendering for task subtypes (http, grpc, asyncapi, openapi, container, script, workflow, etc.) -- Error indication (red border with alert icon) -- Task labels with i18n support -- Handle positioning for edge connections -- Click handlers for side panel integration - -Exports: +Node component implementations for all Serverless Workflow task types. -- `ReactFlowNodeTypes`: Mapping of `GraphNodeType` to React components -- `BaseNodeData`: Type definition for node data (label, task, hasError) - -#### [`taskNodeConfig.ts`](taskNodeConfig.ts) - -Visual configuration for all task node types: - -- **Colors**: Hex color codes for each task type (e.g., Call: blue, Catch: orange, Raise: red) -- **Icons**: Lucide React icons for each task type -- **Type labels**: Display labels (e.g., "CALL", "EMIT", "FOR") -- **Type guards**: `isLeafNodeType()`, `isContainerNodeType()`, `isTerminalNodeType()` -- **Custom types**: - - `CATCH_CONTAINER_NODE_TYPE`: Special React Flow type for catch nodes with children - - `TerminalNodeType`, `ContainerNodeType`, `LeafNodeType`: Union types for node categorization +- **Terminal Nodes**: Compact visual representations for workflow entry/exit points (start, end, entry, exit) +- **Leaf Task Nodes**: Task nodes without children +- **Container Task Nodes**: Task nodes that can contain child nodes +- **Visual Configuration**: Color coding, iconography, type labels, and visual categorization for all task types +- **Interactive Features**: Error indication, task labels with internationalization, connection handles, and side panel integration ### Root Level -#### [`zIndexConstants.ts`](zIndexConstants.ts) - -Centralized z-index layering constants for diagram rendering. - -Ensures proper visual stacking: - -- Selected edges appear above regular edges -- All labels appear above all edges (preventing overlap) -- Selected edge labels appear above regular labels - -## Integration Points - -This directory integrates with: - -- **`src/core/`**: Imports SDK graph types and workflow abstractions (via `workflowSdk.ts` and `graph.ts`) -- **`src/store/`**: Uses `DiagramEditorContext` for state management -- **`src/i18n/`**: Uses `useI18n` hook for internationalized labels -- **`src/side-panel/`**: Integrates `SidePanelTrigger` for node selection panels - -## Key Concepts - -### Node Types - -- **Terminal nodes**: Entry/exit points (start, end, entry, exit) - compact visual style -- **Leaf nodes**: Task nodes without children (call, emit, listen, raise, run, set, switch, wait, catch) -- **Container nodes**: Task nodes that contain child nodes (do, for, fork, try, try-catch, catch-container) - -### Edge Types - -- **Default**: Standard workflow transitions (solid line) -- **Error**: Exception/error flow from raise tasks (dashed red line with AlertTriangle icon) -- **Condition**: Conditional branches from switch tasks (dashed blue line with GitBranch icon) - -### Auto-Layout - -The ELK algorithm provides automatic orthogonal layout with: +Contains shared constants and utilities: -- Top-to-bottom flow direction -- Hierarchical layering -- Waypoint-based edge routing (90-degree bends) -- Container node support (parent-child relationships) +- **Z-Index Constants**: Centralized layering configuration ensuring proper visual stacking order (selected edges above regular edges, labels above edges, selected labels above regular labels) From 730d216968b05979ddecfcac5ba1700be59a8aa0 Mon Sep 17 00:00:00 2001 From: handreyrc Date: Fri, 3 Jul 2026 17:28:22 -0400 Subject: [PATCH 4/8] fix copilot complaints Signed-off-by: handreyrc --- .../serverless-workflow-diagram-editor/src/core/README.md | 2 +- .../src/react-flow/README.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/serverless-workflow-diagram-editor/src/core/README.md b/packages/serverless-workflow-diagram-editor/src/core/README.md index 6c0c0d24..cf40b4e2 100644 --- a/packages/serverless-workflow-diagram-editor/src/core/README.md +++ b/packages/serverless-workflow-diagram-editor/src/core/README.md @@ -26,7 +26,7 @@ The core layer serves as the abstraction boundary between the Serverless Workflo ### SDK Abstraction -**Critical constraint**: This is the only layer allowed to directly import from `@serverlessworkflow/sdk`. All SDK interactions must go through this abstraction to keep the rest of the editor decoupled from SDK implementation details. +**Critical constraint**: This is the only layer allowed to directly import from `@serverlessworkflow/sdk`. All SDK interactions must go through this abstraction to keep the rest of the editor decoupled from SDK implementation details. Despite of that, type-only imports may still be used elsewhere when needed. Responsibilities: diff --git a/packages/serverless-workflow-diagram-editor/src/react-flow/README.md b/packages/serverless-workflow-diagram-editor/src/react-flow/README.md index dd24c821..c6794c20 100644 --- a/packages/serverless-workflow-diagram-editor/src/react-flow/README.md +++ b/packages/serverless-workflow-diagram-editor/src/react-flow/README.md @@ -16,8 +16,8 @@ # react-flow -This directory contains all React Flow (`@xyflow/react`) library-specific code. **All React Flow specifics must be contained within this directory** to maintain library isolation and ensure the editor remains embeddable across different platforms. -Note: The only exception is the `ReactFlowProvider`, needed in a top-level component to allow access to React Flow internal state. +This directory contains the React Flow (`@xyflow/react`) rendering implementation (nodes/edges/diagram). Keep React Flow runtime logic here to maintain library isolation and ensure the editor remains embeddable across different platforms. +Note: Some top-level components may import `ReactFlowProvider`, and other layers may import `@xyflow/react` types when needed. ## Architecture Constraint From 26ca2ce554b9a962e8a8db5323fe13056c1e5769 Mon Sep 17 00:00:00 2001 From: handreyrc Date: Mon, 6 Jul 2026 10:49:09 -0400 Subject: [PATCH 5/8] fix review comments Signed-off-by: handreyrc --- README.md | 3 ++ .../stories/README.md | 2 +- .../stories/introduction/Welcome.mdx | 35 ++++++++++++++++--- 3 files changed, 35 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ae7f5f18..5e42940e 100644 --- a/README.md +++ b/README.md @@ -207,6 +207,9 @@ This project uses [Changesets](https://github.com/changesets/changesets) for ver pnpm changeset # Or compare against upstream explicitly +# add upstream remote, if you don't have it already +git remote add upstream https://github.com/serverlessworkflow/editor.git + pnpm changeset --since upstream/main ``` diff --git a/packages/serverless-workflow-diagram-editor/stories/README.md b/packages/serverless-workflow-diagram-editor/stories/README.md index 68f44e6a..85e720b3 100644 --- a/packages/serverless-workflow-diagram-editor/stories/README.md +++ b/packages/serverless-workflow-diagram-editor/stories/README.md @@ -22,7 +22,7 @@ This directory contains Storybook stories and documentation. - **`introduction/`** - Introductory documentation and welcome pages - **`features/`** - Component features and interactive stories -- **`examples/`** - Serverless workflow specification examples +- **`examples/`** - Open workflow specification examples - **`use-cases/`** - Real-world use case examples - **`assets/`** - Images and media files used in stories diff --git a/packages/serverless-workflow-diagram-editor/stories/introduction/Welcome.mdx b/packages/serverless-workflow-diagram-editor/stories/introduction/Welcome.mdx index 47295403..4dfdc5f8 100644 --- a/packages/serverless-workflow-diagram-editor/stories/introduction/Welcome.mdx +++ b/packages/serverless-workflow-diagram-editor/stories/introduction/Welcome.mdx @@ -20,14 +20,41 @@ import { Meta } from "@storybook/addon-docs/blocks"; # Welcome to the Serverless Workflow Diagram Editor -**TODO** +The **Serverless Workflow Diagram Editor** is the official visual editor for the [CNCF Open Workflow Specification](https://serverlessworkflow.io). +It provides an intuitive, interactive way to design, visualize, and understand serverless workflow definitions. -Content goes here - intro to the editor, relevant links to CNCF, TypeScript SDK, and related resources. +## What is this editor? -Use this page to explain what the editor does, how to get started, and where to find more information. +This is a vendor-neutral, embeddable React component that allows you to: + +- **Visualize** workflow definitions in an interactive diagram format +- **Navigate** complex workflow structures with ease +- **Understand** workflow logic through visual representation +- **Integrate** the editor into your own applications and platforms + +The editor is built with flexibility in mind, designed to work seamlessly in different environments including web applications, VS Code extensions, and browser-based tools. + +## Getting Started + +Explore the **Examples** section in the sidebar to see the editor in action with various workflow patterns. Each example demonstrates different capabilities of the Open Workflow Specification, from simple sequential flows to complex parallel execution and event-driven patterns. + +## Key Features + +- **React Flow powered**: Built on top of React Flow for smooth, performant diagram interactions +- **TypeScript SDK integration**: Leverages the official TypeScript SDK for accurate workflow parsing +- **Internationalization**: Supports multiple languages (English, French) +- **Embeddable**: Strict separation between core logic and platform APIs makes it easy to integrate +- **Accessible**: Built with accessibility standards in mind ## Relevant Resources - [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io) -- [Serverless Workflow Specification](https://github.com/serverlessworkflow/specification) +- [CNCF Open Workflow Specification](https://serverlessworkflow.io) - [Serverless Workflow TypeScript SDK](https://github.com/serverlessworkflow/sdk-typescript) +- [GitHub Repository](https://github.com/serverlessworkflow/editor) + +## Contributing + +This is an open-source CNCF project. Contributions are welcome! All commits must be signed off with the Developer Certificate of Origin (DCO). + +For more information, visit the [GitHub repository](https://github.com/serverlessworkflow/editor). From e886a02a4f5d56ad4efbd578453f553c357b3550 Mon Sep 17 00:00:00 2001 From: handreyrc Date: Mon, 6 Jul 2026 11:04:03 -0400 Subject: [PATCH 6/8] fix copilot complaints Signed-off-by: handreyrc --- packages/serverless-workflow-diagram-editor/stories/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/serverless-workflow-diagram-editor/stories/README.md b/packages/serverless-workflow-diagram-editor/stories/README.md index 85e720b3..15200109 100644 --- a/packages/serverless-workflow-diagram-editor/stories/README.md +++ b/packages/serverless-workflow-diagram-editor/stories/README.md @@ -22,7 +22,7 @@ This directory contains Storybook stories and documentation. - **`introduction/`** - Introductory documentation and welcome pages - **`features/`** - Component features and interactive stories -- **`examples/`** - Open workflow specification examples +- **`examples/`** - Open Workflow Specification examples - **`use-cases/`** - Real-world use case examples - **`assets/`** - Images and media files used in stories From d67169121a2ded0b3ce52785e3a207c492a76541 Mon Sep 17 00:00:00 2001 From: handreyrc Date: Mon, 6 Jul 2026 11:16:36 -0400 Subject: [PATCH 7/8] fix review complaints Signed-off-by: handreyrc --- .../stories/introduction/Welcome.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/serverless-workflow-diagram-editor/stories/introduction/Welcome.mdx b/packages/serverless-workflow-diagram-editor/stories/introduction/Welcome.mdx index 4dfdc5f8..aa10fb1c 100644 --- a/packages/serverless-workflow-diagram-editor/stories/introduction/Welcome.mdx +++ b/packages/serverless-workflow-diagram-editor/stories/introduction/Welcome.mdx @@ -20,7 +20,7 @@ import { Meta } from "@storybook/addon-docs/blocks"; # Welcome to the Serverless Workflow Diagram Editor -The **Serverless Workflow Diagram Editor** is the official visual editor for the [CNCF Open Workflow Specification](https://serverlessworkflow.io). +The **Open Workflow Diagram Editor** is the official visual editor for the [CNCF Open Workflow Specification](https://serverlessworkflow.io). It provides an intuitive, interactive way to design, visualize, and understand serverless workflow definitions. ## What is this editor? @@ -32,7 +32,7 @@ This is a vendor-neutral, embeddable React component that allows you to: - **Understand** workflow logic through visual representation - **Integrate** the editor into your own applications and platforms -The editor is built with flexibility in mind, designed to work seamlessly in different environments including web applications, VS Code extensions, and browser-based tools. +The editor is built with flexibility in mind, designed to work seamlessly in different environments including web applications and browser-based tools. ## Getting Started @@ -42,7 +42,7 @@ Explore the **Examples** section in the sidebar to see the editor in action with - **React Flow powered**: Built on top of React Flow for smooth, performant diagram interactions - **TypeScript SDK integration**: Leverages the official TypeScript SDK for accurate workflow parsing -- **Internationalization**: Supports multiple languages (English, French) +- **Internationalization**: Supports multiple languages (English only for now) - **Embeddable**: Strict separation between core logic and platform APIs makes it easy to integrate - **Accessible**: Built with accessibility standards in mind From 70c8c1f45567f2f1987e27e6b8a69fe9747b6311 Mon Sep 17 00:00:00 2001 From: handreyrc Date: Mon, 6 Jul 2026 11:36:01 -0400 Subject: [PATCH 8/8] fix copilot complaints Signed-off-by: handreyrc --- packages/i18n/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/i18n/README.md b/packages/i18n/README.md index ebfce586..9cb30758 100644 --- a/packages/i18n/README.md +++ b/packages/i18n/README.md @@ -84,7 +84,7 @@ Choose the user's locale either manually or through automatic detection: import { detectLocale } from "@serverlessworkflow/i18n"; import { dictionaries } from "./i18n/locales"; -const supportedLocales = Object.keys(dictionaries) as const; +const supportedLocales = Object.keys(dictionaries) as Array; // Auto-detect with fallback to "en" const locale = detectLocale(supportedLocales);