@juo/orion-core 0.12.0 → 0.14.0

package/dist/flows/WorkflowService.d.ts

@@ -0,0 +1,156 @@
+import { ReadonlySignal } from '@preact/signals-core';
+import { ThemeState } from '../theme-state';
+export declare const WorkflowServiceContext: {
+    __context__: {
+        state: ReadonlySignal<WorkflowState>;
+        /** True when the portal is running inside the Orion editor (editorMode dep
+         *  or ?trigger=... URL param). Consumers use this to suppress auto-start. */
+        isPreviewMode: boolean;
+        isActive: ReadonlySignal<boolean>;
+        isLoading: ReadonlySignal<boolean>;
+        isCompleted: ReadonlySignal<boolean>;
+        hasError: ReadonlySignal<boolean>;
+        currentInteraction: ReadonlySignal<PendingInteraction | null>;
+        currentStepInfo: ReadonlySignal<WorkflowStepInfo | null>;
+        startFlow(flowType: string, context: Record<string, unknown>, workflowId?: string): Promise<void>;
+        respond(responseType: string, responseData?: Record<string, unknown>): Promise<void>;
+        cancel(): Promise<void>;
+        reset(): void;
+        refresh(): Promise<void>;
+    };
+};
+/**
+ * Mirrors `PendingInteraction` from `@juo/workflows-core`.
+ * Inlined here to avoid a cross-package dependency from orion-core -> workflow-core.
+ */
+export interface PendingInteraction {
+    /** Unique per interaction instance (idempotency/stale-response protection) */
+    interactionId: string;
+    stepId: string;
+    actionType: string;
+    actionBehavior: "input";
+    actionConfig: Record<string, unknown>;
+    availableResponses: Array<{
+        type: string;
+        label: string;
+    }>;
+    presentedAt: Date;
+    /** Optional relative timeout duration (milliseconds) */
+    timeoutMs?: number;
+}
+export interface WorkflowOutcome {
+    type: string;
+    message: string;
+}
+export type WorkflowStatus = "idle" | "loading" | "active" | "completed" | "error";
+export interface WorkflowState {
+    status: WorkflowStatus;
+    flowType: string | null;
+    workflowId: string | null;
+    workflowVersion: number | null;
+    runId: string | null;
+    runVersion: number | null;
+    currentStepId: string | null;
+    currentInteraction: PendingInteraction | null;
+    error: string | null;
+    result: Record<string, unknown> | null;
+    /** Parameters passed to startFlow (e.g. { layout: 'modal' | 'sidebar' }) */
+    flowParams: Record<string, unknown> | null;
+    /** Accumulated resources invalidated by actions across all responses in this flow. */
+    invalidatedResources: string[];
+    /** Describes the primary action taken when the workflow completes.
+     *  Used to show a confirmation toast (e.g. "Your subscription has been cancelled"). */
+    outcome: WorkflowOutcome | null;
+}
+/** Available steps metadata (for rendering and editor) */
+export interface WorkflowStepInfo {
+    interactionId: string;
+    stepId: string;
+    actionType: string;
+    actionConfig: Record<string, unknown>;
+    availableResponses: Array<{
+        type: string;
+        label: string;
+    }>;
+}
+/**
+ * Lightweight step definition (no per-instance interactionId).
+ * Used by `interactiveSteps` to describe the full set of input steps
+ * in a workflow so the root block can pre-populate all slots and presets.
+ */
+export interface WorkflowStepDefinition {
+    stepId: string;
+    actionType: string;
+    actionConfig: Record<string, unknown>;
+    availableResponses: Array<{
+        type: string;
+        label: string;
+    }>;
+}
+export type WorkflowStartResponse = {
+    status: "no_workflow";
+} | {
+    status: "completed_silently";
+    invalidatedResources?: string[];
+    outcome?: WorkflowOutcome;
+} | WorkflowRunState;
+export interface WorkflowRunState {
+    workflowId: string;
+    workflowVersion: number;
+    runId: string;
+    runVersion: number;
+    status: "running" | "waiting_interaction" | "completed" | "failed" | "cancelled";
+    pendingInteraction?: PendingInteraction;
+    /** All interactive (input) steps in this workflow, in order.
+     *  Provided on start() so the client can pre-populate all root block slots and editor presets. */
+    interactiveSteps?: WorkflowStepDefinition[];
+    result?: Record<string, unknown>;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    /** Resources invalidated by actions executed during this response (e.g. ["subscription"]). */
+    invalidatedResources?: string[];
+    outcome?: WorkflowOutcome;
+}
+/**
+ * API adapter interface for WorkflowService.
+ * Allows different implementations (real API, mocked, etc.)
+ */
+export interface WorkflowApiAdapter {
+    start(flowType: string, context: Record<string, unknown>, workflowId?: string, dryRun?: boolean): Promise<WorkflowStartResponse>;
+    respond(runId: string, interactionId: string, responseType: string, responseData?: Record<string, unknown>, expectedRunVersion?: number, eventId?: string): Promise<WorkflowRunState>;
+    getState(runId: string): Promise<WorkflowRunState>;
+    cancel(runId: string): Promise<WorkflowRunState>;
+}
+/**
+ * Create a real API adapter for the Customer API.
+ */
+export declare function createWorkflowApiAdapter(sdk: {
+    get: any;
+    post: any;
+}): WorkflowApiAdapter;
+export interface WorkflowServiceDependencies {
+    /** API adapter for communicating with backend */
+    api: WorkflowApiAdapter;
+    /** ThemeState context for resolving the started workflow */
+    themeState: ThemeState;
+}
+export declare function createWorkflowService(deps: WorkflowServiceDependencies): {
+    state: ReadonlySignal<WorkflowState>;
+    /** True when the portal is running inside the Orion editor (editorMode dep
+     *  or ?trigger=... URL param). Consumers use this to suppress auto-start. */
+    isPreviewMode: boolean;
+    isActive: ReadonlySignal<boolean>;
+    isLoading: ReadonlySignal<boolean>;
+    isCompleted: ReadonlySignal<boolean>;
+    hasError: ReadonlySignal<boolean>;
+    currentInteraction: ReadonlySignal<PendingInteraction | null>;
+    currentStepInfo: ReadonlySignal<WorkflowStepInfo | null>;
+    startFlow(flowType: string, context: Record<string, unknown>, workflowId?: string): Promise<void>;
+    respond(responseType: string, responseData?: Record<string, unknown>): Promise<void>;
+    cancel(): Promise<void>;
+    reset(): void;
+    refresh(): Promise<void>;
+};
+export type WorkflowService = ReturnType<typeof createWorkflowService>;

