feat(spec): structured buttons + defaults config on FormViewSchema (#2998)

Track A of #2998: give the renderer-invented flat form keys ObjectUI's
ObjectForm reads today (showSubmit/submitText/showCancel/cancelText/
showReset/initialValues — objectui#2545) a real home in the protocol,
instead of being silently stripped by the strip-mode FormViewSchema
container (the "parsed -> silently inert" shape ADR-0078 prohibits).

- New optional `buttons` block: per-button `{ show, label }` for
  submit/cancel/reset via a new exported FormButtonConfigSchema leaf,
  `.strict()` per ADR-0089 D3a so typo'd keys error loudly.
- New optional `defaults` record: initial field values for create-mode
  forms, keyed by field machine name (absorbs objectui `initialValues`).
- Both marked [EXPERIMENTAL — NOT ENFORCED, #2998] per ADR-0078's escape
  hatch: the framework has no runtime consumer of FormViewSchema, so the
  contract ships ahead of its ObjectUI consumer without a false promise.
  The marker matches the liveness ledger's experimental regex, ready for
  Track B (enrolling `view` in GOVERNED — separate PR per the issue).
- Purely additive (strip-mode container): minor changeset, no tombstone.
- Tests: parse round-trips, strict-leaf rejection of legacy flat keys,
  experimental-marker assertion. api-surface.json regenerated (+2
  exports); ui/view.mdx reference regenerated (scoped hunks only).

Refs ADR-0078, ADR-0089 D3a, objectui#2545, objectui#1763.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Ue47V8zZ5QhcYMPiRQDA7

Author: claude

.changeset/formview-buttons-defaults.md

@@ -0,0 +1,21 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): structured `buttons` + `defaults` config on `FormViewSchema` (#2998)
+
+`FormViewSchema` gains two optional top-level keys — the spec home for the flat
+renderer-invented form config ObjectUI's `ObjectForm` reads today
+(`showSubmit`/`submitText`/`showCancel`/`cancelText`/`showReset`/`initialValues`,
+objectui#2545), which the strip-mode container silently discards:
+
+- **`buttons`** — structured action-button config: per-button `{ show, label }`
+  for `submit` / `cancel` / `reset` (new exported leaf `FormButtonConfigSchema`,
+  `.strict()` per ADR-0089 D3a so typo'd keys error loudly).
+- **`defaults`** — initial field values for create-mode forms, keyed by field
+  machine name (absorbs ObjectUI's `initialValues`).
+
+Both are marked `[EXPERIMENTAL — NOT ENFORCED]` per ADR-0078's escape hatch
+until the ObjectUI renderer reads them (tracked in objectui#2545); authoring
+them today is declared, not yet honored. Purely additive — no existing key
+changes shape, no tombstone needed.

content/docs/references/ui/view.mdx

@@ -16,8 +16,8 @@ Migrated to shared/http.zod.ts. Re-exported here for backward compatibility.
 ## TypeScript Usage
 
 ```typescript
-import { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
-import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
+import { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, FormButtonConfig, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
+import type { AddRecordConfig, AppearanceConfig, CalendarConfig, ColumnSummary, FormButtonConfig, GalleryConfig, GanttConfig, GanttQuickFilter, GroupingConfig, GroupingField, KanbanConfig, ListChartConfig, ListColumn, NavigationConfig, NavigationMode, ObjectUserFilters, PaginationConfig, RowColorConfig, RowHeight, SelectionConfig, TimelineConfig, TreeConfig, UserActionsConfig, UserFilterField, UserFilters, ViewData, ViewFilterRule, ViewItemName, ViewKind, ViewScope, ViewSharing, ViewTab, VisualizationType } from '@objectstack/spec/ui';
 
 // Validate data
 const result = AddRecordConfig.parse(data);
@@ -88,6 +88,18 @@ Aggregation function for column footer summary
 * `max`
 
 
+---
+
+## FormButtonConfig
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **show** | `boolean` | optional | Whether the button is rendered (renderer default applies when omitted) |
+| **label** | `string` | optional | Button label (i18n-capable; renderer default when omitted) |
+
+
 ---
 
 ## GalleryConfig

packages/spec/api-surface.json

@@ -3227,6 +3227,8 @@
     "FocusManagementSchema (const)",
     "FocusTrapConfig (type)",
     "FocusTrapConfigSchema (const)",
+    "FormButtonConfig (type)",
+    "FormButtonConfigSchema (const)",
     "FormField (type)",
     "FormFieldSchema (const)",
     "FormSection (type)",

packages/spec/src/ui/view.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
 import {
   ViewSchema,
   ListViewSchema,
@@ -1931,6 +1932,69 @@ describe('FormViewSchema - defaultSort', () => {
   });
 });
 
+// ============================================================================
+// FormView structured buttons + defaults (#2998, EXPERIMENTAL until objectui#2545)
+// ============================================================================
+
+describe('FormViewSchema - buttons & defaults', () => {
+  it('should accept structured button config with visibility and labels', () => {
+    const result = FormViewSchema.parse({
+      type: 'simple',
+      sections: [{ fields: ['name'] }],
+      buttons: {
+        submit: { show: true, label: 'Save' },
+        cancel: { show: true, label: 'Discard' },
+        reset: { show: false },
+      },
+    });
+    expect(result.buttons?.submit).toEqual({ show: true, label: 'Save' });
+    expect(result.buttons?.reset).toEqual({ show: false });
+  });
+
+  it('should accept a partial buttons block (each button optional)', () => {
+    const result = FormViewSchema.parse({
+      type: 'simple',
+      sections: [{ fields: ['name'] }],
+      buttons: { submit: { label: 'Create' } },
+    });
+    expect(result.buttons?.submit?.label).toBe('Create');
+    expect(result.buttons?.cancel).toBeUndefined();
+  });
+
+  it('should reject unknown keys inside buttons (strict leaf, ADR-0089 D3a)', () => {
+    expect(() => FormViewSchema.parse({
+      type: 'simple',
+      buttons: { submit: { text: 'Save' } }, // legacy `submitText`-style key
+    })).toThrow();
+    expect(() => FormViewSchema.parse({
+      type: 'simple',
+      buttons: { showSubmit: true }, // flat renderer-invented key
+    })).toThrow();
+  });
+
+  it('should accept defaults as a field-name → value record', () => {
+    const result = FormViewSchema.parse({
+      type: 'simple',
+      sections: [{ fields: ['name', 'status', 'priority'] }],
+      defaults: { status: 'open', priority: 3, tags: ['a', 'b'] },
+    });
+    expect(result.defaults).toEqual({ status: 'open', priority: 3, tags: ['a', 'b'] });
+  });
+
+  it('should accept form view without buttons/defaults (optional)', () => {
+    const result = FormViewSchema.parse({ type: 'simple' });
+    expect(result.buttons).toBeUndefined();
+    expect(result.defaults).toBeUndefined();
+  });
+
+  it('marks both keys experimental until the renderer wiring lands (ADR-0078)', () => {
+    const shape = (FormViewSchema as unknown as z.ZodObject<z.ZodRawShape>).shape;
+    for (const key of ['buttons', 'defaults'] as const) {
+      expect(shape[key].description, `${key} .describe()`).toMatch(/EXPERIMENTAL — NOT ENFORCED/);
+    }
+  });
+});
+
 describe('defineView', () => {
   it('should return a parsed view with list config', () => {
     const result = defineView({

packages/spec/src/ui/view.zod.ts

@@ -809,10 +809,21 @@ export const FormSectionSchema = lazySchema(() => z.object({
   ])),
 }, { error: strictVisibilityError }).strict().transform(normalizeVisibleWhen));
 
+/**
+ * A single form action button (submit / cancel / reset): visibility + label.
+ * Leaf of the [EXPERIMENTAL] {@link FormViewSchema} `buttons` block (#2998).
+ * `.strict()` per ADR-0089 D3a so a typo'd key errors instead of vanishing.
+ */
+export const FormButtonConfigSchema = lazySchema(() => z.object({
+  show: z.boolean().optional().describe('Whether the button is rendered (renderer default applies when omitted)'),
+  label: I18nLabelSchema.optional().describe('Button label (i18n-capable; renderer default when omitted)'),
+}).strict());
+export type FormButtonConfig = z.infer<typeof FormButtonConfigSchema>;
+
 /**
  * Form View Schema
  * Defines the layout for creating or editing a single record.
- * 
+ *
  * @example Simple Sectioned Form
  * {
  *   type: "simple",
@@ -924,6 +935,32 @@ export const FormViewSchema = lazySchema(() => z.object({
     z.object({ kind: z.literal('next-record') }),
   ]).optional().describe('Post-submit behavior'),
 
+  /**
+   * ⚠️ EXPERIMENTAL — NOT ENFORCED (#2998, ADR-0078). Structured action-button
+   * config: per-button visibility + label for `submit` / `cancel` / `reset`.
+   * This is the spec home for the flat renderer-invented keys ObjectUI's
+   * `ObjectForm` reads today (`showSubmit`/`submitText`/`showCancel`/`cancelText`/
+   * `showReset`, objectui#2545) — those never existed here and are silently
+   * stripped by this strip-mode container. Experimental until the ObjectUI
+   * renderer reads `buttons.*` (the ADR-0078 escape hatch: the contract ships
+   * ahead of its consumer, marked so authoring it is not a false promise).
+   */
+  buttons: z.object({
+    submit: FormButtonConfigSchema.optional().describe('Submit button'),
+    cancel: FormButtonConfigSchema.optional().describe('Cancel button'),
+    reset: FormButtonConfigSchema.optional().describe('Reset button'),
+  }).strict().optional()
+    .describe('[EXPERIMENTAL — NOT ENFORCED, #2998] Form action-button visibility & labels. Renderer wiring pending in ObjectUI (objectui#2545).'),
+
+  /**
+   * ⚠️ EXPERIMENTAL — NOT ENFORCED (#2998, ADR-0078). Initial field values for
+   * create-mode forms, keyed by field machine name. Spec home for ObjectUI's
+   * renderer-invented `initialValues` (objectui#2545). Experimental until the
+   * ObjectUI renderer reads it.
+   */
+  defaults: z.record(z.string(), z.unknown()).optional()
+    .describe('[EXPERIMENTAL — NOT ENFORCED, #2998] Initial field values for create-mode forms (spec home for ObjectUI `initialValues`). Renderer wiring pending (objectui#2545).'),
+
   /** ARIA accessibility attributes */
   aria: AriaPropsSchema.optional().describe('ARIA accessibility attributes for the form view'),
 }));