@svgrid/enterprise 2.6.0 → 2.6.2

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))