joel-wenzel
diff --git a/‎.github/workflows/main.yml‎
Lines changed: 91 additions & 19 deletions b/‎.github/workflows/main.yml‎
Lines changed: 91 additions & 19 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 155 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 155 additions & 0 deletions
@@ -1,41 +1,113 @@
-# This is a basic workflow to help you get started with Actions
-
 name: CI
 
-# Controls when the workflow will run
 on:
-  # Triggers the workflow on push or pull request events but only for the 1.0.0-beta branch
   push:
     branches: [1.0.0-beta]
 
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
-  # This workflow contains a single job called "build"
   build:
-    # The type of runner that the job will run on
     runs-on: ubuntu-latest
-
-    # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      - uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          registry-url: 'https://registry.npmjs.org'
+      - uses: actions/checkout@v4
 
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
 
-      # Build
-      - name: Build Library
+      - name: Install and Build Library
         run: |
           npm install
           npm run build
 
+      - name: Pack Library
+        run: npm pack
+        working-directory: dist/ng-flowchart
+
+      - name: Upload Library Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ng-flowchart-dist
+          path: dist/ng-flowchart
+          retention-days: 1
+
+  compat-test:
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Oldest supported Angular version
+          - angular-version: 16
+            node-version: 18
+          # Mid-range Angular version
+          - angular-version: 18
+            node-version: 20
+          # Latest supported Angular version
+          - angular-version: 21
+            node-version: 22
+    name: Compat (Angular ${{ matrix.angular-version }})
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: ng-flowchart-dist
+          path: ng-flowchart-dist
+
+      - name: Create Angular ${{ matrix.angular-version }} Project
+        run: |
+          npx -y @angular/cli@${{ matrix.angular-version }} new compat-test \
+            --minimal --skip-git --skip-tests --defaults
+
+      - name: Install Library
+        working-directory: compat-test
+        run: npm install ${{ github.workspace }}/ng-flowchart-dist/joelwenzel-ng-flowchart-*.tgz
+
+      - name: Add Library Import
+        working-directory: compat-test
+        run: |
+          if [ -f src/app/app.module.ts ]; then
+            # NgModule-based app (Angular 16): patch app.module.ts
+            sed -i '1i import { NgFlowchartModule } from "@joelwenzel/ng-flowchart";' src/app/app.module.ts
+            # imports array spans multiple lines; match BrowserModule at end of line
+            sed -i 's/^\(\s*\)BrowserModule$/\1BrowserModule, NgFlowchartModule/' src/app/app.module.ts
+          else
+            # Standalone app: file is app.ts (Angular 21+) or app.component.ts (Angular 17-20)
+            if [ -f src/app/app.ts ]; then
+              APP_FILE=src/app/app.ts
+            else
+              APP_FILE=src/app/app.component.ts
+            fi
+            sed -i '1i import { NgFlowchartModule } from "@joelwenzel/ng-flowchart";' "$APP_FILE"
+            sed -i 's/imports: \[/imports: [NgFlowchartModule, /' "$APP_FILE"
+          fi
+
+      - name: Build Project
+        working-directory: compat-test
+        run: npx ng build
+
+  publish:
+    needs: [build, compat-test]
+    runs-on: ubuntu-latest
+    if: github.repository == 'joel-wenzel/ng-flowchart'
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: ng-flowchart-dist
+          path: ng-flowchart-dist
+
       - name: Publish
         run: npm publish --access public
