feat(components,app-shell): Airtable-style "+ add field" on the data-table column header (#2069)

os-zhuang · claude · web-flow · commit 48f25e1460e0 · 2026-06-29T12:12:00.000+08:00
Adds an opt-in GridFieldAuthoring context to @object-ui/components: the data-table
renders a trailing "+" header cell (and matching body cell) ONLY when a host
provides the context, so every runtime table renders byte-identically. Studio's
Data pillar wraps the object grid in the provider, opening an add-field form
(label + type) that patches the object's `fields`, saves a draft + publishes the
env overlay, busts the data-layer schema cache (adapter.clearCache) and remounts
the grid so the new column appears live.

Note: packaged object schema is `allowOrgOverride: false` by default (objects are
locked — schema changes imply migrations). Adding a field requires the env to
permit object overlays via OS_METADATA_WRITABLE, which a Studio/design environment
enables. When it isn't permitted, the backend's clear "not_overridable" error
surfaces in the form.

Verified live (showcase_account, OS_METADATA_WRITABLE=object): + → form → publish
writes the field to the env overlay (effective fields 16→18), the new column
appears without a reload; non-latin labels slug to field_N.

Co-authored-by: Jack Zhuang &lt;277994282+os-zhuang@users.noreply.github.com&gt;
Co-authored-by: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx b/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx
@@ -16,7 +16,8 @@
 
 import * as React from 'react';
 import { useParams, Link } from 'react-router-dom';
-import { SchemaRenderer } from '@object-ui/react';
+import { SchemaRenderer, useAdapter } from '@object-ui/react';
+import { GridFieldAuthoringProvider } from '@object-ui/components';
 import {
   Boxes,
   FileText,
@@ -587,14 +588,54 @@ function InterfacesPillar({ packageId }: { packageId: string }): React.ReactElem
   );
 }
 
