@svgrid/enterprise 2.6.0 → 2.6.1

package/dist/studio/index.d.ts

@@ -25,11 +25,11 @@ export { crudSuiteScreens, addCrudSuite, crudAppFromSchemas, listScreen, formScr
 export { sanitizeStudioProject, buildStudioBugReport, type SanitizeResult, type BugReport, type BugReportInput, type StudioEnv, } from './bug-report.js';
 export { generateValue, generateRows } from './sample-data.js';
 export { studioThemes, defaultStudioTheme, getStudioTheme, resolveThemeTokens, resolveThemeTokensFor, isDarkTheme, themeStyleString, type StudioTheme } from './themes.js';
-export { createProject, defaultScreenFor, defaultBlockConfig, gridColumns, entityOf, blockPalette, addBlock, addBlockAt, addComponentBlock, removeBlock, duplicateBlock, moveBlock, reorderBlock, updateBlock, addEntity, removeEntity, updateEntity, addScreen, addFreestandingScreen, addScreenAction, removeScreenAction, enableScreenCode, disableScreenCode, setScreenRenderGrid, screenLayoutOf, buildDockLayout, reconcileDock, syncDockPanes, setScreenLayout, isPaneLayout, PANE_LAYOUTS, buildCanvasLayout, canvasRectOf, setCanvasRect, CANVAS_COLS, CANVAS_ROW_PX, CANVAS_GAP_PX, type CanvasRect, applyGridPreset, gridPresetLabel, GRID_PRESETS, setScreenDock, reseedScreenDock, setDockPaneTitle, dockPaneTitleOf, dockPaneIds, setLayoutOpts, gridOpts, stackOpts, splitOpts, dockOpts, canvasOpts, type ScreenLayout, type GridPreset, type LayoutOpts, type GridLayoutOpts, type StackLayoutOpts, type SplitLayoutOpts, type DockLayoutOpts, type CanvasLayoutOpts, setHandlerBody, setScreenHandlersSource, setHandlerSteps, addHandlerStep, updateHandlerStep, moveHandlerStep, stepsToCode, compileStep, compileHandlerSteps, compileValue, compileCondition, compileTriggerStep, compileTriggerSteps, triggersOf, setTrigger, TRIGGER_EVENTS, type TriggerStep, type TriggerEvent, type EntityTriggers, setJob, type ScheduledJob, type ScheduledJobKind, setTenancy, tenantField, isTenantScoped, type TenancyConfig, clickSlot, ssrScreenShape, ssrEligible, withSsrDefaults, setScreenRenderMode, eventSlot, rowSelectSlot, changeSlot, FORM_SUBMIT, GRID_EVENTS, type GridEventDef, addStateVar, updateStateVar, removeStateVar, stateInitExpr, stateTsType, type ActionStep, type ActionStepType, type StateVar, type StateVarType, type LogicValue, type LogicOp, type Condition, type FieldValue, setComponentName, setComponentBinding, componentHasBindings, componentHandleName, ON_LOAD, removeScreen, updateScreen, duplicateScreen, reorderScreen, insertBlock, setDataSource, setDeployTarget, setAuth, setDataLayer, seedUsers, defaultEntitySource, flattenBlocks, TAB_CHILD_KINDS, CONTAINER_CHILD_KINDS, CONTAINER_DISPLAY_KINDS, addTab, removeTab, renameTab, addTabBlock, addTabComponent, removeTabBlock, addAccordionSection, removeAccordionSection, renameAccordionSection, setAccordionMultiple, addAccordionBlock, addAccordionComponent, removeAccordionBlock, setEntityDataSource, entityDataSource, setTheme, setThemePreset, setShell, sanitizeProject, screenFromTemplate, addScreenFromTemplate, serializeProject, parseProject, validateProject, isProjectValid, blockColumns, blockStyleCss, blockClassName, sanitizeClassName, mergeBlockStyle, type BlockStyle, roleCanScreen, roleCanAction, CRUD_ACTIONS, type CrudAction, type RoleAccess, type AccessControl, type AuthConfig, type OAuthProvider, type SeedUser, type I18nConfig, type DeployTarget, type StudioProject, type Screen, type ScreenNav, type Block, type BlockKind, type BlockConfig, type GridConfig, type GridColumnConfig, type ColumnFormat, type ColumnCellType, type GridExportConfig, type GridFilterUi, type TreeDataConfig, type SchedulerViewConfig, type SchedulerViewMode, type RowLink, type RowAction, type RowActionKind, type ActionConfig, type ComponentConfig, type ComponentBinding, type FormatOp, type FormatRule, type GridEditing, type GridDensity, type GridAlign, type PagerPosition, type FormConfig, type ChartConfig, type KpiConfig, type KpiFormat, type GaugeConfig, type TreeConfig, type TabsConfig, type StudioTab, type AccordionConfig, type AccordionSection, type DashboardConfig, type MasterDetailConfig, type LookupConfig, type PivotConfig, type FilterPanelConfig, type RecordConfig, type BoardConfig, type CalendarConfig, type DetailConfig, type DetailRelated, type Reduce, type DataSourceKind, type EntityDataSource, type MemorySource, type RestSource, type RestAdapterConfig, type SqlSource, type SupabaseSource, type PgliteSource, type RestMethod, type ParamLocation, type ParamType, type RequestParam, type SqlDialectKind, type ProjectTheme, type ShellConfig, type ShellStyle, type ScreenTemplate, type PaletteItem, type ProjectIssue, } from './project.js';
+export { createProject, defaultScreenFor, defaultBlockConfig, gridColumns, entityOf, blockPalette, addBlock, addBlockAt, addComponentBlock, removeBlock, duplicateBlock, moveBlock, reorderBlock, updateBlock, addEntity, removeEntity, updateEntity, formPlan, setEntityForm, setFormColumns, addFormSection, updateFormSection, removeFormSection, moveFormSection, moveFormField, moveFormFields, setFieldConditions, updateEntityField, setFieldInput, setFieldHidden, formControlsFor, formControlSettings, suggestFormSections, addScreen, addFreestandingScreen, addScreenAction, removeScreenAction, enableScreenCode, disableScreenCode, setScreenRenderGrid, screenLayoutOf, buildDockLayout, reconcileDock, syncDockPanes, setScreenLayout, isPaneLayout, PANE_LAYOUTS, buildCanvasLayout, canvasRectOf, setCanvasRect, CANVAS_COLS, CANVAS_ROW_PX, CANVAS_GAP_PX, type CanvasRect, applyGridPreset, gridPresetLabel, GRID_PRESETS, setScreenDock, reseedScreenDock, setDockPaneTitle, dockPaneTitleOf, dockPaneIds, setLayoutOpts, gridOpts, stackOpts, splitOpts, dockOpts, canvasOpts, type ScreenLayout, type GridPreset, type LayoutOpts, type GridLayoutOpts, type StackLayoutOpts, type SplitLayoutOpts, type DockLayoutOpts, type CanvasLayoutOpts, setHandlerBody, setScreenHandlersSource, setHandlerSteps, addHandlerStep, updateHandlerStep, moveHandlerStep, stepsToCode, compileStep, compileHandlerSteps, compileValue, compileCondition, compileTriggerStep, compileTriggerSteps, triggersOf, setTrigger, TRIGGER_EVENTS, type TriggerStep, type TriggerEvent, type EntityTriggers, setJob, type ScheduledJob, type ScheduledJobKind, setTenancy, tenantField, isTenantScoped, type TenancyConfig, clickSlot, ssrScreenShape, ssrEligible, withSsrDefaults, setScreenRenderMode, eventSlot, rowSelectSlot, changeSlot, FORM_SUBMIT, GRID_EVENTS, type GridEventDef, addStateVar, updateStateVar, removeStateVar, stateInitExpr, stateTsType, type ActionStep, type ActionStepType, type StateVar, type StateVarType, type LogicValue, type LogicOp, type Condition, type FieldValue, setComponentName, setComponentBinding, componentHasBindings, componentHandleName, ON_LOAD, removeScreen, updateScreen, duplicateScreen, reorderScreen, insertBlock, setDataSource, setDeployTarget, setAuth, setDataLayer, seedUsers, defaultEntitySource, flattenBlocks, TAB_CHILD_KINDS, CONTAINER_CHILD_KINDS, CONTAINER_DISPLAY_KINDS, addTab, removeTab, renameTab, addTabBlock, addTabComponent, removeTabBlock, addAccordionSection, removeAccordionSection, renameAccordionSection, setAccordionMultiple, addAccordionBlock, addAccordionComponent, removeAccordionBlock, setEntityDataSource, entityDataSource, setTheme, setThemePreset, setShell, sanitizeProject, screenFromTemplate, addScreenFromTemplate, serializeProject, parseProject, validateProject, isProjectValid, blockColumns, blockStyleCss, blockClassName, sanitizeClassName, mergeBlockStyle, type BlockStyle, roleCanScreen, roleCanAction, CRUD_ACTIONS, type CrudAction, type RoleAccess, type AccessControl, type AuthConfig, type OAuthProvider, type SeedUser, type I18nConfig, type DeployTarget, type StudioProject, type Screen, type ScreenNav, type Block, type BlockKind, type BlockConfig, type GridConfig, type GridColumnConfig, type ColumnFormat, type ColumnCellType, type GridExportConfig, type GridFilterUi, type TreeDataConfig, type SchedulerViewConfig, type SchedulerViewMode, type RowLink, type RowAction, type RowActionKind, type ActionConfig, type ComponentConfig, type ComponentBinding, type FormatOp, type FormatRule, type GridEditing, type GridDensity, type GridAlign, type PagerPosition, type FormConfig, type ChartConfig, type KpiConfig, type KpiFormat, type GaugeConfig, type TreeConfig, type TabsConfig, type StudioTab, type AccordionConfig, type AccordionSection, type DashboardConfig, type MasterDetailConfig, type LookupConfig, type PivotConfig, type FilterPanelConfig, type RecordConfig, type BoardConfig, type CalendarConfig, type DetailConfig, type DetailRelated, type Reduce, type DataSourceKind, type EntityDataSource, type MemorySource, type RestSource, type RestAdapterConfig, type SqlSource, type SupabaseSource, type PgliteSource, type RestMethod, type ParamLocation, type ParamType, type RequestParam, type SqlDialectKind, type ProjectTheme, type ShellConfig, type ShellStyle, type ScreenTemplate, type PaletteItem, type ProjectIssue, } from './project.js';
 export { verifyScaffold, summarizeVerify, type VerifyResult, type VerifyIssue, type VerifySeverity, } from './verify.js';
 export { UI_COMPONENT_REGISTRY, uiComponentSpec, gridPropSurface, gridApiSettableProps, GRID_CURATED_PROPS, STANDARD_UI_EVENTS, type UiPropType, type UiPropGroup, type UiComponentEvent, type UiComponentProp, type UiComponentSpec, } from './ui-components.js';
 export { buildCopilotMessages, projectFromModelText, type CopilotMessages } from './copilot-core.js';
 export { resolveDeployTarget, deployCommands, missingEnvKeys, type DeployProvider, type DeployResolution, type DeployPlanCommands, } from './deploy-cli.js';
 export { runStudioAdd, runStudioAddApp, resolveSchema, resolveSchemas, type StudioIO, type AddOptions, type AddResult, type AddAppResult, } from './cli.js';
-export { resolveIdField, schemaToColumns, schemaToFormFields, linkRelationLabels, pickLabelField, type EntitySchema, type EntityField, type EntityFieldType, } from '../schema.js';
+export { resolveIdField, schemaToColumns, schemaToFormFields, isFieldHidden, linkRelationLabels, pickLabelField, type EntitySchema, type EntityField, type EntityFieldType, } from '../schema.js';
 export { checkLicenseKey, type LicenseInfo, type LicenseStatus } from '../license-core.js';

package/dist/studio/index.js

@@ -25,14 +25,17 @@ export { crudSuiteScreens, addCrudSuite, crudAppFromSchemas, listScreen, formScr
 export { sanitizeStudioProject, buildStudioBugReport, } from './bug-report.js';
 export { generateValue, generateRows } from './sample-data.js';
 export { studioThemes, defaultStudioTheme, getStudioTheme, resolveThemeTokens, resolveThemeTokensFor, isDarkTheme, themeStyleString } from './themes.js';
-export { createProject, defaultScreenFor, defaultBlockConfig, gridColumns, entityOf, blockPalette, addBlock, addBlockAt, addComponentBlock, removeBlock, duplicateBlock, moveBlock, reorderBlock, updateBlock, addEntity, removeEntity, updateEntity, addScreen, addFreestandingScreen, addScreenAction, removeScreenAction, enableScreenCode, disableScreenCode, setScreenRenderGrid, screenLayoutOf, buildDockLayout, reconcileDock, syncDockPanes, setScreenLayout, isPaneLayout, PANE_LAYOUTS, buildCanvasLayout, canvasRectOf, setCanvasRect, CANVAS_COLS, CANVAS_ROW_PX, CANVAS_GAP_PX, applyGridPreset, gridPresetLabel, GRID_PRESETS, setScreenDock, reseedScreenDock, setDockPaneTitle, dockPaneTitleOf, dockPaneIds, setLayoutOpts, gridOpts, stackOpts, splitOpts, dockOpts, canvasOpts, setHandlerBody, setScreenHandlersSource, setHandlerSteps, addHandlerStep, updateHandlerStep, moveHandlerStep, stepsToCode, compileStep, compileHandlerSteps, compileValue, compileCondition, compileTriggerStep, compileTriggerSteps, triggersOf, setTrigger, TRIGGER_EVENTS, setJob, setTenancy, tenantField, isTenantScoped, clickSlot, ssrScreenShape, ssrEligible, withSsrDefaults, setScreenRenderMode, eventSlot, rowSelectSlot, changeSlot, FORM_SUBMIT, GRID_EVENTS, addStateVar, updateStateVar, removeStateVar, stateInitExpr, stateTsType, setComponentName, setComponentBinding, componentHasBindings, componentHandleName, ON_LOAD, removeScreen, updateScreen, duplicateScreen, reorderScreen, insertBlock, setDataSource, setDeployTarget, setAuth, setDataLayer, seedUsers, defaultEntitySource, flattenBlocks, TAB_CHILD_KINDS, CONTAINER_CHILD_KINDS, CONTAINER_DISPLAY_KINDS, addTab, removeTab, renameTab, addTabBlock, addTabComponent, removeTabBlock, addAccordionSection, removeAccordionSection, renameAccordionSection, setAccordionMultiple, addAccordionBlock, addAccordionComponent, removeAccordionBlock, setEntityDataSource, entityDataSource, setTheme, setThemePreset, setShell, sanitizeProject, screenFromTemplate, addScreenFromTemplate, serializeProject, parseProject, validateProject, isProjectValid, blockColumns, blockStyleCss, blockClassName, sanitizeClassName, mergeBlockStyle, roleCanScreen, roleCanAction, CRUD_ACTIONS, } from './project.js';
+export { createProject, defaultScreenFor, defaultBlockConfig, gridColumns, entityOf, blockPalette, addBlock, addBlockAt, addComponentBlock, removeBlock, duplicateBlock, moveBlock, reorderBlock, updateBlock, addEntity, removeEntity, updateEntity, 
+// Form layout: the operations a form builder drives, on the entity's own
+// `form` so a built form travels with the entity rather than with one block.
+formPlan, setEntityForm, setFormColumns, addFormSection, updateFormSection, removeFormSection, moveFormSection, moveFormField, moveFormFields, setFieldConditions, updateEntityField, setFieldInput, setFieldHidden, formControlsFor, formControlSettings, suggestFormSections, addScreen, addFreestandingScreen, addScreenAction, removeScreenAction, enableScreenCode, disableScreenCode, setScreenRenderGrid, screenLayoutOf, buildDockLayout, reconcileDock, syncDockPanes, setScreenLayout, isPaneLayout, PANE_LAYOUTS, buildCanvasLayout, canvasRectOf, setCanvasRect, CANVAS_COLS, CANVAS_ROW_PX, CANVAS_GAP_PX, applyGridPreset, gridPresetLabel, GRID_PRESETS, setScreenDock, reseedScreenDock, setDockPaneTitle, dockPaneTitleOf, dockPaneIds, setLayoutOpts, gridOpts, stackOpts, splitOpts, dockOpts, canvasOpts, setHandlerBody, setScreenHandlersSource, setHandlerSteps, addHandlerStep, updateHandlerStep, moveHandlerStep, stepsToCode, compileStep, compileHandlerSteps, compileValue, compileCondition, compileTriggerStep, compileTriggerSteps, triggersOf, setTrigger, TRIGGER_EVENTS, setJob, setTenancy, tenantField, isTenantScoped, clickSlot, ssrScreenShape, ssrEligible, withSsrDefaults, setScreenRenderMode, eventSlot, rowSelectSlot, changeSlot, FORM_SUBMIT, GRID_EVENTS, addStateVar, updateStateVar, removeStateVar, stateInitExpr, stateTsType, setComponentName, setComponentBinding, componentHasBindings, componentHandleName, ON_LOAD, removeScreen, updateScreen, duplicateScreen, reorderScreen, insertBlock, setDataSource, setDeployTarget, setAuth, setDataLayer, seedUsers, defaultEntitySource, flattenBlocks, TAB_CHILD_KINDS, CONTAINER_CHILD_KINDS, CONTAINER_DISPLAY_KINDS, addTab, removeTab, renameTab, addTabBlock, addTabComponent, removeTabBlock, addAccordionSection, removeAccordionSection, renameAccordionSection, setAccordionMultiple, addAccordionBlock, addAccordionComponent, removeAccordionBlock, setEntityDataSource, entityDataSource, setTheme, setThemePreset, setShell, sanitizeProject, screenFromTemplate, addScreenFromTemplate, serializeProject, parseProject, validateProject, isProjectValid, blockColumns, blockStyleCss, blockClassName, sanitizeClassName, mergeBlockStyle, roleCanScreen, roleCanAction, CRUD_ACTIONS, } from './project.js';
 export { verifyScaffold, summarizeVerify, } from './verify.js';
 export { UI_COMPONENT_REGISTRY, uiComponentSpec, gridPropSurface, gridApiSettableProps, GRID_CURATED_PROPS, STANDARD_UI_EVENTS, } from './ui-components.js';
 export { buildCopilotMessages, projectFromModelText } from './copilot-core.js';
 export { resolveDeployTarget, deployCommands, missingEnvKeys, } from './deploy-cli.js';
 export { runStudioAdd, runStudioAddApp, resolveSchema, resolveSchemas, } from './cli.js';
 // Re-export the schema surface so consumers get everything from one entry.
-export { resolveIdField, schemaToColumns, schemaToFormFields, linkRelationLabels, pickLabelField, } from '../schema.js';
+export { resolveIdField, schemaToColumns, schemaToFormFields, isFieldHidden, linkRelationLabels, pickLabelField, } from '../schema.js';
 // Pure license classification, so the Node/MCP generator can soft-gate with the
 // same rules as the browser (see license-core.ts). No DOM, safe in Node.
 export { checkLicenseKey } from '../license-core.js';

package/dist/studio/project.d.ts

@@ -10,7 +10,7 @@
  * Block-config unions are defined here (not imported from `sources/`) to keep the
  * module resolvable under node16.
  */
-import type { EntitySchema, FormSection } from '../schema.js';
+import { type EntityField, type EntityFieldType, type EntitySchema, type FormLayout, type FormSection, type StudioEditorType } from '../schema.js';
 import type { ChartType, DockManagerState } from '@svgrid/grid';
 export type Reduce = 'sum' | 'avg' | 'count' | 'min' | 'max';
 export type DataSourceKind = 'memory' | 'sql' | 'supabase' | 'rest' | 'pglite';
@@ -317,9 +317,37 @@ export type ActionConfig = {
 };
 /** Legacy standalone edit-form block. Editing is now a Grid property; kept so old
  *  `studio.config.json` files still parse. Not offered in the palette. */
+/**
+ * A standalone form for creating a record: a "New ticket" page, an intake
+ * screen, a signup. Blank on load, submits, and creates a row.
+ *
+ * Deliberately create-only, because the other two directions are already taken:
+ * a grid with `editing: 'form'` edits an existing row in a popup, and a
+ * `record` block with `editable` edits whatever row is selected. What no block
+ * covered was a form that stands on its own with no grid behind it.
+ *
+ * Its fields, order, sections and conditions come from the entity's own
+ * `EntitySchema.form` - the same layout the form builder edits - so a form
+ * designed once looks the same wherever it is placed.
+ */
 export type FormConfig = {
     kind: 'form';
     presentation: Presentation;
+    /** Heading above the form. Defaults to "New <entity>". */
+    title?: string;
+    /** Submit button text. Defaults to "Create". */
+    submitLabel?: string;
+    /** After a successful create: blank the form for another entry (default), or
+     *  go to another screen. */
+    afterSave?: 'reset' | 'navigate';
+    /** Screen id to open when `afterSave` is 'navigate'. */
+    navigateTo?: string;
+    /**
+     * How wide the form draws. Inline forms fill their block by default, which is
+     * right for a narrow column and too wide to read across a full page - this
+     * caps it. Maps to `SvGridEditPanel`'s `formSize`.
+     */
+    width?: 'sm' | 'md' | 'lg';
 };
 /** A chart, optionally drilling into `drillScreen` (filtered by the clicked category). */
 export type ChartConfig = {
@@ -1068,8 +1096,9 @@ export type PaletteItem = {
     label: string;
     needs?: 'measure' | 'child';
 };
-/** The designer's block palette, in menu order. (Editing is a Grid property, so
- *  there's no standalone form block.) */
+/** The designer's block palette, in menu order. A grid owns edit-in-popup and a
+ *  record panel edits the selected row, so the standalone Form block is the one
+ *  that creates: a form on its own page, with no grid behind it. */
 export declare const blockPalette: ReadonlyArray<PaletteItem>;
 export declare function entityOf(project: StudioProject, name: string | undefined): EntitySchema | undefined;
 /** Sensible grid columns for an entity: every non-grid-hidden field, shown. */
@@ -1151,6 +1180,98 @@ export declare function updateEntity(project: StudioProject, name: string, schem
 export declare function addEntity(project: StudioProject, schema: EntitySchema): StudioProject;
 /** Remove an entity and every screen bound to it. */
 export declare function removeEntity(project: StudioProject, name: string): StudioProject;
+/**
+ * The sections as a builder should show them, plus the fields no section claims.
+ *
+ * Sections name their fields by string, so a rename, a delete, or hiding a field
+ * from the form can leave a name behind. Those are dropped here rather than
+ * drawn as ghosts, and a field in no section comes back in `unassigned` - which
+ * is where the form itself puts it too, in a trailing untitled group.
+ */
+export declare function formPlan(schema: EntitySchema, override?: ReadonlyArray<FormSection>): {
+    sections: FormSection[];
+    unassigned: string[];
+};
+/** Replace an entity's form layout. `undefined` drops it back to the default. */
+export declare function setEntityForm(project: StudioProject, entityName: string, form: FormLayout | undefined): StudioProject;
+/** Set the form's column count, or clear it back to the default. */
+export declare function setFormColumns(project: StudioProject, entityName: string, columns: 1 | 2 | 3 | undefined): StudioProject;
+/** Append a section. New sections start empty - fields move in afterwards. */
+export declare function addFormSection(project: StudioProject, entityName: string, title?: string): StudioProject;
+/** Patch one section. An out-of-range index is a no-op rather than an error. */
+export declare function updateFormSection(project: StudioProject, entityName: string, index: number, patch: Partial<FormSection>): StudioProject;
+/**
+ * Remove a section. Its fields stay in the form - they fall back to the trailing
+ * untitled group, so deleting a heading never deletes the questions under it.
+ */
+export declare function removeFormSection(project: StudioProject, entityName: string, index: number): StudioProject;
+/** Reorder the sections themselves. */
+export declare function moveFormSection(project: StudioProject, entityName: string, from: number, to: number): StudioProject;
+/**
+ * Move a field into a section at a position, or out of every section when
+ * `toSection` is null. The field is pulled out of wherever it was first, so it
+ * can never end up in two sections - which would render the control twice.
+ */
+export declare function moveFormField(project: StudioProject, entityName: string, field: string, toSection: number | null, toIndex?: number): StudioProject;
+/**
+ * Move several fields at once, as one contiguous block in the order given.
+ *
+ * Not a loop of {@link moveFormField}: each single move both shifts the target
+ * indices and re-resolves the plan, so a loop lands the group scattered or
+ * reversed. Strip every named field first, then splice the whole group at the
+ * index computed against the stripped target.
+ *
+ * Unknown and hidden-from-form names are dropped, duplicates keep their first
+ * position, and an input that resolves to nothing returns the project
+ * unchanged (same reference), so an undo stack never records a no-op.
+ */
+export declare function moveFormFields(project: StudioProject, entityName: string, fields: ReadonlyArray<string>, toSection: number | null, toIndex?: number): StudioProject;
+/**
+ * Set (or clear) a field's value-driven conditions. Each is a `PredicateExpr`,
+ * so it stays data all the way into the generated app - see `EntityField.when`.
+ */
+export declare function setFieldConditions(project: StudioProject, entityName: string, field: string, when: EntityField['when'] | undefined): StudioProject;
+/**
+ * Patch one field of one entity. The form builder edits an entity that is not
+ * necessarily the selected screen's, so it needs the project-level door rather
+ * than the schema-level `updateField`.
+ *
+ * Deliberately shallow: `type` changes belong to the schema designer, which also
+ * has to clean up `options` / `relation` when the type moves.
+ */
+export declare function updateEntityField(project: StudioProject, entityName: string, field: string, patch: Partial<EntityField>): StudioProject;
+/**
+ * Patch a field's form presentation (`EntityField.input`). Merges rather than
+ * replaces, and a key set to `undefined` or `''` is removed - so clearing a
+ * placeholder leaves no empty string behind, and emptying the last key drops
+ * `input` itself rather than persisting `input: {}`.
+ */
+export declare function setFieldInput(project: StudioProject, entityName: string, field: string, patch: Partial<NonNullable<EntityField['input']>>): StudioProject;
+/**
+ * Show or hide a field on one surface, keeping the other surface's answer.
+ * `hidden: true` means both, so it is expanded before one half is changed -
+ * otherwise hiding a field from the form would silently un-hide its column.
+ */
+export declare function setFieldHidden(project: StudioProject, entityName: string, field: string, surface: 'grid' | 'form', hidden: boolean): StudioProject;
+/**
+ * The form controls worth offering for a field type. A form builder that listed
+ * every editor for every type would be a wall of mostly-wrong choices - a date
+ * field has no business rendering as a colour picker. The first entry is what
+ * the field renders as when `input.editorType` is unset.
+ */
+export declare function formControlsFor(type: EntityFieldType): StudioEditorType[];
+/**
+ * Which extra settings a control actually uses, so a builder can show those and
+ * nothing else. Picking "mask" and then having nowhere to type the pattern - or
+ * "slider" with no way to set its range - is a dead end, and listing all of them
+ * against every control is a wall of mostly-irrelevant boxes.
+ *
+ * `range` is min/max, which live on the field itself rather than under `input`
+ * (they validate as well as bound the control).
+ */
+export type ControlSetting = 'range' | 'step' | 'precision' | 'affix' | 'mask';
+export declare function formControlSettings(control: StudioEditorType | undefined, type: EntityFieldType): ControlSetting[];
+export declare function suggestFormSections(schema: EntitySchema): FormSection[];
 export declare function addScreen(project: StudioProject, entity: string): StudioProject;
 export declare function removeScreen(project: StudioProject, screenId: string): StudioProject;
 export declare function updateScreen(project: StudioProject, screenId: string, patch: Partial<Pick<Screen, 'title' | 'route' | 'entity' | 'nav' | 'actions' | 'className' | 'renderMode'>>): StudioProject;

package/dist/studio/project.js

@@ -1,3 +1,16 @@
+/**
+ * Studio project model - the declarative spine the visual designer edits and the
+ * codegen emits. A project is a multi-entity app: `entities` (the data model) +
+ * `screens` (one per entity by default), where a screen is an ordered list of
+ * data-bound `blocks` (grid, form, chart, dashboard, KPI, master-detail, lookup).
+ *
+ * Pure + node-safe (lives in the `./studio` subtree - `.js` imports, no Svelte,
+ * no `sources/`), mirroring the immutable-ops style of `schema-designer.ts`:
+ * every mutation returns a NEW project so Svelte reactivity + undo stay simple.
+ * Block-config unions are defined here (not imported from `sources/`) to keep the
+ * module resolvable under node16.
+ */
+import { schemaToFormFields } from '../schema.js';
 import { collectColumnRefs } from '../expressions/parse.js';
 import { uiComponentSpec } from './ui-components.js';
 /** Block kinds allowed inside a Tabs / Accordion container: the controller-free,
@@ -401,10 +414,12 @@ export function setJob(project, id, job) {
     const next = job ? [...rest, { ...job, id }] : rest;
     return { ...project, jobs: next.length ? next : undefined };
 }
-/** The designer's block palette, in menu order. (Editing is a Grid property, so
- *  there's no standalone form block.) */
+/** The designer's block palette, in menu order. A grid owns edit-in-popup and a
+ *  record panel edits the selected row, so the standalone Form block is the one
+ *  that creates: a form on its own page, with no grid behind it. */
 export const blockPalette = [
     { kind: 'grid', label: 'Grid' },
+    { kind: 'form', label: 'Form' },
     { kind: 'chart', label: 'Chart', needs: 'measure' },
     { kind: 'pivot', label: 'Pivot', needs: 'measure' },
     { kind: 'dashboard', label: 'Dashboard' },
@@ -463,7 +478,8 @@ export function defaultBlockConfig(kind, entity) {
         case 'grid':
             return { kind, columns: gridColumns(entity), pageSize: 10, selectable: true, sortable: true, filterable: false, editing: 'form', formPresentation: 'modal', density: 'normal', striped: false, cellSelection: false, rowSummaries: false, paginated: true, paginationPosition: 'bottom', pageSizeOptions: [10, 25, 50, 100] };
         case 'form':
-            return { kind, presentation: 'modal' };
+            // Inline: a create form belongs on the page, not floating over it.
+            return { kind, presentation: 'inline', afterSave: 'reset' };
         case 'chart': {
             const measure = pickMeasure(entity);
             return { kind, dimension: pickDimension(entity), measure, reduce: measure ? 'sum' : 'count', type: 'bar' };
@@ -839,6 +855,365 @@ export function removeEntity(project, name) {
         screens: project.screens.filter((s) => s.entity !== name),
     };
 }
+// ---- Form layout ----------------------------------------------------------
+//
+// The arrangement lives on the entity (`EntitySchema.form`) rather than on the
+// block that happens to render it, so a form built once travels with the entity:
+// it round-trips through `studio.config.json`, generates into the app, and draws
+// the same in the edit panel and in a server-rendered form. These are the
+// operations a builder UI drives; keeping them here - pure, on the project -
+// means the designer and an MCP tool cannot disagree about what "move a field"
+// means.
+/**
+ * The fields a form actually renders, in schema order. Arranging anything else
+ * would be a lie: a field hidden from the form cannot be put in a section and
+ * then appear there.
+ */
+function formFieldNames(schema) {
+    return schemaToFormFields(schema).map((f) => f.field);
+}
+/**
+ * The sections as a builder should show them, plus the fields no section claims.
+ *
+ * Sections name their fields by string, so a rename, a delete, or hiding a field
+ * from the form can leave a name behind. Those are dropped here rather than
+ * drawn as ghosts, and a field in no section comes back in `unassigned` - which
+ * is where the form itself puts it too, in a trailing untitled group.
+ */
+export function formPlan(schema, override) {
+    const inForm = formFieldNames(schema);
+    const known = new Set(inForm);
+    const source = override ?? schema.form?.sections ?? [];
+    const seen = new Set();
+    const sections = source.map((section) => {
+        // A field named twice belongs to the first section that claimed it: two
+        // copies of one control in a form is never what anybody meant. Claiming as
+        // we go also catches a name repeated inside a single section.
+        const fields = section.fields.filter((f) => {
+            if (!known.has(f) || seen.has(f))
+                return false;
+            seen.add(f);
+            return true;
+        });
+        return { ...section, fields };
+    });
+    return { sections, unassigned: inForm.filter((f) => !seen.has(f)) };
+}
+/** Replace an entity's form layout. `undefined` drops it back to the default. */
+export function setEntityForm(project, entityName, form) {
+    return mapEntity(project, entityName, (schema) => {
+        const next = { ...schema };
+        // An empty layout is deleted rather than stored, so a config file does not
+        // carry `form: {}` around and a reader can tell "no layout" from "one column".
+        if (form && (form.columns !== undefined || form.sections?.length))
+            next.form = form;
+        else
+            delete next.form;
+        return next;
+    });
+}
+/** Set the form's column count, or clear it back to the default. */
+export function setFormColumns(project, entityName, columns) {
+    const schema = entityOf(project, entityName);
+    if (!schema)
+        return project;
+    return setEntityForm(project, entityName, { ...schema.form, columns });
+}
+/** Append a section. New sections start empty - fields move in afterwards. */
+export function addFormSection(project, entityName, title = 'Section') {
+    const schema = entityOf(project, entityName);
+    if (!schema)
+        return project;
+    return setEntityForm(project, entityName, { ...schema.form, sections: [...(schema.form?.sections ?? []), { title, fields: [] }] });
+}
+/** Patch one section. An out-of-range index is a no-op rather than an error. */
+export function updateFormSection(project, entityName, index, patch) {
+    const schema = entityOf(project, entityName);
+    const sections = schema?.form?.sections;
+    if (!sections?.[index])
+        return project;
+    const next = sections.map((s, i) => {
+        if (i !== index)
+            return s;
+        const merged = { ...s, ...patch };
+        // A cleared title / description is dropped rather than stored blank, so the
+        // form renders an untitled group instead of an empty heading.
+        if (!merged.title)
+            delete merged.title;
+        if (!merged.description)
+            delete merged.description;
+        if (!merged.visibleWhen)
+            delete merged.visibleWhen;
+        if (!merged.columns)
+            delete merged.columns;
+        if (!merged.collapsible) {
+            delete merged.collapsible;
+            delete merged.collapsed;
+        }
+        if (!merged.collapsed)
+            delete merged.collapsed;
+        return merged;
+    });
+    return setEntityForm(project, entityName, { ...schema.form, sections: next });
+}
+/**
+ * Remove a section. Its fields stay in the form - they fall back to the trailing
+ * untitled group, so deleting a heading never deletes the questions under it.
+ */
+export function removeFormSection(project, entityName, index) {
+    const schema = entityOf(project, entityName);
+    const sections = schema?.form?.sections;
+    if (!sections?.[index])
+        return project;
+    return setEntityForm(project, entityName, { ...schema.form, sections: sections.filter((_, i) => i !== index) });
+}
+/** Reorder the sections themselves. */
+export function moveFormSection(project, entityName, from, to) {
+    const schema = entityOf(project, entityName);
+    const sections = schema?.form?.sections;
+    if (!sections?.[from] || to < 0 || to >= sections.length || from === to)
+        return project;
+    const next = [...sections];
+    next.splice(to, 0, next.splice(from, 1)[0]);
+    return setEntityForm(project, entityName, { ...schema.form, sections: next });
+}
+/**
+ * Move a field into a section at a position, or out of every section when
+ * `toSection` is null. The field is pulled out of wherever it was first, so it
+ * can never end up in two sections - which would render the control twice.
+ */
+export function moveFormField(project, entityName, field, toSection, toIndex = Number.MAX_SAFE_INTEGER) {
+    const schema = entityOf(project, entityName);
+    // Only a field the form renders can be placed - see `formPlan`.
+    if (!schema || !formFieldNames(schema).includes(field))
+        return project;
+    const sections = schema.form?.sections ?? [];
+    if (toSection !== null && !sections[toSection])
+        return project;
+    const stripped = sections.map((s) => ({ ...s, fields: s.fields.filter((f) => f !== field) }));
+    if (toSection === null)
+        return setEntityForm(project, entityName, { ...schema.form, sections: stripped });
+    const target = stripped[toSection];
+    const at = Math.max(0, Math.min(toIndex, target.fields.length));
+    const fields = [...target.fields];
+    fields.splice(at, 0, field);
+    return setEntityForm(project, entityName, {
+        ...schema.form,
+        sections: stripped.map((s, i) => (i === toSection ? { ...s, fields } : s)),
+    });
+}
+/**
+ * Move several fields at once, as one contiguous block in the order given.
+ *
+ * Not a loop of {@link moveFormField}: each single move both shifts the target
+ * indices and re-resolves the plan, so a loop lands the group scattered or
+ * reversed. Strip every named field first, then splice the whole group at the
+ * index computed against the stripped target.
+ *
+ * Unknown and hidden-from-form names are dropped, duplicates keep their first
+ * position, and an input that resolves to nothing returns the project
+ * unchanged (same reference), so an undo stack never records a no-op.
+ */
+export function moveFormFields(project, entityName, fields, toSection, toIndex = Number.MAX_SAFE_INTEGER) {
+    const schema = entityOf(project, entityName);
+    if (!schema)
+        return project;
+    const movable = new Set(formFieldNames(schema));
+    const group = [];
+    for (const f of fields)
+        if (movable.has(f) && !group.includes(f))
+            group.push(f);
+    if (!group.length)
+        return project;
+    const sections = schema.form?.sections ?? [];
+    if (toSection !== null && !sections[toSection])
+        return project;
+    const moving = new Set(group);
+    const stripped = sections.map((s) => ({ ...s, fields: s.fields.filter((f) => !moving.has(f)) }));
+    if (toSection === null)
+        return setEntityForm(project, entityName, { ...schema.form, sections: stripped });
+    const target = stripped[toSection];
+    const at = Math.max(0, Math.min(toIndex, target.fields.length));
+    const next = [...target.fields];
+    next.splice(at, 0, ...group);
+    return setEntityForm(project, entityName, {
+        ...schema.form,
+        sections: stripped.map((s, i) => (i === toSection ? { ...s, fields: next } : s)),
+    });
+}
+/**
+ * Set (or clear) a field's value-driven conditions. Each is a `PredicateExpr`,
+ * so it stays data all the way into the generated app - see `EntityField.when`.
+ */
+export function setFieldConditions(project, entityName, field, when) {
+    return mapEntity(project, entityName, (schema) => ({
+        ...schema,
+        fields: schema.fields.map((f) => {
+            if (f.field !== field)
+                return f;
+            const next = { ...f };
+            if (when?.visible || when?.disabled || when?.required) {
+                next.when = {
+                    ...(when.visible && { visible: when.visible }),
+                    ...(when.disabled && { disabled: when.disabled }),
+                    ...(when.required && { required: when.required }),
+                };
+            }
+            else {
+                delete next.when;
+            }
+            return next;
+        }),
+    }));
+}
+/**
+ * Patch one field of one entity. The form builder edits an entity that is not
+ * necessarily the selected screen's, so it needs the project-level door rather
+ * than the schema-level `updateField`.
+ *
+ * Deliberately shallow: `type` changes belong to the schema designer, which also
+ * has to clean up `options` / `relation` when the type moves.
+ */
+export function updateEntityField(project, entityName, field, patch) {
+    return mapEntity(project, entityName, (schema) => ({
+        ...schema,
+        fields: schema.fields.map((f) => (f.field === field ? { ...f, ...patch } : f)),
+    }));
+}
+/**
+ * Patch a field's form presentation (`EntityField.input`). Merges rather than
+ * replaces, and a key set to `undefined` or `''` is removed - so clearing a
+ * placeholder leaves no empty string behind, and emptying the last key drops
+ * `input` itself rather than persisting `input: {}`.
+ */
+export function setFieldInput(project, entityName, field, patch) {
+    return mapEntity(project, entityName, (schema) => ({
+        ...schema,
+        fields: schema.fields.map((f) => {
+            if (f.field !== field)
+                return f;
+            const input = { ...f.input };
+            for (const [key, value] of Object.entries(patch)) {
+                if (value === undefined || value === '')
+                    delete input[key];
+                else
+                    input[key] = value;
+            }
+            const next = { ...f };
+            if (Object.keys(input).length)
+                next.input = input;
+            else
+                delete next.input;
+            return next;
+        }),
+    }));
+}
+/**
+ * Show or hide a field on one surface, keeping the other surface's answer.
+ * `hidden: true` means both, so it is expanded before one half is changed -
+ * otherwise hiding a field from the form would silently un-hide its column.
+ */
+export function setFieldHidden(project, entityName, field, surface, hidden) {
+    return mapEntity(project, entityName, (schema) => ({
+        ...schema,
+        fields: schema.fields.map((f) => {
+            if (f.field !== field)
+                return f;
+            const current = f.hidden === true ? { grid: true, form: true } : { ...(f.hidden || {}) };
+            const merged = { ...current, [surface]: hidden };
+            const next = { ...f };
+            if (merged.grid && merged.form)
+                next.hidden = true;
+            else if (merged.grid || merged.form)
+                next.hidden = { ...(merged.grid && { grid: true }), ...(merged.form && { form: true }) };
+            else
+                delete next.hidden;
+            return next;
+        }),
+    }));
+}
+/**
+ * The form controls worth offering for a field type. A form builder that listed
+ * every editor for every type would be a wall of mostly-wrong choices - a date
+ * field has no business rendering as a colour picker. The first entry is what
+ * the field renders as when `input.editorType` is unset.
+ */
+export function formControlsFor(type) {
+    switch (type) {
+        case 'number': return ['number', 'slider', 'rating', 'text'];
+        case 'boolean': return ['checkbox'];
+        case 'date':
+        case 'dateString': return ['date', 'date-native'];
+        case 'datetime': return ['datetime', 'datetime-native', 'time'];
+        case 'enum': return ['select', 'rich-select', 'list', 'chips', 'autocomplete'];
+        case 'relation': return ['select', 'autocomplete'];
+        case 'json': return ['textarea', 'text'];
+        default: return ['text', 'textarea', 'password', 'phone', 'country', 'mask', 'color', 'autocomplete', 'chips'];
+    }
+}
+export function formControlSettings(control, type) {
+    const kind = control ?? formControlsFor(type)[0];
+    if (kind === 'mask')
+        return ['mask'];
+    if (kind === 'slider' || kind === 'rating')
+        return ['range', 'step'];
+    if (kind === 'number' || (type === 'number' && kind !== 'text'))
+        return ['range', 'step', 'precision', 'affix'];
+    return [];
+}
+/**
+ * A first pass at sectioning an unarranged form, by what the field names say
+ * they are. Studio's promise is a working app in a few clicks, and an entity of
+ * fifteen fields in one flat list is not that.
+ *
+ * A guess, offered once: it returns sections for a builder to drop in and then
+ * edit, and it never invents a group for a form small enough not to need one.
+ */
+const SECTION_HINTS = [
+    { title: 'Contact', match: /^(email|phone|mobile|fax|website|url|contact)/i },
+    { title: 'Address', match: /(address|street|city|state|province|zip|postcode|postal|country|region)/i },
+    { title: 'Money', match: /(amount|price|cost|total|revenue|mrr|arr|salary|budget|value|balance|fee|tax|discount)/i },
+    { title: 'Dates', match: /(date|_at$|At$|deadline|due|expires|starts|ends)/i },
+    { title: 'Notes', match: /(note|notes|comment|comments|description|summary|remark)/i },
+];
+export function suggestFormSections(schema) {
+    const names = formFieldNames(schema);
+    // Below this a flat form reads fine, and a heading over two fields is noise.
+    if (names.length < 6)
+        return [];
+    const buckets = new Map();
+    const rest = [];
+    for (const name of names) {
+        const hint = SECTION_HINTS.find((h) => h.match.test(name));
+        if (!hint) {
+            rest.push(name);
+            continue;
+        }
+        const bucket = buckets.get(hint.title);
+        if (bucket)
+            bucket.push(name);
+        else
+            buckets.set(hint.title, [name]);
+    }
+    // A bucket of one is not a group; give it back to Details rather than crown it.
+    const sections = [];
+    for (const [title, fields] of buckets) {
+        if (fields.length > 1)
+            sections.push({ title, fields });
+        else
+            rest.push(...fields);
+    }
+    if (!sections.length)
+        return [];
+    // Whatever matched nothing leads, under the entity's own name for a heading.
+    return rest.length ? [{ title: 'Details', fields: rest }, ...sections] : sections;
+}
+/** Apply a change to one entity's schema, leaving the project alone if it is unknown. */
+function mapEntity(project, entityName, fn) {
+    if (!entityOf(project, entityName))
+        return project;
+    return { ...project, entities: project.entities.map((e) => (e.name === entityName ? fn(e) : e)) };
+}
 /** Append a screen, making its id AND route unique against the existing set. */
 function appendScreen(project, base, keyBase) {
     const ids = new Set(project.screens.map((s) => s.id));
@@ -1707,7 +2082,21 @@ export function validateProject(project) {
         for (const b of flattenBlocks(s.blocks)) {
             const at = (message, level = 'warning') => ({ level, message, screen: s.id, block: b.id });
             const c = b.config;
-            if (c.kind === 'master-detail') {
+            if (c.kind === 'form') {
+                // A form on a screen with no entity has nothing to create.
+                if (!s.entity)
+                    issues.push(at('A Form block needs a screen bound to an entity.', 'error'));
+                // "Go to a screen" that names none, or names a screen that has since been
+                // removed, leaves the user on a form that appears to do nothing on save.
+                if (c.afterSave === 'navigate') {
+                    if (!c.navigateTo)
+                        issues.push(at('The form is set to open a screen after saving, but no screen is chosen.'));
+                    else if (!project.screens.some((x) => x.id === c.navigateTo)) {
+                        issues.push(at(`The form opens a missing screen "${c.navigateTo}" after saving.`, 'error'));
+                    }
+                }
+            }
+            else if (c.kind === 'master-detail') {
                 if (!c.childEntity || !c.foreignKey)
                     issues.push(at('Master/detail needs a child entity + foreign key.'));
                 else if (!entityOf(project, c.childEntity))