atscript-ui-wf

Install

npx skills add moostjs/atscript-ui      # installs all atscript-ui skills (this one + general + forms + tables + styles)
npx skills add moostjs/atscript         # sibling — .as language
npx skills add moostjs/moostjs          # sibling — Moost framework (decorators, interceptors)
npx skills add wooksjs/wooksjs          # sibling — underlying @moostjs/event-wf engine + outlets
npx skills add moostjs/atscript-db      # sibling — needed only if persisting state via AsWfStore

# Client
pnpm add @atscript/core @atscript/typescript @atscript/ui @atscript/vue-form @atscript/vue-wf vue

# Server
pnpm add @atscript/moost-wf moost @moostjs/event-http @moostjs/event-wf @prostojs/wf
pnpm add @atscript/db @atscript/db-sqlite        # only if persisting via AsWfStore

Quick start

// src/wf/forms.as
export interface HelloName {
    @meta.label 'Your name'
    @meta.required 'Name is required'
    name: string
}

// src/wf/hello.workflow.ts
import { Controller } from "moost";
import { Workflow, Step, WorkflowParam, WorkflowSchema } from "@moostjs/event-wf";
import { WfInput, finishWf } from "@atscript/moost-wf";
import { HelloName } from "./forms.as";

interface Ctx {
  name?: string;
}

@Controller()
export class HelloWorkflow {
  @Workflow("hello")
  @WorkflowSchema<Ctx>([{ id: "ask" }, { id: "greet" }])
  flow() {}

  // @WfInput() validates against the schema and throws a StepRetriableError
  // (caught natively by the wf engine) when input is missing or invalid —
  // the handler body only runs with valid input.
  @Step("ask")
  async ask(@WfInput() input: HelloName, @WorkflowParam("context") ctx: Ctx) {
    ctx.name = input.name;
  }

  @Step("greet")
  greet(@WorkflowParam("context") ctx: Ctx) {
    finishWf({ data: { greeting: `Hello, ${ctx.name}!` } });
  }
}

<!-- src/views/HelloFlow.vue -->
<script setup lang="ts">
import { createDefaultTypes } from "@atscript/vue-form";
const types = createDefaultTypes();
function onFinished(r: { greeting: string }) {
  alert(r.greeting);
}
</script>

<template>
  <AsWfForm path="/wf/trigger" name="hello" :types="types" @finished="onFinished" />
</template>

Wire protocol

Client → server:
  start          { wfid, input?, wfs? }
  submit         { wfs, input }
  action         { wfs, action }
  actionWithData { wfs, action, input }

Server → client:
  next-step      { inputRequired: { payload, transport: 'http', context }, wfs }
  finished       { finished: true, ...response }
  outlet pause   { sent: true } | { outlet: '<name>' }
  error          { error: { message, status? } }

Token transports: 'body' (default), 'cookie', 'query' (?wfs=...).

Invariants

Key imports

// Client
import { AsWfForm, useWfForm } from "@atscript/vue-wf";
import type { UseWfFormOptions, UseWfFormReturn } from "@atscript/vue-wf";

// Server — decorators, composables, helpers (full public surface of @atscript/moost-wf)
import {
  WfInput,
  WfAction,
  useAtscriptWf,
  useWfActionSlot,
  serializeFormSchema,
  extractPassContext,
  getFormActions,
  createAsHttpOutlet,
  handleAsOutletRequest,
  // WfFinished envelope helpers
  finishWf,
  abortWf,
  isWfFinished,
} from "@atscript/moost-wf";
import type {
  FinishWfOpts,
  WfFinished,
  WfMessage,
  WfNext,
  WfButton,
  WfActionRequest,
} from "@atscript/moost-wf";

// Server — atscript build-time plugin (in atscript.config.ts)
import wfPlugin from "@atscript/moost-wf/plugin"; // default export — registers @wf.context.pass, @wf.action.withData, @wf.store.fromContext

// Server — persistent state store
import { AsWfStore, AsWfStateRecord } from "@atscript/moost-wf/store";

// Moost framework — @Controller, Resolve, Intercept, useControllerContext live here
import { Controller, Resolve, Intercept } from "moost";

// Workflow engine — @Workflow, @Step, @WorkflowSchema, @WorkflowParam,
// useWfState, useWfOutlet, outletEmail, outletHttp, StepRetriableError, etc. all live here.
// (To complete a step prefer `finishWf` / `abortWf` from `@atscript/moost-wf` above;
//  raw `useWfFinished` from `@moostjs/event-wf` is the cookies escape hatch — see server.md.)
import {
  Workflow,
  Step,
  WorkflowParam,
  WorkflowSchema,
  StepTTL,
  useWfState,
  useWfOutlet,
  outlet,
  outletEmail,
  outletHttp,
} from "@moostjs/event-wf";
import { StepRetriableError } from "@wooksjs/event-wf";

References — load only what's needed

Customization

Workflow forms ride on top of <AsForm>, so the bulk of UI customization happens through the forms skill. The wf-specific surfaces:

• Tier 1 — <AsWfForm> and <AsWfFinish> are the integration surface. Use useWfForm(options) for a fully custom shell.
• Tier 2 — the finish slots (wf.finish.*) and the embedded <AsForm> defaults. The form's :types and :components propagate through <AsWfForm> straight to the form it renders.
• Server-side outlets — swap the transport (email magic link, webhook, awaiting payment, …) by mounting different outlet helpers; see [outlets.md](references/outlets.md).

Propagate form customization through <AsWfForm>

The :types and :components props on <AsWfForm> are passed straight through to the underlying <AsForm>. Customize the same way you would a plain form:

<script setup lang="ts">
import { createDefaultTypes } from "@atscript/vue-form";
import MyTextInput from "./MyTextInput.vue";
import CountryPicker from "./CountryPicker.vue";

const types = { ...createDefaultTypes(), text: MyTextInput };
const components = { "country-picker": CountryPicker };
</script>

<template>
  <AsWfForm path="/wf/trigger" name="signup" :types="types" :components="components" />
</template>

See [atscript-ui-forms](../atscript-ui-forms/SKILL.md) for the full :types / :components / AsFieldShell swap mechanics.

Customize finish + abort screens

<AsWfForm> renders <AsWfFinish> once the server emits a WfFinished envelope. Override message, primary CTA, countdown, dismiss button, or any per-option button via the wf.finish.* scoped slots. The server side ships envelopes via finishWf({ ... }) or abortWf(reason, { ... }); see [finish-screens.md](references/finish-screens.md) for the slot contract and WfNext discriminated union.

Swap outlets (server-side)

Outlets are mounted on the server controller. Replace the default createAsHttpOutlet() or add a custom outlet (outletEmail, outletHttp, your own) to change how the workflow pauses; clients reach the resume URL with <AsWfForm :initial-token="...">. See [outlets.md](references/outlets.md).

Auth + custom fetch

Pass a fetch prop on <AsWfForm> to inject auth headers, cookies, or routing — the same way the table side accepts a clientFactory. The composable form is useWfForm({ fetch, ... }).

Style consequence

The form chrome inside <AsWfForm> is plain <AsForm>, so styles tree-shake the same way: replace a default field component and its as- shortcuts drop. The finish screen's as-wf-finish- shortcuts stay reachable as long as you use the default <AsWfFinish> rendering. See atscript-ui-styles for the per-domain shortcut groups (wfShortcuts).

See also

Reference docs: https://ui.atscript.dev/workflows/. Source: https://github.com/moostjs/atscript-ui.