@svgrid/enterprise 2.6.0 → 2.6.2

package/dist/schema.d.ts

@@ -268,6 +268,19 @@ export type FormSection = {
     fields: string[];
     /** Show the section only while this holds - see `EntityField.when`. */
     visibleWhen?: PredicateExpr;
+    /**
+     * Let the user fold this group away. Turns the heading into a disclosure
+     * button, so a long form opens at a readable length instead of a wall of
+     * inputs.
+     *
+     * A collapsed section is still **filled in and still validated** - it is a
+     * display state, not a condition. Use `visibleWhen` to actually drop fields
+     * from the form. If a collapsed section holds an error the panel opens it, so
+     * a failed submit can never point at something the user cannot see.
+     */
+    collapsible?: boolean;
+    /** Start folded. Only meaningful with `collapsible`. */
+    collapsed?: boolean;
 };
 /**
  * How the entity's form is laid out. Lives on the schema rather than on the
@@ -281,6 +294,25 @@ export type FormSection = {
 export type FormLayout = {
     columns?: 1 | 2 | 3;
     sections?: FormSection[];
+    /**
+     * Ask one section at a time, with Back / Next and a progress line - an intake
+     * form or an onboarding flow rather than a page of inputs.
+     *
+     * Each section is a step, so the sections ARE the design: no second list to
+     * keep in sync. **Next validates only the step you are on**, so a long form
+     * fails early and locally instead of dumping every error at the end. A section
+     * hidden by `visibleWhen` is skipped rather than shown empty, so the step count
+     * follows the answers.
+     *
+     * Needs sections (with none, it is one page and this does nothing) and makes
+     * `collapsible` moot - a step is already one group at a time.
+     *
+     * A server-rendered screen renders the steps as ordinary sections: stepping
+     * through a `<form>` with no JavaScript would mean a round-trip per step and
+     * somewhere to keep the half-finished record. The server still validates
+     * everything either way.
+     */
+    steps?: boolean;
 };
 /** Normalized descriptor the edit panel renders from (one per visible-in-form field). */
 export type FormFieldDescriptor = {
@@ -325,6 +357,13 @@ export declare function titleCase(field: string): string;
  * `getRowId`, edit panel, adapters) needs a stable key.
  */
 export declare function resolveIdField<TData extends RowData>(schema: EntitySchema<TData>): string;
