@dataverse-kit/form-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 khester
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @dataverse-kit/form-runtime
+
+Shared React runtime for Dynamics 365 form rendering. Mounted by the
+form-builder designer canvas, the live preview, and code generated for export
+targets (Web Resource, PCF, Static Web App, Standalone Grid Customizer PCF,
+PA Grid Control Customizer). All three paths render the same React tree, so
+what you see in the canvas is what users ship.
+
+## Entries
+
+| Entry | Purpose |
+|-------|---------|
+| `@dataverse-kit/form-runtime` | v8 default — `<FormRuntime>` rendered with Fluent UI v8 (`@fluentui/react`). The designer canvas always mounts this. |
+| `@dataverse-kit/form-runtime/v9` | v9 sibling — `<FormRuntime>` rendered with Fluent UI v9 (`@fluentui/react-components`). Used by generated v9-target projects. Canvas does **not** mount this (ROADMAP-locked). |
+| `@dataverse-kit/form-runtime/hooks` | FluentUI-agnostic hooks: `useSubgridData`, `useChartData`, `useLookupSearch`, `useFormState`, `useDirtyTracker`. |
+| `@dataverse-kit/form-runtime/utils` | `gridLayoutUtils` — shared by designer/preview/generator for dashboard-layout math. |
+| `@dataverse-kit/form-runtime/theme` | `FormThemeProvider` + `useFormTheme`. |
+
+## Dependencies
+
+Every consumed `@dataverse-kit/runtime` and `@dataverse-kit/api-service`
+import flows through this package **directly** — no re-exports, no wrappers.
+Per the dynamics-toolkit v1.0 migration preference (full eradication of
+duplicated logic, not wrapper delegation).
+
+| Peer dep | Why |
+|----------|-----|
+| `react` (`^16.14 || ^17 || ^18`) | Canvas PCF compatibility caps React at 16.14. |
+| `react-dom` | Same. |
+| `@fluentui/react` (`^8.115`) | v8 default entry. |
+| `@fluentui/react-components` (`^9`) | v9 entry (optional). |
+| `@dataverse-kit/runtime` (`^1`) | FetchXmlParser, ConditionEvaluator, DirtyTracker. |
+| `@dataverse-kit/api-service` (`^0.2`) | `IApiService`, `ServiceFactory`. |
+
+## Status
+
+**WYSIWYG-canvas refactor complete (2026-05-19).** Every editor
+surface — main canvas, callout editor, and live preview — and every
+generator-emitted host renders through `<FormRuntime>`. The legacy
+parallel rendering pipeline (`ControlRenderer.tsx`, `SectionBlock`,
+`CellBlock`, `CalloutPreview`, `MainFormPreview` etc.) is fully
+retired. ~6,000 LOC of duplicate rendering code deleted across the
+refactor; ~3,000 LOC of feature-parity runtime + tests added.
+
+### Phase summary
+
+| Phase | Outcome |
+|-------|---------|
+| Phase 1 | Extract this package (`@dataverse-kit/form-runtime`). `<FormRuntime>` dispatcher, 22 per-type v8 controls, capability boundary (`FormRuntimeContext`), instrumentation attrs, live-data hooks. |
+| Phase 2 (m1–m9) | Designer overlay layer (selection, drop zones, drag handles, inline rename, badges, context menu, affordances, empty state, column drops). m9 flipped the runtime canvas + overlay default-on. |
+| Legacy canvas deletion | 7 dead editor-side files removed (`TabBar`, `HeaderBlock`, `CommandBarBlock`, `DialogHeaderBlock`, `DialogButtonsBlock`, `PanelButtonsBlock`, `GridFormCanvas`) — ~1,700 LOC. |
+| Phase 3 (m1–m6) | Runtime gained parity for the legacy preview's features: SectionShell variant/dims/background/collapsible/labels, per-control callouts (`CalloutAnchor`/`CalloutShell`/`CalloutsProvider`), dialog/panel `FooterShell`, business-rule integration (`RuleStatesProvider`), header field summary flyout, tab-content slots (`TabContentSlotsProvider`). m6 deleted the legacy `MainFormPreview`/`DialogFormPreview`/`PanelFormPreview`/`CalloutFormPreview`/`GridFormPreview` paths and the `runtimeCanvasFlag` gate. |
+| Phase 4 | Callout editor moved to runtime (`CalloutEditCanvas` mounts `SectionShell` for section bodies + `CalloutShell` for the preview popup). Cascade deletion of `ControlRenderer.tsx` (2,971 LOC), `SectionBlock.tsx`, `CellBlock.tsx`, `CalloutPreview.tsx` — ~4,100 LOC. |
+
+### What this guarantees
+
+- **Single source of truth for rendering.** Every form / section /
+  cell / control render path runs through the shells in this
+  package. No parity-drift risk between editor canvas, preview, and
+  generated output.
+- **Designer overlay is feature-complete** for the runtime canvas
+  (Phase 2 m1–m8 features all active). Pivot section drops on the
+  overlay remain deferred — they need a `SectionShell` pivot-grouping
+  pass before they can wire in. Editor-side callout pivot grouping
+  works via the form-builder's `DraggablePivotBar`.
+- **Tests: 405 in form-runtime, 352 in form-builder, 1041 in
+  export-engine** — all green at the close of Phase 4.
+
+### Known deferred items (not blocking)
+
+- Pivot section drops on the runtime overlay (waits on
+  `SectionShell` pivot-grouping support).
+- Subgrid focused-view / card-list / grid-customizer variants stay
+  editor-inline pending follow-up.
+- Live Dataverse entity-image fetch + `PersonaPresence` for
+  systemuser lookups in the header flyout — would need a
+  `FormRuntimeCapabilities` extension. Initials render fine without
+  it.
+- The four hooks declared but not extracted in Phase 1
+  (`useFormState`, `useSubgridData`, `useChartData`,
+  `useLookupSearch`, `useDirtyTracker`) — the existing editor
+  versions are still in use.
+- Package.json `exports` map for `/v8` + `/types/*` subpaths
+  (works today via Vite alias; matters for the published-package
+  consumer).
+
+## Build
+
+```bash
+npm run typecheck   # tsc --noEmit + tests config
+npm run build       # tsup → dist/{index,v9,hooks,utils,theme}.{cjs,mjs,d.ts}
+npm run test        # vitest run (jsdom environment)
+```

