feat(form): SplitForm honours the spec's new FormSection.pane (#3041)

A split form's panel assignment was a hardcoded positional rule — first section
left, everything else right (slice(0,1)/slice(1)). The rule was invisible in the
metadata: nothing in the JSON records the assignment, so reordering sections
silently moved them across the divider, and an author (human or AI) could not
place two sections in the left pane at all.

Sections now declare their panel: `pane: 'primary' | 'secondary'`
(@objectstack/spec FormSection.pane, objectstack#4160). Placement follows the
KEY, not the array position — reordering paned sections never changes the
layout. Omitted keys keep the exact legacy rule (first section primary, rest
secondary), so existing metadata renders unchanged.

ObjectForm's split dispatch copies the key through its per-key section mapping —
the path that once silently dropped `visibleOn` — and ObjectFormSection declares
it (it is the "aligns with spec FormSection" runtime type). The spec side
rejects `pane` on non-split form types at parse, so the key can never be an
accepted-but-ignored no-op.

Tests (verified failing against the unfixed renderer first — 3 red / 9 green):
sections group by declared pane not position (two sections side by side in the
primary pane, previously inexpressible); reversing the section array changes
nothing; ObjectForm forwards the key through its mapping.

No compile-time dependency on the new spec version — the key arrives as plain
JSON — but objectstack#4160 merges first per cross-repo convention.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/splitform-section-pane.md

@@ -0,0 +1,22 @@
+---
+"@object-ui/types": minor
+"@object-ui/plugin-form": minor
+---
+
+feat(form): `SplitForm` honours the spec's new `FormSection.pane`
+
+A split form's panel assignment was a hardcoded positional rule — first section
+left, everything else right. The rule was invisible in the metadata, so
+reordering sections silently moved them across the divider, and an author could
+not place two sections in the left pane at all.
+
+Sections now declare their panel: `pane: 'primary' | 'secondary'`
+(@objectstack/spec `FormSection.pane`, objectstack#4160). Placement follows the
+key, not the array position — reordering paned sections never changes the
+layout. Omitted keys keep the exact legacy rule (first section `primary`, rest
+`secondary`), so existing metadata renders unchanged.
+
+`ObjectForm`'s split dispatch copies the key through its per-key section mapping
+(the path that once silently dropped `visibleOn`), and `ObjectFormSection`
+declares it. The spec side rejects `pane` on non-split form types at parse, so
+the key can never be an accepted-but-ignored no-op.

content/docs/plugins/plugin-form.mdx

@@ -145,8 +145,11 @@ divider.
 - Fields no pane claims render above the panel group rather than disappearing.
 - Needs at least two panes; ignored when the form uses `children` or `fieldTabs`.
 
-`SplitForm` builds on this: section 1 becomes the primary pane, the rest stack in
-the secondary one behind inline section headers.
+`SplitForm` builds on this. Each section declares its panel via `pane: 'primary'
+| 'secondary'` (spec `FormSection.pane`) — explicit placement that survives
+reordering. When omitted, the legacy rule applies: section 1 becomes the primary
+pane, the rest stack in the secondary one behind inline section headers. (The
+spec rejects `pane` on non-split form types at parse.)
 
 ## Usage
 

packages/plugin-form/README.md

@@ -182,8 +182,12 @@ divider.
 - Fields no pane claims render above the panel group rather than disappearing.
 - Needs at least two panes; ignored when the form uses `children` or `fieldTabs`.
 
-`SplitForm` is built on this: section 1 becomes the primary pane, the rest stack
-in the secondary one behind inline section headers.
+`SplitForm` is built on this. Each section declares its panel via `pane:
+'primary' | 'secondary'` (spec `FormSection.pane`) — explicit per-section
+placement, so reordering sections never silently moves them across the divider.
+When omitted, the legacy positional rule applies: the first section becomes the
+primary pane, the rest stack in the secondary one behind inline section headers.
+(The spec rejects `pane` on non-split form types at parse.)
 
 ## Examples
 

packages/plugin-form/src/ObjectForm.tsx

@@ -268,6 +268,10 @@ export const ObjectForm: React.FC<ObjectFormProps> = ({
             description: s.description,
             columns: s.columns,
             fields: s.fields,
+            // Explicit pane placement (spec FormSection.pane). This mapping
+            // rebuilds each section key by key, so a key it doesn't copy is
+            // silently dropped — exactly how `visibleOn` once vanished here.
+            pane: s.pane,
             className: (s as any).className,
             gridClassName: (s as any).gridClassName,
           })),

packages/plugin-form/src/SplitForm.tsx

@@ -10,7 +10,9 @@
  * SplitForm Component
  *
  * A form variant that displays sections in a resizable split-panel layout.
- * The first section renders in the left/top panel, remaining sections in the right/bottom panel.
+ * Each section declares its panel via `pane` (spec FormSection.pane); when
+ * omitted the legacy positional rule applies — the first section renders in the
+ * left/top panel, every other section in the right/bottom one.
  * Aligns with @objectstack/spec FormView type: 'split'
  *
  * Both panels are ONE form (#2153). The panel group is a layout the form
@@ -33,6 +35,13 @@ export interface SplitFormSectionConfig {
   label?: string;
   description?: string;
   columns?: 1 | 2 | 3 | 4;
+  /**
+   * Which panel this section renders in. Aligns with @objectstack/spec
+   * FormSection.pane — explicit per-section placement, so reordering sections
+   * never silently moves them across the divider. Omitted → the legacy
+   * positional rule (first section 'primary', every other 'secondary').
+   */
+  pane?: 'primary' | 'secondary';
   fields: (string | FormField)[];
   /** Custom CSS class for the section's header row. */
   className?: string;
@@ -229,9 +238,23 @@ export const SplitForm: React.FC<SplitFormProps> = ({
     }
   }, [schema]);
 
-  // Split sections: first section in panel 1, rest in panel 2
-  const leftSections = useMemo(() => schema.sections.slice(0, 1), [schema.sections]);
-  const rightSections = useMemo(() => schema.sections.slice(1), [schema.sections]);
+  // Which panel each section renders in: explicit `section.pane` first (spec
+  // FormSection.pane), else the legacy positional rule — first section primary,
+  // rest secondary — so keyless metadata keeps its exact layout. Placement
+  // follows the KEY, not the array position: reordering sections with panes
+  // declared never moves them across the divider.
+  const paneOf = (section: SplitFormSectionConfig, index: number): 'primary' | 'secondary' =>
+    section.pane === 'primary' || section.pane === 'secondary'
+      ? section.pane
+      : index === 0 ? 'primary' : 'secondary';
+  const leftSections = useMemo(
+    () => schema.sections.filter((s, i) => paneOf(s, i) === 'primary'),
+    [schema.sections],
+  );
+  const rightSections = useMemo(
+    () => schema.sections.filter((s, i) => paneOf(s, i) === 'secondary'),
+    [schema.sections],
+  );
 
   const direction = schema.splitDirection || 'horizontal';
   const panelSize = schema.splitSize || 50;

packages/plugin-form/src/sectionedFormValues.test.tsx

@@ -37,6 +37,7 @@ import { registerAllFields } from '@object-ui/fields';
 import { ModalForm } from './ModalForm';
 import { TabbedForm } from './TabbedForm';
 import { SplitForm } from './SplitForm';
+import { ObjectForm } from './ObjectForm';
 
 registerAllFields();
 
@@ -370,6 +371,91 @@ describe('SplitForm — one form across BOTH panels (#2153)', () => {
   });
 });
 
