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/CONTRIBUTING.md b/CONTRIBUTING.md index e24cabf9..c94dacab 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,59 @@ 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. +## 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 +181,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..5e42940e 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,186 @@ 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 +``` + +## 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**: 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 + +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 +# 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 ``` -### Key Packages +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..9cb30758 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 Array; -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..a6b5c553 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**: 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` -### 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 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` -### 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..cf40b4e2 100644 --- a/packages/serverless-workflow-diagram-editor/src/core/README.md +++ b/packages/serverless-workflow-diagram-editor/src/core/README.md @@ -16,16 +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` 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. +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. -### workflowSdk.ts +## Functional Areas -Abstraction layer over the `@serverlessworkflow/sdk`. +### SDK Abstraction -### graph.ts +**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. -Add custom types to the original sdk `Graph` type. +Responsibilities: + +- 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 + +### Graph Processing + +Utilities for working with workflow graphs as data structures: + +- Normalize graph connections and edges +- Fix entry/exit node connections by redirecting them to parent containers +- Provide graph traversal and manipulation operations + +### Layout Computation + +Integration with graph layout algorithms: + +- 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 + +### Export Capabilities + +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 667f634e..c6794c20 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 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 + +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 + +## Directory Structure + +### `diagram/` + +Contains the core diagram rendering and layout logic: + +- **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/` + +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/` + +Node component implementations for all Serverless Workflow task types. + +- **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 + +Contains shared constants and utilities: + +- **Z-Index Constants**: Centralized layering configuration ensuring proper visual stacking order (selected edges above regular edges, labels above edges, selected labels above regular labels) diff --git a/packages/serverless-workflow-diagram-editor/stories/README.md b/packages/serverless-workflow-diagram-editor/stories/README.md index 68f44e6a..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/`** - 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..aa10fb1c 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 **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. -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 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 only for now) +- **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).