From e0db641bbec16a99b6650345985059a0e11aa2ff Mon Sep 17 00:00:00 2001 From: handreyrc Date: Tue, 30 Jun 2026 21:42:04 -0400 Subject: [PATCH 1/2] 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 f252e9a6a2ec1b51e62f0933992953de6ac71522 Mon Sep 17 00:00:00 2001 From: handreyrc Date: Tue, 30 Jun 2026 22:29:02 -0400 Subject: [PATCH 2/2] 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