+describe('SplitForm — explicit `section.pane` placement (spec FormSection.pane)', () => {
+  const paneEl = (key: string) =>
+    document.body.querySelector(`[data-testid="form-pane:${key}"]`)!;
+
+  const PANED_SECTIONS = [
+    // Declared order deliberately disagrees with the panes: the SECOND and
+    // THIRD sections are the primary pane. Impossible to express before —
+    // the renderer hardcoded first-section-left / rest-right.
+    { name: 'triage', label: 'Triage', pane: 'secondary' as const, fields: ['status'] },
+    { name: 'basics', label: 'Basics', pane: 'primary' as const, fields: ['subject'] },
+    { name: 'detail', label: 'Detail', pane: 'primary' as const, fields: ['description'] },
+  ];
+
+  it('groups sections by their declared pane, not by array position', async () => {
+    render(
+      <SplitForm
+        schema={{
+          type: 'object-form',
+          formType: 'split',
+          objectName: 'case',
+          mode: 'create',
+          sections: PANED_SECTIONS,
+        }}
+        dataSource={makeDataSource() as any}
+      />,
+    );
+
+    await waitFor(() => expect(document.body.querySelector('form')).toBeTruthy());
+
+    // Two sections side by side in the primary pane…
+    expect(paneEl('primary').querySelector('[data-field="subject"]')).toBeTruthy();
+    expect(paneEl('primary').querySelector('[data-field="description"]')).toBeTruthy();
+    // …and the first-declared section sits in the secondary pane.
+    expect(paneEl('secondary').querySelector('[data-field="status"]')).toBeTruthy();
+    expect(paneEl('secondary').querySelector('[data-field="subject"]')).toBeNull();
+  });
+
+  it('reordering sections does not move them across the divider', async () => {
+    render(
+      <SplitForm
+        schema={{
+          type: 'object-form',
+          formType: 'split',
+          objectName: 'case',
+          mode: 'create',
+          // Same sections, reversed — the hazard the key exists to kill: with
+          // the positional rule this reorder silently relaid the whole form.
+          sections: [...PANED_SECTIONS].reverse(),
+        }}
+        dataSource={makeDataSource() as any}
+      />,
+    );
+
+    await waitFor(() => expect(document.body.querySelector('form')).toBeTruthy());
+
+    expect(paneEl('primary').querySelector('[data-field="subject"]')).toBeTruthy();
+    expect(paneEl('primary').querySelector('[data-field="description"]')).toBeTruthy();
+    expect(paneEl('secondary').querySelector('[data-field="status"]')).toBeTruthy();
+  });
+
+  it('ObjectForm forwards `pane` through its split mapping', async () => {
+    // The dispatch mapping rebuilds sections key by key — a key it does not
+    // copy is silently dropped (how `visibleOn` once vanished). Pin the copy.
+    render(
+      <ObjectForm
+        schema={{
+          type: 'object-form',
+          formType: 'split',
+          objectName: 'case',
+          mode: 'create',
+          sections: [
+            { name: 'triage', label: 'Triage', pane: 'secondary', fields: ['status'] },
+            { name: 'basics', label: 'Basics', pane: 'primary', fields: ['subject'] },
+          ],
+        } as any}
+        dataSource={makeDataSource() as any}
+      />,
+    );
+
+    await waitFor(() => expect(document.body.querySelector('form')).toBeTruthy());
+    expect(paneEl('primary').querySelector('[data-field="subject"]')).toBeTruthy();
+    expect(paneEl('secondary').querySelector('[data-field="status"]')).toBeTruthy();
+  });
+});
+
 describe('TabbedForm — one form for all tabs (#2959)', () => {
   it('submits every tab’s values after the user moves between tabs', async () => {
     const dataSource = makeDataSource();

packages/types/src/objectql.ts

@@ -805,7 +805,17 @@ export interface ObjectFormSection {
    * @default 1
    */
   columns?: 1 | 2 | 3 | 4;
-  
+
+  /**
+   * Which panel of a split form this section renders in. Aligns with
+   * @objectstack/spec FormSection.pane (split forms only — the spec rejects the
+   * key on other form types at parse). Explicit per-section placement, so
+   * reordering sections never silently moves them across the divider.
+   * Omitted → the legacy positional rule: first section 'primary', every
+   * other section 'secondary'.
+   */
+  pane?: 'primary' | 'secondary';
+
   /**
    * Field names or inline field configurations for this section
    */