package/dist/flows/__tests__/WorkflowService.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/flows/__tests__/defaults.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/flows/__tests__/juo-workflow.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/flows/__tests__/overlay-behavior.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/flows/__tests__/theme-state-surfaces.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/flows/defaults.d.ts

@@ -0,0 +1,14 @@
+import { Block } from '../block';
+/**
+ * Get default block for a flow step based on action type.
+ * Looks for a registered block with name `action:<actionType>`.
+ *
+ * Used by:
+ * - <juo-workflow> for rendering current step
+ * - OrionWorkflowInitializer when no custom block is defined for a step
+ */
+export declare function getDefaultBlockForAction(actionType: string, actionConfig: Record<string, unknown>, blockId?: string): Block;
+/**
+ * Check if a default block exists for an action type.
+ */
+export declare function hasDefaultBlockForAction(actionType: string): boolean;

package/dist/flows/index.d.ts

@@ -0,0 +1,3 @@
+export { createWorkflowService, createWorkflowApiAdapter, WorkflowServiceContext, type PendingInteraction, type WorkflowService, type WorkflowApiAdapter, type WorkflowServiceDependencies, type WorkflowState, type WorkflowStatus, type WorkflowStepInfo, type WorkflowStepDefinition, type WorkflowStartResponse, type WorkflowRunState, type WorkflowOutcome, } from './WorkflowService';
+export { getDefaultBlockForAction, hasDefaultBlockForAction, } from './defaults';
+export { createMockWorkflowApiAdapter } from './MockWorkflowApiAdapter';

package/dist/flows/juo-workflow.d.ts

@@ -0,0 +1,47 @@
+/**
+ * <juo-workflow> web component
+ *
+ * Renders the current workflow step by:
+ * 1. Subscribing to WorkflowServiceContext
+ * 2. Watching state (status + currentStepInfo) changes
+ * 3. For active/loading state with a step: renders <juo-extension-root surface="overlay" name="<stepId>">
+ *    - The step is kept mounted during `loading` so button processing state is preserved
+ *      while the respond API call is in flight.
+ *    - The DOM is only replaced when the step ID actually changes.
+ * 4. For all other states: clears content
+ *    - `completed`: unloads content; the portal handles teardown
+ *    - `error`: dispatches a `juo-workflow-error` CustomEvent for the portal to handle
+ *
+ * The `name` attribute on juo-extension-root corresponds to the current step ID.
+ * The `surface="overlay"` attribute selects ThemeStateContext.overlay blocks.
+ * Block resolution (default vs custom) is handled by OrionWorkflowInitializer
+ * which updates ThemeStateContext.overlay with the appropriate blocks.
+ *
+ * Usage:
+ * <juo-workflow></juo-workflow>
+ *
+ * Must be placed inside an element where WorkflowServiceContext is provided.
+ *
+ * The `blockWrapper` property accepts an optional function:
+ *   (rendered: HTMLElement) => HTMLElement
+ * When provided, it is called to wrap each rendered block element.
+ * This allows the parent (e.g. WorkflowOverlay) to inject a sidebar/modal container
+ * inside the Orion block wrapper, producing:
+ *   juo-editor-block-wrapper -> [blockWrapper result] -> actual block
+ */
+export declare class JuoWorkflowElement extends HTMLElement {
+    private workflowService;
+    private unsubscribeContext;
+    private unsubscribeEffect;
+    /** Tracks which step is currently mounted to avoid unnecessary DOM teardown. */
+    private renderedStepId;
+    /**
+     * Optional function to wrap rendered content (step blocks).
+     * Must be set before workflow becomes active for correct behavior.
+     */
+    blockWrapper: ((rendered: HTMLElement) => HTMLElement) | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private setupSubscription;
+    private render;
+}