-        working-directory: dist/ng-flowchart
+        working-directory: ng-flowchart-dist
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
@@ -0,0 +1,155 @@
+# CLAUDE.md - AI Assistant Guide for ng-flowchart
+
+## Project Overview
+
+**ng-flowchart** is a lightweight Angular library for building drag-and-drop flowcharts. It provides customizable chart behavior, step components, and JSON import/export capabilities. Published as `@joelwenzel/ng-flowchart` on NPM.
+
+- **Angular version:** 18.0.3
+- **TypeScript version:** 5.4.5
+- **License:** Apache 2.0
+
+## Repository Structure
+
+This is a monorepo containing two Angular projects:
+
+```
+projects/
+  ng-flowchart/          # The library (published to NPM)
+    src/
+      lib/
+        model/           # Core types and Flow API (flow.model.ts)
+        services/        # Core services (canvas-renderer, dropdata, options, step-manager)
+        ng-flowchart-arrow/         # SVG arrow connector component
+        ng-flowchart-connector/     # Manual connector component
+        ng-flowchart-connector-pad/ # Connection pad component
+        ng-flowchart-pad-arrow/     # Pad arrow component
+        ng-flowchart-step/          # Base step component (extendable)
+        ng-flowchart-canvas.directive.ts   # Main canvas directive
+        ng-flowchart-canvas.service.ts     # Canvas state/rendering service
+        ng-flowchart-step.directive.ts     # Step drag directive
+        ng-flowchart-step-registry.service.ts # Custom step type registry
+        ng-flowchart.module.ts             # NgFlowchartModule
+      index.ts           # Public API surface
+    assets/
+      styles.scss        # Base library styles
+    ng-package.json      # ng-packagr configuration
+  workspace/             # Demo application
+    src/app/
+      custom-step/       # Example custom step component
+      form-step/         # Example form step component
+      nested-flow/       # Example nested flowchart component
+      app.component.ts   # Main demo with all features
+```
+
+## Build Commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm start` | Serve the demo application locally (`ng serve`) |
+| `npm run build` | Build library for production (`ng build ng-flowchart --configuration production`) |
+| `npm test` | Run unit tests with Karma/Jasmine (`ng test`) |
+| `npm run lint` | Run ESLint with auto-fix (`ng lint --fix`) |
+| `npm run prettier` | Format all files with Prettier (`npx prettier --write .`) |
+| `npm run e2e` | Run end-to-end tests with Protractor (`ng e2e`) |
+
+## Architecture
+
+### Design Pattern
+
+- **Directive-based API:** Core functionality exposed via `NgFlowchartCanvasDirective` (canvas host) and `NgFlowchartStepDirective` (draggable palette items)
+- **Service-oriented internals:** Rendering, options, step lifecycle, and drag/drop state are separated into dedicated services
+- **Extendable step components:** Users create custom steps by extending `NgFlowchartStepComponent`
+- **Tree data structure:** The flow is represented as a linked tree with parent-child relationships
+
+### Key Files
+
+| File | Role |
+|------|------|
+| `model/flow.model.ts` | Core `NgFlowchart` namespace with `Flow` class, `Options`, `Callbacks`, step/drop types |
+| `ng-flowchart-canvas.directive.ts` | Main directive handling drop/drag events, zoom, scrolling |
+| `ng-flowchart-canvas.service.ts` | Manages flow state and rendering orchestration |
+| `ng-flowchart-step/ng-flowchart-step.component.ts` | Base step component class (extend for custom steps) |
+| `ng-flowchart-step-registry.service.ts` | Registry for resolving custom step types during JSON import |
+| `services/canvas-renderer.service.ts` | Positioning, layout, and SVG rendering logic |
+| `services/step-manager.service.ts` | Step lifecycle (creation, deletion, movement) |
+| `services/options.service.ts` | Options management |
+| `services/dropdata.service.ts` | Drag/drop transfer state |
+| `index.ts` | Public API exports |
+
+### Module Exports
+
+`NgFlowchartModule` exports two directives:
+- `NgFlowchartCanvasDirective` - Applied to a container element to create a flowchart canvas
+- `NgFlowchartStepDirective` - Applied to elements to make them draggable step sources
+
+### Major Features
+
+- **Horizontal & Vertical Orientation:** `orientation` option (`'VERTICAL'` | `'HORIZONTAL'`) with runtime switching via `setOrientation()`
+- **Drag-Scroll:** Canvas panning via configurable mouse buttons (`dragScroll` option)
+- **Manual Connectors:** Draw arrows between any two steps independent of the tree structure (`manualConnectors` option). Includes connector pads, selectable/deletable arrows, per-step validation overrides (`isConnectorPadEnabled()`, `isValidConnectorDropTarget()`), and callbacks (`onLinkConnector`, `afterDeleteConnector`)
+- **Zoom:** Mouse wheel or manual zoom with `skipRender` performance optimization for large workflows
+- **Nested Canvases:** Steps can contain their own flowchart canvases with scale synchronization (`setNestedScale()`)
+- **OnPush Change Detection:** Full support for `ChangeDetectionStrategy.OnPush`
+- **JSON with Connectors:** Export/import includes both `root` tree and `connectors` array
+
+## Code Style & Conventions
+
+### Formatting (Prettier)
+
+- 2-space indentation, no tabs
+- Single quotes for strings
+- Semicolons required
+- Trailing commas in ES5 positions
+- 80 character print width
+- Arrow function parens avoided for single params (`avoid`)
+- Brackets on same line as opening tag (`bracketSameLine: true`)
+
+### Linting (ESLint)
+
+- Extends: `@angular-eslint/recommended` + `prettier/recommended`
+- Component selectors: **kebab-case** with `lib` prefix (e.g., `lib-my-component`)
+- Directive selectors: **camelCase** with `lib` prefix (e.g., `libMyDirective`)
+- Empty lifecycle methods are allowed (`@angular-eslint/no-empty-lifecycle-method: 0`)
+- HTML templates use Angular template linting rules
+
+### TypeScript
+
+- Target: ES2022, Module: ESNext
+- Strict Angular compiler options enabled (`strictInjectionParameters`, `strictInputAccessModifiers`, `strictTemplates`)
+- `useDefineForClassFields: false` (required for Angular decorator compatibility)
+- Path alias: `ng-flowchart` maps to `dist/ng-flowchart/`
+
+### EditorConfig
+
+- UTF-8 charset
+- 2-space indentation
+- Final newline inserted
+- Trailing whitespace trimmed (except `.md` files)
+- Single quotes for `.ts` files
+
+## Testing
+
+- **Framework:** Jasmine 5.1.2 + Karma 6.4.3
+- **Browser:** Chrome
+- **Test files:** Co-located with source using `.spec.ts` suffix
+- **Coverage:** Istanbul reporter generating HTML, LCOV, and text-summary in `coverage/ng-flowchart/`
+- **Teardown config:** `destroyAfterEach: false`
+- Run tests: `npm test`
+
+## CI/CD
+
+GitHub Actions workflow (`.github/workflows/main.yml`):
+- Triggers on push to `1.0.0-beta` branch or manual dispatch
+- Runs on `ubuntu-latest` with Node 18
+- Steps: `npm install` -> `npm run build` -> `npm publish --access public`
+- Publishes from `dist/ng-flowchart` to NPM using `NPM_AUTH_TOKEN` secret
+
+## Important Notes for AI Assistants
+
+1. **Library vs Demo:** Changes to the library go in `projects/ng-flowchart/`. The `projects/workspace/` directory is the demo app for testing. Do not confuse the two.
+2. **Public API:** Only items exported through `projects/ng-flowchart/src/index.ts` are part of the public API. Internal services should not be exported.
+3. **Build before test with demo:** The demo app (`workspace`) imports the library from `dist/ng-flowchart` via the tsconfig path alias. Build the library first (`npm run build`) before serving the demo.
+4. **ng-packagr:** The library is packaged with ng-packagr. The `ng-package.json` file controls entry points and assets. SCSS assets are bundled from the `assets/` directory.
+5. **Angular version support:** The library supports Angular 16-21 via peer dependencies. Avoid using APIs exclusive to Angular 19+ to maintain backward compatibility.
+6. **No standalone components:** The library uses `NgModule` declarations, not standalone components. Follow this pattern for new components.
+7. **Custom steps pattern:** Users extend `NgFlowchartStepComponent` and register types via `NgFlowchartStepRegistryService` for JSON serialization/deserialization. Refer to the demo app's `custom-step/`, `form-step/`, and `nested-flow/` for examples.