# @masterteam/flowplus-workflow

FlowPlus2 — workflow **design-time builder** package.

This package is the design-time studio + canvas + inspector + publish flow
for FlowPlus workflows. **It is not a runtime.** It does not own:

- Work Center inboxes (`@masterteam/work-center`)
- Runtime dynamic form rendering (`@masterteam/forms/client-form`)
- Runtime task action pages or footer actions (`@masterteam/components/runtime-action`)
- Process-start / task-action pages (those live in host apps + Work Center)

When admins finish designing a workflow here, end-users run it through the
existing Work Center inbox + ClientForm runtime that other apps already use.
FlowPlus runtime needs are tracked in
[`docs/flowplus-runtime-integration-notes.md`](docs/flowplus-runtime-integration-notes.md);
no shared runtime package is modified by this package today.

---

## Layering

- `@foblex/flow` is used directly as the canvas and interaction layer
  **only**, and is fully isolated inside `lib/builder/canvas/`. No Foblex
  names or types leak into contracts, domain, store, or the public API.
- FlowPlus2 owns: design-time graph state, inspector logic, validation
  surfacing, context mapping, builder API integration, layout persistence,
  publish lifecycle, optional run debugger.
- Consumes `@masterteam/forms` only through the optional form designer
  adapter token. No `ClientForm` runtime is imported.
- State is managed with **NGXS** (`@masterteam/components` `handleApiRequest`
  + `LoadingStateShape`), matching the rest of the masterteam packages
  (`@masterteam/work-center`, `@masterteam/properties`, etc.).

## Strict rules

- Does not depend on `@masterteam/workflow`.
- Does not depend on `@masterteam/structure-builder`.
- Does not modify `@masterteam/work-center`, `@masterteam/forms/client-form`,
  `@masterteam/components/runtime-action`, or `@masterteam/client-components`.
  Any future runtime integration must land behind a feature flag in those
  packages and is captured ahead of time in
  [`docs/flowplus-runtime-integration-notes.md`](docs/flowplus-runtime-integration-notes.md).
- Does not own the API base URL — the host app's HTTP interceptor pipeline
  is responsible for base URL, auth, language, tenant, correlation, and
  envelope. Endpoints are emitted as **bare relative paths**
  (`workflow-definitions`, `workflow-definitions/123/builder`, …).
- Does not own the router — the host mounts the package's standalone page
  components at the paths it chooses.

---

## Integration into a host app

The package mounts inside any existing Angular app. The host already provides:

- `provideHttpClient(...)` with its own interceptors (auth, language, tenant…)
- `provideRouter(...)` with the host's existing route tree
- `provideAnimationsAsync()`, theming (`provideMTComponents`, …)
- Transloco providers
- NGXS `provideStore(...)` (the host registers its full `APP_STATES`)

You do **not** call `provideHttpClient`, `provideRouter`, or pass an
`apiBaseUrl` to FlowPlus.

### 1. Register the NGXS state

Add `FlowplusWorkflowState` to the host's NGXS `APP_STATES` array — the
same array that already lists `WorkCenterState`, `GovernanceState`, etc.:

```ts
// apps/<your-app>/src/app/store/store.config.ts
import { provideStore } from '@ngxs/store';
import { FlowplusWorkflowState } from '@masterteam/flowplus-workflow';

export const APP_STATES = [
  // ...existing host states...
  FlowplusWorkflowState,
];

export const appConfig: ApplicationConfig = {
  providers: [
    provideStore(APP_STATES, /* ...host config... */),
    // ...
  ],
};
```

### 2. (Optional) Provide a navigation config

`provideFlowplusWorkflow()` is a no-arg setup helper for general capability
flags. If the host uses different paths from the package defaults, register
a navigation config so internal links follow the host's URLs:

```ts
import {
  provideFlowplusWorkflow,
  provideFlowplusWorkflowNavigation,
} from '@masterteam/flowplus-workflow';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFlowplusWorkflow(),
    provideFlowplusWorkflowNavigation({
      toStudio:  '/flowplus/studio',
      toBuilder: ({ workflowId }) => ['/flowplus/studio', workflowId, 'builder'],
      // Optional: handle "open the matching Work Center task" from the
      // builder topbar. Host wires this into its existing Work Center route.
      openRuntimeTask: ({ requestId, stepId }) =>
        router.navigate(['/work-center/my-inbox/details', requestId, 'tasks', stepId]),
    }),
  ],
};
```

