@dataverse-kit/export-engine 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,658 @@
+import { FormDefinition, BusinessRuleDefinition, RuleVariable, WorkflowDefinition, BusinessProcessFlowDefinition, FormSelectorRule, GridCustomizerDefinition, ControlType, GridColumnDefinition, SubgridColumn, GridColumnDataType } from '@dataverse-kit/form-runtime/types';
+export { V8_ICONS_WITHOUT_V9, V8_PERSONA_SIZE_TO_V9, V8_PRESENCE_TO_V9_STATUS, V8_TO_V9_ICON_MAP, V9IconName, buildV9IconImport, mapV8IconToV9, mapV8PersonaSizeToV9, mapV8PresenceToV9Status, sanitizeV8EnumIdentifier, sanitizeV8PersonaSizeName, sanitizeV8PresenceName } from '@dataverse-kit/form-runtime/icons';
+
+/**
+ * Export-pipeline types owned by export-engine.
+ *
+ * These are export concepts (target / method / options) — they belong to the
+ * export package, not the app. The form-builder app and the design-only fork
+ * each keep their own `types/export.ts`; those are structurally identical, so
+ * an app's `ExportOptions`/`ExportTarget` is assignable at the `exportProject`
+ * call boundary without either app importing from the other.
+ */
+type ExportTarget = 'web-resource' | 'pcf' | 'static-web-app';
+type ExportMethod = 'zip' | 'folder';
+type DeployTarget = {
+    type: 'none';
+} | {
+    type: 'app';
+    appId: string;
+    title?: string;
+};
+interface ExportOptions {
+    target: ExportTarget;
+    projectName: string;
+    namespace?: string;
+    publisherPrefix?: string;
+    includeDeployScript: boolean;
+    minify: boolean;
+    exportMethod: ExportMethod;
+    dataverseUrl?: string;
+    deployTarget?: DeployTarget;
+    includeSampleData?: boolean;
+    /**
+     * When set, overrides the smart default for generating the DAL (models,
+     * constants, hooks). When undefined, the generator computes a default from
+     * the project's bindings and saved preferences.
+     */
+    generateDataAccessLayer?: boolean;
+    /**
+     * Per-export override for the component library used by generated code.
+     * Precedence: this field → `project.componentLibrary` → `'fluent-v8'`.
+     */
+    componentLibrary?: 'fluent-v8' | 'fluent-v9';
+    /**
+     * When true, the export engine additionally emits a "rich entity models"
+     * tree under `src/entities/` produced by `@dataverse-kit/entity-gen`
+     * (only when the rich-entity generator is registered — see ExportEngine's
+     * registration seam). Additive; the `generateDataAccessLayer` output is
+     * untouched.
+     */
+    useRichEntityModels?: boolean;
+    /**
+     * Snapshot of Dataverse metadata cached in the UI at export time, keyed by
+     * entity logical name. ExportEngine is a pure library — it can't reach into
+     * a store — so the snapshot is plumbed through here. Only consumed when
+     * `useRichEntityModels` is on.
+     */
+    dataverseMetadataSnapshot?: Record<string, unknown>;
+}
+
+/**
+ * Project model as export-engine sees it.
+ *
+ * Owned here (not imported from an app) so the package has no dependency on
+ * `apps/*`. The Dataverse-subsystem fields are optional and typed from the
+ * shared `@dataverse-kit/form-runtime` types — so both the form-builder app's
+ * full project (which populates them) and the design-only fork's stripped
+ * project (which omits them) are structurally assignable at the export
+ * boundary. Each app still owns its own canonical `FormBuilderProject`; this is
+ * the structural contract export-engine consumes.
+ */
+
+/**
+ * Export-time options that persist per project so the user's last choice is
+ * remembered. Generators still compute smart defaults when a field is unset.
+ */
+interface ProjectExportOptions {
+    generateDataAccessLayer?: boolean;
+    includeSampleData?: boolean;
+}
+interface FormBuilderProject {
+    id: string;
+    name: string;
+    description: string;
+    exportTarget: ExportTarget;
+    componentLibrary: 'fluent-v8' | 'fluent-v9';
+    forms: FormDefinition[];
+    createdAt: string;
+    updatedAt: string;
+    dataverseUrl?: string;
+    /** Schema version for project-level migrations. */
+    schemaVersion: number;
+    businessRules?: BusinessRuleDefinition[];
+    sharedVariables?: RuleVariable[];
+    workflows?: WorkflowDefinition[];
+    businessProcessFlows?: BusinessProcessFlowDefinition[];
+    formSelectorRules?: FormSelectorRule[];
+    gridCustomizers?: GridCustomizerDefinition[];
+    /** Per-project export preferences that survive across sessions. */
+    exportOptions?: ProjectExportOptions;
+}
+
+/**
+ * Shared helper for resolving the effective component library (Fluent UI v8
+ * or v9) for a given export. Generators call this so the precedence rule
+ * lives in one place.
+ *
+ * Phase 3a wires this through to every generator but no generator branches
+ * on it yet — output remains v8 for now. Phases 3b–3e add the v9 code paths.
+ */
+
+type ComponentLibrary = 'fluent-v8' | 'fluent-v9';
+/**
+ * Returns the effective component library for a project/export.
+ *
+ * Priority:
+ *   1. Explicit ExportOptions.componentLibrary if present
+ *   2. Project-level FormBuilderProject.componentLibrary
+ *   3. 'fluent-v8' (legacy default — preserves current behavior)
+ */
+declare function resolveComponentLibrary(project: FormBuilderProject, options?: ExportOptions): ComponentLibrary;
+
+/** Result of generating code for a single form. */
+interface GeneratedFile {
+    path: string;
+    content: string;
+}
+/** Options for form code generation. */
+interface GenerateFormCodeOptions {
+    /** 'overlay' wraps in Dialog/Panel/Callout; 'fullpage' renders directly for solo web resources. */
+    renderMode?: 'overlay' | 'fullpage';
+    /** When true, integrates useBusinessRules hook for runtime visibility/lock/required. */
+    hasBusinessRules?: boolean;
+    /** Grid customizer definitions from the project — enables inline renderer generation for linked subgrids. */
+    gridCustomizers?: GridCustomizerDefinition[];
+    /** When true, populates subgrids with sample data instead of empty arrays. */
+    includeSampleData?: boolean;
+    /**
+     * When true, subgrids emit helper components that consume the DAL hooks
+     * generated by EntityDataLayerGenerator. Callers should only enable this
+     * when they are also emitting the DAL files alongside the form code.
+     */
+    includeDataAccessLayer?: boolean;
+    /**
+     * Reserved for the v9 code path. Phase 3a wires this through but the
+     * generator currently emits Fluent UI v8 only. Phases 3b-3e will branch
+     * imports, control mappings, theme provider, and styles based on this.
+     */
+    componentLibrary?: 'fluent-v8' | 'fluent-v9';
+}
+/** Generate React component source files from a FormDefinition. */
+declare function generateFormCode(form: FormDefinition, options?: GenerateFormCodeOptions): GeneratedFile[];
+/** Options for `generateAllFormCode`. */
+interface GenerateAllFormCodeOptions {
+    /** Per-form render mode. Defaults to 'overlay' for any form not listed. */
+    renderModes?: Record<string, 'overlay' | 'fullpage'>;
+    /** When true, integrates useBusinessRules hook for runtime visibility/lock/required. */
+    hasBusinessRules?: boolean;
+    /** Grid customizer definitions from the project — enables inline renderer generation for linked subgrids. */
+    gridCustomizers?: GridCustomizerDefinition[];
+    /** When true, populates subgrids with sample data instead of empty arrays. */
+    includeSampleData?: boolean;
+    /** When true, subgrids emit helper components that consume the DAL hooks. */
+    includeDataAccessLayer?: boolean;
+    /** Reserved for the v9 code path; Phase 3a does not branch on this. */
+    componentLibrary?: 'fluent-v8' | 'fluent-v9';
+}
+/** Generate code for all forms in a project and an index barrel. */
+declare function generateAllFormCode(forms: FormDefinition[], options?: GenerateAllFormCodeOptions): GeneratedFile[];
+
+/**
+ * Phase 3f.1 review fix — shared v9 control-type compatibility constants.
+ *
+ * Both `v9CompatibilityScanner` (consumer-facing) and `FormCodeGenerator`
+ * (generator-facing) need to know which control types lack a Fluent UI
+ * v9 equivalent. Extracting the constant + predicate here breaks the
+ * scanner→generator import edge that the architectural review flagged
+ * and gives any future consumer (UI badges, custom-control manifests,
+ * exporter validation) a stable, dependency-free import target.
+ *
+ * Edit `V9_INCOMPATIBLE_CONTROL_TYPES` to add a new Track B control.
+ * Reasons live in the scanner module (UI-facing copy).
+ */
+
+/**
+ * Set of control types with no Fluent UI v9 equivalent. Track B in the
+ * Phase 3f migration plan — these controls are excluded from v9 exports
+ * (placeholder div emitted, ExportDialog warning shown) rather than
+ * migrated.
+ */
+declare const V9_INCOMPATIBLE_CONTROL_TYPES: ReadonlySet<ControlType>;
+/**
+ * Test whether a control type can be emitted under Fluent UI v9. A
+ * compatible control either has a v9 equivalent today or has one
+ * planned in a future Phase 3f sub-phase (currently emitting v8
+ * fallback inside FluentProvider — still renders correctly).
+ */
+declare function isControlV9Compatible(controlType: ControlType): boolean;
+/**
+ * Phase 1b — symmetric counterpart to `V9_INCOMPATIBLE_CONTROL_TYPES`.
+ *
+ * Set of control types with no Fluent UI v8 equivalent in
+ * `@dataverse-kit/components`. These controls 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.
+ *
+ * Currently flagged via `requiresV9: true` on the ControlRegistryEntry in
+ * `apps/form-builder/src/utils/controlMetadata.ts`. The constant here is
+ * the authoritative list for the export-engine scanner; keeping the names
+ * synced between the form-builder registry and this set is enforced by
+ * tests in `v9CompatibilityScanner.test.ts`.
+ */
+declare const V9_REQUIRED_CONTROL_TYPES: ReadonlySet<ControlType>;
+/**
+ * Test whether a control type requires Fluent UI v9. A v9-required
+ * control has no v8 equivalent in the workspace component library and
+ * therefore cannot render under v8 export targets.
+ */
+declare function isControlV9Required(controlType: ControlType): boolean;
+
+/**
+ * Phase 3f.1 — v9 compatibility scanner.
+ *
+ * Walks a `FormBuilderProject` and reports every control whose type
+ * has no Fluent UI v9 equivalent. Used by:
+ *   1. ExportDialog — pre-export warning when user picks v9 + project
+ *      contains incompatible controls. User can cancel or proceed; if
+ *      they proceed, the generator emits a placeholder for the control
+ *      instead of the v8 component.
+ *   2. Designer canvas/palette — future hookup to badge incompatible
+ *      controls with a ⚠ icon when project's componentLibrary is v9.
+ *
+ * **Track A** controls (have v9 equivalent — to be migrated in 3f.2–3f.7)
+ * are NOT reported. Until their migration ships they keep emitting v8
+ * fallback inside FluentProvider, which works correctly.
+ *
+ * **Track B** controls (no v9 equivalent — permanently excluded under v9):
+ *   - `rating`     — no v9 control
+ *   - `timeline`   — custom Dynamics surface, no v9 equivalent
+ *   - `webresource` — embeds v8 HTML resources, not applicable to v9
+ *
+ * Custom controls (Item 6, future) will declare their own
+ * `componentLibraryCompatibility` in their manifest. When that lands,
+ * extend `isControlV9Compatible` to consult the manifest registry.
+ */
+
+/**
+ * Why a control is incompatible with v9. Today only one reason exists,
+ * but the scanner returns it as a tagged value so the warning UI can
+ * render different copy per category and so future categories (e.g.
+ * `'custom-control-no-v9-decl'` from Item 6) slot in cleanly.
+ */
+type V9IncompatibilityReason = 'no-v9-control';
+/** A specific incompatible control's location in the project. */
+interface V9IncompatibleRef {
+    /** Control type string (e.g. `'rating'`). */
+    controlType: ControlType;
+    /** Author-friendly name for the control (e.g. `'starRating'`). */
+    controlName: string;
+    /** Author-friendly label (e.g. `'Customer Satisfaction'`). */
+    controlLabel: string;
+    /** Reason category for the warning UI. */
+    reason: V9IncompatibilityReason;
+    /** Human-readable explanation for the warning UI. */
+    reasonText: string;
+    /** Form containing the control. */
+    formId: string;
+    formName: string;
+    /** Tab containing the control (only for main forms). */
+    tabId?: string;
+    tabLabel?: string;
+    /** Section containing the control. `'header'` for header cells, `'callout:<id>'` for callout sections. */
+    sectionId: string;
+    sectionLabel: string;
+    /** Cell containing the control. */
+    cellId: string;
+}
+/** Result returned from `scanV9Compatibility`. */
+interface V9CompatibilityResult {
+    /** Controls that will be omitted from v9 output (placeholder emitted instead). */
+    excluded: V9IncompatibleRef[];
+    /** Convenience flag: true iff `excluded.length === 0`. */
+    isCompatible: boolean;
+}
+/**
+ * Walk a project and collect every control whose type is in the v9
+ * incompatibility set. Idempotent and side-effect-free; safe to call
+ * from React render paths.
+ */
+declare function scanV9Compatibility(project: FormBuilderProject): V9CompatibilityResult;
+/**
+ * Format a result as a single human-readable summary string. Used by
+ * ExportDialog when the warning needs to be inlined (e.g. small
+ * MessageBar variants without a list view). Returns empty string when
+ * `result.isCompatible` is true.
+ */
+declare function summarizeV9Incompatibility(result: V9CompatibilityResult): string;
+/**
+ * Why a control requires v9. Today only one reason exists (no v8 equivalent
+ * in `@dataverse-kit/components`), but the tagged value lets future
+ * categories — e.g. custom controls declaring `requiresV9` in their
+ * manifest — slot in cleanly.
+ */
+type V9RequirementReason = 'no-v8-control';
+/** A specific v9-required control's location in the project. */
+interface V9RequiredRef {
+    controlType: ControlType;
+    controlName: string;
+    controlLabel: string;
+    reason: V9RequirementReason;
+    reasonText: string;
+    formId: string;
+    formName: string;
+    tabId?: string;
+    tabLabel?: string;
+    sectionId: string;
+    sectionLabel: string;
+    cellId: string;
+}
+/** Result returned from `scanV9Requirements`. */
+interface V9RequirementResult {
+    /** Controls that cannot render under v8 export targets. */
+    required: V9RequiredRef[];
+    /** Convenience flag: true iff `required.length === 0`. */
+    isV8Compatible: boolean;
+}
+/**
+ * Walk a project and collect every control whose type is in the v9-required
+ * set. Uses the shared `walkProjectControls` engine so designer/preview/
+ * generator/scanner all visit the same surfaces by construction.
+ *
+ * Used by:
+ *   1. ExportDialog — disables v8-only target options + shows error
+ *      MessageBar listing the offending controls when the project has any.
+ *   2. `validateExportTarget` in the export-engine entry — rejects v8
+ *      target exports with a typed `V9RequirementError` for headless
+ *      callers that skip the dialog.
+ */
+declare function scanV9Requirements(project: FormBuilderProject): V9RequirementResult;
+/**
+ * Single human-readable summary for the requirement result. Mirrors
+ * `summarizeV9Incompatibility` so ExportDialog can use either consistently.
+ */
+declare function summarizeV9Requirements(result: V9RequirementResult): string;
+
+/**
+ * Rich-entity (Dataverse codegen) generator — injected via a registration
+ * seam instead of a static import so the entity-gen package is NOT pulled into
+ * browser builds that don't use it. The full root barrel (`./index`) registers
+ * the real `generateRichEntityModelFiles`; the browser barrel (`./browser`)
+ * does not register anything, so design-only consumers never bundle entity-gen.
+ * When unregistered, `generateProjectFiles` simply emits no rich-entity files.
+ */
+type RichEntityGenerator = (project: FormBuilderProject, options: ExportOptions) => GeneratedFile[];
+declare function registerRichEntityGenerator(fn: RichEntityGenerator | null): void;
+/**
+ * Thrown by `exportProject` / `validateExportTarget` when the chosen
+ * export target cannot host a v9-required control. Callers (CLI, headless
+ * pipelines, or the ExportDialog as a defense-in-depth) should catch this
+ * and surface the offending control list rather than retrying.
+ */
+declare class V9RequirementError extends Error {
+    readonly required: V9RequiredRef[];
+    constructor(required: V9RequiredRef[]);
+}
+/**
+ * Pre-export gate: when the resolved component library is v8 and the
+ * project contains any v9-required controls (funnel/scatter), reject
+ * the export with a typed error listing the offenders.
+ *
+ * The ExportDialog blocks this via UI affordances, but headless callers
+ * (CLI, batch pipelines, future automation) bypass the dialog — keeping
+ * the gate at the engine layer protects them too.
+ *
+ * **Critical**: resolves the effective library via `resolveComponentLibrary`
+ * before checking. `options.componentLibrary` is allowed to be undefined
+ * (precedence: option → project.componentLibrary → 'fluent-v8'). Without
+ * the resolver the gate would fail open when a caller passes undefined on
+ * a project whose stored default is v8.
+ */
+declare function validateExportTarget(project: FormBuilderProject, options: ExportOptions): {
+    ok: true;
+} | {
+    ok: false;
+    reason: V9RequirementError;
+};
+/** Export project using the chosen method (ZIP download or folder picker). */
+declare function exportProject(project: FormBuilderProject, options: ExportOptions): Promise<void>;
+/**
+ * Preview generated files without downloading. Does NOT enforce the
+ * v9-required gate — preview is a read-only inspection used by the dialog
+ * to show the file tree even when the export would be blocked. Callers
+ * that need the gate should invoke `validateExportTarget` themselves.
+ */
+declare function previewExport(project: FormBuilderProject, options: ExportOptions): GeneratedFile[];
+
+/** Generate a complete CRA + rewire project for Dynamics 365 Web Resources. */
+declare function generateWebResourceProject(project: FormBuilderProject, options?: ExportOptions): GeneratedFile[];
+
+/** Generate a PCF control scaffold that embeds the generated forms. */
+declare function generatePcfProject(project: FormBuilderProject, options?: ExportOptions): GeneratedFile[];
+
+/** Generate a standard Vite + React project for Azure Static Web Apps or standalone hosting. */
+declare function generateStaticWebAppProject(project: FormBuilderProject, options?: ExportOptions): GeneratedFile[];
+
+/**
+ * BusinessRuleCodeGenerator — Generates TypeScript code for business rules.
+ *
+ * Outputs:
+ * - Rule definitions as typed constants
+ * - useBusinessRules hook for runtime evaluation
+ * - FetchXML helper utilities for data source resolution
+ * - Deployment manifest for Dataverse rule table
+ */
+
+interface BusinessRuleCodeGenOptions {
+    /** Include inline comments explaining rule logic */
+    includeComments?: boolean;
+    /** Generate deployment manifest for Dataverse */
+    generateManifest?: boolean;
+    /** Entity logical name for the rules */
+    entityLogicalName?: string;
+    /** Publisher prefix for web resources */
+    publisherPrefix?: string;
+}
+/**
+ * Generate all business rule related files.
+ */
+declare function generateBusinessRuleCode(rules: BusinessRuleDefinition[], workflows?: WorkflowDefinition[], sharedVariables?: RuleVariable[], options?: BusinessRuleCodeGenOptions): GeneratedFile[];
+
+/**
+ * Generates a typed Dataverse data-access layer (constants + models + hooks +
+ * sample data) from the entities referenced by a project's forms and/or grid
+ * customizers.
+ *
+ * The form-builder already owns every piece of metadata needed to stop emitting
+ * `items={[]}` subgrid stubs: bound-control attribute logical names and types,
+ * option-set values with labels, lookup target lists, FetchXML data sources,
+ * and grid customizer data sources. This generator walks that metadata and
+ * produces:
+ *
+ *   src/constants/{Entity}Constants.ts   — attribute logical names + option set enums
+ *   src/models/{Entity}.ts               — BaseModel subclass + static list/retrieve/save
+ *   src/hooks/use{Entities}.ts           — useDataverseQuery-backed list + single record
+ *   src/sampleData/{entity}.json         — mock rows matching the model shape (optional)
+ *   src/constants/index.ts, models/index.ts, hooks/index.ts — barrels
+ *   src/lib/dataverse/*                  — inline runtime (BaseModel, hooks, FetchXML builder)
+ *
+ * Generated files import shared primitives from `../lib/dataverse` (inlined by
+ * `dalInlineTemplates`) so exported projects are self-contained.
+ */
+
+interface GenerateDataLayerOptions {
+    /** When true, `src/sampleData/{entity}.json` files are emitted. */
+    includeSampleData?: boolean;
+}
+interface EntityUsageAttribute {
+    logicalName: string;
+    /** Raw `attributeType` from the control binding ("SingleLineOfText", "DateTime", etc.) */
+    rawType: string;
+    /** Normalized type used by constants/models/schema. */
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'datetime' | 'lookup' | 'optionset' | 'money' | 'memo';
+    required: boolean;
+    maxLength?: number;
+    lookupTargets?: string[];
+    optionSetOptions?: Array<{
+        value: number;
+        label: string;
+    }>;
+}
+interface EntityUsage {
+    entityName: string;
+    entityCollectionName: string;
+    primaryIdAttribute: string;
+    primaryNameAttribute: string;
+    displayName: string;
+    attributes: Map<string, EntityUsageAttribute>;
+    /** Base FetchXML literal (from the form's data source, if any) that list hooks can parameterize. */
+    baseFetchXml?: string;
+}
+/**
+ * Walks all forms and returns an `EntityUsage` map keyed by entity logical name.
+ *
+ * When `gridCustomizers` is passed, subgrids whose `gridCustomizerId` resolves
+ * to a grid definition with a `dataSource` contribute the richer FetchXML +
+ * attribute list from that grid, replacing the bare `entityName`-only path.
+ */
+declare function collectEntityUsage(forms: FormDefinition[], gridCustomizers?: GridCustomizerDefinition[]): Map<string, EntityUsage>;
+/**
+ * Builds an `EntityUsage` map from a single grid customizer's data source.
+ * Used by the grid-scoped DAL generator (standalone PCF / components-only).
+ *
+ * When the grid has a `nestedRelationship` pointing at a linked nested grid,
+ * the nested child entity is walked too so the generated DAL emits model +
+ * constants + hook files for both parent and child.
+ */
+declare function collectEntityUsageFromGrid(grid: GridCustomizerDefinition, allGrids?: GridCustomizerDefinition[]): Map<string, EntityUsage>;
+/**
+ * Form-driven entry point — returns generated files for every entity referenced
+ * by the given forms, resolving subgrid → gridCustomizerId → dataSource links.
+ */
+declare function generateDataAccessLayer(forms: FormDefinition[], options?: GenerateDataLayerOptions, gridCustomizers?: GridCustomizerDefinition[]): GeneratedFile[];
+/**
+ * Grid-driven entry point — emits the DAL file tree for a single grid
+ * customizer. Used by Standalone PCF and Components Only grid exports.
+ */
+declare function generateDataAccessLayerForGrid(grid: GridCustomizerDefinition, options?: GenerateDataLayerOptions, allGrids?: GridCustomizerDefinition[]): GeneratedFile[];
+
+/**
+ * Strip non-alphanumeric chars (keep spaces/underscores/dashes as split
+ * points), then PascalCase. Result is always a valid TypeScript/JavaScript
+ * identifier — leading digits get a `_` prefix because `export class 123`
+ * would otherwise be a syntax error in the generated code.
+ */
+declare function toPascalCase(s: string): string;
+/** PascalCase name that always ends with exactly one "Form" suffix. */
+declare function toFormComponentName(s: string): string;
+/** Safe kebab-case for file/folder names. */
+declare function toSafeFileName(s: string): string;
+
+interface CommandEntry {
+    command: string;
+    description: string;
+    category: 'setup' | 'development' | 'build' | 'deploy';
+}
+declare const categoryLabels: Record<CommandEntry['category'], string>;
+declare const CATEGORY_ORDER: CommandEntry['category'][];
+
+declare function getCommandReference(target: ExportTarget, projectName: string, namespace?: string): CommandEntry[];
+/** Generate a README.md from the command reference. */
+declare function generateReadme(target: ExportTarget, projectName: string, namespace?: string): string;
+
+/**
+ * Shared helpers for deciding whether to emit the generated data-access
+ * layer and for injecting the required package dependency into generated
+ * `package.json` files.
+ *
+ * Downstream generators (WebResource, StaticWebApp, PCF) call these so the
+ * DAL integration logic lives in one place.
+ */
+
+/**
+ * The DAL runtime is inlined into generated projects under `src/lib/dataverse/`,
+ * so no private npm dependency is required. Only the React Query dependency
+ * (which is public) gets injected into the generated `package.json`.
+ */
+/**
+ * Returns the effective "generate data access layer" flag for a project/export.
+ *
+ * Priority:
+ *   1. Explicit ExportOptions.generateDataAccessLayer if present
+ *   2. Project-level saved preference under project.exportOptions.generateDataAccessLayer
+ *   3. Smart default — on when any form has at least one bound attribute
+ */
+declare function resolveDataAccessLayerFlag(project: FormBuilderProject, options?: ExportOptions): boolean;
+/**
+ * Injects the public dependencies that the inlined DAL runtime requires into a
+ * generated `package.json`. Today that is just React Query — everything else
+ * in `src/lib/dataverse/` relies only on built-in Web APIs (`fetch`) and the
+ * app's existing React dependency.
+ */
+declare function ensureDataAccessLayerDependency(dependencies: Record<string, string>, enabled: boolean): void;
+
+/**
+ * Grid Customizer Code Generator
+ *
+ * Generates PCF Grid Customizer code from GridCustomizerDefinition.
+ * Two export modes:
+ *   - 'full': Complete PCF project with webpack, package.json, etc.
+ *   - 'components-only': Just the renderer files + types + barrel export
+ *
+ * Output uses Fluent UI v9 to match Microsoft's Grid Customizer docs.
+ *
+ * Note: `nestedSelectionMode` (independent vs requires-parent gating) is only
+ * honored by FormCodeGenerator's nested-grid emission today. The PA Grid Control
+ * and components-only export modes don't emit nested grids, so the setting is
+ * silently dropped here — extending it is tracked separately.
+ */
+
+type GridExportMode = 'full' | 'components-only' | 'pa-grid-control';
+interface GridExportOptions {
+    mode: GridExportMode;
+    namespace?: string;
+    /**
+     * Emit the typed data-access layer (models, constants, hooks, inline runtime)
+     * alongside the renderer output. Applies to `full` and `components-only`
+     * modes; ignored for `pa-grid-control` which overlays Microsoft's grid and
+     * has no data of its own. Defaults to on when the grid has a `dataSource`
+     * and the mode supports it.
+     */
+    includeDataAccessLayer?: boolean;
+    /** When true, also emits `src/sampleData/{entity}.json` mock rows. */
+    includeSampleData?: boolean;
+    /**
+     * Full grid customizer list from the owning project. Required for nested
+     * relationship exports — the linked nested grid's data source drives the
+     * child entity's DAL emission + the parameterized hook filter.
+     */
+    allGrids?: GridCustomizerDefinition[];
+    /**
+     * Library used for cell-renderer + cell-editor emission in modes `full`
+     * and `components-only`. Defaults to 'fluent-v9' (the original behavior).
+     * Power Pages portals and Canvas App PCF controls need 'fluent-v8'.
+     * The `pa-grid-control` mode IGNORES this — it's a v8 platform contract
+     * and always emits v8 regardless.
+     */
+    componentLibrary?: 'fluent-v8' | 'fluent-v9';
+}
+/**
+ * Resolves the effective "include data access layer" flag for a grid export.
+ * Standalone PCF (`full`) and Components Only emit DAL when the grid has a
+ * data source. PA Grid Control never emits DAL.
+ */
+declare function resolveGridDalFlag(def: GridCustomizerDefinition, options: GridExportOptions): boolean;
+declare function generateGridCustomizerProject(def: GridCustomizerDefinition, options?: GridExportOptions): GeneratedFile[];
+
+/**
+ * Mock Data Generator
+ *
+ * Shared utility for generating type-aware mock/sample data for grid previews.
+ * Used by ControlRenderer (subgrid preview) and GridCustomizer (grid preview).
+ *
+ * Extracted from ControlRenderer.tsx to avoid duplication.
+ */
+
+/**
+ * Given a raw Dataverse row (with all its `@OData.Community.Display.V1.FormattedValue`
+ * and `_lookup_value` annotations), return a shape where each column's
+ * `fieldName` maps to the best display value. Preference order per column:
+ *
+ *   1. `fieldName@OData.Community.Display.V1.FormattedValue` — option set label,
+ *      localized date, formatted money, etc.
+ *   2. `_fieldName_value@OData.Community.Display.V1.FormattedValue` — lookup
+ *      display name when the fieldName is a lookup attribute.
+ *   3. `_fieldName_value` — lookup id as last resort.
+ *   4. `row[fieldName]` — the raw value (plain strings, numbers, dates).
+ *
+ * Non-mentioned columns pass through untouched so annotation-less fields stay
+ * intact. The returned row is a fresh object — the input is not mutated.
+ */
+declare function flattenDataverseRowForPreview(row: Record<string, unknown>, columns: GridColumnDefinition[]): Record<string, unknown>;
+/** Base mock value pools keyed by field name or data type */
+declare const MOCK_VALUE_POOLS: Record<string, string[]>;
+/**
+ * Generate mock rows for a subgrid/DetailsList preview.
+ * Uses SubgridColumn[] interface from the existing form control system.
+ */
+declare function generateMockSubgridData(columns: SubgridColumn[], maxRows: number): Record<string, string>[];
+/** Extended mock value pools for grid customizer data types */
+declare const TYPED_MOCK_POOLS: Record<GridColumnDataType, unknown[]>;
+/**
+ * Generate type-aware mock rows for grid customizer preview.
+ * Uses GridColumnDefinition[] interface with richer data types.
+ * Priority: renderer-specific pool > field-name pool > data-type pool.
+ */
+declare function generateMockGridData(columns: GridColumnDefinition[], rowCount?: number): Record<string, unknown>[];
+
+export { type BusinessRuleCodeGenOptions, categoryLabels as CATEGORY_LABELS, CATEGORY_ORDER, type CommandEntry, type ComponentLibrary, type EntityUsage, type EntityUsageAttribute, type GenerateAllFormCodeOptions, type GenerateDataLayerOptions, type GenerateFormCodeOptions, type GeneratedFile, type GridExportMode, type GridExportOptions, MOCK_VALUE_POOLS, type RichEntityGenerator, TYPED_MOCK_POOLS, type V9CompatibilityResult, type V9IncompatibilityReason, type V9IncompatibleRef, type V9RequiredRef, V9RequirementError, type V9RequirementReason, type V9RequirementResult, V9_INCOMPATIBLE_CONTROL_TYPES, V9_REQUIRED_CONTROL_TYPES, collectEntityUsage, collectEntityUsageFromGrid, ensureDataAccessLayerDependency, exportProject, flattenDataverseRowForPreview, generateAllFormCode, generateBusinessRuleCode, generateDataAccessLayer, generateDataAccessLayerForGrid, generateFormCode, generateGridCustomizerProject, generateMockGridData, generateMockSubgridData, generatePcfProject, generateReadme, generateStaticWebAppProject, generateWebResourceProject, getCommandReference, isControlV9Compatible, isControlV9Required, previewExport, registerRichEntityGenerator, resolveComponentLibrary, resolveDataAccessLayerFlag, resolveGridDalFlag, scanV9Compatibility, scanV9Requirements, summarizeV9Incompatibility, summarizeV9Requirements, toFormComponentName, toPascalCase, toSafeFileName, validateExportTarget };