@dataverse-kit/form-runtime 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,410 @@
+import { ControlPartProps } from './v8.js';
+export { ButtonControl, ChartBranch, ChartBranchProps, ChartRenderer, ChartRendererEntry, ChartRendererProps, CheckboxControl, ChoiceGroupBranch, ChoiceGroupControl, ChoiceGroupControlProps, ComboBoxControl, DateControl, DropdownControl, EmojiRating, EmojiRatingProps, FocusedCardData, FocusedCardRow, FocusedViewMasterDetailPreview, FocusedViewMasterDetailPreviewProps, FormLinkControl, GridMockDataGenerator, LabelControl, LookupBranch, LookupControl, LookupControlProps, LookupSearchCapability, NestedRecordsCallout, NestedRecordsCalloutProps, NestedRecordsSidePanel, NestedRecordsSidePanelProps, NestedRecordsTrigger, NestedRecordsTriggerProps, NumberControl, PersonaControl, RatingControl, SliderControl, SpacerControl, SpinButtonControl, SubgridBranch, SubgridBranchProps, TextControl, TextFieldWithFormat, TextFieldWithFormatProps, TextareaControl, TimelineControl, ToggleControl, UnknownControl, WebResourceBranch, WebResourceRenderer, WebResourceRendererProps, isChartControlType, isDisabled, isEmbeddedEntityBrowser, lookupEntityHelpers, renderGridCell } from './v8.js';
+import { O as FormDefinition, q as CommandBarItem, F as DialogActionButton, x as ControlDefinition, U as FormSection, h as CalloutDefinition, i as CalloutDirectionalHint, l as CalloutTrigger } from './control-DaXBm-52.js';
+import { F as FieldState, S as SectionState, T as TabState } from './businessRules-U1_MBgyG.js';
+import React from 'react';
+export { CalloutsProvider, CalloutsProviderProps, FormRuntimeProvider, FormRuntimeProviderProps, RuleStatesContextValue, RuleStatesProvider, RuleStatesProviderProps, TabContentSlots, TabContentSlotsProvider, TabContentSlotsProviderProps, useCallout, useFieldState, useFormRuntimeContext, useOptionalFormRuntimeContext, useRuleStates, useSectionState, useTabContentSlots, useTabState } from './context.js';
+export { UseLiveDataResult, useLiveData } from './hooks.js';
+import { DirectionalHint } from '@fluentui/react';
+import './gridCustomizer-C0V9FAE_.js';
+import './runtime-capabilities-Brfc7loJ.js';
+import './theme-BfeZIxmZ.js';
+
+/**
+ * Designer-mode instrumentation helpers.
+ *
+ * When `<FormRuntime instrumentation="designer">` is mounted, every
+ * structural element (tab, section, row, cell, control, header,
+ * command-bar item, grid item) gets `data-element-id`,
+ * `data-element-type`, and `data-element-path` attributes so the
+ * designer overlay (Phase 2) can locate, measure, and decorate them
+ * with selection chrome, drop zones, badges, etc.
+ *
+ * The helpers return plain attribute objects rather than React props
+ * so they're trivial to spread onto host elements without importing
+ * `@types/react` into the surface (matches the same pattern used by
+ * `gridLayoutUtils.GridPositionStyle`).
+ */
+type InstrumentationMode = 'designer' | 'off';
+type ElementType = 'header' | 'commandBarItem' | 'tab' | 'column' | 'section' | 'row' | 'cell' | 'control' | 'gridItem' | 'bpf';
+interface InstrumentationAttrs {
+    'data-element-id'?: string;
+    'data-element-type'?: ElementType;
+    'data-element-path'?: string;
+}
+/**
+ * Emit instrumentation attributes for a structural element. When the
+ * runtime isn't in designer mode, returns an empty object so the
+ * spread is a no-op and no extra DOM attributes are emitted in
+ * deployed runtimes.
+ */
+declare function instrumentAttrs(mode: InstrumentationMode, id: string, type: ElementType, path?: string): InstrumentationAttrs;
+/** Path helpers — string composition so paths read top-down. */
+declare const paths: {
+    header(): string;
+    commandBarItem(itemId: string): string;
+    tab(tabId: string): string;
+    column(tabPath: string, colIdx: number): string;
+    section(parentPath: string, sectionId: string): string;
+    row(sectionPath: string, rowId: string): string;
+    cell(rowPath: string, cellId: string): string;
+    control(cellPath: string, controlName: string): string;
+    gridItem(sectionId: string): string;
+    callout(parentPath: string, calloutId: string): string;
+};
+
+interface FormRuntimeProps {
+    /** The form definition to render (tabs, sections, controls, etc.). */
+    form: FormDefinition;
+    /**
+     * Initial record values. Keyed by `dataBinding.attributeLogicalName`
+     * (and the `…@OData.Community.Display.V1.FormattedValue` annotations
+     * Dataverse returns). The dispatcher reads from this when a control
+     * has a binding and no controlled override.
+     */
+    recordData?: Record<string, unknown> | null;
+    /**
+     * `false` disables every input control + reveals the legacy
+     * "designer affordances" inside per-type files (e.g. spacer/label
+     * placeholder outlines). Default `true`.
+     */
+    interactive?: boolean;
+    /**
+     * `'designer'` emits `data-element-id` / `data-element-type` /
+     * `data-element-path` attributes on every structural element so the
+     * Phase 2 designer overlay can locate them. Default `'off'`.
+     */
+    instrumentation?: InstrumentationMode;
+    /**
+     * Optional click handler for command-bar items. The runtime stays
+     * neutral on what an item does — the host decides.
+     */
+    onCommandClick?: (item: CommandBarItem) => void;
+    /** Optional button-click handler propagated into `DispatchedControl`. */
+    onButtonClick?: (action: unknown) => void;
+    /**
+     * Optional value-change handler. When omitted, edits are tracked
+     * internally via the runtime's local `useFormState` so the user can
+     * still interact with controls. Hosts that own form state pass
+     * `onChange` to take over.
+     */
+    onChange?: (controlName: string, next: unknown) => void;
+    /**
+     * Optional dialog/panel footer action-button click handler. Phase 3
+     * m3 — the runtime emits the buttons but stays neutral on actions;
+     * the host (preview wrapper or generated app) decides what 'close'
+     * / 'save' / 'cancel' etc. do.
+     */
+    onActionButtonClick?: (button: DialogActionButton) => void;
+    /**
+     * Optional business-rule evaluation outputs. The runtime consumes
+     * these to gate field / section / tab visibility and merge
+     * readOnly + required overrides into individual controls. Phase 3
+     * m4. The runtime does NOT own the rule engine — pass the maps
+     * from the host's rule-execution store (form-builder uses
+     * useRuleExecutionStore; generated apps pass equivalent maps).
+     */
+    ruleStates?: {
+        fieldStates?: Record<string, FieldState>;
+        sectionStates?: Record<string, SectionState>;
+        tabStates?: Record<string, TabState>;
+    };
+}
+declare const FormRuntime: React.FC<FormRuntimeProps>;
+
+/**
+ * Control dispatcher — maps a `ControlDefinition.type` to the
+ * per-type renderer extracted in Phase 6.5f (Task 17). The dispatcher
+ * is the single place that knows the full control taxonomy; the
+ * surrounding `<FormRuntime>` shell pulls value/effectiveValue
+ * computation up here so per-type files stay focused on UI.
+ *
+ * Routes legacy + chart types:
+ *  - `phone` / `email` / `url` → `UnknownControl` (legacy fallback
+ *    handles them via the `LEGACY_FORMAT_MAP`)
+ *  - 12 chart types          → `ChartBranch`
+ *  - other type literals     → the matching per-type file
+ *  - anything else           → `UnknownControl`
+ */
+
+type ControlComponent = React.FC<ControlPartProps>;
+/**
+ * Resolve which per-type component should render `controlType`. Returns
+ * `UnknownControl` for any type not in the registry (covers the legacy
+ * phone/email/url path inside UnknownControl plus genuinely unknown
+ * future types). Chart types route to `ChartBranch`.
+ */
+declare function resolveControlComponent(controlType: string): ControlComponent;
+/**
+ * Inputs the dispatcher needs from the surrounding shell to compute
+ * `ControlPartProps` for the resolved component.
+ */
+interface DispatchControlInputs {
+    control: ControlDefinition;
+    /** Controlled value override (takes precedence over record-bound value). */
+    controlledValue?: unknown;
+    /** Bound record (live or mock). When supplied, looked up by attribute name. */
+    recordData?: Record<string, unknown> | null;
+    /** When false, controls disable and the legacy designMode affordances show. */
+    interactive: boolean;
+    /** Bubbles up edits — same shape every per-type file expects. */
+    onChange?: (next: unknown) => void;
+    /** Bubbles up button-click actions (used by ButtonControl + FormLinkControl). */
+    onButtonClick?: (action: unknown) => void;
+}
+/**
+ * Build the `ControlPartProps` the resolved per-type file expects.
+ * The shell calls this once per cell so per-type files don't each
+ * repeat the value-precedence rule.
+ */
+declare function buildControlPartProps(inputs: DispatchControlInputs): ControlPartProps;
+/**
+ * Stateless dispatch component. Resolves the per-type renderer for
+ * `control.type` and forwards the computed `ControlPartProps`.
+ * Wrap with `<FormRuntime>` to get value resolution + instrumentation;
+ * tests can use this directly with hand-rolled props.
+ */
+declare const DispatchedControl: React.FC<DispatchControlInputs>;
+
+/**
+ * HeaderShell — main-form top banner (title, subtitle, 0–4 cell slots).
+ *
+ * Two rendering modes governed by `form.settings.headerDisplayMode`:
+ *
+ *   - `'inline'` (or absent — the runtime's current default): cells
+ *     render in a CSS grid alongside the title. Each cell dispatches
+ *     through the runtime's normal control dispatcher.
+ *
+ *   - `'flyout'` (Phase 3 m5): cells render as compact label/value
+ *     summary tiles separated by vertical bars, with a chevron toggle
+ *     on the right. Clicking the chevron opens a Callout containing
+ *     the same cells as editable controls — matches the legacy
+ *     `HeaderFieldSummaryPreview` + flyout in
+ *     apps/form-builder/.../form-preview/FormPreview.tsx.
+ *
+ * The legacy preview also fetched lookup entity images and presence
+ * for systemuser lookups via direct Dataverse calls. That belongs in
+ * a FormRuntimeCapabilities enhancement, not the shell itself — for
+ * now the persona renders with initials only (the universal baseline).
+ */
+
+interface HeaderShellProps {
+    form: FormDefinition;
+    recordData?: Record<string, unknown> | null;
+    interactive: boolean;
+    instrumentation: InstrumentationMode;
+    /**
+     * Pass-through so the dispatcher's button-click handler can route
+     * up to the host (open record, run action, etc.).
+     */
+    onButtonClick?: DispatchControlInputs['onButtonClick'];
+}
+declare const HeaderShell: React.FC<HeaderShellProps>;
+
+/**
+ * CommandBarShell — top command bar for main forms.
+ *
+ * Renders the configured `FormDefinition.commandBar` items as Fluent UI
+ * v8 CommandBar buttons. Overflow / far positions are honored via
+ * Fluent's `overflowItems` and `farItems`. Click handlers route up
+ * through `onCommandClick` so the host decides what to do (save,
+ * navigate, run action).
+ */
+
+interface CommandBarShellProps {
+    form: FormDefinition;
+    interactive: boolean;
+    instrumentation: InstrumentationMode;
+    onCommandClick?: (item: CommandBarItem) => void;
+}
+declare const CommandBarShell: React.FC<CommandBarShellProps>;
+
+/**
+ * BpfShell — Business Process Flow progress indicator.
+ *
+ * Scaffolded for Phase 1. The BPF designer + progress indicators live
+ * in the form-builder app today; this shell renders a minimal stage
+ * strip so the runtime tree has somewhere to drop the BPF in
+ * `<FormRuntime>`. The full pivot through stages / steps + the chevron
+ * / circle / minimal variants land in a follow-up.
+ *
+ * When the form has no `bpfId`, the shell renders nothing.
+ */
+
+interface BpfShellProps {
+    form: FormDefinition;
+    instrumentation: InstrumentationMode;
+}
+declare const BpfShell: React.FC<BpfShellProps>;
+
+/**
+ * TabsShell — tabbed-form layout. Renders the tab strip plus the
+ * sections of the active main tab. Related / audit tabs render a
+ * placeholder until those surfaces fully migrate to runtime (Phase 1+
+ * follow-up).
+ */
+
+interface TabsShellProps {
+    form: FormDefinition;
+    recordData?: Record<string, unknown> | null;
+    interactive: boolean;
+    instrumentation: InstrumentationMode;
+    onCellValueChange?: (controlName: string, next: unknown) => void;
+    onButtonClick?: DispatchControlInputs['onButtonClick'];
+}
+declare const TabsShell: React.FC<TabsShellProps>;
+
+/**
+ * GridShell — dashboard-layout form. Picks the grid-mode host
+ * (first main tab's sections, or flat `form.sections`) and places
+ * each section onto a CSS Grid using `gridLayoutUtils.gridPositionStyle`.
+ */
+
+interface GridShellProps {
+    form: FormDefinition;
+    recordData?: Record<string, unknown> | null;
+    interactive: boolean;
+    instrumentation: InstrumentationMode;
+    onCellValueChange?: (controlName: string, next: unknown) => void;
+    onButtonClick?: DispatchControlInputs['onButtonClick'];
+}
+declare const GridShell: React.FC<GridShellProps>;
+
+/**
+ * SectionShell — renders a single FormSection's rows + cells + controls.
+ *
+ * Phase 3 m1 grew this file to honor the FormSection fields that the
+ * legacy `SectionPreview` (apps/form-builder/.../FormPreview.tsx) was
+ * already rendering and the runtime canvas had been ignoring:
+ *   - `variant: 'placeholder'` → render an empty spacer
+ *   - `minHeight` / `widthPercent` → section dimensions
+ *   - `background` (color / image / gradient) → per-section override
+ *   - `collapsible` → header click toggles expanded state
+ *   - `collapseHidden` → skip rows where every cell's control is hidden
+ *   - `labelPosition` / `labelWidth` / `wrapLabel` → section-level
+ *     defaults that cascade into controls without explicit values
+ *   - control-level `hidden` → cell becomes visibility-hidden
+ *
+ * These were preview-only features in the legacy code. Lifting them
+ * into the runtime makes both the editor canvas AND the preview
+ * surface render identically — the goal of the WYSIWYG-canvas refactor.
+ */
+
+interface SectionShellProps {
+    section: FormSection;
+    parentPath: string;
+    recordData?: Record<string, unknown> | null;
+    interactive: boolean;
+    instrumentation: InstrumentationMode;
+    onCellValueChange?: (controlName: string, next: unknown) => void;
+    onButtonClick?: DispatchControlInputs['onButtonClick'];
+}
+declare const SectionShell: React.FC<SectionShellProps>;
+
+/**
+ * FooterShell — dialog/panel footer with action buttons.
+ *
+ * Phase 3 m3. Replaces the legacy DialogButtonsBlock /
+ * PanelButtonsBlock and the `renderDialogButton` helpers from
+ * apps/form-builder/.../form-preview/FormPreview.tsx.
+ *
+ * Reads buttons from `form.settings.dialogButtons` (form.type=dialog)
+ * or `form.settings.panelButtons` (form.type=panel). When neither is
+ * configured, falls back to a single Close button — same default as
+ * the legacy `createDefaultDialogButtons()`.
+ *
+ * Buttons split into a left group and a right group; alignment of
+ * the whole footer is controlled by `dialogButtonAlignment` /
+ * `panelButtonAlignment` ('left' | 'center' | 'right'; default 'right').
+ *
+ * Click actions are not dispatched here. The legacy `renderDialogButton`
+ * also doesn't wire onClick — actions get processed by the host. The
+ * runtime exposes `onActionButtonClick` so callers (preview, host)
+ * can opt in. Business-rules-driven button state lands in m4.
+ */
+
+interface FooterShellProps {
+    form: FormDefinition;
+    /** Optional click callback. When unset, buttons render as no-ops. */
+    onActionButtonClick?: (button: DialogActionButton) => void;
+}
+declare const FooterShell: React.FC<FooterShellProps>;
+
+/**
+ * CalloutShell — renders a Fluent UI Callout anchored at `target`,
+ * populated by the runtime's SectionShell so its content honors all
+ * the same FormSection rendering rules as the rest of the form.
+ *
+ * Phase 3 milestone 2. Replaces the legacy `CalloutPreview` /
+ * `CalloutControlWrapper` pair in
+ * `apps/form-builder/src/components/form-preview/CalloutPreview.tsx`.
+ *
+ * Trigger handling, open/close state, and the activation surface live
+ * in {@link CalloutAnchor}; this file only paints the open callout.
+ */
+
+/** Map our string-based hint enum into Fluent's runtime enum. */
+declare function mapCalloutDirectionalHint(hint?: CalloutDirectionalHint): DirectionalHint;
+interface CalloutShellProps {
+    callout: CalloutDefinition;
+    target: HTMLElement;
+    onDismiss: () => void;
+    /** Called when the cursor enters the callout content — used by the
+     * hover trigger in {@link CalloutAnchor} to cancel a pending dismiss
+     * so the user can move from the anchor onto the callout without it
+     * disappearing under them. */
+    onContentMouseEnter?: () => void;
+    /** Called when the cursor leaves the callout content. */
+    onContentMouseLeave?: () => void;
+    /** Parent path used to nest callout sections under their host control
+     * for instrumentation. The legacy preview was uninstrumented; the
+     * runtime path keeps the same surface but with element-ids so the
+     * designer overlay can target callout sections too. */
+    parentPath: string;
+    recordData?: Record<string, unknown> | null;
+    interactive: boolean;
+    instrumentation: InstrumentationMode;
+    onCellValueChange?: (controlName: string, next: unknown) => void;
+    onButtonClick?: DispatchControlInputs['onButtonClick'];
+}
+declare const CalloutShell: React.FC<CalloutShellProps>;
+
+/**
+ * CalloutAnchor — wraps a control with click / hover / icon-click
+ * trigger handlers that open a {@link CalloutShell} anchored to the
+ * control's DOM node.
+ *
+ * Phase 3 milestone 2 — replaces `CalloutControlWrapper` +
+ * `CalloutIndicator` from
+ * `apps/form-builder/src/components/form-preview/CalloutPreview.tsx`.
+ *
+ * State is local to each anchor (each control with a callout owns its
+ * own open/close state). The legacy preview centralized state in
+ * FormPreview, but FluentCallout's dismiss-on-click-outside makes
+ * "only one open at a time" the natural behavior anyway — and the
+ * local model avoids prop-drilling activation handlers through the
+ * shell hierarchy.
+ *
+ * Hover bridging: when the trigger is `hover`, a 300ms timer governs
+ * dismissal so the user can move from the anchor onto the callout
+ * content without losing it. CalloutShell calls back into this
+ * component via onContentMouse* to cancel / restart the timer.
+ */
+
+interface CalloutAnchorProps {
+    callout: CalloutDefinition;
+    /** Optional per-attachment override of the callout's default trigger. */
+    triggerOverride?: CalloutTrigger;
+    children: React.ReactNode;
+    /** Parent path threaded through to {@link CalloutShell} for nested
+     * section instrumentation. */
+    parentPath: string;
+    recordData?: Record<string, unknown> | null;
+    interactive: boolean;
+    instrumentation: InstrumentationMode;
+    onCellValueChange?: (controlName: string, next: unknown) => void;
+    onButtonClick?: DispatchControlInputs['onButtonClick'];
+}
+declare const CalloutAnchor: React.FC<CalloutAnchorProps>;
+
+export { BpfShell, type BpfShellProps, CalloutAnchor, type CalloutAnchorProps, CalloutShell, type CalloutShellProps, CommandBarShell, type CommandBarShellProps, ControlPartProps, type DispatchControlInputs, DispatchedControl, type ElementType, FooterShell, type FooterShellProps, FormRuntime, type FormRuntimeProps, GridShell, type GridShellProps, HeaderShell, type HeaderShellProps, type InstrumentationAttrs, type InstrumentationMode, SectionShell, type SectionShellProps, TabsShell, type TabsShellProps, buildControlPartProps, instrumentAttrs, paths as instrumentationPaths, mapCalloutDirectionalHint, resolveControlComponent };