### 3. Mount the page components

The host owns routing. Import the standalone page components and place
them under any path that suits the host's layout/menu/permissions:

```ts
import { Routes } from '@angular/router';
import {
  WorkflowStudioPageComponent,
  WorkflowBuilderPageComponent,
  WorkflowRunDebuggerPageComponent, // optional, admin-gated
} from '@masterteam/flowplus-workflow';

export const routes: Routes = [
  // ...host's existing routes...
  {
    path: 'flowplus/studio',
    component: WorkflowStudioPageComponent,
  },
  {
    path: 'flowplus/studio/:workflowId/builder',
    component: WorkflowBuilderPageComponent,
  },
  // Optional admin route — only mount it if the host's permission system
  // also gates it. The package marks it `data: { permission: 'CONTROL_PANEL',
  // feature: 'workflowRuntimeDebugger' }`.
  {
    path: 'flowplus/studio/:workflowId/runs/:requestId/debug',
    component: WorkflowRunDebuggerPageComponent,
    data: { permission: 'CONTROL_PANEL', feature: 'workflowRuntimeDebugger' },
  },
];
```

There is no built-in route for "start a process" or "open a task" — those
flows already live in the host's existing Work Center + ClientForm pages.

### 4. (Optional) Form designer adapter

If the host has a form designer, register an adapter so the UserInput
step's "Open form designer" / "Preview form" buttons open it:

```ts
import { provideFlowplusFormDesignerAdapter } from '@masterteam/flowplus-workflow';

provideFlowplusFormDesignerAdapter(MyHostFormDesignerAdapter);
```

If no adapter is provided, the UserInput → Form tab renders an inline
"Form designer not connected in this host" notice. There is no browser
alert.

### 5. Assets

The package ships a Tailwind v4 stylesheet at
`@masterteam/flowplus-workflow/assets/flowplus-workflow.css`. Add it to
your app's stylesheets (e.g. in `angular.json` `styles[]` or imported
from the app's root SCSS).

Translations live at `assets/i18n/{en,ar}.json` and follow the host's
Transloco scope loading convention.

---

## What the package provides

| Surface | Description |
|---|---|
| Studio       | Workflow list + filters + create dialog |
| Builder      | Foblex-backed canvas, palette, inspector tabs, problems / test-run / context bottom panel |
| Debugger     | Admin-only context / timeline / lineage / events view (opt-in route) |
| Contracts    | Strongly-typed DTOs for definitions, steps, connections, triggers, catalog, context, validation, debug |
| NGXS state   | `FlowplusWorkflowState` + `FlowplusWorkflowFacade` (debounced saves, optimistic CRUD with rollback, layout-isolated dirty flags) |
| Adapter      | `FLOWPLUS_FORM_DESIGNER_ADAPTER` extension point |
| Navigation   | `provideFlowplusWorkflowNavigation(...)` host-configurable |

## What the package does NOT provide

| Concern | Owned by |
|---|---|
| Inbox / task list / claim / assign       | `@masterteam/work-center` |
| Dynamic form rendering at runtime        | `@masterteam/forms/client-form` |
| Footer / dynamic runtime actions         | `@masterteam/components/runtime-action` |
| `process-form-load` / `process-submit`   | host app + Work Center runtime |
| API base URL / auth / interceptors       | host app |
| Router / route tree                      | host app |

If FlowPlus eventually needs additional runtime behavior from any of those
packages, see [`docs/flowplus-runtime-integration-notes.md`](docs/flowplus-runtime-integration-notes.md)
for the rules (opt-in feature flag, default-OFF, owner sign-off).

## Backend contract status

See [`docs/workflow-backend-contract-gaps.md`](docs/workflow-backend-contract-gaps.md)
for the canonical FE/BE alignment notes and the list of endpoints required
for the next backend deliverable.

## Build

```bash
pnpm --filter @masterteam/flowplus-workflow build
# or
pnpm build:fp-workflow
```

## Test

```bash
pnpm --filter @masterteam/flowplus-workflow test
```
