@dataverse-kit/form-runtime 0.1.0

package/dist/control-DFOg_pc_.d.cts

@@ -0,0 +1,1027 @@
+import { b as FormThemeSettings, B as BackgroundConfig } from './theme-BfeZIxmZ.cjs';
+
+/**
+ * Navigation types for inter-form communication in the form builder.
+ * Supports opening dialogs, panels, and callouts from buttons/commands.
+ */
+/** Types of navigation actions available */
+type NavigationActionType = 'openDialog' | 'openPanel' | 'openCallout' | 'closeForm';
+/** Source for parameter values */
+type ParameterSourceType = 'field' | 'constant' | 'context';
+/** Position for panel overlays */
+type PanelPosition = 'left' | 'right';
+/**
+ * Maps a source value to a target form parameter.
+ * Used to pass data from one form to another.
+ */
+interface ParameterMapping {
+    /** Name of the parameter on the target form */
+    targetParameter: string;
+    /** Where to get the value from */
+    source: ParameterSourceType;
+    /**
+     * Value based on source type:
+     * - 'field': field logical name from source form
+     * - 'constant': literal value
+     * - 'context': context variable name (e.g., 'recordId', 'entityName')
+     */
+    value: string;
+}
+/** Size configuration for overlay forms */
+interface NavigationSizeConfig {
+    /** Width in pixels */
+    width?: number;
+    /** Height in pixels (primarily for dialogs) */
+    height?: number;
+    /** Position for panels */
+    position?: PanelPosition;
+}
+/** Configuration for what happens when the target form closes */
+interface NavigationOnCloseConfig {
+    /** Whether to refresh data in the source form after close */
+    refreshData?: boolean;
+    /** Callback action name to execute (for custom handling) */
+    callbackAction?: string;
+}
+/**
+ * Navigation action configuration.
+ * Defines how to open another form from a button or command.
+ */
+interface NavigationAction {
+    /** Unique identifier for this action */
+    id: string;
+    /** Type of navigation (what kind of overlay to use) */
+    type: NavigationActionType;
+    /** ID of the form to open */
+    targetFormId: string;
+    /** Parameter mappings to pass data to the target form */
+    parameterMappings?: ParameterMapping[];
+    /** Size and position configuration */
+    sizeConfig?: NavigationSizeConfig;
+    /** Configuration for when the target form closes */
+    onClose?: NavigationOnCloseConfig;
+}
+/**
+ * Parameter definition for form input parameters.
+ * Defines what parameters a form accepts when opened from navigation.
+ */
+interface FormParameter {
+    /** Unique identifier */
+    id: string;
+    /** Internal name (used in code/mappings) */
+    name: string;
+    /** User-friendly display name */
+    displayName: string;
+    /** Data type of the parameter */
+    type: 'string' | 'number' | 'boolean' | 'lookup' | 'date' | 'record';
+    /** Whether the parameter is required */
+    required: boolean;
+    /** Default value if not provided */
+    defaultValue?: unknown;
+    /** Description for documentation */
+    description?: string;
+}
+/** Entry in the navigation stack (runtime state) */
+interface NavigationStackEntry {
+    /** ID of the form that was opened */
+    formId: string;
+    /** Type of the form */
+    formType: 'dialog' | 'panel' | 'callout';
+    /** Parameters passed to the form */
+    parameters: Record<string, unknown>;
+    /** ID of the source form that opened this one */
+    sourceFormId: string;
+    /** Size configuration used */
+    sizeConfig?: NavigationSizeConfig;
+    /** On-close configuration */
+    onClose?: NavigationOnCloseConfig;
+}
+/** Result returned when a navigated form closes */
+interface NavigationCloseResult {
+    /** Whether the form was submitted (vs cancelled) */
+    submitted: boolean;
+    /** Return values from the form */
+    returnValues?: Record<string, unknown>;
+}
+/** Context available to a form opened via navigation */
+interface NavigationContext {
+    /** Parameters passed to this form */
+    parameters: Record<string, unknown>;
+    /** ID of the form that opened this one */
+    sourceFormId: string | null;
+    /** Function to close the current form */
+    closeForm: (result?: NavigationCloseResult) => void;
+    /** Whether this form was opened via navigation (vs direct) */
+    isNavigated: boolean;
+}
+
+type FormType = 'main' | 'dialog' | 'panel' | 'callout';
+/**
+ * Layout mode for a form. Tabbed forms use the classic tab/section/row/cell
+ * flow; grid forms place sections as tiles on a CSS Grid (dashboard-style).
+ *
+ * Defaulting absent values to `'tabbed'` at read time preserves backwards
+ * compatibility with v12 projects (see StorageService migration v12 → v13).
+ */
+type FormLayoutMode = 'tabbed' | 'grid';
+/**
+ * Grid container configuration used when `FormDefinition.layoutMode === 'grid'`.
+ * Sections position themselves with `FormSection.gridPosition`; sections lacking
+ * a position get auto-placed by the renderer (top-to-bottom, column-first).
+ */
+interface FormGridLayout {
+    /** Total columns in the grid (e.g. 12 for a responsive 12-column grid). */
+    columns: number;
+    /** Auto-row height in pixels. Sections span H rows. */
+    rowHeight: number;
+    /** Gap between grid cells in pixels (applies to both axes). */
+    gap: number;
+    /** Optional responsive column overrides — designer hint only in v1. */
+    breakpoints?: {
+        sm?: number;
+        md?: number;
+        lg?: number;
+    };
+}
+/** Default grid layout applied when a form is created in grid mode. */
+declare const DEFAULT_FORM_GRID_LAYOUT: FormGridLayout;
+/** Button appearance style */
+type DialogButtonAppearance = 'primary' | 'default' | 'subtle';
+/** Button position in dialog footer */
+type DialogButtonPosition = 'left' | 'right';
+/**
+ * Action to perform when a dialog button is clicked.
+ * Supports close, submit, navigate, and custom actions.
+ */
+type DialogButtonAction = {
+    type: 'close';
+} | {
+    type: 'submit';
+} | {
+    type: 'navigate';
+    target: NavigationAction;
+} | {
+    type: 'custom';
+    actionId: string;
+};
+/**
+ * Configuration for a dialog action button.
+ * Used in dialog footers for confirm/cancel/custom actions.
+ */
+interface DialogActionButton {
+    /** Unique identifier */
+    id: string;
+    /** Button label text */
+    label: string;
+    /** Optional Fluent UI icon name */
+    icon?: string;
+    /** Button appearance style */
+    appearance: DialogButtonAppearance;
+    /** Position in dialog footer (left or right side) */
+    position: DialogButtonPosition;
+    /** Sort order within position group (lower = first) */
+    order: number;
+    /** Whether button is disabled */
+    disabled?: boolean;
+    /** Whether button is hidden */
+    hidden?: boolean;
+    /** Action when button is clicked */
+    action: DialogButtonAction;
+}
+type CommandBarItemPosition = 'primary' | 'overflow' | 'far';
+/**
+ * Where a command bar item is shown. Only meaningful for grid/subgrid
+ * command bars (which also expose a row right-click menu); form-level
+ * command bars treat any value as `commandBar`. Defaults to `both` at
+ * read time so legacy items keep their current behavior.
+ */
+type CommandBarItemVisibility = 'commandBar' | 'contextMenu' | 'both';
+/**
+ * Default Dynamics action behaviors that a command bar item can be wired to.
+ * - `custom`     no default behavior (legacy items default here)
+ * - `navigate`   opens another form via `navigationAction`
+ * - `new`        opens the create form for the grid's entity
+ * - `addExisting` opens the lookup dialog to associate an existing record
+ *                 (only valid on related/nested grids)
+ * - `edit`       opens the edit form for the selected row; multi-select
+ *                falls through to the OOB bulk edit form
+ * - `delete`     deletes selected rows via `Xrm.WebApi.deleteRecord`
+ * - `activate`   sets statecode to active for selected rows
+ * - `deactivate` sets statecode to inactive for selected rows
+ * - `refresh`    re-fetches the grid (always whole-grid)
+ * - `export`     exports the current view (always whole-grid)
+ * - `bulkEdit`   explicitly invokes `Xrm.Navigation.openBulkEditForm`
+ */
+type CommandBarItemActionType = 'custom' | 'navigate' | 'new' | 'addExisting' | 'edit' | 'delete' | 'activate' | 'deactivate' | 'refresh' | 'export' | 'bulkEdit';
+/**
+ * Whether an action operates on selected rows or the whole grid.
+ * - `auto`       derived from `actionType`. Resolution:
+ *                refresh/export/new/addExisting → grid;
+ *                edit/delete/activate/deactivate/bulkEdit → selection;
+ *                navigate/custom → grid (caller decides).
+ * - `selection`  requires at least one selected row
+ * - `grid`       operates on the whole grid
+ */
+type CommandBarItemActionScope = 'auto' | 'selection' | 'grid';
+interface CommandBarItem {
+    id: string;
+    text: string;
+    iconName: string;
+    position: CommandBarItemPosition;
+    iconOnly?: boolean;
+    /**
+     * Optional visibility override (grids only). Defaults to `both` —
+     * the item appears in both the toolbar and the row right-click menu.
+     */
+    visibility?: CommandBarItemVisibility;
+    /** Navigation action when clicked (opens another form) */
+    navigationAction?: NavigationAction;
+    /**
+     * Default Dynamics action behavior. Defaults to `custom` for legacy items
+     * (no wired behavior). When set to `navigate`, `navigationAction` is used.
+     */
+    actionType?: CommandBarItemActionType;
+    /** Whether the action operates on selected rows or the whole grid. Defaults to `auto`. */
+    actionScope?: CommandBarItemActionScope;
+    /**
+     * Hide this item until at least N rows are selected. `0` (or undefined)
+     * means always show. Most useful for `delete`, `edit`, `activate`,
+     * `deactivate`, and `bulkEdit` — defaults are derived from `actionType`
+     * when this is unset.
+     */
+    minSelectionCount?: number;
+}
+/** Number of header field slots (0-4) */
+type HeaderSlotCount = 0 | 1 | 2 | 3 | 4;
+/** Header display modes */
+type HeaderDisplayMode = 'inline' | 'flyout';
+/** Persona size options for header */
+type HeaderPersonaSize = 'size32' | 'size48' | 'size72';
+/** Preset colors for persona avatar */
+type HeaderPersonaColor = 'lightBlue' | 'blue' | 'darkBlue' | 'teal' | 'lightGreen' | 'green' | 'darkGreen' | 'lightPink' | 'pink' | 'magenta' | 'purple' | 'orange' | 'red' | 'darkRed' | 'violet' | 'gold' | 'burgundy' | 'warmGray' | 'coolGray' | 'cyan' | 'rust' | 'custom';
+/** Source mode for header persona data */
+type HeaderPersonaSourceMode = 'static' | 'dataverse';
+/** Configuration for the header persona/avatar */
+interface HeaderPersonaConfig {
+    /** Whether to show the persona in the header */
+    enabled: boolean;
+    /** Source mode: 'static' for manual text/image, 'dataverse' for record-driven */
+    sourceMode?: HeaderPersonaSourceMode;
+    /** Field logical name to use for the display name (e.g., "fullname", "name") */
+    nameField?: string;
+    /** Field logical name to use for the image URL (e.g., "entityimage_url") */
+    imageField?: string;
+    /** Secondary text to display (e.g., entity type). Leave empty to use entity display name */
+    secondaryText?: string;
+    /** Whether to show the secondary text line */
+    showSecondaryText?: boolean;
+    /** Size of the persona avatar */
+    size?: HeaderPersonaSize;
+    /** Preset color for the avatar background */
+    color?: HeaderPersonaColor;
+    /** Custom hex color (used when color is 'custom') */
+    customColor?: string;
+    /** Static image URL or base64 data URL for the avatar */
+    imageUrl?: string;
+    /** Whether to use an uploaded image instead of initials */
+    useImage?: boolean;
+    /** Dataverse entity logical name (e.g., 'systemuser', 'contact', 'account') */
+    dvRecordEntityName?: string;
+    /** Selected record ID */
+    dvRecordId?: string;
+    /** Selected record primary name */
+    dvRecordName?: string;
+    /** Selected record secondary text (jobtitle, description, etc.) */
+    dvRecordSecondaryText?: string;
+    /** Base64 data URL of the record's entity image */
+    dvRecordImageDataUrl?: string;
+    /** Whether the record is disabled (systemuser only, for presence derivation) */
+    dvRecordIsDisabled?: boolean;
+    /** Show presence indicator */
+    showPresence?: boolean;
+    /** Presence status override */
+    presence?: string;
+}
+interface FormHeader {
+    /** Display title shown in header; falls back to form.name when empty */
+    title?: string;
+    /** Subtitle shown below title; falls back to form type label when empty */
+    subtitle?: string;
+    /** Manual title text color override. Overrides auto-contrast when set. */
+    titleColor?: string;
+    /** Manual subtitle text color override. Overrides auto-contrast when set. */
+    subtitleColor?: string;
+    /** Number of field slots to display (0-4), defaults to 4 */
+    slotCount?: HeaderSlotCount;
+    /** Persona configuration for showing an avatar with name */
+    persona?: HeaderPersonaConfig;
+    cells: FormCell[];
+}
+interface FormDefinition {
+    id: string;
+    name: string;
+    type: FormType;
+    /**
+     * Layout mode. `'tabbed'` (default) uses the classic tabs/sections flow.
+     * `'grid'` places sections as tiles on a CSS Grid (dashboard-style). Only
+     * meaningful when `type === 'main'` in v1; dialog/panel/callout ignore it.
+     * Absent on v12-and-earlier projects → treated as `'tabbed'`.
+     */
+    layoutMode?: FormLayoutMode;
+    /**
+     * Grid container configuration. Only read when `layoutMode === 'grid'`.
+     * Undefined means use `DEFAULT_FORM_GRID_LAYOUT`.
+     */
+    gridLayout?: FormGridLayout;
+    settings: FormSettings;
+    /** Header fields for main forms (up to 4 key fields) */
+    header?: FormHeader;
+    /** Command bar items for main forms */
+    commandBar?: CommandBarItem[];
+    /** Tabs for main forms */
+    tabs: FormTab[];
+    /** Flat sections for dialog/panel/callout */
+    sections: FormSection[];
+    /** Display order within type category (for sidebar organization) */
+    order?: number;
+    /** Description for documentation */
+    description?: string;
+    /** Parameters this form accepts when opened from another form */
+    inputParameters?: FormParameter[];
+    /** ID of the template this form was created from (for template editing workflow) */
+    sourceTemplateId?: string;
+    /** Embedded callout definitions owned by this form */
+    callouts?: CalloutDefinition[];
+    /** Callout-to-target attachments (maps callouts to controls/sections/etc.) */
+    calloutAttachments?: CalloutAttachment[];
+}
+/** Aggregate function types supported in FetchXML */
+type FetchXmlAggregateFunction = 'avg' | 'count' | 'countcolumn' | 'max' | 'min' | 'sum';
+/** Attribute parsed from FetchXML */
+interface FetchXmlAttribute {
+    /** The logical name of the attribute, e.g., "fullname" */
+    logicalName: string;
+    /** Optional alias if specified in FetchXML */
+    alias?: string;
+    /** If from a link-entity, the alias of that link-entity */
+    linkedEntityAlias?: string;
+    /** Whether to use the formatted value (e.g., "Active" instead of 0 for option sets) */
+    useFormattedValue?: boolean;
+    /** Aggregate function if this is an aggregate attribute (avg, count, countcolumn, max, min, sum) */
+    aggregateFunction?: FetchXmlAggregateFunction;
+}
+/**
+ * A FetchXML-based data source.
+ *
+ * The FIRST entry in `form.settings.dataSources` is the form's primary source and carries
+ * the primary-entity metadata fields (entitySetName, primaryIdAttribute, etc.) needed for
+ * runtime record fetching and PCF manifest generation. Secondary entries (index >= 1) are
+ * related-record queries and may leave the primary-only fields undefined.
+ */
+interface FormDataSource {
+    /** Unique identifier for this data source */
+    id: string;
+    /** User-friendly name, e.g., "Related Contacts" */
+    name: string;
+    /** The raw FetchXML query */
+    fetchXml: string;
+    /** Entity name parsed from <entity name="..."> */
+    entityName: string;
+    /** Attributes parsed from <attribute name="..."/> */
+    attributes: FetchXmlAttribute[];
+    /** Placeholder tokens like {*accountid*} found in the FetchXML */
+    placeholders: string[];
+    /**
+     * Include formatted values in API response.
+     * When true, adds `Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"`
+     * header to the request. This provides display names for option sets, lookups, dates, etc.
+     */
+    includeFormattedValues?: boolean;
+    /** True if fetch element has aggregate='true' - returns computed values instead of records */
+    isAggregate?: boolean;
+    /** OData entity set name, e.g., "accounts". Required on the primary source for record fetch. */
+    entitySetName?: string;
+    /** Primary key attribute, e.g., "accountid". Required on the primary source. */
+    primaryIdAttribute?: string;
+    /** Primary name attribute, e.g., "name". Used by headers and lookup displays. */
+    primaryNameAttribute?: string;
+    /** Localized entity display name, e.g., "Account". */
+    displayName?: string;
+    /** Localized plural entity display name, e.g., "Accounts". */
+    displayNamePlural?: string;
+}
+interface FormSettings {
+    width?: number;
+    height?: number;
+    position?: 'left' | 'right' | 'center';
+    showCommandBar: boolean;
+    /** Whether to show text labels on command bar items (default: true) */
+    showCommandBarLabels?: boolean;
+    showHeader: boolean;
+    /** How header fields are displayed: 'inline' (always visible) or 'flyout' (expandable callout). Default: 'flyout' */
+    headerDisplayMode?: HeaderDisplayMode;
+    /**
+     * FetchXML-based data sources. The first entry (index [0]) is the form's primary source,
+     * carrying entity metadata (entitySetName, primaryIdAttribute, etc.). Secondary entries are
+     * related-record queries. Use `getPrimaryDataSource()` from `utils/formDataSource` to read.
+     */
+    dataSources?: FormDataSource[];
+    /** Theme configuration (preset and custom colors) */
+    theme?: FormThemeSettings;
+    /** Business rule IDs applied to this form (references project.businessRules) */
+    businessRuleIds?: string[];
+    /** Overrides for entity-scoped rules on this form */
+    ruleOverrides?: {
+        ruleId: string;
+        enabled: boolean;
+    }[];
+    /** Dialog action buttons (only applicable for dialog form type) */
+    dialogButtons?: DialogActionButton[];
+    /** Alignment of the dialog button footer: left, center, or right (default: 'right') */
+    dialogButtonAlignment?: 'left' | 'center' | 'right';
+    /** Optional subheader text shown below the dialog title */
+    dialogSubheader?: string;
+    /** When true, dialog sections render as Pivot tabs instead of stacking vertically */
+    dialogUsePivots?: boolean;
+    /** Column layout for dialog sections (like tab layout for main forms) */
+    dialogLayout?: TabLayout;
+    /** When true, dialog expands to full viewport width */
+    dialogFullWidth?: boolean;
+    /** Optional record counter shown in dialog header (e.g., "3 of 12") */
+    dialogRecordCounter?: {
+        enabled: boolean;
+        current: number;
+        total: number;
+        position?: 'left' | 'right';
+    };
+    /** Panel action buttons (footer buttons for panel form type) */
+    panelButtons?: DialogActionButton[];
+    /** Alignment of the panel button footer (default: 'right') */
+    panelButtonAlignment?: 'left' | 'center' | 'right';
+    /** Optional subheader text shown below the panel title */
+    panelSubheader?: string;
+    /** When true, panel sections render as Pivot tabs */
+    panelUsePivots?: boolean;
+    /** Column layout for panel sections */
+    panelLayout?: TabLayout;
+    /** Fluent UI PanelType for controlling panel size/position */
+    panelType?: 'smallFixedFar' | 'smallFixedNear' | 'medium' | 'large' | 'largeFixed' | 'extraLarge' | 'custom' | 'customNear';
+    /** Whether panel shows a close button (default: true) */
+    panelHasCloseButton?: boolean;
+    /** Whether clicking outside the panel dismisses it (default: false) */
+    panelIsLightDismiss?: boolean;
+    /** Whether footer buttons are pinned to the bottom (default: true) */
+    panelIsFooterAtBottom?: boolean;
+    /** Whether the panel is non-modal (allows interaction with content behind it, no overlay) */
+    panelIsNonModal?: boolean;
+    /** Business Process Flow ID this form is associated with */
+    bpfId?: string;
+    /** BPF stage ID this form is linked to (for stage-specific forms) */
+    bpfStageId?: string;
+    /** Whether to show the BPF progress indicator on this form */
+    showBpfProgress?: boolean;
+    /** BPF progress indicator alignment */
+    bpfAlignment?: 'left' | 'center' | 'right';
+    /** Whether the BPF progress indicator should span full width */
+    bpfFullWidth?: boolean;
+    /** Whether this is the default form for the entity (only one per entity) */
+    isDefaultForEntity?: boolean;
+    /** Order in form selector dropdown (lower = first) */
+    formSelectorOrder?: number;
+    /**
+     * Form group ID for manual grouping.
+     * Forms with the same formGroupId are grouped together in the form selector,
+     * independent of or in addition to entity binding.
+     */
+    formGroupId?: string;
+    /**
+     * Display name for the form group (used when this form defines a new group)
+     */
+    formGroupName?: string;
+    /**
+     * Optional color for the form group indicator (hex color, e.g., "#0078d4")
+     * When set, the link icon in the sidebar uses this color instead of default blue.
+     */
+    formGroupColor?: string;
+}
+interface TabLayout {
+    columns: 1 | 2 | 3;
+    columnWidths: number[];
+}
+/** Base tab properties shared by all tab types */
+interface FormTabBase {
+    id: string;
+    label: string;
+    expanded: boolean;
+    showLabel: boolean;
+}
+/** Main content tab with sections (existing behavior) */
+interface MainFormTab extends FormTabBase {
+    tabType: 'main';
+    layout: TabLayout;
+    sections: FormSection[];
+}
+/** Related records tab configuration */
+interface RelatedTabConfig {
+    /** Logical name of the related entity (e.g., "contact") */
+    entityLogicalName: string;
+    /** Display name of the related entity (e.g., "Contacts") */
+    entityDisplayName: string;
+    /** FetchXML query for retrieving related records */
+    fetchXml: string;
+    /** Attributes parsed from the FetchXML */
+    attributes: FetchXmlAttribute[];
+    /** Placeholder tokens found in the FetchXML (e.g., "{*accountid*}") */
+    placeholders: string[];
+    /** Grid display type */
+    gridType: 'standard' | 'readonly';
+    /** Column configuration for the grid (optional - auto-generated from attributes if not provided) */
+    columns?: SubgridColumn[];
+    /** Maximum rows to display (default: 5) */
+    maxRows?: number;
+    /** Whether to show the command bar (Add, Edit, Delete buttons) */
+    showCommandBar?: boolean;
+}
+/** Related records tab */
+interface RelatedFormTab extends FormTabBase {
+    tabType: 'related';
+    relatedConfig: RelatedTabConfig;
+}
+/** Configuration for audit history tab */
+interface AuditHistoryConfig {
+    /** Maximum number of audit records to display (default: 20) */
+    maxRows?: number;
+    /** Whether to show the user who made the change (default: true) */
+    showChangedBy?: boolean;
+    /** Whether to show detailed field changes (default: true) */
+    showFieldChanges?: boolean;
+    /** Sort order for audit records (default: 'newest') */
+    sortOrder?: 'newest' | 'oldest';
+}
+/** Audit history tab */
+interface AuditFormTab extends FormTabBase {
+    tabType: 'audit';
+    auditConfig: AuditHistoryConfig;
+}
+/**
+ * Union type for form tabs.
+ * - Main tabs: Have sections and layout (existing behavior)
+ * - Related tabs: Display related records via FetchXML
+ * - Audit tabs: Display change history from the audit entity
+ *
+ * Note: For backward compatibility, tabs without tabType are treated as 'main'
+ */
+type FormTab = MainFormTab | RelatedFormTab | AuditFormTab;
+/**
+ * Check if a tab is a main content tab (has sections).
+ * Also handles backward compatibility for tabs without tabType property.
+ */
+declare function isMainTab(tab: FormTab): tab is MainFormTab;
+/**
+ * Check if a tab is a related records tab.
+ */
+declare function isRelatedTab(tab: FormTab): tab is RelatedFormTab;
+/**
+ * Check if a tab is an audit history tab.
+ */
+declare function isAuditTab(tab: FormTab): tab is AuditFormTab;
+/**
+ * Position of a section within a grid-mode form. `x`/`y` are top-left cell
+ * indices; `w`/`h` are spans in grid cells. Only read when the parent
+ * `FormDefinition.layoutMode === 'grid'`. Tabbed mode ignores this field.
+ */
+interface FormSectionGridPosition {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface FormSection {
+    id: string;
+    label: string;
+    columns: 1 | 2 | 3 | 4;
+    showLabel: boolean;
+    collapsible: boolean;
+    variant: 'card' | 'flat' | 'placeholder';
+    tabColumn?: number;
+    /**
+     * Grid placement for this section. Only honored when the parent form's
+     * `layoutMode === 'grid'`. Absent → renderer auto-places the section.
+     */
+    gridPosition?: FormSectionGridPosition;
+    rows: FormRow[];
+    minHeight?: number;
+    widthPercent?: number;
+    fullWidth?: boolean;
+    /** When true, this section renders as a tab in a pivot group with adjacent pivot sections */
+    isPivotTab?: boolean;
+    /** Per-section background override (color, image, or gradient). When undefined, inherits from theme. */
+    background?: BackgroundConfig;
+    /** Manual text color override for section header label. Overrides auto-contrast when set. */
+    textColor?: string;
+    /** Label position: 'beside' (left of field, default) or 'above' (stacked on top) */
+    labelPosition?: 'beside' | 'above';
+    /** Label column width as a percentage (default 35). Only applies when labelPosition is 'beside'. */
+    labelWidth?: number;
+    /** Vertical gap between rows in pixels (default 4) */
+    rowGap?: number;
+    /** Horizontal gap between cells in pixels (default 8) */
+    cellGap?: number;
+    /** When true, labels wrap instead of truncating with ellipsis */
+    wrapLabel?: boolean;
+    /** When true, hidden fields collapse and remaining fields reflow to fill space */
+    collapseHidden?: boolean;
+}
+interface FormRow {
+    id: string;
+    columns: 1 | 2 | 3 | 4;
+    cells: FormCell[];
+}
+interface FormCell {
+    id: string;
+    control: ControlDefinition | null;
+    colSpan: number;
+    rowSpan: number;
+}
+/** Directional hint for callout positioning relative to target */
+type CalloutDirectionalHint = 'topLeftEdge' | 'topCenter' | 'topRightEdge' | 'topAutoEdge' | 'bottomLeftEdge' | 'bottomCenter' | 'bottomRightEdge' | 'bottomAutoEdge' | 'leftTopEdge' | 'leftCenter' | 'leftBottomEdge' | 'rightTopEdge' | 'rightCenter' | 'rightBottomEdge';
+/** How the callout is triggered on the target element */
+type CalloutTrigger = 'click' | 'hover' | 'icon-click';
+/** Action button in callout footer */
+interface CalloutActionButton {
+    id: string;
+    label: string;
+    icon?: string;
+    appearance: 'primary' | 'default';
+    action: 'dismiss' | 'submit';
+}
+/** A field binding for data-bound grid callouts */
+interface CalloutFieldBinding {
+    id: string;
+    /** Row field name to read the value from */
+    fieldName: string;
+    /** Display label shown in the callout */
+    label: string;
+    /** How to render the value */
+    displayType: 'text' | 'badge' | 'currency' | 'date' | 'link' | 'icon-value';
+    /** Optional icon to show next to the label */
+    iconName?: string;
+    /** Display order */
+    order: number;
+}
+/**
+ * A callout definition embedded within a parent form or grid.
+ * Callouts are floating popups attached to controls/sections on a form,
+ * or to grid columns for data-aware cell popups.
+ * Static callouts use FormSection structure for content.
+ * Data-bound callouts use fieldBindings resolved against row data.
+ */
+interface CalloutDefinition {
+    id: string;
+    name: string;
+    /** Callout width in pixels (default: 320) */
+    width?: number;
+    /** Position relative to target (default: bottomAutoEdge) */
+    directionalHint?: CalloutDirectionalHint;
+    /** Show the beak/arrow pointing to target (default: true) */
+    isBeakVisible?: boolean;
+    /** Beak width in pixels (default: 16) */
+    beakWidth?: number;
+    /** Gap between callout and target in pixels (default: 0) */
+    gapSpace?: number;
+    /** How the callout is triggered (default: click) */
+    trigger?: CalloutTrigger;
+    /** Whether clicking outside dismisses the callout (default: true) */
+    dismissOnClickOutside?: boolean;
+    /** Action buttons in callout footer */
+    actionButtons?: CalloutActionButton[];
+    /** Footer button alignment (default: right) */
+    buttonAlignment?: 'left' | 'center' | 'right';
+    /** When true, sections render as Pivot tabs instead of stacking vertically */
+    usePivots?: boolean;
+    /** Callout content (reuses existing section structure) — used when contentMode is 'static' */
+    sections: FormSection[];
+    /** Content mode: 'static' uses sections, 'data-bound' uses fieldBindings (default: 'static') */
+    contentMode?: 'static' | 'data-bound';
+    /** Field bindings for data-bound callouts — each maps a row field to a display slot */
+    fieldBindings?: CalloutFieldBinding[];
+    /** Tracks which factory preset was used for data-bound callouts */
+    presetType?: 'lookup-detail' | 'status-detail' | 'custom';
+}
+/** Type of element a callout can be attached to */
+type CalloutTargetType = 'control' | 'section' | 'commandBarItem' | 'headerField';
+/** Describes a callout's attachment to a specific target element */
+interface CalloutAttachment {
+    calloutId: string;
+    targetType: CalloutTargetType;
+    targetId: string;
+    /** Override the callout's default trigger for this specific attachment */
+    trigger?: CalloutTrigger;
+}
+
+type ControlType = 'text' | 'textarea' | 'number' | 'decimal' | 'currency' | 'date' | 'datetime' | 'dropdown' | 'optionset' | 'checkbox' | 'toggle' | 'combobox' | 'choicegroup' | 'lookup' | 'phone' | 'email' | 'url' | 'subgrid' | 'timeline' | 'webresource' | 'slider' | 'rating' | 'spinbutton' | 'formlink' | 'persona' | 'spacer' | 'label' | 'button' | 'barchart' | 'linechart' | 'areachart' | 'piechart' | 'donutchart' | 'horizontalbarchart' | 'gaugechart' | 'sparkline' | 'heatmapchart' | 'kpicard' | 'funnelchart' | 'scatterchart';
+type ControlCategory = 'popular' | 'input' | 'choice' | 'display' | 'grid' | 'layout' | 'action' | 'chart';
+/** Aggregation function applied when multiple rows share a category. */
+type ChartAggregation = 'count' | 'sum' | 'avg' | 'min' | 'max';
+/** Color palette key for chart rendering. */
+type ChartPalette = 'default' | 'categorical' | 'sequential' | 'diverging';
+/**
+ * Per-control configuration for chart-category controls. Lives on
+ * `ControlDefinition.properties.chartConfig`. The renderer reads from
+ * `dataSourceId` to look up the FetchXML data source on the parent form
+ * (form.settings.dataSources). Sample data is used when dataSourceId is
+ * undefined so the designer canvas shows a plausible visualization
+ * before the user wires up data.
+ */
+interface ChartConfig {
+    /**
+     * Id of a `FormDataSource` on the parent form. When undefined, the
+     * chart renders with library sample data (designer + preview only —
+     * runtime emitted code requires a real source).
+     */
+    dataSourceId?: string;
+    /**
+     * Attribute used as the x-axis / category. For pie/donut, this is
+     * the slice label. Ignored for gauge/kpi (single-value controls).
+     */
+    categoryAttribute?: string;
+    /** Attribute used as the y-axis / value. */
+    valueAttribute?: string;
+    /** Aggregation when multiple rows share a category. */
+    aggregation?: ChartAggregation;
+    /** Chart title displayed above the visualization. */
+    title?: string;
+    /** Color palette. */
+    palette?: ChartPalette;
+    /** Whether to show the legend (most chart types). */
+    showLegend?: boolean;
+    /** Gauge/KPI: target value for trend comparison. */
+    target?: number;
+    /** Gauge: min value of the range. */
+    min?: number;
+    /** Gauge: max value of the range. */
+    max?: number;
+}
+type SubgridColumnDataType = 'text' | 'numeric' | 'yesno' | 'date';
+interface SubgridColumn {
+    key: string;
+    name: string;
+    fieldName: string;
+    minWidth: number;
+    maxWidth?: number;
+    isResizable?: boolean;
+    dataType?: SubgridColumnDataType;
+    isCustom?: boolean;
+}
+type SubgridGridType = 'standard' | 'readonly' | 'focused-view';
+interface ControlDataBinding {
+    attributeLogicalName: string;
+    attributeType: string;
+    metadataDriven: boolean;
+    customFetchXml?: string;
+    lookupTargets?: string[];
+    optionSetOptions?: Array<{
+        value: number;
+        label: string;
+        color?: string;
+    }>;
+    viewId?: string;
+    viewFetchXml?: string;
+    /** If bound to a FetchXML data source instead of primary entity */
+    dataSourceId?: string;
+    /** Field from the data source (logical name or alias) */
+    dataSourceField?: string;
+    /**
+     * Use the formatted/display value instead of raw value.
+     * For option sets: "Active" instead of 0
+     * For lookups: Display name instead of GUID
+     * For dates: Localized date string
+     * For money: Formatted currency string
+     * Requires data source to have includeFormattedValues=true
+     */
+    useFormattedValue?: boolean;
+    /** Lookup-specific: Default view ID for filtering lookup records */
+    lookupViewId?: string;
+    /** Lookup-specific: Custom FetchXML for filtering lookup records */
+    lookupFetchXml?: string;
+    /** Lookup-specific: Whether to use custom FetchXML filter instead of view */
+    useLookupFetchXml?: boolean;
+    /** Global option set options (for dropdown/optionset with global source) */
+    globalOptionSetOptions?: Array<{
+        value: number;
+        label: string;
+        color?: string;
+    }>;
+    /** Global option set name (for dropdown/optionset with global source) */
+    globalOptionSetName?: string;
+}
+interface ControlDefinition {
+    type: ControlType;
+    label: string;
+    name: string;
+    required: boolean;
+    readOnly: boolean;
+    /** When true, the control is hidden by default on the form. Business rules can override visibility at runtime. */
+    hidden?: boolean;
+    hideLabel: boolean;
+    /** Manual label color override. When set, takes precedence over auto-contrast. */
+    labelColor?: string;
+    /** Per-control label position override. When set, takes precedence over section-level setting. */
+    labelPosition?: 'beside' | 'above';
+    /** Per-control label width override (percentage). When set, takes precedence over section-level setting. */
+    labelWidth?: number;
+    /** When true, label wraps instead of truncating with ellipsis. Overrides section-level setting. */
+    wrapLabel?: boolean;
+    /** Manual value/input text color override. When set, overrides theme default. */
+    valueColor?: string;
+    properties: Record<string, unknown>;
+    validation: ValidationRule[];
+    responsive: ResponsiveSettings;
+    dataBinding?: ControlDataBinding;
+    /** References a callout in parent form's callouts array */
+    calloutId?: string;
+    /** Override the callout's default trigger for this control */
+    calloutTrigger?: CalloutTrigger;
+}
+interface ValidationRule {
+    type: 'required' | 'minLength' | 'maxLength' | 'min' | 'max' | 'pattern' | 'custom';
+    value?: string | number;
+    message: string;
+}
+interface ResponsiveSettings {
+    hideOnPhone: boolean;
+    hideOnTablet: boolean;
+}
+interface ControlRegistryEntry {
+    type: ControlType;
+    label: string;
+    icon: string;
+    category: ControlCategory;
+    defaultProperties: Record<string, unknown>;
+    description: string;
+    /**
+     * If set, this control type is an alias for another type.
+     * When dragged from palette, it creates a control of the aliasFor type
+     * with the specified defaultProperties.
+     */
+    aliasFor?: ControlType;
+    /**
+     * If true, this control type should not appear in the Type dropdown
+     * in control properties (e.g., phone, email, url are aliases of text)
+     */
+    hideFromTypeDropdown?: boolean;
+    /**
+     * When true, this control type has no Fluent UI v8 equivalent and can
+     * only render under v9 export targets. ExportDialog blocks v8-only
+     * targets (Power Pages Web Resource, Canvas App PCF) when the project
+     * uses any v9-required control. Symmetric counterpart to the existing
+     * `V9_INCOMPATIBLE_CONTROL_TYPES` set (controls with no v9 equivalent).
+     */
+    requiresV9?: boolean;
+}
+/** Text field format types (similar to Dynamics 365) */
+type TextFormat = 'text' | 'email' | 'url' | 'phone' | 'password';
+/** Text field configuration */
+interface TextFieldConfig {
+    /** Text format type */
+    textFormat?: TextFormat;
+    /** Max character length */
+    maxLength?: number;
+    /** Placeholder text (custom override) */
+    placeholder?: string;
+    /** Whether to show placeholder text (default: true) */
+    showPlaceholder?: boolean;
+    /** Show action button (mailto, tel:, open link) */
+    showActionButton?: boolean;
+    /** For password: allow show/hide toggle */
+    allowPasswordToggle?: boolean;
+}
+/** Mode for determining option source */
+type OptionSourceMode = 'attribute' | 'global' | 'custom';
+/** Custom option item with optional color and icon */
+interface CustomOptionItem {
+    value: number;
+    label: string;
+    color?: string;
+    icon?: string;
+    imageSrc?: string;
+    /** For ComboBox grouping: 'normal' (default), 'header', or 'divider' */
+    itemType?: 'normal' | 'header' | 'divider';
+}
+/** Configuration for dropdown/optionset controls */
+interface DropdownConfig {
+    /** Source mode for options */
+    optionSourceMode: OptionSourceMode;
+    /** Bound attribute name (for attribute mode) */
+    boundAttributeName?: string;
+    /** Global option set name (for global mode) */
+    globalOptionSetName?: string;
+    /** Custom options (for custom mode) */
+    customOptions?: CustomOptionItem[];
+    /** Enable multi-select (uses ComboBox) */
+    multiSelect?: boolean;
+    /** Show option colors as badges */
+    showOptionColors?: boolean;
+}
+/** Configuration for combobox controls */
+interface ComboBoxConfig {
+    /** Source mode for options */
+    optionSourceMode: OptionSourceMode;
+    /** Bound attribute name (for attribute mode) */
+    boundAttributeName?: string;
+    /** Global option set name (for global mode) */
+    globalOptionSetName?: string;
+    /** Custom options (for custom mode) */
+    customOptions?: CustomOptionItem[];
+    /** Enable multi-select */
+    multiSelect?: boolean;
+    /** Allow typing values not in the option list */
+    allowFreeform?: boolean;
+    /** Type-ahead auto-complete */
+    autoComplete?: 'on' | 'off';
+    /** Show option colors as badges */
+    showOptionColors?: boolean;
+}
+type ButtonVariant = 'default' | 'primary' | 'compound' | 'icon' | 'action' | 'command' | 'split' | 'toggle';
+/** Variants that support the `primary` (blue) styling toggle */
+declare const PRIMARY_CAPABLE_VARIANTS: ButtonVariant[];
+type ButtonSize = 'small' | 'medium' | 'large';
+type ButtonAction = {
+    type: 'none';
+} | {
+    type: 'switchTab';
+    targetTabId: string;
+} | {
+    type: 'navigate';
+    target: NavigationAction;
+} | {
+    type: 'triggerBusinessRule';
+    ruleId: string;
+} | {
+    type: 'navigateUrl';
+    url: string;
+    openInNewTab?: boolean;
+} | {
+    type: 'submitForm';
+} | {
+    type: 'scrollToSection';
+    sectionId: string;
+} | {
+    type: 'custom';
+    actionId: string;
+};
+interface ButtonMenuItem {
+    id: string;
+    text: string;
+    iconName?: string;
+    action: ButtonAction;
+}
+interface ButtonCommandBarItem {
+    id: string;
+    text: string;
+    iconName?: string;
+    iconOnly?: boolean;
+    action: ButtonAction;
+    subMenuItems?: ButtonMenuItem[];
+}
+interface ButtonConfig {
+    buttonText: string;
+    buttonVariant: ButtonVariant;
+    buttonAction: ButtonAction;
+    primary?: boolean;
+    iconName?: string;
+    iconPosition?: 'before' | 'after';
+    size?: ButtonSize;
+    fullWidth?: boolean;
+    alignment?: 'left' | 'center' | 'right';
+    disabled?: boolean;
+    tooltip?: string;
+    secondaryText?: string;
+    iconOnly?: boolean;
+    backgroundColor?: string;
+    textColor?: string;
+    iconColor?: string;
+    menuItems?: ButtonMenuItem[];
+    commandBarItems?: ButtonCommandBarItem[];
+    commandBarIconOnly?: boolean;
+    /** Position of the main button within the combined command bar list (default 0 = first) */
+    commandBarMainPosition?: number;
+    checkedText?: string;
+    uncheckedText?: string;
+    checkedIconName?: string;
+    checkedBackgroundColor?: string;
+    checkedTextColor?: string;
+    checkedIconColor?: string;
+}
+type LayoutActionType = 'tab-1col' | 'tab-2col' | 'tab-3col' | 'section-1col' | 'section-2col' | 'section-3col' | 'section-4col' | 'tabbed-section';
+interface LayoutActionEntry {
+    type: LayoutActionType;
+    label: string;
+    icon: string;
+    description: string;
+    columns?: 1 | 2 | 3 | 4;
+    targetStructure: 'tab' | 'section' | 'tabbed-section';
+    disabled?: boolean;
+}
+
+export { type HeaderPersonaConfig as $, type AuditFormTab as A, type ButtonAction as B, type CalloutActionButton as C, type CustomOptionItem as D, DEFAULT_FORM_GRID_LAYOUT as E, type DialogActionButton as F, type DialogButtonAction as G, type DialogButtonAppearance as H, type DialogButtonPosition as I, type DropdownConfig as J, type FetchXmlAggregateFunction as K, type FetchXmlAttribute as L, type FormCell as M, type FormDataSource as N, type FormDefinition as O, type FormGridLayout as P, type FormHeader as Q, type FormLayoutMode as R, type FormParameter as S, type FormRow as T, type FormSection as U, type FormSectionGridPosition as V, type FormSettings as W, type FormTab as X, type FormType as Y, type HeaderDisplayMode as Z, type HeaderPersonaColor as _, type AuditHistoryConfig as a, type HeaderPersonaSize as a0, type HeaderPersonaSourceMode as a1, type HeaderSlotCount as a2, type LayoutActionEntry as a3, type LayoutActionType as a4, type MainFormTab as a5, type NavigationAction as a6, type NavigationActionType as a7, type NavigationCloseResult as a8, type NavigationContext as a9, type NavigationOnCloseConfig as aa, type NavigationSizeConfig as ab, type NavigationStackEntry as ac, type OptionSourceMode as ad, PRIMARY_CAPABLE_VARIANTS as ae, type PanelPosition as af, type ParameterMapping as ag, type ParameterSourceType as ah, type RelatedFormTab as ai, type RelatedTabConfig as aj, type ResponsiveSettings as ak, type SubgridColumn as al, type SubgridColumnDataType as am, type SubgridGridType as an, type TabLayout as ao, type TextFieldConfig as ap, type TextFormat as aq, type ValidationRule as ar, isAuditTab as as, isMainTab as at, isRelatedTab as au, type ButtonCommandBarItem as b, type ButtonConfig as c, type ButtonMenuItem as d, type ButtonSize as e, type ButtonVariant as f, type CalloutAttachment as g, type CalloutDefinition as h, type CalloutDirectionalHint as i, type CalloutFieldBinding as j, type CalloutTargetType as k, type CalloutTrigger as l, type ChartAggregation as m, type ChartConfig as n, type ChartPalette as o, type ComboBoxConfig as p, type CommandBarItem as q, type CommandBarItemActionScope as r, type CommandBarItemActionType as s, type CommandBarItemPosition as t, type CommandBarItemVisibility as u, type ControlCategory as v, type ControlDataBinding as w, type ControlDefinition as x, type ControlRegistryEntry as y, type ControlType as z };