+const NEW_FIELD_TYPES: Array<{ value: string; label: string }> = [
+  { value: 'text', label: '文本' },
+  { value: 'textarea', label: '长文本' },
+  { value: 'number', label: '数字' },
+  { value: 'boolean', label: '勾选' },
+  { value: 'date', label: '日期' },
+  { value: 'datetime', label: '日期时间' },
+];
+
+/** Slugify a label into a safe field name, unique against existing names. */
+function toFieldName(label: string, existing: string[]): string {
+  const base =
+    label
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '_')
+      .replace(/^_+|_+$/g, '') || `field_${existing.length + 1}`;
+  let name = base;
+  let i = 2;
+  while (existing.includes(name)) name = `${base}_${i++}`;
+  return name;
+}
+
+/** Append a field to an object body, honoring keyed-map or array `fields`. */
+function appendField(
+  body: Record<string, unknown>,
+  field: { name: string; type: string; label: string },
+): Record<string, unknown> {
+  const raw = body.fields;
+  if (Array.isArray(raw)) return { ...body, fields: [...raw, field] };
+  return { ...body, fields: { ...((raw as object) ?? {}), [field.name]: field } };
+}
+
 /** Data pillar — the package's objects: list → fields + record grid. */
 function DataPillar({ packageId }: { packageId: string }): React.ReactElement {
   const client = useMetadataClient();
+  const adapter = useAdapter();
   const [objects, setObjects] = React.useState<Surface[]>([]);
   const [current, setCurrent] = React.useState<Surface | null>(null);
   const [obj, setObj] = React.useState<Record<string, unknown> | null>(null);
   const [loading, setLoading] = React.useState(false);
   const [error, setError] = React.useState<string | null>(null);
+  // add-field (Airtable-style "+" on the grid column header)
+  const [addOpen, setAddOpen] = React.useState(false);
+  const [fLabel, setFLabel] = React.useState('');
+  const [fType, setFType] = React.useState('text');
+  const [saving, setSaving] = React.useState(false);
+  const [gridVer, setGridVer] = React.useState(0);
 
   React.useEffect(() => {
     let cancelled = false;
@@ -646,6 +687,34 @@ function DataPillar({ packageId }: { packageId: string }): React.ReactElement {
     return [];
   }, [obj]);
 
+  const doAddField = React.useCallback(async () => {
+    if (!current || !obj || !fLabel.trim()) return;
+    const name = toFieldName(
+      fLabel,
+      fields.map((f) => f.name),
+    );
+    const body = appendField(obj, { name, type: fType, label: fLabel.trim() });
+    setSaving(true);
+    setError(null);
+    try {
+      await client.save('object', current.name, body, { mode: 'draft' });
+      await client.publish('object', current.name);
+      // Bust the data-layer object-schema cache so the remounted grid re-fetches
+      // the new column without a full page reload (the grid reads its columns from
+      // dataSource.getObjectSchema, a separate cache from the metadata client).
+      (adapter as { clearCache?: () => void } | null)?.clearCache?.();
+      setObj(body); // optimistic
+      setGridVer((v) => v + 1);
+      setAddOpen(false);
+      setFLabel('');
+      setFType('text');
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setSaving(false);
+    }
+  }, [adapter, client, current, obj, fLabel, fType, fields]);
+
   return (
     <div className="flex h-full">
       <nav className="w-52 shrink-0 overflow-auto border-r p-2">
@@ -680,13 +749,80 @@ function DataPillar({ packageId }: { packageId: string }): React.ReactElement {
               <span className="text-[11px] text-muted-foreground">{fields.length} 字段</span>
             </div>
             {/* Data mode = the records themselves, as a directly-viewable grid
-              * (Airtable parity). Fields are the columns — no separate table. */}
+              * (Airtable parity). Fields are the columns; the trailing "+" column
+              * header (via GridFieldAuthoringProvider) adds a new field. */}
             <div className="min-h-0 flex-1 overflow-auto rounded-lg border bg-background">
-              <SchemaRenderer schema={{ type: 'object-view', objectName: current.name } as never} />
+              <GridFieldAuthoringProvider
+                value={{ onAddColumn: () => setAddOpen(true), addColumnLabel: '添加字段' }}
+              >
+                <SchemaRenderer
+                  key={`${current.name}:${gridVer}`}
+                  schema={{ type: 'object-view', objectName: current.name } as never}
+                />
+              </GridFieldAuthoringProvider>
             </div>
           </>
         )}
       </main>
+      {addOpen && (
+        <div
+          className="fixed inset-0 z-50 flex items-center justify-center bg-black/30"
+          onClick={() => !saving && setAddOpen(false)}
+        >
+          <div
+            className="w-80 rounded-lg border bg-background p-4 shadow-lg"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <p className="mb-3 text-sm font-medium">添加字段 · {current?.label}</p>
+            {error && (
+              <div className="mb-2 rounded border border-destructive/40 bg-destructive/10 px-2 py-1 text-[11px] text-destructive">
+                {error}
+              </div>
+            )}
+            <label className="mb-1 block text-[11px] text-muted-foreground">字段名称</label>
+            <input
+              autoFocus
+              value={fLabel}
+              onChange={(e) => setFLabel(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' && fLabel.trim() && !saving) doAddField();
+                if (e.key === 'Escape') setAddOpen(false);
+              }}
+              placeholder="例如 备注"
+              className="mb-3 w-full rounded border bg-background px-2 py-1 text-sm outline-none focus:border-primary"
+            />
+            <label className="mb-1 block text-[11px] text-muted-foreground">类型</label>
+            <select
+              value={fType}
+              onChange={(e) => setFType(e.target.value)}
+              className="mb-4 w-full rounded border bg-background px-2 py-1 text-sm outline-none focus:border-primary"
+            >
+              {NEW_FIELD_TYPES.map((ft) => (
+                <option key={ft.value} value={ft.value}>
+                  {ft.label}
+                </option>
+              ))}
+            </select>
+            <div className="flex justify-end gap-2">
+              <button
+                onClick={() => setAddOpen(false)}
+                disabled={saving}
+                className="rounded-md border px-3 py-1 text-xs hover:bg-muted disabled:opacity-50"
+              >
+                取消
+              </button>
+              <button
+                onClick={doAddField}
+                disabled={!fLabel.trim() || saving}
+                className="inline-flex items-center gap-1 rounded-md bg-primary px-3 py-1 text-xs font-medium text-primary-foreground disabled:opacity-50"
+              >
+                {saving ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : null}
+                添加并发布
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
     </div>
   );
 }
diff --git a/packages/components/src/context/gridFieldAuthoring.tsx b/packages/components/src/context/gridFieldAuthoring.tsx
@@ -0,0 +1,51 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * GridFieldAuthoring — an ambient, opt-in affordance that lets a *design*
+ * surface (Studio) add an "+ add field" control to a data-table's column
+ * header without coupling the runtime table renderer to design concerns.
+ *
+ * The data-table reads this context via {@link useGridFieldAuthoring}. With no
+ * provider it returns `null`, so every runtime table renders byte-identically —
+ * the trailing "+" column only appears when a host wraps the table in
+ * {@link GridFieldAuthoringProvider} (e.g. the Studio Data pillar), which owns
+ * the add-field form + metadata save/publish.
+ */
+
+import React from 'react';
+
+export interface GridFieldAuthoring {
+  /** Invoked when the user clicks the trailing "+" add-column header affordance. */
+  onAddColumn: () => void;
+  /** Optional tooltip/aria-label for the add-column button (defaults to "Add field"). */
+  addColumnLabel?: string;
+}
+
+const GridFieldAuthoringContext = React.createContext<GridFieldAuthoring | null>(null);
+
+export function GridFieldAuthoringProvider({
+  value,
+  children,
+}: {
+  value: GridFieldAuthoring | null;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <GridFieldAuthoringContext.Provider value={value}>{children}</GridFieldAuthoringContext.Provider>
+  );
+}
+
+/**
+ * Read the ambient grid field-authoring affordances. Returns `null` outside a
+ * provider — design surfaces opt in by wrapping the table tree in
+ * {@link GridFieldAuthoringProvider}.
+ */
+export function useGridFieldAuthoring(): GridFieldAuthoring | null {
+  return React.useContext(GridFieldAuthoringContext);
+}
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
@@ -44,6 +44,14 @@ export { getLazyIcon, LazyIcon, toKebabIconName } from './lib/lazy-icon';
 // Export placeholder registration
 export { registerPlaceholders } from './renderers/placeholders';
 
+// Export grid field-authoring context — a design surface (Studio) opts into the
+// data-table "+ add field" column header by wrapping the table in the provider.
+export {
+  GridFieldAuthoringProvider,
+  useGridFieldAuthoring,
+  type GridFieldAuthoring,
+} from './context/gridFieldAuthoring';
+
 // Export raw Shadcn UI components
 export * from './ui';
 export * from './custom';
diff --git a/packages/components/src/renderers/complex/data-table.tsx b/packages/components/src/renderers/complex/data-table.tsx
@@ -9,6 +9,7 @@
 // Enterprise-level DataTable Component (Airtable-like)
 import React, { useState, useMemo, useRef, useEffect } from 'react';
 import { cn } from '../../lib/utils';
+import { useGridFieldAuthoring } from '../../context/gridFieldAuthoring';
 import { ComponentRegistry } from '@object-ui/core';
 import type { DataTableSchema } from '@object-ui/types';
 import { useObjectTranslation } from '@object-ui/react';
@@ -231,6 +232,12 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
     disableInnerScroll = false,
   } = schema;
 
