@bsm-form/core 0.39.0

package/dist/index.d.cts

@@ -0,0 +1,591 @@
+import * as _bsm_form_schema from '@bsm-form/schema';
+import { ToastVariant, ToastPosition, Condition, DisplayEventType, FieldEventType, TableInteraction, DialogEventType, DrawerEventType, RepeatOperation, Node, ActionNode, DisplayNode, FieldNode, LayoutNode, ValidationRule, FormSchema, TableTagValueMapping } from '@bsm-form/schema';
+
+type FormEngineNotification = {
+    message: string;
+    variant: ToastVariant;
+    position?: ToastPosition;
+    /** Display duration in milliseconds. */
+    duration?: number;
+};
+type InvokeContext = {
+    values: Record<string, unknown>;
+    resources: Record<string, unknown>;
+    row?: Record<string, unknown>;
+    item?: Record<string, unknown>;
+};
+type InvokeHandler = (ctx: InvokeContext) => void | Promise<void>;
+/** Sync visibility / when-branch predicate. Must not return a Promise. */
+type PredicateHandler = (ctx: InvokeContext) => boolean;
+/**
+ * Sync field validator. `true` = valid; string = error message.
+ * Must not return a Promise.
+ */
+type ValidatorHandler = (ctx: InvokeContext) => true | string;
+/** Sync computed value producer. Must not return a Promise. */
+type ComputerHandler = (ctx: InvokeContext) => unknown;
+type FormEngineEnvironment = {
+    request: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    log: (message: string) => void;
+    navigate: (to: string) => void;
+    notify: (notification: FormEngineNotification) => void;
+    /** Host-registered handlers keyed by invoke Step `name`. */
+    invoke: Record<string, InvokeHandler>;
+    /** Host-registered sync predicates for `{ type: "invoke", name }` conditions. */
+    predicates: Record<string, PredicateHandler>;
+    /** Host-registered sync validators for `{ type: "invoke", name }` rules. */
+    validators: Record<string, ValidatorHandler>;
+    /** Host-registered sync computers for `{ operator: "invoke", name }` computed. */
+    computers: Record<string, ComputerHandler>;
+};
+declare function createFormEngineEnvironment(overrides?: Partial<FormEngineEnvironment>): FormEngineEnvironment;
+declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+
+declare const conditions: {
+    run(ctx: PipelineContext): void;
+};
+
+declare class DependencyGraph {
+    private forward;
+    private reverse;
+    addDependency(from: string, to: string): void;
+    private addEdge;
+    private wouldCreateCycle;
+    getAffected(field: string): string[];
+    getDependencies(field: string): string[];
+    getDependentsDeep(field: string): string[];
+    getAffectedInOrder(fields: Iterable<string>): string[];
+    sortTopologically(fields: Iterable<string>): string[];
+    extractDependencies(conditions: readonly Condition[]): string[];
+    clear(): void;
+}
+
+declare class EventBus<TEvent> {
+    private listeners;
+    emit(event: TEvent): void;
+    subscribe(listener: Listener<TEvent>): () => void;
+}
+
+type StepRunOptions = {
+    row?: Record<string, unknown>;
+    item?: Record<string, unknown>;
+    /** Values-mode Repeat item index for remove/move/duplicate defaults. */
+    itemIndex?: number;
+    /** Parent values-mode path prefix (e.g. `todos.0`) for nested repeats. */
+    valuePrefix?: string;
+};
+
+declare class FormEngine {
+    private runtimeTree;
+    private values;
+    private resources;
+    private initialValues?;
+    private initialResources?;
+    bus: EventBus<FormEvent>;
+    private graph;
+    private stepRunner;
+    private environment;
+    private fieldNodes;
+    private actionNodes;
+    private displayNodes;
+    private stepperNodes;
+    private paginationNodes;
+    private tabsNodes;
+    private accordionNodes;
+    private dialogNodes;
+    private drawerNodes;
+    private repeatNodes;
+    private accordionItemNodes;
+    private valuesRepeatMetas;
+    private valuesRepeatFieldIds;
+    private itemFieldState;
+    private state;
+    private pendingActionIds;
+    private pendingTableInteractions;
+    private runningFieldEvents;
+    private runningLayoutEvents;
+    private resourceInFlight;
+    private computedMap;
+    private batchDepth;
+    private hasPendingStateUpdate;
+    private initializationPromise?;
+    private skipLoadStepsOnInitialize;
+    constructor(runtimeTree: RuntimeNode, environment?: Partial<FormEngineEnvironment>);
+    runLoadSteps(): Promise<void>;
+    initialize(options?: {
+        skipLoadSteps?: boolean;
+    }): Promise<void>;
+    private performInitialization;
+    private buildNodeIndexes;
+    private getFieldNode;
+    private hydrateValues;
+    getError(name: string): string | undefined;
+    touch(name: string): void;
+    isVisible(name: string): boolean;
+    isDisabled(name: string): boolean;
+    isTouched(name: string): boolean;
+    isDirty(name: string): boolean;
+    isFormDisabled(): boolean;
+    setValue(name: string, value: unknown): void;
+    setResource(path: string, value: unknown): void;
+    getState(): {
+        pendingActionIds: string[];
+        pendingTableInteractions: string[];
+        resourceInFlight: string[];
+        isSubmitting: boolean;
+        isSubmitted: boolean;
+        isValidating: boolean;
+        isLoading: boolean;
+        initializationStatus: InitializationStatus;
+        initializationError?: unknown;
+    };
+    isResourceInFlight(path: string): boolean;
+    isOptionsSourceLoading(fieldName: string): boolean;
+    markResourceInFlight(saveAs: string): void;
+    clearResourceInFlight(saveAs: string): void;
+    getStepperState(stepperId: string): StepperState | undefined;
+    getPaginationState(paginationId: string): PaginationState | undefined;
+    changePagination(paginationId: string, page: number, pageSize: number): Promise<PaginationChangeResult>;
+    getTabsState(tabsId: string): TabsState | undefined;
+    changeTabs(tabsId: string, tabId: string): Promise<TabsChangeResult>;
+    getAccordionState(accordionId: string): AccordionState | undefined;
+    changeAccordion(accordionId: string, nextValue: string | string[]): Promise<AccordionChangeResult>;
+    getDialogState(dialogId: string): DialogState | undefined;
+    getDrawerState(drawerId: string): DrawerState | undefined;
+    setValues(nextValues: Record<string, unknown>): void;
+    getValue(name: string): unknown;
+    getTree(): RuntimeNode;
+    getValues(): FormValues;
+    getResources(): Record<string, unknown>;
+    getErrors(): Record<string, string>;
+    getSnapshot(): FormSnapshot;
+    subscribe(listener: () => void): () => void;
+    isValid(): boolean;
+    private getActionNode;
+    getBindValue(path: string): unknown;
+    batch<T>(operation: () => T | Promise<T>): Promise<T>;
+    executeAction(actionName: string, options?: StepRunOptions): Promise<unknown>;
+    private executeSubmitAction;
+    private runSubmitValidation;
+    executeDisplayEvent(nodeId: string, event: DisplayEventType, options?: StepRunOptions): Promise<void>;
+    executeFieldEvent(nodeId: string, event: FieldEventType, options?: StepRunOptions): Promise<void>;
+    private findFieldNodeById;
+    executeTableInteraction(nodeId: string, interaction: TableInteraction): Promise<void>;
+    openDialog(dialogId: string): Promise<DialogTransitionResult>;
+    closeDialog(dialogId: string): Promise<DialogTransitionResult>;
+    executeDialogStep(dialogId: string, operation: DialogEventType): Promise<DialogTransitionResult>;
+    openDrawer(drawerId: string): Promise<DrawerTransitionResult>;
+    closeDrawer(drawerId: string): Promise<DrawerTransitionResult>;
+    executeDrawerStep(drawerId: string, operation: DrawerEventType): Promise<DrawerTransitionResult>;
+    goToStep(stepperId: string, stepId: string): Promise<StepperNavigationResult>;
+    nextStep(stepperId: string): Promise<StepperNavigationResult>;
+    previousStep(stepperId: string): Promise<StepperNavigationResult>;
+    validateStep(stepperId: string, stepId: string): {
+        valid: boolean;
+        errors: Record<string, string>;
+    };
+    submit(): {
+        valid: boolean;
+        errors: {
+            [x: string]: string;
+        };
+        snapshot: FormSnapshot;
+    };
+    reset(): void;
+    onValueChanged({ name, value }: {
+        name: string;
+        value: unknown;
+    }): void;
+    private applyValueChanges;
+    private touchAll;
+    private createFullPipelineContext;
+    private getConditionState;
+    private reevaluateConditions;
+    private syncPendingState;
+    private settleAllFields;
+    private transitionDialog;
+    private transitionDrawer;
+    private transitionOverlay;
+    private getStepperSteps;
+    private getAvailableSteps;
+    private isStepAvailable;
+    private resetStepperStates;
+    private resetPaginationStates;
+    private resetTabsStates;
+    private resetAccordionStates;
+    private createAccordionState;
+    private runLayoutChangeEvent;
+    private createPaginationState;
+    private resetOverlayStates;
+    private reconcileStepperStates;
+    private validateStepNode;
+    private createStepperNavigationResult;
+    private notifyStateUpdated;
+    /** Emit even inside `batch` so UI can observe in-flight resource fetches. */
+    private notifyStateUpdatedImmediate;
+    private buildDependencyGraph;
+    getOptions(name: string): {
+        label: string;
+        value: _bsm_form_schema.SelectOptionValue;
+    }[] | {
+        disabled?: unknown;
+        label: unknown;
+        value: unknown;
+    }[];
+    getTableRows(nodeId: string, options?: {
+        item?: Record<string, unknown>;
+    }): Record<string, unknown>[];
+    getTypographyText(nodeId: string, options?: {
+        item?: Record<string, unknown>;
+    }): string;
+    getTagText(nodeId: string, options?: {
+        item?: Record<string, unknown>;
+    }): string;
+    getTagPresentation(nodeId: string, options?: {
+        item?: Record<string, unknown>;
+    }): {
+        label: string;
+        variant?: string;
+    };
+    getAccordionItemTitle(nodeId: string, options?: {
+        item?: Record<string, unknown>;
+    }): string;
+    getRepeatItems(nodeId: string, options?: {
+        valuePrefix?: string;
+    }): Record<string, unknown>[];
+    mutateRepeat(target: string, operation: RepeatOperation, options?: {
+        from?: string;
+        field?: string;
+        index?: number;
+        to?: number;
+        item?: Record<string, unknown>;
+        valuePrefix?: string;
+    }): Promise<RepeatMutationResult>;
+    private resolveField;
+    private ensureItemFieldState;
+    private readValuesRepeatLength;
+    private buildRepeatItem;
+    private validateValuesRepeatFields;
+    private touchAllValuesRepeatFields;
+    private pruneItemFieldState;
+    private shiftItemFieldState;
+    private rebuildItemFieldStateOrder;
+    private runRepeatEvent;
+}
+
+declare const validation: {
+    run(ctx: PipelineContext): void;
+};
+
+type RuntimeNodeState = {
+    visible: boolean;
+    disabled: boolean;
+    touched: boolean;
+    dirty: boolean;
+    error?: string;
+    /** Present only on `stepper` layout nodes. */
+    activeStepId?: string;
+    /** Present only on `dialog` and `drawer` overlay layout nodes. */
+    open?: boolean;
+    /** Present only on `pagination` layout nodes. */
+    page?: number;
+    /** Present only on `pagination` layout nodes. */
+    pageSize?: number;
+    /** Present only on `tabs` layout nodes. */
+    activeTabId?: string;
+    /** Present only on `accordion` layout nodes. */
+    openItemIds?: string[];
+};
+type RuntimeNode = {
+    id: string;
+    schema: Node;
+    state: RuntimeNodeState;
+    children: RuntimeNode[];
+};
+type RuntimeTree = {
+    root: RuntimeNode;
+};
+
+type ActionContext = {
+    values: Record<string, unknown>;
+    engine: FormEngine;
+};
+type ActionHandler = (ctx: ActionContext) => Promise<unknown> | unknown;
+type FormEngineConfig = {
+    actions?: Record<string, ActionHandler>;
+};
+type FormValues = Record<string, unknown>;
+type InitializationStatus = "idle" | "loading" | "ready" | "failed";
+type FormEngineState = {
+    isSubmitting: boolean;
+    isSubmitted: boolean;
+    isValidating: boolean;
+    isLoading: boolean;
+    initializationStatus: InitializationStatus;
+    initializationError?: unknown;
+    /** Action node ids currently running custom steps. */
+    pendingActionIds: readonly string[];
+    /** Table interaction keys currently running (`nodeId:rowClick` or `nodeId:columnId:actionId`). */
+    pendingTableInteractions: readonly string[];
+    /** Resource relative paths currently being written by an in-flight API `saveAs`. */
+    resourceInFlight: readonly string[];
+};
+type FormSnapshot = {
+    values: Record<string, unknown>;
+    nodes: Map<string, RuntimeNode>;
+};
+type PipelineContext = {
+    tree: RuntimeNode;
+    values: FormValues;
+    changedField: string;
+    value: unknown;
+    affectedFields?: string[];
+    computedMap?: Map<string, RuntimeNode>;
+    resources?: Record<string, unknown>;
+    environment?: FormEngineEnvironment;
+    state?: Pick<FormEngineState, "isLoading" | "initializationStatus" | "pendingActionIds" | "resourceInFlight"> & {
+        /** Mirrors `FormEngine.isValid()` for `$state.isValid` conditions. */
+        isValid?: boolean;
+    };
+};
+type FormErrors = Record<string, string | undefined>;
+type StepperState = {
+    activeStepId?: string;
+    canGoNext: boolean;
+    canGoPrevious: boolean;
+};
+type StepperNavigationReason = "changed" | "already-active" | "not-ready" | "stepper-not-found" | "step-not-found" | "step-unavailable" | "validation-failed" | "no-next-step" | "no-previous-step";
+type StepperNavigationResult = {
+    reached: boolean;
+    changed: boolean;
+    activeStepId?: string;
+    reason: StepperNavigationReason;
+    errors: Record<string, string>;
+};
+type PaginationState = {
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+};
+type PaginationChangeReason = "changed" | "already-current" | "not-ready" | "pagination-not-found" | "invalid-page" | "invalid-page-size";
+type PaginationChangeResult = PaginationState & {
+    changed: boolean;
+    reason: PaginationChangeReason;
+};
+type TabsState = {
+    activeTabId?: string;
+};
+type TabsChangeReason = "changed" | "already-active" | "not-ready" | "tabs-not-found" | "tab-not-found";
+type TabsChangeResult = TabsState & {
+    changed: boolean;
+    reason: TabsChangeReason;
+};
+type AccordionState = {
+    openItemIds: string[];
+    type: "single" | "multiple";
+};
+type AccordionChangeReason = "changed" | "already-current" | "not-ready" | "accordion-not-found" | "invalid-item";
+type AccordionChangeResult = AccordionState & {
+    changed: boolean;
+    reason: AccordionChangeReason;
+};
+type DialogState = {
+    open: boolean;
+};
+type DialogTransitionReason = "opened" | "closed" | "already-open" | "already-closed" | "not-ready" | "dialog-not-found";
+type DialogTransitionResult = {
+    changed: boolean;
+    open: boolean;
+    reason: DialogTransitionReason;
+};
+type DrawerState = {
+    open: boolean;
+};
+type DrawerTransitionReason = "opened" | "closed" | "already-open" | "already-closed" | "not-ready" | "drawer-not-found";
+type DrawerTransitionResult = {
+    changed: boolean;
+    open: boolean;
+    reason: DrawerTransitionReason;
+};
+type FormState = {
+    values: FormValues;
+    errors: FormErrors;
+};
+type DependencyMap = Map<string, Set<string>>;
+type FormEvent = {
+    type: "VALUE_CHANGED";
+    payload: {
+        name: string;
+        value: unknown;
+    };
+} | {
+    type: "STATE_UPDATED";
+};
+type RepeatMutationReason = "changed" | "not-ready" | "repeat-not-found" | "not-values-mode" | "min-items" | "max-items" | "index-out-of-range" | "invalid-target";
+type RepeatMutationResult = {
+    changed: boolean;
+    reason: RepeatMutationReason;
+    length: number;
+    index?: number;
+};
+
+type LoadingPropState = {
+    isLoading: boolean;
+    pendingActionIds?: readonly string[];
+    resourceInFlight?: readonly string[];
+};
+/**
+ * Resolves schema `props.loading` (boolean or `$state` / `$pending` binding)
+ * to a boolean for design-system components.
+ */
+declare function resolveLoadingProp(loading: unknown, state?: LoadingPropState): boolean;
+
+type FieldAdapterInput = {
+    schema: FieldNode;
+    field: {
+        value: unknown;
+        error?: string;
+        disabled?: boolean;
+        touched?: boolean;
+        touch: () => void;
+    };
+    setValue: (v: unknown) => void;
+    /** Engine snapshot for resolving `$state.*` / `$pending.*` loading bindings. */
+    state?: LoadingPropState;
+    /** Extra runtime loading (e.g. options source in flight). */
+    loading?: boolean;
+};
+type ActionAdapterInput = {
+    schema: ActionNode;
+    onClick: () => void;
+    loading?: boolean;
+    disabled?: boolean;
+    state?: LoadingPropState;
+};
+type LayoutAdapterInput<TChildren = unknown> = {
+    schema: LayoutNode;
+    children: TChildren;
+};
+type DisplayAdapterInput = {
+    schema: DisplayNode;
+    onClose?: () => void;
+    onAction?: () => void;
+    onClick?: () => void;
+    /** Runtime disabled (e.g. from `disabledWhen`). */
+    disabled?: boolean;
+};
+
+type OptionsConfig = {
+    source: string;
+    labelField: string;
+    valueField: string;
+} | {
+    items: {
+        label: string;
+        value: string | number;
+    }[];
+};
+type Listener<T> = (event: T) => void;
+type ValidationResult = {
+    valid: boolean;
+    error?: string;
+};
+type Validator<Rule extends ValidationRule = ValidationRule> = (value: unknown, rule: Rule) => ValidationResult;
+
+declare function compileSchema(node: Node): RuntimeNode;
+
+declare function createRuntimeNode(schema: Node): RuntimeNode;
+
+declare function traverseNode(node: RuntimeNode, callback: (node: RuntimeNode) => void): void;
+
+type BuiltinValidationType = Exclude<ValidationRule["type"], "invoke">;
+type ValidationRegistry = {
+    [Type in BuiltinValidationType]: Validator<Extract<ValidationRule, {
+        type: Type;
+    }>>;
+};
+declare const validationRegistry: ValidationRegistry;
+
+type ValidateFieldOptions = {
+    environment?: FormEngineEnvironment;
+    values?: Record<string, unknown>;
+    resources?: Record<string, unknown>;
+    row?: Record<string, unknown>;
+    item?: Record<string, unknown>;
+};
+declare function validateField(node: FieldNode, value: unknown, options?: ValidateFieldOptions): ValidationResult;
+
+declare function validateSchema(schema: FormSchema, values: Record<string, unknown>): {
+    valid: boolean;
+    errors: Record<string, string>;
+};
+
+type ConditionStateSnapshot = {
+    isLoading: boolean;
+    initializationStatus: InitializationStatus;
+    /** Same semantics as `FormEngine.isValid()` after the latest validation settle. */
+    isValid?: boolean;
+    pendingActionIds?: readonly string[];
+    resourceInFlight?: readonly string[];
+};
+
+declare function runConditionEngine(node: RuntimeNode, values: Record<string, unknown>, state?: ConditionStateSnapshot): void;
+
+declare function adaptField({ schema, field, setValue, state, loading, }: FieldAdapterInput): {
+    value: {};
+    onChange: (v: unknown) => void;
+    onBlur: () => void;
+    error: boolean | undefined;
+    disabled: boolean;
+    helperText: string | undefined;
+    loading: boolean;
+};
+
+declare function adaptLayout<TChildren>({ schema, children, }: LayoutAdapterInput<TChildren>): {
+    children: TChildren;
+    direction: "row" | "column";
+    className: unknown;
+    columns: unknown;
+    gap: unknown;
+    rowGap: unknown;
+    columnGap: unknown;
+    alignItems: unknown;
+    justifyContent: unknown;
+    flexWrap: unknown;
+    viewportClassName: unknown;
+    scrollAreaType: unknown;
+    dir: unknown;
+    scrollHideDelay: unknown;
+    ariaLabel: unknown;
+    badgeContent: unknown;
+    badgeShow: unknown;
+    badgeType: unknown;
+    badgeOffsetX: unknown;
+    badgeOffsetY: unknown;
+    cardDivider: unknown;
+};
+
+declare function adaptAction({ schema, onClick, loading, disabled, state, }: ActionAdapterInput): {
+    children: unknown;
+    onClick: () => void;
+    loading: boolean;
+    disabled: boolean;
+    variant: unknown;
+};
+
+declare function adaptDisplay({ schema, onClose, onAction, onClick, disabled, }: DisplayAdapterInput): {
+    disabled?: boolean | undefined;
+    onClick?: (() => void) | undefined;
+    onAction?: (() => void) | undefined;
+    onClose?: (() => void) | undefined;
+};
+
+/**
+ * Resolve a tag value mapping by string key (table columns and Tag `from` + `map`).
+ */
+declare function resolveTagValueMapping(value: unknown, map: Record<string, TableTagValueMapping> | undefined): TableTagValueMapping | undefined;
+declare function tagMapKey(value: unknown): string | undefined;
+declare function formatTagSourceValue(value: unknown): string;
+
+export { type AccordionChangeReason, type AccordionChangeResult, type AccordionState, type ActionAdapterInput, type ActionContext, type ActionHandler, type ComputerHandler, DependencyGraph, type DependencyMap, type DialogState, type DialogTransitionReason, type DialogTransitionResult, type DisplayAdapterInput, type DrawerState, type DrawerTransitionReason, type DrawerTransitionResult, EventBus, type FieldAdapterInput, FormEngine, type FormEngineConfig, type FormEngineEnvironment, type FormEngineNotification, type FormEngineState, type FormErrors, type FormEvent, type FormSnapshot, type FormState, type FormValues, type InitializationStatus, type InvokeContext, type InvokeHandler, type LayoutAdapterInput, type Listener, type OptionsConfig, type PaginationChangeReason, type PaginationChangeResult, type PaginationState, type PipelineContext, type PredicateHandler, type RepeatMutationReason, type RepeatMutationResult, type RuntimeNode, type RuntimeNodeState, type RuntimeTree, type StepRunOptions, type StepperNavigationReason, type StepperNavigationResult, type StepperState, type TabsChangeReason, type TabsChangeResult, type TabsState, type ValidateFieldOptions, type ValidationResult, type Validator, type ValidatorHandler, adaptAction, adaptDisplay, adaptField, adaptLayout, compileSchema, conditions, createFormEngineEnvironment, createRuntimeNode, formatTagSourceValue, isThenable, resolveLoadingProp, resolveTagValueMapping, runConditionEngine, tagMapKey, traverseNode, validateField, validateSchema, validation, validationRegistry };