package/dist/businessRules-U1_MBgyG.d.cts

@@ -0,0 +1,372 @@
+/**
+ * Business Rules Engine — Type Definitions
+ *
+ * Defines the complete type system for visual business rules:
+ * rule definitions, conditions, actions, variables, data sources,
+ * execution context, workflows, highlights, and canvas layout.
+ *
+ * Design principles:
+ * - FetchXML-style operator names (eq, gt, like) for Dynamics consultant familiarity
+ * - Discriminated unions with `kind` for exhaustive pattern matching on action configs
+ * - Record<string, unknown> for JSON-serializable state (not Map/Set)
+ * - Reuses existing FormDataSource for FetchXML data sources
+ */
+
+/** A complete business rule — stored at entity level, enforced at form level */
+interface BusinessRuleDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    /** Entity logical name (e.g., "stn_order", "account") */
+    entityLogicalName: string;
+    /** Where the rule runs */
+    scope: 'entity' | 'form' | 'global';
+    /** For form-scoped rules */
+    targetFormId?: string;
+    /** When the rule evaluates */
+    trigger: RuleTrigger;
+    /** Execution priority (lower = first) */
+    priority: number;
+    /** Active/inactive toggle */
+    enabled: boolean;
+    /** Rule-specific data sources (beyond form-level shared ones) */
+    dataSources: RuleDataSource[];
+    /** Variables computed from data sources, fields, or expressions */
+    variables: RuleVariable[];
+    /** The IF condition tree */
+    conditionTree: RuleConditionGroup;
+    /** Actions when condition is TRUE */
+    thenActions: RuleAction[];
+    /** Actions when condition is FALSE */
+    elseActions: RuleAction[];
+    /** Visual layout for SVG canvas (Phase 2b) */
+    canvas?: RuleCanvasLayout;
+    /** Metadata */
+    createdAt: string;
+    updatedAt: string;
+    createdBy?: string;
+}
+interface RuleTrigger {
+    type: 'onLoad' | 'onChange' | 'onSave' | 'manual';
+    /** For onChange: which fields trigger re-evaluation */
+    watchFields?: string[];
+    /** For manual: command/button id */
+    commandId?: string;
+}
+/** Event that triggers rule evaluation */
+interface TriggerEvent {
+    type: RuleTrigger['type'];
+    /** For onChange: which field changed */
+    fieldName?: string;
+}
+/** A group of conditions joined by AND/OR */
+interface RuleConditionGroup {
+    id: string;
+    logic: 'and' | 'or';
+    conditions: (RuleCondition | RuleConditionGroup)[];
+}
+/** A single condition that evaluates to true/false */
+interface RuleCondition {
+    id: string;
+    /** Left-hand side source */
+    source: 'field' | 'data-source' | 'calculated' | 'form-state';
+    /** Field logical name (when source = 'field' or 'form-state') */
+    fieldName?: string;
+    /** Comparison operator — matches FetchXML operator names */
+    operator: ConditionOperator;
+    /** Right-hand side literal value */
+    value?: ConditionValue;
+    /** Right-hand side is another field */
+    compareToField?: string;
+    /** Data source reference (when source = 'data-source') */
+    dataSourceId?: string;
+    dataSourceField?: string;
+    /** Expression string (when source = 'calculated') */
+    expression?: string;
+}
+/** Type guard: is this a condition group (has `logic`) or a leaf condition? */
+declare function isConditionGroup(c: RuleCondition | RuleConditionGroup): c is RuleConditionGroup;
+/** Operators match FetchXML names for consultant familiarity */
+type ConditionOperator = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' | 'like' | 'not-like' | 'begins-with' | 'ends-with' | 'null' | 'not-null' | 'between' | 'in' | 'not-in' | 'contain-values' | 'not-contain-values' | 'changed' | 'not-changed';
+type ConditionValue = string | number | boolean | null | string[] | [unknown, unknown];
+interface RuleAction {
+    id: string;
+    type: RuleActionType;
+    /** Primary target — always synced to targets[0] */
+    target: ActionTarget;
+    /** Multi-target list (when action applies to multiple fields/sections/tabs) */
+    targets?: ActionTarget[];
+    /** Optional label for the target group (e.g., "Meter Fields") */
+    groupName?: string;
+    config: ActionConfig;
+    /** Execution order within the branch */
+    order: number;
+}
+/** Returns targets array, falling back to [action.target] for legacy data */
+declare function getActionTargets(action: RuleAction): ActionTarget[];
+type RuleActionType = 'setFieldValue' | 'setDefaultValue' | 'setVisibility' | 'setLockState' | 'setRequired' | 'showErrorMessage' | 'showRecommendation' | 'setHighlight' | 'setSectionVisibility' | 'setTabVisibility' | 'setSectionLockState' | 'setFormReadOnly' | 'setFormNotification' | 'preventSave' | 'setButtonVisibility' | 'setButtonEnabled' | 'blockCreate' | 'blockUpdate' | 'blockDelete' | 'callCustomAction' | 'callCustomApi' | 'triggerWorkflow' | 'navigateToForm' | 'openDialog';
+interface ActionTarget {
+    type: 'field' | 'section' | 'tab' | 'form' | 'button' | 'control';
+    /** Control name, section id, tab id, or form id */
+    id: string;
+    displayName?: string;
+}
+type ActionConfig = SetFieldValueConfig | SetDefaultValueConfig | SetVisibilityConfig | SetLockConfig | SetRequiredConfig | ShowMessageConfig | SetHighlightConfig | SetFormReadOnlyConfig | SetFormNotificationConfig | PreventSaveConfig | CrudBlockConfig | CallApiConfig | TriggerWorkflowConfig | NavigateToFormConfig | OpenDialogConfig;
+interface SetFieldValueConfig {
+    kind: 'setFieldValue';
+    source: 'constant' | 'variable' | 'expression' | 'field';
+    value: unknown;
+}
+interface SetDefaultValueConfig {
+    kind: 'setDefaultValue';
+    source: 'constant' | 'variable' | 'expression' | 'field';
+    value: unknown;
+    /** Only apply if field is currently empty */
+    onlyIfEmpty: boolean;
+}
+interface SetVisibilityConfig {
+    kind: 'setVisibility';
+    visible: boolean;
+}
+interface SetLockConfig {
+    kind: 'setLock';
+    locked: boolean;
+}
+interface SetRequiredConfig {
+    kind: 'setRequired';
+    level: 'required' | 'recommended' | 'none';
+}
+interface ShowMessageConfig {
+    kind: 'showMessage';
+    messageType: 'error' | 'warning' | 'info' | 'recommendation';
+    message: string;
+    /** Supports {{variableName}} interpolation */
+    interpolateVariables: boolean;
+}
+interface SetHighlightConfig {
+    kind: 'setHighlight';
+    /** Hex color (e.g., "#63d868") */
+    color: string;
+    /** Higher priority wins when multiple rules match */
+    priority: number;
+}
+interface SetFormReadOnlyConfig {
+    kind: 'setFormReadOnly';
+    readOnly: boolean;
+}
+interface SetFormNotificationConfig {
+    kind: 'setFormNotification';
+    messageType: 'error' | 'warning' | 'info';
+    message: string;
+    interpolateVariables: boolean;
+}
+interface PreventSaveConfig {
+    kind: 'preventSave';
+    message: string;
+}
+interface CrudBlockConfig {
+    kind: 'crudBlock';
+    operation: 'create' | 'update' | 'delete';
+    message?: string;
+}
+interface CallApiConfig {
+    kind: 'callApi';
+    dataSourceId: string;
+    resultVariableId?: string;
+    onSuccessActions?: RuleAction[];
+    onFailureActions?: RuleAction[];
+}
+interface TriggerWorkflowConfig {
+    kind: 'triggerWorkflow';
+    workflowId: string;
+}
+interface NavigateToFormConfig {
+    kind: 'navigateToForm';
+    formId: string;
+    /** Pass field values to the target form */
+    parameterMapping?: Record<string, string>;
+}
+interface OpenDialogConfig {
+    kind: 'openDialog';
+    formId: string;
+    width?: number;
+    height?: number;
+}
+interface RuleVariable {
+    id: string;
+    name: string;
+    displayName: string;
+    type: 'string' | 'number' | 'boolean' | 'datetime' | 'lookup' | 'optionset';
+    source: {
+        kind: 'field';
+        fieldName: string;
+    } | {
+        kind: 'dataSource';
+        dataSourceId: string;
+        outputField: string;
+    } | {
+        kind: 'expression';
+        expression: string;
+    } | {
+        kind: 'constant';
+        value: unknown;
+    } | {
+        kind: 'context';
+        contextPath: string;
+    };
+    defaultValue?: unknown;
+}
+/**
+ * Rule data source — wraps existing FormDataSource with caching,
+ * or defines a Custom Action / API source.
+ */
+interface RuleDataSource {
+    id: string;
+    name: string;
+    displayName: string;
+    type: 'fetchXml' | 'aggregateFetchXml' | 'customAction' | 'customApi';
+    /**
+     * For fetchXml/aggregateFetchXml: reference an existing FormDataSource by id.
+     * Avoids duplicating FetchXML definitions.
+     */
+    formDataSourceId?: string;
+    /**
+     * Inline FetchXML when not referencing a shared FormDataSource.
+     * Supports {{fieldName}} placeholders.
+     */
+    fetchXml?: string;
+    /** Custom Action / API configuration (Phase 3) */
+    apiConfig?: {
+        actionName: string;
+        inputParameters: ApiParameter[];
+        outputParameters: ApiParameter[];
+    };
+    /** Caching strategy */
+    cache: {
+        enabled: boolean;
+        ttlSeconds: number;
+        invalidateOn?: string[];
+    };
+}
+interface ApiParameter {
+    name: string;
+    type: string;
+    source: 'field' | 'variable' | 'constant';
+    value: string;
+}
+/** Full runtime context — plain objects for JSON-serializable portions */
+interface RuleExecutionContext {
+    /** Current form field values */
+    formData: Record<string, unknown>;
+    /** Original values at load time (for dirty detection) */
+    originalData: Record<string, unknown>;
+    /** Fields changed since load (runtime only, not serialized) */
+    dirtyFields: Set<string>;
+    /** Resolved data source results */
+    dataSourceResults: Record<string, unknown>;
+    /** Resolved variable values */
+    variableValues: Record<string, unknown>;
+    /** Form-level state */
+    formState: {
+        isNew: boolean;
+        isDirty: boolean;
+        isValid: boolean;
+        isSaving: boolean;
+        formId: string;
+        entityLogicalName: string;
+        recordId?: string;
+        lastSaved?: string;
+    };
+    /** Custom Action results (Phase 3) */
+    customActionResults: Record<string, unknown>;
+}
+interface RuleExecutionResult {
+    ruleId: string;
+    ruleName: string;
+    conditionMet: boolean;
+    actionsExecuted: ActionResult[];
+    error?: string;
+    durationMs: number;
+}
+interface ActionResult {
+    actionId: string;
+    actionType: RuleActionType;
+    targetId: string;
+    success: boolean;
+    error?: string;
+}
+interface FieldState {
+    visible: boolean;
+    locked: boolean;
+    required: 'required' | 'recommended' | 'none';
+    errorMessage?: string;
+    warningMessage?: string;
+    recommendationMessage?: string;
+    highlightColor?: string;
+}
+interface SectionState {
+    visible: boolean;
+    locked: boolean;
+}
+interface TabState {
+    visible: boolean;
+}
+interface FormNotification {
+    id: string;
+    type: 'error' | 'warning' | 'info';
+    message: string;
+    ruleId: string;
+}
+interface WorkflowDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    trigger: 'on-save' | 'on-field-change' | 'on-load' | 'manual';
+    triggerField?: string;
+    steps: WorkflowStep[];
+}
+interface WorkflowStep {
+    id: string;
+    type: 'validate' | 'save' | 'call-action' | 'refresh' | 'evaluate-rules' | 'set-field';
+    actionName?: string;
+    fieldName?: string;
+    fieldValue?: unknown;
+    onError: 'stop' | 'continue' | 'rollback';
+}
+interface WorkflowResult {
+    workflowId: string;
+    success: boolean;
+    steps: WorkflowStepResult[];
+}
+interface WorkflowStepResult {
+    stepId: string;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+}
+interface RuleCanvasLayout {
+    nodes: CanvasNode[];
+    connections: CanvasConnection[];
+    zoom: number;
+    panX: number;
+    panY: number;
+}
+interface CanvasNode {
+    id: string;
+    type: 'condition' | 'action' | 'branch';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface CanvasConnection {
+    fromNodeId: string;
+    toNodeId: string;
+    type: 'then' | 'else' | 'sequence';
+}
+/** Creates a minimal empty rule definition */
+declare function createDefaultBusinessRule(entityLogicalName: string, name?: string): BusinessRuleDefinition;
+/** Creates a default field state (visible, unlocked, not required) */
+declare function createDefaultFieldState(): FieldState;
+
+export { type ActionConfig as A, type BusinessRuleDefinition as B, type CallApiConfig as C, type ShowMessageConfig as D, type TriggerEvent as E, type FieldState as F, type TriggerWorkflowConfig as G, type WorkflowResult as H, type WorkflowStep as I, type WorkflowStepResult as J, createDefaultBusinessRule as K, createDefaultFieldState as L, getActionTargets as M, type NavigateToFormConfig as N, type OpenDialogConfig as O, type PreventSaveConfig as P, isConditionGroup as Q, type RuleAction as R, type SectionState as S, type TabState as T, type WorkflowDefinition as W, type ActionResult as a, type ActionTarget as b, type ApiParameter as c, type CanvasConnection as d, type CanvasNode as e, type ConditionOperator as f, type ConditionValue as g, type CrudBlockConfig as h, type FormNotification as i, type RuleActionType as j, type RuleCanvasLayout as k, type RuleCondition as l, type RuleConditionGroup as m, type RuleDataSource as n, type RuleExecutionContext as o, type RuleExecutionResult as p, type RuleTrigger as q, type RuleVariable as r, type SetDefaultValueConfig as s, type SetFieldValueConfig as t, type SetFormNotificationConfig as u, type SetFormReadOnlyConfig as v, type SetHighlightConfig as w, type SetLockConfig as x, type SetRequiredConfig as y, type SetVisibilityConfig as z };