@dataverse-kit/form-runtime 0.1.0

package/dist/gridCustomizer-C0V9FAE_.d.ts

@@ -0,0 +1,569 @@
+import { N as FormDataSource, q as CommandBarItem } from './control-DaXBm-52.js';
+
+/**
+ * Focused View configuration types for Work Item Appearance settings.
+ * Supports up to 4 rows, each with primary + optional secondary fields and icons.
+ */
+/**
+ * A field reference in the focused view configuration.
+ */
+interface FocusedViewField {
+    /** Logical field name (e.g., "emailaddress1") */
+    fieldName: string;
+    /** Display label for the field */
+    label: string;
+    /** Alias for linked entity fields (e.g., "primarycontact") */
+    linkedEntityAlias?: string;
+    /** Attribute type for icon display (e.g., "String", "DateTime") */
+    attributeType?: string;
+}
+/**
+ * A row in the focused view configuration.
+ * Each row can have 1-2 fields and an optional icon.
+ */
+interface FocusedViewRow {
+    /** Unique identifier for the row */
+    id: string;
+    /** Primary field (required) */
+    primaryField: FocusedViewField;
+    /** Secondary field (optional, shown on the right) */
+    secondaryField?: FocusedViewField;
+    /** Icon name to display (e.g., "FavoriteStarFill") */
+    iconName?: string;
+}
+/**
+ * Complete focused view configuration matching Dynamics 365 Work Item Appearance.
+ */
+interface FocusedViewConfig {
+    /** 1-4 rows of field configuration */
+    rows: FocusedViewRow[];
+    /** Show "Up next activity" section at bottom */
+    showUpNextActivity?: boolean;
+}
+/**
+ * Icon options for focused view rows.
+ */
+declare const FOCUSED_VIEW_ICON_OPTIONS: readonly [{
+    readonly iconName: "";
+    readonly label: "None";
+}, {
+    readonly iconName: "FavoriteStarFill";
+    readonly label: "Star";
+}, {
+    readonly iconName: "NumberSymbol";
+    readonly label: "Number";
+}, {
+    readonly iconName: "Clock";
+    readonly label: "Time";
+}, {
+    readonly iconName: "Phone";
+    readonly label: "Phone";
+}, {
+    readonly iconName: "Mail";
+    readonly label: "Email";
+}, {
+    readonly iconName: "Calendar";
+    readonly label: "Calendar";
+}, {
+    readonly iconName: "Contact";
+    readonly label: "Contact";
+}, {
+    readonly iconName: "Money";
+    readonly label: "Currency";
+}, {
+    readonly iconName: "StatusCircleCheckmark";
+    readonly label: "Status";
+}];
+/**
+ * Maximum number of rows allowed in focused view configuration.
+ */
+declare const MAX_FOCUSED_VIEW_ROWS = 4;
+/**
+ * Legacy summary field format for backward compatibility.
+ */
+interface LegacySummaryField {
+    label: string;
+    fieldName: string;
+}
+/**
+ * Migrates legacy summary fields format to new FocusedViewConfig.
+ * @param primaryNameField - Legacy primary name field
+ * @param summaryFields - Legacy summary fields array
+ * @returns New FocusedViewConfig
+ */
+declare function migrateLegacyConfig(primaryNameField: string, summaryFields: LegacySummaryField[]): FocusedViewConfig;
+/**
+ * Creates a default focused view configuration.
+ * @param primaryNameField - Optional primary name field
+ * @returns Default FocusedViewConfig
+ */
+declare function createDefaultFocusedViewConfig(primaryNameField?: string): FocusedViewConfig;
+/**
+ * Validates a focused view configuration.
+ * @param config - Configuration to validate
+ * @returns True if valid
+ */
+declare function isValidFocusedViewConfig(config: unknown): config is FocusedViewConfig;
+/**
+ * Grid column interface (subset of SubgridColumn for typing).
+ */
+interface GridColumnInput {
+    key: string;
+    name: string;
+    fieldName: string;
+}
+/**
+ * Creates a focused view configuration from grid columns.
+ * Takes the first 4 columns and converts them to focused view rows.
+ * @param columns - Array of grid columns
+ * @returns FocusedViewConfig with rows based on columns
+ */
+declare function createConfigFromColumns(columns: GridColumnInput[]): FocusedViewConfig;
+
+/**
+ * Grid Customizer Type Definitions
+ *
+ * Models the grid customization structure for PCF Grid Customizers and
+ * Fluent UI DetailsList configurations. Supports column-level renderer
+ * selection, callouts, nested grids, aggregations, and export to code.
+ *
+ * Design principles:
+ * - Matches Microsoft PCF Grid Customizer cellRendererOverrides pattern
+ * - Reuses CalloutDefinition from form.ts for column callouts
+ * - JSON-serializable for IndexedDB persistence
+ * - Supports undo/redo via Immer patches (all types are plain objects)
+ */
+
+/** Data types for grid columns (maps to Dynamics 365 attribute types) */
+type GridColumnDataType = 'text' | 'numeric' | 'currency' | 'date' | 'datetime' | 'boolean' | 'optionset' | 'lookup' | 'image' | 'url' | 'email' | 'phone';
+/** Available renderer types for grid columns */
+type CellRendererType = 'text' | 'lookup' | 'optionset' | 'currency' | 'progress' | 'date' | 'boolean' | 'rating' | 'composite';
+/** Available editor types for editable grid columns */
+type CellEditorType = 'text' | 'dropdown' | 'number' | 'date' | 'toggle' | 'none';
+/** Aggregate functions for footer row */
+type AggregateFunction = 'sum' | 'avg' | 'count' | 'min' | 'max';
+type GridSelectionMode = 'none' | 'single' | 'multiple';
+type GridPaginationMode = 'pagination' | 'infinite-scroll';
+/**
+ * Grid layout/behavior mode. Replaces the older subgrid-control `gridType`
+ * property and folds together what used to be the `isEditable` toggle and
+ * `cardView.enabled` flag.
+ *
+ * - `standard` — default DetailsList rendering, read-only cells
+ * - `editable` — inline cell editing enabled (column-level `isLocked` overrides)
+ * - `readonly` — like standard but hides the command bar and disables selection
+ * - `focused-view` — list-detail layout (Dynamics 365 Work Item Appearance)
+ * - `card-list` — card layout instead of rows; uses `cardView` config
+ */
+type GridType = 'standard' | 'editable' | 'readonly' | 'focused-view' | 'card-list';
+/**
+ * Chart pane configuration shown alongside or in place of the grid records.
+ * Mirrors Dynamics 365 grid chart options.
+ */
+interface GridChartConfig {
+    /** Saved chart ID (`savedqueryvisualizationid`) shown by default */
+    defaultChartId?: string;
+    /** When true, hides the records list and only shows the chart */
+    showChartOnly?: boolean;
+    /** Whether the user can switch charts at runtime */
+    allowChartChange?: boolean;
+}
+/**
+ * Focused-view configuration on the grid customizer. Used only when
+ * `gridType === 'focused-view'`. Fields legacy-migrated from the subgrid
+ * control's `primaryNameField` + `summaryFields` continue to work — see
+ * `LegacySummaryField` and `migrateLegacyConfig`.
+ */
+interface GridFocusedViewSettings {
+    /** Structured row configuration */
+    config?: FocusedViewConfig;
+    /** Legacy primary name attribute (kept for backward compatibility) */
+    primaryNameField?: string;
+    /** Legacy flat summary fields (kept for backward compatibility) */
+    summaryFields?: LegacySummaryField[];
+}
+/** Slot types for the composite renderer */
+type CompositeSlotType = 'icon' | 'text' | 'badge' | 'link' | 'image' | 'spacer' | 'progress' | 'rating';
+/** Conditional style rule — first match wins in an ordered list */
+interface ConditionalStyle {
+    /** Field to evaluate (can be any field in the row, not just this column) */
+    field: string;
+    /** Comparison operator */
+    operator: 'eq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'between';
+    /** Value to compare against */
+    value: string | number;
+    /** End value for 'between' operator */
+    valueTo?: string | number;
+    /** Style to apply when condition matches */
+    style: Record<string, string>;
+}
+/** A composable slot within a composite cell renderer */
+interface CompositeSlot {
+    /** Unique identifier */
+    id: string;
+    /** Slot type determines what is rendered */
+    type: CompositeSlotType;
+    /** Bind to a row field (dynamic), or omit for static value */
+    fieldBinding?: string;
+    /** Static value (icon name, text, URL, etc.) when no field binding */
+    staticValue?: string;
+    /** Base style applied when no conditional style matches */
+    defaultStyle?: Record<string, string>;
+    /**
+     * Ordered list of conditional styles — first match wins.
+     * Falls through to defaultStyle if no condition matches.
+     * Consistent with StatusBadgeConfig's option-value-to-color pattern.
+     */
+    conditionalStyles?: ConditionalStyle[];
+}
+/** Configuration for the composite renderer */
+interface CompositeRendererConfig {
+    /** Layout direction for slots */
+    layout: 'horizontal' | 'vertical';
+    /** Gap between slots in pixels */
+    gap: number;
+    /** Ordered list of composable slots */
+    slots: CompositeSlot[];
+}
+/** Configuration for a single grid column */
+interface GridColumnDefinition {
+    /** Unique identifier */
+    id: string;
+    /** Logical field name (maps to entity attribute) */
+    fieldName: string;
+    /**
+     * Dataverse attribute logical name this column renders. When set alongside
+     * the grid's `dataSource`, enables code generation (models/constants/hooks)
+     * and validation against the entity's attribute list. Defaults to the same
+     * value as `fieldName` when the column is added from the entity picker, but
+     * the two stay independent so `fieldName` can remain a render-only key.
+     */
+    attributeLogicalName?: string;
+    /** Display header text */
+    displayName: string;
+    /** Data type of the column */
+    dataType: GridColumnDataType;
+    /** Column width in pixels */
+    width: number;
+    /** Minimum column width */
+    minWidth?: number;
+    /** Maximum column width */
+    maxWidth?: number;
+    /** Whether the column is resizable */
+    isResizable: boolean;
+    /** Whether the column is visible */
+    isVisible: boolean;
+    /** Display order (lower = leftmost) */
+    order: number;
+    /** Cell renderer type */
+    rendererType: CellRendererType;
+    /**
+     * Type-specific renderer configuration.
+     * Shape depends on rendererType — enforced at the UI layer per config panel.
+     * Examples:
+     *   optionset → { displayMode: 'box', options: [...], showIcon: true }
+     *   currency → { currencyCode: 'USD', showTrend: true, decimals: 2 }
+     *   progress → { min: 0, max: 100, thresholds: { warning: 30, danger: 10 } }
+     *   composite → CompositeRendererConfig
+     */
+    rendererConfig: Record<string, unknown>;
+    /** Cell editor type (for editable grids). 'none' disables editing. */
+    editorType?: CellEditorType;
+    /** Type-specific editor configuration */
+    editorConfig?: Record<string, unknown>;
+    /**
+     * When true, this column is locked even if the parent grid is editable.
+     * Used for read-only fields, computed values, or fields the current user
+     * lacks permission to edit. Renders a lock icon in the column header.
+     */
+    isLocked?: boolean;
+    /** Whether this column is sortable */
+    isSortable: boolean;
+    /** Default sort direction (when column is the initial sort) */
+    defaultSortDirection?: 'asc' | 'desc';
+    /** Whether this column is filterable */
+    isFilterable: boolean;
+    /** Filter control type */
+    filterType?: 'text' | 'dropdown' | 'date-range' | 'number-range';
+    /** Aggregate function for footer row (only valid on numeric columns) */
+    aggregateFunction?: AggregateFunction;
+    /** Whether to show a lookup preview card on hover (only applies to lookup columns) */
+    showLookupPreview?: boolean;
+    /**
+     * Field logical names (on rendererConfig.targetEntity) to render in the
+     * preview card. Empty/undefined shows an empty-state prompting the user
+     * to pick fields. Values are resolved against the row's Dataverse record,
+     * preferring the `@OData.Community.Display.V1.FormattedValue` sibling key.
+     */
+    previewFields?: string[];
+}
+/** Custom toolbar button */
+interface GridToolbarButton {
+    /** Unique identifier */
+    id: string;
+    /** Button label text */
+    text: string;
+    /** Fluent UI icon name */
+    iconName?: string;
+    /** Position in toolbar */
+    position: 'primary' | 'overflow';
+}
+/** Toolbar feature toggles */
+interface GridToolbarConfig {
+    /** Show search box */
+    showSearch: boolean;
+    /** Show column filter dropdowns */
+    showFilters: boolean;
+    /** Show list/card view toggle */
+    showViewToggle: boolean;
+    /** Show export button */
+    showExport: boolean;
+    /** Show refresh button */
+    showRefresh: boolean;
+    /** Show column chooser button */
+    showColumnChooser: boolean;
+    /** Custom toolbar buttons */
+    customButtons: GridToolbarButton[];
+}
+/** Configuration for card view alternative layout */
+interface GridCardViewConfig {
+    /** Whether card view is available */
+    enabled: boolean;
+    /** Number of cards per row */
+    cardsPerRow: number;
+    /** Card height in pixels */
+    cardHeight: number;
+    /** Field to use as card title */
+    titleField?: string;
+    /** Field to use as card subtitle */
+    subtitleField?: string;
+    /** Field to use as card image */
+    imageField?: string;
+}
+/**
+ * Top-level grid customizer definition.
+// ─── Nested Relationship Binding ─────────────────────────────────────────────
+
+/**
+ * Records which Dataverse relationship links a parent grid to its nested
+ * child grid. Stored on `GridCustomizerDefinition.nestedRelationship`.
+ *
+ * - `parentField` is the attribute on the parent row whose value gets
+ *   substituted into the child grid's FetchXML placeholder.
+ * - `childField` is the FK on the child entity that holds the parent's id.
+ *
+ * Example for Account → Contacts via `contact_customer_accounts`:
+ *   parentField = "accountid", childField = "parentcustomerid",
+ *   relatedEntity = "contact", relationshipType = "OneToMany".
+ */
+interface GridNestedRelationship {
+    /** Dataverse relationship SchemaName. */
+    schemaName: string;
+    /** Relationship type. */
+    relationshipType: 'OneToMany' | 'ManyToOne';
+    /** Child entity logical name (should match the nested grid's dataSource.entityName). */
+    relatedEntity: string;
+    /** Parent attribute that provides the id to substitute into the child FetchXML. */
+    parentField: string;
+    /** Child attribute holding the FK back to the parent. */
+    childField: string;
+    /** Friendly label shown in the designer + codegen comments. */
+    displayName?: string;
+}
+/** Configuration for lookup preview cards shown on hover */
+interface LookupPreviewConfig {
+    /** Master toggle for the entire grid */
+    enabled: boolean;
+    /** Hover delay in ms before showing preview (default: 300) */
+    hoverDelay?: number;
+    /** Card width in pixels (default: 320) */
+    cardWidth?: number;
+}
+/**
+ * How nested-grid child records surface to the user. The `inline` mode is the
+ * legacy chevron-expand affordance available on standard / editable / readonly
+ * grids. The other three modes are required for `focused-view` and `card-list`
+ * grids, which have no row-level chevron column.
+ *
+ * - `inline`         — chevron expand under the parent row (DetailsList only)
+ * - `detail-pane`    — render child grid inside the focused-view detail panel
+ * - `side-panel`     — click "View N related" → opens a Panel with full child grid
+ * - `hover-callout`  — hover a count badge → compact callout preview (top N rows)
+ */
+type NestedDisplayMode = 'inline' | 'detail-pane' | 'side-panel' | 'hover-callout';
+/** Side-panel size token shared with Fluent UI Panel sizes */
+type NestedSidePanelSize = 'small' | 'medium' | 'large';
+/**
+ * Configuration for how a parent grid's nested grid (`nestedGridId`) surfaces
+ * its child records. Lives on the parent `GridCustomizerDefinition` — the
+ * single source of truth — and is ignored when `nestedGridId` is unset.
+ *
+ * Defaults populated by the v11 → v12 migration based on parent `gridType`:
+ *   - focused-view → `{ mode: 'detail-pane' }`
+ *   - card-list    → `{ mode: 'side-panel', panelSize: 'medium' }`
+ *   - everything else → `{ mode: 'inline' }`
+ */
+interface NestedDisplayConfig {
+    /** How children are surfaced. */
+    mode: NestedDisplayMode;
+    /** Side-panel size when `mode === 'side-panel'`. Default: 'medium'. */
+    panelSize?: NestedSidePanelSize;
+    /** Hover delay (ms) when `mode === 'hover-callout'`. Default: 300. */
+    hoverDelay?: number;
+    /** Max rows shown in the hover-callout preview. Default: 5. */
+    calloutMaxRows?: number;
+    /**
+     * Trigger label rendered on cards / detail-pane buttons. Supports the
+     * `{count}` token for child-row count substitution. Default:
+     * "View {count} related".
+     */
+    triggerLabel?: string;
+    /** Fluent icon name for the trigger button. Default: 'OpenPaneMirrored'. */
+    triggerIcon?: string;
+}
+/**
+ * Lives at the project level (FormBuilderProject.gridCustomizers[]).
+ * Can be referenced by subgrid controls via gridCustomizerId.
+ */
+interface GridCustomizerDefinition {
+    /** Unique identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /**
+     * @deprecated Use `dataSource.entityName` instead. Kept for schema
+     * compatibility; the v6 → v7 migration synthesizes a `dataSource` from this
+     * field when it is the only signal available.
+     */
+    entityName?: string;
+    /**
+     * Dataverse data source this grid renders. When set, unlocks the column
+     * picker, metadata-aware previews, and DAL emission on export. Grids without
+     * a `dataSource` still work as free-form renderer overlays (legacy behavior).
+     */
+    dataSource?: FormDataSource;
+    /**
+     * Saved Dataverse view ID (`savedqueryid`/`userqueryid`) selected as the
+     * default view for this grid. When set, the dataSource.fetchXml is normally
+     * derived from this view's authored query. Optional — grids can also use
+     * custom FetchXML (`useCustomFetchXml`) or no view binding at all.
+     */
+    viewId?: string;
+    /**
+     * When true, `dataSource.fetchXml` is treated as user-authored and `viewId`
+     * is ignored. Mirrors the legacy subgrid-control `useCustomFetchXml` flag.
+     */
+    useCustomFetchXml?: boolean;
+    /** When true, runtime users can switch views from the grid header. */
+    allowViewChange?: boolean;
+    /** Column definitions */
+    columns: GridColumnDefinition[];
+    /**
+     * Layout/behavior mode. New code should branch on this enum; the older
+     * `isEditable` boolean and `cardView.enabled` flag are derived/back-filled
+     * from it for backward compatibility.
+     */
+    gridType?: GridType;
+    /**
+     * Maximum number of rows visible in the form-embedded preview / generated
+     * subgrid. Distinct from `pageSize` (which controls Dataverse paging in
+     * standalone PCF exports). Mirrors the legacy subgrid `maxRows`.
+     */
+    maxVisibleRows?: number;
+    /** Row selection mode */
+    selectionMode: GridSelectionMode;
+    /** Pagination strategy */
+    paginationMode: GridPaginationMode;
+    /** Rows per page */
+    pageSize: number;
+    /** Whether to show the command bar above the grid */
+    showCommandBar: boolean;
+    /**
+     * Whether command bar buttons display labels next to icons. When false,
+     * buttons render as icon-only. Per-item `iconOnly` overrides this for
+     * individual items. Defaults to true (set by the storage migration for
+     * legacy projects). Mirrors `form.settings.showCommandBarLabels`.
+     */
+    showCommandBarLabels?: boolean;
+    /**
+     * Whether the grid allows inline cell editing. When false, all cells are
+     * read-only regardless of column-level editor settings. When true, cells
+     * can be edited unless the column has `isLocked` set.
+     */
+    isEditable: boolean;
+    /** Toolbar feature configuration */
+    toolbar: GridToolbarConfig;
+    /** Card view configuration */
+    cardView: GridCardViewConfig;
+    /** Whether to show the grid title/name header */
+    showTitle: boolean;
+    /** Use compact row height */
+    compactMode: boolean;
+    /** Alternate row background color */
+    alternateRowColor: boolean;
+    /** Colors for alternating rows (used when alternateRowColor is true) */
+    alternateRowColors?: {
+        even: string;
+        odd: string;
+    };
+    /** References another GridCustomizerDefinition by ID for expandable row detail */
+    nestedGridId?: string;
+    /**
+     * Controls whether child-row selection in the nested grid requires the parent
+     * row to be selected first. 'independent' (default) lets users tick child rows
+     * without selecting the parent; 'requires-parent' disables child checkboxes
+     * until the parent row is selected (gating).
+     */
+    nestedSelectionMode?: 'independent' | 'requires-parent';
+    /**
+     * When set, the nested grid is bound to a Dataverse relationship so each
+     * parent row expands to show its actual child records. Without this field
+     * the nested grid renders static/mock data (legacy behavior).
+     */
+    nestedRelationship?: GridNestedRelationship;
+    /**
+     * How nested-grid child records surface when the parent gridType doesn't
+     * support inline expansion (focused-view, card-list). Ignored when
+     * `nestedGridId` is unset. The v11 → v12 migration backfills sensible
+     * defaults based on the parent gridType.
+     */
+    nestedDisplay?: NestedDisplayConfig;
+    /** Command bar items (shown when showCommandBar is true) */
+    commandBarItems?: CommandBarItem[];
+    /** Lookup preview card configuration for hover-over-lookup behavior */
+    lookupPreview?: LookupPreviewConfig;
+    /** Chart pane configuration (only used when chart features are enabled) */
+    chart?: GridChartConfig;
+    /**
+     * Focused-view configuration. Populated from the legacy subgrid
+     * `focusedViewConfig` / `primaryNameField` / `summaryFields` properties
+     * during migration. Read only when `gridType === 'focused-view'`.
+     */
+    focusedView?: GridFocusedViewSettings;
+    /** Sample data rows for preview */
+    sampleData?: Record<string, unknown>[];
+    /** How sample data is sourced */
+    sampleDataMode: 'auto' | 'manual' | 'dataverse';
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last modification */
+    updatedAt: string;
+}
+/** Generate a unique ID for grid customizer entities */
+declare function generateGridId(prefix?: string): string;
+/** Create a default grid column definition */
+declare function createDefaultGridColumn(overrides?: Partial<GridColumnDefinition>): GridColumnDefinition;
+/** Create a default grid toolbar configuration */
+declare function createDefaultToolbarConfig(): GridToolbarConfig;
+/** Create a default card view configuration */
+declare function createDefaultCardViewConfig(): GridCardViewConfig;
+/** Create a default grid customizer definition */
+declare function createDefaultGridCustomizer(overrides?: Partial<GridCustomizerDefinition>): GridCustomizerDefinition;
+/** Create a default composite slot */
+declare function createDefaultCompositeSlot(type?: CompositeSlotType): CompositeSlot;
+/** Create a default composite renderer config */
+declare function createDefaultCompositeRendererConfig(): CompositeRendererConfig;
+
+export { type AggregateFunction as A, createDefaultCompositeSlot as B, type CellEditorType as C, createDefaultFocusedViewConfig as D, createDefaultGridColumn as E, FOCUSED_VIEW_ICON_OPTIONS as F, type GridCardViewConfig as G, createDefaultGridCustomizer as H, createDefaultToolbarConfig as I, generateGridId as J, isValidFocusedViewConfig as K, type LegacySummaryField as L, MAX_FOCUSED_VIEW_ROWS as M, type NestedDisplayConfig as N, migrateLegacyConfig as O, type CellRendererType as a, type CompositeRendererConfig as b, type CompositeSlot as c, type CompositeSlotType as d, type ConditionalStyle as e, type FocusedViewConfig as f, type FocusedViewField as g, type FocusedViewRow as h, type GridChartConfig as i, type GridColumnDataType as j, type GridColumnDefinition as k, type GridColumnInput as l, type GridCustomizerDefinition as m, type GridFocusedViewSettings as n, type GridNestedRelationship as o, type GridPaginationMode as p, type GridSelectionMode as q, type GridToolbarButton as r, type GridToolbarConfig as s, type GridType as t, type LookupPreviewConfig as u, type NestedDisplayMode as v, type NestedSidePanelSize as w, createConfigFromColumns as x, createDefaultCardViewConfig as y, createDefaultCompositeRendererConfig as z };