+  // Ambient design-surface affordance: when a host (Studio) provides it, render
+  // a trailing "+ add field" column header. `null` for every runtime table, so
+  // existing tables render unchanged.
+  const fieldAuthoring = useGridFieldAuthoring();
+  const addColumnEnabled = !!fieldAuthoring?.onAddColumn;
+
   // i18n support for pagination labels
   const { t, language } = useTableTranslation();
 
@@ -955,13 +962,27 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
               {rowActions && (
                 <TableHead className="w-24 text-right bg-background">{t('common.actions')}</TableHead>
               )}
+              {addColumnEnabled && (
+                <TableHead className="w-10 bg-background px-1 text-center">
+                  <button
+                    type="button"
+                    onClick={fieldAuthoring!.onAddColumn}
+                    title={fieldAuthoring!.addColumnLabel ?? 'Add field'}
+                    aria-label={fieldAuthoring!.addColumnLabel ?? 'Add field'}
+                    data-testid="grid-add-column"
+                    className="inline-flex h-6 w-6 items-center justify-center rounded text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                  >
+                    <Plus className="h-4 w-4" />
+                  </button>
+                </TableHead>
+              )}
             </TableRow>
           </TableHeader>
           <TableBody>
             {paginatedData.length === 0 ? (
               <TableRow className="hover:bg-transparent">
                 <TableCell
-                  colSpan={columns.length + (selectable ? 1 : 0) + (showRowNumbers ? 1 : 0) + (rowActions ? 1 : 0)}
+                  colSpan={columns.length + (selectable ? 1 : 0) + (showRowNumbers ? 1 : 0) + (rowActions ? 1 : 0) + (addColumnEnabled ? 1 : 0)}
                   className="h-48 text-center text-muted-foreground border-0"
                 >
                   <div className="flex flex-col items-center justify-center gap-3">
@@ -1284,6 +1305,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
                           </div>
                         </TableCell>
                       )}
+                      {addColumnEnabled && <TableCell aria-hidden className="w-10" />}
                     </TableRow>
                   );
                 })}
@@ -1295,7 +1317,7 @@ const DataTableRenderer = ({ schema }: { schema: DataTableSchema }) => {
                     onClick={() => schema.onAddRecord?.()}
                   >
                     <TableCell
-                      colSpan={columns.length + (selectable ? 1 : 0) + (showRowNumbers ? 1 : 0) + (rowActions ? 1 : 0)}
+                      colSpan={columns.length + (selectable ? 1 : 0) + (showRowNumbers ? 1 : 0) + (rowActions ? 1 : 0) + (addColumnEnabled ? 1 : 0)}
                       className="h-9 px-3 py-1.5"
                     >
                       <span className="flex items-center gap-1.5 text-muted-foreground text-sm hover:text-foreground transition-colors">