+/**
+ * Whether a field is hidden from one surface. Public because the `hidden`
+ * union (`true` means both surfaces, an object names them) is exactly the kind
+ * of logic that drifts when every caller re-derives it - the form builder's
+ * "Hidden from this form" tray is one such caller.
+ */
+export declare function isFieldHidden(field: Pick<EntityField, 'hidden'>, surface: 'grid' | 'form'): boolean;
 /**
  * Derive grid columns from a schema. Read-only fields become non-editable
  * columns; `enum` carries its options through as `editorOptions`. The

package/dist/schema.js

@@ -75,6 +75,15 @@ function hiddenFor(field, surface) {
         return field.hidden[surface] === true;
     return false;
 }
+/**
+ * Whether a field is hidden from one surface. Public because the `hidden`
+ * union (`true` means both surfaces, an object names them) is exactly the kind
+ * of logic that drifts when every caller re-derives it - the form builder's
+ * "Hidden from this form" tray is one such caller.
+ */
+export function isFieldHidden(field, surface) {
+    return hiddenFor(field, surface);
+}
 /**
  * Derive grid columns from a schema. Read-only fields become non-editable
  * columns; `enum` carries its options through as `editorOptions`. The

package/dist/sources/rest.js

@@ -23,6 +23,31 @@ function defaultBuildQuery(request) {
         params.search = search;
     for (const p of predicates)
         params[p.column] = encodePredicate(p);
+    // ---- Server-side grouping ----------------------------------------------
+    // The grid asks for one level at a time. The path already chosen is sent as
+    // ordinary equality filters (the same shape any other filter uses), so an
+    // endpoint that already understands `?region=eq:EMEA` only needs to learn
+    // `groupBy` and `aggregate`.
+    //
+    //   ?groupBy=region&aggregate=sum:amount,count:id
+    //
+    // and, one level down:
+    //
+    //   ?groupBy=rep&region=eq:EMEA&aggregate=sum:amount
+    //
+    // The response is then one object per distinct key, each carrying the
+    // aggregate under its SOURCE column name - that is where the grid reads it.
+    const groupCols = request.groupBy ?? [];
+    const groupKeys = request.groupKeys ?? [];
+    for (let i = 0; i < groupKeys.length && i < groupCols.length; i += 1) {
+        params[groupCols[i]] = `eq:${groupKeys[i]}`;
+    }
+    if (groupKeys.length < groupCols.length) {
+        params.groupBy = groupCols[groupKeys.length];
+        const aggs = request.aggregations ?? [];
+        if (aggs.length)
+            params.aggregate = aggs.map((a) => `${a.fn}:${a.col}`).join(',');
+    }
     return params;
 }
 function defaultParse(body, response) {

package/dist/sources/supabase.js

@@ -10,7 +10,33 @@ export function createSupabaseDataSource(config) {
         schema.fields.filter((f) => f.type === 'text' || f.type === 'enum').map((f) => String(f.field));
     return {
         async getRows(request) {
-            let q = client.from(table).select('*', { count: 'exact' });
+            // ---- Server-side grouping -------------------------------------------
+            // The grid asks one level at a time. The already-chosen path becomes
+            // ordinary `.eq()` filters below; at this level we ask PostgREST for the
+            // group column plus aggregates, which implicitly groups by the
+            // non-aggregate columns in `select`.
+            //
+            // Each aggregate is aliased back to its SOURCE column name, because that
+            // is the key the grid reads it from on the group row.
+            //
+            // REQUIRES PostgREST 12+ with aggregate functions enabled
+            // (`db-aggregates-enabled`, off by default on some Supabase projects). On
+            // an older or restricted instance the request errors rather than silently
+            // returning ungrouped rows, so the failure is visible.
+            const groupCols = request.groupBy ?? [];
+            const groupKeys = request.groupKeys ?? [];
+            const groupField = groupKeys.length < groupCols.length ? groupCols[groupKeys.length] : undefined;
+            const selectExpr = groupField
+                ? [
+                    groupField,
+                    ...(request.aggregations ?? []).map((a) => a.fn === 'count' ? `${a.col}:count()` : `${a.col}:${a.col}.${a.fn}()`),
+                ].join(',')
+                : '*';
+            let q = client.from(table).select(selectExpr, { count: 'exact' });
+            // The path constrains the rows before grouping.
+            for (let i = 0; i < groupKeys.length && i < groupCols.length; i += 1) {
+                q = q.eq(groupCols[i], groupKeys[i]);
+            }
             const { predicates, search } = normalizeFilters(request.filterModel);
             for (const p of predicates) {
                 switch (p.op) {
@@ -44,8 +70,28 @@ export function createSupabaseDataSource(config) {
                 const term = sanitize(search);
                 q = q.or(searchColumns.map((c) => `${c}.ilike.%${term}%`).join(','));
             }
-            for (const s of request.sortModel)
-                q = q.order(s.id, { ascending: !s.desc });
+            // When grouping, only columns the grouped select actually produces can be
+            // ordered on - PostgREST rejects an ORDER BY over a column that is
+            // neither grouped nor aggregated. Fall back to the group key so the
+            // result has a stable order either way.
+            if (groupField) {
+                const produced = new Set([
+                    groupField,
+                    ...(request.aggregations ?? []).map((a) => a.col),
+                ]);
+                const usable = request.sortModel.filter((s) => produced.has(s.id));
+                if (usable.length) {
+                    for (const s of usable)
+                        q = q.order(s.id, { ascending: !s.desc });
+                }
+                else {
+                    q = q.order(groupField, { ascending: true });
+                }
+            }
+            else {
+                for (const s of request.sortModel)
+                    q = q.order(s.id, { ascending: !s.desc });
+            }
             const { data, count, error } = await q.range(request.startRow, request.endRow - 1);
             if (error)
                 throw new Error(error.message);

package/dist/studio/emit-project.js

@@ -539,10 +539,40 @@ ${panels}
         case 'component':
             return componentBlockMarkup(block, cfg, ctx.handleNames?.get(block.id), rowsExpr);
         case 'form':
+            return createFormMarkup(entity, schemaVar, block, cfg);
         default:
-            return ''; // the form is the edit modal, rendered after the screen grid
+            return '';
     }
 }
+/**
+ * A standalone create form: blank, always on the page, submits a new row.
+ *
+ * Keyed on `formSaves` so a successful create remounts the panel with empty
+ * values - the panel seeds itself from `row` once, so without the key the
+ * previous entry would still be sitting in the fields.
+ */
+function createFormMarkup(entity, schemaVar, block, cfg) {
+    const span = wrapperStyle(block);
+    const cls = wrapperClass(block);
+    const attrs = [`schema={${schemaVar}}`, 'row={null}', 'presentation="inline"'];
+    attrs.push(`title={${jsStr(cfg.title ?? `New ${entity.label ?? entity.name}`)}}`);
+    if (cfg.submitLabel)
+        attrs.push(`submitLabel={${jsStr(cfg.submitLabel)}}`);
+    // Inline fills its block unless told otherwise, so only a real choice is emitted.
+    if (cfg.width && cfg.width !== 'md')
+        attrs.push(`formSize=${jsStr(cfg.width)}`);
+    // A confirmation only makes sense when the page stays put; navigating away
+    // makes the new screen the confirmation.
+    const done = cfg.afterSave === 'navigate'
+        ? ''
+        : `
+      {#if formSaves}<p class="st-form__done" role="status">Saved. Add another below.</p>{/if}`;
+    return `    <div ${span}${cls}>${done}
+      {#key formSaves}
+        <SvGridEditPanel ${attrs.join(' ')} onSubmit={createRecord} />
+      {/key}
+    </div>`;
+}
 /** Emits a UI-kit component block (see `UI_COMPONENT_REGISTRY`): a literal
  *  `<SvXxx .../>` tag carrying its configured "chrome" props + optional text
  *  content. Entity-agnostic - used both from `blockMarkup` (mixed onto an
@@ -1852,7 +1882,10 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
     // literal shared with the PageContext type. Data handles read the entity row type.
     const handleNames = handleNameMap(screen);
     const codeWire = codeEnabled ? codeWiring(screen, n.type, undefined) : null;
-    const hasForm = has(blocks, 'form'); // legacy standalone form block
+    // A standalone Form block creates a record. It does NOT want the grid's edit
+    // modal (that edits an existing row), so it is deliberately kept out of
+    // `wantsForm` - it emits its own always-visible panel and its own handler.
+    const createForm = blocks.map((b) => b.config).find((c) => c.kind === 'form');
     // Editing is a Grid property: a grid with editing 'form' opens the edit panel.
     const gridConfigs = blocks.map((b) => b.config).filter((c) => c.kind === 'grid');
     const formGrid = gridConfigs.find((c) => c.editing === 'form');
@@ -1862,7 +1895,7 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
     // Rich cell renderers (badge / progress / link) each emit a `cell` snippet.
     const cellRenderKinds = new Set(gridConfigs.flatMap((c) => c.columns.filter((col) => col.show && col.cellType).map((col) => col.cellType.kind)));
     const hasCellRenderers = cellRenderKinds.size > 0;
-    const wantsForm = !!formGrid || hasForm || hasEditAction;
+    const wantsForm = !!formGrid || hasEditAction;
     // An unpaginated grid loads everything (one big page); else its configured size.
     const gridPageSize = gridConfigs[0] ? (gridConfigs[0].paginated !== false ? (gridConfigs[0].pageSize ?? 10) : 1000) : 10;
     const formPres = formGrid?.formPresentation ?? 'modal';
@@ -1875,7 +1908,7 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
     const recordEditable = blocks.some((b) => b.config.kind === 'record' && b.config.editable);
     // Filter panels drive the grid's controller; record panels read the grid's
     // selection - both need the controller even if the grid isn't editable.
-    const needsController = hasGrid || wantsForm || hasFilter || hasRecord;
+    const needsController = hasGrid || wantsForm || hasFilter || hasRecord || !!createForm;
     // Supabase Realtime: when the screen's entity is Supabase-backed and opts into
     // live updates, subscribe to Postgres change streams and refresh() the paged
     // grid on any INSERT / UPDATE / DELETE (respects the active sort/filter/page).
@@ -2000,7 +2033,8 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
         (b.config.kind === 'grid' && b.config.rowActions?.some((a) => a.kind === 'navigate' && a.screen && routeById.has(a.screen))) ||
         (b.config.kind === 'chart' && b.config.drillScreen && routeById.has(b.config.drillScreen)) ||
         ((b.config.kind === 'board' || b.config.kind === 'calendar') && b.config.openScreen != null && routeById.has(b.config.openScreen)) ||
-        (b.config.kind === 'master-detail' && b.config.linkScreen != null && routeById.has(b.config.linkScreen)));
+        (b.config.kind === 'master-detail' && b.config.linkScreen != null && routeById.has(b.config.linkScreen)) ||
+        (b.config.kind === 'form' && b.config.afterSave === 'navigate' && b.config.navigateTo != null && routeById.has(b.config.navigateTo)));
     const applyUrlFilters = drillEnabled && needsController;
     const filterableFieldNames = schema.fields.filter((f) => !f.primaryKey).map((f) => f.field);
     // RBAC gates the UI only where there's a create/update affordance to gate.
@@ -2138,6 +2172,21 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
     if (mode === 'create') { await controller.createRow({ [idField]: nextId('${n.idPrefix}'), ...values } as Partial<${n.type}>); controller.setPage(view.pageCount - 1) }
     else if (id) { await controller.updateRow(id, values) }${submitBody}
     editing = undefined${needsAllRows ? '\n    await loadAll()' : ''}
+  }`);
+    }
+    // Standalone create form: a counter that both blanks the panel (it is the
+    // {#key}) and drives the "Saved" confirmation.
+    if (createForm) {
+        const nav = createForm.afterSave === 'navigate' && createForm.navigateTo
+            ? routeById.get(createForm.navigateTo)
+            : undefined;
+        const after = nav
+            ? `\n    await goto('/${nav}')`
+            : '';
+        parts.push(`let formSaves = $state(0)
+  async function createRecord({ values }: { mode: 'create' | 'edit'; id: string | null; values: Partial<${n.type}> }) {
+    await controller.createRow({ [idField]: nextId('${n.idPrefix}'), ...values } as Partial<${n.type}>)${submitBody}
+    formSaves += 1${after}
   }`);
     }
     // Record panel: the row selected in the grid, plus (when editable) a save hook.
@@ -2685,19 +2734,37 @@ ${hint ? `          {#if !form?.errors?.[${key}]}<small class="sk-hint">${htmlEs
         ? (() => {
             const assigned = new Set();
             const groups = layout.sections.map((s) => {
-                const items = s.fields.map((name) => { assigned.add(name); return blockFor(name); }).filter(Boolean);
-                return { title: s.title, description: s.description, columns: s.columns, items };
+                const names = [];
+                const items = s.fields.map((name) => { assigned.add(name); names.push(name); return blockFor(name); }).filter(Boolean);
+                return { title: s.title, description: s.description, columns: s.columns, collapsible: s.collapsible, collapsed: s.collapsed, names, items };
             }).filter((g) => g.items.length);
             const rest = formFields.filter((f) => !assigned.has(f.field)).map((f) => blockFor(f.field)).filter(Boolean);
-            return rest.length ? [...groups, { title: undefined, description: undefined, columns: undefined, items: rest }] : groups;
+            return rest.length ? [...groups, { title: undefined, description: undefined, columns: undefined, collapsible: false, collapsed: false, names: [], items: rest }] : groups;
         })()
         : null;
     const formCols = layout?.columns ?? 1;
     const fieldsMarkup = ssrSections
         ? ssrSections
-            .map((g) => `        <fieldset class="sk-group" style="--sk-cols: ${g.columns ?? formCols}">
-${g.title ? `          <legend>${htmlEsc(g.title)}</legend>\n` : ''}${g.description ? `          <p class="sk-group__desc">${htmlEsc(g.description)}</p>\n` : ''}${g.items.join('\n')}
-        </fieldset>`)
+            .map((g) => {
+            const inner = `${g.description ? `          <p class="sk-group__desc">${htmlEsc(g.description)}</p>\n` : ''}${g.items.join('\n')}`;
+            // A collapsible group is a native <details>, so it folds with no JS at
+            // all - which is the point on a server-rendered page. A group that
+            // starts folded is forced open when the server sent back an error for
+            // one of its fields, so a rejected submit is never pointing at
+            // something the user cannot see.
+            if (g.collapsible && g.title) {
+                const open = g.collapsed
+                    ? `{${JSON.stringify(g.names)}.some((f) => form?.errors?.[f])}`
+                    : '{true}';
+                return `        <details class="sk-group sk-group--fold" style="--sk-cols: ${g.columns ?? formCols}" open=${open}>
+          <summary>${htmlEsc(g.title)}</summary>
+${inner}
+        </details>`;
+            }
+            return `        <fieldset class="sk-group" style="--sk-cols: ${g.columns ?? formCols}">
+${g.title ? `          <legend>${htmlEsc(g.title)}</legend>\n` : ''}${inner}
+        </fieldset>`;
+        })
             .join('\n')
         : `        <div class="sk-group" style="--sk-cols: ${formCols}">\n${fieldBlocks.join('\n')}\n        </div>`;
     const page = `<script lang="ts">
@@ -2811,6 +2878,13 @@ ${facetCss}  .sk-rowact { display: flex; gap: 10px; }
   .sk-group + .sk-group { margin-top: 14px; padding-top: 14px; border-top: 1px solid var(--sg-border, #e2e8f0); }
   .sk-group legend { grid-column: 1 / -1; padding: 0; font-size: 12px; font-weight: 700; letter-spacing: 0.02em; text-transform: uppercase; color: var(--sg-muted, #64748b); }
   .sk-group__desc { grid-column: 1 / -1; margin: 0; font-size: 12px; color: var(--sg-muted, #64748b); }
+  /* A foldable group is a native <details>, so it works with JavaScript off.
+     display:grid on the element itself would lay the <summary> out as a grid
+     item and break the disclosure, so the grid moves to [open] children. */
+  .sk-group--fold { display: block; }
+  .sk-group--fold > summary { grid-column: 1 / -1; margin-bottom: 12px; font-size: 13.5px; font-weight: 650; color: var(--sg-fg, #0f172a); cursor: pointer; list-style-position: inside; }
+  .sk-group--fold[open] { display: grid; }
+  .sk-group--fold[open] > summary { margin-bottom: 0; }
   .sk-field--wide { grid-column: 1 / -1; }
   .sk-hint { color: var(--sg-muted, #64748b); font-size: 11.5px; }
   @media (max-width: 560px) { .sk-group { grid-template-columns: 1fr; } }

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;